node-resource-utils 0.0.0-stage → 1.1.7

package/resources/content/docs/guide/data.md

@@ -0,0 +1,87 @@
+---
+title: 数据浏览、导入与导出
+description: 列表查询、增删改查、Excel 导入导出的通用规则。
+order: 4
+tags: [数据, 列表, Excel, 导入, 导出]
+updated: 2026-10-21
+---
+
+业务模块的列表页遵循同一套交互约定。学会一个模块，其它模块基本可以直接上手。
+
+## 列表页
+
+列表页通常包含搜索栏、操作按钮、表格和分页四部分。
+
+- **搜索**：输入关键词后按回车或点「查询」，支持按名称、编号等常用字段匹配。
+- **筛选**：下拉框和日期范围可以组合使用，条件之间是「并且」关系。
+- **排序**：点击带排序箭头的表头，在升序、降序之间切换。
+- **分页**：在表格右下角切换页码或每页条数。筛选条件会跟着翻页保持。
+
+没有结果时，先清空筛选条件再试；仍然为空可能是当前账号的数据范围只覆盖了部分部门。
+
+## 新增与编辑
+
+点「新增」会打开表单。带星号的字段必填，保存前会做一次校验：
+
+- 编号、用户名这类字段通常要求唯一，重复会给出明确提示。
+- 部门、角色等关联字段只能选择当前账号有权限的范围。
+- 日期和金额会按页面提示的格式校验。
+
+编辑使用同一套表单。保存成功后列表会刷新，操作会写入操作日志。
+
+## 删除
+
+删除通常采用逻辑删除：数据从列表消失，但仍保留在数据库中，管理员可以在必要时追溯。
+
+删除前注意：
+
+- 确认没有下级数据或关联数据仍在使用。
+- 删除是不可逆的业务动作，附件和关联记录可能一并失效。
+- 批量删除会逐条校验权限和数据范围，部分失败时会说明原因。
+
+## Excel 导入
+
+带「导入」按钮的模块支持 Excel 批量录入。
+
+标准流程：
+
+1. 点「导入」→「下载模板」，先拿到带表头和示例的模板。
+2. 按模板填写数据，不要修改表头文字、列顺序和 sheet 名称。
+3. 上传文件，系统会逐行校验并返回结果。
+4. 有错误的行会列出行号和原因，修正后可以只重新导入失败部分。
+
+常见校验失败原因：
+
+| 提示 | 处理方式 |
+| --- | --- |
+| 必填项为空 | 补齐模板中的必填列 |
+| 编号已存在 | 改为新编号，或走编辑而不是导入 |
+| 部门不存在 | 先在部门管理里创建，或改成已存在的部门名称 |
+| 日期格式不正确 | 使用 `YYYY-MM-DD`，避免合并单元格 |
+
+导入会逐条记录结果，成功和失败数量都会显示。文件较大时请等待页面提示完成，不要重复提交。
+
+## Excel 导出
+
+点「导出」会按**当前筛选条件**生成 Excel 文件；清空筛选后再导出即为全量数据。
+
+- 导出范围同样受数据范围限制，不会带出无权查看的记录。
+- 文件生成需要一点时间，数据量大时请等待下载开始。
+- 如果导出的中文出现乱码，请使用 Excel 或 WPS 打开，不要用纯文本编辑器另存。
+- 导出的列以页面配置为准，敏感字段（如密码哈希、密保答案）不会出现在导出文件里。
+
+## 文件与附件
+
+部分表单支持上传附件。附件会保存在系统的上传目录中，下载时同样校验权限：
+
+- 只能下载自己有权访问的记录所关联的附件。
+- 文件名会做安全处理，避免路径穿越和特殊字符问题。
+- 单个文件大小和类型以页面提示为准，超限会直接拒绝。
+
+更完整的文件说明见 [文件与文档处理](/docs/features/files)。
+
+## 操作日志
+
+所有新增、修改、删除、导入、导出都会写入操作日志。管理员可以在「系统管理 → 操作日志」按模块、操作人、时间和结果检索。
+
+日志只记录操作结果和摘要，不保存完整密码或敏感内容。发现数据异常时，日志通常是定位问题的第一手材料。

package/resources/content/docs/guide/navigation.md

