---
name: module-doc
version: "1.0.0"
category: expert
description: "当用户需要分析代码模块并将代码逻辑、业务配置等形成业务文档时使用：包括但不限于生成时序图、类图、类描述、功能描述、配置参数文档等。不要用于代码实现、Bug 修复、代码审查或性能优化。Use when user needs to analyze code modules and generate business documentation: sequence diagrams, class diagrams, class descriptions, functionality descriptions, configuration parameter docs, etc. Do NOT use for code implementation, bug fixing, code review, or performance optimization."
triggers:
  zh: ["模块文档", "生成文档", "代码文档", "时序图", "类图", "配置文档", "架构文档", "模块分析", "接口文档"]
  en: ["module documentation", "generate docs", "class diagram", "sequence diagram", "architecture doc", "code documentation", "module analysis", "config doc"]
license: MIT
compatibility: Java 11+, Node.js >= 18
dependencies: []
metadata:
  author: "sunhongda@example.com"
  created: "2026-06-24"
  updated: "2026-06-24"
  status: "experimental"
---

## Changelog / 版本履历

| 日期 | 版本 | 说明 |
|------|------|------|
| 2026-06-24 | 1.0.0 | 初始版本 |

## Core Concept / 核心概念

### 🇨🇳 核心概念

**输入 → 处理 → 输出**

1. **输入**: 用户指定代码模块路径、分析深度、输出要求
2. **处理**: 扫描代码文件 → 提取结构信息 → 追踪调用链 → 生成图表 → 整合文档
3. **输出**: 模块业务文档（Markdown格式），包含时序图、类图、配置文档、API清单

**不负责的任务**:
- ❌ 代码实现
- ❌ Bug修复
- ❌ 安全审计
- ❌ 代码审查
- ❌ 性能优化

### 🇺🇸 Core Concept

**Input → Process → Output**

1. **Input**: User specifies code module path, analysis depth, and output requirements
2. **Process**: Scan code files → Extract structure → Trace call chains → Generate diagrams → Assemble documentation
3. **Output**: Module business documentation (Markdown format), including sequence diagrams, class diagrams, configuration docs, and API inventory

**Out of Scope**:
- ❌ Code implementation
- ❌ Bug fixing
- ❌ Security audit
- ❌ Code review
- ❌ Performance optimization

## Position / 定位

```
[code-review] + [refactor-plan]
              ↓
         [module-doc]
              ↓
         [ba/developer]

Legend:
- code-review: 代码审查 → 识别模块边界
- refactor-plan: 重构规划 → 理解代码结构
- module-doc: 模块文档 → 生成可读的业务文档
- ba: 业务分析师
- developer: 开发者
```

## Capabilities / 能力

### 1. 模块发现与边界识别 / Module Discovery & Boundary Identification

- **功能**: 自动识别Controller、Service、Mapper、Entity层次结构
- **实现**: 通过文件路径模式匹配 + 类名约定（如`*Controller`、`*Service`）
- **输出**: 模块依赖关系图、核心类清单

### 2. 代码结构与关系分析 / Code Structure & Relationship Analysis

- **功能**: 分析类依赖、继承关系、依赖注入、数据流
- **实现**: LSP符号查询 + AST分析 + grep调用链追踪
- **输出**: 类依赖矩阵、方法调用图

### 3. 业务流程追踪/时序图生成 / Business Flow Tracing & Sequence Diagram Generation

- **功能**: 追踪Controller→Service→Mapper→DB的完整调用链
- **实现**: LSP goto_definition + find_references + 递归追踪
- **输出**: Mermaid sequenceDiagram，标注关键方法、参数、返回值

### 4. 类图生成 / Class Diagram Generation

- **功能**: 生成包含类、接口、方法、字段的类图
- **实现**: LSP symbols + 注解扫描（@Entity、@Component等）
- **输出**: Mermaid classDiagram，标注继承、实现、关联关系

