cloudcc-cli 2.2.8 → 2.3.0

package/docs//350/247/246/345/217/221/345/231/250/347/261/273.md

@@ -0,0 +1,404 @@
+# CloudCC 触发器使用总结
+
+> 基于生产环境 25 个触发器实例分析  
+> 文档版本：v1.0  
+> 更新时间：2026-03-24
+
+## 一、什么是触发器
+
+CloudCC 触发器是符合 Java 语法规范的服务端代码，在特定业务事件发生时自动执行，用于实现业务逻辑自动化处理。
+
+触发器本质：
+
+- 一段 Java 代码，运行在 CloudCC 平台沙箱环境中
+- 使用 `CCService`、`CCObject` 等平台 API 类
+- 在数据变更的特定时刻（前/后）自动触发执行
+
+## 二、触发器能干什么
+
+### 2.1 核心能力
+
+| 能力 | 说明 | 示例 |
+| --- | --- | --- |
+| 自动赋值 | 在记录保存前自动计算并填充字段 | 个人业绩/部门业绩自动赋值 |
+| 数据校验 | 阻止不符合业务规则的数据保存 | 预算金额校验、审批金额验证 |
+| 关联更新 | 修改一条记录时自动更新关联记录 | 回款明细汇总到收款计划 |
+| 自动生成 | 根据业务规则自动创建新记录 | 审批通过后自动生成回款记录 |
+| 权限控制 | 自动设置数据共享权限 | 按部门/人员自动共享 |
+| 状态同步 | 审批状态变更后同步更新相关字段 | 预算审批状态回写 |
+| 汇总计算 | 实时汇总明细数据到主记录 | 部门业绩字段汇总 |
+
+### 2.2 技术能力（基于 CCService API）
+
+```java
+// 1. 新增记录
+CCObject opp = new CCObject("Opportunity");
+opp.put("name", "value");
+cs.insert(opp);
+
+// 2. 查询记录
+// 查询指定字段
+List<CCObject> opps = cs.cqueryByFields(
+    "Opportunity",
+    "khmc__c='" + record_new.get("id") + "'",
+    "id,name,createdate"
+);
+
+// 查询全部字段
+List<CCObject> all = cs.cquery("Opportunity", "khmc__c='" + record_new.get("id") + "'");
+
+// 复杂 SQL 查询
+List<CCObject> ccobjs = cs.cqlQuery(
+    "Opportunity",
+    "select sum(amount) as sumAmount from Opportunity where khmc = '0012001238ytwuiw'"
+);
+
+// 3. 修改记录
+cs.update(opp);
+
+// 4. 删除记录
+cs.delete(opp);
+
+// 5. 发送邮件通知
+SendEmail sendEmail = new SendEmail(userInfo);
+sendEmail.sendMailFromSystem(toAddress, ccAddress, bccAddress, subject, content, isText);
+```
+
+## 三、触发器触发时机详解
+
+### 3.1 beforeUpsert（创建或更新前）
+
+执行时机：记录保存之前，数据尚未写入数据库。  
+典型用途：
+
+- 自动计算字段值
+- 数据格式校验
+- 阻止非法数据保存（抛出异常）
+- 自动填充默认值
+
+生产实例：
+
+| 触发器名称 | 对象 | 作用 |
+| --- | --- | --- |
+| 个人业绩/部门业绩赋值 | 对外付款 | 自动赋值业绩字段 |
+| 计算产研成本/净业绩 | 预算 | 自动计算成本、净业绩 |
+| 生成部门/个人业绩 | 净业绩拆分 | 自动创建业绩记录 |
+| 编辑更新部门业绩 | 净业绩拆分回款 | 更新前校验和计算 |
+
+代码示例：
+
+```java
+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("毛利不能为负数！");
+}
+```
+
+### 3.2 afterInsert（创建后）
+
+执行时机：记录已成功创建，ID 已生成。  
+典型用途：
+
+- 基于新记录 ID 创建关联记录
+- 发送创建通知
+- 初始化关联数据
+
+生产实例：
+
+| 触发器名称 | 对象 | 作用 |
+| --- | --- | --- |
+| 根据净业绩拆分生成净业绩拆分回款 | 回款明细 | 新建回款明细后自动生成回款记录 |
+
+代码示例：
+
+```java
+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);
+```
+
+### 3.3 afterUpsert（创建或更新后）
+
+执行时机：记录已成功保存（新增或修改）。  
+典型用途：
+
+- 汇总数据到父记录
+- 触发下游业务流程
+- 更新关联记录状态
+
+生产实例：
+
+| 触发器名称 | 对象 | 作用 |
+| --- | --- | --- |
+| 金额汇总到收款计划 | 回款明细 | 汇总回款金额到收款计划 |
+| 更新部门业绩字段 | 部门业绩 | 汇总各维度业绩数据 |
+| 更新回款明细 | 回款明细 | 重建净业绩拆分回款记录 |
+
+代码示例：
+
+```java
+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);
+}
+```
+
+### 3.4 afterDelete（删除后）
+
+执行时机：记录已成功删除。  
+典型用途：
+
+- 清理关联数据
+- 反向汇总更新
+
+生产实例：
+
+| 触发器名称 | 对象 | 作用 |
+| --- | --- | --- |
+| 回款明细删除 | 回款明细 | 删除后重新计算回款金额 |
+
+### 3.5 approval（审批时）
+
+执行时机：记录提交审批或审批通过时。  
+典型用途：
+
+- 审批前校验业务规则
+- 审批通过后执行业务操作
+
+生产实例：
+
+| 触发器名称 | 对象 | 作用 |
+| --- | --- | --- |
+| 更新拆分审批状态 | 预算 | 审批通过后回写状态 |
+| 订单审批判断 | 订单 | 审批时校验收款计划 |
+| 审批通过计算剩余欠款 | 费用报销 | 审批后计算欠款 |
+
+## 四、为什么要用触发器
+
+### 4.1 解决的核心问题
+
+| 问题 | 传统方案 | 触发器方案 |
+| --- | --- | --- |
+| 数据一致性 | 依赖用户手动操作，容易遗漏 | 自动执行，保证数据准确 |
+| 业务规则执行 | 前端校验可绕过 | 平台层统一执行，无法绕过 |
+| 跨对象联动 | 需要多次手动操作 | 自动关联更新 |
+| 审批流程复杂逻辑 | 审批流配置无法实现 | Java 代码实现任意逻辑 |
+| 实时性要求 | 定时任务有延迟 | 实时触发，立即执行 |
+
+### 4.2 对比其他方案
+
+| 方案 | 优点 | 缺点 | 适用场景 |
+| --- | --- | --- | --- |
+| 触发器 | 实时、自动、无法绕过 | 需要 Java 开发能力 | 核心业务逻辑 |
+| 审批流 | 配置简单、可视化 | 逻辑能力有限 | 简单审批流程 |
+| 工作流 | 可视化编排 | 复杂逻辑实现困难 | 跨系统流程编排 |
+| 定时任务 | 适合批量处理 | 有延迟 | 数据同步、报表生成 |
+
+## 五、典型业务场景
+
+### 5.1 财务业绩管理（核心场景）
+
+触发器链路：
+
+```text
+订单 (Order)
+│ approval 触发器：审批判断
+▼
+预算 (Budget)
+│ beforeUpsert: 计算产研成本/净业绩
+│ afterUpsert: 自动拆分/生成回款
+▼
+净业绩拆分 (jyjcf)
+│ beforeUpsert: 生成部门/个人业绩
+│ afterUpsert: 校验金额累计是否超预算
+▼
+部门业绩 (bmyj)
+│ afterUpsert: 更新部门业绩字段
+│ afterUpdate: 汇总部门资金池
+回款明细 (cloudccproceeddetail)
+│ afterInsert: 生成净业绩拆分回款
+│ afterUpsert: 金额汇总到收款计划
+│ afterUpsert: 更新回款明细
+│ afterDelete: 回款明细删除
+```
+
+关键触发器说明：
+
+1. 计算产研成本/净业绩（预算 - beforeUpsert）
+   - 自动计算预算收入、产研成本、净业绩
+   - 审批控制：毛利 < 0 阻止提交
+2. 生成部门/个人业绩（净业绩拆分 - beforeUpsert）
+   - 根据拆分规则自动创建业绩记录
+   - 按 owner 部门与年份关联业绩主数据
+3. 金额汇总到收款计划（回款明细 - afterUpsert）
+   - 汇总同一回款单下的明细金额
+   - 回填至收款计划（实际收款、余额、是否完成）
+4. 更新部门业绩字段（部门业绩 - afterUpsert）
+   - 按“类别 + 业绩计算方式”多维度汇总
+   - 计算目标完成率
+
+### 5.2 费用报销管理
+
+```text
+费用报销提交
+│
+▼
+[approval 触发器] 验证审批时校验预算
+│ 校验：报销金额 <= 预算余额
+▼
+审批通过
+│
+▼
+[approval 触发器] 审批通过计算剩余欠款
+│ 计算：剩余欠款 = 借款 - 报销
+```
+
+### 5.3 借款还款管理
+
+| 触发器 | 对象 | 时机 | 作用 |
+| --- | --- | --- | --- |
+| 借款单触发器 | 借款单 | beforeUpsert | 借款前校验、自动计算 |
+| 还款记录审批通过更新借款单 | 还款记录 | approval | 审批后更新借款单 |
+
+## 六、触发器开发最佳实践
+
+### 6.1 代码规范
+
+```java
+try {
+    CCObject record = (CCObject) data.get("record");
+    cs.update(record);
+} catch (Exception e) {
+    System.out.println("触发器执行失败：" + e.getMessage());
+    throw new Exception("业务校验失败：" + e.getMessage());
+}
+```
+
+### 6.2 性能优化
+
+```java
+// 字段过滤，只查询需要的字段
+List<CCObject> records = cs.cqueryByFields(
+    "Object__c",
+    "status__c='active'",
+    "id,name,amount__c"
+);
+
+// 批量操作使用 updateLt（避免递归）
+cs.updateLt(records);
+```
+
+### 6.3 避免递归触发
+
+```java
+// 方法 1：使用 updateLt
+cs.updateLt(records);
+
+// 方法 2：添加标志位
+if ("true".equals(System.getProperty("trigger.running"))) {
+    return;
+}
+System.setProperty("trigger.running", "true");
+cs.update(record);
+System.setProperty("trigger.running", "false");
+```
+
+## 七、触发器调试与监控
+
+### 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
+
+- 明确触发时机（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 | ❌ |
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudcc-cli",
-  "version": "2.2.8",
+  "version": "2.3.0",
   "description": "cloudcc-cli",
   "author": "cloudcc",
   "license": "ISC",

