Merge remote-tracking branch 'upstream/bmad-method' into bmad-method

.claude/settings.local.json

@@ -26,7 +26,9 @@
       "Bash(npx playwright codegen:*)",
       "Bash(pnpm run)",
       "Bash(node:*)",
-      "Bash(pnpm run db:backup:latest:*)"
+      "Bash(pnpm run db:backup:latest:*)",
+      "Bash(done)",
+      "Bash(do sed -i '8d' \"$file\")"
     ],
     "deny": [],
     "ask": []

CLAUDE.md

@@ -1,7 +1,7 @@
 ### 开发环境说明
 - 多八多云端开发容器环境
 - Node.js 20.19.2
-- PostgresSQL 15(默认数据库: postgres) 
+- PostgresSQL 17 (默认数据库: postgres) 
 - Redis 7
 - MinIO(默认存储桶: d8dai)
 - 所有服务使用默认参数连接，正式环境参数相同

docs/architecture.md

@@ -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
 
 ---
 

docs/architecture/api-design-integration.md

@@ -1,10 +1,99 @@
 # API设计和集成
 
+## 版本信息
+| 版本 | 日期 | 描述 | 作者 |
+|------|------|------|------|
+| 2.4 | 2025-09-20 | 与主架构文档版本一致 | Winston |
+
 ## 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

docs/architecture/appendix.md

@@ -1,20 +1,29 @@
 # 附录
 
+## 版本信息
+| 版本 | 日期 | 描述 | 作者 |
+|------|------|------|------|
+| 2.4 | 2025-09-20 | 与主架构文档版本一致 | Winston |
+
 ## 技术决策依据
 - **选择Vitest而不是Jest**: 基于对TypeORM装饰器的更好支持、更快的执行速度和现代化的开发体验
 - **保持现有技术栈**: 现有选择（Hono、TypeORM、React）已经验证有效
 - **增量增强策略**: 最小化风险，最大化现有投资回报
 
 ## 相关文档
-- 现有架构文档: `docs/brownfield-architecture.md`
+- 架构文档: `docs/architecture.md`
+- 架构详细文档: `docs/architecture/` (包含组件架构、API设计、技术栈、安全架构、监控策略等子文档)
 - 产品需求文档: `docs/prd.md`
+- 测试策略文档: `docs/architecture/testing-strategy.md`
 - API文档: 通过 `/ui` 端点访问
+- 开发工作流: `docs/architecture/development-workflow.md`
+- 编码标准: `docs/architecture/coding-standards.md`
 
 ## 联系方式
 - 架构师: Winston 🏗️
-- 最后更新: 2025-09-14
+- 最后更新: 2025-09-20
 
 ---
 
 **文档状态**: 正式版
-**下次评审**: 2025-10-14
+**下次评审**: 2025-12-20

docs/architecture/checklist-results.md

@@ -1,11 +1,16 @@
 # 检查清单结果报告
 
+## 版本信息
+| 版本 | 日期 | 描述 | 作者 |
+|------|------|------|------|
+| 2.4 | 2025-09-20 | 与主架构文档版本一致 | Winston |
+
 ## 架构师检查清单执行结果
 ✅ **技术栈验证**: Node.js + Hono + React + TypeORM 验证通过
 ✅ **架构模式**: 分层架构、模块化设计验证通过
 ✅ **代码质量**: 类型安全、错误处理需要增强
 ✅ **安全性**: 基础安全措施存在，需要加强
-✅ **测试覆盖**: 需要添加完整测试基础设施
+✅ **测试覆盖**: 完整的测试基础设施已建立（Vitest + Testing Library + Playwright），包含单元测试、集成测试、E2E测试
 ✅ **部署策略**: Docker部署成熟稳定
 ✅ **备份策略**: 数据库定时备份方案已设计
 

docs/architecture/coding-standards.md

@@ -1,13 +1,18 @@
 # 编码标准和测试策略
 
