aios/docs/codex/gitops-platform-ui-validation-playbook.md

Codex 验收手册：GitOps Platform UI

目标

本次变更的目标是把 cnnetmkt.top AIOS GitOps Web UI 从基础 dashboard 升级为平台级控制台，形成可审计、可审批、可灰度、可回滚请求的 GitOps 操作入口。

验证分支

• Branch: patch/web-ui-complete-gitops-dashboard-20260706
• Base: main
• 当前目标基线: V1R1C4
• 合并后建议新基线: V1R1C5

主线差异点

与 main 相比，本分支新增或修改以下直接内容：

1. overlays/user-control-center/portal/gitops-dashboard/index.html

   • 新增平台级 GitOps 控制台页面。
   • 包含 Overview、RBAC、Approval、Diff Tree、Patch、Model、Release、Audit 模块。

2. overlays/user-control-center/portal/gitops-dashboard/app.js

   • 新增浏览器运行时 Platform Control Plane。
   • 包含 API-first client、RBAC guard、approval fallback、audit local store、diff tree parser、model graph、SSE event hook。

3. overlays/user-control-center/portal/gitops-dashboard/styles.css

   • 控制台样式。

4. overlays/user-control-center/portal/gitops-dashboard/manifest.json

   • 控制台 manifest。

5. overlays/user-control-center/portal/gitops-dashboard/gitops-ui-policy.json

   • UI 侧策略声明。

6. overlays/user-control-center/portal/gitops-dashboard/gitops-enterprise-api.contract.json

   • 后端 API 契约说明。

7. patches/patch_web-ui-complete-gitops-dashboard-20260706.branch.json

   • GitOps branch 元数据。

间接影响区域

Codex 验证时必须确认以下间接影响：

1. Portal 登录入口不应被破坏。

   • /portal/me/#gitops
   • /portal/me/#gitops-dashboard

2. 现有短链仍应保持登录保护或正常跳转。

   • /base
   • /ver
   • /diff
   • /patch
   • /model
   • /run

3. 机器 API 不应被前端变更破坏。

   • /api/base
   • /api/ver
   • /api/diff
   • /api/patch
   • /api/model
   • /api/run

4. 敏感信息不得进入 Git、日志、前端源码或测试产物。

   • 禁止真实 API key。
   • 禁止 Bearer token。
   • 禁止 password / private key。
   • 允许 secret_ref://...。

5. 高风险操作不得绕过审批。

   • rollback 只能 request。
   • tag/release 默认只能 request。
   • runtime 写入只能 request。
   • UI 不提供 direct main write。

Codex 快速验证命令

在目标工作区执行：

git fetch --all --prune
git checkout patch/web-ui-complete-gitops-dashboard-20260706
git diff --stat main...HEAD
bash scripts/validate-gitops-platform-ui.sh patch/web-ui-complete-gitops-dashboard-20260706 main

灰度验证外的必测项目

除正常灰度页面点击验证外，Codex 必须按 tests/acceptance/gitops-platform-ui.acceptance.json 执行以下测试组：

1. Static Files

   • 必须存在 index/html/js/css/manifest/policy/contract 文件。

2. Security

   • 源码中不得出现真实 secret/token/password。
   • 模型注册必须只允许 secret_ref://。
   • rollback/tag/runtime/main write 必须 request-only 或 disabled。

3. UI Direct Impact

   • 所有 tab id 必须能在 HTML 中找到。
   • app.js 必须绑定 DOMContentLoaded。
   • app.js 必须包含 guardAction、audit、createApproval、renderDiffTree。

4. API Contract Compatibility

   • 读接口保持 /api/base、/api/ver、/api/run、/api/patch、/api/model。
   • 写接口必须包含 branch、patch/plan、model、model-priority、rollback-request、tag-request。

5. Indirect Regression

   • 不得修改 auth/casdoor 配置。
   • 不得修改 Gitea owner password sync 配置。
   • 不得修改 baseline active_version。
   • 不得删除任何版本/tag/patch 历史。

验收判定

• PASS: 所有 required 测试项通过，且没有 secret 泄漏、没有 direct main write、没有破坏短链/API。
• FAIL: 任一 required 测试项失败。
• BLOCKED: 需要真实后端或浏览器环境，但静态检查通过；必须列出 blocked 项，不得合并 main。

失败回流规则

如果验证失败，Codex 必须输出：

1. 失败测试 ID。
2. 失败文件路径。
3. 具体失败原因。
4. 最小修改建议。
5. 是否阻止合并。

然后把问题交给自定义 GPT 继续修改同一 patch 分支。修复后重复执行完整验收，直到 PASS。

合并规则

只有满足以下条件才能合并 main：

1. scripts/validate-gitops-platform-ui.sh PASS。
2. acceptance JSON 中所有 required: true 项 PASS。
3. 灰度验证通过。
4. 无 secret 泄漏。
5. 无 direct main write。
6. 已创建或确认合并后基线提案 V1R1C5。

合并后基线要求

合并进入 main 后，必须定义新基线：

• Version: V1R1C5
• Purpose: Promote AIOS GitOps Platform Control Plane UI with Codex validation workflow, acceptance tests, RBAC/approval/audit/release/model control-plane scaffolding.
• Risk: high
• Approval: owner/admin required
• Rollback target: V1R1C4

合并后再创建 tag/version，不允许在未合并或未验收通过前直接创建生产 tag。