> ## Documentation Index
> Fetch the complete documentation index at: https://tomotek.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# US-CLI-06: Tồn kho Chip định danh ở phòng khám

**Mô tả:** Là một người dùng tại phòng khám (Clinic), tôi muốn quản lý tồn kho chip định danh để theo dõi việc sử dụng, báo cáo sự cố, và xử lý trả về kho tổng, đảm bảo kiểm soát chặt chẽ số lượng chip đang quản lý.

### Điều kiện tiên quyết (Pre-conditions)

* Người dùng đã đăng nhập với quyền **Clinic**.
* Phòng khám đã nhận chip từ Admin (trạng thái `In-Clinic`).
* Hệ thống đã có dữ liệu chip được gán cho phòng khám này.

***

### Tiêu chí chấp nhận (Acceptance Criteria - AC)

#### Xem tồn kho tổng quan

* **Dashboard tồn kho:** Hiển thị bảng điều khiển tổng quan về chip đang quản lý tại phòng khám, **chỉ hiển thị chip thuộc clinic** với các trạng thái:
  * Tổng số chip đang có (chỉ chip thuộc clinic này)
  * Số chip đang gửi đến (`Sending-to-Clinic`) - đang chờ Clinic quét mã nhận hàng
  * Số chip chưa sử dụng (`In-Clinic`)
  * Số chip đã kích hoạt (`Activated`)
  * Số chip có vấn đề (`Problem by Clinic`)
  * Số chip đang trả về (`Returning`)
* **Lưu ý quan trọng:** Clinic **KHÔNG** xem được:
  * Chip ở trạng thái `Available` (tại kho tổng Tomotek)
  * Chip ở trạng thái `Problem by TMT` hoặc `Problem by Factory`
  * Chip thuộc các clinic khác
* **Tìm kiếm và lọc:** Cho phép tìm kiếm theo `SN No.`, lọc theo trạng thái (chỉ các trạng thái được phép xem), hoặc theo khoảng thời gian nhận chip.

#### Theo dõi sử dụng chip

* **Lịch sử kích hoạt:** Hiển thị danh sách các chip đã được kích hoạt, bao gồm:
  * `SN No.` của chip
  * Ngày kích hoạt
  * ID thú cưng được gắn chip
  * Nhân viên thực hiện
* **Chi tiết sử dụng:** Khi click vào một chip đã kích hoạt, hiển thị thông tin hồ sơ thú cưng liên kết (ảnh định danh, thông tin tiêm, v.v.) theo quy trình định danh.

#### Quản lý sự cố và chip hỏng

* **Báo cáo sự cố:** Cho phép báo cáo chip bị hỏng, mất hoặc không sử dụng được.
* **Lý do sự cố:** Người dùng nhập lý do chip có vấn đề (ví dụ: hỏng kỹ thuật, mất, không tiêm được, v.v.).
* **Cập nhật trạng thái:** Chip được chuyển sang trạng thái `Problem by Clinic` và loại khỏi danh sách khả dụng.
* **Xác nhận:** Hệ thống yêu cầu xác nhận trước khi cập nhật trạng thái chip.

```mermaid theme={null}
flowchart TD
    A[Clinic phát hiện chip hỏng/mất] --> B[Ghi nhận thông tin sự cố]
    B --> C[Nhập lý do chi tiết]
    C --> D[Admin xác nhận và cập nhật]
    D --> E[Chip chuyển sang Problem by Clinic]
    E --> F[Ghi nhận vào lịch sử audit]
    F --> G[Loại chip khỏi danh sách khả dụng]
```

#### Trả chip về kho tổng

* **Chọn chip trả về:** Cho phép chọn các chip `In-Clinic` (chưa sử dụng) để trả về kho tổng.
* **Tạo yêu cầu trả về:** Hệ thống tạo yêu cầu trả chip, bao gồm danh sách `SN No.` được chọn.
* **Cập nhật trạng thái:** Chip chuyển từ `In-Clinic` sang `Returning` (đang trong quá trình trả về).
* **Tài liệu trả về:** Hệ thống tự động sinh biên bản trả chip để đính kèm khi bàn giao vật lý.
* **Lưu ý:** Sau khi TMT nhận chip, TMT sẽ kiểm tra và cập nhật trạng thái:
  * Nếu chip tốt: chuyển từ `Returning` sang `Available` (nhập lại vào kho tổng TMT và loại khỏi danh sách của Clinic).
  * Nếu chip hỏng: chuyển từ `Returning` sang `Problem by Clinic`

