# 开发任务规划（基于 serverDesign.md）

> 项目当前状态：仅有 `ServerApplication.java` 和 `application.yaml`，其余代码均需新建。

---

## 阶段一：公共基础设施层

| # | 任务 | 涉及文件 | 说明 |
|---|------|---------|------|
| 1.1 | 统一响应类 | `common/R.java` | `code` + `message` + `data`，提供 `ok/error` 静态工厂 |
| 1.2 | 错误码枚举 | `common/ResultCode.java` | 定义业务状态码常量 |
| 1.3 | 业务异常 | `common/BusinessException.java` | 继承 `RuntimeException`，携带 `code` |
| 1.4 | 全局异常处理 | `config/GlobalExceptionHandler.java` | 覆盖文档第 3.1.3 节列出的所有异常类型 |
| 1.5 | 跨域配置 | `config/CorsConfig.java` | 允许所有来源（开发阶段），`allowCredentials(true)` |
| 1.6 | 拦截器注册 | `config/WebMvcConfig.java` | 注册 AuthInterceptor 和 AdminInterceptor |
| 1.7 | MD5 密码工具 | `config/PasswordConfig.java` | MD5 加盐加密工具 |
| 1.8 | 分页 VO | `common/PageVo.java` | `data` + `total` + `pageNum` + `pageSize` |
| 1.9 | 分页工具 | `util/PageUtil.java` | 封装 LIMIT 分页逻辑（`Supplier` 方式） |
| 1.10 | 登录拦截器 | `interceptor/AuthInterceptor.java` | 从 Session 获取用户，抛 `UnauthorizedException` |
| 1.11 | 管理员拦截器 | `interceptor/AdminInterceptor.java` | 校验 `role=admin`，抛 `ForbiddenException` |

---

## 阶段二：实体类（Entity）

| # | 任务 | 文件 | 关键字段 |
|---|------|------|---------|
| 2.1 | 用户实体 | `entity/User.java` | id, account, username, password, email, phone, avatar, role, enable, createdAt, updatedAt |
| 2.2 | 宠物实体 | `entity/Pet.java` | id, userId, name, species, breed, gender, birthDate, weight, avatar, remark, createdAt, updatedAt |
| 2.3 | 疫苗记录 | `entity/VaccinationRecord.java` | id, petId, vaccineName, vaccineDate, hospital, doctor, remark, createdAt |
| 2.4 | 驱虫记录 | `entity/DewormingRecord.java` | id, petId, dewormingName, dewormingDate, hospital, doctor, remark, createdAt |
| 2.5 | 套餐实体 | `entity/ServicePackage.java` | id, name, type(BOARDING/GROOMING), price, duration, description, isActive, createdAt, updatedAt |
| 2.6 | 寄养房型 | `entity/BoardingRoom.java` | id, roomName, roomType, capacity, pricePerDay, isActive, description, createdAt, updatedAt |
| 2.7 | 房态记录 | `entity/BoardingRoomStatus.java` | id, roomId, date, status(AVAILABLE/OCCUPIED/MAINTENANCE), appointmentId, createdAt |
| 2.8 | 预约订单 | `entity/Appointment.java` | id, userId, petId, packageId, roomId, type, status, startDate, endDate, totalPrice, deposit, depositPaid, cancelReason, rejectReason, remark, createdAt, updatedAt |
| 2.9 | 排班 | `entity/Schedule.java` | id, employeeName, workDate, timeSlot, remark, createdAt |

---

## 阶段三：Mapper 接口 + MyBatis XML

| # | 任务 | Mapper 接口 | XML 文件 | 关键 SQL |
|---|------|------------|----------|---------|
| 3.1 | 用户 Mapper | `mapper/UserMapper.java` | `UserMapper.xml` | insert/selectById/selectByAccount/update/delete, selectByPage, countByCondition |
| 3.2 | 宠物 Mapper | `mapper/PetMapper.java` | `PetMapper.xml` | insert/selectById/selectByUserId/update/delete |
| 3.3 | 疫苗 Mapper | `mapper/VaccinationRecordMapper.java` | `VaccinationRecordMapper.xml` | insert/selectByPetId/deleteByPetId |
| 3.4 | 驱虫 Mapper | `mapper/DewormingRecordMapper.java` | `DewormingRecordMapper.xml` | insert/selectByPetId/deleteByPetId |
| 3.5 | 套餐 Mapper | `mapper/PackageMapper.java` | `PackageMapper.xml` | insert/selectById/selectByType/update/isActive 逻辑删除 |
| 3.6 | 房型 Mapper | `mapper/BoardingRoomMapper.java` | `BoardingRoomMapper.xml` | insert/selectById/selectActive/update |
| 3.7 | 房态 Mapper | `mapper/BoardingRoomStatusMapper.java` | `BoardingRoomStatusMapper.xml` | insertOrUpdate(ON DUPLICATE KEY)/selectByRoomAndDate/deleteByAppointment |
| 3.8 | 预约 Mapper | `mapper/AppointmentMapper.java` | `AppointmentMapper.xml` | insert/selectById/selectByUserId/selectAllByPage, updateStatus/updateDepositPaid |
| 3.9 | 排班 Mapper | `mapper/ScheduleMapper.java` | `ScheduleMapper.xml` | insert/selectByMonth/deleteById, checkConflict |

---

## 阶段四：DTO（请求参数）

