desktop/njts-accounting-core

Fork 0

Files

admin a2d7b54cd3 帳票出力作成

2026-02-01 20:13:52 +09:00

7.5 KiB

Raw Permalink Blame History

📄 账票出力機能 - クイックスタートガイド

概要

給与・賞与の账票出力機能を実装しました。ユーザーは期間、従業員、支払タイプを選択してプレビューまたはCSV出力ができます。

実装内容

1. 新しいTab追加

payroll-calculation.html の「給与計算」「賞与計算」タブ横に「📄 账票出力」タブを追加しました。

2. フロントエンド実装 (payroll-calculation.html)

UI要素

期間選択: 開始年月（必須）、終了年月（任意）
従業員選択: チェックボックス一覧、全選択/全解除ボタン、選択数表示
支払タイプ: ラジオボタン（給与・賞与両方/給与のみ/賞与のみ）
操作ボタン: プレビュー、CSV出力
結果表示: 摘要と詳細データ（隠れた状態で用意）
無データアラート: モーダルダイアログ

JavaScript関数

// 従業員リスト読み込み＆表示
loadVoucherEmployees();

// 従業員選択数更新
updateVoucherEmployeeCount();

// 全選択
selectAllVoucherEmployees();

// 全解除
clearAllVoucherEmployees();

// 選択中の従業員IDを取得
getSelectedVoucherEmployees();

// 条件検証＆API呼び出し
previewVouchers();

// 結果表示
displayVoucherResults(result);

// 無データアラート表示
showNoDataAlert(message);

// CSV出力
exportVouchersCSV();

3. バックエンド実装 (backend/app/payroll/vouchers/)

新規ファイル

router.py (165行): 5つのAPI端点
schemas.py (113行): Pydanticデータモデル
service.py (445行): ビジネスロジック、DB クエリ

API端点

1. 従業員リスト取得

GET /payroll/vouchers/employees

レスポンス:
{
  "total": 5,
  "employees": [
    {"id": 1, "code": "E001", "name": "田中太郎"},
    {"id": 2, "code": "E002", "name": "山田花子"},
    ...
  ]
}

2. 账票エクスポート（メイン）

POST /payroll/vouchers/export

リクエスト:
{
  "start_year": 2026,
  "start_month": 1,
  "end_year": 2026,
  "end_month": 1,
  "employee_ids": [1, 2],
  "voucher_type": "all",  // or "salary" or "bonus"
  "format": "preview"      // or "csv"
}

レスポンス (成功):
{
  "status": "success",
  "has_data": true,
  "message": "✓ 成功查詢: 2位従業員有數據",
  "summary": [
    {
      "employee_id": 1,
      "employee_code": "E001",
      "employee_name": "田中太郎",
      "has_salary_data": true,
      "has_bonus_data": false,
      "salary_count": 12,
      "bonus_count": 0,
      "salary_months": ["2026-01", "2026-02", ...],
      "bonus_months": []
    }
  ],
  "data": {
    "salary": [...],
    "bonus": [...]
  }
}

レスポンス (無データ):
{
  "status": "no_data",
  "has_data": false,
  "message": "選定條件下、沒有找到任何數據。請檢查日期範圍和従業員選擇。"
}

使用手順

テスト環境での実行

1. バックエンドサーバー起動

cd backend
python -m uvicorn app.main:app --reload --port 8000

2. ブラウザでアクセス

http://localhost/payroll-calculation.html

3. 使用フロー

「📄 账票出力」タブをクリック
従業員リストが自動読み込み
開始年月 を選択 (必須)
終了年月 を選択 (任意 - 単月の場合は開始年月のみ)
従業員を選択 (複数選択可、全選択/全解除機能あり)
支払タイプを選択 (デフォルト: 給与・賞与両方)
「プレビュー」ボタンをクリック
結果確認後「CSV出力」でダウンロード

エラーシナリオ

無データの場合

