# .xlsx パーサーライブラリ 要求仕様書
*[English](requirements.en.md)*
## 0. 実装言語
Rust
## 1. プロジェクト概要
既存の `.xlsx` パーサーに代わる、軽量かつ高速な `.xlsx` (OOXML) パーサーライブラリを開発する。特に日本の業務システムで頻出する「方眼紙Excel（極端に多い行・列数を持ち、数百万セル規模に達することもある大量データ）」および「複雑な結合セル」を、メモリを圧迫せずに高速に処理・分析し、フロントエンドや他システムで扱いやすいJSON形式で出力することを目的とする。
## 2. システムアーキテクチャと処理パイプライン
本パーサーは、以下の5つのフェーズによる一方向のデータ処理パイプラインとして機能する。
### フェーズ1：リレーションシップの解決とリソースの破棄（展開・削除）
* **処理:** ZIPアーカイブから `_rels` ファイル（`xl/_rels/workbook.xml.rels` 等）を展開し、シートID（`r:id`）と実体ファイルパス（例: `worksheets/sheet1.xml`）の紐付け（ルーティングマップ）をメモリ上に構築する。
* **必須要件:** メモリ効率の向上および一時データの残存を防ぐため、**ルーティングマップの構築が完了した直後に、展開した `_rels` の一時データおよび関連リソースは即座にメモリ上（またはファイルシステム上）から削除・破棄する**。
### フェーズ2：サニタイズ（悪意のあるインジェクション排除）
* **処理:** 外部からの安全性が担保されていないファイルの読み込みを前提とし、以下のセキュリティ機構をレイヤーとして挟む。
* **要件:**
* **Zip対策:** Zip Bomb（高圧縮ファイルによるメモリ枯渇攻撃）やパストラバーサル（Zip Slip）を解凍処理時に検知・ブロックする。
* **XXE対策:** XMLパース時において、外部エンティティの展開を無効化し、不正なローカルファイル参照を防ぐ。
### フェーズ3：ストリームパースと境界定義（ページング）
* **処理:** メモリ枯渇を防ぐため、対象シート（`sheetX.xml`）のDOM全体をメモリに展開しない。
* **要件:** イベント駆動型（SAX型）のパーサーを使用し、`<sheetData>` 内の `<row>`（行）ごとに処理の境界を定める。1行分の読み込みと後述のデータ保持が完了した時点で、その行のXMLノードは破棄する。
### フェーズ4：分析と遅延解決
* **処理:** 収集した生データを、意味のあるデータ構造へ変換・結合する。
* **要件:**
* **共有文字列・スタイルの解決:** セルの値が `t="s"`（文字列インデックス）の場合、保持しておいた `SharedStringTable` と突き合わせて実際の文字列データを割り当てる。
* **結合セルの遅延解決:** ストリームパース完了後、シートの末尾に出現する `<mergeCells>` を読み取る。結合範囲（例：`A1:C3`）のリストと、取得済みのセルデータを突き合わせ、結合状態を確立する。
### フェーズ5：JSON生成（返却）
* **処理:** 分析・解決が完了したデータモデルをJSON形式にシリアライズして出力する。
* **要件:** フロントエンド等での描画を容易にするため、`row_span`、`col_span` などの属性を付与した構造化JSONとして返却する。
## 3. コア機能要件（業務システム特化要件）
### 3.1 疎行列（Sparse Matrix）によるメモリ最適化（方眼紙Excel対策）
* 二次元配列（`行 × 列`）によるデータ確保を禁止する。
* データまたは書式が存在するセルのみを、座標（例：`row: 1, col: 1`）をキーとしたハッシュマップ（`HashMap` 等）として保持する。
* 空白セルはメモリ上にインスタンスを持たせず、JSON出力時にも除外（または必要最小限のnull出力）とする。
### 3.2 結合セルの透過的アクセスサポート
* 結合されたセル（例：`A1:C3`）において、実データを持つ起点セル（`A1`）だけでなく、結合範囲に含まれる仮想的なセル座標（`B1`, `C2` 等）へのアクセスを考慮する。
* 分析フェーズにて、仮想セルから起点セル（`A1`）への「エイリアス参照」を内部的にマッピングし、どの座標を指定されても正しい結合値および結合メタデータを返却できるようにする。
## 4. 扱う主なOOXML仕様ファイル
* `[Content_Types].xml`: 各パーツのMIMEタイプ定義
* `xl/workbook.xml`: シート構成の定義
* `xl/sharedStrings.xml`: 文字列データの一元管理（`xml:space="preserve"` を遵守すること）
* `xl/styles.xml`: セル書式・スタイルの定義
* `xl/worksheets/sheetX.xml`: シートの実データ（`<sheetData>`, `<mergeCells>` などを包含）