p3c-code-quality

执行代码质量检查测试，基于阿里巴巴 P3C 规范对代码进行全面检查，包括命名规范、异常处理、并发安全、数据库规范、OOP 规范、安全规约和单元测试规范。Invoke when user needs to verify code quality against P3C standards.

# P3C代码质量检查测试

本技能基于阿里巴巴Java开发手册P3C规范，对代码进行全面的质量检查测试。

## 测试范围

本测试技能涵盖以下P3C规范领域：

### 1. 代码风格规范 (p3c-coding-style)
- 命名风格：类名、方法名、变量名、常量命名规范
- 代码格式：大括号、缩进、空格、行长度等格式规范
- 常量定义：魔法值、Long类型、常量分类
- 注释规约：Javadoc规范、注释语言、注释同步更新

### 2. 异常与日志规范 (p3c-exception-logging)
- 异常处理：异常捕获原则、异常处理要求、NPE防护
- 日志规约：日志框架、日志保存、日志输出、日志级别

### 3. 高级编程规范 (p3c-advanced-coding)
- 集合处理：hashCode和equals、subList使用、集合转数组、foreach循环
- 并发处理：线程池、锁性能、死锁预防、并发更新
- 控制语句：switch语句、大括号使用、if-else优化

### 4. MySQL数据库规范 (p3c-mysql-database)
- 建表规约：字段要求、表名要求、索引命名
- SQL语句规约：count使用、in操作、分页查询
- 索引规约：唯一索引、join限制、索引长度
- ORM映射规约：查询字段、参数绑定、事务管理

### 5. OOP编程规范 (p3c-oop-standards)
- 方法覆写：@Override注解、equals方法、包装类比较
- 序列化：serialVersionUID、toString方法
- 访问控制：类成员访问控制、final关键字使用

### 6. 安全规约 (p3c-security-rules)
- 权限控制：水平权限校验、数据脱敏
- SQL注入防护：参数绑定、字符串拼接
- XSS/CSRF防护：安全过滤、防重放限制
- 参数验证：有效性验证、防刷策略

### 7. 单元测试规范 (p3c-unit-testing)
- AIR原则：自动化、独立性、可重复性
- 测试粒度：方法级别测试、核心业务测试
- 测试覆盖率：语句覆盖率、分支覆盖率
- BCDE原则：边界值、正确输入、设计文档、错误输入

## 使用时机

- 功能开发完成后
- 需求变更后
- Bug修复后
- 回归测试
- 代码提交前

## 执行方式

本技能使用 Trae IDE 内置工具进行代码质量检查，无需额外脚本：

### 基本测试流程
1. **查找 Java 文件**：使用 `Glob` 工具查找所有 `.java` 文件
2. **读取代码内容**：使用 `Read` 工具读取文件内容
3. **代码结构分析**：使用 `SearchCodebase` 进行代码结构分析
4. **获取编译诊断**：使用 `GetDiagnostics` 获取编译错误和警告
5. **正则匹配检查**：使用 `Grep` 工具配合正则表达式匹配 P3C 规范违规
6. **调用子技能**：调用以下子技能进行详细检查
   - p3c-coding-style
   - p3c-exception-logging
   - p3c-advanced-coding
   - p3c-mysql-database
   - p3c-oop-standards
   - p3c-security-rules
   - p3c-unit-testing
7. **生成测试报告**：使用 `Write` 工具生成 Markdown 格式报告

### 常用 Trae IDE 内置工具

**文件查找工具**
- `Glob` - 查找所有 `.java` 文件
- `LS` - 列出目录结构

**代码读取工具**
- `Read` - 读取文件内容
- `SearchCodebase` - 搜索代码库中的特定模式和结构

**代码分析工具**
- `Grep` - 使用正则表达式搜索代码，匹配 P3C 规则
- `GetDiagnostics` - 获取 Trae IDE 的语言诊断信息（编译错误、警告等）

**报告生成工具**
- `Write` - 生成 Markdown 格式的测试报告

### 子技能说明

本技能是聚合技能，会调用以下子技能进行详细检查：

