# 源码树和文件组织

## 版本信息
| 版本 | 日期 | 描述 | 作者 |
|------|------|------|------|
| 2.4 | 2025-09-20 | 与主架构文档版本一致 | Winston |

## 实际项目结构
```text
d8d-starter/
├── src/
│   ├── 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__/`目录