整理文档

docs/系统开发日志/LogBook_Phase1.md

@@ -0,0 +1,297 @@
+# 项目变更日志
+
+## 2023-11-16
+- 初始化查看springboot-init-main项目
+- 项目分析详情如下：
+  - 这是一个基于Spring Boot 2.7.0的初始化项目模板
+  - 集成了MyBatis-Plus、Redis、MySQL等核心组件
+  - 遵循经典的MVC架构设计 
+
+## 2023-11-17
+- 启用MyBatis-Plus的驼峰命名转换功能
+  - 修改application.yml文件中的`map-underscore-to-camel-case`配置项为`true`
+  - 准备基于此模板开发全新项目 
+
+## 2023-11-18
+- **项目启动：MQTT 智能充电桩系统**
+  - 基于 `springboot-init` 模板进行二次开发。
+  - 修改项目标识 (`pom.xml`, `application.yml`) 为 `mqtt-charging-system`。
+  - 添加 `org.eclipse.paho.client.mqttv3` 依赖用于 MQTT 通信。
+  - **核心功能规划：**
+    1.  用户登录（管理员/普通用户）
+    2.  MQTT 集成（控制硬件，JSON 消息）
+    3.  简易充电桩系统（激活码充值、时长计费）
+- **创建需求文档**: 在 `doc/requirements.md` 中整理并记录了详细的功能和非功能需求。 
+
+## 2023-11-19
+- **调整需求文档**: 根据反馈更新 `doc/requirements.md`
+  - 明确系统为 **移动式** 充电系统，设备为 **充电机器人**。
+  - 调整充电流程，加入用户 **选择车位** 和 **机器人移动** 的步骤。
+  - 更新 MQTT Topic 和 Payload 示例以反映新流程。
+  - 调整数据库设计，引入 `charging_robot` 和 `parking_spot` 表。
+  - 强调平台侧重于业务逻辑和核心指令交互，不关注机器人底层实现。 
+
+## 2023-11-20
+- **优化数据库设计**: 根据建议调整 `requirements.md` 中的数据库结构。
+  - 将用户余额字段合并到 `user` 表。
+  - 移除 `role` 和 `user_role` 表，在 `user` 表中直接添加 `role` 字段。 
+
+## 2023-11-21
+- **格式化开题报告**: 调整 `doc/kaiti.md` 文件格式，提高可读性。
+- **细化需求并规划 MQTT**: 
+  - 结合 `kaiti.md` 内容，更新 `doc/requirements.md`。
+  - 明确平台与硬件（ESP32-CAM）的职责边界。
+  - 提出具体的 MQTT Topic 结构 (`robot/command/{clientId}`, `robot/status/{clientId}`) 和 JSON Payload 示例。
+  - 强调需要用户提供最终的 MQTT 服务器信息、认证凭据以及与硬件端确认的 Topic/Payload 约定。 
+
+## 2023-11-22
+- **编写开发方案**: 在 `doc/development_plan.md` 中创建了详细的开发计划。
+  - 包含系统架构、开发阶段划分、模块实现细节、数据库初步 DDL、高层 API 设计和 MQTT 契约强调。
+  - 明确后续开发依赖于用户提供 MQTT 连接信息和最终的消息格式约定。 
+
+## 2023-11-23
+- **引入机器人任务表**: 为了提高 MQTT 通信的健壮性，决定引入 `robot_task` 表。
+  - **目的**: 跟踪发送给机器人的命令状态，防止向未响应的机器人发送新命令。
+  - **更新文档**: 
+    - 在 `development_plan.md` 中添加了 `robot_task` 表的 DDL。
+    - 修改了 `development_plan.md` 中的 MQTT 发送/接收流程，集成任务状态检查和更新逻辑。
+    - 在 `development_plan.md` 中增加了任务超时处理的计划。
+    - 在 `requirements.md` 的数据库设计部分补充了 `robot_task` 表说明。 
+
+## 2023-11-24
+- **创建分阶段开发计划**: 
+  - 在 `doc/development_stages/` 目录下创建了详细的阶段性开发计划文件。
+  - 每个文件 (`stage_1_*.md` 到 `stage_4_*.md`) 包含该阶段的目标、前后端详细开发步骤、界面设计要点（针对移动端，蓝白科技感风格）和交付物。
+  - 旨在为后续的编码工作提供更具体的指导。 
+
+## 2023-11-25 开始第一阶段开发：基础架构与用户管理
+- **后端实现**: 
+  - 创建 `User` 实体类。
+  - 创建 `UserMapper` 接口。
+  - 创建 `SecurityConfig` 提供 `PasswordEncoder`。
+  - 创建 `UserService` 接口及 `UserServiceImpl` 实现类，包含注册、登录、登出、获取当前用户、余额操作（增加/扣减，含事务和并发处理）等逻辑。
+  - 创建 `UserConstant` 定义常量。
+  - 创建 `UserLoginRequest` 和 `UserRegisterRequest` DTO。
+  - 创建 `UserController` 实现用户相关 API (/register, /login, /logout, /current)。
+  - 添加 `CorsConfig` 进行全局跨域配置。
+- **下一步**: 需要进行数据库表结构初始化，并可以开始测试后端用户相关接口。 
+
+## 2023-11-26 配置数据库并转向前端开发
+- **更新数据库配置**: 根据用户提供的信息，修改了 `application.yml` 中的数据库连接URL、用户名和密码。
+- **下一步**: 开始进行 **阶段一** 的 **前端页面** 编写，实现登录、注册（如果需要）及基础导航功能。 
+
+### 2023-11-27: 初始化前端项目结构
+
+*   在根目录下创建了 `charging_app` 目录作为前端移动应用项目。
+*   选择了 React Native (使用 Expo) 作为前端技术栈，因为它提供了良好的跨平台能力和开发体验。
+*   创建了标准的前端项目结构，包括 `src` 目录下的 `screens`, `components`, `navigation`, `services`, `contexts`, `utils`, `assets` 子目录。
+*   添加了核心依赖配置文件 `package.json`。
+*   配置了 TypeScript `tsconfig.json`，启用了JSX和严格模式。
+*   创建了应用入口文件 `App.tsx`，集成了 `SafeAreaProvider` 和 `AuthProvider`。
+*   实现了认证上下文 `AuthContext.tsx`，用于管理用户登录状态、用户信息，并提供了登录、注册、登出方法，使用 `expo-secure-store` 存储会话状态。
+*   配置了 API 请求服务 `api.ts` (使用 Axios)，设置了基础 URL、超时和 `withCredentials`，并添加了基础的请求/响应拦截器逻辑。
+*   创建了应用导航器 `AppNavigator.tsx`，使用 `@react-navigation` 实现：
+    *   根据认证状态切换认证流程（登录/注册）和主应用界面。
+    *   认证后，根据用户角色 (`user`/`admin`) 导航到不同的主界面 (通过底部 Tab 导航)。
+    *   添加了加载状态指示器。
+*   创建了基本的屏幕占位符：`LoginScreen.tsx`, `RegisterScreen.tsx`, `UserHomeScreen.tsx`, `AdminHomeScreen.tsx`。
+
+**下一步**: 
+1.  在 `charging_app` 目录下运行 `npm install` 或 `yarn install` 来安装所有前端依赖项。
+2.  实现登录页面的UI和功能逻辑。
+3.  测试前后端用户登录流程。
+
+### 2023-11-28: 实现登录页面UI与逻辑
+
+*   根据 `stage_1_setup_user_management.md` 中的设计要求，更新了 `charging_app/src/screens/LoginScreen.tsx`。
+*   添加了用户名和密码的 `TextInput` 组件，以及一个主要的 "登录" `Button`。
+*   添加了一个 `TouchableOpacity` 作为导航到注册页面的链接。
+*   实现了 `handleLogin` 函数，该函数：
+    *   执行基本的非空输入验证。
+    *   调用 `AuthContext` 中的 `login` 方法。
+    *   管理 `isLoading` 状态，在请求期间显示 `ActivityIndicator`。
+    *   管理 `error` 状态，在登录失败时显示错误文本和 `Alert` 提示。
+*   应用了符合设计指南的样式 (科技蓝主色调，简洁布局，圆角输入框和按钮)。
+*   为 `LoginScreen` 添加了正确的 `navigation` prop类型定义 (`StackNavigationProp`)。
+
+**下一步**:
+1.  启动后端服务 (`springboot-init-main`)。
+2.  在模拟器或真实设备上运行前端应用 (`charging_app`，例如使用 `npx expo start`)。
+3.  测试完整的登录流程，包括成功登录和失败（错误凭据）的情况。
+4.  (可选) 实现注册页面 `RegisterScreen.tsx` 的UI和逻辑。
+
+### 2023-11-26: 更新数据库配置与确认前端方案
+
+*   根据用户提供的最新信息，更新了后端 `springboot-init-main/src/main/resources/application.yml` 文件中的数据库连接配置 (URL, username, password)。
+*   确认了移动端 App 的开发将使用跨平台框架。 
+
+### 2023-11-29: 前端技术方向重大调整：从原生App转向手机版网页
+
+*   **核心决策**：根据最新需求，项目前端将从React Native移动应用调整为手机版网页应用。
+*   **技术选型变更**：放弃React Native + Expo，计划采用 **Next.js** (基于React) 作为新的前端框架。
+    *   理由：Next.js更适合构建服务端渲染或静态生成的网页应用，并能良好支持响应式设计，以适应手机浏览器。
+*   **影响评估**：
+    *   现有的 `charging_app` React Native项目将被新的Next.js项目替代。
+    *   UI组件、样式、导航系统需要完全重写。
+    *   认证逻辑 (`AuthContext`) 和API服务 (`api.ts`) 的核心部分可以迁移和调整，但与原生特性相关的部分（如 `expo-secure-store`）需要替换为Web等效方案（如 `localStorage`）。
+    *   所有前端相关的开发阶段文档（如 `stage_1_*.md`）需要更新以反映新的技术栈和实现方法。
+
+**下一步**:
+1.  删除或归档现有的 `charging_app` (React Native) 项目目录。
+2.  初始化新的Next.js前端项目 (例如 `charging_web_app`)。
+3.  迁移和调整 `AuthContext` 和 `api.ts` 的核心逻辑。
+4.  重新实现登录页面的UI和功能，使其适应Web浏览器。
+5.  更新 `stage_1_setup_user_management.md` 文档。 
+
+### 2023-11-30: 初始化Next.js项目并实现Web登录页
+
+*   在 `charging_web_app` 目录下手动安装了 `axios` 依赖。
+*   更新了 `springboot-init-main/doc/development_stages/stage_1_setup_user_management.md` 文档的前端部分，以适配Next.js技术栈和Web开发实践。
+*   创建了Next.js项目的根布局文件 `charging_web_app/src/app/layout.tsx`，并在此布局中集成了 `AuthProvider`，确保全局认证状态管理。
+*   创建了新的Web登录页面 `charging_web_app/src/app/login/page.tsx`：
+    *   标记为客户端组件 (`'use client';`)。
+    *   使用Tailwind CSS构建了适应Web的登录表单UI (卡片布局、输入框、按钮、注册链接)。
+    *   集成了 `useAuth` 钩子，实现了表单提交、调用 `login` 方法、处理加载和错误状态的逻辑。
+    *   添加了 `useEffect` 钩子，用于在用户已认证时自动重定向到相应的主页。
+
+**下一步**:
+1.  配置Next.js开发环境代理 (在 `next.config.mjs` 中添加 `rewrites`)，将 `/api/*` 请求转发到后端服务 (`http://localhost:7529/api/*`)。
+2.  启动后端服务 (`springboot-init-main`)。
+3.  启动Next.js前端开发服务器 (`cd charging_web_app && npm run dev`)。
+4.  在浏览器中访问登录页面 (通常是 `http://localhost:3000/login`) 并测试登录流程。
+5.  (可选) 实现注册页面 `src/app/register/page.tsx`。 
+
+### 2023-12-01: 实现Web注册页面
+
+*   创建了注册页面组件 `charging_web_app/src/app/register/page.tsx`。
+*   使用Tailwind CSS构建了注册表单UI，包含用户名、密码和确认密码字段，风格与登录页保持一致。
+*   实现了前端输入验证逻辑，包括非空、密码一致性和最小长度检查。
+*   集成了 `useAuth` 钩子，在表单提交时调用 `register` 方法。
+*   实现了加载状态（按钮显示加载动画）、错误状态（显示错误信息）和成功状态（显示成功消息并延迟跳转）的处理。
+*   添加了返回登录页面的链接。
+
+**下一步**:
+1.  测试完整的注册流程，包括成功和失败场景。
+2.  根据用户角色，创建基础的主页路由和组件（例如 `src/app/(authenticated)/dashboard/page.tsx` 和 `src/app/(authenticated)/admin/dashboard/page.tsx`），并实现基本的权限访问控制逻辑（例如在布局或页面中检查 `isAuthenticated` 和 `user.role`）。
+3.  解决之前提到的后端 `/api/user/current` 接口返回 500 错误的问题。 
+
+## YYYY-MM-DD (请替换为当前日期)
+- **移除后端 Redis 依赖**
+  - 从 `springboot-init-main/pom.xml` 中移除了 `spring-boot-starter-data-redis` 和 `spring-session-data-redis` 依赖。
+  - 修改 `springboot-init-main/src/main/resources/application.yml`：
+    - 移除了 `spring.redis` 配置块。
+    - 将 `spring.session.store-type` 的值从 `redis` 修改为 `none`，使 Session 存储回退到默认的内存方式。
+  - 此变更旨在简化项目依赖，如果后续需要分布式 Session 管理或缓存，可以重新引入 Redis 或其他替代方案。
+
+## YYYY-MM-DD (请替换为当前日期)
+- **添加 Spring Security 依赖**
+  - 为了解决 `PasswordEncoder` 相关的编译错误，在 `springboot-init-main/pom.xml` 中添加了 `spring-boot-starter-security` 依赖。 
+
+## 2023-12-02: 完成第一阶段核心功能开发 (用户中心与管理员功能)
+
+**后端 (`springboot-init-main`)**:
+- **`UserService` / `UserServiceImpl`**:
+  - 新增 `listUsers()` 方法，用于获取所有（未删除的）用户信息，并进行脱敏处理。
+- **`UserController`**:
+  - 启用并完善 `/api/user/list` 接口，使其调用 `userService.listUsers()`，并添加了基于 `UserRoleEnum.ADMIN` 的显式权限检查 (作为双重保险)。
+- **`SecurityConfig.java`**:
+  - 更新了 `authorizeRequests` 配置：
+    - `/api/user/current` 设置为需要 `authenticated()`。
+    - `/api/user/list` 设置为需要 `hasAuthority(UserRoleEnum.ADMIN.getValue())`，确保只有 "admin" 角色的用户可以访问。
+    - `/api/user/login` 和 `/api/user/register` 保持 `permitAll()`。
+
+**前端 (`charging_web_app`)**:
+- **`AuthContext.tsx`**:
+  - 在 `login` 方法中，登录成功后，根据 `user.role` (期望为 "admin" 或 "user") 将用户重定向到 `/admin/dashboard` 或 `/dashboard`。
+  - 优化了 `checkAuth` 方法的日志和加载状态处理。
+- **路由与权限控制**:
+  - 创建了路由组目录 `src/app/(authenticated)/`。
+  - 创建了 `src/app/(authenticated)/layout.tsx` (`AuthenticatedLayout`)，用于保护该组下的所有路由：
+    - 使用 `useAuth` 检查认证状态 (`isAuthenticated`, `isLoading`)。
+    - 如果用户未认证，则使用 `router.replace('/login')` 重定向到登录页。
+    - 在加载期间显示 `LoadingSpinner` 组件。
+  - 创建了 `src/components/LoadingSpinner.tsx` 提供一个简单的加载动画组件。
+- **普通用户主页**:
+  - 创建了 `src/app/(authenticated)/dashboard/page.tsx` (`DashboardPage`)：
+    - 显示欢迎信息、用户ID、角色和余额。
+    - 提供登出按钮，调用 `auth.logout()`。
+    - 如果非普通用户（如管理员）意外访问，则重定向到其对应的 dashboard。
+- **管理员主页**:
+  - 创建了 `src/app/(authenticated)/admin/dashboard/page.tsx` (`AdminDashboardPage`)：
+    - 显示管理员欢迎信息。
+    - 提供导航链接到"用户管理"页面 (`/admin/user-management`)。
+    - 提供登出按钮。
+    - 如果非管理员用户意外访问，则重定向到 `/dashboard`。
+- **管理员用户管理页面**:
+  - 创建了 `src/app/(authenticated)/admin/user-management/page.tsx` (`UserManagementPage`)：
+    - 页面加载时，如果用户是管理员，则调用后端 `/api/user/list` 接口获取用户列表。
+    - 将获取到的用户列表（ID, 用户名, 角色, 余额）以表格形式展示。
+    - 处理加载状态和错误状态（如无权限访问或API调用失败）。
+    - 提供返回管理员主页的链接。
+    - 实现了严格的权限检查，非管理员访问会重定向。
+
+**下一步**:
+1.  **全面测试**：
+    - 启动后端 (`springboot-init-main`) 和前端 (`charging_web_app`) 服务。
+    - 测试普通用户注册、登录、查看用户中心、登出。
+    - 测试管理员用户登录、查看管理员控制台、访问用户管理列表、登出。
+    - 验证所有页面的权限控制和重定向逻辑是否按预期工作。
+    - 检查浏览器控制台和后端日志，确保没有错误。
+2.  根据 `stage_1_setup_user_management.md` 的要求，完成 **接口测试报告**。
+3.  如果一切顺利，第一阶段的核心功能（用户管理、用户中心、管理员用户列表）即可视为完成。
+
+## 2023-12-02 (续): 完成管理员对用户的增删改功能
+
+**后端 (`springboot-init-main`)**:
+- **DTOs**:
+  - 创建 `UserAdminAddRequest.java` 用于管理员添加用户 (username, password, role, balance)。
+  - 创建 `UserAdminUpdateRequest.java` 用于管理员更新用户 (id, username?, password?, role?, balance?)。
+- **`UserService` / `UserServiceImpl`**:
+  - 实现 `adminAddUser(UserAdminAddRequest req)`: 校验参数、检查用户名唯一性、加密密码、保存新用户。
+  - 实现 `adminUpdateUser(UserAdminUpdateRequest req)`: 查找用户、校验参数、按需更新用户名（检查冲突）、密码（加密）、角色、余额。
+- **`UserController`**:
+  - 添加 `POST /user/admin/add` 接口，调用 `userService.adminAddUser`。
+  - 添加 `PUT /user/admin/update` 接口，调用 `userService.adminUpdateUser`。
+  - 在各接口中添加了管理员权限校验和必要的参数校验。
+  - `adminDeleteUser` 接口中增加了防止管理员删除自己的逻辑。
+  - `adminUpdateUser` 接口中增加了防止管理员将自己角色修改为非管理员的逻辑。
+- **`SecurityConfig.java`**:
+  - 为 `/user/admin/add` (POST) 和 `/user/admin/update` (PUT) 配置了仅管理员 (`hasAuthority('admin')`)可访问的规则。
+
+**前端 (`charging_web_app`)**:
+- **`UserManagementPage.tsx`**:
+  - 添加了 "新增用户" 按钮。
+  - 为每行用户数据添加了 "编辑" 按钮。
+  - 实现了基本的模态框（使用内联JSX和Tailwind CSS）用于用户添加和编辑：
+    - 包含用户名、密码（新增时必填，编辑时可选用于重置）、角色（下拉选择）、余额的表单字段。
+    - 实现了表单数据的状态管理 (`userFormData`, `editingUser`)。
+    - 实现了打开/关闭模态框的状态 (`isAddUserModalOpen`, `isEditUserModalOpen`)。
+    - 实现了 `handleAddUser` 函数，调用 `POST /api/user/admin/add` API，成功后关闭模态框并刷新用户列表。
+    - 实现了 `handleUpdateUser` 函数，调用 `PUT /api/user/admin/update` API，成功后关闭模态框并刷新用户列表。
+  - `handleDeleteUser` 函数保持不变，用于删除用户。
+  - 编辑按钮对当前登录的管理员（如果其角色也是admin）进行了禁用处理，以防止直接修改自身（特别是角色）。
+
+**下一步**:
+1.  **全面细致的测试**：覆盖所有增删改查操作的成功与失败场景，包括边界条件和权限验证。
+2.  **UI/UX 优化**：后续可以考虑使用成熟的UI组件库替换当前的简易模态框和表单，提升用户体验。
+3.  完成第一阶段的接口测试报告和项目总结。
+
+## 2023-12-02 (续): 优化用户管理弹窗UI
+
+**前端 (`charging_web_app`)**:
+- **依赖安装**:
+  - 在 `charging_web_app` 项目中安装了 `@headlessui/react` 依赖包。
+- **`UserManagementPage.tsx`**:
+  - 导入了 Headless UI 的 `Dialog` 和 `Transition` 组件。
+  - 使用这两个组件重构了新增用户和编辑用户的模态框：
+    - 实现了更平滑的进入和离开动画。
+    - 弹窗背景覆盖层修改为 `bg-black/30 backdrop-blur-sm`，以实现背景模糊效果。
+    - 统一并优化了模态框内部表单字段（用户名、密码、角色、余额）的样式，使用了Tailwind CSS。
+    - 调整了按钮（取消、确认新增/修改）的样式，并为提交按钮添加了 `isLoadingAction` 状态来显示加载动画和禁用状态。
+    - 在模态框中添加了错误信息显示区域，用于反馈操作失败的原因。
+  - 修复了 `isLoadingAction` 未定义的 linting 错误。
+
+**下一步**:
+1.  **重启前端开发服务器**。
+2.  **测试新的弹窗样式和交互**：确认动画、背景模糊、表单样式、按钮状态和错误提示是否符合预期。
+3.  如果效果满意，第一阶段的用户管理前端UI优化基本完成。可以准备正式结束第一阶段。