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 鉴权（需同步更新调用方）
|