cloudcc-cli 2.3.8 → 2.4.0

package/src/triggers/docs/devguide.md

@@ -1,20 +1,123 @@
-# CloudCC 触发器使用总结
+# CloudCC 触发器 AI 开发规范
 
-> 基于 25 个生产环境触发器实例分析。
-> 文档版本：v1.0
-> 更新时间：2026-03-24
+## 1. 文档目的
 
----
+本文用于指导 AI 在当前 CloudCC 项目中设计、编写、修改和发布触发器。
 
-## CLI 与本地文件（必读）
+目标不是让 AI 只写出“能跑”的触发器，而是让 AI 写出的实现同时满足：
 
-本仓库中的触发器源码通过 **cloudcc-cli** 与平台同步，本地目录为 **`triggers/<对象 API 名小写>/<触发器名>/`**（内含 `*.java`、`config.json`），源码中的 `// @SOURCE_CONTENT_START` … `// @SOURCE_CONTENT_END` 与发布、拉取逻辑一致。**必须通过下列命令** 完成新建、发布、拉取与删除；不要手工拼目录、不要整包复制其他项目的触发器、不要私自篡改 `config.json` 中的 `id`、`apiname` 等字段。
+- 选型正确
+- 触发时机正确
+- SDK 使用正确
+- 结构清晰
+- 可维护
+- 可发布
+- 可排错
+- 尽量避免递归、脏数据和性能问题
 
-**允许的做法**：在 CLI 已生成的主类中，仅在上述 SOURCE 标记之间编写业务逻辑；与云端列表、详情、拉取、删除、发布相关的操作一律走命令。
+本文面向 AI，因此重点回答以下问题：
 
-执行命令前请确认：已完成 `cloudcc doc project devguide` 中的环境初始化，项目根目录配置可用且包含 `accessToken`。创建触发器前通常需要先通过 `cloudcc get object ...` 等拿到目标对象的 `schemetableName`、`targetObjectId`（见下文物「创建」示例）。
+- 什么场景应该优先使用触发器
+- 什么场景不应该使用触发器
+- 触发器应该怎样组织代码
+- 触发器中应该如何使用 CloudCC 后端 SDK
+- 触发器开发时有哪些硬规则和常见坑
 
-### 命令总览（以代码实现为准）
+## 2. 编写依据
+
+- 官方 SDK 文档负责定义 `CCObject`、`UserInfo`、`CCService`、`SendEmail`、`DevLogger`、`TimeUtil`、自定义设置、共享对象相关能力
+- `triggers devguide` 负责定义 CLI、目录结构、创建发布拉取删除方式和触发器模块约束
+- 当前项目触发器样例负责补充“本项目常见写法”和“本项目容易踩坑的地方”
+
+## 3. AI 的总体职责
+
+AI 在编写触发器时，应把自己视为“对象生命周期规则设计者”，而不是“在构造函数里临时塞一段业务代码的人”。
+
+AI 需要同时做到：
+
+- 判断需求是否真的适合触发器
+- 选择合适的触发时机
+- 控制触发器体量，不把复杂逻辑全部堆在入口里
+- 正确调用 SDK 完成查、增、改、删、通知、日志、时间处理
+- 主动规避递归触发、重复生成、全表扫描、时区错误、共享误删等风险
+
+## 4. 先判断：是不是应该写成触发器
+
+AI 在动手前，必须先判断需求是否属于“对象事件驱动”。
+
+### 4.1 适合触发器的情况
+
+- 某条记录新增时必须立即执行
+- 某条记录修改时必须立即校验或联动
+- 某条记录删除前必须阻止或删除后必须补偿
+- 提交审批、审批通过、审批撤回时必须执行规则
+- 当前规则必须平台层统一执行，不能依赖前端页面
+- 当前动作如果不在这一刻做，会造成数据错误、状态错误或流程错误
+
+### 4.2 不适合优先使用触发器的情况
+
+- 需要按天、按周、按月跑批
+- 需要扫描大量历史数据做修复
+- 需要复杂重试或长链路集成补偿
+- 逻辑更像一个可复用服务，不只被一个触发器调用
+- 更偏页面交互、输入反馈、展示控制
+- 只是一个手动动作，不需要记录事件自动触发
+
+### 4.3 AI 的默认选型规则
+
+- 单条记录实时事件，用触发器
+- 可复用核心逻辑，下沉到自定义类
+- 周期批处理，用定时器
+- 页面交互，用页面脚本或组件
+
+## 5. 当前项目中触发器的真实约束
+
+这是 AI 最容易忽视、但必须先接受的现实约束。
+
+### 5.1 触发器不是普通 Java 类容器
+
+根据当前项目的实际文件结构，触发器目录位于：
+
+- `triggers/<对象 API 名小写>/<触发器名>/`
+
+主类通常形如：
+
+- `package triggers.<对象小写>.<触发器名>;`
+- `public class Xxx extends CCTrigger`
+- SOURCE 区域位于构造函数中
+
+这意味着：
+
+- 触发器天然是“薄入口”
+- 不适合承载超长业务逻辑
+- 更不适合在触发器里构建一整套复杂服务
+
+### 5.2 复杂逻辑必须主动下沉
+
+当逻辑具备以下任一特征时，AI 不应继续堆在触发器里：
+
+- 超过一个对象联动
+- 超过一个分支状态机
+- 需要复用
+- 需要外部集成
+- 需要复杂查询和映射
+- 需要多次通知或多步编排
+
+推荐做法：
+
+- 触发器只做入口判断和参数收集
+- 核心逻辑下沉到自定义类
+- 触发器通过 `new XxxService(userInfo)` 之类方式调用服务层
+
+这是当前项目中最重要的 AI 设计原则之一。
+
+## 6. AI 必须遵守的硬规则
+
+### 6.1 只能通过 cloudcc-cli 管理触发器目录
+
+不得手工创建或复制 `triggers/...` 目录，不得私自构造 `config.json`。
+
+必须使用：
 
 ```bash
 cloudcc create triggers <encodedCreateJson>
@@ -25,418 +128,892 @@ cloudcc detail triggers <namePath>
 cloudcc detail triggers "" <id>
 cloudcc pullList triggers <id> <projectPath>
 cloudcc delete triggers <namePathOrId> [projectPath]
-cloudcc doc triggers <introduction|devguide>
 ```
 
