lijiaoqiao/docs/plans/2026-04-02-p1-p2-tdd-execution-plan-v1.md

# P1/P2 TDD开发执行计划

> 版本：v1.0
> 日期：2026-04-02
> 依据：Superpowers执行框架 + TDD规范
> 目标：P0 staging验证BLOCKED期间，并行启动P1/P2核心模块TDD开发

---

## 1. 当前状态

### 1.1 Superpowers执行状态

| 工作流 | 状态 | 说明 |
|--------|------|------|
| WG-A 需求冻结 | DONE | PRD v1已冻结 |
| WG-B 契约对齐 | DONE | OpenAPI已对齐 |
| WG-C 测试矩阵 | DONE | 路径一致化完成 |
| WG-D 真实联调 | **BLOCKED** | 缺staging环境 |
| WG-E 报告签署 | **BLOCKED** | 依赖WG-D |
| WG-F 一致性收尾 | DONE | 命名策略完成 |
| WG-G 全局校验 | DONE | 校验链路可执行 |

### 1.2 P1/P2设计状态

| 设计文档 | 评审结论 | 状态 |
|----------|----------|------|
| multi_role_permission_design | GO | 可进入开发 |
| audit_log_enhancement_design | GO | 可进入开发 |
| routing_strategy_template_design | GO | 可进入开发 |
| sso_saml_technical_research | GO | 可进入调研 |
| compliance_capability_package_design | GO | 可进入开发 |

---

## 2. TDD开发原则

### 2.1 红绿重构循环

```
┌─────────────────────────────────────────────────────┐
│  1. RED: 写一个失败的测试（描述期望行为）           │
│  2. GREEN: 写最少量代码让测试通过                   │
│  3. REFACTOR: 重构代码，消除重复                   │
│  循环直到功能完成                                   │
└─────────────────────────────────────────────────────┘
```

### 2.2 测试分层

| 层级 | 范围 | 工具 |
|------|------|------|
| 单元测试 | 纯函数、核心逻辑 | Go test, testify |
| 集成测试 | 模块间交互 | Go test, testify |
| E2E测试 | 完整API链路 | Bash脚本 |

### 2.3 门禁检查

```
Pre-Commit → Unit Tests → Integration Tests → Build Gate → Staging Gate
```

---

## 3. P1开发任务

### 3.1 多角色权限（IAM）

#### 设计文档
`docs/multi_role_permission_design_v1_2026-04-02.md`

#### TDD任务

| Step | 描述 | 测试先行 | 验收标准 |
|------|------|----------|----------|
| IAM-01 | 数据模型：iam_roles表DDL | ✅ | 表结构符合规范 |
| IAM-02 | 数据模型：iam_scopes表DDL | ✅ | 表结构符合规范 |
| IAM-03 | 数据模型：iam_role_scopes关联表DDL | ✅ | 关联正确 |
| IAM-04 | 数据模型：iam_user_roles关联表DDL | ✅ | 关联正确 |
| IAM-05 | 中间件：Scope验证中间件 | ✅ | 正确校验scope |
| IAM-06 | 中间件：角色继承逻辑 | ✅ | 继承关系正确 |
| IAM-07 | API：角色管理API | ✅ | CRUD正确 |
| IAM-08 | API：权限校验API | ✅ | 正确返回 |

#### 目录结构
```
supply-api/internal/
├── iam/                    # 新增IAM模块
│   ├── model/             # 数据模型
│   │   ├── role.go
│   │   ├── scope.go
│   │   └── user_role.go
│   ├── repository/        # 仓储
│   │   └── iam_repository.go
│   ├── service/          # 服务层
│   │   └── iam_service.go
│   ├── handler/          # HTTP处理器
│   │   └── iam_handler.go
│   └── middleware/       # 权限中间件
│       └── scope_auth.go
```

### 3.2 审计日志增强

#### 设计文档
`docs/audit_log_enhancement_design_v1_2026-04-02.md`

