b24014/Q-A_test
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit
CI / typecheck (push) Successful in 1m8s
Details
CI / format (push) Failing after 1m6s
Details
CI / lint (push) Failing after 49s
Details
CI / test (push) Failing after 1m8s
Details

Browse Source
This commit is contained in:
SDI
2026-07-15 18:05:12 +09:00
commit 12e4f17b62
4633 changed files with 817125 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/docs/i18n/ja/docusaurus-plugin-content-docs/current/02-developer-guide/01-installation/01-docker-hub-images.md
+374
View File
@@ -0,0 +1,374 @@
---
id: docker-hub-images
title: Docker Hubイメージインストール
description: Docker Hubに登録されたABC User Feedback公式イメージを使用してシステムを迅速にインストールする方法を説明します。
sidebar_position: 1
---
# Docker Hubイメージインストール
ABC User Feedbackは公式Dockerイメージを提供しています。
このドキュメントは、Docker Composeを使用して**Web UI、APIサーバー、データベース、SMTPサーバー**などのシステムをローカルで迅速に構成する方法を説明します。
---
## 1. 前提条件
| 項目 | 説明 |
| -------------- | ----------------------------------------------------------------------- |
| Docker | 20.10以上 |
| Docker Compose | v2以上推奨 |
| 使用ポート | `3000`、`4000`、`13306`、`5080`、`25`（ローカルで空いている必要がある） |
---
## 2. Dockerイメージ構成
| サービス名 | 説明 | Dockerイメージ名 |
| ------------------------ | ------------------------------- | ------------------------------------- |
| Web (Admin UI) | フロントエンドWeb UI（Next.js） | `line/abc-user-feedback-web` |
| API (Backend) | バックエンドサーバー（NestJS） | `line/abc-user-feedback-api` |
| MySQL | データベース | `mysql:8.0` |
| SMTP4Dev | ローカルテスト用メールサーバー | `rnwood/smtp4dev:v3` |
| （オプション）OpenSearch | 検索機能とAI分析精度向上用 | `opensearchproject/opensearch:2.16.0` |
---
## 3. `docker-compose.yml`の例
```yaml
name: abc-user-feedback
services:
web:
image: line/abc-user-feedback-web:latest
environment:
- NEXT_PUBLIC_API_BASE_URL=http://localhost:4000
ports:
- 3000:3000
depends_on:
- api
restart: unless-stopped
api:
image: line/abc-user-feedback-api:latest
environment:
- JWT_SECRET=jwtsecretjwtsecretjwtsecret
- MYSQL_PRIMARY_URL=mysql://userfeedback:userfeedback@mysql:3306/userfeedback
- SMTP_HOST=smtp4dev
- SMTP_PORT=25
- SMTP_SENDER=user@feedback.com
# OpenSearchを使用する場合は以下のコメントを解除してください
# - OPENSEARCH_USE=true
# - OPENSEARCH_NODE=http://opensearch-node:9200
ports:
- 4000:4000
depends_on:
- mysql
restart: unless-stopped
mysql:
image: mysql:8.0
command:
[
'--default-authentication-plugin=mysql_native_password',
'--collation-server=utf8mb4_bin',
]
environment:
MYSQL_ROOT_PASSWORD: userfeedback
MYSQL_DATABASE: userfeedback
MYSQL_USER: userfeedback
MYSQL_PASSWORD: userfeedback
TZ: UTC
ports:
- 13306:3306
volumes:
- mysql:/var/lib/mysql
restart: unless-stopped
smtp4dev:
image: rnwood/smtp4dev:v3
ports:
- 5080:80
- 25:25
- 143:143
volumes:
- smtp4dev:/smtp4dev
restart: unless-stopped
# OpenSearchを使用する場合は以下のコメントを解除してください
# opensearch-node:
# image: opensearchproject/opensearch:2.16.0
# restart: unless-stopped
# environment:
# - cluster.name=opensearch-cluster
# - node.name=opensearch-node
# - discovery.type=single-node
# - bootstrap.memory_lock=true
# - 'OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m'
# - plugins.security.disabled=true
# - OPENSEARCH_INITIAL_ADMIN_PASSWORD=UserFeedback123!@#
# ulimits:
# memlock:
# soft: -1
# hard: -1
# nofile:
# soft: 65536
# hard: 65536
# volumes:
# - opensearch:/usr/share/opensearch/data
# ports:
# - 9200:9200
# - 9600:9600
volumes:
mysql:
smtp4dev:
# opensearch:
```
---
## 4. 実行手順
### 4.1 Dockerイメージのダウンロードと実行
```bash
# Docker Composeですべてのサービスをバックグラウンドで実行
docker compose up -d
```
### 4.2 実行状態の確認
```bash
# すべてのコンテナが正常に実行中か確認
docker compose ps
```
### 4.3 サービスアクセスの確認
- **Webアプリケーション**: [http://localhost:3000](http://localhost:3000)
- **APIサーバー**: [http://localhost:4000](http://localhost:4000)
- **SMTPテストページ**: [http://localhost:5080](http://localhost:5080)
- **MySQLデータベース**: `localhost:13306`（ユーザー：`userfeedback`、パスワード：`userfeedback`）
---
## 5. SMTP設定
デフォルトでは、この構成では`smtp4dev`を通じてメールをテストできます。
- **Webインターフェース**: [http://localhost:5080](http://localhost:5080)
- **SMTPポート**: `25`
- **IMAPポート**: `143`
### SMTPテスト方法
1. Webアプリケーションでユーザー登録またはユーザー招待機能を使用
2. [http://localhost:5080](http://localhost:5080)で送信されたメールを確認
3. メール内容と添付ファイルなどをテスト
> **重要**: 実際の本番環境では、必ず外部SMTPサーバー（例：Gmail、SendGrid、社内SMTPなど）と連携する必要があります。
## 6. インストール確認
### 6.1 Webアプリケーションアクセス確認
ブラウザで`http://localhost:3000`にアクセスし、以下を確認してください：
- テナント作成画面が正常に表示されるか
- ページの読み込みが完了するか
- JavaScriptエラーがないか（ブラウザの開発者ツールで確認）
### 6.2 APIサーバーステータス確認
```bash
# APIサーバーヘルスチェック
curl http://localhost:4000/api/health
```
予想される応答：
```json
{
"status": "ok",
"info": {
"database": {
"status": "up"
}
}
}
```
### 6.3 データベース接続確認
```bash
# MySQLコンテナに直接アクセスしてデータベースを確認
docker compose exec mysql mysql -u userfeedback -puserfeedback -e "SHOW DATABASES;"
# テーブル作成確認
docker compose exec mysql mysql -u userfeedback -puserfeedback -e "USE userfeedback; SHOW TABLES;"
```
### 6.4 ログ確認
```bash
# すべてのサービスのログを確認
docker compose logs
# 特定のサービスのログのみ確認
docker compose logs api
docker compose logs web
docker compose logs mysql
```
---
## 7. OpenSearch使用時の注意事項
OpenSearchは、検索機能とAI分析の精度を向上させるオプションコンポーネントです。
### 7.1 OpenSearch有効化方法
1. `docker-compose.yml`ファイルで`api`サービスの環境変数のコメントを解除：
```yaml
- OPENSEARCH_USE=true
- OPENSEARCH_NODE=http://opensearch-node:9200
```
2. `opensearch-node`サービスのコメントを解除
3. `volumes:`セクションで`opensearch:`のコメントを解除
4. ポート`9200`、`9600`がローカルで使用されていないことを確認
### 7.2 メモリ要件
> **注意**: OpenSearchは最低2GB以上のメモリを必要とします。メモリ不足の場合、コンテナが自動的に終了する可能性があります。
### 7.3 OpenSearchステータス確認
```bash
# OpenSearchクラスターステータス確認
curl http://localhost:9200/_cluster/health
# OpenSearchノード情報確認
curl http://localhost:9200/_nodes
# インデックス確認
curl http://localhost:9200/_cat/indices
```
### 7.4 OpenSearch無効化
OpenSearchを使用しない場合は、`docker-compose.yml`で該当サービスと環境変数をコメントアウトします。
---
## 8. トラブルシューティング
### 8.1 ポート競合の問題
**症状**: `docker compose up`実行時にポートバインディングエラーが発生
**解決方法**:
```bash
# 使用中のポートを確認
lsof -i :3000 # Webポート
lsof -i :4000 # APIポート
lsof -i :13306 # MySQLポート
lsof -i :5080 # SMTPポート
# 該当ポートを使用しているプロセスを停止して再起動
docker compose down
docker compose up -d
```
### 8.2 コンテナ起動失敗
**症状**: 一部のコンテナが起動しない、または継続的に再起動される
**解決方法**:
```bash
# コンテナステータス確認
docker compose ps
# 失敗したコンテナのログを確認
docker compose logs [サービス名]
# すべてのコンテナを停止して削除
docker compose down
# ボリュームも削除（データ損失に注意）
docker compose down -v
# 再度起動
docker compose up -d
```
### 8.3 データベース接続エラー
**症状**: APIサーバーからMySQL接続失敗
**解決方法**:
```bash
# MySQLコンテナが完全に起動するまで待機
docker compose logs mysql
# MySQLコンテナに直接接続テスト
docker compose exec mysql mysql -u userfeedback -puserfeedback -e "SELECT 1;"
# APIサービスを再起動
docker compose restart api
```
### 8.4 イメージダウンロード失敗
**症状**: Dockerイメージをダウンロードできない
**解決方法**:
```bash
# Docker Hubログイン確認
docker login
# イメージを手動でダウンロード
docker pull line/abc-user-feedback-web:latest
docker pull line/abc-user-feedback-api:latest
# ネットワーク接続確認
ping hub.docker.com
```
### 8.5 メモリ不足の問題
**症状**: OpenSearchコンテナが自動的に終了する
**解決方法**:
```bash
# システムメモリ確認
free -h
# Dockerメモリ使用量確認
docker stats
# OpenSearchを無効化（docker-compose.ymlでコメントアウト）
# またはメモリ割り当てを増やす
```
---
## 9. 参考リンク
- [ABC User Feedback Web - Docker Hub](https://hub.docker.com/r/line/abc-user-feedback-web)
- [ABC User Feedback API - Docker Hub](https://hub.docker.com/r/line/abc-user-feedback-api)
- [smtp4dev - Docker Hub](https://hub.docker.com/r/rnwood/smtp4dev)
- [OpenSearch - Docker Hub](https://hub.docker.com/r/opensearchproject/opensearch)
---
## 関連ドキュメント
- [初期設定ガイド](/ja/user-guide/getting-started)
apps/docs/i18n/ja/docusaurus-plugin-content-docs/current/02-developer-guide/01-installation/02-cli-tool.md
+273
View File
@@ -0,0 +1,273 @@
---
sidebar_position: 2
title: "CLIツール使用方法"
description: "ABC User Feedback CLIツールでシステムを迅速かつ簡単にインストール・管理する方法を説明します。"
---
# CLIツール使用方法
ABC User Feedback CLI（`auf-cli`）は、システムのインストール、実行、管理を簡素化するコマンドラインツールです。Node.jsとDockerがインストールされていれば、追加の依存関係をインストールしたりリポジトリをクローンしたりすることなく、`npx`を通じてすぐに実行できます。
## 主要機能
- 必要なインフラの自動設定（MySQL、SMTP、OpenSearch）
- 環境変数設定の簡素化
- APIおよびウェブサーバーの自動起動/停止
- ボリュームデータのクリーンアップ
- 動的Docker Composeファイル生成
## 使用されるDockerイメージ
- `line/abc-user-feedback-web:latest` - ウェブフロントエンド
- `line/abc-user-feedback-api:latest` - APIバックエンド
- `mysql:8.0` - データベース
- `rnwood/smtp4dev:v3` - SMTPテストサーバー
- `opensearchproject/opensearch:2.16.0` - 検索エンジン（オプション）
## 前提条件
CLIツールを使用する前に、次の要件を満たす必要があります：
- [Node.js v22以上](https://nodejs.org/en/download/)
- [Docker](https://docs.docker.com/desktop/)
## 基本コマンド
### 初期化
ABC User Feedbackに必要なインフラを設定するには、次のコマンドを実行します：
```bash
npx auf-cli init
```
このコマンドは次の作業を実行します：
1. 環境変数設定用の`config.toml`ファイルを作成
2. アーキテクチャ（ARM/AMD）に応じて必要なインフラを設定
初期化が完了すると、現在のディレクトリに`config.toml`ファイルが作成されます。必要に応じてこのファイルを編集して環境変数を調整できます。
### サーバー起動
APIおよびウェブサーバーを起動するには、次のコマンドを実行します：
```bash
npx auf-cli start
```
このコマンドは次の作業を実行します：
1. `config.toml`ファイルから環境変数を読み取り
2. Docker Composeファイルを生成してサービスを開始
3. APIおよびウェブサーバーコンテナと必要なインフラ（MySQL、SMTP、OpenSearch）を起動
サーバーが正常に起動すると、ウェブブラウザで`http://localhost:3000`（または設定されたURL）からABC User Feedbackウェブインターフェースにアクセスできます。CLIは次のURLを表示します：
- ウェブインターフェースURL
- API URL
- MySQL接続文字列
- OpenSearch URL（有効な場合）
- SMTPウェブインターフェース（smtp4dev使用時）
### サーバー停止
APIおよびウェブサーバーを停止するには、次のコマンドを実行します：
```bash
npx auf-cli stop
```
このコマンドは実行中のAPIおよびウェブサーバーコンテナとインフラコンテナを停止します。ボリュームに保存されたすべてのデータは保持されます。
### ボリュームクリーンアップ
起動中に作成されたDockerボリュームをクリーンアップするには、次のコマンドを実行します：
```bash
npx auf-cli clean
```
このコマンドはすべてのコンテナを停止し、MySQL、SMTP、OpenSearchなどのDockerボリュームを削除します。
**警告**: この操作はすべてのデータを削除するため、必要な場合は事前にバックアップしてください。
`--images`オプションを使用して未使用のDockerイメージもクリーンアップできます：
```bash
npx auf-cli clean --images
```
## 設定ファイル（config.toml）
`init`コマンドを実行すると、現在のディレクトリに`config.toml`ファイルが作成されます。このファイルはABC User Feedbackの環境変数を設定するために使用されます。
以下は`config.toml`ファイルの例です：
```toml
[web]
port = 3000
# api_base_url = "http://localhost:4000"
[api]
port = 4000
jwt_secret = "jwtsecretjwtsecretjwtsecretjwtsecretjwtsecretjwtsecret"
# master_api_key = "MASTER_KEY"
# access_token_expired_time = "10m"
# refresh_token_expired_time = "1h"
# [api.auto_feedback_deletion]
# enabled = true
# period_days = 365
# [api.smtp]
# host = "smtp4dev" # SMTP_HOST
# port = 25 # SMTP_PORT
# sender = "user@feedback.com"
# username=
# password=
# tls=
# cipher_spec=
# opportunitic_tls=
# [api.opensearch]
# enabled = true
[mysql]
port = 13306
```
必要に応じてこのファイルを編集して環境変数を調整できます。環境変数の詳細については、[環境変数設定](./05-configuration.md)ドキュメントを参照してください。
## 高度な使用方法
### ポート変更
デフォルトでは、ウェブサーバーはポート3000を、APIサーバーはポート4000を使用します。これらを変更するには、`config.toml`ファイルで次の設定を変更します：
```toml
[web]
port = 8000 # ウェブサーバーポート変更
api_base_url = "http://localhost:8080" # API URLも一緒に変更する必要があります
[api]
port = 8080 # APIサーバーポート変更
[mysql]
port = 13307 # 必要に応じてMySQLポート変更
```
### OpenSearch有効化
高度な検索機能のためにOpenSearchを有効にするには：
```toml
[api.opensearch]
enabled = true
```
**注意事項**：
- OpenSearchには最低2GBの使用可能メモリが必要です
- OpenSearchコンテナは`http://localhost:9200`で利用可能です
- OpenSearchステータス確認: `http://localhost:9200/_cluster/health`
### SMTP設定
開発環境では、デフォルトの`smtp4dev`設定を推奨します：
```toml
[api.smtp]
host = "smtp4dev"
port = 25
sender = "dev@feedback.local"
```
smtp4devウェブインターフェースは`http://localhost:5080`で送信されたメールを確認できます。
## トラブルシューティング
### 一般的な問題
1. **Docker関連エラー**：
- Dockerが実行中か確認: `docker --version`
- Docker権限確認: `docker ps`
- Docker Desktopが正しくインストールされ実行中か確認
2. **ポート競合**：
- ポート使用確認: `lsof -i :PORT`（macOS/Linux）または`netstat -ano | findstr :PORT`（Windows）
- `config.toml`でポート設定変更
- 一般的な競合ポート: 3000、4000、13306、9200、5080
3. **サービス起動失敗**：
- コンテナログ確認: `docker compose logs SERVICE_NAME`
- Dockerイメージが利用可能か確認: `docker images`
- 十分なシステムリソース（メモリ、ディスク容量）を確認
4. **データベース接続問題**：
- MySQLコンテナステータス確認: `docker compose ps mysql`
- MySQLログ確認: `docker compose logs mysql`
- 接続テスト: `docker compose exec mysql mysql -u userfeedback -p`
### デバッグのヒント
1. **コンテナログ確認**：
```bash
# すべてのコンテナログ
docker compose logs
# 特定のサービスログ
docker compose logs api
docker compose logs web
docker compose logs mysql
```
2. **サービスステータス確認**：
```bash
# APIステータス確認
curl http://localhost:4000/api/health
# OpenSearchステータス確認（有効な場合）
curl http://localhost:9200/_cluster/health
```
3. **データベース直接アクセス**：
```bash
# MySQL接続
docker compose exec mysql mysql -u userfeedback -p userfeedback
```
## 制限事項
CLIツールは開発およびテスト環境用に設計されています。本番環境へのデプロイには、次を考慮してください：
1. **セキュリティ考慮事項**：
- 機密データには設定ファイルではなく環境変数を使用
- 適切なシークレット管理を実装
- 本番レベルのJWTシークレットを使用
- HTTPS/TLS暗号化を有効化
2. **スケーラビリティと可用性**：
- KubernetesやDocker Swarmなどのオーケストレーションツールを使用
- ロードバランシングと自動スケーリングを実装
- 適切なモニタリングとアラートを設定
- 管理データベースサービス（RDS、Cloud SQLなど）を使用
3. **データ管理**：
- 自動化されたバックアップ戦略を実装
- 適切なバックアップがある永続ボリュームを使用
- データ保持ポリシーを考慮
- ディスク使用量とパフォーマンスをモニタリング
## 次のステップ
詳細なAPIおよびウェブサーバー設定オプションについては、[環境変数設定](./05-configuration.md)ドキュメントを参照してください。
apps/docs/i18n/ja/docusaurus-plugin-content-docs/current/02-developer-guide/01-installation/03-manual-setup.md
+276
View File
@@ -0,0 +1,276 @@
---
sidebar_position: 3
title: '手動インストール'
description: 'ソースコードから直接ABC User Feedbackをビルドして実行する手動インストールガイド'
---
# 手動インストール
このドキュメントは、ABC User Feedbackを手動でインストール・構成する方法を説明します。ソースコードから直接アプリケーションをビルドして実行したい場合に便利です。
## 前提条件
手動インストールを進める前に、次の要件を満たす必要があります：
- [Node.js v22.19.0以上](https://nodejs.org/en/download/)
- [pnpm v10.15.0以上](https://pnpm.io/installation)（パッケージマネージャー）
- [Git](https://git-scm.com/downloads)
- [MySQL 8.0](https://www.mysql.com/downloads/)
- SMTPサーバー
- （オプション）[OpenSearch 2.16](https://opensearch.org/)
## ソースコードのダウンロード
まず、GitHubリポジトリからABC User Feedbackのソースコードをクローンします：
```bash
git clone https://github.com/line/abc-user-feedback.git
cd abc-user-feedback
```
## インフラ設定
ABC User FeedbackにはMySQLデータベース、SMTPサーバー、そしてオプションでOpenSearchが必要です。これらのインフラコンポーネントを設定する方法はいくつかあります。
### Dockerを使用したインフラ設定
最も簡単な方法は、Docker Composeで必要なインフラを設定することです：
```bash
docker-compose -f docker/docker-compose.infra.yml up -d
```
### 既存インフラの使用
既にMySQL、OpenSearch、またはSMTPサーバーがある場合は、後で環境変数として接続情報を構成できます。
## 依存関係のインストール
ABC User FeedbackはTurboRepoを通じて管理されるモノレポ構造を使用します。すべてのパッケージの依存関係をインストールするには：
```bash
pnpm install
```
依存関係のインストール後、すべてのパッケージをビルドします：
```bash
pnpm build
```
## 環境変数設定
### APIサーバー環境変数
`apps/api`ディレクトリに`.env`ファイルを作成し、`.env.example`を参照して構成します：
```env
# Required environment variables
JWT_SECRET=DEV
MYSQL_PRIMARY_URL=mysql://userfeedback:userfeedback@localhost:13306/userfeedback # required
ACCESS_TOKEN_EXPIRED_TIME=10m # default: 10m
REFRESH_TOKEN_EXPIRED_TIME=1h # default: 1h
# Optional environment variables
# APP_PORT=4000 # default: 4000
# APP_ADDRESS=0.0.0.0 # default: 0.0.0.0
# MYSQL_SECONDARY_URLS= ["mysql://userfeedback:userfeedback@localhost:13306/userfeedback"] # optional
SMTP_HOST=localhost # required
SMTP_PORT=25 # required
SMTP_SENDER=user@feedback.com # required
# SMTP_USERNAME= # optional
# SMTP_PASSWORD= # optional
# SMTP_TLS= # default: false
# SMTP_CIPHER_SPEC= # default: TLSv1.2 if SMTP_TLS=true
# SMTP_OPPORTUNISTIC_TLS= # default: true if SMTP_TLS=true
# OPENSEARCH_USE=false # default: false
# OPENSEARCH_NODE= # required if OPENSEARCH_USE=true
# OPENSEARCH_USERNAME= # optional
# OPENSEARCH_PASSWORD= # optional
# AUTO_MIGRATION=true # default: true
# MASTER_API_KEY= # default: none
# BASE_URL=https://api.example.com # Swaggerドキュメントで使用するAPIサーバーの公開URL（オプション）
# AUTO_FEEDBACK_DELETION_ENABLED=false # default: false
# AUTO_FEEDBACK_DELETION_PERIOD_DAYS=365*5
```
### ウェブサーバー環境変数
`apps/web`ディレクトリに`.env`ファイルを作成し、`.env.example`を参照して構成します：
```env
NEXT_PUBLIC_API_BASE_URL=http://localhost:4000
```
環境変数の詳細については、[環境変数設定](./05-configuration.md)ドキュメントを参照してください。
## データベースマイグレーション
APIサーバーを初めて実行する前に、データベーススキーマを作成する必要があります。`AUTO_MIGRATION=true`環境変数を設定すると、サーバー起動時にマイグレーションが自動的に実行されます。
手動でマイグレーションを実行するには：
```bash
cd apps/api
npm run migration:run
```
## 開発モードでの実行
### 単一コマンドで実行
APIサーバーとウェブサーバーを開発モードで実行するには：
```bash
# プロジェクトルートディレクトリから
pnpm dev
```
このコマンドはAPIサーバーとウェブサーバーを同時に起動します。APIサーバーはデフォルトでポート4000で、ウェブサーバーはポート3000で実行されます。
### 個別パッケージの実行
#### 共通パッケージのビルド
ウェブアプリケーションを実行する前に、共有パッケージをビルドする必要があります：
```bash
# プロジェクトルートディレクトリから
cd packages/ufb-shared
pnpm build
```
#### UIパッケージのビルド
ウェブアプリケーションを実行する前に、UIパッケージをビルドする必要があります：
```bash
# プロジェクトルートディレクトリから
cd packages/ufb-tailwindcss
pnpm build
```
#### 各サーバーの個別実行
各サーバーを個別に実行するには：
```bash
# APIサーバーのみ実行
cd apps/api
pnpm dev
# ウェブサーバーのみ実行
cd apps/web
pnpm dev
```
## 本番ビルド
本番環境用のアプリケーションをビルドするには：
```bash
# プロジェクトルートディレクトリから
pnpm build
```
このコマンドはAPIサーバーとウェブサーバーの両方をビルドします。
## 本番モードでの実行
本番ビルドを実行するには：
```bash
# APIサーバー実行
cd apps/api
pnpm start
# ウェブサーバー実行
cd apps/web
pnpm start
```
## APIタイプ生成
バックエンドAPIが実行中の場合、フロントエンド用のAPIタイプを生成できます：
```bash
cd apps/web
pnpm generate-api-type
```
このコマンドはOpenAPI仕様からTypeScriptタイプを生成し、`src/shared/types/api.type.ts`ファイルに保存します。
**注意**: このコマンドが正しく動作するには、APIサーバーが`http://localhost:4000`で実行中である必要があります。
## コード品質管理
### リンティング
コードリンティングを実行するには：
```bash
pnpm lint
```
### フォーマット
コードフォーマットを実行するには：
```bash
pnpm format
```
### テスト
テストを実行するには：
```bash
pnpm test
```
## Swaggerドキュメント
APIサーバーが実行中の場合、次のエンドポイントでSwaggerドキュメントを確認できます：
- **APIドキュメント**: http://localhost:4000/docs
- **管理者APIドキュメント**: http://localhost:4000/admin-docs
- **OpenAPI JSON**: http://localhost:4000/docs-json
- **管理者OpenAPI JSON**: http://localhost:4000/admin-docs-json
> **注意**: APIサーバーをリバースプロキシの後ろで異なるURLで提供する場合、`BASE_URL`環境変数を設定すると、Swaggerドキュメントで正しいAPIエンドポイントURLが生成されます。例: `BASE_URL=https://api.example.com`
## トラブルシューティング
### 一般的な問題
1. **依存関係インストールエラー**：
- Node.jsバージョンがv22.19.0以上であることを確認してください。
- pnpmバージョンがv10.15.0以上であることを確認してください。
- pnpmを最新バージョンに更新してください。
- `pnpm install --force`を試してください。
2. **データベース接続エラー**：
- MySQLサーバーが実行中であることを確認してください。
- データベース認証情報が正しいことを確認してください。
- `MYSQL_PRIMARY_URL`環境変数の形式が正しいことを確認してください。
- Dockerインフラを使用する場合、MySQLがポート13306（3306ではない）で実行されていることを確認してください。
3. **ビルドエラー**：
- UIパッケージがビルドされていることを確認してください（`pnpm build:ui`）。
- すべての依存関係がインストールされていることを確認してください。
- TypeScriptエラーを確認してください。
4. **ランタイムエラー**：
- 環境変数が正しく設定されていることを確認してください。
- 必要なポートが利用可能であることを確認してください。
- ログのエラーメッセージを確認してください。
apps/docs/i18n/ja/docusaurus-plugin-content-docs/current/02-developer-guide/01-installation/04-smtp-configuration.md
+165
View File
@@ -0,0 +1,165 @@
---
id: smtp-configuration
title: SMTPサーバー統合ガイド
description: 本番環境で認証メール送信のための外部SMTPサーバー統合方法を案内します。
sidebar_position: 4
---
# SMTPサーバー統合ガイド
本番環境では、`smtp4dev`のようなローカルテストサーバーではなく、
**外部SMTPサーバー（Gmail、SendGrid、会社SMTPなど）**と接続して
認証メール（登録、パスワードリセットなど）を正常に送信できる必要があります。
このドキュメントでは、SMTPサーバー統合のための環境変数設定と主要な統合事例を案内します。
---
## 1. SMTP関連環境変数
`api`サービスまたは`.env`ファイルに次の環境変数を設定してください：
> **参考**: 認証が不要なSMTPサーバーの場合、`SMTP_USERNAME`と`SMTP_PASSWORD`は省略できます。
| 環境変数 | 説明 | 必須 |
| ------------------------ | ----------------------------------------------- | --------- |
| `SMTP_HOST` | SMTPサーバーアドレス（例：smtp.gmail.com） | 必須 |
| `SMTP_PORT` | ポート番号（通常587、465など） | 必須 |
| `SMTP_SENDER` | 送信者メールアドレス（例：`noreply@yourdomain.com`） | 必須 |
| `SMTP_USERNAME` | SMTP認証ユーザー名（アカウントID） | オプション |
| `SMTP_PASSWORD` | SMTP認証パスワードまたはAPIキー | オプション |
| `SMTP_TLS` | TLS使用有無（`true`または`false`） | オプション |
| `SMTP_CIPHER_SPEC` | TLS暗号化アルゴリズム（デフォルト：`TLSv1.2`） | オプション |
| `SMTP_OPPORTUNISTIC_TLS` | STARTTLS使用有無（`true`または`false`） | オプション |
> **重要**: 実際のコードでは`SMTP_USERNAME`と`SMTP_PASSWORD`が使用され、`SMTP_TLS=true`はポート465に、`false`はポート587に主に使用されます。
---
## 2. Docker環境例
```yaml
api:
image: line/abc-user-feedback-api
environment:
- SMTP_HOST=smtp.gmail.com
- SMTP_PORT=587
- SMTP_USERNAME=your-email@gmail.com
- SMTP_PASSWORD=your-email-app-password
- SMTP_SENDER=noreply@yourdomain.com
- SMTP_TLS=false
- SMTP_OPPORTUNISTIC_TLS=true
```
または`.env`ファイルで分離管理できます：
```env
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-email-app-password
SMTP_SENDER=noreply@yourdomain.com
SMTP_TLS=false
SMTP_OPPORTUNISTIC_TLS=true
```
---
## 3. SMTP統合例
### ✅ Gmail SMTP統合（個人テスト用）
- `SMTP_HOST`: `smtp.gmail.com`
- `SMTP_PORT`: `587`
- `SMTP_USERNAME`: Gmailアドレス（例：`abc@gmail.com`）
- `SMTP_PASSWORD`: **アプリパスワード**（安全性の低いアプリを許可 → 非推奨）
- `SMTP_TLS`: `false`
- `SMTP_OPPORTUNISTIC_TLS`: `true`
> Gmailアカウントに**2段階認証**が有効になっている場合、[アプリパスワード](https://myaccount.google.com/apppasswords)を作成する必要があります。
---
### ✅ SendGrid統合（推奨）
- `SMTP_HOST`: `smtp.sendgrid.net`
- `SMTP_PORT`: `587`
- `SMTP_USERNAME`: `apikey`
- `SMTP_PASSWORD`: 実際のSendGrid APIキー
- `SMTP_SENDER`: 確認済み送信者アドレス
- `SMTP_TLS`: `false`
- `SMTP_OPPORTUNISTIC_TLS`: `true`
---
## 4. テスト方法
### 4.1 メール送信テスト
1. **メール認証テスト**：
- 管理者またはユーザーアカウント作成
- メール認証コード送信確認
2. **パスワードリセットテスト**：
- パスワードリセットリクエスト
- リセットリンクが含まれたメール受信確認
3. **ユーザー招待テスト**：
- 管理者が新しいユーザーを招待
- 招待メール送信確認
### 4.2 ログ確認
メール送信失敗時、次のコマンドで詳細ログを確認してください：
```bash
# Docker Compose環境
docker compose logs api
# 特定時間帯のログ確認
docker compose logs --since=10m api
# リアルタイムログモニタリング
docker compose logs -f api
```
SMTPエラーが発生すると、ログに詳細メッセージが表示されます。
---
## 5. トラブルシューティング
| 問題タイプ | 原因または解決方法 |
| -------------------------- | ---------------------------------------- |
| 認証エラー（`535`） | `SMTP_USERNAME` / `SMTP_PASSWORD`再確認 |
| 接続拒否（`ECONNREFUSED`） | ファイアウォールまたは誤ったポート設定 |
| メールが届かない | `SMTP_SENDER`が認証されていない |
| TLSエラー（`ETLS`） | `SMTP_TLS`設定が誤っている |
| STARTTLS失敗 | `SMTP_OPPORTUNISTIC_TLS`設定確認 |
---
## 6. SMTPに関連するメールテンプレート
現在、システムでメールは次の状況で送信されます：
- **メール認証**: 管理者/ユーザー登録時に認証コード送信
- **パスワードリセット**: パスワードリセットリクエスト時にリンク送信
- **ユーザー招待**: 管理者がユーザーを招待するときに招待メール送信
メール内容は**Handlebarsテンプレート**ベースで構成されており、次の情報が含まれます：
- 送信者: `"User feedback" <SMTP_SENDER>`
- 基本URL: `ADMIN_WEB_URL`環境変数値を使用
- テンプレート位置: `src/configs/modules/mailer-config/templates/`
---
## 関連ドキュメント
- [Docker Hubインストールガイド](./docker-hub-images)
- [環境変数設定](./configuration)
- [初期設定ガイド](/ja/user-guide/getting-started)
apps/docs/i18n/ja/docusaurus-plugin-content-docs/current/02-developer-guide/01-installation/05-configuration.md
+213
View File
@@ -0,0 +1,213 @@
---
id: configuration
title: 環境変数構成
description: ABC User FeedbackのAPIおよびウェブサーバーの環境変数構成方法を説明します。
sidebar_position: 5
---
# 環境変数構成
このドキュメントでは、ABC User Feedbackの**APIサーバー**および**ウェブサーバー**で使用する主要な環境変数と設定方法を説明します。
---
## 1. APIサーバー環境変数
### 必須環境変数
| 環境変数 | 説明 | デフォルト | 例 |
| ---------------------------- | ------------------------- | ---------- | -------------------------------- |
| `JWT_SECRET` | JWT署名用シークレットキー | なし | `jwtsecretjwtsecretjwtsecret` |
| `MYSQL_PRIMARY_URL` | MySQL接続URL | なし | `mysql://user:pass@host:3306/db` |
| `ACCESS_TOKEN_EXPIRED_TIME` | Access Token有効期間 | `10m` | `10m`、`30s`、`1h` |
| `REFRESH_TOKEN_EXPIRED_TIME` | Refresh Token有効期間 | `1h` | `1h`、`7d` |
> JWTシークレットは十分に複雑で安全な文字列を使用する必要があります。
⚠️ **セキュリティ注意事項**：
- `JWT_SECRET`は最低32文字以上の複雑な文字列を使用してください
- 本番環境では絶対にデフォルト値を使用しないでください
- 環境変数ファイル（`.env`）はバージョン管理に含めないでください
- 機密情報は環境変数やシークレット管理システムを通じて管理してください
---
### オプション環境変数
| 環境変数 | 説明 | デフォルト | 例 |
| ---------------------- | ------------------------------------------------- | ----------------------- | --------------------------- |
| `APP_PORT` | APIサーバーポート | `4000` | `4000` |
| `APP_ADDRESS` | バインドアドレス | `0.0.0.0` | `127.0.0.1` |
| `ADMIN_WEB_URL` | 管理者ウェブURL | `http://localhost:3000` | `https://admin.company.com` |
| `BASE_URL` | Swaggerドキュメントで使用するAPIサーバーの公開URL | なし | `https://api.example.com` |
| `MYSQL_SECONDARY_URLS` | セカンダリDB URL（JSON配列） | なし | `["mysql://..."]` |
| `AUTO_MIGRATION` | アプリ起動時のDB自動マイグレーション | `true` | `false` |
| `MASTER_API_KEY` | マスター権限APIキー（オプション） | なし | `abc123xyz` |
| `NODE_OPTIONS` | Node実行オプション | なし | `--max_old_space_size=4096` |
---
### SMTP設定（メール認証）
| 環境変数 | 説明 | 例 |
| ------------------------ | -------------------------------- | ------------------------------ |
| `SMTP_HOST` | SMTPサーバーアドレス | `smtp.gmail.com` |
| `SMTP_PORT` | ポート（通常587または465） | `587` |
| `SMTP_USERNAME` | ログインユーザー | `user@example.com` |
| `SMTP_PASSWORD` | ログインパスワードまたはトークン | `app-password` |
| `SMTP_SENDER` | 送信者アドレス | `noreply@company.com` |
| `SMTP_BASE_URL` | メール内リンク用基本URL | `https://feedback.company.com` |
| `SMTP_TLS` | TLS使用有無 | `true` |
| `SMTP_CIPHER_SPEC` | 暗号化仕様 | `TLSv1.2` |
| `SMTP_OPPORTUNISTIC_TLS` | STARTTLSサポート有無 | `true` |
📎 詳細設定については、[SMTP統合ガイド](./04-smtp-configuration.md)を参照してください。
---
## 2. OpenSearch設定（オプション）
| 環境変数 | 説明 | 例 |
| --------------------- | -------------------- | ----------------------- |
| `OPENSEARCH_USE` | OpenSearch有効化有無 | `true` |
| `OPENSEARCH_NODE` | OpenSearchノードURL | `http://localhost:9200` |
| `OPENSEARCH_USERNAME` | 認証ID | `admin` |
| `OPENSEARCH_PASSWORD` | 認証パスワード | `admin123` |
> OpenSearchは検索速度向上およびAI機能改善に使用されます。
---
## 3. 自動フィードバック削除設定
| 環境変数 | 説明 | デフォルト / 条件 |
| ------------------------------------ | -------------------------------- | ----------------------- |
| `AUTO_FEEDBACK_DELETION_ENABLED` | 古いフィードバック削除機能有効化 | `false` |
| `AUTO_FEEDBACK_DELETION_PERIOD_DAYS` | 削除基準日数 | `365`（有効な場合必須） |
---
## 4. APIログExport設定（オプション）
APIは標準のコンソールログに加えて、OpenTelemetry経由でアプリケーションログをexportできます。
<!-- markdownlint-disable MD060 -->
| 環境変数 | 説明 | デフォルト | 例 |
| ---------------------------------- | ----------------------------------------------------------------- | ---------- | ---------------------------------------------------------- |
| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | pino OpenTelemetry transportが使用するOTLP HTTPログエンドポイント | なし | `http://localhost:4319/v1/logs` |
| `OTEL_RESOURCE_ATTRIBUTES` | exportされたログに付与するOpenTelemetry resource attributes | なし | `service.name=abc-user-feedback-api,service.version=1.1.1` |
<!-- markdownlint-enable MD060 -->
> `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` が設定されている場合、APIはpretty consoleログを継続して出力しつつ、同じログを設定されたOTLP HTTPエンドポイントにも送信します。
> `OTEL_RESOURCE_ATTRIBUTES` も設定すると、`service.name` や `service.version` などの標準OpenTelemetryリソースメタデータを、カンマ区切りの `key=value` 形式でログに付与できます。
> ローカル開発環境では `apps/api/.env.example` の例を基準に設定してください。
### ローカル検証手順
- リポジトリルートでローカルOTELテストスタックを起動します。
```bash
docker compose -f docker/docker-compose.otel-test.yml up -d
```
- `apps/api/.env.example` を参考にして、`apps/api/.env` に次の値を設定します。
```env
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://localhost:4319/v1/logs
OTEL_RESOURCE_ATTRIBUTES=service.name=abc-user-feedback-api,service.version=1.1.1
```
> APIアプリケーション自体がこの値を個別にパースするわけではなく、`pino-opentelemetry-transport` と OpenTelemetry SDK が標準環境変数として処理します。
- APIサーバーを起動し、ログが発生するリクエストを送信します。
```bash
pnpm --dir apps/api dev
```
- OpenTelemetryパイプラインがログを受信していることを確認します。
- Vectorはポート `4319` でOTLPログを受信し、変換済みログレコードをコンソールへ出力します。
- OpenSearchにはホストポート `9201` でアクセスできる必要があります。
- OpenSearch Dashboardsには [http://localhost:5602](http://localhost:5602) でアクセスでき、ローカルスタックが作成した `logs-*` インデックスを確認できます。
> ローカルテストスタックは `docker/docker-compose.otel-test.yml` の定義に従い、OTLP HTTP `4319`、OpenSearch `9201`、OpenSearch Dashboards `5602` を使用します。
---
## 5. ウェブサーバー環境変数
### 必須環境変数
| 環境変数 | 説明 | 例 |
| -------------------------- | ----------------------------------------- | ----------------------- |
| `NEXT_PUBLIC_API_BASE_URL` | クライアントで使用するAPIサーバーアドレス | `http://localhost:4000` |
### オプション環境変数
| 環境変数 | 説明 | デフォルト | 例 |
| -------- | -------------------- | ---------- | ------ |
| `PORT` | フロントエンドポート | `3000` | `3000` |
---
## 6. 設定方法
### Docker Compose例
```yaml
services:
api:
image: line/abc-user-feedback-api
environment:
- JWT_SECRET=changeme
- MYSQL_PRIMARY_URL=mysql://user:pass@mysql:3306/userfeedback
- SMTP_HOST=smtp.sendgrid.net
- SMTP_USERNAME=apikey
- SMTP_PASSWORD=your-sendgrid-key
```
### .envファイル例
```env
# apps/api/.env
JWT_SECRET=changemechangemechangeme
MYSQL_PRIMARY_URL=mysql://root:pass@localhost:3306/db
ACCESS_TOKEN_EXPIRED_TIME=10m
REFRESH_TOKEN_EXPIRED_TIME=1h
SMTP_HOST=smtp.example.com
SMTP_SENDER=noreply@example.com
# BASE_URL=https://api.example.com # リバースプロキシの後ろで提供する場合に設定
# apps/web/.env
NEXT_PUBLIC_API_BASE_URL=http://localhost:4000
```
---
## 7. トラブルシューティングガイド
<!-- markdownlint-disable MD060 -->
| 問題 | 原因と解決策 |
| ---------------------- | --------------------------------------------------------------------------------------------------- |
| 環境変数が認識されない | `.env`位置確認またはコンテナ再起動 |
| DB接続失敗 | `MYSQL_PRIMARY_URL`形式または接続情報確認 |
| SMTPエラー | ポート/TLS設定または認証情報再確認 |
| OpenSearchエラー | ノードURLまたはユーザー認証確認 |
| OTELログexport失敗 | `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` の設定有無、endpoint URL、OTELスタック起動有無を確認してください |
| JWTトークンエラー | `JWT_SECRET`長さおよび複雑性確認 |
| 環境変数検証失敗 | 必須環境変数欠落またはタイプエラー確認 |
| ポート競合 | `APP_PORT`、`PORT`設定確認 |
<!-- markdownlint-enable MD060 -->
---
## 関連ドキュメント
- [Dockerインストールガイド](./docker-hub-images)
- [SMTP統合ガイド](./smtp-configuration)
- [初期設定ガイド](/ja/user-guide/getting-started)
apps/docs/i18n/ja/docusaurus-plugin-content-docs/current/02-developer-guide/01-installation/_category_.json
+5
View File
@@ -0,0 +1,5 @@
{
"position": 1,
"label": "インストール",
"description": "開発環境の設定とインストールガイドです。"
}
apps/docs/i18n/ja/docusaurus-plugin-content-docs/current/02-developer-guide/01-installation/index.md
+7
View File
@@ -0,0 +1,7 @@
---
title: インストール
---
import DocCardList from '@theme/DocCardList';
<DocCardList />
apps/docs/i18n/ja/docusaurus-plugin-content-docs/current/02-developer-guide/02-api-integration.md
+533
View File
@@ -0,0 +1,533 @@
---
sidebar_position: 2
title: "API統合"
description: "ABC User Feedback APIを活用した外部システム統合方法と実際の実装例を案内します。"
---
# API統合
ABC User Feedbackは**RESTful API**を通じて外部システムと統合できます。プログラムでフィードバックを収集し、イシューを管理し、データを照会できるため、既存のサービスやワークフローに簡単に統合できます。
---
## API基本情報
### 公式APIドキュメント
ABC User Feedbackの**完全なAPIドキュメント**は次のリンクで確認できます：
🔗 **[公式APIドキュメント（Redocly）](https://line.github.io/abc-user-feedback/)**
このドキュメントでは、すべてのエンドポイントの詳細な仕様、リクエスト/レスポンス例、実際にテスト可能なインターフェースを提供します。
### Base URL
```
https://your-domain.com/api
```
### 認証方式
すべてのAPIリクエストは**APIキーベースの認証**を使用します。
```http
X-API-KEY: your-api-key-here
Content-Type: application/json
```
:::warning セキュリティ注意事項
APIキーはサーバーサイドでのみ使用し、クライアント（ブラウザ、モバイルアプリ）に公開しないでください。
:::
### APIキー発行方法
1. **管理者ページアクセス**: ABC User Feedback管理者ページにログイン
2. **プロジェクト設定**: 該当プロジェクトの設定ページに移動
3. **APIキー管理**: 「APIキー管理」メニューから新しいAPIキーを生成
4. **キーコピー**: 生成されたAPIキーを安全な場所に保存
:::info APIキー権限
APIキーはプロジェクトごとに発行され、該当プロジェクトのデータにのみアクセスできます。
:::
---
## 主要APIエンドポイント例
### 1. フィードバック作成
#### 基本フィードバック作成
```javascript
const createFeedback = async (
projectId,
channelId,
message,
issueNames = []
) => {
const response = await fetch(
`/api/projects/${projectId}/channels/${channelId}/feedbacks`,
{
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-KEY": "your-api-key-here",
},
body: JSON.stringify({
message: message,
issueNames: issueNames,
}),
}
);
return await response.json();
};
// 使用例
const feedback = await createFeedback(1, 1, "決済エラーが発生しました", [
"決済",
"エラー",
]);
```
### 2. フィードバック照会
#### チャネル別フィードバック検索
```javascript
const searchFeedbacks = async (
projectId,
channelId,
searchText,
limit = 10,
page = 1
) => {
const response = await fetch(
`/api/projects/${projectId}/channels/${channelId}/feedbacks/search`,
{
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-KEY": "your-api-key-here",
},
body: JSON.stringify({
limit: limit,
page: page,
query: {
searchText: searchText,
createdAt: {
gte: "2024-01-01",
lt: "2024-12-31",
},
},
sort: {
createdAt: "DESC",
},
}),
}
);
return await response.json();
};
// 使用例
const feedbacks = await searchFeedbacks(1, 1, "決済", 20, 1);
console.log(
`合計${feedbacks.meta.totalItems}件のフィードバック中${feedbacks.items.length}件を照会`
);
```
#### 単一フィードバック照会
```javascript
const getFeedbackById = async (projectId, channelId, feedbackId) => {
const response = await fetch(
`/api/projects/${projectId}/channels/${channelId}/feedbacks/${feedbackId}`,
{
method: "GET",
headers: {
"X-API-KEY": "your-api-key-here",
},
}
);
return await response.json();
};
// 使用例
const feedback = await getFeedbackById(1, 1, 123);
console.log("フィードバック詳細:", feedback);
```
#### フィードバック更新
```javascript
const updateFeedback = async (projectId, channelId, feedbackId, updateData) => {
const response = await fetch(
`/api/projects/${projectId}/channels/${channelId}/feedbacks/${feedbackId}`,
{
method: "PUT",
headers: {
"Content-Type": "application/json",
"X-API-KEY": "your-api-key-here",
},
body: JSON.stringify(updateData),
}
);
return await response.json();
};
// 使用例
const updatedFeedback = await updateFeedback(1, 1, 123, {
message: "更新されたフィードバック内容",
issueNames: ["更新されたイシュー"],
});
```
#### フィードバック削除
```javascript
const deleteFeedbacks = async (projectId, channelId, feedbackIds) => {
const response = await fetch(
`/api/projects/${projectId}/channels/${channelId}/feedbacks`,
{
method: "DELETE",
headers: {
"Content-Type": "application/json",
"X-API-KEY": "your-api-key-here",
},
body: JSON.stringify({
feedbackIds: feedbackIds,
}),
}
);
return await response.json();
};
// 使用例
const result = await deleteFeedbacks(1, 1, [123, 124, 125]);
console.log("削除完了:", result);
```
### 3. イシュー管理
#### イシュー作成
```javascript
const createIssue = async (projectId, name, description) => {
const response = await fetch(`/api/projects/${projectId}/issues`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-KEY": "your-api-key-here",
},
body: JSON.stringify({
name: name,
description: description,
}),
});
return await response.json();
};
// 使用例
const issue = await createIssue(
1,
"決済エラー",
"ユーザーが決済過程でエラーを経験"
);
```
#### イシュー検索
```javascript
const searchIssues = async (projectId, query = {}) => {
const response = await fetch(`/api/projects/${projectId}/issues/search`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-KEY": "your-api-key-here",
},
body: JSON.stringify({
limit: 10,
page: 1,
query: query,
sort: {
createdAt: "DESC",
},
}),
});
return await response.json();
};
// 使用例
const issues = await searchIssues(1, { name: "決済" });
```
#### イシュー照会
```javascript
const getIssueById = async (projectId, issueId) => {
const response = await fetch(`/api/projects/${projectId}/issues/${issueId}`, {
method: "GET",
headers: {
"X-API-KEY": "your-api-key-here",
},
});
return await response.json();
};
// 使用例
const issue = await getIssueById(1, 123);
console.log("イシュー詳細:", issue);
```
#### イシュー更新
```javascript
const updateIssue = async (projectId, issueId, updateData) => {
const response = await fetch(`/api/projects/${projectId}/issues/${issueId}`, {
method: "PUT",
headers: {
"Content-Type": "application/json",
"X-API-KEY": "your-api-key-here",
},
body: JSON.stringify(updateData),
});
return await response.json();
};
// 使用例
const updatedIssue = await updateIssue(1, 123, {
name: "更新されたイシュー名",
description: "更新されたイシュー説明",
});
```
#### イシュー削除
```javascript
const deleteIssues = async (projectId, issueIds) => {
const response = await fetch(`/api/projects/${projectId}/issues`, {
method: "DELETE",
headers: {
"Content-Type": "application/json",
"X-API-KEY": "your-api-key-here",
},
body: JSON.stringify({
issueIds: issueIds,
}),
});
return await response.json();
};
// 使用例
const result = await deleteIssues(1, [123, 124, 125]);
console.log("イシュー削除完了:", result);
```
#### フィードバックにイシュー追加
```javascript
const addIssueToFeedback = async (
projectId,
channelId,
feedbackId,
issueId
) => {
const response = await fetch(
`/api/projects/${projectId}/channels/${channelId}/feedbacks/${feedbackId}/issues/${issueId}`,
{
method: "POST",
headers: {
"X-API-KEY": "your-api-key-here",
},
}
);
return await response.json();
};
// 使用例
const result = await addIssueToFeedback(1, 1, 123, 456);
console.log("イシュー追加完了:", result);
```
#### フィードバックからイシュー削除
```javascript
const removeIssueFromFeedback = async (
projectId,
channelId,
feedbackId,
issueId
) => {
const response = await fetch(
`/api/projects/${projectId}/channels/${channelId}/feedbacks/${feedbackId}/issues/${issueId}`,
{
method: "DELETE",
headers: {
"X-API-KEY": "your-api-key-here",
},
}
);
return await response.json();
};
// 使用例
const result = await removeIssueFromFeedback(1, 1, 123, 456);
console.log("イシュー削除完了:", result);
```
### 4. プロジェクトとチャネル情報
#### プロジェクト情報照会
```javascript
const getProjectInfo = async (projectId) => {
const response = await fetch(`/api/projects/${projectId}`, {
method: "GET",
headers: {
"X-API-KEY": "your-api-key-here",
},
});
return await response.json();
};
// 使用例
const project = await getProjectInfo(1);
console.log("プロジェクト情報:", project);
```
#### チャネルフィールド照会
```javascript
const getChannelFields = async (projectId, channelId) => {
const response = await fetch(
`/api/projects/${projectId}/channels/${channelId}/fields`,
{
method: "GET",
headers: {
"X-API-KEY": "your-api-key-here",
},
}
);
return await response.json();
};
// 使用例
const fields = await getChannelFields(1, 1);
console.log("チャネルフィールド:", fields);
```
---
## SwaggerによるAPIテスト
ABC User Feedbackは**Swagger UI**を提供して、APIを簡単にテストし理解できます。
### Swaggerアクセス方法
**APIサーバーアドレス + `/docs`**でアクセスします：
```
https://your-domain.com/api/docs
```
または**ReDoc形式**で：
```
https://your-domain.com/api/docs/redoc
```
### SwaggerでのAPIキー設定
1. Swagger UI上部の**"Authorize"**ボタンをクリック
2. **X-API-KEY**フィールドに発行されたAPIキーを入力
3. **"Authorize"**をクリックして認証完了
これ以降、すべてのAPIリクエストで自動的にAPIキーが含まれ、テストできます。
### Swagger活用のヒント
- **"Try it out"**ボタンで実際のAPI呼び出しテスト
- **Response body**セクションで実際のレスポンスデータ構造を確認
- **Schema**タブでリクエスト/レスポンスデータ形式の詳細を確認
- **cURL**コマンドを自動生成してCLIテスト可能
---
## エラー処理と再試行ロジック
### HTTPステータスコード
| ステータスコード | 意味 | 処理方法 |
| --------- | -------------- | ----------------------- |
| **200** | 成功 | 正常処理 |
| **400** | 不正なリクエスト | リクエストデータ検証 |
| **401** | 認証失敗 | APIキー確認 |
| **403** | 権限なし | プロジェクトアクセス権限確認 |
| **404** | リソースなし | ID値確認 |
| **429** | リクエスト制限超過 | しばらくしてから再試行 |
| **500** | サーバーエラー | 再試行またはサポートチームに問い合わせ |
## レスポンスデータ解析方法
### ページネーションレスポンス構造
```json
{
"meta": {
"itemCount": 10,
"totalItems": 100,
"itemsPerPage": 10,
"totalPages": 10,
"currentPage": 1
},
"items": [
{
"id": 1,
"message": "フィードバック内容",
"createdAt": "2024-01-01T00:00:00.000Z",
"issues": [
{
"id": 1,
"name": "イシュー名"
}
]
}
]
}
```
## セキュリティとパフォーマンス最適化
### APIキーセキュリティ
- **環境変数使用**: APIキーを環境変数で管理
- **サーバーサイドのみ**: クライアントにAPIキーを公開しない
- **キーローテーション**: 定期的なAPIキー交換
- **IPホワイトリスト**: 可能な場合は特定IPからのみアクセス許可
### パフォーマンス最適化
- **ページネーション活用**: 大量データ照会時に適切なlimit設定
- **必要なフィールドのみリクエスト**: クエリ最適化でレスポンス速度改善
- **キャッシング戦略**: 頻繁に照会するデータはクライアントサイドキャッシング
- **バッチ処理**: 複数のリクエストをまとめて処理
## 関連ドキュメント
- [APIキー管理](/ja/user-guide/settings/api-key-management) - UIからAPIキーを発行する方法
- [画像設定](/ja/user-guide/settings/image-setting) - 画像アップロードAPI使用のための設定
- [Webhook統合](/ja/user-guide/settings/webhook-management) - APIと一緒に活用できるリアルタイム通知設定
apps/docs/i18n/ja/docusaurus-plugin-content-docs/current/02-developer-guide/03-oauth-integration.md
+172
View File
@@ -0,0 +1,172 @@
---
sidebar_position: 3
title: "OAuth統合"
description: "Google OAuthおよびカスタムOAuthプロバイダーによるシングルサインオン（SSO）統合方法を案内します。"
---
# OAuth統合
ABC User FeedbackでOAuth 2.0ベースのシングルサインオン（SSO）を設定すると、ユーザーは別のアカウント作成なしで既存のアカウント（Google、Microsoft、GitHubなど）でログインできます。これはユーザーの利便性を向上させ、企業環境で統合認証を実装するために不可欠です。
---
## OAuth統合の概要
ABC User FeedbackでサポートされるOAuth方式：
### 1. Google OAuth
- 追加設定なしでデフォルト提供
- Googleアカウントによる簡単なログイン
### 2. カスタムOAuthプロバイダー
- 社内認証システム
- その他のOAuth 2.0/OpenID Connect互換サービス
OAuthを設定すると、既存のメールログインと並行して使用でき、組織ポリシーに応じてOAuthのみを許可するように制限することもできます。
---
## Google OAuth統合設定
### Google Cloud Consoleでの設定
#### 1. Google Cloud Consoleにアクセス
[Google Cloud Console](https://console.cloud.google.com)にアクセスしてプロジェクトを作成するか、既存のプロジェクトを選択します。
#### 2. OAuth 2.0クライアントID作成
1. **APIとサービス > 認証情報**メニューに移動
2. **+ 認証情報を作成 > OAuthクライアントID**を選択
3. アプリケーションタイプを**ウェブアプリケーション**として選択
#### 3. 承認済みリダイレクトURI設定
**承認済みリダイレクトURI**に次のURLを追加します：
```
https://your-domain.com/auth/oauth-callback
```
例：
- `https://feedback.company.com/auth/oauth-callback`
- `http://localhost:3000/auth/oauth-callback`（開発環境）
#### 4. クライアント情報確認
作成完了後、次の情報を確認してコピーしておきます：
- **クライアントID**: `1234567890-abc123def456.apps.googleusercontent.com`
- **クライアントシークレット**: `GOCSPX-abcdef123456`
### ABC User FeedbackでのGoogle OAuth設定
Google OAuthを使用するには、次の手順に従って設定する必要があります：
#### 1. Google OAuth設定有効化
**Settings > Login Management**で：
1. **OAuth2.0 Login**トグルを有効化
2. **Login Button Type**を"Google Login"として選択
3. Google Cloud Consoleで取得した情報を入力：
- **Client ID**: Google Cloud Consoleで作成したクライアントID
- **Client Secret**: Google Cloud Consoleで作成したクライアントシークレット
- **Authorization Code Request URL**: `https://accounts.google.com/o/oauth2/v2/auth`
- **Scope**: `openid email profile`
- **Access Token URL**: `https://oauth2.googleapis.com/token`
- **User Profile Request URL**: `https://www.googleapis.com/oauth2/v2/userinfo`
- **Email Key**: `email`
#### 2. リダイレクトURI登録
Google Cloud Consoleで次のURLを**承認済みリダイレクトURI**に追加：
```
https://your-domain.com/auth/oauth-callback
```
開発環境の場合：
```
http://localhost:3000/auth/oauth-callback
```
---
## カスタムOAuthプロバイダー統合
### 社内認証システム統合
ABC User Feedbackは、企業環境で使用される社内認証システムと統合できます。ほとんどの社内認証システムはOAuth 2.0またはOpenID Connect標準をサポートしているため、標準OAuthフローを通じて統合が可能です。
#### 社内認証システム設定要件
社内認証システムと統合するには、次の情報が必要です：
1. **OAuthクライアント登録**
- クライアントID
- クライアントシークレット
- リダイレクトURI: `https://your-domain.com/auth/oauth-callback`
2. **OAuthエンドポイント情報**
- Authorization URL（認証リクエストURL）
- Token URL（トークン交換URL）
- User Info URL（ユーザー情報照会URL）
3. **権限範囲（Scope）**
- ユーザープロフィール情報アクセス権限
- メールアドレスアクセス権限
#### 一般的な社内認証システム例
| 項目 | 説明 | 社内システム例 |
| ---------------------------------- | ---------------------------------- | ------------------------------------------ |
| **Login Button Type** | ログインボタンタイプ | `CUSTOM` |
| **Login Button Name** | ログインボタンに表示される名前 | `社内アカウントでログイン` |
| **Client ID** | OAuthクライアントID | `company-auth-client-123` |
| **Client Secret** | クライアントシークレット | `company-secret-abc123` |
| **Authorization Code Request URL** | ユーザー認証リクエストURL | `https://auth.company.com/oauth/authorize` |
| **Scope** | リクエストする権限範囲 | `openid email profile` |
| **Access Token URL** | トークンリクエストURL | `https://auth.company.com/oauth/token` |
| **User Profile Request URL** | ユーザー情報照会API | `https://auth.company.com/api/user` |
| **Email Key** | ユーザー情報JSONのメールフィールド名 | `email`または`mail` |
### その他のOAuth 2.0/OpenID Connect互換サービス
ABC User Feedbackは、OAuth 2.0またはOpenID Connect標準に準拠するすべての認証サービスと統合できます。
#### サポート可能なサービスタイプ
- **OpenID Connectプロバイダー**: 標準OpenID Connectプロトコルをサポートするサービス
- **OAuth 2.0プロバイダー**: OAuth 2.0 Authorization Codeフローをサポートするサービス
- **カスタム認証サーバー**: 標準OAuthエンドポイントを提供する自己構築サービス
#### 統合設定方法
**Settings > Login Management**でカスタムOAuthを設定します：
1. **管理者アカウントでログイン**後、**Settings > Login Management**メニューに移動
2. **OAuth2.0 Login**トグルを有効化
3. **Login Button Type**を`CUSTOM`として選択
4. 認証サービスプロバイダーから受け取った情報を入力：
- **Login Button Name**: ログインボタンに表示されるテキスト（例：「社内アカウントでログイン」）
- **Client ID**: OAuthクライアント識別子
- **Client Secret**: クライアント認証シークレット
- **Authorization Code Request URL**: ユーザー認証リクエストURL
- **Scope**: リクエストする権限範囲（スペース区切り、例：「openid email profile」）
- **Access Token URL**: アクセストークンリクエストURL
- **User Profile Request URL**: ユーザープロフィール情報照会URL
- **Email Key**: ユーザー情報JSONのメールフィールド名（例：「email」または「mail」）
---
## 関連ドキュメント
- [ログイン管理](/ja/user-guide/settings/tenant-settings) - UIでOAuthを設定する方法
apps/docs/i18n/ja/docusaurus-plugin-content-docs/current/02-developer-guide/04-webhook-integration.md
+303
View File
@@ -0,0 +1,303 @@
---
sidebar_position: 4
title: 'ウェブフック統合'
description: 'ウェブフックを活用して外部システムとリアルタイム統合する方法と実装例を案内します。'
---
# ウェブフック統合
ウェブフックにより、ABC User Feedbackで発生する主要イベントをリアルタイムで外部システムに配信できます。Slack通知、自動化ワークフロー、カスタム分析システムなどと統合できます。
---
## サポートされるイベントタイプ
ABC User Feedbackでサポートされるイベントは次のとおりです：
### 1. FEEDBACK_CREATION
新しいフィードバックが作成されたときに発生します。
**リクエストヘッダー：**
```
Content-Type: application/json
x-webhook-token: your-secret-token
```
**ペイロード例：**
```json
{
"event": "FEEDBACK_CREATION",
"data": {
"feedback": {
"id": 123,
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T10:30:00.000Z",
"message": "ユーザーフィードバック内容",
"userEmail": "user@example.com",
"issues": [
{
"id": 456,
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T10:30:00.000Z",
"name": "バグレポート",
"description": "イシュー説明",
"status": "OPEN",
"externalIssueId": "EXT-123",
"feedbackCount": 5
}
]
},
"channel": {
"id": 1,
"name": "ウェブサイトフィードバック"
},
"project": {
"id": 1,
"name": "My Project"
}
}
}
```
### 2. ISSUE_CREATION
新しいイシューが作成されたときに発生します。
**ペイロード例：**
```json
{
"event": "ISSUE_CREATION",
"data": {
"issue": {
"id": 789,
"createdAt": "2024-01-15T11:00:00.000Z",
"updatedAt": "2024-01-15T11:00:00.000Z",
"name": "新しいイシュー",
"description": "イシュー説明",
"status": "OPEN",
"externalIssueId": "EXT-789",
"feedbackCount": 0
},
"project": {
"id": 1,
"name": "My Project"
}
}
}
```
### 3. ISSUE_STATUS_CHANGE
イシューステータスが変更されたときに発生します。
**ペイロード例：**
```json
{
"event": "ISSUE_STATUS_CHANGE",
"data": {
"issue": {
"id": 789,
"createdAt": "2024-01-15T11:00:00.000Z",
"updatedAt": "2024-01-15T12:00:00.000Z",
"name": "イシュー名",
"description": "イシュー説明",
"status": "IN_PROGRESS",
"externalIssueId": "EXT-789",
"feedbackCount": 3
},
"project": {
"id": 1,
"name": "My Project"
},
"previousStatus": "OPEN"
}
}
```
### 4. ISSUE_ADDITION
フィードバックにイシューが追加されたときに発生します。
**ペイロード例：**
```json
{
"event": "ISSUE_ADDITION",
"data": {
"feedback": {
"id": 123,
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T10:30:00.000Z",
"message": "ユーザーフィードバック内容",
"issues": [
{
"id": 456,
"name": "既存イシュー",
"status": "OPEN"
},
{
"id": 789,
"name": "新しく追加されたイシュー",
"status": "OPEN"
}
]
},
"channel": {
"id": 1,
"name": "ウェブサイトフィードバック"
},
"project": {
"id": 1,
"name": "My Project"
},
"addedIssue": {
"id": 789,
"createdAt": "2024-01-15T11:00:00.000Z",
"updatedAt": "2024-01-15T11:00:00.000Z",
"name": "新しく追加されたイシュー",
"description": "イシュー説明",
"status": "OPEN",
"externalIssueId": "EXT-456",
"feedbackCount": 1
}
}
}
```
---
## ウェブフック受信サーバー実装
ウェブフックを受信するためのHTTPサーバーを実装する必要があります。サーバーは次の要件を満たす必要があります：
### 基本要件
1. **HTTP POSTリクエスト処理**: ウェブフックはHTTP POSTで送信されます
2. **JSONペイロード解析**: リクエスト本文はJSON形式です
3. **200レスポンスコード返却**: 処理成功時は必ず200ステータスコードで応答
### 実装例（Node.js/Express）
```javascript
const express = require('express');
const app = express();
app.use(express.json());
app.post('/webhook', (req, res) => {
const { event, data } = req.body;
const token = req.headers['x-webhook-token'];
// トークン検証
if (token !== 'your-secret-token') {
return res.status(401).json({ error: 'Unauthorized' });
}
// イベント処理
switch (event) {
case 'FEEDBACK_CREATION':
console.log('新しいフィードバック作成:', data.feedback);
// フィードバック処理ロジック
break;
case 'ISSUE_CREATION':
console.log('新しいイシュー作成:', data.issue);
// イシュー処理ロジック
break;
case 'ISSUE_STATUS_CHANGE':
console.log(
'イシューステータス変更:',
data.issue,
'以前のステータス:',
data.previousStatus,
);
// ステータス変更処理ロジック
break;
case 'ISSUE_ADDITION':
console.log('イシュー追加:', data.addedIssue);
// イシュー追加処理ロジック
break;
}
res.status(200).json({ success: true });
});
app.listen(3000, () => {
console.log('ウェブフックリスナーサーバーがポート3000で実行中です。');
});
```
---
## セキュリティと再試行ポリシー
### セキュリティ考慮事項
- **トークン検証**: `x-webhook-token`ヘッダーを通じてリクエストを検証します
- **HTTPS使用**: 本番環境では必ずHTTPSを使用してください
### 再試行ポリシー
- **自動再試行**: ABC User Feedbackはウェブフック送信失敗時に最大3回まで自動再試行します
- **再試行間隔**: 各再試行は3秒後に実行されます
### エラー処理
- **4xxエラー**: クライアントエラーと見なされ、再試行しません
- **5xxエラー**: サーバーエラーと見なされ、再試行します
- **ネットワークエラー**: 接続失敗時に再試行します
---
## 活用事例
### 1. 自動翻訳
```javascript
// FEEDBACK_CREATIONイベントを受信して自動翻訳
if (event === 'FEEDBACK_CREATION') {
const translatedMessage = await translateText(data.feedback.message);
// 翻訳された内容をフィードバックに更新
await updateFeedback(data.feedback.id, { translatedMessage });
}
```
### 2. 外部チケットシステム統合
```javascript
// ISSUE_CREATIONイベントを受信して外部システムにチケット作成
if (event === 'ISSUE_CREATION') {
const ticketId = await createExternalTicket({
title: data.issue.name,
description: data.issue.description,
priority: 'medium',
});
// 外部チケットIDをイシューに保存
await updateIssue(data.issue.id, { externalIssueId: ticketId });
}
```
### 3. 通知システム統合
```javascript
// ISSUE_STATUS_CHANGEイベントを受信してチームに通知
if (event === 'ISSUE_STATUS_CHANGE') {
await sendSlackNotification({
channel: '#feedback-alerts',
message: `イシュー"${data.issue.name}"のステータスが${data.previousStatus}から${data.issue.status}に変更されました。`,
});
}
```
---
## 関連ドキュメント
- [ウェブフック管理](/ja/user-guide/settings/webhook-management) - UIでウェブフックを設定する方法
- [API統合](./02-api-integration.md) - ウェブフックと一緒に使用できるAPI活用
- [イシュー管理](/ja/user-guide/issue-management) - イシューステータス変更イベントの理解
apps/docs/i18n/ja/docusaurus-plugin-content-docs/current/02-developer-guide/_category_.json
+5
View File
@@ -0,0 +1,5 @@
{
"position": 3,
"label": "開発者ガイド"
}
apps/docs/i18n/ja/docusaurus-plugin-content-docs/current/02-developer-guide/index.md
+7
View File
@@ -0,0 +1,7 @@
---
title: 開発者ガイド
---
import DocCardList from '@theme/DocCardList';
<DocCardList />