@goplusvn/core 0.1.59 → 0.1.60

package/templates/starter-app/README.md

@@ -0,0 +1,141 @@
+# GoERP starter app
+
+Bộ khung **chạy được ngay** cho một ứng dụng ERP trên `@goerp/core`: Next.js 16 +
+Prisma 7 + Better Auth. Cài, seed, `pnpm dev` là có đăng nhập thật, phân quyền,
+CRUD, nhật ký lỗi, nhật ký hoạt động, thông báo, tác vụ nền và tác vụ định kỳ —
+tất cả lấy từ core, không phải mã copy.
+
+Đây là **điểm xuất phát** của một app mới, không phải bản demo để đọc.
+
+---
+
+## Bắt đầu
+
+```bash
+# tạo app mới (không cần clone goerp-core):
+npx -p @goplusvn/core goerp-init my-app --port 3010 && cd my-app
+# trong repo goerp-core thì dùng: pnpm init-app my-app --dir ../my-app
+
+pnpm install                 # postinstall tự chạy `prisma generate`
+# `.env` đã sinh sẵn lúc init (BETTER_AUTH_SECRET ngẫu nhiên) — sửa DATABASE_URL
+# cho trỏ đúng Postgres của bạn
+
+pnpm prisma:deploy           # dựng toàn bộ bảng (migration `_init` có sẵn)
+pnpm seed                    # vai trò + tài khoản admin + dữ liệu mẫu
+pnpm rbac-sync               # nạp resource/action/quyền từ registry
+pnpm dev                     # http://localhost:3010
+```
+
+> ⚠️ **Thứ tự `seed` → `rbac-sync` không đảo được.** `rbac-sync` chỉ cấp quyền
+> mặc định cho resource nó vừa TẠO MỚI (để không đè chỉnh sửa của quản trị
+> viên trên production). Chạy nó trước `seed` thì vai trò chưa tồn tại, grant
+> bị bỏ, và lần chạy sau resource không còn "mới" nên im lặng bỏ qua mãi —
+> app dựng xong mà không ai vào được màn hình nào. Lỡ đảo rồi thì chữa bằng
+> `pnpm rbac-sync --force-grants`.
+>
+> ⚠️ Đừng dùng `prisma migrate dev` / `db push` / `migrate reset` — chúng có thể
+> reset sạch DB khi phát hiện drift. Template đã có sẵn migration khởi tạo nên
+> `pnpm prisma:deploy` là lệnh duy nhất cần, cả lúc dựng lẫn về sau.
+
+Chỉ muốn xem giao diện, chưa có DB? Đặt `BYPASS_AUTH=1` trong `.env` — app boot
+với phiên admin giả, bỏ qua đăng nhập. Màn hình nào đọc DB thì vẫn cần Postgres.
+
+---
+
+## Có sẵn những gì
+
+| Đường dẫn | Nội dung |
+| --- | --- |
+| `/sign-in` | Đăng nhập thật (Better Auth, mật khẩu bcrypt trên bảng `Account`). |
+| `/vi` | Trang chủ mẫu. |
+| `/vi/crud/departments` | CRUD đầy đủ (bảng + form + lọc + nhập/xuất) sinh từ **một** `EntityConfig`. |
+| `/vi/roles` | Vai trò + ma trận quyền. Trang của core, dữ liệu do app nạp. |
+| `/vi/admin/system/settings` | Cấu hình hệ thống (key-value + nhóm cấu hình có kiểu). |
+| `/vi/admin/system/audit` | Nhật ký thay đổi dữ liệu (extension Prisma tự ghi). |
+| `/vi/admin/system/error-logs` | Nhật ký lỗi server kèm stack. |
+| `/vi/admin/system/jobs` | Tác vụ định kỳ: bật/tắt, chạy tay, lịch sử chạy. |
+| `/vi/notifications` | Hộp thư của người dùng + chuông trên thanh tiêu đề. |
+| `/vi/tasks` | Tác vụ nền của người dùng + tải file kết quả. |
+
+---
+
+## Bản đồ mã nguồn
+
+| File | Vai trò |
+| --- | --- |
+| `src/proxy.ts` | **Cổng xác thực default-deny**. Quên gác một route mới cũng không thành lỗ hổng. |
+| `src/lib/api-handler.ts` | **Cổng của tầng API**: session → quyền → audit context → ghi error_logs. Mọi route đi qua đây. |
+| `src/lib/page-guard.ts` | `requirePageAccess(lang, resource)` — gác quyền ở tầng TRANG. |
+| `src/lib/prisma.ts` | Prisma client DUY NHẤT + audit extension + nối dây `SettingsService`. |
+| `src/lib/auth.ts` / `src/lib/better-auth.ts` | `getSession()` — nguồn phiên duy nhất phía server; cấu hình Better Auth. |
+| `src/lib/rbac/access.ts` | Nạp vai trò + quyền + chi nhánh của user trong MỘT truy vấn cho session. |
+| `src/configs/permissions/` | **Permission Registry** — dữ liệu thuần, mỗi phân hệ một file. `pnpm rbac-sync` đồng bộ xuống DB. |
+| `src/configs/entities/` | `EntityConfig` cho CRUD engine. Thêm entity = thêm một file + một dòng registry. |
+| `src/lib/crud/` + `src/app/api/crud/[entity]/` | Backend CRUD generic của core; app chỉ tiêm `prisma` + map entity → model. |
+| `src/data/navigations.ts` | Menu sidebar. `resource` của mỗi mục nối với RBAC để tự ẩn khi thiếu quyền. |
+| `src/instrumentation.ts` | Boot: khởi động cron, thu hồi tác vụ treo, `onRequestError` → error_logs. |
+| `src/server/tasks/` | Tác vụ nền: `configureTaskRunner` + handler mẫu (xuất CSV theo trang). |
+| `src/server/services/` | Dịch vụ dùng chung cho route (thông báo, cấu hình hệ thống). |
+| `src/__tests__/architecture.test.ts` | **Ratchet** kiến trúc — mỗi kiểm tra là một lỗi im lặng đã từng mất thời gian. |
+
+---
+
+## Thêm một entity
+
+1. Thêm model vào `prisma/schema/domain.prisma` → viết migration → `pnpm prisma:deploy`.
+2. Tạo `src/configs/entities/<thing>.config.ts`, đăng ký ở `index.ts`, map khoá số
+   nhiều → model Prisma trong `src/lib/crud/index.ts`.
+3. Khai resource trong `src/configs/permissions/<feature>.permissions.ts` →
+   `pnpm rbac-sync`.
+4. Thêm mục menu trỏ `/crud/<key>`.
+
+Xong. Không viết route, không viết engine.
+
+---
+
+## Lấy thêm tính năng từ core
+
+```bash
+pnpm goerp-features list          # các feature core có sẵn
+pnpm goerp-features add <name>    # chép schema + migration vào app
+```
+
+Feature đã cắm sẵn trong template: `audit-logs`, `background-tasks`,
+`error-logs`, `notifications`, `system-jobs`.
+
+---
+
+## Lệnh hay dùng
+
+| Lệnh | Việc |
+| --- | --- |
+| `pnpm dev` | Chạy dev (cổng 3010). |
+| `pnpm type-check` | `tsc --noEmit`. |
+| `pnpm test` | Ratchet kiến trúc. Chạy trước mỗi lần commit. |
+| `pnpm rbac-sync` | Đồng bộ Permission Registry → DB (idempotent, chạy lại vô hại). |
+| `pnpm prisma:deploy` | Áp migration đang chờ. **Cách duy nhất** đụng vào DB có dữ liệu thật. |
+| `pnpm seed` | Vai trò + tài khoản admin + dữ liệu mẫu. Chạy TRƯỚC `rbac-sync`. |
+
+---
+
+## Triển khai
+
+`Dockerfile` dựng image standalone (node:24-alpine, TZ Việt Nam). Di trú DB
+**không** chạy trong container: chạy `pnpm prisma migrate deploy` từ CI trước khi
+đổi sang bản mới, để migration hỏng thì dừng ngay ở đó thay vì làm container
+khởi động lại vô hạn.
+
+Cần `pnpm-lock.yaml` trong build context (`pnpm install` sinh ra ở lần cài đầu).
+
+---
+
+## Bẫy đã gặp
+
+- Sau khi đổi schema → **restart `next dev`**. Đừng `rm -rf .next` khi dev đang chạy.
+- Mục menu trỏ tới resource chưa khai trong registry sẽ **ẩn vĩnh viễn với mọi
+  người, kể cả admin**, không có lỗi nào hiện ra. `pnpm test` bắt trường hợp này.
+- Biểu thức cron của core thực chất là `setInterval` tính TỪ LÚC BOOT — `0 1 * * *`
+  nghĩa là "mỗi 24 giờ kể từ khi khởi động", không phải "1 giờ sáng". Muốn đúng
+  giờ thì hẹn theo giờ rồi chặn bằng `isLocalHour()` (xem `src/instrumentation.ts`).
+- Viết thêm đường ghi cấu hình thì phải `revalidateTag("system-settings", "max")`,
+  nếu không giao diện đọc giá trị cũ từ cache.

