# 阶段一：基础设施与用户体系 — 详细任务清单

> 工期：3-4周（15-20天）
> 目标：管理员能录入数据，用户能登录并看到有价值的信息
> 功能点：20个
> 流程：M1(需求) → M2(架构) → M3(编码) → M4(测试)

---

## 里程碑总览

```
Week 1-2              Week 2-3              Week 3-4
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│ M1 需求分析      │  │ M3 编码实现      │  │ M3 编码(续)+自检 │
│ M2 架构设计      │  │ (核心模块)       │  │ M4 测试验收      │
│ (可并行)         │  │                 │  │                 │
└─────────────────┘  └─────────────────┘  └─────────────────┘
  5-7天                  7-8天                  5-7天
```

---

## M1 Team A — 需求分析（3-4天）

### 交付产物

| 序号 | 文件路径 | 说明 |
|------|----------|------|
| 1 | deliveries/team-a-requirement/spec.md | 阶段一需求规格 |
| 2 | deliveries/team-a-requirement/use-cases.md | 用例文档 |
| 3 | deliveries/team-a-requirement/constraints.md | 约束条件 |
| 4 | deliveries/team-a-requirement/DELIVERY-MANIFEST.md | 交付清单 |

### 任务分解

| 任务 | 内容 | 耗时 |
|------|------|------|
| M1.1 | 基于 requirements-specification.md 提取阶段一的20个功能点详细需求 | 1天 |
| M1.2 | 编写用例文档（每个功能点至少1个主用例+异常用例） | 1天 |
| M1.3 | 编写约束条件（技术约束、安全约束、适老化约束） | 0.5天 |
| M1.4 | 编写 DELIVERY-MANIFEST.md（含给下游关键信息） | 0.5天 |

### M1 用例覆盖清单

| 功能模块 | 用例数 | 核心用例 |
|---------|--------|---------|
| 数据库建表 | 2 | 全量建表成功、索引创建验证 |
| 角色管理 | 3 | 创建角色、绑定权限、角色列表 |
| 账号管理 | 4 | 创建账号、分配角色、启用/禁用、列表查询 |
| 字典管理 | 4 | 品种/工种/农资/行政区划 CRUD |
| 操作日志 | 2 | 日志记录、日志查询 |
| Excel 模板下载 | 1 | 下载4类模板 |
| Excel 上传+预览 | 4 | 上传、预览有效行、预览错误行、预览重复行 |
| 数据校验+去重 | 3 | 手机号校验、去重检测、跳过/覆盖选择 |
| 确认入库 | 3 | 同步入库(≤100行)、异步入库(>100行)、完成通知 |
| 审核框架 | 3 | 审核列表、通过操作、驳回+原因 |
| 导入数据审核 | 2 | 待审数据展示、审核后生效 |
| 行情配置 | 3 | 设置价格区间、设置趋势、行情列表 |
| 微信登录 | 3 | 登录成功、拒绝授权兜底、Token 签发 |
| 身份路由 | 3 | 0个身份提示、1个直接进入、N个选择页 |
| 身份选择页 | 2 | 大卡片展示、点击进入 |
| 今日行情 | 2 | 涨价展示、降价展示 |
| 金刚区 | 2 | 4入口展示、灰态入口 |
| 手机号加密 | 2 | 加密存储验证、phone_hash 查询 |
| 权限框架 | 3 | 小程序拦截器、后台拦截器、越权拦截 |
| 接口脱敏 | 2 | 手机号脱敏、姓名脱敏 |

### M1 验收标准
- [ ] spec.md 覆盖20个功能点，每个有独立章节
- [ ] use-cases.md 用例数 ≥ 45（覆盖所有功能的正常+异常场景）
- [ ] constraints.md 包含技术约束、安全约束、适老化约束
- [ ] DELIVERY-MANIFEST.md 的"给下游团队的关键信息"完整

---

## M2 Team B — 架构设计（3-4天）

### 交付产物

| 序号 | 文件路径 | 说明 |
|------|----------|------|
| 1 | deliveries/team-b-architecture/design.md | 架构设计文档 |
| 2 | deliveries/team-b-architecture/api-definition.md | 接口定义 |
| 3 | deliveries/team-b-architecture/tech-stack.md | 技术选型说明 |
| 4 | deliveries/team-b-architecture/DELIVERY-MANIFEST.md | 交付清单 |

### 任务分解

