Nexync連携アプリ第２弾 MileageFlow v2.2.0
MileageFlow – 自家用車業務利用精算ツール
目次
- アプリケーション概要
- 親システム（Nexync）との完全疎結合連携
- 基本方針と特徴
- システムアーキテクチャ
- セキュリティ仕様
- ディレクトリ構成
- 動作環境
- ダウンロード
- インストール手順（ゼロコンフィグ）
- 各機能と使い方
- 免責事項・問い合わせ
1. アプリケーション概要
1.1 名称の由来
自家用車を業務利用した距離（Mileage)を記録して精算するまでの流れ（Flow)を管理するための役割を表しています。
1.2 概要
MileageFlow（マイレージフロー）は、自家用車（マイカー）を業務利用した際の「走行距離」と「精算額」を正確かつ手軽に記録・管理するためのWebアプリケーションです。
統合ID・アプリポータル基盤「Nexync（ネクシンク）」の傘下で動作するマイクロフロントエンド（子システム）として設計されており、スマートフォンからの直感的なGPS連動記録から、管理者による月次締め処理・印刷、バックアップ・監査ログの管理までをワンストップで提供します。
2. 親システム（Nexync）との完全疎結合連携
MileageFlowは、親システム「Nexync」の内部構造や物理パスを一切知ることなく動作する完全疎結合設計を採用しています。
- Nexync Client SDK (nx-ui.js) 連携:
フロントエンドは window.Nexync の抽象インターフェースのみを通じて認証確認（SSO）、共通ログインカードの描画、グローバルモダールやトースト表示を行ないます。 - Nexync Server SDK (nx-core.php) 連携:
バックエンドは NexyncCore クラスを通じて、共通SSO認証チェック、CSRFトークン検証、IP解決（Trust Proxy対応）、レートリミット制御、ハッシュチェーン付き監査ログの記録を完全委譲しています。
3. 基本方針と特徴
- 完全なインフラ非依存・ゼロコンフィグ導入
複雑な環境設定やデータベース作成スクリプトの実行は一切不要です。Webサーバー（PHP環境）にファイルを配置するだけで、自動的に隔離データベースが構築され即座に稼働を開始します。 - ゼロトラスト・セキュリティ（SSOTの確立）
クライアント端末から送信された金額や時刻、計算結果を一切信用しません。精算額の計算は常にサーバー側に記録されたタイムスタンプと単価マスターに照らし合わせて再計算される「信頼できる単一の情報源 (SSOT)」モデルを徹底しています。 - PWA & モバイル最適化
スマホからの利用に最適化されており、ホーム画面への追加（PWA）に対応。設定されたテーマカラーに合わせてアプリ用のスピードメーターアイコンが自動動的生成されます。
4. システムアーキテクチャ
4.1. フロントエンド（Client）
- 技術スタック: Vanilla JavaScript (ES Modules / ESM), Tailwind CSS
- 設計思想 (Pure MVC):
- Model (core.js): 状態管理（AppStateModel）、通信（DataService）、境界値検証（Validator）。
- View (ui.js): 純粋なDOM構築（DocumentFragment を活用し innerHTML に頼らないXSS無害化レンダリング）と画面制御（UIManager）。
- Controller (controllers.js): DOMやブラウザ固有APIから完全に分離されたピュアなビジネスロジック・オーケストレーター。
4.2. バックエンド（Server）
- 技術スタック: PHP 8.x, SQLite3
- 設計思想:
- データベース隔離: Web公開領域外（nexync_data/mileageflow.sqlite3）へデータを安全に隔離格納。
- 短時間ロック & バルク処理: SQLite特有の「Database is locked」を防ぐため、BEGIN EXCLUSIVE TRANSACTION によるミリ秒単位のロック制御と、500件単位の非同期チャンク再計算処理を実装。
5. セキュリティ仕様
- BOLA / IDOR（オブジェクトレベル認可欠如）対策:
全データの更新（PUT）および削除（DELETE）APIにおいて、リクエストされたレコードの所有者（employee_id）と現在のセッション所有者をDB上で照合。管理者ロールでない限り、他者のデータ操作を物理遮断します。 - DOM Based XSS の根絶: ユーザー入力値の展開において innerHTML や危険な文字列結合を排除し、document.createElement と textContent のみを用いたテキストレンダリングを採用。
- OOM / DoS 防御: 監査ログ送信時やファイルアップロード時において、巨大なペイロードによるメモリ枯渇攻撃を防ぐ厳格な文字列切り詰め（Truncation）とストリーミングサイズチェックを強制。
- CSRF防衛 & レートリミット: X-Nexync-CSRF-Token ヘッダーと Sec-Fetch-Site / Origin の多層チェック、および同一IPからの連続リクエストに対するアプリケーション層レートリミットを常時発動。
6. ディレクトリ構成
/var/www/ (Web公開領域外：外部アクセス絶対不可能エリア)
├── nexync_data/ # 🛡️ 物理データおよび暗号鍵の一括隔離ディレクトリ
│ ├── mileageflow.sqlite3 # MileageFlow データベースファイル本体
│ └── sso_keys/ # 🔐 暗号鍵保管庫 (親システム共有)
│
└── public_html/ (Web公開ドキュメントルート)
└── nexync/ # 親システム：Nexync本体
├── index.html
└──mileage/
├── index.html # アプリメインエントリー（Single Page Application）
├── manifest.json # PWA用マニフェストファイル
├── icon-512×512.png # PWA用高解像度アイコン
├── sw.js # Service Worker (APIリクエスト完全素通し仕様)
├── api/
│ ├── db.php # データベース接続・自動マイグレーション処理
│ ├── logs.php # 走行記録（出発・到着・履歴）管理API
│ ├── vehicles.php # 登録車両マスタ管理API
│ ├── settings.php # km単価履歴・再計算・DBバックアップAPI
│ ├── sync_icon.php # PWAアイコン同期ゲートウェイ
│ ├── locks.php # 月次ロック（締め処理）管理API
│ └── audit.php # 監査ログ閲覧・エラー収集API
├── assets/
│ └── js/
│ ├── main.js # ESMエントリーポイント
│ ├── core.js # Model / DataService / AppState / Validator
│ ├── ui.js # View / UIBuilder / UIManager
│ └── controllers.js # Controller（各種ビジネスロジック）
└── docs/
├── README.md # 説明書
└── CHANGELOG.md # バージョン変更履歴
7. 動作環境
- Webサーバー: Apache または Nginx（PHP 8.0 以上が動作すること）
- 必須PHP拡張機能: pdo_sqlite, sqlite3, openssl, mbstring, json, finfo
- クライアント環境: Google Chrome, Safari, Microsoft Edge, Firefox 等のモダンブラウザ（ES6/ES Modules対応）
- 前提システム: 親ポータル「Nexync」環境下への配置
8. ダウンロード
上記画像リンクからzipファイルをダウンロードしてください。
9. インストール手順（ゼロコンフィグ）
- ファイルの配置
親システム（Nexync）が設置されているサーバーの同一ドメインのnexyncディレクトリ直下のmileageディレクトリに全ファイルをアップロードします。
例: https://example.com/nexync/mileage/ - パーミッションの確認
Web公開領域外のデータ保存用ディレクトリ（../nexync_data/）に対し、Webサーバープロセス（www-data や apache 等）の書き込み権限が付与されていることを確認します。 - アクセスと自動初期化
ブラウザから index.html にアクセスします。初回アクセス時に api/db.php が起動し、自動的に mileageflow.sqlite3 データベースおよび必要な全テーブル構造が生成されます。
10. 各機能と使い方
10.1. ダッシュボード（走行記録・GPS連携）
- 出発記録:
利用する車両を選択し、出発時のオドメーター（km）および出発地を入力して「出発する」を押します。この際、スマートフォンの位置情報（GPS）が自動記録されます。 - 到着記録 & 精算額リアルタイム算出:
到着時に到着メーター、到着地、用件を入力します。当時のkm単価マスターに基づき、走行距離および精算予定額がリアルタイムにプレビュー表示されます。
10.2. 利用履歴
- 自社・自身の走行記録を一覧で閲覧・編集・削除できます。
- 過去のオドメーター修正や削除が行われた場合、連鎖的な不整合を防ぐため、バックグラウンドで関連データの連鎖再計算が実行されます。
10.3. 登録車両の管理（私有車マスタ）
- 各社員が所有する自家用車を登録・管理します。
- メインで利用する車両には「★メイン」を設定することで、ダッシュボード初期選択車両として固定できます。
10.4. 利用月報（集計・月次締め・印刷）
- 指定した月の走行日数・合計走行距離・合計精算額を自動集計します。
- 月次ロック機能（管理者専用）: 経費精算完了後、対象月を「ロック」することで、過去データの改ざん・編集・遡り再計算を完全にブロックします。
- PDF / 印刷最適化: 「印刷」ボタンを押すことで、承認印欄（部長・次長・課長・係長）が付いた公式な精算書レイアウトで印刷・PDF保存が可能です。
10.5. システム管理（システム管理者専用）
- km単価のタイムトラベル管理: ガソリン価格の高騰等に応じたkm単価（例: 25円/km）を「適用開始日」付きで追加・管理できます。単価変更時、未ロックの過去履歴に対して正しい単価を遡って一括再計算するチャンクバッチが動きます。
- バックアップ & 復元: データベース（.sqlite3）の即時エクスポートおよびアトミックな上書き復元が可能です。
- 改ざん検知機能付き監査ログ: システム内の重要操作や認証イベントは、前後のハッシュ値が鎖状につながる「改ざん検知ハッシュチェーン」として監査ログに安全に記録されます。
11. 免責事項・お問い合わせ
本ソフトウェアはフリーウェアとして提供されています。ご利用にあたっては組織内のセキュリティ方針に沿って動作確認を行った上でご活用ください。
不具合等のバグ報告や意見などは、メール（info@aizack.net）もしくはウェブサイトのコメントからお願いいたします。
最近のお気に入りの曲
SABER TIGER – Angel Of Wrath (OFFICIAL MUSIC VIDEO)
これはライブで聞くと、最高にノリノリの曲。
