# 健康診断管理×LINEWORKS Bot連携 n8n化 設計書

- 作成日: 2026-09-05
- 対象: プリザンター「健康診断管理」プロジェクト（SiteId 508971）へLINEWORKS Bot経由の対話型ステータス管理機能を実装
- 位置付け: 既存Express実装（`OldCode/express/modules/lineworksSurvey.js`、仕様書`Pleasanter/LINEWORKSアンケート管理/docs/lineworks-survey-scheme.md`）とは別物としてn8nで新規構築。単純な順次質問アンケートではなく、**プリザンターのProcess機能をそのままフロー定義として使うステータス駆動型対話ボット**

## 1. 背景・既存Express実装との違い

Express版（ケアセブンプロジェクト向け）は「アンケート開始→設問を順番に送信→全問回答で1レコードcreate」という一方向の順次アンケートだった。今回の健康診断管理版は要件が異なる。

- 508971は1レコード＝1回の健診。フローは「日程通知→了承/変更→受診確認→結果受取り」のようにレコードのStatusを段階的に進める対話であり、設問の連続ではない
- LINE WORKS Bot APIの制約上、**「トークを開いた瞬間」を検知するイベントは存在しない**（コールバックイベントは`message`/`join`/`leave`/`joined`/`left`/`postback`のみ）。そのため「初期表示切替」は、①Statusが変わった瞬間にBotから能動的にメッセージを送る（プッシュ型）、②ユーザーが何か送信したら現在Statusの案内を返す（フォールバック）、の組み合わせで実現する
- アンケート実行管理・Bot・対象者マスタは新設せず、既存資産を流用する（後述）
- **フロー定義（Statusごとの案内文・選択肢・遷移先）を管理する専用マスタは新設しない。508971自体の`SiteSettings.Processes`（プロセス機能）をそのままフロー定義として使う**
- サーバー実装はExpressでなくn8n。会話の待機状態はn8nプロセスのメモリではなく、n8n Data Table（新規`bot_conversation_state`）で保持する

n8n環境自体の詳細（URL・API・既存ワークフロー・過去の罠）は`NodeSrv/apps/n8n/docs/n8n-guide.md`参照。以下の設計はこのガイドの制約（コンテナメモリ768MB、Data Table操作の罠、Schedule Trigger運用方針等）を踏まえている。

## 2. 前提とした既存資産の流用

| 用途 | 流用元 |
|---|---|
| Bot | 既存「LINEWORKSアンケート管理」プロジェクトのSiteId 484184（LINEWORKS Bot管理）をそのまま参照。健康診断管理側にBotマスタは新設しない |
| 対象者解決 | プリザンター標準Usersのメールアドレスを、そのままLINEWORKS宛先ID（userId）として使う。LINE WORKS側からの受信時も`source.userId`＝メールアドレスという前提で扱う（専用マッピングマスタは不要） |
| 対象レコード特定 | LINEWORKSから届いたメッセージの送信者メール→508971の中で、そのユーザーが紐づくレコードのうち**未完了（Status 900/910以外）の最新レコード**を対象とする。複数該当時の自動判定は行わず、実装上は「複数ヒット」を異常系として扱う |

対象者解決は基本的にプリザンター標準Usersのメールアドレスだけで足りる想定。データ品質の裏付けチェック・補完に社員・組織マスタ管理テーブル（SiteId 504412）を使う件は8章参照（Bot対話フローとは独立した補助機能）。

## 3. 全体アーキテクチャ

```
[プリザンター508971] Statusが変わる契機は2種類
  (a) 担当者がProcessボタンを押す（例:①日程通知発行、日程確定時）
  (b) Bot対話の結果としてProcessが実行される（例:②→③）

(a)の場合
        ▼
n8n: WP「Statusプッシュ通知」(Webhook, 508971クライアントスクリプトから起動)
  └ resultId・processIdを受け取りレコード取得
  └ 該当Processの案内文（ツールチップ欄）をレコード値で置換
  └ 対象者メール解決 → LINEWORKS Bot APIで案内＋選択肢を送信
  └ n8n Data Table「bot_conversation_state」に提示内容を記録
        ▼
LINEWORKS トーク
        │ ユーザー返信（ボタン押下／テキスト／ファイル）
        ▼
n8n: WA「LINEWORKS応答受信」(Webhook、唯一の受信口、署名検証)
  └ 送信者メール解決 → 508971の対象レコード特定
  └ bot_conversation_stateの待機状態を見て回答を処理
  └ 該当Processを`ProcessId`指定でapi/items/updateへ実行 → Status遷移
  └ 遷移後の新Statusに紐づく次のProcess群を取得し、次の案内を送信（WPと共通ロジック）
```

