📝 docs(architecture): 完善BMAD全栈架构规范文档

- 添加版本2.4更新记录，包含架构完善内容
- 新增高层架构章节，包含平台选择和mermaid架构图
- 完善API规范，添加OpenAPI 3.0规范定义
- 扩展安全架构设计，详细说明前端、后端、认证授权和数据安全策略
- 更新技术栈中PostgreSQL版本为17
- 新增监控和可观测性章节，包含监控策略、日志管理和告警机制
- 添加错误处理策略章节，定义统一错误格式和前后端错误处理方案

docs/architecture.md

@@ -7,6 +7,7 @@
 | 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 |
 
 ## 介绍
 
@@ -25,6 +26,7 @@
 | 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 |
 
 ## 现有项目分析
 
@@ -73,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模式**: 类型安全的通用数据操作服务
+- **中间件模式**: 统一的认证、验证、错误处理中间件
+
 ## 技术栈
 
 ### 现有技术栈维护
@@ -82,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 | 服务端状态管理 | 数据同步 |
@@ -111,6 +176,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集成策略
 - **数据库变更要求**: 无新表创建，仅优化现有表结构
 - **新表**: 无
@@ -252,6 +373,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
@@ -498,6 +703,38 @@ src/server/
 - **集成点**: 中间件层、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用户运行
+- **安全监控**: 实时监控异常访问和攻击尝试
+
 ### 安全测试
 - **现有安全测试**: 无自动化安全测试
 - **新安全测试要求**: 添加安全扫描、渗透测试计划
@@ -540,6 +777,67 @@ src/server/
 - 测试生产环境部署流程仍然正常工作
 - 监控性能指标确保无退化
 
+## 监控和可观测性
+
+### 监控策略
+**前端监控**:
+- **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捕获渲染错误
+- **用户输入错误**: 实时验证和提示
+
+### 后端错误处理
+- **全局错误处理**: 统一错误处理中间件
+- **数据库错误**: 连接池管理和重试机制
+- **外部服务错误**: 熔断器和降级处理
+- **日志记录**: 所有错误记录详细上下文信息
+
 ## 附录
 
 ### 技术决策依据