cloudcc-cli 2.3.8 → 2.4.0

package/src/classes/docs/introduction.md

@@ -1,238 +1,374 @@
-# CloudCC 自定义类能力与适用场景说明
+# CloudCC 自定义类分析说明
 
-## 1. 文档目标
+## 1. 分析口径
 
-本文用于说明 CloudCC 自定义类（Class）在企业业务系统中的定位与价值，回答以下问题：
+本文用于回答以下问题：
 
 - 自定义类能干什么
-- 自定义类主要作用是什么
+- 自定义类的主要作用是什么
 - 为什么要用自定义类
 - 自定义类能解决哪些问题
-- 在什么情况下、什么业务场景下使用
+- 在什么情况下使用
+- 在什么业务场景下使用
 
-本文结合两类信息编写：
+## 2. 自定义类是什么
 
-- CloudCC 官方“后端 SDK 参考（Java）”能力（如 `CCService`、`CCObject`、`UserInfo`、`SendEmail`、`DevLogger`、`TimeUtil`）
-- 当前线上环境中的自定义类实际情况（共 87 个，含 `Controller`、`Util`、`Service`、`Handler`、`Bot` 等类型）
+自定义类是运行在 CloudCC 服务端的 Java 业务代码载体。
 
----
+它的定位不是页面本身，也不是触发器本身，而是被页面、按钮、触发器、定时类、组件或其他类调用的后端能力单元。
 
-## 2. 什么是 CloudCC 自定义类
+可以把它理解成 CloudCC 中的“业务服务层”：
 
-自定义类是运行在 CloudCC 服务端的 Java 业务代码载体，可作为“后端能力层”被以下模块调用：
+- 页面和按钮负责发起动作
+- 触发器和定时类负责触发时机
+- 自定义类负责真正的业务处理
 
-- 页面动作/按钮（如详情页按钮触发）
-- 触发器（Trigger）
-- 定时类（Scheduled Class / Timer）
-- 其他自定义类（复用）
+因此，自定义类更适合承载那些：
 
-它的本质是：把业务规则、数据处理、对外集成封装为可复用的服务逻辑，而不是分散在页面脚本或单一触发器里。
+- 逻辑复杂
+- 需要复用
+- 需要服务端执行
+- 需要跨对象处理
+- 需要和外部系统通信
 
----
+的能力。
 
-## 3. 自定义类能干什么（能力清单）
+## 3. 自定义类能干什么
 
-结合官方 SDK，自定义类主要具备以下能力。
+结合全部非测试类的逐类阅读，自定义类主要具备以下能力。
 
-### 3.1 数据读写与业务处理
+### 3.1 数据读写与对象联动
 
-基于 `CCService` + `CCObject` 可实现：
+这是最基础的能力，也是最普遍的能力。
 
-- 新增：`insert(CCObject)`
-- 修改：`update(CCObject)`
-- 删除：`delete(CCObject)`
-- 条件查询：`cquery(apiName, condition, order)`
-- CQL 查询：`cqlQuery(apiName, cql)`
+自定义类可以：
 
-适合处理跨对象计算、批量数据修复、复杂条件检索与更新。
+- 查询对象数据
+- 查询关联对象数据
+- 执行复杂条件检索
+- 新增、更新、删除记录
+- 在多个对象之间做联动更新
+- 在业务动作完成后回写状态、金额、标记和结果
 
-### 3.2 复杂规则计算与封装
+这使它非常适合承载“单次操作影响多个对象”的场景。
 
-可将复杂逻辑沉淀为通用方法，例如：
+### 3.2 复杂规则计算
 
-- 业绩/目标达成率计算
-- 评分/分层/分配策略
-- 订单拆分与状态推进
-- 多步骤审批前置校验
+大量自定义类并不是简单搬运数据，而是在做规则计算、汇总和判断。
 
-### 3.3 对外系统集成
+这类能力通常包括：
 
-可在服务端发起第三方交互并做封装，常见包括：
+- 根据多个条件计算结果
+- 根据角色、状态、时间、区域、分类决定不同处理路径
+- 汇总明细到主记录
+- 对数据进行分摊、拆分、匹配、校验和回写
 