## 4. フロー定義: 508971のProcess機能をそのまま流用

新規マスタサイト・新規テーブルは作らない。プリザンター標準の「プロセス」設定画面（画面種別・現在の状況・変更後の状況・表示名・ツールチップ・入力検証タブ等）を、Bot対話の定義としてそのまま使う。

| Processの項目 | Bot連携での役割 |
|---|---|
| 現在の状況（CurrentStatus）／変更後の状況（ChangedStatus） | 既存のStatus遷移定義をそのまま使う |
| 表示名（DisplayName） | Botが提示する選択肢ボタンのラベル |
| ツールチップ | Bot案内文言。`{検査機関}` `{日程}`のようなプレースホルダーを書いておくと、n8nがレコードの実際の値に置換してから送信する |
| 入力検証タブの「項目」 | このProcess実行に追加入力を伴うかの判定に流用。列名プレフィックスで種別を判定する（`Date*`→日付入力を1往復挟む、`Attachments*`→ファイル受信を1往復挟む、項目なし→即実行） |
| ProcessId | n8nが`POST /api/items/{resultId}/update`に`ProcessId`パラメータとして渡して実行する。公式マニュアル記載の通り、APIからのプロセス実行では入力検証（プリザンター標準の検証機能）は適用されない点に注意 |

新フローを追加する際の運用手順:
1. 508971のProcessを1つ追加（現在の状況・変更後の状況・表示名・ツールチップ文言を設定）
2. 追加入力が必要なら、入力検証タブの「項目」に対象列（`Date*`または`Attachments*`）を登録
3. n8nワークフロー（WP/WA）は無改修。現在Statusに紐づくProcess一覧を都度`getsite`から動的に取得する設計のため、Process追加だけで新フローを反映できる

## 5. n8n側詳細

### Data Table「bot_conversation_state」（新規）

| 列 | 内容 |
|---|---|
| resultId | 508971のResultId |
| targetEmail | 対象者メールアドレス（LINEWORKS userId） |
| currentStatus | 直近提示時点のStatus値 |
| pendingProcesses | 直近提示した選択肢一覧（`[{processId, label, validateColumn}]`のJSON文字列） |
| awaitInput | `none`（選択肢待ち）／`date`（日付入力待ち）／`file`（ファイル受信待ち） |
| awaitProcessId | 追加入力完了後に実行すべきProcessId（`awaitInput`が`date`/`file`の間のみ使用） |
| awaitColumn | 追加入力先の列名（例: `Date001`） |
| updatedAt | 最終更新日時 |

n8n-guide.md 7-1（Clear出力の握り潰し）・7-2（複数行が後続へそのまま渡ると行数分繰り返し実行される）の罠を踏まえ、1レコード=1行の読み書きに限定し、複数行を横断する集約処理は入れない。セッションタイムアウトの概念は持たない（ユーザーの都合のいいタイミングで返信されればよい性質のフローのため、待機状態は無期限に保持する）。

### ワークフロー構成

- **WP Statusプッシュ通知**: Webhookトリガー（`X-API-Key`ヘッダー認証、508971のクライアントスクリプト専用）。担当者がProcessボタンを押した時に起動
- **WA LINEWORKS応答受信**: Webhookトリガー（LINE WORKS本体からの直接コールバック、`x-works-signature`をHMAC-SHA256検証）。唯一の受信口
- タイムアウト監視ワークフローは持たない（3節参照）

### WAの処理詳細

1. 署名検証 → 送信内容（テキスト／ボタン応答／ファイル）を判定
2. 送信者メール解決 → 508971の対象レコード（未完了の最新1件）を特定
3. `bot_conversation_state`から該当resultIdの待機状態を取得
4. **待機状態なし、または`awaitInput=none`で回答が選択肢と不一致** → 現在Statusに紐づくProcess群を`getsite`から再取得し、案内を再送（フォールバック）
5. **`awaitInput=none`で回答が選択肢（DisplayName）と一致**:
   - 対象列なし → 即座に`ProcessId`実行 → 新Statusの次Process群を取得 → 次の案内を送信
   - 対象列が`Date*` → `awaitInput=date`／`awaitProcessId`／`awaitColumn`を記録し、「日付を入力してください」を追加送信（Process実行は保留）
   - 対象列が`Attachments*` → 同様に`awaitInput=file`で保留し、ファイル送信を促す
