82 lines
6.1 KiB
Markdown
82 lines
6.1 KiB
Markdown
# 平台资源中文展示统一
|
||
|
||
## 1. 项目概述
|
||
|
||
本次统一平台总后台 48 类资源的列表、详情、关联记录、操作弹窗和树形页面展示规则。目标是以中文业务名称和业务单号作为主要信息，将 UUID 降级为可复制的技术信息，并阻止未知响应字段直接形成英文表头。
|
||
|
||
技术栈保持不变：Vue 3、TypeScript、Vite、Arco Design 和现有 Gin API。本次不修改数据库结构，不删除或重命名既有接口字段，也不改变已有不脱敏字段的内容和可见性。
|
||
|
||
## 2. 核心目录
|
||
|
||
```text
|
||
frontend/platform_admin/
|
||
├── src/api/
|
||
│ ├── resources.ts # 48 类资源字段、关系和中文名称
|
||
│ ├── resource-display.ts # 共享金额、状态、关系和中文兜底
|
||
│ └── resource-detail-contract.ts # 聚合详情固定列与 JSON 契约
|
||
├── src/views/resource/
|
||
│ ├── ResourceDetailContent.vue # 标准详情和关联记录渲染
|
||
│ └── use-resource-relations.ts # 静态及动态关系名称补载
|
||
├── src/views/shared/
|
||
│ ├── CrudListPage.vue # 业务列优先的标准列表
|
||
│ ├── resource-list-field-display.ts # 资源列表列序与关系名称
|
||
│ ├── RelationNameText.vue # 名称、跳转和 UUID 复制
|
||
│ └── TreePage.vue # 树形资源中文展示
|
||
└── scripts/check-resource-display-contracts.mjs # 48 类资源静态契约检查
|
||
```
|
||
|
||
## 3. 展示规则
|
||
|
||
### 3.1 列表
|
||
|
||
- 不展示数据库自增 `id`。
|
||
- 默认展示最多 6 个主要业务字段。
|
||
- 订单、合同、支付、钱包流水和商城订单使用专属列顺序。
|
||
- “系统唯一标识”位于业务字段之后，并保留完整复制能力。
|
||
- 表格宽度不足时只在表格容器内部滚动。
|
||
|
||
### 3.2 详情与关系
|
||
|
||
- 业务编号、状态和主要关联置前；UUID、创建时间和更新时间靠后。
|
||
- 静态关系和由主体类型决定的动态关系都补载可读名称。
|
||
- 名称可点击进入存在详情路由的关联资源；树形资源没有详情路由时仅展示。
|
||
- 名称加载失败时展示明确错误文案，并继续保留 UUID。
|
||
- 未配置中文名称的响应字段在生产页面隐藏，由静态检查阻止回归。
|
||
|
||
### 3.3 聚合子表与 JSON
|
||
|
||
- 配送合同的气瓶与修订、配送订单的明细、分配、状态、轨迹、确认和支付使用固定中文列。
|
||
- 关联表不再根据 `Object.keys` 自动追加未知列。
|
||
- JSON 查看器完整展示原内容，仅改善排版；已有不脱敏要求保持不变。
|
||
|
||
## 4. 兼容性与维护
|
||
|
||
- 本次前端扩展不改变 API 请求协议。
|
||
- 没有历史名称快照时使用当前关联名称和 UUID，不伪造历史名称。
|
||
- 新增资源字段时必须先加入中文字段字典；新增聚合集合时必须声明固定列。
|
||
- 执行 `npm run resource-display-contracts:check` 可检查资源数量、空只读契约、数据库 ID 列、未知字段保护和固定集合配置。
|
||
|
||
## 5. 变更记录
|
||
|
||
- v1.0：建立 48 类资源中文展示契约，补齐原 19 类空字段只读资源。
|
||
- v1.0：统一业务列优先、关系名称跳转、UUID 次要复制和响应式表格。
|
||
- v1.0：建立固定聚合子表和完整 JSON 查看规则。
|
||
- v1.1：修复树标题插槽误读 `title` 导致中文名称为空的问题，并增加树节点名称回归检查。
|
||
- v1.2：树形资源统一改为树形表格，明确展示名称、排序、状态、系统标识和操作，唯一标识降级为复制入口。
|
||
- v1.2.1：补齐 Arco 表格 `columns` 插槽，修复树形表格容器存在但列和数据不渲染的问题。
|
||
- v1.3：购物车列表的用户与商品关系列统一展示可读名称，UUID 降级为复制和排障信息。
|
||
- v1.4：商城订单统一展示用户名称及空值业务文案；Mock 订单改用商城独立交易状态，并补齐金额、支付时间和下单快照。
|
||
- v1.5：商品评价列表的商城订单、商品和用户关系统一展示可读业务名称，UUID 降级为复制信息。
|
||
- v1.6：商品分类的技术标识列与其他电商列表统一为“系统唯一标识”，显示截断值并保留复制能力。
|
||
- v1.7：提现详情的钱包关系改为可读归属类型摘要，审核人合并展示姓名快照与可复制标识，移除“名称加载失败”和重复裸 UUID。
|
||
- v1.7.1：提现列表的审核人改为直接使用审核姓名快照，并保留审核人标识复制与详情跳转，避免历史账户关系加载失败影响列表展示。
|
||
- v1.8：财务支付记录的商城订单关系统一显示订单号，支付状态使用财务领域的 `35=已支付`，渠道按业务文档统一显示“余额支付”“支付宝”“微信支付”。
|
||
- v1.9：财务支付详情新增“支付商品”，由后端按商城订单明细的成交快照汇总商品名称和数量，确保商品改名后仍可按交易事实核对。
|
||
- v1.10：退款审核列表和详情由接口直接返回原订单号与申请用户姓名，前端保留关系标识复制和详情跳转，不再依赖临时关系加载。
|
||
- v1.11：退款审核新增“退款商品”，商城退款读取成交快照，气体配送退款通过原订单项读取产品名称，并汇总退款数量。
|
||
- v1.12：退款审核补齐空值业务文案、审核人名称、支付单号和钱包归属摘要，UUID 统一降级为复制信息。
|
||
- v1.13：修正固定 Mock 退款误把气站账号写为平台审核人的数据错误，并在重复初始化时幂等修复历史记录；退款审核人由接口稳定返回平台账号名称。
|
||
- v1.14：日期时间统一按字段类型格式化，财务结算周期完整显示为 `YYYY-MM-DD HH:mm:ss`，不再回显带 `T` 的截断 RFC3339 文本。
|
||
- v1.15：财务结算主体类型改为气站、配送点、工作人员中文枚举，并按类型联动对应主体资源，切换类型时清空旧主体。
|
||
- v1.16：财务对账渠道统一显示余额支付、支付宝、微信支付；账单日期按 `YYYY-MM-DD` 展示，不再回显时间和时区。
|