Inventory Ticket

1. Tổng quan

Thuộc tính	Giá trị
ID	FEAT-INV-TICKET
Status	Beta (giai đoạn P2)
Owner	inventory-team
Phụ thuộc	InventoryStock, InventoryLocation, Vendor (loại partner), Customer (loại partner), Material / ProductVariant (line items)

InventoryTicket là một workflow document cho các thao tác stock cần phê duyệt trước khi thực thi: transfer giữa các location, adjustment thủ công, đối chiếu cycle count, return, và scrap. Ticket có các dòng (InventoryTicketItem) và một vòng đời nhiều giai đoạn. Không có hiệu ứng stock cho đến khi ticket đạt COMPLETED — lúc đó các dòng điều khiển các lời gọi adjustStock.

2. Mô hình Entity

Trường InventoryTicket

Trường	Kiểu	Bắt buộc	Mô tả
merchantId	text	✓	Owner
type	text	✓	Xem §3
status	text	✓	Xem §4
partnerType	text		VENDOR / CUSTOMER / NULL
partnerId	text		FK target
sourceLocationId	text		Cho TRANSFER
destinationLocationId	text		Cho TRANSFER
submittedAt / approvedAt / startedAt / completedAt / cancelledAt	timestamptz		Timestamp theo từng trạng thái
note	text		Tự do

Trường InventoryTicketItem

Trường	Kiểu	Bắt buộc	Mô tả
inventoryTicketId	text	✓	FK
inventoryStockId	text		Bucket đích (resolve khi submit)
itemType	text	✓	MATERIAL / PRODUCT_VARIANT
itemId	text	✓	FK target id
plannedQuantity	decimal(15,4)	✓	Lượng được yêu cầu
actualQuantity	decimal(15,4)		Lượng thực sự áp dụng (cho cycle count vs adjustment)
uomId	text		Soft ref
multiplier	decimal(15,4)		UoM-to-base

3. Các loại Ticket

Nguồn: InventoryTicketTypes.

Type	Tác dụng stock khi COMPLETE	Ghi chú
PURCHASE_REQUEST	Không (chỉ thông tin)	Kích hoạt tạo PO downstream (hôm nay là thủ công)
STOCK_IN	+plannedQuantity mỗi line	Nhận hàng thủ công không qua PO
TRANSFER	− source + + destination mỗi line	Atomic mỗi cặp; emit MATERIAL_TRANSFERRED nếu là material
INTERNAL_USE	−plannedQuantity mỗi line	Sử dụng nội bộ kitchen / văn phòng
ADJUSTMENT	± actualQuantity mỗi line	Hiệu chỉnh do operator
CYCLE_COUNT	± actualQuantity−counted	Đối chiếu với count vật lý
RETURN_TO_VENDOR	−plannedQuantity mỗi line	Liên kết với partner Vendor
RETURN_FROM_CUSTOMER	+plannedQuantity mỗi line	Liên kết với partner Customer
SCRAP_DISPOSAL	−plannedQuantity mỗi line	Đánh dấu lý do (DAMAGED / EXPIRED)

4. Vòng đời

Từ	Sự kiện	Đến	Tác dụng
DRAFT	submit	SUBMITTED	Lock items
SUBMITTED	approve	APPROVED	Cổng phê duyệt
APPROVED	start	IN_PROGRESS	Picker bắt đầu làm
IN_PROGRESS	complete	COMPLETED	Áp dụng tác dụng stock cho từng line
any non-terminal	cancel	CANCELLED	Terminal — không có tác dụng stock

Status code	Hiển thị
001_DRAFT	DRAFT
200_SUBMITTED	SUBMITTED
250_APPROVED	APPROVED
300_IN_PROGRESS	IN_PROGRESS
303_COMPLETED	COMPLETED
505_CANCELLED	CANCELLED

5. Vận hành

InventoryTicketService (inventory-ticket.service.ts — 40 dòng)

Kế thừa CRUD từ MerchantScopedService<TInventoryTicketSchema, ...>. Các chuyển vòng đời được wire qua endpoint update + guard ở cấp service (TBD — hiện các phương thức vòng đời còn tối thiểu).

InventoryTicketItemService (inventory-ticket-item.service.ts — 89 dòng)

Phương thức	Mục đích
CRUD (kế thừa)	Quản lý các dòng
Tác dụng stock khi parent COMPLETE	Lặp các dòng và gọi InventoryStockRepository.adjustStock mỗi line

6. REST Endpoints

Verb	Path	Auth	Permission
6× CRUD	/inventory-tickets	JWT/BASIC	InventoryTicket.<crud>
6× CRUD	/inventory-ticket-items	JWT/BASIC	InventoryTicketItem.<crud>
Lifecycle	TBD (submit / approve / start / complete / cancel)	JWT/BASIC	InventoryTicket.<action>

7. Sự kiện

Outbound:

Topic	Khi nào
material.transferred	Sau khi ticket TRANSFER complete cho line material
WebSocket observation/inventory/inventory-stock	Sau mỗi adjustStock của từng line

8. Idempotency khi COMPLETE

Mỗi line ghi một row tracking key theo (INVENTORY_TICKET, ticketId, inventoryStockId). Chạy lại complete (vd từ retry) sẽ trúng idempotency lookup và bỏ qua các line đã áp dụng.

9. Trang liên quan

• Inventory Stock — ngữ nghĩa adjustStock
• Inventory Tracking — reference type INVENTORY_TICKET
• Inventory Location — source/destination cho TRANSFER
• Mô hình miền