AI 入门实战训练营 · 课程讲义

import { can, getEnv, getUser, json } from "@/lib/server";
    
export async function GET(req: Request) {
  const user = await getUser(req);
  if (!user) return json({ error: "Not signed in" }, 401);
  const q = new URL(req.url).searchParams.get("q") ?? "";
  const { results } = await getEnv()
    .DB.prepare(
      SELECT id, title, artist, song_key, tags, updated_at FROM songs        WHERE title LIKE ?1 OR artist LIKE ?1 OR tags LIKE ?1 OR content LIKE ?1        ORDER BY updated_at DESC LIMIT 200
    )
    .bind(%${q}%)
    .all();
  return json(results);
}
    
export async function POST(req: Request) {
  const user = await getUser(req);
  if (!can(user, "editor")) return json({ error: "Editor role required" }, 403);
  const body = (await req.json()) as Record<string, string>;
  if (!body.title?.trim()) return json({ error: "Title is required" }, 400);
  const id = crypto.randomUUID();
  await getEnv()
    .DB.prepare(
      INSERT INTO songs (id, title, artist, song_key, tempo, tags, content, created_by, updated_by)        VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?8)
    )
    .bind(id, body.title.trim(), body.artist ?? null, body.song_key ?? null, Number(body.tempo) || null, body.tags ?? null, body.content ?? "", user!.id)
    .run();
  return json({ id }, 201);
}</code></pre></div>
  
<p class="ai-ref-label"><em>`src/app/api/songs/[id]/route.ts`（新建）——获取、更新（更新前自动保存历史版本）、删除歌曲。这是第二次课的版本，第三次课将补充删除附件功能：</em></p>
<div class="code-wrap ai-ref-code"><div class="code-head"><span class="lang">ts</span></div><pre><code class="language-ts">import { can, getEnv, getUser, json } from &quot;@/lib/server&quot;;
    
type Ctx = { params: Promise<{ id: string }> };
    
export async function GET(req: Request, { params }: Ctx) {
  const user = await getUser(req);
  if (!user) return json({ error: "Not signed in" }, 401);
  const { id } = await params;
  const song = await getEnv().DB.prepare("SELECT * FROM songs WHERE id = ?1").bind(id).first();
  if (!song) return json({ error: "Not found" }, 404);
  return json(song);
}
    
export async function PUT(req: Request, { params }: Ctx) {
  const user = await getUser(req);
  if (!can(user, "editor")) return json({ error: "Editor role required" }, 403);
  const { id } = await params;
  const body = (await req.json()) as Record<string, string>;
  if (!body.title?.trim()) return json({ error: "Title is required" }, 400);
  const db = getEnv().DB;
  // Save the old version first, then update (both in one batch).
  await db.batch([
    db.prepare("INSERT INTO song_versions (song_id, title, content, edited_by) SELECT id, title, content, updated_by FROM songs WHERE id = ?1").bind(id),
    db
      .prepare(
        UPDATE songs SET title = ?2, artist = ?3, song_key = ?4, tempo = ?5, tags = ?6, content = ?7,          updated_by = ?8, updated_at = datetime('now') WHERE id = ?1
      )
      .bind(id, body.title.trim(), body.artist ?? null, body.song_key ?? null, Number(body.tempo) || null, body.tags ?? null, body.content ?? "", user!.id),
  ]);
  return json({ ok: true });
}
    
export async function DELETE(req: Request, { params }: Ctx) {
  const user = await getUser(req);
  if (!can(user, "leader")) return json({ error: "Leader role required" }, 403);
  const { id } = await params;
  const env = getEnv();
  // 第三次课（阶段 8）会在这里加上：先删除 R2 里的附件文件
  await env.DB.batch([
    env.DB.prepare("DELETE FROM attachments WHERE song_id = ?1").bind(id),
    env.DB.prepare("DELETE FROM song_versions WHERE song_id = ?1").bind(id),
    env.DB.prepare("DELETE FROM songs WHERE id = ?1").bind(id),
  ]);
  return json({ ok: true });
}</code></pre></div>
  
