# 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/` 目录中。如需查看完整的架构文档结构，请参阅 [架构文档索引](./architecture/index.md)。

### 文档范围
全面定义系统增强的架构方法和集成策略

### 变更日志
| 日期 | 版本 | 描述 | 作者 |
|------|------|------|------|
| 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端口外网访问
**区域**: 本地开发环境，生产环境参数相同

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

## 技术栈

### 现有技术栈维护
| 类别 | 当前技术 | 版本 | 在增强中的用途 | 备注 |
|------|----------|------|----------------|------|
| 运行时 | 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接口定义
```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端点不变
- 确保现有数据查询继续正常工作
- 不修改任何现有字段定义
- 新增功能通过可选字段或新端点实现

## 组件架构

### 前端组件架构

**实际项目组件组织**:
```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`
- **优化重点**: 增强错误处理、添加测试覆盖、优化性能

**文件管理服务**:
- **责任**: 提供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: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服务，支持分段上传和大文件处理

**请求示例**:
```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: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测试
- **测试策略**: 详见 [测试策略文档](./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契约
- **数据库集成**: 使用测试数据库，避免污染生产数据
- **错误处理**: 测试各种错误场景和边界条件
- **日志一致性**: 测试日志格式和错误信息

## 安全集成

### 现有安全措施
- **认证**: 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