leniu-dev 2.0.0

package/.cursor/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/.cursor/skills/code-patterns/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: code-patterns
+description: |
+  通用编码规范指南。涵盖 RESTful API 设计、命名规范、Git 提交规范、代码风格等。
+  触发场景：代码审查、规范检查、命名讨论、API 设计。
+  触发词：编码规范、代码风格、命名规范、RESTful、Git 提交。
+  注意：如果项目有专属技能（如 `leniu-code-patterns`），优先使用专属版本。
+---
+
+# 编码规范指南
+
+> 通用模板。如果项目有专属技能（如 `leniu-code-patterns`），优先使用。
+
+## 核心规范
+
+### RESTful API 设计
+
+| 操作 | HTTP 方法 | URL 示例 | 说明 |
+|------|----------|---------|------|
+| 创建 | POST | `/api/v1/orders` | 请求体传参 |
+| 查询列表 | GET | `/api/v1/orders` | Query 参数分页 |
+| 查询详情 | GET | `/api/v1/orders/{id}` | 路径参数 |
+| 全量更新 | PUT | `/api/v1/orders/{id}` | 请求体传参 |
+| 部分更新 | PATCH | `/api/v1/orders/{id}` | 请求体传参 |
+| 删除 | DELETE | `/api/v1/orders/{id}` | 路径参数 |
+
+**URL 规范**：
+- 使用名词复数：`/orders` 而非 `/order`
+- 使用小写连字符：`/order-items` 而非 `/orderItems`
+- 版本号放 URL 前缀：`/api/v1/`
+- 嵌套资源不超过两层：`/orders/{id}/items`
+
+### 命名规范
+
+| 类型 | 风格 | 示例 |
+|------|------|------|
+| 类名 | UpperCamelCase | `OrderService`, `UserController` |
+| 方法名 | lowerCamelCase | `createOrder()`, `getUserById()` |
+| 变量名 | lowerCamelCase | `orderNo`, `userName` |
+| 常量 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT`, `DEFAULT_PAGE_SIZE` |
+| 包名 | 全小写 | `com.example.order` |
+| 数据库表/字段 | lower_snake_case | `t_order`, `order_no` |
+
+**类命名约定**：
+
+| 后缀 | 用途 | 示例 |
+|------|------|------|
+| `Controller` | 控制器 | `OrderController` |
+| `Service` / `ServiceImpl` | 服务层 | `OrderServiceImpl` |
+| `Mapper` / `Repository` | 数据访问 | `OrderMapper` |
+| `DTO` | 请求参数 | `OrderCreateDTO` |
+| `VO` | 响应对象 | `OrderVO` |
+| `Enum` | 枚举 | `OrderStatusEnum` |
+| `Config` | 配置类 | `RedisConfig` |
+| `Handler` | 处理器 | `GlobalExceptionHandler` |
+| `Interceptor` | 拦截器 | `AuthInterceptor` |
+| `Utils` / `Helper` | 工具类 | `DateUtils` |
+
+### 方法命名约定
+
+| 前缀 | 含义 | 示例 |
+|------|------|------|
+| `create` / `add` | 创建 | `createOrder()` |
+| `update` / `modify` | 更新 | `updateStatus()` |
+| `delete` / `remove` | 删除 | `deleteById()` |
+| `get` / `find` / `query` | 查询 | `getById()`, `findByName()` |
+| `list` | 查询列表 | `listByStatus()` |
+| `page` | 分页查询 | `pageQuery()` |
+| `count` | 计数 | `countByStatus()` |
+| `is` / `has` / `can` | 布尔判断 | `isValid()`, `hasPermission()` |
+| `check` / `validate` | 校验 | `checkDuplicate()` |
+| `convert` / `to` | 转换 | `convertToVO()`, `toDTO()` |
+
+### Git 提交规范（Conventional Commits）
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+| type | 说明 |
+|------|------|
+| `feat` | 新功能 |
+| `fix` | 修复 Bug |
+| `docs` | 文档变更 |
+| `style` | 代码格式（不影响逻辑） |
+| `refactor` | 重构（非新功能、非修复） |
+| `perf` | 性能优化 |
+| `test` | 测试相关 |
+| `chore` | 构建/工具变更 |
+
+**示例**：
+```
+feat(order): 新增订单导出功能
+
+支持按时间范围导出订单数据为 Excel 格式。
+
+Closes #123
+```
+
+## 代码示例
+
+### 统一响应格式
+
+```java
+@Data
+@AllArgsConstructor
+@NoArgsConstructor
+public class Result<T> {
+    private int code;
+    private String message;
+    private T data;
+
+    public static <T> Result<T> ok(T data) {
+        return new Result<>(200, "success", data);
+    }
+
+    public static <T> Result<T> fail(int code, String message) {
+        return new Result<>(code, message, null);
+    }
+}
+```
+
+### 枚举定义规范
+
+```java
+@Getter
+@AllArgsConstructor
+public enum OrderStatusEnum {
+
+    PENDING(0, "待处理"),
+    COMPLETED(1, "已完成"),
+    CANCELLED(2, "已取消");
+
+    private final int code;
+    private final String desc;
+
+    public static OrderStatusEnum of(int code) {
+        for (OrderStatusEnum status : values()) {
+            if (status.code == code) {
+                return status;
+            }
+        }
+        throw new IllegalArgumentException("未知状态码: " + code);
+    }
+}
+```
+
+## 常见错误
+
+| 错误 | 正确做法 |
+|------|---------|
+| URL 用动词：`/getOrder` | 用名词 + HTTP 方法：`GET /orders/{id}` |
+| 方法名含义不清：`process()` | 明确动作：`calculateTotalAmount()` |
+| 魔法数字：`if (status == 1)` | 用枚举或常量 |
+| 一个方法超过 80 行 | 拆分为多个私有方法 |
+| 注释描述"做了什么" | 注释描述"为什么这样做" |
+| Git 提交信息写"fix bug" | 写清楚修了什么：`fix(order): 修复金额计算精度丢失` |
+| Boolean 变量名：`flag` | 有意义的名字：`isActive`, `hasPermission` |
+| 缩写命名：`usr`, `mgr` | 完整命名：`user`, `manager` |

package/.cursor/skills/code-patterns/references/leniu-code-patterns.md

@@ -0,0 +1,87 @@
+# leniu-tengyun-core 代码模式详解
+
+## Hutool 工具类完整用法
+
+```java
+import cn.hutool.core.collection.CollUtil;
+import cn.hutool.core.util.ObjectUtil;
+import cn.hutool.core.util.StrUtil;
+import cn.hutool.core.bean.BeanUtil;
+
+// 1. 集合操作
+if (CollUtil.isEmpty(list)) {
+    throw new LeException("列表不能为空");
+}
+if (CollUtil.isNotEmpty(list)) {
+    // 处理列表
+}
+
+// 2. 对象判空
+if (ObjectUtil.isNull(user)) {
+    throw new LeException("用户不存在");
+}
+
+// 3. 字符串操作
+if (StrUtil.isBlank(name)) {
+    throw new LeException("名称不能为空");
+}
+String trimmed = StrUtil.trim(name);
+String joined = StrUtil.join(",", list);
+
+// 4. 对象拷贝
+TargetDTO target = BeanUtil.copyProperties(source, TargetDTO.class);
+List<TargetDTO> targets = BeanUtil.copyToList(sources, TargetDTO.class);
+
+// 5. 集合创建
+List<String> list = CollUtil.newArrayList("a", "b", "c");
+Map<String, Object> map = CollUtil.newHashMap();
+```
+
+## 国际化消息
+
+```java
+import net.xnzn.core.common.i18n.I18n;
+
+// RuoYi-Vue-Plus 风格
+throw new ServiceException(MessageUtils.message("user.not.exists"));
+
+// leniu-tengyun-core 风格
+throw new LeException(I18n.getMessage("user.not.exists"));
+
+// 带参数
+throw new LeException(I18n.getMessage("user.password.retry.limit.exceed", maxRetryCount));
+```
+
+## 租户上下文
+
+```java
+import net.xnzn.core.context.TenantContextHolder;
+
+Long tenantId = TenantContextHolder.getTenantId();
+TenantContextHolder.setTenantId(tenantId);
+TenantContextHolder.clear();
+```
+
+## 分页参数处理
+
+```java
+@Data
+public class XxxQueryParam implements Serializable {
+    @ApiModelProperty(value = "分页参数", required = true)
+    @NotNull(message = "分页参数不能为空")
+    private PageDTO page;
+
+    @ApiModelProperty("关键字")
+    private String keyword;
+
+    @ApiModelProperty("状态")
+    private Integer status;
+}
+
+// Service 层
+public Page<XxxVO> pageList(XxxQueryParam param) {
+    PageMethod.startPage(param.getPage().getPageNum(), param.getPage().getPageSize());
+    List<XxxEntity> list = xxxMapper.selectList(buildWrapper(param));
+    return new Page<>(list);
+}
+```

package/.cursor/skills/collaborating-with-codex/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: collaborating-with-codex
+description: |
+  与 Codex MCP 协同开发。通过 GuDaStudio/codexmcp 集成，使用 mcp__codex__codex 工具。
+  默认沙箱：read-only（严禁 codex 修改真实代码）。
+
+  触发场景：
+  - 需要算法实现或复杂逻辑分析
+  - 需要代码审查和 Bug 分析
+  - 需要生成 Unified Diff 补丁
+  - 用户明确要求使用 Codex 协作
+  - 复杂后端逻辑的原型设计
+
+  触发词：Codex、协作、多模型、原型、Diff、算法分析、代码审查、codex协同
+
+  前置要求：
+  - 已通过 `claude mcp add codex -s user --transport stdio -- uvx --from git+https://github.com/GuDaStudio/codexmcp.git codexmcp` 注册
+  - ~/.claude/settings.json 的 permissions.allow 已加入 mcp__codex__codex
+---
+
+# 与 Codex MCP 协同开发
+
+> 通过 `mcp__codex__codex` 工具直接调用，无需命令行。始终使用 `read-only` 沙箱，要求 codex 只输出 unified diff patch。
+
+---
+
+## MCP 工具说明
+
+### 工具名
+`mcp__codex__codex`
+
+### 参数
+
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `PROMPT` | string | ✅ | - | 发送给 Codex 的任务指令（建议用英语） |
+| `cd` | Path | ✅ | - | 工作目录根路径（必须存在） |
+| `sandbox` | string | ❌ | `read-only` | `read-only` / `workspace-write` / `danger-full-access` |
+| `SESSION_ID` | UUID | ❌ | None | 继续之前的会话，保持上下文 |
+| `return_all_messages` | bool | ❌ | False | 是否返回推理过程和工具调用详情 |
+| `model` | string | ❌ | None | 指定模型（None 使用用户默认配置） |
+| `image` | List[Path] | ❌ | None | 附加图片文件 |
+| `yolo` | bool | ❌ | False | 跳过沙箱审批（危险，不推荐） |
+| `profile` | string | ❌ | None | 从 `~/.codex/config.toml` 加载的配置名 |
+| `skip_git_repo_check` | bool | ❌ | False | 允许在非 Git 仓库中运行 |
+
+### 返回值
+
+```json
+// 成功
+{
+  "success": true,
+  "SESSION_ID": "uuid-string",     // 必须保存，用于多轮交互
+  "agent_messages": "codex回复内容"
+}
+
+// 失败
+{
+  "success": false,
+  "error": "错误信息"
+}
+```
+
+---
+
+## 标准协作流程
+
+```
+1. 需求分析阶段
+   Claude 形成初步分析 → 告知 codex → codex 完善方案
+
+2. 编码前（原型阶段）
+   调用 codex（read-only）→ 要求输出 unified diff patch
+   Claude 以 diff 为逻辑参考 → 重写为生产级代码
+
+3. 编码后（审查阶段）
+   调用 codex review 改动 → 验证需求完成度和代码质量
+```
+
+---
+
+## 调用示例
+
+### 场景一：需求分析完善
+
+```
+PROMPT: "Here is my requirement: [需求描述]. My initial approach: [初步思路].
+Please review and improve the analysis and implementation plan.
+Output: structured analysis with potential risks."
+
+cd: /path/to/project
+sandbox: read-only
+```
+
+### 场景二：获取代码原型（Diff）
+
+```
+PROMPT: "Generate a unified diff patch to implement [功能描述].
+File: [目标文件路径]
+Requirements:
+- [要求1]
+- [要求2]
+
+IMPORTANT: Output unified diff patch ONLY. Do NOT modify any real files.
+IMPORTANT: All Java comments and SQL COMMENTs MUST be in Chinese."
+
+cd: /path/to/project
+sandbox: read-only
+```
+
+### 场景三：代码审查
+
+```
+PROMPT: "Review the following code changes for correctness, performance, and security.
+[粘贴代码或说明文件路径]
+
+Check:
+1. Logic correctness
+2. Edge cases
+3. Performance issues
+4. Security vulnerabilities
+
+Output: review with line numbers and severity (CRITICAL/WARNING/INFO)."
+
+cd: /path/to/project
+sandbox: read-only
+```
+
+### 场景四：多轮交互（继续会话）
+
+```
+// 第一轮
+SESSION_ID: None → 保存返回的 SESSION_ID
+
+// 第二轮
+SESSION_ID: "上一轮返回的 uuid"
+PROMPT: "Now refine the diff based on the feedback: [反馈内容]"
+```
+
+---
+
+## 协作分工原则
+
+| 角色 | Claude Code 负责 | Codex 负责 |
+|------|-----------------|-----------|
+| **架构** | 设计决策、规范审校 | 分析现有代码结构 |
+| **开发** | 规范重写、最终代码实施 | 输出原型 diff（只读参考） |
+| **审查** | 规范检查、最终判定 | 逐文件逻辑审查 |
+| **调试** | 日志分析、问题定位 | 深度代码分析、补丁建议 |
+
+### 重要约束
+
+1. **只读优先**：始终使用 `sandbox="read-only"`
+2. **英语 Prompt**：与 codex 交互用英语，代码注释要求中文
+3. **脏原型思维**：codex 输出视为草稿，Claude 按项目规范重构
+4. **保存 SESSION_ID**：每次调用后记录，多轮对话时传入
+5. **质疑 codex**：codex 仅供参考，必须有独立判断
+
+---
+
+## 故障排除
+
+| 问题 | 解决方案 |
+|------|---------|
+| 工具未出现 | 重启 Claude Code，检查 `~/.claude.json` 中 codex 配置 |
+| `cd` 参数报错 | 确认目录存在，使用绝对路径 |
+| 连接超时 | 检查网络，`uvx --from git+https://github.com/GuDaStudio/codexmcp.git codexmcp` 手动测试 |
+| SESSION_ID 失效 | 重新开启新会话（不传 SESSION_ID） |
+| codex 修改了文件 | 确认 `sandbox="read-only"` 已设置 |
+
+## 安装验证
+
+```bash
+# 查看 MCP 配置
+cat ~/.claude.json | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('mcpServers', {}).get('codex', 'not found'))"
+
+# 重启后运行
+claude mcp list
+# 期望看到: codex: uvx ... - ✓ Connected
+```