codebase-summarizer

代码库摘要器

通过分析代码仓库，生成全面的架构文档。

核心工作流

1. 扫描结构：递归分析文件夹树和文件组织方式
2. 识别模式：检测框架、架构风格和关键目录
3. 映射入口点：查找主文件、路由、API 和 CLI 命令
4. 追踪数据流：跟踪请求在各层之间的流转（控制器 → 服务 → 模型）
5. 记录模块：说明各目录的用途和职责
6. 创建导航：为常见任务编写“操作指南”
7. 生成图表：添加 Mermaid 图表以直观呈现架构

文档结构

ARCHITECTURE.md 模板

# Architecture Overview

## System Summary

[Project Name] is a [type] application built with [stack]. It follows [architecture pattern] and handles [primary use cases].

**Tech Stack:**

- Frontend: [framework + key libraries]
- Backend: [framework + key libraries]
- Database: [database + ORM]
- Infrastructure: [hosting + CI/CD]

## High-Level Architecture

```mermaid
graph TB
    Client[Client/Browser] --> API[API Layer]
    API --> Services[Business Logic]
    Services --> DB[(Database)]
    Services --> Cache[(Redis Cache)]
    API --> Queue[Message Queue]
```

项目结构

src/
├── app/              # Application entry point and routing
├── components/       # Reusable UI components
├── lib/              # Utility functions and helpers
├── services/         # Business logic layer
├── models/           # Data models and schemas
└── types/            # TypeScript type definitions

关键组件

入口点

主应用： src/app/page.tsx

• 应用入口点
• 初始化提供程序和路由
• 处理全局错误边界

API 路由： src/app/api/

• RESTful API 端点
• 身份验证中间件
• 请求验证

核心模块

身份验证（src/services/auth/）

• 用户登录和注册
• JWT 令牌管理
• OAuth2 集成
• 依赖项：bcrypt、jsonwebtoken

用户管理（src/services/users/）

• 用户的 CRUD 操作
• 个人资料管理
• 基于角色的访问控制
• 依赖项：Prisma、验证库

数据层（src/models/）

• 数据库架构
• Prisma 模型
• 查询构建器
• 依赖项：Prisma Client

数据流

用户注册流程

sequenceDiagram
    Client->>API: POST /api/auth/register
    API->>Validation: Validate input
    Validation->>Services: UserService.create()
    Services->>Database: Insert user
    Database-->>Services: User created
    Services->>Email: Send welcome email
    Services-->>API: Return JWT
    API-->>Client: 201 Created

请求生命周期

1. 收到请求 → API 路由处理器（src/app/api/[endpoint]/route.ts）
2. 中间件 → 身份验证、验证、速率限制
3. 服务层 → 业务逻辑（src/services/）
4. 数据层 → 数据库查询（src/models/）
5. 响应 → 格式化并返回数据

常见模式

服务模式

// src/services/users/user.service.ts
export class UserService {
  async findById(id: string) {
    return prisma.user.findUnique({ where: { id } });
  }

  async create(data: CreateUserDto) {
    // Validation, business logic, database operations
  }
}

仓储模式

// src/repositories/user.repository.ts
export class UserRepository {
  async findAll() {
    /* DB queries only */
  }
  async findById(id: string) {
    /* DB queries only */
  }
}

操作指南

添加新的 API 端点

1. 创建路由文件： src/app/api/[name]/route.ts

   export async function GET(req: Request) {
     // Implementation
   }
   

2. 添加服务逻辑： src/services/[name].service.ts

3. 定义类型： src/types/[name].ts

4. 添加测试： src/app/api/[name]/route.test.ts

5. 更新 API 文档： 在 OpenAPI/Swagger 中编写文档

添加新的数据库模型

1. 更新架构： prisma/schema.prisma

   model NewModel {
     id String @id @default(cuid())
     // fields
   }
   

2. 运行迁移： npx prisma migrate dev --name add-new-model

3. 生成类型： npx prisma generate

4. 创建服务： src/services/new-model.service.ts

5. 添加 CRUD 路由： src/app/api/new-model/

添加新的 React 组件

