369 lines
11 KiB
Markdown
369 lines
11 KiB
Markdown
# 前后端接口对接完成报告
|
||
|
||
## 一、完成概览
|
||
|
||
本次开发完成了前后端的完整对接，包括：
|
||
- ✅ 新增预约（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 | 删除预约 | 管理员 |
|
||
|
||
#### 预约数据模型
|
||
|
||
```typescript
|
||
{
|
||
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返回格式统一为：
|
||
|
||
```typescript
|
||
{
|
||
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. **用户信息接口**
|
||
```typescript
|
||
// 修改前: /user/info
|
||
// 修改后: /users/profile
|
||
export const getUserInfo = () => {
|
||
return get('/users/profile')
|
||
}
|
||
```
|
||
|
||
2. **案例列表接口**
|
||
```typescript
|
||
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. **公司信息接口**
|
||
```typescript
|
||
// 改为返回固定数据（临时方案，后续可对接后端）
|
||
export const getCompanyInfo = () => {
|
||
return Promise.resolve({
|
||
code: 0,
|
||
message: 'success',
|
||
data: {
|
||
name: '优艺家沙发翻新',
|
||
slogan: '让旧沙发焕发新生',
|
||
// ... 其他信息
|
||
}
|
||
})
|
||
}
|
||
```
|
||
|
||
4. **新增预约相关接口**
|
||
```typescript
|
||
// 提交预约
|
||
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. **正确的数据提交格式**
|
||
```typescript
|
||
{
|
||
serviceId: number, // 服务ID
|
||
contactName: string, // 联系人姓名
|
||
contactPhone: string, // 联系电话
|
||
address: string, // 服务地址
|
||
appointmentTime: string, // 预约时间 (ISO 8601格式)
|
||
requirements: string, // 特殊要求
|
||
images: string[] // 图片列表
|
||
}
|
||
```
|
||
|
||
### 3. 优化案例列表页面
|
||
|
||
**文件：** `前端/pages/cases/list.uvue`
|
||
|
||
#### 数据适配改进：
|
||
|
||
```typescript
|
||
// 适应后端返回的字段结构
|
||
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`
|
||
|
||
#### 数据映射优化：
|
||
|
||
```typescript
|
||
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`
|
||
|
||
```typescript
|
||
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
|
||
**项目状态：** 前后端基础对接完成，可进行功能测试
|