文档维护规范

核心原则

代码与文档同步变更：每次代码修改完成后，必须在同一次提交中同步更新相关文档。

单一事实源（Single Source of Truth）：同一主题只在一处文档维护，其他位置用链接引用，禁止复制粘贴造成双源漂移。

构建即校验：docusaurus.config.ts 已开启 onBrokenLinks: throw，任何站内断链都会导致构建失败——链接有效性由构建强制保证。

文档目录结构

磁盘结构对照：

docs/
├── docs/                    # Docusaurus 站点正文（进入构建与导航）
│   ├── intro.mdx            # 项目简介（站点首页，slug: /）
│   ├── product/             # 产品与能力
│   │   ├── overview.md              # 产品总览与页面地图
│   │   ├── quant-scoring.md         # 量化选股与打分体系
│   │   ├── ai-capabilities.md       # AI 能力架构
│   │   └── auth-and-notification.md # 用户体系：鉴权、配额与通知
│   ├── api/                 # API 参考
│   │   ├── market-api.md
│   │   ├── stocks-api.md
│   │   └── datamgr-api.md
│   ├── data-management/     # 架构与数据
│   │   ├── architecture.md  # 数据管理架构（文件结构+数据表+降级链）
│   │   ├── data-model.md    # 数据模型总览（215 张表）
│   │   ├── data-flow.md     # 数据流转（46 个定时任务时序）
│   │   ├── cache-strategy.md
│   │   ├── task-center.md   # 任务中心与进程模型
│   │   ├── data-sources.md  # 数据源总览
│   │   ├── source-tdx.md / source-tencent.md / source-eastmoney.md / source-sina.md
│   │   ├── error-handling.md / circuit-breaker.md / performance.md
│   │   └── usage-examples.md
│   ├── reference/             # 速查手册（工程权威速查，已纳入站点）
│   │   ├── api-routes.md              # 端点路由速查（按模块全量索引 + 高频降级链）
│   │   ├── data-contract.md           # 数据契约（分层/列契约/单位口径/不变量）
│   │   └── data-source-coverage.md    # 数据源覆盖对照（对标 liangmai / akshare）
│   └── guide/               # 配置与开发指南
│       ├── configuration.md
│       ├── faq.md
│       └── doc-maintenance.md  # 本文档
├── archive/                 # 归档区：历史计划/评审快照（冻结，不进站点）
├── sidebars.ts              # 导航结构（手动维护）
└── docusaurus.config.ts     # 站点配置

命名规范

对象	规则	示例
站点正文文档	kebab-case，全小写，连字符分隔，禁止空格/下划线/中文	`market-api.md`、`source-tdx.md`
速查手册文档（`reference/`）	同上 kebab-case，且必须与站点正文一样带 frontmatter	`reference/api-routes.md`
归档文档	保持原名移入 `archive/`，追溯性优先	`archive/PRODUCTION_REVIEW.md`
惯例大写文件	`README.md`、`AGENTS.md`、`CONTRIBUTING.md`、`LICENSE` 除外	—
API 文档命名	`<路由模块名>-api.md`，与 `backend/app/api/` 下模块一一对应	`datamgr.py` → `datamgr-api.md`
数据源文档命名	`source-<数据源名>.md`	`source-tdx.md`

导航注册要求

站点导航由 sidebars.ts 手动维护，结构为「8 个分类 + 1 个首页文档」，层级固定两级：

分类	入口文档	包含
项目简介	intro	站点首页（`type: 'doc'`，非分类）
产品与能力	product/overview	overview / quant-scoring / ai-capabilities / auth-and-notification
架构设计	architecture	architecture / data-model / data-flow / cache-strategy / task-center
数据源集成	data-sources	data-sources / source-tdx / source-tencent / source-eastmoney / source-sina
可靠性与性能	error-handling	error-handling / circuit-breaker / performance
数据管理操作	usage-examples	usage-examples
API 参考	market-api	market-api / stocks-api / datamgr-api
速查手册	reference/api-routes	api-routes / data-contract / data-source-coverage
配置与开发指南	configuration	configuration / faq / doc-maintenance

