Codex Release Bot
246 lines
9.3 KiB
Markdown
246 lines
9.3 KiB
Markdown
# Nexus 6.0 — 开发验收标准（SSOT）
|
||
|
||
> **更新**: 2026-06-04
|
||
> **读者**: 开发 AI、测试、运维
|
||
> **地位**: 宣称「功能完成 / 可合并 / 可上线」前**必须**对照本文。
|
||
|
||
**相关文档**
|
||
|
||
| 文档 | 路径 |
|
||
|------|------|
|
||
| **功能 SSOT** | [`nexus-functional-development-guide.md`](nexus-functional-development-guide.md) |
|
||
| AI 接续 | [`AI-HANDOFF-2026-06-03.md`](AI-HANDOFF-2026-06-03.md) |
|
||
| 文档总索引 | [`../README.md`](../README.md) |
|
||
| **标准转接包** | [`standards-transfer-package.md`](standards-transfer-package.md) |
|
||
| 生产验证 | [`production-verification-checklist.md`](production-verification-checklist.md) |
|
||
|
||
---
|
||
|
||
## 0. 验收层级总览
|
||
|
||
```
|
||
L0 原则与纪律 perfect-implementation + 架构规则（始终遵守）
|
||
L1 设计验收 设计文档 / 技术文档中的「验收标准」章节
|
||
L2 代码完成 local_verify + pytest +（改 API/前端时）模块手测
|
||
L3 门控 pre_deploy_check.sh 7/7
|
||
L4 模块 E2E run_nexus_acceptance.py --with-ui
|
||
L5 生产部署 production-verification + deploy-production.sh
|
||
```
|
||
|
||
### 改动量级 → 最低验收
|
||
|
||
| 量级 | 范围 | 最低验收 |
|
||
|------|------|----------|
|
||
| **小** | ≤3 文件，非 auth/sync/ssh | L2 + changelog |
|
||
| **中** | 新 API/页面/composable | L2 + 模块 E2E + 精简审计 Closure |
|
||
| **大** | 认证、Agent、sync 引擎 | L2 + L3 + 完整审计 8 步 + 设计/技术文档 |
|
||
|
||
**禁止**：未跑 L2 就声称「已修复 / 已完成」。
|
||
|
||
---
|
||
|
||
## L0 — 实现原则与架构（强制，无例外）
|
||
|
||
| 来源 | 路径 | 要点 |
|
||
|------|------|------|
|
||
| 完美实现 | `.cursor/rules/perfect-implementation.mdc` | 禁止降级/妥协/TODO；先设计→技术文档→代码→验证→changelog |
|
||
| 技术栈 | `.cursor/rules/nexus-tech-stack.mdc` | 四层架构、配置三写、Primary Worker |
|
||
| 后端 | `.cursor/rules/nexus-python-backend.mdc` | API/Service/Repo 分层 |
|
||
| 前端 | `.cursor/rules/nexus-frontend.mdc` | api.js、无 CDN 依赖 |
|
||
| 安全 | `.cursor/rules/nexus-security.mdc` | 凭据、JWT、注入 |
|
||
| 系统开发标准 | `standards/system-development-standard.md` | 完整工程规范 |
|
||
|
||
**执行顺序**（来自 perfect-implementation）：
|
||
|
||
```
|
||
需求确认 → 设计文档 → 技术文档 → 实现 → 测试验证 → changelog
|
||
```
|
||
|
||
**每次代码变更**：
|
||
|
||
- [ ] `docs/changelog/YYYY-MM-DD-<主题>.md` 已写或更新
|
||
- [ ] 新功能/架构变更：已有 `docs/design/specs/` + `docs/design/plans/`（或补全缺档模块）
|
||
- [ ] 无新增 `TODO`/`FIXME`/静默吞错
|
||
|
||
---
|
||
|
||
## L1 — 设计阶段验收标准
|
||
|
||
设计文档 `docs/design/specs/YYYY-MM-DD-<topic>-design.md` **必须包含**：
|
||
|
||
- [ ] 背景与目标
|
||
- [ ] 方案对比与选定理由
|
||
- [ ] 接口 / 数据模型
|
||
- [ ] 安全与性能约束
|
||
- [ ] **验收标准**（可勾选的条目，供 L4/L5 复用）
|
||
|
||
技术文档 `docs/design/plans/` 或 `docs/reports/` **必须包含**：
|
||
|
||
- [ ] 涉及文件清单
|
||
- [ ] 实现步骤
|
||
- [ ] 依赖与配置变更
|
||
- [ ] **测试要点**
|
||
- [ ] 回滚方式
|
||
|
||
---
|
||
|
||
## L2 — 日常开发完成（合并前最低门槛）
|
||
|
||
### 2.1 自动化（必须执行并贴输出）
|
||
|
||
| 场景 | 命令 | 通过标准 |
|
||
|------|------|----------|
|
||
| 任意后端改动 | `pytest tests/test_security_unit.py -q` | 全部 passed |
|
||
| 本地全链路代码向 | `bash scripts/ensure_venv.sh`（首次） | 无 error |
|
||
| | `bash scripts/start-dev.sh` | 服务启动 |
|
||
| | `bash scripts/local_integration_smoke.sh` | security + `/health` + `/api/servers/` 401 |
|
||
| 一键 | `bash scripts/local_verify.sh` | smoke + test_api + ruff |
|
||
| 有 API 契约变更 | `pytest tests/test_api.py`（需 `.env` + 测试账号） | 按项目约定 |
|
||
|
||
详见：[`local-integration-test.md`](local-integration-test.md)
|
||
|
||
### 2.2 按改动类型的附加验收
|
||
|
||
| 改动类型 | 必须验证 |
|
||
|----------|----------|
|
||
| 脚本 / SSH 执行 | 子机执行结果含 `channel: ssh`；危险命令 400 |
|
||
| Agent / 心跳 | 子机出站 443 心跳 200；**不要求**公网 8601 |
|
||
| 推送 / sync | dry-run 首台预览；失败入重试队列 |
|
||
| WebSSH | webssh-token 绑定 server_id；越权 4003 |
|
||
| 设置 / Telegram | 测试发送、告警开关、白名单解析 |
|
||
| 前端页 | 无 `cdn.jsdelivr.net`；Alpine/侧栏正常 |
|
||
| DB 迁移 | `server/infrastructure/database/migrations.py` 可跑；新装/升级路径说明写在 changelog |
|
||
|
||
### 2.3 完成前自检（Agent 直接执行，无 Skill 包）
|
||
|
||
| 动作 | 依据 | 何时 |
|
||
|------|------|------|
|
||
| 跑验证命令后再宣称完成 | `standards/` + `.cursor/rules/perfect-implementation.mdc` | 每次交付前 |
|
||
| 先失败测试再实现 | 项目 `tests/`、设计文档验收标准 | 新功能/修 bug |
|
||
| 根因分析再改代码 | `.cursor/rules/audit-line-review.mdc`（若涉安全路径） | 异常/回归 |
|
||
|
||
---
|
||
|
||
## L3 — 代码审计验收（与开发同等严谨 · 不可简化）
|
||
|
||
**完整标准**：[`standards-transfer-package.md`](standards-transfer-package.md) §2（与团队逐行审查相同）
|
||
|
||
**适用**：用户要求走读/Phase2/全量审计；或改 `server/api/*`、`auth`、`webssh`、`agent`、`script_service`、`sync_engine*`、凭据/websocket、前端 XSS 面。
|
||
|
||
| 文档 | 权威路径 |
|
||
|------|----------|
|
||
| Cursor 触发规则 | `.cursor/rules/audit-line-review.mdc` |
|
||
| 完整走读 v2 | **`standards/line-walk-audit-standard-v2.md`**（§三 八步、§四 规则、§十四 提示词） |
|
||
| 核心原则 | **`standards/audit-core-principles.md`** |
|
||
| Nexus SSOT 副本 | `docs/project/line-walk-audit-standard.md` |
|
||
| FINDING 矩阵 | `docs/reports/audit-phase-2-findings-matrix.md` |
|
||
|
||
**八步 + 限制**（摘要，以 v2 为准）：
|
||
|
||
1. 登记 N → 2. 全文 Read 至 EOF → 3. 规则 → H → 4. Closure（±15 行）→ 5. 入口表 → 6. 输入→sink → 7. 八类 → 8. DoD ✓
|
||
**单回复 ≤5 文件**；禁止 grep/Top15 冒充审计。
|
||
|
||
**单文件 DoD（缺一不可）**：
|
||
|
||
- [ ] `len(H) == Closure 行数`（H=0 写「规则零命中」）
|
||
- [ ] 全文 Read 覆盖 1～N
|
||
- [ ] 每条 FINDING：`文件:行号` + 严重度 + 修复建议
|
||
- [ ] 每条 SAFE：写明依据
|
||
- [ ] API/WS 有入口表
|
||
- [ ] P0/P1 **当场修复**；合并前 **代码待办 = 0**
|
||
- [ ] 产出 `docs/reports/audit-phase-2*-line-walk.md`（Closure **全表含 SAFE**）
|
||
- [ ] 修复写 changelog + 更新矩阵
|
||
|
||
**KPI**：P0 漏报 -100；P1 漏报 -50；无行号 FINDING 无效。
|
||
|
||
---
|
||
|
||
## L4 — 模块专项 E2E（首次部署前建议全做）
|
||
|
||
### 4.1 脚本执行平台
|
||
|
||
文档：[`script-execution.md`](script-execution.md) §11
|
||
|
||
- [ ] T-SE1：3 台短任务，进度 3/3，审计有 `execute_started`
|
||
- [ ] T-SE2：60 台分 2 批
|
||
- [ ] T-SE3：长任务 + `NEXUS_API_BASE_URL` 回调完成
|
||
- [ ] T-SE4～T-SE8：停止、重试、卡住检测、Redis 刷盘
|
||
|
||
**注意**：文档中 Agent HTTP 描述可能过期；执行通道以 **SSH** 为准（见 changelog `2026-05-23-ssh-exec-no-8601.md`）。
|
||
|
||
### 4.2 告警与 Telegram
|
||
|
||
文档：[`alert-push-policy.md`](alert-push-policy.md)
|
||
|
||
- [ ] 超阈值 → Telegram 告警；浏览器**无声音**、无弹窗列表
|
||
- [ ] 恢复 → Telegram 恢复通知
|
||
- [ ] WS 仅刷新仪表盘统计
|
||
- [ ] self_monitor MySQL 异常文案**不含**连接串
|
||
|
||
### 4.3 基础设施（CLAUDE.md T1～T5）
|
||
|
||
- [ ] T1：心跳写入 Redis
|
||
- [ ] T2：WebSocket
|
||
- [ ] T3：杀 Python → Supervisor 拉起
|
||
- [ ] T4：Telegram
|
||
- [ ] T5：install.html 五步
|
||
|
||
### 4.4 Phase 2 Remediation
|
||
|
||
文档：[`phase-2-audit-remediation.md`](phase-2-audit-remediation.md)
|
||
外网勾选：[`production-verification-checklist.md`](production-verification-checklist.md)
|
||
|
||
---
|
||
|
||
## L5 — 首次部署 / 生产验收（上线闸门）
|
||
|
||
**完整清单**：[`production-verification-checklist.md`](production-verification-checklist.md)
|
||
|
||
摘要：
|
||
|
||
| 章节 | 内容 |
|
||
|------|------|
|
||
| 0 | vendor、Supervisor、Nginx `/ws/` 日志 |
|
||
| 1 | JWT 登录/刷新/改密失效 |
|
||
| 2 | 静态资源自托管、TOTP、WebSSH |
|
||
| 3 | 告警 Telegram 行为 |
|
||
| 4 | Agent 401、阈值、kill 404 |
|
||
| 5 | WebSSH token 绑定 |
|
||
| 6 | 危险命令 400、长任务轮询 |
|
||
| 7 | `/health`、Supervisor、cron 健康检查 |
|
||
|
||
**签署**：清单末尾运维/开发签字后视为上线验收通过。
|
||
|
||
---
|
||
|
||
## L6 — 功能完成 vs 上线完成
|
||
|
||
| 声明 | 最低要求 |
|
||
|------|----------|
|
||
| 「PR/分支功能完成」 | L0 + L2（含 pytest + 相关手测）+ changelog |
|
||
| 「安全模块完成」 | 上述 + L3 走读 DoD |
|
||
| 「可首次部署」 | 上述 + L4 专项 + L5 全勾选 |
|
||
| 「生产就绪」 | L5 签署 + 外网 2000 台抽样（运维定义） |
|
||
|
||
---
|
||
|
||
## 7. 验收失败时
|
||
|
||
1. **不得**口头宣称通过；贴失败命令输出。
|
||
2. 按 `systematic-debugging` 查根因，修完重跑 L2 命令。
|
||
3. 无法完美实现 → 停下与用户确认（perfect-implementation 唯一例外路径）。
|
||
|
||
---
|
||
|
||
## 8. 给下一任 AI 的检查顺序
|
||
|
||
```
|
||
1. 读 AI-HANDOFF + nexus-full-site-features（做什么）
|
||
2. 读 standards-transfer-package.md（全部标准转接 + 逐行同等严谨）
|
||
3. 读本文（L0～L5 怎样算做完）
|
||
4. 内化 standards/ 三件套 + 全部 .cursor/rules/*.mdc
|
||
5. 接任务前确认 L1 / L2 / L3（审计）/ L4 / L5
|
||
6. 完成前跑 L2 命令并贴结果；审计任务满足 L3 DoD
|
||
7. 宣称「上线」前对照 L5 逐项勾选
|
||
```
|