kcode-pi 0.1.0

package/vendor/kingdee-skills/ok-cosmic/references/base/sdk/sdk-algo.md

@@ -0,0 +1,67 @@
+# 内存计算框架 (DataSet / Algo)
+
+## TL;DR
+- 适用：`DataSet` 内存计算、过滤、聚合、Join 和流式处理。
+- 先抓：`DataSet` 是流式资源，做完 `select/filter/groupBy` 后记得关闭。
+- 跳转：如果只是简单 ORM 取数，先读 `sdk-orm-access.md` 或 `adv/query-dataset.md`。
+- 继续读全文：当你要写聚合、HashJoin 或高性能数据转换时。
+
+## 概述
+Algo 是苍穹平台的内存计算引擎，遵循 SQL-92 标准，提供类 SQL 的数据处理能力。`DataSet` 是其核心数据结构，采用流式处理（Pipeline），具备严格的内存控制和磁盘交换机制，能有效防止大数据量处理时的 OOM。
+
+## 核心类
+- **`kd.bos.algo.DataSet`**: 核心结果集接口，支持转换（Transform）和动作（Action）。
+- **`kd.bos.algo.Row`**: 行数据访问器（注意：Row 是虚对象，不可缓存）。
+- **`kd.bos.algo.Algo`**: 算法引擎入口。
+- **`kd.bos.algo.GroupbyDataSet`**: 分组聚合构造器。
+- **`kd.bos.algo.JoinDataSet`**: 数据连接构造器。
+- **`kd.bos.algo.HashTable`**: 内存哈希表，用于高性能 HashJoin。
+
+## 常用 API 方法
+### 1. 转换 (Transform) - 返回新 DataSet
+- `select(String fields)`: 选择或重命名字段。
+- `addField(String expression, String alias)`: 增加计算字段。
+- `where(String filter)`: SQL 风格过滤。
+- `groupBy(String[] fields)`: 分组，后接聚合操作。
+- `orderBy(String orderBys)`: 排序。
+- `union(DataSet other)`: 合并数据集。
+- `copy()`: 复制数据集（支持多次遍历）。
+
+### 2. 动作 (Action) - 消费并关闭 DataSet
+- `count()`: 获取总行数。
+- `cache(CacheHint hint)`: 缓存到 Redis，支持分页读取。
+- `toCollection()`: 转为 `DynamicObjectCollection` (慎用)。
+
+## 示例代码
+### 1. 基础转换与聚合
+```java
+try (DataSet ds = QueryServiceHelper.queryDataSet("key", "entity", "id, qty, price", null, null)) {
+    DataSet result = ds.addField("qty * price", "amount")
+                       .where("amount > 1000")
+                       .groupBy(new String[]{"id"})
+                       .sum("amount", "total")
+                       .finish();
+    while (result.hasNext()) {
+        Row row = result.next();
+        // 处理结果...
+    }
+}
+```
+
+### 2. 高性能 HashJoin
+```java
+HashTable detailTable = dsDetail.toHashTable("order_id");
+DataSet joined = dsHeader.hashJoin(detailTable, "id", new String[]{"qty", "price"}, true);
+```
+
+## 实践建议
+1. **优先使用 DataSet**：在处理报表、大批量计算或跨库关联时，应彻底弃用 `DynamicObject`，转为 `DataSet` 编程。
+2. **资源释放**：必须使用 `try-with-resources` 或 `AlgoContext` 确保 `DataSet` 及时关闭。
+3. **及早过滤**：在 `join` 或 `groupBy` 之前先 `where`，减少中间数据集规模。
+4. **大表驱动小表**：在使用普通 `join` 时，尽量将较小的表放在右侧（右侧优先物化并判断规模）。
+
+## 常见坑位
+1. **流式单次遍历**：`DataSet` 默认只能遍历一遍，若需二次遍历，必须先调用 `copy()` 或 `cache()`。
+2. **跨线程禁止**：`DataSet` 绑定了创建线程的资源，严禁跨线程传递和使用。
+3. **字段引用**：在 `join` 后的 `select` 中，若两表有同名列，必须带上表别名，如 `orders.billno`。
+4. **Row 缓存**：严禁将 `ds.next()` 返回的 `Row` 对象存入外部 List 中，因为它只是一个指向当前行数据的游标。

package/vendor/kingdee-skills/ok-cosmic/references/base/sdk/sdk-cache.md

