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,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. **事务测试**:创建企业+账号的原子性
|
||||
@@ -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** 验证当前用户有权限操作该企业
|
||||
@@ -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] 功能测试通过
|
||||
Reference in New Issue
Block a user