Module Reference

รายละเอียดทุก backend module — name, path, purpose, endpoints, dependencies

ทุก module อยู่ใต้ apps/api/src/modules/ (ยกเว้น PrismaModule ที่อยู่ใน infrastructure/)

Infrastructure

PrismaModule

• Path: apps/api/src/infrastructure/prisma/
• Purpose: Global PrismaService — exposed ให้ทุก module inject ได้
• Exports: PrismaService (extends PrismaClient + lifecycle hooks)
• Dependencies: none

Core / System

AuthModule

• Path: modules/auth/
• Purpose: Login, register, JWT issuance, decorators + guards (re-export ให้ module อื่นใช้)
• Endpoints:
  • POST /auth/login — email + password → JWT
  • POST /auth/register — create user (admin only)
  • GET /auth/me — current user from JWT
  • POST /auth/change-password — current user changes own password
• Dependencies: PrismaModule, JwtModule, PassportModule
• Exports: AuthService, JwtAuthGuard, RolesGuard (ใช้ใน module อื่น)

UsersModule

• Path: modules/users/
• Purpose: User CRUD + permission management (adminModules / adminModulesWrite)
• Endpoints:
  • GET /users — list + filter
  • GET /users/stats — count by role/status
  • GET /users/:id — detail
  • POST /users — create user
  • PATCH /users/:id — update (including permissions)
  • POST /users/:id/toggle-status — active ↔ inactive
  • POST /users/:id/reset-password — admin reset
  • DELETE /users/:id — soft delete
• Dependencies: PrismaModule, AuthModule

HealthModule

• Path: modules/health/
• Purpose: liveness / readiness / stats สำหรับ monitoring
• Endpoints:
  • GET /health/live — process alive
  • GET /health/ready — DB connection OK
  • GET /health/stats — uptime, memory, DB response time
• Dependencies: PrismaModule

FilesModule

• Path: modules/files/
• Purpose: Presigned upload URLs สำหรับ Cloudflare R2 (S3-compatible)
• Endpoints: POST presigned upload, GET presigned download (รายละเอียดดู Swagger)
• Dependencies: ใช้ R2 env vars; @aws-sdk/client-s3 + s3-request-presigner

AuditModule

• Path: modules/audit/
• Purpose: Query audit_log table
• Endpoints: GET /audit — list with filters (entityType, entityId, userId, date range)
• Dependencies: PrismaModule
• Note: เขียน log โดย service อื่นเอง (ผ่าน EventEmitter)

Master Data

MasterDataModule

• Path: modules/master-data/
• Purpose: ครอบ 5 sub-controllers ของ master data
• Sub-modules:

items

• Path: modules/master-data/items/
• Controller: @Controller('items')
• Endpoints: GET list, GET :id, POST, PATCH :id, DELETE :id, + bulk import
• Model: Item + ItemUom

locations

• Path: modules/master-data/locations/
• Controller: @Controller('locations')
• Endpoints: standard CRUD; รองรับ 20+ capacity fields (dimensions, storage type, temperature zone, abc class, …)
• Model: Location

uoms

• Path: modules/master-data/uoms/
• Controller: @Controller('uoms')
• Endpoints: UoM CRUD + conversion management (ItemUom)
• Model: Uom, ItemUom

partners

• Path: modules/master-data/partners/
• Controller: @Controller('partners')
• Endpoints: standard CRUD; type filter (supplier/customer/carrier)
• Model: Partner

warehouses

• Path: modules/master-data/warehouses/
• Controller: @Controller('warehouses')
• Endpoints: CRUD warehouses + timezone setting
• Model: Warehouse

Inbound

InboundModule

• Path: modules/inbound/
• Purpose: ครอบ ASN + GRN + Putaway
• Sub-modules:

asn

• Controller: @Controller('asn')
• Purpose: Advance Shipment Notice — supplier แจ้งสินค้าที่จะส่งมา
• Endpoints: CRUD ASN; lifecycle (draft → confirmed → receiving → closed)
• Models: Asn, AsnLine

