cloudcc-cli 2.3.8 → 2.4.0

package/src/classes/docs/devguide.md

@@ -1,541 +1,935 @@
-# CloudCC 自定义类开发指南
+# CloudCC 自定义类 AI 开发规范
 
-> 本文档参考 CloudCC
-> 官方「自定义类」文档整理而成：[自定义类](https://help.cloudcc.cn/product03/zi-ding-yi-lei/)。\
-> 目标：指导开发者在 CloudCC 平台上编写 Java 自定义类，熟练使用
-> `CCService`、`CCObject`、`SendEmail`、`DevLogger`、`TimeUtil`
-> 等工具类，并理解类在触发器、定时作业、自定义组件中的调用方式。
+## 1. 目的
 
----
+本文档用于指导 AI 在 CloudCC 项目中编写自定义类时，如何做出稳定、可维护、可发布的实现。
 
-## 0. 必须使用 CLI 管理本地类文件
+适用范围：
 
-自定义类在本项目中的目录结构、`config.json`、主类中的 `// @SOURCE_CONTENT_START`
-… `// @SOURCE_CONTENT_END` 区域，均与 **cloudcc-cli**
-的创建、发布、拉取逻辑绑定。**必须通过下列命令**
-完成新建目录、与服务器同步、发布与删除；不要手工新建
-`classes/<类名>/`、不要复制粘贴整套类文件夹、不要私自篡改 `config.json` 里的
-`id` 或破坏版本字段，否则容易导致发布失败、拉取覆盖异常或与线上一致性不一致。
+- 新建自定义类
+- 修改现有自定义类
+- 为按钮、触发器、定时类、自定义页面、组件提供后端能力
+- 编写通用服务类、工具类、集成类、流程编排类
 
-**允许的做法**：在 CLI 已生成的主类 `*.java` 中，仅在上述 SOURCE
-标记之间编写与修改业务代码；其余与平台同步相关的操作一律走命令。
+本文档面向 AI，因此重点强调：
 
-执行命令前请确认：已完成 `cloudcc doc project devguide`
-中的环境初始化，项目根目录配置可用且包含 `accessToken`。
+- 什么时候应该使用自定义类
+- AI 写代码时必须遵守哪些硬规则
+- SDK 该怎么用
+- 代码结构应该怎么组织
+- 哪些做法必须避免
 
-### 0.1 命令总览（以代码实现为准）
+## 2. 编写依据
+
+本文档基于以下材料整理：
+
+- CloudCC 官方后端 SDK 参考：`CCObject`、`UserInfo`、`CCService`、`SendEmail`、`DevLogger`、`TimeUtil`
+
+## 3. AI 的总体职责
+
+AI 在编写 CloudCC 自定义类时，应把自己视为“服务端业务能力设计者”，而不是“只补一段能跑代码的脚本工具”。
+
+AI 需要同时满足以下目标：
+
+- 功能正确
+- 结构清晰
+- 可复用
+- 易排错
+- 易发布
+
+## 4. 什么时候应该使用自定义类
+
+满足以下任一情况时，AI 应优先选择自定义类实现：
+
+- 逻辑需要在服务端执行
+- 一个动作会影响多个对象
+- 逻辑会被多个入口复用
+- 需要复杂规则计算
+- 需要流程状态推进
+- 需要调用外部系统
+- 需要处理附件、文件、目录
+- 需要统一日志、异常、时间处理
+- 需要自动通知、提醒、待办协同
+- 需要接入 AI 或分析能力
+
+以下场景不要优先上自定义类：
+
+- 只是简单展示
+- 只是轻量页面交互
+- 只是简单字段联动
+- 标准配置即可完成
+
+## 5. AI 必须遵守的硬规则
+
+### 5.1 只能通过 cloudcc-cli 管理类目录
+
+AI 不得手工创建或复制 `classes/<类名>/` 目录，不得私自改动 `config.json` 中的 `id` 或版本信息。
+
+必须使用以下命令：
 
 ```bash
 cloudcc create classes <name>
 cloudcc publish classes <name>
 cloudcc pull classes <name>
-cloudcc get classes [listQueryJson] [projectPath]
-cloudcc detail classes <name>
-cloudcc detail classes "" <id>
-cloudcc pullList classes <id> <projectPath>
-cloudcc delete classes <nameOrId> [projectPath]
-cloudcc doc classes <introduction|devguide>
+cloudcc delete classes <nameOrId>
 ```
 
-参数约定：
-
-- `name`：Java 类名，与 `classes/<name>/` 目录名一致。
-- `listQueryJson`：可选；列表查询条件的 JSON 经 `encodeURI(JSON.stringify(...))`
-  编码后传入。不传时使用默认分页参数。
-- `projectPath`：项目根路径，可选；不传则使用当前工作目录。
-- `id`：线上类 ID。`detail`
-  在仅查服务器时可将类名置空：`cloudcc detail classes "" <id>`。`pullList` 用 ID
-  将线上类落到指定项目的 `classes/` 下。
-- `nameOrId`：本地目录名，或类 ID。若本地存在 `config.json` 且含
-  `id`，删除时会优先用其中的服务器 ID。
-
-### 0.2 命令说明摘要
-
-| 命令       | 作用                                                                                |
-| ---------- | ----------------------------------------------------------------------------------- |
-| `create`   | 在 `classes/<name>/` 生成主类、测试类、`config.json` 模板                           |
-| `publish`  | 将本地 SOURCE 区域源码提交到服务器；首次成功后会写回 `config.json` 的 `id`          |
-| `pull`     | 按本地 `config.json` 的 `id` 从服务器拉取源码，覆盖主类中 SOURCE 区域（需已发布过） |
-| `get`      | 查询线上类列表（JSON 输出）                                                         |
-| `detail`   | 按类名优先读本地；或仅按 `id` 读服务器详情                                          |
-| `pullList` | 按类 `id` 将线上类拉取到指定 `projectPath` 下的 `classes/<类名>/`                   |
-| `delete`   | 调用接口删除服务器上的类；参数可为本地类名或类 ID                                   |
-| `doc`      | 输出 `introduction` 或 `devguide`（`devguide` 含附录 SDK 速查）                     |
-
-### 0.3 推荐操作顺序
+### 5.2 只能在 SOURCE 区域内写业务代码
 
-```bash
-# 1) 查看线上已有类（可选，避免重名或确认 ID）
-cloudcc get classes
+AI 修改现有类时，只能编辑主类中的：
 
-# 2) 新建类（仅通过 create 生成目录与文件）
-cloudcc create classes MyClass
+```java
+// @SOURCE_CONTENT_START
+// @SOURCE_CONTENT_END
+```
 
-# 3) 编辑 classes/MyClass/MyClass.java 中 SOURCE 区域后发布
-cloudcc publish classes MyClass
+之间的内容。
 
-# 4) 需要与服务器对齐时，拉取覆盖本地 SOURCE 区域
-cloudcc pull classes MyClass
+不得破坏：
 
-# 5) 按已知线上类 ID 拉到指定项目（迁移、批量）
-cloudcc pullList classes <线上类ID> <projectPath>
+- 包路径
+- 类目录结构
+- `config.json`
+- SOURCE 标记外的框架代码
 
-# 6) 不再使用时删除线上类
-cloudcc delete classes MyClass
-```
+### 5.3 必须保留 UserInfo 上下文
 
-### 0.4 文档子命令
+自定义类必须显式接收 `UserInfo`，并通过它构造平台能力对象。
 
-```bash
-cloudcc doc classes introduction
-cloudcc doc classes devguide
+标准写法：
+
+```java
+private UserInfo userInfo;
+private CCService cs;
+
+public XxxClass(UserInfo userInfo) {
+    this.userInfo = userInfo;
+    this.cs = new CCService(userInfo);
+}
 ```
 
-仅支持 `introduction` 与 `devguide`，其他子命令会报错。
+### 5.4 触发器、定时类、页面、按钮应做薄入口
 
----
+AI 不能把大量核心逻辑直接堆在按钮入口、触发器入口、页面接口入口中。
 
-## 1. 概念与使用场景
+推荐模式：
 
-### 1.1 什么是自定义类
+- 入口层只做参数接收、基础校验、结果返回
+- 复杂逻辑沉到服务方法或独立服务类
 
-- 自定义类本质上是运行在 CloudCC 平台上的 Java 类。
-- 可被以下模块调用：
-  - 自定义按钮
-  - 触发器
-  - 定时类 / 定时作业
-  - 自定义组件（通过 CCDK 请求自定义类）
-- 典型用途：
-  - 封装复杂业务逻辑
-  - 查询 / 写入对象数据
-  - 调用自定义设置、发送邮件、记录开发日志
+### 5.5 必须显式处理异常
 
-**注意**：调用 `CCService` 的方法时，需要对异常进行显式抛出或捕获。
+调用 `CCService` 等平台方法时，AI 不能默认“不会失败”。
 
-### 1.2 入口：进入类开发页面
+必须：
 
-1. 登录 CloudCC 系统
-2. 点击右上角头像，选择「开发者平台」（仅对管理员简档用户开放）
-3. 左侧菜单：`扩展 → 类`，进入类开发页面
+- 显式 `throws Exception` 或 `try/catch`
+- 在关键路径记录日志
+- 保留失败原因
+- 对外返回明确结果，而不是悄悄吞错
 
----
+### 5.6 涉及时间必须使用 TimeUtil
 
-## 2. 示例：查询客户对象数据（AccountClass）
+AI 编写代码时，凡是时间写库、时间比较、格式化、Calendar 处理，都不能默认直接用本地时区对象。
 
-下面是一个官方示例类：查询客户对象数据并返回 JSON。
+必须优先使用：
 
-```java
-import net.sf.json.JSONObject;
-import net.sf.json.JSONArray;
-import net.sf.json.JSON;
-
-/**
- * author：*** on 2022-10-12
- * 客户类
- */
-public class AccountClass {
-    private CCService cs;
-    private UserInfo userInfo;
-
-    public AccountClass(UserInfo userInfo) {
-        this.userInfo = userInfo;
-        cs = new CCService(userInfo);
-    }
+- `TimeUtil.getNowDate(userInfo)`
+- `TimeUtil.getUserTimeZone(userInfo)`
+- `TimeUtil.getSimpleDateFormat(format, userInfo)`
+- `TimeUtil.getCalendar(userInfo)`
 
-    public JSONObject selectAccount() throws Exception {
-        JSONObject rtninfo = new JSONObject(); // 返回结果
-        JSONArray dataList = new JSONArray();  // 数据列表
-        boolean flag = false;
-        try {
-            // 查询客户对象数据
-            String sql = "select name, leixing, fenji, hangye from Account where is_deleted='0' ";
-            List<CCObject> accountList = cs.cqlQuery("Account", sql);
-
-            for (int i = 0; i < accountList.size(); i++) {
-                String name = accountList.get(i).get("name") == null ? "" : accountList.get(i).get("name").toString();
-                String type = accountList.get(i).get("leixing") == null ? "" : accountList.get(i).get("leixing").toString();
-                String grade = accountList.get(i).get("fenji") == null ? "0" : accountList.get(i).get("fenji").toString();
-                String industry = accountList.get(i).get("hangye") == null ? "0" : accountList.get(i).get("hangye").toString();
-
-                JSONObject data = new JSONObject();
-                data.put("name", name);
-                data.put("type", type);
-                data.put("grade", grade);
-                data.put("industry", industry);
-                data.put("no", (i + 1) + ""); // 序号
-                dataList.add(data);
-            }
-            flag = true;
-        } catch (Exception e) {
-            throw e;
-        }
-        rtninfo.put("status", flag);
-        rtninfo.put("data", dataList.toString());
-        return rtninfo;
-    }
-}
-```
+禁止默认使用：
 
-要点：
+- `new Date()` 直接作为业务时间来源
+- `Calendar.getInstance()` 不带用户时区
+- `new SimpleDateFormat()` 后不设置时区
 
-- 构造函数接收 `UserInfo`，通过它实例化 `CCService`。
-- 查询结果使用 `CCObject` 列表封装，再转为 `JSONObject`/`JSONArray` 返回。
-- 方法签名抛出 `Exception`，调用方需要处理。
+## 6. SDK 详细参考与使用规范
 
----
+本节用于解决一个核心问题：
 
-## 3. CCService：对象数据读写核心
+- AI 不能只知道“该用哪个类”，还必须知道“这个 API 具体怎么调、参数是什么、哪些是官方明确说明的”。
 
-> `CCService` 是操作 CloudCC 对象（类似
-> ORM）的核心服务类，支持增删改查、自定义设置等。
+本节内容基于官方页面：
 
-### 3.1 在类中实例化 CCService
+使用原则：
 
-通用写法：
+- 只优先使用官方页面已明确给出签名和参数说明的 API
+- 如果官方页没有说明某个方法的参数或返回结构，AI 不得臆造
+- 遇到未文档化能力时，先参考当前仓库相邻类的现有写法，再决定是否使用
+- 对 `ServiceResult` 这类官方页只给出返回类型、但未完整说明字段结构的对象，AI 不得猜字段名；如果确需读取内部字段，必须先参考本项目已有代码模式
 
-```java
-public class DemoClass {
-    private CCService cs;
-    private UserInfo userInfo;
+### 6.1 CCObject 详细说明
 
-    public DemoClass(UserInfo userInfo) {
-        this.userInfo = userInfo;
-        this.cs = new CCService(userInfo);
-    }
-}
+`CCObject` 是 CloudCC 对象数据载体，继承自 `java.util.HashMap`，用于新增、更新、删除以及承载查询结果。
+
+#### 6.1.1 构造方法
+
+```java
+public CCObject()
+public CCObject(String ccobj)
+public CCObject(String ccobj, String isShared)
 ```
 
-在触发器中则通常不需要手动实例化，可直接使用平台提供的 `cs`（见触发器指南）。
+参数说明：
 
-### 3.2 新增记录：insert
+| 方法 | 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `CCObject(String ccobj)` | `ccobj` | `String` | 是 | 对象 APIName |
+| `CCObject(String ccobj, String isShared)` | `ccobj` | `String` | 是 | 对象 APIName |
+| `CCObject(String ccobj, String isShared)` | `isShared` | `String` | 是 | 共享标识，官方建议使用 `CCObject.IS_SHARED` |
 
-1. 通过 `CCObject` 构造要插入的记录
-2. 调用 `cs.insert(对象)` 持久化到数据库
+#### 6.1.2 常量字段
 
-```java
-// 构造一个数据对象，传入对象 API 名称
-CCObject opp = new CCObject("Opportunity");
+| 常量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `CCObject.OBJECT_API` | `CCObjectAPI` | 对象 API |
+| `CCObject.IS_SHARED` | `isShared` | 共享对象标识 |
 
-// 给 CCObject 赋值，key 为字段 API 名称
-opp.put("name", "新建机会");
-opp.put("jine__c", 10000); // 示例：金额字段
+#### 6.1.3 常用方法
 
-// 插入数据库
-cs.insert(opp);
+```java
+public String getObjectApiName()
+public String put(String apiName, String value)
 ```
 
-**注意**：ID、自动编号、创建人、创建时间等系统字段不需要也不应该手动赋值。
+参数说明：
+
+| 方法 | 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `put` | `apiName` | `String` | 是 | 字段 APIName |
+| `put` | `value` | `String` | 是 | 字段值 |
+
+AI 使用规则：
 
-### 3.3 查询记录：cquery
+- 新增或更新对象时优先使用 `new CCObject("ObjectApiName")`
+- 修改记录时必须写入 `id`
+- 字段赋值一律使用字段 APIName，不用字段显示名
+- 共享对象按官方方式传共享标识，不要自己拼魔法字符串
+- 官方页示例把 `put` 记为 `String` 参数；项目里也广泛传入数字、日期、布尔等对象。AI 如果不确定类型，优先参考同对象的现有项目代码，不要自行猜测
 
-`cquery` 提供多种重载，用于按条件和排序查询数据。
+### 6.2 UserInfo 详细说明
 
-- 返回对象全部记录：
+`UserInfo` 是当前登录用户上下文对象，是构造 `CCService`、`SendEmail`、`DevLogger`、`TimeUtil` 的基础。
+
+#### 6.2.1 构造方法
 
 ```java
-List<CCObject> opps = cs.cquery("Opportunity");
+public UserInfo()
 ```
 
-- 按条件查询（where 表达式）：
+#### 6.2.2 官方页明确列出的常用方法
 
 ```java
-List<CCObject> opps = cs.cquery(
-    "Opportunity",
-    "khmc__c = '" + record_new.get("id") + "'"
-);
+public String getUserId()
+public String getOrgId()
+public String getRoleId()
 ```
 
-- 按条件 + 排序：
+参数说明：
+
+| 方法 | 入参 | 返回 | 说明 |
+| --- | --- | --- | --- |
+| `getUserId` | 无 | `String` | 当前用户 ID，未设置时返回 `null` |
+| `getOrgId` | 无 | `String` | 当前组织 ID，未设置时返回 `null` |
+| `getRoleId` | 无 | `String` | 当前角色 ID，未设置时返回 `null` |
+
+AI 使用规则：
+
+- 所有服务端类都应把 `UserInfo` 当作基础上下文
+- 不要自己构造“当前用户”概念
+- 不要使用硬编码用户替代 `UserInfo`
+- 如果需要官方页未列出的 `UserInfo` 方法，先去当前仓库搜索已有用法，再决定是否复用
+
+### 6.3 CCService 详细说明
+
+`CCService` 是 CloudCC 服务端核心工具类，负责增删改查、自定义设置等核心能力。
+
+#### 6.3.1 构造函数
 
 ```java
-List<CCObject> opps = cs.cquery(
-    "Opportunity",
-    "khmc__c = '" + record_new.get("id") + "'",
-    "jine__c desc"
-);
+public CCService(UserInfo userInfo)
 ```
 
-**注意**：条件与排序中的自定义字段 API 名称要加 `__c` 后缀。
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `userInfo` | `UserInfo` | 是 | 当前用户对象 |
 
-### 3.4 修改记录：update
+#### 6.3.2 insert
 
 ```java
-// 先查询到目标记录
-List<CCObject> list = cs.cquery("Opportunity", "id = '" + record_id + "'");
-if (!list.isEmpty()) {
-    CCObject opp = list.get(0);
-    opp.put("name", "修改后的机会名称");
-    cs.update(opp);
-}
+public ServiceResult insert(CCObject ccobj) throws BusiException
 ```
 
-### 3.5 删除记录：delete
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `ccobj` | `CCObject` | 是 | 待新增的对象数据 |
+
+返回说明：
+
+- 返回 `ServiceResult`
+- 官方页未完整展开 `ServiceResult` 字段结构
+
+AI 使用规则：
+
+- 用于单条新增
+- 新增前补齐必填字段
+- 不要默认插入一定成功
+- 若需要读取 `ServiceResult` 内部字段，必须先参考当前项目现有写法，不得猜字段名
+
+#### 6.3.3 cquery
+
+官方页给出两个重载。
 
 ```java
-List<CCObject> list = cs.cquery("Opportunity", "id = '" + record_id + "'");
-if (!list.isEmpty()) {
-    CCObject opp = list.get(0);
-    cs.delete(opp);
-}
+public List<CCObject> cquery(String apiName, String condtion, String order) throws Exception
+public List<CCObject> cquery(String apiName, String condtion, boolean isDataObject) throws Exception
 ```
 
-### 3.6 操作共享表
+参数说明：
+
+| 方法 | 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `cquery(apiName, condtion, order)` | `apiName` | `String` | 是 | 对象 APIName |
+| `cquery(apiName, condtion, order)` | `condtion` | `String` | 否 | 查询条件；官方说明使用字段 APIName，自定义字段要加 `__c` |
+| `cquery(apiName, condtion, order)` | `order` | `String` | 否 | 排序字段；自定义字段要加 `__c` |
+| `cquery(apiName, condtion, isDataObject)` | `apiName` | `String` | 是 | 对象 APIName |
+| `cquery(apiName, condtion, isDataObject)` | `condtion` | `String` | 否 | 查询条件；自定义字段要加 `__c` |
+| `cquery(apiName, condtion, isDataObject)` | `isDataObject` | `boolean` | 否 | `true` 查询普通数据，`false` 查询共享数据 |
+
+返回说明：
+
+- 返回 `List<CCObject>`
+
+AI 使用规则：
+
+- 简单单表查询优先 `cquery`
+- 条件和排序统一使用字段 APIName
+- 自定义字段按官方要求补 `__c`
+- 不要无条件全表扫描
+- 当需求明确查询共享数据时，才使用带 `isDataObject` 的重载
 
-#### 查询共享表
+#### 6.3.4 cqlQuery
 
 ```java
-// isDataObject 传 false，表示查询共享表
-List<CCObject> shares = cs.cquery(
-    "Opportunity",
-    "userid = '" + userId + "'",
-    false
-);
+public List<CCObject> cqlQuery(String apiName, String cql) throws Exception
 ```
 
-#### 删除共享表记录
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `apiName` | `String` | 是 | 对象 APIName |
+| `cql` | `String` | 否 | SQL/CQL 语句，官方说明支持常用 where 条件 |
+
+返回说明：
+
+- 返回 `List<CCObject>`
+
+AI 使用规则：
+
+- 聚合、join、复杂筛选时再用 `cqlQuery`
+- 尽量只查需要的字段，不要默认 `select *`
+- 必须收窄 where 条件
+- 复杂 SQL 要保持可读性和可维护性
+
+#### 6.3.5 update
 
 ```java
-cs.deleteShareObjectBySql("Opportunity", "userid = '" + userId + "'");
+public ServiceResult update(CCObject ccobj) throws Exception
 ```
 
-**注意**：共享表中表达式里的字段 **不需要加 `__c` 后缀**。
+参数说明：
 
-### 3.7 自定义设置（CustomSetting）
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `ccobj` | `CCObject` | 是 | 待更新对象 |
 
-#### 列表类型自定义设置（List）
+返回说明：
 
-- 返回某个 API 名称下的全部数据：
+- 返回 `ServiceResult`
+- 官方页未完整展开 `ServiceResult` 字段结构
+
+AI 使用规则：
+
+- 更新前必须带 `id`
+- 只更新必要字段，避免无意义全量覆盖
+- 更新动作应和状态校验绑定
+
+#### 6.3.6 delete
 
 ```java
-Map listSettings = cs.getListCustomSetting("MyListSettingApiName");
+public ServiceResult delete(CCObject ccobj) throws Exception
 ```
 
-- 返回指定 `Name` 的单条数据：
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `ccobj` | `CCObject` | 是 | 待删除对象，通常至少包含 `id` |
+
+返回说明：
+
+- 返回 `ServiceResult`
+
+AI 使用规则：
+
+- 删除前必须确认条件准确
+- 删除前后最好有日志
+- 删除共享关系时优先使用共享专用能力，不要混用普通删除
+
+#### 6.3.7 deleteShareObjectBySql
 
 ```java
-Map singleSetting = cs.getListCustomSetting("MyListSettingApiName", "SomeName");
+public void deleteShareObjectBySql(String objectApiName, String expression) throws Exception
 ```
 
-#### 层次结构类型自定义设置（Hierarchy）
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `objectApiName` | `String` | 是 | 对象 APIName |
+| `expression` | `String` | 是 | SQL 表达式；官方说明这里字段不需要加 `__c` |
+
+AI 使用规则：
+
+- 仅用于共享关系删除
+- 普通对象删除不要误用这个接口
+- 注意这里的字段规则和 `cquery` 条件规则不同
+
+#### 6.3.8 自定义设置相关方法
+
+官方页列出了 3 类常用能力。
 
 ```java
-// id 为简档 ID 或用户 ID
-Map hiSetting = cs.getCustomSetting("MyHierarchySettingApiName", profileOrUserId);
+public Map getListCustomSetting(String objectApiName)
+public Map getListCustomSetting(String apiName, String name)
+public Map getCustomSetting(String objectApiName, String id)
 ```
 
----
+参数说明：
+
+| 方法 | 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `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 使用规则：
+
+- 外部系统地址、业务开关、阈值、角色映射、模板号优先配置化
+- 不要把可配置项直接写死在代码里
 
-## 4. 常用工具类
+### 6.4 SendEmail 详细说明
 
-### 4.1 SendEmail：发送邮件
+`SendEmail` 用于发送邮件通知。
+
+#### 6.4.1 构造方法
 
 ```java
-SendEmail sendEmail = new SendEmail(userInfo);
-sendEmail.sendMailFromSystem(
-    new String[]{"to@example.com"},     // 收件人
-    new String[]{"cc@example.com"},     // 抄送
-    new String[]{"bcc@example.com"},    // 密送
-    "邮件主题",
-    "邮件内容",
-    true                                // 是否纯文本
-);
+public SendEmail(UserInfo userInfo)
 ```
 
-### 4.2 DevLogger：开发日志
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `userInfo` | `UserInfo` | 是 | 当前用户对象 |
 
-> 用于在自定义类中记录开发日志，便于排查问题。
+#### 6.4.2 sendMailFromSystem
 
 ```java
-// 初始化日志类
-DevLogger cclogger = new DevLogger(userInfo);
+public boolean sendMailFromSystem(
+    String[] toAddress,
+    String[] ccAddress,
+    String[] bccAddress,
+    String subject,
+    String content,
+    boolean isText
+)
+```
 
-// 打印 info 级别日志
-cclogger.devLogInfo("这是 info 日志");
+参数说明：
 
-// 打印 error 级别日志
-cclogger.devLogError("这是 error 日志");
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `toAddress` | `String[]` | 是 | 收件人数组 |
+| `ccAddress` | `String[]` | 是 | 抄送人数组 |
+| `bccAddress` | `String[]` | 是 | 密送人数组 |
+| `subject` | `String` | 是 | 邮件标题 |
+| `content` | `String` | 是 | 邮件正文 |
+| `isText` | `boolean` | 是 | `false` 表示 HTML 邮件，`true` 表示纯文本 |
 
-// 打印异常堆栈
-try {
-    // 业务逻辑
-} catch (Exception e) {
-    cclogger.devLogError("发生异常", e);
-    throw e;
-}
-```
+返回说明：
+
+- 返回 `boolean`
 
-### 4.3 TimeUtil：多时区日期时间
+AI 使用规则：
 
-> 为保证跨时区时间的准确性，推荐使用 `TimeUtil` 获取当前时间与时间格式化工具。
+- 无抄送/密送时传空数组，不要盲目传 `null`
+- HTML 邮件时 `isText=false`
+- 发信动作应建立在业务动作成功之后
 
-- 获取当前时间（根据用户时区）：
+#### 6.4.3 sendEmailNew
 
 ```java
-TpSysTask task = new TpSysTask();
-task.setBeginTime(TimeUtil.getNowDate(userInfo));
+public ServiceResult sendEmailNew(
+    String emailtemplateid,
+    String[] toaddress,
+    String[] ccaddress,
+    String[] bcaddress,
+    String id
+) throws Exception
 ```
 
-- 使用 `SimpleDateFormat` 时设置时区：
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `emailtemplateid` | `String` | 是 | 邮件模板 ID |
+| `toaddress` | `String[]` | 是 | 收件人数组 |
+| `ccaddress` | `String[]` | 是 | 抄送人数组 |
+| `bcaddress` | `String[]` | 是 | 密送人数组 |
+| `id` | `String` | 是 | 业务记录 ID，通常用于模板数据填充 |
+
+返回说明：
+
+- 返回 `ServiceResult`
+
+AI 使用规则：
+
+- 模板邮件优先用这个接口
+- 模板 ID 不要硬编码，优先配置化
+- 如需解析 `ServiceResult`，先参考现有项目代码，不要自行猜字段
+
+### 6.5 DevLogger 详细说明
+
+`DevLogger` 用于运行日志采集。
+
+#### 6.5.1 构造函数
 
 ```java
-SimpleDateFormat myDateFormat = new SimpleDateFormat("yyyy-MM-dd");
-myDateFormat.setTimeZone(TimeUtil.getUserTimeZone(userInfo));
+public DevLogger(UserInfo userInfo)
 ```
 
-- 使用工具方法直接获取带时区的 `SimpleDateFormat`：
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `userInfo` | `UserInfo` | 是 | 当前用户对象 |
+
+#### 6.5.2 devLogInfo
 
 ```java
-SimpleDateFormat myDateFormat =
-    TimeUtil.getSimpleDateFormat("yyyy-MM-dd", userInfo);
+public void devLogInfo(String info)
 ```
 
-- 使用 `Calendar` 时设置时区：
+参数说明：
 
-```java
-// 方式一
-Calendar cal = Calendar.getInstance(TimeUtil.getUserTimeZone(userInfo));
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `info` | `String` | 是 | info 级别日志内容 |
 
-// 方式二（推荐使用工具方法）
-Calendar cal2 = TimeUtil.getCalendar(userInfo);
+#### 6.5.3 devLogError
+
+```java
+public void devLogError(String error, Throwable throwable)
 ```
 
-### 4.4 CCObject：数据载体
+参数说明：
 
-```java
-// 构造一个数据对象，传入对象 API 名称
-CCObject opp = new CCObject("Opportunity");
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `error` | `String` | 是 | 错误日志内容 |
+| `throwable` | `Throwable` | 否 | 异常对象 |
 
-// 构造一个共享表对象
-CCObject oppshare = new CCObject("Opportunity", CCObject.IS_SHARED);
+AI 使用规则：
 
-// 赋值
-opp.put("name", "value");
-```
+- 方法入口要记录
+- 关键业务 ID 要记录
+- 外部调用前后要记录
+- 异常必须记录
+- 不要只写无意义日志
+
+### 6.6 TimeUtil 详细说明
 
----
+`TimeUtil` 用于解决跨时区数据处理问题。官方页明确说明：涉及时间写库与比较时，不应直接依赖本地时区的 `Date` 与 `Calendar`。
 
-## 5. 自定义类与其他模块的配合
+#### 6.6.1 getNowDate
 
-### 5.1 触发器中使用类
+```java
+TimeUtil.getNowDate(userInfo)
+```
 
-- 触发器可以直接调用自定义类中的方法，也可以直接使用 `CCService`。
-- 触发器由 CloudCC 平台动态编译，调用写法与普通 Java 方法调用类似。
-- 典型模式：
-  - 在触发器中只做入口和参数准备
-  - 将复杂逻辑委托给自定义类方法
+参数说明：
 
-（触发器具体语法与最佳实践详见 `custom-trigger-dev.md`。）
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `userInfo` | `UserInfo` | 是 | 当前用户对象 |
 
-### 5.2 自定义类调用其他自定义类（PageClsInvoker）
+返回说明：
 
-> 当需要在一个自定义类中调用另一个自定义类的方法时，可使用 `PageClsInvoker` 的
-> `invoker` 方法。
+- 返回按用户时区获取的当前时间
 
-`invoker` 有两个常用重载：
+#### 6.6.2 getUserTimeZone
 
 ```java
-Object invoker(String className, String method, List<Map> conlist, List<Map> arglist);
-Object invoker(String className, String method, List<Map> conlist, Map map);
+TimeUtil.getUserTimeZone(userInfo)
 ```
 
 参数说明：
 
-- `className`：目标自定义类名称
-- `method`：要调用的方法名
-- `conlist`：构造器参数列表（可为 `null`）
-  - 每个 Map 包含：
-    - `argType`：参数类型
-    - `argValue`：参数值
-- `arglist` / `map`：方法参数
-  - 同样包含 `argType` 和 `argValue`
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `userInfo` | `UserInfo` | 是 | 当前用户对象 |
 
-#### 5.2.1 使用 Map 作为方法参数
+返回说明：
 
-目标类：
+- 返回用户时区对象
+
+#### 6.6.3 getSimpleDateFormat
 
 ```java
-public class Hello {
+TimeUtil.getSimpleDateFormat(format, userInfo)
+```
 
-    public Hello() {}
+参数说明：
 
-    public Hello(UserInfo userInfo) {
-        System.out.print("测试");
-    }
+| 参数 | 类型 | 必填 | 默认值 | 说明 |
+| --- | --- | --- | --- | --- |
+| `format` | `String` | 是 | `yyyy-MM-dd` | 格式化模板 |
+| `userInfo` | `UserInfo` | 是 | - | 当前用户对象 |
 
-    public void test5(Map map) throws Exception {
-        System.out.print("获取 map 中的值" + map.get("name"));
-    }
-}
-```
+返回说明：
+
+- 返回带用户时区的 `SimpleDateFormat`
 
-调用方：
+#### 6.6.4 Calendar 获取方式
+
+官方页给出两种方式：
 
 ```java
