既知の問題¶

扱うこと: インデックス作成の既知の問題（共通・Word 固有・PowerPoint 固有）と確度。扱わないこと: エラーメッセージそのものの一覧（エラーメッセージ一覧）。先に読むページ: インデックス作成。

確度: ◎ = 動作確認済み、○ = コード上明らか、△ = 推定。

Word に固有のものは Word の注意点・既知の問題（Word の注意点・既知の問題）、PowerPoint に固有のものは PowerPoint の注意点・既知の問題（PowerPoint の注意点・既知の問題）にまとめる。

flowchart LR
    A["クロール<br>normalizeFolderPath・testSameFolder"] --> B["取り込み対象の決定<br>createTargetList・getIndexTsvCounts"]
    B --> C["抽出<br>extractWorkbook・prettyTsv"]
    C --> D["本文インデックス<br>updateFolderContentIndex"]
    D --> E["検索<br>searchContentIndex"]
    E --> F["元のファイルを開く<br>openInExcel"]

既知の問題が主に起きる場所を、処理の流れに沿って示す（詳細は各項目の本文）。

共通¶

#	内容	確度
1	ブック名に `.xls_` などを含む別ブックがあっても（例: `a.xls` と `a.xls_b.xlsx`）、本文インデックスに入れる前の TSV はファイル名ごとのフォルダに分かれ、本文インデックスの中でもファイル名（`ファイル名=` の行）で分かれるため、旧 TSV の削除・差分判定・元ファイルが無くなったときの削除で他方を巻き込まない（インデックスのファイルの形）	◎
2	インデクサが強制終了された（PC の停止・タスクマネージャーでの画面の `powershell.exe` の終了等。インデックス作成は画面のプロセスの中で動く）場合は `finally` が実行されず、Excel・Word・PowerPoint が残る（次に画面を起動したときの確認で終了する。前回残った Office の確認）。取り込み一覧には追記した行が重複して残るが、次回のクロール時に書き直される。作りかけのインデックス（一部のシートだけの TSV）は残らない（`publishIndexFiles`。インデックスのファイルの形）。本文インデックスに入れる前の TSV のフォルダは残るが、次回のインデックス作成開始時に本文インデックスへ入れる（`findIndexFoldersWithBooks`。インデックスのファイルの形）。`work/publish/<PID>`・`work/tmp/<PC の鍵>/<PID>` も残るが、次回のインデックス作成開始時に削除する	△
3	長いパス（260 文字超）は `\\?\` を付けて扱う（インデックスのファイルの形）。ファイル名の上限（255 文字）は、元のファイル名をフォルダ名、場所を TSV 名にするため超えない（名前の長いファイルも取り込める）	◎
4	更新の判定は更新日時（秒まで）とサイズで行う。1 秒以内に同じサイズのまま内容だけ変わった場合や、更新日時を保ったまま内容を書き換えるツール（展開・複写・バックアップからの復元など）で変更した場合は検出できない。中身をすべて読んで比べると、インデックス作成と変わらない時間がかかるため行わない。その場合は、そのインデックスを画面で［削除］してから作成し直す（`work/` を削除する必要は無い。ほかのインデックスは残る）	○
5	クロール対象フォルダのパスの書き方を変えても（ドライブ文字と UNC パス、`/` 区切り、`.` `..` を含む形、`\\?\` 付き、環境変数）同じフォルダとみなし、取り込み直さない（`normalizeFolderPath` ・ `testSameFolder`）。ただし、ドライブ文字で書いたパスの割り当て（ネットワークドライブ・`subst`）が既に無い場合は、同じフォルダとは分からない	○
6	クロール時にアクセスできないフォルダがあると、元ファイルが無くなったファイルはインデックス（本文インデックス）から除かれない（次回、全フォルダにアクセスできたときに除かれる）	○
7	`work/store/content` の本文インデックスのファイルやフォルダを直接削除した場合・0 バイトの本文インデックスのファイルや TSV が残っている場合（書き込みの途中で電源が落ちた等）は、次のインデックス作成でそのファイルを取り込み直す（取り込み一覧の「済」と、そのフォルダ・その拡張子の本文インデックスのファイルの有無・大きさ、本文インデックスに入れる前の TSV の数・大きさを照らす。取り込み対象の決定）。ただし本文インデックスのファイルの中身の書き換え・一部の欠け（手で編集した等、0 バイトでないもの）は分からない（本文インデックスのファイルの中の元のファイルごとの場所の数は、中身を読まないと数えられないため確かめない）。その場合は画面で［削除］してから作成し直す	◎
8	取り込み一覧・インデックスの食い違いを避けるため、同じ `work` のインデックス作成は同時に 1 つだけ動かす（`newAppMutex`。鍵は `work` のパスから作る）。別の `work` を使うツールは、同時に動かしても互いに影響しない	◎
9	インデックス作成中にクロール対象フォルダにアクセスできなくなった場合は、残りのファイルを「未取り込み」のまま中止する（すべて「失敗」になるのを避けるため。インデックス作成のメインフロー）。個々のファイルが移動・削除された場合は、そのファイルだけを一覧から除いて続ける	◎
10	ファイルサーバーに到達できない・ネットワークドライブが切断されている場合、Windows の応答待ちでフォルダの有無の確認に時間がかかることがある。確認できなければ存在しないフォルダとして扱い、そのフォルダだけ取り込まずに続行する（既存のインデックスは消さない）	△
11	チェックを外したフォルダのインデックスは検索対象に残る。検索から外すには設定から行を削除する（インデックスも削除される）	○
12	クロール対象フォルダを移した・名前を変えた場合、画面の詳細の「フォルダパス」の欄で「元のフォルダ」を書き換えれば、インデックス名が同じため取り込み直さない。一覧から削除して新しいパスで追加し直すと、別のインデックス（新しい名前）になり全件取り込み直す（クロール対象フォルダと取り込み対象）	○
13	インデックスのファイルの数は、元のフォルダの数 × 拡張子の種類の数まで（本文インデックスのファイル）。取り込み中だけは元のファイル 1 つにつきフォルダ 1 つができるが、フォルダの取り込みが終わると消す。検索の速度は読むファイルの数で決まるため、本文インデックスにして速くなる（検索を速くする仕組み）	○
14	元のファイル名が `.xlsx` などで終わるフォルダ（例: `拡張子付きフォルダ.xlsx`）がクロール対象フォルダの中にあると、インデックスでは「ファイル名のフォルダ」（本文インデックスに入れる前の TSV の置き場所）と同じ形になる。画面の検索対象ツリーには出ない	○
15	制限時間（10 分）で強制終了できるのは自分で起動した Office アプリだけ。利用者の Word に接続して変換している場合は止められない（PowerPoint は利用者のアプリに接続しないため、この問題に当たらない。Office アプリ（Excel・Word・PowerPoint）の管理「PowerPoint」）。`.docx` `.pptx` `.xlsx` を直接読む処理（Office を使わない）は、ZIP の部品 1 つにつき 100MB・1 ファイルの合計 300MB の上限（Office ファイルを開くときの設定）で読む大きさを打ち切るため、細工したファイルで無限に長引くことは無い（`.xlsx` のシートのヘッダー・フッターの流れ読みだけは、この 2 つを通らず、1 ファイルで実際に読んだ合計が展開後 1000MB の別の上限 `$script:zipSheetStreamMaxBytes` に達したところで打ち切り、`readZipEntry` の合計には数えない。同じシートの部品は 1 回だけ読む）。ただし、この上限の範囲内で時間がかかる場合は制限時間まで止められない。上限の値を変えるには `shared/office/office_reader.ps1` の `$script:zipPartMaxBytes`・`$script:zipTotalMaxBytes` を直す（`setting.config` には出していない）。画面の［中止］もファイルの切れ目まで効かない。画面を閉じるときは 60 秒待ってインデックス作成が起動した Office を止め、さらに 15 秒待っても終わらなければそのまま閉じる（閉じるときの順番）。画面（`powershell.exe`）を強制終了した場合も、次回はそのファイルを最後に回し、続けて 2 回なら失敗にする	○
16	正常でも 10 分以上かかる巨大なファイルは失敗になる。取り込みたい場合は `tebunko/indexer/indexer_run.ps1` の `$fileTimeoutMinutes` を大きくする	○
17	制限時間を過ぎたときは、そのワーカーのスレッドが自分で起動した Office（ワーカーごとに 1 つ）を強制終了する。ほかのワーカーのアプリは止めない（次に必要になったときに起動し直すため、結果には影響しない）	○
18	Excel は表示されている形で出力するため、表示形式が「標準」の 12 桁以上の数値は指数表記（`4901234567894` → `4.90123E+12`）、「#,##0」などのセルは桁区切り付きになる。数値として入力した JAN コード・伝票番号は、その番号で検索してもヒットしない（Excel の抽出処理）。表示形式を「文字列」にするか、セルの先頭に `'` を付けて入力すれば検索できる	◎
19	整形（`prettyTsv`）はシート 1 枚分を一度に読み込むため、大きなシートほどメモリを使う（実測: 100 万行 × 10 列 = 書き出し 440MB で約 2.8GB、書き出し 800MB で約 3GB・60 秒）。書き出しが約 1GB を超えるシートはメモリ不足で「失敗」になる（失敗の原因の `シート・文書が大きすぎて取り込めません`）	◎
20	使用範囲（`UsedRange`）が実際のデータよりずっと広いシート（最終行・右端に書式だけが残っている等）は、データの範囲だけを一時シートにコピーしてから書き出す（Excel の抽出処理）。ブックの構成が保護されていて一時シートを作れない場合は、そのまま書き出すため制限時間で失敗することがある（その場合はインデックス作成ログに記録する）	◎
21	取り込みは取り込みのワーカーで並べて行い、Excel・Word・PowerPoint を同時に 1 つずつ動かすため、メモリを多く使う（同じ種類の Office を複数は起動しない）。Office を使わずに読むスレッド（既定はコア数 − 1、最大 4）もメモリを使う。メモリの少ない PC でメモリが足りなくなるときは、`setting.config` の `ingestThreads` を減らす（形式）	○
22	Excel のグラフの項目名（横軸に並ぶ文字。セルの値としては検索できる）・数値、新しい種類のグラフ（じょうご・ツリーマップ・滝など。`cx:chart`）、グラフの中のテキストボックス（`c:userShapes`）は検索対象にならない。グラフのタイトル・軸ラベル・系列名、SmartArt の文字は `[図形]` の場所で検索できる（Word・PowerPoint と同じ決まり。Excel の図形・コメントの読み取り）	○
23	1 つのグラフ・SmartArt の部品が壊れている（または「サイズの上限」を超える）ときは、そのグラフ・SmartArt だけを空のままにして続ける。読めなかった部品はインデックス作成ログに黄色で記録される（同じシートのほかの図形・コメント・セルの値は取り込まれる）	○
24	抽出版の上がった版に更新した後の最初のインデックス作成では、その形式のファイルを取り込み直す。`.xlsx` `.xlsm` はすべて Excel で開き直すため、通常よりも時間がかかる（1 回だけ。インデックス作成のメインフロー）	○
25	透過暗号化の製品（IRM・秘密度ラベルとは別の、社内のファイル暗号化ソフトなど）で暗号化されたファイルは、製品と設定によって動きが違う。Officeがその製品に許可されたアプリなら平文で開けて読める見込みがあるが、そうでなければ `暗号化されているか壊れているため取り込めません。` になる。Officeが開くのは、PowerShell（製品に許可されていないアプリ）が作業領域に作ったコピーのため、ファイルの先頭の印で見分ける製品なら平文を見せる見込みがあるが、フォルダや場所で決める製品では、コピーが平文にならず失敗になることがある（暗号化されたファイルの判定。未確認）	△
26	利用者に渡す確かめ（Office アプリ（Excel・Word・PowerPoint）の管理）は、1 ファイルの取り込みが終わったときと終了の前に行う。取り込みの途中に利用者のファイルが入ると、そのファイルの取り込みが終わるまでの間（最長で 1 ファイルの制限時間）は、制限時間の監視による強制終了や画面を閉じるときの終了で、そのファイルも閉じる。Excel・Word・PowerPoint のどれでも起こりうる。ただし PowerPoint は、取り込み中に窓が見えた（500 ミリ秒ごとに見る）プロセスなら、制限時間を過ぎても画面を閉じるときも止めない（利用者が使っている PowerPoint）。窓が見える前に終了処理（`stopApp`）が走る隙間は残る。利用者がファイルを開いて閉じたあと、次の確かめ（1 ファイルの取り込みの終わり）で印が消えるまでの間に固まると、印が残っているため止めない。PowerPoint は、渡した PowerPoint が残るあいだ、残りの PowerPoint のファイルを後回しにする	○
27	クラウドにだけあるファイルは、ファイルの属性（OneDrive・SharePoint のオンデマンドが付ける印）で見分ける。WebDAV やネットワークドライブ越しの SharePoint など、この印が付かないものは見分けられず、開いたときにダウンロードされる	△
28	見分けるのはクロールのときで、読む直前ではない。クロールのあとにダウンロードされたファイルは取り込まれ、クロールのあとにクラウドにだけになったファイルは、読むときにダウンロードされる	△
29	クラウドにだけあるファイルを含むフォルダを一覧にするだけでは、ダウンロードは起きない。ダウンロードして取り込む指定のときは、ダウンロードの時間も 1 ファイルの制限時間（10 分）に数える	○
30	更新されたあとでクラウドにだけある状態になったファイルは、ダウンロードして取り込むまで、古いインデックスのまま検索される	○

