neo-cmp-cli 1.13.13 → 1.13.16

package/template/neo-bi-cmps/docs/neo-backend-dev/SKILL.md

@@ -1,188 +0,0 @@
----
-name: neo-backend-dev
-description: Neo 后端 PaaS 开发技能，辅助在 NeoCRM 平台上进行 Java 后端开发。当用户需要：(1) 创建项目并配置后端开发环境，(2) 开发 Trigger 触发器，(3) 开发自定义 REST API，(4) 开发计划作业（定时任务），(5) 开发流程扩展（审批流/工作流），(6) 使用 SDK 工具类（数据操作、HTTP请求、缓存、异步），(7) 打包上传/下载/卸载后端代码包，(8) 获取和查询实体模型，(9) 更新 model.jar 时，使用此技能。
----
-
-# Neo 后端 PaaS 开发
-
-辅助完成 NeoCRM PaaS 平台 Java 后端开发全流程。
-
-## 前置条件
-
-- 已全局安装 neo-cmp-cli：`npm i -g neo-cmp-cli`（用于项目创建和登录认证）
-- Node.js 环境
-- JDK 1.8（后端代码编译）
-
-## 重要约定
-
-- `neo login -e production` 默认登录生产环境。执行登录前必须询问用户要登录到哪个环境。环境参数：`production`、`gray`、`sandbox`、`cd`、`tencentuat`、`custom`
-- `neo login` 执行后自动打开浏览器授权，轮询 `.neo-cli/token.json` 确认登录成功
-- 执行平台操作时直接执行，未登录失败后再询问环境并登录重试
-- Java 包路径必须三级且以 `other` 开头（如 `other.xsy.account`），不能生成 4 级或以上
-- 仅支持第三方包：fastJson + commons-lang
-
-## 核心工作流
-
-### 1. 创建项目
-
-如果用户未指定项目名称，先询问。未指定路径则告知默认位置并询问是否修改。
-
-```bash
-neo create project -n <项目名称>
-```
-
-项目创建后将 `neo.config.js` 中 `neoConfig` 改为正式环境：
-```javascript
-neoConfig: {
-  neoBaseURL: 'https://crm.xiaoshouyi.com',
-  loginURL: 'https://login.xiaoshouyi.com/auc/oauth2/auth',
-  tokenURL: 'https://login.xiaoshouyi.com/auc/oauth2/token',
-},
-```
-
-### 2. 登录租户
-
-项目创建后，先询问用户要登录到哪个环境（默认 production），执行登录：
-```bash
-neo login -e <env>
-```
-轮询 `.neo-cli/token.json` 确认登录成功。
-
-### 3. 安装前端依赖（仅开发前端组件时需要）
-
-后端代码开发和部署不需要执行 `npm install`，仅在需要开发前端组件时才执行：
-```bash
-cd <项目目录>
-npm install
-```
-
-### 4. 后端代码开发
-
-后端代码统一放在 `src/server-scripts/` 下，按代码包组织：
-
-```
-<项目>/src/server-scripts/
-  <代码包简称>/
-    other/
-      <company>/
-        <module>/                # 三级包名，如 other/xsy/account
-          XxxTrigger.java
-          XxxApi.java
-    scriptTrigger.xml            # Trigger 配置
-    apiUrl.xml                   # 自定义 API 路由配置
-```
-
-### 后端开发参考文档
-
-根据需求选择对应参考：
-
-- Trigger 触发器 → [references/01-Trigger开发.md](references/01-Trigger开发.md)
-- 自定义 REST API → [references/02-自定义API开发.md](references/02-自定义API开发.md)
-- SDK 工具类 → [references/03-SDK工具类接口.md](references/03-SDK工具类接口.md)
-- 计划作业 → [references/04-计划作业开发.md](references/04-计划作业开发.md)
-- 页面开发 → [references/05-页面开发.md](references/05-页面开发.md)
-- 流程扩展 → [references/06-流程扩展开发.md](references/06-流程扩展开发.md)
-- 平台能力概览 → [references/PaaS平台开发手册解读.md](references/PaaS平台开发手册解读.md)
-
-### 关键限制
-
-| 限制项 | 值 |
-|--------|-----|
-| 同步脚本最大运行时长 | 15 秒 |
-| 异步脚本最大运行时长 | 90 秒 |
-| 脚本最大内存 | 512 MB |
-| 单次 DML 最大数据量 | 10,000 条 |
-| commonHttpClient 最大调用次数 | 50 次/脚本 |
-| 缓存最大大小 | 200 KB |
-
-## 部署后端代码包
-
-```bash
-python3 scripts/deploy_server_script.py <项目目录> <代码包简称> <Java包名>
-```
-
-示例：`python3 scripts/deploy_server_script.py NEOTrail 客户管理 other.xsy.account`
-
-脚本自动：打包 ZIP → 检查/创建代码包 → 上传 → 安装 → 清理临时文件。
-
-## 下载服务端代码包
-
-如果用户未指定代码包名称（Java 包名），必须先询问。
-
-```bash
-python3 scripts/download_server_script.py <项目目录> <Java包名> [代码包简称]
-```
-
-本地已存在同名目录时会覆盖更新。
-
-## 创建计划作业
-
-代码包部署后，需要在 NeoCRM 系统后台手动创建计划作业任务（此接口需要浏览器 session 认证，无法通过 OAuth API 自动化）：
-
-1. 登录 NeoCRM 平台
-2. 进入系统后台 → 开发 → 计划作业
-3. 新建计划作业，填写以下信息：
-   - 任务名称
-   - 选择代码包和对应的 ScheduleJob 类
-   - 执行类型：自定义循环周期（executeType=3）
-   - 执行间隔：小时数（0-24）+ 分钟数（仅支持 5 的倍数：0,5,10,15...55）
-   - 生效时间范围
-4. 启用计划作业
-
-提示用户完成上述手动操作后继续。
-
-## 更新 model.jar
-
-```bash
-python3 scripts/update_model_jar.py <项目目录>
-```
-
-## 卸载代码包
-
-```bash
-python3 scripts/uninstall_server_script.py <项目目录> <Java包名> [--force]
-```
-
-## 获取实体模型
-
-### 生成实体字典
-```bash
-python3 scripts/gen_entitylist.py <项目目录>
-```
-
-### 查询实体字段
-1. 在 `src/entity-model/entitylist.md` 中查找匹配实体
-2. 检查 `src/entity-model/<apiKey>.md` 是否存在
-3. 不存在则运行：`python3 scripts/gen_entity_desc.py <项目目录> <apiKey>`
-
-## 平台 API 参考
-
-所有 API 携带 `Authorization: Bearer <access_token>`（上传文件接口），其他接口直接传 `access_token`。
-
-- 获取 model.jar：`GET /rest/metadata/v2.0/scripts/packages/model/jar/url`
-- 更新 model.jar：`POST /rest/metadata/v2.0/scripts/packages/model/jar`
-- 获取实体列表：`GET /rest/metadata/v2.0/xobjects/filter?custom=<true|false>&active=true`
-- 获取实体字段：`GET /rest/metadata/v2.0/xobjects/<apiKey>/items`
-- 获取业务类型列表：`GET /rest/data/v2.0/xobjects/<xObjectApiKey>/busiType`
-- 下载代码包：`GET /rest/metadata/v2.0/scripts/packages?packageName=<包名>`
-- 创建代码包：`POST /rest/metadata/v2.0/scripts/packages`
-- 上传代码包：`POST /rest/metadata/v2.0/scripts/packages/files?packageName=<包名>`
-- 安装代码包：`POST /rest/metadata/v2.0/scripts/packages/installations`
-- 卸载代码包：`DELETE /rest/metadata/v2.0/scripts/packages/installations/<包名>?force=<bool>`
-- 创建计划作业：`POST /rest/metadata/v2.0/dx/logic/jobDetail`
-- 更新计划作业：`PATCH /rest/metadata/v2.0/dx/logic/jobDetail/<jobId>`
-
-## 注意事项
-
-- Java 类名不能以 "test" 结尾
-- Java 文件必须 UTF-8 无 BOM 编码
-- Trigger 的 DataResult 数量必须与 TriggerRequest 数据量一致
-- Package 名称必须三级且以 other 开始
-- API 调用默认不触发 Trigger
-- `getAttribute()` 返回 Object 类型，不能直接强转 String，必须用 `obj != null ? obj.toString() : ""`
-- CRM 查询 SQL 不支持 `WHERE 1=1`，应使用 `WHERE id > 0` 作为基础条件
-- `RkhdHttpClient.execute()` 需要 `ResponseBodyHandler` 第二参数，且沙箱禁止 `System.getProperty()`
-- 内部平台 API（如获取商机阶段）建议由前端直接调用，后端 SDK 调用内部 API 存在限制
-- 自定义 API 的实际调用路径是 `/rest/data/v2.0/scripts/api/{baseUrl}/{path}`，不是 `/rest/custom/v2.0/`
-- 开发涉及业务对象的功能前，必须先通过 `gen_entity_desc.py` 获取实体的真实字段模型，避免字段名错误
-- 授权配置详见 [references/auth-config.md](references/auth-config.md)

