cfc/docs/requirements-completion-report.md

知心益家 (ZXYJ) - 需求完成情况综合报告

生成时间: 2026-04-09
报告范围: 指导师功能、小游戏功能、连续打卡功能
审计方法: 代码实证 + 需求文档交叉验证

---

📊 总体完成度概览

功能模块	需求文档定义	代码实现状态	端到端可用性	完成度
指导师功能	7项需求已定义	后端基本完整	小程序端未完全闭环	70%
小游戏功能	方向性描述	三端完整实现	存在语义不一致	85%
连续打卡	4项需求已定义	核心链路打通	缺自动调度	75%

---

一、指导师功能完成情况

1.1 需求清单与状态

需求编号	需求描述	文档状态	代码验证结果	优先级
GUIDE-01	首次登录角色选择	✅ 已实现	✅ 基本成立	-
GUIDE-02	指导师信息录入	✅ 已实现	⚠️ 后端未持久化	P0
GUIDE-03	查看家庭任务	✅ 已实现	⚠️ 查询逻辑疑点	P1
GUIDE-04	审核任务	✅ 已实现	⚠️ DTO字段不一致	P1
GUIDE-05	分享码绑定家庭	✅ 已实现	✅ 成立	-
GUIDE-06	接受家长咨询	✅ 已实现	✅ 成立	-
GUIDE-07	调整任务	✅ 已实现	✅ 成立	-

1.2 关键缺陷详情

🔴 P0: 指导师信息入库缺口

问题描述: UpdateUserDTO 包含 teacherNo/teacherPhoto/certificateImage 字段，但 UserService.updateUserInfo() 未处理这些字段。

影响: 前端提交指导师证书信息后，数据不会落库。

位置:

• DTO: zxyj-backend/src/main/java/com/zxyj/dto/UpdateUserDTO.java
• Service: zxyj-backend/src/main/java/com/zxyj/service/UserService.java

修复建议: 在 updateUserInfo() 方法中添加:

if (dto.getTeacherNo() != null) user.setTeacherNo(dto.getTeacherNo());
if (dto.getTeacherPhoto() != null) user.setTeacherPhoto(dto.getTeacherPhoto());
if (dto.getCertificateImage() != null) user.setCertificateImage(dto.getCertificateImage());

🟡 P1: 家庭检索逻辑疑点

问题描述: getBoundFamilies() 使用 like("teacher_family_ids", String.valueOf(guideId)) 查询，语义不明确。

风险: 如果 ID 为 1，可能误匹配到 10, 11, 21 等包含 1 的记录。

位置: GuideFamilyTaskController.java

修复建议: 改用 JSON 数组查询或单独的关联表。

🟡 P1: 审核DTO字段不一致

问题描述: Controller 批量审核构造 approved 字段，Service 审核判断 result=="pass"。

风险: 若 DTO 未双字段兼容，会导致审核结果偏差。

修复建议: 统一审核字段命名，或在 Service 层兼容两种字段。

1.3 前端实现状态

平台	页面	状态	缺失内容
Web端	指导师中心	✅ 完整	-
Web端	家庭任务管理	✅ 完整	-
Web端	家长咨询	✅ 完整	-
小程序	指导师中心	⚠️ 部分	子页面未实现
小程序	家庭任务管理	❌ 缺失	无对应页面
小程序	咨询功能	⚠️ 部分	API存在，UI不完整

---

二、小游戏功能完成情况

2.1 三款游戏实现状态

游戏	前端页面	评分逻辑	API集成	后端处理	状态
舒尔特方格	✅	✅	✅	✅	完整
猜数字 (1a2b)	✅	⚠️ 语义不一致	✅	⚠️ 字段歧义	部分
数独	✅	⚠️ 验证不完整	✅	✅	部分

2.2 关键缺陷详情

🔴 P0: 1a2b 评分语义不一致

问题描述:

• 后端注释说"5次内完成额外2分"，但代码使用 completionTime < 5
• 前端传递的是游戏用时（秒），而非猜测次数
• 字段名 completionTime 与业务含义冲突

影响: 奖励逻辑可能不会按预期触发。

位置:

• 前端: zxyj-frontend/pages/games/1a2b.vue (line 180)
• 后端: MiniGameService.calculatePoints() 1a2b 分支

修复建议:

1. 修改后端逻辑，根据实际业务需求调整判断条件
2. 或者修改前端，传递猜测次数而非用时

🟡 P1: 数独验证不完整

问题描述: checkSolution() 只检查行、列唯一性，缺少 3x3 宫格验证。

影响: 可能接受不符合数独规则的解。

位置: zxyj-frontend/pages/games/sudoku.vue (line 125-145)

修复建议: 添加宫格验证:

// 检查3x3宫格
for (let boxRow = 0; boxRow < 9; boxRow += 3) {
  for (let boxCol = 0; boxCol < 9; boxCol += 3) {
    const nums = new Set();
    for (let r = boxRow; r < boxRow + 3; r++) {
      for (let c = boxCol; c < boxCol + 3; c++) {
        nums.add(board[r][c]);
      }
    }
    if (nums.size !== 9) return false;
  }
}

🔴 P0: API 权限校验缺失

