ai-engineering-init 1.16.2 → 1.16.4

package/.codex/skills/leniu-report-scenario/references/total-line.md

@@ -0,0 +1,179 @@
+
+# leniu-tengyun-core 合计行(Total Line)规范
+
+## 项目特征
+
+| 特征 | 说明 |
+|------|------|
+| **包名前缀** | `net.xnzn.core.*` |
+| **JDK 版本** | 21 |
+| **双库切换** | 默认商户库，`Executors.doInSystem()` 切换系统库 |
+| **分页工具** | `PageMethod.startPage()` |
+| **结果封装** | `ReportBaseTotalVO<T>` |
+| **分页封装** | `PageVO.of()` |
+
+## 核心原则
+
+**合计行SQL只返回需要合计的数值字段**，不返回非数值字段（如日期、名称、ID等）。
+
+## Service层实现
+
+### 带合计行的分页查询
+
+```java
+import net.xnzn.core.common.page.PageMethod;
+import net.xnzn.core.common.page.PageVO;
+import net.xnzn.core.common.vo.ReportBaseTotalVO;
+import cn.hutool.core.collection.CollUtil;
+
+// ⚠️ 系统默认在商户库执行，业务查询无需 Executors.readInSystem()
+// Executors.readInSystem() 仅用于需要访问系统库的场景（如全局配置、商户管理）
+
+public ReportBaseTotalVO<XxxVO> pageWithTotal(XxxPageParam param) {
+    ReportBaseTotalVO<XxxVO> result = new ReportBaseTotalVO<>();
+
+    // 1. 导出时不查询合计行(避免不必要的性能开销)
+    if (CollUtil.isEmpty(param.getExportCols())) {
+        XxxVO totalLine = mapper.getSummaryTotal(param);
+        result.setTotalLine(totalLine);
+    }
+
+    // 2. 开启分页
+    PageMethod.startPage(param.getPage());
+
+    // 3. 查询数据
+    List<XxxVO> list = mapper.getSummaryList(param);
+
+    // 4. 封装分页结果
+    result.setResultPage(PageVO.of(list));
+    return result;
+}
+```
+
+### 单独的合计行查询方法
+
+```java
+public XxxVO getSummaryTotal(XxxPageParam param) {
+    // 默认在商户库执行，无需 Executors 包装
+    return mapper.getSummaryTotal(param);
+}
+```
+
+## Mapper XML规范
+
+### 错误示例：返回非数值字段
+
+```xml
+<!-- ❌ 不要这样做 -->
+<select id="getSummaryTotal" resultType="XxxVO">
+    SELECT
+        '合计' AS dateMonth,        <!-- ❌ 不要返回字符串 -->
+        NULL AS schoolId,            <!-- ❌ 不要返回ID -->
+        NULL AS schoolName,          <!-- ❌ 不要返回名称 -->
+        SUM(staffCount) AS staffCount,
+        SUM(amount) AS amount
+    FROM xxx_table
+</select>
+```
+
+### 正确示例：只返回数值字段
+
+```xml
+<!-- ✅ 正确做法 -->
+<select id="getSummaryTotal" resultType="XxxVO">
+    SELECT
+        SUM(staff_count) AS staffCount,
+        SUM(basic_salary) AS basicSalary,
+        SUM(overtime_salary) AS overtimeSalary,
+        SUM(personal_actual_amount) AS personalActualAmount,
+        CASE
+            WHEN SUM(staff_count) = 0 THEN 0
+            ELSE SUM(avg_salary) / COUNT(DISTINCT tenant_id)
+        END AS avgSalary
+    FROM xxx_table
+    <where>
+        del_flag = 2
+        <if test="startDate != null">
+            AND crtime >= #{startDate}
+        </if>
+        <if test="endDate != null">
+            AND crtime &lt;= #{endDate}
+        </if>
+    </where>
+</select>
+```
+
+## 常见合计字段类型
+
+| 字段类型 | 示例 | 合计方式 |
+|---------|------|---------|
+| 数量 | `staff_count`, `order_count` | `SUM()` |
+| 金额 | `amount`, `salary` | `SUM()` |
+| 百分比 | `discount_rate` | `AVG()` 或 `SUM() / COUNT()` |
+| 计数 | `COUNT(DISTINCT id)` | 直接使用 |
+
+## 特殊处理：平均值
+
+```xml
+<!-- 简单平均值 -->
+SELECT AVG(amount) AS avgAmount
+
+<!-- 加权平均值 -->
+SELECT
+    CASE
+        WHEN SUM(count) = 0 THEN 0
+        ELSE SUM(amount * count) / SUM(count)
+    END AS weightedAvgAmount
+
+<!-- 按维度平均 -->
+SELECT
+    CASE
+        WHEN COUNT(DISTINCT tenant_id) = 0 THEN 0
+        ELSE SUM(total_amount) / COUNT(DISTINCT tenant_id)
+    END AS avgByTenant
+```
+
+## Controller层实现
+
+```java
+@PostMapping("/page")
+@ApiOperation("分页查询（带合计）")
+@RequiresAuthentication
+public ReportBaseTotalVO<XxxVO> page(@RequestBody LeRequest<XxxParam> request) {
+    XxxParam param = request.getContent();
+    return xxxService.pageWithTotal(param);
+}
+
+@GetMapping("/total")
+@ApiOperation("单独查询合计行")
+@RequiresAuthentication
+public XxxVO getTotal(XxxParam param) {
+    return xxxService.getSummaryTotal(param);
+}
+```
+
+## 导出时合计行处理
+
+```java
+public void exportExcel(XxxParam param, HttpServletResponse response) {
+    // 导出时需要查询合计行
+    XxxVO totalLine = mapper.getSummaryTotal(param);
+
+    // 分页查询所有数据（不分页）
+    param.getPage().setSize(Integer.MAX_VALUE);
+    List<XxxVO> list = mapper.getSummaryList(param);
+
+    // 将合计行添加到列表末尾
+    list.add(totalLine);
+
+    // 导出
+    exportService.export(list, response);
+}
+```
+
+## 注意事项
+
+- 合计SQL只返回数值字段，不返回字符串、ID、名称等
+- 业务查询默认在商户库执行，无需 `Executors` 包装；仅访问系统库数据时才使用 `Executors.doInSystem()`
+- 导出时通过 `exportCols` 判断是否需要合计行
+- 金额字段类型与 Entity 保持一致：订单模块用 `BigDecimal`，钱包模块用 `Long`（详见 leniu-java-amount-handling）

