support-ticket

サポートチケットのワークフロー

技術者にも、技術に詳しくないユーザーにも利用できます。誰でも手順 1～3 を実行して、トリアージし、データを依頼し、クライアントへの返信を作成できます。手順 4～5（カスタマイズの除外と修正）には開発者が必要ですが、技術に詳しくないユーザーも、明確な回答が得られた時点、または返信案を作成した時点で作業を止められます。

入力：チケット番号（課題とメールのやり取りを取得）または貼り付けた課題の説明のいずれかです。画像や xlsx/csv ファイルなどの添付ファイルも取得し、動画は無視してください。

調査を始める前に、チケット番号を見える場所（セッション名／タスク名）に記録して、スレッドを見つけやすくしておいてください。

**一度きりではなく、反復して進めます：**分類 → データを依頼 → 分析 → さらに深く調査 → カスタマイズを除外、という流れを、根本原因が特定できるまで繰り返します。データのやり取りは何度か発生する想定です。その後に初めて修正します（手順 5）。

セッションのルール：

• **クライアントが使えるのは Desk のみです。**SSH、bench コマンド、サーバーログ、ファイルシステムにはアクセスできません。System Console または Desk UI から確認できない情報は、決して依頼しないでください。
• **簡潔にします。各手順では、出力の確認と次のスニペットを 1～2 行で示してください。**要約や、問題の言い直しは不要です。
• アプリのバージョンを早い段階で特定し、そのバージョンのコードベースに基づいて判断してください。ブランチごとに差異があります。クライアントがインストールしているバージョンに合うブランチ／タグをチェックアウトするか、読み込んでください：git -C apps/<app> show <branch>:path/to/file.py、または git -C apps/<app> grep <term> <branch> -- '*.py'。
• クライアントへの返信案は、できるだけ短く、非常に簡単な言葉で、調査結果に基づいて作成してください。返信文だけを出力し、それ以外は何も出力しないでください。「返信案はこちらです」といった前置き、補足説明、最後の追加質問は付けず、そのままコピーして送信できるようにします。
• **カスタマイズは判断が難しい領域です。推奨、実装、支援はしないでください。**フレームワークのカスタマイズ（Client Scripts、Custom Fields、Server Scripts、Property Setters）により、エンドユーザーが実際の不足を補える場合もありますが、コアサポートの対象外です。クライアントに代わってカスタマイズを提案、記述、実装しないでください。カスタマイズでしか対応できない依頼には、その旨をはっきり伝え、そこで終了してください。スクリプトや手順は提供しないでください。

チケットの確認（Frappe Helpdesk）

チケットが Frappe Helpdesk（HD Ticket）にある場合は、frappectl などの読み取り専用 Frappe API クライアント（または REST API を直接使用）でチケットとメールのやり取りを取得します：

• チケットのフィールド：frappectl doc get "HD Ticket" <name>
• メールのやり取りと内部メモ：frappectl doc list Communication は権限によって結果が絞り込まれ、[] を返すため、使用しないでください。代わりに：

  frappectl api "method/frappe.desk.form.load.get_docinfo?doctype=HD%20Ticket&name=<name>"
  

  docinfo.communications はメールスレッド（content、sender、communication_date）、docinfo.comments はエージェントの内部メモです。

**スレッドの更新：**最新の返信の確認やコンテキストの更新を依頼された場合は、get_docinfo の呼び出しを再実行し、docinfo.communications の新しいエントリを確認してください（communication_date で並べ替えます）。スレッドはサーバー上で更新されるため、以前取得した内容に頼らず、再取得してください。

1. 分類 → 対応方針を選ぶ

コードとデータから独自に仮説を立ててください。チケットやクライアント／エージェント間のやり取りは症状であり、診断結果ではありません。推測した原因にとらわれないでください。データで裏付けられるまでは修正しないでください。対応方針は以下のとおりです。後半の方針に至るには、手順 2～4 が必要になることがよくあります。

• 機能の説明／「仕組み」（設定、権限、ワークフローの誤解） → 調査結果に基づいて説明し、クライアントへの返信文案を作成します。修正はしません。
• コードのバグと確認済みで、修正可能 → 手順 2～5 に従って修正します。
• データの不整合（コードは正しいが、クライアントのデータが不正な状態にある。孤立／古い行、リンク解除されていない元帳エントリ、壊れた未決済項目など） → クライアントの実データとコードを照合し、ロジックではなくレコードに誤りがあることを証明してから、コードのパッチではなく対象を絞ったデータ修復を行います。手順 5 を参照してください。
• バグだが、RCA が大規模なリファクタリング／互換性を損なう変更となる → そのことをユーザーに伝えます。修正はしません。
• 機能リクエスト → 機能リクエストであることをユーザーに伝えます。修正はしません。
• すでに修正済み／古いリリース → アプリのアップデートをクライアントに促します。修正はしません。まずクライアントのコミットを特定し、タグを確認して最新リリースと比較します。後続リリースには、すでに多くの修正が含まれています。新しいタグに修正が存在する場合、または症状が同期のずれでアップデートとマイグレーションによって解消される場合は、必要なアプリをアップデートして再確認するよう依頼してから、調査を続けてください。

2. データを依頼する — 説明文ではなく、実行可能なコード

クライアントがサイト内の System Console（Desk → /app/system-console）に貼り付けるスニペットを提示してください。これは RestrictedPython サンドボックスであり、bench console／SSH ではありません。以下のサンドボックスルールに従ってください。返された出力と内容が明確に対応するよう、すべての print にラベルを付けてください（print("outstanding:", ...)）。往復を最小限にするため、関連する質問は 1 つのスニペットにまとめてください。

