kcode-pi 0.1.0

package/knowledge/cosmic/review-checklist.md

@@ -0,0 +1,40 @@
+# Cosmic Review Checklist
+
+Use for Cangqiong, Xinghan, and Xingkong Flagship Java code review.
+
+## P0 Blocking Issues
+
+- Listener registration or UI mutation in `initialize`.
+- Independent `SaveServiceHelper.save` inside operation transaction hooks when the transaction data packet should be modified directly.
+- `DataSet` not closed.
+- `DataSet` row fields read without being selected in query fields.
+- Validator or operation plugin reads fields that were not declared in prepare hooks.
+- Loop contains DB calls, service calls, ORM creation, or save operations.
+- SQL string concatenation, `Statement`, sensitive credentials, or external entity XML use.
+- Hard-coded organization, user, department, or environment-dependent IDs.
+- `beforeBindData` or `afterBindData` mutates model data.
+- Native JDK threads or executors bypass platform thread management.
+
+## P1 High-Risk Issues
+
+- Loop contains `updateView` or repeated field-index lookup.
+- Large entry loops use repeated `model.setValue`.
+- Missing query filters cause full table scans.
+- Query field paths are too deep and may create Cartesian products.
+- Third-party calls lack timeout settings.
+- `beginInit` and `endInit` are not paired.
+- Collections accumulate without bounds.
+
+## P2 Maintainability Issues
+
+- User-visible Chinese strings are not resource-managed when the project requires i18n.
+- Exception logs omit stack traces.
+- Magic numbers and scattered status values are not centralized.
+- Plugin class suffix or method naming does not match project conventions.
+- Empty catch blocks hide failures.
+
+## Review Output
+
+- Prioritize behavior, data consistency, transaction boundaries, performance, and security before style.
+- Avoid regex-only judgment; confirm context before reporting.
+- Separate P0, P1, and P2, and provide actionable remediation.

package/knowledge/cosmic/unittest.md

@@ -0,0 +1,35 @@
+# Cosmic Unit Test Guidance
+
+Use for Cosmic-family Java modules that follow common, business, opplugin, and formplugin project structure.
+
+## Project Structure
+
+- `<module>-common`: constants, enums, POJO, DTO, utility classes.
+- `<module>-business`: static helpers and business services.
+- `<module>-opplugin`: validators, operation plugins, conversion plugins.
+- `<module>-formplugin`: form, list, and bill plugins.
+
+## Test Routing
+
+- Common POJO/DTO: instantiate directly, no static mocks.
+- Common enum: test lookup and match methods.
+- Business helper: mock static service helpers and verify outputs or side effects.
+- Validator: collect validation messages and cover declared field preparation.
+- Operation plugin: test transaction data packets, field declarations, and operation results.
+- Form plugin: use the module's `BasePluginTest` or existing tests to obtain view/model mocks.
+
+## Mock Rules
+
+- Mock static helpers such as `QueryServiceHelper`, `BusinessDataServiceHelper`, `OperationServiceHelper`, `SaveServiceHelper`, `BaseDataServiceHelper`, `SystemParamServiceHelper`, and `ResManager` only when the code imports or calls them.
+- Close every `MockedStatic` in teardown.
+- Do not duplicate mocks already provided by the module's base test.
+- Mock `kd.bos.db.DB` only after defrost handling if the project requires it.
+- Some project helpers require custom test helper mocks; do not replace those with generic static mocks without checking existing tests.
+
+## Assertion Rules
+
+- Every test must assert a real output, side effect, exception, or mock interaction.
+- Do not use tautological assertions such as `assertTrue(true)`.
+- Cover switch cases as separate tests.
+- Cover boundary values around comparisons, empty collections, one row, and multiple rows.
+- If source code appears buggy, write the expected correct behavior and call out that the test exposes the bug.

package/knowledge/enterprise/api-reference.md

