# 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 快速验证命令

在目标工作区执行：

```bash
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。