# 第五阶段：管理员会话管理功能开发方案

## 1. 目标与范围

### 1.1. 目标
为系统管理员提供对充电会话（Charging Sessions）的全面查看、监控和有限管理能力，以确保系统运营的透明度和可控性。

### 1.2. 功能范围
*   **查询与浏览 (Read)**:
    *   分页列出所有充电会话。
    *   支持多种条件筛选（如用户、机器人、车位、状态、时间范围等）。
    *   支持按关键字段排序。
    *   查看单个充电会话的完整详细信息。
*   **更新 (Update)**:
    *   **谨慎引入**。主要考虑场景：对异常会话进行状态纠正（例如，系统未能自动更新的会话，管理员可手动标记为 `ERROR` 或 `CANCELLED_BY_SYSTEM`）。
    *   所有手动更新操作必须记录详细的操作审计日志（操作人、时间、原因、变更前后状态）。
*   **创建 (Create)**:
    *   管理员**不直接创建**充电会话。会话由用户通过前端发起，或由系统在特定业务流程中自动创建。

### 1.3. 非范围
*   自动化的会话处理逻辑（这部分属于核心业务模块，已在第三阶段实现）。
*   复杂的统计报表（可作为后续独立模块）。

## 2. 后端实现 (`springboot-init-main`)

### 2.1. 数据模型 (Entity, VO, DTO)
*   **Entity**: `com.yupi.project.model.entity.ChargingSession` (已存在)
    *   确认所有必要字段已包含，参考 `mqtt_power.sql` 中的 `charging_session` 表。
*   **View Object (VO)**: `com.yupi.project.model.vo.ChargingSessionAdminVO` (如果现有VO不满足，则创建或增强)
    *   在现有 `ChargingSessionVO` 基础上，确保包含以下信息，或提供途径方便前端获取：
        *   `id` (会话ID)
        *   `userId`
        *   `username` (关联查询 `user` 表得到)
        *   `robotId`
        *   `robotUidSnapshot` (来自 `charging_session` 表)
        *   `spotId`
        *   `spotUidSnapshot` (来自 `charging_session` 表)
        *   `status` (会话状态)
        *   `requestTime`, `chargeStartTime`, `chargeEndTime`
        *   `totalDurationSeconds`
        *   `energyConsumedKwh`
        *   `cost`
        *   `paymentStatus`
        *   `errorCode`, `errorMessage`
        *   `relatedRobotTaskId`
        *   `createTime`, `updateTime`
*   **Data Transfer Object (DTO)**:
    *   `com.yupi.project.model.dto.chargingsession.ChargingSessionAdminQueryRequest`: (可基于现有 `PageRequest` 扩展)
        *   分页参数 (`current`, `pageSize`)
        *   筛选条件:
            *   `userId` (Long)
            *   `username` (String, 支持模糊查询)
            *   `robotUid` (String, 支持模糊查询)
            *   `spotUid` (String, 支持模糊查询)
            *   `status` (String, 对应 `ChargingSessionStatusEnum`)
            *   `paymentStatus` (String, 对应 `PaymentStatusEnum`)
            *   `requestTimeStart`, `requestTimeEnd` (Date or String)
            *   `chargeEndTimeStart`, `chargeEndTimeEnd` (Date or String)
            *   `id` (Long, 精确查询会话ID)
        *   排序字段 (`sortField`, 例如 `createTime`, `cost`)
        *   排序顺序 (`sortOrder`, `ascend` 或 `descend`)
    *   `com.yupi.project.model.dto.chargingsession.ChargingSessionAdminUpdateStatusRequest`:
        *   `newStatus` (String, 对应 `ChargingSessionStatusEnum`)
        *   `reason` (String, 管理员操作原因)