3. 分析 → 結論を出すか、繰り返す

• 結論が出た → 回答して完了です。
• コードに原因があると考えられる → 固定したバージョンで該当するコードパスをたどり、エッジケースやバグを探します。
• はっきりしない → 仮説を見直し、手順 2 に戻ります。

4. カスタマイズを除外する（コード上は動作するはずの場合）

固定したバージョンに基づく推論では動作が正しいはずなのに、クライアントでは問題が発生し、ローカルで再現できない場合は、コアのバグや行き詰まりと判断する前に、サイトレベルのカスタマイズを疑ってください。手順 5 の前に必ず実施してください。カスタマイズが原因の動作に対して、コアの修正を提案してはいけません。カスタムアプリが導入されている場合は、「Audit System Hooks」レポートに加え、対象オブジェクト（doctype／レポート／ホワイトリスト登録済みメソッド）の Client／Server Scripts、Custom Fields、Property Setters を確認してください。

5. 修正

コードのバグ

• 修正前にエッジケースと回帰への影響を十分に分析してください。症状へのパッチで済ませてはいけません。必要に応じて、修正がなければ失敗する回帰テストを追加してください。
• 専用のテストサイト（例：<app>-test.localhost）で再現して検証してください。クライアントのサイトでは絶対に行わないでください。
• code-style と frappe-app-dev のスキルに従って修正を書いてください。

ブランチ作成とバックポート

• 編集前にブランチを作成する — メインライン（develop）やリリースブランチを直接編集してはいけません。
• まず develop で修正し、その後バックポートする — まだ保守されている各リリースブランチに適用してください。最も古い保守対象リリースより前のブランチには適用しないでください。
• コミット前にレビューを待ち、依頼された場合にのみ PR を作成してください。

データ修復（データ不整合の場合）

クライアントの System Console から実行します（Commit ボックスにチェックを入れた場合にのみ書き込みが保持されます）。スクリプトは次の条件を満たす必要があります。

• 安全である — 誤りを証明する条件（例：元のドキュメントの docstatus == 2、行がまだ有効であること）ですべての書き込みをガードし、正しいデータには何もしないこと。
• 冪等である — 再実行しても、修正後は何も変更されないこと。
• 最小限である — 特定した不正な行だけを変更し、無差別な一括更新を行わないこと。
• 検証可能である — クライアントの出力で変更を確認できるよう、変更前と変更後を出力すること。

正しい最終状態を、まず会計担当者またはユーザーに確認してください。同じ不正な状態が再発する可能性がある場合は、根本原因となるコードの不足について、別途コードのバグとして修正してください。

System Console サンドボックスのルール

safe_exec 経由で実行されます。Server Scripts と同じサンドボックスです。

表示されるのは出力した内容だけです（print()）。式だけを書いても出力されません。Python モードを優先してください。ただし、複雑な読み取りには SQL モードを使用してください。クエリには limit を指定してください。

禁止事項：

• シーケンスのアンパック — a, b = x、for a, b in items:、内包表記での k, v。RestrictedPython は _unpack_sequence_ ガードを出力しますが、これは名前空間にないため、NameError: name '_unpack_sequence_' is not defined が発生します。代わりにインデックスを使ってください（r["a"]、r[0]）。辞書の値はタプルにせず、辞書のまま扱ってください。
• import（すべて）— コンパイル時にブロックされます。間接的なインポートもすべて ImportError: __import__ not found で失敗します。アプリのコードをインポートすること（from erpnext... import x）も、frappe.get_attr / frappe.call を介してアクセスすることもできません（名前空間にありません）。ヘルパーのロジックをテストするには、許可された呼び出しを使ってインラインで再現してください。実際の関数を呼び出そうとしないでください。
• frappe.get_installed_apps — 名前空間にありません（AttributeError）。SQL でアプリを取得してください：SELECT app_name FROM \tabInstalled Application`（SQL モード）。または、frappe.db.exists("Module Def", {"app_name": "erpnext"})` で個別に確認してください。
• frappe.get_single_value — 名前空間にありません。代わりに frappe.db.get_single_value("Doctype", "field") を使用してください。
• frappe.get_conf / conf / get_site_config / local / cache / get_single — 名前空間にありません。
• frappe.parse_json — frappe.utils.parse_json または json.loads を使用してください。
• .format() / .format_map() — f 文字列を使用してください。
• _ で始まる属性（doc.__dict__、obj._x）。
• 許可リストにない frappe.utils.X（例：get_site_path、get_files_path）。
• open() / ファイル I/O、SELECT 以外の frappe.db.sql。

許可事項：

• ORM：frappe.get_doc（実際の Document）、get_all、get_list、get_cached_doc、get_last_doc、get_meta、new_doc、copy_doc、get_mapped_doc。
• frappe.db：get_value、set_value、get_single_value、get_list、get_all、exists、count、get_default、escape、sql（SELECT / EXPLAIN）、commit / rollback（書き込みが永続化されるのは Commit ボックスにチェックを入れた場合のみです）。
• frappe.utils：getdate、get_datetime、nowdate、today、now、now_datetime、add_days、add_months、date_diff、get_first_day、get_last_day、flt、cint、cstr、fmt_money、money_in_words、parse_json、get_link_to_form。
• その他：print、frappe.log、frappe.msgprint、frappe.throw、frappe.qb、frappe.get_system_settings、frappe.session、frappe.form_dict、json.loads/dumps、_dict、組み込み関数（dict/list/set/tuple、len/str/int/float/round/bool、range/enumerate/sorted/sum/min/max）、内包表記、f 文字列、ループ。