MAS-218: タイムトラッキング導入 + R&D / クライアントワーク時間分離記録ルール整備

概要

目的

bizlp の売上は 100% クライアントワーク（F）で発生しており（初年度 7 ヶ月で 1,000 万円）、bizlp-gas-accounting は売上ゼロの R&D 投資。この構造ゆえに、研究開発税制の役員報酬按分（Gemini A 派 積極算入）を主張するには F 時間の正確な分離記録が絶対条件。

R&D 税制効果は 3 年累計 約 43 万 〜 205 万円（売上シナリオ × 賞与パターン次第）。基準ケース（売上 1,800 / 1,800 万 × 賞与 300 万）で累計 約 105 万円。記録がなければ A 派（積極算入）を主張できず B 派（保守除外・API 代のみ計上）しか選べず、累計 22 万円程度しか達成できない（差分 約 83 万円）。即時着手が合理的。

加えて、MAS-062 PSF プロフィタビリティ拡張の稼働率（F-ClientWork ÷ 総労働時間）算出 + MAS-061 Cash ETR の R&D 控除エビデンス + MAS-141 節税シミュレーターの実時間ベース判断 など、複数 FP&A 案件の前提基盤となる。

現在のコード

本案件は新規確立の運用基盤のため、既存コードの利用箇所は薄い。新規実装は CSV 取込パイプライン + R&D 比率集計エンジンのみ。

ADR-0009 Phase 1 アクション #3（既決）

ADR-0009 §4-3 で「タイムトラッキング（Toggl Track 等）の導入」を Phase 1 アクション必須項目として明記済。本案件はその具体実装。

R&D 税制試算 SSoT（既存）の参照

docs/_internal/biz/rd_tax_credit_estimation_2026.md で 3 シナリオ × 4 賞与パターンのマトリクス + ケース C（R&D 50% 按分）の累計控除額を提示。本案件のタグ設計はこの試算前提と整合。

既存 Constants（既存）の利用関数

MAS-061 / MAS-062 連携先（仕様書完了・実装未）

• MAS-061 Cash ETR: 本案件の RdRatioRepository.findByFiscalYear() を呼出して R&D 控除エビデンスを自動エクスポート
• MAS-062 PSF: 本案件の TimeEntryRepository.findByTagAndPeriod('F-ClientWork', ...) を呼出して稼働率算出

修正方針

Step 1 — タグ体系 5 タグ確定（ADR-0009 §4-3 準拠）

Constants.TOGGL_TAGS に 5 値を定数化。5 タグ以外を Toggl 上で使ったら 503_toggl_importer.js で WARN ログを出す（タグ体系の規律維持）。

Step 2 — Toggl Track 設定 + 日次運用

運用ガイド: docs/_internal/biz/time_tracking_operation_guide.md を新設し、上記運用ルールを明文化（spec 起草と同 PR で作成）。

Step 3 — 月次 CSV エクスポート + 取込パイプライン

// 500_import/503_toggl_importer.js (純粋関数 + IIFE 名前空間)

var TogglImporter = (function () {

  /**
   * Toggl Track からエクスポートした CSV を 38_trn_time_entry にインポート
   * @param {string} csvContent  Toggl エクスポート CSV 全文
   * @param {Object} options
   * @returns {{importedCount, warnings, period}}
   */
  function importCsv(csvContent, options) {
    var rows = _parseTogglCsv_(csvContent);
    var validTags = Constants.TOGGL_TAGS;
    var warnings = [];

    var entries = rows.map(function (r) {
      // タグ検証: 5 タグ以外は WARN
      if (validTags.indexOf(r.tag) < 0) {
        warnings.push('Unknown tag: ' + r.tag + ' (row: ' + r.startTime + ')');
        r.tag = 'unknown';  // フィールド汚染を防ぐ
      }
      return {
        tag: r.tag,
        project: r.project,
        startTime: r.startTime,
        endTime: r.endTime,
        durationHours: r.durationHours,
        description: r.description,
      };
    });

    var importedCount = TimeEntryRepository.bulkInsert(entries);
    return {
      importedCount: importedCount,
      warnings: warnings,
      period: { from: rows[0].startTime, to: rows[rows.length-1].endTime },
    };
  }

  return { importCsv: importCsv };
})();

