zhixun: Instructions file for Codex

AGENTS.md

This file provides guidance to Qoder (qoder.com) when working with code in this repository.

项目概述

销冠培养系统 & 社恐培养系统 - 基于 Agent 模拟的销售和社交能力培训平台。

技术栈:

• 前端: Next.js 16 (App Router) + React 19 + TypeScript + Tailwind CSS 4
• 后端: FastAPI + Python 3.11+ + SQLAlchemy (AsyncIO) + Alembic
• 数据库: PostgreSQL + Redis
• AI: 阿里云百炼 (DashScope) - 通义千问系列模型 + Qwen-Omni 实时语音
• 状态管理: Zustand (持久化存储)
• UI 组件: Lucide React 图标库 + 自定义组件
• 任务队列: Celery (可选)

开发命令

环境启动

# 启动数据库服务 (PostgreSQL + Redis)
make db

# 启动后端开发服务器 (需要在新终端中运行)
make backend
# 或直接运行:
cd backend && source .venv/bin/activate && uvicorn app.main:app --reload --host 0.0.0.0 --port 8111

# 启动前端开发服务器 (需要在新终端中运行)
make frontend
# 或直接运行:
cd frontend && npm run dev

依赖安装

# 安装所有依赖 (后端 + 前端)
make install

# 仅安装后端依赖
cd backend && python -m venv .venv && source .venv/bin/activate && pip install -r requirements-dev.txt

# 仅安装前端依赖
cd frontend && npm install

数据库迁移

# 运行数据库迁移
make migrate
# 或: cd backend && source .venv/bin/activate && alembic upgrade head

# 创建新迁移文件
make migrate-new
# 或: cd backend && source .venv/bin/activate && alembic revision --autogenerate -m "描述"

# 初始化种子数据 (管理员、场景、课程等)
make seed
# 或手动运行:
# cd backend && source .venv/bin/activate
# python scripts/seed_data.py          # 基础数据
# python -m scripts.seed_scenarios_full # 30个训练场景
# python -m scripts.seed_all           # 课程、挑战等

测试

# 运行所有测试
make test

# 仅运行后端测试
make test-backend
# 或: cd backend && source .venv/bin/activate && pytest -v

代码质量检查

# 运行 linter (后端 + 前端)
make lint

# 后端代码检查
cd backend && source .venv/bin/activate && ruff check app

# 前端代码检查
cd frontend && npm run lint

# 格式化代码
make format
# 后端: cd backend && source .venv/bin/activate && ruff format app
# 前端: cd frontend && npm run lint -- --fix

构建

# 前端构建
cd frontend && npm run build

# 前端生产运行
cd frontend && npm run start

清理

# 清理临时文件和缓存
make clean

# 停止所有 Docker 服务
make stop

项目架构