up

2025-11-26 16:10:17 +08:00
parent f0e85c5a18
commit c10bd369c0
83 changed files with 1755 additions and 541 deletions
--- a/docs/task/tasker_implementation_guide.md
+++ b/docs/task/tasker_implementation_guide.md
@@ -0,0 +1,182 @@
+# Tasker实现规范指南
+
+## 1. Tasker架构概述
+
+Tasker是系统中用于执行异步任务的核心框架，主要用于处理耗时操作并提供实时进度反馈。Tasker架构包括：
+
+- **Tasker基类**：提供任务执行的基础框架和通信功能
+- **WebSocketServerTasker接口**：定义WebSocket通信任务的规范
+- **MessageHolder**：用于在任务执行过程中传递消息和更新进度
+
+## 2. 服务器端Tasker实现规范
+
+### 2.1 基本结构
+
+服务器端Tasker实现应遵循以下结构：
+
+```java
+@Data
+@EqualsAndHashCode(callSuper = true)
+public class YourTaskNameTask extends Tasker<Object> implements WebSocketServerTasker {
+    // 服务依赖
+    @Setter
+    private YourService service;
+    
+    @Override
+    public void init(JsonNode argsNode) {
+        // 初始化任务标题
+        updateTitle("任务标题");
+        // 初始化参数
+    }
+    
+    @Override
+    protected Object execute(MessageHolder holder) throws Exception {
+        // 实现业务逻辑
+        // 使用holder.info()、holder.error()等方法反馈消息
+        return null;
+    }
+}
+```
+
+### 2.2 关键注意事项
+
+1. **继承与实现**：
+   - 必须继承`Tasker<Object>`基类
+   - 必须实现`WebSocketServerTasker`接口
+
+2. **方法实现**：
+   - **不要重复实现**Tasker基类已提供的handler设置方法：`setMessageHandler`、`setTitleHandler`、`setPropertyHandler`、`setProgressHandler`
+   - 必须实现`init`方法，设置任务标题和初始化参数
+   - 必须实现`execute`方法，实现具体业务逻辑
+
+3. **进度和消息反馈**：
+   - 使用`updateProgress`方法提供进度更新
+   - 使用`MessageHolder`的`info`、`error`、`debug`等方法提供消息反馈
+
+4. **任务取消**：
+   - 在适当的地方检查`isCancelled()`状态，支持任务取消
+
+5. **注册要求**：
+   - 任务类必须在`tasker_mapper.json`中注册
+
+## 3. 客户端Tasker实现规范
+
+客户端Tasker实现应遵循：
+
+```java
+public class YourTaskNameTask extends Tasker<Object> {
+    @Override
+    protected Object execute(MessageHolder holder) throws Exception {
+        // 客户端任务逻辑
+        return null;
+    }
+}
+```
+
+## 4. 通信规范
+
+### 4.1 命名规范
+
+- 客户端和服务器端对应的Tasker类应使用**相同的类名**
+- 示例：客户端的`ContractSyncAllTask`对应服务器端的`ContractSyncAllTask`
+
+### 4.2 消息传递
+
+- 使用`MessageHolder`进行消息传递
+- 支持不同级别的消息：INFO、ERROR、DEBUG
+
+## 5. 最佳实践
+
+1. **任务拆分**：
+   - 将大型任务拆分为多个小任务，提高可维护性
+
+2. **异常处理**：
+   - 捕获并正确处理异常，使用`holder.error()`提供详细错误信息
+
+3. **资源管理**：
+   - 确保及时释放资源，特别是在任务取消的情况下
+
+4. **日志记录**：
+   - 使用`holder.debug()`记录调试信息
+   - 使用`holder.info()`记录进度信息
+
+5. **状态检查**：
+   - 定期检查`isCancelled()`状态，确保任务可以被及时取消
+
+## 6. 代码示例
+
+### 6.1 服务器端Tasker示例
+
+```java
+@Data
+@EqualsAndHashCode(callSuper = true)
+public class ExampleSyncTask extends Tasker<Object> implements WebSocketServerTasker {
+    @Setter
+    private ExampleService exampleService;
+    
+    @Override
+    public void init(JsonNode argsNode) {
+        updateTitle("示例同步任务");
+        // 从argsNode初始化参数
+    }
+    
+    @Override
+    protected Object execute(MessageHolder holder) throws Exception {
+        try {
+            // 获取总记录数
+            long total = exampleService.getTotalCount();
+            holder.info("开始同步数据，共" + total + "条记录");
+            
+            // 分批处理
+            long processed = 0;
+            List<ExampleEntity> entities = exampleService.getAllEntities();
+            
+            for (ExampleEntity entity : entities) {
+                // 检查是否取消
+                if (isCancelled()) {
+                    holder.info("任务已取消");
+                    return null;
+                }
+                
+                // 处理单个实体
+                exampleService.processEntity(entity);
+                processed++;
+                
+                // 更新进度
+                updateProgress(processed, total);
+                if (processed % 100 == 0) {
+                    holder.info("已处理" + processed + "/" + total + "条记录");
+                }
+            }
+            
+            holder.info("同步完成，共处理" + processed + "条记录");
+            return processed;
+        } catch (Exception e) {
+            holder.error("同步失败: " + e.getMessage());
+            throw e;
+        }
+    }
+}
+```
+
+## 7. 常见错误和避免方法
+
+1. **重复实现handler方法**：
+   - 错误：在子类中重复实现setMessageHandler等方法
+   - 解决：删除子类中的这些方法，直接使用Tasker基类提供的实现
+
+2. **缺少任务注册**：
+   - 错误：任务类没有在tasker_mapper.json中注册
+   - 解决：确保所有服务器端Tasker类都在配置文件中正确注册
+
+3. **类名不匹配**：
+   - 错误：客户端和服务器端Tasker类名不一致
+   - 解决：确保两端使用相同的类名
+
+4. **进度更新不正确**：
+   - 错误：进度计算错误或没有更新
+   - 解决：正确计算和更新进度，提高用户体验
+
+5. **资源泄漏**：
+   - 错误：未及时关闭数据库连接等资源
+   - 解决：使用try-with-resources或在finally块中关闭资源
--- a/docs/天眼查下载信用报告.md
+++ b/docs/天眼查下载信用报告.md
@@ -0,0 +1,58 @@
+# 天眼查企业信用报告下载操作指南
+
+## 操作目标
+使用 playwright MCP服务在天眼查平台上查询并下载目标企业的各类信用报告，包括：
+- 企业分析报告
+- 基础版企业信用报告
+- 专业版企业信用报告
+- 工商官网信息快照（图片格式）
+
+## 准备工作
+1. 确保已登录天眼查账户
+2. 确认浏览器下载路径设置为：`C:\Users\SQQ\Downloads\`
+3. 确保网络连接稳定
+
+## 操作步骤
+
+### 1. 企业搜索
+- 页面导航到 `https://www.tianyancha.com/nsearch?key={企业名称}`
+- 或者使用如下步骤：
+  - 在天眼查首页搜索框中输入目标企业全称
+  - 点击搜索按钮或按回车键
+  - 在搜索结果中点击目标企业进入详情页
+
+### 2. 生成企业报告
+- 在企业详情页找到并点击"报告"按钮
+- 在弹出的报告选择框中，依次点击以下报告的"下载报告"按钮：
+  - 企业分析报告
+  - 专业版企业信用报告
+  - 基础版企业信用报告
+- 每个报告下载点击有效时，页面上将提示会"报告已生成"
+
+### 3. 下载PDF报告
+- 进入个人中心报告页面：https://www.tianyancha.com/usercenter/report
+- 却换到 `报告下载`
+- 等待对应的三个报告的状态变为"报告完成"
+- 依次找到对应的报告行
+  - 点击对应报告行的操作列中的下载图标（操作列里有4个图标，第二个图标是下载，需要鼠标点击才会出现下载界面，这个图标是一个 SVG 图片，DOM 对象上没有任何文本，不能通过文本定位到这个按钮），不要使用"在线预览"的段落
+    - 出现 报告下载 窗口
+    - 格式选中：选中PDF格式
+    - 点击下载按钮，
+    - 关闭 报告下载 窗口
+  - 不要使用"在线预览"的段落，那样会打开一个新页面，而不是下载文件
+  - 不要使用 page.pdf 方法
+
+### 4. 下载工商官网快照
+- 在企业详情页找到"工商信息"模块
+- 点击"工商官网快照"链接
+- 在新打开的页面中点击"下载图片"按钮
+
+### 5. 移动文件
+- 将下载的PDF报告和图片文件移动至指定目录：`C:\Users\SQQ\Downloads\`
+
+## 注意事项
+1. 报告生成需要一定时间，请耐心等待
+2. 下载前确保报告状态为"报告完成"
+3. 如果报告下载失败，可尝试重新点击下载按钮
+4. 工商官网快照为图片格式，其他报告为PDF格式
+5. 部分高级报告可能需要会员权限才能下载