@@ -0,0 +1,81 @@
+---
+title: 界面与导航
+description: 侧边栏、面包屑、收藏、全局搜索与红点提示。
+order: 2
+tags: [界面, 导航, 搜索]
+updated: 2026-10-21
+---
+
+后台采用「侧边栏 + 顶栏 + 内容区」的经典布局。熟悉下面几个入口，日常操作会快很多。
+
+## 侧边栏
+
+侧边栏按业务模块分组，只显示当前账号有权限访问的菜单。
+
+- 点击顶栏左侧的折叠按钮可以收起侧边栏，只保留图标；鼠标悬停可查看菜单名。
+- 当前所在页面会高亮，所在分组自动展开。
+- 分组下的菜单全部不可见时，分组本身也不会显示。
+- 菜单右侧的红点数字表示待处理或未读数量；折叠状态下数字会压到图标右上角。
+
+## 面包屑
+
+面包屑显示「工作台 / 分组 / 当前页面」。点击任意一级可以返回，适合从深层页面快速退回。
+
+## 我的常用
+
+每个页面右上角有一个星标：
+
+1. 进入页面后点击星标，页面会出现在侧边栏顶部的「我的常用」。
+2. 再次点击取消收藏。
+3. 最多收藏 8 个页面，超出时会提示先移除一个。
+
+收藏保存的是页面地址，不是菜单编号。因此菜单改名、权限收回或模块关闭后，收藏会自动跟随，不会出现点进去是空页面的情况。
+
+## 全局搜索
+
+按 `Ctrl K`（macOS 为 `⌘ K`）打开全局搜索，或在顶栏点击搜索框。
+
+搜索结果分两类：
+
+- **功能**：来自菜单树，匹配菜单名、别名和路径。目录也能搜到，会跳到它的第一个页面。
+- **数据**：在当前账号权限范围内检索业务记录，权限过滤在服务端完成。
+
+输入多个关键词时用空格分隔，系统按「全部命中」处理。例如「张三 请假」只返回同时匹配两个词的结果。
+
+支持键盘操作：
+
+| 按键 | 作用 |
+| --- | --- |
+| `↑` / `↓` | 在结果之间移动 |
+| `Enter` | 打开当前选中项 |
+| `Esc` | 关闭搜索 |
+
+更多快捷键见 [快捷键与搜索](/docs/shortcuts)。
+
+## 顶栏待办与消息
+
+顶栏右侧的**铃铛**汇总所有模块的待办和未读消息，点开后进入「待办与消息」页：
+
+- 待办来自各业务模块，处理完成后自动消失。
+- 消息是站内通知，点击即标记已读，支持「全部已读」。
+- 待办和消息都能深链到具体业务页面，不需要自己再找。
+
+详细说明见 [待办与消息](/docs/features/inbox)。
+
+## 顶栏外观入口
+
+顶栏右侧的**调色板**图标（或头像菜单里的「外观设置」）可以换皮肤、调字体大小，改完立即生效。三套皮肤（原版 / 简洁 / 炫酷）与四档字号只影响观感，不影响功能与权限；设置存在本机浏览器里，换设备不跟随。详见「功能模块 → 外观设置」。
+
+## 顶栏帮助入口
+
+顶栏右侧的「?」会打开独立的帮助文档站，新标签页展示，不会顶掉当前业务页面。文档站里有完整的操作说明、搜索和常见问题。
+
+## 功能开关与权限
+
+看不到某个模块时，按下面顺序排查：
+
+1. **角色权限**：管理员是否给你的角色勾选了该菜单。
+2. **功能开关**：该模块是否被管理员在系统配置中关闭。
+3. **直接地址**：部分模块关闭后不会出现在菜单里，直接输入地址也不应绕过权限设计。
+
+权限调整后通常需要重新登录才能生效，因为登录时会把权限集合写入会话。具体见 [角色与权限](/docs/guide/permissions)。

package/resources/content/docs/guide/permissions.md

