# 项目文档_配送订单收货地址联动_v1.0

## 1. 项目概述

本次变更优化平台总后台创建配送订单时的收货地址选择。原页面将用户地址退化显示为 UUID，且候选范围未按配送合同用户收敛，管理员难以识别并可能误选其他用户地址。

## 2. 核心规则

- 必须先选择配送合同，再选择收货地址。
- 收货地址仅来源于配送合同签约用户。
- 下拉选项显示完整地址，默认地址追加“默认地址”标记。
- 候选中存在默认地址时自动选中，管理员仍可更换。
- 切换配送合同时同时清空原收货地址和原合同气瓶，并重新加载候选。
- 合同用户没有可用地址时，页面明确提示先维护用户地址并禁止保存。
- 服务端创建订单时继续校验地址确实属于合同用户，前端联动不替代服务端鉴权。

## 3. 目录与文件职责

```text
frontend/platform_admin/
├── src/api/resources.ts                         # 配送订单字段与联动配置
├── src/api/resource-display.ts                  # 地址选项和默认标记展示
├── src/views/resource/ResourceFieldForm.vue     # 联动下拉禁用及空数据引导
├── src/views/resource/ResourceRecordPage.vue    # 空候选时阻止保存
└── src/views/resource/use-resource-relation-linkage.ts # 多组父子联动协调
backend/api/internal/logic/platform/user/
├── relation.go                                  # 按配送合同过滤用户地址
└── relation_test.go                             # 合同地址过滤回归测试
```

## 4. 变更记录

操作时间：2026-08-13

操作类型：扩展

影响模块：平台总后台配送订单、平台用户地址查询

操作前状态：地址下拉显示 UUID，并加载未按合同用户过滤的地址候选。

具体操作：增加合同地址精确过滤；扩展标准资源表单为多子项联动；增加地址业务文案、默认地址自动选择、合同切换清空及空数据阻断。

操作后状态：管理员可识别并且只能选择当前合同用户的地址；无地址时不能提交无效订单。

数据库变更：无。

## 5. 兼容性与风险

- `/user_address` 不携带 `gasorder_contract_identity` 时保持原有地址管理列表行为。
- 新筛选参数仅收窄订单创建页候选范围，不改变地址数据和订单写入协议。
- 多联动扩展保留原配送点、工作人员和合同气瓶联动规则。
- 地址属于敏感数据，完整地址仍只通过已鉴权的平台用户地址接口返回，不扩展到其他终端。

## 6. 验证方式

```bash
cd backend/api
go test ./internal/logic/platform/user

cd frontend/platform_admin
npm run gasorder-address:check
npm run type:check
npm run lint
npm run contract:check
npm run build
```