-- 调用外部 HTTP API（如企业内部系统、第三方服务）
-- 对接企业消息/邮件通知（`SendEmail`）
-- 统一输入输出结构、重试与异常兜底
+当业务规则超出页面公式、字段配置或简单脚本能稳定承载的范围时，自定义类就是主要落点。
 
-### 3.4 统一日志与可观测
+### 3.3 流程编排与状态流转
 
-通过 `DevLogger` 记录关键日志，便于排查：
+自定义类非常适合做流程中的服务端编排。
 
-- 核心入参
-- 关键决策分支
-- 异常上下文（错误信息、栈、业务主键）
+典型表现为：
 
-### 3.5 多时区时间处理
+- 接收一个动作入口
+- 校验当前状态是否合法
+- 查询上下游数据
+- 按规则推进下一步
+- 同步相关对象状态
+- 触发通知、共享或资料处理
+- 返回执行结果
 
-通过 `TimeUtil` 使用用户时区相关时间能力，避免直接 `new Date()` 在跨时区下导致的偏差。
+从项目现状看，一批体量较大的类本质上都在承担这一职责。
 
-### 3.6 服务化复用
+### 3.4 外部系统集成
 
-可作为“公共库”被多个触发器、定时任务、页面调用，避免重复实现，降低维护成本。
+这是本项目自定义类非常鲜明的特征之一。
 
----
+自定义类可以作为平台与外部系统之间的集成层，负责：
 
-## 4. 自定义类的主要作用
+- 拼装请求参数
+- 调用接口
+- 接收返回结果
+- 处理鉴权、异常和容错
+- 将外部结果转换为平台内部可用的数据结构
 
-自定义类在 CloudCC 架构中的核心作用可以归纳为 4 点：
+相比把这些逻辑散落在页面、触发器或多个入口中，统一放到自定义类里更稳定、更易维护。
 
-1. **承载复杂后端逻辑**：把难以在页面层表达的业务规则下沉到服务端。  
-2. **形成可复用能力**：同一逻辑可被多个流程复用，减少复制粘贴。  
-3. **隔离变化与降低耦合**：页面、触发器、定时器只做编排，细节集中在类里。  
-4. **提升稳定性与治理性**：可统一异常处理、日志、权限与时区策略。  
+### 3.5 通知、提醒与协同动作
 
----
+自定义类不仅处理数据，也经常承担业务协同动作：
+
+- 发送邮件
+- 发起提醒
+- 推送待办
+- 创建事件或任务
+- 在关键节点通知相关角色
+
+这类能力通常和流程控制绑定出现，用于保证业务动作执行后，协同链路能被同步拉起。
+
+### 3.6 文件、附件与资料处理
+
+从全量阅读结果看，文件与资料相关处理占比也比较高。
+
+自定义类可以负责：
+
+- 附件读取
+- 文件上传或转发
+- 目录创建
+- 文件关系维护
+- 文件与业务记录的绑定
+- 资料同步与归档
+
+这说明自定义类不仅处理结构化数据，也承担了一部分资料流转和文档协同职责。
+
+### 3.7 权限、共享与角色控制
+
+一部分自定义类会在服务端完成权限相关动作，例如：
+
+- 基于角色、简档、组织关系控制动作
+- 自动写入共享关系
+- 按负责人或部门分配数据
+- 根据审批角色决定是否允许继续
+
+这类能力放在服务端实现，通常比放在前端更可靠。
+
+
+## 4. 自定义类的主要作用是什么
+
+综合来看，自定义类的主要作用可以概括为以下 5 点。
+
+### 4.1 承载复杂后端逻辑
+
+把复杂的、需要服务端执行的业务逻辑从页面层、按钮层、触发层中抽离出来，放到独立的服务端类中处理。
+
+### 4.2 形成可复用能力
+
+把相同能力沉淀为公共服务，让多个入口共享同一套实现，避免逻辑重复。
+
+### 4.3 作为流程编排中枢
+
+把“校验、查询、计算、写回、通知、集成”串成一条完整链路，让一个复杂动作在服务端被稳定执行。
+
+### 4.4 隔离系统边界
+
+把平台内部逻辑和外部系统调用隔离开，让页面、按钮、触发器只需要调用结果，而不需要关心接口细节。
+
+### 4.5 提升治理性
+
+通过统一的日志、异常、时间、返回结构和复用方式，让系统更容易排查、更容易维护、更容易扩展。
 
 ## 5. 为什么要用自定义类
 
