butubb/wxauto_api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

初始化提交

Browse Source
This commit is contained in:
butubb
2026-04-07 14:11:45 +08:00
parent 46342134b6
commit c412e4de5f
69 changed files with 19321 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.trae/rules/gz.md
+464
View File
@@ -0,0 +1,464 @@
# WXAuto Center AI 开发流程规则
## 概述
本项目是 WXAuto Center 中控系统，采用 FastAPI + PostgreSQL + Redis 架构。本规则用于规范 AI Agent 开发流程，确保代码质量和项目一致性。
---
## 项目结构
```
wxauto_api/
├── api/ # API 路由层
│ ├── __init__.py
│ ├── nodes.py # 节点管理
│ ├── messages.py # 消息发送
│ ├── external.py # 外部接口
│ ├── plugins.py # 插件管理
│ └── callback.py # 回调接口
├── services/ # 业务逻辑层
│ ├── node_manager.py
│ ├── monitor_service.py
│ └── log_service.py
├── models.py # 数据模型
├── config.py # 配置管理
├── main.py # FastAPI 主入口
├── data/ # 数据目录
│ ├── db/ # PostgreSQL 数据
│ ├── redis/ # Redis 数据
│ └── logs/ # 应用日志
├── doc/ # 项目文档
├── scripts/ # 部署脚本
├── static/ # 前端资源
└── plugins/ # 插件系统
```
---
## 开发流程
### 1. 需求分析 (Requirement Analysis)
**原则**：在开始任何代码修改前，必须充分理解需求。
#### 执行步骤
1. **澄清需求**
- 明确功能目标和边界
- 确认输入输出格式
- 识别依赖关系和影响范围
2. **影响评估**
- 确定修改涉及的文件
- 评估对现有功能的影响
- 检查是否有breaking change
3. **任务分解**
- 使用 TodoWrite 工具创建任务清单
- 优先级排序
- 预估任务间的依赖
#### 检查清单
- [ ] 需求已明确，无歧义
- [ ] 影响范围已评估
- [ ] 任务已分解并创建 Todo
- [ ] 依赖项已识别
---
### 2. 设计 (Design)
**原则**：设计先行，避免返工。
#### 执行步骤
1. **接口设计**
- RESTful API 设计规范
- 请求/响应格式定义
- 错误码设计
2. **数据模型设计**
- 数据库表结构（如需）
- 配置项设计
- 数据流设计
3. **模块设计**
- 公共函数抽取
- 模块边界定义
- 依赖关系梳理
#### 检查清单
- [ ] API 接口设计已确定
- [ ] 数据模型已设计（如需）
- [ ] 模块划分已明确
- [ ] 向后兼容性已考虑
---
### 3. 实现 (Implementation)
**原则**：遵循代码规范，保持一致性。
#### 代码规范
1. **文件头部注释**
```python
# ///
# filename.py
# 描述：模块功能描述
# 作者：AI Generated
# 创建日期：YYYY-MM-DD
# ///
```
2. **函数注释**
```python
async def function_name(param1: str, param2: int) -> Dict[str, Any]:
"""
函数功能说明
Args:
param1: 参数1说明
param2: 参数2说明
Returns:
返回值说明
Raises:
HTTPException: 异常说明
"""
```
3. **命名规范**
- 类名：PascalCase (如 `NodeManager`)
- 函数名：snake_case (如 `send_message`)
- 常量：UPPER_SNAKE_CASE (如 `MAX_RETRIES`)
- API 字段：snake_case (如 `node_id`, `wechat_status`)
4. **路径规范**
- 项目根目录：`/Users/skn/Desktop/wxauto_api`
- 使用绝对路径
- 数据目录：`data/db`, `data/redis`, `data/logs`
#### 执行步骤
1. **创建 Todo 跟踪任务**
```python
TodoWrite(todos=[
{"id": "1", "content": "任务1", "status": "in_progress"},
{"id": "2", "content": "任务2", "status": "pending"},
])
```
2. **按优先级实现**
- 先核心功能，后辅助功能
- 先底层模块，后上层调用
- 先接口定义，后具体实现
3. **同步更新相关文件**
- API 路由 ↔ 服务层
- 前端 ↔ 后端接口
- 配置 ↔ 代码
#### 检查清单
- [ ] 代码符合注释规范
- [ ] 函数有文档字符串
- [ ] 命名符合规范
- [ ] 错误处理完善
- [ ] 无硬编码配置
---
### 4. 代码审核 (Code Review)
**原则**：主动发现并修复问题。
#### 自检清单
1. **逻辑检查**
- [ ] 所有分支都有处理
- [ ] 异常情况已处理
- [ ] 边界条件已考虑
2. **安全检查**
- [ ] 无硬编码密钥
- [ ] 输入已验证
- [ ] SQL 注入防护
- [ ] 权限检查完整
3. **性能检查**
- [ ] 无阻塞操作在 async 中
- [ ] 数据库连接正确关闭
- [ ] 无内存泄漏
4. **一致性检查**
- [ ] `node_id` vs `node_name` 使用正确
- [ ] 配置命名一致
- [ ] API 响应格式一致
#### 执行步骤
1. **代码自查**
- 逐文件检查
- 逐函数验证
2. **路径验证**
- Grep 搜索关键路径引用
- 确认无残留 `wxauto_center` 等旧路径
3. **导入验证**
```bash
python -c "from module import something"
```
#### 检查清单
- [ ] 代码通过自检清单
- [ ] 无路径错误
- [ ] 导入测试通过
- [ ] 配置一致性检查通过
---
### 5. 测试 (Testing)
**原则**：测试驱动开发，验证所有功能。
#### 测试类型
1. **单元测试**
- 工具函数测试
- 数据模型测试
- 业务逻辑测试
2. **集成测试**
- API 接口测试
- 数据库操作测试
- Redis 操作测试
3. **手动测试**
- 前端功能测试
- 端到端流程测试
#### 执行步骤
1. **启动服务**
```bash
# 本地开发
python main.py
# Docker 环境
docker compose up -d
```
2. **API 测试**
```bash
# 获取节点列表
curl -X GET "http://localhost:8080/api/v1/nodes/" \
-H "X-API-Key: your-external-api-key"
# 发送消息
curl -X POST "http://localhost:8080/api/v1/external/send" \
-H "X-ExternalKey: your-external-api-key" \
-H "Content-Type: application/json" \
-d '{"node_id": "wx1", "who": "文件传输助手", "msg": "test"}'
```
3. **验证清单**
- [ ] API 请求成功
- [ ] 响应格式正确
- [ ] 错误处理正确
- [ ] 前端显示正确
#### 检查清单
- [ ] 核心 API 测试通过
- [ ] 错误场景测试通过
- [ ] 前端功能正常
- [ ] 日志输出正常
---
### 6. 文档更新 (Documentation)
**原则**：文档与代码同步更新。
#### 文档类型
1. **API 文档** (`doc/API.md`)
- 接口说明
- 请求/响应示例
- 错误码说明
2. **架构文档** (`doc/ARCHITECTURE.md`)
- 系统架构图
- 模块说明
- 流程图
3. **部署文档** (`scripts/README.md`)
- Docker 部署说明
- 环境配置
- 故障排查
#### 执行步骤
1. **识别需更新的文档**
- 新增功能 → API 文档
- 架构变更 → 架构文档
- 部署变更 → 部署文档
2. **更新文档内容**
- 接口签名变更
- 响应格式变更
- 配置项变更
3. **添加变更记录**
- 版本号
- 变更日期
- 变更说明
#### 文档格式规范
**接口文档示例**
```markdown
### POST /api/v1/resource
发送消息
**请求参数**
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| node_id | string | 是 | 节点ID |
| who | string | 是 | 接收人 |
| msg | string | 是 | 消息内容 |
**响应示例**
```json
{
"success": true,
"data": {...}
}
```
**错误码**
| 错误码 | 说明 |
|--------|------|
| 404 | 节点不存在 |
| 503 | 节点不可用 |
```
#### 检查清单
- [ ] API 文档已更新
- [ ] 响应示例完整
- [ ] 错误码已说明
- [ ] 变更已记录
---
### 7. 脚本与部署 (Scripts & Deployment)
**原则**：部署脚本自动化，环境一致。
#### 脚本类型
1. **启动脚本** (`scripts/start_*.sh`)
- 环境检查
- 服务启动/停止
- 状态查看
2. **Docker 配置** (`Dockerfile`, `docker-compose.yml`)
- 多架构支持 (arm64/amd64)
- 数据卷挂载
- 环境变量
#### 执行步骤
1. **更新启动脚本**
- 路径正确性
- 架构兼容性
2. **更新 Docker 配置**
- 镜像版本
- 端口映射
- 数据目录
3. **验证部署**
```bash
# 本地构建测试
docker build -t wxauto-center:test .
# 启动测试
docker compose up -d
# 验证服务
curl http://localhost:8080/api/v1/nodes/
```
#### 检查清单
- [ ] 启动脚本路径正确
- [ ] Docker 配置正确
- [ ] 数据目录已创建
- [ ] 端口无冲突
- [ ] 多架构支持（如需）
---
## 流程总结
```
┌─────────────────────────────────────────────────────────────┐
│ AI 开发流程 │
├─────────────────────────────────────────────────────────────┤
│ 1. 需求分析 → 2. 设计 → 3. 实现 → 4. 审核 → 5. 测试 │
│ ↓ │
│ 6. 文档更新 → 7. 部署脚本 │
└─────────────────────────────────────────────────────────────┘
```
### 关键规则
1. **Todo 跟踪**：每个任务使用 TodoWrite 跟踪
2. **先设计后实现**：避免返工
3. **边做边测**：不要最后才测试
4. **文档同步**：代码变更即文档变更
5. **路径规范**：使用绝对路径，项目根目录为 `/Users/skn/Desktop/wxauto_api`
### 常用命令
```bash
# 安装依赖
pip install -r requirements.txt
# 启动服务
python main.py
# Docker 启动
docker compose up -d
# API 测试
curl http://localhost:8080/api/v1/nodes/
```
---
## 附录
### 配置管理
- 开发环境：`config.json`
- 环境变量：`.env`
- Docker 环境：通过 `docker-compose.yml` 配置
### 数据库
- PostgreSQL：端口 5432
- Redis：端口 6379
- 数据目录：`data/db`, `data/redis`
### 日志
- 应用日志：`data/logs/app.log`
- Docker 日志：`docker compose logs -f`