itstudio_manager/README.md

# itstudio_manager

## 目前完成的 API 列表

[完整信息](./API.md)

- /api
  - /test
    - /hello
  - /v1
    - /auth
      - /login
      - /logout
      - /relogin
      - /ask-code
      - /register
      - /reset
    - /departments
    - /email
    - /evaluation-records
    - /finance
    - /items
    - /memos
    - /personnel
    - /project-groups
    - /proof-images
    - /usages
    - /users

## 预计完成的 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                 | 根据用户姓名获取使用记录   |
| `items/categories/`（原 `item_categories/`） | GET/POST/PUT/DELETE | 物品类别 CRUD 操作   |
| `users/`                        | GET                 | 获取用户列表（只读）     |
| `items/images/`（原 `item-images/`）         | GET/POST/PUT/DELETE | 物品图片 CRUD 操作   |
| `usages/images/`（原 `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/`（原 `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>
```