# 接口分类重构计划

## 一、重构目标

将所有后端接口按照使用端分成四类，通过文件夹和路由前缀清晰区分：

1. **应用端 (app)** - 小程序C端用户使用的接口
2. **商家端 (merchant)** - 小程序商家端 + 商家管理后台使用的接口
3. **平台管理端 (admin)** - 平台管理后台使用的接口
4. **官网 (website)** - 官方网站使用的接口

## 二、目标目录结构

```
apps/server/src/modules/
├── app/                   # 应用端接口 (路由前缀: /api/app/*)
│   ├── auth/              # 用户认证
│   ├── profile/           # 用户资料
│   ├── order/             # 订单管理
│   ├── review/            # 评价管理
│   ├── coupon/            # 优惠券
│   ├── guest/             # 入住人管理
│   ├── activity/          # 活动/邀请
│   ├── finance/           # 钱包/提现
│   └── app.module.ts
│
├── merchant/              # 商家端接口 (路由前缀: /api/merchant/*)
│   ├── auth/              # 商家认证
│   ├── profile/           # 商家资料
│   ├── room/              # 房源管理
│   ├── room-calendar/     # 房态日历
│   ├── order/             # 订单管理
│   ├── review/            # 评价管理
│   ├── statistics/        # 数据统计
│   ├── finance/           # 财务管理
│   └── merchant.module.ts
│
├── admin/                 # 平台管理端接口 (路由前缀: /api/admin/*)
│   ├── auth/              # 管理员认证
│   ├── user/              # 用户管理
│   ├── merchant/          # 商家管理
│   ├── room/              # 房源管理
│   ├── order/             # 订单管理
│   ├── review/            # 评价管理
│   ├── coupon/            # 优惠券管理
│   ├── activity/          # 活动管理
│   ├── config/            # 系统配置
│   ├── website/           # 官网内容管理
│   ├── finance/           # 财务管理
│   │   ├── account/       # 账户管理
│   │   ├── transaction/   # 交易记录
│   │   ├── withdrawal/    # 提现管理
│   │   ├── settlement/    # 结算管理
│   │   ├── reconciliation/# 对账管理
│   │   └── report/        # 财务报表
│   └── admin.module.ts
│
├── website/               # 官网接口 (路由前缀: /api/website/*)
│   ├── info/              # 网站信息
│   ├── room/              # 房源展示（公开）
│   ├── merchant/          # 商家展示（公开）
│   └── website.module.ts
│
└── shared/                # 共享模块（不对外暴露路由）
    ├── upload/            # 文件上传
    └── config/            # 配置服务
```

## 三、接口分类详情

### 3.1 应用端接口 (48个接口)

**路由前缀**: `/api/app/*`

| 模块 | 当前路由 | 新路由 | 文件位置 |
|------|---------|--------|----------|
| 用户认证 | `/user/auth/*` | `/api/app/auth/*` | user/auth/ |
| 用户资料 | `/user/profile/*` | `/api/app/profile/*` | user/profile/ |
| 订单管理 | `/user/orders/*` | `/api/app/orders/*` | user/order/ |
| 评价管理 | `/user/reviews/*` | `/api/app/reviews/*` | user/review/ |
| 优惠券 | `/user/coupons/*` | `/api/app/coupons/*` | user/coupon/ |
| 入住人 | `/user/guests/*` | `/api/app/guests/*` | user/guest/ |
| 活动邀请 | `/user/activity/invite/*` | `/api/app/activity/*` | user/activity/ |
| 钱包财务 | `/user/finance/*` | `/api/app/finance/*` | user/finance/ |

**涉及的Controller文件**:
- `user/auth/auth.controller.ts`
- `user/profile/profile.controller.ts`
- `user/order/order.controller.ts`
- `user/review/review.controller.ts`
- `user/coupon/coupon.controller.ts`
- `user/guest/guest.controller.ts`
- `user/activity/activity.controller.ts`
- `common/finance/finance-user.controller.ts`
- `common/finance/withdrawal-user.controller.ts`
- `common/coupon/coupon-user.controller.ts`

