proofdb/apidoc/adminapi.md

管理员后台 API

接口说明

这组接口服务于 Proof DB 的管理员维护面板，包括：

• 管理员登录与会话读取
• archives 表管理
• OpenSearch 状态查看
• 管理员用户管理
• APIDOC 文档查看
• 维护脚本执行

管理员网页入口仍然是：

• GET /
• GET /admin/login
• GET /admin

管理员认证

管理员登录

POST /api/admin/login

Content-Type: application/json

字段	类型	必填	说明
username	string	是	管理员用户名
password	string	是	管理员密码

管理员退出登录

POST /api/admin/logout

当前管理员会话

GET /api/admin/me

未登录时返回：

{
  "code": 401,
  "message": "Admin session not found."
}

archives 表管理

获取档案列表

GET /api/admin/archives

查询参数

字段	类型	必填	说明
query	string	否	按 archive_uid、title、summary、author、source、series 模糊搜索
page	integer	否	页码，默认 1
page_size	integer	否	每页条数，默认 20，最大 100

请求示例

curl '<APIdomain>/api/admin/archives?query=iraq&page=1&page_size=20'

成功响应

{
  "code": 0,
  "message": "Archive list loaded.",
  "data": {
    "items": [
      {
        "archive_uid": "01KQHVREB6XPYF604RVZAP9NNY",
        "title": "1.test",
        "summary": "....",
        "year": 1991,
        "author": "....",
        "source": "....",
        "series": null,
        "tags": ["Iraq", "Kuwait"],
        "chunk_count": 14,
        "created_time": "2026-05-07 12:00:00+00",
        "updated_time": "2026-05-07 12:10:00+00"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}

获取单条档案详情

GET /api/admin/archives/{archive_uid}

更新单条档案

PATCH /api/admin/archives/{archive_uid}

Content-Type: application/json

可更新字段：

• title
• summary
• year
• author
• source
• series
• tags
• metadata

其中：

• tags 可以传字符串，也可以传数组；字符串会按逗号或换行拆分
• metadata 可以传 JSON 对象，也可以传 JSON 字符串
• year 为空时会写回 null

更新请求示例

curl -X PATCH <APIdomain>/api/admin/archives/01KQHVREB6XPYF604RVZAP9NNY \
  -H 'Content-Type: application/json' \
  --data '{
    "title": "Updated Title",
    "summary": "Updated summary",
    "year": 1991,
    "tags": ["Iraq", "Kuwait"],
    "metadata": {
      "reviewed_by": "admin"
    }
  }'

删除单条档案

DELETE /api/admin/archives/{archive_uid}

删除后会因外键约束级联删除对应 chunks 记录。

OpenSearch 状态查看

获取 OpenSearch 管理状态

GET /api/admin/opensearch/status

成功响应要点

响应中会同时返回：

• OpenSearch 连接配置摘要
• PostgreSQL 侧 archives/chunks 数量
• embedded_chunks
• indexed_chunks
• 当前索引是否存在
• docs_count
• cluster 健康状态
• mapping 字段列表

如果 OpenSearch 当前不可达，仍会返回数据库部分统计，但 opensearch.error 会带出错误信息。

获取 OpenSearch 索引文档粗览

GET /api/admin/opensearch/documents

查询参数

字段	类型	必填	说明
query	string	否	按 title、summary、source、author、text 等字段做粗略搜索
size	integer	否	返回条数，默认 20，最大 50

说明：

• 这是索引粗览接口，不返回向量字段本身。
• 返回中会包含 text_preview，用于后台快速检查索引内容是否正确进入 OpenSearch。

管理员用户管理

获取管理员用户列表

GET /api/admin/users

创建管理员用户

POST /api/admin/users

Content-Type: application/json

字段	类型	必填	说明
username	string	是	新管理员用户名
password	string	是	新管理员密码
display_name	string	否	展示名称

更新管理员用户

PATCH /api/admin/users/{id}

Content-Type: application/json

可更新字段：

• display_name
• password
• is_active

说明：

• password 为空时表示不修改
• is_active=false 后，该账号将不能再登录

APIDOC 查看

获取文档列表

GET /api/admin/docs

返回 /apidoc 目录下当前可查看的 .md 文档列表。

获取单份文档内容

GET /api/admin/docs/{name}

例如：

curl <APIdomain>/api/admin/docs/searchapi.md

响应中会带：

• name
• title
• content
• html

其中：

• content 为原始 Markdown 文本
• html 为后台面板可直接渲染的 HTML

维护脚本伪终端

获取白名单脚本列表

GET /api/admin/scripts

当前返回的是允许在管理员面板里执行的 scripts/*.php 白名单，而不是任意文件系统扫描。

如果对应脚本在 /scriptdoc 中存在同名文档，列表接口也会带出：

• doc_title
• doc_html
• doc_content

获取单个维护脚本详情

GET /api/admin/scripts/{name}

这个接口会返回单个脚本的说明、参数提示，以及可用的脚本文档内容。

执行维护脚本

POST /api/admin/scripts/run

Content-Type: application/json

字段	类型	必填	说明
script_name	string	是	白名单脚本名，如 reindex_opensearch
args	string[]	否	参数数组，仅允许 --key=value 风格

请求示例

curl -X POST <APIdomain>/api/admin/scripts/run \
  -H 'Content-Type: application/json' \
  --data '{
    "script_name": "reindex_opensearch",
    "args": ["--archive_uid=01KQHVREB6XPYF604RVZAP9NNY"]
  }'

成功响应

{
  "code": 0,
  "message": "Maintenance script finished.",
  "data": {
    "script_name": "reindex_opensearch",
    "command": [
      "php",
      "scripts/reindex_opensearch.php",
      "--archive_uid=01KQHVREB6XPYF604RVZAP9NNY"
    ],
    "exit_code": 0,
    "stdout": "....",
    "stderr": "",
    "ok": true
  }
}

权限与错误语义

• 除 POST /api/admin/login 外，本文件中的所有接口都要求已有管理员会话。
• 未登录时统一返回 401。
• 参数不合法时通常返回 422。
• JSON 格式错误时返回 400。
• 后端异常时返回 500。