518 lines
16 KiB
Markdown
518 lines
16 KiB
Markdown
# Change Status Component - Implementation Guide (Go Service Layer)
|
|
|
|
## Overview
|
|
|
|
Khi người dùng cập nhật `status` của 1 bản ghi trong bảng `component_items`, hệ thống phải:
|
|
|
|
1. **Tách/mở rộng record** trong bảng `component_items` (quản lý quantity chính xác theo status)
|
|
2. **Tự động ghi log** vào bảng `component_status_history`
|
|
3. Tất cả trong **cùng 1 transaction**
|
|
|
|
### Nguyên tắc: Mỗi record = 1 nhóm linh kiện cùng tình trạng
|
|
|
|
Mỗi record `component_items` đại diện cho **một nhóm linh kiện có cùng component, cùng container, cùng status**. Khi đổi status một phần số lượng → phải tách record.
|
|
|
|
## Tables liên quan
|
|
|
|
- `component_items` — bản ghi linh kiện tại 1 vị trí (container), mỗi record = 1 nhóm cùng status
|
|
- `component_status_history` — lịch sử thay đổi tình trạng (audit log)
|
|
|
|
## Status Enum Values
|
|
|
|
```
|
|
normal | damaged | long_unused | expired | pending_inspection
|
|
```
|
|
|
|
---
|
|
|
|
## Business Logic - 3 Trường Hợp
|
|
|
|
### Request Body
|
|
|
|
```json
|
|
{
|
|
"status": "damaged",
|
|
"changed_quantity": 5,
|
|
"note": "Bị cháy khi test mạch",
|
|
"changed_by": "nguyenvana"
|
|
}
|
|
```
|
|
|
|
### Trường hợp 1: `changed_quantity` = NULL hoặc = `quantity` (đổi toàn bộ)
|
|
|
|
Đổi status của **toàn bộ** linh kiện trong record.
|
|
|
|
```
|
|
Trước: component_items (id=1): quantity=20, status="normal"
|
|
Request: { status: "damaged", changed_quantity: null } hoặc changed_quantity: 20
|
|
|
|
Sau: component_items (id=1): quantity=20, status="damaged"
|
|
```
|
|
|
|
→ Chỉ UPDATE status, không tách record.
|
|
|
|
### Trường hợp 2: `changed_quantity` < `quantity` (đổi một phần, CHƯA có record cùng status mới)
|
|
|
|
Tách thành 2 record: phần còn tốt + phần đổi status.
|
|
|
|
```
|
|
Trước: component_items (id=1): quantity=20, status="normal"
|
|
|
|
Request: { status: "damaged", changed_quantity: 5 }
|
|
|
|
Kiểm tra: KHÔNG có record nào có (component_id=1.component_id, container_id=1.container_id, status="damaged")
|
|
|
|
Sau:
|
|
component_items (id=1): quantity=15, status="normal" ← giảm 5
|
|
component_items (id=NEW): quantity=5, status="damaged" ← record mới
|
|
```
|
|
|
|
### Trường hợp 3: `changed_quantity` < `quantity` (đổi một phần, ĐÃ có record cùng status mới)
|
|
|
|
Giảm quantity record cũ, **cộng dồn** vào record đã có cùng status.
|
|
|
|
```
|
|
Trước:
|
|
component_items (id=1): quantity=20, status="normal"
|
|
component_items (id=2): quantity=3, status="damaged" ← đã có sẵn
|
|
|
|
Request: { status: "damaged", changed_quantity: 5 }
|
|
|
|
Kiểm tra: ĐÃ CÓ record (id=2) cùng (component_id, container_id, status="damaged")
|
|
|
|
Sau:
|
|
component_items (id=1): quantity=15, status="normal" ← giảm 5
|
|
component_items (id=2): quantity=8, status="damaged" ← 3 + 5 = 8
|
|
```
|
|
|
|
---
|
|
|
|
## Go Service Layer Flow
|
|
|
|
### 1. API Endpoint
|
|
|
|
```
|
|
PUT /api/v1/component-items/:id/status
|
|
```
|
|
|
|
### 2. Request Model
|
|
|
|
```go
|
|
type UpdateComponentItemStatusRequest struct {
|
|
Status string `json:"status" binding:"required,oneof=normal damaged long_unused expired pending_inspection"`
|
|
ChangedQuantity *int `json:"changed_quantity"`
|
|
Note string `json:"note"`
|
|
ChangedBy string `json:"changed_by" binding:"required"`
|
|
}
|
|
```
|
|
|
|
### 3. Chi tiết Transaction
|
|
|
|
```
|
|
BEGIN TRANSACTION
|
|
│
|
|
├── Bước 1: SELECT component_items WHERE id = :id
|
|
│ → Lưu lại old_status, old_quantity, component_id, container_id
|
|
│
|
|
├── Bước 2: Kiểm tra changed_quantity
|
|
│ │
|
|
│ ├── Nếu changed_quantity IS NULL hoặc changed_quantity == old_quantity:
|
|
│ │ │
|
|
│ │ └── Bước 2a: UPDATE component_items
|
|
│ │ SET status = :new_status, updated_at = NOW()
|
|
│ │ WHERE id = :id
|
|
│ │
|
|
│ └── Nếu changed_quantity < old_quantity (đổi một phần):
|
|
│ │
|
|
│ ├── Bước 2b-i: UPDATE component_items (record cũ)
|
|
│ │ SET quantity = old_quantity - changed_quantity, updated_at = NOW()
|
|
│ │ WHERE id = :id
|
|
│ │
|
|
│ ├── Bước 2b-ii: SELECT component_items
|
|
│ │ WHERE component_id = :component_id
|
|
│ │ AND container_id = :container_id
|
|
│ │ AND status = :new_status
|
|
│ │ → Kiểm tra đã có record cùng status chưa
|
|
│ │
|
|
│ ├── Nếu CHƯA có:
|
|
│ │ └── Bước 2b-iii: INSERT INTO component_items
|
|
│ │ (component_id, container_id, quantity, status, metadata, created_at)
|
|
│ │ VALUES (:component_id, :container_id, :changed_quantity, :new_status, :metadata, NOW())
|
|
│ │
|
|
│ └── Nếu ĐÃ có (existing_id):
|
|
│ └── Bước 2b-iv: UPDATE component_items
|
|
│ SET quantity = existing_quantity + changed_quantity, updated_at = NOW()
|
|
│ WHERE id = existing_id
|
|
│
|
|
├── Bước 3: INSERT INTO component_status_history
|
|
│ (component_item_id, old_status, new_status, changed_quantity, note, changed_by, changed_at)
|
|
│ VALUES (:id, :old_status, :new_status, :changed_quantity, :note, :changed_by, NOW())
|
|
│
|
|
└── COMMIT (hoặc ROLLBACK nếu có lỗi)
|
|
```
|
|
|
|
### 4. Service Logic (Pseudocode)
|
|
|
|
```go
|
|
func UpdateComponentItemStatus(ctx context.Context, dbPool *pgxpool.Pool, queries *db.Queries, id int64, req UpdateComponentItemStatusRequest) error {
|
|
// 1. Lấy bản ghi hiện tại
|
|
existing, err := queries.GetComponentItemByID(ctx, id)
|
|
if err != nil {
|
|
return ErrNotFound
|
|
}
|
|
|
|
// 2. Kiểm tra status không đổi
|
|
if existing.Status == db.ComponentItemStatusEnum(req.Status) {
|
|
return ErrStatusUnchanged
|
|
}
|
|
|
|
// 3. Bắt đầu transaction
|
|
tx, err := dbPool.Begin(ctx)
|
|
if err != nil {
|
|
return err
|
|
}
|
|
defer func() {
|
|
if err != nil {
|
|
tx.Rollback(ctx)
|
|
}
|
|
}()
|
|
|
|
txQueries := queries.WithTx(tx)
|
|
newStatus := db.ComponentItemStatusEnum(req.Status)
|
|
|
|
// 4. Xác định changed_qty (default = toàn bộ)
|
|
changedQty := int32(existing.Quantity)
|
|
if req.ChangedQuantity != nil {
|
|
changedQty = int32(*req.ChangedQuantity)
|
|
}
|
|
|
|
// 5. Phân nhánh theo trường hợp
|
|
if changedQty >= existing.Quantity {
|
|
// Trường hợp 1: Đổi toàn bộ
|
|
_, err = txQueries.UpdateComponentItemStatus(ctx, db.UpdateComponentItemStatusParams{
|
|
ID: id,
|
|
Status: newStatus,
|
|
UpdatedAt: time.Now(),
|
|
})
|
|
} else {
|
|
// Trường hợp 2 & 3: Đổi một phần
|
|
|
|
// 5a. Giảm quantity record cũ
|
|
_, err = txQueries.UpdateComponentItemQuantity(ctx, db.UpdateComponentItemQuantityParams{
|
|
ID: id,
|
|
Quantity: existing.Quantity - changedQty,
|
|
UpdatedAt: time.Now(),
|
|
})
|
|
if err != nil {
|
|
return err
|
|
}
|
|
|
|
// 5b. Tìm record cùng (component_id, container_id, new_status)
|
|
existingNewStatus, findErr := txQueries.GetComponentItemByComponentContainerStatus(ctx,
|
|
db.GetComponentItemByComponentContainerStatusParams{
|
|
ComponentID: existing.ComponentID,
|
|
ContainerID: existing.ContainerID,
|
|
Status: newStatus,
|
|
},
|
|
)
|
|
|
|
if findErr == sql.ErrNoRows {
|
|
// Trường hợp 2: Chưa có → tạo record mới
|
|
_, err = txQueries.CreateComponentItem(ctx, db.CreateComponentItemParams{
|
|
ComponentID: existing.ComponentID,
|
|
ContainerID: existing.ContainerID,
|
|
Quantity: changedQty,
|
|
Status: newStatus,
|
|
Metadata: existing.Metadata,
|
|
CreatedAt: time.Now(),
|
|
})
|
|
} else if findErr == nil {
|
|
// Trường hợp 3: Đã có → cộng dồn quantity
|
|
_, err = txQueries.UpdateComponentItemQuantity(ctx, db.UpdateComponentItemQuantityParams{
|
|
ID: existingNewStatus.ID,
|
|
Quantity: existingNewStatus.Quantity + changedQty,
|
|
UpdatedAt: time.Now(),
|
|
})
|
|
} else {
|
|
return findErr
|
|
}
|
|
}
|
|
|
|
if err != nil {
|
|
return err
|
|
}
|
|
|
|
// 6. Ghi log vào component_status_history
|
|
_, err = txQueries.CreateComponentStatusHistory(ctx, db.CreateComponentStatusHistoryParams{
|
|
ComponentItemID: id,
|
|
OldStatus: db.NullComponentItemStatusEnum{
|
|
ComponentItemStatusEnum: existing.Status,
|
|
Valid: true,
|
|
},
|
|
NewStatus: newStatus,
|
|
ChangedQuantity: pgtype.Int4{Int32: changedQty, Valid: true},
|
|
Note: pgtype.Text{String: req.Note, Valid: req.Note != ""},
|
|
ChangedBy: pgtype.Text{String: req.ChangedBy, Valid: true},
|
|
ChangedAt: time.Now(),
|
|
})
|
|
if err != nil {
|
|
return err
|
|
}
|
|
|
|
// 7. Commit
|
|
return tx.Commit(ctx)
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## SQL Queries cần viết (cho sqlc)
|
|
|
|
### db/queries/component_item.sql
|
|
|
|
```sql
|
|
-- name: GetComponentItemByID :one
|
|
SELECT * FROM component_items WHERE id = sqlc.arg(id);
|
|
|
|
-- name: UpdateComponentItemStatus :one
|
|
UPDATE component_items
|
|
SET status = sqlc.arg(status),
|
|
updated_at = sqlc.arg(updated_at)
|
|
WHERE id = sqlc.arg(id)
|
|
RETURNING *;
|
|
|
|
-- name: UpdateComponentItemQuantity :one
|
|
UPDATE component_items
|
|
SET quantity = sqlc.arg(quantity),
|
|
updated_at = sqlc.arg(updated_at)
|
|
WHERE id = sqlc.arg(id)
|
|
RETURNING *;
|
|
|
|
-- name: GetComponentItemByComponentContainerStatus :one
|
|
SELECT * FROM component_items
|
|
WHERE component_id = sqlc.arg(component_id)
|
|
AND container_id = sqlc.arg(container_id)
|
|
AND status = sqlc.arg(status);
|
|
|
|
-- name: CreateComponentItem :one
|
|
INSERT INTO component_items (component_id, container_id, quantity, status, metadata, created_at)
|
|
VALUES (
|
|
sqlc.arg(component_id),
|
|
sqlc.arg(container_id),
|
|
sqlc.arg(quantity),
|
|
sqlc.arg(status),
|
|
sqlc.arg(metadata),
|
|
sqlc.arg(created_at)
|
|
)
|
|
RETURNING *;
|
|
```
|
|
|
|
### db/queries/component_status_history.sql
|
|
|
|
```sql
|
|
-- name: CreateComponentStatusHistory :one
|
|
INSERT INTO component_status_history (
|
|
component_item_id, old_status, new_status,
|
|
changed_quantity, note, changed_by, changed_at
|
|
)
|
|
VALUES (
|
|
sqlc.arg(component_item_id),
|
|
sqlc.arg(old_status),
|
|
sqlc.arg(new_status),
|
|
sqlc.arg(changed_quantity),
|
|
sqlc.arg(note),
|
|
sqlc.arg(changed_by),
|
|
sqlc.arg(changed_at)
|
|
)
|
|
RETURNING *;
|
|
```
|
|
|
|
---
|
|
|
|
## Files cần tạo/sửa
|
|
|
|
| File | Action | Mô tả |
|
|
|------|--------|-------|
|
|
| `internal/models/requests/component_item_request.go` | Sửa | Thêm `UpdateComponentItemStatusRequest` |
|
|
| `internal/models/responses/component_item_response.go` | Sửa | Thêm response struct cho status change |
|
|
| `internal/repositories/component_item_repository.go` | Sửa | Hàm `UpdateComponentItemStatus` (chứa transaction logic) |
|
|
| `internal/services/component_item_service.go` | Sửa | Handler `ComponentItemUpdateStatus` |
|
|
| `internal/routers/router.go` | Sửa | Thêm route `PUT /api/v1/component-items/:id/status` |
|
|
| `db/queries/component_item.sql` | Sửa | Thêm `UpdateComponentItemQuantity`, `GetComponentItemByComponentContainerStatus` |
|
|
| `db/queries/component_status_history.sql` | Đã có | `CreateComponentStatusHistory` |
|
|
| `db/migrations/` | (đã có) | Bảng đã tạo ở migration 000001 |
|
|
|
|
---
|
|
|
|
## Edge Cases cần xử lý
|
|
|
|
| Trường hợp | Xử lý |
|
|
|---|---|
|
|
| `old_status == new_status` | Không update, không ghi history, trả về `"Status unchanged"` |
|
|
| `component_item` không tồn tại | Return 404 |
|
|
| `changed_quantity > quantity` | Return 400 — không thể đổi status nhiều hơn số lượng hiện có |
|
|
| `changed_quantity == 0` | Return 400 — không hợp lý |
|
|
| `changed_quantity < 0` | Return 400 — không cho số âm |
|
|
| `changed_quantity` NULL | Đổi status toàn bộ, tương đương `changed_quantity = quantity` |
|
|
| Transaction failed | Rollback, return 500 |
|
|
| `changed_by` | Lấy từ JWT token context hoặc request body, ưu tiên JWT |
|
|
| Record cũ sau khi trừ quantity = 0 | Xóa record đó (`DELETE WHERE quantity = 0`) hoặc để số 0 (tùy chọn) |
|
|
|
|
### Lưu ý: Xử lý khi quantity record cũ = 0 sau khi tách
|
|
|
|
```
|
|
Trước: (id=1): quantity=5, status="normal"
|
|
Request: changed_quantity=5, status="damaged"
|
|
|
|
Sau khi UPDATE: (id=1): quantity=0, status="normal"
|
|
```
|
|
|
|
Nên **xóa** record có quantity = 0 sau khi UPDATE, để tránh record rác:
|
|
|
|
```sql
|
|
-- name: DeleteComponentItemZeroQuantity :execrows
|
|
DELETE FROM component_items WHERE id = sqlc.arg(id) AND quantity = 0;
|
|
```
|
|
|
|
Hoặc thêm logic sau bước UPDATE quantity:
|
|
|
|
```go
|
|
if existing.Quantity - changedQty == 0 {
|
|
txQueries.DeleteComponentItem(ctx, id)
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Ví dụ Response
|
|
|
|
### Thành công - Đổi toàn bộ (Trường hợp 1):
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "Status updated successfully",
|
|
"data": {
|
|
"id": 1,
|
|
"old_status": "normal",
|
|
"new_status": "damaged",
|
|
"changed_quantity": 20,
|
|
"history_id": 42
|
|
}
|
|
}
|
|
```
|
|
|
|
### Thành công - Đổi một phần, tạo record mới (Trường hợp 2):
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "Status updated successfully",
|
|
"data": {
|
|
"id": 1,
|
|
"old_status": "normal",
|
|
"new_status": "damaged",
|
|
"changed_quantity": 5,
|
|
"new_component_item_id": 15,
|
|
"history_id": 42
|
|
}
|
|
}
|
|
```
|
|
|
|
### Thành công - Đổi một phần, cộng dồn record cũ (Trường hợp 3):
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "Status updated successfully",
|
|
"data": {
|
|
"id": 1,
|
|
"old_status": "normal",
|
|
"new_status": "damaged",
|
|
"changed_quantity": 5,
|
|
"merged_component_item_id": 2,
|
|
"history_id": 42
|
|
}
|
|
}
|
|
```
|
|
|
|
### Status không đổi:
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "Status unchanged",
|
|
"data": null
|
|
}
|
|
```
|
|
|
|
### Validation lỗi - changed_quantity > quantity:
|
|
|
|
```json
|
|
{
|
|
"code": 400,
|
|
"message": "changed_quantity (25) exceeds current quantity (20)",
|
|
"data": null
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Ví dụ Vòng Đời Hoàn Chỉnh
|
|
|
|
```
|
|
Ngày 01/03: Nhập kho 20 tụ điện 100uF vào container A
|
|
→ Invoice type=import, quantity=20
|
|
→ component_items (id=1): quantity=20, status="normal"
|
|
|
|
─────────────────────────────────────────────────
|
|
|
|
Ngày 02/04: Kiểm kho phát hiện 5 cái bị ẩm
|
|
→ Request: { status: "damaged", changed_quantity: 5, note: "Bị ẩm mốc" }
|
|
|
|
Transaction:
|
|
UPDATE (id=1): quantity = 20 - 5 = 15
|
|
INSERT (id=2): quantity = 5, status = "damaged"
|
|
INSERT history: old=normal, new=damaged, qty=5
|
|
|
|
Sau:
|
|
component_items (id=1): quantity=15, status="normal"
|
|
component_items (id=2): quantity=5, status="damaged"
|
|
|
|
─────────────────────────────────────────────────
|
|
|
|
Ngày 05/04: Phát hiện thêm 3 cái bị ẩm nữa
|
|
→ Request: { status: "damaged", changed_quantity: 3, note: "Tiếp tục bị ẩm" }
|
|
|
|
Transaction:
|
|
UPDATE (id=1): quantity = 15 - 3 = 12
|
|
UPDATE (id=2): quantity = 5 + 3 = 8 ← cộng dồn vào record damaged đã có
|
|
INSERT history: old=normal, new=damaged, qty=3
|
|
|
|
Sau:
|
|
component_items (id=1): quantity=12, status="normal"
|
|
component_items (id=2): quantity=8, status="damaged"
|
|
|
|
─────────────────────────────────────────────────
|
|
|
|
Ngày 10/04: Kỹ thuật xác nhận 5 cái damaged không sửa được
|
|
→ Request trên record id=2: { status: "expired", changed_quantity: 5 }
|
|
|
|
Transaction:
|
|
UPDATE (id=2): quantity = 8 - 5 = 3
|
|
INSERT (id=3): quantity = 5, status = "expired"
|
|
INSERT history: old=damaged, new=expired, qty=5
|
|
|
|
Sau:
|
|
component_items (id=1): quantity=12, status="normal"
|
|
component_items (id=2): quantity=3, status="damaged"
|
|
component_items (id=3): quantity=5, status="expired"
|
|
|
|
─────────────────────────────────────────────────
|
|
|
|
Ngày 15/04: Xuất bỏ 5 cái expired ra khỏi kho
|
|
→ Invoice type=export, note="Loại bỏ linh kiện expired"
|
|
→ stock_transactions ghi nhận xuất
|
|
→ component_items (id=3): bị xóa hoặc quantity = 0
|
|
```
|