commit

API_DOCUMENTATION.md

@@ -0,0 +1,316 @@
+# Elysia API Documentation
+
+## Overview
+
+This project uses ElysiaJS integrated with Next.js App Router to create high-performance, type-safe APIs. The codebase follows a **Feature-based MVC pattern** for maintainability and scalability.
+
+## Base URL
+
+```
+http://localhost:3001
+```
+
+## Endpoints
+
+### Customers API
+
+#### Get All Customers by Branch
+
+```
+GET /api/customers/:branch
+```
+
+**Parameters:**
+
+- `branch` (path parameter, required): Branch identifier
+  - Examples: `branch-01`, `branch-02`, `head-office`
+- `status` (query parameter, optional): Filter by customer status
+  - Values: `active`, `inactive`, `pending`
+
+**Examples:**
+
+1. Get all customers from branch-01:
+
+```bash
+curl http://localhost:3001/api/customers/branch-01
+```
+
+2. Get active customers from branch-02:
+
+```bash
+curl "http://localhost:3001/api/customers/branch-02?status=active"
+```
+
+3. Get pending customers from head-office:
+
+```bash
+curl "http://localhost:3001/api/customers/head-office?status=pending"
+```
+
+**Response Format:**
+
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "id": "cust-001",
+      "branch": "branch-01",
+      "name": "สมชาย ใจดี",
+      "email": "somchai@example.com",
+      "phone": "081-234-5678",
+      "company": "บริษัท ไทยธุรกิจ จำกัด",
+      "address": "123 ถนนสุขุมวิท แขวงคลองตัน เขตคลองเตย กรุงเทพฯ 10110",
+      "status": "active",
+      "createdAt": "2024-01-15T09:00:00Z",
+      "updatedAt": "2024-01-15T09:00:00Z"
+    }
+  ],
+  "count": 1,
+  "message": "Found 1 customer(s) for branch: branch-01"
+}
+```
+
+#### Get Single Customer by ID
+
+```
+GET /api/customers/:branch/:id
+```
+
+#### Create Customer
+
+```
+POST /api/customers
+```
+
+#### Update Customer
+
+```
+PUT /api/customers/:branch/:id
+```
+
+#### Delete Customer
+
+```
+DELETE /api/customers/:branch/:id
+```
+
+---
+
+### Quotations API
+
+#### Get All Quotations by Branch
+
+```
+GET /api/quotations/:branch
+```
+
+**Parameters:**
+
+- `branch` (path parameter, required): Branch identifier
+  - Examples: `branch-01`, `branch-02`, `head-office`
+- `status` (query parameter, optional): Filter by quotation status
+  - Values: `draft`, `sent`, `accepted`, `rejected`, `expired`
+
+**Examples:**
+
+1. Get all quotations from branch-01:
+
+```bash
+curl http://localhost:3001/api/quotations/branch-01
+```
+
+2. Get sent quotations from head-office:
+
+```bash
+curl "http://localhost:3001/api/quotations/head-office?status=sent"
+```
+
+**Response Format:**
+
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "id": "quot-001",
+      "quotationNumber": "QT-2024-001",
+      "branch": "branch-01",
+      "customerId": "cust-001",
+      "customerName": "สมชาย ใจดี",
+      "date": "2024-01-20T00:00:00Z",
+      "validUntil": "2024-02-20T00:00:00Z",
+      "subtotal": 50000,
+      "taxRate": 0.07,
+      "taxAmount": 3500,
+      "totalAmount": 53500,
+      "status": "sent",
+      "notes": "Quotation for office supplies",
+      "createdAt": "2024-01-20T09:00:00Z",
+      "updatedAt": "2024-01-20T09:00:00Z"
+    }
+  ],
+  "count": 2,
+  "message": "Found 2 quotation(s) for branch: branch-01"
+}
+```
+
+#### Get Single Quotation by ID
+
+```
+GET /api/quotations/:branch/:id
+```
+
+#### Create Quotation
+
+```
+POST /api/quotations
+```
+
+#### Update Quotation
+
+```
+PUT /api/quotations/:branch/:id
+```
+
+#### Delete Quotation
+
+```
+DELETE /api/quotations/:branch/:id
+```
+
+---
+
+## Available Data
+
+### Customers
+
+- `branch-01`: 4 customers (3 active, 1 pending)
+- `branch-02`: 3 customers (1 active, 1 inactive, 1 pending)
+- `head-office`: 3 customers (all active)
+
+### Quotations
+
+- `branch-01`: 2 quotations (1 sent, 1 accepted)
+- `branch-02`: 1 quotation (draft)
+- `head-office`: 1 quotation (sent)
+
+## Testing with Browser
+
+Simply open these URLs in your browser:
+
+### Customers
+
+- http://localhost:3001/api/customers/branch-01
+- http://localhost:3001/api/customers/branch-02?status=active
+- http://localhost:3001/api/customers/head-office
+
+### Quotations
+
+- http://localhost:3001/api/quotations/branch-01
+- http://localhost:3001/api/quotations/head-office?status=sent
+
+## Project Structure
+
+This project follows the **Feature-based MVC pattern** as recommended by ElysiaJS:
+
+```
+src/
+├── app/
+│   └── api/
+│       └── [[...slugs]]/
+│           └── route.ts              # Main API entry point
+├── modules/
+│   ├── customers/
+│   │   ├── controller.ts             # HTTP handlers & routing
+│   │   ├── service.ts                # Business logic
+│   │   └── model.ts                  # Schemas & validation
+│   └── quotations/
+│       ├── controller.ts             # HTTP handlers & routing
+│       ├── service.ts                # Business logic
+│       └── model.ts                  # Schemas & validation
+├── types/
+│   └── customer.ts                   # Shared types
+├── lib/
+│   └── mock-data.ts                  # Mock data
+```
+
+### File Responsibilities
+
+#### Model (`model.ts`)
+
+- Define TypeBox schemas for validation
+- Export TypeScript types from schemas
+- All data structure definitions
+
+#### Service (`service.ts`)
+
+- Business logic and data operations
+- Pure functions (no Elysia dependencies)
+- CRUD operations
+- Data transformation
+
+#### Controller (`controller.ts`)
+
+- Elysia instance for the module
+- Route definitions and handlers
+- Request/response validation
+- Calls service functions
+- HTTP-specific concerns
+
+#### Main Route (`app/api/[[...slugs]]/route.ts`)
+
+- Import all controllers
+- Combine with `.use()`
+- Export handlers for Next.js
+
+### Important Implementation Notes
+
+This project follows the **correct ElysiaJS + Next.js integration pattern**:
+
+- ✅ Single route file `[[...slugs]]/route.ts` with Elysia internal routing
+- ✅ Uses `export const GET = app.fetch` (not `.handle`)
+- ✅ Elysia instance has `prefix: '/api'`
+- ✅ All routes defined within Elysia instances using `.get()`, `.post()`, etc.
+- ✅ WinterCG compliant - works as normal Next.js API route
+- ✅ Feature-based MVC pattern for maintainability
+- ✅ Clear separation of concerns between Model, View, and Controller
+
+## Technologies Used
+
+- **ElysiaJS**: Type-safe, high-performance web framework
+- **Next.js 16**: React framework with App Router
+- **TypeScript**: Type safety throughout
+- **TypeBox**: Schema validation (via `@elysiajs/schema`)
+
+## Features
+
+✅ Feature-based MVC architecture  
+✅ Dynamic branch parameter support  
+✅ Type-safe request/response validation  
+✅ Optional query parameter filtering  
+✅ Mock data for customers and quotations  
+✅ Full TypeScript support  
+✅ Auto-generated API documentation (Swagger/OpenAPI ready)  
+✅ Correct ElysiaJS + Next.js integration pattern  
+✅ Scalable and maintainable code structure  
+✅ Clear separation of concerns
+
+## Adding New Modules
+
+To add a new module (e.g., `products`):
+
+1. Create folder: `src/modules/products/`
+2. Create `model.ts` - Define schemas
+3. Create `service.ts` - Business logic
+4. Create `controller.ts` - Routes and handlers
+5. Update `src/app/api/[[...slugs]]/route.ts`:
+
+   ```typescript
+   import { products } from "@/modules/products/controller";
+
+   const app = new Elysia({ prefix: "/api" })
+     .use(customers)
+     .use(quotations)
+     .use(products); // Add new module
+   ```