NextEdu/docs/superpowers/specs/2026-07-07-documentation-system-redesign-design.md

# 文档体系重设计

> 日期：2026-07-07
> 状态：待用户审阅
> 范围：全局规范文档（`project_rules.md` / `coding-standards.md` / `004` / `005` / `known-issues.md`）+ 新增架构元数据库 + 模块工作手册
> 唯一源原则：004 为架构设计意图唯一源；arch.db 为代码结构唯一源；known-issues.md 为经验唯一源

---

## 一、设计目标

### 1.1 核心诉求

1. **审核并修正现有规范文档**的合规性、遗漏、技术错误
2. **重新设计文档体系结构**，消除职责重叠，让每份文档只回答一类问题
3. **建立架构元数据库**（arch.db），让 AI 快速查询模块/函数/调用链/依赖关系，无需扫描整个代码库
4. **建立 AI 自我演进机制**，让 AI 越工作越了解项目，后来者可接力而非重新梳理

### 1.2 设计原则

| 原则 | 含义 |
|------|------|
| 单一来源 | 每类信息只有一个权威文档，其他文档引用而非重复 |
| 职责分离 | 每份文档只回答一类问题（What / Why / How / When） |
| 贴近代码 | 模块工作手册放在 `src/modules/[module]/README.md`，与代码同生命周期 |
| 自动优于手动 | 代码结构由扫描器自动生成（arch.db），减少人工维护 |
| 信任但验证 | AI 使用经验前必须审核，文档变更后重新审核 |

### 1.3 不做事项（YAGNI）

- 不建 Monorepo（项目明确为单应用 + 模块化）
- 不引入 Storybook（当前无需求）
- 不建独立文档站点（GitHub/Gitea 直接渲染 Markdown 足够）
- 不做实时热更新架构库（CI + AI 工作前手动触发足够）

---

## 二、文档体系拓扑

### 2.1 整体结构

```
项目根/
├─ .trae/rules/project_rules.md          # 全局硬性规则（强制约束）
├─ docs/
│  ├─ standards/coding-standards.md      # 编码规范（How to write code）
│  ├─ architecture/
│  │  ├─ 004_architecture_impact_map.md  # 架构设计意图（Why - 瘦身后约 500 行）
│  │  ├─ 006_k12_feature_checklist.md    # 功能模块清单（保留）
│  │  ├─ 007_gap_audit_report.md         # 差距审计（保留）
│  │  ├─ 008_module_role_mapping.md      # 模块角色映射（保留）
│  │  ├─ roadmap/                        # 【新增】长远规划
│  │  │  ├─ README.md                    # 路线图索引
│  │  │  ├─ tech-debt.md                 # 技术债清单（从 004 第三部分迁入）
│  │  │  ├─ decoupling.md                # 解耦路线图（从 audit/01 迁入）
│  │  │  └─ pending-features.md          # 待开发功能（从 004 "未完成项"迁入）
│  │  └─ audit/archive/                  # 【新增】历史审查报告归档（只读）
│  │     ├─ 005_architecture_data.json   # 005 废弃后归档于此
│  │     └─ (现有 60+ 份 audit 报告迁入)
│  └─ troubleshooting/
│     └─ known-issues.md                 # 经验库（精简为索引式，无代码示例）
├─ src/modules/[module]/
│  └─ README.md                          # 【新增】模块工作手册（每模块一份）
└─ scripts/arch-scan/                    # 【新增】架构扫描器
   ├─ scanner.ts                         # ts-morph 扫描器
   ├─ schema.ts                          # SQLite schema 定义
   ├─ query.ts                           # 查询函数
   ├─ cli.ts                             # CLI 入口
   └─ arch.db                            # 生成的 SQLite（git 提交）
```

### 2.2 文档职责边界

| 文档 | 类型 | 回答的问题 | 谁维护 | 内容禁区 |
|------|------|-----------|--------|---------|
| `arch.db` | 自动生成 | What（代码结构是什么） | 扫描器 | 无人为语义 |
| `004` 架构图 | 人类可读 | Why（架构为什么这样设计） | 人/AI | 不含代码结构、不含规划、不含教程 |
| `project_rules.md` | 硬性规则 | Must（必须遵守什么） | 人 | 不含详细规范、不含架构描述 |
| `coding-standards.md` | 编码规范 | How to write（怎么写代码） | 人 | 不含架构事实、不含经验 |
| `known-issues.md` | 经验库 | Experience（场景→技术、工作经验） | AI 思考后更新 | 不含代码示例、不含错误示范 |
| `modules/[m]/README.md` | 模块上下文 | How to work（怎么上手模块） | 人/AI | 不重复 arch.db 的代码结构、不含经验 |
| `roadmap/*` | 规划 | When（未来做什么） | 人/AI | 不含架构事实、不含经验 |
| `audit/archive/*` | 历史参考 | Past（过去发现了什么） | 只读归档 | 不再更新 |

