# OFBiz Modern UI

`plugins/modern-ui` is the Vue 3 + Element Plus administrator UI for OFBiz. It provides the `/modern/app/` shell, domain workspaces, generated business-page renderer, ERP wrapper components, generated page assets, and verification artifacts.

This plugin is structurally broad, but it is not documented here as a fully signed-off replacement for every legacy OFBiz frontend behavior. Current status and remaining parity work are tracked in `MIGRATION_STATUS.md` and the verification reports.

## Read First

| Need | Document |
| --- | --- |
| What the administrator website delivers, how operators enter it, and what remains to sign off | `DELIVERY.md` |
| How to build pages, choose wrappers, call components, and organize layout/logic | `../../UI.md` |
| Product/design contract, visual rules, and completion boundary | `../../DESIGN.md` |
| Plugin-local usage notes | `UI.md` |
| Plugin-local design brief | `DESIGN.md` |
| Current migration status and true parity gap | `MIGRATION_STATUS.md` |
| App-local component handbook | `app/UI.md` |
| App-local design checklist | `app/DESIGN.md` |

## Code Map

| Concern | Path |
| --- | --- |
| SPA entry | `app/src/main.ts` |
| Route selection and login gate | `app/src/App.vue` |
| Global shell | `app/src/components/erp/ErpAppShell.vue` |
| Module catalog | `app/src/data/moduleCatalog.ts` |
| Generated business route | `app/src/views/BusinessPageView.vue` |
| PageDefinition renderer | `app/src/components/erp/ErpPageRenderer.vue` |
| Adapter/workspace dispatch | `app/src/components/erp/ErpAdapterBlock.vue` |
| ERP wrappers | `app/src/components/erp/*.vue` |
| API, action, lookup, option, entity, fallback services | `app/src/services/*.ts` |
| Tokens and style stack | `app/src/styles/erp-ui.css`, `tokens.css`, `element-overrides.css`, `erp-patterns.css`, `modern.css` |
| Generated assets served by the plugin | `webapp/modern/app/generated` |
| Verification reports and screenshots | `verification/` |

## Wrapper-First Rule

Business pages use Element Plus through ERP wrappers:

```text
PageDefinition / domain route
  -> ErpPageRenderer, ErpAdapterBlock, or domain workspace
  -> ErpSearchForm, ErpEntityForm, ErpDataTable, ErpActionBar, ErpStatusTag, ErpLookup, ErpUpload, ErpDrawer
  -> Element Plus primitives
```

Use direct Element Plus only for local primitives such as tabs, alerts, empty/loading states, dialogs, confirmations, descriptions, timelines, and small local buttons/tags. Do not scatter raw `el-form`, `el-table`, action strips, state colors, spacing, radius, shadows, or deep Element Plus overrides across business views.

## Styling Contract

- `app/src/styles/tokens.css` owns color, type, spacing, radius, control height, table density, and card density.
- `app/src/styles/element-overrides.css` maps Element Plus variables and base component behavior to ERP tokens.
- `app/src/styles/erp-patterns.css` owns reusable ERP form/table/panel/status/action/upload/detail patterns.
- `app/src/styles/modern.css` owns shell, route, generated-page, and domain layout composition.
- Business views may add local CSS only for narrow page placement, and must still use ERP tokens.

## Current Parity Boundary

Use the checked-in status artifacts for claims:

- Structural coverage is established for the scanned legacy view surface.
- The current migration status reports 1772 legacy view routes, 1767 unique generated pages, 0 unsupported block types, and 112 screenshots.
- The current parity artifact reports 46 verified business parity pages, 1721 pending business E2E pages, 876 high-risk pending pages, and 4 Accounting runtime-smoke pages.
- Generated renderability, adapter coverage, and screenshots do not prove all legacy side effects, report output, permission branches, validation, uploads, exports, POS/cart/payment, or JavaScript behavior are equivalent.

Safe wording: "structural coverage established", "Element Plus renderer coverage present", "ready for business E2E", and "representative runtime smoke passed".

Do not write "full parity complete", "全量业务等价完成", or "全量 OFBiz 前端等价重构已完成" unless the verification artifacts show no pending business E2E or high-risk parity work.

## Verification

Run these from `app/` when code or generated assets change:

```bash
npm run build
npm run verify:coverage
npm run verify:preview
npm run verify:parity
npm run verify:browser-runtime
```

Documentation-only changes do not require a build. At minimum, run an `rg` check against the edited docs to confirm they do not claim full parity as fact.