# 出行服务项目架构文档

## 版本信息
| 版本 | 日期 | 描述 | 作者 |
|------|------|------|------|
| 3.1 | 2025-10-15 | 更新乘客信息支持多种证件类型 | Winston |
| 3.0 | 2025-10-15 | 更新为出行服务项目架构 | Winston |
| 2.4 | 2025-09-20 | 完善BMAD全栈架构规范，添加高层架构图、API规范、安全架构 | Winston |
| 2.3 | 2025-09-20 | 根据实际项目结构更新测试架构和共享目录 | Winston |
| 2.2 | 2025-09-19 | 更新测试策略文档引用 | Winston |
| 2.1 | 2025-09-19 | 添加数据库定时备份策略 | Winston |
| 2.0 | 2025-09-14 | 增强架构文档 | Winston |

## 介绍

本文档定义了出行服务项目的整体架构方案，基于对mini-demo页面迁移项目的深度分析。主要目标是将演示原型转化为功能完整的出行服务平台，同时保持技术架构的现代化和可扩展性。

**注意**: 本项目的详细架构文档已拆分为多个子文档，位于 `docs/architecture/` 目录中。如需查看完整的架构文档结构，请参阅 [架构文档索引](./architecture/index.md)。

### 新增Taro小程序和Tailwind规范
基于mini项目迁移需求，新增以下规范文档：
- [Taro小程序开发规范](./architecture/taro-mini-program-standards.md) - Taro小程序开发最佳实践
- [Tailwind CSS样式规范](./architecture/tailwind-css-standards.md) - Tailwind CSS使用规范
- [mini-demo迁移指导规范](./architecture/mini-demo-migration-guide.md) - 从原生小程序迁移到Taro的详细指导（包含精确样式迁移）
- [管理后台开发规范](./architecture/admin-dashboard-standards.md) - 管理后台开发标准和最佳实践

### 文档范围
全面定义出行服务项目的架构方案、技术栈选择、数据模型设计和集成策略

### 变更日志
| 日期 | 版本 | 描述 | 作者 |
|------|------|------|------|
| 2025-10-15 | 3.1 | 更新乘客信息支持多种证件类型（身份证、港澳通行证、台湾通行证、护照等） | Winston |
| 2025-10-15 | 3.0 | 更新为出行服务项目架构 | Winston |
| 2025-09-20 | 2.4 | 完善BMAD全栈架构规范，添加高层架构图、API规范、安全架构 | Winston |
| 2025-09-20 | 2.3 | 根据实际项目结构更新测试架构和共享目录 | Winston |
| 2025-09-19 | 2.2 | 更新测试策略文档引用 | Winston |
| 2025-09-19 | 2.1 | 添加数据库定时备份策略 | Winston |
| 2025-09-14 | 2.0 | 增强架构文档 | Winston |
| 2024-09-14 | 1.0 | 初始现有系统分析 | Winston |

## 现有项目分析

### 当前项目状态
- **主要用途**: 出行服务小程序平台，支持拼车、商务车、包车等出行服务
- **项目结构**: 三目录结构（mini-demo、mini、src）
  - **mini-demo**: 微信原生小程序，16个出行服务页面，纯前端演示
  - **mini**: Taro + React 小程序项目，基础框架已搭建
  - **src**: Hono + TypeORM 后端API和管理后台，用户管理基础已实现
- **技术栈总结**: Node.js 20.19.2 + Hono 4.8.5 + Taro + React + TypeORM 0.3.25 + PostgreSQL 17
- **架构风格**: 分层架构，前后端分离，统一仓库管理
- **部署方式**: 多八多云端开发容器环境，开放8080端口外网访问

### 可用文档分析
✅ **技术文档完整**:
- 技术栈和版本信息准确
- 源码结构和模块组织清晰
- 数据模型定义完整
- API规范通过OpenAPI自动生成
- 完整的PRD和项目简报

✅ **已补充**:
- 出行服务业务数据模型（基于MVP需求）
- 活动-路线关系管理架构
- 订单处理流程文档
- 支付集成详细设计

### 识别出的约束
- 必须保持与现有shadcn设计系统的兼容性
- 需要支持PostgreSQL关系型数据库
- 前端构建基于Vite，后端基于Hono
- 部署环境支持Docker容器化
- 必须兼容微信小程序平台限制
- 需要支持活动-路线关系管理（1个活动关联多条线路）
- 需要支持多个乘客信息管理（下单时选择N个乘车人）
- 现有代码中存在一些`any`类型需要修复

## 项目范围和集成策略

### 项目概述
- **项目类型**: mini-demo页面迁移和出行服务系统构建
- **范围**: 将演示原型转化为功能完整的出行服务平台
- **MVP范围**: 基于MVP需求，实现核心出行服务功能，不包括积分商城、优惠券、会员等级等高级功能
- **集成影响级别**: 高 - 需要新增出行业务数据模型和核心功能

