# バッチ設計書 28-lookup-user.ts

## 概要

本ドキュメントは、ユーザー情報を検索・表示する管理スクリプトの設計を記載したバッチ設計書です。

### 本バッチの処理概要

lookup-user.tsは、メールアドレスまたはワークスペースIDを指定して、ユーザーに関連する詳細情報をデータベースから取得し、コンソールに表形式で表示する管理スクリプトです。カスタマーサポートや運用チームがユーザー状況を確認する際に使用されます。

**業務上の目的・背景**：ZEN APIのサポート業務では、ユーザーからの問い合わせに対応するため、アカウント情報、ワークスペース、課金状況、サブスクリプション、支払い履歴などを迅速に確認する必要があります。本スクリプトにより、管理者はデータベースクエリを直接実行することなく、必要な情報を一覧表示できます。

**バッチの実行タイミング**：管理者による手動実行。カスタマーサポート対応、アカウント調査、課金問題の確認時に使用されます。

**主要な処理内容**：
1. コマンドライン引数からメールアドレスまたはワークスペースIDを取得
2. ワークスペースID指定の場合は直接ワークスペース情報を表示
3. メールアドレス指定の場合は認証情報から関連ワークスペースを検索
4. 各ワークスペースについて以下を表示：
   - ユーザー一覧（メール、ロール、最終アクセス、月次利用状況、サブスクリプション状態）
   - 課金情報（残高、Stripe顧客ID、リロード設定、サブスクリプション詳細）
   - 支払い履歴（最新100件）

**前後の処理との関連**：読み取り専用のスクリプトであり、他のバッチとの依存関係はありません。

**影響範囲**：データベースへの読み取りアクセスのみで、データの変更は行いません。

## バッチ種別

情報照会 / カスタマーサポート支援

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（手動） |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | 管理者による手動実行 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| データベース接続 | Database.useが機能すること |
| 検索対象存在 | 指定したメールアドレスまたはワークスペースIDが存在すること |

### 実行可否判定

- identifierが指定されていること
- メールアドレスの場合はAuthTableに存在すること

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| identifier | string | Yes | - | メールアドレスまたはワークスペースID（wrk_で始まる） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| AuthTable | DB | 認証情報（メールとアカウントの紐付け） |
| UserTable | DB | ユーザー情報 |
| WorkspaceTable | DB | ワークスペース情報 |
| BillingTable | DB | 課金情報 |
| PaymentTable | DB | 支払い履歴 |
| SubscriptionTable | DB | サブスクリプション情報 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| console.log | Text | 整形されたテーブル出力 |
| console.table | Table | データ一覧表示 |
| console.warn | Text | 警告メッセージ |
| console.error | Text | エラーメッセージ |

### 出力ファイル仕様

ファイル出力なし

| 項目 | 内容 |
|-----|------|
| ファイル名 | - |
| 出力先 | - |
| 文字コード | - |
| 区切り文字 | - |

## 処理フロー

### 処理シーケンス

```
1. 引数検証
   └─ process.argv[2]からidentifier取得
   └─ 未指定の場合Usage表示して終了
2. 識別子タイプ判定
   └─ wrk_で始まる場合：ワークスペースID
   └─ それ以外：メールアドレス
3. [メールアドレスの場合]
   └─ AuthTableからsubject=identifierで検索
   └─ 見つからない場合エラー終了
   └─ 複数ある場合警告表示
   └─ accountIDから関連ワークスペース一覧取得
4. [ワークスペースIDの場合]
   └─ 直接printWorkspace()呼び出し
5. printWorkspace()
   └─ ヘッダー表示
   └─ Users表：ユーザー情報、ロール、月次利用状況、サブスクリプション状態
   └─ Billing表：残高、顧客ID、リロード設定、サブスクリプション詳細
   └─ Payments表：支払い履歴（最新100件）
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B{引数あり?}
    B -->|No| C[Usage表示]
    C --> D[process.exit 1]
    B -->|Yes| E{wrk_で始まる?}
    E -->|Yes| F[printWorkspace直接呼出]
    E -->|No| G[AuthTable検索]
    G --> H{メール存在?}
    H -->|No| I[Error: Email not found]
    I --> D
    H -->|Yes| J{複数アカウント?}
    J -->|Yes| K[警告表示]
    K --> L[Auth表表示]
    J -->|No| L
    L --> M[関連ワークスペース取得]
    M --> N[各ワークスペースをループ]
    N --> F
    F --> O[ヘッダー表示]
    O --> P[Users表表示]
    P --> Q[Billing表表示]
    Q --> R[Payments表表示]
    R --> S{次のワークスペース?}
    S -->|Yes| N
    S -->|No| T[バッチ終了]
```

## データベース操作仕様

### 操作別データベース影響一覧

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 認証情報取得 | AuthTable | SELECT | メールアドレスから検索 |
| ワークスペース一覧 | UserTable, WorkspaceTable | SELECT | アカウントに紐づくワークスペース |
| ユーザー情報取得 | UserTable, AuthTable, SubscriptionTable | SELECT | ワークスペースのユーザー詳細 |
| 課金情報取得 | BillingTable | SELECT | 残高・サブスクリプション情報 |
| 支払い履歴取得 | PaymentTable | SELECT | 最新100件 |

### テーブル別操作詳細

#### AuthTable

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | subject, accountID, provider | WHERE subject = identifier | メール検索 |
| SELECT | subject | WHERE accountID = ? AND provider = 'email' | ユーザー表示用 |

#### UserTable

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, workspaceID, accountID, role, email, timeSeen, monthlyLimit, monthlyUsage, timeDeleted | WHERE accountID = ? / WHERE workspaceID = ? | - |

#### WorkspaceTable

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, name | WHERE id = ? | - |

#### BillingTable

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | balance, customerID, reload, subscriptionID, subscriptionPlan, subscription, timeSubscriptionBooked, timeSubscriptionSelected | WHERE workspaceID = ? | - |

#### SubscriptionTable

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | timeCreated, fixedUsage, rollingUsage, timeFixedUpdated, timeRollingUpdated | WHERE userID = ? | - |

#### PaymentTable

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | amount, paymentID, invoiceID, customerID, timeCreated, timeRefunded | WHERE workspaceID = ? ORDER BY timeCreated DESC LIMIT 100 | - |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 引数不足 | identifier未指定 | Usageを確認して再実行 |
| - | メール不存在 | 指定メールがAuthTableにない | 正しいメールアドレスを指定 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

- process.exit(1)で異常終了
- データベースエラー時は例外スロー

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 各クエリ単位（読み取り専用） |
| コミットタイミング | - |
| ロールバック条件 | - |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1ユーザー/実行 |
| 目標処理時間 | 数秒 |
| メモリ使用量上限 | 制限なし |

## 排他制御

- 読み取り専用のため排他制御不要
- 並列実行可能

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | - | - |
| 進捗ログ | - | - |
| 終了ログ | - | - |
| エラーログ | エラー時 | console.error メッセージ |
| 警告ログ | 複数アカウント時 | console.warn メッセージ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| - | - | - |

## 備考

- 金額表示はマイクロセントからドルに変換（/ 100000000）
- 日付表示はISO形式の日付部分のみ（YYYY-MM-DD）
- 削除済みユーザーはメールアドレスの先頭に「❌ 」を付与
- 支払い履歴のpaymentIDはStripeダッシュボードURLに変換
- Blackサブスクリプションの週次/ローリング使用量と制限状態を計算して表示
- retryIn（再試行可能時間）を日・時間・分形式で表示