-参数约定：
-
-- `encodedCreateJson`：`encodeURI(JSON.stringify({ ... }))`，其中至少包含：
-  - `schemetableName`：目标对象 API 名（如 `Account`）
-  - `targetObjectId`：目标对象 ID
-  - `triggerTime`：触发时机（如 `beforeInsert`、`beforeUpsert` 等，以平台为准）
-  - `name`：触发器类名（目录名）
-  - `apiname`：触发器 API 名（全局唯一）
-- `namePath`：**对象目录/触发器名**，与本地路径一致，例如 `account/MyTrigger`（`schemetableName` 小写 + `/` + `name`）。`publish`、`pull`、`delete`（按路径删除时）均使用该形式。
-- `listQueryJson`：列表查询 JSON，经 `encodeURI(JSON.stringify(...))` 编码后传入（**必填**，实现上无默认空查询）。
-- `projectPath`：项目根路径，可选。
-- `id`：线上触发器 ID。`detail` 仅查服务器：`cloudcc detail triggers "" <id>`。
-- `namePathOrId`：可为 `对象小写/触发器名` 形式的路径；若本地 `config.json` 含 `id`，删除时优先用该 ID。
-
-### 命令作用摘要
-
-| 命令 | 作用 |
-|------|------|
-| `create` | 在 `triggers/<对象小写>/<name>/` 生成继承 `CCTrigger` 的 Java 与 `config.json` |
-| `publish` | 提交 SOURCE 区域等到服务器；首次成功后可写回 `config.json` 的 `id`、`apiname` 等 |
-| `pull` | 按本地已发布 `id` 拉取远端源码，覆盖 SOURCE 区域 |
-| `get` | 按条件查询线上触发器列表（JSON 输出） |
-| `detail` | 按 `namePath` 优先读本地；或仅按 `id` 读服务器 |
-| `pullList` | 按触发器 `id` 还原到指定项目的 `triggers/...` |
-| `delete` | 删除服务器上的触发器 |
-| `doc` | 输出模块文档；`devguide` 含附录后端 Java SDK 速查 |
-
-### 创建示例（需先准备对象信息）
-
-先构造对象（字段与平台约定一致），再整段做 `encodeURI(JSON.stringify(...))`，作为 `cloudcc create triggers` 的**唯一参数**：
-
-```json
-{
-  "schemetableName": "Account",
-  "targetObjectId": "<目标对象 ID>",
-  "triggerTime": "beforeInsert",
-  "name": "MyTrigger",
-  "apiname": "NTrigger_unique_api_name"
-}
+### 6.2 只能在 SOURCE 区域内写业务逻辑
+
+AI 修改已有触发器时，只能修改：
+
+```java
+// @SOURCE_CONTENT_START
+// @SOURCE_CONTENT_END
 ```
 
-在 Node 中生成编码后参数示例：
+之间的内容。
 
-```bash
-node -p "encodeURI(JSON.stringify({schemetableName:'Account',targetObjectId:'<对象ID>',triggerTime:'beforeInsert',name:'MyTrigger',apiname:'NTrigger_xxx'}))"
+不得破坏：
+
+- 包路径
+- 类名
+- 目录结构
+- `config.json`
+- SOURCE 标记外的框架代码
+
+### 6.3 不得私改 `config.json` 的身份字段
+
+尤其不要私自改动：
+
+- `id`
+- `apiname`
+- `targetObjectId`
+- `schemetableName`
+- `triggerTime`
+
+这些字段应通过创建、发布、拉取、云端同步保持一致。
+
+### 6.4 必须保留 `userInfo` 上下文
+
+所有 SDK 能力都应围绕当前上下文用户执行。
+
+不得：
+
+- 硬编码用户
+- 绕过 `userInfo` 伪造“当前用户”
+- 用固定时区或固定组织代替上下文
+
+### 6.5 触发器里必须显式考虑递归风险
+
+凡是触发器里再去更新当前对象、父对象、子对象、共享对象，都要先判断是否会再次触发相关逻辑。
+
+AI 不能默认“更新一下没事”。
+
+### 6.6 触发器里必须显式考虑幂等性
+
+尤其是以下动作：
+
+- 自动生成记录
+- 自动发待办
+- 自动发邮件
+- 自动推送外部系统
+- 自动创建共享
+
+必须先判断是否已执行过，否则很容易重复生成、重复发送、重复推送。
+
+### 6.7 涉及时间必须优先使用 `TimeUtil`
+
+只要出现以下需求，AI 默认当成“有时区风险”处理：
+
+- 当前时间
+- 到期日比较
+- 提醒时间
+- 审批时间
+- 统计周期
+- 格式化时间字符串
+
+## 7. 触发器中的运行时思维模型
+
+基于当前项目样例，AI 在触发器里应默认建立以下思维模型：
+
+- 当前记录通常有“新值”和“旧值”两个视角
+- 当前触发器实例有上下文用户 `userInfo`
+- 当前触发器通常可以直接使用平台或基类提供的数据访问能力
+- 当前触发器要么做“拦截”，要么做“联动”，不要两类职责混在一起失控扩张
+
+在当前项目中，触发器里高频出现的能力包括：
+
+- `record_new`
+- `record_old`
+- `trigger`
+- `userInfo`
+- `CCService`
+- `cquery` / `cqlQuery`
+- `updateLt`
+- `SendEmail`
+- `DevLogger`
+
+这说明 AI 编写触发器时，应优先遵循：
+
+- 先拿清楚当前记录上下文
+- 再做必要查询
+- 再做校验或联动
+- 最后记录关键日志或错误
+
+## 8. SDK 使用规范
+
+本节是本文的核心。以下 API 说明基于官方 SDK 页面整理，并专门补成“AI 可直接使用”的格式。
+
+写法原则：
+
+- 先看方法签名
+- 再看参数表
+- 再看返回值
+- 再看 AI 使用规则
+
+### 8.1 `CCObject` 详细说明
+
+类说明：
+
+- 官方定义：CloudCC 对象类
+- 作用：作为对象数据的统一载体，用于新增、修改、删除、共享对象操作
+
+#### 8.1.1 构造方法
+
+方法签名：
+
+```java
+public CCObject()
+public CCObject(String ccobj)
+public CCObject(String ccobj, String isShared)
 ```
 
