cloudcc-cli 2.3.8 → 2.4.0

package/src/timer/docs/introduction.md

@@ -1,302 +1,414 @@
-# CloudCC 定时类使用指南
+# CloudCC 定时器类分析说明
 
-## 一、什么是定时类
+## 1. 分析口径
 
-**定时类（Scheduled Class）** 是 CloudCC 平台中用于**定时自动执行任务**的 Java 代码组件。它允许开发者编写自定义业务逻辑，按照预设的时间规则（如每天、每周、每月）自动运行，无需人工干预。
+本文用于回答以下问题：
 
----
+- 定时器类能干什么
+- 定时器类的主要作用是什么
+- 为什么要用定时器类
+- 定时器类能解决哪些问题
+- 在什么情况下使用
+- 在什么业务场景下使用
 
-## 二、定时类能干什么
+## 2. 定时器类是什么
 
-基于线上实际运行的定时类案例，定时类主要能完成以下任务：
+定时器类是运行在 CloudCC 服务端、由调度机制按时间规则自动触发执行的 Java 业务代码载体。
 
-### 1. 📧 自动通知与提醒
+它的核心特征不是“谁触发”，而是“什么时候触发”。
 
-**场景示例：**
-- **计划收款日期 7 天后发送邮件**：在计划收款日期到期 7 天后，自动发送邮件提醒相关人员
-- **15 日没有更新的线索提醒线索管理者**：检测超过 15 天未更新的线索，自动提醒线索管理者跟进
+如果说：
 
-**解决的问题：**
-- 避免人工遗忘重要时间节点
-- 确保关键业务通知及时送达
-- 减少重复性人工操作
+- 触发器更偏向“某条记录发生变化时立刻执行”
+- 自定义类更偏向“承载可复用业务能力”
+- 定时器类更偏向“按时间批量扫描并自动执行”
 
----
+那么定时器类就是 CloudCC 中典型的“后台自动作业”实现方式。
 
-### 2. 👥 客户关怀与销售提醒
+在当前项目里，定时器类通常会按如下模式工作：
 
-**场景示例：**
-- **客户长时间未联系新建活动通知销售**：根据客户分级（一般/重点/战略），在未联系达到指定天数（30/20/10 天）时，自动创建任务提醒销售跟进
+- 查询一批满足条件的数据
+- 判断是否达到某个时间点、状态点或规则阈值
+- 执行更新、生成、同步、提醒或推进动作
+- 回写执行结果、状态、标记或日志
 
-**解决的问题：**
-- 防止客户流失
-- 确保销售按节奏跟进客户
-- 差异化客户管理策略自动执行
+因此，定时器类更适合承接那些：
 
----
+- 周期性发生
+- 规则相对稳定
+- 需要批量处理
+- 不要求毫秒级实时
+- 需要后台自动运行
 
-### 3. 💼 商机自动生成
+的业务任务。
 
-**场景示例：**
-- **资产失效三个月自动生成业务机会**：检测失效时间满 3 个月的资产，自动创建维保业务机会（Opportunity）
+## 3. 定时器类能干什么
 
-**解决的问题：**
-- 挖掘二次销售机会
-- 避免商机遗漏
-- 自动化销售漏斗填充
+### 3.1 主动提醒与催办
 
----
+定时器类可以自动识别“超期未处理”“长时间未推进”“达到提醒时间点”的业务记录，然后：
 
-### 4. 📊 数据同步与推送
+- 发送邮件
+- 创建任务
+- 发起催办
+- 通知负责人、区域负责人、项目经理等角色
 
-**场景示例：**
-- **全量分月凭证推送**：定时将凭证数据推送到外部系统（如财务系统）
+这类能力通常用于解决“人容易忘记，但业务又必须被持续跟进”的问题。
 
-**解决的问题：**
-- 系统间数据一致性
-- 减少人工导出导入
-- 确保数据及时同步
+### 3.2 数据同步与外部系统集成
 
----
+一批定时器明显承担了平台与外围系统之间的同步职责。
 
-### 5. 📝 定期报告与任务创建
+它们可以：
 
-**场景示例：**
-- **每季度提醒区域总更新城市调研报告**：定期提醒区域负责人更新调研报告
-- **定时创建任务**：按规则批量创建任务记录
+- 按批次推送数据到 SAP、财务、采购等系统
+- 定时调用外部接口
+- 同步字典、主数据或经营数据
+- 对失败任务做补偿性重试
+- 将外部系统结果回写到 CloudCC
 
