cloudcc-cli 2.2.5 → 2.2.7

package/skill/REQUIREMENTS_BREAKDOWN.md

@@ -0,0 +1,98 @@
+## 目标
+
+把业务需求翻译成 CloudCC CRM 二开落地项，并选择“应该做什么组件”：自定义对象/字段/菜单/应用/自定义类/定时器/触发器/自定义组件/客户端脚本。
+
+---
+
+## 需求拆解模板（AI 必须输出）
+
+拿到需求后，先输出以下结构（缺信息则显式标注“待确认”）：
+
+- **背景与目标**：要解决什么问题，成功标准是什么。
+- **角色与权限**：涉及哪些用户/简档/权限集，是否需要后台权限调整。
+- **对象与数据模型**：
+  - 需要哪些**自定义对象**（表）？
+  - 需要哪些**字段**（类型、必填/唯一、默认值、选项、查找/主详关系）？
+  - 是否涉及**记录类型**、**布局**、**验证规则**（若 CLI 不覆盖，需在 CRM 配置）？
+- **业务流程**：
+  - 触发时机：保存前/保存后/提交审批/批处理/定时等
+  - 需要哪些自动化：校验、自动赋值、联动更新、异步任务、定时任务
+- **界面与交互**：
+  - 是否需要自定义页面或嵌入式 UI？
+  - 是否需要列表/详情/编辑页的前端交互（客户端脚本 / 自定义组件）？
+- **集成与外部依赖**：第三方接口、鉴权方式、重试/限流、日志与审计。
+- **风险与回滚**：数据迁移、权限影响、性能与批量场景、灰度与回滚方案。
+- **交付物清单**：最终要产出哪些 CloudCC 资产（对象/字段/菜单/应用/类/触发器/定时器/组件/脚本）。
+
+---
+
+## 方案选型决策表（怎么判断用什么）
+
+### 自定义对象（Custom Object）
+
+当出现以下需求时，优先考虑创建自定义对象：
+
+- 需要一个新的业务实体（类似新表），有独立的字段、权限、页面与列表
+- 需要与现有对象建立查找/主详关系
+- 需要支持审批、报表、共享规则等平台能力（通常都围绕对象展开）
+
+### 自定义字段（Field）
+
+当需求是“给已有对象补充数据结构”时：
+
+- 新增文本/数值/日期/选项/查找关系等字段
+- 需要字段级校验、默认值、必填等（部分能力可能需在 CRM 配置完成）
+
+### 触发器（Trigger）
+
+当需求是“数据写入前后做强一致业务逻辑”时：
+
+- 保存前校验/自动赋值/阻止不合法写入（before*）
+- 保存后联动更新、写日志、创建子记录（after*）
+- 批量/审批/提交后回调等特定时机（approval/batch/commitBatch 等）
+
+> 注意：触发器要考虑**批量**、幂等、递归、性能与异常处理。
+
+### 自定义类（Class）
+
+当需求是“可复用的服务逻辑/复杂计算/对外接口封装”时：
+
+- 作为触发器/定时器/页面调用的后端服务类
+- 抽取通用能力（查询封装、校验器、集成适配器）
+
+### 定时类（Scheduled Class / Timer）
+
+当需求是“按时间周期跑任务”时：
+
+- 夜间同步、定时报表、到期提醒、批量修复数据
+- 需要可控的调度表达式与运行日志
+
+### 自定义组件（Vue Custom Component）
+
+当需求是“在 CloudCC UI 中提供复杂交互 UI”时：
+
+- 自定义表单、复杂联动、可视化、批量操作 UI
+- 需要前端框架能力（Vue2.x）与更强的用户体验
+
+### 客户端脚本（Client Script）
+
+当需求是“页面级轻量交互/字段联动/保存前校验”时：
+
+- 列表/详情/编辑/新建页生命周期钩子
+- 字段变更联动、提示、轻量校验
+
+> 客户端脚本更轻量；交互复杂或需要组件化复用，建议升级为自定义组件。
+
+---
+
+## 推荐落地流程（AI 执行顺序）
+
+一般建议按以下顺序落地（从“数据结构”到“业务逻辑”再到“界面”）：
+
+1. **对象与字段**：先把数据模型搭好（对象、字段、关系）
+2. **菜单与应用**：让用户能访问（菜单/应用）
+3. **后端逻辑**：自定义类 / 触发器 / 定时器
+4. **前端交互**：客户端脚本 / 自定义组件
+5. **联调与回归**：核心路径 + 批量场景 + 权限场景
+6. **发布与回滚准备**：版本记录、灰度、回滚策略
+