@@ -0,0 +1,63 @@
+# 缓存服务 (Cache Service)
+
+## TL;DR
+- 适用：页面缓存和应用缓存，解决跨操作临时数据与应用级共享数据。
+- 先抓：表单内优先 `IPageCache`，跨页面/应用再用 `AppCache`。
+- 跳转：并发互斥不是缓存，去锁或网控文档；持久化数据也不是本页。
+- 继续读全文：当你要确认作用域、有效期、示例和常见误用时。
+
+## 概述
+金蝶云苍穹提供了分布式缓存服务，支持跨微服务节点的数据共享。根据数据的生命周期和隔离级别，主要分为**页面缓存**（随表单关闭而销毁）和**应用缓存**（按应用隔离，支持自定义有效期）。
+
+## 核心类
+- **`kd.bos.form.IPageCache`**: 页面级缓存接口，仅限表单插件使用。
+- **`kd.bos.entity.cache.AppCache`**: 获取应用级缓存的工具类。
+- **`kd.bos.entity.cache.IAppCache`**: 应用级缓存接口。
+
+## 常用 API 方法
+### 页面缓存 (this.getPageCache())
+- `put(String key, String value)`: 存入单条数据。
+- `put(Map<String, String> values)`: 批量存入。
+- `get(String key)`: 读取数据。
+
+### 应用缓存 (AppCache.get("appId"))
+- `put(String key, Object value)`: 存入数据，默认 1 小时过期。
+- `put(String key, Object value, int seconds)`: 存入带自定义过期时间的数据。
+- `get(String key, Class<T> clazz)`: 类型安全地读取数据。
+- `remove(String key)`: 显式移除缓存。
+
+## 示例代码
+```java
+// 1. 页面缓存示例（在表单插件中）
+public class MyFormPlugin extends AbstractFormPlugin {
+    public void cacheTempData() {
+        this.getPageCache().put("temp_token", "ABC-123");
+        String token = this.getPageCache().get("temp_token");
+    }
+}
+
+// 2. 应用缓存示例（通用场景）
+import kd.bos.entity.cache.AppCache;
+import kd.bos.entity.cache.IAppCache;
+
+public class CacheDemo {
+    public void handleAppCache() {
+        IAppCache cache = AppCache.get("my_app_id");
+        // 存入缓存，有效期 10 分钟
+        cache.put("user_config", configObj, 600);
+        
+        // 读取缓存
+        MyConfig config = cache.get("user_config", MyConfig.class);
+    }
+}
+```
+
+## 实践建议
+1. **优先批量操作**：缓存访问虽然快，但高频的网络交互仍有开销，存入多条数据时优先使用批量接口。
+2. **应用编码隔离**：调用 `AppCache.get()` 时，务必传入正确的 `appId`，以实现各应用间的数据隔离。
+3. **及时释放**：对于不再需要的应用缓存，应主动调用 `remove`，防止缓存堆积。
+
+## 常见坑位
+1. **缓存一致性**：由于是分布式缓存，注意在多节点并发更新同一 Key 时可能产生的数据覆盖问题。
+2. **序列化要求**：存入 `AppCache` 的对象必须支持序列化（实现 `Serializable` 接口）。
+3. **大小限制**：严禁将超大对象（如数万行的 List）放入缓存，这会显著增加网络传输和 Redis 内存压力。

package/vendor/kingdee-skills/ok-cosmic/references/base/sdk/sdk-dynamic-model-svc.md