取込フロー:

1. 月末に Toggl Track で CSV エクスポート（Reports → Detailed → Export CSV）
2. Drive 上の bizlp/time-tracking/YYYY-MM.csv に保存
3. メニュー「⏱️ Toggl 月次取込」実行 → Drive 直接読込 + 38_trn_time_entry 更新
4. 同時に RdRatioCalculator.calcMonthly() 実行 → 39_kpi_rd_ratio 更新

Step 4 — R&D 比率の月次集計

// 400_domain/4XX_rd_ratio_calculator.js (純粋関数・本案件で新設は最小限・主に Repository ラッパー)

var RdRatioCalculator = (function () {

  /**
   * @param {string} yearMonth   "2026-04"
   * @returns {{
   *   totalHours, rdHours, rdRatio,
   *   tagBreakdown: {D-RnD, C-ProductDev, B-SelfOps, A-Corporate, F-ClientWork},
   *   highLevelEligible
   * }}
   */
  function calcMonthly(yearMonth) {
    var entries = TimeEntryRepository.findByMonth(yearMonth);
    var tagBreakdown = _aggregateByTag_(entries);
    var totalHours = _sumAll_(tagBreakdown);
    var rdHours = tagBreakdown['D-RnD'] + tagBreakdown['C-ProductDev'] * 0.5;  // ケース C 按分
    var rdRatio = totalHours > 0 ? rdHours / totalHours : 0;

    // 試験研究費 / 売上 ≥ 10% で高水準要件該当（売上は別途集計値を引数で渡す）
    var threshold = Constants.getParam('N42_RD_HIGH_LEVEL_THRESHOLD_RATIO', 0.10);
    var highLevelEligible = rdRatio >= threshold;

    return {
      totalHours: totalHours,
      rdHours: rdHours,
      rdRatio: rdRatio,
      tagBreakdown: tagBreakdown,
      highLevelEligible: highLevelEligible,
    };
  }

  return { calcMonthly: calcMonthly };
})();

39_kpi_rd_ratio シートには月次集計結果を 1 行/月で蓄積（年累計 + 高水準要件到達フラグも併記）。

Step 5 — 過去分（2025-12〜2026-04）の遡及計上

記録開始前の約 4 ヶ月分は以下のエビデンスで推計:

遡及集計スクリプト: scripts/n42_retroactive_aggregator.mjs（Node.js）を新設して git log + 請求書 PDF/CSV を読み込み、推計値を 38_trn_time_entry に bulk insert。実行は spec 起草後 1 回のみ（冪等性確保のため source = 'retroactive_estimate' 列で識別）。

Step 6 — メニュー統合 + 月次運用フロー

000_infra/002_constants.js の MENU_DEFINITION:

📊 マート更新 カテゴリに追加:

{ label: '⏱️ Toggl 月次取込 + R&D 比率更新 (N-42)', funcName: 'importTogglMonthly', description: 'Drive 上の Toggl CSV を取込み 39_kpi_rd_ratio を更新 (N-42)' },

月次運用:

1. 月初（前月分集計）: Toggl Reports → CSV エクスポート → Drive 保存
2. メニュー「⏱️ Toggl 月次取込」実行
3. 39_kpi_rd_ratio の前月行を確認・税理士共有用に PDF エクスポート（年次決算期）

影響範囲

注意事項

1. Toggl 個人プランの制約: Free プランは 5 プロジェクト・3 メンバーまで。一人法人なら Free で十分。商用化時にチームメンバーが増えたら Starter（月 $9）へ移行。spec は Free プラン前提で記述。

2. クライアントワーク記録デバイスの制約: 顧客貸与 PC では bizlp ツール（Toggl も含む）の起動が NDA で禁止のケースあり。個人スマホ or 別 PC からの記録を必須運用ルール化。time_tracking_operation_guide.md で明示。

