# 家庭管理(邀请第二位家长)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:** 家长端可生成家庭邀请码,第二位家长凭码在 `/register` 注册加入家庭,登录后看到全部孩子数据(权限与现有家长一致)。 **Architecture:** 新增 `family_invite` 表(仿 `activation_code`:6 位码、一次性、15 分钟);新增 `/register` 家长注册页(server action 校验码→建 user→自动登录);家长端功能 tab 新增「家庭管理」Section(成员列表 + 生成邀请码按钮)。`users.familyId` 已按家庭隔离数据,第二位家长同 familyId 即自动可见全部数据,无需权限改造。 **Tech Stack:** Next.js 15.5 App Router、TypeScript、Drizzle ORM(mysql2)、bcryptjs、Tailwind/ui 组件(shadcn 风格)、zod。 **Spec:** `docs/superpowers/specs/2026-08-19-family-manage-design.md` ## Global Constraints - 项目无自动化测试框架,验证靠 `npx tsc --noEmit` + `npm run build`(每任务末尾跑 tsc,最终任务跑 build)+ 手工清单。 - 新代码注释遵循项目风格,新函数加一行 `// xuchao:` 注释(用户全局规范)。 - 验证码/邀请码一律只存 sha256 哈希(`crypto.createHash("sha256").update(code).digest("hex")`),明文只在生成后一次性返回给调用方。 - 迁移文件格式:文件头 `-- xuchao:` 注释 + `CREATE TABLE IF NOT EXISTS` + 幂等,语句间 `--> statement-breakpoint` 分隔(参照 `drizzle/0008_points.sql`)。 - 邀请码规则固定:6 位数字、15 分钟过期、一次性(未用且未过期才算有效)。 - 手机号唯一(`uq_user_phone`),注册时先查占用,报「该手机号已注册」。 --- ### Task 1:family_invite 表(schema + 迁移 0009) **Files:** - Modify: `src/db/schema.ts`(在 `activationCodes` 表定义之后追加) - Create: `drizzle/0009_family-invite.sql` **Interfaces:** - Produces: `familyInvites` 表的 drizzle 对象(列:`id`/`familyId`/`codeHash`/`createdBy`/`createdAt`/`expiresAt`/`usedAt`),供 Task 2/3 的 server action 使用。 - [ ] **Step 1: schema.ts 追加 family_invite 表** 在 `src/db/schema.ts` 中 `activationCodes` 表定义(`// ===== 设备激活码` 那一节)结束之后、`// ===== 周模板` 注释之前插入: ```ts // ===== 家庭邀请码(家长生成,其他家长凭码注册加入;一次性,15 分钟)===== export const familyInvites = mysqlTable("family_invite", { id: bigint("id", { mode: "number" }).primaryKey().autoincrement(), familyId: bigint("family_id", { mode: "number" }) .notNull() .references(() => families.id, { onDelete: "cascade" }), codeHash: varchar("code_hash", { length: 64 }).notNull(), createdBy: bigint("created_by", { mode: "number" }) .notNull() .references(() => users.id), createdAt: datetime("created_at").notNull().default(sql`CURRENT_TIMESTAMP`), expiresAt: datetime("expires_at").notNull(), usedAt: datetime("used_at"), }); ``` - [ ] **Step 2: 创建迁移文件 `drizzle/0009_family-invite.sql`** ```sql -- xuchao: 家庭邀请码——家长生成一次性邀请码,其他家长凭码注册加入家庭。幂等。 CREATE TABLE IF NOT EXISTS `family_invite` ( `id` bigint AUTO_INCREMENT NOT NULL, `family_id` bigint NOT NULL, `code_hash` varchar(64) NOT NULL, `created_by` bigint NOT NULL, `created_at` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP, `expires_at` datetime NOT NULL, `used_at` datetime, CONSTRAINT `family_invite_id` PRIMARY KEY(`id`) ); ``` - [ ] **Step 3: 类型检查** Run: `npx tsc --noEmit` Expected: 无输出(退出码 0) - [ ] **Step 4: 提交** ```bash git add src/db/schema.ts drizzle/0009_family-invite.sql git commit -m "新增 family_invite 家庭邀请码表(schema+0009迁移)" ``` --- ### Task 2:`/register` 注册页 + 登录页入口 **Files:** - Create: `src/app/register/actions.ts` - Create: `src/app/register/page.tsx` - Modify: `src/app/login/page.tsx`(登录按钮下的提示区加链接) **Interfaces:** - Consumes: Task 1 的 `familyInvites`、现有 `users`/`createSession`、`bcryptjs`。 - Produces: `registerWithInvite(prev: RegisterState, formData: FormData): Promise`(RegisterState = `{ error?: string } | null`)。 - [ ] **Step 1: 创建 `src/app/register/actions.ts`** ```ts "use server"; import crypto from "node:crypto"; import bcrypt from "bcryptjs"; import { and, eq, gt, isNull } from "drizzle-orm"; import { redirect } from "next/navigation"; import { z } from "zod"; import { db } from "@/db"; import { familyInvites, users } from "@/db/schema"; import { createSession } from "@/lib/auth"; function hashCode(code: string) { return crypto.createHash("sha256").update(code).digest("hex"); } const registerSchema = z.object({ displayName: z.string().trim().min(1, "请输入称呼").max(20, "称呼最多 20 字"), phone: z.string().regex(/^1\d{10}$/, "请输入 11 位手机号"), password: z.string().min(6, "密码至少 6 位"), code: z.string().regex(/^\d{6}$/, "邀请码是 6 位数字"), }); export type RegisterState = { error?: string } | null; // xuchao: 家长凭邀请码注册:校验码→查重手机号→事务(码标记已用+建家长)→自动登录跳家长中心 export async function registerWithInvite( _prev: RegisterState, formData: FormData, ): Promise { const parsed = registerSchema.safeParse({ displayName: formData.get("displayName"), phone: formData.get("phone"), password: formData.get("password"), code: formData.get("code"), }); if (!parsed.success) return { error: parsed.error.issues[0].message }; const { displayName, phone, password, code } = parsed.data; const [invite] = await db .select({ id: familyInvites.id, familyId: familyInvites.familyId }) .from(familyInvites) .where( and( eq(familyInvites.codeHash, hashCode(code)), isNull(familyInvites.usedAt), gt(familyInvites.expiresAt, new Date()), ), ) .limit(1); if (!invite) return { error: "邀请码无效或已过期,请让家长重新生成" }; const [dup] = await db.select({ id: users.id }).from(users).where(eq(users.phone, phone)).limit(1); if (dup) return { error: "该手机号已注册" }; const passwordHash = await bcrypt.hash(password, 10); const newUserId = await db.transaction(async (tx) => { await tx.update(familyInvites).set({ usedAt: new Date() }).where(eq(familyInvites.id, invite.id)); const [created] = await tx .insert(users) .values({ familyId: invite.familyId, role: "parent", displayName, phone, passwordHash }) .$returningId(); return created.id; }); await createSession(newUserId, "家长设备", 30); redirect("/parent"); } ``` - [ ] **Step 2: 创建 `src/app/register/page.tsx`** ```tsx "use client"; import { useActionState } from "react"; import Link from "next/link"; import { UserPlus } from "lucide-react"; import { BackgroundBlobs } from "@/components/background-blobs"; import { registerWithInvite } from "./actions"; import { Button } from "@/components/ui/button"; import { Card, CardContent, CardHeader } from "@/components/ui/card"; import { Input } from "@/components/ui/input"; import { Label } from "@/components/ui/label"; export default function RegisterPage() { const [state, formAction, pending] = useActionState(registerWithInvite, null); return (

