ai-engineering-init 1.4.3 → 1.6.0

package/src/skills/bug-detective/references/error-patterns.md

@@ -0,0 +1,242 @@
+# Bug 排查详细错误案例库
+
+> 本文件是 `bug-detective` 技能的参考文档，包含完整的错误排查案例。
+
+## 1. NullPointerException 详细排查
+
+```java
+// 常见场景
+User user = baseMapper.selectById(id);  // 可能返回 null
+user.getName();  // NPE
+
+// 修复方案
+XxxEntity entity = Optional.ofNullable(xxxMapper.selectById(id))
+    .orElseThrow(() -> new LeException("记录不存在"));
+```
+
+**本项目常见 NPE 位置**:
+- `xxxMapper.selectById(id)` 返回 null
+- `BeanUtil.copyProperties()` 源对象为 null
+- 链式调用中间某环节为 null
+
+---
+
+## 2. SQL 异常详细排查
+
+```sql
+-- 检查表是否存在
+SHOW TABLES LIKE 'xxx_table';
+
+-- 检查字段
+DESC xxx_table;
+
+-- 直接执行验证
+SELECT * FROM xxx_table WHERE id = 1;
+
+-- 唯一键冲突检查
+SELECT * FROM xxx_table WHERE unique_field = 'value';
+```
+
+---
+
+## 3. 权限问题详细排查
+
+```java
+// 1. 检查认证注解
+@RequiresAuthentication  // leniu 项目使用此注解
+@RequiresGuest           // 免登录接口
+
+// 2. 检查请求头
+// Admin-Token: xxx (localStorage)
+// MERCHANT-ID: xxx (租户标识)
+```
+
+---
+
+## 4. 事务问题详细排查
+
+```java
+// 1. 是否加了事务注解
+@Transactional(rollbackFor = Exception.class)
+
+// 2. 异常是否被 try-catch 吞掉
+try {
+    // 操作
+} catch (Exception e) {
+    log.error("错误", e);
+    throw e;  // 必须重新抛出，否则事务不回滚
+}
+
+// 3. 是否在非 public 方法上使用（不生效）
+@Transactional  // private 方法不生效
+private void doSomething() {}
+
+// 4. 同类调用是否通过 self
+@Autowired @Lazy
+private XxxBusiness self;
+self.transactionalMethod();  // 通过代理调用
+```
+
+---
+
+## 5. 日志分析完整示例
+
+### 场景：接口报 500
+
+```
+AI 执行步骤：
+1. Read ./logs/sys-console.log
+   -> 找到最后一个 ERROR：NullPointerException at XxxService.java:45
+
+2. Read 对应源文件第 45 行
+   -> 代码：user.getName()
+
+3. 分析日志中的 SQL
+   -> SELECT * FROM xxx WHERE id = 999 返回空
+
+4. 数据库验证
+   -> 确认 ID 999 不存在
+
+5. 诊断：用户不存在时代码未判空
+   -> 解决：添加 Optional 判空
+```
+
+### 场景：查询慢
+
+```
+1. 搜索 SQL 日志
+   grep "p6spy" ./logs/sys-console.log
+
+2. 分析 Cost 耗时
+   - Cost < 50ms -> 正常
+   - Cost 50-200ms -> 关注
+   - Cost > 200ms -> 优化
+
+3. 检查 N+1 查询
+4. 建议添加索引或批量查询
+```
+
+### 场景：租户数据问题
+
+```
+1. 搜索 SQL 日志中的查询语句
+2. 检查是否使用了正确的 Executors 切换
+   - Executors.doInSystem() -> 系统库
+   - 默认 -> 商户库（根据 MERCHANT-ID）
+3. 对比实际数据
+```
+
+---
+
+## 6. 前端问题排查
+
+### 接口调用失败
+
+| 状态码 | 含义 | 解决 |
+|--------|------|------|
+| 400 | 参数错误 | 检查参数类型格式 |
+| 401 | 未认证 | 检查 Admin-Token (localStorage) |
+| 403 | 无权限 | 检查角色权限、v-hasPerm |
+| 404 | 接口不存在 | 检查 URL、后端是否启动 |
+| 500 | 服务端错误 | 查后端日志 |
+
+### 前端特有问题
+
+```javascript
+// 前端成功码是 10000（非 200）
+if (res.code === 10000) { ... }
+
+// 金额单位是分，展示需转元
+money(amountInFen)
+
+// 加密使用 SM4
+```
+
+---
+
+## 7. 数据库排查 SQL 模板
+
+### 数据关联检查
+
+```sql
+SELECT a.*, b.*
+FROM table_a a
+LEFT JOIN table_b b ON a.id = b.a_id
+WHERE a.id = ?;
+```
+
+### 重复数据检查
+
+```sql
+SELECT id, COUNT(*) FROM 表 GROUP BY id HAVING COUNT(*) > 1;
+```
+
+### 孤立数据检查
+
+```sql
+SELECT a.id FROM 主表 a
+LEFT JOIN 子表 b ON a.id = b.主表id
+WHERE b.id IS NULL;
+```
+
+### 性能检查
+
+```sql
+-- 执行计划
+EXPLAIN SELECT * FROM 表 WHERE 条件;
+
+-- type: ALL(全表扫描需优化) | index | range | ref | const(最优)
+
+-- 检查索引
+SHOW INDEX FROM 表;
+```
+
+---
+
+## 8. 多数据库差异
+
+| 功能 | MySQL | PostgreSQL |
+|------|-------|------------|
+| 分页 | `LIMIT 10` | `LIMIT 10` |
+| 字符串连接 | `CONCAT()` | `||` |
+| 当前时间 | `NOW()` | `NOW()` |
+| 类型转换 | `CAST()` | `::` |
+
+---
+
+## 9. Bean 注入失败排查
+
+```java
+// NoSuchBeanDefinitionException 排查步骤：
+// 1. 检查是否有 @Service/@Component
+@Service
+public class XxxServiceImpl implements XxxService { ... }
+
+// 2. 检查包路径（必须 net.xnzn.core.*）
+package net.xnzn.core.xxx.service.impl;
+
+// 3. 检查循环依赖（A->B->A）
+// 4. 检查接口与实现类是否匹配
+```
+
+---
+
+## 10. 排查清单
+
+### 后端
+
+- [ ] 是否读取了日志文件 `./logs/sys-console.log`？
+- [ ] 异常堆栈包名是否为 `net.xnzn.core.*`？
+- [ ] Controller 路由前缀是否正确（`/api/v2/web|mobile|android/{module}`）？
+- [ ] Service 是否直接注入 Mapper（无 DAO 层）？
+- [ ] 非字符串字段是否使用了 eq/in/between 而不是 like？
+- [ ] BeanUtil.copyProperties() 转换前是否判空？
+- [ ] 双库切换是否正确（Executors.doInSystem/doInTenant）？
+- [ ] del_flag 是否用 2=正常、1=删除？
+- [ ] 数据库中是否真的存在需要的数据？
+
+### 前端
+
+- [ ] Network 中接口状态码和响应内容？
+- [ ] 成功码是否判断 10000？
+- [ ] Admin-Token 和 MERCHANT-ID 请求头是否正确？

