platforms/docs/项目文档_配送订单合同气瓶显示优化_v1.0.md

项目文档_配送订单合同气瓶显示优化_v1.0

1. 项目概述

本次优化平台总后台创建配送订单时的合同气瓶选择体验。原下拉框使用绑定记录唯一标识作为主文案，业务人员无法直接识别气瓶；同时前端携带的合同筛选参数未被列表接口应用，可能混入其他合同或已经解绑的记录。

2. 业务规则

• 创建订单前必须先选择配送合同。
• 合同气瓶候选仅包含所选合同中尚未解绑的绑定记录。
• 候选按气瓶类型名称、气瓶编码升序排列。
• 支持按气瓶编码和气瓶类型名称搜索。
• 选项显示气瓶类型名称，类型名称缺失时才降级显示唯一标识。
• 多选后完整展示全部已选气瓶标签，方便业务人员逐项核对。
• 切换配送合同时清空已选气瓶，并重新加载当前合同候选。
• 没有候选时提示先为合同绑定气瓶，并禁止提交。
• 合同气瓶管理列表不带合同筛选参数时继续展示完整历史。
• 不新增订单占用规则，不修改数据库结构和现有数据。

3. 接口说明

订单表单继续复用平台接口：

GET /gasorder_contract_product?contract_identity=<配送合同唯一标识>&keyword=<可选搜索词>

传入 contract_identity 时，接口按合同内部主键和 unbound_at IS NULL 精确过滤。未传入时保持原管理列表行为，以兼容历史查询。

4. 核心文件

• backend/api/internal/logic/platform/gasorder/gasorder.go：合同气瓶候选过滤与排序。
• backend/api/internal/logic/platform/gasorder/gasorder_test.go：候选 SQL 规则测试。
• frontend/platform_admin/src/api/resources.ts：业务标签和空状态配置。
• frontend/platform_admin/src/api/resource-display.ts：多字段关系标签组合。
• frontend/platform_admin/src/views/resource/ResourceFieldForm.vue：父级选择顺序提示。
• frontend/platform_admin/scripts/check-gasorder-contract-product-display.mjs：前端专项静态检查。

5. 维护指南

• 不得在订单候选中取消合同和未解绑条件，服务端最终创建校验仍需保留。
• 若未来增加“订单占用气瓶”的排他规则，应先补充业务状态定义，再单独扩展候选和创建校验。
• 新增组合关系标签时优先配置 relationOptionLabelKeys，不要在通用组件中硬编码资源名称。

6. 变更记录

操作时间：2026-08-13

操作类型：修改、扩展

影响模块：平台总后台、气体配送订单、合同气瓶

操作前状态：下拉选项显示绑定记录唯一标识，合同筛选参数未生效，可能出现跨合同或已解绑候选。

具体操作：增加服务端候选过滤与排序，扩展前端气瓶类型名称标签、完整多选展示、搜索提示和空候选引导。

操作后状态：业务人员可通过气瓶类型名称识别候选，订单页面只展示当前合同尚未解绑的气瓶。

风险评估：管理列表不带筛选参数时保持原行为；数据库无变更；订单创建最终校验保持不变。