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)**

| 端点                                         | 方法                | 功能说明                 |
|----------------------------------------------|---------------------|--------------------------|
| `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)**

| 端点                            | 方法                | 功能说明                         |
|---------------------------------|---------------------|----------------------------------|
| `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)**

| 端点                                              | 方法                | 功能说明                         |
|---------------------------------------------------|---------------------|----------------------------------|
| `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)**

| 端点                     | 方法     | 功能说明                    |
|--------------------------|----------|-----------------------------|
| `notification-settings/` | GET/POST | 获取/更新通知设置和邮箱列表 |
| `toggle-email-status/`   | POST     | 切换邮箱启用/禁用状态       |

**功能**: 管理邮件通知的全局开关和收件人列表

---

### 5. **备忘录 (Memo)**

| 端点                       | 方法                | 功能说明         |
|----------------------------|---------------------|------------------|
| `memos/`                   | GET/POST/PUT/DELETE | 备忘录 CRUD 操作 |
| `memos/{id}/upload_image/` | POST                | 上传备忘录图片   |
| `memos/{id}/delete_image/` | DELETE              | 删除备忘录图片   |

**搜索字段**: `title`, `content`  
**默认排序**: 按更新时间倒序

---

### 6. **考评系统 (Evaluation)**

| 端点                                    | 方法                | 功能说明                                   |
|-----------------------------------------|---------------------|--------------------------------------------|
| `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. **认证相关**

这是原先的 Django REST Framework JWT 认证端点，主要用于获取和刷新 JWT 令牌。
现在改用 `/api/v1/auth/` 端点来处理登录、注册、重置密码等操作。

| 端点                 | 方法     | 功能说明        |
|----------------------|----------|-----------------|
| `api/token/`         | POST     | JWT 令牌获取    |
| `api/token/refresh/` | POST     | JWT 令牌刷新    |
| `admin/`             | GET/POST | Django 管理后台 |

---

#### 认证方式

所有 API 均使用 **JWT 认证**（除了需要特殊处理的端点）

```
Authorization: Bearer <token>
```

## 数据库结构

[schema.sql](./schema.sql)

- users (系统用户/认证信息)
- departments (组织/部门)
    - parent_id -> departments.id (自关联父级)
- personnel (人员信息)
    - user_id -> users.id
    - department_id -> departments.id
- categories (物品类别)
    - parent_id -> categories.id (自关联父级)
- items (物品基本信息)
    - category_id -> categories.id
    - created_by -> personnel.id
- item_transactions (物品出入库流水)
    - item_id -> items.id (ON DELETE CASCADE)
    - operator_id -> personnel.id
- borrow_records (借用/归还记录)
    - item_id -> items.id (ON DELETE CASCADE)
    - borrower_id -> personnel.id (ON DELETE CASCADE)
    - approver_id -> personnel.id
- memos (备忘/备注)
    - author_id -> personnel.id
    - related_item_id -> items.id
- finance_records (财务相关记录)
    - related_item_id -> items.id
    - recorded_by -> personnel.id
- email_notices (邮件通知规则/历史)
- evaluations (物品/服务评价)
    - related_item_id -> items.id
    - evaluator_id -> personnel.id
- attachments (文件附件存储索引表)
    - uploaded_by -> personnel.id