47 lines
2.0 KiB
Markdown
47 lines
2.0 KiB
Markdown
# 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,不读取真实企业文档,
|
||
并覆盖桌面与移动布局。
|