ken_nogi/Pleasanter/健康診断管理/docs/n8n/design.md

健康診断管理×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を増やしていく