# Kế Hoạch Triển Khai & Nhật Ký Thay Đổi: Hợp Nhất Vật Tư Đơn Hàng (OrderItemMaterials)

Tài liệu này ghi lại chi tiết các thay đổi trong source code của dự án `web-kingston` thuộc gói công việc nâng cấp hệ thống vật tư đóng gói và sản xuất đính kèm đơn hàng.

---

## 1. Bản Đồ Thay Đổi File (File Change Matrix)

Dưới đây là sơ đồ tóm tắt các files đã được tạo mới, sửa đổi hoặc xóa trong quá trình nâng cấp hệ thống:

```
packages/main-app/src/clean-architecture/
├── domain/
│   ├── entities/
│   │   ├── OrderItemMaterial.ts          [NEW] Core entity & builder
│   │   └── Order.ts                      [MODIFY] Thay thế orderPackagingMaterials bằng materials
│   └── repositories/
│       └── OrderItemMaterialRepository.ts [NEW] Định nghĩa interface repo
├── di/
│   ├── types.ts                          [MODIFY] Khai báo các TYPES token mới
│   └── container.ts                      [MODIFY] Binding các UseCase & ApiRepository
├── infrastructure/
│   ├── api/
│   │   ├── types/
│   │   │   ├── OrderItemMaterialResponse.ts [NEW] Response API type
│   │   │   └── OrderResponse.ts          [MODIFY] Cập nhật list materials trong OrderItem
│   │   ├── message/
│   │   │   └── OrderItemMaterialMessage.ts [NEW] Định nghĩa dịch mã lỗi từ API
│   │   ├── mapper/
│   │   │   ├── OrderItemMaterialMapper.ts [NEW] Map JSON sang Domain Entity
│   │   │   └── OrderMapper.ts            [MODIFY] Map list materials của dòng đơn
│   │   └── OrderItemMaterialApiRepository.ts [NEW] Gọi các endpoint REST API hợp nhất
│   └── services/
│       └── ErrorService.ts               [MODIFY] Đăng ký domain lỗi mới
├── application/
│   └── useCases/
│       └── order-item-material/          [NEW] Thư mục chứa 4 Use Case
│           ├── GetOrderItemMaterials.ts
│           ├── CreateOrderItemMaterial.ts
│           ├── UpdateOrderItemMaterial.ts
│           ├── DeleteOrderItemMaterial.ts
│           └── index.ts                  [NEW] Export use cases
└── presentation/
    ├── viewModels/
    │   └── OrderItemView.tsx             [MODIFY] Property materials thay thế packagingMaterials
    ├── forms/
    │   ├── order-item-material/
    │   │   └── OrderItemMaterialFormValues.ts [NEW] Form values interface với type
    │   └── order/
    │       └── OrderFormValues.ts        [MODIFY] Thay packagingMaterials bằng orderItemMaterials
    └── modules/
        └── order/
            ├── components/
            │   ├── OrderForm/            [MODIFY] Hỗ trợ thêm vật tư có Type selector
            │   ├── OrderItemMaterialForm/ [NEW] Form nhập liệu vật tư hợp nhất
            │   └── OrderItemMaterialFormModal/ [NEW] Modal hội thoại
            ├── hooks/
            │   ├── useGetOrderItemMaterials.tsx [NEW] Hook React Query Get
            │   ├── useCreateOrderItemMaterial.tsx [NEW] Hook React Query Post
            │   ├── useUpdateOrderItemMaterial.tsx [NEW] Hook React Query Put
            │   ├── useDeleteOrderItemMaterial.tsx [NEW] Hook React Query Delete
            │   └── useOrderItemMaterialActions.tsx [NEW] Hook xử lý mutations & invalidate cache
            ├── mappers.ts                [MODIFY] Map Form Values ↔ DTOs
            └── components/pages/order/DetailOrderMaterials/
                └── DetailOrderMaterials.tsx [MODIFY] Trực quan hóa tab kép & bộ lọc cột
```

---

## 2. Chi Tiết Thay Đổi Theo Từng Lớp (Layer Breakdown)

