46 KiB
UNIS HRMS 2.0
新一代人力资源管理系统:人事档案 · 招聘 · 薪资 · 福利保险 · 员工自助(Web / H5) 配套完整 RBAC(权限码 + 数据范围 + 动态菜单),面向现代浏览器的简洁高交互界面。
浏览器 ── React 18 + TypeScript + Vite 6 ─┬─ 管理端 / (antd 5)
└─ 员工自助 /m (antd-mobile 5)
│ /api/v1 (JWT + Refresh)
FastAPI 0.115 ── SQLAlchemy 2.0 async ── Alembic ── SQLite(dev) → MySQL 8(prod)
| 层 | 选型 |
|---|---|
| 前端 | React 18 · TypeScript 5.7 · Vite 6 · React Router 6 · TanStack Query 5 · Zustand · antd 5 · antd-mobile 5 · Recharts · dnd-kit |
| 后端 | Python 3.12 · FastAPI · Pydantic v2 · SQLAlchemy 2.0(全异步)· JWT(PyJWT) · bcrypt · openpyxl |
| 数据 | SQLite(aiosqlite,开箱即用)→ MySQL 8(aiomysql,一条连接串切换)· Alembic 迁移 |
| 质量 | pytest + pytest-asyncio(161 项,含职级报销标准、资料审核与 Web⇄H5 一致性守卫 tests/test_self_parity.py)· ruff · tsc --noEmit 严格模式 |
1. 快速开始
一键启动(推荐)
./scripts/run.sh # 自动建 venv、装依赖、起后端 :8000 与前端 :5173
首次运行若 data/hrms.db 不存在,会自动建表并播种演示数据;
两个服务分别输出到当前终端,Ctrl-C 一起退出。SQLite 库与上传附件统一放在
项目根目录的 data/(data/hrms.db、data/uploads/)。
常用变体:
./scripts/run.sh --prod # 构建前端 → 后端 :8000 单端口提供整站
./scripts/run.sh --fresh # 删表重建 + 重新播种(重置演示数据后启动)
./scripts/run.sh --backend-only # 只起后端;--skip-install 跳过依赖检查
PORT=8010 WEB_PORT=5180 ./scripts/run.sh # 换端口;NO_OPEN=1 不自动开浏览器
scripts/dev.sh是run.sh的兼容别名;容器化部署用scripts/deploy.sh(见本节末尾)。
手动启动
# 后端(在项目根目录执行,不需要 cd)
python3.12 -m venv .venv
./.venv/bin/pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -e '.[dev]'
./.venv/bin/python -m app.seed --fresh # 建表 + 播种演示数据
./.venv/bin/python -m uvicorn app.main:app --reload --port 8000
# 前端(另开终端)
cd web
npm ci --cache /tmp/npm-cache-unis
npm run dev # http://localhost:5173
务必使用
.venv/bin/python(系统 python3 未安装 jwt/sqlalchemy 等依赖)。 配置与数据路径都以项目根目录为锚点(.env、data/hrms.db、data/uploads/), 所以在任何工作目录下用绝对路径的解释器启动,读到的都是同一份数据。
演示账号
| 账号 | 密码 | 角色 | 数据范围 | 说明 |
|---|---|---|---|---|
admin |
admin123 |
超级管理员 | 全部 | 绕过权限校验,可见所有菜单 |
hr |
hr123456 |
HR 负责人 | 全部 | 人事 / 招聘 / 福利全权 |
payroll |
pay123456 |
薪酬福利专员 | 全部 | 算薪、报盘、参保 |
recruiter |
rec123456 |
招聘经理 | 全部 | 职位、看板、Offer |
manager |
mgr123456 |
部门经理 | 部门及以下 | 部门内审批(王志强 / EMP00003) |
emp |
emp123456 |
普通员工 | 仅本人 | 桌面浏览器进 Web 自助 5 项导航,手机进 H5(王建国 / EMP00001) |
登录页内置这些账号(点击自动填充);登录后按浏览器自动进入 Web 工作台或 H5,
桌面普通员工进入 /dashboard,手机浏览器进入 /m,无需手动切换。
生产部署(Docker Compose)
镜像是两段式构建:node 阶段编译 web/dist,python 阶段运行 FastAPI 并直接托管前端产物,
因此一个容器、一个端口就是整站(/、/api/v1、/uploads 同源)。数据(SQLite + 附件)
挂在宿主机 ./data,换镜像不动数据。
./scripts/deploy.sh up # 首次部署:准备 .env → 构建镜像 → 后台启动 → 等健康检查
./scripts/deploy.sh status # 容器状态 + 健康探针 + 当前端口/数据库
./scripts/deploy.sh logs # 跟踪日志(Ctrl-C 退出)
./scripts/deploy.sh update # 改完代码重建镜像并替换容器(数据留在 ./data)
./scripts/deploy.sh migrate # 容器内 alembic upgrade head
./scripts/deploy.sh backup # SQLite 热备份到 data/backups/
./scripts/deploy.sh down # 停止并删除容器(数据仍在 ./data)
首次执行会把 .env.example 复制成 .env 并写入随机 SECRET_KEY,之后所有配置改 .env 即可
(HOST_PORT 换对外端口,SKIP_BUILD=1 ./scripts/deploy.sh up 复用现有镜像)。
想用 compose 自带的 MySQL(不用单独装库):
# .env 里改两行
# DATABASE_URL=mysql+aiomysql://hrms:hrms@mysql:3306/hrms?charset=utf8mb4
# PIP_EXTRAS=[mysql] # 镜像里要装 aiomysql / PyMySQL / cryptography
./scripts/deploy.sh mysql-up # 先等 MySQL healthy,再起应用
裸命令等价:docker compose up -d --build;构建参数(基础镜像、pip/npm 源)见 docker-compose.yml。
2. 目录结构
unis_hrms/
├── app/ # FastAPI 后端(目录名即 Python 包名)
│ ├── main.py # 应用装配、中间件、路由与静态资源注册
│ ├── seed.py # 播种入口:python -m app.seed [--force / --fresh]
│ ├── core/ # config security deps permissions pagination errors middleware constants
│ ├── db/ # engine / session / Base(命名约束、Money 类型)
│ ├── models/ # org rbac employee recruitment payroll benefits selfservice
│ ├── schemas/ # Pydantic v2 出入参
│ ├── api/v1/ # auth org system employee recruitment payroll benefits selfservice dashboard common
│ └── services/ # payroll_service(算薪内核)+ seed_* 播种
├── data/ # 统一数据目录:hrms.db · uploads/ · backups/ · openapi.json
├── migrations/ # Alembic 迁移(initial schema:46 张业务表)
├── tests/ # rbac / flows / lifecycle_e2e / role_matrix / api_surface / derived_fields
├── scripts/
│ ├── run.sh # 一键启动:dev / --prod / --fresh / --backend-only
│ ├── dev.sh # 兼容别名 → run.sh
│ ├── deploy.sh # docker-compose 部署:up / update / logs / migrate / backup …
│ └── export_sqlite.py # SQLite ⇄ JSON ⇄ MySQL 数据搬运(按外键拓扑排序)
├── docs/
│ └── MySQL迁移指南.md # 结构迁移 + 数据搬迁完整步骤
├── web/ # React 前端
│ ├── vite.config.ts # /api /uploads 代理 + manualChunks 分包
│ └── src/
│ ├── App.tsx # 路由(全部 lazy 懒加载)
│ ├── api/ # http.ts(axios 封装) resources.ts(资源声明式 CRUD) defs.ts(列/字段定义) routePerms.ts(403 权限码对照)
│ ├── components/ # ResourceTable(核心) FormDrawer(新增/编辑统一右侧抽屉) FieldInput Cell
│ │ # icons(图标白名单) PageFallback EmptyBlock ListFilters
│ ├── layouts/ # AdminLayout(动态菜单 + 固定侧栏/顶栏 + 用户胶囊) MobileLayout(H5 底栏)
│ ├── pages/ # 33 个管理端路由页面 + pages/self 6 个自助页 + pages/mobile 7 个 H5 页
│ ├── self/manifest.ts # 员工自助 7 模块唯一清单(两端名称/权限/顺序/图标/双端路径)
│ ├── lib/mode.ts # 外壳模式判定(Web / H5)唯一口径 + 偏好持久化
│ │ └── account/Settings.tsx # 个人设置(独立页面 /account,侧栏用户胶囊进入)
│ └── store/ # zustand:auth(token/me/menus/can)
├── Dockerfile # 两段式构建:node 产出 web/dist → python 运行整站
├── docker-compose.yml # 单容器整站 +(可选)mysql profile
├── pyproject.toml · alembic.ini · .env.example
└── README.md
3. 功能模块
3.1 人事档案 /employees
花名册(多条件筛选、导入导出、行内启停 Switch、按档案批量生成账号并选择角色,启停口径见 §9.3)· 360° 员工画像(教育/工作/家庭/证书/时间线)· 合同台账与到期预警 ·
异动与调薪审批 · 证明开具台账。合同状态 draft / active / renewed / expired / terminated
(renewed 表示已被续签合同接替,在职员工必有且只有一份 active 合同),续签提醒窗口统一为
90 天(app/core/constants.py: RENEW_WINDOW_DAYS,看板、合同列表、H5 首页同源)。
3.2 招聘 /recruitment
职位需求 · 候选人拖拽看板(dnd-kit,跨阶段拖拽即改状态)· 候选人库与简历 · 面试安排与多维评价 · Offer 审批与一键入职(生成员工 + 账号 + 合同)。漏斗/渠道/周期分析图表。
3.3 薪资 /payroll
薪资账套与账期 · 薪资项目(可配置公式项)· 员工薪资标准与调薪 · 一键算薪: 社保公积金个人/公司分摊 + 累计预扣法个税 + 当期假勤扣款 · 工资条明细与批量发放 · 银行报盘 Excel · 成本报表。
3.4 福利保险 /benefits
五险一金方案(基数上下限、比例)· 参保登记与增减员 · 福利项目与发放记录 · 假期类型 / 额度矩阵 / 请假审批(含额度校验与扣减)/ 假期分析。
3.5 员工自助(Web / H5)
3.5.1 用哪个外壳:设备决定,账号不决定
判定口径只有一处 —— web/src/lib/mode.ts,按优先级:
| 优先级 | 条件 | 结果 |
|---|---|---|
| 1 | 用户在站内显式切换过外壳(localStorage: unis-hrms-shell-mode) |
按所选:Web 工作台 / H5 自助端 |
| 2 | 从未切换过(默认) | 手机浏览器(UA + 触屏 + 视口,lib/device.ts)→ H5;其余(PC、平板桌面)→ Web |
配套规则(这是"员工一登录就被拽进 H5"的三个历史成因,现已封死):
- 账号与角色不参与判定。普通员工在电脑浏览器登录必进
/dashboard, 管理员用手机登录同样落到/m。 - 登录成功、根路径
/、token 过期重登三处统一走entryPath()/sanitizeRedirect(?redirect=), 后者会把历史遗留的/m/xxx改写成本外壳下的等价路径,不再原样把用户送回 H5。 - 两端都有显式切换入口并记住偏好:Web 侧栏顶部的 📱 按钮、自助首页的「用 H5 版打开」、
H5 首页与「我的」页的「💻 进入 Web 工作台」。登录页不再提供版本选择,默认就是跟随设备。
切换时落在同一模块(
oppositePath()),从 Web 的工资条切过去就是 H5 工资条,不会掉回首页。
3.5.2 两端怎么保持一致
唯一事实来源是 web/src/self/manifest.ts 的 7 个模块;后端 MOBILE_MENU_TREE /
SELF_WEB_MENU_TREE(app/core/permissions.py)与前端导航、通知 link(SELF_LINKS)
三方对齐,由 tests/test_self_parity.py(15 项静态守卫) 锁死:路径/权限/名称/顺序、以及「状态中文是否又各写了一套」漂移即红。
| 模块 | 权限码 | Web 路由 | H5 路由 | 侧栏 / 底栏 | 内容 |
|---|---|---|---|---|---|
| 首页 | selfservice:home:read |
/dashboard |
/m |
✅ / ✅ | 最新工资条、假期额度、宫格入口、合同提醒、待我审批、公告、待办 |
| 请假 | selfservice:leave:read |
/self/leave |
/m/leave |
✅ / ✅ | 类型/日期/时段 → 额度预估 → 提交,我的申请状态跟踪与撤销 |
| 工资 | selfservice:payslip:read |
/self/payslips |
/m/payslips |
✅ / ✅ | 年度/季度筛选、收入扣减个税明细、月度累计 |
| 福利 | selfservice:benefit:read |
/self/benefits |
/m/benefits |
✅ / ✅ | 五险一金参保、福利发放、假期额度矩阵 |
| 审批 | selfservice:approval:read |
/self/approvals |
/m/approvals |
✗ / ✗(两端均从首页宫格进入) | 待我审批 / 我的申请 + 类型筛选 + 意见填写,变更前后对照中文化 |
| 待办 | selfservice:task:read |
/self/tasks |
/m/tasks |
✗ / ✗(两端均从首页宫格进入) | HR 待办、消息通知、公告,标记已读/完成 |
| 我的 | selfservice:profile:read |
/self/profile |
/m/profile |
✅ / ✅ | 档案与教育/家庭、资料变更申请(走审批)、合同与薪资标准、证明开具、消息 |
一致性的实现层次:
| 层次 | 位置 | 作用 |
|---|---|---|
| 模块清单 | web/src/self/manifest.ts |
名称、说明、权限、顺序、emoji/配色/图标、双端路径、导航 placement |
| 外壳判定 | web/src/lib/mode.ts |
偏好持久化、entryPath、sanitizeRedirect、toWebPath/toMobilePath 互转 |
| 数据层 | web/src/api/self.ts |
13 个 /self/* 端点 + queryKey + 读写 hooks 两端共用;任一端提交后两端缓存一起失效 |
| 文案层 | web/src/lib/selfLabels.ts |
状态/类型/枚举的中文与配色(请假、工资条、审批、福利、证明、合同…)两端同源;在职/合同/参保状态直接派生自 api/defs 的选项表,金额与比例统一走 rmb() / pct(),避免 7.000000000000001% 这类浮点尾数 |
| 后端导航 | app/core/permissions.py 两份菜单树 |
按权限下发,/auth/menus?platform=web|mobile |
| 后端跳转 | app/core/permissions.py: SELF_LINKS |
通知与待办 link 一律用规范 H5 路径入库,前端渲染前过 toWebPath() |
因此两端读的是同一批接口、同一份缓存、同一套中文文案,只是外壳不同:
Web 用 antd 表格 / 抽屉 / 表头筛选,H5 用卡片 / 胶囊 tab / MChips。
历史上的 WebSelfFrame(把 H5 页面套进手机框显示在 Web 里)已删除 —— 那正是两端功能不一致的根源。
员工修改手机号、邮箱、住址等个人档案字段时统一生成待审申请,审核通过前不会写回档案;
旧版 PATCH /self/profile 也仅作为兼容入口生成审批单,不能绕过审核。
移动端为 390×844 起设计,antd-mobile 组件 + 自绘卡片体系,与桌面端共用一套 JWT 与 API。
3.6 组织与系统 /org /system
部门树(编制/在职对比)· 职位体系 · 职级职等(M/P/O 与薪档)· 字典 · 用户与角色授权 · 公告 · 操作日志。 每个职级可在行尾打开“报销标准”抽屉,维护多个报销项目(名称、金额、计量单位、说明), 员工在自助端“合同与薪资”中查看当前职级标准。
组织架构批量维护:部门 / 职位 / 职级三个页面都提供「导出 / 导入 / 下载模板」。
按编码(缺省时按名称)做 upsert,部门支持先写子部门再写上级,导入后统一重算 dep_path / level / is_parent;
模板与文件上传都走带 JWT 的 http 客户端(download() / upload()),不要再用 window.open 或裸 fetch,
否则浏览器不会带上 Authorization,登录态下也会 401。导入支持 .xlsx 与 UTF-8/GB18030 .csv。
系统管理 · 数据维护(/system/maintenance,超级管理员可见):
- 一键备份:下载 zip,含
manifest.json、全表database.json、SQLite 一致性快照database.sqlite与全部上传附件。 - 导出数据:导出多工作表 Excel,每张表一个 sheet,首表「说明」列出表名 / 中文名 / 记录数 / 清理时是否保留。
- 清理所有数据:需手动输入「unis_hrms」并二次确认;清空业务表、其它账号、附件与日志, 保留系统管理员账号、角色权限、菜单和数据字典,便于原地重新开账。
seed_menus 已改为按「平台 + 父级 + 路径 + 名称」逐条 upsert,老环境重跑 python -m app.seed
即可补上新增菜单,不会重复插入。
3.7 帮助中心 /help
顶部帮助按钮、用户菜单“使用手册”和 H5 我的页面均可打开带真实截图的 HTML 全功能手册;
静态文件位于 web/public/help/index.html,可直接访问 /help/index.html 或打印为 PDF。
3.8 员工全生命周期主线(入职 → 登记 → 发薪 → 调岗 → 离职)
这条主线把五个模块串成一条链,前后端共用同一套接口,tests/test_lifecycle_e2e.py 一条用例跑完全程。
转正 / 调岗 / 离职三个动作都有 direct 开关:direct=true 立即生效并留痕;默认 false 走审批,
在 /employees/changes 审批通过后才落到档案。
| # | 阶段 | 界面入口 | 接口 | 落库与跨模块联动 |
|---|---|---|---|---|
| ① | 招聘转入职 | 招聘 → Offer → 办理入职 | POST /recruitment/offers/{id}/onboard |
建员工 + 建登录账号 + 首份合同 + 起薪标准(adjust_type=hire 入职定薪),Offer 回写 employee_id |
| ② | 人事登记 | 花名册 → 编辑 / 360° 画像 | PATCH /employees/{id}、/employees/{id}/* |
学历、家庭、证书、合同续签;身份证按 GB 11643 校验 18 位,性别库内统一 male/female |
| ③ | 转正 | 员工详情 → 办理转正 | POST /employees/{id}/regular |
probation → active;regular_salary 写回薪资标准并留痕 adjust_type=regular |
| ④ | 参保登记 | 福利保险 → 参保登记 | POST /benefits/enrollments |
按方案基数/比例生成个人与单位应缴,作为算薪的社保口径 |
| ⑤ | 算薪发薪 | 薪资 → 新建批次 → 算薪向导 | POST /payroll/batches → /{id}/calculate → /{id}/approve → /{id}/publish |
一键算薪(社保公积金个人+单位、累计预扣法个税、当期假勤扣款)→ 审核 → 发布工资条 → /{id}/export 银行报盘 |
| ⑥ | 调岗 / 调部门 | 员工详情 → 办理调岗 | POST /employees/{id}/transfer |
写 hr_employee_change(transfer)并保存部门/职位/职级前后快照;生效后部门口径的薪资、参保、假期、报表自动跟随 |
| ⑦ | 离职 | 员工详情 → 办理离职 | POST /employees/{id}/resign |
active → leaving → resigned,终止合同、停保、账号可停用;services/purge_employee_records() 支持彻底清档 |
配套的三类审批同一套交互(列表筛选 → 通过/驳回 → 意见留痕):
人事异动 /employee-changes/{id}/approve、调薪 /salary-adjustments/{id}/approve、
证明开具 /employee-documents/{id}/approve;部门经理与普通员工在 H5 /m/approvals 用同一接口审批。
4. RBAC 设计
用户 → 角色 → 权限码 + 数据范围,菜单由后端按权限下发(前端不做硬编码菜单)。
- 权限码:
module:resource:action,共 170 个(app/core/permissions.py是唯一事实来源, 播种进sys_permission)。action ∈read / create / update / delete / import / export及业务动作(approve、calculate、pay…)。 - 数据范围:
all > dept_tree > dept > self,取用户所有角色的最大范围(core/deps.py: SCOPE_RANK); 列表查询通过apply_employee_scope()自动注入可见员工集合。 - 后端:
Depends(require_perm("payroll:batch:pay"))逐接口校验,越权返回403 {"code":"forbidden","message":"…(需要 xxx)"};超级管理员短路放行。 - 前端:
useAuth().can(code)控制按钮/操作可见性;/auth/menus?platform=web|mobile决定侧边栏与 H5 底栏; 直接敲 URL 命中没有菜单权限的页面时渲染 403 页,并把缺少的权限码用等宽 Tag 标出来 (web/src/api/routePerms.ts维护「页面 URL → 所需:read权限码」对照表, 事实来源是services/seed_rbac.py的菜单定义;子路由如/employees/:id前缀继承父页面)。 - 7 个内置角色:超级管理员 / HR 负责人 / 人事专员 / 招聘经理 / 薪酬福利专员 / 部门经理 / 普通员工,
在
/system/roles用权限树可视化调整并另存新角色。权限树模块与资源的顺序跟随主界面菜单 (permissions.py: menu_catalogue_order()从菜单树反解而来,不是另抄一份常量), 工具条上的「全部收拢 / 全部展开」用于按模块整块勾选;超级管理员固定全权限,面板只读。 - RBAC 基线随启动自动同步(升级发版不再需要手工播种):
services/seed_rbac.py: sync_rbac()按permissions.py幂等补齐sys_permission/sys_menu/ 内置角色,并把超级管理员角色补齐到 全部权限点(新增功能无需手工授权)。app/main.py在AUTO_SEED=false时也会调用它, 因此只要重启一次服务,新菜单与新权限点就落库;只想同步 RBAC、不动业务数据时用./.venv/bin/python -m app.seed --rbac(Docker:./scripts/deploy.sh seed --rbac)。 演示数据仍走python -m app.seed [--force|--fresh]。
4.1 角色 × 模块能力矩阵(当前播种结果)
权限码共 170 个:payroll 30 · employee 26 · recruitment 27 · benefits 27 · system 27 · org 18 · selfservice 15。
| 角色(演示账号) | 数据范围 | 人事档案 | 招聘 | 薪资 | 福利保险 | 员工自助 | 组织 | 系统 | 可见 Web 页面 |
|---|---|---|---|---|---|---|---|---|---|
超级管理员 admin |
all | 读写+审批 | 读写+审批 | 读写+算薪 | 读写+发放 | 读写+审批 | 读写 | 读写 | 30 页(全部) |
HR 负责人 hr |
all | 读写+审批 | 读写+审批 | 读写+算薪 | 读写+发放 | 读写+审批 | 只读 | 读写 | 27 页 / 7 个一级菜单 |
人事专员 hr_specialist |
dept_tree | 读写+审批 | 读写 | — | 读写+审批 | 读写+审批 | 只读 | 读写 | 部门内可见 |
招聘经理 recruiter |
dept_tree | 只读 | 读写+审批 | — | 只读 | 读写+审批 | 只读 | — | 12 页 / 5 个一级菜单 |
薪酬福利专员 payroll |
all | 读写+审批 | — | 读写+算薪 | 读写+发放 | 读写+审批 | 只读 | — | 16 页 / 5 个一级菜单 |
部门经理 manager |
dept_tree | 只读 | 只读 | 只读 | 只读 | 读写+审批 | 只读 | — | 12 页 / 6 个一级菜单 |
普通员工 emp00001 |
self | — | — | — | — | 读写 | — | — | 自助 5 项(首页/请假/工资/福利/我的) |
- 所有角色的 Web 侧栏与 H5 底栏完全同名同序(首页 / 请假 / 工资 / 福利 / 我的), 且能看什么由接口权限决定:例如部门经理在审批页看到待办与审批按钮,普通员工只看到自己的申请进度。
- 表里的「只读」= 有
read无create/update,前端自动隐藏新增/编辑/删除按钮,接口同样 403。
4.2 自定义端点的数据范围红线
通用 CRUD 由 ResourceSpec 统一注入数据范围,但手写的业务端点必须显式收口,否则等于绕开 RBAC:
from app.core.deps import apply_employee_scope, ensure_employee_scope, scope_department_ids
# 1) 有员工归属的表:列表用 apply_employee_scope(session, stmt, auth, Employee.department_id)
# 2) 单条读写用 ensure_employee_scope(...),越权直接 403,不要只靠前端隐藏按钮
# 3) 没有员工归属的记录(Offer、职位需求…)按部门集合过滤:
dept_ids = await scope_department_ids(session, auth) # None = 全部
# 4) 同一个页面的「列表」和「计数/角标」必须同口径,否则审批中心会出现“计数有、列表空”
tests/test_role_matrix.py 会遍历写端点断言 403、并专门回归「审批中心按可见范围过滤 Offer」这类泄漏场景。
5. API 概览
- 交互文档:http://127.0.0.1:8000/docs(OpenAPI:208 个路径 / 322 个操作)
- 前缀
/api/v1,分组:authorgsystememployees|employee-*recruitmentpayrollbenefitsselfdashboardcommon - 列表统一分页:
?page=1&page_size=20&keyword=&…→{items,total,page,page_size,pages} - 错误统一:
{code,message,detail?};401触发前端用refresh_token静默换发并重放请求,失败则登出 - 鉴权:
Authorization: Bearer <access_token>(默认 120 分钟),/auth/refresh滚动续期,sys_refresh_token可撤销 - 附件/导出:
/common/attachments(上传)、download()读取content-disposition(Excel 报盘、名册导出) - 员工自助以
/self开头,一律以 JWT 中的 employee 为身份边界,不接受外部传入的 employee_id
# 快速自检
curl -s localhost:8000/api/v1/auth/login -H 'Content-Type: application/json' \
-d '{"username":"hr","password":"hr123456"}' | head -c 200
6. 数据库与 MySQL 迁移
- 47 张表(46 张业务表 +
alembic_version);前缀sys_ / org_ / hr_ / rec_ / sal_ / ben_ / self_ - 开发期
AUTO_CREATE_SCHEMA=true时除create_all外还会跑db/schema.py: sync_schema(), 给已存在的表自动补可空列(SQLite 无法改类型,只补不删),改了模型不必手动--fresh; 生产关掉该开关,一切以 Alembic 迁移为准 - SQLite 开箱可用;迁移 MySQL 的完整步骤见 docs/MySQL迁移指南.md,要点:
# 1) 结构:Alembic(命名约束/InnoDB+utf8mb4 已在 Base 里处理)
./.venv/bin/pip install -e ".[mysql]" # aiomysql + PyMySQL + cryptography
DATABASE_URL="mysql+pymysql://hrms:pwd@127.0.0.1:3306/hrms?charset=utf8mb4" \
./.venv/bin/alembic upgrade head
# 2) 数据:JSON 中转,按外键拓扑排序,无需关心父子表
./.venv/bin/python scripts/export_sqlite.py --out data/sqlite_dump.json
./.venv/bin/python scripts/export_sqlite.py --in data/sqlite_dump.json
- 新增模型后生成迁移:
./.venv/bin/alembic revision --autogenerate -m "add xxx" - 已规避 MySQL 常见坑:约束命名规范、
Money=DECIMAL(14,2)、JSON/BOOLEAN通用类型、 枚举用VARCHAR+ PydanticLiteral而非 MySQLENUM。
演示数据规模(app/seed.py 固定随机种子,可复现)
76 名员工 / 114 份合同(含续签链路,在职者必有生效合同)· 28 候选人 + 28 应聘 + 面试/Offer · 2 个算薪批次 / 140 张工资条 · 65 条参保 · 84 条请假 · 14 条异动 · 6 条资料变更 · 10 份证明 · 6 条公告
./.venv/bin/python -m app.seed # 幂等:已播种则跳过
./.venv/bin/python -m app.seed --force # 强制补齐缺失数据
./.venv/bin/python -m app.seed --fresh # 删表重建 + 重新播种(重置演示环境)
7. 测试与质量
./.venv/bin/ruff check app tests migrations scripts # All checks passed!
./.venv/bin/python -m pytest -q # 158 passed
cd web && npx tsc --noEmit # 严格模式无输出
cd web && npm run build # tsc --noEmit && vite build
tests/test_rbac.py:角色权限集、数据范围边界、越权 403、菜单可见性tests/test_flows.py:招聘→入职→合同→异动→算薪→发放、请假额度扣减、自助审批闭环、合同续签一致性tests/test_lifecycle_e2e.py:员工全生命周期一条链跑到底 —— Offer 入职 → 档案登记 → 转正 → 参保 → 建批次算薪 → 发布工资条 → 调部门(含审批生效)→ 离职,逐步断言跨模块数据一致tests/test_role_matrix.py:7 个角色的能力矩阵、写端点越权 403 扫描、审批中心可见范围(含 Offer 薪资泄漏回归)tests/test_api_surface.py:全量路由可达性与响应契约tests/test_expense_standards.py:职级多项目报销标准、重复校验与权限边界tests/test_org_io.py:部门/职位/职级模板、导入、导出与权限边界(含 CSV 与人事档案模板 401 回归)tests/test_maintenance.py:数据概况、备份 zip、全量导出与「仅保留系统管理员」的清理逻辑tests/test_derived_fields.py:after_read派生字段回归(用户角色 / 角色计数 / 招聘负责人 / 司龄), 防止「保存即清空角色」这类静默失效再次发生- 测试使用独立库
data/test_hrms-<pid>.db(库名带 PID,跑完自动清理),既不污染开发数据, 也不会因为「两个终端 / CI / 编码代理同时跑 pytest」互相删表而报table sys_role already exists或disk I/O error——这类报错其实是被并发测试打断,不是代码问题
后端约定:通用 CRUD 用
spec.read.model_validate(obj)(Pydanticfrom_attributes)序列化, 因此after_read钩子必须把派生值写到与 schema 字段同名的公开属性上 (row.__dict__["roles"] = ...,写"_roles"会让接口静默返回null)。
8. 配置项(根目录 .env,参考 .env.example)
| 变量 | 默认 | 说明 |
|---|---|---|
SECRET_KEY |
change-me-in-production |
JWT 签名密钥,生产必须替换(建议 ≥32 字节) |
DATABASE_URL |
sqlite+aiosqlite:///./data/hrms.db |
换 MySQL 即完成数据层切换(相对路径按项目根目录解析) |
UPLOAD_DIR |
./data/uploads |
附件目录,同样锚定到项目根目录 |
AUTO_CREATE_SCHEMA |
true |
启动时 create_all(生产建议关掉,交给 Alembic) |
AUTO_SEED |
false |
启动时自动播种 |
ACCESS_TOKEN_MINUTES |
120 |
访问令牌有效期 |
MAX_UPLOAD_MB |
20 |
附件上限 |
CORS_ORIGINS |
["http://localhost:5173",…] |
前端来源白名单 |
SERVE_WEB_DIST |
true |
后端直接托管 web/dist(单端口整站);没有构建产物时自动跳过 |
PORT / HOST_PORT |
8000 |
不是后端配置:分别是 run.sh 监听端口与 compose 对外端口 |
9. 前端工程要点
- 全路由懒加载 +
Suspense(桌面PageFallback骨架屏 / H5MPageFallbackDotLoading) - 声明式资源:
api/resources.ts描述路径与权限,ResourceTable自动完成列表/筛选/新增/编辑/删除/导入导出, 页面通常只需声明列与表单字段(defs.ts的col()/fld()/money()/STATUS_TAG) - 图标白名单:
components/icons.tsx显式登记后端下发的图标名(新增菜单图标需在此补一行), 避免import * as icons把整个图标库打进首屏 —— 图标 chunk 由 742 kB 降至 53 kB - 分包(
vite.config.tsmanualChunks):antd 1.44 MB、charts 438 kB、data 101 kB、antd-mobile 100 kB、ResourceTable 63 kB、icons 53 kB、dnd 43 kB、页面 chunk 3–16 kB - 401 自动刷新重放、全局错误 toast、金额/日期/状态标签统一格式化
- 后台请求静默化:轮询类请求用
getQuiet()(或命中SILENT_URLS/SILENT_CODES)失败时不弹全局提示, 由调用方兜底数据或MProblem空状态解释(管理员账号无员工档案时不再被 403 刷屏) - 后台外壳三段式(
AdminLayout):.admin-shell高度锁100vh且整页不滚,侧栏 = 品牌行(右侧折叠按钮).sider-scroll(菜单自己滚)+.sider-user(用户胶囊常驻底部),主区 = 固定.admin-header+ 内滚.admin-content。 收拢状态写localStorage['unis-hrms-sider-collapsed'],只在断点跨越时联动(窄屏强制收拢、宽屏恢复偏好), 否则刷新会把用户偏好冲掉
- 收拢态不留折叠按钮:72px 宽的侧栏只放系统 logo,
.brand-fold平时opacity:0; pointer-events:none, hover 品牌行时才浮现(叠在 logo 正中,logo 同步淡到 2 成)—— 纯 CSS:hover,不用 JS 记鼠标位置 - 用户胶囊(侧栏底部,不放顶栏,高 51px):34px 圆角方块头像(
borderRadius:10)+ 上行姓名(14px 粗)- 下行角色(12px 灰,多角色用「、」连接;姓名与角色同名时下行退化成登录账号),右侧箭头; 两行各自单行省略,绝不被长姓名/多角色撑高。收拢态只剩头像(胶囊 51×44);点击向上弹出「个人设置 / 退出登录」
- 胶囊二级菜单跟随侧栏宽窄:展开态是「图标 + 文字」(203×72),收拢态同样简化成纯图标条
(52×64,
.user-menu-pop.icon-only隐藏.ant-dropdown-menu-title-content并居中,placement改topRight), 图标项带原生title补提示 —— 收拢侧栏里出现一整条带文字的菜单会显得很突兀 - 弹层图标尺寸 = 主菜单图标尺寸:antd 把
.ant-dropdown-menu-item-icon写死成fontSizeSM(10px), 比主菜单图标(继承全局fontSize,13px)小一圈,胶囊二级菜单和左侧菜单并排就不齐。styles/global.css用.ant-dropdown.ant-dropdown .ant-dropdown-menu .ant-dropdown-menu-item-icon统一到 13px(双写 class 把特异性抬到 4 个,压过 antd 运行时注入的样式,不靠先后顺序); 收拢态 antd 会把主菜单图标放大到fontSizeLG(14px),所以.user-menu-pop.icon-only单独跟到 14px - 个人设置是独立页面(
pages/account/Settings.tsx,路由/account),不是弹窗/抽屉: 顶部身份卡(头像 + 姓名 + 角色 + 登录账号),左「账户资料」改姓名/手机号/邮箱走PUT /auth/profile(只提交 diff 字段,成功后reload()让侧栏胶囊姓名同步),右「修改密码」走POST /auth/change-password(后端吊销全部 refresh_token,前端当场登出重登),右下「账号与权限」只读展示角色/数据范围/关联员工/最近登录。 角色与菜单权限一律只读,归管理员在「系统管理 → 用户」维护。 它不在后端菜单里:AdminLayout的KNOWN_PREFIXES刻意不登记/account(人人可改自己,无需权限码), 面包屑靠OFF_MENU_TITLES兜底标题,胶囊在/account上加.user-chip.on选中态 - 表单抽屉(
components/FormDrawer.tsx):新增 / 编辑 / 办理一类的表单一律右侧滑出,不再用居中 Modal。title + desc固定在 header、取消 / 保存固定在 footer(onSubmit \|\| footerExtra才渲染), 字段多时只有.ant-drawer-body内部滚动(overscroll-behavior:contain),按钮永不被顶出视口; 默认宽 560,字段 > 6 个由调用方给width={780},wrapper限maxWidth:94vw适配窄屏。ResourceTable已内置该容器,所以声明式资源表的新增/编辑自动是抽屉; 自定义表单页(假期、部门、面试、Offer、批次、用户、员工档案…)逐个换成<FormDrawer>。 删除等确认框仍走居中的modal.confirm,H5(pages/mobile/*,antd-mobile)不受影响。
9.1 UI / 交互一致性约定(新增页面照此办理)
界面统一是硬要求,全站按同一套约定实现,评审时逐条对照:
| 主题 | 约定 |
|---|---|
| 枚举中文 | 唯一来源 api/defs.ts 的 *_OPTIONS,同一字段的「列 + 筛选 + 表单」共用一份;Cell 兜底 flowLabel()。active / probation / expired / terminated 属多义值,必须用字段自带 options,不能进全局映射 |
| 码值存储 | 库里只存英文码(gender、adjust_type、change_type、status…),中文只出现在 label 层与 Excel 导出;导入时 gender_code() 一类的归一函数保证「中文/英文」双向可入库 |
| 结构化字段 | type:'json' 走 JsonCell:解析后渲染成「字段名 值」小两列(最多 4 项 + 等 N 项,Tooltip 全量),禁止 JSON.stringify 直出或 [object Object] |
| 状态色 | 一律 STATUS_HEX / statusHex / STATUS_TAG / tagColorOf,同语义同色,不在页面里手搓颜色 |
| 数字与金额 | 年份用 type:'year'(number 会被千分位写成 2,026);金额统一 money()/yuan() |
| 表格尺寸 | 主列表 middle,卡片内嵌小表 small;空态统一 EmptyBlock,分页文案统一「共 N 条」 |
| 表单抽屉 | 新增/编辑一律 components/FormDrawer.tsx(右侧滑出 + body 内滚 + footer 固定),不要再引入 Modal;打开时用 hooks/useModalForm.ts: useModalFormFill() 填值(抽屉同样是懒挂载,直接在 onClick 里 setFieldsValue 会命中未挂载的 Form),组件内部已带 destroyOnHidden,不要写已废弃的 destroyOnClose |
| 表单控件 | FieldInput 按 FieldDef.type 统一渲染;日期在提交前统一转 YYYY-MM-DD;direct 一律表示「直接生效,不走审批」 |
| 反馈 | 成功用 message.success 并说明结果,删除等破坏性动作用 modal.confirm(确认框保持居中,不做抽屉)复述对象名;接口错误由拦截器统一 toast,页面不再叠加 |
| H5 | 外壳 .m-app / .m-tabbar,宽屏下内容 560px 居中;文案与状态色与 Web 端同源(同一份 *_OPTIONS) |
| 启停开关 | 列表里的「启用」列一律用 components/StatusSwitch.tsx(type:'toggle' 由 Cell 渲染),点一下直接 PATCH {is_active},只在停用方向二次确认;列位置见 §9.3 |
| 操作列 | 顺序固定 自定义行操作 → 编辑 → 删除 → ⋮更多(整块 fixed:'right',是列表里唯一固定的列)。「更多」是 MoreOutlined 竖三点图标按钮(不带文字),永远是操作列最后一项,由 ResourceTable 的 rowMore / onRowMore 提供,低频动作(生成账号等)一律收进去,不在操作列堆按钮 |
| 图标 | 只用 components/icons.tsx 白名单,新增菜单图标在那里补一行 |
| 账户入口 | 统一在侧栏底部用户胶囊(AdminLayout 的 .sider-user,圆角方块头像 + 上行姓名 + 下行角色),顶栏不放头像;改资料/改密码只有 /account(pages/account/Settings.tsx)这一处,新页面不要再自建「修改密码」入口,也不要再用弹窗装个人设置 |
9.2 列表筛选与排序规范(所有列表页统一)
一句话:关键字 + 部门树按钮 + 放大镜 三段合一个搜索框;其余可筛字段一律做在表头;排序只放开「工号」列。
| 环节 | 规范 |
|---|---|
| 综合搜索框 | ListFilters.tsx: SearchBar 全站唯一实现,渲染顺序固定为 关键字 ⊗ | 部门 ▾ 🔍。分隔线 |、部门胶囊、放大镜全部塞进 Input.suffix(.ls-actions),不换行、不成第二行控件 |
| 部门筛选 | ListFilters.tsx: DeptFilterButton,在搜索框内放大镜之前的内联胶囊:未选 🏢 部门 ▾,已选 🏢 部门 · N ▾(实心主色)。弹层 = 搜索框 + checkable Tree(checkStrictly,多选)+ 含下级 开关 + 清空 / 确定。部门不生成 chip(由胶囊自身表达),清空走弹层「清空」或右侧「重置」 |
| 表头筛选 | 可筛字段声明在 ResourceDef.filters,由 HeaderFilter 挂到对应列头(filterDropdown + 自绘 filterIcon),不再单独成行。选项优先级:内联 options > dict:'字典码' / field.dict > source 远程 > type:'year' > 布尔开关;超过 8 项自动带搜索框;日期走 dateRange 分支 |
| 已选摘要 | def.filters 生成的值渲染成搜索框外的 FilterChip,逐个可删,末尾「重置」清空全部;部门不占 chip |
| 排序 | 只有「工号」列可排序。defs.ts: col() 默认 sortable: name === 'work_no'(写在 ...opts 之前,故可按列覆盖);ResourceTable 仅在 c.sortable === true 时挂 sorter。业务列(姓名/部门/日期/金额…)不提供排序,需要时给该列显式 sortable: true |
| URL 深链 | hooks/useListFilters.ts 以 URL 为唯一状态源,可直接分享/刷新/前进后退:?keyword=张&status=a,b&hire_date_start=2024-01-01&hire_date_end=2024-12-31&department_id=3,7&dept_subtree=1(dateRange 拆成 <字段>_start/_end,多值逗号分隔) |
| 自定义表格 | 不走 ResourceDef 的表(看板、面板内嵌表)用 usePanelFilters({ dept?, filters? }) 复用同一份 URL 状态与同一套 SearchBar,不要自造筛选行 |
| 后端配套 | 列表端点统一接收 keyword、department_id + dept_subtree(api/helpers.py: dept_filter_ids() 负责展开下级)、以及各筛选字段的多值参数;新页面加 filters 时同步确认端点已支持,否则表头能选但结果不变 |
| H5 | 手机上没有表头,改用 pages/mobile/_ui.tsx 的 MChips(首项固定「全部」,可带条数,options.length <= 1 时自动不渲染)+ MSearch(关键字 + ⊗)。合计、笔数、角标必须随筛选重算(如工资条按季度重算年度累计、请假额度 chip 上的余量) |
| 豁免 | 员工 360° 详情的四张子表(certificate / education / family / workhistory)、/system/roles(左角色右权限的 master-detail)、/payroll/reports(报表图表页)、页面内的统计卡(如「部门请假排行」)不做筛选栏;统计卡排序在前端排完即可,不占用列排序 |
红线(本轮踩过):loading / error 早退必须写在 useState / useMemo / useMutation 之后。
形如 if (q.isFetching) return <MLoading /> 之后再声明 hook,切换 tab 时会抛
Rendered more hooks than during the previous render 并整页白屏 —— 数据未命中缓存时必现,命中缓存时偶发,务必先想清楚再摆位置。
9.3 业务启停:全站只有 is_active 一个开关
一句话:is_active 是唯一的业务启停位,status 只表达在职生命周期,两者不重复、不互写。
| 层 | 口径 |
|---|---|
| 数据模型 | 员工/部门/职位/职级/账套/薪资项目/参保方案/福利项目/假期类型/用户/角色/字典项都用 is_active;不再新增 status 之类的第二套启停字段。员工 status 只表示 probation / active / leave / leaving / resigned |
| 列表 UI | 「启用」列渲染成内联 Switch,恒为倒数第二列:ResourceTable 自动把它挪到所有数据列之后并 fixed:'right',紧贴操作列左边;数据列一律不做左侧 fixed(开关若排在中间会被右侧固定的操作列盖住,一点就落到「删除」上,就是这么踩出来的) |
| 停用档案 | services/lifecycle.py: set_account_state() 联动:非超管账号一并停用并清除 RefreshToken(立刻 401),启用时只恢复带 档案停用,账号停用 标记的账号,不会把 HR 手动停用的账号偷偷放回来 |
| 重新启用 | api/v1/employee.py 用 employee_before 记录的「显式启停意图」在离职联动 close_resignation() 之后重新赋值,避免「停用后点启用返回 200 但状态不变」 |
| 业务过滤 | 参与计算的入口必须带 Employee.is_active.is_(True):算薪取人(payroll_service.employees_for_scope)、福利批量发放、假期额度批量生成、档案批量生成账号;统计与历史台账刻意不过滤,停用的人历史数据仍要能查到 |
| 下拉选择 | /common/options 返回 extra.is_active,停用项仍解析得出名称(历史单据不显示裸 ID),但前端置灰不可再选中 |
10. 常见问题
| 现象 | 处理 |
|---|---|
ModuleNotFoundError: jwt / sqlalchemy |
用了系统 python,改用 .venv/bin/python |
| 前端提示「网络连接失败」 | 后端未启动或端口不是 8000(vite 代理 /api、/uploads → 127.0.0.1:8000) |
| 播种报“已播种”跳过 | 用 --force;想彻底重置用 --fresh |
| 页面空白但接口 200 | 该账号无此权限码,后端返回空集合;用 admin 复核是否为权限配置问题 |
| 菜单图标显示成默认方块 | 图标名不在 icons.tsx 白名单,补一行即可(须是 @ant-design/icons 真实存在的名字) |
| MySQL 连接报 cryptography | pip install -e ".[mysql]"(MySQL 8 的 caching_sha2_password 需要它) |
| 列表里状态/类型显示英文码 | 该字段 type:'tag' 没挂 options,去 defs.ts 复用现成的 *_OPTIONS(列与筛选共用一份) |
年度显示成 2,026 |
列用了 type:'number',改成 type:'year' |
| 列表里的启停开关点下去却弹出「删除确认」 | 开关列被右侧固定的操作列盖住了:数据列不要写 fixed:'left',「启用」列放最后(见 §9.3),ResourceTable 已按此规则重排列序 |
切换 Tab / 首次进入某页整页白屏,控制台报 Rendered more hooks than during the previous render |
loading / error 的早退写在了 useState / useMemo 之前,违反 Hooks 规则;把 hook 全部上移到早退之前(见 §9.2 红线) |
抽屉首次打开控制台报 useForm … not connected |
在 onClick 里直接 setFieldsValue,改用 useModalFormFill()(见 §9.1) |
| 升级后新菜单看不见 / 授权页搜不到新权限码 / 一直 403 | sys_permission、sys_menu 里还没有这几行:重启服务(启动钩子会跑 sync_rbac()),或直接 ./.venv/bin/python -m app.seed --rbac(只同步 RBAC,不动业务数据) |
启动脚本报 unbound variable(变量名带乱码) |
macOS 自带 bash 3.2 在 UTF-8 下会把紧跟变量的全角字符吞进变量名;脚本内已统一写成 ${VAR}),新增中文提示时记得给变量加花括号 |
| 普通员工登录总进 H5 | 外壳由设备 + 站内显式偏好决定,与账号无关:桌面浏览器应落 /dashboard;若曾被 H5 记住偏好,用侧栏 📱 按钮或 H5 的「💻 想用大屏版」卡切回(见 §3.5.1);也可在浏览器控制台执行 localStorage.removeItem('unis-hrms-shell-mode') 恢复跟随设备 |
| Web 自助与 H5 模块对不上 | 三处事实来源必须同步:web/src/self/manifest.ts、permissions.py 两份菜单树、SELF_LINKS;跑 pytest tests/test_self_parity.py 定位漂移项 |
| 新增一个自助模块 | 只在 manifest.ts 加一条(含双端路径与 placement)+ 两份菜单树各一行 + App.tsx 两条路由,两端自动同名同序同权限 |
| 新增页面后 403 页没提示权限码 | 去 web/src/api/routePerms.ts 补一行 URL→权限码(仅影响提示文案,不影响放行判断) |
vhr2.0-main/是需求参考系统,非本项目代码,不参与构建。