# 源码树和文件组织

## 版本信息
| 版本 | 日期 | 描述 | 作者 |
|------|------|------|------|
| 3.1 | 2025-10-22 | 更新为 monorepo 结构，添加 packages/server | Winston |

## 实际项目结构
```text
项目根目录/
├── mini/                       # 小程序项目 (Taro + React)
│   ├── src/
│   │   ├── app.tsx            # 小程序入口
│   │   ├── app.config.ts      # 小程序配置
│   │   ├── api.ts             # API客户端
│   │   ├── components/
│   │   │   ├── AreaPicker.tsx               # 地区选择组件
│   │   │   └── ui/            # UI组件库
│   │   │       ├── avatar-upload.tsx    # 头像上传组件
│   │   │       ├── button.tsx           # 按钮组件
│   │   │       ├── card.tsx             # 卡片组件
│   │   │       ├── dialog.tsx           # 对话框组件
│   │   │       ├── form.tsx             # 表单组件
│   │   │       ├── image.tsx            # 图片组件
│   │   │       ├── input.tsx            # 输入框组件
│   │   │       ├── label.tsx            # 标签组件
│   │   │       ├── navbar.tsx           # 导航栏组件
│   │   │       ├── select.tsx           # 选择器组件
│   │   │       └── tab-bar.tsx          # 标签栏组件
│   │   ├── layouts/
│   │   │   └── tab-bar-layout.tsx       # 标签栏布局
│   │   ├── pages/
│   │   │   ├── explore/                 # 探索页面
│   │   │   │   ├── index.tsx
│   │   │   │   └── index.config.ts
│   │   │   ├── home/                    # 首页
│   │   │   │   ├── index.tsx
│   │   │   │   └── index.config.ts
│   │   │   ├── index/                   # 入口页面
│   │   │   │   ├── index.tsx
│   │   │   │   └── index.config.ts
│   │   │   ├── login/                   # 登录页面
│   │   │   │   ├── index.tsx
│   │   │   │   ├── index.config.ts
│   │   │   │   └── wechat-login.tsx     # 微信登录
│   │   │   ├── passengers/              # 乘客管理
│   │   │   │   ├── add-passenger.tsx
│   │   │   │   ├── add-passenger.config.ts
│   │   │   │   ├── passengers.tsx
│   │   │   │   └── passengers.config.ts
│   │   │   └── profile/                 # 个人资料
│   │   │       ├── index.tsx
│   │   │       └── index.config.ts
│   │   ├── schemas/            # 验证模式
│   │   └── utils/              # 工具函数
│   ├── config/                 # 构建配置
│   ├── dist/                   # 构建输出
│   └── package.json            # 项目依赖配置
├── mini-demo/                  # 小程序演示应用
├── packages/                   # 共享包
│   └── server/                 # API服务器包
│       ├── src/
│       │   ├── api/            # API路由
│       │   │   ├── admin/      # 管理员接口
│       │   │   │   ├── activities/index.ts    # 活动管理
│       │   │   │   ├── areas/index.ts         # 地区管理
│       │   │   │   ├── areas/tree.ts          # 地区树形结构
│       │   │   │   ├── locations/index.ts     # 地点管理
│       │   │   │   ├── passengers/index.ts    # 乘客管理
│       │   │   │   └── routes/index.ts        # 路线管理
│       │   │   ├── areas/index.ts             # 地区接口
│       │   │   ├── auth/       # 认证相关
│       │   │   │   ├── index.ts                 # 认证路由入口
│       │   │   │   ├── login/post.ts            # 登录接口
│       │   │   │   ├── logout.ts                # 登出接口
│       │   │   │   ├── me/get.ts                # 获取用户信息
│       │   │   │   ├── me/put.ts                # 更新用户信息
│       │   │   │   ├── mini-login/post.ts       # 小程序登录
│       │   │   │   ├── register/create.ts       # 注册接口
│       │   │   │   └── sso-verify.ts            # SSO验证
│       │   │   ├── files/      # 文件管理
│       │   │   │   ├── [id]/delete.ts           # 删除文件
│       │   │   │   ├── [id]/download.ts         # 下载文件
│       │   │   │   ├── [id]/get-url.ts          # 获取文件URL
│       │   │   │   ├── index.ts                 # 文件列表
│       │   │   │   ├── multipart-complete/post.ts # 完成分片上传
│       │   │   │   ├── multipart-policy/post.ts # 分片上传策略
│       │   │   │   └── upload-policy/post.ts    # 上传策略
│       │   │   ├── locations/index.ts           # 地点接口
│       │   │   ├── passengers/index.ts          # 乘客接口
│       │   │   ├── roles/index.ts               # 角色管理
│       │   │   ├── routes/index.ts              # 路线接口
│       │   │   ├── users/index.ts               # 用户管理
│       │   │   └── users/custom.ts              # 自定义用户接口
│       │   ├── modules/        # 业务模块
│       │   ├── middleware/     # 中间件
│       │   ├── share/          # 共享类型
│       │   ├── types/          # 类型定义
│       │   ├── utils/          # 工具函数
│       │   ├── data-source.ts                   # 数据库连接
│       │   └── index.ts                         # 服务器入口
│       └── package.json
├── web/                        # Web应用 (React + Vite)
│   ├── src/
│   │   ├── client/             # 客户端代码
│   │   │   ├── admin/          # 管理后台
│   │   │   │   ├── components/ # 管理后台组件
│   │   │   │   │   ├── ActivityForm.tsx        # 活动表单
│   │   │   │   │   ├── ActivitySelect.tsx      # 活动选择器
│   │   │   │   │   ├── AreaForm.tsx            # 地区表单
│   │   │   │   │   ├── AreaSelect.tsx          # 地区选择器
│   │   │   │   │   ├── AreaTree.tsx            # 地区树形组件
│   │   │   │   │   ├── AvatarSelector.tsx      # 头像选择器
│   │   │   │   │   ├── DataTablePagination.tsx # 表格分页
│   │   │   │   │   ├── ErrorPage.tsx           # 错误页面
│   │   │   │   │   ├── FileSelector.tsx        # 文件选择器
│   │   │   │   │   ├── LocationForm.tsx        # 地点表单
│   │   │   │   │   ├── LocationSelect.tsx      # 地点选择器
│   │   │   │   │   ├── MinioUploader.tsx       # MinIO上传器
│   │   │   │   │   ├── NotFoundPage.tsx        # 404页面
│   │   │   │   │   ├── ProtectedRoute.tsx      # 路由保护
│   │   │   │   │   └── RouteForm.tsx           # 路线表单
│   │   │   │   ├── hooks/
│   │   │   │   │   └── AuthProvider.tsx        # 认证状态管理
│   │   │   │   ├── layouts/
│   │   │   │   │   └── MainLayout.tsx          # 主布局
│   │   │   │   ├── pages/
│   │   │   │   │   ├── Activities.tsx          # 活动管理
│   │   │   │   │   ├── Areas.tsx               # 地区管理
│   │   │   │   │   ├── Dashboard.tsx           # 仪表板
│   │   │   │   │   ├── Files.tsx               # 文件管理
│   │   │   │   │   ├── Locations.tsx           # 地点管理
│   │   │   │   │   ├── Login.tsx               # 登录页面
│   │   │   │   │   ├── Passengers.tsx          # 乘客管理
│   │   │   │   │   ├── Routes.tsx              # 路线管理
│   │   │   │   │   └── Users.tsx               # 用户管理
│   │   │   │   ├── menu.tsx                    # 菜单配置
│   │   │   │   ├── routes.tsx                  # 路由配置
│   │   │   │   └── index.tsx                   # 管理后台入口
│   │   │   ├── components/
│   │   │   │   └── ui/                         # UI组件库
│   │   │   ├── api.ts                          # API客户端
│   │   │   └── index.tsx                       # 前端入口
│   │   ├── server/             # 服务器端代码
│   │   │   └── server.js                       # 服务器入口
│   │   └── share/              # 共享代码
│   ├── tests/                  # 测试目录
│   ├── public/                 # 静态资源
│   ├── index.html              # 入口HTML
│   └── package.json            # 项目配置
├── docs/                       # 项目文档
│   └── architecture/           # 架构文档
├── scripts/                    # 脚本文件
├── backups/                    # 备份文件
├── dist/                       # 构建输出
├── .bmad-core/                 # BMAD核心配置
├── .claude/                    # Claude配置
├── .git/                       # Git仓库
├── .pnpm-store/                # pnpm存储
├── package.json                # 根项目配置
├── pnpm-workspace.yaml         # pnpm workspace配置
└── README.md                   # 项目说明
```

