mini-starter/docs/architecture/source-tree.md

源码树和文件组织

版本信息

版本	日期	描述	作者
2.4	2025-09-20	与主架构文档版本一致	Winston

实际项目结构

d8d-starter/
├── src/
│   ├── client/                 # React前端应用
│   │   ├── admin/              # 管理后台应用
│   │   │   ├── components/     # 管理后台专用组件
│   │   │   │   ├── ProtectedRoute.tsx    # 路由保护组件
│   │   │   │   ├── ErrorPage.tsx         # 错误页面
│   │   │   │   └── NotFoundPage.tsx      # 404页面
│   │   │   ├── hooks/          # 管理后台Hooks
│   │   │   │   └── AuthProvider.tsx      # 认证状态管理
│   │   │   ├── layouts/        # 布局组件
│   │   │   │   └── MainLayout.tsx        # 主布局
│   │   │   ├── pages/          # 页面组件
│   │   │   │   ├── Dashboard.tsx         # 仪表板
│   │   │   │   ├── Login.tsx             # 登录页面
│   │   │   │   └── Users.tsx             # 用户管理
│   │   │   ├── routes.tsx      # 路由配置
│   │   │   └── index.tsx       # 管理后台入口
│   │   ├── home/               # 用户前台应用
│   │   ├── components/         # 共享UI组件
│   │   │   └── ui/            # shadcn/ui组件库（50+组件）
│   │   │       ├── button.tsx   # 按钮组件
│   │   │       ├── input.tsx    # 输入框组件
│   │   │       ├── table.tsx    # 表格组件
│   │   │       └── ...          # 其他组件
│   │   ├── hooks/             # 共享Hooks
│   │   ├── lib/               # 工具库
│   │   ├── utils/             # 工具函数
│   │   ├── api.ts             # API客户端配置
│   │   └── index.tsx          # 前端入口
│   ├── server/                 # Hono后端应用
│   │   ├── api/                # API路由
│   │   │   ├── auth/           # 认证相关路由
│   │   │   │   ├── login.ts    # 登录路由
│   │   │   │   ├── logout.ts   # 登出路由
│   │   │   │   └── register.ts # 注册路由
│   │   │   ├── users/          # 用户管理路由
│   │   │   │   ├── index.ts    # 用户列表路由
│   │   │   │   ├── [id].ts     # 用户详情路由
│   │   │   │   └── __tests__/  # 路由测试
│   │   │   ├── roles/          # 角色管理路由
│   │   │   └── __integration_tests__/  # 集成测试
│   │   ├── modules/            # 业务模块
│   │   │   ├── auth/           # 认证业务模块
│   │   │   │   ├── auth.service.ts # 认证服务
│   │   │   │   └── __tests__/  # 认证测试
│   │   │   ├── users/          # 用户业务模块
│   │   │   │   ├── user.entity.ts  # 用户实体
│   │   │   │   ├── user.service.ts # 用户服务
│   │   │   │   └── __tests__/  # 用户测试
│   │   ├── utils/              # 工具层
│   │   │   ├── generic-crud.service.ts  # 通用CRUD服务
│   │   │   ├── generic-crud.routes.ts   # 通用CRUD路由
│   │   │   ├── errorHandler.ts # 错误处理
│   │   │   ├── backup.ts       # 数据库备份工具
│   │   │   ├── restore.ts      # 数据库恢复工具
│   │   │   ├── logger.ts       # 日志工具
│   │   │   └── __tests__/      # 工具测试
│   │   ├── middleware/         # 中间件层
│   │   │   ├── auth.middleware.ts        # 认证中间件
│   │   │   └── permission.middleware.ts  # 权限中间件
│   │   ├── types/             # 类型定义
│   │   ├── data-source.ts     # 数据库连接配置
│   │   └── index.ts           # 服务器入口
│   └── share/                  # 前后端共享代码
│       └── types.ts           # TypeScript类型定义
├── tests/
│   └── e2e/                    # E2E测试 (Playwright)
└── package.json

集成指南

• 文件命名: 保持现有kebab-case命名约定
• 文件夹组织: 遵循功能模块划分，添加tests文件夹
• 测试结构: 单元测试位于__tests__/目录，集成测试位于__integration_tests__/目录
• 导入/导出模式: 使用ES模块，保持现有别名系统（@/）
• 测试位置: 前端集成测试位于__integration_tests__/，页面单元测试位于__tests__/
• 后端测试: API测试位于路由__tests__/目录，服务测试位于模块__tests__/目录
• 工具测试: 通用工具测试位于utils/__tests__/目录