Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 8 additions & 24 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,15 @@ CHIRIMEN デバイス一覧を検索・確認するためのダッシュボー
## ダッシュボード

- 公開 URL: https://chirimen-device-dashboard.web.app/
- 公開データ: [`apps/web/public/devices.json`](apps/web/public/devices.json)
- データソース: [`chirimen-certified-devices/generated/devices.json`](https://github.com/gurezo/chirimen-certified-devices/blob/main/generated/devices.json)

Dashboard は実行時に Certified Devices JSON を取得して表示します。デバイスデータの生成はこのリポジトリの責務ではありません。

## デバイス情報を更新したい方へ

`partslist.csv` や各 example repository の変更をダッシュボードへ反映したい場合は、GitHub issue の `🔄 デバイス情報反映依頼` テンプレートを使って依頼してください。
デバイス情報の追加・修正は [`chirimen-certified-devices`](https://github.com/gurezo/chirimen-certified-devices) で行ってください。Dashboard 側では同期・生成しません。

更新依頼から CI、更新 PR、Firebase Hosting への deploy、ブラウザでの確認までの流れは [デバイス情報の更新フロー](docs/device-data-refresh.md) を参照してください。
報告先の区別と反映確認は [デバイス情報の更新](docs/device-data-refresh.md) を参照してください。

## Quick Start

Expand All @@ -31,32 +33,14 @@ pnpm lint
pnpm nx graph
```

デバイスデータをローカルで再生成する場合は次のコマンドを使います。

```bash
pnpm sync:example-upstreams
pnpm generate:platform-examples
pnpm validate:platform-examples
pnpm generate:devices
```

## ドキュメント

| ドキュメント | 内容 |
| --- | --- |
| [デバイス情報の更新フロー](docs/device-data-refresh.md) | 反映依頼 issue、CI、更新 PR、deploy、キャッシュ確認 |
| [開発環境とコマンド](docs/development.md) | セットアップ、build / test / lint、データ生成コマンド |
| [アーキテクチャ](docs/architecture.md) | Nx workspace 構造、project 一覧、依存関係、レイヤー構成 |
| [デバイス情報の更新](docs/device-data-refresh.md) | データソース、修正先、報告先の区別、反映確認 |
| [開発環境とコマンド](docs/development.md) | セットアップ、build / test / lint |
| [アーキテクチャ](docs/architecture.md) | Nx workspace 構造、project 一覧、依存関係、データフロー |
| [AI エージェント向け設定](docs/ai-agent-setup.md) | Cursor Skills / Rules、Nx AI Agents、Conventional Commits |
| [Platform 別 Example 元データ](data/platform-examples/README.md) | `platform-examples.json` の編集方法、スキーマ、validation |
| [Upstream Example Sources](data/example-upstreams/README.md) | upstream repository 定義と device id override |

## ツール別 README

- [sync-devices](tools/scripts/sync-devices/README.md)
- [sync-example-upstreams](tools/scripts/sync-example-upstreams/README.md)
- [generate-platform-examples](tools/scripts/generate-platform-examples/README.md)
- [validate-platform-examples](tools/scripts/validate-platform-examples/README.md)

## Learn More

Expand Down
37 changes: 19 additions & 18 deletions docs/architecture.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# アーキテクチャ

CHIRIMEN デバイスダッシュボードは Nx モノレポで構成されています。Angular SPA の `web` を入口に、デバイス情報の取得、状態管理、一覧・詳細 UI、データ生成ツールをプロジェクト単位で分離しています。
CHIRIMEN デバイスダッシュボードは Nx モノレポで構成されています。Angular SPA の `web` を入口に、Certified Devices JSON の取得、Dashboard Model への変換、状態管理、一覧・詳細 UI をプロジェクト単位で分離しています。デバイスデータの生成はこのリポジトリの責務ではありません。

## ディレクトリ構造

Expand All @@ -25,16 +25,8 @@ flowchart TB
end
end

subgraph toolsGroup["tools/scripts"]
syncDevices["sync-devices"]
syncExampleUpstreams["sync-example-upstreams"]
generatePlatformExamples["generate-platform-examples"]
validatePlatformExamples["validate-platform-examples"]
end

root --> appsGroup
root --> libsGroup
root --> toolsGroup
```

## プロジェクト依存関係グラフ
Expand Down Expand Up @@ -120,6 +112,19 @@ flowchart TB
platformExamples --> sharedTypes
```

## データフロー

Dashboard は実行時に `chirimen-certified-devices/generated/devices.json` を取得し、adapter で Dashboard Model に変換してから UI へ渡します。

```mermaid
flowchart LR
certifiedJson["chirimen-certified-devices generated/devices.json"] --> dataAccess["libs-data-access fetch"]
dataAccess --> adapter["adapter"]
adapter --> model["shared-types DeviceInfo"]
model --> stateLib["libs-state"]
stateLib --> ui["Angular UI"]
```

## プロジェクト一覧

| プロジェクト | パス | 種別 | 説明 |
Expand All @@ -128,20 +133,16 @@ flowchart TB
| `web` | `apps/web` | Application | Angular フロントエンド |
| `web-e2e` | `apps/web-e2e` | Application | Playwright による E2E テスト |
| `shared-types` | `libs/shared-types` | Library | `DeviceInfo` / `ProductInfo` 等の共有型 |
| `libs-data-access` | `libs/devices/data-access` | Library | デバイスリポジトリ・データアクセス |
| `libs-data-access` | `libs/devices/data-access` | Library | Certified Devices JSON の取得と adapter |
| `libs-state` | `libs/devices/state` | Library | `DeviceListStore` 等の状態管理 |
| `libs-feature-list` | `libs/devices/feature-list` | Library | デバイス一覧 UI コンポーネント |
| `libs-card-list` | `libs/devices/card-list` | Library | デバイスカード一覧 UI |
| `libs-device-detail` | `libs/devices/device-detail` | Library | デバイス詳細 UI |
| `libs-platform-specific-examples` | `libs/devices/platform-specific-examples` | Library | Platform 別 Example UI |
| `sync-devices` | `tools/scripts/sync-devices` | Application | `partslist.csv` と正本データから `devices.json` を生成 |
| `sync-example-upstreams` | `tools/scripts/sync-example-upstreams` | Application | upstream example repository を同期し、候補とレポートを生成 |
| `generate-platform-examples` | `tools/scripts/generate-platform-examples` | Application | upstream 同期結果から Platform 別 Example 候補 JSON を生成 |
| `validate-platform-examples` | `tools/scripts/validate-platform-examples` | Application | Platform 別 Example と `devices.json` の整合性を検証 |

## 主なデータ境界

- `apps/web/public/devices.json` はフロントエンドが読み込む公開データです。
- `data/platform-examples/platform-examples.json` は Platform 別 Example の正本データです。
- `generated/reports/**` は同期・生成・検証で出力されるレビュー用レポートです。
- `generated/upstreams/**` は upstream repository の mirror で、リポジトリにはコミットしません。
- 外部 JSON (`chirimen-certified-devices/generated/devices.json`) の入力型は `libs-data-access` 内部のみが扱う。UI / state は参照しない。
- adapter は外部 JSON を `DeviceInfo` などの Dashboard Model に変換する。
- `shared-types` の Dashboard Model は state と UI が共有する表示用の型である。
- デバイスデータの正本と生成は [`chirimen-certified-devices`](https://github.com/gurezo/chirimen-certified-devices) の責務である。
15 changes: 5 additions & 10 deletions docs/development.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,12 @@
## 前提

- Node.js 24
- pnpm 11.8.0
- pnpm 11.24.0

`package.json` の `packageManager` は次の値です。

```text
pnpm@11.8.0
pnpm@11.24.0
```

## セットアップ
Expand Down Expand Up @@ -42,16 +42,11 @@ pnpm nx test libs-state
pnpm nx affected -t lint,build,test
```

## デバイスデータ関連コマンド
## デバイスデータ

| 目的 | コマンド |
| --- | --- |
| upstream example repository を同期 | `pnpm sync:example-upstreams` |
| Platform 別 Example 候補を生成 | `pnpm generate:platform-examples` |
| Platform 別 Example を検証 | `pnpm validate:platform-examples` |
| `devices.json` を生成 | `pnpm generate:devices` |
デバイスデータは [`chirimen-certified-devices/generated/devices.json`](https://github.com/gurezo/chirimen-certified-devices/blob/main/generated/devices.json) から実行時に取得します。このリポジトリで同期・生成するコマンドはありません。

デバイス情報の更新フロー全体は [デバイス情報の更新フロー](device-data-refresh.md) を参照してください。
データソースと修正先は [デバイス情報の更新](device-data-refresh.md) を参照してください。

## テスト

Expand Down
122 changes: 25 additions & 97 deletions docs/device-data-refresh.md
Original file line number Diff line number Diff line change
@@ -1,119 +1,47 @@
# デバイス情報の更新フロー
# デバイス情報の更新

CHIRIMEN デバイスダッシュボードの表示内容は、公開データ `apps/web/public/devices.json` をもとにしています。このファイルは `partslist.csv` と Platform 別 Example の正本データから生成され、Firebase Hosting へデプロイされます。
CHIRIMEN デバイスダッシュボードの表示内容は、実行時に取得する [`chirimen-certified-devices/generated/devices.json`](https://github.com/gurezo/chirimen-certified-devices/blob/main/generated/devices.json) をもとにしています。デバイスデータの正本と生成は [`chirimen-certified-devices`](https://github.com/gurezo/chirimen-certified-devices) の責務です。Dashboard 側では同期・生成しません。

## コミュニティメンバー向けの依頼手順
## コミュニティメンバー向けの手順

`partslist.csv` や各 example repository の変更をダッシュボードへ反映したい場合は、次の手順で依頼します。
デバイス情報の追加・修正は次の手順で行います。

1. `partslist.csv` または各 example repository に変更を commit / merge する
2. CHIRIMEN デバイスダッシュボードで `🔄 デバイス情報反映依頼` テンプレートを使って issue を作成する
3. CI / workflow の終了を待つ
4. issue に実行結果がコメントされる
5. 差分がない場合は issue が閉じる
6. 差分がある場合は更新 PR が作成される
7. 更新 PR が `main` に merge される
8. Firebase Hosting への deploy が成功すると、issue に反映先がコメントされて閉じる
9. CHIRIMEN デバイスダッシュボードに反映される
1. [`chirimen-certified-devices`](https://github.com/gurezo/chirimen-certified-devices) でデバイスデータを追加・修正する
2. そのリポジトリの手順に従って `generated/devices.json` を更新する
3. `main` に反映された JSON を Dashboard が実行時に取得する

反映後の確認では、ハードリロードまたは別ブラウザでダッシュボードにアクセスしてください。
Dashboard リポジトリに反映依頼 issue を立てる必要はありません。

## 更新フロー
## 報告先の区別

```mermaid
flowchart TD
upstreamChange["partslist.csv または example 更新"] --> refreshIssue["デバイス情報反映依頼 issue 作成"]
refreshIssue --> refreshWorkflow["refresh-devices workflow 実行"]
refreshWorkflow --> syncExamples["upstream example 同期"]
syncExamples --> generateExamples["Platform 別 Example 候補生成"]
generateExamples --> validateExamples["Platform 別 Example 検証"]
validateExamples --> generateDevices["devices.json 生成"]
generateDevices --> hasDiff{"main との差分あり"}
hasDiff -->|"いいえ"| noChangeComment["差分なしをコメント"]
noChangeComment --> closeNoChange["issue close"]
hasDiff -->|"はい"| createPr["更新 PR 作成"]
createPr --> mergeMain["PR を main に merge"]
mergeMain --> deployHosting["Firebase Hosting deploy"]
deployHosting --> deployedComment["反映先をコメント"]
deployedComment --> closeIssue["issue close"]
```

## 関連する GitHub Actions

| Workflow | ファイル | 役割 |
| --- | --- | --- |
| Refresh devices data | [`.github/workflows/refresh-devices.yml`](../.github/workflows/refresh-devices.yml) | `refresh-devices` ラベル付き issue または手動実行から、同期・生成・検証・PR 作成を行う |
| Sync example upstreams | [`.github/workflows/sync-example-upstreams.yml`](../.github/workflows/sync-example-upstreams.yml) | 毎週または手動で upstream を同期し、差分があれば自動 PR を作成する |
| Sync devices | [`.github/workflows/sync-devices.yml`](../.github/workflows/sync-devices.yml) | `partslist.csv` から `devices.json` を更新し、差分があれば自動 PR を作成する |
| Deploy to Firebase Hosting | [`.github/workflows/deploy.yml`](../.github/workflows/deploy.yml) | `main` への push 後に build / deploy し、対象の反映依頼 issue を close する |
| Generate devices.json | [`.github/workflows/generate-devices.yml`](../.github/workflows/generate-devices.yml) | PR / `main` で `devices.json` の生成ドリフトを検出する |
| Generate platform examples | [`.github/workflows/generate-platform-examples.yml`](../.github/workflows/generate-platform-examples.yml) | Platform 別 Example 候補 JSON の生成ドリフトを検出する |
| Validate platform examples | [`.github/workflows/validate-platform-examples.yml`](../.github/workflows/validate-platform-examples.yml) | 正本データと `devices.json` の整合性を検証する |

### 自動 PR 作成に必要な権限

`refresh-devices` / `sync-example-upstreams` / `sync-devices` は `peter-evans/create-pull-request` で更新 PR を作成します。次の 2 点が揃っていないと、`GitHub Actions is not permitted to create or approve pull requests` で失敗します。

1. 各 workflow の `permissions` に `contents: write` と `pull-requests: write` があること
2. リポジトリ設定 **Settings → Actions → General → Workflow permissions** で **Allow GitHub Actions to create and approve pull requests** が有効であること

`GITHUB_TOKEN` では PR 作成できない場合、または自動 PR 上で他の workflow を動かしたい場合は、`repo` スコープを持つ Personal Access Token をリポジトリシークレット `PAT_TOKEN` として登録します。未設定時は `GITHUB_TOKEN` にフォールバックします。

`sync-example-upstreams` / `sync-devices` は作成した PR に auto-merge を有効化します。必須チェックがなく PR がすでに `CLEAN` のとき、または対象ブランチに保護ルールがないときは GitHub が auto-merge を拒否するため、その場合は squash merge にフォールバックします。
| 内容 | 報告先 |
| --- | --- |
| デバイス名・製品リンク・Example などデータの追加・修正・不備 | [`chirimen-certified-devices`](https://github.com/gurezo/chirimen-certified-devices) |
| 一覧・検索・詳細など Dashboard UI の不具合 | 本リポジトリの [バグ報告](https://github.com/gurezo/chirimen-device-dashboard/issues/new?template=bug_report.ja.yml) |

## `refresh-devices` issue で実行される処理
GitHub の Issue 作成画面にも、デバイス情報の追加・修正向けの案内があります。

`🔄 デバイス情報反映依頼` テンプレートで issue を作成すると、`refresh-devices` ラベルが付きます。このラベルをきっかけに `.github/workflows/refresh-devices.yml` が起動します。

workflow は次の順にコマンドを実行します。

```bash
pnpm sync:example-upstreams
pnpm generate:platform-examples
pnpm validate:platform-examples
pnpm generate:devices
```

差分がある場合、workflow は次のファイルを含む更新 PR を作成します。

- `apps/web/public/devices.json`
- `data/platform-examples/**`
- `generated/reports/**`

差分がない場合、PR は作成されず、issue に「差分なし」がコメントされて close されます。

## データ生成の入力と出力
## データフロー

```mermaid
flowchart LR
partslist["partslist.csv"] --> syncDevices["sync-devices"]
platformSource["data/platform-examples/platform-examples.json"] --> syncDevices
upstreamSources["upstream example repositories"] --> syncUpstreams["sync-example-upstreams"]
syncUpstreams --> generatedReports["generated/reports"]
syncUpstreams --> generatePlatformExamples["generate-platform-examples"]
generatePlatformExamples --> generatedExamples["platform-examples.generated.json"]
platformSource --> validatePlatformExamples["validate-platform-examples"]
syncDevices --> devicesJson["apps/web/public/devices.json"]
devicesJson --> dashboard["CHIRIMEN デバイスダッシュボード"]
certifiedRepo["chirimen-certified-devices"] --> devicesJson["generated/devices.json"]
devicesJson --> dataAccess["libs-data-access"]
dataAccess --> adapter["adapter"]
adapter --> dashboard["CHIRIMEN デバイスダッシュボード"]
```

`platform-examples.generated.json` は review 用の候補 JSON です。正本 `data/platform-examples/platform-examples.json` は自動では上書きされないため、必要な差分はレビュー後に手動で反映します。
## 反映確認

## 反映確認とキャッシュ
ダッシュボードは起動時に Certified Devices JSON を取得して表示します。アプリ内では取得結果が再利用されるため、同じブラウザタブを開いたままだと最新データを再取得しない場合があります。

ダッシュボードは起動時に `/devices.json` を取得して表示します。アプリ内では取得結果が再利用されるため、同じブラウザタブを開いたままだと最新の `devices.json` を再取得しない場合があります。

デプロイ後に反映を確認する場合は、次のどちらかを試してください。
GitHub raw 経由の取得のため、ブラウザや CDN が古い内容を使う可能性もあります。反映を確認する場合は、次のいずれかを試してください。

- ハードリロードする
- 別ブラウザまたはシークレットウィンドウでアクセスする

`/devices.json` は `cache-control: max-age=3600` で配信されます。そのため、ブラウザや CDN が最大 1 時間古い内容を使う可能性があります。すぐに更新内容が見えない場合は、時間を置いてから再確認してください。
- 時間を置いてから再確認する

## 関連ドキュメント

- [Platform 別 Example 元データ](../data/platform-examples/README.md)
- [sync-devices](../tools/scripts/sync-devices/README.md)
- [sync-example-upstreams](../tools/scripts/sync-example-upstreams/README.md)
- [generate-platform-examples](../tools/scripts/generate-platform-examples/README.md)
- [validate-platform-examples](../tools/scripts/validate-platform-examples/README.md)
- [アーキテクチャ](architecture.md)
- [chirimen-certified-devices](https://github.com/gurezo/chirimen-certified-devices)
Loading