## 集成指南
- **文件命名**: 保持现有kebab-case命名约定
- **项目结构**: 采用monorepo模式，包含小程序(mini)、Web应用(web)和共享服务器包(packages/server)
- **包管理**: 使用pnpm workspace管理多包依赖关系
- **文件夹组织**: 遵循功能模块划分，各项目独立维护源代码，测试文件统一在各自的`tests/`目录
- **导入/导出模式**: 使用ES模块，保持现有别名系统（@/）
- **小程序架构**: 基于Taro框架，支持微信小程序等多平台，使用React语法开发
- **Web应用架构**: 基于React + Vite，包含管理后台，使用现代前端技术栈
- **API服务器**: 独立的server包，基于Hono框架，提供RESTful API
- **API设计**: 遵循RESTful设计规范，支持文件分片上传
- **数据库**: 使用PostgreSQL + TypeORM进行数据管理
- **存储**: 使用MinIO进行文件存储管理
- **测试结构**:
  - 单元测试位于`tests/unit/`目录
  - 集成测试位于`tests/integration/`目录
  - E2E测试位于`tests/e2e/`目录 (Playwright)
  - 前端测试在各项目的`tests/unit/client/`和`tests/integration/client/`
  - 后端测试在`packages/server/tests/unit/`和`packages/server/tests/integration/`
  - API测试位于`packages/server/tests/integration/api/`目录
  - 服务测试位于`packages/server/tests/unit/modules/`目录
- **开发环境**: 多八多云端开发容器，包含Node.js 20.19.2、PostgreSQL 17、Redis 7、MinIO
- **构建工具**: 使用Vite + pnpm，支持SSR构建
- **架构优势**:
  - 各模块可独立开发、测试和部署
  - 前端和后端可并行开发
  - 共享类型定义减少前后端不一致问题
  - 统一的错误处理和中间件机制
  - 适合团队协作和规模化开发