cloudcc-cli 2.3.8 → 2.4.0

package/src/timer/docs/devguide.md

@@ -1,554 +1,1003 @@
-# CloudCC 定时作业完全指南
+# CloudCC 定时器类 AI 开发规范
 
-> 定时作业（Scheduled Jobs）是 CloudCC CRM 系统中的后台任务调度机制，用于在指定时间自动执行业务逻辑。
+## 1. 文档目的
 
----
+本文用于约束 AI 在当前 CloudCC 项目中编写定时器类时的分析方式、实现方式、SDK 选型和输出要求。
 
-## CLI 与本地文件（必读）
+目标不是让 AI “能写出代码”即可，而是让 AI 写出的定时器类：
 
-本仓库中的**定时类**（与定时作业绑定的 Java 类）通过 **cloudcc-cli** 与平台同步，本地目录为 **`schedule/<类名>/`**（内含 `*.java` 与 `config.json`），源码中的 `// @SOURCE_CONTENT_START` … `// @SOURCE_CONTENT_END` 与发布、拉取逻辑一致。**必须通过下列命令** 完成新建目录、发布、拉取与删除；不要手工新建 `schedule/` 子目录、不要整包复制其他项目的定时类、不要私自篡改 `config.json` 中的 `id` 或版本字段。
+- 适合放在定时器而不是触发器或页面脚本中
+- 符合 CloudCC 官方 SDK 用法
+- 符合 `cloudcc-cli` 的目录和发布约束
+- 符合当前项目的主流实现模式
+- 具备幂等性、可观测性、批量处理意识和时区安全意识
 
-**允许的做法**：在 CLI 已生成的主类中，仅在上述 SOURCE 标记之间编写业务逻辑；与云端列表、详情、拉取、删除、发布相关的操作一律走命令。
+## 2. 依据来源
 
-执行命令前请确认：已完成 `cloudcc doc project devguide` 中的环境初始化，项目根目录配置可用且包含 `accessToken`。
+- 官方 SDK 文档提供 `CCObject`、`CCService`、`SendEmail`、`DevLogger`、`TimeUtil` 等核心 API 依据
+- `2-timer-classes-analysis.md` 提供当前项目定时器使用场景和共性模式
+- `timer devguide` 提供本地目录、CLI、发布和 SOURCE 区域约束
 
-### 命令总览（以代码实现为准）
+## 3. 先判断：是不是应该写成定时器类
 
-```bash
-cloudcc create timer <name>
-cloudcc publish timer <name>
-cloudcc pull timer <name>
-cloudcc get timer [listQueryJson] [projectPath]
-cloudcc detail timer <name>
-cloudcc detail timer "" <id>
-cloudcc pullList timer <id> <projectPath>
-cloudcc delete timer <nameOrId> [projectPath]
-cloudcc doc timer <introduction|devguide>
-```
+AI 在动手写代码前，必须先判断需求是否真的适合用定时器类。
 
-参数约定：
+### 3.1 适合定时器类的情况
 
-- `name`：定时类名，与 `schedule/<name>/` 目录名一致。
-- `listQueryJson`：可选；列表查询 JSON 经 `encodeURI(JSON.stringify(...))` 编码后传入；不传则使用默认分页参数。
-- `projectPath`：项目根路径，可选。
-- `id`：线上定时类 ID。`detail` 仅查服务器时：`cloudcc detail timer "" <id>`。`pullList` 必填。
-- `nameOrId`：本地目录名或类 ID；若本地 `config.json` 含 `id`，删除时优先使用该 ID。
+- 任务按时间触发，而不是按单条记录实时触发
+- 需要每天、每周、每月、月初、月末执行
+- 需要批量扫描一批记录并统一处理
+- 需要失败补偿、周期重试或后台巡检
+- 需要构建底表、看板、台账、报表支撑数据
+- 需要在满足条件后自动提醒、自动推进、自动同步
 
-### 命令作用摘要
+### 3.2 不适合定时器类的情况
 
-| 命令 | 作用 |
-|------|------|
-| `create` | 在 `schedule/<name>/` 生成继承 `CCSchedule` 的 Java 模板与 `config.json` |
-| `publish` | 将 SOURCE 区域提交到服务器；首次成功后可写回 `config.json` 的 `id` |
-| `pull` | 按本地 `id` 拉取远端源码，覆盖主类中 SOURCE 区域（需已发布） |
-| `get` | 查询线上定时类列表（JSON 输出） |
-| `detail` | 按类名优先读本地；或仅按 `id` 读服务器 |
-| `pullList` | 按类 `id` 将线上定时类落到指定项目的 `schedule/<类名>/` |
-| `delete` | 删除服务器上的定时类 |
-| `doc` | 输出模块文档；`devguide` 含附录后端 Java SDK 速查 |
+- 记录保存时必须立刻校验或立刻拦截
+- 单笔数据变化后必须在同一事务里马上联动
+- 高度依赖前端交互、人工确认、页面反馈
+- 只是一次性临时数据处理，不需要长期调度
 
-### 推荐操作顺序
+### 3.3 当前项目中定时器的六大主类型
 
-```bash
-# 1) 查看线上已有定时类（可选）
-cloudcc get timer
+根据现有项目总结，AI 应优先将需求归入以下类型之一：
 
-# 2) 新建定时类（仅通过 create 生成目录与模板）
-cloudcc create timer MySchedule
+- 提醒通知类
+- 同步推送集成类
+- 刷新更新修正类
+- 报表底表支撑类
+- 自动生成派生类
+- 权限共享治理类
 
-# 3) 编辑 schedule/MySchedule/MySchedule.java 中 SOURCE 区域后发布
-cloudcc publish timer MySchedule
+如果需求明显不属于上述类型，AI 应重新评估是否真的应该落到定时器类。
 
-# 4) 与服务器对齐时拉取
-cloudcc pull timer MySchedule
+## 4. 文件与交付规范
 
-# 5) 按已知线上 ID 拉到指定项目
-cloudcc pullList timer <线上类ID> <projectPath>
+这是 AI 必须遵守的第一层约束。
 
-# 6) 删除
-cloudcc delete timer MySchedule
-```
+### 4.1 目录与文件来源
 
