cfc/docs/flows/family-management-flow.md

用户使用流程图 — 家庭管理

端口说明: 📱 小程序 | 🖥 管理后台 | 📋 规划师端 | ⚙️ 系统自动

分层说明: 🏠 页面 → 🔗 API → ⚙️ Service → 📦 数据实体

flowchart TD
    %% ============ 颜色定义 ============
    classDef page fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    classDef api fill:#fff3e0,stroke:#f57c00,stroke-width:1px
    classDef service fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
    classDef data fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
    classDef external fill:#fce4ec,stroke:#d32f2f,stroke-width:1px,stroke-dasharray:3 2
    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px,stroke-dasharray:5 3

    %% ============ 角色 ============
    A0(("👤 家长")):::actor
    B0(("👶 孩子")):::actor
    C0(("📋 规划师")):::actor

    %% ================================================================
    %% 阶段一：家庭创建与加入
    %% ================================================================
    subgraph 阶段一[阶段一：家庭创建与加入]
        P1["🏠 小程序：家庭首页"]:::page
        P1 -->|"选择操作"| P1_choice{"是否有家庭?"}:::page

        P1_choice -->|"无，创建新家庭"| P1a["🏠 创建家庭页"]:::page
        P1a -->|"家庭名称"| A1["🔗 POST /api/family/user/create-family"]:::api
        A1 -->|"用户ID, 家庭名称"| S1["⚙️ UserService.createFamilyForUser()"]:::service
        S1 -->|"写入一条家庭记录，关联用户"| D1["📦 families + users 表"]:::data

        P1_choice -->|"有，加入其他家庭"| P1b["🏠 输入邀请码页"]:::page
        P1b -->|"邀请码"| A2["🔗 POST /api/family/user/join-family"]:::api
        A2 -->|"用户ID, 邀请码"| S2["⚙️ UserService.joinFamily()"]:::service
        S2 -->|"更新用户家庭ID"| D2["📦 users 表（更新familyId）"]:::data

        D1 -->|"家庭创建成功"| P2["🏠 家庭管理页"]:::page
        P2 -->|"生成邀请二维码"| A3["🔗 POST /api/family/invite/qrcode"]:::api
        A3 -->|"用户ID"| S3["⚙️ QrCodeService.generateQrCodeBase64()"]:::service
        S3 -->|"family.inviteCode"| D3["📦 families 表（读取邀请码）"]:::data

        P2 -->|"生成邀请令牌"| A4["🔗 POST /api/family/invite/generate"]:::api
        A4 -->|"用户ID, 家庭ID"| S4["⚙️ FamilyInvitationService.generateInvitation()"]:::service
        S4 -->|"写入邀请令牌记录"| D4["📦 family_invitations 表"]:::data

        P2 -->|"校验邀请令牌"| A5["🔗 POST /api/family/invite/validate"]:::api
        A5 -->|"token"| S5["⚙️ FamilyInvitationService.validateInvitation()"]:::service
        S5 -->|"令牌有效期+家庭信息"| D4

        P2 -->|"通过邀请码接受邀请"| A6["🔗 POST /api/family/invite/accept-by-code"]:::api
        A6 -->|"用户ID, 邀请码"| S6["⚙️ FamilyInviteController.acceptByCode()"]:::service
        S6 -->|"查询家庭+更新用户familyId"| D2

        P2 -->|"接受邀请令牌"| A7["🔗 POST /api/family/invite/accept"]:::api
        A7 -->|"用户ID, token, 家庭角色, 是否合并"| S7["⚙️ FamilyInvitationService.acceptInvitation()"]:::service
        S7 -->|"加入家庭/合并家庭"| D2

        P2 -->|"查询家庭状态"| A8["🔗 POST /api/family/invite/check-family"]:::api
        A8 -->|"用户ID"| S8["⚙️ FamilyInvitationService.checkUserFamilyStatus()"]:::service
        S8 -->|"用户家庭信息"| D1
    end

    %% ================================================================
    %% 阶段二：家庭成员管理
    %% ================================================================
    subgraph 阶段二[阶段二：家庭成员管理]
        D1 -->|"家庭ID"| P3["🏠 家庭成员管理页"]:::page
        P3 -->|"添加成员"| A9["🔗 POST /api/family/member/add"]:::api
        A9 -->|"用户ID, 昵称, 电话, 头像, 性别, 生日"| S9["⚙️ FamilyMemberService.addMember()"]:::service
        S9 -->|"写入一条家庭成员记录"| D5["📦 family_members 表"]:::data

        P3 -->|"成员列表"| A10["🔗 POST /api/family/member/list"]:::api
        A10 -->|"用户ID"| S10["⚙️ FamilyMemberService.listMembers()"]:::service
        S10 -->|"该家庭所有成员"| D5

        P3 -->|"更新成员信息"| A11["🔗 POST /api/family/member/update"]:::api
        A11 -->|"用户ID, memberId, 昵称/电话/头像"| S11["⚙️ FamilyMemberService.updateMember()"]:::service
        S11 -->|"更新成员记录"| D5

        P3 -->|"切换成员视图"| A12["🔗 POST /api/family/member/switch"]:::api
        A12 -->|"用户ID, memberId"| S12["⚙️ FamilyMemberService.switchToMember()"]:::service
        S12 -->|"切换上下文"| D5

        P3 -->|"检查可编辑性"| A13["🔗 POST /api/family/member/editable"]:::api
        A13 -->|"用户ID, memberId"| S13["⚙️ FamilyMemberService.isEditable()"]:::service
        S13 -->|"布尔值"| D5

        P3 -->|"踢出成员"| A14["🔗 POST /api/family/member/kick"]:::api
        A14 -->|"用户ID, memberId"| S14["⚙️ FamilyMemberService.kickMember()"]:::service
        S14 -->|"删除成员记录"| D5

        P3 -->|"变更日志"| A15["🔗 POST /api/family/member/logs"]:::api
        A15 -->|"用户ID, memberId"| S15["⚙️ FamilyMemberService.getMemberLogs()"]:::service
        S15 -->|"操作日志列表"| D6["📦 family_member_logs 表"]:::data

        P3 -->|"可见成员列表"| A16["🔗 POST /api/family/user/members/visible"]:::api
        A16 -->|"用户ID"| S16["⚙️ UserService.getVisibleMembers()"]:::service
        S16 -->|"对当前用户可见的成员"| D5

        P3 -->|"更新可见性"| A17["🔗 POST /api/family/user/members/update-visibility"]:::api
        A17 -->|"用户ID, memberId, memberType, showToFamily"| S17["⚙️ UserService.updateVisibility()"]:::service
        S17 -->|"更新成员可见性标记"| D5
    end

    %% ================================================================
    %% 阶段三：家庭设置
    %% ================================================================
    subgraph 阶段三[阶段三：家庭设置]
        D5 -->|"成员列表"| P4["🏠 家庭设置页"]:::page
        P4 -->|"创建孩子账号"| A18["🔗 POST /api/family/user/children"]:::api
        A18 -->|"用户ID, 孩子昵称/性别/生日"| S18["⚙️ UserService.createFamilyMember()"]:::service
        S18 -->|"写入孩子记录"| D5

        P4 -->|"孩子列表"| A19["🔗 POST /api/family/user/children/list"]:::api
        A19 -->|"用户ID"| S19["⚙️ UserService.getFamilyMemberren()"]:::service
        S19 -->|"孩子信息列表"| D5

        P4 -->|"更新孩子信息"| A20["🔗 POST /api/family/user/children/update"]:::api
        A20 -->|"用户ID, childId, 昵称/性别/生日"| S20["⚙️ UserService.updateFamilyMember()"]:::service
        S20 -->|"更新孩子记录"| D5

        P4 -->|"家庭成员列表"| A21["🔗 POST /api/family/user/family-members"]:::api
        A21 -->|"用户ID"| S21["⚙️ FamilyUserController.getFamilyMembers()"]:::service
        S21 -->|"家长列表+孩子列表"| D1

        P4 -->|"踢出用户（管理员）"| A22["🔗 POST /api/family/user/kick"]:::api
        A22 -->|"用户ID, targetUserId"| S22["⚙️ FamilyUserController.kickMember()"]:::service
        S22 -->|"清空目标用户familyId"| D2

        P4 -->|"转让管理员"| A23["🔗 POST /api/family/invite/transfer-admin"]:::api
        A23 -->|"用户ID, newAdminId"| S23["⚙️ FamilyInvitationService.transferAdmin()"]:::service
        S23 -->|"更新家庭创建者ID"| D1

        P4 -->|"吊销邀请"| A24["🔗 POST /api/family/invite/revoke"]:::api
        A24 -->|"用户ID, invitationId"| S24["⚙️ FamilyInvitationService.revokeInvitation()"]:::service
        S24 -->|"更新邀请令牌状态"| D4

        P4 -->|"用户信息"| A25["🔗 POST /api/family/user/info"]:::api
        A25 -->|"用户ID"| S25["⚙️ UserService.getUserInfo()"]:::service
        S25 -->|"用户完整信息"| D2

        P4 -->|"更新用户信息"| A26["🔗 POST /api/family/user/update"]:::api
        A26 -->|"用户ID, 昵称/头像"| S26["⚙️ UserService.updateUserInfo()"]:::service
        S26 -->|"更新用户记录"| D2
    end

    %% ================================================================
    %% 阶段四：规划师绑定
    %% ================================================================
    subgraph 阶段四[阶段四：规划师绑定]
        D1 -->|"家庭信息"| P5["🏠 规划师绑定管理页"]:::page
        P5 -->|"待审批列表"| A27["🔗 POST /api/family/teacher-bindings/pending"]:::api
        A27 -->|"用户ID"| S27["⚙️ TeacherFamilyBindingRequestService.getPendingByFamily()"]:::service
        S27 -->|"待审批绑定申请列表"| D7["📦 teacher_family_binding_requests 表"]:::data

        P5 -->|"审批通过"| A28["🔗 POST /api/family/teacher-bindings/approve"]:::api
        A28 -->|"用户ID, requestId"| S28["⚙️ TeacherFamilyBindingRequestService.approve()"]:::service
        S28 -->|"更新申请状态+建立绑定"| D7

        P5 -->|"审批拒绝"| A29["🔗 POST /api/family/teacher-bindings/reject"]:::api
        A29 -->|"用户ID, requestId, reason"| S29["⚙️ TeacherFamilyBindingRequestService.reject()"]:::service
        S29 -->|"更新申请状态为拒绝"| D7

        P5 -->|"已绑定规划师列表"| A30["🔗 POST /api/bind/guides"]:::api
        A30 -->|"用户ID"| S30["⚙️ GuideFamilyService.getGuidesByFamily()"]:::service
        S30 -->|"该家庭绑定的规划师"| D8["📦 guide_families 表"]:::data

        P5 -->|"解除绑定"| A31["🔗 POST /api/bind/unbind"]:::api
        A31 -->|"用户ID, id"| S31["⚙️ GuideFamilyService.unbindAndGet()"]:::service
        S31 -->|"更新绑定状态+发送通知"| D8

        D7 -->|"绑定申请"| P6["📋 规划师端：绑定管理"]:::page
        P6 -->|"我的请求"| A32["🔗 POST /api/family/teacher-bindings/my-requests"]:::api
        A32 -->|"用户ID"| S32["⚙️ TeacherFamilyBindingRequestService.getByTeacher()"]:::service
        S32 -->|"该规划师的所有申请"| D7

        P6 -->|"撤销申请"| A33["🔗 POST /api/family/teacher-bindings/cancel"]:::api
        A33 -->|"用户ID, requestId"| S33["⚙️ TeacherFamilyBindingRequestService.cancel()"]:::service
        S33 -->|"更新申请状态为取消"| D7

        P6 -->|"申请绑定家庭"| A34["🔗 POST /api/family/guide-bind"]:::api
        A34 -->|"规划师ID, 邀请码, 留言"| S34["⚙️ TeacherFamilyBindingRequestService.createRequest()"]:::service
        S34 -->|"创建绑定申请记录"| D7

        P6 -->|"生成绑定邀请"| A35["🔗 POST /api/guide/bind/invite"]:::api
        A35 -->|"规划师ID"| S35["⚙️ BindInviteService.generateInvite()"]:::service
        S35 -->|"写入绑定邀请记录"| D9["📦 bind_invites 表"]:::data

        P5 -->|"确认绑定邀请"| A36["🔗 POST /api/bind/accept"]:::api
        A36 -->|"用户ID, guideId, serviceType, servicePrice"| S36["⚙️ GuideFamilyService.confirmBind()"]:::service
        S36 -->|"写入guide_families绑定记录"| D8
    end

    %% ================================================================
    %% 阶段五：关系问卷与质量分析
    %% ================================================================
    subgraph 阶段五[阶段五：关系问卷与质量分析]
        D5 -->|"成员列表"| P7["🏠 关系问卷页"]:::page
        P7 -->|"AI生成问卷"| A37["🔗 POST /api/family/questionnaire/generate"]:::api
        A37 -->|"目标成员ID, 关系类型"| S37["⚙️ RelationshipQuestionnaireService.generateQuestionnaire()"]:::service
        S37 -->|"AI生成问卷内容"| D10["📦 questionnaire_snapshots 表"]:::data

        P7 -->|"提交问卷答案"| A38["🔗 POST /api/family/questionnaire/submit"]:::api
        A38 -->|"问卷快照ID, 答案列表"| S38["⚙️ RelationshipQuestionnaireService.submitQuestionnaire()"]:::service
        S38 -->|"写入问卷响应"| D11["📦 relationship_questionnaire_responses 表"]:::data

        P7 -->|"问卷历史"| A39["🔗 POST /api/family/questionnaire/history/{memberId}"]:::api
        A39 -->|"用户ID, memberId"| S39["⚙️ RelationshipQuestionnaireService.getHistory()"]:::service
        S39 -->|"该成员问卷历史列表"| D11

        P7 -->|"问卷快照"| A40["🔗 POST /api/family/questionnaire/snapshot/{memberId}"]:::api
        A40 -->|"用户ID, memberId"| S40["⚙️ RelationshipQuestionnaireService.getSnapshot()"]:::service
        S40 -->|"最新问卷快照"| D10

        D10 -->|"问卷结果"| P8["🏠 关系质量页"]:::page
        P8 -->|"计算评分"| A41["🔗 POST /api/family/relationship/calculate"]:::api
        A41 -->|"memberId"| S41["⚙️ RelationshipQualityService.calculateScore()"]:::service
        S41 -->|"写入评分结果"| D12["📦 relationship_scores 表"]:::data

        P8 -->|"评分列表"| A42["🔗 POST /api/family/relationship/scores"]:::api
        A42 -->|"用户ID, familyId"| S42["⚙️ RelationshipQualityService.getScores()"]:::service
        S42 -->|"所有成员评分"| D12

        P8 -->|"健康预警"| A43["🔗 POST /api/family/relationship/health-alerts"]:::api
        A43 -->|"用户ID, familyId"| S43["⚙️ RelationshipQualityService.getHealthAlerts()"]:::service
        S43 -->|"预警列表"| D12

        P8 -->|"里程碑"| A44["🔗 POST /api/family/relationship/milestones"]:::api
        A44 -->|"用户ID, familyId, daysAhead"| S44["⚙️ RelationshipQualityService.getMilestones()"]:::service
        S44 -->|"即将到来的里程碑"| D12
    end

    %% ================================================================
    %% 阶段六：互动记录
    %% ================================================================
    subgraph 阶段六[阶段六：互动记录]
        D5 -->|"成员列表"| P9["🏠 互动记录页"]:::page
        P9 -->|"互动类型"| A45["🔗 POST /api/family/interaction/types"]:::api
        A45 -->|""| S45["⚙️ InteractionLogService.getInteractionTypes()"]:::service
        S45 -->|"预定义的互动类型"| D13["📦 内存/配置类型数据"]:::data

        P9 -->|"添加互动"| A46["🔗 POST /api/family/interaction/add"]:::api
        A46 -->|"fromMemberId, toMemberId, type, content"| S46["⚙️ InteractionLogService.addInteraction()"]:::service
        S46 -->|"写入互动记录"| D14["📦 interaction_logs 表"]:::data

        P9 -->|"互动列表"| A47["🔗 POST /api/family/interaction/list"]:::api
        A47 -->|"familyId, fromMemberId, toMemberId, 分页"| S47["⚙️ InteractionLogService.listInteractions()"]:::service
        S47 -->|"分页互动记录"| D14
    end

    %% ================================================================
    %% 角色关联
    %% ================================================================
    A0 -.- P1
    A0 -.- P2
    A0 -.- P3
    A0 -.- P4
    A0 -.- P5
    A0 -.- P7
    A0 -.- P8
    A0 -.- P9
    B0 -.- P3
    C0 -.- P6

