# OFBiz Element Plus 前端重构 Memory

更新时间：2026-06-10

## 🚫 硬规范：项目里绝不允许任何 emoji

任何 `.vue/.ts/.css` **不得出现 emoji**（含 📎👤📅🅣✅⚙️ 及 ▽◉☑▤▦↑↓ 这类几何符号当图标）。需要图标一律用 **Element Plus 官方图标库 `@element-plus/icons-vue`**（已全局注册；`:icon` 用法需 import）。**所有 build 子代理 prompt 必须带这条**。生成后用 emoji 范围正则扫 `src/` 确认零 emoji。详见 `~/.claude/projects/-Users-qiu-Desktop-ERP/memory/no-emoji-rule.md`。

## ⚠️ 重大转向（2026-06-10 晚）：ERP → 致远风格 OA 复刻

用户放弃 ERP 方向，要求把 `modern-ui/app` 原地改造成**致远 A6-V5 协同 OA 的复刻**（用我们自己的 Vue3 + Element Plus，不抄其后端）。已完成的状态：

- **参照系**：致远测试站 `http://222.240.1.170:99/seeyon/main.do`，账号 `cs`/密码 `kd123456`（通过 Claude in Chrome 扩展浏览器探索；致远"办理详情页"是重 iframe，扩展会卡，深页探索靠 OA 通用范式）。
- **OFBiz 账号**：37 个 UserLogin 密码全部改为 `ADMIN`（`{SHA}<hex>` 格式，已 enabled、清锁定）。admin/ADMIN 可真登录（仅 ERP 时代用；OA 现已无登录门禁）。
- **备份**：ERP 旧版前端在 `/Users/qiu/Desktop/ERP/backups/erp-modern-ui-*.tar.gz`（含 modern-ui+modern-api 源码，可恢复）。
- **契约文件**：`plugins/modern-ui/OA-SPEC.md`（功能/页面/布局规格）、`app/src/data/oaModules.ts`（9 模块+子页+空间+快捷的权威目录）。
- **新架构**：`src/oa/OaAppShell.vue`（OA 形态外壳：顶部模块导航+hover 下拉+空间切换+工具栏+快捷条，固定布局只内容滚动）、`src/oa/portal/OaPortalPage.vue`（个人空间门户）、`src/oa/OaGenericPage.vue`（9 种页面原型 fallback 渲染器）、`src/oa/OaContactsPage.vue`（通讯录）。路由 `src/router/index.ts` 用 `import.meta.glob('../oa/pages/**/*.vue')` 自动挑选 `src/oa/pages/<模块>/<key>.vue`，缺失则回退 OaGenericPage —— **加页面只需放文件，无需改路由**。`App.vue` 直接挂 OaAppShell（无 OFBiz 会话门禁）。
- **已建模块**（47 个页面文件，子代理并发）：collab/meeting/goal/knowledge/doccollab/culture/hr/report/appdev 全部子页 + 各自本地 mock 数据（无后端，占位数据）。
- **已删**：全部 ERP `*AdminView.vue`、`Erp*Workspace.vue`、`ErpDomainAdminView/ErpPageRenderer/ErpAdapterBlock/ErpCommerceSurface`、`ErpAppShell.vue`、`moduleCatalog.ts`。**保留**：ErpDataTable/ErpSearchForm/ErpTabbedDataPanel/ErpStatusTag/ErpDrawer/ErpPageHeader/ErpActionBar/ErpLookup/fieldOptions、styles、services、types、appContext、LoginView/LoginRedirectView/NotFoundView。
- **验证**：`npm run build` 绿；headless 启动自检 19/19 路由干净渲染（无 console 错误）。用户**不要截图验证**，自己看后台。
- **下一步可做**：逐页对照致远细化字段/交互、补 OA 后端（之前 BACKEND.md 分析过 OFBiz 的 WorkEffort/Content/Party/Communication 可覆盖部分 OA）、深页（办理详情流程轨迹等）精修。