加入家庭

需要家里已有成员的邀请码
{state?.error &&

{state.error}

}

已有账号?{" "} 去登录

); } ``` - [ ] **Step 3: 登录页加注册入口** `src/app/login/page.tsx` 中「去输入激活码」那个 `

` 之后、`` 之前插入: ```tsx

家里另一位家长想加入?{" "} 用邀请码加入家庭

``` - [ ] **Step 4: 类型检查** Run: `npx tsc --noEmit` Expected: 无输出(退出码 0) - [ ] **Step 5: 提交** ```bash git add src/app/register src/app/login/page.tsx git commit -m "新增家长注册页 /register:凭家庭邀请码注册加入并自动登录" ``` --- ### Task 3:家长端「家庭管理」Section **Files:** - Modify: `src/app/parent/actions.ts`(schema 导入行加 `familyInvites`;文件内新增 `generateFamilyInvite` action) - Create: `src/app/parent/family-manage.tsx` - Modify: `src/app/parent/dashboard.tsx`(新增 `FamilyData` 类型 + props + Section) - Modify: `src/app/parent/page.tsx`(查询家庭名与家长列表,组装 `family` 传入 Dashboard) **Interfaces:** - Consumes: Task 1 的 `familyInvites`;现有 `getSessionUser`/`db`/`families`/`users`。 - Produces: `generateFamilyInvite(): Promise<{ code?: string; error?: string }>`;`FamilyManage({ familyName, parents, kids })` 组件;`FamilyData` 类型。 - [ ] **Step 1: parent/actions.ts 加 `generateFamilyInvite`** 先改 schema 导入行(文件顶部 `import { activationCodes, sessions, taskInstances, taskTemplates, users } from "@/db/schema";` → 追加 `familyInvites`);再在 `createActivationCode` action 之后追加: ```ts // xuchao: 生成家庭邀请码(6 位,15 分钟一次性),对方凭码在 /register 注册加入 export async function generateFamilyInvite(): Promise<{ code?: string; error?: string }> { const parent = await getSessionUser(); if (!parent || parent.role !== "parent") return { error: "请先以家长身份登录" }; const code = String(crypto.randomInt(0, 1_000_000)).padStart(6, "0"); await db.insert(familyInvites).values({ familyId: parent.familyId, codeHash: hashCode(code), createdBy: parent.id, expiresAt: new Date(Date.now() + 15 * 60_000), }); return { code }; } ``` - [ ] **Step 2: 创建 `src/app/parent/family-manage.tsx`** ```tsx "use client"; import { useState, useTransition } from "react"; import { UserPlus } from "lucide-react"; import { Button } from "@/components/ui/button"; import { generateFamilyInvite } from "./actions"; // xuchao: 家庭管理——展示成员列表,生成一次性邀请码让其他家长注册加入 export function FamilyManage({ familyName, parents, kids, }: { familyName: string; parents: { id: number; name: string }[]; kids: { id: number; name: string }[]; }) { const [invite, setInvite] = useState<{ code?: string; error?: string } | null>(null); const [pending, startTransition] = useTransition(); const gen = () => { setInvite(null); startTransition(async () => { setInvite(await generateFamilyInvite()); }); }; return (

