cloudcc-cli 2.3.9 → 2.4.1

package/src/triggers/docs/devguide.md

@@ -1,442 +1,1140 @@
-# 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. 与 introduction 的分工（避免重复）
+
+为避免与 `triggers introduction` 内容重复，本 `devguide` 只保留“开发落地规范”：
+
+- 命令与入参（可直接执行）
+- 目录与文件约束（可直接检查）
+- SDK 用法与边界（可直接编码）
+- 代码结构、性能/递归/幂等与交付要求（可直接评审）
+
+“触发器是什么、适用/不适用场景、能力边界、与其他实现方式差异”等概念说明，统一以
+`cloudcc doc triggers introduction` 为准。
+
+## 4. triggers 模块支持的 CLI 命令总览（重点：入参）
+
+说明：
+
+- 下文命令中的资源名使用 `triggers`。
+- `projectPath` 未传时，默认使用当前工作目录。
+
+#### 1) 创建触发器
+
+命令：
 
 ```bash
 cloudcc create triggers <encodedCreateJson>
+```
+
+`encodedCreateJson`（先 JSON.stringify，再 encodeURI）推荐字段：
+
+| 字段              | 必填 | 类型     | 说明                                                   |
+| ----------------- | ---- | -------- | ------------------------------------------------------ |
+| `schemetableName` | 是   | `string` | 目标对象 API 名（目录中会转小写）                      |
+| `targetObjectId`  | 是   | `string` | 目标对象 ID                                            |
+| `triggerTime`     | 是   | `string` | 触发时机，如 `beforeInsert`、`afterUpdate`、`approval` |
+| `name`            | 是   | `string` | 触发器名称                                             |
+| `apiname`         | 建议 | `string` | 触发器 API 名                                          |
+
+#### 2) 发布触发器
+
+命令：
+
+```bash
 cloudcc publish triggers <namePath>
+```
+
+参数：
+
+| 参数       | 必填 | 类型     | 说明                                    |
+| ---------- | ---- | -------- | --------------------------------------- |
+| `namePath` | 是   | `string` | 触发器路径，格式：`对象小写名/触发器名` |
+
+#### 3) 拉取触发器（按本地路径）
+
+命令：
+
+```bash
 cloudcc pull triggers <namePath>
-cloudcc get triggers <listQueryJson> [projectPath]
-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。
+| 参数       | 必填 | 类型     | 说明                                                                             |
+| ---------- | ---- | -------- | -------------------------------------------------------------------------------- |
+| `namePath` | 是   | `string` | 触发器路径，格式：`对象小写名/触发器名`；会读取该目录 `config.json` 的 `id` 拉取 |
 
-### 命令作用摘要
+#### 4) 查询触发器列表（支持条件查询）
 
-| 命令 | 作用 |
-|------|------|
-| `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 速查 |
+命令：
 
-### 创建示例（需先准备对象信息）
+```bash
+cloudcc get triggers <listQueryJson> [projectPath]
+```
 
-先构造对象（字段与平台约定一致），再整段做 `encodeURI(JSON.stringify(...))`，作为 `cloudcc create triggers` 的**唯一参数**：
+`listQueryJson` 推荐结构：
 
 ```json
 {
-  "schemetableName": "Account",
-  "targetObjectId": "<目标对象 ID>",
-  "triggerTime": "beforeInsert",
-  "name": "MyTrigger",
-  "apiname": "NTrigger_unique_api_name"
+    "shownum": 2000,
+    "showpage": 1,
+    "fid": "",
+    "sname": "",
+    "rptcond": "",
+    "rptorder": "",
+    "objId": ""
 }
 ```
 
-在 Node 中生成编码后参数示例：
+字段语义：
+
+| 字段       | 含义              | 类型     | 是否推荐 | 说明                     |
+| ---------- | ----------------- | -------- | -------- | ------------------------ |
+| `shownum`  | 每页条数          | `number  | string`  | 推荐                     |
+| `showpage` | 页码              | `number  | string`  | 推荐                     |
+| `sname`    | 触发器名字        | `string` | 可选     | 按名称模糊筛选，模糊查询 |
+| `objId`    | 触发器作用对象 ID | `string` | 可选     | 对象id                   |
+
+#### 5) 查看触发器详情
+
+命令：
 
 ```bash
-node -p "encodeURI(JSON.stringify({schemetableName:'Account',targetObjectId:'<对象ID>',triggerTime:'beforeInsert',name:'MyTrigger',apiname:'NTrigger_xxx'}))"
+cloudcc detail triggers <namePath> <id>
 ```
 
