xiaoli/peixue-dev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
e5624c2876
peixue-dev/peidu/docs/fixes/2026-01-23-核心支付流程实施/📋数据库设计.md

17 KiB
Raw Blame History

📋 核心支付流程 - 数据库设计

设计日期: 2026-01-23
数据库: peixue (MySQL)

📊 表结构设计

1. 订单表扩展 (order)

需要添加以下字段以支持多种支付方式：

-- 支付方式相关字段
ALTER TABLE `order` ADD COLUMN `payment_method` VARCHAR(50) COMMENT '支付方式：wallet,timecard,package,wechat,mixed' AFTER `payment_status`;
ALTER TABLE `order` ADD COLUMN `wallet_amount` DECIMAL(10,2) DEFAULT 0.00 COMMENT '钱包支付金额';
ALTER TABLE `order` ADD COLUMN `timecard_id` BIGINT COMMENT '使用的次卡ID';
ALTER TABLE `order` ADD COLUMN `package_id` BIGINT COMMENT '使用的套餐ID';
ALTER TABLE `order` ADD COLUMN `coupon_id` BIGINT COMMENT '使用的优惠券ID';
ALTER TABLE `order` ADD COLUMN `coupon_discount` DECIMAL(10,2) DEFAULT 0.00 COMMENT '优惠券折扣金额';
ALTER TABLE `order` ADD COLUMN `service_address_id` BIGINT COMMENT '服务地址ID';

-- 金额相关字段
ALTER TABLE `order` ADD COLUMN `original_amount` DECIMAL(10,2) COMMENT '原价' AFTER `actual_amount`;
ALTER TABLE `order` ADD COLUMN `discount_amount` DECIMAL(10,2) DEFAULT 0.00 COMMENT '总折扣金额';

-- 结算相关字段
ALTER TABLE `order` ADD COLUMN `teacher_income` DECIMAL(10,2) DEFAULT 0.00 COMMENT '陪伴员收益';
ALTER TABLE `order` ADD COLUMN `manager_commission` DECIMAL(10,2) DEFAULT 0.00 COMMENT '管理师提成';
ALTER TABLE `order` ADD COLUMN `platform_income` DECIMAL(10,2) DEFAULT 0.00 COMMENT '平台收益';
ALTER TABLE `order` ADD COLUMN `settlement_status` TINYINT DEFAULT 0 COMMENT '结算状态：0-未结算，1-已结算';
ALTER TABLE `order` ADD COLUMN `settlement_time` DATETIME COMMENT '结算时间';

-- 添加索引
ALTER TABLE `order` ADD INDEX `idx_timecard_id` (`timecard_id`);
ALTER TABLE `order` ADD INDEX `idx_package_id` (`package_id`);
ALTER TABLE `order` ADD INDEX `idx_coupon_id` (`coupon_id`);
ALTER TABLE `order` ADD INDEX `idx_service_address_id` (`service_address_id`);
ALTER TABLE `order` ADD INDEX `idx_settlement_status` (`settlement_status`);

2. 钱包表 (wallet)

检查是否存在，如不存在则创建：