package/template/neo-bi-cmps/docs/neo-backend-dev/references/01-Trigger/345/274/200/345/217/221.md

@@ -1,183 +0,0 @@
-# 技能包：Trigger 开发
-
-## 概述
-
-Trigger（触发器）用于在业务数据操作保存至数据库之前（before）或之后（after）增加自定义业务逻辑。
-
-## 适用场景
-
-- 创建数据时根据业务规则校验数据
-- 编辑数据后自动同步至第三方系统
-- 数据保存前自动填充/修改字段值
-- 批量数据的查重校验
-
-## 支持的操作
-
-| 操作 | 说明 |
-|------|------|
-| add | 创建 |
-| update | 更新 |
-| delete | 删除 |
-| transfer | 转移 |
-| lock | 锁定 |
-| unlock | 解锁 |
-| recover | 从回收站恢复 |
-
-## 代码模板
-
-### 前置 Trigger（before）
-
-```java
-package other.{company}.{project};
-
-import com.rkhd.platform.sdk.exception.ScriptBusinessException;
-import com.rkhd.platform.sdk.log.Logger;
-import com.rkhd.platform.sdk.log.LoggerFactory;
-import com.rkhd.platform.sdk.model.XObject;
-import com.rkhd.platform.sdk.trigger.*;
-
-import java.util.ArrayList;
-import java.util.List;
-
-/**
- * 前置 Trigger 模板
- * 在数据保存到数据库之前执行，可修改数据或阻止保存
- */
-public class BeforeTriggerTemplate implements Trigger {
-
-    private static final Logger LOG = LoggerFactory.getLogger();
-
-    @Override
-    public TriggerResponse execute(TriggerRequest request) throws ScriptBusinessException {
-        LOG.info("BeforeTrigger 开始执行, 操作: " + request.getOperate());
-
-        List<DataResult> results = new ArrayList<>();
-
-        for (XObject xObject : request.getDataList()) {
-            try {
-                // === 在此编写业务逻辑 ===
-
-                // 示例：修改字段值
-                // xObject.setAttribute("fieldApiName__c", "newValue");
-
-                // 示例：校验数据，不通过则阻止保存
-                // String name = xObject.getAttribute("name");
-                // if (name == null || name.isEmpty()) {
-                //     results.add(new DataResult(false, "名称不能为空", xObject));
-                //     if (!request.getPartialSuccess()) {
-                //         return new TriggerResponse(false, "数据校验失败", results);
-                //     }
-                //     continue;
-                // }
-
-                results.add(new DataResult(true, "", xObject));
-            } catch (Exception e) {
-                LOG.error("处理数据异常: " + e.getMessage());
-                results.add(new DataResult(false, e.getMessage(), xObject));
-            }
-        }
-
-        return new TriggerResponse(true, "", results);
-    }
-}
-```
-
-### 后置 Trigger（after）
-
-```java
-package other.{company}.{project};
-
-import com.rkhd.platform.sdk.exception.ScriptBusinessException;
-import com.rkhd.platform.sdk.log.Logger;
-import com.rkhd.platform.sdk.log.LoggerFactory;
-import com.rkhd.platform.sdk.model.XObject;
-import com.rkhd.platform.sdk.trigger.*;
-
-import java.util.ArrayList;
-import java.util.List;
-
-/**
- * 后置 Trigger 模板
- * 在数据保存到数据库之后执行，可用于数据同步、通知等
- */
-public class AfterTriggerTemplate implements Trigger {
-
-    private static final Logger LOG = LoggerFactory.getLogger();
-
-    @Override
-    public TriggerResponse execute(TriggerRequest request) throws ScriptBusinessException {
-        LOG.info("AfterTrigger 开始执行, 操作: " + request.getOperate());
-
-        List<DataResult> results = new ArrayList<>();
-
-        for (XObject xObject : request.getDataList()) {
-            try {
-                LOG.info("处理数据 ID: " + xObject.getId());
-
-                // === 在此编写业务逻辑 ===
-
-                // 示例：同步数据到外部系统
-                // syncToExternalSystem(xObject);
-
-                results.add(new DataResult(true, "成功", xObject));
-            } catch (Exception e) {
-                LOG.error("处理数据异常: " + e.getMessage());
-                results.add(new DataResult(false, e.getMessage(), xObject));
-            }
-        }
-
-        return new TriggerResponse(true, "成功", results);
-    }
-}
-```
-
-### 使用 TriggerContext 在 before/after 间传参
-
-```java
-// Before Trigger 中设置上下文
-TriggerContext triggerContext = new TriggerContext();
-triggerContext.set("key", "value");
-return new TriggerResponse(true, "", results, triggerContext);
-
-// After Trigger 中获取上下文
-TriggerContext triggerContext = request.getTriggerContext();
-String value = triggerContext.get("key");
-```
-
-## 配置文件模板
-
-scriptTrigger.xml：
-
-```xml
-<?xml version="1.0" encoding="utf-8"?>
-<configs>
-  <config>
-    <!-- 前置 Trigger -->
-    <trigger>
-      <object>{objectApiKey}__c</object>
-      <operate>add</operate>
-      <position>before</position>
-      <order>1</order>
-      <class>other.{company}.{project}.trigger.BeforeTriggerTemplate</class>
-    </trigger>
-    <!-- 后置 Trigger -->
-    <trigger>
-      <object>{objectApiKey}__c</object>
-      <operate>add</operate>
-      <position>after</position>
-      <order>1</order>
-      <class>other.{company}.{project}.trigger.AfterTriggerTemplate</class>
-    </trigger>
-  </config>
-</configs>
-```
-
-## 开发注意事项
-
-1. **类名不能以 "test" 结尾**
-2. **Java 文件必须 UTF-8 无 BOM 编码**
-3. **DataResult 数量必须与 TriggerRequest 数据量一致**
-4. **return 必须返回 TriggerResponse 对象**
-5. **Package 名称必须三级且以 other 开始**（如 `other.xsy.demo`），不能生成4级或以上的包名
-6. **同步脚本最大运行时长 15 秒**，超时会被自动终止
-7. **API 调用默认不触发 Trigger**