-将命令输出的**一整行**传给：`cloudcc create triggers '<粘贴>'`。
+参数规则（实现口径）：
+
+| 参数       | 必填     | 类型     | 说明                                             |
+| ---------- | -------- | -------- | ------------------------------------------------ |
+| `namePath` | 条件必填 | `string` | 传 `namePath` 时优先查本地；本地不完整时再走线上 |
+| `id`       | 条件必填 | `string` | 当 `namePath` 为空时，必须传 `id` 走线上查询     |
 
-### 推荐操作顺序
+等价理解：`namePath` 与 `id` 至少传一个，优先使用 `namePath` 路径。
+
+#### 6) 按 ID 拉取并落地到本地目录
+
+命令：
 
 ```bash
-# 1) 查询自定义对象，取得 schemetableName、targetObjectId（示例）
-cloudcc get object . custom
+cloudcc pullList triggers <id> <projectPath>
+```
+
+参数：
+
+| 参数          | 必填 | 类型     | 说明                                                        |
+| ------------- | ---- | -------- | ----------------------------------------------------------- |
+| `id`          | 是   | `string` | 线上触发器 ID                                               |
+| `projectPath` | 是   | `string` | 项目根目录；会写入到 `<projectPath>/triggers/<obj>/<name>/` |
+
+#### 7) 删除触发器
+
+命令：
 
-# 2) 创建本地触发器目录与模板（encodedCreateJson 见上文）
-cloudcc create triggers '<encodedCreateJson>'
+```bash
+cloudcc delete triggers <namePathOrId> [projectPath]
+```
 
-# 3) 编辑 triggers/<对象小写>/<name>/<name>.java 中 SOURCE 后发布
-cloudcc publish triggers account/MyTrigger
+参数规则：
 
-# 4) 与服务器对齐
-cloudcc pull triggers account/MyTrigger
+| 参数           | 必填 | 类型     | 说明                                                                                  |
+| -------------- | ---- | -------- | ------------------------------------------------------------------------------------- |
+| `namePathOrId` | 是   | `string` | 可传触发器路径或线上 ID；若本地路径存在且 `config.json` 含 `id`，优先使用该 `id` 删除 |
+| `projectPath`  | 否   | `string` | 项目根目录，默认当前目录                                                              |
 
-# 5) 列表（查询 JSON 需 encodeURI）
-cloudcc get triggers '<listQueryJson>' .
+#### 8) 文档命令
 
-# 6) 按线上 ID 拉到指定项目
-cloudcc pullList triggers <线上触发器ID> <projectPath>
+命令：
 
-# 7) 删除
-cloudcc delete triggers account/MyTrigger
+```bash
+cloudcc doc triggers <introduction|devguide>
 ```
 