-将命令输出的**一整行**传给：`cloudcc create triggers '<粘贴>'`。
+参数说明：
 
-### 推荐操作顺序
+| 方法 | 参数 | 类型 | 是否必填 | 官方说明 | AI 使用说明 |
+| --- | --- | --- | --- | --- | --- |
+| `CCObject(String ccobj)` | `ccobj` | `String` | 是 | 对象 API | 传对象 API 名，如 `Account`、`Opportunity` |
+| `CCObject(String ccobj, String isShared)` | `ccobj` | `String` | 是 | 对象 API | 用于共享对象 |
+| `CCObject(String ccobj, String isShared)` | `isShared` | `String` | 是 | 共享标识，建议使用 `CCObject.IS_SHARED` | 不要手写魔法值，优先常量 |
 
-```bash
-# 1) 查询自定义对象，取得 schemetableName、targetObjectId（示例）
-cloudcc get object . custom
+常量字段：
+
+| 字段 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `OBJECT_API` | `String` | `CCObjectAPI` | 对象 API 常量 |
+| `IS_SHARED` | `String` | `isShared` | 共享对象常量 |
+
+#### 8.1.2 常用方法
+
+方法签名：
+
+```java
+public String getObjectApiName()
+public String put(String apiName, String value)
+```
+
+参数说明：
+
+| 方法 | 参数 | 类型 | 是否必填 | 官方说明 | AI 使用说明 |
+| --- | --- | --- | --- | --- | --- |
+| `put` | `apiName` | `String` | 是 | 字段 APIName | 必须传字段 API 名，不要传字段显示名 |
+| `put` | `value` | `String` | 是 | 字段值 | 官方示例按字符串传；AI 应按当前项目已有写法与 SDK 能力处理值类型 |
+
+返回值说明：
 
-# 2) 创建本地触发器目录与模板（encodedCreateJson 见上文）
-cloudcc create triggers '<encodedCreateJson>'
+| 方法 | 返回类型 | 含义 |
+| --- | --- | --- |
+| `getObjectApiName` | `String` | 当前对象 API 名 |
+| `put` | `String` | `HashMap` 风格返回值；在触发器里通常不依赖其返回值 |
 
-# 3) 编辑 triggers/<对象小写>/<name>/<name>.java 中 SOURCE 后发布
-cloudcc publish triggers account/MyTrigger
+AI 使用规则：
 
-# 4) 与服务器对齐
-cloudcc pull triggers account/MyTrigger
+- 新增记录：`new CCObject("ObjectApiName")`
+- 更新记录：必须先 `put("id", "...")`
+- 共享对象：优先 `new CCObject("ObjectApiName", CCObject.IS_SHARED)`
+- 不要把字段显示名直接写进 `put`
 
-# 5) 列表（查询 JSON 需 encodeURI）
-cloudcc get triggers '<listQueryJson>' .
+### 8.2 `UserInfo` 详细说明
 
-# 6) 按线上 ID 拉到指定项目
-cloudcc pullList triggers <线上触发器ID> <projectPath>
+类说明：
 
-# 7) 删除
-cloudcc delete triggers account/MyTrigger
+- 官方定义：用户信息对象，封装登录用户的基本信息
+- 作用：提供当前用户、组织、角色、时区等上下文，是所有服务端能力的根上下文
+
+构造方法：
+
+```java
+public UserInfo()
 ```
 
-### 文档子命令
+常用方法：
 
-```bash
-cloudcc doc triggers introduction
-cloudcc doc triggers devguide
+```java
+public String getUserId()
+public String getOrgId()
+public String getRoleId()
 ```
 
-仅支持 `introduction` 与 `devguide`。
+返回值说明：
 
----
+| 方法 | 返回类型 | 官方说明 | AI 使用说明 |
+| --- | --- | --- | --- |
+| `getUserId` | `String` | 当前用户 ID，未设置返回 `null` | 适合做当前操作人识别 |
+| `getOrgId` | `String` | 当前组织 ID，未设置返回 `null` | 适合做组织级逻辑判断 |
+| `getRoleId` | `String` | 当前角色 ID，未设置返回 `null` | 适合做角色权限判断 |
 
