# 出行服务项目架构文档 ## 版本信息 | 版本 | 日期 | 描述 | 作者 | |------|------|------|------| | 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 { 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; // 详细错误信息 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