# 源码树和文件组织

## 版本信息
| 版本 | 日期 | 描述 | 作者 |
|------|------|------|------|
| 3.0 | 2025-10-15 | 更新为出行服务项目源码树 | Winston |

## 实际项目结构
```text
出行服务项目/
├── mini/                       # Mini小程序应用
│   ├── pages/                  # 小程序页面
│   │   ├── index/              # 首页
│   │   ├── activities/         # 活动页面
│   │   ├── routes/             # 路线页面
│   │   ├── orders/             # 订单页面
│   │   └── profile/            # 个人中心
│   ├── components/             # 小程序组件
│   ├── utils/                  # 小程序工具函数
│   └── app.json               # 小程序配置文件
├── mini-demo/                  # Mini演示应用
│   ├── pages/                  # 演示页面
│   ├── components/             # 演示组件
│   └── app.json               # 演示应用配置
├── 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/               # 用户前台应用
│   │   │   ├── pages/          # 前台页面
│   │   │   │   ├── ActivityList.tsx    # 活动列表页面
│   │   │   │   ├── ActivityDetail.tsx  # 活动详情页面
│   │   │   │   ├── RouteDetail.tsx     # 路线详情页面
│   │   │   │   ├── OrderList.tsx       # 订单列表页面
│   │   │   │   ├── OrderDetail.tsx     # 订单详情页面
│   │   │   │   └── Payment.tsx         # 支付页面
│   │   │   ├── components/     # 前台专用组件
│   │   │   │   ├── ActivityCard.tsx    # 活动卡片组件
│   │   │   │   ├── RouteCard.tsx       # 路线卡片组件
│   │   │   │   ├── PassengerForm.tsx   # 乘客信息表单
│   │   │   │   └── OrderSummary.tsx    # 订单摘要组件
│   │   │   └── hooks/          # 前台Hooks
│   │   │       ├── useActivities.ts    # 活动相关Hook
│   │   │       ├── useRoutes.ts        # 路线相关Hook
│   │   │       └── useOrders.ts        # 订单相关Hook
│   │   ├── 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/          # 角色管理路由
│   │   │   ├── files/          # 文件管理路由
│   │   │   │   ├── multipart-policy/    # 多部分上传策略
│   │   │   │   ├── multipart-complete/  # 完成多部分上传
│   │   │   │   ├── [id]/               # 文件操作路由
│   │   │   │   └── upload-policy/      # 上传策略路由
│   │   │   ├── activities/     # 活动管理路由
│   │   │   │   ├── index.ts    # 活动列表路由
│   │   │   │   ├── [id].ts     # 活动详情路由
│   │   │   │   └── __tests__/  # 路由测试
│   │   │   ├── routes/         # 路线管理路由
│   │   │   │   ├── index.ts    # 路线列表路由
│   │   │   │   ├── [id].ts     # 路线详情路由
│   │   │   │   └── __tests__/  # 路由测试
│   │   │   ├── orders/         # 订单管理路由
│   │   │   │   ├── index.ts    # 订单列表路由
│   │   │   │   ├── [id].ts     # 订单详情路由
│   │   │   │   └── __tests__/  # 路由测试
│   │   │   ├── passengers/     # 乘客管理路由
│   │   │   │   ├── index.ts    # 乘客列表路由
│   │   │   │   ├── [id].ts     # 乘客详情路由
│   │   │   │   └── __tests__/  # 路由测试
│   │   │   └── __integration_tests__/  # 集成测试
│   │   ├── modules/            # 业务模块
│   │   │   ├── auth/           # 认证业务模块
│   │   │   │   ├── auth.service.ts # 认证服务
│   │   │   │   └── __tests__/  # 认证测试
│   │   │   ├── users/          # 用户业务模块
│   │   │   │   ├── user.entity.ts  # 用户实体
│   │   │   │   ├── user.service.ts # 用户服务
│   │   │   │   └── __tests__/  # 用户测试
│   │   │   ├── files/          # 文件业务模块
│   │   │   │   ├── file.entity.ts  # 文件实体
│   │   │   │   ├── file.service.ts # 文件服务
│   │   │   │   ├── minio.service.ts # MinIO服务
│   │   │   │   ├── file.schema.ts  # 文件验证Schema
│   │   │   │   └── __tests__/  # 文件测试
│   │   │   ├── activities/     # 活动业务模块
│   │   │   │   ├── activity.entity.ts   # 活动实体
│   │   │   │   ├── activity.service.ts  # 活动服务
│   │   │   │   └── __tests__/  # 活动测试
│   │   │   ├── routes/         # 路线业务模块
│   │   │   │   ├── route.entity.ts     # 路线实体
│   │   │   │   ├── route.service.ts    # 路线服务
│   │   │   │   └── __tests__/  # 路线测试
│   │   │   ├── orders/         # 订单业务模块
│   │   │   │   ├── order.entity.ts     # 订单实体
│   │   │   │   ├── order.service.ts    # 订单服务
│   │   │   │   └── __tests__/  # 订单测试
│   │   │   └── passengers/     # 乘客业务模块
│   │   │   │   ├── passenger.entity.ts # 乘客实体
│   │   │   │   ├── passenger.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类型定义
│       ├── activity.types.ts  # 活动相关类型
│       ├── route.types.ts     # 路线相关类型
│       ├── order.types.ts     # 订单相关类型
│       └── passenger.types.ts # 乘客相关类型
├── tests/
│   └── e2e/                    # E2E测试 (Playwright)
└── package.json
```

## 集成指南
- **文件命名**: 保持现有kebab-case命名约定
- **文件夹组织**: 遵循功能模块划分，添加__tests__文件夹
- **测试结构**: 单元测试位于`__tests__/`目录，集成测试位于`__integration_tests__/`目录
- **导入/导出模式**: 使用ES模块，保持现有别名系统（@/）
- **测试位置**: 前端集成测试位于`__integration_tests__/`，页面单元测试位于`__tests__/`
- **后端测试**: API测试位于路由`__tests__/`目录，服务测试位于模块`__tests__/`目录
- **工具测试**: 通用工具测试位于`utils/__tests__/`目录
- **Mini小程序**: 使用Taro框架开发，支持微信小程序
- **Mini演示应用**: 用于功能演示和测试的独立小程序应用