<p class="ai-ref-label"><em>`src/lib/song-format.ts`（新建）——解析歌词格式（详见 2.2），并提供导出到 ICC 歌词系统的 `toIccLyric()`：</em></p>
<div class="code-wrap ai-ref-code"><div class="code-head"><span class="lang">ts</span></div><pre><code class="language-ts">// Song content format, compatible with ICC Media Hub (icc-lyric-api).
//   &quot;;&quot;        ends one screen (one click on the ICC control desk)
//   &quot;@V1&quot;      group starting with @ = section name (V1 / V2 / C / B ...)
//   &quot;# V1 C&quot;   group starting with # = play-order note (not shown on screen)
//   &quot;==Title&quot;  line = big title, &quot;=Sub&quot; line = subtitle
//   &quot;[G]奇&quot;    chord G above 奇 (our addition; removed by toIccContent)
export type Line =
  | { kind: &quot;title&quot;; text: string }
  | { kind: &quot;subtitle&quot;; text: string }
  | { kind: &quot;lyric&quot;; pieces: { chord: string; text: string }[] };
export type Block =
  | { kind: &quot;section&quot;; label: string }
  | { kind: &quot;note&quot;; text: string }
  | { kind: &quot;screen&quot;; lines: Line[] };
    
const CHORD = /[([^]\n]*)]/g;
    
export function parseChords(line: string) {
  const pieces: { chord: string; text: string }[] = [];
  const re = /[([^]\n]*)]/g;
  let last = 0;
  let chord = "";
  let m: RegExpExecArray | null;
  while ((m = re.exec(line))) {
    if (m.index > last || chord) pieces.push({ chord, text: line.slice(last, m.index) });
    chord = m[1];
    last = re.lastIndex;
  }
  pieces.push({ chord, text: line.slice(last) });
  return pieces;
}
    
function parseLine(line: string): Line {
  if (line.startsWith("==")) return { kind: "title", text: line.slice(2).trim() };
  if (line.startsWith("=")) return { kind: "subtitle", text: line.slice(1).trim() };
  return { kind: "lyric", pieces: parseChords(line) };
}
    
export function parseSong(content: string): Block[] {
  const groups = content.split(";").map((g) => g.trim());
  if (groups.length > 0 && groups[groups.length - 1] === "") groups.pop(); // trailing ";"
  return groups.map((g): Block => {
    if (g.startsWith("@")) return { kind: "section", label: g.slice(1).trim() };
    if (g.startsWith("#") || g.startsWith("$")) return { kind: "note", text: g.slice(1).trim() };
    const lines = g.split("\n").map((l) => l.trim()).filter(Boolean);
    return { kind: "screen", lines: lines.map(parseLine) };
  });
}
    
// Same text with chords removed: ready for ICC content.
// Lines that only held chords (e.g. an intro "[G] [C]") are dropped.
export function toIccContent(content: string): string {
  const strip = (group: string) =>
    group
      .split("\n")
      .flatMap((line) => {
        const text = line.replace(CHORD, "");
        return text.trim() === "" && line.trim() !== "" ? [] : [text];
      })
      .join("\n");
  return content.split(";").map(strip).join(";");
}
    
// Payload for ICC POST /api/lyrics. ICC titles start with the pinyin initial
// of the first character, e.g. "Q_奇异恩典"; pass it in when known.
export function toIccLyric(song: { title: string; artist?: string | null; content: string }, prefix = "") {
  let content = toIccContent(song.content).trim();
  if (!content.includes("==")) {
    const head = ["@Title;", ==《${song.title}》];
    if (song.artist) head.push(=词曲：${song.artist});
    content = ${head.join(&quot;\n&quot;)};\n${content};
  }
  if (!content.endsWith(";")) content += ";";
  return {
    title: prefix ? ${prefix.toUpperCase()}_${song.title} : song.title,
    content,
    language: /[\u4e00-\u9fff]/.test(song.title + content) ? "zh" : "en",
  } as const;
}</code></pre></div>
  