package/templates/starter-app/gitignore

@@ -0,0 +1,9 @@
+node_modules/
+.next/
+out/
+.env
+.env*.local
+*.tsbuildinfo
+
+# Kho tập tin chế độ đĩa local (@goerp/core/storage) — dữ liệu, không phải mã nguồn.
+/storage

package/templates/starter-app/next.config.mjs

@@ -0,0 +1,50 @@
+import fs from "fs"
+import path from "path"
+import { fileURLToPath } from "url"
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+/**
+ * Khi lập trình core song song với app (`pnpm core:link`) hoặc khi app nằm
+ * trong một pnpm workspace, node_modules/@goerp/core là symlink trỏ RA NGOÀI
+ * thư mục app và turbopack báo "Symlink points out of the filesystem root".
+ *
+ * Nới root lên thư mục cha ĐẦU TIÊN chứa cả app lẫn core thật — đi ngược lên
+ * từng cấp chứ đừng đoán cứng ".." : store pnpm của workspace có thể nằm cách
+ * app 2–3 cấp, và chọn nhầm cấp thì Next không thấy được cả gói `next`.
+ *
+ * App độc lập (core cài từ npm, realpath nằm trong node_modules/.pnpm của
+ * chính app) giữ nguyên __dirname để `output: standalone` emit server.js đúng chỗ.
+ */
+const workspaceRoot = (() => {
+  try {
+    const real = fs.realpathSync(path.join(__dirname, "node_modules/@goerp/core"))
+    if (real.startsWith(__dirname + path.sep)) return __dirname
+    let dir = path.dirname(__dirname)
+    while (dir !== path.dirname(dir)) {
+      if (real.startsWith(dir + path.sep)) return dir
+      dir = path.dirname(dir)
+    }
+  } catch {}
+  return __dirname
+})()
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  // Core ship .tsx thô nên app phải transpile. Cần CẢ HAI tên: đường import là
+  // "@goerp/core" (giữ qua alias pnpm) còn package thật trên đĩa là "@goplusvn/core".
+  transpilePackages: ["@goerp/core", "@goplusvn/core"],
+
+  // Docker image gọn: chỉ .next/standalone + static. Xem Dockerfile.
+  output: "standalone",
+  turbopack: { root: workspaceRoot },
+  // Next đòi outputFileTracingRoot trùng turbopack.root — nới cùng nhau.
+  outputFileTracingRoot: workspaceRoot,
+
+  // Không khai redirects() cho "/:lang": "/vi" CHÍNH LÀ trang chủ
+  // (src/app/[lang]/(main)/page.tsx). Nếu app tách riêng "/vi/home" thì mới
+  // thêm redirect, và nhớ rằng redirects() được nướng lúc BUILD — giá trị phải
+  // truyền bằng build arg, không phải env lúc chạy.
+}
+
+export default nextConfig