-### 5.1 页面脚本/流程配置不够表达复杂度
+### 5.1 因为很多业务已经超出页面配置能力
+
+如果只是简单展示、字段联动、轻量前端交互，标准页面和脚本就足够。
 
-当逻辑包含“多对象关联 + 多分支判断 + 外部交互 + 事务结果回写”时，自定义类是更稳妥的实现方式。
+但当业务涉及：
 
-### 5.2 需要服务端可信执行
+- 多对象联动
+- 多步骤状态推进
+- 复杂计算
+- 外部系统调用
+- 文件和资料流转
+- 权限和共享处理
 
-对关键规则（如金额校验、状态流转、权限校验）要求高时，应放在服务端，避免仅依赖前端校验。
+页面层通常无法优雅承载，这时就需要自定义类。
 
-### 5.3 需要跨场景复用
+### 5.2 因为关键规则必须放在服务端
 
-同一能力在触发器、定时任务、按钮动作都要用时，抽成自定义类可显著降低维护难度。
+关键校验、关键状态、关键金额、关键动作如果只放在前端或入口层，可靠性和一致性都不足。
 
-### 5.4 需要可观测与可维护
+自定义类让这些规则在服务端可信执行，避免绕过和分叉实现。
 
-服务端类可统一日志与异常治理，问题定位效率高于散落在多处脚本中的实现。
+### 5.3 因为同一能力需要跨入口复用
 
----
+同一套业务处理常常会被：
+
+- 页面按钮调用
+- 触发器调用
+- 定时类调用
+- 组件调用
+- 其他类调用
+
+如果没有自定义类，逻辑会在多个地方重复，后续维护成本会迅速上升。
+
+### 5.4 因为需要统一集成出口
+
+外部系统对接如果没有统一出口，接口规则、异常处理和认证逻辑会散落在各处。
+
+自定义类正好可以充当统一的集成边界层。
+
+### 5.5 因为需要长期可维护
+
+随着业务增长，真正难的不是“先做出来”，而是“后面还能改、还能查、还能扩”。
+
+自定义类的价值就在于把复杂逻辑集中起来，为后续维护留下结构基础。
 
 ## 6. 自定义类能解决哪些问题
 
-## 6.1 数据一致性问题
+### 6.1 解决数据一致性问题
+
+- 一个动作影响多个对象，但平台默认能力难以统一处理
+- 主记录和明细记录之间容易口径不一致
+- 上下游对象状态需要同时同步
+
+自定义类可以把这些联动统一放到服务端，减少口径分裂。
+
+### 6.2 解决复杂规则难落地的问题
+
+- 条件过多
+- 公式过长
+- 分支过深
+- 决策依赖多个维度
+
+这些逻辑如果堆在页面、公式或触发器里，维护难度很快失控。自定义类更适合承载这类规则。
+
+### 6.3 解决流程动作分散的问题
+
+- 一个动作不仅要改数据，还要发通知、写共享、建目录、推接口
+- 业务动作涉及多个系统和多个后续步骤
+
+自定义类能够把这些步骤编排为一条服务端流程，保证执行次序和结果完整性。
+
+### 6.4 解决集成混乱的问题
+
+- 外部接口多
+- 返回结构不统一
+- 失败处理不一致
+- 同一种接口能力被多处重复实现
+
+通过自定义类统一集成出口，可以降低重复和耦合。
+
+### 6.5 解决通知协同不及时的问题
+
+- 业务动作完成后需要自动提醒相关人
+- 邮件、待办、事件、任务需要按规则自动触发
+
+自定义类可以把“业务处理”和“协同动作”组合在同一服务端链路里。
+
+### 6.6 解决文件资料处理分散的问题
+
+- 附件上传、同步、归档、目录维护容易分散到多个入口
+- 文件和业务记录之间的关系处理容易缺乏统一规范
+
+自定义类适合承担统一的资料处理逻辑。
 