### 5. 配置参数提取 / Configuration Parameter Extraction

- **功能**: 提取yml/properties配置、@Value注解、@ConfigurationProperties
- **实现**: grep正则匹配 + 配置文件扫描
- **输出**: 配置参数清单，包含默认值、环境差异

### 6. 功能描述与API清单 / Functionality Description & API Inventory

- **功能**: 提取API端点、请求/响应结构、业务规则
- **实现**: 解析@RequestMapping注解 + Swagger注解（如存在）
- **输出**: API文档表格，包含路径、方法、参数、示例

### 7. 前端组件文档（Vue 2专项）/ Frontend Component Documentation (Vue 2 Specialized)

- **功能**: 分析Vue组件模板、props、events、methods
- **实现**: 解析.vue文件 + Element UI组件识别
- **输出**: 组件使用说明、props表格、事件清单

## Dependencies / 依赖

| 依赖项 | 用途 | 必需 | 说明 |
|--------|------|------|------|
| LSP Server (jdtls) | Java符号查询、定义跳转、引用查找 | 是（Java项目） | 用于分析Java代码结构 |
| LSP Server (vue-language-server) | Vue组件符号查询 | 是（Vue项目） | 用于分析Vue 2组件 |
| glob | 文件模式匹配 | 是 | 发现目标文件 |
| grep | 内容搜索与正则匹配 | 是 | 提取配置参数、注解 |
| 无 | 其他技能依赖 | - | 本技能独立运行 |

## Workflow / 工作流程

### Step 1: 模块发现与范围确认 / Module Discovery & Scope Confirmation

**EN**: Scan target directory to identify module components (Controllers, Services, Mappers, Entities), classify their roles, and ask user to confirm or adjust analysis scope.

**中文**: 扫描目标目录识别模块组件（Controller、Service、Mapper、Entity），分类其角色，并请用户确认或调整分析范围。

**中断条件 / Interrupt Condition**: 用户取消任务或提供新的路径

**产出物 / Deliverable**: 模块组件清单（文件路径列表）

---

### Step 2: 结构扫描与分析 / Structure Scanning & Analysis

**EN**: Read all identified files, extract class metadata (names, methods, fields, annotations), map call chains using LSP goto_definition and find_references, and identify inheritance and dependency relationships.

**中文**: 读取所有识别的文件，提取类元数据（名称、方法、字段、注解），使用LSP goto_definition和find_references映射调用链，识别继承和依赖关系。

**中断条件 / Interrupt Condition**: LSP服务不可用或文件读取失败

**产出物 / Deliverable**: 类结构矩阵、依赖关系图

---

### Step 3: 业务流程追踪 / Business Flow Tracing

**EN**: Trace Controller→Service→Mapper→DB call chains, identify AOP interception points and transaction boundaries, and generate Mermaid sequenceDiagram with accurate method names and parameters.

**中文**: 追踪Controller→Service→Mapper→DB调用链，识别AOP拦截点和事务边界，生成包含准确方法名和参数的Mermaid sequenceDiagram。

**中断条件 / Interrupt Condition**: 调用链深度超过max_flow_depth配置值

**产出物 / Deliverable**: 业务流程时序图（Mermaid格式）

---

### Step 4: 配置参数提取 / Configuration Parameter Extraction

**EN**: Scan yml/properties files, @Value annotations, @ConfigurationProperties classes, extract constants and enums, and document default values and environment-specific differences.

**中文**: 扫描yml/properties文件、@Value注解、@ConfigurationProperties类，提取常量和枚举，记录默认值和环境差异。

**中断条件 / Interrupt Condition**: 配置文件解析失败或include_config=false

**产出物 / Deliverable**: 配置参数清单表格

---

### Step 5: 文档组装与图表生成 / Documentation Assembly & Diagram Generation

**EN**: Assemble all analysis results into docs/{module-name}/ directory, generate Mermaid classDiagram, create API inventory tables, and write comprehensive markdown documentation.

