feat: sync lijiaoqiao implementation and staging validation artifacts
This commit is contained in:
Your Name
@@ -1,7 +1,7 @@
|
||||
# 唯一验收门禁表（Single Source of Truth）
|
||||
|
||||
- 版本：v1.1
|
||||
- 日期：2026-03-24
|
||||
- 版本：v1.2
|
||||
- 日期：2026-03-27
|
||||
- 状态：生效
|
||||
- 用途：统一 S0/S1/S2 的验收阈值、判定逻辑与阻断动作，消除多文档阈值漂移。
|
||||
|
||||
@@ -35,12 +35,19 @@
|
||||
| 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` | 外部 query key 被拒绝数/外部 query key 请求总数 | =100% | <100% | 网关拦截日志 |
|
||||
| M-017 | `dependency_compat_audit_pass_pct` | 依赖版本兼容审计通过项/应审计项 | =100% | <100% | 依赖审计报告 |
|
||||
| M-018 | `stage_quality_gate_pass_pct` | 分阶段质量门禁通过项/应通过项 | =100% | <100% | CI Gate 报告 |
|
||||
| M-019 | `requirement_traceability_coverage_pct` | 已追踪需求数/应追踪需求数 | =100% | <100% | 追踪矩阵 |
|
||||
| M-020 | `escaped_p0_defects_count` | 生产放出后 P0 缺陷数 | =0 | >0 | 生产事故平台 |
|
||||
| M-021 | `token_runtime_readiness_pct` | token 运行态必备能力已实现项/应实现项 | =100% | <100% | TOK 验收报告 |
|
||||
|
||||
口径补充：
|
||||
1. 主路径端点集合固定为 `/v1/chat/completions`、`/v1/messages`、`/v1/responses`、`/v1beta/*`。
|
||||
2. `/responses` 等 alias 入口必须在 Ingress 归一后再统计。
|
||||
3. 国内平台分类来源固定为配置表 `gateway_cn_platforms`，禁止 SQL 硬编码。
|
||||
4. 需求方仅可使用平台签发凭证访问平台入口，禁止获取供应方上游凭证。
|
||||
5. 依赖兼容审计口径固定为“SBOM + 锁文件差异 + 兼容矩阵 + 风险清单”四件套，缺一视为未通过。
|
||||
6. 分阶段质量门禁固定为 G0/G1/G2/G3/G4/G5，禁止跳阶段放行。
|
||||
|
||||
---
|
||||
|
||||
@@ -58,17 +65,19 @@
|
||||
| Gate ID | 场景 | 必达条件 | 不通过动作 | 责任人 |
|
||||
|---|---|---|---|---|
|
||||
| G-S1-1 | 灰度7天上线门禁 | M-001>=99.9%，M-004<=0.1%，30分钟内回滚演练通过 | 不得升至全量；维持灰度并整改 | 平台+SRE |
|
||||
| G-S1-2 | 发布前兼容门禁 | Schema/Behavior/Performance 三重Gate全部通过 | 阻断发布 | 架构+QA |
|
||||
| G-S1-2 | 发布前兼容门禁 | Schema/Behavior/Performance 三重Gate全部通过，且 M-017=100% | 阻断发布 | 架构+QA |
|
||||
| G-S1-3 | 凭证边界门禁 | M-013=0，M-014=100%，M-016=100% | 阻断发布并触发安全复盘 | 安全+平台 |
|
||||
| G-S1-4 | 分阶段质量门禁 | M-018=100%，M-019=100% | 阻断发布并回到失败阶段整改 | 架构+QA+PMO |
|
||||
| G-S1-5 | token 运行态门禁 | M-021=100% | 阻断发布并冻结 SUP 升波 | 架构+安全+平台 |
|
||||
|
||||
### 3.3 S2 阶段门禁（替换核心）
|
||||
|
||||
| Gate ID | 阶段 | 必达条件 | 升波条件 | 阻断条件 | 不通过动作 |
|
||||
|---|---|---|---|---|---|
|
||||
| G-S2-A | 10% | M-001>=99.9%，M-002<=60，M-010>=99%，M-004<=0.1%，M-009>=95%，M-014=100% | 连续2周达标 | 任一红线触发 | 回切 subapi，修复后重试 |
|
||||
| G-S2-B | 30% | M-001>=99.95%，M-003<=100，M-009>=97%，M-014=100% | 连续2周达标 | M-004>0.1% 或 P0事故 | 暂停升波，补救后复核 |
|
||||
| G-S2-C1 | 40%中间检查点 | M-001>=99.95%，M-002<=60，M-003<=100，M-010>=99.5%，M-004<=0.1%，M-009>=97%，M-013=0，M-014=100%，M-015=0 | GO/CONDITIONAL GO | 任一红灯阈值 | 决策会：继续/附条件继续/回滚 |
|
||||
| G-S2-C2 | 60%终验 | M-006>=60%，M-007=100%，M-004<=0.1%，M-005<=0.01%，M-008>=99.9%，M-001>=99.95%，M-013=0，M-014=100%，M-015=0，M-016=100% | 通过后S2完成 | 任一硬门槛不满足 | 延长S2并冻结升波，不降终验目标 |
|
||||
| G-S2-A | 10% | M-001>=99.9%，M-002<=60，M-010>=99%，M-004<=0.1%，M-009>=95%，M-014=100%，M-017=100%，M-018=100%，M-021=100% | 连续2周达标 | 任一红线触发 | 回切 subapi，修复后重试 |
|
||||
| G-S2-B | 30% | M-001>=99.95%，M-003<=100，M-009>=97%，M-014=100%，M-017=100%，M-021=100% | 连续2周达标 | M-004>0.1% 或 P0事故 | 暂停升波，补救后复核 |
|
||||
| G-S2-C1 | 40%中间检查点 | M-001>=99.95%，M-002<=60，M-003<=100，M-010>=99.5%，M-004<=0.1%，M-009>=97%，M-013=0，M-014=100%，M-015=0，M-018=100%，M-019=100%，M-021=100% | GO/CONDITIONAL GO | 任一红灯阈值 | 决策会：继续/附条件继续/回滚 |
|
||||
| G-S2-C2 | 60%终验 | M-006>=60%，M-007=100%，M-004<=0.1%，M-005<=0.01%，M-008>=99.9%，M-001>=99.95%，M-013=0，M-014=100%，M-015=0，M-016=100%，M-017=100%，M-018=100%，M-019=100%，M-020=0，M-021=100% | 通过后S2完成 | 任一硬门槛不满足 | 延长S2并冻结升波，不降终验目标 |
|
||||
|
||||
---
|
||||
|
||||
@@ -84,6 +93,9 @@
|
||||
6. `supplier_credential_exposure_events > 0`。
|
||||
7. `direct_supplier_call_by_consumer_events > 0`。
|
||||
8. `platform_credential_ingress_coverage_pct < 100%` 或 `query_key_external_reject_rate_pct < 100%`。
|
||||
9. `dependency_compat_audit_pass_pct < 100%`。
|
||||
10. `stage_quality_gate_pass_pct < 100%` 或 `requirement_traceability_coverage_pct < 100%`。
|
||||
11. `token_runtime_readiness_pct < 100%`。
|
||||
|
||||
处理动作：
|
||||
1. 立即停止升波。
|
||||
|
||||
23
docs/api_naming_strategy_supply_vs_supplier_v1_2026-03-27.md
Normal file
23
docs/api_naming_strategy_supply_vs_supplier_v1_2026-03-27.md
Normal file
@@ -0,0 +1,23 @@
|
||||
# API 命名策略：`/supply` vs `/supplier`（v1.0）
|
||||
|
||||
- 日期：2026-03-27
|
||||
- 决策类型：命名规范与兼容策略
|
||||
- 适用范围：供应侧控制台与平台账务相关 API
|
||||
|
||||
## 1. 决策
|
||||
|
||||
1. 规范主路径统一采用：`/api/v1/supply/*`。
|
||||
2. 历史兼容路径 `/api/v1/supplier/*` 保留为 alias，并标记 `deprecated`。
|
||||
3. 新增接口禁止使用 `/supplier` 前缀。
|
||||
|
||||
## 2. 兼容策略
|
||||
|
||||
1. 别名路径只做兼容，不扩展新字段。
|
||||
2. 响应体增加迁移提示字段（如 `deprecation_notice`）或在文档标注迁移窗口。
|
||||
3. S2 阶段评估 alias 下线时间，提前至少一个版本公告。
|
||||
|
||||
## 3. 验收标准
|
||||
|
||||
1. OpenAPI 同时存在 canonical 路径与 alias 路径声明。
|
||||
2. alias 路径标记 `deprecated: true`。
|
||||
3. 追踪矩阵 `api_alias` 字段可定位所有 alias 使用点。
|
||||
128
docs/database_domain_model_and_governance_v1_2026-03-27.md
Normal file
128
docs/database_domain_model_and_governance_v1_2026-03-27.md
Normal file
@@ -0,0 +1,128 @@
|
||||
# 数据库跨域模型与治理基线（v1.0）
|
||||
|
||||
- 版本：v1.0
|
||||
- 日期：2026-03-27
|
||||
- 状态：生效（数据库设计 SSOT 补丁）
|
||||
- 适用范围：S0-S2 执行与验收
|
||||
- 关联文档：
|
||||
- `docs/llm_gateway_prd_v1_2026-03-25.md`
|
||||
- `docs/supply_technical_design_enhanced_v1_2026-03-25.md`
|
||||
- `docs/technical_architecture_optimized_v2_2026-03-18.md`
|
||||
- `sql/postgresql/supply_schema_v1.sql`
|
||||
- `sql/postgresql/supply_schema_v1_patch_2026-03-27.sql`
|
||||
- `sql/postgresql/platform_core_schema_v1.sql`
|
||||
|
||||
---
|
||||
|
||||
## 1. 本次补齐的缺口
|
||||
|
||||
1. 仅有 `supply_*` 表，缺少 PRD P0/P1 的核心域（租户/项目/鉴权 key/账务总账/审计事件）。
|
||||
2. 供应域缺少统一加密元数据字段，无法审计算法、KMS Key 版本与轮换状态。
|
||||
3. 缺少统一单位字段（quota/cost/amount unit），跨域统计口径不稳定。
|
||||
4. 审计字段不完整（request_id、trace_id、IP、operator、version）。
|
||||
5. 索引以单列为主，未覆盖高频组合查询（租户+状态+时间）。
|
||||
|
||||
---
|
||||
|
||||
## 2. 最小跨域表模型（按 PRD P0/P1）
|
||||
|
||||
| 域 | 表 | 说明 |
|
||||
|---|---|---|
|
||||
| Core | `core_tenants` | 组织/租户主实体 |
|
||||
| Core | `core_projects` | 项目/成本归因单元 |
|
||||
| IAM | `iam_users` | 用户身份与角色 |
|
||||
| Auth | `auth_platform_api_keys` | 平台签发凭证（仅 hash，不存明文） |
|
||||
| Billing | `billing_accounts` | 预算账户与余额 |
|
||||
| Billing | `billing_ledger_entries` | 借贷分录与请求级对账 |
|
||||
| Routing | `routing_policies` | 策略版本、优先级、生效窗口 |
|
||||
| Security | `security_kms_key_registry` | KMS Key 与加密算法版本登记 |
|
||||
| Audit | `audit_events` | 全域审计事件（配置/账务/安全） |
|
||||
|
||||
DDL：`sql/postgresql/platform_core_schema_v1.sql`
|
||||
|
||||
---
|
||||
|
||||
## 3. 供应域字段补齐（在 v1 基础上增量）
|
||||
|
||||
### 3.1 加密字段（必须）
|
||||
|
||||
1. `*_cipher_algo`：默认 `AES-256-GCM`
|
||||
2. `*_kms_key_alias`：KMS key alias（非 key 明文）
|
||||
3. `*_key_version`：key 版本号
|
||||
4. `*_fingerprint`：凭证摘要（不可逆）
|
||||
5. `last_rotation_at`：上次轮换时间
|
||||
|
||||
### 3.2 单位与币种字段（必须）
|
||||
|
||||
1. `quota_unit`：`token/request/credit`
|
||||
2. `price_unit`：`per_1m_tokens` 等
|
||||
3. `amount_unit`：`minor`（分/厘）
|
||||
4. `currency_code`：ISO 4217 三位码
|
||||
|
||||
### 3.3 审计与并发字段（必须）
|
||||
|
||||
1. `request_id`
|
||||
2. `idempotency_key`
|
||||
3. `audit_trace_id`
|
||||
4. `created_ip` / `updated_ip`
|
||||
5. `version`（乐观锁）
|
||||
|
||||
DDL：`sql/postgresql/supply_schema_v1_patch_2026-03-27.sql`
|
||||
|
||||
---
|
||||
|
||||
## 4. 索引策略（高频查询优先）
|
||||
|
||||
### 4.1 组合索引
|
||||
|
||||
1. `supply_accounts(user_id, status, updated_at desc)`
|
||||
2. `supply_packages(user_id, status, updated_at desc)`
|
||||
3. `supply_orders(buyer_user_id, status, created_at desc)`
|
||||
4. `supply_settlements(user_id, status, updated_at desc)`
|
||||
5. `billing_ledger_entries(billing_account_id, occurred_at desc)`
|
||||
|
||||
### 4.2 部分索引
|
||||
|
||||
1. `supply_packages` 的 active 查询（仅 `status=active`）
|
||||
2. `supply_settlements` 的处理中唯一约束（仅 `status=processing`）
|
||||
|
||||
### 4.3 可观测索引
|
||||
|
||||
1. `request_id`
|
||||
2. `trace_id`
|
||||
3. `audit_trace_id`
|
||||
|
||||
说明：所有关键事件必须具备 request 级反查路径，满足“从告警到原始账务分录”单跳可达。
|
||||
|
||||
---
|
||||
|
||||
## 5. 迁移顺序与回滚策略
|
||||
|
||||
1. Phase-A：执行 `platform_core_schema_v1.sql`（新增表，无破坏性）。
|
||||
2. Phase-B：执行 `supply_schema_v1_patch_2026-03-27.sql`（增列+增索引）。
|
||||
3. Phase-C：灰度写入新字段（双写，不读取）。
|
||||
4. Phase-D：回填历史数据（按日批，带校验）。
|
||||
5. Phase-E：切换读路径到新字段并开启质量门禁。
|
||||
|
||||
回滚原则：
|
||||
1. 新字段只增不删，读路径可切回旧字段。
|
||||
2. 新索引可独立回退，不影响主流程事务。
|
||||
3. 任一阶段失败立即冻结下一阶段，不跨阶段带病推进。
|
||||
|
||||
---
|
||||
|
||||
## 6. 质量验收清单（DB）
|
||||
|
||||
1. 结构验收：新增表/列/索引全部存在，且命名符合规范。
|
||||
2. 安全验收：无明文凭证列，hash/指纹字段可用。
|
||||
3. 一致性验收：账务分录借贷平衡，提现处理中单一约束生效。
|
||||
4. 审计验收：关键写接口 100% 带 `request_id + trace_id`。
|
||||
5. 性能验收：高频查询 P95 无劣化（对比 patch 前后）。
|
||||
|
||||
---
|
||||
|
||||
## 7. 约束声明
|
||||
|
||||
1. 本文与两个 SQL 文件共同构成数据库实施 SSOT。
|
||||
2. 任何新增业务功能必须先选择所属域，再定义表/字段/索引，不允许“先代码后补库”。
|
||||
3. 未通过本清单第 6 章，禁止进入发布门禁 `SUP-008` 与全局 `GO` 评审。
|
||||
@@ -0,0 +1,93 @@
|
||||
# 依赖版本兼容性审计基线（v1.0）
|
||||
|
||||
- 版本：v1.0
|
||||
- 日期：2026-03-27
|
||||
- 状态：生效（发布前强制 Gate）
|
||||
- 目标：把“依赖可用”升级为“依赖可审计、可回滚、可阻断”
|
||||
- 关联文档：
|
||||
- `docs/technical_architecture_optimized_v2_2026-03-18.md`
|
||||
- `docs/acceptance_gate_single_source_v1_2026-03-18.md`
|
||||
- `docs/subapi_integration_risk_controls_execution_tasks_v1_2026-03-17.md`
|
||||
|
||||
---
|
||||
|
||||
## 1. 审计对象与冻结策略
|
||||
|
||||
| 层 | 对象 | 冻结规则 |
|
||||
|---|---|---|
|
||||
| Runtime | Go / Node / JDK / Python | 仅允许 LTS 或已验证小版本 |
|
||||
| Data | PostgreSQL / Redis | 生产固定主版本，升级必须灰度 |
|
||||
| 服务依赖 | subapi / provider SDK | 固定精确版本（`X.Y.Z`） |
|
||||
| 第三方库 | go mod / npm / maven | 锁文件变更必须触发兼容测试 |
|
||||
| OS 镜像 | 基础镜像 digest | 必须可追溯到 SBOM |
|
||||
|
||||
---
|
||||
|
||||
## 2. 必交付证据
|
||||
|
||||
每次发布候选版本必须提供：
|
||||
|
||||
1. `SBOM`：`reports/dependency/sbom_<date>.spdx.json`
|
||||
2. `锁文件差异`：`reports/dependency/lockfile_diff_<date>.md`
|
||||
3. `兼容矩阵`：`reports/dependency/compat_matrix_<date>.md`
|
||||
4. `风险清单`：`reports/dependency/risk_register_<date>.md`
|
||||
|
||||
无上述四项，发布门禁直接阻断。
|
||||
|
||||
---
|
||||
|
||||
## 3. 兼容性审计流程（分阶段）
|
||||
|
||||
### 3.1 Pre-Merge（开发合并前）
|
||||
|
||||
1. 检查 `go.mod/go.sum`、`package-lock.json/pnpm-lock.yaml`、`pom.xml` 变化。
|
||||
2. 依赖变更自动分类：Patch/Minor/Major。
|
||||
3. Major 变更必须附“兼容影响评估 + 回滚预案”。
|
||||
|
||||
### 3.2 Nightly（每日）
|
||||
|
||||
1. 运行依赖漏洞扫描（CVE/SCA）。
|
||||
2. 运行契约回归（Schema/Behavior）。
|
||||
3. 生成依赖健康趋势（新增高危漏洞数）。
|
||||
|
||||
### 3.3 Pre-Release（发布前）
|
||||
|
||||
1. 运行完整兼容回归（兼容三重 Gate + SUP Gate）。
|
||||
2. 校验运行时与数据层版本匹配矩阵。
|
||||
3. 通过后冻结候选构建包与镜像 digest。
|
||||
|
||||
### 3.4 Post-Release（发布后 24h）
|
||||
|
||||
1. 监控新增依赖告警、崩溃、性能回退。
|
||||
2. 若触发 P0/P1 依赖事故，执行自动回滚到上一稳定版本。
|
||||
|
||||
---
|
||||
|
||||
## 4. 阻断规则（必须）
|
||||
|
||||
1. `dependency_compat_audit_pass_pct < 100%`：阻断发布。
|
||||
2. 新增 Critical CVE 且无缓解：阻断发布。
|
||||
3. Major 依赖变更无回滚演练记录：阻断发布。
|
||||
4. subapi/provider SDK 精确版本未锁定：阻断发布。
|
||||
5. 依赖清单与运行镜像不一致：阻断发布。
|
||||
|
||||
---
|
||||
|
||||
## 5. 推荐版本兼容矩阵（首版）
|
||||
|
||||
| 组件 | 基线版本 | 兼容范围 | 备注 |
|
||||
|---|---|---|---|
|
||||
| Go | 1.21.x | 1.21.x | 不跨主版本 |
|
||||
| PostgreSQL | 15.x | 15.x | SQL 与索引以 PG15 语法为准 |
|
||||
| Redis | 7.x | 7.x | 限流与缓存行为基于 Redis7 验证 |
|
||||
| subapi | 精确 `X.Y.Z` | 同 patch | Minor 升级需完整回归 |
|
||||
| Node（前端） | 20.x LTS | 20.x | 锁文件必须纳入审计 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 与发布门禁对齐
|
||||
|
||||
1. 依赖兼容审计结果接入 `acceptance_gate_single_source` 指标 `M-017`。
|
||||
2. 分阶段测试质量接入指标 `M-018`。
|
||||
3. 任一未达标，不得进入 `GO` 结论。
|
||||
|
||||
@@ -193,18 +193,23 @@
|
||||
1. 供应商接入稳定性
|
||||
2. 计费与账单口径统一
|
||||
3. 告警渠道与通知系统稳定
|
||||
4. 数据库跨域模型完整（Core/IAM/Auth/Billing/Supply/Audit）
|
||||
5. 依赖版本兼容审计机制可执行（SBOM + 锁文件差异 + 兼容矩阵 + 风险清单）
|
||||
|
||||
## 9.2 主要风险
|
||||
|
||||
1. 功能边界过宽导致首发延期
|
||||
2. 缺少真实客户数据导致价值表达不足
|
||||
3. 定价方案与客户价值感知不匹配
|
||||
4. 依赖版本漂移导致线上兼容故障
|
||||
5. 阶段门禁不完整导致实现偏离需求主线
|
||||
|
||||
## 9.3 风险缓解
|
||||
|
||||
1. 坚持 P0 边界，P1/P2 延后
|
||||
2. 以设计合作伙伴反馈驱动迭代
|
||||
3. 发布前完成小规模定价验证访谈
|
||||
4. 将依赖兼容审计和分阶段质量门禁纳入发布前阻断条件
|
||||
|
||||
## 10. 已冻结决策（v1.0 生效）
|
||||
|
||||
|
||||
126
docs/plans/2026-03-30-superpowers-execution-tasklist-v2.md
Normal file
126
docs/plans/2026-03-30-superpowers-execution-tasklist-v2.md
Normal file
@@ -0,0 +1,126 @@
|
||||
# 规划设计闭环执行任务清单（Superpowers v2）
|
||||
|
||||
- 日期：2026-03-30
|
||||
- 基线来源：`docs/plans/2026-03-25-superpowers-execution-tasklist-v1.md`
|
||||
- 目标：基于最新真实证据重排执行优先级，持续推进到 staging 可复核、可签署。
|
||||
|
||||
---
|
||||
|
||||
## 1. 实际状态复盘（以证据为准）
|
||||
|
||||
### 1.1 已闭环工作流（开发阶段）
|
||||
|
||||
1. `WG-A/WG-B/WG-C` 已完成：需求冻结、OpenAPI 契约对齐、追踪矩阵一致化。
|
||||
2. `WG-F/WG-G` 已完成：全局 P0 映射、命名策略、跨文档一致性与最终决议草稿链路。
|
||||
3. TOK 链路已完成开发闭环（`TOK-002 ~ TOK-007`）：包含 runtime、门禁汇总、复审与候选稿生成。
|
||||
|
||||
关键证据：
|
||||
1. `reports/superpowers_execution_progress_2026-03-27.md`
|
||||
2. `reports/alignment_validation_checkpoint_12_2026-03-30.md` ~ `reports/alignment_validation_checkpoint_27_2026-03-30.md`
|
||||
3. `reports/gates/superpowers_stage_validation_2026-03-30_212426.md`
|
||||
|
||||
### 1.2 未闭环工作流（真实环境）
|
||||
|
||||
1. `WG-D/WG-E` 仍未完成真实 staging 证据闭环，当前仅有 local/mock 与 dry-run 证据。
|
||||
2. 最终签署决议当前为 `NO-GO`，核心阻塞集中在 `F-01/F-02/F-04`（P0）与 `F-03`（P1）。
|
||||
|
||||
关键证据：
|
||||
1. `review/final_decision_2026-03-31.md`
|
||||
2. `reports/supply_gate_review_2026-03-31.md`
|
||||
3. `reports/token_runtime_implementation_gap_review_2026-03-30.md`
|
||||
|
||||
---
|
||||
|
||||
## 2. 状态矩阵（v2）
|
||||
|
||||
| 工作流 | 状态 | 说明 | 下一动作 |
|
||||
|---|---|---|---|
|
||||
| WG-A 需求冻结 | DONE | 已完成冻结与决议映射 | 仅维护 |
|
||||
| WG-B 契约对齐 | DONE | OpenAPI 与幂等头已落地 | 仅维护 |
|
||||
| WG-C 测试矩阵 | DONE | 路径一致化与规则文档已落地 | 仅维护 |
|
||||
| WG-D 真实联调 | BLOCKED（外部依赖） | 缺真实 staging 地址与有效短期 token | 优先解锁 F-01/F-02/F-04 |
|
||||
| WG-E 报告签署 | BLOCKED（依赖 WG-D） | 缺真实证据，无法转 GO | 与 WG-D 同步推进 |
|
||||
| WG-F 一致性收尾 | DONE | 命名策略与映射补齐完成 | 仅维护 |
|
||||
| WG-G 全局校验 | DONE（开发口径） | 校验链路可执行，决议一致性脚本已在跑 | 补真实口径复核 |
|
||||
| TOK 运行态链路 | DONE（开发口径） | M-021 开发阶段 100% | 需 staging 实证回填 |
|
||||
|
||||
---
|
||||
|
||||
## 3. P0/P1 阻塞项（从最终决议回填）
|
||||
|
||||
| 编号 | 等级 | 阻塞描述 | Owner | 截止日期 | 退出条件 |
|
||||
|---|---|---|---|---|---|
|
||||
| F-01 | P0 | staging DNS 与 `API_BASE_URL` 可达性修复，重跑 SUP-004~007 | PLAT + QA | 2026-04-01 | `staging_precheck_and_run.sh` 在真实环境 PASS |
|
||||
| F-02 | P0 | 补齐 M-013~M-016 staging 实测值 | SEC + QA | 2026-04-01 | `sec_sup_boundary_report` 回填真实 PASS |
|
||||
| F-04 | P0 | token runtime staging 联调取证 | ARCH + PLAT + SEC | 2026-04-03 | `M-021` 与边界指标 staging 证据齐全 |
|
||||
| F-03 | P1 | M-017/M-018/M-019 连续 7 天趋势证据 | PLAT + PMO | 2026-04-05 | 趋势报告满足 7 天口径 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 批次执行计划（从 2026-03-30 起）
|
||||
|
||||
### Batch-MON-01（当前批次，先做“可持续执行”能力）
|
||||
|
||||
1. `MON-001`：新增 Minimax 7 日趋势脚本（监控链路补齐）。
|
||||
2. `MON-002`：将 Minimax 日快照接入 `superpowers_release_pipeline.sh`（可选、默认关闭、非阻断）。
|
||||
3. `MON-003`：更新命令手册，补齐执行与断言说明。
|
||||
4. `MON-004`：产出对齐验证报告（Checkpoint-28）。
|
||||
|
||||
执行结果（2026-03-30）：
|
||||
|
||||
| 任务 | 状态 | 证据 |
|
||||
|---|---|---|
|
||||
| MON-001 | DONE | `scripts/ci/minimax_upstream_trend_report.sh` + `reports/gates/minimax_upstream_trend_7d_2026-03-30.md` |
|
||||
| MON-002 | DONE | `scripts/ci/superpowers_release_pipeline.sh` + `reports/gates/superpowers_release_pipeline_2026-03-30_235224.md` |
|
||||
| MON-003 | DONE | `docs/supply_gate_command_playbook_v1_2026-03-25.md` |
|
||||
| MON-004 | DONE | `reports/alignment_validation_checkpoint_28_2026-03-30.md` |
|
||||
|
||||
### Batch-STG-01（下一批次，真实环境解锁）
|
||||
|
||||
1. `STG-001`：确认真实 staging 网关地址并更新 `scripts/supply-gate/.env`。
|
||||
2. `STG-002`：注入有效 owner/viewer/admin 短期 token（禁用占位值）。
|
||||
3. `STG-003`：执行 `scripts/ci/staging_release_pipeline.sh`（真实环境，不允许 local/mock）。
|
||||
4. `STG-004`：回填 `F-01/F-02/F-04` 证据到最终决议与评审报告。
|
||||
|
||||
当前门禁检查（2026-03-30）：
|
||||
1. `scripts/supply-gate/.env` 中 `API_BASE_URL` 仍处于阻塞态（非真实 staging 可发布地址）。
|
||||
2. 因 `STG-001` 未完成，`STG-003` 当前不得触发真实放行判定。
|
||||
|
||||
本机开发测试续跑结果（2026-03-31）：
|
||||
1. `local/mock` 口径 `staging_release_pipeline` 已复跑通过：`reports/gates/staging_release_pipeline_2026-03-31_100116.md`。
|
||||
2. STG 本地续跑中识别并修复 `PHASE-10` 阻塞（M-021 smoke 端口冲突与控制流提前退出）。
|
||||
3. 修复后 `superpowers_release_pipeline` 与 `tok007` 复审链路恢复，结论维持 `CONDITIONAL_GO`。
|
||||
4. `STG-001/STG-002`（真实 staging 地址与真 token）仍未完成，真实放行证据仍阻塞。
|
||||
|
||||
本机端口基线固化结果（2026-03-31）：
|
||||
1. 已清理蚊子残留进程与冲突端口占用，详见 `reports/gates/local_dev_port_baseline_2026-03-31.md`。
|
||||
2. 清理后再次复测 `staging_release_pipeline`：`reports/gates/staging_release_pipeline_2026-03-31_100942.md`（PASS）。
|
||||
3. 对齐验证补充：`reports/alignment_validation_checkpoint_30_2026-03-31.md`。
|
||||
|
||||
真实 STG 前置自动化补齐（2026-03-31）：
|
||||
1. 已新增本地 `.env.staging-real` 一键生成脚本：`scripts/ci/generate_local_staging_env.sh`。
|
||||
2. 已新增真实 STG 就绪度检查脚本：`scripts/ci/staging_real_readiness_check.sh`。
|
||||
3. 当前 `.env.staging-real` 就绪检查结论为 `BLOCKED`：`reports/gates/staging_real_readiness_2026-03-31_110213.md`。
|
||||
4. 阻塞原因聚焦在 `STG-RDY-004/008`（API_BASE_URL 仍为本地地址且无真实外网可达性）。
|
||||
|
||||
完整开发测试续跑结果（2026-03-31 12:31）：
|
||||
1. 已重新生成 `.env.staging-real` 且三类 token 均为非占位值：`reports/gates/local_staging_env_generation_2026-03-31_123102.md`。
|
||||
2. `local/mock` 口径 `staging_release_pipeline` 再次通过：`reports/gates/staging_release_pipeline_2026-03-31_123148.md`。
|
||||
3. `superpowers_release_pipeline` 与 `tok007` 复审链路再次通过，机判维持 `CONDITIONAL_GO`：`reports/gates/superpowers_release_pipeline_2026-03-31_123150.md`、`review/outputs/tok007_release_recheck_2026-03-31_123153.md`。
|
||||
4. 真实 STG 就绪度检查仍为 `BLOCKED`：`reports/gates/staging_real_readiness_2026-03-31_123159.md`（`STG-RDY-004/008` 未关闭）。
|
||||
5. Minimax 上游 smoke 继续保持 `PASS`：`reports/gates/minimax_upstream_smoke_2026-03-31_123210.md`。
|
||||
|
||||
---
|
||||
|
||||
## 5. 执行约束
|
||||
|
||||
1. `local/mock` 结果仅可作为开发演练证据，不可替代 staging 放行证据。
|
||||
2. 任何 `P0` 项未关闭，最终结论不得上调为 `GO`。
|
||||
3. 所有阶段结论以脚本返回码 + 报告产物双重校验为准。
|
||||
|
||||
---
|
||||
|
||||
## 6. 与 v1 的关系
|
||||
|
||||
1. `v1` 保留原子任务定义（A~G）。
|
||||
2. `v2` 作为执行态总控视图，负责状态、批次与阻塞跟踪。
|
||||
@@ -0,0 +1,450 @@
|
||||
openapi: 3.0.3
|
||||
info:
|
||||
title: Platform Token Runtime API Contract Draft
|
||||
version: 1.0.0-draft
|
||||
description: |
|
||||
TOK-002/TOK-003/TOK-004 对应的 token 运行态接口草案。
|
||||
关键边界：
|
||||
1) 仅平台内部可调用 issue/revoke。
|
||||
2) 不暴露上游供应方凭证信息。
|
||||
servers:
|
||||
- url: https://api.example.com
|
||||
description: Production
|
||||
security:
|
||||
- BearerAuth: []
|
||||
tags:
|
||||
- name: PlatformToken
|
||||
paths:
|
||||
/api/v1/platform/tokens/issue:
|
||||
post:
|
||||
tags: [PlatformToken]
|
||||
summary: 签发平台短期 token
|
||||
operationId: issuePlatformToken
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/XRequestIdHeader'
|
||||
- $ref: '#/components/parameters/IdempotencyKeyHeader'
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/IssueTokenRequest'
|
||||
responses:
|
||||
'201':
|
||||
description: 签发成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/IssueTokenResponse'
|
||||
'400':
|
||||
$ref: '#/components/responses/BadRequest'
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'403':
|
||||
$ref: '#/components/responses/Forbidden'
|
||||
'409':
|
||||
$ref: '#/components/responses/Conflict'
|
||||
/api/v1/platform/tokens/{tokenId}/refresh:
|
||||
post:
|
||||
tags: [PlatformToken]
|
||||
summary: 刷新 token 过期时间
|
||||
operationId: refreshPlatformToken
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/TokenIdParam'
|
||||
- $ref: '#/components/parameters/XRequestIdHeader'
|
||||
- $ref: '#/components/parameters/IdempotencyKeyHeader'
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/RefreshTokenRequest'
|
||||
responses:
|
||||
'200':
|
||||
description: 刷新成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/RefreshTokenResponse'
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'403':
|
||||
$ref: '#/components/responses/Forbidden'
|
||||
'404':
|
||||
$ref: '#/components/responses/NotFound'
|
||||
'409':
|
||||
$ref: '#/components/responses/Conflict'
|
||||
/api/v1/platform/tokens/{tokenId}/revoke:
|
||||
post:
|
||||
tags: [PlatformToken]
|
||||
summary: 吊销 token
|
||||
operationId: revokePlatformToken
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/TokenIdParam'
|
||||
- $ref: '#/components/parameters/XRequestIdHeader'
|
||||
- $ref: '#/components/parameters/IdempotencyKeyHeader'
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/RevokeTokenRequest'
|
||||
responses:
|
||||
'200':
|
||||
description: 吊销成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/RevokeTokenResponse'
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'403':
|
||||
$ref: '#/components/responses/Forbidden'
|
||||
'404':
|
||||
$ref: '#/components/responses/NotFound'
|
||||
/api/v1/platform/tokens/introspect:
|
||||
post:
|
||||
tags: [PlatformToken]
|
||||
summary: token 校验与解析
|
||||
operationId: introspectPlatformToken
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/XRequestIdHeader'
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/IntrospectTokenRequest'
|
||||
responses:
|
||||
'200':
|
||||
description: 校验成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/IntrospectTokenResponse'
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'422':
|
||||
$ref: '#/components/responses/BusinessError'
|
||||
/api/v1/platform/tokens/audit-events:
|
||||
get:
|
||||
tags: [PlatformToken]
|
||||
summary: 查询 token 审计事件
|
||||
operationId: listPlatformTokenAuditEvents
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/XRequestIdHeader'
|
||||
- name: request_id
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
maxLength: 128
|
||||
- name: token_id
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
maxLength: 128
|
||||
- name: subject_id
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
maxLength: 128
|
||||
- name: event_name
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
maxLength: 128
|
||||
- name: result_code
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: string
|
||||
maxLength: 64
|
||||
- name: limit
|
||||
in: query
|
||||
required: false
|
||||
schema:
|
||||
type: integer
|
||||
minimum: 1
|
||||
maximum: 500
|
||||
default: 100
|
||||
responses:
|
||||
'200':
|
||||
description: 查询成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/AuditEventsResponse'
|
||||
'400':
|
||||
$ref: '#/components/responses/BadRequest'
|
||||
'501':
|
||||
$ref: '#/components/responses/BusinessError'
|
||||
|
||||
components:
|
||||
securitySchemes:
|
||||
BearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
parameters:
|
||||
XRequestIdHeader:
|
||||
name: X-Request-Id
|
||||
in: header
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
minLength: 8
|
||||
maxLength: 128
|
||||
IdempotencyKeyHeader:
|
||||
name: Idempotency-Key
|
||||
in: header
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
minLength: 8
|
||||
maxLength: 128
|
||||
TokenIdParam:
|
||||
name: tokenId
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
minLength: 8
|
||||
maxLength: 128
|
||||
responses:
|
||||
BadRequest:
|
||||
description: 参数错误
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
Unauthorized:
|
||||
description: 认证失败
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
Forbidden:
|
||||
description: 权限不足
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
NotFound:
|
||||
description: 资源不存在
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
Conflict:
|
||||
description: 状态冲突
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
BusinessError:
|
||||
description: 业务校验失败
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
schemas:
|
||||
IssueTokenRequest:
|
||||
type: object
|
||||
required: [subject_id, role, ttl_seconds, scope]
|
||||
properties:
|
||||
subject_id:
|
||||
type: string
|
||||
minLength: 1
|
||||
maxLength: 128
|
||||
role:
|
||||
type: string
|
||||
enum: [owner, viewer, admin]
|
||||
ttl_seconds:
|
||||
type: integer
|
||||
minimum: 60
|
||||
maximum: 259200
|
||||
scope:
|
||||
type: array
|
||||
minItems: 1
|
||||
items:
|
||||
type: string
|
||||
metadata:
|
||||
type: object
|
||||
additionalProperties: true
|
||||
IssueTokenResponse:
|
||||
type: object
|
||||
required: [request_id, data]
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
data:
|
||||
type: object
|
||||
required: [token_id, access_token, issued_at, expires_at, status]
|
||||
properties:
|
||||
token_id:
|
||||
type: string
|
||||
access_token:
|
||||
type: string
|
||||
writeOnly: true
|
||||
issued_at:
|
||||
type: string
|
||||
format: date-time
|
||||
expires_at:
|
||||
type: string
|
||||
format: date-time
|
||||
status:
|
||||
type: string
|
||||
enum: [active]
|
||||
RefreshTokenRequest:
|
||||
type: object
|
||||
required: [ttl_seconds]
|
||||
properties:
|
||||
ttl_seconds:
|
||||
type: integer
|
||||
minimum: 60
|
||||
maximum: 259200
|
||||
RefreshTokenResponse:
|
||||
type: object
|
||||
required: [request_id, data]
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
data:
|
||||
type: object
|
||||
required: [token_id, previous_expires_at, expires_at, status]
|
||||
properties:
|
||||
token_id:
|
||||
type: string
|
||||
previous_expires_at:
|
||||
type: string
|
||||
format: date-time
|
||||
expires_at:
|
||||
type: string
|
||||
format: date-time
|
||||
status:
|
||||
type: string
|
||||
enum: [active]
|
||||
RevokeTokenRequest:
|
||||
type: object
|
||||
required: [reason]
|
||||
properties:
|
||||
reason:
|
||||
type: string
|
||||
minLength: 1
|
||||
maxLength: 256
|
||||
RevokeTokenResponse:
|
||||
type: object
|
||||
required: [request_id, data]
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
data:
|
||||
type: object
|
||||
required: [token_id, status, revoked_at]
|
||||
properties:
|
||||
token_id:
|
||||
type: string
|
||||
status:
|
||||
type: string
|
||||
enum: [revoked]
|
||||
revoked_at:
|
||||
type: string
|
||||
format: date-time
|
||||
IntrospectTokenRequest:
|
||||
type: object
|
||||
required: [token]
|
||||
properties:
|
||||
token:
|
||||
type: string
|
||||
minLength: 8
|
||||
IntrospectTokenResponse:
|
||||
type: object
|
||||
required: [request_id, data]
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
data:
|
||||
type: object
|
||||
required: [token_id, subject_id, role, status, scope, issued_at, expires_at]
|
||||
properties:
|
||||
token_id:
|
||||
type: string
|
||||
subject_id:
|
||||
type: string
|
||||
role:
|
||||
type: string
|
||||
enum: [owner, viewer, admin]
|
||||
status:
|
||||
type: string
|
||||
enum: [active, revoked, expired]
|
||||
scope:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
issued_at:
|
||||
type: string
|
||||
format: date-time
|
||||
expires_at:
|
||||
type: string
|
||||
format: date-time
|
||||
AuditEventsResponse:
|
||||
type: object
|
||||
required: [request_id, data]
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
data:
|
||||
type: object
|
||||
required: [total, items]
|
||||
properties:
|
||||
total:
|
||||
type: integer
|
||||
minimum: 0
|
||||
items:
|
||||
type: array
|
||||
items:
|
||||
$ref: '#/components/schemas/AuditEventItem'
|
||||
AuditEventItem:
|
||||
type: object
|
||||
required: [event_id, event_name, request_id, route, result_code, created_at]
|
||||
properties:
|
||||
event_id:
|
||||
type: string
|
||||
event_name:
|
||||
type: string
|
||||
request_id:
|
||||
type: string
|
||||
token_id:
|
||||
type: string
|
||||
subject_id:
|
||||
type: string
|
||||
route:
|
||||
type: string
|
||||
result_code:
|
||||
type: string
|
||||
client_ip:
|
||||
type: string
|
||||
created_at:
|
||||
type: string
|
||||
format: date-time
|
||||
ErrorResponse:
|
||||
type: object
|
||||
required: [request_id, error]
|
||||
properties:
|
||||
request_id:
|
||||
type: string
|
||||
error:
|
||||
type: object
|
||||
required: [code, message]
|
||||
properties:
|
||||
code:
|
||||
type: string
|
||||
message:
|
||||
type: string
|
||||
details:
|
||||
type: object
|
||||
additionalProperties: true
|
||||
@@ -0,0 +1,20 @@
|
||||
# 全局 P0 到供应侧/平台侧映射表（v1.0）
|
||||
|
||||
- 日期：2026-03-27
|
||||
- 来源：`docs/llm_gateway_prd_v1_2026-03-25.md`（第 11 节及第 4.1 节）
|
||||
- 目标：避免“供应侧完成=全局P0完成”的误判。
|
||||
|
||||
| 全局 P0 ID | 全局能力 | 供应侧入口（按钮/页面） | 平台侧入口（控制面/API） | 当前状态 |
|
||||
|---|---|---|---|---|
|
||||
| PRD-P0-01 | 供应账号挂载与验证 | SUP-PAGE-001：`BTN-ACC-001~006` | 平台鉴权与审计服务 | 已覆盖 |
|
||||
| PRD-P0-02 | 套餐发布与上下架 | SUP-PAGE-002：`BTN-PKG-001~006` | 平台路由与策略中心 | 已覆盖 |
|
||||
| PRD-P0-03 | 收益结算与提现 | SUP-PAGE-003：`BTN-SET-001~005` | 账务与结算服务 | 已覆盖 |
|
||||
| PRD-P0-04 | 凭证边界强制约束 | 三页面全局约束与 SEC-SUP 用例 | 网关鉴权、出网审计、告警中心 | 已覆盖（待 staging 实证） |
|
||||
| PRD-P0-05 | 预算与配额 | 供应侧仅展示配额结果，不做全局预算配置 | 平台预算中心（组织/项目级阈值） | 待平台侧实现证据 |
|
||||
| PRD-P0-06 | 告警与通知 | 供应侧展示告警状态与处理入口 | 平台告警中心（规则、路由、升级） | 待平台侧实现证据 |
|
||||
| PRD-P0-07 | 账单导出 | 供应侧提供结算单导出（供应方视角） | 平台统一账单导出（组织级） | 部分覆盖（需双侧对齐） |
|
||||
|
||||
## 补充说明（F-002）
|
||||
|
||||
1. “预算/告警/统一账单导出”属于平台控制面能力，供应侧仅保留入口与只读结果，不承担策略主配置职责。
|
||||
2. 供应侧“结算单导出”与平台“组织级账单导出”不是同一能力，必须双轨验收。
|
||||
@@ -0,0 +1,17 @@
|
||||
# 供应侧按钮 PRD 待拍板项决议映射（v1.0）
|
||||
|
||||
- 日期：2026-03-27
|
||||
- 来源文档：`docs/supply_button_level_prd_v1_2026-03-25.md`
|
||||
- 目标：将“待拍板项”转为“可执行决议”，用于实施与验收对齐。
|
||||
|
||||
| 映射ID | 待拍板项 | 决议 | 责任角色 | 交付动作 | 验收证据 |
|
||||
|---|---|---|---|---|---|
|
||||
| MAP-001 | `POST /api/v1/supply/*` 命名是否冻结 | 冻结 `/api/v1/supply/*` 为主路径；`/api/v1/supplier/billing` 保留兼容 | ARCH + PLAT | 在 OpenAPI 记录主路径/兼容路径声明 | OpenAPI 变更记录 |
|
||||
| MAP-002 | 提现金额阈值与冷却期 | 单笔 `<=50000 CNY`；单日 `<=200000 CNY`；冷却期 `15 min` | FIN + ARCH + QA | 在结算规则与测试断言同步阈值 | 测试用例与执行报告 |
|
||||
| MAP-003 | 下架 vs 暂停财务口径 | `pause` 阻断新购、存量订单继续；`unlist` 阻断新购并触发 T+1 核对 | FIN + 产品 + QA | 更新状态机语义与审计事件说明 | PRD 条目 + 审计字段检查 |
|
||||
| MAP-004 | 批量导入账号是否进入 S0/S1 | 不进入 S0/S1；作为 S2 评审项，白名单灰度 | 产品 + ARCH | 从当前门禁移除，纳入路线图 | 路线图条目与门禁范围声明 |
|
||||
|
||||
## 变更控制
|
||||
|
||||
1. 本映射作为 `A-003` 产物，任何变更需记录变更单号与审批人。
|
||||
2. 未经审批，不得恢复“待拍板项”状态。
|
||||
@@ -1,7 +1,7 @@
|
||||
# Subapi 集成风险控制实施任务单（两周执行版，v1.4）
|
||||
# Subapi 集成风险控制实施任务单（两周执行版，v1.5）
|
||||
|
||||
- 版本：v1.4
|
||||
- 日期：2026-03-25
|
||||
- 版本：v1.5
|
||||
- 日期：2026-03-27
|
||||
- 执行窗口：2026-03-18 至 2026-03-31（两周）
|
||||
- 关联文档：
|
||||
- `subapi_integration_compat_security_reliability_design_v1_2026-03-17.md`
|
||||
@@ -11,13 +11,15 @@
|
||||
- `router_core_s2_acceptance_test_cases_v1_2026-03-17.md`
|
||||
- `acceptance_gate_single_source_v1_2026-03-18.md`（v1.1, 2026-03-24）
|
||||
- `llm_gateway_subapi_evolution_plan_v4_2_2026-03-24.md`
|
||||
- `supply_button_level_prd_v1_2026-03-25.md`
|
||||
- `supply_button_level_prd_v1_2026-03-25.md`（v1.1 冻结，2026-03-27）
|
||||
- `supply_api_contract_openapi_draft_v1_2026-03-25.yaml`
|
||||
- `supply_ui_test_cases_executable_v1_2026-03-25.md`
|
||||
- `supply_gate_command_playbook_v1_2026-03-25.md`
|
||||
- `supply_technical_design_enhanced_v1_2026-03-25.md`
|
||||
- `supply_test_plan_enhanced_v1_2026-03-25.md`
|
||||
- `supply_uiux_design_spec_v1_2026-03-25.md`
|
||||
- `database_domain_model_and_governance_v1_2026-03-27.md`
|
||||
- `dependency_compatibility_audit_baseline_v1_2026-03-27.md`
|
||||
- `tests/supply/ui_design_qa_cases_v1_2026-03-25.md`
|
||||
- `reports/supply_gate_preflight_2026-03-25.md`
|
||||
- `review/multi_expert_planning_review_v1_2026-03-25.md`
|
||||
@@ -31,6 +33,7 @@
|
||||
5. 建立“凭证边界”硬门禁：需求方仅用平台凭证，供应方上游凭证零外发。
|
||||
6. 建立供应侧发布门禁链路（SUP）：账号挂载 -> 套餐发布 -> 结算提现全链路可验收。
|
||||
7. 建立四专家整改发布链路（XR）：技术/测试/UIUX/业主条款与门禁统一闭环。
|
||||
8. 建立 token 运行态交付链路（TOK）：从实现、部署到门禁验收可追踪闭环。
|
||||
|
||||
## 2. 责任角色映射（实名RACI）
|
||||
|
||||
@@ -138,7 +141,7 @@
|
||||
|
||||
| 任务ID | 任务 | Owner | 截止日期 | 依赖 | 验收标准 | 证据产物 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| SUP-001 | 供应侧按钮级 PRD 冻结（3 页面） | `产品` + `ARCH` | 2026-03-26 | 无 | 页面字段、按钮、状态机、错误码冻结 | `docs/supply_button_level_prd_v1_2026-03-25.md` |
|
||||
| SUP-001 | 供应侧按钮级 PRD 冻结（3 页面） | `产品` + `ARCH` | 2026-03-26 | 无 | 页面字段、按钮、状态机、错误码冻结 | `docs/supply_button_level_prd_v1_2026-03-25.md`（v1.1 冻结） |
|
||||
| SUP-002 | 供应侧 OpenAPI 契约冻结（3 页面） | `PLAT` + `ARCH` | 2026-03-26 | SUP-001 | 请求/响应字段、枚举、错误码冻结 | `docs/supply_api_contract_openapi_draft_v1_2026-03-25.yaml` |
|
||||
| SUP-003 | UI-SUP 可执行用例评审通过 | `QA` + `产品` | 2026-03-27 | SUP-001, SUP-002 | `UI-SUP-*` + `UI-DESIGN-QA-*` 全量可执行，覆盖按钮/状态/权限/可访问性 | `docs/supply_ui_test_cases_executable_v1_2026-03-25.md` + `tests/supply/ui_design_qa_cases_v1_2026-03-25.md` |
|
||||
| SUP-004 | 账号挂载链路联调（验证/创建/激活/暂停） | `PLAT` + `QA` | 2026-03-28 | SUP-002, SUP-003 | `UI-SUP-ACC-001~006` 通过率 100% | `scripts/supply-gate/sup004_accounts.sh` + `tests/supply/ui_sup_acc_report_2026-03-28.md` |
|
||||
@@ -152,11 +155,34 @@
|
||||
| 任务ID | 任务 | Owner | 截止日期 | 依赖 | 验收标准 | 证据产物 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| XR-001 | 供应侧技术设计增强落地（幂等/并发/不变量/事务） | `ARCH` + `PLAT` | 2026-03-26 | SUP-002 | 关键写路径均具备双键幂等和冲突语义 | `docs/supply_technical_design_enhanced_v1_2026-03-25.md` |
|
||||
| XR-002 | 供应侧测试方案增强落地（追踪矩阵+并发重放） | `QA` + `ARCH` | 2026-03-27 | XR-001 | Requirement->API->Test->Metric->Gate 全量可追踪 | `docs/supply_test_plan_enhanced_v1_2026-03-25.md` + `reports/supply_traceability_matrix_2026-03-25.csv` + `reports/supply_flaky_budget_2026-03-25.md` |
|
||||
| XR-002 | 供应侧测试方案增强落地（追踪矩阵+并发重放） | `QA` + `ARCH` | 2026-03-27 | XR-001 | Requirement->API->Test->Metric->Gate 全量可追踪，且路径一致性检查通过 | `docs/supply_test_plan_enhanced_v1_2026-03-25.md` + `reports/supply_traceability_matrix_2026-03-25.csv` + `docs/supply_traceability_matrix_generation_rules_v1_2026-03-27.md` + `reports/supply_flaky_budget_2026-03-25.md` |
|
||||
| XR-003 | 供应侧 UI/UX 规范与设计验收清单落地 | `产品` + `UIUX` + `QA` | 2026-03-27 | SUP-003 | DQA P0=0，P1 通过率>=95% | `docs/supply_uiux_design_spec_v1_2026-03-25.md` |
|
||||
| XR-004 | 业主 SLA/申诉/赔付条款并入门禁验收 | `产品` + `CS` + `FIN` | 2026-03-28 | XR-002, XR-003 | 条款可执行可测且签字确认 | `docs/product/owner_sla_dispute_compensation_rules_v1.md` |
|
||||
| XR-005 | 四专家再次对齐复核并形成发布结论 | `ARCH` + `QA` + `产品` + `UIUX` | 2026-03-28 | XR-001~XR-004 | 复核结论明确（GO/CONDITIONAL GO/NO-GO） | `review/multi_expert_alignment_recheck_v1_2026-03-25.md` |
|
||||
|
||||
## 4.9 Workstream I：数据库与依赖质量闭环（新增）
|
||||
|
||||
| 任务ID | 任务 | Owner | 截止日期 | 依赖 | 验收标准 | 证据产物 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| DB-001 | 跨域核心表基线落地（Core/IAM/Auth/Billing/Audit） | `ARCH` + `PLAT` | 2026-03-27 | XR-001 | `platform_core_schema_v1.sql` 可执行且评审通过 | `sql/postgresql/platform_core_schema_v1.sql` |
|
||||
| DB-002 | 供应域加密/单位/审计字段与索引补齐 | `PLAT` + `QA` | 2026-03-28 | DB-001 | patch 可幂等执行，关键查询计划不回退 | `sql/postgresql/supply_schema_v1_patch_2026-03-27.sql` |
|
||||
| DB-003 | 数据模型与迁移策略文档并入 SSOT | `ARCH` | 2026-03-28 | DB-001, DB-002 | 迁移顺序、回滚策略、验收清单完整 | `docs/database_domain_model_and_governance_v1_2026-03-27.md` |
|
||||
| DEP-001 | 依赖兼容审计四件套接入发布流程 | `PLAT` + `SEC` | 2026-03-28 | COMP-005 | SBOM/锁差异/兼容矩阵/风险清单缺一阻断 | `docs/dependency_compatibility_audit_baseline_v1_2026-03-27.md` |
|
||||
| DEP-002 | 分阶段质量门禁（G0-G5）接入 CI | `QA` + `PLAT` | 2026-03-29 | DEP-001, XR-002 | `M-018` 与 `M-019` 自动计算并阻断 | CI 记录 + Gate 汇总 |
|
||||
| DEP-003 | 需求-设计-测试漂移日检机制上线 | `PMO` + `QA` | 2026-03-29 | DEP-002 | 发现漂移 24h 内闭环，周报可追踪 | `reports/design_drift_daily_*.md` |
|
||||
|
||||
## 4.10 Workstream J：token 运行态实现与验收闭环（TOK，新增）
|
||||
|
||||
| 任务ID | 任务 | Owner | 截止日期 | 依赖 | 验收标准 | 证据产物 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| TOK-001 | token 能力最小实现清单冻结（签发/校验/吊销/续期/审计） | `ARCH` + `SEC` + `PLAT` | 2026-03-28 | SUP-002 | 功能边界、接口与状态机冻结，禁止再口头变更 | `docs/token_runtime_minimal_spec_v1.md` |
|
||||
| TOK-002 | 平台鉴权与 token 校验中间件实现（仅平台凭证入站） | `PLAT` + `SEC` | 2026-03-30 | TOK-001 | 外部请求必须通过平台凭证校验，覆盖率=100% | 开发阶段：`docs/token_auth_middleware_design_v1_2026-03-29.md` + `docs/platform_token_api_contract_openapi_draft_v1_2026-03-29.yaml`；联调阶段：实现代码 + 单测报告 |
|
||||
| TOK-003 | token 生命周期实现（签发/短期TTL/吊销/轮换） | `PLAT` | 2026-03-31 | TOK-001 | 生命周期状态可追踪，吊销生效延迟满足阈值 | 开发阶段：`docs/token_lifecycle_audit_test_assertions_v1_2026-03-29.md`；联调阶段：实现代码 + 集成测试报告 |
|
||||
| TOK-004 | 安全审计与事件入库（签发/鉴权失败/吊销/越权） | `SEC` + `PLAT` | 2026-03-31 | TOK-002, TOK-003 | 审计事件完整入库，可按租户/角色追踪 | 开发阶段：`docs/token_lifecycle_audit_test_assertions_v1_2026-03-29.md`；联调阶段：审计表样例 + 查询结果 |
|
||||
| TOK-005 | 凭证边界联调（SUP-007 合并复测） | `SEC` + `QA` | 2026-04-01 | TOK-002~TOK-004 | M-013~M-016 在 staging 实测全部达标 | 开发阶段：`scripts/supply-gate/tok005_boundary_dryrun.sh` + `reports/gates/tok005_dryrun_*.md`；联调阶段：`tests/supply/sec_sup_boundary_report_2026-03-30.md`（staging回填） |
|
||||
| TOK-006 | staging 一键回归（SUP-004~SUP-007 + TOK） | `QA` + `PLAT` | 2026-04-01 | TOK-005 | 全链路通过且无 mock 依赖 | 开发阶段：`scripts/supply-gate/tok006_gate_bundle.sh` + `scripts/ci/superpowers_stage_validate.sh` + `reports/gates/tok006_gate_bundle_*.md` + `reports/gates/superpowers_stage_validation_*.md` + `reports/gates/tok006_release_decision_onepager_template_v1_2026-03-30.md`；联调阶段：`reports/gates/sup_run_all_staging_*.log` + 实测单页判定报告 |
|
||||
| TOK-007 | 发布门禁复审（并入 EXP-006 决议） | `ARCH` + `QA` + `SEC` | 2026-04-03 | TOK-006 | F-04 关闭，生产决议可重新评估 | 开发阶段：`scripts/ci/tok007_release_recheck.sh` + `scripts/ci/final_decision_consistency_check.sh` + `scripts/ci/tok007_generate_final_decision_candidate.sh` + `review/outputs/tok007_release_recheck_*.md` + `review/outputs/final_decision_candidate_from_tok007_*.md` + `reports/gates/final_decision_consistency_*.md`；联调阶段：`review/final_decision_2026-03-31.md`（复审回填） |
|
||||
|
||||
## 5. 验收门禁（每日/每周）
|
||||
|
||||
## 5.1 Daily Gate（每日 18:00）
|
||||
@@ -174,6 +200,10 @@
|
||||
11. 供应侧 UI Gate 是否全绿（`UI-SUP-ACC-* / UI-SUP-PKG-* / UI-SUP-SET-*`）。
|
||||
12. 供应侧凭证边界专项（`SEC-SUP-*`）是否全绿（失败即 P0）。
|
||||
13. 四专家整改链路（XR-001~XR-003）是否全绿（未完成即禁止进入 SUP-008 结论环节）。
|
||||
14. 数据库补丁任务（DB-001~DB-003）是否按阶段达成（未完成即禁止升波）。
|
||||
15. 依赖兼容审计四件套是否完整（缺任一项即阻断发布）。
|
||||
16. 分阶段质量门禁 `M-018/M-019` 是否持续 = 100%（否则回退到失败阶段）。
|
||||
17. token 运行态链路（TOK-002~TOK-006）是否完成（未完成即禁止生产 GO）。
|
||||
|
||||
## 5.2 Weekly Gate（2026-03-24 / 2026-03-31）
|
||||
|
||||
@@ -184,6 +214,10 @@
|
||||
5. 是否完成当周专家评审并关闭必须整改项。
|
||||
6. 供应侧 Gate（SUP-004~SUP-008）是否完成并出具结论。
|
||||
7. 四专家复核链路（XR-001~XR-005）是否完成并形成签署结论。
|
||||
8. DB/依赖质量链路（DB-* / DEP-*）是否全量关闭。
|
||||
9. 依赖兼容审计指标 `M-017` 是否连续 7 天达标。
|
||||
10. 阶段质量与追踪覆盖指标 `M-018/M-019` 是否连续 7 天达标。
|
||||
11. token 运行态审计缺口（`TOK-REAL-001~003`）是否全部关闭。
|
||||
|
||||
## 6. 风险与阻断规则
|
||||
|
||||
|
||||
@@ -7,6 +7,9 @@ info:
|
||||
安全边界要求：
|
||||
1) 仅接受平台鉴权头（Authorization），不接受 query key 鉴权。
|
||||
2) 任何响应不得返回可复用上游凭证明文片段。
|
||||
变更日志：
|
||||
- 2026-03-27：新增幂等请求头组件与写操作挂载；补充 409/202 幂等语义示例。
|
||||
- 2026-03-27：命名策略调整为 `/supply` 主路径；`/supplier` 保留为兼容 alias。
|
||||
servers:
|
||||
- url: https://api.example.com
|
||||
description: Production
|
||||
@@ -48,6 +51,9 @@ paths:
|
||||
tags: [SupplyAccounts]
|
||||
summary: 创建供应账号
|
||||
operationId: createSupplyAccount
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/XRequestIdHeader'
|
||||
- $ref: '#/components/parameters/IdempotencyKeyHeader'
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
@@ -61,10 +67,14 @@ paths:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/CreateSupplyAccountResponse'
|
||||
'202':
|
||||
$ref: '#/components/responses/AcceptedInProgress'
|
||||
'400':
|
||||
$ref: '#/components/responses/BadRequest'
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'409':
|
||||
$ref: '#/components/responses/Conflict'
|
||||
'422':
|
||||
$ref: '#/components/responses/BusinessError'
|
||||
/api/v1/supply/accounts/{accountId}/activate:
|
||||
@@ -175,6 +185,8 @@ paths:
|
||||
operationId: publishSupplyPackage
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/PackageIdParam'
|
||||
- $ref: '#/components/parameters/XRequestIdHeader'
|
||||
- $ref: '#/components/parameters/IdempotencyKeyHeader'
|
||||
responses:
|
||||
'200':
|
||||
description: 发布成功
|
||||
@@ -182,6 +194,8 @@ paths:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/SupplyPackageStatusResponse'
|
||||
'202':
|
||||
$ref: '#/components/responses/AcceptedInProgress'
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'404':
|
||||
@@ -233,6 +247,9 @@ paths:
|
||||
tags: [SupplyPackages]
|
||||
summary: 批量调价
|
||||
operationId: batchUpdateSupplyPackagePrice
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/XRequestIdHeader'
|
||||
- $ref: '#/components/parameters/IdempotencyKeyHeader'
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
@@ -246,6 +263,8 @@ paths:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/BatchUpdateSupplyPackagePriceResponse'
|
||||
'202':
|
||||
$ref: '#/components/responses/AcceptedInProgress'
|
||||
'400':
|
||||
$ref: '#/components/responses/BadRequest'
|
||||
'401':
|
||||
@@ -271,11 +290,35 @@ paths:
|
||||
'404':
|
||||
$ref: '#/components/responses/NotFound'
|
||||
|
||||
/api/v1/supply/billing:
|
||||
get:
|
||||
tags: [SupplierBilling]
|
||||
summary: 查询供应方账单汇总（canonical）
|
||||
operationId: getSupplyBilling
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/StartDateParam'
|
||||
- $ref: '#/components/parameters/EndDateParam'
|
||||
- $ref: '#/components/parameters/PageParam'
|
||||
- $ref: '#/components/parameters/PageSizeParam'
|
||||
responses:
|
||||
'200':
|
||||
description: 查询成功
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/SupplierBillingResponse'
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
|
||||
/api/v1/supplier/billing:
|
||||
get:
|
||||
tags: [SupplierBilling]
|
||||
summary: 查询供应方账单汇总
|
||||
operationId: getSupplierBilling
|
||||
summary: 查询供应方账单汇总（alias，兼容路径）
|
||||
description: |
|
||||
Deprecated alias of `/api/v1/supply/billing`.
|
||||
仅用于历史客户端兼容，不新增能力字段。
|
||||
deprecated: true
|
||||
operationId: getSupplierBillingAlias
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/StartDateParam'
|
||||
- $ref: '#/components/parameters/EndDateParam'
|
||||
@@ -296,6 +339,9 @@ paths:
|
||||
tags: [SupplySettlements]
|
||||
summary: 发起提现申请
|
||||
operationId: createSupplySettlementWithdraw
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/XRequestIdHeader'
|
||||
- $ref: '#/components/parameters/IdempotencyKeyHeader'
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
@@ -309,6 +355,8 @@ paths:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/CreateWithdrawResponse'
|
||||
'202':
|
||||
$ref: '#/components/responses/AcceptedInProgress'
|
||||
'400':
|
||||
$ref: '#/components/responses/BadRequest'
|
||||
'401':
|
||||
@@ -322,6 +370,8 @@ paths:
|
||||
operationId: cancelSupplySettlementWithdraw
|
||||
parameters:
|
||||
- $ref: '#/components/parameters/SettlementIdParam'
|
||||
- $ref: '#/components/parameters/XRequestIdHeader'
|
||||
- $ref: '#/components/parameters/IdempotencyKeyHeader'
|
||||
responses:
|
||||
'200':
|
||||
description: 撤销成功
|
||||
@@ -329,6 +379,8 @@ paths:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/SupplySettlementStatusResponse'
|
||||
'202':
|
||||
$ref: '#/components/responses/AcceptedInProgress'
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'404':
|
||||
@@ -428,6 +480,24 @@ components:
|
||||
minimum: 1
|
||||
maximum: 200
|
||||
default: 20
|
||||
XRequestIdHeader:
|
||||
name: X-Request-Id
|
||||
in: header
|
||||
required: true
|
||||
description: 客户端请求幂等追踪ID（全链路唯一）
|
||||
schema:
|
||||
type: string
|
||||
minLength: 8
|
||||
maxLength: 128
|
||||
IdempotencyKeyHeader:
|
||||
name: Idempotency-Key
|
||||
in: header
|
||||
required: true
|
||||
description: 写操作幂等键（同资源同动作语义唯一）
|
||||
schema:
|
||||
type: string
|
||||
minLength: 8
|
||||
maxLength: 128
|
||||
responses:
|
||||
BadRequest:
|
||||
description: 参数错误
|
||||
@@ -453,6 +523,34 @@ components:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
examples:
|
||||
idempotencyPayloadMismatch:
|
||||
summary: 幂等键命中但请求体不一致
|
||||
value:
|
||||
request_id: req_20260327_001
|
||||
error:
|
||||
code: IDEMPOTENCY_PAYLOAD_MISMATCH
|
||||
message: idempotency key replay with different payload
|
||||
details:
|
||||
retryable: false
|
||||
expected_action: reuse_same_payload_or_new_idempotency_key
|
||||
AcceptedInProgress:
|
||||
description: 首次请求仍在处理，请按建议间隔重试
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/ErrorResponse'
|
||||
examples:
|
||||
idempotencyInProgress:
|
||||
summary: 幂等处理中重放
|
||||
value:
|
||||
request_id: req_20260327_002
|
||||
error:
|
||||
code: IDEMPOTENCY_IN_PROGRESS
|
||||
message: request is processing
|
||||
details:
|
||||
retry_after_ms: 2000
|
||||
retryable: true
|
||||
BusinessError:
|
||||
description: 业务校验失败
|
||||
content:
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# 供应侧按钮级 PRD 分解（首批 3 个核心页面）
|
||||
|
||||
- 版本：v1.0（草案）
|
||||
- 日期：2026-03-25
|
||||
- 版本：v1.1（冻结）
|
||||
- 日期：2026-03-27
|
||||
- 适用范围：供应侧 S0/S1 首批上线页面
|
||||
- 关联 SSOT：
|
||||
- `llm_gateway_subapi_evolution_plan_v4_2_2026-03-24.md`
|
||||
@@ -233,9 +233,15 @@
|
||||
|
||||
---
|
||||
|
||||
## 9. 待拍板项（进入 PRD v1.0 前必须确认）
|
||||
## 9. 已决议项（2026-03-27）
|
||||
|
||||
1. `POST /api/v1/supply/*` 系列接口是否按本稿命名冻结。
|
||||
2. 提现金额风控阈值（单笔/单日）与冷却期。
|
||||
3. 套餐“下架”与“暂停”的财务影响口径是否一致。
|
||||
4. 供应方是否允许批量导入账号（当前建议 S1 后）。
|
||||
决议依据：
|
||||
1. `docs/product/supply_prd_pending_to_decision_map_v1_2026-03-27.md`
|
||||
2. `review/outputs/supply_prd_decision_meeting_minutes_2026-03-27.md`
|
||||
|
||||
| 决议ID | 原待拍板项 | 决议结论 | 执行动作 |
|
||||
|---|---|---|---|
|
||||
| DEC-001 | `POST /api/v1/supply/*` 系列接口是否按本稿命名冻结 | 冻结 `/api/v1/supply/*` 为供应侧主路径；`/api/v1/supplier/billing` 作为兼容路径保留，待 F 阶段统一命名策略 | 在 OpenAPI 变更日志记录主路径与兼容路径策略 |
|
||||
| DEC-002 | 提现金额风控阈值（单笔/单日）与冷却期 | S1 阶段阈值冻结：单笔 `<= 50,000 CNY`，单日累计 `<= 200,000 CNY`，同账户提现冷却期 `15 分钟` | 在结算风控与测试用例中同步阈值断言 |
|
||||
| DEC-003 | 套餐“下架”与“暂停”的财务影响口径是否一致 | 不一致：`暂停`仅阻断新购，存量订单不变；`下架`阻断新购并触发 T+1 财务核对任务 | 在结算页与审计事件中区分 `pause/unlist` 财务语义 |
|
||||
| DEC-004 | 供应方是否允许批量导入账号 | 不允许进入 S0/S1 主路径；改为 S2 评审项，仅可在受控灰度与白名单下试点 | 移出当前发布门禁范围，纳入后续路线图 |
|
||||
|
||||
@@ -51,6 +51,18 @@ cd "/home/long/project/立交桥"
|
||||
bash "scripts/supply-gate/run_all.sh"
|
||||
```
|
||||
|
||||
真实 staging 推荐使用（含占位值与可达性预检）：
|
||||
|
||||
```bash
|
||||
cd "/home/long/project/立交桥"
|
||||
bash "scripts/supply-gate/staging_precheck_and_run.sh" "scripts/supply-gate/.env"
|
||||
```
|
||||
|
||||
说明：
|
||||
1. `staging_precheck_and_run.sh` 默认会先执行 `M-021` 预检（token runtime readiness）。
|
||||
2. `staging_precheck_and_run.sh` 默认会再执行 `TOK-005 dry-run`。
|
||||
3. 如需临时跳过可设置：`ENABLE_M021_PRECHECK=0` 或 `ENABLE_TOK005_DRYRUN=0`。
|
||||
|
||||
---
|
||||
|
||||
## 2. SUP-004 账号挂载链路（UI-SUP-ACC-001~006）
|
||||
@@ -163,3 +175,536 @@ bash "scripts/supply-gate/sup007_boundary.sh"
|
||||
1. 结论（PASS/FAIL/BLOCKED）
|
||||
2. 证据路径（json/screenshot/log）
|
||||
3. 责任人签字
|
||||
|
||||
---
|
||||
|
||||
## 7. 依赖兼容审计命令（M-017）
|
||||
|
||||
执行脚本：
|
||||
|
||||
```bash
|
||||
cd "/home/long/project/立交桥"
|
||||
./scripts/ci/dependency-audit-check.sh 2026-03-27
|
||||
```
|
||||
|
||||
最低断言：
|
||||
|
||||
1. 四件套文件存在且非空：
|
||||
1. `reports/dependency/sbom_2026-03-27.spdx.json`
|
||||
2. `reports/dependency/lockfile_diff_2026-03-27.md`
|
||||
3. `reports/dependency/compat_matrix_2026-03-27.md`
|
||||
4. `reports/dependency/risk_register_2026-03-27.md`
|
||||
2. 输出结果为 `PASS`，并生成 `dependency_audit_result_2026-03-27.md`。
|
||||
|
||||
---
|
||||
|
||||
## 8. 分阶段门禁失败回退演练（M-018/M-019）
|
||||
|
||||
执行脚本：
|
||||
|
||||
```bash
|
||||
cd "/home/long/project/立交桥"
|
||||
./scripts/ci/stage-gate-drill.sh G3 2026-03-27
|
||||
```
|
||||
|
||||
最低断言：
|
||||
|
||||
1. G3 失败后必须触发回退到 G2。
|
||||
2. 后续阶段冻结，不允许继续升波。
|
||||
3. 生成原始日志与演练报告：
|
||||
1. `reports/gates/stage_gate_drill_2026-03-27.log`
|
||||
2. `reports/gates/stage_gate_drift_drill_report_2026-03-27.md`
|
||||
|
||||
---
|
||||
|
||||
## 9. 本地 Mock 联调模式（仅演练）
|
||||
|
||||
执行命令：
|
||||
|
||||
```bash
|
||||
cd "/home/long/project/立交桥"
|
||||
python3 "scripts/mock/supply_gateway_mock_server.py"
|
||||
```
|
||||
|
||||
另开终端执行：
|
||||
|
||||
```bash
|
||||
cd "/home/long/project/立交桥"
|
||||
bash "scripts/supply-gate/run_all.sh" "scripts/supply-gate/.env.local-mock"
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
1. 本模式仅用于脚本联调与产物验证，不代表 staging/生产可发布。
|
||||
2. 生产放行仍需在真实 staging 地址与真实短期 token 下复跑并验收。
|
||||
|
||||
---
|
||||
|
||||
## 10. TOK-005 凭证边界 Dry-Run（开发阶段）
|
||||
|
||||
执行命令：
|
||||
|
||||
```bash
|
||||
cd "/home/long/project/立交桥"
|
||||
bash "scripts/supply-gate/tok005_boundary_dryrun.sh" "scripts/supply-gate/.env"
|
||||
```
|
||||
|
||||
最低断言：
|
||||
|
||||
1. `go test ./...` 在 `platform-token-runtime` 通过。
|
||||
2. Query key 外拒规则存在（`key/api_key/token`）。
|
||||
3. 审计脱敏断言存在且通过（禁止敏感值落审计）。
|
||||
4. TOK 用例可执行覆盖完整（`TOK-LIFE-001~008` 与 `TOK-AUD-001~007`）。
|
||||
5. staging 就绪性检查结果可追溯（NO 时需明确阻塞原因）。
|
||||
|
||||
证据输出：
|
||||
|
||||
1. `reports/gates/tok005_dryrun_*.md`
|
||||
2. `reports/gates/tok005_dryrun_*.log`
|
||||
3. `tests/supply/artifacts/tok005_dryrun_*/go_test_output.txt`
|
||||
|
||||
说明：
|
||||
|
||||
1. Dry-run 仅用于开发阶段门禁前置验证，不可替代真实 staging 联调结论。
|
||||
2. 真实放行仍以 `staging_precheck_and_run.sh` + `SUP-007/TOK-005` 实测结果为准。
|
||||
|
||||
---
|
||||
|
||||
## 11. TOK-006 统一 Gate 汇总（Dry-Run + SUP-004~007）
|
||||
|
||||
执行命令：
|
||||
|
||||
```bash
|
||||
cd "/home/long/project/立交桥"
|
||||
bash "scripts/supply-gate/tok006_gate_bundle.sh" "scripts/supply-gate/.env"
|
||||
```
|
||||
|
||||
可选开关：
|
||||
|
||||
```bash
|
||||
# 默认 1：先执行 TOK-005 dry-run
|
||||
ENABLE_TOK005_DRYRUN=1
|
||||
|
||||
# 默认 0：仅汇总现有 SUP 报告，不触发 run_all
|
||||
ENABLE_SUP_RUN=0
|
||||
```
|
||||
|
||||
最低断言：
|
||||
|
||||
1. 输出单页 gate 汇总报告（含 TOK-005 + SUP-004~007）。
|
||||
2. 生成明确发布判定：`GO / CONDITIONAL_GO / NO_GO`。
|
||||
3. 若存在 mock 证据或 `staging readiness != YES`，不得输出 GO。
|
||||
|
||||
证据输出：
|
||||
|
||||
1. `reports/gates/tok006_gate_bundle_*.md`
|
||||
2. `reports/gates/tok006_gate_bundle_*.log`
|
||||
3. `reports/gates/tok006_release_decision_onepager_template_v1_2026-03-30.md`（模板）
|
||||
|
||||
---
|
||||
|
||||
## 12. Superpowers 严格分阶段验证（代码+脚本+门禁）
|
||||
|
||||
执行命令：
|
||||
|
||||
```bash
|
||||
cd "/home/long/project/立交桥"
|
||||
bash "scripts/ci/superpowers_stage_validate.sh"
|
||||
```
|
||||
|
||||
阶段定义（当前实现）：
|
||||
|
||||
1. PHASE-01：TOK 运行时代码测试（Go 单测）
|
||||
2. PHASE-02：SUP-004~SUP-007 本地 mock 脚本联调
|
||||
3. PHASE-03：TOK-005 凭证边界 dry-run（mock 环境）
|
||||
4. PHASE-04：TOK-006 统一 Gate 汇总
|
||||
5. PHASE-05：依赖兼容审计门禁（M-017）
|
||||
6. PHASE-06：分阶段回退演练门禁（M-018/M-019）
|
||||
7. PHASE-07：真实 staging 预检（无真值时应 DEFERRED）
|
||||
8. PHASE-08：每日指标快照生成（M-017/M-018/M-019）
|
||||
9. PHASE-09：7日趋势报告生成（M-017/M-018/M-019）
|
||||
10. PHASE-10：token 运行态就绪度检查（M-021）
|
||||
|
||||
结果判定：
|
||||
|
||||
1. 任一阶段 FAIL => `NO_GO`
|
||||
2. 无 FAIL 且存在 DEFERRED => `CONDITIONAL_GO`
|
||||
3. 全部 PASS => `GO`
|
||||
|
||||
可选环境变量：
|
||||
|
||||
```bash
|
||||
# PHASE-07 使用的环境文件，默认 scripts/supply-gate/.env
|
||||
STAGING_ENV_FILE="scripts/supply-gate/.env"
|
||||
```
|
||||
|
||||
证据输出：
|
||||
|
||||
1. `reports/gates/superpowers_stage_validation_*.md`
|
||||
2. `reports/gates/superpowers_stage_validation_*.log`
|
||||
3. `tests/supply/artifacts/superpowers_stage_validation_*/phase*.log`
|
||||
|
||||
---
|
||||
|
||||
## 13. TOK-007 发布门禁复审（自动汇总）
|
||||
|
||||
执行命令：
|
||||
|
||||
```bash
|
||||
cd "/home/long/project/立交桥"
|
||||
bash "scripts/ci/tok007_release_recheck.sh"
|
||||
```
|
||||
|
||||
最低断言：
|
||||
|
||||
1. 自动读取最新 `TOK-006` 汇总报告。
|
||||
2. 自动读取最新 `Superpowers` 阶段验证报告。
|
||||
3. 自动读取 `SUP Gate` 汇总评审结论。
|
||||
4. 输出复审结论（`GO / CONDITIONAL GO / NO-GO`）与动作建议。
|
||||
|
||||
证据输出：
|
||||
|
||||
1. `review/outputs/tok007_release_recheck_*.md`
|
||||
2. `reports/gates/tok007_release_recheck_*.log`
|
||||
|
||||
---
|
||||
|
||||
## 14. 最终决议一致性校验（Final vs TOK-007）
|
||||
|
||||
执行命令：
|
||||
|
||||
```bash
|
||||
cd "/home/long/project/立交桥"
|
||||
bash "scripts/ci/final_decision_consistency_check.sh"
|
||||
```
|
||||
|
||||
最低断言：
|
||||
|
||||
1. 可解析 `final_decision`、`TOK-007`、`superpowers_stage_validation` 三类结论。
|
||||
2. 若 `final_decision` 与 `TOK-007` 不一致，输出 `WARN`（不自动覆盖签署结论）。
|
||||
3. 若任一来源不可解析，输出 `FAIL` 并阻断自动流程。
|
||||
|
||||
证据输出：
|
||||
|
||||
1. `reports/gates/final_decision_consistency_*.md`
|
||||
2. `reports/gates/final_decision_consistency_*.log`
|
||||
|
||||
---
|
||||
|
||||
## 15. 最终决议候选稿生成（不覆盖签署原件）
|
||||
|
||||
执行命令：
|
||||
|
||||
```bash
|
||||
cd "/home/long/project/立交桥"
|
||||
bash "scripts/ci/tok007_generate_final_decision_candidate.sh"
|
||||
```
|
||||
|
||||
最低断言：
|
||||
|
||||
1. 输入源必须包括 `review/final_decision_2026-03-31.md` 与最新 `tok007_release_recheck_*.md`。
|
||||
2. 输出文件位于 `review/outputs/final_decision_candidate_from_tok007_*.md`。
|
||||
3. 仅生成候选稿，不覆盖原签署文件。
|
||||
|
||||
证据输出：
|
||||
|
||||
1. `review/outputs/final_decision_candidate_from_tok007_*.md`
|
||||
2. `reports/gates/tok007_generate_candidate_*.log`
|
||||
|
||||
---
|
||||
|
||||
## 16. M-021 Token Runtime 就绪度检查
|
||||
|
||||
执行命令：
|
||||
|
||||
```bash
|
||||
cd "/home/long/project/立交桥"
|
||||
bash "scripts/ci/token_runtime_readiness_check.sh" "$(date +%F)"
|
||||
```
|
||||
|
||||
可选开关：
|
||||
|
||||
```bash
|
||||
# 默认 0：跳过本地端口冒烟（适配受限沙箱环境）
|
||||
ENABLE_TOKEN_RUNTIME_SMOKE=0
|
||||
|
||||
# 置 1：执行本地服务启动 + issue + audit-events 冒烟
|
||||
ENABLE_TOKEN_RUNTIME_SMOKE=1
|
||||
|
||||
# 可选：指定冒烟起始端口（默认 18082，若被占用会自动顺延）
|
||||
TOKEN_RUNTIME_SMOKE_PORT=18082
|
||||
```
|
||||
|
||||
最低断言：
|
||||
|
||||
1. 输出 `token_runtime_readiness_*.md` 报告并给出百分比结果。
|
||||
2. 运行态代码与契约工件完整（API入口/HTTP处理/OpenAPI/Dockerfile）。
|
||||
3. `platform-token-runtime` 测试与构建均通过。
|
||||
4. 若就绪度 `<100%`，脚本必须返回失败并阻断后续门禁。
|
||||
|
||||
证据输出：
|
||||
|
||||
1. `reports/gates/token_runtime_readiness_*.md`
|
||||
2. `reports/gates/token_runtime_readiness_*.log`
|
||||
3. `reports/gates/token_runtime_go_test_*.log`
|
||||
4. `reports/gates/token_runtime_go_build_*.log`
|
||||
|
||||
---
|
||||
|
||||
## 17. Token 审计事件查询（TOK-REAL-002）
|
||||
|
||||
本地服务启动：
|
||||
|
||||
```bash
|
||||
cd "/home/long/project/立交桥/platform-token-runtime"
|
||||
export PATH="/home/long/project/立交桥/.tools/go-current/bin:$PATH"
|
||||
go run ./cmd/platform-token-runtime
|
||||
```
|
||||
|
||||
审计查询示例：
|
||||
|
||||
```bash
|
||||
curl -sS "http://127.0.0.1:18081/api/v1/platform/tokens/audit-events?limit=20" \
|
||||
-H "X-Request-Id: req-audit-query-demo"
|
||||
```
|
||||
|
||||
最低断言：
|
||||
|
||||
1. 返回 `200`，且结构包含 `request_id/data.total/data.items`。
|
||||
2. 返回项包含 `event_id/event_name/request_id/route/result_code/created_at`。
|
||||
3. 响应不包含 `access_token` 或上游敏感凭证明文。
|
||||
|
||||
证据输出：
|
||||
|
||||
1. `platform-token-runtime/internal/httpapi/token_api_test.go`（自动化用例）
|
||||
2. `reports/gates/token_runtime_readiness_*.md`（检查项 `TOK-REAL-002-C1/C2`）
|
||||
|
||||
---
|
||||
|
||||
## 18. Staging 证据自动回填草稿
|
||||
|
||||
执行命令：
|
||||
|
||||
```bash
|
||||
cd "/home/long/project/立交桥"
|
||||
bash "scripts/ci/staging_evidence_autofill.sh"
|
||||
```
|
||||
|
||||
可选参数（用于锁定本次流水证据，避免误取历史 latest）：
|
||||
|
||||
```bash
|
||||
bash "scripts/ci/staging_evidence_autofill.sh" \
|
||||
--staging-run-log "reports/gates/staging_run_2026-03-30_184432.log" \
|
||||
--stage-report "reports/gates/superpowers_stage_validation_2026-03-30_184433.md" \
|
||||
--token-readiness "reports/gates/token_runtime_readiness_2026-03-30_184435.md" \
|
||||
--tok007-report "review/outputs/tok007_release_recheck_2026-03-30_184436.md" \
|
||||
--pipeline-report "reports/gates/superpowers_release_pipeline_2026-03-30_184434.md"
|
||||
```
|
||||
|
||||
最低断言：
|
||||
|
||||
1. 自动抽取 `PHASE-07`、`M-013~M-016`、`M-021` 与 TOK-007 机判结论。
|
||||
2. 输出证据路径清单，便于人工补齐与签署。
|
||||
3. 不得自动上调为 GO，仅生成草稿。
|
||||
|
||||
证据输出：
|
||||
|
||||
1. `reports/gates/staging_token_go_evidence_autofill_*.md`
|
||||
2. `reports/gates/staging_token_go_evidence_autofill_*.log`
|
||||
|
||||
---
|
||||
|
||||
## 19. 一键 Staging 发布流水
|
||||
|
||||
执行命令：
|
||||
|
||||
```bash
|
||||
cd "/home/long/project/立交桥"
|
||||
bash "scripts/ci/staging_release_pipeline.sh" "scripts/supply-gate/.env"
|
||||
```
|
||||
|
||||
local/mock 防误跑（默认拦截）：
|
||||
|
||||
```bash
|
||||
# 仅当明确要做 local/mock 演练时启用
|
||||
ALLOW_LOCAL_MOCK_STAGING=1 \
|
||||
bash "scripts/ci/staging_release_pipeline.sh" "scripts/supply-gate/.env.local-mock"
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
1. STEP-01：`staging_precheck_and_run.sh`（含 M-021/TOK-005/SUP run_all）。
|
||||
2. STEP-02：`superpowers_release_pipeline.sh`（使用 `STAGING_ENV_FILE`）。
|
||||
3. STEP-03：`staging_evidence_autofill.sh` 自动生成回填草稿（显式绑定本次流水证据文件）。
|
||||
4. 检测到 local/mock env 且未设置 `ALLOW_LOCAL_MOCK_STAGING=1` 时，脚本应直接失败，防止误把演练结果当成真实 staging 证据。
|
||||
|
||||
可选监控（默认关闭、非阻断）：
|
||||
|
||||
```bash
|
||||
ENABLE_MINIMAX_MONITORING=1 \
|
||||
MINIMAX_ENV_FILE="scripts/supply-gate/.env.minimax-dev" \
|
||||
MINIMAX_RUN_ACTIVE_SMOKE=0 \
|
||||
bash "scripts/ci/superpowers_release_pipeline.sh"
|
||||
```
|
||||
|
||||
说明：
|
||||
1. 开启后会在 `STEP-05` 额外执行 Minimax 每日快照 + 7 日趋势生成。
|
||||
2. 该步骤是监控辅助项，失败仅记 `WARN`，不阻断 SUP 主门禁判定。
|
||||
|
||||
证据输出：
|
||||
|
||||
1. `reports/gates/staging_release_pipeline_*.md`
|
||||
2. `reports/gates/staging_release_pipeline_*.log`
|
||||
|
||||
---
|
||||
|
||||
## 20. Minimax 上游独立 Smoke（不并入 SUP 发布门禁）
|
||||
|
||||
执行命令：
|
||||
|
||||
```bash
|
||||
cd "/home/long/project/立交桥"
|
||||
bash "scripts/supply-gate/minimax_upstream_smoke.sh" "scripts/supply-gate/.env.minimax-dev"
|
||||
```
|
||||
|
||||
可选环境变量：
|
||||
|
||||
```bash
|
||||
# 默认 /v1/messages
|
||||
MINIMAX_SMOKE_PATH="/v1/messages"
|
||||
|
||||
# 默认 minimax-smoke-model（可替换为实际模型）
|
||||
MINIMAX_SMOKE_MODEL="your-model-id"
|
||||
|
||||
# 默认 20 秒
|
||||
MINIMAX_TIMEOUT_SECONDS=20
|
||||
```
|
||||
|
||||
最低断言：
|
||||
|
||||
1. 输出 `reports/gates/minimax_upstream_smoke_*.md` 报告。
|
||||
2. 报告必须包含 base 连通探测与 active 鉴权探测两段结果。
|
||||
3. 分类规则需区分：`PASS / PASS_AUTH_REACHED / FAIL_AUTH / FAIL_PATH / FAIL_NETWORK`。
|
||||
|
||||
说明：
|
||||
|
||||
1. 该脚本仅用于“上游（Minimax）连通与鉴权可达性”验证。
|
||||
2. 该脚本不参与 `SUP-004~SUP-007` 业务契约发布门禁判定。
|
||||
3. 若 Minimax 返回 `404/405`，优先检查 `API_BASE_URL + MINIMAX_SMOKE_PATH` 组合是否正确。
|
||||
|
||||
---
|
||||
|
||||
## 21. Minimax 上游每日快照（CI 汇总）
|
||||
|
||||
执行命令：
|
||||
|
||||
```bash
|
||||
cd "/home/long/project/立交桥"
|
||||
bash "scripts/ci/minimax_upstream_daily_snapshot.sh" "$(date +%F)" "scripts/supply-gate/.env.minimax-dev"
|
||||
```
|
||||
|
||||
可选环境变量：
|
||||
|
||||
```bash
|
||||
# 默认 0：仅汇总最新 smoke 报告，不触发网络请求
|
||||
RUN_ACTIVE_SMOKE=0
|
||||
|
||||
# 置 1：执行一次实时 smoke 后再汇总
|
||||
RUN_ACTIVE_SMOKE=1
|
||||
```
|
||||
|
||||
最低断言：
|
||||
|
||||
1. 生成 `reports/gates/minimax_upstream_daily_snapshot_*.md`。
|
||||
2. 生成/更新 `reports/gates/minimax_upstream_daily_snapshots.csv`。
|
||||
3. 明确标注 `RUN_ACTIVE_SMOKE` 取值，区分“实时探测”与“仅汇总”。
|
||||
4. 默认优先汇总“非 dry-run”最新报告，避免将联调证据误当真实上游证据。
|
||||
|
||||
说明：
|
||||
|
||||
1. 该快照是“上游可达性趋势”证据，不替代 SUP 发布门禁。
|
||||
2. 建议在定时任务中默认 `RUN_ACTIVE_SMOKE=0`，将实时探测作为受控任务执行。
|
||||
3. 若仅存在 `PASS_DRY_RUN` 报告，快照状态应为 `CONDITIONAL_PASS`。
|
||||
|
||||
---
|
||||
|
||||
## 22. Minimax 上游 7 日趋势报告
|
||||
|
||||
执行命令：
|
||||
|
||||
```bash
|
||||
cd "/home/long/project/立交桥"
|
||||
bash "scripts/ci/minimax_upstream_trend_report.sh" "$(date +%F)"
|
||||
```
|
||||
|
||||
最低断言：
|
||||
|
||||
1. 生成 `reports/gates/minimax_upstream_trend_7d_*.md`。
|
||||
2. 报告包含最近 7 条（不足 7 条按实际）快照的状态统计。
|
||||
3. 趋势状态遵循 `PASS_7D / CONDITIONAL_7D / NOT_READY / INSUFFICIENT_DATA`。
|
||||
|
||||
说明：
|
||||
|
||||
1. 该趋势报告用于 F-03（连续观测证据）收敛，不替代 staging 发布门禁。
|
||||
2. 建议与第 21 节每日快照搭配执行，形成“日报 + 周趋势”组合。
|
||||
|
||||
---
|
||||
|
||||
## 23. 一键生成本地 STG 环境（owner/viewer/admin token）
|
||||
|
||||
执行命令：
|
||||
|
||||
```bash
|
||||
cd "/home/long/project/立交桥"
|
||||
bash "scripts/ci/generate_local_staging_env.sh" "scripts/supply-gate/.env.staging-real"
|
||||
```
|
||||
|
||||
可选环境变量：
|
||||
|
||||
```bash
|
||||
# 默认 http://127.0.0.1:18080
|
||||
API_BASE_URL_VALUE="http://127.0.0.1:18080"
|
||||
|
||||
# 默认 http://127.0.0.1:18081
|
||||
TOKEN_RUNTIME_URL="http://127.0.0.1:18081"
|
||||
|
||||
# 默认 7200 秒（2小时）
|
||||
TOKEN_TTL_SECONDS=7200
|
||||
|
||||
# 默认 1：若 token runtime 不可用则自动拉起临时实例
|
||||
START_RUNTIME_IF_NEEDED=1
|
||||
```
|
||||
|
||||
最低断言：
|
||||
|
||||
1. 生成 `scripts/supply-gate/.env.staging-real`（权限 `600`）。
|
||||
2. 文件包含 `OWNER_BEARER_TOKEN / VIEWER_BEARER_TOKEN / ADMIN_BEARER_TOKEN` 三类 token。
|
||||
3. 生成摘要报告 `reports/gates/local_staging_env_generation_*.md`（仅 hash，不泄露明文 token）。
|
||||
|
||||
说明：
|
||||
|
||||
1. 该脚本生成的是“本地开发/联调用”平台 token，非外部 LLM 厂商 key。
|
||||
2. 切换真实 staging 时，只需替换 `API_BASE_URL_VALUE` 并重新执行脚本即可刷新 token 与 env。
|
||||
|
||||
---
|
||||
|
||||
## 24. 真实 STG 就绪度检查（地址+token+可达性）
|
||||
|
||||
执行命令：
|
||||
|
||||
```bash
|
||||
cd "/home/long/project/立交桥"
|
||||
bash "scripts/ci/staging_real_readiness_check.sh" "scripts/supply-gate/.env.staging-real"
|
||||
```
|
||||
|
||||
最低断言：
|
||||
|
||||
1. `API_BASE_URL` 非占位值，且不是 `localhost/127.0.0.1`。
|
||||
2. 三类 token 非空且非占位值。
|
||||
3. `API_BASE_URL` 基础可达性检查通过（`curl -I` 非 `000`）。
|
||||
4. 生成报告 `reports/gates/staging_real_readiness_*.md`。
|
||||
|
||||
说明：
|
||||
|
||||
1. 结果为 `READY` 才建议进入真实 STG 放行口径验证。
|
||||
2. 结果为 `BLOCKED` 时，应先修复地址或 token，再执行 `staging_release_pipeline.sh`。
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# 供应侧技术设计增强版（XR-001）
|
||||
|
||||
- 版本：v1.0
|
||||
- 日期：2026-03-25
|
||||
- 版本：v1.1
|
||||
- 日期：2026-03-27
|
||||
- 状态：生效（实施基线）
|
||||
- 目标：补齐供应侧关键写路径的幂等、并发、事务、不变量与可靠性闭环
|
||||
- 关联 SSOT：
|
||||
@@ -9,6 +9,7 @@
|
||||
- `acceptance_gate_single_source_v1_2026-03-18.md`
|
||||
- `supply_button_level_prd_v1_2026-03-25.md`
|
||||
- `supply_api_contract_openapi_draft_v1_2026-03-25.yaml`
|
||||
- `database_domain_model_and_governance_v1_2026-03-27.md`
|
||||
|
||||
---
|
||||
|
||||
@@ -38,6 +39,7 @@
|
||||
2. Header 必填：`Idempotency-Key`（长度 16-128）
|
||||
3. 幂等作用域：`tenant_id + operator_id + api_path + idempotency_key`
|
||||
4. 幂等有效期：`24h`（提现类可扩展到 `72h`）
|
||||
5. 契约落地状态：已在 OpenAPI 写操作路径挂载上述 header，并补充 `409/202` 幂等语义示例（2026-03-27）。
|
||||
|
||||
## 2.3 语义规范
|
||||
|
||||
@@ -91,7 +93,7 @@ create table if not exists supply_idempotency_record (
|
||||
|
||||
```sql
|
||||
create unique index if not exists uq_settlement_supplier_processing
|
||||
on supply_settlement(supplier_id)
|
||||
on supply_settlements(user_id)
|
||||
where status = 'processing';
|
||||
```
|
||||
|
||||
@@ -160,12 +162,12 @@ where status = 'processing';
|
||||
|
||||
| 页面按钮 | API | SLI | SLO | Error Budget |
|
||||
|---|---|---|---|---|
|
||||
| BTN-ACC-001 立即验证 | `/accounts/verify` | 可用率 + P95 | 可用率 >= 99.9%，P95 <= 800ms | 月度 0.1% |
|
||||
| BTN-ACC-002 提交挂载 | `/accounts` | 成功率 | 成功率 >= 99.5% | 月度 0.5% |
|
||||
| BTN-PKG-002 发布上架 | `/packages/{id}/publish` | 成功率 + 冲突率 | 成功率 >= 99.5%，冲突率 <= 0.3% | 月度 0.5% |
|
||||
| BTN-PKG-005 批量调价 | `/packages/batch-price` | 局部成功可解释率 | 明细可解释率 = 100% | 0 |
|
||||
| BTN-SET-002 发起提现 | `/settlements/withdraw` | 一致性 + 时延 | `billing_error_rate_pct<=0.1%`，P95<=1200ms | 与 M-004 联动 |
|
||||
| BTN-SET-003 撤销申请 | `/settlements/{id}/cancel` | 成功率 | 成功率 >= 99.9% | 月度 0.1% |
|
||||
| BTN-ACC-001 立即验证 | `/api/v1/supply/accounts/verify` | 可用率 + P95 | 可用率 >= 99.9%，P95 <= 800ms | 月度 0.1% |
|
||||
| BTN-ACC-002 提交挂载 | `/api/v1/supply/accounts` | 成功率 | 成功率 >= 99.5% | 月度 0.5% |
|
||||
| BTN-PKG-002 发布上架 | `/api/v1/supply/packages/{id}/publish` | 成功率 + 冲突率 | 成功率 >= 99.5%，冲突率 <= 0.3% | 月度 0.5% |
|
||||
| BTN-PKG-005 批量调价 | `/api/v1/supply/packages/batch-price` | 局部成功可解释率 | 明细可解释率 = 100% | 0 |
|
||||
| BTN-SET-002 发起提现 | `/api/v1/supply/settlements/withdraw` | 一致性 + 时延 | `billing_error_rate_pct<=0.1%`，P95<=1200ms | 与 M-004 联动 |
|
||||
| BTN-SET-003 撤销申请 | `/api/v1/supply/settlements/{id}/cancel` | 成功率 | 成功率 >= 99.9% | 月度 0.1% |
|
||||
|
||||
---
|
||||
|
||||
@@ -191,3 +193,18 @@ where status = 'processing';
|
||||
6. 证据层：执行日志、指标截图、审计抽样、签署记录齐全。
|
||||
|
||||
达到以上 6 项即视为 XR-001 关闭。
|
||||
|
||||
---
|
||||
|
||||
## 10. 跨域数据库约束（新增）
|
||||
|
||||
1. 供应域不是独立孤岛，必须依赖 Core/IAM/Auth/Billing/Audit 五域主表。
|
||||
2. 供应域关键表必须补齐三类字段：
|
||||
1. 加密字段：`*_cipher_algo`、`*_kms_key_alias`、`*_key_version`、`*_fingerprint`。
|
||||
2. 单位字段：`quota_unit`、`price_unit`、`amount_unit`、`currency_code`。
|
||||
3. 审计字段：`request_id`、`idempotency_key`、`audit_trace_id`、`created_ip`、`updated_ip`、`version`。
|
||||
3. 数据库实施顺序固定：
|
||||
1. `platform_core_schema_v1.sql`
|
||||
2. `supply_schema_v1.sql`
|
||||
3. `supply_schema_v1_patch_2026-03-27.sql`
|
||||
4. 未完成上述顺序与字段补齐，不得判定 XR-001 关闭。
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# 供应侧测试方案增强版（XR-002）
|
||||
|
||||
- 版本：v1.0
|
||||
- 日期：2026-03-25
|
||||
- 版本：v1.1
|
||||
- 日期：2026-03-27
|
||||
- 状态：生效（测试执行基线）
|
||||
- 目标：形成“需求-接口-测试-指标-门禁”全链路闭环，补齐并发与重放风险覆盖
|
||||
- 关联文档：
|
||||
@@ -35,22 +35,26 @@
|
||||
|
||||
## 2. 测试追踪矩阵（Requirement -> API -> Test -> Metric -> Gate）
|
||||
|
||||
| 需求ID | 需求描述 | API | 测试用例 | 验收指标 | 门禁映射 |
|
||||
|---|---|---|---|---|---|
|
||||
| R-ACC-001 | 账号凭证验证成功可视化 | `POST /accounts/verify` | UI-SUP-ACC-001 | 验证成功率 >=99.5% | SUP-004 |
|
||||
| R-ACC-002 | 挂载需风险确认与审计 | `POST /accounts` | UI-SUP-ACC-002 | 审计覆盖率=100% | SUP-004 |
|
||||
| R-ACC-003 | 账号状态不跳态 | `POST /accounts/{id}/activate/suspend` | UI-SUP-ACC-003/004 + INT-ACC-STATE-001 | 冲突可解释率=100% | SUP-004 |
|
||||
| R-ACC-004 | 活跃账号不可删除 | `DELETE /accounts/{id}` | UI-SUP-ACC-005 | 违规删除成功率=0 | SUP-004 |
|
||||
| R-PKG-001 | 草稿保存可追踪 | `POST /packages/draft` | UI-SUP-PKG-001 | 保存成功率>=99.5% | SUP-005 |
|
||||
| R-PKG-002 | 套餐发布满足保护价与状态约束 | `POST /packages/{id}/publish` | UI-SUP-PKG-002 + INT-PKG-INV-001 | 保护价违规放行率=0 | SUP-005 |
|
||||
| R-PKG-003 | 批量调价部分失败可回执 | `POST /packages/batch-price` | UI-SUP-PKG-005 | 明细完备率=100% | SUP-005 |
|
||||
| R-SET-001 | 提现发起防重复防双扣 | `POST /settlements/withdraw` | UI-SUP-SET-002 + CON-SET-001 | M-004/M-005 达标 | SUP-006 |
|
||||
| R-SET-002 | 处理中/已完成不可撤销 | `POST /settlements/{id}/cancel` | UI-SUP-SET-003 + INT-SET-STATE-001 | 跳态成功率=0 | SUP-006 |
|
||||
| R-SET-003 | 对账单导出不泄露敏感信息 | `GET /settlements/{id}/statement` | UI-SUP-SET-004 + SEC-SUP-001 | M-013=0 | SUP-006/SUP-007 |
|
||||
| R-SEC-001 | 仅平台凭证入站 | 全部北向 API | SEC-SUP-002 | M-014=100% | SUP-007 |
|
||||
| R-SEC-002 | 外部 query key 全拒绝 | 全部北向 API | SEC-SUP-002 | M-016=100% | SUP-007 |
|
||||
| R-SEC-003 | 需求方不可绕平台直连 | 出网策略与告警 | SEC-SUP-002 + SEC-DIRECT-001 | M-015=0 | SUP-007 |
|
||||
| R-UX-001 | 按钮可见性和禁用规则正确 | 三页面全部按钮 | UI-DESIGN-QA-001~020 | 按钮规则通过率=100% | SUP-003/SUP-008 |
|
||||
| 需求ID | 需求描述 | API | api_alias | 测试用例 | 验收指标 | 门禁映射 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| R-ACC-001 | 账号凭证验证成功可视化 | `POST /api/v1/supply/accounts/verify` | - | UI-SUP-ACC-001 | 验证成功率 >=99.5% | SUP-004 |
|
||||
| R-ACC-002 | 挂载需风险确认与审计 | `POST /api/v1/supply/accounts` | - | UI-SUP-ACC-002 | 审计覆盖率=100% | SUP-004 |
|
||||
| R-ACC-003 | 账号状态不跳态 | `POST /api/v1/supply/accounts/{accountId}/activate` / `POST /api/v1/supply/accounts/{accountId}/suspend` | `POST /api/v1/supply/accounts/{id}/activate` / `POST /api/v1/supply/accounts/{id}/suspend` | UI-SUP-ACC-003/004 + INT-ACC-STATE-001 | 冲突可解释率=100% | SUP-004 |
|
||||
| R-ACC-004 | 活跃账号不可删除 | `DELETE /api/v1/supply/accounts/{accountId}` | `DELETE /api/v1/supply/accounts/{id}` | UI-SUP-ACC-005 | 违规删除成功率=0 | SUP-004 |
|
||||
| R-PKG-001 | 草稿保存可追踪 | `POST /api/v1/supply/packages/draft` | - | UI-SUP-PKG-001 | 保存成功率>=99.5% | SUP-005 |
|
||||
| R-PKG-002 | 套餐发布满足保护价与状态约束 | `POST /api/v1/supply/packages/{packageId}/publish` | `POST /api/v1/supply/packages/{id}/publish` | UI-SUP-PKG-002 + INT-PKG-INV-001 | 保护价违规放行率=0 | SUP-005 |
|
||||
| R-PKG-003 | 批量调价部分失败可回执 | `POST /api/v1/supply/packages/batch-price` | - | UI-SUP-PKG-005 | 明细完备率=100% | SUP-005 |
|
||||
| R-SET-001 | 提现发起防重复防双扣 | `POST /api/v1/supply/settlements/withdraw` | - | UI-SUP-SET-002 + CON-SET-001 | M-004/M-005 达标 | SUP-006 |
|
||||
| R-SET-002 | 处理中/已完成不可撤销 | `POST /api/v1/supply/settlements/{settlementId}/cancel` | `POST /api/v1/supply/settlements/{id}/cancel` | UI-SUP-SET-003 + INT-SET-STATE-001 | 跳态成功率=0 | SUP-006 |
|
||||
| R-SET-003 | 对账单导出不泄露敏感信息 | `GET /api/v1/supply/settlements/{settlementId}/statement` | `GET /api/v1/supply/settlements/{id}/statement` | UI-SUP-SET-004 + SEC-SUP-001 | M-013=0 | SUP-006/SUP-007 |
|
||||
| R-SEC-001 | 仅平台凭证入站 | 全部北向 API | - | SEC-SUP-002 | M-014=100% | SUP-007 |
|
||||
| R-SEC-002 | 外部 query key 全拒绝 | 全部北向 API | - | SEC-SUP-002 | M-016=100% | SUP-007 |
|
||||
| R-SEC-003 | 需求方不可绕平台直连 | 出网策略与告警 | - | SEC-SUP-002 + SEC-DIRECT-001 | M-015=0 | SUP-007 |
|
||||
| R-UX-001 | 按钮可见性和禁用规则正确 | 三页面全部按钮 | - | UI-DESIGN-QA-001~020 | 按钮规则通过率=100% | SUP-003/SUP-008 |
|
||||
|
||||
跨域映射补充：
|
||||
1. 全局 P0 中预算/告警/组织级账单导出映射见：`docs/product/global_p0_to_supply_platform_mapping_v1_2026-03-27.md`。
|
||||
2. 对应追踪项已并入：`reports/supply_traceability_matrix_2026-03-25.csv`（`R-PLAT-001~003`）。
|
||||
|
||||
---
|
||||
|
||||
@@ -143,6 +147,16 @@
|
||||
4. `SEC-SUP Gate`：凭证边界与泄露扫描（阻断）。
|
||||
5. `PERF/REL Gate`：每晚定时跑，异常进入发布前强制复核。
|
||||
|
||||
## 7.3 分阶段质量门禁（防偏航）
|
||||
|
||||
1. G0 Requirement Gate：检查 PRD/OpenAPI/按钮清单版本一致，任一漂移阻断开发。
|
||||
2. G1 Design Gate：检查 DDL、状态机、不变量、审计字段齐套，缺一阻断联调。
|
||||
3. G2 Dev Gate：单测与契约测试达标后才允许合并。
|
||||
4. G3 Integration Gate：DB/Redis/Outbox/权限链路通过后才允许提测。
|
||||
5. G4 Release Gate：SUP-004~SUP-007 与安全门禁全绿才允许发布。
|
||||
6. G5 Post Gate：发布后 24h 观察窗口出现 P0/P1 立即冻结后续升波。
|
||||
7. 指标约束：`M-018=100%` 且 `M-019=100%`，否则回退到失败阶段整改。
|
||||
|
||||
## 7.2 失败策略
|
||||
|
||||
1. P0 用例失败：立即阻断发布 + 当日复盘。
|
||||
@@ -158,6 +172,7 @@
|
||||
1. PRD 按钮级规格冻结。
|
||||
2. OpenAPI 字段冻结。
|
||||
3. 技术增强稿（XR-001）已落地。
|
||||
4. 路径一致性检查通过（API 字段与 OpenAPI 主路径一致，alias 映射完整）。
|
||||
|
||||
## 8.2 退出（Exit）
|
||||
|
||||
|
||||
@@ -0,0 +1,37 @@
|
||||
# 供应侧追踪矩阵生成规则（v1.0）
|
||||
|
||||
- 日期：2026-03-27
|
||||
- 适用文件：`reports/supply_traceability_matrix_2026-03-25.csv`
|
||||
- 目标：保证 Requirement -> API -> Test -> Metric -> Gate 的自动化可追踪与口径一致。
|
||||
|
||||
## 1. 字段规范
|
||||
|
||||
1. `requirement_id`：唯一且稳定，不得复用。
|
||||
2. `api`：必须使用 OpenAPI 主路径与精确参数名（如 `{accountId}`、`{packageId}`、`{settlementId}`）。
|
||||
3. `api_alias`：仅记录历史兼容路径；无兼容值填写 `-`。
|
||||
4. `test_case`：使用 `|` 连接多个用例 ID，顺序按主路径优先。
|
||||
5. `metric`：使用 SSOT 中的统一指标名，禁止自造同义词。
|
||||
6. `gate`：映射 SUP/SEC/XR 门禁，多个值用 `|` 分隔。
|
||||
7. `status`：`PLANNED/RUNNING/PASS/FAIL/BLOCKED` 五态。
|
||||
|
||||
## 2. 生成流程
|
||||
|
||||
1. 从按钮级 PRD 抽取需求项并形成 `requirement_id`。
|
||||
2. 从 OpenAPI 提取接口主路径，填入 `api`。
|
||||
3. 对历史路径或迁移路径填入 `api_alias`。
|
||||
4. 绑定测试用例、指标、门禁并指定 owner。
|
||||
5. 由 QA 执行完整性检查后发布 CSV。
|
||||
|
||||
## 3. 校验规则
|
||||
|
||||
1. `api` 必须可在 OpenAPI 中检索命中。
|
||||
2. `api_alias` 不得与 `api` 完全相同。
|
||||
3. `gate` 必须在任务单中存在对应条目。
|
||||
4. 每条记录必须有 `evidence_path`。
|
||||
5. 任一校验失败，`M-019` 计为不通过。
|
||||
|
||||
## 4. 变更治理
|
||||
|
||||
1. 修改 `api` 视为高风险变更，必须同步更新用例与门禁映射。
|
||||
2. 新增 alias 必须附迁移原因和下线计划。
|
||||
3. 每次变更后需执行一次路径一致性检查并留痕。
|
||||
@@ -1,7 +1,7 @@
|
||||
# 优化技术架构设计（最小可运营栈 + 触发式扩容）
|
||||
|
||||
- 版本：v2.0
|
||||
- 日期：2026-03-18
|
||||
- 版本：v2.1
|
||||
- 日期：2026-03-27
|
||||
- 目标：降低 S0/S1 运维复杂度，同时保证 S2 替换目标可达。
|
||||
|
||||
---
|
||||
@@ -110,6 +110,8 @@ Internet
|
||||
- `llm_gateway_subapi_evolution_plan_v4_2_2026-03-24.md`
|
||||
- `acceptance_gate_single_source_v1_2026-03-18.md`
|
||||
- `test_plan_go_aligned_v1_2026-03-18.md`
|
||||
- `dependency_compatibility_audit_baseline_v1_2026-03-27.md`
|
||||
- `database_domain_model_and_governance_v1_2026-03-27.md`
|
||||
|
||||
---
|
||||
|
||||
@@ -120,3 +122,42 @@ Internet
|
||||
3. 发布扩容触发条件评审模板（无触发条件不得引入组件）。
|
||||
4. 将运维看板与门禁阈值绑定到唯一验收门禁表。
|
||||
5. 完成一次“升级 + 灰度 + 自动回滚”全链路演练。
|
||||
|
||||
---
|
||||
|
||||
## 8. 依赖兼容性审计（新增强制门禁）
|
||||
|
||||
1. 发布前必须产出四类证据：SBOM、锁文件差异、兼容矩阵、风险清单。
|
||||
2. 对 `subapi/provider SDK` 执行精确版本锁定（`X.Y.Z`），禁止“仅锁主次版本”。
|
||||
3. 任一依赖发生 major 变更，必须附兼容影响评估与回滚演练记录。
|
||||
4. 依赖审计结果接入门禁指标 `M-017`，要求 `dependency_compat_audit_pass_pct=100%`。
|
||||
5. 运行时、数据层、构建镜像三类版本必须可追溯到同一发布包，禁止“文档版本”和“运行版本”漂移。
|
||||
|
||||
---
|
||||
|
||||
## 9. 分阶段质量检查（防偏离主线）
|
||||
|
||||
### 9.1 阶段门禁定义
|
||||
|
||||
| 阶段 | Gate | 必达条件 | 阻断动作 |
|
||||
|---|---|---|---|
|
||||
| G0 需求冻结 | Requirement Gate | P0/P1 需求、按钮、接口状态全部冻结 | 禁止进入开发 |
|
||||
| G1 设计冻结 | Design Gate | 数据模型、OpenAPI、状态机与审计字段齐套 | 禁止进入联调 |
|
||||
| G2 开发自检 | Dev Gate | 单元/契约测试通过，覆盖率达标 | 禁止合并 |
|
||||
| G3 集成验证 | Integration Gate | DB/缓存/外部依赖集成测试通过 | 禁止预发布 |
|
||||
| G4 发布演练 | Release Gate | 回滚演练、性能门禁、安全门禁通过 | 禁止生产发布 |
|
||||
| G5 发布观察 | Post Gate | 24h 指标稳定，无 P0/P1 回归 | 冻结后续升波 |
|
||||
|
||||
### 9.2 防偏航机制
|
||||
|
||||
1. 需求追踪覆盖率（`M-019`）必须 100%，每条 P0 需求都能映射到 API/测试/指标/Gate。
|
||||
2. 阶段通过率（`M-018`）必须 100%，任一阶段失败禁止“跳阶段推进”。
|
||||
3. 每日执行“需求-设计-测试-门禁”一致性巡检，发现漂移 24h 内关闭。
|
||||
4. 所有变更按 `request_id + trace_id` 留痕，确保故障可逆向定位到需求与提交。
|
||||
|
||||
---
|
||||
|
||||
## 10. 本版补充结论
|
||||
|
||||
1. 架构基线从“最小可运营栈”扩展为“最小可运营栈 + 依赖可审计 + 分阶段质量闭环”。
|
||||
2. 未完成依赖兼容审计或阶段门禁的变更，不得进入 `GO` 决策。
|
||||
|
||||
122
docs/token_auth_middleware_design_v1_2026-03-29.md
Normal file
122
docs/token_auth_middleware_design_v1_2026-03-29.md
Normal file
@@ -0,0 +1,122 @@
|
||||
# 平台鉴权与 Token 校验中间件设计（TOK-002）
|
||||
|
||||
- 版本：v1.0
|
||||
- 日期：2026-03-29
|
||||
- 状态：开发实施设计基线
|
||||
- 依赖：`docs/token_runtime_minimal_spec_v1.md`
|
||||
- 目标：实现“仅平台凭证入站”，并为 M-014/M-016/M-021 提供可验证链路。
|
||||
|
||||
## 1. 设计目标
|
||||
|
||||
1. 所有北向请求必须通过平台凭证校验。
|
||||
2. 外部 `query key` 入站一律拒绝并记录审计事件。
|
||||
3. 鉴权结果可追踪到 `request_id + subject_id + token_id`。
|
||||
4. 在不泄露上游凭证的前提下返回标准错误码。
|
||||
|
||||
## 2. 适用范围
|
||||
|
||||
1. 路由范围：`/api/v1/supply/*`、`/api/v1/platform/*`。
|
||||
2. 鉴权头：仅支持 `Authorization: Bearer <token>`。
|
||||
3. 排除范围：健康检查、内部探针、公开静态资源。
|
||||
|
||||
## 3. 中间件链路
|
||||
|
||||
## 3.1 处理顺序
|
||||
|
||||
1. `RequestIdMiddleware`
|
||||
2. `QueryKeyRejectMiddleware`
|
||||
3. `BearerExtractMiddleware`
|
||||
4. `TokenVerifyMiddleware`
|
||||
5. `TokenStatusCheckMiddleware`
|
||||
6. `ScopeRoleAuthzMiddleware`
|
||||
7. `AuditEmitMiddleware`
|
||||
|
||||
## 3.2 关键规则
|
||||
|
||||
1. `QueryKeyRejectMiddleware`
|
||||
- 拒绝任意 `?key=`、`?api_key=`、`?token=` 形式外部参数。
|
||||
- 返回 `401 QUERY_KEY_NOT_ALLOWED`。
|
||||
2. `BearerExtractMiddleware`
|
||||
- 无 `Authorization` 直接 `401 AUTH_MISSING_BEARER`。
|
||||
3. `TokenVerifyMiddleware`
|
||||
- 校验签名、`iss`、`aud`、`exp`、`nbf`、`jti`。
|
||||
- 签名失败返回 `401 AUTH_INVALID_TOKEN`。
|
||||
4. `TokenStatusCheckMiddleware`
|
||||
- 查询 token 状态缓存（`active/revoked/expired`）。
|
||||
- `revoked/expired` 返回 `401 AUTH_TOKEN_INACTIVE`。
|
||||
5. `ScopeRoleAuthzMiddleware`
|
||||
- 按路由匹配 scope；不足返回 `403 AUTH_SCOPE_DENIED`。
|
||||
|
||||
## 4. 数据与缓存策略
|
||||
|
||||
1. 状态源：`platform_token_registry`（运行态主表）。
|
||||
2. 热缓存：`token_status_cache`（TTL 30s）。
|
||||
3. 吊销传播：
|
||||
- 吊销事件写入总线后，1~5 秒内刷新缓存。
|
||||
- 验收阈值：吊销生效延迟 `<= 5s`。
|
||||
|
||||
## 5. 错误语义
|
||||
|
||||
| 场景 | HTTP | error.code | 说明 |
|
||||
|---|---|---|---|
|
||||
| 缺失 Bearer | 401 | AUTH_MISSING_BEARER | 请求头缺失 |
|
||||
| query key 外部入站 | 401 | QUERY_KEY_NOT_ALLOWED | 边界拒绝 |
|
||||
| token 无效/签名失败 | 401 | AUTH_INVALID_TOKEN | 校验失败 |
|
||||
| token 已吊销/过期 | 401 | AUTH_TOKEN_INACTIVE | 状态不可用 |
|
||||
| scope 不足 | 403 | AUTH_SCOPE_DENIED | 权限不足 |
|
||||
|
||||
## 6. 审计事件（TOK-004 依赖）
|
||||
|
||||
1. `token.authn.success`
|
||||
2. `token.authn.fail`
|
||||
3. `token.authz.denied`
|
||||
4. `token.query_key.rejected`
|
||||
|
||||
最小字段：
|
||||
1. `event_id`
|
||||
2. `request_id`
|
||||
3. `token_id`（可空，提取失败时为空）
|
||||
4. `subject_id`（可空）
|
||||
5. `route`
|
||||
6. `result_code`
|
||||
7. `client_ip`
|
||||
8. `created_at`
|
||||
|
||||
## 7. 伪代码（实现参考）
|
||||
|
||||
```text
|
||||
onRequest(req):
|
||||
reqId = ensureRequestId(req)
|
||||
if hasExternalQueryKey(req):
|
||||
emitAudit("token.query_key.rejected", reqId, route, clientIp)
|
||||
return 401 QUERY_KEY_NOT_ALLOWED
|
||||
|
||||
bearer = parseBearer(req.headers.Authorization)
|
||||
if bearer is null:
|
||||
emitAudit("token.authn.fail", reqId, route, "AUTH_MISSING_BEARER")
|
||||
return 401 AUTH_MISSING_BEARER
|
||||
|
||||
claims = verifyToken(bearer)
|
||||
if verify failed:
|
||||
emitAudit("token.authn.fail", reqId, route, "AUTH_INVALID_TOKEN")
|
||||
return 401 AUTH_INVALID_TOKEN
|
||||
|
||||
status = getTokenStatus(claims.jti)
|
||||
if status != active:
|
||||
emitAudit("token.authn.fail", reqId, route, "AUTH_TOKEN_INACTIVE")
|
||||
return 401 AUTH_TOKEN_INACTIVE
|
||||
|
||||
if !checkScopeRole(claims.scope, claims.role, route):
|
||||
emitAudit("token.authz.denied", reqId, route, "AUTH_SCOPE_DENIED")
|
||||
return 403 AUTH_SCOPE_DENIED
|
||||
|
||||
attachPrincipal(req, claims)
|
||||
emitAudit("token.authn.success", reqId, route, "OK")
|
||||
pass
|
||||
```
|
||||
|
||||
## 8. 开发阶段验收（设计级）
|
||||
|
||||
1. 与 `TOK-001` 角色、状态机、审计字段一致。
|
||||
2. 与 `M-014/M-016` 指标定义一致。
|
||||
3. 与 OpenAPI token 契约草案字段一致。
|
||||
76
docs/token_lifecycle_audit_test_assertions_v1_2026-03-29.md
Normal file
76
docs/token_lifecycle_audit_test_assertions_v1_2026-03-29.md
Normal file
@@ -0,0 +1,76 @@
|
||||
# TOK-003/TOK-004 测试断言清单（生命周期 + 审计事件）
|
||||
|
||||
- 版本：v1.0
|
||||
- 日期：2026-03-29
|
||||
- 状态：开发实施测试基线
|
||||
- 适用任务：`TOK-003`、`TOK-004`
|
||||
|
||||
## 1. 测试范围
|
||||
|
||||
1. TOK-003：签发、续期、吊销、过期生命周期。
|
||||
2. TOK-004：签发/校验失败/吊销/越权事件入库与可追踪。
|
||||
|
||||
## 2. 前置数据
|
||||
|
||||
1. 租户：`tenant_id=1001`
|
||||
2. 主体：
|
||||
- `subject_owner=2001`
|
||||
- `subject_viewer=2002`
|
||||
3. 角色策略：
|
||||
- owner: `supply:*`
|
||||
- viewer: `supply:read`
|
||||
4. 观测阈值：
|
||||
- 吊销生效延迟 `<=5s`
|
||||
- 审计事件落库延迟 `<=3s`
|
||||
|
||||
## 3. TOK-003 生命周期断言
|
||||
|
||||
| 用例ID | 场景 | 步骤 | 断言 |
|
||||
|---|---|---|---|
|
||||
| TOK-LIFE-001 | 签发成功 | 1) 调用 `POST /tokens/issue` 2) 记录返回 | 1) `status=active` 2) `expires_at>issued_at` 3) `token_id` 唯一 |
|
||||
| TOK-LIFE-002 | 签发参数非法 | 1) `ttl_seconds` 超上限 2) 调用签发 | 1) 返回 `400` 2) 不落 active token |
|
||||
| TOK-LIFE-003 | 同键幂等签发重放 | 1) 相同 `Idempotency-Key` 重复提交 | 1) 返回同一 `token_id` 2) 无重复写入 |
|
||||
| TOK-LIFE-004 | 续期成功 | 1) 调用 `POST /tokens/{tokenId}/refresh` | 1) `expires_at` 延后 2) `status=active` |
|
||||
| TOK-LIFE-005 | 吊销成功 | 1) 调用 `POST /tokens/{tokenId}/revoke` 2) 立刻 introspect | 1) 最终 `status=revoked` 2) 生效延迟 <=5s |
|
||||
| TOK-LIFE-006 | 吊销后访问受限接口 | 1) 使用被吊销 token 访问受保护路由 | 1) 返回 `401 AUTH_TOKEN_INACTIVE` |
|
||||
| TOK-LIFE-007 | 过期自动失效 | 1) 签发短 TTL token 2) 等待过期 3) introspect | 1) `status=expired` 2) 返回不可用错误 |
|
||||
| TOK-LIFE-008 | viewer 越权写操作 | 1) viewer token 调用写接口 | 1) 返回 `403 AUTH_SCOPE_DENIED` 2) 无写入副作用 |
|
||||
|
||||
## 4. TOK-004 审计事件断言
|
||||
|
||||
| 用例ID | 场景 | 步骤 | 断言 |
|
||||
|---|---|---|---|
|
||||
| TOK-AUD-001 | 签发成功事件 | 执行 TOK-LIFE-001 | 1) 存在 `token.issue.success` 2) 字段齐全 |
|
||||
| TOK-AUD-002 | 签发失败事件 | 执行 TOK-LIFE-002 | 1) 存在 `token.issue.fail` 2) `result_code` 准确 |
|
||||
| TOK-AUD-003 | 鉴权失败事件 | 无效 token 访问受保护路由 | 1) `token.authn.fail` 入库 2) 含 `request_id` |
|
||||
| TOK-AUD-004 | 越权事件 | 执行 TOK-LIFE-008 | 1) `token.authz.denied` 入库 2) 含 `subject_id` |
|
||||
| TOK-AUD-005 | 吊销事件 | 执行 TOK-LIFE-005 | 1) `token.revoke.success` 入库 2) 含 `token_id` |
|
||||
| TOK-AUD-006 | query key 拒绝事件 | 使用 query key 访问接口 | 1) `token.query_key.rejected` 入库 2) 不出现敏感值 |
|
||||
| TOK-AUD-007 | 事件不可篡改 | 重复读取同 `event_id` | 1) 核心字段不可变 2) 时间顺序正确 |
|
||||
|
||||
## 5. 字段级硬断言
|
||||
|
||||
每条审计事件必须包含：
|
||||
1. `event_id`
|
||||
2. `request_id`
|
||||
3. `result_code`
|
||||
4. `route`
|
||||
5. `created_at`
|
||||
|
||||
可选字段规则：
|
||||
1. `token_id`：提取失败场景可空，其余场景必填。
|
||||
2. `subject_id`：匿名失败场景可空，其余场景必填。
|
||||
|
||||
禁止项：
|
||||
1. 不得写入上游供应方凭证明文。
|
||||
2. 不得写入完整 `access_token` 明文（仅允许哈希或指纹）。
|
||||
|
||||
## 6. 结果判定
|
||||
|
||||
1. TOK-003 通过标准：
|
||||
- `TOK-LIFE-*` 全通过
|
||||
- 吊销延迟阈值满足 `<=5s`
|
||||
2. TOK-004 通过标准：
|
||||
- `TOK-AUD-*` 全通过
|
||||
- 审计字段完整率 `=100%`
|
||||
- 敏感数据泄露事件 `=0`
|
||||
92
docs/token_runtime_minimal_spec_v1.md
Normal file
92
docs/token_runtime_minimal_spec_v1.md
Normal file
@@ -0,0 +1,92 @@
|
||||
# Token 运行态最小实现规格（TOK-001）
|
||||
|
||||
- 版本：v1.0
|
||||
- 日期：2026-03-27
|
||||
- 状态：开发实施基线
|
||||
- 对应任务：`TOK-001`
|
||||
|
||||
## 1. 目标
|
||||
|
||||
在不依赖真实 staging 参数的前提下，定义可落地的 token 运行态最小能力集，为后续 TOK-002~TOK-007 提供统一实施输入。
|
||||
|
||||
## 2. 最小能力范围（MVP）
|
||||
|
||||
1. 平台签发：短期访问 token（owner/viewer/admin）。
|
||||
2. 入站校验：仅平台凭证有效，拒绝 query key 外部入站。
|
||||
3. 生命周期：签发、续期、吊销、过期。
|
||||
4. 边界审计：签发/校验失败/吊销/越权事件全量入审计。
|
||||
5. 指标可观测：可计算 M-013~M-016 与 M-021。
|
||||
|
||||
## 3. 角色与权限
|
||||
|
||||
| 角色 | 能力 | 约束 |
|
||||
|---|---|---|
|
||||
| owner | 管理供应侧账号、套餐、结算 | 不可读取上游凭证明文 |
|
||||
| viewer | 只读查询 | 不可执行写操作 |
|
||||
| admin | 风控与审计管理 | 仅平台内部可用 |
|
||||
|
||||
## 4. Token 数据模型（最小字段）
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| token_id | string | 平台内部唯一标识 |
|
||||
| subject_id | string | 用户/服务主体ID |
|
||||
| role | string | owner/viewer/admin |
|
||||
| issued_at | datetime | 签发时间 |
|
||||
| expires_at | datetime | 过期时间 |
|
||||
| status | string | active/revoked/expired |
|
||||
| scope | string[] | 授权范围 |
|
||||
| request_id | string | 请求追踪ID |
|
||||
| revoked_reason | string | 吊销原因（可空） |
|
||||
|
||||
## 5. 生命周期状态机
|
||||
|
||||
`active -> revoked -> expired`
|
||||
|
||||
规则：
|
||||
1. `revoked` 不可恢复为 `active`，需重新签发。
|
||||
2. `expires_at` 到期自动进入 `expired`。
|
||||
3. 续期只能对 `active` token 生效。
|
||||
|
||||
## 6. 核心接口（草案）
|
||||
|
||||
1. `POST /api/v1/platform/tokens/issue`
|
||||
2. `POST /api/v1/platform/tokens/{tokenId}/refresh`
|
||||
3. `POST /api/v1/platform/tokens/{tokenId}/revoke`
|
||||
4. `POST /api/v1/platform/tokens/introspect`
|
||||
5. `GET /api/v1/platform/tokens/audit-events`
|
||||
|
||||
返回要求：
|
||||
1. 不回传任何上游供应方凭证。
|
||||
2. 错误码需区分：无效、过期、越权、吊销。
|
||||
3. 审计查询接口仅返回审计字段，不返回 access token 或任何上游凭证明文。
|
||||
|
||||
## 7. 安全约束
|
||||
|
||||
1. token 存储需采用哈希或加密指纹，禁止明文落库。
|
||||
2. 校验路径必须记录 `request_id` 与调用来源。
|
||||
3. 外部 query key 入站请求必须拒绝并记录事件。
|
||||
4. 任一泄露事件触发 P0。
|
||||
|
||||
## 8. 审计事件最小集
|
||||
|
||||
1. `token.issue.success/fail`
|
||||
2. `token.introspect.success/fail`
|
||||
3. `token.refresh.success/fail`
|
||||
4. `token.revoke.success/fail`
|
||||
5. `token.authz.denied`
|
||||
|
||||
审计字段：
|
||||
1. `event_id`
|
||||
2. `request_id`
|
||||
3. `operator_id`
|
||||
4. `subject_id`
|
||||
5. `token_id`
|
||||
6. `result_code`
|
||||
7. `created_at`
|
||||
|
||||
## 9. 验收标准（TOK-001 关闭条件）
|
||||
|
||||
1. 本规格被 `ARCH + SEC + PLAT` 确认并引用到执行任务单。
|
||||
2. 后续 TOK-002~TOK-004 的实现字段与本规格一致。
|
||||
3. 不得新增“直接向终端用户分发上游 token”的路径。
|
||||
Reference in New Issue
Block a user