-### 文档子命令
+- 定时器目录必须位于 `schedule/<类名>/`
+- 每个定时器目录包含主类 `*.java` 和 `config.json`
+- 定时器目录必须通过 `cloudcc create timer <name>` 创建
 
-```bash
-cloudcc doc timer introduction
-cloudcc doc timer devguide
-```
+### 4.2 AI 不得做的事情
 
-仅支持 `introduction` 与 `devguide`。
+- 不要手工新建 `schedule/` 子目录
+- 不要整包复制其他项目的定时器目录
+- 不要手工修改 `config.json` 中的 `id` 或版本字段
+- 不要在 `// @SOURCE_CONTENT_START` 与 `// @SOURCE_CONTENT_END` 之外写业务逻辑
 
----
+### 4.3 AI 允许做的事情
 
-## 📌 什么是定时作业？
+- 只在 CLI 生成的主类 SOURCE 区域内实现业务逻辑
+- 保持 `package schedule.<类名>;` 与目录名一致
+- 让类继承 `CCSchedule`
+- 构造方法名与类名一致
 
-定时作业是一种**自动化任务调度系统**，允许你：
+## 5. AI 编写定时器类的核心原则
 
-- 设定任务的执行时间（如每天上午 8 点、每周一、每月 1 号）
-- 关联自定义的业务逻辑代码（定时类）
-- 系统自动在指定时间触发执行，无需人工干预
+### 5.1 先分析，再编码
 
-**类比理解：** 就像手机的闹钟功能，但触发的是业务代码而不是铃声。
+AI 在写代码前，至少应明确以下内容：
 
----
+- 主对象是什么
+- 关联对象是什么
+- 触发频率是什么
+- 筛选条件是什么
+- 执行动作是什么
+- 是否存在重复执行风险
+- 是否需要批量处理
+- 是否需要通知
+- 是否需要日志
+- 是否需要失败补偿
 
-## 🎯 定时作业的主要作用
+### 5.2 优先配置化，不要硬编码
 
-### 1. 自动化重复性任务
+以下信息如果未来可能变化，优先配置化，不要直接写死在代码里：
 
-将人工需要定期执行的操作自动化，例如：
+- 提醒天数
+- 阈值条件
+- 模版 ID
+- 收件人范围
+- 开关标记
+- 外部接口地址或行为参数
 
-- 每天发送收款提醒邮件
-- 每周生成销售报表
-- 每月清理过期数据
+如果必须读取配置，优先使用官方 SDK 的自定义设置能力。
 
-### 2. 时间敏感的业务逻辑
+### 5.3 必须考虑幂等性
 
-在特定时间点必须执行的操作：
+定时器会重复执行，因此 AI 生成代码时必须避免“重复跑一次就重复造数据”。
 
-- 合同到期前 30 天提醒续约
-- 客户生日当天发送祝福
-- 季度末自动生成业绩报告
+常见幂等策略包括：
 
-### 3. 后台批处理
+- 先判断是否已处理，再执行
+- 通过状态位、标记位、执行日期控制重复执行
+- 通过业务唯一键判断是否已存在目标记录
+- 通过补偿表或日志表判断是否已成功处理
 
-处理大量数据的离线任务：
+### 5.4 必须考虑批量处理
 
-- 夜间同步外部系统数据
-- 批量更新客户状态
-- 计算佣金和业绩
+定时器天然面向批量数据。AI 不能默认按“单笔页面逻辑”写法来写。
 
-### 4. 监控与预警
+应优先考虑：
 
-持续监控系统状态并触发告警：
+- 分页查询
+- 分批写入
+- 减少循环内查询
+- 减少循环内单条更新
 
-- 客户超过 15 天未联系 → 提醒销售跟进
-- 收款计划逾期 → 通知财务人员
-- 资产即将失效 → 自动生成业务机会
+### 5.5 必须考虑可观测性
 
----
+AI 生成的定时器类至少要做到：
 
-## 💡 为什么要用定时作业？
+- 关键路径有日志
+- 异常可定位
+- 批处理数量可观察
+- 失败信息可追踪
 
-### 对比人工操作
+### 5.6 必须考虑时区安全
 
-| 维度 | 人工操作 | 定时作业 |
-|------|----------|----------|
-| **准确性** | 可能遗忘、出错 | 100% 准时执行 |
-| **效率** | 耗时耗力 | 自动执行，零人力成本 |
-| **一致性** | 不同人操作可能有差异 | 每次执行逻辑一致 |
-| **可扩展性** | 任务多了忙不过来 | 可同时运行多个任务 |
-| **可追溯** | 难以追踪谁什么时候做的 | 完整执行日志 |
+涉及日期比较、日期格式化、写库时间时，不能默认依赖本地时区。
 
-### 核心价值
+应优先使用 `TimeUtil`。
 
-```
-定时作业 = 自动化 + 准时性 + 可追溯
-```
+## 6. 官方 SDK 详细速查
 
----
+- 本节优先给出方法签名、入参、返回值和使用场景
+- 表中“必填”信息来源于官方文档
+- 如果某个批量方法在当前项目里很常见，但官方页面没有展开签名，会单独标注“项目约定”
+- 当前项目大量定时器直接调用 `this.cquery(...)`、`this.cqlQuery(...)`、`this.insert(...)` 等 inherited 方法；AI 在理解参数语义时，应以官方 `CCService` 版本为准
 
-## 🔧 定时作业能解决哪些问题？
+### 6.1 `CCObject`
 
-### 问题 1：遗忘和延误
+类定位：
 