-### 文档子命令
+参数：
+
+| 参数          | 必填      | 类型 | 说明     |
+| ------------- | --------- | ---- | -------- |
+| `introduction | devguide` | 是   | `string` |
+
+## 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 doc triggers introduction
-cloudcc doc triggers devguide
+cloudcc create triggers <encodedCreateJson>
+cloudcc publish triggers <namePath>
+cloudcc pull triggers <namePath>
+cloudcc get triggers <listQueryJson> [projectPath]
+cloudcc detail triggers <namePath>
+cloudcc detail triggers "" <id>
+cloudcc pullList triggers <id> <projectPath>
+cloudcc delete triggers <namePathOrId> [projectPath]
+```
+
+### 6.2 只能在 SOURCE 区域内写业务逻辑
+
+AI 修改已有触发器时，只能修改：
+
+```java
+// @SOURCE_CONTENT_START
+// @SOURCE_CONTENT_END
 ```
 
-仅支持 `introduction` 与 `devguide`。
+之间的内容。
+
+不得破坏：
+
+- 包路径
+- 类名
+- 目录结构
+- `config.json`
+- SOURCE 标记外的框架代码
+
+### 6.3 不得私改 `config.json` 的身份字段
+
+尤其不要私自改动：
+
+- `id`
+- `apiname`
+- `targetObjectId`
+- `schemetableName`
+- `triggerTime`
+
+这些字段应通过创建、发布、拉取、云端同步保持一致。
+
+### 6.4 必须保留 `userInfo` 上下文
 
----
+所有 SDK 能力都应围绕当前上下文用户执行。
 
-## 一、什么是触发器
+不得：
 
-CloudCC 触发器是完全符合 Java 语法规范的代码，在特定业务事件发生时自动执行，实现业务逻辑自动化处理。
+- 硬编码用户
+- 绕过 `userInfo` 伪造“当前用户”
+- 用固定时区或固定组织代替上下文
 
-触发器本质：
-- 一段 Java 代码，运行在 CloudCC 平台沙箱环境中
-- 使用 CCService、CCObject 等平台提供的 API 类
-- 在数据变更的特定时刻（前/后）自动触发执行
+### 6.5 触发器里必须显式考虑递归风险
 
-## 二、触发器能干什么
+凡是触发器里再去更新当前对象、父对象、子对象、共享对象，都要先判断是否会再次触发相关逻辑。
 
-### 2.1 核心能力
+AI 不能默认“更新一下没事”。
 
-| 能力 | 说明 | 示例 |
-|------|------|------|
-| 自动赋值 | 在记录保存前自动计算并填充字段 | 个人业绩/部门业绩自动赋值 |
-| 数据校验 | 阻止不符合业务规则的数据保存 | 预算金额校验、审批金额验证 |
-| 关联更新 | 修改一条记录时自动更新关联记录 | 回款明细汇总到收款计划 |
-| 自动生成 | 根据业务规则自动创建新记录 | 审批通过后自动生成回款记录 |
-| 权限控制 | 自动设置数据共享权限 | 按部门/人员自动共享 |
-| 状态同步 | 审批状态变更后同步更新相关字段 | 预算审批状态回写 |
-| 汇总计算 | 实时汇总明细数据到主记录 | 部门业绩字段汇总 |
+### 6.6 触发器里必须显式考虑幂等性
 
-### 2.2 技术能力（基于 CCService API）
+尤其是以下动作：
+
+- 自动生成记录
+- 自动发待办
+- 自动发邮件
+- 自动推送外部系统
+- 自动创建共享
+
+必须先判断是否已执行过，否则很容易重复生成、重复发送、重复推送。
+
+### 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
-// 1. 新增记录
-CCObject opp = new CCObject("Opportunity");
-opp.put("name", "value");
-cs.insert(opp);
+public CCObject()
+public CCObject(String ccobj)
+public CCObject(String ccobj, String isShared)
+```
+
+参数说明：
 
