# 源码树和文件组织

## 版本信息
| 版本 | 日期 | 描述 | 作者 |
|------|------|------|------|
| 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/            # API路由
│       │   │   ├── 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    # 上传策略
│       │   │   ├── roles/index.ts               # 角色管理
│       │   │   ├── users/index.ts               # 用户管理
│       │   │   └── users/custom.ts              # 自定义用户接口
│       │   ├── modules/        # 业务模块
│       │   │   ├── auth/       # 认证模块
│       │   │   │   ├── auth.service.ts          # 认证服务
│       │   │   │   └── mini-auth.service.ts     # 小程序认证服务
│       │   │   ├── files/      # 文件模块
│       │   │   │   ├── file.entity.ts           # 文件实体
│       │   │   │   ├── file.schema.ts           # 文件模式
│       │   │   │   ├── file.service.ts          # 文件服务
│       │   │   │   └── minio.service.ts         # MinIO服务
│       │   │   └── users/      # 用户模块
│       │   │       ├── role.entity.ts           # 角色实体
│       │   │       ├── role.schema.ts           # 角色模式
│       │   │       ├── role.service.ts          # 角色服务
│       │   │       ├── user.entity.ts           # 用户实体
│       │   │       ├── user.schema.ts           # 用户模式
│       │   │       └── user.service.ts          # 用户服务
│       │   ├── middleware/     # 中间件
│       │   │   ├── auth.middleware.ts           # 认证中间件
│       │   │   └── permission.middleware.ts     # 权限中间件
│       │   ├── share/          # 共享类型
│       │   │   └── types.ts                     # 共享类型定义
│       │   ├── types/          # 类型定义
│       │   │   └── context.ts                   # 上下文类型
│       │   ├── utils/          # 工具函数
│       │   │   ├── backup.ts                    # 数据库备份
│       │   │   ├── concrete-crud.service.ts     # 具体CRUD服务
│       │   │   ├── errorHandler.ts              # 错误处理
│       │   │   ├── generic-crud.routes.ts       # 通用CRUD路由
│       │   │   ├── generic-crud.service.ts      # 通用CRUD服务
│       │   │   ├── jwt.util.ts                  # JWT工具
│       │   │   ├── logger.ts                    # 日志工具
│       │   │   ├── parseWithAwait.ts            # 异步解析
│       │   │   └── restore.ts                   # 数据库恢复
│       │   ├── data-source.ts                   # 数据库连接
│       │   └── index.ts                         # 服务器入口
│       ├── tests/              # 服务器测试
│       │   ├── integration/    # 集成测试
│       │   │   ├── auth.integration.test.ts      # 认证集成测试
│       │   │   ├── backup.integration.test.ts    # 备份集成测试
│       │   │   ├── files.integration.test.ts     # 文件集成测试
│       │   │   ├── minio.integration.test.ts     # MinIO集成测试
│       │   │   └── users.integration.test.ts     # 用户集成测试
│       │   └── unit/           # 单元测试
│       │       ├── modules/    # 业务模块测试
│       │       │   ├── file.service.test.ts      # 文件服务测试
│       │       │   ├── minio.service.test.ts     # MinIO服务测试
│       │       │   └── user.service.test.ts      # 用户服务测试
│       │       └── utils/      # 工具函数测试
│       │           ├── backup.test.ts            # 备份工具测试
│       │           └── restore.test.ts           # 恢复工具测试
│       └── 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)和共享服务器包(packages/server)
- **包管理**: 使用pnpm workspace管理多包依赖关系
- **小程序架构**: 基于Taro框架，支持多平台（微信小程序、H5等）
- **Web应用架构**: 基于Hono + React SSR，使用shadcn/ui组件库
- **API服务器**: 独立的`@d8d/server`包，基于Hono框架，提供RESTful API
- **API设计**: 使用Hono框架，RESTful API设计，支持文件分片上传
- **数据库**: 使用PostgreSQL + TypeORM
- **存储**: 使用MinIO进行文件存储
- **测试结构**:
  - **packages/server**: 独立的服务器测试
    - 单元测试位于`packages/server/tests/unit/`
    - 集成测试位于`packages/server/tests/integration/`
  - **web**: Web应用测试
    - 单元测试位于`web/tests/unit/`
    - 集成测试位于`web/tests/integration/`
    - E2E测试位于`web/tests/e2e/` (Playwright)
- **开发环境**: 多八多云端开发容器，包含Node.js 20.19.2、PostgreSQL 17、Redis 7、MinIO
- **构建工具**: 使用Vite + pnpm，支持SSR构建
- **架构优势**:
  - 服务器代码可独立部署和测试
  - 前端和后端可独立开发
  - 共享类型定义减少重复代码
  - 统一的错误处理和中间件
