源码树和文件组织
版本信息
| 版本 |
日期 |
描述 |
作者 |
| 3.1 |
2025-10-22 |
更新为 monorepo 结构，添加 packages/server |
Winston |
实际项目结构
项目根目录/
├── 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构建
- 架构优势:
- 各模块可独立开发、测试和部署
- 前端和后端可并行开发
- 共享类型定义减少前后端不一致问题
- 统一的错误处理和中间件机制
- 适合团队协作和规模化开发
