# 整改任务规格与验收约定

## 一、需求确认和完整范围

以《Scert整改合并优化清单.md》为原始需求，保留 P0 的 12 项、P1 的 12 项、P2 的 10 项和 P3 的 10 项，共 44 项，不因已有实现或测试容易程度缩减范围。用户已要求按此清单执行；本规格将要求转成可执行检查，不额外认定尚未确认的数据库版本和新功能设计已经获准。

正式产品是 Web 与 Windows/Linux 服务端，桌面版范围外。P3 不阻断第一阶段交付，但仍属于完整整改目标。原文“建议”的实体名、目录名、角色名和阈值不等于已经实现；采用不同实现时必须说明如何满足同一能力，不能用用户分组替代项目隔离。

任务索引和实际进展以《Scert整改任务执行清单.md》为准，逐项规格拆分如下：

- 《基础整改任务规格.md》：P0-01 至 P0-12。
- 《核心能力任务规格.md》：P1-01 至 P1-12。
- 《运维验收任务规格.md》：P2-01 至 P2-10。
- 《增强能力任务规格.md》：P3-01 至 P3-10。

每项记录编号、名称、优先级、当前状态、六阶段状态、问题、涉及文件、依赖、整改内容、验证命令、实机步骤、验收证据和复审结果。状态变更必须同步汇总表、规格和证据；历史记录不覆盖、不伪造。

## 二、六阶段与状态

六阶段固定为需求确认、代码实现、自动化测试、隔离环境测试、生产部署测试、最终验收。各阶段独立使用 `[ ]`、`[~]`、`[x]`、`[✓]`、`[!]`。

- 需求已列明可标 `[x]`，但不代表代码完成。
- 已有测试不能自动证明新规格全部覆盖；在覆盖审查前仍标 `[~]` 或 `[ ]`。
- 文档治理项的“代码实现”指文档与规则交付；生产部署阶段可标“未独立执行，关联生产门禁”，不能伪造实机步骤已通过。
- `[!]` 表示某阶段暂缺前提，不表示整项目无法推进。
- 自动化或构建层通过最多支持对应范围 `[x]`；最终 `[✓]` 必须附复审人、日期、源码提交和匹配范围的实机证据。

## 三、验证命令约定

下列是可执行的基础命令，不代表单条命令已经覆盖整项需求。各规格引用命令编号并列出需补的用例；目录未实现的功能，必须先编写正式测试，再执行基础命令。生产网络和真实数据库集成测试需要独立环境参数，缺参导致跳过不算通过。

| 编号 | 工作目录 | 命令 | 用途 |
|---|---|---|---|
| V01 | 仓库根目录 | `git status --short --untracked-files=all`；`git diff --check`；`git ls-files` | 工作区与索引边界 |
| V02 | `backend/` | `go test -p 1 -count=1 -timeout=3m ./...`；`go vet -p=1 ./...`；`go mod verify` | 全量基础回归 |
| V03 | `frontend/` | `npm.cmd ci --no-audit --no-fund`；`npm.cmd test`；`npm.cmd run build` | 锁文件安装、前端回归与生产构建 |
| V04 | 仓库根目录 | `powershell -NoProfile -ExecutionPolicy Bypass -File .\build\build-release.ps1 -OutputDirectory .\release\<新的唯一候选目录>` | 双平台构建；执行时替换尖括号占位值，不覆盖现有包 |
| V05 | `backend/` | `go test -count=1 ./internal/releasearchive ./internal/cli` | 发布边界和运维入口 |
| V06 | `backend/` | `go test -count=1 ./internal/database ./internal/repository ./internal/cli` | 数据库、归属及备份恢复基础测试 |
| V07 | `backend/` | `go test -count=1 ./internal/auth ./internal/admin ./internal/httpapi` | 认证、权限及接口 |
| V08 | `backend/` | `go test -count=1 ./internal/secretstore ./internal/sshkey ./internal/config ./internal/localreset` | 凭据、密钥和本机恢复 |
| V09 | `backend/` | `go test -count=1 ./internal/deployment ./internal/sshkey` | SSH、部署、回滚 |
| V10 | `backend/` | `go test -count=1 ./internal/certificate ./internal/dnsprovider ./internal/dnsverification` | ACME、DNS、续期 |
| V11 | `backend/` | `go test -count=1 ./internal/notification ./internal/logging ./internal/httpapi` | 通知、日志和接口 |
| V12 | `backend/` | `go test -count=1 ./internal/servicehost ./internal/bootstrap ./internal/setup ./internal/certstorage ./internal/nginxactivation` | 服务和初始化；平台专用用例须在对应系统重跑 |

任务规格结构核对：逐项比对原始清单的编号和名称、依赖编号、涉及文件是否存在或明确标“拟新增”、12 个必需字段与六阶段状态是否齐全。结构核对不是业务测试，也不需要新增辅助脚本。

## 四、统一实机前置条件

1. 修改前核对工作区并推送中文检查点。测试前从明确源码提交构建最新候选包，核对 SHA256、平台和版本。
2. 首次流程使用明确的可清理测试数据库；涉及多个数据库时逐个建立隔离实例或专用库，再按授权清理测试数据。不把测试清理要求推广为删除共享主机的其他库、服务或业务记录。
3. 桌面 Web 测试前检查后端、前端和专用浏览器 MCP 的状态、端口与所属项目；清理该测试上下文缓存并重开页面。移动端按用户要求使用 Mobile Preview 插件，不改用桌面 MCP 冒充移动验收。
4. 服务器信息与凭据仅用于连接。连接须校验用户确认的 SSH 指纹，公网访问使用正常 DNS 和完整 TLS/SNI 校验。禁止关闭 TLS、跳过指纹或用强制 IP TLS 作为正式证据。
5. 涉及 DNS、邮件、ACME、远程文件、服务启停和恢复时，先确认目标归属和影响范围；仅清理本轮创建的测试记录。真实秘密不进日志、截图、文档、Git 或测试产物。
6. 使用产品的 Web/服务端/正式运维入口及已有测试，不新增临时辅助脚本替代验收。已有 Go、前端和安装器正式测试继续保留。

## 五、验收证据格式

每项证据必须能定位：任务编号与用例、源码提交、候选包 SHA256、目标平台和数据库版本、脱敏环境标识、操作入口、起止时间、退出码、断言、结果、清理结果及覆盖缺口。自动化、隔离、真实生产链路和复审分别记录。

本地证据放 `artifacts/`；可提交的脱敏结论放 `doc/`。历史结果必须注明当时提交，不把旧输出当作当前版本已测试。没有凭据本身、测试服务器 IP 或域名之外的过程证据时，视为未验收。

完整发布仍需 P0-11 的 12 层门禁，不能以本规格文档齐全、HTTP 200、构建成功或测试数量替代。