6. **`awaitInput=date`** → 受信テキストを日付として検証（Express版の和暦・月日省略対応ロジックを踏襲）→ `awaitColumn`をupdate → `awaitProcessId`を`ProcessId`実行 → 新Status提示 → 待機状態を`none`へ戻す
7. **`awaitInput=file`** → 受信がファイルでなければ再送要求。ファイルならLINEWORKS Bot APIでダウンロード → Pleasanter添付ファイルAPIで`awaitColumn`へアップロード → `awaitProcessId`を`ProcessId`実行 → 新Status提示 → 待機状態を`none`へ戻す

### 認証まわり

- LINEWORKS Bot APIメッセージ送信: 既存Credential「LINEWORKS Bot Private Key (v4)」(`Hw0qlEaGfLPnQWp1`)が流用できるか、BotIdとの対応関係を実装時に確認する
- 対象者メール解決: `POST api/users/get`（`View:{ApiGetMailAddresses:true}`）。org-master-sync③で実績のある実装パターンを流用

## 6. エラーハンドリング・異常系

- 対象レコードが複数ヒット（同一ユーザーの未完了レコードが2件以上）→ 自動判定せず、担当者確認が必要な異常系として扱う（Bot応答は保留し、通知等は今後の実装計画で検討）
- 選択肢に一致しない回答 → 選択肢を再提示（4節のフォールバックと同じ経路）
- 日付形式不正／ファイル未送信 → エラーメッセージ＋再送、待機状態は維持
- LINEWORKS送信失敗・508971 update失敗 → n8n Execution History（Postgres保存）に残す。追加のログ実装はしない

## 7. 導入・検証方針

- n8n運用ルール（n8n-guide.md 9章）に従い、ワークフローの構築・編集自体は確認不要。**Webhook実行によるプリザンター書き込み・LINEWORKS送信を伴うテストは都度事前確認**
- 初回検証は1Process・1件のみで実施し、疎通確認後にフロー全体（①〜③）の通し検証に進める
- 508971は本番の健診データそのものなので、検証は既存レコードを壊さない捨てレコードを用意して行う

## 8. 補助機能（Bot対話フローとは独立）: 社員マスタ(504412)によるデータ品質チェック・補完

3〜7章のBot対話フローとは関係のない、508971のデータ品質を担保するための補助機能。n8nのHC-SUB/HC-WP/HC-WAワークフローには組み込まず、別途の仕組み（バッチ・Pleasanter Process/ServerScript等、実装方式は別途検討）として扱う。

社員・組織マスタ管理テーブル（SiteId 504412、2章参照）の列構成（`NodeSrv/apps/org-master-sync/configs/site-504412_社員・組織マスタ管理テーブル/`で取得済み）:

| 504412の列 | 内容 |
|---|---|
| `Class011` | ユーザID（PleasanterUserId） |
| `ClassB` | メールアドレス |
| `Class036` | PLメールアドレス |
| `Class003` / `Class004` | 姓（カナ）／名（カナ） |

- **メールアドレス整合性チェック**: 508971の`ClassC`（Users参照）から解決した対象者のPleasanterUserIdを軸に504412の`Class011`と突き合わせ、その社員の`Class036`（PLメールアドレス）と、`api/users/get`で解決した実際のメールアドレスが一致するかを検証する
- **フリガナ補完**: 508971の`ClassD`（フリガナ、必須項目）が空欄の場合、504412の`Class003`（姓（カナ））＋`Class004`（名（カナ））から補完する

## 9. 未確定事項（実装時に個別確定）

- 具体的なProcess定義（①日程通知〜③検査結果受取りの各Process内容、Status値の追加・修正）は508971のStatus設計がまだ未完成のため、実装着手時に個別に設計する
- LINEWORKS Bot Private Key CredentialとBotId（484184側）の対応関係の実機確認
- LINEWORKS Bot APIでのファイル受信（ダウンロードURL取得）とPleasanter添付ファイルAPIへのアップロードの具体的な実装方法
- 今後フロー内容の詳細が追加判明する前提のため、4節の枠組み（Process流用）の汎用性を保ったまま個別Processを増やしていく