# 泛用定制销售生产前端接口字段说明

## 1. 背景

本次新增的是一套泛用的“定制销售生产履约”模型，不只服务眼镜，也可扩展到家具、服装、设备等需要定制参数、部件、工序、异常跟踪的行业。

前端需要重点理解三个层级：

1. 销售层：仍然使用现有 `sale_order`、`sale_order_detail`。
2. 履约层：新增 `custom_order_item`，表示一个实际需要生产/采购/装配/交付的定制履约单元。
3. 执行层：新增部件、工序、日志，分别是 `custom_item_component`、`custom_item_process`、`custom_process_log`。

## 2. 核心数据关系

### 2.1 销售订单和定制履约

关系如下：

```text
sale_order
  └─ sale_order_detail
      └─ custom_order_item
          ├─ custom_item_component
          ├─ custom_item_process
          └─ custom_process_log
```

设计原则：

- `sale_order` 表示销售订单。
- `sale_order_detail` 表示销售订单明细。
- `custom_order_item` 表示履约单元。
- 一个 `sale_order_detail` 可以对应一个或多个 `custom_order_item`。
- 不建议为了一个眼镜的左镜片、右镜片、镜架拆成多条 `sale_order_detail`。
- 左镜片、右镜片、镜架应该作为 `custom_item_component` 部件记录。

### 2.2 模板配置关系

```text
custom_flow_template
  ├─ custom_component_template
  ├─ custom_process_template
  └─ custom_param_schema
```

用途：

- `custom_flow_template`：行业/产品对应的定制流程模板。
- `custom_component_template`：模板下有哪些部件，例如镜架、左镜片、右镜片。
- `custom_process_template`：模板下有哪些工序，例如备料、装配、质检、交付。
- `custom_param_schema`：模板下可配置的动态参数定义。

## 3. 新增接口

以下接口走现有后台通用 CRUD 路由。

### 3.1 流程模板

模块：`custom-flow-template`

接口：

```text
GET  /admin/custom-flow-template/index
GET  /admin/custom-flow-template/detail?id={id}
GET  /admin/custom-flow-template/fetch
POST /admin/custom-flow-template/add
POST /admin/custom-flow-template/edit
POST /admin/custom-flow-template/delete
```

主要字段：

| 字段 | 说明 |
| --- | --- |
| `id` | 模板 ID |
| `company_id` | 公司 ID |
| `industry_type` | 行业类型，例如 `optical` |
| `title` | 模板名称 |
| `product_id` | 绑定产品 ID，可为空 |
| `status` | 状态：`1` 正常，`0` 停用 |
| `admin_remark` | 备注 |

### 3.2 部件模板

模块：`custom-component-template`

接口：

```text
GET  /admin/custom-component-template/index
GET  /admin/custom-component-template/detail?id={id}
GET  /admin/custom-component-template/fetch
POST /admin/custom-component-template/add
POST /admin/custom-component-template/edit
POST /admin/custom-component-template/delete
```

主要字段：

| 字段 | 说明 |
| --- | --- |
| `template_id` | 流程模板 ID |
| `component_type` | 部件类型，例如 `frame`、`lens_left`、`lens_right` |
| `component_title` | 部件名称 |
| `default_product_id` | 默认产品 ID |
| `source_type` | 默认来源：`1` 库存，`2` 采购，`3` 委外，`4` 自产 |
| `is_required` | 是否必需 |
| `rank` | 排序 |
| `status` | 状态 |

### 3.3 工序模板

模块：`custom-process-template`

接口：

```text
GET  /admin/custom-process-template/index
GET  /admin/custom-process-template/detail?id={id}
GET  /admin/custom-process-template/fetch
POST /admin/custom-process-template/add
POST /admin/custom-process-template/edit
POST /admin/custom-process-template/delete
```

主要字段：

