MAS-158: 給与計算SaaSデータ取込

概要

目的

給与計算SaaS（freee人事労務 / MFクラウド給与 等）のCSVエクスポート or API から、従業員別の月次給与データ（基本給・各種手当・源泉税・住民税・社保従業員負担・社保会社負担・差引支給額）を取得し、22_bud_headcount の各列に自動反映する。

現状の手入力（源泉税額・社保額等）を置き換え、手入力ミスの排除と月次の転記作業ゼロ化を実現する。

取込方式

Phase 1: CSV取込

1. SaaS の給与明細 CSV を Google Drive にアップロード
2. 管理ID で 22_bud_headcount の従業員行と照合
3. 各控除額列を上書き

Phase 2（将来）: API取込

freee人事労務 API or MFクラウド給与 API で月次確定後に自動取得。OAuth2 認証は MAS-155（Outlook連携）と同様のパターン。

既存シミュレーション機能への影響分析

影響なし（安全）と判定できる項目

注意が必要な項目

RPA のINV生成制御の仕組み

22_bud_headcount
  ├── 開始年月: INV 生成の開始月
  ├── 終了年月: INV 生成の終了月（退職等）
  └── 最終起票年月日: RPA が「ここまで生成済み」と判定する上限

RPA 月ループ:
  curHcYm = 開始年月
  while (curHcYm <= rowTargetYm) {
    if (終了年月 && curHcYm > 終了年月) break;
    if (isDuplicate_(摘要)) → SKIP
    else → INV 生成
  }

推奨する HC 行の構成

SaaS から過去実績を取り込む場合の 22_bud_headcount の構成例:

管理ID   氏名       開始年月   終了年月   最終起票年月日   源泉税額  社保額  ...
EMP001   田中太郎   2025-04    2026-03    2026-03          ← SaaS確定値
EMP001   田中太郎   2026-04    (空)       2026-12          ← 将来シミュレーション用

• 過去分行: SaaS から取得した確定値。終了年月 = 最終月、最終起票年月日 = 同月
• 将来分行: 手入力の見込み値。既存のまま維持

検討事項

関連ドキュメント

実装プロンプト（Claude Code 用）

あなたはGAS会計システム(bizlp-gas-accounting)のシニア開発者です。
案件 MAS-158「給与計算SaaSデータ取込」を Phase 1（CSV 取込）のみ実装してください。
Phase 2（API 取込）は別案件として後日実装します。

## Phase 1: 実行前タスク（Read で実物を確認。推測しない）

1. `500_import/501_cc_importer.js` / `502_bank_importer.js` — CSV 取込の既存パターン（ファイル読込・パース・対象シートへの append）を確認。MAS-158 はこのパターンを踏襲する。
2. `500_import/502_receipt_reader.js` — Drive フォルダからファイル取得する `DriveApp.getFolderById(...).getFiles()` パターンを確認。
3. `100_config/101_sys_config.js` — `schemas` の `BUD_HC` (= 22_bud_headcount) ヘッダー定義を特定し、以下の列の有無を確認:
   - `管理ID` / `氏名` / `開始年月` / `終了年月` / `最終起票年月日`
   - `基本給` / `諸手当` / `源泉税額` / `住民税額` / `社保_従業員負担` / `社保_会社負担` 等の控除系列（列名の正確な綴りを控える）
4. `000_infra/003_contracts.js` — 22_bud_headcount 対応の DTO（`HeadcountDTO` 相当）が存在するか確認。
5. `200_data/202_repository.js` — `HeadcountRepository` または相当のリポジトリの `findAll()` / `save()` シグネチャを確認。
6. `400_domain/401_rpa_hc.js` — HC RPA の `isDuplicate_` 呼び出し箇所と摘要パターン `【RPA:HC】{年月} {氏名} {種別}` を確認。CSV 取込後に過去行を追加した場合の INV 二重生成リスクを正確に把握。
7. `000_infra/001_env.js` — 新規プロパティ `HC_CSV_FOLDER_ID` のアクセサを追加する雛形として `receiptFolderId` を参照。

## Phase 2: 修正対象ファイル

- `000_infra/001_env.js` — `hcCsvFolderId()` / `setHcCsvFolderId()` アクセサ追加
- `100_config/101_sys_config.js` — メニュー追加（「📥 給与CSV取込」）+ 既存 BUD_HC スキーマ確認（列追加が必要なら schemas 更新）
- `500_import/503_hc_saas_importer.js`（新規） — CSV パーサ + 22_bud_headcount への反映ロジック
- `900_test/901_test_runner.js` — 重複取込・マッピング整合のテスト追加

## Phase 3: 実装内容

### Step 1: SaaS 列マッピング定義

`503_hc_saas_importer.js` 冒頭に定数として SaaS 種別ごとの列マッピングを定義する（アダプター形式）:

