乐橙智康文档生产规范

本文档是 docs_site/ 文档工程的高标准 handoff prompt，用于让后续 Codex 会话在不同批次中保持同一套专业判断：事实优先、读者视角、深度足够、图文有职责、来源可追溯。

1. 文档站定位

docs_site/ 是乐橙智康正式文档站源码，目标是沉淀一套面向同事理解与交接的事实型文档，帮助团队快速看懂产品全局、App 页面、主流程、前后端结构、AI/RAG、API、数据库与运行方式。

它不是：

PRD 系统
项目管理面板
开发排期或进度跟踪页
日报、周报或阶段汇报集合
脱离源码和运行事实的宣传页

核心标准只有两个：

内容足够清晰，读者不用回头猜代码、接口、页面、流程或数据库关系。
关键事实能追溯到源码、截图、API、表结构、配置、命令或测试结果。

正式文档默认面向：

新接手的开发同事
需要理解系统结构的产品或项目协作者
需要快速定位实现与运行事实的维护者

2. 真相源与边界

2.1 真相源优先级

正式文档优先引用可验证事实，优先级如下：

源码、目录结构、配置文件
API、模型、migration、测试、运行命令
当前版本截图、构建产物、部署事实
docs/ 中已有正式资料
.docs/ 中的历史记忆与 workflow

规则：

docs_site/ 正式文档优先引用 1-3。
.docs/ 只用于发现上下文、历史决策和临时框架，不替代源码、配置、API、migration、截图、测试与部署事实。
只有当某项关键信息暂时无法直接从正式代码或运行事实表达时，才允许用 .docs/ 作为过渡来源，并尽快回填到真实来源。
不确定的来源写 待校验 或 待补，不要编造。
出现品牌名与代码名冲突时，产品/品牌叙述使用“乐橙智康 / 动养AI”，代码、仓库、服务名、历史文件名保留真实 FitDoc。

2.2 站点与记忆分工

docs_site/：正式 HTML 文档源码，只保留常驻、可阅读、可交付内容。
.docs/：agent-facing memory、执行基线、阶段 TODO 和状态同步，不污染正式站点。
DOC_MATRIX.md：维护文档覆盖程度、状态和可见性，不承担项目管理职责。
SOURCE_MAP.md：维护跨文档来源映射，帮助后续会话找到事实来源。

2.3 安全与脱敏底线

禁止写入：

真实患者数据
手机号、身份证、诊疗记录
生产数据库连接串
JWT secret、API key、短信平台凭证、LLM vendor key
完整生产日志

允许写入：

脱敏示例
本地开发命令
不含真实值的环境变量名
抽象后的服务拓扑
内部交付所需的表结构、接口、模块关系

数据库文档是内部 reference，不做字段级“高敏/低敏”表；只保留总规则：不写真实患者样例、生产连接串、密钥和完整生产日志。

3. 写作总原则

3.1 读者视角

正式文档必须站在“读者阅读成品”的视角写，不站在“agent 正在工作”的视角写。正文只写系统当前是什么、页面如何工作、流程如何推进、边界在哪里、来源是什么。

允许的表达：

当前系统的前端路由由……构成。
本页说明 Flutter 路由结构、入口与主要转场方式。
RAG 专项治理不在本页展开。

禁止的表达：

本页只讲……
本板块承接……
这里不照抄……
不重复 Phase 1 / Phase 2 ……
这轮 / 这批 / 当前这轮回填……
按你的要求……
后续如需升到……
适合同事阅读……
为什么这里不放图 / 为什么这里不展开 / 为什么采用这种编排……

这些话术暴露了文档生产过程、会话上下文或 agent 工作痕迹，对正式读者没有价值。除非文档主题本身就是项目计划或 workflow 记录，否则正式站点不出现 Phase、workflow、本轮、回填 等推进语义。

3.2 事实与结构

