2026-10-25-task-complete-500-bug.md 11 KB

睡眠打卡完成接口 500 与双身份任务列表——根因诊断与修复设计

环境:生产 cfc.etotem.com.cn 现象(用户原话):从首页任务进睡眠打卡,完成后 POST /api/tasks/2964/complete 返回 {"code":500,"message":"任务不存在、无权完成或状态已变更","data":null},但首页任务确实取消掉了。 任务列表页面,本人和本人所对应的成员依然同时存在,且对应的任务列表不同。 诊断日期:2026-10-25


一、结论速览(单一事实源)

500 的根因 = 双身份(数据)+ 重复完成(流程)叠加:

  1. 睡眠打卡是每日进度型任务,由 POST /api/health/sleep/create 在落库后自动完成(达标即 status=completed)。
  2. 前端 sleep-checkin.vue 在 create 成功后又冗余调用一次 POST /api/tasks/{id}/complete(代码自述"后端按 taskId 置为 completed",但这一步其实已由 create 完成)。
  3. 用户存在两条 family_members 行("本人" 与 "本人所对应的成员",同 user_id 指向同一家长,即已知的"家长本人"重复记录)。
    • 每日任务 2964 挂在成员 M_task 上(生成器写入的 familyMemberId)。
    • 前端操作视角成员为 M_front(来自 URL ?memberId= 或本地 currentMemberId 存储),与 M_task 不同。
  4. create 内部有"以任务归属为准修正成员"的逻辑(HealthSleepController.create 76–80 行),把打卡记录纠回 M_task 并完成 → 首页卡片消失(用户所见"确实取消掉了")。
  5. 但冗余 /complete 传入的是 M_front ≠ M_task,命中 TaskService.completeTask 第 587 行 if (task == null || !Objects.equals(task.getFamilyMemberId(), memberId)) return null; → 返回 null → TaskController.completeTask 第 139 行返回 500。
  6. 任务列表页把 M_task 与 M_front 当作两个独立可切换身份呈现,二者 familyMemberId 不同,故"对应的任务列表不同"。

即使不存在双身份(M_task == M_front),冗余 /complete 也会命中第 591 行(status 已是 completed) 同样返回 null → 500。所以双身份让 500 经行 587 触发,无双身份则经行 591 触发,两种都成立。


二、证据链(文件:行号,已逐行核实)

2.1 报错出口

  • controller/task/TaskController.java:109-140 completeTask:
    • 118 行 memberId = dto.getMemberId() != null ? dto.getMemberId() : currentMemberId;(前端显式传 self.memberId)
    • 137-139 行:taskService.completeTask 返回 null → Result.error("任务不存在、无权完成或状态已变更")。
  • service/TaskService.java:585-672 completeTask:
    • 587 行:if (task == null || !Objects.equals(task.getFamilyMemberId(), memberId)) return null;(身份不匹配)
    • 591 行:if ("completed".equals(task.getStatus()) || "pending_review".equals(task.getStatus())) return null;(已完成)

2.2 打卡"自动完成"链路(首页卡片消失的真正原因)

  • controller/HealthSleepController.java:57-95 create:
    • 76-80 行:若 record.getMemberId() != linkedTask.getFamilyMemberId(),则 record.setMemberId(linkedTask.getFamilyMemberId());(以任务归属为准,防串号)。
    • 81-86 行:每日进度型任务调用 taskService.updateCheckinTaskProgress(record.getTaskId(), fm.getUserId(), fm.getId(), 1); 其中 fm.getId() = 已修正为 M_task。
  • service/TaskService.java:1784-1848 updateCheckinTaskProgress:
    • 1795 行:校验 task.getFamilyMemberId().equals(familyMemberId)(M_task),不符则跳过。
    • 1843-1847 行:progress≥target 时调用 awardTaskCompletionRewards(...)。
  • service/TaskService.java:893-921 awardTaskCompletionRewards:
    • 918 行 task.setStatus("completed"); + 921 行 taskMapper.updateById(task);(真落库,updateCheckinTaskProgress 注释"status 写入 completed"属实)。

2.3 前端冗余调用(bug 触发器)

  • cfc-frontend/pages/growth/sleep-checkin.vue doCheckin(413-465):

    • 424 行 POST /api/health/sleep/create(带 taskId)。
    • 439 行 toast「打卡成功,任务已完成」(前端已认定完成)。
    • 448-452 行:

      // 联动任务(来自首页「我的任务」?taskId=):显式将对应每日任务标记完成,
      // 后端按 taskId 置为 completed,返回首页后卡片才会消失
      if (self.taskId) {
      completeTaskApi(self.taskId, self.memberId || null, '').catch(function () {})
      }
      

      注释与实现错位:卡片消失其实由 create 的自动完成造成,这一步 /complete 是多余的,且传 self.memberId(M_front)。

    • self.memberId 来源(293-305 行):options.memberId || uni.getStorageSync('currentMemberId'),即首页卡片下钻时带入的成员,可能与任务实际归属 M_task 不同。

2.4 双身份数据根因("本人 / 本人所对应的成员")

  • config/JwtInterceptor.java:174-190:
    • currentMemberId / familyMemberId 取自 family_members WHERE user_id=userId AND family_id=familyId .last("LIMIT 1")(177-182 行)。
    • 多行同 (user_id, family_id) 时 LIMIT 1 非确定性取首行 → 不同请求可能解析到 M_task 或 M_front。
  • service/EnergyService.java:121 与 :263 注释明确: > family_members 可能包含"家长本人"的重复记录(user_id 指向家长); > 排除 user_id 指向家长本人的重复记录,并对同一孩子账号只保留一条。 → 说明该重复是已知存量问题,服务层已多处手工去重规避,但任务系统未统一处理。
  • dto/FamilyMemberVO.java:88:isSelf(是否当前登录用户本人)用于前端切换/移除权限判断; 成员切换器把"本人"与"本人所对应的成员"列为两个可选项 → 任务列表按各自 familyMemberId 过滤,故不同。