新增文档必须同步在 sidebars.ts 对应分类的 items 中注册；每个分类必须保留 link（入口文档）与 description（入口说明）。首页 <DocCardList /> 会自动收录分类卡片，分类的 description 会直接显示在首页，改分类必须同时改这句摘要。

frontmatter 要求

每篇站点文档顶部必须包含 frontmatter：

---
description: 一句话说明本篇覆盖的内容与范围（全站检索摘要与 SEO 描述）
sidebar_position: 2   # 分类内的建议排序（手动导航下作备用）
---

字段	必填	说明
`description`	✅	一句话摘要，用于检索结果与链接预览；同分类内不应重复
`sidebar_position`	✅	分类内排序；手动导航下作备用
`slug`	仅首页	只有 `intro.mdx` 使用 `slug: /` 固定为站点根

页面尾巴：相关文档

每篇站点文档正文末尾必须有 ## 相关文档 小节，列出 2~5 条互链：

## 相关文档

- [数据流转](/data-management/data-flow)
- [缓存策略](/data-management/cache-strategy)
- [数据契约速查](/reference/data-contract)

站内文档（含 reference/ 速查手册）用站内绝对路径（/data-management/xxx、/reference/xxx），由构建强制校验
速查手册是站点正文的一部分，引用它一律写 markdown 链接（不要退化成文字路径，那正是它此前没有导航与检索入口的原因）
仓库根级文件（AGENTS.md、README.md、docs/archive/）不在站点内，站点里提到时写成代码路径 `AGENTS.md`
不要在页尾堆砌全部同类文档，只列真正相关的 2~5 条

本地全文检索

站点内置 @easyops-cn/docusaurus-search-local，索引在 npm run build 时本地生成（build/search-index.json），不依赖外部服务、不发任何网络请求：

检索只在构建产物里可用：该插件仅在 postBuild 阶段生成索引，npm start（开发模式）下搜索框会提示 "search index is only available when you run docusaurus build"。需要验证检索/预览成品，用 npm run build && npm run serve；需要边改边看热更新，用 npm start 且不依赖搜索
中文分词依赖显式声明的 language: ['zh', 'en']，缺失会退化为按字符切分
索引是构建期快照：新增/改名文档后必须重新 npm run build 才会进入索引
配置位于 docusaurus.config.ts 的 plugins 段（hashed: true 使索引文件名带哈希，避免浏览器缓存旧索引）

首页与导航卡片

intro.mdx 是站点首页（slug: /），通过 <DocCardList /> 自动渲染 sidebars.ts 中 8 个分类的卡片（标题取自分类 label，摘要取自分类 description）。

因此分类的 description 不是可选装饰：它直接显示在首页与分类跳转页上，必须写清楚该分类覆盖什么。

文档更新责任

角色	责任
代码修改者	负责在提交前完成相关文档更新
Code Reviewer	检查文档是否与代码变更一致
项目负责人	定期审计文档与代码的一致性

触发文档更新的代码变更

以下类型的代码变更必须同步更新文档：

1. API 变更 → 更新 `docs/docs/api/*.md` + `docs/docs/reference/api-routes.md`

新增 API 端点 / 修改请求响应格式 / 变更参数名称或类型 / 删除或废弃端点
前端会用到的端点须补进速查手册的高频表；新增/删除 backend/app/api/ 下的路由模块时，同步改 reference/api-routes.md §〇的「按模块全量索引」行（模块数/前缀/操作数）

对应文档：

路由文件	文档文件
`backend/app/api/datamgr.py`	`docs/docs/api/datamgr-api.md`
`backend/app/api/market.py`	`docs/docs/api/market-api.md`
`backend/app/api/stocks.py`	`docs/docs/api/stocks-api.md`

2. 数据源变更 → 更新 `docs/docs/data-management/source-*.md`

