feat: 实现账号与佣金管理模块

新增功能： - 店铺佣金查询：店铺佣金统计、店铺佣金记录列表、店铺提现记录 - 佣金提现审批：提现申请列表、审批通过、审批拒绝 - 提现配置管理：配置列表、新增配置、获取当前生效配置 - 企业管理：企业列表、创建、更新、删除、获取详情 - 企业卡授权：授权列表、批量授权、批量取消授权、统计 - 客户账号管理：账号列表、创建、更新状态、重置密码 - 我的佣金：佣金统计、佣金记录、提现申请、提现记录数据库变更： - 扩展 tb_commission_withdrawal_request 新增提现单号等字段 - 扩展 tb_account 新增 is_primary 字段 - 扩展 tb_commission_record 新增 shop_id、balance_after - 扩展 tb_commission_withdrawal_setting 新增每日提现次数限制 - 扩展 tb_iot_card、tb_device 新增 shop_id 冗余字段 - 新建 tb_enterprise_card_authorization 企业卡授权表 - 新建 tb_asset_allocation_record 资产分配记录表 - 数据迁移：owner_type 枚举值 agent 统一为 shop 测试： - 新增 7 个单元测试文件覆盖各服务 - 修复集成测试 Redis 依赖问题
2026-01-21 18:20:44 +08:00
parent 1489abe668
commit 91c9bbfeb8
89 changed files with 11958 additions and 159 deletions
--- a/openspec/changes/archive/2026-01-21-add-commission-model-changes/proposal.md
+++ b/openspec/changes/archive/2026-01-21-add-commission-model-changes/proposal.md
@@ -0,0 +1,180 @@
+# 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` 企业卡授权表
+用于记录企业被授权可见的卡。**这是企业查看卡的唯一途径，不改变卡的归属**。
+
+```sql
+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` 资产分配记录表
+用于记录卡/设备在平台和代理商之间流转的历史。
+
+```sql
+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/` 目录创建数据模型变更说明
--- a/openspec/changes/archive/2026-01-21-add-commission-model-changes/specs/commission-model/spec.md
+++ b/openspec/changes/archive/2026-01-21-add-commission-model-changes/specs/commission-model/spec.md
@@ -0,0 +1,142 @@
+## ADDED Requirements
+
+### Requirement: 佣金提现申请扩展字段
+系统 SHALL 在佣金提现申请表中支持以下扩展字段：
+- 提现单号（`withdrawal_no`）：唯一标识，格式 W + 时间戳 + 随机数
+- 申请人ID（`applicant_id`）：提交申请的账号ID
+- 店铺ID（`shop_id`）：冗余字段，方便查询
+- 手续费比率（`fee_rate`）：申请时的费率快照，基点单位
+- 放款类型（`payment_type`）：如 manual（人工打款）
+- 处理人ID（`processor_id`）：审批/放款人
+- 处理时间（`processed_at`）：审批时间
+- 备注（`remark`）：审批备注
+
+#### Scenario: 创建提现申请时自动生成提现单号
+- **WHEN** 代理商发起提现申请
+- **THEN** 系统自动生成唯一提现单号
+- **AND** 记录申请人ID和店铺ID
+- **AND** 记录当前生效的手续费比率
+
+#### Scenario: 审批提现申请时记录处理信息
+- **WHEN** 管理员审批（通过或拒绝）提现申请
+- **THEN** 系统记录处理人ID和处理时间
+- **AND** 可选记录备注信息
+
+---
+
+### Requirement: 店铺主账号标识
+系统 SHALL 支持标识店铺的主账号，通过 `is_primary` 字段区分。
+
+#### Scenario: 创建店铺时标记主账号
+- **WHEN** 创建店铺时同步创建账号
+- **THEN** 该账号的 `is_primary` 字段设置为 `true`
+
+#### Scenario: 查询店铺主账号
+- **WHEN** 查询代理商列表
+- **THEN** 可以关联查询每个店铺的主账号信息（用户名、手机号）
+
+---
+
+### Requirement: 佣金记录店铺关联
+系统 SHALL 在佣金记录表中支持店铺关联：
+- 店铺ID（`shop_id`）：佣金主要跟着店铺走
+- 入账后余额（`balance_after`）：记录每次入账后的累计余额
+
+#### Scenario: 创建佣金记录时关联店铺
+- **WHEN** 系统创建佣金记录
+- **THEN** 记录对应的店铺ID
+- **AND** 计算并记录入账后的佣金余额
+
+#### Scenario: 按店铺查询佣金明细
+- **WHEN** 查询某店铺的佣金明细
+- **THEN** 可以直接通过 `shop_id` 字段过滤
+
+---
+
+### Requirement: 提现设置每日限制
+系统 SHALL 支持配置每日提现次数限制，通过 `daily_withdrawal_limit` 字段。
+
+#### Scenario: 配置每日提现次数
+- **WHEN** 管理员新增提现设置
+- **THEN** 可以设置每日提现次数限制
+
+#### Scenario: 验证每日提现次数
+- **WHEN** 代理商发起提现申请
+- **THEN** 系统检查今日已提现次数是否超过限制
+
+---
+
+### Requirement: 卡/设备店铺冗余字段
+系统 SHALL 在物联网卡表和设备表中支持店铺ID冗余字段（`shop_id`），方便数据权限过滤。
+
+#### Scenario: 分配卡给代理商时设置 shop_id
+- **WHEN** 将卡从平台分配给代理商
+- **THEN** 设置卡的 `shop_id` 为目标店铺ID
+
+#### Scenario: 代理商查询卡列表时按 shop_id 过滤
+- **WHEN** 代理商用户查询卡列表
+- **THEN** 系统使用 `shop_id` 字段进行数据权限过滤
+
+---
+
+### Requirement: 企业卡授权表
+系统 SHALL 提供企业卡授权表（`tb_enterprise_card_authorization`），记录企业被授权可见的卡。
+
+**核心设计**：
+- 卡的归属（owner）始终是代理商店铺，不会变成企业
+- 企业通过授权表"看到"被授权的卡
+- 授权是永久的，回收时更新 `status=0`
+
+#### Scenario: 授权卡给企业
+- **WHEN** 代理商将卡授权给企业
+- **THEN** 创建授权记录，状态为有效（`status=1`）
+- **AND** 记录授权人和授权时间
+- **AND** 卡的 owner 不变，仍属于代理商
+
+#### Scenario: 回收卡授权
+- **WHEN** 代理商回收企业的卡授权
+- **THEN** 更新授权记录状态为已回收（`status=0`）
+- **AND** 卡的 owner 不变
+
+#### Scenario: 企业查询被授权的卡
+- **WHEN** 企业用户查询卡列表
+- **THEN** 系统通过授权表过滤，只返回被授权且有效的卡
+
+---
+
+### Requirement: 资产分配记录表
+系统 SHALL 提供资产分配记录表（`tb_asset_allocation_record`），记录卡/设备在平台和代理商之间的流转历史。
+
+#### Scenario: 记录卡分配
+- **WHEN** 平台将卡分配给代理商
+- **THEN** 创建分配记录，类型为 `allocate`
+- **AND** 记录来源（平台）和目标（店铺）
+
+#### Scenario: 记录卡回收
+- **WHEN** 从代理商回收卡到平台
+- **THEN** 创建分配记录，类型为 `recall`
+- **AND** 记录来源（店铺）和目标（平台）
+
+#### Scenario: 查询资产流转历史
+- **WHEN** 查询某卡或设备的分配历史
+- **THEN** 返回完整的流转记录列表
+
+---
+
+### Requirement: owner_type 枚举统一
+系统 SHALL 统一卡/设备的 `owner_type` 枚举值：
+- `platform`：平台库存
+- `shop`：代理商持有
+
+**废弃值**：
+- `agent`：改为 `shop`
+- `user`：不再使用
+- `device`：不再使用
+
+#### Scenario: 迁移现有数据
+- **WHEN** 执行数据库迁移
+- **THEN** 将现有 `owner_type='agent'` 的记录更新为 `owner_type='shop'`
+
+#### Scenario: 新数据使用统一枚举
+- **WHEN** 创建或更新卡/设备归属
+- **THEN** `owner_type` 只能是 `platform` 或 `shop`
--- a/openspec/changes/archive/2026-01-21-add-commission-model-changes/tasks.md
+++ b/openspec/changes/archive/2026-01-21-add-commission-model-changes/tasks.md
@@ -0,0 +1,171 @@
+# 实现任务清单
+
+**Change ID**: `add-commission-model-changes`
+
+---
+
+## 阶段 1: 数据库迁移 (1-2 小时)
+
+### Task 1.1: 创建迁移文件
+
+**文件**: `migrations/000010_add_commission_model_changes.up.sql`
+
+**实现内容**:
+- [x] 1.1.1 新增 `tb_commission_withdrawal_request` 表字段
+- [x] 1.1.2 新增 `tb_account.is_primary` 字段
+- [x] 1.1.3 新增 `tb_commission_record` 表字段（`shop_id`, `balance_after`）
+- [x] 1.1.4 新增 `tb_commission_withdrawal_setting.daily_withdrawal_limit` 字段
+- [x] 1.1.5 新增 `tb_iot_card.shop_id` 字段
+- [x] 1.1.6 新增 `tb_device.shop_id` 字段
+- [x] 1.1.7 创建 `tb_enterprise_card_authorization` 表
+- [x] 1.1.8 创建 `tb_asset_allocation_record` 表
+- [x] 1.1.9 创建必要的索引
+
+**验证**:
+- [x] 迁移脚本语法正确
+- [x] 字段类型与需求文档一致
+
+---
+
+### Task 1.2: 数据迁移 - owner_type 枚举统一
+
+**文件**: `migrations/000010_add_commission_model_changes.up.sql`
+
+**实现内容**:
+- [x] 1.2.1 更新 `tb_iot_card` 表 `owner_type='agent'` 为 `owner_type='shop'`
+- [x] 1.2.2 更新 `tb_device` 表 `owner_type='agent'` 为 `owner_type='shop'`
+- [x] 1.2.3 填充 `tb_iot_card.shop_id` 字段（`owner_type='shop'` 时等于 `owner_id`）
+- [x] 1.2.4 填充 `tb_device.shop_id` 字段（`owner_type='shop'` 时等于 `owner_id`）
+
+**验证**:
+- [x] 数据迁移逻辑正确
+- [x] 无数据丢失
+
+---
+
+### Task 1.3: 创建回滚迁移
+
+**文件**: `migrations/000010_add_commission_model_changes.down.sql`
+
+**实现内容**:
+- [x] 1.3.1 删除新增的表字段
+- [x] 1.3.2 删除新增的表
+- [x] 1.3.3 恢复 `owner_type` 枚举值（`shop` → `agent`）
+
+**验证**:
+- [x] 回滚脚本可以正确执行
+- [x] 回滚后数据库状态正确
+
+---
+
+## 阶段 2: Model 更新 (1 小时)
+
+### Task 2.1: 更新现有 Model
+
+**文件**: 
+- `internal/model/financial.go`
+- `internal/model/commission.go`
+- `internal/model/account.go`
+- `internal/model/iot_card.go`
+- `internal/model/device.go`
+
+**实现内容**:
+- [x] 2.1.1 `CommissionWithdrawalRequest` 新增字段
+- [x] 2.1.2 `Account` 新增 `IsPrimary` 字段
+- [x] 2.1.3 `CommissionRecord` 新增 `ShopID`, `BalanceAfter` 字段
+- [x] 2.1.4 `CommissionWithdrawalSetting` 新增 `DailyWithdrawalLimit` 字段
+- [x] 2.1.5 `IotCard` 新增 `ShopID` 字段
+- [x] 2.1.6 `Device` 新增 `ShopID` 字段
+
+**验证**:
+- [x] 字段标签正确（`gorm`, `json`）
+- [x] 字段类型与数据库一致
+
+---
+
+### Task 2.2: 新增 Model
+
+**文件**: 
+- `internal/model/enterprise_card_authorization.go`
+- `internal/model/asset_allocation_record.go`
+
+**实现内容**:
+- [x] 2.2.1 创建 `EnterpriseCardAuthorization` 模型
+- [x] 2.2.2 创建 `AssetAllocationRecord` 模型
+- [x] 2.2.3 实现 `TableName()` 方法
+
+**验证**:
+- [x] 模型定义完整
+- [x] 遵循项目 Model 规范
+
+---
+
+### Task 2.3: 更新常量定义
+
+**文件**: `pkg/constants/iot.go`
+
+**实现内容**:
+- [x] 2.3.1 更新 `OwnerType` 常量（移除 `agent`, `user`, `device`，保留 `platform`, `shop`）
+- [x] 2.3.2 新增 `EnterpriseCardAuthorizationStatus` 常量
+- [x] 2.3.3 新增 `AssetAllocationType` 常量
+- [x] 2.3.4 新增 `PaymentType` 常量
+- [x] 2.3.5 新增 Redis Key 生成函数（如有需要）
+
+**验证**:
+- [x] 常量命名符合规范
+- [x] 中文注释完整
+
+---
+
+## 阶段 3: 代码兼容性修复 (30 分钟)
+
+### Task 3.1: 更新现有代码中的 owner_type 引用
+
+**实现内容**:
+- [x] 3.1.1 全局搜索 `owner_type.*agent` 引用
+- [x] 3.1.2 更新为 `shop`
+- [x] 3.1.3 验证无遗漏
+
+**验证**:
+- [x] 编译通过
+- [x] 无运行时错误
+
+---
+
+## 阶段 4: 验证 (30 分钟)
+
+### Task 4.1: 执行迁移
+
+**实现内容**:
+- [x] 4.1.1 在开发环境执行迁移
+- [x] 4.1.2 验证表结构正确
+- [x] 4.1.3 验证数据迁移正确
+- [x] 4.1.4 验证索引创建正确
+
+**验证**:
+- [x] `migrate up` 成功
+- [x] `migrate down` 可以回滚
+
+---
+
+### Task 4.2: Model 验证
+
+**实现内容**:
+- [x] 4.2.1 验证 Model 与数据库表结构一致
+- [x] 4.2.2 简单 CRUD 测试
+- [x] 4.2.3 验证 GORM 自动迁移无冲突
+
+**验证**:
+- [x] 所有新字段可正常读写
+- [x] 新表 CRUD 正常
+
+---
+
+## 完成标准
+
+- [x] 所有迁移文件创建完成
+- [x] 所有 Model 更新完成
+- [x] 常量定义更新完成
+- [x] 代码兼容性修复完成
+- [x] 迁移执行成功
+- [x] 编译通过，无错误