MakiMath

接口约定 ​

本文说明知识点、讲义、审核与会话接口。后端基线见前端接入流程。

先读前端接入流程。参考分为认证、知识点、讲义、审核与管理。

通用结构 ​

  • 接口表使用完整路径，已包含 /api 前缀，请勿重复拼接。ID 为正的安全整数；路径 ID 只接受十进制正整数。版本序号 revision_no、版本 ID id 与草稿并发号 edit_version 不可混用。
  • 登录使用 Authorization: Bearer <access_token>，刷新令牌放请求体 refresh_token，不使用 Cookie 认证。服务端每次检查账号状态和会话，不能只解析 JWT 判断权限。
  • 请求对象使用字段白名单，多余字段返回 400。读取响应不能原样回传保存。
  • 通常读取/保存/提交返回 200，创建/审核返回 201；注销、改密、移除协作者返回 204，无正文。列表直接返回数组；搜索返回 { hits }。日期为 JSON 时间字符串，未发生的时间为 null。
  • 当前没有列表分页。请求体上限 4 MiB，包含加密开销；限流每分钟最多 300 次，超出返回 429。

通信加密 ​

所有 JSON 示例都是加密前请求或解密后响应，不能直接作为 HTTP 写请求体。GET /api/auth/pubkey 返回明文 { "ok": true, "pubkey": "服务端公钥的Base64" }。使用准确路径，不附加查询参数；插件按完整 URL 判断豁免。

浏览器生成 P-256 ECDH 临时密钥对，以 raw 格式公钥（65 字节）的 Base64 设置 x-cp。与服务端公钥协商得到的 256 位共享位串直接作为 AES-256-GCM 密钥。封装为 { "d": "Base64(12字节IV + 16字节Tag + 密文)" }。现有通信适配层继续负责封装和解封。

POST/PUT/PATCH 非空请求体必须加密，Content-Type 为 application/json。GET 也应携带 x-cp，因为 /api 下有内容的 2xx JSON 响应会加密。204 不解密；4xx/5xx 为普通 JSON，不解密。公钥接口和 /health 不封装。缺少 x-cp 时后端兼容配置中的固定密钥，供脚本和测试使用，不应在浏览器分发该密钥。此协议不能替代 HTTPS。自定义服务端私钥时，须由后端确认其与固定公开公钥匹配。

错误与限制 ​

错误为 { "error": "说明" }，部分带 details。按 HTTP 状态处理，不依赖中文错误文案。

状态含义
400字段、类型、加密格式、检查约束等错误
401未登录、令牌/会话无效、登录失败或旧密码错误
403缺少管理员、贡献者或讲义权限
404不存在或不满足公开条件；登录不绕过公开接口筛选
409并发号过时、重复提交/审核、非草稿写入、未审核引用、slug/关联/业务约束冲突
413 / 429 / 500请求过大 / 请求过频 / 服务端错误

409 应重新读取并解决冲突，不盲目覆盖。数据库外键映射 409、检查约束映射 400、触发器业务异常映射 409，成环不一定为 400。

知识点/讲义/分类 slug 最长 100，只允许小写字母、数字及分隔连字符，如 sequence-limit。目录章/节 slug 只要求非空、最长 100。标题最长 200，源码最长 200000，摘要/简介最长 5000，修改说明最长 2000；字符串长度按 JavaScript length，密码另有字节限制。metadata 必须为对象。草稿源码可空，知识点提交要求非空正文，讲义提交要求至少一块内容。

animation 接受对象或接口允许的 null；递归拒绝规范化后为 scenescode 的键，包括 scenes_code、scenesCode、scenes-code 及大小写变体。当前没有新的可执行场景协议，不能换个字段继续执行旧动画代码。