@dtt_siye/atool 1.1.0

package/skills/project-analyze/rules/java.md

@@ -0,0 +1,507 @@
+# Java / Spring Boot 项目分析规则
+
+## 分析粒度
+
+按 Maven/Gradle 模块和 Spring 分层架构（Controller → Service → Repository → Entity）进行分析。
+
+```
+Application Entry (main)
+    ↓
+Config / Bootstrap（配置）
+    ↓
+Controller / REST（API 入口）
+    ↓
+Service / UseCase（业务逻辑）
+    ↓
+Repository / DAO（数据访问）
+    ↓
+Entity / Model（数据模型）
+    ↓
+Security（安全）
+    ↓
+Common / Utils（工具）
+```
+
+## 目录扫描策略
+
+### 1. 识别构建文件
+
+**信号文件检测：**
+- `pom.xml` → Maven 项目
+- `build.gradle` / `build.gradle.kts` → Gradle 项目
+- `settings.gradle` / `settings.gradle.kts` → Gradle settings
+
+### 2. 识别 Spring 特征
+
+- `@SpringBootApplication` → Spring Boot
+- `spring-boot-starter-*` 依赖 → Spring Boot starters
+- `application.yml` / `application.properties` → Spring 配置
+- `bootstrap.yml` → Spring Cloud 配置中心
+
+### 3. 多模块结构提取
+
+从 `pom.xml` 的 `<modules>` 或 `settings.gradle` 的 `include` 提取：
+- 每个模块为一个分析单元
+- 模块间依赖关系
+
+### 4. 依赖提取
+
+| 类别 | 常见依赖 |
+|------|----------|
+| Web | spring-boot-starter-web, spring-boot-starter-webflux |
+| ORM | mybatis-plus, mybatis-spring-boot, spring-data-jpa |
+| 数据库 | mysql-connector, postgresql, h2, oracle |
+| 安全 | spring-boot-starter-security, shiro-spring |
+| 缓存 | spring-boot-starter-data-redis, caffeine |
+| 消息 | spring-kafka, spring-amqp |
+| 微服务 | spring-cloud-starter-*, nacos, eureka |
+| 文档 | springdoc-openapi, knife4j |
+| 工具 | lombok, mapstruct, hutool |
+
+### 5. 按层扫描路径
+
+- **Controller**: `*/controller/`, `*/rest/`, `*/api/`
+- **Service**: `*/service/`, `*/service/impl/`
+- **Repository**: `*/repository/`, `*/dao/`, `*/mapper/`
+- **Model**: `*/model/`, `*/entity/`, `*/domain/`, `*/dto/`, `*/vo/`
+- **Config**: `*/config/`, `*/configuration/`
+- **Security**: `*/security/`
+- **Common**: `*/common/`, `*/utils/`, `*/enums/`
+
+## 多模块项目发现策略
+
+### Maven 多模块项目
+
+**前置检测（Step 3 模块发现之前必须执行）**：
+
+1. 检查根 `pom.xml` 中是否存在 `<modules>` 标签
+2. 如果存在，提取所有 `<module>` 值作为独立分析单元
+3. 对每个模块，执行以下提取：
+
+```
+{module}/
+├── pom.xml                          → groupId, artifactId, parent, dependencies
+├── src/main/java/{package}/         → 所有 Java 源码
+│   ├── controller/                  → API 入口
+│   ├── service/                     → 业务逻辑
+│   ├── mapper/ or repository/       → 数据访问
+│   ├── domain/ or entity/ or model/ → 数据模型
+│   ├── config/                      → 配置
+│   └── ...
+├── src/main/resources/              → application.yml, mapper XML
+└── src/test/java/                   → 测试
+```
+
+#### 包路径推断（关键 — 防止生成 `com/example/` 等占位符）
+
+1. **优先从 pom.xml `<groupId>` 推断**：
+   - `<groupId>com.ftms.scrm</groupId>` → `com/ftms/scrm/`
+   - **跳过**框架 groupId（`org.springframework.*`, `org.apache.*`, `com.alibaba.*`）
+2. **备选从首个 .java 文件的 `package` 声明推断**：
+   - `package com.ftms.scrm.auth;` → `com/ftms/scrm/auth/`
+3. **禁止使用** `com/example/`、`com.demo`、`com.yourcompany` 等默认占位符
+
+#### Java 版本推断（防止默认 JDK 17+）
+
+1. 从 `<java.version>` 属性提取（如 `<java.version>1.8</java.version>` → `JDK 8`）
+2. 从 maven-compiler-plugin `<source>` 提取
+3. 从 build.gradle `sourceCompatibility` 提取
+4. **禁止默认使用** `JDK 17+` 或 `JDK 11+` 等猜测值
+
+#### 每个模块必须提取的信息
+
+| 信息 | 来源 | 用途 |
+|------|------|------|
+| artifactId | pom.xml | 模块名称 |
+| groupId | pom.xml | 包路径推断 |
+| Java 版本 | pom.xml properties | 环境要求 |
+| Spring Boot 版本 | pom.xml parent/dependency | 技术栈表格 |
+| 模块依赖 | pom.xml dependencies | 依赖关系图 |
+| 端口 | application.yml server.port | 架构图标注 |
+| 数据库 URL | application.yml datasource | 微服务适应性评估 |
+
+### Gradle 多模块项目
+
+1. 检查 `settings.gradle` 或 `settings.gradle.kts` 中的 `include` 声明
+2. 每个 include 项为一个独立模块
+3. 源码路径：`{module}/src/main/java/` 和 `{module}/src/main/kotlin/`
+
+### 模块依赖拓扑图
+
+从所有模块的 pom.xml/build.gradle 提取模块间依赖，生成 ASCII 拓扑图：
+- 分析时按拓扑顺序（被依赖的模块先分析）
+- 检测循环依赖（存在则标记为 Critical 问题）
+
+## 架构适应性评估
+
+在模块分析完成后，生成架构合规报告。评估以下 4 个维度：
+
+### 1. 分层合规性
+
+扫描所有 Java 文件的 import 语句，检测层间依赖是否合规：
+
+| 层 | 允许依赖 | 禁止依赖 |
+|----|----------|----------|
+| Controller | Service, DTO, VO | Repository, Entity, Mapper |
+| Service | Repository, Entity, DTO, 其他 Service | Controller |
+| Repository | Entity | Service, Controller |
+| Entity / Model | 无（纯数据类） | Service, Repository, Controller |
+| DTO / VO | 无（纯数据类） | Service, Repository |
+| Config | Service, Repository（通过 @Bean） | — |
+
+**检测方法**：
+- 分析每个 `*Controller.java` 的 import，查找 `*Mapper`、`*Repository`、`*Dao` 的引用
+- 分析每个 `*Entity.java` 的 import，查找 `*Service` 的引用
+- 分析每个 `*Service.java` 的 import，查找 `*Controller` 的引用
+
+**白名单（不计为违规）**：
+- `@ControllerAdvice` + `@ExceptionHandler` — 全局异常处理
+- `@Configuration` 类（`*Config.java`）— 通过 @Bean 注入
+- Actuator/HealthCheck 端点
+- Test 类（`src/test/` 下）
+- `*Application.java` 启动类
+
+### 2. 微服务适应性
+
+**适用条件**：项目包含 Spring Cloud/Nacos/Dubbo 等 微服务框架依赖。
+
+| 检测项 | 判定标准 | 严重度 |
+|--------|----------|--------|
+| 共享数据库 | 多个模块的 application.yml 指向同一数据库 URL | Critical |
+| 跨服务直接数据访问 | 服务 A 的 Mapper 查询服务 B 的表 | Critical |
+| 共享业务逻辑库 | common 模块包含 `*Service.java` | Warning |
+| Feign 调用链过深 | 调用链 >3 层 | Warning |
+| 服务无法独立部署 | 模块间存在非 API 的编译期依赖 | Critical |
+| API 网关仅做路由 | Gateway 模块无聚合/限流/认证逻辑 | Info |
+
+**检测方法**：
+```
+# 共享数据库：提取所有模块的 datasource URL
+grep -r 'spring.datasource.url' */src/main/resources/
+
+# 跨服务数据访问：检查 Mapper XML 是否引用其他服务的表
+grep -r '<tableName>' */src/main/resources/mapper/
+
+# Feign 调用链：扫描 @FeignClient 接口，构建调用图
+grep -r '@FeignClient' --include='*.java' .
+```
+
+### 3. 包结构健康度
+
+| 检测项 | 判定标准 | 严重度 |
+|--------|----------|--------|
+| 组织模式 | 按层分包 vs 按功能分包 vs 混合 | — |
+| 大泥球 | 单个包内 >50 个 .java 文件 | Warning |
+| 循环依赖 | 包 A import 包 B，包 B 也 import 包 A | Critical |
+| 包层次过深 | 包路径 >6 层 | Info |
+
+### 4. 依赖方向
+
+从 pom.xml/build.gradle 提取模块间依赖，构建有向图：
+- 上层依赖下层，不存在反向依赖
+- 公共模块（common, utils, core）不依赖业务模块
+- API 模块（仅含接口/DTO）不依赖实现模块
+- 检测并标注循环依赖
+
+### 输出格式
+
+在每个模块的 MODULE-DOC.md 中增加「架构合规评估」章节：
+
+```markdown
+## 架构合规评估
+
+### 分层合规
+| 规则 | 状态 | 违规位置 | 严重度 |
+|------|------|----------|--------|
+| Controller 不直接调用 Repository | ⚠️ 违规 | UserController.java:45 imports UserMapper | Warning |
+| Entity 不包含业务逻辑 | ✅ 合规 | — | — |
+| Service 不依赖 Controller | ✅ 合规 | — | — |
+
+### 包结构
+- 组织模式：按层分包（建议迁移为按功能分包）
+- 包层次深度：4 层
+- 循环依赖：无
+
+### 微服务适应性（适用时）
+| 检测项 | 状态 | 详情 |
+|--------|------|------|
+| 独立数据库 | ❌ | 3 个服务共享同一 MySQL |
+| 同步耦合 | ⚠️ | Feign 调用链最深 3 层 |
+```
+
+## 各层提取规则
+
+### 层 1: Controller 层
+
+**扫描文件**: `*Controller.java`, `*Resource.java`, `*Endpoint.java`
+
+**提取内容**:
+- 类名 + `@RequestMapping` 基础路径
+- API 方法列表（HTTP 方法 + 路径 + 参数 + 返回类型 + Swagger 注解）
+- 权限注解（`@PreAuthorize`, `@RequiresPermissions`）
+- 请求/响应 DTO
+
+**输出示例**:
+```
+### UserController
+- **路径**: `com.example.system.controller.UserController`
+- **基础路径**: `/system/user`
+- **依赖注入**: UserService, DeptService
+- **API 方法**:
+  | 方法 | HTTP | 路径 | 参数 | 返回类型 | 权限 | 说明 |
+  |------|------|------|------|----------|------|------|
+  | list | GET | /list | UserQueryDTO | TableDataInfo<UserVO> | @PreAuthorize("@ss.hasPermi('system:user:list')") | 分页查询 |
+  | getInfo | GET | /{userId} | @PathVariable Long | R<UserVO> | @PreAuthorize("@ss.hasPermi('system:user:query')") | 获取详情 |
+  | add | POST | / | @Validated @RequestBody UserDTO | R<Void> | @PreAuthorize("@ss.hasPermi('system:user:add')") | 新增用户 |
+  | edit | PUT | / | @Validated @RequestBody UserDTO | R<Void> | @PreAuthorize("@ss.hasPermi('system:user:edit')") | 修改用户 |
+  | remove | DELETE | /{userIds} | @PathVariable Long[] | R<Void> | @PreAuthorize("@ss.hasPermi('system:user:remove')") | 删除用户 |
+  | export | POST | /export | UserQueryDTO | void (Excel) | @PreAuthorize("@ss.hasPermi('system:user:export')") | 导出 Excel |
+- **Swagger**: @Tag(name = "用户管理")
+```
+
+### 层 2: Service 层
+
+**扫描文件**: `*Service.java` (接口), `*ServiceImpl.java` (实现)
+
+**提取内容**:
+- 接口方法签名
+- 实现类的业务逻辑摘要
+- 依赖的其他 Service / Repository
+- 事务注解（`@Transactional`）
+
+**输出示例**:
+```
+### UserService (接口)
+- **路径**: `com.example.system.service.UserService`
+- **方法**:
+  | 方法 | 签名 | 说明 |
+  |------|------|------|
+  | selectUserList | (UserQueryDTO) → List<UserVO> | 分页查询用户列表 |
+  | selectUserById | (Long) → UserVO | 查询用户详情 |
+  | insertUser | (UserDTO) → int | 新增用户 |
+  | updateUser | (UserDTO) → int | 修改用户 |
+  | deleteUser | (Long[]) → int | 批量删除 |
+  | resetPwd | (Long, String) → int | 重置密码 |
+
+### UserServiceImpl (实现)
+- **路径**: `com.example.system.service.impl.UserServiceImpl`
+- **依赖注入**: UserMapper, RoleMapper, DeptService, PasswordEncoder
+- **关键业务逻辑**:
+  - insertUser: 校验用户名唯一 → 加密密码 → 初始化角色 → 插入用户+角色关联
+  - updateUser: 校验权限 → 更新用户信息 → 同步角色关联
+- **事务**: @Transactional (insertUser, updateUser, deleteUser)
+```
+
+### 层 3: Repository / Mapper 层
+
+**扫描文件**: `*Mapper.java`, `*Repository.java`, `*Dao.java`
+
+#### MyBatis Mapper
+
+**提取内容**:
+- Mapper 接口方法签名
+- XML 映射文件中的 SQL（自定义查询）
+- ResultMap 映射关系
+
+**输出示例**:
+```
+### UserMapper
+- **路径**: `com.example.system.mapper.UserMapper`
+- **继承**: BaseMapper<UserEntity>
+- **自定义方法**:
+  | 方法 | 签名 | SQL 位置 | 说明 |
+  |------|------|----------|------|
+  | selectUserByUserName | (String) → UserEntity | UserMapper.xml | 按用户名查询 |
+  | checkUserNameUnique | (String) → int | UserMapper.xml | 检查用户名唯一 |
+  | selectUserByPhone | (String) → UserEntity | UserMapper.xml | 按手机号查询 |
+- **XML 文件**: `resources/mapper/system/UserMapper.xml`
+```
+
+#### JPA Repository
+
+**提取内容**:
+- Repository 接口继承的基类
+- 自定义查询方法（`findBy*`, `@Query`）
+
+**输出示例**:
+```
+### UserRepository
+- **路径**: `com.example.user.repository.UserRepository`
+- **继承**: JpaRepository<User, Long>
+- **自定义查询**:
+  | 方法 | 查询方式 | 说明 |
+  |------|----------|------|
+  | findByEmail(String email) | 方法名推导 | 按邮箱查询 |
+  | findByRole(String role) | 方法名推导 | 按角色查询 |
+  | findActiveUsers() | @Query("SELECT u FROM User u WHERE u.active = true") | 查询活跃用户 |
+```
+
+### 层 4: Entity / Model 层
+
+**扫描文件**: `*/entity/*.java`, `*/domain/*.java`, `*/dto/*.java`, `*/vo/*.java`
+
+**提取内容**:
+- 实体类 + `@TableName` / `@Table` 注解
+- 字段列表（名称 + 类型 + 数据库列名 + 注解）
+- DTO/VO 与 Entity 的映射关系
+- 枚举类型定义
+
+**输出示例**:
+```
+### SysUser (Entity)
+- **路径**: `com.example.system.domain.SysUser`
+- **表名**: sys_user
+- **字段**:
+  | 字段 | 类型 | 列名 | 注解 | 说明 |
+  |------|------|------|------|------|
+  | userId | Long | user_id | @TableId | 主键 |
+  | userName | String | user_name | @NotBlank | 用户名 |
+  | nickName | String | nick_name | - | 昵称 |
+  | email | String | email | @Email | 邮箱 |
+  | phonenumber | String | phonenumber | - | 手机号 |
+  | status | String | status | - | 状态（0正常 1停用） |
+  | createTime | Date | create_time | - | 创建时间 |
+
+### UserVO (View Object)
+- **路径**: `com.example.system.vo.UserVO`
+- **来源**: SysUser + 关联查询（deptName, roleNames）
+- **字段**: userId, userName, nickName, deptName, roleNames, status, createTime
+```
+
+### 层 5: Security 层
+
+**扫描文件**: `*/security/**/*.java`, `*/config/SecurityConfig.java`
+
+**提取内容**:
+- Security Filter Chain 配置
+- 认证方式（JWT / Session / OAuth2）
+- 权限模型（RBAC / ABAC）
+- 密码编码方式
+- CORS 配置
+
+**输出示例**:
+```
+### Security 配置
+- **文件**: `com.example.config.SecurityConfig`
+- **认证方式**: JWT (Bearer Token)
+- **Filter Chain**:
+  1. JwtAuthenticationTokenFilter — 从 header 解析 token，验证签名
+  2. LogoutSuccessHandler — 清除 token
+  3. AuthenticationEntryPoint — 401 未认证响应
+  4. AccessDeniedHandler — 403 无权限响应
+- **公开路径**: /login, /register, /captchaImage, /doc.html
+- **密码编码**: BCryptPasswordEncoder
+- **Token 存储**: Redis (key: login_tokens:{uuid})
+```
+
+### 层 6: 配置层
+
+**扫描文件**: `application.yml`, `application-*.yml`, `bootstrap.yml`
+
+**提取内容**:
+- 服务端口和上下文路径
+- 数据库连接配置
+- Redis 配置
+- 中间件配置
+- Profile 环境区分
+
+**输出示例**:
+```
+### application.yml 核心配置
+| 配置项 | 值 | 说明 |
+|--------|------|------|
+| server.port | 8080 | 服务端口 |
+| spring.datasource.url | jdbc:mysql://... | 数据库连接 |
+| spring.redis.host | localhost | Redis 地址 |
+| mybatis-plus.mapper-locations | classpath*:mapper/**/*Mapper.xml | Mapper XML |
+| knife4j.enable | true | API 文档 |
+```
+
+## 输出模板
+
+### README.md 章节结构
+
+```markdown
+# {项目名}
+
+## 项目概述
+系统功能描述
+
+## 技术栈
+| 技术 | 版本 | 用途 |
+|------|------|------|
+
+## 架构设计
+### 架构图（ASCII）
+### 数据流图
+请求 → Filter → Controller → Service → Repository → Database → 返回
+
+## 模块结构
+Maven/Gradle 模块依赖关系图
+
+## API 接口文档
+按模块分组的 API 端点表
+
+## 安全设计
+认证流程 + 权限模型
+
+## 数据模型
+Entity 关系图（ER 图 ASCII）
+
+## 配置说明
+关键配置项 + 环境变量
+
+## 构建 & 部署
+Maven/Gradle 命令 + Docker 配置
+```
+
+### COMPONENT.md 章节结构
+
+```markdown
+# 模块文档
+
+## Controller 层
+按模块分组的 API 端点表
+
+## Service 层
+接口定义 + 业务逻辑说明
+
+## Repository / Mapper 层
+数据访问方法 + SQL 映射
+
+## 数据模型
+Entity + DTO + VO 定义 + 关系图
+
+## 枚举类型
+业务枚举定义
+
+## 跨模块依赖
+模块间调用关系图
+```
+
+## 模块边界识别
+
+以下目录模式下的每个子目录视为独立模块（L2+ 分析时生成 MODULE-DOC.md）：
+
+| 层 | 扫描路径 | 模块判定规则 | MODULE-DOC slug 来源 |
+|----|----------|-------------|---------------------|
+| Maven 模块层 | Maven `<modules>` | 每个模块 | artifactId kebab-case |
+| Controller 层 | `src/main/java/**/controller/` | 每个子目录 | 目录名 kebab-case |
+| Service 层 | `src/main/java/**/service/` | 每个子目录 | 目录名 kebab-case |
+| Config 层 | `src/main/java/**/config/` | 每个子目录 | 目录名 kebab-case |
+| Entity 层 | `src/main/java/**/entity/` | 每个文件 | 类名 kebab-case |
+
+**不视为独立模块的情况**：
+- 单文件入口（如 `Application.java`）
+- 纯导出桶文件（仅有 re-export）
+- 工具函数目录（`util/`, `helper/`）— 合并为一个模块
+- DTO/VO 目录（`dto/`, `vo/`）— 合并为一个模块
+
+## Token 管理
+
+- 大模块（>20 文件）拆分为子任务
+- 每个子任务分析 ≤10 文件
+- `pom.xml` / `build.gradle` 依赖分析单独一个子任务
+- MyBatis XML 映射文件与对应 Mapper 接口一起分析
+- 测试文件（`src/test/`）单独分析
+- 配置文件（`application*.yml`）单独分析