新增/替换数据源、修改连接机制或降级策略、变更数据源优先级

数据源文件	文档文件
`tdx_client.py`	`source-tdx.md`
`em_client.py` / `em_paginated.py`	`source-eastmoney.md`
`tencent_client.py`	`source-tencent.md`
`sina_source.py`	`source-sina.md`

3. 数据库模型变更 → 更新 `data-model.md` + `architecture.md`

新增数据表、修改表结构（增删字段）、变更索引或约束

4. 架构变更 → 更新 `architecture.md` + `data-sources.md`

修改文件结构、变更降级链路、调整缓存策略、新增核心模块

5. 前端组件变更 → 更新相关功能文档

新增用户可操作的功能按钮、变更页面交互流程、新增数据展示面板

6. 产品与业务体系变更 → 更新 `docs/docs/product/*.md`

变更	文档文件
新增/删除路由、页面职责变化、导航分组调整	`product/overview.md`（页面地图须与 `src/App.tsx` 逐条对齐）
因子定义/权重、门控阈值、预设条目、形态判据、留痕口径	`product/quant-scoring.md`
模型 Key 池与降级、技能数量、MCP 工具、provenance 档位、晨报复盘区块契约	`product/ai-capabilities.md`
鉴权/角色/配额、通知与 SMTP、菜单可见性	`product/auth-and-notification.md`

7. 任务与进程模型变更 → 更新 `data-management/task-center.md` + `data-flow.md`

新增/删除 SCHEDULED_TASKS 注册项、改触发时点、改 app_task_* 三层表结构、改 XUANGU_ROLE 角色语义或 worker 心跳判活规则

8. 数据口径与数据源能力变更 → 更新 `docs/docs/reference/*.md`

变更	文档文件
新增写入口/分层规则、列契约、单位口径、段级出处标签、形态字段语义	`reference/data-contract.md`
新增数据源或补齐对 akshare / liangmai 的覆盖缺口（含明确不实现项）	`reference/data-source-coverage.md`

reference/data-contract.md 是约 12 个后端源文件与测试注释引用的权威（按 §号定位），改分层规则时必须同步该节的 §号，否则引用会指错。

新文档创建流程

确定归属分类（参照上方分类表，避免新建游离文档）
复制下方模板创建文件（kebab-case 命名）
在 sidebars.ts 对应分类注册
补全 frontmatter（description + sidebar_position）
正文末尾补「相关文档」并在相关页面回链（双向）
cd docs && npm run build 验证通过
代码 + 文档一起提交

新增文档后侧边栏与首页分类卡片自动包含该页；但本地检索索引需重启 npm start 才会包含新页面。

文档模板

通用文档模板

---
description: 一句话摘要（覆盖范围与读者）
sidebar_position: N
---

# <标题>

## 概述

<一段话说明本文档覆盖范围与读者>

## 正文

<按主题分节，图表优先（Mermaid）>

## 相关文档

- [关联文档](/category/doc-name)

API 端点模板

### METHOD /api/v1/path/to/endpoint

功能描述（一句话）。

**参数**（如有）:
- `param1`: 说明（类型，默认值）

**请求体**（如有）:
```json
{...}
```

**响应**:
```json
{...}
```

数据源文档模板

每个数据源文档必须包含：

概述（协议、封IP风险、优先级）
实现文件路径
连接机制说明
提供的数据接口表格
在降级链中的位置
注意事项

链接规范

场景	规则
站内文档互链	使用站内路径（如 `[架构总览](/data-management/architecture)`），构建时由 `onBrokenLinks: throw` 强制校验
站点正文 ↔ 速查手册	速查手册（`docs/docs/reference/`）是站点正文的一部分，互链用站内绝对路径（如 `[端点路由速查](/reference/api-routes)`）
站点正文 → 仓库根级文件	`AGENTS.md`、`README.md`、`docs/archive/` 不在站点路由内，提到时写代码路径（如 `AGENTS.md`），写成 markdown 链接会断链
README / AGENTS.md → docs	使用相对路径文件引用（如 `docs/docs/reference/api-routes.md`）
外部资源	允许完整 URL；禁止引用内网/临时地址

