8e8bbcde6e
Express実装(ケアセブン向け)をn8nへ作り直すにあたり、健康診断管理 プロジェクト固有の要件(508971へ統合、既存Bot/Usersマスタ流用、 n8n Data Tableでのセッション管理)を反映した設計をbrainstormingで まとめた。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
121 lines
8.8 KiB
Markdown
121 lines
8.8 KiB
Markdown
# 健康診断管理×LINEWORKSアンケート n8n化 設計書
|
||
|
||
- 作成日: 2026-09-05
|
||
- 対象: プリザンター「健康診断管理」プロジェクト（SiteId 508971）へLINEWORKS Bot経由アンケート機能を実装
|
||
- 位置付け: 既存Express実装（`OldCode/express/modules/lineworksSurvey.js`、仕様書`Pleasanter/LINEWORKSアンケート管理/docs/lineworks-survey-scheme.md`）と同等機能をn8nで新規構築。Expressの流用・移植ではなく作り直し
|
||
|
||
## 1. 背景・既存Express実装との違い
|
||
|
||
Express版（ケアセブンプロジェクト向け）は以下の構成だった。
|
||
|
||
- 「アンケート実行管理」を独立サイト（484186）として持ち、対象テーブル（例: 車両点検報告484182）へ回答を新規レコードcreateする
|
||
- Bot・対象者マスタも専用サイト（484184/484181）を新設
|
||
- セッション状態はExpressプロセスのメモリ（`Map`）で保持
|
||
|
||
今回の健康診断管理版は要件が異なるため、以下の方針で作り直す。
|
||
|
||
- **アンケート実行管理を独立サイトにせず、508971自体に統合**（Process＋列追加）。回答は新規レコードcreateではなく、発行元の508971レコード自体へupdateで書き戻す
|
||
- **Botマスタは新設せず、既存の「LINEWORKSアンケート管理」プロジェクトのSiteId 484184をそのまま参照**
|
||
- **対象者マスタは新設せず、プリザンター標準Usersのメールアドレスをそのまま LINEWORKS の宛先ID（userId）として使う**（LINEWORKS ID＝メールアドレスという前提。484181のような変換用マスタは不要）
|
||
- **サーバー実装はExpressでなくn8n**。セッション状態はn8nプロセスのメモリではなく、n8n Data Table（新規テーブル `survey_sessions`）で保持する
|
||
|
||
n8n環境自体の詳細（URL・API・既存ワークフロー・過去の罠）は`NodeSrv/apps/n8n/docs/n8n-guide.md`参照。以下の設計はこのガイドの制約（コンテナメモリ768MB、Data Table操作の罠、Schedule Trigger運用方針等）を踏まえている。
|
||
|
||
## 2. 全体アーキテクチャ
|
||
|
||
```
|
||
プリザンター(508971 健康診断管理データ本体)
|
||
└ Process「アンケート発行」ボタン（flowIdごとに1つ）
|
||
│ クライアントスクリプト fetch
|
||
▼
|
||
n8n: W1「健診アンケート開始」(Webhook)
|
||
└ resultId取得 → ClassC(Users参照列)からPleasanterUserId解決
|
||
└ POST api/users/get（View:{ApiGetMailAddresses:true}）でメールアドレス取得
|
||
→ LINEWORKS userIdとしてそのまま使用
|
||
└ 508971自身のColumnsからflowId該当設問を抽出
|
||
└ n8n Data Table「survey_sessions」へセッション行Insert
|
||
└ 484184(LINEWORKS Bot)から該当BotId取得 → LINEWORKS Bot APIで第1問送信
|
||
│
|
||
▼
|
||
LINEWORKS トーク（Bot⇔対象者）
|
||
│ 回答
|
||
▼
|
||
n8n: W2「健診アンケート回答受信」(Webhook, 署名検証)
|
||
└ targetId(=メール)でsurvey_sessions検索 → 型検証 → 回答蓄積
|
||
└ 未完了 → 次設問送信 / セッション更新
|
||
└ 完了 → 508971へupdate（Hashネスト）→ アンケート進捗列更新 → セッション削除
|
||
|
||
n8n: W3「健診アンケートタイムアウト監視」(Schedule Trigger、数分毎)
|
||
└ survey_sessions走査 → 期限切れセッションに終了通知 → 削除
|
||
```
|
||
|
||
## 3. プリザンター側（508971）変更点
|
||
|
||
| 追加項目 | 内容 |
|
||
|---|---|
|
||
| 設問対象列 | アンケートで使う列の`ExtendedControlCss`に`survey survey-<flowId>`トークンを付与。1列が複数flowに属してもよい（スペース区切りで複数トークン） |
|
||
| アンケート進捗列（新規、列名は実装時に採番） | アンケートの発行・回答状況を管理する専用列。既存業務Status（100申込中〜910対象外）とは別軸で持つ |
|
||
| Process「アンケート発行」 | flowIdごとに1つずつ追加。`OnClick`でn8n WebhookのW1へPOST（`resultId`・`flowId`を送信） |
|
||
| ClassC（Users参照、既存） | そのまま流用。ここからPleasanterUserIdを取得し、n8n側でメールアドレスを解決する |
|
||
|
||
新規アンケート（flowId）を追加する際の運用手順:
|
||
1. 該当列の`ExtendedControlCss`に`survey-<新flowId>`トークンを追記（既存列流用 or 新規列追加はflow内容次第で都度判断）
|
||
2. 508971にProcess「◯◯アンケート発行」を追加、`flowId`を固定値でn8n Webhookへ渡すよう設定
|
||
3. n8n側の設問抽出ロジックは`ExtendedControlCss`のトークンでflowIdを判定するため、n8nワークフロー自体の改修は不要（列追加・Process追加のみで新flowを増やせる設計）
|
||
|
||
アンケート進捗列の具体的な値・遷移（業務Statusとの整合を取るか等）は、実際のアンケートフロー内容を設計する際に個別に確定する。本設計書では「既存業務Statusとは独立した列で管理する」という方針のみを定める。
|
||
|
||
## 4. n8n側詳細
|
||
|
||
### Data Table「survey_sessions」（新規作成）
|
||
|
||
| 列 | 内容 |
|
||
|---|---|
|
||
| sessionId | UUID |
|
||
| resultId | 508971のResultId |
|
||
| flowId | アンケート種別識別子 |
|
||
| botId | 484184から取得したBotId |
|
||
| targetEmail | 対象者メールアドレス（LINEWORKS userId） |
|
||
| currentIndex | 現在の設問番号 |
|
||
| answersJson | ここまでの回答（JSON文字列） |
|
||
| expiresAt | 現在設問のタイムアウト時刻 |
|
||
| startedAt | 開始日時（無応答タイムアウト判定用） |
|
||
| firstAnswerAt | 初回応答有無判定用 |
|
||
|
||
n8n-guide.md 7-1（Clear出力の握り潰し）・7-2（複数行が後続へそのまま渡ると行数分繰り返し実行される）の罠を踏まえ、1セッション=1行の読み書きに限定し、複数セッションを一括で展開・集約する処理は入れない。
|
||
|
||
### ワークフロー構成
|
||
|
||
- **W1 開始**: Webhookトリガー（`X-API-Key`ヘッダー認証、508971のクライアントスクリプト専用）
|
||
- **W2 回答受信**: Webhookトリガー（LINEWORKS本体からの直接コールバック、`x-works-signature`をHMAC-SHA256検証。Express版`verifyWebhookSignature`と同等ロジック）
|
||
- **W3 タイムアウト監視**: Schedule Trigger（数分間隔）。n8n-guide.md 9章では「Schedule Trigger等の自動化は今回のスコープ外」としているが、**本機能ではセッションタイムアウト監視のために自動実行を解禁する**（今回の設計で追加する例外）
|
||
|
||
### 認証まわり
|
||
|
||
- LINEWORKS Bot APIメッセージ送信: 既存Credential「LINEWORKS Bot Private Key (v4)」(`Hw0qlEaGfLPnQWp1`)が流用できるか、実装時にBotIdとの対応関係を確認する
|
||
- 対象者メール解決: `POST api/users/get`（`View:{ApiGetMailAddresses:true}`、Offset+TotalCountページング）。org-master-sync③で実績のある実装パターンをそのまま使う
|
||
|
||
## 5. 設問の型・検証ルール
|
||
|
||
Express版（選択式／数値／自由記述の3種、日付は和暦・月日省略に対応）と同等の検証ロジックをn8n上（Codeノード）に再実装する。列名プレフィックスによる型判定（`Class*`→選択式 or 短文、`Num*`→数値、`Date*`→日付、`Description*`→長文）もExpress版を踏襲する。
|
||
|
||
## 6. エラーハンドリング・異常系
|
||
|
||
- キャンセルキーワード（取消/キャンセル/終了等）受信 → セッション削除＋508971のアンケート進捗列を「キャンセル」相当へ
|
||
- 必須設問での無回答・スキップ要求 → 再送（同じ設問を再送信）
|
||
- 型検証失敗（数値・日付フォーマット不正）→ エラーメッセージ＋再送
|
||
- セッション未検出（期限切れ後の回答等）→ 「アンケートが開始されていません」を返信
|
||
- LINEWORKS送信失敗・508971 update失敗 → n8n Execution History（Postgres保存）に残す。追加のログ実装はしない
|
||
|
||
## 7. 導入・検証方針
|
||
|
||
- n8n運用ルール（n8n-guide.md 9章）に従い、ワークフローの構築・編集自体は確認不要。**Webhook実行によるプリザンター書き込み・LINEWORKS送信を伴うテストは都度事前確認**
|
||
- 初回検証は1flow・1件のみで実施し、疎通確認後に複数flow展開へ進める
|
||
- 508971は本番の健診データそのものなので、検証は既存レコードを壊さない捨てレコードを用意して行う
|
||
|
||
## 8. 未確定事項（今後のflow設計時に個別確定）
|
||
|
||
- アンケートflowの具体的な設問内容・対象列・flowId命名は本設計書のスコープ外。flow追加のたびに3章の運用手順に従って個別設計する
|
||
- アンケート進捗列の具体的な値・遷移
|
||
- LINEWORKS Bot Private Key CredentialとBotIdの対応関係の実機確認
|