# Monorepo 架构文档

## 概述

本项目采用 pnpm workspaces 实现 Monorepo 架构，统一管理多个应用、模块和共享包。

## 技术选型

| 技术 | 版本 | 用途 |
|------|------|------|
| pnpm | 10.18.3 | 包管理和工作空间 |
| Turbo | - | 构建编排和缓存 |
| TypeScript | 5.9.3 | 类型安全 |
| Vite | 7.x | 构建工具 |

## 工作空间配置

### pnpm-workspace.yaml
```yaml
packages:
  - 'mini'                    # 员工小程序
  - 'mini-talent'             # 人才小程序
  - 'web'                     # 管理后台
  - 'packages/*'              # 核心包 (61个)
  - 'allin-packages/*'        # 业务模块包 (15个)
  - 'mini-ui-packages/*'      # 小程序UI包 (18个)
```

## 包分类架构

```
┌─────────────────────────────────────────────────────────────┐
│                    188-179 Monorepo                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   应用层      │  │   应用层      │  │   应用层      │     │
│  ├──────────────┤  ├──────────────┤  ├──────────────┤     │
│  │  web/        │  │  mini/       │  │  mini-talent/│     │
│  │  管理后台     │  │  员工小程序   │  │  人才小程序   │     │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘     │
│         │                 │                 │              │
│         └─────────────────┼─────────────────┘              │
│                           │                                │
│  ┌────────────────────────▼─────────────────────────────┐  │
│  │                   模块层                               │  │
│  ├─────────────────────────────────────────────────────┤  │
│  │  packages/           allin-packages/                  │  │
│  │  ├── core-module      ├── channel-module             │  │
│  │  ├── auth-module      ├── company-module             │  │
│  │  ├── user-module      ├── disability-module          │  │
│  │  ├── orders-module    ├── order-module               │  │
│  │  ├── goods-module     ├── platform-module            │  │
│  │  ├── merchant-module  ├── salary-module              │  │
│  │  └── ...              └── statistics-module          │  │
│  └─────────────────────────────────────────────────────┘  │
│                           │                                │
│  ┌────────────────────────▼─────────────────────────────┐  │
│  │                   共享层                               │  │
│  ├─────────────────────────────────────────────────────┤  │
│  │  mini-ui-packages/      packages/ 共享               │  │
│  │  ├── mini-charts        ├── shared-types             │  │
│  │  ├── mini-shared-ui     ├── shared-utils             │  │
│  │  ├── yongren-*          ├── shared-crud              │  │
│  │  ├── rencai-*           ├── shared-ui-components      │  │
│  │  └── allin-enums        └── ...                      │  │
│  └─────────────────────────────────────────────────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

## 依赖关系

### 应用依赖
```
web/           → packages/core-module, packages/shared-ui-components
mini/          → mini-ui-packages/yongren-*, packages/core-module
mini-talent/   → mini-ui-packages/rencai-*, packages/core-module
```

### 模块依赖
```
*-module       → packages/core-module, packages/shared-types
*-management-ui → packages/shared-ui-components, packages/*-module
```

### 共享依赖
```
所有包         → packages/shared-types, packages/shared-utils
```

## 包命名规范

### 后端模块包
- 格式: `<业务领域>-module`
- 示例: `auth-module`, `orders-module`, `goods-module`
- 多租户变体: `<业务领域>-module-mt`

### UI管理包
- 格式: `<业务领域>-management-ui`
- 示例: `user-management-ui`, `order-management-ui`

### 小程序UI包
- 通用组件: `mini-*`
- 员工端: `yongren-*`
- 人才端: `rencai-*`

### 共享包
- 格式: `shared-*`
- 示例: `shared-types`, `shared-utils`, `shared-crud`

## 构建策略

### 并行构建
```bash
# 使用Turbo并行构建所有包
pnpm build

# 按类别并行构建
pnpm run build:mini-ui-packages
pnpm run build:mini-ui-packages:common
pnpm run build:mini-ui-packages:yongren
pnpm run build:mini-ui-packages:rencai
```

### 构建顺序
1. **共享包优先**: shared-types → shared-utils → shared-crud
2. **核心模块**: core-module, auth-module
3. **业务模块**: 依赖核心模块的业务包
4. **UI包**: 依赖业务模块的UI组件
5. **应用**: web, mini, mini-talent

## 开发工作流

### 添加新包
1. 在对应目录创建包文件夹
2. 初始化 `package.json`
3. 更新工作空间依赖
4. 添加构建脚本

### 包间依赖
```json
{
  "name": "order-management-ui",
  "dependencies": {
    "@d8d/orders-module": "workspace:*",
    "@d8d/shared-ui-components": "workspace:*",
    "@d8d/shared-types": "workspace:*"
  }
}
```

## 多租户支持

部分模块支持多租户架构，具有独立的 `-mt` 变体：

| 单租户版本 | 多租户版本 |
|-----------|-----------|
| auth-module | auth-module-mt |
| goods-module | goods-module-mt |
| orders-module | orders-module-mt |
| user-module | user-module-mt |

多租户版本包含额外的租户隔离逻辑和数据过滤。

## 性能优化

### Turbo 缓存
- 构建缓存位于 `.turbo/` 目录
- 未变更的包使用缓存，加快构建速度

### 并行执行
- 使用 `--workspace-concurrency` 控制并行度
- 默认使用CPU核心数

## 故障排查

### 依赖问题
```bash
# 重新安装依赖
rm -rf node_modules .pnpm-store
pnpm install
```

### 构建缓存清理
```bash
# 清除Turbo缓存
rm -rf .turbo

# 重新构建
pnpm build
```

### 包链接问题
```bash
# 检查包依赖关系
pnpm list --depth 0
```

## 相关文档
- [模块组织结构](./module-structure.md)
- [开发规范](../standards/coding-standards.md)