# 外部系统与星空 OpenAPI 集成模式

> **二开字段（如扩展文本、对照 ID）以你们账套元数据为准**；生成 Save Model 时用 `QueryBusinessInfo` / View 确认字段标识，勿照搬示例中的扩展字段名。

## 1. 连接与客户端

- **官方 SDK**：`com.kingdee.bos.webapi.sdk.K3CloudApi` + `IdentifyInfo`（`serverUrl`、`dCID` 账套、`appId`、`appSecret`、`userName`、`lCID=2052`）。
- **多账套/多环境**：配置表存连接信息，取一条「启用」记录构造默认 `K3CloudApi`。
- **密钥**：`appSecret` 加密存储，避免写入日志。

模板：[assets/K3CloudApiServiceImpl.java](../assets/K3CloudApiServiceImpl.java)、[assets/KingdeeConfigDTO.java](../assets/KingdeeConfigDTO.java)。

## 2. 统一 ERP 门面（推荐）

在业务 Service 外再包一层：

- `executeBillQuery(json)` — 建议超时约 10s，网络错误可重试（如最多 3 次）
- `save` / `delete` / `submit` / `audit` / `unAudit` / `cancelAssign` — 15–30s

模板：[assets/KingdeeErpServiceJava.java](../assets/KingdeeErpServiceJava.java)。

**响应解析**：核对 `Result.ResponseStatus.IsSuccess` 与 `Errors`；不同 SDK 版本键名大小写可能不一致。

## 3. Save 请求标准壳（KingdeeSaveRequest）

常见 Save 外层字段：

| 字段 | 典型值 | 说明 |
|------|--------|------|
| NeedUpDateFields | `[]` 或指定字段 | 部分更新 |
| NeedReturnFields | `fid`、`billNo`、分录 `FEntryID` | 回写外部系统 |
| IsDeleteEntry | `true`/`false` | 改单是否先删分录 |
| IsVerifyBaseDataField | `false` | 联调期可关，上线再开 |
| ValidateFlag / NumberSearch | `true` | |
| IsAutoAdjustField | `true` | 自动补全组织等 |
| Model | Map / JSON | 业务体 |

模板：[assets/KingdeeSaveRequest.java](../assets/KingdeeSaveRequest.java)。

## 4. 典型销售链（示例）

```
外部销售订单 ──Save/Submit──► SAL_SaleOrder
         │
         ├─► 发货通知 ──Save──► SAL_DELIVERYNOTICE（分录 FEntity_Link 关联源订单）
         │
         ├─► 收款 ──Push（RuleId 见 push-rules-catalog）──► AR_RECEIVEBILL ──Save 补分录──► Submit
         │
         ├─► 开票 ──Save──► IV_SALESIC（分录 Link 关联订单或应收）
         │
         └─► 借货出库 ──Save──► STK_MisDelivery

删除：查 FDocumentStatus → 已提交则 cancelAssign → delete
工作流中（如状态 D）：可先 workflowAudit 再 submit
```

片段见 `assets/snippets/` 下 Sal / Ar / Iv / Stk 系列。

## 5. Save 前常用查询

| FormId | 用途 |
|--------|------|
| BD_Customer | 客户 |
| BD_OPERATOR | 业务员 |
| BD_NEWSTAFF | 员工任岗→部门 |
| SAL_SaleOrder | 按单号查状态、销售员、部门 |

`FilterString` 中的业务单号须转义，避免注入。

## 6. 幂等与回写

- 外部系统保存 ERP `fid`、分录 `FEntryID`、单据编号。
- Save：`fid=0` 新建，非 0 修改。
- Model 中可增加对照字段（扩展字段）做幂等与对账。

## 7. 与本技能的关系

- **协议**：以 [SKILL.md](../SKILL.md) HTTP 服务名为准。
- **实现**：有 Java SDK 优先 `K3CloudApi`；否则用 `OpenApiClient*` 裸 HTTP。
- **BOS 插件**：见 `kd-enterprise-csharp`，非本技能范围。