cfc/docs/superpowers/plans/2026-05-19-guide-invite-code-flow.md

Team Invitation Code Flow Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Implement two-code system (team + family) for guides and complete mini-program invite flow

Architecture: Backend adds type field to GuideInviteCode, mini-program checks invite code type on registration to route correctly (register → apply → join), Web admin shows both codes in Layout.vue dialog

Tech Stack: Spring Boot 2.7.18, uni-app Vue 2, Vue 2 + Element UI

---

Task 1: Backend — Add type field to GuideInviteCode

Files:

• Modify: zxyj-backend/.../entity/GuideInviteCode.java:24 (add type field)
• Modify: zxyj-backend/.../service/GuideInviteCodeService.java (support type in create/generate)
• Modify: zxyj-backend/.../controller/guide/GuideTeamController.java (add type to invite-code response)

Details:

• Add private String type; to GuideInviteCode with values "team" / "family"
• Default new codes to "team" in generateInviteCode()
• createInviteCode() checks existing by guideId + type, not just guideId
• GuideTeamController.getMyInviteCode() accepts optional type param (defaults to "team")
• New endpoint POST /api/guide/team/invite-code/family returns family-type code

---

Task 2: Backend — Invite code validation with type routing

Files:

• Modify: zxyj-backend/.../service/GuideInviteCodeService.java
• Modify: zxyj-backend/.../controller/guide/GuideManagementController.java

Details:

• validateInviteCode(code, type) — validates code matches the expected type
• POST /api/guide/invite-code/validate enhanced to return code type + guide info
• Response includes: { valid, type, guideId, guideName, code }

---

Task 3: Backend — Team join/leave endpoints

Files:

• New: (add to) zxyj-backend/.../controller/guide/GuideTeamController.java

Endpoints:

• POST /api/guide/team/join — accept { inviteCode, userId }, validates code, checks if user is already a teacher, if in another team → error telling them to leave first
• POST /api/guide/team/leave — removes user from team (clears teacher_no or team relation)
• POST /api/guide/team/check-status — returns { isTeacher, inTeam, teamId } for the invite code flow routing

---

Task 4: Web admin — Show both codes in Layout.vue dialog

Files:

• Modify: zxyj-web/src/api/guide.js — add getMyFamilyInviteCode()
• Modify: zxyj-web/src/views/Layout.vue — extend invite code dialog

Details:

• Add "家庭邀请码" section below "团队邀请码" in the existing dialog
• Family invite code fetched via separate API call
• Both codes shown with copy button
• Each section has description text explaining what the code is for

---

Task 5: Mini-program — Registration with invite code

Files:

• Modify: zxyj-frontend/pages/login/login.vue
• Modify: zxyj-frontend/utils/api.js

Details:

• When app opens with invite code param (from QR code or shared link), store it
• Registration page: show invite code indicator, collect phone + verification code + nickname only (no role selection)
• On submit: POST /api/auth/register-with-invite with { phone, code, inviteCode, nickname }
• Backend creates user, checks invite code type, routes accordingly

---

Task 6: Mini-program — Invite code routing (application flow)

Files:

• New: zxyj-frontend/pages/guide/apply/index.vue (guide application page)
• Modify: zxyj-frontend/pages/teacher/index.vue
• Modify: zxyj-frontend/App.vue

Details:

• After registration, if invite code is team-type:
  • User already has role=teacher → redirect to confirm team join
  • User has teacherStatus=pending → show application pending page
  • User is not a teacher → show guide application page
• If invite code is family-type: bind to family on registration
• Store inviteCodeInfo in global state (guide name, code type)

---

Task 7: Mini-program — Team join confirmation page

Files:

• New: zxyj-frontend/pages/guide/team-confirm/index.vue

Details:

• Shows: inviting guide info (name, avatar), current team info (if any)
• If already in a team: "您当前在 XX 团队中，请先退出再加入新团队" with "退出团队" button
• If eligible: "确认加入 XX 的团队" → calls /api/guide/team/join
• Success → navigate to teacher home

---

Task 8: Database migration

Files:

• Modify: zxyj-backend/.../config/DatabaseInitializer.java

SQL:

ALTER TABLE guide_invite_codes ADD COLUMN type VARCHAR(20) DEFAULT 'team' COMMENT '邀请码类型: team/family';
ALTER TABLE guide_invite_codes ADD INDEX idx_type (type);

---

Task 9: Mini-program registration page update

Files:

• Modify: zxyj-frontend/pages/login/login.vue or registration page

Details:

• Remove role selector when invite code is present
• Add hidden field carrying invite code through the flow
• After registration success, call /api/guide/team/check-status to determine next step
• Navigate to appropriate page based on user status + invite code type