CREATE TABLE IF NOT EXISTS `wallet` (
  `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `user_id` BIGINT NOT NULL COMMENT '用户ID',
  `balance` DECIMAL(10,2) NOT NULL DEFAULT 0.00 COMMENT '余额',
  `frozen_amount` DECIMAL(10,2) NOT NULL DEFAULT 0.00 COMMENT '冻结金额',
  `total_recharge` DECIMAL(10,2) NOT NULL DEFAULT 0.00 COMMENT '累计充值',
  `total_consume` DECIMAL(10,2) NOT NULL DEFAULT 0.00 COMMENT '累计消费',
  `total_withdraw` DECIMAL(10,2) NOT NULL DEFAULT 0.00 COMMENT '累计提现',
  `version` INT NOT NULL DEFAULT 0 COMMENT '乐观锁版本号',
  `tenant_id` BIGINT COMMENT '租户ID',
  `created_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `updated_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  `deleted` TINYINT DEFAULT 0 COMMENT '删除标记',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_user_id` (`user_id`),
  KEY `idx_tenant_id` (`tenant_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='钱包表';

3. 钱包交易记录表 (wallet_transaction)

CREATE TABLE IF NOT EXISTS `wallet_transaction` (
  `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `user_id` BIGINT NOT NULL COMMENT '用户ID',
  `wallet_id` BIGINT NOT NULL COMMENT '钱包ID',
  `order_id` BIGINT COMMENT '关联订单ID',
  `transaction_type` VARCHAR(50) NOT NULL COMMENT '交易类型：recharge-充值，consume-消费，refund-退款，withdraw-提现，income-收益',
  `amount` DECIMAL(10,2) NOT NULL COMMENT '交易金额',
  `balance_before` DECIMAL(10,2) NOT NULL COMMENT '交易前余额',
  `balance_after` DECIMAL(10,2) NOT NULL COMMENT '交易后余额',
  `transaction_no` VARCHAR(100) COMMENT '交易流水号',
  `payment_channel` VARCHAR(50) COMMENT '支付渠道：wechat,alipay',
  `status` TINYINT DEFAULT 1 COMMENT '状态：0-失败，1-成功，2-处理中',
  `remark` VARCHAR(500) COMMENT '备注',
  `tenant_id` BIGINT COMMENT '租户ID',
  `created_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `updated_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  `deleted` TINYINT DEFAULT 0 COMMENT '删除标记',
  PRIMARY KEY (`id`),
  KEY `idx_user_id` (`user_id`),
  KEY `idx_wallet_id` (`wallet_id`),
  KEY `idx_order_id` (`order_id`),
  KEY `idx_transaction_no` (`transaction_no`),
  KEY `idx_created_time` (`created_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='钱包交易记录表';

4. 次卡表扩展 (time_card)

检查并添加必要字段：

-- 检查表是否存在
-- 如果存在，添加缺失字段

ALTER TABLE `time_card` ADD COLUMN IF NOT EXISTS `total_times` INT NOT NULL DEFAULT 0 COMMENT '总次数';
ALTER TABLE `time_card` ADD COLUMN IF NOT EXISTS `used_times` INT NOT NULL DEFAULT 0 COMMENT '已使用次数';
ALTER TABLE `time_card` ADD COLUMN IF NOT EXISTS `remaining_times` INT NOT NULL DEFAULT 0 COMMENT '剩余次数';
ALTER TABLE `time_card` ADD COLUMN IF NOT EXISTS `expire_date` DATE COMMENT '过期日期';
ALTER TABLE `time_card` ADD COLUMN IF NOT EXISTS `status` TINYINT DEFAULT 1 COMMENT '状态：0-已过期，1-使用中，2-已用完';
ALTER TABLE `time_card` ADD COLUMN IF NOT EXISTS `version` INT NOT NULL DEFAULT 0 COMMENT '乐观锁版本号';

-- 添加索引
ALTER TABLE `time_card` ADD INDEX IF NOT EXISTS `idx_user_id` (`user_id`);
ALTER TABLE `time_card` ADD INDEX IF NOT EXISTS `idx_status` (`status`);
ALTER TABLE `time_card` ADD INDEX IF NOT EXISTS `idx_expire_date` (`expire_date`);

5. 次卡使用记录表 (time_card_usage)

CREATE TABLE IF NOT EXISTS `time_card_usage` (
  `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `user_id` BIGINT NOT NULL COMMENT '用户ID',
  `timecard_id` BIGINT NOT NULL COMMENT '次卡ID',
  `order_id` BIGINT NOT NULL COMMENT '订单ID',
  `used_times` INT NOT NULL DEFAULT 1 COMMENT '使用次数',
  `remaining_times` INT NOT NULL COMMENT '剩余次数',
  `remark` VARCHAR(500) COMMENT '备注',
  `tenant_id` BIGINT COMMENT '租户ID',
  `created_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `updated_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  `deleted` TINYINT DEFAULT 0 COMMENT '删除标记',
  PRIMARY KEY (`id`),
  KEY `idx_user_id` (`user_id`),
  KEY `idx_timecard_id` (`timecard_id`),
  KEY `idx_order_id` (`order_id`),
  KEY `idx_created_time` (`created_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='次卡使用记录表';

6. 套餐表扩展 (package)

检查并添加必要字段：

ALTER TABLE `package` ADD COLUMN IF NOT EXISTS `total_hours` DECIMAL(10,2) NOT NULL DEFAULT 0 COMMENT '总课时';
ALTER TABLE `package` ADD COLUMN IF NOT EXISTS `used_hours` DECIMAL(10,2) NOT NULL DEFAULT 0 COMMENT '已使用课时';
ALTER TABLE `package` ADD COLUMN IF NOT EXISTS `remaining_hours` DECIMAL(10,2) NOT NULL DEFAULT 0 COMMENT '剩余课时';
ALTER TABLE `package` ADD COLUMN IF NOT EXISTS `expire_date` DATE COMMENT '过期日期';
ALTER TABLE `package` ADD COLUMN IF NOT EXISTS `status` TINYINT DEFAULT 1 COMMENT '状态：0-已过期，1-使用中，2-已用完';
ALTER TABLE `package` ADD COLUMN IF NOT EXISTS `version` INT NOT NULL DEFAULT 0 COMMENT '乐观锁版本号';

-- 添加索引
ALTER TABLE `package` ADD INDEX IF NOT EXISTS `idx_user_id` (`user_id`);
ALTER TABLE `package` ADD INDEX IF NOT EXISTS `idx_status` (`status`);
ALTER TABLE `package` ADD INDEX IF NOT EXISTS `idx_expire_date` (`expire_date`);

7. 套餐使用记录表 (package_usage)

已存在，检查字段是否完整：

-- 检查 package_usage 表结构
-- 确保包含以下字段：
-- id, user_id, package_id, order_id, used_hours, remaining_hours, remark, created_time, updated_time, deleted

8. 优惠券表 (coupon)

检查表结构：

CREATE TABLE IF NOT EXISTS `coupon` (
  `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `name` VARCHAR(100) NOT NULL COMMENT '优惠券名称',
  `type` TINYINT NOT NULL COMMENT '类型：1-满减券，2-折扣券，3-代金券',
  `discount_type` TINYINT NOT NULL COMMENT '折扣类型：1-金额，2-折扣',
  `discount_value` DECIMAL(10,2) NOT NULL COMMENT '折扣值（金额或折扣率）',
  `min_amount` DECIMAL(10,2) DEFAULT 0.00 COMMENT '最低消费金额',
  `max_discount` DECIMAL(10,2) COMMENT '最大折扣金额',
  `total_quantity` INT NOT NULL COMMENT '发行总量',
  `received_quantity` INT DEFAULT 0 COMMENT '已领取数量',
  `used_quantity` INT DEFAULT 0 COMMENT '已使用数量',
  `start_time` DATETIME NOT NULL COMMENT '开始时间',
  `end_time` DATETIME NOT NULL COMMENT '结束时间',
  `status` TINYINT DEFAULT 1 COMMENT '状态：0-停用，1-启用',
  `tenant_id` BIGINT COMMENT '租户ID',
  `created_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `updated_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  `deleted` TINYINT DEFAULT 0 COMMENT '删除标记',
  PRIMARY KEY (`id`),
  KEY `idx_status` (`status`),
  KEY `idx_start_end_time` (`start_time`, `end_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='优惠券表';

9. 用户优惠券表 (user_coupon)

CREATE TABLE IF NOT EXISTS `user_coupon` (
  `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `user_id` BIGINT NOT NULL COMMENT '用户ID',
  `coupon_id` BIGINT NOT NULL COMMENT '优惠券ID',
  `order_id` BIGINT COMMENT '使用的订单ID',
  `status` TINYINT DEFAULT 0 COMMENT '状态：0-未使用，1-已使用，2-已过期',
  `receive_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '领取时间',
  `use_time` DATETIME COMMENT '使用时间',
  `expire_time` DATETIME NOT NULL COMMENT '过期时间',
  `tenant_id` BIGINT COMMENT '租户ID',
  `created_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `updated_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  `deleted` TINYINT DEFAULT 0 COMMENT '删除标记',
  PRIMARY KEY (`id`),
  KEY `idx_user_id` (`user_id`),
  KEY `idx_coupon_id` (`coupon_id`),
  KEY `idx_order_id` (`order_id`),
  KEY `idx_status` (`status`),
  KEY `idx_expire_time` (`expire_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户优惠券表';

10. 用户地址表 (user_address)

检查表结构：

CREATE TABLE IF NOT EXISTS `user_address` (
  `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `user_id` BIGINT NOT NULL COMMENT '用户ID',
  `contact_name` VARCHAR(50) NOT NULL COMMENT '联系人姓名',
  `contact_phone` VARCHAR(20) NOT NULL COMMENT '联系电话',
  `province` VARCHAR(50) COMMENT '省份',
  `city` VARCHAR(50) COMMENT '城市',
  `district` VARCHAR(50) COMMENT '区县',
  `address` VARCHAR(200) NOT NULL COMMENT '详细地址',
  `address_tag` VARCHAR(20) COMMENT '地址标签：家，公司，学校',
  `longitude` DECIMAL(10,6) COMMENT '经度',
  `latitude` DECIMAL(10,6) COMMENT '纬度',
  `is_default` TINYINT DEFAULT 0 COMMENT '是否默认地址：0-否，1-是',
  `tenant_id` BIGINT COMMENT '租户ID',
  `created_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `updated_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  `deleted` TINYINT DEFAULT 0 COMMENT '删除标记',
  PRIMARY KEY (`id`),
  KEY `idx_user_id` (`user_id`),
  KEY `idx_is_default` (`is_default`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户地址表';

11. 陪伴员收益表 (teacher_salary)

检查并扩展字段：

ALTER TABLE `teacher_salary` ADD COLUMN IF NOT EXISTS `order_id` BIGINT COMMENT '订单ID';
ALTER TABLE `teacher_salary` ADD COLUMN IF NOT EXISTS `settlement_type` VARCHAR(50) DEFAULT 'order' COMMENT '结算类型：order-订单结算，manual-手动结算';
ALTER TABLE `teacher_salary` ADD COLUMN IF NOT EXISTS `income_ratio` DECIMAL(5,2) DEFAULT 70.00 COMMENT '收益比例（%）';

-- 添加索引
ALTER TABLE `teacher_salary` ADD INDEX IF NOT EXISTS `idx_order_id` (`order_id`);
ALTER TABLE `teacher_salary` ADD INDEX IF NOT EXISTS `idx_settlement_type` (`settlement_type`);

12. 管理师提成表 (manager_commission) - 新建

CREATE TABLE IF NOT EXISTS `manager_commission` (
  `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `manager_id` BIGINT NOT NULL COMMENT '管理师ID',
  `order_id` BIGINT NOT NULL COMMENT '订单ID',
  `order_amount` DECIMAL(10,2) NOT NULL COMMENT '订单金额',
  `commission_ratio` DECIMAL(5,2) NOT NULL DEFAULT 10.00 COMMENT '提成比例（%）',
  `commission_amount` DECIMAL(10,2) NOT NULL COMMENT '提成金额',
  `status` TINYINT DEFAULT 0 COMMENT '状态：0-未结算，1-已结算',
  `settlement_time` DATETIME COMMENT '结算时间',
  `remark` VARCHAR(500) COMMENT '备注',
  `tenant_id` BIGINT COMMENT '租户ID',
  `created_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `updated_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  `deleted` TINYINT DEFAULT 0 COMMENT '删除标记',
  PRIMARY KEY (`id`),
  KEY `idx_manager_id` (`manager_id`),
  KEY `idx_order_id` (`order_id`),
  KEY `idx_status` (`status`),
  KEY `idx_created_time` (`created_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='管理师提成表';

📋 SQL 执行脚本

将创建一个完整的 SQL 脚本文件：payment_system_database.sql

该脚本将包含：

  1. 所有表的创建语句（IF NOT EXISTS）
  2. 所有字段的添加语句（ADD COLUMN IF NOT EXISTS）
  3. 所有索引的创建语句
  4. 数据完整性检查

🔍 数据完整性约束

外键关系（逻辑外键，不使用物理外键）

order.timecard_id → time_card.id
order.package_id → package.id
order.coupon_id → user_coupon.id
order.service_address_id → user_address.id

wallet_transaction.wallet_id → wallet.id
wallet_transaction.order_id → order.id

time_card_usage.timecard_id → time_card.id
time_card_usage.order_id → order.id

package_usage.package_id → package.id
package_usage.order_id → order.id

user_coupon.coupon_id → coupon.id
user_coupon.order_id → order.id

teacher_salary.order_id → order.id
manager_commission.order_id → order.id

数据一致性规则

  1. 钱包余额一致性

    wallet.balance = wallet.total_recharge - wallet.total_consume - wallet.total_withdraw

  2. 次卡次数一致性

    time_card.remaining_times = time_card.total_times - time_card.used_times

  3. 套餐课时一致性

    package.remaining_hours = package.total_hours - package.used_hours

  4. 订单金额一致性

    order.actual_amount = order.original_amount - order.discount_amount
order.discount_amount = order.coupon_discount

  5. 收益分配一致性

    order.actual_amount = order.teacher_income + order.manager_commission + order.platform_income

🔐 乐观锁字段

以下表使用乐观锁防止并发问题：

  • wallet.version - 钱包余额更新
  • time_card.version - 次卡次数更新
  • package.version - 套餐课时更新

更新示例：

UPDATE wallet 
SET balance = balance - ?, version = version + 1 
WHERE id = ? AND version = ?

📊 索引优化

查询优化索引

  1. 订单查询优化

    • idx_user_id - 按用户查询订单
    • idx_payment_status - 按支付状态查询
    • idx_settlement_status - 按结算状态查询

  2. 钱包交易查询优化

    • idx_user_id - 按用户查询交易记录
    • idx_created_time - 按时间查询交易记录
    • idx_transaction_no - 按流水号查询

  3. 优惠券查询优化

    • idx_user_id + idx_status - 查询用户可用优惠券
    • idx_expire_time - 查询即将过期的优惠券

🧪 数据验证查询

1. 检查钱包余额一致性

SELECT 
    w.id,
    w.user_id,
    w.balance,
    w.total_recharge,
    w.total_consume,
    w.total_withdraw,
    (w.total_recharge - w.total_consume - w.total_withdraw) AS calculated_balance,
    (w.balance - (w.total_recharge - w.total_consume - w.total_withdraw)) AS difference
FROM wallet w
WHERE w.balance != (w.total_recharge - w.total_consume - w.total_withdraw);

2. 检查次卡次数一致性

SELECT 
    tc.id,
    tc.user_id,
    tc.total_times,
    tc.used_times,
    tc.remaining_times,
    (tc.total_times - tc.used_times) AS calculated_remaining,
    (tc.remaining_times - (tc.total_times - tc.used_times)) AS difference
FROM time_card tc
WHERE tc.remaining_times != (tc.total_times - tc.used_times);

3. 检查套餐课时一致性

SELECT 
    p.id,
    p.user_id,
    p.total_hours,
    p.used_hours,
    p.remaining_hours,
    (p.total_hours - p.used_hours) AS calculated_remaining,
    (p.remaining_hours - (p.total_hours - p.used_hours)) AS difference
FROM package p
WHERE p.remaining_hours != (p.total_hours - p.used_hours);

📝 下一步

  1. 执行 SQL 脚本创建/更新表结构
  2. 验证数据完整性
  3. 开始后端接口实现

文档版本: v1.0
最后更新: 2026-01-23