販売アシスト 1 号「母艦お局様」プロジェクト概要

開発コード: CMO-01 (Commercial Management Office - Version 1)
最終更新日: 2026/03/07

---

📋 プロジェクトドキュメント

ドキュメント	内容	パス	活用シーン	更新頻度
要件定義書	機能要件・非機能要件・アーキテクチャ定義	新機能開発時の要件確認 チームメンバーへの仕様共有 承認プロセスでの根拠資料	変更時
工程管理ガイド	工程管理フレームワーク（活用方法明記）	📝 スプリント管理・ステークホルダー報告 リスク管理・承認フロー定義 新規参入者へのオンボーディング資料	各スプリント完了時 ⬅️ 優先的に参照
短期計画（Sprint）	2 週間単位のタスクリスト（CheckList）	📋 次の週の仕事割り当て 実捗確認・チェックオフ管理 スプリントレビュー資料準備	各スプリント開始時
長期計画（Roadmap）	3〜12 ヶ月目標・マイルストーンロードマップ	🎯 ベータ→正式版リリース道筋 チーム成長・人材獲得計画 機能拡張優先順位決定資料	マイルストーン完了時
プロジェクト計画書	統合計画書（承認用）	ステークホルダーレビュー M1-M3 マイルストーン記録 リリース条件確認	各ステークホルダーレビュー時

📚 ドキュメント活用法:

• 新規参入者: README → requirements.md → short_term_plan.md の順に読み進めて「何を」「なぜ」やるか理解
• スプリント開始: short_term_plan.md の未着手タスクリストを確認→アサイン・実装開始
• ステークホルダー報告: project_plan.md + long_term_plan.md で達成状況を説明資料として作成
• リスク管理: 発生事項は engineering_management.md に記録→チーム会議で対応策共有
• バージョンアップ: MAJOR バージョン時 → requirements.md の移行ガイド確認

---

🎯 コアコンセプト

販売アシスト 1 号は オフライン単体で見積・納品・請求・レジ業務まで完結できる販売アシスタント であり、オプション機能として オンライン接続時に母艦「お局様」とデータ同期・バックアップ・監視を行う二層構造 を目指しています。

コンセプト比較表

モード	目的	主な特徴
オフライン・スタンドアロン	端末単体で全業務を完結	SQLite に全データ保存、印影以外は非暗号化、AI などによる再利用も想定
オンライン（システムオプション）	母艦と接続しデータ交換・監視	SSH/クラウドトンネル経由で同期、APK 寿命チェックやバックアップを遠隔制御

母艦「お局様」はブリッジ／モニタリング／バックアップに専念し、実務機能は販売アシスト 1 号側に集約する方針です。TV BOX を母艦に据える運用や、単一端末で両役割を兼務するシナリオも想定しています。

---

📝 ドキュメント管理ポリシー

ドキュメントを更新するタイミングと方針:

更新トリガー	対象ドキュメント	頻度
機能実装完了	README.md, project_plan.md	直後
要件追加/修正	requirements.md	即座に
マイルストーン完了	project_plan.md	フェーズ完了時
リスク発生・対応策決定	project_plan.md (リスク管理節)	発生日
アーキテクチャ変更	README.md, requirements.md	計画立案後

🔄 バージョン管理方針 (semver)

• MAJOR: バックワーズ互換性の破壊（DB スキーマ変更、API ラストメソッド等）
• MINOR: 新機能追加、可逆的変更、ドキュメント改善
• PATCH: バグ修正、パフォーマンス向上、セキュリティパッチ

ルール:

• MAJOR バージョンアップ時は requirements.md で移行ガイドを記載する
• ドキュメントは Git commit と同時に README に反映させる（例：git commit -m "feat: XXX" → README 更新）

✅ 承認フロー

1. ドキュメント作成・修正 (Plan Phase)
2. チームレビュー（必要に応じて）
3. 要件定義書 (requirements.md) の承認（CTO/管理母艦）
4. プロジェクト計画書 (project_plan.md) のマイルストーン登録
5. README.md にドキュメントリンク追加

