6.4 KiB
推荐商品开发与视觉检查记录
操作时间：2026-09-08。操作类型：新增、扩展和布局修复。影响模块：用户推荐API、购物车、收藏、商品详情返回刷新。沿用远程PostgreSQL与Redis，本轮没有数据库迁移、容器操作、全库初始化或商品资料写入。
操作前后
已打开并检查最新图13购物车和图15我的收藏。操作前购物车缺少“猜你喜欢”和换一换，收藏缺少底部推荐入口。操作后购物车显示真实推荐商品，收藏推荐入口打开可滚动弹层，均可查看详情、换一批及加购。实际价格、库存、图片来自既有后台，不用原图示例金额代替业务数据。
截图检查还发现320宽度、1.3倍字体时购物车金额会逐字换行，已改为金额独立一行。从推荐或已有购物车商品进入详情后返回会重读购物车，避免详情加购后合计仍显示旧值。
文件与职责
| 文件（仓库相对路径） | 关键函数与变更 |
|---|---|
| backend/api/internal/logic/client/user/recommendation.go | 新增90行，Recommendations、recommendationValues，归属过滤、分类排序、分页、批量图片与分类 |
| backend/api/internal/logic/client/user/recommendation_test.go | 新增96行，双入口归属/排序、分页、公开字段与非法参数回归 |
| backend/api/internal/routers/client.go、client_test.go | 新增受JWT保护的GET shop/recommendations和路由回归 |
| apps/user_app/lib/domain/models/product_recommendations.dart | 新增49行，ProductRecommendations校验分页与整数分金额 |
| apps/user_app/lib/data/repositories/client_repository.dart | recommendations；cart/cartItem/setCartItem补充会话一致性检查 |
| apps/user_app/lib/ui/features/shop/product_recommendations.dart | 新增283行，ProductRecommendationSection、showFavoriteRecommendations，读取、换页、条件加购和错误恢复 |
| apps/user_app/lib/ui/features/shop/cart_page.dart | build/_busy，内嵌推荐、加购时阻止结算、金额响应式布局、详情返回刷新 |
| apps/user_app/lib/ui/features/shop/favorites_page.dart | build增加推荐入口，关闭弹层后刷新收藏 |
| apps/user_app/test/ui/product_recommendations_test.dart | 新增195行，分页、未知加购重试、库存、结算阻止、详情返回与收藏弹层 |
| apps/user_app/test/data/product_recommendations_test.dart、cart_test.dart | 新增推荐契约与购物车旧账号迟到响应回归 |
| apps/user_app/test/support/a1_fixture.dart | 仅自动测试用推荐数据，不进入运行入口 |
接口行为
GET /heqi/client/v1/user/shop/recommendations?source=cart&page=1&page_size=2：source只接受cart、favorites；page范围1至10000，page_size范围1至20。未登录HTTP401。服务端只选择status=1、未软删除且stock_quantity>0商品，始终排除本人有效购物车，收藏场景再排除本人有效收藏。
同入口关联分类优先，其余按商品更新时间倒序、公开标识排序。通过GORM的clause.OrderBy.Expression绑定账户参数，避免Order(gorm.Expr)被忽略；表名只取固定枚举，禁止拼接用户输入。每页商品元数据只需一次图片和一次分类查询，返回字段白名单，不暴露内部ID。
客户端换一换读取下一页，末页回到第一页。加购读取购物车快照并提交绝对目标数量和原revision；未知响应在当前组件保留原目标，重试不重复加量，成功后重读购物车及推荐。加购期间禁用购物车结算与批量操作。401交由会话路由处理，旧账号迟到响应不更新当前界面。
验证与实际数据
- Go全量测试、vet、API构建通过；新增测试验证双入口SQL归属、分类排序实际生效、分页多读一条、主图与分类隔离、公开字段及空页/非法参数。
- Flutter analyze、全量90项测试通过；补充详情返回刷新后，购物车及推荐的7项定向测试再次通过。所有测试使用生产主题，Fixture不修改远程数据。
- 图13/15在320、360、390、430宽度及1.0/1.3文字缩放共16项布局检查通过；修复金额换行后图13的8项复查通过，并实际查看390普通、320大字体截图。并排对照已更新。
- Web Release与Android Debug构建通过；原生设备操作未据此声明已验收。Android仍有speech_to_text/tobias未来Kotlin插件兼容提示。
- 远程接口首批实际返回后台现有“示例配送商品10/9”，下一批8/7；原购物车1件商品被排除。临时收藏商品10后，favorites推荐排除它，测试收藏已取消恢复；未登录HTTP401。
- 浏览器390×844验证换一换、查看商品8详情、返回、推荐商品10加购：购物车由1件变2件，合计从10300分变20800分，推荐列表移除商品10。通过管理仅删除本轮新增条目，保留原商品1件；本轮未创建订单、支付或改变库存。
- 收藏页实际打开推荐弹层，显示真实价格与可操作的换一换、详情和加购入口；关闭正常，浏览器错误/警告日志为空。最终HTTP复核收藏为空、购物车仅原商品1件且已勾选，基线恢复通过。
- 最终详情返回修复已重新构建Web与Android Debug；API进程32148运行本轮后端，Web继续由18571提供。构建通过不代表原生设备验收完成。
视觉结果与剩余风险
严格验收仍为failed。58图仍是13张部分实现、45张无完整页、0张通过严格全功能1:1。商品图片为空或404、月销量无口径、押金与配送服务承诺尚未实现，卡片密度和精细样式仍有差异。图13推荐双列及图15推荐入口已补，不能据此声称整个购物车/收藏页面还原完成。
证据：图13并排、图15并排、320大字体修复。图片缺失保留明确提示，不把设计截图当成真实商品照片。未知加购结果只在当前组件保留；跨页面重建恢复、全商品图片运营配置、其余45页仍需继续实现。
维护时扩展推荐条件应更新双入口归属测试，继续使用字段白名单和参数绑定；不可把推荐服务改成客户端上传完整私有购物车。测试单独执行flutter test test/ui/product_recommendations_test.dart test/data/product_recommendations_test.dart，Go使用go test ./internal/logic/client/user ./internal/routers。