### 2.3 三类信息源的互补关系

```
arch.db (What)          ── AI 查询代码结构、调用关系、依赖
  ↓ 基于代码生成
004 架构图 (Why)        ── 人理解架构设计意图
  ↓ 解释决策
模块手册 (How to work)  ── 人/AI 上手模块的工作流程
  ↓ 记录经验
known-issues (Experience) ── 遇到问题时查技术方向
```

### 2.4 废弃文档

| 文档 | 处理 | 理由 |
|------|------|------|
| `005_architecture_data.json` | 废弃，归档到 `audit/archive/` | arch.db 自动生成比手维护 JSON 准确 |
| `docs/architecture/audit/01_decoupling_roadmap.md` | 迁移到 `roadmap/decoupling.md` | 属于规划而非审查报告 |
| `docs/architecture/audit/` 下 60+ 份审查报告 | 迁移到 `audit/archive/`，只读归档 | 历史参考，不再更新 |

---

## 三、arch.db 架构元数据库

### 3.1 设计目标

让 AI 无需扫描整个代码库即可精准查询：
- 某模块的所有导出函数
- 某函数被谁调用（逆向追踪，递归）
- 某函数调用了什么（正向追踪，递归）
- 某模块依赖哪些模块（递归）
- 哪些地方用了某技术（如 cacheFn）
- 架构违规检测（超长文件、Server Action 缺权限校验等）
- 完整调用链（从 UI 到 DB）

### 3.2 技术选型

| 决策 | 选择 | 理由 |
|------|------|------|
| 存储 | SQLite | 嵌入式、零配置、.db 文件可 git 提交、AI 可直接 sqlite3 查询 |
| 扫描器 | ts-morph | TypeScript AST 操作库，支持类型推导，能提取调用关系 |
| 扫描粒度 | 全调用图 | 模块 + 函数 + 类型 + 函数间调用关系，覆盖 UE 引用查看器所有用法 |
| 触发时机 | CI 自动 + 本地手动 + AI 工作前强制 | 三重保障架构库与代码同步 |
| 数据源 | 自动扫描代码 | 零人工维护，与代码同步 |

### 3.3 SQLite Schema

