kcode-pi 0.1.0

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

@@ -0,0 +1,70 @@
+# 网络控制 (Data Mutex / NetCtrl)
+
+## TL;DR
+- 适用：单据/数据的网控互斥，避免多人同时编辑或冲突操作。
+- 先抓：`DataMutex` + `MutexLockInfo`，先区分功能互斥和数据互斥。
+- 跳转：跨服务通用资源锁不是网控，去 `sdk-lock.md`。
+- 继续读全文：当你要批量申请网控、读取锁信息或处理释放时。
+
+## 概述
+网络控制（也称网控或互斥锁）用于解决多用户并发操作同一单据时产生的数据冲突问题。它主要分为**功能互斥**（如审核时禁止编辑）和**数据互斥**（如同一单据禁止两人同时修改）。
+
+## 核心类
+- **`kd.bos.mutex.DataMutex`**: 网控核心接口类（支持 AutoCloseable）。
+- **`kd.bos.form.operate.MutexHelper`**: 网控操作帮助类。
+- **`kd.bos.mutex.MutexLockInfo`**: 定义锁的具体信息（实体、主键、操作标识等）。
+
+## 常用 API 方法
+### 1. 申请网控
+- `DataMutex.create().require(MutexLockInfo info)`: 申请单条数据的网控锁。
+- `batchrequire(List<Map<String, Object>> data)`: 批量申请网控。
+
+### 2. 释放网控
+- `release(String objId, String entityKey, String operationKey)`: 释放单条网控。
+- `batchRelease(List<Map<String, Object>> data)`: 批量释放。
+
+### 3. 获取锁信息
+- `getLockInfo(String objId, String groupId, String entityKey)`: 查询当前数据被谁锁定。
+
+## 示例代码
+```java
+import kd.bos.mutex.DataMutex;
+import kd.bos.mutex.MutexLockInfo;
+
+public void doTaskWithMutex(String billId) {
+    // 1. 创建网控对象（使用 try-with-resources 自动管理）
+    try (DataMutex mutex = DataMutex.create()) {
+        // 2. 定义锁信息
+        MutexLockInfo lockInfo = new MutexLockInfo();
+        lockInfo.setDataObjId(billId);
+        lockInfo.setEntityKey("my_entity_id");
+        lockInfo.setOperationKey("submit");
+        lockInfo.setGroupId("default_netctrl"); // 默认互斥组
+        
+        // 3. 申请锁
+        if (mutex.require(lockInfo)) {
+            try {
+                // 执行核心业务逻辑
+                process();
+            } finally {
+                // 4. 显式释放（重要）
+                mutex.release(billId, "my_entity_id", "submit");
+            }
+        } else {
+            throw new KDBizException("单据已被其他用户锁定，请稍后重试");
+        }
+    } catch (Exception e) {
+        logger.error("网控异常", e);
+    }
+}
+```
+
+## 实践建议
+1. **自动释放**：始终使用 `try-with-resources` 语法创建 `DataMutex` 实例，以确保底层连接被正确关闭。
+2. **细粒度控制**：合理利用 `groupId`。如果希望你的逻辑不与系统标准操作冲突，可以自定义 `groupId`。
+3. **友好提示**：申请锁失败时，建议调用 `getLockInfo` 并将占用者的信息提示给用户。
+
+## 常见坑位
+1. **死锁风险**：严禁在持有锁的过程中执行超长时间的同步等待（如调用外系统 API），这会导致单据被长时间锁定无法操作。
+2. **忘记释放**：手动调用的 `require` **必须**有对应的 `release` 调用，否则该单据可能一直处于“锁定中”状态，直到用户 Session 超时。
+3. **同用户重入**：默认情况下，同用户多次申请同一把锁是允许的（可重入），但需注意逻辑闭环。

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

