docs(plan): record phase1 authority baseline

Record the current identity entry points in the execution log and update the minimal token runtime spec with a single authority rule and canonical principal fields. Mark P1-A-01 through P1-A-03 complete in the optimization plan so subsequent batches can continue from the verified baseline.

docs/plans/2026-04-21-project-quality-performance-ops-optimization-execution-log.md

@@ -0,0 +1,39 @@
+# 2026-04-21 Project Quality / Performance / Ops Optimization Execution Log
+
+## P1-A-01 当前身份入口扫描结果
+
+执行命令：
+
+```bash
+rg -n "inmemory|remote_introspection|token runtime|JWT|Bearer" gateway supply-api platform-token-runtime
+```
+
+结论：
+
+1. `gateway` 当前同时保留两种 token runtime 装配路径：
+   - `gateway/internal/app/bootstrap.go`
+   - `gateway/internal/config/config.go`
+   - `gateway/internal/middleware/chain.go`
+   - `gateway/README.md`
+
+2. `platform-token-runtime` 当前承载独立的 token issue / refresh / revoke / introspect / audit-events 语义：
+   - `platform-token-runtime/internal/app/bootstrap.go`
+   - `platform-token-runtime/internal/httpapi/token_api.go`
+   - `platform-token-runtime/internal/auth/middleware/token_auth_middleware.go`
+   - `platform-token-runtime/README.md`
+
+3. `supply-api` 当前仍保留独立 JWT 校验、Bearer 提取和 token 状态后端：
+   - `supply-api/internal/middleware/auth.go`
+   - `supply-api/internal/app/bootstrap.go`
+   - `supply-api/internal/middleware/ratelimit.go`
+   - `supply-api/internal/middleware/token_format_test.go`
+
+4. 当前身份链路的关键事实：
+   - `gateway` 的远程模式依赖 `platform-token-runtime` 做 introspection。
+   - `supply-api` 仍以 JWT claims 为认证入口。
+   - 三个服务对“谁是 authority”仍未收敛为单一真源。
+
+## P1-A-04 OpenAPI 与 canonical principal 差异记录
+
+待执行。
+

docs/plans/2026-04-21-project-quality-performance-ops-optimization-plan.md