先给结构和事实，再给解释。
用短标题、表格、流程图、列表、代码块承载信息。
不在每篇文档重复“这是什么、谁来读、有什么风险”。
不写“强大、领先、智能化”等没有证据的宣传词。
不把未验证内容写成事实。
需要警示时，只在真实有风险、未实现、不可用或会误导交接的地方写。
不把开发优先级、排期、Owner、Sprint 状态混入正式文档；这类推进信息放 .docs/workflow/。

3.3 深度标准

正式文档不追求平均展开，而追求“该深的地方足够深，该简的地方不啰嗦”。

判断标准：

如果读者读完一节后仍需要反复翻代码才能建立基本理解，说明写得太薄。
如果一节内容只是重复标题、目录名或显而易见的文件名，说明信息密度不够。
如果一节加入了很多只对文档作者有意义、对读者无帮助的提醒句或过程句，说明写偏了。

最低深度要求：

总览页要给出系统骨架、关键闭环和阅读入口，而不只是目录。
页面索引页要能让读者快速找到页面、入口、状态源和截图。
核心页面详解要讲清入口、动作、状态、数据源、边界和去向。
流程页要讲真实节点、阶段、跳转、返回、清栈、tab switch、dialog 和结果。
视觉页要讲 token、组件职责、落地页面、代表截图和已知偏差。
工程页要解释组织方式、关键依赖如何协作、当前有什么真实边界。
Reference 页可以更稠密，但必须保持可检索、可核对、少废话。

3.4 反模式

禁止把正式文档写成 AI 流水账或审计过程记录。

常见反模式：

用“首先 / 然后 / 最后”机械串联没有信息增量的段落。
用“该页面主要用于……”重复标题，而不说明入口、动作、状态和结果。
用“本页分三层写 / 下面从几个方面说明 / 这里不再配图”解释文档编排。
用“结论：基本符合 / 残留点 / 对齐点”把正式文档写成 review 记录。
为了页面显得丰富而插图、插表或插 Mermaid。
把页面图册、流程说明和视觉规范混成同一种文档。

推荐替代：

直接写读者关心的事实：入口在哪里、页面展示什么、点击后去哪里、失败时怎么表现。
对复杂流程按阶段写，每个阶段说明进入条件、页面动作、状态变化和离开方式。
对视觉规范按规范基线、当前落地、已知偏差、代表界面组织，偏差只写事实，不写作者评语。

4. 参考范式

这些参考不是逐页照搬，而是抽取公开成熟工程文档的组织方式。

参考对象	借鉴点	项目对应
腾讯蓝鲸 / BK-CI	平台型软件的产品模块、部署、开发者文档、API 与运维入口分层	产品总览、部署与运行
Ant Design Pro / Umi	路由、权限、请求、布局、构建部署、异常处理拆分清楚	Flutter 路由、鉴权、API client、页面状态
百度 amis	页面、组件、动作、数据源、CRUD、交互示例的结构化说明	App 页面文档、功能地图、表单和交互说明
Nacos / CloudWeGo	Overview、Architecture、Reference、Best Practice、FAQ 的分层	后端服务、AI/RAG、接口契约
OceanBase / RocketMQ / Dubbo / Seata	架构、部署、配置、迁移、排障、开发者 reference	数据库、部署运维、故障手册
Semi / Arco / TDesign	设计规范、Design Token、组件状态、示例、主题	UI/UX 与视觉规范
Logan / CAT	客户端、服务端、日志、监控、排障链路	移动端日志、线上问题定位、运维闭环

5. 文档类型职责

不同类型文档使用不同结构，不强制所有页面套同一个模板。关键是让每一页有明确阅读职责。

5.1 总览页

适用于板块入口，例如产品总览、后端总览、AI/RAG 总览、部署运维总览。

职责：

定义板块覆盖范围。
给出内容地图。
说明核心结构、主链或模块关系。
指向后续深读入口和来源锚点。

推荐结构：

# 板块名称

一句话说明本板块覆盖范围。

## 内容地图

列出子文档和用途。

## 核心结构

用 Mermaid 或表格说明模块关系。

## 接续方式

说明下一步应该读哪篇或从哪里取证。

5.2 页面总览与截图索引

职责：

