sync from WSL host: latest openclaw config update
This commit is contained in:
@@ -0,0 +1,188 @@
|
||||
# G5 库存管理优化 — 需求确认与代码审视清单
|
||||
|
||||
> 用途：拿这份清单去代码里翻答案，翻完了回来交底，我再出正式技术规格。
|
||||
|
||||
---
|
||||
|
||||
## 目录
|
||||
1. [威玛斯 · 物料转换 — 单价·金额·默认工厂仓库](#1-威玛斯--物料转换)
|
||||
2. [切纳 · 库存预警 — 采购申请/采购订单模式参数](#2-切纳--库存预警)
|
||||
3. [凯熙 · 库存调整 — APP/PC 跨仓库物料移动](#3-凯熙--库存调整)
|
||||
4. [骏全塑胶 · 委外红冲 — 退料失败不回滚](#4-骏全塑胶--委外入库红冲退料不回滚)
|
||||
|
||||
---
|
||||
|
||||
## 1. 威玛斯 · 物料转换
|
||||
|
||||
### 需求摘要
|
||||
- 转换前物料：增加「无税单价」「无税金额」字段，取采购时的值
|
||||
- 转换前：合计金额取各行金额合计
|
||||
- 转换后物料：自动带出默认工厂和仓库，取自主数据-物料信息
|
||||
|
||||
### 🔍 需要去看代码回答的问题
|
||||
|
||||
#### 1.1 物料转换的数据模型
|
||||
| # | 去代码里找什么 | 为什么问 |
|
||||
|---|---------------|----------|
|
||||
| 1.1.1 | 物料转换的**数据库表名**是什么？（找 `mapper.xml` 或 `@TableName` 注解） | 确定在哪个表加字段 |
|
||||
| 1.1.2 | 转换**明细表**有哪些字段？有无 `batch_no`（批次号）、`warehouse_id`、`purchase_order_id` 等关联字段？ | 关联采购单时靠什么字段 join |
|
||||
| 1.1.3 | 转换单**主表**有哪些字段？有无 `total_amount` 合计字段？ | 合计是存库还是前端算 |
|
||||
| 1.1.4 | 现有的**物料主数据表**（`material` 或 `item`）是否有 `default_warehouse_id`、`default_factory_id` 字段？ | 确认数据源头是否存在 |
|
||||
|
||||
#### 1.2 采购单价取数逻辑
|
||||
| # | 去代码里找什么 | 为什么问 |
|
||||
|---|---------------|----------|
|
||||
| 1.2.1 | 现有代码中**采购入库单明细表**（`purchase_inbound_detail` 或类似）有哪些字段？是否有 `unit_price_no_tax`、`amount_no_tax`？ | 找到单价的数据来源表 |
|
||||
| 1.2.2 | 采购入库明细和物料**通过什么字段关联**？`material_id`？`batch_no`？`inbound_order_no`？ | 取数时的 join 键 |
|
||||
| 1.2.3 | 如果物料有**批次管理**，同一个物料不同批次的单价不同，现有逻辑怎么取的？ | 多批次时必须确认取数规则 |
|
||||
| 1.2.4 | 有没有**加权平均**或者**移动平均**的成本计算逻辑？代码的 `service` 或 `util` 层有没有相关工具方法？ | 如果有现成的成本计算工具，可以直接复用 |
|
||||
| 1.2.5 | **非采购入库场景**的物料（盘盈、产成品入库、期初）怎么处理单价？已有代码有没有类似场景的处理？ | 处理边界情况 |
|
||||
|
||||
#### 1.3 转换后默认工厂/仓库
|
||||
| # | 去代码里找什么 | 为什么问 |
|
||||
|---|---------------|----------|
|
||||
| 1.3.1 | 物料主数据加载时，代码中**如何取默认仓库**的？搜 `getDefaultWarehouse` / `defaultWarehouseId` 等 | 复用已有逻辑还是新建 |
|
||||
| 1.3.2 | 转换后物料的工厂/仓库字段，在前端表单中**当前是怎么赋值的**？有没有自动填充机制？ | 确定改哪里 |
|
||||
| 1.3.3 | 跨工厂的场景：物料主数据的默认仓库属于A工厂，但登录用户属于B工厂，**代码有没有做组织校验**？ | 判断是否需要增加校验 |
|
||||
|
||||
#### 1.4 前端部分
|
||||
| # | 去代码里找什么 | 为什么问 |
|
||||
|---|---------------|----------|
|
||||
| 1.4.1 | 转换前物料表格的 **JSON schema 或 columns 配置**在哪里？ | 确定表格列配置的代码位置 |
|
||||
| 1.4.2 | 当前表单**提交时物料数据的组装逻辑**（`handleSubmit` 或 `transformPayload`） | 决定新增字段如何提交 |
|
||||
| 1.4.3 | 详情页有没有**只读的渲染组件**？是复用的表单组件还是单独的 Detail 组件？ | 详情页改一处还是两处 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 切纳 · 库存预警
|
||||
|
||||
### 需求摘要
|
||||
- 加一个参数配置：库存预警触发时对接「采购申请」还是「采购订单」
|
||||
- 采购申请：走原有逻辑
|
||||
- 采购订单：直接新增采购订单
|
||||
|
||||
### 🔍 需要去看代码回答的问题
|
||||
|
||||
#### 2.1 现有库存预警流程
|
||||
| # | 去代码里找什么 | 为什么问 |
|
||||
|---|---------------|----------|
|
||||
| 2.1.1 | 现有库存预警触发后，**生成采购申请单的代码入口**在哪里？搜 `warn` / `alert` / `purchaseRequisition` 相关 service | 找到切入点 |
|
||||
| 2.1.2 | 采购申请的**自动生成逻辑**是什么？有哪些字段是系统填充的，哪些字段保留给用户填？ | 理解现有流程完整链路 |
|
||||
| 2.1.3 | 预警是按**物料级别**触发还是按**物料+仓库级别**触发？同一物料多个仓库都缺货时怎么处理？ | 判断参数配置的作用域 |
|
||||
|
||||
#### 2.2 参数配置
|
||||
| # | 去代码里找什么 | 为什么问 |
|
||||
|---|---------------|----------|
|
||||
| 2.2.1 | 系统现有的**参数配置表**或配置中心机制是什么？（`sys_config`？`system_param`？还是枚举 + 常量？） | 参数放哪里 |
|
||||
| 2.2.2 | 现有的**库存预警相关的参数**有哪些？（预警上下限、预警方式等）已经存在哪些配置项？代码如何读取？ | 复用已有的参数框架 |
|
||||
| 2.2.3 | 配置参数是**全局**级别还是**仓库/物料分类**级别？代码里有没有已有按维度区分参数的写法？ | 决定参数的作用域 |
|
||||
|
||||
#### 2.3 直接生成采购订单的链路
|
||||
| # | 去代码里找什么 | 为什么问 |
|
||||
|---|---------------|----------|
|
||||
| 2.3.1 | 新增采购订单（`purchase_order`）的 **Service/Create 方法**在哪里？方法签名是什么？需要哪些必填参数？ | 找到订单创建入口 |
|
||||
| 2.3.2 | 采购订单的**默认供应商**怎么确定？物料主数据有没有 `default_supplier_id` 字段？ | 自动下单必须要填供应商 |
|
||||
| 2.3.3 | 采购订单的**单价**怎么取？（上次采购价？物料价格表？加权均价？）代码里有没有现成的取价工具？ | 自动下单必须有单价 |
|
||||
| 2.3.4 | 新增采购订单**是否需要走审批流**？如需审批，审批流代码入口在哪？能否跳过？ | 决定是否全自动 |
|
||||
| 2.3.5 | 同一个供应商同时多个物料触达预警，现在是**合并生成一张采购申请单**还是分开建？直接生成采购订单时是否也要做合并？ | 确定合并策略 |
|
||||
|
||||
#### 2.4 前端
|
||||
| # | 去代码里找什么 | 为什么问 |
|
||||
|---|---------------|----------|
|
||||
| 2.4.1 | 库存预警的**设置页面**在哪里？参数配置的UI入口是什么？ | 找到新增参数的位置 |
|
||||
| 2.4.2 | 之前的预警**参数是怎么做表单联动的**？（存在级联/显隐逻辑吗） | 参数表单的改法 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 凯熙 · 库存调整
|
||||
|
||||
### 需求摘要
|
||||
- APP 和 PC 的库存调整功能，从"单仓库内调整"扩展为"支持跨仓库间的物料移动"
|
||||
|
||||
### 🔍 需要去看代码回答的问题
|
||||
|
||||
#### 3.1 现有库存调整的逻辑
|
||||
| # | 去代码里找什么 | 为什么问 |
|
||||
|---|---------------|----------|
|
||||
| 3.1.1 | 现有库存调整的**数据库表**是什么？有哪些字段？有无 `target_warehouse_id` / `to_warehouse_id` 字段？ | 要不要加字段 |
|
||||
| 3.1.2 | 现有调整单**Service层**的调整逻辑：减源仓库存 → 加目标仓库存。代码位置在哪里？ | 确定改哪段逻辑 |
|
||||
| 3.1.3 | 调整是否影响**成本**？库存调整时有没有调用成本计算的接口（`costService` / `calculateCost` 等）？ | 跨仓库移动是否需要重新计价 |
|
||||
| 3.1.4 | 现有代码**仓库的库存组织**是怎么处理的？一个仓库属于一个工厂/法人，代码里怎么校验跨仓库操作的合法性？ | 判断是否允许跨组织移动 |
|
||||
|
||||
#### 3.2 同一仓库内 vs 跨仓库的关键差异
|
||||
| # | 去代码里找什么 | 为什么问 |
|
||||
|---|---------------|----------|
|
||||
| 3.2.1 | 前端**库存调整页面**的 `warehouse_id` 是从哪里取的？（URL参数？用户默认仓库？还是页面下拉选择？） | 确定怎么加"目标仓库" |
|
||||
| 3.2.2 | 库存调整的**列表页面**，是否存在按仓库过滤的查询逻辑？ | 跨仓移动是否需要显示一张单跨两仓 |
|
||||
| 3.2.3 | 如果有**批次/序列号**物料，调整时批次号的处理逻辑是什么？ | 跨仓时批次是否拆分 |
|
||||
| 3.2.4 | 现有**审批流**配置中，有没有按"库存调整类型"设置不同审批链的机制？ | 判断跨仓是否需要不同的审批 |
|
||||
|
||||
#### 3.3 APP 端（移动端）
|
||||
| # | 去代码里找什么 | 为什么问 |
|
||||
|---|---------------|----------|
|
||||
| 3.3.1 | APP 库存调整页面是**原生还是 H5/WebView**？代码在哪个目录？ | 确定开发语言和工具链 |
|
||||
| 3.3.2 | APP 是否有**扫码功能**？扫码后的逻辑是直接识别物料+数量，还是需要额外选择操作？ | 跨仓库移动扫码流程设计 |
|
||||
| 3.3.3 | APP 端下拉选择**仓库列表**的数据源是哪个接口？是否有按用户权限过滤？ | 确定目的仓库的数据源 |
|
||||
|
||||
#### 3.4 后端接口
|
||||
| # | 去代码里找什么 | 为什么问 |
|
||||
|---|---------------|----------|
|
||||
| 3.4.1 | 库存调整的 **DTO/VO** 有哪些字段？新增/编辑接口的请求体结构？ | 接口改造范围 |
|
||||
| 3.4.2 | 列表查询接口已经支持按哪些字段**过滤和排序**？ | 判断是否需要扩展查询接口 |
|
||||
| 3.4.3 | 如果是**同价调拨**，库存移动时是否需要生成财务凭证？代码里有没有凭证生成逻辑？ | 评估财务影响范围 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 骏全塑胶 · 委外入库红冲退料不回滚
|
||||
|
||||
### 需求摘要
|
||||
- 红冲委外采购入库单时，自动退料失败了，**红冲入库单不回滚**
|
||||
- 提示用户："入库成功，但自动退料失败，请手工退料"
|
||||
|
||||
### 🔍 需要去看代码回答的问题
|
||||
|
||||
#### 4.1 现有委外红冲+退料流程
|
||||
| # | 去代码里找什么 | 为什么问 |
|
||||
|---|---------------|----------|
|
||||
| 4.1.1 | 委外入库单**红冲的代码入口**在哪里？是 `reverse()` / `redFlush()` / `negativeInbound()` 之类的方法？ | 找到主入口 |
|
||||
| 4.1.2 | 红冲时**自动生成委外退料单**的代码是哪一段？`createReturnMaterial()` / `autoReturn()` 等 | 找到退料触发点 |
|
||||
| 4.1.3 | 红冲和退料在同一个**事务**里吗？`@Transactional` 注解的范围？| 决定事务边界怎么调整 |
|
||||
| 4.1.4 | 当前退料**失败时抛了什么异常**？是 `RuntimeException` + `@Transactional(rollbackFor)` 导致整体回滚的吗？ | 找到回滚的根因 |
|
||||
| 4.1.5 | 退料的**Service方法**抛出的异常类型都有哪些？代码里有没有区分"可重试"和"不可重试"的异常？ | 设计异常处理策略 |
|
||||
|
||||
#### 4.2 退料失败的细分场景
|
||||
| # | 去代码里找什么 | 为什么问 |
|
||||
|---|---------------|----------|
|
||||
| 4.2.1 | 退料数量 > 委外商在库数量时，代码怎么处理的？是否有数量校验逻辑？ | 常见失败场景 |
|
||||
| 4.2.2 | 委外退料如果需要**审批**，审批不通过时返回什么结果？是抛异常还是返回状态码？ | 非抛异常场景的失败判断 |
|
||||
| 4.2.3 | 委外商已经**领用消耗**了该物料（如已经加工消耗），系统怎么处理？是否有校验？ | 物料已被消耗的边界 |
|
||||
| 4.2.4 | 退料接口调用的**网络超时/服务异常**场景，现有代码有没有重试机制（`@Retryable`、MQ、定时任务）？ | 判断临时失败 vs 确定性失败 |
|
||||
|
||||
#### 4.3 改造后的处理逻辑
|
||||
| # | 去代码里找什么 | 为什么问 |
|
||||
|---|---------------|----------|
|
||||
| 4.3.1 | 红冲入库单表是否有**状态字段**（`status` 或 `reverse_status`）？都有哪些枚举值？ | 考虑是否需要加退料状态标记 |
|
||||
| 4.3.2 | 系统中已有的**操作日志/系统日志表**结构和插入逻辑是怎样的？ | 记录失败原因到日志 |
|
||||
| 4.3.3 | 有没有**通知/待办/消息推送**的现成工具类？（`sendNotification()` / `createTask()` 等） | 提示用户手工退料时调用 |
|
||||
| 4.3.4 | 前端**提示弹窗或消息提示**的统一组件/API是什么？（`message.error` / `notification.warning` 等） | 前端提示怎么做 |
|
||||
| 4.3.5 | 现有**委外退料的手工入口**在哪里？（菜单路径 / 页面路由） | 提示"请手工退料"时需要告诉用户去哪里操作 |
|
||||
|
||||
#### 4.4 类似场景排查
|
||||
| # | 去代码里找什么 | 为什么问 |
|
||||
|---|---------------|----------|
|
||||
| 4.4.1 | PC端/APP端有没有**其他"自动流程失败但主流程不回滚"的现有处理模式**可以参照？ | 复用已有模式，保持一致性 |
|
||||
| 4.4.2 | 除了委外红冲，还有哪些业务也自动触发委外退料？（退货出库、委外结算等） | 判断是否需要同步改造 |
|
||||
|
||||
---
|
||||
|
||||
## 使用建议
|
||||
|
||||
1. **按需求逐一查代码**：从 #1.1 开始，逐个问题去看，把答案写在旁边
|
||||
2. **不确定就截代码片段**：拿不准的或者代码看不懂的，把关键代码片段（方法、变量、表结构）直接截下来带回来
|
||||
3. **遇到瓶颈标记下来**：代码里找不到答案的，标记为「待产品确认」，我帮你转化为需求澄清问题
|
||||
|
||||
答完所有问题后，把结果带回来，我出正式的技术规格说明书（含：数据库变更 DDL、接口定义、前端改造点、伪代码逻辑）。
|
||||
|
||||
---
|
||||
|
||||
*版次：v1.0 | 生成日期：2026-06-01 | 适用范围：G5 版本 维云智造 库存管理模块*
|
||||
@@ -0,0 +1,393 @@
|
||||
# DailyHotJob 改造任务清单
|
||||
|
||||
## 改造目标
|
||||
|
||||
修复 DailyHotJob 异常吞没、性能低下、运维盲区等核心缺陷，改造为可观测、可中断、高性能的定时任务。
|
||||
|
||||
## 涉及文件清单
|
||||
|
||||
| 文件 | 路径 | 改动量 |
|
||||
|------|------|--------|
|
||||
| DailyHotJob.java | `yudao-module-wellness/.../wellness/job/jackett/DailyHotJob.java` | 小改 |
|
||||
| JackettServiceImpl.java | `yudao-module-wellness/.../wellness/service/jackett/impl/JackettServiceImpl.java` | 大改 |
|
||||
| ResourcesUtils.java | `yudao-module-wellness/.../wellness/utils/ResourcesUtils.java` | 小改 |
|
||||
| application-{env}.yml | `yudao-module-wellness/.../resources/` | 新增配置项 |
|
||||
|
||||
---
|
||||
|
||||
## 分步任务
|
||||
|
||||
### P0-1：异常不再吞没，让 JobHandlerInvoker 能记录真实状态
|
||||
|
||||
**描述**：当前 `DailyHotJob.execute()` 没有 throws Exception，内部 `dailyHot()` 所有异常都被 try-catch 吞掉。JobHandlerInvoker 永远收不到异常，Job 日志永远显示成功，运维完全盲区。
|
||||
|
||||
**改动点**：
|
||||
|
||||
1. **`DailyHotJob.java`**：`execute()` 方法改为 `throws Exception`，不再包 try-catch
|
||||
```java
|
||||
@Override
|
||||
public String execute(String param) throws Exception {
|
||||
jackettService.dailyHot();
|
||||
return "每日热点";
|
||||
}
|
||||
```
|
||||
注意：如果 `dailyHot()` 声明了 throws Exception，这里会自动向上传播，不需要额外处理。
|
||||
|
||||
2. **`JackettServiceImpl.java` — `dailyHot()` 方法签名**：改为 `throws Exception`
|
||||
```java
|
||||
@Override
|
||||
@TenantIgnore
|
||||
public void dailyHot() throws Exception { ... }
|
||||
```
|
||||
|
||||
3. **`dailyHot()` 内部循环**：**保留**单个关键词搜索失败的捕获（因为一个搜失败不应该影响其他关键词），但去掉最外层那层兜底 try-catch，或者让最外层 catch 后重新 throw：
|
||||
```java
|
||||
// ❌ 错误做法：catch 后只打日志
|
||||
// ✅ 正确做法：catch 可恢复异常后继续循环，不可恢复异常向上抛
|
||||
for (String javId : newIds) {
|
||||
try {
|
||||
...
|
||||
} catch (Exception e) {
|
||||
log.error("搜索 '{}' 时出错", javId, e.getMessage(), e);
|
||||
// 单个失败不中断整体任务，continue 继续下一个
|
||||
}
|
||||
}
|
||||
```
|
||||
这样单个关键词搜索失败不会影响整体，但 `dailyHot()` 本身如果出现致命错误（如 FlareSolverr 不可用），会在 `getPageContent()` 抛出异常并向上传播。
|
||||
|
||||
**注意事项**：
|
||||
- `dailyHot()` 的循环内 `catch` 后应该 `continue`，而不是 `break` 或 `throw`
|
||||
- 如果 `ResourcesUtils.saveFile()` 抛出 `RuntimeException`，它也会向上传播——需要考虑这个是否属于「可恢复」异常
|
||||
|
||||
---
|
||||
|
||||
### P0-2：租户注解问题修正
|
||||
|
||||
**描述**：`@TenantIgnore` 只在 `dailyHot()` 上，但内部调用的 `getDailyHotIds()`、`getPageContent()`、`searchSingleKeyword()`、`searchRecent()` 都是通过 `this.` 内部调用，Spring AOP 切面不会触发，租户 SQL 拦截器可能拼入错误的 `WHERE tenant_id = ?`。
|
||||
|
||||
**改动点**：
|
||||
|
||||
1. 在这些方法上补 `@TenantIgnore`：
|
||||
- `getDailyHotIds()`
|
||||
- `getPageContent(String targetUrl)`
|
||||
- `searchSingleKeyword(String query, Integer limit)`
|
||||
- `searchRecent(List<String> keywords, Integer hours, Integer limit)`
|
||||
|
||||
```java
|
||||
@Override
|
||||
@TenantIgnore
|
||||
public Set<String> getDailyHotIds() { ... }
|
||||
|
||||
@Override
|
||||
@TenantIgnore
|
||||
public String getPageContent(String targetUrl) { ... }
|
||||
|
||||
@Override
|
||||
@TenantIgnore
|
||||
public List<JackettSearchResultVO> searchSingleKeyword(String query, Integer limit) { ... }
|
||||
|
||||
@Override
|
||||
@TenantIgnore
|
||||
public List<JackettSearchResultVO> searchRecent(List<String> keywords, Integer hours, Integer limit) { ... }
|
||||
```
|
||||
|
||||
**注意事项**：
|
||||
- `saveRedisIds()` 也加了 `@TenantIgnore` 了吗？检查一下，如果没有也要加上
|
||||
- 如果 ruoyi 框架的租户拦截是通过 `@TenantIgnore` 在 Service 方法上加注解来跳过，这些方法都需要加
|
||||
|
||||
---
|
||||
|
||||
### P1-1：批量查重 + 批量插入替代 N+1
|
||||
|
||||
**描述**：当前对每个 hotId 执行一次 `selectOne`（N 次查询）+ 循环内逐条 `insert`，严重低效。
|
||||
|
||||
**改动点**：
|
||||
|
||||
1. **`JavInfoMapper.java`**：新增批量查询方法
|
||||
```java
|
||||
// 根据 javId 列表批量查询已存在的记录
|
||||
List<JavInfoDO> selectByJavIds(@Param("javIds") Collection<String> javIds);
|
||||
```
|
||||
|
||||
对应的 XML：
|
||||
```xml
|
||||
<select id="selectByJavIds" resultMap="JavInfoResultMap">
|
||||
SELECT * FROM wellness_jav_info WHERE jav_id IN
|
||||
<foreach collection="javIds" item="javId" open="(" separator="," close=")">
|
||||
#{javId}
|
||||
</foreach>
|
||||
</select>
|
||||
```
|
||||
|
||||
2. **`JavInfoMapper.java`**：新增批量插入方法
|
||||
```java
|
||||
// 批量插入（忽略重复键）
|
||||
int insertBatch(@Param("list") Collection<JavInfoDO> list);
|
||||
```
|
||||
|
||||
对应的 XML（使用 MySQL `INSERT IGNORE` 或 `ON DUPLICATE KEY UPDATE`）：
|
||||
```xml
|
||||
<insert id="insertBatch">
|
||||
INSERT IGNORE INTO wellness_jav_info(jav_id, create_time, update_time) VALUES
|
||||
<foreach collection="list" item="item" separator=",">
|
||||
(#{item.javId}, #{item.createTime}, #{item.updateTime})
|
||||
</foreach>
|
||||
</insert>
|
||||
```
|
||||
|
||||
3. **`JackettServiceImpl.dailyHot()`**：改造查重逻辑
|
||||
```java
|
||||
// ❌ 旧：逐条 selectOne
|
||||
Set<String> newIds = hotIds.stream()
|
||||
.filter(javId -> javInfoMapper.selectOne(JavInfoDO::getJavId, javId) == null)
|
||||
.collect(Collectors.toSet());
|
||||
|
||||
// ✅ 新：批量查重
|
||||
Set<String> existingIds = javInfoMapper.selectByJavIds(hotIds)
|
||||
.stream().map(JavInfoDO::getJavId).collect(Collectors.toSet());
|
||||
Set<String> newIds = hotIds.stream()
|
||||
.filter(id -> !existingIds.contains(id))
|
||||
.collect(Collectors.toSet());
|
||||
```
|
||||
|
||||
4. **`JackettServiceImpl.dailyHot()`**：改造插入逻辑，循环结束后统一批量插入
|
||||
```java
|
||||
// 循环内不再逐条 insert，改为收集待插入
|
||||
List<JavInfoDO> toInsert = new ArrayList<>();
|
||||
|
||||
for (String javId : newIds) {
|
||||
// ...搜索+过滤+保存文件...
|
||||
toInsert.add(new JavInfoDO().setJavId(javId));
|
||||
}
|
||||
|
||||
// 循环结束后批量插入
|
||||
if (!toInsert.isEmpty()) {
|
||||
javInfoMapper.insertBatch(toInsert);
|
||||
}
|
||||
```
|
||||
|
||||
**注意事项**：
|
||||
- `insertBatch` 需要 MySQL 支持，如果是 PostgreSQL 或 Oracle 需要对应适配
|
||||
- 使用 `INSERT IGNORE` 可以避免重复键冲突；如果不需要 `ignore` 行为，可以用 `ON DUPLICATE KEY UPDATE` 更新 update_time
|
||||
|
||||
---
|
||||
|
||||
### P1-2：并发搜索 + 超时控制
|
||||
|
||||
**描述**：逐条串行搜索 + `Thread.sleep`，如果 50 个新 ID，仅 sleep 就 100s，加上 HTTP 耗时 2-5s/次，整个 Job 跑几分钟。
|
||||
|
||||
**改动点**：
|
||||
|
||||
1. **`JackettServiceImpl.java`**：引入并发控制
|
||||
```java
|
||||
import java.util.concurrent.CompletableFuture;
|
||||
import java.util.concurrent.ExecutorService;
|
||||
import java.util.concurrent.Executors;
|
||||
import java.util.concurrent.TimeUnit;
|
||||
```
|
||||
|
||||
在类中声明线程池（或者使用 Spring 的 `TaskExecutor`）：
|
||||
```java
|
||||
private static final ExecutorService SEARCH_EXECUTOR = Executors.newFixedThreadPool(5);
|
||||
```
|
||||
|
||||
改造 `dailyHot()` 中的循环：
|
||||
```java
|
||||
// ❌ 旧：串行 for 循环 + sleep
|
||||
for (String javId : newIds) {
|
||||
List<JackettSearchResultVO> results = searchSingleKeyword(javId, 30);
|
||||
// ...过滤+保存...
|
||||
Thread.sleep(jackettProperties.getSearchDelay());
|
||||
}
|
||||
|
||||
// ✅ 新：CompletableFuture 并发
|
||||
List<CompletableFuture<Void>> futures = new ArrayList<>();
|
||||
for (String javId : newIds) {
|
||||
CompletableFuture<Void> future = CompletableFuture.runAsync(() -> {
|
||||
try {
|
||||
List<JackettSearchResultVO> results = searchSingleKeyword(javId, 30);
|
||||
// ...过滤+保存...
|
||||
} catch (Exception e) {
|
||||
log.error("搜索 '{}' 时出错", javId, e.getMessage(), e);
|
||||
}
|
||||
}, SEARCH_EXECUTOR);
|
||||
futures.add(future);
|
||||
}
|
||||
|
||||
// 等待所有搜索完成（带超时）
|
||||
CompletableFuture.allOf(futures.toArray(new CompletableFuture[0]))
|
||||
.get(jackettProperties.getSearchTimeoutMinutes(), TimeUnit.MINUTES);
|
||||
```
|
||||
|
||||
`searchRecent()` 同理也要改造。
|
||||
|
||||
2. **`JackettProperties.java`**：新增配置项
|
||||
```java
|
||||
/** 搜索超时时间（分钟） */
|
||||
private Integer searchTimeoutMinutes = 30;
|
||||
```
|
||||
|
||||
3. **`application.yml`**：验证或添加配置
|
||||
```yaml
|
||||
jackett:
|
||||
search-timeout-minutes: 30
|
||||
```
|
||||
|
||||
4. **`RestTemplate` 配置**：在 `JackettConfig` 或 `RestTemplate` 的 `@Bean` 创建处，设置连接超时和读取超时
|
||||
```java
|
||||
SimpleClientHttpRequestFactory factory = new SimpleClientHttpRequestFactory();
|
||||
factory.setConnectTimeout(10_000); // 10秒连接超时
|
||||
factory.setReadTimeout(30_000); // 30秒读取超时
|
||||
RestTemplate restTemplate = new RestTemplate(factory);
|
||||
```
|
||||
|
||||
**注意事项**：
|
||||
- 线程池要确保应用关闭时正确 shutdown（可以用 `@PreDestroy` 或在 Spring 的 `@Bean(destroyMethod="shutdown")`）
|
||||
- 并发度不宜过高（3-5 即可），避免 Jackett 服务端限流
|
||||
- `searchSingleKeyword()` 和 `searchRecent()` 内部已有 try-catch，在 CompletableFuture 内还会继续 catch，注意异常不会自动传播到 `future.get()`，需要 `CompletableFuture` 的 `handle()` 或自行封装
|
||||
|
||||
---
|
||||
|
||||
### P2-1：文件按日期分片替代无限追加
|
||||
|
||||
**描述**：`ResourcesUtils.saveFile(content, wujiBaseDirectory, "hot")` 永远追加到同一个 `hot.txt`，文件无限增长。
|
||||
|
||||
**改动点**：
|
||||
|
||||
1. **`JackettServiceImpl.dailyHot()`**：传入文件名时带上日期
|
||||
```java
|
||||
// ❌ 旧
|
||||
ResourcesUtils.saveFile(resultVO.getMagnetUri(),
|
||||
jackettProperties.getWujiBaseDirectory(), "hot");
|
||||
|
||||
// ✅ 新：按日期分文件
|
||||
String dateStr = LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyy-MM-dd"));
|
||||
ResourcesUtils.saveFile(resultVO.getMagnetUri(),
|
||||
jackettProperties.getWujiBaseDirectory(), "hot-" + dateStr);
|
||||
```
|
||||
或按年月日三级目录：
|
||||
```java
|
||||
String yyyy = LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyy"));
|
||||
String MMdd = LocalDateTime.now().format(DateTimeFormatter.ofPattern("MM/dd"));
|
||||
ResourcesUtils.saveFile(resultVO.getMagnetUri(),
|
||||
jackettProperties.getWujiBaseDirectory() + "/" + yyyy + "/" + MMdd, "hot");
|
||||
```
|
||||
|
||||
2. 或者如果决定改入库（推荐方案）：
|
||||
在 `JavInfoDO` 中新增 `magnet_uri` 字段，在 `insertBatch` 时一并写入，完全替代文件存储。
|
||||
|
||||
此时 `dailyHot()` 循环内去掉 `saveFile` 调用，`toInsert` 中设置 `magnetUri`。
|
||||
|
||||
**注意事项**：
|
||||
- 如果选择入库替代文件，需要考虑 `JavInfoDO` 表结构变更和数据库 migration，改动量更大
|
||||
- 如果继续用文件，建议增加清理策略（如保留最近 30 天的文件，自动删除过期文件）
|
||||
|
||||
---
|
||||
|
||||
### P2-2：日期过滤改为时间窗口
|
||||
|
||||
**描述**：当前用 `resultVO.getPublishDate().getYear() != currentYear` 过滤，语义是「当年发布」而非「最近发布」。跨年时段逻辑偏差明显。
|
||||
|
||||
**改动点**：
|
||||
|
||||
**`JackettServiceImpl.dailyHot()`**：替换过滤条件
|
||||
```java
|
||||
// ❌ 旧
|
||||
if (resultVO.getPublishDate() == null
|
||||
|| resultVO.getPublishDate().getYear() != currentYear) {
|
||||
continue;
|
||||
}
|
||||
|
||||
// ✅ 新：最近 24 小时内发布
|
||||
LocalDateTime since = LocalDateTime.now().minusHours(24);
|
||||
if (resultVO.getPublishDate() == null
|
||||
|| resultVO.getPublishDate().isBefore(since)) {
|
||||
continue;
|
||||
}
|
||||
```
|
||||
|
||||
时间窗口大小建议外部化配置：
|
||||
```yaml
|
||||
jackett:
|
||||
hot-window-hours: 24
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### P2-3：避免 Thread.sleep 阻塞 Quartz 线程
|
||||
|
||||
**描述**：`Thread.sleep(searchDelay)` 在 Quartz 的 `@DisallowConcurrentExecution` 工作线程中阻塞，无法处理其他 Job。
|
||||
|
||||
**改动点**：
|
||||
|
||||
如果改用了 P1-2 的并发方案（CompletableFuture），线程池已经独立于 Quartz 线程，sleep 问题自然解决。如果暂时不改并发，至少：
|
||||
|
||||
1. 将 `searchDelay` 从 sleep 改为使用 `ScheduledExecutorService` 调度
|
||||
2. 或者在并发方案中就解决了，不用额外改动
|
||||
|
||||
**推荐**：P1-2 的并发方案已经涵盖了这一条，不需要独立处理。
|
||||
|
||||
---
|
||||
|
||||
### P3-1：Redis Key 硬编码修复
|
||||
|
||||
**描述**：`saveRedisIds()` 中的 Redis key 硬编码为 `"\""jav:rank:2023"\""`，年份过时且带有多余引号。
|
||||
|
||||
**改动点**：
|
||||
|
||||
**`JackettProperties.java`**：新增配置项
|
||||
```java
|
||||
/** Redis 热门排名 Key */
|
||||
private String redisRankKey = "jav:rank";
|
||||
```
|
||||
|
||||
**`JackettServiceImpl.saveRedisIds()`**：改为使用配置
|
||||
```java
|
||||
// ❌ 旧
|
||||
String key = "\""jav:rank:2023"\"";
|
||||
|
||||
// ✅ 新
|
||||
String key = jackettProperties.getRedisRankKey();
|
||||
```
|
||||
|
||||
**`application.yml`**：添加配置
|
||||
```yaml
|
||||
jackett:
|
||||
redis-rank-key: "jav:rank:2026" # 或更通用 key
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### P3-2：幂等性/中断支持
|
||||
|
||||
**描述**：Job 执行中断时，已 insert 的记录和已保存的文件产生不一致，下次执行产生重复数据。
|
||||
|
||||
**改动点**：
|
||||
|
||||
1. **数据库层**：`JavInfoDO.jav_id` 加 UNIQUE 约束，`insertBatch` 使用 `INSERT IGNORE` → 幂等写入，重复自动跳过
|
||||
```sql
|
||||
ALTER TABLE wellness_jav_info ADD UNIQUE INDEX uk_jav_id (jav_id);
|
||||
```
|
||||
|
||||
2. **文件层**：按日期分片后（P2-1），同一天执行多次也是追加到同一个日期文件，仍然会重复。可以在写入前检查是否已存在：
|
||||
```java
|
||||
// 方式 A：先读文件内容做 Set 去重（小文件可行，大文件低效）
|
||||
// 方式 B：不管去重，反正按日期分片，运维定期清理即可
|
||||
```
|
||||
|
||||
3. **「执行中标记」**：可选地在 Redis 中设置一个锁/标记，防止同一个 Job 实例并发（Quartz 的 `@DisallowConcurrentExecution` 已经解决了同一实例的并发，但多实例部署还需要确认）
|
||||
|
||||
---
|
||||
|
||||
## 验收条件
|
||||
|
||||
| # | 验收项 | 验证方式 |
|
||||
|---|--------|----------|
|
||||
| 1 | 异常能被 Job 框架记录 | 手动使 FlareSolverr 不可用，观察 Job 日志面板显示失败状态 |
|
||||
| 2 | 租户注解正确 | 多租户环境下执行 Job，确认没有错误的 `tenant_id` SQL |
|
||||
| 3 | 数据库批量查询+插入 | 100+ hotIds 时，SQL 日志只出现一次 select 和一次 insert |
|
||||
| 4 | 并发搜索 | 50 个新 ID 的搜索时间 ≤ 30s（之前 4+ 分钟） |
|
||||
| 5 | 文件按日期分片 | 执行每天 Job 后，目录下生成 `hot-2026-04-26.txt` 格式文件，而非累加到一个文件 |
|
||||
| 6 | 日期过滤正确 | 插入数据库的应该是最近 24h 发布的数据，而非整年数据 |
|
||||
| 7 | Redis Key 可配置 | 修改 `application.yml` 中的 `jackett.redis-rank-key`，Job 读取新值 |
|
||||
| 8 | 幂等性 | 同一批 hotIds 执行两次，数据库和文件不产生重复记录 |
|
||||
@@ -0,0 +1,206 @@
|
||||
# DailyHotJob 代码审查报告
|
||||
|
||||
> 审查目标：`DailyHotJob#execute()` + `JackettServiceImpl.dailyHot()`
|
||||
> 审查时间：2026-04-25
|
||||
> 审查人：需求分析助手
|
||||
|
||||
---
|
||||
|
||||
## 1. 整体架构概览
|
||||
|
||||
```
|
||||
DailyHotJob.execute(param)
|
||||
└─ JackettServiceImpl.dailyHot()
|
||||
├─ getDailyHotIds() → 爬取 wuji.me 获取 hot IDs
|
||||
│ └─ getPageContent(url) → 通过 FlareSolverr 获取 HTML
|
||||
├─ 逐条 selectOne 查重 → 过滤已存在的 ID
|
||||
├─ 循环（逐条串行）：
|
||||
│ ├─ searchSingleKeyword() → 调用 Jackett API
|
||||
│ ├─ 内存过滤（大小≥3G、当年发布）
|
||||
│ ├─ ResourcesUtils.saveFile() → 追加写到 hot.txt
|
||||
│ ├─ javInfoMapper.insert() → 逐条插入
|
||||
│ └─ Thread.sleep() → sleep 间隔
|
||||
└─ 结束
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 🔴 P0 严重问题
|
||||
|
||||
### 2.1 异常全被吞，Job 日志永远显示「成功」
|
||||
|
||||
`JobHandlerInvoker` 依赖 `exception != null` 判断 Job 是否执行成功：
|
||||
|
||||
```java
|
||||
// JobHandlerInvoker 的关键逻辑
|
||||
try {
|
||||
data = this.executeInternal(jobHandlerName, jobHandlerParam);
|
||||
} catch (Throwable ex) {
|
||||
exception = ex; // 只有这里 exception 才非 null
|
||||
}
|
||||
```
|
||||
|
||||
但 `DailyHotJob.execute()` 和 `dailyHot()` 内的每一层都是：
|
||||
|
||||
```java
|
||||
// DailyHotJob
|
||||
@Override
|
||||
public String execute(String param) {
|
||||
jackettService.dailyHot(); // 没有 throws，异常全在里面吞了
|
||||
return "每日热点"; // 永远返回正常字符串
|
||||
}
|
||||
|
||||
// dailyHot() 内部
|
||||
for (...) {
|
||||
try {
|
||||
...
|
||||
} catch (Exception e) {
|
||||
log.error("搜索 '{}' 时出错", javId, e.getMessage()); // 只打日志
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**后果**：即使远程 API 完全不可用、所有搜索全失败，Job 日志面板仍然显示「成功」。运维人员无法通过框架面板感知故障。
|
||||
|
||||
### 2.2 租户注解缺失问题
|
||||
|
||||
```java
|
||||
@Override
|
||||
@TenantIgnore // ← 只有最外层加了
|
||||
public void dailyHot() { ... }
|
||||
```
|
||||
|
||||
`dailyHot()` 内部调用了 `this.getDailyHotIds()`、`this.getPageContent()`、`this.searchSingleKeyword()`，都是**内部方法调用**。
|
||||
|
||||
在 Spring AOP（JDK 动态代理）下，内部 `this.method()` 不会触发 `@TenantIgnore` 切面。如果 ruoyi 的租户 SQL 拦截器处于激活状态，可能导致这些方法执行时产生错误的 `WHERE tenant_id = ?` 过滤。
|
||||
|
||||
`saveRedisIds()` 方法也完全没加 `@TenantIgnore`，同样有风险。
|
||||
|
||||
---
|
||||
|
||||
## 3. 🟠 P1-P2 中等问题
|
||||
|
||||
### 3.1 N+1 数据库查询 + 逐条 insert
|
||||
|
||||
```java
|
||||
// N 次独立 selectOne
|
||||
Set<String> newIds = hotIds.stream()
|
||||
.filter(javId -> javInfoMapper.selectOne(JavInfoDO::getJavId, javId) == null)
|
||||
.collect(Collectors.toSet());
|
||||
|
||||
// M 次独立 insert
|
||||
for (String javId : newIds) {
|
||||
JavInfoDO javInfo = new JavInfoDO();
|
||||
javInfo.setJavId(javId);
|
||||
javInfoMapper.insert(javInfo); // 逐条
|
||||
}
|
||||
```
|
||||
|
||||
如果 hotIds 有 200 条，就是 200 次 select + 若干次 insert，数据库连接往返开销巨大。
|
||||
|
||||
**建议**：改为 `selectByJavIds(Collection)` 批量查重 + `insertBatch` 批量插入。
|
||||
|
||||
### 3.2 逐条串行远程搜索 + sleep 阻塞
|
||||
|
||||
```java
|
||||
for (String javId : newIds) {
|
||||
List<JackettSearchResultVO> results = searchSingleKeyword(javId, 30);
|
||||
// 过滤...
|
||||
Thread.sleep(jackettProperties.getSearchDelay()); // 通常 1-3s
|
||||
}
|
||||
```
|
||||
|
||||
假设只差 50 条新 ID，每次 search 耗时 3s + sleep 2s = 5s/条 → **总共 250 秒（4+ 分钟）**。如果匹配更多，耗时线性增长。
|
||||
|
||||
**建议**：使用并行流或 `CompletableFuture` 控制并发度（3-5），同时为 `RestTemplate` 配置连接/读取超时。
|
||||
|
||||
### 3.3 文件无限追加不轮转
|
||||
|
||||
```java
|
||||
ResourcesUtils.saveFile(resultVO.getMagnetUri(),
|
||||
jackettProperties.getWujiBaseDirectory(), "hot");
|
||||
```
|
||||
|
||||
每次都追加到同一个 `hot.txt`，永不清理。每天几十上百条磁力链接，一年后文件可能几十上百 MB，I/O 持续劣化。
|
||||
|
||||
**建议**：按日期分文件，如 `hot/2026-04-25.txt`；或改用数据库存储。
|
||||
|
||||
### 3.4 年度过滤器不符合「热点」语义
|
||||
|
||||
```java
|
||||
if (resultVO.getPublishDate().getYear() != currentYear) {
|
||||
continue;
|
||||
}
|
||||
```
|
||||
|
||||
如果今天是 2026-04-25，这个条件会接受 2026-01-01 到 2026-04-24 的所有结果，而不是「最近发布的结果」。
|
||||
|
||||
**建议**：改为 `isAfter(LocalDateTime.now().minusHours(N))` 时间窗口过滤。
|
||||
|
||||
---
|
||||
|
||||
## 4. 🟡 P3 潜在坑
|
||||
|
||||
### 4.1 Redis Key 硬编码且已过时
|
||||
|
||||
```java
|
||||
String key = "\"jav:rank:2023\"";
|
||||
```
|
||||
|
||||
- 2023 硬编码，距离现在已经 3 年
|
||||
- Key 带多余的双引号，实际可能是 `jav:rank:2023`
|
||||
- 如果这是保存历史 ID 的入口，2023 早已不是有效数据源
|
||||
|
||||
### 4.2 非幂等 + 中断无保护
|
||||
|
||||
Job 执行到一半时应用关闭：
|
||||
- 已插入的 `JavInfoDO` 已提交（无事务包裹）
|
||||
- 已写入文件的磁力链已持久化
|
||||
- 下次执行时已入库的 ID 被跳过，但 `hot.txt` 用 APPEND 追加，**产生重复行**
|
||||
|
||||
### 4.3 Redis 数据清洗掩盖上游 Bug
|
||||
|
||||
```java
|
||||
private String cleanString(String raw) {
|
||||
// 去首尾引号 + 转义
|
||||
String cleaned = raw;
|
||||
if (cleaned.startsWith("\"")) cleaned = cleaned.substring(1);
|
||||
if (cleaned.endsWith("\"")) cleaned = cleaned.substring(0, cleaned.length() - 1);
|
||||
cleaned = cleaned.replace("\\\"", "\"");
|
||||
return cleaned.isEmpty() ? null : cleaned;
|
||||
}
|
||||
```
|
||||
|
||||
Redis 的 Set<String> 中存储的值不应该带序列化引号或转义。出现这种情况说明**上游写入数据的方式有问题**。消费侧做清洗只是遮盖症状，不是根本解决。
|
||||
|
||||
### 4.4 `saveFile()` 两个重载路径冲突
|
||||
|
||||
```java
|
||||
// 重载1（dailyHot 调用的）
|
||||
saveFile(content, path, fileName) → Paths.get(path, fileName + ".txt")
|
||||
|
||||
// 重载2
|
||||
saveFile(content, name) → dir = "/app/daily"; Paths.get(dir, name + ".txt")
|
||||
```
|
||||
|
||||
重载2 硬编码了 `/app/daily`，如果其他调用方使用了这个重载但没有意识到路径硬编码，可能产生预期外的写入位置。
|
||||
|
||||
### 4.5 `Thread.sleep` 占用 Quartz 线程
|
||||
|
||||
`Thread.sleep` 是阻塞操作，在 Quartz 的工作线程中执行会让该线程无法处理其他 Job。虽然 `@DisallowConcurrentExecution` 避免了同 Job 并行，但如果 `JackettServiceImpl` 被多个 Job 共享，sleep 期间资源浪费更明显。
|
||||
|
||||
---
|
||||
|
||||
## 5. 改造建议优先级
|
||||
|
||||
| 优先级 | 问题 | 建议方案 |
|
||||
|--------|------|----------|
|
||||
| **P0** | 异常吞没，运维盲区 | `dailyHot()` 改为 `throws Exception`，仅捕获可恢复异常，向上传播不可恢复异常 |
|
||||
| **P0** | 租户注解内部调用不生效 | 在 `getDailyHotIds()`、`searchSingleKeyword()`、`saveRedisIds()` 上也加 `@TenantIgnore` |
|
||||
| **P1** | N+1 数据库操作 | 替换为 `selectByJavIds` 批量查重 + `insertBatch` 批量插入 |
|
||||
| **P1** | 串行远程搜索过慢 | `CompletableFuture` 并发（并发度 3-5），配置 RestTemplate 超时（connect+read） |
|
||||
| **P2** | 文件追加不轮转 | 按日期分文件：`hot/yyyy-MM-dd.txt` |
|
||||
| **P2** | 年度过滤语义不对 | 改为最近 N 小时/天的时间窗口过滤 |
|
||||
| **P2** | Thread.sleep 阻塞 | 使用 `ThreadPoolTaskScheduler` 或 `ScheduledThreadPoolExecutor` 提交异步任务 |
|
||||
| **P3** | Redis Key 硬编码 | 提取为配置项 `wuji.redis-rank-key` |
|
||||
| **P3** | 非幂等设计 | 改造为支持幂等（基于 jav_id 唯一约束的 `ON DUPLICATE KEY UPDATE`，文件去重写入） |
|
||||
Reference in New Issue
Block a user