mini-starter/docs/architecture/monorepo.md

Monorepo 架构文档

概述

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

技术选型

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

工作空间配置

pnpm-workspace.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

构建策略

并行构建

# 使用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. 添加构建脚本

包间依赖

{
  "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核心数

故障排查

依赖问题

# 重新安装依赖
rm -rf node_modules .pnpm-store
pnpm install

构建缓存清理

# 清除Turbo缓存
rm -rf .turbo

# 重新构建
pnpm build

包链接问题

# 检查包依赖关系
pnpm list --depth 0

相关文档

• 模块组织结构
• 开发规范