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,72 @@
# Change: 企业客户管理模块基础CRUD
## Why
平台和代理商需要管理企业客户:
1. 新增企业客户,同时自动创建企业账号
2. 查询企业客户列表
3. 编辑企业信息
4. 启用/禁用企业(同步禁用账号)
5. 重置企业账号密码
这是账号管理-企业客户管理模块的基础功能。
## What Changes
### 新增 API 接口
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/admin/enterprises` | 新增企业(含自动创建账号) |
| GET | `/api/admin/enterprises` | 企业列表 |
| PUT | `/api/admin/enterprises/:id` | 编辑企业 |
| PUT | `/api/admin/enterprises/:id/status` | 启用/禁用 |
| PUT | `/api/admin/enterprises/:id/password` | 修改密码 |
### 技术实现
- 新增 Handler`internal/handler/admin/enterprise.go`
- 新增 Service`internal/service/enterprise/service.go`
- 新增 DTO`internal/model/dto/enterprise_dto.go`
- 扩展 Store`internal/store/postgres/enterprise_store.go`
### 业务逻辑
**新增企业**
1. 验证企业编号唯一性
2. 验证 `login_phone` 在账号表中不存在
3. 如果指定 `owner_shop_id`,验证店铺存在且有权限
4. 开启事务:
- 创建企业记录
- 创建企业账号UserType=4, EnterpriseID=企业ID
5. 提交事务
**禁用企业**
1. 更新企业状态
2. 同步禁用企业关联的账号
## Impact
### 影响的规范
- **新增 Capability**`enterprise-management`
### 影响的代码
**新增文件**(约 400 行):
- `internal/handler/admin/enterprise.go`~120 行)
- `internal/service/enterprise/service.go`~200 行)
- `internal/model/dto/enterprise_dto.go`~80 行)
### 兼容性
- ✅ 向后兼容:新增 API不影响现有功能
## Dependencies
- 依赖提案:`add-commission-model-changes`
- 依赖现有模型:`Enterprise``Account``Shop`
## Testing Strategy
1. **单元测试**:企业创建逻辑、状态同步逻辑
2. **集成测试**:完整 CRUD 流程
3. **事务测试**:创建企业+账号的原子性

View File

@@ -0,0 +1,142 @@
## ADDED Requirements
### Requirement: 新增企业客户
系统 SHALL 提供新增企业客户的接口,同时自动创建企业账号。
**接口**`POST /api/admin/enterprises`
**请求参数**
- `owner_shop_id`归属代理商ID可选不填为平台自营
- `enterprise_name`:企业名称(必填)
- `enterprise_code`:企业编号(必填,唯一)
- `legal_person`:法人代表
- `contact_name`:联系人姓名(必填)
- `contact_phone`:联系人电话(必填)
- `login_phone`:登录手机号(必填,作为企业账号)
- `password`:登录密码(必填)
- `business_license`:营业执照号
- `province``city``district``address`:地址信息
**响应字段**
- 企业信息enterprise
- 账号信息account
#### Scenario: 创建企业并自动创建账号
- **WHEN** 创建企业客户
- **THEN** 创建企业记录
- **AND** 自动创建企业账号UserType=4, EnterpriseID=企业ID
- **AND** 使用事务确保原子性
#### Scenario: 企业编号唯一性校验
- **WHEN** 创建企业时企业编号已存在
- **THEN** 返回错误:企业编号已存在
#### Scenario: 登录手机号唯一性校验
- **WHEN** 创建企业时登录手机号已被其他账号使用
- **THEN** 返回错误:手机号已被使用
#### Scenario: 指定归属店铺
- **WHEN** 指定 `owner_shop_id`
- **THEN** 验证店铺存在且当前用户有权限
- **AND** 设置企业归属该店铺
---
### Requirement: 查询企业客户列表
系统 SHALL 提供查询企业客户列表的接口。
**接口**`GET /api/admin/enterprises`
**请求参数**
- `page``page_size`:分页
- `enterprise_name`:企业名称(模糊查询)
- `login_phone`:登录手机号(模糊查询)
- `contact_phone`:联系人电话(模糊查询)
- `owner_shop_id`归属代理商ID
- `status`状态0=禁用, 1=启用)
**响应字段**
- 企业信息id, enterprise_name, enterprise_code, contact_name, contact_phone
- 归属信息owner_shop_id, owner_shop_name
- 账号信息login_phone
- 状态信息status, status_name
- 地址信息province, city, district, address
#### Scenario: 平台用户查看所有企业
- **WHEN** 平台用户请求企业列表
- **THEN** 返回所有企业
#### Scenario: 代理商用户查看归属企业
- **WHEN** 代理商用户请求企业列表
- **THEN** 只返回 `owner_shop_id` 在自己+下级店铺范围内的企业
#### Scenario: 关联查询登录手机号
- **WHEN** 返回企业列表
- **THEN** 通过关联账号表获取 `login_phone`
---
### Requirement: 编辑企业信息
系统 SHALL 提供编辑企业信息的接口。
**接口**`PUT /api/admin/enterprises/:id`
**请求参数**
- `id`企业ID路径参数
- 可编辑字段owner_shop_id, enterprise_name, enterprise_code, legal_person, contact_name, contact_phone, business_license, 地址信息
**注意**:修改联系人电话不影响账号的登录手机号。
#### Scenario: 编辑企业基本信息
- **WHEN** 编辑企业信息
- **THEN** 更新企业记录
- **AND** 不影响关联账号
#### Scenario: 修改企业编号时校验唯一性
- **WHEN** 修改企业编号
- **THEN** 验证新编号不与其他企业冲突
#### Scenario: 修改归属店铺
- **WHEN** 修改 `owner_shop_id`
- **THEN** 验证目标店铺存在且当前用户有权限
---
### Requirement: 启用/禁用企业
系统 SHALL 提供启用或禁用企业的接口,同步影响企业账号。
**接口**`PUT /api/admin/enterprises/:id/status`
**请求参数**
- `id`企业ID路径参数
- `status`状态0=禁用, 1=启用)
#### Scenario: 禁用企业
- **WHEN** 禁用企业
- **THEN** 更新企业状态为禁用
- **AND** 同步禁用企业关联的账号
#### Scenario: 启用企业
- **WHEN** 启用企业
- **THEN** 更新企业状态为启用
- **AND** 同步启用企业关联的账号
---
### Requirement: 修改企业账号密码
系统 SHALL 提供修改企业账号密码的接口。
**接口**`PUT /api/admin/enterprises/:id/password`
**请求参数**
- `id`企业ID路径参数
- `password`:新密码(必填)
#### Scenario: 重置企业账号密码
- **WHEN** 修改企业账号密码
- **THEN** 查找企业关联的账号
- **AND** 更新账号密码bcrypt加密
#### Scenario: 权限校验
- **WHEN** 修改密码
- **THEN** 验证当前用户有权限操作该企业

View File

@@ -0,0 +1,119 @@
# 实现任务清单
**Change ID**: `add-enterprise-management`
---
## 阶段 1: DTO 定义 (30 分钟)
### Task 1.1: 创建 DTO 文件
**文件**: `internal/model/enterprise_dto.go`
**实现内容**:
- [x] 1.1.1 `CreateEnterpriseReq` 请求结构(企业信息 + 登录信息)
- [x] 1.1.2 `UpdateEnterpriseReq` 编辑请求
- [x] 1.1.3 `EnterpriseListReq` 列表查询请求
- [x] 1.1.4 `EnterpriseItem` 响应结构
- [x] 1.1.5 `UpdateEnterpriseStatusReq` 状态更新请求
- [x] 1.1.6 `UpdateEnterprisePasswordReq` 密码更新请求
**验证**:
- [x] 验证标签正确
- [x] 字段完整
---
## 阶段 2: Store 层 (45 分钟)
### Task 2.1: 创建/扩展 Enterprise Store
**文件**: `internal/store/postgres/enterprise_store.go`
**实现内容**:
- [x] 2.1.1 `Create(enterprise)` - 创建企业
- [x] 2.1.2 `Update(enterprise)` - 更新企业
- [x] 2.1.3 `GetByID(id)` - 获取单条记录
- [x] 2.1.4 `List(req)` - 分页查询
- [x] 2.1.5 `ExistsByCode(code)` - 检查编号是否存在GetByCode
- [x] 2.1.6 `UpdateStatus(id, status)` - 更新状态在Service层通过事务实现
**验证**:
- [x] 数据权限过滤正确
- [x] 关联查询正确(归属店铺、账号)
---
## 阶段 3: Service 层 (1.5 小时)
### Task 3.1: 创建 Enterprise Service
**文件**: `internal/service/enterprise/service.go`
**实现内容**:
- [x] 3.1.1 `Create(ctx, req)` - 新增企业(含创建账号)
- [x] 3.1.2 `Update(ctx, id, req)` - 编辑企业
- [x] 3.1.3 `List(ctx, req)` - 查询企业列表
- [x] 3.1.4 `UpdateStatus(ctx, id, status)` - 更新状态(同步账号)
- [x] 3.1.5 `UpdatePassword(ctx, id, password)` - 修改密码
**业务逻辑**:
- [x] 3.1.6 创建企业时的事务处理
- [x] 3.1.7 禁用企业时同步禁用账号
- [x] 3.1.8 权限校验
**验证**:
- [x] 事务正确
- [x] 状态同步正确
---
## 阶段 4: Handler 层 (1 小时)
### Task 4.1: 创建 Handler
**文件**: `internal/handler/admin/enterprise.go`
**实现内容**:
- [x] 4.1.1 `CreateEnterprise` - POST /api/admin/enterprises
- [x] 4.1.2 `ListEnterprises` - GET /api/admin/enterprises
- [x] 4.1.3 `UpdateEnterprise` - PUT /api/admin/enterprises/:id
- [x] 4.1.4 `UpdateEnterpriseStatus` - PUT /api/admin/enterprises/:id/status
- [x] 4.1.5 `UpdateEnterprisePassword` - PUT /api/admin/enterprises/:id/password
**验证**:
- [x] 参数校验正确
- [x] 响应格式正确
---
### Task 4.2: 路由注册
**实现内容**:
- [x] 4.2.1 注册五个 API 路由
---
## 阶段 5: 测试 (1 小时)
### Task 5.1: 功能测试
**实现内容**:
- [x] 5.1.1 创建企业测试(含账号创建)
- [x] 5.1.2 编辑企业测试
- [x] 5.1.3 禁用企业测试(验证账号同步禁用)
- [x] 5.1.4 密码修改测试
- [x] 5.1.5 数据权限测试
---
## 完成标准
- [x] 所有 DTO 定义完成
- [x] Store 层方法实现完成
- [x] Service 层业务逻辑完成
- [x] Handler 层 API 实现完成
- [x] 创建企业时账号同步创建
- [x] 禁用企业时账号同步禁用
- [x] 编译通过
- [x] 功能测试通过