@@ -0,0 +1,78 @@
+# ORM 与查询 (QFilter / KSQL)
+
+## TL;DR
+- 适用：原生 ORM、`QFilter`、KSQL、`DBRoute` 查询写法和底层 DB 路由。
+- 先抓：优先 ORM + `QFilter`，只有表达不了再下沉到 KSQL 或 SQL。
+- 跳转：团队封装查询优先读 `adv/query-dataset.md`；精确签名必须走脚本验证。
+- 继续读全文：当你要写复杂过滤、KSQL 更新或跨库路由逻辑时。
+
+金蝶云苍穹提供了强大的 ORM 引擎和基于 KSQL 的查询能力。
+
+**注意：** 仅展示核心查询模式与最佳实践。如需查询 `ORM`、`QFilter` 或 `DBServiceHelper` 的完整方法列表、准确参数签名，**请务必使用 `cosmic_get_class_detail(classname="<类名>")` 工具查询。**
+
+## 1. ORM 查询基础 (ORM / QFilter)
+
+### 核心查询模式
+```java
+import kd.bos.orm.ORM;
+import kd.bos.orm.query.QFilter;
+import kd.bos.orm.query.QCP;
+
+ORM orm = ORM.create();
+
+// 1. 查询单条记录 (返回 DynamicObject)
+DynamicObject obj = orm.queryOne("entity_name", new QFilter[]{filter});
+
+// 2. 查询集合 (返回 DynamicObjectCollection)
+DynamicObjectCollection coll = orm.query("entity_name", fields, new QFilter[]{filter});
+
+// 3. 流式查询 (推荐，返回 DataSet)
+DataSet ds = orm.queryDataSet("algo_key", "entity_name", fields, new QFilter[]{filter}, "id desc");
+```
+
+### QFilter 常用操作符 (QCP)
+- **基本比较**: `equals`, `not_equals`, `large_than`, `less_than`, `large_equals`, `less_equals`
+- **集合/范围**: `in`, `not_in`, `between`
+- **模糊匹配**: `like` (自动补 `%`), `not_like`
+
+### 复杂条件组合
+```java
+QFilter f1 = new QFilter("status", QCP.equals, "C");
+QFilter f2 = new QFilter("amt", QCP.large_than, 100);
+
+// AND 组合
+QFilter combined = f1.and(f2);
+// OR 组合
+QFilter combinedOr = f1.or(new QFilter("type", QCP.equals, "A"));
+
+// 链式调用
+QFilter finalFilter = QFilter.of("status = 'C'").and("amt > 1000");
+```
+
+## 2. KSQL 与原生 SQL (DBServiceHelper)
+
+用于执行复杂的、非 ORM 能够表达的 SQL 逻辑。
+
+### 核心方法
+- **KSQL 查询**: `DBServiceHelper.executeQuery(algoKey, ksql, params)` -> 返回 `DataSet`
+- **KSQL 更新**: `DBServiceHelper.executeUpdate(ksql, params)` (慎用，优先用 `SaveServiceHelper`)
+
+### 底层 DB 路由 (DB / DBRoute)
+用于跨库访问或需要使用数据库方言 (`/*dialect*/`) 的场景。
+```java
+import kd.bos.db.DB;
+import kd.bos.db.DBRoute;
+
+DB.execute(DBRoute.of("route_key"), "/*dialect*/update t_table set fstatus='C' where fid=?", params);
+```
+
+## 3. 开发建议 (Best Practices)
+
+1. **优先使用 QFilter**：避免手写 SQL 字符串拼接，防止 SQL 注入并确保跨数据库兼容性。
+2. **字段按需加载**：严禁在 `query` 中使用 `*` 或加载不必要的字段，以节省内存。
+3. **关联查询技巧**：
+   - 访问基础资料属性：`new QFilter("customer.number", QCP.like, "C%")`
+   - 访问单据体字段：`new QFilter("entryentity.material", QCP.equals, mid)`
+4. **性能预警**：避免在 `QFilter` 中使用大量的 `OR` 条件或复杂的子查询，这可能导致索引失效。
+5. **资源关闭**：通过 `orm.queryDataSet` 或 `DBServiceHelper.executeQuery` 获取的 `DataSet` **必须**及时关闭。
+

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