-**场景：** 销售忘记跟进客户，导致商机流失
+- CloudCC 对象封装类
+- 用于承载新增、更新、删除、共享等对象数据
 
-**解决：** 设置定时作业检测客户最后联系时间，超过 15 天自动提醒
+#### 构造方法 1
 
-```
-┌─────────────────┐    ┌──────────────┐    ┌─────────────────┐
-│ 客户最后联系时间 │ →  │ 定时作业检测  │ →  │ 创建跟进活动     │
-│ > 15 天          │    │ (每天 8:00)   │    │ 并通知销售       │
-└─────────────────┘    └──────────────┘    └─────────────────┘
+```java
+public CCObject()
 ```
 
-### 问题 2：重复劳动效率低
+说明：
 
-**场景：** 财务人员每天手动发送收款提醒，耗时 2 小时
+- 官方提供默认构造
+- 在当前项目定时器中较少单独使用
 
-**解决：** 定时作业自动扫描逾期收款计划，批量发送邮件
+#### 构造方法 2
 
-```
-人工方式：每天 2 小时 × 250 工作日 = 500 小时/年
-定时作业：配置 1 次，自动执行，0 小时/年
-节省：500 小时/年 ≈ 62 个工作日
+```java
+public CCObject(String ccobj)
 ```
 
-### 问题 3：跨系统数据同步
+参数说明：
 
-**场景：** CRM 和 ERP 系统数据需要保持一致
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `ccobj` | `String` | 是 | 对象 API 名 |
 
-**解决：** 定时作业每晚同步两个系统的数据
+返回：
 
-```
-┌──────────┐         ┌──────────────┐         ┌──────────┐
-│   CRM    │ ←─────→ │  定时作业同步  │ ←─────→ │   ERP    │
-│  客户数据 │  2:00   │  (每日凌晨)   │  2:30   │  客户数据 │
-└──────────┘         └──────────────┘         └──────────┘
-```
+- `CCObject` 实例
 
-### 问题 4：报表生成和分发
+AI 使用要求：
 
-**场景：** 管理层需要定期查看各类报表
+- 新增普通记录时优先用这个构造器
+- `ccobj` 必须写对象 API 名，不要写对象标签名
 
-**解决：** 定时作业自动生成报表并邮件发送给相关人员
+#### 构造方法 3
 
