2026-05-19-status-tag-registry-design.md 8.0 KB

状态标签注册表设计

日期:2026-05-19 状态:已批准 范围:web-admin 前端工程所有枚举字段标签集中化管理

1. 背景与问题

当前 web-admin 中所有状态/结论/类型字段的标签映射散落在 21 个 Vue 文件 中,存在以下问题:

  1. 颜色不一致:同一状态值在表格中用 el-tag type="primary"(蓝色),查看弹窗中用自定义 badge--purple(紫色)
  2. 大量重复:protocolStatusLabel 在 6 个文件中重复定义,newbornSexLabel 在 6 个文件中重复定义
  3. tagType 缺失:仅 1/15 的集中化函数有 tagType 变体,其余需在使用处手写
  4. Badge CSS 残留:3 个复杂查看弹窗(ProtocolViewDialog、DonationViewDialog、ChannelViewDialog)仍使用自定义 .badge--* CSS,与 el-tag 并存

2. 目标

  • 新建一个 src/utils/status-tag-registry.ts,集中定义所有枚举字段的 label + tagType
  • 所有页面和弹窗统一从此文件导入,确保同一状态值在任何地方颜色一致
  • 消灭所有自定义 badge CSS 系统,统一为 el-tag
  • 与现有调用签名完全兼容,零迁移成本

3. 方案选择

方案 描述 优点 缺点
A. 单体注册表(选定) 一个 status-tag-registry.ts 集中管理所有枚举 Ctrl+Click 一处看到所有映射,改颜色绝不遗漏 文件约 300 行
B. 按域分文件 拆成 qc-status.ts、protocol-status.ts 等 每个文件职责单一 需记住去哪个文件找,import 路径多
C. 运行时注册 registerStatusGroup + getStatusLabel 查找 可扩展 过度设计,丧失类型安全

选定方案 A。

4. 数据结构

// src/utils/status-tag-registry.ts

/** el-tag 的 type 属性值 */
export type TagType = 'success' | 'warning' | 'danger' | 'info' | '' | 'primary'

/** 单条枚举映射 */
export interface StatusItem {
  label: string
  tagType: TagType
}

/** 注册表类型 */
export type StatusRegistry = Record<string, StatusItem>

不使用类、不使用运行时注册、不使用 Map。纯静态 Record,类型安全、tree-shakeable。

5. 便捷函数工厂

/** 从注册表提取 label */
export function createLabelGetter(registry: StatusRegistry) {
  return (code: string): string => registry[code]?.label ?? code ?? '—'
}

/** 从注册表提取 tagType */
export function createTagTypeGetter(registry: StatusRegistry) {
  return (code: string): TagType => registry[code]?.tagType ?? 'info'
}

导出示例:

export const protocolStatus: StatusRegistry = {
  dsx: { label: '待生效', tagType: 'info' },
  sxz: { label: '生效中', tagType: 'success' },
  ygq: { label: '已过期', tagType: 'warning' },
  yzf: { label: '已作废', tagType: 'danger' },
  zky: { label: '转科研', tagType: 'primary' },
}

export const protocolStatusLabel = createLabelGetter(protocolStatus)
export const protocolStatusTagType = createTagTypeGetter(protocolStatus)

现有代码调用 protocolStatusLabel('dsx') 完全不变,零迁移成本。

6. 完整注册表分组

6.1 协议/捐赠/样本域

注册表名 枚举值 原散落文件数
protocolStatus dsx/sxz/ygq/yzf/zky 6
donationStatus dsx/sxz/ygq/yzf/zckc 3
sampleStatus ycj/jcz/yrk/yzf 3
payStatus dfj/jfqrz/yjf/tfqrz/ytf 3
auditStatus shtg/shth 2
acceptConclusion js/bj(jjj) 2
transportType kdys/ryxd 5+
sourceType direct/from_storage 1
newbornSex 1/0 6
deliveryMode sc/pgc 6

6.2 质检域

注册表名 枚举值 原散落文件数
qcBizType inbound/outbound 1
taskStatus dzx/jxz/ywc 1
taskType sysz/dsfjc 1
qcConclusion tg/btg 1
workOrderStatus dpz/ypz/ywc 1
receptionSource cell_storage/research_donation 1

