cloudcc-cli 2.3.8 → 2.4.0

package/src/triggers/docs/introduction.md

@@ -1,404 +1,675 @@
-# CloudCC 触发器使用总结
+# CloudCC 触发器 AI 概念规范
 
-> 基于生产环境 25 个触发器实例分析  
-> 文档版本：v1.0  
-> 更新时间：2026-03-24
+## 1. 文档目的
 
-## 一、什么是触发器
+本文用于给 AI 提供一份稳定、抽象、可复用的触发器概念说明。
 
-CloudCC 触发器是符合 Java 语法规范的服务端代码，在特定业务事件发生时自动执行，用于实现业务逻辑自动化处理。
+目标不是描述某一个具体业务触发器怎么写，而是回答以下问题：
 
-触发器本质：
+- 触发器是什么
+- 触发器能干什么
+- 触发器的主要作用是什么
+- 为什么要用触发器
+- 触发器能解决哪些问题
+- 什么时候应该使用触发器
+- 在什么业务场景下适合使用触发器
+- 什么时候不应该使用触发器
 
-- 一段 Java 代码，运行在 CloudCC 平台沙箱环境中
-- 使用 `CCService`、`CCObject` 等平台 API 类
-- 在数据变更的特定时刻（前/后）自动触发执行
+本文不包含业务代码，不绑定某一个对象字段设计，重点服务于 AI 后续做方案判断、实现选型和需求归类。
 
-## 二、触发器能干什么
+## 2. 触发器是什么
 
-### 2.1 核心能力
+触发器是 CloudCC 服务端的事件驱动逻辑入口。
 
-| 能力 | 说明 | 示例 |
-| --- | --- | --- |
-| 自动赋值 | 在记录保存前自动计算并填充字段 | 个人业绩/部门业绩自动赋值 |
-| 数据校验 | 阻止不符合业务规则的数据保存 | 预算金额校验、审批金额验证 |
-| 关联更新 | 修改一条记录时自动更新关联记录 | 回款明细汇总到收款计划 |
-| 自动生成 | 根据业务规则自动创建新记录 | 审批通过后自动生成回款记录 |
-| 权限控制 | 自动设置数据共享权限 | 按部门/人员自动共享 |
-| 状态同步 | 审批状态变更后同步更新相关字段 | 预算审批状态回写 |
-| 汇总计算 | 实时汇总明细数据到主记录 | 部门业绩字段汇总 |
+它的核心特征是：
 
-### 2.2 技术能力（基于 CCService API）
+- 绑定在某个对象的某个事件时机上
+- 由平台自动触发，不依赖用户手工执行
+- 运行在服务端，不属于前端页面逻辑
+- 更适合承接“必须发生”“不能绕过”“需要即时处理”的业务规则
 
-```java
-// 1. 新增记录
-CCObject opp = new CCObject("Opportunity");
-opp.put("name", "value");
-cs.insert(opp);
+从 AI 的角度理解，触发器不是一个“功能页面”，也不是一个“批处理任务”，而是一个“跟着数据变化自动执行的业务守门人和联动器”。
 
-// 2. 查询记录
-// 查询指定字段
-List<CCObject> opps = cs.cqueryByFields(
-    "Opportunity",
-    "khmc__c='" + record_new.get("id") + "'",
-    "id,name,createdate"
-);
+## 3. 触发器能干什么
 
-// 查询全部字段
-List<CCObject> all = cs.cquery("Opportunity", "khmc__c='" + record_new.get("id") + "'");
+触发器最常见的能力边界包括：
 
-// 复杂 SQL 查询
-List<CCObject> ccobjs = cs.cqlQuery(
-    "Opportunity",
-    "select sum(amount) as sumAmount from Opportunity where khmc = '0012001238ytwuiw'"
-);
+- 数据校验：拦截非法数据、阻止错误提交、限制非法删除
+- 自动赋值：补默认值、带出维度、自动回填关键字段
+- 关联同步：修改当前记录时同步更新关联对象
+- 自动生成：新建记录后自动派生子记录、中间记录、共享记录
+- 状态推进：根据阶段、审批结果、业务动作推进状态机
+- 审批控制：审批前校验，审批后回写、生成、通知、解锁
+- 汇总计算：实时汇总金额、比例、成本、数量、状态
+- 权限治理：自动共享、回收共享、同步负责人、调整协同关系
+- 删除补偿：删除后重算汇总、清理关联、消除待办
+- 通知与集成：发送待办、邮件、OA 通知，或向外部系统推送
 
-// 3. 修改记录
-cs.update(opp);
+一句话概括：
 
-// 4. 删除记录
-cs.delete(opp);
+触发器最适合做“和当前数据变更强相关、必须立即发生、必须由平台统一执行”的事情。
 
-// 5. 发送邮件通知
-SendEmail sendEmail = new SendEmail(userInfo);
-sendEmail.sendMailFromSystem(toAddress, ccAddress, bccAddress, subject, content, isText);
-```
+## 4. 触发器的主要作用
 