| # | 任务 | 文件 |
|---|------|------|
| 4.1 | 认证 DTO | `dto/auth/LoginDto.java`, `RegisterDto.java` |
| 4.2 | 用户 DTO | `dto/user/UserDto.java`, `UpdateUserPasswordDto.java`, `UpdateUserAvatarDto.java`, `UpdateUserStatusDto.java` |
| 4.3 | 宠物 DTO | `dto/pet/PetDto.java`, `VaccinationDto.java`, `DewormingDto.java` |
| 4.4 | 预约 DTO | `dto/appointment/AppointmentDto.java`, `ReviewDto.java`, `HandleCancelDto.java` |
| 4.5 | 套餐 DTO | `dto/servicePackage/PackageDto.java` |
| 4.6 | 房态 DTO | `dto/room/RoomStatusDto.java`, `QueryByPageParams.java` |
| 4.7 | 排班 DTO | `dto/schedule/ScheduleDto.java` |

---

## 阶段五：VO（返回结果）

| # | 任务 | 文件 |
|---|------|------|
| 5.1 | 用户 VO | `vo/user/UserVo.java` |
| 5.2 | 宠物 VO | `vo/pet/PetVo.java`, `VaccinationVo.java`, `DewormingVo.java` |
| 5.3 | 预约 VO | `vo/appointment/AppointmentVo.java` |
| 5.4 | 套餐 VO | `vo/servicePackage/PackageVo.java` |
| 5.5 | 房型/VO | `vo/room/BoardingRoomVo.java`, `RoomStatusVo.java` |
| 5.6 | 排班 VO | `vo/schedule/ScheduleVo.java` |
| 5.7 | 管理员用户详情 VO | `vo/user/AdminUserDetailVo.java` |

---

## 阶段六：Service 层（接口 + 实现）

| # | 任务 | 接口 | 实现 | 关键逻辑 |
|---|------|------|------|---------|
| 6.1 | 认证服务 | `AuthService` | `AuthServiceImpl` | 注册(唯一性校验+MD5+session)、登录(密码校验+session)、logout |
| 6.2 | 用户服务 | `UserService` | `UserServiceImpl` | 分页、CRUD、updatePassword/updateStatus/updateAvatar |
| 6.3 | 宠物服务 | `PetService` | `PetServiceImpl` | 当前用户宠物列表、CRUD（校验归属）、疫苗/驱虫子记录 |
| 6.4 | 预约服务 | `AppointmentService` | `AppointmentServiceImpl` | 创建(校验套餐/宠物/房态+计算价格)、支付定金、取消、审核、处理取消（含事务） |
| 6.5 | 房型服务 | `BoardingRoomService` | `BoardingRoomServiceImpl` | 房型列表(active)、按月房态查询、手动修改房态 |
| 6.6 | 套餐服务 | `PackageService` | `PackageServiceImpl` | 按类型查询(active)、CRUD（逻辑删除） |
| 6.7 | 排班服务 | `ScheduleService` | `ScheduleServiceImpl` | 按月查询、新增(冲突校验)、删除 |

---

## 阶段七：Controller 层

| # | 任务 | 文件 | 说明 |
|---|------|------|------|
| 7.1 | 认证控制器 | `controller/AuthController.java` | `/auth/register`, `/auth/login`, `/auth/logout` |
| 7.2 | 用户控制器 | `controller/UserController.java` | `/user/**` 分页/CRUD/状态/密码/头像 |
| 7.3 | 宠物控制器 | `controller/PetController.java` | `/pets/**` 宠物 CRUD + 疫苗/驱虫子接口 |
| 7.4 | 预约控制器 | `controller/AppointmentController.java` | `/appointments/**` 创建/列表/详情/取消/支付 |
| 7.5 | 房型控制器 | `controller/BoardingRoomController.java` | `/boarding-rooms/**` 房型列表 + 房态查询 |
| 7.6 | 套餐控制器 | `controller/PackageController.java` | `/packages/**` 列表 + 详情 |
| 7.7 | 排班视图 | `controller/ScheduleController.java` | `/schedules/**`（排班查询，用户侧） |
| 7.8 | 管理员-预约 | `controller/admin/AdminAppointmentController.java` | `/admin/appointments` 审核 + 处理取消 |
| 7.9 | 管理员-房态 | `controller/admin/AdminBoardingRoomController.java` | `/admin/boarding-rooms` 修改房态 |
| 7.10 | 管理员-排班 | `controller/admin/AdminScheduleController.java` | `/admin/schedules` 排班 CRUD |
| 7.11 | 管理员-套餐 | `controller/admin/AdminPackageController.java` | `/admin/packages` 套餐 CRUD |
| 7.12 | 管理员-用户 | `controller/admin/AdminUserController.java` | `/admin/users` 用户列表 + 详情(含宠物档案) |

---

## 阶段八：测试

| # | 任务 | 说明 |
|---|------|------|
| 8.1 | Service 单元测试 | 核心逻辑（AuthService、AppointmentService 等）JUnit 5 + Mockito |
| 8.2 | 构建验证 | `./mvnw clean package` 确保编译通过 |

---

## 阶段九：最终检查

- [x] 所有 Controller 添加 `@Operation` OpenAPI 注解
- [x] 所有 DTO 添加 `@Valid` 校验注解
- [x] 所有 Service 方法添加 `@Transactional(rollbackFor = Exception.class)`（写操作）
- [ ] 所有 Entity 字段添加 inline 注释（待补充）
- [x] 全局异常处理覆盖所有预期异常
- [x] 验证分页接口实现正确
- [x] `application.yaml` 与文档第 8 节一致

## 设计变更记录

1. `entity/Package.java` → `entity/ServicePackage.java`（`Package` 与 `java.lang.Package` 冲突）
2. `dto/package/` → `dto/servicePackage/`（`package` 为 Java 关键字，不可用作包名）
3. `vo/package/` → `vo/servicePackage/`（同上）