モーダルダイアログが表示
メッセージ: 「選定條件下、沒有找到任何數據。請檢查日期範圍和従業員選擇。」
OK ボタンで閉じる

部分的なデータの場合

データがある従業員のみ結果表示
摘要で「部分成功」と表示
給与/賞与の有無が明記

データベースクエリ構造

給与データ取得

SELECT
  e.id, e.code, e.name,
  mp.payroll_year, mp.payroll_month,
  mp.gross_salary, mp.total_deductions, mp.net_salary
FROM employees e
JOIN monthly_payroll mp ON e.id = mp.employee_id
WHERE e.id IN (employee_ids)
  AND (mp.payroll_year * 100 + mp.payroll_month) >= start_ym
  AND (mp.payroll_year * 100 + mp.payroll_month) <= end_ym
ORDER BY mp.payroll_year, mp.payroll_month

賞与データ取得

SELECT
  e.id, e.code, e.name,
  bp.bonus_year, bp.bonus_month,
  bp.bonus_amount, bp.tax_amount, bp.net_bonus
FROM employees e
JOIN bonus_payments bp ON e.id = bp.employee_id
WHERE e.id IN (employee_ids)
  AND (bp.bonus_year * 100 + bp.bonus_month) >= start_ym
  AND (bp.bonus_year * 100 + bp.bonus_month) <= end_ym
ORDER BY bp.bonus_year, bp.bonus_month

CSV出力フォーマット

データ,従業員コード,従業員名,年月,支給額,控除額,差引支給額
给与,E001,田中太郎,2026-01,250000,50000,200000
给与,E001,田中太郎,2026-02,250000,50000,200000
賞与,E001,田中太郎,2025-12,500000,100000,400000

テストケース

✓ テスト完了

従業員リスト取得: 成功
給与データ取得: 成功（複数月、複数従業員）
賞与データ取得: 成功
混合データ取得: 成功（給与＋賞与）
無データ検出: 成功（適切なエラーメッセージ）
年跨ぎ対応: 成功（例: 2025-12 ～ 2026-03）

トラブルシューティング

「従業員リストが表示されない」

→ タブをクリック時に loadVoucherEmployees() が実行されることを確認
→ ブラウザのコンソール（F12 → Console）でエラーを確認
→ バックエンド /payroll/vouchers/employees が返すかテスト

「プレビューをクリック後、何も表示されない」

→ 開始年月が選択されているか確認
→ 従業員が選択されているか確認
→ ネットワークタブ（F12 → Network）で /payroll/vouchers/export へのリクエストを確認
→ バックエンドのログを確認（ターミナル出力）

「CSVが正しく出力されない」

→ ブラウザコンソールで exportVouchersCSV() 実行結果を確認
→ CSV形式とエンコーディング（UTF-8）を確認
→ Excelで開く際、ファイル形式を自動判定に任せず明示的に「UTF-8 CSV」を選択

次の実装予定

Phase 2: PDF生成

reportlab による帳票PDF生成
複数ページ処理
日本語フォント対応

Phase 3: 高度な機能

メール配信
一括ダウンロード
アーカイブ管理

ファイル一覧

バックエンド

backend/app/payroll/vouchers/router.py - API定義
backend/app/payroll/vouchers/schemas.py - データモデル
backend/app/payroll/vouchers/service.py - ビジネスロジック
backend/app/payroll/vouchers/__init__.py - パッケージ初期化

フロントエンド

frontend/payroll-calculation.html - UI実装（新Tab追加）
frontend/voucher-export-test.html - テストページ

ドキュメント

docs/voucher-export-quickstart.md - このファイル

質問・サポート

不明な点がある場合は、以下を確認してください：

ブラウザコンソール（F12）でのエラーメッセージ
バックエンドターミナルのログ出力
ネットワークタブでのAPI通信状況

7.5 KiB Raw Permalink Blame History Unescape Escape