Initial commit
This commit is contained in:
ChuXun
288
FRONTEND_HANDOFF.md
Normal file
288
FRONTEND_HANDOFF.md
Normal file
@@ -0,0 +1,288 @@
|
||||
# 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，前端可暂不实现）
|
||||
- 考勤规则配置实体
|
||||
- 部门结构实体
|
||||
> 后端暂未提供接口，仅模型存在
|
||||
Reference in New Issue
Block a user