-**解决的问题：**
-- 周期性工作自动化
-- 确保合规性要求
-- 减少管理成本
+这使定时器类成为“跨系统定时对接层”的重要落点。
 
----
+### 3.3 数据刷新、修正与回填
 
-## 三、为什么要用定时类
+这是数量最多的一类。
 
-### 对比人工操作
+定时器类可以：
 
-| 维度 | 人工操作 | 定时类 |
-|------|----------|--------|
-| **准确性** | 容易遗漏、出错 | 100% 按规则执行 |
-| **及时性** | 依赖记忆和自觉 | 准时触发 |
-| **成本** | 人力成本高 | 一次开发，长期受益 |
-| **可扩展性** | 难以处理大量数据 | 可批量处理 |
-| **可追溯性** | 难以追踪 | 有执行日志 |
+- 刷新派生字段
+- 修正历史数据
+- 回填缺失值
+- 统一编号、状态、负责人或关联关系
+- 批量修复迁移后遗留问题
+- 对旧数据重新计算并回写结果
 
-### 核心价值
+这类任务通常不是新建记录时立即完成，而是要通过后台批量方式持续治理。
 
-1. **自动化**：将重复性、规则明确的工作交给系统
-2. **标准化**：确保业务流程按统一标准执行
-3. **效率提升**：释放人力，专注于高价值工作
-4. **风险控制**：避免因人为疏忽导致的业务损失
+### 3.4 报表、底表与看板支撑
 
----
+一批定时器并不直接面向业务动作，而是面向分析层。
 
-## 四、什么情况下使用定时类
+它们可以：
 
-### ✅ 适合使用定时类的场景
+- 构建经营底表
+- 汇总报表数据
+- 刷新台账
+- 为看板预计算分析结果
+- 让前台报表直接读取已加工的数据层
 
-| 特征 | 说明 | 案例 |
-|------|------|------|
-| **周期性** | 需要按固定频率执行 | 每天、每周、每月 |
-| **规则明确** | 执行逻辑清晰、可编码 | 如果 A 则 B |
-| **批量处理** | 需要处理大量数据 | 遍历所有客户 |
-| **时间敏感** | 需要在特定时间点执行 | 到期提醒 |
-| **跨系统** | 需要与外部系统交互 | 数据推送 |
-| **易遗漏** | 人工容易忘记 | 客户关怀 |
+这说明定时器类不仅处理业务流程，也承担了部分“分析型数据加工层”的职责。
 
-### ❌ 不适合使用定时类的场景
+### 3.5 自动生成下游对象或推进流程
 
-| 场景 | 原因 | 建议方案 |
-|------|------|----------|
-| **实时性要求极高** | 定时类有执行间隔 | 使用触发器（Trigger） |
-| **需要人工判断** | 逻辑无法编码 | 人工审批流程 |
-| **一次性任务** | 开发成本不划算 | 手动执行或脚本 |
-| **频繁变更的规则** | 维护成本高 | 配置化方案 |
+部分定时器会在满足条件时自动创建新的业务对象，或者自动推进节点。
 
----
+这类能力包括：
 
-## 五、典型业务场景
+- 自动生成服务商机
+- 自动生成分期、产品线等派生记录
+- 自动创建项目目录或资料结构
+- 自动推进里程碑节点
+- 在满足条件时自动翻牌或进入下一阶段
 
-### 场景 1：销售管理
+本质上，这类定时器承担的是“流程衔接自动化”职责。
 
-```
-问题：销售忘记跟进客户，导致客户流失
+### 3.6 权限、共享与负责人治理
 
-定时类方案：
-- 每天上午 8 点执行
-- 查询所有客户的"未联系天数"
-- 根据客户分级判断是否需要提醒
-- 自动创建任务或发送邮件
-```
+还有一小批定时器明确承担治理类工作。
 
-### 场景 2：财务管理
+它们可以：
 
