296 lines
11 KiB
Markdown
296 lines
11 KiB
Markdown
# shanxia2.0 Fresh Mint UI 对齐 — 总改造计划
|
||
|
||
> **基准**：zkxw/web-admin（中科兴皖）
|
||
> **目标**：shanxia2.0/web-admin（山峡化工）
|
||
> **日期**：2026-06-29
|
||
> **客户要求**：只改 UI，不影响功能；Portal 顶栏一级 + 左侧二三级菜单结构不变
|
||
|
||
---
|
||
|
||
## 一、背景与目标
|
||
|
||
两项目同源（Fresh Mint + Art Design Pro），shanxia 使用 **Portal 布局**（`MenuTypeEnum.PORTAL`），zkxw 使用 **TOP_LEFT + ArtMixedMenu**。交互与视觉应对齐 zkxw，壳层组件不同但 Token、内容区骨架一致。
|
||
|
||
**视觉权威**：`docs/web-admin-ui-spec-fresh-mint.md`
|
||
**模式选型**：`docs/web-admin-ui-pattern-index.md`（P01–P27）
|
||
|
||
---
|
||
|
||
## 二、改造边界（硬约束）
|
||
|
||
| 允许 | 禁止 |
|
||
|------|------|
|
||
| 全局 SCSS（`assets/styles/core/*.scss`） | 修改业务 `<script>` 逻辑 |
|
||
| Vue template 的 class / 属性 / 结构骨架 | 改 API、路由、权限、校验 |
|
||
| Portal 壳层样式微调（高度、颜色、WorkTab） | 替换 Portal 布局架构 |
|
||
| 从 zkxw 拷贝 Demo 模板页 | 整文件覆盖 `app.scss` |
|
||
| 文档与验收清单 | 跨端混色（web 勿用 `#0a9f6d`） |
|
||
|
||
**shanxia 保留项**（优于 zkxw，勿回退）：
|
||
- `SystemViewDialog` 四列 `ViewKvGrid`
|
||
- Portal 顶栏 + 侧栏交互结构
|
||
|
||
---
|
||
|
||
## 三、进度总览
|
||
|
||
```
|
||
Step 0 基线文档与对照页 ✅ 已完成
|
||
Step 1 全局 SCSS + Portal 壳层 ✅ 已完成
|
||
Step 1b WorkTab 最多 10 个标签 ✅ 已完成
|
||
Step 2 分模块 class 补齐 ✅ 已完成
|
||
Step 3 bx/db 模块样式收敛 ✅ 2026-06-29
|
||
Step 4 Demo 模板页 + 路由 ✅ 已完成
|
||
Step 5 CRM 旧布局整页改造 ✅ 已完成
|
||
Step 6 详情/统计/看板页查漏 ✅ 2026-06-29
|
||
Step 7 全量回归与收尾 ✅ 2026-06-29
|
||
```
|
||
|
||
**关联文档**：
|
||
|
||
| 文档 | 用途 |
|
||
|------|------|
|
||
| `2026-06-29-fresh-mint-content-ui-step0-1.md` | Step 0/1 改动明细与回归清单 |
|
||
| `2026-06-29-fresh-mint-step2-module-plan.md` | Step 2 逐页勾选表（执行中更新） |
|
||
|
||
---
|
||
|
||
## 四、各 Step 详细说明
|
||
|
||
### Step 0 — 基线文档 ✅
|
||
|
||
**产出**：对照页、功能回归清单、改造边界
|
||
**对照页**（每模块抽 1 页视觉 + 功能基准）：
|
||
|
||
| 模块 | 路径 |
|
||
|------|------|
|
||
| 系统 | `views/system/user/index.vue` |
|
||
| CRM | `views/crm/customer/index.vue` |
|
||
| PL | `views/pl/plan/index.vue` |
|
||
| 报销 | `views/bx/reimburse/apply/index.vue` |
|
||
| 地磅 | `views/db/weighing/index.vue` |
|
||
|
||
---
|
||
|
||
### Step 1 — 全局 SCSS + Portal 壳层 ✅
|
||
|
||
**已改文件**：
|
||
|
||
| 文件 | 要点 |
|
||
|------|------|
|
||
| `fresh-mint-tokens.scss` | `--primary` 别名、`--mint-success-*` |
|
||
| `el-light.scss` / `el-ui.scss` | success `#059669`、表头 muted、primary 色阶 |
|
||
| `app.scss` | 筛选 label 11px、弹窗顶对齐、Portal 兜底 |
|
||
| `style.portal.scss` | 顶栏 56px |
|
||
| `art-portal-header` / `art-portal-top-nav` | 一级模块卡片样式 |
|
||
| `art-sidebar-menu/theme.scss` | 选中绿底白字 |
|
||
| `art-work-tab/index.vue` | padding 对齐 |
|
||
|
||
**未改**：`main.ts` 的 `ElTable border: true`（与 zkxw 一致）
|
||
|
||
---
|
||
|
||
### Step 1b — WorkTab 上限 ✅
|
||
|
||
**文件**：`store/modules/worktab.ts`
|
||
**规则**：`MAX_OPEN_TABS = 10`；新开前淘汰最早**未固定** tab；全固定且满 10 则拒绝新开。
|
||
|
||
---
|
||
|
||
### Step 2 — 分模块 class 补齐 ✅（基本完成）
|
||
|
||
**原则**：只改 template；不改 script。
|
||
|
||
**单页检查清单**（每改一页勾选）：
|
||
|
||
- [ ] `h2.title-bar-heading`（列表主标题竖条）
|
||
- [ ] 筛选搜索/重置 `:loading="loading"`
|
||
- [ ] 工具栏「已选 N 项」置前；批量操作带 `<el-icon>`
|
||
- [ ] 状态/类型列 `<el-tag size="small">`
|
||
- [ ] 弹窗 `dialog-form-layout` + `label-position="top"`
|
||
- [ ] 操作列 `fixed="right"`，min-width ≥ 260px
|
||
- [ ] 表格列用 `min-width` 而非 `width`
|
||
|
||
**模块完成情况**：
|
||
|
||
| 模块 | 页面数 | 状态 | 备注 |
|
||
|------|--------|------|------|
|
||
| system | 14 | ✅ | tenant～workflow 全部完成 |
|
||
| CRM 列表 | 10 | ✅ | 见 Step 5 遗留 3 页 |
|
||
| bx | 12 | ✅ | 此前已对齐 |
|
||
| db | 4 | ✅ | plans/inventory/weighing/dashboard |
|
||
| PL | 17+ | ✅ | 含 freight 子 Panel |
|
||
|
||
**Step 2 遗留**（转入 Step 5/6）：
|
||
|
||
| 路径 | 原因 |
|
||
|------|------|
|
||
| `crm/contract/template/index.vue` | 旧 RuoYi `app-container` + `el-card` |
|
||
| `crm/contract/change/index.vue` | 同上 |
|
||
| `crm/contract/approval/index.vue` | 同上 |
|
||
| `crm/opportunity/kanban.vue` | 旧布局 |
|
||
| `crm/opportunity/funnel.vue` | 旧布局 |
|
||
| `crm/opportunity/statistics.vue` | 旧布局 |
|
||
| `crm/contract/detail.vue` / `form.vue` | 详情/表单页待抽查 |
|
||
|
||
---
|
||
|
||
### Step 3 — bx / db 模块样式收敛 ✅（2026-06-29）
|
||
|
||
**目标**：减少页面私有 SCSS，统一走全局 Token + 模块入口。
|
||
|
||
| 序号 | 任务 | 文件 | 状态 |
|
||
|------|------|------|------|
|
||
| 3.1 | bx 样式审计 | `src/styles/bx/index.scss` | ✅ 删除 :root/独立 layout/与 app 重复规则，1936→955 行 |
|
||
| 3.2 | bx 附件样式 | `src/styles/bx/attachment.scss` | ✅ 硬编码色值改 `--primary`/`--text` 等 Token |
|
||
| 3.3 | db 样式审计 | `src/styles/db-module.scss` | ✅ 统一 `--border`/`--text`/`--surface` |
|
||
| 3.4 | 页面 scoped 清理 | `views/bx/**/*.vue` | ✅ reimburse/apply、payment、reimburse/approve |
|
||
| 3.5 | 页面 scoped 清理 | `views/db/**/*.vue` | ✅ 无 scoped/硬编码色（已确认） |
|
||
|
||
**附带**：`fresh-mint-tokens.scss` 补充 `--text`/`--border`/`--danger` 等 bx/db 语义别名，修复 bx 原 `--text-muted: #1e293b` 错误。
|
||
|
||
---
|
||
|
||
## Step 4 — Demo 模板页 + 路由 ✅（2026-06-29）
|
||
|
||
| 序号 | 项 | 状态 |
|
||
|------|-----|------|
|
||
| 4.1 | 工作台 `/#/demo/console` | ✅ |
|
||
| 4.2 | 标准列表 `views/demo/unit/index.vue` | ✅ |
|
||
| 4.3 | 复杂列表 `views/demo/order/index.vue` | ✅ |
|
||
| 4.4 | 商品 `views/demo/product/index.vue` | ✅ |
|
||
| 4.5 | 树形分类 `views/demo/category/index.vue` | ✅ |
|
||
| 4.6 | 用户 CRUD → `/demo/user`（复用 `system/user`） | ✅ |
|
||
| 4.7 | `product-view-dialog` 组件 | ✅ |
|
||
| 4.8 | 路由 `router/modules/demo.ts` | ✅ |
|
||
| 4.9 | Mock API `api/demo/*`（无后端） | ✅ |
|
||
|
||
**说明**：Demo 数据走 `src/api/demo/mock-api.ts` 内存 Mock；侧栏「Demo」菜单在 `VITE_ACCESS_MODE=frontend` 下自动可见。
|
||
|
||
---
|
||
|
||
### Step 5 — CRM 旧布局整页改造 ✅（2026-06-29）
|
||
|
||
| 页面 | 路径 | 状态 |
|
||
|------|------|------|
|
||
| 合同模板 | `views/crm/contract/template/index.vue` | ✅ |
|
||
| 合同审批记录 | `views/crm/contract/approval/index.vue` | ✅ |
|
||
| 合同变更 | `views/crm/contract/change/index.vue` | ✅ |
|
||
|
||
**改造要点**：`page-container` 骨架、Fresh Mint 筛选/工具栏/表格/分页、弹窗 `dialog-form-layout`、状态 `el-tag`、按钮带图标与 loading；业务逻辑与权限保持不变。
|
||
|
||
---
|
||
|
||
### Step 6 — 详情 / 统计 / 看板页查漏 ✅（2026-06-29）
|
||
|
||
| 类型 | 页面 | 状态 |
|
||
|------|------|------|
|
||
| 看板 | `crm/opportunity/kanban.vue` | ✅ Fresh Mint 筛选 + 看板 Token |
|
||
| 漏斗 | `crm/opportunity/funnel.vue` | ✅ stat-grid + chart-panel + 薄荷色 ECharts |
|
||
| 统计 | `crm/opportunity/statistics.vue` | ✅ 对齐 `clue/statistics` 骨架 |
|
||
| 详情 | `crm/contract/detail.vue` | ✅ panel-top + detail-toolbar 外壳 |
|
||
| 表单 | `crm/contract/form.vue` | ✅ panel-top 外壳 |
|
||
| 报价 | `crm/quote/detail.vue`、`form.vue` | ✅ 已是 Mint（Step 2 前已改造） |
|
||
| PL | `pl/plan/detail.vue`、`form.vue` | ✅ 已是 Mint（无需改动） |
|
||
|
||
---
|
||
|
||
### Step 7 — 全量回归与收尾 ✅（2026-06-29）
|
||
|
||
| 序号 | 任务 | 状态 |
|
||
|------|------|------|
|
||
| 7.1 | 功能回归清单（见第六节） | ✅ 代码审查 + 模块抽测路径已列 |
|
||
| 7.2 | 浏览器抽测 1366 / 1920 / 窄屏 | ⬜ 需人工在浏览器完成（见下表） |
|
||
| 7.3 | `pnpm build` | ✅ 通过（修复 `category-path-display` → `@/api/demo` 导入） |
|
||
| 7.4 | `step2-module-plan.md` | ✅ 各模块均已 ✅ |
|
||
| 7.5 | `./scripts/update-graph.sh all` | ✅ |
|
||
| 7.6 | OpenSpec 归档 | ⬜ 可选，未执行 |
|
||
|
||
**构建修复**：`utils/category-path-display.ts` 原从 `@/api/admin` 导入 Demo 专用 `fetchCategoryList`（Step 4 已迁至 `api/demo`），导致 Vite build 失败；已改为 `@/api/demo`。
|
||
|
||
**ESLint**：`pnpm lint` 仍有大量历史 Prettier/未使用变量告警（非本次 Fresh Mint 引入）；`pnpm build` 为发布门禁，已通过。
|
||
|
||
**建议浏览器抽测路径（每模块 1 页）**：
|
||
|
||
| 模块 | Hash 路由 | 验证点 |
|
||
|------|-----------|--------|
|
||
| Demo | `/#/demo/unit` | 列表 CRUD、弹窗两列、分页 |
|
||
| system | `/#/demo/user` | 多选、批量删除、权限按钮 |
|
||
| CRM | `/#/crm/customer` | 筛选 loading、Tag 状态 |
|
||
| CRM 看板 | `/#/crm/opportunity/kanban` | 看板滚动、卡片操作 |
|
||
| bx | `/#/bx/expense-item` | stats + 列表 + 弹窗 |
|
||
| db | `/#/db/weighing` | 日期快捷、表格 |
|
||
| PL | `/#/pl/plan` | 工具栏、操作列 fixed |
|
||
| WorkTab | 任意模块连开 11 页 | 最早未固定 tab 自动关闭 |
|
||
|
||
---
|
||
|
||
## 五、推荐执行顺序（给后续会话）
|
||
|
||
按**风险低 → 价值高**排列，每次会话完成 1～2 个 Step 或一个批次：
|
||
|
||
```
|
||
已完成 Step 0 → Step 1 → Step 1b → Step 2（列表页）
|
||
下一步 Step 4（Demo 模板，利于后续新页开发）
|
||
然后 Step 5.1 → 5.2 → 5.3（CRM 三页）
|
||
并行 Step 3（bx/db SCSS，可与 Step 5 交错）
|
||
随后 Step 6（看板/统计/详情）
|
||
最后 Step 7（全量回归）
|
||
```
|
||
|
||
**单次会话建议粒度**：
|
||
- 小：1 个 index.vue 的 Step 2 清单项
|
||
- 中：Step 5 中 1 个整页改造 + 回归
|
||
- 大：Step 4 全部 Demo 页（建议拆 2 次）
|
||
|
||
---
|
||
|
||
## 六、功能回归清单（每模块至少 1 页）
|
||
|
||
改造后必测（Step 7 代码审查已覆盖结构；浏览器勾选由人工完成）：
|
||
|
||
- [x] 列表：查询、重置、分页、排序、多选（各模块模板页已对齐）
|
||
- [x] 新增/编辑：弹窗 `dialog-form-layout`、按钮图标（Step 2/5/6）
|
||
- [x] 删除/批量：确认框 + 创建人限制工具（`creator-delete` 已接入）
|
||
- [x] 查看详情：Tag 语义色（OpenSpec ui-conventions）
|
||
- [x] 权限：`hasPermi` / `hasContractPerm` 等业务守卫保留
|
||
- [x] WorkTab：`MAX_OPEN_TABS = 10`（`store/modules/worktab.ts`）
|
||
- [ ] 浏览器实机：1366 / 1920 / 窄屏弹窗单列降级
|
||
|
||
---
|
||
|
||
## 七、风险与注意事项
|
||
|
||
1. **勿整文件覆盖 `app.scss`**：shanxia 含 bx/db/Portal 专用段落，仅 cherry-pick。
|
||
2. **creator-delete 合并**：批量删除注意 `handleDelete` 函数体 `{` 勿漏（曾出现语法错误）。
|
||
3. **双 loading 变量**：bx 部分页用 `searchLoading` / `pendingLoading`，保持一致即可。
|
||
4. **CRM 合同子页**：改造时保留 `hasContractPerm` 权限判断。
|
||
5. **graphify**：改 Vue/SCSS 后执行 `./scripts/update-graph.sh frontend`。
|
||
|
||
---
|
||
|
||
## 八、快速命令
|
||
|
||
```bash
|
||
# 前端开发
|
||
cd web-admin && pnpm dev
|
||
|
||
# 构建验证
|
||
cd web-admin && pnpm build
|
||
|
||
# 更新知识图谱
|
||
cd /Users/zlwu/work/00code/shanxia2.0 && ./scripts/update-graph.sh frontend
|
||
|
||
# 对照 zkxw 同路径文件
|
||
diff web-admin/src/views/pl/plan/index.vue ../zkxw/web-admin/src/views/pl/plan/index.vue
|
||
```
|
||
|
||
---
|
||
|
||
## 九、变更记录
|
||
|
||
| 日期 | 内容 |
|
||
|------|------|
|
||
| 2026-06-29 | Step 7：`pnpm build` 通过；graphify all；修复 category-path-display 导入 |
|
||
| 2026-06-29 | Step 2 system/CRM/bx/db/PL 列表页 class 补齐 |
|