Kurs vibe coding z Claude Code · Moduł 12: Klon Medium

Oklaski i zakreślenia: limit na serwerze i /rewind

8 min czytania
W tej lekcji10

Kronika ma pierwszych czytelników. Chcą pokazać autorowi, że tekst im się podobał, i zakreślić zdanie, do którego wrócą po wachcie. W tej lekcji dodajesz oba: przycisk oklasków i zakreślanie fragmentów. Obie funkcje wyglądają na drobne i obie mają pułapkę, której nie widać przy pierwszym kliknięciu.

Czego się nauczysz

  • wymagać limitu po stronie serwera, nie tylko w przycisku, i sprawdzić go komendą curl;
  • przeczytać przycisk, który rośnie od razu, a cofa się, gdy serwer odmówi;
  • liczyć zaznaczenie od początku bloku, a nie od kawałka tekstu, w którym zaczyna się myszka;
  • cofnąć nieudaną próbę przez /rewind, zamiast dokładać kolejną łatkę.

Polecenie dla Claude Code: oklaski

W naszym klonie czytelnik może klasnąć do 50 razy pod jednym artykułem. Liczba jest umowna, ważniejsze jest to, kto jej pilnuje. Przycisk w przeglądarce to tylko prośba: każdy może wysłać żądanie z pominięciem strony, choćby komendą curl. Dlatego zasadę sprawdza serwer, jak zamek z lekcji 8_3.

Polecenie dla Claude Code:

Dodaj oklaski na stronie artykułu /artykuly/[id]. Czytelnik może
klasnąć od 1 do 50 razy pod jednym artykułem. Trasa
POST /api/articles/[id]/clap zapisuje jeden oklask i odrzuca 51.
kodem 409. Czytelnika rozpoznaj po ciasteczku, logowania jeszcze
nie mamy. Dane trzymaj w pamięci serwera. Przycisk
components/ClapButton.tsx podbija licznik od razu, a gdy serwer
odmówi albo sieć zawiedzie, cofa go i pokazuje komunikat.
Będzie gotowe, gdy test Vitest pokaże cofnięcie licznika po
odpowiedzi 409, a pętla curl pokaże 409 przy 51. oklasku.

Kod 409 według MDN oznacza konflikt żądania z obecnym stanem zasobu: czytelnik prosi o oklask, którego stan artykułu już nie dopuszcza.

Co napisał Claude: trasa z limitem

Otwórz w Cursorze lib/claps.ts. Sercem limitu jest jedna funkcja:

// lib/claps.ts
export function addClap(articleId: string, readerId: string): ClapResult | null {
  const { total, mine } = getClaps(articleId, readerId);
  if (mine >= MAX_CLAPS) return null;
  store.totals.set(articleId, total + 1);
  store.byReader.set(`${articleId}:${readerId}`, mine + 1);
  return { total: total + 1, mine: mine + 1 };
}

ClapResult to dwie liczby: oklaski wszystkich czytelników i oklaski tego jednego. Typ i stała MAX_CLAPS leżą w osobnym pliku lib/clapRules.ts, bo importuje je też przycisk. null znaczy "limit wyczerpany", a store to dwie mapy w pamięci serwera. Teraz otwórz trasę:

// app/api/articles/[id]/clap/route.ts
export async function POST(_request: Request, { params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  if (!getArticle(id)) {
    return Response.json({ error: "Nie ma takiego artykułu" }, { status: 404 });
  }
  const readerId = await getOrCreateReaderId();
  const result = addClap(id, readerId);
  if (!result) {
    return Response.json({ error: `Limit to ${MAX_CLAPS} oklasków`, ...getClaps(id, readerId) }, { status: 409 });
  }
  return Response.json(result);
}

W Next.js 16 params to obietnica, więc pierwsza linia to await params, jak w dokumentacji Route Handlers. getOrCreateReaderId z lib/reader.ts czyta ciasteczko reader przez await cookies(), a gdy go nie ma, ustawia nowe z identyfikatorem z crypto.randomUUID(). Dokumentacja Next.js pozwala ustawiać ciasteczka właśnie w Route Handlers i Server Functions. Pamiętaj, że ciasteczko odróżnia przeglądarki, nie ludzi: kto je skasuje, klaszcze od nowa. Prawdziwego czytelnika da dopiero logowanie, jak w lekcji 8_5.

Co napisał Claude: przycisk, który umie się cofnąć

Otwórz components/ClapButton.tsx. Kliknięcie podbija licznik, zanim serwer odpowie. To aktualizacja optymistyczna: zakładasz sukces, żeby przycisk reagował od razu, i sprzątasz, gdy sukcesu nie było:

// components/ClapButton.tsx
async function clap() {
  if (limitReached) return;
  setError("");
  setClaps((c) => ({ total: c.total + 1, mine: c.mine + 1 }));
  const ok = await fetch(`/api/articles/${articleId}/clap`, { method: "POST" })
    .then((res) => res.ok)
    .catch(() => false);
  if (!ok) {
    setClaps((c) => ({ total: c.total - 1, mine: c.mine - 1 }));
    setError("Oklask nie dotarł do serwera. Licznik wrócił.");
  }
}

limitReached to claps.mine >= MAX_CLAPS, a ten sam warunek wyłącza przycisk przez disabled. Kluczowe są linie z then i catch. MDN pisze wprost: obietnica z fetch() odrzuca tylko przy błędzie sieci albo złym adresie, a odpowiedź z kodem błędu przychodzi jak zwykły sukces, więc trzeba sprawdzić Response.ok. Wersja agenta miała samo .catch(...) z cofnięciem. U nas przeszła lint i tsc, a test z odpowiedzią 409 oblał z komunikatem Unable to find role="alert": licznik został podbity, a komunikat nie pojawił się wcale.

Sprawdzian: 51. oklask

Przycisk wyłączony po 50 kliknięciach jeszcze niczego nie dowodzi, bo serwera nie pyta nikt poza nim. Poproś Claude o pętlę, która klaszcze 51 razy z jednym ciasteczkiem, i uruchom ją przy działającym npm run dev:

for i in $(seq 1 51); do echo "$i $(curl -s -w ' %{http_code}' -X POST -c jar.txt -b jar.txt localhost:3000/api/articles/a3/clap)"; done | tail -3

Opcje -c i -b zapisują ciasteczko do pliku jar.txt i odsyłają je przy każdym żądaniu, więc serwer widzi jednego czytelnika, a tail -3 zostawia trzy ostatnie linie. U nas wyszło tak:

49 {"total":94,"mine":49} 200
50 {"total":95,"mine":50} 200
51 {"error":"Limit to 50 oklasków","total":95,"mine":50} 409

Artykuł miał na start 45 oklasków z przykładowych danych, stąd 95. Liczba na końcu linii to kod odpowiedzi: 50 razy 200 i raz 409.

Zakreślenia: polecenie, które się rozjechało

Zakreślenie to dwa numery: gdzie się zaczyna i gdzie kończy. Krótkie polecenie "Dodaj zakreślanie zaznaczonego tekstu, zakreślenia renderuj jako <mark>" łatwo kończy się kodem, który bierze numery wprost z zaznaczenia przeglądarki: range.startOffset i range.endOffset. Pierwsze zakreślenie wychodzi dobrze. Drugie, za pierwszym w tym samym akapicie, ląduje w złym miejscu.

Powód podaje MDN: startOffset liczy znaki od początku węzła tekstowego, w którym zaczyna się zaznaczenie, a nie od początku akapitu. Po pierwszym zakreśleniu akapit to już trzy węzły: tekst przed <mark>, tekst w nim i tekst za nim. W akapicie "Ala ma kota" z zakreślonym "ma" słowo "kota" zaczyna się w trzecim węźle na pozycji 1, a w tekście bloku na pozycji 7. U nas test wypisał expected { start: 1, end: 5 } to deeply equal { start: 7, end: 11 }.

/rewind zamiast czwartej łatki

Kusi, żeby napisać "popraw offsety", potem "nie działa przez dwa akapity", potem "teraz zepsuło się pierwsze". Każda łatka dokłada wyjątek do złego pomysłu. Gdy poprawki zaczynają łatać poprzednie poprawki, cofnij całą próbę. Wpisz /rewind albo naciśnij dwa razy Esc przy pustym polu, wybierz polecenie z zakreślaniem i opcję "Restore code and conversation". Kod i rozmowa wracają do stanu sprzed tamtego polecenia, a jego treść wraca do pola, gotowa do poprawienia. Granica z lekcji 0_6 zostaje: pliku zmienionego wyłącznie komendą terminala /rewind nie śledzi, a do stanu z ostatniego commita wracasz przez Gita. Nowe polecenie od razu nazywa pułapkę:

Dodaj zakreślanie w components/HighlightableArticle.tsx. Zakreślenie
żyje w jednym bloku: start i end liczone od początku tekstu bloku,
nie od węzła, w którym zaczyna się zaznaczenie. Zaznaczenie przez
kilka bloków i zakreślenie nachodzące na inne ignoruj. Funkcje
w lib/highlights.ts z testami Vitest, także dla zaznaczenia
za istniejącym <mark>.

Co napisał Claude: numery od początku bloku

Otwórz lib/highlights.ts. TextRange to para start i end, a funkcja liczy ją od początku bloku:

// lib/highlights.ts
export function offsetsInBlock(block: HTMLElement, range: Range): TextRange | null {
  if (!block.contains(range.startContainer) || !block.contains(range.endContainer)) return null;
  const before = document.createRange();
  before.selectNodeContents(block);
  before.setEnd(range.startContainer, range.startOffset);
  const start = before.toString().length;
  const end = start + range.toString().length;
  return end > start ? { start, end } : null;
}

Pierwsza linia odrzuca zaznaczenie, które wychodzi poza blok. Potem powstaje pomocniczy zakres od początku bloku do początku zaznaczenia. selectNodeContents obejmuje całą zawartość bloku, setEnd przycina go do miejsca, gdzie zaczyna się zaznaczenie, a toString() według MDN zwraca tekst zakresu. Długość tego tekstu to start, niezależnie od tego, ile znaczników <mark> stoi po drodze. Rysowanie dzieli tekst na kawałki według zakreśleń:

// lib/highlights.ts
const sorted = [...highlights].sort((a, b) => a.start - b.start);

Zakreślenia przychodzą w propsach, a sort zmienia tablicę w miejscu. Wersja highlights.sort(...) przestawiłaby dane rodzica w trakcie rysowania. U nas przeszła lint i tsc, a złapał ją dopiero test (expected +0 to be 7). Kawałki trafiają do <mark> albo <span> z kluczem seg.start, czyli pozycją kawałka w tekście.

Przegląd kapitana

  1. Limit w dwóch miejscach. Wyszukaj w projekcie MAX_CLAPS: ma stać w lib/claps.ts i w przycisku. Samo disabled to nie zamek. Typowy błąd agenta to limit tylko w przycisku, bo polecenie wspominało o nim jednym zdaniem.
  2. res.ok. Cofnięcie licznika musi reagować na odmowę serwera, nie tylko na zerwaną sieć.
  3. await params. Trasa i strona czytają params przez await.
  4. Pamięć serwera. U nas mapy zwykłe, zadeklarowane w module, nie działały: po trzech oklaskach przez curl strona artykułu dalej pokazywała 120 i "Twoje: 0/50", w next dev i w next start. Trasa i strona dostały osobne kopie modułu, dlatego lib/claps.ts trzyma mapy na globalThis.
  5. Kopia przed sortowaniem. Wyszukaj .sort(: przed każdym stoi [....

Następny krok

Gdy testy, pętla curl i przeglądarka się zgadzają, poproś o commit "Oklaski i zakreślenia". Potem odpowiedzi czytelników pod artykułem, z jednym poziomem zagnieżdżenia, jak drzewo komentarzy z lekcji 4_2. Dopisz do polecenia nazwę typu: ArticleResponse, nie Response. Wbudowany typ Response z Fetch API już istnieje, a własny o tej samej nazwie go przesłania. U nas trasa z interface Response w tym samym pliku nie przeszła tsc: Type 'Response' is missing the following properties from type 'Response': id, parentId. Dwa razy to samo słowo w komunikacie to znak, że nazwy się zderzyły. W edytorze poniżej czeka artykuł z przyciskiem i zakreślaniem: przełącz wersje agenta, klaśnij przy "serwerze, który odmawia" i zakreśl słowo za istniejącym zakreśleniem.

Zapamiętaj: dzwon na pokładzie bije tyle razy, ile pozwala bosman, a nie tyle, ile ktoś pociągnie za linkę, a dobra załoga umie zawrócić okręt, zanim rozbije się o rafę.

Kod do tej lekcji: App.jsx
// Oklaski i zakreślenia w miniaturze: udawany serwer z limitem i liczenie od początku bloku
import { useState } from 'react';

const MAX_CLAPS = 50;
const BLOCKS = [
  { id: 'b1', text: 'Sztorm przyszedł nocą, a załoga spała po długiej wachcie.' },
  { id: 'b2', text: 'Zwinęliśmy żagle, zanim fale urosły. Każdy wiedział, gdzie stoi.' },
];

// Udawany serwer: pamięć jak mapy na globalThis w projekcie
const server = { total: 45, mine: 0 };

function fakeFetch(options) {
  return new Promise((resolve) => {
    setTimeout(() => {
      if (options.refuse) return resolve({ ok: false, status: 503 });
      if (!options.limitOnlyInButton && server.mine >= MAX_CLAPS) return resolve({ ok: false, status: 409 });
      server.total += 1;
      server.mine += 1;
      resolve({ ok: true, status: 200 });
    }, 300);
  });
}

// Poprawka: liczymy od początku bloku przez pomocniczy zakres
function offsetsInBlock(block, range, agentBug) {
  if (!block.contains(range.startContainer) || !block.contains(range.endContainer)) return null;
  if (agentBug) return { start: range.startOffset, end: range.endOffset }; // liczy od węzła, nie od bloku
  const before = document.createRange();
  before.selectNodeContents(block);
  before.setEnd(range.startContainer, range.startOffset);
  const start = before.toString().length;
  const end = start + range.toString().length;
  return end > start ? { start, end } : null;
}

function overlaps(a, b) {
  return a.start < b.end && b.start < a.end;
}

function splitText(text, highlights) {
  const sorted = [...highlights].sort((a, b) => a.start - b.start); // kopia, nie props
  const segments = [];
  let pos = 0;
  for (const h of sorted) {
    if (h.start > pos) segments.push({ start: pos, text: text.slice(pos, h.start), highlighted: false });
    segments.push({ start: h.start, text: text.slice(h.start, h.end), highlighted: true });
    pos = h.end;
  }
  if (pos < text.length) segments.push({ start: pos, text: text.slice(pos), highlighted: false });
  return segments;
}

let nextId = 1;

export default function App() {
  const [claps, setClaps] = useState({ total: server.total, mine: server.mine });
  const [error, setError] = useState('');
  const [serverView, setServerView] = useState({ ...server });
  const [refuse, setRefuse] = useState(false);
  const [onlyCatch, setOnlyCatch] = useState(false);
  const [limitOnlyInButton, setLimitOnlyInButton] = useState(false);
  const [startOffsetBug, setStartOffsetBug] = useState(false);
  const [highlights, setHighlights] = useState([]);
  const [note, setNote] = useState('');

  async function clap() {
    if (claps.mine >= MAX_CLAPS) return;
    setError('');
    setClaps((c) => ({ total: c.total + 1, mine: c.mine + 1 }));
    const res = await fakeFetch({ refuse, limitOnlyInButton });
    setServerView({ ...server });
    // Wersja agenta z samym .catch nie cofa licznika, gdy serwer odpowie kodem błędu
    if (!res.ok && !onlyCatch) {
      setClaps((c) => ({ total: c.total - 1, mine: c.mine - 1 }));
      setError('Oklask nie dotarł do serwera (' + res.status + '). Licznik wrócił.');
    }
  }

  async function bypassButton() {
    const res = await fakeFetch({ refuse: false, limitOnlyInButton });
    setServerView({ ...server });
    setNote('Żądanie z pominięciem przycisku: ' + res.status);
  }

  function skipTo49() {
    server.total += 49 - server.mine;
    server.mine = 49;
    setServerView({ ...server });
    setClaps({ total: server.total, mine: server.mine });
    setNote('Masz już 49 oklasków. Klaśnij jeszcze dwa razy.');
  }

  function handleMouseUp() {
    const selection = window.getSelection();
    if (!selection || selection.isCollapsed) return;
    const range = selection.getRangeAt(0);
    const node = range.startContainer;
    const element = node.nodeType === 1 ? node : node.parentElement;
    const blockEl = element && element.closest('[data-block-id]');
    if (!blockEl) return;
    const offsets = offsetsInBlock(blockEl, range, startOffsetBug);
    if (!offsets) {
      setNote('Zaznaczenie wychodzi poza jeden akapit: pomijam je.');
      return;
    }
    const blockId = blockEl.dataset.blockId;
    if (highlights.some((h) => h.blockId === blockId && overlaps(h, offsets))) {
      setNote('Zaznaczenie nachodzi na istniejące zakreślenie: pomijam je.');
    } else {
      setHighlights((prev) => [...prev, { id: 'h' + nextId++, blockId, ...offsets }]);
      setNote('Zakreślenie: start ' + offsets.start + ', end ' + offsets.end + ' w bloku ' + blockId);
    }
    selection.removeAllRanges();
  }

  return (
    <div className="min-h-screen bg-gray-50 p-4 text-gray-900">
      <article onMouseUp={handleMouseUp} className="mx-auto max-w-xl space-y-3 rounded-xl bg-white p-4 shadow-sm">
        <h1 className="text-2xl font-bold">Jak przetrwać sztorm na Atlantyku</h1>
        {BLOCKS.map((block) => (
          <p key={block.id} data-block-id={block.id} className="leading-relaxed">
            {splitText(block.text, highlights.filter((h) => h.blockId === block.id)).map((seg) =>
              seg.highlighted ? (
                <mark key={seg.start} className="bg-yellow-200">{seg.text}</mark>
              ) : (
                <span key={seg.start}>{seg.text}</span>
              ),
            )}
          </p>
        ))}
        <div className="flex flex-wrap items-center gap-3">
          <button
            type="button"
            onClick={clap}
            disabled={claps.mine >= MAX_CLAPS}
            className="rounded-full border border-gray-400 px-4 py-2 font-semibold disabled:opacity-50"
          >
            Brawo
          </button>
          <span>{claps.total}</span>
          <span className="text-sm text-gray-500">Twoje: {claps.mine}/{MAX_CLAPS}</span>
          {error && <span role="alert" className="text-sm text-red-700">{error}</span>}
        </div>
      </article>

      <div className="mx-auto mt-3 max-w-xl space-y-2 rounded-xl bg-gray-900 p-4 text-sm text-white">
        <p>Serwer pamięta: łącznie <strong>{serverView.total}</strong>, Twoje <strong>{serverView.mine}</strong></p>
        <div className="flex flex-wrap gap-2">
          <button type="button" onClick={skipTo49} className="rounded bg-gray-700 px-3 py-1">
            Przewiń do 49 oklasków
          </button>
          <button type="button" onClick={bypassButton} className="rounded bg-gray-700 px-3 py-1">
            Wyślij oklask z pominięciem przycisku (jak curl)
          </button>
        </div>
        {note && <p className="text-amber-300">{note}</p>}
        <label className="flex items-center gap-2">
          <input type="checkbox" checked={refuse} onChange={(e) => setRefuse(e.target.checked)} />
          Serwer odmawia (kod 503)
        </label>
        <label className="flex items-center gap-2">
          <input type="checkbox" checked={onlyCatch} onChange={(e) => setOnlyCatch(e.target.checked)} />
          Błąd agenta: samo .catch, bez sprawdzenia res.ok
        </label>
        <label className="flex items-center gap-2">
          <input type="checkbox" checked={limitOnlyInButton} onChange={(e) => setLimitOnlyInButton(e.target.checked)} />
          Błąd agenta: limit tylko w przycisku
        </label>
        <label className="flex items-center gap-2">
          <input type="checkbox" checked={startOffsetBug} onChange={(e) => setStartOffsetBug(e.target.checked)} />
          Błąd agenta: range.startOffset zamiast liczenia od początku bloku
        </label>
      </div>
    </div>
  );
}

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Co znaczy, że ClapButton podbija licznik oklasków optymistycznie?

  2. 2. Gdzie w Captain's Chronicle musi być sprawdzany limit oklasków jednego czytelnika?

To 2 z 6 pytań do tej lekcji. Pozostałe rozwiążesz w grze.

Zadania praktyczne w grze

  • Układanie w poziomie

    Ułóż w jednej linii odczyt identyfikatora artykułu w trasie Next.js 16:

  • Klikanie w kolejności

    Kliknij elementy, aby zbudować start zakreślenia z pomocniczego zakresu before:

  • Edytor kodu

    Clap interaction component

  • Układanie w pionie

    Uporządkuj, co dzieje się z zakreśleniem w poprawionej wersji z lekcji:

  • Układanie w poziomie

    Ułóż w jednej linii posortowanie zakreśleń bez zmiany tablicy z propsów:

  • Edytor kodu

    Comments interface

  • Układanie w pionie

    Uporządkuj cofnięcie nieudanej próby z zakreśleniami:

  • Klikanie w kolejności

    Kliknij elementy, aby zbudować odpowiedź trasy na oklask ponad limit:

  • Klikanie w kolejności

    Kliknij elementy, aby zbudować cofnięcie licznika po odmowie serwera:

  1. PytanieLicznik optymistyczny
  2. PytanieKto pilnuje limitu oklasków
  3. Ułóż w kolejnościOdczyt params w trasie
  4. Kliknij w kolejnościPoczątek zakreślenia od początku bloku
  5. Zadanie z kodemPraktyka: Clap button
  6. PytanieOdpowiedź 409 i samo .catch
  7. Ułóż w kolejnościZakreślenie krok po kroku
  8. PytanieOffset liczony od węzła
  9. Ułóż w kolejnościSortowanie kopii zakreśleń
  10. Zadanie z kodemPraktyka: Response section
  11. PytanieTrzecia łatka zakreśleń
  12. PytanieNazwa typu odpowiedzi
  13. Ułóż w kolejnościCofnięcie przez /rewind
  14. Kliknij w kolejnościOdpowiedź 409 z trasy
  15. Kliknij w kolejnościCofnięcie licznika

Przydatne artykuły