-```
-问题：收款提醒不及时，影响回款率
+- 根据负责人变化重算共享关系
+- 自动补齐读写权限
+- 删除过期或错误共享
+- 保证相关对象上的责任人和访问权限保持一致
 
-定时类方案：
-- 每天检查计划收款日期
-- 提前 7 天发送邮件提醒
-- 逾期 3 天升级通知上级
-```
+这类任务适合放在后台批量执行，因为它们通常涉及多对象、多角色联动。
 
-### 场景 3：客户服务
+## 4. 定时器类与触发器、自定义类的区别
 
-```
-问题：资产到期后未及时发现二次销售机会
+在当前项目里，这三类能力的分工非常清楚。
 
-定时类方案：
-- 每天凌晨 1 点执行
-- 查询失效满 3 个月的资产
-- 自动生成维保业务机会
-- 分配给对应销售人员
-```
+### 4.1 定时器类
 
-### 场景 4：数据管理
+重点解决“按时间自动执行”的问题。
 
-```
-问题：线索长期不更新，数据质量下降
+适合：
 
-定时类方案：
-- 每天检查线索最后更新时间
-- 超过 15 天未更新的线索
-- 提醒线索管理者跟进
-```
+- 每天、每周、每月定时执行
+- 达到某个日期后处理
+- 扫全量或扫增量数据
+- 失败补偿和后台批处理
 
-### 场景 5：系统集成
+### 4.2 触发器
 
-```
-问题：CRM 与财务系统数据不同步
+重点解决“记录发生变化时立即执行”的问题。
 
-定时类方案：
-- 每月 10 日下午 4 点执行
-- 导出当月凭证数据
-- 推送到财务系统
-- 记录同步日志
-```
-
----
-
-## 六、定时类技术特点
-
-### 开发规范
+适合：
 
-```java
-package schedule.定时类名称;
+- 新增、修改、删除时立即校验
+- 实时联动
+- 单次事务内必须完成的控制
 
-import com.cloudcc.core.*;
+### 4.3 自定义类
 
-public class 定时类名称 extends CCSchedule {
-    public 定时类名称() {
-        // @SOURCE_CONTENT_START
-        
-        // 业务逻辑写在这里
-        CCService cs = new CCService(userInfo);
-        List<CCObject> list = cs.cquery("Object", "条件");
-        
-        // @SOURCE_CONTENT_END
-    }
-}
-```
+重点解决“业务能力复用”的问题。
 
-### 可用 API
+适合：
 
-| 方法 | 说明 |
-|------|------|
-| `cs.cquery(对象，条件)` | 查询对象列表 |
-| `cs.insert(对象)` | 插入单条记录 |
-| `cs.insertLt(对象)` | 批量插入 |
-| `cs.update(对象)` | 更新单条记录 |
-| `cs.updateLt(对象)` | 批量更新 |
-| `SendEmail.sendMailFromSystem()` | 发送系统邮件 |
+- 承载复杂逻辑
+- 被按钮、页面、触发器、定时器共同调用
+- 作为服务层或工具层复用
 
-### 执行上下文
+因此，定时器类通常不是独立存在的，它往往会调用自定义类完成核心业务处理，只是负责把执行时机放到“定时调度”上。
 
-- **userInfo**：当前执行用户信息（通常为系统管理员）
-- **事务**：定时类在独立事务中执行
-- **超时**：单次执行有超时限制（通常 30 分钟）
-- **日志**：执行日志可在后台查看
+## 5. 定时器类的主要作用是什么
 
----
+综合来看，当前项目中的定时器类主要作用可以概括为以下 5 点。
 
-## 七、最佳实践
+### 5.1 把重复性业务自动化
 
-### 1. 幂等性设计
-
-```java
-// ✅ 推荐：检查是否已处理
-if ("否".equals(obj.get("sfscwbjh"))) {
-    // 执行业务逻辑
-    obj.put("sfscwbjh", "是");
-    cs.update(obj);
-}
+将每天、每周、每月都要做的动作交给系统自动执行，减少人工反复处理。
 
-// ❌ 避免：重复执行会产生重复数据
-```
+### 5.2 把时间规则系统化
 
-### 2. 批量处理
+把“超期多久提醒”“每月何时同步”“月底何时汇总”“节点满足后何时推进”等规则固化到后台执行逻辑中。
 