package/skill/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: cloudcc-cli-dev
+description: CloudCC CRM 二次开发 CLI 助手。用于需求拆解与方案选型，并通过 cloudcc-cli（cc 命令）创建/拉取/发布自定义对象、字段、菜单/应用、自定义类、定时器、触发器与 Vue 自定义组件等资产。用户提到 CloudCC、cloudcc-cli、cc 命令、对象/字段/触发器/定时器/自定义组件 时应优先使用。
+---
+
+# CloudCC CLI Development Skill
+
+## 使用方式（AI 必须遵循）
+
+- 先阅读 `REQUIREMENTS_BREAKDOWN.md`，输出需求拆解与交付物清单，再进入落地步骤。
+- 需要环境/密钥 配置时，阅读 `INSTALL_AND_BOOTSTRAP.md`。
+- 需要建模时（对象/字段/菜单/应用），阅读 `OBJECTS_AND_FIELDS.md`。
+- 需要后端逻辑时（类/定时器/触发器），阅读 `BACKEND_CODE.md`。
+- 需要自定义组件时，阅读 `VUE_CUSTOM_COMPONENT.md`。
+- 需要快速对照命令与参数时，阅读 `CLI_CHEATSHEET.md`。
+
+## 强制安全边界
+
+- 不要在输出/代码/提交中包含真实密钥（`CloudCCDev`、`safetyMark`、`secretKey`、`openSecretKey`、token
+  等）。
+- 后端类/触发器/定时器遵守片段同步：仅在
+  `@SOURCE_CONTENT_START`~`@SOURCE_CONTENT_END` 内编写可发布逻辑。
+- 客户端脚本遵守片段同步：仅在 `function main($CCDK, obj) { ... }`
+  的函数体内编写可发布逻辑。
+
+## 快速入口
+
+- 安装与初始化：`INSTALL_AND_BOOTSTRAP.md`
+- 需求拆解与方案选择：`REQUIREMENTS_BREAKDOWN.md`
+- 自定义对象与字段：`OBJECTS_AND_FIELDS.md`
+- 自定义类/定时器/触发器：`BACKEND_CODE.md`
+- Vue 自定义组件：`VUE_CUSTOM_COMPONENT.md`
+- CLI 速查：`CLI_CHEATSHEET.md`

package/skill/VUE_CUSTOM_COMPONENT.md

@@ -0,0 +1,50 @@
+## 覆盖范围
+
+本篇聚焦 CloudCC Vue2.x 自定义组件（Custom Component）：
+
+- 创建组件骨架
+- 编辑与最佳实践入口
+- 编译与发布到服务器
+
+---
+
+## 创建自定义组件
+
+### CLI 命令
+
+```bash
+# 在项目根目录执行（会生成到 plugins/<pluginName>/）
+cc create plugin <pluginName>
+```
+
+创建后会生成组件主文件、子组件目录与配置文件（以项目模板为准）。
+
+---
+
+## 发布组件
+
+```bash
+cc publish plugin <pluginName>
+```
+
+> 发布会执行编译/打包/上传；如果组件依赖复杂，注意依赖收集与发布策略。
+
+---
+
+## 编辑要点（CLI 项目约束）
+
+- 组件目录通常为 `plugins/<pluginName>/`
+- 确保所有 `<style>` 标签带 `scoped`，避免全局样式污染
+- 发布通过 `cc publish plugin <pluginName>` 执行编译与上传
+
+---
+
+## 选型建议（组件 vs 客户端脚本）
+
+- **自定义组件**：复杂交互、强 UI、可复用组件化、需要更完整工程化能力。
+- **客户端脚本**：轻量联动、页面钩子逻辑、少量 UI 提示与校验。
+
+一般建议：
+
+- 先用脚本满足基础联动；当逻辑与 UI 复杂度上升时，再升级为组件方案。
+

package/src/api/backend-sdk-java.md