@@ -0,0 +1,62 @@
+# 请求上下文 (Request Context)
+
+## TL;DR
+- 适用：查看当前线程里的用户、租户、组织和语言等上下文字段。
+- 先抓：`RequestContext.get()` 只解决“读取上下文”，不解决跨线程传播。
+- 跳转：异步/后台线程恢复上下文优先读 `adv/request-context.md` 或线程池文档。
+- 继续读全文：当你要手动传递上下文、读组织/语种信息或排查线程问题时。
+
+## 概述
+`RequestContext` 保存了当前请求线程关联的租户、账套、用户信息及登录环境。它是苍穹平台识别“我是谁”、“我在哪”的核心依据，贯穿了从前端请求到后台服务调用的全生命周期。
+
+## 核心类
+- **`kd.bos.context.RequestContext`**: 请求上下文的核心工具类。
+
+## 常用 API 方法
+- `RequestContext.get()`: 获取当前线程绑定的上下文对象。
+- `getCurrUserId()` / `getUid()`: 获取当前登录用户的 ID。
+- `getUserName()`: 获取用户姓名。
+- `getTenantId()` / `getAccountId()`: 获取租户 ID 和账套 ID。
+- `getOrgId()`: 获取当前用户登录时选中的组织 ID。
+- `getLocale()` / `getLang()`: 获取当前语种（如 `zh_CN`）。
+
+## 示例代码
+### 1. 基础信息获取
+```java
+import kd.bos.context.RequestContext;
+
+public void bizMethod() {
+    RequestContext ctx = RequestContext.get();
+    long userId = ctx.getCurrUserId();
+    long orgId = ctx.getOrgId();
+    String accountId = ctx.getAccountId();
+    // 执行基于当前身份的逻辑...
+}
+```
+
+### 2. 跨线程手动传递 (不推荐，优先用线程池)
+```java
+// 复制当前上下文
+RequestContext copiedCtx = RequestContext.copy(RequestContext.get());
+
+new Thread(() -> {
+    try {
+        // 在新线程中绑定上下文
+        RequestContext.set(copiedCtx);
+        // 执行逻辑...
+    } finally {
+        // 务必清理，防止干扰后续任务
+        RequestContext.remove();
+    }
+}).start();
+```
+
+## 实践建议
+1. **优先使用平台线程池**：手动使用 `RequestContext.copy` 极易出错，推荐使用 `ThreadPools.executeOnceIncludeRequestContext`，平台会自动处理上下文克隆。
+2. **严禁共用实例**：跨线程传递时**必须调用 `copy()`**，严禁直接 `set(originalCtx)`，否则会导致调用链监控数据混乱。
+3. **及时清理**：如果手动调用了 `RequestContext.set()`，务必在 `finally` 块中执行 `remove()`。
+
+## 常见坑位
+1. **异步线程失效**：在普通异步线程或 MQ 消费者中，直接调用 `RequestContext.get()` 返回的是空对象或默认对象，导致 `userId` 为 0 或数据库操作无权限。
+2. **内存泄露**：频繁在非平台托管线程中 `set` 而不 `remove`，会导致 `ThreadLocal` 变量不断堆积。
+3. **调用链污染**：若直接复用原线程的 `RequestContext` 实例，多个并发线程会共享同一个 `traceId`，导致日志追踪无法区分。

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