**中文**: 将所有分析结果组装到docs/{module-name}/目录，生成Mermaid classDiagram，创建API清单表格，编写完整的markdown文档。

**中断条件 / Interrupt Condition**: 输出目录不可写

**产出物 / Deliverable**: 完整的模块业务文档（Markdown格式）

## Configuration / 配置

| 参数名 | 类型 | 必需 | 默认值 | 说明 |
|--------|------|------|--------|------|
| target_path | string | 是 | - | 目标模块路径（相对或绝对路径） |
| depth | enum | 否 | full | 分析深度：quick（仅核心类）、full（完整分析） |
| include_vue | boolean | 否 | false | 是否包含Vue 2组件分析 |
| include_config | boolean | 否 | true | 是否提取配置参数 |
| max_flow_depth | integer | 否 | 10 | 时序图最大追踪深度 |
| output_dir | string | 否 | docs/{module-name} | 输出目录 |

## Iron Law / 核心铁律

### Law 1: 文档必须可执行验证 / Documentation Must Be Verifiable

**🇨🇳**: 所有API示例必须可直接复制执行（curl、Postman格式），数据示例必须真实且符合schema

**🇺🇸**: All API examples must be directly executable (curl/Postman format), data examples must be real and schema-compliant

❌ **Violation**:
```yaml
# API文档示例：虚构的响应结构
Response: { success: true, data: "some fake data" }
```

✅ **Compliance**:
```yaml
# API文档示例：基于真实代码的响应
# Source: UserController.java:45
Response:
  {
    "code": 200,
    "message": "success",
    "data": {
      "id": 1,
      "username": "admin",
      "email": "admin@example.com"
    }
  }
```

---

### Law 2: 图表语法有效且与代码一致 / Diagrams Must Be Syntax-Valid & Code-Consistent

**🇨🇳**: Mermaid图表必须语法有效，类名、方法名必须与实际代码完全一致（区分大小写）

**🇺🇸**: Mermaid diagrams must be syntax-valid, class/method names must exactly match actual code (case-sensitive)

❌ **Violation**:
```mermaid
classDiagram
  class User {
    +String name  // 实际代码中字段为 username
    +getInfo()   // 实际方法名为 getUserInfo()
  }
```

✅ **Compliance**:
```mermaid
classDiagram
  class User {
    +String username
    +getUserInfo()
  }
  %% Source: User.java:15
```

---

### Law 3: 不虚构不存在的逻辑 / No Fabricated Logic

**🇨🇳**: 不得编造不存在的调用关系、方法签名、配置项。所有信息必须标注来源（文件名:行号）

**🇺🇸**: Do not fabricate non-existent call relationships, method signatures, or config items. All info must cite sources (filename:line)

❌ **Violation**:
```markdown
UserSerivce调用OrderService的createOrder()方法
（实际代码中不存在此调用）
```

✅ **Compliance**:
```markdown
UserService调用OrderService的createOrder()方法
Source: UserService.java:78 → OrderService.createOrder():45
```

---

### Law 4: 配置文档区分环境 / Config Docs Must Distinguish Environments

**🇨🇳**: 配置参数必须标注环境差异（dev/test/prod），不同环境的默认值必须明确

**🇺🇸**: Config parameters must annotate environment differences (dev/test/prod), default values for each env must be explicit

❌ **Violation**:
```yaml
database.url: jdbc:mysql://localhost:3306/db  # 未标注环境
```

✅ **Compliance**:
```yaml
database.url:
  - dev: jdbc:mysql://localhost:3306/db_dev
  - test: jdbc:mysql://test-server:3306/db_test
  - prod: jdbc:mysql://prod-server:3306/db_prod
Source: application.yml:12
```

---

### Law 5: 一时序图一流程 / One Sequence Diagram Per Flow