@@ -0,0 +1,739 @@
+# Project Quality / Performance / Ops Optimization Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** 通过四个阶段收敛项目的身份与鉴权真源、发布真源、运行时治理和维护边界，使项目质量更高、性能更强、运维更简单。
+
+**Architecture:** 先解决“谁说了算”的问题，再解决“怎么发布”和“怎么验证”的问题，最后收口运行时与代码结构。每个阶段都要求同时覆盖设计、实现、验证、回滚和文档，不允许只做局部修补。
+
+**Tech Stack:** Go, Bash, PostgreSQL, Redis, HTTP, OpenAPI, Markdown, CI Shell Scripts
+
+---
+
+## 1. 文档用途
+
+本文件同时承担四个用途：
+
+1. 汇总本轮综合 review 的关键发现。
+2. 给出按阶段推进的优化目标和退出标准。
+3. 把每个阶段拆成可自行细分、几分钟内可完成的最小任务清单。
+4. 复审任务清单是否足以彻底达成各阶段目标。
+
+本文件不是“方向性建议”，而是执行前的落地任务底稿。
+
+## 2. 范围
+
+本计划覆盖以下代码和流程边界：
+
+- `gateway`
+- `supply-api`
+- `platform-token-runtime`
+- `scripts/ci`
+- `scripts/devtest`
+- `scripts/auto_review`
+- `sql/postgresql`
+- `docs/`
+- `review/`
+
+## 3. 关键发现
+
+### 3.1 架构与边界问题
+
+1. `token`/鉴权存在三套并行权威源。
+   证据：`gateway/internal/app/bootstrap.go`、`gateway/internal/middleware/remote_runtime.go`、`supply-api/internal/middleware/auth.go`、`supply-api/internal/app/runtime.go`、`platform-token-runtime/internal/auth/service/inmemory_runtime.go`
+   影响：跨服务身份语义漂移，审计口径不一致，联调和回归验证成本持续上升。
+
+2. `platform-token-runtime` 的 schema 与运行时模型漂移。
+   证据：`sql/postgresql/token_runtime_schema_v1.sql`、`platform-token-runtime/internal/auth/service/inmemory_runtime.go`、`platform-token-runtime/internal/auth/service/postgres_runtime_store.go`、`platform-token-runtime/internal/auth/service/postgres_audit_store.go`
+   影响：多租户字段、操作人字段和 metadata 形同虚设，后续审计和权限治理会缺证据链。
+
+3. 鉴权链、审计模型和日志实现重复复制并开始分叉。
+   证据：`gateway/internal/middleware/chain.go`、`platform-token-runtime/internal/auth/middleware/token_auth_middleware.go`、`gateway/internal/pkg/logging/logger.go`、`platform-token-runtime/internal/pkg/logging/logger.go`、`supply-api/internal/pkg/logging/logger.go`
+   影响：安全修复和兼容调整需要多处同步，容易遗漏。
+
+4. `gateway` 长期保留未接入主链路的实验能力。
+   证据：`gateway/internal/app/bootstrap.go`、`gateway/internal/router/engine/routing_engine.go`、`gateway/internal/router/strategy/cost_aware.go`、`gateway/internal/router/fallback/fallback.go`、`gateway/README.md`
+   影响：认知负担高，路由行为与仓库实现不一致。
+
+5. `supply-api` 的 `InvariantChecker` 已实现但未进入执行路径，IAM 也未闭环。
+   证据：`supply-api/internal/app/runtime.go`、`supply-api/internal/domain/invariants.go`、`supply-api/internal/iam/handler/iam_handler.go`
+   影响：规则定义与真实行为会继续漂移，权限边界难以稳定。
+
+### 3.2 发布与运维问题
+
+1. 发布门禁把 `mock`/`DEFERRED` 结果计入可通过链路。
+   证据：`scripts/ci/superpowers_stage_validate.sh`、`scripts/ci/metrics_daily_snapshot.sh`、`scripts/ci/staging_release_pipeline.sh`
+   影响：真实 staging 不是唯一硬阻断条件，上线结论可能偏离真实环境。
+
+2. 发布证据按“最新文件”拼装，存在跨批次串用风险。
+   证据：`scripts/ci/staging_release_pipeline.sh`、`scripts/ci/staging_evidence_autofill.sh`、`scripts/ci/tok007_release_recheck.sh`、`scripts/ci/final_decision_consistency_check.sh`
+   影响：历史工件可能污染当前发布决策。
+
+3. `supply-api` 的 staging/devtest 仍复用 `dev` 配置。
+   证据：`scripts/devtest/start_dev_stack.sh`、`supply-api/cmd/supply-api/main.go`、`supply-api/config/config.dev.yaml`
+   影响：环境语义不统一，难以建立稳定的预发布信任。
+
+4. 当前 `e2e` 主要是进程内装配，不是跨服务真实部署验证。
+   证据：`scripts/ci/repo_integrity_check.sh`、`scripts/ci/backend-verify.sh`、`supply-api/e2e/e2e_test.go`、`supply-api/e2e/README.md`
+   影响：通过了测试，不等于通过了发布链路。
+
+5. `auto_review` 目前只是文档巡检，不是工程门禁。
+   证据：`scripts/auto_review/auto_review.sh`、`scripts/auto_review/README.md`
+   影响：如果被误解为质量守门员，会形成错误安全感。
+
+### 3.3 性能与运行时问题
+
+1. `gateway` 的远程 token runtime 默认使用 `http.DefaultClient`，没有显式超时。
+   证据：`gateway/internal/middleware/remote_runtime.go`
+   影响：远端抖动会直接放大为入口尾延迟。
+
+2. 远程 token 状态缓存只增不减，没有淘汰策略。
+   证据：`gateway/internal/middleware/remote_runtime.go`
+   影响：长时间运行后会形成内存增长风险。
+
+3. `gateway` 的加权路由使用全局随机源，并且 provider 被摘除后没有自动恢复路径。
+   证据：`gateway/internal/router/router.go`
+   影响：并发选择质量不可控，瞬时故障可能演变为长期降级。
+
+4. 运行时指标主要靠离线脚本推导，服务自身缺少统一 `/metrics` 暴露。
+   证据：`scripts/ci/metrics_daily_snapshot.sh`、`gateway/internal/app/bootstrap.go`、`platform-token-runtime/internal/app/bootstrap.go`
+   影响：容量判断和故障定位都偏慢。
+
+5. 后台 worker 的 shutdown 纪律不够完整。
+   证据：`supply-api/internal/app/background.go`
+   影响：优雅关闭、分区维护和后台任务退出时行为不够透明。
+
+### 3.4 安全与治理问题
+
+1. `supply-api` 的“KMS”实现仍是本地派生密钥方案，默认 provider 也是 `local`。
+   证据：`supply-api/internal/security/kms_service.go`
+   影响：如果被误认为生产级 KMS，会形成严重的密钥治理假象。
+
+2. 仓库中存在被跟踪的环境文件，且本地脚本内置默认 secret。
+   证据：`scripts/supply-gate/.env`、`scripts/devtest/start_dev_stack.sh`
+   影响：误提交、误复用、误传播风险持续存在。
+
+3. `gateway` 仍保留默认加密 key 常量，虽然生产有 guard，但治理方式偏脆弱。
+   证据：`gateway/internal/config/config.go`、`gateway/internal/app/bootstrap.go`
+   影响：一旦环境语义校验被绕开，会退回到静态默认 key。
+
+## 4. 阶段化优化目标
+
+### Phase 1: 身份、鉴权、审计真源收敛
+
+**目标：**
+建立唯一 token authority、唯一 principal 契约、唯一审计字段契约。
+
+**阶段完成标准：**
+
+1. `platform-token-runtime` 成为唯一 token authority。
+2. `gateway` 在非 dev 环境不再持有本地 token authority。
+3. `supply-api` 不再自带独立 token 语义，只消费统一 principal。
+4. token schema、HTTP contract、审计模型三者字段一致。
+5. 跨服务 contract tests 能覆盖 `gateway -> token-runtime -> supply-api` 的身份链路。
+
+### Phase 2: 发布真源、证据真源、环境真源收敛
+
+**目标：**
+让发布结论只建立在“本次 run 的真实 staging 证据”之上。
+
+**阶段完成标准：**
+
+1. 发布流水线按 `run_id` 隔离工件和报告。
+2. `mock`/`local` 只作为 rehearsal，不参与 release pass 计算。
+3. `WARN` 不再默认放行 release decision。
+4. staging/prod 配置模板独立存在，不再复用 `dev` 配置。
+5. 至少存在一条真实跨服务 smoke 链路。
+
+### Phase 3: 运行时稳定性、性能、可观测性收敛
+
+**目标：**
+降低入口尾延迟风险，补齐运行时指标和 shutdown 纪律。
+
+**阶段完成标准：**
+
+1. 远程 introspection 有超时、连接池、缓存淘汰和指标。
+2. provider 健康摘除后存在自动恢复路径。
+3. 三个核心服务都有统一 `/metrics` 或等效指标出口。
+4. 关键 SLI 来自运行时采集，而不是 markdown/CSV 推导。
+5. 后台 worker、分区维护、补偿处理器具备可观测退出行为。
+
+### Phase 4: 代码结构、IAM、安全治理收敛
+
+**目标：**
+降低重复实现和大文件复杂度，补齐 IAM 闭环与 secret 治理。
+
+**阶段完成标准：**
+
+1. auth/audit/logging 共享实现不再三处分叉。
+2. `supply-api` 的大文件完成按职责拆分。
+3. `InvariantChecker` 要么接入真实写路径，要么被删除。
+4. IAM 路由接入 tenant/operator/scope 闭环。
+5. tracked `.env` 清理完成，devtest 默认 secret 被替换。
+6. 本地派生密钥方案不再被表述为生产可用 KMS。
+
+## 5. 详细任务清单
+
+说明：
+
+- 每个任务设计为 2 到 5 分钟内可完成。
+- 每个任务必须产生一个可见输出。
+- 每个任务都包含完成标准。
+- 若执行中发现新事实，必须先补文档，再改代码。
+
+---
+
+## Phase 1 任务清单
+
+### Task P1-A: 定义唯一 token authority 与 canonical principal 契约
+
+**Files:**
+- Modify: `docs/token_runtime_minimal_spec_v1.md`
+- Modify: `docs/platform_token_api_contract_openapi_draft_v1_2026-03-29.yaml`
+- Modify: `gateway/README.md`
+- Modify: `supply-api/README.md`
+- Modify: `platform-token-runtime/README.md`
+
+- [x] `P1-A-01` 运行 `rg -n "inmemory|remote_introspection|token runtime|JWT|Bearer" gateway supply-api platform-token-runtime`，收集当前身份入口。
+  完成标准：执行记录中列出全部入口文件。
+- [x] `P1-A-02` 在 `docs/token_runtime_minimal_spec_v1.md` 增加“唯一 authority”段落草稿。
+  完成标准：文档里明确写出 authority 所属服务。
+- [x] `P1-A-03` 在同一文档新增 canonical principal 字段清单。
+  完成标准：至少包含 `token_id`、`subject_id`、`tenant_id`、`scope`、`issued_at`、`expires_at`、`status`。
+- [ ] `P1-A-04` 打开 `docs/platform_token_api_contract_openapi_draft_v1_2026-03-29.yaml`，比对现有 introspection 响应字段。
+  完成标准：差异项被记录到计划执行日志。
+- [ ] `P1-A-05` 在 OpenAPI 草案里补 canonical principal 字段定义。
+  完成标准：OpenAPI 草案与最小规范字段一致。
+- [ ] `P1-A-06` 在 `gateway/README.md` 增加“非 dev 环境只允许远程 introspection”说明。
+  完成标准：README 不再给 staging/prod 留下本地 authority 的解释空间。
+- [ ] `P1-A-07` 在 `supply-api/README.md` 增加“消费统一 principal，不自持独立 authority”说明。
+  完成标准：README 用词与 Phase 1 目标一致。
+- [ ] `P1-A-08` 在 `platform-token-runtime/README.md` 增加“唯一 authority”声明和字段边界。
+  完成标准：三份 README 口径一致。
+
+### Task P1-B: 收敛 token schema、存储模型和审计字段
+
+**Files:**
+- Modify: `sql/postgresql/token_runtime_schema_v1.sql`
+- Modify: `platform-token-runtime/internal/auth/service/inmemory_runtime.go`
+- Modify: `platform-token-runtime/internal/auth/service/postgres_runtime_store.go`
+- Modify: `platform-token-runtime/internal/auth/service/postgres_audit_store.go`
+- Create: `docs/plans/2026-04-21-token-runtime-schema-alignment-notes.md`
+
+- [ ] `P1-B-01` 打开 schema，圈出 `tenant_id`、`project_id`、`operator_id`、`metadata` 所在列。
+  完成标准：对齐笔记里列出字段和表名。
+- [ ] `P1-B-02` 打开 `TokenRecord`，列出当前缺失字段。
+  完成标准：差异清单写入对齐笔记。
+- [ ] `P1-B-03` 决策“保留字段并贯穿”还是“删除字段并收缩契约”。
+  完成标准：对齐笔记里只保留一个决策，不允许双轨。
+- [ ] `P1-B-04` 如果选择保留，先写字段迁移顺序。
+  完成标准：顺序包含 model、store、API、audit、tests。
+- [ ] `P1-B-05` 如果选择删除，先写 shrink SQL 和历史数据影响说明。
+  完成标准：说明中覆盖 fresh setup 和 existing DB 两种情况。
+- [ ] `P1-B-06` 检查 `postgres_runtime_store.go` 的 `INSERT`/`SELECT` 字段映射。
+  完成标准：每个字段映射都被记录。
+- [ ] `P1-B-07` 检查 `postgres_audit_store.go` 的写入字段映射。
+  完成标准：审计模型缺口被单独列出。
+- [ ] `P1-B-08` 为字段一致性写一个最小执行清单。
+  完成标准：包含“改 model、改 SQL、改 test、跑验证”四类动作。
+
+### Task P1-C: 收敛 gateway 与 supply-api 的身份实现
+
+**Files:**
+- Modify: `gateway/internal/app/bootstrap.go`
+- Modify: `gateway/internal/middleware/remote_runtime.go`
+- Modify: `supply-api/internal/middleware/auth.go`
+- Modify: `supply-api/internal/app/runtime.go`
+- Modify: `supply-api/internal/app/bootstrap.go`
+
+- [ ] `P1-C-01` 在 `gateway/internal/app/bootstrap.go` 标出 `inmemory` 与 `remote_introspection` 分支。
+  完成标准：分支入口和调用点被记录。
+- [ ] `P1-C-02` 在 `supply-api/internal/middleware/auth.go` 标出 JWT 验证、token 状态检查和 principal 注入点。
+  完成标准：三个位置都被记录。
+- [ ] `P1-C-03` 在 `supply-api/internal/app/runtime.go` 标出 token backend 的装配点。
+  完成标准：DB-backed 与 memory-backed 装配点均被记录。
+- [ ] `P1-C-04` 写出 `gateway` 非 dev 禁用本地 authority 的代码改动清单。
+  完成标准：至少包含 config、bootstrap、tests。
+- [ ] `P1-C-05` 写出 `supply-api` 从“JWT authority”迁到“principal consumer”的代码改动清单。
+  完成标准：至少包含 middleware、runtime、HTTP handler、tests。
+- [ ] `P1-C-06` 写出过渡期兼容策略。
+  完成标准：明确单写、双读、切流或一次性切换的方案。
+- [ ] `P1-C-07` 写出回滚条件。
+  完成标准：明确何时回滚、回滚到哪一版契约。
+- [ ] `P1-C-08` 为兼容窗口补一段 README/ADR 说明草稿。
+  完成标准：说明中同时覆盖上线前、上线中、上线后三个时段。
+
+### Task P1-D: 建立跨服务 contract tests 与阶段 gate
+
+**Files:**
+- Modify: `scripts/ci/backend-verify.sh`
+- Modify: `scripts/ci/repo_integrity_check.sh`
+- Create: `tests/contract/README.md`
+- Create: `tests/contract/gateway_token_runtime_supply_chain.md`
+- Create: `docs/plans/2026-04-21-phase1-contract-gate-checklist.md`
+
+- [ ] `P1-D-01` 盘点当前 CI 对三服务身份链路的真实覆盖缺口。
+  完成标准：清单里明确“当前没有覆盖”的场景。
+- [ ] `P1-D-02` 定义最小 contract 场景 1：合法 token。
+  完成标准：说明中包含请求入口、期望状态码和关键字段。
+- [ ] `P1-D-03` 定义最小 contract 场景 2：吊销 token。
+  完成标准：说明中包含吊销后的 gateway 与 supply-api 预期行为。
+- [ ] `P1-D-04` 定义最小 contract 场景 3：scope 不足。
+  完成标准：说明中包含 principal 字段和拒绝行为。
+- [ ] `P1-D-05` 定义最小 contract 场景 4：token runtime 不可用。
+  完成标准：说明中包含入口超时和错误码约束。
+- [ ] `P1-D-06` 在 `backend-verify.sh` 设计新增执行位。
+  完成标准：写清楚命令入口、产物路径和失败语义。
+- [ ] `P1-D-07` 在 `repo_integrity_check.sh` 设计新增 contract gate 入口。
+  完成标准：文件里明确放在何处执行。
+- [ ] `P1-D-08` 写 Phase 1 gate checklist。
+  完成标准：只有当 contract tests 通过，Phase 1 才能标记完成。
+
+---
+
+## Phase 2 任务清单
+
+### Task P2-A: 引入 run_id 和 manifest，隔离发布工件
+
+**Files:**
+- Modify: `scripts/ci/staging_release_pipeline.sh`
+- Modify: `scripts/ci/staging_evidence_autofill.sh`
+- Modify: `scripts/ci/tok007_release_recheck.sh`
+- Modify: `scripts/ci/final_decision_consistency_check.sh`
+- Create: `reports/releases/.gitkeep`
+- Create: `docs/plans/2026-04-21-release-manifest-contract.md`
+
+- [ ] `P2-A-01` 盘点所有依赖 `latest_file_or_empty` 的脚本入口。
+  完成标准：清单覆盖全部脚本和调用行。
+- [ ] `P2-A-02` 设计 `run_id` 生成规则。
+  完成标准：规则包含日期、提交号或流水号。
+- [ ] `P2-A-03` 设计发布目录结构 `reports/releases/<run_id>/...`。
+  完成标准：目录草图写入 manifest 合同文档。
+- [ ] `P2-A-04` 设计 `manifest.json` 必填字段。
+  完成标准：至少包含 `run_id`、`commit_sha`、`env`、`artifact_paths`、`decision_inputs`。
+- [ ] `P2-A-05` 把 `staging_release_pipeline.sh` 的输入改成 manifest 读取方案草稿。
+  完成标准：不再依赖“最新文件”。
+- [ ] `P2-A-06` 把 `staging_evidence_autofill.sh` 的输入改成 manifest 读取方案草稿。
+  完成标准：只消费本次 run 的工件。
+- [ ] `P2-A-07` 把 `tok007_release_recheck.sh` 的输入改成 manifest 读取方案草稿。
+  完成标准：复检脚本不再扫历史目录。
+- [ ] `P2-A-08` 把 `final_decision_consistency_check.sh` 的输入改成 manifest 读取方案草稿。
+  完成标准：最终一致性检查绑定单次 run。
+
+### Task P2-B: 把真实 staging 设为唯一发布硬门禁
+
+**Files:**
+- Modify: `scripts/ci/superpowers_stage_validate.sh`
+- Modify: `scripts/ci/staging_real_readiness_check.sh`
+- Modify: `scripts/ci/superpowers_release_pipeline.sh`
+- Modify: `scripts/ci/final_decision_consistency_check.sh`
+- Create: `docs/plans/2026-04-21-real-staging-gate-rules.md`
+
+- [ ] `P2-B-01` 找出 `mock`、`local`、`DEFERRED` 被计为通过的判定点。
+  完成标准：每个判定点都有文件和行号。
+- [ ] `P2-B-02` 定义 rehearsal 与 real staging 的术语。
+  完成标准：规则文档中两者语义不重叠。
+- [ ] `P2-B-03` 定义“只有 real staging 通过才允许 release pass”的总规则。
+  完成标准：总规则写成一句可执行判定语句。
+- [ ] `P2-B-04` 设计 `superpowers_stage_validate.sh` 的状态枚举。
+  完成标准：至少区分 `PASS_REAL`、`PASS_REHEARSAL`、`FAIL`。
+- [ ] `P2-B-05` 设计 `staging_real_readiness_check.sh` 的阻断输出格式。
+  完成标准：输出里包含明确的 pass/fail 字段。
+- [ ] `P2-B-06` 设计 `superpowers_release_pipeline.sh` 的 fail-fast 位置。
+  完成标准：release 在 real staging 未通过时立即退出。
+- [ ] `P2-B-07` 设计 override 机制。
+  完成标准：override 必须要求审批人、时间戳、run_id、理由。
+- [ ] `P2-B-08` 设计禁止 `DEFERRED` 计入完成率的规则。
+  完成标准：文档里写出精确计算口径。
+
+### Task P2-C: 统一环境语义和配置模板
+
+**Files:**
+- Modify: `gateway/internal/config/config.go`
+- Modify: `gateway/internal/app/bootstrap.go`
+- Modify: `supply-api/cmd/supply-api/main.go`
+- Modify: `scripts/devtest/start_dev_stack.sh`
+- Create: `supply-api/config/config.staging.example.yaml`
+- Create: `supply-api/config/config.prod.example.yaml`
+- Create: `docs/plans/2026-04-21-env-normalization-checklist.md`
+
+- [ ] `P2-C-01` 盘点三服务支持的环境枚举和值别名。
+  完成标准：清单覆盖 `dev`、`staging`、`prod`、`production`、`online`。
+- [ ] `P2-C-02` 定义统一枚举。
+  完成标准：计划文档只保留 `dev`、`staging`、`prod`。
+- [ ] `P2-C-03` 设计 `gateway` 对 `production/online -> prod` 的归一化入口。
+  完成标准：只保留一个真正规则。
+- [ ] `P2-C-04` 设计 `supply-api` 对 `-env=staging -config=config.dev.yaml` 的拒绝规则。
+  完成标准：规则中包含错误信息草稿。
+- [ ] `P2-C-05` 复制 `config.dev.yaml` 所需段落，生成 staging 模板骨架。
+  完成标准：`config.staging.example.yaml` 包含必要配置段。
+- [ ] `P2-C-06` 复制 prod 模板骨架。
+  完成标准：`config.prod.example.yaml` 包含关键安全配置占位。
+- [ ] `P2-C-07` 在 `scripts/devtest/start_dev_stack.sh` 设计改用 staging 模板的参数。
+  完成标准：脚本不再硬编码 `config.dev.yaml`。
+- [ ] `P2-C-08` 写环境归一化检查清单。
+  完成标准：包括启动前检查、启动后检查、CI 检查三类项。
+
+### Task P2-D: 重构测试分类，补真实跨服务 smoke
+
+**Files:**
+- Modify: `scripts/ci/backend-verify.sh`
+- Modify: `scripts/ci/repo_integrity_check.sh`
+- Modify: `supply-api/e2e/README.md`
+- Modify: `supply-api/e2e/e2e_test.go`
+- Create: `tests/smoke/README.md`
+- Create: `scripts/ci/cross_service_smoke.sh`
+
+- [ ] `P2-D-01` 盘点当前被叫做 `e2e` 的测试真实边界。
+  完成标准：区分进程内、单服务、跨服务三类。
+- [ ] `P2-D-02` 定义新的测试分类名。
+  完成标准：至少包含 `unit`、`integration`、`service-http`、`cross-service-smoke`。
+- [ ] `P2-D-03` 在 `supply-api/e2e/README.md` 改写术语草稿。
+  完成标准：README 不再把进程内测试叫成真实部署 E2E。
+- [ ] `P2-D-04` 设计 `cross_service_smoke.sh` 的最小链路。
+  完成标准：至少覆盖 `gateway -> token-runtime -> supply-api`。
+- [ ] `P2-D-05` 为 smoke 脚本设计输入环境变量。
+  完成标准：包含地址、token、期望模型或 scope。
+- [ ] `P2-D-06` 为 smoke 脚本设计输出报告路径。
+  完成标准：输出可被 manifest 收录。
+- [ ] `P2-D-07` 设计 `backend-verify.sh` 中新增 smoke 入口。
+  完成标准：能区分“本地占位跳过”和“真实 smoke 失败”。
+- [ ] `P2-D-08` 设计 `repo_integrity_check.sh` 的职责边界说明。
+  完成标准：明确它不是 release gate，只是代码完整性 gate。
+
+---
+
+## Phase 3 任务清单
+
+### Task P3-A: 加固远程 token runtime 客户端
+
+**Files:**
+- Modify: `gateway/internal/middleware/remote_runtime.go`
+- Modify: `gateway/internal/app/bootstrap.go`
+- Modify: `gateway/internal/config/config.go`
+- Create: `gateway/internal/middleware/remote_runtime_metrics_test.go`
+
+- [ ] `P3-A-01` 列出现有 `http.DefaultClient` 的使用点。
+  完成标准：清单覆盖文件和构造入口。
+- [ ] `P3-A-02` 设计专用 `http.Client` 超时值。
+  完成标准：至少包含总超时、连接超时、空闲连接策略。
+- [ ] `P3-A-03` 设计 `remote_runtime` 的缓存 TTL。
+  完成标准：定义 active、expired、revoked 三类缓存寿命。
+- [ ] `P3-A-04` 设计缓存淘汰策略。
+  完成标准：明确按 TTL、容量还是两者结合。
+- [ ] `P3-A-05` 设计缓存命中率指标。
+  完成标准：至少定义 hit、miss、evict 三项。
+- [ ] `P3-A-06` 设计上游调用延迟指标。
+  完成标准：定义 histogram 或 bucket 方案。
+- [ ] `P3-A-07` 设计配置项命名。
+  完成标准：写出环境变量草稿。
+- [ ] `P3-A-08` 补最小测试矩阵。
+  完成标准：覆盖 timeout、cache hit、cache evict、upstream fail。
+
+### Task P3-B: 修正 router 健康摘除与恢复行为
+
+**Files:**
+- Modify: `gateway/internal/router/router.go`
+- Modify: `gateway/internal/router/router_test.go`
+- Create: `docs/plans/2026-04-21-router-health-recovery-notes.md`
+
+- [ ] `P3-B-01` 记录现有 provider 摘除条件。
+  完成标准：笔记里写出失败率阈值和现状行为。
+- [ ] `P3-B-02` 记录现有恢复条件。
+  完成标准：如果没有恢复路径，要明确写“缺失”。
+- [ ] `P3-B-03` 定义自动恢复策略。
+  完成标准：至少说明探测频率、恢复门槛、半开状态。
+- [ ] `P3-B-04` 定义随机源实现策略。
+  完成标准：明确使用线程安全方案。
+- [ ] `P3-B-05` 定义 provider 健康指标。
+  完成标准：至少包含 availability、failure_rate、latency_ema。
+- [ ] `P3-B-06` 补测试场景 1：瞬时故障后恢复。
+  完成标准：写出期望结果。
+- [ ] `P3-B-07` 补测试场景 2：长时间故障保持摘除。
+  完成标准：写出期望结果。
+- [ ] `P3-B-08` 补测试场景 3：并发权重选择无竞态。
+  完成标准：写出期望结果。
+
+### Task P3-C: 统一三服务的 metrics、trace、health 可观测面
+
+**Files:**
+- Modify: `gateway/internal/app/bootstrap.go`
+- Modify: `supply-api/internal/app/bootstrap.go`
+- Modify: `platform-token-runtime/internal/app/bootstrap.go`
+- Modify: `scripts/ci/metrics_daily_snapshot.sh`
+- Create: `docs/plans/2026-04-21-observability-surface-plan.md`
+
+- [ ] `P3-C-01` 盘点三个服务当前暴露的健康接口。
+  完成标准：清单里有路径、响应格式和用途。
+- [ ] `P3-C-02` 定义统一 metrics 路径。
+  完成标准：文档中明确路径和鉴权要求。
+- [ ] `P3-C-03` 定义统一 trace 字段。
+  完成标准：至少包含 request_id、trace_id、span_id。
+- [ ] `P3-C-04` 定义统一基础指标集。
+  完成标准：至少包含请求数、错误数、延迟、上游调用、缓存命中。
+- [ ] `P3-C-05` 定义 token runtime 指标集。
+  完成标准：至少包含 introspection 次数、缓存命中、超时数。
+- [ ] `P3-C-06` 定义 synthetic probe 指标集。
+  完成标准：至少包含 gateway health、token introspection、supply auth path。
+- [ ] `P3-C-07` 设计 `metrics_daily_snapshot.sh` 从运行时采集而非 grep 文档的方案。
+  完成标准：至少写出三个采集入口。
+- [ ] `P3-C-08` 设计 Dashboard/告警最小模板。
+  完成标准：包含 SLI、SLO、报警阈值草稿。
+
+### Task P3-D: 收紧后台 worker 的启动、退出和验证纪律
+
+**Files:**
+- Modify: `supply-api/internal/app/background.go`
+- Modify: `supply-api/internal/app/runtime.go`
+- Modify: `supply-api/cmd/supply-api/main.go`
+- Create: `docs/plans/2026-04-21-background-worker-exit-checklist.md`
+
+- [ ] `P3-D-01` 盘点所有后台 worker 入口。
+  完成标准：清单覆盖 outbox、revocation、partition maintenance、compensation。
+- [ ] `P3-D-02` 盘点哪些 worker 在内部使用了 `context.Background()`。
+  完成标准：清单逐个写出调用点。
+- [ ] `P3-D-03` 定义 worker 启动日志最小字段。
+  完成标准：至少包含 worker 名称、配置、间隔、run_id。
+- [ ] `P3-D-04` 定义 worker 退出日志最小字段。
+  完成标准：至少包含 worker 名称、退出原因、持续时间。
+- [ ] `P3-D-05` 定义 worker shutdown 超时策略。
+  完成标准：写出 rootCtx、initCtx、shutdownCtx 的边界。
+- [ ] `P3-D-06` 定义 worker 健康指标。
+  完成标准：至少包含 last_success_ts、last_error_ts、loop_duration。
+- [ ] `P3-D-07` 设计 startup precheck。
+  完成标准：在 prod/staging 缺少 broker 时行为清晰。
+- [ ] `P3-D-08` 编写后台 worker 退出检查清单。
+  完成标准：可用于人工演练或 CI smoke 复核。
+
+---
+
+## Phase 4 任务清单
+
+### Task P4-A: 抽取共享 auth / audit / logging 能力
+
+**Files:**
+- Modify: `gateway/internal/middleware/chain.go`
+- Modify: `platform-token-runtime/internal/auth/middleware/token_auth_middleware.go`
+- Modify: `gateway/internal/pkg/logging/logger.go`
+- Modify: `platform-token-runtime/internal/pkg/logging/logger.go`
+- Modify: `supply-api/internal/pkg/logging/logger.go`
+- Create: `internal/shared/auth/README.md`
+- Create: `internal/shared/logging/README.md`
+
+- [ ] `P4-A-01` 盘点三个服务的 auth middleware 差异点。
+  完成标准：按“可共享”和“必须保留差异”两列输出。
+- [ ] `P4-A-02` 盘点三个服务的 logging 差异点。
+  完成标准：列出字段名、输出格式、fatal 行为差异。
+- [ ] `P4-A-03` 盘点 audit emitter/表契约差异。
+  完成标准：写出当前表名和字段差异。
+- [ ] `P4-A-04` 定义共享包边界。
+  完成标准：明确什么放共享包，什么保留在服务内。
+- [ ] `P4-A-05` 定义迁移顺序。
+  完成标准：先抽 logging、再抽 auth、再抽 audit，或给出其他单一路径。
+- [ ] `P4-A-06` 定义兼容适配层。
+  完成标准：不允许一次性跨三个服务大爆炸改动。
+- [ ] `P4-A-07` 为共享日志格式写 golden output 测试方案。
+  完成标准：至少覆盖 info、warn、error、fatal。
+- [ ] `P4-A-08` 为共享 auth 行为写契约测试方案。
+  完成标准：至少覆盖 missing bearer、invalid token、inactive token。
+
+### Task P4-B: 拆分大文件并收口未接入能力
+
+**Files:**
+- Modify: `supply-api/internal/httpapi/supply_api.go`
+- Modify: `supply-api/internal/app/runtime.go`
+- Modify: `supply-api/internal/middleware/auth.go`
+- Modify: `gateway/internal/app/bootstrap.go`
+- Modify: `gateway/README.md`
+
+- [ ] `P4-B-01` 记录 `supply_api.go` 的 handler 分区。
+  完成标准：至少分账户、套餐、结算、收益、审计。
+- [ ] `P4-B-02` 记录 `runtime.go` 的职责分区。
+  完成标准：至少分输入解析、资源初始化、store bundle、security bundle、api bundle。
+- [ ] `P4-B-03` 记录 `auth.go` 的职责分区。
+  完成标准：至少分 query reject、bearer extract、verify、error helpers。
+- [ ] `P4-B-04` 记录 `gateway` 实验能力清单。
+  完成标准：标出已接入与未接入模块。
+- [ ] `P4-B-05` 决策未接入路由能力“删除/迁移到 experimental/正式接入”三选一。
+  完成标准：只保留一个决策。
+- [ ] `P4-B-06` 写 `InvariantChecker` 的去留决策。
+  完成标准：明确“接入真实写路径”还是“删除”。
+- [ ] `P4-B-07` 如果接入，定义接入点顺序。
+  完成标准：至少包含 account、package、settlement 三类写路径。
+- [ ] `P4-B-08` 如果删除，写删除清单和回归测试清单。
+  完成标准：包含代码、测试、README 三类位置。
+
+### Task P4-C: 补齐 IAM 的 tenant / operator / scope 闭环
+
+**Files:**
+- Modify: `supply-api/internal/iam/handler/iam_handler.go`
+- Modify: `supply-api/internal/iam/middleware`
+- Modify: `supply-api/internal/app/runtime.go`
+- Modify: `supply-api/internal/app/bootstrap.go`
+- Create: `docs/plans/2026-04-21-iam-closure-checklist.md`
+
+- [ ] `P4-C-01` 标记 IAM handler 中所有直接写死 `tenantID` 或上下文占位注释的位置。
+  完成标准：清单覆盖全部待收口点。
+- [ ] `P4-C-02` 定义 IAM 路由消费的 principal 字段。
+  完成标准：至少包含 tenant、operator、role、scope。
+- [ ] `P4-C-03` 定义 IAM middleware 链顺序。
+  完成标准：明确 bearer extract、verify、scope check、operator inject 顺序。
+- [ ] `P4-C-04` 标记当前启动链缺少 scope middleware 的位置。
+  完成标准：清单写出具体注册入口。
+- [ ] `P4-C-05` 设计 IAM handler 的错误码口径。
+  完成标准：区分 unauthenticated、unauthorized、tenant mismatch。
+- [ ] `P4-C-06` 设计 IAM contract tests。
+  完成标准：至少覆盖 viewer、operator、admin 三个角色。
+- [ ] `P4-C-07` 设计 IAM 审计事件字段。
+  完成标准：至少包含 operator_id、tenant_id、action、result_code。
+- [ ] `P4-C-08` 写 IAM 闭环检查清单。
+  完成标准：只有 principal、scope、audit、tests 四者齐全才算完成。
+
+### Task P4-D: 清理 secret 治理和 KMS 误导性表述
+
+**Files:**
+- Modify: `scripts/supply-gate/.env`
+- Modify: `scripts/devtest/start_dev_stack.sh`
+- Modify: `supply-api/internal/security/kms_service.go`
+- Modify: `supply-api/config/config.dev.yaml`
+- Modify: `gateway/internal/config/config.go`
+- Create: `docs/plans/2026-04-21-secret-and-kms-governance-checklist.md`
+
+- [ ] `P4-D-01` 检查被 git 跟踪的 `.env` 和本地凭据文件。
+  完成标准：形成“必须去跟踪”和“可保留模板”两列清单。
+- [ ] `P4-D-02` 把 `scripts/supply-gate/.env` 转成模板或移出版本控制方案。
+  完成标准：文档中明确迁移方式。
+- [ ] `P4-D-03` 盘点 `start_dev_stack.sh` 中的默认密码和默认 secret。
+  完成标准：全部列入治理清单。
+- [ ] `P4-D-04` 设计“本地默认 secret 只允许通过显式 dev profile 注入”的规则。
+  完成标准：规则可落到脚本和 README。
+- [ ] `P4-D-05` 重写 `kms_service.go` 的能力说明。
+  完成标准：文案中明确这是 local envelope demo，不是生产 KMS。
+- [ ] `P4-D-06` 定义真正生产 KMS 的接入前置条件。
+  完成标准：至少包含 provider、auth、rotation、audit、failure mode。
+- [ ] `P4-D-07` 盘点 `gateway` 默认加密 key 的保留理由与替代方案。
+  完成标准：决策文档中只保留一个替代方案。
+- [ ] `P4-D-08` 写 secret 与 KMS 治理检查清单。
+  完成标准：包含“模板、注入、轮换、审计、回收”五类项。
+
+## 6. 阶段退出验证清单
+
+### Phase 1 Exit Gate
+
+- [ ] authority 决策已写入规范和 README。
+- [ ] schema、model、audit 字段对齐决策已确定。
+- [ ] gateway 与 supply-api 的迁移方案和回滚方案已成文。
+- [ ] contract tests 场景清单已形成并进入 CI 设计。
+
+### Phase 2 Exit Gate
+
+- [ ] `run_id + manifest` 规则已形成。
+- [ ] real staging 成为唯一硬门禁。
+- [ ] `DEFERRED` 不再计入通过率。
+- [ ] staging/prod 模板不再复用 dev 配置。
+- [ ] cross-service smoke 已被纳入发布链。
+
+### Phase 3 Exit Gate
+
+- [ ] remote runtime 有超时、缓存和指标设计。
+- [ ] router 有自动恢复设计。
+- [ ] 三服务统一 observability surface 已定义。
+- [ ] worker 启动、退出和 shutdown 纪律已可验证。
+
+### Phase 4 Exit Gate
+
+- [ ] shared package 边界已定义。
+- [ ] 大文件拆分顺序已成文。
+- [ ] IAM 闭环路径已定义。
+- [ ] tracked `.env`、默认 secret、KMS 表述风险都已有治理路径。
+
+## 7. 任务清单复审
+
+### 7.1 复审方法
+
+本次复审按五个维度检查每个阶段是否闭环：
+
+1. 设计闭环：是否先明确单一规则，而不是边改边猜。
+2. 实现闭环：是否覆盖会改动的代码、脚本、配置和文档。
+3. 验证闭环：是否为阶段目标设计了可执行 gate。
+4. 发布闭环：是否考虑回滚、兼容窗口和放量顺序。
+5. 治理闭环：是否考虑长期维护、README、模板和审计口径。
+
+### 7.2 复审结论
+
+**Phase 1 复审结论：可以达成。**
+
+原因：
+
+- 已覆盖 authority 决策、schema 对齐、实现收敛、contract gate。
+- 已包含回滚和兼容窗口任务。
+- 不再只停留在“代码该怎么改”，而是先收敛规范和契约。
+
+前提：
+
+- 执行时必须坚持“schema 保留或删除二选一”，不能双轨。
+
+**Phase 2 复审结论：可以达成。**
+
+原因：
+
+- 已覆盖 run_id、manifest、real staging、环境模板、真实 smoke。
+- 已补上 override 机制和 `DEFERRED` 口径调整。
+
+前提：
+
+- 执行时必须同时修改所有消费旧工件查找逻辑的脚本，不能只改主流水线。
+
+**Phase 3 复审结论：可以达成。**
+
+原因：
+
+- 已覆盖 remote runtime、router 恢复、metrics/trace、worker shutdown。
+- 已把“离线报告推导”替换为“运行时采集”纳入目标。
+
+前提：
+
+- 执行时必须把指标出口和 CI 采集脚本一起改，否则会留下半成品。
+
+**Phase 4 复审结论：可以达成。**
+
+原因：
+
+- 已覆盖共享能力抽取、大文件拆分、IAM 闭环、secret/KMS 治理。
+- 已把“未接入能力”与“误导性文案”都纳入治理，不只是改代码。
+
+前提：
+
+- 执行时必须遵循“小步迁移 + 兼容适配层”，不能跨多个服务一次性重构。
+
+### 7.3 复审后补充的强制约束
+
+为保证这份清单能彻底达成四阶段目标，执行时必须额外遵守以下约束：
+
+1. 每个阶段结束前，必须先通过该阶段 Exit Gate，再开始下一阶段。
+2. 每个阶段至少保留一次回滚演练记录。
+3. 每个阶段的关键决策必须同步更新 README 或规范文档。
+4. 任何“先改代码，之后补文档”的做法都视为阶段未完成。
+
+### 7.4 最终判断
+
+在满足以下三个条件时，这份任务清单足以彻底达成各阶段目标：
+
+1. 执行顺序严格按 Phase 1 -> Phase 2 -> Phase 3 -> Phase 4 推进。
+2. 每个阶段都先完成规范与 gate，再进入实现。
+3. 所有脚本、配置、README、契约测试都跟着代码一起收口。
+
+如果执行中跳过任一类任务，这份清单就只能“局部改善”，不能“彻底达成”。
+
+## 8. 推荐执行顺序
+
+1. 先完成 `P1-A` 到 `P1-D`，确认身份和契约真源。
+2. 再完成 `P2-A` 到 `P2-D`，确认发布和环境真源。
+3. 再完成 `P3-A` 到 `P3-D`，补齐性能和可观测性。
+4. 最后完成 `P4-A` 到 `P4-D`，做结构和治理收口。
+
+## 9. 建议的执行节奏
+
+1. 每次只执行一个 Task Group。
+2. 每完成一个 Task Group 就提交一次中间文档或代码。
+3. 每完成一个 Phase 就做一次人工复审和一次脚本复核。