-```
-定时触发 → 查询数据 → 生成报表 → 发送邮件 → 完成
-   ↓
- 每周一 9:00
+```java
+public CCObject(String ccobj, String isShared)
 ```
 
----
+参数说明：
 
-## 📚 典型业务场景
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `ccobj` | `String` | 是 | 对象 API 名 |
+| `isShared` | `String` | 是 | 共享标识，官方建议使用 `CCObject.IS_SHARED` |
 
-### 场景 1：销售管理
+返回：
 
-| 场景 | 触发条件 | 执行动作 |
-|------|----------|----------|
-| 线索分配 | 新线索创建后 24 小时未分配 | 自动分配给销售主管 |
-| 客户跟进提醒 | 客户最后联系时间 > 15 天 | 创建跟进活动并通知销售 |
-| 商机推进提醒 | 商机停留当前阶段 > 30 天 | 提醒销售经理介入 |
-| 业绩统计 | 每日 23:00 | 计算当日业绩并更新报表 |
+- `CCObject` 实例
 
-### 场景 2：客户服务
+AI 使用要求：
 
-| 场景 | 触发条件 | 执行动作 |
-|------|----------|----------|
-| 服务到期提醒 | 服务合同到期前 30 天 | 发送续约提醒邮件 |
-| 客户满意度调查 | 服务完成后 7 天 | 发送满意度调查问卷 |
-| 生日祝福 | 客户生日当天 | 发送祝福短信/邮件 |
-| 投诉升级 | 投诉 48 小时未处理 | 自动升级至上级主管 |
+- 仅在共享表对象场景使用
+- 不要自己发明共享标识字符串，优先使用 `CCObject.IS_SHARED`
 
-### 场景 3：财务管理
+#### 常用对象方法
 
-| 场景 | 触发条件 | 执行动作 |
-|------|----------|----------|
-| 收款提醒 | 收款计划日期前 7 天 | 邮件通知客户和财务 |
-| 逾期通知 | 收款计划逾期 1 天 | 发送逾期通知并标记 |
-| 发票生成 | 确认收款后 | 自动生成并发送发票 |
-| 佣金计算 | 每月 1 日 | 计算销售佣金并生成报表 |
+官方文档列出：
 
-### 场景 4：数据维护
+- `getUserId()`
+- `getOrgId()`
+- `getRoleId()`
 
-| 场景 | 触发条件 | 执行动作 |
-|------|----------|----------|
-| 数据清理 | 每周日 3:00 | 清理临时表和过期日志 |
-| 数据备份 | 每日 1:00 | 备份关键数据到指定位置 |
-| 数据同步 | 每日 2:00 | 同步 CRM 与外部系统数据 |
-| 索引优化 | 每月 1 日 4:00 | 重建数据库索引提升性能 |
+AI 使用要求：
 
-### 场景 5：营销自动化
+- 如果需要读取当前对象上下文中的用户、组织、角色信息，可使用这些方法
+- 定时器的主要业务数据写入仍以 `put` 为主
 
-| 场景 | 触发条件 | 执行动作 |
-|------|----------|----------|
-| 营销活动提醒 | 活动开始前 3 天 | 通知参与人员准备 |
-| 线索培育 | 线索创建后第 3/7/14 天 | 发送培育邮件 |
-| 活动效果分析 | 活动结束后 1 天 | 生成效果分析报告 |
-| 客户分群更新 | 每日 5:00 | 根据行为更新客户分群 |
+### 6.2 `CCService`
 
----
+类定位：
 
-## ⚙️ 技术实现
+- CloudCC 核心对象服务类
+- 提供对象增删改查、自定义设置、共享删除等能力
 
-### 定时作业结构
+#### 构造函数
 
+```java
+public CCService(UserInfo userInfo)
 ```
-┌─────────────────────────────────────────────────────────┐
-│                    定时作业 (Schedule Job)               │
-├─────────────────────────────────────────────────────────┤
-│  基本信息                                                │
-│  ├── 名称 (name)                                        │
-│  ├── ID (id)                                            │
-│  └── 描述 (description)                                 │
-├─────────────────────────────────────────────────────────┤
-│  调度配置                                                │
-│  ├── 频率类型 (frequency): daily/weekly/monthly         │
-│  ├── 执行时间 (executetime): 08:00                      │
-│  ├── 星期 (weeks): Mon,Tues,Wed,Thur,Fri                │
-│  ├── 开始日期 (startdate): 2024-01-01                   │
-│  └── 结束日期 (enddate): 2024-12-31                     │
-├─────────────────────────────────────────────────────────┤
-│  关联程序                                                │
-│  ├── 程序 ID (prgid)                                    │
-│  └── 定时类 (className): com.xxx.scheduler.MyJob        │
-└─────────────────────────────────────────────────────────┘
+
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `userInfo` | `UserInfo` | 是 | 当前用户对象 |
+
+返回：
+
+- `CCService` 实例
+
+AI 使用要求：
+
+- 定时器中默认先初始化 `CCService cs = new CCService(userInfo);`
+- 除非使用 `CCSchedule` 已提供的同语义快捷方法，否则统一从 `cs` 调用 SDK
+
+### 6.3 `insert`
+
+方法签名：
+
+```java
+public ServiceResult insert(CCObject ccobj) throws BusiException
 ```
 
-### 执行流程
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `ccobj` | `CCObject` | 是 | 待新增的 CloudCC 对象 |
+
+返回：
+
+- `ServiceResult`
+
+适用场景：
+
+- 新增单条记录
+- 新增任务、提醒、日志类单条对象
+
+AI 使用要求：
+
+- 先构造 `CCObject`，再 `put` 字段，最后 `insert`
+- 不要在大批量循环里无脑逐条 `insert`
+- 如果需要创建大量记录，优先考虑项目已有的批量写法
+
+### 6.4 `cquery`
+
+#### 查询普通数据
 
+方法签名：
+
+```java
+public List<CCObject> cquery(String apiName, String condition, String order) throws Exception
 ```
-┌─────────────┐
-│  系统时钟   │
-└──────┬──────┘
-       │ 到达触发时间
-       ▼
-┌─────────────┐
-│ 调度器检查   │ ──→ 是否在有效期内？
-└──────┬──────┘     ──→ 状态是否激活？
-       │ 是
-       ▼
-┌─────────────┐
-│ 加载定时类   │
-└──────┬──────┘
-       │
-       ▼
-┌─────────────┐
-│ 执行 main() │
-└──────┬──────┘
-       │
-       ▼
-┌─────────────┐
-│ 记录执行日志 │
-└─────────────┘
+
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `apiName` | `String` | 是 | 对象 API 名 |
+| `condition` | `String` | 否 | 查询条件；自定义字段 API 名要带 `__c` |
+| `order` | `String` | 否 | 排序条件 |
+
+返回：
+
+- `List<CCObject>`
+
+适用场景：
+
+- 单对象简单条件查询
+- 条件和排序较直接的巡检类定时器
+
+AI 使用要求：
+
+- 优先用于简单查询
+- 不要把页面字段标签名写进条件
+- 自定义字段必须用 API 名并带 `__c`
+
+#### 查询共享数据
+
+方法签名：
+
+```java
+public List<CCObject> cquery(String apiName, String condition, boolean isDataObject) throws Exception
 ```
 
-### 定时类示例
-
-```javascript
-/**
- * 定时类：客户长时间未联系自动新建活动
- * 程序 ID: ccp20213DC20298RebnS
- */
-function main($CCDK, obj) {
-  // 1. 查询超过 15 天未联系的客户
-  const fifteenDaysAgo = new Date();
-  fifteenDaysAgo.setDate(fifteenDaysAgo.getDate() - 15);
-  
-  const customers = $CCDK.query(`
-    SELECT Id, Name, OwnerId 
-    FROM Account 
-    WHERE LastActivityDate < '${fifteenDaysAgo.toISOString()}'
-  `);
-  
-  // 2. 为每个客户创建跟进活动
-  customers.forEach(customer => {
-    $CCDK.create('Activity', {
-      Subject: `跟进客户：${customer.Name}`,
-      Type: 'Call',
-      Status: 'Not Started',
-      OwnerId: customer.OwnerId,
-      RelatedToId: customer.Id
-    });
-  });
-  
-  return `已为 ${customers.length} 个客户创建跟进活动`;
-}
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `apiName` | `String` | 是 | 对象 API 名 |
+| `condition` | `String` | 否 | 查询条件 |
+| `isDataObject` | `boolean` | 是 | 是否查询业务对象；共享数据场景按项目现有写法传入对应布尔值 |
+
+返回：
+
+- `List<CCObject>`
+
+适用场景：
+
+- 共享关系查询
+- 权限治理类定时器
+
+AI 使用要求：
+
+- 涉及共享表查询时使用该重载
+- 布尔参数不要凭空猜测语义，优先参考现有仓库同类写法
+
+### 6.5 `cqlQuery`
+
+方法签名：
+
+```java
+public List<CCObject> cqlQuery(String apiName, String cql) throws Exception
 ```
 
----
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `apiName` | `String` | 是 | 对象 API 名 |
+| `cql` | `String` | 否 | SQL/CQL 查询语句，支持常见 `where` 条件 |
+
+返回：
+
+- `List<CCObject>`
+
+适用场景：
+
+- 联表查询
+- 聚合查询
+- 分组统计
+- 报表底表查询
+- 复杂分页场景
 
-## 📊 实际案例（来自你的系统）
+AI 使用要求：
 
