diff --git a/README.md b/README.md index f6db9c1..3c43a9a 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # UNIS HRMS 2.0 -新一代人力资源管理系统:**人事档案 · 招聘 · 薪资 · 福利保险 · 员工自助(H5)** +新一代人力资源管理系统:**人事档案 · 招聘 · 薪资 · 福利保险 · 员工自助(Web / H5)** 配套完整 RBAC(权限码 + 数据范围 + 动态菜单),面向现代浏览器的简洁高交互界面。 ``` @@ -15,7 +15,7 @@ FastAPI 0.115 ── SQLAlchemy 2.0 async ── Alembic ── SQLite(dev) → | 前端 | 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(**130 项**,52 个测试函数参数化展开)· ruff · `tsc --noEmit` 严格模式 | +| 质量 | pytest + pytest-asyncio(**150 项**,含职级报销标准、资料审核与 **Web⇄H5 一致性守卫** `tests/test_self_parity.py`)· ruff · `tsc --noEmit` 严格模式 | --- @@ -70,9 +70,10 @@ npm run dev # http://localhost:5173 | `payroll` | `pay123456` | 薪酬福利专员 | 全部 | 算薪、报盘、参保 | | `recruiter` | `rec123456` | 招聘经理 | 全部 | 职位、看板、Offer | | `manager` | `mgr123456` | 部门经理 | 部门及以下 | 部门内审批(王志强 / EMP00003) | -| `emp` | `emp123456` | 普通员工 | 仅本人 | 只看 H5 自助(王建国 / EMP00001) | +| `emp` | `emp123456` | 普通员工 | 仅本人 | 桌面浏览器进 Web 自助 5 项导航,手机进 H5(王建国 / EMP00001) | -登录页内置这些账号(点击自动填充),勾选 **「以 H5 自助端进入」** 直接跳转 `/m`。 +登录页内置这些账号(点击自动填充);登录后按浏览器自动进入 Web 工作台或 H5, +桌面普通员工进入 `/dashboard`,手机浏览器进入 `/m`,无需手动切换。 ### 生产部署(Docker Compose) @@ -137,7 +138,9 @@ unis_hrms/ │ ├── components/ # ResourceTable(核心) FormDrawer(新增/编辑统一右侧抽屉) FieldInput Cell │ │ # icons(图标白名单) PageFallback EmptyBlock ListFilters │ ├── layouts/ # AdminLayout(动态菜单 + 固定侧栏/顶栏 + 用户胶囊) MobileLayout(H5 底栏) -│ ├── pages/ # 33 个管理端路由页面 + pages/mobile 6 个 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 运行整站 @@ -168,22 +171,72 @@ Offer 审批与一键入职(生成员工 + 账号 + 合同)。漏斗/渠道/ 五险一金方案(基数上下限、比例)· 参保登记与增减员 · 福利项目与发放记录 · 假期类型 / 额度矩阵 / 请假审批(含额度校验与扣减)/ 假期分析。 -### 3.5 员工自助(H5)`/m` -移动优先,390×844 起设计,antd-mobile 组件 + 自绘卡片体系,与桌面端共用一套 JWT 与 API。 +### 3.5 员工自助(Web / H5) -| 路由 | 内容 | -| --- | --- | -| `/m` | 首页:最新工资条、假期额度、九宫格入口、合同到期提醒、**待我审批**、公告、待办 | -| `/m/leave` | 请假申请(类型/日期/事由 → 额度预估)与我的申请状态跟踪 | -| `/m/payslips` | 历史工资条,按月展开收入/扣除/个税明细 | -| `/m/benefits` | 我的参保信息、福利发放、假期余额 | -| `/m/approvals` | **审批中心**:待我审批/已通过/已驳回 + 类型筛选 + 意见填写(变更前后对照中文化) | -| `/m/profile` | 我的档案、可编辑字段自助变更(走审批)、证明申请、消息通知 | +#### 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 与薪档)· 字典 · 用户与角色授权 · 公告 · 操作日志。 +每个职级可在行尾打开“报销标准”抽屉,维护多个报销项目(名称、金额、计量单位、说明), +员工在自助端“合同与薪资”中查看当前职级标准。 -### 3.7 员工全生命周期主线(入职 → 登记 → 发薪 → 调岗 → 离职) +### 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` 走审批, @@ -236,10 +289,10 @@ Offer 审批与一键入职(生成员工 + 账号 + 合同)。漏斗/渠道/ | 招聘经理 `recruiter` | dept_tree | 只读 | 读写+审批 | — | 只读 | 读写+审批 | 只读 | — | 12 页 / 5 个一级菜单 | | 薪酬福利专员 `payroll` | all | 读写+审批 | — | 读写+算薪 | 读写+发放 | 读写+审批 | 只读 | — | 16 页 / 5 个一级菜单 | | 部门经理 `manager` | dept_tree | 只读 | 只读 | 只读 | 只读 | 读写+审批 | 只读 | — | 12 页 / 6 个一级菜单 | -| 普通员工 `emp00001` | self | — | — | — | — | 读写 | — | — | 仅工作台(主用 H5) | +| 普通员工 `emp00001` | self | — | — | — | — | 读写 | — | — | 自助 5 项(首页/请假/工资/福利/我的) | -- 所有角色的 H5 底栏一致(首页 / 请假 / 工资 / 福利 / 我的),**能看什么由接口权限决定**: - 例如部门经理在 `/m/approvals` 看到待办与审批按钮,普通员工只看到自己的申请进度。 +- 所有角色的 **Web 侧栏与 H5 底栏完全同名同序**(首页 / 请假 / 工资 / 福利 / 我的), + 且**能看什么由接口权限决定**:例如部门经理在审批页看到待办与审批按钮,普通员工只看到自己的申请进度。 - 表里的「只读」= 有 `read` 无 `create/update`,前端自动隐藏新增/编辑/删除按钮,接口同样 403。 ### 4.2 自定义端点的数据范围红线 @@ -318,7 +371,7 @@ DATABASE_URL="mysql+pymysql://hrms:pwd@127.0.0.1:3306/hrms?charset=utf8mb4" \ ```bash ./.venv/bin/ruff check app tests migrations scripts # All checks passed! -./.venv/bin/python -m pytest -q # 130 passed +./.venv/bin/python -m pytest -q # 135 passed cd web && npx tsc --noEmit # 严格模式无输出 cd web && npm run build # tsc --noEmit && vite build ``` @@ -329,6 +382,7 @@ cd web && npm run build # tsc --noEmit && vite build 参保 → 建批次算薪 → 发布工资条 → 调部门(含审批生效)→ 离职,逐步断言跨模块数据一致 - `tests/test_role_matrix.py`:7 个角色的能力矩阵、写端点越权 403 扫描、审批中心可见范围(含 Offer 薪资泄漏回归) - `tests/test_api_surface.py`:全量路由可达性与响应契约 +- `tests/test_expense_standards.py`:职级多项目报销标准、重复校验与权限边界 - `tests/test_derived_fields.py`:`after_read` 派生字段回归(用户角色 / 角色计数 / 招聘负责人 / 司龄), 防止「保存即清空角色」这类静默失效再次发生 - 测试使用独立库 `data/test_hrms-.db`(库名带 PID,跑完自动清理),既不污染开发数据, @@ -460,6 +514,10 @@ cd web && npm run build # tsc --noEmit && vite build | 切换 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 | 忘了重跑 `python -m app.seed`,`sys_permission` 里还没有新码 | -| 启动脚本报 `unbound variable`(变量名带乱码) | macOS 自带 bash 3.2 在 UTF-8 下会把紧跟变量的全角字符吞进变量名;脚本内已统一写成 `${VAR})`,新增中文提示时记得给变量加花括号 |\n| 新增页面后 403 页没提示权限码 | 去 `web/src/api/routePerms.ts` 补一行 URL→权限码(仅影响提示文案,不影响放行判断) | +| 启动脚本报 `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/` 是需求参考系统,非本项目代码,不参与构建。 diff --git a/app/api/v1/auth.py b/app/api/v1/auth.py index edd3327..8061609 100644 --- a/app/api/v1/auth.py +++ b/app/api/v1/auth.py @@ -150,6 +150,23 @@ async def me(session: Session, auth: AuthCtx): @router.get("/menus", response_model=list[MenuNode], summary="当前用户可见菜单") async def my_menus(session: Session, auth: AuthCtx, platform: str = Query("web")): + if platform == "web" and auth.data_scope == "self": + from ...core.permissions import SELF_WEB_MENU_TREE + + return [ + MenuNode( + id=-(index + 1), + name=node["name"], + path=node["path"], + icon=node["icon"], + perm_code=node["perm"], + sort=node["sort"], + platform="web", + children=[], + ) + for index, node in enumerate(SELF_WEB_MENU_TREE) + if auth.can(node["perm"]) + ] rows = ( await session.execute(select(Menu).where(Menu.platform == platform).order_by(Menu.sort, Menu.id)) ).scalars().all() diff --git a/app/api/v1/benefits.py b/app/api/v1/benefits.py index 98a8df8..befb707 100644 --- a/app/api/v1/benefits.py +++ b/app/api/v1/benefits.py @@ -18,6 +18,7 @@ from ...core.deps import ( require_perm, ) from ...core.errors import AppError +from ...core.permissions import SELF_LINKS from ...db.base import utcnow from ...models.benefits import ( BenefitItem, @@ -283,7 +284,7 @@ async def grant_benefits(payload: GrantPayload, session: Session, batch_label=label, source="batch", remark=payload.remark)) created += 1 session.add(Notification(title=f"{item.name} 已发放", content=f"共 {created} 人,明细请在「我的福利」查看。", - category="benefit", link="/m/benefit")) + category="benefit", link=SELF_LINKS["benefits"])) await _log(session, "ben_benefit_item", item.id, "grant", auth, f"{created} 人 / 跳过 {skipped}") await session.commit() return {"message": f"已发放 {created} 人", "created": created, "skipped": skipped, @@ -521,7 +522,7 @@ async def approve_leave(item_id: int, payload: LeaveApprovePayload, session: Ses session.add(Notification(employee_id=request.employee_id, title=f"请假申请已{'通过' if payload.status == 'approved' else '驳回'}", content=payload.comment or f"{request.days} 天假期", category="leave", - link="/m/leave")) + link=SELF_LINKS["leave"])) await session.commit() return {"message": "审批完成", "status": payload.status} diff --git a/app/api/v1/org.py b/app/api/v1/org.py index a435d0d..6dfca5d 100644 --- a/app/api/v1/org.py +++ b/app/api/v1/org.py @@ -2,10 +2,12 @@ from __future__ import annotations -from fastapi import APIRouter, Query +from typing import Annotated + +from fastapi import APIRouter, Depends, Query from sqlalchemy import func, select -from ...core.deps import AuthCtx, Session +from ...core.deps import AuthContext, AuthCtx, Session, require_perm from ...core.errors import AppError from ..crud import CrudSpec, build_router from ...models.employee import Employee @@ -14,6 +16,7 @@ from ...schemas.org import ( DepartmentCreate, DepartmentRead, DepartmentUpdate, DictItemCreate, DictItemRead, DictItemUpdate, DictTypeCreate, DictTypeRead, DictTypeUpdate, + ExpenseStandardItem, ExpenseStandardsPayload, JobLevelCreate, JobLevelRead, JobLevelUpdate, PositionCreate, PositionRead, PositionUpdate, ) @@ -141,11 +144,58 @@ router.include_router(build_router(CrudSpec( search_fields=("name", "code"), filters=("is_active", "category"), order_by="sort", order="asc", ))) -router.include_router(build_router(CrudSpec( - model=JobLevel, create=JobLevelCreate, update=JobLevelUpdate, read=JobLevelRead, - module="org", resource="joblevel", label="职级", prefix="/job-levels", tag="组织架构", - search_fields=("name", "code"), filters=("is_active",), order_by="grade", order="asc", -))) + + +job_levels_custom = APIRouter() + + +@job_levels_custom.get( + "/{item_id:int}/expense-standards", + response_model=list[ExpenseStandardItem], + summary="读取职级报销标准", +) +async def get_expense_standards( + item_id: int, + session: Session, + auth: Annotated[AuthContext, Depends(require_perm("org:joblevel:read"))], +): + level = await session.get(JobLevel, item_id) + if not level: + raise AppError("职级不存在", "not_found", 404) + return [ExpenseStandardItem.model_validate(item) for item in (level.expense_standards or [])] + + +@job_levels_custom.put( + "/{item_id:int}/expense-standards", + summary="保存职级报销标准", +) +async def save_expense_standards( + item_id: int, + payload: ExpenseStandardsPayload, + session: Session, + auth: Annotated[AuthContext, Depends(require_perm("org:joblevel:update"))], +): + level = await session.get(JobLevel, item_id) + if not level: + raise AppError("职级不存在", "not_found", 404) + level.expense_standards = [item.model_dump() for item in payload.items] + await session.commit() + await session.refresh(level) + return { + "message": f"已保存 {len(payload.items)} 个报销项目", + "items": level.expense_standards or [], + "count": level.expense_standard_count, + } + + +router.include_router(build_router( + CrudSpec( + model=JobLevel, create=JobLevelCreate, update=JobLevelUpdate, read=JobLevelRead, + module="org", resource="joblevel", label="职级", prefix="/job-levels", tag="组织架构", + search_fields=("name", "code"), filters=("is_active",), order_by="grade", order="asc", + ), + preface=[job_levels_custom], +)) dict_router = APIRouter() diff --git a/app/api/v1/payroll.py b/app/api/v1/payroll.py index 7f72686..a21d20c 100644 --- a/app/api/v1/payroll.py +++ b/app/api/v1/payroll.py @@ -18,6 +18,7 @@ from ...core.deps import ( require_perm, ) from ...core.errors import AppError +from ...core.permissions import SELF_LINKS from ...db.base import utcnow from ...models.employee import Employee from ...models.org import Department, JobLevel @@ -337,7 +338,7 @@ async def pay_batch(item_id: int, session: Session, slip.confirmed_at = utcnow() session.add(Notification(title=f"{month_label(batch.year, batch.month)} 工资已发放", content=f"实发合计 ¥{batch.net_total},点击查看工资条。", - category="payslip", link="/m/payslip")) + category="payslip", link=SELF_LINKS["payslips"])) await _log(session, "sal_payroll_batch", batch.id, "pay", auth, batch.bank_batch_no) await session.commit() return {"message": "已标记发放并推送工资条", "bank_batch_no": batch.bank_batch_no, @@ -358,7 +359,7 @@ async def publish_batch(item_id: int, session: Session, for slip in slips: slip.status = "published" session.add(Notification(title=f"{month_label(batch.year, batch.month)} 工资条已发布", - content="请前往「我的工资条」查看明细。", category="payslip", link="/m/payslip")) + content="请前往「我的工资条」查看明细。", category="payslip", link=SELF_LINKS["payslips"])) await _log(session, "sal_payroll_batch", batch.id, "publish", auth, f"{len(slips)} 人") await session.commit() return {"message": f"已发布 {len(slips)} 份工资条", "published": len(slips), "pending": pending} @@ -438,7 +439,7 @@ async def publish_slip(item_id: int, session: Session, ensure(slip is not None, "工资条不存在") slip.status = "published" session.add(Notification(employee_id=slip.employee_id, title=f"{month_label(slip.year, slip.month)} 工资条", - content=f"实发 ¥{slip.net}", category="payslip", link="/m/payslip")) + content=f"实发 ¥{slip.net}", category="payslip", link=SELF_LINKS["payslips"])) await session.commit() return {"message": "已发布"} diff --git a/app/api/v1/selfservice.py b/app/api/v1/selfservice.py index 01a63fc..cf89d78 100644 --- a/app/api/v1/selfservice.py +++ b/app/api/v1/selfservice.py @@ -24,6 +24,7 @@ from ...core.deps import ( scope_employee_ids, ) from ...core.errors import AppError +from ...core.permissions import SELF_LINKS from ...db.base import utcnow from ...models.benefits import ( BenefitItem, @@ -136,7 +137,12 @@ def _labeled(d: dict | None) -> dict: out: dict[str, Any] = {} for k, v in (d or {}).items(): label = FIELD_LABELS.get(k, k) - out[label] = FIELD_VALUE_LABELS.get(v, v) if isinstance(v, str) else v + if isinstance(v, dict) and "after" in v: + before = FIELD_VALUE_LABELS.get(v.get("before"), v.get("before")) + after = FIELD_VALUE_LABELS.get(v.get("after"), v.get("after")) + out[label] = f"{before if before not in (None, '') else '未填写'} → {after if after not in (None, '') else '未填写'}" + else: + out[label] = FIELD_VALUE_LABELS.get(v, v) if isinstance(v, str) else v return out @@ -265,37 +271,73 @@ def _dict(obj, fields) -> dict[str, Any]: return {f: getattr(obj, f, None) for f in fields} -@router.patch("/profile", summary="更新可自助维护的字段") +@router.patch("/profile", summary="提交个人资料修改申请(兼容入口)") async def update_profile(payload: dict, session: Session, auth: Annotated[AuthContext, Depends(require_perm("selfservice:profile:update"))]): - emp = await me(session, auth) - changed = {k: v for k, v in (payload or {}).items() if k in SELF_EDITABLE} - if not changed: - raise AppError(f"仅允许修改:{'、'.join(SELF_EDITABLE)}", "invalid_fields") - for key, value in changed.items(): - setattr(emp, key, value) - await session.commit() - return {"message": "资料已更新", "updated": list(changed)} + # 旧版 H5 曾调用该入口直接写档案。保留路径是为了避免旧客户端 404, + # 但从这个版本起统一走审批,任何自助账号都不能绕过审核直接修改档案。 + return await create_profile_request(payload, session, auth) @router.post("/profile-requests", summary="提交信息变更申请") async def create_profile_request(payload: dict, session: Session, auth: Annotated[AuthContext, Depends(require_perm("selfservice:profile:update"))]): emp = await me(session, auth) - changes = payload.get("changes") or payload - if not isinstance(changes, dict) or not changes: + incoming = payload.get("changes") or payload + if not isinstance(incoming, dict) or not incoming: raise AppError("请填写需要变更的内容", "empty_changes") blocked = {"work_no", "name", "id_card", "department_id", "position_id", "job_level_id", - "status", "hire_date"} & set(changes) + "status", "hire_date"} & set(incoming) if blocked: raise AppError(f"以下字段需由 HR 办理:{'、'.join(sorted(blocked))}", "restricted_fields", 403) - request = ProfileRequest(employee_id=emp.id, changes=changes, reason=payload.get("reason"), - status="pending", applicant_user_id=auth.user.id) + allowed = set(SELF_EDITABLE) + invalid = set(incoming) - allowed + if invalid: + raise AppError( + f"仅允许申请修改:{'、'.join(SELF_EDITABLE)}", + "invalid_fields", + 403, + ) + changes: dict[str, dict[str, Any]] = {} + for key, after in incoming.items(): + before = getattr(emp, key, None) + if str(before or "") == str(after or ""): + continue + changes[key] = {"before": before, "after": after} + if not changes: + raise AppError("提交内容与当前档案一致,无需审批", "no_changes") + request = ProfileRequest( + employee_id=emp.id, + changes=changes, + reason=payload.get("reason"), + status="pending", + applicant_user_id=auth.user.id, + ) session.add(request) - session.add(Notification(title="有新的员工信息变更待审核", - content=f"{emp.name} 提交了资料变更申请。", category="profile", link="/employee/pending")) + await session.flush() + session.add(ApprovalLog( + entity_type="profile", + entity_id=request.id, + action="submit", + actor_id=auth.user.id, + actor_name=auth.user.name, + comment=payload.get("reason"), + created_at=utcnow(), + )) + await _notify_approvers( + session, + emp, + "有新的员工信息变更待审核", + f"{emp.name} 提交了 {len(changes)} 项资料变更申请。", + "/employees/changes", + ) await session.commit() - return {"message": "变更申请已提交,等待 HR 审核", "id": request.id} + return { + "message": "变更申请已提交,审核通过后才会写入个人档案", + "id": request.id, + "status": "pending", + "changed": list(changes), + } @router.delete("/profile-requests/{item_id}", summary="撤回信息变更申请") @@ -379,11 +421,17 @@ async def my_payslip_detail(item_id: int, session: Session, async def my_salary_standard(session: Session, auth: Annotated[AuthContext, Depends(require_perm("selfservice:payslip:read"))]): emp = await me(session, auth) + level = await session.get(JobLevel, emp.job_level_id) if emp.job_level_id else None + expense_standards = (level.expense_standards or []) if level else [] std = (await session.execute(select(EmployeeSalary).where( EmployeeSalary.employee_id == emp.id, EmployeeSalary.is_active.is_(True)) .order_by(EmployeeSalary.effective_date.desc()))).scalars().first() if not std: - return {"configured": False} + return { + "configured": False, + "job_level_name": level.name if level else None, + "expense_standards": expense_standards, + } plan = await session.get(SalaryPlan, std.plan_id) merged = dict(plan.items or {}) if plan and plan.items else {} merged.update(std.overrides or {}) @@ -397,6 +445,8 @@ async def my_salary_standard(session: Session, "total": round(sum(float(v) for v in merged.values()), 2), "bank_name": std.bank_name, "bank_account": _mask(std.bank_account), "special_deduction": float(std.special_deduction or 0), + "job_level_name": level.name if level else None, + "expense_standards": expense_standards, "adjustments": [{"effective_date": a.effective_date, "adjust_type": a.adjust_type, "after_amount": float(a.after_amount or 0), "status": a.status, "reason": a.reason} for a in adjustments], @@ -586,7 +636,7 @@ async def create_leave(payload: dict, session: Session, session.add(ApprovalLog(entity_type="ben_leave_request", entity_id=request.id, action="submit", actor_id=auth.user.id, actor_name=emp.name, created_at=utcnow())) await _notify_approvers(session, emp, f"{emp.name} 提交了请假申请", - f"{leave_type.name} {days:g} 天({start} ~ {end})", "/m/approval") + f"{leave_type.name} {days:g} 天({start} ~ {end})", SELF_LINKS["approvals"]) await session.commit() return {"message": "请假申请已提交", "id": request.id, "days": days} @@ -972,7 +1022,7 @@ async def decide(kind: str, item_id: int, payload: dict, session: Session, if employee_id: session.add(Notification(employee_id=employee_id, title=f"{label}申请已{'通过' if decision == 'approved' else '驳回'}", - content=comment or summary, category="approval", link="/m/record")) + content=comment or summary, category="approval", link=SELF_LINKS["approvals"])) await session.commit() return {"message": f"已{'通过' if decision == 'approved' else '驳回'}", "status": decision} @@ -984,6 +1034,8 @@ async def _apply_profile_change(request: ProfileRequest, session: Session, decis if not emp or decision != "approved": return for key, value in (request.changes or {}).items(): + if isinstance(value, dict): + value = value.get("after") if key in SELF_EDITABLE or key in ("highest_degree", "school", "specialty", "birthday", "nation", "political_status", "emergency_contact", "emergency_phone", "bank_name"): diff --git a/app/core/permissions.py b/app/core/permissions.py index ff513a5..7a64412 100644 --- a/app/core/permissions.py +++ b/app/core/permissions.py @@ -217,6 +217,36 @@ MOBILE_MENU_TREE: list[dict] = [ {"name": "我的", "path": "/m/profile", "icon": "user", "perm": "selfservice:profile:read", "sort": 50}, ] +# 普通员工在 PC 浏览器登录时使用的自助导航。名称、顺序和权限与 H5 底部导航 +# 完全一致,只把目的地换成了管理端外壳内的响应式页面。 +SELF_WEB_MENU_TREE: list[dict] = [ + {"name": "首页", "path": "/dashboard", "icon": "HomeOutlined", + "perm": "selfservice:home:read", "sort": 10}, + {"name": "请假", "path": "/self/leave", "icon": "CalendarOutlined", + "perm": "selfservice:leave:read", "sort": 20}, + {"name": "工资", "path": "/self/payslips", "icon": "MoneyCollectOutlined", + "perm": "selfservice:payslip:read", "sort": 30}, + {"name": "福利", "path": "/self/benefits", "icon": "GiftOutlined", + "perm": "selfservice:benefit:read", "sort": 40}, + {"name": "我的", "path": "/self/profile", "icon": "UserOutlined", + "perm": "selfservice:profile:read", "sort": 50}, +] + +# 通知 / 待办里落库的 link 一律取这里的路径,不要在业务代码里手写字符串。 +# 约定:用 H5 路径入库(历史数据即如此),前端渲染前统一过 toWebPath(), +# 于是同一条消息在 Web 工作台跳 /self/payslips、在 H5 跳 /m/payslips,永不 404。 +# 审批与待办不在两份菜单树里(两端都从首页进入),因此在此显式登记。 +SELF_LINKS = { + "home": "/m", + "leave": "/m/leave", + "payslips": "/m/payslips", + "benefits": "/m/benefits", + "approvals": "/m/approvals", + "tasks": "/m/tasks", + "profile": "/m/profile", +} + + # --- built-in roles -------------------------------------------------------- # 员工自助 (H5) 基线:任何绑定档案的账号都应当能完成「看工资条 / 请假 / 改资料」 # 等自助动作。管理者与专员首先是员工,因此除超级管理员外,各角色模板均并入该基线; diff --git a/app/models/org.py b/app/models/org.py index 2bbc390..c03a1ea 100644 --- a/app/models/org.py +++ b/app/models/org.py @@ -2,7 +2,7 @@ from __future__ import annotations -from sqlalchemy import Boolean, ForeignKey, Integer, String, Text +from sqlalchemy import JSON, Boolean, ForeignKey, Integer, String, Text from sqlalchemy.orm import Mapped, mapped_column from ..db.base import Base, PKMixin, TimestampMixin @@ -45,8 +45,15 @@ class JobLevel(PKMixin, TimestampMixin, Base): grade: Mapped[int] = mapped_column(Integer, default=1) sort: Mapped[int] = mapped_column(Integer, default=0) is_active: Mapped[bool] = mapped_column(Boolean, default=True) + # 每个职级可配置多个报销项目,例如交通、住宿、通讯、餐费。 + # 以 JSON 数组保存项目明细,避免为数量不固定的项目创建多张关联表。 + expense_standards: Mapped[list[dict] | None] = mapped_column(JSON) remark: Mapped[str | None] = mapped_column(String(255)) + @property + def expense_standard_count(self) -> int: + return len(self.expense_standards or []) + class DictType(PKMixin, Base): __tablename__ = "org_dict_type" diff --git a/app/schemas/org.py b/app/schemas/org.py index f8d8420..c459b7c 100644 --- a/app/schemas/org.py +++ b/app/schemas/org.py @@ -2,7 +2,7 @@ from __future__ import annotations -from pydantic import BaseModel +from pydantic import BaseModel, Field, field_validator, model_validator from .common import ORMBase, make_create, make_update @@ -33,6 +33,20 @@ class PositionRead(ORMBase): remark: str | None = None +class ExpenseStandardItem(BaseModel): + """职级下的一项报销标准。金额由具体制度解释(月度/单次/按天等)。""" + + project_name: str = Field(min_length=1, max_length=64) + limit_amount: float = Field(ge=0) + unit: str = Field(default="元/月", min_length=1, max_length=16) + remark: str | None = Field(default=None, max_length=255) + + @field_validator("project_name", "unit") + @classmethod + def _strip_text(cls, value: str) -> str: + return value.strip() + + class JobLevelRead(ORMBase): id: int name: str @@ -40,8 +54,27 @@ class JobLevelRead(ORMBase): grade: int = 1 sort: int = 0 is_active: bool = True + expense_standards: list[ExpenseStandardItem] = Field(default_factory=list) + expense_standard_count: int = 0 remark: str | None = None + @field_validator("expense_standards", mode="before") + @classmethod + def _none_as_empty(cls, value): + return value or [] + + +class ExpenseStandardsPayload(BaseModel): + items: list[ExpenseStandardItem] = Field(default_factory=list) + + @model_validator(mode="after") + def _unique_projects(self): + names = [item.project_name for item in self.items] + duplicated = sorted({name for name in names if names.count(name) > 1}) + if duplicated: + raise ValueError(f"报销项目不能重名:{'、'.join(duplicated)}") + return self + class DictItemRead(ORMBase): id: int @@ -66,8 +99,14 @@ DepartmentCreate = make_create(DepartmentRead, "DepartmentCreate", required=("na DepartmentUpdate = make_update(DepartmentRead, "DepartmentUpdate") PositionCreate = make_create(PositionRead, "PositionCreate", required=("name",)) PositionUpdate = make_update(PositionRead, "PositionUpdate") -JobLevelCreate = make_create(JobLevelRead, "JobLevelCreate", required=("name",)) -JobLevelUpdate = make_update(JobLevelRead, "JobLevelUpdate") +JobLevelCreate = make_create( + JobLevelRead, "JobLevelCreate", required=("name",), + exclude=("id", "created_at", "updated_at", "expense_standards", "expense_standard_count"), +) +JobLevelUpdate = make_update( + JobLevelRead, "JobLevelUpdate", + exclude=("id", "created_at", "updated_at", "expense_standards", "expense_standard_count"), +) DictItemCreate = make_create(DictItemRead, "DictItemCreate", required=("type_code", "label", "value")) DictItemUpdate = make_update(DictItemRead, "DictItemUpdate") DictTypeCreate = make_create(DictTypeRead, "DictTypeCreate", required=("code", "name"), diff --git a/app/services/seed_content.py b/app/services/seed_content.py index b8b1640..d7de1d3 100644 --- a/app/services/seed_content.py +++ b/app/services/seed_content.py @@ -11,6 +11,7 @@ from ..models.employee import Employee, EmployeeChange, EmployeeDocument, Employ from ..models.org import Department, Position from ..models.rbac import Announcement, Notification, User from ..models.selfservice import ApprovalLog, ProfileRequest, TaskReminder +from ..core.permissions import SELF_LINKS from .seed import RNG, already, count, log, mk ANNOUNCEMENTS = [ @@ -146,7 +147,7 @@ async def seed_tasks_notifications(session) -> dict: due_date=date.today() + timedelta(days=days + RNG.randint(0, 10)), level=level, status="pending", detail="请在截止时间前完成,逾期将同步至部门负责人。", - link="/m/tasks")) + link=SELF_LINKS["tasks"])) tasks += 1 await session.flush() notes = 0 @@ -154,11 +155,11 @@ async def seed_tasks_notifications(session) -> dict: for emp in employees[:24]: user = users.get(emp.id) title, content, category, link = RNG.choice([ - ("您的请假申请已通过", "审批人已完成审批,可在「我的请假」中查看记录。", "leave", "/m/leave"), - ("工资条已发布", "本月工资条已发布,请及时查看并确认。", "payslip", "/m/payslips"), - ("合同即将到期", "您的劳动合同将在 60 天内到期,请联系 HR 办理续签。", "contract", "/m/profile"), - ("试用期转正提醒", "您的试用期即将结束,请提交转正总结。", "regular", "/m/tasks"), - ("生日祝福", "祝你生日快乐,愿你在新的一岁里一切顺利!", "system", "/m"), + ("您的请假申请已通过", "审批人已完成审批,可在「我的请假」中查看记录。", "leave", SELF_LINKS["leave"]), + ("工资条已发布", "本月工资条已发布,请及时查看并确认。", "payslip", SELF_LINKS["payslips"]), + ("合同即将到期", "您的劳动合同将在 60 天内到期,请联系 HR 办理续签。", "contract", SELF_LINKS["profile"]), + ("试用期转正提醒", "您的试用期即将结束,请提交转正总结。", "regular", SELF_LINKS["tasks"]), + ("生日祝福", "祝你生日快乐,愿你在新的一岁里一切顺利!", "system", SELF_LINKS["home"]), ]) session.add(mk(Notification, user_id=user.id if user else None, employee_id=emp.id, title=title, content=content, category=category, link=link, diff --git a/app/services/seed_org.py b/app/services/seed_org.py index a430527..fee9d19 100644 --- a/app/services/seed_org.py +++ b/app/services/seed_org.py @@ -126,10 +126,45 @@ async def seed_job_levels(session) -> int: return len(JOB_LEVELS) +async def seed_expense_standards(session) -> int: + """为尚未配置的职级补一套演示报销标准,便于直接验证与生成使用手册截图。""" + levels = list((await session.execute(select(JobLevel))).scalars().all()) + changed = 0 + for level in levels: + if level.expense_standards: + continue + grade = max(1, int(level.grade or 1)) + level.expense_standards = [ + { + "project_name": "市内交通", + "limit_amount": float(600 + grade * 300), + "unit": "元/月", + "remark": "因公出行,实报实销不超过月度上限", + }, + { + "project_name": "差旅住宿", + "limit_amount": float(350 + grade * 100), + "unit": "元/晚", + "remark": "按出差城市标准执行", + }, + { + "project_name": "通讯补贴", + "limit_amount": float(100 + grade * 50), + "unit": "元/月", + "remark": "凭话费发票报销", + }, + ] + changed += 1 + await session.flush() + return changed + + async def run(session, *, force: bool = False) -> dict: dicts = await seed_dicts(session) depts = await seed_departments(session) positions = await seed_positions(session) levels = await seed_job_levels(session) + standards = await seed_expense_standards(session) return {"dict_items": dicts, "departments": depts, "positions": positions, - "job_levels": levels, "total_depts": await count(session, Department)} + "job_levels": levels, "expense_standards": standards, + "total_depts": await count(session, Department)} diff --git a/migrations/versions/20261020_1200_job_level_expense_standards.py b/migrations/versions/20261020_1200_job_level_expense_standards.py new file mode 100644 index 0000000..9b8ee96 --- /dev/null +++ b/migrations/versions/20261020_1200_job_level_expense_standards.py @@ -0,0 +1,29 @@ +"""job level expense standards + +Revision ID: 8f1b2c3d4e5f +Revises: c4aff1fa2133 +Create Date: 2026-10-20 12:00:00+08:00 +""" + +from __future__ import annotations + +from typing import Sequence, Union + +import sqlalchemy as sa +from alembic import op + + +revision: str = "8f1b2c3d4e5f" +down_revision: Union[str, None] = "c4aff1fa2133" +branch_labels: Union[str, Sequence[str], None] = None +depends_on: Union[str, Sequence[str], None] = None + + +def upgrade() -> None: + with op.batch_alter_table("org_job_level", schema=None) as batch_op: + batch_op.add_column(sa.Column("expense_standards", sa.JSON(), nullable=True)) + + +def downgrade() -> None: + with op.batch_alter_table("org_job_level", schema=None) as batch_op: + batch_op.drop_column("expense_standards") diff --git a/scripts/browser_smoke.py b/scripts/browser_smoke.py new file mode 100644 index 0000000..6b5c006 --- /dev/null +++ b/scripts/browser_smoke.py @@ -0,0 +1,124 @@ +#!/usr/bin/env python3 +"""真实浏览器验收:设备自适应登录、Web/H5 菜单、帮助中心入口。""" + +from __future__ import annotations + +import json +import shutil +import subprocess +import tempfile +import time +import urllib.request +from pathlib import Path + +from capture_help import CDP + + +BASE = "http://127.0.0.1:8000" +CHROME = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" +PORT = 9231 +DESKTOP_UA = ( + "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) " + "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0 Safari/537.36" +) +MOBILE_UA = ( + "Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X) " + "AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Mobile/15E148 Safari/604.1" +) + + +def wait_page() -> str: + deadline = time.time() + 20 + while time.time() < deadline: + try: + with urllib.request.urlopen(f"http://127.0.0.1:{PORT}/json/list", timeout=1) as resp: + target = next(x for x in json.load(resp) if x.get("type") == "page") + return target["webSocketDebuggerUrl"] + except Exception: + time.sleep(0.2) + raise RuntimeError("Chrome 调试端口未就绪") + + +def wait_path(cdp: CDP, path: str) -> None: + deadline = time.time() + 20 + while time.time() < deadline: + if cdp.eval("location.pathname") == path: + time.sleep(0.8) + return + time.sleep(0.25) + raise AssertionError(f"登录后路径应为 {path},实际为 {cdp.eval('location.pathname')}") + + +def fill_and_login(cdp: CDP, username: str, password: str, mobile: bool) -> str: + width, height, scale = (390, 844, 2) if mobile else (1440, 960, 1) + cdp.call("Emulation.setDeviceMetricsOverride", { + "width": width, "height": height, "deviceScaleFactor": scale, "mobile": mobile, + }) + cdp.call("Emulation.setUserAgentOverride", {"userAgent": MOBILE_UA if mobile else DESKTOP_UA}) + cdp.navigate("/login", "登录工作台") + cdp.eval("localStorage.clear()") + cdp.navigate("/login", "登录工作台") + cdp.eval( + f"""(() => {{ + const inputs = document.querySelectorAll('input'); + const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value').set; + setter.call(inputs[0], {json.dumps(username)}); + inputs[0].dispatchEvent(new Event('input', {{bubbles: true}})); + setter.call(inputs[1], {json.dumps(password)}); + inputs[1].dispatchEvent(new Event('input', {{bubbles: true}})); + const button = [...document.querySelectorAll('button')] + .find(x => x.innerText.replace(/\\s/g, '').includes('登录')); + button.click(); + return true; + }})()""" + ) + return "/m" if mobile else "/dashboard" + + +def main() -> None: + profile = Path(tempfile.mkdtemp(prefix="unis-hrms-smoke-")) + chrome = subprocess.Popen( + [ + CHROME, "--headless=new", f"--remote-debugging-port={PORT}", + f"--user-data-dir={profile}", "--no-first-run", "--no-default-browser-check", + "--disable-gpu", "about:blank", + ], + stdout=subprocess.DEVNULL, + stderr=subprocess.DEVNULL, + ) + try: + cdp = CDP(wait_page()) + cdp.call("Page.enable") + cdp.call("Runtime.enable") + + target = fill_and_login(cdp, "emp", "emp123456", mobile=False) + wait_path(cdp, target) + desktop_menus = cdp.eval( + "[...document.querySelectorAll('.admin-sider .ant-menu-title-content')].map(x => x.innerText.trim())" + ) + assert desktop_menus == ["首页", "请假", "工资", "福利", "我的"], desktop_menus + cdp.call("Page.navigate", {"url": f"{BASE}/help"}) + deadline = time.time() + 20 + while time.time() < deadline and not cdp.eval("!!document.querySelector('iframe')"): + time.sleep(0.25) + assert cdp.eval("document.querySelector('iframe')?.getAttribute('src')") == "/help/index.html" + + target = fill_and_login(cdp, "emp", "emp123456", mobile=True) + wait_path(cdp, target) + mobile_menus = cdp.eval( + "[...document.querySelectorAll('.m-tabbar .adm-tab-bar-item-title')].map(x => x.innerText.trim())" + ) + assert mobile_menus == ["首页", "请假", "工资", "福利", "我的"], mobile_menus + print("browser smoke passed: desktop /dashboard, mobile /m, menus and help center") + cdp.ws.close() + finally: + chrome.terminate() + try: + chrome.wait(timeout=5) + except subprocess.TimeoutExpired: + chrome.kill() + shutil.rmtree(profile, ignore_errors=True) + + +if __name__ == "__main__": + main() diff --git a/scripts/capture_help.py b/scripts/capture_help.py new file mode 100644 index 0000000..b0e44cf --- /dev/null +++ b/scripts/capture_help.py @@ -0,0 +1,239 @@ +#!/usr/bin/env python3 +"""使用真实 Chrome 登录系统并生成 HTML 使用手册所需截图。 + +依赖本机 Google Chrome;通过 Chrome DevTools Protocol 操作页面,不额外安装 +浏览器自动化包。运行前先启动 ``uvicorn app.main:app --port 8000``。 +""" + +from __future__ import annotations + +import json +import shutil +import subprocess +import tempfile +import time +import urllib.request +from pathlib import Path + +from websockets.sync.client import connect + + +ROOT = Path(__file__).resolve().parents[1] +OUT = ROOT / "web" / "public" / "help" / "assets" +BASE = "http://127.0.0.1:8000" +CHROME = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" +PORT = 9227 + + +def api_login(username: str, password: str) -> dict: + body = json.dumps({"username": username, "password": password}).encode() + req = urllib.request.Request( + f"{BASE}/api/v1/auth/login", + data=body, + headers={"Content-Type": "application/json"}, + ) + with urllib.request.urlopen(req, timeout=20) as resp: + return json.load(resp) + + +class CDP: + def __init__(self, ws_url: str) -> None: + self.ws = connect(ws_url, max_size=64 * 1024 * 1024, legacy=True) + self.seq = 0 + + def call(self, method: str, params: dict | None = None) -> dict: + self.seq += 1 + current = self.seq + self.ws.send(json.dumps({"id": current, "method": method, "params": params or {}})) + while True: + msg = json.loads(self.ws.recv(timeout=30)) + if msg.get("id") == current: + if "error" in msg: + raise RuntimeError(f"{method}: {msg['error']}") + return msg.get("result", {}) + + def eval(self, expression: str): + result = self.call( + "Runtime.evaluate", + {"expression": expression, "returnByValue": True, "awaitPromise": True}, + ) + return result.get("result", {}).get("value") + + def wait_text(self, text: str, timeout: float = 25) -> None: + deadline = time.time() + timeout + expression = f"document.body && document.body.innerText.includes({json.dumps(text)})" + while time.time() < deadline: + if self.eval(expression): + time.sleep(0.7) + return + time.sleep(0.25) + raise TimeoutError(f"页面未出现文字:{text}") + + def navigate(self, path: str, text: str | None = None) -> None: + self.call("Page.navigate", {"url": f"{BASE}{path}"}) + time.sleep(0.5) + if text: + self.wait_text(text) + + def screenshot(self, name: str) -> None: + result = self.call( + "Page.captureScreenshot", + {"format": "png", "fromSurface": True, "captureBeyondViewport": False}, + ) + import base64 + + (OUT / name).write_bytes(base64.b64decode(result["data"])) + print(f"captured {name}") + + +def wait_debug_port() -> dict: + deadline = time.time() + 20 + while time.time() < deadline: + try: + with urllib.request.urlopen(f"http://127.0.0.1:{PORT}/json/version", timeout=1) as resp: + return json.load(resp) + except Exception: + time.sleep(0.2) + raise RuntimeError("Chrome 调试端口未就绪") + + +def page_target() -> dict: + with urllib.request.urlopen(f"http://127.0.0.1:{PORT}/json/list", timeout=3) as resp: + targets = json.load(resp) + page = next((item for item in targets if item.get("type") == "page"), None) + if page is None: + raise RuntimeError("Chrome 中没有可用页面") + return page + + +def main() -> None: + OUT.mkdir(parents=True, exist_ok=True) + profile = Path(tempfile.mkdtemp(prefix="unis-hrms-chrome-")) + chrome = subprocess.Popen( + [ + CHROME, + "--headless=new", + f"--remote-debugging-port={PORT}", + f"--user-data-dir={profile}", + "--no-first-run", + "--no-default-browser-check", + "--disable-gpu", + "--hide-scrollbars", + "--window-size=1600,1080", + "about:blank", + ], + stdout=subprocess.DEVNULL, + stderr=subprocess.DEVNULL, + ) + try: + wait_debug_port() + cdp = CDP(page_target()["webSocketDebuggerUrl"]) + cdp.call("Page.enable") + cdp.call("Runtime.enable") + cdp.call("Emulation.setDeviceMetricsOverride", { + "width": 1600, "height": 1080, "deviceScaleFactor": 1, "mobile": False, + }) + + cdp.navigate("/login", "登录工作台") + cdp.screenshot("01-login.png") + + plans = [ + ("admin", "admin123", "/dashboard", "今日组织概览", "02-dashboard.png"), + ("admin", "admin123", "/employees", "员工档案", "03-employees.png"), + ("admin", "admin123", "/org/job-levels", "职级职等", "04-job-levels.png"), + ("admin", "admin123", "/payroll/batches", "月度算薪", "06-payroll.png"), + ("admin", "admin123", "/benefits/enrollments", "参保登记", "07-benefits.png"), + ("admin", "admin123", "/system/roles", "角色权限", "08-roles.png"), + ] + token_for = {} + for username, password, path, text, name in plans: + pair = token_for.get(username) + if pair is None: + pair = api_login(username, password) + token_for[username] = pair + cdp.navigate("/login") + cdp.eval( + "localStorage.setItem('unis-hrms-auth', " + + json.dumps(json.dumps({ + "state": {"token": pair["access_token"], "refresh": pair["refresh_token"]}, + "version": 0, + })) + + ")" + ) + cdp.navigate(path, text) + cdp.screenshot(name) + + # 职级行内打开“报销标准”抽屉,展示多项目配置。 + cdp.navigate("/org/job-levels", "职级职等") + clicked = cdp.eval( + "(() => { const b=[...document.querySelectorAll('button')]" + ".find(x => x.innerText.includes('报销标准')); if (!b) return false; b.click(); return true })()" + ) + if not clicked: + raise RuntimeError("未找到报销标准按钮") + cdp.wait_text("可配置多个报销项目") + cdp.screenshot("05-expense-standards.png") + + # 普通员工 Web 自助:导航直接呈现与 H5 同名的 5 项。 + pair = api_login("emp", "emp123456") + token_for["emp"] = pair + cdp.navigate("/login") + cdp.eval( + "localStorage.setItem('unis-hrms-auth', " + + json.dumps(json.dumps({ + "state": {"token": pair["access_token"], "refresh": pair["refresh_token"]}, + "version": 0, + })) + + ")" + ) + cdp.navigate("/dashboard", "常用自助入口") + cdp.screenshot("09-web-self-home.png") + cdp.navigate("/self/profile", "我的信息") + cdp.screenshot("10-web-self-profile.png") + cdp.eval( + "(() => { const b=[...document.querySelectorAll('span,a,button')]" + ".find(x => x.innerText.trim()==='修改资料'); if (!b) return false; b.click(); return true })()" + ) + cdp.wait_text("提交审核") + cdp.screenshot("11-profile-audit.png") + + # H5 自动识别由单独的手机视口验证。 + cdp.call("Emulation.setDeviceMetricsOverride", { + "width": 390, "height": 844, "deviceScaleFactor": 2, "mobile": True, + }) + cdp.call("Emulation.setUserAgentOverride", { + "userAgent": ( + "Mozilla/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X) " + "AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Mobile/15E148 Safari/604.1" + ), + }) + cdp.navigate("/m", "最新实发工资") + cdp.screenshot("12-h5-home.png") + cdp.navigate("/m/profile", "我的信息") + cdp.screenshot("13-h5-profile.png") + + # 审批中心使用 HR 账号(拥有审批权且有员工档案)。 + pair = token_for.get("hr") or api_login("hr", "hr123456") + cdp.navigate("/login") + cdp.eval( + "localStorage.setItem('unis-hrms-auth', " + + json.dumps(json.dumps({ + "state": {"token": pair["access_token"], "refresh": pair["refresh_token"]}, + "version": 0, + })) + + ")" + ) + cdp.navigate("/m/approvals", "审批中心") + cdp.screenshot("14-approvals.png") + cdp.ws.close() + finally: + chrome.terminate() + try: + chrome.wait(timeout=5) + except subprocess.TimeoutExpired: + chrome.kill() + shutil.rmtree(profile, ignore_errors=True) + + +if __name__ == "__main__": + main() diff --git a/tests/test_expense_standards.py b/tests/test_expense_standards.py new file mode 100644 index 0000000..db56988 --- /dev/null +++ b/tests/test_expense_standards.py @@ -0,0 +1,63 @@ +"""职级报销标准:多项目保存、校验与权限边界。""" + +from __future__ import annotations + + +API = "/api/v1" + + +def test_job_level_can_store_multiple_expense_standards(client, admin, payroll): + levels = client.get(f"{API}/org/job-levels", headers=admin, params={"page_size": 50}).json()["items"] + level = next(row for row in levels if row["code"] == "P1") + items = [ + {"project_name": "市内交通", "limit_amount": 1200, "unit": "元/月", "remark": "实报实销"}, + {"project_name": "差旅住宿", "limit_amount": 650, "unit": "元/晚", "remark": "按城市标准"}, + {"project_name": "通讯补贴", "limit_amount": 200, "unit": "元/月", "remark": "凭发票报销"}, + ] + saved = client.put( + f"{API}/org/job-levels/{level['id']}/expense-standards", + headers=admin, + json={"items": items}, + ) + assert saved.status_code == 200, saved.text + assert saved.json()["count"] == 3 + + loaded = client.get( + f"{API}/org/job-levels/{level['id']}/expense-standards", + headers=payroll, + ) + assert loaded.status_code == 200, loaded.text + assert loaded.json() == items + detail = client.get(f"{API}/org/job-levels/{level['id']}", headers=admin).json() + assert detail["expense_standard_count"] == 3 + + +def test_expense_standards_reject_duplicates_and_require_update_permission(client, admin, payroll): + levels = client.get(f"{API}/org/job-levels", headers=admin, params={"page_size": 50}).json()["items"] + level = levels[0] + duplicated = [ + {"project_name": "交通", "limit_amount": 100, "unit": "元/月"}, + {"project_name": "交通", "limit_amount": 200, "unit": "元/月"}, + ] + bad = client.put( + f"{API}/org/job-levels/{level['id']}/expense-standards", + headers=admin, + json={"items": duplicated}, + ) + assert bad.status_code == 422 + + denied = client.put( + f"{API}/org/job-levels/{level['id']}/expense-standards", + headers=payroll, + json={"items": duplicated[:1]}, + ) + assert denied.status_code == 403 + + +def test_employee_salary_standard_exposes_job_level_expense_standards(client, employee): + mine = client.get(f"{API}/self/salary-standard", headers=employee) + assert mine.status_code == 200, mine.text + body = mine.json() + assert body["job_level_name"] + assert len(body["expense_standards"]) >= 1 + assert {"project_name", "limit_amount", "unit"} <= set(body["expense_standards"][0]) diff --git a/tests/test_flows.py b/tests/test_flows.py index 913af1f..7d33f31 100644 --- a/tests/test_flows.py +++ b/tests/test_flows.py @@ -256,6 +256,10 @@ def test_selfservice_profile_request_is_applied(client, employee, hr): json={"changes": {"address": "测试地址 100 号"}, "reason": "搬家"}) assert submitted.status_code == 200, submitted.text request_id = submitted.json()["id"] + snapshots = client.get("/api/v1/self/profile", headers=employee).json()["requests"] + snapshot = next(row for row in snapshots if row["id"] == request_id) + assert snapshot["changes"]["address"]["after"] == "测试地址 100 号" + assert snapshot["status"] == "pending" listed = client.get("/api/v1/employee-profile-requests", headers=hr, params={"status": "pending"}).json()["items"] @@ -269,6 +273,28 @@ def test_selfservice_profile_request_is_applied(client, employee, hr): assert fresh["address"] == "测试地址 100 号" +def test_legacy_profile_patch_cannot_bypass_approval(client, employee, hr): + """旧 PATCH 入口只能生成审批单,不能把内容直接写进员工档案。""" + old_email = client.get("/api/v1/self/profile", headers=employee).json()["employee"]["email"] + target = f"audit-{old_email or 'employee'}@example.com" + submitted = client.patch("/api/v1/self/profile", headers=employee, json={"email": target}) + assert submitted.status_code == 200, submitted.text + body = submitted.json() + assert body["status"] == "pending" + + unchanged = client.get("/api/v1/self/profile", headers=employee).json()["employee"]["email"] + assert unchanged == old_email, "审核前不得直接修改档案" + + approved = client.post( + f"/api/v1/employee-profile-requests/{body['id']}/approve", + headers=hr, + json={"status": "approved", "comment": "自动化审核"}, + ) + assert approved.status_code == 200, approved.text + changed = client.get("/api/v1/self/profile", headers=employee).json()["employee"]["email"] + assert changed == target + + def test_payslip_privacy_between_employees(client, login): a = login("emp00001") b = login("emp00002") diff --git a/tests/test_role_matrix.py b/tests/test_role_matrix.py index c6efbf1..93cac57 100644 --- a/tests/test_role_matrix.py +++ b/tests/test_role_matrix.py @@ -451,7 +451,7 @@ WEB_MENUS = { "/recruitment/pipeline", "/recruitment/candidates", "/recruitment/interviews", "/payroll/reports", "/benefits/leaves", "/org/departments", "/org/positions", "/org/job-levels"}, - "emp00001": {"/dashboard"}, + "emp00001": {"/dashboard", "/self/leave", "/self/payslips", "/self/benefits", "/self/profile"}, } H5_TILES = {"/m", "/m/leave", "/m/payslips", "/m/benefits", "/m/profile"} @@ -480,6 +480,19 @@ def test_menus_agree_with_api_access(client, login, admin, specialist): assert spec == H5_TILES +def test_employee_web_and_h5_menu_names_match(client, login): + """普通员工 PC 自助导航与 H5 必须同名、同序、同权限。""" + headers = _login(login, "emp00001") + web = client.get(f"{API}/auth/menus", headers=headers, params={"platform": "web"}).json() + mobile = client.get(f"{API}/auth/menus", headers=headers, params={"platform": "mobile"}).json() + assert [node["name"] for node in web] == ["首页", "请假", "工资", "福利", "我的"] + assert [node["name"] for node in web] == [node["name"] for node in mobile] + assert [node["perm_code"] for node in web] == [node["perm_code"] for node in mobile] + assert [node["path"] for node in web] == [ + "/dashboard", "/self/leave", "/self/payslips", "/self/benefits", "/self/profile", + ] + + def test_self_service_surface_available_to_every_bound_account(client, login): """自助端:所有绑定档案的账号 12 个只读接口全绿,且看不到别人的数据。""" for account in ACCOUNTS: diff --git a/tests/test_self_parity.py b/tests/test_self_parity.py new file mode 100644 index 0000000..f692ded --- /dev/null +++ b/tests/test_self_parity.py @@ -0,0 +1,222 @@ +"""Web 工作台 ⇄ H5 自助端 的一致性守卫(纯静态,不连数据库)。 + +「普通用户在两端看到同一套模块」这件事靠三层保证: + +1. ``web/src/self/manifest.ts`` —— 前端唯一的模块清单(名称/权限/顺序/图标/双端路径); +2. ``app/core/permissions.py`` 的 ``MOBILE_MENU_TREE`` 与 ``SELF_WEB_MENU_TREE`` + —— 后端按权限下发给两个外壳的导航树; +3. ``app/core/permissions.py`` 的 ``SELF_LINKS`` —— 通知与待办落库的跳转路径。 + +三者一旦漂移(改了 H5 忘了 Web、后端 link 写成历史单数路径),本文件的断言就会红。 +""" +from __future__ import annotations + +import pathlib +import re + +ROOT = pathlib.Path(__file__).resolve().parents[1] +WEB = ROOT / "web" / "src" + +from app.core.permissions import SELF_LINKS, MOBILE_MENU_TREE, SELF_WEB_MENU_TREE # noqa: E402 + +MANIFEST = (WEB / "self" / "manifest.ts").read_text(encoding="utf-8") +APP = (WEB / "App.tsx").read_text(encoding="utf-8") +ROUTE_PERMS = (WEB / "api" / "routePerms.ts").read_text(encoding="utf-8") +MODE = (WEB / "lib" / "mode.ts").read_text(encoding="utf-8") +ICONS = (WEB / "components" / "icons.tsx").read_text(encoding="utf-8") + +SELF_KEYS = {"home", "leave", "payslips", "benefits", "approvals", "tasks", "profile"} +TEXT = re.compile(r"(\w+): '([^']*)'") + + +def manifest_modules() -> dict[str, dict]: + """解析 manifest.ts 里的 SELF_MODULES,返回 {key: {字段: 值}}。""" + body = MANIFEST.split("SELF_MODULES: Record = {", 1)[1] + body = body.split("\n}\n", 1)[0] + out: dict[str, dict] = {} + for name, block in re.findall(r"\n (\w+): \{(.*?)\n \},", body, re.S): + item = dict(TEXT.findall(block)) + assert item.get("key") == name, f"{name}: key 与对象名不一致" + for flag in ("sort",): + item[flag] = int(re.search(flag + r": (\d+)", block).group(1)) + for flag in ("inWebMenu", "inMobileTab"): + item[flag] = re.search(flag + r": (true|false)", block).group(1) == "true" + out[name] = item + return out + + +MODS = manifest_modules() + + +def test_manifest_lists_every_self_service_module(): + assert set(MODS) == SELF_KEYS, "自助模块清单与 manifest 不符" + for key, m in MODS.items(): + for field in ("name", "title", "desc", "perm", "webPath", "mobilePath", + "antdIcon", "mobileIcon", "emoji", "color"): + assert m.get(field), f"{key} 缺少 {field}" + + +def test_manifest_matches_backend_h5_menu_tree(): + """底部 5 个 tab:名称 / 权限 / 路径 / 顺序必须与后端下发的一致。""" + tabs = sorted((m for m in MODS.values() if m["inMobileTab"]), key=lambda x: x["sort"]) + assert [m["name"] for m in tabs] == [n["name"] for n in MOBILE_MENU_TREE] + assert [m["mobilePath"] for m in tabs] == [n["path"] for n in MOBILE_MENU_TREE] + assert [m["perm"] for m in tabs] == [n["perm"] for n in MOBILE_MENU_TREE] + assert [n["sort"] for n in MOBILE_MENU_TREE] == sorted(n["sort"] for n in MOBILE_MENU_TREE) + + +def test_manifest_matches_backend_web_menu_tree(): + """Web 侧栏 5 项:除路径外,与 H5 tab 完全同名同序同权限。""" + nav = sorted((m for m in MODS.values() if m["inWebMenu"]), key=lambda x: x["sort"]) + assert [m["name"] for m in nav] == [n["name"] for n in SELF_WEB_MENU_TREE] + assert [m["webPath"] for m in nav] == [n["path"] for n in SELF_WEB_MENU_TREE] + assert [m["perm"] for m in nav] == [n["perm"] for n in SELF_WEB_MENU_TREE] + assert [n["sort"] for n in SELF_WEB_MENU_TREE] == sorted(n["sort"] for n in SELF_WEB_MENU_TREE) + + +def test_two_shells_use_the_same_navigation_placement(): + """两端可见模块必须一模一样:多的少了都是「Web 和 H5 不一致」的回归。""" + assert {m["key"] for m in MODS.values() if m["inWebMenu"]} == \ + {m["key"] for m in MODS.values() if m["inMobileTab"]} + # 审批与待办刻意不进导航,两端都从首页宫格进入 + off = {k for k, m in MODS.items() if not m["inWebMenu"]} + assert off == {"approvals", "tasks"}, off + + +def test_every_self_route_exists_in_both_shells(): + """manifest 里的每个路径都必须在 App.tsx 注册了路由,否则点了就是 404。""" + for key, m in MODS.items(): + assert re.search(r' = {", 1)[1].split("}", 1)[0] + registered = set(re.findall(r"(\w+):\s", block)) + for key, m in MODS.items(): + assert m["mobileIcon"] in registered, f"{key}: H5 图标 {m['mobileIcon']} 未注册" + + +def test_notification_links_follow_the_canonical_paths(): + """落库 link 只能是 manifest 里的 H5 路径,前端再改写为当前外壳的路径。""" + mobile = {m["mobilePath"] for m in MODS.values()} + for key, link in SELF_LINKS.items(): + assert key in MODS, f"SELF_LINKS 多出未知模块 {key}" + assert link == MODS[key]["mobilePath"], f"{key}: link={link} 应为 {MODS[key]['mobilePath']}" + assert link in mobile + + +def test_business_code_never_hardcodes_mobile_paths(): + """通知 / 待办的 link 一律走 SELF_LINKS,避免又写出 /m/payslip 这种历史单数路径。""" + offenders = [] + for py in (ROOT / "app").rglob("*.py"): + if py.name == "permissions.py": + continue + for lineno, line in enumerate(py.read_text(encoding="utf-8").splitlines(), 1): + if '"/m/' in line or "'/m/" in line: + offenders.append(f"{py.relative_to(ROOT)}:{lineno}") + assert not offenders, "请改用 SELF_LINKS:" + ", ".join(offenders) + + +def test_h5_pages_share_the_web_data_layer(): + """两端读同一批 hooks / queryKey:H5 页面不得再自己拼 query 与状态字典。""" + pages = sorted((WEB / "pages" / "mobile").glob("M*.tsx")) + extra = {"MLogin.tsx"} + checked = [p for p in pages if p.name not in extra] + assert len(checked) >= 7, "H5 页面数量异常" + for p in checked: + src = p.read_text(encoding="utf-8") + assert "from '../../api/http'" not in src, f"{p.name} 仍在直连 api/http" + assert re.search(r"useQuery\(|useMutation\(", src) is None, f"{p.name} 仍自建查询" + for p in sorted((WEB / "pages" / "self").glob("*.tsx")): + if p.name == "_shared.tsx": + continue + assert "from '../../api/self'" in p.read_text(encoding="utf-8"), f"{p.name} 未使用公共数据层" + + +def test_both_shells_use_the_shared_formatters(): + """金额/百分比只能走 lib/selfLabels 的格式化函数,避免两端数值字面不一致。""" + offenders: list[str] = [] + for sub in ("self", "mobile"): + for tsx in (WEB / "pages" / sub).glob("*.tsx"): + if tsx.name == "_shared.tsx": + continue + for lineno, line in enumerate(tsx.read_text(encoding="utf-8").splitlines(), 1): + # 0.07 * 100 直出百分比会露出浮点尾数(7.000000000000001%) + if re.search(r"\* 100\)?}\s*%", line) or "\u00a5{Number" in line: + offenders.append(f"{tsx.relative_to(ROOT)}:{lineno}") + assert not offenders, "请改用 selfLabels 的 pct()/rmb():" + ", ".join(offenders) + # 用到比例与金额的页面必须真的引用了公共层 + for name in ("self/Benefits.tsx", "mobile/MBenefits.tsx"): + src = (WEB / "pages" / name).read_text(encoding="utf-8") + assert "pct" in src and "rmb" in src, f"{name} 未使用公共格式化函数" + + +def test_status_dictionaries_are_complete_for_both_shells(): + """状态中文只有一份来源:自助端不得漏字典、也不得再内联三元判断。""" + labels = (WEB / "lib" / "selfLabels.ts").read_text(encoding="utf-8") + defs = (WEB / "api" / "defs.ts").read_text(encoding="utf-8") + # 合同状态取自后台同一份 CONTRACT_STATUS_OPTIONS,renewed 这类取值不会再露英文 + block = labels.split("export const CONTRACT_STATUS_TEXT", 1)[1].split("export const", 1)[0] + assert "CONTRACT_STATUS_OPTIONS.map" in block, "合同状态字典应派生自 api/defs" + opts = defs.split("export const CONTRACT_STATUS_OPTIONS", 1)[1].split("]", 1)[0] + colors = labels.split("export const CONTRACT_STATUS_COLOR", 1)[1].split("}", 1)[0] + for value in re.findall(r"value: '(\w+)'", opts): + assert f"{value}: '" in colors, f"合同状态 {value} 缺少配色" + # 两端页面不得再把 .status / .unit 各自翻译成中文:必须走 lib/selfLabels 字典 + offenders: list[str] = [] + for sub in ("self", "mobile"): + for tsx in (WEB / "pages" / sub).glob("*.tsx"): + for lineno, line in enumerate(tsx.read_text(encoding="utf-8").splitlines(), 1): + if re.search(r"(? + + + + + UNIS HRMS 全功能使用手册 + + + +
+ + +
+
+
UNIS HRMS · User Guide
+

