Codebase Context

find {projectRoot}/src -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.vue" -o -name "*.json" \) -newer {DOC_DIR}/.scan-meta.json

✅ codebase-context 增量扫描完成 — {project-name}
🔍 变更检测: 新增 {N} 个 | 修改 {N} 个 | 删除 {N} 个
📄 已更新文档: {文档列表，如 04-api-routes、05-data-models、09-changelog、00-index}

📚 已加载 {project-name} 参考文档（{实际数量} 份，覆盖 {相关模块}，最后更新 {日期}）
📌 项目概要: {已核实的一句话或待核实}

# {project-name} — 代码库参考文档索引

- 最后更新: {YYYY-MM-DD HH:MM UTC}
- 扫描类型: {full | incremental}
- 项目根: {projectRoot}

## 文档导航

| 文档 | 内容 | 什么时候看 |
| ---- | ---- | ---- |
| 01-overview | 项目概述与技术栈 | 初次接触项目 |
| 02-directory | 目录结构 | 找文件放哪/在哪 |
| 03-architecture | 架构与模块关系 | 新代码归属、理解依赖方向 |
| 04-api-routes | API 接口汇总 | 调接口前查重 |
| 05-data-models | 数据模型与类型 | 定义类型前查重 |
| 06-core-modules | 组件/Hooks/Store | 写组件前查复用 |
| 07-business-logic | 关键业务逻辑 | 改业务流程前看线路 |
| 08-conventions | 编码规范与约定 | 动手写代码前 |
| 09-changelog | 文档变更记录 | 追溯文档演进 |

## 快速定位

| 我想找… | 去 |
| ---- | ---- |
| 某个接口怎么调 | 04-api-routes |
| 某个字段的类型定义 | 05-data-models |
| 有没有现成组件/Hook | 06-core-modules |
| 某业务流程的完整线路 | 07-business-logic |
| 命名/风格规矩 | 08-conventions |

# 项目概述与技术栈

## 项目定位

{一句话说明这个项目是什么、给谁用、解决什么问题}

## 技术栈

| 层 | 技术 | 版本 |
| ---- | ---- | ---- |
| 语言 | {TypeScript/…} | {x.y} |
| 框架 | {React/Vue/…} | {x.y} |
| 构建 | {Vite/Webpack/…} | {x.y} |
| 状态管理 | {…} | {x.y} |
| 其他关键依赖 | {…} | {x.y} |

## 脚本命令

| 命令 | 作用 |
| ---- | ---- |
| `npm run dev` | {…} |
| `npm run build` | {…} |
| `npm run test` | {…} |

## 环境变量（仅键名与用途，不含值）

| 键 | 用途 | 来源 |
| ---- | ---- | ---- |
| {ENV_KEY} | {…} | .env.example |

# 目录结构

## 目录树（src 两层）

```text
src/
├── pages/          # {职责}
├── components/     # {职责}
├── api/            # {职责}
├── store/          # {职责}
├── hooks/          # {职责}
├── utils/          # {职责}
└── types/          # {职责}
```

## 目录职责

| 目录 | 职责 | 典型文件 |
| ---- | ---- | ---- |
| {src/pages} | {…} | {…} |

## 文件清单（供增量扫描对比新增/删除）

| 文件 | 所属轮次 |
| ---- | ---- |
| {src/api/user.ts} | 4 |

# 架构设计与模块关系

## 分层结构

```text
{页面层 pages}
    ↓ 调用
{逻辑层 hooks / store}
    ↓ 调用
{服务层 api / services}
    ↓ 请求
{后端 / 云函数}
```

## 启动链路

{main.* → App.* → 路由挂载 → 全局 store 初始化，逐步说明，每步带 文件:位置}

## 路由表

| 路径 | 页面 | 定义位置 |
| ---- | ---- | ---- |
| {/home} | {pages/home} | {router/index.ts} |

## 模块依赖关系

| 模块 | 依赖谁 | 被谁依赖 |
| ---- | ---- | ---- |
| {store/user} | {api/user} | {pages/*, hooks/useAuth} |

# API 接口汇总

## {模块名，如 user}

| 函数名 | 方法 | URL | 参数 | 返回类型 | 定义位置 |
| ---- | ---- | ---- | ---- | ---- | ---- |
| {getUser} | GET | {/api/user/:id} | {id: string} | {User} | {src/api/user.ts} |

（按模块分节重复上表；无 api/ 与 services/ 目录时填"本项目未发现此类文件"）

# 数据模型与类型

## 实体

| 名称 | 字段摘要 | 定义位置 | 主要使用方 |
| ---- | ---- | ---- | ---- |
| {User} | {id, name, role…} | {src/types/user.ts} | {api/user, store/user} |

## 枚举

| 名称 | 取值 | 定义位置 |
| ---- | ---- | ---- |
| {OrderStatus} | {pending/paid/closed} | {src/types/order.ts} |

## DTO / 请求响应类型

| 名称 | 用于接口 | 定义位置 |
| ---- | ---- | ---- |
| {CreateOrderReq} | {POST /api/order} | {src/types/dto.ts} |

# 核心模块

## 公共组件

| 组件 | Props 摘要 | 定义位置 | 复用场景 |
| ---- | ---- | ---- | ---- |
| {Button} | {type, onClick…} | {src/components/common/} | {全局} |

## 业务组件

| 组件 | 职责 | 定义位置 | 所属业务 |
| ---- | ---- | ---- | ---- |

## Hooks

| 名称 | 输入 | 输出 | 定义位置 |
| ---- | ---- | ---- | ---- |
| {useAuth} | {—} | {user, login, logout} | {src/hooks/useAuth.ts} |

## Store

| 模块 | state 摘要 | 主要 actions | 定义位置 |
| ---- | ---- | ---- | ---- |

## 复杂页面精读（3–5 个）

### {页面名}（{文件路径}）

- 职责: {…}
- 关键状态: {…}
- 关键流程: {步骤 1 → 步骤 2 → …，每步带函数名}

# 关键业务逻辑

## {业务线名，如：下单}

**线路**：{页面 pages/order} → {hook useOrder} → {api createOrder} → {POST /api/order} → {模型 Order}
（每个环节标注 文件:函数）

**关键规则**：

- {规则 1，如：金额用分存储，展示层才转元 —— src/utils/money.ts}
- {规则 2}

**边界与注意**：

- {已知坑/特殊分支/兼容逻辑，带位置}

（按业务线重复本节）

# 编码规范与约定

## 命名

| 对象 | 规则 | 示例 |
| ---- | ---- | ---- |
| 组件文件 | {PascalCase} | {UserCard.tsx} |
| hooks | {use 前缀} | {useAuth} |

## 代码风格（自 ESLint/Prettier 推断）

- {缩进/引号/分号/import 排序 等要点}

## 常量

| 常量 | 值/含义 | 定义位置 |
| ---- | ---- | ---- |

## 工具函数

| 函数 | 用途 | 定义位置 |
| ---- | ---- | ---- |

## 其他约定

- {错误处理方式/请求封装规则/目录放置约定}

# 文档变更记录

| 日期(UTC) | 类型 | 变更摘要 | 涉及文档 |
| ---- | ---- | ---- | ---- |
| {2026-07-14T08:00Z} | full | 首次全量扫描 | 全部 10 份 |
| {…} | incremental | {新增 2 接口/修改 1 类型} | {04、05} |
| {…} | dev回写 | {开发 xx 功能后回写} | {04、06、07} |