### 集成方法
- **代码集成策略**: 渐进式迁移，保持业务连续性
- **数据库集成**: 新增出行服务数据模型（活动、路线、订单、乘客），扩展现有用户管理
- **API集成**: 新增出行服务API，保持现有API兼容
- **UI集成**: 迁移mini-demo页面到Taro + React，保持用户体验一致性
- **MVP重点**: 优先实现路线查询、活动筛选、订单管理、乘客管理、支付集成等核心功能

### 兼容性要求
- **现有API兼容性**: 100%保持，不破坏现有客户端
- **数据库Schema兼容性**: 扩展现有模型，确保数据完整性
- **UI/UX一致性**: 迁移页面保持原有交互体验
- **性能影响**: 页面加载时间<2秒，API响应时间<500ms，无性能退化

## 高层架构

### 平台和基础设施选择
**平台**: 多八多云端开发容器环境
**核心服务**: PostgreSQL 17, Redis 7, MinIO对象存储
**部署主机**: Node.js 20.19.2运行时，开放8080端口外网访问
**区域**: 本地开发环境，生产环境参数相同
**目标平台**: 微信小程序为主要发布平台

### 架构图
```mermaid
graph TD
    subgraph "前端应用层"
        A[Taro + React 小程序] --> B[微信小程序API]
        A --> C[React Query 状态管理]
        A --> D[shadcn/ui 组件库]
        E[React 管理后台] --> F[React Router v7]
    end

    subgraph "API网关层"
        G[Hono 4.8.5 API路由] --> H[Zod Schema验证]
        G --> I[JWT认证中间件]
        G --> J[OpenAPI文档生成]
    end

    subgraph "业务服务层"
        K[出行服务模块] --> L[活动管理服务]
        K --> M[路线管理服务]
        K --> N[订单管理服务]
        K --> O[乘客管理服务]
        K --> P[支付集成服务]
        Q[通用CRUD服务] --> R[TypeORM实体管理]
        Q --> S[数据库备份工具]
    end

    subgraph "数据存储层"
        T[PostgreSQL 17] --> U[用户数据]
        T --> V[活动数据]
        T --> W[路线数据]
        T --> X[订单数据]
        T --> Y[乘客数据]
        Z[Redis 7 缓存] --> AA[会话缓存]
        AB[MinIO 对象存储] --> AC[文件存储]
    end

    subgraph "第三方服务"
        AD[微信支付] --> AE[支付处理]
        AF[地图服务] --> AG[位置服务]
    end

    subgraph "基础设施层"
        AH[多八多云端容器] --> AI[Node.js 20.19.2]
        AJ[开放8080端口] --> AK[外网访问]
    end

    A --> G
    E --> G
    G --> K
    G --> Q
    K --> T
    Q --> T
    G --> Z
    G --> AB
    K --> AD
    K --> AF
    J --> AL[Swagger UI /ui]

    style A fill:#e1f5fe
    style E fill:#f3e5f5
    style G fill:#fff3e0
    style K fill:#e8f5e8
    style O fill:#fff0f5
    style R fill:#e8f5e8
    style W fill:#ffebee
    style Y fill:#f3e5f5
    style AA fill:#fff3e0
    style AC fill:#e1f5fe
```

### 架构模式
- **分层架构**: 清晰的前后端分离，统一的代码仓库管理
- **组件化UI**: 基于Taro + React + shadcn/ui的可复用组件架构
- **RESTful API**: 遵循OpenAPI规范的统一API设计
- **通用CRUD模式**: 类型安全的通用数据操作服务
- **中间件模式**: 统一的认证、验证、错误处理中间件
- **领域驱动设计**: 基于出行服务业务领域的模块化设计
- **快照模式**: 订单数据快照确保历史数据完整性
- **活动-路线关联模式**: 支持1个活动关联多条路线的业务模型

## 技术栈

### 现有技术栈维护
| 类别 | 当前技术 | 版本 | 在项目中的用途 | 备注 |
|------|----------|------|----------------|------|
| 运行时 | Node.js | 20.19.2 | 服务器运行时环境 | ES模块支持 |
| 框架 | Hono | 4.8.5 | Web框架和API路由 | RPC类型安全 |
| 前端框架 | Taro + React | 最新 | 小程序用户界面构建 | 多端支持 |
| 构建工具 | Vite | 7.0.0 | 开发服务器和构建 | 热重载支持 |
| 数据库 | PostgreSQL | 17 | 数据持久化存储 | 通过TypeORM |
| ORM | TypeORM | 0.3.25 | 数据库操作抽象 | 实体管理 |
| 样式 | Tailwind CSS | 4.1.11 | 原子化CSS框架 | 设计一致性 |
| 状态管理 | React Query | 5.83.0 | 服务端状态管理 | 数据同步 |
| 认证 | JWT | 9.0.2 | 用户认证和安全 | Bearer Token |