### 2.2. Service 层 (`com.yupi.project.service.ChargingSessionService`)
*   **Read (查询)**:
    *   `Page<ChargingSessionAdminVO> pageAdminSessions(ChargingSessionAdminQueryRequest queryRequest)`:
        *   实现复杂条件组合查询、分页和排序。
        *   内部需要调用 `UserMapper` 或 `UserService` 来根据 `userId` 填充 `username` 到 `ChargingSessionAdminVO`。
        *   （此功能可能部分已由现有 `/admin/session/list/page` 接口的 Service 方法覆盖，需检查并增强）。
    *   `ChargingSessionAdminVO getAdminSessionDetailsById(Long sessionId)`:
        *   获取单个会话的详细信息，并转换为 `ChargingSessionAdminVO`。
*   **Update (更新)**:
    *   `boolean adminUpdateSessionStatus(Long sessionId, ChargingSessionStatusEnum newStatus, String reason, Long adminUserId)`:
        *   检查会话是否存在。
        *   校验状态转换的合法性（例如，不能将已完成的会话改回进行中）。
        *   更新会话状态、`update_time`。
        *   记录操作日志（可考虑引入操作日志表或利用现有日志框架）。
        *   `adminUserId` 用于审计。

### 2.3. Controller 层 (`com.yupi.project.controller.ChargingSessionAdminController`)
*   `POST /api/admin/session/list/page`: (已存在，需审视是否需要修改请求体和响应体以满足 `ChargingSessionAdminQueryRequest` 和 `Page<ChargingSessionAdminVO>`)
    *   调用 `chargingSessionService.pageAdminSessions(queryRequest)`。
    *   权限: `@AuthCheck(mustRole = UserConstant.ADMIN_ROLE)`。
*   `GET /api/admin/session/{sessionId}`:
    *   调用 `chargingSessionService.getAdminSessionDetailsById(sessionId)`。
    *   权限: `@AuthCheck(mustRole = UserConstant.ADMIN_ROLE)`。
*   `PUT /api/admin/session/{sessionId}/status`:
    *   请求体: `ChargingSessionAdminUpdateStatusRequest`
    *   调用 `chargingSessionService.adminUpdateSessionStatus(sessionId, newStatus, reason, adminUserId)`。
    *   `adminUserId` 从当前登录用户上下文获取。
    *   权限: `@AuthCheck(mustRole = UserConstant.ADMIN_ROLE)`。

## 3. 前端实现 (`charging_web_app`)

### 3.1. 页面与路由
*   **主页面**: `src/app/(authenticated)/admin/sessions/page.tsx`
    *   此页面已在 `AdminDashboardPage` 中有导航链接，需具体实现。

### 3.2. UI 组件 (Ant Design)
*   `Card`: 用于整体布局和分块。
*   `Form`, `Input`, `Select`, `DatePicker`, `Button`: 用于构建查询筛选表单。
*   `Table`: 用于展示会话列表，支持分页、排序。
*   `Modal`: 用于展示会话详情、执行状态更新操作。
*   `Tag`: 用于美化状态显示。
*   `Tooltip`, `Typography.Text`: 用于辅助信息展示。
*   `Descriptions`: 用于在详情模态框中展示会话信息。
*   `Popconfirm`: 用于删除或敏感操作前的确认。
*   `message`, `notification`: 用于操作结果反馈。

### 3.3. 主要功能实现
*   **列表展示**:
    *   **数据获取**: 调用后端 `/api/admin/session/list/page` 接口。
    *   **列定义**: 参考 `ChargingSessionAdminVO`，合理展示关键信息，例如：会话ID, 用户名, 机器人UID, 车位UID, 请求时间, 开始时间, 结束时间, 总时长, 费用, 会话状态 (Tag), 支付状态 (Tag), 操作。
    *   **分页**: 实现前端分页组件与后端分页数据的同步。
    *   **排序**: 表格列头点击排序，将排序参数传递给后端。
    *   **操作列**:
        *   "详情"按钮：点击打开会话详情模态框。
        *   "修改状态"按钮 (如果实现该功能)：打开状态修改模态框。