-// 2. 查询记录（指定字段）
-List<CCObject> opps1 = cs.cqueryByFields(
-  "Opportunity",
-  "khmc__c='" + record_new.get("id") + "'",
-  "id,name,createdate"
-);
+| 方法                                      | 参数       | 类型     | 是否必填 | 官方说明                                | 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` | 不要手写魔法值，优先常量                   |
 
-// 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'"
-);
+| 字段         | 类型     | 默认值        | 说明          |
+| ------------ | -------- | ------------- | ------------- |
+| `OBJECT_API` | `String` | `CCObjectAPI` | 对象 API 常量 |
+| `IS_SHARED`  | `String` | `isShared`    | 共享对象常量  |
 
-// 5. 修改/删除
-cs.update(opp);
-cs.delete(opp);
+#### 8.1.2 常用方法
 
-// 6. 发送邮件通知
-SendEmail sendEmail = new SendEmail(userInfo);
-sendEmail.sendMailFromSystem(toAddress, ccAddress, bccAddress, subject, content, isText);
+方法签名：
+
+```java
+public String getObjectApiName()
+public String put(String apiName, String value)
 ```
 
----
+参数说明：
+
+| 方法  | 参数      | 类型     | 是否必填 | 官方说明     | AI 使用说明                                                      |
+| ----- | --------- | -------- | -------- | ------------ | ---------------------------------------------------------------- |
+| `put` | `apiName` | `String` | 是       | 字段 APIName | 必须传字段 API 名，不要传字段显示名                              |
+| `put` | `value`   | `String` | 是       | 字段值       | 官方示例按字符串传；AI 应按当前项目已有写法与 SDK 能力处理值类型 |
+
+返回值说明：
+
+| 方法               | 返回类型 | 含义                                               |
+| ------------------ | -------- | -------------------------------------------------- |
+| `getObjectApiName` | `String` | 当前对象 API 名                                    |
+| `put`              | `String` | `HashMap` 风格返回值；在触发器里通常不依赖其返回值 |
+
+AI 使用规则：
 
-## 三、触发器的触发时机详解
+- 新增记录：`new CCObject("ObjectApiName")`
+- 更新记录：必须先 `put("id", "...")`
+- 共享对象：优先 `new CCObject("ObjectApiName", CCObject.IS_SHARED)`
+- 不要把字段显示名直接写进 `put`
 
-### 3.1 beforeUpsert（创建或更新前）
-- 执行时机：记录保存之前，数据尚未写入数据库
-- 典型用途：自动计算字段、数据格式校验、阻止非法数据保存、自动填充默认值
-- 生产实例：个人业绩/部门业绩赋值、计算产研成本/净业绩、生成部门/个人业绩
+### 8.2 `UserInfo` 详细说明
+
+类说明：
+
+- 官方定义：用户信息对象，封装登录用户的基本信息
+- 作用：提供当前用户、组织、角色、时区等上下文，是所有服务端能力的根上下文
+
+构造方法：
 
 ```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 UserInfo()
 ```
 
-### 3.2 afterInsert（创建后）
-- 执行时机：记录创建成功后（可获取 ID）
-- 典型用途：基于新记录 ID 创建关联记录、发送创建通知、初始化关联数据
-- 生产实例：根据净业绩拆分生成净业绩拆分回款
+常用方法：
 
 ```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 String getUserId()
+public String getOrgId()
+public String getRoleId()
 ```
 
-### 3.3 afterUpsert（创建或更新后）
-- 执行时机：记录保存成功后（新增或修改）
-- 典型用途：汇总数据到父记录、触发下游流程、更新关联记录状态
-- 生产实例：金额汇总到收款计划、更新部门业绩字段、更新回款明细
+返回值说明：
+
+| 方法        | 返回类型 | 官方说明                       | AI 使用说明          |
+| ----------- | -------- | ------------------------------ | -------------------- |
+| `getUserId` | `String` | 当前用户 ID，未设置返回 `null` | 适合做当前操作人识别 |
+| `getOrgId`  | `String` | 当前组织 ID，未设置返回 `null` | 适合做组织级逻辑判断 |
+| `getRoleId` | `String` | 当前角色 ID，未设置返回 `null` | 适合做角色权限判断   |
+
+AI 使用规则：
+
+- `CCService`、`SendEmail`、`DevLogger`、`TimeUtil` 都应围绕 `userInfo`
+  构造或调用
+- 不要硬编码用户、组织、角色信息替代 `userInfo`
+
+### 8.3 `CCService` 详细说明
+
+类说明：
+
+- 官方定义：CloudCC 核心工具类，提供对象增删改查等方法
+- 作用：触发器中最核心的数据访问入口
+
+#### 8.3.1 构造函数
+
+方法签名：
 
 ```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 CCService(UserInfo userInfo)
