ginskill-init 2.7.0

package/skills/active-life-dev/docs/integrations.md

@@ -0,0 +1,209 @@
+# Active Life Backend - External Integrations
+
+## 1. eTelecom (SIP Phone System)
+
+### Purpose
+Call center integration for TeleSales and LiveChat staff. Staff members are assigned SIP extensions to make/receive calls.
+
+### Models
+- `EtelecomExtension` — SIP extension config (extensionNumber, password, tenantId, tenantDomain)
+- `OmiCall` — Call log records (callId, direction, fromNumber, toNumber, status, duration, recordingUrl)
+
+### Module: `src/etelecom/`
+- **Controller**: Extension management, webhook receiver
+- **Service**: Create extensions, link to staff, process webhooks
+
+### Key Endpoints
+```
+POST /api/v1/etelecom/extension      — Create SIP extension
+POST /api/v1/etelecom/link-staff     — Link staff to extension
+POST /api/v1/etelecom/webhook        — Receive call events (Public)
+GET  /api/v1/etelecom/calls          — List call logs
+```
+
+### JWT Integration
+Staff JWT payload includes eTelecom data:
+```typescript
+{
+  etelecom: {
+    extensionNumber: string;
+    extensionPassword: string;
+    tenantId: string;
+    tenantDomain: string;
+  }
+}
+```
+
+### Environment Variables
+```
+ETELECOM_URL=           # eTelecom API base URL
+AT_ETELECOM=            # eTelecom API token
+```
+
+---
+
+## 2. Firebase
+
+### Dependencies
+```json
+"firebase": "^11.4.0",
+"firebase-admin": "^12.6.0"
+```
+
+### Usage
+- Push notifications to mobile clients
+- Possible auth integration for social login
+- Firebase Admin SDK for server-side operations
+
+### Configuration
+Firebase config expected via environment variables or service account JSON.
+
+---
+
+## 3. Redis (IORedis)
+
+### Dependencies
+```json
+"@nestjs-modules/ioredis": "^2.0.2",
+"ioredis": "^5.8.2"
+```
+
+### Usage
+- Session caching
+- Rate limiting support
+- Temporary data storage
+- Queue management (potential)
+
+### Setup in AppModule
+```typescript
+import { RedisModule } from '@nestjs-modules/ioredis';
+
+RedisModule.forRoot({
+  type: 'single',
+  url: process.env.REDIS_URL,
+})
+```
+
+---
+
+## 4. Email (Nodemailer)
+
+### Dependencies
+```json
+"@nestjs-modules/mailer": "^1.6.1",
+"nodemailer": "^6.9.14"
+```
+
+### Usage
+- Transactional emails (order confirmation, password reset)
+- Templates in `views/mail/templates/` directory
+- EJS template engine
+
+### Setup
+```typescript
+import { MailerModule } from '@nestjs-modules/mailer';
+
+MailerModule.forRoot({
+  transport: {
+    host: process.env.MAIL_HOST,
+    port: process.env.MAIL_PORT,
+    auth: {
+      user: process.env.MAIL_USER,
+      pass: process.env.MAIL_PASS,
+    },
+  },
+  defaults: {
+    from: process.env.MAIL_FROM,
+  },
+  template: {
+    dir: join(__dirname, '..', 'views', 'mail', 'templates'),
+    adapter: new EjsAdapter(),
+  },
+})
+```
+
+---
+
+## 5. Mongoose (MongoDB - Secondary)
+
+### Dependencies
+```json
+"@nestjs/mongoose": "^10.0.0",
+"mongoose": "^8.5.0",
+"mongoose-delete": "^1.0.2"
+```
+
+### Usage
+- Secondary database for specific use cases
+- Soft delete support via mongoose-delete plugin
+- NOT the primary database (Prisma/PostgreSQL is primary)
+
+### Note
+Some models may use MongoDB for flexible schema requirements or legacy data. Check individual modules for MongoDB vs Prisma usage.
+
+---
+
+## 6. Swagger / OpenAPI
+
+### Dependency
+```json
+"@nestjs/swagger": "^7.0.0"
+```
+
+### Access
+Available at `/api` endpoint in development.
+
+### Usage in Controllers
+```typescript
+@ApiTags('products')
+@ApiBearerAuth()
+@Controller('product')
+export class ProductController {
+  @Post()
+  @ApiOperation({ summary: 'Create a new product' })
+  @ApiResponse({ status: 201, description: 'Product created' })
+  create(@Body() dto: CreateProductDto) { }
+}
+```
+
+---
+
+## 7. Rate Limiting (Throttler)
+
+### Dependency
+```json
+"@nestjs/throttler": "^6.0.0"
+```
+
+### Configuration
+```typescript
+ThrottlerModule.forRoot([{
+  ttl: 60000,   // 60 seconds window
+  limit: 10,    // Max 10 requests per window
+}])
+```
+
+Global rate limiting applied to all endpoints.
+
+---
+
+## Integration Architecture
+
+```
+                    ┌─────────────┐
+                    │   Clients   │
+                    │ (Mobile/Web)│
+                    └──────┬──────┘
+                           │
+                    ┌──────▼──────┐
+                    │   NestJS    │
+                    │   API       │
+                    └──────┬──────┘
+                           │
+           ┌───────┬───────┼───────┬────────┐
+           │       │       │       │        │
+      ┌────▼──┐ ┌──▼───┐ ┌▼────┐ ┌▼─────┐ ┌▼────────┐
+      │Supabase│ │Redis │ │Email│ │Firebase│ │eTelecom │
+      │  PG   │ │Cache │ │SMTP │ │ Push  │ │  SIP    │
+      └───────┘ └──────┘ └─────┘ └──────┘ └─────────┘
+```