3. タグ体系の規律維持: 5 タグ以外を Toggl 上で使ったら 503_toggl_importer.js で WARN ログ。運用が緩むと R&D 比率算出が破綻するため、月次取込時のレポートで未知タグを必ず確認。

4. 過去分遡及計上の主張強度: Toggl 記録（リアルタイム）vs git log 推計（事後）で、税務調査時の主張強度に差がある。過去 4 ヶ月分の遡及計上範囲は顧問税理士と事前協議して決定。spec は推計手法のみ提供。

5. タイマー記録漏れ時の事後記入ルール: 当日中の事後記入は許容、翌日以降の事後記入は WARN（記録信頼性低下）。38_trn_time_entry に recordedAt 列を追加し、エントリ実時刻と入力時刻の差を集計（5% 超で警告）。

6. 税理士協議タイミング: 1 回目 = 本案件着手時（タグ体系 + 遡及計上範囲）/ 2 回目 = 初回決算期（2027 春想定）/ 3 回目 = 高水準要件到達見込み時（試験研究費 ≥ 売上 10%）。協議結果は docs/_internal/biz/ に時系列で保管。

7. クライアントワーク案件別の粒度: Toggl Project 機能で「クライアント-A」「クライアント-B」と分けるか、Tag のみで対応するか。spec v1 は Tag のみ（5 プロジェクト制限内に収める）。商用化時の顧客別売上配賦が必要になったら v2 で Project 拡張。

8. failure_patterns #25 遵守（並列実装対称性）: 503_toggl_importer.js は既存の 502_bank_importer.js（CSV 取込）と並列対称。importCsv 関数命名・WARN ログパターン・bulk insert ロジックを揃える。

9. failure_patterns #18-#20 遵守（命名造語禁止）: 関数名 importCsv / calcMonthly / TogglImporter は既存命名と整合。「Toggl」は商品名・「R&D」は業界標準略称で新語ではない。Read で既存ファイルに同名関数がないことを着手時に裏取り。

10. failure_patterns #26 遵守: appsscript.json の OAuth スコープは変更不要（既存 Drive スコープで CSV 読込可）。

11. 試験研究費の勘定科目分離（ADR-0009 §4-4）: API 利用料 / 開発ツール代は会計上「試験研究費」として独立集計し、通常の販管費と明確に分離。勘定科目マスタ（11_mst_account）にサブ分類「試験研究費」属性を追加するのは MAS-063 の営業外サブ分類拡張と同じパターン（別 PR 推奨）。

12. 役員報酬按分の判断基準: A 派（積極算入・R&D 比率 × 役員報酬）vs B 派（保守・API 代のみ計上）vs C 派（中間 50% 按分）。spec は C 派 default（rd_tax_credit_estimation_2026.md の基準ケース準拠）。税理士協議で A or B に切替可能。

13. 高水準要件 150 万円閾値: 試験研究費 ≥ 売上 10% かつ ≥ 150 万円で高水準要件適用。N42_REQUIRED_RD_ANNUAL_AMOUNT で閾値管理。39_kpi_rd_ratio 月次集計でこの到達見込みをトラック。

14. CSV エクスポート形式の依存: Toggl Track の Detailed Export CSV 形式に依存（列順・列名）。Toggl 側の仕様変更時は _parseTogglCsv_ の修正必要。spec v1 は 2026-04 時点の Toggl エクスポート形式準拠。

15. GAS 6 分制限対応: 月次 1 ヶ月分の CSV 取込（1 日数時間 × 30 日 = 約 100 entries）は GAS 6 分以内で完了想定。年次取込（1,200 entries）は 60 秒以内。bulkInsert で Range.setValues 一発書込みで最適化。

エッジケース

実データ検証

1. 基準ケース（売上 1,800 万 / 賞与 300 万）の R&D 比率期待値

rd_tax_credit_estimation_2026.md ケース C（R&D 50% 按分）の前提と整合させて検証:

平均 19.3% > 10% で高水準要件該当。