### 新技术添加
| 技术 | 版本 | 用途 | Rationale | 集成方法 |
|------|------|------|-----------|-----------|
| Vitest | 2.x | 单元测试框架 | 填补测试空白，确保代码质量，更好的TypeORM支持 | 集成到现有构建流程 |
| Testing Library | 13.x | React组件测试 | 提供组件级测试能力 | 与React项目集成 |
| hono/testing | 内置 | API端点测试 | 验证API功能和集成 | Hono官方测试工具，更好的类型安全 |
| node-cron | latest | 定时任务调度 | Node.js定时任务调度库 | 集成到应用启动流程 |
| MinIO | latest | 对象存储服务 | 提供可扩展的文件存储解决方案，支持大文件上传和分段上传 | 通过MinIO客户端SDK集成 |
| MinIO客户端SDK | latest | MinIO API集成 | 提供与MinIO服务的完整交互能力 | 后端服务集成 |

| Taro | 最新 | 多端小程序框架 | 支持微信小程序发布，更好的开发体验 | 替换mini-demo原生开发 |
| 微信支付SDK | 最新 | 支付集成 | 支持出行服务支付需求 | 后端API集成 |
| 地图服务SDK | 最新 | 位置服务 | 支持路线规划和位置跟踪 | 前后端集成 |
| 活动-路线管理 | 自定义 | 活动路线关系 | 支持1个活动关联多条路线 | 业务逻辑层实现 |
| 多乘客管理 | 自定义 | 乘客信息管理 | 支持下单时选择N个乘车人 | 业务逻辑层实现 |

## 数据模型和Schema变更

### 现有数据模型状态
**用户模型**:
- **现状**: 设计良好，包含完整的用户管理和权限系统
- **关键属性**:
  - `id`: number - 主键标识符
  - `username`: string - 唯一用户名（主要登录标识）
  - `email`: string | null - 可选邮箱地址
  - `password`: string - 加密密码（bcrypt哈希）
  - `roles`: Role[] - 用户角色多对多关系
- **关系**: 与Role实体建立正确的多对多关系映射

**文件管理模型**:
- **现状**: 新增完整的文件管理系统，支持MinIO对象存储
- **关键属性**:
  - `id`: number - 主键标识符
  - `name`: string - 文件名
  - `path`: string - MinIO存储路径
  - `size`: number - 文件大小（字节）
  - `type`: string - 文件类型
  - `uploadUserId`: number - 上传用户ID
  - `uploadTime`: Date - 上传时间
- **关系**: 与User实体建立多对一关系映射

### 新增出行服务数据模型
**活动模型**:
- **用途**: 管理出行活动，关联多条路线
- **关键属性**:
  - `id`: number - 主键标识符
  - `name`: string - 活动名称
  - `type`: ActivityType - 活动类型（去程活动/返程活动）
  - `startDate`: Date - 活动开始日期
  - `endDate`: Date - 活动结束日期
  - `status`: ActivityStatus - 活动状态

**路线模型**:
- **用途**: 管理出行路线，关联到活动
- **关键属性**:
  - `id`: number - 主键标识符
  - `activityId`: number - 关联的活动ID
  - `startPoint`: string - 上车点
  - `endPoint`: string - 下车点
  - `departureTime`: Date - 出发时间
  - `vehicleType`: string - 车型
  - `maxPassengers`: number - 最大乘客数
  - `price`: number - 价格
  - `driverPlate`: string - 司机车牌
  - `driverPhone`: string - 司机电话

**订单模型**:
- **用途**: 管理出行订单信息
- **关键属性**:
  - `id`: number - 主键标识符
  - `userId`: number - 用户ID
  - `routeId`: number - 路线ID
  - `activityId`: number - 活动ID
  - `passengerCount`: number - 乘客数量
  - `totalAmount`: number - 订单总金额
  - `status`: string - 订单状态（待出发、行程中、已完成、已取消）
  - `paymentStatus`: string - 支付状态
  - `passengerSnapshots`: JSON - 乘客信息快照数组（下单时的多个乘客信息）
  - `routeSnapshot`: JSON - 路线信息快照（下单时的路线信息）
  - `createdAt`: Date - 创建时间

**乘客模型**:
- **用途**: 管理乘客信息
- **关键属性**:
  - `id`: number - 主键标识符
  - `userId`: number - 用户ID
  - `name`: string - 乘客姓名
  - `idType`: IdType - 证件类型（身份证、回乡证、护照等）
  - `idNumber`: string - 证件号码
  - `phone`: string - 手机号
  - `isDefault`: boolean - 是否默认乘客

**积分模型**:
- **用途**: 管理用户积分（MVP阶段暂不实现）
- **关键属性**:
  - `id`: number - 主键标识符
  - `userId`: number - 用户ID
  - `points`: number - 积分余额
  - `earnedPoints`: number - 累计获得积分
  - `usedPoints`: number - 累计使用积分

