docs(pl): define per-stop certificate management and contract tabs

2026-11-01 20:38:26 +08:00
1 parent 4dbd48d827
commit 3a3cafc2c5
@@ -0,0 +1,68 @@
+# 设计与决策
+
+## 跟踪与原型
+
+- 工单：[#9 用证管理按段次计量及合同双视角](https://gitea.aichengyan.com/cykj/shanxia2.0/issues/9)。
+- 分支：`codex/pl-stop-cert-management`。
+- [Figma v3 总览](https://www.figma.com/design/ImDcikQnCX5GiJQLwUHwDC/shanxia2.0?node-id=26-3)，状态：待用户确认。
+- 合同详情独立视图：[合同证件与额度](https://www.figma.com/design/ImDcikQnCX5GiJQLwUHwDC/shanxia2.0?node-id=26-445)、[运输计划合法使用证明](https://www.figma.com/design/ImDcikQnCX5GiJQLwUHwDC/shanxia2.0?node-id=26-513)。
+- 原型包含五个管理视图、两个合同面板、建档绑定及安排校验，共九个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仅适用于列表修复，新版原型单独确认。
+
+## 现状与复用
+
+`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事务验证单独保留待办。
@@ -0,0 +1,23 @@
+# 用证管理按段次计量及合同双视角
+
+## Why
+
+用户于2026-11-01确认五个管理Tab及合同详情两个独立Tab。当前代码具备证件共享余额、合同产品适用范围、事务化安排预占，但只选择唯一装送计量侧，合法使用证明挂在计划产品上，不能满足各装送段分别校验、分别占用、分别上传的需求。
+
+## What Changes
+
+- Web用证管理增加证件建档、合同用证、证件用量、计划段次用证、合法使用证明五个视图。
+- 新增证件可在同一次保存中关联合同和合同产品；解析仍仅提供候选字段。
+- 合同详情在运输计划后依次增加“合同证件与额度”“运输计划合法使用证明”，两个独立Tab。
+- **BREAKING** 新规则按各段次产品独立用证：同证装货100吨、送货40吨及60吨，累计预占200吨。替代旧工单#4的装送去重要求；两类证各自核算。
+- 合法使用证明按每个段次产品分别上传，不提供一次上传批量覆盖多个段次的操作。
+- 现有已安排/已归档账目不自动重算；旧账使用版本化兼容处理。
+
+## Capabilities
+
+### New Capabilities
+- `stop-cert-management`: 五视图、合同双Tab、各段独立计量、段次产品资料及历史兼容。
+
+## Impact
+
+Web管理端、共享后端、MySQL5.7迁移脚本及对应API/schema；H5/小程序调用兼容纳入验证，本轮不新增其五Tab界面。保留租户/数据权限、差量保存、幂等及额度事务。默认Agent测试；不执行生产迁移、部署或自动关闭既有工单。本阶段交付OpenSpec与可编辑原型，业务实现待新版原型确认。
@@ -0,0 +1,51 @@
+## ADDED Requirements
+
+### Requirement: 五视图与合同双Tab
+系统 SHALL 提供证件建档、合同用证、证件用量、计划段次用证、合法使用证明五个管理视图；合同详情 SHALL 在运输计划之后依次提供合同证件与额度、运输计划合法使用证明两个独立Tab。
+
+#### Scenario: 从合同查看用证和资料
+- **WHEN** 用户打开合同详情
+- **THEN** 两个独立Tab分别展示该合同证件统计/绑定维护和该合同相关段产品资料，不混入其他合同统计。
+
+### Requirement: 各装送段独立匹配与计量
+新规则 SHALL 以每个适用段次产品为独立来源，按各自合同产品匹配购买证、运输证；同证不同段量 SHALL 累计，不做装送去重；两类证 SHALL 独立核算。
+
+#### Scenario: 一装两送使用同一张证
+- **WHEN** 装货100吨、送货40吨和60吨，各段选用同一张购买证与同一张运输证且条件满足
+- **THEN** 购买证预占200吨、运输证预占200吨；任一证余额不足则安排失败且原账不变。
+
+#### Scenario: 各段属于不同合同
+- **WHEN** 装货段属于合同A、送货段属于合同B
+- **THEN** 分别校验A与B的合同产品适用范围，A的可用绑定不能替代B缺失的绑定。
+
+### Requirement: 统一共享余额与范围统计
+系统 SHALL 从同一份账本和使用明细产生统计，区分全证共享余额与本合同/产品预占和已用量，不跨单位或跨证种求和。
+
+#### Scenario: 多合同共用证件
+- **WHEN** 核定300吨，本合同预占100吨，其他合同预占80吨，累计已用20吨
+- **THEN** 全证共享余额为100吨，本合同预占为100吨，绑定本身不扣量。
+
+### Requirement: 建档与合同产品绑定原子保存
+系统 SHALL 在同一事务保存证件和本次提交的多合同产品适用范围，完整执行归属、权限及引用校验，差量更新已有明细。
+
+#### Scenario: 任一合同产品无效
+- **WHEN** 建档同时绑定多个合同，其中一个产品不属于对应合同
+- **THEN** 全部保存失败，不留下新证件或部分成功关联。
+
+### Requirement: 段次产品独立资料
+合法使用证明 SHALL 按每个适用段次产品分别上传、查看和统计，保留MinIO附件和审计；资料操作 SHALL 不改变额度、运输或库存。
+
+#### Scenario: 多送货段仅一段上传
+- **WHEN** 一个计划有两个需要证明的送货段产品，仅第一段已上传
+- **THEN** 第一段已上传、第二段未上传，总计1/2；不能从计划产品的附件推断第二段齐全。
+
+#### Scenario: 资料缺失仍可安排
+- **WHEN** 所有需证段产品的两证满足，但合法使用证明未上传
+- **THEN** 安排不因资料缺失受阻，资料界面继续显示待补。
+
+### Requirement: 历史计量与附件保护
+系统 SHALL 保留旧计划的原计量口径和账目，新规则不得自动重算旧账；旧计划级附件 SHALL 独立保留且不得自动计作各段已上传。
+
+#### Scenario: 旧计划已按唯一侧占用100吨
+- **WHEN** 系统升级到各段独立计量
+- **THEN** 旧占用仍为100吨并标识原口径，不自动增加到200吨；后续合法历史释放和结转仍可追溯。
@@ -0,0 +1,26 @@
+## 1. 规格与原型
+- [x] 核对现有实现与用户决定，明确各段分别累计、资料分别上传、合同详情两个独立Tab。
+- [x] 建立proposal/design/specs并记录历史兼容、统计和权限边界。
+- [x] 关联独立工单#9，制作并检查可编辑Figma v3（九个静态画面）。
+- [ ] 用户确认具体新版原型后开始依赖它的业务界面实现。
+
+## 2. 后端与迁移
+- [ ] 先写新规则100+40+60=200及旧版100不变的失败回归，再扩展版本化来源提取及分配入口。
+- [ ] 实现合同/证件统计查询及主对象分页，验证单位、证种、权限与期初未归属口径。
+- [ ] 实现证件+合同产品原子保存，覆盖多合同失败回滚、遗漏/空集合、身份及引用保护。
+- [ ] 新增段产品资料模型/schema/API与MySQL5.7迁移，保留旧附件和旧账；不自动执行数据库迁移。
+- [ ] 校验安排、调整、释放、归档、异常补量及旧客户端不能绕过正式规则。
+
+## 3. Web界面
+- [ ] 实现五Tab容器及共用合同、证件、段次明细组件。
+- [ ] 建档增加合同产品绑定，保留单附件解析和人工核对。
+- [ ] 合同详情增加两个独立Tab，固定当前合同并复用主模块面板。
+- [ ] 安排显示逐段预检与定位异常；资料按段产品独立上传。
+
+## 4. 验证交付
+- [ ] 后端专项和前端行为回归，H5/小程序共享API兼容检查。
+- [ ] 合成数据浏览器交互、主要尺寸及加载/失败/保存状态视觉核对。
+- [ ] 独立审查、适用数据库事务验证及迁移演练（此前用户要求暂不启MySQL容器，未完成项如实保留）。
+- [ ] 记录最终版本、实际测试与缺口，再按已有授权交付；不自动部署或关闭旧工单。
+
+当前状态：规格与原型阶段。尚未修改业务代码、创建数据库表或执行迁移；不得标记实现/测试完成。