grn

• Controller: @Controller('grn')
• Purpose: Goods Receipt Note — บันทึกของจริงที่รับ
• Endpoints: create GRN against ASN; QC fields; auto-update AsnLine.receivedQty
• Models: Grn, GrnLine

putaway

• Controller: @Controller('putaway') + @Controller('putaway-rules')
• Purpose: จัดเก็บจาก staging → final location; rule engine สำหรับ suggest location
• Endpoints: task lifecycle (pending → in_progress → completed); rule CRUD
• Models: PutawayTask, PutawayRule

Inventory

InventoryModule

• Path: modules/inventory/
• Purpose: Stock inquiry + movements + adjustments + cycle counts
• Sub-modules:

stock

• Controller: @Controller('stock')
• Endpoints: query by warehouse/location/item/lot/serial; aggregates by item
• Models: Stock, StockReservation

adjustments

• Controller: @Controller('adjustments')
• Purpose: manual stock correction (with reason code → trigger approval if exceeds threshold)
• Side-effects: writes StockMovement (type=adjust) + may create ApprovalRequest

cycle-counts

• Controller: @Controller('cycle-counts')
• Purpose: count CRUD + variance approval workflow
• Models: CycleCount, CycleCountLine

(movements query lives in stock module's service — no separate controller)

Outbound

OutboundModule

• Path: modules/outbound/
• Sub-modules:

orders

• Controller: @Controller('orders')
• Purpose: Sales order CRUD + lifecycle (draft → confirmed → allocated → released → shipped)
• Endpoints: standard CRUD + POST :id/cancel, POST :id/release
• Models: SalesOrder, SalesOrderLine

waves

• Controller: @Controller('waves')
• Purpose: group orders เป็น batch สำหรับ pick → release ออกเป็น pick tasks
• Models: Wave

pick-tasks

• Controller: @Controller('pick-tasks')
• Purpose: individual pick — assign to operator, track completion
• Models: PickTask

shipments

• Controller: @Controller('shipments')
• Purpose: packing + label generation + carrier handoff
• Models: Shipment, ShipmentPackage

Returns

ReturnsModule

• Path: modules/returns/rma/
• Controller: @Controller('rma')
• Purpose: Return Merchandise Authorization + receipt + disposition routing (restock/scrap/quarantine/repair)
• Models: Rma, RmaLine
• Dependencies: ใช้ Outbound (อ้าง originalOrderId)

Replenishment

ReplenishmentModule

• Path: modules/replenishment/
• Controller: @Controller('replenishment')
• Purpose: min/max rule + auto task generation (เติม pick face จาก bulk)
• Endpoints: rules CRUD, tasks CRUD, trigger generate
• Models: ReplenishmentRule, ReplenishmentTask

LPN (License Plate)

LpnModule

• Path: modules/lpn/
• Controller: @Controller('lpn')
• Purpose: Pallet/case tracking — build, nest, split, merge, move, breakdown
• Models: LicensePlate, LpnMovement
• Dependencies: Inventory (link Stock.lpnId)

Approvals

ApprovalsModule

• Path: modules/approvals/
• Controller: @Controller('approvals')
• Purpose: generic approval queue (cycle count variance, adjustment over threshold)
• Endpoints: list pending, approve, reject
• Models: ApprovalRequest

Config & Admin

ConfigWmsModule

• Path: modules/config/
• Controller: @Controller('config')
• Purpose: key-value system config (scoped: system/tenant/warehouse/user) — backing data for WMS Settings 8 tabs
• Models: SystemConfig, CustomFieldDefinition

AnnouncementsModule

• Path: modules/announcements/
• Controller: @Controller('announcements')
• Purpose: banner messages (info/warning/critical/maintenance) — Admin posts, Main WMS displays
• Endpoints: CRUD + GET /announcements/active (for client polling)
• Models: Announcement

ApiKeysModule

• Path: modules/api-keys/
• Controller: @Controller('api-keys')
• Purpose: create/revoke/inspect API keys; stats + request log
• Endpoints:
  • GET /api-keys
  • GET /api-keys/:id
  • GET /api-keys/:id/stats
  • GET /api-keys/:id/requests — paginated log
  • POST /api-keys — returns rawKey ครั้งเดียว
  • PATCH /api-keys/:id — toggle active, change scopes/whitelist/rateLimit
  • DELETE /api-keys/:id
• Models: ApiKey, ApiKeyRequest
• Dependencies: AuthModule (uses ApiKeyGuard for validation function)

WebhookModule

• Path: modules/webhook/
• Controller: @Controller('webhooks')
• Purpose: outbound webhook subscription + delivery tracking
• Endpoints:
  • GET /webhooks — list
  • GET /webhooks/:id
  • POST /webhooks — create
  • PATCH /webhooks/:id
  • DELETE /webhooks/:id
  • POST /webhooks/:id/test — fire test event
• Models: WebhookSubscription, WebhookDelivery

Reports

ReportsModule

• Path: modules/reports/
• Controller: @Controller('reports')
• Purpose: aggregated read-only reports — 22 endpoints
• Endpoints by group:

Group	Endpoints (GET /reports/…)
inventory	/inventory/stock-snapshot, /inventory/movements, /inventory/adjustments, /inventory/aging, /inventory/low-stock, /inventory/cycle-count-variance
receiving	/receiving/asn-summary, /receiving/grn-summary, /receiving/by-sku, /receiving/putaway-summary
outbound	/outbound/order-fulfillment, /outbound/pick-tasks, /outbound/cycle-time, /outbound/by-customer
delivery	/delivery/shipments, /delivery/by-carrier
users	/users/activity, /users/login-history, /users/productivity

ทุก endpoint รับ filter querystring (warehouseId, dateFrom, dateTo, …) — service ใช้ Prisma groupBy / raw SQL

• Dependencies: PrismaModule

Integration

IntegrationModule

• Path: modules/integration/
• Controller: @Controller('integration/v1')
• Auth: controller-level @UseGuards(ApiKeyGuard) + @UseInterceptors(IdempotencyInterceptor)
• Purpose: push API สำหรับ external systems (ERP, e-commerce)
• Endpoints: ดู Integrations สำหรับรายการ 16 endpoints
• Models: สร้าง/อัปเดต Item, Partner, Location, Asn, Grn, SalesOrder, LicensePlate; idempotency cache ใน IntegrationRequest
• Dependencies: AuthModule (ApiKeyGuard), all relevant business services

Cross-Cutting Concerns

นอกจาก modules ปกติ ยังมี:

Concern	Implementation	location
Global ConfigModule	@nestjs/config + Joi validation	app.module.ts
EventEmitter	@nestjs/event-emitter	app.module.ts (EventEmitterModule.forRoot())
Global ValidationPipe	class-validator	main.ts
CORS	custom function (allow *.pages.dev + explicit list)	main.ts
Swagger	@nestjs/swagger (non-prod only)	main.ts
Logging	Nest built-in Logger	per-service

Adding a New Module

1. สร้าง folder apps/api/src/modules/<feature>/
2. สร้างไฟล์ตาม convention:
   • <feature>.module.ts
   • <feature>.controller.ts (@Controller('<feature>'))
   • <feature>.service.ts
   • dto/create-<feature>.dto.ts + dto/update-<feature>.dto.ts
3. ลงทะเบียนใน apps/api/src/app.module.ts:

   import { MyFeatureModule } from './modules/my-feature/my-feature.module';
   // เพิ่มใน imports: [...]

4. ถ้าต้องการ persistence — เพิ่ม model ใน prisma/schema.prisma แล้ว pnpm db:push && pnpm db:generate
5. ถ้าเป็น admin feature — เพิ่ม module key ในรายการ permission (Authorization)