platforms/docs/项目文档_平台资源中文展示统一_v1.0.md

平台资源中文展示统一

1. 项目概述

本次统一平台总后台 48 类资源的列表、详情、关联记录、操作弹窗和树形页面展示规则。目标是以中文业务名称和业务单号作为主要信息，将 UUID 降级为可复制的技术信息，并阻止未知响应字段直接形成英文表头。

技术栈保持不变：Vue 3、TypeScript、Vite、Arco Design 和现有 Gin API。本次不修改数据库结构，不删除或重命名既有接口字段，也不改变已有不脱敏字段的内容和可见性。

2. 核心目录

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 查看规则。