文档体系架构

本文档描述项目的7层文档体系架构、依赖关系和导航逻辑。

📊 依赖关系图

三层入口体系

Layer 0（统一入口）
└─ README.md
   ├─ 🆕 新用户 → QUICKSTART.md
   ├─ 👨‍💻 开发者 → docs/README.md
   └─ 🤖 Claude Code → CLAUDE.md

Layer 1（角色分流）
├─ QUICKSTART.md（5分钟快速上手）
│  ├─ docs/product.md
│  ├─ docs/design.md
│  └─ docs/development.md
│
├─ docs/README.md（7层文档导航）
│  ├─ Layer 2（产品业务）→ 4个文档
│  ├─ Layer 3（开发规范）→ 9个文档
│  ├─ Layer 4（架构设计）→ 2个文档
│  ├─ Layer 5（专项技术）→ 9个文档
│  ├─ Layer 6（辅助工具）→ 7+个文档
│  └─ Layer 7（自动化）→ 6+个文档
│
└─ CLAUDE.md（Claude 总控制台）
   ├─ docs/README.md（导航）
   ├─ docs/product.md（产品）
   ├─ docs/design.md（架构）
   ├─ docs/decisions.md（技术决策）
   ├─ docs/development.md（开发规范）
   ├─ docs/database/schema.md（数据库权威）
   ├─ docs/deployment/（配置指南）
   └─ docs/ui-guidelines/（UI规范）

Layer 2-7（具体文档）
└─ 37个专项文档（见 docs/README.md）

🎯 依赖关系原则

单向依赖（DAG）

文档依赖关系遵循**有向无环图（DAG）**原则：

高层级文档 ─引用→ 低层级文档
（抽象）           （具体）

✅ 正向依赖（允许）：
README.md → QUICKSTART.md
CLAUDE.md → docs/database/schema.md
docs/README.md → docs/product.md

❌ 反向依赖（禁止）：
docs/product.md → README.md
docs/database/schema.md → CLAUDE.md

❌ 循环依赖（禁止）：
CLAUDE.md ↔ docs/README.md

依赖分级

层级	名称	可引用的层级	被引用的层级
Layer 0	统一入口	Layer 1	无（顶层）
Layer 1	角色分流	Layer 2-7	Layer 0
Layer 2	产品业务	Layer 3-7	Layer 0-1
Layer 3	开发规范	Layer 4-7	Layer 0-2
Layer 4	架构设计	Layer 5-7	Layer 0-3
Layer 5	专项技术	Layer 6-7	Layer 0-4
Layer 6	辅助工具	Layer 7	Layer 0-5
Layer 7	自动化	无（底层）	Layer 0-6

核心规则：

✅ 只能引用同级或更低层级的文档
❌ 禁止引用更高层级的文档（避免循环依赖）

📈 文档入度/出度统计

入度（被引用次数）

高入度文档（被频繁引用，核心文档）：

文档	入度	角色
docs/README.md	106	📚 导航中枢
CLAUDE.md	42	🤖 Claude控制台
docs/database/schema.md	35	🗄️ 数据库权威
docs/product.md	28	📋 产品定位
docs/development.md	24	👨‍💻 开发规范
CHANGELOG.md	18	📝 变更历史

中入度文档（重要文档）：

文档	入度	角色
docs/design.md	15	🏗️ 架构设计
docs/deployment/supabase-setup-guide.md	12	⚙️ 配置指南
docs/plans/backlog.md	10	✅ 任务追踪（旧 TODO.md 2026-08-17 归档）

低入度文档（专项文档）：

入度 < 5：大部分 Layer 5-7 文档（按需查阅）

出度（引用其他文档数量）

高出度文档（导航型文档）：

文档	出度	角色
docs/README.md	59	📚 主导航（7层文档体系）
CLAUDE.md	42	🤖 Claude工作流导航
README.md	16	🏠 入口导航
docs/development.md	12	👨‍💻 开发指南导航

低出度文档（叶子文档）：

出度 = 0：专项技术文档（如具体的 UI 规范文档）

