From 569ac314b14b1cbd5667ebc7e7fa412b700842d7 Mon Sep 17 00:00:00 2001 From: czl231 <3286836406@qq.com> Date: Tue, 18 Aug 2026 23:43:59 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BC=98=E5=8C=96=E6=B0=94=E7=AB=99=E8=AE=A2?= =?UTF-8?q?=E5=8D=95=E5=90=88=E5=90=8C=E6=B0=94=E7=93=B6=E5=80=99=E9=80=89?= =?UTF-8?q?=E9=80=89=E6=8B=A9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- backend/api/internal/logic/gas/gasorder.go | 8 +++ docs/06-气站管理系统需求.md | 1 + .../操作日志_气站订单合同气瓶选择_20260818.md | 43 ++++++++++++++ docs/项目文档_气站订单合同气瓶选择_v1.0.md | 59 +++++++++++++++++++ frontend/gas_admin/src/api/resources.ts | 2 +- 5 files changed, 112 insertions(+), 1 deletion(-) create mode 100644 docs/操作日志_气站订单合同气瓶选择_20260818.md create mode 100644 docs/项目文档_气站订单合同气瓶选择_v1.0.md diff --git a/backend/api/internal/logic/gas/gasorder.go b/backend/api/internal/logic/gas/gasorder.go index b094873..d5da62a 100644 --- a/backend/api/internal/logic/gas/gasorder.go +++ b/backend/api/internal/logic/gas/gasorder.go @@ -206,6 +206,14 @@ func ListGasorderContractProduct(ctx *gin.Context) { if !ok { return } + // 订单候选场景先校验合同属于当前气站，再复用可读名称和有效绑定过滤。 + if contractIdentity := strings.TrimSpace(ctx.Query("contract_identity")); contractIdentity != "" { + if _, ok := scopedContract(ctx, contractIdentity, station.ID); !ok { + return + } + platformgasorder.ListGasorderContractProduct(ctx) + return + } query := common.ActiveRecords(impl.DBService.Model(&models.GasorderContractProduct{})). Joins("JOIN gasorder_contract ON gasorder_contract.id = gasorder_contract_product.gasorder_contract_id"). Where("gasorder_contract.gas_basic_id = ?", station.ID) diff --git a/docs/06-气站管理系统需求.md b/docs/06-气站管理系统需求.md index 923d1a9..aa1955d 100644 --- a/docs/06-气站管理系统需求.md +++ b/docs/06-气站管理系统需求.md @@ -113,6 +113,7 @@ - 气站可基于当前气站生效合同创建订单。 - 服务端强制订单创建方为当前气站，不接受前端伪造创建方。 +- 创建订单时，合同气瓶候选仅显示所选合同尚未解绑的气瓶，并支持按智能气阀名称、设备类型或设备编码搜索；选项使用可读名称，不直接展示系统 UUID。 - 可将订单分配到当前气站配送点及当前气站工作人员。 - 气站端允许动作：分配、开始罐装、待配送、标记异常、恢复、取消。 - 气站端不得执行：开始配送、等待签收、完成订单。 diff --git a/docs/操作日志_气站订单合同气瓶选择_20260818.md b/docs/操作日志_气站订单合同气瓶选择_20260818.md new file mode 100644 index 0000000..7daf0d9 --- /dev/null +++ b/docs/操作日志_气站订单合同气瓶选择_20260818.md @@ -0,0 +1,43 @@ +# 操作日志：气站订单合同气瓶选择 + +操作时间：2026-08-18 +操作类型：修改 +影响模块：气站管理端 5175、气站 API 合同气瓶候选 + +## 操作前状态 + +- 创建订单页将合同气瓶直接显示为 UUID，无法直观区分设备。 +- 气站端字段没有按所选合同联动，后端气站列表也未处理 `contract_identity` 候选筛选。 +- 创建订单页的配送合同和用户地址仍显示技术字段名称，不便于业务人员理解。 + +## 具体操作 + +- 参考 5173 增加合同气瓶的可读标签、搜索提示、空状态和合同联动配置。 +- 气站后端在候选场景先校验合同属于当前气站，再返回当前合同未解绑的气瓶及可读设备信息。 +- 仅将两个字段标题改为“配送合同”和“收货地址”，不复制 5173 的平台级候选、联动或校验规则。 +- 收货地址选项参考 5173 显示实际地址和默认地址标识，不再向业务人员显示 UUID。 + +## 操作后状态 + +- 候选显示“智能气阀名称（设备类型）”，同名时追加设备编码。 +- 支持按名称、类型和编码搜索。 +- 候选严格限制为当前合同的有效绑定，切换合同会清空旧选择。 +- 字段标题使用业务名称；气站端原有合同和地址行为保持不变。 + +## 代码变更 + +- `frontend/gas_admin/src/api/resources.ts`：完善 `gasorder_contract_product_identities` 字段配置。 +- `backend/api/internal/logic/gas/gasorder.go`：增加气站合同范围校验和候选查询分支。 +- `docs/06-气站管理系统需求.md`：补充订单候选展示要求。 + +## 验证结果 + +- `go test ./internal/logic/gas ./internal/logic/platform/gasorder ./internal/routers`：通过。 +- `pnpm type:check`：通过。 +- `pnpm contract:check`：通过，20 个资源。 +- `pnpm build`：通过。 + +## 风险评估 + +- 修改只影响携带 `contract_identity` 的订单候选查询；合同气瓶列表页保持原查询行为。 +- 后端仍执行当前气站合同归属校验，不能通过修改查询参数读取其他气站合同候选。 diff --git a/docs/项目文档_气站订单合同气瓶选择_v1.0.md b/docs/项目文档_气站订单合同气瓶选择_v1.0.md new file mode 100644 index 0000000..8d678fb --- /dev/null +++ b/docs/项目文档_气站订单合同气瓶选择_v1.0.md @@ -0,0 +1,59 @@ +# 项目文档：气站订单合同气瓶选择 v1.0 + +## 1. 项目概述 + +- 项目：物联网智能瓶阀平台气站管理端。 +- 功能：气站创建燃气配送订单时，以可读信息选择当前合同的有效气瓶。 +- 技术栈：Vue 3、TypeScript、Gin、GORM。 +- 运行环境：气站前端 5175、气站 API `/heqi/gas/v1`。 + +本次参考平台总后台 5173 的现有交互，不改变订单、合同气瓶或智能气阀的数据结构。 + +## 2. 目录结构说明 + +```text +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. 切换合同后，已选气瓶被清空并加载新候选。 diff --git a/frontend/gas_admin/src/api/resources.ts b/frontend/gas_admin/src/api/resources.ts index b7cfc6b..7ae3db7 100644 --- a/frontend/gas_admin/src/api/resources.ts +++ b/frontend/gas_admin/src/api/resources.ts @@ -527,7 +527,7 @@ const gasOverrides: ResourceUiDefinition[] = [ ]), define('gasorder_contract_revision', '合同修订记录', 'readonly', []), define('product_info', '合同可选气瓶', 'readonly', []), - define('gasorder_basic', '燃气配送订单', 'append_only', [f('request_no', { required: true }), relation('gasorder_contract_identity', '/gasorder_contract', true), relation('user_address_identity', '/user_address', true), f('gasorder_contract_product_identities', { required: true, type: 'identity-list', relation: '/gasorder_contract_product' }), f('contact_name', { required: true }), f('contact_phone', { required: true }), f('discount_amount'), f('remark')], 'list', [ + define('gasorder_basic', '燃气配送订单', 'append_only', [f('request_no', { required: true }), relation('gasorder_contract_identity', '/gasorder_contract', true, { label: '配送合同' }), relation('user_address_identity', '/user_address', true, { label: '收货地址', listDisplayKey: 'address', relationOptionLabelKey: 'address', relationOptionDefaultKey: 'is_default' }), f('gasorder_contract_product_identities', { label: '合同气瓶', required: true, type: 'identity-list', listDisplayKey: 'contract_products_summary', listDetailLink: true, emptyText: '未填写', relation: '/gasorder_contract_product', placeholder: '请输入智能气阀名称、设备类型或设备编码搜索', relationOptionDisplay: 'product-name-type', relationEmptyText: '该合同暂无可用气瓶，请先为合同绑定气瓶', relationLinkage: { parentKey: 'gasorder_contract_identity', optionParentKey: '', filterKey: 'contract_identity', filterOnly: true, requiresParent: true, parentChangeMessage: '配送合同已变更，请重新选择该合同可用的气瓶' } }), f('contact_name', { required: true }), f('contact_phone', { required: true }), f('discount_amount'), f('remark')], 'list', [ { name: '分配订单', resource: '/gasorder_basic/:identity/assign', fields: [relation('delivery_basic_identity', '/delivery_basic', true), relation('staff_account_identity', '/staff_account', true, { staffRelation: { roles: ['delivery'], enabledOnly: true } }), ...reason], visibleFor: { field: 'order_status', values: [16, 18] } }, { name: '开始罐装', resource: '/gasorder_basic/:identity/filling', fields: reason, visibleFor: { field: 'order_status', values: [18] } }, { name: '待配送', resource: '/gasorder_basic/:identity/ready', fields: reason, visibleFor: { field: 'order_status', values: [19] } },