端点明细

家庭创建与加入

端点	说明	端口	请求数据	响应数据
POST /api/family/user/create-family	创建新家庭	📱小程序	{name: "我的家庭"}	{familyId}
POST /api/family/user/join-family	通过邀请码加入家庭	📱小程序	{inviteCode}	{success}
POST /api/family/invite/qrcode	生成家庭邀请二维码	📱小程序	— (从token取userId)	{inviteCode, familyName, qrCodeBase64, familyId}
POST /api/family/invite/generate	生成家庭邀请令牌+小程序码	📱小程序	—	{token, qrCodeBase64, familyName, familyId}
POST /api/family/invite/validate	校验邀请令牌有效性	📱小程序	{token}	{valid, familyId, familyName, ...}
POST /api/family/invite/accept-by-code	通过邀请码加入家庭	📱小程序	{inviteCode}	"加入家庭成功"
POST /api/family/invite/accept	接受邀请令牌	📱小程序	{token, familyRole, mergeFamily}	"加入家庭成功"
POST /api/family/invite/check-family	查询用户家庭状态	📱小程序	—	{hasFamily, familyId, familyName, ...}

家庭成员管理

端点	说明	端口	请求数据	响应数据
POST /api/family/member/add	添加家庭成员	📱小程序	{nickname, phone, avatar, gender, birthday}	FamilyMemberVO
POST /api/family/member/list	获取成员列表	📱小程序	—	List<FamilyMemberVO>
POST /api/family/member/switch	切换到成员视图	📱小程序	{memberId}	SwitchMemberVO
POST /api/family/member/kick	踢出成员	📱小程序	{memberId}	"踢出成功"
POST /api/family/member/update	更新成员信息	📱小程序	{memberId, nickname, phone, avatar, gender, birthday}	FamilyMemberVO
POST /api/family/member/editable	检查成员是否可编辑	📱小程序	{memberId}	boolean
POST /api/family/member/logs	成员变更日志	📱小程序	{memberId}	List<FamilyMemberLog>
POST /api/family/user/members/visible	可见成员列表	📱小程序	—	List<FamilyMemberVO>
POST /api/family/user/members/update-visibility	更新成员可见性	📱小程序	{memberId, memberType, showToFamily}	boolean