-### 案例 1：客户长时间未联系新建活动
+- 复杂查询优先 `cqlQuery`
+- 默认把它当“查询接口”使用
+- 除非有充分依据，不要把它写成更新或删除通道
+- 报表、底表、汇总类定时器优先考虑 `cqlQuery`
 
+### 6.6 `update`
+
+方法签名：
+
+```java
+public ServiceResult update(CCObject ccobj) throws Exception
 ```
-┌─────────────────────────────────────────────────────┐
-│ 作业名称：客户长时间未联系新建活动                    │
-├─────────────────────────────────────────────────────┤
-│ 执行时间：每天 上午 8:00                             │
-│ 有效期：2021-12-04 ~ 2033-12-21                     │
-│ 状态：✅ 运行中                                      │
-│                                                     │
-│ 业务逻辑：                                          │
-│ 1. 扫描所有客户，找出最后联系时间 > 15 天的          │
-│ 2. 为每个客户自动创建"跟进"活动                      │
-│ 3. 活动分配给对应的销售负责人                        │
-│                                                     │
-│ 价值：防止销售遗忘客户跟进，提升客户满意度            │
-└─────────────────────────────────────────────────────┘
+
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `ccobj` | `CCObject` | 是 | 待更新对象，必须含 `id` |
+
+返回：
+
+- `ServiceResult`
+
+适用场景：
+
+- 修改单条记录
+- 回填单条标记、状态、编号
+
+AI 使用要求：
+
+- 更新前必须 `put("id", ...)`
+- 仅回写必要字段，不要把无关字段全量覆盖
+- 如果数据量大，优先改用批量更新策略
+
+### 6.7 `delete`
+
+方法签名：
+
+```java
+public ServiceResult delete(CCObject ccobj) throws Exception
 ```
 
-### 案例 2：计划收款日期 7 天后发送邮件
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `ccobj` | `CCObject` | 是 | 待删除对象，通常至少包含 `id` |
 
+返回：
+
+- `ServiceResult`
+
+适用场景：
+
+- 删除普通业务记录
+
+AI 使用要求：
+
+- 删除前必须确认这是业务允许的动作
+- 默认不要在定时器中做大批量物理/逻辑删除，除非需求明确
+
+### 6.8 `deleteShareObjectBySql`
+
+方法签名：
+
+```java
+public void deleteShareObjectBySql(String objectApiName, String expression) throws Exception
 ```
-┌─────────────────────────────────────────────────────┐
-│ 作业名称：计划收款日期 7 天后发送邮件                  │
-├─────────────────────────────────────────────────────┤
-│ 执行时间：每天 上午 8:00                             │
-│ 有效期：2021-12-10 ~ 2034-12-31                     │
-│ 状态：✅ 运行中                                      │
-│                                                     │
-│ 业务逻辑：                                          │
-│ 1. 查询收款计划日期 = 今天 + 7 天的记录              │
-│ 2. 发送邮件给客户提醒付款                            │
-│ 3. 抄送财务人员和对应销售                            │
-│                                                     │
-│ 价值：提前提醒客户付款，降低逾期率，改善现金流        │
-└─────────────────────────────────────────────────────┘
+
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `objectApiName` | `String` | 是 | 共享对象 API 名 |
+| `expression` | `String` | 是 | SQL 表达式；官方说明字段名不需要加 `__c` |
+
+返回：
+
+- `void`
+
+适用场景：
+
+- 共享关系清理
+- 权限治理类定时器
+
+AI 使用要求：
+
+- 优先用于共享对象删除，不要拿它删除普通业务对象
+- 条件一定要收敛，避免误删共享关系
+
+### 6.9 自定义设置 `getListCustomSetting`
+
+#### 读取列表类型全部记录
+
+方法签名：
+
+```java
+public Map getListCustomSetting(String objectApiName)
 ```
 
-### 案例 3：资产失效三个月自动生成业务机会
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `objectApiName` | `String` | 是 | 自定义设置 API 名 |
 
+返回：
+
+- `Map`
+
+适用场景：
+
+- 读取一整套配置项
+- 读取阈值表、邮件配置表、组织映射配置
+
+#### 读取列表类型单条记录
+
+方法签名：
+
+```java
+Map map = cs.getListCustomSetting(String apiName, String name);
 ```
-┌─────────────────────────────────────────────────────┐
-│ 作业名称：资产失效三个月自动生成业务机会              │
-├─────────────────────────────────────────────────────┤
-│ 执行时间：每天 凌晨 1:00                             │
-│ 有效期：2021-12-10 ~ 2033-12-31                     │
-│ 状态：✅ 运行中                                      │
-│                                                     │
-│ 业务逻辑：                                          │
-│ 1. 查询资产失效时间 = 今天 - 3 个月的记录            │
-│ 2. 自动创建新的业务机会（续费/升级）                 │
-│ 3. 分配给原销售或客户经理                            │
-│                                                     │
-│ 价值：抓住续费时机，提升客户生命周期价值              │
-└─────────────────────────────────────────────────────┘
+
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `apiName` | `String` | 是 | 自定义设置 API 名 |
+| `name` | `String` | 是 | 自定义设置记录名称 |
+
+返回：
+
+- `Map`
+
+AI 使用要求：
+
+- 可配置项优先放自定义设置，不要硬编码
+- 提醒阈值、开关、模板 ID、收件人规则都应优先配置化
+
+### 6.10 `getCustomSetting`
+
+方法签名：
+
+```java
+public Map getCustomSetting(String objectApiName, String id)
 ```
 
-### 案例 4：报表订阅（已过期）
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `objectApiName` | `String` | 是 | 自定义设置 API 名 |
+| `id` | `String` | 是 | 简档 ID 或用户 ID |
+
+返回：
+
+- `Map`
+
+适用场景：
+
+- 分用户、分角色、分权限读取配置
+- 不同组织或角色使用不同阈值/模版
+
+### 6.11 `SendEmail`
 
