# 项目文档：配送点资料只读卡片 v1.0

## 1. 项目概述

- 项目：和气配送点管理系统。
- 功能：将“本点资料”从通用资源列表改为当前配送点专用只读资料卡。
- 技术栈：Vue 3、TypeScript、Arco Design、Go、Gin。
- 运行要求：前端 Node.js 20.19.0 及以上；后端沿用项目现有 Go 运行环境。

## 2. 目录结构

```text
platforms/
├── backend/api/internal/logic/delivery/
│   ├── base.go                              # 配送点资料响应组装
│   └── profile_test.go                      # 配送点资料字段映射测试
├── frontend/delivery_admin/
│   ├── scripts/check-delivery-profile-page.mjs # 资料卡静态契约检查
│   └── src/
│       ├── api/http.ts                      # 配送点后台 HTTP 客户端
│       └── views/shared/
│           ├── DeliveryProfilePage.vue      # 本点资料专用只读卡片
│           └── ResourcePage.vue             # 资源页面分发入口
└── docs/
    ├── 项目文档_配送点资料只读卡片_v1.0.md
    └── 操作日志_配送点资料只读卡片_20260822.md
```

## 3. 核心文件说明

### `backend/api/internal/logic/delivery/base.go`

- `ListProfile` 继续依据 JWT 中的配送点范围返回唯一记录。
- `buildDeliveryProfileView` 显式组合配送点公开字段和所属气站名称。
- API 路径和 `{ total, list }` 响应结构保持不变，不增加按客户端 identity 查询本点资料的接口。

### `frontend/delivery_admin/src/views/shared/DeliveryProfilePage.vue`

- 直接展示配送点编码、名称、负责人、地址、所属气站和状态。
- 配送点及气站完整 identity 可复制。
- 提供刷新、空数据、页面级错误和重新加载状态。
- 不提供查询、分页、详情或编辑入口。

### `frontend/delivery_admin/src/api/http.ts`

- `request<T>` 公共签名保持不变。
- 对纯文本 404、网关错误和其他非 JSON 响应生成可读错误，避免暴露 `JSON.parse` 异常。

## 4. 变更记录

- 新增本点资料专用只读卡片。
- 扩展 `/delivery_profile` 响应，新增 `gas_basic_name`。
- 移除本点资料页面的通用列表交互。
- 增加非 JSON HTTP 响应保护、后端字段映射测试和前端专项检查。
- 未新增依赖，未修改现有 API 路径和公共请求函数签名。

## 5. 维护指南

- 新增资料字段时，先在 `deliveryProfileView` 中声明公开字段，再同步前端 `DeliveryProfile` 类型和资料卡。
- 不得把 `/delivery_profile` 改为允许客户端选择任意配送点；数据范围必须来自 JWT。
- 修改资料卡后运行 `npm run profile:check` 和 `npm run build`。
- 修改资料响应后运行 `go test ./internal/logic/delivery`。
- 本地后端代码更新后必须重启 API 服务，再执行浏览器刷新回归。

## 6. 已知事项

- API 服务已更新并重启，重新登录后的浏览器回归确认所属气站名称、资料刷新和错误状态均正常。