ShaFaFanXin/前端/docs/接口对接完成报告.md

前后端接口对接完成报告

一、完成概览

本次开发完成了前后端的完整对接，包括：

• ✅ 新增预约（Booking）模块的完整后端实现
• ✅ 修正所有前端API调用的路径和参数
• ✅ 统一后端响应数据格式
• ✅ 完善预约页面功能
• ✅ 优化案例列表和详情页面的数据适配

二、后端完成的工作

1. 新增 Booking 模块

文件结构

后端/src/booking/
├── booking.controller.ts  # 预约控制器
├── booking.service.ts     # 预约服务
├── booking.module.ts      # 预约模块
└── dto/
    └── booking.dto.ts     # 预约DTO

API 接口列表

方法	路径	说明	权限
POST	/api/booking	创建预约	登录用户
GET	/api/booking	获取所有预约	管理员/工人
GET	/api/booking/my	获取我的预约列表	登录用户
GET	/api/booking/:id	获取预约详情	登录用户
PATCH	/api/booking/:id	更新预约信息	本人/管理员
POST	/api/booking/:id/cancel	取消预约	本人/管理员
DELETE	/api/booking/:id	删除预约	管理员

预约数据模型

{
  id: number;
  bookingNumber: string;        // 预约编号 (自动生成)
  serviceId: number;            // 服务ID
  customerId: number;           // 客户ID
  contactName: string;          // 联系人姓名
  contactPhone: string;         // 联系电话
  address: string;              // 服务地址
  appointmentTime: Date;        // 预约时间
  requirements?: string;        // 特殊要求
  images?: string[];            // 沙发现状图片
  status: string;               // 状态: pending/confirmed/in_progress/completed/cancelled
  quotedPrice?: number;         // 报价
  finalPrice?: number;          // 最终价格
  notes?: string;               // 备注
  assignedWorkerId?: number;    // 分配工人ID
}

2. 统一后端响应格式

所有API返回格式统一为：

{
  code: 0,           // 0表示成功
  message: string,   // 响应消息
  data: any          // 响应数据
}

修改的服务：

• case.service.ts - 案例服务

  • findAll() - 返回格式: { code, message, data: { list, total, page, pageSize } }
  • findOne() - 返回格式: { code, message, data: caseEntity }
  • getMyCases() - 返回格式: { code, message, data: { list, total, page, pageSize } }

• service.service.ts - 服务管理

  • getActiveServices() - 返回格式: { code, message, data: { list, total } }

• booking.service.ts - 预约管理

  • 所有方法统一返回上述格式

三、前端完成的工作

1. 修正 API 调用路径

文件： 前端/api/index.uts

修改的接口：

1. 用户信息接口

   // 修改前: /user/info
   // 修改后: /users/profile
   export const getUserInfo = () => {
     return get('/users/profile')
   }
   

2. 案例列表接口

   export const getCaseList = (params ?: UTSJSONObject) => {
     const queryParams : UTSJSONObject = {
       page: params ? (params['page'] || 1) : 1,
       limit: params ? (params['pageSize'] || params['limit'] || 10) : 10,
       status: 'published'
     }
     // 只在有分类且不为'all'时添加serviceType参数
     if (params && params['category'] && params['category'] != 'all') {
       queryParams['serviceType'] = params['category']
     }
     return get('/cases', queryParams)
   }
   

3. 公司信息接口

   // 改为返回固定数据（临时方案，后续可对接后端）
   export const getCompanyInfo = () => {
     return Promise.resolve({
       code: 0,
       message: 'success',
       data: {
         name: '优艺家沙发翻新',
         slogan: '让旧沙发焕发新生',
         // ... 其他信息
       }
     })
   }
   

4. 新增预约相关接口

   // 提交预约
   export const submitBooking = (data : UTSJSONObject) => {
     return post('/booking', data)
   }
   
   // 获取我的预约列表
   export const getMyBookings = (params ?: UTSJSONObject) => {
     return get('/booking/my', queryParams)
   }
   
   // 获取预约详情
   export const getBookingDetail = (id : string) => {
     return get(`/booking/${id}`)
   }
   
   // 取消预约
   export const cancelBooking = (id : string) => {
     return post(`/booking/${id}/cancel`, {})
   }
   

2. 完善预约页面

文件： 前端/pages/booking/index.uvue

主要改进：

1. 动态加载服务列表

   • 从后端 /api/services/active 获取可用服务
   • 用户可选择具体的服务类型

2. 添加预约时间选择

   • 使用日期选择器选择预约日期
   • 最小日期为当天

3. 完善表单验证

   • 必填项：姓名、电话、地址、服务类型、预约时间
   • 手机号格式验证

4. 正确的数据提交格式

   {
     serviceId: number,        // 服务ID
     contactName: string,      // 联系人姓名
     contactPhone: string,     // 联系电话
     address: string,          // 服务地址
     appointmentTime: string,  // 预约时间 (ISO 8601格式)
     requirements: string,     // 特殊要求
     images: string[]          // 图片列表
   }
   

3. 优化案例列表页面