### A. Lớp Domain (Domain Layer)
*   **[OrderItemMaterial.ts](file:///Users/lcnghia95/workspace/kingston/web-kingston/packages/main-app/src/clean-architecture/domain/entities/OrderItemMaterial.ts)**:
    *   Thực thể lõi biểu diễn vật tư đính kèm với 2 loại: `PRODUCTION` (Sản xuất) và `PACKAGING` (Đóng gói) dựa trên enum `EOrderItemMaterialType`.
    *   Hỗ trợ `OrderItemMaterialBuilder` để xây dựng thực thể linh hoạt.
*   **[OrderItemMaterialRepository.ts](file:///Users/lcnghia95/workspace/kingston/web-kingston/packages/main-app/src/clean-architecture/domain/repositories/OrderItemMaterialRepository.ts)**:
    *   Khai báo interface chuẩn giao tiếp: `getOrderItemMaterials`, `createOrderItemMaterial`, `updateOrderItemMaterial`, `deleteOrderItemMaterial`.
*   **[Order.ts](file:///Users/lcnghia95/workspace/kingston/web-kingston/packages/main-app/src/clean-architecture/domain/entities/Order.ts)**:
    *   Cập nhật `IOrderItem` và `OrderItem` để sở hữu thuộc tính `materials: OrderItemMaterial[]` thay cho `orderPackagingMaterials: OrderPackagingMaterial[]`.

### B. Lớp Infrastructure (Infrastructure Layer)
*   **[OrderItemMaterialApiRepository.ts](file:///Users/lcnghia95/workspace/kingston/web-kingston/packages/main-app/src/clean-architecture/infrastructure/api/OrderItemMaterialApiRepository.ts)**:
    *   Triển khai gọi các API qua `ApiService`:
        *   `GET /api/admin/order-items/:itemId/materials`
        *   `POST /api/admin/order-items/:itemId/materials`
        *   `PUT /api/admin/order-items/:itemId/materials/:id`
        *   `DELETE /api/admin/order-items/:itemId/materials/:id`
*   **[OrderItemMaterialMapper.ts](file:///Users/lcnghia95/workspace/kingston/web-kingston/packages/main-app/src/clean-architecture/infrastructure/api/mapper/OrderItemMaterialMapper.ts)**:
    *   Chuyển đổi dữ liệu thô (với định dạng số từ REST API) sang kiểu thực thể Domain (chuỗi `ID` và định dạng enum chuẩn).
*   **[ErrorService.ts](file:///Users/lcnghia95/workspace/kingston/web-kingston/packages/main-app/src/clean-architecture/infrastructure/services/ErrorService.ts)**:
    *   Bổ sung domain `orderItemMaterial` và liên kết với file dịch mã lỗi từ API giúp hiển thị thông báo lỗi thân thiện trên UI.

### C. Lớp Application (Application Layer)
*   **Use Cases (`order-item-material/`)**:
    *   Tách biệt logic thực thi của từng chức năng nghiệp vụ (Get, Create, Update, Delete) ra thành 4 lớp đơn nhiệm, tuân thủ nguyên tắc SOLID.
*   **Dependency Injection (DI)**:
    *   Đăng ký và liên kết toàn bộ repository/use case mới trong container hệ thống giúp quản lý vòng đời và phụ thuộc tự động.

### D. Lớp Presentation (Presentation Layer)
*   **[DetailOrderMaterials.tsx](file:///Users/lcnghia95/workspace/kingston/web-kingston/packages/main-app/src/clean-architecture/presentation/components/pages/order/DetailOrderMaterials/DetailOrderMaterials.tsx)**:
    *   Tích hợp bộ chọn Tab Kép: **"Sản xuất"** và **"Đóng gói"**.
    *   Khi ở tab **Sản xuất**: Bảng vật tư ẩn cột đóng gói, hiển thị các cột lắp ráp (`SL Lắp ráp`, `SL Extra`).
    *   Khi ở tab **Đóng gói**: Ẩn các cột sản xuất, hiển thị cột đóng gói (`SL Đóng gói`).
    *   Lọc thông minh: Hàm `buildAllRows` và `buildOrderItemRows` tự động phân tách định mức Variant và các vật tư tự tạo vào tab tương ứng.
*   **Form & Modals**:
    *   Thêm mới cấu trúc form nhập liệu `OrderItemMaterialForm` và modal `OrderItemMaterialFormModal` hỗ trợ thêm/sửa cho cả hai loại vật tư bằng select box động.
    *   Cập nhật `OrderForm` khi khởi tạo đơn hàng: cho phép Planner thêm đồng thời nhiều vật tư tùy chỉnh thuộc cả hai loại sản xuất/đóng gói trực tiếp trên giao diện tạo đơn.

---

## 3. Quy Trình Xác Minh & Kiểm Thử (UAT Verification)

1.  **Biên dịch & Kiểm tra Tĩnh (Compile Verification)**:
    *   Chạy thành công lệnh typecheck toàn dự án: `bun run tsc --noEmit` ở thư mục `packages/main-app` với kết quả **0 lỗi** biên dịch.
    *   Chạy rebuild gói giao diện dùng chung: `bun run build:ui` thành công.
2.  **Chạy Thử Nghiệm Cục Bộ (Local Dev Server)**:
    *   Khởi chạy server thành công tại cổng `5173` thông qua lệnh `bun run dev`.
3.  **Kiểm tra Giao Diện Trực Quan**:
    *   Đã truy cập và kiểm thử các tính năng chuyển đổi tab, nút thêm vật tư đính kèm ngoài định mức hoạt động trơn tru trên sa bàn và giao diện thực tế.