package/templates/starter-app/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@goerp/starter-app",
+  "version": "0.2.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev --turbopack --port 3010",
+    "build": "prisma generate && next build",
+    "postinstall": "prisma generate",
+    "start": "next start --port 3010",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "prisma:generate": "prisma generate",
+    "prisma:deploy": "prisma migrate deploy",
+    "prisma:studio": "prisma studio",
+    "seed": "tsx prisma/seed.ts",
+    "rbac-sync": "tsx scripts/rbac-sync.ts",
+    "goerp-features": "goerp-features"
+  },
+  "dependencies": {
+    "@goerp/core": "npm:@goplusvn/core@^0.1.59",
+    "@prisma/adapter-pg": "^7.0.0",
+    "@prisma/client": "^7.0.0",
+    "bcryptjs": "^3.0.3",
+    "better-auth": "1.6.23",
+    "lucide-react": "0.446.0",
+    "next": "16.0.10",
+    "next-themes": "^0.2.1",
+    "pg": "^8.16.3",
+    "react": "19.2.0",
+    "react-dom": "19.2.0",
+    "server-only": "^0.0.1",
+    "sonner": "2.0.2",
+    "swr": "^2.3.6",
+    "zod": "3.23.8"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "4.0.17",
+    "@vitejs/plugin-react": "^5.0.4",
+    "@testing-library/react": "^16.3.0",
+    "@types/bcryptjs": "^2.4.6",
+    "@types/node": "22.9.0",
+    "@types/pg": "^8.16.0",
+    "@types/react": "19.0.12",
+    "@types/react-dom": "19.0.4",
+    "dotenv": "^16.4.7",
+    "jsdom": "^27.4.0",
+    "prisma": "^7.0.0",
+    "tailwindcss": "4.1.3",
+    "tsx": "^4.7.1",
+    "tw-animate-css": "1.2.5",
+    "typescript": "5.8.3",
+    "vitest": "^4.0.16"
+  }
+}

package/templates/starter-app/postcss.config.mjs

@@ -0,0 +1,5 @@
+const config = {
+  plugins: ["@tailwindcss/postcss"],
+}
+
+export default config