@@ -0,0 +1,67 @@
+---
+title: 角色与权限
+description: 菜单权限、按钮权限与数据范围，以及看不到菜单时怎么排查。
+order: 3
+tags: [权限, 角色, 数据范围]
+updated: 2026-10-21
+---
+
+系统采用「用户 → 角色 → 权限」的 RBAC 模型，同时叠加一层「数据范围」控制能看见哪些行。
+
+## 三个概念
+
+| 概念 | 作用 |
+| --- | --- |
+| 用户 | 登录系统的账号，一个用户可以拥有多个角色 |
+| 角色 | 一组权限的集合，例如「系统管理员」「普通员工」 |
+| 权限 | 菜单访问权、按钮操作权，以及数据范围 |
+
+超级管理员是特殊账号，不受菜单权限限制，始终拥有全部数据和全部功能。
+
+## 菜单权限
+
+管理员在「系统管理 → 角色管理」里为角色勾选菜单。勾选后：
+
+- 该角色下的用户能在侧边栏看到并进入对应页面。
+- 父目录会自动出现；只勾选子菜单、不勾选父目录也能正常显示。
+- 取消勾选后，菜单、面包屑、全局搜索和收藏入口会一起消失。
+
+按钮级权限（新增、编辑、删除、重置密码等）与菜单权限一起配置。没有按钮权限时，页面上对应的按钮不会出现；即使绕过界面直接调用接口，服务端也会拒绝。
+
+## 数据范围
+
+菜单权限决定「能不能进这个页面」，数据范围决定「进去能看见哪些行」。系统提供四档：
+
+| 档位 | 可见范围 | 典型场景 |
+| --- | --- | --- |
+| 全部 | 所有部门的数据 | 系统管理员、全局统计岗 |
+| 本部门及下级 | 本人部门 + 全部下级部门 | 部门负责人 |
+| 本部门 | 仅本人所在部门 | 科室主管 |
+| 仅本人 | 仅自己创建或负责的数据 | 普通员工 |
+
+一个用户有多个角色时，数据范围取**最宽**的一档；超级管理员恒为「全部」。
+
+数据范围的过滤在服务端完成。全局搜索、列表、导出、统计和图谱都使用同一套规则，因此不会出现「列表看不到、搜索能搜到」的越权问题。
+
+## 功能开关
+
+部分模块有独立的功能开关，例如 AI 能力、知识图谱、文件中心、问题反馈和部门管理。开关关闭后：
+
+- 模块从侧边栏、面包屑、全局搜索和统计中一起移除。
+- 菜单管理里仍然保留配置，重新打开后自动恢复。
+- 开关不是权限，不能代替角色授权。
+
+## 看不到菜单时的排查步骤
+
+1. 确认当前登录的是自己的账号，而不是浏览器里残留的其它账号。
+2. 联系管理员检查角色是否勾选了对应菜单和按钮。
+3. 确认该模块的功能开关是否开启。
+4. 权限调整后退出并重新登录，让新权限进入会话。
+5. 仍然看不到时，把菜单名、账号和页面地址一起提交到问题反馈。
+
+## 安全约定
+
+- 所有写操作都会校验当前用户的权限和数据范围。
+- 删除、导入、重置密码等敏感操作会写入操作日志。
+- 导出文件同样受数据范围限制，不能通过导出拿到界面上看不到的数据。
+- 管理员清理日志、修改角色等操作也会被记录，避免权限被滥用后无从追溯。

package/resources/content/docs/guide/system.md

