# 金蝶领域知识手册

本文件是所有金蝶技能（ok-cosmic / kd-enterprise-csharp / kd-enterprise-python-plugin / kd-grill 等）共享的领域真源。需要领域判断时优先读此文件。

## 1. 产品线

| 产品线 ID | 平台 | 开发语言 | 插件模型 | 对应 skill |
|-----------|------|----------|----------|-----------|
| cangqiong | 金蝶AI苍穹 | Java | Cosmic BOS | ok-cosmic |
| xinghan | 金蝶AI星瀚 | Java | Cosmic BOS | ok-cosmic |
| flagship | 金蝶AI星空旗舰版 | Java | Cosmic BOS | ok-cosmic |
| enterprise-csharp | 金蝶AI星空企业版/标准版 C# | C# | .NET BOS | kd-enterprise-csharp |
| enterprise-ironpython | 金蝶AI星空企业版/标准版 IronPython | IronPython | .NET BOS | kd-enterprise-python-plugin |
| enterprise-openapi | 金蝶AI星空企业版 OpenAPI | C# | WebAPI | kd-enterprise-openapi |

**画像真源**：`.trellis/spec/shared/project-context.md`。由 `kcode init --cosmic|--enterprise` 写入。

**判断规则**（不可跨族混淆）：
- Cosmic 族（cangqiong/xinghan/flagship）：Java + Gradle + `kd.bos.*` API
- 企业版族（enterprise-csharp/ironpython/enterprise-openapi）：.NET + MSBuild + `Kingdee.BOS.*` API
- 两族的基类名相同但命名空间不同，事件签名相同，**不能混用 API**

## 2. 插件类型与基类对照（三平台）

### 表单/单据插件

| 场景 | Java (Cosmic) | C# (企业版) | Python (企业版) |
|------|---------------|-------------|-----------------|
| 基类 | AbstractBillPlugin | AbstractBillPlugIn | 裸函数（载入到 AbstractBillPlugIn） |
| 动态表单 | AbstractDynamicFormPlugin | AbstractDynamicFormPlugIn | 裸函数 |
| 命名空间 | kd.bos.* | Kingdee.BOS.Core.Bill.PlugIn | clr.AddReference('Kingdee.BOS.*') |
| 事件风格 | override + super | override + base | 裸函数 def OnLoad(e): |

### 列表插件

| Java | C# | Python |
|------|-----|--------|
| AbstractListPlugin | AbstractListPlugIn | 裸函数 |

### 操作服务插件

| Java | C# | Python |
|------|-----|--------|
| AbstractOperationServicePlugIn | AbstractOperationServicePlugIn | 裸函数 |
| 无 this.View | 无 this.View | 无 this.View |

### 转换插件（BOTP）

| Java | C# | Python |
|------|-----|--------|
| AbstractConvertPlugIn | AbstractConvertPlugIn | 裸函数 |
| 无 this.View | 无 this.View | 无 this.View |

### 报表表单

| Java | C# | Python |
|------|-----|--------|
| AbstractSysReportPlugIn | AbstractSysReportPlugIn | 裸函数 |

### 报表取数服务

| Java | C# | Python |
|------|-----|--------|
| SysReportBaseService | SysReportBaseService | 裸函数 |

### 其他

| 类型 | Java | C# | 说明 |
|------|------|-----|------|
| 校验器 | AbstractValidator | AbstractValidator | 在操作插件 OnAddValidators 中注册 |
| 定时任务 | — | IScheduleService | Run(Context, Schedule) |
| 工作流 | AbstractWorkflowPlugin | — | Cosmic 专有 |
| 树列表 | AbstractTreeListPlugin | — | Cosmic 专有 |
| 反写 | AbstractWriteBackPlugIn | — | BOTP 回写阶段 |
| 打印 | AbstractPrintPlugin | — | Cosmic 专有 |
| WebAPI | — | AbstractWebApiBusinessService | 企业版 OpenAPI |
| 批量导入 | AbstractBatchImportPlugin | — | Cosmic 专有 |

## 3. 核心事件生命周期

### 表单生命周期（执行顺序 ↑ 表示先执行 ↓ 表示后执行）