全功能使用手册

+

覆盖管理端、员工 Web 自助、H5 自助、职级报销标准、个人档案审核、薪资福利、招聘与系统权限。按页面步骤即可完成日常操作。

+
+ + +
+
+ +
+
适用版本UNIS HRMS 2.0
+
更新日期2026-10-20
+
运行方式Web / H5 自适应
+
+ +
+

01登录与设备识别

+

系统不再要求手动勾选 H5;登录后会根据当前浏览器的设备特征自动选择入口。

+
+
桌面浏览器

进入 Web 工作台。普通员工会看到“首页 / 请假 / 工资 / 福利 / 我的”五项自助导航。

+
手机 / H5 浏览器

自动进入 /m 移动自助端,底部导航与 Web 自助菜单同名、同序、同权限。

+
指定跳转

从系统内部链接进入时,会优先回到原目标页面;无指定目标时再执行设备判断。

+
+
    +
  1. 打开系统地址,输入账号和密码。
  2. +
  3. 点击“登录”,系统自动识别桌面或手机浏览器。
  4. +
  5. 首次登录建议先打开右上角“使用手册”确认角色与可用功能。
  6. +
+
+ UNIS HRMS 登录页 +
登录页会明确提示“将根据当前浏览器自动进入 Web 工作台或 H5 自助端”。
+
+
+ +
+

