node-resource-utils 0.0.0-stage → 1.1.7

package/resources/src/lib/api.ts

@@ -0,0 +1,160 @@
+import { NextResponse, type NextRequest } from 'next/server';
+import { ZodError } from 'zod';
+
+/**
+ * 统一 API 响应结构。
+ *
+ * 前端永远只认这一种形状，于是「错误处理」只需要写一遍：
+ *   { code: 0, data: T, message: 'OK' }        成功
+ *   { code: 400xx, data: null, message: '...' } 失败
+ *
+ * 这样做的直接好处：任何接口忘记 try/catch 都不会把 500 堆栈泄漏给前端，
+ * 评委点到的永远是干净的提示语，而不是一屏红字。
+ */
+export type ApiOk<T> = { code: 0; data: T; message: string };
+export type ApiErr = { code: number; data: null; message: string };
+
+export const CODE = {
+  OK: 0,
+  BAD_REQUEST: 40000,
+  UNAUTHORIZED: 40100,
+  FORBIDDEN: 40300,
+  NOT_FOUND: 40400,
+  CONFLICT: 40900,
+  SERVER_ERROR: 50000,
+} as const;
+
+export function ok<T>(data: T, message = 'OK', init?: ResponseInit) {
+  return NextResponse.json<ApiOk<T>>({ code: 0, data, message }, init);
+}
+
+export function fail(message: string, code: number = CODE.BAD_REQUEST, status = 200) {
+  // 注意：业务失败一律用 HTTP 200 + 业务码，避免浏览器/代理对 4xx 做额外处理，
+  // 前端拦截器只需看 code 字段。真正的传输层错误才用非 200。
+  return NextResponse.json<ApiErr>({ code, data: null, message }, { status });
+}
+
+/** 业务异常：抛出后由 withRoute 统一转成 fail() */
+export class BizError extends Error {
+  constructor(
+    message: string,
+    public code: number = CODE.BAD_REQUEST,
+    public status = 200
+  ) {
+    super(message);
+    this.name = 'BizError';
+  }
+}
+
+/**
+ * 路由包装器：把任何未捕获异常变成规范响应。
+ * 用法：export const GET = withRoute(async (req) => { ... return ok(data) })
+ */
+export function withRoute<Ctx = unknown>(
+  handler: (req: NextRequest, ctx: Ctx) => Promise<NextResponse> | NextResponse
+) {
+  return async (req: NextRequest, ctx: Ctx) => {
+    const t0 = Date.now();
+    try {
+      return await handler(req, ctx);
+    } catch (e) {
+      const ms = Date.now() - t0;
+      if (e instanceof BizError) {
+        return fail(e.message, e.code, e.status);
+      }
+      if (e instanceof ZodError) {
+        // 校验提示已经由 validation.ts 拼成「字段名 + 错在哪 + 正确格式」，
+        // 不再把内部字段路径（如 idCard）拼到用户看到的文案里。
+        const first = e.issues[0];
+        return fail(`参数校验失败：${first?.message || '请检查输入内容'}`, CODE.BAD_REQUEST);
+      }
+      console.error(`[API] ${req.method} ${req.nextUrl.pathname} 失败 (${ms}ms)`, e);
+      const msg = process.env.NODE_ENV === 'production' ? '服务器内部错误' : String((e as Error)?.message || e);
+      return fail(msg, CODE.SERVER_ERROR);
+    }
+  };
+}
+
+/** 解析分页 / 排序 / 关键字，带安全上限，避免前端传 pageSize=999999 把库拖死 */
+export type ListQuery = {
+  page: number;
+  pageSize: number;
+  skip: number;
+  take: number;
+  keyword: string;
+  orderBy: Record<string, 'asc' | 'desc'>;
+  raw: URLSearchParams;
+};
+
+export function parseListQuery(req: NextRequest, defaultSort: Record<string, 'asc' | 'desc'> = { createdAt: 'desc' }): ListQuery {
+  const sp = req.nextUrl.searchParams;
+  const page = Math.max(1, Number(sp.get('page') || 1) || 1);
+  const pageSize = Math.min(200, Math.max(1, Number(sp.get('pageSize') || 10) || 10));
+  const keyword = (sp.get('keyword') || '').trim();
+
+  const sortField = sp.get('sortField');
+  const sortOrder = sp.get('sortOrder') === 'ascend' ? 'asc' : sp.get('sortOrder') === 'descend' ? 'desc' : null;
+  // 计算属性名的对象字面量会被 TS 拓宽成 { [x: string]: string }，这里显式标注收窄回字面量联合
+  const orderBy: Record<string, 'asc' | 'desc'> =
+    sortField && sortOrder ? { [sortField]: sortOrder } : defaultSort;
+
+  return { page, pageSize, skip: (page - 1) * pageSize, take: pageSize, keyword, orderBy, raw: sp };
+}
+
+/** 统一分页返回体 */
+export function pageResult<T>(list: T[], total: number, q: Pick<ListQuery, 'page' | 'pageSize'>) {
+  return { list, total, page: q.page, pageSize: q.pageSize };
+}
+
+/** 从请求里取客户端信息，写审计日志用 */
+export function clientInfo(req: NextRequest) {
+  const h = req.headers;
+  return {
+    ip:
+      h.get('x-forwarded-for')?.split(',')[0]?.trim() ||
+      h.get('x-real-ip') ||
+      '127.0.0.1',
+    userAgent: h.get('user-agent') || '',
+  };
+}
+
+/**
+ * 写操作审计。故意做成"失败不影响主流程"：
+ * 日志写不进去也得让业务成功，否则一个日志表问题就能让整个系统不可用。
+ */
+export async function audit(params: {
+  userId?: string | null;
+  username?: string | null;
+  module: string;
+  action: string;
+  method?: string;
+  path?: string;
+  targetId?: string | null;
+  detail?: unknown;
+  ip?: string;
+  userAgent?: string;
+  status?: number;
+  durationMs?: number;
+}) {
+  try {
+    const { prisma } = await import('@/lib/prisma');
+    await prisma.operationLog.create({
+      data: {
+        userId: params.userId ?? null,
+        username: params.username ?? null,
+        module: params.module,
+        action: params.action,
+        method: params.method ?? null,
+        path: params.path ?? null,
+        targetId: params.targetId ?? null,
+        detail: params.detail === undefined ? null : JSON.stringify(params.detail),
+        ip: params.ip ?? null,
+        userAgent: params.userAgent ?? null,
+        status: params.status ?? 1,
+        durationMs: params.durationMs ?? null,
+      },
+    });
+  } catch (e) {
+    console.error('[audit] 写审计日志失败（已忽略，不影响业务）', e);
+  }
+}