```sql
-- ============ 核心实体 ============

-- 1. 模块（src/modules/* 下的目录）
CREATE TABLE modules (
  id          INTEGER PRIMARY KEY,
  name        TEXT NOT NULL UNIQUE,
  path        TEXT NOT NULL,
  description TEXT,
  layer       TEXT NOT NULL,               -- "modules" | "shared" | "app" | "root"
  created_at  TEXT NOT NULL
);

-- 2. 文件
CREATE TABLE files (
  id         INTEGER PRIMARY KEY,
  module_id  INTEGER REFERENCES modules(id),
  path       TEXT NOT NULL UNIQUE,
  kind       TEXT NOT NULL,                -- "actions" | "data-access" | "schema" | "types" | "component" | "hook" | "lib" | "config" | "route" | "page" | "layout"
  lines      INTEGER,
  is_server  INTEGER DEFAULT 0,
  is_client  INTEGER DEFAULT 0,
  has_server_only INTEGER DEFAULT 0
);

-- 3. 导出符号（函数、类、类型、常量、组件）
CREATE TABLE symbols (
  id          INTEGER PRIMARY KEY,
  file_id     INTEGER NOT NULL REFERENCES files(id),
  name        TEXT NOT NULL,
  kind        TEXT NOT NULL,               -- "function" | "class" | "type" | "interface" | "const" | "component"
  is_exported INTEGER DEFAULT 0,
  is_async    INTEGER DEFAULT 0,
  is_server_action INTEGER DEFAULT 0,
  signature   TEXT,
  start_line  INTEGER,
  end_line    INTEGER,
  UNIQUE(file_id, name, start_line)
);

-- ============ 关系 ============

-- 4. 调用关系（符号间调用）
CREATE TABLE calls (
  id            INTEGER PRIMARY KEY,
  caller_id     INTEGER NOT NULL REFERENCES symbols(id),
  callee_id     INTEGER REFERENCES symbols(id),
  callee_external TEXT,                    -- 项目外调用（如 "fetch", "console.log"）
  call_line     INTEGER,
  count         INTEGER DEFAULT 1
);

-- 5. 文件级导入
CREATE TABLE file_imports (
  id            INTEGER PRIMARY KEY,
  source_file_id INTEGER NOT NULL REFERENCES files(id),
  imported_file_id INTEGER REFERENCES files(id),
  import_path   TEXT NOT NULL,
  is_type_only  INTEGER DEFAULT 0,
  imported_names TEXT
);

-- 6. 模块间依赖（聚合视图）
CREATE TABLE module_deps (
  id            INTEGER PRIMARY KEY,
  source_module_id INTEGER NOT NULL REFERENCES modules(id),
  target_module_id INTEGER NOT NULL REFERENCES modules(id),
  dep_type      TEXT NOT NULL,             -- "import" | "data-access-call" | "action-call"
  UNIQUE(source_module_id, target_module_id, dep_type)
);

-- ============ 业务元数据 ============

-- 7. 技术标签
CREATE TABLE tech_tags (
  id    INTEGER PRIMARY KEY,
  name  TEXT NOT NULL UNIQUE,
  category TEXT
);

-- 8. 符号-技术标签关联
CREATE TABLE symbol_tech_tags (
  symbol_id INTEGER NOT NULL REFERENCES symbols(id),
  tag_id    INTEGER NOT NULL REFERENCES tech_tags(id),
  PRIMARY KEY(symbol_id, tag_id)
);

-- 9. 权限点
CREATE TABLE permissions (
  id          INTEGER PRIMARY KEY,
  key         TEXT NOT NULL UNIQUE,
  description TEXT
);

-- 10. 路由
CREATE TABLE routes (
  id         INTEGER PRIMARY KEY,
  path       TEXT NOT NULL UNIQUE,
  kind       TEXT NOT NULL,                -- "page" | "api" | "layout"
  file_id    INTEGER REFERENCES files(id),
  min_permission TEXT
);

-- 11. 数据库表
CREATE TABLE db_tables (
  id          INTEGER PRIMARY KEY,
  name        TEXT NOT NULL UNIQUE,
  module_id   INTEGER REFERENCES modules(id),
  description TEXT
);

-- ============ 扫描元数据 ============

-- 12. 扫描元数据
CREATE TABLE scan_meta (
  key   TEXT PRIMARY KEY,
  value TEXT NOT NULL
);
```

### 3.4 关键索引

```sql
CREATE INDEX idx_symbols_file ON symbols(file_id);
CREATE INDEX idx_symbols_name ON symbols(name);
CREATE INDEX idx_calls_caller ON calls(caller_id);
CREATE INDEX idx_calls_callee ON calls(callee_id);
CREATE INDEX idx_file_imports_source ON file_imports(source_file_id);
CREATE INDEX idx_file_imports_target ON file_imports(imported_file_id);
CREATE INDEX idx_symbol_tech_tags_tag ON symbol_tech_tags(tag_id);
```

### 3.5 技术标签自动识别规则

扫描器通过启发式规则自动打标签：

| 标签 | 识别规则 | 类别 |
|------|---------|------|
| `cacheFn` | 文件内出现 `cacheFn(` 调用 | cache |
| `zustand` | import 自 `zustand` | state |
| `useOptimistic` | 文件内出现 `useOptimistic` 调用 | state |
| `react-hook-form` | import 自 `react-hook-form` | form |
| `TanStack Query` | import 自 `@tanstack/react-query` | state |
| `Server Action` | 文件顶部 `"use server"` 或函数级 `"use server"` | server |
| `Tiptap` | import 自 `@tiptap/*` | ui |
| `Drizzle` | import 自 `drizzle-orm` | db |
| `nuqs` | import 自 `nuqs` | state |
| `recharts` | import 自 `recharts` | ui |

### 3.6 递归查询能力（6 类）

#### 查询 1：逆向递归（谁调用了 X？递归到入口）

