# Posimai Project — AI 学習ログ

このファイルはすべての AI エージェントが読むべき「現場で学んだ知見」のログです。
新しい重要な発見があれば、ここに追記してください。

---

## デプロイ・Git 関連

### Gitea push "Push to create is not enabled"
- **問題**: リポジトリが存在しない状態で push すると失敗する
- **解決策**: Gitea API でリポジトリを先に作成してから push する
  ```bash
  curl -X POST "$GITEA_URL/api/v1/user/repos" -u "mai:$PASS" \
    -d '{"name":"app-id","private":true,"auto_init":false}'
  ```

### Gitea API 認証は Basic Auth を使う
- **問題**: `Authorization: token` ではなく Basic Auth で認証する必要がある
- **正しい方法**: `curl -u "mai:$GITEA_PASS"` または `-H "Authorization: Basic base64(mai:pass)"`
- **パスワード取得**: `printf "protocol=http\nhost=100.76.7.3\n" | git credential fill`

### npm run deploy の直列化
- `git push gitea main && git push github main` は `&&` で連結済み
- Gitea が失敗すると GitHub には push されない（意図した動作）

### GitHub push でメールプライバシーエラー（GH007）
- **原因**: GitHub の「コマンドラインプッシュでメールを公開するブロック」設定
- **解決**: Settings > Emails > "Block command line pushes that expose my email address" を OFF
- **安全性**: リポジトリが private なら安全

---

## Vercel 関連

### Vercel git connect で複数リモートがある場合
- **問題**: gitea と github の2リモートがあると、どちらに接続するか対話的に聞かれる
- **解決策**: `printf "2\n" | vercel git connect "https://github.com/posimai/$APP_ID.git" --yes`
  （github は通常2番目に表示される）

### Vercel 環境変数の Sensitive 設定
- Sensitive な変数は Development 環境では設定不可
- Production + Preview のみ選択して作成する

### `vercel --prod` は直接実行しない
- GitHub push → Vercel 自動デプロイの流れを壊す
- 必ず `npm run deploy`（= `git push gitea main && git push github main`）を使う

---

## 認証・セキュリティ関連

### Magic Link 認証パターン（Brain 専用）
- `?init_key=xxx` URLパラメータで API キーを localStorage に自動セット
- Synology API が稼働していることが前提
- 静的アプリ（events/maps/hotels/reader/together）には不要

### Basic Auth（dashboard/analytics）
- `middleware.ts` で実装
- 環境変数: `BASIC_AUTH_USER` / `BASIC_AUTH_PASSWORD`
- デフォルト: `mai / posimai`

### アプリ種別と認証の必要性

| アプリ種別 | 認証 | URLだけで見られるか |
|-----------|------|-------------------|
| 静的（events/hotels/maps/reader/together） | なし | Yes |
| Brain / Feed | Magic Link（任意） | Yes（ゲストモードあり） |
| Dashboard / Analytics | Basic Auth | No（パスワード必要） |

---

## デザインシステム

### アクセントカラーの現状（2026-03-11 時点）
- **公式（新）**: `#6EE7B7`（Posimai Teal）— テンプレート・projects.json で採用
- **旧**: `#818CF8`（Indigo）— Brain / Feed / Reader で未移行
- **方針**: 新規アプリはすべて Teal。旧アプリは次のリファクタ時に移行

### 絵文字は絶対禁止
- ユーザーの明示的なルール
- CSS コメントにも記載済み
- AI がこのルールを破った場合は即 revert する

### Lucide アイコンのみ使用
- stroke: 1.5〜2.0
- CDN: `https://unpkg.com/lucide@latest`
- 他のアイコンセット（Font Awesome 等）は使わない

---

## アーキテクチャ判断

### CDN 依存（バンドルツールなし）は意図的な選択
- Vite 等の導入は非エンジニアにとって「ビルドエラー」という障壁を生む
- 2026年の規模（9〜20アプリ）では CDN で十分
- オフライン強化が必要になったときのみ検討する

### Synology NAS 上での直接作業は避ける
- AI ツール（Claude Code / Cursor）のファイルスキャンが著しく遅くなる
- 作業: ローカル PC（SSD 上）
- バックアップ: Gitea（push 時に自動）

### Dev Containers は現時点で不要
- 開発者が 1 名のうちは README.md のセットアップ手順で十分
- 将来コントリビューターが増えたときに検討する

---

## コードパターン

### Stale-While-Revalidate（Brain で実証済み）
```js
// 1. キャッシュからの即時描画
const cached = loadFromStorage();
if (cached) render(cached);

// 2. API フェッチ → 差分更新
fetch(API_URL, { headers: authHeaders() })
  .then(res => res.json())
  .then(data => {
    saveToStorage(data);
    render(data);
  })
  .catch(() => { /* キャッシュのまま継続 */ });
```

### タイムアウト付き fetch（Brain で実証済み）
```js
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 8000);
fetch(url, { signal: controller.signal })
  .finally(() => clearTimeout(timeoutId));
```

---

## よくあるミス

1. `git push origin` を使う → **gitea / github の2リモートを使う**
2. `vercel --prod` を直接実行 → **`npm run deploy` のみ**
3. 絵文字をコードに追加 → **即 revert**
4. `--accent` 以外のカラーを追加 → **デザイントークンの変更禁止**
5. Gitea リポジトリ未作成で push → **API で先に作成する**