知岛学习 · 接口文档（导出）

AI 能力

1v1 可视化讲解

WS /ws/lecture

单条 WS 承载讲题：JSON 文本帧（题干/分段/结束）+ 二进制音频帧。

流式语音识别

WS /ws/asr

反代豆包 SAUC，PCM 上行、partial/final 文本下行。握手需 ?token=（见鉴权设计）。

端到端实时语音对话（豆包 O2.0）

WS /ws/realtime-dialog

反代火山「实时对话」端到端大模型，一条 WS 内同时做 ASR+LLM+TTS（密钥只在后端）。浏览器先发 {type:'start'} → 后端读后台语音设置(app_voice_dialog_settings)建上游会话并念开场白 → 浏览器上行二进制麦克风 PCM(16k/16bit/mono)、下行二进制 TTS 音频(24k/16bit/mono) + JSON 控制帧。用户出声自动打断(barge-in)。每轮 user(ASR)/assistant(AI) 文本落库 app_voice_dialog_*。握手需 ?token=。人设/开场白/风格/音色/联网/唱歌在管理后台「语音对话设置」配置（默认 K12 教师角色「知岛老师」）。可选 ?scene= 选场景人设（缺省=K12 老师；spoken_en_pron=英语发音教练；spoken_en_scene=英语情景对话），供英语「练口语」复用同一 WS 而注入不同英文人设。

拍照切题（cutQuestions）

POST /api/photo-qa/cut

收图片 base64 → 上传火山 TOS 拿公网 URL → 调阿里云百炼 EduTutor cutQuestions 切题。返回每题外框四角点 + 题干/选项/题型 + 配图裁剪 URL。需登录（Bearer）。

拍照讲题·讲解（AnswerSSE 流式）

WS /ws/photo-qa/explain

首帧 JSON {questionText|cropUrl, depth:'fast'极速|'deep'深度, grade?, subject?} → 反代阿里云百炼 AnswerSSE 流式讲解。下行 {t:'begin'} → 多个 {t:'delta',text} → {t:'done'}；出错 {t:'error',msg}。握手需 ?token=。极速=简短答案，深度=分步【考点分析/方法点拨/详细解析】含 LaTeX。

拍照答疑·切题+AI修正（流式）

WS /ws/photo-qa/scan

一条 WS 跑完整管线：收图(首帧 JSON {imageBase64, mime?}) → 上传 TOS → 阿里云 cutQuestions 切题 → 落库 session+N 题(pending) → 立刻下行 cut(N 题骨架，前端渲染加载卡) → 有界并发逐题「AI 修正」(整题截图+OCR 文本喂视觉模型，纠错+公式转 LaTeX+结构化+裁配图) → 每题完成下行 question → 全部完成 done。握手需 ?token=。修正只做展示、不做标记（标记在 1v1 讲解阶段）。

拍照答疑·会话复看

GET /api/photo-qa/session/{session_id}

读回某次拍照扫描的 session + 题目（含已修正内容），供前端重开/断连恢复，以及后续 1v1 讲解按 dbId 取题。需登录(Bearer)，仅本人会话。

拍照答疑·历史记录列表

GET /api/photo-qa/sessions

列出本人「已完成(status=done)」的拍照答疑会话（按时间倒序），供相机页「历史记录」整屏页展示。点一条再调 /api/photo-qa/session/{id} 复看。需登录(Bearer)，仅本人记录。

拍照题·按住提问（单轮语音答疑）

POST /api/photo-qa/ask

拍照讲题结果页「按住提问」：前端用 SAUC 流式 ASR(/ws/asr) 把语音转文字后，调本接口针对当前题做单轮答疑。复用主讲解 LLM(llm_client.complete)；题带配图(figure_url)时走多模态(complete_vision)。答案口语化、适合 TTS 朗读。需登录(Bearer)。

文本转语音（答案朗读）

POST /api/photo-qa/tts

把一段文本合成语音返回。复用 tts_doubao.stream_pcm 收齐裸 PCM(24k/16bit/mono)补 WAV 头，返回 audio/wav，便于前端 new Audio(blob) 直接播。给拍照题「按住提问」朗读答案用。文本上限 800 字。需登录(Bearer)。

