forge_admin/code-copilot/changes/unified-capability-open-platform/test-spec.md

测试规格 — 统一能力开放平台

变更目录：code-copilot/changes/unified-capability-open-platform/ 依据：code-copilot/rules/automated-testing-standard.md（增量优先、证据优先） 创建：2026-07-31（本变更首个测试轮次，无历史 test-spec 可复用）

1. 变更概述

将 Forge Capability 底座通过 REST 开放网关 POST /openapi/v1/capabilities/{capabilityCode}/invoke 开放给外部机器客户端。涉及：

• 后端新模块：forge-starter-openapi-security（防重放/限流/幂等通用组件）、forge-plugin-capability-identity（客户端凭据与签名认证）、forge-plugin-capability-open-gateway（网关认证 + 九步编排）
• 控制面扩展：客户端/授权/发布/调用日志管理接口（control-plane）
• Flyway：V1.0.74__capability_open_gateway.sql（表/字典/菜单/权限）+ V1.0.75__add_capability_registration_dict.sql（流程动作字典）+ V1.0.76__add_capability_external_user_delegation.sql（客户端主体模式与外部身份映射）
• 前端：forge-admin-ui/src/api/ai/capability.js + views/ai/capability/{catalog,client,grant,invocation}.vue + 能力注册弹窗
• 清理任务：幂等快照过期清理

2. 验证范围与优先级

P0（必须通过）

