forked from ITStudio_OUC/itstudio_manager
doc: API.md
This commit is contained in:
server_main
Generated
-1
@@ -2,6 +2,5 @@
|
||||
<project version="4">
|
||||
<component name="VcsDirectoryMappings">
|
||||
<mapping directory="" vcs="Git" />
|
||||
<mapping directory="$PROJECT_DIR$/src/beckend/Springboot4-Vue3_Demo" vcs="Git" />
|
||||
</component>
|
||||
</project>
|
||||
@@ -0,0 +1,138 @@
|
||||
# http://localhost:8080/api
|
||||
|
||||
所有返回的json对象总有如下格式
|
||||
|
||||
```typescript
|
||||
class respose<T> {
|
||||
"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}`
|
||||
```
|
||||
|
||||
@@ -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 <token>
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user