### 3.2 商家端接口 (56个接口)

**路由前缀**: `/api/merchant/*`

| 模块 | 当前路由 | 新路由 | 文件位置 |
|------|---------|--------|----------|
| 商家认证 | `/merchant/auth/*` | `/api/merchant/auth/*` | merchant/auth/ |
| 商家资料 | `/merchant/profile/*` | `/api/merchant/profile/*` | merchant/profile/ |
| 房源管理 | `/merchant/rooms/*` | `/api/merchant/rooms/*` | merchant/room/ |
| 房态日历 | `/merchant/room-calendar/*` | `/api/merchant/room-calendar/*` | merchant/room-calendar/ |
| 订单管理 | `/merchant/orders/*` | `/api/merchant/orders/*` | merchant/order/ |
| 评价管理 | `/merchant/reviews/*` | `/api/merchant/reviews/*` | merchant/review/ |
| 数据统计 | `/merchant/statistics/*` | `/api/merchant/statistics/*` | merchant/statistics/ |
| 财务管理 | `/merchant/finance/*` | `/api/merchant/finance/*` | merchant/finance/ |

**涉及的Controller文件**:
- `merchant/auth/auth.controller.ts`
- `merchant/profile/profile.controller.ts`
- `merchant/room/room.controller.ts`
- `merchant/room-calendar/room-calendar.controller.ts`
- `merchant/order/order.controller.ts`
- `merchant/review/review.controller.ts`
- `merchant/statistics/statistics.controller.ts`
- `merchant/finance/finance.controller.ts`
- `common/finance/transaction-seller.controller.ts`
- `common/finance/withdrawal-merchant.controller.ts`
- `common/finance/settlement-merchant.controller.ts`

### 3.3 平台管理端接口 (72个接口)

**路由前缀**: `/api/admin/*`

| 模块 | 当前路由 | 新路由 | 文件位置 |
|------|---------|--------|----------|
| 管理员认证 | `/admin/auth/*` | `/api/admin/auth/*` | admin/auth/ |
| 用户管理 | `/admin/users/*` | `/api/admin/users/*` | admin/user/ |
| 商家管理 | `/admin/merchants/*` | `/api/admin/merchants/*` | admin/merchant/ |
| 房源管理 | `/admin/rooms/*` | `/api/admin/rooms/*` | admin/room/ |
| 订单管理 | `/admin/orders/*` | `/api/admin/orders/*` | admin/order/ |
| 评价管理 | `/admin/reviews/*` | `/api/admin/reviews/*` | admin/review/ |
| 优惠券管理 | `/admin/coupons/*` | `/api/admin/coupons/*` | admin/coupon/ |
| 活动管理 | `/admin/activity/*` | `/api/admin/activity/*` | admin/activity/ |
| 系统配置 | `/admin/config/*` | `/api/admin/config/*` | admin/config/ |
| 官网管理 | `/admin/website/info/*` | `/api/admin/website/*` | admin/website/ |
| 账户管理 | `/admin/finance/accounts/*` | `/api/admin/finance/accounts/*` | admin/finance/ |
| 交易记录 | `/admin/finance/transactions/*` | `/api/admin/finance/transactions/*` | admin/finance/ |
| 提现管理 | `/admin/finance/withdrawals/*` | `/api/admin/finance/withdrawals/*` | admin/finance/ |
| 结算管理 | `/admin/finance/settlements/*` | `/api/admin/finance/settlements/*` | admin/finance/ |
| 对账管理 | `/admin/finance/reconciliations/*` | `/api/admin/finance/reconciliations/*` | admin/finance/ |
| 财务报表 | `/admin/finance/reports/*` | `/api/admin/finance/reports/*` | admin/finance/ |

