# 数据字典接口文档

## 1. 通用约定

- 基础路径：`/api/dictionary`
- 请求方法：`GET`
- 参数位置：URL Query 参数
- 分页：服务端固定返回第 1 页、每页最多 100 条；不要传入 `page`、`pageSize`
- 所有 SQL 条件均由服务端固定维护，调用方只能传入文档中声明的筛选参数
- 未注册字典编码、缺少必填参数或传入未声明参数时，接口返回 HTTP `400`

公司参数 `ent` 的映射：

| `ent` 值 | ERP 公司编号 |
| --- | --- |
| `明磊` | `86` |
| `越南` | `60` |

## 2. 成功响应

```json
{
  "code": 200,
  "isSuccess": true,
  "result": {
    "page": 1,
    "pageSize": 100,
    "total": 238,
    "records": []
  }
}
```

`records` 中的字段名与 ERP 查询 SQL 的返回字段一致。`total` 为符合条件的总记录数，`records` 最多包含 100 条。

## 3. 接口清单

| 字典编码 | 业务名称 | 必填参数 | 可选参数 |
| --- | --- | --- | --- |
| `erp-supplier` | ERP 供应商视图 | `t100id`、`ent` | `pmaal004` |
| `erp-packaging-b9-window-view` | 明磊包材 B9 开窗视图 | `t100id`、`ent` | `keyword` |
| `erp-packaging-material` | 包材材质 | `ent` | `keyword` |
| `erp-material-original-price` | 根据材料编号取原单价 | `czbh`、`ent` | 无 |
| `erp-item-view` | ERP 料件视图 | `ent` | `keyword` |
| `erp-sales-order` | 销售订单开窗 | `t100id` | `keyword` |
| `erp-sales-order-line` | 客户订单项次 | 无 | `keyword` |
| `erp-order-qty` | 订单号查订单数量 | `ddh` | 无 |
| `erp-order-product-model` | 订单号查产品型号 | `ddh` | 无 |
| `erp-production-order` | 生产令开窗 | `t100id`、`userId` | 无 |
| `erp-supplier-disabled` | ERP 供应商禁用视图 | `t100id`、`ent` | `keyword` |
| `erp-active-item` | T100 有效料号 | 无 | `keyword` |
| `erp-template-item` | 范本料号开窗 | 无 | `keyword` |
| `erp-template-orders` | 范本料号开窗对应所有订单 | `bgfblh` | `keyword` |
| `erp-last-price` | 取料号上次价格 | `main.pmdi004`、`detail_1.ljbh` | 无 |
| `erp-unfulfilled-order` | 已审核未发齐出通单 | `ent`、`site`、`keyword` | 无 |
| `erp-delivery-order` | 出通单列表 | `ent`、`site` | `keyword` |
| `erp-outsourced-purchase-order-window` | 委外采购单开窗 | `formtable_main_158_dt1_wwcgdh` | 无 |
| `erp-outsourced-bom` | 委外采购对应工单备料 | `formtable_main_158_dt1_wwcgdh`、`formtable_main_158_dt1_cgxc` | 无 |

## 4. 接口说明

### 4.1 ERP 供应商视图

```http
GET /api/dictionary/erp-supplier?t100id=ML&ent=明磊&pmaal004=供应商
```

- `t100id`：据点。
- `ent`：公司名称，仅支持 `明磊` 或 `越南`。
- `pmaal004`：供应商名称，可选，按包含关系模糊匹配。
- 返回：`DSDATA.erp_apmt440_pmaauc_v` 的全部字段。

### 4.2 明磊包材 B9 开窗视图

```http
GET /api/dictionary/erp-packaging-b9-window-view?t100id=ML&ent=明磊&keyword=B9开窗
```

- `keyword` 可选，同时匹配料件编号 `imaf001`、中文品名 `imaal003`、规格 `imaal004`。
- 仅返回中文料件信息，排除 `TY`、`LTY`，并限制料件编码以 `B9`、`VB9` 或 `J` 开头。
- 返回字段：`imaf001`、`imaal003`、`imaal004`。

### 4.3 包材材质

```http
GET /api/dictionary/erp-packaging-material?ent=明磊&keyword=彩盒
```

