# 项目文档：配送点订单创建联动 v1.0

## 1. 项目概述

5176 配送点管理端创建订单页按 5173 的安全联动规则展示候选。配送合同是地址和合同气瓶的父级；前端只负责筛选交互和金额预估，后端始终在当前配送点范围内重新校验并计算最终金额。

技术栈：Vue 3、TypeScript、Arco Design、Go、Gin、GORM。

## 2. 目录结构

```text
frontend/delivery_admin/src/
├── api/order-creation.ts                    # 金额预估与前端金额校验
├── api/resources.ts                         # 订单字段和关系联动契约
└── views/resource/
    ├── OrderAmountPreview.vue               # 只读金额预估
    ├── ResourceFieldForm.vue                # 关系空态、禁用和可读候选
    ├── ResourceRecordPage.vue               # 保存保护和页面编排
    └── use-resource-relations.ts            # 父子联动、搜索和版本守卫
backend/api/internal/logic/delivery/
├── order.go                                 # 可履约合同与未解绑合同气瓶候选
├── user.go                                  # 合同签约用户地址候选
└── order_candidate_test.go                  # 候选 SQL 范围测试
```

## 3. 业务规则

- 请求流水号按 5173 保持人工必填，用作唯一幂等追踪字段。
- 合同候选仅包含当前配送点范围内、生效中、已到生效时间、尚未过期且签约用户服务关系仍有效的合同。
- 未选择合同时，收货地址和合同气瓶禁用并提示先选合同。
- 收货地址仅来自合同签约用户，显示完整地址；存在默认地址时自动选择。
- 合同气瓶仅包含所选合同尚未解绑的绑定，显示“智能气阀名称 / 气瓶编码 / 气瓶类型”。
- 切换合同立即清空旧地址和旧气瓶；同一资源仅最新请求可以回写候选。
- 联系人和联系电话继续作为独立、必填、可编辑的订单快照字段，不从地址伪造回填。
- 优惠金额默认 0，不得为负，且必须小于气瓶金额与配送费之和。
- 金额预估公式为：气瓶金额 + 默认配送费 - 优惠金额。最终金额由服务端重新计算。

## 4. 接口兼容与安全

- `/gasorder_contract` 新增可选 `candidate=order` 筛选；不传参数时合同管理列表保持原行为。
- `/user_address` 新增可选 `gasorder_contract_identity` 筛选；后端先确认合同属于当前配送点，再限定合同用户。
- `/gasorder_contract_product` 新增可选 `contract_identity` 筛选；后端先确认合同属于当前配送点，再限定未解绑绑定。
- 原路径、原响应字段和创建订单请求协议保持兼容；候选接口只新增可选参数和只读展示名称。
- 前端候选不可作为授权依据，创建接口继续校验合同、地址、气瓶、创建方和金额。

## 5. 维护与验证

新增联动字段时必须声明父字段、服务端筛选键、空态文案和切换提示。禁止仅在浏览器中过滤全量候选。关系请求必须保留版本守卫，保存期间冻结表单并显式防重入。

验证命令：

```text
go test ./api/internal/logic/delivery ./api/internal/logic/platform/gasorder
npm.cmd run type:check
npm.cmd run resource-pages:check
npm.cmd run contract:check
npm.cmd run build
```

## 6. 变更记录

- v1.0（2026-08-23）：新增配送合同到地址、合同气瓶的安全联动，加入金额预估、空态提示、过期响应保护和提交保护。