@goplusvn/core 0.1.5 → 0.1.6

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+## Unreleased — platform foundation extraction
+
+Promoted the cross-cutting platform layer out of the Vinh Hoa reference app into
+core so every app inherits the same design system + infrastructure and only
+builds its own business logic. All additive — existing subpaths are unchanged.
+
+### Added
+
+- **`@goerp/core/styles/base.css`** — the canonical design-system tokens (Radix
+  scale → shadcn semantic → Plane semantic; status, charts, sidebar, scrollbar,
+  animations). Apps `@import` this from their Tailwind v4 entry stylesheet and
+  override only brand tokens (`--primary`, `--sidebar-*`). Brand default: indigo.
+  Also ships `@goerp/core/styles/radix-themes.css` (the HSL Radix scale).
+
+- **`@goerp/core/errors`** — `AppError` + `toAppError` (maps Prisma
+  P2002/P2025/P2003/P2014 → friendly message + stable `errorId`),
+  `withErrorHandler` / `createErrorResponse` / `errorResponse`, and the
+  db-injected factories `createErrorLogger(db)` (fingerprint-deduped persistence
+  to an `error_logs` table) + `buildServerError({ logServerError })` /
+  `createServerError({ db })`. Granular client-safe paths:
+  `@goerp/core/errors/{app-error,error-handler,server-error}`.
+
+- **`@goerp/core/export`** — `useExport()` (the unified "Xuất Excel" hook),
+  `triggerBlobDownload` / `filenameFromContentDisposition`, and `toCsv` /
+  `escapeCsvField` (RFC 4180). The crud `exportToCSV` now delegates to `toCsv`,
+  fixing unescaped commas/quotes/newlines and falsy `0`/`false`. Granular paths:
+  `@goerp/core/export/{to-csv,download-file,use-export}`.
+
+- **`@goerp/core/print`** — `DirectPrintProvider` (document-agnostic print device
+  layer: hidden-iframe URL printing with a mobile same-tab fallback, one-page
+  sizing, loading overlay) driven by a `renderContent` render-prop, the
+  `useDirectPrint` hook, and `PrintStyles` (A4/A5 `@media print`). Granular paths:
+  `@goerp/core/print/{direct-print-provider,print-styles}`.
+
+- **`@goerp/core/repository`** — `casUpdate` / `casUpdateById`: the compare-and-
+  swap invariant for money/stock mutations (`updateMany` on expected state,
+  throw on zero rows so an enclosing transaction rolls back).
+
+- **`@goerp/core/utils/{serialize,fetcher,date-utils,cccd-parser}`** —
+  `serializeDecimalFields` (Prisma Decimal → string for Client Components),
+  `swrFetcher` / `swrListFetcher` / `unwrapList`, Vietnam-timezone date helpers,
+  and the CCCD (VN ID-card) QR parser.
+
+### Fixed
+
+- `exportToCSV` (crud) no longer breaks column alignment on values containing
+  commas / quotes / newlines, and no longer drops falsy `0` / `false`.

package/PLATFORM.md