package/template/neo-bi-cmps/docs/neo-backend-dev/references/02-/350/207/252/345/256/232/344/271/211API/345/274/200/345/217/221.md

@@ -1,196 +0,0 @@
-# 技能包：自定义 API 开发
-
-## 概述
-
-自定义 API 允许开发者根据业务需求封装自定义的 REST API 接口，供外部系统或页面代码调用。
-
-## 适用场景
-
-- 封装复杂的业务查询逻辑为 API
-- 为外部系统提供数据集成接口
-- 为自定义页面提供后端数据服务
-- 实现跨对象的复杂数据操作
-
-## 代码模板
-
-### GET 请求 API
-
-```java
-package other.{company}.{project};
-
-import com.rkhd.platform.sdk.api.annotations.RequestMethod;
-import com.rkhd.platform.sdk.api.annotations.RestApi;
-import com.rkhd.platform.sdk.api.annotations.RestMapping;
-import com.rkhd.platform.sdk.api.annotations.RestQueryParam;
-import com.rkhd.platform.sdk.exception.ApiEntityServiceException;
-import com.rkhd.platform.sdk.log.Logger;
-import com.rkhd.platform.sdk.log.LoggerFactory;
-import com.rkhd.platform.sdk.model.QueryResult;
-import com.rkhd.platform.sdk.model.XObject;
-import com.rkhd.platform.sdk.service.XObjectService;
-
-import com.alibaba.fastjson.JSONArray;
-import com.alibaba.fastjson.JSONObject;
-
-import java.util.List;
-
-@RestApi(baseUrl = "/custom")
-public class CustomGetApi {
-
-    private Logger log = LoggerFactory.getLogger();
-
-    /**
-     * GET 请求示例
-     * 访问路径: /rest/data/v2.0/scripts/api/getData?keyword=xxx
-     */
-    @RestMapping(value = "/getData", method = RequestMethod.GET)
-    public String handleGet(@RestQueryParam("keyword") String keyword)
-            throws ApiEntityServiceException {
-        try {
-            log.info("收到查询请求, keyword: " + keyword);
-
-            // 查询数据
-            String sql = "SELECT id, name FROM account WHERE name LIKE '%" + keyword + "%' LIMIT 10";
-            QueryResult queryResult = XObjectService.instance().query(sql);
-            List<XObject> records = queryResult.getRecords();
-
-            // 构建返回结果
-            JSONObject result = new JSONObject();
-            JSONArray dataArray = new JSONArray();
-
-            if (records != null) {
-                for (XObject record : records) {
-                    JSONObject item = new JSONObject();
-                    item.put("id", record.getId());
-                    item.put("name", record.getAttribute("name"));
-                    dataArray.add(item);
-                }
-            }
-
-            result.put("code", "200");
-            result.put("data", dataArray);
-            result.put("total", dataArray.size());
-            return result.toJSONString();
-
-        } catch (Exception e) {
-            log.error("查询异常: " + e.getMessage());
-            JSONObject error = new JSONObject();
-            error.put("code", "500");
-            error.put("message", e.getMessage());
-            return error.toJSONString();
-        }
-    }
-}
-```
-
-### POST 请求 API
-
-```java
-package other.{company}.{project};
-
-import com.rkhd.platform.sdk.api.annotations.RequestMethod;
-import com.rkhd.platform.sdk.api.annotations.RestApi;
-import com.rkhd.platform.sdk.api.annotations.RestMapping;
-import com.rkhd.platform.sdk.api.annotations.RestBeanParam;
-import com.rkhd.platform.sdk.exception.ApiEntityServiceException;
-import com.rkhd.platform.sdk.log.Logger;
-import com.rkhd.platform.sdk.log.LoggerFactory;
-import com.rkhd.platform.sdk.model.XObject;
-import com.rkhd.platform.sdk.service.XObjectService;
-
-import com.alibaba.fastjson.JSON;
-import com.alibaba.fastjson.JSONObject;
-
-@RestApi(baseUrl = "/custom")
-public class CustomPostApi {
-
-    private Logger log = LoggerFactory.getLogger();
-
-    /**
-     * POST 请求示例
-     * 访问路径: /rest/data/v2.0/scripts/api/createData
-     * Content-Type: application/json
-     * 注意：POST方法参数必须使用 @RestBeanParam(name="xxx") 注解
-     */
-    @RestMapping(value = "/createData", method = RequestMethod.POST)
-    public String handlePost(@RestBeanParam(name = "requestBody") String requestBody)
-            throws ApiEntityServiceException {
-        try {
-            log.info("收到创建请求, body: " + requestBody);
-
-            JSONObject body = JSON.parseObject(requestBody);
-
-            // 创建数据
-            // XObject xObject = new CustomEntity1__c();
-            // xObject.setAttribute("name", requestBody.getString("name"));
-            // xObject.setAttribute("entityType", MetadataService.instance()
-            //     .getBusiType(xObject.getApiKey(), "defaultBusiType").getId());
-            // XObjectService.instance().insert(xObject);
-
-            JSONObject result = new JSONObject();
-            result.put("code", "200");
-            result.put("message", "创建成功");
-            return result.toJSONString();
-
-        } catch (Exception e) {
-            log.error("创建异常: " + e.getMessage());
-            JSONObject error = new JSONObject();
-            error.put("code", "500");
-            error.put("message", e.getMessage());
-            return error.toJSONString();
-        }
-    }
-}
-```
-
-## 配置文件模板
-
-scriptTrigger.xml：
-
-```xml
-<?xml version="1.0" encoding="utf-8"?>
-<configs>
-  <config>
-    <customApi>
-      <class>other.{company}.{project}.api.CustomGetApi</class>
-    </customApi>
-    <customApi>
-      <class>other.{company}.{project}.api.CustomPostApi</class>
-    </customApi>
-  </config>
-</configs>
-```
-
-## 调用方式
-
-### 外部调用
-
-```
-GET  https://api.xiaoshouyi.com/rest/data/v2.0/scripts/api/getData?keyword=xxx
-POST https://api.xiaoshouyi.com/rest/data/v2.0/scripts/api/createData
-
-Header:
-  Authorization: Bearer {access_token}
-  Content-Type: application/json
-```
-
-### 页面代码中调用（NeoLappSdk.js）
-
-```javascript
-lapp.connection.invoke({
-    url: '/rest/data/v2.0/scripts/api/getData?keyword=test',
-    method: 'GET'
-}).then(
-    res => { console.log(res); },
-    err => { console.log(err); }
-)
-```
-
-## 注意事项
-
-1. 自定义 API 入参最大值 **15 MB**
-2. 外部并发调用限制：用户级 **15 次/秒**，租户级 **50 次/秒**
-3. 第三方包仅支持 **fastJson** 和 **commons-lang**
-4. POST 方法参数必须使用 `@RestBeanParam(name="xxx")` 注解，不能直接用裸参数
-5. `QueryResult.getRecords()` 返回 `List<XObject>`，没有 `getTotalSize()` 方法，需通过 `records.size()` 或单独 count 查询获取总数
-6. Package 名称必须三级且以 other 开始（如 `other.xsy.pipeline`），不能生成四级包名