warehouse-management-BE/docs/db/ChangeStatusComponent.md

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

{
  "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

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)

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

-- 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

-- 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:

-- 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:

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):

{
  "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):

{
  "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):

{
  "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:

{
  "code": 200,
  "message": "Status unchanged",
  "data": null
}

Validation lỗi - changed_quantity > quantity:

{
  "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