@@ -0,0 +1,111 @@
+# Building an app on `@goerp/core`
+
+Core is the platform foundation: design system, layout, RBAC, CRUD engine, and
+the cross-cutting infrastructure below. An app should only implement its own
+business domain (entities, routes, document templates, domain services) and wire
+the platform pieces — not re-implement them. The Vinh Hoa app is the reference
+implementation of every pattern here.
+
+> When you find yourself copying a util, an error helper, a CSV builder, a print
+> mechanism, or a CAS update into an app, stop — it belongs in core. Promote it
+> and re-export a thin shim from the app so call sites don't change.
+
+## Design system (styles)
+
+One import gives the whole token system; override only your brand.
+
+```css
+/* app: src/app/globals.css */
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "@goerp/core/styles/base.css";          /* Radix → shadcn → Plane tokens */
+@source "../node_modules/@goerp/core/src/**/*.tsx";  /* scan core classes */
+
+:root {
+  --primary: var(--violet-9);     /* re-skin: brand default is indigo */
+  --sidebar-background: 262 60% 20%;
+}
+```
+
+Use semantic tokens, never the raw Tailwind palette: `text-muted-foreground` not
+`text-slate-500`, `bg-card` not `bg-white`, `text-destructive` not `text-red-600`.
+Editing `base.css` reskins every app at once.
+
+## Errors
+
+Bind the db-injected factories once, then use `serverError` in every catch block.
+
+```ts
+// app: src/lib/errors/log-server-error.ts
+import { createErrorLogger, type ErrorLoggerDb } from "@goerp/core/errors/server-error"
+import { db } from "@/lib/prisma"
+export const { logServerError } = createErrorLogger(db as unknown as ErrorLoggerDb)
+
+// app: src/lib/errors/server-error.ts
+import { buildServerError } from "@goerp/core/errors/server-error"
+import { logServerError } from "./log-server-error"
+export const serverError = buildServerError({ logServerError })
+```
+
+```ts
+// in a route catch block
+} catch (error) {
+  return serverError(error, request, { message: "Lỗi xử lý thao tác" })
+}
+```
+
+The app provides an `error_logs` Prisma model matching `ErrorLogDelegate`
+(fingerprint, occurrenceCount, lastSeenAt, severity, …) and keeps its own
+domain error codes; core owns the machinery.
+
+## Export
+
+```ts
+const { exportFile, isExporting } = useExport()             // client buttons
+exportFile(`/api/customers/export?${params}`)               // never window.open
+```
+
+```ts
+import { toCsv } from "@goerp/core/export/to-csv"           // server CSV routes
+return new Response(toCsv(rows, columns), { headers: { ... } })
+```
+
+## Print
+
+Core owns *how* to print; the app supplies *what* via `renderContent`.
+
+```tsx
+// app: wrap core's provider once near the root
+<DirectPrintProvider renderContent={(p) => <PrintContent type={p.type} data={p.data} />}>
+  {children}
+</DirectPrintProvider>
+
+// anywhere
+const { triggerDirectPrint } = useDirectPrint()
+triggerDirectPrint({ printUrl: `/${lang}/print/direct?type=invoice&id=${id}` })
+```
+
+## Repository / money + stock mutations
+
+Mutate money/stock with compare-and-swap, never read-modify-write.
+
+```ts
+import { casUpdateById } from "@goerp/core/repository"
+
+// only writes if the order is still unpaid; throws otherwise → tx rolls back
+await casUpdateById(
+  tx.salesOrder,
+  orderId,
+  { paymentStatus: { not: "paid" } },
+  { paymentStatus: "paid" },
+  new Error("Đơn đã được thanh toán bởi thao tác khác")
+)
+```
+
+## Utils
+
+`@goerp/core/utils` (formatCurrency, formatDate, cn, …) plus the granular:
+`@goerp/core/utils/serialize` (`serializeDecimalFields` before returning Prisma
+rows to Client Components), `.../fetcher` (`swrFetcher`/`swrListFetcher`),
+`.../date-utils` (Vietnam-timezone formatting + Prisma day/month bounds),
+`.../cccd-parser` (VN ID-card QR).

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.5",
+  "version": "0.1.6",
   "private": false,
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -14,7 +14,8 @@
   "files": [
     "src",
     "README.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "PLATFORM.md"
   ],
   "repository": {
     "type": "git",
@@ -34,6 +35,20 @@
       "default": "./src/*/index.ts"
     },
     "./assets/*": "./src/assets/*",