| 字段 | 说明 |
| --- | --- |
| `template_id` | 流程模板 ID |
| `process_type` | 工序类型，例如 `prepare`、`assemble`、`qc`、`ship` |
| `process_title` | 工序名称 |
| `rank` | 排序 |
| `lead_hours` | 默认工期小时 |
| `auto_start` | 是否自动开始 |
| `auto_finish_rule` | 自动完成规则 |
| `is_required` | 是否必需 |
| `status` | 状态 |

### 3.4 参数定义

模块：`custom-param-schema`

接口：

```text
GET  /admin/custom-param-schema/index
GET  /admin/custom-param-schema/detail?id={id}
GET  /admin/custom-param-schema/fetch
POST /admin/custom-param-schema/add
POST /admin/custom-param-schema/edit
POST /admin/custom-param-schema/delete
```

主要字段：

| 字段 | 说明 |
| --- | --- |
| `template_id` | 流程模板 ID，可为空 |
| `scope` | 作用域：`item`、`component`、`process` |
| `scope_type` | 作用域类型，例如 `lens_left`、`assemble` |
| `param_key` | 参数键 |
| `param_title` | 参数名称 |
| `param_type` | 参数类型：`string`、`number`、`date`、`select`、`json` |
| `options` | 选项配置，JSON |
| `is_required` | 是否必填 |
| `is_searchable` | 是否可搜索 |
| `rank` | 排序 |
| `status` | 状态 |

### 3.5 履约单元

模块：`custom-order-item`

接口：

```text
GET  /admin/custom-order-item/index
GET  /admin/custom-order-item/detail?id={id}
GET  /admin/custom-order-item/fetch
POST /admin/custom-order-item/add
POST /admin/custom-order-item/edit
POST /admin/custom-order-item/delete
```

主要字段：

| 字段 | 说明 |
| --- | --- |
| `industry_type` | 行业类型，例如 `optical` |
| `sale_order_id` | 销售订单 ID |
| `sale_order_detail_id` | 销售订单明细 ID |
| `customer_id` | 客户 ID |
| `template_id` | 流程模板 ID |
| `product_id` | 主产品 ID |
| `third_line_item_id` | 第三方行项目 ID |
| `item_no` | 同一销售明细下第几个履约单元 |
| `quantity` | 履约单元数量，通常为 `1` |
| `params_snapshot` | 下单时完整定制参数快照，JSON |
| `status` | 履约状态 |
| `abnormal_status` | 异常状态 |
| `abnormal_reason` | 异常原因 |
| `is_remake` | 是否重做 |
| `remake_from_id` | 来源履约单元 ID |
| `owner_admin_id` | 负责人 |

履约状态建议前端枚举：

| 值 | 说明 |
| --- | --- |
| `0` | 待处理 |
| `10` | 准备中 |
| `20` | 生产加工中 |
| `30` | 质检中 |
| `40` | 已完成 |
| `50` | 已交付 |
| `80` | 异常 |
| `90` | 取消 |

### 3.6 履约部件

模块：`custom-item-component`

接口：

```text
GET  /admin/custom-item-component/index
GET  /admin/custom-item-component/detail?id={id}
GET  /admin/custom-item-component/fetch
POST /admin/custom-item-component/add
POST /admin/custom-item-component/edit
POST /admin/custom-item-component/delete
```

主要字段：

| 字段 | 说明 |
| --- | --- |
| `custom_order_item_id` | 履约单元 ID |
| `component_template_id` | 部件模板 ID |
| `component_type` | 部件类型 |
| `component_title` | 部件名称 |
| `product_id` | 产品 ID |
| `supplier_id` | 供应商 ID |
| `source_type` | 来源：`1` 库存，`2` 采购，`3` 委外，`4` 自产 |
| `status` | 部件状态 |
| `expected_finish_time` | 预计完成时间 |
| `actual_finish_time` | 实际完成时间 |
| `purchase_order_id` | 采购单 ID |
| `purchase_order_detail_id` | 采购明细 ID |
| `entrust_id` | 委外单 ID |
| `production_receipt_id` | 生产工单 ID |
| `repository_freeze_log_id` | 库存冻结记录 ID |
| `repository_receipt_detail_id` | 出入库明细 ID |
| `tracking_num` | 物流/供应商单号 |
| `params_snapshot` | 部件参数快照，JSON |
| `is_abnormal` | 是否异常 |
| `abnormal_reason` | 异常原因 |

