# 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 首次推送、重复推送、数量增加、数量减少和终态拒绝。 - 人工核对订单、备货、套管的开始、取消、恢复、完成和结束状态流转。 - 人工核对跨天进行中订单持续出现在作业页面。 - 人工核对顺序模式与权重轮转模式的列展示和候选计划顺序。 - 模拟页面操作与定时器同时更新，确认版本冲突不会覆盖完成数量。