# 源码树和文件组织

## 版本信息
| 版本 | 日期 | 描述 | 作者 |
|------|------|------|------|
| 4.0 | 2026-01-02 | 根据实际项目结构更新：删除不存在的目录，添加新包 | James (Claude Code) |
| 3.3 | 2025-12-26 | 更新完整项目结构，包含allin-packages和mini-ui-packages | James |
| 3.2 | 2025-11-11 | 更新包结构，添加基础设施和业务模块包 | Winston |
| 3.1 | 2025-11-09 | 更新测试结构，清理重复测试文件 | James |
| 3.0 | 2025-10-22 | 更新为 monorepo 结构，添加 packages/server | Winston |

## 实际项目结构
```text
186-175-template-6/
├── .bmad-core/                      # BMad框架配置目录
│   ├── agents/                      # 代理配置
│   ├── agent-teams/                 # 团队配置
│   ├── checklists/                  # 检查清单
│   ├── data/                        # 知识库数据
│   ├── tasks/                       # 任务定义
│   ├── templates/                   # 模板文件
│   ├── workflows/                   # 工作流定义
│   └── core-config.yaml             # 核心配置文件
├── .claude/                         # Claude CLI配置
│   └── commands/                    # Claude命令定义
├── .gitea/                          # Gitea配置
├── .github/                         # GitHub Actions配置
│   └── workflows/                   # CI/CD工作流
├── .git/                            # Git版本控制
├── .roo/                            # Roo配置
├── docs/                            # 项目文档目录
│   ├── architecture/                # 架构文档（分片）
│   │   ├── coding-standards.md      # 编码标准和测试策略
│   │   ├── source-tree.md           # 源码树和文件组织（本文件）
│   │   ├── tech-stack.md            # 技术栈
│   │   └── ui-package-standards.md  # UI包开发规范
│   ├── prd/                         # 产品需求文档（分片）
│   ├── stories/                     # 用户故事文档
│   ├── architecture.md              # 架构总览
│   ├── brief.md                     # 项目简述
│   ├── development.md               # 开发指南
│   ├── error-handling.md            # 错误处理
│   ├── integration-testing-best-practices.md  # 集成测试最佳实践
│   ├── prd.md                       # PRD文档
│   └── ui-architecture.md           # UI架构
├── mini/                            # 商户小程序项目 (Taro + React)
│   ├── src/
│   │   ├── app.tsx                  # 小程序入口
│   │   ├── app.config.ts            # 小程序配置
│   │   ├── api/                     # API目录
│   │   ├── api.ts                   # API客户端
│   │   ├── app.css                  # 全局样式
│   │   ├── components/              # 组件目录
│   │   ├── contexts/                # React Context
│   │   ├── layouts/                 # 布局组件
│   │   ├── pages/                   # 页面目录
│   │   │   ├── address-edit/        # 地址编辑
│   │   │   ├── address-manage/      # 地址管理
│   │   │   ├── cart/                # 购物车
│   │   │   ├── category/            # 分类
│   │   │   ├── explore/             # 探索
│   │   │   ├── goods-detail/        # 商品详情
│   │   │   ├── goods-list/          # 商品列表
│   │   │   ├── index/               # 首页
│   │   │   ├── login/               # 登录
│   │   │   ├── order-detail/        # 订单详情
│   │   │   ├── order-list/          # 订单列表
│   │   │   ├── order-submit/        # 提交订单
│   │   │   ├── payment/             # 支付
│   │   │   ├── payment-success/     # 支付成功
│   │   │   ├── profile/             # 个人资料
│   │   │   ├── register/            # 注册
│   │   │   ├── search/              # 搜索
│   │   │   └── search-result/       # 搜索结果
│   │   ├── schemas/                 # 验证模式
│   │   └── utils/                   # 工具函数
│   ├── config/                      # 配置目录
│   │   ├── dev.ts                   # 开发环境配置
│   │   ├── index.ts                 # 配置入口
│   │   └── prod.ts                  # 生产环境配置
│   ├── tests/                       # 测试文件
│   ├── dist/                        # 构建输出
│   ├── tdesign/                     # TDesign组件库
│   └── package.json
├── mini-ui-packages/                # 小程序UI组件包目录
│   ├── mini-charts/                 # 小程序图表组件
│   ├── mini-shared-ui-components/   # 共享UI组件
│   ├── mini-testing-utils/          # 测试工具
│   ├── rencai-attendance-ui/        # 人才考勤UI
│   ├── rencai-auth-ui/              # 人才认证UI
│   ├── rencai-dashboard-ui/         # 人才仪表盘UI
│   ├── rencai-employment-ui/        # 人才就业UI
│   ├── rencai-personal-info-ui/     # 人才个人信息UI
│   ├── rencai-settings-ui/          # 人才设置UI
│   └── rencai-shared-ui/            # 人才共享UI
├── packages/                        # 核心共享包目录
│   # ==================== UI管理包 ====================
│   ├── advertisement-management-ui/         # 广告管理UI
│   ├── advertisement-management-ui-mt/      # 广告管理UI（多租户）
│   ├── advertisement-type-management-ui/    # 广告类型管理UI
│   ├── advertisement-type-management-ui-mt/ # 广告类型管理UI（多租户）
│   ├── area-management-ui/                  # 区域管理UI
│   ├── area-management-ui-mt/               # 区域管理UI（多租户）
│   ├── auth-management-ui/                  # 认证管理UI
│   ├── auth-management-ui-mt/               # 认证管理UI（多租户）
│   ├── credit-balance-management-ui-mt/     # 余额管理UI（多租户）
│   ├── data-overview-ui-mt/                 # 数据概览UI（多租户）
│   ├── delivery-address-management-ui/      # 收货地址管理UI
│   ├── delivery-address-management-ui-mt/   # 收货地址管理UI（多租户）
│   ├── feie-printer-management-ui-mt/       # 飞鹅打印管理UI（多租户）
│   ├── file-management-ui/                  # 文件管理UI
│   ├── file-management-ui-mt/               # 文件管理UI（多租户）
│   ├── goods-category-management-ui/        # 商品类别管理UI
│   ├── goods-category-management-ui-mt/     # 商品类别管理UI（多租户）
│   ├── goods-management-ui/                 # 商品管理UI
│   ├── goods-management-ui-mt/              # 商品管理UI（多租户）
│   ├── merchant-management-ui/              # 商户管理UI
│   ├── merchant-management-ui-mt/           # 商户管理UI（多租户）
│   ├── order-management-ui/                 # 订单管理UI
│   ├── order-management-ui-mt/              # 订单管理UI（多租户）
│   ├── supplier-management-ui/              # 供应商管理UI
│   ├── supplier-management-ui-mt/           # 供应商管理UI（多租户）
│   ├── system-config-management-ui-mt/      # 系统配置管理UI（多租户）
│   ├── tenant-management-ui/                # 租户管理UI
│   ├── user-management-ui/                  # 用户管理UI
│   └── user-management-ui-mt/               # 用户管理UI（多租户）
│   # ==================== 业务模块包 ====================
│   ├── advertisements-module/               # 广告模块
│   ├── advertisements-module-mt/            # 广告模块（多租户）
│   ├── auth-module/                         # 认证模块
│   ├── auth-module-mt/                      # 认证模块（多租户）
│   ├── core-module-mt/                      # 核心模块（多租户）
│   ├── credit-balance-module-mt/            # 余额模块（多租户）
│   ├── data-overview-module-mt/             # 数据概览模块（多租户）
│   ├── delivery-address-module/             # 收货地址模块
│   ├── delivery-address-module-mt/          # 收货地址模块（多租户）
│   ├── feie-printer-module-mt/              # 飞鹅打印模块（多租户）
│   ├── file-module/                         # 文件管理模块
│   ├── file-module-mt/                      # 文件管理模块（多租户）
│   ├── geo-areas/                           # 地理区域模块
│   ├── geo-areas-mt/                        # 地理区域模块（多租户）
│   ├── goods-category-module/               # 商品类别模块
│   ├── goods-category-module-mt/            # 商品类别模块（多租户）
│   ├── goods-module/                        # 商品模块
│   ├── goods-module-mt/                     # 商品模块（多租户）
│   ├── merchant-module/                     # 商户模块
│   ├── merchant-module-mt/                  # 商户模块（多租户）
│   ├── mini-payment/                        # 小程序支付模块
│   ├── mini-payment-mt/                     # 小程序支付模块（多租户）
│   ├── orders-module/                       # 订单模块
│   ├── orders-module-mt/                    # 订单模块（多租户）
│   ├── supplier-module/                     # 供应商模块
│   ├── supplier-module-mt/                  # 供应商模块（多租户）
│   ├── tenant-module-mt/                    # 租户模块（多租户）
│   ├── user-module/                         # 用户管理模块
│   └── user-module-mt/                      # 用户管理模块（多租户）
│   # ==================== 共享基础设施包 ====================
│   ├── shared-crud/                         # 通用CRUD基础设施
│   ├── shared-test-util/                    # 测试基础设施
│   ├── shared-types/                        # 共享类型定义
│   ├── shared-ui-components/                # 共享UI组件
│   ├── shared-utils/                        # 共享工具函数
│   # ==================== 服务器包 ====================
│   └── server/                              # API服务器包
├── scripts/                                 # 脚本文件目录
├── tcb-shop-demo/                           # TCB商城演示
├── web/                                     # Web管理后台 (Vite + React)
│   ├── src/
│   │   ├── assets/                          # 静态资源
│   │   ├── client/                          # 客户端代码
│   │   ├── server/                          # 服务器端代码
│   │   ├── share/                           # 共享代码
│   │   └── style.css                        # 全局样式
│   ├── tests/
│   │   ├── e2e/                             # E2E测试 (Playwright)
│   │   ├── integration/                     # 集成测试
│   │   └── unit/                            # 单元测试
│   ├── public/                              # 公共资源
│   └── package.json
├── .ai/                                     # AI辅助目录
├── .eslintrc                                # ESLint配置
├── .gitignore                               # Git忽略文件
├── .npmrc                                   # NPM配置
├── CLAUDE.md                                # Claude开发指南
├── Dockerfile                               # Docker配置
├── cloudflared-config.yml                   # Cloudflared配置
├── debug-print-task-issue.js                # 调试脚本
├── debug-print-task.js                      # 调试脚本
├── debug-simple.js                          # 调试脚本
├── fix-config-issue.js                      # 修复脚本
├── fix-delay-scheduler.js                   # 修复脚本
├── fix-delay-simple.js                      # 修复脚本
├── fix-scheduler-autostart.js               # 修复脚本
├── package.json                             # 根项目配置
├── pnpm-lock.yaml                           # 依赖锁定文件
├── pnpm-workspace.yaml                      # pnpm workspace配置
├── screenshot.js                            # 截图脚本
├── system_config_mt_tenant1_insert.sql      # 系统配置SQL
├── test-log-cjs.cjs                         # 测试脚本
├── test-log-fix.js                          # 测试脚本
├── test-log-simple.js                       # 测试脚本
├── test-print-task-log.js                   # 测试脚本
├── test-user-consumption.js                 # 测试脚本
├── test_schema.js                           # Schema测试
└── tsconfig.json                            # TypeScript配置
```