6.3 渠道域

注册表名 枚举值 原散落文件数
channelType yy/hzjg/zs/zfjg/qt 2
agreementType kyxy/zsxy/lcxy 2
agreementStatus dsx/sxz/yzf 2
settlementType yj/jj/nj/dcjs 2

6.4 支付/通用域

注册表名 枚举值 原散落文件数
payMode dj/fq 2
transferType wxzz/zzbzz/yhkzz/xj 5+
enableStatus 1/0(通用启用/停用) 12+

6.5 系统域

注册表名 枚举值 原散落文件数
leaveStatus draft/pending/approved/rejected/cancelled 1
workflowStatus running/completed/rejected/cancelled/pending/approved/withdrawn 1
menuType M/C/F 1
userRole admin/supplier/client/deliver 1
dataScope 1-5 1
cleanRoomGrade A/B/C/D 1
sampleCodeType zxbm/qdbm 1
packType bzhcb/zdyhcb 1
paramType text/select/multi_select 2
orderStatus pending_payment/pending_confirm/completed/cancelled/... 1
deliveryStatus pending_dispatch/pending_delivery/delivering/delivered/... 1

7. 与现有文件的关系

现有文件 处理方式
utils/qc-labels.ts 所有函数迁移到 registry,原文件改为从 registry re-export(过渡期兼容)
utils/protocol-payment-labels.ts 标签函数迁移到 registry;formatPaymentAmount、isPaymentDueWithinWarnWindow、formatPaymentDueDate 等纯格式化函数保留原文件
21 个 Vue 文件中的本地函数 删除本地函数,改为从 registry 导入

8. 消灭自定义 Badge 系统

以下 3 个文件的自定义 .badge CSS 和 status-dot 全部替换为 <el-tag>:

文件 消灭内容
cell-storage/protocol/ProtocolViewDialog.vue .badge / badge--* → <el-tag>
research-donation/list/DonationViewDialog.vue .badge / badge--* / status-dot → <el-tag>
pilot-service/channel/ChannelViewDialog.vue .badge / badge--* → <el-tag>
components/business/sample-qc-info-cards/index.vue 内联 badge class → <el-tag>

替换后删除 <style scoped> 中的 .badge 相关 CSS 定义。

9. Tag Type 语义色规范

TagType 颜色 适用语义 示例
success 绿色 正常、启用、已完成、生效中、通过、已缴费 正常/启用/已完成/接收/通过/已入库
warning 橙色 进行中、待确认、已过期、预警 进行中/已排配/已过期/待确认/检测中
danger 红色 异常、已作废、拒绝、不通过、已退费 异常/已作废/拒绝/不通过/已退费
info 灰色 待执行、待生效、停用、默认 待执行/待生效/停用/无结论/其他
primary 蓝色 特殊分类、来源类型、转出 转科研/医院/框架协议/已采集
'' 默认色 无特殊语义 目录类型

10. 迁移策略

分 3 波执行,每波可独立验证:

波次 1:核心(质检 + 协议状态 + Badge 消灭)

  • 创建 status-tag-registry.ts
  • 迁移质检域 6 组 + 协议/支付域 4 组
  • 消灭 ProtocolViewDialog、DonationViewDialog 的 badge 系统
  • 迁移 qc-labels.ts 的 re-export
  • 涉及约 12 个文件

波次 2:捐赠 + 渠道

  • 迁移捐赠域 5 组 + 渠道域 4 组
  • 消灭 ChannelViewDialog 的 badge 系统
  • 涉及约 8 个文件

波次 3:系统 + 通用 + 订单

  • 迁移通用启用/停用、系统域、订单域等
  • 消灭 sample-qc-info-cards 的 badge 系统
  • 迁移 protocol-payment-labels.ts 标签部分为 re-export
  • 涉及约 15 个文件

11. 验收标准

  1. status-tag-registry.ts 覆盖所有 30+ 组枚举映射
  2. 项目中不存在自定义 .badge--* CSS 类
  3. 项目中不存在本地定义的 xxxStatusLabel / xxxTagType 函数(除 re-export 文件外)
  4. 所有状态/结论/类型字段在表格和查看弹窗中颜色完全一致
  5. LSP 诊断零错误
  6. 现有页面功能无回归