拍照答疑·语音输入诊断上报

POST /api/photo-qa/asr-log

「按住说话」客户端诊断上报：前端每次录音结束把采集情况上报，落「AI 流程日志」(flow=asr)，便于真机排错——一眼判断卡在「没采到音频/没上行/后端没识别」哪一环。仅诊断、不参与业务。需登录(Bearer)。

拍照答疑·语音回放诊断

POST /api/photo-qa/asr-replay

回放诊断：客户端把本次采集的原始 16k/16bit/mono PCM(application/octet-stream)发上来，服务端用同款豆包 SAUC 重新识别这段字节，并把 WAV 存 TOS 便于人工试听，结果记入「AI 流程日志」(flow=asr「[回放诊断]」)。判读：服务端能识别→字节没问题、问题在前端流式时序；识别不出→字节/重采样坏了。需登录(Bearer)。

拍照翻译·识别翻译

POST /api/photo-translate/run

收图片 base64 → 上传火山 TOS 拿公网 URL → 调阿里云百炼 AnyTrans（SubmitImageTranslateTask 提交 + GetImageTranslateTask 轮询到 success）整图翻译（默认英→中）→ 落库 session+N 文字区域框 → 返回原图 URL + 坐标系 + 每个文字区域的四角坐标 + 原文 + 译文。前端在原图上叠加可点框、点框看译文。需登录(Bearer)。

拍照翻译·会话复看

GET /api/photo-translate/session/{session_id}

读回某次拍照翻译的 session + 全部文字区域框（含原文/译文/坐标），供历史复看/断连恢复。需登录(Bearer)，仅本人。

拍照翻译·历史记录列表

GET /api/photo-translate/sessions

列出本人拍照翻译会话（按时间倒序），供相机页「历史」整屏页展示。点一条再调 /api/photo-translate/session/{id} 复看。需登录(Bearer)，仅本人记录。

拍照翻译·取词翻译

POST /api/photo-translate/word

取词翻译：传入单个英文单词 → LLM 返回音标(英/美)+词性+中文释义（进程内 TTL 缓存，避免重复调用）。需登录(Bearer)。

拍照翻译·原文点读

POST /api/photo-translate/tts

把一段文本合成语音返回 audio/wav。文本无中文字符时默认用英文音色(tts_speaker_en)，否则中文音色；给结果页「原文点读/连读」朗读英文原文用。文本上限 800 字。需登录(Bearer)。

作业批改·整卷批改（流式）

WS /ws/grading/correct

