leniu-dev 2.0.0

package/.claude/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/.claude/skills/chrome-cdp/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: chrome-cdp
+description: 通过 Chrome DevTools Protocol 与本地 Chrome 浏览器交互（截图、导航、点击、执行JS等）
+---
+
+# Chrome CDP
+
+轻量级 Chrome DevTools Protocol CLI 工具。通过 WebSocket 直接连接 Chrome 浏览器 —— 无需 Puppeteer，支持 100+ 标签页，即时连接。
+
+## 前置条件
+
+- Chrome 已启用远程调试：打开 `chrome://inspect/#remote-debugging` 并开启开关
+- Node.js 22+（使用内置 WebSocket）—— 通过 nvm 自动切换
+
+## 脚本路径
+
+所有命令通过包装脚本执行（自动切换 Node.js 23）：
+
+```bash
+CDP="/Users/xujiajun/Developer/ai-engineering-init/.claude/skills/chrome-cdp/scripts/run-cdp.sh"
+```
+
+## 命令速查
+
+### 列出打开的页面
+
+```bash
+bash $CDP list
+```
+
+### 截图
+
+```bash
+bash $CDP shot <target> [file]    # 默认: /tmp/screenshot.png
+```
+
+截取**视口**。需要滚动后内容时先用 `eval` 滚动。输出包含 DPR 和坐标转换提示。
+
+### 可访问性树快照
+
+```bash
+bash $CDP snap <target>
+```
+
+### 执行 JavaScript
+
+```bash
+bash $CDP eval <target> <expr>
+```
+
+> **注意：** 避免跨多次 `eval` 调用使用基于索引的选择器（`querySelectorAll(...)[i]`），因为 DOM 可能在调用间变化。应在一次 `eval` 中收集所有数据或使用稳定选择器。
+
+### 其他命令
+
+```bash
+bash $CDP html    <target> [selector]   # 完整页面或元素 HTML
+bash $CDP nav     <target> <url>        # 导航并等待加载
+bash $CDP net     <target>              # 资源加载计时
+bash $CDP click   <target> <selector>   # 通过 CSS 选择器点击元素
+bash $CDP clickxy <target> <x> <y>      # 在 CSS 像素坐标处点击
+bash $CDP type    <target> <text>       # 在焦点元素处输入文本
+bash $CDP loadall <target> <selector> [ms]  # 点击"加载更多"直到消失
+bash $CDP evalraw <target> <method> [json]  # 原始 CDP 命令透传
+bash $CDP stop    [target]              # 停止守护进程
+```
+
+## 坐标系统
+
+`shot` 以原生分辨率保存图片：图片像素 = CSS 像素 x DPR。CDP 输入事件（`clickxy` 等）使用 **CSS 像素**。
+
+```
+CSS px = 截图图片 px / DPR
+```
+
+`shot` 会输出当前页面的 DPR。典型 Retina (DPR=2)：截图坐标除以 2。
+
+## 使用技巧
+
+- 优先使用 `snap --compact` 而非 `html` 来查看页面结构
+- 使用 `type`（而非 eval）在跨域 iframe 中输入文本 —— 先用 `click`/`clickxy` 聚焦，再用 `type`
+- Chrome 在首次访问标签页时显示"允许调试"弹窗。后台守护进程会保持会话，后续命令无需再次确认。守护进程在 20 分钟无活动后自动退出