package/.codex/skills/loki-log-query/SKILL.md

@@ -25,9 +25,35 @@ description: |
 
 ## 多环境配置
 
-配置文件：`.claude/skills/loki-log-query/environments.json`
+### 配置文件查找顺序
 
-### 环境列表
+```
+1. 本地项目：.claude/loki-config.json（新格式）
+2. 本地项目：.claude/skills/loki-log-query/environments.json（旧格式，兼容）
+3. 全局配置：~/.claude/loki-config.json（或 ~/.cursor/loki-config.json）
+```
+
+本地优先。全局配置用 `npx ai-engineering-init config --type loki --scope global` 创建。
+
+### 配置结构（支持 range 范围匹配）
+
+```json
+{
+  "active": "monitor-dev",
+  "environments": {
+    "monitor-dev": {
+      "name": "Monitor 开发环境",
+      "url": "https://monitor-dev.xnzn.net/grafana",
+      "token": "glsa_xxx",
+      "aliases": ["mdev", "dev"],
+      "range": "dev1~15",
+      "projects": ["dev01","dev02","...","dev15"]
+    }
+  }
+}
+```
+
+### 环境列表（默认）
 
 | 环境别名 | 名称 | URL | 快捷词 |
 |----------|------|-----|--------|
@@ -37,31 +63,34 @@ description: |
 | `monitor02-dev` | Monitor02 开发环境 | `https://monitor02-dev.xnzn.net/grafana` | m02, monitor02 |
 | `monitor-tyy-dev` | Monitor 体验园开发环境 | `https://monitor-tyy-dev.xnzn.net/grafana` | tyy, 体验园 |
 
-### 环境匹配规则
+### 环境匹配规则（含 range）
 
-用户说的话 → 匹配环境：
-- "查 test13 的日志" → `test13`
-- "去 monitor-dev 查" → `monitor-dev`
-- "切到体验园" → `monitor-tyy-dev`
-- "去 m02 查一下" → `monitor02-dev`
-- 未指定环境 → 使用 `active` 字段指定的默认环境
+| 用户说法 | 匹配方式 | 结果 |
+|---------|---------|------|
+| "查 test13 的日志" | 精确匹配 key/aliases | `test13` 环境 |
+| "去 dev10 查" | **range 匹配**：dev10 在 monitor-dev 的 projects 中 | `monitor-dev`，`project="dev10"` |
+| "去 monitor-dev 查" | 精确匹配 key | `monitor-dev` 环境 |
+| "切到体验园" | aliases 匹配 | `monitor-tyy-dev` 环境 |
+| 未指定环境 | 使用 `active` 字段 | 默认活跃环境 |
 