三、修复方案(按风险与收益排序)

修复 A(生产热修 · 后端 · 必做 · 低危)

让 TaskService.completeTask 对"已完成的本人任务"幂等返回成功,而非返回 null→500。

  • 在 587/591 行逻辑中:若 task.familyMemberId == memberId(或调用者为家庭管理员/家长且任务属本家庭)且 status 已是 completed/pending_review,返回一个成功结果 (复用既有 result 结构:pointsEarned=0, newBalance=当前积分, needReview=false, alreadyCompleted=true),不再吐 500。
  • 收益:不依赖前端发版即可立即消除全部用户的该 500(覆盖行 587 与行 591 两种触发)。
  • 风险:极低。幂等完成是 REST 标准做法;不会改变奖励(已在 updateCheckinTaskProgress 发过,awardTaskCompletionRewards 对已完成任务幂等跳过)。
  • 落点:service/TaskService.java:585-593;controller/TaskController.java:118-139(可选:将"已完成的本人任务"从 500 文案改为成功,或保留错误仅对本人任务放行)。

修复 B(正本清源 · 前端 · 必做)

删除 sleep-checkin.vue 448-452 行的冗余 /complete 调用。

  • 理由:create 已按任务归属自动完成(并自纠成员),/complete 纯属多余且会在双身份/已完成时失败。
  • 同步检查其它打卡页是否同样冗余调用 /complete:pages/health/daily-checkin.vue、pages/growth/diet-checkin.vue、pages/growth/exercise-checkin.vue、pages/wealth-sub/checkin.vue、pages/mind-detail/emotion-checkin.vue、pages/body-detail/checkin.vue。凡"打卡 create 已自动完成 + 又调 /complete"的一律移除或改为幂等。
  • 收益:消除重复完成路径,避免未来任何类似 500。

修复 C(数据根治 · 双身份 · 中危 · 需授权)

清理 family_members 中同 (user_id, family_id) 的重复"家长本人"记录,并加约束防止再生。

  • 诊断 SQL(先在从库/备份验证,禁止直连生产主库盲改):

    -- 1) 找出同一 (user_id, family_id) 的多余成员行
    SELECT user_id, family_id, COUNT(*) c, GROUP_CONCAT(id) ids
    FROM family_members
    GROUP BY user_id, family_id
    HAVING c > 1;
    
    -- 2) 聚焦"家长本人"型(user_id 指向有 openid 的可登录用户,且存在多条)
    SELECT fm.* FROM family_members fm
    JOIN user u ON u.id = fm.user_id AND u.openid IS NOT NULL
    WHERE (fm.user_id, fm.family_id) IN (
      SELECT user_id, family_id FROM family_members
      GROUP BY user_id, family_id HAVING COUNT(*) > 1
    )
    ORDER BY fm.user_id, fm.family_id, fm.id;
    
  • 合并策略(需 DBA + 业务确认,严禁脚本自动删):

    • 保留一条(优先保留 status='active'、积分/打卡数据更全、或被任务/报告外键引用最多的那行)作为该用户的唯一成员身份;
    • 将其他重复行上的 tasks.family_member_id、task_executions.member_id、health_*、points_log.child_id 等外键迁移到保留行;
    • 删除被合并的重复行;
    • 加唯一索引 UNIQUE (user_id, family_id)(允许 user_id IS NULL 的 local 成员存在多条,用部分唯一索引或应用层兜底)。
  • 代码侧配合:

    • JwtInterceptor 的 LIMIT 1 改为确定性取值(优先 status='active' 且 userId 匹配的"主成员"),避免解析漂移。
    • 成员切换器(FamilyMemberVO.isSelf)对"本人"去重,不再把同一用户的两条成员当作两个身份。

四、任务拆分(建议入池)

编号 内容 类型 风险 是否需 prod 授权
T24-A completeTask 幂等:已完成本人任务返回成功 后端热修 低 是(仅部署到 prod 时需 --allow-prod)
T24-B 移除打卡页冗余 /complete 调用 + 全量排查 前端 低 否(发版流程)
T24-C family_members 重复行诊断 SQL 产出 数据 中 是(只读诊断可先跑)
T24-D 重复成员合并迁移 + 唯一约束 + 拦截器确定性解析 数据+后端 中高 是(写操作需授权)

五、待用户拍板事项

  1. 是否同意先上修复 A(后端幂等)作为生产热修——可立即消除 500,不依赖前端发版。
  2. 是否授权对生产库只读跑诊断 SQL(T24-C)以确认受影响用户/家庭范围。
  3. 双身份合并(T24-D)涉及写库与外键迁移,必须在备份 + DBA 复核后单独授权执行,不在本次热修范围内。

六、复盘教训(沉淀)

  • "打卡 create 自动完成" 与 "前端再调 /complete" 是两条完成路径并存的设计债:新增自动完成后未回收前端旧调用。
  • family_members 重复"家长本人"记录是跨模块存量问题,EnergyService 已多处手工规避,但任务/报告/打卡等模块未统一收敛;应在数据层 + 拦截器解析层一次性根治,而非各处打补丁。
  • 500 文案 "任务不存在、无权完成或状态已变更" 把"已完成"与"无权限"混为一谈,既不友好也掩盖真实原因;建议拆分文案(已完成→成功/已领取;无权限→无权)。