diff --git a/.idea/vcs.xml b/.idea/vcs.xml index ef2fda2..35eb1dd 100644 --- a/.idea/vcs.xml +++ b/.idea/vcs.xml @@ -2,6 +2,5 @@ - \ No newline at end of file diff --git a/API.md b/API.md new file mode 100644 index 0000000..647412e --- /dev/null +++ b/API.md @@ -0,0 +1,138 @@ +# http://localhost:8080/api + +所有返回的json对象总有如下格式 + +```typescript +class respose { + "code": number; + "message": string; + "data": T +} +``` + +接下来将省略`/api`并只给出`T`的类声明 + +当`"code"`不是`200`时，`"data"`必定为`null` + +部分`/api/test`的返回值不遵循上述格式 + +## /test + +### GET /hello + +Authorization: Bearer $Token + +key: 无 + +回复： + +```typescript +"Hello Kotlin WebFlux!" +``` + +## /v1/auth + +### POST /login + +Authorization: 无 + +key: username, password + +data： + +```typescript +class data { + "username": string; + "role": string; + "token": string; + "expire": Date; +} +``` + +### GET /logout + +Authorization: Bearer $Token + +key: 无 + +data： + +```typescript +null +``` + +### GET /ask-code?email=******&type=register + +Authorization: 无 + +key: 无 + +data： + +```typescript +null +``` + +### GET /ask-code?email=******&type=reset + +Authorization: 无 + +key: 无 + +data： + +```typescript +null +``` + +### POST /register + +Authorization: 无 + +key: 无 + +data：email, code, username, password + +```typescript +null +``` + +### POST /reset + +Authorization: 无 + +key: email, code, password + +data： + +```typescript +null +``` + +### GET /relogin + +Authorization: Bearer $Token + +key: 无 + +data： + +```typescript +class data { + "token": sting; + "expire": time +} +``` + +# ws://localhost:8080/ws + +几乎所有的ws请求都需要先在`http`请求中获取`ticket` + +## /test + +回复： + +```typescript +`Kotlin springboot4 received: ${userText}` +``` + diff --git a/README.md b/README.md index 509c5f7..aad6db3 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,137 @@ # itstudio_manager +## 目前完成的 API 列表 + +[完整信息](./API.md) + +- /api + - /test + - /hello + - /v1 + - /auth + - /login + - /logout + - /relogin + - /ask-code + - /register + - /reset +- /ws + - /test + +## 预计完成的 API 列表 + +### 1. **物品管理 (Items)** - `/api/` + +| 端点 | 方法 | 功能说明 | +|---------------------------------|---------------------|----------------| +| `items/` | GET/POST/PUT/DELETE | 物品 CRUD 操作 | +| `items/{id}/upload_images/` | POST | 上传物品图片 | +| `items/{id}/set_primary_image/` | POST | 设置主图片 | +| `items/{id}/borrow/` | POST | 借用物品 | +| `items/{id}/return_item/` | POST | 归还物品 | +| `items/available/` | GET | 获取可用物品列表 | +| `items/in_use/` | GET | 获取使用中的物品列表 | +| `usages/` | GET/POST/PUT/DELETE | 物品使用记录 CRUD 操作 | +| `usages/{id}/upload_images/` | POST | 上传使用记录图片 | +| `usages/current/` | GET | 获取当前使用中的记录 | +| `usages/by_user/` | GET | 根据用户姓名获取使用记录 | +| `item_categories/` | GET/POST/PUT/DELETE | 物品类别 CRUD 操作 | +| `users/` | GET | 获取用户列表（只读） | +| `item-images/` | GET/POST/PUT/DELETE | 物品图片 CRUD 操作 | +| `usage-images/` | GET/POST/PUT/DELETE | 使用记录图片 CRUD 操作 | + +--- + +### 2. **人员管理 (Personnel)** - `/api/` + +| 端点 | 方法 | 功能说明 | +|---------------------------------|---------------------|------------------| +| `personnel/` | GET/POST/PUT/DELETE | 人员信息 CRUD 操作 | +| `personnel/statistics/` | GET | 获取人员统计信息（按部门和职位） | +| `personnel/{id}/set_inactive/` | POST | 设置人员为已卸任状态 | +| `personnel/{id}/set_active/` | POST | 设置人员为在职状态 | +| `personnel/{id}/` | DELETE | 删除人员（发送邮件通知） | +| `personnel/check_expired/` | POST | 检查并更新已到期的人员状态 | +| `project-groups/` | GET/POST/PUT/DELETE | 项目组 CRUD 操作 | +| `project-groups/by_department/` | GET | 按部门获取项目组 | +| `project-groups/{id}/` | DELETE | 删除项目组（发送邮件通知） | + +**搜索/过滤字段**: `name`, `student_id`, `phone`, `email`, `grade_major` + +--- + +### 3. **财务管理 (Finance)** - `/api/` + +| 端点 | 方法 | 功能说明 | +|-------------------------------|---------------------|------------------| +| `finance/` | GET/POST/PUT/DELETE | 财务记录 CRUD 操作 | +| `finance/{id}/upload_images/` | POST | 上传财务凭证图片 | +| `finance/{id}/` | DELETE | 删除财务记录（发送邮件通知） | +| `departments/` | GET/POST/PUT/DELETE | 部门 CRUD 操作 | +| `departments/{id}/` | DELETE | 删除部门（发送邮件通知） | +| `finance_categories/` | GET/POST/PUT/DELETE | 财务分类 CRUD 操作 | +| `proof-images/` | GET/POST/PUT/DELETE | 财务凭证图片 CRUD 操作 | +| `proof-images/{id}/` | DELETE | 删除凭证图片（自动删除物理文件） | + +--- + +### 4. **邮件通知 (Email Notice)** - `/api/` + +| 端点 | 方法 | 功能说明 | +|------|------|--------| +| `notification-settings/` | GET/POST | 获取/更新通知设置和邮箱列表 | +| `toggle-email-status/` | POST | 切换邮箱启用/禁用状态 | + +**功能**: 管理邮件通知的全局开关和收件人列表 + +--- + +### 5. **备忘录 (Memo)** - `/api/` + +| 端点 | 方法 | 功能说明 | +|----------------------------|---------------------|-------------| +| `memos/` | GET/POST/PUT/DELETE | 备忘录 CRUD 操作 | +| `memos/{id}/upload_image/` | POST | 上传备忘录图片 | +| `memos/{id}/delete_image/` | DELETE | 删除备忘录图片 | + +**搜索字段**: `title`, `content` +**默认排序**: 按更新时间倒序 + +--- + +### 6. **考评系统 (Evaluation)** - `/api/` + +| 端点 | 方法 | 功能说明 | +|-----------------------------------------|---------------------|------------------------| +| `evaluation-records/` | GET/POST/PUT/DELETE | 考评记录 CRUD 操作 | +| `evaluation-records/personnel-summary/` | GET | 获取人员考评汇总（按人员、部门、年级分组） | +| `evaluation-records/personnel-records/` | GET | 获取某个人员的所有考评记录 | +| `evaluation-records/delete-personnel/` | DELETE | 删除某个人员的所有考评记录 | +| `evaluation-records/export/` | GET | 导出考评记录为 Excel（每个人一个表格） | +| `evaluation-records/download-template/` | GET | 下载人员导入样表 | +| `evaluation-records/import/` | POST | 导入考评记录（支持 Excel/CSV） | + +**功能**: +- 支持批量导入和导出 +- 样表格式：只需部门、年级、姓名（初始分39分） +- 完整格式：包含详细的加分/扣分记录 +- 所有操作发送邮件通知 + +--- + +### 7. **认证相关** + +| 端点 | 方法 | 功能说明 | +|----------------------|----------|-------------| +| `api/token/` | POST | JWT 令牌获取 | +| `api/token/refresh/` | POST | JWT 令牌刷新 | +| `admin/` | GET/POST | Django 管理后台 | + +--- + +## 认证方式 + +所有 API 均使用 **JWT 认证**（除了需要特殊处理的端点）： +``` +Authorization: Bearer +```