MBE 团队协作开发指南

开发环境访问

开发工作流

1. 前端/客户端开发

直接调用开发环境 API：

// 配置 API 基础地址
const API_BASE = 'https://mbe-dev.hi-maker.com';

// 调用对话 API
const response = await fetch(`${API_BASE}/api/v1/chat`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
        message: '你好',
        session_id: 'test-session-001'
    })
});

2. 后端开发（代码修改）

方式 A：本地开发 + 推送更新

# 1. 克隆代码
git clone <仓库地址>
cd mises-behavior-engine

# 2. 本地修改代码
# 编辑 src/ 目录下的文件

# 3. 提交代码
git add .
git commit -m "feat: 添加新功能"
git push

# 4. 通知管理员重启开发环境
# 或者有权限的成员执行：
docker-compose -f docker-compose.dev.yml restart mbe-api-dev

方式 B：本地运行完整环境

# 1. 安装依赖
pip install -r requirements.txt

# 2. 配置环境变量
cp env.example.txt .env
# 编辑 .env 填入必要配置

# 3. 本地启动
python -m src.main
# 访问 http://localhost:8000

3. 测试 API

使用 curl

# 健康检查
curl https://mbe-dev.hi-maker.com/health

# 对话测试
curl -X POST https://mbe-dev.hi-maker.com/api/v1/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "你好", "session_id": "test-001"}'

# 专家匹配
curl -X POST https://mbe-dev.hi-maker.com/api/v1/expert/match \
  -H "Content-Type: application/json" \
  -d '{"query": "法律咨询问题"}'

使用 Python

import httpx

API = "https://mbe-dev.hi-maker.com"

# 对话
response = httpx.post(f"{API}/api/v1/chat", json={
    "message": "帮我分析一下股票走势",
    "session_id": "dev-test-001"
})
print(response.json())

4. 查看日志

联系管理员或有服务器权限的成员：

# 查看开发环境日志
docker logs mbe-api-dev --tail 100

# 实时跟踪日志
docker logs mbe-api-dev -f

API 端点速查

核心接口

QT2 量化交易接口

MCP 接口

开发数据库访问

开发数据库可外部访问（仅开发环境）：

Host: <服务器IP或域名>
Port: 5433
User: mbe
Password: mbe_dev_password
Database: mbe_dev

# 连接示例
psql -h <服务器IP> -p 5433 -U mbe -d mbe_dev

注意事项

开发规范

1. 不要在开发环境测试大量数据 - 资源有限
2. 使用独立的 session_id - 避免干扰他人测试
3. 敏感操作先沟通 - 如清理数据、重启服务
4. 代码提交前本地测试 - 减少环境问题

环境区分

# 根据环境切换配置
import os

if os.getenv('ENV') == 'production':
    API_BASE = 'https://mbe.hi-maker.com'
else:
    API_BASE = 'https://mbe-dev.hi-maker.com'

问题反馈

遇到问题时提供：

1. 调用的 API 端点
2. 请求参数
3. 错误响应
4. 时间戳（便于查日志）

常见问题

Q: API 返回 502 错误

服务可能正在重启，等待 1-2 分钟后重试。

Q: 响应很慢

开发环境资源有限，首次调用需要加载模型，约 30-60 秒。

Q: 如何查看我的测试数据

使用唯一的 session_id，联系管理员查询数据库。

Q: 代码修改后多久生效

提交代码后，需要管理员重启服务才能生效（约 2 分钟）。

Git 工作流

首次设置

# 1. 克隆仓库（从 Gitea）
git clone http://localhost:3000/admin/mises-behavior-engine.git
cd mises-behavior-engine

# 2. 或添加远程仓库（已有代码）
git remote add origin http://localhost:3000/admin/mises-behavior-engine.git

日常开发流程

# 1. 拉取最新代码
git pull origin main

# 2. 创建功能分支
git checkout -b feature/my-feature

# 3. 开发和本地测试
# ... 修改代码 ...
pytest tests/test_api.py -v

# 4. 提交代码
git add .
git commit -m "feat: 添加新功能"

# 5. 推送分支
git push origin feature/my-feature

# 6. 在 Gitea 创建合并请求

分支规范

提交规范

feat: 新功能
fix: 修复 bug
docs: 文档更新
style: 代码格式调整
refactor: 代码重构
test: 测试相关
chore: 构建/工具相关

Webhook 自动部署

配置说明

当代码推送到 main 分支时，Gitea 会自动通知 MBE API：

推送代码 → Gitea → Webhook → MBE API → 记录部署事件

Webhook 端点

手动部署

# 快速部署（跳过测试）
python scripts/quick_deploy.py

# 完整部署（含测试）
python scripts/auto_deploy.py

# 查看部署日志
Get-Content logs/deploy.log -Tail 50

本地开发环境

启动服务

# 方式一：使用管理脚本
.\mbe.ps1 dev start

# 方式二：使用 Docker Compose
docker-compose -f docker-compose.dev.yml up -d

# 方式三：使用批处理
.\start-dev.bat

验证服务

# 检查容器状态
docker ps | Select-String mbe

# 测试 API
Invoke-WebRequest http://localhost:8001/ -UseBasicParsing

# 查看日志
docker logs mbe-api-dev --tail 50

团队协作最佳实践

代码审查

1. 所有代码通过 Pull Request 合并
2. 至少一人审查后才能合并
3. 审查关注：功能正确性、代码规范、性能影响

沟通机制

1. 开始开发前，在群里同步任务
2. 遇到阻塞问题，及时沟通
3. 完成功能后，通知测试验证

环境使用规范

1. 开发环境：日常开发测试
2. 生产环境：仅部署验证通过的代码
3. 本地环境：个人调试，不影响他人