提交
This commit is contained in:
zlwu committed
1 parent
3779de12ce
commit
fb85230d25
25 files changed
+6003
-234
No files matched your search
@@ -575,23 +575,20 @@ import { Plus, Close, Check, Search, RefreshLeft, Edit, Delete, View } from '@el
|
||||
</el-table-column>
|
||||
```
|
||||
|
||||
**多状态映射标准写法（使用辅助函数）：**
|
||||
**多状态映射标准写法（使用状态标签注册表）：**
|
||||
|
||||
```html
|
||||
<el-table-column prop="workOrderStatus" label="状态" width="100" align="center">
|
||||
<template #default="{ row }">
|
||||
<el-tag :type="statusTagType(row.workOrderStatus)" size="small">
|
||||
{{ statusLabel(row.workOrderStatus) }}
|
||||
<el-tag :type="workOrderStatusTagType(row.workOrderStatus)" size="small">
|
||||
{{ workOrderStatusLabel(row.workOrderStatus) }}
|
||||
</el-tag>
|
||||
</template>
|
||||
</el-table-column>
|
||||
```
|
||||
|
||||
```typescript
|
||||
function statusTagType(s: string): string {
|
||||
const m: Record<string, string> = { ywc: 'success', ypz: 'warning', dpz: 'info' }
|
||||
return m[s] || 'info'
|
||||
}
|
||||
import { workOrderStatusLabel, workOrderStatusTagType } from '@/utils/status-tag-registry'
|
||||
```
|
||||
|
||||
#### 2. 查看弹窗（SystemViewDialog）中的 Tag 展示
|
||||
@@ -615,13 +612,15 @@ export interface ViewField {
|
||||
**标准写法：**
|
||||
|
||||
```typescript
|
||||
import { taskStatusLabel, taskStatusTagType, qcTaskConclusionLabel, qcTaskConclusionTagType } from '@/utils/status-tag-registry'
|
||||
|
||||
const viewSections = computed<ViewSection[]>(() => [
|
||||
{
|
||||
title: '任务信息',
|
||||
fields: [
|
||||
{ label: '任务号', value: d.taskNo },
|
||||
{ label: '状态', value: statusLabel(d.status), tagType: d.status === 'ywc' ? 'success' : d.status === 'jxz' ? 'warning' : 'info' },
|
||||
{ label: '检测结论', value: conclusionLabel(d.conclusion), tagType: d.conclusion === 'tg' ? 'success' : d.conclusion === 'btg' ? 'danger' : 'info' },
|
||||
{ label: '状态', value: taskStatusLabel(d.status), tagType: taskStatusTagType(d.status) },
|
||||
{ label: '检测结论', value: qcTaskConclusionLabel(d.conclusion), tagType: qcTaskConclusionTagType(d.conclusion) },
|
||||
// 普通字段不加 tagType，仍以纯文本展示
|
||||
{ label: '备注', value: d.remark || '—', span: true },
|
||||
]
|
||||
@@ -637,12 +636,16 @@ const viewSections = computed<ViewSection[]>(() => [
|
||||
|
||||
```html
|
||||
<dd>
|
||||
<el-tag :type="row.acceptConclusion === 'js' ? 'success' : 'danger'" size="small">
|
||||
<el-tag :type="acceptConclusionTagType(row.acceptConclusion)" size="small">
|
||||
{{ acceptConclusionLabel(row.acceptConclusion) }}
|
||||
</el-tag>
|
||||
</dd>
|
||||
```
|
||||
|
||||
```typescript
|
||||
import { acceptConclusionLabel, acceptConclusionTagType } from '@/utils/status-tag-registry'
|
||||
```
|
||||
|
||||
#### 4. Tag 类型语义色映射规范
|
||||
|
||||
| Tag Type | 颜色 | 适用语义 | 示例 |
|
||||
@@ -655,9 +658,72 @@ const viewSections = computed<ViewSection[]>(() => [
|
||||
|
||||
**对于启用/停用的状态字段**，SHALL 使用 `success`（启用）和 `info`（停用），SHALL NOT 使用 `danger` 表示停用状态。
|
||||
|
||||
#### 5. 公共标签映射函数
|
||||
#### 5. 状态标签注册表（集中定义 label + tagType）
|
||||
|
||||
多个页面复用的状态标签映射 SHALL 抽取为公共工具函数（如 `utils/protocol-payment-labels.ts`、`utils/qc-labels.ts`），同时提供 `xxxLabel`（文本）和 `xxxTagType`（tag type）两个配套函数。仅单个页面使用的状态标签 SHALL 在页面 `<script setup>` 中定义。
|
||||
`web-admin` 中所有状态、结论、类型等枚举字段的 **文案（label）与 Tag 语义色（tagType）SHALL 在单一注册表中集中定义**，权威文件为 `web-admin/src/utils/status-tag-registry.ts`。
|
||||
|
||||
**核心原则：**
|
||||
|
||||
1. **同一枚举值全局一致**：同一枚举 code 在列表、查看弹窗、导出、嵌套子列表等任何展示位置，SHALL 使用相同的 label 与 tagType；SHALL NOT 在页面内用三元表达式或局部 `Record` 重复定义映射。
|
||||
2. **成对导出**：每个枚举域 SHALL 导出 registry 对象及配套的 `xxxLabel(code)`、`xxxTagType(code)` 两个 getter；未知 code 时 label 回退为原值、`tagType` 回退为 `'info'`。
|
||||
3. **新增枚举先注册后使用**：新增业务枚举时，SHALL 先在 `status-tag-registry.ts` 追加 registry 与 getter，再在页面/组件中 import 使用；SHALL NOT 直接在 `.vue` 中写 `if/else` 或内联映射。
|
||||
4. **域内分组**：registry 内按业务域分区维护（协议/存储、质检、渠道、订单、系统通用等），便于检索与 code review。
|
||||
|
||||
**注册表结构（已实现）：**
|
||||
|
||||
```typescript
|
||||
/** el-tag 的 type 属性值 */
|
||||
export type TagType = 'success' | 'warning' | 'danger' | 'info' | '' | 'primary'
|
||||
|
||||
export interface StatusItem {
|
||||
label: string
|
||||
tagType: TagType
|
||||
}
|
||||
|
||||
export type StatusRegistry = Record<string, StatusItem>
|
||||
|
||||
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)
|
||||
```
|
||||
|
||||
**页面使用方式：**
|
||||
|
||||
```typescript
|
||||
import { protocolStatusLabel, protocolStatusTagType } from '@/utils/status-tag-registry'
|
||||
```
|
||||
|
||||
```html
|
||||
<el-tag :type="protocolStatusTagType(row.status)" size="small">
|
||||
{{ protocolStatusLabel(row.status) }}
|
||||
</el-tag>
|
||||
```
|
||||
|
||||
**兼容 re-export（非新增入口）：**
|
||||
|
||||
`utils/protocol-payment-labels.ts`、`utils/qc-labels.ts` 等历史文件 MAY 继续 re-export 注册表中的 getter 以保持既有 import 路径；**新增枚举 SHALL 直接写入 `status-tag-registry.ts`**，SHALL NOT 再新建独立的 label/tag 映射文件。
|
||||
|
||||
**禁止写法：**
|
||||
|
||||
- 页面 `<script setup>` 内定义 `function xxxTagType()` / `const xxxMap = { ... }` 映射已在或应在注册表中的枚举
|
||||
- 查看弹窗 `ViewField.tagType` 使用内联三元表达式（如 `d.status === 'ywc' ? 'success' : ...`）替代 registry getter
|
||||
- 同一枚举在不同页面使用不同 tagType
|
||||
|
||||
#### Scenario: 新增业务枚举的状态展示
|
||||
|
||||
- **WHEN** 新增页面需展示新的状态/结论/类型枚举字段
|
||||
- **THEN** 开发者 SHALL 先在 `status-tag-registry.ts` 注册该枚举的 label 与 tagType，并在页面中 import 对应的 `xxxLabel` / `xxxTagType` getter 使用
|
||||
|
||||
#### Scenario: 复用已有枚举的状态展示
|
||||
|
||||
- **WHEN** 页面需展示已在注册表中定义的枚举（如 `protocolStatus`、`taskStatus`、`enableStatus`）
|
||||
- **THEN** 页面 SHALL 直接从 `@/utils/status-tag-registry` import 并使用，SHALL NOT 在页面内重复定义映射
|
||||
|
||||
#### Scenario: 新增列表页包含状态列
|
||||
|
||||
@@ -672,7 +738,7 @@ const viewSections = computed<ViewSection[]>(() => [
|
||||
#### Scenario: Code review Tag 展示
|
||||
|
||||
- **WHEN** PR 修改列表页或查看弹窗中的状态/结论/类型字段展示
|
||||
- **THEN** 审查者 SHALL 确认使用 `<el-tag>` 组件（表格列）或 `tagType` 属性（SystemViewDialog），SHALL NOT 出现纯文本状态展示或自定义 `<span class="tag">`
|
||||
- **THEN** 审查者 SHALL 确认使用 `<el-tag>` 组件（表格列）或 `tagType` 属性（SystemViewDialog），SHALL NOT 出现纯文本状态展示或自定义 `<span class="tag">`；若枚举已在或应进入注册表，SHALL 确认映射来自 `status-tag-registry.ts` 而非页面内联定义
|
||||
|
||||
### Requirement: 嵌套弹窗与子弹窗内列表风格一致
|
||||
|
||||
@@ -701,3 +767,108 @@ const viewSections = computed<ViewSection[]>(() => [
|
||||
- **WHEN** PR 在弹窗、侧栏详情或嵌套面板中新增或修改 `el-table`
|
||||
- **THEN** 审查者 SHALL 确认未使用 `size="small"` / 紧凑字号覆盖，且列表风格与主列表页一致
|
||||
|
||||
### Requirement: web-admin 界面模式索引与参考页选型
|
||||
|
||||
`web-admin` 新增或改造业务页面时，开发者 SHALL 在编码前按 **功能特征 → 模式编号（P01–P27）→ 参考页** 完成界面选型；模式定义、决策表、各模式标准写法与全站页面映射的**详细说明**以 `docs/web-admin-ui-pattern-index.md` 为权威索引，本 Requirement 给出 SHALL 级门禁与摘要。
|
||||
|
||||
**选型流程（SHALL 按序执行）：**
|
||||
|
||||
1. 对照下方「功能特征 → 模式」决策表或索引文档 §二，确定模式编号（如 P01、P12）。
|
||||
2. 打开该模式对应的 **Demo 模板页** 或 **业务参考页**（Hash + 源码路径见索引文档 §三）。
|
||||
3. 复制页面骨架与交互模式，替换 API、字段、`menuCode`；**SHALL NOT** 从零设计布局或另起一套类名习惯。
|
||||
4. 枚举字段 SHALL 注册至 `status-tag-registry.ts`（见本 spec「状态标签注册表」Requirement）。
|
||||
|
||||
**官方 Demo 模板（永远优先对照，SHALL 优先于业务页）：**
|
||||
|
||||
| 用途 | Hash | 源码 |
|
||||
|------|------|------|
|
||||
| 标准列表 CRUD | `/#/demo/unit` | `web-admin/src/views/system/unit/index.vue` |
|
||||
| 复杂业务列表 | `/#/demo/order` | `web-admin/src/views/system/order/index.vue` |
|
||||
| 商品类 + 查看弹窗 | `/#/demo/product` | `web-admin/src/views/system/product/index.vue` |
|
||||
| 树形主数据 | `/#/demo/category` | `web-admin/src/views/system/category/index.vue` |
|
||||
| 用户类 CRUD | `/#/demo/user` | `web-admin/src/views/system/user/index.vue` |
|
||||
| 工作台说明 | `/#/demo/console` | `web-admin/src/views/dashboard/console/index.vue` |
|
||||
|
||||
**功能特征 → 模式编号（决策表）：**
|
||||
|
||||
| 功能特征 | 模式 | 首选参考 |
|
||||
|----------|------|----------|
|
||||
| 单表主数据，增删改查 + 分页 + 关键词筛选 | **P01** | `/#/demo/unit` → `basic-info/customer` |
|
||||
| 列表多状态，操作按钮随状态变化 | **P02** | `/#/demo/order` → `cell-storage/protocol-audit` |
|
||||
| 树形结构，父子级联，无分页 | **P03** | `/#/demo/category` → `system/dept` |
|
||||
| 左侧组织/分类树 + 右侧分页列表 | **P04** | `/#/demo/user` → `system/user` |
|
||||
| 同页上下两块表（类型 + 明细） | **P05** | `system/dict` |
|
||||
| 主表列表 + 弹窗内维护子表 | **P06** | `basic-info/collection-region` |
|
||||
| 批量生成编号/编码 + 下发/收回 | **P07** | `basic-info/sample-code` |
|
||||
| 列表顶部 Tab 按状态切换（非路由 Tab） | **P08** | `cell-storage/payment-info` |
|
||||
| 只读查看，字段分 Section（≤20 字段） | **P09** | `SystemViewDialog` → `system/express` |
|
||||
| 只读查看，多 Tab/KPI/审核历史/附件 | **P10** | `ProtocolViewDialog` / `DonationViewDialog` |
|
||||
| 简单审核/状态变更（单表单 ~560px） | **P11** | `ProtocolAuditDialog` |
|
||||
| 多分区大表单（Tab 锚点 + 行内子表） | **P12** | `ProtocolFormDialog` / `DonationFormDialog` |
|
||||
| 财务/业务确认（只读明细 + 上传附件） | **P13** | `cell-storage/payment-confirm` |
|
||||
| 主表 + 嵌套配置大弹窗（子资源 CRUD） | **P14** | `basic-info/insurance-company` |
|
||||
| 主表 + 多 Tab 子模块（渠道/协议等） | **P15** | `pilot-service/channel` |
|
||||
| 三栏：资源库 \| 步骤列表 \| 步骤详情 | **P16** | `production/process-route` |
|
||||
| 工单列表 + 派发/执行弹窗链 | **P17** | `production/production-work-order` |
|
||||
| 任务执行（虚拟步骤 + 步骤状态机） | **P18** | `TaskExecutionDialog` + `useTaskStepEditor` |
|
||||
| 主数据 + append-to-body 选择器弹窗 | **P19** | `production/process` |
|
||||
| 库存主数据 + 入库/出库 + 流水只读页 | **P20** | `production/consumable` + `material-stock-log` |
|
||||
| 质检工单/任务（配置检测项） | **P21** | `quality-inspection/qc-work-order` |
|
||||
| 审核列表 + 专用审核弹窗 | **P22** | `quality-inspection/storage-release-review` |
|
||||
| 接收/登记（关联协议样本） | **P23** | `quality-inspection/sample-reception` |
|
||||
| 工作流配置 / 待办 / 审批 | **P24** | `system/workflow/*` |
|
||||
| 独立详情页（非弹窗） | **P25** | `system/user/detail` |
|
||||
| 角色/权限扩展（菜单树/数据范围） | **P26** | `system/role` |
|
||||
| 衍生列表（跳转主业务查看弹窗） | **P27** | `cell-storage/storage-cert` |
|
||||
|
||||
**各模式 SHALL 级要点（摘要）：**
|
||||
|
||||
- **P01**：`page-head` → `filter-block` → `list-toolbar`（已选 N 项在前）→ `list-table stripe` → 分页；`dialog-form-layout` 编辑 + `SystemViewDialog` 查看。
|
||||
- **P02**：在 P01 基础上增加状态筛选、操作列多按钮、业务弹窗（审核/状态变更）。
|
||||
- **P03**：`el-table` 树形、无分页；路径展示遵循「树形主数据展示规则」Requirement。
|
||||
- **P04**：左 `el-tree` + 右 P01 列表；组织全路径用 `tree-path.ts`。
|
||||
- **P06**：主从平铺 + 子 API；**SHALL NOT** 误用树形主数据 UI。
|
||||
- **P07**：`/batch-generate`、`/batch-issue`、`/batch-revoke`；批量请求超时 SHALL ≥ 120s。
|
||||
- **P08**：`region-tabs` 切换列表筛选；各 Tab 可有不同批量操作。
|
||||
- **P09**：查看 SHALL 使用 `SystemViewDialog`；状态字段传 `tagType`。
|
||||
- **P10**：复杂查看 SHALL 使用独立 `*ViewDialog` 组件；与编辑弹窗 **同 Tab/section 命名**；只读附件复用 `ProtocolAttachmentReadonly` 等。
|
||||
- **P11/P22**：轻量审核弹窗 width ~560px；结论字段用 registry Tag。
|
||||
- **P12**：重表单 SHALL 拆为独立 `.vue` 组件；`DialogFormBody` + `detail-tabs` + `scroll-to-error`；附件卡片化布局遵循本 spec 附件 Requirement。
|
||||
- **P16**：三栏布局 SHALL 使用 `_route-config.scss` 的 `.route-config-*` 类；新三栏场景 SHALL 复用 `useTaskStepEditor` + `StepDetailPanel`，**SHALL NOT** 复制 `process-route` 内联逻辑。
|
||||
- **P17/P18**：工单/任务流 SHALL 对齐 `production-work-order` 弹窗链与 composable 模式。
|
||||
- **P27**：衍生列表查看 SHALL 打开主业务 ViewDialog（如 `ProtocolViewDialog`），**SHALL NOT** 重复实现完整查看 UI。
|
||||
|
||||
**维护约定：**
|
||||
|
||||
- 新增页面落地后，SHALL 在 `docs/web-admin-ui-pattern-index.md` §四补充「页面 → 模式」映射。
|
||||
- 出现现有 P01–P27 无法覆盖的新交互形态时，SHALL 先在索引文档新增模式编号与参考页，再更新本 Requirement 决策表。
|
||||
|
||||
#### Scenario: 新增标准主数据页
|
||||
|
||||
- **WHEN** 新增单表 CRUD 主数据页（如供应商、配置项）
|
||||
- **THEN** 开发者 SHALL 选定模式 **P01**，以 `/#/demo/unit` 或 `basic-info/customer` 为骨架参考
|
||||
- **THEN** PR 描述或设计说明中 SHALL 注明所选模式编号与参考页路径
|
||||
|
||||
#### Scenario: 新增复杂业务或工单页
|
||||
|
||||
- **WHEN** 新增含多状态操作、工单派发、任务执行或三栏编辑的页面
|
||||
- **THEN** 开发者 SHALL 从 P02、P16、P17、P18、P21 等决策表中选定模式，并对照索引文档 §三对应参考页实现
|
||||
- **THEN** SHALL NOT 仅参照 P01 标准列表强行裁剪复杂交互
|
||||
|
||||
#### Scenario: 新增重表单或专用查看弹窗
|
||||
|
||||
- **WHEN** 新增字段多、需 Tab 分区或 KPI 的业务表单/查看
|
||||
- **THEN** 编辑 SHALL 采用 **P12**（独立 FormDialog 组件）；查看字段极多 SHALL 采用 **P10**（专用 ViewDialog）
|
||||
- **THEN** SHALL NOT 在 `index.vue` 内堆叠超过 500 行表单/查看模板
|
||||
|
||||
#### Scenario: Code review 界面模式选型
|
||||
|
||||
- **WHEN** PR 新增或大幅改造 `web-admin` 业务页面
|
||||
- **THEN** 审查者 SHALL 确认 PR 注明模式编号（Pxx）及参考页
|
||||
- **THEN** 页面骨架、工具栏顺序、弹窗类名与参考页一致；若偏离 SHALL 有书面理由
|
||||
|
||||
#### Scenario: 索引文档与 OpenSpec 同步
|
||||
|
||||
- **WHEN** 新增 P28 或更高级别模式，或全站页面映射变更
|
||||
- **THEN** 维护者 SHALL 同步更新 `docs/web-admin-ui-pattern-index.md` 与本 Requirement 决策表
|
||||
|
||||
Reference in new issue
Block a user