ginskill-init 2.7.0

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

@@ -0,0 +1,180 @@
+# Active Life Backend - Order System
+
+## Order Lifecycle
+
+```
+PENDING → PROCESSING → SHIPPED → DELIVERED
+    │          │           │
+    ▼          ▼           ▼
+CANCELLED  CANCELLED   RETURN_PENDING → RETURN_RECEIVED → DELIVERED (restocked)
+                                │
+                                ▼
+                        RETURN_REJECTED
+
+                        REFUND_PENDING → REFUNDED
+```
+
+## Order Statuses (OrderStatus enum)
+
+| Status | Description | Triggered By |
+|--------|------------|-------------|
+| `PENDING` | New order, awaiting processing | Customer/Staff creates order |
+| `PROCESSING` | Staff processing, selecting inventory lots | Staff processes order |
+| `SHIPPED` | Order shipped to customer | Staff marks as shipped |
+| `DELIVERED` | Customer received order | Staff confirms delivery |
+| `CANCELLED` | Order cancelled | Customer or staff cancels |
+| `RETURN_PENDING` | Return requested | Customer requests return |
+| `RETURN_RECEIVED` | Returned items received | Staff confirms receipt |
+| `RETURN_REJECTED` | Return request rejected | Staff rejects return |
+| `REFUND_PENDING` | Refund in progress | Staff initiates refund |
+| `REFUNDED` | Refund completed | Staff completes refund |
+
+## Order Model
+
+```prisma
+model Order {
+  id              String        @id @default(uuid())
+  orderCode       String        @unique    // Human-readable code
+  clientId        String
+  status          OrderStatus   @default(PENDING)
+  paymentMethod   PaymentMethod            // CASH or TRANSFER
+  totalAmount     Float                    // Sum of items
+  discountAmount  Float         @default(0) // Voucher discount
+  finalAmount     Float                    // totalAmount - discountAmount + shippingFee
+  shippingAddress String?
+  shippingFee     Float         @default(0)
+  note            String?
+  voucherId       String?
+  staffId         String?                  // Staff who processed
+}
+```
+
+## Order Flow
+
+### 1. Customer Creates Order
+```
+POST /api/v1/order (with jwt-client auth)
+Body: CreateOrderDto {
+  items: [{ productId, comboId, quantity }],
+  paymentMethod: "CASH" | "TRANSFER",
+  shippingAddress: string,
+  voucherCode?: string,
+  note?: string
+}
+```
+- Validates product/combo availability
+- Applies voucher if provided
+- Calculates totals
+- Creates Order + OrderItems
+- Creates LogOrder (CREATE)
+
+### 2. Staff Creates Order (on behalf)
+```
+POST /api/v1/order/staff-create (staff auth)
+Body: StaffCreateOrderDto {
+  clientId: string,
+  items: [...],
+  paymentMethod: ...,
+  ...
+}
+```
+
+### 3. Process Order (assign inventory)
+```
+PATCH /api/v1/order/:id/process (staff auth)
+Body: ProcessOrderDto {
+  items: [{
+    orderItemId: string,
+    lots: [{
+      inventoryItemId: string,  // ProductInventoryItem
+      quantity: number
+    }]
+  }]
+}
+```
+- Staff selects specific inventory lots (FIFO by expiry)
+- Deducts inventory quantities
+- Creates InventoryTransactions (EXPORT type)
+- Status: PENDING → PROCESSING
+
+### 4. Ship Order
+```
+PATCH /api/v1/order/:id/ship (staff auth)
+```
+- Status: PROCESSING → SHIPPED
+- Creates LogOrder (SHIP)
+
+### 5. Deliver Order
+```
+PATCH /api/v1/order/:id/deliver (staff auth)
+```
+- Status: SHIPPED → DELIVERED
+- Creates LogOrder (DELIVER)
+- Awards loyalty points to client
+
+### 6. Cancel Order
+```
+PATCH /api/v1/order/:id/cancel (staff or client auth)
+Body: CancelOrderDto { reason: string }
+```
+- Status: PENDING/PROCESSING → CANCELLED
+- If PROCESSING: reverses inventory deductions
+- Creates LogOrder (CANCEL_CLIENT or CANCEL_STAFF)
+
+### 7. Return Request
+```
+POST /api/v1/order/:id/return-request (client or staff)
+Body: CreateReturnRequestDto { reason, items[] }
+```
+- Status: DELIVERED → RETURN_PENDING
+- Creates LogOrder (RETURN_CREATE)
+
+### 8. Complete Return
+```
+PATCH /api/v1/order/:id/return-complete (staff)
+Body: CompleteReturnRequestDto { action: "receive" | "reject" }
+```
+- If receive: RETURN_PENDING → RETURN_RECEIVED, restock inventory
+- If reject: RETURN_PENDING → RETURN_REJECTED
+
+### 9. Refund Request
+```
+POST /api/v1/order/:id/refund-request (staff)
+Body: CreateRefundRequestDto { amount, reason }
+```
+- Status: → REFUND_PENDING
+
+### 10. Complete Refund
+```
+PATCH /api/v1/order/:id/refund-complete (staff)
+```
+- Status: REFUND_PENDING → REFUNDED
+- Creates LogOrder (REFUND_COMPLETE)
+
+## Audit Trail (LogOrder)
+
+Every status change creates a log entry:
+```prisma
+model LogOrder {
+  id        String       @id @default(uuid())
+  orderId   String
+  type      LogOrderType // CREATE, PROCESS, SHIP, DELIVER, CANCEL_*, RETURN_*, REFUND_*
+  note      String?
+  userId    String?      // Staff who made the change
+  createdAt DateTime     @default(now())
+}
+```
+
+## Payment Methods
+- `CASH` — Cash on delivery
+- `TRANSFER` — Bank transfer
+
+## Key Business Rules
+1. Only PENDING orders can be processed
+2. Only PROCESSING orders can be shipped
+3. Only SHIPPED orders can be delivered
+4. Only PENDING/PROCESSING orders can be cancelled
+5. Only DELIVERED orders can have return requests
+6. Cancellation of PROCESSING orders must reverse inventory
+7. Points are awarded only on DELIVERED status
+8. Order code is auto-generated and unique

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