-- 保存前/保存后数据规则难统一
-- 多对象联动导致状态不同步
-- 批量变更时局部失败难控制
+### 6.7 解决权限与共享难统一的问题
 
-## 6.2 复杂计算问题
+- 不同角色对动作权限不同
+- 数据共享规则需要自动生成
+- 负责人切换后共享关系要同步变化
 
-- 规则引擎化计算（计提、评分、归因）
-- 按角色、组织、区域进行差异化处理
+这类逻辑放在自定义类中更容易统一控制。
 
-## 6.3 集成问题
+## 7. 在什么情况下使用自定义类
 
-- 外部系统接口返回结构不稳定
-- 需要统一请求封装、失败重试、错误标准化
+满足以下任一情况时，优先考虑自定义类：
 
-## 6.4 性能与治理问题
+- 业务逻辑复杂，页面层无法稳定承载
+- 同一能力需要被多个入口复用
+- 涉及多对象联动或批量处理
+- 需要服务端强校验
+- 需要复杂规则计算
+- 需要外部系统集成
+- 需要文件、附件、目录等资料处理
+- 需要自动通知、提醒、待办协同
+- 需要统一权限、共享和角色控制
+- 需要接入 AI 或智能分析能力
 
-- 查询/更新逻辑重复且难优化
-- 缺少统一日志导致故障定位慢
+相反，以下场景通常不需要优先上自定义类：
 
-## 6.5 跨时区时间问题
+- 仅做简单展示
+- 仅做轻量前端交互
+- 仅做简单字段联动
+- 完全可以由标准配置完成的场景
 
-- 日期比较、提醒时间、截止时间在多时区下出现偏差
+## 8. 在什么业务场景下使用
 
----
+从全部非测试类的整体结构看，自定义类适合以下业务场景。
 
-## 7. 什么情况下使用自定义类（决策准则）
+### 8.1 复杂流程型场景
 
-满足以下任一条件，优先考虑自定义类：
+特点：
 
-- 业务规则超过页面层可维护阈值（分支多、链路长、对象多）
-- 同一逻辑需要被多处复用（触发器/定时器/页面/接口）
-- 需要对外系统集成与响应封装
-- 需要服务端强校验（合规、审计、财务、关键流程）
-- 需要统一异常、日志、时区、返回值协议
+- 一次动作会牵引多个后续步骤
+- 同时影响多类数据
+- 需要统一控制前后状态
 
-反过来，以下场景可优先考虑其他能力：
+适合使用自定义类，因为这类场景最依赖服务端编排能力。
 
-- 仅页面轻交互、字段联动：客户端脚本
-- 主要是数据写入前后钩子：触发器（复杂部分可调用类）
-- 明确按时间调度执行：定时类（复杂部分可调用类）
-- 仅新增数据结构：对象/字段配置
+### 8.2 规则密集型场景
 
----
+特点：
 
-## 8. 典型业务场景（推荐）
+- 有大量条件判断
+- 有汇总、分摊、计算、校验
+- 结果需要回写并留痕
 
-### 场景 1：销售流程控制器
+适合使用自定义类，因为这类场景需要稳定的规则承载层。
 
-- 需求：商机/订单在多个状态节点切换，要求统一校验、补全字段、写入日志
-- 做法：`Controller` 类统一处理状态迁移，触发器只负责调用
-- 价值：规则集中、便于迭代与审计
+### 8.3 集成协同型场景
 
-### 场景 2：通用工具类（数据与响应封装）
+特点：
 
-- 需求：多个流程需要统一返回结构、异常编码、JSON 处理
-- 做法：`Util` + `ReturnResult` + `BusinessException` 风格封装
-- 价值：接口契约稳定，调用方成本降低
+- 需要和外部系统对接
+- 需要把内部动作同步到外部
+- 需要将外部结果回填平台
 
