App 11 – Sản phẩm & kho

Hướng: Xây mới bằng builder · Đợt: Đợt 1 · Phụ thuộc: —
Quy ước chung, nguồn dữ liệu nhân viên và cách chạy builder: 00-tong-quan.md

Mục đích: quản lý danh mục sản phẩm có biến thể (size, màu…), giá vốn và giá bán, tồn kho theo từng kho, phiếu nhập/xuất/chuyển kho; cung cấp sản phẩm cho hóa đơn. Nguồn: Products & Inventory, Product Management, Warehouse Management.

Hướng: xây mới bằng builder. Độc lập; thủ kho lấy từ hrm (tạm dùng người dùng Shell). Xây được ngay ở đợt 1.

Vai trò & quyền

Vai trò	Được làm
Quản trị	Toàn quyền, kể cả danh mục, kho, nhà cung cấp hàng (merchant)
Thủ kho	Tạo và xác nhận phiếu nhập/xuất/chuyển cho kho mình phụ trách; kiểm kê
Nhân viên bán hàng	Xem sản phẩm, giá bán và tồn kho (không xem giá vốn)

Dữ liệu

Thực thể	Trường	Ghi chú
Danh mục sản phẩm	tên, danh mục cha	Dạng cây
Loại sản phẩm	tên (Hàng hóa, Dịch vụ, Nguyên liệu…)	Dịch vụ không quản lý tồn
Sản phẩm	tên, mã (duy nhất), mô tả, danh mục, loại, đơn vị tính, ảnh, thuế suất (%), đang bán (đúng/sai)
Thuộc tính biến thể	sản phẩm, tên thuộc tính (Size, Màu), các giá trị
Biến thể	sản phẩm, SKU (duy nhất), tổ hợp giá trị thuộc tính, giá vốn, giá bán lẻ, tiền tệ, chính sách xuất hóa đơn (Theo đặt hàng, Theo giao hàng), đang bán	Sản phẩm không có biến thể = một biến thể mặc định
Kho	tên, mã (duy nhất), địa chỉ, người liên hệ, thủ kho, đang hoạt động
Tồn kho	kho, biến thể, số lượng, mức tồn tối thiểu	Một dòng cho mỗi cặp kho – biến thể; chỉ thay đổi qua phiếu
Phiếu kho	số phiếu, loại (Nhập, Xuất, Chuyển kho, Điều chỉnh kiểm kê), kho nguồn, kho đích, ngày, lý do, nhà cung cấp hàng, trạng thái (Nháp, Đã xác nhận, Đã hủy), dòng phiếu (biến thể, số lượng, đơn giá)
Nhà cung cấp hàng (merchant)	tên, logo, tiền tệ mặc định, liên hệ, các kho liên kết

Quy tắc nghiệp vụ

1. Mã sản phẩm, SKU, mã kho không trùng; hai biến thể của một sản phẩm không cùng tổ hợp thuộc tính.
2. Tồn kho chỉ thay đổi khi xác nhận phiếu: Nhập cộng vào kho đích; Xuất trừ kho nguồn; Chuyển kho trừ nguồn và cộng đích trong cùng một giao dịch; Điều chỉnh ghi đè bằng số đếm thực tế.
3. Không xác nhận phiếu làm tồn kho âm; phiếu bị từ chối toàn bộ nếu một dòng thiếu hàng.
4. Chuyển kho: kho nguồn khác kho đích; số lượng mỗi dòng lớn hơn 0.
5. Phiếu đã xác nhận không sửa; muốn đảo thì lập phiếu ngược lại.
6. Sản phẩm loại Dịch vụ không xuất hiện trong phiếu kho.
7. Tồn dưới mức tối thiểu thì đánh dấu Cần nhập hàng.
8. Không xóa sản phẩm hoặc kho còn tồn; chỉ được ngừng bán/ngừng hoạt động.
9. Thủ kho chỉ thao tác trên kho mình phụ trách; giá vốn ẩn với nhân viên bán hàng.

Màn hình

Màn hình	Nội dung
Danh sách sản phẩm	Lọc theo danh mục, loại, đang bán; tổng tồn mọi kho
Chi tiết sản phẩm	Thông tin, thuộc tính, bảng biến thể (SKU, giá), tồn theo kho
Kho	Danh sách kho; tồn theo kho, lọc Cần nhập hàng
Phiếu kho	Danh sách phiếu theo loại và trạng thái; soạn phiếu nhiều dòng; Xác nhận
Thẻ kho	Lịch sử nhập/xuất của một biến thể tại một kho kèm tồn lũy kế
Danh mục	Cây danh mục, loại sản phẩm, nhà cung cấp hàng