@@ -0,0 +1,92 @@
+---
+title: 组织、用户与菜单维护
+description: 管理员如何维护部门、账号、角色、菜单与操作日志。
+order: 5
+tags: [管理员, 组织, 用户, 菜单, 日志]
+updated: 2026-10-23
+---
+
+这一章面向管理员。普通用户只需要了解 [角色与权限](/docs/guide/permissions) 中「为什么看不到菜单」的部分。
+
+## 部门管理
+
+部门是一棵树，支持多级。维护时注意：
+
+- 部门编码必须唯一，建议使用简短的英文或数字编码。
+- 上级部门决定层级关系；调整上级部门会连带影响该部门及下级的数据范围。
+- 停用部门不会自动停用其下的账号，需要单独处理。
+- 删除部门前先确认没有用户和业务数据仍关联，否则会提示冲突。
+
+人员通常分配在**叶子部门**（没有下级的部门）。中间层部门主要用于汇总统计。
+
+## 用户管理
+
+用户列表支持按用户名、姓名、部门和状态筛选。
+
+常用操作：
+
+| 操作 | 说明 |
+| --- | --- |
+| 新增用户 | 设置用户名、姓名、初始密码、部门和角色；可同时设置密保问题 |
+| 编辑 | 修改姓名、联系方式、部门和角色；用户名通常不允许随意修改 |
+| 重置密码 | 生成临时密码，并要求用户下次登录时修改 |
+| 停用 / 启用 | 停用后无法登录，历史数据保留 |
+| 删除 | 逻辑删除，账号从列表消失，历史操作日志仍可追溯 |
+
+管理员无法查看用户密码明文，只能重置。密保答案同样只存哈希。
+
+### 注册开关（仅超级管理员）
+
+用户管理页顶部的「注册设置」控制访客能否自助注册：
+
+- **关闭（默认）**：登录页不显示注册入口，账号只能由管理员在用户管理里创建。
+- **开放**：登录页出现「注册账号」入口，任何人可自助开通账号；同一 IP 10 分钟内最多注册 5 个。
+
+自助注册的账号是「裸账号」：启用、无部门、无角色、非超管，需要管理员补配角色后才能使用功能。开关切换会记入操作日志；临时关闭注册不影响已注册账号的登录。
+
+## 角色管理
+
+一个角色由三部分组成：
+
+1. **菜单权限**：能进入哪些页面。
+2. **按钮权限**：在页面里能执行哪些动作。
+3. **数据范围**：能看见哪些部门、哪些人的数据。
+
+给角色授权时，建议按「最小可用」原则：只勾选完成工作必需的菜单和按钮，不要为了方便直接给全部权限。
+
+修改角色权限后，相关用户需要重新登录才会拿到新的权限集合。
+
+## 菜单管理
+
+菜单树同时承担三件事：侧边栏导航、全局搜索索引、角色授权清单。因此新增业务模块时，登记菜单是必须动作。
+
+一个菜单节点包含：
+
+| 字段 | 说明 |
+| --- | --- |
+| 名称 | 侧边栏与搜索结果里的显示名 |
+| 路径 | 页面地址，必须以 `/` 开头；目录可以为空 |
+| 类型 | 目录 / 菜单 / 按钮；按钮不出现在侧边栏 |
+| 权限码 | 用于服务端和前端按钮鉴权，建议按 `模块:资源:动作` 命名 |
+| 关键词 | 全局搜索别名，用户口头怎么叫就写什么 |
+| 排序 | 同级菜单从小到大的显示顺序 |
+| 隐藏 | 勾选后菜单不显示，但页面仍可通过地址访问 |
+| 徽标 | 绑定待办 / 未读计数源，在菜单右侧显示数字 |
+
+新增模块的正确顺序是：先建页面和接口，再登记菜单并授权，最后补充帮助文档。菜单登记后，侧边栏、面包屑、全局搜索和角色授权抽屉会自动出现，不需要再改其它代码。
+
+## 操作日志
+
+操作日志记录所有写操作，包括登录、增删改、导入导出、密码重置和权限调整。
+
+- 支持按模块、操作人、动作、时间范围和结果筛选。
+- 详情里保存操作摘要，例如修改前后变化、导入成功数量。
+- 日志主要用于审计和排障，不建议作为业务报表使用。
+- 清空日志是不可逆操作，只应在确认已备份后执行。
+
+## 维护建议
+
+- 定期检查长期未登录的账号，及时停用。
+- 角色数量保持精简，优先通过数据范围而不是复制角色来区分权限。
+- 菜单改名时同步更新关键词，否则用户用旧叫法会搜不到。
+- 新增或调整功能后，同步更新帮助文档对应页面。

package/resources/content/docs/quick-start.md