### TypeScript接口定义
```typescript
// 用户实体接口
export interface User {
  id: number;
  username: string;
  email: string | null;
  password: string;
  roles: Role[];
  createdAt: Date;
  updatedAt: Date;
}

// 角色实体接口
export interface Role {
  id: number;
  name: string;
  permissions: string[];
  users: User[];
  createdAt: Date;
  updatedAt: Date;
}

// 活动实体接口
export interface Activity {
  id: number;
  name: string;
  type: ActivityType;
  startDate: Date;
  endDate: Date;
  status: ActivityStatus;
  routes: Route[];
  createdAt: Date;
  updatedAt: Date;
}

// 路线实体接口
export interface Route {
  id: number;
  activityId: number;
  activity: Activity;
  startPoint: string;
  endPoint: string;
  departureTime: Date;
  vehicleType: VehicleType;
  maxPassengers: number;
  price: number;
  driverPlate: string;
  driverPhone: string;
  availableSeats: number;
  orders: Order[];
  createdAt: Date;
  updatedAt: Date;
}

// 订单实体接口
export interface Order {
  id: number;
  userId: number;
  user: User;
  routeId: number;
  route: Route;
  activityId: number;
  activity: Activity;
  passengerCount: number;
  totalAmount: number;
  status: OrderStatus;
  paymentStatus: PaymentStatus;
  passengerSnapshots: PassengerSnapshot[];
  routeSnapshot: RouteSnapshot;
  passengers: Passenger[];
  createdAt: Date;
  updatedAt: Date;
}

// 乘客实体接口
export interface Passenger {
  id: number;
  userId: number;
  user: User;
  name: string;
  idType: IdType; // 证件类型
  idNumber: string; // 证件号码
  phone: string;
  isDefault: boolean;
  orders: Order[];
  createdAt: Date;
  updatedAt: Date;
}

// 乘客信息快照接口
export interface PassengerSnapshot {
  name: string;
  idType: IdType; // 证件类型
  idNumber: string; // 证件号码
  phone: string;
  isDefault: boolean;
}

// 路线信息快照接口
export interface RouteSnapshot {
  startPoint: string;
  endPoint: string;
  departureTime: Date;
  vehicleType: VehicleType;
  maxPassengers: number;
  price: number;
  driverPlate: string;
  driverPhone: string;
}

// 积分实体接口
export interface Points {
  id: number;
  userId: number;
  user: User;
  points: number;
  earnedPoints: number;
  usedPoints: number;
  lastUpdated: Date;
}

// 枚举定义
export enum OrderStatus {
  WAITING_DEPARTURE = '待出发',
  IN_PROGRESS = '行程中',
  COMPLETED = '已完成',
  CANCELLED = '已取消'
}

export enum PaymentStatus {
  PENDING = '待支付',
  PAID = '已支付',
  FAILED = '支付失败',
  REFUNDED = '已退款'
}

export enum VehicleType {
  CARPOOL = '拼车',
  BUSINESS = '商务车',
  CHARTER = '包车'
}

export enum ActivityType {
  OUTBOUND = '去程活动',
  INBOUND = '返程活动'
}

export enum ActivityStatus {
  ACTIVE = '进行中',
  ENDED = '已结束',
  CANCELLED = '已取消'
}

export enum IdType {
  ID_CARD = '身份证',
  HONG_KONG_MACAO_PASS = '港澳通行证',
  TAIWAN_PASS = '台湾通行证',
  PASSPORT = '护照',
  OTHER = '其他证件'
}

// 分页响应接口
export interface PaginatedResponse<T> {
  data: T[];
  pagination: {
    total: number;
    current: number;
    pageSize: number;
    totalPages: number;
  };
}
```

### 数据关系
- **User ↔ Role**: 多对多关系，通过中间表关联
- **User → Order**: 一对多关系，一个用户可以创建多个订单
- **User → Passenger**: 一对多关系，一个用户可以管理多个乘客
- **User → Points**: 一对一关系，每个用户有一个积分账户（MVP阶段暂不实现）
- **Activity → Route**: 一对多关系，一个活动可以关联多条路线
- **Route → Order**: 一对多关系，一条路线可以有多个订单
- **Order ↔ Passenger**: 多对多关系，一个订单可以有多个乘客，一个乘客可以出现在多个订单中
- **User → (createdAt, updatedAt)**: 自动时间戳管理
- **Role → permissions**: 字符串数组存储权限列表

**快照设计说明**:
- **passengerSnapshots**: 存储下单时的多个乘客信息快照数组，确保订单历史数据完整性
- **routeSnapshot**: 存储下单时的路线信息快照，防止路线信息变更影响历史订单