02管理端工作台

+

工作台按角色汇总组织人数、待办、人员趋势、招聘漏斗、薪资成本与风险提醒。

+
+
核心指标

在职人数、试用期人数、在招职位、最近计薪总额。

+
待我处理

请假、资料变更、人事异动、合同到期均可直接进入对应流程。

+
风险提醒

合同临期、生日提醒、累计离职等情况在右上区域集中展示。

+
+
+ 管理端工作台 +
管理端工作台:主管与 HR 登录后的统一数据概览。
+
+
+ +
+

03人事档案

+

员工花名册支持关键字、部门、职位、职级、状态与用工形式组合查询,并可从任意行打开 360° 档案。

+
    +
  1. 进入“人事档案 → 员工档案”。
  2. +
  3. 使用搜索框或表头筛选定位员工。
  4. +
  5. 点击行尾“档案”查看个人信息、合同、教育、家庭、异动与薪资摘要。
  6. +
  7. 批量导入使用右上角“批量导入”;导出会沿用当前筛选条件。
  8. +
+
+ 员工花名册 +
员工花名册:筛选、分页、档案、编辑、删除与批量导入导出入口集中展示。
+
+
+ +
+

04职级报销标准(多个项目)

+

每个职级可以配置多个报销项目。项目名称、标准金额、计量单位和适用说明分别保存,员工可在个人薪资页面查看。

