# 前后端代码对齐检查报告

## 检查时间
2026-04-21

## 检查范围
- 订单模块 (Orders)
- 商品模块 (Products)

---

## 一、订单模块对齐分析

### 1.1 字段类型对比

| 字段名 | 后端类型 | 前端类型 | 状态 | 说明 |
|--------|---------|---------|------|------|
| id | Long | string | ❌ **不对齐** | 应统一为 number |
| orderNo | String | string | ✅ | 对齐 |
| channelOrderNo | String | string | ✅ | 对齐 |
| channelId | Long | - | ⚠️ | 前端缺少此字段 |
| channel | - | string | ⚠️ | 后端DTO有，实体无 |
| orderStatus | String | string | ✅ | 对齐 |
| shippingStatus | String | string | ✅ | 对齐 |
| paymentStatus | String | string | ✅ | 对齐 |
| refundStatus | String | string | ✅ | 对齐 |
| exceptionTag | String | string | ✅ | 对齐 |
| priority | String | string | ✅ | 对齐 |
| buyerId | String | string | ✅ | 对齐 |
| buyer | String | string | ✅ | 对齐 |
| buyerEmail | String | string | ✅ | 对齐 |
| buyerPhone | String | string | ✅ | 对齐 |
| buyerCountry | String | string | ✅ | 对齐 |
| buyerLevel | String | string | ✅ | 对齐 |
| buyerTags | String | string[] | ❌ **不对齐** | String vs Array |
| buyerOrderCount | Integer | number | ✅ | 对齐 |
| buyerTotalSpent | BigDecimal | string | ⚠️ | 建议用 string |
| receiverName | String | string | ✅ | 对齐 |
| receiverPhone | String | string | ✅ | 对齐 |
| receiverCountry | String | string | ✅ | 对齐 |
| receiverState | String | string | ✅ | 对齐 |
| receiverCity | String | string | ✅ | 对齐 |
| receiverDistrict | String | string | ✅ | 对齐 |
| receiverPostalCode | String | string | ✅ | 对齐 |
| receiverAddress | String | string | ✅ | 对齐 |
| latitude | BigDecimal | number | ⚠️ | 可接受 |
| longitude | BigDecimal | number | ⚠️ | 可接受 |
| orderAmount | BigDecimal | string | ⚠️ | 建议用 string |
| actualPaid | BigDecimal | string | ⚠️ | 建议用 string |
| amount | - | string | ❌ **后端缺失** | 前端在用 |
| warehouseLocation | String | string | ✅ | 对齐 |
| warehouseId | Long | - | ⚠️ | 前端缺少 |
| trackingNo | String | string | ✅ | 对齐 |
| itemCount | Integer | number | ✅ | 对齐 |
| items | List<OrderItemDTO> | OrderProductItem[] | ⚠️ | 类型名不同 |

### 1.2 字段命名差异

| 后端命名 | 前端命名 | 建议 |
|---------|---------|------|
| carrierName | carrier | 前端统一用 carrierName |
| handlerName | handler | 前端统一用 handlerName |
| warehouseName | warehouse | 前端统一用 warehouseName |
| channelName | channel | 前端统一用 channelName |

---

## 二、商品模块对齐分析

### 2.1 字段类型对比

| 字段名 | 后端类型 | 前端类型 | 状态 | 说明 |
|--------|---------|---------|------|------|
| id | Long | string | ❌ **不对齐** | 应统一为 number |
| spu | String | string | ✅ | 对齐 |
| title | String | string | ✅ | 对齐 |
| subtitle | String | - | ⚠️ | 前端缺少 |
| categoryId | Long | string | ❌ **不对齐** | Long vs string |
| category | - | string | ❌ **后端缺失** | 前端在用 |
| brand | String | string | ✅ | 对齐 |
| tags | String | string[] | ❌ **不对齐** | String vs Array |
| description | String | string | ✅ | 对齐 |
| specs | String | SpecItem[] | ❌ **不对齐** | JSON vs Array |
| channelStatus | String | string | ✅ | 对齐 |
| status | String | string | ✅ | 对齐 |
| owner | String | string | ✅ | 对齐 |
| skuCount | Integer | number | ✅ | 对齐 |
| image | String | string | ✅ | 对齐 |
| images | String | MediaItem[] | ❌ **不对齐** | JSON vs Array |
| videos | String | MediaItem[] | ❌ **不对齐** | JSON vs Array |
| translations | String | TranslationItem[] | ❌ **不对齐** | JSON vs Array |
| inventory | - | number | ❌ **后端缺失** | 前端在用 |
| priceRange | - | string | ❌ **后端缺失** | 前端在用 |

### 2.2 字段命名差异

| 后端命名 | 前端命名 | 建议 |
|---------|---------|------|
| categoryId | category | 前端使用 categoryId，前端也应有分类名称字段 |

---

## 三、严重问题汇总

### 3.1 类型不匹配问题

1. **ID字段类型不一致**
   - 后端: `Long`
   - 前端: `string`
   - 影响: 路由参数、API调用
   - 建议: 前端统一使用 `number` 类型