| 子技能 | 描述 | 检查内容 |
|--------|------|---------|
| p3c-coding-style | 代码风格规范 | 命名风格、代码格式、常量定义、注释规约 |
| p3c-exception-logging | 异常与日志规范 | 异常处理、日志规约、NPE防护 |
| p3c-advanced-coding | 高级编程规范 | 集合处理、并发处理、控制语句 |
| p3c-mysql-database | MySQL数据库规范 | 建表规约、SQL语句、索引规约、ORM映射 |
| p3c-oop-standards | OOP编程规范 | 方法覆写、equals/hashCode、包装类、序列化 |
| p3c-security-rules | 安全规约 | 权限控制、SQL注入防护、XSS/CSRF防护、参数验证 |
| p3c-unit-testing | 单元测试规范 | AIR原则、测试粒度、测试覆盖率、BCDE原则 |

## 测试执行流程

### 步骤1：代码扫描
使用 Trae IDE 内置工具扫描指定的Java源代码文件或目录：
- 使用 `Glob` 查找所有 `.java` 文件
- 使用 `Read` 读取文件内容
- 使用 `SearchCodebase` 进行代码结构分析
- 使用 `GetDiagnostics` 获取编译诊断信息

### 步骤2：规范检查
根据P3C规范对代码进行逐项检查。本技能是聚合技能，会调用以下子技能进行详细检查：

#### 子技能调用
1. **p3c-coding-style** - 代码风格规范
   - 命名风格：类名、方法名、变量名、常量命名规范
   - 代码格式：大括号、缩进、空格、行长度等格式规范
   - 常量定义：魔法值、Long类型、常量分类
   - 注释规约：Javadoc规范、注释语言、注释同步更新

2. **p3c-exception-logging** - 异常与日志规范
   - 异常处理：异常捕获原则、异常处理要求、NPE防护
   - 日志规约：日志框架、日志保存、日志输出、日志级别

3. **p3c-advanced-coding** - 高级编程规范
   - 集合处理：hashCode和equals、subList使用、集合转数组、foreach循环
   - 并发处理：线程池、锁性能、死锁预防、并发更新
   - 控制语句：switch语句、大括号使用、if-else优化

4. **p3c-mysql-database** - MySQL数据库规范
   - 建表规约：字段要求、表名要求、索引命名
   - SQL语句规约：count使用、in操作、分页查询
   - 索引规约：唯一索引、join限制、索引长度
   - ORM映射规约：查询字段、参数绑定、事务管理

5. **p3c-oop-standards** - OOP编程规范
   - 方法覆写：@Override注解、equals方法、包装类比较
   - 序列化：serialVersionUID、toString方法
   - 访问控制：类成员访问控制、final关键字使用

6. **p3c-security-rules** - 安全规约
   - 权限控制：水平权限校验、数据脱敏
   - SQL注入防护：参数绑定、字符串拼接
   - XSS/CSRF防护：安全过滤、防重放限制
   - 参数验证：有效性验证、防刷策略

7. **p3c-unit-testing** - 单元测试规范
   - AIR原则：自动化、独立性、可重复性
   - 测试粒度：方法级别测试、核心业务测试
   - 测试覆盖率：语句覆盖率、分支覆盖率
   - BCDE原则：边界值、正确输入、设计文档、错误输入

#### 检查方法
使用 `Grep` 工具配合正则表达式匹配代码中的P3C规范违规：
- **强制规范**：必须遵守，违反即视为严重问题
- **推荐规范**：建议遵守，违反视为一般问题
- **参考规范**：可选择性遵守，违反视为轻微问题

### 步骤3：问题分类
将检查到的问题按严重程度分类：
- **致命问题**：违反强制规范，可能导致严重后果
- **严重问题**：违反强制规范，影响代码质量
- **一般问题**：违反推荐规范，影响代码可维护性
- **轻微问题**：违反参考规范，属于优化建议

### 步骤4：生成测试报告
使用 `Write` 工具生成详细的测试报告，包含：
- 测试范围和测试时间
- 问题统计（按严重程度和规范类别）
- 问题详情列表
- 改进建议

## 输入参数

执行测试时需要提供以下参数：

