cloudcc-cli 2.2.8 → 2.2.9

package/docs/cloudcc/345/256/232/346/227/266/347/261/273.md

@@ -0,0 +1,302 @@
+# CloudCC 定时类使用指南
+
+## 一、什么是定时类
+
+**定时类（Scheduled Class）** 是 CloudCC 平台中用于**定时自动执行任务**的 Java 代码组件。它允许开发者编写自定义业务逻辑，按照预设的时间规则（如每天、每周、每月）自动运行，无需人工干预。
+
+---
+
+## 二、定时类能干什么
+
+基于线上实际运行的定时类案例，定时类主要能完成以下任务：
+
+### 1. 📧 自动通知与提醒
+
+**场景示例：**
+- **计划收款日期 7 天后发送邮件**：在计划收款日期到期 7 天后，自动发送邮件提醒相关人员
+- **15 日没有更新的线索提醒线索管理者**：检测超过 15 天未更新的线索，自动提醒线索管理者跟进
+
+**解决的问题：**
+- 避免人工遗忘重要时间节点
+- 确保关键业务通知及时送达
+- 减少重复性人工操作
+
+---
+
+### 2. 👥 客户关怀与销售提醒
+
+**场景示例：**
+- **客户长时间未联系新建活动通知销售**：根据客户分级（一般/重点/战略），在未联系达到指定天数（30/20/10 天）时，自动创建任务提醒销售跟进
+
+**解决的问题：**
+- 防止客户流失
+- 确保销售按节奏跟进客户
+- 差异化客户管理策略自动执行
+
+---
+
+### 3. 💼 商机自动生成
+
+**场景示例：**
+- **资产失效三个月自动生成业务机会**：检测失效时间满 3 个月的资产，自动创建维保业务机会（Opportunity）
+
+**解决的问题：**
+- 挖掘二次销售机会
+- 避免商机遗漏
+- 自动化销售漏斗填充
+
+---
+
+### 4. 📊 数据同步与推送
+
+**场景示例：**
+- **全量分月凭证推送**：定时将凭证数据推送到外部系统（如财务系统）
+
+**解决的问题：**
+- 系统间数据一致性
+- 减少人工导出导入
+- 确保数据及时同步
+
+---
+
+### 5. 📝 定期报告与任务创建
+
+**场景示例：**
+- **每季度提醒区域总更新城市调研报告**：定期提醒区域负责人更新调研报告
+- **定时创建任务**：按规则批量创建任务记录
+
+**解决的问题：**
+- 周期性工作自动化
+- 确保合规性要求
+- 减少管理成本
+
+---
+
+## 三、为什么要用定时类
+
+### 对比人工操作
+
+| 维度 | 人工操作 | 定时类 |
+|------|----------|--------|
+| **准确性** | 容易遗漏、出错 | 100% 按规则执行 |
+| **及时性** | 依赖记忆和自觉 | 准时触发 |
+| **成本** | 人力成本高 | 一次开发，长期受益 |
+| **可扩展性** | 难以处理大量数据 | 可批量处理 |
+| **可追溯性** | 难以追踪 | 有执行日志 |
+
+### 核心价值
+
+1. **自动化**：将重复性、规则明确的工作交给系统
+2. **标准化**：确保业务流程按统一标准执行
+3. **效率提升**：释放人力，专注于高价值工作
+4. **风险控制**：避免因人为疏忽导致的业务损失
+
+---
+
+## 四、什么情况下使用定时类
+
+### ✅ 适合使用定时类的场景
+
+| 特征 | 说明 | 案例 |
+|------|------|------|
+| **周期性** | 需要按固定频率执行 | 每天、每周、每月 |
+| **规则明确** | 执行逻辑清晰、可编码 | 如果 A 则 B |
+| **批量处理** | 需要处理大量数据 | 遍历所有客户 |
+| **时间敏感** | 需要在特定时间点执行 | 到期提醒 |
+| **跨系统** | 需要与外部系统交互 | 数据推送 |
+| **易遗漏** | 人工容易忘记 | 客户关怀 |
+
+### ❌ 不适合使用定时类的场景
+
+| 场景 | 原因 | 建议方案 |
+|------|------|----------|
+| **实时性要求极高** | 定时类有执行间隔 | 使用触发器（Trigger） |
+| **需要人工判断** | 逻辑无法编码 | 人工审批流程 |
+| **一次性任务** | 开发成本不划算 | 手动执行或脚本 |
+| **频繁变更的规则** | 维护成本高 | 配置化方案 |
+
+---
+
+## 五、典型业务场景
+
+### 场景 1：销售管理
+
+```
+问题：销售忘记跟进客户，导致客户流失
+
+定时类方案：
+- 每天上午 8 点执行
+- 查询所有客户的"未联系天数"
+- 根据客户分级判断是否需要提醒
+- 自动创建任务或发送邮件
+```
+
+### 场景 2：财务管理
+
+```
+问题：收款提醒不及时，影响回款率
+
+定时类方案：
+- 每天检查计划收款日期
+- 提前 7 天发送邮件提醒
+- 逾期 3 天升级通知上级
+```
+
+### 场景 3：客户服务
+
+```
+问题：资产到期后未及时发现二次销售机会
+
+定时类方案：
+- 每天凌晨 1 点执行
+- 查询失效满 3 个月的资产
+- 自动生成维保业务机会
+- 分配给对应销售人员
+```
+
+### 场景 4：数据管理
+
+```
+问题：线索长期不更新，数据质量下降
+
+定时类方案：
+- 每天检查线索最后更新时间
+- 超过 15 天未更新的线索
+- 提醒线索管理者跟进
+```
+
+### 场景 5：系统集成
+
+```
+问题：CRM 与财务系统数据不同步
+
+定时类方案：
+- 每月 10 日下午 4 点执行
+- 导出当月凭证数据
+- 推送到财务系统
+- 记录同步日志
+```
+
+---
+
+## 六、定时类技术特点
+
+### 开发规范
+
+```java
+package schedule.定时类名称;
+
+import com.cloudcc.core.*;
+
+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 分钟）
+- **日志**：执行日志可在后台查看
+
+---
+
+## 七、最佳实践
+
+### 1. 幂等性设计
+
+```java
+// ✅ 推荐：检查是否已处理
+if ("否".equals(obj.get("sfscwbjh"))) {
+    // 执行业务逻辑
+    obj.put("sfscwbjh", "是");
+    cs.update(obj);
+}
+
+// ❌ 避免：重复执行会产生重复数据
+```
+
+### 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);
+}
+
+// ❌ 避免：循环中单条操作
+```
+
+### 3. 异常处理
+
+```java
+// ✅ 推荐：捕获异常，记录日志
+try {
+    // 业务逻辑
+} catch (Exception e) {
+    System.out.println("错误：" + e.getMessage());
+    // 或记录到自定义对象
+}
+```
+
+### 4. 性能优化
+
+```java
+// ✅ 推荐：减少查询次数
+// 先批量查询，再内存处理
+List<CCObject> all = cs.cquery("Account", "1=1");
+
+// ❌ 避免：循环中查询
+for (CCObject obj : list) {
+    cs.cquery("Contact", "accountid='" + obj.get("id") + "'"); // 慢！
+}
+```
+
+---
+
+## 八、总结
+
+**定时类是 CloudCC 平台自动化能力的核心组件**，它让系统能够：
+
+- ⏰ **按时执行**：在预设时间自动运行
+- 🔄 **批量处理**：高效处理大量数据
+- 🔗 **系统集成**：连接外部系统
+- 📢 **主动通知**：邮件、任务、短信提醒
+- 💡 **智能决策**：基于规则自动创建商机、任务等
+
+**适用场景关键词**：周期性、规则明确、批量、时间敏感、易遗漏
+
+**核心价值**：释放人力、提升效率、降低风险、确保标准化
+
+---
+
+*文档基于线上实际运行的 9 个定时类案例总结*  
+*最后更新：2026-03-25*

