@goplusvn/core 0.1.34 → 0.1.36

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@goplusvn/core",
   "description": "GoPlusVN Platform Kit - ERP kernel: layout, RBAC, CRUD, multi-tenant, system pages",
-  "version": "0.1.34",
+  "version": "0.1.36",
   "private": false,
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/src/accounting-period/index.ts

@@ -0,0 +1,80 @@
+/**
+ * Kỳ kế toán tháng + khóa sổ — GUARD dùng chung (@goerp/core/accounting-period).
+ *
+ * Promote từ vinhhoa (Phase 1 ERP). Prisma-agnostic: consumer truyền `tx`
+ * (structural PeriodClient có `accountingPeriod.findUnique`). Quy ước: KHÔNG có
+ * dòng AccountingPeriod = kỳ MỞ; chỉ dòng status="closed" là đóng. Tháng/năm
+ * theo lịch VIỆT NAM (UTC+7) tính inline bằng Intl — không phụ thuộc date-utils.
+ *
+ * Consumer schema PHẢI có model `AccountingPeriod { year Int, month Int,
+ * status String, @@unique([year, month], name: "year_month") }`.
+ *
+ * closePeriod/reopenPeriod/listPeriods KHÔNG ở đây — chúng gắn nghiệp vụ GL
+ * (kết chuyển 911) đặc thù từng app; giữ ở consumer.
+ */
+import { AppError } from "../errors/app-error"
+
+/** Client tối thiểu để đọc kỳ kế toán — Prisma delegate của consumer thoả. */
+export interface PeriodClient {
+  accountingPeriod: {
+    findUnique(args: {
+      where: { year_month: { year: number; month: number } }
+      select: { status: true }
+    }): Promise<{ status: string | null } | null>
+  }
+}
+
+const VN_YM_FMT = new Intl.DateTimeFormat("en-CA", {
+  timeZone: "Asia/Ho_Chi_Minh",
+  year: "numeric",
+  month: "2-digit",
+})
+
+/** Năm/tháng theo lịch VN (UTC+7) của một mốc thời gian. */
+export function vnYearMonth(date: Date | string): {
+  year: number
+  month: number
+} {
+  const d = typeof date === "string" ? new Date(date) : date
+  // en-CA → "yyyy-MM"
+  const parts = VN_YM_FMT.format(d)
+  return {
+    year: parseInt(parts.slice(0, 4), 10),
+    month: parseInt(parts.slice(5, 7), 10),
+  }
+}
+
+export async function isPeriodClosed(
+  date: Date | string,
+  tx: PeriodClient
+): Promise<boolean> {
+  const { year, month } = vnYearMonth(date)
+  const row = await tx.accountingPeriod.findUnique({
+    where: { year_month: { year, month } },
+    select: { status: true },
+  })
+  return row?.status === "closed"
+}
+
+/**
+ * Ném AppError 423 nếu ngày nghiệp vụ rơi vào kỳ đã khóa sổ.
+ * `label` mô tả thao tác để thông báo lỗi tự giải thích (vd "sửa phiếu thu").
+ */
+export async function assertPeriodOpen(
+  date: Date | string,
+  options: { tx: PeriodClient; label?: string }
+): Promise<void> {
+  if (await isPeriodClosed(date, options.tx)) {
+    const { year, month } = vnYearMonth(date)
+    const period = `${String(month).padStart(2, "0")}/${year}`
+    throw new AppError({
+      code: "ACCOUNTING_PERIOD_CLOSED",
+      message: `Accounting period ${period} is closed`,
+      userMessage: `Kỳ kế toán ${period} đã khóa sổ — không thể ${
+        options.label ?? "ghi nhận/chỉnh sửa chứng từ trong kỳ này"
+      }. Liên hệ quản trị để mở lại kỳ nếu thật sự cần.`,
+      statusCode: 423,
+      context: { year, month },
+    })
+  }
+}