-## 三、触发器触发时机详解
+### 4.1 作为业务规则的统一入口
 
-### 3.1 beforeUpsert（创建或更新前）
+很多规则不能只依赖前端页面校验，因为：
 
-执行时机：记录保存之前，数据尚未写入数据库。  
-典型用途：
+- 页面可能不止一个
+- 导入、接口、批量操作也会写入数据
+- 人工操作容易绕过流程
 
-- 自动计算字段值
-- 数据格式校验
-- 阻止非法数据保存（抛出异常）
-- 自动填充默认值
+触发器的作用，就是把规则放到平台层统一执行，让所有入口遵守同一套规则。
 
-生产实例：
+### 4.2 作为跨对象联动的自动执行器
 
-| 触发器名称 | 对象 | 作用 |
-| --- | --- | --- |
-| 个人业绩/部门业绩赋值 | 对外付款 | 自动赋值业绩字段 |
-| 计算产研成本/净业绩 | 预算 | 自动计算成本、净业绩 |
-| 生成部门/个人业绩 | 净业绩拆分 | 自动创建业绩记录 |
-| 编辑更新部门业绩 | 净业绩拆分回款 | 更新前校验和计算 |
+业务里经常存在“一处变化，多处联动”的情况，例如：
 
-代码示例：
+- 商机变化后更新报价、合同、项目
+- 明细变化后回写主记录汇总
+- 审批通过后生成下游业务记录
 
-```java
-CCObject record = (CCObject) data.get("record");
-BigDecimal income = record.getBigDecimal("ysr");
-BigDecimal cost = record.getBigDecimal("cycb");
-BigDecimal net = income.subtract(cost);
-record.put("jyj", net);
-if (net.compareTo(BigDecimal.ZERO) < 0) {
-    throw new Exception("毛利不能为负数！");
-}
-```
+这类动作不适合依赖用户手工补做，触发器可以在事件发生当下自动处理。
 
-### 3.2 afterInsert（创建后）
+### 4.3 作为审批流程的补强层
 
-执行时机：记录已成功创建，ID 已生成。  
-典型用途：
+审批流适合做流程配置，但复杂判断、跨对象处理、审批前后差异动作，往往需要触发器承接。
 
-- 基于新记录 ID 创建关联记录
-- 发送创建通知
-- 初始化关联数据
+因此，触发器在很多项目里不是替代审批流，而是补足审批流。
 
-生产实例：
+### 4.4 作为数据质量和一致性的守门人
 
-| 触发器名称 | 对象 | 作用 |
-| --- | --- | --- |
-| 根据净业绩拆分生成净业绩拆分回款 | 回款明细 | 新建回款明细后自动生成回款记录 |
+触发器可以把很多“错误数据不要进来”“错误删除不能发生”“状态不能乱跳”“金额不能失真”这类要求，变成系统级约束。
 
-代码示例：
+## 5. 为什么要用触发器
 
-```java
-CCObject newRecord = (CCObject) data.get("record");
-String recordId = newRecord.getString("id");
+从业务价值看，触发器的意义主要有六点：
 
-CCObject hkRecord = new CCObject("Huikuan");
-hkRecord.put("mingxi__c", recordId);
-hkRecord.put("je", newRecord.get("je"));
-cs.insert(hkRecord);
-```
+- 实时：记录变化时立即执行，不需要等待定时任务
+- 统一：不管数据从页面、导入还是接口进入，都走同一规则
+- 强约束：关键校验可以做到不可绕过
+- 自动化：减少人工补录、手工回填、人工同步
+- 一致性：多对象、多字段、多状态之间能保持同步
+- 可扩展：复杂流程、复杂校验、复杂派生逻辑都可以承载
 