```sql
WITH RECURSIVE upstream(caller_id, caller_name, caller_path, depth, path_chain) AS (
  SELECT c.caller_id, s.name, f.path, 0, s.name
  FROM calls c
  JOIN symbols s ON c.caller_id = s.id
  JOIN files f ON s.file_id = f.id
  WHERE c.callee_id = (SELECT id FROM symbols WHERE name = ? LIMIT 1)
  UNION
  SELECT c.caller_id, s.name, f.path, u.depth + 1, u.path_chain || ' → ' || s.name
  FROM upstream u
  JOIN calls c ON c.callee_id = u.caller_id
  JOIN symbols s ON c.caller_id = s.id
  JOIN files f ON s.file_id = f.id
  WHERE u.depth < 10
    AND u.caller_id NOT IN (SELECT caller_id FROM upstream)
)
SELECT caller_name, caller_path, depth, path_chain FROM upstream
ORDER BY depth, caller_path;
```

#### 查询 2：正向递归（X 调用了什么？递归到叶子）

```sql
WITH RECURSIVE downstream(callee_id, callee_name, callee_path, depth, path_chain) AS (
  SELECT c.callee_id, s.name, f.path, 0, ?
  FROM calls c
  JOIN symbols s ON c.callee_id = s.id
  JOIN files f ON s.file_id = f.id
  WHERE c.caller_id = (SELECT id FROM symbols WHERE name = ? LIMIT 1)
  UNION
  SELECT c.callee_id, s.name, f.path, d.depth + 1, d.path_chain || ' → ' || s.name
  FROM downstream d
  JOIN calls c ON c.caller_id = d.callee_id
  JOIN symbols s ON c.callee_id = s.id
  JOIN files f ON s.file_id = f.id
  WHERE d.depth < 10
    AND d.callee_id NOT IN (SELECT callee_id FROM downstream)
)
SELECT callee_name, callee_path, depth, path_chain FROM downstream
ORDER BY depth, callee_path;
```

#### 查询 3：模块级逆向（谁依赖了模块 X？递归到根）

```sql
WITH RECURSIVE mod_upstream(source_module, target_module, depth, path_chain) AS (
  SELECT m.name, m2.name, 0, m.name || ' ← ' || m2.name
  FROM module_deps md
  JOIN modules m ON md.target_module_id = m.id
  JOIN modules m2 ON md.source_module_id = m2.id
  WHERE m.name = ?
  UNION
  SELECT mu.source_module, m.name, mu.depth + 1, mu.path_chain || ' ← ' || m.name
  FROM mod_upstream mu
  JOIN module_deps md ON md.target_module_id = (
    SELECT id FROM modules WHERE name = mu.source_module
  )
  JOIN modules m ON md.source_module_id = m.id
  WHERE mu.depth < 10
)
SELECT DISTINCT source_module, target_module, depth, path_chain
FROM mod_upstream ORDER BY depth;
```

#### 查询 4：模块级正向（模块 X 依赖了哪些模块？递归到叶子）

类似查询 3，方向反转（从 source_module_id 出发递归 target_module_id）。实施时补全完整 SQL。

#### 查询 5：双向依赖检测（模块 A 和 B 之间是否有循环依赖）

同时执行查询 3（A→B）和查询 4（B→A），若两方向都存在路径，则存在循环依赖。实施时封装为单一查询函数。

#### 查询 6：完整调用链（UI → Server Action → data-access → DB）

```sql
WITH RECURSIVE trace(symbol_id, symbol_name, file_path, kind, depth, path_chain) AS (
  -- 入口：UI 事件处理函数（handle*, onSubmit*, onClick*）
  SELECT s.id, s.name, f.path, f.kind, 0, s.name
  FROM symbols s JOIN files f ON s.file_id = f.id
  WHERE s.name LIKE 'handle%' OR s.name LIKE 'onSubmit%' OR s.name LIKE 'onClick%'
  UNION
  SELECT cs.id, cs.name, cf.path, cf.kind, t.depth + 1, t.path_chain || ' → ' || cs.name
  FROM trace t
  JOIN calls c ON c.caller_id = t.symbol_id
  JOIN symbols cs ON c.callee_id = cs.id
  JOIN files cf ON cs.file_id = cf.id
  WHERE t.depth < 15
    AND t.symbol_id NOT IN (SELECT symbol_id FROM trace)
)
SELECT * FROM trace
WHERE kind IN ('actions', 'data-access')
ORDER BY depth, path_chain;
```

### 3.7 CLI 接口

