platforms/docs/08-生产管理系统需求.md

# 生产管理系统需求（规划基线）

## 1. 文档目的

本文定义生产管理系统的职责边界、角色权限、数据模型原则、生产与质检流程、设备身份安全和规划验收标准，作为后续 `frontend/product_admin` 及对应后端能力的规划基线。

当前仓库尚未实现生产管理系统。本文描述的是目标能力，不代表现有平台总后台已经交付，也不得通过在平台后台增加通用 CRUD 页面冒充生产闭环。

## 2. 系统定位与边界

生产管理系统主责智能瓶阀及关联配件的型号执行、生产计划、工序、序列号、设备身份注入、质量检验、成品仓储、出厂和质量追溯。

生产管理系统不承担以下主责：

- 不创建或管理用户、气站、配送点和服务人员账号。
- 不建立用户设备绑定，不处理商城订单、配送任务、用户钱包或支付。
- 不处理平台告警运营、安检整改、远程开关阀或设备控制授权。
- 不修改平台已发布的安全规则、商品价格、合同或结算政策。
- 不直接向气站或配送点业务库写库存事实，只通过出厂/调拨契约交付。
- 不允许任何生产角色查看与生产质量无关的用户隐私、交易和定位数据。

设备型号、IoT 能力定义、固件正式发布和设备召回策略需要平台设备/安全主责方审批；生产系统负责执行已批准版本并形成可追溯事实。

## 3. 角色与权限

### 3.1 角色职责

| 角色 | 可用能力 | 明确禁止 |
| --- | --- | --- |
| 生产管理员 | 维护本生产单位、产线、班组和本单位角色分配，查看本单位综合进度 | 修改平台全局型号、批准自己提交的高风险发布、查看用户/订单/资金 |
| 生产计划员 | 根据已批准型号/BOM 创建生产计划和工单、排产、调整数量与计划时间 | 修改 BOM 已发布版本、填写质检结论、放行设备、接触设备私钥 |
| 产线操作员 | 执行分配工序、扫码领料、记录产量、设备序列号和工序异常 | 修改计划、跳过工序、填写最终质检、报废后恢复设备 |
| 质检员 | 执行来料、过程和出厂检验，记录原始结果、缺陷和复检 | 修改生产原始记录、批准本人提交的让步放行、删除不合格结果 |
| 仓管员 | 执行物料和成品收发、库位、盘点、出库交接 | 修改质检结果、将未放行设备转为可出库、修改设备身份状态 |
| 身份注入操作员 | 在受控工位执行序列号绑定、证书申请和安全注入 | 查看或导出明文私钥、批量复用凭证、批准证书策略 |
| 售后质量人员 | 处理 RMA、故障归因、批次趋势和召回执行 | 远程控制用户设备、修改用户订单、删除历史质量结论 |

### 3.2 职责分离

- 计划创建、生产执行、质检判定、成品放行和出库不得由单一普通角色包办。
- 同一质检员不能单独批准本人发起的让步接收或重大缺陷关闭。
- 固件签名、设备证书策略、批量吊销和召回发布属于高风险能力，需要独立审批。
- 生产管理员仅管理本生产单位，不自动拥有平台设备、安全或 IoT 管理权限。
- 前端按钮、扫码枪配置和工位网络隔离不能替代服务端权限与状态校验。

## 4. 技术与数据约定

- 每张表包含 `id bigint` 自增主键、`created_at` 和 `updated_at`。
- 主表及可独立访问、跨系统引用或审计定位的明细包含 UUID V7 `identity`。
- HTTP、事件、日志和跨系统同步使用 `identity`，不暴露内部自增 ID。
- 设备序列号、生产工单号、批次号、检验单号和 RMA 编号是唯一业务编号，但不能替代物理主键和 `identity`。
- 生产数量使用整数；测试值必须记录数值、单位、上下限、仪器、校准状态和采集时间。
- 工序记录、检验原始值、设备身份注入、证书状态、出厂记录和召回记录属于事实数据，不允许物理删除或覆盖。
- 所有写操作具备幂等键；扫码、自动测试台和离线工位补传必须保留原始采集时间与服务端接收时间。

