admin/Nexus
1
0
Fork 0
Code Issues Pull Requests Actions 82 Packages Projects Releases Wiki Activity
Files
1933f0af6e647818e716ed194cdb92d7ed7bb47a
Nexus/docs/project/development-acceptance-standard.md
T
Codex Release Bot 1933f0af6e release: nexus btpanel session fix and app-v2
2026-07-08 22:31:31 +08:00

9.3 KiB
Raw Blame History

Nexus 6.0 — 开发验收标准（SSOT）

更新: 2026-06-04
读者: 开发 AI、测试、运维
地位: 宣称「功能完成 / 可合并 / 可上线」前必须对照本文。

相关文档

文档 路径
功能 SSOT nexus-functional-development-guide.md
AI 接续 AI-HANDOFF-2026-06-03.md
文档总索引 ../README.md
标准转接包 standards-transfer-package.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

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 §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 §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

  • 超阈值 → 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
外网勾选：production-verification-checklist.md

L5 — 首次部署 / 生产验收（上线闸门）

完整清单：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 View Git Blame Copy Permalink