469 lines
18 KiB
Markdown
469 lines
18 KiB
Markdown
# 家庭管理(邀请第二位家长)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>`(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<RegisterState> {
|
|
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 (
|
|
<main className="relative flex min-h-dvh items-center justify-center p-4">
|
|
<BackgroundBlobs />
|
|
<Card className="w-full max-w-sm border-slate-100 shadow-soft transition-shadow duration-200 hover:shadow-lift">
|
|
<CardHeader className="items-center gap-3 text-center">
|
|
<div className="flex size-14 items-center justify-center rounded-xl bg-gradient-to-br from-emerald-500 to-teal-600 shadow-btn">
|
|
<UserPlus className="size-8 text-white" />
|
|
</div>
|
|
<h1 className="text-2xl font-extrabold tracking-tight">加入家庭</h1>
|
|
<p className="text-sm text-muted-foreground">需要家里已有成员的邀请码</p>
|
|
</CardHeader>
|
|
<CardContent>
|
|
<form action={formAction} className="space-y-4">
|
|
<div className="space-y-2">
|
|
<Label htmlFor="displayName">称呼</Label>
|
|
<Input id="displayName" name="displayName" placeholder="如:妈妈" required />
|
|
</div>
|
|
<div className="space-y-2">
|
|
<Label htmlFor="phone">手机号</Label>
|
|
<Input
|
|
id="phone"
|
|
name="phone"
|
|
type="tel"
|
|
inputMode="numeric"
|
|
autoComplete="username"
|
|
placeholder="11 位手机号"
|
|
required
|
|
/>
|
|
</div>
|
|
<div className="space-y-2">
|
|
<Label htmlFor="password">密码</Label>
|
|
<Input
|
|
id="password"
|
|
name="password"
|
|
type="password"
|
|
autoComplete="new-password"
|
|
placeholder="至少 6 位"
|
|
required
|
|
/>
|
|
</div>
|
|
<div className="space-y-2">
|
|
<Label htmlFor="code">邀请码</Label>
|
|
<Input
|
|
id="code"
|
|
name="code"
|
|
inputMode="numeric"
|
|
maxLength={6}
|
|
placeholder="6 位数字"
|
|
className="font-mono tracking-widest"
|
|
required
|
|
/>
|
|
</div>
|
|
{state?.error && <p className="text-sm font-medium text-destructive">{state.error}</p>}
|
|
<Button type="submit" className="w-full" size="lg" disabled={pending}>
|
|
{pending ? "注册中…" : "注册并加入家庭"}
|
|
</Button>
|
|
<p className="text-center text-sm text-muted-foreground">
|
|
已有账号?{" "}
|
|
<Link href="/login" className="font-semibold text-indigo-600 underline-offset-4 hover:underline">
|
|
去登录
|
|
</Link>
|
|
</p>
|
|
</form>
|
|
</CardContent>
|
|
</Card>
|
|
</main>
|
|
);
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 3: 登录页加注册入口**
|
|
|
|
`src/app/login/page.tsx` 中「去输入激活码」那个 `<p>` 之后、`</form>` 之前插入:
|
|
|
|
```tsx
|
|
<p className="text-center text-sm text-muted-foreground">
|
|
家里另一位家长想加入?{" "}
|
|
<Link
|
|
href="/register"
|
|
className="font-semibold text-indigo-600 underline-offset-4 hover:underline"
|
|
>
|
|
用邀请码加入家庭
|
|
</Link>
|
|
</p>
|
|
```
|
|
|
|
- [ ] **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 (
|
|
<div className="space-y-3">
|
|
<p className="text-sm text-slate-700">
|
|
<span className="font-semibold">{familyName}</span> · {parents.length} 位家长 · {kids.length} 个孩子
|
|
</p>
|
|
<div className="space-y-1.5">
|
|
{parents.map((p) => (
|
|
<div key={p.id} className="flex items-center justify-between rounded-lg border border-slate-200 bg-white px-3 py-2 text-sm">
|
|
<span className="font-medium text-slate-800">{p.name}</span>
|
|
<span className="rounded-full bg-indigo-100 px-2 py-0.5 text-xs font-medium text-indigo-700">家长</span>
|
|
</div>
|
|
))}
|
|
{kids.map((k) => (
|
|
<div key={k.id} className="flex items-center justify-between rounded-lg border border-slate-200 bg-white px-3 py-2 text-sm">
|
|
<span className="font-medium text-slate-800">{k.name}</span>
|
|
<span className="rounded-full bg-slate-100 px-2 py-0.5 text-xs font-medium text-slate-500">孩子</span>
|
|
</div>
|
|
))}
|
|
</div>
|
|
<div className="flex flex-wrap items-center gap-3">
|
|
<Button size="sm" variant="secondary" disabled={pending} onClick={gen}>
|
|
<UserPlus className="size-4" /> {pending ? "生成中…" : "生成邀请码"}
|
|
</Button>
|
|
{invite?.error && <p className="text-sm font-medium text-destructive">{invite.error}</p>}
|
|
{invite?.code && (
|
|
<p className="text-sm text-slate-700">
|
|
邀请码{" "}
|
|
<span className="font-mono text-lg font-bold tracking-widest text-indigo-600">{invite.code}</span>
|
|
<span className="ml-1 text-xs text-muted-foreground">15 分钟有效,一次性</span>
|
|
</p>
|
|
)}
|
|
</div>
|
|
</div>
|
|
);
|
|
}
|
|
```
|
|
|
|
- [ ] **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
|
|
<Section title="家庭管理" desc="添加家庭其他家长,一起查看孩子的学习情况">
|
|
<FamilyManage
|
|
familyName={family.familyName}
|
|
parents={family.parents}
|
|
kids={family.kids}
|
|
/>
|
|
</Section>
|
|
```
|
|
|
|
- [ ] **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` 里 `<ParentDashboard ... />` 追加 `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`;孩子设备激活流程不受影响。 |