ドキュメント作成

docs/30_マスタードキュメント_Alexa_TTS_API編.md

@@ -1,8 +1,10 @@
 # マスタードキュメント - Alexa TTS API 編
 
 > **最終更新**: 2026-03-04
-> **対象システム**: windmill.keinafarm.net（ワークスペース: admins）
+> **対象システム**: windmill.keinafarm.net（ワークスペース: admins）
-> **目的**: このドキュメントだけで Alexa TTS API の全容を把握し、作業を継続できること
+> **目的**: このドキュメントだけで Alexa TTS API の全容を把握し、作業を継続できること
+
+> **関連ドキュメント**: `docs/31_Alexa_Cookie更新GUI運用.md`
 
 ---
 

docs/31_Alexa_Cookie更新GUI運用.md

@@ -0,0 +1,211 @@
+# Alexa Cookie更新 GUI 運用ドキュメント
+
+> 最終更新: 2026-04-04
+> 対象: `/home/akira/develop/windmill_workflow/alexa-api`
+> 目的: Alexa Cookie の更新を、ローカル GUI と権限制限付きのサーバー反映で安全に運用する
+
+---
+
+## 1. 何を作ったか
+
+Alexa Cookie の更新作業を、手作業のコマンド列ではなく GUI 中心で進められるようにした。
+
+今回追加・変更したもの:
+
+| ファイル | 役割 |
+|---------|------|
+| `alexa-api/auth4-core.js` | Amazon 認証と Cookie 取得の共通ロジック |
+| `alexa-api/auth4.js` | CLI 版の Cookie 更新ツール。`auth4-core.js` を利用 |
+| `alexa-api/auth4-web.js` | ローカルで起動する GUI。Cookie 更新とサーバー反映を行う |
+| `alexa-api/alexa-cookie-deploy.sh` | サーバー側の専用反映スクリプト。`/tmp/alexa-api.env` を本番 `.env` に反映し、`docker compose restart` を実行 |
+| `alexa-api/alexa-cookie-deploy.sudoers` | `akira` から専用反映スクリプトだけを `sudo` 実行できるようにする sudoers 設定例 |
+| `flows/hourly_chime.flow.json` | LINE 通知文面を GUI 手順に合わせて更新 |
+
+この構成にした理由:
+
+- `akira` に広い `sudo` 権限や `windmill` への自由な切り替え権限を与えたくない
+- それでも Cookie 更新だけは迷わず再実行できるようにしたい
+- そのため「GUI から呼べる専用コマンドだけを sudoers で許可する」構成にした
+
+---
+
+## 2. 全体の流れ
+
+通常運用の流れは以下の通り。
+
+1. ローカルで GUI を起動する
+2. ブラウザで Amazon のメールアドレスとパスワードを入力する
+3. `alexa-api/.env` の `ALEXA_COOKIE` を更新する
+4. GUI からサーバーへ `/tmp/alexa-api.env` を転送する
+5. GUI から `sudo /usr/local/bin/alexa-cookie-deploy.sh /tmp/alexa-api.env` を実行する
+6. サーバー側で `.env` 反映と `alexa_api` コンテナ再起動が行われる
+
+---
+
+## 3. 初回セットアップ
+
+このセットアップはサーバーで一度だけ必要。
+
+### 3-1. 専用スクリプトを配置
+
+```bash
+scp /home/akira/develop/windmill_workflow/alexa-api/alexa-cookie-deploy.sh keinafarm:/tmp/alexa-cookie-deploy.sh
+ssh keinafarm 'sudo install -m 755 /tmp/alexa-cookie-deploy.sh /usr/local/bin/alexa-cookie-deploy.sh'
+```
+
+### 3-2. sudoers を配置
+
+```bash
+scp /home/akira/develop/windmill_workflow/alexa-api/alexa-cookie-deploy.sudoers keinafarm:/tmp/alexa-cookie-deploy.sudoers
+ssh keinafarm 'sudo install -m 440 /tmp/alexa-cookie-deploy.sudoers /etc/sudoers.d/alexa-cookie-deploy'
+```
+
+### 3-3. 何が許可されるか
+
+`alexa-cookie-deploy.sudoers` の内容:
+
+```sudoers
+akira ALL=(root) NOPASSWD: /usr/local/bin/alexa-cookie-deploy.sh /tmp/alexa-api.env
+```
+
+許可しているのはこれだけ:
+
+- `akira` が root として `/usr/local/bin/alexa-cookie-deploy.sh /tmp/alexa-api.env` を実行すること
+
+許可していないもの:
+
+- `windmill` への自由な `su`
+- 任意コマンドの `sudo`
+- 任意パスへのコピーや任意の Docker 操作
+
+---
+
+## 4. ふだんの使い方
+
+### 4-1. GUI を起動
+
+```bash
+cd /home/akira/develop/windmill_workflow/alexa-api
+npm run auth:web
+```
+
+ブラウザで次を開く:
+
+```text
+http://127.0.0.1:3678
+```
+
+### 4-2. Cookie を更新
+
+画面上部の「Alexa Cookie 更新」で次を入力する。
+
+- Amazon メールアドレス
+- Amazon パスワード
+
+「Cookie を更新する」を押すと、成功時は `alexa-api/.env` が更新される。
+
+### 4-3. サーバーへ反映
+
+画面下部の「サーバー反映」で次を確認する。
+
+- SSH 接続先: `keinafarm`
+- リモート一時アップロード先: `/tmp/alexa-api.env`
+- 実行する専用コマンド: `sudo /usr/local/bin/alexa-cookie-deploy.sh /tmp/alexa-api.env`
+
+「サーバーへ反映する」を押すと、内部では次を実行する。
+
+```bash
+scp /home/akira/develop/windmill_workflow/alexa-api/.env keinafarm:/tmp/alexa-api.env
+ssh keinafarm 'sudo /usr/local/bin/alexa-cookie-deploy.sh /tmp/alexa-api.env'
+```
+
+成功時はログに以下のように表示される。
+
+```text
+alexa cookie deployed
+Container alexa_api  Restarting
+Container alexa_api  Started
+反映完了
+```
+
+---
+
+## 5. 各ファイルの使い分け
+
+### `auth4-web.js`
+
+通常はこちらを使う。人が毎回コマンドを思い出さなくてよい。
+
+### `auth4.js`
+
+CLI で直接更新したい時のために残してある。基本運用は GUI を推奨。
+
+例:
+
+```bash
+cd /home/akira/develop/windmill_workflow/alexa-api
+AMAZON_EMAIL="xxx" AMAZON_PASSWORD="xxx" node auth4.js
+```
+
+### `auth4-core.js`
+
+直接実行するものではない。CLI 版と GUI 版の共通認証ロジック。
+
+### `alexa-cookie-deploy.sh`
+
+サーバー側で root として動く専用スクリプト。役割は次の3つ。
+
+1. `/tmp/alexa-api.env` に `ALEXA_COOKIE=` があるか確認
+2. `/home/claude/alexa-api/.env` を更新
+3. `docker compose --env-file /home/claude/alexa-api/.env -f /home/claude/alexa-api/docker-compose.yml restart` を実行
+
+---
+
+## 6. LINE 通知との関係
+
+`flows/hourly_chime.flow.json` の失敗時通知は、この GUI 運用に合わせて更新済み。
+
+通知では次の導線を案内する。
+
+1. `npm run auth:web`
+2. `http://127.0.0.1:3678` を開く
+3. GUI 上でサーバー反映まで実行する
+
+これにより「あとでどう直すのか分からない」状態になりにくくしている。
+
+---
+
+## 7. トラブルシュート
+
+### `Could not resolve hostname ...`
+
+SSH 接続先の別名が `~/.ssh/config` に存在しない。
+
+今回の環境では使える別名は `keinafarm`。
+
+### `Permission denied` で `/home/claude/alexa-api/.env` に書けない
+
+`scp` で直接 `/home/claude/alexa-api/.env` へ置こうとすると起きる。  
+現在は `/tmp/alexa-api.env` に送ってから、専用スクリプトで反映する設計に変更済み。
+
+### `stat /home/claude/alexa-api/.env: permission denied`
+
+旧版の専用スクリプトで、権限不足のユーザーに切り替えて `docker compose` を実行していた時の症状。  
+現在の `alexa-cookie-deploy.sh` は root のまま `.env` 反映と再起動を完了する。
+
+### CAPTCHA や MFA が出る
+
+Amazon 側で追加認証が必要。GUI のログに失敗理由が出る。  
+この場合は一発で通らない可能性がある。
+
+---
+
+## 8. 関連ファイル
+
+- `docs/30_マスタードキュメント_Alexa_TTS_API編.md`
+- `alexa-api/auth4-web.js`
+- `alexa-api/auth4.js`
+- `alexa-api/auth4-core.js`
+- `alexa-api/alexa-cookie-deploy.sh`
+- `alexa-api/alexa-cookie-deploy.sudoers`
+- `flows/hourly_chime.flow.json`