首页 / 工程规范 / 文档来源、版本与事实边界
文档来源、版本与事实边界
doc 文档的覆盖映射、来源优先级、设计与现状区分、冲突登记和更新流程。
doc 覆盖矩阵
本轮已盘点 /Users/oy/work/引势创新/doc/doc 下 53 份核心文档，并对 demo/doc、demo/app、demo/web、demo/figma 与 docker 进行了来源分类。下表把来源按主题映射到知识库，避免“看过文档但没有沉淀入口”。
| 来源组 | 主要文档 | 知识库入口 | 性质 |
|---|---|---|---|
| 架构与跨语言 | architecture/DOC_JAVA_GO_INTEROP、中台架构、10万级蓝图、实时音视频 ADD、图集、通信流程 | 总体架构、架构图集、gRPC 契约 | 目标架构/方案 |
| 设备协议与接口 | GPS Tracker MQTT、Tracker 适配、设备与云平台接口 V2/DEV | 设备协议与云端接口契约 | 多份协议草案，需冻结 |
| 产品、业务与中台 | 完整需求、业务逻辑、需求分析、微服务规划/功能、系统中台功能清单、详细规格 | 产品能力与业务中台地图 | 需求/规划/部分历史版本 |
| 客户端与后台 | App 功能清单、App 接口清单、前端实现、流程图、Web 缺口审计、后台任务 | 客户端与管理后台能力地图 | 交互与待办参考 |
| 规则、数据与 SIM | 规则设置、数据库设计任务、EIOTCLUB API 索引 | 规则引擎、数据库演进、SIM 供应商接入 | 目标数据模型/外部索引 |
| OTA 与诊断 | OTA 平台设计、技术规格、设备接口中的 OTA/诊断章节 | OTA 平台与远程诊断 | 目标平台设计 |
| 安全与合规 | 安全架构、P2P、规则、隐私/法规映射、SRC、响应手册、测试用例、出海清单 | P2P 安全、出海合规与事件响应 | 控制要求/需法务确认 |
| 交付与运行 | 开发测试环境、专项拆解、整改任务、订单任务、Go 分析报告 | 多团队研发专项拆解、研发交付治理与验收 | 计划/任务，不是完成证据 |
| 家庭影像产品 | 家庭影像/doc、meta-story-agent、docs/ai | 家庭影像功能全景、家庭影像技术架构 | 独立产品；按工程与来源文档区分已实现、待实测、规划 |
| 跨产品资料 | 智能康复系统规格、AI 运动康复架构图 | AquaRecover AI 参考规格 | 独立产品参考 |
| 演示与 Figma 资料 | demo/doc/*.md、demo/app、demo/web、demo/figma | 客户端与管理后台能力地图 | UI/交互和任务参考，不作为 API、权限或实现事实 |
| 工具与运行手册 | docker/*.md、根目录 README/项目指引 | 研发交付治理与验收 | 局部工具操作或仓库约定；敏感配置不复制进知识库 |
来源优先级
- 已验证运行事实：当前部署配置、已发布 API/Proto、数据库迁移、可复现测试和生产监控证据。
- 已批准且版本化的契约：ADR、Schema、OpenAPI/Proto、受控安全策略和发布说明。
- 已评审的需求/设计：明确标为目标状态，进入排期前还需技术验证。
- 规划、任务、图纸、演示与外部 API 索引：仅用于发现需求、方案和待办；不能直接推断当前实现或供应商接口字段。
知识库页面应在来源变更时更新“来源文件、版本/日期、性质、实现状态、最后验证方式”。无法确认时标为“待验证”，而不是补写猜测。
已识别的冲突
| 主题 | 文档差异 | 治理动作 |
|---|---|---|
| 设备 MQTT | Protobuf + $thing/... 与 MessagePack + device/{imei}/... 两套身份、Topic、编码约定。 | 按产品线建立协议 Profile；用版本化 Schema/抓包测试冻结，禁止自动混用。 |
| 媒体存储 | 云录像/对象存储设计与“平台不接收、不保存媒体内容”的本地 microSD 模式并存。 | 产品配置必须二选一或明确双模式隔离；数据、权限、成本和验收分别管理。 |
| 数据与租户 | 数据库任务出现多租户与多种数据库演进方案，合规/架构文档又有不同数据区域/改造设想。 | 以当前 Schema 和产品隔离需求重新做 ADR；历史表/任务不自动成为实现标准。 |
| 完成状态 | 部分开发清单标为完成，但缺少与当前代码、迁移、部署和测试绑定的统一证据。 | 状态统一改用“计划/进行中/已验证/阻塞”，并附构建、运行或审计证据。 |
| 跨产品内容 | 智能康复规格与车载平台文档共处同一目录。 | 独立分类、独立术语和交付物，不纳入车载平台服务/数据/合规事实。 |
| 演示页面 | 静态 demo 与 Figma 资料可能展示目标交互、模拟数据或已废弃页面。 | 只提炼用户任务和 UI 缺口；发布前以当前 API、权限契约和真机/浏览器验证为准。 |
更新与评审流程
- 新增/修订 doc 文档时，先标注产品、版本、作者/评审人、目标或现状性质和替代关系。
- 更新对应知识库页面、来源链接和冲突表；避免复制整篇文档造成多处漂移。
- 涉及接口、数据库、权限、数据留存或基础设施时，同时更新机器可读契约和验证用例。
- 构建知识库并检查导航、搜索、图片、链接和来源完整性；上线后补充实际验证证据。