Module Analyzer Generate Doc

Java/Maven single-module deep documentation generator. Generates L3(file-level) to L2(module-level) business logic docs for specified module. Supports multi-subagent parallel processing, context compression, checkpoint resume, and auto-retry.

# Module Analyzer Generate Doc - Java 单模块深度文档生成器

> 专注于单个 Java/Maven 模块的深度业务逻辑分析 - 让 AI 全面理解模块的每个细节

## 核心特性

**单模块深度分析**:
- 专注于单个模块的完整扫描（而非整个项目）
- L3 文件级文档：每个包含业务逻辑的类生成详细业务解释
- L2 模块级文档：模块架构索引、核心业务流程、依赖关系汇总

**智能任务执行**:
- 多子代理并行分片处理（默认 5 个并行，每片 10-16 个文件）
- 上下文自动压缩（每处理 2-3 个文件压缩一次）
- 失败自动重试（最多 3 次，指数退避）
- 断点续传支持（状态文件记录进度）
- 进度定时汇报（每 20 分钟）

**文档质量保证**:
- 纯自然语言业务描述（无代码片段）
- 方法级别流程分析（触发条件、数据处理、业务规则、异常处理）
- 领域知识解释（业务概念、术语说明）
- 设计意图说明（为什么这样设计，解决什么问题）

**智能跳过机制**:
- 纯数据对象（Entity/DTO/VO，仅 getter/setter）→ 跳过
- 枚举定义（无复杂逻辑）→ 跳过
- 简单参数对象 → 跳过
- 测试类 → 跳过
- 接口定义（业务逻辑在 Impl 中）→ 跳过

---

## 激活条件

当用户提到以下关键词时激活：
- "分析这个模块"
- "生成模块文档"
- "扫描 admin-api 模块"
- "为 xxx 模块生成源码解析"
- "理解这个模块的业务逻辑"
- "模块级文档索引"
- "Java 模块分析"
- "单模块深度分析"

**与 project-analyzer-generate-doc 的区别**:
- `project-analyzer-generate-doc`：全项目多模块扫描，生成 L3→L2→L1 三层文档
- `module-analyzer-generate-doc`：单模块深度扫描，生成 L3→L2 两层文档（更详细、更快速）

---

## 完整工作流程

### Step 0: 模块扫描与规划

```powershell
# 1. 扫描模块目录结构
Get-ChildItem "<模块路径>" -Directory -Recurse | Where-Object { $_.Name -notmatch 'target|\.git|build' }

# 2. 统计 Java 文件
$javaFiles = Get-ChildItem "<模块路径>/src/main/java" -Include *.java -Recurse | Where-Object { $_.FullName -notmatch '\\test\\' }

# 3. 统计 XML 文件（MyBatis Mapper）
$xmlFiles = Get-ChildItem "<模块路径>/src/main/resources" -Include *.xml -Recurse | Where-Object { $_.Name -match 'mapper|Mapper' }

# 4. 检查已存在文档
$existingDocs = Get-ChildItem "<项目根目录>/.ai-doc/<模块名>" -Include *.md -Recurse 2>$null

# 5. 制定分片计划
# - <20 文件：单子代理
# - 20-50 文件：3-4 个子代理分片
# - >50 文件：5-6 个子代理分片，每片 10-16 个文件
```

**输出**: 文件列表 + 分片计划 + 已存在文档检查

---

### Step 0.5: 已存在文档处理

**目的**: 检查已存在的文档是否符合要求，按需迁移或更新

```markdown
检查规则:
1. 文档路径是否符合 `.ai-doc/模块名/src/main/java/包路径/类名.java.md` 规则
2. 文档内容是否包含详细业务逻辑描述（非简单解释）
3. 文档是否包含代码片段（应全部为自然语言）

处理策略:
- 路径不符合 → 迁移到正确位置
- 内容过于简单 → 重新生成
- 内容符合要求 → 保留，不重复生成
- 源码已变更 → 更新文档
```

---

### Step 0.6: 识别低质量文档（仅报告，需用户确认）

**目的**: 识别不符合要求的文档，**仅生成报告，不自动删除**

```powershell
# 1. 识别低质量文档（只有模板框架，无实际业务内容）
$lowQualityDocs = Get-ChildItem "<项目根目录>/.ai-doc/<模块名>" -Include *.md -Recurse | Where-Object {
    $content = Get-Content $_.FullName -Raw
    $lineCount = (Get-Content $_.FullName).Count
    # 行数少于 20 行
    $lineCount -lt 20 -or
    # 只包含模板框架文字
    $content -match 'Business component - participates in system business processing' -or
    $content -match 'Executes business logic based on specific scenario' -or
    $content -match 'Simple data object' -or
    $content -match 'Interface definition - declares contract specification'
}
# 输出报告，供用户决定是否处理
foreach ($doc in $lowQualityDocs) {
    Write-Host "低质量文档：$($doc.FullName)"
}

# 2. 识别空文件夹（供用户参考）
Get-ChildItem "<项目根目录>/.ai-doc/<模块名>" -Directory -Recurse | ForEach-Object {
    if ((Get-ChildItem $_.FullName -Force).Count -eq 0) {
        Write-Host "空目录：$($_.FullName)"
    }
}
```

