# 设计文档分析指南

Phase 1 使用本文档指导项目设计文档的搜索、分析和信息提取。

---

## 文档搜索策略

按优先级搜索以下位置：

### 第一梯队：专用设计文档

| 文件/目录 | 典型内容 |
|-----------|----------|
| `ARCHITECTURE.md` | 系统架构、模块划分、设计决策 |
| `DESIGN.md` | 设计规范、接口约定 |
| `docs/architecture/` | 架构图、组件关系 |
| `docs/design/` | 设计文档集合 |
| `docs/adr/` | 架构决策记录 (Architecture Decision Records) |
| `CONTRIBUTING.md` | 项目规范、模块说明 |

### 第二梯队：项目配置

| 文件 | 可提取的信息 |
|------|-------------|
| `README.md` | 项目目标、功能概述、使用方式 |
| `package.json` | 依赖关系、脚本定义、项目描述 |
| `go.mod` | 模块名、依赖 |
| `pyproject.toml` | 项目元信息、依赖 |
| `Makefile` / `Taskfile` | 构建流程、可用命令 |
| `docker-compose.yml` | 服务依赖、外部系统 |
| `.env.example` | 环境依赖、外部服务配置 |

### 第三梯队：API 定义

| 文件 | 可提取的信息 |
|------|-------------|
| `openapi.yaml` / `swagger.json` | API 端点、请求/响应格式、业务规则 |
| `*.proto` | gRPC 服务定义、消息结构 |
| `schema.graphql` | GraphQL 类型、查询、变更 |
| `*.thrift` | Thrift 服务定义 |

### 第四梯队：代码推断

当没有任何文档时，从代码结构推断：

| 来源 | 推断方法 |
|------|----------|
| 目录结构 | 顶级目录名 → 模块划分 |
| import/require 图 | 模块间依赖关系 |
| main/entry 文件 | 启动流程、核心初始化 |
| 路由定义 | API 端点、功能入口 |
| 数据库 migration | 数据模型、业务实体 |
| 已有测试 | 预期行为、边界条件 |

---

## 信息提取框架

从找到的文档中提取以下五类信息：

### 1. 项目目标和核心功能

需要回答的问题：
- 这个项目解决什么问题？
- 核心用户是谁？
- 关键的用户操作是什么？

提取来源：README 的开头段落、项目描述字段。

### 2. 模块划分和职责

需要回答的问题：
- 有哪些主要模块/包/服务？
- 每个模块的核心职责是什么？
- 模块之间的依赖方向是什么？

提取来源：ARCHITECTURE.md、目录结构、import 关系。

输出格式：

```markdown
| 模块 | 职责 | 对外接口 | 依赖 |
|------|------|----------|------|
| auth | 用户认证和授权 | AuthService | db, cache |
| orders | 订单管理 | OrderService | auth, db, payment |
```

### 3. 核心数据流

需要回答的问题：
- 数据从哪里进入系统？
- 经过哪些处理步骤？
- 最终输出到哪里？

提取来源：架构图、API 定义、路由文件、main 函数。

用文字描述主要数据流，例如：

```
HTTP Request → Router → Controller → Service → Repository → Database
                                        ↓
                                   Event Bus → Notification Service → Email/Push
```

### 4. 外部依赖

需要回答的问题：
- 系统依赖哪些外部服务？
- 哪些是可替换的（有接口抽象），哪些是硬编码的？
- 外部依赖的失败模式是什么？

提取来源：docker-compose.yml、.env.example、import 语句、配置文件。

输出格式：

```markdown
| 依赖 | 类型 | 用途 | 是否有接口抽象 |
|------|------|------|----------------|
| PostgreSQL | 数据库 | 主数据存储 | 是 (Repository 接口) |
| Redis | 缓存 | 会话和缓存 | 否 (直接调用 client) |
| Stripe API | 第三方 | 支付处理 | 是 (PaymentGateway 接口) |
```

### 5. 业务规则和约束

需要回答的问题：
- 有哪些显式的业务规则（验证、权限、状态机等）？
- 有哪些隐式的约束（性能要求、一致性保证等）？

提取来源：文档中的规则描述、验证函数、状态枚举、错误定义。

---

## 无文档时的降级分析

当项目没有任何设计文档时，按以下步骤进行降级分析：

### Step 1: 目录结构推断

```bash
# 查看顶级结构
ls -la
# 查看源码组织
find src/ -type d -maxdepth 3  # 或对应的源码根目录
```

常见目录模式：

| 模式 | 含义 |
|------|------|
| `cmd/ + internal/ + pkg/` | Go 标准布局 |
| `src/controllers/ + src/models/ + src/services/` | MVC 架构 |
| `src/features/ + src/shared/` | 功能切片架构 |
| `packages/` | Monorepo |
| `app/ + lib/ + config/` | Rails 风格 |

### Step 2: 入口文件分析

找到程序入口（main、index、app），理解启动流程和顶层组织。

### Step 3: 依赖图构建

从 import/require 语句构建模块间依赖关系，识别核心模块和边缘模块。

### Step 4: 诚实标注信息来源

在产出的摘要中，明确标注每条信息的来源：

```markdown
### 模块划分
| 模块 | 职责 | 信息来源 |
|------|------|----------|
| auth | 用户认证 | 推断自目录结构和导出函数 |
| orders | 订单管理 | 推断自路由定义 |
```

---

## 产出模板

```markdown
## 项目理解摘要

### 项目类型
[Web 应用 / API 服务 / CLI 工具 / 库 / 混合]

### 项目目标
[一句话描述项目解决的核心问题]

### 技术栈
- 语言: [...]
- 框架: [...]
- 数据库: [...]
- 其他: [...]

### 模块划分
| 模块 | 职责 | 对外接口 | 依赖 | 信息来源 |
|------|------|----------|------|----------|

### 核心数据流
[文字或简图描述]

### 外部依赖
| 依赖 | 类型 | 用途 | 是否有接口抽象 |
|------|------|------|----------------|

### 业务规则与约束
1. [规则 1]
2. [规则 2]

### 信息缺失项
[列出无法从文档中获取、需要向用户确认的信息]
```