cloudcc-cli 2.3.1 → 2.3.2

package/src/triggers/doc.js

@@ -1,378 +1,63 @@
 /**
- * triggers 文档统一入口（全量一次性输出）
+ * triggers 文档入口：正文均在 `docs/` 目录，本文件只负责按子命令读取并输出。
  */
 const fs = require("fs");
 const path = require("path");
 
-function generateFullMarkdownDoc() {
-    const lines = [
-        "# 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> opps1 = cs.cqueryByFields(",
-        "  \"Opportunity\",",
-        "  \"khmc__c='\" + record_new.get(\"id\") + \"'\",",
-        "  \"id,name,createdate\"",
-        ");",
-        "",
-        "// 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'\"",
-        ");",
-        "",
-        "// 5. 修改/删除",
-        "cs.update(opp);",
-        "cs.delete(opp);",
-        "",
-        "// 6. 发送邮件通知",
-        "SendEmail sendEmail = new SendEmail(userInfo);",
-        "sendEmail.sendMailFromSystem(toAddress, ccAddress, bccAddress, subject, content, isText);",
-        "```",
-        "",
-        "---",
-        "",
-        "## 三、触发器的触发时机详解",
-        "",
-        "### 3.1 beforeUpsert（创建或更新前）",
-        "- 执行时机：记录保存之前，数据尚未写入数据库",
-        "- 典型用途：自动计算字段、数据格式校验、阻止非法数据保存、自动填充默认值",
-        "- 生产实例：个人业绩/部门业绩赋值、计算产研成本/净业绩、生成部门/个人业绩",
-        "",
-        "```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(\"毛利不能为负数！\");",
-        "}",
-        "```",
-        "",
-        "### 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);",
-        "```",
-        "",
-        "### 3.3 afterUpsert（创建或更新后）",
-        "- 执行时机：记录保存成功后（新增或修改）",
-        "- 典型用途：汇总数据到父记录、触发下游流程、更新关联记录状态",
-        "- 生产实例：金额汇总到收款计划、更新部门业绩字段、更新回款明细",
-        "",
-        "```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);",
-        "}",
-        "```",
-        "",
-        "### 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：回款明细删除",
-        "```",
-        "",
-        "### 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\"",
-        ");",
-        "",
-        "// 推荐：批量更新，降低递归风险",
-        "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 | ❌ |",
-        "",
-        "文档生成时间：2026-03-24",
-        "基于 CloudCC 生产环境 25 个触发器实例分析",
-        "",
-    ];
+const DOCS_DIR = path.join(__dirname, "docs");
+const BACKEND_SDK_JAVA = path.join(__dirname, "..", "api", "backend-sdk-java.md");
 
-    const base = lines.join("\n");
-    const sdkPath = path.join(__dirname, "..", "api", "backend-sdk-java.md");
-    let sdkContent = "";
+function readDocFile(basename) {
+    return fs.readFileSync(path.join(DOCS_DIR, `${basename}.md`), "utf8");
+}
+
+/**
+ * 介绍文档（introduction.md）
+ * 用于了解 CloudCC 触发器的概念、定位、能力与适用场景。
+ */
+function getIntroductionDoc() {
+    return readDocFile("introduction");
+}
+
+/**
+ * 开发指导文档（devguide.md + backend-sdk-java.md）
+ * 用于触发器开发实践：触发时机、常见模式、性能与递归风险等；末尾拼接后端 SDK 速查。
+ */
+function getDevGuideDoc() {
+    const base = readDocFile("devguide").trimEnd();
+    let sdk = "";
     try {
-        sdkContent = fs.readFileSync(sdkPath, "utf8");
+        sdk = fs.readFileSync(BACKEND_SDK_JAVA, "utf8").trim();
     } catch (e) {
-        sdkContent = `# CloudCC 后端 SDK（Java）使用指南\n\n（未找到文件：${sdkPath}）\n`;
+        sdk = "";
     }
-
-    return [
-        base,
-        "",
-        "---",
-        "",
-        "## 附录：后端 SDK（Java）速查",
-        "",
-        "> 来源：`src/api/backend-sdk-java.md`",
-        "",
-        sdkContent.trim(),
-        "",
-    ].join("\n");
+    if (!sdk) {
+        return base;
+    }
+    return [base, "", "---", "", "## 附录：后端 SDK（Java）速查", "", sdk, ""].join("\n");
 }
 
-function doc() {
-    const content = generateFullMarkdownDoc();
-    console.log(content);
-    return content;
+/**
+ * cc doc triggers <introduction|devguide>
+ * @param {string[]} argvs [doc, type, introduction|devguide, ...]
+ */
+function doc(argvs) {
+    const subType = argvs[2];
+    const key = String(subType || "").trim().toLowerCase();
+    if (!key) {
+        throw new Error("cc doc triggers 需要子命令：introduction 或 devguide");
+    }
+    if (key === "introduction") {
+        const content = getIntroductionDoc();
+        console.log(content);
+        return content;
+    }
+    if (key === "devguide") {
+        const content = getDevGuideDoc();
+        console.log(content);
+        return content;
+    }
+    throw new Error(`doc 不支持的子命令: ${subType}，请使用 introduction 或 devguide`);
 }
 
-// 兼容旧调用方：统一返回全量文档
-doc.getEditGuide = doc;
-
 module.exports = doc;