admin/Nexus
1
0
Fork 0
Code Issues Pull Requests Actions 91 Packages Projects Releases Wiki Activity
Files
d93c518a1464579a7d2508b76dfd91a827cc26e0
Nexus/docs/project/development-acceptance-standard.md
T

236 lines
8.9 KiB
Markdown
Raw Normal View History

fix: 六轮深度扫描 — 47项Bug修复、安全加固、死代码清理
2026-05-24 16:26:40 +08:00
# Nexus 6.0 — 开发验收标准（SSOT）
> **更新**: 2026-05-23
> **读者**: 开发 AI、测试、运维
> **地位**: 宣称「功能完成 / 可合并 / 可上线」前**必须**对照本文；与功能清单、接续文档并列。
**相关文档**
| 文档 | 路径 |
|------|------|
| 全站功能 | [`nexus-full-site-features.md`](nexus-full-site-features.md) |
| AI 接续 | [`AI-HANDOFF-2026-05-23.md`](AI-HANDOFF-2026-05-23.md) |
| **标准转接包（全量）** | [`standards-transfer-package.md`](standards-transfer-package.md) |
| 功能说明书 HTML | [`../Nexus-功能说明书.html`](../Nexus-功能说明书.html) |
---
## 0. 验收层级总览
```
L0 原则与纪律 perfect-implementation + 架构规则（始终遵守）
L1 设计验收 设计文档 / 技术文档中的「验收标准」章节
L2 代码完成 单测 + WSL smoke +（改 API/前端时）对应模块手测
L3 安全审计 逐行走读 DoD（改安全路径或大 diff 时）
L4 模块 E2E 脚本 T-SE、告警策略、推送 dry-run 等专项清单
L5 首次部署 production-verification-checklist（上线前）
```
**禁止**：未跑 L2 对应命令就声称「已修复 / 已完成」；未满足 L0 就合并。
---
## 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 |
| WSL 全链路代码向 | `bash scripts/wsl_ensure_venv.sh`（首次） | 无 error |
| | `bash scripts/wsl_start_dev.sh` | 服务启动 |
| | `bash scripts/wsl_integration_smoke.sh` | security + `/health` + `/api/servers/` 401 |
| 有 API 契约变更 | `pytest tests/test_api.py`（需 `.env` + 测试账号） | 按项目约定 |
详见：[`wsl-integration-test.md`](wsl-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 |
chore: 移除 superpowers 工作流 Skill，改为单 Agent 协作
2026-06-01 14:04:50 +08:00
### 2.3 完成前自检（Agent 直接执行，无 Skill 包）
fix: 六轮深度扫描 — 47项Bug修复、安全加固、死代码清理
2026-05-24 16:26:40 +08:00
chore: 移除 superpowers 工作流 Skill，改为单 Agent 协作
2026-06-01 14:04:50 +08:00
| 动作 | 依据 | 何时 |
|------|------|------|
| 跑验证命令后再宣称完成 | `standards/` + `.cursor/rules/perfect-implementation.mdc` | 每次交付前 |
| 先失败测试再实现 | 项目 `tests/`、设计文档验收标准 | 新功能/修 bug |
| 根因分析再改代码 | `.cursor/rules/audit-line-review.mdc`（若涉安全路径） | 异常/回归 |
fix: 六轮深度扫描 — 47项Bug修复、安全加固、死代码清理
2026-05-24 16:26:40 +08:00
---
## 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 逐项勾选
```
Reference in New Issue Copy Permalink