posimai-root/docs/new-app-guide.md

# 新アプリ作成ガイド

**最終更新: 2026-04-11**

`posimai-project` で新しい PWA アプリを作成し、エコシステムに統合するための完全な手順書。

---

## 0. テンプレート選択

| テンプレート | 使うべきアプリ |
|------------|--------------|
| `_template-minimal/` | **全ての新規アプリ**（現行標準） |

`_template/`（旧フル版）は廃止予定。`_template-minimal/` が唯一の基準。

### テンプレートに含まれるもの

- `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
<!-- </body> 直前の base.js の後に追記 -->
<script src="https://cdn.jsdelivr.net/npm/alpinejs@3.14.3/dist/cdn.min.js"
        integrity="sha384-GHo7DVRmCTRSFRzLMbZ4YtNhX4mJRqtGSZ6+j5RqbzW8i3KO/pFqGmNE7qJBg1t"
        defer></script>
```

バージョンは `3.14.3` 固定（`@latest` 禁止）。使い方:

```html
<div x-data="{ count: 0 }">
  <button x-on:click="count++">+</button>
  <span x-text="count"></span>
</div>
```

---

## 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" "アプリの説明"
```

**このコマンドで自動完了するもの:**

| ステップ | 内容 |
|---------|------|
| 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） |
| 7.5 | **カスタムドメイン設定**（`vercel domains add` + `vercel alias set`） |
| 8 | `projects.json` にカード追加 |
| 8 | `timeline/page.tsx` に launch エントリ追加 |
| 8 | `roadmap.json` に追加 |
| 8 | dashboard / roadmap をデプロイ |

> **重要**: `vercel domains add` だけでは本番 URL に割り当たらない。必ず続けて `vercel alias set <deployment-url> <subdomain>.posimai.soar-enrich.com` を実行すること（2026-04-18 実証済み）。`create-app.sh` はこれを自動実行する。

---

## 4. 手動で追加が必要なもの（判断が必要なため自動化不可）

### 4-A. apps/page.tsx の projectIds に追加

`posimai-dashboard/src/app/apps/page.tsx` の `APP_CATEGORIES` から適切なカテゴリを選んで `projectIds` に追加する。

カテゴリ一覧: `input` / `routine` / `create` / `tools` / `business` / `infra` / `ideas`

### 4-B. ecosystem/page.tsx のノード/エッジに追加

`posimai-dashboard/src/app/ecosystem/page.tsx` の `NODES` と `EDGES` に追加する。
接続関係（VPS API を使うか・他アプリからデータを受け取るか）を判断して記述する。

### 4-C. logo.png の配置とデプロイ

Gemini で生成した logo.png をアプリディレクトリに配置後:

```bash
cd posimai-[app-name]
git add logo.png
git commit -m "feat: logo 追加"
npm run deploy
```

### 4-D. Dashboard をデプロイ（4-A / 4-B 完了後）

```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
```

---

## 5. アプリ固有の実装ガイドライン

### CSS の書き方

```html
<style>
    /* posimai-ui のトークンを使う — 直接カラーコードを書かない */
    .my-card {
        background: var(--surface);
        border: 1px solid var(--border);
        border-radius: var(--radius);
        color: var(--text);
    }

    /* アクセントを使う場合 */
    .my-btn {
        background: var(--accent);
        color: #0D0D0D;  /* アクセント上のテキストのみ直書き可 */
    }
</style>
```

**禁止:**
- `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 の <html data-app-id="posimai-[app-name]"> が正しいか
[ ] 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` | 今何をしている最中か（毎セッション参照・更新） |