-### 读取配置
+### 读取配置（含全局降级 + range 匹配）
 
 ```bash
-SKILL_DIR="$CLAUDE_PROJECT_DIR/.claude/skills/loki-log-query"
-ENV_FILE="${SKILL_DIR}/environments.json"
-
-# 读取指定环境（参数: 环境别名）
-read_env() {
-  local ENV_KEY="${1:-$(python3 -c "import json; print(json.load(open('${ENV_FILE}'))['active'])")}"
-  GRAFANA_URL=$(python3 -c "import json; print(json.load(open('${ENV_FILE}'))['environments']['${ENV_KEY}']['url'])")
-  TOKEN=$(python3 -c "import json; print(json.load(open('${ENV_FILE}'))['environments']['${ENV_KEY}']['token'])")
-  API="${GRAFANA_URL}/api/datasources/proxy/uid/loki/loki/api/v1"
-  echo "Environment: ${ENV_KEY} → ${GRAFANA_URL}"
+# 按优先级查找配置文件
+find_config() {
+  local PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+  for f in \
+    "${PROJECT_DIR}/.claude/loki-config.json" \
+    "${PROJECT_DIR}/.claude/skills/loki-log-query/environments.json" \
+    "${HOME}/.claude/loki-config.json" \
+    "${HOME}/.cursor/loki-config.json"; do
+    [ -f "$f" ] && echo "$f" && return
+  done
 }
 
-# 通过别名查找环境 key
+ENV_FILE=$(find_config)
+
+# 通过别名或 range 查找环境 key + project
 find_env() {
   python3 -c "
 import json
@@ -69,10 +98,11 @@ data = json.load(open('${ENV_FILE}'))
 alias = '${1}'.lower()
 for key, env in data['environments'].items():
     if alias == key or alias in env.get('aliases', []):
-        print(key)
-        break
-else:
-    print(data['active'])
+        print(f'{key}|'); exit()
+for key, env in data['environments'].items():
+    if alias in env.get('projects', []):
+        print(f'{key}|{alias}'); exit()
+print(f'{data[\"active\"]}|')
 "
 }
 ```

package/.codex/skills/mysql-debug/SKILL.md

@@ -27,22 +27,28 @@ description: |
 
 ---
 
-## 连接信息获取（三级降级，自动查找）
+## 连接信息获取（四级降级，自动查找）
 
 当本技能被激活时，**按以下优先级获取数据库连接信息**：
 
 ### 优先级 1：用户对话中指定（最高优先级）
 
 用户直接给出连接信息，或指定环境名：
-- "连 dev 环境查一下" → 使用 `.claude/mysql-config.json` 中 dev 环境的配置
+- "连 dev 环境查一下" → 使用配置中 dev 环境
+- "去 dev10 查" → **范围匹配** dev 环境（range: "1~15"）
 - 直接给出 host/port/user/password → 直接使用
 
-### 优先级 2：`.claude/mysql-config.json`（显式配置，可选）
+### 优先级 2：本地项目 `.claude/mysql-config.json`
 
-如果文件存在且当前环境的 password 不是占位符 `YOUR_PASSWORD`，使用该配置。
-**此文件为可选**，主要用于连接非本地环境（dev/prod 远程数据库）。
+项目目录下的配置文件，优先于全局配置。
 
-### 优先级 3：工程配置文件（零配置，本地开发默认）
+### 优先级 3：全局配置（所有项目共享）
+
+全局配置文件（通过 `npx ai-engineering-init config --scope global` 创建）。
+查找路径：`~/.claude/mysql-config.json` 或 `~/.cursor/mysql-config.json`（取决于使用的工具）。
+**推荐**：公司统一的数据库连接信息放全局，项目特定的覆盖放本地。
+
+### 优先级 4：工程配置文件（零配置，本地开发默认）
 
 从项目的 `bootstrap-dev.yml` 中自动提取连接信息：
 

package/.cursor/skills/code-patterns/SKILL.md

