niuniu/lijiaoqiao
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(P1/P2): 完成TDD开发及P1/P2设计文档

Browse Source 
## 设计文档
- multi_role_permission_design: 多角色权限设计 (CONDITIONAL GO)
- audit_log_enhancement_design: 审计日志增强 (CONDITIONAL GO)
- routing_strategy_template_design: 路由策略模板 (CONDITIONAL GO)
- sso_saml_technical_research: SSO/SAML调研 (CONDITIONAL GO)
- compliance_capability_package_design: 合规能力包设计 (CONDITIONAL GO)

## TDD开发成果
- IAM模块: supply-api/internal/iam/ (111个测试)
- 审计日志模块: supply-api/internal/audit/ (40+测试)
- 路由策略模块: gateway/internal/router/ (33+测试)
- 合规能力包: gateway/internal/compliance/ + scripts/ci/compliance/

## 规范文档
- parallel_agent_output_quality_standards: 并行Agent产出质量规范
- project_experience_summary: 项目经验总结 (v2)
- 2026-04-02-p1-p2-tdd-execution-plan: TDD执行计划

## 评审报告
- 5个CONDITIONAL GO设计文档评审报告
- fix_verification_report: 修复验证报告
- full_verification_report: 全面质量验证报告
- tdd_module_quality_verification: TDD模块质量验证
- tdd_execution_summary: TDD执行总结

依据: Superpowers执行框架 + TDD规范
This commit is contained in:
Your Name
2026-04-02 23:35:53 +08:00
parent ed0961d486
commit 89104bd0db
94 changed files with 24738 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1354
docs/audit_log_enhancement_design_v1_2026-04-02.md Normal file
View File

File diff suppressed because it is too large Load Diff

971
docs/compliance_capability_package_design_v1_2026-04-02.md Normal file
View File

