fix: Windows syslog兼容 + API设计文档

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

@@ -0,0 +1,73 @@
+# 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 鉴权（需同步更新调用方）