1. **代码路径**：要检查的Java源代码文件或目录路径
2. **业务名称**：用于生成报告路径和文件名
3. **测试内容**：描述本次测试的具体内容
4. **测试接口/模块名称**：被测试的接口或模块名称

## 测试报告格式

测试报告将生成到以下路径：
```
doc/{业务名称}/测试报告/{测试内容}/{测试接口名称}_{时间戳}.md
```

报告包含以下内容：

### 报告头部
- 测试时间
- 测试人员
- 测试范围
- 测试工具

### 问题统计
- 问题总数
- 致命问题数量
- 严重问题数量
- 一般问题数量
- 轻微问题数量

### 问题分类统计
按P3C规范类别统计问题分布

### 问题详情列表
每个问题包含：
- 问题编号
- 严重程度
- 规范类别
- 规则描述
- 代码位置（文件名、行号）
- 问题说明
- 修改建议

### 改进建议
- 高优先级改进项
- 中优先级改进项
- 低优先级改进项

### 质量评估
- 代码质量评分
- 符合度百分比
- 风险评估

## 使用示例

### 示例 1：检查单个文件
```
输入：
- 代码路径：src/main/java/com/example/UserService.java
- 业务名称：用户管理
- 测试内容：代码质量检查
- 测试接口名称：UserService

输出：
- 报告路径：doc/用户管理/测试报告/代码质量检查/UserService_20250103143025.md
```

### 示例 2：检查整个模块
```
输入：
- 代码路径：src/main/java/com/example/order/
- 业务名称：订单系统
- 测试内容：代码质量检查
- 测试接口名称：OrderModule

输出：
- 报告路径：doc/订单系统/测试报告/代码质量检查/OrderModule_20250103143025.md
```

### 示例 3：完整测试报告样例
```markdown
# P3C 代码质量检查报告

## 基本信息
- 测试时间：2026-03-11 14:30:25
- 测试人员：AI Assistant
- 测试范围：src/main/java/com/bgyfw/parking/
- P3C 版本：《阿里巴巴 Java 开发手册》2022 版

## 问题统计
- 问题总数：15
- 致命问题：2
- 严重问题：5
- 一般问题：6
- 轻微问题：2

## 问题详情

### 致命问题
【问题编号】P3C-001
【严重程度】致命
【规范类别】p3c-security-rules
【规则描述】SQL 注入防护 - 禁止使用字符串拼接 SQL
【代码位置】RefundOrderController.java:45
【问题说明】发现使用字符串拼接 SQL 语句，存在 SQL 注入风险
【修改建议】使用参数化查询或 MyBatis 的#{param} 方式

### 严重问题
【问题编号】P3C-002
【严重程度】严重
【规范类别】p3c-exception-logging
【规则描述】异常处理 - 禁止捕获 Exception 后不做任何处理
【代码位置】RefundOrderServiceImpl.java:78
【问题说明】catch 块中仅打印日志，未进行异常传播或返回错误状态
【修改建议】抛出运行时异常或返回明确的错误响应

### 一般问题
【问题编号】P3C-003
【严重程度】一般
【规范类别】p3c-coding-style
【规则描述】命名风格 - 方法名应使用动词 + 名词形式
【代码位置】RefundOrder.java:23
【问题说明】方法名"status"不够清晰，无法表达是获取状态还是设置状态
【修改建议】修改为 getStatus() 或 setStatus()

### 轻微问题
【问题编号】P3C-004
【严重程度】轻微
【规范类别】p3c-coding-style
【规则描述】注释规约 - 公共方法应有 Javadoc 注释
【代码位置】RefundOrderMapper.java:15
【问题说明】selectById 方法缺少 Javadoc 注释
【修改建议】添加/** */格式的 Javadoc 注释
```

## 常见违规案例

### 案例 1：魔法值
```java
// ❌ 错误示例
if (status == 1) {
    // ...
}

// ✅ 正确示例
public static final int STATUS_ACTIVE = 1;
if (status == STATUS_ACTIVE) {
    // ...
}
```

