# 用户地址受控展示项目文档 v1.0

## 1. 项目概述

- 项目名称：平台总后台用户地址受控展示。
- 实施范围：平台 API 的 `user_address` 资源，以及端口 5173 的平台总后台列表、详情和编辑页。
- 主要功能：向已通过平台后台鉴权和用户地址菜单权限校验的管理员展示真实地址、经度和纬度；空值明确显示“未填写”。
- 技术栈：Go、Gin、GORM、Vue 3、TypeScript、Arco Design。
- 运行环境：后端 API 与 `frontend/platform_admin` 本地开发环境。

## 2. 目录结构

```text
platforms/
├── backend/api/internal/logic/platform/user/
│   ├── relation.go                 # 用户地址列表、详情及受控位置字段恢复
│   └── relation_test.go            # 地址与坐标恢复回归测试
├── frontend/platform_admin/src/
│   ├── api/resources.ts            # 用户地址字段展示规则
│   ├── api/resource-display.ts     # 六位小数展示格式
│   └── views/resource/
│       └── ResourceFieldForm.vue   # 表单字段占位文本
└── docs/
    └── 11-数据接口与安全.md         # 用户地址资源级安全例外
```

## 3. 核心文件说明

### 3.1 后端用户地址逻辑

`backend/api/internal/logic/platform/user/relation.go` 继续先执行通用敏感字段保护，再仅在 `user_address` 的受控列表和详情响应中恢复当前查询记录的地址、经度和纬度。创建、更新、归档、默认地址事务以及公共路由均保持不变。

### 3.2 前端展示规则

- 列表复用共享表格的单行省略和悬停全文能力。
- 地址、经度、纬度为空时显示“未填写”。
- 经度和纬度在列表、详情中统一保留六位小数。
- 编辑页从详情接口回填真实字段；空字段使用“未填写”占位文本，不伪造数据。

## 4. 安全与兼容性

- 资源例外只作用于平台总后台 `/user_address` 列表和详情。
- 请求仍必须通过平台 JWT、角色、菜单及资源权限中间件。
- 用户端、工作人员端、气站端、配送点端及其他平台资源继续沿用原脱敏规则。
- 不修改数据库结构，不补充历史数据，不改变公开请求字段或返回字段名称。

## 5. 变更记录

- 新增用户地址受控位置字段恢复。
- 新增空值文案和坐标六位小数展示。
- 同步安全基线和回归测试。

## 6. 维护指南

- 新增其他敏感字段展示例外时，不得修改全局脱敏字段表，应采用资源级恢复并补充权限、测试和安全文档。
- 后端验证执行 `go test ./internal/logic/platform/user ./internal/logic/common`。
- 前端验证执行 `pnpm type:check`、`pnpm lint`、`pnpm contract:check` 和 `pnpm build`。