1. 创建组件： src/components/NewComponent/NewComponent.tsx
2. 添加样式： NewComponent.module.css 或内联 Tailwind
3. 编写测试： NewComponent.test.tsx
4. 添加 stories： NewComponent.stories.tsx（如果使用 Storybook）
5. 导出： 更新 src/components/index.ts

修改身份验证

1. 服务层： src/services/auth/auth.service.ts
2. 中间件： src/middleware/auth.middleware.ts
3. 路由： src/app/api/auth/
4. 更新测试： 确保身份验证流程仍可正常运行

关键文件参考

文件	用途	修改时机
src/app/layout.tsx	根布局、提供程序	修改全局布局
src/lib/db.ts	数据库连接	修改连接配置
src/lib/api.ts	API 客户端设置	修改请求拦截器
src/middleware.ts	Next.js 中间件	修改身份验证、重定向
prisma/schema.prisma	数据库架构	修改数据模型
.env.example	环境变量	添加配置值

依赖项

关键依赖项

• next - React 框架
• prisma - ORM 和数据库工具包
• react - UI 库
• typescript - 类型安全

关键库

• zod - 模式验证
• bcrypt - 密码哈希
• jsonwebtoken - JWT 处理
• date-fns - 日期工具

开发工作流

1. **本地设置：**参见 DEVELOPMENT.md
2. **进行更改：**创建分支 → 实现 → 测试 → PR
3. 运行测试：pnpm test
4. **数据库更改：**Prisma 迁移工作流
5. **部署：**Vercel 自动部署

故障排查

数据库连接错误

• 检查 .env 中的 DATABASE_URL
• 确保数据库正在运行
• 运行 npx prisma generate

模式更改后出现类型错误

• 运行 npx prisma generate
• 重启 TypeScript 服务器

构建失败

• 清除 .next 文件夹：rm -rf .next
• 清除 node_modules：rm -rf node_modules && pnpm install

其他资源

• API 文档 - 端点参考
• 开发指南 - 设置和工作流
• 贡献指南 - 代码规范
• 数据库模式 - 数据模型详情

## Analysis Techniques

### Identify Framework
Look for telltale files:
- `next.config.js` → Next.js
- `vite.config.ts` → Vite
- `nest-cli.json` → NestJS
- `manage.py` → Django
- `Cargo.toml` → Rust

### Map Entry Points
- Frontend: `index.html`, `main.tsx`, `app.tsx`, `_app.tsx`
- Backend: `main.ts`, `server.ts`, `app.py`, `index.js`
- CLI: `cli.ts`, `__main__.py`, `main.go`

### Trace Request Flow
Follow typical paths:
1. Route/endpoint definition
2. Middleware/guards
3. Controller/handler
4. Service/business logic
5. Repository/model
6. Database query

### Module Categories
- **Core**: Essential business logic
- **Infrastructure**: Database, cache, queue
- **Utilities**: Helpers, formatters, validators
- **Features**: User-facing functionality
- **Config**: Environment, settings

## Mermaid Diagrams

### Architecture Diagram
```mermaid
graph LR
    Client --> NextJS
    NextJS --> API
    API --> Services
    Services --> Prisma
    Prisma --> PostgreSQL

数据流

sequenceDiagram
    participant Client
    participant API
    participant Service
    participant DB
    Client->>API: Request
    API->>Service: Process
    Service->>DB: Query
    DB-->>Service: Data
    Service-->>API: Result
    API-->>Client: Response

模块关系

graph TB
    API[API Layer] --> Auth[Auth Service]
    API --> Users[User Service]
    Auth --> DB[(Database)]
    Users --> DB
    Users --> Cache[(Cache)]

最佳实践

1. **从高层次开始：**先概览，再看细节
2. **优先使用图示：**复杂流程使用图表
3. **具体明确：**引用实际文件路径
4. **展示示例：**包含代码片段
5. **链接相关文档：**引用其他文档
6. **保持更新：**随架构演进而更新
7. **面向开发者：**为新成员入职和日常使用而编写

输出清单

每份代码库摘要都应包含：

• 系统概览和技术栈
• 高层架构图
• 项目结构说明
• 入口点标识
• 模块／目录用途
• 数据流图
• 常见模式说明
• 常见任务的“操作指南”
• 关键文件参考表
• 依赖项说明
• 故障排查部分