2. 遡及計上スクリプトの精度検証

過去 4 ヶ月分（2025-12〜2026-04）で git log から R&D 推計時間を算出し、後発 Toggl 記録（2026-05 以降）と比較。±20% 以内で一致を合格基準とする（推計の限界を考慮した広めの許容幅）。

3. 試験研究費 / 売上比率の月次推移

39_kpi_rd_ratio で 12 ヶ月分の推移を可視化し、年累計が 10% 超 + 150 万円超を維持できているか確認。基準ケースで年 R&D 時間 約 504h（42h × 12）→ 役員報酬 600 万 × 19.3% 按分 = 約 116 万 + API 代等 50 万 = 約 166 万 > 150 万達成。

4. MAS-062 PSF 稼働率算出との整合

TimeEntryRepository.findByTagAndPeriod('F-ClientWork', ...) の戻り値を MAS-062 PSF の稼働率分母と比較し、±1h 一致を合格基準とする。

5. エッジケース検証（単体テスト N42-01〜N42-13）

エッジケースセクションの 13 項目それぞれを 1 テストケースとして 901_test_runner.js に追加。

関連ドキュメント

人間が検討すべき事項

1. Toggl Track の選定（vs Clockify / Harvest 等）: spec は Toggl default。Clockify は無料で多機能だが UI が複雑。Harvest は請求機能込みだが有料。個人スマホアプリの完成度で Toggl 推奨。最終判断はユーザーが実機テスト。

2. タグ体系の粒度: 5 タグ採用したが、C-ProductDev を C-Spec（仕様書）/ C-Code（実装）に分けるか。spec v1 は 5 タグで開始、運用 3 ヶ月後に細分化検討。

3. クライアントワーク時間の記録デバイス: 個人スマホアプリ vs 別 PC。個人スマホアプリが運用負荷最小。顧客貸与 PC が制限されている前提で spec 記述。

4. 過去 4 ヶ月分の遡及計上の強度: N42_RETROACTIVE_GIT_HOURS_PER_COMMIT の default 1.5h。保守的に 1.0h vs 積極的に 2.0h。税理士協議で確定。

5. タイマー記録漏れ時の事後記入ルール: 翌日以降の事後記入を許容するか禁止するか。spec は「許容するが WARN + 5% 超でアラート」を採用。商用化時のチームメンバー教育コンテンツ化。

6. 税理士協議タイミング: 着手時 / 決算期 / 高水準要件到達見込み時の 3 回。協議費用（時給 1.5 万 × 1h × 3 回 = 4.5 万）を予算に織込。

7. クライアントワーク案件別の粒度を Toggl Project 機能で管理するか: spec v1 は Tag のみ（Free プラン制限内）。商用化時の顧客別売上配賦が必要になったら v2 で Project 拡張。

8. 役員報酬按分の判断（A / B / C 派）: spec は C 派 default、税理士協議で A or B に切替可能。A 派採用なら累計 205 万円、B 派なら 22 万円、C 派なら 105 万円（試算 SSoT 参照）。

9. 試験研究費の勘定科目分離（ADR-0009 §4-4）の実装タイミング: 本案件と同時 vs 別 PR。spec は別 PR 推奨（11_mst_account 拡張は MAS-063 営業外サブ分類と同パターンで統合）。

10. 遡及計上スクリプトの言語選択: Node.js（scripts/n42_retroactive_aggregator.mjs）vs Python。spec は Node.js 採用（既存 scripts/ パターン整合）。

11. 39_kpi_rd_ratio の DDL 管理 vs 動的生成: spec は DDL 管理を default（setupAllSchemas で再作成）。動的生成にすると履歴が消える危険あり。

12. Toggl 仕様変更時の対応: CSV 形式変更時の _parseTogglCsv_ 修正フロー。テスト N42-04（CSV パース失敗）でリグレッション検出。

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

Claude Sonnet 4.6 推奨。CSV 取込 + 集計 + 運用ガイド作成の中難易度。税務的判断は人間レビュー必須。