+## 版本信息
+| 版本 | 日期 | 描述 | 作者 |
+|------|------|------|------|
+| 2.4 | 2025-09-20 | 与主架构文档版本一致 | Winston |
+
 ## 现有标准合规性
 - **代码风格**: TypeScript严格模式，一致的缩进和命名
-- **linting规则**: 需要配置ESLint/Prettier
-- **测试模式**: 无现有测试框架配置
-- **文档风格**: 代码注释良好，但缺少完整文档
+- **linting规则**: 已配置ESLint，支持TypeScript和React
+- **测试模式**: 完整的测试框架已配置（Vitest + Testing Library + Playwright）
+- **文档风格**: 代码注释良好，测试策略文档完整
 
 ## 增强特定标准
-- **测试框架**: 添加Vitest + Testing Library + hono/testing
+- **测试框架**: 使用Vitest + Testing Library + hono/testing + Playwright
 - **测试位置**: `__tests__` 文件夹与源码并列
 - **覆盖率目标**: 核心业务逻辑 > 80%
 - **测试类型**: 单元测试、集成测试、E2E测试

docs/architecture/component-architecture.md

@@ -1,5 +1,100 @@
 # 组件架构
 
+## 版本信息
+| 版本 | 日期 | 描述 | 作者 |
+|------|------|------|------|
+| 2.4 | 2025-09-20 | 与主架构文档版本一致 | Winston |
+
+### 前端组件架构
+
+**实际项目组件组织**:
+```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.ts           # 认证中间件
+│   └── validation.ts     # 验证中间件
+├── types/                # 类型定义
+├── data-source.ts        # 数据库连接配置
+└── index.ts              # 服务器入口
+```
+
+**后端技术栈配置**:
+- **框架**: Hono 4.8.5 + TypeScript
+- **数据库**: PostgreSQL 15 + TypeORM 0.3.25
+- **验证**: Zod schema验证
+- **认证**: JWT Bearer Token
+- **API文档**: @hono/zod-openapi + Swagger UI
+- **测试**: Vitest + hono/testing
+
 ## 现有组件优化
 **通用CRUD服务**:
 - **责任**: 提供类型安全的通用CRUD操作，支持自定义扩展

docs/architecture/data-model-schema-changes.md

@@ -1,5 +1,10 @@
 # 数据模型和Schema变更
 
+## 版本信息
+| 版本 | 日期 | 描述 | 作者 |
+|------|------|------|------|
+| 2.4 | 2025-09-20 | 与主架构文档版本一致 | Winston |
+
 ## 现有数据模型状态
 **用户模型**:
 - **现状**: 设计良好，包含完整的用户管理和权限系统
@@ -28,6 +33,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表（文件管理）

docs/architecture/development-workflow.md

@@ -0,0 +1,51 @@
+# 开发工作流
+
+## 版本信息
+| 版本 | 日期 | 描述 | 作者 |
+|------|------|------|------|
+| 2.4 | 2025-09-20 | 与主架构文档版本一致 | Winston |
+
+## 实际开发命令
+```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
+```

docs/architecture/enhancement-scope-integration.md

@@ -1,5 +1,10 @@
 # 增强范围和集成策略
 
+## 版本信息
+| 版本 | 日期 | 描述 | 作者 |
+|------|------|------|------|
+| 2.4 | 2025-09-20 | 与主架构文档版本一致 | Winston |
+
 ## 增强概述
 - **增强类型**: 现有项目功能完善和业务需求文档化
 - **范围**: 将技术实现转化为明确的业务价值主张

docs/architecture/existing-project-analysis.md

@@ -1,5 +1,10 @@
 # 现有项目分析
 
