forked from jiaoly/financial_system
146 lines
6.0 KiB
Markdown
146 lines
6.0 KiB
Markdown
# 企业薪酬管理系统前端
|
||
|
||
这是 `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 设计变量。 |
|
||
|
||
## 本地启动
|
||
|
||
先启动后端服务：
|
||
|
||
```bash
|
||
cd /Users/jiaolongyan/PycharmProjects/牛牛小屋/Financial_System
|
||
/Users/jiaolongyan/miniconda3/envs/Financial_System/bin/python main.py
|
||
```
|
||
|
||
再启动前端服务：
|
||
|
||
```bash
|
||
cd /Users/jiaolongyan/PycharmProjects/牛牛小屋/Financial_System/frontend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
默认访问地址：
|
||
|
||
```text
|
||
http://127.0.0.1:5173/
|
||
```
|
||
|
||
## 后端接口代理
|
||
|
||
开发环境下，`vite.config.ts` 已将以下路径代理到后端：
|
||
|
||
```text
|
||
/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`，并设置：
|
||
|
||
```env
|
||
VITE_API_BASE_URL=http://127.0.0.1:8000
|
||
VITE_DEV_PROXY_TARGET=http://127.0.0.1:8000
|
||
```
|
||
|
||
如果后端 `8000` 端口被旧进程占用，新后端自动启动到了 `8001`，需要把开发代理改成：
|
||
|
||
```env
|
||
VITE_DEV_PROXY_TARGET=http://127.0.0.1:8001
|
||
```
|
||
|
||
修改 `.env` 后需要重启前端开发服务。
|
||
|
||
## 默认账号
|
||
|
||
后端首次启动会初始化超级管理员：
|
||
|
||
```text
|
||
用户名：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`，默认是：
|
||
|
||
```text
|
||
static/uploads/avatars
|
||
```
|
||
|
||
## 权限说明
|
||
|
||
| 角色 | 可见菜单和操作 |
|
||
| --- | --- |
|
||
| `superuser` | 拥有全部菜单和全部操作权限。 |
|
||
| `manager` | 可进行实时考勤同步、月度核算、工资计算、组织架构、员工维护、薪资维护、提成管理、规则配置、报表查看和操作日志查看。 |
|
||
| `viewer` | 可查看实时考勤、计算记录、下载结果和统计报表。 |
|
||
|
||
## 构建
|
||
|
||
```bash
|
||
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` 更换端口。
|