3.8 KiB
商品详情开发日志
操作时间：2026-09-08。操作类型：新增及兼容扩展。影响模块：图11商城、图12详情、图14结算及游客登录回跳。
操作前后
原商城只能直接购买，没有独立商品详情。现在点击商品图片或名称进入 /products/:identity；游客可直接查看，购买时先登录，登录后保留商品和数量进入结算。原商品购买按钮继续直接进入结算，已有调用不删除。
新增 GET /heqi/client/v1/user/public/products/:identity，查询启用且未删除商品，允许查看零库存商品；图片、属性只读取该商品启用记录并按后台顺序排列。白名单返回identity/name/price_amount/stock_quantity/category_name/images/attributes，不返回内部主键，不查询订单。不存在或下架返回1112，客户端显示“商品已下架或不存在”；首次联调发现通用500后已修正并实测。
详情支持后台图片翻页、缩放预览、参数、数量1—min(库存,999)、售罄禁购及加载重试。金额使用整数分。结算仍重新查询商品价格与库存，提交由服务端校验，不信任详情页数据。直接打开详情或结算也有可用返回入口。
代码职责
backend/api/internal/logic/client/user/product_detail.go：PublicProduct公开详情；新增文件，无模型迁移。backend/api/internal/routers/client.go：注册匿名详情路由。apps/user_app/lib/domain/models/product_detail.dart：公开字段、图片/属性集合、金额与库存校验。apps/user_app/lib/data/repositories/client_repository.dart：productDetail匿名读取、图片地址解析、中文错误映射。apps/user_app/lib/ui/features/shop/product_detail_page.dart：详情图片、参数、数量、售罄、购买入口。shop_page.dart：图片/名称打开详情；游客购买使用根级登录跳转，解决页面内push后登录刷新停留问题。checkout_page.dart、app/router.dart：向后兼容的initialQuantity默认1，解析站内数量参数，结算重新读价。test/ui/product_detail_page_test.dart、test/data/product_detail_test.dart、test/app/router_test.dart、后端product_detail_test.go：页面、数据、鉴权回跳及公开数据边界。tool/a1_visual_test.dart与scripts/compare-user-app-a1.ps1：加入图12的8组截图及并排图。
验证
Go全量测试、vet、build通过，修改不存在错误码后两项详情专项复测通过。Flutter全量72项通过，新增数据解析/错误映射2项定向测试通过；analyze无问题，Web Release构建通过。平台contract:sync/check通过48个资源。图12的320/360/390/430宽、文本1.0/1.3共8组截图及溢出检查通过；已实际查看390截图和设计源图，严格1:1未通过。
远程只读接口：商品 00000000-0000-7000-8000-000000002015 返回“示例配送商品10”、10500分、库存30；该商品没有图片和参数，按空状态展示，没有把设计稿气瓶图冒充其真实商品图。不存在商品实测code=1112。
浏览器：新构建以游客打开真实详情，选2件，点击立即购买跳登录，测试账户登录后进入同一商品结算，数量2、应付¥210.00。没有提交订单、修改库存、支付或修改数据库。API仍使用原远程PostgreSQL与Redis，本机仅API/Web进程。
差异与风险
当前商品模型没有可选规格组合、月销量、押金、配送承诺和售后保障字段，因此只展示后台实际参数。收藏、客服和购物车入口继续明确说明未开放；尚未实现加购及分享。图片列表和参数接口已存在，但真实商品内容需要平台维护，不能填入与商品无关的样例。
整体更新为11张部分实现、47张尚无完整对应页，0张严格全功能与1:1通过。新详情不等同于完整商城闭环。