node-resource-utils 1.1.9 → 1.1.12

package/resources/src/lib/appInfo.ts

@@ -4,12 +4,12 @@
  * ★ 为什么要有这个文件
  *
  * 之前这些值是硬编码在 layout / 登录页 / 侧边栏三个地方的，
- * AI 建站时经常只改一处（甚至一处都不改），结果交上去的系统标题还叫
+ * AI 建站时经常只改一处（甚至一处都不改），结果上线后的系统标题还叫
  * "业务管理系统"，一眼就是演示品，专业度直接掉分。
  *
  * ★ 用法（AI 建站时第 0 步就要做）
  *
- * 把 APP_NAME 改成题目里的系统名，SUBTITLE 写一句业务定位，
+ * 把 APP_NAME 改成需求里的系统名，SUBTITLE 写一句业务定位，
  * 再把 HOME_STATS 换成这个业务最该看的 3~4 个指标。
  */
 
@@ -22,13 +22,13 @@
  */
 
 /**
- * 系统全称。**必须和题目的系统名一致**。
+ * 系统全称。**必须和需求的系统名一致**。
  * 例：车辆派遣管理系统 / 请销假管理系统 / 值班管理系统
  *
  * ★ 长名字不用自己截断：侧栏那 154px 的文字列只放得下约 9 个字，
  *   超过就折成 2 行（`globals.css` 的 `.wb-brand-title`，行高给足、品牌行自己长高），
  *   再长才用省略号，完整名字挂在 `title` 属性上（悬停可见）。
- *   所以题目名字长也不必改短，写全称即可。
+ *   所以需求名字长也不必改短，写全称即可。
  */
 export const APP_NAME: string = '业务管理系统';
 
@@ -62,7 +62,7 @@ export const APP_DESC: string = '内置 RBAC 权限、操作审计与数据导
  * 登录页是否显示「演示账号」提示。
  *
  * ★ 交付前必须改成 false。
- *   「演示账号：admin / 123456」是评委一眼就认出这是演示系统的最强信号。
+ *   「演示账号：admin / 123456」是用户一眼就认出这是演示系统的最强信号。
  *   自己答辩时记在纸上就行，不要写在页面上。
  */
 export const SHOW_DEMO_ACCOUNT_HINT: boolean = true;
@@ -71,10 +71,10 @@ export const SHOW_DEMO_ACCOUNT_HINT: boolean = true;
 export const DEMO_ACCOUNT_TEXT: string = '演示账号：admin / 123456（超管）· zhangsan / 123456（普通用户）';
 
 /**
- * 是否已经按题目配置过。
+ * 是否已经按需求配置过。
  *
  * 判据：APP_NAME 不再是脚手架默认值。
- * 首页会用它决定要不要显示「待配置」警告，`npm run check:config` 也用它卡构建。
+ * 首页会用它决定要不要显示「待配置」警告，`node scripts/check-config.mjs` 也用它卡构建。
  */
 export const IS_CONFIGURED = APP_NAME !== '业务管理系统';
 