家庭设置

端点	说明	端口	请求数据	响应数据
POST /api/family/user/info	获取用户信息	📱小程序	—	User对象
POST /api/family/user/update	更新用户信息	📱小程序	{nickname, avatar, ...}	boolean
POST /api/family/user/children	创建孩子账号	📱小程序	{nickname, gender, birthday, ...}	FamilyMemberInfoDTO
POST /api/family/user/children/list	孩子列表	📱小程序	—	List<FamilyMemberInfoDTO>
POST /api/family/user/children/update	更新孩子信息	📱小程序	{childId, nickname, gender, birthday, ...}	boolean
POST /api/family/user/family-members	家庭成员完整列表（含家长）	📱小程序	—	{familyId, familyName, parents, children}
POST /api/family/user/kick	管理员踢出用户	📱小程序	{targetUserId}	boolean
POST /api/family/invite/transfer-admin	转让家庭管理员	📱小程序	{newAdminId}	"转让成功"
POST /api/family/invite/revoke	吊销邀请链接	📱小程序	{invitationId}	"邀请已吊销"
POST /api/family/user/switch-role	切换用户角色	📱小程序	{role}	新token
POST /api/family/user/switch-back-to-parent	切换回家长视图	📱小程序	—	boolean
POST /api/family/user/switch-back-verify	密码校验后切换回家长	📱小程序	{password}	boolean

