yovision/docs/delivery/README.md

generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Delivery-Documentation-Guide wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Delivery-Documentation-Guide.- wiki_revision: d4f2bfcef46493361ba019839b36957ed9947003 synchronized_at: 2026-08-14T01:18:58Z

交付文档指南

本页用途

本页规定项目开发完成后，怎样为客户、最终用户和其他岗位选择、编写、验证及维护交付文档。交付文档面向实际使用产品的人，不替代开发工作流、架构说明和任务归档。

最小原则：先确认交付对象，只创建对方完成工作确实需要的文档，不预建空白手册。

什么时候需要交付文档

出现以下任一情况时，应在单元任务工单中评估并更新交付文档：

• 新增或改变用户可见功能、操作步骤、界面、权限或限制；
• 改变安装、配置、部署、备份、恢复、监控或升级方法；
• 改变外部 API、数据格式、集成条件或兼容范围；
• 改变常见故障的识别、处理或支持方式；
• 发布新版本或交付客户验收。

纯内部重构只有在外部行为、操作方式、配置和支持边界均未改变时，才可选择“无交付文档影响”并说明原因。

受众与文档选择

交付对象	典型文档	需要回答的问题
最终用户	用户使用说明	怎样完成日常操作，失败后怎么办
管理员	管理员指南	怎样配置用户、权限和系统参数
运维人员	部署与运维指南	怎样安装、启停、监控、备份和恢复
客服或一线支持	支持与排错指南	怎样识别问题、收集信息和升级处理
集成人员	接口与集成指南	怎样认证、调用接口和处理兼容性
验收或项目负责人	发布、升级与验收说明	本次交付了什么，怎样验证和回退

一个项目只选择实际存在的交付对象。多个岗位需要相同内容时可共享一份文档，但必须明确各自可以执行的操作和权限边界。

内部文档与交付文档边界

交付文档可以包含用户完成工作所需的产品地址、公开接口、配置项、操作步骤、结果、限制和支持渠道。

面向客户或公开的文档不得包含：

• 内部工单链接、聊天记录、内部决策过程或任务归档；
• 内部网络地址、仓库路径、无必要的源码模块名和调试细节；
• 密码、令牌、Cookie、私钥、个人数据或生产数据；
• 未经确认的安全实现、漏洞细节或仅供内部使用的恢复手段；
• 未承诺的路线图、期限和功能。

交付前必须检查模板中的“可见范围”。同一主题同时存在内部版和客户版时，应分别维护并明确名称，不能依靠读者自行忽略内部内容。

编写和维护流程

1. 在项目初始化或需求确认时识别交付对象、可见范围和所需文档。
2. 使用岗位文档模板按需创建文档，不创建没有明确读者的空页面。
3. 单元任务在工单“交付文档影响”中选择无影响并说明原因，或列出需要更新的页面和受众。
4. 功能、配置或流程改变时，代码与对应交付文档在同一任务中更新。
5. 由熟悉该岗位但未参与实现的人按文档执行关键步骤；不能验证的环境和步骤必须明确标注。
6. 发布或交付前确认适用版本、最后验证日期、负责人、已知限制和支持渠道。
7. 长期维护仍遵循 Wiki-first：先修改 Wiki、读取确认，再导出本地 docs/ 镜像。

具体项目创建的岗位文档应增加到 wiki-docs.json 的显式映射中。本模板自身的指南和模板镜像位于 docs/delivery/。

最小验收清单

• 文档有明确受众、适用版本、可见范围和负责人。
• 前置条件、操作步骤和预期结果完整且可以对应。
• 常见失败、恢复方法、安全提示和已知限制已说明。
• 关键步骤由目标岗位视角验证，或明确记录未验证项。
• 外部版本不含内部链接、敏感数据和无关实现细节。
• 本次功能变化涉及的交付文档已更新并与版本一致。
• Wiki 已读取确认，本地镜像检查一致。

不在本页解决的内容

开发任务怎样建单、实施和归档见开发工作流；代码结构和维护入口见架构与代码地图。本页不规定市场宣传、合同、法务或商务承诺。

Sense MVP 岗位操作路径

Sense 面向网管、实施人员和非技术现场人员，菜单按日常任务组织：工作台 → 设备管理 → 视频接入 → 视频服务 → 实时监看 → 区域与警戒线。普通操作优先展示中文状态与下一步，不要求用户理解 ONVIF、RTSP 或 MediaMTX 内部模型。

• 系统管理员：完成一次性安全初始化，维护 Sense 用户与角色，查看操作记录。首次管理员和新用户密码仅要求至少 6 个字符，不限制字符种类并允许包含用户名；仍应由管理员选择难猜且不复用的密码。
• 实施/运维：添加设备、只写更新凭据、在获准网卡发现或手工接入、检查主辅码流、处理媒体进程与对账。
• 站点管理员：查看/维护站点设备，实时监看，绘制和发布区域版本；无权创建系统管理员。
• 只读用户：查看设备、媒体状态、实时画面和区域，不能修改。

交付验收必须使用仓库外测试账户和获准实验室设备；文档、截图、工单和日志不得包含摄像机密码、Cookie、令牌、含凭据 URI 或客户真实画面。当前自动化已覆盖内部状态和安全边界；真实 PostgreSQL、MediaMTX、摄像机兼容与目标浏览器画面仍需实施人员验证。

Sense Windows 运行包交付

交付对象为实施和运维人员。sense-windows-amd64.zip 包含后端程序、已构建前端、空值示例配置、上游许可证、启动脚本与包内说明；不包含 PostgreSQL、MediaMTX、Windows 服务、生产数据或秘密。

• 临时查看必须显式运行 start-sense.bat demo，其内存数据在进程结束后丢失，不能当作生产部署。
• 生产配置可由运维写入解压目录的 config\sense.env，或通过 Windows 进程环境安全注入；进程环境优先。先运行 start-sense.bat check 检查必填项，再运行 start-sense.bat。
• 交付时记录 ZIP SHA-256，并至少验证 /healthz 与首页；真实 PostgreSQL、MediaMTX、摄像机和目标浏览器仍需在获准环境验收。
• 包内 README-WINDOWS.md 是现场操作入口；真实 config\sense.env 只留在具体部署目录，不得提交 Git 或重新打入交付 ZIP，交付 ZIP 只保留 sense.env.example。