| 任务 | 内容 | 耗时 |
|------|------|------|
| M2.1 | 模块架构设计（分层架构：Controller→Service→Mapper） | 0.5天 |
| M2.2 | 数据库详细设计（字段类型、索引、注释） | 0.5天 |
| M2.3 | 接口定义（RESTful API，请求/响应格式） | 1天 |
| M2.4 | 安全架构设计（加密方案、拦截器链、脱敏策略） | 0.5天 |
| M2.5 | 技术选型说明 | 0.5天 |
| M2.6 | DELIVERY-MANIFEST.md | 0.5天 |

### M2 接口清单（阶段一）

#### 认证模块
| 接口 | 方法 | 模块 | 说明 |
|------|------|------|------|
| /api/wx/auth/login | POST | gateway-mobile | 微信登录 |
| /api/wx/auth/identity-list | GET | gateway-mobile | 获取身份列表 |
| /api/admin/auth/login | POST | gateway-management | 后台登录 |

#### 系统管理模块
| 接口 | 方法 | 模块 | 说明 |
|------|------|------|------|
| /api/admin/roles | GET/POST | service-system | 角色列表/创建 |
| /api/admin/roles/{id} | PUT/DELETE | service-system | 角色编辑/删除 |
| /api/admin/users | GET/POST | service-system | 账号列表/创建 |
| /api/admin/users/{id} | PUT | service-system | 账号编辑 |
| /api/admin/dicts | GET/POST | service-system | 字典列表/创建 |
| /api/admin/dicts/{id} | PUT/DELETE | service-system | 字典编辑/删除 |
| /api/admin/logs | GET | service-system | 操作日志查询 |

#### 数据导入模块
| 接口 | 方法 | 模块 | 说明 |
|------|------|------|------|
| /api/admin/import/template/{type} | GET | service-system | 下载模板 |
| /api/admin/import/upload | POST | service-system | 上传 Excel |
| /api/admin/import/preview | POST | service-system | 预览导入数据 |
| /api/admin/import/confirm | POST | service-system | 确认入库 |

#### 审核模块
| 接口 | 方法 | 模块 | 说明 |
|------|------|------|------|
| /api/admin/audit/list | GET | service-audit | 审核列表 |
| /api/admin/audit/{id} | PUT | service-audit | 审核操作（通过/驳回） |

#### 行情模块
| 接口 | 方法 | 模块 | 说明 |
|------|------|------|------|
| /api/admin/market-price | GET/POST | service-trade | 行情列表/配置 |
| /api/admin/market-price/{id} | PUT/DELETE | service-trade | 行情编辑/删除 |
| /api/wx/market-price | GET | gateway-mobile | 今日行情（小程序端） |

#### 小程序首页
| 接口 | 方法 | 模块 | 说明 |
|------|------|------|------|
| /api/wx/home/market-price | GET | gateway-mobile | 首页行情数据 |
| /api/wx/home/entries | GET | gateway-mobile | 金刚区入口配置 |

### M2 验收标准
- [ ] api-definition.md 接口数 ≥ 20（覆盖所有功能点）
- [ ] DDL 每张表有字段注释
- [ ] design.md 包含模块架构图、安全架构图
- [ ] tech-stack.md 列出所有依赖及版本
- [ ] DELIVERY-MANIFEST.md 的"给下游团队的关键信息"完整

---

## M3 Team C — 编码实现（10-12天）

### 模块拆分与并行策略

```
并行组1（基础层，无依赖）:
├── C-Common: service-common 共享库
├── C-DB: 全量建表 SQL + MyBatis XML
└── C-Security: 加密/脱敏/拦截器基础框架

并行组2（业务层，依赖并行组1）:
├── C-System: 系统管理（角色/账号/字典/日志）
├── C-Import: 数据导入（上传/预览/校验/入库）
└── C-Audit: 审核框架

并行组3（展示层，依赖并行组2）:
├── C-Trade: 行情管理
├── C-Auth: 微信登录+身份路由
└── C-Home: 小程序首页

串行（集成层）:
└── C-Gateway: 网关配置+拦截器注册
```

### 任务详细分解

#### C-Common: service-common 共享库（1天）

| 任务 | 文件 | 说明 |
|------|------|------|
| C-Common.1 | ApiResult.java | 统一响应体 |
| C-Common.2 | PageResult.java | 分页响应体 |
| C-Common.3 | BaseEntity.java | 基础实体（id, created_at, updated_at） |
| C-Common.4 | BizException.java | 业务异常类 |
| C-Common.5 | ErrorCode.java | 错误码枚举 |
| C-Common.6 | PageUtil.java | 分页工具 |
| C-Common.7 | AesUtil.java | AES 加密工具 |
| C-Common.8 | PhoneUtil.java | 手机号脱敏工具 |
| C-Common.9 | JwtUtil.java | JWT 工具 |

