# 🛠️ 开发指南
> **Development Guide**
本文档面向加入天工智能体平台开发的工程师，涵盖开发环境搭建、编码规范、测试与调试等内容。
---
## 一、开发环境搭建
### 前置要求
| 工具 | 版本 | 下载 |
|:----|:-----|:-----|
| Node.js | 18+ | [nodejs.org](https://nodejs.org/) |
| pnpm | 8+ | `npm install -g pnpm` |
| Python | 3.11+ | [python.org](https://python.org/) |
| Docker Desktop | 最新 | [docker.com](https://www.docker.com/products/docker-desktop/) |
| Git | 2.30+ | [git-scm.com](https://git-scm.com/) |
| IDE | VSCode / PyCharm | 推荐 VSCode + 对应插件 |
### 推荐 VSCode 插件
- **Vue 开发**：Vue Language Features (Volar)、TypeScript Vue Plugin
- **Python 开发**：Python、Pylance
- **数据库**：MySQL (weijan-chen)
- **Redis**：Redis
- **Docker**：Docker
- **格式化**：Prettier、ESLint
- **Git**：GitLens、Git History
---
## 二、代码规范
### 前端规范
#### 命名规范
| 类型 | 规范 | 示例 |
|:----|:-----|:-----|
| 组件名 | PascalCase | `UserProfile.vue` |
| 文件名 | kebab-case | `user-profile.vue` |
| 变量/函数 | camelCase | `getUserList()` |
| 常量 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT` |
| Pinia Store | useXxxStore | `useUserStore` |
| CSS 类名 | kebab-case | `.user-avatar` |
#### 组件结构
```vue
```
#### Git Commit 规范
遵循 Conventional Commits 规范：
```
():
```
| Type | 含义 |
|:-----|:------|
| `feat` | 新功能 |
| `fix` | 修复 Bug |
| `docs` | 文档变更 |
| `style` | 代码格式调整（不影响功能） |
| `refactor` | 重构代码 |
| `perf` | 性能优化 |
| `test` | 添加/修改测试 |
| `chore` | 构建/工具链变更 |
```bash
# 示例
feat(agent): 新增智能体知识库关联功能
fix(user): 修复 Token 刷新失败问题
docs(readme): 更新快速开始指南
```
---
### 后端规范
#### 项目约定
| 项目 | 约定 |
|:-----|:------|
| 代码风格 | 遵循 PEP 8 |
| 类型注解 | 所有函数必须包含类型注解 |
| 注释 | 关键逻辑需写中文注释 |
| 路由命名 | `/{module}/{action}`，如 `/agents/{id}/start` |
| 响应格式 | 统一使用 `{ code, message, data }` 格式 |
#### 响应格式
```python
# 成功响应
{
"code": 200,
"message": "success",
"data": { ... }
}
# 错误响应
{
"code": 40001,
"message": "用户不存在",
"data": null
}
```
---
## 三、测试指南
### 前端测试
```bash
cd frontend
# 运行单元测试
pnpm test
# 运行测试并生成覆盖率报告
pnpm test:coverage
```
### 后端测试
```bash
cd backend
# 运行所有测试
pytest
# 运行特定模块测试
pytest tests/test_agent.py -v
# 运行测试并生成覆盖率
pytest --cov=app tests/
```
---
## 四、调试技巧
### 前端
- **Vue Devtools**：浏览器安装 Vue Devtools 插件，可查看组件树、状态、事件
- **Axios 拦截器**：在 `utils/request.ts` 中可打印请求/响应的完整信息
### 后端
- **FastAPI 自动文档**：访问 `http://localhost:8037/docs` 交互式调试 API
- **Pdb 调试**：在代码中插入 `import pdb; pdb.set_trace()` 启动断点调试
- **日志查看**：后端日志输出到控制台，关键位置使用 `logger.info()` 打点
---
## 五、数据库变更流程
```bash
# 1. 修改 model 文件（如 app/models/user.py）
# 2. 生成迁移脚本
cd backend
alembic revision --autogenerate -m "add_user_avatar_field"
# 3. 审查并执行迁移
alembic upgrade head
# 4. （如需回滚）
alembic downgrade -1
```
> ⚠️ **注意**：生产环境的数据库迁移需先在预发布环境验证。
---
## 六、常见开发问题
| 问题 | 解决方案 |
|:-----|:---------|
| `pnpm install` 报错 | 检查 Node.js 版本，删除 `node_modules` 重新安装 |
| 后端热重载不生效 | 检查 `uvicorn` 是否带 `--reload` 参数 |
| Alembic 检测不到模型变更 | 确认模型已导入 `app/models/__init__.py` |
| CORS 错误 | 检查后端 CORS 配置中 `origins` 是否包含前端地址 |
---
> 📎 **相关文档**：[快速开始指南](./quickstart.md) | [项目结构概览](./project-structure.md)