# 组件架构

## 版本信息
| 版本 | 日期 | 描述 | 作者 |
|------|------|------|------|
| 2.4 | 2025-09-20 | 与主架构文档版本一致 | Winston |

### 前端组件架构

**实际项目组件组织**:
```text
src/client/
├── admin/                 # 管理后台应用
│   ├── components/        # 管理后台专用组件
│   │   ├── ProtectedRoute.tsx    # 路由保护组件
│   │   ├── ErrorPage.tsx         # 错误页面
│   │   └── NotFoundPage.tsx      # 404页面
│   ├── hooks/            # 管理后台Hooks
│   │   └── AuthProvider.tsx      # 认证状态管理
│   ├── layouts/          # 布局组件
│   │   └── MainLayout.tsx        # 主布局
│   ├── pages/            # 页面组件
│   │   ├── Dashboard.tsx         # 仪表板
│   │   ├── Login.tsx             # 登录页面
│   │   ├── Users.tsx             # 用户管理
│   │   └── Files.tsx             # 文件管理页面
│   ├── routes.tsx        # 路由配置
│   └── index.tsx         # 管理后台入口
├── home/                 # 用户前台应用
├── components/           # 共享UI组件
│   └── ui/              # shadcn/ui组件库（50+组件）
│       ├── button.tsx   # 按钮组件
│       ├── input.tsx    # 输入框组件
│       ├── table.tsx    # 表格组件
│       └── ...          # 其他组件
├── hooks/               # 共享Hooks
├── lib/                 # 工具库
├── utils/               # 工具函数
│   └── minio.ts         # MinIO上传工具
└── api.ts               # API客户端配置
```

**技术栈配置**:
- **前端框架**: React 19.1.0 + TypeScript
- **路由**: React Router v7
- **状态管理**: @tanstack/react-query (服务端状态) + Context (本地状态)
- **UI组件库**: shadcn/ui (基于Radix UI)
- **构建工具**: Vite 7.0.0
- **样式**: Tailwind CSS 4.1.11
- **HTTP客户端**: 基于Hono Client的封装 + axios适配器

### 后端组件架构

**实际后端项目结构**:
```text
src/server/
├── api/                    # API路由层
│   ├── auth/              # 认证相关路由
│   │   ├── login.ts       # 登录路由
│   │   ├── logout.ts      # 登出路由
│   │   └── register.ts    # 注册路由
│   ├── users/             # 用户管理路由
│   │   ├── index.ts       # 用户列表路由
│   │   ├── [id].ts        # 用户详情路由
│   │   └── __tests__/     # 路由测试
│   ├── roles/             # 角色管理路由
│   ├── files/              # 文件管理路由
│   │   ├── multipart-policy/    # 多部分上传策略
│   │   ├── multipart-complete/  # 完成多部分上传
│   │   ├── [id]/               # 文件操作路由
│   │   └── upload-policy/      # 上传策略路由
│   └── __integration_tests__/  # 集成测试
├── modules/               # 业务模块层
│   ├── auth/              # 认证业务模块
│   │   ├── auth.service.ts # 认证服务
│   │   └── __tests__/     # 认证测试
│   ├── users/             # 用户业务模块
│   │   ├── user.entity.ts  # 用户实体
│   │   ├── user.service.ts # 用户服务
│   │   └── __tests__/     # 用户测试
│   ├── files/              # 文件业务模块
│   │   ├── file.entity.ts  # 文件实体
│   │   ├── file.service.ts # 文件服务
│   │   ├── minio.service.ts # MinIO服务
│   │   ├── file.schema.ts  # 文件验证Schema
│   │   └── __tests__/     # 文件测试
├── utils/                 # 工具层
│   ├── generic-crud.service.ts  # 通用CRUD服务
│   ├── generic-crud.routes.ts   # 通用CRUD路由
│   ├── errorHandler.ts    # 错误处理
│   ├── backup.ts          # 数据库备份工具
│   ├── restore.ts         # 数据库恢复工具
│   ├── logger.ts          # 日志工具
│   └── __tests__/         # 工具测试
├── middleware/            # 中间件层
│   ├── auth.ts           # 认证中间件
│   └── validation.ts     # 验证中间件
├── types/                # 类型定义
├── data-source.ts        # 数据库连接配置
└── index.ts              # 服务器入口
```

**后端技术栈配置**:
- **框架**: Hono 4.8.5 + TypeScript
- **数据库**: PostgreSQL 15 + TypeORM 0.3.25
- **验证**: Zod schema验证
- **认证**: JWT Bearer Token
- **API文档**: @hono/zod-openapi + Swagger UI
- **测试**: Vitest + hono/testing

## 现有组件优化
**通用CRUD服务**:
- **责任**: 提供类型安全的通用CRUD操作，支持自定义扩展
- **现状**: 已实现完整功能，支持关联查询和复杂操作
- **优化重点**: 增强错误处理、添加测试覆盖、优化性能

**API文档组件**:
- **责任**: 自动生成和维护OpenAPI文档
- **现状**: 通过@hono/zod-openapi集成，提供Swagger UI
- **优化重点**: 完善文档示例、确保文档与代码同步

**文件管理服务**:
- **责任**: 提供MinIO对象存储集成，支持文件上传、下载、删除等操作
- **现状**: 已实现完整功能，支持分段上传、预签名URL生成
- **核心功能**:
  - 单文件上传（≤5MB）
  - 多部分分段上传（>5MB大文件）
  - 预签名URL生成（支持下载和直接访问）
  - 文件元数据管理（数据库记录）
  - 文件删除（同时删除MinIO对象和数据库记录）
- **优化重点**: 增强大文件处理能力，优化上传性能

## 组件交互
```mermaid
graph TD
    A[前端React组件] --> B[Hono API路由]
    B --> C[通用CRUD服务]
    C --> D[TypeORM实体]
    C --> E[Zod验证]
    B --> F[OpenAPI文档生成]
    F --> G[Swagger UI]
    B --> H[文件管理服务]
    H --> I[MinIO对象存储]
    H --> J[文件实体管理]

    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#fff3e0
    style D fill:#e8f5e8
    style H fill:#fff0f5
    style I fill:#f0fff0
```