168 lines
6.2 KiB
Markdown
168 lines
6.2 KiB
Markdown
---
|
||
module: ai-service-admin
|
||
feature: ASA
|
||
status: in_progress
|
||
created: 2026-02-24
|
||
last_updated: 2026-02-24
|
||
---
|
||
|
||
# AI 中台管理界面（ai-service-admin）进度文档
|
||
|
||
## context
|
||
|
||
- **module**: ai-service-admin
|
||
- **feature**: ASA
|
||
- **status**: 🔄进行中
|
||
|
||
## spec_references
|
||
|
||
- requirements: "spec/ai-service-admin/requirements.md"
|
||
- design: "spec/ai-service-admin/design.md"
|
||
- tasks: "spec/ai-service-admin/tasks.md"
|
||
- openapi_admin: "spec/ai-service/openapi.admin.yaml"
|
||
|
||
## overall_progress
|
||
|
||
- [x] Phase 1: 基础建设 (100%) [P1-01 ~ P1-05]
|
||
- [x] Phase 2: 知识库管理 (100%) [P2-01 ~ P2-05]
|
||
- [x] Phase 3: RAG 实验室 (100%) [P3-01 ~ P3-04]
|
||
- [x] Phase 4: 会话监控与详情 (100%) [P4-01 ~ P4-03]
|
||
- [x] Phase 5: 后端管理接口实现 (100%) [Backend Admin APIs]
|
||
|
||
## current_phase
|
||
|
||
**goal**: 知识库管理模块开发，实现文档上传、列表展示与状态轮询
|
||
|
||
### sub_tasks
|
||
|
||
- [x] (P1-01) 初始化 `ai-service-admin` 前端工程（Vue 3 + Element Plus + RuoYi-Vue 基座对齐），落地基础目录结构与路由骨架
|
||
- [x] (P1-02) 接入 Pinia：实现 `tenant` store（`currentTenantId`）并持久化（localStorage），提供切换租户能力
|
||
- [x] (P1-03) Axios/SDK 请求层封装：创建统一 `request` 实例，自动注入必填 Header `X-Tenant-Id`
|
||
- [x] (P1-04) 全局异常拦截：实现 401/403 响应拦截策略
|
||
- [x] (P1-05) 基础组件封装：`BaseTable`、`BaseForm` 并给出示例页
|
||
- [x] (P2-01) 创建 `openapi.deps.yaml` 明确依赖契约 (L1) [AC-ASA-08]
|
||
- [x] (P2-02) 实现知识库列表 API 对接及分页展示 [AC-ASA-08]
|
||
- [x] (P2-03) 实现文档上传功能（Multipart/form-data）[AC-ASA-01]
|
||
- [x] (P2-04) 实现索引任务状态轮询机制（3s 间隔）[AC-ASA-02]
|
||
- [x] (P2-05) 失败任务错误详情弹窗展示 [AC-ASA-02]
|
||
- [x] (P5-01) 实现后端 GET /admin/kb/documents 文档列表接口 [AC-ASA-08]
|
||
- [x] (P5-02) 实现后端 POST /admin/kb/documents 文档上传接口 [AC-ASA-01]
|
||
- [x] (P5-03) 实现后端 GET /admin/kb/index/jobs/{jobId} 索引任务查询接口 [AC-ASA-02]
|
||
- [x] (P5-04) 实现后端 POST /admin/rag/experiments/run RAG实验接口 [AC-ASA-05]
|
||
- [x] (P5-05) 实现后端 GET /admin/sessions 会话列表接口 [AC-ASA-09]
|
||
- [x] (P5-06) 实现后端 GET /admin/sessions/{sessionId} 会话详情接口 [AC-ASA-07]
|
||
|
||
### next_action
|
||
|
||
**immediate**: 后端管理接口已实现完成，等待前端联调
|
||
|
||
**details**:
|
||
- file: "ai-service/app/api/admin/"
|
||
- action: "后端 7 个管理接口已全部实现，包含 Mock 数据返回，支持前端并行开发"
|
||
- reference: "spec/ai-service/openapi.admin.yaml"
|
||
- constraints:
|
||
- 所有接口均已实现 X-Tenant-Id Header 校验
|
||
- 返回数据格式与契约定义一致
|
||
|
||
### backend_implementation_summary
|
||
|
||
**已实现的后端接口**:
|
||
|
||
| 接口 | 方法 | 文件 | 验收标准 |
|
||
|------|------|------|----------|
|
||
| /admin/kb/documents | GET | api/admin/kb.py | [AC-ASA-08] |
|
||
| /admin/kb/documents | POST | api/admin/kb.py | [AC-ASA-01] |
|
||
| /admin/kb/index/jobs/{jobId} | GET | api/admin/kb.py | [AC-ASA-02] |
|
||
| /admin/rag/experiments/run | POST | api/admin/rag.py | [AC-ASA-05] |
|
||
| /admin/sessions | GET | api/admin/sessions.py | [AC-ASA-09] |
|
||
| /admin/sessions/{sessionId} | GET | api/admin/sessions.py | [AC-ASA-07] |
|
||
|
||
**代码提交规范**:
|
||
- 所有文件头部标注相关 AC 编号
|
||
- 使用 `get_tenant_id()` 统一处理 X-Tenant-Id
|
||
- 返回格式与契约 Schema 对齐（DocumentInfo, SessionInfo, PageInfo）
|
||
|
||
## technical_context
|
||
|
||
### module_structure
|
||
|
||
```
|
||
ai-service-admin/ # 前端工程（待创建）
|
||
├── src/
|
||
│ ├── api/ # API 请求层
|
||
│ ├── components/ # 通用组件
|
||
│ ├── composables/ # Vue Composables
|
||
│ ├── router/ # 路由配置
|
||
│ ├── stores/ # Pinia stores
|
||
│ ├── views/ # 页面视图
|
||
│ └── utils/ # 工具函数
|
||
└── package.json
|
||
```
|
||
|
||
### key_decisions
|
||
|
||
| decision | reason | impact |
|
||
|----------|--------|--------|
|
||
| Vue 3 + Element Plus | 与 RuoYi-Vue-Plus 基座技术栈一致 | 复用基座组件与权限体系 |
|
||
| Pinia 状态管理 | Vue 3 官方推荐，替代 Vuex | 更简洁的 store 模式 |
|
||
| localStorage 持久化 | 租户切换需跨会话保持 | 无需后端 session 支持 |
|
||
|
||
### code_snippets
|
||
|
||
```typescript
|
||
// stores/tenant.ts (待实现)
|
||
export const useTenantStore = defineStore('tenant', {
|
||
state: () => ({
|
||
currentTenantId: localStorage.getItem('currentTenantId') || ''
|
||
}),
|
||
actions: {
|
||
setTenant(id: string) {
|
||
this.currentTenantId = id
|
||
localStorage.setItem('currentTenantId', id)
|
||
}
|
||
}
|
||
})
|
||
```
|
||
|
||
## session_history
|
||
|
||
- session: "Session #1 (2026-02-24)"
|
||
completed: []
|
||
changes: []
|
||
|
||
- session: "Session #2 (2026-02-24) - Backend Admin APIs Implementation"
|
||
completed:
|
||
- 补齐 openapi.admin.yaml 契约（GET /admin/kb/documents, GET /admin/sessions）
|
||
- 创建 ai-service/app/api/admin/ 路由模块结构
|
||
- 实现 6 个管理接口（KB文档管理、RAG实验、会话监控）
|
||
- 在 main.py 注册管理路由
|
||
- 更新进度文档
|
||
- 修复 FastAPI Query 参数语法问题（Annotated 默认值格式）
|
||
changes:
|
||
- spec/ai-service/openapi.admin.yaml - 添加 DocumentInfo, SessionInfo, PageInfo Schema 及列表接口
|
||
- ai-service/app/api/admin/__init__.py - 新增
|
||
- ai-service/app/api/admin/kb.py - 新增（3个接口）
|
||
- ai-service/app/api/admin/rag.py - 新增（1个接口）
|
||
- ai-service/app/api/admin/sessions.py - 新增（2个接口）
|
||
- ai-service/app/main.py - 注册管理路由
|
||
- docs/progress/ai-service-admin-progress.md - 更新进度
|
||
|
||
## startup_guide
|
||
|
||
1. **Step 1**: 读取本进度文档（了解当前位置与下一步）
|
||
2. **Step 2**: 读取 spec_references 中定义的模块规范（了解业务与接口约束）
|
||
3. **Step 3**: 直接执行 next_action - 初始化前端工程
|
||
|
||
---
|
||
|
||
## Phase 任务速查
|
||
|
||
| Phase | 名称 | 任务数 | 状态 |
|
||
|-------|------|--------|------|
|
||
| Phase 1 | 基础建设 | 5 | ⏳ 待开始 |
|
||
| Phase 2 | 知识库管理 | 5 | ⏳ 待开始 |
|
||
| Phase 3 | RAG 实验室 | 4 | ⏳ 待开始 |
|
||
| Phase 4 | 会话监控与详情 | 3 | ⏳ 待开始 |
|
||
|
||
**总计: 17 个任务**
|