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