package/src/approval/__tests__/approval-engine.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from "vitest"
+
+import { planApproval, planRejection, resolveEffectiveSteps } from "../approval-engine"
+import { ApprovalError, type ApprovalFlow } from "../types"
+
+const FLOW: ApprovalFlow = {
+  entityType: "test-doc",
+  steps: [
+    { level: 1, name: "Phê duyệt Lần 1", permission: { resource: "doc", action: "approve_l1" } },
+    { level: 2, name: "Phê duyệt Lần 2", permission: { resource: "doc", action: "approve_l2" } },
+    {
+      level: 3,
+      name: "Phê duyệt Giám đốc",
+      permission: { resource: "doc", action: "approve_l3" },
+      minAmount: 5_000_000,
+    },
+  ],
+}
+
+const allow = () => true
+const denyAll = () => false
+
+describe("approval-engine", () => {
+  it("duyệt tuần tự n cấp: bước kế + isFinal đúng", async () => {
+    const p1 = await planApproval(FLOW, { amount: 10_000_000, completedLevel: 0, terminal: false }, allow)
+    expect(p1.step.level).toBe(1)
+    expect(p1.isFinal).toBe(false)
+
+    const p3 = await planApproval(FLOW, { amount: 10_000_000, completedLevel: 2, terminal: false }, allow)
+    expect(p3.step.level).toBe(3)
+    expect(p3.isFinal).toBe(true)
+  })
+
+  it("điều kiện tiền: dưới ngưỡng bỏ qua cấp có minAmount", async () => {
+    const steps = resolveEffectiveSteps(FLOW, 1_000_000)
+    expect(steps.map((s) => s.level)).toEqual([1, 2])
+
+    const p2 = await planApproval(FLOW, { amount: 1_000_000, completedLevel: 1, terminal: false }, allow)
+    expect(p2.step.level).toBe(2)
+    expect(p2.isFinal).toBe(true) // L2 là bước cuối vì L3 bị lọc
+  })
+
+  it("amount null = áp dụng đủ mọi cấp", () => {
+    expect(resolveEffectiveSteps(FLOW, null)).toHaveLength(3)
+  })
+
+  it("thiếu quyền của ĐÚNG bước hiện tại → 403 kèm tên bước", async () => {
+    const canOnlyL1 = (_r: string, a: string) => a === "approve_l1"
+    await expect(
+      planApproval(FLOW, { amount: null, completedLevel: 1, terminal: false }, canOnlyL1)
+    ).rejects.toThrowError(/Phê duyệt Lần 2/)
+    await expect(
+      planApproval(FLOW, { amount: null, completedLevel: 1, terminal: false }, canOnlyL1)
+    ).rejects.toMatchObject({ status: 403 })
+  })
+
+  it("chứng từ terminal hoặc đã đủ cấp → ApprovalError", async () => {
+    await expect(
+      planApproval(FLOW, { amount: null, completedLevel: 0, terminal: true }, allow)
+    ).rejects.toThrowError(/đã được xử lý/)
+    await expect(
+      planApproval(FLOW, { amount: null, completedLevel: 3, terminal: false }, allow)
+    ).rejects.toThrowError(/đủ cấp/)
+  })
+
+  it("planRejection: chặn terminal + thiếu quyền", async () => {
+    await expect(
+      planRejection(
+        { amount: null, completedLevel: 1, terminal: true },
+        allow,
+        { resource: "doc", action: "reject" },
+        "Bạn không có quyền Từ chối"
+      )
+    ).rejects.toThrowError(/đã được xử lý/)
+    await expect(
+      planRejection(
+        { amount: null, completedLevel: 1, terminal: false },
+        denyAll,
+        { resource: "doc", action: "reject" },
+        "Bạn không có quyền Từ chối"
+      )
+    ).rejects.toThrowError(/không có quyền Từ chối/)
+  })
+})

package/src/approval/approval-engine.ts

@@ -0,0 +1,80 @@
+import {
+  ApprovalError,
+  type ApprovalFlow,
+  type ApprovalPlan,
+  type ApprovalState,
+  type ApprovalStep,
+} from "./types"
+
+/**
+ * APPROVAL ENGINE — máy trạng thái duyệt n cấp dùng chung (Phase 6).
+ *
+ * Engine chỉ TÍNH TOÁN: bước nào đến lượt, ai được duyệt, có phải bước cuối
+ * không. Persistence (đổi status, ghi history, side-effect như tạo phiếu chi)
+ * do adapter của từng module thực hiện trong transaction của nó — engine
+ * không import Prisma nên promote lên core không kéo theo schema.
+ */
+
+/** Lọc các bước áp dụng thực tế theo điều kiện số tiền. */
+export function resolveEffectiveSteps(
+  flow: ApprovalFlow,
+  amount: number | null
+): ApprovalStep[] {
+  const steps = [...flow.steps].sort((a, b) => a.level - b.level)
+  if (amount == null) return steps
+  return steps.filter((s) => s.minAmount == null || amount >= s.minAmount)
+}
+
+/**
+ * Xác định bước duyệt kế tiếp + kiểm tra quyền. Ném ApprovalError nếu chứng
+ * từ đã kết thúc, đã duyệt đủ cấp, hoặc người duyệt thiếu quyền của bước.
+ * `can` được phép async (quyền qua ủy quyền phải tra DB).
+ */
+export async function planApproval(
+  flow: ApprovalFlow,
+  state: ApprovalState,
+  can: (resource: string, action: string) => boolean | Promise<boolean>
+): Promise<ApprovalPlan> {
+  if (state.terminal) {
+    throw new ApprovalError(
+      "Chứng từ này đã được xử lý (Đã duyệt hoặc Bị từ chối)"
+    )
+  }
+  const effectiveSteps = resolveEffectiveSteps(flow, state.amount)
+  const step = effectiveSteps[state.completedLevel]
+  if (!step) {
+    throw new ApprovalError("Chứng từ đã duyệt đủ cấp — không còn bước nào")
+  }
+  if (!(await can(step.permission.resource, step.permission.action))) {
+    throw new ApprovalError(
+      step.denyMessage ?? `Bạn không có quyền ${step.name}`,
+      403
+    )
+  }
+  return {
+    step,
+    isFinal: state.completedLevel === effectiveSteps.length - 1,
+    effectiveSteps,
+  }
+}
+
+/**
+ * Kiểm tra điều kiện từ chối: chứng từ chưa kết thúc + có quyền. Trả về
+ * void — từ chối được phép ở BẤT KỲ cấp nào đang chờ (khớp hành vi 2 flow
+ * hiện có).
+ */
+export async function planRejection(
+  state: ApprovalState,
+  can: (resource: string, action: string) => boolean | Promise<boolean>,
+  permission: { resource: string; action: string },
+  denyMessage: string
+): Promise<void> {
+  if (state.terminal) {
+    throw new ApprovalError(
+      "Chứng từ này đã được xử lý (Đã duyệt hoặc Bị từ chối)"
+    )
+  }
+  if (!(await can(permission.resource, permission.action))) {
+    throw new ApprovalError(denyMessage, 403)
+  }
+}