+## 版本信息
+| 版本 | 日期 | 描述 | 作者 |
+|------|------|------|------|
+| 2.4 | 2025-09-20 | 与主架构文档版本一致 | Winston |
+
 ## 当前项目状态
 - **主要用途**: 现代化的全栈Web应用启动模板，专注于开发者体验
 - **技术栈总结**: Node.js 20.18.3 + Hono 4.8.5 + React 19.1.0 + TypeORM 0.3.25 + PostgreSQL 15

docs/architecture/index.md

@@ -36,6 +36,9 @@
     - [现有基础设施](./infrastructure-deployment.md#现有基础设施)
     - [增强部署策略](./infrastructure-deployment.md#增强部署策略)
     - [回滚策略](./infrastructure-deployment.md#回滚策略)
+  - [开发工作流](./development-workflow.md)
+    - [实际开发命令](./development-workflow.md#实际开发命令)
+    - [环境配置](./development-workflow.md#环境配置)
   - [编码标准和测试策略](./coding-standards.md)
     - [现有标准合规性](./coding-standards.md#现有标准合规性)
     - [增强特定标准](./coding-standards.md#增强特定标准)
@@ -43,7 +46,13 @@
   - [安全集成](./security-integration.md)
     - [现有安全措施](./security-integration.md#现有安全措施)
     - [增强安全要求](./security-integration.md#增强安全要求)
+    - [安全架构详细设计](./security-integration.md#安全架构详细设计)
     - [安全测试](./security-integration.md#安全测试)
+  - [运营和监控](./operations-monitoring.md)
+    - [监控策略](./operations-monitoring.md#监控策略)
+    - [日志管理](./operations-monitoring.md#日志管理)
+    - [告警策略](./operations-monitoring.md#告警策略)
+    - [错误处理策略](./operations-monitoring.md#错误处理策略)
   - [检查清单结果报告](./checklist-results.md)
     - [架构师检查清单执行结果](./checklist-results.md#架构师检查清单执行结果)
     - [需要立即修复的安全漏洞](./checklist-results.md#需要立即修复的安全漏洞)

docs/architecture/infrastructure-deployment.md

@@ -1,5 +1,10 @@
 # 基础设施和部署集成
 
+## 版本信息
+| 版本 | 日期 | 描述 | 作者 |
+|------|------|------|------|
+| 2.4 | 2025-09-20 | 与主架构文档版本一致 | Winston |
+
 ## 现有基础设施
 - **当前部署**: Docker Compose本地开发，Node.js生产部署
 - **基础设施工具**: Docker, Docker Compose, Node.js运行时

docs/architecture/introduction.md

@@ -2,6 +2,8 @@
 
 本文档定义了D8D Starter项目的架构增强方案，基于对现有代码的深度分析。主要目标是将技术实现转化为明确的业务价值主张，同时保持与现有系统的完全兼容。
 
+**注意**: 本项目的详细架构文档已拆分为多个子文档，位于 `docs/architecture/` 目录中。如需查看完整的架构文档结构，请参阅 [架构文档索引](./index.md)。
+
 ## 文档范围
 全面定义系统增强的架构方法和集成策略
 
@@ -10,3 +12,7 @@
 |------|------|------|------|
 | 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 |

docs/architecture/next-steps.md

@@ -1,5 +1,10 @@
 # 下一步骤
 
+## 版本信息
+| 版本 | 日期 | 描述 | 作者 |
+|------|------|------|------|
+| 2.4 | 2025-09-20 | 与主架构文档版本一致 | Winston |
+
 ## 故事经理交接
 基于此架构文档，开始实现以下故事：
 1. 完善用户认证和管理功能（参考现有UserService）

docs/architecture/operations-monitoring.md

@@ -0,0 +1,78 @@
+# 运营和监控
+
+## 版本信息
+| 版本 | 日期 | 描述 | 作者 |
+|------|------|------|------|
+| 2.4 | 2025-09-20 | 与主架构文档版本一致 | Winston |
+
+## 监控策略
+
+**前端监控**:
+- **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捕获渲染错误
+- **用户输入错误**: 实时验证和提示
+
+### 后端错误处理
+- **全局错误处理**: 统一错误处理中间件
+- **数据库错误**: 连接池管理和重试机制
+- **外部服务错误**: 熔断器和降级处理
+- **日志记录**: 所有错误记录详细上下文信息
+
+### 性能监控指标
+- **应用性能指标**: 请求响应时间(p50, p95, p99)、错误率、吞吐量
+- **数据库性能**: 查询执行时间、连接池使用率、锁等待时间
+- **缓存性能**: Redis命中率、内存使用率、响应时间
+- **基础设施**: CPU使用率、内存使用率、磁盘IO、网络带宽
+
+### 业务监控指标
+- **用户活跃度**: 日活用户(DAU)、月活用户(MAU)、用户留存率
+- **API使用统计**: 各端点调用频率、成功率、平均响应时间
+- **功能使用**: 关键功能使用率、用户行为漏斗分析
+- **业务健康度**: 订单成功率、支付成功率、用户满意度

docs/architecture/security-integration.md

@@ -1,5 +1,10 @@
 # 安全集成
 
+## 版本信息
+| 版本 | 日期 | 描述 | 作者 |
+|------|------|------|------|
+| 2.4 | 2025-09-20 | 与主架构文档版本一致 | Winston |
+
 ## 现有安全措施
 - **认证**: JWT Bearer Token实现完整
 - **授权**: 基础角色权限管理
@@ -11,7 +16,45 @@
 - **集成点**: 中间件层、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用户运行
+- **安全监控**: 实时监控异常访问和攻击尝试
+
 ## 安全测试
-- **现有安全测试**: 无自动化安全测试
-- **新安全测试要求**: 添加安全扫描、渗透测试计划
-- **渗透测试**: 计划季度安全审计
+- **现有安全测试**: 已集成安全测试到测试策略中
+- **安全测试要求**: 包括输入验证测试、认证测试、数据保护测试
+- **渗透测试**: 计划季度安全审计，使用OWASP ZAP等工具
+
+### 安全监控和响应
+- **实时监控**: 监控异常登录尝试、API滥用、数据泄露迹象
+- **安全事件响应**: 建立安全事件响应流程，30分钟内响应关键安全事件
+- **漏洞管理**: 定期安全扫描，关键漏洞24小时内修复
+- **合规审计**: 季度安全合规审计，确保符合行业安全标准

docs/architecture/source-tree.md

@@ -1,71 +1,88 @@
 # 源码树和文件组织
 
-## 现有项目结构
-```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/            # 前后端共享代码
-```
+## 版本信息
+| 版本 | 日期 | 描述 | 作者 |
+|------|------|------|------|
+| 2.4 | 2025-09-20 | 与主架构文档版本一致 | Winston |
 
-## 新文件组织
+## 实际项目结构
 ```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/     # 管理后台专用组件
+│   │   │   │   ├── 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客户端配置
+│   │   └── index.tsx          # 前端入口
+│   ├── server/                 # Hono后端应用
+│   │   ├── 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           # 服务器入口
+│   └── share/                  # 前后端共享代码
+│       └── types.ts           # TypeScript类型定义
+├── tests/
+│   └── e2e/                    # E2E测试 (Playwright)
+└── package.json
 ```
 
 ## 集成指南
 - **文件命名**: 保持现有kebab-case命名约定
 - **文件夹组织**: 遵循功能模块划分，添加__tests__文件夹
+- **测试结构**: 单元测试位于`__tests__/`目录，集成测试位于`__integration_tests__/`目录
 - **导入/导出模式**: 使用ES模块，保持现有别名系统（@/）
+- **测试位置**: 前端集成测试位于`__integration_tests__/`，页面单元测试位于`__tests__/`
+- **后端测试**: API测试位于路由`__tests__/`目录，服务测试位于模块`__tests__/`目录
+- **工具测试**: 通用工具测试位于`utils/__tests__/`目录

docs/architecture/tech-stack.md

@@ -1,5 +1,10 @@
 # 技术栈
 
+## 版本信息
+| 版本 | 日期 | 描述 | 作者 |
+|------|------|------|------|
+| 2.4 | 2025-09-20 | 与主架构文档版本一致 | Winston |
+
 ## 现有技术栈维护
 | 类别 | 当前技术 | 版本 | 在增强中的用途 | 备注 |
 |------|----------|------|----------------|------|
@@ -7,7 +12,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 | 服务端状态管理 | 数据同步 |

docs/architecture/testing-strategy.md

@@ -3,7 +3,7 @@
 ## 版本信息
 | 版本 | 日期 | 描述 | 作者 |
 |------|------|------|------|
-| 1.0 | 2025-09-19 | 初始测试策略文档 | Winston |
+| 2.4 | 2025-09-20 | 更新测试策略与主架构文档版本一致 | Winston |
 
 ## 概述
 
@@ -275,6 +275,7 @@ describe('UserService', () => {
 | 日期 | 版本 | 描述 |
 |------|------|------|
 | 2025-09-19 | 1.0 | 初始版本，基于现有测试基础设施 |
+| 2025-09-20 | 2.4 | 更新版本与主架构文档一致 |
 
 ---
 

docs/architecture/version-info.md

@@ -2,3 +2,7 @@
 | 版本 | 日期 | 描述 | 作者 |
 |------|------|------|------|
 | 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 |

docs/development.md

@@ -4,6 +4,7 @@
 | 版本 | 日期 | 描述 | 作者 |
 |------|------|------|------|
 | 1.0 | 2025-09-15 | 初始开发指南 | Sarah (PO) |
+| 1.1 | 2025-09-20 | 更新为pnpm命令，添加完整测试命令 | Claude |
 
 ## 1. 环境要求
 
@@ -149,24 +150,38 @@ src/
 ### 4.2 常用开发命令
 ```bash
 # 开发命令
-npm run dev          # 启动完整开发环境
-npm run dev:client   # 仅启动前端
-npm run dev:server   # 仅启动后端
+pnpm dev             # 启动完整开发环境（前后端同时运行）
+
+# 测试命令
+pnpm test            # 运行API测试 (Vitest)
+pnpm test:api        # 运行API测试
+pnpm test:components # 运行组件测试
+pnpm test:integration # 运行集成测试
+pnpm test:e2e        # 运行E2E测试
+pnpm test:e2e:chromium # 运行Chrome E2E测试
+pnpm test:e2e:ui     # 运行E2E测试UI模式
+pnpm test:e2e:debug  # 运行E2E调试模式
 
 # 构建命令
-npm run build        # 生产构建
-npm run build:client # 仅构建前端
-npm run build:server # 仅构建后端
+pnpm build           # 生产构建
+pnpm build:client    # 仅构建前端
+pnpm build:server    # 仅构建后端
 
 # 数据库命令
-npm run db:migrate   # 运行数据库迁移
-npm run db:seed      # 填充种子数据
-npm run db:reset     # 重置数据库
+pnpm db:migrate      # 运行数据库迁移
+pnpm db:seed         # 填充种子数据
+pnpm db:reset        # 重置数据库
+pnpm db:backup       # 数据库备份
+pnpm db:restore      # 数据库恢复
+pnpm db:backup:list  # 列出备份文件
+pnpm db:backup:latest # 获取最新备份
+pnpm db:backup:cleanup # 清理旧备份
 
 # 代码质量
-npm run lint         # 代码检查
-npm run lint:fix     # 自动修复
-npm run typecheck    # 类型检查
+pnpm lint            # ESLint检查
+pnpm lint:fix        # 自动修复ESLint问题
+pnpm typecheck       # TypeScript类型检查
+pnpm test:coverage   # 生成测试覆盖率报告
 ```
 
 ### 4.3 热重载和调试