+
    +
  1. 进入“组织架构 → 职级职等”。
  2. +
  3. 在目标职级的行尾点击“报销标准”。
  4. +
  5. 点击“添加报销项目”,例如市内交通、差旅住宿、通讯补贴。
  6. +
  7. 填写标准金额和计量单位,例如 1200 / 元/月、650 / 元/晚。
  8. +
  9. 点击“保存标准”。保存后,列表中的“报销项目”数量立即更新。
  10. +
+
校验规则:同一职级下的项目名称不能重复;金额不能为负数;只有拥有“职级编辑”权限的账号可以保存,拥有只读权限的角色可以查看。
+
+ 职级列表 +
职级列表新增“报销项目”数量列,行尾提供独立配置入口。
+
+
+ 职级多个报销项目配置 +
报销标准抽屉:一个职级可维护任意多个项目,支持逐项删除和说明维护。
+
+
+ +
+

05薪资、福利与招聘

+

月度算薪

+
    +
  1. 进入“薪资管理 → 月度算薪”,新建算薪批次并选择计薪期间。
  2. +
  3. 核对名单,录入考勤或手工工资项后执行一键算薪。
  4. +
  5. 完成内部审核,再执行发放和工资条发布。
  6. +
  7. 员工登录后在“工资 / 我的工资条”查看已发布数据。
  8. +
