74 lines
2.6 KiB
Markdown
74 lines
2.6 KiB
Markdown
|
# API Token 鉴权与数据写入接口设计
|
|||
|
|
|
|||
|
|
## 概述
|
|||
|
|
|
|||
|
|
为家庭日报系统增加 Token 鉴权机制，并通过 API 支持外部写入阅读记录、感悟记录、今日计划。
|
|||
|
|
|
|||
|
|
## Token 鉴权
|
|||
|
|
|
|||
|
|
- Token 存储在 `settings.py` 的 `API_TOKEN` 配置项中
|
|||
|
|
- 请求需携带 `Authorization: Bearer <token>` 头
|
|||
|
|
- 新建 `@require_api_token` 装饰器统一校验，校验失败返回 401
|
|||
|
|
- 已有 API（`api_submit_summary`、`api_temp_upload`）同步加上鉴权（破坏性变更，需评估影响）
|
|||
|
|
|
|||
|
|
## 新增 API 端点
|
|||
|
|
|
|||
|
|
所有端点均为 POST，支持 `application/json` 和 `multipart/form-data`（文件上传场景）。统一返回格式：
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{"success": true/false, "message": "...", "id": ...}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 1. POST /api/v1/insight/submit/ - 写入感悟记录
|
|||
|
|
|
|||
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|||
|
|
|------|------|------|------|
|
|||
|
|
| content | string | 是 | 感悟内容 |
|
|||
|
|
| speaker | string | 是 | 发言人姓名，匹配 FamilyMember.name |
|
|||
|
|
| date | string | 否 | 日期 YYYY-MM-DD，默认今天 |
|
|||
|
|
| file | file | 否 | 附件 |
|
|||
|
|
|
|||
|
|
### 2. POST /api/v1/reading/submit/ - 写入阅读记录
|
|||
|
|
|
|||
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|||
|
|
|------|------|------|------|
|
|||
|
|
| type | string | 是 | 阅读类型，匹配 ReadingType.name |
|
|||
|
|
| title | string | 是 | 标题 |
|
|||
|
|
| source | string | 否 | 来源 |
|
|||
|
|
| progress | string | 否 | 进度 |
|
|||
|
|
| note | string | 否 | 阅读笔记 |
|
|||
|
|
| date | string | 否 | 日期 YYYY-MM-DD，默认今天 |
|
|||
|
|
| file | file | 否 | 附件 |
|
|||
|
|
|
|||
|
|
### 3. POST /api/v1/plan/submit/ - 写入今日计划
|
|||
|
|
|
|||
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|||
|
|
|------|------|------|------|
|
|||
|
|
| content | string | 是 | 计划内容 |
|
|||
|
|
| speaker | string | 否 | 发言人，默认"机器人" |
|
|||
|
|
| priority | string | 否 | 优先级，匹配 Priority.name，默认"中" |
|
|||
|
|
| type | string | 否 | 类型，匹配 PlanType.name，默认"其他" |
|
|||
|
|
| status | string | 否 | 状态，匹配 Status.name，默认"未开始" |
|
|||
|
|
| date | string | 否 | 日期 YYYY-MM-DD，默认今天 |
|
|||
|
|
|
|||
|
|
## 实现范围
|
|||
|
|
|
|||
|
|
- `diary_family/settings.py`：新增 `API_TOKEN` 配置
|
|||
|
|
- `core/views.py`：新增 `require_api_token` 装饰器、3 个 API 视图函数
|
|||
|
|
- `core/urls.py`：新增 3 条路由
|
|||
|
|
- 不引入 DRF，沿用项目现有 JsonResponse + 函数视图模式
|
|||
|
|
- 不涉及数据库迁移
|
|||
|
|
|
|||
|
|
## 错误处理
|
|||
|
|
|
|||
|
|
- 401：Token 缺失或错误
|
|||
|
|
- 400：必填字段缺失、外键匹配失败
|
|||
|
|
- 405：非 POST 请求
|
|||
|
|
- 500：服务器内部错误
|
|||
|
|
- 所有错误统一返回 `{"success": false, "message": "错误描述"}`
|
|||
|
|
|
|||
|
|
## 向后兼容
|
|||
|
|
|
|||
|
|
- 已有 Web 页面功能不受影响
|
|||
|
|
- 已有 API 端点加上 Token 鉴权（需同步更新调用方）
|