package/src/skills/check/SKILL.md

@@ -0,0 +1,367 @@
+---
+name: check
+description: |
+  当需要检查后端代码规范、验证代码质量时自动使用此 Skill。
+
+  触发场景：
+  - 开发完成后检查代码是否符合规范
+  - 代码审查前进行规范检查
+  - 检查包名、API路径、权限注解等规范
+  - 检查对象转换是否使用 MapstructUtils
+
+  触发词：代码检查、check、规范检查、代码规范、代码审查、包名检查、API检查、权限检查
+---
+
+# /check - 后端代码规范检查
+
+作为代码规范检查助手，自动检测项目代码是否符合 RuoYi-Vue-Plus 后端规范。
+
+## 检查范围
+
+支持三种检查模式：
+
+1. **全量检查**：`/check` - 检查所有代码
+2. **模块检查**：`/check system` - 检查指定模块
+3. **文件检查**：`/check XxxServiceImpl.java` - 检查指定文件
+
+---
+
+## 检查清单总览
+
+| 检查项 | 级别 | 说明 |
+|--------|------|------|
+| 包名规范 | 🔴 严重 | 必须是 `org.dromara.*` |
+| 完整类型引用 | 🔴 严重 | 禁止内联全限定名，必须 import |
+| API 路径规范 | 🔴 严重 | Controller 方法路径必须规范 |
+| 权限注解检查 | 🟡 警告 | 必须使用 @SaCheckPermission |
+| Service 接口 | 🟡 警告 | Service 接口必须有标准方法声明 |
+| Entity 基类 | 🟡 警告 | 业务实体应继承 TenantEntity |
+| BO 映射注解 | 🟡 警告 | 必须使用 @AutoMapper |
+| 对象转换 | 🟡 警告 | 必须用 MapstructUtils，禁止 BeanUtil |
+| Mapper 继承 | 🟢 建议 | 必须继承 BaseMapperPlus |
+| Map 传递数据 | 🟢 建议 | 禁止用 Map 封装业务数据 |
+
+---
+
+## 检查详情
+
+### 1. 包名规范 [🔴 严重]
+
+```bash
+# 检查错误包名
+Grep pattern: "package com\.ruoyi\." path: ruoyi-modules/ output_mode: files_with_matches
+Grep pattern: "import com\.ruoyi\." path: ruoyi-modules/ output_mode: files_with_matches
+```
+
+```java
+// ❌ 错误
+package com.ruoyi.system.service;
+import com.ruoyi.common.core.domain.R;
+
+// ✅ 正确
+package org.dromara.system.service;
+import org.dromara.common.core.domain.R;
+```
+
+### 2. 完整类型引用 [🔴 严重]
+
+```bash
+# 检查完整类型引用
+Grep pattern: "org\.dromara\.[a-z]+\.[A-Z][a-zA-Z]+\s" path: ruoyi-modules/ glob: "*.java" output_mode: content
+```
+
+```java
+// ❌ 错误
+public org.dromara.common.core.domain.R<XxxVo> getXxx(Long id) { ... }
+
+// ✅ 正确
+import org.dromara.common.core.domain.R;
+public R<XxxVo> getXxx(Long id) { ... }
+```
+
+### 3. API 路径规范 [🔴 严重]
+
+```bash
+# 检查 Controller 方法的路径规范
+Grep pattern: "@(GetMapping|PostMapping|PutMapping|DeleteMapping)\(" path: ruoyi-modules/ glob: "*Controller.java" output_mode: content -C 1
+```
+
+**规范要求**：
+
+| 操作 | HTTP 方法 | 路径格式 | 示例 |
+|------|---------|--------|------|
+| 分页查询 | GET | `/list` 或 `/` 空路径 | `@GetMapping("/list")` |
+| 获取详情 | GET | `/{id}` | `@GetMapping("/{id}")` |
+| 新增 | POST | `/` 空路径 | `@PostMapping` |
+| 修改 | PUT | `/` 空路径 | `@PutMapping` |
+| 删除 | DELETE | `/{ids}` | `@DeleteMapping("/{ids}")` |
+| 导出 | POST | `/export` | `@PostMapping("/export")` |
+
+```java
+// ❌ 错误（路径不规范）
+@GetMapping("/queryList")  // 应该用 /list
+@PostMapping("/add")       // POST 应该不加路径
+@PutMapping("/update")     // PUT 应该不加路径
+
+// ✅ 正确
+@GetMapping("/list")
+@PostMapping
+@PutMapping
+@DeleteMapping("/{ids}")
+```
+
+### 4. 权限注解检查 [🟡 警告]
+
+```bash
+# 检查 Controller 是否使用权限注解
+Grep pattern: "@SaCheckPermission" path: ruoyi-modules/ glob: "*Controller.java" output_mode: files_with_matches
+Grep pattern: "public.*\(.*\)\s*\{" path: ruoyi-modules/ glob: "*Controller.java" output_mode: content -B 1
+```
+
+**规范要求**：Controller 的所有公开接口都必须添加 `@SaCheckPermission` 注解
+
+```java
+// ❌ 错误（缺少权限注解）
+@GetMapping("/list")
+public TableDataInfo<XxxVo> list(XxxBo bo, PageQuery pageQuery) {
+    return service.queryPageList(bo, pageQuery);
+}
+
+// ✅ 正确
+@SaCheckPermission("xxx:list")
+@GetMapping("/list")
+public TableDataInfo<XxxVo> list(XxxBo bo, PageQuery pageQuery) {
+    return service.queryPageList(bo, pageQuery);
+}
+```
+
+### 5. Service 接口 [🟡 警告]
+
+```bash
+# 检查 Service 接口是否声明标准方法
+Grep pattern: "public interface I.*Service" path: ruoyi-modules/ glob: "*Service.java" output_mode: files_with_matches
+```
+
+**规范要求**：Service 接口必须声明以下标准方法
+
+```java
+// ✅ 正确
+public interface IXxxService {
+    XxxVo queryById(Long id);
+    TableDataInfo<XxxVo> queryPageList(XxxBo bo, PageQuery pageQuery);
+    List<XxxVo> queryList(XxxBo bo);
+    Boolean insertByBo(XxxBo bo);
+    Boolean updateByBo(XxxBo bo);
+    Boolean deleteByIds(Collection<Long> ids);
+}
+```
+
+### 6. Entity 基类 [🟡 警告]
+
+```bash
+# 检查业务实体是否继承 TenantEntity
+Grep pattern: "extends TenantEntity" path: ruoyi-modules/ glob: "*.java" output_mode: files_with_matches
+Grep pattern: "extends BaseEntity" path: ruoyi-modules/ glob: "*.java" output_mode: files_with_matches
+```
+
+```java
+// ⚠️ 普通实体（非多租户）
+public class SysNotice extends BaseEntity { }
+
+// ✅ 业务实体（多租户）
+public class XxxEntity extends TenantEntity { }
+```
+
+### 7. BO 映射注解 [🟡 警告]
+
+```bash
+# 检查 BO 是否使用 @AutoMapper
+Grep pattern: "@AutoMapper" path: ruoyi-modules/ glob: "*Bo.java" output_mode: files_with_matches
+```
+
+```java
+// ❌ 错误
+public class XxxBo extends BaseEntity { }
+
+// ✅ 正确
+@AutoMapper(target = Xxx.class, reverseConvertGenerate = false)
+public class XxxBo extends BaseEntity { }
+```
+
+### 8. 对象转换 [🟡 警告]
+
+```bash
+# 检查是否使用 BeanUtil
+Grep pattern: "BeanUtil\.copy" path: ruoyi-modules/ output_mode: files_with_matches
+Grep pattern: "BeanUtils\.copy" path: ruoyi-modules/ output_mode: files_with_matches
+```
+
+```java
+// ❌ 错误
+BeanUtil.copyProperties(bo, entity);
+BeanUtils.copyProperties(source, target);
+
+// ✅ 正确
+XxxVo vo = MapstructUtils.convert(entity, XxxVo.class);
+List<XxxVo> voList = MapstructUtils.convert(entityList, XxxVo.class);
+```
+
+### 9. Mapper 继承 [🟢 建议]
+
+```bash
+Grep pattern: "extends BaseMapperPlus" path: ruoyi-modules/ output_mode: files_with_matches
+```
+
+```java
+// ✅ 正确
+public interface XxxMapper extends BaseMapperPlus<Xxx, XxxVo> { }
+```
+
+### 10. Map 传递数据 [🟢 建议]
+
+```bash
+Grep pattern: "Map<String,\s*Object>" path: ruoyi-modules/ glob: "*Service*.java" output_mode: files_with_matches
+```
+
+```java
+// ❌ 错误
+public Map<String, Object> getXxx(Long id) {
+    Map<String, Object> result = new HashMap<>();
+    result.put("id", entity.getId());
+    return result;
+}
+
+// ✅ 正确（创建 VO 类）
+public XxxVo getXxx(Long id) {
+    return MapstructUtils.convert(entity, XxxVo.class);
+}
+```
+
+---
+
+## 输出格式
+
+```markdown
+# 🔍 代码规范检查报告
+
+**检查时间**：YYYY-MM-DD HH:mm
+**检查范围**：[全量 / 模块名 / 文件名]
+
+---
+
+## 📋 检查结果汇总
+
+| 类别 | 通过 | 警告 | 错误 |
+|------|------|------|------|
+| 后端 Java | X | X | X |
+
+---
+
+## 🔴 严重问题（必须修复）
+
+### 1. [问题类型]
+
+**文件**：`path/to/file.java:42`
+**问题**：包名使用了 com.ruoyi
+**代码**：
+\```java
+package com.ruoyi.system.service;
+\```
+**修复**：
+\```java
+package org.dromara.system.service;
+\```
+
+---
+
+## 🟡 警告问题（建议修复）
+
+### 1. [问题类型]
+...
+
+---
+
+## 🟢 建议优化
+
+### 1. [优化建议]
+...
+
+---
+
+## ✅ 检查通过项
+
+- [x] 包名规范
+- [x] 对象转换
+- ...
+```
+
+---
+
+## 检查优先级
+
+### 开发完成后必查（阻塞提交）
+
+1. 包名是否是 `org.dromara.*`
+2. 是否有完整类型引用（内联全限定名）
+3. API 路径是否规范
+4. 对象转换是否使用 MapstructUtils
+5. 权限注解是否完整
+
+### 代码审查建议查
+
+1. Service 接口是否有标准方法声明
+2. BO 是否有 @AutoMapper
+3. Entity 是否继承正确的基类
+4. Mapper 是否继承 BaseMapperPlus
+5. 是否有冗余的 Map 传递
+
+---
+
+## 快速修复指南
+
+### 包名错误修复
+
+```bash
+# 查找所有错误包名
+Grep pattern: "package com\.ruoyi\." path: ruoyi-modules/ output_mode: files_with_matches
+```
+
+批量替换：`com.ruoyi` → `org.dromara`
+
+### API 路径修复
+
+| 错误写法 | 正确写法 | 说明 |
+|---------|--------|------|
+| `@GetMapping("/queryList")` | `@GetMapping("/list")` | 列表查询统一用 /list |
+| `@PostMapping("/add")` | `@PostMapping` | POST 新增不加路径 |
+| `@PutMapping("/update")` | `@PutMapping` | PUT 修改不加路径 |
+| `@GetMapping` | `@GetMapping("/{id}")` | 单条查询必须加 ID 参数 |
+
+### 权限注解修复
+
+```java
+// 快速修复模板
+@SaCheckPermission("模块:功能:操作")
+@GetMapping("/list")
+public TableDataInfo<XxxVo> list(...) { ... }
+
+// 权限标识符格式
+// system:notice:list       - 系统模块的通知管理-列表权限
+// demo:xxx:add             - demo 模块的 xxx 功能-新增权限
+// 模块:功能:操作            - [模块]:[功能]:[操作]
+```
+
+### 对象转换修复
+
+| 替换前 | 替换后 |
+|--------|--------|
+| `BeanUtil.copyProperties(a, b)` | `MapstructUtils.convert(a, B.class)` |
+| `BeanUtils.copyProperties(a, b)` | `MapstructUtils.convert(a, B.class)` |
+| `new HashMap<>()` (传递业务数据) | 创建专属 VO 类 |
+
+---
+
+## 参考
+
+- 正确后端代码：`ruoyi-system/.../controller/system/SysNoticeController.java`
+- 正确 Service 代码：`ruoyi-system/.../service/impl/SysNoticeServiceImpl.java`