@@ -0,0 +1,82 @@
+# 动态领域模型 - 公共服务 (ServiceHelpers 全集)
+
+## TL;DR
+- 适用：各种 `ServiceHelper` 的快速索引，含存取、操作、编号、基础资料和微服务分发。
+- 先抓：按场景先选对 Helper，再决定是否继续查具体签名。
+- 跳转：若已知道确切 Helper 或要用团队封装，优先看 `adv` 文档或脚本验证。
+- 继续读全文：当你要找公共服务入口、典型示例或跨微服务调用方式时。
+
+## 概述
+苍穹平台提供了一系列 ServiceHelper，作为分布式环境下的基础工具类。它们封装了复杂的跨服务调用，使开发者能够以本地静态调用的方式完成数据存取、元数据获取、业务操作触发、编码生成及微服务调用。
+
+## 核心类与用途
+| 分类 | 核心类 | 说明 |
+| :--- | :--- | :--- |
+| **数据存取** | `BusinessDataServiceHelper` | 结构化对象加载（含缓存、主子表）。 |
+| **数据查询** | `QueryServiceHelper` | 轻量级查询、DataSet 获取。 |
+| **持久化操作** | `SaveServiceHelper` / `DeleteServiceHelper` | 物理层的数据新增、修改、物理/逻辑删除。 |
+| **业务逻辑** | `OperationServiceHelper` | 执行单据生命周期操作（审核、提交等）。 |
+| **编码/规则** | `CodeRuleServiceHelper` | 自动生成符合编码规则的单据编号。 |
+| **基础资料** | `BaseDataServiceHelper` | 基础资料的分配、自动补值及权限过滤。 |
+| **跨微服务** | `DispatchServiceHelper` | 调用其他微服务、二开服务或平台服务。 |
+| **系统/环境** | `SystemParamServiceHelper` / `TimeServiceHelper` | 获取系统参数、全局统一时间。 |
+
+## 常用 API 方法
+
+### 1. 编码规则 (CodeRuleServiceHelper)
+- `getNumber(String entityId, DynamicObject data)`: 获取单据编号。
+- `getBatchCodes(String entityId, int count)`: 批量获取编码。
+
+### 2. 基础资料分配与补值 (BaseDataServiceHelper)
+- `assign(String entityId, long[] ids, long[] orgIds)`: 将基础资料分配到目标组织。
+- `queryBaseDataFromCache(...)`: 高性能获取基础资料字段值。
+
+### 3. 微服务分发与工厂 (DispatchServiceHelper / ServiceFactory)
+- **调用业务微服务**: `DispatchServiceHelper.invokeBizService(cloud, app, svc, method, args)`。
+- **调用二开服务**: `DispatchServiceHelper.invokeService(factory, app, svc, method, args)`。
+- **自定义工厂模式**:
+```java
+public class ServiceFactory {
+    public static Object getService(String serviceName) {
+        String impl = "com.isv.mservice.impl." + serviceName + "Impl";
+        return TypesContainer.getOrRegisterSingletonInstance(impl);
+    }
+}
+```
+
+### 4. 数据删除 (DeleteServiceHelper)
+- `delete(String entityId, Object[] ids)`: 物理删除。
+- `deleteOperate(...)`: 执行删除操作（触发删除插件）。
+
+### 5. 系统参数 (SystemParamServiceHelper)
+- `getValue(String paramKey)`: 获取全局参数。
+- `getValue(String paramKey, long orgId)`: 获取组织隔离的参数值。
+
+## 示例代码
+### 1. 自动生成单据编号
+```java
+// 创建新对象并自动根据规则填入编号
+DynamicObject bill = BusinessDataServiceHelper.newDynamicObject("my_entity");
+String billNo = CodeRuleServiceHelper.getNumber("my_entity", bill);
+bill.set("billno", billNo);
+```
+
+### 2. 调用外部微服务
+```java
+// 调用“供应链云”下的“库存服务”
+Object result = DispatchServiceHelper.invokeBizService(
+    "scm", "im", "StockService", "queryInventory", 
+    new Object[]{materialId, orgId}
+);
+```
+
+## 实践建议
+1. **优先使用 Helper**：ServiceHelper 系列是苍穹开发的最标准入口，具备良好的事务和权限兼容性。
+2. **时间统一性**：获取业务时间务必使用 `TimeServiceHelper.getSystemDate()`，以保证在集群环境下所有节点的时间严格一致。
+3. **参数缓存**：系统参数读取较为频繁，`SystemParamServiceHelper` 内部已有良好缓存，无需在业务层二次缓存。
+4. **基础资料**：你在处理基础资料（BaseData）相关的业务动作时，请务必先查阅 `BaseDataServiceHelper` 是否已有现成的方法。
+
+## 常见坑位
+1. **删除服务误用**：`DeleteServiceHelper.delete` 是物理删除，且不触发任何插件；对于业务单据，建议始终使用 `deleteOperate`。
+2. **跨云调用超时**：使用 `DispatchServiceHelper` 调用时，若目标服务负载过高，可能导致当前线程挂死，建议对不稳定接口增加异步处理。
+3. **编码规则失效**：调用 `getNumber` 前，单据对象中必须包含规则中定义的“条件字段”（如组织、业务类型），否则生成的编码可能不符合预期。

package/vendor/kingdee-skills/ok-cosmic/references/base/sdk/sdk-dynamic-object.md