### Schema集成策略
- **数据库变更要求**: 新增出行服务数据表，扩展现有用户管理
- **新表**: activity表（活动管理）、route表（路线管理）、order表（订单管理）、passenger表（乘客管理）
- **可选表**: points表（积分管理，MVP阶段暂不实现）
- **修改的表**: 无结构性变更
- **新索引**: 为订单查询字段添加索引（userId, status, createdAt）、为路线查询字段添加索引（startPoint, endPoint, departureTime）、为活动查询字段添加索引（type, status）
- **迁移策略**: 使用TypeORM迁移工具，确保数据完整性

### 向后兼容性
- 保持所有现有API端点不变
- 确保现有数据查询继续正常工作
- 不修改任何现有字段定义
- 新增功能通过可选字段或新端点实现

## 组件架构

### 前端组件架构

**实际项目组件组织**:
```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.middleware.ts           # 认证中间件
│   └── permission.middleware.ts     # 权限中间件
├── types/                # 类型定义
├── data-source.ts        # 数据库连接配置
└── index.ts              # 服务器入口
```

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

### 通用CRUD服务
- **责任**: 提供类型安全的通用CRUD操作，支持自定义扩展
- **现状**: 已实现完整功能，支持关联查询和复杂操作
- **文件位置**: `src/server/utils/generic-crud.service.ts`
- **路由生成**: `src/server/utils/generic-crud.routes.ts`
- **优化重点**: 增强错误处理、添加测试覆盖、优化性能
- **详细规范**: 参见 [通用CRUD规范](./architecture/generic-crud-standards.md)

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

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

### 组件交互
```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[文件实体管理]

    subgraph "文件上传流程"
        K[前端上传组件] --> L[获取上传策略]
        L --> M[直接上传到MinIO]
        M --> N[更新文件记录]
    end

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

## API设计和集成

### API集成策略
- **API集成策略**: 保持现有RESTful API设计，增强OpenAPI文档
- **认证**: JWT Bearer Token，保持现有认证机制
- **版本控制**: 使用v1前缀 (`/api/v1/`)，保持向后兼容

### OpenAPI规范
```yaml
openapi: 3.0.0
info:
  title: D8D Starter API
  version: 1.0.0
  description: D8D Starter项目RESTful API文档
servers:
  - url: http://localhost:8080/api/v1
    description: 本地开发环境
  - url: https://api.example.com/api/v1
    description: 生产环境

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        username:
          type: string
        email:
          type: string
          nullable: true
        roles:
          type: array
          items:
            $ref: '#/components/schemas/Role'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Role:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        permissions:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    PaginatedUsers:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Pagination:
      type: object
      properties:
        total:
          type: integer
        current:
          type: integer
        pageSize:
          type: integer
        totalPages:
          type: integer

security:
  - BearerAuth: []
```

### API端点示例
**用户管理端点**:
- **方法**: GET
- **端点**: `/api/v1/users`
- **用途**: 获取用户分页列表
- **集成**: 使用通用CRUD服务，支持搜索和过滤

**文件管理端点**:
- **方法**: POST
- **端点**: `/api/v1/files/upload-policy`
- **用途**: 生成文件上传策略和预签名URL
- **集成**: 使用MinIO服务，支持分段上传和大文件处理

**请求示例**:
```json
{
  "page": 1,
  "pageSize": 10,
  "keyword": "搜索词",
  "sortBy": "createdAt",
  "sortOrder": "DESC"
}
```

**响应示例**:
```json
{
  "data": [
    {
      "id": 1,
      "email": "user@example.com",
      "roles": [{"id": 1, "name": "admin"}]
    }
  ],
  "pagination": {
    "total": 100,
    "current": 1,
    "pageSize": 10
  }
}
```

## 源码树和文件组织

### 实际项目结构
```text
d8d-starter/
├── src/
│   ├── client/                 # React前端应用
│   │   ├── admin/              # 管理后台应用
│   │   │   ├── components/     # 管理后台组件
│   │   │   ├── hooks/          # 管理后台Hooks
│   │   │   ├── layouts/        # 布局组件
│   │   │   ├── pages/          # 页面组件
│   │   │   ├── routes.tsx      # 路由配置
│   │   │   └── index.tsx       # 入口文件
│   │   ├── home/               # 用户前台应用（待开发）
│   │   ├── components/         # 共享UI组件
│   │   │   └── ui/            # shadcn/ui组件库
│   │   ├── hooks/              # 共享Hooks
│   │   ├── lib/                # 工具库
│   │   ├── utils/              # 工具函数
│   │   ├── api.ts              # API客户端
│   │   └── index.tsx           # 前端入口
│   ├── server/                 # Hono后端应用
│   │   ├── api/                # API路由
│   │   ├── modules/            # 业务模块
│   │   ├── middleware/         # 中间件
│   │   └── index.ts            # 服务器入口
│   └── share/                  # 前后端共享代码
│       └── types.ts            # TypeScript类型定义
├── tests/
│   └── e2e/                    # E2E测试 (Playwright)
└── package.json
```

### 集成指南
- **文件命名**: 保持现有kebab-case命名约定
- **文件夹组织**: 遵循功能模块划分，添加__tests__文件夹
- **导入/导出模式**: 使用ES模块，保持现有别名系统（@/）

## 基础设施和部署集成

### 现有基础设施
- **当前部署**: Docker Compose本地开发，Node.js生产部署
- **基础设施工具**: Docker, Docker Compose, Node.js运行时
- **环境**: 开发、生产环境配置

### 增强部署策略
- **部署方法**: 使用现有Docker Compose和Node.js部署流程
- **基础设施变更**: 添加数据库定时备份系统（详见基础设施部署文档）
- **流水线集成**: 集成测试到现有CI/CD流程

### 回滚策略
- **回滚方法**: Docker镜像版本回滚 + 数据库备份恢复
- **数据库恢复**: 使用最新备份文件进行快速恢复
- **风险缓解**: 蓝绿部署或金丝雀发布（可选）
- **监控**: 添加应用健康检查、性能监控和备份状态监控

## 开发工作流

**实际开发命令**:
```bash
# 安装依赖
pnpm install