### 案例 2：NPE 防护
```java
// ❌ 错误示例
String name = user.getName();
if (name.equals("admin")) {
    // ...
}

// ✅ 正确示例
if ("admin".equals(user.getName())) {
    // ...
}
```

### 案例 3：线程池使用
```java
// ❌ 错误示例
ExecutorService executor = Executors.newCachedThreadPool();

// ✅ 正确示例
ExecutorService executor = new ThreadPoolExecutor(
    corePoolSize,
    maximumPoolSize,
    keepAliveTime,
    TimeUnit.SECONDS,
    new LinkedBlockingQueue<>(capacity),
    new ThreadFactoryBuilder().setNameFormat("custom-%d").build(),
    new ThreadPoolExecutor.CallerRunsPolicy()
);
```

## 检查规则说明

### 强制规范检查（必须遵守）
以下规范违反将导致**致命**或**严重**问题：

#### 1. 安全规约（致命级别）
- 【P3C-SEC-001】禁止使用字符串拼接 SQL 语句，必须使用参数化查询
- 【P3C-SEC-002】涉及用户敏感数据必须进行脱敏处理
- 【P3C-SEC-003】接口必须进行参数有效性验证，防止恶意输入
- 【P3C-SEC-004】禁止硬编码密码、密钥等敏感信息

#### 2. 异常处理（严重级别）
- 【P3C-EXC-001】禁止捕获 Exception 后不做任何处理（空 catch）
- 【P3C-EXC-002】禁止使用 printStackTrace()，必须使用日志框架
- 【P3C-EXC-003】事务方法中必须进行异常传播，不能吞掉异常
- 【P3C-EXC-004】NPE 防护：使用 equals 时常量在前，或使用 Objects.equals()

#### 3. 并发处理（严重级别）
- 【P3C-CON-001】禁止使用 Executors 创建线程池，必须使用 ThreadPoolExecutor
- 【P3C-CON-002】线程池必须指定拒绝策略
- 【P3C-CON-003】SimpleDateFormat 非线程安全，禁止在多线程环境下直接使用
- 【P3C-CON-004】集合类遍历时禁止直接修改集合结构

#### 4. 数据库规范（严重级别）
- 【P3C-DB-001】表必备字段：id（主键）、gmt_create（创建时间）、gmt_modified（修改时间）
- 【P3C-DB-002】禁止使用物理删除，必须使用逻辑删除
- 【P3C-DB-003】SQL 查询必须使用索引优化，禁止全表扫描
- 【P3C-DB-004】count(*) 用于统计行数，count(列名) 用于统计非 NULL 值

#### 5. 代码风格（严重级别）
- 【P3C-STY-001】类名：UpperCamelCase（DO/BO/DTO/VO 等后缀大写）
- 【P3C-STY-002】方法名、变量名：lowerCamelCase
- 【P3C-STY-003】常量名：UPPER_CASE，用下划线分隔
- 【P3C-STY-004】禁止魔法值，必须定义常量

#### 6. OOP 规范（严重级别）
- 【P3C-OOP-001】覆写 equals 必须同时覆写 hashCode
- 【P3C-OOP-002】包装类比较必须使用 equals，禁止使用==
- 【P3C-OOP-003】类必须有访问控制符，成员变量必须是 private
- 【P3C-OOP-004】POJO 类必须实现 Serializable 接口

#### 7. 单元测试（严重级别）
- 【P3C-TST-001】测试方法必须使用@Test注解
- 【P3C-TST-002】测试类必须遵循*Test命名规范
- 【P3C-TST-003】核心业务逻辑必须有单元测试覆盖

### 推荐规范检查（建议遵守）
以下规范违反将导致**一般**问题：

#### 1. 注释完整性
- 【P3C-CMT-001】公共方法应有 Javadoc 注释
- 【P3C-CMT-002】复杂算法、业务逻辑应有详细注释
- 【P3C-CMT-003】注释语言应与项目一致（中文项目用中文）

#### 2. 代码可读性
- 【P3C-RED-001】方法长度不超过 80 行
- 【P3C-RED-002】单行代码不超过 120 个字符
- 【P3C-RED-003】避免过深的嵌套（不超过 4 层）
- 【P3C-RE