289 lines
5.2 KiB
Markdown
289 lines
5.2 KiB
Markdown
# Smart Office 前端交付文档（给另一个模型使用）
|
||
|
||
> 目标：在没有上下文的情况下，仅凭本文档生成**与当前后端完全兼容**的前端界面。
|
||
> 技术栈：React 18 + Vite
|
||
|
||
---
|
||
|
||
## 1. 项目概览
|
||
- 系统名称：Smart Office（智能办公管理系统）
|
||
- 当前版本：v1.0（MVP）
|
||
- 已实现模块：登录/权限、考勤打卡、请假审批、通知、用户管理
|
||
- 角色：`ADMIN` / `MANAGER` / `EMPLOYEE`
|
||
|
||
### 默认账号
|
||
- admin / admin123
|
||
- manager / manager123
|
||
- employee / employee123
|
||
|
||
### 目标页面
|
||
- 登录
|
||
- 概览（Dashboard）
|
||
- 考勤（打卡、个人记录）
|
||
- 请假（提交、我的请假）
|
||
- 审批（经理/管理员可见）
|
||
- 用户管理（管理员/经理可见，创建仅管理员）
|
||
- 通知
|
||
|
||
---
|
||
|
||
## 2. 技术与接入约定
|
||
- API Base：`/api/v1`
|
||
- 本地后端：`http://localhost:8080`（如在 8081，可通过 `VITE_PROXY_TARGET` 或 `VITE_API_BASE` 配置）
|
||
- Token：JWT，存储在 LocalStorage，Header：`Authorization: Bearer <token>`
|
||
- 后端响应结构统一：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "OK",
|
||
"data": {},
|
||
"timestamp": "2026-01-28T11:31:58.291Z"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 权限规则（前端必须遵守）
|
||
- `ADMIN`：全部页面、可创建用户/修改状态、可审批
|
||
- `MANAGER`：可查看用户列表、审批
|
||
- `EMPLOYEE`：仅个人考勤、请假、通知、概览
|
||
|
||
UI 级别必须隐藏不可访问页面，但后端也会校验权限。
|
||
|
||
---
|
||
|
||
## 4. 路由建议
|
||
- `/login` 登录页
|
||
- `/` 概览
|
||
- `/attendance` 考勤
|
||
- `/leave` 请假
|
||
- `/approvals` 审批（ADMIN/MANAGER）
|
||
- `/users` 用户（ADMIN/MANAGER）
|
||
- `/notifications` 通知
|
||
|
||
---
|
||
|
||
## 5. 后端接口文档（完整）
|
||
|
||
### 5.1 Auth
|
||
#### 登录
|
||
- **POST** `/auth/login`
|
||
```json
|
||
{ "username": "admin", "password": "admin123" }
|
||
```
|
||
响应：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "OK",
|
||
"data": {
|
||
"token": "jwt-token",
|
||
"user": {
|
||
"id": 1,
|
||
"username": "admin",
|
||
"fullName": "管理员",
|
||
"role": "ADMIN",
|
||
"status": "ACTIVE",
|
||
"lastLoginAt": "2026-01-28T11:31:58.275Z"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 注册
|
||
- **POST** `/auth/register`
|
||
```json
|
||
{
|
||
"username": "u1",
|
||
"password": "u1123",
|
||
"fullName": "Test User",
|
||
"email": "u1@example.com",
|
||
"phone": "123456"
|
||
}
|
||
```
|
||
响应：`UserDto`
|
||
|
||
#### 当前用户
|
||
- **GET** `/auth/me`
|
||
- Header：`Authorization`
|
||
- 响应：`UserDto`
|
||
|
||
---
|
||
|
||
### 5.2 用户管理 Users
|
||
> ADMIN/MANAGER 可访问；创建/状态变更仅 ADMIN
|
||
|
||
#### 列表
|
||
- **GET** `/users`
|
||
- 响应：`UserDto[]`
|
||
|
||
#### 详情
|
||
- **GET** `/users/{id}`
|
||
- 响应：`UserDto`
|
||
|
||
#### 创建用户
|
||
- **POST** `/users`
|
||
```json
|
||
{
|
||
"username": "u1",
|
||
"password": "u1123",
|
||
"fullName": "Test User",
|
||
"email": "u1@example.com",
|
||
"phone": "123456",
|
||
"role": "EMPLOYEE"
|
||
}
|
||
```
|
||
|
||
#### 修改状态
|
||
- **PATCH** `/users/{id}/status`
|
||
```json
|
||
{ "status": "ACTIVE" }
|
||
```
|
||
|
||
---
|
||
|
||
### 5.3 考勤 Attendance
|
||
#### 上班打卡
|
||
- **POST** `/attendance/check-in`
|
||
```json
|
||
{ "location": "HQ" }
|
||
```
|
||
|
||
#### 下班签退
|
||
- **POST** `/attendance/check-out`
|
||
|
||
#### 我的考勤记录
|
||
- **GET** `/attendance/me`
|
||
|
||
---
|
||
|
||
### 5.4 请假 Leave Requests
|
||
#### 提交请假
|
||
- **POST** `/leave-requests`
|
||
```json
|
||
{
|
||
"type": "ANNUAL",
|
||
"startTime": "2026-01-29T09:00:00Z",
|
||
"endTime": "2026-01-29T18:00:00Z",
|
||
"reason": "Family matters"
|
||
}
|
||
```
|
||
|
||
#### 我的请假
|
||
- **GET** `/leave-requests/my`
|
||
|
||
#### 待审批列表（ADMIN/MANAGER）
|
||
- **GET** `/leave-requests/pending`
|
||
|
||
#### 审批通过
|
||
- **POST** `/leave-requests/{id}/approve`
|
||
```json
|
||
{ "note": "Approved" }
|
||
```
|
||
|
||
#### 审批拒绝
|
||
- **POST** `/leave-requests/{id}/reject`
|
||
```json
|
||
{ "note": "Rejected" }
|
||
```
|
||
|
||
---
|
||
|
||
### 5.5 通知 Notifications
|
||
#### 通知列表
|
||
- **GET** `/notifications`
|
||
|
||
#### 标记已读
|
||
- **POST** `/notifications/{id}/read`
|
||
|
||
---
|
||
|
||
## 6. DTO 数据结构
|
||
|
||
### UserDto
|
||
```ts
|
||
{
|
||
id: number
|
||
username: string
|
||
fullName: string
|
||
email?: string
|
||
phone?: string
|
||
role: 'ADMIN' | 'MANAGER' | 'EMPLOYEE'
|
||
status: 'ACTIVE' | 'DISABLED' | 'LOCKED'
|
||
lastLoginAt?: string
|
||
}
|
||
```
|
||
|
||
### AttendanceDto
|
||
```ts
|
||
{
|
||
id: number
|
||
date: string
|
||
checkInTime?: string
|
||
checkOutTime?: string
|
||
workHours: number
|
||
status: string
|
||
location?: string
|
||
}
|
||
```
|
||
|
||
### LeaveDto
|
||
```ts
|
||
{
|
||
id: number
|
||
requester: UserDto
|
||
type: string
|
||
startTime: string
|
||
endTime: string
|
||
reason: string
|
||
status: string
|
||
approver?: UserDto
|
||
decidedAt?: string
|
||
createdAt: string
|
||
}
|
||
```
|
||
|
||
### NotificationDto
|
||
```ts
|
||
{
|
||
id: number
|
||
type: string
|
||
title: string
|
||
content: string
|
||
readAt?: string
|
||
createdAt: string
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 枚举
|
||
- 角色：`ADMIN | MANAGER | EMPLOYEE`
|
||
- 用户状态：`ACTIVE | DISABLED | LOCKED`
|
||
- 请假类型：`ANNUAL | SICK | PERSONAL | MARRIAGE | MATERNITY | BEREAVEMENT`
|
||
|
||
---
|
||
|
||
## 8. 错误码参考
|
||
- 400：参数校验失败
|
||
- 401：未登录 / Token 无效
|
||
- 403：无权限
|
||
- 404：资源不存在
|
||
- 409：冲突（如重复、已处理）
|
||
- 500：服务器异常
|
||
|
||
---
|
||
|
||
## 9. 设计要求（给生成前端用）
|
||
- 必须生成 **企业级、现代、干净** 的 UI
|
||
- 页面需覆盖所有模块，角色权限需隐藏
|
||
- 所有接口调用必须与上述 API 完全一致
|
||
- Token 保存到 LocalStorage，并在每次请求中带上
|
||
|
||
---
|
||
|
||
## 10. v1.1 增量（目前无 API，前端可暂不实现）
|
||
- 考勤规则配置实体
|
||
- 部门结构实体
|
||
> 后端暂未提供接口，仅模型存在
|