@goplusvn/core 0.1.35 → 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.35",
+  "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/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")}`
+}