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
|
||||
```
|
||||
4
docs/db/Note.md
Normal file
4
docs/db/Note.md
Normal file
@@ -0,0 +1,4 @@
|
||||
- Ở bảng component_items số lượng chỉ được thêm khi ở lúc tạo
|
||||
|
||||
* Sau này cập nhật sẽ được tự động từ invoice
|
||||
* Trạng thái muốn cập nhật sẽ phải transaction cả bảng component_status_history
|
||||
@@ -288,6 +288,409 @@ const docTemplate = `{
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/component-items": {
|
||||
"get": {
|
||||
"description": "Retrieve a list of all component items ordered by creation date",
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"component-item"
|
||||
],
|
||||
"summary": "List all component items",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/definitions/response.SuccessResponse"
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"data": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/definitions/models.ComponentItem"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Internal Server Error",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"post": {
|
||||
"description": "Create a new component item with the provided details",
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"component-item"
|
||||
],
|
||||
"summary": "Create a new component item",
|
||||
"parameters": [
|
||||
{
|
||||
"description": "Component item request body",
|
||||
"name": "body",
|
||||
"in": "body",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"$ref": "#/definitions/requests.CreateComponentItemRequest"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"201": {
|
||||
"description": "Created",
|
||||
"schema": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/definitions/response.SuccessResponse"
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"data": {
|
||||
"$ref": "#/definitions/responses.CreateComponentItemResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Bad Request",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Internal Server Error",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/component-items/find/{componentId}": {
|
||||
"get": {
|
||||
"description": "Retrieve component items with full location details (container, shelf, cabinet, room, warehouse) for a given component ID",
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"component-item"
|
||||
],
|
||||
"summary": "Find component items by component ID",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "Component ID",
|
||||
"name": "componentId",
|
||||
"in": "path",
|
||||
"required": true
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/definitions/response.SuccessResponse"
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"data": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/definitions/models.FindComponentItemResult"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Bad Request",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Internal Server Error",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/component-items/{id}": {
|
||||
"get": {
|
||||
"description": "Retrieve a single component item using its unique identifier",
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"component-item"
|
||||
],
|
||||
"summary": "Get component item by ID",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "Component item ID",
|
||||
"name": "id",
|
||||
"in": "path",
|
||||
"required": true
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/definitions/response.SuccessResponse"
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"data": {
|
||||
"$ref": "#/definitions/models.ComponentItem"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Bad Request",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "Not Found",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Internal Server Error",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"put": {
|
||||
"description": "Update an existing component item by its ID. Only non-empty fields will be updated.",
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"component-item"
|
||||
],
|
||||
"summary": "Update component item",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "Component item ID",
|
||||
"name": "id",
|
||||
"in": "path",
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"description": "Component item request body",
|
||||
"name": "body",
|
||||
"in": "body",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"$ref": "#/definitions/requests.UpdateComponentItemRequest"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/definitions/response.SuccessResponse"
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"data": {
|
||||
"$ref": "#/definitions/responses.UpdateComponentItemResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Bad Request",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "Not Found",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Internal Server Error",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"delete": {
|
||||
"description": "Delete a component item by its unique identifier",
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"component-item"
|
||||
],
|
||||
"summary": "Delete component item",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "Component item ID",
|
||||
"name": "id",
|
||||
"in": "path",
|
||||
"required": true
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.SuccessResponse"
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Bad Request",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Internal Server Error",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/component-items/{id}/status": {
|
||||
"put": {
|
||||
"description": "Change the status of a component item. Supports partial quantity change with automatic split/merge logic. A status history record is created automatically.",
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"component-item"
|
||||
],
|
||||
"summary": "Change component item status",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "Component item ID",
|
||||
"name": "id",
|
||||
"in": "path",
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"description": "Status change request body",
|
||||
"name": "body",
|
||||
"in": "body",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"$ref": "#/definitions/requests.UpdateComponentItemStatusRequest"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/definitions/response.SuccessResponse"
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"data": {
|
||||
"$ref": "#/definitions/responses.UpdateComponentItemStatusResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Validation error (e.g., changed_quantity \u003e quantity, status unchanged)",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "Component item not found",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Internal server error",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/component-types": {
|
||||
"get": {
|
||||
"description": "Retrieve a list of all component types ordered by creation date",
|
||||
@@ -2375,6 +2778,38 @@ const docTemplate = `{
|
||||
}
|
||||
}
|
||||
},
|
||||
"models.ComponentItem": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"componentId": {
|
||||
"type": "integer"
|
||||
},
|
||||
"containerId": {
|
||||
"type": "integer"
|
||||
},
|
||||
"createdAt": {
|
||||
"type": "string"
|
||||
},
|
||||
"id": {
|
||||
"type": "integer"
|
||||
},
|
||||
"metadata": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "integer"
|
||||
}
|
||||
},
|
||||
"quantity": {
|
||||
"type": "integer"
|
||||
},
|
||||
"status": {
|
||||
"type": "string"
|
||||
},
|
||||
"updatedAt": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"models.ComponentType": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@@ -2436,6 +2871,41 @@ const docTemplate = `{
|
||||
}
|
||||
}
|
||||
},
|
||||
"models.FindComponentItemResult": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"cabinetName": {
|
||||
"type": "string"
|
||||
},
|
||||
"componentName": {
|
||||
"type": "string"
|
||||
},
|
||||
"containerName": {
|
||||
"type": "string"
|
||||
},
|
||||
"containerType": {
|
||||
"type": "string"
|
||||
},
|
||||
"quantity": {
|
||||
"type": "integer"
|
||||
},
|
||||
"roomName": {
|
||||
"type": "string"
|
||||
},
|
||||
"shelfName": {
|
||||
"type": "string"
|
||||
},
|
||||
"status": {
|
||||
"type": "string"
|
||||
},
|
||||
"typeName": {
|
||||
"type": "string"
|
||||
},
|
||||
"warehouseName": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"models.Room": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@@ -2576,6 +3046,35 @@ const docTemplate = `{
|
||||
}
|
||||
}
|
||||
},
|
||||
"requests.CreateComponentItemRequest": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"componentId",
|
||||
"containerId",
|
||||
"quantity",
|
||||
"status"
|
||||
],
|
||||
"properties": {
|
||||
"componentId": {
|
||||
"type": "integer"
|
||||
},
|
||||
"containerId": {
|
||||
"type": "integer"
|
||||
},
|
||||
"metadata": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "integer"
|
||||
}
|
||||
},
|
||||
"quantity": {
|
||||
"type": "integer"
|
||||
},
|
||||
"status": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"requests.CreateComponentRequest": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
@@ -2751,6 +3250,47 @@ const docTemplate = `{
|
||||
}
|
||||
}
|
||||
},
|
||||
"requests.UpdateComponentItemRequest": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"componentId": {
|
||||
"type": "integer"
|
||||
},
|
||||
"containerId": {
|
||||
"type": "integer"
|
||||
},
|
||||
"metadata": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "integer"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"requests.UpdateComponentItemStatusRequest": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"status"
|
||||
],
|
||||
"properties": {
|
||||
"changedQuantity": {
|
||||
"type": "integer"
|
||||
},
|
||||
"note": {
|
||||
"type": "string"
|
||||
},
|
||||
"status": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"normal",
|
||||
"damaged",
|
||||
"long_unused",
|
||||
"expired",
|
||||
"pending_inspection"
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
"requests.UpdateComponentRequest": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@@ -2913,6 +3453,14 @@ const docTemplate = `{
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses.CreateComponentItemResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "integer"
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses.CreateComponentResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@@ -2998,6 +3546,58 @@ const docTemplate = `{
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses.UpdateComponentItemResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"componentId": {
|
||||
"type": "integer"
|
||||
},
|
||||
"containerId": {
|
||||
"type": "integer"
|
||||
},
|
||||
"id": {
|
||||
"type": "integer"
|
||||
},
|
||||
"metadata": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "integer"
|
||||
}
|
||||
},
|
||||
"quantity": {
|
||||
"type": "integer"
|
||||
},
|
||||
"status": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses.UpdateComponentItemStatusResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"changedQuantity": {
|
||||
"type": "integer"
|
||||
},
|
||||
"historyId": {
|
||||
"type": "integer"
|
||||
},
|
||||
"id": {
|
||||
"type": "integer"
|
||||
},
|
||||
"mergedComponentItemId": {
|
||||
"type": "integer"
|
||||
},
|
||||
"newComponentItemId": {
|
||||
"type": "integer"
|
||||
},
|
||||
"newStatus": {
|
||||
"type": "string"
|
||||
},
|
||||
"oldStatus": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses.UpdateComponentResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
|
||||
@@ -282,6 +282,409 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/component-items": {
|
||||
"get": {
|
||||
"description": "Retrieve a list of all component items ordered by creation date",
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"component-item"
|
||||
],
|
||||
"summary": "List all component items",
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/definitions/response.SuccessResponse"
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"data": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/definitions/models.ComponentItem"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Internal Server Error",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"post": {
|
||||
"description": "Create a new component item with the provided details",
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"component-item"
|
||||
],
|
||||
"summary": "Create a new component item",
|
||||
"parameters": [
|
||||
{
|
||||
"description": "Component item request body",
|
||||
"name": "body",
|
||||
"in": "body",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"$ref": "#/definitions/requests.CreateComponentItemRequest"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"201": {
|
||||
"description": "Created",
|
||||
"schema": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/definitions/response.SuccessResponse"
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"data": {
|
||||
"$ref": "#/definitions/responses.CreateComponentItemResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Bad Request",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Internal Server Error",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/component-items/find/{componentId}": {
|
||||
"get": {
|
||||
"description": "Retrieve component items with full location details (container, shelf, cabinet, room, warehouse) for a given component ID",
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"component-item"
|
||||
],
|
||||
"summary": "Find component items by component ID",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "Component ID",
|
||||
"name": "componentId",
|
||||
"in": "path",
|
||||
"required": true
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/definitions/response.SuccessResponse"
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"data": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/definitions/models.FindComponentItemResult"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Bad Request",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Internal Server Error",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/component-items/{id}": {
|
||||
"get": {
|
||||
"description": "Retrieve a single component item using its unique identifier",
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"component-item"
|
||||
],
|
||||
"summary": "Get component item by ID",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "Component item ID",
|
||||
"name": "id",
|
||||
"in": "path",
|
||||
"required": true
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/definitions/response.SuccessResponse"
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"data": {
|
||||
"$ref": "#/definitions/models.ComponentItem"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Bad Request",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "Not Found",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Internal Server Error",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"put": {
|
||||
"description": "Update an existing component item by its ID. Only non-empty fields will be updated.",
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"component-item"
|
||||
],
|
||||
"summary": "Update component item",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "Component item ID",
|
||||
"name": "id",
|
||||
"in": "path",
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"description": "Component item request body",
|
||||
"name": "body",
|
||||
"in": "body",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"$ref": "#/definitions/requests.UpdateComponentItemRequest"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/definitions/response.SuccessResponse"
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"data": {
|
||||
"$ref": "#/definitions/responses.UpdateComponentItemResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Bad Request",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "Not Found",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Internal Server Error",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"delete": {
|
||||
"description": "Delete a component item by its unique identifier",
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"component-item"
|
||||
],
|
||||
"summary": "Delete component item",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "Component item ID",
|
||||
"name": "id",
|
||||
"in": "path",
|
||||
"required": true
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.SuccessResponse"
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Bad Request",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Internal Server Error",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/component-items/{id}/status": {
|
||||
"put": {
|
||||
"description": "Change the status of a component item. Supports partial quantity change with automatic split/merge logic. A status history record is created automatically.",
|
||||
"consumes": [
|
||||
"application/json"
|
||||
],
|
||||
"produces": [
|
||||
"application/json"
|
||||
],
|
||||
"tags": [
|
||||
"component-item"
|
||||
],
|
||||
"summary": "Change component item status",
|
||||
"parameters": [
|
||||
{
|
||||
"type": "integer",
|
||||
"description": "Component item ID",
|
||||
"name": "id",
|
||||
"in": "path",
|
||||
"required": true
|
||||
},
|
||||
{
|
||||
"description": "Status change request body",
|
||||
"name": "body",
|
||||
"in": "body",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"$ref": "#/definitions/requests.UpdateComponentItemStatusRequest"
|
||||
}
|
||||
}
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"schema": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/definitions/response.SuccessResponse"
|
||||
},
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"data": {
|
||||
"$ref": "#/definitions/responses.UpdateComponentItemStatusResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"400": {
|
||||
"description": "Validation error (e.g., changed_quantity \u003e quantity, status unchanged)",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
},
|
||||
"404": {
|
||||
"description": "Component item not found",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
},
|
||||
"500": {
|
||||
"description": "Internal server error",
|
||||
"schema": {
|
||||
"$ref": "#/definitions/response.ErrorResponse"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/v1/component-types": {
|
||||
"get": {
|
||||
"description": "Retrieve a list of all component types ordered by creation date",
|
||||
@@ -2369,6 +2772,38 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"models.ComponentItem": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"componentId": {
|
||||
"type": "integer"
|
||||
},
|
||||
"containerId": {
|
||||
"type": "integer"
|
||||
},
|
||||
"createdAt": {
|
||||
"type": "string"
|
||||
},
|
||||
"id": {
|
||||
"type": "integer"
|
||||
},
|
||||
"metadata": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "integer"
|
||||
}
|
||||
},
|
||||
"quantity": {
|
||||
"type": "integer"
|
||||
},
|
||||
"status": {
|
||||
"type": "string"
|
||||
},
|
||||
"updatedAt": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"models.ComponentType": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@@ -2430,6 +2865,41 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"models.FindComponentItemResult": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"cabinetName": {
|
||||
"type": "string"
|
||||
},
|
||||
"componentName": {
|
||||
"type": "string"
|
||||
},
|
||||
"containerName": {
|
||||
"type": "string"
|
||||
},
|
||||
"containerType": {
|
||||
"type": "string"
|
||||
},
|
||||
"quantity": {
|
||||
"type": "integer"
|
||||
},
|
||||
"roomName": {
|
||||
"type": "string"
|
||||
},
|
||||
"shelfName": {
|
||||
"type": "string"
|
||||
},
|
||||
"status": {
|
||||
"type": "string"
|
||||
},
|
||||
"typeName": {
|
||||
"type": "string"
|
||||
},
|
||||
"warehouseName": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"models.Room": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@@ -2570,6 +3040,35 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"requests.CreateComponentItemRequest": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"componentId",
|
||||
"containerId",
|
||||
"quantity",
|
||||
"status"
|
||||
],
|
||||
"properties": {
|
||||
"componentId": {
|
||||
"type": "integer"
|
||||
},
|
||||
"containerId": {
|
||||
"type": "integer"
|
||||
},
|
||||
"metadata": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "integer"
|
||||
}
|
||||
},
|
||||
"quantity": {
|
||||
"type": "integer"
|
||||
},
|
||||
"status": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"requests.CreateComponentRequest": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
@@ -2745,6 +3244,47 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"requests.UpdateComponentItemRequest": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"componentId": {
|
||||
"type": "integer"
|
||||
},
|
||||
"containerId": {
|
||||
"type": "integer"
|
||||
},
|
||||
"metadata": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "integer"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"requests.UpdateComponentItemStatusRequest": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"status"
|
||||
],
|
||||
"properties": {
|
||||
"changedQuantity": {
|
||||
"type": "integer"
|
||||
},
|
||||
"note": {
|
||||
"type": "string"
|
||||
},
|
||||
"status": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"normal",
|
||||
"damaged",
|
||||
"long_unused",
|
||||
"expired",
|
||||
"pending_inspection"
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
"requests.UpdateComponentRequest": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@@ -2907,6 +3447,14 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses.CreateComponentItemResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "integer"
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses.CreateComponentResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
@@ -2992,6 +3540,58 @@
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses.UpdateComponentItemResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"componentId": {
|
||||
"type": "integer"
|
||||
},
|
||||
"containerId": {
|
||||
"type": "integer"
|
||||
},
|
||||
"id": {
|
||||
"type": "integer"
|
||||
},
|
||||
"metadata": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "integer"
|
||||
}
|
||||
},
|
||||
"quantity": {
|
||||
"type": "integer"
|
||||
},
|
||||
"status": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses.UpdateComponentItemStatusResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"changedQuantity": {
|
||||
"type": "integer"
|
||||
},
|
||||
"historyId": {
|
||||
"type": "integer"
|
||||
},
|
||||
"id": {
|
||||
"type": "integer"
|
||||
},
|
||||
"mergedComponentItemId": {
|
||||
"type": "integer"
|
||||
},
|
||||
"newComponentItemId": {
|
||||
"type": "integer"
|
||||
},
|
||||
"newStatus": {
|
||||
"type": "string"
|
||||
},
|
||||
"oldStatus": {
|
||||
"type": "string"
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses.UpdateComponentResponse": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
|
||||
@@ -59,6 +59,27 @@ definitions:
|
||||
type: integer
|
||||
type: array
|
||||
type: object
|
||||
models.ComponentItem:
|
||||
properties:
|
||||
componentId:
|
||||
type: integer
|
||||
containerId:
|
||||
type: integer
|
||||
createdAt:
|
||||
type: string
|
||||
id:
|
||||
type: integer
|
||||
metadata:
|
||||
items:
|
||||
type: integer
|
||||
type: array
|
||||
quantity:
|
||||
type: integer
|
||||
status:
|
||||
type: string
|
||||
updatedAt:
|
||||
type: string
|
||||
type: object
|
||||
models.ComponentType:
|
||||
properties:
|
||||
createdAt:
|
||||
@@ -99,6 +120,29 @@ definitions:
|
||||
updatedAt:
|
||||
type: string
|
||||
type: object
|
||||
models.FindComponentItemResult:
|
||||
properties:
|
||||
cabinetName:
|
||||
type: string
|
||||
componentName:
|
||||
type: string
|
||||
containerName:
|
||||
type: string
|
||||
containerType:
|
||||
type: string
|
||||
quantity:
|
||||
type: integer
|
||||
roomName:
|
||||
type: string
|
||||
shelfName:
|
||||
type: string
|
||||
status:
|
||||
type: string
|
||||
typeName:
|
||||
type: string
|
||||
warehouseName:
|
||||
type: string
|
||||
type: object
|
||||
models.Room:
|
||||
properties:
|
||||
createdAt:
|
||||
@@ -192,6 +236,26 @@ definitions:
|
||||
- code
|
||||
- componentId
|
||||
type: object
|
||||
requests.CreateComponentItemRequest:
|
||||
properties:
|
||||
componentId:
|
||||
type: integer
|
||||
containerId:
|
||||
type: integer
|
||||
metadata:
|
||||
items:
|
||||
type: integer
|
||||
type: array
|
||||
quantity:
|
||||
type: integer
|
||||
status:
|
||||
type: string
|
||||
required:
|
||||
- componentId
|
||||
- containerId
|
||||
- quantity
|
||||
- status
|
||||
type: object
|
||||
requests.CreateComponentRequest:
|
||||
properties:
|
||||
componentTypeId:
|
||||
@@ -309,6 +373,34 @@ definitions:
|
||||
type: integer
|
||||
type: array
|
||||
type: object
|
||||
requests.UpdateComponentItemRequest:
|
||||
properties:
|
||||
componentId:
|
||||
type: integer
|
||||
containerId:
|
||||
type: integer
|
||||
metadata:
|
||||
items:
|
||||
type: integer
|
||||
type: array
|
||||
type: object
|
||||
requests.UpdateComponentItemStatusRequest:
|
||||
properties:
|
||||
changedQuantity:
|
||||
type: integer
|
||||
note:
|
||||
type: string
|
||||
status:
|
||||
enum:
|
||||
- normal
|
||||
- damaged
|
||||
- long_unused
|
||||
- expired
|
||||
- pending_inspection
|
||||
type: string
|
||||
required:
|
||||
- status
|
||||
type: object
|
||||
requests.UpdateComponentRequest:
|
||||
properties:
|
||||
componentTypeId:
|
||||
@@ -414,6 +506,11 @@ definitions:
|
||||
id:
|
||||
type: integer
|
||||
type: object
|
||||
responses.CreateComponentItemResponse:
|
||||
properties:
|
||||
id:
|
||||
type: integer
|
||||
type: object
|
||||
responses.CreateComponentResponse:
|
||||
properties:
|
||||
id:
|
||||
@@ -468,6 +565,40 @@ definitions:
|
||||
isPrimary:
|
||||
type: boolean
|
||||
type: object
|
||||
responses.UpdateComponentItemResponse:
|
||||
properties:
|
||||
componentId:
|
||||
type: integer
|
||||
containerId:
|
||||
type: integer
|
||||
id:
|
||||
type: integer
|
||||
metadata:
|
||||
items:
|
||||
type: integer
|
||||
type: array
|
||||
quantity:
|
||||
type: integer
|
||||
status:
|
||||
type: string
|
||||
type: object
|
||||
responses.UpdateComponentItemStatusResponse:
|
||||
properties:
|
||||
changedQuantity:
|
||||
type: integer
|
||||
historyId:
|
||||
type: integer
|
||||
id:
|
||||
type: integer
|
||||
mergedComponentItemId:
|
||||
type: integer
|
||||
newComponentItemId:
|
||||
type: integer
|
||||
newStatus:
|
||||
type: string
|
||||
oldStatus:
|
||||
type: string
|
||||
type: object
|
||||
responses.UpdateComponentResponse:
|
||||
properties:
|
||||
componentTypeId:
|
||||
@@ -723,6 +854,260 @@ paths:
|
||||
summary: Update component code
|
||||
tags:
|
||||
- component-code
|
||||
/api/v1/component-items:
|
||||
get:
|
||||
consumes:
|
||||
- application/json
|
||||
description: Retrieve a list of all component items ordered by creation date
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
schema:
|
||||
allOf:
|
||||
- $ref: '#/definitions/response.SuccessResponse'
|
||||
- properties:
|
||||
data:
|
||||
items:
|
||||
$ref: '#/definitions/models.ComponentItem'
|
||||
type: array
|
||||
type: object
|
||||
"500":
|
||||
description: Internal Server Error
|
||||
schema:
|
||||
$ref: '#/definitions/response.ErrorResponse'
|
||||
summary: List all component items
|
||||
tags:
|
||||
- component-item
|
||||
post:
|
||||
consumes:
|
||||
- application/json
|
||||
description: Create a new component item with the provided details
|
||||
parameters:
|
||||
- description: Component item request body
|
||||
in: body
|
||||
name: body
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/definitions/requests.CreateComponentItemRequest'
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"201":
|
||||
description: Created
|
||||
schema:
|
||||
allOf:
|
||||
- $ref: '#/definitions/response.SuccessResponse'
|
||||
- properties:
|
||||
data:
|
||||
$ref: '#/definitions/responses.CreateComponentItemResponse'
|
||||
type: object
|
||||
"400":
|
||||
description: Bad Request
|
||||
schema:
|
||||
$ref: '#/definitions/response.ErrorResponse'
|
||||
"500":
|
||||
description: Internal Server Error
|
||||
schema:
|
||||
$ref: '#/definitions/response.ErrorResponse'
|
||||
summary: Create a new component item
|
||||
tags:
|
||||
- component-item
|
||||
/api/v1/component-items/{id}:
|
||||
delete:
|
||||
consumes:
|
||||
- application/json
|
||||
description: Delete a component item by its unique identifier
|
||||
parameters:
|
||||
- description: Component item ID
|
||||
in: path
|
||||
name: id
|
||||
required: true
|
||||
type: integer
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
schema:
|
||||
$ref: '#/definitions/response.SuccessResponse'
|
||||
"400":
|
||||
description: Bad Request
|
||||
schema:
|
||||
$ref: '#/definitions/response.ErrorResponse'
|
||||
"500":
|
||||
description: Internal Server Error
|
||||
schema:
|
||||
$ref: '#/definitions/response.ErrorResponse'
|
||||
summary: Delete component item
|
||||
tags:
|
||||
- component-item
|
||||
get:
|
||||
consumes:
|
||||
- application/json
|
||||
description: Retrieve a single component item using its unique identifier
|
||||
parameters:
|
||||
- description: Component item ID
|
||||
in: path
|
||||
name: id
|
||||
required: true
|
||||
type: integer
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
schema:
|
||||
allOf:
|
||||
- $ref: '#/definitions/response.SuccessResponse'
|
||||
- properties:
|
||||
data:
|
||||
$ref: '#/definitions/models.ComponentItem'
|
||||
type: object
|
||||
"400":
|
||||
description: Bad Request
|
||||
schema:
|
||||
$ref: '#/definitions/response.ErrorResponse'
|
||||
"404":
|
||||
description: Not Found
|
||||
schema:
|
||||
$ref: '#/definitions/response.ErrorResponse'
|
||||
"500":
|
||||
description: Internal Server Error
|
||||
schema:
|
||||
$ref: '#/definitions/response.ErrorResponse'
|
||||
summary: Get component item by ID
|
||||
tags:
|
||||
- component-item
|
||||
put:
|
||||
consumes:
|
||||
- application/json
|
||||
description: Update an existing component item by its ID. Only non-empty fields
|
||||
will be updated.
|
||||
parameters:
|
||||
- description: Component item ID
|
||||
in: path
|
||||
name: id
|
||||
required: true
|
||||
type: integer
|
||||
- description: Component item request body
|
||||
in: body
|
||||
name: body
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/definitions/requests.UpdateComponentItemRequest'
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
schema:
|
||||
allOf:
|
||||
- $ref: '#/definitions/response.SuccessResponse'
|
||||
- properties:
|
||||
data:
|
||||
$ref: '#/definitions/responses.UpdateComponentItemResponse'
|
||||
type: object
|
||||
"400":
|
||||
description: Bad Request
|
||||
schema:
|
||||
$ref: '#/definitions/response.ErrorResponse'
|
||||
"404":
|
||||
description: Not Found
|
||||
schema:
|
||||
$ref: '#/definitions/response.ErrorResponse'
|
||||
"500":
|
||||
description: Internal Server Error
|
||||
schema:
|
||||
$ref: '#/definitions/response.ErrorResponse'
|
||||
summary: Update component item
|
||||
tags:
|
||||
- component-item
|
||||
/api/v1/component-items/{id}/status:
|
||||
put:
|
||||
consumes:
|
||||
- application/json
|
||||
description: Change the status of a component item. Supports partial quantity
|
||||
change with automatic split/merge logic. A status history record is created
|
||||
automatically.
|
||||
parameters:
|
||||
- description: Component item ID
|
||||
in: path
|
||||
name: id
|
||||
required: true
|
||||
type: integer
|
||||
- description: Status change request body
|
||||
in: body
|
||||
name: body
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/definitions/requests.UpdateComponentItemStatusRequest'
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
schema:
|
||||
allOf:
|
||||
- $ref: '#/definitions/response.SuccessResponse'
|
||||
- properties:
|
||||
data:
|
||||
$ref: '#/definitions/responses.UpdateComponentItemStatusResponse'
|
||||
type: object
|
||||
"400":
|
||||
description: Validation error (e.g., changed_quantity > quantity, status
|
||||
unchanged)
|
||||
schema:
|
||||
$ref: '#/definitions/response.ErrorResponse'
|
||||
"404":
|
||||
description: Component item not found
|
||||
schema:
|
||||
$ref: '#/definitions/response.ErrorResponse'
|
||||
"500":
|
||||
description: Internal server error
|
||||
schema:
|
||||
$ref: '#/definitions/response.ErrorResponse'
|
||||
summary: Change component item status
|
||||
tags:
|
||||
- component-item
|
||||
/api/v1/component-items/find/{componentId}:
|
||||
get:
|
||||
consumes:
|
||||
- application/json
|
||||
description: Retrieve component items with full location details (container,
|
||||
shelf, cabinet, room, warehouse) for a given component ID
|
||||
parameters:
|
||||
- description: Component ID
|
||||
in: path
|
||||
name: componentId
|
||||
required: true
|
||||
type: integer
|
||||
produces:
|
||||
- application/json
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
schema:
|
||||
allOf:
|
||||
- $ref: '#/definitions/response.SuccessResponse'
|
||||
- properties:
|
||||
data:
|
||||
items:
|
||||
$ref: '#/definitions/models.FindComponentItemResult'
|
||||
type: array
|
||||
type: object
|
||||
"400":
|
||||
description: Bad Request
|
||||
schema:
|
||||
$ref: '#/definitions/response.ErrorResponse'
|
||||
"500":
|
||||
description: Internal Server Error
|
||||
schema:
|
||||
$ref: '#/definitions/response.ErrorResponse'
|
||||
summary: Find component items by component ID
|
||||
tags:
|
||||
- component-item
|
||||
/api/v1/component-types:
|
||||
get:
|
||||
consumes:
|
||||
|
||||
Reference in New Issue
Block a user