huang
91c9bbfeb8
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 依赖问题
181 lines
5.9 KiB
Markdown
181 lines
5.9 KiB
Markdown
# 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/` 目录创建数据模型变更说明
|