## 5. 规划功能域

### 5.1 产品执行基线

生产系统读取平台已批准的设备型号、硬件版本、IoT 能力和安全约束，并维护生产执行所需的版本化 BOM、工艺路线、检验规范和包装规范。

| 能力 | 规则 |
| --- | --- |
| 型号引用 | 只能选择平台已批准且处于可生产状态的型号 |
| BOM 版本 | 草稿可编辑；发布后不可覆盖，只能创建新版本 |
| 工艺路线 | 工序顺序、必做项、工位能力和返工路径版本化 |
| 检验规范 | 测试项目、上下限、抽检规则和判定规则版本化 |
| 变更控制 | BOM、工艺和检验规范变更需评审、生效时间和影响批次 |

普通操作员、仓管员和质检员不能发布型号、BOM 或工艺版本。

### 5.2 物料与供应批次

- 维护本单位供应商引用、采购批次、到货数量、批号、有效期和质量状态。
- 来料必须经过规定检验或获得受控放行，才能进入可领料库存。
- 不合格物料进入隔离状态，不能通过普通库存调整回到可用。
- 领料、退料、替代料和批次拆并保留生产工单、操作者和审批依据。
- 供应商主数据和采购结算若由 ERP 主责，生产系统只同步引用，不重复维护财务事实。

### 5.3 生产计划与工单

```text
已批准型号/BOM -> 创建计划 -> 下达生产工单 -> 领料
-> 工序执行 -> 过程检验 -> 完工待检 -> 出厂检验
```

- 工单记录型号、版本、批次、计划数量、产线、工艺路线和检验规范快照。
- 已下达工单不能直接替换版本；变更需评估已领料、在制品和已生成设备身份。
- 产线操作员只能执行分配给本工位、当前状态允许的工序。
- 跳站、超量生产、序列号重复和未授权返工必须被服务端拒绝。
- 工序异常形成独立记录，不通过修改原始结果掩盖。

### 5.4 设备身份与安全注入

| 能力 | 关键规则 |
| --- | --- |
| 序列号生成 | 按批准规则生成且全局唯一，作废后不得复用 |
| 二维码 | 只承载设备公开标识或受签名内容，不包含私钥和长期管理令牌 |
| 证书申请 | 每台设备使用独立身份，记录证书序列号、状态和有效期 |
| 密钥注入 | 在受控工位或 HSM/安全模块内完成，应用和日志不得获得明文私钥 |
| 身份绑定 | 序列号、模组标识、硬件版本、证书和生产批次一一关联 |
| 吊销与换证 | 必须记录原因、审批、操作者和同步结果 |

请求成功不代表注入成功。系统必须记录待处理、执行中、成功、失败和待确认状态，并以安全工位或设备回执为准。

### 5.5 质量检验

- 支持来料检验、过程检验、出厂检验、抽检、复检和返工后检验。
- 检验至少覆盖适用的压力、密封、通信、开关动作、电源、电池温度、传感器和固件版本。
- 自动测试结果保留原始数据、测试台、软件版本、仪器校准信息、测试时间和操作者。
- 不合格项记录缺陷代码、严重度、处置、责任批次和证据。
- 原始结果不可修改；录入错误通过更正记录和复检结果表达。
- 未完成必检项、存在未关闭致命缺陷或证书注入失败的设备不得出厂放行。

### 5.6 固件生产使用

生产系统只使用平台已批准、签名有效且与型号兼容的固件版本进行烧录。

- 记录烧录工位、固件哈希、签名校验、设备序列号、时间和结果。
- 产线人员不能上传或发布正式固件，不能关闭签名校验。
- 灰度 OTA、在线升级策略和用户设备升级由平台 IoT/设备域主责；生产系统只提供生产烧录与质量追溯数据。
- 发现固件质量问题时，生产系统提交影响批次和设备清单，由平台决定在线处置策略。

### 5.7 成品仓储与出厂