```bash
# 1. 更新架构库
npm run arch:scan

# 2. 查询命令
npm run arch:query ref <symbolName> [--forward] [--depth=10]    # 符号引用（默认逆向）
npm run arch:query module <moduleName> [--reverse] [--depth=10] # 模块依赖
npm run arch:query tech <techTag>                               # 技术使用
npm run arch:query path <moduleA> <moduleB>                     # 模块间路径
npm run arch:query violations                                   # 架构违规
npm run arch:query trace <entrySymbol>                          # 完整调用链
npm run arch:query sql "<SQL>"                                  # 自由 SQL
npm run arch:query repl                                         # 交互式
```

### 3.8 输出格式

默认输出**树形可视化**（模仿 UE 引用查看器），可选 `--json` 输出机器可读格式：

```
$ npm run arch:query ref createExam

▼ createExam (src/modules/exams/data-access.ts#L42)
  │
  ├─▼ createExamAction (src/modules/exams/actions.ts#L18) [Server Action]
  │  │
  │  └─▼ handleCreateExam (src/modules/exams/components/exam-form.tsx#L67) [Client]
  │     │
  │     └── <Form onSubmit> (src/modules/exams/components/exam-form.tsx#L120)
  │
  └─▼ importExams (src/modules/exams/import-export.ts#L234)
```

---

## 四、AI 自我演进机制

### 4.1 模块 README.md 标准结构

```markdown
# [模块名] 模块工作手册

> 经验查 known-issues.md，代码结构查 arch.db，本文件只记工作流程。

## 模块职责
一句话描述本模块做什么。

## 核心工作流程
1. 新增考试: ...
2. 修改成绩计算: ...

## 关键约束
- [不可违反的约束]
- [依赖关系，从 arch.db 提取]

## 架构决策（为什么这样设计）
- **为什么用 X 而不用 Y**: [决策理由]
```

### 4.2 known-issues.md 结构（唯一经验库）

```markdown
# 项目经验库

> AI 工作前必读，使用经验前必审核。AI 发现更好办法时更新本文件。
> 最后审核: 2026-07-07 14:00 (commit: abc1234)

## 全局经验

### 缓存策略
| 场景 | 技术方向 | 模块 | 备注 |
|------|---------|------|------|
| 服务端数据缓存 | cacheFn + Redis | 全局 | 详见 arch.db tech_tags |
| 客户端数据缓存 | TanStack Query | 全局 | 禁止 useEffect+fetch |

### 状态管理
| 场景 | 技术方向 | 模块 | 备注 |
|------|---------|------|------|
| URL 状态 | nuqs | 全局 | 5 层状态模型 L1 |
| 表单状态 | react-hook-form + zodResolver | 全局 | L5 层 |

## 模块经验: exams

### 考试创建流程
| 场景 | 技术方向 | 备注 |
|------|---------|------|
| 考试数据缓存 | cacheFn 包裹 createExamRaw | 修改后须失效 importExams 缓存 |
| AI 题目解析 | 动态 import + webpackIgnore | 可选依赖 ollama |

## 模块经验: grades
...

## 工作经验日志（按时间倒序，定期提炼到上述分区）

### 2026-07-07 重构 createExam 调用链
- **模块**: exams
- **做了什么**: 拆分 createExam 为 createExamRaw + createExam(含缓存)
- **学到什么**: data-access 层已有 cacheFn，actions 层无需再缓存
- **下次注意**: 修改 createExam 必须同步更新 importExams 的缓存失效
- **审核状态**: 待审核
```

### 4.3 known-issues.md 精简规则

| 内容类型 | 处理 |
|---------|------|
| 代码示例（多行代码块） | 删除，改为"技术方向"描述 |
| 错误示范 | 删除，只保留"正确做法" |
| 重复的架构规则 | 删除，引用 004/project_rules |
| "场景 → 技术"映射 | 保留，按模块分区 |
| 工作经验日志 | 保留（追加区） |

### 4.4 AI 工作强制流程（写入 project_rules.md）

