Página Principal Explorar Ajuda
Registe-se Iniciar Sessão
liaoxg
/
cfc
1
1
Fork 0
Ficheiros Problemas 0 Pull Requests 0 Wiki
Árvore: 4f57e5842d
Ramos Etiquetas
cfc
/
docs
/
analysis
/
circle-feature-analysis.md

circle-feature-analysis.md 10 KB
Histórico Em bruto

圈子功能分析报告：需求 · 设计 · 实现

日期：2026-09-05 范围：社交圈子（social_circle）、健康圈子（health_circle）、圈子挑战（circle_challenge） 基准：按当前代码事实撰写（cfc-backend / cfc-frontend / cfc-web） 用途：需求-设计-实现三端对齐基线；含已发现的 Bug 清单与修复状态跟踪

1. 功能全景（3 大模块）

模块 后端实体/表 Controller 前端页面
社交圈子 social_circle / _member / _post / _like / _comment CircleController (/api/circle) discover/circles、discover/circle-feed、discover/create-circle
健康圈子 health_circle / _member HealthCircleController (/api/health/circle) 无独立页面（排行榜组件挂在 parent-index）
圈子挑战 circle_challenge CircleChallengeController (/api/health/circle/challenge) 无独立页面

2. 需求/设计文档

文档 要点
docs/flows/circle-contact-flow.md 权威需求文档：4 阶段 24 端点全量定义
docs/superpowers/specs/2026-07-27-circle-replace-octopus-design.md 行首页 OctopusGraph → 圈子区块替换设计
docs/superpowers/plans/2026-07-27-circle-replace-octopus.md 对应实现计划
docs/superpowers/specs/2026-08-06-family-challenge-flow-design.md 家庭挑战基线（明确圈子挑战不在其范围）
docs/superpowers/specs/2026-08-08-family-challenge-participation-design.md 家庭挑战参与设计

3. 后端实现清单

3.1 社交圈子（14 接口，完整）

CircleController + CircleService + CirclePostService + CircleMatchService

端点 功能
POST /api/circle/my-circles 我的圈子列表
POST /api/circle/discover 推荐圈子（公开 + 匹配引擎）
POST /api/circle/create 创建圈子（含 joinCondition/reviewRequired/isPublic）
POST /api/circle/update 更新圈子
POST /api/circle/join 加入（审核制置 pending）
POST /api/circle/leave 退出
POST /api/circle/members 成员列表
POST /api/circle/feed 单圈动态（分页，成员校验）
POST /api/circle/feed/multi 多圈合并动态
POST /api/circle/post/create 发布动态（7 种类型）
POST /api/circle/post/delete 删除帖子（软删，仅作者）
POST /api/circle/post/like 点赞/取消
POST /api/circle/comment/add 评论（支持嵌套回复 parentId）
POST /api/circle/comment/list 评论列表（含 replies）

3.2 健康圈子（5 接口）

HealthCircleController + HealthCircleService

端点 功能
POST /api/health/circle/list 家庭所属健康圈（每家庭限 3 个）
POST /api/health/circle/create 创建（生成 6 位邀请码，memberLimit=20）
POST /api/health/circle/join 邀请码加入
POST /api/health/circle/leave 退出（软标记 left）
POST /api/health/circle/ranking 圈内家庭健康积分排行

3.3 圈子挑战（2 接口，仅查询）

CircleChallengeController + CircleChallengeService

端点 功能
POST /api/health/circle/challenge/list 活跃挑战（空时自动生成 3 个模板）
POST /api/health/circle/challenge/history 已完成挑战

4. 匹配引擎（CircleMatchService）

6 大匹配源，基于五维数据发现共同点：

匹配源 数据依据 规则
共同活动圈 activity_registration 参与同一活动
认知能力圈 dan_assessment_result (COG) 子分差 < 10
情绪成长圈 dan_assessment_result (EMI) 子分差 < 10
健康生活圈 health_report 总分差 < 15
好物分享圈 product_order 购买同一商品
规划师同门圈 family.teacher_id 同一规划师

⚠️ 数据污染隐患：getOrCreateRecommendation 在发现时自动创建圈子（memberCount=1）， 会导致 social_circle 被大量单成员自动圈子填充，且 isPublic=1 永远出现在推荐列表。

5. 问题清单与修复状态