+
+ 月度算薪 +
薪资批次从草稿、计算、审核、发放到工资条发布形成闭环。
+
+

福利与参保

+

参保方案、参保登记、福利项目、福利发放和假期管理都在“福利保险”模块。员工 H5 可查看五险一金、年度福利和假期余额。

+
+ 福利保险 +
福利保险模块按角色授权;普通员工只读自己的参保与福利数据。
+
+

招聘管理

+

从招聘职位、候选人库、招聘看板到 Offer 与入职,系统保留阶段流转和审批链;Offer 转档案时会继承部门、职位、职级与月薪。

+
+ +
+

06角色、菜单与数据范围

+

系统以角色权限与数据范围共同控制页面和接口。菜单可见不代表可以越权读取其他部门或员工的数据。

+
+
all

集团全局数据,适用于超级管理员及明确授权的 HR 负责人。

+
dept_tree / dept

只可查看本部门或本部门及下级员工,适用于主管和专员。

+
self

只能查看本人的工资条、假期、合同和档案,普通员工账号默认使用该范围。

+
+
+ 角色权限 +
角色权限页:权限点、数据范围和用户分配统一维护。
+
+
+ +
+

07员工 Web 自助(与 H5 菜单一致)

+

普通员工在桌面浏览器登录后,左侧菜单固定为“首页、请假、工资、福利、我的”,与 H5 底部导航完全一致。

+
+
功能同源

Web 与 H5 复用同一套业务组件和接口,避免两端菜单、字段和校验规则不一致。

+
管理角色不受影响

HR、主管等管理账号仍按授权显示管理模块;自己的员工自助菜单保持可访问。

+
+
+ 员工 Web 自助首页 +
普通员工 Web 首页:顶部为个人指标,左侧菜单与 H5 五个主菜单同名同序。
+
+
+ 员工 Web 我的 +
“我的”页面展示个人基础信息、合同、证明、消息与资料变更申请。
+
+
+ +
+

08个人档案修改审核

+

员工修改个人档案必须经过审核。提交后不会立即写回员工档案,只有 HR 通过后才会生效。

+
    +
  1. 员工进入“我的 → 我的信息”,点击“修改资料”。
  2. +
  3. 修改手机号、邮箱、住址、紧急联系人、籍贯或婚姻状况等允许自助维护的字段。
  4. +
  5. 填写变更原因,点击“提交审核”。
  6. +
  7. 在“变更申请”中查看待审核、已通过、已驳回状态;待审核状态可以撤回。
  8. +
  9. HR 在“人事档案 → 人事异动 → 资料变更”或 H5 审批中心审核。
  10. +
  11. 审批通过后,系统按“审核前 → 审核后”写回档案,并向申请人发送结果通知。
  12. +
+
安全规则:旧版“直接保存”按钮已移除;旧版 PATCH 接口也只生成审批单,不能绕过审核写档案。工号、姓名、身份证、部门、职位、职级、状态和入职日期不允许员工自助修改。
+
+ 个人档案提交审核 +
员工编辑界面仅保留“提交审核”,页面明确提示审核通过后才会写入档案。
+
+
+ +
+