部件状态建议前端枚举：

| 值 | 说明 |
| --- | --- |
| `0` | 待处理 |
| `10` | 已备齐 |
| `20` | 采购中 |
| `30` | 委外中 |
| `40` | 生产中 |
| `50` | 已完成 |
| `80` | 异常 |
| `90` | 取消 |

### 3.7 履约工序

模块：`custom-item-process`

接口：

```text
GET  /admin/custom-item-process/index
GET  /admin/custom-item-process/detail?id={id}
GET  /admin/custom-item-process/fetch
POST /admin/custom-item-process/add
POST /admin/custom-item-process/edit
POST /admin/custom-item-process/delete
```

主要字段：

| 字段 | 说明 |
| --- | --- |
| `custom_order_item_id` | 履约单元 ID |
| `process_template_id` | 工序模板 ID |
| `process_type` | 工序类型 |
| `process_code` | 工序编码 |
| `process_title` | 工序名称 |
| `rank` | 排序 |
| `status` | 工序状态 |
| `main_admin_id` | 执行人 |
| `supplier_id` | 供应商 |
| `plan_start_time` | 计划开始时间 |
| `plan_finish_time` | 计划完成时间 |
| `actual_start_time` | 实际开始时间 |
| `actual_finish_time` | 实际完成时间 |
| `ref_module` | 关联模块 |
| `ref_id` | 关联单据 ID |
| `params_snapshot` | 工序参数快照，JSON |
| `is_abnormal` | 是否异常 |
| `abnormal_reason` | 异常原因 |

工序状态建议前端枚举：

| 值 | 说明 |
| --- | --- |
| `0` | 待开始 |
| `10` | 进行中 |
| `20` | 已完成 |
| `80` | 异常 |
| `90` | 取消 |

### 3.8 流程日志

模块：`custom-process-log`

接口：

```text
GET  /admin/custom-process-log/index
GET  /admin/custom-process-log/detail?id={id}
GET  /admin/custom-process-log/fetch
POST /admin/custom-process-log/add
POST /admin/custom-process-log/edit
POST /admin/custom-process-log/delete
```

主要字段：

| 字段 | 说明 |
| --- | --- |
| `custom_order_item_id` | 履约单元 ID |
| `target_type` | 目标类型：`item`、`component`、`process` |
| `target_id` | 目标 ID |
| `event` | 事件类型 |
| `from_status` | 原状态 |
| `to_status` | 新状态 |
| `remark` | 备注 |
| `operator_admin_id` | 操作人 |
| `create_time` | 记录时间 |

事件类型建议前端枚举：

| 值 | 说明 |
| --- | --- |
| `status_change` | 状态变更 |
| `remake` | 重做 |
| `rollback` | 回退 |
| `abnormal` | 异常 |
| `manual_adjust` | 手工调整 |

## 4. 订单接口新增带出字段

### 4.1 销售订单详情

接口：

```text
GET /admin/sale-order/detail?id={id}
```

新增带出：

```text
custom_order_item_list
```

结构：

```json
{
  "id": 24078,
  "code": "JYKJ-CUSTOM-20260706093814-01",
  "custom_order_item_list": [
    {
      "id": 1,
      "industry_type": "optical",
      "sale_order_id": 24078,
      "sale_order_detail_id": 60644,
      "template_id": 1,
      "product_id": 33817,
      "item_no": 1,
      "quantity": 1,
      "params_snapshot": {},
      "status": 10,
      "abnormal_status": 0,
      "component_list": [],
      "process_list": [],
      "log_list": []
    }
  ]
}
```

