@umec/core 0.1.0-alpha.11 → 0.1.0-alpha.12

package/registry/disclosure/manifest.md

@@ -0,0 +1,242 @@
+---
+id: disclosure
+version: 0.2.0
+requires: { core: ">=0.1.0-alpha.11" }
+touches: [src/pages/legal/disclosure.astro, src/pages/api/disclosure-request.ts, src/lib/disclosure-request.ts, src/lib/disclosure-db.ts, src/lib/disclosure-send.ts, src/pages/admin/disclosure.astro, src/pages/api/admin/disclosure-send.ts, migrations/local/0001_disclosure_requests.sql, src/pages/legal/tokushoho.astro, src/worker.ts, wrangler.jsonc, .doc/AGENTS.md, src/pages/admin/inventory.astro, src/pages/admin/orders.astro, src/pages/admin/products.astro]
+risk: high            # high: 法務判断を含む。弁護士確認前は本番有効化しない
+---
+# 特商法開示請求（PaF-1〜PaF-3）
+
+umec-template の特商法「全項目非表示 + 開示請求フォーム + 即時自動開示メール + 管理画面 +
+日次リマインダ」機能を、既存インスタンスへ届ける registry item。
+
+**v0.2.0の変更**: PaF-2（管理画面・再送）・PaF-3（日次リマインダ）を追加収録。
+`src/lib/disclosure-request.ts` と `src/lib/disclosure-db.ts` の内容が更新されている
+（PaF-3の関数追加）ため、v0.1.0を適用済みのインスタンスに再適用する場合は
+`umec add disclosure --force` が必要（未改変ファイルへの正規バージョンアップであることを
+確認してから使うこと）。
+
+適用先は **umec-template >= 0.1.0 由来のインスタンス**（機械可読な `requires` は CLI が解釈できる
+`core` / `admin` / `items` のみのため、`@umec/core >=0.1.0-alpha.11` を記録する）。
+
+`files/` には設計書 §10.4 の「機械的に配布してよい新規ファイル」だけを置く。
+ブランド固有の既存ファイルは **`files/` に含めない**。`umec add --force` でも上書きされない。
+
+実体は umec-template `b0c5f69`（2026-09-17、PaF-1 dogfood）の main からコピーした。
+
+**この item を適用しただけでは本番で有効にならない。** 手作業再適用・vars/Secret・
+`umec migrate`・弁護士確認が揃うまで、特商法ページの表示も cron も開示メールも動かない。
+
+## 弁護士確認が済んでいない（設計書 §9.2）
+
+コードは dogfood として umec-template に入っているが、次は未確認。**本番店舗（runrun 含む）では
+有効化しない。** go/no-go は事業者（Daisuke）が弁護士確認後に判断する。
+
+| # | 項目 | 影響 |
+|---|---|---|
+| 1 | 請求手段がフォームのみ（メール・電話を出さない）が執行で「請求できる状態」と認められるか | 認められない場合はメールアドレス表示＋フォーム併設へ戻す |
+| 2 | 即時自動送信で「意思決定前の時間的余裕」を満たすと言えるか | 満たせないなら全項目非表示モード自体を提供しない |
+| 3 | APPI 第32条の取扱事業者情報公表と全項目非表示の同時達成 | `privacy.astro` の事業者名・問い合わせ先の扱い |
+| 4 | 第三者メールアドレス記載時の漏洩が「必要な範囲の提供」と言えるか | 追加緩和策の要否 |
+| 5 | 将来の特商法改正（2026年検討会） | 追従方針のみ |
+| 6 | 全項目非表示モードのトレードオフ承認（auto 開示による機械的収集リスク） | 提供開始の go/no-go |
+| 7 | バーチャルオフィスを開示住所にする場合の Q18 要件 | セットアップ注記 |
+| 8 | テンプレート既定の表示モード（全項目非表示 vs 氏名表示＋住所電話開示） | 既定の方針決定 |
+
+## 法務リサーチの要点（設計書 §0.1）
+
+- 氏名・住所・電話番号は、ただし書（請求により遅滞なく電磁的記録を提供する旨の表示＋実際の体制）により省略可能（消費者庁通信販売広告 Q&A Q15/Q17）
+- メールアドレスはウェブサイト広告の法定表示事項ではない。ただし通信販売電子メール広告を送る場合、そのメール本文に事業者メールアドレスは必須
+- 「遅滞なく」＝申込みの意思決定に先立って十分な時間的余裕。即時購入可能な店では **自動即時送信が本線**
+- なりすまし対策は CAPTCHA・同一 IP レート制限。「購入者限定・注文番号必須・身分証」は法的に危険
+- 開示内容は省略した全項目を、印刷可能なメール本文/添付で返す
+- 屋号を法定の「氏名又は名称」の代わりに出してはならない。出ない電話・実在しない住所も不可
+
+## `umec add disclosure` がコピーするファイル（新規 + 更新）
+
+| パス | 役割 |
+|---|---|
+| `src/pages/legal/disclosure.astro` | 請求フォーム（メールのみ、Turnstile） |
+| `src/pages/api/disclosure-request.ts` | 受付 API の薄いアダプタ |
+| `src/lib/disclosure-request.ts` | バリデーション、Turnstile、レート制限、即時開示メール、事業者通知、cron リトライ、日次リマインダ（PaF-3） |
+| `src/lib/disclosure-db.ts` | インスタンス所有テーブル `disclosure_requests` の読み書き（一覧・未開示取得を含む） |
+| `src/lib/disclosure-send.ts` | 管理画面からの再送・手動開示ロジック（PaF-2） |
+| `src/pages/admin/disclosure.astro` | 請求一覧・再送・手動開示画面（PaF-2、`requireAdminAuth`保護） |
+| `src/pages/api/admin/disclosure-send.ts` | 再送・手動開示 API（PaF-2） |
+| `migrations/local/0001_disclosure_requests.sql` | 加算 DDL |
+
+PaF-1のみ適用済み（v0.1.0）のインスタンスにv0.2.0を適用する場合、`disclosure-request.ts`と
+`disclosure-db.ts`は内容が変わるため`--force`が必要（他の新規ファイルはそのまま追加される）。
+
+### マイグレーション番号（必ず読み直すこと）
+
+`files/` の SQL はテンプレート正本の番号 **`0001_disclosure_requests.sql` のまま**置く。
+**適用先インスタンスの `migrations/local/` に既に `0001_*.sql` がある場合は、コピー後に
+次番号へリネームしてから `umec migrate` すること。** 同名ファイルの上書き適用はしない
+（`0002_orders.sql` 事故と同じ形状になる）。
+
+今回の自動コピーは番号を書き換えない。実際の採番し直しと D1 適用は、弁護士確認後に
+適用者が判断する。適用経路は `umec migrate` のみ。`wrangler d1 migrations apply` は使わない。
+
+runrun の `migrations/local/` は 2026-09-17 時点で `.gitkeep` のみなので、初回適用なら
+`0001_` のままで衝突しない。それでも適用前にディレクトリを目視すること。
+
+## 手作業で再適用するファイル（`files/` に入れない）
+
+設計書 §10.4: インスタンスが既にブランド固有のカスタマイズをしている可能性が高く、
+機械的な上書きは危険。差分の持ち込みではなく、下記の変更内容を手で再適用する。
+
+### 1. `src/pages/legal/tokushoho.astro`（設計書 §1）
+
+販売事業者名・運営責任者・所在地・電話番号・メールアドレスの5行を1ブロックに置き換え、
+`/legal/disclosure` へリンクする。販売価格・支払方法・支払時期・引渡時期・返品の5行は
+現行どおり維持（省略不可）。屋号を法定名の代わりにしない。
+
+文案ブロック（全項目非表示モード）:
+
+> 販売事業者名・運営責任者名・所在地・電話番号・メールアドレスについては、ご請求があった場合に、**遅滞なく電子メールで提供**いたします。→ **開示のご請求はこちら**（`/legal/disclosure`）
+
+umec-template の実体（CSS トークンはインスタンス側のクラス名に合わせる）:
+
+```astro
+const identityLabel = '販売事業者名・運営責任者・所在地・電話番号・メールアドレス';
+```
+
+```html
+<dt>{identityLabel}</dt>
+<dd>
+  販売事業者名・運営責任者名・所在地・電話番号・メールアドレスについては、ご請求があった場合に、<strong>遅滞なく電子メールで提供</strong>いたします。
+  <a href="/legal/disclosure">開示のご請求はこちら</a>
+</dd>
+```
+
+ページは `prerender = true` のまま。runrun は販売条件が既に実データなので、
+条件5行は触らず、身元5行だけを差し替える。
+
+段階的有効化（§10.4-5）: フォームと API が動くまでは tokushoho の現行表示を残し、
+動作実績の後にこの差し替えを行う。ロールバックは tokushoho を元に戻すだけで足りる。
+
+### 2. `src/worker.ts`（設計書 §3.3・§5.3）
+
+`scheduled()` に `retryDisclosureEmails()`（15分cron）と `alertStaleDisclosureRequests()`
+（日次cron、PaF-3）を追加する。即時送信が Resend 5xx / タイムアウト / レート制限で失敗したら
+その場で1回リトライし、それでもダメなら行を `received` のまま残して cron に委譲する。
+上限（既定 3）を超えた行は無限リトライしない。日次リマインダは未開示行がある場合のみ
+事業者へ一覧メールを送る。
+
+15分 cron（`*/15 * * * *`）では既存の日次未発送アラート・日次リマインダを再実行しない。
+runrun の `fetch()` にある `www.runrun.kids` → `runrun.kids` の 301 は残す。
+
+```ts
+import { formatEmailFrom } from '@umec/core/config';
+import config from '../umec.config';
+import {
+  DISCLOSURE_RETRY_CRON,
+  retryDisclosureEmails,
+  alertStaleDisclosureRequests,
+  type DisclosureBrandContext,
+  type DisclosureEnv,
+} from './lib/disclosure-request';
+
+function disclosureBrandContext(): DisclosureBrandContext {
+  return {
+    brandName: config.brand.name,
+    brandUrl: String(config.brand.url),
+    emailFrom: formatEmailFrom(config.email),
+    emailReplyTo: config.email.replyTo,
+    notifyFallback: config.email.bcc,
+  };
+}
+
+async scheduled(controller: { cron?: string }, env: WorkerEnv) {
+  // 15-minute disclosure retry must not re-fire the daily unshipped alert
+  // or the daily undisclosed-request reminder.
+  if (controller?.cron !== DISCLOSURE_RETRY_CRON) {
+    try {
+      await alertUnshippedOrders(env);
+    } catch {
+      console.error('[scheduled/unshipped] alert failed');
+    }
+    try {
+      await alertStaleDisclosureRequests(env, disclosureBrandContext());
+    } catch {
+      console.error('[scheduled/disclosure] stale reminder failed');
+    }
+  }
+  await retryDisclosureEmails(env, disclosureBrandContext());
+}
+```
+
+正本は umec-template `src/worker.ts`。適用者は既存インスタンスの `fetch()` 実装
+（301リダイレクト等のブランド固有処理）を残したまま、`scheduled()` とimport文だけを
+上記の形に揃えること。
+
+`WorkerEnv` に `DisclosureEnv` を交差させる。
+
+### 3. `wrangler.jsonc`（設計書 §3.3・§7）
+
+既存の日次 cron は消さず、15分 cron を併記する。vars に Secret を書かない。
+runrun は既に `PUBLIC_STRIPE_PUBLISHABLE_KEY` 等の vars と `account_id` を持っているので、
+テンプレートの wrangler を丸ごとコピーしない。
+
+```jsonc
+"vars": {
+  // DISCLOSURE_PAYLOAD / DISCLOSURE_MODE / DISCLOSURE_NOTIFY_TO / DISCLOSURE_RATE_* /
+  // DISCLOSURE_RETRY_MAX / PUBLIC_TURNSTILE_SITE_KEY は .dev.vars またはダッシュボード vars で設定する。
+  // TURNSTILE_SECRET_KEY / DISCLOSURE_IP_SALT は wrangler secret put で設定する（vars に書かない）。
+},
+"triggers": {
+  "crons": ["0 0 * * *", "*/15 * * * *"]
+}
+```
+
+### 4. `.doc/AGENTS.md`（設計書 §7）
+
+環境変数表へ追記する。値は git に入れない。
+
+Secret（`wrangler secret put`）:
+
+| 変数名 | 用途 |
+|---|---|
+| `TURNSTILE_SECRET_KEY` | Cloudflare Turnstile のサーバ検証 |
+| `DISCLOSURE_IP_SALT` | IP ハッシュ用 salt。未設定でも動くが非推奨 |
+
+ビルド変数 / vars（`.dev.vars` またはダッシュボード。Secret ではないが git 禁止）:
+
+| 変数名 | 用途 | 未設定時 |
+|---|---|---|
+| `PUBLIC_TURNSTILE_SITE_KEY` | Turnstile ウィジェット。本番では必須 | 本番 503・dev スキップ |
+| `DISCLOSURE_PAYLOAD` | 開示内容 JSON（`sellerName` / `operatorName` / `address` / `phone` / `email`） | 開示実行時にエラー＋事業者通知 |
+| `DISCLOSURE_MODE` | `auto`（既定）/ `manual`。全項目非表示では `manual` 不可 | auto |
+| `DISCLOSURE_NOTIFY_TO` | 事業者通知 To | `config.email.bcc` → 無ければ通知スキップ |
+| `DISCLOSURE_RATE_PER_EMAIL` / `DISCLOSURE_RATE_PER_IP` / `DISCLOSURE_RATE_GLOBAL` | 1日あたりレート | 3 / 10 / 50 |
+| `DISCLOSURE_RETRY_MAX` | 開示メール自動リトライ上限 | 3 |
+
+```
+DISCLOSURE_PAYLOAD={"sellerName":"...","operatorName":"...","address":"...","phone":"...","email":"..."}
+```
+
+### 5. `src/pages/admin/inventory.astro` / `orders.astro` / `products.astro`（PaF-2）
+
+既存ナビに1行追加するだけ（`@umec/admin`配線後もこの3ファイルの markup 自体は
+インスタンス所有のまま。実質バイト一致している運用層なので機械上書きしても安全なはずだが、
+念のため手作業リストに残す）:
+
+```html
+<a href="/admin/disclosure" class="text-sm underline decoration-border underline-offset-4 hover:text-accent">開示請求</a>
+```
+
+既存の「CSV出力」「商品管理」「注文一覧」等のリンクの直後に追記する。3ファイルとも同じ形。
+
+## 適用後に残る作業（自動ではやらない）
+
+1. `migrations/local/` の次番号を確認し、必要なら SQL をリネームして `umec migrate`
+2. 上記5ファイル（tokushoho.astro / worker.ts / wrangler.jsonc / .doc/AGENTS.md /
+   admin 3ページのナビ）の手作業再適用
+3. vars / Secret をインスタンス用に設定（コード配布とは別作業）
+4. 段階的有効化（§10.4-5）:
+   1. `DISCLOSURE_MODE=manual` でフォームのみ（tokushoho は現行表示のまま）
+   2. 受付→通知の動作確認、管理画面（PaF-2）での目視確認
+   3. 問題なければ tokushoho を非表示モードへ
+   4. 実績を見て `auto` に切り替え
+5. 弁護士確認とトレードオフ承認（§9.2-6）が済むまで本番有効化しない

package/registry/example-hello/files/src/example-hello.txt

@@ -0,0 +1 @@
+This file was added by `umec add example-hello`.

package/registry/example-hello/manifest.md

@@ -0,0 +1,10 @@
+---
+id: example-hello
+version: 1.0.0
+requires: { core: ">=0.1.0-alpha.11" }
+touches: [src/example-hello.txt]
+risk: low            # low: UI のみ / medium: DB・API / high: 決済経路
+---
+# ハローサンプル
+
+顧客リポジトリへサンプルテキストを1ファイル追加する、registry CLI の動作確認用 item。