顧客詳細・メモ・タグ

Document ID: SRS-CUS-002 Parent: SRS-ROOT-001 v0.5 Version: 0.2 Status: Implemented (API + Web UI 最小) Last Updated: 2026-05-06 Depends on: SRS-CUS-001 v0.2, SRS-TEN-002 v0.2, SRS-TEN-003 v0.2, SRS-MST-001 v0.6 依存される: SRS-RES-002 v0.5

本書は SRS-ROOT-001 v0.5 に従う。

1. 目的

顧客詳細画面で基本情報の閲覧・更新、メモ追加、タグ付与、論理削除を扱う。

Phase 1 のメモ type は memo のみ、タグは 8 色プリセット、bulk apply は不採用。

2. ユーザーストーリー

As a 店長, I want to 顧客の基本情報を詳細画面で更新したい, so that 連絡先や指名情報を保てる
As a スタッフ, I want to 顧客メモを残したい, so that 次回来店時の接客に活かせる
As a 受付, I want to 顧客にタグを付けたい, so that 検索や注意喚起に使える
As a 店長, I want to 顧客を論理削除したい, so that 退会対応と法的保持を両立できる

3. ユースケース

3.1 主シナリオ

顧客一覧から顧客詳細を開く
基本情報を編集して保存する
メモ欄に memo を追記する
タグを新規作成または既存から付与する
必要に応じて顧客を論理削除する

3.2 代替フロー

AF-1 メモ編集者は作成者でなくてもよい
AF-2 archived タグは新規付与候補に出さないが、既存顧客への表示は残す
AF-3 削除した note は 7 日以内なら restore 可能（UI は Phase 2 で公開）
AF-4 顧客の物理削除は cleanup-deleted-customers-for-store ジョブが 90 日後に実行（SRS-WRK-001）

3.3 例外フロー

EF-1 archived tag と同名 tag の新規作成: 409 CUSTOMER_TAG.NAME_CONFLICT
EF-2 note 空文字: 422 CUSTOMER_NOTE.INPUT_INVALID
EF-3 既に削除済み顧客への note 追加: 422 CUSTOMER.DELETED
EF-4 タグ未存在: 404
EF-5 他店舗 tag を付与: 404

4. UI仕様

4.1 主要要素

基本情報カード
タグ一覧と付与フォーム
メモ時系列
予約一覧サマリ
論理削除ボタン

4.2 バリデーション

note body: 1..5000
tag name: 1..50
tag color: 8 色 enum
detail update は CUS-001 と同一入力ルール

5. API仕様

5.1 エンドポイント一覧

Method	Path	用途	permission
GET	`/api/admin/customers/{id}`	詳細取得	`admin:customer:read`
PATCH	`/api/admin/customers/{id}`	基本情報更新	`admin:customer:update`
DELETE	`/api/admin/customers/{id}`	論理削除	`admin:customer:update`
GET	`/api/admin/customers/{id}/notes`	note 一覧	`admin:customer:read`
POST	`/api/admin/customers/{id}/notes`	note 作成	`admin:customer:update`
PATCH	`/api/admin/customers/{id}/notes/{noteId}`	note 更新	`admin:customer:update`
DELETE	`/api/admin/customers/{id}/notes/{noteId}`	note 論理削除	`admin:customer:update`
POST	`/api/admin/customers/{id}/notes/{noteId}/restore`	note 復元	`admin:customer:update`
GET	`/api/admin/customer-tags`	tag 一覧	`admin:customer:read`
POST	`/api/admin/customer-tags`	tag 作成	`admin:customer:update`
PATCH	`/api/admin/customer-tags/{tagId}`	tag 更新	`admin:customer:update`
POST	`/api/admin/customers/{id}/tags/{tagId}`	tag 付与	`admin:customer:update`
DELETE	`/api/admin/customers/{id}/tags/{tagId}`	tag 解除	`admin:customer:update`

Phase 1 では admin:customer:update 1 個に集約（細分化は Phase 2 OQ）。

5.2 zodスキーマ

customer_note:

id
type: 'memo'
body
author_operator_id NULL 許容
created_at, updated_at, deleted_at

customer_tag:

id, name, color, is_archived

5.3 エラーコード