package/skills/active-life-dev/docs/inventory.md

@@ -0,0 +1,192 @@
+# Active Life Backend - Inventory System
+
+## Architecture
+
+```
+InventoryProduct (warehouse item: SKU, barcode, unit, brand)
+    ├──< ProductInventoryItem (individual lots with expiry dates)
+    └──< InventoryTransaction (import/export records)
+              └──> InventorySession (batch import/export session)
+```
+
+## Key Concept: Inventory vs Store Products
+
+- **InventoryProduct** — Physical warehouse items (raw materials, actual stock)
+- **StoreProduct** — Customer-facing products (may combine multiple inventory products via combos)
+- **ProductInventoryItem** — Individual lot/batch with quantity, expiry date, lot number
+
+**Example**:
+```
+InventoryProduct: "Whey Protein Gold Standard 1kg"
+  ├── Lot #1: qty=50, expires=2025-06-01, remaining=45
+  ├── Lot #2: qty=100, expires=2025-09-01, remaining=100
+  └── Lot #3: qty=75, expires=2025-12-01, remaining=75
+```
+
+## Models
+
+### InventoryProduct
+```prisma
+model InventoryProduct {
+  id      String  @id @default(uuid())
+  name    String
+  sku     String? @unique
+  barcode String?
+  image   String?
+  unitId  String?
+  brandId String?
+  // Relations
+  unit    Unit?   @relation(...)
+  brand   Brand?  @relation(...)
+  items   ProductInventoryItem[]
+  transactions InventoryTransaction[]
+  comboItems   StoreProductComboItem[]
+}
+```
+
+### ProductInventoryItem (Lot/Batch)
+```prisma
+model ProductInventoryItem {
+  id                  String    @id @default(uuid())
+  inventoryProductId  String
+  quantity            Int       // Original imported quantity
+  remainingQuantity   Int       // Current remaining
+  expiryDate          DateTime?
+  lotNumber           String?
+  createdAt           DateTime  @default(now())
+  updatedAt           DateTime  @updatedAt
+}
+```
+
+### InventorySession
+```prisma
+model InventorySession {
+  id           String                    @id @default(uuid())
+  type         InventoryTransactionType  // IMPORT or EXPORT
+  note         String?
+  userId       String                    // Staff who created
+  transactions InventoryTransaction[]
+  createdAt    DateTime                  @default(now())
+}
+```
+
+### InventoryTransaction
+```prisma
+model InventoryTransaction {
+  id                  String   @id @default(uuid())
+  sessionId           String
+  inventoryProductId  String
+  quantity            Int
+  expiryDate          DateTime?
+  lotNumber           String?
+  orderItemId         String?   // Links to OrderItem when exporting for orders
+  createdAt           DateTime  @default(now())
+}
+```
+
+## Inventory Operations
+
+### Import (Stock In)
+```
+POST /api/v1/inventory/import
+Body: CreateInventorySessionDto {
+  type: "IMPORT",
+  note: "Weekly stock delivery",
+  items: [
+    {
+      inventoryProductId: "uuid",
+      quantity: 100,
+      expiryDate: "2025-12-01",
+      lotNumber: "LOT-2025-001"
+    }
+  ]
+}
+```
+
+**What happens**:
+1. Creates `InventorySession` (type=IMPORT)
+2. For each item:
+   - Creates `InventoryTransaction` record
+   - Creates or updates `ProductInventoryItem` (lot)
+   - Adds quantity to the lot
+
+### Export (Stock Out - Manual)
+```
+POST /api/v1/inventory/export
+Body: CreateInventorySessionDto {
+  type: "EXPORT",
+  note: "Damaged goods removal",
+  items: [
+    { inventoryProductId: "uuid", quantity: 5 }
+  ]
+}
+```
+
+### Export via Order Processing
+When staff processes an order, they select specific lots:
+```
+PATCH /api/v1/order/:id/process
+Body: {
+  items: [{
+    orderItemId: "order-item-uuid",
+    lots: [{
+      inventoryItemId: "lot-uuid",    // ProductInventoryItem
+      quantity: 2
+    }]
+  }]
+}
+```
+
+**What happens**:
+1. Creates `InventorySession` (type=EXPORT)
+2. For each lot selection:
+   - Deducts `remainingQuantity` from `ProductInventoryItem`
+   - Creates `InventoryTransaction` with `orderItemId` link
+3. Order status → PROCESSING
+
+### Inventory Reversal (Order Cancellation)
+When a PROCESSING order is cancelled:
+1. Finds all `InventoryTransaction` records for the order
+2. Adds quantities back to `ProductInventoryItem.remainingQuantity`
+3. Marks transactions as reversed
+
+## Valid Items Query
+
+Get non-expired inventory items with remaining stock:
+```
+GET /api/v1/inventory-product/:id/valid-items
+```
+
+Returns `ProductInventoryItem[]` where:
+- `remainingQuantity > 0`
+- `expiryDate > now()` (or no expiry date)
+- Sorted by expiry date ASC (FIFO)
+
+## Key API Endpoints
+
+### Inventory Products (Warehouse Items)
+```
+GET    /api/v1/inventory-product           — List all inventory products
+GET    /api/v1/inventory-product/:id       — Get with stock details
+POST   /api/v1/inventory-product           — Create warehouse item
+PATCH  /api/v1/inventory-product/:id       — Update warehouse item
+DELETE /api/v1/inventory-product/:id       — Delete warehouse item
+GET    /api/v1/inventory-product/:id/valid-items — Get non-expired lots
+```
+
+### Inventory Sessions (Import/Export)
+```
+GET    /api/v1/inventory                   — List sessions
+GET    /api/v1/inventory/:id               — Get session with transactions
+POST   /api/v1/inventory/import            — Import stock
+POST   /api/v1/inventory/export            — Export stock (manual)
+```
+
+## Business Rules
+
+1. **FIFO** — Use oldest lots first (sorted by expiry date)
+2. **Expiry tracking** — Items past expiry should not be sold
+3. **Lot traceability** — Every export links back to specific lots
+4. **Order linking** — Export transactions link to order items for audit
+5. **Reversal support** — Cancelled orders restore inventory
+6. **Stock check** — Cannot export more than remaining quantity