@@ -0,0 +1,70 @@
+# 动态领域模型 - 数据包 (DynamicObject)
+
+## TL;DR
+- 适用：原生 `DynamicObject` 读写方式以及基础资料、分录字段访问。
+- 先抓：先理解主子表和基础资料字段在运行时的真实结构。
+- 跳转：更安全的团队推荐写法优先读 `adv/dynamic-object.md`。
+- 继续读全文：当你要写原生 getter/setter、处理基础资料字段或排查类型坑时。
+
+## 概述
+`DynamicObject` 是苍穹平台的核心数据载体，它是实体模型（EntityType）的运行时实例。它采用多层嵌套的数组结构存储数据，能够灵活地表达主子表、基础资料引用等复杂的业务结构。
+
+## 核心类
+- **`kd.bos.dataentity.entity.DynamicObject`**: 单条数据包对象。
+- **`kd.bos.dataentity.entity.DynamicObjectCollection`**: 数据包集合（常用于单据体分录）。
+
+## 常用 API 方法
+### 获取值 (Getter)
+- `get(String key)`: 通用取值，返回 `Object`。
+- `getString(String key)` / `getLong(String key)` / `getBigDecimal(String key)`: 类型化取值。
+- `getDynamicObject(String key)`: 获取关联的基础资料或 1:1 属性。
+- `getDynamicObjectCollection(String key)`: 获取单据体分录集合。
+
+### 设置值 (Setter)
+- `set(String key, Object value)`: 设置字段值。
+
+### 其他
+- `getDataEntityType()`: 获取该数据包对应的元数据模型。
+- `getPkValue()`: 获取该对象的主键值。
+
+## 示例代码
+### 1. 存取简单字段与分录
+```java
+// 获取主表字段
+String billNo = bill.getString("billno");
+BigDecimal totalAmt = bill.getBigDecimal("totalamount");
+
+// 遍历分录
+DynamicObjectCollection entryRows = bill.getDynamicObjectCollection("entryentity");
+for (DynamicObject row : entryRows) {
+    BigDecimal qty = row.getBigDecimal("qty");
+    // 修改分录字段
+    row.set("amt", qty.multiply(new BigDecimal("10")));
+}
+```
+
+### 2. 处理基础资料字段 (重要)
+基础资料在 `DynamicObject` 中存有两个 Key：`xxx` (对象) 和 `xxx_id` (内码)。
+```java
+// 获取客户内码
+long customerId = bill.getLong("customer_id");
+// 获取客户对象并读取其编码
+DynamicObject customer = bill.getDynamicObject("customer");
+if (customer != null) {
+    String code = customer.getString("number");
+}
+
+// 设置基础资料（必须传入 DynamicObject 对象，严禁直接给 customer 键设 ID）
+DynamicObject newCust = BusinessDataServiceHelper.loadSingleFromCache(123456L, "bd_customer");
+bill.set("customer", newCust); 
+```
+
+## 实践建议
+1. **优先使用内码**：如果只需要 ID 进行过滤或关联，优先读取 `xxx_id` 键，避免触发不必要的对象加载。
+2. **安全取值**：从 `getDynamicObject` 返回的对象可能为 `null`，访问前务必判空。
+3. **性能注意**：`DynamicObject` 是纯内存对象，大批量处理时注意及时清理引用，或改用 `DataSet`。
+
+## 常见坑位
+1. **Key 拼写错误**：字段标识必须与表单设计器中的“标识”完全一致，大小写敏感。
+2. **直接修改 Entity 集合**：对 `DynamicObjectCollection` 执行 `add` 或 `remove` 后，若在插件环境，必须确保 UI 能感知变化。
+3. **基础资料设值误区**：执行 `bill.set("customer", 123456L)` 是错误的，这会导致后续代码通过 `getDynamicObject("customer")` 报错。必须先 load 出对象再 set。

package/vendor/kingdee-skills/ok-cosmic/references/base/sdk/sdk-entity-model.md

