feat: 初始化考培练系统项目

- 从服务器拉取完整代码
- 按框架规范整理项目结构
- 配置 Drone CI 测试环境部署
- 包含后端(FastAPI)、前端(Vue3)、管理端

技术栈: Vue3 + TypeScript + FastAPI + MySQL
This commit is contained in:
111
2026-01-24 19:33:28 +08:00
commit 998211c483
1197 changed files with 228429 additions and 0 deletions

View 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

View 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` 一致

View 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`

View 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")
```

View 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 流与中断在本地正常工作。
- 验收
- 后端端点通过集成测试;前端子应用在本地环境可稳定使用。