From 1d9c2b5f3d8bae0a42d5f1e151079c0731dc8a3d Mon Sep 17 00:00:00 2001 From: posimai Date: Sat, 11 Apr 2026 12:05:03 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20new-app-guide.md=20=E3=82=92=E7=8F=BE?= =?UTF-8?q?=E8=A1=8C=E7=8A=B6=E6=85=8B=E3=81=AB=E5=85=A8=E9=9D=A2=E6=9B=B4?= =?UTF-8?q?=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - create-app.sh の Step 8（ダッシュボード自動更新）を反映 - テンプレートを _template-minimal 一本化に変更 - Alpine.js をパターンBとして追加（ビルド不要・reactive state） - SW キャッシュ更新タイミングの方針を明記 - 実装チェックリストを追加 - 旧手動ステップ（自動化済み）を削除・整理 Co-Authored-By: Claude Sonnet 4.6 --- docs/new-app-guide.md | 286 ++++++++++++++++++++++++++++++++---------- 1 file changed, 222 insertions(+), 64 deletions(-) diff --git a/docs/new-app-guide.md b/docs/new-app-guide.md index b41fa46e..6736e72e 100644 --- a/docs/new-app-guide.md +++ b/docs/new-app-guide.md @@ -1,94 +1,252 @@ # 新アプリ作成ガイド -**このドキュメントは `posimai-project` で新しい PWA アプリを作成し、エコシステム（ダッシュボード等）に統合するための完全な手順書です。** +**最終更新: 2026-04-11** -## 1. テンプレート選択 +`posimai-project` で新しい PWA アプリを作成し、エコシステムに統合するための完全な手順書。 + +--- + +## 0. テンプレート選択 | テンプレート | 使うべきアプリ | |------------|--------------| -| `_template/` | 複数ビュー・i18n・Magic Link 認証・サイドバーナビが必要なアプリ（brain, daily, together, journal 相当） | -| `_template-minimal/` | 単機能ツール・サイドバー不要なアプリ（diff, clean, timer, lens, ambient 相当） | +| `_template-minimal/` | **全ての新規アプリ**（現行標準） | -迷ったら `_template-minimal/` を選ぶ（後からフル機能に移行する方が簡単）。 +`_template/`（旧フル版）は廃止予定。`_template-minimal/` が唯一の基準。 -`create-app.sh` で新規アプリを一括セットアップ可能（Git 初期化 + Gitea/GitHub リポジトリ作成 + Vercel 連携まで自動）: +### テンプレートに含まれるもの + +- `index.html` — posimai-ui 参照・JWT token handoff・PWA meta 完備 +- `sw.js` — stale-while-revalidate + skipWaiting（即時反映） +- `manifest.json` — PWA 必須ファイル +- `package.json` — `npm run deploy` スクリプト + +--- + +## 1. アプリ分類と技術選定 + +### 実装パターンの選び方 + +| パターン | 対象 | 具体例 | +|---------|------|--------| +| **A: 静的 HTML + posimai-ui** | 単機能ツール・表示系 | diff, clean, timer, lens, ambient | +| **B: 静的 HTML + posimai-ui + Alpine.js** | 状態管理が必要なアプリ | brain, feed, journal, habit, pulse 相当の新アプリ | +| **C: Next.js** | 複雑なデータダッシュボード・管理画面 | dashboard, analytics 相当のみ | + +**迷ったらパターン A から始める。** 後から Alpine.js を足す方が、最初から Next.js にするより簡単。 + +### Alpine.js の追加（パターン B） + +```html + + +``` + +バージョンは `3.14.3` 固定（`@latest` 禁止）。使い方: + +```html +
+ + +
+``` + +--- + +## 2. 実装前チェック（0 番台） + +### 0. アクセントカラーを確定する + +デフォルトの Teal (`#6EE7B7`) で問題なければ何もしない。 +変更する場合は `docs/design-system.md` の「アプリ別アクセントカラー」テーブルに**先に追記**してから実装を開始する。 + +カテゴリ別ガイドライン: + +| カテゴリ | 推奨アクセント | +|---------|--------------| +| input / routine / create / tools | `#6EE7B7` Teal（デフォルト） | +| インフラ / 開発ツール | `#22D3EE` Cyan または `#A78BFA` Violet | +| 公開サイト / CMS | `#80CAEE` Sky-Blue | +| 和風 / 特殊テーマ | デザインシステム外で独自定義 | + +### 0.5. logo.png 用 Gemini プロンプトを作成する + +**共通プロンプト（全アプリ固定）:** + +``` +App icon, 512x512px, squircle shape with rounded corners. +A small translucent glass orb character, soft matte-frosted surface with +inner teal (#6EE7B7) luminescence glowing from within, gentle light refraction. +Two tiny calm black dot eyes, subtle implied smile. +Background: deep charcoal (#0D0D0D) with barely visible teal ambient gradient. +Style: Apple Liquid Glass, multi-material, 2026 premium minimal. +No outline, no harsh edges. Soft depth, subsurface scattering. +``` + +アプリ固有の追加プロンプトを末尾に付ける（「持っているもの」「背景の変化」等の感覚的な表現でよい）。 + +--- + +## 3. 新規アプリ作成（コマンド 1 行） ```bash bash create-app.sh posimai-myapp "My App Name" "アプリの説明" ``` -## 2. 新アプリ作成後の必須チェックリスト（抜け漏れ禁止） +**このコマンドで自動完了するもの:** -新しいアプリを作ったら、**必ずこの順番で実行する**こと（0番台は実装開始前、1番以降は実装完了後）： +| ステップ | 内容 | +|---------|------| +| 1 | `_template-minimal/` をコピーして APP_ID/APP_NAME/APP_DESC を置換 | +| 2 | Git 初期化・初回コミット | +| 3 | Gitea にリポジトリ作成（git credential store から自動認証） | +| 4 | GitHub にリポジトリ作成（`gh` CLI） | +| 5 | 2リモート（gitea + github）に push | +| 6 | Vercel と GitHub を連携 | +| 7 | 初回本番デプロイ（空 commit で trigger） | +| 8 | `projects.json` にカード追加 | +| 8 | `timeline/page.tsx` に launch エントリ追加 | +| 8 | `roadmap.json` に追加 | +| 8 | dashboard / roadmap をデプロイ | -0. **【実装前】アクセントカラーを宣言する** - - このアプリのカテゴリを確認（`input` / `routine` / `create` / `tools` / `business` / `infra` / `ideas`） - - デフォルト Teal (`#6EE7B7`) で問題なければ何もしない - - 変更する場合は `docs/design-system.md` の「アプリ別アクセントカラー」テーブルに**先に追記**してから実装を開始する +--- -0.5. **【実装前】logo.png 用 Gemini プロンプトを作成・提示する** - - 構成: 以下の共通プロンプト + アプリ固有の追加プロンプト（感覚的な表現） +## 4. 手動で追加が必要なもの（判断が必要なため自動化不可） - **共通プロンプト（全アプリ固定）:** - ``` - App icon, 512x512px, squircle shape with rounded corners. - A small translucent glass orb character, soft matte-frosted surface with - inner teal (#6EE7B7) luminescence glowing from within, gentle light refraction. - Two tiny calm black dot eyes, subtle implied smile. - Background: deep charcoal (#0D0D0D) with barely visible teal ambient gradient. - Style: Apple Liquid Glass, multi-material, 2026 premium minimal. - No outline, no harsh edges. Soft depth, subsurface scattering. - ``` +### 4-A. apps/page.tsx の projectIds に追加 -1. **Git 初期化・リポジトリ作成・初回 push** - ```bash - cd posimai-[app-name] - git init && git add . && git commit -m "feat: initial commit" +`posimai-dashboard/src/app/apps/page.tsx` の `APP_CATEGORIES` から適切なカテゴリを選んで `projectIds` に追加する。 - # Gitea リポジトリ作成 - GITEA_PASS=$(git credential fill <<< $'protocol=http\nhost=100.76.7.3:3000' | grep password | cut -d= -f2) - curl -s -X POST "http://100.76.7.3:3000/api/v1/user/repos" \ - -H "Content-Type: application/json" -u "mai:$GITEA_PASS" \ - -d "{\"name\":\"posimai-[app-name]\",\"private\":false,\"auto_init\":false}" - git remote add gitea http://100.76.7.3:3000/mai/posimai-[app-name].git +カテゴリ一覧: `input` / `routine` / `create` / `tools` / `business` / `infra` / `ideas` - # GitHub リポジトリ作成 - gh repo create posimai/posimai-[app-name] --private --source=. --remote=github - npm run deploy - ``` +### 4-B. ecosystem/page.tsx のノード/エッジに追加 -2. **Vercel に接続して初回デプロイをトリガーする** - ```bash - echo "https://github.com/posimai/posimai-[app-name].git" | vercel git connect --yes - git commit --allow-empty -m "ci: trigger initial Vercel deployment" - npm run deploy - ``` +`posimai-dashboard/src/app/ecosystem/page.tsx` の `NODES` と `EDGES` に追加する。 +接続関係（VPS API を使うか・他アプリからデータを受け取るか）を判断して記述する。 -3. **Dashboard カード追加** - - `posimai-dashboard/src/data/projects.json` に追加 +### 4-C. logo.png の配置とデプロイ -4. **App Browser カテゴリに追加** - - `posimai-dashboard/src/app/apps/page.tsx` に追加 +Gemini で生成した logo.png をアプリディレクトリに配置後: -5. **Ecosystem Map 追加** - - `posimai-dashboard/src/app/ecosystem/page.tsx` に追加 +```bash +cd posimai-[app-name] +git add logo.png +git commit -m "feat: logo 追加" +npm run deploy +``` -6. **Development Timeline に追記** - - `posimai-dashboard/src/app/timeline/page.tsx` の `EVENTS` に `launch` エントリ追加 +### 4-D. Dashboard をデプロイ（4-A / 4-B 完了後） -7. **Access Guide に追記** - - `posimai-dashboard/src/app/access/page.tsx` に追記 +```bash +cd posimai-dashboard +git add src/app/apps/page.tsx src/app/ecosystem/page.tsx +git commit -m "feat: [app-name] をエコシステムに追加" +npm run deploy +``` -8. **Roadmap サイドバーに追加** - - `posimai-roadmap/roadmap.json` に `{ "id": "posimai-[app-name]", "tasks": [] }` を追加して `npm run deploy` +--- -9. **Dashboard をデプロイ** - ```bash - npm run deploy - ``` +## 5. アプリ固有の実装ガイドライン -10. **プロジェクト構成テーブルを更新** - - `docs/master-architecture.md` のアプリ一覧に追加 +### CSS の書き方 -11. **logo.png デプロイ** - - ユーザーが `logo.png` を配置した後、コミット＆デプロイ +```html + +``` + +**禁止:** +- `color: #6EE7B7` のような直接カラーコード（`var(--accent)` を使う） +- posimai-ui のトークン外の色（`--champions` `--teal-dim` 等は analytics 専用） + +### API 呼び出しの書き方 + +```js +const API_BASE = 'https://api.soar-enrich.com/brain/api'; +const token = localStorage.getItem('posimai_token'); + +const res = await fetch(`${API_BASE}/your-endpoint`, { + headers: { 'Authorization': `Bearer ${token}` } +}); +if (!res.ok) throw new Error('API error'); +const data = await res.json(); +``` + +### VPS API を使う新アプリの場合 + +`server.js` に新しいエンドポイントを追加する場合は `bash deploy-server.sh` でバックエンドをデプロイする。 +スキーマ変更（ALTER TABLE / DROP TABLE）は mai 確認必須。 + +### SW キャッシュバージョンの管理 + +`sw.js` の `const CACHE = 'APP_ID-v2';` の数値を変更すると旧キャッシュが削除される。 +機能追加・デザイン変更のたびに更新する必要はない。**ファイル追加・削除時のみ更新する。** + +--- + +## 6. 実装チェックリスト（完了確認） + +アプリ実装完了前に以下を全て確認すること: + +``` +[ ] index.html の が正しいか +[ ] manifest.json の "id" が "/posimai-[app-name]/" になっているか +[ ] sw.js の CACHE 名に APP_ID が入っているか +[ ] posimai-ui の base.css / base.js を参照しているか +[ ] デザイントークン外の色を直書きしていないか +[ ] 外部リンクに rel="noopener" が付いているか +[ ] 絵文字が含まれていないか（コード・UI・コミット全て） +[ ] Lucide のバージョンが @0.344.0 固定になっているか +[ ] 空状態（Empty State）が実装されているか +[ ] PWA インストール可能か（manifest + SW + HTTPS） +[ ] logo.png が配置されているか +``` + +--- + +## 7. デプロイ手順（再掲） + +```bash +# フロントエンド（全アプリ共通） +git add . && git commit -m "feat/fix/chore: ..." && npm run deploy +# = git push gitea main && git push github main → Vercel 自動デプロイ + +# VPS バックエンド（server.js 変更時） +bash deploy-server.sh + +# Ubuntu PC（posimai-dev / Station 変更時） +npm run deploy:dev # git push + scp + systemctl restart +``` + +**禁止:** +- `vercel --prod` 直接実行 +- `git push origin`（gitea と github の2リモートを必ず両方 push） + +--- + +## 8. 参照ドキュメント + +| ドキュメント | 内容 | +|-------------|------| +| `docs/design-system.md` | カラートークン・フォント・アイコンルール | +| `docs/master-architecture.md` | インフラ構成・全アプリ一覧・URL | +| `docs/disaster-recovery.md` | PC 消失時の復元手順 | +| `docs/server-refactor-plan.md` | server.js 設計・分割方針 | +| `posimai-ui/public/v1/base.css` | 共通スタイルの実装 | +| `posimai-ui/public/v1/base.js` | 共通 JS（テーマ・設定パネル・Toast・SW 登録・Lucide） | +| `STATUS.md` | 今何をしている最中か（毎セッション参照・更新） |