# 企业薪酬管理系统前端

这是 `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/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` | 展示最近计算任务、统计卡片和趋势面板。 |
| 工资计算 | `/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` 更换端口。