**涉及的Controller文件**:
- `admin/auth/auth.controller.ts`
- `admin/user/user.controller.ts`
- `admin/merchant/merchant.controller.ts`
- `admin/room/room.controller.ts`
- `admin/order/order.controller.ts`
- `admin/review/review.controller.ts`
- `admin/coupon/coupon.controller.ts`
- `admin/activity/activity.controller.ts`
- `admin/config/config.controller.ts`
- `admin/website/website.controller.ts`
- `common/finance/account-admin.controller.ts`
- `common/finance/transaction-admin.controller.ts`
- `common/finance/withdrawal-admin.controller.ts`
- `common/finance/settlement-admin.controller.ts`
- `common/finance/reconciliation-admin.controller.ts`
- `common/finance/report-admin.controller.ts`
- `common/coupon/coupon-admin.controller.ts`

### 3.4 官网接口 (12个接口)

**路由前缀**: `/api/website/*`

| 模块 | 当前路由 | 新路由 | 文件位置 |
|------|---------|--------|----------|
| 网站信息 | `/website/info/*` | `/api/website/info/*` | website/info/ |
| 房源展示 | `/public/rooms/*` | `/api/website/rooms/*` | website/room/ |
| 商家展示 | `/public/merchants/*` | `/api/website/merchants/*` | website/merchant/ |

**涉及的Controller文件**:
- `website/info/info.controller.ts`
- 需要新建: `website/room/room.controller.ts` (公开房源查询)
- 需要新建: `website/merchant/merchant.controller.ts` (公开商家查询)

## 四、执行步骤

### 步骤1: 重命名和移动目录 (30分钟)

```bash
# 1. 重命名 user 为 app
cd apps/server/src/modules
mv user app

# 2. 保持 merchant 不变

# 3. 保持 admin 不变

# 4. 保持 website 不变

# 5. 重命名 common 为 shared
mv common shared
```

### 步骤2: 移动 common 中的 controller 到对应模块 (45分钟)

#### 2.1 移动应用端相关的 controller

```bash
# 移动用户优惠券
mv shared/coupon/coupon-user.controller.ts app/coupon/
mv shared/coupon/coupon-user.service.ts app/coupon/

# 移动用户财务
mv shared/finance/finance-user.controller.ts app/finance/
mv shared/finance/withdrawal-user.controller.ts app/finance/
```

#### 2.2 移动商家端相关的 controller

```bash
# 移动商家财务
mv shared/finance/transaction-seller.controller.ts merchant/finance/
mv shared/finance/withdrawal-merchant.controller.ts merchant/finance/
mv shared/finance/settlement-merchant.controller.ts merchant/finance/
```

#### 2.3 移动平台管理端相关的 controller

```bash
# 移动管理优惠券
mv shared/coupon/coupon-admin.controller.ts admin/coupon/

# 移动管理财务
mv shared/finance/account-admin.controller.ts admin/finance/
mv shared/finance/transaction-admin.controller.ts admin/finance/
mv shared/finance/withdrawal-admin.controller.ts admin/finance/
mv shared/finance/settlement-admin.controller.ts admin/finance/
mv shared/finance/reconciliation-admin.controller.ts admin/finance/
mv shared/finance/report-admin.controller.ts admin/finance/
```

### 步骤3: 修改所有 Controller 的路由前缀 (60分钟)

使用 VS Code 全局查找替换功能 (`Ctrl+Shift+H`)：

#### 3.1 应用端路由

在 `apps/server/src/modules/app` 目录下：

```
查找: @Controller\('user/auth
替换: @Controller('api/app/auth

查找: @Controller\('user/profile
替换: @Controller('api/app/profile

查找: @Controller\('user/orders
替换: @Controller('api/app/orders

查找: @Controller\('user/reviews
替换: @Controller('api/app/reviews

查找: @Controller\('user/coupons
替换: @Controller('api/app/coupons

查找: @Controller\('user/guests
替换: @Controller('api/app/guests

查找: @Controller\('user/activity
替换: @Controller('api/app/activity

查找: @Controller\('user/finance
替换: @Controller('api/app/finance

查找: @Controller\('user
替换: @Controller('api/app
```

#### 3.2 商家端路由

在 `apps/server/src/modules/merchant` 目录下：

