# Commerce Link Builder

Amazon / 楽天市場 / Yahoo!ショッピングの商品検索・商品リンク生成・記事埋め込みを提供する WordPress プラグイン。

## なぜこのプラグインか (motivation)

**Amazon Product Advertising API 5.0 (PA-API 5.0) は 2026-05-15 に Amazon が deprecated にする** ことが公式に告知されています ([Amazon 公式ドキュメント](https://webservices.amazon.com/paapi5/documentation/) 冒頭の deprecation notice を参照)。

Commerce Link Builder は、PA-API 5.0 の後継である **Amazon Creators API** ベースで Amazon Associates 利用者向けの商品リンクプラグインを提供することを核心動機としています。既存の WordPress エコシステムには PA-API 5.0 ベースのアフィリエイトプラグインが多数存在しますが、Creators API ベースの選択肢はまだ少なく、deprecation 後も継続して動作する選択肢を提供することに価値があります。

判断記録: [`architecture-decision-records/0022-adopt-creators-api-and-deprecate-paapi.md`](./architecture-decision-records/0022-adopt-creators-api-and-deprecate-paapi.md)

> **Amazon Creators API の利用にあたっての注意**: Creators API は Amazon Associates Central 上で credentials を発行する際に **過去 30 日間で 10 件以上の qualifying sales** が必要な資格要件があります。新規 Associate 登録から API 利用までに時間がかかる場合があります。詳細は [Amazon Creators API ドキュメント](https://affiliate-program.amazon.com/creatorsapi/docs/en-us/onboarding/register-for-creators-api) を参照してください。


- スラッグ: `commerce-link-builder`
- 略称: `CLB`
- PHP 最低要件: 8.1
- サポート対象: WordPress 最新 + one-back（WooCommerce の有無に依存しない。WooCommerce 共存時も動作するようテスト済み）
- ライセンス: GPL-2.0-or-later

## ドキュメント

- 設計仕様: [`specifications/`](./specifications/)
- ADR: [`architecture-decision-records/`](./architecture-decision-records/)
- 実装ロードマップ: [`specifications/implementation-roadmap.md`](./specifications/implementation-roadmap.md)
- フェーズゲート検証: [`specifications/phase-gate-verification-matrix.md`](./specifications/phase-gate-verification-matrix.md)

## 開発環境

本プラグインは [Docker Desktop](https://www.docker.com/products/docker-desktop/) + [`@wordpress/env`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/) で開発する。

### 前提

- macOS / Linux / Windows (WSL2)
- Docker Desktop が起動済み
- Node.js 20 以上 / npm 10 以上
- PHP 8.1 以上（ホスト側の lint / static analysis 用）
- Composer 2.x

### 初回セットアップ

```sh
# 依存インストール
npm install
composer install

# WordPress 環境を起動（Docker コンテナが立ち上がる）
npm run env:start
```

起動すると以下で WordPress にアクセスできる。

- 開発サイト: http://localhost:8888
- テストサイト: http://localhost:8889
- 管理画面ログイン: `admin` / `password`

### よく使うコマンド

| コマンド | 用途 |
| --- | --- |
| `npm run env:start` | WordPress 環境を起動 |
| `npm run env:stop` | 環境を停止 |
| `npm run env:clean` | データをリセット |
| `npm run env:destroy` | コンテナを完全破棄 |
| `npm run build` | ブロックをビルド |
| `npm run start` | ブロックをウォッチビルド |
| `composer test` | PHPUnit 実行 |
| `composer lint` | PHPCS（WordPress Coding Standards） |
| `composer analyze` | PHPStan |

### コンテナ内でのコマンド実行

```sh
# WP-CLI
npx wp-env run cli wp plugin list

# PHPUnit（テスト環境コンテナ内）
npx wp-env run tests-cli --env-cwd=wp-content/plugins/commerce-link-builder composer test
```

## ディレクトリ構成

```
commerce-link-builder/
├─ commerce-link-builder.php   # プラグインエントリ（Phase 1 で追加）
├─ uninstall.php               # アンインストール処理（Phase 1 で追加）
├─ composer.json
├─ package.json
├─ .wp-env.json                # 開発環境定義
├─ src/                        # PSR-4: CommerceLinkBuilder\
│  ├─ Admin/
│  ├─ Application/
│  ├─ Bootstrap/
│  ├─ Domain/
│  ├─ Infrastructure/
│  ├─ Presentation/
│  └─ Support/
├─ blocks/                     # Gutenberg ブロックソース
├─ templates/                  # テンプレート（frontend / admin / emails）
├─ assets/                     # CSS / JS / img
├─ config/                     # 設定ファイル
├─ languages/                  # 翻訳
├─ tests/                      # PSR-4: CommerceLinkBuilder\Tests\
│  ├─ Unit/
│  ├─ Integration/
│  ├─ Contract/
│  ├─ E2E/
│  └─ Fixtures/
└─ bin/                        # 開発用スクリプト
```

## 配布物の作り方 (ZIP ビルド)

リポジトルートで `bin/build.sh` を実行すると、`dist/commerce-link-builder-<version>.zip` を生成します。バージョンは `commerce-link-builder.php` の `Version:` ヘッダーから抽出されます。

```sh
bin/build.sh
```

出力先を変えたい場合:

```sh
bin/build.sh /tmp/clb-release
```

ビルド手順:

1. `commerce-link-builder.php` からバージョンを抽出。
2. `commerce-link-builder/` を top-level ディレクトリとして一時ディレクトリにステージング。
3. ステージング側で `composer install --no-dev --optimize-autoloader` を実行 (本番 `vendor/` に PHPUnit / PHPStan / phpcs 等の dev tooling が含まれないように)。
4. `.distignore` を `rsync --exclude-from` で適用し、`tests/` / `specifications/` / `architecture-decision-records/` / `.github/` / `node_modules/` / `playwright.config.js` / `RELEASE-NOTES.md` 等 repo-only パスを ZIP から除外。
5. `zip -rq` で圧縮。

出力 ZIP を WordPress の [プラグイン > 新規追加 > プラグインのアップロード] でアップロードし、有効化すると `wp-content/plugins/commerce-link-builder/` としてインストールされます。

要件: `composer` / `rsync` / `zip` / `unzip` が PATH 上に存在すること。macOS / Linux どちらでも動作します (BSD / GNU 両方の sed / stat を fallback でサポート)。

## コントリビューション

- コーディング規約: [`specifications/coding-standards.md`](./specifications/coding-standards.md)
- コントリビュートガイド: [`contribution-guide.md`](./contribution-guide.md)
- i18n / 翻訳: 新規文字列を追加したら `npm run i18n:make-pot` を実行して `languages/commerce-link-builder.pot` を再生成してコミットしてください (CI の `i18n` job が drift をチェック)。日本語訳は `languages/commerce-link-builder-ja.po` を手で更新し、`npm run i18n:make-mo` で .mo を再生成します。

## ライセンス

GPL-2.0-or-later