### 二次深扒 + 引擎复刻（2026-06-10 更晚）
深扒确认：**致远 OA 本质 = 表单引擎 + 流程引擎 + 低代码设计器**（详见 OA-SPEC.md 第 5 节）。待办/已办只是"表单实例在审批流流转"的结果。已复刻：
- `src/oa/engine/`：`types.ts`（FormSchema 字段+网格行+明细子表 / FlowSchema 节点+审批/知会/协同+并行 parallels / FormTemplate）、`OaFormRenderer.vue`（致远式表格网格表单，13 种字段+人员/部门选择+附件+明细子表加行；readonly=预览）、`OaFlowDiagram.vue`（横向节点流程图+并行框+缩放）、`OaProcessSpecModal.vue`（"流程说明书"弹窗，表单/流程/流程使用说明书三页签）、`OaCreateItemDialog.vue`（新建事项模板选择器：分类树+模板卡 预览/使用）、`store.ts`（前端 mock 提交store）、`templates/`（10 张样板：保函付款申请单【精确复刻表单+11节点含并行流程】/费用报销/请假/用印/通用/供应商准入/出差/采购合同会签/付款/加班）。
- `src/oa/designer/`：`OaFormDesigner.vue`（三栏低代码表单设计器：字段面板+表格网格画布+属性面板）、`OaFlowDesigner.vue`（流程设计器：加节点/选类型/连线/并行）。挂在 `应用定制平台/应用管理中心`（appdev/appmgr）。
- `pages/appdev/workbench.vue`=CAP 落地页（banner+环图统计 表单总数248 等+三入口）。`pages/collab/create.vue`=新建事项发起器。
- 验证：`npm run build` 绿；headless 自检 19/19 + 引擎实拍（表单预览=表格网格+子表、说明书、表单设计器）确认忠实复刻。仍 mock 数据、无后端（用户要求）。
- 截图存 `verification/oa-shots/`（eng-*.png 为引擎实拍）。脚本：`scripts/oa-bootcheck.mjs`（启动自检）、`oa-shots.mjs` / `oa-engine-shots.mjs`（截图）。
- 看：`#/oa/collab/create`（新建事项）、`#/oa/appdev/workbench`（CAP）、`#/oa/appdev/appmgr`（设计器）。

---
（以下为 ERP 时代的历史记录，已备份，保留供参考）

## 用户的核心要求

用户要把 Apache OFBiz 的原有 Web 前端整体重构为 Vue 3 + TypeScript + Element Plus 的现代 ERP 管理后台。

明确要求：

- 前端需要重构完，不能只是组件展示、预览页、套壳页面。
- 旧的 OFBiz FreeMarker / Widget 风格 UI 不作为最终 UI。
- 后端业务逻辑、权限、事务、service、entity 语义先不推翻，前端通过新 API / 元数据适配层接入。
- 功能必须全部具备，最终要达到可验收状态。
- 不需要兼容旧浏览器。
- 浏览器调用不需要再次请求权限，应该直接使用浏览器验证。
- 任务不要无限跑太久，但必须朝 100% 可验收推进。
- 可以使用最多 6 个子代理并发拆任务，模型配置按工作区约定使用 GPT-5.5 / x-high / fast 等能力。
- 误注入的 PCB 相关提示词需要忽略，不属于当前任务。

## 既定产品路线

目标架构：

- 新增或继续使用 `plugins/modern-ui` 作为生产级现代前端。
- 使用 Vue 3、TypeScript、Vite、Element Plus。
- 新前端入口为 `/modern/app/`。
- 旧 GET / HEAD HTML 页面入口最终导向现代 SPA。
- POST、API、下载、静态资源、登录、登出等非页面请求不得被错误拦截。
- 保留旧 OFBiz controller / widget / form / menu / screen XML 作为迁移元数据来源，直到新 UI 彻底具备业务等价能力。

设计系统方向：

- Element Plus 是基础组件库。
- 必须有 OFBiz ERP 专用的视觉系统，而不是直接使用 Element Plus 默认样式。
- 需要沉淀颜色、字号、间距、表格密度、状态色、按钮层级、导航规则、卡片规则、表单规则。
- UI 风格应该安静、耐用、专用，适合后台 ERP 长时间使用。
- 页面应该是业务工作台，而不是组件库展示站。

## 已经完成的主要工作

当前本地仓库：

- 工作区：`/Users/qiu/Desktop/ERP`
- OFBiz 仓库：`/Users/qiu/Desktop/ERP/ofbiz-framework`
- 现代前端：`/Users/qiu/Desktop/ERP/ofbiz-framework/plugins/modern-ui/app`
- 前端构建产物：`/Users/qiu/Desktop/ERP/ofbiz-framework/plugins/modern-ui/webapp/modern/app`
- 本地预览地址：`http://127.0.0.1:8080/modern/app/`

已经完成：

- 建立了生产方向的 `plugins/modern-ui` 前端应用。
- 将产品文案从“预览 / 组件展示 / lab / gallery”方向改为正式 ERP 管理后台语言。
- 新前端 shell 已使用正式产品语义，例如：
  - `OFBiz ERP`
  - `统一运营管理平台`
