本目录包含 AI PPTist 项目的统一 API 规范文档，基于当前项目的分层架构和最佳实践。所有新开发的 API 必须遵循此规范。

• 文件: API设计与实现规范.md
• 内容: 统一的设计原则、分层架构、路由管理、代码实现规范
• 适用: 所有 API 的设计、开发和维护

• 文件: API响应与日志规范.md
• 内容: 统一的响应格式、错误处理、状态码规范、日志记录标准
• 适用: 所有 API 的响应格式和日志记录

• 文件: ../../backend/tests/README.md
• 内容: 测试框架指南、分层测试架构、单元测试和集成测试规范
• 适用: 所有后端测试用例的编写和维护

项目采用轻路由、重服务的分层架构：

• 端点层 (endpoints/): 处理 HTTP 请求和响应
• 处理器层 (handler/): 处理网络层逻辑和异常
• 服务层 (service/): 实现核心业务逻辑
• 仓库层 (repositories/): 封装数据访问细节

所有 API 响应必须使用标准格式：

{
  "status": "success",
  "message": "操作成功",
  "data": {},
  "error_code": null,
  "error_details": null,
  "timestamp": "2024-01-01T12:00:00Z",
  "request_id": "req_123456"
}

• 使用统一的日志消息模板
• 支持结构化数据记录
• 统一的异常处理模式
• 便于监控和排查

• 分层测试架构（单元测试 + 集成测试）
• 统一的测试配置管理
• 专用运行脚本支持
• 丰富的 Mock 工具和测试数据管理

1. 所有新开发的 API 必须遵循本规范
2. 现有 API 逐步迁移到标准格式
3. 错误处理使用统一错误码
4. 响应包含请求 ID 和时间戳
5. 编写符合规范的测试用例

1. 统一处理响应结构解析
2. 基于标准错误码进行错误处理
3. 支持请求追踪和调试

• OpenAPI 文档
• 后端代码库
• 前端代码库
• 测试框架指南

如发现规范问题或需要补充内容，请提交 Issue 或联系架构团队。