# 用户地址受控展示操作日志

操作时间：2026-08-11

操作类型：扩展

影响模块：平台总后台用户地址列表、详情、编辑页及平台 API

## 操作前状态

用户地址已写入数据库，但通用敏感字段投影会从列表与详情响应中删除地址和经纬度。端口 5173 的列表显示 `-`，详情与编辑页也无法读取已保存的位置字段。

## 具体操作

1. 保留全局敏感字段保护规则。
2. 在已受平台 JWT、角色和菜单权限保护的 `user_address` 列表与详情接口中恢复当前记录的地址和坐标。
3. 列表地址沿用单行省略和悬停全文；空字段显示“未填写”。
4. 列表与详情中的经纬度统一显示六位小数。
5. 新增列表、详情及空位置字段回归测试，并同步安全与项目文档。

## 操作后状态

端口 5173 的用户地址列表、详情和编辑页能够读取数据库中真实保存的地址及坐标。历史空数据不补充、不伪造，页面明确显示“未填写”。

## 代码变更

- `backend/api/internal/logic/platform/user/relation.go`：新增受控列表、详情与位置字段恢复。
- `backend/api/internal/logic/platform/user/relation_test.go`：新增恢复与空值回归测试。
- `frontend/platform_admin/src/api/resources.ts`：新增用户地址空值及坐标精度规则。
- `frontend/platform_admin/src/api/resource-display.ts`：支持字段级小数精度展示。
- `frontend/platform_admin/src/views/resource/ResourceFieldForm.vue`：支持文本字段自定义占位文本。
- `docs/11-数据接口与安全.md`：记录用户地址资源级安全例外。
- `docs/项目文档_用户地址受控展示_v1.0.md`：新增项目说明。

## 验证结果

- `go test ./internal/logic/platform/user ./internal/logic/common`：通过；测试使用工作区 Go 缓存，避免系统缓存目录权限限制。
- `pnpm.cmd type:check`：通过。
- 项目内 Biome 对本次 3 个前端修改文件执行定向检查：通过；仅报告 7 条既有模板识别告警，无新增错误。
- `pnpm.cmd contract:check`：通过，共校验 48 个资源。
- `pnpm.cmd build`：通过，Vite 成功构建 2608 个模块。
- `git diff --check`：通过。
- 浏览器访问 `http://localhost:5173/`：服务正常，重定向到登录页，控制台无错误；因无可用登录会话，未在自动化浏览器中读取真实用户地址数据。
- 重启平台开发后端后，12426 端口正常监听；`GET /heqi/platform/v1/ping/hello` 返回 `platform-api`、`ok`。

## 风险评估

完整地址和坐标属于敏感数据。风险通过资源级最小放行控制，不修改全局脱敏函数；其他终端和其他资源不受影响。若后续需要导出或扩大可见角色，必须另行增加用途审计与审批规则。