-## 一、什么是触发器
+AI 使用规则：
 
-CloudCC 触发器是完全符合 Java 语法规范的代码，在特定业务事件发生时自动执行，实现业务逻辑自动化处理。
+- `CCService`、`SendEmail`、`DevLogger`、`TimeUtil` 都应围绕 `userInfo` 构造或调用
+- 不要硬编码用户、组织、角色信息替代 `userInfo`
 
-触发器本质：
-- 一段 Java 代码，运行在 CloudCC 平台沙箱环境中
-- 使用 CCService、CCObject 等平台提供的 API 类
-- 在数据变更的特定时刻（前/后）自动触发执行
+### 8.3 `CCService` 详细说明
 
-## 二、触发器能干什么
+类说明：
 
-### 2.1 核心能力
+- 官方定义：CloudCC 核心工具类，提供对象增删改查等方法
+- 作用：触发器中最核心的数据访问入口
 
-| 能力 | 说明 | 示例 |
-|------|------|------|
-| 自动赋值 | 在记录保存前自动计算并填充字段 | 个人业绩/部门业绩自动赋值 |
-| 数据校验 | 阻止不符合业务规则的数据保存 | 预算金额校验、审批金额验证 |
-| 关联更新 | 修改一条记录时自动更新关联记录 | 回款明细汇总到收款计划 |
-| 自动生成 | 根据业务规则自动创建新记录 | 审批通过后自动生成回款记录 |
-| 权限控制 | 自动设置数据共享权限 | 按部门/人员自动共享 |
-| 状态同步 | 审批状态变更后同步更新相关字段 | 预算审批状态回写 |
-| 汇总计算 | 实时汇总明细数据到主记录 | 部门业绩字段汇总 |
+#### 8.3.1 构造函数
 
-### 2.2 技术能力（基于 CCService API）
+方法签名：
 
 ```java
-// 1. 新增记录
-CCObject opp = new CCObject("Opportunity");
-opp.put("name", "value");
-cs.insert(opp);
-
-// 2. 查询记录（指定字段）
-List<CCObject> opps1 = cs.cqueryByFields(
-  "Opportunity",
-  "khmc__c='" + record_new.get("id") + "'",
-  "id,name,createdate"
-);
-
-// 3. 查询记录（全部字段）
-List<CCObject> opps2 = cs.cquery(
-  "Opportunity",
-  "khmc__c='" + record_new.get("id") + "'"
-);
-
-// 4. 复杂查询
-List<CCObject> ccobjs = cs.cqlQuery(
-  "Opportunity",
-  "select sum(amount) as sumAmount from Opportunity where khmc='0012001238ytwuiw'"
-);
-
-// 5. 修改/删除
-cs.update(opp);
-cs.delete(opp);
-
-// 6. 发送邮件通知
-SendEmail sendEmail = new SendEmail(userInfo);
-sendEmail.sendMailFromSystem(toAddress, ccAddress, bccAddress, subject, content, isText);
+public CCService(UserInfo userInfo)
 ```
 
----
+参数说明：
 
-## 三、触发器的触发时机详解
+| 参数 | 类型 | 是否必填 | 官方说明 | AI 使用说明 |
+| --- | --- | --- | --- | --- |
+| `userInfo` | `UserInfo` | 是 | 用户对象 | 必须传当前上下文用户 |
 
-### 3.1 beforeUpsert（创建或更新前）
-- 执行时机：记录保存之前，数据尚未写入数据库
-- 典型用途：自动计算字段、数据格式校验、阻止非法数据保存、自动填充默认值
-- 生产实例：个人业绩/部门业绩赋值、计算产研成本/净业绩、生成部门/个人业绩
+#### 8.3.2 `insert`
+
+方法签名：
 
 ```java
-// beforeUpsert 示例
-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("毛利不能为负数！");
-}
+public ServiceResult insert(CCObject ccobj) throws BusiException
 ```
 
-### 3.2 afterInsert（创建后）
-- 执行时机：记录创建成功后（可获取 ID）
-- 典型用途：基于新记录 ID 创建关联记录、发送创建通知、初始化关联数据
-- 生产实例：根据净业绩拆分生成净业绩拆分回款
+参数说明：
+
+| 参数 | 类型 | 是否必填 | 官方说明 | AI 使用说明 |
+| --- | --- | --- | --- | --- |
+| `ccobj` | `CCObject` | 是 | CC 对象 | 用于新增单条记录 |
+
+返回值：
+
+- `ServiceResult`
+
+适用场景：
+
+- 新建关联记录
+- 审批通过后生成下游单据
+- 初始化台账、共享记录、中间记录
+
+AI 使用规则：
+
+- 新增前先补齐必要字段
+- 派生记录创建前必须先做幂等判断
+- 不要在可能重复触发的场景里无条件 `insert`
+
+#### 8.3.3 `cquery`
+
+方法签名：
 
 ```java
-// afterInsert 示例
-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);
+public List<CCObject> cquery(apiName, condtion, order) throws Exception
+public List<CCObject> cquery(String apiName, String condtion, boolean isDataObject) throws Exception
 ```
 