- 只有完成全部生产工序、出厂检验合格、设备身份有效且状态为已放行的设备才能入成品可用库。
- 入库、移库、盘点、冻结、出库和交接形成不可变库存流水。
- 出库关联接收组织、交付单、设备清单、批次、质检结论和交接结果。
- 生产系统记录“生产方已交付”；气站或配送点接收后的经营库存由其主责系统记录，不能由生产系统直接修改。
- 运输损坏、接收差异和退回进入异常流程，不得覆盖原出厂记录。

### 5.8 售后质量与召回

- RMA 关联设备序列号、故障现象、固件、生产批次、历史检验和处理结论。
- 失效分析保留拆检、测试、根因、纠正预防措施和责任批次。
- 批次质量趋势可生成召回建议，但生产系统不能自行远程停用或控制用户设备。
- 召回范围和风险等级经平台审批后，生产系统负责设备清单、返厂、复检、维修、报废和替换追踪。
- 历史质量记录、召回前状态和处置证据不得删除。

## 6. 设备入网与平台同步

```mermaid
flowchart LR
  A[生成序列号] --> B[绑定硬件与批次]
  B --> C[安全注入设备身份]
  C --> D[工序与功能测试]
  D --> E{出厂检验合格}
  E -->|否| F[隔离/返工/报废]
  E -->|是| G[成品放行]
  G --> H[同步平台设备主档]
  H --> I{平台确认}
  I -->|失败| J[异常队列与重试]
  I -->|成功| K[允许交付和后续激活]
```

向平台同步的最小数据包括：

- 设备 `identity`、序列号、公开二维码状态和型号。
- 硬件版本、固件版本、生产工单和生产批次。
- 设备证书状态与有效期，不包含私钥。
- 出厂检验结论、放行状态、激活资格和同步时间。
- 召回、作废、换码、换证和报废状态。

同步使用幂等键并记录请求、响应和重试。同步失败、数据冲突或平台未确认时，设备不得被标记为已入网成功。

平台只接受质检合格、身份有效且具备激活资格的设备。生产系统不得同步用户、订单、钱包、服务关系或现场履约事实。

## 7. 审计与安全

- 型号/BOM引用、计划下达、工序执行、返工、检验、放行、注入、出库、RMA 和召回全程审计。
- 设备私钥不得进入数据库业务字段、接口响应、日志、导出、测试样例或人工下载文件。
- 身份注入工位采用最小网络权限、设备认证和操作员双重鉴权。
- 高风险操作记录申请人、审批人、原因、前后状态、设备范围和结果，申请人与最终审批人按规则分离。
- 自动测试和工位离线补传必须校验幂等、顺序、数据签名和完整性。
- 生产系统的数据范围至少隔离生产单位、工厂、产线和角色，禁止普通角色跨单位查询。

## 8. 未实现范围

当前仓库不存在 `frontend/product_admin` 及独立生产后端。生产计划、BOM、工艺、设备身份注入、质量检验、成品仓储、RMA 和召回均属于规划能力。

用户绑定、配送履约、平台安全运营、设备远程控制、资金结算和在线 OTA 策略不属于生产管理系统建设范围。

## 9. 规划验收标准

1. 生产角色只能访问所属生产单位、产线和职责范围内的数据。
2. 计划、执行、质检、放行和出库具备职责分离，普通角色不能一人完成全部高风险环节。
3. 已发布 BOM、工艺和检验规范不可覆盖，工单保留执行版本快照。
4. 序列号全局唯一且作废不复用；设备身份、硬件、证书和批次一一对应。
5. 私钥不以明文进入接口、日志、数据库或导出，注入结果以受控工位回执为准。
6. 未完成必检项、不合格、身份失败或未获平台确认的设备不能放行、出库或激活。
7. 原始生产、测试和质检事实不可删除或覆盖，更正和复检形成新记录。
8. 出厂同步具备幂等、重试、冲突处理和平台确认状态。
9. 生产系统不能写入用户、订单、资金、服务关系、安全事件或设备控制事实。
10. 越权、跳站、重复序列号、重复同步、非法放行和密钥泄露场景具有服务端测试。