# 巡回リスト（仮）設計書

- 最終更新：2026-11-18
- つくった人：きょん
- この設計書は、AI（Claude Code や Codex など）にそのまま貼って使うためのものです。

---

## 0. AIへのお願い（最初に読んでください）

あなたはこれから、この設計書どおりのツールをつくり、それをインターネット上に置くところまで、ユーザーを案内します。ユーザーはプログラミングに慣れていない前提で進めてください。

進め方は次のとおりです。

1. まず「これから何をするか」を3行くらいで伝える。
2. **つくる**：この設計書の 2〜8 章にしたがって、ファイルを2つつくる（9章のファイル構成）。
3. **置く**：10章にしたがって、GitHub と Cloudflare Pages の設定を案内する。
4. **確かめる**：11章のチェックリストを、ユーザーといっしょに1つずつ確認する。

案内するときのルール：

- **人の手が必要な操作は、かならず案内する。** アカウントをつくる、ログインする、許可のボタンを押す、画面で設定を選ぶ、といった「AIが代わりにできない操作」を、黙って飛ばしたり「設定しておいてください」の一言で済ませたりしない。どの画面の、どこを押すのかまで伝える（10章の「人の手が必要なところ」を全部通ること）。
- 手順は **1回に1ステップだけ** 伝え、ユーザーの「できた」を待ってから次へ進む。
- 最初に「GitHub と Cloudflare のアカウントを持っているか」「どのAIを、どこで使っているか（パソコンのアプリ／ターミナル／ブラウザ版など）」を聞き、それに合わせて案内を変える。
- 画面のボタンやメニューの名前は、**英語名と日本語名を両方** 書く（例：Create application（アプリケーションを作成））。画面の文言は変わることがあるので、見つからないときはユーザーにスクリーンショットを見せてもらい、それに合わせて案内する。
- コマンド操作が必要なときは、あなたが代わりに実行するか、コピーして貼れる形で渡す。
- 専門用語を使うときは、ひとこと説明を添える。
- この設計書に書いていない機能を、勝手に足さない。迷ったらユーザーに聞く。
- 色や見た目（7章）だけは、ユーザーの好みを聞いて変えてよい。

---

## 1. このツールでできること

よく通う note のクリエイターさんを登録しておき、「今日はもう行ったか」をチェックできる、自分専用のリストです。

- note の ID を入れると、アカウント名とアイコンを自動で取ってきて登録できる
- 名前を押すと、その人の note のページが新しいタブで開き、自動でチェックが付く
- 決めた時刻になると、チェックが全部リセットされる（時刻は設定で変えられる）
- グループ分け、グループの折りたたみ、ドラッグでの並び替えができる
- パソコンでもスマホでも使える
- ログインは不要。データは、使っているブラウザの中にだけ保存される

---

## 2. 全体のつくり

- **画面**：`index.html` 1ファイルだけ。HTML・CSS・JavaScript をすべてこの中に書く。外部のライブラリやフォント、ビルドの仕組みは使わない。
- **中継**：`functions/api/creator.js` 1ファイル。Cloudflare Pages Functions（Cloudflare Pages に付いている、小さなサーバー側プログラムを動かす仕組み）で動く。

中継が必要な理由：ブラウザから note のデータを直接取りにいくと、ブラウザの安全のための制限（CORS）で止められます。そこで、同じサイトの中に「note に代わりに聞いてきてくれる係」を置きます。

データの保存先はブラウザの `localStorage`（キー名：`junkai-list-v1`）。読み書きは必ず try/catch で囲み、保存できない環境でも画面が壊れないようにする。

`alert` `confirm` `prompt` は使わない。確認や入力は、ページの中のダイアログ（`<dialog>` 要素）で行う。

---

## 3. 保存するデータ

```json
{
  "groups": [
    { "id": "g1", "name": "いつもの人" },
    { "id": "g2", "name": "そのほか", "collapsed": true }
  ],
  "creators": [
    {
      "id": "c1",
      "name": "表示する名前",
      "url": "https://note.com/example_id",
      "groupId": "g1",
      "noteId": "example_id",
      "icon": "https://assets.st-note.com/....png"
    }
  ],
  "resetTime": "00:00",
  "visited": { "c1": true },
  "dayKey": "2026-11-18"
}
```

