給与変換ツール v0.1（KOT勤怠CSV → 給与大臣 受入CSV）

[yankubota]

有限会社櫻井運輸向け「給与変換ツール」一式の初版（v0.1）です。
KING OF TIME の勤怠CSVを給与大臣 NX Ver.4 Super の受入CSVへ変換し、毎月の4項目の目視転記をゼロにします。

DDD①（ドキュメント駆動開発）に従い、kot2kyuuyo/spec.md を先に作成し、それを唯一の正（SSOT）として実装しています。

⚠️ このPRの位置づけ（重要）

KOT・給与大臣の実サンプル未入手の状態での初版です。mapping.yaml の値はすべてプレースホルダ（仮）です。
確定が必要な13項目は spec.md §10 に一覧化しています。本運用の前に確定と承認が必要です（DoD の D-7 / D-8 が未達）。

変更内容

開発用 kot2kyuuyo/

ファイル	内容
spec.md	仕様書（SSOT）。用語集・機能仕様 ADD-01〜07・データ仕様・リスク・変更履歴・要確認一覧
mapping.yaml	変換ルール（設定）。仮値の行に「# 要確認」コメント
src/convert.py	変換ロジック本体（958行、機能IDと日本語コメント付き）
tests/make_dummy.py	ダミーKOT CSV・参照名簿の生成
tests/test_convert.py	自動テスト 50件
build.bat	exe化（テストが通らなければビルドしない）
README.md	再セットアップ手順

配布・運用用 給与変換/

入力/ 出力/ mapping.yaml 従業員マスタ_サンプル.csv README.txt（cp932/CRLF・早映子さん向け手順）
※ exe はビルド成果物のためコミットしていません（build.bat で生成）。

実装（P0：ADD-01〜07）

• ADD-01 入力読込 — 「入力」フォルダのCSVを1件特定。0件/複数件はどれを使うか推測せずエラー停止。文字コード自動判定（utf-8-sig → cp932 → utf-8）。原本はバイト列として読むだけで一切書き換えない。
• ADD-02 時間表記変換 — 10進と60進を別ロジックで実装。10進は小数部×60で分に換算し rounding（floor/round/none）で端数処理。文字列置換による 8.50 → 8:50 の誤変換をしない（テストで明示的に検証）。1E2 NaN Infinity --1 等は勤怠値として拒否。
• ADD-03 突合・整列 — 従業員コードで突合（氏名は不使用）、昇順整列。重複コードは合算も上書きもせず確認リストへ。
• ADD-04 列整形 — output_order の順に整列するホワイトリスト方式のため、マイナンバー等が入力に含まれていても受入CSVには出力されない。必須列の欠落は推測補完せず確認リストへ（突合キーの欠落のみエラー停止）。
• ADD-05 検算 — 書き出す直前のバイト列を出力と同じ文字コードで読み直し、H:MM を分に戻して合計を比較。1件でも不一致なら受入CSVを出力せず停止。文字コード・改行・列順・エスケープの不具合もここで検出できます。
• ADD-06 確認リスト — 空欄／想定外の値／在籍差分／検算不一致／必須列欠落／コード重複／コード空欄を列挙。自動修正は一切しません。 個人情報は従業員コードのみ記載。
• ADD-07 完了通知 — tkinter messagebox。GUI利用不可の環境では標準出力へフォールバックするため、テストがGUIに依存しません。

変換ルールはすべて mapping.yaml から読み、コードにハードコードしていません（後日サンプルで差し替えるだけで確定できる構造）。

テスト結果

$ python -m unittest discover -s tests
..................................................
Ran 50 tests in 0.363s

OK

10進/60進の時間変換・端数処理（floor/round/none）・検算の一致/不一致・確認リスト生成・空欄・在籍差分（双方向）・入力CSVの不変性（バイト列と更新日時）・入力0件/複数件のエラー停止・設定ファイルの検証を含みます。

ダミーデータでの実行結果：

従業員コード,出勤日数,総労働時間,深夜時間,法定外時間
1001,21,168:30,12:15,20:45
1002,20,160:00,0:00,15:30
1003,19,152:18,,8:00          ← 深夜時間が空欄（補完せず確認リストへ）
1004,22,176:45,30:30,24:15

（152.30 が 152:30 ではなく 152:18 になっている点が、10進変換が正しく効いている証拠です）

レビューで特にご確認いただきたい仕様判断

仕様に記載が無く、実装のために spec.md 側で定義した項目です。承認または修正指示をお願いします。

1. 在籍差分の判定方法（最重要） — 受入CSVは入力から生成されるため「出力側にのみ存在するコード」は原理的に発生せず、判定には給与大臣側の従業員コード一覧が別途必要です。roster_file（既定 給与変換/従業員マスタ.csv）を参照する方式にし、ファイルが無い場合はエラーにせず「スキップした」と確認リストに明記する仕様としました（spec.md ADD-06）。
2. output_columns の追加 — KOTの列名と給与大臣の列名は一致するとは限らないため、columns（入力側）と output_columns（出力側）を分けました。output_order は output_columns の値を並べたものです。
3. 60進の1桁小数 — 8.5 を「8時間50分」（右に0埋め）と解釈しています（spec.md ADD-02 §要確認12）。
4. rounding: none の挙動 — 分に端数が出る場合は自動処理せず変換不可とし、確認リストへ回します。
5. 検算不一致時の出力 — 受入CSVは出力しませんが、原因調査のため確認リストは出力します（ADD-05 と ADD-06 の両立）。
6. 参照名簿の置き場所 — 「入力」フォルダ内に置くと ADD-01 が「CSVが2件ある」と判定するため、フォルダ外を既定としました（内に置かれた場合は入力候補から自動除外）。

DDDチェックリスト

• このコード変更に対応する仕様書の更新は済んでいるか（spec.md を先に作成）
• 変更履歴に版数・日付・対応IDを記録したか（§9 に v0.1 / 2026-08-01 / ADD-01〜07）
• 完了条件（DoD）のどの項目に対応する変更か明示したか（§4 D-1〜D-6 達成、D-7/D-8 は未達）
• データ破壊を伴う変更か（該当なし。入力CSVは読み取り専用、出力は再生成可能な導出値）
• 仕様書にない振る舞いを推測で実装していないか（上記6項目を spec.md に明記のうえ実装、要承認）
• 用語（ユビキタス言語）が仕様書・UI・コードで一致しているか（§2.5 用語集と識別子を対応）

次の作業

1. 上記「レビューで特にご確認いただきたい仕様判断」の承認
2. サンプル入手後、spec.md §10 の🟡要確認13項目を確定 →「プロンプト②」で mapping.yaml を差し替え
3. 8月給与での並走検証（手入力と自動変換の全件突合）→ 一致確認後、9月に本運用へ

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
test	Ready	Preview	Aug 1, 2026 2:26am