258 lines
14 KiB
Markdown
258 lines
14 KiB
Markdown
# LMS 日计划管理与作业设计
|
||
|
||
## 目标
|
||
|
||
在 LMS 的“管芯库管理”下新增“日计划管理”和“日计划作业”两个页面，接收 ERP 当日日计划并支持人工建单。日计划开始后，现场人员可维护备货、套管、取消、恢复和结束状态；后续定时器根据进行中的日计划生成实际任务。本期只维护日计划及调度状态，不下发桁架、出入库或套管任务。
|
||
|
||
## 范围
|
||
|
||
- ERP 幂等推送日计划。
|
||
- 人工新增、编辑和查询日计划。
|
||
- 开始、结束、取消和恢复订单。
|
||
- 开始、取消和恢复备货或套管。
|
||
- 追加管芯数量。
|
||
- 人工调整日计划顺序和权重。
|
||
- 备货、套管分别维护全局调度策略，并支持即时切换。
|
||
- 查询操作记录和状态时间节点。
|
||
- 为后续定时器提供待备货、待套管计划查询及完成数量更新能力。
|
||
- 不实现实际任务生成、任务下发、库存扣减和桁架交互。
|
||
- 不拆分管芯明细表。一张日计划只对应一种管芯，不同订单即使管芯相同也独立流转。
|
||
|
||
## 菜单与页面边界
|
||
|
||
在 `LMS管理 → 管芯库管理` 下新增两个同级菜单。
|
||
|
||
### 日计划管理
|
||
|
||
该页面负责全量查询和基础维护：
|
||
|
||
- 查询所有日期、所有状态的日计划。
|
||
- 查看基本信息、数量进度、状态时间和操作记录。
|
||
- 人工新增日计划。
|
||
- 编辑未开始的人工日计划。
|
||
- 对未开始订单执行“开始订单”。
|
||
- 对未开始订单执行“取消订单”，填写原因后可从作业页恢复。
|
||
- 已结束订单只在本页面查询，不进入作业页面。
|
||
|
||
查询条件在桌面端一行多项展示，包括日计划编号或 ERP 订单号、计划日期范围、管芯编码或名称、来源和订单状态。
|
||
|
||
### 日计划作业
|
||
|
||
该页面负责现场操作，不以计划日期作为限制：
|
||
|
||
- 默认查询已经开始、尚未结束且订单状态为“进行中”的日计划，跨天计划继续显示。
|
||
- 单独提供“已取消”页签，显示允许恢复的取消订单。
|
||
- 展示并维护顺序、权重、备货进度和套管进度。
|
||
- 提供追加数量、开始/取消/恢复备货、开始/取消/恢复套管、取消/恢复/结束订单等操作。
|
||
- 提供备货策略和套管策略的独立切换入口。
|
||
- 不提供人工新增和未开始计划编辑。
|
||
|
||
## 数据模型
|
||
|
||
### 日计划主表 `lms_daily_plan`
|
||
|
||
主表保存当前业务事实和调度状态：
|
||
|
||
- 标识：日计划 ID、日计划编号。
|
||
- 来源：来源类型（ERP、人工）、ERP 订单号。
|
||
- 计划：计划日期、装箱信息多行文本。
|
||
- 管芯：管芯物料 ID、物料编码、物料名称、规格。
|
||
- 数量：计划数量、追加数量、已备货数量、已套管数量。
|
||
- 调度：顺序号、权重。
|
||
- 状态：订单状态、备货状态、套管状态。
|
||
- 状态时间：订单开始/结束时间、备货开始/完成时间、套管开始/完成时间。
|
||
- 恢复信息：取消前订单状态、取消前备货状态、取消前套管状态，用于准确恢复。
|
||
- 并发控制：版本号。
|
||
- 通用审计字段：创建人、创建时间、修改人、修改时间、删除标记、租户 ID。
|
||
|
||
需求总量不单独存储，统一按“计划数量 + 追加数量”计算。已备货数量和已套管数量不能超过需求总量。
|
||
|
||
人工日计划编号由编码规则生成，格式为 `DPyyyyMMdd0001`。ERP 订单号仅对 ERP 来源必填，并在租户范围内唯一，用于幂等处理。
|
||
|
||
### 策略配置表 `lms_daily_plan_strategy`
|
||
|
||
每个租户固定两条业务配置：
|
||
|
||
- 备货策略。
|
||
- 套管策略。
|
||
|
||
每条配置保存业务类型、当前模式、修改人、修改时间和版本号。当前模式包括“顺序模式”和“权重轮转模式”。数据库唯一约束保证同一租户、同一业务类型只有一条有效配置；查询或调度时若当前租户尚无配置，则并发安全地懒初始化备货、套管两类默认顺序策略，已逻辑删除的历史配置不自动恢复或重复插入。
|
||
|
||
### 操作记录表 `lms_daily_plan_operation_log`
|
||
|
||
操作记录只追加、不修改，保存：
|
||
|
||
- 日计划 ID；策略切换记录允许日计划 ID 为空。
|
||
- 操作类型和操作对象（订单、备货、套管、策略、数量、排序、权重）。
|
||
- 操作前值、操作后值。
|
||
- 数量变化。
|
||
- 操作原因。
|
||
- 操作人和操作时间。
|
||
- 租户 ID。
|
||
|
||
开始、结束、取消、恢复、追加、调整顺序、调整权重和策略切换均写入记录。取消和恢复必须填写原因。
|
||
|
||
## 状态模型
|
||
|
||
订单、备货和套管分别保存状态，避免备货与套管并行时丢失业务事实。
|
||
|
||
### 订单状态
|
||
|
||
- 未开始：ERP 推送或人工新增后的初始状态。
|
||
- 进行中：人工执行“开始订单”后进入。
|
||
- 已结束：人工执行“结束订单”后进入，不允许恢复。
|
||
- 已取消：人工可从任意未结束状态取消，允许恢复。
|
||
|
||
结束订单允许随时执行。结束时将尚未完成的备货和套管停止并标记为已取消，保留实际完成数量；订单结束后不可再备货、套管、追加或恢复。
|
||
|
||
取消订单时，将尚未完成的备货和套管同步标记为已取消，并分别记录操作历史。恢复订单后，订单恢复为取消前状态；备货和套管仍保持已取消，由人工按需分别恢复，避免恢复订单时自动重启作业。
|
||
|
||
### 备货状态与套管状态
|
||
|
||
两类作业使用相同状态集合：
|
||
|
||
- 未开始。
|
||
- 进行中。
|
||
- 已完成。
|
||
- 已取消。
|
||
|
||
“开始备货”和“开始套管”只改变状态，不直接生成或下发任务。定时器或后续业务更新完成数量；完成数量达到需求总量时，对应状态自动变为已完成并记录完成时间。
|
||
|
||
单独取消备货或套管只停止对应流程，不影响另一流程和订单。恢复时回到取消前状态。已完成流程不允许取消或恢复。
|
||
|
||
## ERP 推送规则
|
||
|
||
ERP 推送字段包括 ERP 订单号、计划日期、管芯物料信息、计划数量和装箱信息。接口通过 ERP 订单号与租户 ID 幂等识别订单：
|
||
|
||
- 首次推送：创建 ERP 来源日计划，自动生成 LMS 日计划编号，三个状态均为未开始。
|
||
- 相同订单未开始：覆盖管芯信息、计划数量、计划日期和装箱信息，不覆盖 LMS 审计信息。
|
||
- 相同订单进行中，ERP 数量增加：计划数量保持原值，增加的差额累计到追加数量，并记录操作历史。
|
||
- 相同订单进行中，ERP 数量不变：视为幂等成功，不产生重复记录。
|
||
- 相同订单进行中，ERP 数量减少：拒绝推送并返回明确原因。
|
||
- 相同订单已结束或已取消：拒绝推送。
|
||
|
||
ERP 推送不允许直接修改顺序、权重、当前完成数量或作业状态。
|
||
|
||
## 人工创建和维护
|
||
|
||
人工创建字段包括计划日期、人工订单号、管芯物料、计划数量、装箱信息、顺序和权重。人工订单号统一去除首尾空白；未填写、全空白或修改时清空，均使用 LMS 日计划编号作为订单号。
|
||
|
||
只有未开始的人工来源日计划允许编辑基本信息。ERP 来源计划通过 ERP 幂等推送维护，管理页面只读。开始订单时 ERP 和人工来源均允许再次确认计划数量，并可填写追加数量；计划数量、累计追加数量和开始状态在同一事务中原子更新，开始成功后进入日计划作业页面。
|
||
|
||
追加数量仅允许订单进行中时执行，必须大于零，按累计值保存并记录每次追加明细。
|
||
|
||
## 调度策略
|
||
|
||
备货和套管分别维护一套租户级全局策略。策略切换后，所有进行中的日计划从定时器下一轮查询开始使用新策略；已经生成或下发的任务不撤销。
|
||
|
||
### 顺序模式
|
||
|
||
按人工顺序号从小到大处理。前一个日计划对应流程完成或取消后，再选择下一个日计划。
|
||
|
||
页面只展示和维护顺序字段，不展示权重字段。
|
||
|
||
### 权重轮转模式
|
||
|
||
先按顺序号从小到大确定订单轮转先后，再按每张订单的权重决定该轮处理数量。例如 A 的顺序为 1、权重为 2，B 的顺序为 2、权重为 3，则调度次序为 A 处理 2 根、B 处理 3 根，再回到 A 处理 2 根，循环至完成或取消。
|
||
|
||
页面同时展示顺序和权重。权重必须为正整数。若某张计划剩余数量小于权重，本轮只处理剩余数量。完成或取消的计划立即退出轮转，下一轮按剩余计划的顺序继续。
|
||
|
||
备货策略与套管策略独立，因此同一张计划可在备货调度中采用一种模式，在套管调度中采用另一种模式。
|
||
|
||
## 定时器衔接
|
||
|
||
本期不实现任务下发定时器，但 Service 和 Mapper 提供明确的数据能力：
|
||
|
||
- 查询订单进行中、备货进行中且已备货数量小于需求总量的计划。
|
||
- 查询订单进行中、套管进行中且已套管数量小于需求总量的计划。
|
||
- 按当前备货或套管策略返回下一批候选计划及本轮建议数量。
|
||
- 原子增加已备货数量或已套管数量。
|
||
- 数量达到需求总量时自动完成对应流程。
|
||
|
||
轮转游标由策略配置保存，记录下一轮应从哪个日计划继续，避免定时器每次都从顺序第一张开始。调整顺序、取消、完成或切换策略后，下一轮重新校验游标；游标对应计划不再可调度时，按当前顺序选择下一张。
|
||
|
||
## 后端接口边界
|
||
|
||
### ERP 接口
|
||
|
||
- 推送日计划：提供给 ERP 的幂等写入接口。
|
||
|
||
### 管理端接口
|
||
|
||
- 日计划管理分页。
|
||
- 日计划作业分页。
|
||
- 日计划详情和操作记录。
|
||
- 人工新增、编辑未开始计划。
|
||
- 开始订单。
|
||
- 追加数量。
|
||
- 开始、取消、恢复备货。
|
||
- 开始、取消、恢复套管。
|
||
- 取消、恢复、结束订单。
|
||
- 批量调整顺序。
|
||
- 修改权重。
|
||
- 查询和切换备货、套管策略。
|
||
|
||
每个状态操作使用独立请求对象和接口，不使用通用“修改状态”接口，防止客户端绕过状态机。查询 SQL 统一写入 MyBatis XML。
|
||
|
||
## 前端交互
|
||
|
||
- 管理页面搜索条件同行排列，空间不足时响应式换行。
|
||
- 管理列表展示计划与 ERP 订单号、日期、管芯、需求总量、进度、三个状态、来源、修改人和修改时间。
|
||
- 作业页面默认进入“进行中”页签，另有“已取消”页签用于恢复。
|
||
- 作业列表始终展示顺序；当当前业务策略为权重轮转时额外展示权重。
|
||
- 备货与套管策略在页面顶部独立展示和切换。
|
||
- 操作按钮根据三个状态动态显示，不可执行的操作不展示。
|
||
- 新增和编辑使用抽屉；详情抽屉包含基本信息、状态时间和操作记录。
|
||
- 开始、结束、取消、恢复、追加和策略切换均二次确认；取消和恢复弹窗要求填写原因。
|
||
|
||
## 权限
|
||
|
||
权限按职责拆分：
|
||
|
||
- 日计划查询。
|
||
- 日计划人工新增。
|
||
- 日计划编辑。
|
||
- 开始订单。
|
||
- 日计划作业操作。
|
||
- 顺序和权重维护。
|
||
- 策略切换。
|
||
- ERP 推送接口使用独立的接口鉴权，不复用管理端登录权限。
|
||
|
||
菜单 SQL 以幂等方式将两个页面挂载到“管芯库管理”下，并同步已授权角色所需的父目录权限。
|
||
|
||
## 并发与事务
|
||
|
||
- 页面状态及资料操作使用日计划版本号进行乐观锁校验；调度数量确认不绑定整张日计划版本。
|
||
- 状态变更、数量变更和对应操作记录在同一事务中提交。
|
||
- 批量调整顺序在一个事务内完成；任一计划版本冲突时整体回滚。
|
||
- 策略切换和轮转游标更新使用版本号，避免两个调度线程重复选择同一轮计划。
|
||
- 每次调度先持久化排他 Claim，Claim 令牌、作业类型、预占数量、领取时作业进度和 Claim 自身版本共同构成确认并发边界。备货与套管 Claim 相互独立。
|
||
- 进度确认先原子消费 Claim，再以领取时对应作业进度为条件累计数量；重复确认同一已完成 Claim 幂等成功，不重复计数。
|
||
- 排序、权重、ERP 追加和另一作业进度不会阻断有效 Claim 确认。取消、结束后不再产生新 Claim，但已下发的有效 Claim 仍可确认；确认只累计数量，保留用户选择的取消或结束状态。
|
||
- Claim 支持续租、主动释放和过期回收；过期或已释放 Claim 不得确认。
|
||
|
||
## 错误处理
|
||
|
||
- 日计划不存在时返回业务异常。
|
||
- ERP 数量减少、更新已结束或已取消计划时返回明确原因。
|
||
- 未开始订单不能执行备货、套管、追加和结束作业操作。
|
||
- 已结束订单不能取消、恢复、追加或重新开始。
|
||
- 完成数量不能为负数，也不能超过需求总量。
|
||
- 顺序号和权重必须为正整数，且只允许对订单状态为“进行中”的计划修改；批量排序任一计划状态不符时整批回滚。
|
||
- 取消和恢复未填写原因时由参数校验直接拒绝。
|
||
- 非法状态流转返回业务异常，不做静默幂等成功。
|
||
- 请求失败沿用全局错误提示，不在前端吞掉异常。
|
||
|
||
## 验证
|
||
|
||
遵循项目“未经明确要求不新增测试”的规则，本次不创建自动化测试文件，使用以下方式验收：
|
||
|
||
- 后端 Maven 编译，验证 Java、Mapper XML 和模块依赖。
|
||
- 前端 TypeScript 类型检查和相关文件 ESLint。
|
||
- SQL 脚本语法、幂等重复执行和菜单层级校验。
|
||
- 本地接口联调 ERP 首次推送、重复推送、数量增加、数量减少和终态拒绝。
|
||
- 人工核对订单、备货、套管的开始、取消、恢复、完成和结束状态流转。
|
||
- 人工核对跨天进行中订单持续出现在作业页面。
|
||
- 人工核对顺序模式与权重轮转模式的列展示和候选计划顺序。
|
||
- 模拟页面操作与定时器同时更新，确认版本冲突不会覆盖完成数量。
|