规划师绑定

端点	说明	端口	请求数据	响应数据
POST /api/family/teacher-bindings/pending	待审批绑定列表	📱小程序	—	List<TeacherFamilyBindingRequest>
POST /api/family/teacher-bindings/approve	审批通过	📱小程序	{requestId}	"审批通过"
POST /api/family/teacher-bindings/reject	审批拒绝	📱小程序	{requestId, reason}	"已拒绝"
POST /api/family/teacher-bindings/my-requests	规划师我的请求	📋规划师端	—	List<TeacherFamilyBindingRequest>
POST /api/family/teacher-bindings/cancel	撤销申请	📋规划师端	{requestId}	"已撤销"
POST /api/family/guide-bind	规划师申请绑定家庭	📋规划师端	{inviteCode, message}	"申请已提交"
POST /api/guide/bind/invite	规划师生成绑定邀请	📋规划师端	—	{token, ...}
POST /api/guide/bind/validate	校验绑定邀请令牌	📋规划师端	{token}	{valid, guideInfo, ...}
POST /api/bind/accept	家长确认绑定规划师	📱小程序	{guideId, serviceType, servicePrice}	boolean
POST /api/bind/guides	已绑定规划师列表	📱小程序	—	List<{id, guideId, serviceType, ...}>
POST /api/bind/unbind	解除绑定规划师	📱小程序	{id}	boolean

