Răsfoiți Sursa

feat(growth-plan): S-cfc-382 plan.draft.save 方案草稿保存与恢复(SC-P-81)

使红契约测试 PlanDraftSaveContractTest 转绿(10/10):
- GrowthPlan 实体增 draftExpiresAt / draftVersion 字段
- GrowthPlanService 增 saveDraft / restoreDraft(id) / restoreDraft(id,userId) /
  isDraftExpired / isDraftVersionConflict(status=draft + now+7天有效期 +
  版本号递增;过期抛『草稿已失效』;越权 403『无权限』不泄露;服务端版本>本地即冲突)
- GrowthPlanController 增 POST /draft-save 与 /draft-restore 端点(统一 @PostMapping)
- schema.sql growth_plans 增 draft_expires_at / draft_version 列
- DatabaseInitializer 迁移496 ensureColumn 幂等补列
Administrator 2 zile în urmă
părinte
comite
3e024736dd

+ 17 - 0
cfc-backend/src/main/java/com/etotem/cfc/config/DatabaseInitializer.java

@@ -3643,6 +3643,9 @@ insertSysConfigSeed("gift_membership_pay_price", "198000", "送会员商品达
 
         // 迁移495: coupon_gift_transfer 增列 share_token / claim_method(记录分享领取方式,§4.2)
         addCouponGiftTransferShareColumns();
+
+        // 迁移496: growth_plans 增列 draft_expires_at / draft_version(SC-P-81 方案草稿保存与恢复,能力键 plan.draft.save)
+        addGrowthPlanDraftColumns();
     }
 
 
@@ -16808,4 +16811,18 @@ log.info("迁移298: 已为无 openid 的 child 账号补齐 family_members 记
                 "VARCHAR(16) NOT NULL DEFAULT 'DIRECT' COMMENT '领取方式: DIRECT=定向转赠 SHARE=分享转赠(存量行默认DIRECT)'");
         log.info("迁移495: coupon_gift_transfer.share_token / claim_method 列已就绪");
     }
+
+    /**
+     * 迁移496: growth_plans 增列 draft_expires_at / draft_version(SC-P-81 方案草稿保存与恢复,能力键 plan.draft.save)。
+     *
+     * <p>draft_expires_at:草稿有效期(存草稿时 now+7 天),恢复时超期判定『草稿已失效』的持久化基础(TC-P-81-E);
+     * draft_version:草稿版本号(并发存两版草稿:后者覆盖且提示冲突,TC-P-81-E)。ensureColumn 幂等。</p>
+     */
+    private void addGrowthPlanDraftColumns() {
+        ensureColumn("growth_plans", "draft_expires_at",
+                "DATETIME NULL COMMENT '草稿有效期(SC-P-81 草稿保存/恢复,plan.draft.save)'");
+        ensureColumn("growth_plans", "draft_version",
+                "INT NULL COMMENT '草稿版本号(并发存两版草稿:后者覆盖且提示冲突)'");
+        log.info("迁移496: growth_plans.draft_expires_at / draft_version 列已就绪(plan.draft.save / SC-P-81)");
+    }
 }

+ 43 - 0
cfc-backend/src/main/java/com/etotem/cfc/controller/growth/GrowthPlanController.java

@@ -238,4 +238,47 @@ public class GrowthPlanController {
 
         return Result.success(resultMap);
     }
