04 · API 参考

Base URL：http://localhost:1228。数据接口统一返回 { data, success } 包裹；错误返回 { error, success: false } + 4xx/5xx。

认证（2026-08 安全强化后）：除 /api/auth/* 与 /api/error-report 外，全部端点需认证。 凭据双通道：httpOnly Cookie（浏览器，登录后自动携带）或 Authorization: Bearer <accessToken>（API 客户端）。 数据端点按用户租户隔离（只见自己的数据）；AI 端点带按用户限流。

数据 CRUD（全部需认证 + 租户隔离）

GET /api/children

列出当前用户的宝宝档案（不可见他人与种子归属数据）。401 未认证。

POST /api/children

// 请求（必填 name、birth_date）
{ "name": "小语", "birth_date": "2026-01-01", "gender": "female" }
// 201 → { data: Child }（user_id 一律取自认证令牌，传入的 user_id 被忽略）
// 400 → name/birth_date 缺失

字段白名单：name / nickname / birth_date / gender / avatar_url / current_stage；其余字段（含恶意键）静默丢弃。

PATCH /api/children/[id]

部分更新（白名单同上；id/user_id 不可变更）。404 不存在 / 403 非本人。

DELETE /api/children/[id]

删除档案，外键级联删除其成长记录/作业/里程碑/评估。404 不存在 / 403 非本人。

GET /api/growth-records

仅返回当前用户孩子集合的记录，按 recorded_at 倒序；media_urls、tags 已是结构化数组。

POST /api/growth-records

// 必填 child_id、title、content；recorded_at 缺省为当前时间
{ "child_id": "<uuid>", "type": "observation", "title": "公园社交",
  "content": "主动邀请小朋友玩耍", "media_urls": [], "tags": ["社交"] }
// 403 → child_id 不属于当前用户（防 IDOR 探测）

DELETE /api/growth-records/[id]

删除记录。404 不存在 / 403 非本人（记录 → 孩子 → 用户归属校验）。

GET /api/stats

当前用户聚合统计：data: { children, records, milestones, assessments }（首页卡片数据源）。

GET /api/homework

Query：childId、status（pending/in_progress/completed/overdue）。租户隔离同上。

POST /api/homework

必填 child_id、subject、title；status 默认 pending、priority 默认 normal。child 归属校验同上（403）。

PATCH /api/homework/[id]

部分更新；status → completed 时自动补 completed_at。404 = 任务不存在；403 = 任务属于其他用户。 id / child_id / created_at 不接受变更。

DELETE /api/homework/[id]

删除任务，{ success: true }；404 不存在 / 403 非本人。

自治核心（服务端单例）

AgenticCore 及 prediction 服务栈仅存在于服务端，客户端经此 HTTP 入口调用。

AI 代理（全部需认证 + 按用户限流，超限 429 带 Retry-After）

通用响应：401 未认证；429 超限（body 含重试秒数，头含 Retry-After）；413 体积超限。

鉴权（JWT + httpOnly Cookie）

JWT（access/refresh 携带 type 声明，不可互换）+ bcrypt。令牌主通道为 httpOnly Cookie： 登录/刷新成功时 Set-Cookie（yyc3_at path=/；yyc3_rt path=/api/auth；HttpOnly + SameSite=Lax，生产含 Secure）， 浏览器请求自动携带；API 客户端可继续用 Bearer 头与 body refreshToken（兼容保留）。

CSRF：Cookie 认证的非 GET 请求校验 Origin 同源（跨源 → 403）；Bearer 头不受影响。

# 浏览器路径：登录后 Cookie 自动携带，无需手动处理
# API 客户端路径：
TOKEN=$(curl -s -X POST /api/auth/login -H 'Content-Type: application/json' \
  -d '{"email":"a@b.c","password":"password123"}' | jq -r .data.tokens.accessToken)
curl /api/children -H "Authorization: Bearer $TOKEN"

# curl Cookie 路径：
curl -c jar -X POST /api/auth/login ... && curl -b jar /api/children

配置：JWT_SECRET（生产必设，openssl rand -hex 32；开发缺省时自动生成安装级随机密钥 data/.jwt-dev-secret）、 JWT_EXPIRES_IN（默认 2h，泄露窗口收窄；前端 401 自动刷新无感）、JWT_REFRESH_EXPIRES_IN（默认 30d）。 演示账号（仅开发/预览环境种子，生产自动跳过种入）：parent@yyc3.com / demo123456。

日志体系（Winston，P0-2 融合）

服务端日志基于 Winston + 每日轮转（移植自 YYC3-AI-Growth-Companion）：

用法：服务端路由 import { error, info } from "@/lib/logger/server"；已接入 auth 全部端点与 error-report。LOG_DIR（默认 logs/）、LOG_LEVEL（默认 dev=debug / prod=info）可配置；logs/ 已 gitignore。

错误码约定