列出页面范围。
告诉读者页面入口、主要功能、状态源。
提供缩略图或截图文件索引，帮助快速定位。
区分当前可达页面、过渡页、代码保留但入口隐藏页面。

不承担：

逐页详细讲解。
大图阅读。
复杂流程说明。

适合内容：

表格。
小尺寸缩略图。
页面分组。
页面入口、状态源、预览图。

5.3 核心页面详解

职责：

让读者边看图边理解单个页面。
解释页面入口、功能、状态、用户动作、数据来源和边界。
讲清页面之间的主要去向，不把页面写成孤立截图。

每个页面至少包含：

维度	内容
页面入口	route、tab、按钮或跳转来源
数据来源	API client、BLoC/state、mock 或本地缓存
用户动作	点击、提交、返回、刷新、跳转
页面状态	loading、empty、error、offline、auth expired 等真实存在的状态
截图	当前版本截图，文件名可追踪

不承担：

全量索引。
页面全集堆图。
复杂跨页流程图。

适合内容：

一页一块或一组一块。
中等尺寸截图。
图下紧跟说明。
截图与对应页面说明保持一一绑定，避免先堆图、后解释。

注意：

图注使用自然标题，不直接把截图文件名写进正文或 caption。
单个页面小节的重点是“看图即可理解这一页在做什么”，不是展示原始文件名。

5.4 主流程与跳转关系

适用于用户旅程、功能地图、跳转关系、核心链路。

职责：

说明关键流程如何跨页面推进。
解释阶段边界、入口、状态变化、跳转、返回、清栈、tab switch、dialog 和结果。
区分独立路由、底部 tab、顶部 tab、弹窗、抽屉、页面内状态切换。

不承担：

页面图册。
每个页面的完整视觉说明。

适合内容：

Mermaid 总流程图。
关键跳转表。
分阶段说明。
每个阶段只在有明确阅读职责时配代表图。

推荐结构：

# 功能或流程名称

一句话说明当前链路状态。

## 流程图

Mermaid 或必要截图。

## 关键跳转表

页面、动作、目标、实现方式、备注。

## 分阶段说明

进入条件、页面动作、状态变化、离开方式。

## 来源锚点

列出对应文件、接口、截图或命令。

5.5 视觉风格与组件规范

视觉规范不单独作为一级板块，统一放入 App 使用与页面说明。它服务于截图、页面说明和前端实现，不写成独立设计系统，除非后续真的进入系统性 UI 改版。

必须覆盖：

全局配色候选或当前 token。
字体与排版。
组件风格。
页面状态视觉。
截图规范。
可选视觉方向及取舍。

写法要求：

每个颜色给出用途，不只给色值。
每个组件风格说明适用场景。
可选方案必须有 trade-off，不能只放“好看”的方案。
最终落地到 Flutter theme 或截图时，补来源锚点。
代表图只证明视觉判断，不承担页面全集展示。

5.6 Reference 页

适用于 API、数据库表、配置、环境变量、路由表、部署命令等可检索内容。

职责：

用清单、字段、参数、配置项、关联关系和来源锚点组织事实。
保持可检索、可核对、少散文。
明确对象被谁调用、读写哪些表、影响哪些页面。

推荐结构：

# Reference 名称

## 清单

表格列出对象。

## 字段 / 参数 / 配置项

类型、含义、约束、默认值。

## 关联关系

被谁调用、读写哪些表、影响哪些页面。

## 来源锚点

源码、配置、迁移、测试。

6. 图表与截图规则

6.1 图表职责

Mermaid 用于解释关系、路径、状态、数据流、ER 或架构边界，不能替代正文说明。
截图用于证明真实界面、布局、状态或视觉判断，不能充当页面清单装饰。
表格用于压缩可比较信息，不能把需要连续理解的流程拆成碎片。
复杂图可以用图片，但需要在文档里说明图的来源和更新时间。
如果一张图不能回答一个清晰阅读问题，就删除它。

6.2 Mermaid 可读性规则

Mermaid 图优先服务阅读，不追求把所有源码节点画进一张图。