#### TDD任务

| Step | 描述 | 测试先行 | 验收标准 |
|------|------|----------|----------|
| AUD-01 | 数据模型：audit_events表DDL | ✅ | 表结构符合规范 |
| AUD-02 | 数据模型：M-013~M-016子表DDL | ✅ | 子表结构正确 |
| AUD-03 | 事件分类：SECURITY事件定义 | ✅ | invariant_violation存在 |
| AUD-04 | 事件分类：CRED事件定义 | ✅ | CRED-EXPOSE/INGRESS/DIRECT |
| AUD-05 | 写入API：POST /audit/events | ✅ | 幂等性正确 |
| AUD-06 | 查询API：GET /audit/events | ✅ | 分页过滤正确 |
| AUD-07 | 指标API：M-013~M-016统计 | ✅ | 计算正确 |
| AUD-08 | 脱敏扫描：敏感信息检测 | ✅ | 扫描逻辑正确 |

#### 目录结构
```
supply-api/internal/audit/
├── model/                 # 审计事件模型
│   ├── audit_event.go
│   └── audit_metrics.go
├── repository/           # 审计仓储
│   └── audit_repository.go
├── service/             # 审计服务
│   └── audit_service.go
├── handler/             # HTTP处理器
│   └── audit_handler.go
└── sanitizer/           # 脱敏扫描器
    └── sanitizer.go
```

### 3.3 路由策略模板

#### 设计文档
`docs/routing_strategy_template_design_v1_2026-04-02.md`

#### TDD任务

| Step | 描述 | 测试先行 | 验收标准 |
|------|------|----------|----------|
| ROU-01 | 评分模型：ScoreWeights默认权重 | ✅ | 延迟40%/可用30%/成本20%/质量10% |
| ROU-02 | 评分模型：CalculateScore方法 | ✅ | 评分正确 |
| ROU-03 | 策略模板：StrategyTemplate接口 | ✅ | 模板可替换 |
| ROU-04 | 策略模板：CostBased/CostAware策略 | ✅ | 策略正确 |
| ROU-05 | 路由决策：RoutingEngine | ✅ | 决策正确 |
| ROU-06 | Fallback：多级Fallback | ✅ | 降级正确 |
| ROU-07 | 指标采集：M-008采集 | ✅ | 全路径覆盖 |
| ROU-08 | A/B测试：ABStrategyTemplate | ✅ | 流量分配正确 |
| ROU-09 | 灰度发布：RolloutConfig | ✅ | 百分比正确 |

#### 目录结构
```
gateway/internal/router/
├── strategy/             # 策略模板
│   ├── strategy.go       # 接口定义
│   ├── cost_based.go
│   ├── cost_aware.go
│   ├── quality_first.go
│   ├── latency_first.go
│   ├── ab_strategy.go
│   └── rollout.go
├── scoring/             # 评分模型
│   └── scoring_model.go
├── engine/              # 路由引擎
│   └── routing_engine.go
├── metrics/             # 指标采集
│   └── routing_metrics.go
└── fallback/            # Fallback策略
    └── fallback.go
```

---

## 4. P2开发任务

### 4.1 合规能力包

#### 设计文档
`docs/compliance_capability_package_design_v1_2026-04-02.md`

#### TDD任务

| Step | 描述 | 测试先行 | 验收标准 |
|------|------|----------|----------|
| CMP-01 | 规则引擎：规则加载器 | ✅ | YAML加载正确 |
| CMP-02 | 规则引擎：CRED-EXPOSE规则 | ✅ | 凭证泄露检测 |
| CMP-03 | 规则引擎：CRED-INGRESS规则 | ✅ | 入站覆盖检测 |
| CMP-04 | 规则引擎：CRED-DIRECT规则 | ✅ | 直连检测 |
| CMP-05 | 规则引擎：AUTH-QUERY规则 | ✅ | query key拒绝检测 |
| CMP-06 | CI脚本：m013_credential_scan.sh | ✅ | 扫描执行正确 |
| CMP-07 | CI脚本：M-017四件套生成 | ✅ | SBOM生成正确 |
| CMP-08 | Gate集成：compliance_gate.sh | ✅ | 门禁通过 |

