# Phase 4: 数据流追踪指南

**执行时间**：约 1-2 分钟

**目标**：追踪核心数据的转换链路

---

## ⚠️ 重要约束

**在调用 Task tool 时，必须在 prompt 开头包含以下约束：**

```
⚠️ 重要约束：本次分析只返回文本结果，禁止生成任何文件（.md, .txt 等）。
所有 Mermaid 图表、数据模型清单、转换链路都应包含在你的文本回复中，不要使用 Write 或其他文件创建工具。
```

**Explore agent 只返回文本结果，不要生成任何文件。**

---

## 分析步骤

### 步骤 1: 识别核心数据模型

使用 Grep 工具搜索数据模型定义：

#### Python 项目

```bash
# Pydantic 模型
grep -r "class.*BaseModel" --include="*.py"

# Dataclass
grep -r "@dataclass" --include="*.py"

# SQLAlchemy 模型
grep -r "class.*Base" --include="*.py"
```

#### TypeScript 项目

```bash
# Interface 定义
grep -r "interface.*{" --include="*.ts"

# Type 别名
grep -r "type.*=" --include="*.ts"

# Class 定义
grep -r "export class" --include="*.ts"
```

#### Go 项目

```bash
# Struct 定义
grep -r "type.*struct" --include="*.go"
```

### 步骤 2: 追踪数据转换

1. **定位数据入口**
   - 从 API 端点的请求体开始
   - 识别请求参数的类型定义

2. **追踪转换链路**
   - 读取每个业务函数的参数类型和返回值类型
   - 记录每次类型转换的代码位置
   - 识别数据验证、清洗、增强步骤

3. **标注关键转换点**
   - 序列化/反序列化
   - 数据库 ORM 映射
   - DTO（Data Transfer Object）转换
   - 业务逻辑处理

### 步骤 3: 生成序列图

使用 `assets/sequence.mermaid` 模板生成 Mermaid 序列图。

**⚠️ sequenceDiagram 语法约束（版本 11.x）**：
- `alt/loop/par` 块必须正确配对 `end`
- 使用 `<br/>` 换行

---

## 预期输出格式

### 1. Mermaid 序列图

```mermaid
sequenceDiagram
    participant U as 用户
    participant F as Frontend
    participant B as Backend
    participant R as Researcher
    participant W as Writer

    U->>F: 输入查询 "AI 发展趋势"
    F->>B: POST /api/research<br/>{query, depth: 3}
    Note over B: 构造 ResearchTask
    B->>R: invoke(ResearchTask)
    R->>R: 搜索引擎调用
    R-->>B: SearchResults (10 个文档)
    B->>W: 传递 SearchResults
    W->>W: GPT-4 生成报告
    W-->>B: Report (2000 字)
    B->>F: 返回 HTML
    F->>U: 展示报告
```

### 2. 数据模型清单

列出所有核心数据模型及其位置：

```
核心数据模型:
1. ResearchTask (models/task.py:8)
   - 用途: 用户查询任务
   - 字段: query: str, depth: int, filters: Optional[List[str]]

2. SearchResults (models/results.py:15)
   - 用途: 搜索结果集合
   - 字段: documents: List[Document], total: int, timestamp: datetime

3. Report (models/report.py:22)
   - 用途: 最终生成的报告
   - 字段: content: str, score: float, metadata: Dict[str, Any]
```

### 3. 数据转换链路

```
数据流转路径:
用户输入 (str)
  → ResearchTask (构造于 backend/routes.py:42)
  → SearchResults (返回于 agents/researcher.py:67)
  → Report (生成于 agents/writer.py:89)
  → HTML (渲染于 backend/routes.py:58)
  → 前端展示
```

---

## 分析技巧

### 1. 类型提示追踪

Python 示例：
```python
# 从函数签名追踪类型流转
def process_query(task: ResearchTask) -> SearchResults:
    # task 类型: ResearchTask
    results = search_engine.search(task.query)
    # results 类型: SearchResults
    return results
```

TypeScript 示例：
```typescript
// 从接口定义追踪
interface ApiRequest {
  query: string;
  depth: number;
}

async function handleRequest(req: ApiRequest): Promise<Report> {
  // req 类型: ApiRequest
  const results = await research(req);
  // results 类型: Report
  return results;
}
```

### 2. ORM 映射识别

SQLAlchemy 示例：
```python
# 数据库模型 → Pydantic 模型
class UserDB(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True)

class UserSchema(BaseModel):
    id: int
    # 从 UserDB 转换到 UserSchema
```

### 3. DTO 转换模式

```python
# 请求 DTO → 领域对象 → 响应 DTO
RequestDTO → DomainModel → ResponseDTO
```

---

## 注意事项

1. **关注核心路径**：只追踪主要业务流程的数据转换，忽略辅助功能
2. **最多 5 层深度**：避免追踪过深导致图表过于复杂
3. **标注转换位置**：每次类型转换都记录文件名和行号
4. **区分同步/异步**：在序列图中用实线（同步）和虚线（异步）区分