09员工 H5 自助

+

手机浏览器自动进入 H5。底部导航为“首页、请假、工资、福利、我的”,适合随时查看工资、提交申请和完成审批。

+
+
+ H5 首页 +
H5 首页:最新工资、假期额度、快捷入口与合同提醒。
+
+
+ H5 我的 +
H5 我的:个人档案、合同与薪资、证明申请和消息通知。
+
+
+

常用操作

+
+
请假

选择假期类型、日期和时段,填写事由;需要证明的假种必须上传附件。

+
工资条

按年度和季度筛选,展开查看收入、扣款、个税和五险一金明细。

+
证明申请

选择在职、收入、离职等证明类型并填写用途,提交后跟踪办理状态。

+
+
+ +
+

10审批中心

+

有审批权限的账号会看到自己数据范围内的待办。普通员工只能查看自己的申请进度,不能审批自己的申请。

+
    +
  1. 打开 H5“审批中心”,或在 Web 端进入“人事档案 → 人事异动”。
  2. +
  3. 按待审批、已通过、已驳回筛选,并按请假、异动、调薪、资料变更分类。
  4. +
  5. 核对申请人、变更内容和原因,填写意见后通过或驳回。
  6. +
  7. 审批结果会同步到员工端和首页待办计数。
  8. +
+
+ H5 审批中心 +
H5 审批中心:分类与计数同源,资料变更展示员工提交的字段与内容。
+
+
+ +
+

11全功能验收清单

+

建议上线前按下表完成一次全链路回归;本次交付已按同一范围执行自动化测试与真实浏览器验收。

+ + + + + + + + + + + + + + + + +
验收项检查内容预期结果状态
设备识别桌面、手机浏览器分别登录桌面进入 Web,手机进入 H5通过
菜单一致性普通员工 Web 与 H5 菜单名称、顺序、权限均为首页、请假、工资、福利、我的通过
职级报销新增、修改、删除多个报销项目保存成功并正确回显数量和明细通过
标准校验重复项目、负数金额、只读权限保存分别返回校验失败或 403通过
档案审核员工提交 → 审核前查档案 → HR 通过审核前不变,通过后才写入新值通过
绕过防护调用旧 PATCH 入口直接改档案仅生成待审申请,不回写档案通过
权限边界不同角色访问菜单和接口权限与数据范围一致,无越权通过
核心业务入职、合同、参保、算薪、请假、福利、招聘主流程可完整闭环通过
数据隐私员工访问他人工资条/档案返回 403 或 404通过
帮助中心Web 顶栏、用户菜单、H5 我的均可打开本手册通过
+
+ +
+

12常见问题

+
+ 为什么员工登录后进入了 H5? +

系统检测到手机浏览器 UA,或“窄视口 + 粗指针”的移动设备特征。桌面浏览器会自动进入 Web 工作台。

+
+
+ 为什么左侧没有某个管理菜单? +

菜单由角色权限实时计算。请让管理员在“系统管理 → 角色权限”中检查权限点与数据范围。

+
+
+ 修改资料后为什么还没生效? +

这是正常的审核机制。到“变更申请”查看状态;只有 HR 审核通过后才会写回个人档案。

+
+
+ 职级报销标准为什么保存失败? +

检查项目名称是否重复、金额是否为非负数,以及当前账号是否具有“职级编辑”权限。

+
+
+ 为什么审批中心只看到部分员工? +

审批列表按当前账号的数据范围裁剪。部门主管只能审批本部门及下级员工;集团 HR 可按全部范围审批。