问题描述: completeMiniGame 接口未验证 userId 与 childId 的关系。

风险: 任何用户都可以为任意孩子提交游戏成绩。

位置: MiniGameController.completeGame()

修复建议: 添加权限校验:

User user = userService.getById(userId);
List<Child> children = childService.getChildrenByFamilyId(user.getFamilyId());
boolean hasAccess = children.stream().anyMatch(c -> c.getId().equals(childId));
if (!hasAccess) {
    return Result.error("无权限操作该孩子数据");
}

2.3 评分规则汇总

后端统一积分计算 (MiniGameService.calculatePoints()):

分数范围	积分计算
score >= 60	basePoints + ((score - 60) / 40) * basePoints
score < 60	basePoints * 0.6
最低保底	1 分

游戏特殊加成:

• 舒尔特方格: 用时 < 30秒 → +2分
• 猜数字: completionTime < 5 → +2分 (语义待澄清)
• 数独: completionTime < 180秒 → +3分

---

三、连续打卡功能完成情况

3.1 需求清单与状态

需求编号	需求描述	文档定义	代码实现	状态
STREAK-001	首页显示连续天数	✅	✅	完成
STREAK-002	火苗图标+天数展示	✅	⚠️	部分
STREAK-003	中断自动重置	✅	⚠️	缺失调度
STREAK-004	里程碑奖励发放	✅	✅	完成

3.2 已实现内容

✅ 数据库表结构:

• streak_milestones: 里程碑定义表 (3/7/30/100天)
• children.streak_days: 当前连续天数
• children.last_task_date: 最后任务日期

✅ 后端服务:

• StreakService.checkAndAwardMilestone(): 检查并发放里程碑奖励
• StreakService.getStreakProgress(): 查询打卡进度
• StreakService.resetStreakIfNeeded(): 断签重置逻辑

✅ API接口:

• GET /api/streak/progress/{childId}: 查询进度
• POST /api/streak/reset: 手动重置

✅ 前端集成:

• child-index.vue: 展示进度条、里程碑弹窗
• utils/api.js: API 封装

3.3 关键缺陷详情

🟡 P1: 缺少自动调度任务

问题描述: 有重置逻辑，但未绑定定时任务。

影响: 断签不会自动重置，需要手动调用 API。

修复建议: 添加定时任务:

@Scheduled(cron = "0 0 0 * * ?") // 每天凌晨执行
public void checkAndResetStreaks() {
    List<Child> children = childMapper.selectList(null);
    for (Child child : children) {
        streakService.resetStreakIfNeeded(child.getId());
    }
}

🟡 P1: API 权限校验缺失

问题描述: /progress/{childId} 未验证当前用户是否有权限查看该孩子。

风险: 任何用户都可以查询任意孩子的打卡记录。

修复建议: 参考小游戏 API 权限校验实现。

🟢 P2: 里程碑解析逻辑脆弱

问题描述: extractMilestoneDays() 使用正则提取数字，如果描述文案变化可能误判。

影响: 低风险，但建议改进。

修复建议: 改用里程碑 ID 或专门的字段标识。

---

四、测试覆盖情况

4.1 已创建测试文件

测试文件	类型	覆盖内容
tests/unit/games/1a2b.spec.js	单元测试	首次猜测满分场景
tests/e2e/mini-games.spec.js	E2E测试	游戏逻辑验证
tests/e2e/mini-games-playwright.spec.js	E2E测试	UI流程测试
tests/integration/mini-games-api.spec.js	集成测试	API端点测试

4.2 缺失测试覆盖

❌ 指导师功能测试: 无对应测试文件 ❌ 打卡功能测试: 无对应测试文件 ❌ API权限测试: 集成测试未覆盖权限校验场景

---

五、修复优先级排序

P0 (高优先级 - 影响核心功能)

1. 指导师信息入库缺口 - 导致证书信息无法保存
2. 小游戏API权限校验 - 安全漏洞，可越权操作
3. 1a2b评分语义不一致 - 奖励逻辑不符合预期

P1 (中优先级 - 影响功能完整性)

1. 数独验证逻辑补全 - 可能接受无效解
2. 打卡自动调度任务 - 断签不会自动重置
3. 打卡API权限校验 - 安全漏洞
4. 指导师家庭检索逻辑 - 可能误匹配
5. 审核DTO字段统一 - 数据一致性风险

P2 (低优先级 - 改进建议)

1. 里程碑解析逻辑加固 - 降低脆弱性
2. 补充测试覆盖 - 提高代码质量

---

六、下一步行动建议

立即执行 (本周)

• 修复指导师信息入库缺口
• 添加小游戏和打卡 API 权限校验
• 澄清 1a2b 评分语义并修正

近期规划 (2周内)

• 完善数独验证逻辑
• 实现打卡自动重置定时任务
• 统一审核 DTO 字段

长期优化 (1月内)

• 补充指导师、打卡功能测试
• 小程序端指导师任务管理页面
• 打卡历史统计与配置界面

---

报告生成者: Sisyphus AI Agent
审计范围: 代码实证 + 需求文档交叉验证
数据来源: 后端代码、前端代码、数据库 schema、需求文档