最終更新: 2026/03/07
バージョン: 1.0 (Initial Release)

---

🛠️ 実装済み機能

✅ マスタ管理画面（Material Design テンプレート）

画面名	ファイル名	主要機能
商品マスタ	lib/screens/master/product_master_screen.dart	コード、名称、単価、在庫数の CRUD
得意先マスタ	lib/screens/master/customer_master_screen.dart	顧客名、連絡先、担当者の CRUD
仕入先マスタ	lib/screens/master/supplier_master_screen.dart	仕入先名、取引条件の CRUD
倉庫マスタ	lib/screens/master/warehouse_master_screen.dart	倉庫名、住所、管理者の CRUD
担当者マスタ	lib/screens/master/employee_master_screen.dart	担当者名、职务、連絡先の CRUD

✅ 業務機能実装

機能	ファイル	状態
見積入力	lib/screens/estimate_screen.dart	✅ コンプリート - 得意先選択・商品追加 - DatabaseHelper を介した保存 - エラーハンドリング完全化
DB CRUD API	lib/services/database_helper.dart	✅ Estimate/Sales テーブル対応 ・insertEstimate ・getEstimates ・insertSales ・getSales
Estimate モデル	lib/models/estimate.dart	✅ LineItem ネスト構造 ・toMap/fromMap 実装

---

🗄️ データベース・モデル層

DatabaseHelper (lib/services/database_helper.dart)

SQLite アクセスコードを集中実装し、すべてのデータ操作はこのヘルパー経由で行う設計です。

主な機能:

• 各マスタ/業務テーブルの CRUD オペレーション (INSERT/UPDATE/DELETE/SELECT)
• トランザクション管理 (DatabaseHelper.transaction)
• JSON 型のスナップショット保存（非正規化設計）
• Soft delete 対応 (isDeleted フィールドによるフィルタリング)

モデル定義

各エンティティのモデルクラスを toMap()/fromMap() 形式で管理しています。これにより JSON 変換処理が一元化され、可読性が向上します。

---

📱 メインメニュー構成（必須機能のベースライン）

実運用で必須になるメニューをツリー形式で整理し、ダッシュボード設定やモジュール化の土台とします。

• ✅: 実装済み（画面・ナビゲーションあり）
• ⚠️: 画面は未実装だがプレースホルダ／メニュー定義済み
• ⏳: 未着手

01. マスタ管理

• 商品マスタ ✅
• 得意先マスタ ✅
• 仕入先マスタ ✅
• 倉庫マスタ ✅
• 担当者マスタ ✅

02. 販売管理

• 見積入力（基本動作完了）✅
• 受注入力
• 売上入力（レジモードの主戦場）⏳
• 売上返品入力
• 請求書発行

03. 仕入管理

• 発注入力
• 仕入入力（未入荷管理を含む）
• 仕入返品入力
• 支払予定管理

04. 在庫管理

• 在庫照会
• 在庫移動（倉庫間）
• 棚卸入力
• 在庫調整

05. 集計分析

• 売上日報
• 得意先別売上推移
• 商品別粗利分析
• 在庫評価額一覧

06. システム設定

• ユーザー権限設定
• ログ管理

---

🔧 Base System - Universal Sales Assistant

クラウド連携やバックエンド処理で共通化したい基盤機能のリファレンスです。Google エコシステム連携や台帳層を切り出しておくことで、オフライン POS と母艦クラウドのハイブリッド連携を容易にします。

• 00. System Setup & Security
  • Google OAuth 認証管理
  • 環境設定管理（.env はデフォルトでブラックリスト化）
  • API 接続制限・クォータ管理
  • ログ出力・エラー通知設定
• 01. Google Ecosystem Integration
  • Calendar Sync Engine（イベント取得 / 解析 / 更新）
  • Drive File Manager（バックアップディレクトリ・テンプレ PDF 管理）
  • Sheets Data Provider（スプレッドシートを DB として接続、ストリーミング書き込み）