#### C-DB: 数据库（1天）

| 任务 | 文件 | 说明 |
|------|------|------|
| C-DB.1 | schema.sql | 全量建表 SQL（15张表+索引） |
| C-DB.2 | data.sql | 初始数据（字典+管理员） |
| C-DB.3 | SysUserMapper.xml | 用户表 MyBatis 映射 |
| C-DB.4 | UserIdentityMapper.xml | 身份表映射 |
| C-DB.5 | MarketPriceMapper.xml | 行情表映射 |
| C-DB.6 | AuditLogMapper.xml | 审核日志映射 |
| C-DB.7 | OperationLogMapper.xml | 操作日志映射 |
| C-DB.8 | 其他 Mapper.xml | 剩余表的映射（空表预建） |

#### C-Security: 安全基础设施（2天）

| 任务 | 文件 | 模块 | 说明 |
|------|------|------|------|
| C-Sec.1 | WxAuthInterceptor.java | gateway-mobile | 微信 JWT 拦截器 |
| C-Sec.2 | AdminAuthInterceptor.java | gateway-management | 后台 JWT 拦截器 |
| C-Sec.3 | PermissionInterceptor.java | gateway-* | RBAC 权限拦截器 |
| C-Sec.4 | DataMaskingInterceptor.java | gateway-* | 数据脱敏拦截器 |
| C-Sec.5 | WebMvcConfig.java | gateway-* | 拦截器注册配置 |
| C-Sec.6 | SecurityConfig.java | service-common | 安全配置常量 |

#### C-System: 系统管理（2天）

| 任务 | 文件 | 说明 |
|------|------|------|
| C-Sys.1 | SysRoleController.java | 角色管理 API |
| C-Sys.2 | SysRoleService.java | 角色业务逻辑 |
| C-Sys.3 | SysUserController.java | 账号管理 API |
| C-Sys.4 | SysUserService.java | 账号业务逻辑 |
| C-Sys.5 | DictController.java | 字典管理 API |
| C-Sys.6 | DictService.java | 字典业务逻辑 |
| C-Sys.7 | OperationLogService.java | 操作日志记录 |
| C-Sys.8 | OperationLogAspect.java | 日志切面（AOP） |

#### C-Import: 数据导入（2天）

| 任务 | 文件 | 说明 |
|------|------|------|
| C-Imp.1 | ImportController.java | 导入 API（上传/预览/确认） |
| C-Imp.2 | ExcelParseService.java | Excel 解析（Apache POI） |
| C-Imp.3 | ImportValidateService.java | 数据校验（手机号/必填项） |
| C-Imp.4 | ImportDedupService.java | 去重逻辑（手机号+身份） |
| C-Imp.5 | ImportExecuteService.java | 入库执行（同步/异步） |
| C-Imp.6 | ImportTemplateService.java | 模板下载 |
| C-Imp.7 | FieldMappingConfig.java | 字段映射配置（硬编码4种模板） |

#### C-Audit: 审核框架（1天）

| 任务 | 文件 | 说明 |
|------|------|------|
| C-Aud.1 | AuditController.java | 审核 API（列表/通过/驳回） |
| C-Aud.2 | AuditService.java | 审核业务逻辑 |
| C-Aud.3 | AuditLogService.java | 审核日志记录 |
| C-Aud.4 | SlaReminderTask.java | SLA 提醒定时任务（24h/48h） |

#### C-Trade: 行情管理（0.5天）

| 任务 | 文件 | 说明 |
|------|------|------|
| C-Trade.1 | MarketPriceController.java | 行情 CRUD API（后台） |
| C-Trade.2 | MarketPriceService.java | 行情业务逻辑 |
| C-Trade.3 | WxMarketPriceController.java | 行情查询 API（小程序端） |

#### C-Auth: 微信登录（1.5天）

| 任务 | 文件 | 说明 |
|------|------|------|
| C-Auth.1 | WxAuthController.java | 登录 API（code→JWT） |
| C-Auth.2 | WxAuthService.java | 登录业务逻辑 |
| C-Auth.3 | IdentityService.java | 身份查询+路由逻辑 |
| C-Auth.4 | WxApiService.java | 微信 API 调用（code2session） |

#### C-Home: 小程序首页（0.5天）

| 任务 | 文件 | 说明 |
|------|------|------|
| C-Home.1 | HomeController.java | 首页 API（行情+金刚区） |
| C-Home.2 | HomeService.java | 首页数据聚合 |

#### C-Gateway: 网关配置（0.5天）

