diary-family/docs/superpowers/specs/2026-06-07-api-token-auth-design.md

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（文件上传场景）。统一返回格式：

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