```mermaid theme={null}
flowchart TD
    A[Clinic chọn chip cần trả] --> B[Tạo yêu cầu trả chip]
    B --> C[Chip chuyển sang Returning]
    C --> D[TMT nhận chip và kiểm tra]
    D --> E{Chip có vấn đề?}
    E -->|Không| F[Chip chuyển sang Available]
    E -->|Có| G[Chip chuyển sang Problem by Clinic]
    F --> H[Cập nhật tồn kho TMT]
    G --> I[Ghi nhận sự cố]
    H --> J[Chip có thể được phân phối lại]
    I --> J
```

#### Cảnh báo tồn kho

* **Cảnh báo hết chip:** Khi số lượng chip `In-Clinic` (chưa sử dụng) giảm xuống dưới ngưỡng quy định (ví dụ: \< 5 chip), hệ thống hiển thị cảnh báo.

***

### Gợi ý giao diện (UI/UX Suggestions)

* **Trang Dashboard Tổng quan (Top-level Metrics):**
  * Sử dụng các Widget/Card số liệu lớn đặt trên cùng để làm nổi bật 4 chỉ số cốt lõi: Chip khả dụng (`In-Clinic`), Chip đang giao tới (`Sending`), Chip đã dùng (`Activated`) và Chip lỗi (`Problem`).
  * Gắn kèm biểu đồ tròn (Pie chart) hoặc thanh tiến trình (Progress bar) để Clinic dễ dàng theo dõi tỷ lệ tiêu hao.
* **Bảng dữ liệu (Data Table):**
  * Sử dụng nhãn dán (Badges) với mã màu nhất quán cho từng trạng thái (VD: Xanh lá cho `In-Clinic`, Vàng cho `Sending`, Đỏ cho `Problem`, Xanh dương cho `Returning`).
  * Nút tìm kiếm nhanh và các bộ lọc (Filter) đặt ngay trên đầu bảng.
* **Thao tác nhanh (Quick Actions):**
  * **Nút "Báo lỗi":** Tích hợp dưới dạng icon ở cột thao tác (Action Column) của từng dòng. Bấm vào sẽ mở Popup (Modal) đơn giản để chọn lý do lỗi (Dropdown) và nhập ghi chú.
  * **Chọn nhiều (Bulk Actions):** Hỗ trợ Checkbox ở đầu mỗi dòng để Clinic có thể chọn cùng lúc nhiều chip rồi bấm nút "Trả về TMT" (Return) thay vì thao tác lẻ tẻ từng cái.
* **Khu vực Cảnh báo (Alert Banner):**
  * Sử dụng một thanh ngang (Banner) màu đỏ/cam nổi bật xuất hiện ngay dưới thanh điều hướng (Header) khi kho chip sắp hết (dưới 5 chip).
  * Banner nên kèm theo một nút CTA nhỏ: *"Bấm để yêu cầu Tomotek gửi thêm chip"*.

***

### Quy trình vận hành (Workflow)

1. **Truy cập:** Người dùng tại phòng khám đăng nhập và điều hướng đến màn hình Quản lý tồn kho.
2. **Xem tổng quan:** Kiểm tra số lượng chip theo từng trạng thái.
3. **Theo dõi sử dụng:** Xem lịch sử kích hoạt và chi tiết hồ sơ thú cưng.
4. **Báo cáo sự cố:** Khi phát hiện chip hỏng, thực hiện báo cáo và cập nhật trạng thái.
5. **Trả chip:** Khi có chip chưa sử dụng cần trả về, tạo yêu cầu trả chip.
6. **Xuất báo cáo:** Tạo báo cáo tồn kho định kỳ để đối chiếu.

***