Prompt cho builder – chia lượt

Dán từng lượt theo thứ tự, mỗi lượt là một tin nhắn. Duyệt kế hoạch trước khi builder chạy; chỉ sang lượt sau khi lượt trước đã kiểm tra xong trong bản xem trước.

Lượt 1 – Lõi: sản phẩm, kho, tồn, phiếu kho

Tôi cần app quản lý sản phẩm và kho có phân quyền, lưu trong database.
Mọi dữ liệu tách theo tổ chức của người đăng nhập.
Nhân viên lấy từ sự kiện của app hrm (hrm:stream:employees) vào bảng chỉ đọc,
khớp người đăng nhập qua mã user Shell; khi hrm chưa phát đủ sự kiện thì tạm dùng
sự kiện người dùng của Shell (shell:stream:users).
Có dữ liệu mẫu cho bảng nhân viên (khoảng 10 người) để thử trong bản xem trước.
Dữ liệu: sản phẩm (tên, mã không trùng, mô tả, loại Hàng hóa/Dịch vụ, đơn vị tính,
thuế suất %, đang bán), biến thể (sản phẩm, SKU không trùng, thuộc tính size/màu,
giá vốn, giá bán, tiền tệ, đang bán; sản phẩm không có biến thể thì có một biến thể
mặc định), kho (tên, mã không trùng, địa chỉ, thủ kho, đang hoạt động), tồn kho theo
kho và biến thể (số lượng, mức tối thiểu), phiếu kho (số phiếu, loại Nhập/Xuất/
Chuyển kho/Điều chỉnh kiểm kê, kho nguồn, kho đích, ngày, lý do, trạng thái Nháp/Đã
xác nhận/Đã hủy, nhiều dòng biến thể, số lượng, đơn giá).
Phân quyền: quản trị toàn quyền; thủ kho chỉ lập và xác nhận phiếu cho kho mình phụ
trách; nhân viên bán hàng xem sản phẩm, giá bán và tồn nhưng không thấy giá vốn.
Quy tắc (kiểm tra ở API): tồn kho chỉ đổi khi xác nhận phiếu – Nhập cộng vào kho
đích, Xuất trừ kho nguồn, Chuyển kho trừ nguồn cộng đích trong một giao dịch, Điều
chỉnh ghi đè bằng số đếm thực tế; không được xuất hoặc chuyển quá số đang tồn, thiếu
một dòng thì từ chối cả phiếu; chuyển kho thì kho nguồn khác kho đích; số lượng mỗi
dòng lớn hơn 0; phiếu đã xác nhận không sửa; sản phẩm Dịch vụ không vào phiếu kho;
tồn dưới mức tối thiểu thì đánh dấu Cần nhập hàng; không xóa sản phẩm hoặc kho còn tồn.
Màn hình: danh sách sản phẩm có tổng tồn; chi tiết sản phẩm có bảng biến thể và tồn
theo kho; tồn theo kho có lọc Cần nhập hàng; soạn và xác nhận phiếu kho.

Lượt 2 – Danh mục và nhà cung cấp hàng

Thêm danh mục sản phẩm dạng cây (tên, danh mục cha, không tạo vòng), ảnh sản phẩm,
và nhà cung cấp hàng (tên, logo, tiền tệ mặc định, liên hệ, các kho liên kết); phiếu
nhập ghi được nhà cung cấp hàng.

Lượt 3 – Thẻ kho

Thêm thẻ kho: lịch sử nhập, xuất, chuyển, điều chỉnh của một biến thể tại một kho,
kèm tồn lũy kế sau mỗi phiếu; lọc theo khoảng ngày; xuất CSV.

Lượt 4 – Phát sự kiện cho app khác

Phát sự kiện qua Redis Streams khi sản phẩm hoặc biến thể được tạo, sửa, ngừng bán
(mã, SKU, tên, đơn vị tính, giá bán, tiền tệ, thuế suất; không gửi giá vốn), để app
hóa đơn đồng bộ danh mục sản phẩm.

Kiểm tra trước khi Publish

Đăng nhập lần lượt bằng từng vai trò trong bản xem trước:

• [ ] Xuất quá số tồn thì cả phiếu bị từ chối, tồn không đổi.
• [ ] Chuyển kho: tồn kho nguồn giảm và kho đích tăng đúng bằng nhau.
• [ ] Phiếu đã xác nhận không sửa được.
• [ ] Nhân viên bán hàng không thấy giá vốn (kiểm tra cả phản hồi API).
• [ ] Checklist chung trong 00-tong-quan.md (mục Checklist chung trước khi Publish).