CrossBorder_OS/FRONTEND_BACKEND_ALIGNMENT_CHECK.md

前后端代码对齐检查报告

检查时间

2026-04-21

检查范围

• 订单模块 (Orders)
• 商品模块 (Products)

---

一、订单模块对齐分析

1.1 字段类型对比

1.2 字段命名差异

字段名	后端类型	前端类型	状态	说明
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	OrderProductItem[]	⚠️	类型名不同

后端命名	前端命名	建议
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处理:

// 后端需要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 - 高优先级

1. 字段补齐

   • 前端添加: channelId, warehouseId
   • 后端DTO添加: 计算字段 (inventory, priceRange)

2. 字段命名统一

   • 前端: carrier → carrierName
   • 前端: handler → handlerName
   • 前端: warehouse → warehouseName
   • 前端: channel → channelName

🟢 P2 - 中优先级

1. 金额字段规范

   • 统一使用 string 类型避免精度问题
   • 前端显示时格式化

2. 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问题