@@ -0,0 +1,186 @@
+# 金蝶云星空企业版 C# API 参考
+
+## 核心服务类
+
+### BusinessDataServiceHelper
+
+业务数据服务助手，是最常用的数据访问类。
+
+**常用方法：**
+
+```csharp
+// 加载单个数据实体
+DynamicObject LoadSingle(Context ctx, object pkValue, string entityName)
+
+// 加载多个数据实体
+DynamicObject[] Load(Context ctx, object[] pkValues, string entityName)
+
+// 按条件查询
+DynamicObject[] Load(Context ctx, string entityName, QFilter[] filters)
+
+// 按条件查询指定字段
+DynamicObject[] Load(Context ctx, string entityName, string selectFields, QFilter[] filters)
+
+// 加载基础资料
+DynamicObject LoadSingle(Context ctx, string entityName, object pkValue, QFilter[] filters)
+```
+
+**使用示例：**
+
+```csharp
+// 加载采购订单
+QFilter filter = new QFilter("billno", "=", "PO-001");
+DynamicObject[] orders = BusinessDataServiceHelper.Load(
+    ctx, 
+    "PUR_POOrder", 
+    new QFilter[]{filter}
+);
+
+if (orders.Length > 0)
+{
+    DynamicObject order = orders[0];
+    string billNo = order["billno"] as string;
+    decimal totalAmount = Convert.ToDecimal(order["totalamount"]);
+}
+```
+
+### DBUtils
+
+数据库工具类，用于执行 SQL 查询。
+
+**常用方法：**
+
+```csharp
+// 执行查询，返回 DataSet
+DataSet ExecuteDataSet(Context ctx, string sql)
+
+// 执行查询带参数
+DataSet ExecuteDataSet(Context ctx, string sql, List<SqlParam> parameters)
+
+// 执行更新
+int Execute(Context ctx, string sql)
+
+// 执行更新带参数
+int Execute(Context ctx, string sql, List<SqlParam> parameters)
+```
+
+**使用示例：**
+
+```csharp
+// 查询采购订单
+string sql = "SELECT FBILLNO, FDATE, FAMOUNT FROM T_PUR_POORDER WHERE FDOCUMENTSTATUS = 'C'";
+DataSet ds = DBUtils.ExecuteDataSet(ctx, sql);
+
+foreach (DataRow row in ds.Tables[0].Rows)
+{
+    string billNo = row["FBILLNO"] as string;
+    DateTime date = Convert.ToDateTime(row["FDATE"]);
+    decimal amount = Convert.ToDecimal(row["FAMOUNT"]);
+}
+```
+
+### IDBAccesser
+
+数据访问接口，提供 ORM 功能。
+
+**常用方法：**
+
+```csharp
+// 执行查询
+DataSet Query(string sql)
+
+// 执行更新
+int Update(string sql)
+
+// 批量插入
+void InsertBatch(string tableName, DataSet data)
+```
+
+---
+
+## 插件基类
+
+### AbstractOperationServicePlugIn
+
+操作服务插件基类，用于操作事件处理。
+
+**常用事件：**
+
+```csharp
+// 准备属性
+public override void OnPreparePropertys(PreparePropertysEventArgs e)
+
+// 操作执行前
+public override void BeforeExecuteOperationTransaction(BeforeExecuteOperationTransaction e)
+
+// 操作执行后
+public override void AfterExecuteOperationTransaction(AfterExecuteOperationTransaction e)
+
+// 添加校验规则
+public override void OnAddValidateRules(AddValidateRulesEventArgs e)
+```
+
+### AbstractOperationCheckPlugIn
+
+操作校验插件基类，用于数据校验。
+
+**常用方法：**
+
+```csharp
+// 自定义校验规则
+public override void OnAddValidateRules(AddValidateRulesEventArgs e)
+
+// 校验数据
+public override void Validate(ValidateEventArgs e)
+```
+
+### AbstractBillPlugIn
+
+表单插件基类，用于表单事件处理。
+
+**常用事件：**
+
+```csharp
+// 表单加载后
+public override void AfterBindData(EventArgs e)
+
+// 字段值变更后
+public override void AfterPropertyChanged(PropertyChangedEventArgs e)
+
+// 保存前
+public override void BeforeSave(BeforeSaveEventArgs e)
+
+// 保存后
+public override void AfterSave(EventArgs e)
+```
+
+---
+
+## 常用工具类
+
+### StringUtils
+
+字符串处理工具。
+
+```csharp
+// 判断是否为空
+bool IsEmpty(string str)
+
+// 判断是否不为空
+bool IsNotEmpty(string str)
+
+// 去除空格
+string Trim(string str)
+```
+
+### KDException
+
+金蝶自定义异常。
+
+```csharp
+// 抛出异常
+throw new KDException("错误编码", "错误信息");
+
+// 带原因的异常
+throw new KDException("错误编码", "错误信息", innerException);
+```