## 项目结构概览

### 主要目录分类

| 目录 | 用途 | 技术栈 |
|------|------|--------|
| `mini/` | 商户小程序 | Taro + React |
| `mini-ui-packages/` | 小程序UI组件包 | React + Taro |
| `web/` | Web管理后台 | Vite + React |
| `packages/` | 核心共享包 | Node.js + TypeScript |
| `docs/` | 项目文档 | Markdown |

### 包架构层次

```
基础设施层:
  └── shared-types → shared-utils → shared-crud → shared-test-util

业务模块层:
  └── user-module → auth-module → file-module → geo-areas
  └── goods-module → orders-module → merchant-module
  └── mini-payment
  └── (多租户版本: *-mt)

UI展示层:
  └── user-management-ui → auth-management-ui → file-management-ui
  └── (多租户版本: *-ui-mt)

应用层:
  └── server (API服务器)
  └── web (Web管理后台)
  └── mini (商户小程序)
```

### 集成指南

- **文件命名**: 保持现有kebab-case命名约定
- **项目结构**: 采用monorepo模式，使用pnpm workspace管理多包依赖关系
- **包管理**: 核心包在`packages/`，小程序UI组件在`mini-ui-packages/`
- **小程序架构**: 基于Taro框架，使用TDesign组件库
- **Web应用架构**: 基于Vite + React，使用shadcn/ui组件库
- **模块化架构**: 采用分层包结构，支持按需安装和独立开发
- **多租户支持**: 核心模块和UI包都有对应的多租户版本（`-mt`后缀）
- **API设计**: 使用Hono框架，RESTful API设计
- **数据库**: 使用PostgreSQL + TypeORM
- **存储**: 使用MinIO进行文件存储
- **测试结构**:
  - **基础设施包**: 每个包独立的单元测试和集成测试
  - **业务模块包**: 每个模块包含完整的测试套件
  - **server包**: 集成测试验证模块间协作
  - **web应用**: 组件测试、集成测试和E2E测试
  - **mini应用**: Jest单元测试
- **开发环境**: 多八多云端开发容器，包含Node.js 20.19.2、PostgreSQL 17、Redis 7、MinIO
- **构建工具**: 使用Vite + pnpm

### 架构优势

- 清晰的模块边界和职责分离
- 支持按需安装，减少包体积
- 基础设施和业务逻辑分离
- 统一的测试模式和工具
- 更好的代码复用和维护性
- 独立的包版本管理
- 支持多租户架构
- 小程序UI组件复用（rencai系列）