## 案件
MAS-218 — タイムトラッキング導入 + R&D / クライアントワーク時間分離記録ルール整備

## 事前調査（必ず Read する）
1. `docs/dev/dev_mas-218_time_tracking.md` 全文（本仕様書）
2. `docs/adr/0009-separation-strategy.md` §4-3（Phase 1 アクション #3）
3. `docs/_internal/biz/rd_tax_credit_estimation_2026.md` 全文（税制試算 SSoT）
4. `500_import/502_bank_importer.js` 全文（並列実装の手本）
5. `200_data/202_repository.js` BankImporterRepository 実装パターン
6. `100_config/101_sys_config.js` DDL 定義パターン
7. `000_infra/002_constants.js` getParam / Constants 定数追加パターン
8. `docs/dev/dev_mas-061_cash_etr_tracking.md` / `dev_mas-062_psf_profitability_extension.md`
   — 連携先のデータ呼出 API 仕様
9. `docs/_internal/failure_patterns.md` #18-#20 / #25 / #26

## 実装対象

1. `500_import/503_toggl_importer.js` 新規（IIFE 名前空間 TogglImporter）:
   - importCsv(csvContent, options) — メイン API
   - 内部ヘルパ: _parseTogglCsv_ / _validateTags_ / _normalizeEntry_

2. `100_config/101_sys_config.js` 拡張:
   - 38_trn_time_entry DDL 追加（列: tag, project, startTime, endTime, durationHours, description, source, recordedAt）
   - 39_kpi_rd_ratio DDL 追加（列: yearMonth, totalHours, rdHours, rdRatio, tagBreakdownJson, highLevelEligible）

3. `200_data/202_repository.js` 拡張:
   - TimeEntryRepository（findByMonth / findByTagAndPeriod / bulkInsert）
   - RdRatioRepository（findByYearMonth / findByFiscalYear / save）

4. `400_domain/4XX_rd_ratio_calculator.js` 新規（小規模・約 60 行）:
   - RdRatioCalculator.calcMonthly(yearMonth)

5. `000_infra/002_constants.js` 拡張:
   - TOGGL_TAGS 定数追加（5 値）
   - MENU_DEFINITION に「⏱️ Toggl 月次取込」追加

6. `03_sys_params` の 6 キー追加（default は Constants.getParam の第 2 引数）

7. `scripts/n42_retroactive_aggregator.mjs` 新規（Node.js）:
   - git log + 請求書 PDF/CSV から過去 4 ヶ月分を推計
   - source = 'retroactive_estimate' で bulk insert（冪等）

8. `docs/_internal/biz/time_tracking_operation_guide.md` 新規:
   - 5 タグ体系の用途定義
   - Toggl Track Free プラン設定手順
   - 日次運用ルール（タイマー起動 / 個人スマホ記録 / 5% 超事後記入アラート）

9. `900_test/901_test_runner.js` に N42-01〜N42-13 単体テスト

## 動作確認
1. サンプル CSV（10 entries）の取込で 38_trn_time_entry が正確に更新
2. 5 タグ以外を含む CSV で WARN ログ出力
3. 月次集計で R&D 比率算出（基準ケースで 19.3% ±5%）
4. 過去分遡及スクリプトで git log から推計値が ±20% 以内
5. MAS-062 PSF 稼働率算出との F-ClientWork 集計が ±1h 一致
6. エッジケース 13 項目すべて想定通り

## デプロイ
1. dev で push:dev → メニュー「⏱️ Toggl 月次取込」実行 → 38/39 シート確認
2. Go なら push:prod
3. コミット: feat(MAS-218): タイムトラッキング導入 (Toggl 取込 + R&D 比率月次集計 + 過去分遡及スクリプト)

## failure_patterns チェック
- #18-#20: TogglImporter / importCsv / RdRatioCalculator を Read で裏取り
- #25: 502_bank_importer と並列対称（CSV 取込 + bulk insert + WARN ログ）
- #26: appsscript.json は変更なし

推奨実行モデル

変更履歴