financial_system/frontend

企业薪酬管理系统前端

这是 Financial_System 项目的前端子工程，使用 Vue3、Vite、TypeScript、Pinia 和 Vue Router 开发，用于对接后端 FastAPI 工资计算服务。

技术栈

• Vue3：页面和组件开发。
• Vite：本地开发服务和生产构建。
• TypeScript：接口类型、状态类型和页面逻辑类型约束。
• Pinia：登录用户、菜单和权限状态管理。
• Vue Router：页面路由和权限守卫。
• @lucide/vue：按钮、菜单和状态图标。

目录结构

目录	说明
src/api/	后端接口封装、请求工具、接口类型、文件下载逻辑。
src/stores/	Pinia 状态管理，目前主要是登录态、菜单、权限和主题色。
src/router/	路由配置和登录/权限守卫。
src/components/	通用布局、侧边栏、顶部栏、统计卡片和工资结果表格。
src/views/	登录、工作台、实时考勤、月度核算、工资计算、计算记录、提成管理、统计报表、组织架构、员工维护、薪资维护、规则配置、用户管理、操作日志页面。
src/assets/	全局样式和 UI 设计变量。

本地启动

先启动后端服务：

cd /Users/jiaolongyan/PycharmProjects/牛牛小屋/Financial_System
/Users/jiaolongyan/miniconda3/envs/Financial_System/bin/python main.py

再启动前端服务：

cd /Users/jiaolongyan/PycharmProjects/牛牛小屋/Financial_System/frontend
npm install
npm run dev

默认访问地址：

http://127.0.0.1:5173/

后端接口代理

开发环境下，vite.config.ts 已将以下路径代理到后端：

/api    -> http://127.0.0.1:8000
/health -> http://127.0.0.1:8000
/static -> http://127.0.0.1:8000

因此前端代码中可以直接请求 /api/auth/login、/api/attendance/realtime/today、/api/payroll/monthly/runs、/api/payroll/excel 等路径，头像静态资源也可以直接访问 /static/uploads/avatars/...。

如果部署时前端和后端不在同一个域名，可以复制 .env.example 为 .env，并设置：

VITE_API_BASE_URL=http://127.0.0.1:8000
VITE_DEV_PROXY_TARGET=http://127.0.0.1:8000

如果后端 8000 端口被旧进程占用，新后端自动启动到了 8001，需要把开发代理改成：

VITE_DEV_PROXY_TARGET=http://127.0.0.1:8001

修改 .env 后需要重启前端开发服务。

默认账号

后端首次启动会初始化超级管理员：

用户名：admin
密码：Admin@123456
角色：superuser

登录成功后，前端会根据后端返回的 menus 渲染左侧菜单，根据 permissions 控制按钮和操作权限。

页面说明

页面	路由	说明
登录	/login	用户登录入口。
工作台	/dashboard	展示最近计算任务、统计卡片和趋势面板。
实时考勤	/attendance/realtime	查看今日打卡、迟到、缺卡、请假、加班和本月薪资预估，可同步钉钉刷新。
月度核算	/payroll/monthly	按工资月份完成 Excel 导入、钉钉同步计算、异常处理、锁定和导出。
工资计算	/payroll	支持 Excel 导入和钉钉实时计算。
计算记录	/payroll/jobs	支持按任务编号查询已落库工资结果。
提成管理	/payroll/commissions	支持手工维护提成和 Excel 批量导入。
统计报表	/reports	查看工资汇总、部门工资成本和考勤工时统计。
组织架构	/system/organization	维护部门上下级和部门下的岗位。
员工维护	/system/employees	维护员工编号、姓名、钉钉用户ID、部门、岗位和状态。
薪资维护	/system/salary-profiles	维护包月、计时、计件、试用期工资规则和三类加班费单价。
规则配置	/system/configs	维护考勤扣款、加班取整、请假关键字和默认加班单价。
用户管理	/system/users	超级用户创建账号、查看账号和角色权限。
操作日志	/system/operation-logs	支持按操作人、模块、动作、状态和关键字查看系统操作记录。

组织架构页面中的岗位编码由后端自动生成，新增或编辑岗位时不需要手工输入；员工维护页面会按所选部门联动展示该部门下的岗位，员工编号由后端按 ZA0001、ZA0002 规则自动生成。

个性化与个人资料

实时考勤中的薪资金额是过程预估，最终工资以月度核算锁定结果为准。月度核算锁定后，本月工资不能重新计算，只保留导出。

顶部栏提供两个常用入口：

• 调色盘按钮：切换主题色，支持深海蓝、专业蓝、翡翠绿、勃艮第，选择结果保存在浏览器本地。
• 头像/姓名区域：打开个人资料弹窗，可修改显示名称、邮箱、手机号、部门、职位，并上传头像。

头像上传接口为 /api/auth/me/avatar，后端会保存到 storage.avatar_dir，默认是：

static/uploads/avatars

权限说明

角色	可见菜单和操作
superuser	拥有全部菜单和全部操作权限。
manager	可进行实时考勤同步、月度核算、工资计算、组织架构、员工维护、薪资维护、提成管理、规则配置、报表查看和操作日志查看。
viewer	可查看实时考勤、计算记录、下载结果和统计报表。

构建

cd /Users/jiaolongyan/PycharmProjects/牛牛小屋/Financial_System/frontend
npm run build

构建产物生成在 dist/，该目录已加入项目 .gitignore。

常见问题

1. 登录失败：确认后端已启动，并且 /health 返回 {"status":"ok"}。
2. 前端请求 401：重新登录，或确认当前用户拥有对应权限。
3. 下载结果失败：确认任务已生成 output_file，且后端 outputs/ 中文件未被删除。
4. 端口被占用：可临时执行 npm run dev -- --port 5174 更换端口。