关系问卷与质量分析

端点	说明	端口	请求数据	响应数据
POST /api/family/questionnaire/generate	AI生成关系问卷	📱小程序	{targetMemberId, relationshipType}	QuestionnaireSnapshotVO
POST /api/family/questionnaire/submit	提交问卷答案	📱小程序	{snapshotId, answers[]}	RelationshipQuestionnaireResponse
POST /api/family/questionnaire/history/{memberId}	问卷历史记录	📱小程序	path: memberId	List<RelationshipQuestionnaireResponse>
POST /api/family/questionnaire/snapshot/{memberId}	最新问卷快照	📱小程序	path: memberId	QuestionnaireSnapshotVO
POST /api/family/relationship/calculate	计算并保存评分	⚙️系统自动	{memberId}	RelationshipScoreVO
POST /api/family/relationship/scores	关系质量评分列表	📱小程序	{familyId}	List<RelationshipScoreVO>
POST /api/family/relationship/health-alerts	健康预警列表	📱小程序	{familyId}	List<HealthAlertVO>
POST /api/family/relationship/milestones	即将到来的里程碑	📱小程序	{familyId, daysAhead}	List<MilestoneVO>

互动记录

端点	说明	端口	请求数据	响应数据
POST /api/family/interaction/types	互动类型列表	📱小程序	—	Map<类型代码, 类型名称>
POST /api/family/interaction/add	添加互动记录	📱小程序	{fromMemberId, toMemberId, type, content}	InteractionLogVO
POST /api/family/interaction/list	互动记录分页列表	📱小程序	{familyId, fromMemberId, toMemberId, page, size}	Page<InteractionLogVO>

