# 源码树和文件组织

## 版本信息
| 版本 | 日期 | 描述 | 作者 |
|------|------|------|------|
| 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
│   ├── delivery-address-module/ # 配送地址管理模块 (@d8d/delivery-address-module)
│   │   ├── src/
│   │   │   ├── entities/
│   │   │   │   └── delivery-address.entity.ts  # 配送地址实体
│   │   │   ├── services/
│   │   │   │   └── delivery-address.service.ts # 配送地址服务
│   │   │   ├── schemas/
│   │   │   │   ├── user-delivery-address.schema.ts    # 用户专用Schema
│   │   │   │   └── admin-delivery-address.schema.ts   # 管理员专用Schema
│   │   │   └── routes/
│   │   │       ├── index.ts                    # 路由导出
│   │   │       ├── user-routes.ts              # 用户路由（数据权限控制）
│   │   │       ├── admin-routes.ts             # 管理员路由（完整权限）
│   │   │       └── admin-custom.routes.ts      # 管理员自定义路由（地区验证）
│   │   ├── tests/
│   │   │   └── integration/
│   │   │       ├── user-routes.integration.test.ts    # 用户路由集成测试
│   │   │       └── admin-routes.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构建
- **架构优势**:
  - 清晰的模块边界和职责分离
  - 支持按需安装，减少包体积
  - 基础设施和业务逻辑分离
  - 统一的测试模式和工具
  - 更好的代码复用和维护性
  - 独立的包版本管理
