# 项目初始化 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>