From 963e497bf32e15c7e8ca83f416e222bfb66eaf2c Mon Sep 17 00:00:00 2001
From: czl231 <3286836406@qq.com>
Date: Sat, 15 Aug 2026 18:36:38 +0800
Subject: [PATCH] =?UTF-8?q?=E4=BC=98=E5=8C=96=E9=85=8D=E9=80=81=E8=AE=A2?=
 =?UTF-8?q?=E5=8D=95=E7=8A=B6=E6=80=81=E4=B8=AD=E6=96=87=E5=B1=95=E7=A4=BA?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../操作日志_配送订单状态展示优化_20260815.md | 49 +++++++++++++++++++
 docs/项目文档_配送订单状态展示优化_v1.0.md    | 33 +++++++++++++
 frontend/platform_admin/package.json          |  1 +
 .../scripts/check-gasorder-status-display.mjs | 20 ++++++++
 .../src/api/resource-display.ts               | 26 +++++++++-
 5 files changed, 128 insertions(+), 1 deletion(-)
 create mode 100644 docs/操作日志_配送订单状态展示优化_20260815.md
 create mode 100644 docs/项目文档_配送订单状态展示优化_v1.0.md
 create mode 100644 frontend/platform_admin/scripts/check-gasorder-status-display.mjs

diff --git a/docs/操作日志_配送订单状态展示优化_20260815.md b/docs/操作日志_配送订单状态展示优化_20260815.md
new file mode 100644
index 0000000..219df0b
--- /dev/null
+++ b/docs/操作日志_配送订单状态展示优化_20260815.md
@@ -0,0 +1,49 @@
+# 配送订单状态展示优化操作日志
+
+操作时间：2026-08-15
+
+操作类型：修改
+
+影响模块：平台总后台、气体配送订单详情
+
+## 操作前状态
+
+- 订单详情中的异常前订单状态直接显示数字 `0`。
+- 状态记录中的原状态和新状态直接显示数字编码。
+- 尚未分配订单的工作人员唯一标识显示通用占位符 `-`。
+
+## 具体操作
+
+- 新增配送订单状态中文展示字典，并应用于当前状态、异常前状态和状态记录。
+- 按字段语义将 `previous_order_status=0` 显示为“无”，保留 `from_status=0` 的“草稿”含义。
+- 将空工作人员唯一标识显示为“暂未分配”。
+- 新增配送订单状态展示专项检查。
+
+## 操作后状态
+
+- 管理员无需理解数字编码即可阅读订单状态和流转历史。
+- 非异常订单与尚未分配订单具有明确空值文案。
+- 接口、数据库和订单状态机保持不变。
+
+## 代码变更
+
+- `frontend/platform_admin/src/api/resource-display.ts`：增加配送订单状态和空值展示规则。
+- `frontend/platform_admin/scripts/check-gasorder-status-display.mjs`：增加专项静态检查。
+- `frontend/platform_admin/package.json`：注册专项检查命令。
+- `docs/项目文档_配送订单状态展示优化_v1.0.md`：记录状态字典和维护规则。
+
+## 验证结果
+
+- `npm.cmd run gasorder-status-display:check`：通过。
+- `npm.cmd run gasorder-list-display:check`：通过，既有订单可读展示未回退。
+- `npm.cmd run type:check`：通过。
+- `npm.cmd run contract:check`：通过，48 个资源契约一致。
+- `npm.cmd run build`：通过，TypeScript 编译和 Vite 生产构建成功。
+- `git diff --check`：通过，未发现空白符错误。
+- 变更文件专项 Biome lint：通过，仅报告 `resource-display.ts` 原有的 `hasOwnProperty` 建议级警告。
+- 全量 `npm.cmd run lint`：未通过，仓库既有文件仍有 2 个错误和 176 个警告；本次未扩大范围处理。
+
+## 风险评估
+
+- 改动仅影响展示层，不改变状态值、接口或业务流转。
+- 状态字典集中维护；未知状态保留数字值以便排查，不会被错误映射。
diff --git a/docs/项目文档_配送订单状态展示优化_v1.0.md b/docs/项目文档_配送订单状态展示优化_v1.0.md
new file mode 100644
index 0000000..cd8bcad
--- /dev/null
+++ b/docs/项目文档_配送订单状态展示优化_v1.0.md
@@ -0,0 +1,33 @@
+# 项目文档：配送订单状态展示优化 v1.0
+
+## 1. 项目概述
+
+平台总后台的配送订单详情和状态记录统一展示中文业务状态，并为异常前状态及未分配工作人员提供明确文案，避免管理员直接理解数字编码或无语义占位符。
+
+## 2. 状态字典
+
+- `0`：草稿，仅用于首条状态记录的原状态。
+- `16`：已创建。
+- `18`：已分配。
+- `19`：充装中。
+- `20`：已就绪。
+- `21`：异常。
+- `22`：已取消。
+- `23`：已完成。
+- `33`：配送中。
+- `34`：待确认。
+
+## 3. 核心行为
+
+- 订单当前状态、状态记录原状态和新状态使用同一中文状态字典。
+- `previous_order_status=0` 是“没有异常前状态”的哨兵值，单独显示为“无”，不显示为“草稿”。
+- 工作人员唯一标识为空时显示“暂未分配”。
+- 唯一标识继续使用公共组件展示末尾 12 位，支持悬浮查看和点击复制完整值。
+
+## 4. 接口兼容性
+
+本次仅修改前端展示，不修改数据库字段、后端状态机、接口字段和值域。
+
+## 5. 维护指南
+
+配送订单新增状态时，应先更新服务端状态常量与状态机规则，再同步更新 `gasorderStatusLabel` 和专项展示检查。
diff --git a/frontend/platform_admin/package.json b/frontend/platform_admin/package.json
index 8beab7a..3563bc9 100644
--- a/frontend/platform_admin/package.json
+++ b/frontend/platform_admin/package.json
@@ -27,6 +27,7 @@
     "gasorder-contract-products:check": "node scripts/check-gasorder-contract-product-display.mjs",
     "gasorder-creator:check": "node scripts/check-gasorder-creator-linkage.mjs",
     "gasorder-list-display:check": "node scripts/check-gasorder-list-display.mjs",