# 级别 问题 影响 状态
BUG-A 🔴 严重 create-circle.vue 导入 createCircle（=/api/health/circle/create），应使用 createGeneralCircle（=/api/circle/create）；createGeneralCircle 目前是死代码 社交圈子创建从未生效：表单字段被健康圈接口丢弃；孩子端因无 familyId 报"请先创建或加入家庭" ✅ 已修复
BUG-B 🔴 严重 parent-index.vue 的 loadHealthCircle() 调 getCircleRanking({}) 传空对象，无 circleId；getCircleList 从未被调用 健康圈排行榜永远返回空 map，CircleRanking.vue 永远显示"暂无健康圈数据" ✅ 已修复
GAP-C1 🟠 缺失 /api/circle/update 无前端入口 圈子信息无法编辑 ✅ 已修复
GAP-C2 🟠 缺失 approveMember() 无 Controller 端点暴露、无任何端审批 UI 审核制圈子（joinCondition=1）申请永远卡 pending，功能不可用 ✅ 已修复
GAP-C3 🟠 缺失 /api/circle/post/delete 无前端入口 帖子无法删除（虽有软删接口） ✅ 已修复
GAP-C4 🟠 缺失 健康圈子 5 接口仅有 ranking 被（错误地）调用，list/create/join/leave 无页面 健康圈子整体对用户不可触达 待办
GAP-C5 🟠 缺失 圈子挑战无 updateProgress/checkAndSettle/settleChallenge（对比 FamilyChallengeService 齐全）；仅 list/history 查询 挑战自动生成后永远 active，无法打卡/结算/完成，历史永远为空；且前端无任何调用 待决策
BUG-D 🟡 体验 CirclePostService.buildPostDetailList 不返回作者昵称/头像；前端 getMemberName() 硬编码返回"我" 所有帖子作者都显示为"我" ✅ 已修复
BUG-E 🟡 体验 circle-feed.vue 的 <scroll-view> 未绑定 @scrolltolower="onScrollToLower" 帖子分页加载永不触发，只显示第一页 ✅ 已修复
BUG-F 🟡 体验 loadMoreComments() 空实现、sharePost() 仅 toast"开发中" 查看全部评论/分享不可用 ✅ 已修复
RISK-1 ⚠️ 隐患 匹配引擎自动创建圈子（memberCount=1）+ 全表 selectList 内存计算 数据污染 + 大数据量性能问题 待评估
RISK-2 ⚠️ 治理 帖子/评论无任何端的内容审核入口 内容风险无管控 待评估

6. 修复记录

2026-09-05 第一批修复

  • BUG-A：create-circle.vue 改用 createGeneralCircle
  • BUG-B：parent-index.vue 的 loadHealthCircle() 补 getCircleList 取值流程
  • BUG-D：后端 buildPostDetailList 补 authorName/authorAvatar；前端改用真实昵称

2026-09-05 第二批修复

  • GAP-C2：审批链路闭环
    • 后端：CircleService.getPendingMembers(adminMemberId, memberType)（查当前用户作为 admin 的圈子中 pending 成员，经 UserMapper 批量带出申请人昵称/头像）；approveMember 增加 admin 权限校验（adminMemberId 非圈主则拒绝）
    • 后端：CircleController 新增 POST /api/circle/pending-members 与 POST /api/circle/approve（审批人优先取 currentMemberId，可回退 adminMemberId）
    • 前端：utils/api.js 新增 getPendingCircleMembers / approveCircleMember
    • 前端：circles.vue 新增"⏳ 待审核成员"区块（申请人昵称/头像 + 圈子名 + 申请时间 + 同意/拒绝按钮，onApprove 操作后刷新），空列表自动隐藏
    • 修订（2026-09-05）：圈子 member_id 关联的是 users 表主键（用户确认），非 family_members。getPendingMembers 申请人昵称/头像查询由 FamilyMemberMapper 改为 UserMapper；同批修正 CirclePostService.buildPostDetailList 作者昵称/头像查询（BUG-D 修复亦改用 UserMapper）

2026-09-05 第三批修复

  • GAP-C3：帖子删除入口
    • 前端：circle-feed.vue 动态操作栏新增"🗑 删除"按钮（仅 post.memberId === myMemberId 且 !post.deleting 时显示）；deletePost() 弹确认框后调 deleteCirclePost({circleId, postId, memberId})，成功则从列表移除
    • 前端：utils/api.js 的 deleteCirclePost wrapper 原本已存在，本次接线使用
  • BUG-E：分页滚动绑定
    • 前端：circle-feed.vue 的 <scroll-view> 补绑定 @scrolltolower="onScrollToLower"，滚动到底触发下一页加载
  • BUG-F：评论全量加载与分享
    • 前端：loadMoreComments() 实现——getCircleComments({postId, page:1, size:100}) 拉全量后 $set(post, 'showAllComments', true)（Vue 2 需 $set 保证新属性响应式）；collapseComments() 收起；getVisibleComments() 默认只展前 3 条、展开后全量；新增 getCommentKey/getCommentName/getCommentAvatar 辅助方法（优先取评论响应中的 authorName/authorAvatar，回退成员列表昵称）
    • 前端：sharePost() 实现——uni.showActionSheet 提供"复制内容分享 / 保存图片并分享"（uni.setClipboardData / uni.saveImageToPhotosAlbum）
    • 后端：CirclePostService.getComments 评论及 replies 补 authorName/authorAvatar（经 UserMapper 批量查询，评论 member_id = user.id）；CircleService.getCircleMembers 返回项补 nickname/avatar，供成员弹窗与评论名字回退显示
  • circle-feed.vue 模板校验（node --check EXIT=0）、后端 mvn compile EXIT=0、CI audit 无新增 ERROR（仅预存 report-list.vue 1 处）

2026-09-05 第四批修复

  • GAP-C1：圈子编辑入口
    • 前端：circles.vue 我的圈子卡片右侧新增"✏️ 编辑"按钮（仅 item.role === 'admin' 可见，getMyCircles 已返回 role 字段）；新增编辑弹窗（圈子名称 / 简介 / 加入方式：自由加入 ↔ 审核制）
    • 前端：saveEdit() 调 updateCircle({circleId, name, description, joinCondition})，成功 toast 后 loadData() 刷新；updateCircle wrapper 原本已存在，本次接线
    • 校验：circles.vue script node --check EXIT=0；CI audit 复跑仍仅预存 report-list.vue 1 处 ERROR，未新增

待办（后续批次）

  • GAP-C4：健康圈子独立页面（列表/创建/邀请码加入）
  • GAP-C5：圈子挑战结算链路（需产品确认是否保留）
  • RISK-1：匹配引擎改为"仅推荐已存在圈子"或控制自动创建频率