| 任务 | 文件 | 说明 |
|------|------|------|
| C-Gw.1 | GatewayMobileConfig.java | 移动端网关路由配置 |
| C-Gw.2 | GatewayManagementConfig.java | 管理端网关路由配置 |
| C-Gw.3 | application.properties | 完整配置（DB/Redis/OSS/短信/JWT） |

### 编译自检（Team C 执行）

```bash
# 依赖链编译
cd com.fenzhitech.crrc.service-common && ./gradlew compileJava
cd com.fenzhitech.crrc.service-system && ./gradlew compileJava
cd com.fenzhitech.crrc.service-audit && ./gradlew compileJava
cd com.fenzhitech.crrc.service-trade && ./gradlew compileJava
cd com.fenzhitech.crrc.gateway-mobile && ./gradlew compileJava
cd com.fenzhitech.crrc.gateway-management && ./gradlew compileJava
```

### M3 验收标准
- [ ] DELIVERY-MANIFEST.md 注明编译自检结果（零错误）
- [ ] 每个 Controller 方法对应 api-definition.md 中一个接口
- [ ] MyBatis XML 全部使用 `#{}` 语法（无 `${}`）
- [ ] 手机号存储为 AES 密文
- [ ] 接口返回手机号脱敏
- [ ] 操作日志 AOP 切面正常记录

---

## M4 Team D — 测试验收（5-7天）

### 交付产物

| 序号 | 文件路径 | 说明 |
|------|----------|------|
| 1 | deliveries/team-d-testing/test-cases.md | 测试用例 |
| 2 | deliveries/team-d-testing/test-report.md | 测试报告 |
| 3 | deliveries/team-d-testing/bug-list.md | Bug 清单 |
| 4 | deliveries/team-d-testing/DELIVERY-MANIFEST.md | 交付清单 |
| 5 | {module}/src/test/java/ | 自动化测试代码 |

### 测试重点（业务领导指定）

#### 核心接口（必须测试）
- /api/admin/auth/login — 后台登录
- /api/wx/auth/login — 微信登录
- /api/admin/import/upload — Excel 上传
- /api/admin/import/preview — 导入预览
- /api/admin/import/confirm — 确认入库
- /api/admin/audit/{id} — 审核操作
- /api/wx/market-price — 今日行情

#### 重点场景
| 场景 | 说明 |
|------|------|
| 登录成功/失败 | 微信登录正常流程、拒绝授权兜底 |
| 身份路由 | 0/1/N个身份的路由逻辑 |
| Excel 导入 | 空行/格式错误/重复/超大文件 |
| 预览准确性 | 有效行/错误行/重复行计数正确 |
| 审核操作 | 通过/驳回、SLA 提醒触发 |
| 权限隔离 | 不同角色访问隔离、越权拦截 |
| 手机号安全 | 加密存储验证、接口脱敏验证 |

### 任务分解

| 任务 | 内容 | 耗时 |
|------|------|------|
| M4.1 | 编写测试用例（≥45个，覆盖所有用例） | 1.5天 |
| M4.2 | 编写自动化测试代码（JUnit 4 + Spring Boot Test） | 2天 |
| M4.3 | 执行手动验证（核心接口冒烟） | 0.5天 |
| M4.4 | 运行 ./gradlew test 确认全部通过 | 0.5天 |
| M4.5 | 编写 test-report.md 和 bug-list.md | 0.5天 |
| M4.6 | Bug 修复（如有） | 1-2天 |

### M4 验收标准
- [ ] 测试用例数 ≥ 45
- [ ] 核心接口测试覆盖 ≥ 80%
- [ ] `./gradlew test` 全部通过
- [ ] 测试代码未修改 src/main/java/ 下的文件
- [ ] Bug 清单含复现步骤+严重等级
- [ ] test-report.md 记录完整测试结果

---

## 阶段一风险与缓解

| 风险 | 影响 | 概率 | 缓解措施 |
|------|------|------|----------|
| 20个功能点工期不足 | 延期1-2周 | 高 | 优先完成登录+导入+行情，审核框架可延到阶段2a初 |
| Excel 导入格式多样性 | 字段映射不全 | 中 | MVP 硬编码覆盖4种标准模板 |
| 微信手机号授权拒绝 | 用户无法注册 | 中 | 后台手动绑定兜底 |
| Spring Boot 1.5.9 兼容性 | SDK 版本冲突 | 低 | 阶段零已验证 |
| 安全框架与业务逻辑耦合 | 代码复杂度高 | 中 | 拦截器独立模块，AOP 切面解耦 |