• 02. Data Ledger (Transaction Core)
  • 取引データの登録・照会・修正・削除（履歴保持）
• 03. Calculation Engine (Common Rules)
  • 日時フォーマット統一
  • 通貨・数値型キャスト処理
  • 共通利益計算（売上 − 原価）
• 04. Output & Notification
  • PDF 帳票生成エンジン（テンプレ変数差し込み）
  • Mailer（Gmail API、BCC 自動送付制御含む）

---

📡 Event Sourcing / Hash Chain 指針

堅牢で監査可能なエンタープライズレベルの実装に向け、Flutter + SQLite 上でイベントソーシングを採用する際の要求事項を明文化します。

役割と必須要件

• 役割: 「イベントソーシング・アーキテクチャ」を実装し、全操作を監査可能に保つモバイルアプリ専門エンジニア。
• 要件
  1. UPDATE 禁止・INSERT のみで履歴を積むイベントソーシング方式。
  2. 各イベントは previous_hash / current_hash を保持し、追記時にチェーンを再計算。(ハッシュチェーン)
  3. 伝票発行時にはマスタ情報を JSON スナップショットとして非正規化して保存。
  4. 生成するコードヘッダーに // Version: <semver> のようなバージョン表記を必須化。
  5. 設定値は .env から読み込み、ソース直書きを禁止 (セキュリティ確保)。

実装対象コンポーネント

1. EventRecord モデル … ハッシュ計算ヘルパーとバリデーションを内包。
2. DatabaseHelper … SQLite トランザクションとチェーン検証 (追記時に完全性チェック)。
3. SyncService … 伝票単位で差分同期を行う骨子と再送制御ロジック。

出力・コード品質

• 可読性・保守性を重視した Dart 実装。
• 各ファイル先頭へ // Version: <semver> を記載し、バージョン管理ポリシーと整合させる。

内部改修のインパクト

• 既存の app_settings や業務テーブルはイベントテーブルへ段階的に移行する必要があり、DB スキーマの大幅刷新とデータ移行手順（マイグレーション／復元）が不可欠。
• ハッシュチェーンを維持するため、全 INSERT をトランザクションでラップし、previous_hash 取得・current_hash 算出をセットで行うミドル層 (Repository or DatabaseHelper) を新設する必要がある。
• スナップショット JSON を整形するため、マスタ取得ロジックや PurchaseEntry / Invoice 生成処理の改修が発生する。
• .env 管理を徹底するため、既存の AppConfig や DatabaseHelper の初期化フローに環境変数リーダーを導入し、公開ビルドとの整合を取る必要がある。
• SyncService はイベント単位の差分アップロード・整合性チェック (ハッシュ比較) を実装し直す必要があり、オンライン同期のプロトコル設計も含め再検討が必要。

上記の通り 内部的には大幅なアーキテクチャ改造が前提 となるため、段階的に (1) イベントテーブルの追加 → (2) 既存書き込みのラップ → (3) スナップショット導入 → (4) Sync/Hash 連携 というロードマップで移行する予定です。

---

📂 リポジトリ構成

/home/user/dev/h-1.flutter.4
├── README.md                   … 本ファイル
├── analysis_options.yaml       … Lint 設定
├── lib/                        … Flutter アプリ本体
│   ├── screens/                … 各種画面（estimate_screen.dart など）
│   │   ├── master/             … マスタ管理画面
│   │   ├── estimate_screen.dart … 見積入力画面
│   │   ├── sales_screen.dart   … 売上入力画面
│   │   └── ...
│   ├── widgets/                … 共通ウィジェット
│   ├── models/                 … データモデル（customer, product, estimate など）
│   ├── services/               … DB アクセス・ユーティリティ
│   └── utils/                  … ビルド寿命ユーティリティ
├── docs/                       … 工程管理ドキュメント
│   ├── engineering_management.md … 工程管理ガイド
│   ├── short_term_plan.md     … 短期計画（スプリント）
│   ├── long_term_plan.md      … 長期計画（ロードマップ）
│   ├── requirements.md        … 要件定義書
│   └── project_plan.md        … プロジェクト計画書
├── scripts/                    … ビルドスクリプト
├── assets/                     … 画像・リソース
├── android/                    … Android プラットフォーム設定
├── ios/                        … iOS プラットフォーム設定
└── web/                        … Web プラットフォーム設定