+
+    /**
+     * 存草稿(SC-P-81 正常流:计划创建前暂存未完,能力键 plan.draft.save)。
+     * 持久化 status=draft + 有效期 draftExpiresAt(now+7 天)+ 版本号递增。
+     */
+    @Operation(summary = "保存成长方案草稿(SC-P-81 存草稿,status=draft + 有效期)")
+    @PostMapping("/draft-save")
+    public Result<GrowthPlan> saveDraft(@RequestBody GrowthPlan plan,
+                                         @RequestAttribute("userId") Long userId) {
+        if (plan.getMemberId() == null) {
+            return Result.error("请选择家庭成员");
+        }
+        plan.setTeacherId(userId);
+        try {
+            GrowthPlan saved = growthPlanService.saveDraft(plan);
+            return Result.success(saved);
+        } catch (IllegalStateException e) {
+            return Result.error(e.getMessage());
+        }
+    }
+
+    /**
+     * 恢复草稿继续编辑(SC-P-81 正常流/异常流/权限流,能力键 plan.draft.save)。
+     * 过期 → 提示『草稿已失效』;越权(非归属)→ 403 拒绝,不泄露他人草稿。
+     */
+    @Operation(summary = "恢复成长方案草稿(SC-P-81 恢复继续编辑;过期提示草稿已失效;越权 403)")
+    @PostMapping("/draft-restore")
+    public Result<GrowthPlan> restoreDraft(@RequestBody Map<String, Object> body,
+                                            @RequestAttribute("userId") Long userId) {
+        Long draftId = ParamUtils.getLong(body.get("draftId"));
+        if (draftId == null) {
+            return Result.error("draftId不能为空");
+        }
+        try {
+            GrowthPlan restored = growthPlanService.restoreDraft(draftId, userId);
+            if (restored == null) {
+                return Result.error("草稿不存在");
+            }
+            return Result.success(restored);
+        } catch (IllegalStateException e) {
+            return Result.error(e.getMessage());
+        }
+    }
 }

+ 4 - 0
cfc-backend/src/main/java/com/etotem/cfc/entity/GrowthPlan.java