<p class="ai-ref-label"><em>`src/components/SongRender.tsx`（新建）——将段落、分屏与 `[和弦]` 渲染为歌谱：</em></p>
<div class="code-wrap ai-ref-code"><div class="code-head"><span class="lang">tsx</span></div><pre><code class="language-tsx">// Renders song content (format: see src/lib/song-format.ts).
import { parseSong } from &quot;@/lib/song-format&quot;;
    
export function SongRender({ content, showChords = true }: { content: string; showChords?: boolean }) {
  return (
    <div className="song-body font-mono leading-relaxed">
      {parseSong(content).map((b, i) => {
        if (b.kind === "section") return <h3 key={i} className="section-title mt-4 font-bold">{b.label}</h3>;
        if (b.kind === "note") return <p key={i} className="text-sm text-gray-500">顺序：{b.text}</p>;
        return (
          <div key={i} className="screen mb-3">
            {b.lines.map((l, j) => {
              if (l.kind === "title") return <h2 key={j} className="text-xl font-bold">{l.text}</h2>;
              if (l.kind === "subtitle") return <p key={j} className="text-gray-600">{l.text}</p>;
              return (
                <div key={j} className="lyric-line flex flex-wrap items-end">
                  {l.pieces.map((p, k) => (
                    <span key={k} className="inline-flex flex-col whitespace-pre">
                      {showChords && <span className="chord text-sm font-bold text-blue-700">{p.chord || "\u00a0"}</span>}
                      <span>{p.text || "\u00a0"}</span>
                    </span>
                  ))}
                </div>
              );
            })}
          </div>
        );
      })}
    </div>
  );
}</code></pre></div>
  
<p class="ai-ref-label"><em>`src/components/SongForm.tsx`（新建）——歌曲编辑表单，左侧编辑、右侧实时预览：</em></p>
<div class="code-wrap ai-ref-code"><div class="code-head"><span class="lang">tsx</span></div><pre><code class="language-tsx">&quot;use client&quot;;
import { useState } from &quot;react&quot;;
import { SongRender } from &quot;./SongRender&quot;;
    
export type SongInput = { title: string; artist: string; song_key: string; tempo: string; tags: string; content: string };
export const emptySong: SongInput = { title: "", artist: "", song_key: "", tempo: "", tags: "", content: "" };
    
export function SongForm({ initial, onSave }: { initial: SongInput; onSave: (s: SongInput) => Promise<void> }) {
  const [s, setS] = useState<SongInput>(initial);
  const [saving, setSaving] = useState(false);
  const set = (k: keyof SongInput) => (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) =>
    setS({ ...s, [k]: e.target.value });
  const input = "border rounded px-2 py-1 w-full";
    
  return (
    <form
      className="grid gap-4 md:grid-cols-2"
      onSubmit={async (e) => {
        e.preventDefault();
        setSaving(true);
        try { await onSave(s); } finally { setSaving(false); }
      }}
    >
      <div className="space-y-3">
        <input className={input} placeholder="歌名（必填）" value={s.title} onChange={set("title")} required />
        <input className={input} placeholder="作者 / 原唱" value={s.artist} onChange={set("artist")} />
        <div className="flex gap-2">
          <input className={input} placeholder="调号，例如 G" value={s.song_key} onChange={set("song_key")} />
          <input className={input} placeholder="速度 BPM" value={s.tempo} onChange={set("tempo")} />
        </div>
        <input className={input} placeholder="标签，用逗号分隔" value={s.tags} onChange={set("tags")} />
        <textarea
          className={${input} h-96 font-mono}
          placeholder={"@V1;\n[G]奇异恩[G7]典 何等[C]甘[G]甜\n我罪已得[Em]赦[D]免;"}
          value={s.content}
          onChange={set("content")}
        />
        <p className="text-sm text-gray-500">格式：英文分号 ; 结束一屏；@V1 这样的一组是段落名；和弦写在方括号里，放在对应的字前面。</p>
        <button disabled={saving} className="rounded bg-blue-600 px-4 py-2 text-white">{saving ? "保存中…" : "保存"}</button>
      </div>
      <div className="rounded border p-4">
        <p className="mb-2 text-sm text-gray-500">实时预览</p>
        <h2 className="text-xl font-bold">{s.title}</h2>
        <SongRender content={s.content} />
      </div>
    </form>
  );
}</code></pre></div>
  