# 启动完整开发环境（前后端同时运行）
pnpm dev

# 运行测试
pnpm test                      # 运行API测试 (Vitest)
pnpm test:api                  # 运行API测试
pnpm test:components           # 运行组件测试
pnpm test:integration          # 运行集成测试 (同test:components)
pnpm test:e2e                  # 运行E2E测试
pnpm test:e2e:chromium         # 运行Chrome E2E测试
pnpm test:e2e:ui               # 运行E2E测试UI模式
pnpm test:e2e:debug            # 运行E2E调试模式

# 代码质量检查
pnpm lint                      # ESLint检查
pnpm typecheck                 # TypeScript类型检查
pnpm test:coverage             # 生成测试覆盖率报告

# 数据库相关
pnpm db:backup                 # 数据库备份
pnpm db:restore                # 数据库恢复
pnpm db:backup:list            # 列出备份文件
pnpm db:backup:latest          # 获取最新备份
pnpm db:backup:cleanup         # 清理旧备份
pnpm db:migrate                # 数据库迁移
pnpm db:seed                   # 数据库种子数据
pnpm db:reset                  # 重置数据库
```

**环境配置**:
```bash
# 前端环境变量 (Vite)
VITE_API_BASE_URL=http://localhost:8080/api

# 后端环境变量
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres
JWT_SECRET=your-jwt-secret-key
NODE_ENV=development
```

## 编码标准和测试策略

### 现有标准合规性
- **代码风格**: TypeScript严格模式，一致的缩进和命名
- **linting规则**: 需要配置ESLint/Prettier
- **测试模式**: 完整的测试框架已配置（Vitest + Testing Library + Playwright）
- **文档风格**: 代码注释良好，测试策略文档完整

### 增强特定标准
- **测试框架**: 使用Vitest + Testing Library + hono/testing + Playwright
- **测试位置**: 统一在 `tests/` 目录中，按类型分层组织
- **覆盖率目标**: 核心业务逻辑 > 80%
- **测试类型**: 单元测试、集成测试、E2E测试
- **测试策略**: 详见 [测试策略文档](./testing-strategy.md)

### Taro小程序测试策略
- **测试框架**: 使用Jest + @tarojs/test-utils-react (独立于主项目)
- **测试位置**: `mini/tests/` 目录
- **测试范围**: 组件测试、页面测试、应用级测试
- **多端测试**: 支持H5和小程序环境测试
- **详细规范**: 参见 [Taro测试规范文档](../taro-test.md)

### 测试策略

详细的测试策略、标准、执行流程和最佳实践请参考 [测试策略文档](./testing-strategy.md)。

**实际测试结构**:
```text
tests/
├── e2e/                    # E2E测试 (Playwright)
│   ├── fixtures/           # 测试夹具数据
│   │   ├── test-users.json    # 测试用户数据
│   │   ├── roles.json         # 角色数据
│   │   └── test-data.ts       # TypeScript测试数据
│   ├── pages/              # 页面对象模型
│   │   └── admin/          # 管理后台页面对象
│   │       ├── login.page.ts      # 登录页面对象
│   │       ├── dashboard.page.ts  # 仪表板页面对象
│   │       └── user-management.page.ts  # 用户管理页面对象
│   ├── specs/              # 测试规范
│   │   └── admin/          # 管理后台E2E测试
│   │       ├── dashboard.spec.ts    # 仪表板测试
│   │       ├── login.spec.ts        # 登录测试
│   │       ├── settings.spec.ts     # 设置测试
│   │       └── users.spec.ts        # 用户管理测试
│   ├── utils/              # 测试工具
│   │   └── test-setup.ts   # 测试设置工具
│   ├── global-setup.ts     # 全局设置
│   ├── global-teardown.ts  # 全局清理
│   └── playwright.config.ts # Playwright配置
├── integration/            # 集成测试
│   ├── client/             # 前端集成测试
│   │   └── admin/          # 管理后台集成测试
│   │       ├── dashboard.test.tsx  # 仪表板集成测试
│   │       ├── login.test.tsx      # 登录集成测试
│   │       └── users.test.tsx      # 用户管理集成测试
│   └── server/             # 后端集成测试
│       ├── auth.integration.test.ts     # 认证集成测试
│       ├── backup.integration.test.ts   # 备份集成测试
│       ├── files/                       # 文件服务集成测试
│       │   ├── files.integration.test.ts
│       │   └── minio.integration.test.ts
│       └── users.integration.test.ts    # 用户集成测试
├── unit/                   # 单元测试
│   ├── basic.test.ts       # 基础单元测试
│   ├── client/             # 前端单元测试
│   │   └── pages/          # 页面单元测试
│   │       ├── Users.test.tsx      # 用户页面单元测试
│   │       └── debug.test.tsx      # 调试页面单元测试
│   └── server/             # 后端单元测试
│       ├── modules/        # 业务模块单元测试
│       │   └── files/      # 文件服务单元测试
│       │       ├── file.service.test.ts
│       │       └── minio.service.test.ts
│       ├── modules/user.service.test.ts # 用户服务单元测试
│       └── utils/          # 工具单元测试
│           ├── backup.test.ts    # 备份工具测试
│           └── restore.test.ts   # 恢复工具测试
└── utils/                  # 测试工具
    ├── client/             # 前端测试工具
    │   ├── test-query.tsx  # 测试查询工具
    │   ├── test-render.tsx # 测试渲染工具
    │   └── test-router.tsx # 测试路由工具
    ├── server/             # 后端测试工具
    │   ├── integration-test-db.ts    # 集成测试数据库
    │   ├── integration-test-utils.ts # 集成测试工具
    │   ├── service-mocks.ts          # 服务模拟
    │   ├── service-stubs.ts          # 服务桩
    │   ├── test-auth.ts              # 测试认证
    │   └── test-db.ts                # 测试数据库
    └── setup.ts            # 通用测试设置