完整性分析

#	维度	评估	说明
1	流程完整性	✅ 完整	覆盖家庭创建/加入、成员管理、家庭设置、规划师绑定、关系问卷与质量分析、互动记录6个阶段，路径完整
2	异常路径	⚠️ 部分覆盖	邀请码无效、令牌过期、非管理员踢出等错误在Service层处理；家庭合并冲突已在图中体现
3	端点覆盖	✅ 完整	47个端点全部映射到流程图中，与代码实际暴露的控制器一致
4	角色覆盖	✅ 完整	家长(parent)管理家庭全流程、规划师(teacher)绑定申请、孩子(child)可见性管理均已覆盖；管理员(admin)在管理后台管理家庭，不在本图范围
5	数据实体	✅ 完整	families、users、family_members、family_member_logs、family_invitations、teacher_family_binding_requests、guide_families、bind_invites、questionnaire_snapshots、relationship_questionnaire_responses、relationship_scores、interaction_logs 均在图中映射
6	一致性	✅ 与代码一致	所有端点路径与实际Controller（FamilyUserController、FamilyInviteController、FamilyMembersController、TeacherFamilyBindingController、RelationshipQuestionnaireController、RelationshipQualityController、InteractionLogController、BindController、BindInviteController）中的@PostMapping匹配