#### 目录结构
```
gateway/internal/compliance/     # 或新增compliance目录
├── rules/                      # 规则定义
│   ├── loader.go
│   ├── cred_expose.go
│   ├── cred_ingress.go
│   ├── cred_direct.go
│   └── auth_query.go
├── engine/                    # 规则引擎
│   └── compliance_engine.go
└── ci/                        # CI脚本
    ├── compliance_gate.sh
    ├── m013_credential_scan.sh
    ├── m014_ingress_check.sh
    ├── m015_direct_check.sh
    ├── m016_query_key_check.sh
    └── m017_dependency_audit.sh
```

---

## 5. TDD执行协议

### 5.1 单个任务执行流程

```
1. 读取设计文档对应章节
2. 编写测试用例（RED）
3. 运行测试确认失败（RED）
4. 编写实现代码（GREEN）
5. 运行测试确认通过（GREEN）
6. 重构代码（REFACTOR）
7. 提交代码（git commit）
```

### 5.2 测试命名规范

```go
// 命名格式: Test{模块}_{场景}_{期望行为}
TestAuditService_CreateEvent_Success
TestAuditService_CreateEvent_DuplicateIdempotencyKey
TestRoutingEngine_SelectProvider_CostBasedStrategy
TestScopeAuth_CheckScope_SuperAdminHasAllScopes
```

### 5.3 断言规范

```go
// 使用testify/assert
assert.Equal(t, expected, actual, "描述")
assert.NoError(t, err, "描述")
assert.True(t, condition, "描述")
```

---

## 6. 执行约束

1. **测试先行**：必须先写测试再写实现
2. **门禁检查**：所有测试通过才能提交
3. **代码覆盖**：核心逻辑覆盖率 >= 80%
4. **文档更新**：每完成一个任务更新进度

---

## 7. 验收标准

### 7.1 IAM模块

| 验收项 | 标准 |
|--------|------|
| 审计字段 | request_id, created_ip, updated_ip, version |
| 角色层级 | super_admin(100) > org_admin(50) > supply_admin(40) > ... > viewer(10) |
| Scope校验 | 正确校验token.scope包含required_scope |
| API | /api/v1/iam/* CRUD正确 |

### 7.2 审计日志模块

| 验收项 | 标准 |
|--------|------|
| 事件分类 | CRED-EXPOSE/INGRESS/DIRECT, AUTH-QUERY |
| M-014/M-016边界 | 分母不同，无重叠 |
| 幂等性 | 201/202/409/200正确响应 |
| 脱敏 | 敏感字段自动掩码 |

### 7.3 路由策略模块

| 验收项 | 标准 |
|--------|------|
| 评分权重 | 延迟40%/可用30%/成本20%/质量10% |
| M-008覆盖 | 主路径+Fallback全采集 |
| A/B测试 | 流量分配正确 |
| 灰度发布 | 百分比递增正确 |

### 7.4 合规模块

| 验收项 | 标准 |
|--------|------|
| 规则格式 | CRED-EXPOSE-RESPONSE等 |
| M-017四件套 | SBOM+LockfileDiff+兼容矩阵+风险登记册 |
| CI集成 | compliance_gate.sh可执行 |

---

## 8. 进度追踪

| 任务 | 状态 | 完成日期 |
|------|------|----------|
| IAM-01~08 | TODO | - |
| AUD-01~08 | TODO | - |
| ROU-01~09 | TODO | - |
| CMP-01~08 | TODO | - |

---

**文档状态**：执行计划
**下次更新**：每日进度报告
**维护责任人**：项目开发组