Переглянути джерело

feat(shop.review.detail): S-cfc-403 商品评价详情/去评价按钮态契约使绿

- ProductReviewResponse DTO 落地(review/canReview/reviewHint,canReview=Boolean、reviewHint=String)
- ProductReviewService 接口新增 detail(Long orderId, Long userId)
- ProductReviewServiceImpl 实现 detail:未评=null、已评→canReview=false;completed+90天窗口+非activity+未评→canReview=true 并附 reviewHint
- 字段 productOrderMapper 重命名为 orderMapper(对齐设计 §5.3 类图)
- ProductReviewController 新增 POST /api/product/review/detail(@RequestAttribute userId)
- API_REFERENCE.md 登记 R2 接口

验证:ProductReviewDetailContractTest 9 跑 0 失败(红 9 → 绿 9);ProductReviewCreateContractTest 10 跑 0 失败(回归零漂移)
Agnes Agent 4 днів тому
батько
коміт
7e94fd0ac7

+ 13 - 1
cfc-backend/src/main/java/com/etotem/cfc/controller/product/ProductReviewController.java

@@ -2,6 +2,7 @@ package com.etotem.cfc.controller.product;
 
 import com.etotem.cfc.common.Result;
 import com.etotem.cfc.dto.ProductReviewRequest;
+import com.etotem.cfc.dto.ProductReviewResponse;
 import com.etotem.cfc.service.ProductReviewService;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestAttribute;
@@ -13,10 +14,13 @@ import javax.annotation.Resource;
 import java.util.Map;
 
 /**
- * 普通商品评价控制器(能力键 {@code shop.review.create} / {@code shop.review.my})。
+ * 普通商品评价控制器(能力键 {@code shop.review.create},R1;{@code shop.review.detail},R2;
+ * {@code shop.review.my},R5)。
  *
  * <p>设计 {@code docs/superpowers/specs/2026-11-14-product-order-gap-arch-design.md} §3.1:
  * R1 {@code POST /api/product/review/create}(鉴权=登录买家本人)、
+ * R2 {@code POST /api/product/review/detail}(鉴权=登录下单人/商家,出参
+ * {@code Result<ProductReviewResponse>})、
  * R5 {@code POST /api/product/review/my}(鉴权=登录买家)。
  * 对齐 {@code ProductOrderController} 同点位 {@code @RequestAttribute("userId")} 写法。</p>
  */
@@ -34,6 +38,14 @@ public class ProductReviewController {
         return Result.success(result);
     }
 