@@ -0,0 +1,61 @@
+# 动态领域模型 - 实体模型 (Entity Model)
+
+## TL;DR
+- 适用：原生实体模型和字段属性 API，用于动态分析主表、分录和基础资料字段。
+- 先抓：`MainEntityType` / `FieldProp` / `EntryProp` 这组类型层级。
+- 跳转：团队封装优先读 `adv/entity-metadata.md`；只处理数据值不必读本页。
+- 继续读全文：当你要遍历字段元数据、判断字段类型或拿属性特征时。
+
+## 概述
+实体模型（Entity Model）是苍穹平台对现实世界业务对象的抽象定义。它类似于 Java 中的“类”定义，规定了数据包（DynamicObject）的结构、字段类型、字段标识及字段间的关系（如主子表）。
+
+## 核心类
+- **`kd.bos.entity.MainEntityType`**: 所有实体的基类。
+- **`kd.bos.entity.BillEntityType`**: 业务单据实体模型。
+- **`kd.bos.entity.BasedataEntityType`**: 基础资料实体模型。
+- **`kd.bos.entity.EntryType`**: 单据体（分录）实体模型。
+- **`kd.bos.entity.property.FieldProp`**: 简单字段属性基类（如文本、数值）。
+- **`kd.bos.entity.property.BasedataProp`**: 基础资料字段属性（复杂属性，指向另一个实体）。
+- **`kd.bos.entity.property.EntryProp`**: 分录字段属性（集合属性，包含多行子数据）。
+
+## 常用 API 方法
+### 获取属性
+- `getProperties()`: 获取实体的所有属性集合。
+- `getProperty(String name)`: 根据字段标识获取属性对象。
+- `getPrimaryKey()`: 获取主键属性。
+
+### 属性特征访问
+- `prop.getName()`: 获取字段标识（Key）。
+- `prop.getAlias()`: 获取数据库字段名（Alias）。
+- `prop.getDataType()`: 获取字段的物理数据类型。
+
+## 示例代码
+### 1. 遍历实体字段元数据
+```java
+MainEntityType entityType = MetadataServiceHelper.getDataEntityType("my_entity_id");
+// 获取所有字段并打印其显示名称
+for (IDataEntityProperty prop : entityType.getProperties()) {
+    String displayName = prop.getDisplayName().getLocaleValue();
+    String key = prop.getName();
+    System.out.println(key + " : " + displayName);
+}
+```
+
+### 2. 动态判断字段类型
+```java
+IDataEntityProperty prop = entityType.getProperty("customer");
+if (prop instanceof BasedataProp) {
+    String baseEntityId = ((BasedataProp) prop).getBaseEntityId();
+    // 该字段是一个指向 baseEntityId 的基础资料
+}
+```
+
+## 实践建议
+1. **标识驱动**：在代码中访问数据时，务必使用 `prop.getName()`（标识），严禁硬编码 `prop.getAlias()`（数据库物理名），以保证模型的解耦。
+2. **元数据缓存**：虽然平台有二级缓存，但在高频循环中建议将 `MainEntityType` 对象提取到循环外。
+3. **区分分录**：通过 `prop instanceof EntryProp` 快速识别单据体字段，并递归处理子实体的元数据。
+
+## 常见坑位
+1. **同名冲突**：在主表和分录中可能存在标识相同的字段，获取属性时注意 `entityType` 所在的层级。
+2. **多语言取值**：`prop.getDisplayName()` 返回的是多语言对象，必须调用 `getLocaleValue()` 才能获取当前语种的字符串。
+3. **主键识别**：部分虚实体可能没有物理主键，调用 `getPrimaryKey()` 可能返回 null。

package/vendor/kingdee-skills/ok-cosmic/references/base/sdk/sdk-exception.md

@@ -0,0 +1,64 @@
+# 异常处理 (Exception Handling)
+
+## TL;DR
+- 适用：平台异常体系、错误码定义、多语言异常抛出与封装。
+- 先抓：业务异常统一走 `KDException` / `ErrorCode`，先区分业务错误和系统错误。
+- 跳转：日志记录不是本页；事务回滚边界要配合操作/事务文档一起看。
+- 继续读全文：当你要定义错误码类、封装底层异常或规范前端提示时。
+
+## 概述
+苍穹平台提供了统一的异常处理规范，要求所有的业务和系统异常均通过 `KDException` 或其子类进行表达。核心原则是：统一异常类型、错误码全局唯一、多语言支持以及精准的异常捕获。
+
+## 核心类
+- **`kd.bos.exception.KDException`**: 平台所有异常的基类。
+- **`kd.bos.exception.KDBizException`**: 业务逻辑异常（通常直接继承自 `KDException`，用于在前端显示友好提示）。
+- **`kd.bos.exception.ErrorCode`**: 错误码定义类，包含唯一的错误代码和多语言消息模板。
+
+## 常用 API 方法
+- `new ErrorCode(String code, String message)`: 构造错误码。格式建议：`云.应用.变量名`。
+- `new KDException(ErrorCode code, Object... args)`: 抛出带错误码和格式化参数的异常。
+- `new KDException(Throwable cause, ErrorCode code, Object... args)`: 封装原始异常并抛出。
+- `exception.getErrorCode()`: 获取异常中的错误码对象。
+
+## 示例代码
+### 1. 定义错误码类
+```java
+public class MyModuleErrorCode {
+    private static ErrorCode create(String code, String message) {
+        return new ErrorCode("my.module." + code, message);
+    }
+    // 使用 %s 作为动态参数占位符
+    public final static ErrorCode orderNotFound = create("orderNotFound", "订单【%s】不存在或已删除。");
+    public final static ErrorCode dataProcessError = create("dataProcessError", "数据处理失败：%s");
+}
+```
+
+### 2. 抛出与捕获异常
+```java
+public void processOrder(String billNo) {
+    if (StringUtils.isBlank(billNo)) {
+        // 直接抛出业务异常
+        throw new KDBizException(MyModuleErrorCode.orderNotFound, billNo);
+    }
+
+    try {
+        doComplexTask();
+    } catch (KDException e) {
+        // 关注的业务异常，再次往上抛（无需记录日志，平台会自动处理显示）
+        throw e;
+    } catch (Exception e) {
+        // 系统级异常（如网络、IO），封装为业务异常再抛出，并可在此记录日志
+        throw new KDException(e, MyModuleErrorCode.dataProcessError, e.getMessage());
+    }
+}
+```
+
+## 实践建议
+1. **业务异常优先**：业务逻辑校验失败时，应优先抛出 `KDBizException`，这样前端会自动拦截并以友好弹窗形式展示 `message`。
+2. **错误码规范**：错误码应保持产品全局唯一，且对应的消息应在多语言资源文件中配置。
+3. **按需捕获**：只 catch 那些你真正需要处理（如回滚、补偿、转换）的异常，其他异常任其向上抛出到框架层统一处理。
+
+## 常见坑位
+1. **吞掉异常不记录日志**：如果 catch 了异常且没有再次抛出，必须使用 `LogFactory` 记录详细堆栈，否则问题将极难定位。
+2. **UI 显示非业务语言**：严禁直接将 `SQLException` 等底层堆栈信息抛给前端展示，必须封装为用户可理解的业务语义。
+3. **乱用 Exception 基类**：尽量避免直接 `throw new Exception()`，这会导致框架无法精准区分系统错误和业务校验。

