Imported from Tai1337/He_Thong_Quan_Ly_Ban_Dang_DMS_TradeLedger (.agents/skills/dms-npp-database-schema/SKILL.md). Install upstream with npx skills add Tai1337/He_Thong_Quan_Ly_Ban_Dang_DMS_TradeLedger --skill dms-npp-database-schema. Copyright stays with the author.

DMS-NPP Database Schema Reference

Toàn bộ schema được định nghĩa tại: prisma/schema.prisma
Database: MySQL, db name: dms_npp

Nhóm 1: Danh mục (Master Data)

roles – Vai trò người dùng

distributors – Nhà phân phối (NPP)

users – Người dùng hệ thống

product_categories – Danh mục sản phẩm (cây phân cấp)

products – Sản phẩm (SKU)

suppliers – Nhà cung cấp

retailers – Đại lý / Điểm bán lẻ

warehouses – Kho hàng

Nhóm 2: Tồn kho (Inventory)

stock_lots – Lô hàng (tracking theo lô)

stock_balances – Số dư tồn kho theo lô

[Cải tiến] Tồn khả dụng = quantity_on_hand - quantity_reserved (tính trong app, không lưu vào DB)

inventory_transactions – Giao dịch nhập/xuất kho

Nhóm 3: Đơn hàng bán (Sales)

sales_orders – Đơn hàng bán (SO)

sales_order_items – Chi tiết đơn hàng bán

order_status_history – Lịch sử trạng thái đơn hàng

Nhóm 4: Mua hàng (Purchase) & Đề xuất PPO

ppo_suggestions – Đề xuất mua hàng tự động (ROP Engine & Khung giờ 9h-11h)

purchase_orders – Lệnh mua hàng (PO)

purchase_order_items – Chi tiết PO

purchase_returns – Trả hàng nhà cung cấp (POR)

purchase_return_items – Chi tiết POR

purchase_plan_orders – Đề nghị đặt hàng cũ (Legacy)

Nhóm 5: Vận chuyển & Điều phối kho

delivery_trips – Chuyến giao nhận hàng (Inbound & Outbound)

stock_transfers – Điều phối tồn kho

stock_transfer_items – Chi tiết điều phối

Nhóm 6: Kiểm kê & Điều chỉnh

inventory_adjustments – Điều chỉnh kho

inventory_adjustment_items – Chi tiết điều chỉnh

inventory_counts – Phiếu kiểm kê

inventory_count_items – Chi tiết kiểm kê

Nhóm 7: Hoá đơn & Thanh toán [CẢI TIẾN]

invoices – Hoá đơn bán hàng

payments – Lịch sử thanh toán

Nhóm 8: Khuyến mãi [CẢI TIẾN]

promotions – Chương trình khuyến mãi

promotion_products – Sản phẩm trong chương trình KM

Các quy tắc Prisma query quan trọng

// ✅ Đúng - Convert BigInt
const result = await prisma.salesOrder.findMany();
return result.map(r => ({ ...r, id: r.id.toString() }));

// ✅ Đúng - Include relations
const order = await prisma.salesOrder.findUnique({
  where: { id: BigInt(req.params.id) },
  include: { items: { include: { product: true } }, retailer: true }
});

// ✅ Đúng - Filter theo distributor (data isolation)
const orders = await prisma.salesOrder.findMany({
  where: { distributorId: BigInt(user.distributorId) }
});

// ✅ Đúng - Pagination
const page = parseInt(req.query.page) || 1;
const limit = 20;
const orders = await prisma.salesOrder.findMany({
  skip: (page - 1) * limit,
  take: limit,
  orderBy: { createdAt: 'desc' }
});

// ✅ Đúng - Kiểm tra tồn kho khả dụng (tránh oversell)
const balance = await prisma.stockBalance.findUnique({ where: { lotId: BigInt(lotId) } });
const available = balance.quantityOnHand - balance.quantityReserved;
if (available < requiredQty) throw new Error('Tồn kho không đủ');

// ✅ Đúng - Convert BigInt
const result = await prisma.salesOrder.findMany();
return result.map(r => ({ ...r, id: r.id.toString() }));

// ✅ Đúng - Include relations
const order = await prisma.salesOrder.findUnique({
  where: { id: BigInt(req.params.id) },
  include: { items: { include: { product: true } }, retailer: true }
});

// ✅ Đúng - Filter theo distributor (data isolation)
const orders = await prisma.salesOrder.findMany({
  where: { distributorId: BigInt(user.distributorId) }
});

// ✅ Đúng - Pagination
const page = parseInt(req.query.page) || 1;
const limit = 20;
const orders = await prisma.salesOrder.findMany({
  skip: (page - 1) * limit,
  take: limit,
  orderBy: { createdAt: 'desc' }
});