# 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: `cfc-backend/.../entity/GuideInviteCode.java:24` (add type field)
- Modify: `cfc-backend/.../service/GuideInviteCodeService.java` (support type in create/generate)
- Modify: `cfc-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: `cfc-backend/.../service/GuideInviteCodeService.java`
- Modify: `cfc-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) `cfc-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: `cfc-web/src/api/guide.js` — add `getMyFamilyInviteCode()`
- Modify: `cfc-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: `cfc-frontend/pages/login/login.vue`
- Modify: `cfc-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: `cfc-frontend/pages/guide/apply/index.vue` (guide application page)
- Modify: `cfc-frontend/pages/teacher/index.vue`
- Modify: `cfc-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: `cfc-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: `cfc-backend/.../config/DatabaseInitializer.java`

**SQL:**
```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: `cfc-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