docs: README.md をプロジェクトドキュメントと活用法を明記した最新版に更新\n- プロジェクトドキュメントテーブルの拡張（工程管理ガイド、短/長期計画追加）\n- ドキュメント活用法セクションの新規追加\n- 実装済み機能一覧の見直し（見積入力、マスタ管理画面）\n- メインメニュー構成のステータス表示更新\n- リポジトリ構成ツリーの整理

2026-03-07 17:15:44 +09:00 · 2026-03-07 17:15:44 +09:00 · fe177f9af8
commit fe177f9af8
parent b29026b469
1 changed files with 258 additions and 4 deletions
--- a/README.md
+++ b/README.md
@ -74,11 +74,265 @@

 ---

-## 実装完了マスタ管理画面
+## 🛠️ 実装済み機能

-Material Design テンプレートを使用した CRUD 機能を実装した以下の 5 マスタ管理画面が完成しました:
+### ✅ マスタ管理画面（Material Design テンプレート）

 | 画面名 | ファイル名 | 主要機能 |
 |--------|-------------|----------|
-| 商品マスタ | `lib/screens/master/product_master_screen.dart` | 商品コード、名称、単価、在庫数の CRUD |
-| 得意先マスタ | `lib/screens
+| 商品マスタ | `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` | ✅ 基本動作完了<br>- 得意先選択・商品追加<br>- DatabaseHelper を介した保存<br>- エラーハンドリング実装中 |
+| DB CRUD API | `lib/services/database_helper.dart` | ✅ Estimate テーブル対応<br>・insertEstimate<br>・getEstimates<br>・estimate CRUD |
+| Estimate モデル | `lib/models/estimate.dart` | ✅ LineItem ネスト構造<br>・toMap/fromMap 実装 |
+
+### ⏳ 次期実装予定（Sprint 4）
+
+- [ ] 見積保存時の完全なエラーハンドリング
+- [ ] PDF 帳票出力テンプレート準備
+- [ ] 売上入力画面実装
+- [ ] 請求書機能設計
+
+---
+
+## 🗄️ データベース・モデル層
+
+### DatabaseHelper (`lib/services/database_helper.dart`)
+
+SQLite アクセスコードを集中実装し、すべてのデータ操作はこのヘルパー経由で行う設計です。
+
+**主な機能**:
+- 各マスタ/業務テーブルの CRUD オペレーション (INSERT/UPDATE/DELETE/SELECT)
+- トランザクション管理 (`DatabaseHelper.transaction`)
+- JSON 型のスナップショット保存（非正規化設計）
+- Soft delete 対応 (isDeleted フィールドによるフィルタリング)
+
+### モデル定義
+
+各エンティティのモデルクラスを `toMap()/fromMap()` 形式で管理しています。これにより JSON 変換処理が一元化され、可読性が向上します。
+
+---
+
+## 📱 メインメニュー構成（必須機能のベースライン）
+
+実運用で必須になるメニューをツリー形式で整理し、ダッシュボード設定やモジュール化の土台とします。
+
+- ✅: 実装済み（画面・ナビゲーションあり）
+- ⚠️: 画面は未実装だがプレースホルダ／メニュー定義済み
+- ⏳: 未着手
+
+### 01. マスタ管理
+- [x] 商品マスタ ✅
+- [x] 得意先マスタ ✅
+- [x] 仕入先マスタ ✅
+- [x] 倉庫マスタ ✅
+- [x] 担当者マスタ ✅
+
+### 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 環境を用意し、依存パッケージを取得
+   ```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 は **機能追加・アーキテクチャ変更・モジュール構成の見直し時に必ず更新** します。
+- 変更履歴とファイルツリーは必要に応じて追記し、最新状態を反映させます。
+
+---
+
+**最終更新**: 2026/03/07  
+**バージョン**: 1.0 (Initial Release)