feat: implement component-item management with CRUD operations and status updates
This commit is contained in:
Tran Anh Tuan
517
docs/db/ChangeStatusComponent.md
Normal file
517
docs/db/ChangeStatusComponent.md
Normal file
@@ -0,0 +1,517 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user