+```
+
+参数说明：
+
+| 参数       | 类型       | 是否必填 | 官方说明 | AI 使用说明          |
+| ---------- | ---------- | -------- | -------- | -------------------- |
+| `userInfo` | `UserInfo` | 是       | 用户对象 | 必须传当前上下文用户 |
+
+#### 8.3.2 `insert`
+
+方法签名：
+
+```java
+public ServiceResult insert(CCObject ccobj) throws BusiException
 ```
 
-### 3.4 afterDelete（删除后）
-- 执行时机：记录删除成功后
-- 典型用途：清理关联数据、反向汇总更新
-- 生产实例：回款明细删除后重新计算回款金额
+参数说明：
+
+| 参数    | 类型       | 是否必填 | 官方说明 | AI 使用说明      |
+| ------- | ---------- | -------- | -------- | ---------------- |
+| `ccobj` | `CCObject` | 是       | CC 对象  | 用于新增单条记录 |
+
+返回值：
 
-### 3.5 approval（审批时）
-- 执行时机：记录提交审批或审批通过时
-- 典型用途：审批前校验、审批通过后执行业务操作
-- 生产实例：更新拆分审批状态、订单审批判断、审批通过计算剩余欠款
+- `ServiceResult`
 
----
+适用场景：
 
-## 四、为什么要用触发器
+- 新建关联记录
+- 审批通过后生成下游单据
+- 初始化台账、共享记录、中间记录
 
-### 4.1 解决的核心问题
+AI 使用规则：
+
+- 新增前先补齐必要字段
+- 派生记录创建前必须先做幂等判断
+- 不要在可能重复触发的场景里无条件 `insert`
+
+#### 8.3.3 `cquery`
+
+方法签名：
+
+```java
+public List<CCObject> cquery(apiName, condtion, order) throws Exception
+public List<CCObject> cquery(String apiName, String condtion, boolean isDataObject) throws Exception
+```
 
-| 问题 | 传统方案 | 触发器方案 |
-|------|----------|------------|
-| 数据一致性 | 依赖用户手动操作，容易遗漏 | 自动执行，保证数据准确 |
-| 业务规则执行 | 前端校验可绕过 | 统一在平台层执行，无法绕过 |
-| 跨对象联动 | 需要多次手动操作 | 自动关联更新 |
-| 审批复杂逻辑 | 审批流配置难以承载 | Java 代码可实现复杂逻辑 |
-| 实时性要求 | 定时任务有延迟 | 实时触发，立即执行 |
+参数说明：
 
-### 4.2 与其他方案对比
+| 方法                                      | 参数           | 类型      | 是否必填 | 官方说明                                                        | 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` 查共享数据                           | 不要混淆普通对象和共享对象口径 |
 
-| 方案 | 优点 | 缺点 | 适用场景 |
-|------|------|------|----------|
-| 触发器 | 实时、自动、无法绕过 | 需要 Java 开发能力 | 核心业务逻辑 |
-| 审批流 | 配置简单、可视化 | 逻辑能力有限 | 简单审批流程 |
-| 工作流 | 可视化编排 | 复杂逻辑实现困难 | 跨系统流程编排 |
-| 定时任务 | 适合批量处理 | 有延迟 | 数据同步、报表生成 |
+返回值：
 
----
+- `List<CCObject>`
 
-## 五、典型业务场景
+适用场景：
 
-### 5.1 财务业绩管理（核心场景）
+- 简单单表查询
+- 普通对象查询
+- 共享对象查询
 
-```text
-订单 (Order)
-  └─ approval：审批判断
-预算 (Budget)
-  ├─ beforeUpsert：计算产研成本/净业绩
-  └─ afterUpsert：自动拆分/生成回款
-净业绩拆分 (jyjcf)
-  ├─ beforeUpsert：生成部门/个人业绩
-  └─ afterUpsert：校验金额累计是否超预算
-部门业绩 (bmyj)
-  ├─ afterUpsert：更新部门业绩字段
-  └─ afterUpdate：汇总部门资金池
-回款明细 (cloudccproceeddetail)
-  ├─ afterInsert：生成净业绩拆分回款
-  ├─ afterUpsert：金额汇总到收款计划
-  ├─ afterUpsert：更新回款明细
-  └─ afterDelete：回款明细删除
+AI 使用规则：
+
+- 简单查询优先 `cquery`
+- 自定义字段条件和排序都要加 `__c`
+- 条件为空会查全部数据，AI 应尽量避免
+
+#### 8.3.4 `cqlQuery`
+
+方法签名：
+
+```java
+public List<CCObject> cqlQuery(String apiName, String cql) throws Exception
 ```
 
-### 5.2 费用报销管理
+参数说明：
+
+| 参数      | 类型     | 是否必填 | 官方说明                        | AI 使用说明                                 |
+| --------- | -------- | -------- | ------------------------------- | ------------------------------------------- |
+| `apiName` | `String` | 是       | 对象 APIName                    | 必传主对象 API                              |
+| `cql`     | `String` | 否       | SQL 语句，支持常用 `where` 条件 | 适用于聚合、复杂过滤；避免无边界 `select *` |
+
+返回值：
+
+- `List<CCObject>`
+
+适用场景：
+
+- 聚合统计
+- 求和、计数、汇总
+- `cquery` 不足以表达的复杂查询
+
+AI 使用规则：
 
-```text
-费用报销提交
-  -> approval 触发器：验证审批时校验预算（报销金额 <= 预算余额）
-审批通过
-  -> approval 触发器：计算剩余欠款（借款 - 报销）
+- 能用 `cquery` 时优先不用 `cqlQuery`
+- 使用 `cqlQuery` 时必须写清过滤条件
+- 结果为空时必须做空值保护
+
+#### 8.3.5 `update`
+
+方法签名：
+
+```java
+public ServiceResult update(CCObject ccobj) throws Exception
 ```
 
