2026-09-02 13:48:31 +08:00

47 lines
2.0 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Demo Admin Console 使用说明
DEMO-010 在 FastAPI 服务中提供一个轻量、同源的管理客户端。页面只负责展示和交互,上传、
文档管理与检索仍全部通过 `/api/v1` 公开业务接口完成,不复制服务端业务逻辑。
## 启动与访问
完成运行时配置后启动 API:
```bash
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 操作闭环
1. 在上传页选择一个 PDF、DOCX、TXT 或 Markdown 文件并提交;
2. 等待同步流水线返回 `Ready`,失败时页面显示经过 API 收敛的错误;
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;
- 本任务不包含 ACL/RBAC、审计、异步任务、Document Version、Compiled Knowledge、MCP、
Hybrid/BM25 或完整 V1 Admin Console 导航;
- 删除是 Demo 的直接删除语义,确认后会清理 canonical Metadata、派生产物、源文件与向量行。
## 验证
静态路由和范围契约由 `tests/integration/test_admin_console.py` 覆盖;现有 REST 全链路测试覆盖
上传、列表、详情、搜索与删除。浏览器验收使用确定性本地 Provider,不读取真实企业文档,
并覆盖桌面与移动布局。