package/skills/active-life-dev/docs/modules.md

@@ -0,0 +1,181 @@
+# Active Life Backend - All Modules Reference
+
+## Module List (23 total)
+
+### Core Business Modules
+
+#### 1. Auth Module (`src/auth/`)
+- **Controller**: `AuthController` — Login, register, token refresh
+- **Service**: `AuthService` — JWT signing, password hashing, validation
+- **Strategies**: `JwtStrategy` (staff), `JwtClientStrategy` (customer)
+- **Guard**: `JwtAuthGuard` — Global auth guard, checks @Public, checks isBan
+- **DTOs**:
+  - `UserLoginDto` — { phone, password }
+  - `ClientLoginDto` — { phone, password }
+  - `ClientRegisterDto` — { phone, password, name }
+  - `ClientZaloLoginDto` — Zalo OAuth login
+  - `UserRegisterDto` — Staff registration (admin only)
+  - `AdminUpdateUserDto` — Admin updates user profile
+
+#### 2. Product Module (`src/product/`)
+- **Controller**: `ProductController` — CRUD products, combo management
+- **Service**: `ProductService` — Product operations, combo logic, slug generation
+- **DTOs**:
+  - `CreateProductDto` — { name, description, images, categoryIds, brandId, unitId, status }
+  - `UpdateProductDto` — Partial of create
+  - `CreateProductComboDto` — { name, price, comparePrice, items[] }
+  - `UpdateProductComboDto` — Partial of combo create
+  - `AddComboToProductDto` — Add combo to product
+  - `AddComboGiftDto` — Add gift items to combo
+  - `ComboItemDto` — { inventoryProductId, quantity }
+
+#### 3. Order Module (`src/order/`)
+- **Controller**: `OrderController` — Create, process, ship, deliver, cancel, refund, return
+- **Service**: `OrderService` — Order lifecycle, inventory deduction, status flow
+- **DTOs**:
+  - `CreateOrderDto` — Customer creates order
+  - `StaffCreateOrderDto` — Staff creates order on behalf
+  - `CreateOrderItemDto` — { productId, comboId, quantity }
+  - `UpdateOrderStatusDto` — Change order status
+  - `UpdateOrderFlowDto` — Process order through stages
+  - `CancelOrderDto` — { reason }
+  - `ProcessOrderDto` — Process with lot selection
+  - `ProcessOrderItemLotDto` — Assign inventory lots to items
+  - `RefundOrderDto` — Initiate refund
+  - `RefundRequestDto`, `CreateRefundRequestDto`, `CompleteRefundRequestDto` — Refund workflow
+  - `ReturnRequestDto`, `CreateReturnRequestDto`, `CompleteReturnRequestDto` — Return workflow
+  - `OrderRequestDto` — Query/filter orders
+
+#### 4. Inventory Module (`src/inventory/`)
+- **Controller**: `InventoryController` — Import/export sessions
+- **Service**: `InventoryService` — Session management, transaction creation
+- **DTOs**:
+  - `CreateInventorySessionDto` — { type, items[], note }
+  - `CreateInventoryItemDto` — { inventoryProductId, quantity, expiryDate, lotNumber }
+
+#### 5. Inventory Product Module (`src/inventory-product/`)
+- **Controller**: `InventoryProductController` — Warehouse product CRUD
+- **Service**: `InventoryProductService` — Stock tracking, valid items
+- **DTOs**:
+  - `CreateInventoryProductDto` — { name, sku, unitId, brandId }
+  - `UpdateInventoryProductDto` — Partial update
+  - `GetValidItemsDto` — Filter non-expired items
+
+#### 6. Category Module (`src/category/`)
+- **Controller**: `CategoryController` — Hierarchical category CRUD
+- **Service**: `CategoryService` — Recursive queries, slug generation
+- **DTOs**:
+  - `CreateCategoryDto` — { name, parentId?, image?, description? }
+  - `UpdateCategoryDto` — Partial update
+
+#### 7. Brand Module (`src/brand/`)
+- **Controller**: `BrandController` — Brand CRUD
+- **Service**: `BrandService` — Brand operations
+- **DTOs**:
+  - `CreateBrandDto` — { name, image?, description? }
+  - `UpdateBrandDto` — Partial update
+
+#### 8. Voucher Module (`src/voucher/`)
+- **Controller**: `VoucherController` — Voucher CRUD, redemption
+- **Service**: `VoucherService` — Voucher lifecycle, usage tracking
+- **DTOs**:
+  - `CreateVoucherDto` — { code, type, value, minOrder, maxDiscount, expiryDate, quantity }
+  - `UpdateVoucherDto` — Partial update
+  - `RedeemVoucherDto` — { code, orderId }
+
+#### 9. Client Module (`src/client/`)
+- **Controller**: `ClientController` — Customer CRUD, self-update
+- **Service**: `ClientService` — Customer management, assignment
+- **DTOs**:
+  - `CreateClientDto` — { phone, name, email?, address? }
+  - `UpdateClientDto` — Staff updates client
+  - `UpdateClientSelfDto` — Client updates own profile
+  - `UpdateBankInfoDto` — { bankName, accountNumber, accountHolder }
+
+#### 10. Cart Module (`src/cart/`)
+- **Controller**: `CartController` — Add, update, remove items, checkout
+- **Service**: `CartService` — Cart operations, checkout flow
+- **DTOs**:
+  - `AddToCartDto` — { productId, comboId, quantity }
+  - `UpdateCartItemDto` — { quantity }
+  - `CheckoutDto` — { voucherCode?, paymentMethod, shippingAddress }
+
+#### 11. User Module (`src/user/`)
+- **Controller**: `UserController` — Staff profile management
+- **Service**: `UserService` — Staff CRUD
+- **DTOs**:
+  - `UpdateUserDto` — Update staff profile
+  - `UpdatePasswordDto` — { oldPassword, newPassword }
+
+#### 12. Role Module (`src/role/`)
+- **Controller**: `RoleController` — Role CRUD (Admin only)
+- **Service**: `RoleService` — Role management
+- **No DTOs** — Uses inline types
+
+### CRM / Lookup Modules
+
+#### 13. Customer Source (`src/customer-source/`)
+- Lookup table for where customers come from (Facebook, Zalo, Walk-in, etc.)
+- **DTO**: `CreateCustomerSourceDto` — { name, description? }
+
+#### 14. Customer Status (`src/customer-status/`)
+- Lookup table for customer lifecycle status (New, Active, Inactive, etc.)
+- **DTO**: `CreateCustomerStatusDto` — { name, description? }
+
+#### 15. Customer Detail Status (`src/customer-detail-status/`)
+- Granular customer status (Interested, Following Up, Purchased, etc.)
+- **DTO**: `CreateCustomerDetailStatusDto` — { name, description? }
+
+#### 16. Interaction Status (`src/interaction-status/`)
+- Call/chat interaction statuses (Connected, No Answer, Busy, etc.)
+- **DTO**: `CreateInteractionStatusDto` — { name, description? }
+
+#### 17. Interaction Result (`src/interaction-result/`)
+- Outcomes of customer interactions (Interested, Not Interested, Callback, etc.)
+- **DTO**: `CreateInteractionResultDto` — { name, description? }
+
+#### 18. Interaction Type (`src/interaction-type/`)
+- Types of interactions (Phone Call, Zalo Chat, In-store, etc.)
+- **DTO**: `CreateInteractionTypeDto` — { name, description? }
+
+### Utility Modules
+
+#### 19. Unit Module (`src/unit/`)
+- Units of measurement (kg, liter, box, piece, etc.)
+- **DTOs**: `CreateUnitDto`, `UpdateUnitDto` — { name, abbreviation? }
+
+#### 20. Report Module (`src/report/`)
+- Business analytics and reporting
+- **No DTOs** — Query params based
+
+#### 21. Seed Module (`src/seed/`)
+- Database seeding for development/staging
+- **No DTOs** — Hardcoded seed data
+
+#### 22. Etelecom Module (`src/etelecom/`)
+- SIP phone system integration for call center
+- **DTOs**:
+  - `CreateEtelecomExtensionDto` — { extensionNumber, extensionPassword, tenantId, tenantDomain }
+  - `LinkStaffExtensionDto` — { userId, extensionId }
+  - `WebhookBodyDto` — Incoming call webhook data
+
+---
+
+## Module Import Pattern
+
+All modules are imported in `src/app.module.ts`:
+
+```typescript
+@Module({
+  imports: [
+    ConfigModule.forRoot({ isGlobal: true }),
+    ThrottlerModule.forRoot([{ ttl: 60000, limit: 10 }]),
+    // ... all feature modules
+    AuthModule,
+    ProductModule,
+    OrderModule,
+    // etc.
+  ],
+})
+export class AppModule {}
+```