2. **JSON字段序列化问题**
   - 后端: `String` (存储JSON字符串)
   - 前端: `Array` 类型
   - 影响: tags, specs, images, videos, translations
   - 需要后端Converter处理序列化/反序列化

3. **金额字段类型**
   - 后端: `BigDecimal`
   - 前端: `string`
   - 建议: 统一使用 `string` 避免精度问题

### 3.2 缺失字段

**订单模块:**
- 后端有但前端未使用: `channelId`, `warehouseId`, `carrierId`
- 前端在用但后端无: `amount` (应该是 `actualPaid` 的别名)

**商品模块:**
- 后端有但前端未使用: `subtitle`, `categoryId`
- 前端在用但后端无: `category`, `inventory`, `priceRange` (计算字段)

### 3.3 字段命名不一致

```
后端实体使用驼峰命名: orderNo, buyerId, channelId
前端类型使用驼峰命名: orderNo, buyerId, channelId
✅ 命名风格一致，但具体字段名有差异:
- carrierName vs carrier
- handlerName vs handler
- warehouseName vs warehouse
- channelName vs channel
```

---

## 四、DTO转换器问题

### 4.1 后端Converter检查

需要检查以下Converter是否正确处理字段映射:
- `OrdersConverter.toListDto()`
- `OrdersConverter.toDto()`
- `OrderItemConverter.toDto()`
- Product相关的Converter

### 4.2 JSON字段序列化

后端存储为JSON字符串的字段，需要Converter处理:
```java
// 后端需要Converter处理
private String tags;           // -> 前端 string[]
private String specs;          // -> 前端 SpecItem[]
private String images;         // -> 前端 MediaItem[]
private String videos;         // -> 前端 MediaItem[]
private String translations;   // -> 前端 TranslationItem[]
```

---

## 五、API路径对齐

### 5.1 订单API

| 功能 | 后端路径 | 前端调用 | 状态 |
|------|---------|---------|------|
| 获取订单列表 | GET /api/order/orders | api.getOrders() | ✅ |
| 获取订单详情 | GET /api/order/orders/{id} | api.getOrder() | ✅ |
| 创建订单 | POST /api/order/orders | api.createOrder() | ✅ |
| 更新订单 | PUT /api/order/orders/{id} | api.updateOrder() | ✅ |
| 删除订单 | DELETE /api/order/orders/{id} | api.deleteOrder() | ✅ |

### 5.2 商品API

| 功能 | 后端路径 | 前端调用 | 状态 |
|------|---------|---------|------|
| 获取商品列表 | GET /api/product/products | api.getProducts() | ✅ |
| 获取商品详情 | GET /api/product/products/{id} | api.getProduct() | ✅ |
| 创建商品 | POST /api/product/products | api.createProduct() | ✅ |
| 更新商品 | PUT /api/product/products/{id} | api.updateProduct() | ✅ |
| 删除商品 | DELETE /api/product/products/{id} | api.deleteProduct() | ✅ |

---

## 六、修复建议优先级

### 🔴 P0 - 必须立即修复

1. **ID字段类型统一**
   - 前端 OrderItem.id: string → number
   - 前端 ProductItem.id: string → number
   - 影响: 路由跳转、API调用

2. **JSON字段序列化**
   - 后端Converter处理 tags, specs, images, videos, translations
   - 确保 JSON字符串正确转换为对象数组

### 🟡 P1 - 高优先级

3. **字段补齐**
   - 前端添加: channelId, warehouseId
   - 后端DTO添加: 计算字段 (inventory, priceRange)

4. **字段命名统一**
   - 前端: carrier → carrierName
   - 前端: handler → handlerName
   - 前端: warehouse → warehouseName
   - 前端: channel → channelName

### 🟢 P2 - 中优先级

5. **金额字段规范**
   - 统一使用 string 类型避免精度问题
   - 前端显示时格式化

6. **Category字段处理**
   - 后端DTO增加: categoryName (从categoryId查询)
   - 前端使用 categoryId 而非 category

---

## 七、待修复代码清单

### 后端需要修改:

1. **OrderListDTO.java** - 添加缺失字段
2. **OrdersConverter.java** - 完善字段映射
3. **ProductConverter.java** - 处理JSON序列化
4. **ProductDTO.java** - 添加计算字段

### 前端需要修改:

1. **types/page.ts** - 修改类型定义
2. **views/order/OrderListView.vue** - 使用正确字段名
3. **views/product/ProductListView.vue** - 使用正确字段名

---

## 八、验证方法

修复后需要验证:

1. ✅ 后端编译通过
2. ✅ 前端构建通过
3. ✅ 订单列表正常显示
4. ✅ 订单详情正常显示
5. ✅ 商品列表正常显示
6. ✅ 商品详情正常显示
7. ✅ 筛选功能正常
8. ✅ 分页功能正常

---

**检查完成时间**: 2026-04-21
**检查人员**: Claude Code
**下一步**: 开始修复P0问题