# 源码树和文件组织 ## 版本信息 | 版本 | 日期 | 描述 | 作者 | |------|------|------|------| | 3.2 | 2025-11-11 | 更新包结构，添加基础设施和业务模块包 | Winston | | 3.1 | 2025-11-09 | 更新测试结构，清理重复测试文件 | James | | 3.0 | 2025-10-22 | 更新为 monorepo 结构，添加 packages/server | Winston | ## 实际项目结构 ```text d8d-mini-starter/ ├── mini/ # 小程序项目 (Taro + React) │ ├── src/ │ │ ├── app.tsx # 小程序入口 │ │ ├── app.config.ts # 小程序配置 │ │ ├── api.ts # API客户端 │ │ ├── components/ │ │ │ └── ui/ # UI组件库 │ │ │ ├── avatar-upload.tsx # 头像上传组件 │ │ │ ├── button.tsx # 按钮组件 │ │ │ ├── card.tsx # 卡片组件 │ │ │ ├── form.tsx # 表单组件 │ │ │ ├── image.tsx # 图片组件 │ │ │ ├── input.tsx # 输入框组件 │ │ │ ├── label.tsx # 标签组件 │ │ │ ├── navbar.tsx # 导航栏组件 │ │ │ └── tab-bar.tsx # 标签栏组件 │ │ ├── layouts/ │ │ │ └── tab-bar-layout.tsx # 标签栏布局 │ │ ├── pages/ │ │ │ ├── explore/ # 探索页面 │ │ │ │ ├── index.tsx │ │ │ │ └── index.config.ts │ │ │ ├── index/ # 首页 │ │ │ │ ├── index.tsx │ │ │ │ └── index.config.ts │ │ │ ├── login/ # 登录页面 │ │ │ │ ├── index.tsx │ │ │ │ ├── index.config.ts │ │ │ │ └── wechat-login.tsx # 微信登录 │ │ │ ├── profile/ # 个人资料 │ │ │ │ ├── index.tsx │ │ │ │ └── index.config.ts │ │ │ └── register/ # 注册页面 │ │ │ ├── index.tsx │ │ │ └── index.config.ts │ │ ├── schemas/ # 验证模式 │ │ └── utils/ # 工具函数 │ ├── config/ │ │ ├── dev.ts # 开发环境配置 │ │ ├── index.ts # 配置入口 │ │ └── prod.ts # 生产环境配置 │ └── package.json ├── packages/ # 共享包 │ ├── server/ # API服务器包 (@d8d/server) - 重构后 │ │ ├── src/ │ │ │ ├── api.ts # API路由导出 │ │ │ └── index.ts # 服务器入口 │ │ ├── tests/ │ │ └── package.json │ ├── shared-types/ # 共享类型定义 (@d8d/shared-types) │ │ ├── src/ │ │ │ └── index.ts # 类型定义导出 │ │ └── package.json │ ├── shared-utils/ # 共享工具函数 (@d8d/shared-utils) │ │ ├── src/ │ │ │ ├── utils/ │ │ │ │ ├── jwt.util.ts # JWT工具 │ │ │ │ ├── errorHandler.ts # 错误处理 │ │ │ │ ├── parseWithAwait.ts # 异步解析 │ │ │ │ ├── logger.ts # 日志工具 │ │ │ │ └── redis.util.ts # Redis会话管理 │ │ │ └── data-source.ts # 数据库连接 │ │ ├── tests/ │ │ └── package.json │ ├── shared-crud/ # 通用CRUD基础设施 (@d8d/shared-crud) │ │ ├── src/ │ │ │ ├── services/ │ │ │ │ ├── generic-crud.service.ts # 通用CRUD服务 │ │ │ │ └── concrete-crud.service.ts # 具体CRUD服务 │ │ │ └── routes/ │ │ │ └── generic-crud.routes.ts # 通用CRUD路由 │ │ ├── tests/ │ │ └── package.json │ ├── shared-test-util/ # 测试基础设施 (@d8d/shared-test-util) │ │ ├── src/ │ │ │ ├── integration-test-db.ts # 集成测试数据库工具 │ │ │ ├── integration-test-utils.ts # 集成测试断言工具 │ │ ├── tests/ │ │ └── package.json │ ├── user-module/ # 用户管理模块 (@d8d/user-module) │ │ ├── src/ │ │ │ ├── entities/ │ │ │ │ ├── user.entity.ts # 用户实体 │ │ │ │ └── role.entity.ts # 角色实体 │ │ │ ├── services/ │ │ │ │ ├── user.service.ts # 用户服务 │ │ │ │ └── role.service.ts # 角色服务 │ │ │ ├── schemas/ │ │ │ │ ├── user.schema.ts # 用户Schema │ │ │ │ └── role.schema.ts # 角色Schema │ │ │ └── routes/ │ │ │ ├── user.routes.ts # 用户路由 │ │ │ ├── role.routes.ts # 角色路由 │ │ │ └── custom.routes.ts # 自定义路由 │ │ ├── tests/ │ │ └── package.json │ ├── auth-module/ # 认证管理模块 (@d8d/auth-module) │ │ ├── src/ │ │ │ ├── services/ │ │ │ │ ├── auth.service.ts # 认证服务 │ │ │ │ └── mini-auth.service.ts # 小程序认证服务 │ │ │ ├── schemas/ │ │ │ │ └── auth.schema.ts # 认证Schema │ │ │ ├── routes/ │ │ │ │ ├── login.route.ts # 登录路由 │ │ │ │ ├── register.route.ts # 注册路由 │ │ │ │ ├── mini-login.route.ts # 小程序登录路由 │ │ │ │ ├── phone-decrypt.route.ts # 手机号解密路由 │ │ │ │ ├── me.route.ts # 获取用户信息路由 │ │ │ │ ├── update-me.route.ts # 更新用户信息路由 │ │ │ │ ├── logout.route.ts # 登出路由 │ │ │ │ └── sso-verify.route.ts # SSO验证路由 │ │ │ └── middleware/ │ │ │ ├── auth.middleware.ts # 认证中间件 │ │ │ └── index.ts # 中间件导出 │ │ ├── tests/ │ │ └── package.json │ ├── file-module/ # 文件管理模块 (@d8d/file-module) │ │ ├── src/ │ │ │ ├── entities/ │ │ │ │ └── file.entity.ts # 文件实体 │ │ │ ├── services/ │ │ │ │ ├── file.service.ts # 文件服务 │ │ │ │ └── minio.service.ts # MinIO服务 │ │ │ ├── schemas/ │ │ │ │ └── file.schema.ts # 文件Schema │ │ │ └── routes/ │ │ │ ├── upload-policy/post.ts # 上传策略路由 │ │ │ ├── multipart-policy/post.ts # 多部分上传策略路由 │ │ │ ├── multipart-complete/post.ts # 完成多部分上传路由 │ │ │ └── [id]/ │ │ │ ├── get.ts # 获取文件详情路由 │ │ │ ├── get-url.ts # 获取文件URL路由 │ │ │ ├── download.ts # 文件下载路由 │ │ │ └── delete.ts # 删除文件路由 │ │ ├── tests/ │ │ └── package.json │ ├── mini-payment/ # 微信小程序支付模块 (@d8d/mini-payment) │ │ ├── src/ │ │ │ ├── entities/ │ │ │ │ ├── payment.entity.ts # 支付实体 │ │ │ │ └── payment.types.ts # 支付类型定义 │ │ │ ├── services/ │ │ │ │ └── payment.service.ts # 支付服务 │ │ │ ├── schemas/ │ │ │ │ └── payment.schema.ts # 支付Schema │ │ │ └── routes/ │ │ │ └── payment/ │ │ │ ├── create.ts # 支付创建路由 │ │ │ ├── callback.ts # 支付回调路由 │ │ │ └── status.ts # 支付状态查询路由 │ │ ├── tests/ │ │ │ └── integration/ │ │ │ ├── payment.integration.test.ts # 支付集成测试 │ │ │ └── payment-callback.integration.test.ts # 支付回调集成测试 │ │ └── package.json │ └── geo-areas/ # 地区模块 (@d8d/geo-areas) │ ├── src/ │ │ ├── modules/areas/ │ │ │ ├── area.entity.ts # 地区实体 │ │ │ ├── area.service.ts # 地区服务 │ │ │ └── area.schema.ts # 地区Schema │ │ ├── api/ │ │ │ ├── areas/index.ts # 公共地区API │ │ │ └── admin/areas/index.ts # 管理地区API │ │ └── index.ts # 包入口 │ ├── tests/ │ └── package.json ├── web/ # Web应用 (Hono + React SSR) │ ├── src/ │ │ ├── client/ # 客户端代码 │ │ │ ├── admin/ # 管理后台 │ │ │ │ ├── components/ # 管理后台组件 │ │ │ │ │ ├── AvatarSelector.tsx # 头像选择器 │ │ │ │ │ ├── DataTablePagination.tsx # 表格分页 │ │ │ │ │ ├── ErrorPage.tsx # 错误页面 │ │ │ │ │ ├── FileSelector.tsx # 文件选择器 │ │ │ │ │ ├── MinioUploader.tsx # MinIO上传器 │ │ │ │ │ ├── NotFoundPage.tsx # 404页面 │ │ │ │ │ └── ProtectedRoute.tsx # 路由保护 │ │ │ │ ├── hooks/ │ │ │ │ │ └── AuthProvider.tsx # 认证状态管理 │ │ │ │ ├── layouts/ │ │ │ │ │ └── MainLayout.tsx # 主布局 │ │ │ │ ├── pages/ │ │ │ │ │ ├── Dashboard.tsx # 仪表板 │ │ │ │ │ ├── Files.tsx # 文件管理 │ │ │ │ │ ├── Login.tsx # 登录页面 │ │ │ │ │ └── Users.tsx # 用户管理 │ │ │ │ ├── menu.tsx # 菜单配置 │ │ │ │ ├── routes.tsx # 路由配置 │ │ │ │ └── index.tsx # 管理后台入口 │ │ │ ├── components/ │ │ │ │ └── ui/ # shadcn/ui组件库 │ │ │ │ ├── accordion.tsx # 手风琴组件 │ │ │ │ ├── alert-dialog.tsx # 警告对话框 │ │ │ │ ├── alert.tsx # 警告组件 │ │ │ │ └── ... # 其他50+组件 │ │ │ ├── api.ts # API客户端 │ │ │ └── index.tsx # 前端入口 │ │ ├── server/ # 服务器端代码 (SSR) │ │ │ ├── index.tsx # 服务器入口 │ │ │ └── renderer.tsx # React渲染器 │ │ └── share/ # 共享代码 │ ├── tests/ │ │ ├── e2e/ # E2E测试 (Playwright) │ │ ├── integration/ # Web集成测试 │ │ │ └── client/ # 客户端集成测试 │ │ └── unit/ # 单元测试 │ │ └── client/ # 客户端单元测试 │ │ ├── pages/ # 页面组件测试 │ │ │ └── Users.test.tsx # 用户页面测试 │ │ └── debug.test.tsx # 调试测试 │ └── package.json ├── docs/ # 项目文档 │ └── architecture/ # 架构文档 ├── scripts/ # 脚本文件 ├── .bmad-core/ # BMAD核心配置 ├── .claude/ # Claude配置 ├── .git/ # Git仓库 ├── package.json # 根项目配置 ├── pnpm-workspace.yaml # pnpm workspace 配置 └── pnpm-lock.yaml # 依赖锁定文件 ``` ## 集成指南 - **文件命名**: 保持现有kebab-case命名约定 - **项目结构**: 采用monorepo模式，包含小程序(mini)、Web应用(web)和模块化包架构 - **包管理**: 使用pnpm workspace管理多包依赖关系 - **小程序架构**: 基于Taro框架，支持多平台（微信小程序、H5等） - **Web应用架构**: 基于Hono + React SSR，使用shadcn/ui组件库 - **模块化架构**: 采用分层包结构，支持按需安装和独立开发 - **API服务器**: 重构后的`@d8d/server`包，基于模块化架构，提供RESTful API - **API设计**: 使用Hono框架，RESTful API设计，支持文件分片上传 - **数据库**: 使用PostgreSQL + TypeORM - **存储**: 使用MinIO进行文件存储 - **包架构层次**: - **基础设施层**: shared-types → shared-utils → shared-crud - **测试基础设施**: shared-test-util - **业务模块层**: user-module → auth-module → file-module → geo-areas - **应用层**: server (重构后) - **测试结构**: - **基础设施包**: 每个包独立的单元测试和集成测试 - **业务模块包**: 每个模块包含完整的测试套件 - **server包**: 集成测试验证模块间协作 - **web应用**: 组件测试、集成测试和E2E测试 - **开发环境**: 多八多云端开发容器，包含Node.js 20.19.2、PostgreSQL 17、Redis 7、MinIO - **构建工具**: 使用Vite + pnpm，支持SSR构建 - **架构优势**: - 清晰的模块边界和职责分离 - 支持按需安装，减少包体积 - 基础设施和业务逻辑分离 - 统一的测试模式和工具 - 更好的代码复用和维护性 - 独立的包版本管理