+    "gasorder-status-display:check": "node scripts/check-gasorder-status-display.mjs",
     "product-ownership:check": "node scripts/check-product-ownership-action.mjs",
     "product-ownership-display:check": "node scripts/check-product-ownership-display.mjs",
     "product-lifecycle-display:check": "node scripts/check-product-lifecycle-display.mjs",
diff --git a/frontend/platform_admin/scripts/check-gasorder-status-display.mjs b/frontend/platform_admin/scripts/check-gasorder-status-display.mjs
new file mode 100644
index 0000000..b996960
--- /dev/null
+++ b/frontend/platform_admin/scripts/check-gasorder-status-display.mjs
@@ -0,0 +1,20 @@
+/**
+ * 功能：检查配送订单详情和状态记录使用中文状态及明确空值文案。
+ * 版本：v1.0.0
+ */
+import fs from 'node:fs';
+
+const display = fs.readFileSync(new URL('../src/api/resource-display.ts', import.meta.url), 'utf8');
+const checks = [
+  [display.includes("0: '草稿'"), '缺少状态记录原状态“草稿”文案'],
+  [display.includes("16: '已创建'"), '缺少配送订单“已创建”状态文案'],
+  [display.includes("34: '待确认'"), '缺少配送订单“待确认”状态文案'],
+  [display.includes("key === 'previous_order_status' && Number(value) === 0"), '异常前订单状态 0 未单独处理'],
+  [display.includes("return '暂未分配'"), '缺少未分配工作人员文案'],
+];
+
+for (const [passed, message] of checks) {
+  if (!passed) throw new Error(message);
+}
+
+console.log('配送订单状态展示检查通过：状态中文化，哨兵值和未分配人员语义明确。');
diff --git a/frontend/platform_admin/src/api/resource-display.ts b/frontend/platform_admin/src/api/resource-display.ts
index 356c999..97b9107 100644
--- a/frontend/platform_admin/src/api/resource-display.ts
+++ b/frontend/platform_admin/src/api/resource-display.ts
@@ -1,6 +1,6 @@
 /**
  * 功能：统一资源列表与详情页面的字段名称、关系、金额、状态和时间展示。
- * 版本：v1.3.0
+ * 版本：v1.4.0
  */
 import dayjs from 'dayjs';
 import { staffRoleLabel } from './resource-staff-relation';
@@ -141,6 +141,24 @@ export function contractStatusLabel(status: number) {
   );
 }
 
+/** 将配送订单业务状态转换为状态机约定的中文名称。 */
+export function gasorderStatusLabel(status: number) {
+  return (
+    {
+      0: '草稿',
+      16: '已创建',
+      18: '已分配',
+      19: '充装中',
+      20: '已就绪',
+      21: '异常',
+      22: '已取消',
+      23: '已完成',
+      33: '配送中',
+      34: '待确认',
+    }[status] ?? `未知（${status}）`
+  );
+}
+
 /** 选择关系记录的首选可读名称。 */
 export function optionLabel(option: ResourceRow) {
   return String(
@@ -227,10 +245,16 @@ function relationLabel(
 export function displayRawValue(key: string, value: unknown) {
   // 历史合同可能缺少到期时间，明确提示补录，避免将数据缺失误认为无期限合同。
   if (key === 'expired_at' && (value == null || value === '')) return '待补录';
+  // 配送订单尚未分配时不存在工作人员标识，使用业务语义替代通用占位符。
+  if (key === 'staff_account_identity' && (value == null || value === ''))
+    return '暂未分配';
   if (value == null || value === '') return '-';
   if (typeof value === 'boolean') return value ? '是' : '否';
   if (key === 'status') return recordStatusLabel(Number(value));
   if (key === 'contract_status') return contractStatusLabel(Number(value));
+  if (key === 'previous_order_status' && Number(value) === 0) return '无';
+  if (['order_status', 'previous_order_status', 'from_status', 'to_status'].includes(key))
+    return gasorderStatusLabel(Number(value));
   if (key === 'action') {
     return (
       {