Zettelkasten Inbox ／ アーキテクチャ

システムの骨組み

APIの一覧（全12本）

すべて /api/ の下にあり、すべて 1番の門を通る。画面のHTMLはサーバーで組み立てるが、 中身のデータはこの12本を通してブラウザが取りに行く。

コードの意味の使い分け。 400＝送られてきた中身が形として間違っている。 401＝あなたが誰か分からない（サインインしていない）。 404＝Notion側で対象が見つからない、または連携に共有されていない。 409＝形は正しいが、いまのNotionの状態と噛み合わない（すでに処理済み、開いてから変わった、など）。 429＝Notionへの要求が多すぎる。 502＝書いたあとの照合が合わなかった。 503＝Notionの接続情報（トークン）が設定されていない。

特徴的なのは、Notionが返したコードがそのまま利用者側の応答コードになること。 Notionが 429 を返せばアプリも 429 を返し、404 を返せばアプリも 404 を返す。 「Notionの状態をそのまま伝える」という方針が、コードの選び方にも出ている。

認証のしくみ

• アプリ自身は認証を実装していない。置かれている土台（ホスティング側）が サインイン済みの要求に oai-authenticated-user-id というヘッダを差し込む。 アプリはそのヘッダが存在するかどうかだけを見る。値の中身は照合も記録もしない。
• 無ければ、本文を1バイトも読む前に 401 と日本語のメッセージを返す。
• 本番以外では素通し。実行環境が本番でないときは、この確認処理はその場で戻る。 手元で開発するときにサインインを要求しないための割り切り。
• PINやパスワードの照合、Cookieへの署名、OAuth 2.0 のような外部の認可の流れは、 アプリ側には無い。サインイン用の補助コード一式はファイルとして置かれているが、 どのページ・どのAPIからも呼ばれていない（未使用のまま残っている）。
• Notionに対しては、環境変数に入れたトークンを Authorization: Bearer … で毎回送り、 あわせて Notion-Version: 2026-03-11 というAPIの版を指定する。 トークンが空なら、Notionへ行く前に 503 で止まる。

外部へ出ていく通信は3方向だけ

Notion側のデータの形（このアプリが前提にしている構造）

• Literature Notes DB＝読んだものの記録。項目は 名前／タグ／🧠 Zettelkasten DB（＝ABC Noteへの関連）／コメント／URL／媒体／ステータス。
• Tag DB＝観点。項目は 名前／親アイテム／Out_Permanent（＝配下のABC Note）／Number_In_Literature（＝使われた数の集計）。
• ABC（Zettelkasten）DB＝知識ページ。項目は 名前／タグ／Literature Notes DB（＝引いた元ノート）。
• 「未処理」の定義はタグ欄もABC欄も両方空であること。この2つが空のものだけが受信箱に並ぶ。
• 転記の行き先は、ABC Noteの本文にある 「その他」という見出しの下と決め打ちされている。 無ければ作り、2つあれば 409 で止まって人に直させる。
• Tagは「あとで読む」「本」「読みたい本、ブログ」「読みたい本・ブログ」の4つだけ 整理用として扱われ、おすすめの点数から45点差し引かれる。

覚えておく期間（キャッシュ）

キャッシュはすべてサーバーのメモリの中に置かれている。ディスクにも外部にも書かない。 置かれている実行環境は要求ごとに切り替わりうるので、 「30秒キャッシュが効く」のは運が良ければ、という程度に読むのが正しい。 正しさはキャッシュに依存せず、書き込み前の再取得と書き込み後の照合で担保している。

同時に触ってしまったときの守り

• ノート単位の鍵。同じLiterature Noteに対する保存と削除は、 前の処理が終わるまで次が始まらないよう、1本の待ち行列につながれる。
• ABC Note単位の鍵。本文への転記は、転記先のABC Noteごとに別の待ち行列。 違うノートから同じABC Noteへ同時に書こうとしても、本文の読み取りと追記が交錯しない。
• 指紋による楽観的な排他（11番）。再構成ラボだけは、 本文の内容と最終更新時刻から作った短い指紋を画面が持っておき、 保存時にサーバー側の指紋と突き合わせる。ずれていたら 409 で断る。
• この3つとも1つのサーバー実行環境の中でしか効かない。 別の環境が同時に動いた場合に何が起きるかは未確認。