@@ -0,0 +1,63 @@
+# 线程池 (Unified Thread Pool)
+
+## TL;DR
+- 适用：平台统一线程池和携带 `RequestContext` 的异步任务执行。
+- 先抓：优先用平台线程池 API，不要直接 new JDK 线程池。
+- 跳转：只是恢复上下文本身看 `adv/request-context.md`；定时作业则看 `plugin-task.md`。
+- 继续读全文：当你要创建线程池、提交任务或处理返回值/上下文传递时。
+
+## 概述
+苍穹平台提供了统一的线程池管理机制，用于替代原生的 JDK 线程池。使用平台线程池可以确保线程生命周期的安全管理、自动清理线程变量，并支持将 `RequestContext` (请求上下文) 自动传递到异步线程中。
+
+## 核心类
+- **`kd.bos.threads.ThreadPools`**: 获取和创建线程池的工厂类。
+- **`kd.bos.threads.ThreadPool`**: 平台封装的线程池接口。
+
+## 常用 API 方法
+### 快速执行
+- `executeOnceIncludeRequestContext(String name, Runnable runnable)`: 携带当前上下文执行一次异步任务。
+
+### 创建线程池
+- `newCachedThreadPool(String name, int coreSize, int maxSize)`: 创建可缓存线程池。
+- `newFixedThreadPool(String name, int size)`: 创建固定大小线程池。
+
+### 提交任务
+- `execute(Runnable task)`: 提交任务。
+- `executeIncludeRequestContext(Runnable task)`: 提交任务并携带上下文。
+- `submit(Callable<T> task)`: 提交带返回值的任务。
+
+## 示例代码
+```java
+import kd.bos.threads.ThreadPool;
+import kd.bos.threads.ThreadPools;
+
+public class ThreadDemo {
+    // 1. 建议将线程池定义为静态常量（全局共享）
+    private static final ThreadPool pool = ThreadPools.newFixedThreadPool("MyBizPool", 5);
+
+    public void runAsyncTask() {
+        // 2. 提交携带上下文的异步任务
+        pool.executeIncludeRequestContext(() -> {
+            // 在此异步线程中可以正常调用 RequestContext.get()
+            doComplexBusiness();
+        });
+    }
+    
+    public void runOnce() {
+        // 3. 简单场景：单次快速异步
+        ThreadPools.executeOnceIncludeRequestContext("SingleTask", () -> {
+            log.info("异步执行中...");
+        });
+    }
+}
+```
+
+## 实践建议
+1. **优先携带上下文**：在业务逻辑中，务必使用 `xxxIncludeRequestContext` 系列方法，否则异步线程中无法获取用户信息、账套信息及进行数据库操作。
+2. **全局化维护**：线程池应作为类的静态成员变量，严禁在方法内部频繁创建和关闭线程池。
+3. **命名规范**：创建线程池时必须指定有业务语义的 `name`，以便在 `monitor` 监控中定位问题。
+
+## 常见坑位
+1. **直接 new Thread**：严禁在代码中直接使用 `new Thread().start()`，这会导致上下文丢失且线程不可控。
+2. **拒绝策略**：平台线程池对阻塞队列做了优化，默认不会丢失任务，但在高负载下可能会阻塞提交线程，需注意响应时间。
+3. **内存泄露**：虽然平台会自动清理线程变量，但如果在异步线程中使用 `ThreadLocal` 存储了大对象且未手动移除，仍存在泄露风险。

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