-### 3.3 afterUpsert（创建或更新后）
-- 执行时机：记录保存成功后（新增或修改）
-- 典型用途：汇总数据到父记录、触发下游流程、更新关联记录状态
-- 生产实例：金额汇总到收款计划、更新部门业绩字段、更新回款明细
+参数说明：
+
+| 方法 | 参数 | 类型 | 是否必填 | 官方说明 | AI 使用说明 |
+| --- | --- | --- | --- | --- | --- |
+| `cquery(apiName, condtion, order)` | `apiName` | `String` | 是 | 对象 APIName | 必传对象 API |
+| `cquery(apiName, condtion, order)` | `condition` | `String` | 否 | 使用字段 APIName 查询，自定义字段一定要加 `__c`；无条件则查全部 | 必须收窄条件，避免全表查 |
+| `cquery(apiName, condtion, order)` | `order` | `String` | 否 | 使用字段 APIName 排序，自定义字段一定要加 `__c` | 只在确实需要排序时传 |
+| `cquery(apiName, condtion, isDataObject)` | `apiName` | `String` | 是 | 对象 APIName | 必传对象 API |
+| `cquery(apiName, condtion, isDataObject)` | `condtion` | `String` | 否 | 同上 | 自定义字段记得 `__c` |
+| `cquery(apiName, condtion, isDataObject)` | `isDataObject` | `Boolean` | 否 | `true` 查普通数据，`false` 查共享数据 | 不要混淆普通对象和共享对象口径 |
+
+返回值：
+
+- `List<CCObject>`
+
+适用场景：
+
+- 简单单表查询
+- 普通对象查询
+- 共享对象查询
+
+AI 使用规则：
+
+- 简单查询优先 `cquery`
+- 自定义字段条件和排序都要加 `__c`
+- 条件为空会查全部数据，AI 应尽量避免
+
+#### 8.3.4 `cqlQuery`
+
+方法签名：
 
 ```java
-// afterUpsert 示例 - 汇总金额到父记录
-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);
-}
+public List<CCObject> cqlQuery(String apiName, String cql) throws Exception
 ```
 
-### 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：回款明细删除
+参数说明：
+
+| 参数 | 类型 | 是否必填 | 官方说明 | AI 使用说明 |
+| --- | --- | --- | --- | --- |
+| `apiName` | `String` | 是 | 对象 APIName | 必传主对象 API |
+| `cql` | `String` | 否 | SQL 语句，支持常用 `where` 条件 | 适用于聚合、复杂过滤；避免无边界 `select *` |
+
+返回值：
+
+- `List<CCObject>`
+
+适用场景：
+
+- 聚合统计
+- 求和、计数、汇总
+- `cquery` 不足以表达的复杂查询
+
+AI 使用规则：
+
+- 能用 `cquery` 时优先不用 `cqlQuery`
+- 使用 `cqlQuery` 时必须写清过滤条件
+- 结果为空时必须做空值保护
+
+#### 8.3.5 `update`
+
+方法签名：
+
+```java
+public ServiceResult update(CCObject ccobj) throws Exception
 ```
 
-### 5.2 费用报销管理
+参数说明：
+
+| 参数 | 类型 | 是否必填 | 官方说明 | AI 使用说明 |
+| --- | --- | --- | --- | --- |
+| `ccobj` | `CCObject` | 是 | CC 对象 | 修改记录时必须带 `id` |
+
+返回值：
+
+- `ServiceResult`
+
+适用场景：
+
+- 回写状态
+- 同步字段
+- 更新汇总结果
+
+AI 使用规则：
+
+- 必须先 `put("id", ...)`
+- 只更新必要字段
+- 优先评估递归触发风险
+
+#### 8.3.6 `delete`
+
+方法签名：
 
-```text
-费用报销提交
-  -> approval 触发器：验证审批时校验预算（报销金额 <= 预算余额）
-审批通过
-  -> approval 触发器：计算剩余欠款（借款 - 报销）
+```java
+public ServiceResult delete(CCObject ccobj) throws Exception
 ```
 
-### 5.3 借款还款管理
+参数说明：
+
+| 参数 | 类型 | 是否必填 | 官方说明 | AI 使用说明 |
+| --- | --- | --- | --- | --- |
+| `ccobj` | `CCObject` | 是 | CC 对象 | 删除记录时通常必须带 `id` |
+
+返回值：
+
+- `ServiceResult`
+
+适用场景：
 
-| 触发器 | 对象 | 时机 | 作用 |
-|--------|------|------|------|
-| 借款单触发器 | 借款单 | beforeUpsert | 借款前校验、自动计算 |
-| 还款记录审批通过更新借款单 | 还款记录 | approval | 审批后回写借款单 |
+- 删除派生记录
+- 删除中间记录
+- 服务端清理明确对象
 
----
+AI 使用规则：
 
-## 六、触发器开发最佳实践
+- 删除条件必须精准
+- 删除前后建议有日志
+- 涉及共享关系时优先看共享专用接口
 
-### 6.1 代码规范
+#### 8.3.7 `deleteShareObjectBySql`
+
+方法签名：
 
 ```java
-try {
-  CCObject record = (CCObject) data.get("record");
-  cs.update(record);
-} catch (Exception e) {
-  System.out.println("触发器执行失败：" + e.getMessage());
-  throw new Exception("业务校验失败：" + e.getMessage());
-}
+public void deleteShareObjectBySql(String objectApiName, String expression) throws Exception
 ```
 
-### 6.2 性能优化
+参数说明：
+
+| 参数 | 类型 | 是否必填 | 官方说明 | AI 使用说明 |
+| --- | --- | --- | --- | --- |
+| `objectApiName` | `String` | 是 | 对象 APIName | 共享对象 API |
+| `expression` | `String` | 是 | SQL 表达式，字段不需要加 `__c` | 这是共享删除的关键差异点 |
+
+返回值：
+
+- `void`
+
+适用场景：
+
+- 删除共享表记录
+- 删除旧共享关系
+- 负责人变化后回收历史共享
+
+AI 使用规则：
+
+- 普通对象删除和共享对象删除不要混用
+- 这里的字段表达式不需要加 `__c`
+
+#### 8.3.8 自定义设置 API
+
+方法签名：
 
 ```java