```
AI 进入项目工作流程（强制，违反即违规）:

阶段 1: 上下文加载
  1.1  npm run arch:scan                           # 更新 arch.db
  1.2  npm run arch:query module <目标模块>          # 查模块依赖
  1.3  npm run arch:query ref <目标函数> --forward   # 查调用链
  1.4  阅读 src/modules/[模块]/README.md            # 读模块工作流程
  1.5  查 known-issues.md "模块经验: <模块>" 分区    # 读相关经验
       1.5.1  审核相关经验（检查代码是否仍匹配）
       1.5.2  若文档自上次审核后已变更 → 重新审核并标记
       1.5.3  审核通过 → 使用；失败 → 标记失效，不使用

阶段 2: 执行工作
  2.1  按规划执行
  2.2  修改代码后立即运行 arch:scan

阶段 3: 经验沉淀（强制，不可跳过）
  3.1  在 known-issues.md "工作经验日志" 区追加一条记录:
       - 做了什么
       - 学到什么
       - 下次注意事项
       - 审核状态: 待审核
  3.2  若发现新的"场景→技术"映射 → 提炼到对应模块分区
  3.3  若发现新的架构决策 → 更新 004
  3.4  若代码结构变化 → arch:scan 确认 arch.db 已更新

阶段 4: 提交后审核（人工）
  4.1  人工审查"待审核"日志条目
  4.2  通过 → 标记"已审核 (commit, 审核人)"
  4.3  失败 → 标记"审核失败，原因:..."
  4.4  定期（如每两周）将成熟日志提炼到分区表格
```

### 4.5 信任但验证机制

```
AI 读取 known-issues.md 经验
  ↓
检查该条经验的"审核状态":
  ├─ 已审核 → 检查代码是否仍匹配
  │   ├─ 匹配 → 使用经验
  │   └─ 不匹配 → 标记"待重新审核"，不使用
  ├─ 待审核 → 标记"AI 使用前审核"，验证后使用
  └─ 审核失败 → 不使用，记录原因
  ↓
使用经验工作时，若发现经验有误 → 标记"审核失败，原因:..."
```

### 4.6 防 known-issues.md 膨胀

- **工作经验日志区上限 50 条**——超过则人工提炼最早的到分区表格，删除原日志
- **分区表格无上限**——但每条保持单行索引式
- **精简目标**：从 1317 行降至约 300 行

---

## 五、004 瘦身方案

### 5.1 现状问题

004 当前 4227 行，远超架构文档应有体量。主要问题：

| 问题 | 表现 | 行数估算 |
|------|------|---------|
| 混入工作日志 | "1.1.1 M7 移动端 PWA 支持（2026-07-01 新增）"等 7 个变更日志章节 | ~400 行 |
| 混入规划/待办 | "未完成项（待后续专项）"、各模块的 P0/P1/P2 修复标记 | ~600 行 |
| 混入实现细节 | 函数签名索引、文件行数表格、组件清单 | ~1500 行 |
| 模块清单冗长 | 27 个模块每个都用大段文字描述，含"V4 P2-4 已修复"等历史 | ~1500 行 |
| 真正的架构内容 | 分层图、依赖关系图、数据流向图、核心原则 | ~227 行 |

### 5.2 瘦身后目标结构（约 500 行）

```markdown
# Next_Edu 架构影响地图

> 唯一源：项目架构事实。代码结构查 arch.db，经验查 known-issues.md，规划查 roadmap/。

## 1. 分层架构
- 三层架构图（app → modules → shared）
- 分层规则（4 条核心约束）
- 根模块说明（auth.ts, proxy.ts）

## 2. 模块清单
（表格形式，每模块一行，详情查 arch.db 和模块 README）

| 模块 | 职责 | 核心依赖 | 被依赖 | README |
|------|------|---------|--------|--------|
| exams | 考试管理 | grades, classes, questions | dashboard | [README](../../src/modules/exams/README.md) |
| ... | ... | ... | ... | ... |

## 3. 模块依赖关系图
- 核心业务模块依赖图
- 扩展模块依赖图
- （循环依赖检测见 arch.db 查询）

## 4. 数据流向（核心场景）
- 考试流程数据流
- 学生提交作业数据流
- 仪表盘聚合数据流

## 5. 核心架构原则
- 三层架构单向依赖
- 模块间通过 data-access 通信
- Server Action 必须权限校验
- 设计令牌分层（Primitive → Semantic → Tailwind）

## 6. 设计令牌体系
- 文件分布（src/app/styles/tokens/）
- 令牌分层规则
- 强制约束（禁止硬编码颜色/字体/字号）

## 相关文档
- [arch.db 查询](../../scripts/arch-scan/) - 代码结构
- [known-issues.md](../troubleshooting/known-issues.md) - 经验库
- [roadmap/](./roadmap/) - 规划
- [模块 README](../../src/modules/) - 模块工作流程
```

### 5.3 迁移映射