---

🛠️ セットアップ & ビルド

1. Flutter 3.x 環境を用意し、依存パッケージを取得

   flutter pub get
   

2. 90 日寿命 APK の生成

   chmod +x scripts/build_with_expiry.sh
   ./scripts/build_with_expiry.sh [debug|profile|release]
   

   • スクリプト内で APP_BUILD_TIMESTAMP を UTC で自動付与
   • flutter analyze → flutter build apk を連続実行

3. 実機/エミュレータで起動すると、寿命切れ時には ExpiredApp が自動表示されます。

---

🧪 テストデータの初期化

新規インストール時に以下マスタが自動挿入されます（既に存在する場合スキップ）:

マスタ	対象テーブル	登録件数	特徴
得意先	customers	3 件	C00001~C00003 / 「テスト株式会社*」表記
担当者	employees	3 件	「山田 太郎」「鈴木 花子」「田中 次郎」
倉庫	warehouses	2 件	「中央倉庫」「東京支庫」
仕入先	suppliers	3 件	「仕入元 Alpha~Gamma」
商品	products	3 件	PRD001~PRD003 / 「テスト商品*A・B・C」

※ データ名に _test または「テスト」と付くものや、Alpha/Beta/Gamma など一目でテストデータとわかるデザイン採用。

テストデータの削除

必要に応じてマスタを空に戻すには customers 以外のマスタテーブルから手動で DELETE 操作を行ってください（アプリ起動時の自動挿入制御の対象外）。

---

🖥️ 母艦「お局様」LAN サーバの起動

1. Dart/Flutter SDK が入った Linux / Android（Termux 等）端末でリポジトリを取得
2. 監視サーバを起動

   dart run bin/mothership_server.dart
   

   • 環境変数 MOTHERSHIP_HOST, MOTHERSHIP_PORT, MOTHERSHIP_API_KEY, MOTHERSHIP_DATA_DIR で上書き可能
   • 既定値：0.0.0.0:8787, API キー TEST_MOTHERSHIP_KEY, 保存先 data/mothership
   • data/mothership/status.json に各クライアントの心拍/ハッシュを保存
3. ブラウザで http://<host>:<port>/ を開くとステータス一覧を閲覧できます（CUI 常駐で OK）

クライアント（販売アシスト 1 号）からの接続設定

1. アプリの S1:設定 → 「外部同期（母艦システム『お局様』連携）」で以下を入力
   • ホストドメイン：http://192.168.0.10:8787 のようにプロトコル付きで指定
   • パスワード：サーバ側 API キー（例：TEST_MOTHERSHIP_KEY）
2. 保存するとアプリ起動時に POST /sync/heartbeat が自動送信され、寿命残時間が母艦に表示されます。
3. 同じ設定でチャット送受信・ハッシュ送信が有効になります（下記参照）。

チャット同期（最小構成）

• Flutter アプリ側では 10 秒間隔の軽量ポーリングをバックグラウンドで実行し、/chat/send / /chat/pending / /chat/ack とローカル SQLite を同期します。
• 設定画面からチャット画面を開かなくても新着が取り込まれ、開いた瞬間に最新ログが表示されます。
• 端末がスリープに入るとポーリングを停止し、アプリが前面に戻ったタイミングで即時同期→再開します。

---

📝 更新ポリシー

• README は 機能追加・アーキテクチャ変更・モジュール構成の見直し時に必ず更新 します。
• 変更履歴とファイルツリーは必要に応じて追記し、最新状態を反映させます。

---

最終更新: 2026/03/07
バージョン: 1.0 (Initial Release)