# src 目录整理设计

## 概述

本设计旨在优化 koa3-demo 项目的 src 目录结构，在保持现有 MVC 架构不变的前提下，通过最小化的代码改动来提升代码组织的清晰度和可维护性。

## 当前目录结构分析

### 现状问题
- 目录层级较为扁平，业务模块分散
- controllers 按类型（Api/Page）分组，但缺乏按业务领域组织
- services 和 models 分离在不同的顶级目录
- 缺乏统一的模块组织规范

### 优势保持
- MVC 架构清晰，分层明确
- 中间件系统完善
- 路由自动发现机制完整
- 数据库操作层设计合理

## 整理方案

### 目标架构

采用**领域驱动的模块化架构**，在保持 MVC 分层的同时，按业务领域组织代码：

```mermaid
graph TB
    subgraph "src 目录结构"
        A[src/] --> B[app/]
        A --> C[modules/]
        A --> D[shared/]
        A --> E[presentation/]
        
        B --> B1[config/]
        B --> B2[providers/]
        B --> B3[bootstrap/]
        
        C --> C1[auth/]
        C --> C2[article/]
        C --> C3[user/]
        C --> C4[site-config/]
        
        D --> D1[utils/]
        D --> D2[constants/]
        D --> D3[helpers/]
        
        E --> E1[middlewares/]
        E --> E2[routes/]
        E --> E3[views/]
        
        subgraph "模块内部结构"
            C1 --> C1A[controllers/]
            C1 --> C1B[services/]
            C1 --> C1C[models/]
            C1 --> C1D[validators/]
        end
    end
```

### 详细目录规划

#### 1. app/ - 应用核心
```
app/
├── config/          # 配置管理
│   ├── index.js     # 当前 src/config/index.js
│   └── database.js  # 数据库配置（从 db/ 提取）
├── providers/       # 服务提供者
│   ├── DatabaseProvider.js   # 数据库连接管理
│   └── index.js     # 提供者注册
└── bootstrap/       # 应用引导
    ├── app.js       # 应用实例（当前 global.js）
    ├── logger.js    # 日志配置
    └── index.js     # 引导入口
```

#### 2. modules/ - 业务模块
```
modules/
├── auth/            # 认证模块
│   ├── controllers/
│   │   ├── AuthController.js      # API 控制器
│   │   └── AuthPageController.js  # 页面控制器
│   ├── services/
│   │   └── AuthService.js         # 从 userService.js 提取认证相关
│   ├── models/
│   │   └── UserModel.js           # 用户模型
│   └── validators/
│       └── AuthValidator.js       # 认证验证规则
├── user/            # 用户管理模块
│   ├── controllers/
│   │   └── ProfileController.js   # 用户资料控制器
│   ├── services/
│   │   └── UserService.js         # 用户业务服务
│   └── models/
│       └── UserModel.js           # 用户模型（共享）
├── article/         # 文章管理模块
│   ├── controllers/
│   │   └── ArticleController.js
│   ├── services/
│   │   └── ArticleService.js
│   └── models/
│       └── ArticleModel.js
├── bookmark/        # 书签管理模块
│   ├── services/
│   │   └── BookmarkService.js
│   └── models/
│       └── BookmarkModel.js
├── site-config/     # 站点配置模块
│   ├── services/
│   │   └── SiteConfigService.js
│   └── models/
│       └── SiteConfigModel.js
└── common/          # 通用模块
    ├── controllers/
    │   ├── ApiController.js
    │   ├── StatusController.js
    │   └── UploadController.js
    └── services/
        └── JobService.js
```

#### 3. shared/ - 共享资源
```
shared/
├── utils/           # 工具函数
│   ├── error/
│   ├── router/
│   ├── bcrypt.js
│   ├── helper.js
│   └── scheduler.js
├── constants/       # 常量定义
│   ├── errors.js
│   └── status.js
└── base/            # 基础类
    ├── BaseController.js
    ├── BaseService.js
    └── BaseModel.js
```

#### 4. presentation/ - 表现层
```
presentation/
├── middlewares/     # 中间件（当前 middlewares/）
├── routes/          # 路由管理
│   ├── api.js       # API 路由
│   ├── web.js       # 页面路由
│   └── index.js     # 路由注册
└── views/           # 视图模板（当前 views/）
```

#### 5. infrastructure/ - 基础设施
```
infrastructure/
├── database/        # 数据库相关
│   ├── migrations/  # 迁移文件
│   ├── seeds/       # 种子数据
│   ├── docs/        # 数据库文档
│   └── index.js     # 数据库连接
└── jobs/            # 定时任务
    ├── exampleJob.js
    └── index.js
```

## 迁移策略

### 阶段一：创建新目录结构
1. 创建 `app/`, `modules/`, `shared/`, `presentation/`, `infrastructure/` 目录
2. 建立各模块的子目录结构

### 阶段二：文件迁移与重组
1. **配置文件迁移**
   - `config/` → `app/config/`
   - 从 `db/index.js` 提取数据库配置到 `app/config/database.js`

2. **核心文件重组**
   - `global.js` → `app/bootstrap/app.js`
   - `logger.js` → `app/bootstrap/logger.js`
   - 创建 `app/bootstrap/index.js` 统一引导

3. **业务模块化**
   - 按业务领域创建模块目录
   - 将相关的 controllers, services, models 组织到对应模块