```
查找: @Controller\('merchant/auth
替换: @Controller('api/merchant/auth

查找: @Controller\('merchant/profile
替换: @Controller('api/merchant/profile

查找: @Controller\('merchant/rooms
替换: @Controller('api/merchant/rooms

查找: @Controller\('merchant/room-calendar
替换: @Controller('api/merchant/room-calendar

查找: @Controller\('merchant/orders
替换: @Controller('api/merchant/orders

查找: @Controller\('merchant/reviews
替换: @Controller('api/merchant/reviews

查找: @Controller\('merchant/statistics
替换: @Controller('api/merchant/statistics

查找: @Controller\('merchant/finance
替换: @Controller('api/merchant/finance

# 处理旧的 seller 前缀
查找: @Controller\('seller/
替换: @Controller('api/merchant/
```

#### 3.3 平台管理端路由

在 `apps/server/src/modules/admin` 目录下：

```
查找: @Controller\('admin/
替换: @Controller('api/admin/
```

#### 3.4 官网路由

在 `apps/server/src/modules/website` 目录下：

```
查找: @Controller\('website/
替换: @Controller('api/website/

查找: @Controller\('public/
替换: @Controller('api/website/
```

### 步骤4: 更新模块导入和注册 (45分钟)

#### 4.1 更新各模块的 module.ts 文件

需要修改的文件：
- `app/app.module.ts` (重命名自 user.module.ts)
- `merchant/merchant.module.ts`
- `admin/admin.module.ts`
- `website/website.module.ts`

#### 4.2 更新根模块 app.module.ts

```typescript
import { AppModule as AppClientModule } from './modules/app/app.module';
import { MerchantModule } from './modules/merchant/merchant.module';
import { AdminModule } from './modules/admin/admin.module';
import { WebsiteModule } from './modules/website/website.module';
import { SharedModule } from './modules/shared/shared.module';

@Module({
  imports: [
    // ... 其他配置
    AppClientModule,
    MerchantModule,
    AdminModule,
    WebsiteModule,
    SharedModule,
  ],
})
export class AppModule {}
```

### 步骤5: 更新前端 API 调用路径 (90分钟)

#### 5.1 小程序端 (apps/miniapp/src/api/)

在整个 `apps/miniapp/src/api` 目录下执行替换：

```
查找: '/user/auth/
替换: '/api/app/auth/

查找: '/user/profile
替换: '/api/app/profile

查找: '/user/orders
替换: '/api/app/orders

查找: '/user/reviews
替换: '/api/app/reviews

查找: '/user/coupons
替换: '/api/app/coupons

查找: '/user/guests
替换: '/api/app/guests

查找: '/user/activity
替换: '/api/app/activity

查找: '/user/finance
替换: '/api/app/finance

查找: '/user
替换: '/api/app

# 公开接口
查找: '/public/rooms
替换: '/api/website/rooms

查找: '/public/merchants
替换: '/api/website/merchants
```

#### 5.2 商家管理后台 (apps/merchant-admin/src/api/)

在整个 `apps/merchant-admin/src/api` 目录下执行替换：

```
查找: '/merchant/auth/
替换: '/api/merchant/auth/

查找: '/merchant/
替换: '/api/merchant/

查找: '/seller/
替换: '/api/merchant/
```

#### 5.3 平台管理后台 (apps/platform-admin/src/api/)

在整个 `apps/platform-admin/src/api` 目录下执行替换：

```
查找: '/admin/
替换: '/api/admin/
```

#### 5.4 官网 (apps/official-website/)

```
查找: '/website/
替换: '/api/website/

查找: '/public/
替换: '/api/website/
```

### 步骤6: 更新 Swagger 配置 (15分钟)

修改 `apps/server/src/main.ts`，为不同模块添加 API 标签分组：

```typescript
const config = new DocumentBuilder()
  .setTitle('酒店民宿短租预订平台 API')
  .setDescription('API 文档')
  .setVersion('1.0')
  .addBearerAuth()
  .addTag('应用端', '小程序C端用户使用的接口')
  .addTag('商家端', '小程序商家端和商家管理后台使用的接口')
  .addTag('平台管理端', '平台管理后台使用的接口')
  .addTag('官网', '官方网站使用的接口')
  .build();
```

