256 lines
9.1 KiB
Markdown
256 lines
9.1 KiB
Markdown
# 新アプリ作成ガイド
|
||
|
||
**最終更新: 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` | 今何をしている最中か（毎セッション参照・更新） |
|