# 下一步开发工作规划

> 基于 `detailDesign.md` 与当前项目实际代码的差异分析

## 项目当前状态

**代码骨架已全部完成：** 基础设施、Entity、DTO、VO、Mapper/XML、Service、Controller 共计 ~70 个 Java 文件已全部创建。

**可编译启动：** `./mvnw spring-boot:run` 可正常启动，但存在以下待办事项。

---

## 一、确认存在的 Bug（需优先修复）

### 1.1 取消订单逻辑错误（严重）

**问题位置：** `service/impl/AppointmentServiceImpl.java:119-130` + `mapper/AppointmentMapper.xml:56-58`

| 当前状态 | 设计文档要求 | 当前代码行为 |
|---------|-------------|-------------|
| PENDING | 直接 `status='CANCELLED'` | 错误地设置为 `CANCEL_REQUESTED` |
| CONFIRMED | 设置为 `status='CANCEL_REQUESTED'` | 正确（但需要与服务端逻辑解耦） |

**根本原因：** `AppointmentMapper.xml` 中 `updateCancelReason` 硬编码了 `status = 'CANCEL_REQUESTED'`，导致 PENDING 和 CONFIRMED 两种场景都进入等待审核状态。

**修复方案：**
1. 删除 `updateCancelReason` 方法（或改为仅更新 `cancel_reason` 字段，不修改 status）
2. `AppointmentServiceImpl.cancel()` 中根据当前 status 分别处理：
   - PENDING → `updateStatus(id, "CANCELLED")` + 更新 `cancel_reason`（房间状态未锁定，无需释放）
   - CONFIRMED → `updateStatus(id, "CANCEL_REQUESTED")` + 更新 `cancel_reason`

---

## 二、遗漏的管理后台房间管理功能（较大工作量）

设计文档 `6.4.2` 节定义了 8 个管理员房间接口，当前仅实现了 1 个（`PUT .../status`）。

### 2.1 需新建的 DTO

| 文件 | 字段 |
|------|------|
| `dto/room/BatchRoomStatusDto.java` | startDate(LocalDate), endDate(LocalDate), status(String) |
| `dto/room/BoardingRoomCreateDto.java` | roomName(String), roomType(String), capacity(Integer), pricePerDay(BigDecimal), description(String) |

### 2.2 需新建的 VO

| 文件 | 字段 |
|------|------|
| `vo/room/TodayStatusVo.java` | totalRooms(int), availableCount(int), occupiedCount(int), maintenanceCount(int), todayGuests(List\<TodayGuestVo\>) |
| `vo/room/TodayGuestVo.java` | roomName(String), petName(String), ownerName(String) |

### 2.3 需补充的 Mapper 层

**`mapper/BoardingRoomMapper.java`** 新增方法：

| 方法 | 用途 |
|------|------|
| `selectAll()` | 查询所有房型（含已禁用） |
| `deleteById(Long id)` | 逻辑删除（`UPDATE ... SET is_active = 0`） |

**`mapper/BoardingRoomMapper.xml`** 新增对应的 SQL 语句。

### 2.4 需补充的 Service 层

**`service/BoardingRoomService.java`** 接口新增：

| 方法 | 说明 |
|------|------|
| `listAllRooms()` | 获取所有房型（含已禁用） |
| `createRoom(BoardingRoomCreateDto dto)` | 新增房型 |
| `updateRoom(Long id, BoardingRoomCreateDto dto)` | 修改房型信息 |
| `deleteRoom(Long id)` | 逻辑删除房型 |
| `batchUpdateStatus(Long roomId, BatchRoomStatusDto dto)` | 批量修改日期范围房态（@Transactional，范围 ≤31 天） |
| `getTodayStatus()` | 今日所有房型入住概览 |

**`service/impl/BoardingRoomServiceImpl.java`** 实现上述方法。

> `getTodayStatus()` 算法要点：
> 1. 查询 `boarding_room_status` 中今天日期的所有记录
> 2. 统计 AVAILABLE/OCCUPIED/MAINTENANCE 数量
> 3. 关联查询 appointment + pet + user 获取今日入住宠物列表

