# Smark **Repository Path**: lol1296/smark ## Basic Information - **Project Name**: Smark - **Description**: 管理员前端Vue，用户前端原生框架，后端SpringBoot + JPA + MySQL - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2025-05-26 - **Last Updated**: 2025-09-09 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README ## API 接口文档 ### 1. 引言 本文档描述了应用提供的API接口，主要包括用户管理和记账管理两大模块。所有接口均使用JSON格式进行数据交换，并遵循统一的响应结构。 ### 2. 认证 本API使用JWT (JSON Web Token)进行认证。用户成功登录后，会在响应中获得一个JWT。后续访问受保护的接口时，需要在请求的`Authorization`头中携带此JWT，格式为： `Authorization: Bearer ` ### 3. 统一响应格式 所有API接口的响应都遵循以下结构： ```json { "code": 200, "success": true, "message": "操作成功", "data": {} } ``` 字段说明： * `Code` (integer): HTTP状态码的数字表示。 * `success` (boolean): 操作是否成功。 * `message` (string): 操作结果的提示信息。 * `data` (object | array | null): 实际返回的数据内容。 ### 4. 用户接口 (/api/users) #### 4.1 用户注册 * **功能描述**: 注册新用户。 * **请求URL**: `/api/users/register` * **请求方法**: `POST` * **请求体与响应体**: * **请求体 JSON**: ```json { "account": "testuser01", "username": "测试用户一号", "password": "password123" } ``` * **成功响应 (200 OK / 201 Created) JSON**: ```json { "code": 200, "success": true, "message": "注册成功", "data": { "id": 1, "account": "testuser01", "username": "测试用户一号", "avatar": null, "addTime": "2024-05-29T08:30:00Z", "updateTime": "2024-05-29T08:30:00Z", "bookCount": 0 } } ``` * **失败响应示例 (账号已存在 - 409 Conflict) JSON**: ```json { "code": 409, "success": false, "message": "账号已存在: testuser01", "data": null } ``` * **失败响应示例 (参数错误 - 400 Bad Request) JSON**: ```json { "code": 400, "success": false, "message": "密码长度不能少于6位", "data": null } ``` #### 4.2 用户登录 * **功能描述**: 用户登录并获取JWT。 * **请求URL**: `/api/users/login` * **请求方法**: `POST` * **请求体与响应体**: * **请求体 JSON**: ```json { "account": "testuser01", "password": "password123" } ``` * **成功响应 (200 OK) JSON**: ```json { "code": 200, "success": true, "message": "登录成功", "data": { "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZXN0dXNlcjAxIiwiaWF0IjoxNzE2OTY2ODAwLCJleHAiOjE3MTY5NzAwMDB9.xxxxxxxxxxxx", "user": { "id": 1, "account": "testuser01", "username": "测试用户一号", "avatar": null, "addTime": "2024-05-29T08:30:00Z", "updateTime": "2024-05-29T08:30:00Z", "bookCount": 0 } } } ``` * **失败响应示例 (认证失败 - 401 Unauthorized) JSON**: ```json { "code": 401, "success": false, "message": "用户名或密码错误", "data": null } ``` #### 4.3 根据ID获取用户信息 * **功能描述**: 获取指定ID的用户信息。 * **请求URL**: `/api/users/{id}` * **请求方法**: `GET` * **请求头**: `Authorization: Bearer ` * **路径参数**: `id` (integer) - 用户ID。 * **请求体与响应体**: * **请求体**: 无 * **成功响应 (200 OK) JSON**: ```json { "code": 200, "success": true, "message": "操作成功", "data": { "id": 1, "account": "testuser01", "username": "测试用户一号", "avatar": null, "addTime": "2024-05-29T08:30:00Z", "updateTime": "2024-05-29T08:30:00Z", "bookCount": 0 } } ``` * **失败响应示例 (用户未找到 - 404 Not Found) JSON**: ```json { "code": 404, "success": false, "message": "用户未找到，ID: 999", "data": null } ``` #### 4.4 根据账号获取用户信息 * **功能描述**: 获取指定账号的用户信息。 * **请求URL**: `/api/users/account/{account}` * **请求方法**: `GET` * **请求头**: `Authorization: Bearer ` * **路径参数**: `account` (string) - 用户账号。 * **请求体与响应体**: * **请求体**: 无 * **成功响应 (200 OK) JSON**: ```json { "code": 200, "success": true, "message": "操作成功", "data": { "id": 1, "account": "testuser01", "username": "测试用户一号", "avatar": null, "addTime": "2024-05-29T08:30:00Z", "updateTime": "2024-05-29T08:30:00Z", "bookCount": 0 } } ``` * **失败响应示例 (用户未找到 - 404 Not Found) JSON**: ```json { "code": 404, "success": false, "message": "用户未找到，账号: nonexistuser", "data": null } ``` #### 4.5 获取所有用户信息 * **功能描述**: 获取所有用户列表。 * **请求URL**: `/api/users` * **请求方法**: `GET` * **请求头**: `Authorization: Bearer ` * **请求体与响应体**: * **请求体**: 无 * **成功响应 (200 OK) JSON**: ```json { "code": 200, "success": true, "message": "操作成功", "data": [ { "id": 1, "account": "testuser01", "username": "测试用户一号", "avatar": null, "addTime": "2024-05-29T08:30:00Z", "updateTime": "2024-05-29T08:30:00Z", "bookCount": 0 }, { "id": 2, "account": "admin", "username": "管理员", "avatar": null, "addTime": "2024-05-28T10:00:00Z", "updateTime": "2024-05-28T10:00:00Z", "bookCount": 10 } ] } ``` * **失败响应示例 (服务器错误 - 500 Internal Server Error) JSON**: ```json { "code": 500, "success": false, "message": "获取用户列表失败: [具体错误信息]", "data": null } ``` #### 4.6 更新用户信息 * **功能描述**: 更新指定ID用户的部分信息 (例如 `username`, `account`, `avatar` 等，具体可更新字段见相应DTO)。 * **请求URL**: `/api/users/{id}` * **请求方法**: `PUT` * **请求头**: `Authorization: Bearer ` * **路径参数**: `id` (integer) - 用户ID。 * **请求体与响应体**: * **请求体 JSON (示例: 仅更新用户名和头像)**: ```json { "username": "测试用户一号更新", "avatar": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..." } ``` * **成功响应 (200 OK) JSON**: ```json { "code": 200, "success": true, "message": "用户信息更新成功", "data": { "id": 1, "account": "testuser01", "username": "测试用户一号更新", "avatar": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...", "addTime": "2024-05-29T08:30:00Z", "updateTime": "2024-05-29T08:35:00Z", "bookCount": 0 } } ``` * **失败响应示例 (用户未找到 - 404 Not Found) JSON**: ```json { "code": 404, "success": false, "message": "用户未找到，ID: 999", "data": null } ``` * **失败响应示例 (参数错误 - 400 Bad Request) JSON**: ```json { "code": 400, "success": false, "message": "用户名不能为空", "data": null } ``` #### 4.7 修改用户密码 * **功能描述**: 修改指定ID用户的密码。 * **请求URL**: `/api/users/{id}/change-password` * **请求方法**: `POST` * **请求头**: `Authorization: Bearer ` * **路径参数**: `id` (integer) - 用户ID。 * **请求体与响应体**: * **请求体 JSON**: ```json { "oldPassword": "password123", "newPassword": "newPassword456" } ``` * **成功响应 (200 OK) JSON**: ```json { "code": 200, "success": true, "message": "密码修改成功", "data": null } ``` * **失败响应示例 (用户未找到 - 404 Not Found) JSON**: ```json { "code": 404, "success": false, "message": "用户未找到，ID: 999", "data": null } ``` * **失败响应示例 (密码错误 - 400 Bad Request) JSON**: ```json { "code": 400, "success": false, "message": "旧密码不正确", "data": null } ``` #### 4.8 删除用户 * **功能描述**: 删除指定ID的用户。 * **请求URL**: `/api/users/{id}` * **请求方法**: `DELETE` * **请求头**: `Authorization: Bearer ` * **路径参数**: `id` (integer) - 用户ID。 * **请求体与响应体**: * **请求体**: 无 * **成功响应 (200 OK) JSON**: ```json { "code": 200, "success": true, "message": "用户删除成功", "data": null } ``` * **失败响应示例 (用户未找到 - 404 Not Found) JSON**: ```json { "code": 404, "success": false, "message": "用户未找到，ID: 999", "data": null } ``` ### 5. 记账接口 (/api/bookkeeping) **注意**: 以下所有记账接口都需要用户认证，系统会自动获取当前登录用户的ID进行操作。 #### 5.1 添加记账记录 * **功能描述**: 为当前登录用户添加一条新的记账记录。 * **请求URL**: `/api/bookkeeping` * **请求方法**: `POST` * **请求头**: `Authorization: Bearer ` * **请求体与响应体**: * **请求体 JSON**: ```json { "type": 1, "category": "交通", "price": 20.00, "remark": "地铁票", "bookDate": "2024-05-29" } ``` * **成功响应 (200 OK ) JSON**: ```json { "code": 200, "success": true, "message": "记账成功", "data": { "id": 101, "userId": 1, "type": 1, "category": "交通", "price": 20.00, "remark": "地铁票", "bookDate": "2024-05-29", "addTime": "2024-05-29T09:00:05Z", "updateTime": "2024-05-29T09:00:05Z", "year": 2024, "month": 5 } } ``` * **失败响应示例 (未认证 - 401 Unauthorized) JSON**: ```json { "code": 401, "success": false, "message": "用户未认证", "data": null } ``` * **失败响应示例 (参数错误 - 400 Bad Request) JSON**: ```json { "code": 400, "success": false, "message": "金额必须大于0", "data": null } ``` #### 5.2 查看当前用户某年某月的记账数据 * **功能描述**: 获取当前登录用户在指定年月的记账记录列表。 * **请求URL**: `/api/bookkeeping` * **请求方法**: `GET` * **请求头**: `Authorization: Bearer ` * **查询参数**: * `year` (integer, 必填): 年份，例如 `2024`。 * `month` (integer, 必填): 月份，例如 `5` (代表5月)。 * **请求体与响应体**: * **请求体**: 无 * **成功响应 (200 OK) JSON**: ```json { "code": 200, "success": true, "message": "查询成功", "data": [ { "id": 101, "userId": 1, "type": 1, "category": "交通", "price": 20.00, "remark": "地铁票", "bookDate": "2024-05-29", "addTime": "2024-05-29T09:00:05Z", "updateTime": "2024-05-29T09:00:05Z", "year": 2024, "month": 5 }, { "id": 102, "userId": 1, "type": 0, "category": "工资", "price": 5000.00, "remark": "五月工资", "bookDate": "2024-05-10", "addTime": "2024-05-10T10:00:05Z", "updateTime": "2024-05-10T10:00:05Z", "year": 2024, "month": 5 } ] } ``` * **成功响应 (无记录 - 200 OK) JSON**: ```json { "code": 200, "success": true, "message": "您在此期间无记账记录", "data": [] } ``` * **失败响应示例 (未认证 - 401 Unauthorized) JSON**: ```json { "code": 401, "success": false, "message": "用户未认证", "data": null } ``` #### 5.3 查看当前用户某条记账数据的详情 * **功能描述**: 获取当前登录用户指定的某条记账记录的详细信息。 * **请求URL**: `/api/bookkeeping/{recordId}` * **请求方法**: `GET` * **请求头**: `Authorization: Bearer ` * **路径参数**: `recordId` (integer) - 记账记录ID。 * **请求体与响应体**: * **请求体**: 无 * **成功响应 (200 OK) JSON**: ```json { "code": 200, "success": true, "message": "查询详情成功", "data": { "id": 101, "userId": 1, "type": 1, "category": "交通", "price": 20.00, "remark": "地铁票", "bookDate": "2024-05-29", "addTime": "2024-05-29T09:00:05Z", "updateTime": "2024-05-29T09:00:05Z", "year": 2024, "month": 5 } } ``` * **失败响应示例 (未找到 - 404 Not Found) JSON**: ```json { "code": 404, "success": false, "message": "记账记录未找到或不属于该用户", "data": null } ``` #### 5.4 修改记账数据 * **功能描述**: 修改当前登录用户指定的某条记账记录。 * **请求URL**: `/api/bookkeeping/{recordId}` * **请求方法**: `PUT` * **请求头**: `Authorization: Bearer ` * **路径参数**: `recordId` (integer) - 记账记录ID。 * **请求体与响应体**: * **请求体 JSON**: ```json { "type": 1, "category": "餐饮", "price": 25.50, "remark": "午餐便当" } ``` * **成功响应 (200 OK) JSON**: ```json { "code": 200, "success": true, "message": "修改成功", "data": { "id": 101, "userId": 1, "type": 1, "category": "餐饮", "price": 25.50, "remark": "午餐便当", "bookDate": "2024-05-29", "addTime": "2024-05-29T09:00:05Z", "updateTime": "2024-05-29T09:10:15Z", "year": 2024, "month": 5 } } ``` * **失败响应示例 (未找到 - 404 Not Found) JSON**: ```json { "code": 404, "success": false, "message": "记账记录未找到或不属于该用户, 无法更新", "data": null } ``` #### 5.5 删除记账数据 * **功能描述**: 删除当前登录用户指定的某条记账记录。 * **请求URL**: `/api/bookkeeping/{recordId}` * **请求方法**: `DELETE` * **请求头**: `Authorization: Bearer ` * **路径参数**: `recordId` (integer) - 记账记录ID。 * **请求体与响应体**: * **请求体**: 无 * **成功响应 (200 OK) JSON**: ```json { "code": 200, "success": true, "message": "删除成功", "data": null } ``` * **失败响应示例 (未找到 - 404 Not Found) JSON**: ```json { "code": 404, "success": false, "message": "记账记录未找到或不属于该用户, 无法删除", "data": null } ``` ### 管理员 #### 管理员登录 - **功能描述**：管理员使用账号和密码登录系统，成功后获取认证令牌 (Token)。 - **请求URL**：`/api/admin/login` - **请求方法**：`POST` - **请求头**： - `Content-Type: application/json`（必需，用于指定请求体格式） - **路径参数**：无 - **请求体与响应体**： - **请求体 (JSON)**： ```json { "account": "管理员账号", "password": "管理员密码" } ``` **示例**： ```json { "account": "123", "password": "123456" } ``` - **成功响应 (200 OK) JSON**： ```json { "success": true, "message": "管理员登录成功", "data": { "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjMiLCJpYXQiOjE3NDk0NzM3ODEsImV4cCI6MTc1MjA2NTc4MX0.-3QRqW2g8WOfvYOHgsOgOhgRmh5l7A4NWKFgMQBioVY", "user": { "id": 1, "account": "123", "username": "123" } }, "code": 200 } ``` **字段说明**： - `success` (boolean)：操作是否成功。 - `message` (string)：响应消息。 - `data` (object)：响应数据。 - `token` (string)：生成的JWT认证令牌。 - `user` (object)：登录的管理员用户信息。 - `id` (integer/long)：管理员ID。 - `account` (string)：管理员账号。 - `username` (string)：管理员显示的用户名。 - `code` (integer)：HTTP状态码或业务状态码。 - **失败响应示例 (凭据错误 - 401 Unauthorized) JSON**： ```json { "code": 401, "success": false, "message": "账号或密码错误", "data": null } ``` - **失败响应示例 (用户被禁用 - 403 Forbidden) JSON**： ```json { "code": 403, "success": false, "message": "用户已被禁用", "data": null } ``` - **失败响应示例 (请求体错误/参数缺失 - 400 Bad Request) JSON**： ```json { "code": 400, "success": false, "message": "请求参数错误，请检查account和password字段", "data": null } ``` #### 创建管理员 (需要认证) - **功能描述**：已登录的管理员创建新的管理员账户。此操作需要有效的认证令牌 (Token)。 - **请求URL**：`/api/admin/create-admin` - **请求方法**：`POST` - **请求头**： - `Content-Type: application/json`（必需，用于指定请求体格式） - `Authorization: Bearer `（必需，用于身份认证） - **路径参数**：无 - **请求体与响应体**： - **请求体 (JSON)**： ```json { "account": "新管理员账号", "username": "新管理员用户名 (可选)", "password": "新管理员密码" } ``` **字段说明**： - `account` (string, 必需)：新管理员的登录账号，必须唯一。长度限制：1-50字符。 - `username` (string, 可选)：新管理员显示的用户名。如果未提供，将默认为账号。长度限制：最大50字符。 - `password` (string, 必需)：新管理员的登录密码。长度限制：6-100字符。 **示例**： ```json { "account": "newAdmin01", "username": "New Admin User", "password": "password123" } ``` - **成功响应 (通常 HTTP 201 Created，但业务 `code` 为 200) JSON**： ```json { "success": true, "message": "管理员创建成功", "data": { "id": 4, "account": "newAdmin01", "username": "New Admin User" }, "code": 200 } ``` **字段说明**： - `success` (boolean)：操作是否成功。 - `message` (string)：响应消息。 - `data` (object)：创建成功的管理员信息。 - `id` (integer)：新创建管理员的唯一ID。 - `account` (string)：新创建管理员的账号。 - `username` (string)：新创建管理员的用户名。 - `code` (integer)：业务状态码。 #### 查询所有管理员信息 (需要认证) - **功能描述**：已登录的管理员获取系统中所有管理员账户的信息列表。此操作需要有效的认证令牌 (Token)。 - **请求URL**：`/api/admin/all` - **请求方法**：`GET` - **请求头**： - `Authorization: Bearer `（必需，用于身份认证） - **路径参数**：无 - **查询参数**：无 - **请求体与响应体**： - **请求体**：无 - **成功响应 (200 OK) JSON**： ```json { "success": true, "message": "成功获取所有管理员信息", "data": [ { "id": 1, "account": "admin1", "username": "Administrator One" }, { "id": 2, "account": "admin2", "username": "Administrator Two" } ], "code": 200 } ``` **字段说明**： - `success` (boolean)：操作是否成功。 - `message` (string)：响应消息。 - `data` (array)：管理员信息对象列表。每个对象包含： - `id` (integer)：管理员的唯一ID。 - `account` (string)：管理员的账号。 - `username` (string)：管理员的用户名。 - `code` (integer)：业务状态码。 #### 修改当前管理员的个人信息 (需要认证) - **功能描述**：当前已登录的管理员修改自己的个人信息，包括登录账号、显示的用户名和密码。此操作需要有效的认证令牌 (Token)。 - **请求URL**：`/api/admin/me/profile` - **请求方法**：`PUT` - **请求头**： - `Content-Type: application/json`（必需） - `Authorization: Bearer `（必需） - **路径参数**：无 - **请求体与响应体**： - **请求体 (JSON)**： ```json { "newAccount": "新的登录账号 (可选)", "username": "新的显示用户名 (可选)", "newPassword": "新的登录密码 (可选，长度至少6位)" } ``` **字段说明**： - `newAccount` (string, 可选)：如果提供且与当前账号不同，则尝试更新登录账号。必须唯一。 - `username` (string, 可选)：如果提供，则更新显示的用户名。可设置为空字符串。 - `newPassword` (string, 可选)：如果提供，则更新登录密码。长度至少6位。 **示例 (只修改用户名和密码)**： ```json { "username": "SuperAdminUpdated", "newPassword": "newSecurePassword123" } ``` **示例 (修改账号和用户名)**： ```json { "newAccount": "super_admin_new_account", "username": "Super Administrator New" } ``` - **成功响应 (200 OK) JSON (使用 `ApiResponse` 结构)**： ```json { "success": true, "message": "管理员个人信息更新成功", "data": { "id": 1, "account": "super_admin_new_account", "username": "Super Administrator New" }, "code": 200 } ``` **字段说明**： - `code` (integer)：业务状态码 (通常为200)。 - `success` (boolean)：操作是否成功。 - `message` (string)：响应消息。 - `data` (object)：更新后的管理员信息 (`AdminInfoDto`)，不包含密码。 - `id` (integer)：管理员ID。 - `account` (string)：管理员账号。 - `username` (string)：管理员显示的用户名。 #### 删除当前管理员的账户 (需要认证) - **功能描述**：当前已登录的管理员删除自己的账户。此操作不可逆，并需要有效的认证令牌 (Token)。 - **请求URL**：`/api/admin/me` - **请求方法**：`DELETE` - **请求头**： - `Authorization: Bearer `（必需） - **路径参数**：无 - **请求体**：无 - **响应体**： - **成功响应 (200 OK) JSON (使用 `ApiResponse` 结构)**： ```json { "success": true, "message": "管理员账户已成功删除。", "data": null, "code": 200 } ``` **字段说明**： - `code` (integer)：业务状态码 (通常为200)。 - `success` (boolean)：操作是否成功。 - `message` (string)：响应消息。 - `data` (null)：成功删除时，data 通常为null。 #### 获取所有普通用户信息 (Admin Only) - **功能描述**：已登录的管理员获取系统中所有注册的普通用户（非管理员）的信息列表。此接口需要管理员权限。 - **请求URL**：`api/admin/users` - **请求方法**：`GET` - **请求头**： - `Authorization: Bearer `（必需, `` 替换为管理员登录后获取的JWT） - **路径参数**：无 - **请求体**：无 - **响应体 (成功示例 - 200 OK)**： ```json { "code": 200, "success": true, "message": "成功获取所有用户信息", "data": [ { "id": 1, "account": "13000000001", "username": "user1", "avatar": null, "addTime": "2025-06-11T12:45:02", "updateTime": "2025-06-11T12:45:02", "bookCount": 0 }, { "id": 2, "account": "13000000002", "username": "user2", "avatar": null, "addTime": "2025-06-11T12:45:08", "updateTime": "2025-06-11T12:45:08", "bookCount": 0 }, { "id": 3, "account": "13000000003", "username": "user3", "avatar": null, "addTime": "2025-06-11T12:45:16", "updateTime": "2025-06-11T12:45:16", "bookCount": 0 }, { "id": 4, "account": "13800138004", "username": "TestUserFour", "avatar": null, "addTime": "2025-06-11T20:53:10", "updateTime": "2025-06-11T20:53:10", "bookCount": 0 }, { "id": 5, "account": "13900139005", "username": "SampleUserFive", "avatar": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==", "addTime": "2025-06-11T20:53:10", "updateTime": "2025-06-11T20:53:10", "bookCount": 1 } ] } ``` **响应字段说明**： - `code` (integer)：业务状态码，成功时通常为 `200`。 - `success` (boolean)：操作是否成功，成功时为 `true`。 - `message` (string)：描述操作结果的信息。 - `data` (array)：包含用户信息的数组。每个元素是一个对象，代表一个用户，其结构如下： - `id` (integer)：用户的唯一标识符。 - `account` (string)：用户的账号。 - `username` (string)：用户的昵称。 - `avatar` (string, nullable)：用户的头像，可以是 Base64 编码的字符串或图片 URL，如果用户未设置头像则为 `null`。 - `addTime` (string)：用户账户的创建时间（ISO 8601 格式，例如 `YYYY-MM-DDTHH:mm:ss`）。 - `updateTime` (string)：用户信息的最后更新时间（ISO 8601 格式）。 - `bookCount` (integer)：用户的记账总数。 - **注意**：用户的密码等敏感信息不会在此接口中返回。 --- 好的，这是根据您的代码和提供的示例为您生成的四个管理员操作用户相关接口的文档。 --- #### 管理员新增用户 (接口 6) * **功能:** 管理员创建一个新的普通用户账户。 * **HTTP 方法:** `POST` * **URL:** `/api/admin/users` * **认证:** 需要管理员权限 (Bearer Token)。 * **请求头:** * `Authorization: Bearer ` * `Content-Type: application/json` * **请求体 (JSON):** ```json { "account": "hh", "username": "hh", "password": "123456", "avatar": null } ``` **字段说明:** * `account` (String, **必需**): 新用户的登录账号，长度不能超过 11 位，且不能与现有用户或管理员账号冲突。 * `username` (String, 可选): 新用户的显示昵称，长度不能超过 50 位。如果未提供，将使用 `account` 作为默认值。 * `password` (String, **必需**): 新用户的登录密码，长度至少为 6 位。 * `avatar` (String, 可选):用户的头像信息 (Base64 或 URL)，可以为 `null`。 * **成功响应 (HTTP 201 Created):** ```json { "success": true, "message": "用户创建成功", "data": { "id": 8, // 新用户的唯一 ID "account": "hh", // 新用户的账号 "username": "hh", // 新用户的用户名 "avatar": null, // 新用户的头像 "addTime": "2025-06-12T11:40:13.348838", // 创建时间 "updateTime": "2025-06-12T11:40:13.348838", // 更新时间 "bookCount": 0 // 记账数量，初始为 0 }, "code": 200 // 业务成功码 } ``` * **错误响应:** * **HTTP 409 Conflict:** 账号已存在或被管理员占用 (`"message": "账号已存在: hh"` 或 `"message": "账号已被管理员占用: hh"`)。 * **HTTP 400 Bad Request:** 请求体验证失败（如密码太短、账号超长等）。 * **HTTP 401 Unauthorized / 403 Forbidden:** 认证失败或权限不足。 * **HTTP 500 Internal Server Error:** 服务器内部错误。 --- #### 管理员删除用户 (接口 7) * **功能:** 管理员根据用户账号删除指定的普通用户。 * **HTTP 方法:** `DELETE` * **URL:** `/api/admin/users/{userAccount}` * **认证:** 需要管理员权限 (Bearer Token)。 * **请求头:** * `Authorization: Bearer ` * **URL 路径参数:** * `userAccount` (String, **必需**): 需要删除的用户的账号。 * **请求体:** 无 * **成功响应 (HTTP 200 OK):** ```json { "success": true, "message": "用户删除成功", "data": null, "code": 200 } ``` * **错误响应:** * **HTTP 404 Not Found:** 指定账号的用户不存在 (`"message": "无法删除：未找到账号为 '...' 的用户。"`). * **HTTP 401 Unauthorized / 403 Forbidden:** 认证失败或权限不足。 * **HTTP 500 Internal Server Error:** 服务器内部错误。 --- #### 管理员修改指定用户信息 (接口 10) * **功能:** 管理员修改指定账号的用户信息，可以更新用户名、账号、密码、头像、记账数。 * **HTTP 方法:** `PUT` * **URL:** `/api/admin/users/{userAccount}` * **认证:** 需要管理员权限 (Bearer Token)。 * **请求头:** * `Authorization: Bearer ` * `Content-Type: application/json` * **URL 路径参数:** * `userAccount` (String, **必需**): 需要修改的用户的 **当前** 账号。 * **请求体 (JSON):** * 所有字段均为可选，只提供需要修改的字段。 ```json { "username": "hh123", "newAccount": "hh123", "newPassword": "hh123456", "avatar": null, "bookCount": 1 } ``` **字段说明:** * `username` (String, 可选): 新的用户名，长度不能超过 50 位。 * `newAccount` (String, 可选): 新的登录账号，长度不能超过 11 位，且不能与现有用户或管理员账号冲突。如果提供了此字段，用户未来的登录和查找需要使用新账号。 * `newPassword` (String, 可选): 新的登录密码，长度至少为 6 位。 * `avatar` (String, 可选): 新的头像信息 (Base64 或 URL)。 * `bookCount` (Integer, 可选): 更新用户的记账数量。 * **成功响应 (HTTP 200 OK):** ```json { "success": true, "message": "用户信息更新成功", "data": { // 返回更新后的用户信息 "id": 8, "account": "hh123", // 注意：如果账号被修改，这里显示的是新账号 "username": "hh123", // 更新后的用户名 "avatar": null, // 更新后的头像 "addTime": "2025-06-12T11:40:13", // 创建时间（不变） "updateTime": "2025-06-12T11:41:12.573945", // 本次更新的时间 "bookCount": 1 // 更新后的记账数 }, "code": 200 } ``` * **错误响应:** * **HTTP 404 Not Found:** 指定账号的用户不存在 (`"message": "无法更新：未找到账号为 '...' 的用户。"`). * **HTTP 409 Conflict:** 提供的新账号 `newAccount` 已被其他用户或管理员占用 (`"message": "管理员更新用户失败：新账号 '...' 已被..."`). * **HTTP 400 Bad Request:** 请求体验证失败（如密码太短、账号超长等）。 * **HTTP 401 Unauthorized / 403 Forbidden:** 认证失败或权限不足。 * **HTTP 500 Internal Server Error:** 服务器内部错误。 --- #### 管理员查询指定用户的账本数据 (接口 14) * **功能:** 管理员根据用户账号查询该用户的所有记账记录。 * **HTTP 方法:** `GET` * **URL:** `/api/admin/users/{userAccount}/bookkeeping` * **认证:** 需要管理员权限 (Bearer Token)。 * **请求头:** * `Authorization: Bearer ` * **URL 路径参数:** * `userAccount` (String, **必需**): 需要查询账本的用户的账号。 * **请求体:** 无 * **成功响应 (HTTP 200 OK):** ```json { "success": true, "message": "成功获取用户账本数据", "data": [ // 返回一个 Bookkeeping 对象的数组 { "id": 1, // 记账记录 ID "type": 1, // 类型：支出 或 收入 "price": 50.00, // 金额 "category": "餐饮", // 分类 "date": "2025-06-11T10:30:00", // 记账日期时间 "remark": "午餐", // 描述 "addTime": "2025-06-11T10:31:00", // 记录添加时间 "updateTime": "2025-06-11T10:31:00" // 记录更新时间 // 注意：user 字段通常不会在此处序列化以避免循环引用 }, { // ... 其他记账记录 ... } ], "code": 200 } ``` * **注意:** `data` 数组可能为空 `[]`，如果该用户没有任何记账记录。 * **错误响应:** * **HTTP 404 Not Found:** 指定账号的用户不存在 (`"message": "用户未找到，账号: ..."`)。 * **HTTP 401 Unauthorized / 403 Forbidden:** 认证失败或权限不足。 * **HTTP 500 Internal Server Error:** 服务器内部错误。 --- #### 管理员为指定用户添加账本记录 * **Method**: `POST` * **Endpoint**: `/users/{userAccount}/bookkeeping` * **描述**: 管理员为指定账号的用户创建一条新的账本记录。 * **权限**: 需要管理员 (Admin) 权限。 **路径参数 (Path Parameters):** | 参数名 | 类型 | 描述 | 示例 | | :------------ | :----- | :------------- | :--- | | `userAccount` | String | 目标用户的账号 | `hh` | **请求体 (Request Body):** * **Content-Type**: `application/json` * **DTO**: `AdminBookkeepingCreationRequestDto` ```json { "type": 1, // Integer, 必填, 0: 收入, 1: 支出 "bookDate": "2024-06-10", // String (LocalDate), 必填, 格式: YYYY-MM-DD "category": "游戏", // String, 可选 "price": 20.00, // BigDecimal, 必填, 必须大于0 "remark": "Stream" // String, 可选 } ``` **成功响应 (Success Response):** * **状态码**: `201 Created` (业务 `code` 为 `200`) * **Content-Type**: `application/json` * **Body**: `ApiResponse` ```json { "code": 200, "success": true, "message": "管理员成功为用户添加账本记录", "data": { "id": 2, // Integer, 新创建的账本记录ID "user": null, // 在此响应中通常不包含完整的用户信息以避免循环引用或冗余，具体取决于序列化配置 "type": 1, "bookDate": "2024-06-10", "category": "游戏", "price": 20.00, "remark": "Stream", "addTime": "2025-06-14T11:00:10.018342", // LocalDateTime, 记录创建时间 "updateTime": "2025-06-14T11:00:10.018342", // LocalDateTime, 记录最后更新时间 "year": 2024, // Integer, 从bookDate自动提取 "month": 6 // Integer, 从bookDate自动提取 } } ``` **错误响应 (Error Responses):** * **`400 Bad Request`**: 请求体数据校验失败 (例如，`type` 或 `price` 缺失，`price` 不符合要求)。 ```json { "code": 400, "success": false, "message": "类型不能为空", // 或其他具体的校验错误信息 "data": null } ``` * **`401 Unauthorized`**: JWT Token 无效或缺失。 ```json { "code": 401, "success": false, "message": "认证失败: Full authentication is required to access this resource", // 或其他具体认证错误 "data": null } ``` * **`403 Forbidden`**: 当前管理员用户没有足够的权限。 ```json { "code": 403, "success": false, "message": "禁止访问", "data": null } ``` * **`404 Not Found`**: 指定的 `userAccount` 用户未找到。 ```json { "code": 404, "success": false, "message": "用户未找到，账号: hh", "data": null } ``` * **`500 Internal Server Error`**: 服务器内部错误。 ```json { "code": 500, "success": false, "message": "为用户添加账本时发生内部错误", "data": null } ``` --- #### 管理员修改指定用户的账本记录 * **Method**: `PUT` * **Endpoint**: `/users/{userAccount}/bookkeeping/{recordId}` * **描述**: 管理员修改指定账号用户的某条特定账本记录。 * **权限**: 需要管理员 (Admin) 权限。 **路径参数 (Path Parameters):** | 参数名 | 类型 | 描述 | 示例 | | :------------ | :------ | :------------------- | :--- | | `userAccount` | String | 目标用户的账号 | `hh` | | `recordId` | Integer | 要修改的账本记录的ID | `2` | **请求体 (Request Body):** * **Content-Type**: `application/json` * **DTO**: `AdminBookkeepingUpdateRequestDto` (所有字段都是可选的，只提供需要修改的字段) ```json { "type": 1, "category": "游戏", "price": 648.00, "remark": "原神", "bookDate": "2024-06-10" } ``` * **字段说明**: * `type` (Integer, 可选): 0: 收入, 1: 支出 * `bookDate` (String, 可选): 格式: YYYY-MM-DD * `category` (String, 可选) * `price` (BigDecimal, 可选): 必须大于0 (如果提供) * `remark` (String, 可选) **成功响应 (Success Response):** * **状态码**: `200 OK` * **Content-Type**: `application/json` * **Body**: `ApiResponse` ```json { "code": 200, "success": true, "message": "管理员成功修改用户账本记录", "data": { "id": 2, // Integer, 被修改的账本记录ID "user": null, "type": 1, "bookDate": "2024-06-10", "category": "游戏", "price": 648.00, // 更新后的价格 "remark": "原神", // 更新后的备注 "addTime": "2025-06-14T11:00:10.018342", // 原始创建时间不变 "updateTime": "2025-06-14T11:05:20.123456", // 更新后的时间 "year": 2024, "month": 6 } } ``` **错误响应 (Error Responses):** * **`400 Bad Request`**: 请求体数据校验失败 (例如，如果提供了 `price` 但不符合要求)。 ```json { "code": 400, "success": false, "message": "金额必须大于0", "data": null } ``` * **`401 Unauthorized`**: JWT Token 无效或缺失。 * **`403 Forbidden`**: * 当前管理员用户没有足够的权限。 * 尝试修改的账本记录不属于指定的 `userAccount` (由 `BookkeepingService` 中的权限检查抛出 `SecurityException`，Controller 层捕获并转换为 403)。 ```json { "code": 403, "success": false, "message": "无权访问该记账记录", // 或 "禁止访问" "data": null } ``` * **`404 Not Found`**: * 指定的 `userAccount` 用户未找到。 * 指定的 `recordId` 账本记录未找到。 ```json { "code": 404, "success": false, "message": "用户未找到，账号: hh", // 或 "记账记录未找到，ID: 99" "data": null } ``` * **`500 Internal Server Error`**: 服务器内部错误。 --- #### 管理员删除指定用户的账本记录 * **Method**: `DELETE` * **Endpoint**: `/users/{userAccount}/bookkeeping/{recordId}` * **描述**: 管理员删除指定账号用户的某条特定账本记录。 * **权限**: 需要管理员 (Admin) 权限。 **路径参数 (Path Parameters):** | 参数名 | 类型 | 描述 | 示例 | | :------------ | :------ | :------------------- | :--- | | `userAccount` | String | 目标用户的账号 | `hh` | | `recordId` | Integer | 要删除的账本记录的ID | `2` | **请求体 (Request Body):** * 无 **成功响应 (Success Response):** * **状态码**: `200 OK` * **Content-Type**: `application/json` * **Body**: `ApiResponse` (data 为 null) ```json { "code": 200, "success": true, "message": "管理员成功删除用户账本记录", "data": null } ``` **错误响应 (Error Responses):** * **`401 Unauthorized`**: JWT Token 无效或缺失。 * **`403 Forbidden`**: * 当前管理员用户没有足够的权限。 * 尝试删除的账本记录不属于指定的 `userAccount` (由 `BookkeepingService` 中的权限检查抛出 `SecurityException`，Controller 层捕获并转换为 403)。 ```json { "code": 403, "success": false, "message": "无权访问该记账记录", // 或 "禁止访问" "data": null } ``` * **`404 Not Found`**: * 指定的 `userAccount` 用户未找到。 * 指定的 `recordId` 账本记录未找到。 ```json { "code": 404, "success": false, "message": "用户未找到，账号: hh", // 或 "记账记录未找到或不属于该用户, 无法删除" "data": null } ``` * **`500 Internal Server Error`**: 服务器内部错误。 ---