package/src/approval/index.ts

@@ -0,0 +1,9 @@
+/**
+ * APPROVAL ENGINE — máy trạng thái duyệt n cấp dùng chung (@goerp/core/approval).
+ *
+ * Thuần logic, Prisma-agnostic: consumer tự cung cấp `can(resource, action)`
+ * (đồng bộ/bất đồng bộ) + flow. Persistence + delegation + DB-config do app lo.
+ * Promote từ vinhhoa (Phase 6, KE_HOACH_ERP_THUC_THU.md).
+ */
+export * from "./types"
+export * from "./approval-engine"

package/src/approval/types.ts

@@ -0,0 +1,60 @@
+/**
+ * APPROVAL ENGINE — kiểu dữ liệu (Phase 6, KE_HOACH_ERP_THUC_THU.md).
+ *
+ * Trừu tượng hóa 2 bản duyệt cài riêng (PO + đề nghị thanh toán) thành một
+ * máy trạng thái n cấp dùng chung. Engine THUẦN LOGIC — không import Prisma,
+ * không side-effect: người gọi (adapter trong module) tự lo persistence
+ * trong transaction của mình. Viết kiểu DI để promote lên @goerp/core (M3).
+ */
+
+export interface ApprovalStep {
+  /** Cấp duyệt, 1-based, tăng dần. */
+  level: number
+  /** Tên hiển thị của cấp ("Kế toán", "Giám đốc", "Phê duyệt Lần 1"...). */
+  name: string
+  /** Quyền RBAC yêu cầu để duyệt cấp này. */
+  permission: { resource: string; action: string }
+  /**
+   * Điều kiện theo số tiền: bước CHỈ áp dụng khi amount >= minAmount.
+   * Bỏ trống = luôn áp dụng. (Ví dụ: dưới 5tr bỏ qua cấp Giám đốc.)
+   */
+  minAmount?: number
+  /** Message khi thiếu quyền — mặc định "Bạn không có quyền <name>". */
+  denyMessage?: string
+}
+
+export interface ApprovalFlow {
+  /** Loại chứng từ ("payment-request", "purchase-order"...). */
+  entityType: string
+  steps: ApprovalStep[]
+}
+
+/** Trạng thái duyệt hiện tại của chứng từ — adapter map từ model riêng. */
+export interface ApprovalState {
+  /** Số tiền chứng từ (null = không có điều kiện tiền). */
+  amount: number | null
+  /** Số CẤP đã duyệt xong (0 = chưa cấp nào; tính theo effective steps). */
+  completedLevel: number
+  /** Đã kết thúc (approved/rejected) — mọi thao tác duyệt tiếp bị chặn. */
+  terminal: boolean
+}
+
+export interface ApprovalPlan {
+  /** Bước cần duyệt bây giờ. */
+  step: ApprovalStep
+  /** true nếu đây là bước cuối → sau bước này chứng từ approved. */
+  isFinal: boolean
+  /** Danh sách bước áp dụng thực tế sau khi lọc điều kiện tiền. */
+  effectiveSteps: ApprovalStep[]
+}
+
+/** Lỗi nghiệp vụ của engine — message hiển thị thẳng cho user (VN). */
+export class ApprovalError extends Error {
+  readonly status: number
+
+  constructor(message: string, status = 400) {
+    super(message)
+    this.name = "ApprovalError"
+    this.status = status
+  }
+}