+    @PostMapping("/detail")
+    public Result<ProductReviewResponse> detail(@RequestBody Map<String, Object> params,
+                                                @RequestAttribute("userId") Long userId) {
+        Long orderId = params != null && params.get("orderId") != null
+                ? Long.valueOf(params.get("orderId").toString()) : null;
+        return Result.success(reviewService.detail(orderId, userId));
+    }
+
     @PostMapping("/my")
     public Result<Map<String, Object>> my(@RequestBody Map<String, Object> params,
                                           @RequestAttribute("userId") Long userId) {

+ 20 - 0
cfc-backend/src/main/java/com/etotem/cfc/dto/ProductReviewResponse.java

@@ -0,0 +1,20 @@
+package com.etotem.cfc.dto;
+
+import com.etotem.cfc.entity.ProductReview;
+import lombok.Data;
+
+import java.io.Serializable;
+
+/**
+ * R2 响应 DTO:商品评价详情/去评价按钮态载体(能力键 {@code shop.review.detail},任务 S-be-2)。
+ * 包含已评记录、可评态和提示文案。
+ */
+@Data
+public class ProductReviewResponse implements Serializable {
+
+    private ProductReview review;      // 已评记录,未评为 null
+
+    private Boolean canReview;         // 可评价态:completed 且 90 天窗口内且未评时 true
+
+    private String reviewHint;         // 提示文案:不可评/已评提示文案,供前端按钮态兜底
+}

+ 13 - 1
cfc-backend/src/main/java/com/etotem/cfc/service/ProductReviewService.java

@@ -1,11 +1,13 @@
 package com.etotem.cfc.service;
 
 import com.etotem.cfc.dto.ProductReviewRequest;
+import com.etotem.cfc.dto.ProductReviewResponse;
 
 import java.util.Map;
 
 /**
- * 普通商品评价服务(能力键 {@code shop.review.create} / {@code shop.review.my})。
+ * 普通商品评价服务(能力键 {@code shop.review.create} / {@code shop.review.detail} /
+ * {@code shop.review.my})。
  *
  * <p>独立于活动评价 {@link ReviewOrderService}(PRD P0-A:活动链路零改动,不走复用)。
  * 设计 {@code docs/superpowers/specs/2026-11-14-product-order-gap-arch-design.md} §5.3 类图。</p>
@@ -21,6 +23,16 @@ public interface ProductReviewService {
      */
     String createReview(ProductReviewRequest request, Long reviewerId);
 
+    /**
+     * 评价详情/去评价按钮态(设计 §3.1 R2:订单详情页「去评价」按钮 + 已评展示)。
+     *
+     * @param orderId 订单主键
+     * @param userId  登录用户ID(下单人/商家)
+     * @return {@link ProductReviewResponse}:review 已评记录(未评为 null)、
+     *         canReview 可评态(review==null 且可评时 true)、reviewHint 提示文案
+     */
+    ProductReviewResponse detail(Long orderId, Long userId);
+
     /**
      * 我的评价 + 待评价入口(R5,能力键 {@code shop.review.my})。
      *

+ 62 - 7
cfc-backend/src/main/java/com/etotem/cfc/service/ProductReviewServiceImpl.java

@@ -3,6 +3,7 @@ package com.etotem.cfc.service;
 import com.alibaba.fastjson.JSON;
 import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
 import com.etotem.cfc.dto.ProductReviewRequest;
+import com.etotem.cfc.dto.ProductReviewResponse;
 import com.etotem.cfc.entity.ProductOrder;
 import com.etotem.cfc.entity.ProductReview;
 import com.etotem.cfc.mapper.ProductOrderMapper;
@@ -20,12 +21,14 @@ import java.util.List;
 import java.util.Map;
 
 /**
- * 普通商品评价服务实现(能力键 {@code shop.review.create} / {@code shop.review.my})。
+ * 普通商品评价服务实现(能力键 {@code shop.review.create} / {@code shop.review.detail} /
+ * {@code shop.review.my},R1 + R2 + R5)。
  *
  * <p>设计 {@code docs/superpowers/specs/2026-11-14-product-order-gap-arch-design.md} §3.1 R1 校验链:
  * 订单存在 / {@code productType != 'activity'}(活动评价零污染)/ {@code status=completed} /
  * {@code buyerId==userId}(评价人为下单人本人)/ {@code confirmTime >= now-90d}(Q4 窗口)/
- * {@link ProductReviewMapper#findByOrderId} 幂等(一单一评,表唯一键 {@code uk_order_id})。</p>
+ * {@link ProductReviewMapper#findByOrderId} 幂等(一单一评,表唯一键 {@code uk_order_id})。
+ * §3.1 R2:{@link #detail} 判定「去评价」按钮态(completed + 90 天窗口 + 未评)。</p>
  */
 @Service
 public class ProductReviewServiceImpl extends ServiceImpl<ProductReviewMapper, ProductReview>
@@ -38,7 +41,7 @@ public class ProductReviewServiceImpl extends ServiceImpl<ProductReviewMapper, P
     private ProductReviewMapper reviewMapper;
 
     @Resource
-    private ProductOrderMapper productOrderMapper;
+    private ProductOrderMapper orderMapper;
 
     @Override
     @Transactional
@@ -61,7 +64,7 @@ public class ProductReviewServiceImpl extends ServiceImpl<ProductReviewMapper, P
         Long orderId = request.getOrderId();
 
         // 1) 订单存在
-        ProductOrder order = productOrderMapper.selectById(orderId);
+        ProductOrder order = orderMapper.selectById(orderId);
         if (order == null) {
             throw new RuntimeException("订单不存在");
         }
@@ -109,6 +112,47 @@ public class ProductReviewServiceImpl extends ServiceImpl<ProductReviewMapper, P
         return "评价提交成功";
     }
 
