# 商品详情开发日志

操作时间：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通过。新详情不等同于完整商城闭环。