项目理解skill-v1

codebase_architecture_analyzer_v1/reference/data-flow-analysis.md

@@ -0,0 +1,204 @@
+# 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. **区分同步/异步**：在序列图中用实线（同步）和虚线（异步）区分