CUSTOMER.DELETED
CUSTOMER_NOTE.INPUT_INVALID
CUSTOMER_NOTE.RESTORE_WINDOW_EXPIRED
CUSTOMER_TAG.NAME_CONFLICT
CUSTOMER_TAG.ARCHIVED

6. データモデル影響

6.1 スキーマ

`customer_note`

カラム	型	制約
`id`	`uuid`	PK
`store_id`	`uuid`	NOT NULL, FK
`customer_id`	`uuid`	NOT NULL, 複合 FK
`type`	`varchar(20)`	NOT NULL DEFAULT ‘memo’, CHECK `= 'memo'`
`body`	`text`	NOT NULL, CHECK `btrim(body) <> ''`
`author_operator_id`	`uuid`	NULL, FK → `operator(id)`（TEN-002 後に有効）
`created_at`	`timestamptz`	NOT NULL
`updated_at`	`timestamptz`	NOT NULL
`deleted_at`	`timestamptz`	NULL
制約		`UNIQUE(store_id, id)`

`customer_tag`

カラム	型	制約
`id`	`uuid`	PK
`store_id`	`uuid`	NOT NULL, FK
`name`	`varchar(50)`	NOT NULL, CHECK `btrim(name) <> ''`
`color`	`varchar(20)`	NOT NULL, CHECK `IN (8 colors)`
`is_archived`	`boolean`	NOT NULL DEFAULT false
`created_at`, `updated_at`	`timestamptz`	NOT NULL
制約		`UNIQUE(store_id, id)`
制約		`UNIQUE(store_id, name)`

`customer_tag_link`

カラム	型	制約
`store_id`	`uuid`	NOT NULL
`customer_id`	`uuid`	NOT NULL
`tag_id`	`uuid`	NOT NULL
`created_at`	`timestamptz`	NOT NULL
PK		`(store_id, customer_id, tag_id)`

6.2 マイグレーション計画

0018_customer_crm.sql で CUS-001 と同時導入。

permission は admin:customer:read (CUS-001) + admin:customer:update（CUS-002）の 2 つ。

7. 業務ルール

7.1 メモ type

Phase 1 は memo のみ
karte / sketch は Phase 2 で type 値域拡張

7.2 メモ編集権限

同店舗の全 operator が編集可
ABAC（作成者のみ編集）は OQ

7.3 メモ削除と復元

deleted_at 採用
復元は 7 日以内のみ
7 日経過後は purge_deleted_customer_notes ジョブで物理削除（SRS-WRK-001）

7.4 タグ

name は store 内 unique（archived 含む）
archived タグは新規 link 不可だが既存 link は表示
8 色プリセット

7.5 顧客削除

deleted_at のみ
紐付く customer_note, customer_tag_link は保持
90 日後に cleanup-deleted-customers-for-store が cascade 物理削除

7.6 監査

customer.update / delete
customer_note.create / update / delete / restore
customer_tag.create / update / link / unlink

8. 非機能要件

detail 取得 p95 300ms
note 一覧は 200 件まで即時表示

9. セキュリティ・認可

admin:customer:read
admin:customer:update

PII マスキングは Phase 2 OQ。

10. 受け入れ基準

GWT-1: 顧客基本情報更新 → updated_at が更新される
GWT-2: staff A 作成の note を staff B が更新 → 成功（同店舗 operator 全員可）
GWT-3: archived tag と同名の新規作成 → CUSTOMER_TAG.NAME_CONFLICT
GWT-4: note を 3 日後に restore → 復元される
GWT-5: note を 8 日超で restore → CUSTOMER_NOTE.RESTORE_WINDOW_EXPIRED
GWT-6: 顧客 delete → deleted_at セット、tag/note は保持

11. テスト計画

Unit: tag color check, restore window
Integration: note CRUD, tag apply/remove, customer logical delete

12. 関連ジョブ

purge_deleted_customer_notes
cleanup-deleted-customers-for-store

13. Open Questions

#	内容	扱い
OQ-CUS-002-01	作成者限定 ABAC	Phase 2
OQ-CUS-002-02	カルテ構造化	Phase 2 SRS-CUS-005
OQ-CUS-002-03	スケッチ画像	Phase 2

14. 変更履歴

Version	Date	Author	Change
0.1	2026-05-05	Codex / yudai	初版
0.2	2026-05-05	yudai (with Codex co-design)	Round 2 反映: migration 番号 0018 確定、permission を `admin:customer:update` 1 個に集約