@@ -0,0 +1,427 @@
+# CloudCC 后端 SDK（Java）使用指南
+
+> 本文档参考 CloudCC 官方「后端 SDK 参考」整理而成：[后端SDK参考](https://help.cloudcc.cn/product03/fu-wu-duan-sdkcan-kao-java/)。  
+> 目标：为自定义类、触发器、定时类中的 Java 开发，提供 `CCObject`、`UserInfo`、`CCService`、`SendEmail`、`DevLogger`、`TimeUtil` 等核心 API 的速查说明。
+
+---
+
+## 1. CCObject：CloudCC 对象封装
+
+### 1.1 类说明
+
+- 继承自 `java.util.HashMap`：`com.g3cloud.platform.publik.CCObject`  
+- 用于承载某个对象（如 `Account`、`Contact`）的一条记录或共享表记录。
+
+### 1.2 构造函数
+
+```java
+public CCObject() {}
+```
+
+```java
+public CCObject(String ccobj)
+```
+
+| 参数      | 类型     | 是否必填 | 说明         |
+| --------- | -------- | -------- | ------------ |
+| `ccobj`   | `String` | 是       | 对象 API 名称 |
+
+```java
+public CCObject(String ccobj, String isShared)
+```
+
+| 参数        | 类型     | 是否必填 | 说明                                      |
+| ----------- | -------- | -------- | ----------------------------------------- |
+| `ccobj`     | `String` | 是       | 对象 API 名称                             |
+| `isShared`  | `String` | 是       | 共享标识，建议使用 `CCObject.IS_SHARED`   |
+
+### 1.3 常量字段
+
+| 修饰符和类型                 | 字段           | 默认值         | 说明      |
+| ---------------------------- | -------------- | -------------- | --------- |
+| `public static final String` | `OBJECT_API`   | `CCObjectAPI`  | 对象 API  |
+| `public static final String` | `IS_SHARED`    | `isShared`     | 共享对象标识 |
+
+### 1.4 常用方法
+
+#### `getObjectApiName()`
+
+```java
+public String getObjectApiName()
+```
+
+返回当前 `CCObject` 对应的对象 API 名称。
+
+#### `put(String apiName, String value)`
+
+```java
+public String put(String apiName, String value)
+```
+
+| 参数        | 类型     | 是否必填 | 说明              |
+| ----------- | -------- | -------- | ----------------- |
+| `apiName`   | `String` | 是       | 字段 API 名称      |
+| `value`     | `String` | 是       | 字段值（字符串形式） |
+
+示例：
+
+```java
+CCObject contact = new CCObject("Contact");
+contact.put("email", "hello@cloudcc.com");
+```
+
+---
+
+## 2. UserInfo：当前用户信息
+
+类：`com.g3cloud.common.UserInfo`（实现 `java.io.Serializable`）
+
+### 2.1 常用方法
+
+```java
+public String getUserId()
+public String getOrgId()
+public String getRoleId()
+```
+
+- `getUserId()`：当前用户 ID  
+- `getOrgId()`：当前组织 ID  
+- `getRoleId()`：当前角色 ID  
+
+在自定义类构造函数或方法中通常作为参数传入，用于实例化 `CCService`、`DevLogger` 等。
+
+---
+
+## 3. CCService：对象操作核心工具类
+
+类：`com.g3cloud.platform.publik.CCService`
+
+### 3.1 构造函数
+
+```java
+public CCService(UserInfo userInfo)
+```
+
+| 参数        | 类型       | 是否必填 | 说明     |
+| ----------- | ---------- | -------- | -------- |
+| `userInfo`  | `UserInfo` | 是       | 当前用户对象 |
+
+在自定义类中常见用法：
+
+```java
+private CCService cs;
+private UserInfo userInfo;
+
+public MyClass(UserInfo userInfo) {
+    this.userInfo = userInfo;
+    this.cs = new CCService(userInfo);
+}
+```
+
+### 3.2 新增记录：`insert`
+
+```java
+public ServiceResult insert(CCObject ccobj) throws BusiException
+```
+
+| 参数     | 类型        | 是否必填 | 说明    |
+| -------- | ----------- | -------- | ------- |
+| `ccobj`  | `CCObject`  | 是       | CC 对象 |
+
+示例：
+
+```java
+CCObject contact = new CCObject("Contact");
+contact.put("email", "hello@cloudcc.com");
+cs.insert(contact);
+```
+
+### 3.3 查询记录：`cquery`
+
+```java
+public List<CCObject> cquery(String apiName, String condition, String order) throws Exception
+```
+
+| 参数         | 类型     | 是否必填 | 说明                                                                 |
+| ------------ | -------- | -------- | -------------------------------------------------------------------- |
+| `apiName`    | `String` | 是       | 对象 API 名称                                                        |
+| `condition`  | `String` | 否       | 使用字段 apiname 查询，自定义字段 API 后需加 `__c`，为空则查询所有   |
+| `order`      | `String` | 否       | 排序条件，字段 API 后需加 `__c`                                      |
+
+示例：
+
+```java
+List<CCObject> opps = cs.cquery(
+    "Opportunity",
+    "khmc__c = '123'",
+    "jine__c desc"
+);
+```
+
+#### 查询共享数据
+
+```java
+public List<CCObject> cquery(String apiName, String condition, boolean isDataObject) throws Exception
+```
+
+| 参数           | 类型      | 是否必填 | 说明                                         |
+| -------------- | --------- | -------- | -------------------------------------------- |
+| `apiName`      | `String`  | 是       | 对象 API 名称                                |
+| `condition`    | `String`  | 否       | 同上                                         |
+| `isDataObject` | `Boolean` | 否       | `true` 查询普通数据，`false` 查询共享数据     |
+
+示例：
+
+```java
+List<CCObject> opps = cs.cquery(
+    "Opportunity",
+    "khmc__c = '123'",
+    false
+);
+```
+
+### 3.4 SQL 查询：`cqlQuery`
+
+```java
+public List<CCObject> cqlQuery(String apiName, String cql) throws Exception
+```
+
+| 参数      | 类型     | 是否必填 | 说明                                   |
+| --------- | -------- | -------- | -------------------------------------- |
+| `apiName` | `String` | 是       | 对象 API 名称                          |
+| `cql`     | `String` | 否       | CQL/SQL 语句，支持常用 where 条件       |
+
+示例：
+
+```java
+List<CCObject> list = cs.cqlQuery(
+  "test_object_a",
+  "select * from test_object_a where text_field = 'hello002'"
+);
+```
+
+### 3.5 修改记录：`update`
+
+```java
+public ServiceResult update(CCObject ccobj) throws Exception
+```
+
+示例：
+
+```java
+CCObject obj = new CCObject("test_object_a");
+obj.put("id", "a252025B79C1B99R62Nf");
+obj.put("text_field", "hello003");
+cs.update(obj);
+```
+
+### 3.6 删除记录：`delete`
+
+```java
+public ServiceResult delete(CCObject ccobj) throws Exception
+```
+
+示例：
+
+```java
+CCObject obj = new CCObject("test_object_a");
+obj.put("id", "a252025B79C1B99R62Nf");
+cs.delete(obj);
+```
+
+### 3.7 删除共享表记录：`deleteShareObjectBySql`
+
+```java
+public void deleteShareObjectBySql(String objectApiName, String expression) throws Exception
+```
+
+| 参数             | 类型     | 是否必填 | 说明                               |
+| ---------------- | -------- | -------- | ---------------------------------- |
+| `objectApiName`  | `String` | 是       | 对象 API 名称                      |
+| `expression`     | `String` | 是       | SQL 表达式，字段 **不需要** 加 `__c` |
+
+---
+
+## 4. 自定义设置（CustomSetting）
+
+### 4.1 列表类型：`getListCustomSetting`
+
+```java
+public Map getListCustomSetting(String objectApiName)
+```
+
+| 参数             | 类型     | 是否必填 | 说明          |
+| ---------------- | -------- | -------- | ------------- |
+| `objectApiName`  | `String` | 是       | 自定义设置 API |
+
+返回指定 API 下的全部列表类型自定义设置。
+
+### 4.2 列表类型单条：`getListCustomSetting(String apiName, String name)`
+
+```java
+Map map = cs.getListCustomSetting(String apiName, String name);
+```
+
+| 参数        | 类型     | 是否必填 | 说明           |
+| ----------- | -------- | -------- | -------------- |
+| `apiName`   | `String` | 是       | 自定义设置 API  |
+| `name`      | `String` | 是       | 自定义设置记录名称 |
+
+### 4.3 层次结构类型：`getCustomSetting`
+
+```java
+public Map getCustomSetting(String objectApiName, String id)
+```
+
+| 参数             | 类型     | 是否必填 | 说明                     |
+| ---------------- | -------- | -------- | ------------------------ |
+| `objectApiName`  | `String` | 是       | 自定义设置 API           |
+| `id`             | `String` | 是       | 简档 ID 或用户 ID        |
+
+---
+
+## 5. SendEmail：发送邮件
+
+类：`com.g3cloud.platform.common.service.emailservice.SendEmail`
+
+### 5.1 构造函数
+
+```java
+public SendEmail(UserInfo userInfo)
+```
+
+| 参数        | 类型       | 是否必填 | 说明     |
+| ----------- | ---------- | -------- | -------- |
+| `userInfo`  | `UserInfo` | 是       | 用户对象 |
+
+### 5.2 直接发送邮件：`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 格式邮件     |
+
+### 5.3 使用模板发送：`sendEmailNew`
+
+```java
+public ServiceResult sendEmailNew(
+    String emailtemplateid,
+    String[] toaddress,
+    String[] ccaddress,
+    String[] bcaddress,
+    String id) throws Exception
+```
+
+| 参数              | 类型       | 是否必填 | 说明          |
+| ----------------- | ---------- | -------- | ------------- |
+| `emailtemplateid` | `String`   | 是       | 邮件模板 ID    |
+| `toaddress`       | `String[]` | 是       | 收件人         |
+| `ccaddress`       | `String[]` | 是       | 抄送人         |
+| `bcaddress`       | `String[]` | 是       | 密送人         |
+| `id`              | `String`   | 是       | 关联记录 ID     |
+
+---
+
+## 6. DevLogger：运行日志采集
+
+类：`com.g3cloud.platform.common.service.devlogger.DevLogger`（示例名，具体包以实际项目为准）
+
+### 6.1 构造函数
+
+```java
+public DevLogger(UserInfo userInfo)
+```
+
+| 参数        | 类型       | 是否必填 | 说明     |
+| ----------- | ---------- | -------- | -------- |
+| `userInfo`  | `UserInfo` | 是       | 用户对象 |
+
+### 6.2 info 日志：`devLogInfo`
+
+```java
+public void devLogInfo(String info)
+```
+
+| 参数    | 类型     | 是否必填 | 说明     |
+| ------- | -------- | -------- | -------- |
+| `info`  | `String` | 是       | 日志信息 |
+
+### 6.3 error 日志：`devLogError`
+
+```java
+public void devLogError(String error, Throwable throwable)
+```
+
+| 参数         | 类型        | 是否必填 | 说明       |
+| ------------ | ----------- | -------- | ---------- |
+| `error`      | `String`    | 是       | 错误信息   |
+| `throwable`  | `Throwable` | 否       | 异常对象   |
+
+---
+
+## 7. TimeUtil：多时区时间工具
+
+说明：`TimeUtil` 用于在多时区环境下安全处理时间，避免直接使用 `new Date()` / `Calendar.getInstance()` 带来的偏差。
+
+### 7.1 获取当前时间：`getNowDate`
+
+```java
+TpSysTask task = new TpSysTask();
+task.setBeginTime(TimeUtil.getNowDate(userInfo));
+```
+
+| 参数        | 类型       | 是否必填 | 说明     |
+| ----------- | ---------- | -------- | -------- |
+| `userInfo`  | `UserInfo` | 是       | 用户对象 |
+
+### 7.2 获取用户时区：`getUserTimeZone`
+
+```java
+TimeZone tz = TimeUtil.getUserTimeZone(userInfo);
+```
+
+### 7.3 获取带时区的 `SimpleDateFormat`：`getSimpleDateFormat`
+
+```java
+SimpleDateFormat myDateFormat =
+    TimeUtil.getSimpleDateFormat("yyyy-MM-dd", userInfo);
+```
+
+| 参数        | 类型       | 是否必填 | 说明           |
+| ----------- | ---------- | -------- | -------------- |
+| `format`    | `String`   | 是       | 日期格式化模式 |
+| `userInfo`  | `UserInfo` | 是       | 用户对象       |
+
+### 7.4 获取带时区的 `Calendar`
+
+```java
+Calendar cal = Calendar.getInstance(TimeUtil.getUserTimeZone(userInfo));
+// 或
+Calendar cal2 = TimeUtil.getCalendar(userInfo);
+```
+
+---
+
+## 8. 后端 SDK 使用建议 Checklist
+
+- [ ] 在自定义类/触发器/定时类中统一使用 `CCService` 操作对象，不直接写 JDBC。  
+- [ ] 查询条件和排序中，自定义字段使用 API 名称并加 `__c` 后缀（共享表表达式除外）。  
+- [ ] 涉及时区的所有时间写入/比较统一使用 `TimeUtil`。  
+- [ ] 需要发邮件时首选 `SendEmail`，避免自己拼 SMTP。  
+- [ ] 关键业务流程和异常通过 `DevLogger` 记录，便于问题排查。  
+- [ ] 自定义设置使用 `getListCustomSetting` / `getCustomSetting` 统一读取。  
+