package/plugins/cc-test-001/cc-test-001.vue

@@ -0,0 +1,32 @@
+<template>
+  <div class="cc-container">
+     <HelloWorld />
+  </div>
+</template>
+
+<script>
+import HelloWorld from "./components/HelloWorld.vue";
+export default {
+components: {
+  HelloWorld,
+},
+data() {
+  return {
+    componentInfo: {
+      
+      component: "component-cc-test-001",
+      
+      compName: "compName-cc-test-001",
+      
+      compDesc: "Component description information",
+    }
+  };
+},
+};
+</script>
+<style lang="scss" scoped>
+.cc-container {
+  text-align: center;
+  padding: 8px;
+}
+</style>

package/plugins/cc-test-001/components/HelloWorld.vue

@@ -0,0 +1,11 @@
+
+<template>
+  <div>Hello world</div>
+</template>
+
+<script>
+export default {};
+</script>
+
+<style lang="scss" scoped>
+</style>

package/plugins/cc-test-001/config.json

@@ -0,0 +1,6 @@
+{
+  "component": "component-cc-test-001",
+  "compName": "compName-cc-test-001",
+  "compDesc": "Component description information",
+  "id": "69c38fd038e37e5c14b83922"
+}

package/schedule/CCdd/CCdd.java

@@ -0,0 +1,11 @@
+package schedule.CCdd;
+
+import com.cloudcc.core.*;
+
+public class CCdd extends CCSchedule {
+    public CCdd() {
+        // @SOURCE_CONTENT_START
+        System.out.print("hello World");
+        // @SOURCE_CONTENT_END
+    }
+}