<p class="ai-ref-label"><em>`src/app/page.tsx`（覆盖）——首页：歌曲列表与搜索：</em></p>
<div class="code-wrap ai-ref-code"><div class="code-head"><span class="lang">tsx</span></div><pre><code class="language-tsx">&quot;use client&quot;;
import Link from &quot;next/link&quot;;
import { useEffect, useState } from &quot;react&quot;;
import { authFetch } from &quot;@/lib/firebase&quot;;
import { RequireLogin } from &quot;@/components/RequireLogin&quot;;
    
type Row = { id: string; title: string; artist: string | null; song_key: string | null; tags: string | null; updated_at: string };
    
function SongList() {
  const [q, setQ] = useState("");
  const [songs, setSongs] = useState<Row[]>([]);
  useEffect(() => {
    const t = setTimeout(async () => {
      const res = await authFetch(/api/songs?q=${encodeURIComponent(q)});
      if (res.ok) setSongs((await res.json()) as Row[]);
    }, 300);
    return () => clearTimeout(t);
  }, [q]);
    
  return (
    <div>
      <h1 className="mb-4 text-2xl font-bold">歌曲库</h1>
      <input className="mb-4 w-full rounded border px-3 py-2" placeholder="搜索歌名、作者、标签或歌词…" value={q} onChange={(e) => setQ(e.target.value)} />
      <ul className="divide-y">
        {songs.map((s) => (
          <li key={s.id} className="py-3">
            <Link href={/songs/${s.id}} className="font-semibold text-blue-700">{s.title}</Link>
            <span className="ml-2 text-sm text-gray-500">{[s.artist, s.song_key && 调: ${s.song_key}, s.tags].filter(Boolean).join(" · ")}</span>
          </li>
        ))}
        {songs.length === 0 && <li className="py-3 text-gray-500">还没有歌曲。</li>}
      </ul>
    </div>
  );
}
    
export default function Home() {
  return <RequireLogin><SongList /></RequireLogin>;
}</code></pre></div>
  
<p class="ai-ref-label"><em>`src/app/songs/new/page.tsx`（新建）——新建歌曲页面：</em></p>
<div class="code-wrap ai-ref-code"><div class="code-head"><span class="lang">tsx</span></div><pre><code class="language-tsx">&quot;use client&quot;;
import { useRouter } from &quot;next/navigation&quot;;
import { authFetch } from &quot;@/lib/firebase&quot;;
import { RequireLogin } from &quot;@/components/RequireLogin&quot;;
import { SongForm, emptySong } from &quot;@/components/SongForm&quot;;
    
export default function NewSong() {
  const router = useRouter();
  return (
    <RequireLogin>
      <h1 className="mb-4 text-2xl font-bold">新建歌曲</h1>
      <SongForm
        initial={emptySong}
        onSave={async (s) => {
          const res = await authFetch("/api/songs", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify(s),
          });
          const data = (await res.json()) as { id: string; error?: string };
          if (!res.ok) return alert(data.error);
          router.push(/songs/${data.id});
        }}
      />
    </RequireLogin>
  );
}</code></pre></div>
  
<p class="ai-ref-label"><em>`src/app/songs/[id]/page.tsx`（新建）——歌曲详情页。这是第二次课的简化版，第三次课将补充附件与评论功能：</em></p>
<div class="code-wrap ai-ref-code"><div class="code-head"><span class="lang">tsx</span></div><pre><code class="language-tsx">&quot;use client&quot;;
import Link from &quot;next/link&quot;;
import { useParams, useRouter } from &quot;next/navigation&quot;;
import { useEffect, useState } from &quot;react&quot;;
import { authFetch } from &quot;@/lib/firebase&quot;;
import { useAuth } from &quot;@/components/AuthProvider&quot;;
import { RequireLogin } from &quot;@/components/RequireLogin&quot;;
import { SongRender } from &quot;@/components/SongRender&quot;;
    