+类定位：
+
+- 官方邮件发送服务
+
+#### 构造函数
+
+```java
+public SendEmail(UserInfo userInfo)
 ```
-┌─────────────────────────────────────────────────────┐
-│ 作业名称：报表订阅 - 销售部收款统计报表               │
-├─────────────────────────────────────────────────────┤
-│ 执行时间：每月 10 日 下午 4:00                        │
-│ 有效期：2025-01-01 ~ 2025-02-28 ⚠️ 已过期           │
-│ 状态：⚠️ 需要续期或停用                              │
-│                                                     │
-│ 业务逻辑：                                          │
-│ 1. 生成销售部收款统计报表                            │
-│ 2. 发送邮件给销售总监和财务经理                      │
-│                                                     │
-│ 建议：如仍需此报表，需更新有效期                      │
-└─────────────────────────────────────────────────────┘
+
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `userInfo` | `UserInfo` | 是 | 当前用户对象 |
+
+#### `sendMailFromSystem`
+
+方法签名：
+
+```java
+public boolean sendMailFromSystem(
+    String[] toAddress,
+    String[] ccAddress,
+    String[] bccAddress,
+    String subject,
+    String content,
+    boolean isText
+)
 ```
 
----
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `toAddress` | `String[]` | 是 | 收件人数组 |
+| `ccAddress` | `String[]` | 是 | 抄送人数组，可传空数组 |
+| `bccAddress` | `String[]` | 是 | 密送人数组，可传空数组 |
+| `subject` | `String` | 是 | 邮件主题 |
+| `content` | `String` | 是 | 邮件正文，支持 HTML |
+| `isText` | `boolean` | 是 | `true` 为纯文本，`false` 为 HTML |
+
+返回：
+
+- `boolean`
+
+适用场景：
+
+- 简单通知
+- 汇总提醒
+- 失败告警
+
+AI 使用要求：
 
-## 🎓 最佳实践
+- 优先聚合后发送，避免一条记录一封邮件
+- HTML 邮件时 `isText` 应传 `false`
+- 收件人为空时不要发
 
-### 1. 合理设置执行时间
+#### `sendEmailNew`
 
+方法签名：
+
+```java
+public ServiceResult sendEmailNew(
+    String emailtemplateid,
+    String[] toaddress,
+    String[] ccaddress,
+    String[] bcaddress,
+    String id
+) throws Exception
 ```
-✅ 推荐：
-- 报表生成：非工作时间（如 23:00 或凌晨）
-- 邮件通知：工作时间开始前（如 8:00）
-- 数据同步：系统负载低时（如 2:00-4:00）
-
-❌ 避免：
-- 业务高峰期执行大量数据处理
-- 多个重任务同时执行
+
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `emailtemplateid` | `String` | 是 | 邮件模板 ID |
+| `toaddress` | `String[]` | 是 | 收件人数组 |
+| `ccaddress` | `String[]` | 是 | 抄送人数组 |
+| `bcaddress` | `String[]` | 是 | 密送人数组 |
+| `id` | `String` | 是 | 关联记录 ID |
+
+返回：
+
+- `ServiceResult`
+
+适用场景：
+
+- 已存在标准模版的业务提醒
+- 需要统一邮件样式的场景
+
+AI 使用要求：
+
+- 模板 ID 应优先配置化
+- 关联记录 ID 应传实际业务记录，不要随意填空字符串
+
+### 6.12 `DevLogger`
+
+类定位：
+
+- 官方运行日志采集工具
+
+#### 构造函数
+
+```java
+public DevLogger(UserInfo userInfo)
 ```
 
-### 2. 设置合理的有效期
+参数说明：
 
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `userInfo` | `UserInfo` | 是 | 当前用户对象 |
+
+#### `devLogInfo`
+
+方法签名：
+
+```java
+public void devLogInfo(String info)
 ```
-✅ 推荐：
-- 长期任务：设置 5-10 年有效期
-- 临时任务：设置明确结束日期
-- 定期审查：每季度检查过期任务
-
-❌ 避免：
-- 不设置结束日期（永久运行）
-- 过期任务不处理（占用系统资源）
+
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `info` | `String` | 是 | info 级别日志内容 |
+
+返回：
+
+- `void`
+
+#### `devLogError`
+
+方法签名：
+
+```java
+public void devLogError(String error, Throwable throwable)
 ```
 