**⚠️ 重要安全约束**:
- 此步骤**仅生成报告**，绝不自动删除任何文件
- 如需处理低质量文档，必须**明确询问用户并获得确认**
- 删除操作示例（仅当用户明确同意时执行）:
  ```powershell
  # 询问用户确认
  $confirm = Read-Host "是否删除 $($lowQualityDocs.Count) 个低质量文档？(y/n)"
  if ($confirm -eq "y") {
      # 移动到回收站而非直接删除（如果可能）
      foreach ($doc in $lowQualityDocs) {
          Write-Host "将移动到回收站：$($doc.FullName)"
      }
  }
  ```

---

### Step 1: 生成 L3 文件级文档（核心阶段）

**子代理分片策略**:

| 文件总数 | 子代理数 | 每片文件数 | 超时时间 |
|----------|----------|------------|----------|
| <20 | 1 | 全部 | 300 秒 |
| 20-50 | 3-4 | 10-16 | 600 秒 |
| 50-80 | 5 | 12-18 | 900 秒 |
| >80 | 6-8 | 10-14 | 900 秒 |

**子代理任务模板**:

```markdown
# 任务：为 <模块名> 模块生成 L3 文档（分片 X/Y）

## 项目路径
<绝对路径>

## 源码根目录
<模块路径>/src/main/java

## 输出目录
<项目根目录>/.ai-doc/<模块名>/

## 本分片文件列表
<文件列表，10-16 个>

## 核心要求

### 1. 文档内容要求
- **详细业务逻辑描述**：将代码逻辑转换为自然语言，非程序员也能理解
- **不包含代码片段**：MD 文件中不要出现任何原代码
- **方法级别分析**：每个有业务逻辑的方法都要描述其执行流程、业务语义
- **领域知识**：解释涉及的业务概念、领域术语
- **流程上下文**：方法间的调用关系、数据流转
- **设计意图**：为什么这样设计，解决什么问题

### 2. 文档路径规则（⚠️ 重要！）
- 源文件：`<模块路径>/src/main/java/包路径/类名.java`
- 文档：`<项目根目录>/.ai-doc/<模块名>/src/main/java/包路径/类名.java.md`
- **⚠️ 必须包含 `src/main/java/` 完整路径！**
- **❌ 错误示例**：`.ai-doc/app-api/com/infypower/...`（缺少 src/main/java）
- **✅ 正确示例**：`.ai-doc/app-api/src/main/java/com/infypower/...`
- 生成文档前必须检查路径是否正确，错误路径的文档会被视为无效

### 3. 跳过规则（⚠️ 严格执行！）

**必须跳过的文件类型**（满足任一条件即跳过）：

| 类型 | 判断标准 | 示例 |
|------|----------|------|
| **DTO/VO/Param** | 类名以 DTO/VO/Param/BO 结尾，且行数<50，且不包含方法（除 getter/setter） | UserDTO.java, LoginVO.java |
| **枚举** | 包含 `enum` 关键字，且不包含复杂方法 | PaymentStatus.java |
| **常量类** | 类名包含 Constant，且只包含 `public static final` 字段 | AppApiConstant.java |
| **接口** | 包含 `public interface`，且无方法实现 | UserService.java |
| **MapStruct Converter** | 包含 `@Mapper` 注解，或接口名包含 Converter | UserConverter.java |
| **抽象基类** | 包含 `public abstract class`，且方法都是抽象的 | AbstractHandler.java |
| **测试类** | 类名包含 Test，或包含 `@Test` 注解 | UserServiceTest.java |

**代码特征检查**（满足任一条件即跳过）：
```
1. 文件行数 < 30 行
2. 不包含以下关键字：if, for, while, switch, try, catch, return（getter/setter 除外）
3. 只包含字段定义和 @ 注解
4. 方法体都是空的（只有分号或 throw new UnsupportedOperationException）
```

**⚠️ 必须生成文档的情况**（满足任一条件）：
- Controller 类（包含 API 接口）
- Service/ServiceImpl 类
- Helper/Util 类（包含业务方法）
- Consumer/Listener 类（消息处理）
- Job/Task 类（定时任务）
- Config 配置类（包含 Bean 定义）
- Interceptor/Filter/Aspect 类
- 任何包含实际业务逻辑的类

### 4. 文档质量自检（⚠️ 生成后必须检查！）

**生成每个文档后自检**，确保文档合格：

**✅ 合格文档检查清单**（必须全部满足）：
- [ ] 文档行数 > 30 行
- [ ] 包含"触发条件"或类似描述（什么时候执行）
- [ ] 包含"输入数据"或"处理流程"描述（如何处理）
- [ ] 包含"业务规则"或"判断逻辑"描述（判断条件）
- [ ] 包含"输出结果"或"数据流转"描述（结果去向）
- [ ] 不包含原代码片段（`public class`, `if ()`, `return` 等关键字）

**❌ 低质量文档特征**（出现任一需重新生成，不建议使用）：
- [ ] 文档行数 < 20 行
- [ ] 只包含模板框架（"Business component", "Interface definition", "Simple data object"）
- [ ] 只重复类名和包名，无实际业务解释
- [ ] 核心业务逻辑部分只有"Executes business logic based on specific scenario"

**自检示例**：
```markdown
# ❌ 低质量文档（需要重新生成）
## Business Responsibility
Business component - participates in system business processing