type Song = { id: string; title: string; artist: string | null; song_key: string | null; tempo: number | null; tags: string | null; content: string; updated_at: string };
    
function SongView({ id }: { id: string }) {
  const { me } = useAuth();
  const router = useRouter();
  const [song, setSong] = useState<Song | null>(null);
  const [showChords, setShowChords] = useState(true);
  const canEdit = me?.role === "leader" || me?.role === "editor";
    
  useEffect(() => {
    authFetch(/api/songs/${id}).then(async (r) => r.ok && setSong((await r.json()) as Song));
  }, [id]);
  if (!song) return <p>加载中…</p>;
    
  async function del() {
    if (!confirm("确定删除这首歌？")) return;
    const res = await authFetch(/api/songs/${id}, { method: "DELETE" });
    if (res.ok) router.push("/");
    else alert(((await res.json()) as { error: string }).error);
  }
    
  return (
    <article>
      <div className="no-print mb-4 flex flex-wrap gap-3 text-sm">
        <button onClick={() => window.print()} className="rounded bg-gray-800 px-3 py-1 text-white">🖨 打印</button>
        <label><input type="checkbox" checked={showChords} onChange={(e) => setShowChords(e.target.checked)} /> 显示和弦</label>
        {canEdit && <Link href={/songs/${id}/edit} className="rounded border px-3 py-1">✏️ 编辑</Link>}
        {me?.role === "leader" && <button onClick={del} className="rounded border border-red-500 px-3 py-1 text-red-600">删除</button>}
      </div>
      <h1 className="text-3xl font-bold">{song.title}</h1>
      <p className="mb-4 text-gray-600">{[song.artist, song.song_key && 调: ${song.song_key}, song.tempo && ${song.tempo} BPM].filter(Boolean).join(" · ")}</p>
      <SongRender content={song.content} showChords={showChords} />
      {/* 第三次课会在这里加上：附件 Attachments + 评论 Comments */}
    </article>
  );
}
    
export default function SongPage() {
  const { id } = useParams<{ id: string }>();
  return <RequireLogin><SongView id={id} /></RequireLogin>;
}</code></pre></div>
  
<p class="ai-ref-label"><em>`src/app/songs/[id]/edit/page.tsx`（新建）——编辑歌曲页面：</em></p>
<div class="code-wrap ai-ref-code"><div class="code-head"><span class="lang">tsx</span></div><pre><code class="language-tsx">&quot;use client&quot;;
import { useParams, useRouter } from &quot;next/navigation&quot;;
import { useEffect, useState } from &quot;react&quot;;
import { authFetch } from &quot;@/lib/firebase&quot;;
import { RequireLogin } from &quot;@/components/RequireLogin&quot;;
import { SongForm, type SongInput } from &quot;@/components/SongForm&quot;;
    
function EditSong({ id }: { id: string }) {
  const router = useRouter();
  const [initial, setInitial] = useState<SongInput | null>(null);
  useEffect(() => {
    authFetch(/api/songs/${id}).then(async (r) => {
      if (!r.ok) return;
      const s = (await r.json()) as Record<string, string | number | null>;
      setInitial({
        title: String(s.title ?? ""), artist: String(s.artist ?? ""), song_key: String(s.song_key ?? ""),
        tempo: s.tempo ? String(s.tempo) : "", tags: String(s.tags ?? ""), content: String(s.content ?? ""),
      });
    });
  }, [id]);
  if (!initial) return <p>加载中…</p>;
  return (
    <>
      <h1 className="mb-4 text-2xl font-bold">编辑歌曲</h1>
      <SongForm
        initial={initial}
        onSave={async (s) => {
          const res = await authFetch(/api/songs/${id}, {
            method: "PUT",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify(s),
          });
          if (!res.ok) return alert(((await res.json()) as { error: string }).error);
          router.push(/songs/${id});
        }}
      />
    </>
  );
}
    
export default function EditPage() {
  const { id } = useParams<{ id: string }>();
  return <RequireLogin><EditSong id={id} /></RequireLogin>;
}</code></pre></div>