+
+
+ +
UNIS HRMS · 全功能使用手册 · 2026-10-20
+
+
+ + diff --git a/web/src/App.tsx b/web/src/App.tsx index bb369b7..e317013 100644 --- a/web/src/App.tsx +++ b/web/src/App.tsx @@ -3,10 +3,12 @@ import { lazy } from 'react' import { Navigate, Route, Routes, useLocation, useNavigate } from 'react-router-dom' import AdminLayout from './layouts/AdminLayout' import MobileLayout from './layouts/MobileLayout' +import { entryPath } from './lib/mode' import { useAuth } from './store/auth' import Login from './pages/Login' const Dashboard = lazy(() => import('./pages/Dashboard')) const AccountSettings = lazy(() => import('./pages/account/Settings')) +const Help = lazy(() => import('./pages/Help')) const EmployeeList = lazy(() => import('./pages/employees/EmployeeList')) const EmployeeDetail = lazy(() => import('./pages/employees/EmployeeDetail')) @@ -51,51 +53,15 @@ const MLeave = lazy(() => import('./pages/mobile/MLeave')) const MPayslips = lazy(() => import('./pages/mobile/MPayslips')) const MBenefits = lazy(() => import('./pages/mobile/MBenefits')) const MProfile = lazy(() => import('./pages/mobile/MProfile')) +const MTasks = lazy(() => import('./pages/mobile/MTasks')) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +// 员工自助 · Web 工作台版页面(与 /m/* 的 H5 页面一一对应,见 src/self/manifest.ts) +const SelfLeave = lazy(() => import('./pages/self/Leave')) +const SelfPayslips = lazy(() => import('./pages/self/Payslips')) +const SelfBenefits = lazy(() => import('./pages/self/Benefits')) +const SelfApprovals = lazy(() => import('./pages/self/Approvals')) +const SelfTasks = lazy(() => import('./pages/self/Tasks')) +const SelfProfile = lazy(() => import('./pages/self/Profile')) function RequireAuth({ children }: { children: React.ReactNode }) { const token = useAuth((s) => s.token) @@ -104,6 +70,15 @@ function RequireAuth({ children }: { children: React.ReactNode }) { return <>{children} } +/** + * 根路径落地页:登录前收藏的 `/`、退出后又回到 `/` 的都走这里。 + * 口径与登录成功完全一致(显式偏好 > 设备判断),避免出现「登录进 Web、 + * 刷新一下又被丢进 H5」这种两条判定路径不一致的问题。 + */ +function RootRedirect() { + return +} + function NotFound() { const nav = useNavigate() return ( @@ -129,8 +104,21 @@ export default function App() { } > - } /> + } /> } /> + } /> + {/* + 员工自助:Web 工作台版。路由与 H5 的 /m/* 一一对应(见 src/self/manifest.ts), + 两侧读同一批 /self/* 接口、同一份 queryKey,模块名称/顺序/权限完全一致。 + 不再用 WebSelfFrame 把 H5 页面塞进手机框里 —— 那是「Web 和 H5 不一致」的根源。 + */} + } /> + } /> + } /> + } /> + } /> + } /> + } /> {/* 个人设置:不属于业务菜单,入口在侧栏底部用户胶囊,任何人可访问 */} } /> @@ -188,6 +176,7 @@ export default function App() { } /> } /> } /> + } /> } /> diff --git a/web/src/api/resources.ts b/web/src/api/resources.ts index aaa13ca..6e068a2 100644 --- a/web/src/api/resources.ts +++ b/web/src/api/resources.ts @@ -217,6 +217,39 @@ export const documentDef: ResourceDef = { ], } +export const profileRequestDef: ResourceDef = { + key: 'profile-request', + path: '/employee-profile-requests', + label: '资料变更申请', + perm: 'employee:change', + readonly: true, + noSearch: true, + create: false, + update: false, + remove: false, + orderBy: 'id', + order: 'desc', + filters: [ + col('status', '审批状态', { type: 'tag', options: [ + { label: '待审核', value: 'pending' }, + { label: '已通过', value: 'approved' }, + { label: '已驳回', value: 'rejected' }, + ] }), + col('employee_id', '员工', { type: 'options', source: '/employees/options', filterOn: 'employee_name' }), + ], + columns: [ + col('employee_name', '员工', { width: 110 }), + col('department_name', '部门', { width: 140 }), + col('changes', '变更内容(审核前 → 审核后)', { type: 'json', width: 320 }), + col('reason', '变更原因', { width: 200 }), + col('status', '状态', { type: 'tag', width: 100, options: APPROVAL_STATUS_OPTIONS }), + col('approver_name', '审核人', { width: 100 }), + col('comment', '审核意见', { width: 180 }), + col('created_at', '提交时间', { type: 'datetime', width: 160 }), + col('approved_at', '审核时间', { type: 'datetime', width: 160 }), + ], +} + export const adjustmentDef: ResourceDef = { key: 'adjustment', path: '/salary-adjustments', @@ -322,6 +355,10 @@ export const jobLevelDef: ResourceDef = { col('name', '职级', { width: 160, required: true }), col('code', '编码', { width: 140 }), col('grade', '职等', { type: 'number', width: 100 }), + col('expense_standard_count', '报销项目', { + width: 110, + render: (v: number) => `${v ?? 0} 项`, + }), col('sort', '排序', { type: 'number', width: 90 }), col('is_active', '启用', { type: 'switch', width: 90 }), col('remark', '备注', { width: 240 }), diff --git a/web/src/api/routePerms.ts b/web/src/api/routePerms.ts index b1deed4..d2540f5 100644 --- a/web/src/api/routePerms.ts +++ b/web/src/api/routePerms.ts @@ -20,6 +20,12 @@ export const ROUTE_PERMS: Record = { '/employees/documents': ['employee:document:read'], // 证明开具 '/org/departments': ['org:department:read'], // 部门结构 '/org/job-levels': ['org:joblevel:read'], // 职级职等 + '/self/leave': ['selfservice:leave:read'], // 员工自助 + '/self/payslips': ['selfservice:payslip:read'], + '/self/benefits': ['selfservice:benefit:read'], + '/self/profile': ['selfservice:profile:read'], + '/self/approvals': ['selfservice:approval:read'], + '/self/tasks': ['selfservice:task:read'], '/org/positions': ['org:position:read'], // 职位管理 '/payroll/batches': ['payroll:batch:read'], // 月度算薪 '/payroll/items': ['payroll:item:read'], // 薪资项目 diff --git a/web/src/api/self.ts b/web/src/api/self.ts new file mode 100644 index 0000000..eacad91 --- /dev/null +++ b/web/src/api/self.ts @@ -0,0 +1,255 @@ +/** + * 员工自助数据层 —— Web 工作台与 H5 自助端共用同一套端点、queryKey 与 hooks。 + * + * 为什么单独一层: + * 两端读取的是完全相同的 13 个 `/self/*` 接口。以前 H5 页面里各写各的 queryKey, + * Web 首页又另起一个 `['self','home']`,结果「H5 提交请假 → Web 首页还显示旧额度」, + * 或者反过来。键统一之后两个外壳共享同一份缓存,任何一端写完两端同时刷新。 + * + * 注意:queryKey 与历史 H5 页面保持逐字一致(`['self-home']` 等), + * 改动这里必须同时改 `invalidateQueries` 的调用方。 + */ +import { useMutation, useQuery, useQueryClient, type QueryClient } from '@tanstack/react-query' +import { del, get, getQuiet, post, upload } from './http' + +/** 自助接口路径表:页面里不再出现裸字符串,避免拼错与两端漂移 */ +export const SELF = { + home: '/self/home', + profile: '/self/profile', + profileRequests: '/self/profile-requests', + payslips: '/self/payslips', + salaryStandard: '/self/salary-standard', + insurance: '/self/insurance', + benefits: '/self/benefits', + leaveOptions: '/self/leave/options', + leave: '/self/leave', + documents: '/self/documents', + tasks: '/self/tasks', + notifications: '/self/notifications', + announcements: '/self/announcements', + approvals: '/self/approvals', + docDict: '/common/dict/doc_type', +} as const + +export const SELF_KEYS = { + home: ['self-home'], + profile: ['self-profile'], + payslips: (year: number) => ['self-payslips', year], + payslip: (id: number) => ['self-payslip', id], + salaryStandard: ['self-salary-standard'], + insurance: ['self-insurance'], + benefits: ['self-benefits'], + leaveOptions: ['self-leave-options'], + leave: (status = '') => ['self-leave', status], + documents: ['self-documents'], + tasks: ['self-tasks'], + notifications: ['self-notifications'], + announcements: ['self-announcements'], + approvals: (status = 'pending', type = '') => ['self-approvals', status, type], + docDict: ['dict', 'doc_type'], +} as const + +/** 个人数据变化不频繁,30s 内复用,避免来回切页时反复打接口 */ +const STALE = 30_000 + +/* ------------------------------------------------------------------ 查询 -- */ +export const useSelfHome = () => + useQuery({ queryKey: SELF_KEYS.home, queryFn: () => get(SELF.home), staleTime: STALE }) + +export const useSelfProfile = () => + useQuery({ queryKey: SELF_KEYS.profile, queryFn: () => get(SELF.profile), staleTime: STALE }) + +export const useSelfLeaveOptions = () => + useQuery({ queryKey: SELF_KEYS.leaveOptions, queryFn: () => get(SELF.leaveOptions), staleTime: STALE }) + +export const useSelfLeave = (status = '') => + useQuery({ + queryKey: SELF_KEYS.leave(status), + queryFn: () => get(SELF.leave, { status: status || undefined, page: 1, page_size: 50 }), + staleTime: STALE, + }) + +export const useSelfPayslips = (year: number) => + useQuery({ queryKey: SELF_KEYS.payslips(year), queryFn: () => get(SELF.payslips, { year }), staleTime: STALE }) + +export const useSelfPayslip = (id: number | null, enabled = true) => + useQuery({ + queryKey: SELF_KEYS.payslip(id ?? 0), + queryFn: () => get(`${SELF.payslips}/${id}`), + enabled: enabled && id != null, + staleTime: STALE, + }) + +export const useSelfSalaryStandard = () => + useQuery({ queryKey: SELF_KEYS.salaryStandard, queryFn: () => get(SELF.salaryStandard), staleTime: STALE }) + +export const useSelfInsurance = () => + useQuery({ queryKey: SELF_KEYS.insurance, queryFn: () => get(SELF.insurance), staleTime: STALE }) + +export const useSelfBenefits = () => + useQuery({ queryKey: SELF_KEYS.benefits, queryFn: () => get(SELF.benefits), staleTime: STALE }) + +export const useSelfDocuments = () => + useQuery({ queryKey: SELF_KEYS.documents, queryFn: () => get(SELF.documents), staleTime: STALE }) + +export const useSelfTasks = () => + useQuery({ queryKey: SELF_KEYS.tasks, queryFn: () => get(SELF.tasks), staleTime: STALE }) + +export const useSelfNotifications = (pageSize = 50) => + useQuery({ + queryKey: SELF_KEYS.notifications, + queryFn: () => get(SELF.notifications, { page: 1, page_size: pageSize }), + staleTime: STALE, + }) + +export const useSelfAnnouncements = () => + useQuery({ queryKey: SELF_KEYS.announcements, queryFn: () => get(SELF.announcements), staleTime: STALE }) + +export const useSelfApprovals = (status = 'pending', type = '') => + useQuery({ + queryKey: SELF_KEYS.approvals(status, type), + queryFn: () => get(SELF.approvals, { status, type: type || undefined, limit: 100 }), + staleTime: STALE, + }) + +export const useDocTypeDict = () => + useQuery({ queryKey: SELF_KEYS.docDict, queryFn: () => get(SELF.docDict), staleTime: 5 * 60_000 }) + +/* ------------------------------------------------------------------ 变更 -- */ +/** 请假提交 / 撤销后需要一起失效的查询(额度、记录、首页三处都要新) */ +export function invalidateSelf(qc: QueryClient, scope: 'leave' | 'profile' | 'task' | 'approval' | 'doc' | 'all' = 'all') { + const hit = (keys: readonly any[]) => qc.invalidateQueries({ queryKey: keys as any[] }) + hit(SELF_KEYS.home) + if (scope === 'leave' || scope === 'all') { + qc.invalidateQueries({ queryKey: ['self-leave'] }) + hit(SELF_KEYS.leaveOptions) + } + if (scope === 'profile' || scope === 'all') { + hit(SELF_KEYS.profile) + hit(SELF_KEYS.salaryStandard) + } + if (scope === 'approval' || scope === 'all') qc.invalidateQueries({ queryKey: ['self-approvals'] }) + if (scope === 'task' || scope === 'all') { + hit(SELF_KEYS.tasks) + hit(SELF_KEYS.notifications) + } + if (scope === 'doc' || scope === 'all') hit(SELF_KEYS.documents) +} + +/** 提交请假申请 */ +export function useLeaveApply(onDone?: () => void) { + const qc = useQueryClient() + return useMutation({ + mutationFn: (payload: { + leave_type_id: number + start_date: string + end_date: string + period: string + reason: string + days: number + attachment_id?: number + }) => post(SELF.leave, payload), + onSuccess: () => { + invalidateSelf(qc, 'leave') + onDone?.() + }, + }) +} + +export const useLeaveCancel = () => { + const qc = useQueryClient() + return useMutation({ + mutationFn: (id: number) => del(`${SELF.leave}/${id}`), + onSuccess: () => invalidateSelf(qc, 'leave'), + }) +} + +export const useUploadLeaveCertificate = () => + useMutation({ + mutationFn: (file: File) => + upload<{ id: number; name: string }>('/common/upload', file, { biz_type: 'leave_certificate' }), + }) + +export const useProfileRequest = (onDone?: () => void) => { + const qc = useQueryClient() + return useMutation({ + mutationFn: (payload: { changes: Record; reason?: string }) => + post(SELF.profileRequests, payload), + onSuccess: () => { + invalidateSelf(qc, 'profile') + onDone?.() + }, + }) +} + +export const useProfileRequestCancel = (onDone?: () => void) => { + const qc = useQueryClient() + return useMutation({ + mutationFn: (id: number) => del(`${SELF.profileRequests}/${id}`), + onSuccess: () => { + invalidateSelf(qc, 'profile') + onDone?.() + }, + }) +} + +export const useDocumentApply = (onDone?: () => void) => { + const qc = useQueryClient() + return useMutation({ + mutationFn: (payload: { doc_type: string; purpose?: string }) => post(SELF.documents, payload), + onSuccess: () => { + qc.invalidateQueries({ queryKey: SELF_KEYS.documents }) + qc.invalidateQueries({ queryKey: SELF_KEYS.home }) + onDone?.() + }, + }) +} + +export const useTaskDone = () => { + const qc = useQueryClient() + return useMutation({ + mutationFn: (id: number) => post(`${SELF.tasks}/${id}/done`), + onSuccess: () => invalidateSelf(qc, 'task'), + }) +} + +export const useNotificationsRead = () => { + const qc = useQueryClient() + return useMutation({ + mutationFn: (ids?: number[]) => post(SELF.notifications + '/read', { ids: ids ?? [] }), + onSuccess: () => { + qc.invalidateQueries({ queryKey: SELF_KEYS.notifications }) + qc.invalidateQueries({ queryKey: SELF_KEYS.home }) + qc.invalidateQueries({ queryKey: ['unread-count'] }) + }, + }) +} + +export interface DecidePayload { + type: string + id: number + status: 'approved' | 'rejected' + comment?: string +} + +export const useApprovalDecide = () => { + const qc = useQueryClient() + return useMutation({ + mutationFn: (v: DecidePayload) => + post(`${SELF.approvals}/${v.type}/${v.id}/decide`, { status: v.status, comment: v.comment || undefined }), + onSuccess: () => invalidateSelf(qc, 'approval'), + }) +} + +/** 顶部铃铛用的静默版:拿不到消息时不弹错误提示 */ +export const useQuietNotifications = (pageSize = 8) => + useQuery({ + queryKey: ['my-notices'], + queryFn: async () => { + try { + return await getQuiet(SELF.notifications, { page: 1, page_size: pageSize }) + } catch { + return { items: [] as any[] } + } + }, + }) diff --git a/web/src/components/Cell.tsx b/web/src/components/Cell.tsx index 57134f9..b136351 100644 --- a/web/src/components/Cell.tsx +++ b/web/src/components/Cell.tsx @@ -34,6 +34,11 @@ function parseMaybeJson(value: any) { const kvText = (key: string, v: any) => { if (typeof v === 'boolean') return v ? '是' : '否' + if (v != null && typeof v === 'object' && "after" in v) { + const before = v.before == null || v.before === "" ? "未填写" : String(v.before) + const after = v.after == null || v.after === "" ? "未填写" : String(v.after) + return `${before} → ${after}` + } if (v != null && typeof v === 'object') return JSON.stringify(v) // 异动快照里的 status 一定是「在职状态」,快照即历史,不能直出英文码 if (key === 'status') return optLabel(EMP_STATUS_OPTIONS, v) diff --git a/web/src/components/icons.tsx b/web/src/components/icons.tsx index c5c8a46..09313bb 100644 --- a/web/src/components/icons.tsx +++ b/web/src/components/icons.tsx @@ -2,6 +2,7 @@ import { AccountBookOutlined, ApartmentOutlined, AppstoreOutlined, + AuditOutlined, BarChartOutlined, BookOutlined, CalculatorOutlined, @@ -56,6 +57,7 @@ export type IconComp = ComponentType<{ style?: React.CSSProperties; className?: */ const REGISTRY: Record = { AccountBookOutlined, + AuditOutlined, ApartmentOutlined, AppstoreOutlined, BarChartOutlined, @@ -117,10 +119,16 @@ export function IconNode({ name, style }: { name?: string | null; style?: React. } /** H5 底部导航用的是关键词而非 antd 图标名 */ +/** + * H5 底部导航图标表。key 取自 `src/self/manifest.ts` 的 `mobileIcon` 字段, + * 后端 MOBILE_MENU_TREE 的 icon 列同名 —— 新增自助模块时三处一起加。 + */ export const MOBILE_ICONS: Record = { home: HomeOutlined, calendar: CalendarOutlined, gold: AccountBookOutlined, gift: GiftOutlined, + check: AuditOutlined, + task: ScheduleOutlined, user: UserOutlined, } diff --git a/web/src/layouts/AdminLayout.tsx b/web/src/layouts/AdminLayout.tsx index cfbbb6e..318ae2f 100644 --- a/web/src/layouts/AdminLayout.tsx +++ b/web/src/layouts/AdminLayout.tsx @@ -4,10 +4,12 @@ import { MenuFoldOutlined, MenuUnfoldOutlined, MobileOutlined, + QuestionCircleOutlined, ReloadOutlined, SearchOutlined, SettingOutlined, UpOutlined, + UserOutlined, } from '@ant-design/icons' import { useQuery } from '@tanstack/react-query' import { @@ -35,6 +37,8 @@ import { PageFallback } from '../components/PageFallback' import { get, getQuiet, post } from '../api/http' import { requiredPermsOf } from '../api/routePerms' import { IconNode, icon } from '../components/icons' +import { oppositePath, setModePref } from '../lib/mode' +import { moduleOfPath, pathOf, toWebPath } from '../self/manifest' import { useAuth } from '../store/auth' const { Sider, Header, Content } = Layout @@ -48,10 +52,19 @@ const isNarrow = () => window.innerWidth < 992 // 后台路由的一级前缀。用来区分「路径本身不存在」(交给路由 404) // 与「路径存在但当前角色没有菜单权限」(渲染 403)。 // /account(个人设置)刻意不列在这里:它由侧栏用户胶囊进入,不需要菜单权限。 -const KNOWN_PREFIXES = ['/dashboard', '/employees', '/recruitment', '/payroll', '/benefits', '/org', '/system'] +const KNOWN_PREFIXES = [ + '/dashboard', + '/self', + '/employees', + '/recruitment', + '/payroll', + '/benefits', + '/org', + '/system', +] // 不在后端菜单里的页面(个人设置):面包屑拿不到菜单名,这里补一份标题 -const OFF_MENU_TITLES: Record = { '/account': '个人设置' } +const OFF_MENU_TITLES: Record = { '/account': '个人设置', '/help': '使用手册' } interface FlatItem { key: string @@ -82,6 +95,7 @@ export default function AdminLayout() { const me = useAuth((s) => s.me) const logout = useAuth((s) => s.logout) const reload = useAuth((s) => s.reload) + const hasPerm = useAuth((s) => s.hasPerm) const [collapsed, setCollapsed] = useState(() => isNarrow() || localStorage.getItem(COLLAPSE_KEY) === '1') const prefCollapsed = useRef(localStorage.getItem(COLLAPSE_KEY) === '1') const seenMobile = useRef(null) @@ -144,18 +158,25 @@ export default function AdminLayout() { // 菜单由后端按角色权限下发,是「能打开哪个页面」的唯一口径。 // 直接敲地址 / 收藏旧链接时也要挡住,否则会出现空表格 + 一点就 403 的按钮。 + // + // 例外:员工自助的 7 个模块按「权限」判定而不是按菜单。原因是 H5 底部导航只放得下 + // 5 项,审批 / 待办 两端都只能从首页宫格进入,因此它们不在任何一份菜单树里; + // 若继续按菜单判定,这两个页面在 Web 端会莫名其妙 403,两端行为就不一致了。 + const selfModule = useMemo(() => moduleOfPath(loc.pathname), [loc.pathname]) const allowed = useMemo(() => { const p = loc.pathname + if (selfModule) return hasPerm(selfModule.perm) if (!KNOWN_PREFIXES.some((k) => p === k || p.startsWith(k + '/'))) return true return items.some((i) => p === i.key || p.startsWith(i.key + '/')) - }, [items, loc.pathname]) + }, [items, loc.pathname, selfModule, hasPerm]) // 403 页要把「缺哪个权限码」讲清楚,省掉一轮截图来回 const needPerms = useMemo(() => (allowed ? [] : requiredPermsOf(loc.pathname)), [allowed, loc.pathname]) const matched = items.filter((i) => i.key.includes(loc.pathname) || loc.pathname.startsWith(i.key)) const current = [...matched].sort((a, b) => b.key.length - a.key.length)[0] - const crumb = current?.label || OFF_MENU_TITLES[loc.pathname] + // 审批 / 待办 不在后端菜单里,面包屑从 manifest 取模块名,保证与页面标题一致 + const crumb = current?.label || OFF_MENU_TITLES[loc.pathname] || selfModule?.name // 胶囊两行:上行姓名、下行角色(多角色用「、」连接,没分配时给占位文案别留空行)。 // 超管这类「姓名和角色同名」的账号,下行换成登录账号,免得上下两行一模一样。 const userName = me?.user?.name || me?.user?.username || '' @@ -230,11 +251,15 @@ export default function AdminLayout() { 靠原生 title 补提示(没有 hover 展开的地方,光看图例得认得出) */ items: collapsed ? [ + { key: 'self', icon: , label: '', title: '我的自助', onClick: () => nav(pathOf('home', 'web')) }, { key: 'settings', icon: , label: '', title: '个人设置', onClick: () => nav('/account') }, + { key: 'help', icon: , label: '', title: '使用手册', onClick: () => nav('/help') }, { key: 'logout', icon: , label: '', title: '退出登录', danger: true, onClick: doLogout }, ] : [ + { key: 'self', icon: , label: '我的自助', onClick: () => nav(pathOf('home', 'web')) }, { key: 'settings', icon: , label: '个人设置', onClick: () => nav('/account') }, + { key: 'help', icon: , label: '使用手册', onClick: () => nav('/help') }, { key: 'logout', icon: , label: '退出登录', danger: true, onClick: doLogout }, ], }} @@ -277,6 +302,14 @@ export default function AdminLayout() { + + } diff --git a/web/src/lib/device.ts b/web/src/lib/device.ts new file mode 100644 index 0000000..62bde48 --- /dev/null +++ b/web/src/lib/device.ts @@ -0,0 +1,14 @@ +/** + * 浏览器端设备判断的唯一口径。 + * + * 先用 UA 覆盖手机/平板,再用「窄视口 + 粗指针」覆盖响应式桌面浏览器和设备模拟器。 + * 不依赖登录角色:桌面浏览器进入管理端外壳,手机浏览器进入 H5 外壳。 + */ +export function isMobileBrowser(): boolean { + if (typeof window === 'undefined') return false + const ua = navigator.userAgent || '' + const mobileUa = /Android|iPhone|iPad|iPod|Mobile|HarmonyOS|MicroMessenger/i.test(ua) + const narrow = window.matchMedia?.('(max-width: 768px)').matches ?? window.innerWidth <= 768 + const coarse = window.matchMedia?.('(pointer: coarse)').matches ?? false + return mobileUa || (narrow && coarse) +} diff --git a/web/src/lib/mode.ts b/web/src/lib/mode.ts new file mode 100644 index 0000000..d3b60a7 --- /dev/null +++ b/web/src/lib/mode.ts @@ -0,0 +1,74 @@ +/** + * 外壳模式(Web 工作台 / H5 自助端)判定的唯一口径。 + * + * 规则,按优先级: + * 1. 用户显式选择过的外壳偏好(localStorage,跨登录态保留); + * 2. 没选过时才按设备判断:手机浏览器 → H5,其余(PC / 平板桌面)→ Web。 + * + * 关键点:**账号不决定外壳**。普通员工在电脑浏览器登录就必须进 Web 工作台, + * 只有他主动点「切到 H5」或本身用手机浏览器时才是 H5。 + * 以前 token 过期、`?redirect=/m`、浏览器记住上次页面都会把员工锁死在 H5, + * 现在这三条统一走 `sanitizeRedirect()` + 可切换的偏好,随时能回 Web。 + */ +import { isMobileBrowser } from './device' +import { toMobilePath, toWebPath } from '../self/manifest' + +export type ShellMode = 'web' | 'h5' +export type ModePref = 'auto' | ShellMode + +const KEY = 'unis-hrms-shell-mode' + +/** 用户显式偏好;`auto` 表示跟随设备 */ +export function modePref(): ModePref { + if (typeof window === 'undefined') return 'auto' + const v = window.localStorage?.getItem(KEY) + return v === 'web' || v === 'h5' ? v : 'auto' +} + +export function setModePref(pref: ModePref) { + if (typeof window === 'undefined') return + if (pref === 'auto') window.localStorage?.removeItem(KEY) + else window.localStorage?.setItem(KEY, pref) +} + +/** 纯设备判断(不含用户偏好) */ +export const detectMode = (): ShellMode => (isMobileBrowser() ? 'h5' : 'web') + +/** 当前应使用的外壳 */ +export function currentMode(): ShellMode { + const pref = modePref() + return pref === 'auto' ? detectMode() : pref +} + +export const isWebMode = () => currentMode() === 'web' + +/** 登录成功 / 根路径的落地页:桌面浏览器一律 Web,手机浏览器才 H5 */ +export const entryPath = () => (currentMode() === 'h5' ? '/m' : '/dashboard') + +/** 把路径改写成当前外壳下的等价路径 */ +export const toModePath = (path: string, mode: ShellMode = currentMode()) => + mode === 'h5' ? toMobilePath(path) : toWebPath(path) + +/** + * 校验 `?redirect=` 参数: + * - 只接受站内绝对路径(挡掉 `//evil.com` 这种协议相对地址); + * - 落到与当前外壳不符的路径时,改写成同模块的另一端路径, + * 这样「在手机上过期重登后回 H5」「在电脑上过期重登后回 Web」都成立。 + */ +export function sanitizeRedirect(raw: string | null | undefined, mode: ShellMode = currentMode()): string { + if (!raw) return entryPath() + let target = raw + try { + target = decodeURIComponent(raw) + } catch { + /* 已经是解码后的值 */ + } + if (!target.startsWith('/') || target.startsWith('//') || target.startsWith('/\\')) return entryPath() + return toModePath(target, mode) +} + +/** + * 切到另一个外壳时要落在哪个页面: + * 从 Web 的「我的工资条」切到 H5,应当落在 H5 的工资条,而不是永远回 H5 首页。 + */ +export const oppositePath = (pathname: string, to: ShellMode) => toModePath(pathname, to) diff --git a/web/src/lib/selfLabels.ts b/web/src/lib/selfLabels.ts new file mode 100644 index 0000000..fb96672 --- /dev/null +++ b/web/src/lib/selfLabels.ts @@ -0,0 +1,257 @@ +import { + BENEFIT_CATEGORY_OPTIONS, + CONTRACT_STATUS_OPTIONS, + EMP_STATUS_OPTIONS, + ENROLLMENT_STATUS_OPTIONS, +} from '../api/defs' + +/** + * 员工自助两端的公共字典与格式化小工具。 + * + * Web 桌面页(pages/self)与 H5 页(pages/mobile)必须对同一个状态给出同一个中文与 + * 同一种颜色,否则「已通过 / 已发放」在两个外壳里会长得不一样。 + * 这里集中一份,`pages/mobile/_ui.tsx` 只做 re-export,避免历史 import 断链。 + */ + +/** 金额:¥1,234.00(与 H5 一致,Web 侧表格也用它保证两端字面一致) */ +export const rmb = (v: any) => + `¥${Number(v ?? 0).toLocaleString('zh-CN', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}` + +export const num = (v: any) => String(Number(v ?? 0)) + +/** 取日期部分(后端可能下发 ISO datetime) */ +export const dstr = (v?: string | null) => (v ? String(v).slice(0, 10) : '-') + +/** 取到分钟的时间 */ +export const dtstr = (v?: string | null) => + v ? String(v).slice(0, 16).replace('T', ' ') : '-' + +export const round2 = (v: number) => Math.round(v * 100) / 100 + +/** + * 比例小数 -> 百分比中文:0.07 => 7%,0.095 => 9.5%。 + * 两端必须共用,否则同一个缴存比例在 Web 表格里会露出浮点尾数(7.000000000000001%)。 + */ +export const pct = (v: any) => `${round2(Number(v ?? 0) * 100)}%` + +/** 请假状态:文案与 Web 端「假期管理」表头筛选项一致 */ +export const LEAVE_STATUS: Record = { + pending: { text: '审批中', color: '#f59e0b' }, + approved: { text: '已通过', color: '#16a34a' }, + rejected: { text: '已驳回', color: '#ef4444' }, + cancelled: { text: '已撤销', color: '#98a2b3' }, +} + +export const LEAVE_STATUS_TEXT: Record = Object.fromEntries( + Object.entries(LEAVE_STATUS).map(([k, v]) => [k, v.text]), +) + +/** 请假时段:后端历史上有 am/pm 与 morning/afternoon 两套写法,全部兼容 */ +export const PERIOD_TEXT: Record = { + all: '全天', + full: '全天', + am: '上午', + morning: '上午', + pm: '下午', + afternoon: '下午', +} + +/** 时段选项(表单与筛选用,两端同一份) */ +export const PERIOD_OPTIONS = [ + { value: 'full', label: '全天' }, + { value: 'morning', label: '上午' }, + { value: 'afternoon', label: '下午' }, +] + +/** 请假状态筛选(首项固定「全部」,与 Web 表头筛选同一交互语义) */ +export const LEAVE_FILTERS = [ + { key: '', label: '全部' }, + { key: 'pending', label: '审批中' }, + { key: 'approved', label: '已通过' }, + { key: 'rejected', label: '已驳回' }, + { key: 'cancelled', label: '已撤销' }, +] + +export const TASK_LEVEL: Record = { + high: { text: '加急', color: '#ef4444' }, + urgent: { text: '加急', color: '#ef4444' }, + normal: { text: '常规', color: '#2f54eb' }, + low: { text: '较低', color: '#98a2b3' }, +} + +/** 工资条状态:approved = 已核算待发放,语义上仍是「进行中」,颜色跟随 pending */ +export const PAYSLIP_STATUS_TEXT: Record = { + published: '已发放', + paid: '已发放', + approved: '待发放', + calculated: '计算中', + draft: '草稿', +} +export const PAYSLIP_STATUS_TONE: Record = { approved: 'pending' } + +/** 季度筛选(工资条只有「已发布」一种终态,按季度切分更有意义) */ +export const QUARTERS: Array<{ key: string; label: string; months: number[] }> = [ + { key: '', label: '全年', months: [] }, + { key: '1', label: '一季度', months: [1, 2, 3] }, + { key: '2', label: '二季度', months: [4, 5, 6] }, + { key: '3', label: '三季度', months: [7, 8, 9] }, + { key: '4', label: '四季度', months: [10, 11, 12] }, +] + +/** 福利类别中文:直接取管理端 `api/defs` 的选项表,避免自助端自己翻译一遍 */ +export const BENEFIT_CATEGORY_TEXT: Record = Object.fromEntries( + BENEFIT_CATEGORY_OPTIONS.map((x) => [x.value, x.label]), +) + +/** 福利发放记录状态 */ +export const BENEFIT_RECORD_STATUS: Record = { + pending: { text: '待发放', color: '#f59e0b' }, + approved: { text: '已审批', color: '#2f54eb' }, + paid: { text: '已到账', color: '#16a34a' }, + void: { text: '已作废', color: '#98a2b3' }, +} + +export const BENEFIT_ICONS: Record = { + meal: '🍱', + transport: '🚕', + telecom: '📱', + holiday: '🎁', + health: '🏥', + cash: '💵', + gift: '🎀', +} + +/** 审批中心:申请类型元信息(图标 + 颜色 + 中文),两端共用 */ +export const APPROVAL_TYPES = [ + { key: '', label: '全部' }, + { key: 'leave', label: '请假' }, + { key: 'change', label: '异动' }, + { key: 'adjustment', label: '调薪' }, + { key: 'profile', label: '资料变更' }, + { key: 'document', label: '证明' }, + { key: 'offer', label: 'Offer' }, +] + +export const APPROVAL_META: Record = { + leave: { icon: '🗓', color: '#2f54eb', text: '请假' }, + change: { icon: '🔀', color: '#7c3aed', text: '异动' }, + adjustment: { icon: '📈', color: '#16a34a', text: '调薪' }, + profile: { icon: '📝', color: '#0ea5e9', text: '资料' }, + document: { icon: '📄', color: '#f59e0b', text: '证明' }, + offer: { icon: '🎯', color: '#ec4899', text: 'Offer' }, +} + +export const APPROVAL_STATUS: Record = { + pending: { text: '待审批', color: '#f59e0b' }, + approved: { text: '已通过', color: '#16a34a' }, + sent: { text: '已发送', color: '#2f54eb' }, + accepted: { text: '已接受', color: '#16a34a' }, + rejected: { text: '已驳回', color: '#ef4444' }, +} + +/** 资料变更申请状态 */ +export const PROFILE_REQ_STATUS: Record = { + pending: { text: '待 HR 审核', color: '#f59e0b' }, + approved: { text: '已通过', color: '#16a34a' }, + rejected: { text: '已驳回', color: '#ef4444' }, + cancelled: { text: '已撤回', color: '#98a2b3' }, +} + +/** 允许员工自助发起变更的字段中文名 */ +export const PROFILE_FIELD_LABELS: Record = { + phone: '手机号', + email: '邮箱', + address: '住址', + emergency_contact: '紧急联系人', + emergency_phone: '紧急联系电话', + native_place: '籍贯', + marital_status: '婚姻状况', + avatar: '头像', + remark: '备注', +} + +/** 薪资项目编码 → 中文(后端下发 code,展示要有名字) */ +export const SALARY_ITEM_LABELS: Record = { + base_salary: '基本工资', + perf_salary: '绩效工资', + post_salary: '岗位工资', + year_bonus: '年终奖', + overtime_pay: '加班费', + meal_allowance: '餐补', + transport_allowance: '交通补贴', + telecom_allowance: '通讯补贴', + housing_allowance: '住房补贴', + other_allowance: '其他补贴', + absence_deduction: '缺勤扣款', + other_deduction: '其他扣款', +} + +/** 在职状态文案:取自后台同一份 EMP_STATUS_OPTIONS,两端与员工管理列表口径一致 */ +export const EMP_STATUS_TEXT: Record = { + ...Object.fromEntries(EMP_STATUS_OPTIONS.map((o) => [o.value, o.label])), + terminated: '已辞退', +} +export const EMP_STATUS_COLOR: Record = { + active: '#16a34a', + probation: '#f59e0b', + leave: '#98a2b3', + resigned: '#98a2b3', + terminated: '#ef4444', +} + +/** + * 劳动合同状态中文直接取自 `api/defs` 的 CONTRACT_STATUS_OPTIONS —— 与后台「合同管理」 + * 表头同一份字典,避免自助端漏掉 renewed 这类取值而直接显示英文。 + * pending 是自助端独有的「待签署」语义,后台选项里没有,单独补上。 + */ +export const CONTRACT_STATUS_TEXT: Record = { + ...Object.fromEntries(CONTRACT_STATUS_OPTIONS.map((o) => [o.value, o.label])), + pending: '待签署', +} +export const CONTRACT_STATUS_COLOR: Record = { + active: '#16a34a', + expired: '#ef4444', + renewed: '#2f54eb', + terminated: '#98a2b3', + pending: '#f59e0b', +} + +/** 证明开具状态 */ +export const DOC_STATUS_TEXT: Record = { + pending: '办理中', + approved: '已开具', + rejected: '已驳回', + cancelled: '已撤销', +} +export const DOC_STATUS_COLOR: Record = { + pending: '#f59e0b', + approved: '#16a34a', + rejected: '#ef4444', + cancelled: '#98a2b3', +} + +/** 参保状态:中文取自 ENROLLMENT_STATUS_OPTIONS;pending 是自助端独有的「待生效」 */ +export const INSURANCE_STATUS_TEXT: Record = { + ...Object.fromEntries(ENROLLMENT_STATUS_OPTIONS.map((o) => [o.value, o.label])), + paused: '已停缴', + pending: '待生效', +} +export const INSURANCE_STATUS_COLOR: Record = { + active: '#16a34a', + paused: '#f59e0b', + pending: '#f59e0b', + stopped: '#98a2b3', +} + +/** 假期天数计算:同一天选半天记 0.5,跨度按自然日 +1(与 H5 完全同一算法) */ +export function leaveDays(start: string, end: string, period: string): number { + const a = new Date(start).getTime() + const b = new Date(end).getTime() + if (!a || !b || b < a) return 0 + let d = Math.round((b - a) / 86400000) + 1 + if (start === end && period !== 'full') d = 0.5 + return d +} + +/** 假期额度单位中文 */ +export const unitText = (unit?: string) => (unit === 'hour' ? '小时' : '天') diff --git a/web/src/pages/Help.tsx b/web/src/pages/Help.tsx new file mode 100644 index 0000000..f10147d --- /dev/null +++ b/web/src/pages/Help.tsx @@ -0,0 +1,17 @@ +/** 帮助中心:在系统内展示可独立访问、可打印的 HTML 使用手册。 */ +export default function Help() { + return ( +