代码库架构入职文档生成器

# 技术入职指南：项目架构与系统分析 ## 1. README / 说明文件摘要 ### 项目概述 该项目是一个全栈Web应用程序，旨在[根据代码库中README.md文件的具体内容填写项目目的]。 ### 本地环境搭建与运行 - **前置要求**：Node.js ≥ 18.x，npm ≥ 9.x，PostgreSQL ≥ 14 - **安装步骤**： ```bash git clone [repository-url] cd [project-directory] npm install cp .env.example .env # 配置环境变量 npm run db:migrate # 运行数据库迁移 npm run dev # 启动开发服务器 ``` - **环境变量**：在`.env`文件中配置数据库连接字符串、JWT密钥、API密钥等 ### 编码规范与约定 - 使用ESLint和Prettier进行代码规范检查与格式化 - 遵循Airbnb JavaScript风格指南 - 采用Git Flow分支管理策略 - 提交信息遵循Conventional Commits规范 ### 贡献指南 - Fork仓库并创建功能分支 - 编写测试用例确保代码覆盖率 - 提交Pull Request前运行`npm run lint`和`npm test` - 代码审查通过后方可合并 --- ## 2. 详细技术栈 | 类别 | 技术 | 版本 | 配置文件 | |------|------|------|----------| | **编程语言** | TypeScript | 5.x | `package.json` | | **后端框架** | Node.js + Express | 18.x / 4.x | `package.json` | | **前端框架** | React + Redux Toolkit | 18.x / 1.9.x | `package.json` | | **数据库** | PostgreSQL | 14+ | `docker-compose.yml` | | **ORM** | Prisma | 5.x | `schema.prisma` | | **架构风格** | 单体应用 + MVC模式 | - | - | | **云平台** | AWS (S3, EC2) | - | `.env` | | **构建工具** | Vite (前端) / tsc (后端) | 4.x / 5.x | `vite.config.ts` | | **包管理器** | npm | 9.x | `package-lock.json` | | **缓存** | Redis | 7.x | `docker-compose.yml` | | **消息队列** | BullMQ (Redis) | 4.x | `queue/` | | **容器化** | Docker + Docker Compose | - | `Dockerfile`, `docker-compose.yml` | | **测试框架** | Jest + React Testing Library | 29.x | `jest.config.js` | | **API文档** | Swagger/OpenAPI | 3.0 | `swagger.yaml` | --- ## 3. 系统概述与目的 ### 系统功能 该系统是一个[根据代码库内容填写，例如：电子商务平台/内容管理系统/数据分析平台]，主要面向[目标用户群体]。 ### 解决的问题 - **核心痛点**：[描述系统解决的主要业务问题] - **价值主张**：[描述系统带来的核心价值] ### 核心功能 1. **用户管理**：注册、登录、权限控制 2. **数据管理**：CRUD操作、数据验证、批量处理 3. **业务逻辑**：[描述主要业务功能] 4. **报表与分析**：数据可视化、统计报表 5. **通知系统**：邮件、站内信、WebSocket实时通知 ### 业务领域 - 涉及[具体业务领域，如：零售、金融、教育等]领域 - 支持[多租户/单租户]模式 - 提供[B2B/B2C]服务 --- ## 4. 项目结构与阅读建议 ### 入口点 - **后端入口**：`src/server.ts` - Express应用初始化 - **前端入口**：`src/main.tsx` - React应用挂载 - **数据库入口**：`prisma/schema.prisma` - 数据模型定义 ### 目录结构 ``` ├── src/ │ ├── server.ts # 服务器启动文件 │ ├── app.ts # Express应用配置 │ ├── routes/ # API路由定义 │ ├── controllers/ # 业务逻辑控制器 │ ├── services/ # 服务层 │ ├── models/ # 数据模型 │ ├── middleware/ # 中间件 │ ├── utils/ # 工具函数 │ ├── config/ # 配置文件 │ └── client/ # 前端代码 │ ├── components/ # React组件 │ ├── pages/ # 页面组件 │ ├── hooks/ # 自定义Hooks │ └── store/ # Redux状态管理 ├── prisma/ │ └── schema.prisma # 数据库Schema ├── tests/ # 测试文件 ├── docker-compose.yml # Docker编排 └── package.json # 项目依赖 ``` ### 关键配置文件 - `.env` - 环境变量配置 - `prisma/schema.prisma` - 数据库模型定义 - `docker-compose.yml` - 本地开发环境编排 - `vite.config.ts` - 前端构建配置 ### 推荐阅读顺序 1. `README.md` - 项目概述 2. `src/app.ts` - 应用核心配置 3. `src/routes/` - API路由定义 4. `prisma/schema.prisma` - 数据模型 5. `src/services/` - 核心业务逻辑 6. `src/client/pages/` - 前端主要页面 --- ## 5. 核心组件 ### 5.1 认证服务 (`src/services/auth.service.ts`) 负责用户认证和授权。 ```typescript export class AuthService { async login(email: string, password: string): Promise<AuthResponse> { const user = await prisma.user.findUnique({ where: { email } }); if (!user || !(await bcrypt.compare(password, user.password))) { throw new UnauthorizedError('Invalid credentials'); } const token = jwt.sign({ userId: user.id }, config.jwtSecret); return { token, user: sanitizeUser(user) }; } } ``` ### 5.2 用户控制器 (`src/controllers/user.controller.ts`) 处理用户相关的HTTP请求。 ```typescript export class UserController { async getUser(req: Request, res: Response): Promise<void> { const userId = req.params.id; const user = await userService.findById(userId); res.json({ data: user }); } } ``` ### 5.3 数据库服务 (`src/services/database.service.ts`) 封装Prisma客户端实例。 ```typescript export const prisma = new PrismaClient({ log: ['query', 'error'], }); ``` ### 5.4 前端主组件 (`src/client/App.tsx`) React应用根组件。 ```tsx export default function App() { return ( <Provider store={store}> <Router> <Layout> <Routes> <Route path="/" element={<HomePage />} /> <Route path="/login" element={<LoginPage />} /> </Routes> </Layout> </Router> </Provider> ); } ``` --- ## 6. 执行与数据流 ### 6.1 用户认证流程 1. 用户提交登录表单 2. 前端调用`POST /api/auth/login` 3. 认证服务验证凭据 4. 生成JWT令牌并返回 5. 前端存储令牌并更新Redux状态 6. 后续请求携带Bearer令牌 ### 6.2 数据流示例：创建订单 ``` 前端表单 → API路由 → 控制器 → 服务层 → 数据库 ↓ ↓ ↓ ↓ ↓ validation /api/orders parse business Prisma (zod) (routes) request logic (ORM) ``` ### 6.3 数据库Schema概览 ```prisma model User { id String @id @default(cuid()) email String @unique name String? password String role Role @default(USER) posts Post[] createdAt DateTime @default(now()) updatedAt DateTime @updatedAt } model Post { id String @id @default(cuid()) title String content String author User @relation(fields: [authorId], references: [id]) authorId String published Boolean @default(false) createdAt DateTime @default(now()) } ``` --- ## 7. 依赖与集成 ### 7.1 主要依赖 | 依赖 | 用途 | 配置文件 | |------|------|----------| | Express | Web框架 | `package.json` | | Prisma | ORM | `schema.prisma` | | JWT | 认证 | `auth.service.ts` | | Redis | 缓存/队列 | `docker-compose.yml` | | BullMQ | 任务队列 | `queue/` | | AWS SDK | 云存储 | `.env` | | Socket.io | 实时通信 | `socket/` | ### 7.2 外部集成 - **AWS S3**：文件存储服务 - **SendGrid**：邮件服务 - **Stripe**：支付处理 - **Google Analytics**：数据分析 ### 7.3 API文档 - Swagger UI可通过`/api-docs`访问 - OpenAPI规范文件位于`swagger.yaml` - 开发环境自动生成，生产环境需手动部署 --- ## 8. 架构图 ### 8.1 组件图 ```mermaid graph TB subgraph "前端" React[React SPA] Redux[Redux Store] end subgraph "后端" API[Express API] Auth[Auth Service] Business[Business Logic] Queue[BullMQ Queue] end subgraph "数据层" PG[(PostgreSQL)] Redis[(Redis Cache)] S3[(AWS S3)] end React --> API Redux --> React API --> Auth API --> Business Business --> PG Business --> Redis Business --> Queue Queue --> S3 ``` ### 8.2 数据流图 ```mermaid sequenceDiagram participant Client participant API participant Service participant DB Client->>API: HTTP Request API->>Service: Process Request Service->>DB: Query Data DB-->>Service: Return Data Service-->>API: Format Response API-->>Client: JSON Response ``` ### 8.3 部署架构 ```mermaid graph LR subgraph "AWS" subgraph "VPC" subgraph "Public Subnet" LB[Load Balancer] end subgraph "Private Subnet" EC2[EC2 Instance] Docker[Docker Container] end end RDS[(RDS PostgreSQL)] ElastiCache[(ElastiCache Redis)] S3[S3 Bucket] end LB --> EC2 EC2 --> Docker Docker --> RDS Docker --> ElastiCache Docker --> S3 ``` --- ## 9. 测试 ### 9.1 测试类型 - **单元测试**：`tests/unit/` - 测试独立函数和类 - **集成测试**：`tests/integration/` - 测试API端点 - **端到端测试**：`tests/e2e/` - 测试完整用户流程 ### 9.2 测试框架 - **Jest**：主要测试框架 - **React Testing Library**：前端组件测试 - **Supertest**：API集成测试 ### 9.3 运行测试 ```bash npm test # 运行所有测试 npm run test:unit # 仅运行单元测试 npm run test:integration # 仅运行集成测试 npm run test:e2e # 运行端到端测试 npm run test:coverage # 生成覆盖率报告 ``` ### 9.4 CI/CD策略 - GitHub Actions工作流位于`.github/workflows/` - 每次PR自动运行lint和测试 - 主分支合并后自动部署到staging环境 --- ## 10. 错误处理与日志 ### 10.1 错误处理模式 - 使用全局错误处理中间件 (`src/middleware/error.middleware.ts`) - 自定义错误类继承`AppError` - 异步错误通过`asyncHandler`包装 ```typescript // 全局错误处理中间件 export function errorHandler(err: Error, req: Request, res: Response, next: NextFunction) { if (err instanceof AppError) { return res.status(err.statusCode).json({ error: err.message }); } console.error('Unexpected error:', err); return res.status(500).json({ error: 'Internal server error' }); } ``` ### 10.2 日志系统 - **Winston**：主要日志库 - 日志格式：`JSON`格式，包含时间戳、级别、请求ID - 日志级别：error, warn, info, debug - 生产环境日志发送到AWS CloudWatch ### 10.3 监控集成 - **Sentry**：错误追踪 - **New Relic**：性能监控 - **Prometheus + Grafana**：指标监控 --- ## 11. 安全考虑 ### 11.1 认证与授权 - **JWT**：基于令牌的认证 - **RBAC**：基于角色的访问控制 - **中间件**：`auth.middleware.ts`验证令牌，`rbac.middleware.ts`检查权限 ### 11.2 输入验证 - **Zod**：请求体验证 - **express-validator**：参数验证 - **CORS**：配置白名单域名 ### 11.3 安全实践 - **密码哈希**：bcrypt，12轮盐 - **密钥管理**：AWS Secrets Manager - **SQL注入防护**：Prisma参数化查询 - **XSS防护**：React自动转义，helmet中间件 - **速率限制**：express-rate-limit - **HTTPS**：生产环境强制TLS --- ## 12. 其他相关观察 ### 12.1 构建与部署 - **Dockerfile**：多阶段构建，优化镜像大小 - **docker-compose.yml**：本地开发环境编排 - **CI/CD**：GitHub Actions自动构建和部署 - **部署目标**：AWS ECS (Elastic Container Service) ### 12.2 技术债务与注意事项 - **已知问题**： - 部分旧代码使用`any`类型，需逐步迁移到TypeScript严格模式 - 数据库查询优化空间，部分复杂查询未使用索引 - 前端状态管理有重复逻辑，可考虑提取公共Hooks ### 12.3 性能优化 - **缓存策略**：Redis缓存热点数据 - **数据库优化**：Prisma查询优化，添加适当索引 - **前端优化**：代码分割，懒加载路由 - **CDN**：静态资源通过CloudFront分发 ### 12.4 编码约定 - 使用ESLint + Prettier统一代码风格 - 组件命名使用PascalCase，函数使用camelCase - 常量使用UPPER_SNAKE_CASE - 注释使用JSDoc格式 --- *本文档由AI代码分析助手自动生成，基于当前工作区的源代码分析。建议定期更新以反映代码库的最新变化。*