package/vendor/kingdee-skills/ok-cosmic/references/base/sdk/sdk-file.md

@@ -0,0 +1,63 @@
+# 文件服务 (File Service)
+
+## TL;DR
+- 适用：物理文件上传、下载、删除以及图片/附件文件服务。
+- 先抓：先选对 `FileServiceFactory` 提供的具体文件服务，再做流操作。
+- 跳转：如果文件还要挂到业务附件面板，优先读 `adv/attachment-api.md`。
+- 继续读全文：当你要确认文件对象、上传下载代码或清理策略时。
+
+## 概述
+文件服务用于在苍穹平台中存储、下载和管理物理文件（如单据附件、单据图片）。它支持高可用部署，并提供统一的 SDK 接口，屏蔽了底层存储介质（文件服务器、S3、OSS 等）的差异。
+
+## 核心类
+- **`kd.bos.fileservice.FileServiceFactory`**: 获取文件服务的工厂类。
+- **`kd.bos.fileservice.FileService`**: 执行文件操作的核心接口。
+- **`kd.bos.fileservice.FileItem`**: 代表一个待上传的文件对象（包含文件名、输入流等）。
+
+## 常用 API 方法
+### 获取服务
+- `FileServiceFactory.getAttachmentFileService()`: 获取通用的附件存储服务。
+- `FileServiceFactory.getImageFileService()`: 获取专用的图片存储服务。
+
+### 文件操作
+- `upload(FileItem item)`: 上传文件，返回文件在服务器上的唯一 URL（路径）。
+- `download(String url)`: 下载文件，返回文件字节数组。
+- `getInputStream(String url)`: 获取文件的输入流（适用于大文件）。
+- `delete(String url)`: 物理删除服务器上的文件。
+- `preview(String url)`: 获取文件预览地址。
+
+## 示例代码
+```java
+import kd.bos.fileservice.FileService;
+import kd.bos.fileservice.FileServiceFactory;
+import kd.bos.fileservice.FileItem;
+import java.io.InputStream;
+
+public class FileDemo {
+    public String uploadFile(String fileName, InputStream is) {
+        // 1. 获取附件服务
+        FileService fs = FileServiceFactory.getAttachmentFileService();
+        
+        // 2. 构造上传对象
+        FileItem item = new FileItem(fileName, is);
+        
+        // 3. 执行上传并返回 URL
+        return fs.upload(item);
+    }
+
+    public void deleteFile(String fileUrl) {
+        FileService fs = FileServiceFactory.getAttachmentFileService();
+        fs.delete(fileUrl);
+    }
+}
+```
+
+## 实践建议
+1. **区分场景**：普通的业务附件使用 `getAttachmentFileService`；如果是单据上的头像、商品图片，建议使用 `getImageFileService`，以便平台执行特定的缩略图优化。
+2. **资源释放**：通过 `getInputStream` 获取流后，务必在 `finally` 块或 `try-with-resources` 中手动关闭。
+3. **URL 存储**：上传成功返回的 `url` 是访问该文件的唯一凭证，应将其保存到单据对应的附件表或字段中。
+
+## 常见坑位
+1. **文件后缀**：上传时 `FileItem` 的文件名后缀应准确，否则可能导致预览（`preview`）功能失效。
+2. **URL 格式**：存储和传递 URL 时，不要随意拼凑，应保持 `fs.upload` 返回的原始字符串。
+3. **权限控制**：物理删除（`delete`）操作不可逆，执行前务必在业务层做好权限校验。