-List<Map> conlist = new ArrayList<Map>();
+Calendar cal = Calendar.getInstance(TimeUtil.getUserTimeZone(userInfo));
+Calendar cal = TimeUtil.getCalendar(userInfo);
+```
 
-Map c = new HashMap();
-c.put("argType", UserInfo.class);
-c.put("argValue", userInfo);
-conlist.add(c);
+AI 使用规则：
 
-Map m = new HashMap();
-m.put("name", "Alex");
+- 只要涉及时间写库、比较、提醒、截止、统计，一律优先 `TimeUtil`
+- 禁止默认用 `new Date()` 或不带时区的 `Calendar`
 
-new PageClsInvoker(userInfo).invoker("Hello", "test5", conlist, m);
-```
+### 6.7 AI 不得猜测的 SDK 内容
+
+以下内容如果官方页没有明确说明，AI 不得自己编：
+
+- 未在官方页列出的 SDK 方法名
+- 未文档化的参数顺序
+- `ServiceResult` 的内部字段结构
+- 未确认的 `UserInfo` 扩展方法
+- 外部能力类的构造方法和返回值
+
+正确做法：
+
+1. 先查官方文档
+2. 再查当前仓库已有同类实现
+3. 仍不确定时，不生成“看起来像真的”代码
+
+## 7. 代码结构规范
+
+### 7.1 分层建议
+
+AI 编写自定义类时，优先按职责分层：
+
+- `Controller`：入口编排、参数接收、结果返回
+- `Service`：核心业务逻辑
+- `Util/Utils`：通用工具、通用查询、通用转换
+- `Client`：外部系统调用封装
+- `Handler`：触发器或事件逻辑下沉层
+
+如果项目已有既定命名习惯，优先跟随相邻模块命名。
+
+### 7.2 方法粒度
+
+AI 不应默认把所有逻辑塞进一个超长方法。
+
+推荐拆分：
+
+- `validateXxx`
+- `queryXxx`
+- `calculateXxx`
+- `updateXxx`
+- `sendXxx`
+- `buildXxxResult`
+
+原则：
+
+- 一个方法只负责一类动作
+- 复杂编排方法负责串联，不负责所有细节
+
+### 7.3 返回值规范
+
+AI 需要根据调用场景选择返回值类型：
+
+- 页面/按钮/组件接口：优先 `JSONObject`、`Map` 或稳定结构对象
+- 内部服务方法：优先返回明确业务结果
+- 仅做写操作的方法：可返回 `void`，但必须通过异常或日志暴露失败
+
+规则：
+
+- 返回值结构要稳定
+- 不要同一方法一会儿返回字符串、一会儿返回对象
+- 对外接口最好带成功标识和错误信息
+
+## 8. 数据与查询规范
+
+### 8.1 字段名统一使用 API 名称
+
+AI 不得使用字段显示名直接拼查询条件。
+
+必须：
+
+- 使用对象 APIName
+- 使用字段 APIName
+- 自定义字段按文档规则补 `__c`
+
+### 8.2 查询要收敛
+
+AI 默认应避免：
+
+- 无条件全表查询
+- 无限制 `select *`
+- 在循环里反复查同一批数据
+
+应优先：
+
+- 一次查够
+- 只查必要字段
+- 提前构造索引或映射
+- 把批量处理合并到同一逻辑块
+
+### 8.3 写操作要可回溯
 
