mai
/
posimai-root
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
posimai-root/docs/LEARNINGS.md

5.5 KiB
Raw Blame History

Posimai Project — AI 学習ログ

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

デプロイ・Git 関連

Gitea push "Push to create is not enabled"

  • 問題: リポジトリが存在しない状態で push すると失敗する
  • 解決策: Gitea API でリポジトリを先に作成してから push する 
    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
  • 環境変数未設定時は認証スキップ（デフォルト認証情報は削除済み）

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

アプリ種別 認証 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@0.344.0（バージョン固定必須。@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 で実証済み）

// 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 で実証済み）

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 で先に作成する