|
|
@@ -6,11 +6,15 @@
|
|
|
| 2.0 | 2025-09-14 | 增强架构文档 | Winston |
|
|
|
| 2.1 | 2025-09-19 | 添加数据库定时备份策略 | Winston |
|
|
|
| 2.2 | 2025-09-19 | 更新测试策略文档引用 | Winston |
|
|
|
+| 2.3 | 2025-09-20 | 根据实际项目结构更新测试架构和共享目录 | Winston |
|
|
|
+| 2.4 | 2025-09-20 | 完善BMAD全栈架构规范，添加高层架构图、API规范、安全架构 | Winston |
|
|
|
|
|
|
## 介绍
|
|
|
|
|
|
本文档定义了D8D Starter项目的架构增强方案，基于对现有代码的深度分析。主要目标是将技术实现转化为明确的业务价值主张，同时保持与现有系统的完全兼容。
|
|
|
|
|
|
+**注意**: 本项目的详细架构文档已拆分为多个子文档，位于 `docs/architecture/` 目录中。如需查看完整的架构文档结构，请参阅 [架构文档索引](./architecture/index.md)。
|
|
|
+
|
|
|
### 文档范围
|
|
|
全面定义系统增强的架构方法和集成策略
|
|
|
|
|
|
@@ -21,12 +25,14 @@
|
|
|
| 2025-09-14 | 2.0 | 增强架构文档 | Winston |
|
|
|
| 2025-09-19 | 2.1 | 添加数据库定时备份策略 | Winston |
|
|
|
| 2025-09-19 | 2.2 | 更新测试策略文档引用 | Winston |
|
|
|
+| 2025-09-20 | 2.3 | 根据实际项目结构更新测试架构和共享目录 | Winston |
|
|
|
+| 2025-09-20 | 2.4 | 完善BMAD全栈架构规范，添加高层架构图、API规范、安全架构 | Winston |
|
|
|
|
|
|
## 现有项目分析
|
|
|
|
|
|
### 当前项目状态
|
|
|
- **主要用途**: 现代化的全栈Web应用启动模板，专注于开发者体验
|
|
|
-- **技术栈总结**: Node.js 20.18.3 + Hono 4.8.5 + React 19.1.0 + TypeORM 0.3.25 + PostgreSQL 15
|
|
|
+- **技术栈总结**: Node.js 20.18.3 + Hono 4.8.5 + React 19.1.0 + TypeORM 0.3.25 + PostgreSQL 17
|
|
|
- **架构风格**: 分层架构，前后端分离但统一仓库管理
|
|
|
- **部署方式**: Docker Compose本地开发，Node.js生产部署
|
|
|
|
|
|
@@ -69,6 +75,69 @@
|
|
|
- **UI/UX一致性**: 遵循现有设计模式，保持视觉统一
|
|
|
- **性能影响**: 响应时间保持在100ms以内，无性能退化
|
|
|
|
|
|
+## 高层架构
|
|
|
+
|
|
|
+### 平台和基础设施选择
|
|
|
+**平台**: Docker + Node.js 本地开发部署
|
|
|
+**核心服务**: PostgreSQL 17, Redis 7, MinIO对象存储
|
|
|
+**部署主机**: 多八多云端开发容器环境，开放8080端口外网访问
|
|
|
+**区域**: 本地开发环境，生产环境参数相同
|
|
|
+
|
|
|
+### 架构图
|
|
|
+```mermaid
|
|
|
+graph TD
|
|
|
+ subgraph "前端应用层"
|
|
|
+ A[React 19 管理后台] --> B[React Router v7]
|
|
|
+ A --> C[React Query 状态管理]
|
|
|
+ A --> D[shadcn/ui 组件库]
|
|
|
+ end
|
|
|
+
|
|
|
+ subgraph "API网关层"
|
|
|
+ E[Hono 4.8.5 API路由] --> F[Zod Schema验证]
|
|
|
+ E --> G[JWT认证中间件]
|
|
|
+ E --> H[OpenAPI文档生成]
|
|
|
+ end
|
|
|
+
|
|
|
+ subgraph "业务服务层"
|
|
|
+ I[通用CRUD服务] --> J[TypeORM实体管理]
|
|
|
+ I --> K[数据库备份工具]
|
|
|
+ I --> L[数据库恢复工具]
|
|
|
+ end
|
|
|
+
|
|
|
+ subgraph "数据存储层"
|
|
|
+ M[PostgreSQL 17] --> N[用户数据]
|
|
|
+ M --> O[角色权限数据]
|
|
|
+ P[Redis 7 缓存] --> Q[会话缓存]
|
|
|
+ R[MinIO 对象存储] --> S[文件存储]
|
|
|
+ end
|
|
|
+
|
|
|
+ subgraph "基础设施层"
|
|
|
+ T[Docker Compose] --> U[本地开发环境]
|
|
|
+ V[Node.js 20.18.3] --> W[生产运行时]
|
|
|
+ end
|
|
|
+
|
|
|
+ A --> E
|
|
|
+ E --> I
|
|
|
+ I --> M
|
|
|
+ I --> P
|
|
|
+ E --> R
|
|
|
+ H --> X[Swagger UI /ui]
|
|
|
+
|
|
|
+ style A fill:#e1f5fe
|
|
|
+ style E fill:#f3e5f5
|
|
|
+ style I fill:#fff3e0
|
|
|
+ style M fill:#e8f5e8
|
|
|
+ style P fill:#ffebee
|
|
|
+ style R fill:#f3e5f5
|
|
|
+```
|
|
|
+
|
|
|
+### 架构模式
|
|
|
+- **分层架构**: 清晰的前后端分离，统一的代码仓库管理
|
|
|
+- **组件化UI**: 基于React + shadcn/ui的可复用组件架构
|
|
|
+- **RESTful API**: 遵循OpenAPI规范的统一API设计
|
|
|
+- **通用CRUD模式**: 类型安全的通用数据操作服务
|
|
|
+- **中间件模式**: 统一的认证、验证、错误处理中间件
|
|
|
+
|
|
|
## 技术栈
|
|
|
|
|
|
### 现有技术栈维护
|
|
|
@@ -78,7 +147,7 @@
|
|
|
| 框架 | Hono | 4.8.5 | Web框架和API路由 | RPC类型安全 |
|
|
|
| 前端框架 | React | 19.1.0 | 用户界面构建 | 最新版本 |
|
|
|
| 构建工具 | Vite | 7.0.0 | 开发服务器和构建 | 热重载支持 |
|
|
|
-| 数据库 | PostgreSQL | 15 | 数据持久化存储 | 通过TypeORM |
|
|
|
+| 数据库 | PostgreSQL | 17 | 数据持久化存储 | 通过TypeORM |
|
|
|
| ORM | TypeORM | 0.3.25 | 数据库操作抽象 | 实体管理 |
|
|
|
| 样式 | Tailwind CSS | 4.1.11 | 原子化CSS框架 | 设计一致性 |
|
|
|
| 状态管理 | React Query | 5.83.0 | 服务端状态管理 | 数据同步 |
|
|
|
@@ -120,6 +189,62 @@
|
|
|
|
|
|
**优化重点**: 保持现有数据模型不变，新增文件管理功能，优化查询性能和验证逻辑
|
|
|
|
|
|
+### 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;
|
|
|
+}
|
|
|
+
|
|
|
+// 用户创建DTO
|
|
|
+export interface CreateUserDto {
|
|
|
+ username: string;
|
|
|
+ email?: string;
|
|
|
+ password: string;
|
|
|
+ roleIds?: number[];
|
|
|
+}
|
|
|
+
|
|
|
+// 用户更新DTO
|
|
|
+export interface UpdateUserDto {
|
|
|
+ username?: string;
|
|
|
+ email?: string | null;
|
|
|
+ password?: string;
|
|
|
+ roleIds?: number[];
|
|
|
+}
|
|
|
+
|
|
|
+// 分页响应接口
|
|
|
+export interface PaginatedResponse<T> {
|
|
|
+ data: T[];
|
|
|
+ pagination: {
|
|
|
+ total: number;
|
|
|
+ current: number;
|
|
|
+ pageSize: number;
|
|
|
+ totalPages: number;
|
|
|
+ };
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 数据关系
|
|
|
+- **User ↔ Role**: 多对多关系，通过中间表关联
|
|
|
+- **User → (createdAt, updatedAt)**: 自动时间戳管理
|
|
|
+- **Role → permissions**: 字符串数组存储权限列表
|
|
|
+
|
|
|
### Schema集成策略
|
|
|
- **数据库变更要求**: 新增文件管理表，优化现有表结构
|
|
|
- **新表**: file表（文件管理）
|
|
|
@@ -135,10 +260,101 @@
|
|
|
|
|
|
## 组件架构
|
|
|
|
|
|
-### 现有组件优化
|
|
|
-**通用CRUD服务**:
|
|
|
+### 前端组件架构
|
|
|
+
|
|
|
+**实际项目组件组织**:
|
|
|
+```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 # 用户管理
|
|
|
+│ ├── routes.tsx # 路由配置
|
|
|
+│ └── index.tsx # 管理后台入口
|
|
|
+├── home/ # 用户前台应用
|
|
|
+├── components/ # 共享UI组件
|
|
|
+│ └── ui/ # shadcn/ui组件库（50+组件）
|
|
|
+│ ├── button.tsx # 按钮组件
|
|
|
+│ ├── input.tsx # 输入框组件
|
|
|
+│ ├── table.tsx # 表格组件
|
|
|
+│ └── ... # 其他组件
|
|
|
+├── hooks/ # 共享Hooks
|
|
|
+├── lib/ # 工具库
|
|
|
+├── utils/ # 工具函数
|
|
|
+└── 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/ # 角色管理路由
|
|
|
+│ └── __integration_tests__/ # 集成测试
|
|
|
+├── modules/ # 业务模块层
|
|
|
+│ ├── auth/ # 认证业务模块
|
|
|
+│ │ ├── auth.service.ts # 认证服务
|
|
|
+│ │ └── __tests__/ # 认证测试
|
|
|
+│ ├── users/ # 用户业务模块
|
|
|
+│ │ ├── user.entity.ts # 用户实体
|
|
|
+│ │ ├── user.service.ts # 用户服务
|
|
|
+│ │ └── __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`
|
|
|
- **优化重点**: 增强错误处理、添加测试覆盖、优化性能
|
|
|
|
|
|
**文件管理服务**:
|
|
|
@@ -146,9 +362,10 @@
|
|
|
- **现状**: 已实现完整功能，支持分段上传、预签名URL生成
|
|
|
- **优化重点**: 增强大文件处理能力，优化上传性能
|
|
|
|
|
|
-**API文档组件**:
|
|
|
+### API文档组件
|
|
|
- **责任**: 自动生成和维护OpenAPI文档
|
|
|
- **现状**: 通过@hono/zod-openapi集成，提供Swagger UI
|
|
|
+- **访问路径**: `/ui` 端点
|
|
|
- **优化重点**: 完善文档示例、确保文档与代码同步
|
|
|
|
|
|
### 组件交互
|
|
|
@@ -179,6 +396,90 @@ graph TD
|
|
|
- **认证**: 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: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
|
|
|
@@ -223,69 +524,36 @@ graph TD
|
|
|
|
|
|
## 源码树和文件组织
|
|
|
|
|
|
-### 现有项目结构
|
|
|
-```text
|
|
|
-d8d-starter/
|
|
|
-├── src/
|
|
|
-│ ├── client/ # React前端代码
|
|
|
-│ │ ├── admin/ # 管理后台界面
|
|
|
-│ │ ├── home/ # 用户主页界面
|
|
|
-│ │ ├── components/ # 共享组件
|
|
|
-│ │ ├── hooks/ # React Hooks
|
|
|
-│ │ └── lib/ # 工具库
|
|
|
-│ ├── server/ # Node.js后端代码
|
|
|
-│ │ ├── api/ # API路由处理
|
|
|
-│ │ │ ├── auth/ # 认证路由
|
|
|
-│ │ │ ├── users/ # 用户管理路由
|
|
|
-│ │ │ └── roles/ # 角色管理路由
|
|
|
-│ │ ├── modules/ # 业务模块
|
|
|
-│ │ ├── middleware/ # 中间件
|
|
|
-│ │ ├── types/ # TypeScript类型
|
|
|
-│ │ └── utils/ # 工具函数
|
|
|
-│ └── share/ # 前后端共享代码
|
|
|
-```
|
|
|
-
|
|
|
-### 新文件组织
|
|
|
+### 实际项目结构
|
|
|
```text
|
|
|
d8d-starter/
|
|
|
├── src/
|
|
|
-│ ├── client/ # 现有结构保持不变
|
|
|
-│ │ └── utils/
|
|
|
-│ │ └── minio.ts # 新增：MinIO前端上传工具
|
|
|
-│ ├── server/
|
|
|
-│ │ ├── api/
|
|
|
-│ │ │ ├── users/
|
|
|
-│ │ │ │ ├── __tests__/ # 新增：API测试
|
|
|
-│ │ │ │ ├── [id]/
|
|
|
-│ │ │ │ ├── get.ts
|
|
|
-│ │ │ │ └── index.ts
|
|
|
-│ │ │ ├── files/ # 新增：文件管理API
|
|
|
-│ │ │ │ ├── upload-policy/
|
|
|
-│ │ │ │ │ └── post.ts # 文件上传策略生成
|
|
|
-│ │ │ │ ├── multipart-policy/
|
|
|
-│ │ │ │ │ └── post.ts # 分段上传策略生成
|
|
|
-│ │ │ │ ├── multipart-complete/
|
|
|
-│ │ │ │ │ └── post.ts # 分段上传完成
|
|
|
-│ │ │ │ ├── [id]/
|
|
|
-│ │ │ │ │ ├── download.ts # 文件下载
|
|
|
-│ │ │ │ │ └── get-url.ts # 获取文件URL
|
|
|
-│ │ ├── modules/
|
|
|
-│ │ │ ├── users/
|
|
|
-│ │ │ │ ├── __tests__/ # 新增：服务测试
|
|
|
-│ │ │ │ ├── user.entity.ts
|
|
|
-│ │ │ │ ├── user.service.ts
|
|
|
-│ │ │ │ └── role.entity.ts
|
|
|
-│ │ │ ├── files/ # 新增：文件管理模块
|
|
|
-│ │ │ │ ├── file.entity.ts # 文件实体
|
|
|
-│ │ │ │ ├── file.service.ts # 文件服务
|
|
|
-│ │ │ │ ├── minio.service.ts # MinIO服务
|
|
|
-│ │ │ │ └── file.schema.ts # 文件Schema定义
|
|
|
-│ │ └── utils/
|
|
|
-│ │ ├── __tests__/ # 新增：工具测试
|
|
|
-│ │ ├── generic-crud.service.ts
|
|
|
-│ │ ├── generic-crud.routes.ts
|
|
|
-│ │ └── errorHandler.ts # 需要增强的错误处理
|
|
|
-│ └── share/ # 现有结构保持不变
|
|
|
+│ ├── 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
|
|
|
```
|
|
|
|
|
|
### 集成指南
|
|
|
@@ -311,6 +579,53 @@ d8d-starter/
|
|
|
- **风险缓解**: 蓝绿部署或金丝雀发布（可选）
|
|
|
- **监控**: 添加应用健康检查、性能监控和备份状态监控
|
|
|
|
|
|
+## 开发工作流
|
|
|
+
|
|
|
+**实际开发命令**:
|
|
|
+```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:3000/api
|
|
|
+
|
|
|
+# 后端环境变量
|
|
|
+DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres
|
|
|
+JWT_SECRET=your-jwt-secret-key
|
|
|
+NODE_ENV=development
|
|
|
+```
|
|
|
+
|
|
|
## 编码标准和测试策略
|
|
|
|
|
|
### 现有标准合规性
|
|
|
@@ -326,6 +641,78 @@ d8d-starter/
|
|
|
- **测试类型**: 单元测试、集成测试、E2E测试
|
|
|
- **测试策略**: 详见 [测试策略文档](./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配置
|
|
|
+```
|
|
|
+
|
|
|
+**前端测试位置**:
|
|
|
+```text
|
|
|
+src/client/
|
|
|
+├── __integration_tests__/ # 前端集成测试
|
|
|
+│ └── admin/ # 管理后台集成测试
|
|
|
+│ ├── dashboard.test.tsx # 仪表板集成测试
|
|
|
+│ ├── login.test.tsx # 登录集成测试
|
|
|
+│ └── users.test.tsx # 用户管理集成测试
|
|
|
+└── admin/
|
|
|
+ └── pages/
|
|
|
+ └── __tests__/ # 页面单元测试
|
|
|
+ ├── Users.test.tsx # 用户页面单元测试
|
|
|
+ └── debug.test.tsx # 调试页面单元测试
|
|
|
+```
|
|
|
+
|
|
|
+**后端测试位置**:
|
|
|
+```text
|
|
|
+src/server/
|
|
|
+├── api/
|
|
|
+│ ├── auth/ # 认证API
|
|
|
+│ │ └── __tests__/ # 认证测试
|
|
|
+│ │ └── auth.integration.test.ts # 认证集成测试
|
|
|
+│ └── users/ # 用户API
|
|
|
+│ └── __tests__/ # 用户测试
|
|
|
+│ └── users.integration.test.ts # 用户集成测试
|
|
|
+├── modules/
|
|
|
+│ └── users/ # 用户业务模块
|
|
|
+│ └── __tests__/ # 用户服务测试
|
|
|
+│ └── user.service.test.ts # 用户服务单元测试
|
|
|
+└── utils/
|
|
|
+ ├── __tests__/ # 工具单元测试
|
|
|
+ │ ├── backup.test.ts # 备份工具测试
|
|
|
+ │ └── restore.test.ts # 恢复工具测试
|
|
|
+ └── __integration_tests__/ # 工具集成测试
|
|
|
+ └── backup.integration.test.ts # 备份集成测试
|
|
|
+```
|
|
|
+
|
|
|
+**测试框架配置**:
|
|
|
+- **单元测试**: Vitest + Testing Library (前端) / Vitest + hono/testing (后端)
|
|
|
+- **集成测试**: Vitest + 自定义测试工具
|
|
|
+- **E2E测试**: Playwright
|
|
|
+- **测试覆盖率**: 核心业务逻辑 > 80%
|
|
|
+- **测试位置**: `__tests__` 文件夹与源码并列
|
|
|
+
|
|
|
### 关键集成规则
|
|
|
- **现有API兼容性**: 确保测试不破坏现有API契约
|
|
|
- **数据库集成**: 使用测试数据库，避免污染生产数据
|
|
|
@@ -345,6 +732,38 @@ d8d-starter/
|
|
|
- **集成点**: 中间件层、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用户运行
|
|
|
+- **安全监控**: 实时监控异常访问和攻击尝试
|
|
|
+
|
|
|
### 安全测试
|
|
|
- **现有安全测试**: 无自动化安全测试
|
|
|
- **新安全测试要求**: 添加安全扫描、渗透测试计划
|
|
|
@@ -387,6 +806,67 @@ d8d-starter/
|
|
|
- 测试生产环境部署流程仍然正常工作
|
|
|
- 监控性能指标确保无退化
|
|
|
|
|
|
+## 监控和可观测性
|
|
|
+
|
|
|
+### 监控策略
|
|
|
+**前端监控**:
|
|
|
+- **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捕获渲染错误
|
|
|
+- **用户输入错误**: 实时验证和提示
|
|
|
+
|
|
|
+### 后端错误处理
|
|
|
+- **全局错误处理**: 统一错误处理中间件
|
|
|
+- **数据库错误**: 连接池管理和重试机制
|
|
|
+- **外部服务错误**: 熔断器和降级处理
|
|
|
+- **日志记录**: 所有错误记录详细上下文信息
|
|
|
+
|
|
|
## 附录
|
|
|
|
|
|
### 技术决策依据
|
|
|
@@ -395,14 +875,15 @@ d8d-starter/
|
|
|
- **增量增强策略**: 最小化风险，最大化现有投资回报
|
|
|
|
|
|
### 相关文档
|
|
|
-- 现有架构文档: `docs/brownfield-architecture.md`
|
|
|
+- 架构文档: `docs/architecture.md` (本文件)
|
|
|
+- 架构详细文档: `docs/architecture/` (包含组件架构、API设计、技术栈等子文档)
|
|
|
- 产品需求文档: `docs/prd.md`
|
|
|
- 测试策略文档: `docs/architecture/testing-strategy.md`
|
|
|
- API文档: 通过 `/ui` 端点访问
|
|
|
|
|
|
### 联系方式
|
|
|
- 架构师: Winston 🏗️
|
|
|
-- 最后更新: 2025-09-19
|
|
|
+- 最后更新: 2025-09-20
|
|
|
|
|
|
---
|
|
|
|
yourname