{familyName} · {parents.length} 位家长 · {kids.length} 个孩子

{parents.map((p) => (
{p.name} 家长
))} {kids.map((k) => (
{k.name} 孩子
))}
{invite?.error &&

{invite.error}

} {invite?.code && (

邀请码{" "} {invite.code} 15 分钟有效,一次性

)}
); } ``` - [ ] **Step 3: dashboard.tsx 加 `FamilyData` 类型、props 与 Section** a) `WeeklyRow` 类型定义之后追加: ```ts // xuchao: 家庭管理数据——家庭名 + 家长成员 + 孩子成员 export type FamilyData = { familyName: string; parents: { id: number; name: string }[]; kids: { id: number; name: string }[]; }; ``` b) 导入区加 `import { FamilyManage } from "./family-manage";`(与 `ChildManage` 导入相邻)。 c) `ParentDashboard` 函数签名 props 加 `family: FamilyData;`,`({ overview, templates, devices, weekly, points, family }: { ...; family: FamilyData; })`。 d) 「孩子管理」Section 之前插入: ```tsx
``` - [ ] **Step 4: page.tsx 查询并传入 family 数据** a) schema 导入行(第 4-16 行 `import { sessions, ... } from "@/db/schema";`)追加 `families`。 b) Dashboard 类型导入(第 27-34 行)追加 `FamilyData`。 c) 会话/周测查询之后、`return` 之前插入: ```ts // ===== 家庭管理(家庭名 + 全部成员) ===== const [familyRow] = await db .select({ name: families.name }) .from(families) .where(eq(families.id, parent.familyId)) .limit(1); const parentRows = await db .select({ id: users.id, displayName: users.displayName }) .from(users) .where(and(eq(users.familyId, parent.familyId), eq(users.role, "parent"))) .orderBy(asc(users.id)); const family: FamilyData = { familyName: familyRow?.name ?? "我的家庭", parents: parentRows.map((p) => ({ id: p.id, name: p.displayName })), kids: kids.map((k) => ({ id: k.id, name: k.name })), }; ``` d) `return` 里 `` 追加 `family={family}` prop。 - [ ] **Step 5: 类型检查 + 构建** Run: `npx tsc --noEmit` Expected: 无输出 Run: `npm run build` Expected: 构建成功,`/register`、`/parent` 均出现在路由表 - [ ] **Step 6: 提交** ```bash git add src/app/parent git commit -m "家长端新增家庭管理:成员列表+生成邀请码,第二位家长凭码注册加入" ``` --- ## 手工测试清单(部署 jump.hn12301.net 前在本地 MySQL 可用时/或部署后执行) 1. 家长端功能 tab → 「家庭管理」:显示家庭名、家长/孩子成员与计数。 2. 点「生成邀请码」→ 显示 6 位码与「15 分钟有效,一次性」。 3. 浏览器开 `/register`:输称呼+新手机号+密码+邀请码 → 注册成功自动进 `/parent`,看到全部孩子与数据。 4. 第二家长登录(新手机号+密码)→ 能编辑课程/看积分,设备管理里出现两个家长会话。 5. 同一邀请码二次注册 → 「邀请码无效或已过期」;过期(15 分钟)同样报错。 6. 已注册手机号再注册 → 「该手机号已注册」;错误邀请码 → 「邀请码无效或已过期」。 7. 登录页出现「用邀请码加入家庭」链接,可达 `/register`;孩子设备激活流程不受影响。