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

```bash
npm install
```

### Development

Start the development server:

```bash
npm run dev
```

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

### Storybook

View component library:

```bash
npm run storybook
```

Storybook will open at `http://localhost:6006`

### Build for Production

```bash
npm run build
```

### Testing

**Unit Tests** (70+ tests, Vitest):
```bash
npm run test:unit         # Run once
npm run test:watch       # Watch mode (development)
```

**Integration Tests** (65+ tests, MSW mocking):
```bash
npm run test:integration # Run integration tests
```

**E2E Tests** (50+ tests, Playwright):
```bash
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):
```bash
npm run verify           # Full pipeline
npm run test:all         # All tests (unit + integration + E2E)
```

**Coverage Report**:
```bash
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

```bash
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.