文件： 前端/pages/cases/list.uvue

数据适配改进：

// 适应后端返回的字段结构
const newList = list.map((item) : CaseItem => {
  return {
    id: String(item['id']),
    title: item['title'] as string,
    category: item['serviceType'] as string,      // 后端字段
    categoryName: item['serviceName'] as string,  // 服务名称
    coverImage: item['coverImage'] as string,
    material: item['material'] as string || '',
    duration: item['duration'] as string || '',
    price: String(item['estimatedPrice'] || 0),   // 估算价格
    views: item['views'] as number || 0,
    likes: item['likes'] as number || 0
  }
})

4. 优化案例详情页面

文件： 前端/pages/cases/detail.uvue

数据映射优化：

caseDetail.value = {
  id: String(data['id']),
  title: data['title'] as string,
  category: data['serviceType'] as string || '',      // 后端使用serviceType
  categoryName: data['serviceName'] as string || '',
  beforeImages: data['beforeImages'] as string[] || [],
  afterImages: data['afterImages'] as string[] || [],
  description: data['description'] as string,
  material: data['material'] as string || '优质材料',
  duration: data['duration'] as string || '5-7天',
  price: '¥' + (data['estimatedPrice'] || '面议'),
  views: data['views'] as number || 0,
  likes: data['likes'] as number || 0,
  createTime: createdAt.split('T')[0] || ''          // 格式化日期
}

四、配置更新

环境配置

文件： 前端/utils/config.uts

export const ENV = {
  development: {
    baseUrl: 'http://localhost:3000/api',
    imageBaseUrl: 'http://localhost:3000'
  },
  production: {
    baseUrl: 'https://api.youyijia.com/api',
    imageBaseUrl: 'https://api.youyijia.com'
  }
}

// 当前环境
export const currentEnv = 'development'

// 关闭Mock数据
export const useMock = false

五、接口对应关系总结

1. 认证相关

前端调用	后端路径	说明
-	POST /api/auth/register	用户注册
-	POST /api/auth/login	用户登录
-	POST /api/auth/wechat/login	微信登录

2. 用户相关

前端调用	后端路径	说明
getUserInfo()	GET /api/users/profile	获取当前用户信息

3. 案例相关

前端调用	后端路径	说明
getCaseList(params)	GET /api/cases?page&limit&serviceType&status	获取案例列表
getCaseDetail(id)	GET /api/cases/:id	获取案例详情
getHotCases()	GET /api/cases?limit=4&status=published	获取热门案例

4. 服务相关

前端调用	后端路径	说明
getActiveServices()	GET /api/services/active	获取有效服务列表
getServiceProcess()	GET /api/services	获取服务流程

5. 预约相关

前端调用	后端路径	说明
submitBooking(data)	POST /api/booking	提交预约
getMyBookings(params)	GET /api/booking/my	获取我的预约
getBookingDetail(id)	GET /api/booking/:id	获取预约详情
cancelBooking(id)	POST /api/booking/:id/cancel	取消预约

六、后端服务状态

服务器信息

• 地址： http://localhost:3000
• API文档： http://localhost:3000/docs
• 状态： ✅ 运行中

数据库连接

• 类型： MySQL
• 数据库： sffx
• 状态： ✅ 已连接

已注册的模块

• ✅ AppModule
• ✅ AuthModule (认证模块)
• ✅ UserModule (用户模块)
• ✅ CaseModule (案例模块)
• ✅ ServiceModule (服务模块)
• ✅ BookingModule (预约模块) 【新增】

七、待完成的工作

1. 前端功能待完善

• 用户登录/注册页面
• 我的预约列表页面
• 收藏功能实现
• 图片上传功能

2. 后端功能待完善

• 用户收藏API
• 图片上传API
• 公司信息管理API
• 轮播图管理API

3. 后台管理界面

• 后台管理系统开发（等前端功能完善后开始）
  • 用户管理
  • 案例管理
  • 服务管理
  • 预约管理
  • 数据统计

八、测试建议

1. 接口测试

访问 http://localhost:3000/docs 查看Swagger API文档，可以在线测试所有接口。

2. 前端测试流程

1. 启动后端服务：cd 后端 && npm run start:dev
2. 启动前端：使用HBuilderX运行到浏览器或小程序
3. 测试流程：
   • 浏览首页，查看案例列表
   • 点击案例查看详情
   • 进入服务页面查看服务列表
   • 填写预约表单并提交

3. 需要准备的测试数据

• 创建管理员账号
• 添加服务类型（布艺沙发、皮沙发等）
• 添加几个案例数据
• 测试预约流程

九、注意事项

1. 认证机制：部分接口需要登录后才能访问，需要在请求头中携带 Bearer Token
2. 数据库同步：后端配置了 synchronize: true，会自动同步数据库结构
3. 跨域问题：如需在不同域名访问，需配置CORS
4. 图片存储：当前图片路径为字符串数组，需要配置文件上传服务

---

报告生成时间： 2026年1月28日 完成人员： GitHub Copilot 项目状态： 前后端基础对接完成，可进行功能测试