# 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，前端可暂不实现）
- 考勤规则配置实体
- 部门结构实体
> 后端暂未提供接口，仅模型存在