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

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

1. 项目概述

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

2. 目录结构

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