Word の注意点・既知の問題¶

確度: ◎ = 動作確認済み、○ = コード上明らか、△ = 推定。共通の注意点は共通の共通を参照。

#	内容	確度
1	Word のページ番号は目安。保存したときの Word の表示環境（プリンター・フォント等）で変わり、旧形式を変換した場合は互換モードの行送りの違いで元の文書とずれることがある	◎
2	旧形式（`.doc`）の取り込みには Word が必要（インストールされていない場合は取り込み一覧に「失敗」と記録される）。パスワード付き（新形式）は、暗号化されたファイルの判定でWordを起動せずに判定するため、Word が無くても同じ文言で失敗と記録される	○
2a	PDF は文字の命令だけを読む。画像だけの PDF（OCR しない）・開くのにパスワードが要る PDF・AES-256 以外の暗号化の PDF（RC4・AES-128）・`FlateDecode` 以外の圧縮・対応表（`ToUnicode`）の無い複合フォントの文字は検索できない。段組みや表は、位置でなくファイルに書かれた順に並ぶ。検索結果から開いても該当ページへは移動しない（PDF ファイルの読み取り）	○
3	埋め込みオブジェクトのうち Office のファイル（.xlsx・.docx・.pptx）は `[埋め込みN]` の場所で検索できる（深さは 1 段まで。画像・PDF・そのほかの形式、ヘッダー・フッター・脚注の中の埋め込みは検索できない）。グラフの項目名（データは埋め込みのブックにあり、セルとしては取り込まないため検索できない）・数値、変更履歴で削除した文字は検索対象にならない。コメント・SmartArt・グラフのタイトル・軸ラベル・系列名は `[コメント]` `[図形]` の場所で検索できる	○
4	ページ割りが済む前に保存された文書（プログラムから作成・保存した文書など）は、保存時のページ区切りが記録されていないため、手動の改ページが無ければ全体が `ページ001` になる（例: テストデータの `Word\長文.docx` は 3000 段落あるが、`w:lastRenderedPageBreak` が 0 個で `docProps/app.xml` のページ数も 1）	◎
5	透過暗号化の製品による暗号化で「形式の分からないバイナリ」になった `.doc` の中身が、実は RTF・HTML（透過暗号化前は Word がそのまま読めていた形式）だった場合、予備で開くときに `Format` を拡張子（`.doc`）に合わせて固定するため開けず、`暗号化されているか壊れているため取り込めません。` になる（Word の旧形式の変換）。まれなため対応しない	△

PowerPoint の注意点・既知の問題¶

確度: ◎ = 動作確認済み、○ = コード上明らか、△ = 推定。共通の注意点は共通の共通を参照。

#	内容	確度
1	旧形式（`.ppt`）の取り込みには PowerPoint が必要（インストールされていない場合は取り込み一覧に「失敗」と記録される）。パスワード付き（新形式）は、暗号化されたファイルの判定でPowerPointを起動せずに判定するため、PowerPoint が無くても同じ文言で失敗と記録される	○
2	スライドマスター・レイアウトのテキスト、グラフの項目名（データは埋め込みのブックにあり、セルとしては取り込まないため検索できない）・数値は検索対象にならない。コメント・SmartArt・グラフのタイトル・軸ラベル・系列名は `[コメント]` `[図形]` の場所で検索できる	○
3	PowerPoint を利用者が使用中の場合、旧形式（`.ppt`）・パスワード付きのファイルは接続せず、取り込まず、理由付きの失敗として見せる（一覧の状態は未取り込みのままなので、次回のインデックス作成で、失敗分の再取り込みを選ばなくても取り込む）（利用者の PowerPoint には触らない。Office アプリ（Excel・Word・PowerPoint）の管理「PowerPoint」）	◎