package/schedule/CCdd/config.json

@@ -0,0 +1 @@
+{"name":"CCdd","version":"2"}

package/src/customPage/create.js

@@ -0,0 +1,77 @@
+const chalk = require('chalk');
+const { getPackageJson } = require('../../utils/config');
+const { post } = require('../../utils/http');
+const BaseUrl = 'https://developer.apis.cloudcc.cn';
+
+/**
+ * 新建自定义页面
+ *
+ * 用法：cc customPage create <pageLabel> <pageApi> [projectPath]
+ */
+async function createCustomPage(argvs) {
+    const pageLabel = argvs[2];
+    const pageApi = argvs[3];
+    const projectPath = argvs[4] || process.cwd();
+
+    if (!pageLabel || !pageApi) {
+        console.error();
+        console.error(chalk.red('Error: pageLabel and pageApi are required'));
+        console.error(chalk.yellow('Usage: cc customPage create <pageLabel> <pageApi> [projectPath]'));
+        console.error();
+        return;
+    }
+
+    const config = await getPackageJson(projectPath);
+    if (!config || !config.accessToken) {
+        console.error();
+        console.error(chalk.red('Error: Configuration not found or accessToken is missing'));
+        console.error();
+        return;
+    }
+
+    const devSvcDispatch = config.devSvcDispatch || '/devconsole';
+    const baseUrl = config.baseUrl || BaseUrl;
+
+    const header = {
+        appType: 'lightning-devconsole',
+        accessToken: config.accessToken,
+        source: 'lightning-devconsole',
+        version: 'public',
+    };
+
+    const body = {
+        id: '',
+        pageLabel,
+        pageApi,
+        pageContent: '[]',
+        orgId: config.orgId || '',
+        renderVersion: '',
+        compList: [],
+        canvasStyleData: JSON.stringify({ width: 100, height: 100, scale: 100, unit: '%' }),
+        isTemplate: 0,
+    };
+
+    console.error();
+    console.error(chalk.green(`Creating custom page "${pageLabel}" (api: ${pageApi}), please wait...`));
+
+    const res = await post(
+        `${baseUrl}${devSvcDispatch}/custom/pc/1.0/post/insertCustomPage`,
+        body,
+        header
+    );
+
+    if (res && res.returnCode == 200) {
+        const id = res.data?.id || res.data || '';
+        console.error(chalk.green(`Success! Custom page created.${id ? ' ID: ' + id : ''}`));
+        console.error();
+    } else {
+        const errMsg = res?.returnInfo || 'Unknown error';
+        console.error(chalk.red(`Fail: ${errMsg}`));
+        console.error();
+        throw new Error('Create Custom Page Failed: ' + errMsg);
+    }
+
+    return res;
+}
+
+module.exports = createCustomPage;

