開発規約（Conventions）

モノレポ構成

npm workspaces ＋ Turborepo によるモノレポ。apps/*（アプリ）と packages/*（共有パッケージ）で構成する。

• アプリ横断で使うコードは packages/ に置き、@aihomestaging/* として import する。
• DB アクセスは必ず @aihomestaging/database 経由。アプリから Prisma を直接初期化しない。

技術スタック

• Next.js（App Router） ＋ React Server Components。各アプリは app/ 配下。
• Tailwind CSS v4。
• Prisma 7（PostgreSQL）。
• Zod（バリデーション・Json カラムの parse）。
• NextAuth（認証）。
• PWA（Progressive Web App）：Webアプリをスマホのホーム画面に追加し、ネイティブアプリのように起動できる仕組み。ユーザー画面（apps/user）はインストール可能なPWAで、設定画面（/v/settings）にインストールボタンを持つ。
• 画像配信は AWS CloudFront（CDN）、画像保存は S3。
• TypeScript。

ディレクトリ・命名

サーバーアクション

• 各アプリの actions/{domain}/ に配置。
• ファイル名は操作ごとに分割：create-X.ts / get-X.ts / list-X.ts / update-X.ts / delete-X.ts。画像生成は generate-image/。

ルートのコロケーション（App Router）

• _components/ ＝ そのルート専用のコンポーネント（先頭 _ はルートにならない）。
• _actions/ ＝ そのルート専用のアクション、_fields/ ＝ フォーム部品。
• コンポーネントは責務ごとに細かく分割し、ネストした _components/ に置く。

フォーム（react-hook-form）

• フォームの各フィールドは _fields/ に1ファイル1コンポーネントで分割する（フォーム本体の index.tsx に FormField をベタ書きしない）。
• ファイル名は {field-name}-field.tsx、エクスポートは {FieldName}Field。
• 各フィールドは useFormContext<FieldInputs, unknown, FieldOutputs>() でフォームへ接続する（props でのバケツリレーをしない）。
• Zod スキーマと型は schema.ts に切り出し、schema / FieldInputs（z.input）/ FieldOutputs（z.output）をエクスポートする。
• index.tsx は useForm（defaultValues・submit）とフィールドの組み立てに専念する。
• _fields/ と schema.ts はフォーム単位で持つ（作成フォームと編集フォームで各自に配置する）。例：contract-plans/new/.../contract-plan-add-form/、system-notifications/new/.../system-notification-add-form/。

ルートグループ（ユーザー画面）

• (horizontal)/h ＝ PC版、(vertical)/v ＝ モバイル版（用語: PC版/モバイル版）。
• (tracking)/t、(landing-page)/lp など、レイアウト単位でルートグループを分ける。

コンポーネント

• コンポーネントはアクションが export する型に依存しない。 コンポーネント内で必要な型はコンポーネント側で定義する。 アクションの戻り値型と構造が同じであっても、アクションファイルから import しない。 TypeScript の構造的型付けにより型互換性は保証される。

// NG: アクションの型に依存
import { BillingRecordMonthlyTotal } from "@/actions/billing-record/list-billing-record-monthly-totals";

// OK: コンポーネント側で型を定義
type BillingRecordMonthlyTotals = {
  month: number;
  totalAmount: number;
}[];

サーバーアクション

• 先頭に "use server"。
• action(actionName, handler) ヘルパーでラップするのを標準とする。認証チェックと try/catch を集約し、handler には認証済み user（organization 付き）が渡る。※ 一部に未適用の関数あり（既知のブレ ①）。
• アクションはUIで必要なものだけ作成する。使われない CRUD は作らず、必要になった時点で追加する。
• 戻り値は Result<T>（{ success: true, data } または { success: false, errorCode }）。例外をクライアントへ投げず、failed() を返す。
• 成功は succeeded(data)、失敗は failed(ErrorCode.X, { log })。失敗時は logError で記録される。
• システム管理画面の更新系は session.user.isSystemManager を検証してから処理する。
• 読み取り系は必要に応じ React cache() でラップ（例：listGenerationLogCached）。

export async function createHomestaging(data): Promise<Result<Homestaging>> {
  return action("createHomestaging", async (user) => {
    // user.organization 利用可
    if (!inputImageUri) return failed(ErrorCode.BadRequest, { log: { ... } });
    const homestaging = await prisma.homestaging.create({ ... });
    return succeeded(homestaging);
  });
}

エラーコード

• ErrorCode（lib/server-action/error-code.ts）に集中定義する。
• 共通：Unexpected / Unauthorized / BadRequest / FeatureUnavailable。
• ドメイン固有はネストして定義：例 ErrorCode.Cleaning.GenerationHasAlreadyStarted、ErrorCode.SystemNotification.HasBeenExpired。

Prisma / データモデル

• 1モデル＝1ファイルで prisma/schema/*.prisma に分割する。
• モデル・フィールドに /// ドキュメントコメントと @namespace を付ける（埋め込み用語集として機能）。
• 主キー：cuid(2)・@db.VarChar(30)。
• カラムは @map("snake_case")、テーブルは @@map("snake_case_複数形")。
• タイムスタンプ：createdAt / updatedAt。
• 論理削除：deletedAt を持ち、取得時は where: { deletedAt: null } で除外する。
• 柔軟な構造は Json カラム＋ Zod スキーマで parse（packages/database/lib/{domain}/）。kind 判別は discriminated union。

認証・認可

• NextAuth。サーバー側は auth() でセッション取得。
• ページ保護は AuthPage ラッパーを用いる。
• session.user は organization や isSystemManager 等のフラグを持つ。権限はこれで分岐する。

外部サービス

• 画像生成：Google Gemini（@google/genai、lib/gemini）。
• 画像保存：AWS S3。アップロード時は 画像内容の MD5 ハッシュをキーに用いる（コンテンツアドレス）。公開参照は CloudFront 経由（AWS_CLOUDFRONT_ENDPOINT + key）。
  • サーバー経由：lib/aws/s3/upload（base64 を Buffer.from(data, "base64") でバイナリ化して保存）。
  • クライアント直接アップロード（presigned URL 方式）：actions/s3/get-upload-url で presigned PUT URL を取得し、ブラウザから S3 へ直接 PUT する。 ⚠️ PUT のボディは必ずバイナリ（Blob）にする。ImageData.data は base64 文字列なので、そのまま fetch の body にすると S3 に「base64 テキスト」が保存され画像が壊れる（S3 は base64 を自動デコードしない）。 await (await fetch(`data:${mimeType};base64,${data}`)).blob() 等でデコードしてから PUT する。 PUT の content-type は presigned の ContentType と一致させる。 画像生成（ホームステージング / DIYリフォーム / 家具消し / 家具引越し / 居抜き / 3D間取り 等）の作成フォームではこの方式を標準とし、作成サーバーアクションは inputImage（base64）ではなく inputImageUri を受け取る形に統一する（base64 をサーバーへ通さず VPC/ECS/WAF コストを抑える。2026/06/10 セッション。外装は未対応 →課題）。
  • ⚠️ コンテンツアドレスの罠：キーが MD5(内容) のため、実装を変えても同一画像なら同一キーになる。S3 の中身を確認して動作検証する際は、旧実装が残したオブジェクトとのキー衝突による誤検知に注意（一度削除してから再アップロードして先頭バイトを確認するのが確実）。
  • ⚠️ get-upload-url は現状クライアント指定の key を検証していない（課題）。サーバー側でのキー生成/接頭辞検証へ寄せたい。
• 決済：Mulpay（@aihomestaging/mulpay）。
• 日時：@aihomestaging/datetime（日時・タイムゾーン 参照）。

日時・タイムゾーン

• 標準は DateTime（@aihomestaging/datetime から import { DateTime }）。 内部実装は date-fns + @date-fns/tz。 生成：DateTime.of({ datetime, timezone })（datetime 文字列は "yyyy-MM-dd HH:mm:ss"）。 主なメソッド：monthStart() / addMonth(n) / toString({ format, timezone }) / toDate()。 フォーマットは date-fns トークン（年は yyyy、月は M／MM。tempo の YYYY とは異なる点に注意）。
• LocalDateTime（@aihomestaging/datetime/lib/local-datetime）は非推奨（@deprecated）。 タイムゾーン計算の挙動に問題があり、DateTime へ統一中。新規コードでは使用しない。 既存利用（organizations / system-notifications 配下など）は順次移行する。
• 月境界は Asia/Tokyo を正とする。 年月集計（生成ログの月次集計・課金履歴の対象月など）は JST の月初 00:00:00 を境界として gte（以上）/ lt（未満）で範囲指定する。

既知のブレ（要整理）

開発を進める中で方針が変わり、コードベースに生じている不整合のうち、把握済みのもの。 今後どちらかへ寄せる予定の項目を記録する（意図通りの差異はここには含めない）。