QuantEngineByItz/oms-wms-erp/README.md

OMS·WMS·ERP Platform

Enterprise-grade Order Management (OMS) + Warehouse Management (WMS) + Enterprise Resource Planning (ERP) platform built with Vue 3, TypeScript, and Vite.

Project Status

Phase: 2 (Typed Fields & State Management)
Status: 🚀 In Progress (Step 4: Final Verification)
Started: 2026-08-02
Phase 2 Target: 2026-08-27 (End of Week 3)
Overall Target: 2026-11-30 (Phase 11)

Progress:

• ✅ Phase 1: Complete (Primitives, Storybook, CI/CD)
• 🔄 Phase 2 Step 1-3: Complete (Typed Fields, Pinia, MSW)
• 🔄 Phase 2 Step 4: In Progress (Final Verification)

Getting Started

Prerequisites

• Node.js >= 18.0.0
• npm >= 9.0.0

Installation

npm install

Development

Start the development server:

npm run dev

The app will open at http://localhost:5173

Storybook

View component library:

npm run storybook

Storybook will open at http://localhost:6006

Build for Production

npm run build

Testing

Unit Tests (70+ tests, Vitest):

npm run test:unit         # Run once
npm run test:watch       # Watch mode (development)

Integration Tests (65+ tests, MSW mocking):

npm run test:integration # Run integration tests

E2E Tests (50+ tests, Playwright):

npm run test:e2e         # Requires dev server running (npm run dev)
npx playwright test --headed  # Run with browser visible

Complete Verification (lint + type-check + unit + integration + build):

npm run verify           # Full pipeline
npm run test:all         # All tests (unit + integration + E2E)

Coverage Report:

npm run test:coverage    # Generate HTML coverage report
# Open coverage/index.html in browser

Test Statistics:

• Total Coverage: 185+ test cases
• Unit Tests: 70+
• Integration Tests: 65+
• E2E Tests: 50+
• Target Coverage: 70%+

Linting

npm run lint

Architecture

4-Layer Component Hierarchy

1. Primitives (30) - Pure UI building blocks

   • Button, Input, Select, Table, Card, Badge, Modal, etc.
   • No business logic, full accessibility (WCAG 2.1 AA)

2. Typed Fields (12) - Domain-aware inputs

   • TextField, DateField, CurrencyField, etc.
   • Built-in validation and formatting

3. Domain Fields (12) - Business-specific components

   • OrderLineField, ProductField, etc.
   • API lookups, business rules

4. Business Composites (11) - Full CRUD workflows

   • OrderForm, InventoryTransferWizard, VoucherEditor, etc.
   • State orchestration, approval workflows

Project Structure

src/
├── components/
│   ├── primitives/          # Layer 1: UI building blocks
│   ├── fields/
│   │   ├── typed/          # Layer 2: Type-safe inputs
│   │   └── domain/         # Layer 3: Business-specific
│   └── composites/         # Layer 4: Full workflows
├── stores/                  # Pinia state management
├── services/                # API client, validators, formatters
├── views/                   # Page components
├── router.ts               # Vue Router configuration
├── App.vue                 # Root component
└── main.ts                 # Entry point

Development Guidelines

Code Quality

• TypeScript Strict Mode: Enabled (no any types)
• ESLint: Enforced on commit
• Prettier: Auto-format on save
• Test Coverage: Target 70%+

Component Development

1. Responsibility: Each component does one thing well
2. Props & Events: Follow Vue 3 Composition API conventions
3. Accessibility: WCAG 2.1 AA minimum
4. Documentation: Storybook stories required (5+ per component)

Testing

• Unit Tests: Vitest + @testing-library/vue
• Integration Tests: Vitest with MSW mocks
• E2E Tests: Playwright (116 scenarios)

Key Technologies

• Framework: Vue 3 (Composition API)
• Language: TypeScript (strict mode)
• Build Tool: Vite
• Component Documentation: Storybook 8.0+
• State Management: Pinia
• HTTP Client: Axios
• Testing: Vitest + Playwright
• Linting: ESLint + Prettier
• UI Framework: Tabler (Bootstrap 5)

Phase Roadmap

Phase	Goal	Duration	Status
0	Requirements & Baseline	2 weeks	✅ Complete
1	Dev Env & CI/CD	2 weeks	🚀 In Progress
2	Primitives (30 components)	2 weeks	⏳ Pending
3	Fields & Pinia	2 weeks	⏳ Pending
4	CRUD Templates & E2E	2 weeks	⏳ Pending
5-11	Polish, Security, Deployment	10 weeks	⏳ Pending

Contributing

1. Create a feature branch
2. Make changes following code standards
3. Write tests (70%+ coverage target)
4. Create Storybook stories for new components
5. Submit PR with reference to task/issue

API Specification

See spec/63_oms_wms_erp_api_openapi.yaml for complete OpenAPI 3.0 specification.

Database Schema

See spec/64_oms_wms_erp_database_schema.sql for PostgreSQL schema (3NF + audit trails).

License

Internal Use Only - QuantEngine Project

Support

For questions or issues, refer to CLAUDE.md in the project root.