- `keyword` 可选，同时匹配包材编号 `pmaauc001`、包材名称 `pmaauc002`、材质类型 `tp`。
- `tp` 将 ERP 编码转换为 `说明书`、`彩盒`、`纸箱`、`标贴`。
- 返回字段：`pmaauc001`、`pmaauc002`、`tp`。

### 4.3.1 根据材料编号取原单价

```http
GET /api/dictionary/erp-material-original-price?czbh=B9-001&ent=明磊
```

- `czbh`：材料编号，必填，按 `pmaauc001` 精确匹配。
- `ent`：公司名称，必填，仅支持 `明磊` 或 `越南`。
- 返回字段：`pmaauc002`、`pmaauc015`、`pmaauc001`、`pmaaucent`。

### 4.4 ERP 料件视图

```http
GET /api/dictionary/erp-item-view?ent=明磊&keyword=电池
```

- `keyword` 可选，同时按料号 `imaa001` 和中文品名 `imaal003` 模糊匹配。
- 返回：`DSDATA.erp_apmt440_imaauc_v` 的全部字段。

### 4.5 销售订单开窗

```http
GET /api/dictionary/erp-sales-order?t100id=ML&keyword=SO-001
```

- 固定查询公司 `86` 的已审核订单。
- `keyword`：可选，按销售订单号 `xmdadocno` 模糊匹配。
- 仅返回存在未交数量、料号不以 `6` 开头且不属于指定排除客户的订单。
- 返回订单、客户、料件、未交数量和开票关联信息。

### 4.5.1 客户订单项次

```http
GET /api/dictionary/erp-sales-order-line?keyword=SO-001-10
```

- SQL 使用 `T100客户订单项次.sql`，公司 `86`、据点 `ML` 及原有筛选条件保持不变。
- `keyword`：可选，普通文本，不是数组。对返回列 `docseq` 模糊匹配。例如 `keyword=SO-001-10`。

### 4.5.2 订单号查订单数量

```http
GET /api/dictionary/erp-order-qty?ddh=SO-001
```

- SQL 使用 `订单号查订单数量.sql`。表名加 `DSDATA`，公司 `86`、据点 `ML` 及原有筛选条件保持不变。
- `ddh`：订单号，必填，精确匹配 `xmdcdocno`。
- 只汇总 `xmdc019 = '1'` 且料号以 `1` 开头的明细。
- 返回字段：`xmdc007`。没有符合条件的明细时仍返回一行，数量为 `0`。

### 4.5.3 订单号查产品型号

```http
GET /api/dictionary/erp-order-product-model?ddh=SO-001
```

- SQL 使用 `订单号查产品型号.sql`。表名加 `DSDATA`，公司 `86`、据点 `ML` 及原有筛选条件保持不变。
- `ddh`：订单号，必填，精确匹配 `xmdcdocno`。
- 只取 `xmdc019 = '1'` 且料号以 `1` 开头的明细，返回这些明细规格 `imaal004` 的最大值。
- 返回字段：`imaal004`。没有符合条件的明细时仍返回一行，型号为空。

### 4.6 生产令开窗

```http
GET /api/dictionary/erp-production-order?t100id=ML&userId=USER-001
```

- `userId`：钉钉用户 ID，必填。服务端先从本地员工花名册查询对应的 `employee_no`。
- 固定查询公司 `86` 的已审核订单；员工工号需同时匹配订单业务员字段 `xmda002`，并将该工号在 `ooag_t` 对应的 `ooag003` 与订单部门字段 `xmdaowndp` 进行匹配。
- 不限制未交数量。

### 4.7 ERP 供应商禁用视图

```http
GET /api/dictionary/erp-supplier-disabled?t100id=ML&ent=明磊&keyword=供应商
```

- 返回：`DSDATA.ERP_APMT440_PMAAUC_N` 的全部字段。
- `keyword` 可选，按供应商名称字段 `pmaal004` 模糊匹配。

### 4.8 T100 有效料号

```http
GET /api/dictionary/erp-active-item?keyword=B9
```

