Go to file
mula.liu 9dd5aaed7c v 0.1.1 2026-10-22 18:05:10 +08:00
app v 0.1.1 2026-10-22 18:05:10 +08:00
docs v0.1.0 2026-10-20 10:53:43 +08:00
migrations v0.1.0-sp1 2026-10-21 10:28:25 +08:00
scripts v 0.1.1 2026-10-22 16:06:18 +08:00
tests v 0.1.1 2026-10-22 18:05:10 +08:00
web v 0.1.1 2026-10-22 18:05:10 +08:00
.dockerignore v0.1.0 2026-10-20 10:53:43 +08:00
.env.example v0.1.0 2026-10-20 10:53:43 +08:00
.gitignore v0.1.0 2026-10-20 10:53:43 +08:00
Dockerfile v0.1.0 2026-10-20 10:53:43 +08:00
README.md v 0.1.1 2026-10-22 16:06:18 +08:00
alembic.ini v0.1.0 2026-10-20 10:53:43 +08:00
docker-compose.yml v0.1.0 2026-10-20 10:53:43 +08:00
pyproject.toml v0.1.0 2026-10-20 10:53:43 +08:00

README.md

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,分组:auth org system employees|employee-* recruitment payroll benefits self dashboard common
  • 列表统一分页:?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 + Pydantic Literal 而非 MySQL ENUM。

演示数据规模(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)(Pydantic from_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 骨架屏 / H5 MPageFallback DotLoading)
  • 声明式资源:api/resources.ts 描述路径与权限,ResourceTable 自动完成列表/筛选/新增/编辑/删除/导入导出, 页面通常只需声明列与表单字段(defs.ts 的 col()/fld()/money()/STATUS_TAG)
  • 图标白名单:components/icons.tsx 显式登记后端下发的图标名(新增菜单图标需在此补一行), 避免 import * as icons 把整个图标库打进首屏 —— 图标 chunk 由 742 kB 降至 53 kB
  • 分包(vite.config.ts manualChunks):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/ 是需求参考系统,非本项目代码,不参与构建。