package/vendor/kingdee-skills/ok-cosmic/references/base/sdk/sdk-id.md

@@ -0,0 +1,47 @@
+# 分布式 ID (Distributed ID)
+
+## TL;DR
+- 适用：生成全局唯一主键或业务唯一 ID。
+- 先抓：`ID.genLongId()` 是最常用入口，类型要与数据库字段匹配。
+- 跳转：如果你要的是业务编码而不是主键，去 `CodeRuleServiceHelper` 文档。
+- 继续读全文：当你要批量生成 ID、选择 `String`/`long` 类型或看示例时。
+
+## 概述
+分布式 ID 服务用于在多微服务节点环境下产生全局唯一的 ID 值。它主要用作实体的主键，或其他需要唯一标识的业务场景。该服务具备高性能、趋势有序和高可用的特性。
+
+## 核心类
+- **`kd.bos.id.ID`**: ID 生成的核心工具类。
+
+## 常用 API 方法
+- `ID.genLongId()`: 获取单个 `long` 类型 ID（对应 DB 字段 `bigint(19)`）。
+- `ID.genLongIds(int count)`: 一次性获取指定数量的 `long` 类型 ID 数组。
+- `ID.genStringId()`: 获取单个 `String` 类型 ID（对应 DB 字段 `varchar(12)`）。
+- `ID.genStringIds(int count)`: 一次性获取指定数量的 `String` 类型 ID 数组。
+
+## 示例代码
+```java
+import kd.bos.id.ID;
+
+public class IdDemo {
+    public void generateId() {
+        // 生成主键 ID
+        long billId = ID.genLongId();
+        
+        // 批量生成主键
+        long[] batchIds = ID.genLongIds(10);
+        
+        // 生成字符串类型的唯一标识
+        String traceId = ID.genStringId();
+    }
+}
+```
+
+## 实践建议
+1. **主键必选**：凡是苍穹平台的业务实体主键，务必使用 `ID.genLongId()` 生成，不要使用外部随机数或自增 ID。
+2. **批量获取**：在需要大批量创建单据或分录的循环中，建议先调用 `genLongIds` 一次性拿到 ID 数组，以减少内部锁竞争。
+3. **类型匹配**：`long` 类型 ID 是对 `String` 类型进行 Base39 编码后的结果，两者可以互转且保持趋势有序。
+
+## 常见坑位
+1. **历史数据转换**：旧系统初始化数据或第三方系统导入的 ID 可能不是通过此服务生成的，强行互转可能导致数据错误。
+2. **种子耗尽风险**：如果微服务节点频繁异常重启且系统时间跳动过大，可能导致 WorkerId 种子用完（上限 8192），此时需要清理 Zookeeper 上的种子节点。
+3. **依赖 DLock**：ID 服务启动时依赖分布式锁（DLock）获取种子，若 Redis/Zookeeper 异常导致锁不可用，ID 服务将无法启动。

package/vendor/kingdee-skills/ok-cosmic/references/base/sdk/sdk-lock.md

@@ -0,0 +1,61 @@
+# 分布式锁 (Distributed Lock)
+
+## TL;DR
+- 适用：跨实例并发互斥，需要排他处理共享资源时。
+- 先抓：默认优先可重入锁，并保证在 `finally` 里释放。
+- 跳转：单据编辑互斥更常见的是网控，去 `sdk-network-control.md`。
+- 继续读全文：当你要确认 `tryLock` 策略、示例或防死锁约束时。
+
+## 概述
+分布式锁用于在分布式环境下对共享资源执行排他性操作。它能确保在多个微服务实例并发执行时，同一时刻只有一个线程能持有特定标识的锁。苍穹平台提供不可重入和可重入两种锁类型。
+
+## 核心类
+- **`kd.bos.dlock.DLock`**: 分布式锁的核心管理类。
+
+## 常用 API 方法
+- `DLock.create(String lockId, String desc)`: 创建一个不可重入锁。
+- `DLock.createReentrant(String lockId, String desc)`: 创建一个可重入锁（推荐，防止同一线程死锁）。
+- `lock()`: 阻塞式加锁，直到成功为止。
+- `tryLock()`: 尝试加锁，不等待，立即返回成功或失败。
+- `tryLock(long timeout, TimeUnit unit)`: 在指定时间内尝试加锁。
+- `unlock()`: 释放锁。**必须在 finally 块中调用**。
+
+## 示例代码
+```java
+import kd.bos.dlock.DLock;
+import java.util.concurrent.TimeUnit;
+
+public class LockDemo {
+    public void executeWithLock() {
+        // 1. 创建锁标识（建议包含模块和业务主键）
+        DLock lock = DLock.createReentrant("my_module/order/12345", "订单12345并发锁");
+        
+        // 2. 加锁
+        try {
+            if (lock.tryLock(5, TimeUnit.SECONDS)) {
+                try {
+                    // 执行排他性业务逻辑
+                    processBusiness();
+                } finally {
+                    // 3. 释放锁
+                    lock.unlock();
+                }
+            } else {
+                throw new KDBizException("获取锁超时，请稍后重试");
+            }
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+        }
+    }
+}
+```
+
+## 实践建议
+1. **优先使用可重入锁**：通过 `createReentrant` 创建的锁可以防止同一线程在嵌套调用中产生的死锁问题。
+2. **Key 命名规范**：锁标识应具备唯一性且易于识别，建议采用 `模块/业务类型/主键ID` 的格式。
+3. **超时控制**：尽量使用 `tryLock` 并设置合理的超时时间，避免因长时间阻塞导致微服务线程池枯竭。
+
+## 常见坑位
+1. **忘记释放锁**：如果不在 `finally` 中执行 `unlock()`，一旦业务代码抛出异常，锁将无法及时释放，直到节点心跳超时。
+2. **死锁风险**：不可重入锁在同一个线程内重复调用 `lock()` 会导致永久阻塞。
+3. **宕机延迟释放**：若持有锁的节点崩溃，锁会自动保留直到服务注册中心将其移除（约 5 分钟），期间其他节点可能无法获取该锁。