package/knowledge/enterprise/code-patterns.md

@@ -0,0 +1,217 @@
+# 金蝶云星空企业版 C# 代码模式
+
+## 数据访问模式
+
+### 模式一：BusinessDataServiceHelper 查询
+
+**适用场景：** 按主键或条件查询单个/多个实体
+
+```csharp
+// 按主键查询
+DynamicObject entity = BusinessDataServiceHelper.LoadSingle(
+    ctx, 
+    primaryKey, 
+    "PUR_POOrder"
+);
+
+// 按条件查询
+QFilter filter = new QFilter("billno", "=", "PO-001");
+DynamicObject[] entities = BusinessDataServiceHelper.Load(
+    ctx, 
+    "PUR_POOrder", 
+    new QFilter[]{filter}
+);
+
+// 查询指定字段
+string[] selectFields = new string[] { "id", "billno", "date", "amount" };
+DynamicObject[] entities = BusinessDataServiceHelper.Load(
+    ctx, 
+    "PUR_POOrder", 
+    selectFields, 
+    new QFilter[]{filter}
+);
+```
+
+### 模式二：DBUtils SQL 查询
+
+**适用场景：** 复杂查询、报表查询、跨表查询
+
+```csharp
+// 简单查询
+string sql = "SELECT FBILLNO, FDATE, FAMOUNT FROM T_PUR_POORDER WHERE FDOCUMENTSTATUS = 'C'";
+DataSet ds = DBUtils.ExecuteDataSet(ctx, sql);
+
+// 带参数查询
+string sql = "SELECT * FROM T_PUR_POORDER WHERE FDATE >= @StartDate AND FDATE <= @EndDate";
+List<SqlParam> parameters = new List<SqlParam>
+{
+    new SqlParam("@StartDate", startDate),
+    new SqlParam("@EndDate", endDate)
+};
+DataSet ds = DBUtils.ExecuteDataSet(ctx, sql, parameters);
+
+// 聚合查询
+string sql = "SELECT FSUPPLIERID, SUM(FAMOUNT) AS TOTAL FROM T_PUR_POORDER GROUP BY FSUPPLIERID";
+DataSet ds = DBUtils.ExecuteDataSet(ctx, sql);
+```
+
+---
+
+## 事务处理模式
+
+### 事务内操作
+
+```csharp
+// 使用 KDTransactionScope
+using (KDTransactionScope scope = new KDTransactionScope())
+{
+    try
+    {
+        // 业务操作
+        DBUtils.Execute(ctx, sql1);
+        DBUtils.Execute(ctx, sql2);
+        
+        scope.Complete();
+    }
+    catch (Exception)
+    {
+        // 事务会自动回滚
+        throw;
+    }
+}
+```
+
+---
+
+## 异常处理模式
+
+### 业务异常处理
+
+```csharp
+public void ProcessOrder(DynamicObject order)
+{
+    try
+    {
+        // 业务逻辑
+        ValidateOrder(order);
+        SaveOrder(order);
+    }
+    catch (KDException ex)
+    {
+        // 业务异常，记录日志并抛出
+        Logger.Error("处理订单失败: " + ex.Message, ex);
+        throw;
+    }
+    catch (Exception ex)
+    {
+        // 其他异常，包装为业务异常
+        Logger.Error("系统异常: " + ex.Message, ex);
+        throw new KDException("SYS001", "系统异常，请联系管理员", ex);
+    }
+}
+```
+
+### 校验异常处理
+
+```csharp
+public void ValidateOrder(DynamicObject order)
+{
+    List<string> errors = new List<string>();
+    
+    // 校验必填字段
+    if (string.IsNullOrEmpty(order["FBillNo"] as string))
+    {
+        errors.Add("单据编号不能为空");
+    }
+    
+    // 校验业务规则
+    decimal amount = Convert.ToDecimal(order["FAmount"] ?? 0);
+    if (amount <= 0)
+    {
+        errors.Add("金额必须大于零");
+    }
+    
+    // 抛出校验异常
+    if (errors.Count > 0)
+    {
+        throw new KDException("VALIDATE001", string.Join("; ", errors));
+    }
+}
+```
+
+---
+
+## 日志记录模式
+
+### 使用 Logger
+
+```csharp
+private static readonly ILog Logger = LogManager.GetLogger(typeof(OrderPlugin));
+
+// 记录信息
+Logger.Info("开始处理订单: " + billNo);
+
+// 记录警告
+Logger.Warn("订单金额较大: " + amount);
+
+// 记录错误
+Logger.Error("处理订单失败", exception);
+
+// 调试日志
+if (Logger.IsDebugEnabled)
+{
+    Logger.Debug("订单详情: " + order.ToString());
+}
+```
+
+---
+
+## 批量处理模式
+
+### 批量查询
+
+```csharp
+// 分批查询大量数据
+int batchSize = 1000;
+int offset = 0;
+List<DynamicObject> allResults = new List<DynamicObject>();
+
+while (true)
+{
+    string sql = string.Format(
+        "SELECT * FROM T_PUR_POORDER ORDER BY FID OFFSET {0} ROWS FETCH NEXT {1} ROWS ONLY",
+        offset, batchSize
+    );
+    DataSet ds = DBUtils.ExecuteDataSet(ctx, sql);
+    
+    if (ds.Tables[0].Rows.Count == 0) break;
+    
+    foreach (DataRow row in ds.Tables[0].Rows)
+    {
+        // 处理每行数据
+        allResults.Add(ConvertToEntity(row));
+    }
+    
+    offset += batchSize;
+}
+```
+
+### 批量更新
+
+```csharp
+// 使用事务批量更新
+using (KDTransactionScope scope = new KDTransactionScope())
+{
+    foreach (var entity in entities)
+    {
+        string sql = "UPDATE T_PUR_POORDER SET FStatus = @Status WHERE FID = @ID";
+        List<SqlParam> parameters = new List<SqlParam>
+        {
+            new SqlParam("@Status", "C"),
+            new SqlParam("@ID", entity["FID"])
+        };
+        DBUtils.Execute(ctx, sql, parameters);
+    }
+    scope.Complete();
+}
+```