-```java
-// ✅ 推荐：批量插入/更新
-List<CCObject> batch = new ArrayList<>();
-for (CCObject obj : list) {
-    batch.add(obj);
-    if (batch.size() >= 200) {
-        cs.insertLt(batch);
-        batch.clear();
-    }
-}
-if (batch.size() > 0) {
-    cs.insertLt(batch);
-}
+### 5.3 把批量治理放到后台
 
-// ❌ 避免：循环中单条操作
-```
+让历史修正、状态重算、字段回填、编号修复、共享重算等任务不占用前台实时事务。
 
-### 3. 异常处理
-
-```java
-// ✅ 推荐：捕获异常，记录日志
-try {
-    // 业务逻辑
-} catch (Exception e) {
-    System.out.println("错误：" + e.getMessage());
-    // 或记录到自定义对象
-}
-```
+### 5.4 作为流程推进器
 
-### 4. 性能优化
-
-```java
-// ✅ 推荐：减少查询次数
-// 先批量查询，再内存处理
-List<CCObject> all = cs.cquery("Account", "1=1");
+在业务推进过程中，定时器类可以主动发现卡点、补齐动作、推进后续节点。
 
-// ❌ 避免：循环中查询
-for (CCObject obj : list) {
-    cs.cquery("Contact", "accountid='" + obj.get("id") + "'"); // 慢！
-}
-```
-
----
-
-## 八、总结
-
-**定时类是 CloudCC 平台自动化能力的核心组件**，它让系统能够：
-
-- ⏰ **按时执行**：在预设时间自动运行
-- 🔄 **批量处理**：高效处理大量数据
-- 🔗 **系统集成**：连接外部系统
-- 📢 **主动通知**：邮件、任务、短信提醒
-- 💡 **智能决策**：基于规则自动创建商机、任务等
-
-**适用场景关键词**：周期性、规则明确、批量、时间敏感、易遗漏
-
-**核心价值**：释放人力、提升效率、降低风险、确保标准化
-
----
+### 5.5 作为系统之间的批处理桥梁
 
