新增配送点资料只读卡片

docs/项目文档_配送点资料只读卡片_v1.0.md

@@ -0,0 +1,67 @@
+# 项目文档：配送点资料只读卡片 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 服务已更新并重启，重新登录后的浏览器回归确认所属气站名称、资料刷新和错误状态均正常。