-// 推荐：字段过滤，只查询需要的字段
-List<CCObject> records = cs.cqueryByFields(
-  "Object__c",
-  "status__c='active'",
-  "id,name,amount__c"
-);
-
-// 推荐：批量更新，降低递归风险
-cs.updateLt(records);
+public Map getListCustomSetting(String objectApiName)
+Map map = cs.getListCustomSetting(String apiName, String Name)
+public Map getCustomSetting(String objectApiName, String id)
 ```
 
-### 6.3 避免递归触发
+参数说明：
+
+| 方法 | 参数 | 类型 | 是否必填 | 官方说明 | AI 使用说明 |
+| --- | --- | --- | --- | --- | --- |
+| `getListCustomSetting(String objectApiName)` | `objectApiName` | `String` | 是 | 对象 APIName | 返回某个列表型自定义设置的全部数据 |
+| `getListCustomSetting(String apiName, String name)` | `apiName` | `String` | 是 | 对象 APIName | 取列表型自定义设置中的单条 |
+| `getListCustomSetting(String apiName, String name)` | `name` | `String` | 是 | 自定义设置属性名称 | 通过名称定位单条配置 |
+| `getCustomSetting(String objectApiName, String id)` | `objectApiName` | `String` | 是 | 对象 APIName | 用于层次结构型自定义设置 |
+| `getCustomSetting(String objectApiName, String id)` | `id` | `String` | 是 | 简档 id 或用户 id | 按权限上下文取配置 |
+
+返回值：
+
+- `Map`
+
+适用场景：
+
+- 开关参数
+- 业务阈值
+- 模板映射
+- 接口地址
+- 角色映射
+- 分环境配置
+
+AI 使用规则：
+
+- 可变参数优先配置化
+- 不要把阈值、模板 ID、地址、角色映射硬编码在触发器里
+
+### 8.4 `SendEmail` 详细说明
+
+类说明：
+
+- 官方定义：用于发送邮件通知
+
+#### 8.4.1 构造方法
+
+方法签名：
 
 ```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");
+public SendEmail(UserInfo userInfo)
 ```
 
----
+参数说明：
 
-## 七、触发器调试与监控
+| 参数 | 类型 | 是否必填 | 官方说明 | AI 使用说明 |
+| --- | --- | --- | --- | --- |
+| `userInfo` | `UserInfo` | 是 | 用户对象 | 用当前上下文发送邮件 |
 
-### 7.1 日志记录
+#### 8.4.2 `sendMailFromSystem`
+
+方法签名：
 
 ```java