@@ -101,120 +101,6 @@ feat(order): 新增订单导出功能
 Closes #123
 ```
 
-## 数据类型规范
-
-### 布尔语义字段必须使用 Boolean
-
-```java
-// ❌ 错误
-private Integer ifNarrow;
-private Integer isEnabled;
-
-// ✅ 正确
-private Boolean narrow;     // getter 自动生成 isNarrow()
-private Boolean enabled;    // getter 自动生成 isEnabled()
-```
-
-**规则**：
-- 语义为"是/否"的字段，类型必须为 `Boolean`
-- 字段名不加 `if`/`is`/`has` 前缀（JavaBean 规范中 `Boolean` 的 getter 自动生成 `isXxx()`）
-- 数据库字段使用 `TINYINT(1)` 或 `BIT(1)`
-
-### 枚举字段必须提供明确约束
-
-```java
-// ❌ 错误：调用方无法知道合法值
-@ApiModelProperty(value = "操作类型")
-private Integer tradeType;
-
-// ✅ 方案一：VO/DTO 层直接用枚举（推荐）
-@ApiModelProperty(value = "操作类型")
-private AccTradeTypeEnum tradeType;
-
-// ✅ 方案二：保留 Integer 但标注合法值
-@ApiModelProperty(value = "操作类型：1-充值 2-消费 3-退款", allowableValues = "1,2,3")
-private Integer tradeType;
-```
-
-### 金额字段禁止使用浮点类型
-
-```java
-// ❌ 错误
-private Double amount;
-private Float price;
-
-// ✅ 正确：Entity/Service 层用 Long（分），VO 层展示用 BigDecimal（元）
-private Long amountFen;
-private BigDecimal amountYuan;
-```
-
-### 原始类型 vs 包装类型
-
-| 场景 | 用原始类型 | 用包装类型 |
-|------|----------|----------|
-| Entity / VO / DTO 字段 | — | ✅ 统一用包装类型 |
-| 方法参数（不允许 null） | ✅ `int count` | — |
-| 方法参数（允许 null） | — | ✅ `Integer count` |
-| 局部变量 | ✅ `int i = 0` | — |
-
-## Optional 使用规范
-
-```java
-// ❌ 错误：of() 不接受 null，value 为 null 直接 NPE
-Optional.of(value).orElse(defaultValue);
-
-// ✅ 正确：ofNullable() 安全处理 null
-Optional.ofNullable(value).orElse(defaultValue);
-
-// ❌ 禁止：Optional 作为方法参数或类字段
-public void process(Optional<String> name) { ... }
-private Optional<String> name;
-
-// ✅ 允许：Optional 作为方法返回值、链式处理
-public Optional<Entity> findById(Long id) { ... }
-Optional.ofNullable(entity).map(Entity::getConfig).orElse(DEFAULT_VALUE);
-```
-
-## @Transactional 规范
-
-```java
-// ❌ 错误：默认只回滚 RuntimeException
-@Transactional
-public void createOrder() { ... }
-
-// ✅ 正确：显式指定回滚异常
-@Transactional(rollbackFor = Exception.class)
-public void createOrder() { ... }
-```
-
-- 所有 `@Transactional` 必须显式写 `rollbackFor = Exception.class`
-- 只读查询不加 `@Transactional`（或用 `readOnly = true`）
-- 事务方法不要 try-catch 吞掉异常，否则事务不回滚
-
-## TODO 管理规范
-
-```java
-// ❌ 错误：无负责人、无日期、无跟踪
-// TODO 修改一下
-
-// ✅ 正确：完整 TODO 格式
-// TODO(@陈沈杰, 2026-03-20, #TASK-1234): 移动端 AppId 赋值逻辑待产品确认
-```
-
-- 每个 TODO 必须有对应的任务号
-- 超过 2 个迭代未处理的 TODO 必须清理
-- 不用的代码直接删除，不要注释保留
-
-## 代码格式化规范
-
-| 项目 | 规范 |
-|------|------|
-| 缩进 | 4 个空格（不用 Tab） |
-| 行宽 | 120 字符 |
-| 大括号 | K&R 风格（同行开始） |
-| 空行 | 方法间 1 个空行，逻辑块间 1 个空行 |
-| import | 分组排序：java → jakarta → org → net → com，组间空行 |
-
 ## 代码示例
 
 ### 统一响应格式
@@ -275,8 +161,3 @@ public enum OrderStatusEnum {
 | Git 提交信息写"fix bug" | 写清楚修了什么：`fix(order): 修复金额计算精度丢失` |
 | Boolean 变量名：`flag` | 有意义的名字：`isActive`, `hasPermission` |
 | 缩写命名：`usr`, `mgr` | 完整命名：`user`, `manager` |
-| `Optional.of(可能null值)` | `Optional.ofNullable(value)` |
-| `@Transactional` 无 rollbackFor | `@Transactional(rollbackFor = Exception.class)` |
-| TODO 无负责人和日期 | `// TODO(@负责人, 日期, #任务号): 描述` |
-| 布尔字段用 `Integer` | 用 `Boolean` 类型 |
-| 枚举字段无合法值说明 | `@ApiModelProperty` 标注合法值或直接用枚举类型 |

