# Workflow Xuất/Trả Kho — Hướng dẫn FE > **TL;DR:** Thêm 2 màn hình mới (Inbox + Request Detail mở rộng) và 1 panel nhỏ trong trang tạo request. Không cần đập lại gì cả. --- ## Luồng tổng quan — ai thấy gì ``` User tạo request (out_* hoặc in_return) ↓ [Infra inbox] → duyệt tổng quan → approve ↓ [Inventory inbox] → nhập serial vào draft → approve ↓ [DC.Server inbox] → check từng serial → approve ↓ [SO inbox] → bấm Approve như cũ (endpoint cũ, không đổi) ↓ DONE — device status cập nhật, tồn kho trừ ``` Với **in_return**: bước 2 = DC.Server, bước 3 = Inventory (đảo nhau). Với các loại khác (in_new, in_old...): **không có workflow**, SO approve thẳng như cũ. --- ## Cần build bao nhiêu màn hình? ### 1. Inbox — danh sách nhóm (MỚI) ### 2. Group Detail — chi tiết nhóm (MỚI, dùng lại data inbox filter group_id) ### 3. Request Detail — mở rộng thêm panel workflow (CHỈNH SỬA) ### 4. SO dùng nút Approve cũ — không đổi gì --- ## MÀN HÌNH 1 — Inbox Inbox hiển thị theo **nhóm (request_group)**, không phải từng phiếu đơn lẻ. Mỗi nhóm có thể gồm nhiều loại thiết bị xuất/trả cùng đợt. **API:** ``` POST /auth/workflow/inbox ``` ```json { "username": "phatdev", "page": 1, "limit": 20, "filter": { "request_id": "GD-025", ← search theo mã phiếu, LIKE "group_id": "GP-025", ← search theo mã nhóm, LIKE "wf_status": "active", ← để trống = lấy active + rework_pending "step_code": "inventory_check" ← lọc bước cụ thể } } ``` **Response:** ```json { "data": [ { "request_group_id": 23, "group_id": "GP-025000023", "note": "Xuất batch tháng 6", "created_by": "nguyen.van", "created_at": "2025-06-01 09:00:00", "has_actionable": true, "requests": [ { "inventory_request_id": 157, "request_id": "GD-025000157", "item_name": "Server 1U Dell R750", "device_type": "server", "transaction_type": "out_new", "quantity": 2, "department": "Platform", "product": "ZaloPay", "location": "HCM DC1", "proof_related": "JIRA-1234", "wf_status": "active", "rework_count": 0, "step_code": "inventory_check", "step_name": "Inventory verify serial", "is_final": 0, "can_act": true, "draft_transaction_date": "2025-06-10" }, { "inventory_request_id": 158, "request_id": "GD-025000158", "item_name": "RAM DDR4 32GB", "device_type": "ram", "transaction_type": "out_new", "quantity": 8, "wf_status": "active", "rework_count": 1, "step_code": "inventory_check", "can_act": true, "draft_transaction_date": "" } ] } ], "pagination": { "page": 1, "limit": 20, "total": 5 } } ``` **Giải thích fields quan trọng:** | Field | Ý nghĩa | |---|---| | `group_id` | Mã nhóm "GP-025000023" — để biết đây là batch nào | | `request_id` | **Mã phiếu "GD-025000157"** — đơn vị xử lý dùng cái này để tra cứu / điền vào biên bản | | `item_name` | Tên loại thiết bị — "Server 1U Dell R750" | | `device_type` | Loại — server / ram / disk / ... | | `can_act` | `true` = user đang login có thể action request này ngay | | `has_actionable` | `true` = nhóm có ít nhất 1 request cần mình xử lý | | `rework_count > 0` | Badge đỏ "Rework lần X" | | `draft_transaction_date` | Ngày kho đã chốt — rỗng = Inventory chưa điền | **Layout gợi ý:** ``` ┌──────────────────────────────────────────────────────────────────┐ │ 🔍 [Nhập mã phiếu GD-... hoặc mã nhóm GP-...] [Bước ▼] [Reset]│ ├──────────────────────────────────────────────────────────────────┤ │ ● GP-025000023 | nguyen.van | 01/06 [2 phiếu] │ │ GD-025000157 Server 1U Dell R750 x2 ● Cần bạn xử lý │ │ GD-025000158 RAM DDR4 32GB x8 ● Cần bạn xử lý [R1] │ │ [Xem nhóm →] │ ├──────────────────────────────────────────────────────────────────┤ │ ○ GP-025000021 | tranthib | 30/05 [2 phiếu] │ │ GD-025000142 HDD 4TB SAS x4 ○ DC.Server đang xử │ │ GD-025000143 Switch 24-port x1 ○ DC.Server đang xử │ │ [Xem nhóm →] │ └──────────────────────────────────────────────────────────────────┘ ``` - `●` xanh + "Cần bạn xử lý" = `can_act: true` - `○` xám = đang ở bước khác, không phải lượt mình - `[R1]` đỏ = đã rework 1 lần --- ## MÀN HÌNH 1b — Group Detail (click "Xem nhóm →") Khi user click vào 1 nhóm trong inbox, mở màn hình này để thấy tất cả phiếu con. **Dùng lại data từ inbox** — không cần gọi thêm API, chỉ cần lọc theo `group_id`: ``` POST /auth/workflow/inbox { "username": "...", "page": 1, "limit": 100, "filter": { "group_id": "GP-025000023" } } ``` Response trả về đúng 1 group với tất cả requests. Từ đó render chi tiết. **Layout gợi ý:** ``` ┌────────────────────────────────────────────────────────────────┐ │ ← Inbox GP-025000023 │ │ Tạo bởi: nguyen.van | 01/06/2025 | "Xuất batch tháng 6" │ ├────────────────────────────────────────────────────────────────┤ │ GD-025000157 Server 1U Dell R750 x2 │ │ Dept: Platform | Product: ZaloPay | Ngày kho: 10/06 │ │ Bước hiện tại: ● Inventory verify serial [Rework 0] │ │ [Xem chi tiết →] │ ├────────────────────────────────────────────────────────────────┤ │ GD-025000158 RAM DDR4 32GB x8 │ │ Dept: Platform | Product: ZaloPay | Ngày kho: chưa điền │ │ Bước hiện tại: ● Inventory verify serial [Rework 1] │ │ [Xem chi tiết →] │ └────────────────────────────────────────────────────────────────┘ ``` Click **"Xem chi tiết →"** vào từng phiếu → mở Màn hình 2 (Request Detail). --- ## MÀN HÌNH 2 — Request Detail (mở rộng) Trang này đã có. Chỉ cần thêm **1 panel "Workflow"** ở dưới hoặc sidebar. **API lấy data:** ``` POST /auth/workflow/instance/getbyreqid { "inventory_request_id": 157, "username": "..." } ``` Panel workflow gồm **3 tab nhỏ:** --- ### Tab 1: Tiến trình Hiển thị các bước dạng timeline: ``` ● Infra duyệt ✓ dangnt — 01/06 09:15 ● Inventory ✓ phatdev — 01/06 10:30 [rework lần 1] ● DC.Server ← đang ở đây ○ SO Approve ``` Data lấy từ `history[]` trong response. ```json "history": [ { "action": "approve", "actor": "dangnt", "step_code": "infra_review", "created_at": "..." }, { "action": "rework", "actor": "chungops","step_code": "dc_server_check", "comment": "Serial lỗi" }, { "action": "approve", "actor": "phatdev", "step_code": "inventory_check", "created_at": "..." } ] ``` - `action = approve` → icon ✓ xanh - `action = reject` → icon ✗ đỏ - `action = rework` → icon ↩ vàng, show `comment` - `action = created` → icon 📋 --- ### Tab 2: Danh sách serial (Draft) **API:** ``` POST /auth/workflow/draft/get { "inventory_request_id": 157, "username": "..." } ``` ```json { "wf_draft_id": 3, "rework_version": 0, "draft_status": "active", "transaction_date": "2025-06-10", "change_note": "Inventory nhập serial", "trackings": [ { "target_server": "rack-HCM-01", "quantity": 2, "serials": [ { "wf_draft_serial_id": 5, "device_id": 6427, "serial_number": "SN-ABC-001", "serial_status": "verified" }, { "wf_draft_serial_id": 6, "device_id": 6428, "serial_number": "SN-XYZ-002", "serial_status": "rejected" } ] } ] } ``` Hiển thị phần header của draft: ``` Ngày xuất/nhập: 10/06/2025 Phiên bản: v0 [rework lần 1 nếu rework_count>0] ``` Hiển thị danh sách bảng: | Server | Device ID | Serial | Trạng thái | |---|---|---|---| | rack-HCM-01 | 6427 | SN-ABC-001 | ✓ Verified | | rack-HCM-01 | 6428 | SN-XYZ-002 | ✗ Rejected | - `serial_status = verified` → badge xanh - `serial_status = rejected` → badge đỏ - `serial_status = pending` → badge xám "chưa scan" **Quan trọng — build local map ngay khi load:** ```javascript // Dùng cho màn hình scan của DC.Server const draftSerialMap = {} draft.trackings.forEach(t => { t.serials.forEach(s => { draftSerialMap[s.serial_number] = { wf_draft_serial_id: s.wf_draft_serial_id, device_id: s.device_id, target_server: t.target_server } }) }) // Khi scan serial "SN-ABC-001" → draftSerialMap["SN-ABC-001"] trả về ID cần gửi API ``` --- ### Tab 3: Action (các nút bấm) > Nút nào hiện ra **tùy theo step hiện tại và role của người đang đăng nhập**. ``` current_step.required_permission = "workflow.inventory.action" ``` Logic FE check đơn giản: ``` nếu user có permission == current_step.required_permission → hiện nút action → nếu step_code = "inventory_check" → hiện form nhập serial + DATE PICKER chọn ngày xuất (bắt buộc) → disable nút Approve nếu chưa có transaction_date trong draft → nếu step_code = "dc_server_check" → hiện màn hình scan (xem chi tiết bên dưới) → nếu step_code = "so_approve" → hiện nút Approve như cũ (redirect về trang approve cũ) → hiển thị ngày chốt: "Ngày xuất: [draft.transaction_date]" để SO biết ``` > **Trong luồng return** (`in_return`): bước 2 = DC.Server nhập serial (không phải Inventory). > DC.Server ở bước này cũng cần date picker — logic giống hệt Inventory ở bước export. --- ## CÁC ACTION CỤ THỂ ### Action: Approve / Reject / Rework / Cancel ``` POST /auth/workflow/step/action { "inventory_request_id": 157, "action": "approve", ← hoặc: reject / rework / cancel "comment": "Lý do...", "username": "dangnt" } ``` Sau khi gọi xong: reload lại tab "Tiến trình" và tab "Action". --- ### Action: Inventory nhập/sửa serial + chọn ngày Form của Inventory có **2 phần bắt buộc**: 1. **Date picker** — chọn ngày xuất/nhập (đây là ngày chính thức, SO không đổi được) 2. **Danh sách device** theo từng server ``` POST /auth/workflow/draft/update { "inventory_request_id": 157, "transaction_date": "2025-06-10", ← BẮT BUỘC, Inventory chọn "change_note": "Nhập serial sau khi Infra approve", "username": "phatdev", "trackings": [ { "target_server": "rack-HCM-01", "quantity": 2, "device_ids": [6427, 6428] } ] } ``` > `serials[]` không cần truyền — backend tự lấy serial từ device table. > `transaction_date` bắt buộc — nếu thiếu sẽ trả lỗi 210. > Khi rework, Inventory được phép chọn lại ngày khác. Validation FE: `device_ids.length <= quantity` và `transaction_date` không được rỗng. --- ### Action: DC.Server check serial — màn hình scan Có thể lên đến cả nghìn serial → **không thể bấm từng cái**. Build theo cơ chế scan: #### Cách hoạt động ``` Bước 1: Load draft → FE giữ local map: { serial_number → wf_draft_serial_id } Bước 2: Máy scan bắn serial vào input → FE tự match Bước 3: Sau khi scan xong → FE gửi batch lên server ``` #### Layout màn hình ``` ┌─────────────────────────────────────────────────────┐ │ 📦 Check serial — rack-HCM-01 │ │ │ │ [████████████░░░░░░░░] 45 / 120 đã scan │ │ │ │ ┌─────────────────────────────────────────────┐ │ │ │ 🔍 Scan hoặc nhập serial... [Enter] │ │ │ └─────────────────────────────────────────────┘ │ │ │ │ Kết quả scan: Filter: [Tất cả ▼] │ │ ┌──────────────────────────────────────────────┐ │ │ │ ✓ SN-ABC-001 6427 rack-HCM-01 │ │ │ │ ✓ SN-ABC-002 6428 rack-HCM-01 │ │ │ │ ⚠ SN-XYZ-999 — KHÔNG CÓ TRONG LIST │ │ │ │ ○ SN-DEF-003 6430 rack-HCM-01 (chưa) │ │ │ └──────────────────────────────────────────────┘ │ │ │ │ [Reject thủ công] [Gửi kết quả scan] ←──── nút │ └─────────────────────────────────────────────────────┘ ``` #### Logic FE **Khi scan 1 serial:** ```javascript // 1. Tìm trong local map (build từ draft data lúc load trang) const found = draftSerialMap[scannedSerialNumber] if (found) { // Đánh dấu local: verified localResults[found.wf_draft_serial_id] = "verified" // Hiện ✓ xanh trong list } else { // Hiện dòng cảnh báo: serial này không có trong danh sách showAlert(`⚠ ${scannedSerial} — không có trong draft`) } ``` **Các filter trong list:** - `Tất cả` — xem toàn bộ - `Chưa scan` — chỉ serial chưa được scan (để tìm cái còn sót) - `Không khớp` — serial scan được nhưng không có trong draft **Manual reject** (cho serial chưa scan mà biết chắc là lỗi): - Bấm vào dòng serial trạng thái `○ chưa scan` → chọn **Reject** + nhập lý do #### Gửi kết quả lên server Khi bấm **"Gửi kết quả scan"** — gửi toàn bộ 1 lần, không gửi từng cái: ``` POST /auth/workflow/serial/check { "inventory_request_id": 157, "username": "chungops", "checks": [ { "wf_draft_serial_id": 5, "check_status": "verified", "note": "" }, { "wf_draft_serial_id": 6, "check_status": "verified", "note": "" }, { "wf_draft_serial_id": 7, "check_status": "rejected", "note": "Manual reject — hỏng" } // Các serial chưa scan → KHÔNG gửi, để status=pending // DC.Server tự quyết định approve hay rework tùy % đã verified ] } ``` > Serial nào **không gửi lên** = vẫn là `pending` trong DB. > DC.Server tự xem % match rồi quyết định approve bước hay rework. #### Sau khi gửi xong Hiện bảng tổng kết trước khi cho approve: ``` ┌────────────────────────────┐ │ Kết quả check: │ │ ✓ Verified: 118 / 120 │ │ ✗ Rejected: 1 / 120 │ │ ○ Chưa check: 1 / 120 │ │ │ │ [Rework — yêu cầu sửa] │ │ [Approve — đẩy lên SO] ✓ │ └────────────────────────────┘ ``` --- ### Action: SO Approve Khi `step_code = "so_approve"` — **không dùng workflow endpoint**. SO dùng nút Approve cũ, gọi endpoint cũ: ``` POST /auth/request/approvev2 { "inventory_request_id": 157, "transaction_date": "2025-06-02", ← truyền gì cũng được, backend sẽ override "username": "so_admin" } ``` > **`transaction_date` SO truyền sẽ bị override** bởi ngày Inventory đã chọn trong draft. > Ngày chính thức = ngày Inventory thiết lập, không phải ngày SO bấm. > > Nếu Inventory **chưa** điền `transaction_date` trong draft → SO approve sẽ bị lỗi: > `"transaction_date chưa được Inventory thiết lập"`. > FE nên hiển thị cảnh báo này rõ ràng thay vì generic error. Backend tự commit draft → logic approve cũ chạy. FE không cần biết gì thêm. --- ### Action: Requester resubmit sau rework Khi `wf_status = "rework_pending"` — requester thấy thông báo "Yêu cầu cần sửa lại". Sau khi sửa xong (update draft), bấm **Gửi lại**: ``` POST /auth/workflow/resubmit { "inventory_request_id": 157, "comment": "Đã sửa theo yêu cầu", "username": "nguyen.van" } ``` --- ## Các trạng thái `wf_status` — hiển thị gì | `wf_status` | Hiển thị với requester | Hiển thị với đơn vị xử lý | |---|---|---| | `active` | "Đang xử lý — bước: [step_name]" | Xem trong inbox | | `rework_pending` | ⚠️ "Cần sửa lại" + nút Gửi lại | Không thấy trong inbox | | `completed` | ✅ "Hoàn thành" | — | | `rejected` | ❌ "Bị từ chối — [lý do]" | — | | `cancelled` | 🚫 "Đã hủy" | — | --- ## Phân quyền — nút nào hiện với ai Permissions của user lấy từ login response (hoặc gọi API account). | Permission | Vai trò | Được làm gì | |---|---|---| | `workflow.infra.action` | Zalo Infra | Approve/Reject/Rework bước 1 | | `workflow.inventory.action` | Inventory | Nhập serial + Approve/Rework bước 2 | | `workflow.dc_server.action` | DC.Server | Check serial + Approve/Rework bước 3 | | `request.approve` | SO | Approve bước 4 (endpoint cũ) | | `request.create` | Requester | Tạo request + Resubmit | | `workflow.view` | Tất cả | Xem inbox, xem trạng thái | Logic tổng quát: ```javascript // Hiện nút action khi: const canAct = user.permissions.includes(currentStep.required_permission) // Ngoại lệ: bước so_approve thì dùng nút Approve cũ const isFinalStep = currentStep.is_final === 1 ``` --- ## Không cần build gì cho các loại request này `in_new`, `in_old`, `in_maintenance`, `out_sold`, `out_disposed`, `out_maintenance` → Không có workflow, SO approve thẳng như cũ. FE không cần xử lý gì thêm. Kiểm tra đơn giản: gọi `getbyreqid` — nếu trả `errorcode: 205` thì request đó không có workflow. --- ## Gợi ý thứ tự build 1. **Inbox** — list nhóm + search. Gọi 1 API, render group card. Dễ nhất, build trước. 2. **Group Detail** — filter inbox theo `group_id`, không cần API mới. 3. **Tab Tiến trình** trong Request Detail — timeline history, chỉ đọc, không tương tác. 4. **Tab Action** — các nút approve/reject/rework theo `can_act` + `required_permission`. 5. **Tab Draft / Serial** — form nhập serial + date picker (Inventory) + scan screen (DC.Server). 6. **Rework flow** — thông báo `wf_status=rework_pending` + nút resubmit. ## Tóm tắt API dùng theo màn hình | Màn hình | API | Mục đích | |---|---|---| | Inbox | `POST /auth/workflow/inbox` | Lấy danh sách nhóm + search | | Group Detail | `POST /auth/workflow/inbox` filter `group_id` | Chi tiết nhóm | | Request Detail — Tiến trình | `POST /auth/workflow/instance/getbyreqid` | History + current step | | Request Detail — Draft | `POST /auth/workflow/draft/get` | Serial list + date | | Nhập serial (Inventory) | `POST /auth/workflow/draft/update` | Cập nhật draft + ngày | | Check serial (DC.Server) | `POST /auth/workflow/serial/check` | Batch verify | | Approve/Reject/Rework | `POST /auth/workflow/step/action` | Action trên bước hiện tại | | Resubmit | `POST /auth/workflow/resubmit` | Requester gửi lại sau rework | | SO Approve | `POST /auth/request/approvev2` | Endpoint cũ, không đổi | tạo UI mẫu cho cái này , để frontend tôi dễ hình dùng