ai-robot-core/docs/progress/ai-service-admin-progress.md

module	feature	status	created	last_updated
ai-service-admin	ASA	in_progress	2026-02-24	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

• Phase 1: 基础建设 (100%) [P1-01 ~ P1-05]
• Phase 2: 知识库管理 (100%) [P2-01 ~ P2-05]
• Phase 3: RAG 实验室 (100%) [P3-01 ~ P3-04]
• Phase 4: 会话监控与详情 (100%) [P4-01 ~ P4-03]
• Phase 5: 后端管理接口实现 (100%) [Backend Admin APIs]

current_phase

goal: 知识库管理模块开发，实现文档上传、列表展示与状态轮询

sub_tasks

• (P1-01) 初始化 ai-service-admin 前端工程（Vue 3 + Element Plus + RuoYi-Vue 基座对齐），落地基础目录结构与路由骨架
• (P1-02) 接入 Pinia：实现 tenant store（currentTenantId）并持久化（localStorage），提供切换租户能力
• (P1-03) Axios/SDK 请求层封装：创建统一 request 实例，自动注入必填 Header X-Tenant-Id
• (P1-04) 全局异常拦截：实现 401/403 响应拦截策略
• (P1-05) 基础组件封装：BaseTable、BaseForm 并给出示例页
• (P2-01) 创建 openapi.deps.yaml 明确依赖契约 (L1) [AC-ASA-08]
• (P2-02) 实现知识库列表 API 对接及分页展示 [AC-ASA-08]
• (P2-03) 实现文档上传功能（Multipart/form-data）[AC-ASA-01]
• (P2-04) 实现索引任务状态轮询机制（3s 间隔）[AC-ASA-02]
• (P2-05) 失败任务错误详情弹窗展示 [AC-ASA-02]
• (P5-01) 实现后端 GET /admin/kb/documents 文档列表接口 [AC-ASA-08]
• (P5-02) 实现后端 POST /admin/kb/documents 文档上传接口 [AC-ASA-01]
• (P5-03) 实现后端 GET /admin/kb/index/jobs/{jobId} 索引任务查询接口 [AC-ASA-02]
• (P5-04) 实现后端 POST /admin/rag/experiments/run RAG实验接口 [AC-ASA-05]
• (P5-05) 实现后端 GET /admin/sessions 会话列表接口 [AC-ASA-09]
• (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

// 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 个任务