节点主标签使用中文业务语义；必要的接口、函数、表名和类名放在第二行，保留英文原名。
第二行英文应短而可核对，例如 RAGRuntimeGateway、knowledge_chunks、POST /api/chat/message；完整函数路径放到正文表格或来源锚点。
节点换行统一使用 Mermaid 原生 \n，不使用 <br/>；双行节点优先保持“中文业务语义 + 英文锚点”。
单个节点不承载完整路径、长函数名或长表名组合；节点文字过长时，保留短锚点，把完整信息放入正文表格或来源锚点。
总览图控制在 6-8 个主节点以内；超过一屏才能讲清的链路，应拆成“总览图 + 分阶段表格”。
主流程、业务闭环、部署拓扑和调用链优先控制在 5-7 个节点内；节点较少且一屏可放下时可使用 flowchart LR，复杂分支使用 flowchart TB/TD 并把细节放入正文表格。
Mermaid 图不应产生页面级横向滚动；如果横向图需要左右滑动才能读完，说明节点过多，应拆分或改写为阶段图。
不用 Mermaid 装饰页面；每张图必须说明结构、边界、状态或数据流。
不在节点里使用 HTML 字号标签压缩信息；如果文字太多，说明它应进入正文或表格。
技术名不能替代业务语义。FastAPI routes、BLoC、knowledge_chunks 可以保留，但不应成为读者第一眼看到的唯一信息。

6.3 截图来源与脱敏

截图放在：

text

docs_site/public/images/screenshots/

文件名长期建议使用英文短横线：

text

chat-session-empty-state.png

当前若已有中文截图文件名，可以先保留真实路径；对外发布或长期维护时再统一迁移命名。

截图规则：

截图用于辅助理解页面、布局、状态和交互，不承担 bug 追踪或验收存档职责。
截图优先使用当前真实界面，不使用带真实患者信息、真实账号信息或生产数据的画面。
如果截图是示意图、旧稿或未与当前界面完全一致，必须在文档中标明。
caption 使用自然标题，不写文件名，不写“见上图 / 如下图所示”这类低信息句。

6.4 截图尺寸与编排

截图尺寸不追求原图原样摆上去，而追求健康阅读。

规则：

索引页使用小尺寸缩略图。
详解页使用中等尺寸截图，优先控制在单列可完整阅读范围内。
不在正文中直铺超高手机原图，避免一张图占满整个阅读视口。
一组同类页面优先用 gallery 或卡片式布局，不建议一页中连续堆叠多张大图。
页尾不集中堆放一串无上下文的截图占位路径；截图应放在真正服务理解的位置。
如果索引页已经承担页面全集检索，详解页不再追求图片齐全，而应优先保证重点页面的图文绑定质量。

7. 来源锚点规范

所有非显而易见的事实都要能落到来源。来源锚点写短，不写长篇解释。

推荐格式：

## 来源锚点

- Flutter: `apps/flutter_app/lib/...`
- Backend: `apps/backend_service/app/api/...`
- DB: `apps/backend_service/app/models/...`
- Migration: `apps/backend_service/alembic/...`
- Screenshot: `public/images/screenshots/...`
- Command: `npm run docs:build`

规则：

一个页面可以只列 2-5 个关键来源，不需要堆满。
不确定的来源写 待补 或 待校验。
新增跨模块事实来源必须登记到 SOURCE_MAP.md。

8. API 文档规范

API 文档必须采用接近 OpenAPI reference 的严谨格式，不写散文。

要求：

Method、Path、Auth、Request、Response、Errors 必须有。
Consumers、Backend Handler、DB Touchpoints、Tests 在源码确认后补。
示例 JSON 必须脱敏，不使用真实用户数据。
错误处理要说明前端处理方式，尤其是 401、422、500 这类常见分支。

推荐格式：

# POST /api/v1/chat/message

## Summary

发送用户消息并返回 AI 响应。

## Auth

Bearer JWT required.

## Request

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `session_id` | string | false | 会话 ID，不传时由后端创建或沿用默认策略。 |
| `message` | string | true | 用户输入。 |

