工作手机开发文档｜唯一总入口
本目录只描述 工作手机 SDK、设备 Agent、Android APK、控制通道、接口、部署与验收。不再以其他业务系统作为项目主体。
一、十章结构
| 章节 | 负责回答的问题 | 主入口 |
|---|---|---|
| 1、需求 | 为什么做、做什么、做到什么程度 | 1、需求/README.md |
| 2、架构 | 系统怎样组成、模块怎样协作 | 2、架构/README.md |
| 3、原型 | 用户如何操作、页面如何流转 | 3、原型/README.md |
| 4、前端 | 控制台与设备界面如何实现 | 4、前端/README.md |
| 5、接口 | 外部系统和设备如何调用 | 5、接口/README.md |
| 6、后端 | 服务端、Agent、任务路由如何实现 | 6、后端/README.md |
| 7、数据库 | 数据如何存储、迁移和审计 | 7、数据库/README.md |
| 8、部署 | 本地、服务器、真机如何上线 | 8、部署/README.md |
| 9、手册 | 开发、运维和使用人员如何操作 | 9、手册/README.md |
| 10、项目管理 | 进度、风险、验收、版本如何管理 | 10、项目管理/README.md |
二、开发前只读四份
三、开发完成必须补四处
- 需求状态：更新当前需求中的验收项。
- 技术说明：更新对应章节主文档，不另建重复总纲。
- 验收证据：保存命令、JSON、日志、截图或视频索引。
- 项目进度：更新开发进度总表和工作日志。
四、文档统一标准
每份主文档至少包含：
- 文档目标与适用范围
- 当前版本和最后更新时间
- 前置条件
- 结构或流程说明
- 可执行步骤或接口示例
- 成功判定标准
- 常见失败与排查
- 关联代码路径
- 关联测试或验收证据
- 变更记录
五、唯一真源规则
| 内容 | 唯一真源 |
|---|---|
| 当前需求 | 1、需求/修改/工作手机_进行中_20260613.md |
| 系统边界 | 2、架构/01-总览/系统架构.md |
| 页面与交互 | 3、原型/ 中当前版本总方案 |
| 前端规范 | 4、前端/前端开发规范.md |
| API 契约 | 5、接口/01-规范与统一层/工作手机API全量接口目录.md + /openapi.json |
| 服务端实现 | 6、后端/01-服务端/SDK服务端实现文档.md |
| 数据结构 | 7、数据库/01-设计/数据库设计文档.md |
| 部署流程 | 8、部署/ 对应环境主文档 |
| 操作说明 | 9、手册/工作手机·五图总览与使用手册.md |
| 进度百分比 | 10、项目管理/开发进度总表.md |
六、禁止事项
- 禁止在多个章节重复维护同一份接口表或进度百分比。
- 禁止把密码、Token、私钥、数据库口令写入文档。
- 禁止用 Mock、静态截图或页面演示替代真机验收。
- 禁止在章节根目录堆放没有索引的临时文件。
- 禁止继续新增其他项目名称作为工作手机文档主体。
七、验收闭环
一个功能只有同时满足以下条件才可标记完成：
需求有编号
→ 代码有实现路径
→ 接口或页面可执行
→ 真机或真实服务验证成功
→ 有日志/JSON/截图证据
→ 文档和进度已同步
八、目录维护责任
每个一级章节 README 是该章节的目录、规范和验收入口。新增文件时必须：
- 放入正确子目录；
- 在本章 README 登记；
- 标明主文档或补充材料；
- 添加关联代码与验收证据；
- 重复内容优先合并，不新增同义文件。