@dtt_siye/atool 1.3.0 → 1.3.1

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

@@ -1,507 +1,69 @@
-# Java / Spring Boot 项目分析规则
+# Java / Spring Boot 分析规则
 
-## 分析粒度
+> **编码规范**：本规则不包含编码规范内容。Phase 2.5 精炼阶段会自动加载 `java-conventions` skill 作为规范约束。
 
-按 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. 识别构建文件
+- **Maven 多模块**：检查根 `pom.xml` 的 `<modules>` 标签，每个 `<module>` 为独立分析单元
+- **Gradle 多模块**：检查 `settings.gradle` / `settings.gradle.kts` 的 `include` 声明
+- **包路径推断**：从 `pom.xml` `<groupId>` 推断（跳过 `org.springframework.*` 等框架 groupId），备选读首个 `.java` 文件的 `package` 声明；禁止使用 `com.example` 等占位符
+- **Java 版本推断**：从 `<java.version>` / `sourceCompatibility` 提取；禁止默认使用 JDK 17+
 
-**信号文件检测：**
-- `pom.xml` → Maven 项目
-- `build.gradle` / `build.gradle.kts` → Gradle 项目
-- `settings.gradle` / `settings.gradle.kts` → Gradle settings
+模块间依赖拓扑：从所有模块 pom.xml/build.gradle 提取，检测循环依赖（标记 Critical）。
 
-### 2. 识别 Spring 特征
+## 入口识别
 
-- `@SpringBootApplication` → Spring Boot
-- `spring-boot-starter-*` 依赖 → Spring Boot starters
-- `application.yml` / `application.properties` → Spring 配置
-- `bootstrap.yml` → Spring Cloud 配置中心
+| 标记 | 含义 |
+|------|------|
+| `@SpringBootApplication` | 应用主入口（`main()` 方法所在类） |
+| `@RestController` / `@Controller` | HTTP API 入口 |
+| `@FeignClient` | 外部服务调用入口 |
+| `@KafkaListener` / `@RabbitListener` | 消息消费入口 |
+| `@Scheduled` | 定时任务入口 |
+| `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. 分层合规性
+| 标准 Spring 三层 | `controller/` + `service/` + `repository/mapper/` 目录并存 |
+| 按功能分包（DDD） | 包路径含业务域名（如 `order/`, `payment/`），每个包内含完整分层 |
+| 微服务 | 存在 `spring-cloud-*` / nacos / eureka 依赖 + 多个可独立部署模块 |
+| CQRS | 存在 `command/` + `query/` 分离目录或 `CommandHandler` / `QueryHandler` 类 |
 
-扫描所有 Java 文件的 import 语句，检测层间依赖是否合规：
+架构合规检测：扫描 Controller import 是否引用 Mapper/Repository（层间越级）；检查 Entity 是否引用 Service（反向依赖）。
 
-| 层 | 允许依赖 | 禁止依赖 |
-|----|----------|----------|
-| 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` 的引用
+- **HTTP 请求链**：Filter → Controller → Service → Repository → DB
+- **异步消息链**：MQ Listener → Service → Repository → DB
+- **定时任务链**：@Scheduled → Service → Repository → DB
+- **Feign 调用链**：Controller → Service → FeignClient → 外部服务
 
-**白名单（不计为违规）**：
-- `@ControllerAdvice` + `@ExceptionHandler` — 全局异常处理
-- `@Configuration` 类（`*Config.java`）— 通过 @Bean 注入
-- Actuator/HealthCheck 端点
-- Test 类（`src/test/` 下）
-- `*Application.java` 启动类
+## 分析关注点
 
-### 2. 微服务适应性
+- **Bean 注入图**：从 `@Autowired` / 构造注入扫描 Service/Repository 依赖关系，识别循环依赖
+- **事务边界**：`@Transactional` 标注的方法，是否跨模块事务
+- **多数据源**：多个 `DataSource` Bean / 多个 datasource URL，标记微服务共享数据库风险
+- **安全配置**：`SecurityFilterChain` → 认证方式（JWT/Session/OAuth2）+ 公开路径白名单
+- **配置提取**：`application.yml` 中的端口、数据库 URL、Redis 地址用于架构图标注
 
-**适用条件**：项目包含 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
-
-**输出示例**:
+Controller 提取片段：
 ```
-### 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 = "用户管理")
+UserController  /system/user
+  GET  /list      → UserService.selectUserList()    @PreAuthorize
+  POST /          → UserService.insertUser()         @PreAuthorize
+  PUT  /          → UserService.updateUser()         @PreAuthorize
 ```
 
-### 层 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 | 重置密码 |
+分层合规
+  ⚠️ UserController:45 imports UserMapper（Controller 越级调用 Mapper）
+  ✅ Entity 无反向 Service 依赖
 
-### UserServiceImpl (实现)
-- **路径**: `com.example.system.service.impl.UserServiceImpl`
-- **依赖注入**: UserMapper, RoleMapper, DeptService, PasswordEncoder
-- **关键业务逻辑**:
-  - insertUser: 校验用户名唯一 → 加密密码 → 初始化角色 → 插入用户+角色关联
-  - updateUser: 校验权限 → 更新用户信息 → 同步角色关联
-- **事务**: @Transactional (insertUser, updateUser, deleteUser)
+微服务适应性
+  ❌ 3 个服务共享同一 MySQL datasource URL
 ```
-
-### 层 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`）单独分析