junhong_cmp_fiber/openspec/changes/archive/2026-01-21-add-commission-model-changes/proposal.md

Change: 账号与佣金管理模块 - 数据模型变更

Why

账号与佣金管理模块需要扩展现有数据模型以支持以下业务场景：

1. 佣金提现申请需要记录完整的审批流程信息（提现单号、申请人、处理人等）
2. 店铺主账号标识，用于在代理商列表中显示主账号信息
3. 企业客户卡授权机制，允许企业"看到"代理商的卡而不改变归属
4. 卡/设备归属体系统一，简化 owner_type 枚举值

这是账号与佣金管理模块的基础依赖提案，后续所有功能提案都依赖此数据模型变更。

What Changes

1. 表字段新增

1.1 tb_commission_withdrawal_request 佣金提现申请表

字段名	类型	说明
withdrawal_no	varchar(50)	提现单号（唯一，格式：W + 时间戳 + 随机数）
applicant_id	uint	申请人账号ID
shop_id	uint	店铺ID（冗余字段）
fee_rate	int64	手续费比率（基点，100=1%，快照）
payment_type	varchar(20)	放款类型（manual=人工打款）
processor_id	uint	处理人ID
processed_at	timestamp	处理时间
remark	text	备注

1.2 tb_account 账号表

字段名	类型	说明
is_primary	boolean	是否为店铺主账号（默认 false）

1.3 tb_commission_record 佣金记录表

字段名	类型	说明
shop_id	uint	店铺ID（佣金主要跟着店铺走）
balance_after	int64	入账后佣金余额（分）

1.4 tb_commission_withdrawal_setting 提现设置表

字段名	类型	说明
daily_withdrawal_limit	int	每日提现次数限制

1.5 tb_iot_card 物联网卡表

字段名	类型	说明
shop_id	uint	店铺ID（冗余字段，方便查询）

1.6 tb_device 设备表

字段名	类型	说明
shop_id	uint	店铺ID（冗余字段，方便查询）

2. 新增表

2.1 tb_enterprise_card_authorization 企业卡授权表

用于记录企业被授权可见的卡。这是企业查看卡的唯一途径，不改变卡的归属。

CREATE TABLE tb_enterprise_card_authorization (
    id BIGSERIAL PRIMARY KEY,
    enterprise_id BIGINT NOT NULL,
    iot_card_id BIGINT NOT NULL,
    shop_id BIGINT NOT NULL,
    authorized_by BIGINT NOT NULL,
    authorized_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    status INT DEFAULT 1,  -- 1=有效, 0=已回收
    creator BIGINT,
    updater BIGINT,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    deleted_at TIMESTAMP WITH TIME ZONE,
    CONSTRAINT uk_enterprise_card UNIQUE(enterprise_id, iot_card_id)
);

2.2 tb_asset_allocation_record 资产分配记录表

用于记录卡/设备在平台和代理商之间流转的历史。

CREATE TABLE tb_asset_allocation_record (
    id BIGSERIAL PRIMARY KEY,
    allocation_no VARCHAR(50) NOT NULL UNIQUE,
    allocation_type VARCHAR(20) NOT NULL,  -- allocate/recall
    asset_type VARCHAR(20) NOT NULL,       -- iot_card/device
    asset_id BIGINT NOT NULL,
    asset_identifier VARCHAR(50) NOT NULL,
    from_owner_type VARCHAR(20),
    from_owner_id BIGINT,
    to_owner_type VARCHAR(20) NOT NULL,
    to_owner_id BIGINT NOT NULL,
    related_device_id BIGINT,
    related_card_ids JSONB,
    operator_id BIGINT NOT NULL,
    remark TEXT,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    deleted_at TIMESTAMP WITH TIME ZONE
);

3. 枚举值统一

owner_type 字段值变更（tb_iot_card 和 tb_device 表）：

旧值	新值	说明
platform	platform	不变
agent	shop	统一命名
user	废弃	不再使用
device	废弃	不再使用

Impact

影响的规范

• 新增 Capability：commission-model（佣金数据模型）
• 修改 Capability：iot-card（新增 shop_id 字段）
• 修改 Capability：iot-device（新增 shop_id 字段）

影响的代码

迁移文件（新增）：

• migrations/XXXXXX_add_commission_model_changes.up.sql
• migrations/XXXXXX_add_commission_model_changes.down.sql

Model 文件（修改）：

• internal/model/commission.go（新增字段）
• internal/model/account.go（新增 is_primary 字段）
• internal/model/iot_card.go（新增 shop_id 字段）
• internal/model/device.go（新增 shop_id 字段）

Model 文件（新增）：

• internal/model/enterprise_card_authorization.go
• internal/model/asset_allocation_record.go

常量文件（修改）：

• pkg/constants/owner_type.go（统一枚举值）

兼容性

• BREAKING：owner_type 枚举值变更（agent → shop），需要数据迁移
• 数据库迁移需要更新现有数据的 owner_type 值
• 现有代码中引用 agent 的地方需要改为 shop

风险评估

• 中等风险：涉及数据迁移和枚举值变更
• 缓解措施：
  1. 迁移脚本包含数据转换逻辑
  2. 提供回滚脚本
  3. 在测试环境充分验证

Dependencies

• 无外部依赖
• 后续提案依赖此提案：
  • add-shop-commission-query
  • add-commission-withdrawal-approval
  • add-commission-withdrawal-settings
  • add-enterprise-management
  • add-enterprise-card-authorization
  • add-customer-account-management
  • add-my-commission

Testing Strategy

1. 迁移测试：

   • 验证 up 迁移成功执行
   • 验证 down 迁移可以回滚
   • 验证数据转换正确（agent → shop）

2. Model 测试：

   • 新增字段可正常读写
   • 新增表 CRUD 操作正常

Documentation

• 更新 README.md 数据模型说明
• 在 docs/ 目录创建数据模型变更说明