feat: 实现账号与佣金管理模块
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 4m35s
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:
@@ -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/` 目录创建数据模型变更说明
|
||||
Reference in New Issue
Block a user