feat: 实现账号与佣金管理模块
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 4m35s

新增功能:
- 店铺佣金查询:店铺佣金统计、店铺佣金记录列表、店铺提现记录
- 佣金提现审批:提现申请列表、审批通过、审批拒绝
- 提现配置管理:配置列表、新增配置、获取当前生效配置
- 企业管理:企业列表、创建、更新、删除、获取详情
- 企业卡授权:授权列表、批量授权、批量取消授权、统计
- 客户账号管理:账号列表、创建、更新状态、重置密码
- 我的佣金:佣金统计、佣金记录、提现申请、提现记录

数据库变更:
- 扩展 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 依赖问题
This commit is contained in:
2026-01-21 18:20:44 +08:00
parent 1489abe668
commit 91c9bbfeb8
89 changed files with 11958 additions and 159 deletions

View File

@@ -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/` 目录创建数据模型变更说明