doc: sql in README

2026-07-25 12:46:09 +08:00
parent c11a1dccf4
commit 9e9dc051d1
3 changed files with 136 additions and 83 deletions
@@ -5,6 +5,7 @@
    <option name="linkedExternalProjectsSettings">
      <GradleProjectSettings>
        <option name="externalProjectPath" value="$PROJECT_DIR$/src/beckend" />
+        <option name="gradleJvm" value="25" />
        <option name="modules">
          <set>
            <option value="$PROJECT_DIR$/src/beckend" />
@@ -0,0 +1,12 @@
+<component name="InspectionProjectProfileManager">
+  <profile version="1.0">
+    <option name="myName" value="Project Default" />
+    <inspection_tool class="PyShadowingBuiltinsInspection" enabled="true" level="WEAK WARNING" enabled_by_default="true">
+      <option name="ignoredNames">
+        <list>
+          <option value="id" />
+        </list>
+      </option>
+    </inspection_tool>
+  </profile>
+</component>
@@ -5,122 +5,123 @@
 [完整信息](./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
+    - /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/`
+### 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 操作 |
+| 端点                                         | 方法                | 功能说明                 |
+|----------------------------------------------|---------------------|--------------------------|
+| `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/`
+### 2. **人员管理 (Personnel)**

-| 端点                              | 方法                  | 功能说明             |
-|---------------------------------|---------------------|------------------|
-| `personnel/`                    | GET/POST/PUT/DELETE | 人员信息 CRUD 操作     |
+| 端点                            | 方法                | 功能说明                         |
+|---------------------------------|---------------------|----------------------------------|
+| `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              | 删除项目组（发送邮件通知）    |
+| `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/`
+### 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              | 删除凭证图片（自动删除物理文件） |
+| 端点                                              | 方法                | 功能说明                         |
+|---------------------------------------------------|---------------------|----------------------------------|
+| `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/`
+### 4. **邮件通知 (Email Notice)**

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

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

 ---

-### 5. **备忘录 (Memo)** - `/api/`
+### 5. **备忘录 (Memo)**

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

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

 ---

-### 6. **考评系统 (Evaluation)** - `/api/`
+### 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）   |
+| 端点                                    | 方法                | 功能说明                                   |
+|-----------------------------------------|---------------------|--------------------------------------------|
+| `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分）
 - 完整格式：包含详细的加分/扣分记录
@@ -130,17 +131,56 @@

 ### 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