<?php
/**
 * 数据库模型：订阅实例记录（基础表结构与 CRUD）。
 *
 * 使用场景与业务说明：
 * - 产品层面的订阅计划（周期、价格、折扣等）存放在 WooCommerce 的 postmeta 中；
 * - 本数据表用于保存“用户的实际订阅实例”，包括开始时间、下一次续费时间、数量、每周期应付金额、状态等；
 * - 后续可以基于此表实现：自动续费（根据 next_renewal_date 触发）、冻结/暂停、取消、续订记录审计、对账等；
 * - 当前阶段仅提供表结构和读写 API，不在前端自动创建订阅实例，便于之后逐步接入。
 *
 * 表结构字段含义（yoone_subscriptions）：
 * - id：主键，自增；
 * - user_id：订阅所属的用户（WP 用户 ID）；
 * - product_id：关联的商品 ID（通常为具有订阅属性的产品）；
 * - period：订阅周期，目前支持 'month'（月）与 'year'（年）；
 * - qty：订阅的数量（例如包月数量、份数等），默认为 1；
 * - price_per_cycle：每个周期需要支付的金额（DECIMAL(18,8)），保留 8 位小数以兼容各种币种与税费；
 * - status：订阅当前状态，示例：active（活跃）、paused（暂停）、canceled（已取消）等；
 * - start_date：订阅开始时间（DATETIME）；
 * - next_renewal_date：下一次续费时间（DATETIME，可空），由定时任务或业务逻辑维护；
 * - created_at / updated_at：记录创建与最后更新时间戳；
 * 索引：
 * - KEY user_id：便于按用户查询其订阅列表；
 * - KEY product_id：便于按商品维度统计与筛选；
 * - KEY status：便于按状态快速过滤（例如批量续费仅处理 active）。
 */

defined('ABSPATH') || exit;

class Yoone_Subscriptions_DB {
    const TABLE = 'yoone_subscriptions'; // 实际表名为 {$wpdb->prefix}yoone_subscriptions

    protected static $instance = null;

    public static function instance() {
        if (null === self::$instance) self::$instance = new self();
        return self::$instance;
    }

    private function __construct() {}

    /**
     * 返回完整表名（含前缀）。
     */
    public static function table_name() {
        global $wpdb;
        return $wpdb->prefix . self::TABLE;
    }

    /**
     * 安装/升级表结构。
     *
     * 业务要点：
     * - 使用 dbDelta 执行 CREATE TABLE，当表结构有变更时可自动比对并调整；
     * - 使用 $wpdb->prefix 保证与站点前缀一致，避免与其他站点冲突；
     * - 使用 get_charset_collate() 为表设置正确字符集与排序规则；
     * - 字段设计保守，满足通用订阅场景，后续可通过迁移增加更多业务字段（如上次扣费结果、失败次数等）。
     */
    public static function install() {
        global $wpdb;
        $table = self::table_name();
        $charset_collate = $wpdb->has_cap( 'collation' ) ? $wpdb->get_charset_collate() : '';

        require_once ABSPATH . 'wp-admin/includes/upgrade.php';

        // 说明：下方 SQL 为完整表结构定义，字段含义见文件头部注释。
        $sql = "CREATE TABLE {$table} (
            id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT,
            user_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 0,
            product_id BIGINT(20) UNSIGNED NOT NULL DEFAULT 0,
            period VARCHAR(10) NOT NULL DEFAULT 'month',
            qty INT(11) UNSIGNED NOT NULL DEFAULT 1,
            price_per_cycle DECIMAL(18,8) NOT NULL DEFAULT 0.00000000,
            status VARCHAR(20) NOT NULL DEFAULT 'active',
            start_date DATETIME NOT NULL,
            next_renewal_date DATETIME NULL,
            created_at DATETIME NOT NULL,
            updated_at DATETIME NOT NULL,
            PRIMARY KEY  (id),
            KEY user_id (user_id),
            KEY product_id (product_id),
            KEY status (status)
        ) {$charset_collate};";