@@ -103,7 +103,7 @@ export type HomeStat = {
  *   所以指标换掉之后记得同步改 `src/app/api/stats/route.ts` 返回同名字段。
  *
  * ★ 默认给的是骨架自带的三个（用户/角色/员工），
- *   接业务后应该全部替换掉 —— 首页是评委第一眼看的地方，
+ *   接业务后应该全部替换掉 —— 首页是用户第一眼看的地方，
  *   摆"用户总数"这种系统自身指标，一眼就是脚手架没改。
  *
  * 例（车辆派遣）：

package/resources/src/lib/appearance.ts

@@ -2,7 +2,7 @@
  * 外观设置 —— 皮肤（配色 + 材质）与字体大小的唯一来源。
  *
  * 为什么要有这一层：
- *   题目一换，页面全是新写的，但"换个外观"这种全站能力不能跟着重写。
+ *   需求一换，页面全是新写的，但"换个外观"这种全站能力不能跟着重写。
  *   所以这里只描述 **token**（颜色、阴影、侧栏材质、品牌区渐变），
  *   页面永远只引用语义（MILITARY.primary / var(--wb-text)），
  *   皮肤切换就是把另一套 token 换上去，页面代码一行都不用动。

package/resources/src/lib/badges.test.ts

@@ -6,7 +6,7 @@ import { BADGE_MAX, BADGE_SOURCES, badgeText, sumBadges } from './badges';
  *
  * 这几条看着琐碎，但都是侧边栏每天要渲染几十次的分支：
  * 0 要不要显示、三位数会不会把菜单挤变形、后端返回 null 时会不会渲染出 "NaN"。
- * NaN 尤其致命 —— 它会原样出现在侧边栏上，是评委一眼就能看见的那种 bug。
+ * NaN 尤其致命 —— 它会原样出现在侧边栏上，是用户一眼就能看见的那种 bug。
  */
 describe('badgeText', () => {
   it('0 和负数不显示', () => {

package/resources/src/lib/docs-shared.ts

@@ -128,7 +128,7 @@ function parseScalar(raw: string): FrontMatterValue {
 /**
  * 解析 `---` 包围的简易 front matter。
  *
- * 刻意不引入 yaml 依赖：比赛环境离线，而文档只需要 title / description /
+ * 刻意不引入 yaml 依赖：运行环境离线，而文档只需要 title / description /
  * order / tags / updated / hidden 这几个标量。解析失败一律降级为空元数据，
  * 正文照常渲染 —— 写错一个冒号不该让整篇文档打不开。
  */

package/resources/src/lib/docs.ts

@@ -28,7 +28,7 @@ import {
  *
  * ★ 内容即目录：`content/docs` 下的 Markdown 文件自动成为文档页，
  *   子目录自动成为分组；新增一篇文档 = 丢一个 .md 进去，不需要改任何页面代码。
- *   这正是「通用底座」的关键 —— 比赛换题、加模块时，只需要补内容，不用改框架。
+ *   这正是「通用底座」的关键 —— 换业务、加模块时，只需要补内容，不用改框架。
  *
  * 约定：
  *   - 页面：`content/docs/<路径>.md`，URL 为 `/docs/<路径>`

package/resources/src/lib/err-text.ts

@@ -5,7 +5,7 @@ import axios from 'axios';
  *
  * 约定：后端业务失败也是 HTTP 200 + `{ code, message }`（见 lib/api.ts），
  * 所以 axios 不报错、但 body 里有 message 的情况很常见 —— 两层都要看。
- * 最后才回落到 JS 的原始 message，避免把一屏英文堆栈甩给评委。
+ * 最后才回落到 JS 的原始 message，避免把一屏英文堆栈甩给用户。
  */
 export function errText(e: unknown, fallback = '操作失败'): string {
   if (axios.isAxiosError(e)) {

package/resources/src/lib/excel.ts

@@ -7,7 +7,7 @@ import dayjs from 'dayjs';
  *
  * 选 exceljs 而不是 xlsx(SheetJS)：exceljs 是纯 JS + 自带类型，
  * 内网离线装完即用；而且它对「样式」支持完整，
- * 导出的表格能带表头底色、冻结行、自动筛选，评委一眼能看出是「认真做的」。
+ * 导出的表格能带表头底色、冻结行、自动筛选，用户一眼能看出是「认真做的」。
  */
 
 export type ExcelColumn = {

package/resources/src/lib/features.ts

@@ -3,12 +3,12 @@
  *
  * ## 默认策略：业务能力默认关，反馈通道默认开
  *
- * AI 中心、知识图谱、文件中心、部门管理默认 `false`。题目的组织维度、要不要 AI、
- * 要不要图谱，只有读过题目的人才知道；默认关着，写业务代码前必须**明确改一次**，
+ * AI 中心、知识图谱、文件中心、部门管理默认 `false`。需求的组织维度、要不要 AI、
+ * 要不要图谱，只有读过需求的人才知道；默认关着，写业务代码前必须**明确改一次**，
  * 于是"这个模块到底要不要"变成一次有意识的决定，而不是默认跟着模板走。
  *
  * 问题反馈是例外：它是任何系统都成立的兜底通道，也是待办与消息中心的示例来源，
- * 所以默认 `true`。题目明确不需要反馈时再关掉。
+ * 所以默认 `true`。需求明确不需要反馈时再关掉。
  *
  * ## 关掉的影响（改之前先知道）
  *

package/resources/src/lib/http.ts

@@ -8,7 +8,7 @@ import { beginTask, endTask } from './pending';
  *
  * ★ 这是「任何耗时场景都有提示」的**兜底层**：
  *   在 Providers 里装一次拦截器，全站所有 axios 请求（现有 34 个接口 +
- *   比赛新加的接口）都会自动登记到全局任务表，
+ *   新加的接口）都会自动登记到全局任务表，
  *   超过 3 秒没有结束，右下角就会浮出一张「正在处理…已等待 N 秒」的小卡片。
  *
  *   也就是说：哪怕新写的页面忘了加 loading，用户也不会对着静止的界面猜。
@@ -32,7 +32,7 @@ declare module 'axios' {
  * 路径 → 人话文案。
  *
  * 命中不到不算错，会回退成「正在处理数据…」。
- * 比赛出了新题、加了新接口，想让提示更具体，在这里补一行正则即可 ——
+ * 换了业务、加了新接口，想让提示更具体，在这里补一行正则即可 ——
  * 不需要改页面、不需要改组件。
  */
 const LABELS: { test: RegExp; text: string }[] = [

package/resources/src/lib/menu-service.ts

@@ -169,14 +169,7 @@ function firstLeafPath(node: MenuTreeNode): string | null {
   return null;
 }
 
-/**
- * 菜单树 → 全局搜索索引。
- *
- * 为什么拿菜单树当唯一数据源：**菜单就是这个系统的「功能注册表」** ——
- * AI 每加一个业务模块都会在 seed 里登记菜单（见通用提示词铁律），
- * 所以新功能不用为搜索写任何代码，进了侧边栏就等于进了搜索。
- * 按钮（type=button）没有页面、隐藏菜单用户看不见，两者都不进索引。
- */
+/** 菜单树 → 全局搜索索引；按钮与隐藏菜单不进索引。 */
 export function buildSearchEntries(nodes: MenuTreeNode[]): SearchEntry[] {
   const out: SearchEntry[] = [];
   const walk = (list: MenuTreeNode[], trail: string) => {

package/resources/src/lib/office.ts

@@ -23,7 +23,7 @@ import { BizError } from '@/lib/api';
 /**
  * 文档处理：解析（Word / Excel / PDF / 纯文本）+ 生成（Word / PDF）。
  *
- * 设计取舍说明（很重要，评委一定会问「为什么不自己解析二进制」）：
+ * 设计取舍说明（很重要，用户一定会问「为什么不自己解析二进制」）：
  *
  *   1. .docx 是 zip + OOXML，交给 mammoth 最稳；mammoth 还能顺手给出 HTML，
  *      这样前端可以「左边纯文本、右边富文本」双视图预览。

package/resources/src/lib/ontology.ts

@@ -2,7 +2,7 @@
  * 本体论（Ontology）配置 —— 知识图谱的"通用引擎"。
  *
  * ★ 这是整套骨架里第二个差异化亮点（第一个是 AI 能力）。
- *   评委打开看到一个能点的知识图谱，基本就记住你了。
+ *   用户打开看到一个能点的知识图谱，基本就记住你了。
  *
  * 设计思路：
  *   图谱画什么，由这个文件里的声明式配置决定，跟代码完全解耦。
@@ -16,7 +16,7 @@
  * ★ views[0] 就是 /graph 默认打开的视图。页面会自动读取 views 并渲染视图下拉，
  *   **不需要改 graph/page.tsx** —— 换业务时只改这个文件就够了。
  *   views 里引用的 entities / relations / root 必须都是已声明的 id，
- *   `npm run check:config` 会在 1 秒内把这些引用错误报出来。
+ *   `node scripts/check-config.mjs` 会在 1 秒内把这些引用错误报出来。
  *
  * 换系统的例子（请销假）：
  *   entities:  Person(人) / LeaveRequest(请假申请) / LeavePlan(休假计划) / LeaveChange(变更申请)

package/resources/src/lib/pending.ts

@@ -1,7 +1,7 @@
 /**
  * 全局等待任务登记表（等待反馈体系的「大脑」）。
  *
- * 解决的问题：比赛出的题不可预知，页面里任何一个耗时动作都可能让人干瞪眼。
+ * 解决的问题：业务需求不可预知，页面里任何一个耗时动作都可能让人干瞪眼。
  * 与其给每个按钮/每个页面各写一套 loading，不如让**所有耗时动作都往这里登记一条**，
  * 由全局浮层统一兜底 —— 即使写页面的人忘了加 spinner，用户也不会看到"点了没反应"。
  *

package/resources/src/lib/search-data.ts

@@ -117,7 +117,7 @@ export async function searchData(user: SessionUser, rawQuery: string): Promise<D
      *   有 deptId  → 套部门范围；
      *   没有 deptId → 非「全部数据」时只看自己名下的行（userId = 自己）。
      * 少了第二条，列表上明明过滤了、Ctrl K 一搜就把别人的单子全列出来 ——
-     * 这是最容易被评委顺手试出来的漏洞。
+     * 这是最容易被用户顺手试出来的漏洞。
      */
     const scopeIsAll = !('deptId' in scope);
     if (!scopeIsAll) {

package/resources/src/lib/system-config.ts

@@ -13,7 +13,7 @@ import { prisma } from '@/lib/prisma';
  *
  * - 布尔统一存 '1' / '0'；
  * - **缺行 = 默认值**，不往 seed 里塞行 —— 默认值以代码为唯一来源，
- *   重跑 db:reset 也不会把管理员的开关悄悄打回默认之外的状态；
+ *   重跑建库流程也不会把管理员的开关悄悄打回默认之外的状态；
  * - 读多写少（登录页每次加载都读一次），SQLite 点查主键，不值得上缓存，
  *   加了缓存反而要处理「管理员改了、登录页还是旧值」的失效问题。
  */

package/resources/src/lib/validation.ts

@@ -2,7 +2,7 @@
  * 输入合理性校验底座 —— 前端表单、后端接口、AI 动态表单共用同一套规则。
  *
  * ★ 为什么单独抽一层，而不是在每个 Form.Item 里写正则：
- *   比赛会换题/加字段，如果校验规则散落在页面和接口里，每加一个「身份证号」
+ *   业务会换/加字段，如果校验规则散落在页面和接口里，每加一个「身份证号」
  *   就要前端写一遍 required、后端再写一遍 zod，提示语还对不上。
  *   这里把「字段类型 → 规整方式 + 校验逻辑 + 友好提示」收敛成注册表：
  *     - 新题加字段：优先复用内置类型；不够用时 registerFieldType() 注册一个即可

package/resources/src/lib/visit-stats.ts

@@ -92,7 +92,7 @@ export async function trackVisit(input: TrackVisitInput, now: Date = new Date())
  *
  * 三条 count 并行发：在线数走 Visitor.lastSeenAt 索引，今日 / 总量走 Visit.createdAt 索引，
  * 在 SQLite 上都是毫秒级。演示规模不引入缓存层 —— 数字要是"缓存过的旧值"，
- * 反而会让评委怀疑系统没在实时统计。
+ * 反而会让用户怀疑系统没在实时统计。
  */
 export async function getVisitStats(now: Date = new Date()): Promise<VisitStats> {
   const [online, today, total] = await Promise.all([