- `groups`：グループの並び順どおりの配列。`collapsed` は折りたたんでいるときだけ `true` を持つ。
- `creators`：全員をひとつの配列に入れる。グループ内の並び順は、この配列の中での順番で決まる。
- `icon` は取得できたときだけ持つ。`https:` のURLだけ受けつける。
- `resetTime`：`HH:MM` 形式（24時間）。最初は `00:00`。
- `visited`：今日チェックした人の `id` をキーにする。
- `dayKey`：最後にリセット判定をした「日付」。
- はじめて開いたときは、グループ「いつもの人」「そのほか」の2つを用意し、人は0人。
- `id` は、かぶらないランダムな文字列でよい。

読みこんだデータは必ず形を確かめる。壊れた項目は捨て、存在しないグループを指している人は先頭のグループに入れる。`url` は `http:` か `https:` 以外を受けつけない。

---

## 4. リセットの考え方

「日付が変わったか」は、次のように決める。

1. いまの時刻から、リセット時刻のぶん（例：`04:00` なら4時間）を引く。
2. 引いたあとの時刻の「年-月-日」（端末のローカル時刻）を、今日の `dayKey` とする。
3. 保存してある `dayKey` と違っていたら、`visited` を空にして、`dayKey` を更新して保存する。

この判定は、次のタイミングで行う。

- ページを開いたとき
- 30秒ごと
- タブに戻ってきたとき（`visibilitychange`、`focus`）
- チェックを付けたり外したりする直前

ドラッグで並び替えている最中は、判定による画面の描き直しをしない。

設定でリセット時刻を変えたときは、今日のチェックを消さない（新しい時刻で `dayKey` を計算し直して保存するだけ）。

---

## 5. 画面

### 5-1. 上の部分

- タイトル
- 「11月18日（水）の巡回 ・ リセット 00:00」のような1行（日付は4章の「引いたあとの時刻」のもの）
- 進み具合：「今日は 3 ／ 10 人」と、横長の進行バー。折りたたんだグループの人も数に入れる
- ボタン3つ：「＋ 追加」「編集」「設定」

### 5-2. グループ

- 見出しに、`▼`（ひらいている）か `▶`（折りたたんでいる）の印、グループ名、「1 ／ 2」のような人数を出す
- 見出しを押すと、折りたたむ／ひらくが切りかわり、状態を保存する
- 折りたたんでいるあいだは、中の人のリストを隠す。人数の表示は残す
- ひらいていて0人のときは「まだ誰もいません。「＋ 追加」から登録できます。」と出す

### 5-3. 人の行

左から順に：

1. **チェックボックス**：見た目は 22px の角丸の四角。押せる範囲はそのまわりまで広げる（横40px × 縦44px以上）。チェックすると色が付き、白い `✓` が入る。押すたびに付く／外れる
2. **リンク**：丸いアイコン（40px。無いときは出さない）、表示する名前、その下に小さく `@noteのID`
   - ふつうのリンク（`<a href target="_blank" rel="noopener noreferrer">`）にする。`window.open` は使わない
   - リンクを押したら、その人にチェックを付ける
   - アイコン画像が読みこめなかったら、画像だけ隠す

チェック済みの行は、背景と文字の色を少し変えて、ひと目でわかるようにする。

### 5-4. 編集モード

「編集」を押すと編集モードになり、ボタンの表示が「編集をおわる」に変わる。編集モードのときだけ、次のものを出す。

- 人の行：左端に並び替えハンドル `⠿`、右に「編集」「削除」
- グループの見出し：左端に並び替えハンドル `⠿`、右に「名前」「削除」
- いちばん下に「＋ グループを追加」

削除は2段階にする。1回押すと「もう一度で削除」という表示に変わり、3秒以内にもう一度押したら削除する。3秒たったら元に戻す。

グループを削除したとき、中にいた人は消さずに、先頭のグループへ移す。グループが1つしかないときは、削除できないようにする。

### 5-5. ドラッグでの並び替え

- ハンドルをつかんでドラッグすると並び替えられる。マウスでも指でも同じ動きにするため、Pointer Events（`pointerdown` / `pointermove` / `pointerup` / `pointercancel`）でつくる。HTML標準のドラッグ＆ドロップは、スマホで動かないので使わない
- ハンドルには CSS の `touch-action: none` を付ける（指でつかんだときに画面がスクロールしないようにするため）
- つかんでいるあいだ、指の高さに合わせて、行（またはグループ）を実際の位置に差しこんで見せる。差しこむ位置は「相手の行の上下まんなかより上なら、その行の前」で決める
- 人は、グループをまたいで移動できる。ただし、折りたたんでいるグループには入れない
- グループ自体も、同じやり方で並び替えられる
- 画面の上下の端（70pxくらい）に近づいたら、ゆっくり自動スクロールする
- 指を離したら、画面に並んでいる順番をそのまま保存データに写して保存する
- キーボードでも動かせるように、ハンドルを選んで上下キーを押すと、1つずつ動くようにする