- 已经形成 Element Plus ERP wrapper 层和业务页面渲染结构。
- 已经存在或推进过的核心 UI 结构包括：
  - `ErpAppShell`
  - `ErpPageHeader`
  - `ErpPageRenderer`
  - `ErpAdapterBlock`
  - 业务工作台页面
  - 菜单 / 导航 / 页面区 / 动作区
  - 表单、表格、状态、业务块等封装
- 已经处理过部分动态文案泄漏问题：
  - 新增共享显示文本清洗工具：`plugins/modern-ui/app/src/utils/display.ts`
  - `businessCapabilityText(values, fallback)` 用于把动态 capability 转为产品可读文案。
  - Finance / Order / HumanRes 等 workspace 中直接暴露 `block.source` / `block.capabilities` 的风险已经被处理过一轮。
- 已经修正过截图验证中 portal create 页面误判的问题。

## 路由和覆盖情况

已有覆盖验证结果显示：

- `legacyViewRoutes: 1772`
- `uniquePageDefinitions: 1767`
- `renderedPages: 1767`
- `missingRoutes: 0`
- `missingActions: 0`
- `frontendRewriteCoverageGate: passed`

含义：

- 现代前端的结构性路由覆盖已经做到很大规模。
- 旧页面到新页面定义的映射检查没有缺失路由。
- action 映射检查没有缺失。

但需要特别注意：

- 这不等于完整业务深度等价已经完成。
- 当前仍有大量页面只是生成式 / 元数据式覆盖，还没有逐页完成深度业务验收。

## 已跑过的验证

在 `/Users/qiu/Desktop/ERP/ofbiz-framework/plugins/modern-ui/app` 下已经跑通过：

- `npm run build`
- `npm run verify:admin-site`
- `npm run verify:admin-product`
- `npm run verify:erp-renderer-copy`
- `npm run verify:browser-runtime-policy`
- `npm run verify:coverage`
- `npm run verify:business-e2e:batch`
- `npm run verify:browser-runtime`
- 部分截图验收，例如：
  - `MODERN_UI_SCREENSHOT_IDS=business-page-portal-create npm run verify:screenshots`

浏览器验证证据：

- 曾真实打开 `http://127.0.0.1:8080/modern/app/#/`
- 浏览器 runtime 验证无 console error
- 截图产物：
  - `/Users/qiu/Desktop/ERP/ofbiz-framework/plugins/modern-ui/verification/browser-runtime-admin.png`

`verify:business-e2e:batch` 的重要结果：

- `missingRoutes: 0`
- `missingActions: 0`
- `frontendReadyPages: 1767`
- `runtimeSmokePassed: 22`
- `runtimeSmokePassedWithLegacyUnavailable: 2`
- `runtimeSmokeFailed: 0`
- `fullBusinessParityVerified: false`

## 当前没有完成的部分

必须诚实记录：

- OFBiz 前端尚未达到“全部功能 100% 业务等价重构完成”。
- 当前报告中仍有：
  - `pendingBusinessParityPages: 1721`
  - `businessDepthParityGate: pending`
  - `mustNotClaim100PercentBusinessParity: true`
- 所以不能对用户说“整个 OFBiz 前端已经完全重构完并 100% 业务验收通过”。

当前准确表述应该是：

- 结构性前端重构覆盖已大幅完成。
- `/modern/app/` 现代 ERP 管理后台入口已经可运行。
- 路由 / action 覆盖检查为 0 missing。
- 核心构建、产品化文案、浏览器 runtime、部分截图和批量结构 e2e 已通过。
- 深度业务等价验收仍未完成，仍需继续推进。

## 2026-06-10 重大进展：后端测绘 + 专业级外壳重构（已完成并验证）

用户在本次会话明确两项决策：
- 旧前端：**立即物理删除旧 OFBiz UI**（已知代价：冻结 1721 页、之后无法再生成 inventory）。
- 重构：**外壳 + 逐域深度精修一起做**（最彻底）。

已完成（task 1 + task 2）：

1. **后端全面测绘** → `/Users/qiu/Desktop/ERP/ofbiz-framework/BACKEND.md`（690 行，19 个组件，已对真实仓库校验：1772 viewRoute / 7935 action / 3848 service / 1208 entity）。这是前端编码所对契约 + 删除边界的权威文档，删除/逐域工作前先读它。

