开发测试计划

这是什么

这是一份把手册站建设、截图采集、发布接入、验收门禁统一起来的执行计划。它不是实现细节说明，而是业务、产品、开发、测试、发布都能按它推进的作业单。

目标

做出公开可访问的 booking-manual.xspet.net
未登录可看
文字、流程图、截图三者严格一致
业务人员能够照着做
我方只通过截图和构建结果验收，不依赖真机实测
满足 SSOT / SDD / TDD 三层约束

成功标准

这版只有在下面条件同时满足时才算完成：

手册站能打开
每章都能按业务顺序读懂
每张截图都能在正文里找到对应位置
桌面端和移动端都没有明显错位、溢出、重叠
站点发布后 HTTPS 正常，未登录可访问
所有关键限制都有图、有文、有测试示例

站点首页

首页要先告诉人“这是什么”，再告诉人“从哪开始看”。

范围

本轮要做

手册首页
手册目录页
登录与账号
医生管理
排班号源
预约创建
今日队列
客户档案与宠物档案
历史预约
状态与术语
常见问题
测试示例场景
开发测试计划本章
独立静态站发布
登录页外链入口
HTTPS 自动续期

本轮不做

不做新的业务功能
不改现有预约逻辑
不改客户端/医院端页面
不做额外报表
不做登录后的交互改造

SSOT

唯一业务事实来源：

docs/SSOT.md

规则：

页面、文案、状态和 SSOT 冲突时，先改手册。
手册和截图冲突时，以截图验收结果为准，再回头修正文案。
所有术语必须只出现一套中文口径，不允许同一页面多种叫法。

SDD

信息架构

业务主线按依赖顺序组织：

医生管理
排班号源
预约创建
今日队列
客户档案与宠物档案
历史预约

页面规则

首页优先给入口，不堆术语
每章优先回答“怎么做”
复杂规则用流程图
章节固定使用同一模板
截图必须与正文句子一一对应

产品哲学

先让读者完成任务，再解释规则。
复杂限制优先用流程图，不用长段文字硬解释。
能用截图说明的，不用抽象描述。
同一类信息在医院端、客户端、手册里的表达要统一。

站点结构

业务顺序按医生、排班、预约、队列、档案、历史往下读，不按菜单堆。

角色口径

医院前台：看医生、排班、预约、队列
运营：看账号、档案、历史、FAQ
客户：看登录、预约、档案、历史
超级管理员：只负责账号开通和停用，不额外扩展权限体系

TDD

内容测试

验证每章是否具备：

定义
角色
入口
操作步骤
结果说明
异常说明
流程图
截图
测试示例

文档测试

验证每章是否满足：

标题顺序正确
章节顺序正确
文字和截图对得上
流程图和正文一致
术语表和正文一致

构建测试

必须通过：

npm run manual-site:build
npm run deploy-config-check
npm run ci-local

视觉测试

必须检查：

桌面端不溢出
手机端不重叠
章节内链可跳转
Mermaid 图可渲染
图片路径可打开

验收原则

只接受截图验收，不接受口头确认。

截图策略

正常态

登录页
医生列表
排班总览
正常预约
今日队列
档案查看态
历史预约

特殊态

手术日
停号
满号
停用医生
过去日期不可选
变更医生
无改动不可保存

环境分工

beta：正常主流程图
beta2：特殊状态图

实施步骤

第 1 步：定稿章节结构

确认首页、目录、章节顺序和图文模板。

验收：

首页能直接找到所有章节
章节顺序与业务依赖一致

第 2 步：补齐正文

把每章写到可执行状态，避免只有概念没有步骤。

验收：

每章至少能独立完成一次业务动作
所有限制都能在章节里找到解释

第 3 步：准备截图清单

按 ASSET-MANIFEST.md 逐项采集。

验收：

每张图都有文件名
每张图都有正文引用位置
每张图都能对应一个明确业务场景

第 4 步：生成静态站

把 Markdown 转成 HTML，连同图片一起发布。

验收：

output/manual-site 可生成
页面可本地打开
目录和内链正常

第 5 步：接入发布链路

把 booking-manual.xspet.net 纳入 nginx、证书和部署脚本。

验收：

HTTP 自动跳 HTTPS
证书自动续期
静态目录独立

第 6 步：做截图验收

我只通过截图判断是否通过，不依赖你现场操作。

验收：

图文一致
无错位
无溢出
无误导性文案
正常态、特殊态、边缘态都覆盖到了
桌面和手机端都没有布局破坏

验收示例

左边看章节目录，中间看正文步骤，右边看关键证据图，三者必须一致。

标准发版流程

本地开发
本地构建
本地门禁
截图验证
合并 main
120 服务器部署
HTTPS 验证
域名可访问验证
最终截图验收

Git

所有修改必须在仓库内
发布只从 main
不允许线上改代码
不允许绕过构建门禁

CI 门禁

最少门禁：

语法检查
类型检查
单元测试
SSOT 检查
配置检查
手册站构建
整仓构建

DevOps

发布要求

手册站必须是独立静态目录
booking-manual.xspet.net 必须单独配置 HTTPS
证书必须自动续期
登录页必须有未登录可见的外链入口
发布后必须能直接打开首页和章节页

验收证据

构建日志
浏览器截图
链接检查结果
页面渲染结果

结论

这份计划的判断标准很简单：

能不能照着写
能不能照着做
能不能只靠截图验收
能不能在 beta2 -> beta -> 手册站 三条线里闭环

120 服务器托管静态站
独立 nginx server_name
独立 HTTPS
certbot 自动续期
静态目录与 beta 文档站分离

验收标准

以下全部满足才算通过：

booking-manual.xspet.net 可访问
未登录可访问
首页和目录可用
11 个章节可用
图片可打开
Mermaid 可渲染
桌面和手机端不乱版
构建和门禁通过
截图与正文严格一致
业务人员可按文档完成主要流程

最终交付物

docs/manual/ 全量正文
docs/manual/assets/ 截图资源
output/manual-site/ 静态站产物
ops/build-manual-site.mjs 构建脚本
ops/nginx-manual-http.conf.template
ops/nginx-manual-https.conf.template
docs/manual/PUBLISHING.md
docs/manual/DEPLOYMENT.md