package/src/document-number/index.ts

@@ -0,0 +1,87 @@
+/**
+ * Sinh số chứng từ tập trung — hợp nhất ~12 bản copy-paste của pattern
+ * "advisory lock + MAX sequence trong prefix + 1" rải khắp services.
+ *
+ * Nguyên tắc (đúc từ bug thực tế, xem docs/KE_HOACH_ERP_THUC_THU.md Phase 1):
+ * - Lấy MAX số thứ tự hiện có rồi +1 — KHÔNG `count + 1` (trùng số sau khi xoá
+ *   phiếu ở giữa, hoặc khi nhiều chi nhánh chung một chuỗi đếm).
+ * - `pg_advisory_xact_lock` theo prefix để chống đua đa instance; lock chỉ nhả
+ *   khi transaction commit ⇒ BẮT BUỘC gọi bên trong transaction chứa lệnh
+ *   create (sinh số ngoài tx là lock nhả ngay sau SELECT → trùng số).
+ * - Tên lock của từng loại phiếu GIỮ NGUYÊN giá trị lịch sử (option `lockName`/
+ *   `lockKey`) — đổi tên lock là mất serialize giữa bản cũ/mới lúc rolling
+ *   deploy, hai bản cùng sinh một số.
+ */
+
+/**
+ * Executor tối thiểu để chạy advisory lock — Prisma-agnostic. Prisma
+ * TransactionClient của consumer thoả structural type này ($executeRaw là
+ * tagged-template trả Promise<number>).
+ */
+export interface SqlExecutor {
+  $executeRaw(query: TemplateStringsArray, ...values: unknown[]): Promise<number>
+}
+
+/** Delegate tối thiểu của bảng chứa số phiếu (vd `tx.receipt`). */
+interface NumberedDelegate {
+  findFirst(args: {
+    where: Record<string, unknown>
+    orderBy: Record<string, "desc">
+    select: Record<string, boolean>
+  }): Promise<Record<string, unknown> | null>
+}
+
+export interface NextDocumentNumberOptions {
+  /** Delegate của bảng chứa số phiếu — PHẢI lấy từ `tx` truyền vào, không từ `db`. */
+  delegate: NumberedDelegate
+  /** Field chứa số phiếu, vd "receiptNo". */
+  field: string
+  /** Toàn bộ phần đứng trước số thứ tự (thường gồm ngày), vd "PT-260711". */
+  prefix: string
+  /** Ký tự nối prefix ↔ số thứ tự. Mặc định "-"; dùng "" cho HD2607110001/PAY00000001. */
+  separator?: string
+  /** Số chữ số của phần thứ tự. Mặc định 4. */
+  pad?: number
+  /** Tên khóa advisory lock (mặc định = prefix). Giữ tên lịch sử của từng loại phiếu. */
+  lockName?: string
+  /** Override khóa lock bằng số cứng (Payment dùng 1002 từ trước). */
+  lockKey?: number
+  /** Điều kiện bổ sung merge vào filter của field (vd Payment: `{ not: { contains: "-" } }`). */
+  fieldWhereExtra?: Record<string, unknown>
+  /** Điều kiện bổ sung ở mức where (vd phiếu mở ca: `{ type: "opening" }`). */
+  whereExtra?: Record<string, unknown>
+}
+
+/** Hash tên lock → int (char-code sum — giữ nguyên thuật toán lịch sử). */
+export function advisoryLockKey(name: string): number {
+  return name.split("").reduce((acc, ch) => acc + ch.charCodeAt(0), 0)
+}
+
+export async function nextDocumentNumber(
+  tx: SqlExecutor,
+  options: NextDocumentNumberOptions
+): Promise<string> {
+  const { delegate, field, prefix, separator = "-", pad = 4 } = options
+  const lockKey = options.lockKey ?? advisoryLockKey(options.lockName ?? prefix)
+
+  await tx.$executeRaw`SELECT pg_advisory_xact_lock(${lockKey})`
+
+  const startsWith = `${prefix}${separator}`
+  const last = await delegate.findFirst({
+    where: {
+      [field]: { startsWith, ...(options.fieldWhereExtra ?? {}) },
+      ...(options.whereExtra ?? {}),
+    },
+    orderBy: { [field]: "desc" },
+    select: { [field]: true },
+  })
+
+  let sequence = 1
+  const lastValue = last?.[field]
+  if (typeof lastValue === "string" && lastValue.length > startsWith.length) {
+    const parsed = parseInt(lastValue.slice(startsWith.length), 10)
+    if (!isNaN(parsed)) sequence = parsed + 1
+  }
+
+  return `${startsWith}${String(sequence).padStart(pad, "0")}`
+}