@@ -0,0 +1,64 @@
+# 分布式事务 (Distributed Transaction / KDTX)
+
+## TL;DR
+- 适用：分布式事务、最终一致性、TCC 和本地事务控制。
+- 先抓：默认优先最终一致性模式，本地 `TX` 只解决单库事务。
+- 跳转：普通单据操作别过度上升到 KDTX，先判断是否真的跨服务或跨库。
+- 继续读全文：当你要注册一致性任务、写 TCC 或控制本地事务边界时。
+
+## 概述
+KDTX (Kingdee Distributed Transaction) 是苍穹平台提供的分布式事务解决方案，主要用于解决跨微服务、跨数据库操作时的数据一致性问题。它支持“最终一致性”和“TCC”两种核心模式。
+
+## 核心类
+- **`kd.bos.kdtx.sdk.api.EventualConsistencyService`**: 最终一致性服务基类。
+- **`kd.bos.kdtx.sdk.api.TCCService`**: TCC 模式服务基类。
+- **`kd.bos.db.tx.TX`**: 本地数据库事务控制工具。
+
+## 常用 API 方法
+### 1. 最终一致性模式 (推荐)
+- `EventualConsistencyService.register(Class<? extends EventualConsistencyService> clazz)`: 注册异步执行任务。
+- `addProperty(String key, Object value)`: 传递业务参数。
+
+### 2. 本地事务控制
+- `TX.required()`: 如果当前没有事务，则开启一个新事务；如果有，则加入。
+- `txHandle.commit()`: 提交事务。
+
+## 示例代码
+### 实现最终一致性服务
+```java
+import kd.bos.kdtx.sdk.api.EventualConsistencyService;
+
+// 1. 定义任务逻辑
+public class MySyncTask extends EventualConsistencyService {
+    @Override
+    public void invoke() throws Exception {
+        String billNo = (String) this.getProperty("billno");
+        // 执行具体的跨系统同步逻辑...
+    }
+}
+
+// 2. 在主业务逻辑中注册
+public void auditBill(DynamicObject bill) {
+    try (TXHandle tx = TX.required()) {
+        // 修改本地状态
+        bill.set("status", "C");
+        SaveServiceHelper.update(bill);
+        
+        // 注册异步同步任务（本地事务提交后才会真正触发执行）
+        EventualConsistencyService.register(MySyncTask.class)
+            .addProperty("billno", bill.getString("billno"));
+            
+        tx.commit();
+    }
+}
+```
+
+## 实践建议
+1. **优先最终一致性**：绝大多数业务场景（如发邮件、同步第三方接口）建议使用最终一致性模式，以保证主流程的响应速度和高可用。
+2. **幂等性要求**：分布式事务任务可能会因网络波动而重试，`invoke()` 方法内部逻辑**必须**实现幂等。
+3. **事务范围最小化**：不要在事务块（`TX.required`）中放置耗时的网络 IO 操作。
+
+## 常见坑位
+1. **参数序列化**：通过 `addProperty` 传递的对象必须支持序列化（基础类型或 DynamicObject）。
+2. **事务嵌套风险**：注意 `TX.required` 与外部事务的交互，避免产生意料之外的回滚。
+3. **异常处理**：`invoke()` 方法抛出异常会导致 KDTX 框架自动重试，请确保异常捕获的准确性。

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

@@ -0,0 +1,67 @@
+# 基础工具类 (DataEntity Utils)
+
+## TL;DR
+- 适用：`StringUtils`、`DateUtils`、`CollectionUtils`、`SerializationUtils` 等基础工具。
+- 先抓：优先平台自带空安全工具，少混入第三方同名工具导致风格不一。
+- 跳转：业务对象处理不是本页；`DynamicObject`、查询、元数据分别看专题文档。
+- 继续读全文：当你要查字符串、日期、集合、JSON 的常用方法和示例时。
+
+## 概述
+苍穹平台在 `kd.bos.dataentity.utils` 包下提供了一系列高性能、Null 安全的工具类，用于处理字符串、日期、集合及 JSON 序列化。在业务开发中，应优先使用这些工具类而非原生 JDK 或第三方库。
+
+## 核心类
+- **`kd.bos.dataentity.utils.StringUtils`**: 字符串处理工具。
+- **`kd.bos.dataentity.utils.DateUtils`**: 日期计算与格式化工具。
+- **`kd.bos.dataentity.utils.CollectionUtils`**: 集合操作工具。
+- **`kd.bos.dataentity.serialization.SerializationUtils`**: JSON 序列化工具。
+
+## 常用 API 方法
+### 1. 字符串 (StringUtils)
+- `isBlank(String str)` / `isNotBlank(String str)`: Null 安全的空白检查。
+- `equals(String str1, String str2)`: 避免 NPE 的相等比较。
+- `join(Iterable<?> iterable, String separator)`: 字符串拼接。
+
+### 2. 日期 (DateUtils)
+- `format(Date date, String pattern)`: 日期格式化。
+- `parseDate(String str, String pattern)`: 日期解析。
+- `addDays(Date date, int amount)`: 日期加减计算。
+
+### 3. 集合 (CollectionUtils)
+- `isEmpty(Collection<?> coll)`: Null 安全的判空。
+- `partition(List<T> list, int size)`: 将大列表拆分为固定大小的子列表（分批处理利器）。
+
+### 4. JSON 序列化 (SerializationUtils)
+- `toJsonString(Object obj)`: 对象转 JSON。
+- `fromJsonString(String json, Class<T> clazz)`: JSON 转对象。
+
+## 示例代码
+```java
+import kd.bos.dataentity.utils.StringUtils;
+import kd.bos.dataentity.utils.CollectionUtils;
+import java.util.List;
+
+public class UtilsDemo {
+    public void processData(String input, List<Long> ids) {
+        // 1. 字符串检查
+        if (StringUtils.isBlank(input)) { return; }
+        
+        // 2. 集合分批处理（每 100 条一批）
+        if (CollectionUtils.isNotEmpty(ids)) {
+            List<List<Long>> batches = CollectionUtils.partition(ids, 100);
+            for (List<Long> batch : batches) {
+                doBatchUpdate(batch);
+            }
+        }
+    }
+}
+```
+
+## 实践建议
+1. **Null 安全第一**：凡是涉及外部输入（如界面字段、API 入参）的变量，建议一律通过 `StringUtils.isNotBlank` 或 `CollectionUtils.isEmpty` 进行预检。
+2. **格式统一**：日期格式化建议统一使用 `DateUtils.format`，以保证在不同时区环境下的表现一致。
+3. **避免重复造轮子**：在手写复杂的字符串截取或集合合并逻辑前，先查阅上述工具类的 API。
+
+## 常见坑位
+1. **混用包名**：注意 `StringUtils` 存在于多个包中（如 Apache Commons, Spring），苍穹开发务必认准 `kd.bos.dataentity.utils`。
+2. **JSON 性能**：`SerializationUtils` 内部基于 FastJson，对于极高性能要求的场景，注意大对象的序列化开销。
+3. **DateUtils 偏移**：日期加减时，注意 `amount` 参数的正负值含义。