+    "./styles/*": "./src/styles/*",
+    "./errors/app-error": "./src/errors/app-error.ts",
+    "./errors/error-handler": "./src/errors/error-handler.ts",
+    "./errors/server-error": "./src/errors/server-error.ts",
+    "./export/to-csv": "./src/export/to-csv.ts",
+    "./export/download-file": "./src/export/download-file.ts",
+    "./export/use-export": "./src/export/use-export.ts",
+    "./print/direct-print-provider": "./src/print/direct-print-provider.tsx",
+    "./print/print-styles": "./src/print/print-styles.tsx",
+    "./utils/serialize": "./src/utils/serialize.ts",
+    "./utils/fetcher": "./src/utils/fetcher.ts",
+    "./utils/date-utils": "./src/utils/date-utils.ts",
+    "./utils/cccd-parser": "./src/utils/cccd-parser.ts",
+    "./configs/status": "./src/configs/status.ts",
     "./package.json": "./package.json"
   },
   "peerDependencies": {

package/src/crud/lib/import-export-service.ts

@@ -1,4 +1,5 @@
 import type { EntityConfig, ImportOptions, ImportResult } from "../../types";
+import { toCsv } from "../../export/to-csv";
 
 function getRowValue(
   row: Record<string, unknown>,
@@ -257,15 +258,9 @@ export function exportToCSV(
   data: Record<string, unknown>[],
   fields?: string[],
 ): string {
-  if (data.length === 0) return "";
-
-  const keys = fields || Object.keys(data[0]);
-  const headers = keys.join(",");
-  const rows = data.map((row) =>
-    keys.map((key) => String(row[key] || "")).join(","),
-  );
-
-  return [headers, ...rows].join("\n");
+  // Delegates to the shared RFC 4180 writer so values with commas/quotes/
+  // newlines (and falsy 0/false) survive instead of breaking column alignment.
+  return toCsv(data, fields);
 }
 
 /**

package/src/errors/app-error.ts

@@ -0,0 +1,236 @@
+/**
+ * Application Error class with structured error information.
+ * Provides error code, user-friendly message, and context for debugging.
+ */
+export class AppError extends Error {
+    /** Machine-readable error code (e.g. CUSTOMER_DUPLICATE_PHONE) */
+    readonly code: string
+
+    /** User-friendly message in Vietnamese */
+    readonly userMessage: string
+
+    /** HTTP status code */
+    readonly statusCode: number
+
+    /** Additional context for debugging */
+    readonly context?: Record<string, unknown>
+
+    /** HTTP Request context (URL, method, body, status) */
+    readonly requestContext?: Record<string, unknown>
+
+    /** Timestamp of the error */
+    readonly timestamp: string
+
+    /** Unique error ID for tracing */
+    readonly errorId: string
+
+    constructor(options: {
+        code: string
+        message: string
+        userMessage?: string
+        statusCode?: number
+        context?: Record<string, unknown>
+        requestContext?: Record<string, unknown>
+        cause?: unknown
+    }) {
+        super(options.message, { cause: options.cause })
+        this.name = "AppError"
+        this.code = options.code
+        this.userMessage = options.userMessage || options.message
+        this.statusCode = options.statusCode || 500
+        this.context = options.context
+        this.requestContext = options.requestContext
+        this.timestamp = new Date().toISOString()
+        this.errorId = generateErrorId()
+    }
+
+    /**
+     * Convert to a serializable object for API responses.
+     * Contains user-safe info only (no stack traces in production).
+     */
+    toResponse() {
+        return {
+            error: this.userMessage,
+            code: this.code,
+            errorId: this.errorId,
+            timestamp: this.timestamp,
+            ...(process.env.NODE_ENV === "development" && {
+                debug: {
+                    message: this.message,
+                    context: this.context,
+                    requestContext: this.requestContext,
+                    stack: this.stack,
+                },
+            }),
+        }
+    }
+
+    /**
+     * Convert to a full diagnostic string for copy/paste support.
+     */
+    toDiagnosticString(): string {
+        const parts = [
+            `=== Thông tin lỗi ===`,
+            `Mã lỗi: ${this.code}`,
+            `ID: ${this.errorId}`,
+            `Thời gian: ${formatTimestampVN(this.timestamp)}`,
+            `Mô tả: ${this.userMessage}`,
+        ]
+
+        if (this.context && Object.keys(this.context).length > 0) {
+            parts.push(`Chi tiết: ${JSON.stringify(this.context, null, 2)}`)
+        }
+
+        if (this.requestContext && Object.keys(this.requestContext).length > 0) {
+            parts.push(`Request Context:\n${JSON.stringify(this.requestContext, null, 2)}`)
+        }
+
+        if (this.message !== this.userMessage) {
+            parts.push(`Technical: ${this.message}`)
+        }
+
+        if (this.stack) {
+            parts.push(`\nStack Trace:\n${this.stack}`)
+        }
+
+        return parts.join("\n")
+    }
+}
+
+/**
+ * Convert any error to AppError.
+ * Handles Prisma errors, standard errors, and unknown errors.
+ */
+export function toAppError(error: unknown, fallbackUserMessage?: string): AppError {
+    // Already AppError
+    if (error instanceof AppError) return error
+
+    // Prisma known errors
+    if (isPrismaError(error)) {
+        return prismaToAppError(error)
+    }
+
+    // Standard Error
+    if (error instanceof Error) {
+        return new AppError({
+            code: "SYSTEM_ERROR",
+            message: error.message,
+            userMessage: fallbackUserMessage || "Đã xảy ra lỗi hệ thống",
+            statusCode: 500,
+            cause: error,
+        })
+    }
+
+    // Unknown
+    return new AppError({
+        code: "UNKNOWN_ERROR",
+        message: String(error),
+        userMessage: fallbackUserMessage || "Đã xảy ra lỗi không xác định",
+        statusCode: 500,
+    })
+}
+
+// ============================================================================
+// Prisma Error Handling
+// ============================================================================
+
+interface PrismaError {
+    code: string
+    message: string
+    meta?: { target?: string[]; modelName?: string; cause?: string }
+}
+
+function isPrismaError(error: unknown): error is PrismaError {
+    return (
+        typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        typeof (error as any).code === "string" &&
+        (error as any).code.startsWith("P")
+    )
+}
+
+function prismaToAppError(error: PrismaError): AppError {
+    const target = error.meta?.target?.join(", ") || ""
+    const model = error.meta?.modelName || ""
+
+    switch (error.code) {
+        case "P2002": // Unique constraint violation
+            return new AppError({
+                code: "VALIDATION_DUPLICATE",
+                message: `Duplicate value for ${target} in ${model}`,
+                userMessage: `Giá trị đã tồn tại${target ? ` (${target})` : ""}. Vui lòng sử dụng giá trị khác.`,
+                statusCode: 409,
+                context: { prismaCode: error.code, target, model },
+                cause: error,
+            })
+
+        case "P2025": // Record not found
+            return new AppError({
+                code: "NOT_FOUND",
+                message: `Record not found in ${model}`,
+                userMessage: `Không tìm thấy dữ liệu${model ? ` (${model})` : ""}`,
+                statusCode: 404,
+                context: { prismaCode: error.code, model },
+                cause: error,
+            })
+
+        case "P2003": // Foreign key constraint violation
+            return new AppError({
+                code: "VALIDATION_REFERENCE",
+                message: `Foreign key constraint failed on ${target}`,
+                userMessage: `Không thể xóa vì có dữ liệu liên quan`,
+                statusCode: 409,
+                context: { prismaCode: error.code, target, model },
+                cause: error,
+            })
+
+        case "P2014": // Required relation violation
+            return new AppError({
+                code: "VALIDATION_RELATION",
+                message: `Required relation violation in ${model}`,
+                userMessage: `Thiếu dữ liệu bắt buộc liên quan`,
+                statusCode: 400,
+                context: { prismaCode: error.code, model },
+                cause: error,
+            })
+
+        default:
+            return new AppError({
+                code: `DATABASE_${error.code}`,
+                message: error.message,
+                userMessage: "Lỗi cơ sở dữ liệu. Vui lòng thử lại.",
+                statusCode: 500,
+                context: { prismaCode: error.code, model, cause: error.meta?.cause },
+                cause: error,
+            })
+    }
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function generateErrorId(): string {
+    // Short 8 char ID: timestamp base36 + random
+    const ts = Date.now().toString(36).slice(-4)
+    const rand = Math.random().toString(36).slice(2, 6)
+    return `${ts}${rand}`.toUpperCase()
+}
+
+function formatTimestampVN(isoString: string): string {
+    try {
+        const date = new Date(isoString)
+        return date.toLocaleString("vi-VN", {
+            timeZone: "Asia/Ho_Chi_Minh",
+            day: "2-digit",
+            month: "2-digit",
+            year: "numeric",
+            hour: "2-digit",
+            minute: "2-digit",
+            second: "2-digit",
+        })
+    } catch {
+        return isoString
+    }
+}

package/src/errors/error-handler.ts

@@ -0,0 +1,89 @@
+import { NextResponse } from "next/server"
+import type { NextRequest } from "next/server"
+
+import { AppError, toAppError } from "./app-error"
+
+/**
+ * Wrap an API route handler with centralized error handling.
+ * Catches all errors and returns structured JSON responses.
+ *
+ * Usage:
+ *   export async function POST(req: NextRequest) {
+ *     return withErrorHandler(async () => {
+ *       // your logic here
+ *       return NextResponse.json({ data: result })
+ *     }, { operation: "createCustomer" })
+ *   }
+ */
+export async function withErrorHandler(
+    handler: () => Promise<Response>,
+    options?: { operation?: string; req?: NextRequest | Request }
+): Promise<Response> {
+    try {
+        return await handler()
+    } catch (error) {
+        const appError = toAppError(error)
+
+        const requestContext = options?.req
+            ? {
+                  url: options.req.url,
+                  method: options.req.method,
+              }
+            : undefined
+
+        // If the error doesn't already have a requestContext, attach it from the request
+        if (requestContext && !appError.requestContext) {
+            Object.assign(appError, { requestContext })
+        }
+
+        // Dev/terminal visibility. The persisted error_logs row (via serverError)
+        // is the durable record; this is just the in-process trace.
+        console.error(
+            `[${options?.operation || "API"}] ${appError.code}: ${appError.message}`,
+            {
+                errorId: appError.errorId,
+                code: appError.code,
+                statusCode: appError.statusCode,
+                context: appError.context,
+                requestContext: appError.requestContext,
+                operation: options?.operation,
+                stack: appError.stack,
+            }
+        )
+
+        return createErrorResponse(appError)
+    }
+}
+
+/**
+ * Create a structured error response from an AppError.
+ */
+export function createErrorResponse(error: AppError): NextResponse {
+    return NextResponse.json(error.toResponse(), {
+        status: error.statusCode,
+        headers: {
+            "X-Error-Id": error.errorId,
+        },
+    })
+}
+
+/**
+ * Create an AppError and return as response.
+ * Convenience for direct use in routes without wrapping.
+ */
+export function errorResponse(
+    code: string,
+    userMessage: string,
+    statusCode: number = 500,
+    options?: { message?: string; context?: Record<string, unknown> }
+): NextResponse {
+    const error = new AppError({
+        code,
+        message: options?.message || userMessage,
+        userMessage,
+        statusCode,
+        context: options?.context,
+    })
+
+    return createErrorResponse(error)
+}

package/src/errors/index.ts

@@ -0,0 +1,17 @@
+export { AppError, toAppError } from "./app-error"
+export {
+  withErrorHandler,
+  createErrorResponse,
+  errorResponse,
+} from "./error-handler"
+export {
+  createErrorLogger,
+  buildServerError,
+  createServerError,
+} from "./server-error"
+export type {
+  ServerErrorContext,
+  ErrorLogDelegate,
+  ErrorLoggerDb,
+  LogServerError,
+} from "./server-error"