docs: complete documentation system (250+ files)
- System architecture and design documentation - Business module docs (ASL/AIA/PKB/RVW/DC/SSA/ST) - ASL module complete design (quality assurance, tech selection) - Platform layer and common capabilities docs - Development standards and API specifications - Deployment and operations guides - Project management and milestone tracking - Architecture implementation reports - Documentation templates and guides
This commit is contained in:
568
docs/00-系统总体设计/07-Monorepo架构评估.md
Normal file
568
docs/00-系统总体设计/07-Monorepo架构评估.md
Normal file
@@ -0,0 +1,568 @@
|
||||
# Monorepo架构评估 - 当前阶段是否需要？
|
||||
|
||||
> **文档版本：** v1.0
|
||||
> **创建日期：** 2025-11-06
|
||||
> **文档目的：** 评估当前阶段采用Monorepo架构的必要性和成本
|
||||
|
||||
---
|
||||
|
||||
## 🤔 核心问题
|
||||
|
||||
1. 当前阶段需要使用Monorepo架构吗？
|
||||
2. 对当前阶段的成本高吗？
|
||||
3. 什么时候是最佳时机？
|
||||
|
||||
---
|
||||
|
||||
## 📊 当前项目结构分析
|
||||
|
||||
### 现有代码结构
|
||||
|
||||
```
|
||||
AIclinicalresearch/
|
||||
├── frontend/ # 前端（React + Vite）
|
||||
│ ├── src/
|
||||
│ ├── package.json
|
||||
│ └── node_modules/
|
||||
│
|
||||
├── backend/ # 后端（Node.js + Fastify）
|
||||
│ ├── src/
|
||||
│ ├── package.json
|
||||
│ └── node_modules/
|
||||
│
|
||||
├── extraction_service/ # Python文档提取服务
|
||||
│ ├── main.py
|
||||
│ ├── requirements.txt
|
||||
│ └── venv/
|
||||
│
|
||||
├── docker-compose.yml # Docker配置
|
||||
└── ...
|
||||
```
|
||||
|
||||
**当前特点：**
|
||||
- ✅ 结构简单，易于理解
|
||||
- ✅ 前后端分离，职责清晰
|
||||
- ✅ 各自独立的依赖管理
|
||||
- ❌ 没有代码共享机制
|
||||
- ❌ 重复的配置文件
|
||||
- ❌ 不支持模块独立打包
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Monorepo架构对比
|
||||
|
||||
### Monorepo结构示例
|
||||
|
||||
```
|
||||
AIclinicalresearch/
|
||||
├── packages/ # 共享包
|
||||
│ ├── platform-core/ # 平台核心（可复用）
|
||||
│ │ ├── auth/
|
||||
│ │ ├── storage/
|
||||
│ │ ├── package.json
|
||||
│ │ └── tsconfig.json
|
||||
│ │
|
||||
│ ├── capabilities-core/ # 通用能力（可复用）
|
||||
│ │ ├── llm-gateway/
|
||||
│ │ ├── document-processor/
|
||||
│ │ ├── package.json
|
||||
│ │ └── tsconfig.json
|
||||
│ │
|
||||
│ └── shared-types/ # 共享类型定义
|
||||
│ ├── src/
|
||||
│ ├── package.json
|
||||
│ └── tsconfig.json
|
||||
│
|
||||
├── apps/ # 应用
|
||||
│ ├── frontend/ # Web前端
|
||||
│ │ ├── src/
|
||||
│ │ └── package.json
|
||||
│ │
|
||||
│ ├── backend/ # Web后端
|
||||
│ │ ├── src/
|
||||
│ │ └── package.json
|
||||
│ │
|
||||
│ └── admin-frontend/ # 运营管理端（未来）
|
||||
│ ├── src/
|
||||
│ └── package.json
|
||||
│
|
||||
├── products/ # 独立产品打包（未来）
|
||||
│ ├── review-system/
|
||||
│ └── literature-system/
|
||||
│
|
||||
├── package.json # 根package.json（Workspace配置）
|
||||
├── pnpm-workspace.yaml # Workspace配置
|
||||
└── tsconfig.base.json # 共享TS配置
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💰 成本分析：现在 vs 以后
|
||||
|
||||
### 方案A：现在转换Monorepo
|
||||
|
||||
#### 成本（2-3天）
|
||||
|
||||
**Day 1：学习和设计（0.5-1天）**
|
||||
```
|
||||
学习内容：
|
||||
- pnpm workspaces 或 npm workspaces
|
||||
- 包依赖管理（workspace:*）
|
||||
- TypeScript path mapping
|
||||
- 共享配置（tsconfig, eslint等）
|
||||
|
||||
工作量：4-8小时
|
||||
难度：⭐⭐⭐ 中等
|
||||
```
|
||||
|
||||
**Day 2：重构现有代码（1天）**
|
||||
```
|
||||
任务清单：
|
||||
1. 创建packages/和apps/目录结构
|
||||
2. 移动frontend和backend到apps/
|
||||
3. 提取共享类型到packages/shared-types/
|
||||
4. 配置workspace依赖
|
||||
5. 更新import路径
|
||||
6. 测试验证
|
||||
|
||||
工作量：8小时
|
||||
难度：⭐⭐⭐ 中等
|
||||
风险：⭐⭐ 低（有回滚方案）
|
||||
```
|
||||
|
||||
**Day 3：测试和优化（0.5-1天）**
|
||||
```
|
||||
测试内容：
|
||||
- 前端启动和构建
|
||||
- 后端启动和构建
|
||||
- 依赖安装速度
|
||||
- 开发体验
|
||||
|
||||
工作量：4-8小时
|
||||
```
|
||||
|
||||
**总成本：2-3天**
|
||||
|
||||
#### 收益
|
||||
|
||||
**立即收益：**
|
||||
1. ✅ 代码共享变容易（类型定义、工具函数等）
|
||||
2. ✅ 统一的依赖管理（减少重复安装）
|
||||
3. ✅ 统一的配置（TypeScript、ESLint等）
|
||||
4. ✅ 为未来打基础
|
||||
|
||||
**未来收益：**
|
||||
1. ✅ 新增模块时，可以复用platform-core和capabilities-core
|
||||
2. ✅ 独立产品打包变简单
|
||||
3. ✅ Electron单机版开发变容易
|
||||
4. ✅ 避免未来大规模重构
|
||||
|
||||
---
|
||||
|
||||
### 方案B：继续当前结构，以后再转
|
||||
|
||||
#### 短期成本（0天）
|
||||
|
||||
**优点：**
|
||||
- ✅ 无需学习新技术
|
||||
- ✅ 无需重构代码
|
||||
- ✅ 可以立即开始ASL模块开发
|
||||
|
||||
**缺点：**
|
||||
- ❌ 代码重复（前后端类型定义、工具函数等）
|
||||
- ❌ 依赖管理分散
|
||||
- ❌ 为未来埋下技术债
|
||||
|
||||
#### 未来成本（1-2周）
|
||||
|
||||
**触发条件：**
|
||||
- 需要开发运营管理端（独立前端）
|
||||
- 需要开发独立产品包（审稿系统、AI文献）
|
||||
- 需要开发Electron单机版
|
||||
- 代码重复严重，维护困难
|
||||
|
||||
**重构成本（估算）：**
|
||||
```
|
||||
未来重构成本：
|
||||
- 学习和设计：1天（同现在）
|
||||
- 重构代码：3-5天（代码量更大）
|
||||
* 多个前端应用（Web、Admin、Electron）
|
||||
* 多个后端模块
|
||||
* 大量共享代码需要提取
|
||||
- 测试验证：2-3天
|
||||
- 修复问题：1-2天
|
||||
|
||||
总成本：7-11天
|
||||
|
||||
是现在的3-5倍！
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 对比矩阵
|
||||
|
||||
| 维度 | 方案A：现在转 | 方案B：以后转 |
|
||||
|------|-------------|-------------|
|
||||
| **立即成本** | ⭐⭐⭐ 中（2-3天） | ⭐⭐⭐⭐⭐ 零 |
|
||||
| **未来成本** | ⭐⭐⭐⭐⭐ 零 | ⭐⭐ 高（7-11天） |
|
||||
| **学习难度** | ⭐⭐⭐ 中等 | ⭐⭐⭐ 中等（延后） |
|
||||
| **风险** | ⭐⭐ 低 | ⭐⭐⭐ 中（技术债） |
|
||||
| **代码复用** | ⭐⭐⭐⭐⭐ 优秀 | ⭐⭐ 困难 |
|
||||
| **模块独立打包** | ⭐⭐⭐⭐⭐ 容易 | ⭐⭐ 困难 |
|
||||
| **团队协作** | ⭐⭐⭐⭐ 好 | ⭐⭐⭐ 一般 |
|
||||
| **开发体验** | ⭐⭐⭐⭐ 好 | ⭐⭐⭐ 一般 |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 当前阶段评估
|
||||
|
||||
### 当前项目状态
|
||||
|
||||
**已完成：**
|
||||
- ✅ 前端（React + Vite）
|
||||
- ✅ 后端（Node.js + Fastify）
|
||||
- ✅ Python文档提取服务
|
||||
- ✅ 基础功能（AIA、PKB）
|
||||
|
||||
**即将开发：**
|
||||
- ⏳ ASL模块（AI智能文献）
|
||||
- ⏳ ADMIN（运营管理端）- 独立前端应用
|
||||
|
||||
**未来规划：**
|
||||
- ⏳ DC、SSA、ST、RVW模块
|
||||
- ⏳ 独立产品包（审稿系统、AI文献）
|
||||
- ⏳ Electron单机版
|
||||
|
||||
---
|
||||
|
||||
### 是否需要Monorepo？
|
||||
|
||||
**评估标准：**
|
||||
|
||||
#### ✅ 需要 - 如果满足以下条件：
|
||||
|
||||
1. **近期（1-3个月）会开发多个独立应用**
|
||||
- ✅ 运营管理端（独立前端）
|
||||
- ✅ ASL、DC等新模块
|
||||
|
||||
2. **有代码共享需求**
|
||||
- ✅ 类型定义（User、Project等）
|
||||
- ✅ API客户端（apiClient）
|
||||
- ✅ 工具函数（日期格式化、验证等）
|
||||
|
||||
3. **未来有模块独立部署需求**
|
||||
- ✅ 审稿系统独立产品
|
||||
- ✅ AI文献独立产品
|
||||
- ✅ Electron单机版
|
||||
|
||||
4. **团队能够接受2-3天的学习和重构**
|
||||
- ✅ 学习曲线不陡峭
|
||||
- ✅ 文档和最佳实践丰富
|
||||
|
||||
#### ❌ 不需要 - 如果满足以下条件：
|
||||
|
||||
1. **只有一个前端 + 一个后端**
|
||||
- ❌ 当前已有运营管理端需求
|
||||
|
||||
2. **没有代码共享需求**
|
||||
- ❌ 已有大量重复代码（类型定义等）
|
||||
|
||||
3. **不打算模块化和独立部署**
|
||||
- ❌ 已规划模块独立销售
|
||||
|
||||
4. **团队完全没有时间学习新技术**
|
||||
- ⚠️ 只需2-3天
|
||||
|
||||
---
|
||||
|
||||
## 💡 我的建议
|
||||
|
||||
### 建议：现在转换Monorepo ⭐⭐⭐⭐ **推荐**
|
||||
|
||||
**理由：**
|
||||
|
||||
**1. 投入产出比极高**
|
||||
```
|
||||
投入：2-3天
|
||||
节省：未来7-11天（节省5-8天）
|
||||
ROI：300%+
|
||||
```
|
||||
|
||||
**2. 正处于最佳时机**
|
||||
```
|
||||
当前：
|
||||
- 代码量适中（不多不少）
|
||||
- 即将开发多个新模块
|
||||
- 团队小，沟通成本低
|
||||
|
||||
未来：
|
||||
- 代码量大（重构困难）
|
||||
- 多个应用同时运行
|
||||
- 重构影响范围大
|
||||
```
|
||||
|
||||
**3. 符合未来需求**
|
||||
```
|
||||
近期需求（3个月内）：
|
||||
- ✅ 运营管理端（独立前端）
|
||||
- ✅ 多个业务模块（ASL、DC等）
|
||||
- ✅ 代码共享（类型、工具函数）
|
||||
|
||||
未来需求（6-12个月）：
|
||||
- ✅ 独立产品打包
|
||||
- ✅ Electron单机版
|
||||
- ✅ 微服务拆分
|
||||
```
|
||||
|
||||
**4. 学习成本不高**
|
||||
```
|
||||
Monorepo工具：
|
||||
- pnpm workspaces（推荐，最简单）
|
||||
- npm workspaces（内置，无需安装）
|
||||
- yarn workspaces（成熟）
|
||||
|
||||
学习资源：
|
||||
- ✅ 官方文档完善
|
||||
- ✅ 社区最佳实践丰富
|
||||
- ✅ AI助手（我）可以全程指导
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 如果必须选择方案B
|
||||
|
||||
**最低要求：**
|
||||
|
||||
**1. 建立代码共享机制**
|
||||
```typescript
|
||||
// 创建共享目录
|
||||
shared/
|
||||
├── types/ # 共享类型定义
|
||||
│ ├── user.ts
|
||||
│ ├── project.ts
|
||||
│ └── index.ts
|
||||
│
|
||||
└── utils/ # 共享工具函数
|
||||
├── date.ts
|
||||
├── validation.ts
|
||||
└── index.ts
|
||||
|
||||
// 前后端引用
|
||||
import { User } from '../../shared/types';
|
||||
```
|
||||
|
||||
**2. 统一配置文件**
|
||||
```
|
||||
tsconfig.base.json # 共享TS配置
|
||||
.eslintrc.shared.js # 共享ESLint配置
|
||||
```
|
||||
|
||||
**3. 严格的代码规范**
|
||||
```
|
||||
- 禁止复制粘贴代码
|
||||
- 强制使用共享类型
|
||||
- 定期代码审查
|
||||
```
|
||||
|
||||
**触发Monorepo转换的信号：**
|
||||
- 开始开发运营管理端
|
||||
- 代码重复超过3处
|
||||
- 新增第3个应用
|
||||
|
||||
---
|
||||
|
||||
## 🚀 实施方案（如果选择转换）
|
||||
|
||||
### 阶段一：准备（半天）
|
||||
|
||||
**学习pnpm workspaces：**
|
||||
```bash
|
||||
# 1. 安装pnpm（如果没有）
|
||||
npm install -g pnpm
|
||||
|
||||
# 2. 阅读文档（30分钟）
|
||||
https://pnpm.io/workspaces
|
||||
|
||||
# 3. 看示例项目（30分钟）
|
||||
```
|
||||
|
||||
**设计目录结构：**
|
||||
```
|
||||
决定：
|
||||
- packages/ 放什么？（shared-types、platform-core等）
|
||||
- apps/ 放什么？（frontend、backend、admin-frontend）
|
||||
- 是否需要products/？（暂时不需要）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 阶段二：重构（1-1.5天）
|
||||
|
||||
**Step 1：创建基础结构**
|
||||
```bash
|
||||
# 1. 创建根package.json
|
||||
pnpm init
|
||||
|
||||
# 2. 创建pnpm-workspace.yaml
|
||||
cat > pnpm-workspace.yaml << EOF
|
||||
packages:
|
||||
- 'packages/*'
|
||||
- 'apps/*'
|
||||
EOF
|
||||
|
||||
# 3. 创建目录
|
||||
mkdir -p packages/shared-types
|
||||
mkdir -p apps
|
||||
```
|
||||
|
||||
**Step 2：移动现有代码**
|
||||
```bash
|
||||
# 移动frontend
|
||||
mv frontend apps/frontend
|
||||
|
||||
# 移动backend
|
||||
mv backend apps/backend
|
||||
|
||||
# extraction_service保持原位（Python不需要Monorepo）
|
||||
```
|
||||
|
||||
**Step 3：提取共享代码**
|
||||
```bash
|
||||
# 创建shared-types包
|
||||
cd packages/shared-types
|
||||
pnpm init
|
||||
# 移动类型定义
|
||||
```
|
||||
|
||||
**Step 4：配置依赖**
|
||||
```json
|
||||
// apps/frontend/package.json
|
||||
{
|
||||
"dependencies": {
|
||||
"@yizhengxun/shared-types": "workspace:*"
|
||||
}
|
||||
}
|
||||
|
||||
// apps/backend/package.json
|
||||
{
|
||||
"dependencies": {
|
||||
"@yizhengxun/shared-types": "workspace:*"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Step 5：更新import**
|
||||
```typescript
|
||||
// 修改前
|
||||
import { User } from '../types/user';
|
||||
|
||||
// 修改后
|
||||
import { User } from '@yizhengxun/shared-types';
|
||||
```
|
||||
|
||||
**Step 6：安装依赖**
|
||||
```bash
|
||||
# 根目录执行（会安装所有包的依赖）
|
||||
pnpm install
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 阶段三：测试验证（半天）
|
||||
|
||||
**测试清单：**
|
||||
- [ ] 前端启动正常（`cd apps/frontend && pnpm dev`）
|
||||
- [ ] 后端启动正常（`cd apps/backend && pnpm dev`）
|
||||
- [ ] 类型提示正常（VSCode智能提示）
|
||||
- [ ] 构建成功（`pnpm build`）
|
||||
- [ ] 所有功能正常
|
||||
|
||||
**回滚方案：**
|
||||
```bash
|
||||
# 如果出现问题，可以立即回滚
|
||||
git reset --hard HEAD
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 总结对比
|
||||
|
||||
### 立即转换 vs 延后转换
|
||||
|
||||
| 项目 | 立即转换 | 延后转换 |
|
||||
|------|---------|---------|
|
||||
| **时间成本** | 2-3天 | 未来7-11天 |
|
||||
| **学习成本** | 中等 | 中等（延后） |
|
||||
| **风险** | 低 | 中（技术债） |
|
||||
| **代码质量** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
|
||||
| **开发效率** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
|
||||
| **未来扩展** | ⭐⭐⭐⭐⭐ | ⭐⭐ |
|
||||
| **投入产出比** | ⭐⭐⭐⭐⭐ | ⭐⭐ |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 最终建议
|
||||
|
||||
### 推荐方案：立即转换Monorepo ⭐⭐⭐⭐⭐
|
||||
|
||||
**核心理由：**
|
||||
1. ✅ **投入小，收益大**：2-3天换来未来5-8天的节省
|
||||
2. ✅ **正处于最佳时机**：代码量适中，即将开发多模块
|
||||
3. ✅ **符合未来规划**：运营管理端、独立产品包、Electron单机版
|
||||
4. ✅ **学习成本可控**：有AI全程指导，有详细文档
|
||||
|
||||
**实施计划：**
|
||||
```
|
||||
本周：Monorepo重构（2-3天）
|
||||
Day 1：学习 + 设计（半天）
|
||||
Day 2：重构实施（1天）
|
||||
Day 3：测试验证（半天）
|
||||
|
||||
下周：继续ASL模块开发
|
||||
- 享受Monorepo带来的便利
|
||||
- 代码复用变简单
|
||||
- 类型共享开箱即用
|
||||
```
|
||||
|
||||
**如果您决定采纳，我可以：**
|
||||
1. ✅ 提供详细的step-by-step指导
|
||||
2. ✅ 帮您设计目录结构
|
||||
3. ✅ 编写配置文件
|
||||
4. ✅ 协助重构和测试
|
||||
|
||||
---
|
||||
|
||||
### 替代方案：延后转换（不推荐）
|
||||
|
||||
**如果时间确实紧迫：**
|
||||
|
||||
**最低要求：**
|
||||
1. ✅ 创建`shared/`目录存放共享代码
|
||||
2. ✅ 制定代码复用规范
|
||||
3. ✅ 在开发运营管理端前必须转换
|
||||
|
||||
**触发条件：**
|
||||
- 开始开发运营管理端
|
||||
- 代码重复严重
|
||||
- 团队成员抱怨
|
||||
|
||||
---
|
||||
|
||||
**您觉得呢？** 😊
|
||||
|
||||
是否愿意投入2-3天，为未来节省5-8天？
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user