@@ -0,0 +1,70 @@
+---
+title: 快速开始
+description: 三分钟完成登录、认识界面分区，并走通一次完整的业务操作。
+order: 1
+tags: [入门, 登录, 界面]
+updated: 2026-10-21
+---
+
+第一次使用本系统，建议按下面的顺序走一遍。全部读完大约三分钟，之后就可以按菜单直接开始工作。
+
+## 第一步：登录系统
+
+打开系统地址后会进入登录页，使用管理员分配的账号和密码登录。
+
+- 首次登录后建议立即修改初始密码，见 [账号与登录](/docs/guide/account)。
+- 如果管理员重置过你的密码，系统会强制你先设置新密码，再进入后台。
+- 忘记密码时，可以在登录页走「忘记密码」流程，通过密保问题或账号申诉找回。
+
+登录成功后默认进入**工作台**。工作台展示当前业务最关心的统计指标和最近操作，方便一眼判断今天要处理什么。
+
+## 第二步：认识主界面
+
+后台主界面分为四个区域：
+
+| 区域 | 位置 | 主要用途 |
+| --- | --- | --- |
+| 侧边栏 | 左侧 | 按业务模块组织的功能入口，可折叠 |
+| 顶栏 | 顶部 | 全局搜索、帮助文档、当前账号与退出 |
+| 面包屑 | 顶栏左侧 | 显示当前位置，点击可回到上级 |
+| 内容区 | 中央 | 当前页面的列表、表单或看板 |
+
+侧边栏里的分组就是功能分类。看不到某个菜单时，通常是角色权限没有勾选，或该模块被管理员关闭了功能开关，可以联系管理员确认。
+
+## 第三步：找到你要用的功能
+
+有四种方式可以快速到达目标页面：
+
+1. **全局搜索**：按 `Ctrl K`（macOS 为 `⌘ K`），输入功能名或口头叫法，例如「请假」「员工」「日志」。功能结果在前，业务数据在后。
+2. **我的常用**：进入任意页面后，点顶栏的星标即可收藏；收藏会固定在侧边栏顶部。
+3. **待办与消息**：点顶栏铃铛，集中查看各模块的待处理事项和站内消息。
+4. **帮助文档**：点顶栏的「?」或侧边栏的「帮助文档」，进入文档站查看操作说明。
+
+更多搜索技巧见 [快捷键与搜索](/docs/shortcuts)。
+
+## 第四步：走通一次典型操作
+
+以带增删改查的列表页为例，一次完整的操作通常是：
+
+1. 在左侧菜单进入列表页。
+2. 用搜索框、筛选条件或分页找到目标数据。
+3. 点「新增」填写表单，或点行内「编辑」修改已有记录。
+4. 需要批量处理时，使用页面提供的导入 / 导出按钮。
+5. 删除前确认影响范围，删除动作会写入操作日志。
+
+所有新增、修改、删除都会记入**操作日志**，管理员可以在「系统管理 → 操作日志」里按模块、操作人或时间检索。
+
+## 第五步：遇到问题时
+
+- 先在本帮助中心搜索关键词，多数操作问题都能在 [使用指南](/docs/guide/navigation) 或 [常见问题](/docs/faq) 中找到答案。
+- 文档没有覆盖的问题，到「问题反馈」提交，附上页面路径和截图，管理员处理后会在反馈页回复。
+- 涉及账号锁定、权限缺失、数据异常这类需要管理员操作的问题，也可以在反馈中说明，处理会更集中。
+
+## 接下来读什么
+
+- [账号与登录](/docs/guide/account)：改密码、忘记密码、账号状态。
+- [界面与导航](/docs/guide/navigation)：菜单、收藏、搜索、徽标。
+- [待办与消息](/docs/features/inbox)：跨模块待办与站内通知。
+- [角色与权限](/docs/guide/permissions)：为什么有些菜单看不到。
+- [数据浏览、导入与导出](/docs/guide/data)：列表操作与 Excel 使用。
+- [常见问题](/docs/faq)：按现象快速定位。

package/resources/content/docs/shortcuts.md