        dbDelta($sql);
    }

    /**
     * 创建订阅实例。
     *
     * 参数与校验规则：
     * - user_id / product_id：转为非负整数（absint），缺省为 0；
     * - period：仅允许 'month' 或 'year'，否则回落到 'month'；
     * - qty：数量最小为 1；
     * - price_per_cycle：每周期金额，使用 floatval；
     * - status：使用 sanitize_key 过滤，建议统一枚举：active / paused / canceled 等；
     * - start_date / next_renewal_date：字符串形式的 DATETIME，使用 sanitize_text_field；
     * - created_at / updated_at：由系统自动填充当前时间；
     * 返回值：插入成功返回插入的自增 ID，失败返回 false。
     *
     * 业务提示：
     * - 该方法不做业务级冲突检测（例如同用户同产品是否已存在 active 实例），留给上层业务处理；
     * - 可在创建后根据 period 自动计算 next_renewal_date（例如 +1 month/+1 year）。
     */
    public static function create($data) {
        global $wpdb;
        $table = self::table_name();
        $now = current_time('mysql');

        $defaults = array(
            'user_id' => 0,
            'product_id' => 0,
            'period' => 'month',
            'qty' => 1,
            'price_per_cycle' => 0.0,
            'status' => 'active',
            'start_date' => $now,
            'next_renewal_date' => null,
            'created_at' => $now,
            'updated_at' => $now,
        );
        $data = wp_parse_args($data, $defaults);

        // 执行插入，构造字段与格式数组以确保类型安全
        $inserted = $wpdb->insert(
            $table,
            array(
                'user_id' => absint($data['user_id']),
                'product_id' => absint($data['product_id']),
                'period' => in_array($data['period'], array('month','year'), true) ? $data['period'] : 'month',
                'qty' => max(1, intval($data['qty'])),
                'price_per_cycle' => floatval($data['price_per_cycle']),
                'status' => sanitize_key($data['status']),
                'start_date' => sanitize_text_field($data['start_date']),
                'next_renewal_date' => $data['next_renewal_date'] ? sanitize_text_field($data['next_renewal_date']) : null,
                'created_at' => $now,
                'updated_at' => $now,
            ),
            array('%d','%d','%s','%d','%f','%s','%s','%s','%s','%s')
        );

        if (false === $inserted) return false;
        return $wpdb->insert_id;
    }

    /**
     * 更新订阅实例（部分字段更新）。
     *
     * 使用说明：
     * - 仅允许更新允许字段（allowed 列表），其他键会被忽略；
     * - 自动刷新 updated_at 为当前时间；
     * - 根据不同字段类型设置对应的 SQL 格式（%d/%f/%s），保证类型安全；
     * - 返回布尔，true 表示更新成功（wpdb->update 返回非 false）。
     */
    public static function update($id, $data) {
        global $wpdb;
        $table = self::table_name();
        $id = absint($id);
        if ($id <= 0) return false;

        $data['updated_at'] = current_time('mysql');

        // 过滤并构造格式：仅采纳白名单字段
        $fields = array();
        $formats = array();
        $allowed = array('user_id','product_id','period','qty','price_per_cycle','status','start_date','next_renewal_date','updated_at');
        foreach ($allowed as $key) {
            if (! array_key_exists($key, $data)) continue;
            $val = $data[$key];
            switch ($key) {
                case 'user_id':
                case 'product_id':
                    $fields[$key] = absint($val); $formats[] = '%d'; break;
                case 'qty':
                    $fields[$key] = max(1, intval($val)); $formats[] = '%d'; break;
                case 'price_per_cycle':
                    $fields[$key] = floatval($val); $formats[] = '%f'; break;
                case 'period':
                    $fields[$key] = in_array($val, array('month','year'), true) ? $val : 'month'; $formats[] = '%s'; break;
                case 'status':
                    $fields[$key] = sanitize_key($val); $formats[] = '%s'; break;
                case 'start_date':
                case 'next_renewal_date':
                case 'updated_at':
                    $fields[$key] = sanitize_text_field($val); $formats[] = '%s'; break;
            }
        }

        if (empty($fields)) return false; // 无有效更新字段时直接返回
        return $wpdb->update($table, $fields, array('id' => $id), $formats, array('%d')) !== false;
    }

    /**
     * 获取单个订阅实例。
     *
     * @param int $id 订阅实例主键 ID
     * @return array|null 关联数组（字段同表结构），找不到返回 null
     */
    public static function get($id) {
        global $wpdb;
        $table = self::table_name();
        $id = absint($id);
        return $wpdb->get_row($wpdb->prepare("SELECT * FROM {$table} WHERE id = %d", $id), ARRAY_A);
    }

    /**
     * 获取某用户的订阅实例列表。
     *
     * 过滤参数：
     * - status：按状态过滤（active/paused/canceled 等），为空则不限制；
     * - product_id：按商品过滤，0 或空则不限制；
     * - limit / offset：分页参数，默认 limit=50, offset=0；
     * 返回值：二维数组，每项为一条订阅实例记录（关联数组）。
     */
    public static function get_by_user($user_id, $args = array()) {
        global $wpdb;
        $table = self::table_name();
        $user_id = absint($user_id);
        $defaults = array('status' => '', 'product_id' => 0, 'limit' => 50, 'offset' => 0);
        $args = wp_parse_args($args, $defaults);

        $where = array('user_id = %d');
        $params = array($user_id);

        if (! empty($args['status'])) { $where[] = 'status = %s'; $params[] = sanitize_key($args['status']); }
        if (! empty($args['product_id'])) { $where[] = 'product_id = %d'; $params[] = absint($args['product_id']); }

        $limit = max(1, absint($args['limit']));
        $offset = max(0, absint($args['offset']));

        // 组装分页查询语句，按 id 倒序排列，便于查看最新实例
        $sql = "SELECT * FROM {$table} WHERE " . implode(' AND ', $where) . " ORDER BY id DESC LIMIT %d OFFSET %d";
        $params[] = $limit;
        $params[] = $offset;

        return $wpdb->get_results($wpdb->prepare($sql, $params), ARRAY_A);
    }
}