package/resources/src/lib/appInfo.ts

@@ -0,0 +1,128 @@
+/**
+ * 全站信息配置 —— **系统名称、副标题、首页统计卡都在这里改**。
+ *
+ * ★ 为什么要有这个文件
+ *
+ * 之前这些值是硬编码在 layout / 登录页 / 侧边栏三个地方的，
+ * AI 建站时经常只改一处（甚至一处都不改），结果交上去的系统标题还叫
+ * "业务管理系统"，一眼就是演示品，专业度直接掉分。
+ *
+ * ★ 用法（AI 建站时第 0 步就要做）
+ *
+ * 把 APP_NAME 改成题目里的系统名，SUBTITLE 写一句业务定位，
+ * 再把 HOME_STATS 换成这个业务最该看的 3~4 个指标。
+ */
+
+/* ============================ 1. 系统标识 ============================ */
+
+/**
+ * ⚠️ 下面的字符串常量统一显式标注 `: string`。
+ * 不标的话 TS 会把它们推断成字面量类型，之后任何
+ * `if (APP_NAME === 'xxx')` 都会报 TS2367「此比较看起来是无意为之，类型无重叠」。
+ */
+
+/**
+ * 系统全称。**必须和题目的系统名一致**。
+ * 例：车辆派遣管理系统 / 请销假管理系统 / 值班管理系统
+ *
+ * ★ 长名字不用自己截断：侧栏那 154px 的文字列只放得下约 9 个字，
+ *   超过就折成 2 行（`globals.css` 的 `.wb-brand-title`，行高给足、品牌行自己长高），
+ *   再长才用省略号，完整名字挂在 `title` 属性上（悬停可见）。
+ *   所以题目名字长也不必改短，写全称即可。
+ */
+export const APP_NAME: string = '业务管理系统';
+
+/** 侧边栏收起时显示的短名（2~4 个字符，或英文缩写） */
+export const APP_SHORT: string = 'BIZ';
+
+/**
+ * 侧边栏副标题 / 登录页副标题。一句话说清这个系统是干什么的。
+ * 例：「车辆申请、审批派车与归队登记」「请假申请与销假跟踪」
+ */
+export const APP_SUBTITLE: string = '内置 RBAC 权限、操作审计与数据导出';
+
+/** 登录页左侧特性列表（3 条，写这个系统的核心能力） */
+export const APP_FEATURES: string[] = [
+  '统一的账号与权限管理',
+  '完整的操作审计留痕',
+  '数据导入导出与文档处理',
+];
+
+/** 浏览器标签页标题模板 */
+export const APP_TITLE_SUFFIX: string = '';
+
+/**
+ * meta description / 浏览器与分享卡片的描述。
+ * **不要留"基于 Next.js + antd + Prisma 的业务系统"这种框架描述** ——
+ * 一眼就是模板。写成这个系统的业务定位。
+ */
+export const APP_DESC: string = '内置 RBAC 权限、操作审计与数据导出的业务系统';
+
+/**
+ * 登录页是否显示「演示账号」提示。
+ *
+ * ★ 交付前必须改成 false。
+ *   「演示账号：admin / 123456」是评委一眼就认出这是演示系统的最强信号。
+ *   自己答辩时记在纸上就行，不要写在页面上。
+ */
+export const SHOW_DEMO_ACCOUNT_HINT: boolean = true;
+
+/** 登录页上那段提示文案（SHOW_DEMO_ACCOUNT_HINT 为 false 时整块不渲染） */
+export const DEMO_ACCOUNT_TEXT: string = '演示账号：admin / 123456（超管）· zhangsan / 123456（普通用户）';
+
+/**
+ * 是否已经按题目配置过。
+ *
+ * 判据：APP_NAME 不再是脚手架默认值。
+ * 首页会用它决定要不要显示「待配置」警告，`npm run check:config` 也用它卡构建。
+ */
+export const IS_CONFIGURED = APP_NAME !== '业务管理系统';
+
+/* ============================ 2. 首页统计卡 ============================ */
+
+export type HomeStat = {
+  /** 指标名，例如「待派车申请」 */
+  label: string;
+  /** 接口字段名，从 /api/stats 返回的 data 里取 */
+  key: string;
+  /** antd 图标组件名（不填则不显示图标） */
+  icon?: string;
+  /** 强调色 */
+  color?: string;
+  /** 单位后缀，如「辆」「单」「人」 */
+  suffix?: string;
+  /** 点击下钻到哪个页面（不填则卡片不可点，避免"能抬起来但点不动"） */
+  href?: string;
+};
+
+/**
+ * 首页顶部的统计卡。**换成这个业务最该看的指标。**
+ *
+ * ★ 工作台（`(admin)/dashboard/page.tsx`）**直接渲染这个数组**：
+ *   改完这里，卡片就跟着变，不用再改页面。数字从 `/api/stats` 的返回里按 `key` 取，
+ *   所以指标换掉之后记得同步改 `src/app/api/stats/route.ts` 返回同名字段。
+ *
+ * ★ 默认给的是骨架自带的三个（用户/角色/员工），
+ *   接业务后应该全部替换掉 —— 首页是评委第一眼看的地方，
+ *   摆"用户总数"这种系统自身指标，一眼就是脚手架没改。
+ *
+ * 例（车辆派遣）：
+ *   { label:'可用车辆', key:'vehicleAvailable', suffix:'辆', color:'#4E5F3C', icon:'CarOutlined', href:'/dispatch/vehicles' },
+ *   { label:'今日出车', key:'dispatchToday',     suffix:'单', color:'#7C8F63', icon:'SendOutlined' },
+ *   { label:'待派车申请', key:'dispatchPending',  suffix:'单', color:'#B99C6B', icon:'ClockCircleOutlined', href:'/dispatch/requests' },
+ *   { label:'维修中',   key:'vehicleRepairing',  suffix:'辆', color:'#B4472F', icon:'ToolOutlined' },
+ *
+ * `color` 请用军绿主题色系（`MILITARY`）而不是饱和蓝绿；`href` 不填就不显示可点手感。
+ */
+export const HOME_STATS: HomeStat[] = [
+  { label: '用户总数', key: 'userCount', icon: 'TeamOutlined', color: '#4E5F3C' },
+  { label: '角色数量', key: 'roleCount', icon: 'SafetyCertificateOutlined', color: '#7C8F63' },
+  { label: '员工总数', key: 'empCount', icon: 'IdcardOutlined', color: '#B99C6B' },
+];
+
+/**
+ * 首页欢迎语（工作台标题下的一行字）。
+ * 留空则不显示。有业务语境的欢迎语比通用问候专业得多。
+ * 例：「今天有 3 个待派车申请需要处理」
+ */
+export const HOME_WELCOME: string = '';