package/.cursor/skills/fix-bug/SKILL.md

@@ -197,6 +197,62 @@ Agent(mysql-runner, "根据日志发现涉及 order_info 表，查询 id=xxx 的
 | Bug 描述 + DB 信息 | bug-analyzer + mysql-runner | — |
 | Bug 描述 + traceId + DB 信息 | 全部 | 日志中有新表/ID → mysql-runner 追加查询 |
 
+## SQL 报表 Bug 专项流程
+
+当 Bug 涉及 **SQL 查询逻辑错误**（SUM/GROUP BY/CASE WHEN/金额计算等），启用以下验证流程：
+
+### 修复前：建立基线
+
+```
+1. 读取当前 Mapper XML，理解现有 SQL 逻辑
+2. 如果有已修复的参考查询（如同模块的明细查询），先读取其 SQL 逻辑作为正确参考
+3. 查库获取当前错误结果作为"修复前基线"（可选，用户提供 DB 时执行）
+```
+
+### 修复后：交叉验证（必须执行）
+
+**两步验证法**（以本项目销售汇总修复为典型案例）：
+
+```
+步骤 1：直接执行修改后的 SQL，验证基本逻辑
+  - 检查各记录类型是否正确处理（称重/按份、正向/逆向、入库/出库）
+  - 检查特殊值：NULL 处理、除零保护、边界条件
+
+步骤 2：交叉对比验证
+  - 方法 A：用已修复的明细查询做 SUM 汇总
+  - 方法 B：执行修改后的汇总查询
+  - 对比 A vs B：总计必须完全一致
+  - 按维度对比（按商品/按门店等）：逐行 MATCH/DIFF
+```
+
+### 验证 SQL 模板
+
+```sql
+-- 交叉验证：明细汇总 vs 汇总查询
+SELECT '明细汇总' as source, SUM(saleNum), SUM(cost), ...
+FROM (/* 明细查询逐行 */) detail
+UNION ALL
+SELECT '汇总查询' as source, ...
+FROM /* 汇总查询 */;
+
+-- 按维度逐行对比
+SELECT COALESCE(d.name, s.name) as name,
+       d.detail_value, s.summary_value,
+       CASE WHEN d.detail_value = s.summary_value THEN 'MATCH' ELSE 'DIFF' END as result
+FROM (/* 明细按维度 GROUP BY */) d
+LEFT JOIN (/* 汇总按维度 GROUP BY */) s ON d.id = s.id;
+```
+
+### SQL 修改注意事项
+
+| 规则 | 说明 |
+|------|------|
+| **保留 WHERE 条件** | 新增/修改查询必须包含与现有查询相同的过滤条件 |
+| **GROUP BY 优先** | 优先添加字段到 GROUP BY，不用 ANY_VALUE() |
+| **JOIN 一致性** | 主查询和合计查询的 JOIN 必须一致（如 drp_unit） |
+| **IFNULL 保护** | 除法运算中的分母必须用 IFNULL 防止除零 |
+| **业务类型分支** | CASE WHEN 必须覆盖所有业务类型（称重/按份、入库/出库等） |
+
 ## 提交规则
 
 修复完成后，**必须调用 `Skill(git-workflow)` 再执行 git 操作**。
@@ -210,3 +266,4 @@ Agent(mysql-runner, "根据日志发现涉及 order_info 表，查询 id=xxx 的
 - 简单 Bug 不要过度编排，直接修就行（但仍需先报告再修复）
 - 如果用户没提供 DB/Loki 信息但 Bug 涉及数据问题，主动询问
 - 与 `bug-detective` 技能的区别：`bug-detective` 是排查指南，`fix-bug` 是全流程编排（包含排查+修复+提交）
+- SQL 报表 Bug 修复后**必须执行交叉验证**，不能只看"能跑"就提交