2026-09-02 20:18:58 +08:00

2.8 KiB
Raw Blame History

Demo Admin Console 使用说明

DEMO-010 在 FastAPI 服务中提供一个轻量、同源的管理客户端。页面只负责展示和交互,上传、 文档管理与检索仍全部通过 /api/v1 公开业务接口完成,不复制服务端业务逻辑。

启动与访问

完成运行时配置后启动 Worker 与 API:

make run-worker
make run

页面地址:

页面 地址 对应业务接口
文档上传 /admin/upload POST /api/v1/documents
文档列表与详情 /admin/documents GET/DELETE /api/v1/documents*
Search Lab /admin/search POST /api/v1/search

/admin 默认展示上传页。OpenAPI 文档仍位于 /api/v1/docs。

品牌视觉基线

DEMO-014 参考地瓜机器人公开官网的设计语言,使用品牌橙 #FF3C00、黑白高对比、中文 无衬线标题、紧凑数据字体、低圆角容器和宽松留白。贯穿页面标题的“计算信号轨”是唯一的 强调性图形,序号对应上传、文档、检索三步真实操作顺序。

品牌图形使用仓库内的代码原生 SVG/CSS 绘制,不复制或热链官网图片、字体和脚本;页面 运行时不依赖品牌官网。前端设计方法参考 GitHub anthropics/skills 的 Apache-2.0 frontend-design Skill,并以现有 Demo 信息架构、可访问性和业务正确性为优先约束。

Demo 操作闭环

  1. 在上传页选择一个 PDF、DOCX、TXT 或 Markdown 文件并提交;
  2. 接口返回 202 后,当前页面显示已接收;在文档列表刷新查看 Processing/Ready/Failed;
  3. 在文档列表查看状态和安全元数据;
  4. 在 Search Lab 输入问题并查看 Top-K 的文件名、页码、章节、Chunk 内容、Dense Score 和 Rerank Score;
  5. 如需清理 Demo 数据,在文档列表确认后直接删除。

范围与安全边界

  • 页面静态文件位于 apps/admin-web,由同一个 FastAPI 进程提供,避免额外前端运行时;
  • API 返回内容仅通过 DOM textContent 渲染,不作为 HTML 注入;
  • 页面不保存或展示 Provider 凭据、内部 Endpoint、storage key 或 Index Profile;
  • 当前 Console 尚不轮询 Job 详情或展示 Attempt;该状态 UI 与批量上传一起由 DEMO-016 实现;
  • 本任务不包含 ACL/RBAC、审计、Document Version、Compiled Knowledge、MCP、Hybrid/BM25 或完整 V1 Admin Console 导航;
  • 删除是 Demo 的直接删除语义,确认后会清理 canonical Metadata、派生产物、源文件与向量行。

验证

静态路由和范围契约由 tests/integration/test_admin_console.py 覆盖;现有 REST 全链路测试覆盖 上传、列表、详情、搜索与删除。浏览器验收使用确定性本地 Provider,不读取真实企业文档, 并覆盖桌面与移动布局。