# 架构优化 PRD

## 1. 引言/概述

本次架构优化旨在提升后端服务的可维护性、可观测性和健壮性。通过引入统一日志、全局错误处理和响应封装，规范接口行为，便于团队协作和后续扩展。新增 Redis 支持，为缓存、限流等功能打下基础。

## 2. 目标

- 实现统一、可扩展的日志记录方案，支持分环境美化/存储/清理
- 实现全局错误捕获与标准化响应，支持分环境详细度
- 实现接口响应结构统一封装
- 集成 Redis，支持缓存、限流等能力
- 提升系统可观测性和异常可追溯性

## 3. 用户故事

- 作为开发者，我希望所有接口出错时能收到统一格式的错误响应，便于前端处理和排查。
- 作为运维，我希望能通过日志快速定位线上问题。
- 作为开发者，我希望所有接口响应结构一致，便于前后端协作。
- 作为开发者，我希望在开发环境下看到彩色美观的日志和详细错误堆栈。
- 作为运维，我希望生产环境日志能自动分文件存储并定期清理。
- 作为开发者，我希望能方便地使用 Redis 进行缓存、限流等操作。

## 4. 功能需求

1. **日志记录器**
    - 支持 info、warn、error、debug 等日志等级
    - 日志内容包含时间、等级、消息、上下文信息
    - 日志默认输出到控制台，后续可扩展到文件/远程
    - 关键操作、异常、接口请求需有日志
    - 每条请求日志包含唯一请求 id、method、url、状态码、耗时、IP、时间戳
    - dev 环境日志美化输出（带颜色）、控制台打印
    - prod 环境日志按天/小时分文件存储，支持定时清理历史日志
    - 日志格式美观，dev 环境带颜色区分 info/warn/error

2. **全局错误处理器**
    - 捕获所有未处理异常，返回统一 JSON 结构
    - 支持自定义业务异常类型
    - 错误日志自动记录
    - 错误响应结构需包含 code、message、data 字段
    - dev 环境异常响应包含详细堆栈，prod 环境仅输出友好错误信息

3. **响应封装**
    - 所有接口返回统一结构：`{ code, message, data }`
    - 支持自定义响应码和 message
    - 可扩展 traceId、耗时等字段

4. **请求日志中间件**
    - 记录 method、url、耗时、状态码、IP、请求 id
    - 日志链路追踪

5. **健康检查接口**
    - 提供 `/health` 路由，返回服务健康状态

6. **配置中心优化**
    - 所有配置集中到 config，支持多环境

7. **Redis 支持**
    - 集成 Redis，配置集中管理
    - Redis 连接池、健康检查
    - 预留缓存、限流、会话等场景的基础能力

8. **接口文档自动化完善**
    - Swagger UI 增加全局响应示例、错误码说明

## 5. 非目标（范围之外）

- 日志持久化到远程（本期仅本地文件）
- 速率限制、权限控制等安全功能

## 6. 设计考虑

- 日志、错误、响应封装均以中间件/插件方式实现，便于复用和扩展
- 代码与注释规范保持一致
- 目录结构建议：
    - `src/middlewares/logger.ts`
    - `src/middlewares/error-handler.ts`
    - `src/utils/response.ts`
    - `src/config/redis.config.ts`
- 日志库建议用 pino/winston/simple 自研
- 日志文件存储建议按天分目录，定时清理可用定时任务
- 请求 id 可用 nanoid/uuid 生成，并通过中间件注入上下文
- Redis 推荐用 bun:redis 原生或社区库

## 7. 技术考虑

- 日志库选型、日志文件清理策略
- 错误类型建议自定义 Error 类
- 响应封装为工具函数或 Elysia 插件
- Redis 连接池与健康检查实现

## 8. 成功指标

- 100% 接口响应结构统一
- 关键操作/异常均有日志
- 错误响应无堆栈泄漏，信息友好
- 日志分环境输出，生产环境日志可定期清理
- Redis 连接稳定，健康检查通过

## 9. 待解决问题

- 日志等级与格式细节
- 错误码与 message 规范
- 响应结构是否需 traceId、耗时等扩展字段
- Redis 具体使用场景细化