makemd/docs/ARCHIVE/00_Business/tasks/backend/16_merchant.md

# 多商户功能收费后端任务

## 任务列表

| Task ID  | 闭环关联      | 任务描述      | 输入         | 输出       | 触发条件 | 状态          | 优先级 | 依赖       | 预计耗时 | 负责人           | 完成时间 |
| -------- | --------- | --------- | ---------- | -------- | ---- | ----------- | --- | -------- | ---- | ------------- | -------- |
| BE-MV001 | 多商户入驻闭环   | 商户注册与认证接口 | 商户信息, 资质文件 | 商户ID, 状态 | 前端提交 | ✅ completed | P1  | -        | 12h  | AI-Backend-12 | 2026-03-20 |
| BE-MV002 | 多商户入驻闭环   | 商户店铺管理    | 商户ID, 店铺信息 | 店铺ID     | 前端提交 | ✅ completed | P1  | BE-MV001 | 10h  | AI-Backend-12 | 2026-03-20 |
| BE-MV003 | 功能模块化闭环   | 功能模块管理    | 模块ID, 配置   | 模块状态     | 系统配置 | ✅ completed | P1  | BE-MV001 | 8h   | AI-Backend-12 | 2026-03-20 |
| BE-MV004 | 功能开通与支付闭环 | 功能开通接口    | 商户ID, 模块ID | 开通记录     | 前端提交 | ✅ completed | P1  | BE-MV003 | 10h  | AI-Backend-12 | 2026-03-20 |
| BE-MV005 | 功能开通与支付闭环 | 功能费用计算    | 商户ID, 使用数据 | 费用明细     | 定时任务 | ✅ completed | P1  | BE-MV004 | 8h   | AI-Backend-12 | 2026-03-20 |
| BE-MV006 | 多商户结算闭环   | 商户结算引擎    | 商户ID, 结算周期 | 结算单      | 定时任务 | ✅ completed | P1  | BE-MV005 | 12h  | AI-Backend-12 | 2026-03-20 |
| BE-MV007 | 多商户订单闭环   | 多商户订单拆分   | 订单ID, 商户列表 | 子订单列表    | 订单创建 | ✅ completed | P1  | BE-MV002 | 10h  | AI-Backend-12 | 2026-03-20 |
| BE-MV008 | 多商户库存闭环   | 多商户库存同步   | 商户ID, 库存数据 | 同步状态     | 库存变化 | ✅ completed | P1  | BE-MV002 | 8h   | AI-Backend-12 | 2026-03-20 |

## 相关闭环

- 多商户入驻闭环
- 功能模块化闭环
- 功能开通与支付闭环
- 多商户结算闭环
- 多商户订单闭环
- 多商户库存闭环

## 依赖关系

```
BE-MV001 ─┬─► BE-MV002 ─┬─► BE-MV007
          │            └─► BE-MV008
          └─► BE-MV003 ─► BE-MV004 ─► BE-MV005 ─► BE-MV006
```

## 数据库表结构

### cf_merchant
| 字段 | 类型 | 说明 |
| ---- | ---- | ---- |
| id | string | 商户ID |
| tenant_id | string | 租户ID |
| name | string | 商户名称 |
| contact_name | string | 联系人姓名 |
| contact_email | string | 联系人邮箱 |
| status | enum | PENDING/ACTIVE/INACTIVE/SUSPENDED |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

### cf_merchant_shop
| 字段 | 类型 | 说明 |
| ---- | ---- | ---- |
| id | string | 店铺ID |
| merchant_id | string | 商户ID |
| name | string | 店铺名称 |
| domain | string | 店铺域名 |
| status | enum | ACTIVE/INACTIVE/MAINTENANCE |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

### cf_feature_module
| 字段 | 类型 | 说明 |
| ---- | ---- | ---- |
| id | string | 模块ID |
| name | string | 模块名称 |
| description | text | 模块描述 |
| price | decimal(10,2) | 模块价格 |
| status | enum | ACTIVE/INACTIVE |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

### cf_merchant_feature
| 字段 | 类型 | 说明 |
| ---- | ---- | ---- |
| id | string | 开通记录ID |
| merchant_id | string | 商户ID |
| module_id | string | 模块ID |
| start_date | datetime | 开始日期 |
| end_date | datetime | 结束日期 |
| status | enum | ACTIVE/EXPIRED/CANCELLED |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

### cf_merchant_settlement
| 字段 | 类型 | 说明 |
| ---- | ---- | ---- |
| id | string | 结算单ID |
| merchant_id | string | 商户ID |
| period_start | datetime | 结算开始日期 |
| period_end | datetime | 结算结束日期 |
| amount | decimal(10,2) | 结算金额 |
| status | enum | PENDING/COMPLETED/FAILED |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

## API端点

### 商户管理API
- `GET /api/merchant/merchants` - 获取商户列表
- `POST /api/merchant/merchants` - 注册商户
- `GET /api/merchant/merchants/:id` - 获取商户详情
- `PUT /api/merchant/merchants/:id` - 更新商户信息
- `GET /api/merchant/shops` - 获取店铺列表
- `POST /api/merchant/shops` - 创建店铺
- `GET /api/merchant/shops/:id` - 获取店铺详情

### 功能管理API
- `GET /api/merchant/modules` - 获取功能模块列表
- `POST /api/merchant/modules` - 创建功能模块
- `GET /api/merchant/modules/:id` - 获取模块详情
- `POST /api/merchant/features/activate` - 开通功能
- `GET /api/merchant/features/:merchantId` - 获取商户已开通功能
- `POST /api/merchant/billing/calculate` - 计算功能费用
- `GET /api/merchant/settlements/:merchantId` - 获取商户结算单

## 验收标准

- [ ] 商户注册与认证接口能正确处理商户注册和认证
- [ ] 商户店铺管理能有效管理商户店铺
- [ ] 功能模块管理能正确管理功能模块
- [ ] 功能开通接口能正确开通功能
- [ ] 功能费用计算能准确计算费用
- [ ] 商户结算引擎能正确生成结算单
- [ ] 多商户订单拆分能正确拆分订单
- [ ] 多商户库存同步能及时同步库存
- [ ] 所有接口响应时间不超过2秒
- [ ] 数据一致性得到保证

## 测试要求

- [ ] 单元测试：覆盖商户管理和功能开通逻辑
- [ ] 集成测试：验证与订单和库存系统的交互
- [ ] 端到端测试：模拟完整的商户管理流程
- [ ] 边界测试：测试异常数据和边界情况

## 风险提示

- **风险点1**：商户资质审核不严格 - 应对措施：建立严格的审核流程和标准
- **风险点2**：功能费用计算错误 - 应对措施：实现多重校验和审计机制
- **风险点3**：结算流程异常 - 应对措施：建立结算异常处理机制和人工审核

## 性能要求

- 响应时间：平均响应时间 < 2秒
- 并发处理：支持200个并发请求
- 数据处理：能处理5000条商户记录/小时

## 安全要求

- 权限控制：只有ADMIN和MERCHANT角色可访问商户数据
- 数据加密：敏感商户信息加密存储
- 审计日志：所有商户操作需记录详细日志
- 输入验证：严格验证所有商户相关输入