```

**测试框架配置**:
- **单元测试**: Vitest + Testing Library (前端) / Vitest + hono/testing (后端)
- **集成测试**: Vitest + 自定义测试工具
- **E2E测试**: Playwright
- **测试覆盖率**: 核心业务逻辑 > 80%
- **测试位置**: 统一在 `tests/` 目录中，按类型分层组织

### 关键集成规则
- **现有API兼容性**: 确保测试不破坏现有API契约
- **数据库集成**: 使用测试数据库，避免污染生产数据
- **错误处理**: 测试各种错误场景和边界条件
- **日志一致性**: 测试日志格式和错误信息

## 安全集成

### 现有安全措施
- **认证**: JWT Bearer Token实现完整
- **授权**: 基础角色权限管理
- **数据保护**: 密码使用bcrypt哈希
- **安全工具**: 基本中间件保护

### 增强安全要求
- **新安全措施**: 添加输入验证、速率限制、CSP头
- **集成点**: 中间件层、API网关、数据库层
- **合规要求**: 遵循OWASP Top 10安全最佳实践

### 安全架构详细设计

**前端安全**:
- **CSP头**: `default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'`
- **XSS防护**: 所有用户输入通过Zod schema验证和转义
- **安全存储**: JWT token存储在HTTP Only cookie中
- **HTTPS强制**: 生产环境强制HTTPS连接

**后端安全**:
- **输入验证**: 所有API输入通过Zod schema验证
- **速率限制**: API端点每分钟100请求限制
- **SQL注入防护**: TypeORM参数化查询，禁止原生SQL
- **CORS配置**: 仅允许信任域名跨域访问

**认证授权**:
- **JWT配置**: HS256算法，30分钟过期时间
- **密码策略**: bcrypt哈希，强度12，最小长度8字符
- **角色权限**: 基于角色的访问控制(RBAC)
- **会话管理**: JWT无状态认证，Redis会话缓存

**数据安全**:
- **加密传输**: TLS 1.3加密所有数据传输
- **数据加密**: 敏感数据在数据库层加密存储
- **备份加密**: 数据库备份文件AES-256加密
- **访问审计**: 所有数据访问操作记录审计日志

**基础设施安全**:
- **网络隔离**: 数据库仅允许应用服务器访问
- **防火墙规则**: 仅开放必要端口(3000, 5432, 6379, 9000)
- **最小权限**: 所有服务以非root用户运行
- **安全监控**: 实时监控异常访问和攻击尝试