### 2.5 需补充的 Controller 层

**`controller/admin/AdminBoardingRoomController.java`** 新增 7 个接口：

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/admin/boarding-rooms` | 获取所有房型 |
| POST | `/admin/boarding-rooms` | 新增房型 |
| PUT | `/admin/boarding-rooms/{id}` | 修改房型 |
| DELETE | `/admin/boarding-rooms/{id}` | 删除房型 |
| GET | `/admin/boarding-rooms/{id}/status` | 获取房态（管理员） |
| PUT | `/admin/boarding-rooms/{roomId}/status/batch` | 批量修改房态 |
| GET | `/admin/boarding-rooms/today-status` | 今日入住概览 |

> 原有 `PUT /{roomId}/status` 保留不动。

---

## 三、实体类字段注释（中等工作量）

设计规范要求 _"每个 Entity 字段必须有 inline 注释"_。当前所有 9 个 Entity 均缺少字段注释。

**涉及文件：**
- `entity/User.java` — 12 个字段
- `entity/Pet.java` — 13 个字段
- `entity/VaccinationRecord.java` — 6 个字段
- `entity/DewormingRecord.java` — 6 个字段
- `entity/ServicePackage.java` — 10 个字段
- `entity/BoardingRoom.java` — 8 个字段
- `entity/BoardingRoomStatus.java` — 5 个字段
- `entity/Appointment.java` — 16 个字段
- `entity/Schedule.java` — 5 个字段

每个字段添加 `// 说明` 行尾注释，参考 `detailDesign.md` §3.1 中的字段描述。

---

## 四、补充测试（中等工作量）

当前 `src/test/` 为空，需要按设计文档第 9 章建立测试：

### 4.1 工具类测试
- `util/PageUtil` — 分页逻辑
- `config/PasswordConfig` — MD5 加密/匹配

### 4.2 Service 单元测试（JUnit 5 + Mockito）
- `AuthServiceImplTest` — 注册唯一性校验、登录密码校验、session 操作
- `AppointmentServiceImplTest` — 创建预约（寄养/洗护）、房间可用性校验、状态转换、取消逻辑、审核逻辑

### 4.3 Controller 集成测试（MockMvc）
- 认证接口：注册/登录/登出/未登录返回 401
- 预约接口：完整流程（创建→支付→审核→取消→处理取消）
- 权限校验：普通用户访问 /admin/** 返回 403

### 4.4 Mapper 测试（可选）
- SQL 语句正确性校验（可在集成测试中覆盖）

---

## 五、构建验证

```bash
./mvnw clean package
```

确保编译通过、测试通过。

---

## 六、优先级与执行顺序建议

| 优先级 | 任务 | 预估工时 | 说明 |
|--------|------|---------|------|
| P0 | 修复取消订单 Bug | ~30min | 影响核心业务流程 |
| P0 | 补充 AdminBoardingRoom 管理功能 | ~3h | 设计文档承诺的功能缺失较大 |
| P1 | 补充 Entity 字段注释 | ~30min | 编码规范要求 |
| P1 | 构建验证 + 测试 | ~4h | 保证质量、可维护性 |

---

## 七、当前代码中值得注意的设计决策

| 项目 | 说明 |
|------|------|
| Session 认证 | 基于服务端 HttpSession + Cookie，未使用 JWT |
| 上下文路径 | `server.servlet.context-path: /`（无 `/api` 前缀，与设计文档描述一致） |
| 密码加密 | MD5 + 固定盐值 "PetService2026!@#" |
| 房间状态 upsert | 使用 `INSERT ... ON DUPLICATE KEY UPDATE` |
| 预约状态机 | PENDING → CONFIRMED → CANCEL_REQUESTED → CANCELLED / COMPLETED |
| 管理员拦截 | AuthInterceptor 先校验登录，AdminInterceptor 后校验角色 |