-*文档基于线上实际运行的 9 个定时类案例总结*  
-*最后更新：2026-03-25*
+在 CloudCC 与 SAP、财务、采购、主数据源之间，定时器类常常承担定时推送、失败补偿、周期同步的桥梁角色。
+
+## 6. 为什么要用定时器类
+
+### 6.1 因为很多业务不是实时触发，而是时间触发
+
+有些动作不是记录一保存就该执行，而是：
+
+- 到期前提醒
+- 到期后催办
+- 每月汇总
+- 月初同步
+- 过几天未处理再通知
+
+这类任务天然更适合定时器，而不是触发器。
+
+### 6.2 因为人工执行不稳定
+
+如果依赖人工每天查报表、盯超时、做同步、补修数据，往往会出现：
+
+- 忘记执行
+- 执行不及时
+- 执行标准不一致
+- 执行后缺少留痕
+
+定时器类可以把这些动作标准化、自动化。
+
+### 6.3 因为批量任务不适合塞进实时事务
+
+很多任务需要：
+
+- 扫描大量记录
+- 汇总计算
+- 调接口
+- 修复历史数据
+
+如果放在触发器或页面动作里，会拖慢实时链路，甚至影响用户操作体验。
+
+### 6.4 因为需要失败补偿能力
+
+跨系统同步和推送很难保证每次都成功。
+
+定时器类可以：
+
+- 按批次重试
+- 定时补偿失败数据
+- 异常后通知相关人员
+- 用后台重跑方式恢复业务连续性
+
+### 6.5 因为需要长期治理而不是一次性处理
+
+很多问题不是一次脚本能彻底解决，而是需要长期巡检、长期修正、长期维护。
+
+这类治理型任务最适合放到定时器体系中持续运行。
+
+## 7. 定时器类能解决哪些问题
+
+从当前项目的定时器分布看，它们主要在解决以下问题。
+
+### 7.1 解决“业务节点没人盯”的问题
+
+例如：
+
+- 商机超期无人处理
+- 合同评审后迟迟不移交
+- 线索长时间未分配、未确认、未推进
+- 负责人没有及时跟进
+
+### 7.2 解决“系统间数据不同步”的问题
+
+例如：
+
+- CRM 与 SAP 经营数据不同步
+- 项目、合同、回款、采购等外围系统接口调用失败
+- 字典或主数据需要周期同步
+
+### 7.3 解决“历史数据脏乱差”的问题
+
+例如：
+
+- 编号缺失或不规范
+- 派生字段长期不准确
+- 迁移后旧数据未补齐
+- 负责人、状态、共享关系不一致
+
+### 7.4 解决“报表口径不稳”的问题
+
+例如：
+
+- 看板依赖的底表没有持续刷新
+- 台账数据与业务对象不一致
+- 报表统计需要预加工
+
+### 7.5 解决“流程到了但动作没跟上”的问题
+
+例如：
+
+- 条件满足后没有自动生成下游记录
+- 节点可以推进但没有及时翻牌
+- 派生对象没有按规则创建
+
+## 7. 在什么情况下使用定时器类
+
+定时器类最适合以下场景。
+
+### 8.1 周期性任务
+
+例如：
+
+- 每天执行
+- 每周执行
+- 每月执行
+- 月初、月末执行
+
+### 8.2 时间敏感但不要求实时
+
+例如：
+
+- 提前 7 天提醒
+- 超过 15 天未更新即通知
+- 每晚统一批处理
+
+### 8.3 需要批量扫描与批量处理
+
+例如：
+
+- 扫全部项目
+- 扫昨日变更数据
+- 扫本月待同步记录
+- 扫失败记录并补偿
+
+### 8.4 需要将重计算放到后台
+
+例如：
+
+- 经营底表重建
+- 历史数据修正
+- 权限重算
+- 派生字段统一刷新
+
+### 8.5 需要系统自动巡检
+
+例如：
+
+- 巡检超时事项
+- 巡检未完成流程
+- 巡检缺失数据
+- 巡检失败接口
+
+## 9. 什么情况下不适合用定时器类
+
+以下场景一般不适合优先使用定时器类。
+
+### 9.1 强实时控制场景
+
+如果用户保存数据时必须立刻校验、立刻拦截、立刻联动，那么更适合使用触发器。
+
+### 9.2 强交互场景
+
+如果动作依赖用户逐步确认、页面即时反馈、人工选择分支，那么更适合页面按钮、组件或流程交互。
+
+### 9.3 一次性临时任务
+
+如果只是临时清洗一次数据，通常更适合脚本或临时类，而不一定需要长期保留一个定时器。
+
+### 9.4 需要复杂人工判断的场景
+
+如果业务结论高度依赖人工判断、审批意见或线下协同，定时器类通常只能做提醒，不能替代人工决策。
+
+## 10. 典型业务场景
+
+结合当前项目现状，定时器类主要落在以下业务场景。
+
+### 10.1 销售与线索管理
+
+- 线索待分配、待确认、待决策、重复线索提醒
+- 商机超时提醒
+- 赢单、失单分析提醒
+- 商机移交时间更新提醒
+
+### 10.2 合同、报价与审批协同
+
+- 合同评审提醒
+- 移交合同提醒
+- 报价单催办
+- 合同额分配表催办
+- 合同相关状态和底表更新
+
+### 10.3 项目交付与里程碑推进
+
+- 项目出厂自动翻牌
+- 配置管理各阶段自动更新
+- 项目、开箱单、资产台账类数据刷新
+- 项目目录或资料结构自动创建
+
+### 10.4 财务、经营与集成
+
+- 预计总成本、预算、回款流水定时推送
+- 记账接口、采购接口调用
+- 收入看板底表更新
+- 月初、月末经营数据同步
+
+### 10.5 主数据与基础资料治理
+
+- 省市信息接口同步
+- 客户信息、交通信息、工业园区信息补齐
+- 产品线、规格、付款方式、物料类数据刷新
+
+### 10.6 权限与共享治理
+
+- 商机权限自动维护
+- 合同负责人变更后的共享修正
+- 项目负责人变更后的共享修正
+
+## 11. 总结
+
+一句话概括，当前项目中的定时器类适合承接“时间驱动、规则明确、批量执行、允许后台处理”的业务自动化任务。
+
+它们的价值不只是“定时跑代码”，而是把以下能力持续、稳定、标准化地放到后台：
+
+- 业务提醒
+- 数据治理
+- 流程推进
+- 集成补偿
+- 报表支撑
+- 权限维护
+
+因此，在 CloudCC 项目中，定时器类通常不是边缘能力，而是连接“运营动作、数据质量、流程节点、系统集成、经营分析”的核心后台机制。