| 004 现有内容 | 去向 | 理由 |
|------------|------|------|
| 1.1.1-1.1.7 变更日志章节 | 删除（git 历史已记录） | 工作日志不属于架构事实 |
| "Phase X.X 新增"标记 | 删除 | 同上 |
| "P0-X 已修复"标记 | 删除（保留事实，删除修复历史） | 修复历史属于 git log |
| "未完成项（待后续专项）" | 迁移到 `roadmap/tech-debt.md` | 属于规划 |
| 各模块的"V1/V2/V3/V4"版本描述 | 删除，只保留当前状态 | 版本演进属于 git log |
| 函数签名索引（附录 C） | 删除（查 arch.db） | 代码结构属于 arch.db |
| 模块间依赖矩阵（附录 A） | 删除（查 arch.db `module_deps`） | 同上 |
| 关键参数影响链（附录 B） | 保留（架构决策） | 属于架构意图 |
| 第三部分"已知架构问题和技术债" | 迁移到 `roadmap/tech-debt.md` | 属于规划 |
| 模块清单（第二部分） | 大幅精简为表格 | 详情查 arch.db + README |

---

## 六、规范文档修正要点

### 6.1 已发现的跨文档冲突

| 冲突项 | project_rules.md | coding-standards.md | 004 | 修正方向 |
|--------|-----------------|---------------------|-----|---------|
| 设计令牌位置 | `src/app/styles/tokens/` | `globals.css` | `src/app/styles/tokens/` | 统一为 `src/app/styles/tokens/`（以 004 为准） |
| 架构文档清单 | 仅列 004-008 + audit/01 | 无 | 自身 | project_rules.md 补全 001/002/003/008 |
| 002 编号冲突 | 无 | 无 | 无 | `002_rbac_refactoring.md` 与 `002_role_based_routing.md` 编号冲突，需重命名 |
| 缓存策略描述 | 无 | "用 unstable_cache" | 已迁移到 cacheFn | coding-standards.md 更新为 cacheFn |

### 6.2 project_rules.md 修正

1. **架构文档清单补全**：加入 001/002/003/008
2. **新增 AI 工作流程规则**：写入第四节"AI 工作强制流程"
3. **新增 arch.db 规则**：AI 工作前必须 `npm run arch:scan`
4. **令牌位置统一**：与 004 一致，明确为 `src/app/styles/tokens/`

### 6.3 coding-standards.md 修正

1. **令牌位置统一**：从 `globals.css` 改为 `src/app/styles/tokens/`
2. **缓存策略更新**：从 `unstable_cache` 改为 `cacheFn`
3. **删除过时内容**：tsconfig "当前差异"部分（已升级则删除，未升级则列入 roadmap）
4. **状态管理章节更新**：加入 5 层状态模型（L1 URL / L2 Server / L3 Client Business / L4 Global UI / L5 Form）
5. **ESLint 配置章节更新**：反映已实现的 `no-restricted-syntax`、`design-tokens/no-hardcoded-fonts` 等规则

---

## 七、实施阶段划分

### 7.1 三阶段流水线

| 阶段 | 目标 | 产出 | 验收标准 |
|------|------|------|---------|
| 阶段 1: 同步实际 | 把 4 份文档对齐到代码现状 | 实际状态基线报告 | 4 份文档与代码零冲突 |
| 阶段 2: 审核正确性 | 基于阶段 1 基线，按 4 维度审核文档 | 问题清单 + 修正建议 | 文档内部一致、无技术错误、无遗漏、对齐大仓最佳实践 |
| 阶段 3: 反向修正代码 | 基于阶段 2 审核后文档，修正代码偏差 | 代码修正 PR | 代码与文档零冲突 |

### 7.2 阶段 1 任务分解

1. 扫描代码实际状态（令牌位置、模块结构、tsconfig、Husky/lint-staged 是否配置等）
2. 对照 4 份文档找出不一致项
3. 修正文档使其与代码一致
4. 产出"实际状态基线报告"

### 7.3 阶段 2 任务分解

按 4 维度审核：
1. **合规性**：文档内部一致性、跨文档一致性
2. **遗漏**：对照大仓最佳实践找缺失规则（包边界、依赖方向、共享工具下沉）
3. **技术错误**：tsconfig 目标版本、令牌位置、ESLint 规则等具体错误
4. **大仓规范对照**：提取适用于单应用模块化的部分

### 7.4 阶段 3 任务分解

