diff --git a/docs/superpowers/specs/2026-08-14-lms-daily-plan-design.md b/docs/superpowers/specs/2026-08-14-lms-daily-plan-design.md new file mode 100644 index 00000000..48f58f13 --- /dev/null +++ b/docs/superpowers/specs/2026-08-14-lms-daily-plan-design.md @@ -0,0 +1,253 @@ +# 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 幂等推送维护,管理页面只读。开始订单时允许再次确认计划数量,并可填写追加数量;开始成功后进入日计划作业页面。 + +追加数量仅允许订单进行中时执行,必须大于零,按累计值保存并记录每次追加明细。 + +## 调度策略 + +备货和套管分别维护一套租户级全局策略。策略切换后,所有进行中的日计划从定时器下一轮查询开始使用新策略;已经生成或下发的任务不撤销。 + +### 顺序模式 + +按人工顺序号从小到大处理。前一个日计划对应流程完成或取消后,再选择下一个日计划。 + +页面只展示和维护顺序字段,不展示权重字段。 + +### 权重轮转模式 + +先按顺序号从小到大确定订单轮转先后,再按每张订单的权重决定该轮处理数量。例如 A 的顺序为 1、权重为 2,B 的顺序为 2、权重为 3,则调度次序为 A 处理 2 根、B 处理 3 根,再回到 A 处理 2 根,循环至完成或取消。 + +页面同时展示顺序和权重。权重必须为正整数。若某张计划剩余数量小于权重,本轮只处理剩余数量。完成或取消的计划立即退出轮转,下一轮按剩余计划的顺序继续。 + +备货策略与套管策略独立,因此同一张计划可在备货调度中采用一种模式,在套管调度中采用另一种模式。 + +## 定时器衔接 + +本期不实现任务下发定时器,但 Service 和 Mapper 提供明确的数据能力: + +- 查询订单进行中、备货进行中且已备货数量小于需求总量的计划。 +- 查询订单进行中、套管进行中且已套管数量小于需求总量的计划。 +- 按当前备货或套管策略返回下一批候选计划及本轮建议数量。 +- 原子增加已备货数量或已套管数量。 +- 数量达到需求总量时自动完成对应流程。 + +轮转游标由策略配置保存,记录下一轮应从哪个日计划继续,避免定时器每次都从顺序第一张开始。调整顺序、取消、完成或切换策略后,下一轮重新校验游标;游标对应计划不再可调度时,按当前顺序选择下一张。 + +## 后端接口边界 + +### ERP 接口 + +- 推送日计划:提供给 ERP 的幂等写入接口。 + +### 管理端接口 + +- 日计划管理分页。 +- 日计划作业分页。 +- 日计划详情和操作记录。 +- 人工新增、编辑未开始计划。 +- 开始订单。 +- 追加数量。 +- 开始、取消、恢复备货。 +- 开始、取消、恢复套管。 +- 取消、恢复、结束订单。 +- 批量调整顺序。 +- 修改权重。 +- 查询和切换备货、套管策略。 + +每个状态操作使用独立请求对象和接口,不使用通用“修改状态”接口,防止客户端绕过状态机。查询 SQL 统一写入 MyBatis XML。 + +## 前端交互 + +- 管理页面搜索条件同行排列,空间不足时响应式换行。 +- 管理列表展示计划与 ERP 订单号、日期、管芯、需求总量、进度、三个状态、来源、修改人和修改时间。 +- 作业页面默认进入“进行中”页签,另有“已取消”页签用于恢复。 +- 作业列表始终展示顺序;当当前业务策略为权重轮转时额外展示权重。 +- 备货与套管策略在页面顶部独立展示和切换。 +- 操作按钮根据三个状态动态显示,不可执行的操作不展示。 +- 新增和编辑使用抽屉;详情抽屉包含基本信息、状态时间和操作记录。 +- 开始、结束、取消、恢复、追加和策略切换均二次确认;取消和恢复弹窗要求填写原因。 + +## 权限 + +权限按职责拆分: + +- 日计划查询。 +- 日计划人工新增。 +- 日计划编辑。 +- 开始订单。 +- 日计划作业操作。 +- 顺序和权重维护。 +- 策略切换。 +- ERP 推送接口使用独立的接口鉴权,不复用管理端登录权限。 + +菜单 SQL 以幂等方式将两个页面挂载到“管芯库管理”下,并同步已授权角色所需的父目录权限。 + +## 并发与事务 + +- 页面操作和定时器数量更新使用版本号进行乐观锁校验。 +- 状态变更、数量变更和对应操作记录在同一事务中提交。 +- 批量调整顺序在一个事务内完成;任一计划版本冲突时整体回滚。 +- 策略切换和轮转游标更新使用版本号,避免两个调度线程重复选择同一轮计划。 +- 并发失败统一提示“日计划已发生变化,请刷新后重试”。 + +## 错误处理 + +- 日计划不存在时返回业务异常。 +- ERP 数量减少、更新已结束或已取消计划时返回明确原因。 +- 未开始订单不能执行备货、套管、追加和结束作业操作。 +- 已结束订单不能取消、恢复、追加或重新开始。 +- 完成数量不能为负数,也不能超过需求总量。 +- 顺序号和权重必须为正整数。 +- 取消和恢复未填写原因时由参数校验直接拒绝。 +- 非法状态流转返回业务异常,不做静默幂等成功。 +- 请求失败沿用全局错误提示,不在前端吞掉异常。 + +## 验证 + +遵循项目“未经明确要求不新增测试”的规则,本次不创建自动化测试文件,使用以下方式验收: + +- 后端 Maven 编译,验证 Java、Mapper XML 和模块依赖。 +- 前端 TypeScript 类型检查和相关文件 ESLint。 +- SQL 脚本语法、幂等重复执行和菜单层级校验。 +- 本地接口联调 ERP 首次推送、重复推送、数量增加、数量减少和终态拒绝。 +- 人工核对订单、备货、套管的开始、取消、恢复、完成和结束状态流转。 +- 人工核对跨天进行中订单持续出现在作业页面。 +- 人工核对顺序模式与权重轮转模式的列展示和候选计划顺序。 +- 模拟页面操作与定时器同时更新,确认版本冲突不会覆盖完成数量。