145 lines
5.4 KiB
Markdown
145 lines
5.4 KiB
Markdown
# 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 で先に作成する**
|