docs: 原型改为线上审核和按需导出 (#27)

ila
2026-08-26 15:59:57 +08:00
parent e9e0ebafd9
commit 4e30058e24
+22 -11
@@ -59,25 +59,33 @@ Gitea 暂时不可用时可以准备工单和 Wiki 草稿,但不得把本地
采用最低成本、足以让用户确认的证据,不为了形式制作高保真原型。草稿原型可以用于需求讨论;草稿需要写入 Git/Wiki、多人协作或单独实施时,应建立设计任务。草稿原型和临时技术验证都不能直接作为生产实现。
### 本地 HTML 审核快照
### 线上原型审核与按需导出
新页面、独立用户功能、重大交互或导航变化使用 Quant-UX 或等效工具形成待审核版本后,必须在用户审核前生成本地可浏览 HTML 快照:
新页面、独立用户功能、重大交互或导航变化使用 Quant-UX 或等效工具形成待审核版本后,默认直接通过线上原型审核,不要求每次导出本地 HTML:
- 可编辑设计源仍保存在 Quant-UX 或原设计工具;Git 中的 HTML 只是与需求和代码版本绑定的审核证据,Wiki 和工单只保存索引与确认记录。
- 快照放入 `prototypes/<工单号>/<版本>/index.html`;图片、样式、脚本和字体使用该版本目录内的相对路径。需要网络资源才能显示时,不得标记为可离线浏览。
- 用户通过 `index.html` 审核;浏览器限制直接打开时,在工单记录最小本地静态服务命令和访问地址,不新增项目专用服务脚本。
- 提交或请求审核前检查入口可打开、主要页面和交互可访问、图片和字体不缺失,并删除令牌、账号、个人信息和生产数据。
- 页面结构、主要流程、状态、权限、异常处理或验收结果发生变化时,在新版本目录重新导出并重新确认;不得覆盖已经确认的版本。
- 纯显示文案、小范围现有 UI 调整、非 UI 需求和恢复既有行为的 Bug 不强制生成 HTML;仍使用双门禁表规定的最低证据。
- 设计工具无法生成可用 HTML 时必须在工单说明限制并停止审核,由用户确认等效的本地可浏览原型方案;不得只保留难以访问的线上链接后直接编码。
- 可编辑设计源保存在 Quant-UX 或原设计工具;工单和 Wiki 只保存链接、版本与确认记录,不复制为第二份可编辑事实来源。
- 线上链接必须能被确认人访问,并能通过版本、revision、复制版本或确认日期识别本次审核对象;无法访问或无法区分版本时停止审核,等待用户确认等效方案。
- 提交审核前检查主要页面、流程、状态和交互可访问,并删除令牌、真实账号、个人信息和生产数据。
- 页面结构、主要流程、状态、权限、异常处理或验收结果变化时,更新线上原型并重新确认;不得用旧确认覆盖新版本。
- 纯显示文案、小范围现有 UI 调整、非 UI 需求和恢复既有行为的 Bug 仍只使用双门禁表规定的最低证据,不强制建立完整线上原型。
只有用户明确发出 `导出原型 #N`、`导出全部原型`,或项目专用规则明确要求离线交付时,才导出本地 HTML:
- 指定工单的快照放入 `prototypes/<工单号>/<版本>/index.html`;全部导出时也按工单和版本分目录,先在工单明确导出范围。
- 图片、样式、脚本和字体使用版本目录内的相对路径;需要网络资源才能显示时不得标记为可离线浏览。
- 已确认的本地快照不得原位覆盖;新版本使用新目录,已有快照继续作为历史审核证据。
- 导出后检查入口、主要交互和资源完整性;浏览器限制直接打开时,在工单记录最小本地静态服务命令和访问地址,不新增项目专用服务脚本。
- 导出指令只生成或更新请求范围内的快照并报告结果,不自动提交;用户未明确要求时不得顺带导出其他原型。
- 设计工具无法生成用户要求的可用 HTML 时,在工单记录限制并停止该导出或离线交付,等待用户确认等效方案;线上原型仍可访问且版本明确时,不因此阻塞线上审核。
### 记录和重新确认
需要设计证据的工单必须记录:
- 原型或设计的链接、Git 路径或对应事实来源;
- 版本、revision 或确认日期;
- 原型或设计的线上链接、对应事实来源,以及链接可访问性;
- 版本、revision、复制版本或确认日期,以及审核版本的识别方式;
- 状态:无、草稿、已确认或已废弃;
- 只有显式导出时才记录本地 HTML 路径、版本和资源检查结果;
- 确认人和确认时间;
- 本次确认覆盖的页面、组件、流程和边界;
- 不需要 UI 原型时采用的技术设计,或无需任何原型的原因。
@@ -290,6 +298,8 @@ python dev_scripts/harness.py export --all # 全量导出已有归档
| `继续工单 #N` | 核对工单、Git 和 Wiki 证据,从首个未完成步骤继续,不重复仍然有效的检查 | 到达该工单当前流程的停止条件 |
| `检查工单 #N` | 只读对照范围、验收标准、测试和证据,报告通过项、缺失项及未验证部分 | 输出检查报告;不自动修复 |
| `同步文档` | 读取 Wiki,导出核心长期文档镜像并检查一致性,不处理任务归档 | 显示结果和差异;不修改 Wiki、不自动提交 |
| `导出原型 #N` | 人工触发导出指定工单已确认的原型版本;按工单和版本写入 `prototypes/` | 显示路径和检查结果;不扩展范围、不自动提交 |
| `导出全部原型` | 人工触发导出当前项目明确范围内的全部已确认原型 | 显示导出范围和结果;不自动提交 |
| `导出任务归档` | 人工触发增量导出,只写入新增或 revision 已变化的任务归档 | 显示导出或跳过结果;不删除本地文件、不自动提交 |
| `导出全部任务归档` | 人工触发全量读取并导出线上全部任务归档 | 显示导出结果;不删除本地文件、不自动提交 |
| `#N 验收通过` | 在工单追加验收结论,按需更新真实变化的长期 Wiki,推送、同步父工单并关闭任务;不创建或导出任务归档 | 工单“已完成”并关闭 |
@@ -300,6 +310,7 @@ python dev_scripts/harness.py export --all # 全量导出已有归档
- 前置依赖未满足且不允许并行时,实施类指令停在“待实施”。
- `#N 验收通过` 必须来自用户明确表达;其他快捷指令不得关闭待验收工单。
- `同步文档` 或任务归档导出发现目标镜像有未提交改动时停止,不覆盖现有修改。
- `导出原型 #N` 和 `导出全部原型` 必须由用户明确提出或项目专用规则明确要求;其他指令不隐式导出原型。
- `导出任务归档` 和 `导出全部任务归档` 必须由用户明确提出,其他快捷指令不隐式执行。
- Gitea 工单是单次任务唯一事实来源,不导出全文;`docs/task/` 只保存人工明确要求的专项或历史兼容快照。