Files
rent/INTERFACE_CLASSIFICATION_PLAN.md
T
2026-05-15 11:28:02 +08:00

585 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 接口分类重构计划
## 一、重构目标
将所有后端接口按照使用端分成四类,通过文件夹和路由前缀清晰区分:
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. **性能优化**: 为不同端的接口设置不同的缓存策略