-#### 5.2.2 使用 List<Map> 作为方法参数列表
+涉及新增、更新、删除时：
 
-目标类：
+- 要明确主键或条件
+- 要记录关键业务键
+- 要尽量保证幂等
+- 要避免重复插入
+
+## 9. 外部集成规范
+
+AI 编写集成类时，必须把外部系统调用与业务逻辑适度隔离。
+
+规则：
+
+- 接口地址、密钥、系统标识优先配置化
+- 不要在多个业务方法中重复拼接 URL
+- 外部调用前后必须记录日志
+- 调用失败要保留错误上下文
+- 文件上传、下载、同步逻辑要单独封装
+
+推荐模式：
+
+- `Client` 负责调用外部接口
+- `Service` 负责业务编排
+- `Controller` 负责入口输出
+
+## 10. 通知与协同规范
+
+AI 编写通知能力时，应遵循：
+
+- 先完成业务动作，再触发通知
+- 通知内容应基于真实业务结果生成
+- 收件人/待办对象来源应可追溯
+- 同一动作不要重复发送
+
+如果通知逻辑复杂：
+
+- 单独提取通知方法
+- 不要把大段 HTML 拼接散落到多处
+
+## 11. 权限与共享规范
+
+AI 处理权限相关需求时，应优先使用服务端判断，而不是把关键限制交给前端。
+
+规则：
+
+- 角色判断放服务端
+- 审批权限放服务端
+- 共享写入放服务端
+- 删除共享关系要使用正确接口
+
+当需求和共享、角色、负责人变化相关时，AI 应主动考虑：
+
+- 是否要补共享
+- 是否要删旧共享
+- 是否要校验当前用户是否有权执行
+
+## 12. 异常与日志规范
+
+AI 写代码时必须假设以下事情都可能失败：
+
+- 查询为空
+- 字段为空
+- 配置缺失
+- 外部接口超时
+- 文件不存在
+- 写操作失败
+- 状态不满足前置条件
+
+因此必须：
+
+- 对空值做保护
+- 对异常做显式处理
+- 对关键节点打日志
+- 对外返回明确错误
+
+不允许：
+
+- 空 `catch`
+- 吞异常后继续假装成功
+- 失败时只返回 `false` 而不给任何上下文
+
+## 13. 命名规范
+
+优先遵循以下模式：
+
+- `XxxController`：入口编排类
+- `XxxService`：核心业务服务类
+- `XxxUtil` / `XxxUtils`：通用工具类
+- `XxxClient`：外部系统客户端
+- `XxxHandler`：触发逻辑处理类
+
+方法命名优先使用动词开头：
+
+- `queryXxx`
+- `createXxx`
+- `updateXxx`
+- `deleteXxx`
+- `sendXxx`
+- `calculateXxx`
+- `buildXxx`
+
+## 14. AI 禁止事项
+
+AI 不得：
+
+- 手工新建 `classes/<类名>/` 目录
+- 修改 `config.json` 的 `id` 或版本字段
+- 在 SOURCE 区域外写业务代码
+- 默认使用 `new Date()` 作为业务时间
+- 使用字段显示名代替 API 名称
+- 无条件全量查询大对象
+- 将关键逻辑全部堆在入口方法里
+- 在多个地方复制同样的外部接口调用代码
+- 把地址、角色、阈值、模板 ID 等全部硬编码
+- 吞异常不报错
+- 只写“成功/失败”而没有上下文日志
+
+## 15. AI 生成代码前的检查清单
+
+在开始写代码前，AI 应先确认：
+
+1. 这是页面/按钮/触发器/定时类/组件中的哪一种入口
+2. 这段逻辑是否真的应该放到自定义类
+3. 会影响哪些对象
+4. 是否需要外部系统调用
+5. 是否需要附件或文件处理
+6. 是否涉及时区
+7. 是否涉及权限、共享或审批
+8. 哪些参数适合配置化而不是硬编码
+
+## 16. AI 交付前的自检清单
+
+AI 完成代码后，必须自检：
+
+1. 是否只修改了 SOURCE 区域
+2. 是否保留了 `UserInfo` + `CCService`
+3. 是否正确使用对象/字段 API 名称
+4. 是否优先使用了 `cquery` / `cqlQuery` 的正确场景
+5. 是否对写操作做了失败处理
+6. 是否对关键步骤加了日志
+7. 是否避免了直接 `new Date()`
+8. 是否把复杂逻辑拆成了可读的方法
+9. 是否避免了不必要硬编码
+10. 是否让返回结果对调用方足够清晰
+
+## 17. 推荐骨架
+
+下面是一个适合 AI 生成新类时参考的通用骨架：
 
 ```java
-public class Hello {
+import com.cloudcc.core.*;
+import net.sf.json.JSONObject;
+import java.util.List;
 
-    public Hello() {}
+public class XxxService {
+    private final UserInfo userInfo;
+    private final CCService cs;
+    private final DevLogger logger;
 
-    public ServiceResult test3(UserInfo userInfo, String leadName) throws Exception {
-        CCService cs = new CCService((UserInfo) userInfo);
-        CCObject co = new CCObject("Lead");
-        co.put("name", leadName);
-        ServiceResult sr = cs.insert(co);
-        return sr;
+    public XxxService(UserInfo userInfo) {
+        this.userInfo = userInfo;
+        this.cs = new CCService(userInfo);
+        this.logger = new DevLogger(userInfo);
     }
-}
-```
 