+    @Override
+    public ProductReviewResponse detail(Long orderId, Long userId) {
+        // 入参守卫
+        if (orderId == null) {
+            throw new RuntimeException("订单ID不能为空");
+        }
+        // 订单存在
+        ProductOrder order = orderMapper.selectById(orderId);
+        if (order == null) {
+            throw new RuntimeException("订单不存在");
+        }
+        // 已评记录(未评为 null)
+        ProductReview review = reviewMapper.findByOrderId(orderId);
+
+        ProductReviewResponse resp = new ProductReviewResponse();
+        resp.setReview(review);
+        if (review != null) {
+            resp.setCanReview(false);
+            resp.setReviewHint("该订单已评价");
+            return resp;
+        }
+        if (!"completed".equals(order.getStatus())) {
+            resp.setCanReview(false);
+            resp.setReviewHint("订单完成后可评价");
+            return resp;
+        }
+        if ("activity".equals(order.getProductType())) {
+            resp.setCanReview(false);
+            resp.setReviewHint("活动订单暂不支持评价");
+            return resp;
+        }
+        if (!inReviewWindow(order.getConfirmTime())) {
+            resp.setCanReview(false);
+            resp.setReviewHint("确认收货后90天内可评价");
+            return resp;
+        }
+        resp.setCanReview(true);
+        resp.setReviewHint("");
+        return resp;
+    }
+
     @Override
     public Map<String, Object> my(Long userId, int page, int size) {
         int pageNum = Math.max(page, 1);
@@ -116,8 +160,7 @@ public class ProductReviewServiceImpl extends ServiceImpl<ProductReviewMapper, P
 
         Map<String, Object> result = new HashMap<>();
 
-        // 1) 我的评价列表:按 reviewer_id 查,review_at 倒序分页(只取首屏页规模,不做总数统计——
-        //    小程序「我的评价」为简单列表,翻页按 offset 拉取即可)
+        // 1) 我的评价列表:按 reviewer_id 查,review_at 倒序分页
         List<ProductReview> reviews = lambdaQuery()
                 .eq(ProductReview::getReviewerId, userId)
                 .orderByDesc(ProductReview::getReviewAt)
@@ -136,7 +179,7 @@ public class ProductReviewServiceImpl extends ServiceImpl<ProductReviewMapper, P
         }
 
         // selectBatchIds 不保序,按 findReviewableOrderIds 返回的 confirm_time 倒序顺序重组
-        List<ProductOrder> fetched = productOrderMapper.selectBatchIds(reviewableOrderIds);
+        List<ProductOrder> fetched = orderMapper.selectBatchIds(reviewableOrderIds);
         Map<Long, ProductOrder> byId = new HashMap<>();
         if (fetched != null) {
             for (ProductOrder o : fetched) {
@@ -154,4 +197,16 @@ public class ProductReviewServiceImpl extends ServiceImpl<ProductReviewMapper, P
         result.put("reviewableCount", reviewableOrders.size());
         return result;
     }
+
+    /**
+     * 90 天评价窗口判定:confirmTime 存在且 >= now - 90d。
+     */
+    private boolean inReviewWindow(Date confirmTime) {
+        if (confirmTime == null) {
+            return false;
+        }
+        Calendar cal = Calendar.getInstance();
+        cal.add(Calendar.DAY_OF_MONTH, -REVIEW_WINDOW_DAYS);
+        return !confirmTime.before(cal.getTime());
+    }
 }

+ 1 - 0
docs/superpowers/api/API_REFERENCE.md

@@ -670,6 +670,7 @@ find cfc-backend/src/main/java -name "*XxxService.java" -o -name "*XxxController
 | `POST /api/product/order/ship` | 服务商/管理端发货(填物流单号+快递公司)。发货成功后自动调用微信「小程序交易管理服务」`upload_shipping_info` 同步物流到微信订单管理(用户在微信侧收发货通知/查物流/确认收货);自提订单或无单号跳过;失败只记日志不阻塞(fail-open);`wechat.test-mode=true` 或 `wechat.fulfillment-enabled=false`(环境变量 `WECHAT_FULFILLMENT_ENABLED`)时跳过 |
 | `POST /api/product/order/review/update` | 供应商审核修改待支付订单(修改价格/配送方式/添加优惠券/赠品) |
 | `POST /api/product/review/create` | 创建商品订单评价(能力键 `shop.review.create`;普通商品订单 completed 后一单一评:综合星级1-5+文字≤500字+晒图≤3张、确认收货90天内,独立表 product_reviews,活动评价零污染) |
+| `POST /api/product/review/detail` | 商品评价详情/去评价按钮态(能力键 `shop.review.detail`;入参 `{orderId}`,出参 `ProductReviewResponse`:review 已评记录未评为 null / canReview 可评态(completed 且 90 天窗口内且未评时 true)/ reviewHint 提示文案) |
 | `POST /api/product/review/my` | 我的评价 + 待评价入口(能力键 `shop.review.my`;登录买家本人:`{reviews[], reviewableOrders[], reviewableCount}`,reviews=按评价时间倒序分页的我的评价列表,reviewableOrders=待评价订单(completed 且 90 天内且未评且非 activity 的买家本人订单),reviewableCount=待评价条数) |
 | `POST /api/cart/add` | 加入购物车 |
 | `POST /api/cart/list` | 购物车列表 |