交付文档指南
本页用途
本页规定项目开发完成后，怎样为客户、最终用户和其他岗位选择、编写、验证及维护交付文档。交付文档面向实际使用产品的人，不替代开发工作流、架构说明和任务归档。
最小原则：先确认交付对象，只创建对方完成工作确实需要的文档，不预建空白手册。
什么时候需要交付文档
出现以下任一情况时，应在单元任务工单中评估并更新交付文档：
- 新增或改变用户可见功能、操作步骤、界面、权限或限制；
- 改变安装、配置、部署、备份、恢复、监控或升级方法；
- 改变外部 API、数据格式、集成条件或兼容范围；
- 改变常见故障的识别、处理或支持方式；
- 发布新版本或交付客户验收。
纯内部重构只有在外部行为、操作方式、配置和支持边界均未改变时，才可选择“无交付文档影响”并说明原因。
受众与文档选择
| 交付对象 | 典型文档 | 需要回答的问题 |
|---|---|---|
| 最终用户 | 用户使用说明 | 怎样完成日常操作，失败后怎么办 |
| 管理员 | 管理员指南 | 怎样配置用户、权限和系统参数 |
| 运维人员 | 部署与运维指南 | 怎样安装、启停、监控、备份和恢复 |
| 客服或一线支持 | 支持与排错指南 | 怎样识别问题、收集信息和升级处理 |
| 集成人员 | 接口与集成指南 | 怎样认证、调用接口和处理兼容性 |
| 验收或项目负责人 | 发布、升级与验收说明 | 本次交付了什么，怎样验证和回退 |
一个项目只选择实际存在的交付对象。多个岗位需要相同内容时可共享一份文档，但必须明确各自可以执行的操作和权限边界。
内部文档与交付文档边界
交付文档可以包含用户完成工作所需的产品地址、公开接口、配置项、操作步骤、结果、限制和支持渠道。
面向客户或公开的文档不得包含：
- 内部工单链接、聊天记录、内部决策过程或任务归档；
- 内部网络地址、仓库路径、无必要的源码模块名和调试细节；
- 密码、令牌、Cookie、私钥、个人数据或生产数据；
- 未经确认的安全实现、漏洞细节或仅供内部使用的恢复手段；
- 未承诺的路线图、期限和功能。
交付前必须检查模板中的“可见范围”。同一主题同时存在内部版和客户版时，应分别维护并明确名称，不能依靠读者自行忽略内部内容。
编写和维护流程
- 在项目初始化或需求确认时识别交付对象、可见范围和所需文档。
- 使用岗位文档模板按需创建文档，不创建没有明确读者的空页面。
- 单元任务在工单“交付文档影响”中选择无影响并说明原因，或列出需要更新的页面和受众。
- 功能、配置或流程改变时，代码与对应交付文档在同一任务中更新。
- 由熟悉该岗位但未参与实现的人按文档执行关键步骤；不能验证的环境和步骤必须明确标注。
- 发布或交付前确认适用版本、最后验证日期、负责人、已知限制和支持渠道。
- 长期维护仍遵循 Wiki-first：先修改 Wiki、读取确认，再导出本地
docs/镜像。
具体项目创建的岗位文档应增加到 wiki-docs.json 的显式映射中。本模板自身的指南和模板镜像位于 docs/delivery/。
最小验收清单
- 文档有明确受众、适用版本、可见范围和负责人。
- 前置条件、操作步骤和预期结果完整且可以对应。
- 常见失败、恢复方法、安全提示和已知限制已说明。
- 关键步骤由目标岗位视角验证，或明确记录未验证项。
- 外部版本不含内部链接、敏感数据和无关实现细节。
- 本次功能变化涉及的交付文档已更新并与版本一致。
- Wiki 已读取确认，本地镜像检查一致。
不在本页解决的内容
开发任务怎样建单、实施和归档见开发工作流；代码结构和维护入口见架构与代码地图。本页不规定市场宣传、合同、法务或商务承诺。
Sense MVP 岗位操作路径
Sense 面向网管、实施人员和非技术现场人员，菜单按日常任务组织：工作台 → 设备管理 → 视频接入 → 视频服务 → 实时监看 → 区域与警戒线。普通操作优先展示中文状态与下一步，不要求用户理解 ONVIF、RTSP 或 MediaMTX 内部模型。
- 系统管理员：使用仓库外、至少 32 个字符的一次性初始化令牌创建首位管理员；系统已有用户后不得再次初始化。随后维护 Sense 用户、角色并查看登录和操作记录。仓库没有默认账号或默认密码。
- 实施/运维：查看实施所需日志和字典支撑信息；设备接入、凭据更新、码流检查与媒体服务处置能力由后续业务工单逐步启用。
- 站点管理员：维护普通账户并读取角色、部门、岗位和字典选项，但不能修改角色、菜单或系统配置；设备、实时监看和区域能力由后续业务工单逐步启用。
- 只读用户：当前不能进入账户、权限或系统管理接口；后续只获得设备、媒体状态、实时画面和区域的查看权限。
所有 Sense 密码至少 6 个字符、最多 72 字节，可使用全小写，不强制字符组合；管理员仍应选择难猜、不复用的密码。登录成功/失败、登出、密码变更和权限拒绝会进入身份审计，交付检查必须确认审计不含密码、令牌、Cookie、验证码或摄像头凭据。
交付验收必须使用仓库外测试账户和获准实验室设备；文档、截图、工单和日志不得包含摄像机密码、Cookie、令牌、含凭据 URI 或客户真实画面。当前身份自动化已覆盖四角色权限矩阵和安全边界；真实生产 PostgreSQL、反向代理、目标浏览器和后续设备链路仍需实施人员按相应工单验证。
Sense Windows 运行包交付
交付对象为实施和运维人员。以 sense-windows-amd64.zip 交付后端程序、已构建前端、空值示例配置、迁移基线、许可证、启动/检查/停止/备份/恢复脚本与包内说明；不包含 PostgreSQL、生产数据、默认管理员、默认密码或客户秘密。可按交付决定是否包含已审核的 bin\mediamtx.exe。
- production 先复制
config\sense.env.example为config\sense.env，填写 PostgreSQL、至少 32 字符 JWT secret、凭据密钥、获准 ONVIF 网络和 MediaMTX 模式。进程环境中的同名非空值优先，脚本不执行 env 文件内容，也不打印秘密。 - 先运行
check-sense.bat，再运行start-sense.bat。启动会先迁移，失败时不会开放 HTTP；managedMediaMTX 在 Sense HTTP 前启动，external必须已有可达的回环 Control API，production 禁止disabled。 - 首位管理员通过至少 32 字符的一次性 bootstrap token 和
initialize-admin.bat -Username admin创建，密码由隐藏提示输入；成功后立即清空 token 并重启。仓库与交付包均无默认账号密码。 - 临时演示必须显式运行
start-sense.bat demo，使用独立config\sense.demo.env和名称含 demo/test 的数据库；不会回退 production 数据库，也不能作为生产部署。 - 日常停止优先在启动窗口按 Ctrl+C；窗口丢失或进程无响应时使用
stop-sense.bat。脚本会验证端口与可执行文件归属，拒绝停止其他程序。 - 备份使用
backup-sense.bat生成 PostgreSQL custom-format 文件。恢复前停止服务并再次备份，执行restore-sense.bat时需确认目标数据库名及RESTORE-数据库名，随后重新迁移。 - 交付时保存 ZIP 和
MANIFEST.sha256的 SHA-256，至少验证首页、/healthz、数据库迁移、MediaMTX API、启动/停止和备份/恢复。真实摄像机、目标浏览器与客户数据库账号仍在授权现场验证。 - 包内
README-WINDOWS.md是现场事实入口；真实config\sense.env、运行生成的data\runtime\settings.yml、日志和备份不得提交 Git 或重新打入 ZIP。
Sense 设备台账交付说明
设备管理已开放列表、新建、编辑、停用和摄像头凭据更新。系统管理员、实施/运维和站点管理员可以维护；只读用户只能查看。现场人员应使用中文设备名称和安装位置，类型选择“视频”时才可配置 ONVIF/RTSP 凭据；其他类型会明确提示适配器尚未就绪。
凭据窗口每次均为空，不会回显已保存用户名或密码；“已配置”标签只表示服务器保存了密文。部署人员必须在仓库外为服务进程配置 Base64 编码的随机 32 字节 SENSE_CREDENTIAL_KEY，丢失或更换该密钥会使旧凭据不可用，因此应纳入受控秘密备份。停用设备不会物理删除台账。
Sense 视频接入交付说明
部署人员必须先确认获准摄像头网段，再把本机对应网卡 IP 配置为 SENSE_ONVIF_DISCOVERY_IP，把获准网段配置为逗号分隔的 SENSE_ONVIF_ALLOWED_CIDRS。不得为了省事填写全网段。现场人员在“视频接入”选择已登记且已配置凭据的视频设备，可使用发现结果或手工填写不含账号密码的 ONVIF 地址。
验证结果区分可用、部分码流失败、认证失败、目标未获准、重定向拒绝、响应超时、设备时间异常和无法连接，并显示主/子码流及逐 Profile 状态。失败重试不会删除上次已验证 Profile；修改凭据后应重新验证。真实摄像机兼容性、网络 ACL 和设备校时仍需在客户授权环境完成。
Sense 视频服务交付说明
“视频服务”面向实施、运维和站点管理员展示 MediaMTX 进程归属、媒体路径、拉流状态、观看数、失败原因和下次重试。只读用户只能查看；有操作权限的人员可立即对账或停止单一路径。
交付时 MediaMTX 二进制和真实配置放在仓库外受控目录，Control API 只能绑定回环地址。Sense 关闭时只停止自己启动的 MediaMTX；外部启动进程会显示“外部启动（受保护）”。“等待拉流”表示按需路径尚无观看者，不等同于故障。停止路径不会删除设备或 Profile，后续重新接入可恢复期望态。
任何客户文档、截图和日志都不得包含 Control API 请求体、摄像头凭据或带凭据 URI。现场至少验证启动失败、端口冲突、外部进程保护、重复对账、冷启动恢复和 reader 状态。
部署与运维文档
YoVision 已有 Sense Windows 交付包和本机 Supervisor 常驻实例，因此维护 Deployment-and-Operations 页面。部署命令、服务身份、配置来源、端口、日志、启动停止、回退或升级方式变化时必须先更新该 Wiki 页面，再同步本地镜像。