cykj/shanxia2.0
1
0 Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
6a8cd90b98d1c94f7231a76cd3e7e4e0b0e76a3f
shanxia2.0/docs/superpowers/specs/2026-06-29-fresh-mint-master-plan.md
T
zlwu 7c838cfb2d 提交
2026-06-30 23:44:22 +08:00

11 KiB
Raw Blame History

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 代码审查已覆盖结构；浏览器勾选由人工完成）：

  • 列表：查询、重置、分页、排序、多选（各模块模板页已对齐）
  • 新增/编辑：弹窗 dialog-form-layout、按钮图标（Step 2/5/6）
  • 删除/批量：确认框 + 创建人限制工具（creator-delete 已接入）
  • 查看详情：Tag 语义色（OpenSpec ui-conventions）
  • 权限：hasPermi / hasContractPerm 等业务守卫保留
  • 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。

八、快速命令

# 前端开发
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 补齐
Reference in new issue View Git Blame Copy Permalink