2. **专业级外壳与导航重构**（替换"挤在一页、左侧纯文本链接堆叠、手写 hash 路由"）：
   - 引入 **vue-router 4（hash history）**，路由集中在 `src/router/index.ts`，与既有 `#/...` 链接完全兼容。
   - `src/App.vue` 改为薄壳：登录门禁 + `provide` 共享态（`src/appContext.ts` 的 SessionKey/NavigationKey/InventoryKey）+ `<ErpAppShell><RouterView/></ErpAppShell>`。
   - `ErpAppShell.vue` 重建为**专业级左侧 el-menu 折叠分组树**：核心业务 / 渠道与扩展（由 moduleCatalog 驱动，模块=el-sub-menu，子项=landing+quickPages）+ 运营工作台 + 系统治理；顶栏=折叠开关+面包屑+搜索+新建+待办+账号；支持折叠。
   - 选中态用**线性 left-bar（透明底，无圆角胶囊）**，符合用户审美与设计门禁。
   - 类名 `.modern-*` → `.erp-*`；登录品牌文案统一为 `OFBiz ERP / 统一运营管理平台`。
   - 适配 3 个取数视图：DashboardView/BusinessPageView 改 inject，ModuleWorkspaceView 用路由 props。

3. **验证套件已与新架构对齐**（原套件深度耦合旧 shell；用一个工作流 + 自己手改完成）：
   - 已重写 `verify-admin-runtime-policy.mjs`（运行时 DOM 策略：新 `.erp-*` 选择器 + 侧边栏 active 断言）。
   - `verify-admin-site.mjs` / `verify-admin-product.mjs` 经工作流重表达（路由断言改查 `router/index.ts` + 新增 `assertRouteMapsToView`，意图未弱化）。
   - `verify-erp-visual-policy.mjs`（线性导航 + 折叠 + 排除 display.ts 清洗器）、`verify-admin-shell.mjs`（新品牌文案）、capture/admin-runtime/preview（`.modern-shell__main`→`.erp-shell__main` 等选择器）均已修。

验证结果（全绿）：`npm run build`；7 个源码门禁全 PASS（admin-shell/admin-site/admin-product/modern-navigation/erp-visual-policy/browser-runtime-policy/erp-renderer-copy）；截图运行时策略 **41 个场景全过**（19 业务域 admin + 全部 workspace + security/system-operations/extension + 7 个业务页 + portal-create）。

复跑命令（服务器未起时，用静态预览 + mock 兜底）：

```bash
cd /Users/qiu/Desktop/ERP/ofbiz-framework/plugins/modern-ui/app
npm run build
nohup npx vite preview --port 4178 --host 127.0.0.1 >/tmp/erp-preview.log 2>&1 &
export CHROME_BIN="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
export MODERN_UI_BASE_URL="http://127.0.0.1:4178/modern/app/" MODERN_UI_SCREENSHOT_ALLOW_MOCK_FALLBACK=1
npm run verify:screenshots   # 不带 IDS=全部；login-door 在 mock 下不可用（需真实 OFBiz）
```

## 已知遗留（非外壳回归，留待后续）

- 截图场景 `business-page-portal-pages`（`#/pages/myportal__FindPortalPage`）内容文案未达断言（期望 `门户页面查询` 且不含 `插件应用`）。属 myportal 域 **内容/adapter 选择**问题，渲染器/页面定义我未改动、portal-create 正常、其余 41 场景全过——是 Phase 2 逐域内容项，不是 shell 回归。
- `login-door` 截图场景在 mock 兜底下不可用（mock 强制 authenticated），需真实 OFBiz 验证。

## 仪表盘瘦身（已完成）

DashboardView 已从"卡片墙"重写为安静工作台：经营数据 KPI 条（克制数字、无大数字 hero、无填充）+ 两列聚焦布局（待办队列/最近记录 | 系统健康与权限/快速检索），删除了与侧边栏重复的"ERP 模块目录"大网格、彩色竖线行、大数字卡片。新增 scoped 类 `erp-kpi/erp-row/erp-quick`。保留全部必需 section 锚点，仅删 `处理路径/当班入口/核心模块入口`（已同步更新 verify-admin-runtime / capture / verify-preview / admin-site / admin-product 的对应断言）。源码 7 门禁 + admin-workbench 运行时策略全过。

## 重要环境注意