### 安全测试
- **现有安全测试**: 无自动化安全测试
- **新安全测试要求**: 添加安全扫描、渗透测试计划
- **渗透测试**: 计划季度安全审计

## 检查清单结果报告

### 架构师检查清单执行结果
✅ **技术栈验证**: Node.js + Hono + React + TypeORM 验证通过
✅ **架构模式**: 分层架构、模块化设计验证通过
✅ **代码质量**: 类型安全、错误处理需要增强
✅ **安全性**: 基础安全措施存在，需要加强
✅ **测试覆盖**: 完整的测试基础设施已建立（Vitest + Testing Library + Playwright）
✅ **部署策略**: Docker部署成熟稳定
✅ **备份策略**: 数据库定时备份方案已设计

### 需要立即修复的安全漏洞
1. **密码安全漏洞**: UserService第121行存在明文密码比较风险
2. **错误信息泄露**: 部分错误信息可能包含敏感细节
3. **输入验证缺失**: 需要加强业务规则验证

## 下一步骤

### 故事经理交接
基于此架构文档，开始实现以下故事：
1. 完善用户认证和管理功能（参考现有UserService）
2. 增强通用CRUD服务和API文档（利用现有通用CRUD基础）
3. 重点关注现有系统兼容性和错误处理统一

### 开发者交接
开始实现时注意：
- 保持与现有shadcn设计系统兼容
- 遵循现有的TypeORM实体模式和API路由结构
- 优先修复已识别的安全漏洞（密码比较逻辑）
- 逐步添加测试覆盖，从核心业务逻辑开始

### 关键集成验证点
- 确保新功能不破坏现有API契约
- 验证数据库迁移不会丢失现有数据
- 测试生产环境部署流程仍然正常工作
- 监控性能指标确保无退化

## 监控和可观测性

### 监控策略
**前端监控**:
- **Core Web Vitals**: 监控LCP, FID, CLS等关键性能指标
- **错误跟踪**: 捕获JavaScript运行时错误和API调用失败
- **用户行为**: 跟踪关键用户交互和转化漏斗
- **性能指标**: 页面加载时间，API响应时间监控

**后端监控**:
- **应用性能**: 请求率、错误率、响应时间(p95)
- **数据库性能**: 查询执行时间、连接池使用率
- **基础设施**: CPU、内存、磁盘使用率监控
- **业务指标**: 用户活跃度、API调用统计

### 日志管理
- **结构化日志**: JSON格式日志，包含请求ID、用户ID等上下文
- **日志级别**: DEBUG, INFO, WARN, ERROR分级管理
- **日志聚合**: 集中式日志收集和分析
- **审计日志**: 所有安全敏感操作记录详细审计日志

### 告警策略
- **关键告警**: 应用不可用、数据库连接失败、5xx错误率 > 1%
- **警告告警**: 响应时间 > 500ms, 4xx错误率 > 5%
- **信息告警**: 资源使用率 > 80%, 备份任务完成

## 错误处理策略

### 统一错误格式
```typescript
interface ApiError {
  error: {
    code: string;      // 错误代码，如: 'VALIDATION_ERROR'
    message: string;   // 用户友好的错误信息
    details?: Record<string, any>; // 详细错误信息
    timestamp: string; // ISO时间戳
    requestId: string; // 请求追踪ID
  };
}
```

### 错误分类和处理
- **验证错误**(400): 输入数据验证失败
- **认证错误**(401): 未认证或token过期
- **权限错误**(403): 权限不足
- **资源不存在**(404): 请求的资源不存在
- **服务器错误**(500): 内部服务器错误
- **服务不可用**(503): 维护或过载

### 前端错误处理
- **API错误**: 统一错误处理中间件，用户友好提示
- **网络错误**: 重试机制和离线状态处理
- **组件错误**: React Error Boundary捕获渲染错误
- **用户输入错误**: 实时验证和提示

### 后端错误处理
- **全局错误处理**: 统一错误处理中间件
- **数据库错误**: 连接池管理和重试机制
- **外部服务错误**: 熔断器和降级处理
- **日志记录**: 所有错误记录详细上下文信息

## 附录

### 技术决策依据
- **选择Vitest而不是Jest**: 基于对TypeORM装饰器的更好支持、更快的执行速度和现代化的开发体验
- **保持现有技术栈**: 现有选择（Hono、TypeORM、React）已经验证有效
- **增量增强策略**: 最小化风险，最大化现有投资回报

### 相关文档
- 架构文档: `docs/architecture.md` (本文件)
- 架构详细文档: `docs/architecture/` (包含组件架构、API设计、技术栈等子文档)
- 产品需求文档: `docs/prd.md`
- 测试策略文档: `docs/architecture/testing-strategy.md`
- API文档: 通过 `/ui` 端点访问

### 联系方式
- 架构师: Winston 🏗️
- 最后更新: 2025-09-20

---

**文档状态**: 正式版
**下次评审**: 2025-10-14