diff --git a/docs/plans/2026-04-21-project-quality-performance-ops-optimization-execution-log.md b/docs/plans/2026-04-21-project-quality-performance-ops-optimization-execution-log.md index feb64a8f..1ed41df3 100644 --- a/docs/plans/2026-04-21-project-quality-performance-ops-optimization-execution-log.md +++ b/docs/plans/2026-04-21-project-quality-performance-ops-optimization-execution-log.md @@ -46,3 +46,18 @@ rg -n "IntrospectTokenResponse|tenant_id|project_id|operator_id|metadata|IssueTo 1. `IssueTokenRequest` 已定义 `metadata`，但 `IntrospectTokenResponse.data` 尚未暴露 `tenant_id`。 2. 现有 introspection 响应字段只有 `token_id`、`subject_id`、`role`、`status`、`scope`、`issued_at`、`expires_at`，与 canonical principal 最小字段清单相比缺少 `tenant_id`。 3. `project_id`、`operator_id`、`metadata` 目前也未出现在 introspection 响应中，但它们尚未进入最小 canonical principal 强制字段，保留为 Phase 1 后续 schema / 审计收敛项。 + +## P1-A-07 supply-api README 统一 principal 说明 + +结论： + +1. 已在 `supply-api/README.md` 明确 `supply-api` 只消费 canonical principal，不自持独立 token authority。 +2. 文档现在把 token 状态与权限判断的唯一来源收束到 `platform-token-runtime` 的 introspection 结果。 + +## P1-A-08 platform-token-runtime README 唯一 authority 与字段边界 + +结论： + +1. 已在 `platform-token-runtime/README.md` 明确 `platform-token-runtime` 是唯一 token authority。 +2. 文档现在把 canonical principal 的最小字段边界写死为 `token_id`、`subject_id`、`tenant_id`、`role`、`scope`、`issued_at`、`expires_at`、`status`。 +3. 文档同时要求未来扩展字段必须同步更新 DDL、OpenAPI、存储模型和审计字段，避免边界漂移。 diff --git a/docs/plans/2026-04-21-project-quality-performance-ops-optimization-plan.md b/docs/plans/2026-04-21-project-quality-performance-ops-optimization-plan.md index 2cc077c3..f9bde34a 100644 --- a/docs/plans/2026-04-21-project-quality-performance-ops-optimization-plan.md +++ b/docs/plans/2026-04-21-project-quality-performance-ops-optimization-plan.md @@ -206,9 +206,9 @@ 完成标准：OpenAPI 草案与最小规范字段一致。 - [x] `P1-A-06` 在 `gateway/README.md` 增加“非 dev 环境只允许远程 introspection”说明。 完成标准：README 不再给 staging/prod 留下本地 authority 的解释空间。 -- [ ] `P1-A-07` 在 `supply-api/README.md` 增加“消费统一 principal，不自持独立 authority”说明。 +- [x] `P1-A-07` 在 `supply-api/README.md` 增加“消费统一 principal，不自持独立 authority”说明。 完成标准：README 用词与 Phase 1 目标一致。 -- [ ] `P1-A-08` 在 `platform-token-runtime/README.md` 增加“唯一 authority”声明和字段边界。 +- [x] `P1-A-08` 在 `platform-token-runtime/README.md` 增加“唯一 authority”声明和字段边界。 完成标准：三份 README 口径一致。 ### Task P1-B: 收敛 token schema、存储模型和审计字段 diff --git a/platform-token-runtime/README.md b/platform-token-runtime/README.md index 274065f6..a2b5c66d 100644 --- a/platform-token-runtime/README.md +++ b/platform-token-runtime/README.md @@ -6,6 +6,7 @@ - 服务入口是 `cmd/platform-token-runtime/main.go`，装配逻辑收口在 `internal/app/bootstrap.go`。 - 当前可用接口包括 `issue`、`refresh`、`revoke`、`introspect`、`audit-events`。 +- `platform-token-runtime` 是唯一 token authority；对外 introspection 仅暴露 canonical principal 最小字段边界，不在其他服务中复制 authority 语义。 - `TOKEN_RUNTIME_ENV=dev` 且未显式注入 store 时，bootstrap 会自动使用内存 runtime store 与内存 audit store。 - `TOKEN_RUNTIME_ENV=staging` 或 `TOKEN_RUNTIME_ENV=prod` 时，支持通过 `TOKEN_RUNTIME_DATABASE_URL` 自动装配 PostgreSQL runtime store 与 audit store；未提供 DSN 时仍会快速失败，而不是回退到内存实现。 - `audit-events` 当前始终保持可查询接口语义；默认内存 audit store 会返回真实事件，未提供查询能力的自定义 emitter 会返回空结果而不是 `501` 占位响应。 @@ -15,6 +16,7 @@ 1. 仅支持 `Authorization: Bearer ` 入站。 2. 外部 query key（`key`、`api_key`、`token`）一律拒绝。 3. 不在任何响应或审计字段中输出 access token 明文。 +4. canonical principal 最小字段边界为 `token_id`、`subject_id`、`tenant_id`、`role`、`scope`、`issued_at`、`expires_at`、`status`；若后续扩展字段，必须同步更新 DDL、OpenAPI、存储模型与审计字段。 ## 本地运行 diff --git a/supply-api/README.md b/supply-api/README.md index 33bda1dd..81a15928 100644 --- a/supply-api/README.md +++ b/supply-api/README.md @@ -9,6 +9,7 @@ - 数据库不可用时，开发模式下仍保留部分内存降级路径；当前仓库不把这种模式视为生产可用状态。 - 告警 API 在 PostgreSQL 可用时走数据库仓储；数据库不可用时才显式回退内存实现。 - IAM 路由默认不进入对外交付面；只有 `server.iam_enabled=true` 且 runtime 具备数据库依赖时才注册 `/api/v1/iam/*`。 +- `supply-api` 只消费 canonical principal，不自持独立 token authority；token 状态与权限判断以 `platform-token-runtime` 的 introspection 结果为准。 - 提现接口路径存在不代表能力已上线。只有 `settlement.withdraw_enabled=true`、`sms.*` 配置齐备，且 runtime 显式注入了真实 `SMSVerifier` 时，提现才会从关闭态切到可用态。 - 依赖幂等仓储的写接口在中间件缺失时会返回 `503 SUP_HTTP_5031`，不再静默切回内联逻辑。 - Outbox processor 与补偿 worker 仅在数据库可用时启动。