**🇨🇳**: 每个时序图只展示单一业务流程，参与者不超过10个。复杂流程拆分为多个图

**🇺🇸**: Each sequence diagram shows only one business flow, max 10 participants. Split complex flows into multiple diagrams

❌ **Violation**:
```mermaid
sequenceDiagram
  participant A as UserController
  participant B as UserService
  participant C as OrderService
  participant D as PaymentService
  participant E as NotificationService
  participant F as LogService
  participant G as CacheService
  participant H as AuditService
  participant I as MetricService
  participant J as Database
  participant K as MQ
  participant L as Redis  <!-- 超过10个参与者 -->
```

✅ **Compliance**:
```mermaid
sequenceDiagram
  participant User as UserController
  participant Svc as UserService
  participant DB as Database

  User->>Svc: createUser(request)
  Svc->>DB: INSERT INTO user
  DB-->>Svc: affected rows
  Svc-->>User: userId

  %% Flow: 用户注册流程
  %% Source: UserController.createUser():23
```

## Rationalization Table / 合理化防御表

| 模型合理化倾向 | 防御措施 | 具体执行 |
|---------------|---------|---------|
| 倾向于简化复杂的依赖关系 | 强制标注来源 | 每个调用关系必须标注 filename:line |
| 倾向于编造缺失的配置 | 失败即停止 | 配置文件不存在时明确报错，不虚构默认值 |
| 倾向于过度概括业务流程 | 深度限制 | 时序图追踪深度不超过max_flow_depth，超出则拆分 |
| 倾向于忽略边界情况 | 完整性检查 | 必须包含异常处理分支（如存在try-catch） |
| 倾向于混淆类似命名 | 精确匹配 | 类名、方法名必须通过LSP验证，不能靠猜测 |
| 倾向于省略次要细节 | 用户确认 | 每个步骤产出物需用户确认后才进入下一步 |

## Red Flags / 三层防御

### Layer 1: Input Validation / 输入层防御

🔴 **Critical**:
- target_path不存在或无读权限 → 立即终止
- depth值非quick/full → 终止并提示
- max_flow_depth < 1 或 > 50 → 终止并提示

🟡 **Warning**:
- target_path包含过多文件（>1000） → 提示确认继续
- include_vue=true但检测到Vue 3项目 → 警告兼容性问题

🔵 **Info**:
- output_dir已存在 → 提示将覆盖

---

### Layer 2: Execution Control / 执行层防御

🔴 **Critical**:
- LSP服务不可用 → 终止并提示检查LSP配置
- 文件读取失败（IO错误） → 终止并显示具体错误
- Mermaid语法验证失败 → 修正或终止

🟡 **Warning**:
- 调用链深度超过阈值 → 提示拆分流程
- 检测到循环依赖 → 标注但继续执行

🔵 **Info**:
- 某些文件未被分析（如被.gitignore排除） → 提示忽略列表

---

### Layer 3: Output Validation / 输出层防御

🔴 **Critical**:
- 生成的文档包含虚构内容 → 终止并报告问题
- Mermaid图表无法渲染 → 修正或终止
- 输出目录创建失败 → 终止并检查权限

🟡 **Warning**:
- 配置参数未找到默认值 → 标注为"未指定"
- API文档缺少示例 → 提示补充

🔵 **Info**:
- 文档生成成功 → 显示输出路径

## Output / 输出规范

### 🇨🇳 输出目录结构 / 🇺🇸 Output Directory Structure

```
docs/{module-name}/
├── README.md                  # 模块概述、核心功能
├── class-diagram.md          # 类图（Mermaid classDiagram）
├── sequence-diagrams/        # 业务流程时序图目录
│   ├── flow-1-create-user.md
│   ├── flow-2-update-order.md
│   └── ...
├── api-inventory.md          # API清单表格
├── configuration.md          # 配置参数文档
└── components/               # Vue组件文档（如include_vue=true）
    └── UserList.vue.md
```

