📝 docs(architecture): enhance architecture documentation with detailed specifications

- add OpenAPI specification with security schemes and data schemas
- document frontend and backend component architecture with directory structure
- add TypeScript interface definitions for data models and relationships
- create new development workflow document with commands and environment variables
- add operations and monitoring documentation including error handling strategy
- enhance security integration with detailed security architecture design
- update document index and introduction with new subdocuments structure
- update version history with latest documentation changes

docs/architecture/api-design-integration.md

@@ -5,6 +5,90 @@
 - **认证**: 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/component-architecture.md

@@ -1,5 +1,95 @@
 # 组件架构
 
+### 前端组件架构
+
+**实际项目组件组织**:
+```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

@@ -13,6 +13,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集成策略
 - **数据库变更要求**: 无新表创建，仅优化现有表结构
 - **新表**: 无

docs/architecture/development-workflow.md

@@ -0,0 +1,46 @@
+# 开发工作流
+
+## 实际开发命令
+```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/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/introduction.md

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

@@ -0,0 +1,61 @@
+# 运营和监控
+
+## 监控策略
+
+**前端监控**:
+- **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捕获渲染错误
+- **用户输入错误**: 实时验证和提示
+
+### 后端错误处理
+- **全局错误处理**: 统一错误处理中间件
+- **数据库错误**: 连接池管理和重试机制
+- **外部服务错误**: 熔断器和降级处理
+- **日志记录**: 所有错误记录详细上下文信息

docs/architecture/security-integration.md

@@ -11,6 +11,38 @@
 - **集成点**: 中间件层、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用户运行
+- **安全监控**: 实时监控异常访问和攻击尝试
+
 ## 安全测试
 - **现有安全测试**: 已集成安全测试到测试策略中
 - **安全测试要求**: 包括输入验证测试、认证测试、数据保护测试

docs/architecture/version-info.md

@@ -5,3 +5,4 @@
 | 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 |