-### 场景 3：外部系统对接
+适合使用自定义类，因为它天然适合做集成边界层。
 
-- 需求：调用第三方接口（如企业服务、外部查询、文件服务）
-- 做法：`Service` 类封装请求、签名、重试、错误翻译
-- 价值：外部波动被隔离，主流程更稳定
+### 8.4 通知驱动型场景
 
-### 场景 4：触发器逻辑下沉
+特点：
 
-- 需求：触发器中逻辑过重，难测试、难复用
-- 做法：触发器保留触发时机判断，核心逻辑迁入 `Handler`/`Service` 类
-- 价值：降低触发器复杂度，减少回归风险
+- 某个节点发生后必须提醒相关人
+- 需要自动创建待办、任务或消息
+- 通知内容依赖业务数据动态生成
 
-### 场景 5：AI/助手类业务能力
+适合使用自定义类，因为通知逻辑通常要和业务处理紧密耦合。
 
-- 需求：会话分析、摘要、建议、合同辅助等服务端处理
-- 做法：`Bot` 类封装上下文处理、外部调用与业务落库
-- 价值：能力沉淀为后端服务，可跨入口复用
+### 8.5 文件资料型场景
 
----
+特点：
 
-## 9. 与触发器/定时类/客户端脚本的分工
+- 需要读写附件
+- 需要目录维护
+- 需要文件同步、上传、归档或转发
 
-- **自定义类**：复杂逻辑与复用能力中心（推荐作为“业务服务层”）
-- **触发器**：数据生命周期节点的编排与触发
-- **定时类**：时间驱动任务调度与批处理入口
-- **客户端脚本**：页面交互与轻量校验
+适合使用自定义类，因为文件流转需要统一的服务端处理能力。
 
-推荐模式：**触发器/定时类/页面脚本做“薄入口”，自定义类做“厚服务”**。
+### 8.6 权限共享型场景
 
----
+特点：
 
-## 10. 设计与实施建议（落地实践）
+- 不同角色处理路径不同
+- 需要自动授权、共享或分配
+- 动作是否允许执行取决于服务端判断
 
-### 10.1 分层建议
+适合使用自定义类，因为权限控制必须具备服务端可信性。
 
-- `Controller`：面向入口，参数校验、编排流程
-- `Service`：承载核心业务逻辑
-- `Util`：通用工具、格式转换、公共方法
-- `Exception/Result`：统一错误码与返回结构
+### 8.7 智能辅助型场景
 
-### 10.2 开发建议
+特点：
 
-- 避免在入口类写过长方法，提炼私有方法或服务类
-- 关键路径加入 `DevLogger` 日志（入参、结果、异常）
-- 日期时间统一使用 `TimeUtil` 相关方法
-- 对外调用统一封装超时、重试与错误翻译
-- 对批量场景做幂等与容错设计
+- 需要调用模型或分析服务
+- 需要上传文件给智能服务处理
+- 需要把分析结果转成平台中的业务动作
 
-### 10.3 命名建议
+适合使用自定义类，因为它既能做调用入口，也能做结果落地层。
 
-- 入口控制：`xxxController`
-- 业务服务：`xxxService`
-- 公共能力：`xxxUtil`
-- 触发器下沉：`xxxHandler`
-- 结果与异常：`xxxResult` / `xxxException`
+## 9. 与其他能力的分工建议
 
----
+- 自定义类：负责复杂逻辑、服务复用、流程编排、集成处理
+- 触发器：负责触发时机
+- 定时类：负责时间驱动的自动执行
+- 页面和组件：负责界面展示与交互
+- 按钮：负责动作入口
 
-## 12. 一句话结论
+推荐模式是：
 
-当业务进入“多对象、复杂规则、跨系统、可复用、可治理”阶段时，CloudCC 自定义类是最关键的后端实现手段：它不仅能实现功能，更能提升系统长期可维护性与稳定性。
+- 页面、按钮、触发器、定时类做“薄入口”
+- 自定义类做“厚服务”
 
+这样可以把复杂度集中在服务端可治理的地方。