- 固定查询公司 `86`、据点 `ML`。
- `keyword` 可选，同时对料号 `imaa001` 和中文品名 `imaal003` 进行模糊匹配。
- 排除 `imaa010 = 'TY'` 的停用料号。
- 返回字段：`imaa001`、`imaal003`、`imaal004`。

### 4.9 范本料号开窗

```http
GET /api/dictionary/erp-template-item?keyword=B9
```

- 固定查询公司 `86` 的未停用料号。
- `keyword` 可选，同时按料号 `imaa001` 和中文品名 `imaal003` 模糊匹配。
- 返回字段：`imaa001`、`imaal003`、`imaal004`。

### 4.10 范本料号开窗对应所有订单

```http
GET /api/dictionary/erp-template-orders?bgfblh=B9&keyword=SO-001
```

- `bgfblh`：范本料号前缀，必填；服务端自动追加 `%` 进行前缀匹配。
- `keyword`：可选，按订单号 `xmdadocno` 模糊匹配。
- 固定查询公司 `86`、据点 `ML` 中状态不为 `X` 的订单与料件明细。
- `xmdastus` 转换为中文状态：`已结案`、`未审核`、`已审核`、`留置`、`其他`。

### 4.11 取料号上次价格

```http
GET /api/dictionary/erp-last-price?main.pmdi004=SUP-001&detail_1.ljbh=B9-001
```

- `main.pmdi004`：宜搭主表料号，必填。
- `detail_1.ljbh`：宜搭子表料件编号，必填。
- 固定查询公司 `86`、据点 `ML` 中有效且在生效期间内的采购价格单。
- 按相同料号和料件编号取最新确认时间，返回价格字段 `pmdj011`。

### 4.12 已审核未发齐出通单

```http
GET /api/dictionary/erp-unfulfilled-order?ent=明磊&site=ML&keyword=MLCT6261023002-1
```

- `ent`：公司名称，必填，仅支持 `明磊` 或 `越南`。
- `site`：据点，必填。
- `keyword`：出通单号与项次，必填，按 `出通单号-项次` 精确匹配，例如 `MLCT6261023002-1`。
- 返回出通单号 `xmdgdocno`、项次 `xmdhseq`、内外销 `xmda048`、生产令 `xmdcud010`、料号 `xmdh006`、料件中文名称 `imaal003`、规格 `imaal004`、客户编号 `xmdg005` 和客户中文名称 `pmaal003`。

### 4.13 出通单列表

```http
GET /api/dictionary/erp-delivery-order?ent=明磊&site=ML&keyword=110001-1
```

- `ent`：公司名称，必填，仅支持 `明磊` 或 `越南`。
- `site`：据点，必填。
- `keyword`：可选，按拼接后的“出通单号-项次”模糊匹配，例如 `110001-1`。
- 仅返回状态为 `Y`、`H`、`N` 的出通单明细。
- 返回出通单号 `xmdgdocno`、生产令 `xmdcud010`、样品标识 `xmdc019` 和未发数量 `k`；`xmdc019=9` 返回“样品”，其他值返回“一般”。

### 4.14 委外采购单开窗

```http
GET /api/dictionary/erp-outsourced-purchase-order-window?formtable_main_158_dt1_wwcgdh=WWCG-001
```

- `formtable_main_158_dt1_wwcgdh`：采购单号，必填。
- 固定查询公司 `86`、据点 `ML`。
- 返回字段：`pmdpseq`、`pmdp003`、`pmdp001`、`imaal003`、`imaal004`、`pmdp023`、`sfaaud009`。

### 4.15 委外采购对应工单备料

```http
GET /api/dictionary/erp-outsourced-bom?formtable_main_158_dt1_wwcgdh=WWCG-001&formtable_main_158_dt1_cgxc=10
```

- `formtable_main_158_dt1_wwcgdh`：采购单号，必填。
- `formtable_main_158_dt1_cgxc`：采购项次，必填。
- 固定查询公司 `86`、据点 `ML`。
- 返回字段：`sfba006`、`imaal003`、`imaal004`、`sfba013`。

## 5. 兼容路径

历史路径 `erp-material` 目前仍映射到 `erp-packaging-b9-window-view`。新接入调用请统一使用正式路径：

```http
GET /api/dictionary/erp-packaging-b9-window-view?t100id=ML&ent=明磊
```