forge_admin/code-copilot/changes/archive/2026-07-12-forge-ai-hub-control-plane/tasks.md

任务拆分 — Forge AI 中枢控制面

变更名：forge-ai-hub-control-plane 执行方式：用户已预授权 Proposal 后自动 Apply；TDD；禁止 commit/push

前置条件

• 阶段 0 已归档且 Capability/MCP/AI/Admin 验证通过；
• 读取根 AGENTS、长期记忆、自动化测试标准和相关 Skills；
• 检查阶段 1 路线图、当前 Capability/MCP 实现和 SDK 动态目录限制；
• 确认下一个 Flyway 版本为 V1.0.21；
• 不覆盖工作区已有供应商、模型路由、组织权限和 vendor 源码改动。

Task 1：Flyway 控制面结构

• 新建五张表，全部包含标准审计字段和 del_flag tinyint；
• 为能力编码、工具名、版本、客户端编码和 grant 增加仅约束有效记录的生成列唯一键；
• 添加 capability/client/grant 状态与可见性字典，内置数据 tenant_id=1；
• 添加控制面 API 权限资源，全部 NOT EXISTS；
• 静态检查 ${...}、tenant 0、无列名 INSERT 和物理 DELETE。

Task 2：实体、Mapper 与 XML

• 新建五个 TenantEntity 实体并显式 @TableLogic；
• 新建 Mapper，分页、详情、唯一性和授权决策查询全部写 XML；
• XML 显式列清单、tenant_id 和 del_flag=0；
• 调用日志 Mapper 只接受安全元数据模型。

Task 3：能力目录与不可变版本

• Red：重复 code/toolName、无效 Schema、相同版本修改和跨租户详情必须失败；
• 实现发布事务：校验 Schema、计算 checksum、插入不可变 version、更新 current pointer；
• 只允许 READ_ONLY、LOW/MEDIUM 进入本阶段 grant；
• 实现分页、详情和停用。

Task 4：机器客户端凭据

• Red：缺 Pepper、Secret 落库、错误 Secret、过期/吊销客户端、非正数 user/org 必须失败；
• 使用 SecureRandom 生成 256 bit Secret，HMAC-SHA256 + 常量时间比较；
• 创建/轮换只返回一次原始 Secret，持久化只保存 prefix/hash/version；
• 实现 revoke 与安全分页，不返回 keyHash。

Task 5：显式授权交集

• Red：跨租户、组织不一致、客户端/能力/grant 禁用或过期、版本不匹配全部拒绝；
• 实现 PINNED/FOLLOW_MAJOR 版本解析；
• ACTION/FLOW/MESSAGE/EXTERNAL 能力拒绝授权；
• 授权分页、创建和撤销使用逻辑删除。

Task 6：调用审计

• Red：安全事件写入后不包含 arguments/data/Header/Token/Secret；
• 实现幂等 requestId 写入和日志分页；
• 失败日志只存稳定 errorCode/schemaPath，不存 Throwable message；
• 保留后续留存任务接口，不在本变更物理删除日志。

Task 7：管理 API 与安全边界

• Controller 使用 RespInfo、pageNum/pageSize、POST-safe 写接口；
• 加入 @SaCheckPermission、@OperationLog、@ApiDecrypt/@ApiEncrypt；
• DTO 不包含 tenantId、keyHash、delFlag 等受控字段；
• MCP 自动配置不注入持久化能力，现有 ping 测试保持全绿。

Task 8：验证与文档

• Capability/MCP 测试真实执行且无 skip；
• 控制面领域测试覆盖 P0 安全分支；
• AI 84 tests 回归；
• Admin 38 个预期聚合模块 package（以实际 reactor 数为准）；
• Flyway、XML、SSE/Nacos/高风险工具/敏感日志/空白扫描；
• 回填四份文档，执行两阶段 Review；
• Review 通过前未归档；当前保持 review-ready 等待用户明确归档。

Review 结果

• Spec Compliance Review 通过，无前端、低代码执行器、动态业务 Tool、Nacos 或旧 SSE 范围漂移；
• Code Quality Review 完成并修复 6 类安全/一致性问题；
• 最终修复后 Capability 13、Control Plane 20、MCP 13、AI 84、Admin 身份适配 2 项、Admin 38/38 全部通过；
• 状态保持 review-ready，等待用户后续明确归档。

2026-07-12 增量 Fix

• Secret 改为全局不可猜测 keyId 格式，认证前不再要求调用方提供 tenantId；
• authenticate/rotate/revoke 使用目标字段原子更新和 credential_version CAS，旧快照不能恢复已吊销凭据；
• 版本 checksum 与不可变校验覆盖 source、behavior、riskLevel、visibility 全部执行语义；
• 审计增加 actor/service 双身份字段并限制稳定码格式，拒绝原始异常、Token、Secret 内容；
• Admin 组合根接入 Bearer 机器凭据解析器，只信任数据库绑定的 tenant/serviceUser/activeOrg；
• 认证前凭据定位和 last_used_at CAS 更新均显式绕过自动租户追加，同时保留 SQL 内权威 tenant 条件；
• 完成 Control Plane 20、MCP 13、AI 84、Admin 身份适配 2 项与 38/38 聚合回归；
• 明确具体人员委托令牌为下一独立变更，本轮禁止信任调用方自报 userId Header。

Archive

• 用户于 2026-07-12 明确要求归档上一个阶段需求并开始阶段 2；
• 核对四份文档、长期决策、踩坑记录、最终验证证据和跳过项；
• 状态更新为 done，归档到 code-copilot/changes/archive/2026-07-12-forge-ai-hub-control-plane/；
• 下一变更固定为 mcp-user-delegation-identity，不在归档动作中追加业务代码。