mini-starter/docs/architecture.md

出行服务项目架构文档

版本信息

版本	日期	描述	作者
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/ 目录中。如需查看完整的架构文档结构，请参阅 架构文档索引。

新增Taro小程序和Tailwind规范

基于mini项目迁移需求，新增以下规范文档：

• Taro小程序开发规范 - Taro小程序开发最佳实践
• Tailwind CSS样式规范 - Tailwind CSS使用规范
• mini-demo迁移指导规范 - 从原生小程序迁移到Taro的详细指导（包含精确样式迁移）
• 管理后台开发规范 - 管理后台开发标准和最佳实践

文档范围

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

变更日志

日期	版本	描述	作者
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端口外网访问 区域: 本地开发环境，生产环境参数相同 目标平台: 微信小程序为主要发布平台

架构图

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接口定义

// 用户实体接口
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端点不变
• 确保现有数据查询继续正常工作
• 不修改任何现有字段定义
• 新增功能通过可选字段或新端点实现

组件架构

前端组件架构

实际项目组件组织:

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适配器

后端组件架构

实际后端项目结构:

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规范

文件管理服务:

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

API文档组件

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

组件交互

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规范

openapi: 3.0.0
info:
  title: D8D Starter API
  version: 1.0.0
  description: D8D Starter项目RESTful API文档
servers:
  - url: http://localhost:3000/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服务，支持分段上传和大文件处理

请求示例:

{
  "page": 1,
  "pageSize": 10,
  "keyword": "搜索词",
  "sortBy": "createdAt",
  "sortOrder": "DESC"
}

响应示例:

{
  "data": [
    {
      "id": 1,
      "email": "user@example.com",
      "roles": [{"id": 1, "name": "admin"}]
    }
  ],
  "pagination": {
    "total": 100,
    "current": 1,
    "pageSize": 10
  }
}

源码树和文件组织

实际项目结构

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镜像版本回滚 + 数据库备份恢复
• 数据库恢复: 使用最新备份文件进行快速恢复
• 风险缓解: 蓝绿部署或金丝雀发布（可选）
• 监控: 添加应用健康检查、性能监控和备份状态监控

开发工作流

实际开发命令:

# 安装依赖
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                  # 重置数据库

环境配置:

# 前端环境变量 (Vite)
VITE_API_BASE_URL=http://localhost:3000/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测试
• 测试策略: 详见 测试策略文档

Taro小程序测试策略

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

测试策略

详细的测试策略、标准、执行流程和最佳实践请参考 测试策略文档。

实际测试结构:

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%, 备份任务完成

错误处理策略

统一错误格式

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