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