-### 5.3 借款还款管理
+参数说明：
+
+| 参数    | 类型       | 是否必填 | 官方说明 | AI 使用说明           |
+| ------- | ---------- | -------- | -------- | --------------------- |
+| `ccobj` | `CCObject` | 是       | CC 对象  | 修改记录时必须带 `id` |
+
+返回值：
 
-| 触发器 | 对象 | 时机 | 作用 |
-|--------|------|------|------|
-| 借款单触发器 | 借款单 | beforeUpsert | 借款前校验、自动计算 |
-| 还款记录审批通过更新借款单 | 还款记录 | approval | 审批后回写借款单 |
+- `ServiceResult`
 
----
+适用场景：
 
-## 六、触发器开发最佳实践
+- 回写状态
+- 同步字段
+- 更新汇总结果
 
-### 6.1 代码规范
+AI 使用规则：
+
+- 必须先 `put("id", ...)`
+- 只更新必要字段
+- 优先评估递归触发风险
+
+#### 8.3.6 `delete`
+
+方法签名：
 
 ```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 ServiceResult delete(CCObject ccobj) throws Exception
+```
+
+参数说明：
+
+| 参数    | 类型       | 是否必填 | 官方说明 | AI 使用说明               |
+| ------- | ---------- | -------- | -------- | ------------------------- |
+| `ccobj` | `CCObject` | 是       | CC 对象  | 删除记录时通常必须带 `id` |
+
+返回值：
+
+- `ServiceResult`
+
+适用场景：
+
+- 删除派生记录
+- 删除中间记录
+- 服务端清理明确对象
+
+AI 使用规则：
+
+- 删除条件必须精准
+- 删除前后建议有日志
+- 涉及共享关系时优先看共享专用接口
+
+#### 8.3.7 `deleteShareObjectBySql`
+
+方法签名：
+
+```java
+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"
-);
+public Map getListCustomSetting(String objectApiName)
+Map map = cs.getListCustomSetting(String apiName, String Name)
+public Map getCustomSetting(String objectApiName, String id)
+```
+
+参数说明：
+
+| 方法                                                | 参数            | 类型     | 是否必填 | 官方说明           | 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 构造方法
 
-// 推荐：批量更新，降低递归风险
-cs.updateLt(records);
+方法签名：
+
+```java
+public SendEmail(UserInfo userInfo)
 ```
 
-### 6.3 避免递归触发
+参数说明：
+
+| 参数       | 类型       | 是否必填 | 官方说明 | AI 使用说明          |
+| ---------- | ---------- | -------- | -------- | -------------------- |
+| `userInfo` | `UserInfo` | 是       | 用户对象 | 用当前上下文发送邮件 |
+
+#### 8.4.2 `sendMailFromSystem`
+
+方法签名：
 
 ```java
-// 方法 1：使用 updateLt
-cs.updateLt(records);
+public boolean sendMailFromSystem(
+    String[] toAddress,
+    String[] ccAddress,
+    String[] bccAddress,
+    String subject,
+    String content,
+    boolean isText)
+```
 
-// 方法 2：增加标志位（示例）
-if ("true".equals(System.getProperty("trigger.running"))) {
-  return;
-}
-System.setProperty("trigger.running", "true");
-cs.update(record);
-System.setProperty("trigger.running", "false");
+参数说明：
+
+| 参数         | 类型       | 是否必填 | 官方说明                               | 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`
 
-### 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
-
-- [ ] 本地 `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 个触发器实例分析
+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 做规范数据操作
+- 用自定义类承接复杂逻辑
+- 用日志、幂等、时区和配置意识保证长期可维护