platforms/docs/项目文档_气站订单合同气瓶选择_v1.0.md

项目文档：气站订单合同气瓶选择 v1.0

1. 项目概述

• 项目：物联网智能瓶阀平台气站管理端。
• 功能：气站创建燃气配送订单时，以可读信息选择当前合同的有效气瓶。
• 技术栈：Vue 3、TypeScript、Gin、GORM。
• 运行环境：气站前端 5175、气站 API /heqi/gas/v1。

本次参考平台总后台 5173 的现有交互，不改变订单、合同气瓶或智能气阀的数据结构。

2. 目录结构说明

platforms/
├── frontend/gas_admin/src/api/resources.ts  # 合同气瓶选择字段及联动配置
├── backend/api/internal/logic/gas/
│   └── gasorder.go                          # 气站合同范围校验和候选查询转发
└── docs/
    └── 06-气站管理系统需求.md               # 订单候选展示验收口径

3. 核心文件说明

frontend/gas_admin/src/api/resources.ts

• 将字段名称由“合同气瓶唯一标识”改为“合同气瓶”。
• 候选显示智能气阀名称和类型；同名同类型时追加设备编码。
• 支持按名称、类型和编码搜索。
• 配送合同变化后清空旧选择，并重新加载新合同的候选气瓶。
• 创建订单页仅在展示层将技术字段标题改为“配送合同”和“收货地址”，不改变气站端原有候选、联动或校验规则。
• 收货地址选择项显示实际地址；默认地址追加“默认地址”标识，提交值仍为地址 identity。

backend/api/internal/logic/gas/gasorder.go

• 接收 contract_identity 筛选参数时，先验证合同属于当前气站。
• 校验通过后复用既有候选查询，只返回该合同尚未解绑的气瓶。
• 未携带筛选参数的合同气瓶列表继续保持原有气站范围查询。

4. 变更记录

• 修复 5175 创建订单时合同气瓶选项直接显示 UUID 的问题。
• 修复气站候选接口忽略当前合同筛选、可能混入其他合同绑定的问题。
• 优化创建订单页字段标题：“配送合同唯一标识”改为“配送合同”，“用户地址唯一标识”改为“收货地址”。
• 未修改数据库、公共模型、合同绑定规则或订单创建接口。

5. 维护指南

• 合同气瓶候选必须同时满足当前气站、当前合同和未解绑三个条件。
• 前端不得仅依靠选项隐藏保证范围，后端必须保留合同归属校验。
• 调整候选展示字段时，应同步验证名称为空、名称重复和编码为空的降级显示。

6. 验收方式

1. 选择配送合同前，合同气瓶字段不可选择。
2. 选择合同后，只出现该合同尚未解绑的气瓶。
3. 候选优先显示“名称（类型）”，重名时追加编码。
4. 输入名称、类型或编码均可搜索。
5. 切换合同后，已选气瓶被清空并加载新候选。