TTECHNICALAI CRM Demo

小規模店舗向け顧客・販促管理システム（CRM）

AI CRM Demo

顧客・来店・売上を 1 か所にまとめ、次に声をかけるべき顧客を見つけ、販促の文案を用意し、人が承認するまでを回す。

Sections

01このページについて
02Architecture
03Why this architecture
04Failure modes
05Trade-offs
06Tests
07Security / Data handling
08Limitations
09Scale
10Links

01このページについて

このページについて

対象AI CRM Demo（ai-crm-demo/）

公開 claim の正本ai-crm-demo/README.md

実装形態個人開発です。画面・API・データベース・AI 呼び出し・権限・テストまでを 1 人で実装しました。私的に開発中のプロダクトから公開可能な範囲を切り出したもので、外部配信・代理店管理・本番インフラは含めていません。

含めていないもの

LINE Messaging API 連携（webhook / 一斉・個別・ステップ配信 / リッチメニュー）
代理店マルチテナント管理（/agencies UI・代理店単位の店舗ダッシュボード）
Celery + Redis による配信の定期実行・バックグラウンド処理
本番インフラ（HTTPS 終端・HSTS・secure cookie・CDN・VPS 運用手順）
実顧客 CSV 取込のポリシー（生データのマスキング・保持期限の削除）

02Architecture

Architecture

画面（React 18 / TypeScript / Vite）→ API（Django 5.0 / DRF・/api/v1/）→ AI provider（mock = DEFAULT / anthropic = OPTIONAL）/ DB の 4 層。Django アプリは計 11 個、業務の流れ 7 段（人による承認を含む）。

03Why this architecture

Why this architecture

ドメインが顧客・予約・売上・施策・監査の 5 系統に分かれ、いずれも管理系の CRUD と権限判定が中心である。ORM とマイグレーション、認証・権限の既製レイヤ、drf-spectacular による OpenAPI 自動生成が標準で揃うため、業務ロジックとテストに時間を割ける。監査ログとマスキングを Serializer / 認証クラスという単一の通り道へ集約できることも決め手。同一画面を権限で出し分ける要件があるため、画面側は型で応答形状を固定し、サーバ状態の取得を TanStack Query に寄せて分岐をコンポーネントへ閉じ込めた。

Django テンプレートによる一体構成
画面数は少ないため作れはするが、権限別の出し分けがテンプレート内の条件分岐へ散り、API 契約として外部へ渡せる形（引き継ぎ・別クライアント）が残らない。「引き継げること」を要件に含めたため却下。
SSR フレームワーク（Next.js 等）でのフルスタック構成
認証・権限・監査をアプリ側で自作する比重が上がり、Django の既製レイヤで済む部分を書き直すことになる。SEO 要件もない。
既製 SaaS CRM のカスタマイズ
AI 文案の承認フローと権限別マスキングが中核要件であり、外部サービスの拡張点に載せるとロジックが分散する。

04Failure modes

Failure modes

ログイン状態の失効は秒単位ではない（次アクセス時に token_version 判定）。
マスクは API 応答時の加工であり、DB は平文。
画面側のトークン自動更新は未実装（apiClient.ts に TODO）。
監査は対象操作限定で、reservation / sale の書き込みは対象外。
表現チェックは辞書ベースで、辞書に無い表現は検出しない（法的判断ではない）。

05Trade-offs

Trade-offs

マスキングを表示層に置いたため、DB 直参照や dump では平文が見える。
監査を「対象操作の列挙」にしたため、網羅性より可読性を取っている。
AI 利用ログは 5 サービス中 3 つのみトークン数を保持しており、コスト上限制御はこのデータのままでは組めない。
frontend / backend の 2 デプロイ単位、型定義の二重管理（OpenAPI からの生成は未導入）、frontend テスト 0 件。

06Tests

Tests

静的 def test_ 480 件、CI 実測 484 passed（run 32078586978、Python 3.12 / config.settings.test / SQLite in-memory / AI_PROVIDER=mock）。frontend テストは 0 件。

backend 静的 480 件 / CI 実測 484 passedAI CRM CI の main 実行ログ（run 32078586978）

領域	内容
認証	apps/accounts/tests/test_auth.py（30）
マスキング	apps/customers/tests/test_masking.py（19）
承認	apps/campaigns/tests/test_approval.py（16）
CSV 出力	29
AI 呼び出し	apps/ai_core/tests（37）
監査	apps/audit/tests/test_audit.py（7）
共同作業者	test_collaborators.py（21）
取込エラー保持	test_import_error_retention.py（8）

07Security / Data handling

Security / Data handling

apps/customers/utils.py:1-40 と serializers.py:182-202 が to_representation 時にマスク。
apps/accounts/authentication.py:26-40 で per-request token_version 判定。
ログイン試行は SimpleRateThrottle。
監査は apps/audit/services.py の write_audit_log（before-after スナップショット）。
取込エラー行は PII をマスクして保持し、purge_import_errors で削除する（自動実行なし）。

08Limitations

Limitations

できること・含めていないことの各行に対応。README「Differences from the Original Product Scope」および「AI Architecture」の 5 サービス表を正本とする。

この公開デモに含めていない

frontend テストは 0 件（CI が frontend で回すのは lint / type-check / build のみ）。
マスキングは API 応答時の表示制御で、データベースは平文で保持している。
監査ログは対象操作限定。予約・売上の書き込みは対象外（23 か所 / 7 アプリ）。

09Scale

Scale

項目	実測値	取得方法
API エンドポイント	55	apps/*/urls.py の path() 総数 63 から、下位 urls.py を束ねる include() 8 件を除いた実数。DRF Router は不使用
モデル / アプリ	26 / 11	Django のモデルレジストリ（apps.get_models() のうち apps.* 所属）
設計文書	24 本	docs/ の Markdown（連番の設計文書 23 本 + API_CONTRACT.md）
backend テスト	静的 480 件 / CI 実測 484 passed	backend/apps のテスト定義を数えた静的件数 480 件（2026-08-20 再計測）。CI 実行ログ run 32078586978 の実測は 484 passed
frontend テスト	0 件	frontend/ 配下に .test. / .spec. が 0 件（node_modules 除く）

10Links