package/docs//350/207/252/345/256/232/344/271/211/347/261/273.md

@@ -0,0 +1,258 @@
+# CloudCC 自定义类能力与适用场景说明
+
+## 1. 文档目标
+
+本文用于说明 CloudCC 自定义类（Class）在企业业务系统中的定位与价值，回答以下问题：
+
+- 自定义类能干什么
+- 自定义类主要作用是什么
+- 为什么要用自定义类
+- 自定义类能解决哪些问题
+- 在什么情况下、什么业务场景下使用
+
+本文结合两类信息编写：
+
+- CloudCC 官方“后端 SDK 参考（Java）”能力（如 `CCService`、`CCObject`、`UserInfo`、`SendEmail`、`DevLogger`、`TimeUtil`）
+- 当前线上环境中的自定义类实际情况（共 87 个，含 `Controller`、`Util`、`Service`、`Handler`、`Bot` 等类型）
+
+---
+
+## 2. 什么是 CloudCC 自定义类
+
+自定义类是运行在 CloudCC 服务端的 Java 业务代码载体，可作为“后端能力层”被以下模块调用：
+
+- 页面动作/按钮（如详情页按钮触发）
+- 触发器（Trigger）
+- 定时类（Scheduled Class / Timer）
+- 其他自定义类（复用）
+
+它的本质是：把业务规则、数据处理、对外集成封装为可复用的服务逻辑，而不是分散在页面脚本或单一触发器里。
+
+---
+
+## 3. 自定义类能干什么（能力清单）
+
+结合官方 SDK，自定义类主要具备以下能力。
+
+### 3.1 数据读写与业务处理
+
+基于 `CCService` + `CCObject` 可实现：
+
+- 新增：`insert(CCObject)`
+- 修改：`update(CCObject)`
+- 删除：`delete(CCObject)`
+- 条件查询：`cquery(apiName, condition, order)`
+- CQL 查询：`cqlQuery(apiName, cql)`
+
+适合处理跨对象计算、批量数据修复、复杂条件检索与更新。
+
+### 3.2 复杂规则计算与封装
+
+可将复杂逻辑沉淀为通用方法，例如：
+
+- 业绩/目标达成率计算
+- 评分/分层/分配策略
+- 订单拆分与状态推进
+- 多步骤审批前置校验
+
+### 3.3 对外系统集成
+
+可在服务端发起第三方交互并做封装，常见包括：
+
+- 调用外部 HTTP API（如企业内部系统、第三方服务）
+- 对接企业消息/邮件通知（`SendEmail`）
+- 统一输入输出结构、重试与异常兜底
+
+### 3.4 统一日志与可观测
+
+通过 `DevLogger` 记录关键日志，便于排查：
+
+- 核心入参
+- 关键决策分支
+- 异常上下文（错误信息、栈、业务主键）
+
+### 3.5 多时区时间处理
+
+通过 `TimeUtil` 使用用户时区相关时间能力，避免直接 `new Date()` 在跨时区下导致的偏差。
+
+### 3.6 服务化复用
+
+可作为“公共库”被多个触发器、定时任务、页面调用，避免重复实现，降低维护成本。
+
+---
+
+## 4. 自定义类的主要作用
+
+自定义类在 CloudCC 架构中的核心作用可以归纳为 4 点：
+
+1. **承载复杂后端逻辑**：把难以在页面层表达的业务规则下沉到服务端。  
+2. **形成可复用能力**：同一逻辑可被多个流程复用，减少复制粘贴。  
+3. **隔离变化与降低耦合**：页面、触发器、定时器只做编排，细节集中在类里。  
+4. **提升稳定性与治理性**：可统一异常处理、日志、权限与时区策略。  
+
+---
+
+## 5. 为什么要用自定义类
+
+### 5.1 页面脚本/流程配置不够表达复杂度
+
+当逻辑包含“多对象关联 + 多分支判断 + 外部交互 + 事务结果回写”时，自定义类是更稳妥的实现方式。
+
+### 5.2 需要服务端可信执行
+
+对关键规则（如金额校验、状态流转、权限校验）要求高时，应放在服务端，避免仅依赖前端校验。
+
+### 5.3 需要跨场景复用
+
+同一能力在触发器、定时任务、按钮动作都要用时，抽成自定义类可显著降低维护难度。
+
+### 5.4 需要可观测与可维护
+
+服务端类可统一日志与异常治理，问题定位效率高于散落在多处脚本中的实现。
+
+---
+
+## 6. 自定义类能解决哪些问题
+
+## 6.1 数据一致性问题
+
+- 保存前/保存后数据规则难统一
+- 多对象联动导致状态不同步
+- 批量变更时局部失败难控制
+
+## 6.2 复杂计算问题
+
+- 规则引擎化计算（计提、评分、归因）
+- 按角色、组织、区域进行差异化处理
+
+## 6.3 集成问题
+
+- 外部系统接口返回结构不稳定
+- 需要统一请求封装、失败重试、错误标准化
+
+## 6.4 性能与治理问题
+
+- 查询/更新逻辑重复且难优化
+- 缺少统一日志导致故障定位慢
+
+## 6.5 跨时区时间问题
+
+- 日期比较、提醒时间、截止时间在多时区下出现偏差
+
+---
+
+## 7. 什么情况下使用自定义类（决策准则）
+
+满足以下任一条件，优先考虑自定义类：
+
+- 业务规则超过页面层可维护阈值（分支多、链路长、对象多）
+- 同一逻辑需要被多处复用（触发器/定时器/页面/接口）
+- 需要对外系统集成与响应封装
+- 需要服务端强校验（合规、审计、财务、关键流程）
+- 需要统一异常、日志、时区、返回值协议
+
+反过来，以下场景可优先考虑其他能力：
+
+- 仅页面轻交互、字段联动：客户端脚本
+- 主要是数据写入前后钩子：触发器（复杂部分可调用类）
+- 明确按时间调度执行：定时类（复杂部分可调用类）
+- 仅新增数据结构：对象/字段配置
+
+---
+
+## 8. 典型业务场景（推荐）
+
+### 场景 1：销售流程控制器
+
+- 需求：商机/订单在多个状态节点切换，要求统一校验、补全字段、写入日志
+- 做法：`Controller` 类统一处理状态迁移，触发器只负责调用
+- 价值：规则集中、便于迭代与审计
+
+### 场景 2：通用工具类（数据与响应封装）
+
+- 需求：多个流程需要统一返回结构、异常编码、JSON 处理
+- 做法：`Util` + `ReturnResult` + `BusinessException` 风格封装
+- 价值：接口契约稳定，调用方成本降低
+
+### 场景 3：外部系统对接
+
+- 需求：调用第三方接口（如企业服务、外部查询、文件服务）
+- 做法：`Service` 类封装请求、签名、重试、错误翻译
+- 价值：外部波动被隔离，主流程更稳定
+
+### 场景 4：触发器逻辑下沉
+
+- 需求：触发器中逻辑过重，难测试、难复用
+- 做法：触发器保留触发时机判断，核心逻辑迁入 `Handler`/`Service` 类
+- 价值：降低触发器复杂度，减少回归风险
+
+### 场景 5：AI/助手类业务能力
+
+- 需求：会话分析、摘要、建议、合同辅助等服务端处理
+- 做法：`Bot` 类封装上下文处理、外部调用与业务落库
+- 价值：能力沉淀为后端服务，可跨入口复用
+
+---
+
+## 9. 与触发器/定时类/客户端脚本的分工
+
+- **自定义类**：复杂逻辑与复用能力中心（推荐作为“业务服务层”）
+- **触发器**：数据生命周期节点的编排与触发
+- **定时类**：时间驱动任务调度与批处理入口
+- **客户端脚本**：页面交互与轻量校验
+
+推荐模式：**触发器/定时类/页面脚本做“薄入口”，自定义类做“厚服务”**。
+
+---
+
+## 10. 设计与实施建议（落地实践）
+
+### 10.1 分层建议
+
+- `Controller`：面向入口，参数校验、编排流程
+- `Service`：承载核心业务逻辑
+- `Util`：通用工具、格式转换、公共方法
+- `Exception/Result`：统一错误码与返回结构
+
+### 10.2 开发建议
+
+- 避免在入口类写过长方法，提炼私有方法或服务类
+- 关键路径加入 `DevLogger` 日志（入参、结果、异常）
+- 日期时间统一使用 `TimeUtil` 相关方法
+- 对外调用统一封装超时、重试与错误翻译
+- 对批量场景做幂等与容错设计
+
+### 10.3 命名建议
+
+- 入口控制：`xxxController`
+- 业务服务：`xxxService`
+- 公共能力：`xxxUtil`
+- 触发器下沉：`xxxHandler`
+- 结果与异常：`xxxResult` / `xxxException`
+
+---
+
+## 11. 线上现状观察（来自当前环境）
+
+线上共 87 个自定义类，命名与职责呈现明显分层趋势：
+
+- `Controller` 类：承接流程入口与动作编排
+- `Util` 类：沉淀通用方法与查询能力
+- `Service` 类：承担外部集成与业务服务
+- `Handler` 类：承接触发器下沉逻辑
+- `Bot` 类：承载智能助手相关业务
+
+从源码统计看，当前环境中大量类已在使用：
+
+- `CCService`（数据 CRUD 与查询）
+- JSON 处理能力
+- 异常机制（`Exception` 相关）
+
+这说明自定义类已成为该环境中“复杂逻辑与复用能力”的核心载体。
+
+---
+
+## 12. 一句话结论
+
+当业务进入“多对象、复杂规则、跨系统、可复用、可治理”阶段时，CloudCC 自定义类是最关键的后端实现手段：它不仅能实现功能，更能提升系统长期可维护性与稳定性。
+