在各个 Controller 中添加对应的 `@ApiTags` 装饰器。

### 步骤7: 测试验证 (60分钟)

#### 7.1 后端测试

```bash
# 启动后端服务
cd apps/server
pnpm run start:dev

# 检查控制台是否有错误
# 访问 Swagger 文档
# http://localhost:3000/api/docs
```

#### 7.2 前端测试

```bash
# 启动小程序
cd apps/miniapp
pnpm run dev:mp-weixin

# 启动商家后台
cd apps/merchant-admin
pnpm run dev

# 启动平台后台
cd apps/platform-admin
pnpm run dev

# 启动官网
cd apps/official-website
pnpm run dev
```

#### 7.3 功能测试清单

- [ ] 应用端
  - [ ] 用户登录/注册
  - [ ] 浏览房源
  - [ ] 创建订单
  - [ ] 查看订单列表
  - [ ] 发表评价
  - [ ] 优惠券领取
  - [ ] 钱包充值/提现

- [ ] 商家端
  - [ ] 商家登录
  - [ ] 房源管理（增删改查）
  - [ ] 订单管理
  - [ ] 数据统计
  - [ ] 财务管理

- [ ] 平台管理端
  - [ ] 管理员登录
  - [ ] 用户管理
  - [ ] 商家审核
  - [ ] 订单管理
  - [ ] 财务管理
  - [ ] 系统配置

- [ ] 官网
  - [ ] 首页展示
  - [ ] 房源浏览
  - [ ] 商家展示

## 五、风险控制

### 5.1 备份策略

在开始重构前，创建 Git 分支：

```bash
git checkout -b refactor/interface-classification
git add .
git commit -m "feat: 开始接口分类重构"
```

### 5.2 回滚方案

如果出现问题，可以快速回滚：

```bash
git checkout dev
git branch -D refactor/interface-classification
```

### 5.3 分阶段提交

建议按以下阶段提交代码：

1. 第一次提交：目录重命名和移动
2. 第二次提交：Controller 路由前缀修改
3. 第三次提交：模块导入更新
4. 第四次提交：前端 API 路径更新
5. 第五次提交：测试通过后的最终调整

## 六、预计时间

| 步骤 | 预计时间 | 说明 |
|------|---------|------|
| 步骤1: 目录重命名移动 | 30分钟 | 使用命令行批量操作 |
| 步骤2: 移动 controller | 45分钟 | 手动移动并调整导入 |
| 步骤3: 修改路由前缀 | 60分钟 | VS Code 批量替换 |
| 步骤4: 更新模块注册 | 45分钟 | 修改 module.ts 文件 |
| 步骤5: 更新前端路径 | 90分钟 | 四个前端项目批量替换 |
| 步骤6: 更新 Swagger | 15分钟 | 添加 API 分组 |
| 步骤7: 测试验证 | 60分钟 | 全面功能测试 |
| **总计** | **5.75小时** | 约半个工作日 |

## 七、注意事项

1. **路径别名**: 确保所有 `@/` 路径别名正确指向新的目录结构
2. **导入语句**: 检查所有 import 语句是否正确
3. **DTO 共享**: 如果有共享的 DTO，考虑放在 `shared/dto` 目录
4. **Guard 和 Decorator**: 确保认证守卫和装饰器路径正确
5. **测试文件**: 同步更新所有 `.spec.ts` 测试文件
6. **环境变量**: 检查是否有硬编码的路径需要更新
7. **文档更新**: 更新 CLAUDE.md 和其他文档中的路径说明

## 八、后续优化建议

1. **API 版本控制**: 考虑添加 `/api/v1/` 版本前缀
2. **接口文档**: 为每个模块生成独立的 Swagger 文档
3. **权限控制**: 基于路由前缀实现更细粒度的权限控制
4. **监控日志**: 按模块分类记录 API 调用日志
5. **性能优化**: 为不同端的接口设置不同的缓存策略