MAS-177: 多年度データ基盤 (Multiyear Data Foundation)

案件位置づけ: TODO_future.md §1 P1 ★★ ・ 🔧 Infra ・ 唯一の P1/P1.5 未起票案件。引き継ぎ書 (docs/_internal/daily_log/2026-W18.md) で「アーキテクチャ判断議論待ち」として最高優先で指摘された案件。

連携先: MAS-067 マルチイヤー計画ワークスペース (Phase A〜E 完了 PR #418-#454) ・ MAS-057 Solo CEO Cockpit (v2.4 で 5 年連結 P/L/B/S/CF 表示) ・ MAS-002 (期末スナップショット・並行起票) ・ MAS-133 (年度跨ぎアーカイブ機構・既存)

背景・問題意識

bizlp は会計年度 = 単年度を前提とした構造で実装されている:

• 主要タブ (61_pl_monthly / 71_bs / 81_cf_actual) は当期のみ管理
• 過去年度データは MAS-133 アーカイブタブで別途管理されているが、横断分析には統合されていない
• MAS-067 マルチイヤー計画 (5 年連結) は計画値ベースのみ・実績の多年度連結機能がない
• 期間横断 KPI (3 年 CAGR / 5 年累計売上 / 経常利益年次推移) を MAS-003 KPI ダッシュボードで表示できない
• 税務調査・銀行融資審査での「過去 3 期分財務諸表」要請に即応できない

User Story

Section 1. 概要

Section 2. 目的

**「単年度処理の bizlp を多年度連結処理可能に拡張する基盤」**を構築する。

4 つの User Story を満たす

1. US-1 (過去 3 年の経常利益推移): cockpit に多年トレンドパネルを追加可能にする基盤を提供
2. US-2 (5 期目 M&A 検討時の過去実績取得): 5 年分の P/L / B/S / CF を統合 API で取得可能にする
3. US-3 (Jr オンボーディング): 過去年度データの分断状態を解消し、データモデルの一貫性を担保
4. US-4 (税理士・監査向け過去 3 期分財務諸表): 過去年度の財務諸表を現環境で再現できる仕組みを提供

MAS-067 / MAS-057 / MAS-002 との位置づけ

• MAS-067 (マルチイヤー計画): 計画値ベースで 5 年連結 P/L / B/S / CF を提供済 (PR #418-#459)。本案件は 実績側 の多年連結基盤を提供し、MAS-067 Phase E v3 の Y0 着地見込み (getSoloCEOY0Forecast) と接続して Y-3 〜 Y+5 の連続トレンド (実績 + 計画) を実現する
• MAS-057 (Solo CEO Cockpit): v2.4 で 5 年連結表示済 (計画値)。本案件で実績側の API を提供し、v2.5+ で多年トレンドパネル (実績 + 計画) を実装可能にする
• MAS-002 (期末スナップショット): 並行起票仕様。本案件の多年保存機能を利用し、期末時点の B/S / P/L をスナップショット保存する

Section 3. 現在のコード構造

注: 本セクションはプロンプト記載内容に基づく既存パターンの整理。実装着手時に最新コードを再確認すること。

3.1 DDL 定義 (SSoT)

• 100_config/101_sys_config.js の schemas 配列が DDL 定義の Single Source of Truth
• 既存パターンとして MAS-133 (年度跨ぎアーカイブ機構) のシード migration が 800_ops/ に存在
• setupAllSchemas() で全タブ一括 DDL 生成

3.2 リポジトリ層 (現在は単年度前提)

200_data/202_repository.js の OrderRepository / InvoiceRepository 等が以下のパターンで実装:

- cache (シート 1 回読み込み + メモリ保持)
- findAll() (全行取得)
- save() (ID 一致行を更新)
- append() (末尾追加)

すべて当期データのみを対象とし、過去年度データへのアクセス API は提供されていない。

3.3 マート層 (単年度前提)

600_report/601_datamart_ingest.js は単年度前提で実装:

• maxInvYm / boundaryMonthStr 等の境界処理は当期内の月境界のみを扱う
• 多年度データのマート集約ロジックは存在しない

3.4 既存の年度別タブ

61_pl_monthly / 71_bs / 81_cf_actual / 91_fs_bs / 92_fs_pl 等の年度別タブはすべて 当期データのみ保持。過去年度データは MAS-133 アーカイブタブ (タブ末尾に _YYYY サフィックス) に手動移管される運用。

Section 4. 修正方針 (アーキテクチャ案 A/B/C)

重要: 本案件はアーキテクチャ判断議論待ちのため、3 案を提示し Q1 で議論 する。最終判断は人間との対話で確定する前提で v0.1 を起票する。

案 A: タブ年度別シャーディング (Period Sharding)

概要: 既存 61_pl_monthly を維持しつつ、過去年度を 61_pl_monthly_2025 / 61_pl_monthly_2024 等のタブにアーカイブ。

実装イメージ:

61_pl_monthly         ← 当期 (2026FY)
61_pl_monthly_2025FY  ← 前期アーカイブ
61_pl_monthly_2024FY  ← 前々期アーカイブ
71_bs                 ← 当期
71_bs_2025FY          ← 前期アーカイブ
...

• MAS-133 既存パターンを拡張
• タブ命名規則 + ヘッダー互換性維持
• 多年度集約は 600_report/610_multiyear_aggregator.js で各年度タブを getDataRange() してマージ

メリット:

• シンプル・MAS-133 の延長
• 既存ロジック影響最小 (当期タブは無変更)
• 物理的に年度ごとに分離されているため、データ修正時の影響範囲が明確

デメリット:

• タブ数が 年数 × 主要タブ数 で爆発 (5 年 × 10 主要タブ = 50 タブ追加)
• タブ一覧が煩雑化
• GAS の 200 タブ上限注意 (10 年運用で 100 タブ追加 → 警告ライン)
• 横断クエリは aggregator で都度マージが必要

案 B: 単一統合タブ + 期間列追加 (Unified with Period Column)

概要: 主要タブ (61_pl_monthly / 71_bs) のヘッダーに 会計年度 列を追加し、全年度のデータを単一タブに格納。年度フィルタで表示制御。

実装イメージ:

61_pl_monthly:
| 会計年度 | YM   | 勘定科目 | 金額    | ... |
|---------|------|---------|--------|-----|
| 2026FY  | 202604 | 売上高 | 100000 | ... |
| 2025FY  | 202504 | 売上高 |  80000 | ... |
| 2024FY  | 202404 | 売上高 |  60000 | ... |

• 既存単年度処理は 会計年度 = 当期 フィルタで動作互換維持
• 横断クエリは WHERE 会計年度 IN (...) で SQL ライクに実現

メリット:

• タブ数増えない (タブ管理シンプル)
• 横断クエリ容易・SQL ライク
• データの一貫性が単一タブで担保

デメリット:

• 既存タブの大規模再構成 (DDL 変更・データ移行)
• 行数増加 (5 年で約 5 倍)
• パフォーマンス影響 (MAS-231 GAS 最適化パス 1 と相互作用)
• 既存単年度ロジック総点検必要 (フィルタ漏れ = 多年度データの誤集計リスク)

案 C: ハイブリッド (Aggregator Layer)

概要: 物理データは案 A (年度別タブ) で保管しつつ、論理アクセスは新規 MultiyearRepository (200_data/203_multiyear_repository.js) で抽象化。

実装イメージ:

// 多年度取得
const rows = MultiyearRepository.findAll({
  sheetKey: '61_pl_monthly',
  periods: ['2026FY', '2025FY', '2024FY']
});

// 単年度互換 (既存コード)
const rows = MultiyearRepository.findAll({
  sheetKey: '61_pl_monthly',
  periods: ['current']
});

• 物理データ層: 年度別タブ (案 A と同じ)
• 論理アクセス層: MultiyearRepository で統合 (案 B のメリットを論理層で実現)

メリット:

• 物理移行リスク低 (案 A の延長)
• 論理アクセスはきれい (案 B の利点)
• 段階的移行可能 (Phase A: Aggregator のみ実装 → Phase B: 主要タブ年度別シャーディング → Phase C: 既存ロジックの MultiyearRepository 経由化)
• 既存単年度コードは findAll({periods: ['current']}) で互換維持

デメリット:

• 抽象化レイヤー実装コスト (~200 行)
• キャッシュ戦略要設計 (複数年度キャッシュの整合性)
• 案 A + 案 B の両方の制約を一部継承

推奨: 案 C (ハイブリッド・Aggregator Layer)

理由:

1. 既存単年度コードへの破壊的変更を最小化
2. 物理データは MAS-133 既存パターンの延長で実装容易
3. 論理アクセスは将来の MAS-067 / MAS-057 / MAS-003 多年化で再利用可能
4. 段階的移行可能 (Phase A → B → C)

ただし: 案 C はバランス型のため、シンプルさ優先なら案 A・SQL ライク統合優先なら案 B も合理的。最終判断は人間との対話で確定する前提で v0.1 を起票。

Section 5. 影響範囲

5.1 新規ファイル

番号割当: 800_ops は 822 まで使用済 + MAS-336 / 337 / 338 で予約済。本案件は 824 以降 で番号確定 (実装着手時に grep で再確認)。

5.2 DDL 拡張 (主要タブ)

5.3 既存ロジックへの影響

• 案 A: 影響最小 (当期タブは無変更・aggregator のみ追加)
• 案 B: 全関数の点検必要 (会計年度 フィルタ漏れ = 多年度誤集計)
• 案 C: 段階的に切替 (Phase C で既存ロジックを MultiyearRepository 経由に移行)

5.4 連携案件への影響

Section 6. 注意事項

1. GAS のタブ数上限: Google Sheets 1 ファイル 200 タブが推奨上限。案 A で 5 年 × 10 主要タブ = 50 タブ追加は安全圏内。10 年運用で 100 タブ追加は警告ライン。

2. MAS-133 既存アーカイブ機構との整合: MAS-133 は「年度終了後にアーカイブタブを作成」する後付け処理。本案件は当初から多年度前提・MAS-133 の責務を吸収して廃止する判断もあり (Q2 で議論)。

3. データ移行の冪等性: migration script は「既に多年度形式に変換済みのタブはスキップ」する冪等性ガード必須。804-808 マイグレーションの既存パターンに従う。

4. GAS パフォーマンス: 案 B (単一タブ + 期間列) は行数増加でパフォーマンス劣化リスク。MAS-231 (GAS 最適化パス 1) と相互作用。多年度集約処理はキャッシュ層を通すこと。

5. 既存単年度ロジックとの後方互換性:

   • 案 C: MultiyearRepository.findAll({periods: ['current']}) で互換維持
   • 案 B: フィルタ強制で互換維持
   • 案 A: API 変更不要 (既存コードは当期タブのみアクセス)

6. ヘッダー互換性: タブ年度別シャーディング (案 A / C) では年度毎のヘッダー差異 (新列追加等) を吸収する仕組み (headerCompatibilityMap) が必要。

7. 会計年度の境界: 日本法人の会計年度は決算月 (例: 3 月決算) ベースで暦年と一致しない。会計年度 列の値は 「2025FY (2025/4-2026/3)」 等の表現に統一。

8. マルチテナント (将来): ADR-0009 (活動領域分離戦略) で複数法人運用想定する場合、組織ID + 会計年度 のキー設計が必要 (Q3 で議論)。

9. MCP add_rows との関係: シート先頭追加問題 (CLAUDE.md 記載) は本案件でも要注意・update_cells で末尾書込パターン継承。

10. テストランナー: F177-01〜F177-15 を 901_test_runner.js に追加。

11. MAS-067 Phase E v3 の Y0 着地見込み: 既に MAS-067 で getSoloCEOY0Forecast() API 実装済 (PR #459)。本案件で Y-1〜Y-3 ライン追加時に同パターン踏襲。

12. ドキュメンテーション: 本案件は基盤系のため、MAS-067 / MAS-057 / MAS-002 / MAS-003 にクロスリンク必要。

13. 段階的リリース: Phase A (Aggregator + 1 タブ年度別シャーディング検証) → Phase B (主要 5 タブ展開) → Phase C (既存ロジック切替) の 3 段階推奨。

14. failure_patterns #34 (計画 B/S 構造的乖離) との関係: 多年実績取得時に PHASE 1 仕訳振替 INV (MAS-336 で本則化) との整合性必須。期首残高 (PHASE 0) + ΔB/S (PHASE 1〜) の連結ロジックで failure pattern #34 を踏まないよう注意。

Section 7. エッジケース

1. 設立初年度 (Y0) で過去年度データなし → findAll({periods: ['current']}) 単年度動作・空配列ではなく当期データのみ返却

2. 会計年度途中の決算月変更 (例: 3 月決算 → 12 月決算) → 短縮 / 長期事業年度の表現を 会計年度 列で「2025FY-short (2025/4-2025/12)」のように区別

3. 期首残高 (B/S) の年度間引き継ぎ (PHASE 0 期首) → 多年度連結時のスタート点として B/S は期首スナップショットを保持

4. 過去年度のデータ修正 (前期修正損益) → 多年度集計の再計算ロジック必要・updatedAt 列で再計算トリガー判定

5. 通貨単位の年度間変更 (将来の海外展開時) → 単位 conversion レイヤーを Aggregator に組み込み

6. 法人合併・分割で会計年度が複雑化 → 単一法人前提を文書化 (将来別案件・ADR-0009 で議論)

7. アーカイブタブの読込タイムアウト → ページネーション or キャッシュ層 (Phase A の設計判断ポイント)

8. 5 年累計 KPI (例: 5 年累計売上) → 同一会計基準の年度のみ集計・基準変更があった年度は警告表示

9. CF (キャッシュフロー計算書) の多年連結 → 期首残高 + 各期 ΔCF で再計算 (failure_patterns #34 と関連)

10. ヘッダー変更を含む年度間差異 (DDL 変更) → headerCompatibilityMap でマッピング

11. 案 B (統合タブ) のサイズ制限 → 1 タブ 1,000 万セル超過リスク回避・10 年で月次 P/L 12 行 × 100 科目 × 10 年 = 12,000 行 × 列数で警戒

12. MAS-067 多年計画 + MAS-177 多年実績の Y0 重複 → 「実績優先 / 計画優先」優先順位ルール (Q4 で議論)

Section 8. 実データ検証

シナリオ 1: bizlp 設立年度 (Y0 = 2026FY) のみで動作

• 過去年度なし状態で MultiyearRepository.findAll({periods: ['2025FY', '2026FY']}) が 2025FY 分は空配列・2026FY 分は当期データを返却
• 既存単年度ロジックとの互換動作を確認

シナリオ 2: 2 期目 (Y1) で過去 1 年実績取得

• findAll({sheetKey: '61_pl_monthly', periods: ['2025FY', '2026FY']}) が 2 年分マージ
• 行数 = 12 ヶ月 × 2 = 24 行 (P/L 月次・科目あたり)
• 各行の 会計年度 列 (案 B / C) または出典タブ (案 A) で年度識別可能

シナリオ 3: 5 期目で過去 5 年連結 P/L 表示

• cockpit に 5 年トレンド表示 (経常利益年次推移)
• 12 ヶ月 × 5 = 60 ヶ月分のデータを Aggregator が統合
• パフォーマンス検証 (キャッシュヒット時 < 200ms)

シナリオ 4: 税理士向け過去 3 期分財務諸表エクスポート

• 92_fs_pl / 91_fs_bs の年次サマリを過去 3 期分エクスポート
• PDF 化 (将来 MAS-021 連携)
• 年次サマリの整合性 (各年度の合計値が DDL 単年度集計と一致)

シナリオ 5: MAS-067 マルチイヤー計画 + MAS-177 実績連結

• Y-3 〜 Y+5 の連続トレンド (実績 + 計画) を 1 グラフで表示
• Y0 重複時は 実績優先 ルール (Q4 推奨案)
• MAS-067 v1.9 Phase E v3 の getSoloCEOY0Forecast() パターン踏襲

Section 9. 関連ドキュメント

• MAS-067 マルチイヤー計画ワークスペース — 計画側の連携先
• MAS-057 Solo CEO Cockpit — 多年トレンド表示先 (将来)
• MAS-002 期末スナップショット — 並行起票・本基盤を利用
• MAS-003 KPI ダッシュボード — 多年 KPI 追加先
• MAS-133 年度跨ぎアーカイブ機構 — 既存アーカイブ・本案件で吸収検討
• MAS-231 GAS 最適化パス 1 — パフォーマンス相互作用
• ADR-0009 活動領域分離戦略 — マルチテナント (将来)
• 失敗パターン #34 — 計画 B/S 構造的乖離 (多年実績取込時の整合性)
• CLAUDE.md — GAS ファイル番号体系・名前空間ルール

Section 10. 人間が検討すべき事項 (Q1-Q5)

Q1. アーキテクチャ案 A / B / C のいずれを採用するか

推奨: 案 C (ハイブリッド・Aggregator Layer)

理由:

• 既存破壊最小 + 物理移行容易 + 論理抽象化で再利用可能
• 段階的移行可能 (Phase A → B → C)
• トレードオフ: 抽象化レイヤー実装コスト (~200 行) は許容範囲

Q2. MAS-133 既存アーカイブ機構との関係

推奨理由:

• MAS-133 の責務 = 年度終了後アーカイブを本案件 MultiyearRepository が担う
• 重複機能の整理が運用シンプル化に寄与
• MAS-133 のシード migration は本案件 Phase B の migration に統合

Q3. マルチテナント対応 (組織 ID キー設計)

推奨理由:

• ADR-0009 でも複数組織前提は先延ばし
• 当初実装をシンプルに保つ
• 将来必要時に MultiyearRepository 抽象層に組織 ID キーを追加 (案 C ならスキーマ追加で対応可能)

Q4. MAS-067 多年計画 + MAS-177 多年実績の Y0 重複時の優先順位

推奨理由:

• MAS-067 v1.9 Phase E v3 で Y0 着地見込み (getSoloCEOY0Forecast) 実装パターン踏襲
• 「実績既経過月 + 残月計画」は monthly forecast の標準的アプローチ
• 経営判断の精度を実績データで担保

Q5. リリース順序 (Phase A〜C) の優先度

推奨: Phase A → Phase B → Phase C の順序を維持

運用ルール:

• 各 Phase 独立 PR
• 前 Phase 完了確認後に次 Phase 着手
• Phase A 完了時点で本案件の MVP として運用可能 (1 タブ検証で実証)

Section 11. 実装プロンプト

## Phase A: Aggregator + 1 タブ年度別シャーディング検証 (Opus)

### 対象ファイル
- 新規: `200_data/203_multiyear_repository.js` (~200 行・名前空間 MultiyearRepository)

### 公開 API
- `MultiyearRepository.findAll({periods, sheetKey})` — 多年度統合取得
- `MultiyearRepository.findCurrent({sheetKey})` — 単年度互換 (既存コード用)
- `MultiyearRepository.invalidateCache({sheetKey, period})` — キャッシュ無効化

### 検証手順
- 検証用 1 タブ (`61_pl_monthly_2025`) を手動作成
- `findAll({sheetKey: '61_pl_monthly', periods: ['2025FY', '2026FY']})` で 2 年分取得確認
- `findCurrent({sheetKey: '61_pl_monthly'})` で当期データのみ取得確認 (互換性)

### 単体テスト
- F177-01: findAll 単年度 (current のみ)
- F177-02: findAll 複数年度 (2 年)
- F177-03: findAll 存在しない年度 (空配列返却)
- F177-04: findCurrent 互換動作
- F177-05: invalidateCache 動作確認

---

## Phase B: 主要タブ年度別シャーディング展開 (Opus)

### 対象ファイル
- 拡張: `100_config/101_sys_config.js` (DDL 拡張)
  - `61_pl_monthly` / `71_bs` / `81_cf_actual` / `91_fs_bs` / `92_fs_pl` の 5 タブ
- 新規: `800_ops/824_migration_multiyear_data_foundation.js` (冪等性ガード)
  - 注: 番号は実装着手時に grep で再確認 (822 まで使用済 + MAS-336/337/338 予約)

### 移行手順
1. 既存 5 タブを年度別タブに分割 (`61_pl_monthly_2026FY` 等)
2. 当期タブ (`61_pl_monthly`) を当期データのみに整理
3. headerCompatibilityMap を `MultiyearRepository` に登録
4. 冪等性チェック (既に多年度形式の場合スキップ)

### 単体テスト
- F177-06: DDL 拡張で 5 タブ年度別生成
- F177-07: migration 冪等性 (2 回実行で同一結果)
- F177-08: headerCompatibilityMap 動作 (年度間ヘッダー差異吸収)
- F177-09: 主要 5 タブの multiyear 取得
- F177-10: MAS-133 アーカイブとの整合 (既存アーカイブタブの統合)

---

## Phase C: 既存ロジックの MultiyearRepository 経由化 (Opus)

### 対象ファイル
- 拡張: `600_report/601_datamart_ingest.js` 等の既存単年度処理
- 拡張: `200_data/202_repository.js` (連携層追加)

### 移行方針
- 既存 `OrderRepository.findAll()` 等を内部で `MultiyearRepository.findCurrent()` 呼び出しに移行
- 互換性確保 (findCurrent で旧来動作維持)
- 段階的に主要マートを `MultiyearRepository` 経由に切替

### 単体テスト
- F177-11: 既存マート再生成の回帰テスト
- F177-12: P/L マート (61_pl_monthly) の MultiyearRepository 経由化
- F177-13: B/S マート (71_bs) の MultiyearRepository 経由化
- F177-14: CF マート (81_cf_actual) の MultiyearRepository 経由化
- F177-15: 全主要マートの回帰テスト (Phase A 完了前後で同一結果)

---

## Phase D: MAS-067 / MAS-002 / MAS-003 連携 (各案件側で実装)

- MAS-067: `getMultiyearActuals` API を実装 (本案件 MultiyearRepository を呼び出し)
- MAS-002: 期末スナップショット保存先を本案件の年度別タブに切替
- MAS-003: 3 年 CAGR / 5 年累計 KPI 追加
- MAS-057: 多年トレンドパネル (cockpit v2.5+)

各案件側で個別 PR・本案件 Phase A〜C 完了後に着手

Section 12. 推奨実行モデル

Section 13. 変更履歴

Section 14. 仕様書作成プロンプト

# MAS-177: 多年度データ基盤 (Multiyear Data Foundation)

## frontmatter (先頭・必須)
```yaml
---
id: MAS-177
aliases: ["MULTIYEAR-DATA-FOUNDATION", "MULTIYEAR-DATA"]
type: Story
status: Open
---

</details>