1. 识别代码与审核后文档的偏差
2. 修正代码（如 tsconfig 升级、令牌位置迁移等）
3. 验证 `npm run lint` 和 `npx tsc --noEmit` 零错误

### 7.5 独立项目：arch.db 扫描器

arch.db 扫描器作为独立项目，可与三阶段并行推进：

1. 实现 ts-morph 扫描器（scanner.ts）
2. 实现 SQLite schema（schema.ts）
3. 实现查询函数（query.ts）
4. 实现 CLI（cli.ts）
5. 添加 `npm run arch:scan` 和 `npm run arch:query` 脚本
6. 配置 CI 自动运行
7. 写入 project_rules.md 作为 AI 工作前置规则

### 7.6 独立项目：模块 README 创建

约 27 个模块各创建一份 README.md（实施时以 arch.db 扫描结果为准），可分批推进：

1. 标杆模块先做（textbooks、grades 已在 004 标记为"标杆模块"）
2. 核心业务模块（exams、homework、questions）
3. 教学管理模块（classes、school、scheduling、attendance）
4. 用户沟通模块（users、messaging、notifications、parent）
5. 扩展功能模块（elective、proctoring、diagnostic、dashboard）
6. 其他模块（announcements、files、settings、auth、layout、student、lesson-preparation、standards、course-plans、audit、rbac、onboarding）

---

## 八、验收标准

### 8.1 文档体系验收

- [ ] 4 份全局规范文档（project_rules.md / coding-standards.md / 004 / known-issues.md）内部无矛盾
- [ ] 4 份文档与代码零冲突
- [ ] 004 瘦身至约 500 行，不含规划/工作日志/代码结构
- [ ] 005 归档到 audit/archive/
- [ ] known-issues.md 精简至约 300 行，无代码示例
- [ ] roadmap/ 目录建立，包含 tech-debt.md / decoupling.md / pending-features.md
- [ ] audit/archive/ 目录建立，60+ 份审查报告归档

### 8.2 arch.db 验收

- [ ] `npm run arch:scan` 能成功扫描全项目并生成 arch.db
- [ ] `npm run arch:query ref <symbol>` 能递归查询符号引用
- [ ] `npm run arch:query module <module>` 能递归查询模块依赖
- [ ] `npm run arch:query tech <tag>` 能查询技术使用
- [ ] `npm run arch:query violations` 能检测架构违规
- [ ] arch.db 与代码零偏差（扫描器在干净代码上运行无错误）

### 8.3 模块 README 验收

- [ ] 27 个模块各有 README.md
- [ ] 每个 README 含：模块职责、核心工作流程、关键约束、架构决策
- [ ] 每个 README 不含经验（查 known-issues.md）、不含代码结构（查 arch.db）

### 8.4 AI 工作流程验收

- [ ] project_rules.md 写入 AI 工作强制流程
- [ ] AI 工作前运行 `npm run arch:scan` 成为硬性规则
- [ ] known-issues.md 含审核状态字段
- [ ] 模块 README 含审核标记

---

## 九、风险与缓解

| 风险 | 影响 | 缓解 |
|------|------|------|
| ts-morph 扫描大型项目慢 | CI 时间增加 | 扫描器增量扫描（仅变更文件），全量扫描仅 CI 触发 |
| arch.db 二进制文件 git diff 不友好 | Code review 难 | 配合导出 SQL 文本文件，diff 看 SQL，应用看 .db |
| 模块 README 维护成本 | AI/人遗忘更新 | project_rules.md 强制 AI 工作后更新；CI 检查 README 格式 |
| known-issues.md 日志区膨胀 | 文件过大 | 50 条上限，定期提炼到分区表格 |
| 60+ 份 audit 报告归档后信息丢失 | 历史经验丢失 | 归档前提取有价值内容到模块 README 和 known-issues.md |
| AI 不遵守工作流程 | 文档体系失效 | project_rules.md 写为硬性规则，CI 检查 arch.db 是否更新 |

---

## 十、未决事项

本 spec 已涵盖所有用户确认的决策。以下事项在实施阶段可能需要进一步决策：

1. **ts-morph 扫描器性能**：若全量扫描超过 30 秒，需考虑增量扫描策略
2. **arch.db 大小**：若超过 10MB，需考虑是否排除部分表（如 calls 表可能很大）
3. **模块 README 模板**：实施时可能需要根据实际模块调整模板
4. **技术标签体系扩展**：初始 10 个标签可能不够，实施时根据需要扩展