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

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

---

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

| ドキュメント | 内容 | パス | 活用シーン | 更新頻度 |
| --- | --- | --- | --- | --- |
| [要件定義書](./docs/requirements.md) | 機能要件・非機能要件・アーキテクチャ定義 | 新機能開発時の要件確認<br>チームメンバーへの仕様共有<br>承認プロセスでの根拠資料 | 変更時 |
| [プロジェクト計画書](./docs/project_plan.md) | 短期長期計画・マイルストーン・リスク管理 | スプリントプランニング<br>レビューサイクルの計画<br>ステークホルダー報告 | 各フェーズ完了時 |

---

## 🎯 コアコンセプト

販売アシスト 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 テンプレートを使用した CRUD 機能を実装した以下の 5 マスタ管理画面が完成しました:

| 画面名 | ファイル名 | 主要機能 |
|--------|-------------|----------|
| 商品マスタ | `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 |

各画面は共通テンプレートを使用しており、Material Design のボタンプレスデザインを採用しています。

---

## データベース・モデル層

### DatabaseHelper

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

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

### モデル定義

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

---

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

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

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

### 01. マスタ管理
- [x] 商品マスタ ✅
- [x] 得意先マスタ ✅
- [x] 仕入先マスタ ✅
- [x] 倉庫マスタ ✅
- [x] 担当者マスタ ✅

上記を D2（ダッシュボード設定）画面のデフォルトメニューや並べ替え対象として順次実装していきます。

### 02. 販売管理
- [ ] 見積入力
- [ ] 受注入力
- [ ] 売上入力（レジモードの主戦場）
- [ ] 売上返品入力
- [ ] 請求書発行

### 03. 仕入管理
- [ ] 発注入力
- [ ] 仕入入力（未入荷管理を含む）
- [ ] 仕入返品入力
- [ ] 支払予定管理

### 04. 在庫管理
- [ ] 在庫照会
- [ ] 在庫移動（倉庫間）
- [ ] 棚卸入力
- [ ] 在庫調整

### 05. 集計分析
- [ ] 売上日報
- [ ] 得意先別売上推移
- [ ] 商品別粗利分析
- [ ] 在庫評価額一覧

### 06. システム設定
- [ ] ユーザー権限設定
- [ ] ログ管理

上記を D2（ダッシュボード設定）画面のデフォルトメニューや並べ替え対象として順次実装していきます。

---

## 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 自動送付制御含む）

これらの層を意識しつつ Flutter アプリ／母艦サーバ双方で責務分担を進めます。

---

## Event Sourcing / Hash Chain 指針

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

### 役割と必須要件

- **役割**: 「イベントソーシング・アーキテクチャ」を実装し、全操作を監査可能に保つモバイルアプリ専門エンジニア。
- **要件**
  1. UPDATE 禁止・INSERT のみで履歴を積むイベントソーシング方式。
  2. 各イベントは `previous_hash` / `current_hash` を保持し、追記時にチェーンを再計算。(ハッシュチェーン)
  3. 伝票発行時にはマスタ情報を JSON スナップショットとして非正規化して保存。
  4. 生成するコードヘッダーに `// Version: 1.0.0` のようなバージョン表記を必須化。
  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.0
├── README.md                   … 本ファイル
├── analysis_options.yaml       … Lint 設定
├── lib/                        … Flutter アプリ本体
│   ├── screens/                … 各種画面（business_profile_screen 等）
│   ├── widgets/                … 共通ウィジェット（contact_picker_sheet 等）
│   ├── services/               … 永続化・ユーティリティ（company_profile_service 等）
│   └── utils/build_expiry_info.dart … ビルド寿命ユーティリティ
├── scripts/build_with_expiry.sh … dart-define 付きビルドスクリプト
├── android/, ios/, macos/, windows/, linux/ … 各プラットフォームテンプレート
├── assets/                     … 画像・リソース

```

※ フルツリーが必要になった場合は `tree` や `list_dir` の出力を README 末尾に追加して更新していきます。

---

## セットアップ & ビルド

1. Flutter 3.x 環境を用意し、依存パッケージを取得
   ```bash
   flutter pub get
   ```
2. 90 日寿命 APK の生成
   ```bash
   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. 監視サーバを起動
   ```bash
   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 は **機能追加・アーキテクチャ変更・モジュール構成の見直し時に必ず更新** します。
- 変更履歴とファイルツリーは必要に応じて追記し、最新状態を反映させます。