*   **查询筛选**:
    *   表单元素对应 `ChargingSessionAdminQueryRequest` 中的筛选字段。
    *   "查询"按钮触发 API 请求，更新表格数据。
    *   "重置"按钮清除筛选条件并重新加载数据。
*   **会话详情 (Modal)**:
    *   调用后端 `/api/admin/session/{sessionId}` 接口获取数据。
    *   使用 `Descriptions` 组件清晰展示所有会话信息。
*   **修改状态 (Modal)** (如果实现):
    *   表单包含可选的新状态和操作原因。
    *   提交时调用后端 `/api/admin/session/{sessionId}/status` 接口。

### 3.4. API 服务层
*   在 `charging_web_app/src/services/` 目录下创建 `sessionAdminService.ts` (或类似名称)。
*   封装对上述后端管理员会话管理 API 的调用函数。
    *   `fetchAdminSessions(query: ChargingSessionAdminQueryRequest): Promise<BaseResponse<Page<ChargingSessionAdminVO>>>`
    *   `fetchAdminSessionDetails(sessionId: number): Promise<BaseResponse<ChargingSessionAdminVO>>`
    *   `updateAdminSessionStatus(sessionId: number, data: ChargingSessionAdminUpdateStatusRequest): Promise<BaseResponse<any>>`

### 3.5. 状态管理 (React Context / Zustand / Redux Toolkit - 根据项目现有方式)
*   管理会话列表数据、加载状态、错误信息。
*   管理分页参数 (`current`, `pageSize`, `total`)。
*   管理筛选表单的条件。
*   管理模态框的显示/隐藏状态及当前操作的会话数据。
*   状态更新操作的业务逻辑和数据一致性。
*   并发操作下的数据准确性（如果适用）。

## 4. 数据库变更
*   当前 `charging_session` 表结构基本满足需求。
*   **可选**: 如果需要详细的管理员操作审计，可以考虑新增一个 `admin_operation_log` 表，记录管理员对会话等关键数据的修改操作。

## 5. 测试要点
*   **后端**:
    *   各 API 接口的参数校验、权限控制。
    *   筛选条件（特别是组合条件和边界值）的正确性。
    *   分页和排序逻辑的正确性。
    *   状态更新操作的业务逻辑和数据一致性。
    *   并发操作下的数据准确性（如果适用）。
*   **前端**:
    *   页面数据能否正确加载和展示。
    *   查询、分页、排序功能是否按预期工作。
    *   操作按钮（详情、修改状态）的交互和功能是否正常。
    *   表单校验和用户提示。
    *   不同屏幕尺寸下的响应式布局。
*   **整体**:
    *   数据在前后端之间的一致性。
    *   错误处理和用户友好提示。

## 6. 开发阶段与交付物
1.  **后端开发 (预计 X 天)**:
    *   完善/创建 DTO, VO。
    *   实现 Service 层逻辑。
    *   实现 Controller 层 API 接口。
    *   编写单元测试/集成测试。
    *   API 文档更新 (如使用 Swagger，则自动生成并校验)。
2.  **前端开发 (预计 Y 天)**:
    *   创建/完善页面组件。
    *   实现 API 服务调用。
    *   实现核心功能逻辑 (列表、筛选、分页、详情、操作等)。
    *   编写组件测试 (如果项目有要求)。
3.  **联调测试 (预计 Z 天)**:
    *   前后端集成测试。
    *   问题修复和优化。
4.  **文档更新**:
    *   更新 `LogBook.md` 记录开发过程。
    *   本方案文档根据实际开发情况进行调整。

## 7. 注意事项
*   **权限控制**: 严格确保所有管理接口仅管理员可访问。
*   **数据安全**: 对于手动修改会话状态等敏感操作，务必谨慎，并有充分的理由和记录。
*   **用户体验**: 管理界面应清晰易用，方便管理员快速找到所需信息并执行操作。 