@@ -0,0 +1,69 @@
+---
+title: 快捷键与搜索技巧
+description: 全局搜索、文档搜索与常用键盘操作。
+order: 80
+tags: [快捷键, 搜索, 效率]
+updated: 2026-10-21
+---
+
+## 全局快捷键
+
+| 快捷键 | 作用 | 适用范围 |
+| --- | --- | --- |
+| `Ctrl K` / `⌘ K` | 打开全局搜索（后台）或文档搜索（文档站） | 全站 |
+| `↑` / `↓` | 在搜索结果中移动 | 搜索弹窗 |
+| `Enter` | 打开当前选中结果 | 搜索弹窗 |
+| `Esc` | 关闭搜索或弹窗 | 全站 |
+| `Ctrl Shift K` | 清空当前输入框（部分浏览器） | 浏览器级 |
+
+> 搜索弹窗打开后输入框自动获得焦点，不需要再用鼠标点击。
+
+## 全局搜索技巧
+
+搜索同时覆盖「功能」和「数据」两层：
+
+1. **功能层**：菜单名、别名、路径。搜「请假」「休假」「考勤」都能命中同一个模块。
+2. **数据层**：当前权限范围内的业务记录，按标题、编号、姓名等字段匹配。
+
+提高命中率的方法：
+
+- 多个关键词用空格分隔，系统按全部命中处理。例如「张三 请假」。
+- 中文、英文和数字都可以混用。
+- 搜不到时换用更短的关键词，或改用列表页的筛选条件。
+- 目录也能搜到，结果会跳到该目录下的第一个页面。
+
+## 文档站快捷键
+
+| 快捷键 | 作用 |
+| --- | --- |
+| `Ctrl K` / `⌘ K` | 打开文档搜索 |
+| `↑` / `↓` | 在搜索结果中移动 |
+| `Enter` | 打开选中的文档 |
+| `Esc` | 关闭搜索 |
+
+阅读文档时：
+
+- 点击标题左侧的 `#` 可以复制该小节的锚点链接，直接分享给同事。
+- 代码块右上角的「复制」按钮可以复制整段代码。
+- 右侧目录会跟随滚动高亮当前小节。
+
+## 收藏
+
+- 页面右上角的星标用于收藏 / 取消收藏。
+- 收藏会出现在侧边栏顶部的「我的常用」，最多 8 个。
+- 收藏跟随页面地址和权限，不会绕过菜单授权。
+
+## 侧边栏
+
+| 操作 | 作用 |
+| --- | --- |
+| 点击顶栏左侧折叠按钮 | 收起 / 展开侧边栏 |
+| 悬停折叠后的图标 | 查看菜单名称 |
+| 点击分组标题 | 展开 / 收起分组 |
+| 查看菜单右侧数字 | 待处理或未读数量 |
+
+## 浏览器建议
+
+- 使用 Chrome、Edge 或 Firefox 的较新版本。
+- 不要使用 IE 兼容模式或老旧内核浏览器，部分表格和图表可能无法正常显示。
+- 在公共电脑上使用完毕后，点右上角头像 →「退出登录」。

package/resources/eslint.config.mjs

@@ -0,0 +1,17 @@
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { FlatCompat } from '@eslint/eslintrc';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const compat = new FlatCompat({ baseDirectory: __dirname });
+
+export default [
+  ...compat.extends('next/core-web-vitals', 'next/typescript'),
+  {
+    // next-env.d.ts 由 Next 每次构建时自动重写，里面的三斜线引用不归我们管。
+    // 不排除的话 `npm run lint` 会稳定报一条 triple-slash-reference 错误，
+    // 而这条错误谁都不该去"修"（改了下次构建又被覆盖）。
+    ignores: ['.next/**', 'node_modules/**', 'out/**', 'next-env.d.ts'],
+  },
+];

package/resources/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+/// <reference path="./.next/types/routes.d.ts" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/resources/next.config.ts

@@ -0,0 +1,13 @@
+import type { NextConfig } from 'next';
+
+const nextConfig: NextConfig = {
+  // 内网部署常用：允许局域网访问 dev server
+  // devIndicators: false,
+  eslint: { ignoreDuringBuilds: false },
+  typescript: { ignoreBuildErrors: false },
+  experimental: {
+    // 内网环境关闭遥测
+  },
+};
+
+export default nextConfig;

package/resources/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+
+export default config;

package/resources/prisma/org.config.ts