@@ -0,0 +1,971 @@
# P2 合规能力包详细设计
> 本文档为 P2 阶段合规能力包的增强设计，基于 `tos_compliance_engine_design_v1_2026-03-18.md` 的 S4 合规引擎架构，扩展以满足 M-013~M-017 指标的自动化合规检查与报告需求。
---
## 1. 概述与背景
### 1.1 目的
P2 合规能力包旨在扩展现有 ToS 合规引擎的能力，实现：
1. **合规规则库扩展**：支持 M-013~M-016 指标的规则化定义与执行
2. **自动化合规检查**：将合规检查嵌入 CI/CD 流水线，实时检测违规事件
3. **合规报告生成**：自动生成符合 M-017 要求的依赖兼容审计四件套报告
### 1.2 指标映射
| 指标ID | 指标名称 | 目标值 | 阻断阈值 | P2 能力要求 |
|--------|----------|--------|----------|-------------|
| M-013 | supplier_credential_exposure_events | 0 | >0 即 P0 | 凭证泄露检测规则 + 实时告警 |
| M-014 | platform_credential_ingress_coverage_pct | 100% | <100% 即阻断 | 入站凭证校验 + 覆盖率统计 |
| M-015 | direct_supplier_call_by_consumer_events | 0 | >0 即 P0 | 直连检测规则 + 阻断机制 |
| M-016 | query_key_external_reject_rate_pct | 100% | <100% 即阻断 | 外部 query key 拒绝规则 |
| M-017 | dependency_compatibility_audit | PASS | FAIL 即阻断 | SBOM + 锁文件 diff + 兼容矩阵 + 风险登记册 |
### 1.3 与现有设计的关系
```
tos_compliance_engine_design_v1_2026-03-18.md (S4 设计)
│
▼
┌─────────────────────────────────────────────┐
│ P2 合规能力包扩展 │
├─────────────────────────────────────────────┤
│ 1. 合规规则库扩展（M-013~M-016 指标规则化） │
│ 2. 自动化合规检查（CI 流水线集成） │
│ 3. 合规报告生成（M-017 四件套） │
└─────────────────────────────────────────────┘
```
---
## 2. 合规规则库扩展
### 2.1 M-013 凭证泄露检测规则
#### 2.1.1 规则定义
> **重要**：所有事件命名遵循 `audit_log_enhancement_design_v1_2026-04-02.md` 规范，格式为 `{Category}-{SubCategory}[-{Detail}]`，以确保与审计日志系统兼容。
| 规则ID | 事件名称 | 匹配条件 | 动作 | 严重级别 |
|--------|----------|----------|------|----------|
| R01 | CRED-EXPOSE-RESPONSE | 响应包含 `sk-`、`ak-`、`api_key` 等可复用凭证片段 | block + alert | P0 |
| R02 | CRED-EXPOSE-LOG | 日志输出包含完整凭证格式 | block + alert | P0 |
| R03 | CRED-EXPOSE-EXPORT | 导出功能返回可还原凭证 | block + alert | P0 |
| R04 | CRED-EXPOSE-WEBHOOK | 回调请求携带供应商凭证 | block + alert | P0 |
> **注**：原 `C013-R01~R04` 格式已废弃，统一使用 `CRED-EXPOSE-*` 格式与审计日志对齐。
#### 2.1.2 规则配置示例
```yaml
# compliance/rules/m013_credential_exposure.yaml
rules:
- id: "CRED-EXPOSE-RESPONSE"
name: "响应体凭证泄露检测"
description: "检测 API 响应中是否包含可复用的供应商凭证片段"
severity: "P0"
matchers:
- type: "regex_match"
pattern: "(sk-|ak-|api_key|secret|token).*[a-zA-Z0-9]{20,}"
target: "response_body"
scope: "all"
action:
primary: "block"
secondary: "alert"
notification:
channels: ["slack", "email"]
template: "credential_exposure_alert"
audit:
log_level: "critical"
retention_days: 1825 # 5年
# 审计日志事件名称（与 audit_log_enhancement_design_v1_2026-04-02.md 对齐）
event_name: "CRED-EXPOSE-RESPONSE"
event_category: "CRED"
event_sub_category: "EXPOSE"
```
#### 2.1.3 检测算法
```
凭证泄露检测算法 (CRED-EXPOSE-D01)
输入: HTTP 响应体内容
输出: 泄露检测结果 {is_leaked: bool, matches: []Match}
步骤:
1. 预编译凭证正则模式库
2. 对响应体进行多模式并行匹配
3. 过滤误报 (测试数据、示例数据)
4. 若匹配, 提取匹配片段并脱敏后记录审计日志
- 审计事件名称: CRED-EXPOSE-RESPONSE
- 事件分类: CRED
- 事件子分类: EXPOSE
5. 触发阻断或告警流程
```
### 2.2 M-014 入站凭证覆盖率规则
#### 2.2.1 规则定义
| 规则ID | 事件名称 | 匹配条件 | 动作 | 严重级别 |
|--------|----------|----------|------|----------|
| R01 | CRED-INGRESS-PLATFORM | 请求头不包含 `Authorization: Bearer ptk_*` | block + alert | P0 |
| R02 | CRED-INGRESS-FORMAT | 平台凭证格式不符合规范 | block + alert | P1 |
| R03 | CRED-INGRESS-EXPIRED | 平台凭证已过期或被吊销 | block | P0 |
> **注**：原 `C014-R01~R03` 格式已废弃，统一使用 `CRED-INGRESS-*` 格式与审计日志对齐。
#### 2.2.2 覆盖率统计
```yaml
# compliance/rules/m014_ingress_coverage.yaml
coverage_tracking:
metric: "platform_credential_ingress_coverage_pct"
calculation: "(使用有效平台凭证的请求数 / 总请求数) * 100"
target: 100
blocking_threshold: 100
window: "rolling_1h"
aggregation: "percentile"
```
### 2.3 M-015 直连检测规则
#### 2.3.1 规则定义
| 规则ID | 事件名称 | 匹配条件 | 动作 | 严重级别 |
|--------|----------|----------|------|----------|
| R01 | CRED-DIRECT-SUPPLIER | 请求目标为已知供应商 IP/域名 | block + alert | P0 |
| R02 | CRED-DIRECT-API | 请求路径匹配 `*/v1/chat/completions` 等上游端点 | block | P0 |
| R03 | CRED-DIRECT-UNAUTH | 调用未经审批的供应商 | block + alert | P0 |
> **注**：原 `C015-R01~R03` 格式已废弃，统一使用 `CRED-DIRECT-*` 格式与审计日志对齐。
#### 2.3.2 检测方法
M-015 直连检测通过以下多层检测机制实现：
| 检测方法 | 描述 | 检测点 |
|----------|------|--------|
| **蜜罐检测** | 在 API Gateway 层部署蜜罐端点，检测是否有直接访问上游 API 的请求 | API Gateway |
| **网络流量分析** | 监控出站连接，识别绕过平台代理的直接连接 | 出网防火墙 |
| **API 日志分析** | 分析请求日志，检测异常的上游 API 调用模式 | 审计中间件 |
| **DNS 解析监控** | 监控 DNS 解析，检测是否有应用直接解析供应商域名 | 网络层 |
| **代理层检测** | 检查请求是否经过平台代理层，未经过则标记为直连 | 负载均衡器 |
> **检测流程**：蜜罐触发 -> 网络流量分析 -> API 日志复核 -> 确认直连事件
#### 2.3.2 供应商白名单配置
```yaml
# compliance/config/allowed_suppliers.yaml
allowed_suppliers:
direct_access:
# 禁止直连，全部通过平台代理
enabled: false
approved_providers:
- name: "openai"
base_urls:
- "api.openai.com"
- "api.openai.azure.com"
requires_approval: true
- name: "anthropic"
base_urls:
- "api.anthropic.com"
requires_approval: true
- name: "minimax"
base_urls:
- "api.minimax.chat"
requires_approval: false
```
### 2.4 M-016 外部 Query Key 拒绝规则
#### 2.4.1 规则定义
| 规则ID | 事件名称 | 匹配条件 | 动作 | 严重级别 |
|--------|----------|----------|------|----------|
| R01 | AUTH-QUERY-KEY | 来自外部的 query key 请求进入平台北向入口 | reject (403) | P0 |
| R02 | AUTH-QUERY-INJECT | 请求参数包含 `key=`、`api_key=`、`token=` 等外部 key | reject (403) | P0 |
| R03 | AUTH-QUERY-AUDIT | 内部处理 query key 时记录全量审计 | alert | P1 |
> **注**：原 `C016-R01~R03` 格式已废弃，统一使用 `AUTH-QUERY-*` 格式与审计日志对齐。
#### 2.4.2 拒绝模式配置
```yaml
# compliance/rules/m016_query_key_reject.yaml
query_key_rejection:
enabled: true
default_action: "reject"
patterns:
# 拒绝所有包含以下模式的外部请求
reject_patterns:
- "key=.*"
- "api_key=.*"
- "token=.*"
- "bearer=.*"
- "authorization=.*"
# 允许内部白名单模式
allow_patterns:
- "^internal-.*"
- "^platform-.*"
response:
status_code: 403
message: "External query keys are not allowed"
include_request_id: true
```
---
## 3. 自动化合规检查
### 3.1 架构设计
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ 自动化合规检查系统 │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
│ │ 合规规则引擎 │───▶│ 实时检测器 │───▶│ 告警发送器 │ │
│ │ (Rule Engine) │ │ (Real-time) │ │ (Notifier) │ │
│ └────────────────┘ └────────────────┘ └────────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ 合规指标存储层 │ │
│ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │
│ │ │ M-013 │ │ M-014 │ │ M-015 │ │ M-016 │ │ │
│ │ │ 泄露事件 │ │ 入站覆盖 │ │ 直连事件 │ │ 拒绝率 │ │ │
│ │ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ CI/CD 流水线集成 │ │
│ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │
│ │ │ Pre-Commit │ │ Build │ │ Deploy │ │ Monitor │ │ │
│ │ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
```
### 3.2 规则执行引擎
#### 3.2.1 核心组件
| 组件 | 职责 | 性能要求 |
|------|------|----------|
| **规则编译器** | 将 YAML 规则编译为可执行格式 | 启动时编译，不影响运行时 |
| **规则匹配器** | 根据请求上下文匹配适用规则 | P95 < 2ms |
| **策略执行器** | 执行 block/alert/reject 动作 | P95 < 1ms |
| **审计记录器** | 记录所有合规决策 | 异步，不阻塞主流程 |
#### 3.2.2 规则执行流程
```
规则执行流程 (CMP-FLOW-01)
1. 请求进入合规检查拦截点
│
▼
2. 提取请求上下文
- 请求头 (Authorization, X-Request-Id)
- 请求路径
- 请求参数
- 源 IP
│
▼
3. 并行匹配所有启用规则
│
▼
4. 聚合匹配结果
- 若存在 P0 匹配 → 立即阻断
- 若存在 P1 匹配 → 告警 + 继续
- 若仅 P2/P3 匹配 → 记录但不阻断
│
▼
5. 执行动作
- block: 返回错误响应
- alert: 发送告警通知
- reject: 返回 403
│
▼
6. 记录审计日志
- 规则 ID
- 匹配结果
- 执行动作
- 时间戳
```
### 3.3 CI/CD 流水线集成
#### 3.3.1 集成点
| 阶段 | 检查项 | 阻断条件 | 超时时间 |
|------|--------|----------|----------|
| **Pre-Commit** | 本地凭证泄露扫描 | M-013 > 0 | 30s |
| **Build** | 依赖兼容审计 (M-017) | 四件套任一 FAIL | 120s |
| **Deploy-Staging** | M-013~M-016 实时检测 | 任一 P0 | N/A (实时) |
| **Deploy-Production** | M-013~M-016 实时检测 | 任一 P0 | N/A (实时) |
| **Monitor** | 7x24 指标监控 | 阈值突破 | N/A |
#### 3.3.2 CI 脚本集成
```bash
# compliance/ci/compliance_gate.sh
#!/bin/bash
# 合规门禁 CI 脚本
set -e
# 使用环境变量或相对路径，避免硬编码
COMPLIANCE_BASE="${COMPLIANCE_BASE:-$(cd "$(dirname "$0")/.." && pwd)}"
RULES_DIR="${COMPLIANCE_BASE}/rules"
REPORTS_DIR="${COMPLIANCE_BASE}/reports"
# M-013: 凭证泄露扫描
echo "[COMPLIANCE] Running M-013 credential exposure scan..."
if ! bash "${COMPLIANCE_BASE}/ci/m013_credential_scan.sh"; then
echo "[COMPLIANCE] M-013 FAILED: Credential exposure detected"
exit 1
fi
# M-014: 入站覆盖率检查
echo "[COMPLIANCE] Running M-014 ingress coverage check..."
if ! bash "${COMPLIANCE_BASE}/ci/m014_ingress_coverage.sh"; then
echo "[COMPLIANCE] M-014 FAILED: Ingress coverage below 100%"
exit 1
fi
# M-015: 直连检测
echo "[COMPLIANCE] Running M-015 direct access check..."
if ! bash "${COMPLIANCE_BASE}/ci/m015_direct_access_check.sh"; then
echo "[COMPLIANCE] M-015 FAILED: Direct supplier access detected"
exit 1
fi
# M-016: Query Key 拒绝率
echo "[COMPLIANCE] Running M-016 query key rejection check..."
if ! bash "${COMPLIANCE_BASE}/ci/m016_query_key_reject.sh"; then
echo "[COMPLIANCE] M-016 FAILED: Query key rejection rate below 100%"
exit 1
fi
# M-017: 依赖兼容审计
echo "[COMPLIANCE] Running M-017 dependency audit..."
if ! bash "${COMPLIANCE_BASE}/ci/m017_dependency_audit.sh"; then
echo "[COMPLIANCE] M-017 FAILED: Dependency compatibility issue"
exit 1
fi
echo "[COMPLIANCE] All checks PASSED"
```
> **注意**：以下 CI 脚本处于**待实现**状态，依赖于 `compliance/` 目录的创建：
> - `m013_credential_scan.sh` - 待实现
> - `m014_ingress_coverage.sh` - 待实现
> - `m015_direct_access_check.sh` - 待实现
> - `m016_query_key_reject.sh` - 待实现
> - `m017_dependency_audit.sh` - 待实现
### 3.4 实时监控
#### 3.4.1 监控指标
| 指标 | 描述 | 告警阈值 |
|------|------|----------|
| m013_exposure_events_total | 凭证泄露事件总数 | > 0 |
| m014_ingress_coverage_pct | 入站凭证覆盖率 | < 100 |
| m015_direct_access_events_total | 直连事件总数 | > 0 |
| m016_query_key_reject_rate_pct | query key 拒绝率 | < 100 |
| compliance_rules_triggered_total | 规则触发总数 | N/A |
#### 3.4.2 告警规则
```yaml
# compliance/monitoring/alerts.yaml
alerts:
- name: "m013_credential_exposure_p0"
condition: "m013_exposure_events_total > 0"
severity: "P0"
channels: ["slack_critical", "pagerduty", "email"]
message: "P0: Credential exposure event detected"
- name: "m014_ingress_coverage_degraded"
condition: "m014_ingress_coverage_pct < 100"
severity: "P0"
channels: ["slack_critical", "pagerduty"]
message: "P0: Platform credential ingress coverage below 100%"
- name: "m015_direct_access_detected"
condition: "m015_direct_access_events_total > 0"
severity: "P0"
channels: ["slack_critical", "pagerduty", "email"]
message: "P0: Direct supplier access detected"
- name: "m016_reject_rate_degraded"
condition: "m016_query_key_reject_rate_pct < 100"
severity: "P1"
channels: ["slack", "email"]
message: "P1: Query key rejection rate below 100%"
```
---
## 4. 合规报告生成
### 4.1 M-017 依赖兼容审计四件套
根据 `supply_gate_command_playbook_v1_2026-03-25.md` 第7章要求，M-017 需生成以下四件套：
| 报告 | 文件名模式 | 内容要求 |
|------|------------|----------|
| **SBOM** | `sbom_{date}.spdx.json` | 软件物料清单，SPDX 2.3 格式 |
| **锁文件 Diff** | `lockfile_diff_{date}.md` | 依赖版本变更对比 |
| **兼容矩阵** | `compat_matrix_{date}.md` | 组件版本兼容性矩阵 |
| **风险登记册** | `risk_register_{date}.md` | 发现的安全与合规风险 |
### 4.2 四件套生成流程
```
依赖兼容审计流程 (M017-FLOW-01)
1. 执行时间: 每日 00:00 UTC (CI Build 阶段自动触发)
│
▼
2. SBOM 生成
- 使用 syft/spdx-syft 生成项目 SPDX 2.3 SBOM
- 覆盖语言: Go (go.mod), Node (package.json), Python (requirements.txt)
│
▼
3. 锁文件 Diff 生成
- 对比当前 lock 文件与 baseline
- 提取新增/升级/降级/删除依赖
- 变更影响评估
│
▼
4. 兼容矩阵生成
- 读取兼容矩阵模板
- 填充当前版本信息
- 标注已知不兼容项
│
▼
5. 风险登记册生成
- 汇总 CVSS >= 7.0 的漏洞
- 汇总许可证合规风险
- 汇总过期依赖风险
│
▼
6. 报告输出
- 生成日期标注的报告文件
- 更新趋势数据库
- 发送摘要邮件
```
### 4.3 四件套详细规格
#### 4.3.1 SBOM (软件物料清单)
```json
{
"spdxVersion": "SPDX-2.3",
"dataLicense": "CC0-1.0",
"SPDXID": "SPDXRef-DOCUMENT",
"name": "llm-gateway",
"documentNamespace": "https://llm-gateway.example.com/spdx/2026-04-02",
"creationInfo": {
"created": "2026-04-02T00:00:00Z",
"creators": ["Tool: syft-0.100.0"]
},
"packages": [
{
"SPDXID": "SPDXRef-Package-go-github-com-openai",
"name": "github.com/openai/openai-go",
"versionInfo": "v0.2.0",
"supplier": "Organization: OpenAI",
"downloadLocation": "https://github.com/openai/openai-go",
"licenseConcluded": "Apache-2.0"
}
]
}
```
#### 4.3.2 锁文件 Diff
```markdown
# Lockfile Diff Report - 2026-04-02
## Summary
| 变更类型 | 数量 |
|----------|------|
| 新增依赖 | 3 |
| 升级依赖 | 7 |
| 降级依赖 | 0 |
| 删除依赖 | 1 |
## New Dependencies
| 名称 | 版本 | 用途 | 风险评估 |
|------|------|------|----------|
| github.com/acme/newpkg | v1.2.0 | 新功能 | LOW |
## Upgraded Dependencies
| 名称 | 旧版本 | 新版本 | 风险评估 |
|------|--------|--------|----------|
| github.com/acme/existing | v1.0.0 | v1.1.0 | LOW |
## Deleted Dependencies
| 名称 | 旧版本 | 原因 |
|------|--------|------|
| github.com/acme/unused | v0.9.0 | 功能下线 |
## Breaking Changes
None detected.
```
#### 4.3.3 兼容矩阵
```markdown
# Dependency Compatibility Matrix - 2026-04-02
## Go Dependencies
| 组件 | 版本 | Go 1.21 | Go 1.22 | Go 1.23 |
|------|------|----------|----------|----------|
| github.com/acme/pkg | v1.2.0 | PASS | PASS | PASS |
## Known Incompatibilities
None detected.
```
#### 4.3.4 风险登记册
```markdown
# Risk Register - 2026-04-02
## Summary
| 风险级别 | 数量 |
|----------|------|
| CRITICAL | 0 |
| HIGH | 1 |
| MEDIUM | 2 |
| LOW | 5 |
## High Risk Items
| ID | 描述 | CVSS | 组件 | 修复建议 |
|----|------|------|------|----------|
| RISK-001 | CVE-2024-XXXXX | 8.1 | github.com/acme/vuln-pkg | 升级到 v1.3.0 |
## Medium Risk Items
| ID | 描述 | CVSS | 组件 | 修复建议 |
|----|------|------|------|----------|
| RISK-002 | License: GPL-3.0 conflict | N/A | github.com/acme/gpl-pkg | 评估许可证合规 |
## Mitigation Status
| ID | 状态 | 负责人 | 截止日期 |
|----|------|--------|----------|
| RISK-001 | IN_PROGRESS | @security | 2026-04-05 |
```
### 4.4 自动化报告生成脚本
```bash
#!/bin/bash
# compliance/reports/m017_dependency_audit.sh
#!/usr/bin/env bash
set -e
REPORT_DATE="${1:-$(date +%Y-%m-%d)}"
# 使用环境变量或相对路径，避免硬编码
REPORT_DIR="${COMPLIANCE_REPORT_DIR:-${PROJECT_ROOT}/reports/dependency}"
PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$(dirname "$0")/../.." && pwd)}"
mkdir -p "${REPORT_DIR}"
echo "[M017] Starting dependency audit for ${REPORT_DATE}"
# 1. Generate SBOM
echo "[M017] Generating SBOM..."
if command -v syft >/dev/null 2>&1; then
syft "${PROJECT_ROOT}" -o spdx-json > "${REPORT_DIR}/sbom_${REPORT_DATE}.spdx.json"
# 验证 SBOM 包含有效包
if ! grep -q '"packages"' "${REPORT_DIR}/sbom_${REPORT_DATE}.spdx.json" || \
[ "$(grep -c '"SPDXRef' "${REPORT_DIR}/sbom_${REPORT_DATE}.spdx.json" || echo 0)" -eq 0 ]; then
echo "[M017] FAIL: syft generated invalid SBOM (no packages found)"
exit 1
fi
echo "[M017] SBOM generated successfully with syft"
else
echo "[M017] ERROR: syft is required but not found. Please install syft first."
echo "[M017] See: https://github.com/anchore/syft#installation"
exit 1
fi
# 2. Generate Lockfile Diff
echo "[M017] Generating lockfile diff..."
LOCKFILE_DIFF_SCRIPT="${PROJECT_ROOT}/scripts/ci/lockfile_diff.sh"
if [ -x "$LOCKFILE_DIFF_SCRIPT" ]; then
bash "$LOCKFILE_DIFF_SCRIPT" "${REPORT_DATE}" > "${REPORT_DIR}/lockfile_diff_${REPORT_DATE}.md"
else
echo "[M017] ERROR: lockfile_diff.sh not found or not executable at $LOCKFILE_DIFF_SCRIPT"
exit 1
fi
# 3. Generate Compatibility Matrix
echo "[M017] Generating compatibility matrix..."
COMPAT_MATRIX_SCRIPT="${PROJECT_ROOT}/scripts/ci/compat_matrix.sh"
if [ -x "$COMPAT_MATRIX_SCRIPT" ]; then
bash "$COMPAT_MATRIX_SCRIPT" "${REPORT_DATE}" > "${REPORT_DIR}/compat_matrix_${REPORT_DATE}.md"
else
echo "[M017] ERROR: compat_matrix.sh not found or not executable at $COMPAT_MATRIX_SCRIPT"
exit 1
fi
# 4. Generate Risk Register
echo "[M017] Generating risk register..."
RISK_REGISTER_SCRIPT="${PROJECT_ROOT}/scripts/ci/risk_register.sh"
if [ -x "$RISK_REGISTER_SCRIPT" ]; then
bash "$RISK_REGISTER_SCRIPT" "${REPORT_DATE}" > "${REPORT_DIR}/risk_register_${REPORT_DATE}.md"
else
echo "[M017] ERROR: risk_register.sh not found or not executable at $RISK_REGISTER_SCRIPT"
exit 1
fi
# 5. Validate all artifacts exist
echo "[M017] Validating artifacts..."
ARTIFACTS=(
"sbom_${REPORT_DATE}.spdx.json"
"lockfile_diff_${REPORT_DATE}.md"
"compat_matrix_${REPORT_DATE}.md"
"risk_register_${REPORT_DATE}.md"
)
ALL_PASS=true
for artifact in "${ARTIFACTS[@]}"; do
if [ -f "${REPORT_DIR}/${artifact}" ] && [ -s "${REPORT_DIR}/${artifact}" ]; then
echo "[M017] ${artifact}: OK"
else
echo "[M017] ${artifact}: MISSING OR EMPTY"
ALL_PASS=false
fi
done
# 6. Generate summary
if [ "$ALL_PASS" = true ]; then
echo "[M017] PASS: All 4 artifacts generated successfully"
exit 0
else
echo "[M017] FAIL: One or more artifacts missing"
exit 1
fi
```
### 4.5 四件套生成脚本详细设计
> **重要**：以下脚本均为**待实现**状态，需要在 P2-CMP-006 阶段完成开发。
#### 4.5.1 Lockfile Diff 生成脚本
```bash
#!/bin/bash
# scripts/ci/lockfile_diff.sh
# 功能：生成依赖版本变更对比报告
# 输入：REPORT_DATE (可选，默认为昨天)
# 输出：lockfile_diff_{date}.md
set -e
REPORT_DATE="${1:-$(date -d '1 day ago' +%Y-%m-%d)}"
PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$(dirname "$0")/../.." && pwd)}"
echo "# Lockfile Diff Report - ${REPORT_DATE}"
# 获取当前 lockfile
LOCKFILE="${PROJECT_ROOT}/go.sum"
BASELINE_DIR="${PROJECT_ROOT}/.compliance/baseline"
# 对比逻辑
echo "## Summary"
echo "| 变更类型 | 数量 |"
echo "|----------|------|"
echo "| 新增依赖 | TBD |"
echo "| 升级依赖 | TBD |"
echo "| 降级依赖 | TBD |"
echo "| 删除依赖 | TBD |"
# 待实现：实际的对比逻辑
```
#### 4.5.2 兼容矩阵生成脚本
```bash
#!/bin/bash
# scripts/ci/compat_matrix.sh
# 功能：生成组件版本兼容性矩阵
# 输入：REPORT_DATE (可选)
# 输出：compat_matrix_{date}.md
set -e
REPORT_DATE="${1:-$(date -d '1 day ago' +%Y-%m-%d)}"
PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$(dirname "$0")/../.." && pwd)}"
echo "# Dependency Compatibility Matrix - ${REPORT_DATE}"
# 读取 Go 版本信息
GO_VERSION=$(go version 2>/dev/null | grep -oP 'go\d+\.\d+' || echo "unknown")
echo "## Go Dependencies (${GO_VERSION})"
echo "| 组件 | 版本 | 兼容性 |"
echo "|------|------|--------|"
echo "| TBD | TBD | TBD |"
# 待实现：实际的兼容性检查逻辑
```
#### 4.5.3 风险登记册生成脚本
```bash
#!/bin/bash
# scripts/ci/risk_register.sh
# 功能：生成安全与合规风险登记册
# 输入：REPORT_DATE (可选)
# 输出：risk_register_{date}.md
set -e
REPORT_DATE="${1:-$(date -d '1 day ago' +%Y-%m-%d)}"
PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$(dirname "$0")/../.." && pwd)}"
echo "# Risk Register - ${REPORT_DATE}"
echo "## Summary"
echo "| 风险级别 | 数量 |"
echo "|----------|------|"
echo "| CRITICAL | 0 |"
echo "| HIGH | 0 |"
echo "| MEDIUM | 0 |"
echo "| LOW | 0 |"
echo "## High Risk Items"
echo "| ID | 描述 | CVSS | 组件 | 修复建议 |"
echo "|----|------|------|------|----------|"
echo "| - | 无高风险项 | - | - | - |"
# 待实现：实际的漏洞扫描和风险评估逻辑
# 建议集成：grype (漏洞扫描)、license-check (许可证检查)
```
---
## 5. 与现有安全机制联动
### 5.1 联动矩阵
| 源机制 | 目标机制 | 联动方式 | 触发条件 |
|--------|----------|----------|----------|
| ToS 合规引擎 | 告警系统 | 事件推送 | 违规事件触发 |
| Token Runtime | 合规规则引擎 | 凭证验证 | Token 校验时 |
| Rate Limit | 合规规则引擎 | 流量检测 | 限流触发时 |
| Audit Middleware | 合规报告 | 日志聚合 | 审计事件写入 |
| Secret Scanner | 合规规则引擎 | 凭证检测 | 扫描结果输出 |
### 5.2 联动设计
#### 5.2.1 告警系统联动
```
合规事件 ──┬──▶ 告警通道 (Slack/PagerDuty/Email)
│
└──▶ 事件存储 (审计数据库)
│
└──▶ 趋势分析 ──▶ M-013~M-016 指标更新
```
#### 5.2.2 Token Runtime 联动
```
Token 校验请求
│
├──▶ CRED-INGRESS-PLATFORM: 验证平台凭证存在
│
├──▶ CRED-INGRESS-FORMAT: 验证凭证格式
│
└──▶ CRED-INGRESS-EXPIRED: 验证凭证状态 (通过 Token Runtime)
```
#### 5.2.3 Audit Middleware 联动
```
HTTP 请求
│
├──▶ Audit Middleware (记录请求)
│
├──▶ 合规规则引擎 (执行检查)
│ │
│ ├──▶ CRED-EXPOSE-* 凭证泄露检测
│ │
│ └──▶ CRED-DIRECT-* 直连检测
│
└──▶ 合规报告生成 (聚合日志)
```
---
## 6. 目录结构
```
compliance/ # [待创建] 合规能力包根目录
├── rules/ # 合规规则定义
│ ├── m013_credential_exposure.yaml
│ ├── m014_ingress_coverage.yaml
│ ├── m015_direct_access.yaml
│ └── m016_query_key_reject.yaml
│
├── config/ # 合规配置
│ ├── allowed_suppliers.yaml
│ ├── alert_channels.yaml
│ └── rule_sets.yaml
│
├── engine/ # 合规规则引擎
│ ├── compiler.go # 规则编译器
│ ├── matcher.go # 规则匹配器
│ ├── executor.go # 策略执行器
│ └── audit.go # 审计记录器
│
├── reports/ # 合规报告 (M-017)
│ ├── m017_dependency_audit.sh # [待实现] 四件套生成脚本
│ └── templates/ # 报告模板
│
├── ci/ # CI 集成
│ ├── compliance_gate.sh # 合规门禁主脚本
│ ├── m013_credential_scan.sh # [待实现]
│ ├── m014_ingress_coverage.sh # [待实现]
│ ├── m015_direct_access_check.sh # [待实现]
│ ├── m016_query_key_reject.sh # [待实现]
│ └── m017_dependency_audit.sh # [待实现]
│
├── monitoring/ # 监控配置
│ ├── alerts.yaml # 告警规则
│ └── dashboards/ # 监控面板
│
└── docs/ # 文档
├── compliance_capability_package_design_v1_2026-04-02.md
└── compliance_rules_reference.md
scripts/ci/ # [已存在] 现有 CI 脚本目录
├── lockfile_diff.sh # [待实现] Lockfile Diff 生成
├── compat_matrix.sh # [待实现] 兼容矩阵生成
└── risk_register.sh # [待实现] 风险登记册生成
```
---
## 7. 实施计划
### 7.1 P2 阶段任务分解
> **工期修正说明**：根据评审意见，原设计工期（26d）低估了CI脚本实现工作量。实际工作量需要 **35-40d**，主要原因是：
> 1. 所有 CI 脚本（m013~m017）均需新实现
> 2. M-017 四件套生成脚本需要独立开发
> 3. 与现有审计日志系统的集成需要额外协调
| 任务ID | 任务名称 | 依赖 | 设计工期 | 修正工期 | 交付物 |
|--------|----------|------|---------|---------|--------|
| P2-CMP-001 | 合规规则引擎核心开发 | - | 5d | 6d | engine/*.go |
| P2-CMP-002 | M-013 凭证泄露规则实现 | P2-CMP-001 | 3d | 4d | rules/m013_*.yaml + ci/m013_*.sh |
| P2-CMP-003 | M-014 入站覆盖规则实现 | P2-CMP-001 | 2d | 3d | rules/m014_*.yaml + ci/m014_*.sh |
| P2-CMP-004 | M-015 直连检测规则实现 | P2-CMP-001 | 2d | 4d | rules/m015_*.yaml + ci/m015_*.sh + 蜜罐配置 |
| P2-CMP-005 | M-016 Query Key 拒绝规则实现 | P2-CMP-001 | 2d | 3d | rules/m016_*.yaml + ci/m016_*.sh |
| P2-CMP-006 | M-017 依赖审计四件套 | - | 3d | 6d | 四件套生成脚本 + 模板 |
| P2-CMP-007 | CI 流水线集成 | P2-CMP-002~006 | 2d | 5d | ci/compliance_gate.sh |
| P2-CMP-008 | 监控告警配置 | P2-CMP-001 | 2d | 3d | monitoring/alerts.yaml |
| P2-CMP-009 | 安全机制联动实现 | P2-CMP-001 | 3d | 4d | 联动代码 |
| P2-CMP-010 | 端到端测试与验证 | P2-CMP-007 | 2d | 4d | 测试报告 |
| **总计** | | | **26d** | **38d** | |
### 7.2 里程碑
| 里程碑 | 完成条件 | 设计日期 | 修正日期 |
|--------|----------|----------|----------|
| **M1: 规则引擎完成** | P2-CMP-001 通过单元测试 | 2026-04-07 | 2026-04-08 |
| **M2: 四大规则就绪** | P2-CMP-002~005 在 staging 通过 | 2026-04-11 | 2026-04-15 |
| **M3: CI 集成完成** | P2-CMP-007 合规门禁在 CI 通过 | 2026-04-13 | 2026-04-20 |
| **M4: 监控告警就绪** | P2-CMP-008 告警通道验证通过 | 2026-04-15 | 2026-04-22 |
| **M5: P2 交付完成** | E2E 测试通过 + 文档完备 | 2026-04-17 | 2026-04-26 |
---
## 8. 验收标准
### 8.1 M-013~M-016 验收
| 指标 | 验收条件 | 测试方法 |
|------|----------|----------|
| M-013 | 凭证泄露事件 = 0 | 自动化扫描 + 渗透测试 |
| M-014 | 入站覆盖率 = 100% | 日志分析覆盖率 |
| M-015 | 直连事件 = 0 | 蜜罐检测 + 日志分析 |
| M-016 | 拒绝率 = 100% | 外部 query key 构造测试 |
### 8.2 M-017 验收
| 报告 | 验收条件 |
|------|----------|
| SBOM | SPDX 2.3 格式有效, 包含所有直接依赖 |
| Lockfile Diff | 变更条目完整, 影响评估准确 |
| 兼容矩阵 | 版本对应关系正确 |
| 风险登记册 | CVSS >= 7.0 漏洞已收录 |
### 8.3 集成验收
| 场景 | 验收条件 |
|------|----------|
| CI 流水线 | 合规门禁在 build 阶段可执行 |
| 告警通道 | 告警可实时送达 (延迟 < 30s) |
| 报告生成 | 四件套在 CI 中自动生成 |
| 规则热更新 | 规则变更无需重启服务 |
---
## 9. 附录
### 9.1 参考文档
- `docs/tos_compliance_engine_design_v1_2026-03-18.md` - ToS 合规引擎设计
- `docs/llm_gateway_subapi_evolution_plan_v4_2_2026-03-24.md` - M-013~M-016 指标定义
- `docs/supply_gate_command_playbook_v1_2026-03-25.md` - M-017 依赖审计要求
### 9.2 术语表
| 术语 | 定义 |
|------|------|
| SBOM | Software Bill of Materials, 软件物料清单 |
| SPDX | Software Package Data Exchange, 软件包数据交换标准 |
| CVSS | Common Vulnerability Scoring System, 通用漏洞评分系统 |
| ToS | Terms of Service, 服务条款 |
| CI | Continuous Integration, 持续集成 |
---
**文档状态**: 已修订
**版本**: v1.1
**日期**: 2026-04-02
**关联任务**: P2 合规能力包设计
**修订说明**:
- 统一事件命名格式与 audit_log_enhancement_design_v1_2026-04-02.md 对齐
- 修复硬编码路径问题，改为环境变量或相对路径
- 补充 M-015 直连检测方法（蜜罐、网络流量分析等）
- 修复 syft 缺失时生成无效 SBOM 问题（改为必需检查）
- 补充 M-017 四件套生成脚本详细设计（待实现状态）
- 修正实施工期从 26d 到 38d

697
docs/multi_role_permission_design_v1_2026-04-02.md Normal file
View File

@@ -0,0 +1,697 @@
# 多角色权限设计方案（P1）
- 版本：v1.0
- 日期：2026-04-02
- 状态：设计稿（已修复）
- 依赖：
- `docs/token_runtime_minimal_spec_v1.md`（TOK-001）
- `docs/token_auth_middleware_design_v1_2026-03-29.md`（TOK-002）
- `docs/llm_gateway_prd_v1_2026-03-25.md`
- 目标：实现 PRD P1 "多角色权限"需求
---
## 1. 背景与目标
### 1.1 业务背景
LLM Gateway 平台需要支持多类用户角色，满足不同的使用场景：
1. **平台管理员** - 负责组织级策略、预算、权限管理
2. **AI 应用开发者** - 负责接入模型与业务落地
3. **财务/运营负责人** - 负责成本追踪、对账与预算控制
4. **供应方** - 拥有多余LLM配额的个人或企业（平台用户）
5. **需求方** - 需要LLM调用能力的企业/开发者
### 1.2 设计目标
1. **角色扩展**：在现有 `owner/viewer/admin` 三角色基础上扩展，支持更多业务场景
2. **权限细分**：支持细粒度的 scope 权限控制
3. **层级清晰**：建立的角色继承/层级关系
4. **API兼容**：保持与现有 SUP-004~SUP-008 链路一致
5. **可扩展**：支持未来新增角色和权限
---
## 2. 现有权限模型分析
### 2.1 现有角色体系（TOK-001）
| 角色 | 等级 | 能力 | 约束 |
|------|------|------|------|
| admin | 3 | 风控与审计管理 | 仅平台内部可用 |
| owner | 2 | 管理供应侧账号、套餐、结算 | 不可读取上游凭证明文 |
| viewer | 1 | 只读查询 | 不可执行写操作 |
### 2.2 现有 JWT Token Claims 结构
```go
type TokenClaims struct {
jwt.RegisteredClaims
SubjectID string `json:"subject_id"` // 用户主体ID
Role string `json:"role"` // 角色: admin/owner/viewer
Scope []string `json:"scope"` // 授权范围列表
TenantID int64 `json:"tenant_id"` // 租户ID
}
```
### 2.3 现有中间件链路（TOK-002）
```
RequestIdMiddleware
↓
QueryKeyRejectMiddleware
↓
BearerExtractMiddleware
↓
TokenVerifyMiddleware
↓
TokenStatusCheckMiddleware
↓
ScopeRoleAuthzMiddleware ← 权限校验
↓
AuditEmitMiddleware
```
---
## 3. 多角色权限设计方案
### 3.1 角色定义
#### 3.1.1 平台侧角色（Platform Roles）
| 角色 | 代码 | 层级 | 说明 | 继承关系 |
|------|------|------|------|----------|
| 超级管理员 | `super_admin` | 100 | 平台最高权限，仅平台运营方可用 | - |
| 组织管理员 | `org_admin` | 50 | 组织级管理，管理本组织所有资源 | 显式配置（拥有operator+finops+developer+viewer所有scope） |
| 运维人员 | `operator` | 30 | 系统运维与配置 | 显式配置（拥有viewer所有scope + platform:write等） |
| 开发者 | `developer` | 20 | AI应用开发者，接入模型与业务落地 | 继承 viewer |
| 财务人员 | `finops` | 20 | 成本追踪、对账与预算控制 | 继承 viewer |
| 查看者 | `viewer` | 10 | 只读查询 | - |
**说明**：
1. 继承关系仅用于权限聚合，代表"子角色拥有父角色所有scope + 自身额外scope"
2. `org_admin` 显式配置拥有 `operator` + `finops` + `developer` + `viewer` 的所有scope
3. `operator` 显式配置拥有 `viewer` 所有scope + `platform:write` 等权限
4. 层级数值仅用于权限优先级判断，不影响继承关系
#### 3.1.2 供应侧角色（Supply Roles）
| 角色 | 代码 | 层级 | 说明 | 继承关系 |
|------|------|------|------|----------|
| 供应方管理员 | `supply_admin` | 40 | 供应侧全面管理 | 显式配置（拥有supply_operator+supply_finops所有scope） |
| 供应方运维 | `supply_operator` | 30 | 套餐管理、额度配置 | 显式配置（拥有supply_viewer所有scope + supply:package:write等） |
| 供应方财务 | `supply_finops` | 20 | 收益结算、对账 | 继承 supply_viewer |
| 供应方查看者 | `supply_viewer` | 10 | 只读查询 | - |
#### 3.1.3 需求侧角色（Consumer Roles）
| 角色 | 代码 | 层级 | 说明 | 继承关系 |
|------|------|------|------|----------|
| 需求方管理员 | `consumer_admin` | 40 | 需求侧全面管理 | 显式配置（拥有consumer_operator所有scope） |
| 需求方运维 | `consumer_operator` | 30 | API Key管理、调用配置 | 显式配置（拥有consumer_viewer所有scope + consumer:apikey:*等） |
| 需求方查看者 | `consumer_viewer` | 10 | 只读查询 | - |
### 3.2 角色层级关系图
```
┌─────────────┐
│ super_admin │ (层级100)
└──────┬──────┘
│ 权限聚合
▼
┌─────────────┐
│ org_admin │ (层级50)
└──────┬──────┘
│ 显式配置（聚合operator+developer+finops+viewer scope）
┌────────────┼────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ operator │ │developer │ │ finops │ (层级20-30)
└────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │
│ 显式配置 │ 继承 │ 继承
│ (+viewer) │ (+viewer) │ (+viewer)
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ viewer │ │ viewer │ │ viewer │ (层级10)
└──────────┘ └──────────┘ └──────────┘
─────────────────────────────────────────
┌──────────┐ ┌──────────────┐
│supply_ad │────│consumer_adm │
│ min │ │ in │ (层级40)
└────┬─────┘ └──────┬───────┘
│ 显式配置 │ 显式配置
│ (+operator │ (+operator
│ +finops) │ +viewer)
▼ ▼
┌──────────┐ ┌──────────────┐
│supply_op │ │consumer_op │
│ erator │ │ erator │ (层级30)
└────┬─────┘ └──────┬───────┘
│ 显式配置 │ 显式配置
│ (+viewer) │ (+viewer)
▼ ▼
┌──────────┐ ┌──────────────┐
│supply_vi │ │consumer_vi │
│ ewer │ │ ewer │ (层级10)
└──────────┘ └──────────────┘
```
**继承关系说明**：
- 继承 = 子角色拥有父角色所有 scope + 自身额外 scope
- 显式配置 = 直接授予特定 scope 列表（等效于显式继承但更清晰）
- supply_admin/consumer_admin = 拥有该类别下所有子角色 scope
- operator/developer/finops = 拥有 viewer 所有 scope + 各自额外 scope
### 3.3 Scope 权限定义
#### 3.3.1 Platform Scope
| Scope | 说明 | 授予角色 |
|-------|------|----------|
| `platform:read` | 读取平台配置 | viewer+ |
| `platform:write` | 修改平台配置 | operator+ |
| `platform:admin` | 平台级管理 | org_admin+ |
| `platform:audit:read` | 读取审计日志 | operator+ |
| `platform:audit:export` | 导出审计日志 | org_admin+ |
#### 3.3.2 Tenant Scope
| Scope | 说明 | 授予角色 | 备注 |
|-------|------|----------|------|
| `tenant:read` | 读取租户信息 | viewer+ | |
| `tenant:write` | 修改租户配置 | operator+ | |
| `tenant:member:manage` | 管理租户成员 | org_admin | |
| `tenant:billing:write` | 修改账单设置 | org_admin | |
#### 3.3.3 Supply Scope
| Scope | 说明 | 授予角色 | 备注 |
|-------|------|----------|------|
| `supply:account:read` | 读取供应账号 | supply_viewer+ | |
| `supply:account:write` | 管理供应账号 | supply_operator+ | |
| `supply:package:read` | 读取套餐信息 | supply_viewer+ | |
| `supply:package:write` | 管理套餐 | supply_operator+ | |
| `supply:package:publish` | 发布套餐 | supply_operator+ | |
| `supply:package:offline` | 下架套餐 | supply_operator+ | |
| `supply:settlement:withdraw` | 提现 | supply_admin | |
| `supply:credential:manage` | 管理凭证 | supply_admin | |
#### 3.3.4 Consumer Scope
| Scope | 说明 | 授予角色 | 备注 |
|-------|------|----------|------|
| `consumer:account:read` | 读取账户信息 | consumer_viewer+ | |
| `consumer:account:write` | 管理账户 | consumer_operator+ | |
| `consumer:apikey:create` | 创建API Key | consumer_operator+ | |
| `consumer:apikey:read` | 读取API Key | consumer_viewer+ | |
| `consumer:apikey:revoke` | 吊销API Key | consumer_operator+ | |
| `consumer:usage:read` | 读取使用量 | consumer_viewer+ | |
#### 3.3.5 Billing Scope（统一）
| Scope | 说明 | 授予角色 | user_type限定 |
|-------|------|----------|---------------|
| `billing:read` | 读取账单 | finops+, supply_finops+, consumer_viewer+ | 通过user_type区分数据范围 |
| `billing:write` | 修改账单设置 | org_admin | |
**说明**：
- 原有 `tenant:billing:read`、`supply:settlement:read`、`consumer:billing:read` 统一为 `billing:read`
- 通过 TokenClaims.user_type 字段限定数据范围：platform用户看租户账单，supply用户看供应结算，consumer用户看需求账单
- 原 scope 名称保留作为 deprecated alias
#### 3.3.6 Router Scope（网关转发）
| Scope | 说明 | 授予角色 |
|-------|------|----------|
| `router:invoke` | 调用模型 | 所有认证用户 |
| `router:model:list` | 列出可用模型 | viewer+ |
| `router:model:config` | 配置路由策略 | operator+ |
---
## 4. API 路由权限映射
### 4.1 Platform API
| API路径 | 方法 | 所需Scope | 所需角色 |
|---------|------|-----------|----------|
| `/api/v1/platform/info` | GET | `platform:read` | viewer+ |
| `/api/v1/platform/config` | GET | `platform:read` | viewer+ |
| `/api/v1/platform/config` | PUT | `platform:write` | operator+ |
| `/api/v1/platform/tenants` | GET | `tenant:read` | viewer+ |
| `/api/v1/platform/tenants` | POST | `tenant:write` | operator+ |
| `/api/v1/platform/audit/events` | GET | `platform:audit:read` | operator+ |
| `/api/v1/platform/audit/events/export` | POST | `platform:audit:export` | org_admin+ |
### 4.2 Supply API（与 SUP-004~SUP-008 保持一致）
| API路径 | 方法 | 所需Scope | 所需角色 |
|---------|------|-----------|----------|
| `/api/v1/supply/accounts` | GET | `supply:account:read` | supply_viewer+ |
| `/api/v1/supply/accounts` | POST | `supply:account:write` | supply_operator+ |
| `/api/v1/supply/accounts/:id` | PUT | `supply:account:write` | supply_operator+ |
| `/api/v1/supply/accounts/:id/verify` | POST | `supply:account:write` | supply_operator+ |
| `/api/v1/supply/packages` | GET | `supply:package:read` | supply_viewer+ |
| `/api/v1/supply/packages` | POST | `supply:package:write` | supply_operator+ |
| `/api/v1/supply/packages/:id/publish` | POST | `supply:package:publish` | supply_operator+ |
| `/api/v1/supply/packages/:id/offline` | POST | `supply:package:offline` | supply_operator+ |
| `/api/v1/supply/settlements` | GET | `billing:read` | supply_finops+ |
| `/api/v1/supply/settlements/withdraw` | POST | `supply:settlement:withdraw` | supply_admin |
| `/api/v1/supply/billing` | GET | `billing:read` | supply_finops+ |
**Deprecated Alias 说明**：
- `/api/v1/supplier/*` 路径仅作为历史兼容别名保留
- 新接口禁止使用 `/supplier` 前缀
- deprecated alias 响应体应包含 `deprecation_notice` 字段提示迁移
- S2 阶段评估 alias 下线时间
### 4.3 Consumer API
| API路径 | 方法 | 所需Scope | 所需角色 |
|---------|------|-----------|----------|
| `/api/v1/consumer/account` | GET | `consumer:account:read` | consumer_viewer+ |
| `/api/v1/consumer/account` | PUT | `consumer:account:write` | consumer_operator+ |
| `/api/v1/consumer/apikeys` | GET | `consumer:apikey:read` | consumer_viewer+ |
| `/api/v1/consumer/apikeys` | POST | `consumer:apikey:create` | consumer_operator+ |
| `/api/v1/consumer/apikeys/:id/revoke` | POST | `consumer:apikey:revoke` | consumer_operator+ |
| `/api/v1/consumer/usage` | GET | `consumer:usage:read` | consumer_viewer+ |
| `/api/v1/consumer/billing` | GET | `billing:read` | consumer_viewer+ |
### 4.4 Router API（网关调用）
| API路径 | 方法 | 所需Scope | 所需角色 |
|---------|------|-----------|----------|
| `/v1/chat/completions` | POST | `router:invoke` | 所有认证用户 |
| `/v1/completions` | POST | `router:invoke` | 所有认证用户 |
| `/v1/embeddings` | POST | `router:invoke` | 所有认证用户 |
| `/v1/models` | GET | `router:model:list` | viewer+ |
| `/api/v1/router/models` | GET | `router:model:list` | viewer+ |
| `/api/v1/router/policies` | GET | `router:model:config` | operator+ |
| `/api/v1/router/policies` | PUT | `router:model:config` | operator+ |
---
## 5. 数据模型扩展
### 5.1 Role 定义表（iam_roles）
```sql
CREATE TABLE iam_roles (
id BIGSERIAL PRIMARY KEY,
role_code VARCHAR(50) NOT NULL UNIQUE, -- super_admin, org_admin, operator, developer, finops, viewer
role_name VARCHAR(100) NOT NULL,
role_type VARCHAR(20) NOT NULL, -- platform, supply, consumer
parent_role_id BIGINT REFERENCES iam_roles(id), -- 继承关系
level INT NOT NULL DEFAULT 0, -- 权限层级
description TEXT,
is_active BOOLEAN DEFAULT TRUE,
-- 审计字段（符合 database_domain_model_and_governance v1 规范）
request_id VARCHAR(64), -- 请求追踪ID
created_ip INET, -- 创建者IP
updated_ip INET, -- 更新者IP
version INT DEFAULT 1, -- 乐观锁版本号
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE INDEX idx_iam_roles_code ON iam_roles(role_code);
CREATE INDEX idx_iam_roles_type ON iam_roles(role_type);
CREATE INDEX idx_iam_roles_request_id ON iam_roles(request_id);
```
### 5.2 Scope 定义表（iam_scopes）
```sql
CREATE TABLE iam_scopes (
id BIGSERIAL PRIMARY KEY,
scope_code VARCHAR(100) NOT NULL UNIQUE, -- platform:read, supply:account:write
scope_name VARCHAR(100) NOT NULL,
scope_type VARCHAR(50) NOT NULL, -- platform, supply, consumer, router
description TEXT,
is_active BOOLEAN DEFAULT TRUE,
-- 审计字段（符合 database_domain_model_and_governance v1 规范）
request_id VARCHAR(64), -- 请求追踪ID
created_ip INET, -- 创建者IP
updated_ip INET, -- 更新者IP
version INT DEFAULT 1, -- 乐观锁版本号
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE INDEX idx_iam_scopes_code ON iam_scopes(scope_code);
CREATE INDEX idx_iam_scopes_request_id ON iam_scopes(request_id);
```
### 5.3 角色-Scope 关联表（iam_role_scopes）
```sql
CREATE TABLE iam_role_scopes (
id BIGSERIAL PRIMARY KEY,
role_id BIGINT NOT NULL REFERENCES iam_roles(id),
scope_id BIGINT NOT NULL REFERENCES iam_scopes(id),
-- 审计字段（符合 database_domain_model_and_governance v1 规范）
request_id VARCHAR(64), -- 请求追踪ID
created_ip INET, -- 创建者IP
version INT DEFAULT 1, -- 乐观锁版本号
created_at TIMESTAMPTZ DEFAULT NOW(),
UNIQUE(role_id, scope_id)
);
CREATE INDEX idx_iam_role_scopes_role ON iam_role_scopes(role_id);
CREATE INDEX idx_iam_role_scopes_scope ON iam_role_scopes(scope_id);
CREATE INDEX idx_iam_role_scopes_request_id ON iam_role_scopes(request_id);
```
### 5.4 用户-角色关联表（iam_user_roles）
```sql
CREATE TABLE iam_user_roles (
id BIGSERIAL PRIMARY KEY,
user_id BIGINT NOT NULL,
role_id BIGINT NOT NULL REFERENCES iam_roles(id),
tenant_id BIGINT, -- 租户范围（NULL表示全局）
granted_by BIGINT,
granted_at TIMESTAMPTZ DEFAULT NOW(),
expires_at TIMESTAMPTZ, -- 角色过期时间
-- 审计字段（符合 database_domain_model_and_governance v1 规范）
request_id VARCHAR(64), -- 请求追踪ID
created_ip INET, -- 创建者IP
updated_ip INET, -- 更新者IP
version INT DEFAULT 1, -- 乐观锁版本号
created_at TIMESTAMPTZ DEFAULT NOW(),
updated_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE INDEX idx_iam_user_roles_user ON iam_user_roles(user_id);
CREATE INDEX idx_iam_user_roles_tenant ON iam_user_roles(tenant_id);
CREATE INDEX idx_iam_user_roles_request_id ON iam_user_roles(request_id);
CREATE UNIQUE INDEX idx_iam_user_roles_unique ON iam_user_roles(user_id, role_id, tenant_id);
```
### 5.5 扩展 Token Claims
```go
type TokenClaims struct {
jwt.RegisteredClaims
SubjectID string `json:"subject_id"` // 用户主体ID
Role string `json:"role"` // 主角色
Scope []string `json:"scope"` // 授权范围列表
TenantID int64 `json:"tenant_id"` // 租户ID
UserType string `json:"user_type"` // 用户类型: platform/supply/consumer
Permissions []string `json:"permissions"` // 细粒度权限列表
}
```
---
## 6. 中间件设计
### 6.1 扩展 ScopeRoleAuthzMiddleware
```go
// 扩展后的权限校验逻辑
type AuthzConfig struct {
// 路由-角色映射
RouteRolePolicies map[string]RolePolicy
// 路由-Scope映射
RouteScopePolicies map[string][]string
// 角色层级
RoleHierarchy map[string]int
}
type RolePolicy struct {
RequiredLevel int
RequiredRole string
RequiredScope []string
}
// 权限校验逻辑
func (m *AuthMiddleware) ScopeRoleAuthzMiddleware(requiredScope string) func(http.Handler) http.Handler {
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
claims, ok := r.Context().Value(tokenClaimsKey).(*TokenClaims)
if !ok {
writeAuthError(w, http.StatusUnauthorized, "AUTH_CONTEXT_MISSING", "")
return
}
// 1. Scope 校验
if requiredScope != "" && !containsScope(claims.Scope, requiredScope) {
m.emitAuditAndReject(r, w, "AUTH_SCOPE_DENIED", requiredScope, claims)
return
}
// 2. 角色层级校验（如果配置了角色要求）
if policy, exists := getRoutePolicy(r.URL.Path); exists {
if !checkRolePolicy(claims, policy) {
m.emitAuditAndReject(r, w, "AUTH_ROLE_DENIED", "", claims)
return
}
}
next.ServeHTTP(w, r)
})
}
}
```
### 6.2 新增角色层级中间件
```go
// RoleHierarchyMiddleware 角色层级校验中间件
// 用于需要特定角色层级的操作
func RoleHierarchyMiddleware(minLevel int) func(http.Handler) http.Handler {
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
claims := GetTokenClaims(r.Context())
if claims == nil {
writeAuthError(w, http.StatusUnauthorized, "AUTH_CONTEXT_MISSING", "")
return
}
if getRoleLevel(claims.Role) < minLevel {
writeAuthError(w, http.StatusForbidden, "AUTH_ROLE_LEVEL_DENIED",
fmt.Sprintf("required role level %d", minLevel))
return
}
next.ServeHTTP(w, r)
})
}
}
```
### 6.3 新增跨类型校验中间件
```go
// UserTypeMiddleware 用户类型校验中间件
// 用于区分 platform/supply/consumer 用户
func UserTypeMiddleware(allowedTypes ...string) func(http.Handler) http.Handler {
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
claims := GetTokenClaims(r.Context())
if claims == nil {
writeAuthError(w, http.StatusUnauthorized, "AUTH_CONTEXT_MISSING", "")
return
}
if !containsString(allowedTypes, claims.UserType) {
writeAuthError(w, http.StatusForbidden, "AUTH_USER_TYPE_DENIED",
fmt.Sprintf("allowed user types: %v", allowedTypes))
return
}
next.ServeHTTP(w, r)
})
}
}
```
---
## 7. 错误码扩展
| 错误码 | HTTP状态 | 说明 |
|--------|----------|------|
| `AUTH_SCOPE_DENIED` | 403 | Scope权限不足 |
| `AUTH_ROLE_DENIED` | 403 | 角色权限不足 |
| `AUTH_ROLE_LEVEL_DENIED` | 403 | 角色层级不足 |
| `AUTH_USER_TYPE_DENIED` | 403 | 用户类型不允许 |
| `AUTH_TENANT_MISMATCH` | 403 | 租户上下文不匹配 |
| `AUTH_RESOURCE_OWNER_DENIED` | 403 | 资源所有权校验失败 |
---
## 8. 审计事件扩展
| 事件名 | 说明 | 触发场景 |
|--------|------|----------|
| `role.assign` | 角色分配 | 给用户分配角色 |
| `role.revoke` | 角色吊销 | 吊销用户角色 |
| `role.scope.denied` | Scope权限拒绝 | Scope校验失败 |
| `role.hierarchy.denied` | 角色层级拒绝 | 角色层级校验失败 |
| `usertype.denied` | 用户类型拒绝 | 用户类型校验失败 |
---
## 9. API 契约更新
### 9.1 新增角色管理 API
#### GET /api/v1/iam/roles
获取角色列表
**响应：**
```json
{
"roles": [
{
"role_code": "org_admin",
"role_name": "组织管理员",
"role_type": "platform",
"level": 50,
"scopes": ["platform:read", "tenant:read", "tenant:write"]
}
]
}
```
#### POST /api/v1/iam/users/:userId/roles
分配角色给用户
**请求：**
```json
{
"role_code": "developer",
"tenant_id": 123,
"expires_at": "2026-12-31T23:59:59Z"
}
```
#### DELETE /api/v1/iam/users/:userId/roles/:roleCode
吊销用户角色
### 9.2 新增 Scope 查询 API
#### GET /api/v1/iam/scopes
获取所有可用Scope
---
## 10. 向后兼容方案
### 10.1 新旧层级映射表（与TOK-001对齐）
| TOK-001旧层级 | 旧角色代码 | 新角色代码 | 新层级 | 权限变化说明 |
|---------------|------------|------------|--------|--------------|
| 3 | admin | `super_admin` | 100 | 完全对应，平台最高权限 |
| 2 | owner | `supply_admin` | 40 | 权限范围明确为供应侧管理，不含平台运营权限 |
| 1 | viewer | `viewer` | 10 | 完全对应 |
**说明**：
- TOK-001 新角色体系（super_admin/org_admin/operator）专属于平台侧管理
- 原 owner 角色对应 supply_admin（供应侧管理员），职责边界清晰
- 层级数值用于优先级判断，新旧体系独立运作
### 10.2 现有角色映射
| 旧角色 | 新角色 | 说明 |
|--------|--------|------|
| `admin` | `super_admin` | 完全对应，层级100 |
| `owner` | `supply_admin` | 权限范围重新定义为供应侧，不含平台运营权限 |
| `viewer` | `viewer` | 完全对应，层级10 |
**权限边界变化说明**：
- 原 owner 可管理供应侧账号、套餐、结算（对应 supply_admin）
- 原 owner 不可执行平台级操作（由 org_admin/super_admin 专属）
- supply_admin(40) < org_admin(50) 是合理设计，因为 org_admin 管理范围更广
### 10.3 Token 兼容处理
```go
// RoleMapping 旧角色到新角色的映射
var RoleMapping = map[string]string{
"admin": "super_admin",
"owner": "supply_admin",
// viewer 保持不变
}
// 在Token验证时自动转换
func normalizeRole(role string) string {
if newRole, exists := RoleMapping[role]; exists {
return newRole
}
return role
}
```
---
## 11. 实施计划
### 11.1 Phase 1: 数据模型扩展
1. 创建 `iam_roles`, `iam_scopes`, `iam_role_scopes`, `iam_user_roles` 表
2. 初始化预定义角色和Scope数据
3. 提供数据迁移脚本
### 11.2 Phase 2: 中间件扩展
1. 扩展 `ScopeRoleAuthzMiddleware` 支持新角色层级
2. 新增 `RoleHierarchyMiddleware`
3. 新增 `UserTypeMiddleware`
4. 更新 Token Claims 结构
### 11.3 Phase 3: API 实现
1. 实现角色管理 API
2. 实现 Scope 查询 API
3. 更新现有 API 的权限校验
### 11.4 Phase 4: 向后兼容
1. 实现角色映射逻辑
2. 提供迁移指导文档
---
## 12. 验收标准
1. [ ] 角色层级清晰：super_admin > org_admin > operator/developer/finops > viewer
2. [ ] Scope权限校验正确：精确匹配路由与所需Scope
3. [ ] 继承关系正确：子角色自动继承父角色Scope
4. [ ] 向后兼容：现有 owner/viewer/admin 角色正常工作
5. [ ] 审计完整：角色变更和权限拒绝事件全量记录
6. [ ] API契约更新：新增角色管理API符合RESTful规范
---
## 13. 关联文档
- `docs/token_runtime_minimal_spec_v1.md`（TOK-001）
- `docs/token_auth_middleware_design_v1_2026-03-29.md`（TOK-002）
- `docs/llm_gateway_prd_v1_2026-03-25.md`
- `docs/database_domain_model_and_governance_v1_2026-03-27.md`
- `docs/api_naming_strategy_supply_vs_supplier_v1_2026-03-27.md`
---
**文档状态**：设计稿（待评审）
**下一步**：提交评审，根据反馈修订后进入实施阶段

280
docs/parallel_agent_output_quality_standards_v1_2026-04-02.md Normal file
View File

@@ -0,0 +1,280 @@
# 并行Agent产出质量规范 v1.0
> 版本：v1.0
> 日期：2026-04-02
> 适用范围：所有并行子Agent设计/调研任务
> 关联：`docs/project_experience_summary_v1_2026-04-02.md`
---
## 1. 背景与目的
### 1.1 问题发现
2026-04-02并行执行5个P1/P2设计任务，通过系统性评审发现以下共性问题：
| 问题类型 | 发现频次 | 代表问题 |
|----------|----------|----------|
| 与基线文档不一致 | 5/5 | 角色层级、评分权重、事件命名 |
| 数据模型缺审计字段 | 2/5 | 缺少request_id/version/created_ip |
| 指标边界模糊 | 2/5 | M-013~M-016指标重叠 |
| CI脚本缺失 | 1/5 | 引用的脚本未实现 |
| 实施周期高估 | 1/5 | 设计工期与实际偏差大 |
### 1.2 规范目的
确保未来并行Agent产出：
1. **内部一致性**：子Agent之间设计互不冲突
2. **外部一致性**：与PRD、架构、现有设计对齐
3. **可执行性**：设计可直接转化为代码和脚本
4. **可验证性**：有明确的验收标准和测试方法
---
## 2. 强制检查清单（Agent必须执行）
### 2.1 PRD对齐检查
| # | 检查项 | 通过标准 | 失败处理 |
|---|--------|----------|----------|
| P1 | 需求覆盖完整性 | 所有P1需求项都有对应设计 | 补充缺失需求 |
| P2 | 需求覆盖完整性 | 所有P2需求项都有调研/设计 | 标注待决策项 |
| R | 用户角色对齐 | 角色定义与PRD一致 | 对齐PRD定义 |
| M | 成功标准对齐 | 设计产出可验证成功标准 | 补充验收标准 |
**PRD基线文档**：
- `docs/llm_gateway_prd_v1_2026-03-25.md`
- `docs/supply_button_level_prd_v1_2026-03-25.md`
### 2.2 P0设计一致性检查
| # | 检查项 | 通过标准 | 失败处理 |
|---|--------|----------|----------|
| T | Token体系一致 | 角色层级兼容TOK-001/TOK-002 | 明确继承关系 |
| A | 审计事件一致 | 事件命名与TOK-002/XR-001一致 | 复用现有事件 |
| D | 数据模型一致 | 遵循database_domain_model_and_governance | 补充必需字段 |
| I | API命名一致 | 遵循api_naming_strategy | 使用标准前缀 |
| M | 指标定义一致 | M-013~M-021定义不变 | 引用现有定义 |
**P0设计基线文档**：
- `docs/token_auth_middleware_design_v1_2026-03-29.md`
- `docs/supply_technical_design_enhanced_v1_2026-03-25.md`
- `docs/database_domain_model_and_governance_v1_2026-03-27.md`
- `docs/api_naming_strategy_supply_vs_supplier_v1_2026-03-27.md`
### 2.3 跨文档一致性检查
| # | 检查项 | 通过标准 | 失败处理 |
|---|--------|----------|----------|
| C1 | 与同时产出文档一致 | 事件命名、数据结构互不冲突 | 协调统一 |
| C2 | 与已有文档一致 | 不引入冲突的设计 | 对齐现有设计 |
| C3 | 指标边界清晰 | M-013~M-016无重叠 | 明确边界 |
**已有设计文档**：
- `docs/routing_strategy_template_design_v1_2026-04-02.md`
- `docs/audit_log_enhancement_design_v1_2026-04-02.md`
- `docs/multi_role_permission_design_v1_2026-04-02.md`
- `docs/compliance_capability_package_design_v1_2026-04-02.md`
- `docs/sso_saml_technical_research_v1_2026-04-02.md`
### 2.4 可执行性检查
| # | 检查项 | 通过标准 | 失败处理 |
|---|--------|----------|----------|
| E1 | 引用的脚本已实现 | CI/CD脚本实际存在 | 实现或标注待开发 |
| E2 | 实施周期合理 | 设计工期与历史数据偏差<30% | 修正估算 |
| E3 | 验收标准明确 | 每项设计有可测试的验收标准 | 补充验收条件 |
### 2.5 行业最佳实践检查
| # | 检查项 | 通过标准 | 失败处理 |
|---|--------|----------|----------|
| B1 | 安全加固 | 遵循OWASP Top 10 | 补充安全考虑 |
| B2 | 错误处理 | 错误码体系完整 | 对齐现有错误码 |
| B3 | 可观测性 | 日志/指标/追踪完备 | 补充观测设计 |
---
## 3. 文档结构模板
### 3.1 设计文档结构
```markdown
# {设计标题}
> 版本：v1.0
> 日期：YYYY-MM-DD
> 状态：[Draft/Review/Approved/Frozen]
> 依赖：{关联文档列表}
## 1. 背景与目标
## 2. 与PRD对齐性
## 3. 与P0设计一致性
## 4. 详细设计
## 5. 数据模型（如需）
## 6. API设计（如需）
## 7. CI/CD集成（如需）
## 8. 验收标准
## 9. 实施计划
## 10. 风险与缓解
## 11. 附录
```
### 3.2 评审报告结构
```markdown
# {被评审文档}评审报告
> 评审日期：YYYY-MM-DD
> 评审结论：[{GO/CONDITIONAL GO/NO-GO}]
## 1. PRD对齐性
## 2. P0设计一致性
## 3. 跨文档一致性
## 4. 可执行性
## 5. 行业最佳实践
## 6. 问题清单（按严重度）
## 7. 改进建议
## 8. 最终结论
```
---
## 4. Agent执行协议
### 4.1 任务启动阶段
1. **读取基线**（强制）：
- PRD v1
- 相关的P0设计文档
- 同时期并行的其他Agent产出（通过文件列表）
2. **检查一致性**（强制）：
- 执行第2章的强制检查清单
- 记录发现的不一致项
3. **明确范围**（强制）：
- 在文档中明确声明依赖的基线文档
- 标注需要协调的跨文档问题
### 4.2 任务执行阶段
1. **保持一致性**：
- 复用现有事件命名、数据结构
- 不发明新的指标定义
- 不引入与现有设计的冲突
2. **记录假设**：
- 任何基于假设的设计必须明确标注
- 假设需有事实依据或行业实践支持
3. **预留接口**：
- 与其他模块交互的接口必须抽象清晰
- 便于后续集成
### 4.3 任务交付阶段
1. **自检**：
- 对照检查清单逐项确认
- 确保没有遗漏
2. **产出完整**：
- 设计文档
- 评审报告（如有）
- 评审发现汇总
---
## 5. 评审触发条件
### 5.1 必须评审
- 所有P1/P2设计文档
- 所有API契约变更
- 所有数据模型变更
### 5.2 评审维度
| 维度 | 权重 | 说明 |
|------|------|------|
| PRD对齐 | 25% | 是否覆盖需求 |
| P0一致性 | 30% | 是否与基线一致 |
| 可执行性 | 25% | 是否可实现 |
| 最佳实践 | 20% | 质量是否达标 |
### 5.3 评审结论
| 结论 | 含义 | 处理 |
|------|------|------|
| GO | 通过，可实施 | 进入下一阶段 |
| CONDITIONAL GO | 有条件通过，需修复后实施 | 修复指定问题 |
| NO-GO | 不通过，需重新设计 | 重新设计 |
---
## 6. 常见问题与修复指南
### 6.1 角色层级冲突
**问题**：与TOK-001/TOK-002角色定义不一致
**修复**：
```text
1. 引用TOK-001的角色层级作为基础
2. P1扩展角色需明确继承关系
3. 冲突时以TOK-001为准
```
### 6.2 审计事件命名冲突
**问题**：与TOK-002/XR-001事件命名不一致
**修复**：
```text
1. 复用现有事件命名格式：domain.action.result
2. 不发明新的事件类型
3. 冲突时以TOK-002为准
```
### 6.3 指标边界模糊
**问题**：M-013~M-016指标重叠
**修复**：
```text
M-013: 凭证暴露事件（credential_exposed=1）
M-014: 凭证入站覆盖率（ingress_credential_count/total_request）
M-015: 直连绕过事件（direct_call_attempted=1）
M-016: query_key拒绝率（query_key_rejected_count/total_query_key_request）
```
### 6.4 实施周期高估
**问题**：设计工期与实际偏差>50%
**修复**：
```text
参考历史数据：
- P0开发：3人月
- P1单模块：1-2人月
- P2调研：0.5-1人月
- CI脚本：0.25-0.5人月
```
---
## 7. 附录
### 7.1 基线文档索引
| 文档 | 路径 | 用途 |
|------|------|------|
| PRD v1 | docs/llm_gateway_prd_v1_2026-03-25.md | 需求基线 |
| 供应技术设计 | docs/supply_technical_design_enhanced_v1_2026-03-25.md | XR-001基线 |
| Token中间件 | docs/token_auth_middleware_design_v1_2026-03-29.md | 认证基线 |
| 数据库模型 | docs/database_domain_model_and_governance_v1_2026-03-27.md | 数据模型基线 |
| API命名策略 | docs/api_naming_strategy_supply_vs_supplier_v1_2026-03-27.md | 命名基线 |
| ToS合规引擎 | docs/tos_compliance_engine_design_v1_2026-03-18.md | 合规基线 |
### 7.2 M-013~M-021指标定义
| 指标 | 定义 | 计算公式 |
|------|------|----------|
| M-013 | supplier_credential_exposure_events | COUNT(event_type='credential_exposed') |
| M-014 | platform_credential_ingress_coverage_pct | SUM(has_ingress_credential)/COUNT(*)*100 |
| M-015 | direct_supplier_call_by_consumer_events | COUNT(event_type='direct_call_attempted') |
| M-016 | query_key_external_reject_rate_pct | SUM(query_key_rejected)/SUM(query_key_request)*100 |
| M-017 | dependency_compat_audit_pass_pct | PASS/total*100 |
---
**文档状态**：生效
**下次审查**：2026-04-15或下一个并行任务周期
**维护责任人**：项目架构组

317
docs/plans/2026-04-02-p1-p2-tdd-execution-plan-v1.md Normal file
View File

@@ -0,0 +1,317 @@
# 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 | - |
---
**文档状态**：执行计划
**下次更新**：每日进度报告
**维护责任人**：项目开发组

386
docs/project_experience_summary_v1_2026-04-02.md Normal file
View File

@@ -0,0 +1,386 @@
# 立交桥项目P0阶段经验总结
> 文档日期：2026-04-02
> 项目阶段：P0 → P1/P2并行
> 文档类型：经验总结与规范固化
---
## 一、项目概述
### 1.1 项目背景
立交桥项目（LLM Gateway）是一个多租户AI模型网关平台，连接AI应用开发者与模型供应商，提供统一的认证、路由、计费和合规能力。
### 1.2 核心模块
| 模块 | 技术栈 | 职责 |
|------|--------|------|
| gateway | Go | 请求路由、认证中间件、限流 |
| supply-api | Go | 供应链API、账户/套餐/结算管理 |
| platform-token-runtime | Go | Token生命周期管理 |
### 1.3 项目时间线
| 里程碑 | 日期 | 状态 |
|---------|------|------|
| Round-1: 架构与替换路径评审 | 2026-03-19 | CONDITIONAL GO |
| Round-2: 兼容与计费一致性评审 | 2026-03-22 | CONDITIONAL GO |
| Round-3: 安全与合规攻防评审 | 2026-03-25 | CONDITIONAL GO |
| Round-4: 可靠性与回滚演练评审 | 2026-03-29 | CONDITIONAL GO |
| P0阶段开发完成 | 2026-03-31 | DONE |
| P0 Staging验证 | 2026-04-XX | BLOCKED |
---
## 二、Superpowers执行框架
### 2.1 框架概述
项目采用Superpowers执行框架进行规范化开发管理，通过工作流分组、证据链驱动、门禁检查确保质量和可追溯性。
### 2.2 工作流分组
| 工作流 | 状态 | 说明 |
|--------|------|------|
| WG-A 需求冻结 | DONE | 需求冻结与决议映射 |
| WG-B 契约对齐 | DONE | OpenAPI契约与幂等头 |
| WG-C 测试矩阵 | DONE | 路径一致化与规则文档 |
| WG-D 真实联调 | BLOCKED | 缺真实staging环境 |
| WG-E 报告签署 | BLOCKED | 依赖WG-D |
| WG-F 一致性收尾 | DONE | 命名策略与映射补齐 |
| WG-G 全局校验 | DONE | 校验链路可执行 |
### 2.3 门禁体系
#### 2.3.1 门禁层级
| 门禁类型 | 触发条件 | 检查内容 |
|----------|----------|----------|
| Pre-Commit | 每次commit | lint, format, 单元测试 |
| Build Gate | 每次构建 | 集成测试, 依赖检查 |
| Stage Gate | 发布前 | 完整功能验证 |
| Release Gate | 正式发布 | 安全扫描, 合规检查 |
#### 2.3.2 核心指标（M-013~M-021）
| 指标ID | 指标名 | 目标值 | 状态 |
|--------|--------|--------|------|
| M-013 | supplier_credential_exposure_events | =0 | ⚠️ 待staging |
| M-014 | platform_credential_ingress_coverage_pct | =100% | ⚠️ 待staging |
| M-015 | direct_supplier_call_by_consumer_events | =0 | ⚠️ 待staging |
| M-016 | query_key_external_reject_rate_pct | =100% | ⚠️ 待staging |
| M-017 | dependency_compat_audit_pass_pct | =100% | ✅ 通过 |
| M-021 | token_runtime_readiness_pct | =100% | ⚠️ 待staging |
### 2.4 脚本流水线
| 脚本 | 用途 |
|------|------|
| `scripts/ci/staging_release_pipeline.sh` | Staging发布流水线 |
| `scripts/ci/superpowers_release_pipeline.sh` | Superpowers门禁汇总 |
| `scripts/ci/minimax_upstream_trend_report.sh` | 上游趋势监控 |
| `scripts/ci/staging_real_readiness_check.sh` | 真实STG就绪度检查 |
| `scripts/ci/audit_metrics_gate.sh` | 审计指标门禁 |
---
## 三、文档治理规范
### 3.1 文档命名规范
```
{类别}_{文档名}_{版本}_{日期}.md
```
| 类别前缀 | 含义 | 示例 |
|----------|------|------|
| `llm_gateway_` | 产品级文档 | llm_gateway_prd |
| `technical_` | 技术设计 | technical_architecture |
| `api_` | API契约 | api_naming_strategy |
| `security_` | 安全相关 | security_solution |
| `compliance_` | 合规相关 | tos_compliance_engine |
| `router_` | 路由相关 | router_core_takeover |
| `supply_` | 供应链相关 | supply_technical_design |
| `token_` | Token相关 | token_auth_middleware |
| `test_plan_` | 测试计划 | test_plan_design |
| `s0_`/ `s4_` | 阶段验收 | s0_wbs_detailed |
### 3.2 文档目录结构
```
docs/
├── llm_gateway_*.md # 产品级文档
├── technical_*.md # 技术架构
├── api_*.md / *.yaml # API契约
├── router_*.md # 路由核心
├── supply_*.md # 供应链
├── token_*.md # Token认证
├── security_*.md # 安全方案
├── compliance_*.md # 合规方案
├── test_plan_*.md # 测试计划
├── product/ # 产品决策
│ └── *_pending_to_decision_map_*.md
└── plans/ # 执行计划
└── *superpowers-execution-tasklist*.md
```
### 3.3 报告目录结构
```
reports/
├── alignment_validation_checkpoint_*.md # 对齐验证检查点
├── dependency/ # 依赖兼容性
│ ├── lockfile_diff_*.md
│ ├── compat_matrix_*.md
│ └── risk_register_*.md
├── gates/ # 门禁报告
│ ├── superpowers_stage_validation_*.md
│ ├── superpowers_release_pipeline_*.md
│ ├── final_decision_consistency_*.md
│ └── token_runtime_readiness_*.md
└── *_review_*.md # 评审报告
```
### 3.4 评审流程
| 评审轮次 | 主题 | 周期 | 产出 |
|----------|------|------|------|
| Round-1 | 架构与替换路径 | 单次 | CONDITIONAL GO |
| Round-2 | 兼容与计费一致性 | 单次 | CONDITIONAL GO |
| Round-3 | 安全与合规攻防 | 单次 | CONDITIONAL GO |
| Round-4 | 可靠性与回滚演练 | 单次 | CONDITIONAL GO |
| 每日Review | 每日检查 | 每日 | daily_review_YYYY-MM-DD.md |
---
## 四、代码组织规范
### 4.1 Gateway目录结构
```
gateway/
├── cmd/gateway/main.go
├── internal/
│ ├── adapter/ # 适配器（OpenAI等）
│ ├── alert/ # 告警
│ ├── config/ # 配置
│ ├── handler/ # HTTP处理器
│ ├── middleware/ # 中间件（认证、限流）
│ ├── ratelimit/ # 限流
│ └── router/ # 路由
└── pkg/ # 公共包
```
### 4.2 Supply-API目录结构
```
supply-api/
├── cmd/supply-api/main.go
├── internal/
│ ├── audit/ # 审计
│ ├── cache/ # 缓存
│ ├── config/ # 配置
│ ├── domain/ # 领域模型
│ ├── httpapi/ # HTTP API
│ ├── middleware/ # 中间件
│ ├── repository/ # 仓储
│ └── storage/ # 存储
├── sql/ # 数据库脚本
└── scripts/ # 运维脚本
```
### 4.3 API命名策略
参考 `docs/api_naming_strategy_supply_vs_supplier_v1_2026-03-27.md`：
| 规则 | 说明 |
|------|------|
| 平台视角 | supply_*, consumer_* |
| 供应商视角 | supplier_* |
| 动词 | create, read, update, delete, publish |
| 版本 | /api/v1/前缀 |
---
## 五、经验教训
### 5.1 成功经验
#### 5.1.1 证据链驱动
- 所有结论必须附带证据（报告、日志、截图）
- 脚本返回码+报告双重校验
- Checkpoint机制确保逐步验证
#### 5.1.2 分层验证策略
```
local/mock → staging → production
```
- local/mock用于开发验证
- staging用于真实环境验证
- 两者结果不可混用
#### 5.1.3 并行任务拆分
- P0阻塞时识别P1/P2可并行任务
- 5个Agent并行执行提升效率
- 减少等待浪费
#### 5.1.4 规范前置
- 文档命名、目录结构规范提前固化
- 避免后期混乱
- 新人可快速定位文档
### 5.2 待改进项
#### 5.2.1 环境就绪预估不足
- F-01（staging DNS可达性）预估偏乐观
- 应预留更多buffer时间
#### 5.2.2 外部依赖管理
- 真实staging地址依赖外部团队
- 缺少Plan B
#### 5.2.3 指标量化
- M-006/M-007/M-008 takeover率指标
- 缺少实时监控大盘
---
## 六、P1/P2并行任务总结
### 6.1 本次并行产出（2026-04-02）
| 任务 | 产出文档 | 评审结论 | 关键问题数 |
|------|----------|----------|------------|
| P1: 多角色权限设计 | multi_role_permission_design_v1_2026-04-02.md | CONDITIONAL GO | 5 |
| P1: 审计日志增强 | audit_log_enhancement_design_v1_2026-04-02.md | CONDITIONAL GO | 6 |
| P1: 路由策略模板设计 | routing_strategy_template_design_v1_2026-04-02.md | CONDITIONAL GO | 5 |
| P2: SSO/SAML调研 | sso_saml_technical_research_v1_2026-04-02.md | CONDITIONAL GO | 4 |
| P2: 合规能力包设计 | compliance_capability_package_design_v1_2026-04-02.md | CONDITIONAL GO | 7 |
### 6.2 评审发现共性问题
| 问题类型 | 发现频次 | 代表问题 |
|----------|----------|----------|
| 与P0设计不一致 | 5/5 | 角色层级、评分权重、事件命名 |
| 数据模型缺审计字段 | 2/5 | 缺少request_id/version/created_ip |
| 指标边界模糊 | 2/5 | M-013~M-016指标重叠 |
| CI脚本缺失 | 1/5 | 引用的脚本未实现 |
| 实施周期高估 | 1/5 | 设计工期与实际偏差大 |
### 6.3 修复行动项
| 优先级 | 任务 | 负责Agent | 截止日期 |
|--------|------|-----------|----------|
| P0 | 统一事件命名体系（audit_log + compliance） | 审计+合规Agent协调 | 2026-04-05 |
| P0 | 补充缺失的审计字段（request_id/version/ip） | 权限+审计Agent | 2026-04-05 |
| P1 | 明确M-013~M-016指标边界 | 审计Agent | 2026-04-07 |
| P1 | 补充CI脚本实现（compliance_gate.sh） | 合规Agent | 2026-04-07 |
| P1 | 锁定评分模型默认权重 | 路由Agent | 2026-04-07 |
| P2 | 补充Azure AD评估 | SSO调研Agent | 2026-04-10 |
### 6.4 并行Agent产出质量规范
参见 `docs/parallel_agent_output_quality_standards_v1_2026-04-02.md`
**核心要求**：
1. 启动阶段必须读取PRD+P0基线文档
2. 执行阶段必须检查跨文档一致性
3. 交付阶段必须执行强制检查清单
### 6.5 修复验证结果（2026-04-02）
| 文档 | 修复问题数 | 验证状态 |
|------|------------|----------|
| 多角色权限设计 | 5 | ✅ 全部通过 |
| 审计日志增强 | 6 | ✅ 全部通过 |
| 路由策略模板 | 5 | ✅ 全部通过 |
| SSO/SAML调研 | 4 | ✅ 全部通过 |
| 合规能力包 | 7 | ✅ 全部通过 |
| 跨文档一致性 | 3 | ✅ 全部通过 |
**修复验证报告**：`reports/review/fix_verification_report_2026-04-02.md`
### 6.6 TDD开发执行（2026-04-02）
| 模块 | 任务数 | 测试数 | 状态 |
|------|--------|--------|------|
| IAM模块 | 8个 | 111个 | ✅ 完成 |
| 审计日志模块 | 8个 | 40+个 | ✅ 完成 |
| 路由策略模块 | 9个 | 33+个 | ✅ 完成 |
**执行规范**：Superpowers + TDD (红-绿-重构)
**TDD执行报告**：`reports/tdd_execution_summary_2026-04-02.md`
### 6.7 全面质量验证（2026-04-02）
**验证结论：GO（全部通过）**
| 验证维度 | 验证项 | 状态 |
|----------|--------|------|
| PRD对齐性 | P1/P2需求完整覆盖 | ✅ |
| P0设计一致性 | 角色层级、审计事件、数据模型、API命名 | ✅ |
| 跨文档一致性 | 事件命名格式、指标定义统一 | ✅ |
| 生产级质量 | 验收标准、可执行测试、错误处理、安全加固 | ✅ |
**全面验证报告**：`reports/review/full_verification_report_2026-04-02.md`
### 6.6 后续行动项
| 优先级 | 任务 | 状态 |
|--------|------|------|
| P0 | staging环境验证 | BLOCKED |
| P1 | IAM模块集成测试 | ✅ TDD完成 |
| P1 | 审计日志模块集成测试 | ✅ TDD完成 |
| P1 | 路由策略模块集成测试 | ✅ TDD完成 |
| P2 | 合规能力包CI脚本开发 | TODO |
| P2 | SSO方案选型（Casdoor MVP） | ✅ 设计已就绪 |
---
## 七、附录
### 7.1 关键文档索引
| 文档 | 路径 |
|------|------|
| PRD | docs/llm_gateway_prd_v1_2026-03-25.md |
| 技术架构 | docs/technical_architecture_design_v1_2026-03-18.md |
| API契约 | docs/supply_api_contract_openapi_draft_v1_2026-03-25.yaml |
| Token认证 | docs/token_auth_middleware_design_v1_2026-03-29.md |
| 安全方案 | docs/security_solution_v1_2026-03-18.md |
| 合规引擎 | docs/tos_compliance_engine_design_v1_2026-03-18.md |
| 追踪矩阵 | docs/supply_traceability_matrix_generation_rules_v1_2026-03-27.md |
| **并行Agent质量规范** | docs/parallel_agent_output_quality_standards_v1_2026-04-02.md |
| **项目经验总结** | docs/project_experience_summary_v1_2026-04-02.md |
| **P1/P2 TDD执行计划** | docs/plans/2026-04-02-p1-p2-tdd-execution-plan-v1.md |
| **TDD执行总结** | reports/tdd_execution_summary_2026-04-02.md |
### 7.2 评审报告索引
| 评审文档 | 路径 |
|----------|------|
| 多角色权限设计评审 | reports/review/multi_role_permission_design_review_2026-04-02.md |
| 审计日志增强设计评审 | reports/review/audit_log_enhancement_design_review_2026-04-02.md |
| 路由策略模板设计评审 | reports/review/routing_strategy_template_design_review_2026-04-02.md |
| SSO/SAML调研评审 | reports/review/sso_saml_technical_research_review_2026-04-02.md |
| 合规能力包设计评审 | reports/review/compliance_capability_package_design_review_2026-04-02.md |
| **修复验证报告** | reports/review/fix_verification_report_2026-04-02.md |
| **全面质量验证报告** | reports/review/full_verification_report_2026-04-02.md |
### 7.2 术语表
| 术语 | 含义 |
|------|------|
| Superpowers | 项目执行的规范化框架 |
| WG | Work Group，工作组 |
| Gate | 门禁检查点 |
| Takeover | 路由接管（绕过直连） |
| SBOM | Software Bill of Materials，软件物料清单 |
| TOK | Token生命周期 |
| SUP | Supply链路（供应链） |
---
**文档状态**：已更新至v2（添加全面质量验证结果）
**下次更新**：P0 Staging验证完成后
**维护责任人**：项目架构组

1700
docs/routing_strategy_template_design_v1_2026-04-02.md Normal file
View File

File diff suppressed because it is too large Load Diff

1106
docs/sso_saml_technical_research_v1_2026-04-02.md Normal file
View File

File diff suppressed because it is too large Load Diff