Python / PySide6 / Playwright を使用して、複数部署のCCP応答率を監視し、状態変化および定時報告をMicrosoft Teams Webへ自動投稿するWindows向けRPAを作成してください。
単なる試作品ではなく、今後部署数やTeams送信先が増えてもGUI設定だけで拡張できる構造にしてください。
巨大な1ファイルへ全部詰め込まず、責務ごとに適切に分割してください。
1. 使用技術
-
Python
-
PySide6
-
Playwright
-
Google Chrome
-
Chrome DevTools Protocol(CDP)
-
Chrome専用リモートデバッグポート:9500
-
PyAutoGUI
-
ctypes / Windows API
-
queue.Queue等によるTeams送信キュー
Microsoft Graph API等は使用しません。
Teamsへの投稿はWeb版TeamsをPlaywrightで操作して行います。
PyAutoGUIはWebページ操作には使用せず、Chrome本体が表示する外部アプリ起動確認ダイアログへESCを送信する用途だけに限定してください。
2. 全体構成
システムを以下の責務に分けてください。
-
GUI
-
設定管理
-
Chrome / CCP起動
-
CCP監視
-
状態判定
-
15分値保持
-
1時間定時報告生成
-
発報イベント生成
-
配信ルール判定
-
Teams送信キュー
-
Teams Web操作
PlaywrightのPageやContextを異なるスレッド間で直接共有しないでください。
各WorkerがPlaywrightを使用する場合、そのWorker自身でPlaywrightを開始し、CDPへ接続してください。
GUI更新はSignalを使用し、Workerから直接PySide6 GUI部品を変更しないでください。
3. GUI基本構成
PySide6でタブ式GUIを作成してください。
タブは以下の4つです。
-
稼働状況
-
監視対象
-
Teams送信先
-
配信ルール
GUI上部または稼働状況タブに、
-
CCP起動
-
監視開始
-
監視停止
を設置してください。
「CCP起動」と「監視開始」は別処理にしてください。
4. 稼働状況タブ
各監視対象を1行として表示してください。
表示項目:
-
有効/無効
-
部署名
-
現在の応答率
-
現在状態 UNDER / OVER
-
最終発火
-
15分クールダウン残時間
-
最終取得時刻
画面上部には、
-
CCP接続状態
-
監視状態
-
Teams送信Worker状態
-
次回CCP取得までのカウントダウン
も表示してください。
CCP取得間隔は初期値5秒です。
GUIでは、
5.0 → 4.9 → … → 0.0 → 5.0
のように次回取得までの残時間が見えるようにしてください。
5. 監視対象タブ
監視対象をGUIから追加・削除・編集可能にしてください。
初期サンプルとして、
-
CSR
-
部署A
-
部署B
-
部署C
-
部署D
-
全体
の6対象を登録してください。
「全体」も特別扱いせず、通常の監視対象1件として扱ってください。
監視対象には最低限以下を持たせてください。
-
enabled
-
name
-
threshold
-
CCP内タブを開くための情報
-
応答率取得用Locator / selector
-
polling interval
例:
{
"enabled": true,
"name": "CSR",
"threshold": 90.0,
"tab_selector": "...",
"rate_selector": "...",
"poll_interval": 5
}
部署数をコードへ固定しないでください。
GUIで行を追加すれば7部署、10部署へ増やせる構造にしてください。
6. CCP画面
Chromeを専用ポート9500で起動します。
起動時には専用user-data-dirを使用してください。
すでに9500番ポートのChromeが存在する場合は再利用してください。
CCP URLは設定値として管理してください。
「CCP起動」ボタン:
-
9500番ポートを確認
-
Chromeがなければ起動
-
CCP URLを開く
-
既にCCPタブが存在する場合は重複して開かない
-
CCP画面を表示
「監視開始」ボタン:
-
9500番ChromeへPlaywrightでconnect_over_cdp
-
CCPページを取得
-
有効な監視対象を読み込む
-
監視を開始
7. 複数部署の監視
複数部署は同一ブラウザタブ内のWebアプリ内タブとして存在する想定です。
各監視対象について、
-
必要ならアプリ内タブをPlaywrightで選択
-
対象DOMが表示されるまで待つ
-
応答率を取得
-
数値化
-
状態判定
を順番に行ってください。
DOMがすべて同時に存在していて直接取得可能な場合は、不要なタブ切替を行わない設計でも構いません。
監視対象を200件程度まで増やしても、状態保持部分が問題にならない構造にしてください。
個別の変数を大量に作らず、辞書またはdataclass等で管理してください。
8. 応答率状態判定
監視対象ごとにthresholdを持たせます。
初期値は90%。
判定:
rate < threshold
→ UNDER
rate >= threshold
→ OVER
最初に取得した状態はreference_statusとして記憶するだけで、起動直後には発火しないでください。
9. 状態変化による発火
通常状態:
OVER → UNDER
→ アンダー発火
UNDER → OVER
→ オーバー発火
同じ状態が続く場合は発火しません。
各監視対象は独立したreference_statusを持ってください。
10. 15分クールダウン
本番仕様として15分クールダウンを実装してください。
どちらかの発火が発生したら、その監視対象について15分間は、
-
アンダー発火
-
オーバー発火
の両方を禁止してください。
ただしCCP監視自体は5秒ごとに継続します。
クールダウン中も現在状態へreference_statusを追従させてください。
つまり、
-
発火
-
15分クールダウン開始
-
CD中にUNDER/OVERが変化しても発火しない
-
reference_statusは現在状態へ更新
-
CD終了
-
CD終了時点の状態を基準状態とする
-
その後、再び状態が変化した時だけ次の発火
という動作にしてください。
クールダウン状態はメモリ上だけで構いません。
11. 永続化方針
運用ログは原則保存しません。
DBも不要です。
保存するのはGUI設定だけです。
設定はconfig.json等へ保存してください。
保存対象例:
-
CCP URL
-
Chrome関連設定
-
監視対象
-
閾値
-
selector
-
Teams送信先
-
Teams URL
-
メンション
-
配信ルール
-
発報文テンプレート
保存しないもの:
-
5秒ごとの応答率ログ
-
過去の発報履歴
-
過去の定時報告
-
運用時系列ログ
RPA再起動により当該時間帯の15分値が欠けても問題ありません。
欠損値を過去ログから復元しようとしないでください。
12. Teams送信先タブ
Teams送信先をGUIから追加・削除・編集可能にしてください。
項目:
-
enabled
-
name
-
Teams URL
-
mention
-
用途
例:
{
"enabled": true,
"name": "CSR管理",
"url": "https://teams...",
"mention": "@1",
"usage": "部署用"
}
mentionは任意入力可能にしてください。
例:
-
@1
-
@zazi
-
空欄
空欄ならメンションなしで本文だけ投稿してください。
基本運用では「@1 → Enter」によって全員メンションを確定する想定です。
13. 配信ルールタブ
「どの監視対象の通知を、どのTeams送信先へ送るか」をGUIで設定可能にしてください。
例:
CSR管理 部署A管理 全体管理
CSR ON OFF ON
部署A OFF ON ON
部署B OFF OFF ON
全体 OFF OFF ON
監視対象名やTeams送信先が変更されたら、配信ルール表も再構築可能にしてください。
可能であれば、
-
閾値発報
-
1時間定時報告
の配信ルールを別々に設定できる構造にしてください。
14. 発報文テンプレート
文言をコードへ固定しないでください。
GUIまたはconfig.jsonから編集可能にしてください。
テンプレートには以下の変数を利用可能にすると望ましいです。
{name}
{rate}
{threshold}
初期例:
UNDER:
【{name}】
応答率が{threshold}%を下回りました。
現在:{rate}%
OVER:
【{name}】
応答率が{threshold}%以上に回復しました。
現在:{rate}%
15. Teams発報キュー
同じ内容を複数Teamsチャットへ送る場合があります。
Teams操作を並列実行しないでください。
理由:
Chrome本体へのESC送信およびWindowsのForeground制御を使用するためです。
発火したら、
-
配信ルールから送信対象を抽出
-
Teams送信Jobを生成
-
queueへ追加
-
TeamsWorkerが1件ずつ順番に処理
してください。
Job例:
{
"target_name": "...",
"url": "...",
"mention": "@1",
"message": "...",
"source": "CSR",
"event_type": "UNDER"
}
監視処理とTeamsWorkerは分離し、Teams画面の読み込み中でもCCP監視を止めないでください。
16. Teams Web操作フロー
Teams送信Jobを1件処理するときは以下の順番です。
-
Playwrightで9500番ChromeへCDP接続
-
新規Teamsタブを作成
-
JobのTeams URLを開く
-
Teamsタブをbring_to_front
-
約0.5秒待つ
-
Windows APIで対象ChromeウィンドウをForeground / Active化
-
Chrome本体の「Microsoft Teamsを開きますか?」へPyAutoGUIでESC
-
Webページ内の「このブラウザーで続ける」をクリック
-
Teamsメッセージ入力欄がvisibleになるまで待機
-
設定されたmentionを入力
-
Enterでメンション候補を確定
-
Shift+Enterで改行
-
本文を入力
-
Enterで送信
-
少し待つ
-
今回開いたTeamsタブだけ閉じる
-
次のJobへ進む
Webページ内部の操作はPlaywrightを使用してください。
17. 現在確認済みTeams selector
「このブラウザーで続ける」:
button[data-tid="joinOnWeb"]
入力欄:
div[data-tid="ckeditor"][contenteditable="true"][aria-label="メッセージを入力"]
Teamsの入力欄は動的なidが付与されるため、動的idはselectorとして使用しないでください。
data-tid、aria-label、role等の比較的安定した属性を優先してください。
18. Chrome外部アプリ確認ダイアログ
「Microsoft Teamsを開きますか?」はWebページDOMではありません。
Playwright locatorで操作しようとしないでください。
以下で処理してください。
-
teams_page.bring_to_front()
-
約0.5秒待機
-
ctypes / Windows APIで対象ChromeウィンドウをForeground化
-
Foregroundになったことを確認
-
pyautogui.press("esc")
page.bring_to_front()だけではOS上のChromeウィンドウがアクティブになる保証がないため、Windows APIによる前面化処理を入れてください。
19. メンション入力
mentionが空欄ではない場合:
-
editor.click()
-
mention文字列を入力
-
Teamsの候補表示を少し待つ
-
Enter
-
少し待つ
-
Shift+Enter
-
本文入力
mentionが空欄の場合:
メンション操作を行わず、本文を直接入力してください。
Python版PlaywrightではLocator.insert_text()を使用せず、必要に応じて、
page.keyboard.insert_text(message)
を使用してください。
20. Teams操作エラー
Teams操作が失敗してもCCP監視は停止させないでください。
Teams送信失敗:
-
GUIへエラー表示
-
当該Teamsタブはデバッグしやすいよう残す
-
次のJobを継続可能な設計にする
CCP監視そのものが失敗した場合は監視エラーとしてGUIへ表示してください。
21. 15分刻み値
5秒ごとの応答率はログ保存しません。
各監視対象について、メモリ上に当該時間帯の代表値だけ保持してください。
保持する時刻:
-
xx:00
-
xx:15
-
xx:30
-
xx:45
各時刻に最も近い直近取得値を使用してください。
例:
{
"09:00": 90,
"09:15": 89,
"09:30": 91,
"09:45": 90
}
次の時間帯へ移行したら、前時間帯の報告完了後に不要な値をクリアしてください。
22. 1時間定時報告
毎時00分になったら、直前の1時間についてTeamsへ状況報告してください。
例:
10:00になった場合は「9時台」を報告します。
形式:
【9時台 CSR応答率】
09:00 90% | 09:15 ⚠89%
09:30 91% | 09:45 90%
▶ 現在 90%
threshold未満だった値だけ、
⚠
を付けてください。
例:
89%
→ ⚠89%
欠損している時間帯は無理に復元せず、
--
等で表示してください。
現在値は報告時点で保持している最新値を使用してください。
この定時報告も配信ルールを通し、設定された複数Teams送信先へTeamsキュー経由で順番に送信してください。
Teams側に投稿履歴が残るため、過去時間帯を次回投稿へ再掲する必要はありません。
23. 二重定時報告防止
5秒ループのため、毎時00分条件が複数回成立する可能性があります。
メモリ上に、
last_report_hour
等を保持し、同じ時間帯の定時報告を複数回送らないようにしてください。
永続化は不要です。
24. 状態管理
各監視対象について少なくとも以下を保持してください。
-
current_rate
-
current_status
-
reference_status
-
cooldown_until
-
last_trigger
-
quarter_values
-
last_read_time
監視対象ごとの状態を別々のPython変数として大量に作らず、
dict
dataclass
等でまとめてください。
25. 設定と実行状態を分離
設定値と実行中の状態を混在させないでください。
例えば、
MonitorConfig
MonitorState
TeamsTargetConfig
TeamsJob
のように明確に分けてください。
26. GUIから設定保存
GUIへ、
「設定保存」
ボタンを用意してください。
config.jsonへ保存してください。
起動時にはconfig.jsonを読み込みます。
config.jsonが存在しない場合のみ初期サンプル設定を生成してください。
運用ログは作成しないでください。
27. 推奨ファイル構成
例:
ccp_monitor/
main.py
gui.py
models.py
config_manager.py
chrome_manager.py
monitor_worker.py
teams_worker.py
routing.py
reporter.py
config.json
requirements.txt
README.md
必要に応じて変更して構いませんが、責務分離は維持してください。
28. 重要な設計思想
以下を必ず守ってください。
Webページ内部
→ Playwright
Chrome本体UI
→ PyAutoGUI
Windowsウィンドウ制御
→ ctypes / Windows API
監視結果保持
→ メモリ上の状態変数
設定
→ config.json
Teams複数送信
→ Queueで直列処理
CCP監視
→ Teams処理中も継続
部署数
→ ハードコードしない
Teams送信先数
→ ハードコードしない
29. 実装手順
いきなり巨大コードを作らず、以下の順序で実装してください。
Phase 1
-
プロジェクト構造
-
dataclass
-
config.json
-
GUI
Phase 2
-
Chrome 9500起動
-
CCP接続
-
単一監視対象取得
Phase 3
-
複数監視対象
-
UNDER / OVER
-
15分CD
-
GUI状態反映
Phase 4
-
Teams送信Worker
-
Queue
-
複数送信先
-
メンション
Phase 5
-
配信ルール
Phase 6
-
15分値
-
1時間定時報告
Phase 7
-
エラー処理
-
再接続
-
README
-
最終整理
各Phase終了時に既存機能を壊していないか確認してください。
30. 完成条件
最低限以下が確認できれば完成です。
-
CCP起動と監視開始が別ボタン
-
複数監視対象をGUI設定できる
-
5部署+全体を同時管理できる
-
各対象の現在応答率がGUIへ表示される
-
UNDER / OVERが対象ごとに独立
-
状態変化時のみ発火
-
発火後15分CD
-
CD中も監視継続
-
複数Teams送信先をGUI管理
-
送信先ごとにURL設定
-
送信先ごとにメンション設定
-
配信ルール設定
-
Teams送信を直列Queue処理
-
Teams処理中もCCP監視継続
-
15分代表値をメモリ保持
-
毎時、直前1時間の状況報告
-
ログファイルを蓄積しない
-
設定のみconfig.jsonへ保存
-
エラーがGUIで分かる
-
Teams投稿失敗で監視全体が停止しない
31. 実装時の姿勢
不明なDOM selectorを勝手に推測して完成したことにしないでください。
実際のCCP画面で確認が必要なselectorには分かりやすくTODOを残してください。
Teamsについては、この仕様内で提示している確認済みselectorを優先してください。
実装後は、
-
作成したファイル一覧
-
各ファイルの責務
-
起動方法
-
必要pipパッケージ
-
config.jsonの構造
-
実機で差し替える必要があるCCP selector
-
現在実装済み機能
-
未確認箇所
を報告してください。
可能な範囲で実際にsyntax checkを行い、明らかなPythonエラーを残さないでください。