**大事な注意**：`pointermove` と `pointerup` は、ハンドルではなく `document` で受けとること。つかんでいる要素を並び替えのために付け替えると、ハンドルで受けていたイベントが途中で切れて、指を離しても保存されなくなる。

### 5-6. 追加・編集のダイアログ

入力欄はこれだけにする。

- **noteのID（プロフィールのURLでもOK）** と、その横に「取得」ボタン
- 説明文：「プロフィールページのURL「note.com/○○○」の ○○○ の部分です。URLをそのまま貼ってもOK。」
- 取得できたら、アイコンとアカウント名を出す
- **表示する名前**（取得した名前が自動で入る。自分で書き換えられる。60文字まで）
- **グループ**（選ぶ）
- 「やめる」「保存」

入力からIDを取り出すルール：

- `example_id`、`@example_id`、`https://note.com/example_id`、`https://note.com/example_id/n/xxxx` のどれでも、`example_id` を取り出す
- IDに使える文字は、半角の英数字と `_` `-`、1〜64文字

動き：

- 「取得」を押すと、`/api/creator?id=ID` を呼ぶ。取得中は「取得中…」と出し、ボタンを押せなくする
- まだ取得していないID（または取得したあとに書き換えたID）で「保存」を押したら、保存のかわりに取得を行う。つまり、1回目の「保存」で取得、2回目で保存になる
- 保存するとき、`url` は `https://note.com/ID` にする
- 取得に失敗したとき（見つからない／通信できない）は、その旨を出す。そのまま**もう一度「保存」を押すと、アイコンなしで登録できる**ようにする（名前が空なら `@ID` を名前にする）
- 編集のときは、いまの内容を入れた状態でひらく。アイコンがまだ無い人には「「取得」を押すと取ってこられます」と出す

### 5-7. 設定のダイアログ

- **チェックをリセットする時刻**（時刻の入力）。説明：「この時刻をすぎると、チェックが全部はずれます。夜ふかしする日は「04:00」などにすると、日付をまたいでも続きから巡回できます。」
- 「今日のチェックを全部はずす」ボタン
- **バックアップ**：`groups` `creators` `resetTime` を JSON にした文字を、読みとり専用の入力欄に出す。「コピー」ボタンでクリップボードにコピーする（コピーできない環境では、文字を全選択して「そのままコピーしてください」と出す）
- **読み込み**：バックアップの文字を貼りつけて「読み込む」。形を確かめてから入れ替える。読み込んだあとは、今日のチェックを空にする
- 「とじる」

ファイルのダウンロードやアップロードは使わない（コピーと貼りつけだけにする）。

---

## 6. 中継（functions/api/creator.js）

- Cloudflare Pages Functions の書き方でつくる。ファイルの中で `export async function onRequestGet({ request }) { ... }` を1つ書き出すだけでよい（`Response` を返す）。`package.json` や `wrangler` の設定ファイル、追加のライブラリは要らない
- 受けつけるのは `GET /api/creator?id=noteのID` だけ
- `id` が「半角英数字と `_` `-`、1〜64文字」でなければ、`400` を返す
- `https://note.com/api/v2/creators/{id}` を取りにいく。リクエストには、ふつうのブラウザの `User-Agent` と `Accept: application/json` を付ける
- note からの返事（JSON）の `data` の中の、次の3つだけを返す

```json
{ "id": "data.urlname", "name": "data.nickname", "icon": "data.profileImageUrl" }
```

- note が `404` を返したら `404`、それ以外の失敗は `502` を返す
- 返事はすべて JSON で、`Cache-Control: no-store` を付ける
- 同じIDへの問い合わせは10分キャッシュして、note への問い合わせを減らす（Cloudflare の `cf: { cacheEverything: true, cacheTtlByStatus: { '200-299': 600, '300-599': -1 } }`）
- **IDしか受けとらない**こと。URLを丸ごと受けとって中継する形にはしない（ほかの用途に使われないようにするため）

これは note の公式に案内されている仕組みではありません。note 側の変更で、ある日使えなくなることがあります。使えなくなっても、登録済みの人のリンクとチェックはそのまま使えます。

---

## 7. 見た目