🔍 依赖关系类型

定义：用于引导用户找到相关文档

示例：

markdown

README.md:
- 🆕 **新用户**：[5分钟快速上手](QUICKSTART.md)
- 👨‍💻 **开发者**：[文档导航](docs/README.md)

特点：

✅ 高层级 → 低层级
✅ 抽象 → 具体
✅ 单向依赖

2. 引用依赖（Reference）

定义：引用权威文档作为详细说明

示例：

markdown

CLAUDE.md:
详细表结构见 [docs/database/schema.md](docs/database/schema.md)

特点：

✅ 避免重复内容
✅ 保持单一数据源（Single Source of Truth）
✅ 指向权威文档

3. 工作流依赖（Workflow）

定义：指导用户按顺序查阅文档

示例：

markdown

开发新功能：
1. 确认优先级：[product.md](product.md)
2. 了解架构：[design.md](design.md)
3. 遵循规范：[development.md](development.md)

特点：

✅ 任务导向
✅ 按执行顺序排列
✅ 面向具体场景

📐 架构设计原则

原则 1：单一入口（Single Entry Point）

定义：所有用户从 README.md 进入，按角色分流

实现：

README.md（统一入口）
├─ 新用户 → QUICKSTART.md
├─ 开发者 → docs/README.md
└─ Claude Code → CLAUDE.md

优势：

✅ 避免用户迷失
✅ 统一的"首页"体验
✅ 易于维护（修改入口只需改一处）

原则 2：职责分离（Separation of Concerns）

定义：每个文档有明确且单一的职责

实现：

文档	职责	禁止内容
README.md	入口导航	❌ 详细技术细节
CLAUDE.md	Claude行为规则	❌ 开发者操作指南
docs/README.md	文档导航	❌ 具体技术实现
docs/database/schema.md	数据库权威定义	❌ 产品需求

原则 3：层级隔离（Layer Isolation）

定义：每层文档只引用同级或更低层级

实现：

Layer 1 ─可引用→ Layer 2-7
Layer 2 ─可引用→ Layer 3-7
Layer 3 ─可引用→ Layer 4-7
...
Layer 7 ─不引用任何层级（叶子节点）

禁止：

❌ Layer 5 → Layer 2（反向依赖）
❌ Layer 3 ↔ Layer 4（循环依赖）

原则 4：权威数据源（Single Source of Truth）

定义：每类信息只在一个文档中定义，其他文档引用

示例：

信息类型	权威文档	引用方式
数据库表结构	docs/database/schema.md	链接引用
产品功能列表	docs/product.md	链接引用
架构设计	docs/design.md	链接引用
Schema 版本号	app_database.dart	文档引用代码

反例（重复内容）：

❌ CLAUDE.md 复制粘贴 schema.md 的表结构
❌ README.md 复制粘贴 product.md 的功能列表

✅ CLAUDE.md 链接到 schema.md
✅ README.md 链接到 product.md

🛠️ 维护机制

Git Hooks 自动检查

Pre-commit Hook（.git/hooks/pre-commit）：

自动检测以下问题：

✅ 断链（Broken Links）- 引用不存在的文档
✅ 循环依赖（Circular Dependencies）- 双向引用
✅ 文档一致性（Consistency）- Schema版本、数据一致性
✅ 命名规范（Naming Convention）- kebab-case vs UPPER_CASE

检查脚本：scripts/doc-consistency-check.sh

Claude 自动感知

触发条件：

创建新文档（*.md）
大量修改文档（5+ 个文件）
检测到循环依赖关键词

自动响应：

📋 提醒更新 docs/README.md
📋 检查是否引入循环依赖
📋 验证层级归属

季度架构审查

频率：每季度一次（Q1/Q2/Q3/Q4）

审查内容：

文档数量统计（各层是否超标）
依赖关系检查（是否有新的循环依赖）
导航完整性（docs/README.md 是否包含所有文档）
架构演进决策（是否需要调整层级定义）

审查脚本：scripts/doc-architecture-review.sh（待创建）

