diff --git a/docs/操作日志_配送点详情字段中文化_20260823.md b/docs/操作日志_配送点详情字段中文化_20260823.md new file mode 100644 index 0000000..b3bc866 --- /dev/null +++ b/docs/操作日志_配送点详情字段中文化_20260823.md @@ -0,0 +1,39 @@ +# 操作日志：配送点详情字段中文化 + +操作时间：2026-08-23 +操作类型：新增、修改 +影响模块：5176 标准资源详情、合同关联记录、合同动作区 + +## 操作前状态 + +详情组件按响应对象键顺序动态展示字段。合同详情出现 `user_account_display_name`、`user_service_active`、`bound_at`、`product_name`、`product_params` 等英文键；合同状态显示数字，JSON 参数在表格中被截断。 + +## 具体操作 + +1. 新增配送端聚合详情契约，固定合同、订单的主字段和关联记录列序。 +2. 建立主详情与集合上下文中文标签，未知响应键默认不展示。 +3. 将用户名称合并到用户唯一标识行，将设备和操作人名称与唯一标识组合展示。 +4. 增加合同状态、合同动作、订单状态、布尔、金额和时间格式化。 +5. 为 JSON 参数增加“查看参数”弹层，支持对象、合法 JSON 字符串和历史普通文本。 +6. 明确当前设备名称与合同绑定快照的语义区别。 +7. 当签约用户不再属于合同气站时，仅保留终止合同操作。 + +## 行为变化 + +- 变更前：未知英文键直接成为标签，子表列序随响应漂移。 +- 变更后：只显示具有中文业务契约的字段；合同气瓶和修订记录使用固定列与完整参数查看器。 +- 兼容性：不修改 API、数据库和原始业务值，未知历史状态或动作仍保留原编码用于排障。 + +## 验证结果 + +- `npm.cmd run type:check`：通过。 +- `npm.cmd run resource-pages:check`：通过，详情 17、新建 9、编辑 5，并覆盖详情白名单、固定列序、关系合并、JSON 查看器和动作限制。 +- `npm.cmd run contract:check`、`npm.cmd run profile:check`：通过。 +- `npm.cmd run build`：通过，2643 个模块完成生产构建。 +- 应用内浏览器当前没有已登录的 5176 标签页，自动视觉回归被登录状态阻挡；用户提供的修复前截图已用于定位，不替代修复后回归。 + +## 风险评估 + +- 新后端字段默认隐藏：通过自动检查和维护规范要求先补中文契约，避免内部字段意外暴露。 +- 当前设备名称可能变化：页面说明其非历史快照，编码和类型继续作为绑定快照展示。 +- 子表字段较多：保留固定列宽和横向滚动，避免压缩导致内容不可读。 diff --git a/docs/项目文档_配送点独立资源页面_v1.0.md b/docs/项目文档_配送点独立资源页面_v1.0.md index e6be476..a45f997 100644 --- a/docs/项目文档_配送点独立资源页面_v1.0.md +++ b/docs/项目文档_配送点独立资源页面_v1.0.md @@ -87,6 +87,7 @@ npm.cmd run build - 新增配送人员资质的强制人员范围、上下文展示、关系预填锁定和安全返回链路。 - 新增后端生成的资源搜索契约，隐藏无效搜索并支持枚举中文名称与稳定编码。 - 新增配送合同受控 PDF 附件上传、鉴权预览、下载、替换和移除流程，列表及接口均不暴露内部路径。 +- 新增详情字段中文白名单和聚合子表固定契约，未知响应键不再直接回显；合同状态、动作和 JSON 参数对齐 5173。 - 保持配送点资料专用只读页面和现有公共后端接口不变。 ## 7. 已知边界 diff --git a/docs/项目文档_配送点详情字段中文化_v1.0.md b/docs/项目文档_配送点详情字段中文化_v1.0.md new file mode 100644 index 0000000..0d1659a --- /dev/null +++ b/docs/项目文档_配送点详情字段中文化_v1.0.md @@ -0,0 +1,39 @@ +# 项目文档：配送点详情字段中文化 v1.0 + +## 1. 项目概述 + +本项目将 5176 配送点管理端的标准资源详情展示对齐 5173。所有管理员可见字段必须来自显式中文契约；后端辅助键、内部 ID 和未知响应字段不得直接成为页面标签。 + +技术栈：Vue 3、TypeScript、Arco Design。功能仅修改展示层和前端动作可见性，不修改数据库及聚合详情接口。 + +## 2. 目录结构 + +```text +frontend/delivery_admin/src/ +├── api/resource-detail-contract.ts # 聚合详情字段、列序和 JSON 契约 +├── api/resource-display.ts # 中文标签、状态、动作、金额与时间格式化 +├── views/resource/ResourceDetailContent.vue # 白名单详情与关联表渲染 +└── views/resource/ResourceRecordPage.vue # 服务关系失效时的动作限制 +``` + +## 3. 核心规则 + +- 普通详情仅展示资源定义或公共中文字典中已声明的字段，未知响应键默认隐藏。 +- `*_display_name` 只作为对应 `*_identity` 的可读名称，不重复显示独立字段。 +- 合同状态显示“草稿、待处理、生效中、已过期、已终止”；未知值显示原编码。 +- 合同动作显示“启用合同、续签合同、终止合同”；未知动作保留原编码。 +- `user_service_active` 显示为“签约用户仍属合同气站：是/否”；为否时只保留终止合同操作。 +- 合同气瓶和修订记录使用固定中文列序，超宽表格横向滚动。 +- 名称字段与唯一标识组合展示；`product_params` 通过弹层完整查看格式化 JSON。 + +## 4. 合同气瓶语义 + +“智能气阀名称”读取当前设备资料，可能随设备改名变化；气瓶编码和气瓶类型名称是合同绑定时保存的快照。页面必须明确说明这一差异，避免把当前名称误认为历史审计快照。 + +## 5. 维护与验证 + +后端新增详情字段时，应先在资源字段字典或资源专属详情契约中声明中文名称和展示语义，再开放页面显示。禁止回退到 `Object.keys()` 后直接使用未知键名。修改后运行 `type:check`、`resource-pages:check`、`contract:check` 和生产构建，并抽查合同、订单及用户详情。 + +## 6. 变更记录 + +- v1.0（2026-08-23）：新增配送端详情中文白名单、合同固定子表、JSON 查看器、关系合并和合同动作限制。 diff --git a/frontend/delivery_admin/scripts/check-resource-pages.mjs b/frontend/delivery_admin/scripts/check-resource-pages.mjs index f560683..7805b0a 100644 --- a/frontend/delivery_admin/scripts/check-resource-pages.mjs +++ b/frontend/delivery_admin/scripts/check-resource-pages.mjs @@ -93,6 +93,9 @@ assert(listPage.includes("field.key === 'staff_account_identity'"), '人员范 assert(recordPage.includes('已锁定，不可更换'), '人员资质独立页未锁定所属配送人员'); const attachmentApi = read('src/api/contract-attachment.ts'); const attachmentState = read('src/views/resource/use-contract-attachment.ts'); +const detailContent = read('src/views/resource/ResourceDetailContent.vue'); +const detailContract = read('src/api/resource-detail-contract.ts'); +const resourceDisplay = read('src/api/resource-display.ts'); assert(definitions.includes("type: 'contract-file'"), '合同附件仍按普通文本字段渲染'); assert(recordPage.includes('title="合同附件"'), '合同详情页缺少附件状态卡片'); assert(recordPage.includes('downloadContractAttachment'), '合同详情页缺少独立下载入口'); @@ -101,5 +104,19 @@ assert(attachmentApi.includes('/gasorder_contract/attachment/upload'), '前端 assert(attachmentApi.includes('/:identity') === false, '前端附件接口不得拼接路由模板字面量'); assert(attachmentState.includes('delete payload.file_uri'), '新版管理端仍可能提交裸附件 URI'); assert(attachmentState.includes('payload.attachment_receipt'), '附件保存未提交签名收据'); +assert( + detailContract.indexOf("'bound_at'") < detailContract.indexOf("'product_name'") && + detailContract.indexOf("'product_name'") < detailContract.indexOf("'product_code'"), + '合同气瓶缺少固定业务列序', +); +assert(detailContract.includes("relationIdentityKeys: { product_name: 'product_info_identity' }"), '智能气阀名称未合并唯一标识'); +assert(detailContract.includes("relationIdentityKeys: { operator_name: 'operator_identity' }"), '合同修订操作人未合并唯一标识'); +assert(detailContent.includes("key.endsWith('_display_name')"), '详情页仍可能重复显示英文辅助名称字段'); +assert(detailContent.includes('hasDetailFieldLabel'), '详情页未启用中文字段白名单'); +assert(detailContent.includes('查看参数'), '关联记录缺少完整 JSON 查看入口'); +assert(detailContent.includes('智能气阀名称取当前设备资料'), '合同气瓶名称与快照语义未说明'); +assert(resourceDisplay.includes("user_service_active: '签约用户仍属合同气站'"), '签约服务关系缺少中文业务标签'); +assert(resourceDisplay.includes("activate: '启用合同'"), '合同修订动作未中文化'); +assert(recordPage.includes("record.value.user_service_active === false"), '失效服务关系下未限制合同动作'); console.log(`独立资源页面契约通过：详情 ${listResources.length}，新建 ${creatable.size}，编辑 ${editable.size}`); diff --git a/frontend/delivery_admin/src/api/resource-detail-contract.ts b/frontend/delivery_admin/src/api/resource-detail-contract.ts new file mode 100644 index 0000000..30377fb --- /dev/null +++ b/frontend/delivery_admin/src/api/resource-detail-contract.ts @@ -0,0 +1,186 @@ +/** + * 功能描述：声明配送端聚合详情的固定字段顺序、关联表列和 JSON 展示规则。 + * 版本：v1.0.0。 + */ + +export type ResourceCollectionContract = { + columns: string[]; + jsonColumns?: string[]; + relationIdentityKeys?: Record; +}; + +export type ResourceDetailContract = { + leadingKeys?: string[]; + hiddenKeys?: string[]; + collections?: Record; +}; + +const contracts: Record = { + gasorder_contract: { + leadingKeys: [ + 'contract_no', + 'contract_status', + 'title', + 'user_account_identity', + 'user_service_active', + 'gas_basic_identity', + 'delivery_basic_identity', + 'default_delivery_fee', + 'signed_at', + 'effective_at', + 'expired_at', + 'terms', + 'identity', + 'status', + 'created_at', + 'updated_at', + ], + collections: { + products: { + columns: [ + 'bound_at', + 'product_name', + 'product_code', + 'product_type_name', + 'product_params', + 'unit_price', + 'unbound_at', + 'unbind_reason', + ], + jsonColumns: ['product_params'], + relationIdentityKeys: { product_name: 'product_info_identity' }, + }, + revisions: { + columns: [ + 'occurred_at', + 'action', + 'contract_status', + 'effective_at', + 'expired_at', + 'operator_name', + 'reason', + ], + relationIdentityKeys: { operator_name: 'operator_identity' }, + }, + }, + }, + gasorder_basic: { + leadingKeys: [ + 'order_no', + 'request_no', + 'order_status', + 'gasorder_contract_identity', + 'creator_type', + 'creator_identity', + 'user_account_identity', + 'gas_basic_identity', + 'delivery_basic_identity', + 'staff_account_identity', + 'identity', + 'status', + ], + collections: { + items: { + columns: [ + 'product_name', + 'product_code', + 'product_type_name', + 'product_params', + 'unit_price', + ], + jsonColumns: ['product_params'], + }, + assignments: { + columns: [ + 'assigned_at', + 'gas_basic_display_name', + 'delivery_basic_display_name', + 'staff_account_display_name', + 'assigner_name', + 'reason', + ], + }, + statuses: { + columns: [ + 'occurred_at', + 'from_status', + 'to_status', + 'operator_name', + 'reason', + ], + }, + tracks: { + columns: [ + 'attempt_no', + 'staff_account_display_name', + 'started_at', + 'completed_at', + ], + relationIdentityKeys: { + staff_account_display_name: 'staff_account_identity', + }, + }, + confirmations: { + columns: [ + 'confirmed_at', + 'confirm_type', + 'recipient_name', + 'recipient_phone', + 'remark', + ], + }, + payments: { + columns: [ + 'attempt_no', + 'payment_no', + 'payment_order_identity', + 'amount', + 'payment_status', + ], + }, + }, + }, +}; + +const jsonFieldKeys = new Set([ + 'params', + 'product_params', + 'product_snapshot', + 'args', + 'callback_msg', +]); + +/** 返回资源专属详情契约；普通资源使用中文字段白名单动态排序。 */ +export function resourceDetailContract(name: string): ResourceDetailContract { + return contracts[name] ?? {}; +} + +/** 判断主详情字段是否使用完整 JSON 查看器。 */ +export function isResourceJsonField(key: string) { + return jsonFieldKeys.has(key); +} + +/** 返回集合名称字段对应的稳定唯一标识字段。 */ +export function collectionRelationIdentityKey( + resourceName: string, + collectionKey: string, + column: string, +) { + return ( + contracts[resourceName]?.collections?.[collectionKey] + ?.relationIdentityKeys?.[column] ?? '' + ); +} + +/** 判断集合字段是否使用完整 JSON 查看器。 */ +export function isCollectionJsonField( + resourceName: string, + collectionKey: string, + column: string, +) { + return Boolean( + contracts[resourceName]?.collections?.[ + collectionKey + ]?.jsonColumns?.includes(column), + ); +} diff --git a/frontend/delivery_admin/src/api/resource-display.ts b/frontend/delivery_admin/src/api/resource-display.ts index 899f8d4..a23a89b 100644 --- a/frontend/delivery_admin/src/api/resource-display.ts +++ b/frontend/delivery_admin/src/api/resource-display.ts @@ -1,10 +1,13 @@ /** * 功能描述：统一配送点资源独立页面的字段名称和值展示。 - * 版本：v1.0.0。 + * 版本：v1.1.0。 */ import dayjs from 'dayjs'; -import { resourceFieldLabel, type ResourceUiDefinition } from './resources'; import type { ResourceRow } from './resource-record-form'; +import { + resourceFieldLabel as defaultResourceFieldLabel, + type ResourceUiDefinition, +} from './resources'; const aliases: Record = { id: 'ID', @@ -19,34 +22,175 @@ const aliases: Record = { payments: '支付记录', revisions: '修订记录', products: '合同气瓶', + addresses: '用户地址', + contract: '合同', + order: '订单', + user_service_active: '签约用户仍属合同气站', + user_account_display_name: '用户账户', + gas_basic_display_name: '气站', + delivery_basic_display_name: '配送点', + staff_account_display_name: '配送人员', + assigner_name: '分配人', +}; + +/** 聚合子表字段按父资源和集合覆盖全局同名字段语义。 */ +const collectionAliases: Record> = { + 'gasorder_contract.products': { + bound_at: '绑定时间', + product_name: '智能气阀名称', + product_code: '气瓶编码', + product_type_name: '气瓶类型名称', + product_params: '气瓶规格参数', + unit_price: '约定充装单价（元）', + unbound_at: '解绑时间', + unbind_reason: '解绑原因', + }, + 'gasorder_contract.revisions': { + occurred_at: '发生时间', + action: '合同动作', + contract_status: '合同状态', + effective_at: '生效时间', + expired_at: '到期时间', + operator_name: '操作人', + reason: '变更原因', + }, + 'gasorder_basic.items': { + product_name: '智能气阀名称', + product_code: '设备编码', + product_type_name: '设备类型', + product_params: '设备参数', + unit_price: '成交单价（元）', + }, + 'gasorder_basic.assignments': { + assigned_at: '分配时间', + gas_basic_display_name: '气站', + delivery_basic_display_name: '配送点', + staff_account_display_name: '配送人员', + assigner_name: '分配人', + reason: '分配原因', + }, + 'gasorder_basic.statuses': { + occurred_at: '发生时间', + from_status: '原状态', + to_status: '新状态', + operator_name: '操作人', + reason: '原因', + }, + 'gasorder_basic.tracks': { + attempt_no: '配送尝试次数', + staff_account_display_name: '配送人员', + started_at: '开始时间', + completed_at: '完成时间', + }, + 'gasorder_basic.confirmations': { + confirmed_at: '确认时间', + confirm_type: '确认方式', + recipient_name: '签收人姓名', + recipient_phone: '签收人电话', + remark: '备注', + }, + 'gasorder_basic.payments': { + attempt_no: '支付尝试次数', + payment_no: '支付单号', + payment_order_identity: '支付记录唯一标识', + amount: '支付金额（元）', + payment_status: '支付状态', + }, }; const moneyKeys = new Set([ - 'amount', 'unit_price', 'balance', 'withdrawal_balance', 'delivery_fee', - 'discount_amount', 'total_amount', 'default_delivery_fee', 'fee', + 'amount', + 'unit_price', + 'balance', + 'withdrawal_balance', + 'delivery_fee', + 'discount_amount', + 'total_amount', + 'default_delivery_fee', + 'fee', ]); /** 返回聚合详情中的主记录。 */ export function primaryRecord(detail: ResourceRow): ResourceRow { for (const key of ['order', 'contract', 'track', 'user']) { - if (detail[key] && typeof detail[key] === 'object') return detail[key] as ResourceRow; + if (detail[key] && typeof detail[key] === 'object') + return detail[key] as ResourceRow; } return detail; } /** 返回字段中文名称。 */ -export function detailFieldLabel(key: string) { - return aliases[key] ?? resourceFieldLabel(key); +export function detailFieldLabel( + definition: ResourceUiDefinition, + key: string, + collectionKey = '', +) { + const normalized = key.endsWith('_masked') ? key.slice(0, -7) : key; + return ( + collectionAliases[`${definition.name}.${collectionKey}`]?.[normalized] ?? + definition.fields.find((field) => field.key === normalized)?.label ?? + aliases[normalized] ?? + defaultResourceFieldLabel(normalized) + ); +} + +/** 判断字段是否具有明确中文契约，未知响应键不得直接回显。 */ +export function hasDetailFieldLabel( + definition: ResourceUiDefinition, + key: string, + collectionKey = '', +) { + const normalized = key.endsWith('_masked') ? key.slice(0, -7) : key; + return detailFieldLabel(definition, key, collectionKey) !== normalized; } /** 返回通用记录状态名称。 */ export function recordStatusLabel(status: number) { - return { 0: '待审核', 1: '启用', 2: '停用', 3: '已归档', 4: '已冻结' }[status] ?? '未知状态'; + return ( + { 0: '待审核', 1: '启用', 2: '停用', 3: '已归档', 4: '已冻结' }[status] ?? + `未知状态（${status}）` + ); } /** 返回通用记录状态颜色。 */ export function recordStatusColor(status: number) { - return { 0: 'orange', 1: 'green', 2: 'red', 3: 'gray', 4: 'purple' }[status] ?? 'gray'; + return ( + { 0: 'orange', 1: 'green', 2: 'red', 3: 'gray', 4: 'purple' }[status] ?? + 'gray' + ); +} + +/** 返回合同业务状态名称。 */ +export function contractStatusLabel(status: number) { + return ( + { + 0: '草稿', + 10: '待处理', + 11: '生效中', + 12: '已过期', + 13: '已终止', + }[status] ?? `未知状态（${status}）` + ); +} + +/** 返回合同业务状态颜色。 */ +export function contractStatusColor(status: number) { + return ( + { 0: 'gray', 10: 'orange', 11: 'green', 12: 'red', 13: 'gray' }[status] ?? + 'gray' + ); +} + +/** 返回合同修订动作名称。 */ +export function contractActionLabel(action: unknown) { + const value = String(action); + return ( + { + activate: '启用合同', + renew: '续签合同', + terminate: '终止合同', + }[value] ?? `未知动作（${value}）` + ); } /** 将接口字段值转换为中文可读内容。 */ @@ -57,17 +201,53 @@ export function displayResourceValue( ) { if (value == null || value === '') return '-'; const field = definition.fields.find((item) => item.key === key); - const option = field?.options?.find((item) => String(item.value) === String(value)); + const option = field?.options?.find( + (item) => String(item.value) === String(value), + ); if (option) return option.label; if (key === 'role_code') { - return { delivery: '配送人员', installer: '安装人员', operations: '运维人员' }[String(value)] - ?? String(value); + return ( + { delivery: '配送人员', installer: '安装人员', operations: '运维人员' }[ + String(value) + ] ?? String(value) + ); } if (typeof value === 'boolean') return value ? '是' : '否'; if (key === 'status') return recordStatusLabel(Number(value)); - if (moneyKeys.has(key) || key.endsWith('_amount') || key.endsWith('_balance_after')) { + if (key === 'contract_status') return contractStatusLabel(Number(value)); + if (key === 'action') return contractActionLabel(value); + if ( + [ + 'order_status', + 'previous_order_status', + 'from_status', + 'to_status', + ].includes(key) + ) { + return ( + { + 0: '草稿', + 16: '已创建', + 18: '已分配', + 19: '充装中', + 20: '已就绪', + 21: '异常', + 22: '已取消', + 23: '已完成', + 33: '配送中', + 34: '待确认', + }[Number(value)] ?? `未知状态（${String(value)}）` + ); + } + if ( + moneyKeys.has(key) || + key.endsWith('_amount') || + key.endsWith('_balance_after') + ) { const amount = Number(value); - return Number.isFinite(amount) ? `¥${(amount / 100).toFixed(2)}` : String(value); + return Number.isFinite(amount) + ? `¥${(amount / 100).toFixed(2)}` + : String(value); } if (key.endsWith('_at') || key === 'created_at' || key === 'updated_at') { const date = dayjs(String(value)); @@ -77,10 +257,23 @@ export function displayResourceValue( return String(value); } +/** 判断软删除时间是否为空对象或空值。 */ +export function isEmptyDeletedAt(value: unknown) { + if (value == null || value === '') return true; + if (typeof value !== 'object') return false; + return Object.values(value as Record).every( + (item) => item == null || item === '' || item === false || item === 0, + ); +} + /** 返回合同编辑阻止原因。 */ -export function recordEditReason(definition: ResourceUiDefinition, row: ResourceRow) { +export function recordEditReason( + definition: ResourceUiDefinition, + row: ResourceRow, +) { if (definition.name !== 'gasorder_contract') return ''; if (Number(row.contract_status) !== 0) return '只有草稿状态的合同可以编辑'; - if (![0, 1].includes(Number(row.status))) return '停用、已归档或已冻结的合同不可编辑'; + if (![0, 1].includes(Number(row.status))) + return '停用、已归档或已冻结的合同不可编辑'; return ''; } diff --git a/frontend/delivery_admin/src/views/resource/ResourceDetailContent.vue b/frontend/delivery_admin/src/views/resource/ResourceDetailContent.vue index 3c644a6..d9b55ad 100644 --- a/frontend/delivery_admin/src/views/resource/ResourceDetailContent.vue +++ b/frontend/delivery_admin/src/views/resource/ResourceDetailContent.vue @@ -1,44 +1,91 @@ - +