- やわらかいパステルピンクを基調にした、角の丸いデザイン（背景 `#fff7fa`、アクセント `#f48fb1`、チェック済み `#6fcf97`）
- 横幅は最大 720px くらいで中央に寄せる
- ボタンや押せるところは、高さ40px以上にして、指で押しやすくする
- 横幅480px以下では、編集モードのボタンを行の下の段に折り返す
- 色や雰囲気は、ユーザーの好みに合わせて変えてよい

---

## 8. 安全のための決まり

- ユーザーが入力した文字や、note から取ってきた文字を画面に出すときは、`textContent` を使う（`innerHTML` に入れない）
- リンク先とアイコンのURLは、`http:` / `https:` だけを通す
- 検索に載りにくくするため、`<meta name="robots" content="noindex, nofollow">` を入れる

---

## 9. ファイル構成

```
（リポジトリ）
├─ index.html              ← 画面
└─ functions/
    └─ api/
        └─ creator.js      ← 中継
```

`functions` フォルダは、かならずリポジトリのいちばん上に置く。Cloudflare Pages は、ここに置いたファイルを自動で `/api/creator` として動かす。

---

## 10. 置き方（GitHub → Cloudflare Pages）

### 10-0. 人の手が必要なところ（AIはここを必ず案内する）

次の操作は、ユーザー本人が画面で行う必要があります。AIは、1つずつ順番に案内してください。

1. GitHub のアカウントをつくる（またはログインする）
2. Cloudflare のアカウントをつくる（またはログインする）
3. GitHub にリポジトリをつくる
4. AI がそのリポジトリにファイルを入れられるように、連携・許可をする（できない環境では、手でファイルを入れる）
5. Cloudflare に、GitHub のリポジトリを見る許可を出す
6. Cloudflare Pages のプロジェクトを設定して、デプロイする
7. できあがったURLをひらいて、動作を確かめる

画面の文言やボタンの位置は変わることがあります。案内と画面が合わないときは、ユーザーにスクリーンショットを見せてもらい、AIが最新の公式の手順を確かめたうえで、その画面に合わせて案内し直してください。

### 10-1. アカウントを用意する

どちらも無料でつくれます。すでに持っている場合は、ログインできるかだけ確かめます。

- **GitHub**（ファイルを置いておく場所）：`https://github.com/` をひらき、Sign up（サインアップ）から、メールアドレス・パスワード・ユーザー名を決めて登録する。届いたメールの確認コードを入れる
- **Cloudflare**（ツールを公開する場所）：`https://dash.cloudflare.com/sign-up` をひらき、メールアドレスとパスワードで登録する。届いたメールで確認する

### 10-2. GitHub にリポジトリをつくる

リポジトリは、ファイルを入れておく「フォルダ」のようなものです。

1. GitHub 右上の「＋」→ New repository（新しいリポジトリ）
2. Repository name（リポジトリ名）を決める（例：`my-junkai`）
3. Private（非公開）を選ぶ
4. Add a README file（READMEファイルを追加）にチェック
5. Create repository（リポジトリを作成）

### 10-3. ファイルを入れる（AIが入れられる場合）

まず、AIがこのリポジトリを読み書きできる状態かを確かめます。できない場合、連携のしかたは使っているAIと環境によって違うので、AIは自分の環境の最新の手順を確かめてから、1ステップずつ案内してください。

よくある流れ：

1. AIの画面（または設定）から、GitHub との連携を始める
2. GitHub の許可画面がひらくので、Only select repositories（選択したリポジトリのみ）を選び、10-2 でつくったリポジトリにチェックを入れる
3. Install & Authorize（インストールして認可）のような緑のボタンを押す

連携できたら、AIが9章の2つのファイルを入れて、commit（変更の記録）と push（GitHub へ送る）まで行います。そのあと、ユーザーに GitHub のリポジトリのページをひらいてもらい、`index.html` と `functions` フォルダが見えるかを確かめてもらいます。

### 10-4. ファイルを入れる（手で入れる場合）

AIが直接入れられないときは、AIが2つのファイルの中身を出し、ユーザーが GitHub の画面で貼りつけます。

1. GitHub のリポジトリのページで、Add file（ファイルを追加）→ Create new file（新しいファイルを作成）
2. ファイル名の欄に `index.html` と入れる
3. 大きい入力欄に、AIが出した `index.html` の中身をまるごと貼る
4. Commit changes（変更をコミット）を押し、出てきた画面でもう一度 Commit changes を押す
5. もう一度、Add file → Create new file
6. ファイル名の欄に `functions/api/creator.js` と入れる（`/` を打つたびに、フォルダが自動でつくられる）
7. AIが出した `creator.js` の中身をまるごと貼り、Commit changes を2回押す

