📝 docs(architecture): 根据实际项目结构更新架构文档

- 添加版本历史记录（2.3版本）
- 详细描述前端组件架构和技术栈配置
- 详细描述后端组件架构和技术栈配置
- 更新源码树和文件组织结构图
- 添加开发工作流章节，包含常用命令和环境配置
- 扩展测试策略章节，添加测试目录结构和测试位置说明
- 更新最后更新时间为2025-09-20

docs/architecture.md

@@ -6,6 +6,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 |
 
 ## 介绍
 
@@ -21,6 +22,7 @@
 | 2025-09-14 | 2.0 | 增强架构文档 | Winston |
 | 2025-09-19 | 2.1 | 添加数据库定时备份策略 | Winston |
 | 2025-09-19 | 2.2 | 更新测试策略文档引用 | Winston |
+| 2025-09-20 | 2.3 | 根据实际项目结构更新测试架构和共享目录 | Winston |
 
 ## 现有项目分析
 
@@ -122,15 +124,107 @@
 
 ## 组件架构
 
-### 现有组件优化
-**通用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.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操作，支持自定义扩展
 - **现状**: 已实现完整功能，支持关联查询和复杂操作
+- **文件位置**: `src/server/utils/generic-crud.service.ts`
+- **路由生成**: `src/server/utils/generic-crud.routes.ts`
 - **优化重点**: 增强错误处理、添加测试覆盖、优化性能
 
-**API文档组件**:
+### API文档组件
 - **责任**: 自动生成和维护OpenAPI文档
 - **现状**: 通过@hono/zod-openapi集成，提供Swagger UI
+- **访问路径**: `/ui` 端点
 - **优化重点**: 完善文档示例、确保文档与代码同步
 
 ### 组件交互
@@ -194,52 +288,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/           # 现有结构保持不变
-│   ├── server/
-│   │   ├── api/
-│   │   │   ├── users/
-│   │   │   │   ├── __tests__/          # 新增：API测试
-│   │   │   │   ├── [id]/
-│   │   │   │   ├── get.ts
-│   │   │   │   └── index.ts
-│   │   ├── modules/
-│   │   │   ├── users/
-│   │   │   │   ├── __tests__/          # 新增：服务测试
-│   │   │   │   ├── user.entity.ts
-│   │   │   │   ├── user.service.ts
-│   │   │   │   └── role.entity.ts
-│   │   └── 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
 ```
 
 ### 集成指南
@@ -265,6 +343,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
+```
+
 ## 编码标准和测试策略
 
 ### 现有标准合规性
@@ -280,6 +405,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契约
 - **数据库集成**: 使用测试数据库，避免污染生产数据
@@ -356,7 +553,7 @@ d8d-starter/
 
 ### 联系方式
 - 架构师: Winston 🏗️
-- 最后更新: 2025-09-19
+- 最后更新: 2025-09-20
 
 ---