D8D Starter 遗留系统增强架构

版本信息

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

文档范围

全面定义系统增强的架构方法和集成策略

变更日志

日期	版本	描述	作者
2024-09-14	1.0	初始现有系统分析	Winston
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 17
架构风格: 分层架构，前后端分离但统一仓库管理
部署方式: Docker Compose本地开发，Node.js生产部署

可用文档分析

✅ 技术文档完整:

技术栈和版本信息准确
源码结构和模块组织清晰
数据模型定义完整
API规范通过OpenAPI自动生成

⚠️ 需要补充:

完整的业务需求文档
测试策略和覆盖率
性能优化指南
安全最佳实践

识别出的约束

必须保持与现有shadcn设计系统的兼容性
需要支持PostgreSQL关系型数据库
前端构建基于Vite，后端基于Hono
部署环境支持Docker容器化
现有代码中存在一些any类型需要修复

增强范围和集成策略

增强概述

增强类型: 现有项目功能完善和业务需求文档化
范围: 将技术实现转化为明确的业务价值主张
集成影响级别: 中等 - 主要添加文档和优化，不改变核心架构

集成方法

代码集成策略: 增量改进，保持向后兼容
数据库集成: 无模式变更，仅优化查询和索引
API集成: 保持现有API不变，增强文档和错误处理
UI集成: 保持现有shadcn设计系统，优化用户体验

兼容性要求

现有API兼容性: 100%保持，不破坏现有客户端
数据库Schema兼容性: 无变更，确保数据完整性
UI/UX一致性: 遵循现有设计模式，保持视觉统一
性能影响: 响应时间保持在100ms以内，无性能退化

高层架构

平台和基础设施选择

平台: Docker + Node.js 本地开发部署 核心服务: PostgreSQL 17, Redis 7, MinIO对象存储 部署主机: 多八多云端开发容器环境，开放8080端口外网访问区域: 本地开发环境，生产环境参数相同

架构图

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模式: 类型安全的通用数据操作服务
中间件模式: 统一的认证、验证、错误处理中间件

技术栈

现有技术栈维护

类别	当前技术	版本	在增强中的用途	备注
运行时	Node.js	20.18.3	服务器运行时环境	ES模块支持
框架	Hono	4.8.5	Web框架和API路由	RPC类型安全
前端框架	React	19.1.0	用户界面构建	最新版本
构建工具	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服务的完整交互能力	后端服务集成

数据模型和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实体建立多对一关系映射

优化重点: 保持现有数据模型不变，新增文件管理功能，优化查询性能和验证逻辑

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 File {
  id: number;
  name: string;
  type: string | null;
  size: number | null;
  path: string;
  description: string | null;
  uploadUserId: number;
  uploadUser: User;
  uploadTime: Date;
  lastUpdated: Date | null;
  createdAt: Date;
  updatedAt: Date;
  fullUrl: Promise<string>; // 异步获取预签名URL
}

// 文件创建DTO
export interface CreateFileDto {
  name: string;
  type?: string;
  size?: number;
  description?: string;
  uploadUserId: number;
}

// 多部分上传策略响应
export interface MultipartUploadPolicy {
  uploadId: string;
  bucket: string;
  key: string;
  host: string;
  partUrls: string[];
}

// 上传策略响应
export interface UploadPolicy {
  uploadPolicy: {
    'x-amz-algorithm': string;
    'x-amz-credential': string;
    'x-amz-date': string;
    'x-amz-security-token'?: string;
    policy: string;
    'x-amz-signature': string;
    host: string;
    key: string;
    bucket: string;
  };
}

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

数据关系

User ↔ Role: 多对多关系，通过中间表关联
User → (createdAt, updatedAt): 自动时间戳管理
Role → permissions: 字符串数组存储权限列表

Schema集成策略

数据库变更要求: 新增文件管理表，优化现有表结构
新表: file表（文件管理）
修改的表: 无结构性变更
新索引: 为文件查询字段添加索引（name, uploadUserId, uploadTime）
迁移策略: 使用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
优化重点: 增强错误处理、添加测试覆盖、优化性能

文件管理服务:

责任: 提供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测试
测试策略: 详见测试策略文档

测试策略

实际测试结构:

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配置

前端测试位置:

src/client/
├── __integration_tests__/      # 前端集成测试
│   └── admin/                  # 管理后台集成测试
│       ├── dashboard.test.tsx  # 仪表板集成测试
│       ├── login.test.tsx      # 登录集成测试
│       └── users.test.tsx      # 用户管理集成测试
└── admin/
    └── pages/
        └── __tests__/          # 页面单元测试
            ├── Users.test.tsx  # 用户页面单元测试
            └── debug.test.tsx  # 调试页面单元测试

后端测试位置:

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契约
数据库集成: 使用测试数据库，避免污染生产数据
错误处理: 测试各种错误场景和边界条件
日志一致性: 测试日志格式和错误信息

安全集成

现有安全措施

认证: 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部署成熟稳定 ✅ 备份策略: 数据库定时备份方案已设计

需要立即修复的安全漏洞

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

下一步骤

故事经理交接

基于此架构文档，开始实现以下故事：

完善用户认证和管理功能（参考现有UserService）
增强通用CRUD服务和API文档（利用现有通用CRUD基础）
重点关注现有系统兼容性和错误处理统一

开发者交接

开始实现时注意：

保持与现有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）已经验证有效
增量增强策略: 最小化风险，最大化现有投资回报

联系方式

架构师: Winston 🏗️
最后更新: 2025-09-20

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

architecture.md 33 KB Lien permanent Historique Raw