-### 3. 错误处理和日志
-
-```javascript
-function main($CCDK, obj) {
-  try {
-    // 业务逻辑
-    const result = doSomething();
-    return `成功：${result}`;
-  } catch (error) {
-    // 记录错误日志
-    $CCDK.log(`定时作业执行失败：${error.message}`);
-    // 发送告警通知
-    sendAlertToAdmin(error);
-    throw error; // 让系统记录失败状态
-  }
-}
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `error` | `String` | 是 | 错误日志内容 |
+| `throwable` | `Throwable` | 否 | 异常对象 |
+
+返回：
+
+- `void`
+
+AI 使用要求：
+
+- 批处理开始、结束、数量、关键分支打 `info`
+- 异常路径打 `error`
+- 日志至少带业务主键、批次标识或关键条件
+
+### 6.13 `TimeUtil`
+
+类定位：
+
+- 多时区安全时间工具
+
+官方说明重点：
+
+- `Date` 和 `Calendar` 基于本地时区
+- 跨时区场景下应优先通过 `TimeUtil` 获取当前时间、时区和格式化工具
+
+#### `getNowDate`
+
+官方示例写法：
+
+```java
+TpSysTask task = new TpSysTask();
+task.setBeginTime(TimeUtil.getNowDate(userInfo));
 ```
 
-### 4. 性能优化
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `userInfo` | `UserInfo` | 是 | 当前用户对象 |
+
+返回：
+
+- 当前用户时区下的当前时间
+
+#### `getUserTimeZone`
 
+方法签名式写法：
+
+```java
+TimeZone tz = TimeUtil.getUserTimeZone(userInfo);
 ```
-✅ 推荐：
-- 批量操作代替循环单条处理
-- 使用分页查询避免内存溢出
-- 异步处理非关键逻辑
-
-❌ 避免：
-- 单次查询大量数据（>10000 条）
-- 在定时作业中调用外部 API（无超时控制）
-- 长时间运行的任务（>30 分钟）
+
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `userInfo` | `UserInfo` | 是 | 当前用户对象 |
+
+返回：
+
+- `TimeZone`
+
+#### `getSimpleDateFormat`
+
+官方示例写法：
+
+```java
+SimpleDateFormat myDateFormat =
+    TimeUtil.getSimpleDateFormat("yyyy-MM-dd", userInfo);
 ```
 
-### 5. 监控和告警
+参数说明：
+
+| 参数 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `format` | `String` | 是 | 日期格式；官方默认示例为 `yyyy-MM-dd` |
+| `userInfo` | `UserInfo` | 是 | 当前用户对象 |
+
+返回：
+
+- 已绑定用户时区的 `SimpleDateFormat`
 
+#### `getCalendar`
+
+官方示例写法：
+
+```java
+Calendar cal = Calendar.getInstance(TimeUtil.getUserTimeZone(userInfo));
+// 或
+Calendar cal2 = TimeUtil.getCalendar(userInfo);
 ```
-建议配置：
-- 执行失败时发送邮件/短信告警
-- 定期检查执行日志
-- 监控任务执行时长变化
+
+返回：
+
+- 带用户时区的 `Calendar`
+
+AI 使用要求：
+
+- 涉及比较、格式化、写入时间时，优先使用 `TimeUtil`
+- 不要默认直接使用裸 `new Date()`、裸 `SimpleDateFormat`、裸 `Calendar`
+
+### 6.14 项目常见批量写法：`insertLt` / `updateLt`
+
+说明：
+
+- 这两个方法在当前项目定时器和 `cloudcc doc timer devguide` 示例中非常常见
+- 官方链接页未在本次抓取结果中展开它们的详细签名表
+- 因此，AI 不能“脑补重载签名”，必须沿用仓库已有写法
+
+当前项目与文档中已出现的典型用法：
+
+```java
+cs.insertLt(batch);
+cs.updateLt(batch);
 ```
 
----
+AI 使用要求：
+
+- 只在已有项目先例清晰时使用
+- 参数形态优先沿用本仓库同类定时器
+- 如果需求需要新的批量调用方式，而仓库中没有先例，应先说明依据不足，不要编造 API
+
+### 6.15 本节给 AI 的结论
+
+AI 编写定时器时，对 SDK 的使用顺序应默认如下：
+
+1. 用 `CCService` 作为主入口
+2. 用 `CCObject` 承载新增/更新对象
+3. 简单查询优先 `cquery`
+4. 联表和聚合优先 `cqlQuery`
+5. 单条写入用 `insert` / `update` / `delete`
+6. 通知用 `SendEmail`
+7. 观测用 `DevLogger`
+8. 时间统一走 `TimeUtil`
+9. 配置优先走 `getListCustomSetting` / `getCustomSetting`
+10. 批量方法只复用项目已验证写法，不凭空猜
+
+## 7. 当前项目的定时器代码风格要求
+
+### 7.1 当前项目更偏向这几类任务
 
-## 📋 管理操作
+- 提醒催办
+- 数据同步
+- 数据刷新与修正
+- 报表底表构建
+- 自动生成下游对象
+- 权限治理
 
-### 定时类：使用 CLI 管理本地 `schedule/`（推荐）
+因此，AI 生成方案时应优先往这些成熟模式靠拢，而不是引入与现有仓库明显脱节的实现风格。
 
-与**定时类源码**的创建、同步、删除，请优先使用上文「CLI 与本地文件（必读）」中的命令，避免绕过 CLI 直接改目录或 `config.json`。
+### 7.2 当前项目中常见模式
 
-以下接口面向**定时作业配置**（调度时间、启用状态等在设置中的作业），与 `schedule/` 下定时类源码管理是不同层面；具体以你环境的管理后台与 OpenAPI 为准。
+- 先查数据，再按条件处理
+- 按责任人聚合后通知
+- 批量更新字段、状态、台账、底表
+- 在满足条件时自动生成任务或派生对象
+- 对接口失败记录做补偿和邮件告警
 
-### 查询定时作业（平台接口示例）
+### 7.3 当前项目中 AI 应优先保留的工程意识
 
-```bash
-# 获取列表
-POST /ccsetup/api/schedulAbleprg/list
+- 业务逻辑尽量清晰直白
+- 关键分支有日志
+- 批量处理避免深层嵌套查询
+- 数据写回前先判断是否真的需要写
+- 可能重复执行的逻辑必须考虑去重或状态控制
 
-# 获取详细信息
-POST /ccsetup/api/schedulAbleprg/edit
-Body: { "id": "作业 ID" }
+## 8. AI 实现模板
+
+下面是推荐给 AI 的定时器实现骨架。
+
+```java
+package schedule.示例定时器;
+
+import com.cloudcc.core.*;
+
+public class 示例定时器 extends CCSchedule {
+    public 示例定时器() {
+        // @SOURCE_CONTENT_START
+        CCService cs = new CCService(userInfo);
+        DevLogger log = new DevLogger(userInfo);
+        try {
+            java.util.Date now = TimeUtil.getNowDate(userInfo);
+            java.text.SimpleDateFormat sdf =
+                TimeUtil.getSimpleDateFormat("yyyy-MM-dd HH:mm:ss", userInfo);
+
+            log.devLogInfo("示例定时器 start, now=" + sdf.format(now));
+
+            // 1. 查询目标数据
+            // 2. 判断是否满足执行条件
+            // 3. 批量生成/更新/通知
+            // 4. 记录处理数量与结果
+
+            log.devLogInfo("示例定时器 finish");
+        } catch (Exception e) {
+            log.devLogError("示例定时器 error", e);
+            throw new RuntimeException(e.getMessage(), e);
+        }
+        // @SOURCE_CONTENT_END
+    }
+}
 ```
 
