# 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 逐项勾选
```