package/knowledge/enterprise/plugin-lifecycle.md

@@ -0,0 +1,188 @@
+# 金蝶云星空企业版插件生命周期
+
+## 操作服务插件生命周期 (AbstractOperationServicePlugIn)
+
+### 生命周期顺序
+
+```
+操作触发
+  ↓
+OnPreparePropertys() - 准备属性
+  ↓
+OnAddValidateRules() - 添加校验规则
+  ↓
+BeforeExecuteOperationTransaction() - 操作执行前
+  ↓
+ExecuteOperationTransaction() - 执行操作（事务内）
+  ↓
+AfterExecuteOperationTransaction() - 操作执行后
+  ↓
+操作完成
+```
+
+### 关键事件详解
+
+#### OnPreparePropertys - 准备属性
+
+**触发时机：** 操作开始前，用于指定需要加载的字段
+
+**用途：**
+- 指定需要访问的字段
+- 优化数据加载性能
+
+**示例：**
+```csharp
+public override void OnPreparePropertys(PreparePropertysEventArgs e)
+{
+    // 添加需要访问的字段
+    e.FieldKeys.Add("FQty");
+    e.FieldKeys.Add("FPrice");
+    e.FieldKeys.Add("FAmount");
+}
+```
+
+#### BeforeExecuteOperationTransaction - 操作执行前
+
+**触发时机：** 操作事务开始前
+
+**用途：**
+- 业务规则校验
+- 数据预处理
+- 权限检查
+
+**示例：**
+```csharp
+public override void BeforeExecuteOperationTransaction(BeforeExecuteOperationTransaction e)
+{
+    string operateKey = e.OperateKey;
+    
+    if (operateKey == "Submit")
+    {
+        // 提交前校验
+        foreach (var entity in e.DataEntitys)
+        {
+            decimal amount = Convert.ToDecimal(entity["FAmount"] ?? 0);
+            if (amount <= 0)
+            {
+                throw new KDException("", "金额必须大于零");
+            }
+        }
+    }
+}
+```
+
+#### AfterExecuteOperationTransaction - 操作执行后
+
+**触发时机：** 操作事务提交后
+
+**用途：**
+- 触发下游业务
+- 发送通知
+- 记录日志
+
+**示例：**
+```csharp
+public override void AfterExecuteOperationTransaction(AfterExecuteOperationTransaction e)
+{
+    string operateKey = e.OperateKey;
+    
+    if (operateKey == "Audit")
+    {
+        // 审核后触发下游业务
+        foreach (var entity in e.DataEntitys)
+        {
+            TriggerDownstreamBusiness(entity);
+        }
+    }
+}
+```
+
+---
+
+## 表单插件生命周期 (AbstractBillPlugIn)
+
+### 生命周期顺序
+
+```
+表单打开
+  ↓
+AfterBindData() - 绑定数据后
+  ↓
+用户操作
+  ↓
+AfterPropertyChanged() - 字段值变更后
+  ↓
+BeforeSave() - 保存前
+  ↓
+AfterSave() - 保存后
+  ↓
+表单关闭
+```
+
+### 示例
+
+```csharp
+public class OrderPlugin : AbstractBillPlugIn
+{
+    public override void AfterBindData(EventArgs e)
+    {
+        // 初始化界面
+        this.View.Visible = true;
+        this.View.SetControlValue("FStatus", "A");
+    }
+    
+    public override void AfterPropertyChanged(PropertyChangedEventArgs e)
+    {
+        if (e.Property.Name == "FQty")
+        {
+            // 数量变更后计算金额
+            decimal qty = Convert.ToDecimal(e.NewValue);
+            decimal price = Convert.ToDecimal(this.Model.GetValue("FPrice"));
+            decimal amount = qty * price;
+            this.Model.SetValue("FAmount", amount);
+        }
+    }
+    
+    public override void BeforeSave(BeforeSaveEventArgs e)
+    {
+        // 校验必填字段
+        var dataEntity = this.Model.DataEntity;
+        string billNo = dataEntity["FBillNo"] as string;
+        
+        if (string.IsNullOrEmpty(billNo))
+        {
+            e.Cancel = true;
+            this.View.ShowErrorNotification("单据编号不能为空");
+            return;
+        }
+    }
+}
+```
+
+---
+
+## 校验插件生命周期 (AbstractOperationCheckPlugIn)
+
+### 示例
+
+```csharp
+public class AmountCheckPlugin : AbstractOperationCheckPlugIn
+{
+    public override void OnAddValidateRules(AddValidateRulesEventArgs e)
+    {
+        // 添加校验规则
+        e.AddValidateRule("FAmount", "金额必须大于零");
+    }
+    
+    public override void Validate(ValidateEventArgs e)
+    {
+        var dataEntity = e.DataEntity;
+        decimal amount = Convert.ToDecimal(dataEntity["FAmount"] ?? 0);
+        
+        if (amount <= 0)
+        {
+            e.AddError("FAmount", "金额必须大于零");
+        }
+    }
+}
+```