# [メタ情報]
# 識別子: ローカルファイルパスからpCloudダイレクトリンクを取得する手順_exe
# システム名: ローカルファイルパスからpCloudダイレクトリンクを取得する手順
# 技術種別: Misc
# 機能名: Misc
# 使用言語: 手順の記述
# 状態: 実行用
# [/メタ情報]
要約：cloudid シートの filepath を基に、pCloud Public Folder 内の該当ファイルを特定し、自動で fileid と filedn 形式の direct_url を生成して書き戻す手順である。filepath から内部パス（生パス）を構築し、/stat API により fileid を取得。さらに正式パスを再構築し、encodeURI により UI と同等のダイレクトリンクを生成する。pCloud は direct link を API で返さないため、この方法が唯一正確である。

filepath (D列)
    ↓
内部パス構築 (Public Folder + NFD)
    ↓ encodeURIComponent
/stat?path=
    ↓
fileid取得
    ↓
/stat?fileid で正式パス取得
    ↓
Public Folder/ を除去
    ↓ encodeURI
filedn直リンク生成


【目的】
マイライブラリへ新規追加したメディアのローカル filepath（mmedia/pmedia 以下）をもとに、
pCloud の Public Folder 内で対応するファイルを特定し、fileid およびダイレクトリンク（filedn URL）
を生成して pcloudid シートへ書き戻す。

------------------------------------------------------------
【前提】
● pcloudid シートの各行には以下の列がある：
  A: wpidex
  B: fileid（新規時は空欄）
  C: filename
  D: filepath（例: mmedia/2024_xxx/zzz.png）
  E: direct_url
  F: needs_update（新規時は TRUE）
  G: last_update

● filepath は pCloud Public Folder 以下の相対パスを記述する。
● needs_update = TRUE の行だけが処理対象となる。

------------------------------------------------------------
【手順】

1. pcloudid シートの 2 行目以降を走査し、以下の行を検出する：
   - fileid が空である
   - filepath が入力されている
   - needs_update = TRUE

2. D列の filepath（例: mmedia/xxx/abc.png）から、pCloud API 用の「内部パス（raw path）」を構築する。
   手順：
     (1) filepath の先頭に "/" を付与し absolute 化する。
         例: "mmedia/xxx.png" → "/mmedia/xxx.png"
     (2) "/Public Folder" を先頭に追加し、pCloud の正式な仮想パス形式にする。
         例: "/Public Folder/mmedia/xxx.png"
     (3) パス文字列を Unicode NFD に正規化する（濁点・結合文字の差異を吸収するため）。

   ※ここで得られる文字列が、pCloud API が内部比較に使用する「生パス」である。

3. 上記の生パスを encodeURIComponent で URL エンコードし、
   pCloud API /stat?path= にクエリとして送信する。
   例：
     /stat?path=%2FPublic%20Folder%2Fmmedia%2Fxxx.png&auth=...

4. pCloud サーバ側では URL をデコードし、内部に保持しているパスと比較する。
   完全一致した場合、JSON レスポンス内に metadata.fileid が返される。

5. 取得した fileid をシートの B列に書き込む。

6. 次に、fileid を指定して pCloud API /stat?fileid= を呼び出し、
   親フォルダ ID、ファイル名、更新日などの正式メタ情報を取得する。

7. 取得したメタ情報をもとにフォルダ階層を再帰的に解決し、
   pCloud Public Folder 内での完全パス
     /Public Folder/.../filename.ext
   を再構築する（NFD のまま保持）。

8. 上記パスから "Public Folder/" を取り除き、残りの部分を encodeURI でエンコードし、
   あらかじめ設定した filedn ベース URL と結合して direct_url を生成する。

   例：
     base: https://filedn.eu/xxxxx/
     path: mmedia/xxx/abc.png
     direct_url: https://filedn.eu/xxxxx/mmedia/xxx/abc.png


※補足（重要）：
pCloud の Web UI が表示する「ダイレクトリンク」は API が返す値ではなく、
ブラウザ内の JavaScript により、
「Public Folder 以下のパスを UTF-8 でパーセントエンコード（encodeURI と同等の方式）し、
filedn ベース URL と結合して構築」されている。

pCloud は direct link（filedn URL）を API として提供していないため、
外部アプリ（GAS 等）が direct_url を生成する際は encodeURI を用いる方式が
実質的に唯一の正しい方法である。

GAS による direct_url 生成方式が UI の direct link と実質一致すると判断できる理由は以下の通り。

(1) UI でコピーした direct link のパス部を decode すると、
    pCloud API (/stat?fileid, /stat?path) が返す raw path（生パス）と完全一致する。

(2) encodeURI（UTF-8 → %エンコード、スラッシュを保持）の挙動と、
    pCloud UI が direct link を生成する挙動が、
    日本語、濁点、スペース、フォルダ階層など多様な条件下で完全一致することを検証済み。

(3) direct link のエンコード仕様は pCloud の API ドキュメントに記載されていないが、
    UI の動作・API の挙動・エンコード結果の再現性から、
    encodeURI に基づく URL が UI 生成と同一であることが実質的に保証される。

以上より、GAS によって生成された direct_url は
pCloud UI の「リンクをコピー」で得られる direct link と
構造・意味・挙動のすべてにおいて等価である。


9. 生成した direct_url を E列に書き込み、
   needs_update を FALSE に変更し、
   last_update に現在時刻を記録する。

10. すべての行の処理が終わったら、pcloud_library.json を生成し、
    fileid・filename・direct_url を含むレコード一覧を Google Drive 上に保存する。

------------------------------------------------------------
【結果】

● 新規追加したメディアについて：
  - fileid が自動取得される。
  - filedn 形式のダイレクトリンク（直リンク）が自動生成される。
  - 両方が pcloudid シートの該当行に書き戻される。
  - JSON（pcloud_library.json）にも正式な direct_url が反映される。

● direct_url は WordPress（rd.php）で最優先して使用され、
   pCloud Public Folder のファイルを高速かつ安定して再生できる。

------------------------------------------------------------
【補足】
● pCloud API は「生パス（UTF-8 デコード後）」を完全一致で比較して fileid を返す。
● URL の大小文字やエンコード後の見た目は一致判定に影響せず、
   デコード後のテキスト一致のみが本質である。
● filepath が正しく入力されていれば、fileid は高い安定性で取得できる。