### 10-5. Cloudflare Pages とつなぐ

1. Cloudflare のダッシュボードで Workers & Pages（Workers と Pages）を開く
2. Create application（アプリケーションを作成）を押す
3. **Pages の入口を選ぶ**。「Looking to deploy Pages? Get started」のような小さい案内があるので、その Get started（始める）を押す
4. Connect to Git（Git に接続）を押す
5. はじめてのときは、GitHub の許可画面がひらく。Only select repositories（選択したリポジトリのみ）で 10-2 のリポジトリを選び、Install & Authorize（インストールして認可）のようなボタンを押す
6. Cloudflare の画面に戻り、リポジトリの一覧から 10-2 のリポジトリを選ぶ
7. 次のように設定する
   - Project name（プロジェクト名）：好きな名前（これがURLになる）
   - Production branch（プロダクション ブランチ）：`main`
   - Framework preset（フレームワーク プリセット）：None（なし）
   - Build command（ビルド コマンド）：空のまま
   - Build output directory（ビルド出力ディレクトリ）：`/`
8. Save and Deploy（保存してデプロイ）

**まちがえやすいところ①**：説明に「Worker プロジェクトを構成し…」と書いてある画面は、Pages ではなく Workers 用の画面です。そこでデプロイせずに戻って、Pages の入口から入り直してください。「Framework preset」と「Build output directory」の欄が出ていれば、Pages の画面で合っています。

**まちがえやすいところ②**：リポジトリが一覧に出てこないときは、Cloudflare にそのリポジトリを見る許可が出ていません。GitHub の右上のアイコン → Settings（設定）→ Applications（アプリケーション）→ Cloudflare の Configure（設定）を開き、Repository access（リポジトリへのアクセス）にそのリポジトリを足してください。

### 10-6. ひらいて確かめる

デプロイが終わると、`https://（プロジェクト名）.pages.dev/` で開けるようになります（同じ名前がすでに使われていると、後ろに文字が足されます。実際のURLは Cloudflare の画面で確かめます）。以後は、リポジトリに push するたびに自動で更新されます。

このURLは、知っている人なら誰でも開けます。パスワードはかかっていません。登録したリスト自体は各自のブラウザの中にあるので、ほかの人に見えることはありません。

---

## 11. 動作確認チェックリスト

1. 「＋ 追加」で、noteのIDを入れて「取得」を押すと、アカウント名とアイコンが出る
2. 「保存」で、リストに並ぶ
3. 名前を押すと、その人の note が新しいタブで開き、チェックが付く
4. 上の「今日は ○ ／ ○ 人」が増える
5. 「設定」でリセット時刻を「いまの1〜2分あと」にして待つと、チェックが全部はずれる
6. グループ名を押すと、折りたためる。開き直しても状態が残っている
7. 「編集」で、ハンドルをドラッグして並び替えられる。別のグループへも動かせる
8. スマホでも、1〜7が同じようにできる
9. 「設定」のバックアップをコピーして、別のブラウザ（またはスマホ）で読み込める

---

## 12. つまずきやすいところ

- **「取得」を押すと 404 や 405 になる**：`creator.js` が `onRequestGet` を書き出しているか確かめる（書き方が違うと、Cloudflare Pages が中継として認識しない）
- **「取得」がずっと失敗する**：`functions/api/creator.js` がリポジトリのいちばん上の `functions` フォルダに入っているか確かめる。また、`index.html` をパソコンから直接ひらいている（`file://`）と、中継が無いので取得できない。Cloudflare Pages のURLで開く
- **ドラッグしても順番が保存されない**：5-5 の「大事な注意」を確かめる
- **スマホでドラッグすると画面がスクロールしてしまう**：ハンドルに `touch-action: none` が付いているか確かめる
- **パソコンとスマホでリストが違う**：データはブラウザごとに別々に保存される。バックアップのコピーと読み込みで移す
- **アイコンが古い**：アイコンと名前は、登録したときのものを保存している。「編集」から「取得」を押すと新しくなる

---

## 更新履歴

- 2026-11-18：最初の版
- 2026-11-18：置き方（10章）を書き足し。人の手が必要な操作（アカウントづくり、GitHubの連携と許可、手でファイルを入れる方法、Cloudflareへの許可）を、すべて手順として入れた
- 2026-11-18：中継の書き方（`onRequestGet` を書き出す）を明記
