cursor-init/tasks/archive/20240610-prd-项目初始化.md

项目初始化 PRD（Bun.js + Elysia API 服务）

1. 引言/概述

本项目旨在基于 Bun.js 下的 Elysia 框架，搭建一个高效、可维护的 API 服务后端。项目将集成 MySQL 数据库、JWT 用户认证、自动生成 Swagger API 文档，采用 TypeScript 进行开发，配备 Vitest 测试框架，并严格遵循 ESLint + Prettier 代码规范和团队注释规范。项目结构分层清晰，便于后续扩展和团队协作。

2. 目标

• 快速搭建可运行的 Elysia API 服务基础工程。
• 支持 MySQL 数据库连接与基础操作。
• 集成 JWT 认证中间件，支持用户登录鉴权。
• 自动生成并暴露 Swagger API 文档。
• 采用 TypeScript，保证类型安全。
• 集成 Vitest 测试框架，支持单元与接口测试。
• 配置 ESLint + Prettier，统一代码风格。
• 遵循团队目录结构与注释规范。

3. 用户故事

• 作为开发者，我希望有一个结构清晰、规范统一的 API 服务项目模板，便于快速开发和维护。
• 作为开发者，我希望能方便地连接和操作 MySQL 数据库。
• 作为开发者，我希望项目自带 JWT 认证能力，便于后续扩展用户系统。
• 作为开发者，我希望能通过 Swagger UI 查看和调试所有 API。
• 作为开发者，我希望有完善的测试和代码规范工具，保证代码质量。

4. 功能需求

1. 项目初始化：
   • 必须基于 Bun.js 和 Elysia 框架初始化项目。
   • 必须采用 TypeScript。
2. 目录结构与规范：
   • 必须采用 rules 文件中最新推荐的分层目录结构：

     ├── src/
     │   ├── controllers/   # 路由与业务入口
     │   ├── services/      # 业务逻辑
     │   ├── models/        # 数据模型与类型定义
     │   ├── middlewares/   # 中间件
     │   ├── plugins/       # Elysia 插件
     │   ├── utils/         # 工具函数
     │   ├── validators/    # 参数校验
     │   ├── config/        # 配置文件
     │   ├── type/          # 类型定义文件
     │   └── app.ts         # 应用入口
     ├── tests/             # 测试用例
     ├── public/            # 静态资源
     ├── .env               # 环境变量
     ├── bun.lockb          # Bun 依赖锁
     ├── package.json
     └── README.md
     

   • 每个文件、类、方法、复杂逻辑必须有规范注释（参考注释规范 rules）。
3. 数据库集成：
   • 必须集成 MySQL 数据库，支持基础连接与操作。
   • 数据库配置需通过环境变量管理。
4. 认证与鉴权：
   • 必须集成 JWT 认证中间件，支持生成和校验 Token。
   • 提供基础的登录接口示例。
5. API 文档：
   • 必须集成 @elysiajs/swagger 插件，自动生成并暴露 Swagger UI。
   • 所有接口需完整描述参数、返回值、错误码等。
6. 代码规范与工具：
   • 必须集成 ESLint（含 TypeScript 规则）和 Prettier。
   • 必须配置 Vitest 测试框架，支持单元和接口测试。
   • 必须提供基础的 CI/CD 配置（如 GitHub Actions 示例）。
7. 示例接口：
   • 提供一个基础的健康检查接口（/api/health）。
   • 提供一个带 JWT 认证的示例接口。

5. 非目标（范围之外）

• 不实现具体的业务功能（如用户注册、复杂业务逻辑等）。
• 不集成除 MySQL 外的其他数据库。
• 不实现前端页面，仅提供 API 服务。
• 不实现国际化、定时任务、第三方服务集成等高级功能。

6. 设计考虑

• 目录结构、注释风格、接口风格等均严格参考 rules 文件规范。
• 所有配置（如数据库、JWT 密钥等）均通过 .env 文件和 config 目录集中管理。
• API 路由统一前缀为 /api。

7. 技术考虑

• 使用 Bun.js 作为运行时，Elysia 作为主框架。
• MySQL 连接推荐使用官方或社区兼容库（如 bun-mysql、mysql2 等）。
• JWT 推荐使用 @elysiajs/jwt 插件。
• Swagger 推荐使用 @elysiajs/swagger 插件。
• 测试推荐使用 Vitest，接口测试可用 supertest/undici。
• 代码规范工具需支持 TypeScript。

8. 成功指标

• 项目可一键启动并通过健康检查接口返回正常。
• 能成功连接 MySQL 并进行基础操作。
• JWT 认证流程可用，接口能正确校验 Token。
• Swagger UI 能自动展示所有接口文档。
• 通过 Vitest 测试，覆盖率不低于 80%。
• 代码通过 ESLint 检查并格式化。

9. 待解决问题

• MySQL 连接库的最终选择（bun-mysql、mysql2 等）。
• JWT 密钥和安全配置的管理细节。
• CI/CD 工具链的具体实现细节（如是否接入特定平台）。

</rewritten_file>