docs/token_runtime_minimal_spec_v1.md

@@ -17,6 +17,17 @@
 4. 边界审计：签发/校验失败/吊销/越权事件全量入审计。
 5. 指标可观测：可计算 M-013~M-016 与 M-021。
 
+## 2.1 唯一 Authority 约束
+
+`platform-token-runtime` 是唯一 token authority。
+
+约束：
+
+1. `gateway` 只负责接入、校验、转发和入口审计，不再在非 `dev` 环境承载本地 token authority。
+2. `supply-api` 只消费 canonical principal，不再拥有独立的 token authority 语义。
+3. token 生命周期、状态解释、吊销语义和 introspection 字段都以 `platform-token-runtime` 为单一真源。
+4. 任意 README、OpenAPI 草案、DDL 和运行时代码都不得声明第二个 authority。
+
 ## 3. 角色与权限
 
 | 角色 | 能力 | 约束 |
@@ -31,6 +42,7 @@
 |---|---|---|
 | token_id | string | 平台内部唯一标识 |
 | subject_id | string | 用户/服务主体ID |
+| tenant_id | string | 租户唯一标识 |
 | role | string | owner/viewer/admin |
 | issued_at | datetime | 签发时间 |
 | expires_at | datetime | 过期时间 |
@@ -39,6 +51,25 @@
 | request_id | string | 请求追踪ID |
 | revoked_reason | string | 吊销原因（可空） |
 
+### 4.1 Canonical Principal 字段清单
+
+canonical principal 至少包含以下字段：
+
+1. `token_id`
+2. `subject_id`
+3. `tenant_id`
+4. `role`
+5. `scope`
+6. `issued_at`
+7. `expires_at`
+8. `status`
+
+说明：
+
+1. `gateway` 和 `supply-api` 只消费 canonical principal，不自行扩展 authority 语义。
+2. 如果后续补充 `project_id`、`operator_id`、`metadata`，必须同时更新 DDL、OpenAPI、存储模型和审计字段。
+
+
 ## 5. 生命周期状态机
 
 `active -> revoked -> expired`