-System.out.println("=== 触发器开始执行 ===");
-System.out.println("对象：" + record.getSObjectName());
-System.out.println("操作：" + data.get("action"));
-System.out.println("记录 ID：" + record.get("id"));
+public boolean sendMailFromSystem(
+    String[] toAddress,
+    String[] ccAddress,
+    String[] bccAddress,
+    String subject,
+    String content,
+    boolean isText)
 ```
 
-### 7.2 常见问题排查
-
-| 问题 | 可能原因 | 解决方案 |
-|------|----------|----------|
-| 触发器不执行 | 未激活、触发时机不对 | 检查状态与配置 |
-| 递归触发 | 更新操作再次触发触发器 | 使用 `updateLt` 或增加条件判断 |
-| 性能问题 | 查询数据量过大 | 增加查询条件、字段过滤 |
-| 数据不一致 | 触发器执行失败 | 增加异常处理与关键日志 |
-
----
-
-## 八、总结
-
-### 8.1 触发器价值
-1. 自动化：减少人工操作，降低出错率
-2. 一致性：保证数据准确与规则统一执行
-3. 实时性：业务变更立即响应
-4. 灵活性：Java 代码可承载复杂逻辑
-
-### 8.2 适用与不适用场景
-
-**适合使用触发器：**
-- 需要实时数据联动
-- 核心业务规则校验
-- 跨对象数据同步
-- 审批流程复杂逻辑
-- 自动创建或更新关联记录
-
-**不适合使用触发器：**
-- 简单字段默认值（优先配置化能力）
-- 大批量离线数据处理
-- 跨系统集成调用
-- 强交互型前端界面逻辑
-
-### 8.3 触发器开发 Checklist
-
-- [ ] 本地 `triggers/` 目录仅通过 `cloudcc create` / `cloudcc pull` / `cloudcc pullList` / `cloudcc publish` / `cloudcc delete` 等命令维护，不手造路径、不手改 `config.json` 的 `id`
-- [ ] 明确触发时机（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 | ❌ |
-
-文档生成时间：2026-03-24
-基于 CloudCC 生产环境 25 个触发器实例分析
+参数说明：
+
+| 参数 | 类型 | 是否必填 | 官方说明 | AI 使用说明 |
+| --- | --- | --- | --- | --- |
+| `toAddress` | `String[]` | 是 | 收件箱 | 没有收件人不要发送 |
+| `ccAddress` | `String[]` | 是 | 抄送人 | 没有可传空数组 |
+| `bccAddress` | `String[]` | 是 | 密送人 | 没有可传空数组 |
+| `subject` | `String` | 是 | 邮件标题 | 标题要能表达业务动作 |
+| `content` | `String` | 是 | 邮件内容 | HTML 内容要控制复杂度 |
+| `isText` | `boolean` | 是 | 是否采用 TXT 方式发送；`false` 为 HTML | HTML 邮件常用 `false` |
+
+返回值：
+
+- `boolean`
+
+AI 使用规则：
+
+- 业务动作成功后再发邮件
+- 不要把邮件发送当成日志系统
+- 同一动作避免重复发送
+
+#### 8.4.3 `sendEmailNew`
+
+方法签名：
+
+```java
+public ServiceResult sendEmailNew(
+    String emailtemplateid,
+    String[] toaddress,
+    String[] ccaddress,
+    String[] bcaddress,
+    String id) throws Exception
+```
+
+参数说明：
+
+| 参数 | 类型 | 是否必填 | 官方说明 | AI 使用说明 |
+| --- | --- | --- | --- | --- |
+| `emailtemplateid` | `String` | 是 | 邮件模版 id | 优先模板化发送 |
+| `toaddress` | `String[]` | 是 | 收件箱 | 传收件人数组 |
+| `ccaddress` | `String[]` | 是 | 抄送人 | 没有可传空数组 |
+| `bcaddress` | `String[]` | 是 | 密送人 | 官方签名为 `bcaddress`，按签名使用 |
+| `id` | `String` | 是 | 官方文档仅给出 `id` | 结合方法语义，AI 应将其视为模板填充关联记录 ID；此处为基于官方方法名与示例的推断 |
+
+返回值：
+
+- `ServiceResult`
+
+AI 使用规则：
+
+- 模板内容能配置就不要在触发器里拼长字符串
+- 对 `id` 的使用要和模板数据来源一致
+
+### 8.5 `DevLogger` 详细说明
+
+类说明：
+
+- 官方定义：运行日志采集
+
+#### 8.5.1 构造函数
+
+方法签名：
+
+```java
+public DevLogger(UserInfo userInfo)
+```
+
+参数说明：
+
+| 参数 | 类型 | 是否必填 | 官方说明 | AI 使用说明 |
+| --- | --- | --- | --- | --- |
+| `userInfo` | `UserInfo` | 是 | 用户对象 | 用当前上下文记录日志 |
+
+#### 8.5.2 `devLogInfo`
+
+方法签名：
+
+```java
+public void devLogInfo(String info)
+```
+
+参数说明：
+
+| 参数 | 类型 | 是否必填 | 官方说明 | AI 使用说明 |
+| --- | --- | --- | --- | --- |
+| `info` | `String` | 是 | 日志信息 | 记录关键主键、关键分支、关键动作 |
+
+返回值：
+
+- `void`
+
+#### 8.5.3 `devLogError`
+
+方法签名：
+
+```java
+public void devLogError(String error, Throwable throwable)
+```
+
+参数说明：
+
+| 参数 | 类型 | 是否必填 | 官方说明 | AI 使用说明 |
+| --- | --- | --- | --- | --- |
+| `error` | `String` | 是 | 日志信息 | 错误信息必须包含业务上下文 |
+| `throwable` | `Throwable` | 否 | 异常对象 | 有异常时尽量带上 |
+
+返回值：
+
+- `void`
+
+AI 使用规则：
+
+- 关键主键要记录
+- 当前触发时机要记录
+- 下游调用结果要记录
+- 异常不能吞
+
+### 8.6 `TimeUtil` 详细说明
+
+类说明：
+
+- 官方说明：`Date` 和 `Calendar` 默认基于本地时区，跨时区处理容易出错
+- 作用：所有和当前时间、用户时区、格式化、Calendar 相关的逻辑，都应优先走 `TimeUtil`
+
+#### 8.6.1 `getNowDate`
+
+官方示例：
+
+```java
+TpSysTask task = new TpSysTask();
+task.setBeginTime(TimeUtil.getNowDate(userInfo));
+```
+
+参数说明：
+
+| 参数 | 类型 | 是否必填 | 官方说明 |
+| --- | --- | --- | --- |
+| `userInfo` | `UserInfo` | 是 | 用户对象 |
+
+AI 使用规则：
+
+- 需要“当前时间”时优先它，不要直接 `new Date()`
+
+#### 8.6.2 `getUserTimeZone`
+
+方法形式：
+
+```java
+TimeUtil.getUserTimeZone(userInfo)
+```
+
+参数说明：
+
+| 参数 | 类型 | 是否必填 | 官方说明 |
+| --- | --- | --- | --- |
+| `userInfo` | `UserInfo` | 是 | 用户对象 |
+
+AI 使用规则：
+
+- 需要自己构造时区相关对象时优先先取用户时区
+
+#### 8.6.3 `getSimpleDateFormat`
+
+官方示例：
+
+```java
+SimpleDateFormat myDateFormat = TimeUtil.getSimpleDateFormat(format, userInfo);
+```
+
+参数说明：
+
+| 参数 | 类型 | 是否必填 | 默认值 | 官方说明 | AI 使用说明 |
+| --- | --- | --- | --- | --- | --- |
+| `format` | `String` | 是 | `"yyyy-MM-dd"` | 格式化 | 显式传格式串 |
+| `userInfo` | `UserInfo` | 是 | - | 用户对象 | 用用户时区创建格式化器 |
+
+#### 8.6.4 `getCalendar`
+
+官方文档给出两种方式：
+
+```java
+Calendar cal = Calendar.getInstance(TimeUtil.getUserTimeZone(userInfo));
+Calendar cal = TimeUtil.getCalendar(userInfo);
+```
+
+AI 使用规则：
+
+- 处理日历计算时优先 `TimeUtil.getCalendar(userInfo)`
+- 不要默认 `Calendar.getInstance()` 使用本地时区
+
+## 9. 触发器里的代码结构建议
+
+### 9.1 采用“判断 -> 查询 -> 校验 -> 执行 -> 记录”的顺序
+
+推荐思路：
+
+1. 先识别当前触发场景
+2. 再判断是否满足继续执行条件
+3. 再做最小必要查询
+4. 再执行业务动作
+5. 最后记录日志或错误
+
+不要一上来就先查很多无关数据。
+
+### 9.2 先过滤，再计算
+
+如果当前触发器只在某些状态、某些字段、某些记录类型下生效，应先快速退出无关场景。
+
+这样做的价值：
+
+- 降低无谓查询
+- 降低递归触发影响
+- 降低对其他业务分支的误伤
+
+### 9.3 先查一批，再批量处理
+
+如果需要操作多条关联记录，优先：
+
+- 一次查够
+- 建立映射
+- 合并处理
+
+避免：
+
+- 在循环里重复查询
+- 在循环里逐条查、逐条更
+
+### 9.4 薄触发器 + 服务下沉
+
+如果逻辑超过以下规模，优先下沉到自定义类：
+
+- 多个对象联动
+- 多层条件嵌套
+- 多处复用
+- 外部接口调用
+- 多步通知和补偿
+
+触发器中更推荐：
+
+- 只拼装输入
+- 调服务类
+- 根据结果做拦截或记录
+
+## 10. 性能、递归与幂等
+
+### 10.1 性能原则
+
+AI 默认应避免：
+
+- 无条件全表查询
+- 过度使用 `select *`
+- 循环内查数据库
+- 循环内大量单条更新
+
+AI 应优先：
+
+- 只查必要字段
+- 只查必要记录
+- 合并写操作
+- 复用查询结果
+
+### 10.2 递归触发原则
+
+触发器中最危险的问题之一，是“我更新了一条数据，结果又触发自己或兄弟触发器”。
+
+AI 每次写更新逻辑时都必须问：
+
+- 更新的是不是当前对象
+- 更新的是不是相关联、也挂了触发器的对象
+- 这次更新是否会反向回写回来
+
+如果有风险，应优先：
+
+- 缩小更新字段
+- 加前置判断
+- 利用项目已有的低触发/批量更新能力
+- 将高复杂逻辑下沉到更可控的服务层
+
+### 10.3 幂等原则
+
+以下动作最需要幂等判断：
+
+- 自动生成项目、工作包、子单据
+- 自动创建共享
+- 自动发送待办、邮件
+- 自动推送外部系统
+
+AI 不得默认“只会触发一次”。
+
+必须显式考虑：
+
+- 是否已生成
+- 是否已发送
+- 是否已同步
+- 是否已存在同业务键记录
+
+## 11. 触发器中的常见业务模式
+
+基于当前项目本地触发器分析，AI 可优先把需求归入以下模式之一：
+
+- 保存前校验
+- 保存前自动赋值
+- 保存后汇总回写
+- 创建后自动派生
+- 审批前校验
+- 审批后推进流程
+- 删除前保护
+- 删除后补偿
+- 负责人变化后的共享治理
+- 事件触发后的通知和集成
+
+一旦能把需求归入模式，时机选择、SDK 选择和代码结构都会更清晰。
+
+## 12. AI 最容易犯的错误
+
+### 12.1 把触发器写成大型业务类
+
+错误表现：
+
+- 大量查询、更新、通知、外部调用全堆在 SOURCE 区域
+
+正确做法：
+
+- 触发器做薄入口
+- 大逻辑下沉到自定义类
+
+### 12.2 在错误时机做错误动作
+
+错误表现：
+
+- 在 `before*` 里做依赖 ID 的派生创建
+- 在 `after*` 里做本应提前阻断的校验
+
+正确做法：
+
+- 先判断这是拦截型规则还是联动型规则
+
+### 12.3 没有考虑递归和重复执行
+
+错误表现：
+
+- 更新引发再次触发
+- 自动生成重复记录
+- 同一通知反复发送
+
+正确做法：
+
+- 加前置判断
+- 做幂等检查
+- 缩小写入范围
+
+### 12.4 把可配置项写死
+
+错误表现：
+
+- 模板 ID、角色映射、阈值、接口地址直接写死在触发器里
+
+正确做法：
+
+- 优先使用自定义设置
+
+### 12.5 忽视日志和异常
+
+错误表现：
+
+- 吞掉异常
+- 失败无日志
+- 只有“执行失败”这种低价值日志
+
+正确做法：
+
+- 关键分支打日志
+- 异常带上下文
+- 错误信息能定位到业务对象和关键动作
+
+## 13. AI 的交付要求
+
+当 AI 输出一个触发器方案或实现时，至少应明确：
+
+- 为什么要用触发器，而不是定时器、页面脚本或纯自定义类
+- 为什么选这个触发时机
+- 当前触发器负责什么，不负责什么
+- 哪些逻辑保留在触发器里
+- 哪些逻辑应该下沉到自定义类
+- 使用了哪些 SDK 能力
+- 如何避免递归、性能和幂等问题
+- 如何处理日志、异常、通知和时间
+
+## 14. 最终结论
+
+对 AI 来说，触发器最正确的定位不是“哪里都能塞逻辑”，而是：
+
+- 一个跟随对象生命周期执行的服务端规则入口
+- 一个负责拦截、联动、推进、补偿的即时执行点
+- 一个必须尽量薄、尽量稳、尽量可控的入口层
+
+因此，AI 在写触发器时，应始终遵循这条总原则：
+
+- 用触发器做事件入口
+- 用 SDK 做规范数据操作
+- 用自定义类承接复杂逻辑
+- 用日志、幂等、时区和配置意识保证长期可维护