### 📋 Mermaid Sequence Diagram Template / Mermaid时序图模板

```mermaid
sequenceDiagram
    participant Controller as UserController
    participant Service as UserService
    participant Mapper as UserMapper
    participant DB as Database

    %% 业务流程：创建用户
    %% Source: UserController.createUser():23

    Controller->>Service: createUser(CreateUserDTO)
    activate Service
    Service->>Service: validateEmail(email)
    Service->>Service: checkDuplicate(username)
    Service->>Mapper: insert(UserEntity)
    activate Mapper
    Mapper->>DB: INSERT INTO user
    DB-->>Mapper: affected rows: 1
    Mapper-->>Service: userId: 123
    deactivate Mapper
    Service-->>Controller: CreateUserResponse(userId: 123)
    deactivate Service

    Note over Service,DB: 事务边界: @Transactional
```

### 📋 Mermaid Class Diagram Template / Mermaid类图模板

```mermaid
classDiagram
    class UserController {
        -UserService userService
        +createUser(CreateUserDTO) CreateUserResponse
        +getUserById(Long) UserDTO
        +deleteUser(Long) void
    }
    %% Source: UserController.java:15

    class UserService {
        -UserMapper userMapper
        +createUser(CreateUserDTO) Long
        +getById(Long) UserEntity
        +deleteById(Long) void
    }
    %% Source: UserService.java:20

    class UserMapper {
        +insert(UserEntity) int
        +selectById(Long) UserEntity
        +deleteById(Long) int
    }
    %% Source: UserMapper.java:10

    class UserEntity {
        -Long id
        -String username
        -String email
        +getId() Long
        +setUsername(String)
        +getEmail() String
    }
    %% Source: UserEntity.java:8

    UserController --> UserService: uses
    UserService --> UserMapper: uses
    UserMapper ..> UserEntity: maps
```

## Examples / 示例

### Example 1: 深度分析 / Deep Analysis

**User Request**:
```
生成用户管理模块的完整文档
target_path: src/main/java/com/example/user
depth: full
include_config: true
```

**Generated Output**:
- `docs/user-module/README.md` - 模块概述
- `docs/user-module/class-diagram.md` - 完整类图
- `docs/user-module/sequence-diagrams/` - 5个业务流程时序图
- `docs/user-module/api-inventory.md` - 12个API端点文档
- `docs/user-module/configuration.md` - 配置参数清单

---

### Example 2: 快速分析 / Quick Analysis

**User Request**:
```
快速分析订单模块的核心类
target_path: src/main/java/com/example/order
depth: quick
```

**Generated Output**:
- `docs/order-module/README.md` - 核心功能描述
- `docs/order-module/class-diagram.md` - 核心类关系图
- `docs/order-module/api-inventory.md` - 主要API端点（仅Controller层）

---

### Example 3: Vue组件分析 / Vue Component Analysis

**User Request**:
```
分析前端用户列表组件
target_path: src/views/user
include_vue: true
```

**Generated Output**:
- `docs/user-module/components/UserList.vue.md` - 组件说明
  - Props: `users`、`loading`、`pagination`
  - Events: `@edit`、`@delete`、`@page-change`
  - Element UI组件使用清单
  - 模板结构说明

## Auto-Review / 自检清单

- [ ] YAML frontmatter语法有效（通过YAML解析器验证）
- [ ] 所有13个必需章节都已创建
- [ ] Mermaid sequenceDiagram语法有效（通过Mermaid在线验证器）
- [ ] Mermaid classDiagram语法有效（通过Mermaid在线验证器）
- [ ] 所有类名、方法名都已标注来源文件:行号
- [ ] 配置参数文档区分了dev/test/prod环境
- [ ] API示例包含可执行的curl命令
- [ ] 时序图参与者数量不超过10个
- [ ] 输出目录结构符合规范
- [ ] 所有铁律（Iron Law）都有违规示例和合规示例