16 KiB
段次用证与合同双视角实施计划
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: 实现已确认v3的五视图、合同双Tab、装送各段累计额度与逐段产品证明。
Architecture: 延续证件共享余额和现有使用明细账,以服务端确定的计量版本选择旧单侧或新全段来源。新增独立段产品资料与分页查询,合同详情复用管理页组件,保存和安排仍由单事务入口处理。
Tech Stack: Python 3.9/FastAPI/SQLAlchemy/Pydantic v2、MySQL 5.7、Vue 3/Element Plus、pytest、pnpm。
已确认边界与执行顺序
用户已明确“采用v3,继续实现”。分支codex/pl-stop-cert-management,集成目标V3.0。使用现有隔离worktree,不触碰主目录未提交文件。先后端计量,再资料及统计,再Web;任务间规格审查后质量审查。Agent执行合成数据测试;不启动MySQL容器,不连接业务库验证、不执行SQL、不部署。主目录项目配置允许任务分支推送/工单回写,不允许合并。本任务不扩大手机UI范围,但共享API保持兼容。
界面依据用户补充沿用已有样式:列表采用P02,参考web-admin/src/views/pl/plan-quota/index.vue和web-admin/src/views/demo/order/index.vue;合同详情沿用P10及ContractDetailDialog.vue;建档沿用P12及现有web-admin/src/views/pl/quota-cert/index.vue。复用统一路由页签、搜索、漏斗、工具栏和附件组件。v3确定功能与信息组织,Fresh Mint与现有组件确定视觉。
本机运行来源只读核对:3006端口进程cwd为主目录/Users/zlwu/work/00code/shanxia2.0/web-admin,8000端口为同主目录backend,不是任务worktree。任务Web依赖软链到主目录node_modules,dist为任务目录独立实体目录;构建不安装或清理共享依赖,使用pnpm --config.verify-deps-before-run=false。浏览器验收必须加载任务产物并以合成API响应隔离,不把现有主目录服务视为任务版验证。
Task 1: 服务器决定计量版本及各段独立来源
Files: backend/app/services/pl_quota_sources.py、pl_quota_planning.py、pl_quota_business.py、pl_quota_usage_service.py;backend/app/schemas/pl/quota_planning.py;backend/tests/test_pl_quota_sources.py、test_pl_quota_planning.py、test_pl_quota_business.py。
- 增加失败用例,复用现有SQLite合成fixture,将装货100、两送40/60分别关联不同合同产品,断言新来源三条且合计200;实际量独立取每段。保留显式legacy测试。
assert sum(source.quantity for source in sources) == Decimal('200') assert {source.source_id for source in sources} == {'load:lp', 'delivery:dp', 'delivery:dp2'} assert {source.contract_id for source in sources} == {'purchase', 'sale', 'sale2'} - 用主目录虚拟环境从本worktree的backend运行
python -m pytest tests/test_pl_quota_sources.py tests/test_pl_quota_planning.py -q,记录预期失败。 - 来源增加
measurement_version选择;旧版本维持原算法,新版按所有易制毒段产品创建来源,不依赖客户端挑选计量侧。缺少段产品或合同身份拒绝;来源指纹含新版标识,legacy指纹不改变。配置接受measurementVersion用于显示,但服务端根据已持有账目/安排归档状态决定版本,拒绝客户端降级/切换;历史已产生账目缺版本视为legacy,新草稿/新安排固定per_stop_v2。新版本忽略旧客户端对侧配对选择,不允许借它少扣。 - 正式reserve/resize把服务端版本写回配置/账本快照;settle/release保持旧版可追溯,避免旧计划升级加扣。预览和正式提交共用版本决策。get返回版本及来源主体、段序、合同、产品。
- 运行来源、planning、business、usage、allocation、supplement相关pytest;验证旧单侧100、新版200、跨合同匹配、不可降级、0实际量和缺失实际量。提交本任务。
Task 1证据:提交cde30287f;实施者298项回归通过,独立规格审查320项通过并验证跨合同新200/旧100,独立质量审查104项通过。均为SQLite合成测试;未执行MySQL并发验证。
Task 2: 段产品证明与合同范围分页
Files: 新增backend/app/services/pl_stop_legal_document.py、backend/tests/test_pl_stop_legal_document.py;修改backend/app/models/pl_quota_models.py、backend/app/schemas/pl/legal_use_document.py、backend/app/api/pl/quota_cert.py;新增docs/sql/2026-11-01-pl-stop-legal-document.sql。
- 写合成用例:一装两送只传第二段,结果1/3;按第二段合同查询为1/1;另租户、另合同、重复段身份拒绝;遗漏集合不变、空附件清空单行、旧计划附件不会标记新段完成。运行看到缺失功能失败。
- 新表
pl_stop_legal_document使用完整公共字段、软删除、唯一tenant_no/plan_id/stop_type/stop_product_id;增加MySQL5.7可执行建表脚本,不自动执行。以有效计划/父段/段产品/计划产品联查判定易制爆适用范围;合同权限和计划权限均过滤。保存按稳定段产品身份差量更新,全部校验后写入;上传权限和MinIO新附件授权沿用旧逻辑;删除段产品下游引用保护包含新资料。 - 独立新API避免旧端混淆:
GET /transport/legal-use-documents/stops分页{list,total,page,pageSize};GET/PATCH /stops/{plan_id}获取/保存。查询contractId限定当前合同;PATCH载荷{items:[{stopType,stopProductId,legalUseCertUrl}]},不得批量套用同一附件。{"id":"plan", "planNo":"PL001", "uploadedCount":1,"requiredCount":3, "items":[{"stopType":"delivery","stopProductId":"dp","productName":"双氧水","contractId":"sale","contractNo":"XS001","legalUseCertUrl":"","documentStatus":"pending"}], "legacyProducts":[]} - 保留旧计划级端点和旧附件查看,清楚标为历史;回归旧端点测试,运行新权限/保存/统计测试。提交本任务。
Task 2证据:提交2dd396509与并发当前读修复b21618151;核心10模块159项通过,新证明20项经独立复审通过。规格、质量审查通过。SQL仅编写未执行;MySQL锁SQL编译测试不等同真实并发验证。扩展检查中既有test_pl_mobile_stop_meta.py两项失败(历史SQL路径不存在、AST测试替身缺少assert_plan_can_arrange),未扩大修改。
Task 3A: 建档原子绑定
Files: 新增backend/app/services/pl_quota_cert_bindings.py和对应tests;修改backend/app/api/pl/quota_cert.py,按需扩展已有schemas及将已有证件/范围保存分为校验准备与应用。
实施者反馈统计和原子绑定合并任务上下文过大,拆为3A、3B顺序实施,各自完成规格及质量审查后进入下一项;不并行改共享服务和路由。
- 写失败用例:第二合同非法不修改证面或第一合同,原有链接及产品ID保持、其他证件不被移除;遗漏/空集合、重复/跨租户/跨父ID、引用和隐藏范围保护。
- 在证件save payload增加可选
contractBindings:[{contractId,products:[{id?,contractProductId,scopeStatus?}],id?,linkStatus?}],get返回同字段。遗漏不修改,空集合申请清空并执行引用保护;不允许隐藏范围被静默删除。主证、购买证引用与合同绑定同事务,完整校验先于写入,维护其他证件关系和原ID,失败不commit。 - 锁顺序为所有受影响证件按证种/ID排序,再按ID锁合同及关系。等待后当前读校验范围,遇新增未锁证件返回409,不能持合同锁倒序补证锁。新增证先分配稳定ID供验证,全部准备通过后再写入。
- 运行原子保存、contract_scope、cert_archive、api回归及锁SQL意图测试,保留无bindings旧行为。提交并审查。
Task 3A证据:提交71116ed69与保存响应当前读修复5912e9d05;独立规格、质量审查通过,相关79项SQLite测试通过。GET返回contractBindings及bindingsEditable,不可编辑时客户端省略绑定集合可单独改证面。真实MySQL并发未验证。
Task 3B: 合同与证件统计
Files: 新增backend/app/services/pl_quota_statistics.py及tests;修改backend/app/api/pl/quota_cert.py。
- 写失败用例:核定300、两合同预占100/80、已用20得到共享100;无权合同/计划不出现在明细或合同聚合;两证和不同单位不合并;分页按合同/证件而非明细。
- API固定为
GET /statistics/contracts、GET /statistics/certificates返回分页主对象,GET /contracts/{id}/statistics返回合同及certificates,每证certType/certId/certNo/productNames/quantityUnit/totalQty/reservedQty/usedQty/availableQty/contractReservedQty/contractUsedQty/products;GET /{kind}/{id}/statistics返回证件及contracts及当前权限内usageItems。查询当前租户、软删除、CRM和PL范围;余额为授权可见证的全局缓存,合同使用聚合只取授权计划,不泄漏不可见合同明细。 - 期初/未归属取独立无计划流水,不从全局余额与可见明细的差额推导。主对象先过滤分页,当前页批量取数,Decimal通过_wire序列化为字符串。
- 运行统计/分页/权限、contract_scope、cert_archive、api回归。提交并审查。
Task 3B证据:提交f9c206c91,相关78项SQLite回归通过;独立规格、质量审查均通过,各自统计/API 24项验证通过。实际MySQL执行性能未验证。
后端组合验证(Web实施前):主目录venv在任务backend执行python -m pytest tests/test_pl_quota*.py tests/test_pl_legal_use_document.py tests/test_pl_stop_legal_document.py tests/test_pl_child_differential_save.py -q,505 passed / 14既有警告,17.05秒。所有数据为SQLite合成fixture、识别请求已mock,无外部业务数据库调用;日志.local/agent/stop-cert-v3/backend-combined.log。
Task 4: 五Tab容器和复用统计面板
Files: web-admin/src/api/pl/quota-cert.ts;新web-admin/src/views/pl/contract-quota/index.vue、web-admin/src/views/pl/certificate-usage/index.vue和复用统计面板;修改router和ContractDetailDialog.vue。
- 增加API类型和请求方法与Task2/3一致,分页保留数值字符串。用组件行为测试覆盖Tab切换正确视图、合同固定id、切换合同清空旧响应、统计不相加共享余额。
- 沿用现有ArtGroupLeafTabs路由组扩为五个叶子,避免再嵌套第二层Tab;静态路由和数据库菜单迁移同步维护。仅有合法证明菜单权限时不请求额度API。旧Web菜单URL保留,移动路由保持原组件;复用已有建档/计划组件,面板嵌入合同详情时补
embedded支持避免双标题/双padding。const tabPaths = ['quota-cert', 'contract-quota', 'certificate-usage', 'plan-cert', 'legal-use-document'] as const - 统计面板使用ListQuickSearchInput/ListToolbarEndActions/ColumnHeaderFilter、服务端分页、展开按需取明细。合同面板prop
contractId?: string固定范围,复用ContractScopeDialog维护绑定;证件面板按证种展示全局数量和各合同明细,展开段产品用量。 - 合同详情运输计划后插入“合同证件与额度”lazy Tab,按菜单权限显示,挂载ContractQuotaPanel并固定contractId,切换合同销毁旧状态。“运输计划合法使用证明”Tab随Task 6组件一起接入,避免引用尚不存在的组件。
- 定向tsx/node:test及类型检查(区分历史错误);提交。
Task 4证据:0d1d264bc及后续修复至bd90d2099;规格和质量审查通过,相关前端43项通过,最后局部23项通过,类型检查499→499无新增。统计字段/筛选增量后端30项通过。任务pnpm build成功(39.12秒),构建产物在无HTTP服务的Playwright路由中加载,API全部合成拦截;两页加载/展开/第二页/组合筛选通过,unknown请求与pageerror均0,截图已查看。复核并修复默认Boolean wrapper、分页归零、权限初始化、重开弹窗响应和展开区宽度边界。浏览器脚本与截图在.local/agent/stop-cert-v3/;全流程最终验收仍在Task 6。
Task 5A: 建档合同产品绑定
Files: web-admin/src/views/pl/quota-cert/index.vue、model.ts及绑定编辑子组件、相关tests。
实施者反馈Task 5涵盖三个大型界面,拆为5A/5B顺序实施并各自双审,功能范围不变。
- 行为测试覆盖多合同产品选择后一次save、保存失败保留输入、单附件解析、编辑ID/status/备注往返和异步生命周期。
- 建档表单在1200px三列现有区后增加合同产品绑定编辑,加载编辑已有绑定,不由客户端多请求分步保存。建档方式/类型同行,绿色分组竖条保持。bindingsEditable=false时只读绑定并省略集合保存证面。
- 定向tsx/node:test与类型检查无新增,提交、自查并完成规格和质量审查。
Task 5A证据:136a85dda及eb4a34cd5;独立规格、质量审查通过,修复同合同产品请求反序覆盖及移除重加旧响应,并支持失败重试。相关前端42项通过,最后表单/模型20项复审通过;类型499→499无新增。任务构建39.42秒成功;合成API浏览器验证最新GET编辑、单次PUT保留关系/产品ID、建档选择合同产品一次POST,页面错误/未知请求均0,1200px三列及绑定区截图已查看。脚本browser-cert-form.mjs与日志/截图保留在.local/agent/stop-cert-v3/;最终产物验证在Task 6再次覆盖。
Task 5B: 段次列表与新版用证配置
Files: web-admin/src/views/pl/plan-quota/index.vue、web-admin/src/components/business/pl-plan-quota-dialog/index.vue及model/test;必要时扩展backend/app/services/pl_quota_planning.py只读段明细返回及对应测试。
- 新版配置展示所有装送易制毒段产品、合同/单位/需用量;隐藏唯一侧选择,不提交旧配对。保留legacy配置用于旧计划。计划页展开get_plan_quota,列出各段绑定证件及预占/已用,标注缺配、无需两证、原口径。
- 段次展示须包含无需双证的段产品;当前sourceOptions仅含易制毒,必要时在同一用证详情API新增只读stopProducts,保留sourceOptions计量语义,避免为展示依赖权限不同的计划编辑API。
- 安排沿用后端原子校验和双证预检,缺证明不阻断;拒绝返回定位段产品。实际库存、法定证明、两证状态互不替代。
- TDD覆盖新版全段/旧版配对、异步预览失效、段次展开与独立证量、无需两证产品,以及已有H5/小程序共享配置测试,修正兼容而不新增手机五Tab。类型检查无新增,提交并双审。
Task 6: 段次证明Web与最终验证
Files: 新web-admin/src/views/pl/legal-use-document/StopDocuments.vue;API types;合同详情及五Tab挂载;相关node:test。
- 测试合同范围上传1/1、全局1/3、逐段附件操作、上传中禁止保存、失败保留输入、切租户/合同丢弃过时响应。
- 使用服务端分页和状态过滤,展开计划显示每个装送段产品及附件;每行单独上传/保存,上传控件与MinIO沿用AttachmentUploadField。历史计划级附件单独只读,不能当作段已上传。
- 合同详情在“合同证件与额度”后接入独立“运输计划合法使用证明”lazy Tab,按证明菜单权限显示并固定当前contractId;五视图中的合法使用证明路由同时切换到共用StopDocuments组件。
- 使用主目录venv运行受影响后端pytest;Web运行定向tsx/node:test、pnpm build与类型检查,已知历史错误单列;共享手机API测试。审查固定base/head,规格合格后质量审查;修复所有阻塞。
- 在允许的本地测试环境以合成响应验证页面/弹窗及合同切换、加载失败、保存状态;未获服务启动授权则使用不启动业务后端的组件浏览器测试,缺口如实记录。MySQL真实事务验证保留未执行,不以SQLite冒充。
- 更新OpenSpec/tasks、SQL执行指引、工单和提交证据,按已授权推送任务分支,保持工单开放至验收;不自动合并或执行SQL。