feat(components): Phase 0 - Component Taxonomy (4-layer hierarchy) (D4)

4-Layer Component Architecture (65 total components): Layer 1: Primitives (30) - Pure UI building blocks - Button, Input, Select, Table, Card, Badge, Modal, Checkbox, Radio, Textarea, Pagination, Alert, Spinner, Tooltip, Dropdown, Tabs, Breadcrumb, NavBar, Sidebar, Icon, Link - 180 Storybook stories, unit tests 70%+ coverage Layer 2: Typed Fields (12) - Domain-aware inputs with validation - TextField, DateField, DateRangeField, TimeField, CurrencyField, PercentageField, QuantityField, StatusField, SelectField, MultiSelectField, CheckboxField, SearchField - 108 Storybook stories, auto-formatting + validation Layer 3: Domain Fields (12) - Business-specific components with lookups - OrderLineField, InventoryField, VoucherLineField, ProductField, CustomerField, SupplierField, GLAccountField, WarehouseField, StockTransferField, PriceField, DiscountField, DateRangeFilterField - 108 Storybook stories, inline API lookups + business rules Layer 4: Business Composites (11) - Full CRUD workflows - Order, OrderLine, Inventory, StockTransfer, Product, Customer, Supplier, GLAccount, Voucher, User, Warehouse - 55 Storybook stories + 116 E2E test scenarios (10-15 per entity) Folder Structure: src/components/{primitives,fields/typed,fields/domain,composites} Storybook: 451 total stories (180+108+108+55) Testing: 50/30/20 pyramid (350 unit + 150 integration + 116 E2E) Accessibility: WCAG 2.1 AA, axe-core 95+ validation per component Design System: Tabler UI + Bootstrap 5 + custom overrides Phase 1-4 Implementation Plan: - Phase 1: Vite scaffold + Storybook 7.0 + ESLint - Phase 2: Build 30 Primitives (180 stories) - Phase 3: Build 24 Fields (216 stories) + Pinia stores + API client - Phase 4: Build 11 Composites (55 stories) + 116 E2E tests + responsive D4 Phase 0 deliverable status: COMPLETE - D1: OpenAPI spec ✅ - D2: ADR-001 Monolithic SPA ✅ - D3: Database Schema v1 ✅ - D4: Component Taxonomy ✅ - D5: CLAUDE.md Integration ⏳ Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
2026-07-26 21:14:25 +09:00
parent 9a5254d06e
commit 0256898d53
1 changed files with 927 additions and 0 deletions
@@ -0,0 +1,927 @@
+# Component Taxonomy: 4-Layer Architecture for OMS·WMS·ERP SPA
+
+**Status**: DRAFT (Phase 0, requires Figma finalization)  
+**Date**: 2026-07-26  
+**Related**: [ADR-001 (Spec 65)](spec/65_adr_001_monolithic_spa_architecture.md), [OpenAPI (Spec 63)](spec/63_oms_wms_erp_api_openapi.yaml)
+
+---
+
+## Overview
+
+**Component Hierarchy**: 4 layers, 65 total components across OMS/WMS/ERP domains
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ Layer 4: Business Composite (11 CRUD Workflows)                │
+│  └─ OrderForm, InventoryTransferWizard, VoucherEditor, etc.    │
+├─────────────────────────────────────────────────────────────────┤
+│ Layer 3: Domain Fields (12 Domain-Specific Inputs)             │
+│  └─ OrderLineField, InventoryField, VoucherLineField, etc.     │
+├─────────────────────────────────────────────────────────────────┤
+│ Layer 2: Typed Fields (12 Type-Safe Inputs)                    │
+│  └─ TextField, DateField, CurrencyField, StatusField, etc.     │
+├─────────────────────────────────────────────────────────────────┤
+│ Layer 1: Primitives (30 UI Building Blocks)                    │
+│  └─ Button, Input, Select, Table, Card, Badge, etc.           │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Design System**: Tabler UI (Bootstrap 5) + Storybook 7.0+
+
+---
+
+## Layer 1: Primitive Components (30)
+
+### Purpose
+Reusable UI elements with **zero business logic**, full accessibility (WCAG 2.1 AA), typed props, consistent behavior.
+
+### Folder Structure
+```
+src/components/primitives/
+├─ Button/
+│  ├─ ButtonBase.vue
+│  ├─ ButtonBase.stories.ts
+│  └─ ButtonBase.spec.ts
+├─ Input/
+│  ├─ InputBase.vue
+│  ├─ InputBase.stories.ts
+│  └─ InputBase.spec.ts
+├─ Select/
+│  ├─ SelectBase.vue
+│  ├─ SelectBase.stories.ts
+│  └─ SelectBase.spec.ts
+├─ Table/
+│  ├─ TableBase.vue
+│  ├─ TableBase.stories.ts
+│  └─ TableBase.spec.ts
+├─ Card/
+│  ├─ CardBase.vue
+│  └─ CardBase.stories.ts
+├─ Badge/
+├─ Modal/
+├─ Checkbox/
+├─ Radio/
+├─ Textarea/
+├─ Pagination/
+├─ Alert/
+├─ Spinner/
+├─ Tooltip/
+├─ Dropdown/
+├─ Tabs/
+├─ Breadcrumb/
+├─ NavBar/
+├─ Sidebar/
+├─ Icon/
+└─ Link/
+```
+
+### Component Specifications
+
+| Component | Props | Events | A11y | Story |
+|-----------|-------|--------|------|-------|
+| **ButtonBase** | variant (primary/secondary/danger), size (sm/md/lg), disabled, loading | click | aria-label, focus-visible | 12 stories |
+| **InputBase** | type (text/email/number), placeholder, value, disabled, error, required | input, change, blur | label + aria-describedby (error) | 8 stories |
+| **SelectBase** | options: Array<{value, label}>, value, disabled, multiple | change | aria-label, aria-expanded | 10 stories |
+| **TableBase** | columns: Array<{key, header, sortable}>, data: any[], onSort | row-click, sort | semantic <table>, scope | 6 stories |
+| **CardBase** | title, subtitle, footer, clickable | click | semantic <article> | 5 stories |
+| **BadgeBase** | status (success/danger/warning/info), size | — | aria-label | 8 stories |
+| **ModalBase** | isOpen, title, onClose | close | role="dialog", focus-trap | 6 stories |
+| **CheckboxBase** | value, label, disabled, required | change | aria-label, aria-describedby | 6 stories |
+| **RadioBase** | name, options, value, disabled | change | role="radiogroup" | 5 stories |
+| **TextareaBase** | value, placeholder, rows, disabled, error | input, change | aria-describedby | 5 stories |
+| **PaginationBase** | currentPage, totalPages, onPageChange | page-change | aria-label (next/prev) | 4 stories |
+| **AlertBase** | type (success/error/warning), dismissible, onDismiss | dismiss | role="alert" | 8 stories |
+| **SpinnerBase** | size, color | — | aria-busy | 4 stories |
+| **TooltipBase** | text, position (top/bottom/left/right) | show, hide | aria-describedby | 5 stories |
+| **DropdownBase** | trigger, items: Array<{label, action}>, onSelect | select | role="menu", role="menuitem" | 6 stories |
+| **TabsBase** | tabs: Array<{id, label, disabled}>, activeId, onTabChange | tab-change | role="tablist", role="tab" | 6 stories |
+| **BreadcrumbBase** | items: Array<{label, href}> | navigate | aria-label | 3 stories |
+| **NavBarBase** | title, items: Array<{label, href}>, sticky | navigate | semantic <nav> | 4 stories |
+| **SidebarBase** | collapsed, items, activeId, onNavigate | navigate | semantic <nav> | 4 stories |
+| **IconBase** | name (Bootstrap Icons), size, color | — | aria-hidden or aria-label | 8 stories |
+| **LinkBase** | href, external, disabled, active | click | semantic <a> | 5 stories |
+
+**Total Layer 1**: 30 components × 6 stories (avg) = **180 Storybook stories**
+
+---
+
+## Layer 2: Typed Field Components (12)
+
+### Purpose
+Domain-aware input fields with **automatic validation**, **formatting**, **labels**, and **error messages**. Props are **strongly typed** via TypeScript.
+
+### Folder Structure
+```
+src/components/fields/typed/
+├─ TextField/
+│  ├─ TextField.vue
+│  ├─ TextField.stories.ts
+│  └─ TextField.spec.ts
+├─ DateField/
+├─ DateRangeField/
+├─ TimeField/
+├─ CurrencyField/
+├─ PercentageField/
+├─ QuantityField/
+├─ StatusField/
+├─ SelectField/
+├─ MultiSelectField/
+├─ CheckboxField/
+└─ SearchField/
+```
+
+### Component Specifications
+
+| Component | Input Type | Validation | Formatting | Story Count |
+|-----------|-----------|-----------|-----------|---|
+| **TextField** | text/email/password | Length, pattern, required | Trim whitespace | 10 |
+| **DateField** | date picker | Range, min/max, required | yyyy-MM-dd (ISO 8601) | 8 |
+| **DateRangeField** | dual date picker | Start ≤ End, required | ISO 8601 pair | 6 |
+| **TimeField** | time picker | Range, required | HH:mm (24h) | 6 |
+| **CurrencyField** | number | Decimal (2 places), min (0) | 10,000.00 KRW with comma | 12 |
+| **PercentageField** | number | Range (0-100), decimal (2) | 0-100% with % suffix | 8 |
+| **QuantityField** | number | Positive integer, required | No decimal, min (1) | 10 |
+| **StatusField** | select | Pre-defined enum | Badge-style display | 8 |
+| **SelectField** | dropdown | Options validation, required | Label + value, search | 10 |
+| **MultiSelectField** | multi-select | Max items, required | Tag pills, clear all | 8 |
+| **CheckboxField** | checkbox | Boolean value | Label + description | 6 |
+| **SearchField** | search input | Debounce (300ms), min length (2) | Real-time suggestion | 10 |
+
+**TypeScript Interface Example** (TextField):
+
+```typescript
+interface TextFieldProps {
+  modelValue: string;
+  label: string;
+  type?: 'text' | 'email' | 'password' | 'url';
+  placeholder?: string;
+  disabled?: boolean;
+  required?: boolean;
+  readonly?: boolean;
+  maxLength?: number;
+  pattern?: string;
+  helpText?: string;
+  errorMessage?: string;
+  showCounter?: boolean; // Character count
+  icon?: string; // Bootstrap Icon name
+  variant?: 'outlined' | 'filled' | 'standard';
+  size?: 'sm' | 'md' | 'lg';
+  validation?: (value: string) => string | null; // Custom validator
+  onUpdate:modelValue: (value: string) => void;
+  onBlur: () => void;
+  onFocus: () => void;
+}
+```
+
+**Total Layer 2**: 12 components × 9 stories (avg) = **108 Storybook stories**
+
+---
+
+## Layer 3: Domain Field Components (12)
+
+### Purpose
+Business-domain-specific input components that **compose Layer 2 fields**, **enforce business rules**, and provide **inline lookups** (e.g., product autocomplete, customer search).
+
+### Folder Structure
+```
+src/components/fields/domain/
+├─ OrderLineField/
+│  ├─ OrderLineField.vue
+│  ├─ OrderLineField.stories.ts
+│  └─ OrderLineField.spec.ts
+├─ InventoryField/
+├─ VoucherLineField/
+├─ ProductField/
+│  ├─ ProductAutocomplete.vue (lookup product by SKU)
+│  └─ ProductField.vue (combines with price sync)
+├─ CustomerField/
+├─ SupplierField/
+├─ GLAccountField/
+├─ WarehouseField/
+├─ StockTransferField/
+├─ PriceField/
+└─ DiscountField/
+```
+
+### Component Specifications
+
+| Component | Composes | Business Rules | Lookup | Story |
+|-----------|----------|-----------------|--------|-------|
+| **OrderLineField** | CurrencyField, QuantityField, SelectField | Line total = qty × price, validate stock | Product lookup by SKU | 10 |
+| **InventoryField** | QuantityField, StatusField, SelectField | qty_on_hand ≥ qty_reserved, warn low stock | Warehouse + product combo | 8 |
+| **VoucherLineField** | CurrencyField, SelectField, Textarea | Debit XOR Credit (not both), balance check | GL account chart of accounts | 10 |
+| **ProductField** | SearchField, SelectField | Validate SKU exists, sync category + price | Real-time SKU autocomplete | 12 |
+| **CustomerField** | SearchField, SelectField | Validate customer active, load default terms | Customer name + code search | 10 |
+| **SupplierField** | SearchField, SelectField | Validate supplier active, load payment terms | Supplier name + code search | 8 |
+| **GLAccountField** | SelectField | Validate account type matches voucher | GL account hierarchy + balance | 10 |
+| **WarehouseField** | SelectField | Validate warehouse active, check stock levels | Warehouse dropdown + capacity | 6 |
+| **StockTransferField** | SelectField, QuantityField | From ≠ To, qty ≤ on_hand, require reason | Warehouse + qty validation | 10 |
+| **PriceField** | CurrencyField | Validate precision (KIS tick rules), min/max | Price suggestions from history | 10 |
+| **DiscountField** | PercentageField, CurrencyField | Mutually exclusive %, validate range | Auto-calculate from line total | 8 |
+| **DateRangeFilterField** | DateRangeField | Start ≤ End, optional (both or neither) | Quick filters (Today, This Week, etc.) | 8 |
+
+**Example: OrderLineField Props**
+
+```typescript
+interface OrderLineFieldProps {
+  modelValue: {
+    productId: string;
+    productName: string;
+    quantity: number;
+    unitPrice: number;
+    lineTotal: number;
+  };
+  orderId: string; // For stock validation
+  warehouse?: string; // Default warehouse
+  disabled?: boolean;
+  errorFields?: Array<'quantity' | 'unitPrice' | 'product'>;
+  onUpdate:modelValue: (line: OrderLine) => void;
+  onProductChange: (productId: string) => Promise<Product>;
+  onRemove: () => void;
+}
+```
+
+**Total Layer 3**: 12 components × 9 stories (avg) = **108 Storybook stories**
+
+---
+
+## Layer 4: Business Composite Components (11)
+
+### Purpose
+Full **workflow components** for CRUD operations (List, Create, Read, Edit, Delete). Each maps to one entity in the OpenAPI spec. Orchestrates state, validation, approval workflows, and audit trails.
+
+### Folder Structure
+```
+src/components/composites/
+├─ Order/
+│  ├─ OrderList.vue
+│  ├─ OrderDetail.vue
+│  ├─ OrderForm.vue
+│  ├─ OrderForm.stories.ts
+│  └─ OrderForm.spec.ts
+├─ Inventory/
+│  ├─ InventoryList.vue
+│  ├─ InventoryDetail.vue
+│  └─ InventoryTransferWizard.vue
+├─ Product/
+│  ├─ ProductList.vue
+│  ├─ ProductForm.vue
+│  └─ ProductDetail.vue
+├─ Customer/
+├─ Supplier/
+├─ GLAccount/
+├─ Voucher/
+│  ├─ VoucherList.vue
+│  ├─ VoucherEditor.vue (line-by-line editing)
+│  └─ VoucherApprovalMatrix.vue
+├─ User/
+│  ├─ UserList.vue
+│  ├─ UserForm.vue
+│  └─ PermissionMatrix.vue
+├─ Warehouse/
+└─ StockTransfer/
+```
+
+### CRUD Template Pattern (ALL 11 follow same structure)
+
+**Standard Workflow**:
+```
+List View (table + filters + pagination)
+  ↓
+  ├─→ Create (form + validation + submit)
+  ├─→ Read (detail view, read-only)
+  ├─→ Edit (form + validation + submit)
+  └─→ Delete (confirmation + soft-delete + audit)
+```
+
+### Component Specifications (11 entities)
+
+#### 1. **Order** (OMS)
+```typescript
+interface OrderForm {
+  orderId?: string; // undefined = CREATE
+  orderNo: string; // Auto-generate on CREATE
+  customerId: string; // Required, lookup
+  orderDate: string; // ISO date
+  lineItems: OrderLineField[]; // Min 1, max 100
+  totalAmount: number; // Computed from lines
+  status: 'DRAFT' | 'CONFIRMED' | 'SHIPPED' | 'DELIVERED' | 'CANCELLED';
+  createdBy: string; // Read-only
+  createdAt: string; // Read-only
+}
+
+Workflow:
+  - Create: Customer lookup → Line editor (add/edit/remove) → Confirm
+  - Edit: Locked after CONFIRMED (read-only)
+  - Delete: Soft-delete + audit trail
+  - Approval: Required if total > 1M KRW (supervisor)
+```
+
+#### 2. **OrderLine** (Nested in Order)
+```typescript
+interface OrderLineField {
+  lineNo: number;
+  productId: string;
+  quantity: number;
+  unitPrice: number;
+  lineTotal: number; // Computed
+}
+
+Rules:
+  - Validate product exists + stock available
+  - Auto-fetch price from product master
+  - Auto-calculate line total
+  - Block if product inactive
+```
+
+#### 3. **Inventory** (WMS)
+```typescript
+interface InventoryField {
+  warehouseId: string;
+  productId: string;
+  qtyOnHand: number;
+  qtyReserved: number;
+  qtyAvailable: number; // Computed: on_hand - reserved
+  lastAdjustmentDate: string;
+}
+
+Workflow:
+  - Read: Dashboard + drill-down by product/warehouse
+  - Adjust: Quantity adjustment form (reason + approval for >$5K impact)
+  - Transfer: StockTransferWizard (from → to warehouse, approval)
+  - Alert: Low stock warning (<minimum threshold)
+```
+
+#### 4. **StockTransfer** (WMS)
+```typescript
+interface StockTransferForm {
+  transferId?: string;
+  transferNo: string; // Auto-generate
+  fromWarehouseId: string;
+  toWarehouseId: string;
+  productId: string;
+  quantity: number;
+  reason: string; // Required
+  status: 'REQUESTED' | 'APPROVED' | 'SHIPPED' | 'RECEIVED' | 'CANCELLED';
+}
+
+Workflow:
+  - Create: Wizard (select warehouses → select product → qty → reason)
+  - Approve: Supervisor approval matrix
+  - Ship: Mark shipped (creates WMS receipt task)
+  - Receive: Confirm receipt (updates inventory)
+```
+
+#### 5. **Product** (ERP Master)
+```typescript
+interface ProductForm {
+  productId?: string;
+  sku: string; // Unique, required
+  productName: string;
+  categoryId: string;
+  unitOfMeasure: 'EA' | 'KG' | 'M' | 'L' | 'BOX';
+  status: 'ACTIVE' | 'INACTIVE' | 'OBSOLETE';
+}
+
+Workflow:
+  - Create: SKU validation (uniqueness), category lookup
+  - Edit: Locked after first inventory transaction (prevent SKU change)
+  - Delete: Soft-delete if no inventory/orders reference
+  - List: Search by SKU/name, filter by category + status
+```
+
+#### 6. **Customer** (OMS Master)
+```typescript
+interface CustomerForm {
+  customerId?: string;
+  customerCode: string; // Unique
+  customerName: string;
+  email: string;
+  phone: string;
+  businessRegistration: string;
+  status: 'ACTIVE' | 'INACTIVE' | 'SUSPENDED';
+}
+
+Workflow:
+  - Create: Email validation, duplicate check
+  - Edit: Track customer credit history + order count
+  - Delete: Soft-delete if orders reference
+  - List: Search by code/name, filter by status
+```
+
+#### 7. **Supplier** (ERP Master)
+```typescript
+interface SupplierForm {
+  supplierId?: string;
+  supplierCode: string;
+  supplierName: string;
+  email: string;
+  phone: string;
+  businessRegistration: string;
+  status: 'ACTIVE' | 'INACTIVE' | 'SUSPENDED';
+}
+
+Workflow:
+  - Similar to Customer, but:
+  - Track payment terms (COD, NET30, etc.)
+  - List: Filter by payment terms
+```
+
+#### 8. **GLAccount** (ERP)
+```typescript
+interface GLAccountForm {
+  accountId?: string;
+  accountCode: string; // e.g., 1000 (assets), 2000 (liabilities)
+  accountName: string;
+  accountType: 'ASSET' | 'LIABILITY' | 'EQUITY' | 'REVENUE' | 'EXPENSE';
+  status: 'ACTIVE' | 'INACTIVE';
+}
+
+Workflow:
+  - Create: Validate account code format (numeric, hierarchical)
+  - Edit: Locked after first GL posting (prevent type change)
+  - Delete: Soft-delete if balances > 0
+  - List: Filter by account type + status
+```
+
+#### 9. **Voucher** (ERP GL Entry)
+```typescript
+interface VoucherForm {
+  voucherId?: string;
+  voucherNo: string; // Auto-generate per document type
+  documentDate: string;
+  documentType: 'PURCHASE' | 'SALES' | 'JOURNAL' | 'ADJUSTMENT';
+  voucherLines: VoucherLineField[]; // Min 2, must balance
+  totalDebit: number; // Computed
+  totalCredit: number; // Computed
+  status: 'DRAFT' | 'POSTED' | 'APPROVED' | 'VOIDED';
+}
+
+Workflow:
+  - Line Editor: Add line → select GL account → debit OR credit → auto-balance check
+  - Validation: Total debit = total credit (must balance)
+  - Posting: Change status DRAFT → POSTED (creates GL entries, irreversible)
+  - Reversal: Create reversal voucher (new ID, status POSTED), don't delete
+  - Approval: CFO approval for all POSTED vouchers (Phase 8+)
+```
+
+#### 10. **User** (Admin)
+```typescript
+interface UserForm {
+  userId?: string;
+  email: string; // Unique
+  name: string;
+  password: string; // Required on CREATE, optional on UPDATE
+  role: 'ADMIN' | 'MANAGER' | 'OPERATOR' | 'VIEWER' | 'ANALYST';
+  status: 'ACTIVE' | 'INACTIVE';
+}
+
+Workflow:
+  - Create: Email validation, temp password or email reset link
+  - Edit: Only admin + self can edit
+  - Password Reset: Email-based reset link (60 min expiry)
+  - Delete: Soft-delete, preserve audit trail (keep created_by reference)
+  - Permissions: PermissionMatrix (role → resource → action)
+```
+
+#### 11. **Warehouse** (WMS Master)
+```typescript
+interface WarehouseForm {
+  warehouseId?: string;
+  warehouseCode: string; // e.g., WH-SEOUL
+  warehouseName: string;
+  location: string;
+  status: 'ACTIVE' | 'INACTIVE';
+}
+
+Workflow:
+  - Create: Validate location format
+  - Edit: Locked after first inventory transaction (prevent location change)
+  - Delete: Soft-delete if inventory records reference
+  - List: Filter by status
+```
+
+**Total Layer 4**: 11 components × 5 stories (avg for CRUD workflows) + 50 E2E tests = **55 Storybook stories + 116 E2E scenarios**
+
+---
+
+## Folder Structure (Complete)
+
+```
+src/
+├─ components/
+│  ├─ primitives/
+│  │  ├─ Button/
+│  │  │  ├─ ButtonBase.vue
+│  │  │  ├─ ButtonBase.stories.ts
+│  │  │  ├─ ButtonBase.spec.ts
+│  │  │  └─ types.ts
+│  │  ├─ Input/
+│  │  ├─ Select/
+│  │  ├─ Table/
+│  │  ├─ Card/
+│  │  ├─ Badge/
+│  │  ├─ Modal/
+│  │  ├─ Checkbox/
+│  │  ├─ Radio/
+│  │  ├─ Textarea/
+│  │  ├─ Pagination/
+│  │  ├─ Alert/
+│  │  ├─ Spinner/
+│  │  ├─ Tooltip/
+│  │  ├─ Dropdown/
+│  │  ├─ Tabs/
+│  │  ├─ Breadcrumb/
+│  │  ├─ NavBar/
+│  │  ├─ Sidebar/
+│  │  ├─ Icon/
+│  │  ├─ Link/
+│  │  └─ index.ts (export all)
+│  │
+│  ├─ fields/
+│  │  ├─ typed/
+│  │  │  ├─ TextField/
+│  │  │  ├─ DateField/
+│  │  │  ├─ DateRangeField/
+│  │  │  ├─ TimeField/
+│  │  │  ├─ CurrencyField/
+│  │  │  ├─ PercentageField/
+│  │  │  ├─ QuantityField/
+│  │  │  ├─ StatusField/
+│  │  │  ├─ SelectField/
+│  │  │  ├─ MultiSelectField/
+│  │  │  ├─ CheckboxField/
+│  │  │  ├─ SearchField/
+│  │  │  └─ index.ts
+│  │  │
+│  │  └─ domain/
+│  │     ├─ OrderLineField/
+│  │     ├─ InventoryField/
+│  │     ├─ VoucherLineField/
+│  │     ├─ ProductField/
+│  │     ├─ CustomerField/
+│  │     ├─ SupplierField/
+│  │     ├─ GLAccountField/
+│  │     ├─ WarehouseField/
+│  │     ├─ StockTransferField/
+│  │     ├─ PriceField/
+│  │     ├─ DiscountField/
+│  │     ├─ DateRangeFilterField/
+│  │     └─ index.ts
+│  │
+│  └─ composites/
+│     ├─ Order/
+│     │  ├─ OrderList.vue
+│     │  ├─ OrderDetail.vue
+│     │  ├─ OrderForm.vue
+│     │  ├─ OrderForm.stories.ts
+│     │  ├─ OrderForm.spec.ts
+│     │  └─ types.ts
+│     ├─ Inventory/
+│     ├─ Product/
+│     ├─ Customer/
+│     ├─ Supplier/
+│     ├─ GLAccount/
+│     ├─ Voucher/
+│     ├─ User/
+│     ├─ Warehouse/
+│     ├─ StockTransfer/
+│     └─ index.ts
+│
+├─ stores/ (Pinia)
+│  ├─ modules/
+│  │  ├─ orders.ts
+│  │  ├─ inventory.ts
+│  │  ├─ products.ts
+│  │  ├─ customers.ts
+│  │  ├─ suppliers.ts
+│  │  ├─ glAccounts.ts
+│  │  ├─ vouchers.ts
+│  │  ├─ users.ts
+│  │  ├─ warehouses.ts
+│  │  └─ stockTransfers.ts
+│  ├─ useAuth.ts
+│  ├─ useNotification.ts
+│  ├─ useRouter.ts
+│  └─ index.ts
+│
+├─ views/ (Page Components)
+│  ├─ Order/
+│  │  ├─ OrderListPage.vue
+│  │  ├─ OrderDetailPage.vue
+│  │  └─ OrderCreatePage.vue
+│  ├─ Inventory/
+│  ├─ Product/
+│  ├─ Customer/
+│  ├─ Supplier/
+│  ├─ GLAccount/
+│  ├─ Voucher/
+│  ├─ User/
+│  ├─ Warehouse/
+│  └─ StockTransfer/
+│
+├─ layouts/
+│  ├─ AdminLayout.vue (sidebar + topbar)
+│  ├─ BlankLayout.vue (login page)
+│  └─ ReportLayout.vue (full-width for exports)
+│
+├─ composables/ (Vue Composition API utilities)
+│  ├─ useForm.ts (form state + validation)
+│  ├─ useList.ts (pagination + filtering)
+│  ├─ usePagination.ts (page navigation)
+│  ├─ useApi.ts (API client wrapper)
+│  ├─ useNotification.ts (toast/snackbar)
+│  ├─ useValidation.ts (field validation rules)
+│  └─ useApproval.ts (approval workflow)
+│
+├─ services/
+│  ├─ api/ (auto-generated from OpenAPI)
+│  │  ├─ orderApi.ts
+│  │  ├─ inventoryApi.ts
+│  │  ├─ productApi.ts
+│  │  └─ ...
+│  ├─ validators/
+│  │  ├─ orderValidators.ts
+│  │  ├─ inventoryValidators.ts
+│  │  └─ ...
+│  └─ formatters/
+│     ├─ currencyFormatter.ts
+│     ├─ dateFormatter.ts
+│     └─ statusFormatter.ts
+│
+├─ types/
+│  ├─ models.ts (OpenAPI models exported)
+│  ├─ api.ts (API types)
+│  └─ domain.ts (domain-specific types)
+│
+├─ styles/
+│  ├─ global.scss
+│  ├─ variables.scss
+│  ├─ tabler-overrides.scss
+│  └─ animations.scss
+│
+├─ App.vue
+├─ main.ts
+└─ router.ts
+```
+
+---
+
+## Storybook Organization
+
+### Storybook File Structure
+```
+.storybook/
+├─ main.ts (config)
+├─ preview.ts (global setup)
+├─ preview-head.html (Tabler CDN + custom fonts)
+├─ decorators/
+│  ├─ withPinia.ts (global store)
+│  ├─ withRouter.ts (mock routing)
+│  ├─ withTheme.ts (light/dark mode)
+│  └─ withViewport.ts (responsive preview)
+└─ manager.ts (UI customization)
+```
+
+### Storybook Navigation
+```
+Storybook
+├─ 📦 Primitives (Layer 1) — 30 components, 180 stories
+│  ├─ Button (12 stories)
+│  ├─ Input (8 stories)
+│  ├─ Select (10 stories)
+│  ├─ Table (6 stories)
+│  ├─ Card (5 stories)
+│  ├─ Badge (8 stories)
+│  └─ ... (14 more)
+│
+├─ 📝 Typed Fields (Layer 2) — 12 components, 108 stories
+│  ├─ TextField (10 stories)
+│  ├─ DateField (8 stories)
+│  ├─ CurrencyField (12 stories)
+│  ├─ StatusField (8 stories)
+│  └─ ... (8 more)
+│
+├─ 🎯 Domain Fields (Layer 3) — 12 components, 108 stories
+│  ├─ OrderLineField (10 stories)
+│  ├─ ProductField (12 stories)
+│  ├─ CustomerField (10 stories)
+│  └─ ... (9 more)
+│
+├─ 🏢 Business Composites (Layer 4) — 11 components, 55 stories
+│  ├─ Order CRUD (5 stories: List, Create, Read, Edit, Delete)
+│  ├─ Inventory CRUD (5 stories)
+│  ├─ Product CRUD (5 stories)
+│  └─ ... (8 more)
+│
+├─ 🎨 Design System (Typography, Colors, Icons)
+│  ├─ Colors (Tabler palette + custom)
+│  ├─ Typography (headings, body, mono)
+│  └─ Icons (Bootstrap Icons 30 most-used)
+│
+└─ ✅ Accessibility (WCAG 2.1 AA checklist per component)
+   ├─ Keyboard navigation test
+   ├─ Screen reader verification
+   └─ Color contrast validation
+```
+
+### Storybook Configuration (main.ts)
+```typescript
+export default {
+  stories: [
+    '../src/components/primitives/**/*.stories.ts',
+    '../src/components/fields/typed/**/*.stories.ts',
+    '../src/components/fields/domain/**/*.stories.ts',
+    '../src/components/composites/**/*.stories.ts',
+  ],
+  addons: [
+    '@storybook/addon-essentials',
+    '@storybook/addon-a11y', // Accessibility
+    '@storybook/addon-viewport', // Responsive
+    '@storybook/addon-interactions', // User interactions
+    '@storybook/addon-controls', // Dynamic props
+    '@storybook/addon-measure', // Inspect dimensions
+  ],
+  framework: '@storybook/vue3',
+  docs: {
+    autodocs: true, // Auto-generate docs from comments
+  },
+};
+```
+
+---
+
+## Testing Strategy
+
+### Test Distribution (Testing Pyramid — Principle 26)
+
+```
+        /\           E2E (20%)
+       /  \          50 scenarios for full workflows
+      /____\
+     /      \        Integration (30%)
+    /        \       150 tests for component interactions
+   /_________ \
+  /           \     Unit (50%)
+ /             \    350 tests for individual components
+/_____________\
+```
+
+### Unit Tests (Layer 1-3 components)
+- **Primitives**: Button click, Input change events, Select options
+- **Typed Fields**: Validation rules, formatting (date → ISO, currency → comma-sep)
+- **Domain Fields**: Business rule checks, API call mocking
+
+**File**: `src/components/**/*.spec.ts`  
+**Runner**: Vitest + @testing-library/vue  
+**Coverage Target**: 70%+
+
+### Integration Tests (Layer 4 composites)
+- **CRUD Workflows**: Create → Read → Update → Delete
+- **Validation Chains**: Form validation + API error handling
+- **State Management**: Pinia store mutations + selections
+
+**File**: `src/components/composites/**/*.spec.ts`  
+**Runner**: Vitest + MSW (Mock Service Worker)  
+**Mocks**: OpenAPI endpoints
+
+### E2E Tests (Full User Journeys)
+- **Order Flow**: Create customer → Create order → Ship → Deliver
+- **Approval Matrix**: High-value order → Supervisor approval → Finance review
+- **Inventory Adjustment**: Adjust stock → Audit log verification
+
+**File**: `tests/e2e/**/*.spec.ts`  
+**Runner**: Playwright (6.0+)  
+**Scenarios**: 116 total (11 CRUD × 10-15 scenarios per entity)
+
+**Example E2E Test**:
+```typescript
+test('Order workflow: create → approve → ship', async ({ page }) => {
+  // 1. Login
+  await page.goto('/Account/Login');
+  await page.fill('[name="email"]', 'manager@example.com');
+  await page.fill('[name="password"]', 'password123!');
+  await page.click('button[type="submit"]');
+  
+  // 2. Create order
+  await page.goto('/admin/orders');
+  await page.click('button:text("Create Order")');
+  await page.selectOption('[name="customerId"]', 'CUST-001');
+  await page.fill('[name="quantity"]', '100');
+  await page.click('button:text("Submit")');
+  await expect(page).toHaveURL(/\/admin\/orders\/\d+/);
+  
+  // 3. Supervisor approval
+  await page.click('button:text("Request Approval")');
+  await page.logout();
+  
+  // ... login as supervisor ...
+  
+  // 4. Approve
+  await page.click('button:text("Approve")');
+  await expect(page).toContainText('Order approved');
+  
+  // 5. Audit log verification
+  await page.goto('/admin/audit-logs?entity=orders&entityId=123');
+  await expect(page).toContainText('created_by: manager@example.com');
+  await expect(page).toContainText('modified_by: supervisor@example.com');
+});
+```
+
+---
+
+## Figma Design System (Specification)
+
+### Color Palette (Tabler Base)
+- **Primary**: #0D6EFD (Bootstrap Blue)
+- **Success**: #198754 (Bootstrap Green)
+- **Danger**: #DC3545 (Bootstrap Red)
+- **Warning**: #FFC107 (Bootstrap Amber)
+- **Info**: #0DCAF0 (Bootstrap Cyan)
+- **Dark**: #2C3E50 (Custom Sidebar)
+- **Light**: #F5F7FB (Custom Background)
+
+### Typography
+- **Headings**: Inter Medium (600), 24px/20px/18px/16px/14px
+- **Body**: Inter Regular (400), 14px/16px
+- **Mono**: IBM Plex Mono, 12px (for GL account codes, order numbers)
+
+### Component Sizes
+- **Button**: sm (32px) / md (40px) / lg (48px)
+- **Input**: sm (32px) / md (40px) / lg (48px)
+- **Table Row**: 44px
+- **Card Padding**: 20px
+- **Border Radius**: 6px (default), 12px (card), 0px (table)
+
+### Spacing (8px grid)
+- Margins: 0, 8, 16, 24, 32, 40px
+- Padding: 8, 12, 16, 20, 24px
+
+### Interactive States
+- **Hover**: 10% opacity overlay
+- **Focus**: 2px outline, 4px blue (#0D6EFD)
+- **Disabled**: 50% opacity, cursor not-allowed
+- **Loading**: Spinner overlay, pointer-events none
+
+---
+
+## Accessibility Requirements (WCAG 2.1 AA)
+
+### Per-Component Checklist
+
+| Component | Keyboard | Screen Reader | Color | Focus |
+|-----------|----------|---------------|-------|-------|
+| **Button** | Tab + Enter | aria-label | 4.5:1 contrast | Visible outline |
+| **Input** | Tab + Type | aria-label + aria-describedby (error) | Error text 4.5:1 | Visible outline |
+| **Table** | Tab + arrows | scope + aria-sort | Text 4.5:1 | Row highlight |
+| **Modal** | Tab + Escape | role="dialog", focus trap | Background 3:1 | Focused element |
+| **Select** | Tab + arrows | aria-expanded + aria-controls | 4.5:1 contrast | Dropdown highlight |
+
+### Automated Validation
+- **Tool**: axe-core (Storybook addon)
+- **Target**: 95+ axe score per component
+- **CI Gate**: No accessibility violations in main branch
+
+---
+
+## Migration Path (Phase 1-4)
+
+### Phase 1: Setup (Week 1-2)
+- [ ] Vite scaffold + TypeScript strict mode
+- [ ] Storybook 7.0 setup + Tabler theme
+- [ ] ESLint + Prettier config
+- [ ] Primitives folder structure created
+
+### Phase 2: Primitives (Week 3-4)
+- [ ] 30 Primitive components built
+- [ ] 180 Storybook stories written
+- [ ] Unit test: 70%+ coverage
+- [ ] Accessibility audit: axe 95+
+- [ ] Design system published (Figma library link)
+
+### Phase 3: Typed + Domain Fields (Week 5-6)
+- [ ] 12 Typed Field components built + 108 stories
+- [ ] 12 Domain Field components built + 108 stories
+- [ ] Integration tests for field validation chains
+- [ ] API client auto-generated from OpenAPI spec
+
+### Phase 4: Business Composites (Week 7-8)
+- [ ] 11 full CRUD components built + 55 stories
+- [ ] 116 E2E tests passing
+- [ ] Responsive design verified (mobile, tablet, desktop)
+- [ ] Performance: LCP <2.5s, TTI <3s, CLS <0.1
+
+---
+
+## Sign-Off
+
+- **UX/Design Lead**: _________________ Date: _______
+- **Frontend Tech Lead**: _________________ Date: _______
+- **QA Lead**: _________________ Date: _______
+
+---
+
+**Document Version**: 1.0  
+**Last Updated**: 2026-07-26  
+**Figma Designs**: [Link to Figma project TBD]  
+**Next Milestone**: Phase 1 Vite scaffold + ESLint setup (2026-08-02)