@@ -0,0 +1,98 @@
+/**
+ * 组织架构配置 —— 比赛时**只改这个文件**。
+ *
+ * ## 为什么单独抽出来
+ *
+ * 题目里的**部门由题意决定，一个字都不能编**；而人员姓名可以随便造。
+ * 以前部门写死在 seed.ts 里（HQ / 技术部 / 市场部 / 人力资源部），
+ * 一跑 seed 就把这 4 个题目外部门塞进「部门管理」，人员也全被分到这三个部门，
+ * 题目要的部门里一个人都没有 —— 评委点开就能看出是模板数据。
+ *
+ * 现在把「部门」和「人员」解耦：
+ *   - 部门树在本文件 ORG_TREE 里声明（唯一来源，改了重跑 seed 即生效）
+ *   - 人员数量由 PEOPLE_TOTAL 决定，seed 自动按**叶子部门**均衡铺满
+ *   - 人数不够时以「每部门保底 PEOPLE_MIN_PER_DEPT 人」为准自动扩容
+ *
+ * ## 两种工作流，二选一
+ *
+ * ### ① 配置驱动（默认，推荐）—— 部门写在下面
+ * 把 ORG_TREE 换成题目给的部门树，然后 `npm run db:reset`。
+ * code 是 upsert 主键，自己定，全库唯一、之后别改（业务表按它找部门）。
+ *
+ * ### ② 库里现有（ORG_SOURCE = 'existing'）—— 部门已在界面里录好
+ * 如果你已经在「系统管理 → 部门管理」把题目部门手工建完了，
+ * 把 ORG_SOURCE 改成 'existing'：seed **完全不碰部门表**，
+ * 只按库里现有的叶子部门铺人员。适合「先录组织、再补数据」的节奏。
+ *
+ * ## 注意
+ *
+ * - 改了部门树之后要 `npm run db:reset`（或先清空部门表）。
+ *   `db:seed` 只 upsert、不删旧数据，旧的 HQ/TECH/SALES/HR 会残留在库里。
+ * - 业务单据里的部门字段一律引用这里建出来的部门 id，不要再手写部门名。
+ */
+
+/* ============================ 1. 部门来源 ============================ */
+
+/**
+ * 'config'   —— 按 ORG_TREE 建部门（默认）
+ * 'existing' —— 不碰部门表，直接用库里已有的部门铺人员
+ */
+export const ORG_SOURCE: 'config' | 'existing' = 'config';
+
+/* ============================ 2. 部门树 ============================ */
+
+/** 部门树节点：code 全库唯一且稳定，children 递归嵌套 */
+export interface OrgNode {
+  /** 部门编码，upsert 主键。建议用拼音首字母或短英文，如 BGS / CWK / CGK */
+  code: string;
+  /** 部门名称，必须与题意完全一致 */
+  name: string;
+  children?: OrgNode[];
+}
+
+/**
+ * ★★ 比赛时改这里 ★★
+ *
+ * 下面是骨架自带的通用组织（4 个部门），只作开箱演示。
+ * 题目给了部门清单就整段替换掉，层级照题目写：
+ *
+ * ```ts
+ * export const ORG_TREE: OrgNode[] = [
+ *   {
+ *     code: 'ROOT', name: 'XX单位',
+ *     children: [
+ *       { code: 'BGS', name: '办公室' },
+ *       { code: 'CWK', name: '财务科' },
+ *       { code: 'CGK', name: '车管科' },
+ *       { code: 'HQK', name: '后勤保障科' },
+ *     ],
+ *   },
+ * ];
+ * ```
+ *
+ * 人员会被铺到**叶子部门**（没有下级的那些）。所以想让某个部门有人，
+ * 就把它写成叶子 —— 别只写在中间层。
+ */
+export const ORG_TREE: OrgNode[] = [
+  {
+    code: 'HQ',
+    name: '总公司',
+    children: [
+      { code: 'TECH', name: '技术部' },
+      { code: 'SALES', name: '市场部' },
+      { code: 'HR', name: '人力资源部' },
+    ],
+  },
+];
+
+/* ============================ 3. 人员规模 ============================ */
+
+/** 名册总人数（不含 admin / zhangsan）。调大重跑 seed 会补新账号。 */
+export const PEOPLE_TOTAL = 20;
+
+/**
+ * 每个叶子部门的保底人数。
+ * 实际人数 = max(PEOPLE_TOTAL, 叶子部门数 × 本值) —— 保证没有空部门。
+ * 设 1 表示「每个部门至少有 1 个人」，设 0 则完全按总数均分（可能有的部门没人）。
+ */
+export const PEOPLE_MIN_PER_DEPT = 2;