## Response 200

```json
{
  "session_id": "...",
  "message_id": "...",
  "content": "..."
}
```

## Errors

| Status | Meaning | Frontend Handling |
| --- | --- | --- |
| 401 | token expired | 清理登录态并跳转登录 |
| 422 | invalid payload | 展示字段级提示 |
| 500 | service failure | 展示失败提示，允许重试 |

## Consumers

- Flutter client: `...`
- Page: `...`

## Backend Handler

- Router: `...`
- Service: `...`

## DB Touchpoints

- Read: `...`
- Write: `...`

## Tests

- `pytest ...`

9. 数据库文档规范

数据库板块优先覆盖：

ER 图
表清单
字段说明
表关系
索引与约束
Alembic 迁移来源
哪些 API 会读写这张表
核心数据流
常用排障 SQL 或检查命令

表文档推荐格式：

# `dialogue_log`

## 用途

保存聊天消息记录。

## 字段

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| `id` | bigint | no | 主键。 |

## Relations

| Relation | Description |
| --- | --- |
| `session_id -> chat_session.id` | 归属会话。 |

## Read / Write

| API / Service | Read | Write |
| --- | --- | --- |
| 待补 | 待补 | 待补 |

## Source

- Model: `...`
- Migration: `...`

10. 维护与验证

维护规则：

新增文档必须登记到 DOC_MATRIX.md。
新增跨模块事实来源必须登记到 SOURCE_MAP.md。
过期文档不要静默删除，先标注替代文档或迁移去向。
阶段性交付后更新面向交接真正有价值的入口页，不要把临时汇报混进常驻文档。
每次修改文档后运行 npm run docs:build。

提交前检查：

正式正文是否仍有 本轮 / Phase / workflow / 按你的要求 / 后续如需升到 等生产痕迹。
每张图是否有明确阅读职责。
索引页、详解页、流程页、视觉页是否各司其职。
页面覆盖是否与真实代码、截图和当前可达入口一致。
HealthOverviewScreen、WeeklyReportScreen 这类隐藏入口页是否被写成“代码保留但当前不作为可达入口”。
来源锚点是否能回到真实存在的源码、配置、截图或运行事实。
文档是否没有写入真实患者数据、凭证、生产连接串或完整生产日志。

乐橙智康文档生产规范 ​

1. 文档站定位 ​

2. 真相源与边界 ​

2.1 真相源优先级 ​

2.2 站点与记忆分工 ​

2.3 安全与脱敏底线 ​

3. 写作总原则 ​

3.1 读者视角 ​

3.2 事实与结构 ​

3.3 深度标准 ​

3.4 反模式 ​

4. 参考范式 ​

5. 文档类型职责 ​

5.1 总览页 ​

5.2 页面总览与截图索引 ​

5.3 核心页面详解 ​

5.4 主流程与跳转关系 ​

5.5 视觉风格与组件规范 ​

5.6 Reference 页 ​

6. 图表与截图规则 ​

6.1 图表职责 ​

6.2 Mermaid 可读性规则 ​

6.3 截图来源与脱敏 ​

6.4 截图尺寸与编排 ​

7. 来源锚点规范 ​

8. API 文档规范 ​

9. 数据库文档规范 ​

10. 维护与验证 ​

乐橙智康文档生产规范

1. 文档站定位

2. 真相源与边界

2.1 真相源优先级

2.2 站点与记忆分工

2.3 安全与脱敏底线

3. 写作总原则

3.1 读者视角

3.2 事实与结构

3.3 深度标准

3.4 反模式

4. 参考范式

5. 文档类型职责

5.1 总览页

5.2 页面总览与截图索引

5.3 核心页面详解

5.4 主流程与跳转关系

5.5 视觉风格与组件规范

5.6 Reference 页

6. 图表与截图规则

6.1 图表职责

6.2 Mermaid 可读性规则

6.3 截图来源与脱敏

6.4 截图尺寸与编排

7. 来源锚点规范

8. API 文档规范

9. 数据库文档规范

10. 维护与验证