xiaoquan/rent

Fork 0

Files

T

xiaoquan 8c908ea557 feat: 迭代

2026-05-15 11:28:02 +08:00

18 KiB

Raw Blame History

接口分类重构计划

一、重构目标

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

应用端 (app) - 小程序C端用户使用的接口
商家端 (merchant) - 小程序商家端 + 商家管理后台使用的接口
平台管理端 (admin) - 平台管理后台使用的接口
官网 (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分钟)

# 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

# 移动用户优惠券
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

# 移动商家财务
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

# 移动管理优惠券
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

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 标签分组：

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

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

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

7.1 后端测试

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

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

7.2 前端测试

# 启动小程序
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 分支：

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

5.2 回滚方案

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

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

5.3 分阶段提交

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

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

六、预计时间

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

七、注意事项

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

八、后续优化建议

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

18 KiB Raw Blame History Unescape Escape

接口分类重构计划

一、重构目标

二、目标目录结构

三、接口分类详情

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

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

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

3.4 官网接口 (12个接口)

四、执行步骤

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

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

2.1 移动应用端相关的 controller

2.2 移动商家端相关的 controller

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

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

3.1 应用端路由

3.2 商家端路由

3.3 平台管理端路由

3.4 官网路由

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

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

4.2 更新根模块 app.module.ts

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

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

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

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

5.4 官网 (apps/official-website/)

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

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

7.1 后端测试

7.2 前端测试

7.3 功能测试清单

五、风险控制

5.1 备份策略

5.2 回滚方案

5.3 分阶段提交

六、预计时间

七、注意事项

八、后续优化建议

18 KiB

Raw Blame History