package/vendor/kingdee-skills/ok-cosmic/requirements.txt

@@ -0,0 +1,2 @@
+tree-sitter>=0.23.0
+tree-sitter-java>=0.23.0

package/vendor/kingdee-skills/ok-cosmic/rules/a-layer-rules.json

@@ -0,0 +1,24 @@
+{
+  "_comment": "A 层硬约束规则 ID 列表（单一可信源）。cosmic-post-lint.py 和 post-check.md 共同引用此文件。",
+  "a_layer_rule_ids": [
+    "SCENE-001",
+    "SCENE-002",
+    "SCENE-006",
+    "SCENE-007",
+    "SCENE-008",
+    "SCENE-009",
+    "SCENE-010",
+    "SCENE-012",
+    "STYLE-009",
+    "STYLE-011",
+    "STYLE-012",
+    "STYLE-014",
+    "STYLE-015",
+    "STYLE-016",
+    "STYLE-018",
+    "STYLE-022",
+    "STYLE-023",
+    "STYLE-024",
+    "RESOURCE-004"
+  ]
+}

package/vendor/kingdee-skills/ok-cosmic/rules/anti-patterns.md

@@ -0,0 +1,48 @@
+# 禁忌清单 (Anti-Patterns)
+
+> 本文件为禁忌清单；其中 `scene_check.py`（SCENE-\*）对应的场景错配条目会被自动检测。
+> 幻觉方法名/类名黑名单用于事前人工/AI 自检，`hal_check.py` 与 `HAL-*` 事后 lint 规则已废弃。
+> 场景错配条目默认属于 **A 层硬约束**，除非单独标注 `[B层]`。
+> 编码风格（STYLE-\*）和资源管理（RESOURCE-\*）规则见 [coding-preferences.md](coding-preferences.md)。
+
+## 幻觉方法名黑名单 `[事前自检]`
+
+| 错误写法 | 正确替代 | 说明 |
+|---|---|---|
+| `setReadOnly(...)` | `getView().setEnable(false, "key")` | 苍穹不存在 setReadOnly 方法 |
+| `afterCreateControl(...)` | `afterBindData` / `registerListener` | 不存在该事件方法 |
+| `IDataModel.setReadOnly(...)` | `getView().setEnable(false, "key")` | 模型层不负责 UI 状态 |
+| `this.getView().refresh()` | `this.getView().updateView(key)` | 不存在 refresh()，使用 updateView |
+| `model.getEntryCount(...)` | `model.getEntryRowCount(entryKey)` | 方法名和参数都不同 |
+| `model.deleteRow(...)` | `model.deleteEntryRow(entryKey, rowIndex)` | 方法名不同 |
+| `model.addRow(...)` | `model.createNewEntryRow(entryKey, rowIndex)` | 方法名不同 |
+| `destroy(...)` | `destory(...)` | 苍穹方法名就是 destory（少 r），不是 destroy |
+| `model.getRowCount(...)` | `model.getEntryRowCount(entryKey)` | 与 JTable 的 getRowCount 混淆 |
+| `model.getEntry(...)` | `dataEntity.getDynamicObjectCollection(entryKey)` 或 `model.getEntryRowEntity(entryKey, rowIndex)` | IDataModel 不存在 getEntry() |
+| `QueryServiceHelper.queryAll(...)` | `QueryServiceHelper.query(entityId, selectFields, filters)` | 不存在 queryAll 方法 |
+
+## 幻觉类名黑名单 `[事前自检]`
+
+- ❌ 不存在以 `Cosmic` 开头的工具类（Utils/Helper/Service），除非脚本明确查到。
+- ❌ 不存在以 `Cloud` 开头的 Utils/Helper 工具类，除非脚本明确查到。项目自定义的 `Cloud*Service` 不在该规则范围内。
+- ❌ 不存在 `BillHelper`（应为 `BusinessDataServiceHelper`）。
+- ❌ 不存在 `FormHelper`（应为 `FormUtils`，位于 `kd.cd.common.form`）。
+- ❌ 不存在 `ListHelper`（应为 `BaseDataServiceHelper` 或 `QueryServiceHelper`）。
+- ❌ 不存在 `PluginHelper`（应按具体场景使用对应 ServiceHelper）。
+
+## 场景错配黑名单 `[A层]`
+
+| 错误做法 | 原因 | 正确做法 | 层级 |
+|---|---|---|---|
+| 在操作插件中调用 `this.getView()` | 操作插件无 UI 上下文 | 使用 `log` 或 `addErrorMessage` | `[A层]` `→ SCENE-001` |
+| 在操作插件中 `this.getModel().setValue(...)` | 操作插件不通过 model 操作 | 直接操作 `DynamicObject` 数据包 | `[A层]` `→ SCENE-002` |
+| 在 UI 插件中做重查询/复杂事务 | UI 插件应保持轻量 | 移至操作插件或服务层 | `[B层]` |
+| 在 `initialize()` 中注册监听或写 UI 状态逻辑 | 生命周期不对，可能失效或错时执行 | 在 `registerListener` 注册，在 `afterBindData` 处理界面状态 | `[A层]` `→ SCENE-006` |
+| 在 `registerListener` 中调用 `model.getValue(...)` | 此时数据尚未绑定 | 推迟到 `afterBindData` | `[B层]` |
+| 在 `beforeBindData` / `afterBindData` 中 `setValue` 或改数据包 | 绑定阶段禁止改数据 | 改到 `createNewData`、`propertyChanged`、保存前等正确事件 | `[A层]` `→ SCENE-008` |
+| 在 `afterCreateNewData` 中期望触发 `propertyChanged` | 此时赋值不触发 | 在 `afterBindData` 中处理级联 | `[B层]` |
+| 仅 `implements Listener` 不注册监听 | 监听不会生效 | 在 `registerListener` 中调用 `add*Listener` | `[B层]` |
+| 对继承型插件 `@Override` 不调 `super.xxx()` | 基类初始化逻辑不执行 | 继承型必须先调 `super`；接口型无需 | `[B层]` |
+| 直接修改 `EntityMetadataCache` 返回的元数据对象 | 缓存对象是单例，污染全局 | `clone` 后再修改 | `[A层]` |
+| 用其他实体 `createInstance()` 的对象给引用属性赋值 `→ SCENE-010` | 引用对象类型可能不一致 | 使用属性复杂类型或当前实体元数据创建对象 | `[A层]` |
+| 在 `propertyChanged` 中无条件 `setValue` `→ SCENE-012` | 触发新的 `propertyChanged` 导致死循环（栈溢出） | 先判断 `e.getProperty().getName()` 是否是目标字段，赋值前比对新旧值是否相同 | `[A层]` |