docs: new-app-guide.md を現行状態に全面更新
- create-app.sh の Step 8（ダッシュボード自動更新）を反映 - テンプレートを _template-minimal 一本化に変更 - Alpine.js をパターンBとして追加（ビルド不要・reactive state） - SW キャッシュ更新タイミングの方針を明記 - 実装チェックリストを追加 - 旧手動ステップ（自動化済み）を削除・整理 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
parent
5538cde753
commit
1d9c2b5f3d
|
|
@ -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
|
||||
<!-- </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" "アプリの説明"
|
||||
```
|
||||
|
||||
## 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
|
||||
<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` | 今何をしている最中か（毎セッション参照・更新） |
|
||||
|
|
|
|||
Loading…
Reference in New Issue