```js
const HC_ADAPTERS = {
  'freee': {
    detect: (headers) => headers.includes('従業員番号') && headers.includes('支給年月'),
    employeeId: '従業員番号',
    ym: '支給年月',           // フォーマット: YYYY-MM or YYYY/MM/DD
    baseSalary: '基本給',
    withholding: '源泉所得税',
    residentTax: '住民税',
    socialEmployee: '社会保険料(従業員負担)',
    socialCompany: '社会保険料(会社負担)',
  },
  'mfcloud': { /* 同様 */ },
};
```

### Step 2: CSV 取込関数

1. `importHcCsvFromDrive()`: `Env.hcCsvFolderId()` のフォルダから未処理 CSV を取得
2. 1ファイルずつパース → `HC_ADAPTERS` の `detect` でアダプター自動選択
3. 管理ID + 支給年月 で 22_bud_headcount の対象行を特定
   - 対象行の条件: `管理ID` 一致 AND `開始年月 ≤ 支給年月 ≤ (終了年月 || 支給年月)`
4. 控除系列を上書き（既存値があれば警告ログ + 上書き）
5. 取込済 CSV は Drive 内で `processed/` サブフォルダに移動（冪等性）

### Step 3: 二重生成防止（最重要）

- CSV 取込後に HC RPA を再実行する場合、既存 INV の摘要と新規 INV の摘要が一致すれば `isDuplicate_` で弾かれる。
- ただし、HC 行の `開始年月` / `終了年月` / `最終起票年月日` を CSV 取込時に**変更しない**こと。これらは RPA の生成範囲を決める重要な列。
- 過去分行を新規追加する場合は、取込処理ではなく手動で専用行を用意する運用とする（仕様書「推奨する HC 行の構成」を参照）。

### Step 4: メニュー + UI

- 「📥 データ取込」メニューに `.addItem('📥 給与CSV取込', 'importHcCsvFromDrive')` 追加
- 初回セットアップ用に `.addItem('⚙️ 給与CSVフォルダ設定', 'setHcCsvFolderUi')` も追加

### Step 5: テスト追加

`901_test_runner.js` に T10 を追加:

- T10-01: 同一 CSV を 2 回取込しても行数が変わらない（冪等性）
- T10-02: freee / mfcloud 両フォーマットが自動判別される
- T10-03: 管理ID が 22_bud_headcount に存在しない CSV 行はスキップ + 警告ログ
- T10-04: 取込後に HC RPA を再実行しても INV 二重生成されない（`isDuplicate_` の摘要完全一致を確認）

## 制約

- Phase 2（API 取込）には着手しない。本案件は CSV 取込のみ。
- 22_bud_headcount の `開始年月` / `終了年月` / `最終起票年月日` 列を CSV 取込で**自動更新しない**（HC RPA の生成範囲保護のため）。
- 列番号ハードコード禁止。すべてヘッダー名ベースで取得。
- マイナンバー等の機密情報は取込対象外（MAS-267 参照）。CSV パース時に不要な列は破棄。

## エッジケース

| 条件 | 動作 |
|------|------|
| CSV に管理ID 列がない | エラーログ + CSV ファイルスキップ（processed に移動しない） |
| 22_bud_headcount に管理ID が存在しない | 警告ログ + 該当行スキップ |
| 支給年月が `開始年月` より前 / `終了年月` より後 | 警告ログ + 該当行スキップ |
| 既存値があるセルを上書き | 警告ログ + 上書き実施（CSV を正とする） |
| 同一 CSV の再取込 | `processed/` に移動済なので通常起きない。手動コピーで発生した場合は冪等性で同一結果 |
| 数値列に非数値が混入 | 警告ログ + 0 で取込（合計計算を壊さない） |

## 実データ検証（実装直前に実施）

- 実際の freee 人事労務 / MF クラウド給与の CSV サンプルを取得し、ヘッダー名の正確な綴りを確認（特に `社会保険料(従業員負担)` の括弧・半角全角）
- 22_bud_headcount の既存ヘッダーと SaaS 側列名のマッピング表を作成
- `HC_ADAPTERS.detect` のヘッダー一致条件を実データで検証

## 動作確認

1. `npm run push:dev` → デプロイ
2. Drive にテスト用 CSV（3 名 × 1 ヶ月分）を配置し、メニューから取込実行
3. 22_bud_headcount の該当行に控除額が反映されていること
4. 取込済 CSV が `processed/` サブフォルダに移動していること
5. 同じ CSV を再配置して再取込 → 0 件更新（冪等性）
6. HC RPA を実行し、32_wrk_invoice に重複 INV が生成されないこと
7. T10 テスト全項目 PASS

### 拡張思考の使用状況

| フェーズ | 拡張思考 | 備考 |
|---------|---------|------|
| Phase 1（設計） | あり | SaaS アダプター設計・二重生成防止策の確定 |
| Phase 2（実装） | なし | 501/502_importer パターンの踏襲 |

推奨実行モデル

変更履歴