-### 3.3 afterUpsert（创建或更新后）
+如果一个规则满足以下特征，通常就值得优先考虑触发器：
 
-执行时机：记录已成功保存（新增或修改）。  
-典型用途：
-
-- 汇总数据到父记录
-- 触发下游业务流程
-- 更新关联记录状态
-
-生产实例：
-
-| 触发器名称 | 对象 | 作用 |
-| --- | --- | --- |
-| 金额汇总到收款计划 | 回款明细 | 汇总回款金额到收款计划 |
-| 更新部门业绩字段 | 部门业绩 | 汇总各维度业绩数据 |
-| 更新回款明细 | 回款明细 | 重建净业绩拆分回款记录 |
-
-代码示例：
-
-```java
-CCObject detail = (CCObject) data.get("record");
-String planId = detail.getString("skjh__c");
-List<CCObject> plans = cs.cqueryByFields("ShoukuanJihua", "id='" + planId + "'", "id,shyjje,yishouje");
-if (!plans.isEmpty()) {
-    CCObject plan = plans.get(0);
-    BigDecimal current = plan.getBigDecimal("yishouje");
-    BigDecimal detailAmount = detail.getBigDecimal("je");
-    plan.put("yishouje", current.add(detailAmount));
-    cs.update(plan);
-}
-```
-
-### 3.4 afterDelete（删除后）
-
-执行时机：记录已成功删除。  
-典型用途：
-
-- 清理关联数据
-- 反向汇总更新
-
-生产实例：
-
-| 触发器名称 | 对象 | 作用 |
-| --- | --- | --- |
-| 回款明细删除 | 回款明细 | 删除后重新计算回款金额 |
-
-### 3.5 approval（审批时）
-
-执行时机：记录提交审批或审批通过时。  
-典型用途：
-
-- 审批前校验业务规则
-- 审批通过后执行业务操作
-
-生产实例：
-
-| 触发器名称 | 对象 | 作用 |
-| --- | --- | --- |
-| 更新拆分审批状态 | 预算 | 审批通过后回写状态 |
-| 订单审批判断 | 订单 | 审批时校验收款计划 |
-| 审批通过计算剩余欠款 | 费用报销 | 审批后计算欠款 |
-
-## 四、为什么要用触发器
-
-### 4.1 解决的核心问题
-
-| 问题 | 传统方案 | 触发器方案 |
-| --- | --- | --- |
-| 数据一致性 | 依赖用户手动操作，容易遗漏 | 自动执行，保证数据准确 |
-| 业务规则执行 | 前端校验可绕过 | 平台层统一执行，无法绕过 |
-| 跨对象联动 | 需要多次手动操作 | 自动关联更新 |
-| 审批流程复杂逻辑 | 审批流配置无法实现 | Java 代码实现任意逻辑 |
-| 实时性要求 | 定时任务有延迟 | 实时触发，立即执行 |
-
-### 4.2 对比其他方案
-
-| 方案 | 优点 | 缺点 | 适用场景 |
-| --- | --- | --- | --- |
-| 触发器 | 实时、自动、无法绕过 | 需要 Java 开发能力 | 核心业务逻辑 |
-| 审批流 | 配置简单、可视化 | 逻辑能力有限 | 简单审批流程 |
-| 工作流 | 可视化编排 | 复杂逻辑实现困难 | 跨系统流程编排 |
-| 定时任务 | 适合批量处理 | 有延迟 | 数据同步、报表生成 |
-
-## 五、典型业务场景
-
-### 5.1 财务业绩管理（核心场景）
-
-触发器链路：
-
-```text
-订单 (Order)
-│ approval 触发器：审批判断
-▼
-预算 (Budget)
-│ beforeUpsert: 计算产研成本/净业绩
-│ afterUpsert: 自动拆分/生成回款
-▼
-净业绩拆分 (jyjcf)
-│ beforeUpsert: 生成部门/个人业绩
-│ afterUpsert: 校验金额累计是否超预算
-▼
-部门业绩 (bmyj)
-│ afterUpsert: 更新部门业绩字段
-│ afterUpdate: 汇总部门资金池
-回款明细 (cloudccproceeddetail)
-│ afterInsert: 生成净业绩拆分回款
-│ afterUpsert: 金额汇总到收款计划
-│ afterUpsert: 更新回款明细
-│ afterDelete: 回款明细删除
-```
-
-关键触发器说明：
-
-1. 计算产研成本/净业绩（预算 - beforeUpsert）
-   - 自动计算预算收入、产研成本、净业绩
-   - 审批控制：毛利 < 0 阻止提交
-2. 生成部门/个人业绩（净业绩拆分 - beforeUpsert）
-   - 根据拆分规则自动创建业绩记录
-   - 按 owner 部门与年份关联业绩主数据
-3. 金额汇总到收款计划（回款明细 - afterUpsert）
-   - 汇总同一回款单下的明细金额
-   - 回填至收款计划（实际收款、余额、是否完成）
-4. 更新部门业绩字段（部门业绩 - afterUpsert）
-   - 按“类别 + 业绩计算方式”多维度汇总
-   - 计算目标完成率
-
-### 5.2 费用报销管理
-
-```text
-费用报销提交
-│
-▼
-[approval 触发器] 验证审批时校验预算
-│ 校验：报销金额 <= 预算余额
-▼
-审批通过
-│
-▼
-[approval 触发器] 审批通过计算剩余欠款
-│ 计算：剩余欠款 = 借款 - 报销
-```
-
-### 5.3 借款还款管理
-
-| 触发器 | 对象 | 时机 | 作用 |
-| --- | --- | --- | --- |
-| 借款单触发器 | 借款单 | beforeUpsert | 借款前校验、自动计算 |
-| 还款记录审批通过更新借款单 | 还款记录 | approval | 审批后更新借款单 |
-
-## 六、触发器开发最佳实践
-
-### 6.1 代码规范
-
-```java
-try {
-    CCObject record = (CCObject) data.get("record");
-    cs.update(record);
-} catch (Exception e) {
-    System.out.println("触发器执行失败：" + e.getMessage());
-    throw new Exception("业务校验失败：" + e.getMessage());
-}
-```
-
-### 6.2 性能优化
-
-```java
-// 字段过滤，只查询需要的字段
-List<CCObject> records = cs.cqueryByFields(
-    "Object__c",
-    "status__c='active'",
-    "id,name,amount__c"
-);
-
-// 批量操作使用 updateLt（避免递归）
-cs.updateLt(records);
-```
-
-### 6.3 避免递归触发
-
-```java
-// 方法 1：使用 updateLt
-cs.updateLt(records);
-
-// 方法 2：添加标志位
-if ("true".equals(System.getProperty("trigger.running"))) {
-    return;
-}
-System.setProperty("trigger.running", "true");
-cs.update(record);
-System.setProperty("trigger.running", "false");
-```
-
-## 七、触发器调试与监控
-
-### 7.1 日志记录
-
-```java
-System.out.println("=== 触发器开始执行 ===");
-System.out.println("对象：" + record.getSObjectName());
-System.out.println("操作：" + data.get("action"));
-System.out.println("记录 ID: " + record.get("id"));
-```
-
-### 7.2 常见问题排查
-
-| 问题 | 可能原因 | 解决方案 |
-| --- | --- | --- |
-| 触发器不执行 | 未激活、触发时机不对 | 检查状态和配置 |
-| 递归触发 | 更新操作再次触发触发器 | 使用 `updateLt` |
-| 性能问题 | 查询数据量过大 | 添加查询条件、字段过滤 |
-| 数据不一致 | 触发器执行失败 | 添加异常处理 |
-
-## 八、总结
-
-### 8.1 触发器的价值
-
-1. 自动化：减少人工操作，降低出错率
-2. 一致性：保证数据准确性和业务规则执行
-3. 实时性：业务变更立即响应
-4. 灵活性：Java 代码可实现复杂业务逻辑
-
-### 8.2 何时使用触发器
-
-适合使用：
-
-- 需要实时数据联动
-- 核心业务规则校验
-- 跨对象数据同步
-- 审批流程中的复杂逻辑
-- 自动创建/更新关联记录
-
-不适合使用：
-
-- 简单字段默认值
-- 大批量数据处理
-- 跨系统集成
-- 用户界面交互
-
-### 8.3 触发器开发 Checklist
-
-- 明确触发时机（before/after/approval）
-- 评估递归触发风险
-- 添加异常处理
-- 记录关键日志
-- 测试边界情况
-- 做大数据量场景性能测试
-
-## 附录：25 个生产触发器清单
-
-| # | 名称 | 对象 | 时机 | 状态 |
-| --- | --- | --- | --- | --- |
-| 1 | 个人业绩/部门业绩赋值 | 对外付款 | beforeUpsert | ✅ |
-| 2 | 个人业绩/部门业绩赋值 | 费用报销 | beforeUpsert | ❌ |
-| 3 | 本部业绩统计 | 本部业绩统计 | beforeUpsert | ✅ |
-| 4 | 更新拆分审批状态 | 预算 | approval | ✅ |
-| 5 | 订单审批判断 | 订单 | approval | ✅ |
-| 6 | 根据净业绩拆分生成净业绩拆分回款 | 回款明细 | afterInsert | ✅ |
-| 7 | 金额汇总到收款计划 | 回款明细 | afterUpsert | ✅ |
-| 8 | 回款明细删除 | 回款明细 | afterDelete | ❌ |
-| 9 | 计算产研成本/净业绩 | 预算 | beforeUpsert | ✅ |
-| 10 | 保证金回款记录 | 概算 | afterUpdate | ✅ |
-| 11 | 校验金额累计是否超预算 | 净业绩拆分 | afterUpsert | ✅ |
-| 12 | 更新部门业绩字段 | 部门业绩 | afterUpsert | ✅ |
-| 13 | 汇总部门资金池 | 部门业绩 | afterUpdate | ✅ |
-| 14 | 编辑更新部门业绩 | 净业绩拆分回款 | beforeUpsert | ✅ |
-| 15 | 生成部门/个人业绩 | 净业绩拆分 | beforeUpsert | ✅ |
-| 16 | 更新回款明细 | 回款明细 | afterUpsert | ✅ |
-| 17 | （新）新建自动拆分/审批通过自动生成回款 | 预算 | afterUpsert | ✅ |
-| 18 | 提交审批验证金额 | 对外付款 | approval | ❌ |
-| 19 | 还款记录审批通过更新借款单 | 还款记录 | approval | ✅ |
-| 20 | 审批通过计算剩余欠款 | 费用报销 | approval | ✅ |
-| 21 | 借款单触发器 | 借款单 | beforeUpsert | ✅ |
-| 22 | 创建编辑项目任务时判断 | 项目任务 | beforeUpsert | ✅ |
-| 23 | 任务派工工时限制 | 项目任务 | afterUpsert | ✅ |
-| 24 | 测试 AI 代码生成 | 客户 | beforeInsert | ❌ |
-| 25 | 验证审批时校验预算 | 费用报销 | approval | ❌ |
+- 需要即时生效
+- 跟某条记录的新增、修改、删除、审批直接相关
+- 不执行就会造成数据错误或流程错误
+- 不能依赖人工补操作
 
