公开与管理 API 速查
提供项目、文档和搜索的只读请求示例，并解释管理认证、乐观锁、关系与生命周期接口。
契约与调用前提
完整契约位于 api/openapi.yaml，实现分布在 server/internal/httpapi/、service/ 与 repository/。公开 API 前缀为 /api/v1，管理 API 为 /api/admin/v1。本地 API 默认 8080，Web 同源代理转发 /api/；以下只读示例需服务已启动，非默认端口自行替换。
项目、文档与搜索
curl --fail-with-body 'http://127.0.0.1:8080/api/v1/projects?page=1&page_size=20'
curl --fail-with-body 'http://127.0.0.1:8080/api/v1/projects/douya-ops-website'
curl --fail-with-body 'http://127.0.0.1:8080/api/v1/docs?project=douya-ops-website&page_size=100'
curl --fail-with-body 'http://127.0.0.1:8080/api/v1/docs/douya-ops-website/handbook/api-reference'
curl --fail-with-body --get --data-urlencode 'q=项目手册' 'http://127.0.0.1:8080/api/v1/search'公开目录只返回符合公开条件的内容。文档详情路径由项目 Slug 和文档路径组成，不是数据库 ID。文档目录响应包含树节点，但分页仍按接口返回的 pagination 处理；不要假设第一页就是全部文档，也不要只计算根节点数量来替代文档总数。
响应与分页
成功响应使用 code、message、data、request_id 包装；列表数据包含 items 和 pagination。客户端同时检查 HTTP 状态和业务码，不要直接把异常文本当作列表。项目和文档的 page_size 不可超过 100，使用返回的页数遍历。
缺失详情通常返回 404；非法字段或过滤条件可能返回 400；并发或依赖冲突返回 409。保留 request_id 便于关联服务端日志，但分享日志前仍需去掉凭据和个人数据。
管理认证与权限
管理员先调用 POST /api/admin/v1/auth/login，已开启 MFA 的账号需要 mfa_code。服务端设置 Session Cookie，再通过 GET /api/admin/v1/auth/csrf 取得当前会话的 CSRF Token。后续写请求携带 Cookie 和 X-CSRF-Token，权限可通过 GET /api/admin/v1/auth/me 检查。
不要复制公开请求示例后直接拼入真实密码；使用后台或已审查的导入脚本。401 先处理会话，403 检查权限与 CSRF，登录出现 423 或 429 时按锁定或限流提示等待排查，不能持续重试。
项目文档写入顺序
项目在 /api/admin/v1/projects 创建，文档在 /api/admin/v1/documents 创建；新记录 lock_version 为 1。更新通过对应 /{id} 的 PATCH，必须提交当前版本。标签通过 /relations/{entity_type}/{id}/tags 替换，项目工具与场景、文档工具使用各实体的专属关系接口。
发布使用 POST /api/admin/v1/documents/{id}/lifecycle/publish，请求为当前 lock_version 与可选 note。文档移动使用 PATCH /api/admin/v1/documents/{id}/move，包含父 ID、排序和当前版本。每次修改后采用响应的新版本，不复用旧版本连续写入。
验证与停止条件
写入应先在一次性测试数据库验证。出现 409 时重新读取当前记录并人工合并，不能不断增加版本号碰运气。管理请求超时并不等于未写入，重试前按 ID 或 Slug 查询结果，避免重复创建。公开接口验收还应覆盖项目、祖先文档状态以及搜索投影，不能仅看管理端创建成功。
请求关系替换接口前先保存当前关系集合：替换表示以本次列表为完整结果，而不是仅追加一个目标。确认目标已发布且属于预期目录，再提交修改。文档父节点必须属于同一项目，当前层级上限为四层，禁止形成循环或把祖先移到自己的子树中。