-### 常见管理需求
+AI 可以在此基础上扩展，但不得破坏以下结构：
+
+- `package schedule.<类名>;`
+- `extends CCSchedule`
+- 构造方法同名
+- SOURCE 边界完整
+
+## 9. AI 生成定时器类时的必填设计项
+
+AI 在输出实现前，应先在思路中覆盖以下设计项。
+
+### 9.1 业务定义
+
+- 这个定时器服务什么业务目标
+- 为什么它应该是定时器，而不是触发器
+
+### 9.2 数据范围
 
-| 需求 | 操作 |
-|------|------|
-| 查看有哪些定时作业 | 调用 list 接口 |
-| 查看作业详细配置 | 调用 edit 接口 |
-| 启用/禁用作业 | 修改作业状态（需管理权限） |
-| 修改执行时间 | 编辑作业的 executetime 和 frequency |
-| 延长有效期 | 更新 enddate 字段 |
-| 创建新作业 | 使用 cloudcc-cli 创建定时类并配置调度 |
+- 主对象
+- 关联对象
+- 查询条件
+- 是否全量
+- 是否增量
+- 是否分页
 
----
+### 9.3 执行动作
 
-## 🚨 常见问题
+- 是提醒、同步、修正、汇总、生成，还是权限治理
+- 动作顺序是什么
+- 失败后是否继续处理后续数据
 
-### Q1: 定时作业不执行怎么办？
+### 9.4 幂等设计
 
-**检查清单：**
-1. 当前日期是否在有效期内？
-2. 作业状态是否为激活？
-3. 定时类代码是否有错误？
-4. 系统日志是否有报错？
+- 如何防止重复新增
+- 如何防止重复通知
+- 如何防止重复推进状态
 
-### Q2: 如何调试定时作业？
+### 9.5 性能设计
 
-**方法：**
-1. 在代码中添加日志输出
-2. 手动执行定时类测试逻辑
-3. 查看系统执行日志
-4. 设置测试环境验证
+- 是否存在循环内查询
+- 是否存在大量单条写入
+- 是否需要分批提交
 
-### Q3: 定时作业可以传递参数吗？
+### 9.6 观测与异常
 
-**答案：** 可以。在配置定时作业时设置参数，在定时类中通过 `obj` 参数接收。
+- 哪些日志必须打
+- 哪些异常要抛出
+- 哪些异常要告警
 
-### Q4: 定时作业执行失败会重试吗？
+### 9.7 配置化设计
+
+- 阈值是否应该来自自定义设置
+- 邮件模版、收件人、开关是否应该配置化
+
+## 10. AI 禁止事项
+
+以下是 AI 在当前项目中编写定时器类时应明确避免的行为。
+
+- 不要手工创建 `schedule/<name>/` 目录
+- 不要修改 `config.json` 的 `id`、版本字段
+- 不要在 SOURCE 区域之外写业务代码
+- 不要把明显实时场景错误地写成定时器
+- 不要在大循环里频繁嵌套查询，造成 N+1 问题
+- 不要在大批量处理中逐条单次写入而不考虑 `insertLt` / `updateLt`
+- 不要默认使用 `new Date()`、裸 `Calendar`、裸 `SimpleDateFormat` 处理业务时间
+- 不要吞掉异常而不打日志
+- 不要默认把邮箱、模版 ID、阈值、组织 ID 全部硬编码
+- 不要在没有明确理由时用 SQL 风格语句替代官方 CRUD
+- 不要无条件全表扫描并直接修改全量数据
+- 不要让定时器重复执行后反复创建相同记录、任务或邮件
+
+## 11. AI 输出结果要求
+
+AI 在完成定时器类开发时，输出说明至少应包含：
+
+- 为什么选择定时器类
+- 主对象与处理范围
+- 执行条件
+- 核心动作
+- 幂等策略
+- 批量策略
+- 日志与异常策略
+- 是否使用通知
+- 是否使用配置化
+
+如果未能做到其中某一项，AI 应显式说明原因，而不是默认省略。
+
+## 12. 推荐给 AI 的任务描述模板
+
+下面这个模板适合作为给 AI 下达定时器开发任务时的标准输入。
+
+```text
+请为 CloudCC 编写一个定时器类，要求如下：
+
+1. 定时器名称：
+2. 业务目标：
+3. 为什么需要定时执行：
+4. 主对象与关联对象：
+5. 查询范围（全量/增量/按日期/按状态）：
+6. 满足什么条件后执行：
+7. 执行动作（提醒/同步/更新/生成/汇总/权限处理）：
+8. 是否需要邮件或任务：
+9. 是否需要读取自定义设置：
+10. 幂等要求：
+11. 批量要求：
+12. 异常和日志要求：
+
+请按当前项目的 CloudCC 定时器规范实现，并只在 SOURCE_CONTENT 区域内编写业务代码。
+```
 
-**答案：** 默认不自动重试。建议在代码中实现重试逻辑或配置告警通知人工处理。
+## 13. 最终结论
 
----
+对 AI 而言，CloudCC 定时器类不是“会写 Java 就能写”，而是要同时满足三层约束：
 
+- 第一层：必须符合 CloudCC 官方 SDK 的能力边界和推荐用法
+- 第二层：必须符合 `cloudcc-cli` 的目录、发布和 SOURCE 区域约束
+- 第三层：必须符合当前项目中定时器类的主流业务模式和工程风格
 
-*最后更新：2026-03-25*
+只有同时满足这三层要求，AI 生成的定时器类才能真正可落地、可维护、可发布。