CompanyRegister/FRONTEND_HANDOFF.md

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>
• 后端响应结构统一：

{
  "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

{ "username": "admin", "password": "admin123" }

响应：

{
  "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

{
  "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

{
  "username": "u1",
  "password": "u1123",
  "fullName": "Test User",
  "email": "u1@example.com",
  "phone": "123456",
  "role": "EMPLOYEE"
}

修改状态

• PATCH /users/{id}/status

{ "status": "ACTIVE" }

---

5.3 考勤 Attendance

上班打卡

• POST /attendance/check-in

{ "location": "HQ" }

下班签退

• POST /attendance/check-out

我的考勤记录

• GET /attendance/me

---

5.4 请假 Leave Requests

提交请假

• POST /leave-requests

{
  "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

{ "note": "Approved" }

审批拒绝

• POST /leave-requests/{id}/reject

{ "note": "Rejected" }

---

5.5 通知 Notifications

通知列表

• GET /notifications

标记已读

• POST /notifications/{id}/read

---

6. DTO 数据结构

UserDto

{
  id: number
  username: string
  fullName: string
  email?: string
  phone?: string
  role: 'ADMIN' | 'MANAGER' | 'EMPLOYEE'
  status: 'ACTIVE' | 'DISABLED' | 'LOCKED'
  lastLoginAt?: string
}

AttendanceDto

{
  id: number
  date: string
  checkInTime?: string
  checkOutTime?: string
  workHours: number
  status: string
  location?: string
}

LeaveDto

{
  id: number
  requester: UserDto
  type: string
  startTime: string
  endTime: string
  reason: string
  status: string
  approver?: UserDto
  decidedAt?: string
  createdAt: string
}

NotificationDto

{
  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，前端可暂不实现）

• 考勤规则配置实体
• 部门结构实体

后端暂未提供接口，仅模型存在