@@ -42,6 +42,10 @@ public class GrowthPlan implements Serializable {
 
     private Integer reviewCount;  // 已复盘次数
 
+    private Date draftExpiresAt;  // 草稿有效期(SC-P-81 草稿保存/恢复,能力键 plan.draft.save;超期判定『草稿已失效』)
+
+    private Integer draftVersion;  // 草稿版本号(并发存两版草稿:后者覆盖且提示冲突)
+
     private Date createdAt;
 
     private Date updatedAt;

+ 98 - 0
cfc-backend/src/main/java/com/etotem/cfc/service/GrowthPlanService.java

@@ -254,4 +254,102 @@ public class GrowthPlanService {
         plan.setUpdatedAt(new Date());
         return growthPlanMapper.updateById(plan) > 0;
     }
+
+    /** 草稿默认有效期 7 天(SC-P-81 边界:草稿有效期) */
+    private static final long DRAFT_VALIDITY_MS = 7L * 24L * 3600_000L;
+
+    /**
+     * 存草稿(SC-P-81 正常流:计划创建前暂存未完,能力键 plan.draft.save)。
+     *
+     * <p>持久化 {@code status="draft"};设置 {@code draftExpiresAt = now + 7 天}(有效期边界);
+     * 并发存两版草稿:{@code draftVersion} 递增,后存覆盖前存(TC-P-81-E 冲突检测依据)。
+     * 已有 id 为更新(版本号+1,后存覆盖),无 id 为新建。</p>
+     */
+    public GrowthPlan saveDraft(GrowthPlan plan) {
+        if (plan.getStatus() == null || !"draft".equals(plan.getStatus())) {
+            plan.setStatus("draft");
+        }
+        plan.setDraftExpiresAt(new Date(System.currentTimeMillis() + DRAFT_VALIDITY_MS));
+        if (plan.getId() != null) {
+            GrowthPlan existing = growthPlanMapper.selectById(plan.getId());
+            if (existing != null) {
+                plan.setDraftVersion((existing.getDraftVersion() != null ? existing.getDraftVersion() : 0) + 1);
+            } else {
+                plan.setDraftVersion(1);
+            }
+            plan.setCreatedAt(existing != null ? existing.getCreatedAt() : new Date());
+            plan.setUpdatedAt(new Date());
+            growthPlanMapper.updateById(plan);
+        } else {
+            plan.setDraftVersion(1);
+            plan.setCreatedAt(new Date());
+            plan.setUpdatedAt(new Date());
+            growthPlanMapper.insert(plan);
+        }
+        return plan;
+    }
+
+    /**
+     * 恢复草稿继续编辑(SC-P-81 正常流,能力键 plan.draft.save)。
+     *
+     * <p>草稿不存在返回 null;已超有效期抛 {@link IllegalStateException}『草稿已失效』
+     * (TC-P-81-E 异常流提示);有效期内返回可继续编辑的草稿(status 保持 draft)。</p>
+     */
+    public GrowthPlan restoreDraft(Long draftId) {
+        GrowthPlan plan = growthPlanMapper.selectById(draftId);
+        if (plan == null) {
+            return null;
+        }
+        if (isDraftExpired(plan)) {
+            throw new IllegalStateException("草稿已失效");
+        }
+        return plan;
+    }
+
+    /**
+     * 权限恢复(SC-P-81-P 越权拒绝,不泄露他人草稿,能力键 plan.draft.save)。
+     *
+     * <p>归属判定:{@code userId} 须等于草稿创建人 {@code teacherId}(方案由
+     * 规划师/家长创建,创建人即归属方)。非归属 → 抛 {@link IllegalStateException}
+     *『无权限』(403 拒绝,不返回他人草稿);归属 → 恢复,过期则抛『草稿已失效』。</p>
+     */
+    public GrowthPlan restoreDraft(Long draftId, Long userId) {
+        GrowthPlan plan = growthPlanMapper.selectById(draftId);
+        if (plan == null) {
+            // 方案不存在:统一 403 口径拒绝,不泄露任何草稿信息
+            throw new IllegalStateException("无权限:草稿不存在");
+        }
+        if (userId == null || !userId.equals(plan.getTeacherId())) {
+            throw new IllegalStateException("无权限");
+        }
+        if (isDraftExpired(plan)) {
+            throw new IllegalStateException("草稿已失效");
+        }
+        return plan;
+    }
+
+    /**
+     * 草稿是否已超有效期({@code draftExpiresAt < now},TC-P-81-E『草稿已失效』判定)。
+     * 无有效期记录的存量草稿视为未过期(安全默认,不阻断历史数据恢复)。
+     */
+    public boolean isDraftExpired(GrowthPlan draft) {
+        if (draft == null || draft.getDraftExpiresAt() == null) {
+            return false;
+        }
+        return draft.getDraftExpiresAt().getTime() < System.currentTimeMillis();
+    }
+
+    /**
+     * 并发检测(TC-P-81-E:后存覆盖前存且提示冲突)。
+     *
+     * <p>服务端已存版本 &gt; 本地版本 → 冲突(true,提示用户重新拉取);
+     * 本地版本 ≥ 服务端版本 → 无冲突(false)。草稿不存在时返回 false(无版本可比对)。</p>
+     */
+    public boolean isDraftVersionConflict(Long draftId, long localVersion) {
+        GrowthPlan plan = growthPlanMapper.selectById(draftId);
+        if (plan == null || plan.getDraftVersion() == null) {
+            return false;
+        }
+        return plan.getDraftVersion() > localVersion;
+    }
 }

+ 2 - 0
cfc-backend/src/main/resources/schema.sql

@@ -522,6 +522,8 @@ CREATE TABLE IF NOT EXISTS growth_plans (
     start_date DATE,
     end_date DATE,
     review_count INT DEFAULT 0 COMMENT '已复盘次数',
+    draft_expires_at DATETIME DEFAULT NULL COMMENT '草稿有效期(SC-P-81 草稿保存/恢复,plan.draft.save)',
+    draft_version INT DEFAULT NULL COMMENT '草稿版本号(并发存两版草稿:后者覆盖且提示冲突)',
     created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
     updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
     INDEX idx_child_id (child_id),