4. **基础设施迁移**
   - `db/` → `infrastructure/database/`
   - `jobs/` → `infrastructure/jobs/`
   - `middlewares/` → `presentation/middlewares/`
   - `views/` → `presentation/views/`

### 阶段三：更新引用路径
1. 更新 `main.js` 中的导入路径
2. 更新中间件注册路径
3. 更新服务间的依赖引用
4. 更新路由自动发现配置

## 实现细节

### 模块内 MVC 组织

每个业务模块内部采用标准的 MVC 分层：

```mermaid
graph LR
    subgraph "auth 模块"
        AC[AuthController] --> AS[AuthService]
        AS --> UM[UserModel]
        APC[AuthPageController] --> AS
    end
    
    subgraph "共享层"
        BC[BaseController]
        BS[BaseService] 
        BM[BaseModel]
    end
    
    AC -.-> BC
    AS -.-> BS
    UM -.-> BM
```

### 路径映射表

| 当前路径 | 新路径 | 说明 |
|---------|-------|------|
| `src/config/` | `src/app/config/` | 配置管理 |
| `src/global.js` | `src/app/bootstrap/app.js` | 应用实例 |
| `src/logger.js` | `src/app/bootstrap/logger.js` | 日志配置 |
| `src/controllers/Api/AuthController.js` | `src/modules/auth/controllers/AuthController.js` | 认证API控制器 |
| `src/controllers/Page/AuthPageController.js` | `src/modules/auth/controllers/AuthPageController.js` | 认证页面控制器 |
| `src/services/userService.js` | `src/modules/auth/services/AuthService.js` + `src/modules/user/services/UserService.js` | 拆分认证和用户服务 |
| `src/db/models/UserModel.js` | `src/modules/auth/models/UserModel.js` | 用户模型 |
| `src/middlewares/` | `src/presentation/middlewares/` | 中间件 |
| `src/views/` | `src/presentation/views/` | 视图模板 |
| `src/db/migrations/` | `src/infrastructure/database/migrations/` | 数据库迁移 |
| `src/jobs/` | `src/infrastructure/jobs/` | 定时任务 |

### 导入路径更新

#### main.js 更新示例
```javascript
// 原始导入
import { app } from "./global"
import { logger } from "./logger.js"
import "./jobs/index.js"
import LoadMiddlewares from "./middlewares/install.js"

// 更新后导入
import { app } from "./app/bootstrap/app.js"
import { logger } from "./app/bootstrap/logger.js" 
import "./infrastructure/jobs/index.js"
import LoadMiddlewares from "./presentation/middlewares/install.js"
```

### 自动路由发现适配

更新路由扫描配置以适配新的模块结构：

```javascript
// 扫描路径配置
const scanPaths = [
    'src/modules/*/controllers/**/*.js',
    'src/modules/common/controllers/**/*.js'
];
```

## 文件操作清单

### 需要移动的文件
- [ ] `src/config/` → `src/app/config/`
- [ ] `src/global.js` → `src/app/bootstrap/app.js`
- [ ] `src/logger.js` → `src/app/bootstrap/logger.js`
- [ ] `src/db/` → `src/infrastructure/database/`
- [ ] `src/jobs/` → `src/infrastructure/jobs/`
- [ ] `src/middlewares/` → `src/presentation/middlewares/`
- [ ] `src/views/` → `src/presentation/views/`
- [ ] `src/utils/` → `src/shared/utils/`

### 需要按模块重组的文件
- [ ] 认证相关：`AuthController.js`, `AuthPageController.js`, `userService.js`(部分), `UserModel.js`
- [ ] 用户管理：`ProfileController.js`, `userService.js`(部分)
- [ ] 文章管理：`ArticleController.js`, `ArticleService.js`, `ArticleModel.js`
- [ ] 书签管理：`BookmarkService.js`, `BookmarkModel.js`
- [ ] 站点配置：`SiteConfigService.js`, `SiteConfigModel.js`
- [ ] 通用功能：`ApiController.js`, `StatusController.js`, `UploadController.js`, `JobController.js`

### 需要更新导入的文件
- [ ] `src/main.js`
- [ ] `src/presentation/middlewares/install.js`
- [ ] 各个控制器文件中的服务导入
- [ ] 各个服务文件中的模型导入

## 预期效果

### 代码组织改善
1. **业务内聚性**：相关的 controller、service、model 集中在同一模块
2. **职责清晰**：每个模块负责特定的业务领域
3. **依赖明确**：模块间依赖关系更加清晰可见

### 开发体验提升
1. **文件查找**：按业务功能快速定位相关文件
2. **代码维护**：修改某个功能时，相关文件集中在一个目录
3. **团队协作**：不同开发者可以专注于不同的业务模块

### 架构扩展性
1. **新增模块**：按照统一规范快速创建新的业务模块
2. **功能拆分**：大模块可以进一步拆分成子模块
3. **微服务准备**：为将来可能的微服务拆分做好准备

## 风险评估与注意事项

### 低风险操作
- 目录创建和文件移动
- 路径引用更新
- 配置文件调整

### 需要谨慎的操作  
- 路由自动发现逻辑调整
- 中间件注册顺序维护
- 数据库连接管理迁移

### 测试验证点
1. 应用启动正常
2. 路由注册成功
3. 数据库连接正常
4. 中间件功能完整
5. 各业务模块功能正常

本方案通过最小化改动实现目录结构优化，保持原有架构优势的同时提升代码组织质量，为项目的长期维护和扩展奠定良好基础。