安全红线

严禁在文档中写入真实密码、API Key、JWT token、数据库凭据——一律使用占位符（<admin-user>、<your-token>）
示例中的账号密码来自真实环境同样禁止（历史教训：usage-examples.md 曾泄漏真实凭据，已于文档审查中清除）
日志/报错截图入文档前需脱敏

归档政策

历史计划、一次性评审报告、测试快照等时间敏感文档在目的达成后移入 docs/archive/：

确认文档零外部引用（Grep 文件名全库扫描）
git mv <file> docs/archive/
在 docs/archive/README.md 归档清单登记

归档文档不再维护、不进站点构建；最新信息以 docs/docs/ 站点正文为准。

一致性检查清单

代码提交前，对照以下清单确认文档一致性：

文档构建验证

cd docs
npm run build

构建配置了 onBrokenLinks: throw / onBrokenAnchors: throw / onDuplicateRoutes: throw：任何站内断链、失效锚点或重复路由都会使构建失败，确保提交的文档引用始终有效。

npm run build 另带 prebuild 钩子：先校验提示块写法（见下节），不合法同样会让构建失败。

提示块（admonitions）语法

关键字共 6 个：note / tip / info / caution / warning / danger。带标题时标题必须写在方括号里：

:::warning[写入口已废弃（2026-08-22）]
正文支持完整 Markdown（列表、代码块、表格、行内 `代码`），标题本身也支持。
:::

:::tip
不带标题时关键字后**不加空格与文字**。
:::

🔴 下面两种写法在 Docusaurus v3+ 下都不被解析为提示块（整块连同 ::: 一起当普通正文渲染，页面上只表现为「漏了一段文字」，而 docusaurus build 自身不会报错）：

:::warning 标题 —— 关键字后直接跟空格和标题（Docusaurus v2 旧语法）
:::warning [标题] —— 关键字与方括号之间有空格

因此构建前有一道守卫，不必靠肉眼核对：npm run build 的 prebuild 钩子会先执行 npm run check:admonitions（scripts/check-admonitions.mjs），扫出上述写法与未登记的关键字后以非零码退出。也可单独执行：

npm run check:admonitions   # 无输出即通过；不通过会列出 file:line 与建议写法

该脚本会跳过代码围栏内的示例文本；新增自定义提示块关键字时，需同步登记到脚本的 KEYWORDS。

版本标记

重大架构变更时，在文档顶部添加版本标记：

:::info[版本变更]
自 v2.0 起，TDX 主客户端改为项目内自实现的 TCP 协议客户端（`tdx/` 包），
已彻底移除 easy_tdx / mootdx / pytdx 等第三方依赖。
:::

核心原则​

文档目录结构​

命名规范​

导航注册要求​

frontmatter 要求​

页面尾巴：相关文档​

本地全文检索​

首页与导航卡片​

文档更新责任​

触发文档更新的代码变更​

1. API 变更 → 更新 docs/docs/api/*.md + docs/docs/reference/api-routes.md​

2. 数据源变更 → 更新 docs/docs/data-management/source-*.md​

3. 数据库模型变更 → 更新 data-model.md + architecture.md​

4. 架构变更 → 更新 architecture.md + data-sources.md​

5. 前端组件变更 → 更新相关功能文档​

6. 产品与业务体系变更 → 更新 docs/docs/product/*.md​

7. 任务与进程模型变更 → 更新 data-management/task-center.md + data-flow.md​

8. 数据口径与数据源能力变更 → 更新 docs/docs/reference/*.md​

新文档创建流程​

文档模板​

通用文档模板​

API 端点模板​

数据源文档模板​

链接规范​

安全红线​

归档政策​

一致性检查清单​

文档构建验证​

提示块（admonitions）语法​

版本标记​

相关文档​