+## 6. 触发器能解决哪些问题
+
+### 6.1 数据准入问题
+
+典型问题：
+
+- 必填项不完整
+- 金额、比例、数量不合法
+- 当前状态下不允许编辑、提交或删除
+- 数据重复、冲突或越界
+
+触发器价值：
+
+- 在保存前拦截问题数据
+- 防止脏数据进入系统
+- 保证关键规则不依赖人工记忆
+
+### 6.2 数据联动问题
+
+典型问题：
+
+- 一个对象更新后，关联对象没有同步
+- 主子表口径不一致
+- 上下游业务单据状态脱节
+
+触发器价值：
+
+- 把联动逻辑自动化
+- 降低人工同步遗漏
+- 保持对象间状态一致
+
+### 6.3 审批补强问题
+
+典型问题：
+
+- 审批前需要复杂校验
+- 审批通过后要生成下游数据
+- 审批撤回后要回滚状态或清待办
+
+触发器价值：
+
+- 承接审批流无法直接表达的规则
+- 让审批前后动作自动执行
+- 让流程控制更严密
+
+### 6.4 实时计算问题
+
+典型问题：
+
+- 汇总金额、成本、比例、回款、认款需要即时准确
+- 主记录字段依赖明细变化实时重算
+
+触发器价值：
+
+- 在数据变化当下重算
+- 避免报表、页面、审批依据口径失真
+
+### 6.5 权限与协同问题
+
+典型问题：
+
+- 负责人变化后共享关系未更新
+- 团队成员、部门共享、审批参与人没有同步
+
+触发器价值：
+
+- 自动修正共享与权限关系
+- 保证协同对象始终正确
+
+### 6.6 通知与集成问题
+
+典型问题：
+
+- 某个业务事件发生后需要推送 OA、邮件、外部系统
+- 人员提醒、待办生成、外部回传不能漏
+
+触发器价值：
+
+- 把事件和通知、集成绑定起来
+- 保证关键动作发生时立即通知或同步
+
+## 7. 什么时候应该使用触发器
+
+AI 在判断方案时，可以先问自己四个问题：
+
+- 这是由某条记录的新增、修改、删除、审批直接触发的吗
+- 这件事必须立刻发生吗
+- 这件事必须由平台统一执行、不能依赖人工吗
+- 这件事如果不在当前时点做，会导致数据错误或流程错误吗
+
+如果以上问题大部分回答是“是”，通常就适合触发器。
+
+### 7.1 适合使用触发器的情况
+
+- 记录保存前必须校验
+- 记录保存时必须自动赋值
+- 记录保存后必须立即联动其他对象
+- 删除后必须立刻做反向更新或清理
+- 提交审批或审批通过时必须执行业务动作
+- 关键业务状态必须平台层统一约束
+- 关键共享关系和负责人关系必须自动维护
+
+### 7.2 不适合优先使用触发器的情况
+
+- 按天、按周、按月执行的任务
+- 一次要扫描大量历史数据的批处理
+- 失败后需要复杂重试和补偿的长链路集成
+- 强依赖前端交互和页面反馈的场景
+- 只是简单展示或轻量交互
+- 只是一个手动按钮动作，不需要事件自动触发
+
+## 8. 触发器与其他实现方式的边界
+
+AI 在做方案选型时，必须区分触发器、自定义类、定时器、页面脚本的边界。
+
+### 8.1 触发器
+
+适合：
+
+- 单条记录事件驱动
+- 需要即时执行
+- 需要强规则约束
+
+关键词：
+
+- 自动触发
+- 紧贴对象生命周期
+- 平台统一执行
+
+### 8.2 自定义类
+
+适合：
+
+- 可复用的服务逻辑
+- 多入口共用能力
+- 复杂计算、复杂集成、复杂流程编排
+
+关键词：
+
+- 服务能力
+- 复用
+- 被触发器、按钮、页面、定时器调用
+
+### 8.3 定时器类
+
+适合：
+
+- 周期任务
+- 批量扫描
+- 后台修复
+- 延迟处理
+
+关键词：
+
+- 按时间触发
+- 批量
+- 巡检和补偿
+
+### 8.4 页面脚本或页面组件
+
+适合：
+
+- 前端交互
+- 页面展示
+- 用户即时输入反馈
+
+关键词：
+
+- 页面体验
+- 界面交互
+- 非服务端强规则
+
+### 8.5 AI 的默认判断原则
+
+可以简单记成一句话：
+
+- 实时事件规则，用触发器
+- 通用能力沉到自定义类
+- 周期批处理用定时器
+- 页面交互留给前端
+
+## 9. 按触发时机逐个分析
+
+以下内容用于帮助 AI 判断“同样是触发器，应该挂在哪个时机”。
+
+### 9.1 `beforeInsert`
+
+主要作用：
+
+- 新建前校验
+- 新建前默认值填充
+- 新建前防重和准入控制
+
+为什么要用：
+
+- 因为记录还没入库，最适合做拦截和初始值处理
+
+解决的问题：
+
+- 不合法记录进入系统
+- 新建记录缺少关键字段
+
+适用场景：
+
+- 新建商机、报价、合同、客户时的必填校验
+- 编号规则、初始状态、默认负责人赋值
+
+### 9.2 `beforeUpdate`
+
+主要作用：
+
+- 编辑前限制
+- 状态切换限制
+- 变更前业务保护
+
+为什么要用：
+
+- 很多业务错误不是发生在创建时，而是发生在后续修改时
+
+解决的问题：
+
+- 已审批数据被误改
+- 不允许的状态回退或跳转
+- 已锁定记录被继续编辑
+
+适用场景：
+
+- 合同、商机、报价、项目状态变更控制
+- 金额、阶段、负责人变更限制
+
+### 9.3 `beforeUpsert`
+
+主要作用：
+
+- 同时覆盖新建与更新的统一校验
+- 同时覆盖新建与更新的统一赋值
+
+为什么要用：
+
+- 当规则对“新建”和“更新”都成立时，用一个入口更稳定
+
+解决的问题：
+
+- 同一规则在创建和修改场景下实现不一致
+
+适用场景：
+
+- 统一口径的金额、比例、分类字段计算
+- 创建和更新都要执行的格式和业务校验
+
+### 9.4 `afterInsert`
+
+主要作用：
+
+- 根据新记录生成关联记录
+- 创建后发送通知或初始化下游数据
+
+为什么要用：
+
+- 只有创建成功后，记录 ID 和上下文才完整
+
+解决的问题：
+
+- 派生数据漏建
+- 新建后没有初始化关联关系
+
+适用场景：
+
+- 新建后自动生成工作包、分期、子表、共享记录、待办
+
+### 9.5 `afterUpdate`
+
+主要作用：
+
+- 对编辑后的结果做定向联动
+- 在特定字段变化后触发后续动作
+
+为什么要用：
+
+- 有些动作只适合在修改后做，不适合在新建时做
+
+解决的问题：
+
+- 修改后的状态、金额、负责人未同步到下游
+
+适用场景：
+
+- 状态推进后的通知、同步、创建或解锁动作
+
+### 9.6 `afterUpsert`
+
+主要作用：
+
+- 在新增或更新成功后做统一联动
+- 做汇总、回写、同步、派生
+
+为什么要用：
+
+- 它适合承接“只要保存成功就要处理”的通用后置动作
+
+解决的问题：
+
+- 主子记录口径不同步
+- 上下游对象字段不同步
+
+适用场景：
+
+- 汇总金额、同步状态、回写父记录、刷新关联对象
+
+### 9.7 `beforeDelete`
+
+主要作用：
+
+- 删除前拦截
+- 删除前检查依赖
+
+为什么要用：
+
+- 一旦删除完成，恢复成本就高
+
+解决的问题：
+
+- 误删关键记录
+- 删除造成数据断链
+
+适用场景：
+
+- 已提交、已审批、已关联、已汇总数据不允许删除
+
+### 9.8 `afterDelete`
+
+主要作用：
+
+- 删除后清理和补偿
+- 删除后重算汇总
+
+为什么要用：
+
+- 删除已经发生，此时适合做回收和反向修复
+
+解决的问题：
+
+- 删除后主记录口径未重算
+- 删除后待办、共享、派生数据残留
+
+适用场景：
+
+- 删除子记录后重算父记录金额或比例
+- 删除业务记录后取消待办、清理关联
+
+### 9.9 `approval`
+
+主要作用：
+
+- 审批提交前校验
+- 审批通过后推进业务
+- 审批撤回或拒绝后回滚状态
+
+为什么要用：
+
+- 审批节点往往是业务控制最严格的节点
+
+解决的问题：
+
+- 提交审批前条件不满足
+- 审批通过后下游业务没有自动启动
+- 审批撤回后状态没有恢复
+
+适用场景：
+
+- 审批前预算、金额、附件、状态校验
+- 审批通过后生成记录、推送系统、发送待办、解锁或锁定对象
+
+## 10. 当前项目里最常见的十类业务场景
+
+### 10.1 数据校验与限制类
+
+主要作用：
+
+- 阻止非法新增、非法编辑、非法删除、非法提交
+
+解决问题：
+
+- 数据错误进入系统
+- 关键业务口径被破坏
+
+适用场景：
+
+- 金额、比例、状态、字段必填、重复判断、删除限制
+
+### 10.2 自动生成与初始化类
+
+主要作用：
+
+- 自动生成关联记录、默认结构、初始化业务数据
+
+解决问题：
+
+- 派生数据依赖人工创建
+- 新建后缺少后续业务支撑数据
+
+适用场景：
+
+- 生成项目、生成分期、生成工作包、生成共享记录、初始化统计数据
+
+### 10.3 更新与同步类
+
+主要作用：
+
+- 跨对象更新、回写、同步、补齐字段
+
+解决问题：
+
+- 一个对象变化后下游对象未更新
+- 业务链条断裂
+
+适用场景：
+
+- 商机到报价、报价到合同、合同到项目、明细到主表的同步
+
+### 10.4 审批与流程推进类
+
+主要作用：
+
+- 审批节点前后控制和流程驱动
+
+解决问题：
+
+- 审批前条件校验不足
+- 审批通过后流程没有自动衔接
+
+适用场景：
+
+- 提交审批校验、审批通过回写、撤回消办、审批后生成下游业务数据
+
+### 10.5 共享与权限治理类
+
+主要作用：
+
+- 自动维护共享范围、协同关系、负责人体系
+
+解决问题：
+
+- 人员变化后共享关系错乱
+- 团队协同对象不准确
+
+适用场景：
+
+- 共享规则、负责人变化、审批参与人分配、项目成员同步
+
+### 10.6 通知与集成类
+
+主要作用：
+
+- 业务事件发生时推送待办、邮件、OA 或外部系统
+
+解决问题：
+
+- 关键动作无人感知
+- 外部系统数据不同步
+
+适用场景：
+
+- 审批待办、邮件提醒、OA 推送、SAP/BI/第三方系统同步
+
+### 10.7 汇总与计算类
+
+主要作用：
+
+- 实时计算金额、比例、成本、回款、认款、汇总字段
+
+解决问题：
+
+- 主记录汇总失真
+- 审批依据和财务口径不一致
+
+适用场景：
+
+- 报价、合同额、预算、回款、成本、项目作业比例
+
+### 10.8 删除补偿与清理类
+
+主要作用：
+
+- 删除后重算、清理、取消、恢复
+
+解决问题：
+
+- 删除后出现残留数据或统计错误
+
+适用场景：
+
+- 删除子记录后重算父记录
+- 删除后取消待办、清理共享、清空关联
+
+### 10.9 编号与编码治理类
+
+主要作用：
+
+- 统一管理编号、编码、命名规则
+
+解决问题：
+
+- 手工编号重复
+- 编码规则不统一
+
+适用场景：
+
+- 合同编号、物料编码、产品线编码、业务单据编码
+
+### 10.10 导入迁移与修复类
+
+主要作用：
+
+- 为导入、迁移、历史修复提供自动化处理
+
+解决问题：
+
+- 导入数据结构不完整
+- 历史数据缺少标准化处理
+
+适用场景：
+
+- 导入后回填、迁移中间表修复、初始化历史口径
+
+## 11. AI 在使用触发器概念时应遵守的判断顺序
+
+AI 在看到一个需求时，建议按以下顺序判断：
+
+1. 先判断是不是“记录事件驱动”
+2. 再判断是不是“必须立即执行”
+3. 再判断是不是“必须平台层强约束”
+4. 再判断是不是“和审批节点直接相关”
+5. 再判断是“保存前控制”还是“保存后联动”
+6. 再判断是否需要把复杂逻辑下沉到自定义类
+
+如果一个需求只是“事件入口很薄，真正逻辑很重”，AI 应优先采用：
+
+- 触发器做入口
+- 自定义类做核心能力
+
+不要把所有复杂逻辑都直接堆在触发器里。
+
+## 12. AI 不应把触发器当成什么
+
+AI 不应把触发器当成以下东西：
+
+- 周期批处理器
+- 大规模数据修复器
+- 前端交互逻辑容器
+- 任意可复用服务类的替代品
+- 所有问题的默认答案
+
+触发器的价值，在于“紧贴对象生命周期做即时规则和即时联动”，而不是替代一切后端能力。
+
+## 13. 最终结论
+
+从概念上看，CloudCC 触发器最适合承接四类核心职责：
+
+- 守门：保存前、删除前、审批前的规则校验和拦截
+- 联动：保存后、审批后的同步、回写、生成、通知
+- 治理：共享、权限、状态、编号、流程秩序的维护
+- 计算：金额、比例、成本、回款、汇总口径的实时更新
+
+因此，AI 在未来遇到以下描述时，应优先联想到触发器：
+
+- 保存时必须校验
+- 修改后必须同步
+- 审批后必须生成
+- 删除后必须重算
+- 负责人变化后必须共享
+- 关键状态不能被绕过
+
+如果需求不是“即时事件驱动”，或者需要“周期批处理、复杂重试、长链路集成、前端交互”，就不应优先落到触发器。