@@ -0,0 +1,319 @@
+# Active Life Backend - Coding Patterns & Conventions
+
+## Project Structure Convention
+
+Every feature module follows this structure:
+```
+src/<module-name>/
+├── <module-name>.module.ts
+├── <module-name>.controller.ts
+├── <module-name>.service.ts
+└── dto/
+    ├── create-<module-name>.dto.ts
+    └── update-<module-name>.dto.ts
+```
+
+## Module Pattern
+
+```typescript
+import { Module } from '@nestjs/common';
+import { XxxController } from './xxx.controller';
+import { XxxService } from './xxx.service';
+
+@Module({
+  controllers: [XxxController],
+  providers: [XxxService],
+  exports: [XxxService],  // Only if other modules need this service
+})
+export class XxxModule {}
+```
+
+## Controller Pattern
+
+```typescript
+import { Controller, Get, Post, Body, Param, Query, Patch, Delete } from '@nestjs/common';
+import { ApiTags, ApiBearerAuth, ApiOperation } from '@nestjs/swagger';
+import { Public } from 'src/decorators/customize';
+import { ResponseMessage, User } from 'src/decorators/customize';
+import { IUser } from 'src/interface/users.interface';
+
+@Controller('xxx')
+@ApiTags('xxx')
+export class XxxController {
+  constructor(private readonly xxxService: XxxService) {}
+
+  @Post()
+  @ApiBearerAuth()
+  @ApiOperation({ summary: 'Create xxx' })
+  @ResponseMessage('Created successfully')
+  create(@Body() dto: CreateXxxDto, @User() user: IUser) {
+    return this.xxxService.create(dto, user);
+  }
+
+  @Get()
+  @Public()
+  @ApiOperation({ summary: 'Get all xxx' })
+  findAll(@Query() query: any) {
+    return this.xxxService.findAll(query);
+  }
+
+  @Get(':id')
+  @Public()
+  findOne(@Param('id') id: string) {
+    return this.xxxService.findOne(id);
+  }
+
+  @Patch(':id')
+  @ApiBearerAuth()
+  update(@Param('id') id: string, @Body() dto: UpdateXxxDto) {
+    return this.xxxService.update(id, dto);
+  }
+
+  @Delete(':id')
+  @ApiBearerAuth()
+  remove(@Param('id') id: string) {
+    return this.xxxService.remove(id);
+  }
+}
+```
+
+## Service Pattern
+
+```typescript
+import { Injectable, BadRequestException, NotFoundException } from '@nestjs/common';
+import { PrismaService } from 'src/prisma/prisma.service';
+
+@Injectable()
+export class XxxService {
+  constructor(private prismaService: PrismaService) {}
+
+  async create(dto: CreateXxxDto, user?: IUser) {
+    // Check for duplicates if needed
+    const existing = await this.prismaService.xxx.findUnique({
+      where: { name: dto.name },
+    });
+    if (existing) {
+      throw new BadRequestException('Already exists');
+    }
+
+    return this.prismaService.xxx.create({
+      data: {
+        ...dto,
+        slug: this.generateSlug(dto.name),  // If applicable
+      },
+    });
+  }
+
+  async findAll(query: any) {
+    const { page = 1, limit = 10, search } = query;
+    const skip = (page - 1) * limit;
+
+    const where = search
+      ? { name: { contains: search, mode: 'insensitive' as const } }
+      : {};
+
+    const [data, total] = await Promise.all([
+      this.prismaService.xxx.findMany({
+        where,
+        skip,
+        take: +limit,
+        orderBy: { createdAt: 'desc' },
+      }),
+      this.prismaService.xxx.count({ where }),
+    ]);
+
+    return {
+      data,
+      meta: {
+        total,
+        page: +page,
+        limit: +limit,
+        totalPages: Math.ceil(total / +limit),
+      },
+    };
+  }
+
+  async findOne(id: string) {
+    const item = await this.prismaService.xxx.findUnique({
+      where: { id },
+      include: { /* relations */ },
+    });
+    if (!item) {
+      throw new NotFoundException('Not found');
+    }
+    return item;
+  }
+
+  async update(id: string, dto: UpdateXxxDto) {
+    await this.findOne(id);  // Ensure exists
+    return this.prismaService.xxx.update({
+      where: { id },
+      data: dto,
+    });
+  }
+
+  async remove(id: string) {
+    await this.findOne(id);  // Ensure exists
+    return this.prismaService.xxx.delete({ where: { id } });
+  }
+}
+```
+
+## DTO Pattern
+
+```typescript
+import { ApiProperty } from '@nestjs/swagger';
+import { IsString, IsNotEmpty, IsOptional, IsNumber, IsEnum, IsArray } from 'class-validator';
+import { Type } from 'class-transformer';
+
+export class CreateXxxDto {
+  @ApiProperty({ example: 'Example name' })
+  @IsString()
+  @IsNotEmpty()
+  name: string;
+
+  @ApiProperty({ required: false })
+  @IsOptional()
+  @IsString()
+  description?: string;
+
+  @ApiProperty({ example: 100 })
+  @IsNumber()
+  @Type(() => Number)  // For query params auto-conversion
+  price: number;
+
+  @ApiProperty({ enum: ProductStatus })
+  @IsEnum(ProductStatus)
+  status: ProductStatus;
+
+  @ApiProperty({ type: [String] })
+  @IsArray()
+  @IsString({ each: true })
+  images: string[];
+}
+```
+
+**Update DTO** — typically partial:
+```typescript
+import { PartialType } from '@nestjs/mapped-types';
+import { CreateXxxDto } from './create-xxx.dto';
+
+export class UpdateXxxDto extends PartialType(CreateXxxDto) {}
+```
+
+## Response Format
+
+All responses are wrapped by `TransformInterceptor`:
+```typescript
+// Success response
+{
+  "statusCode": 200,
+  "message": "Success",  // From @ResponseMessage() or default
+  "data": { ... }        // Actual data
+}
+
+// Error response (from exceptions)
+{
+  "statusCode": 400,
+  "message": "Bad Request",
+  "error": "Detailed error message"
+}
+```
+
+## Slug Generation
+
+Vietnamese-aware slug generation (remove diacritics):
+```typescript
+private generateSlug(name: string): string {
+  return name
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')  // Remove diacritics
+    .replace(/đ/g, 'd').replace(/Đ/g, 'D')
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, '')
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-')
+    .trim();
+}
+```
+
+## Pagination Pattern
+
+Services return paginated data with meta:
+```typescript
+{
+  data: [...items],
+  meta: {
+    total: 100,
+    page: 1,
+    limit: 10,
+    totalPages: 10
+  }
+}
+```
+
+## Error Handling
+
+Use NestJS built-in exceptions:
+```typescript
+throw new BadRequestException('Validation error message');
+throw new NotFoundException('Resource not found');
+throw new ForbiddenException('Access denied');
+throw new UnauthorizedException('Invalid credentials');
+```
+
+## Naming Conventions
+
+- **Files**: kebab-case (`create-product.dto.ts`)
+- **Classes**: PascalCase (`CreateProductDto`)
+- **Methods**: camelCase (`findAll`, `createOrder`)
+- **Database tables**: PascalCase in Prisma schema (auto-mapped to snake_case)
+- **API routes**: kebab-case (`/api/v1/inventory-product`)
+- **Env vars**: SCREAMING_SNAKE_CASE (`JWT_CLIENT_ACCESS_TOKEN_SECRET`)
+
+## Import Conventions
+
+```typescript
+// NestJS core
+import { Injectable, Controller, Module } from '@nestjs/common';
+// Swagger
+import { ApiTags, ApiBearerAuth, ApiProperty } from '@nestjs/swagger';
+// Validation
+import { IsString, IsNotEmpty } from 'class-validator';
+// Project internals (absolute paths from src/)
+import { PrismaService } from 'src/prisma/prisma.service';
+import { Public, User, ResponseMessage } from 'src/decorators/customize';
+import { IUser } from 'src/interface/users.interface';
+```
+
+## Logging
+
+The `LoggingInterceptor` automatically logs:
+- HTTP method, URL, IP
+- User info (if authenticated)
+- Response status code
+- Execution time (ms)
+- Error details on failure
+
+No need to add manual logging in services unless debugging specific flows.
+
+## Global Configuration (main.ts)
+
+```typescript
+// Applied globally:
+app.useGlobalGuards(new JwtAuthGuard(...));           // Auth on all routes
+app.useGlobalPipes(new ValidationPipe({
+  whitelist: true,           // Strip unknown properties
+  transform: true,           // Auto-transform types
+  transformOptions: { enableImplicitConversion: true },
+}));
+app.useGlobalInterceptors(
+  new LoggingInterceptor(),
+  new TransformInterceptor(reflector),
+);
+
+// CORS: all origins allowed
+// Rate limit: 10 requests / 60 seconds
+// API versioning: URI-based (/api/v1/, /api/v2/)
+// Swagger at /api
+```

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