- 本项目在 `~/Desktop` 下，受 macOS TCC 保护。若工具突然全部报 `Operation not permitted`（连之前能读的文件也读不了），是 **Claude 桌面版（/Applications/Claude.app，bundle com.anthropic.claudefordesktop）丢了"桌面文件夹/完全磁盘访问"权限**，需在系统设置→隐私与安全性里重新授予并重启 App。`tccutil reset` 在工具内无权限、改不了。

## 下一步（待办）

- Phase 2：基于 BACKEND.md 逐域深度精修 19 个业务域（字段/查询/按钮/提交/导出/上传/lookup/状态流转/权限），把 pendingBusinessParityPages 朝 0 推进。
- Phase 3：物理删除旧 OFBiz UI 表现层（先冻结 inventory 快照、严格保留 entity/service/Java/data 运行期后端、删后验证 OFBiz 启动 + modern-api 可达 + 前端 build）。

如继续推进后端 cutover 验证，可跑：

```bash
cd /Users/qiu/Desktop/ERP/ofbiz-framework
JAVA_HOME=/Users/qiu/Desktop/ERP/.jdks/jdk-17.0.19+10/Contents/Home ./gradlew --no-daemon test --rerun-tasks \
  --tests org.apache.ofbiz.webapp.control.ControlFilterTests \
  --tests org.apache.ofbiz.webapp.control.RequestHandlerTests \
  --tests org.apache.ofbiz.modernapi.core.ModernApiAuthFilterTests
```

## 关于“删除旧前端”的当前判断

用户要求“把原来的前端全部删除”。

当前没有物理删除旧 OFBiz Widget / FreeMarker / controller XML，原因：

- 这些旧文件仍作为自动迁移清单、页面定义、菜单、表单、动作、service 映射的元数据来源。
- 直接删除会破坏当前迁移器和等价映射的来源。

当前更安全的技术路线：

- 旧 UI 不作为最终用户入口。
- 旧文件暂时保留为迁移元数据。
- 新前端功能等价验收全部通过后，再进入物理删除或只读归档阶段。

## UI 方向沉淀

用户对 UI 的明确偏好：

- 不喜欢“待处理订单”那种左侧一条彩色竖线、中间大数字的卡片。
- 更喜欢安静底色、细边框、1px 分隔、颜色克制的后台 UI。
- 可以有大卡片 / 中卡片 / 小卡片三种尺寸，但风格应统一。
- 顶部菜单选中态不要圆角胶囊，底部 1px 线即可。
- 菜单组件、左侧菜单、顶部菜单、面包屑、表格、表单、弹窗、上传、状态、分页等都需要完整覆盖。
- 不要把所有组件塞在一页；应该拆成多页或业务路由。
- 每个组件 / pattern 应有展示示例和对应代码，最好像 tab 一样切换“示例 / 代码”。

## 需要继续推进的工作

建议下一步按优先级执行：

1. 修复 `verify:admin-runtime` 中旧文案断言。
2. 重跑 `npm run verify:admin-runtime`。
3. 重跑核心截图验收，例如 `core-admin`。
4. 用浏览器直接打开 `/modern/app/` 做当前 UI 视觉验收。
5. 对高频核心业务域继续做深度业务等价：
   - Order
   - Product
   - Accounting
   - Party
   - HumanRes
   - Content
   - Manufacturing
   - WorkEffort
   - WebTools
   - Ecommerce
   - WebPOS
6. 把 `pendingBusinessParityPages` 从 1721 持续降到 0。
7. 每个业务页面验收字段、查询、按钮、提交、导出、上传、lookup、状态流转、权限。
8. 最终才可以声明 100% 可验收。

## 给后续代理的注意事项

- 不要重复从零开始。
- 不要把 PCB 当成有效需求。
- 不要声称 100% 业务等价完成，除非新的验证报告明确显示 pending 为 0 且核心 e2e / 截图 / 浏览器验收通过。
- 不要为了满足“删除旧前端”而直接删掉 OFBiz 旧 XML / Widget / FreeMarker 元数据源。
- 继续工作时先看：
  - `/Users/qiu/Desktop/ERP/ofbiz-framework/plugins/modern-ui/app`
  - `/Users/qiu/Desktop/ERP/ofbiz-framework/plugins/modern-ui/app/scripts`
  - `/Users/qiu/Desktop/ERP/ofbiz-framework/plugins/modern-ui/verification`
  - `/Users/qiu/Desktop/ERP/DESIGN.md`
  - `/Users/qiu/Desktop/ERP/ofbiz-framework/plugins/modern-ui/app/UI.md`
- 完成任何声明前必须重新跑对应验证命令。