feat: 初始化考培练系统项目
- 从服务器拉取完整代码 - 按框架规范整理项目结构 - 配置 Drone CI 测试环境部署 - 包含后端(FastAPI)、前端(Vue3)、管理端 技术栈: Vue3 + TypeScript + FastAPI + MySQL
This commit is contained in:
60
docs/规划/后端开发拆分策略/子agent/05-Agent-Training/api_contract.yaml
Normal file
60
docs/规划/后端开发拆分策略/子agent/05-Agent-Training/api_contract.yaml
Normal file
@@ -0,0 +1,60 @@
|
||||
openapi: 3.0.0
|
||||
info:
|
||||
title: AI陪练模块API
|
||||
version: 1.0.0
|
||||
description: 陪练场景与会话的最小契约(骨架)
|
||||
|
||||
paths:
|
||||
/api/v1/training-scenes:
|
||||
get:
|
||||
summary: 陪练场景列表
|
||||
tags: [陪练]
|
||||
security:
|
||||
- bearerAuth: []
|
||||
responses:
|
||||
200:
|
||||
description: 成功
|
||||
post:
|
||||
summary: 创建场景(管理员)
|
||||
tags: [陪练]
|
||||
security:
|
||||
- bearerAuth: []
|
||||
responses:
|
||||
201:
|
||||
description: 已创建
|
||||
|
||||
/api/v1/training/start:
|
||||
post:
|
||||
summary: 开始陪练
|
||||
tags: [陪练]
|
||||
security:
|
||||
- bearerAuth: []
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
required: [scene_id]
|
||||
properties:
|
||||
scene_id: { type: integer }
|
||||
responses:
|
||||
200:
|
||||
description: 成功
|
||||
|
||||
/api/v1/training/end:
|
||||
post:
|
||||
summary: 结束陪练
|
||||
tags: [陪练]
|
||||
security:
|
||||
- bearerAuth: []
|
||||
responses:
|
||||
200:
|
||||
description: 成功
|
||||
|
||||
components:
|
||||
securitySchemes:
|
||||
bearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: JWT
|
||||
20
docs/规划/后端开发拆分策略/子agent/05-Agent-Training/checklist.md
Normal file
20
docs/规划/后端开发拆分策略/子agent/05-Agent-Training/checklist.md
Normal file
@@ -0,0 +1,20 @@
|
||||
# Agent-Training 开发检查清单(简版)
|
||||
|
||||
## 准备
|
||||
- [ ] 阅读通用规范与架构文档
|
||||
|
||||
## 最小功能
|
||||
- [ ] `GET /api/v1/training-scenes` 场景列表
|
||||
- [ ] `POST /api/v1/training-scenes` 创建场景(管理员)
|
||||
- [ ] `POST /api/v1/training/start` 开始陪练(创建会话/初始化 Coze)
|
||||
- [ ] `POST /api/v1/training/end` 结束陪练(生成报告)
|
||||
|
||||
## 安全与规范
|
||||
- [ ] 登录必需;会话鉴权;敏感音频访问控制
|
||||
- [ ] 参数验证与统一异常
|
||||
- [ ] 结构化日志覆盖关键操作
|
||||
|
||||
## 质量
|
||||
- [ ] 单元测试覆盖率 ≥ 80%
|
||||
- [ ] 通过 Black/isort/flake8/mypy
|
||||
- [ ] API 与 `api_contract.yaml` 一致
|
||||
18
docs/规划/后端开发拆分策略/子agent/05-Agent-Training/context.md
Normal file
18
docs/规划/后端开发拆分策略/子agent/05-Agent-Training/context.md
Normal file
@@ -0,0 +1,18 @@
|
||||
# Agent-Training 上下文(极简版)
|
||||
|
||||
## 位置
|
||||
- 项目根:`/Users/nongjun/Desktop/Ai公司/本地开发与测试/kaopeilian-backend/`
|
||||
- 工作目录:`app/api/v1/`、`app/services/`、`app/models/`、`app/schemas/`
|
||||
|
||||
## 依赖
|
||||
- 输入依赖:Auth(认证)、User(学员信息)、Course(课程内容)、Coze(对话/评分)
|
||||
- 输出接口:陪练会话/记录/报告 API/服务,供 Analytics 消费
|
||||
|
||||
## 关键约束
|
||||
- 安全:登录必需;会话鉴权;敏感音频存储与访问控制
|
||||
- 性能:WS 往返延迟 < 100ms(本地);音频处理 < 500ms
|
||||
- 观测:会话开始/结束、评分生成记录结构化日志
|
||||
|
||||
## 最小运行信息
|
||||
- 环境变量:`COZE_API_BASE`、`COZE_API_TOKEN`、`COZE_TRAINING_BOT_ID`
|
||||
- 关联模型/表:`training_scenes`、`training_sessions`、`training_messages`、`training_reports`
|
||||
17
docs/规划/后端开发拆分策略/子agent/05-Agent-Training/examples/README.md
Normal file
17
docs/规划/后端开发拆分策略/子agent/05-Agent-Training/examples/README.md
Normal file
@@ -0,0 +1,17 @@
|
||||
# Agent-Training 示例(最小)
|
||||
|
||||
- 开始陪练:
|
||||
|
||||
```python
|
||||
# app/api/v1/training.py 片段(示例)
|
||||
from fastapi import APIRouter, Depends
|
||||
from app.api.deps import get_current_user
|
||||
from app.schemas.base import ResponseModel
|
||||
|
||||
router = APIRouter()
|
||||
|
||||
@router.post("/start")
|
||||
async def start_training():
|
||||
# 省略 Coze 会话初始化逻辑
|
||||
return ResponseModel(code=200, message="success")
|
||||
```
|
||||
50
docs/规划/后端开发拆分策略/子agent/05-Agent-Training/prompt.md
Normal file
50
docs/规划/后端开发拆分策略/子agent/05-Agent-Training/prompt.md
Normal file
@@ -0,0 +1,50 @@
|
||||
# Agent-Training 提示词(极简版)
|
||||
|
||||
## 必读引用
|
||||
@子agent/00-通用基础/base_prompt.md
|
||||
@子agent/00-通用基础/essential_docs.md
|
||||
@考培练系统规划/后端开发拆分策略/模块分工指南.md
|
||||
@考培练系统规划/后端开发拆分策略/协作机制设计.md
|
||||
|
||||
## 你的角色
|
||||
- 本模块职责:AI 陪练(场景/会话管理、实时对话、评估报告)
|
||||
- 依赖模块:Auth、User、Course、Coze
|
||||
- 对外输出:陪练会话/记录/报告 API,供 Analytics 使用
|
||||
|
||||
## 交付内容
|
||||
- 代码:`app/api/v1/training.py`、`app/services/training_service.py`、相关 `app/models/`、`app/schemas/`
|
||||
- 契约:本目录 `api_contract.yaml`(OpenAPI 3.0)
|
||||
- 文档与测试:`checklist.md` 全通过,单元测试覆盖率 ≥ 80%
|
||||
|
||||
## 验收标准(最小集)
|
||||
- API 与 `api_contract.yaml` 一致并通过基本集成测试
|
||||
- 认证/权限依赖正常(读需登录,写需登录)
|
||||
- 输入校验、统一异常、结构化日志符合通用规范
|
||||
|
||||
## 可复用资产与迁移要点
|
||||
- 后端对接(复用 08-Agent-Coze 网关)
|
||||
- 训练会话创建/结束:经 `Agent-Coze` 网关落到 Coze 客户端;与本模块的场景/记录模型解耦(Training 只持久化业务字段与审计,Coze 会话 ID 作为外部引用)。
|
||||
- 语音与流式:复用 `coze-chat-backend/main.py` 的 SSE 流式实现与中断逻辑(`conversation.message.delta/completed/failed`),保持“卡片”输出兼容(如需要在陪练中输出富结果)。
|
||||
- 上传能力:复用 `upload-file` 端点与文件到 Coze 的上传流程;在本模块内记录附件元数据与权限。
|
||||
- 前端可复用(`/Users/nongjun/Desktop/Ai公司/本地开发与测试/coze-chat-frontend/`)
|
||||
- 页面:`src/pages/Training/VoiceChat.tsx`、`src/pages/Training/TextChat.tsx`、`src/pages/Training/index.tsx` 可直接参考迁移;只需切换到新网关端点并接入统一鉴权。
|
||||
- Store:`src/stores/TrainingStore.ts` 的状态流转(连接/断开/中断/首个 delta 标记)、流式累计、滚动到底等逻辑可复用。
|
||||
- API:`src/server/api.ts`/`global.ts` 的会话/流式/中断接口封装;迁移时对齐为 `api_contract.yaml` 的 `POST /api/v1/training/sessions`、`POST /api/v1/training/sessions/{id}/end`,并预留 WS 能力(如需实时语音)。
|
||||
- 映射建议(旧 → 新)
|
||||
- 会话创建:`POST /agent/v1/cozechat/create-conversation` → `POST /api/v1/training/sessions`
|
||||
- 会话结束:无统一端点 → `POST /api/v1/training/sessions/{id}/end`
|
||||
- 流式聊天:`POST /agent/v1/cozechat/chat-stream` 或 `/api/chat/stream` → 由网关内聚合为会话内消息事件(如扩展 `WS /ws/v1/training/{session_id}`)。
|
||||
- 配置与安全
|
||||
- 使用 Auth 的 Bearer 认证;前端本地调试的 PAT 获取接口在生产禁用。
|
||||
- 复用 `COZE_API_BASE/WORKSPACE_ID` 等变量;保持 `NO_PROXY` 直连。
|
||||
|
||||
## 整合并入系统(当前阶段)
|
||||
- 后端并入
|
||||
- 依赖 `08-Agent-Coze` 网关:Training 仅持久化训练场景/记录/报告与审计字段,引用外部 `coze_conversation_id`;对话/中断/上传经网关转发。
|
||||
- 端点以本模块 `api_contract.yaml` 为准(`POST /api/v1/training/sessions`、`POST /api/v1/training/sessions/{id}/end`、`/messages(stream)`);旧路由由网关短期兼容。
|
||||
- 统一日志/鉴权/限流;SSE 错误映射为统一异常码。
|
||||
- 前端接入
|
||||
- 将 `coze-chat-frontend` 的 Training 页面以子应用挂载至主站(如 `/training/*`),统一登录态与 API 基址到新网关。
|
||||
- 验证语音/文本陪练的 SSE 流与中断在本地正常工作。
|
||||
- 验收
|
||||
- 后端端点通过集成测试;前端子应用在本地环境可稳定使用。
|
||||
Reference in New Issue
Block a user