说明：

- 该字段只在订单详情默认带出。
- 订单列表暂不默认带出全量履约信息，避免列表接口过重。
- 如果订单列表需要展示定制状态，建议后端后续补轻量统计字段，例如 `custom_item_count`、`custom_abnormal_count`、`custom_progress_status`。

### 4.2 销售订单明细

接口：

```text
GET /admin/sale-order-detail/index?order_id={order_id}
GET /admin/sale-order-detail/detail?id={detail_id}
GET /admin/sale-order-detail/fetch?order_id={order_id}
```

新增带出：

```text
custom_order_item_list
```

结构：

```json
{
  "id": 60644,
  "order_id": 24078,
  "product_id": 33817,
  "num": 2,
  "custom_order_item_list": [
    {
      "id": 1,
      "sale_order_id": 24078,
      "sale_order_detail_id": 60644,
      "item_no": 1,
      "params_snapshot": {},
      "component_list": [],
      "process_list": [],
      "log_list": []
    }
  ]
}
```

说明：

- 订单明细列表默认带出履约单元。
- 履约单元下默认带出部件、工序、日志。
- 前端在订单详情页可以优先从明细的 `custom_order_item_list` 展示每个明细对应的定制履约。

## 5. 眼镜参数存放方式

眼镜度数等参数当前放在：

```text
custom_order_item.params_snapshot
```

示例：

```json
{
  "pd": 63,
  "left": {
    "sphere": -1.25,
    "cylinder": -0.5,
    "axis": 81
  },
  "right": {
    "sphere": -1.5,
    "cylinder": -0.75,
    "axis": 91
  }
}
```

字段说明：

| 字段 | 说明 |
| --- | --- |
| `pd` | 瞳距 |
| `left.sphere` | 左眼球镜 |
| `left.cylinder` | 左眼柱镜 |
| `left.axis` | 左眼轴位 |
| `right.sphere` | 右眼球镜 |
| `right.cylinder` | 右眼柱镜 |
| `right.axis` | 右眼轴位 |

部件级参数可放在：

```text
custom_item_component.params_snapshot
```

建议：

- 订单/履约单元级参数放完整验光和定制快照。
- 左镜片、右镜片的生产加工参数也同步放到对应部件的 `params_snapshot`。
- 前端展示详情时，优先读 `custom_order_item.params_snapshot`；展示部件生产细节时读 `custom_item_component.params_snapshot`。

## 6. 前端页面建议

### 6.1 订单详情页

建议新增“定制履约”区域：

- 展示每个 `custom_order_item`。
- 展示履约状态、异常状态、负责人。
- 展示 `params_snapshot` 中的核心定制参数。
- 展示部件列表。
- 展示工序进度。
- 展示流程日志。

### 6.2 履约单元详情页

建议以 `custom-order-item/detail` 为主接口：

- 基础信息：订单、客户、产品、模板、状态。
- 参数信息：`params_snapshot`。
- 部件信息：`component_list`。
- 工序信息：`process_list`。
- 日志信息：`log_list`。

### 6.3 模板配置页

建议拆成三个 Tab：

- 基础信息：`custom-flow-template`
- 部件配置：`custom-component-template`
- 工序配置：`custom-process-template`
- 参数配置：`custom-param-schema`

## 7. 测试数据

已生成一批测试订单数据，所属公司：

```text
hg8fa286ab8f434d8f
```

批次号：

```text
JYKJ-CUSTOM-20260706093814
```

订单 ID：

```text
24078, 24079, 24080, 24081, 24082, 24083, 24084, 24085, 24086, 24087
```

数据规模：

| 类型 | 数量 |
| --- | --- |
| 销售订单 | 10 |
| 销售订单明细 | 10 |
| 定制履约单元 | 10 |
| 部件 | 30 |
| 工序 | 40 |
| 日志 | 50 |