package/vendor/kingdee-skills/ok-cosmic/references/base/sdk/sdk-log.md

@@ -0,0 +1,63 @@
+# 日志框架 (Logging Framework)
+
+## TL;DR
+- 适用：统一日志记录、级别判断和异常堆栈输出。
+- 先抓：优先 `LogFactory.getLog(Class)`，避免 `System.out.println`。
+- 跳转：如果继承了 Ext 插件基类，先直接用内置 `log` 对象，不必回到本页。
+- 继续读全文：当你要确认参数化日志、异常记录和生产级日志建议时。
+
+## 概述
+苍穹平台提供了一套统一的日志处理接口，底层默认基于 Logback 实现。它支持标准的日志级别（DEBUG, INFO, WARN, ERROR），并具备异步写入、链路追踪及集群环境下的统一日志收集能力。
+
+## 核心类
+- **`kd.bos.logging.LogFactory`**: 获取日志对象的工厂类。
+- **`kd.bos.logging.Log`**: 日志执行接口。
+
+## 常用 API 方法
+### 获取日志实例
+- `LogFactory.getLog(Class<?> clazz)`: 推荐方式，根据类名获取日志对象。
+- `LogFactory.getLog(String name)`: 根据标识名获取。
+
+### 级别判断
+- `isDebugEnabled()` / `isInfoEnabled()` / `isWarnEnabled()` / `isErrorEnabled()`
+
+### 记录日志
+- `debug(String message, Object... args)`
+- `info(String message, Object... args)`
+- `warn(String message, Object... args)`
+- `error(String message, Throwable t)`: 记录错误及异常堆栈。
+
+## 示例代码
+```java
+import kd.bos.logging.Log;
+import kd.bos.logging.LogFactory;
+
+public class LogDemo {
+    // 1. 定义静态常量日志对象
+    private static final Log logger = LogFactory.getLog(LogDemo.class);
+
+    public void doWork(String billNo) {
+        // 2. 先判断级别，再输出（减少字符串拼接开销）
+        if (logger.isInfoEnabled()) {
+            logger.info("开始处理单据: {}", billNo);
+        }
+
+        try {
+            process();
+        } catch (Exception e) {
+            // 3. 记录异常堆栈
+            logger.error("单据处理失败: " + billNo, e);
+        }
+    }
+}
+```
+
+## 实践建议
+1. **先判断后输出**：输出 DEBUG 或较长的 INFO 日志时，务必包裹在 `isXXXEnabled()` 判断中，以避免在高并发下产生大量的字符串计算开销。
+2. **占位符写法**：推荐使用 `{}` 占位符，而不是手写字符串拼接。
+3. **异常完整记录**：在 `error` 级别中，务必将异常对象 `e` 作为最后一个参数传入，以便记录完整的堆栈信息。
+
+## 常见坑位
+1. **`System.out` 滥用**：严禁在生产代码中使用 `System.out.println`，这些输出无法被集中收集和管理。
+2. **循环内输出**：避免在处理几万行的循环内输出大量的日志，这会导致严重的 IO 瓶颈。
+3. **敏感信息泄露**：记录日志时注意脱敏，避免将用户的密码、个人手机号等敏感信息直接打入日志。