diff --git a/docs/操作日志_客服工单关联与枚举中文展示修复_20260817.md b/docs/操作日志_客服工单关联与枚举中文展示修复_20260817.md new file mode 100644 index 0000000..8d48620 --- /dev/null +++ b/docs/操作日志_客服工单关联与枚举中文展示修复_20260817.md @@ -0,0 +1,43 @@ +# 客服工单关联与枚举中文展示修复操作日志 + +操作时间:2026-08-17 +操作类型:修改 +影响模块:平台总后台 / 客服管理 / 客服工单 + +## 操作前状态 + +- 用户列直接显示内部 UUID,业务人员无法快速识别提交人。 +- 分类和优先级直接显示 `delivery`、`normal` 等技术编码。 +- 新建、编辑页面使用自由文本输入,和列表的业务表达不一致。 + +## 具体操作 + +- 用户字段沿用 `/user_account` 关系接口,列表和详情优先展示用户名称,同时保留系统标识复制能力。 +- 分类增加配送、安装、维修、安检、复检、客服咨询中文选项。 +- 优先级增加低、普通、高、紧急中文选项,默认值仍为 `normal`。 +- 未知历史编码继续展示明确的未知值提示,不修改或丢弃原始值。 +- 增加静态展示契约检查,防止客服工单退回技术编码直出。 + +## 操作后状态 + +- 工单列表、详情、新建和编辑使用一致的中文业务名称。 +- API 与数据库仍使用原编码,公共接口保持向下兼容。 + +## 代码变更 + +- `frontend/platform_admin/src/api/resources.ts`:补充客服工单用户关系展示、分类和优先级枚举。 +- `frontend/platform_admin/scripts/check-resource-display-contracts.mjs`:增加客服工单中文展示契约。 +- `docs/项目文档_平台资源中文展示统一_v1.0.md`:增加 v1.18 变更记录。 + +## 验证结果 + +- 资源展示契约检查通过:`pnpm resource-display-contracts:check`。 +- 后端接口契约检查通过:`pnpm contract:check`。 +- Biome 代码检查通过:`pnpm exec biome lint src/api/resources.ts scripts/check-resource-display-contracts.mjs`。 +- TypeScript 类型检查通过:`pnpm type:check`。 +- 前端生产构建通过:`pnpm build`。 + +## 风险评估 + +- 仅调整前端字段元数据和展示方式,不改变接口字段、数据库值或现有路由。 +- 历史未知编码使用兜底提示,避免被错误翻译。 diff --git a/docs/项目文档_平台资源中文展示统一_v1.0.md b/docs/项目文档_平台资源中文展示统一_v1.0.md index fab1a98..8dd1062 100644 --- a/docs/项目文档_平台资源中文展示统一_v1.0.md +++ b/docs/项目文档_平台资源中文展示统一_v1.0.md @@ -80,3 +80,4 @@ frontend/platform_admin/ - v1.15:财务结算主体类型改为气站、配送点、工作人员中文枚举,并按类型联动对应主体资源,切换类型时清空旧主体。 - v1.16:财务对账渠道统一显示余额支付、支付宝、微信支付;账单日期按 `YYYY-MM-DD` 展示,不再回显时间和时区。 - v1.17:内容类型统一显示公告、协议,发布状态统一显示草稿、已发布;新建和编辑改用中文下拉并保留未知值提示。 +- v1.18:客服工单用户统一展示可读名称并保留标识复制;分类与优先级统一显示中文,新建和编辑改用中文下拉并保留未知值提示。 diff --git a/frontend/platform_admin/scripts/check-resource-display-contracts.mjs b/frontend/platform_admin/scripts/check-resource-display-contracts.mjs index 5aa58cc..3263fb2 100644 --- a/frontend/platform_admin/scripts/check-resource-display-contracts.mjs +++ b/frontend/platform_admin/scripts/check-resource-display-contracts.mjs @@ -356,6 +356,20 @@ for (const contentContract of [ `内容管理缺少中文枚举契约:${contentContract}`, ); } +for (const ticketContract of [ + "define('cs_ticket', '客服工单'", + "{ label: '配送', value: 'delivery' }", + "{ label: '客服咨询', value: 'customer_service' }", + "unknownValueLabel: '未知工单分类'", + "{ label: '普通', value: 'normal' }", + "unknownValueLabel: '未知优先级'", +]) { + assertIncludes( + resources, + ticketContract, + `客服工单缺少用户关系或中文枚举契约:${ticketContract}`, + ); +} assertIncludes( detailPage, '!hasResourceFieldLabel(props.definition, actualKey)', diff --git a/frontend/platform_admin/src/api/resources.ts b/frontend/platform_admin/src/api/resources.ts index b42054d..d1c8088 100644 --- a/frontend/platform_admin/src/api/resources.ts +++ b/frontend/platform_admin/src/api/resources.ts @@ -902,7 +902,27 @@ export const resources: ResourceUiDefinition[] = [ unknownValueLabel: '未知发布状态', }), ]), - define('cs_ticket', '客服工单', 'writable', [relation('user_account_identity', '/user_account', true), f('ticket_no', { required: true }), f('category', { required: true }), f('priority', { required: true })]), + define('cs_ticket', '客服工单', 'writable', [ + relation('user_account_identity', '/user_account', true, { + label: '用户', listLabel: '用户', listRelationNameOnly: true, + listDisplayIdentityCopy: true, displayRelationLabel: true, showIdentityCopy: true, + }), + f('ticket_no', { required: true }), + f('category', { required: true, type: 'select', options: [ + { label: '配送', value: 'delivery' }, + { label: '安装', value: 'installation' }, + { label: '维修', value: 'repair' }, + { label: '安检', value: 'inspection' }, + { label: '复检', value: 'reinspection' }, + { label: '客服咨询', value: 'customer_service' }, + ], unknownValueLabel: '未知工单分类' }), + f('priority', { required: true, type: 'select', defaultValue: 'normal', options: [ + { label: '低', value: 'low' }, + { label: '普通', value: 'normal' }, + { label: '高', value: 'high' }, + { label: '紧急', value: 'urgent' }, + ], unknownValueLabel: '未知优先级' }), + ]), define('platform_account', '平台账户', 'writable', [f('username', { required: true }), f('password', { required: true }), f('display_name'), f('avatar'), f('platform_role_code', { required: true, unknownValueLabel: '未知角色' }), f('phone')]), define('platform_role', '平台角色', 'writable', [f('role_code', { required: true }), f('name', { required: true }), f('location_scope', { required: true, type: 'select', options: resourceSearchEnumOptions('platform_role', 'location_scope') })], 'list', [ { name: '分配菜单', resource: '/platform_role/:identity/menu', method: 'PUT', fields: [f('menu_identities', { type: 'identity-list', relation: '/platform_menu' })] },