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 查看规则。
• 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 展示，不再回显时间和时区。
• v1.17：内容类型统一显示公告、协议，发布状态统一显示草稿、已发布；新建和编辑改用中文下拉并保留未知值提示。
• v1.18：客服工单用户统一展示可读名称并保留标识复制；分类与优先级统一显示中文，新建和编辑改用中文下拉并保留未知值提示。
• v1.19：客服工单详情的气站、配送点和处理人员统一展示关系名称；未分派、未开始、未完成及未提交结果等空值改用明确业务状态，不再显示裸 -。
• v1.20：平台账户接口补回真实创建时间和更新时间；root 未填写联系电话时显示“未填写”，不生成虚假号码。