package/src/customPage/delete.js

@@ -0,0 +1,65 @@
+const chalk = require('chalk');
+const { getPackageJson } = require('../../utils/config');
+const { post } = require('../../utils/http');
+const BaseUrl = 'https://developer.apis.cloudcc.cn';
+
+/**
+ * 删除自定义页面
+ *
+ * 用法：cc customPage delete <id> [projectPath]
+ */
+async function deleteCustomPage(argvs) {
+    const id = argvs[2];
+    const projectPath = argvs[3] || process.cwd();
+
+    if (!id) {
+        console.error();
+        console.error(chalk.red('Error: Custom page ID is required'));
+        console.error(chalk.yellow('Usage: cc customPage delete <id> [projectPath]'));
+        console.error();
+        return;
+    }
+
+    const config = await getPackageJson(projectPath);
+    if (!config || !config.accessToken) {
+        console.error();
+        console.error(chalk.red('Error: Configuration not found or accessToken is missing'));
+        console.error();
+        return;
+    }
+
+    const devSvcDispatch = config.devSvcDispatch || '/devconsole';
+    const baseUrl = config.baseUrl || BaseUrl;
+
+    const header = {
+        appType: 'lightning-devconsole',
+        accessToken: config.accessToken,
+        source: 'lightning-devconsole',
+        version: 'public',
+    };
+
+    const body = { id };
+
+    console.error();
+    console.error(chalk.green(`Deleting custom page (ID: ${id}), please wait...`));
+
+    const res = await post(
+        `${baseUrl}${devSvcDispatch}/custom/pc/1.0/post/deleteCustomPage`,
+        body,
+        header
+    );
+
+    if (res && res.returnCode == 200) {
+        console.error(chalk.green(`Success! Custom page (ID: ${id}) deleted.`));
+        console.error();
+    } else {
+        const errMsg = res?.returnInfo || 'Unknown error';
+        console.error(chalk.red(`Fail: ${errMsg}`));
+        console.error();
+        throw new Error('Delete Custom Page Failed: ' + errMsg);
+    }
+
+    return res;
+}
+
+module.exports = deleteCustomPage;