```
BeforeCreateModelData → CreateNewData → AfterCreateModelData
    → OnLoad → BeforeBindData → AfterBindData
    → DataChanged（用户操作触发）
    → BarItemClick / ButtonClick（菜单/按钮点击）
    → BeforeF7Select（放大镜选择前）
    → BeforeDoOperation → BeforeSave（保存前）
        → BeginOperationTransaction（事务内）
        → EndOperationTransaction（事务内）
        → AfterExecuteOperationTransaction（事务外）
    → AfterDoOperation
```

### 操作服务生命周期

```
OnPrepareOperationServiceOption（设置事务选项）
    → OnPreparePropertys（声明需要加载的字段）
    → OnAddValidators（注册校验器）
    → BeforeExecuteOperationTransaction（事务外校验）
    → BeginOperationTransaction（事务内，可回滚）
        → 实际业务执行
    → EndOperationTransaction（事务内，可回滚）
    → RollbackData（发生异常时触发）
    → AfterExecuteOperationTransaction（事务外，追加提示）
```

### 转换插件（BOTP）生命周期

```
OnQueryBuilderParemeter（构建查询参数，声明额外加载字段）
    → OnParseFilter / OnParseFilterOptions（过滤条件）
    → BeforeGetSourceData → OnGetSourceData（获取源单数据）
    → OnBeforeGroupBy（分单分组）
    → CreateTarget（创建目标单）
    → OnBeforeFieldMapping → OnFieldMapping → OnAfterFieldMapping（字段赋值）
    → OnCreateLink → OnAfterCreateLink（创建关联）
    → OnGetConvertBusinessService（表单服务策略）
    → AfterConvert（全部完成）
```

## 3.5 字段标识口径（按产品线）

### 企业版 / 标准版（必须区分三标识）

**必读**：[three-identifiers.md](three-identifiers.md)（**仅企业版**）。

- View/`GetValue`/`FieldKey` → **标识 Key**
- `billObj["…"]` → **实体属性 PropertyName**（只认元数据；常与 Key 不同）
- SQL → **字段名 FieldName**（库列）
- 取证：`metadata-db-query.md`

### 苍穹 / 星瀚 / 旗舰版（Cosmic 族，不套企业版三标识）

- 同一 Java 模型（`kd.bos.*`），**不要**对企业版那样拆 Key/PropertyName/FieldName 三层口诀。  
- 插件字段以 **field key** + 平台 API 为准（见 `ok-cosmic`）；库表列名写 SQL/KSQL 时仍须元数据确认。  
- 规范集：`rules/kd-flagship-*`。






## 4. 核心约束

- 表单/列表插件可以用 `this.View`；操作服务/转换/报表取数**不能**
- 事务钩子（BeginOperationTransaction）内修改数据包，**不独立调用 Save**
- 字段 key 必须经元数据验证（**只读连库**查 FKERNELXML/fdata 并解析，见 [metadata-db-query.md](metadata-db-query.md)），**禁止臆造**
- 禁止循环内 DB 调用、Redis、ORM.create
- 枚举值必须从元数据读，不能猜


- 异常不吞（catch 块至少记日志）
- Cosmic Java 用 `kd.bos.*`，企业版用 `Kingdee.BOS.*`，**不能混**

## 5. 技能导航

| 需要 | 读哪个 skill |
|------|-------------|
| 需求拷问/领域建模 | `kd-grill` |
| **元数据只读连库查询与解析** | [metadata-db-query.md](metadata-db-query.md)（grill/写码共用） |
| Cosmic Java 插件编码 | `ok-cosmic` + 事件表 `assets/*.md` |
| 企业版插件形态选型 | [enterprise-plugin-shape.md](enterprise-plugin-shape.md) |
| 企业版 C# 插件编码 | `kd-enterprise-csharp` + 事件表 `assets/*.md` |

| 企业版 IronPython 编码 | `kd-enterprise-python-plugin` + 事件表 `assets/*.md` |
| 苍穹二开规范集（6 文件，先读索引） | `rules/kd-flagship-index` → 命名/注释/插件/数据/安全/SDK |
| 企业版二开规范集（7 文件，先读索引） | `rules/kd-enterprise-index` → 工程/代码/DB/API/支付/UI/安全 |
| 交付规则/编码规范 | `kd-delivery-rules` / `kd-coding-standards` |
| 苍穹代码审查 | `kd-cosmic-review` + `kd-cosmic-review-rules` |
| 运行时常见错误模式 | `rules/kd-debug-rules` |
| KSQL 数据修复 | `kd-ksql` |
| 企业版 OpenAPI | `kd-enterprise-openapi` |