diff --git a/openspec/changes/pl-stop-cert-management/design.md b/openspec/changes/pl-stop-cert-management/design.md new file mode 100644 index 000000000..571d0e27a --- /dev/null +++ b/openspec/changes/pl-stop-cert-management/design.md @@ -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事务验证单独保留待办。 diff --git a/openspec/changes/pl-stop-cert-management/proposal.md b/openspec/changes/pl-stop-cert-management/proposal.md new file mode 100644 index 000000000..b364014c3 --- /dev/null +++ b/openspec/changes/pl-stop-cert-management/proposal.md @@ -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与可编辑原型,业务实现待新版原型确认。 diff --git a/openspec/changes/pl-stop-cert-management/specs/stop-cert-management/spec.md b/openspec/changes/pl-stop-cert-management/specs/stop-cert-management/spec.md new file mode 100644 index 000000000..aa974d198 --- /dev/null +++ b/openspec/changes/pl-stop-cert-management/specs/stop-cert-management/spec.md @@ -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吨;后续合法历史释放和结转仍可追溯。 diff --git a/openspec/changes/pl-stop-cert-management/tasks.md b/openspec/changes/pl-stop-cert-management/tasks.md new file mode 100644 index 000000000..869de3dce --- /dev/null +++ b/openspec/changes/pl-stop-cert-management/tasks.md @@ -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容器,未完成项如实保留)。 +- [ ] 记录最终版本、实际测试与缺口,再按已有授权交付;不自动部署或关闭旧工单。 + +当前状态:规格与原型阶段。尚未修改业务代码、创建数据库表或执行迁移;不得标记实现/测试完成。