一条 WS 跑完整管线：收图(首帧 JSON，二选一：{images:[{imageBase64,mime?}], 1~3 张} 拍照/相册 base64，逐张上传火山 TOS；或 {imageUrls:[...], 1~3 张} 已是带路径的 http/https 公网图，直传上游、跳过上传，用于「用示例体验」/外部已传) → 后端代理上游 V4 智能整卷批改同步接口(POST {smart_correction_base}/api/v4/smart_correction，默认 IP http://118.145.245.205:8000)的 SSE 流 → 把上游事件转译为下行帧：先 image(合并图) → cut(N 题骨架，前端停识别动画、渲染加载卡) → 每题 processing/question(逐题完成即渲染) → done(汇总)。落库 app_homework_*。握手需 ?token=。整卷实测 P50 ~54s(5 题)，超时 300s。前端不直连上游(明文 http + mixed-content)。

作业批改·会话复看

GET /api/grading/session/{session_id}

读回某次整卷批改的 session + 题目（含每题批改/OCR 结果），供重开/断连恢复/错题溯源。需登录(Bearer)，仅本人。

作业批改·历史记录列表

GET /api/grading/sessions

列出本人「已完成(status=done)」的作业批改会话（按时间倒序），供相机页「历史记录」整屏页展示。缩略图优先合并图、否则取首张原图。点一条再调 /api/grading/session/{id} 复看。需登录(Bearer)，仅本人记录。

错题本·加入（单/批量）

POST /api/grading/wrong-book/add

把作业批改(或其它来源)的错题加入错题本(app_wrong_questions)。需登录(Bearer)。

错题本·列表

GET /api/grading/wrong-book

列当前用户错题本(按时间倒序，可按 subject 过滤)。供「我的→AI 错题本」。需登录(Bearer)。

错题本·按学科统计

GET /api/grading/wrong-book/counts

按学科 key 统计错题数(错题本首页徽标)。需登录(Bearer)。

作文批改·提交

POST /api/essay/submit

收作文图 base64 → 上传火山 TOS 拿公网 URL → 调腾讯云 OCR SubmitMarkEssayAgentJob 提交批改任务 → 插一行 running 并起后台任务（轮询 DescribeMarkEssayAgentJob 到 DONE）→ 立即返回 sessionId。前端凭 sessionId 轮询 /api/essay/result。lang 由入口决定(语文 zh/英语 en)。需登录(Bearer)。本期纯腾讯优先：视觉 LLM 整体评分默认关闭(essay_use_llm_score=False, scoring 恒 null)，整体评分后续自研。腾讯原始请求/响应整段落 app_essay_sessions.raw_request/raw_result + AI 流程日志(flow=essay)，供后续自研直接读。

作文批改·轮询结果

GET /api/essay/result/{session_id}

前端每 ~2.5s 轮询。running=继续转圈；done=渲染（原图按 suggests[].positions 四边形坐标画可点热区，点击弹该处批改详情；scoring 本期恒为 null，整体评分后续自研）；failed=报错可重拍。需登录(Bearer)，仅本人会话。

作文批改·历史记录列表

GET /api/essay/sessions

作文批改相机页右上「历史」：列出本人已完成（status=done）的作文批改会话，倒序，含缩略图 + 批改处数 + 时间。lang=zh/en 仅看对应语种（语文页/英语页各自过滤），省略看全部。点一条复看走 GET /api/essay/result/{id}。需登录(Bearer)，仅本人会话。

AI老师·小思对话（流式 qwen3-max）

WS /ws/ai-chat

请求/应答式多轮聊天。前端持有完整对话数组，每轮发一条 ask；后端组装【小思系统提示 + 历史 + 本轮】流式跑 qwen3-max，逐 token 回 delta，结束回 done。后端每轮无状态（上下文由前端带来），但把 user/assistant 两条消息落库 app_chat_* 供历史回看。纯文本流，前端用 MarkdownView 渲染 Markdown+LaTeX。握手需 ?token=。

小思·拍照看图上传

POST /api/ai-teacher/upload-image

小思「拍照看图」：上传图片 base64 → 火山 TOS → 返回公网 URL。再把该 URL 随 WS /ws/ai-chat 的 ask.imageUrl 发出，小思用 qwen-vl 视觉模型看图回答。需登录(Bearer)。走 REST 上传避免把大 base64 塞进 WS 帧。

小思·对话历史列表

GET /api/ai-teacher/sessions

当前用户的对话历史，按最近消息倒序。需登录(Bearer)。query: limit(默认50,≤100)。

小思·读历史会话消息

GET /api/ai-teacher/sessions/{session_id}/messages

读回某次对话的全部消息（按顺序），供重新打开历史会话。需登录(Bearer)，仅本人。

小思·删除历史会话

DELETE /api/ai-teacher/sessions/{session_id}

删除一条历史会话（级联删消息）。需登录(Bearer)，仅本人。

小思·重命名历史会话

PATCH /api/ai-teacher/sessions/{session_id}

重命名历史会话。需登录(Bearer)，仅本人。body: {title}。

学字词·教材册列表

GET /api/hanzi/books

选教材册（语文，小学/初中）。后端代理智慧校园平台 GET /api/hanzi/books，透传学生本人 Bearer。默认只回已上架 status=启用。见 docs/汉字字词数据对接.md。需登录(Bearer)。

学字词·整册字词（分组+发音）

GET /api/hanzi/book/{textbook_id}

一次取整册全部字+词，按 versionPath（「单元 / 课文」）分组成 units→lessons→items，并规范化成前端 wordlearn 详情 item 形态（type=char/word），含预生成发音直链 audioUrl。一份载荷驱动「同步识字」单元页与字词详情页。后端代理平台 GET /api/hanzi?textbook_id=&size=2000，透传学生 Bearer。需登录(Bearer)。

字词听写·写入错题本

POST /api/hanzi/dictation/mistakes

字词听写自批判错的字/词写入本端错题本（app_word_dictation_mistakes）。按 用户+册+课+字词 去重 upsert（重练刷新）。需登录(Bearer)。表见 docs/本端数据库表/字词听写错题表.md。

字词听写·错题列表

GET /api/hanzi/dictation/mistakes

列出当前用户的听写错题（可按册过滤，时间倒序）。需登录(Bearer)。

字词听写·删除错题

DELETE /api/hanzi/dictation/mistakes/{mistake_id}

删除一条听写错题（订正/已掌握）。仅能删本人。需登录(Bearer)。

字词听写·手写字形+笔顺分析(多模态)

POST /api/hanzi/dictation/analyze

听写自批：把学生手写图（笔画起点带书写顺序编号，纯 base64/data URL）交多模态模型（settings.hanzi_analyze_model，默认 qwen3.7-plus）判「字形」是否正确 + 「笔顺」是否正确 + 一句点评。需登录(Bearer)。AI 流程日志 flow=hanzi_handwriting_analyze。失败回 502，前端回退本地笔顺(hanzi-writer)+人工自批。

语文作文·教材册列表

GET /api/zuowen/books

选作文教材册（语文，小学习作/初中写作实践）。后端代理智慧教育平台 GET /api/zuowen/books，透传学生本人 Bearer。默认只回已上架 status=启用。见 docs/资源系统对接/作文管理对接指南.md。需登录(Bearer)。短 TTL 缓存(10min)，fresh=1 旁路。

语文作文·整册作文题（按单元分组）

GET /api/zuowen/book/{textbook_id}

一次取整册作文题摘要，按 unitName 分组成 units→topics，并按平台目录树 ordinal 排序单元。驱动「同步作文」列表页。后端代理平台 GET /api/zuowen?textbook_id=&size=200（+ /units 取排序），透传学生 Bearer。需登录(Bearer)。长 TTL 缓存(6h)，fresh=1 旁路。

语文作文·单题详情（写作要求+5类素材）

GET /api/zuowen/task/{task_id}

取单个作文题完整内容：写作要求 requirement（分点，\n 换行）+ AI 写作素材 materials（规范成 5 个固定分组：标题妙引/好词添彩/好句生辉→字符串数组；首尾锦绣→[{kind,text}]；选材案例→[{tag,text}]）。驱动写作指导页/素材页/AI 话题辅导。后端代理平台 GET /api/zuowen/{id}，透传学生 Bearer。需登录(Bearer)。长 TTL 缓存(6h)，fresh=1 旁路。

试卷库·卷型字典（筛选项来源）

GET /api/shijuan/paper-types

各场景 Tab 下的试卷类型名分组，给 browse 的 tab/type 填合法选项。后端代理平台 GET /api/papers/paper-types，透传学生本人 Bearer。需登录(Bearer)。长 TTL 缓存(1h)，fresh=1 旁路。

试卷库·主列表（三库统一，分页）

GET /api/shijuan/browse

试卷库主检索：金字塔(jzt 约25万)+学科网整卷+本校卷统一检索、分页（每页固定 10 条）。后端代理平台 GET /api/papers/browse，透传学生 Bearer。需登录(Bearer)。短 TTL 缓存(5min)，fresh=1 旁路。返回 items 的 id 含前缀（jzt_/xk_/uuid），取详情时原样回传给 /preview。

试卷库·整卷逐题详情（核心）

GET /api/shijuan/{paper_id}/preview

取整卷+逐题内容（题号/题型/题干/答案/解析，均为可直接渲染的 HTML，含公式图 <img class=xkw-math-img>）。paper_id 三形态（jzt_/xk_/uuid）原样回传，平台内部分流。后端代理平台 GET /api/papers/{id}/preview，透传学生 Bearer。需登录(Bearer)。长 TTL 缓存(6h)，fresh=1 旁路。金字塔 jzt_ 卷 answer 恒空（答案并入 explanation）；xk_ 学科网卷首取会回源（较慢且计费），之后走缓存。

背单词·英语教材册列表

GET /api/words/books

选英语教材册（小学/初中/高中）。后端代理智慧教育平台 GET /api/words/books，透传学生本人 Bearer。默认只回已上架 status=启用。见 docs/资源系统对接/单词管理对接指南.md。需登录(Bearer)。短 TTL 缓存(10min)，fresh=1 旁路。

背单词·单元章节树

GET /api/words/books/{textbook_id}/chapters

取该教材的单元/课时嵌套章节树 + 各节点单词数，用于按单元取词（catalog_id）。后端代理平台 GET /api/words/books/{id}/chapters，透传学生 Bearer。需登录(Bearer)。长 TTL 缓存(6h)，fresh=1 旁路。

背单词·单词列表（音标/词性/释义/例句/配图/发音状态）

GET /api/words

按教材/单元/关键词取单词，每项含完整字段。后端代理平台 GET /api/words，透传学生 Bearer。需登录(Bearer)。需提供 textbook_id / catalog_id / keyword 之一。长 TTL 缓存(6h)，fresh=1 旁路。

背单词·发音惰性合成（美/英）

POST /api/words/{word_id}/tts

取单词发音（豆包 TTS 惰性合成 + 缓存）。后端代理平台 POST /api/words/{id}/tts，透传学生 Bearer。需登录(Bearer)。返回 TOS 公网直链 .wav，前端可直接 <audio> 播放（无需鉴权）。

背单词·该册学习概况（含计划）

GET /api/words/progress

取当前用户某册学习概况（本端库 app_word_learning + app_word_plan）：已新学/已复习/已掌握/待复习数、今日新学·复习数（按 Asia/Shanghai 自然日）、计划天数（未设置为 0）。首页「已新学/已复习/剩余天数/今日配额/去复习按钮」全部吃本接口。需登录(Bearer)。表见 docs/本端数据库表/单词学习进度表.md、docs/本端数据库表/单词学习计划表.md。

背单词·复习队列（艾宾浩斯间隔重复）

GET /api/words/review

取当前用户某册复习候选词 + 已学释义池（前端造复习题干扰项）+ 已学词id（剔除已学）。scope=due（默认）：仅到期词（next_review_at<=now，最早优先），「去复习」用；scope=mix：到期词优先、不足 limit 时用最近学过的旧词补足，「去学习」低频穿插旧词用。需登录(Bearer)。

背单词·设置学习计划天数

POST /api/words/plan

设置当前用户某册背词计划天数（upsert 到本端 app_word_plan，1-365）。每日新词量 = 该册总词数 ÷ 计划天数（前端派生）；选词书弹层「计划天数」确定时调用。需登录(Bearer)。表见 docs/本端数据库表/单词学习计划表.md。

背单词·回写学习/复习结果

POST /api/words/progress

回写学习/复习结果（按 用户+单词 去重 upsert，驱动 SM-2 lite 间隔重复：对→连对+1延长间隔/连对达阈值置掌握，错→连对归零明天重练）。需登录(Bearer)。

单词听写·手写拼写识别(多模态)

POST /api/words/dictation/analyze

单词听写自批：把学生四线格手写图（纯 base64/data URL）交多模态模型（settings.hanzi_analyze_model，默认 qwen3.7-plus，与汉字听写共用）做纯识别，拼写对错由后端比对识别结果与目标词得出。⚠️ 不把目标词喂给模型（规避确认偏置：潦草手写被一律判对）。没认出手写时 spellingCorrect=null、recognizable=false，前端转人工判定（不默认判对）。需登录(Bearer)。AI 流程日志 flow=words_handwriting_analyze。失败回 502，前端回退人工自批。

课文背诵·教材册列表

GET /api/kewen/books

选语文课文教材册（小学/初中/高中）。后端代理平台 GET /api/kewen/books，透传学生本人 Bearer。默认 status=启用。需登录(Bearer)。

课文背诵·某册需背诵课文列表

GET /api/kewen/poems

取某教材册「需背诵」课文摘要（古诗/词/曲/文言文等）。代理平台 GET /api/kewen?textbook_id=&size=500。需登录(Bearer)。

课文背诵·单篇详情（规范化）

GET /api/kewen/{poem_id}

单篇课文：逐字拼音 lines + 三路朗读音频(原文/译文/讲解) + AI 配图 + 译文 + 讲解。代理平台 GET /api/kewen/{id} 并规范化（逐行拼音→逐字对齐）。需登录(Bearer)。

课文背诵·语音评分

POST /api/kewen/recite/grade

把 ASR(/ws/asr) 识别文本与课文原文逐字比对(difflib + pypinyin 同音宽容)→分数/错字坐标/星级，并落库背诵记录+错题本。需登录(Bearer)。

课文背诵·我的背诵汇总

GET /api/kewen/recite/records

每篇课文最佳分/星级/最近时间/次数（列表徽标用）。需登录(Bearer)。

课文背诵·背诵错题列表

GET /api/kewen/recite/mistakes

当前用户背诵背错的字（可按课文过滤，时间倒序）。需登录(Bearer)。

课文背诵·删除背诵错题

DELETE /api/kewen/recite/mistakes/{mistake_id}

删除一条背诵错题（订正/已掌握）。仅能删本人。需登录(Bearer)。

读课文·教材册列表

GET /api/en-kewen/books

选英语课文教材册（小学/初中/高中）。后端代理平台 GET /api/en-kewen/books，透传学生本人 Bearer。默认 status=启用。需登录(Bearer)。

读课文·单元目录树

GET /api/en-kewen/books/{textbook_id}/chapters

某册英语课文单元/课时嵌套目录树（选单元导航用，可选）。代理平台 GET /api/en-kewen/books/{id}/chapters。需登录(Bearer)。

读课文·某册课文列表

GET /api/en-kewen

取某教材册英语课文摘要（不含逐句正文，省流量）。代理平台 GET /api/en-kewen?textbook_id=&size。需 textbook_id/catalog_id/keyword 之一。需登录(Bearer)。

读课文·逐句跟读评分

POST /api/en-kewen/read/grade

把 ASR(/ws/asr) 识别文本与标准英文句逐词比对(归一化+LCS,自由跳过噪声)→分数/错词。<85 分句写入待巩固错题本。需登录(Bearer)。

读课文·整课结束写记录

POST /api/en-kewen/read/finish

整课朗读结束写一条 lesson 级学习记录（逐句均分）。需登录(Bearer)。

读课文·我的朗读汇总

GET /api/en-kewen/read/records

每篇课文最佳分/星级/最近时间/次数（列表徽标用）。需登录(Bearer)。

读课文·待巩固句列表

GET /api/en-kewen/read/mistakes

当前用户读得不好(<85)的句子（可按课文过滤，时间倒序）。需登录(Bearer)。

读课文·删除待巩固句

DELETE /api/en-kewen/read/mistakes/{mistake_id}

删除一条待巩固句（订正/已掌握）。仅能删本人。需登录(Bearer)。

读课文·单篇详情（逐句）

GET /api/en-kewen/{lesson_id}

单篇英语课文逐句内容：sentences=[{en, zh, audio_url}]（逐句真人朗读音频，当前多为空、分批回填）。代理平台 GET /api/en-kewen/{id}。需登录(Bearer)。

App

App 版本检查（在线升级）

GET /api/app/version

公开免鉴权。读智慧校园平台维护的共享版本表(apps/app_versions)，返回本包名「最新且上架」版本清单，供 App 应用内检查更新→下载(TOS/CDN)→覆盖安装。发版流程见 docs/版本管理接口对接文档.md。

健康检查

GET /health

存活探针。

用户·鉴权

用户登录 / 首次登录即注册

POST /api/auth/login

公开。拼虚拟邮箱 login_name@admin_email_domain 调 Supabase Auth 验密码。账号不存在则自动注册并登录（代理管理后台建三件套，返回 created=true）；账号存在但密码错 → 401。返回 Supabase access/refresh + profile + created。见 docs/多端账号与登录规范.md。

用户注册（登录名+密码）

POST /api/auth/register

公开。server-to-server 代理管理后台 POST /auth/register，按规范建三件套（auth.users+profiles+students 回填）、role=student、注册即登录。无校自由注册挂占位校「未分配」。前端默认走 /login 合并流程，本接口为契约对齐。

令牌续期

POST /api/auth/refresh

公开。用 refresh_token 向 Supabase Auth 换新 access/refresh。

当前用户

GET /api/auth/me

需 Bearer Supabase access 令牌。按 sub 查共享 profiles，返回 {profile}。

【已废弃】旧用户登录

POST /api/user/login

已迁移到 /api/auth/login（共用账号体系）。本路径返回 410。

【已废弃】当前用户

GET /api/user/me

已迁移到 /api/auth/me（共用账号体系）。本路径返回 410。

管理后台·AI流程

AI 流程清单

GET /api/admin/ai/flows

各 AI 流程近 24h 运行数 + 成功率（侧栏二级 + 概览）。

AI 流程统计卡

GET /api/admin/ai/stats

今日运行数/成功率/平均耗时(+P95)/失败数，按 flow 作用域。

AI 流程运行列表

GET /api/admin/ai/runs

AI 流程详情（run + 步骤）

GET /api/admin/ai/runs/{run_id}

run 元信息 + 其全部步骤（含每步 input/output），供步骤时间线展示。

管理后台·文档

语音对话设置·读取

GET /api/admin/voice-dialog/settings

读取实时语音对话的全局配置（K12 教师角色）：联网/唱歌开关、基础人设、背景人设、对话风格、开场白、音色、bot 版本。需登录(Bearer)。

语音对话设置·更新

PUT /api/admin/voice-dialog/settings

更新实时语音对话全局配置（单行 upsert + 审计）。下次发起语音对话即生效。需登录(Bearer)。

文档列表

GET /api/admin/docs

文档详情

GET /api/admin/docs/{doc_id}

新建文档

POST /api/admin/docs

更新文档

PUT /api/admin/docs/{doc_id}

发布文档

POST /api/admin/docs/{doc_id}/publish

删除文档

DELETE /api/admin/docs/{doc_id}

导出文档

GET /api/admin/docs/export

format=json（三栏站结构）| markdown。导出已发布文档回灌 docs/接口文档/。

按 method+path 解析文档

GET /api/admin/docs/resolve

管理后台·日志

日志分类清单

GET /api/admin/logs/categories

各分类近 24h 计数 + 成功率（侧栏二级 + 概览）。顺序固定。

接口日志列表（按分类）

GET /api/admin/logs

按 category/method/status_code/result(成功|失败)/q(关键词)/date 过滤 + 分页。

日志统计卡（按分类）

GET /api/admin/logs/stats

今日请求数(24h)/成功率/平均耗时(+P95)/失败数，按 category 作用域。

日志详情（含输入/输出）

GET /api/admin/logs/{log_id}

日志→接口文档

GET /api/admin/logs/{log_id}/doc

按日志的 method+path 解析对应接口文档；命中返回 doc，否则返回 prefill 供新建。

管理后台·管理员

管理员列表

GET /api/admin/users

需 super_admin。

新建管理员

POST /api/admin/users

更新管理员

PUT /api/admin/users/{user_id}

删除管理员

DELETE /api/admin/users/{user_id}

管理后台·鉴权

管理员登录

POST /api/admin/login

校验 bcrypt 口令，签发 JWT。

当前管理员

GET /api/admin/me

Bearer 令牌换取当前账号信息。

修改密码

POST /api/admin/change-password

通用

个人中心·读自编资料

GET /api/user/profile

读当前用户在本 App 自编的资料覆盖（昵称/年级/头像）。无行则全 null，前端回落登录档案 display_name。需登录(Bearer)。

个人中心·更新昵称/年级

PUT /api/user/profile

upsert 当前用户昵称/年级到本端 app_user_profiles（不动共享表）。仅覆盖传入非空字段。需登录(Bearer)。

个人中心·上传头像

POST /api/user/avatar

收 {imageBase64, mime?} → 上传火山 TOS（前缀 user-avatar）→ 存 avatar_url 到 app_user_profiles → 返回公网 URL。需登录(Bearer)。