@@ -0,0 +1,216 @@
+# Active Life Backend - Products & Catalog
+
+## Product Architecture
+
+```
+Category (hierarchical tree)
+    └──< CategoryBrand >── Brand
+    └──< ProductCategory >── StoreProduct
+                                └──< StoreProductCombo (pricing/bundle)
+                                        └──< StoreProductComboItem ──> InventoryProduct
+                                        └──< StoreProductComboItem (gifts) ──> InventoryProduct
+```
+
+### Key Concept: Product vs Combo vs Inventory Product
+
+- **StoreProduct** — What customers see (name, images, description, status)
+- **StoreProductCombo** — A purchasable configuration with price (e.g., "Pack of 3", "Family Bundle")
+- **StoreProductComboItem** — Links combo to warehouse inventory products with quantities
+- **InventoryProduct** — Actual warehouse item (SKU, barcode, unit, brand)
+
+**Example**:
+```
+StoreProduct: "Whey Protein Gold Standard"
+  ├── Combo: "1kg Bag" — price: 500,000 VND
+  │     └── Item: InventoryProduct("WP-GS-1KG") × 1
+  ├── Combo: "2kg Bag + Shaker" — price: 900,000 VND
+  │     ├── Item: InventoryProduct("WP-GS-2KG") × 1
+  │     └── Gift: InventoryProduct("SHAKER-01") × 1
+  └── Combo: "5kg Bulk" — price: 2,000,000 VND
+        └── Item: InventoryProduct("WP-GS-1KG") × 5
+```
+
+## Categories
+
+### Hierarchical Structure (Parent-Child)
+```prisma
+model Category {
+  id       String     @id @default(uuid())
+  name     String
+  slug     String     @unique
+  parentId String?
+  parent   Category?  @relation("CategoryTree", fields: [parentId], references: [id])
+  children Category[] @relation("CategoryTree")
+}
+```
+
+**Example tree**:
+```
+Supplements
+  ├── Protein
+  │     ├── Whey Protein
+  │     └── Casein Protein
+  ├── Pre-Workout
+  └── Vitamins
+Equipment
+  ├── Weights
+  └── Accessories
+```
+
+### Recursive Category Queries
+The service uses raw SQL for recursive queries to get full category trees:
+```sql
+WITH RECURSIVE category_tree AS (
+  SELECT * FROM "Category" WHERE "parentId" IS NULL
+  UNION ALL
+  SELECT c.* FROM "Category" c
+  JOIN category_tree ct ON c."parentId" = ct.id
+)
+SELECT * FROM category_tree;
+```
+
+### Category-Brand Relationship
+Many-to-many via `CategoryBrand` join table. A category can have multiple brands, and a brand can appear in multiple categories.
+
+## Products
+
+### StoreProduct Model
+```prisma
+model StoreProduct {
+  id          String        @id @default(uuid())
+  name        String
+  slug        String        @unique
+  description String?
+  images      String[]                         // Array of image URLs
+  status      ProductStatus @default(NORMAL)   // HIDDEN, NORMAL, HIGH
+}
+```
+
+### Product Status
+- `HIDDEN` — Not visible to customers
+- `NORMAL` — Standard visibility
+- `HIGH` — Featured/promoted product
+
+### Creating a Product
+```
+POST /api/v1/product
+Body: {
+  name: "Whey Protein Gold Standard",
+  description: "Premium whey protein...",
+  images: ["url1", "url2"],
+  categoryIds: ["cat-uuid-1", "cat-uuid-2"],
+  status: "NORMAL"
+}
+```
+Auto-generates slug from name (Vietnamese diacritics removed).
+
+## Combos (Product Pricing)
+
+### StoreProductCombo Model
+```prisma
+model StoreProductCombo {
+  id           String  @id @default(uuid())
+  name         String
+  price        Float
+  comparePrice Float?   // "Was" price for showing discounts
+  productId    String
+  items        StoreProductComboItem[]       // Regular items
+  giftItems    StoreProductComboItem[]       // Gift items
+}
+```
+
+### Creating a Combo
+```
+POST /api/v1/product/:id/combo
+Body: {
+  name: "1kg Bag",
+  price: 500000,
+  comparePrice: 600000,
+  items: [
+    { inventoryProductId: "inv-uuid", quantity: 1 }
+  ]
+}
+```
+
+### Adding Gift Items
+```
+POST /api/v1/product/:id/combo/:comboId/gift
+Body: {
+  items: [
+    { inventoryProductId: "shaker-uuid", quantity: 1 }
+  ]
+}
+```
+
+### Promotion History
+When combo price changes, a history record is created:
+```prisma
+model StoreProductComboPromotionHistory {
+  comboId   String
+  oldPrice  Float
+  newPrice  Float
+  reason    String?
+  createdAt DateTime @default(now())
+}
+```
+
+## Brands
+
+```prisma
+model Brand {
+  id          String @id @default(uuid())
+  name        String
+  slug        String @unique
+  image       String?
+  description String?
+}
+```
+
+## Key API Endpoints
+
+### Products
+```
+GET    /api/v1/product              — List products (public, paginated)
+GET    /api/v1/product/:id          — Get product detail (public)
+GET    /api/v1/product/slug/:slug   — Get by slug (public)
+POST   /api/v1/product              — Create product (staff)
+PATCH  /api/v1/product/:id          — Update product (staff)
+DELETE /api/v1/product/:id          — Delete product (staff)
+```
+
+### Combos
+```
+POST   /api/v1/product/:id/combo           — Add combo to product
+PATCH  /api/v1/product/:id/combo/:comboId  — Update combo
+DELETE /api/v1/product/:id/combo/:comboId  — Delete combo
+POST   /api/v1/product/:id/combo/:comboId/gift — Add gift items
+```
+
+### Categories
+```
+GET    /api/v1/category             — List categories (tree structure, public)
+GET    /api/v1/category/:id         — Get category with products (public)
+POST   /api/v1/category             — Create category (staff)
+PATCH  /api/v1/category/:id         — Update category (staff)
+DELETE /api/v1/category/:id         — Delete category (staff)
+```
+
+### Brands
+```
+GET    /api/v1/brand                — List brands (public)
+POST   /api/v1/brand                — Create brand (staff)
+PATCH  /api/v1/brand/:id            — Update brand (staff)
+DELETE /api/v1/brand/:id            — Delete brand (staff)
+```
+
+## Shopping Cart Integration
+
+Cart items reference both product and combo:
+```prisma
+model CartItem {
+  productId String
+  comboId   String
+  quantity  Int
+}
+```
+Customers add combos to cart, not raw products.