shanxia2.0/openspec/changes/pl-stop-cert-management/design.md

设计与决策

跟踪与原型

• 工单：#9 用证管理按段次计量及合同双视角。
• 分支：codex/pl-stop-cert-management。
• Figma v3 总览，状态：用户已确认采用v3。
• 合同详情独立视图：合同证件与额度、运输计划合法使用证明。
• 原型包含五个管理视图、两个合同面板、建档绑定及安排校验，共九个1440px可编辑画面。原型为静态设计，页签跳转、上传与保存尚非可运行功能；交互状态以说明呈现，业务实现后须实际验证。
• 复用现有文件字体及导入的Body样式，局部复用表格单元格、页签、按钮实例；采用Fresh Mint规范色。建档画面说明新增绑定区，实际弹窗仍沿用现有1200px及三列布局，不按原型画布宽度扩大到1440px。
• 当前只提交规格；未修改业务代码、执行SQL或重算历史额度。
• 设计检查：首轮总览截图发现文本过早换行，调整复用组件的文本宽度后，通过Plugin API截图复查九画面布局；298个组件实例、无图片铺底。常规截图接口复查超时，改用节点截图完成。该检查仅针对静态原型，不代表浏览器功能、响应式或交互状态验收。
• 规格检查：openspec validate pl-stop-cert-management --strict通过。用户已回复“采用 v3，继续实现（推荐）”，原型状态更新为已确认；按实施计划进入开发。

用户确认

1. 装货段、每个送货段分别按各自合同及合同产品匹配、校验购买证和运输证。
2. 同张证用于装100、送40、送60，累计200；不得按实物货量去重。购买证与运输证分别200，不将两类证合计为400吨货量。
3. 合法使用证明按每个段次产品分别上传；不做多段批量覆盖。
4. 合同详情“运输计划”后为两个独立Tab：合同证件与额度、运输计划合法使用证明。资料仅汇总当前合同对应段次产品。
5. 用户“好的，请继续”确认继续已讨论方案；此前#8免Figma仅适用于列表修复，新版原型单独确认。
6. 用户在v3确认后补充“界面参考已有的界面样式进行开发”。v3作为功能与信息布局依据，实际视觉复用项目已有组件、同类页面与Fresh Mint规范，不引入独立视觉体系。

现状与复用

pl_purchase_cert/pl_transport_cert继续各维护一个共享额度池；PlContractCertLink/Product继续定义合同产品适用范围，绑定不预占。PlPlanCertUsage仍按计划、证种、证件汇总；PlPlanCertUsageItem已有段次类型、段产品ID、合同产品及分配数量，可复用身份和数量结构。

pl_quota_sources.extract_sources的唯一计量侧与对侧只追溯限制须按计量版本分支；新规则自动提取所有适用装送段产品，所有来源均按各自合同匹配。保留同一段产品跨多张同类证分配、运输证引用配对和按原分配顺序归档规则；不因同SKU或同计划产品合并来源。

计量版本与历史

拟增加显式计量版本 legacy_single_side / per_stop_v2，放在计划用证配置及使用快照中；缺失且已有账目的记录明确视作legacy，不推断为新规则。新安排/无历史占用的草稿使用per_stop_v2。旧记录继续按旧版来源完成释放、结转及纠错，不自动补扣。

存量已安排计划切换新规则必须独立预览旧占用、新占用和差额；确认后在同一事务释放/追加并写审计，任一失败保留原账。首期不自动转换存量，历史只读展示计量口径；后续迁移动作需明确授权。已归档数据不重写。不可用新数据要求让合法的历史归档失去可追溯性。

查询与统计

五Tab共享服务端查询，搜索/排序/筛选在分页前执行。合同和证件列表以主对象分页，展开读取明细，避免全量加载或每行一次统计查询。

• 证件层：核定、当前预占、累计已用、可用=核定-预占-已用、有效期/状态。
• 合同/合同产品层：从使用明细累计本范围reserved_qty/used_qty；证件全局余额必须标注“共享”。不为绑定关系计算虚假的独立余额。
• 段产品层：展示来源计划/实际数量、分配证量、当前预占、已用、校验状态。完整来源快照不可跨证重复累计。
• 计划数按ID去重；购买/运输证分开，异单位分组，不跨单位求和。
• 期初和无合同归属的调整单独列“期初/未归属”，不强制塞入某合同，不能要求可见合同明细之和等于全局总账。
• 合同资料完成数只统计该合同中需要证明的有效段产品；0条显示无需上传，不显示缺失。其他合同资料不计入，权限隐藏部分不能推定为零。

写入与校验

证件建档+多合同适用产品采用一个后端事务入口，复用不提交事务的已有服务。校验全部合同、产品归属、证种和权限后写入；遗漏集合保留，显式空集合按引用保护处理，保留明细ID。不得前端多次调用制造半成功。

正式安排后端重新校验全部需证段产品的合同范围、证件启用/日期/次数/车号/引用关系、分配数量及共享余额，锁定证件并幂等写入；失败整体回滚。前端预览不构成额度授权。调整、取消、归档复用正式业务入口，实际量异常保留真实业务事实及原占用，不伪造用量。

易制毒按现有产品属性规则要求双证；纯易制爆不被强制要求双证。合法使用证明缺失仍不阻断运输安排。

段次合法使用证明

拟新增段产品资料表，唯一身份为tenant_no+plan_id+stop_type+stop_product_id，附件逗号分隔MinIO URL，记录公共字段与软删除。保存须验证段次及产品属于当前计划与租户、未删除、为适用产品，附件授权正常。

每个段产品独立上传与保存；可多附件但不提供一份附件批量应用到多个段的界面。上传/替换/清空保留审计，不能改变运输、额度、归档或库存。计划级旧legal_use_cert_url保留“历史计划级资料”入口，不自动标记各段已上传。段次删除/替换保护资料归属，不能按名称或SKU自动移交资料。

界面

Web Fresh Mint规范、现有运输计划工具栏/漏斗、P02/P06/P10/P12/P15模式。复用ListQuickSearchInput、ListToolbarEndActions、ColumnHeaderFilter、AttachmentUploadField；合同详情两个面板与主模块对应面板共用组件并锁定contractId。

证件建档侧重待核对/未绑定与录入；证件用量侧重总账及合同明细，避免两份台账。新增弹窗沿用1200px、三列、单附件解析、类型与建档方式同行，并增加合同产品绑定区。原型保留老v1/v2，在新容器创建v3，使用合成数据。

验收与限制

覆盖100+40+60=200、购买/运输两类独立、跨合同共享余额、各段跨证分配、实际量顺序结转、并发/幂等/回滚、历史版本、新旧客户端、两合同资料隔离、子数据ID及重复/跨租户拒绝。数据库验证不得连接生产；用户此前不启动MySQL容器的决定继续有效，真实MySQL事务验证单独保留待办。