## Core Business Logic
Executes business logic based on specific scenario

# ✅ 合格文档（正确示例）
## 业务职责
AuthService 是认证服务核心类，处理用户账户的创建、更新、查询，
以及支付宝授权码验证和加密手机号解密。当用户通过小程序授权登录时，
该类负责从微信/支付宝获取用户信息，创建或更新本地用户账户...

## 核心业务逻辑
### 支付宝授权码验证
触发条件：用户在小程序点击授权登录，前端传入 auth_code
处理流程：
1. 调用支付宝 API 换取用户 open_id
2. 验证返回的 open_id 是否有效
3. 根据 open_id 查询本地用户...
```

### 5. 上下文管理
- Config 配置类（包含业务配置逻辑）
- 工具类（包含业务相关工具方法）
- 拦截器/过滤器（包含业务逻辑）
- 异常处理器
- MyBatis Mapper XML 文件
- 任何包含业务逻辑的类

### 5. 上下文管理
- 每处理完 2-3 个文件，压缩已处理内容
- 只保留：文件路径 + 1 行摘要
- 丢弃：完整文档内容、中间思考过程

### 6. 文件读取失败处理
- 如文件读取失败，记录该文件到失败列表
- 在最终报告中标注无法读取的文件
- 请求用户确认文件访问权限
- ⚠️ 禁止尝试提权或使用替代读取工具

## L3 文档模板

```markdown
# {类名} - 业务逻辑详解

## 基本信息
- **文件路径**: {relativePath}
- **行数**: {lines}
- **文件类型**: {Config/Controller/Service/ServiceImpl/Interceptor/Handler/Util}
- **所属模块**: {moduleName}

## 业务职责
{用自然语言描述这个类的业务职责，200-300 字}

## 核心业务逻辑

### {方法/功能点 1}
{详细描述该功能的业务逻辑流程，包括：
- 触发条件
- 输入数据处理
- 业务规则判断
- 数据流转过程
- 输出结果
- 异常情况处理
}

### {方法/功能点 2}
{同上}

## 业务流程
{描述方法间的调用关系和业务流转过程}

## 数据交互
{描述与数据库、外部服务、Redis、MQ 等的交互}

## 依赖关系
{该类依赖的其他组件和服务}

## 设计意图
{解释为什么这样设计，解决了什么业务问题}
```

## 返回格式

```json
{
  "chunk": "X/Y",
  "status": "completed|partial",
  "processed": ["File1.java", ...],
  "skipped": ["SimpleClass.java", ...],
  "failed": [],
  "summaries": [
    {"file": "File1.java", "lines": 150, "type": "Controller", "summary": "一句话业务摘要"}
  ]
}
```
```

**上下文压缩策略**:

```
每处理 2-3 个文件后：
保留：
- 文件路径列表
- 每文件 1 行摘要
- 当前任务描述
- 输出路径
- 进度统计

丢弃：
- 已生成文档的完整内容
- 中间思考过程
- 详细示例
- 完整函数体
```

---

### Step 2: 生成 L2 模块级文档

**触发条件**: 所有 L3 文档生成完成

**核心策略**:
- spawn 一个子代理
- 读取该模块所有 L3 文档的摘要信息
- 汇总生成 module.md
- 包含模块架构、核心业务流程、依赖关系

**L2 文档模板**:

详见 [references/l2-module-template.md](references/l2-module-template.md)

**核心章节**:

```markdown
# {模块名} - 模块详解

## 模块职责
{200-300 字概述模块的业务定位和核心价值}

## 文件索引表
| 文件路径 | 职责简述 | 类型 | 行数 |
|----------|----------|------|------|
{列出所有已生成 L3 文档的文件}

## 核心业务流程

### 1. {核心流程 1}
{详细描述跨类的业务流程，如用户认证授权流程}

### 2. {核心流程 2}
{如数据权限隔离流程}

### 3. {核心流程 3}
{如系统管理功能流程}

## MyBatis 映射关系
{SQL 与 Java 方法的映射关系，核心表说明}

## 模块依赖
- **内部依赖**: 依赖的其他模块
- **外部服务**: Redis/MySQL/Apollo/RabbitMQ/XXL-Job 等
- **框架依赖**: Spring Boot/MyBatis-Plus/Spring Security 等

## 配置项汇总
{application 配置文件的主要设置，按功能分类}

## 技术栈
{使用