📊 架构演进历史

v1.0（2026-01-15）：7层文档体系建立

✅ 定义 Layer 1-7 分层架构
✅ 创建 docs/README.md 作为导航中枢
✅ 按专项创建子目录（database/, guides/, ui-guidelines/）

v1.1（2026-01-23）：文档清理和备份机制

✅ 删除过时文档（testing.md, performance.md）
✅ 建立 backups/ 备份机制
✅ 清理临时文件和日志

v1.2（2026-01-28）：解决循环依赖 + 三层入口体系

✅ 解决 CLAUDE.md ↔ docs/README.md 循环依赖
✅ 建立三层入口体系（README → QUICKSTART/docs/README/CLAUDE）
✅ 创建 docs/deployment/ 目录组织配置文档
✅ 创建 docs/ARCHITECTURE.md（本文档）

🎯 快速参考

如何选择引用哪个文档？

场景 1：新功能开发

用户角色：开发者
入口：README.md → docs/README.md
路径：按任务查找 → 开发新功能

场景 2：Claude 执行任务

用户角色：Claude Code
入口：CLAUDE.md
路径：开发流程 → 新功能开发

场景 3：新人上手

用户角色：新用户
入口：README.md → QUICKSTART.md
路径：5分钟快速了解项目

如何避免循环依赖？

检查清单：

✅ 确认引用方向（高层级 → 低层级）
✅ 避免双向引用（A→B 且 B→A）
✅ 使用导航型文档做中介（通过 docs/README.md 导航，而非直接相互引用）

工具：

bash

# 检查潜在循环依赖
bash scripts/check_circular_deps.sh

# 分析文档入度/出度
bash scripts/analyze_indegree.sh

最后更新：2026-01-28 维护者：项目团队反馈：如发现架构问题，请提 Issue 或修改本文档

文档体系架构 ​

📊 依赖关系图 ​

三层入口体系 ​

🎯 依赖关系原则 ​

单向依赖（DAG） ​

依赖分级 ​

📈 文档入度/出度统计 ​

入度（被引用次数） ​

出度（引用其他文档数量） ​

🔍 依赖关系类型 ​

1. 导航依赖（Navigation） ​

2. 引用依赖（Reference） ​

3. 工作流依赖（Workflow） ​

📐 架构设计原则 ​

原则 1：单一入口（Single Entry Point） ​

原则 2：职责分离（Separation of Concerns） ​

原则 3：层级隔离（Layer Isolation） ​

原则 4：权威数据源（Single Source of Truth） ​

🛠️ 维护机制 ​

Git Hooks 自动检查 ​

Claude 自动感知 ​

季度架构审查 ​

📊 架构演进历史 ​

v1.0（2026-01-15）：7层文档体系建立 ​

v1.1（2026-01-23）：文档清理和备份机制 ​

v1.2（2026-01-28）：解决循环依赖 + 三层入口体系 ​

🎯 快速参考 ​

如何选择引用哪个文档？ ​

如何避免循环依赖？ ​

文档体系架构

📊 依赖关系图

三层入口体系

🎯 依赖关系原则

单向依赖（DAG）

依赖分级

📈 文档入度/出度统计

入度（被引用次数）

出度（引用其他文档数量）

🔍 依赖关系类型

1. 导航依赖（Navigation）

2. 引用依赖（Reference）

3. 工作流依赖（Workflow）

📐 架构设计原则

原则 1：单一入口（Single Entry Point）

原则 2：职责分离（Separation of Concerns）

原则 3：层级隔离（Layer Isolation）

原则 4：权威数据源（Single Source of Truth）

🛠️ 维护机制

Git Hooks 自动检查

Claude 自动感知

季度架构审查

📊 架构演进历史

v1.0（2026-01-15）：7层文档体系建立

v1.1（2026-01-23）：文档清理和备份机制

v1.2（2026-01-28）：解决循环依赖 + 三层入口体系

🎯 快速参考

如何选择引用哪个文档？

如何避免循环依赖？