-调用方：
+    public JSONObject execute(String recordId) throws Exception {
+        JSONObject result = new JSONObject();
+        logger.devLogInfo("XxxService.execute start, recordId=" + recordId);
+        try {
+            validate(recordId);
 
-```java
-List<Map> arglist = new ArrayList<Map>();
+            List<CCObject> records = queryData(recordId);
+            JSONObject calcResult = calculate(records);
+            updateData(recordId, calcResult);
 
-Map u = new HashMap();
-u.put("argType", UserInfo.class);
-u.put("argValue", userInfo);
-arglist.add(u);
+            result.put("success", true);
+            result.put("data", calcResult);
+            logger.devLogInfo("XxxService.execute success, recordId=" + recordId);
+            return result;
+        } catch (Exception e) {
+            logger.devLogError("XxxService.execute failed, recordId=" + recordId, e);
+            throw e;
+        }
+    }
 
-Map n = new HashMap();
-n.put("argType", String.class);
-n.put("argValue", "Alex");
-arglist.add(n);
+    private void validate(String recordId) throws Exception {
+        if (recordId == null || "".equals(recordId.trim())) {
+            throw new Exception("recordId is required");
+        }
+    }
 
-new PageClsInvoker(userInfo).invoker("Hello", "test3", null, arglist);
+    private List<CCObject> queryData(String recordId) throws Exception {
+        return cs.cquery("ObjectApiName", "id = '" + recordId + "'", null);
+    }
+
+    private JSONObject calculate(List<CCObject> records) {
+        JSONObject result = new JSONObject();
+        result.put("count", records == null ? 0 : records.size());
+        return result;
+    }
+
+    private void updateData(String recordId, JSONObject calcResult) throws Exception {
+        CCObject obj = new CCObject("ObjectApiName");
+        obj.put("id", recordId);
+        obj.put("last_execute_time", TimeUtil.getNowDate(userInfo));
+        cs.update(obj);
+    }
+}
 ```
 
----
-
-## 6. 自定义类开发 Checklist
-
-- [ ] 类目录与平台同步仅通过 `cloudcc create` / `cloudcc pull` / `cloudcc pullList` /
-      `cloudcc publish` / `cloudcc delete` 等命令操作，不手工造目录或改 `config.json` 的
-      `id`
-- [ ] 类名、方法名与调用方（按钮/触发器/组件/定时作业）约定一致
-- [ ] 构造函数正确接收 `UserInfo` 并实例化 `CCService` 等依赖
-- [ ] 所有 `CCService` 操作（`insert`/`update`/`delete`/`cquery`）使用正确的对象
-      API 名称和字段 API 名称（自定义字段加 `__c`）
-- [ ] 访问共享表时，表达式中的字段未错误地添加 `__c` 后缀
-- [ ] 涉及时间处理的逻辑统一使用 `TimeUtil`，避免时区问题
-- [ ] 异常统一捕获并按需抛出，同时使用 `DevLogger` 记录关键错误信息
-- [ ] 使用 `SendEmail` 时确认收件地址与内容来源安全可靠
-- [ ] 使用 `PageClsInvoker` 跨类调用时，`argType` 与 `argValue` 类型匹配
-- [ ] 对外暴露的方法返回结构（如
-      `JSONObject`）与前端/调用方约定一致，字段清晰、语义明确
+## 18. 一句话结论
+
+AI 编写 CloudCC 自定义类时，最重要的不是“把需求翻译成几段 Java”，而是遵守 CloudCC 的类管理方式、正确使用 SDK、把复杂逻辑放在服务端可治理的位置，并让代码具备复用性、可追踪性和可发布性。