编号	验证项	方式	命令/位置
P0-1	OpenApiReplayGuard 单测：appId 缺失 401 / 时间戳超窗 401 / nonce 格式非法 401 / nonce 重复 401 / Redis 不可用与异常失败关闭 503 / 正常放行	JUnit5 + Mockito	forge-starter-openapi-security → OpenApiReplayGuardTest
P0-2	CapabilityInvokeOrchestrator 单测：scope 缺失 FORBIDDEN / 授权目录不可用 INTERNAL_ERROR 503 / ACTOR_TYPE_NOT_ALLOWED / 权限缺失 FORBIDDEN / RATE_LIMITED 429 / 写操作缺 Idempotency-Key SCHEMA_INVALID / 幂等命中 idempotentHit / payload 非法顶层字段 SCHEMA_INVALID / READ_ONLY 跳过幂等 / 写路径成功 SUCCESS	JUnit5 + Mockito	forge-plugin-capability-open-gateway → CapabilityInvokeOrchestratorTest
P0-3	Admin 聚合生产打包	JAVA_HOME=... mvn -Penable-tests -pl forge-admin-server -am package -Dforge.tests.skip=true（forge-server 根）	47 个 Reactor 模块成功
P0-4	本变更 Flyway 脚本静态检查（无占位符）	rg -n '\$\{[^}]+\}' forge-server/db/migration/V1.0.7{4,5,6}__*.sql	应无输出；全目录存在 V1.0.72 历史占位符，不能作为本变更失败依据
P0-5	前端构建	nvm use v20.19.0 && NODE_OPTIONS=--max-old-space-size=8192 pnpm build（forge-admin-ui）	构建成功
P0-6	前端 Lint（API、4 页面、注册组件）	pnpm exec eslint src/api/ai/capability.js src/views/ai/capability/*.vue src/views/ai/capability/components/*.vue	零错误
P0-7	控制面授权候选项、客户端凭据和 ACTION/FLOW 授权策略	JUnit5 + Mockito，4 个目标测试类	23 条通过
P0-8	流程能力注册来源校验	FlowActionSourceServiceTest + FlowActionCapabilityPublisherTest	5 条通过
P0-9	签名 AppId 稳定性与网关认证	OpenGatewayAuthenticatorTest	2 条通过；数值 clientId 同时作为 OAuth client_id 与签名 AppId

P1（视环境执行，不可用则记录跳过原因）

编号	验证项	方式	前置条件
P1-1	端到端：启动 admin 服务 → Flyway V1.0.74 迁移成功	启动日志 + forge_schema_history	本地 MySQL/Redis 可用
P1-2	端到端：创建客户端 → 授权能力 → HMAC 签名 curl 调用 /openapi/v1/capabilities/{code}/invoke 走通 8 错误码契约	curl	本地 MySQL/Redis 可用 + 存在已发布能力
P1-3	控制台 4 页面（能力目录/机器客户端/能力授权/调用日志）人工走查	浏览器	前后端均启动

3. 测试环境与约束

• Java 17：JAVA_HOME=/opt/homebrew/Cellar/openjdk@17/17.0.13/libexec/openjdk.jdk/Contents/Home
• 单测使用 Mockito（spring-boot-starter-test 已在两模块 pom 中），不依赖 MySQL/Redis
• 默认不跑全量 mvn test，仅跑本变更两个模块的单测

4. 结果记录

执行证据统一记录到同目录 execution-log.md。

5. 2026-08-01 前端可用性修复增量验证

• 能力目录新增业务动作/流程动作可视化注册，不暴露原始 Schema JSON。
• 机器客户端改用服务账号选择器和组织绑定下拉，认证模式字典缺失时阻止无效提交。
• 客户端创建按 OAUTH/SIGNATURE 模式同步 OAuth 启用状态，覆盖默认 OAuth 可用与纯签名关闭分支。
• 客户端数值 ID 统一作为 OAuth client_id 和签名 X-Forge-App-Id，OAuth 密钥轮换不再改变签名身份标识。
• 授权候选项改为同权限专用接口，结构化生成字段/操作白名单，ACTION/FLOW 不再被运行时只读策略误拒绝。
• 流程对象选择后实时校验已发布主流程绑定；非平台托管对象不允许注册 START。
• 自动化和静态验证均通过；真实数据库迁移、登录态浏览器操作和外部调用 E2E 保留为部署门禁。

6. 2026-08-01 能力注册接口 404 增量验证

• 根因：业务动作/流程动作的管理控制面 Controller 与运行时执行 Bean 共用 enabled 条件，默认关闭外部网关时路由也被移除。
• P0：FlowActionAutoConfigurationTest 验证开关关闭时保留来源/发布 Bean，不装配执行日志与流程执行适配器；开启时执行 Bean 正常装配。
• P0：SecureActionAutoConfigurationTest 验证开关关闭时保留业务动作发布 Bean，不装配 MCP 目录/Handler/工具贡献者；开启时运行时 Bean 正常装配。
• P0：两个 Controller 不再携带运行时 @ConditionalOnProperty，前端 404 显示明确的 Admin 更新/重启提示。
• P0：目标模块测试、Admin 聚合编译、前端定向 ESLint 和 git diff --check。
• P1：用户重启当前 Admin 进程后，带登录态调用 GET /ai/capability/flow-action/registration-source，预期从 404 变为成功数据或可解释的业务校验错误。

7. 2026-08-01 外部用户无绑定委托与能力文档增量验证

• P0：CapabilityClientServiceTest 覆盖 USER_DELEGATION 不需要 serviceUserId/activeOrgId、拒绝 SIGNATURE，以及 SERVICE/HYBRID 仍强制绑定。
• P0：外部 JWT 验证测试覆盖受信 RS256、未知 issuer、错误 audience、过期 Token、JWK/用户目录失败关闭、首次手机号匹配、姓名不一致、issuer+sub 稳定映射。
• P0：系统用户目录按已验证手机号最多读取两条有效候选；零条或重复候选均返回 invalid_grant，禁止任意选取第一条。
• P0：Token Exchange 测试覆盖机密客户端认证、USER_DELEGATION 模式、USER Token 签发及 /oauth2/userinfo 身份返回。
• P0：CapabilityAccessTokenServiceTest 与流程动作测试覆盖 USER 身份 serviceUserId 可空，SERVICE 身份仍强制服务账号。
• P0：能力 OpenAPI 文档测试覆盖发布版本 Schema、认证方式、幂等头、错误码、actor type，且不包含密钥字段。
• P0：V1.0.76 防重复/tenant_id/主键墓碑静态检查，Identity/Control Plane/Flow Actions 目标模块测试，Admin 聚合编译，前端定向 ESLint 与生产构建。
• P1：用户配置真实 OIDC issuer/JWK、MySQL/Redis 后执行 JWT Token Exchange → userinfo → FLOW_ACTION START/APPROVE，并验证非办理人被拒绝。

8. 2026-08-01 Capability Pepper 自动引导增量验证

• P0：Starter Crypto 测试覆盖三个 Pepper 首次生成、32 字节随机强度、互不相同和跨重启复用。
• P0：旧版 crypto.properties 不含 Pepper 时，在文件锁内原子补齐并保留既有 Crypto 密钥。
• P0：环境变量/JVM 参数对三个 Pepper 逐项覆盖；application.yml 空占位符不得覆盖持久化值。
• P0：显式关闭 forge.crypto.bootstrap.enabled 时不生成文件或 Pepper，Capability 既有启动校验继续失败关闭。
• P0：SpringApplication 集成测试确认配置绑定前可见三个属性；Identity 全量测试和 Admin 47 模块聚合编译回归。