### Sơ đồ trình tự (Sequence Diagram)

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor ClinicUser
    participant UI as Clinic Portal
    participant Service as Inventory Service
    participant DB as Database
    actor TMTUser

    ClinicUser->>UI: Đăng nhập và truy cập tồn kho
    UI->>Service: Yêu cầu dữ liệu tồn kho
    Service->>DB: Truy vấn chip theo Clinic_ID
    DB-->>Service: Trả về danh sách chip
    Service-->>UI: Hiển thị dashboard tồn kho
    UI-->>ClinicUser: Hiển thị tổng quan tồn kho

    ClinicUser->>UI: Báo cáo chip hỏng
    UI->>Service: Gửi lý do chip hỏng
    Service->>DB: Cập nhật Status = Problem by Clinic
    DB-->>Service: Xác nhận thành công
    Service-->>UI: Cập nhật dashboard
    UI-->>ClinicUser: Thông báo thành công

    ClinicUser->>UI: Tạo yêu cầu trả chip
    UI->>Service: Gửi danh sách chip cần trả
    Service->>DB: Cập nhật Status = Returning
    DB-->>Service: Xác nhận
    Service-->>UI: Sinh biên bản trả chip
    UI-->>ClinicUser: Hiển thị biên bản và thông báo

    Note over TMTUser,DB: TMT nhận chip và kiểm tra
    TMTUser->>Service: Cập nhật trạng thái chip sau kiểm tra
    alt Chip tốt
        Service->>DB: Cập nhật Status = Available
    else Chip hỏng
        Service->>DB: Cập nhật Status = Problem by Clinic
    end
    DB-->>Service: Xác nhận thành công
```

***

### Báo cáo và đối soát (Reports & Reconciliation)

| Loại báo cáo | Mục đích |
| - | - |
| Báo cáo tồn kho định kỳ | Theo dõi biến động chip theo thời gian |
| Báo cáo sử dụng chip | Phân tích hiệu quả sử dụng chip tại phòng khám |
| Báo cáo chip hỏng | Đánh giá chất lượng chip và quy trình xử lý |
| Báo cáo trả về kho | Đối chiếu số lượng chip trả về với kho tổng |

***

### Quy tắc nghiệp vụ (Business Rules)

> [!WARNING]
>
> Các quy tắc dưới đây đảm bảo tính toàn vẹn dữ liệu tại phòng khám.

* **Phân quyền dữ liệu:** Clinic chỉ được xem và thao tác trên chip thuộc clinic của mình (trạng thái: `Sending-to-Clinic`, `In-Clinic`, `Activated`, `Problem by Clinic`, `Returning`).
* **Không xem được chip kho tổng:** Clinic không thể xem chip ở trạng thái `Available`, `Problem by TMT`, `Problem by Factory`. Một khi chip trả về thành công và chuyển thành `Available`, nó sẽ không còn hiển thị ở Clinic.
* **Không xem chip clinic khác:** Clinic không thể xem hoặc thao tác chip thuộc các clinic khác.
* Chip ở trạng thái `Activated` không thể chuyển về trạng thái khác.
* Chip ở trạng thái `Problem by Clinic` không thể được sử dụng cho thú cưng mới.
* **Quy trình gửi chip từ TMT:**
  * Khi TMT giao hàng cho Shipper, chip chuyển từ `Available` sang `Sending-to-Clinic`.
  * **Nhận hàng bằng Barcode:** Khi nhận thùng hàng, Clinic tiến hành dùng súng quét hoặc Camera để quét mã vạch trên từng con chip.
  * Quét trúng chip nào, chip đó lập tức chuyển từ `Sending-to-Clinic` sang `In-Clinic` và có thể tiêm cho khách ngay lập tức.
  * Những chip không được quét (bị thiếu do Shipper làm mất) sẽ tự động bị đánh dấu là `Problem by TMT` (với lý do: Mất trên đường vận chuyển do Shipper) để TMT tự xử lý bồi thường. Clinic KHÔNG bị giam hàng và KHÔNG cần chờ gửi bù.
* **Quy trình trả chip:**
  * Chỉ chip ở trạng thái `In-Clinic` mới có thể được Clinic yêu cầu trả về kho tổng.
  * Khi Clinic tạo yêu cầu trả, chip chuyển từ `In-Clinic` sang `Returning`.
  * Nếu trả về thành công, TMT đổi trạng thái chip từ `Returning` sang `Available`.
  * TMT có quyền chuyển chip từ `Returning` sang `Problem by Clinic` nếu phát hiện hỏng trong quá trình kiểm tra.
* Mỗi lần báo cáo sự cố phải có lý do cụ thể và được lưu vào lịch sử.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.