63 lines
3.5 KiB
Markdown
63 lines
3.5 KiB
Markdown
# 项目文档：配送点订单创建联动 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）：新增配送合同到地址、合同气瓶的安全联动，加入金额预估、空态提示、过期响应保护和提交保护。
|