$ curl https://get.volta.sh | bash

$ volta -v

$ volta install node@24.21.0

$ node -v

$ brew install pnpm

$ pnpm -v

$ mkdir hono-sample && cd hono-sample
$ pnpm create hono@latest .

$ touch .npmrc

engine-strict=true

{

・・・

  "engines": {
    "node": "24.21.0",
    "pnpm": "12.6.0"
  },
  "packageManager": "pnpm@12.6.0",

・・・

$ pnpm run dev

/hono-sample
 └─ /src
     |
     ├─ /core（中核の業務領域）
     |   |
     |   └─ /[domainName]（ドメインモジュール）
     |       |
     |       ├─ /domain（ドメイン）
     |       |   |
     |       |   ├─ [entityName].ts（エンティティ）
     |       |   |
     |       |   ├─ [valueObjectName].ts（値オブジェクト）
     |       |   |
     |       |   ├─ [domainServiceName]Service.ts（ドメインサービス）
     |       |   |
     |       |   ├─ [repositoryName]Repository.ts（リポジトリのインターフェース）
     |       |   |
     |       |   └─ [gatewayName]Gateway.ts（外部サービス用のインターフェース）
     |       |
     |       |
     |       ├─ /usecase（ユースケース層）
     |       |
     |       └─ /infrastructure（ドメイン用のインフラストラクチャ層）
     |           |
     |           ├─ /persistence（パーシステンス層）
     |           |   |
     |           |   └─ /pg（PostgreSQL用）
     |           |       |
     |           |       ├─ /command（書き込み）
     |           |       |
     |           |       └─ /query（読み込み）
     |           |
     |           └─ /external（外部サービスの実装）
     |
     ├─ /supporting（補完的なの業務領域）
     |   |
     |   └── /[supportingName]（サービス層）
     |        |
     |        └─ useCase.ts（ユースケース）
     |
     ├─ /generic（一般的な業務領域）
     |
     ├─ /shared（横断関心）
     |   |
     |   └─ /logger（共通ロガーの定義）
     |       |
     |       └─ logger.ts
     |
     ├─ /di（DIコンテナ層）
     |   |
     |   └─ nodeContainer.ts（Node.js環境用）
     |
     ├─ /infrastructure（共通のインフラストラクチャ層）
     |   |
     |   ├─ /logger
     |   |   |
     |   |   └─ consoleLogger.ts（consoleロガーの実装）
     |   |
     |   └─ /database
     |       |
     |       └─ /drizzle（Drizzle ORM用）
     |           |
     |           └─ /pg（PostgreSQL用）
     |               |
     |               ├─ /migration（マイグレーション関連）
     |               |
     |               ├─ /schema（スキーマ定義）
     |               |
     |               └─ client.ts（接続設定）
     |
     ├─ /presentation（プレゼンテーション層）
     |   |
     |   └─ /http
     |       |
     |       ├─ /middleware（ミドルウェア）
     |       |
     |       ├─ /core
     |       |   |
     |       |   └─ /[domainName]
     |       |       |
     |       |       ├─ handler.ts（ハンドラー部分）
     |       |       |
     |       |       └─ routes.ts（ルーティング部分）
     |       |
     |       ├─ /supporting
     |       |   |
     |       |   └─ /[supportingName]
     |       |       |
     |       |       ├─ handler.ts（ハンドラー部分）
     |       |       |
     |       |       └─ routes.ts（ルーティング部分）
     |       |
     |       ├─ /generic
     |       |
     |       └─ routesNode.ts（Node.js環境用のルーティング設定）
     |
     ├─ /runtime（ランタイム層）
     |   |
     |   └─ /node（Node.js環境用）
     |       |
     |       ├─ config.ts（コンフィグ設定）
     |       |
     |       ├─ app.ts（アプリ設定）
     |       |
     |       └─ server.ts（サーバー設定）
     |
     ├─ /tests（結合テスト用）
     |
     └─ app.ts（アプリ全体の定義）

$ pnpm add -D vitest @biomejs/biome
$ pnpm add zod @hono/zod-validator

$ pnpm biome init

$ mkdir -p src/shared/logger && touch src/shared/logger/logger.ts
$ mkdir -p src/infrastructure/logger && touch src/infrastructure/logger/consoleLogger.ts

// ログ用コンテキストの型定義
export type LogContext = {
  requestId?: string;
  [key: string]: unknown;
};

// ロガーのインターフェース定義
export interface Logger {
  info(message: string, context?: LogContext): void;
  warn(message: string, context?: LogContext): void;
  error(message: string, context?: LogContext): void;
  debug(message: string, context?: LogContext): void;
  withRequestId(requestId: string): Logger;
};

import type { LogContext, Logger } from "../../shared/logger/logger.js";

// ロガーの作成用関数
const createLogger = (baseContext: LogContext = {}): Logger => {
  // ログ出力用の関数定義
  const log = (level: string, message: string, context: LogContext = {}) => {
    console.log(
      JSON.stringify({
        level,
        message,
        ...baseContext,
        ...context,
        timestamp: new Date().toISOString(),
      }),
    );
  };

  return {
    info(message, context) {
      log("INFO", message, context);
    },

    warn(message, context) {
      log("WARN", message, context);
    },

    error(message, context) {
      log("ERROR", message, context);
    },

    debug(message, context) {
      log("DEBUG", message, context);
    },

    withRequestId(requestId) {
      return createLogger({
        ...baseContext,
        requestId,
      });
    },
  };
};

// ロガーのインスタンス
export const logger = createLogger();

$ mkdir -p src/supporting/sample && touch src/supporting/sample/useCase.ts src/supporting/sample/useCase.test.ts
$ mkdir -p src/tests/integration/supporting/sample && touch src/tests/integration/supporting/sample/sample.test.ts
$ mkdir -p src/presentation/http/supporting/sample && touch src/presentation/http/supporting/sample/handler.ts
$ touch src/presentation/http/supporting/sample/routes.ts src/presentation/http/supporting/sample/routes.test.ts
$ mkdir -p src/presentation/http/middleware && touch src/presentation/http/middleware/requestLogger.ts
$ touch src/app.ts .env
$ rm src/index.ts

import type { Logger } from "../../shared/logger/logger.js";

type SampleTextInput = {
  text: string;
};

export class SampleHelloUseCase {
  execute(logger: Logger) {
    // ログ出力
    logger.info("SampleHelloUseCaseを実行！");

    return {
      message: "Hello World !!",
    };
  }
}

export class SampleTextUseCase {
  execute(logger: Logger, input: SampleTextInput) {
    // ログ出力
    logger.info("SampleTextUseCaseを実行！", { text: input.text });

    return {
      message: input.text,
    };
  }
}

import { beforeEach, describe, expect, it, vi } from "vitest";
import type { Logger } from "../../shared/logger/logger.js";
import { SampleHelloUseCase, SampleTextUseCase } from "./useCase.js";

// ロガーのモック化
const createMockLogger = (): Logger => ({
  info: vi.fn(),
  warn: vi.fn(),
  error: vi.fn(),
  debug: vi.fn(),
  withRequestId: vi.fn(),
});

let logger: Logger;

// テスト前の共通セットアップ
beforeEach(() => {
  logger = createMockLogger();
});

describe("SampleHelloUseCase", () => {
  it("Hello Worldを返す", () => {
    // ユースケース作成
    const useCase = new SampleHelloUseCase();

    // ユースケース実行
    const result = useCase.execute(logger);

    // 検証
    expect(result).toEqual({
      message: "Hello World !!",
    });

    expect(logger.info).toHaveBeenCalledWith("SampleHelloUseCaseを実行！");
  });
});

describe("SampleTextUseCase", () => {
  it("渡されたtextを返す", () => {
    // ユースケース作成
    const useCase = new SampleTextUseCase();

    // ユースケース実行
    const result = useCase.execute(logger, {
      text: "テストメッセージ",
    });

    // 検証
    expect(result).toEqual({
      message: "テストメッセージ",
    });

    expect(logger.info).toHaveBeenCalledWith("SampleTextUseCaseを実行！", {
      text: "テストメッセージ",
    });
  });
});

import { testClient } from "hono/testing";
import { describe, expect, it, vi } from "vitest";
import { createNodeApp } from "../../../../runtime/node/app.js";
import type { NodeConfig } from "../../../../runtime/node/config.js";
import { config } from "../../../../runtime/node/config.js";

// ログ出力の無効化
vi.spyOn(console, "log").mockImplementation(() => {});

// テスト用コンフィグ変数
let testConfig: NodeConfig;

// テスト用クライアント作成関数
const createTestClient = () => {
  testConfig = {
    ...config,
  };

  return testClient(createNodeApp(testConfig));
};

describe("GET /api/v1/sample", () => {
  const client = createTestClient();

  it("メッセージに「Hello World !!」を出力し、正常終了すること", async () => {
    // テスト実行
    const response = await client.api.v1.sample.$get();

    // 検証
    expect(response.status).toBe(200);

    // レスポンス結果の検証
    const body = await response.json();
    expect(body).toEqual({
      message: "Hello World !!",
    });
  });
});

describe("POST /api/v1/sample", () => {
  const client = createTestClient();

  it("メッセージに「サンプルテキスト！」を出力し、正常終了すること", async () => {
    // テスト実行
    const response = await client.api.v1.sample.$post({
      json: {
        text: "サンプルテキスト！",
      },
    });

    // 検証
    expect(response.status).toBe(200);

    // レスポンス結果の検証
    const body = await response.json();
    expect(body).toEqual({
      message: "サンプルテキスト！",
    });
  });
});

import type { Context } from "hono";
import type {
  SampleHelloUseCase,
  SampleTextInput,
  SampleTextUseCase,
} from "../../../../supporting/sample/useCase.js";

export const createSampleHelloHandler =
  (useCase: SampleHelloUseCase) => (c: Context) => {
    // 共通ロガー取得
    const logger = c.get("logger");

    // ユースケース実行
    const result = useCase.execute(logger);

    return c.json(result);
};

export const createSampleTextHandler =
  (useCase: SampleTextUseCase) => (c: Context, input: SampleTextInput) => {
    // 共通ロガー取得
    const logger = c.get("logger");

    // ユースケース実行
    const result = useCase.execute(logger, input);

    return c.json(result);
};

import { zValidator } from "@hono/zod-validator";
import { Hono } from "hono";
import { z } from "zod";
import type {
  SampleHelloUseCase,
  SampleTextInput,
  SampleTextUseCase,
} from "../../../../supporting/sample/useCase.js";
import {
  createSampleHelloHandler,
  createSampleTextHandler,
} from "./handler.js";

// リクエストボディ用のスキーマ定義
const sampleTextRequestBodySchema = z.object({
  text: z
    .string()
    .min(1, "textは必須です")
    .max(10, "textは10文字以内で入力してください"),
});


export const createSampleRoutes = (
  sampleHelloUseCase: SampleHelloUseCase,
  sampleTextUseCase: SampleTextUseCase,
) => {
  // Honoでルーティングを作る際は、メソッドチェーン推薦
  return (
    new Hono()
      // GET /sample
      .get("/", createSampleHelloHandler(sampleHelloUseCase))
      // POST /sample
      .post(
        "/",
        zValidator("json", sampleTextRequestBodySchema), // バリデーションチェック
        (c) => {
          // バリデーション済みのリクエストパラメータを取得
          const { text } = c.req.valid("json");

          // バリデーション済みのリクエストパラメータを取得
          const input: SampleTextInput = { text };

          return createSampleTextHandler(sampleTextUseCase)(c, input);
        },
      )
  );
};

import { Hono } from "hono";
import { testClient } from "hono/testing";
import { beforeEach, describe, expect, it, vi } from "vitest";
import { createApp } from "../../../../app.js";
import type { NodeConfig } from "../../../../runtime/node/config.js";
import { config } from "../../../../runtime/node/config.js";
import type {
  SampleHelloUseCase,
  SampleTextUseCase,
} from "../../../../supporting/sample/useCase.js";
import { createSampleRoutes } from "./routes.js";

// ログ出力の無効化
vi.spyOn(console, "log").mockImplementation(() => {});

// UseCaseのモック
let sampleHelloUseCase: {
  execute: ReturnType<typeof vi.fn>;
};

let sampleTextUseCase: {
  execute: ReturnType<typeof vi.fn>;
};

// テスト用クライアント作成関数
const createTestClient = (config: NodeConfig) => {
  // ルーティング設定
  const v1 = new Hono().route(
    "/sample",
    createSampleRoutes(
      sampleHelloUseCase as SampleHelloUseCase,
      sampleTextUseCase as SampleTextUseCase,
    ),
  );
  const routes = new Hono().route("/v1", v1);
  const app = createApp(config).route("/api", routes);

  return testClient(app);
};

// テスト用クライアント変数
let client: ReturnType<typeof createTestClient>;

// テスト用コンフィグ変数
let testConfig: NodeConfig;

// テスト前の共通セットアップ
beforeEach(() => {
  // モックの初期化
  sampleHelloUseCase = {
    execute: vi.fn().mockReturnValue({
      message: "Hello World !!",
    }),
  };

  sampleTextUseCase = {
    execute: vi.fn().mockReturnValue({
      message: "テキスト！",
    }),
  };

  testConfig = {
    ...config,
  };

  client = createTestClient(testConfig);
});

describe("GET /api/v1/sample", () => {
  it("正常終了すること", async () => {
    // テスト実行
    const response = await client.api.v1.sample.$get();

    // 検証
    expect(response.status).toBe(200);
    expect(sampleHelloUseCase.execute).toHaveBeenCalledTimes(1);
  });
});

describe("POST /api/v1/sample", () => {
  it("正常終了すること", async () => {
    // テスト実行
    const response = await client.api.v1.sample.$post({
      json: {
        text: "サンプル！",
      },
    });

    // 検証
    expect(response.status).toBe(200);
    expect(sampleTextUseCase.execute).toHaveBeenCalledTimes(1);
    expect(sampleTextUseCase.execute).toHaveBeenCalledWith(expect.anything(), {
      text: "サンプル！",
    });
  });

  it("textが未指定の場合にバリデーションエラーになること", async () => {
    // テスト実行
    const response = await client.api.v1.sample.$post({
      json: {
        text: "",
      },
    });

    // 検証
    expect(response.status).toBe(400);
    expect(sampleTextUseCase.execute).not.toHaveBeenCalled();
  });

  it("textが全角10文字以内の場合に正常終了すること", async () => {
    // テスト実行
    const response = await client.api.v1.sample.$post({
      json: {
        text: "あいうえおかきくけこ",
      },
    });

    // 検証
    expect(response.status).toBe(200);
    expect(sampleTextUseCase.execute).toHaveBeenCalledTimes(1);
  });

  it("textが全角10文字を超えている場合にバリデーションエラーになること", async () => {
     // テスト実行
     const response = await client.api.v1.sample.$post({
       json: {
         text: "あいうえおかきくけこさ",
       },
     });

     // 検証
     expect(response.status).toBe(400);
     expect(sampleTextUseCase.execute).not.toHaveBeenCalled();
  });

  it("textが半角10文字以内の場合に正常終了すること", async () => {
    // テスト実行
    const response = await client.api.v1.sample.$post({
      json: {
        text: "abcdefghij",
      },
    });

    // 検証
    expect(response.status).toBe(200);
    expect(sampleTextUseCase.execute).toHaveBeenCalledTimes(1);
  });

  it("textが半角10文字を超えている場合にバリデーションエラーになること", async () => {
    // テスト実行
    const response = await client.api.v1.sample.$post({
      json: {
        text: "abcdefghijk",
      },
    });

    // 検証
    expect(response.status).toBe(400);
    expect(sampleTextUseCase.execute).not.toHaveBeenCalled();
  });
});

import { createMiddleware } from "hono/factory";
import { logger } from "../../../infrastructure/logger/consoleLogger.js";

export const requestLogger = createMiddleware(async (c, next) => {
  // 処理の開始時刻を取得
  const start = performance.now();

  // Honoのミドルウェアで設定したリクエストIDを取得
  const requestId = c.get("requestId");

  // リクエストIDをセットしたロガーを取得
  const requestLogger = logger.withRequestId(requestId);

  // 共通ロガーを設定
  c.set("logger", requestLogger);

  // 処理実行
  await next();

  // 処理時間を取得
  const duration = performance.now() - start;

  // 処理結果をログ出力
  requestLogger.info("HTTP request", {
    method: c.req.method,
    path: c.req.path,
    durationMs: Math.round(duration),
    status: c.res.status,
  });
});

import { Hono } from "hono";
import { cors } from "hono/cors";
import { requestId } from "hono/request-id";
import { requestLogger } from "./presentation/http/middleware/requestLogger.js";
import type { Logger } from "./shared/logger/logger.js";

// アプリのコンフィグ型
export type AppConfig = {
  env: string;
  corsOrigin: string;
};

// アプリの変数型
export type AppVariables = {
  Variables: {
    requestId: string;
    logger: Logger;
  };
};

export const createApp = (config: AppConfig) => {
  // Honoでルーティングを作る際は、メソッドチェーン推薦
  return (
    new Hono<AppVariables>()
      .get("/", (c) => {
        return c.text("Hello Hono!");
      })
      // CORS設定
      .use(
        "*",
        cors({
          origin: config.corsOrigin,
          allowHeaders: ["Content-Type", "Authorization"],
          credentials: true,
        }),
      )
      // 共通ミドルウェア設定
      .use("*", requestId())
      .use("*", requestLogger)
  );
};

ENV=local
PORT=3000
CORS_ORIGIN="http://localhost:3000"

$ mkdir -p src/runtime/node
$ touch src/runtime/node/config.ts src/runtime/node/app.ts src/runtime/node/server.ts
$ mkdir -p src/di && touch src/di/nodeContainer.ts
$ touch src/presentation/http/routesNode.ts

import type { AppConfig } from "../../app.js";

// Node環境用のコンフィグ型
export type NodeConfig = AppConfig & {
  port: number;
};

// Node環境用のコンフィグ設定
export const config: NodeConfig = {
  env: process.env.ENV ?? "local",
  corsOrigin: process.env.CORS_ORIGIN ?? "http://localhost:3000",
  port: Number(process.env.PORT ?? "3000"),
};

import { createApp } from "../../app.js";
import { createNodeContainer } from "../../di/nodeContainer.js";
import { createRoutesNode } from "../../presentation/http/routesNode.js";
import type { NodeConfig } from "./config.js";

// Node.js環境用のapp作成関数
export const createNodeApp = (config: NodeConfig) => {
  const container = createNodeContainer(config);

  return createApp(config).route("/api", createRoutesNode(container));
};

export type NodeApp = ReturnType<typeof createNodeApp>;

import { serve } from "@hono/node-server";
import { createNodeApp } from "./app.js";
import { config } from "./config.js";

// Node.js環境用のapp作成
const app = createNodeApp(config);

// サーバー起動処理
serve(
  {
    fetch: app.fetch,
    port: config.port,
  },
  (info) => {
    console.log(`Server is running on http://localhost:${info.port}`);
  },
);

import type { NodeConfig } from "../runtime/node/config.js";
import {
  SampleHelloUseCase,
  SampleTextUseCase,
} from "../supporting/sample/useCase.js";

export const createNodeContainer = (_config: NodeConfig) => {
  const sampleHelloUseCase = new SampleHelloUseCase();
  const sampleTextUseCase = new SampleTextUseCase();

  return {
    sampleHelloUseCase,
    sampleTextUseCase,
  };
};

export type NodeContainer = ReturnType<typeof createNodeContainer>;

import { Hono } from "hono";
import type { NodeContainer } from "../../di/nodeContainer.js";
import { createSampleRoutes } from "../http/supporting/sample/routes.js";

export const createRoutesNode = (container: NodeContainer) => {
  /******************************
  * v1用のルーティング
  ******************************/
  // Honoでルーティングを作る際は、メソッドチェーン推薦
  const v1 = new Hono()
    .route(
      "/sample",
      createSampleRoutes(
        container.sampleHelloUseCase,
        container.sampleTextUseCase,
      ),
    );

  /******************************
  * ルーティング設定
  ******************************/
  return new Hono().route("/v1", v1);
};

{

・・・

  "scripts": {
    "dev": "pnpm run dev:node",
    "dev:node": "tsx watch src/runtime/node/server.ts",
    "build:node": "tsc",
    "start:node": "node dist/runtime/node/server.js",
    "test": "vitest run",
    "test:verbose": "vitest run --reporter=verbose",
    "test:watch": "vitest",
    "format": "biome format --write . && biome check --write --only=assist/source/organizeImports .",
    "lint": "biome lint .",
    "check": "biome check .",
    "check:fix": "biome check --write ."
  },

・・・

}

$ pnpm run format
$ pnpm run lint

$ pnpm run test

$ pnpm run dev

$ mkdir -p deploy/docker/local/db/pg && touch deploy/docker/local/db/pg/Dockerfile
$ mkdir -p deploy/docker/local/db/pg/init && touch deploy/docker/local/db/pg/init/init.sql
$ touch compose.yaml

FROM postgres:18.6

ENV LANG=ja_JP.utf8

# PostgreSQLの日本語化で「ja_JP.utf8」を使うために必要
RUN apt-get update && \
    apt-get install -y locales && \
    rm -rf /var/lib/apt/lists/* && \
    localedef -i ja_JP -c -f UTF-8 -A /usr/share/locale/locale.alias ja_JP.UTF-8

-- テスト用DB作成
CREATE DATABASE "testing-db-pg";

services:
  pg:
    container_name: hono-sample-pg
    build:
      context: .
      dockerfile: ./deploy/docker/local/db/pg/Dockerfile
    environment:
      POSTGRES_DB: "local-db-pg"
      POSTGRES_USER: "root"
      POSTGRES_PASSWORD: "root-pass"
      # ローカル環境でもパスワードを有効化する設定
      POSTGRES_INITDB_ARGS: --auth-local=scram-sha-256 --auth-host=scram-sha-256
    volumes:
      - hono-sample-pg-data:/var/lib/postgresql
      # 初回起動時にSQLを実行する設定
      - ./deploy/docker/local/db/pg/init:/docker-entrypoint-initdb.d
    ports:
      - "5432:5432"
volumes:
  hono-sample-pg-data:

ENV=production
PORT=3000
CORS_ORIGIN="http://localhost:3000"
DB_PG_NAME=local-db-pg
DB_PG_USER=root
DB_PG_PASSWORD=root-pass
DB_PG_HOST=localhost
DB_PG_PORT=5432
DB_PG_MAX_OPEN_CONNS=2
DB_PG_CONN_MAX_LIFETIME=300

$ docker compose up -d

$ docker compose ps

$ pnpm add drizzle-orm pg dotenv
$ pnpm add -D drizzle-kit @types/pg

$ touch drizzle.pg.config.ts
$ mkdir -p src/infrastructure/database/drizzle/pg && touch src/infrastructure/database/drizzle/pg/client.ts

import "dotenv/config";
import { defineConfig } from "drizzle-kit";

// テスト用のDB名
const testingDbPgName = "testing-db-pg";

// 接続先DB名
const dbPgName =
  process.env.ENV === "testing" ? testingDbPgName : process.env.DB_PG_NAME;

// 接続先URL
const url =
  `postgresql://${process.env.DB_PG_USER}:${process.env.DB_PG_PASSWORD}` +
  `@${process.env.DB_PG_HOST}:${process.env.DB_PG_PORT}` +
  `/${dbPgName}`;

// drizzleのDB接続設定
export default defineConfig({
  dialect: "postgresql",
  schema: "./src/infrastructure/database/drizzle/pg/schema/*.ts",
  out: "./src/infrastructure/database/drizzle/pg/migrations",
  dbCredentials: {
    url: url,
  },
});

import type { NodePgDatabase } from "drizzle-orm/node-postgres";
import { drizzle } from "drizzle-orm/node-postgres";
import { Pool } from "pg";

// PostgreSQL用のコンフィグ型
export type PgConfig = {
  name: string;
  user: string;
  password: string;
  host: string;
  port: number;
  maxOpenConns: number;
  connMaxLifetime: number;
};

// PostgreSQLのインスタンス型
export type PgDatabase = NodePgDatabase;

// PostgreSQLのトランザクションのインスタンス型
export type PgTransaction = Parameters<
  Parameters<PgDatabase["transaction"]>[0]
>[0];

// PostgreSQLのDBクライアント型
export type PgDbClient = PgDatabase | PgTransaction;

// DBインスタンス生成用関数
export const createDbPg = (config: PgConfig) => {
  const pool = new Pool({
    database: config.name,
    user: config.user,
    password: config.password,
    host: config.host,
    port: config.port,
    max: config.maxOpenConns,
    maxLifetimeSeconds: config.connMaxLifetime,
  });

  const db = drizzle({
    client: pool,
  });

  return {
    pool,
    db,
  };
};

export type DbPg = ReturnType<typeof createDbPg>;

{
  ・・・

  "exclude": ["node_modules", "drizzle.pg.config.ts"]
}

$ mkdir -p src/infrastructure/database/drizzle/pg/schema && touch src/infrastructure/database/drizzle/pg/schema/users.ts

import {
  bigint,
  index,
  integer,
  pgTable,
  text,
  timestamp,
  uuid,
} from "drizzle-orm/pg-core";

export const users = pgTable(
  "users",
  {
    id: bigint("id", { mode: "number" })
      .primaryKey()
      .generatedAlwaysAsIdentity(),
    uid: uuid().notNull().defaultRandom().unique(),
    lastName: text("last_name").notNull(),
    firstName: text("first_name").notNull(),
    totalPurchaseAmount: integer("total_purchase_amount").notNull().default(0),
    createdAt: timestamp("created_at", {
      withTimezone: true,
    })
      .notNull()
      .defaultNow(),
    updatedAt: timestamp("updated_at", {
      withTimezone: true,
    })
      .notNull()
      .defaultNow(),
  },
  (table) => [index("users_last_name_idx").on(table.lastName)],
);

$ pnpm drizzle-kit generate --config=drizzle.pg.config.ts

$ pnpm drizzle-kit migrate --config=drizzle.pg.config.ts

docker compose exec pg bash
PGPASSWORD=root-pass psql -U root -d local-db-pg
\dt

\d users

\q
exit

$ pnpm add -D wrangler @cloudflare/workers-types

$ pnpm wrangler --version

$ touch wrangler.jsonc

{
  "name": "local-d1",
  "compatibility_date": "2026-09-29",

  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "local-db-d1",
      "database_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "migrations_dir": "src/infrastructure/database/drizzle/d1/migrations"
    }
  ]
}

$ pnpm wrangler d1 execute local-db-d1 --local --command="SELECT 1"

{
  "name": "local-d1",
  "compatibility_date": "2026-09-29",

  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "local-db-d1",
      "database_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "migrations_dir": "src/infrastructure/database/drizzle/d1/migrations"
    },
    {
      "binding": "TEST_DB",
      "database_name": "testing-db-d1",
      "database_id": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
      "migrations_dir": "src/infrastructure/database/drizzle/d1/migrations"
    }
  ]
}

$ pnpm wrangler d1 execute testing-db-d1 --local --command="SELECT 1"

ENV=production
PORT=3000
CORS_ORIGIN="http://localhost:3000"
DB_PG_NAME=local-db-pg
DB_PG_USER=root
DB_PG_PASSWORD=root-pass
DB_PG_HOST=localhost
DB_PG_PORT=5432
DB_PG_MAX_OPEN_CONNS=2
DB_PG_CONN_MAX_LIFETIME=300
DB_D1_PATH=".wrangler/state/v3/d1/miniflare-D1DatabaseObject/423c60534c20823e3775c6e1de8b0d6f1fb85ef14b525413932d985d8dc6abf5.sqlite"
DB_D1_TEST_PATH=".wrangler/state/v3/d1/miniflare-D1DatabaseObject/d5cace998a99b013073f98823ec85d6a6601f80941c4f243f809eef878b809e8.sqlite"

・・・

# wrangler
.wrangler/

$ pnpm add -D node-gyp @types/better-sqlite3
$ pnpm add better-sqlite3

$ touch drizzle.d1.config.ts
$ mkdir -p src/infrastructure/database/drizzle/d1 && touch src/infrastructure/database/drizzle/d1/client.ts

import "dotenv/config";
import { defineConfig } from "drizzle-kit";

// 接続先DBパス
const dbPath =
  process.env.ENV === "testing"
    ? process.env.DB_D1_TEST_PATH
    : process.env.DB_D1_PATH;

// 接続先URL
const url = `${dbPath}`;

// drizzleのDB接続設定
export default defineConfig({
  dialect: "sqlite",
  schema: "./src/infrastructure/database/drizzle/d1/schema/*.ts",
  out: "./src/infrastructure/database/drizzle/d1/migrations",
  dbCredentials: {
    url: url,
  },
});

import type { DrizzleD1Database } from "drizzle-orm/d1";
import { drizzle } from "drizzle-orm/d1";

// DBインスタンスの型
export type DatabaseD1 = DrizzleD1Database;

// DBクライアントの型
export type DbClient = DatabaseD1;

// DBインスタンス生成用関数
export const createDbD1 = (db: D1Database): DatabaseD1 => {
  return drizzle(db);
};

{
  "compilerOptions": {

    ・・・

    "types": ["node", "@cloudflare/workers-types"],
  
    ・・・

  },
  "exclude": ["node_modules", "drizzle.pg.config.ts", "drizzle.d1.config.ts"]
}

$ mkdir -p src/infrastructure/database/drizzle/d1/schema && touch src/infrastructure/database/drizzle/d1/schema/users.ts

import { index, integer, sqliteTable, text } from "drizzle-orm/sqlite-core";

export const users = sqliteTable(
  "users",
  {
    id: integer("id").primaryKey({ autoIncrement: true }),
    uid: text("uid").notNull().unique(),
    lastName: text("last_name").notNull(),
    firstName: text("first_name").notNull(),
    totalPurchaseAmount: integer("total_purchase_amount").notNull().default(0),
    createdAt: integer("created_at", {
      mode: "timestamp",
    })
      .notNull()
      .$defaultFn(() => new Date()),
    updatedAt: integer("updated_at", {
      mode: "timestamp",
    })
      .notNull()
      .$defaultFn(() => new Date()),
  },
  (table) => [index("users_last_name_idx").on(table.lastName)],
);

$ pnpm drizzle-kit generate --config=drizzle.d1.config.ts

$ pnpm drizzle-kit migrate --config=drizzle.d1.config.ts

$ pnpm wrangler d1 execute local-db-d1 --local --command="SELECT name FROM sqlite_master WHERE type='table' ORDER BY name;"

$ pnpm wrangler d1 execute local-db-d1 --local --command="PRAGMA table_info(users);"

$ pnpm wrangler types

{

・・・

  "files": {
    "ignoreUnknown": false,
    "includes": ["**", "!**/worker-configuration.d.ts"]
  },

・・・

}

$ mkdir -p src/runtime/cloudflare
$ touch src/runtime/cloudflare/config.ts src/runtime/cloudflare/app.ts src/runtime/cloudflare/worker.ts
$ touch src/di/cloudflareContainer.ts
$ touch src/presentation/http/routesCloudflare.ts

import type { AppConfig } from "../../app.js";

// Cloudflare環境用のコンフィグ定義
export type CloudflareConfig = AppConfig & {
  db: D1Database;
};

// Cloudflare環境用のコンフィグ設定関数
export const createConfig = (env: Env): CloudflareConfig => {
  return {
    env: env.ENV,
    corsOrigin: env.CORS_ORIGIN,
    db: env.ENV === "testing" ? env.TEST_DB : env.DB,
  };
};

import { createApp } from "../../app.js";
import { createCloudflareContainer } from "../../di/cloudflareContainer.js";
import { createRoutesCloudflare } from "../../presentation/http/routesCloudflare.js";
import type { CloudflareConfig } from "./config.js";

// Cloudflare環境用のapp作成関数
export const createCloudflareApp = (config: CloudflareConfig) => {
  const container = createCloudflareContainer(config);

  return createApp(config).route("/api", createRoutesCloudflare(container));
};

export type CloudflareApp = ReturnType<typeof createCloudflareApp>;

import { createCloudflareApp } from "./app.js";
import { createConfig } from "./config.js";

// サーバー起動処理
export default {
  fetch: (request: Request, env: Env, ctx: ExecutionContext) => {
    // コンフィグ作成
    const config = createConfig(env);

    // Cloudflare用のapp作成
    const app = createCloudflareApp(config);

    // 戻り値
    return app.fetch(request, env, ctx);
  },
};

import type { CloudflareConfig } from "../runtime/cloudflare/config.js";
import {
  SampleHelloUseCase,
  SampleTextUseCase,
} from "../supporting/sample/useCase.js";

export const createCloudflareContainer = (_config: CloudflareConfig) => {
  const sampleHelloUseCase = new SampleHelloUseCase();
  const sampleTextUseCase = new SampleTextUseCase();

  return {
    sampleHelloUseCase,
    sampleTextUseCase,
  };
};

export type CloudflareContainer = ReturnType<typeof createCloudflareContainer>;

import { Hono } from "hono";
import type { CloudflareContainer } from "../../di/cloudflareContainer.js";
import { createSampleRoutes } from "../http/supporting/sample/routes.js";

export const createRoutesCloudflare = (container: CloudflareContainer) => {
  /******************************
  * v1用のルーティング
  ******************************/
  // Honoでルーティングを作る際は、メソッドチェーン推薦
  const v1 = new Hono().route(
    "/sample",
    createSampleRoutes(
      container.sampleHelloUseCase,
      container.sampleTextUseCase,
    ),
  );
  /******************************
  * ルーティング設定
  ******************************/
  return new Hono().route("/v1", v1);
};

$ pnpm wrangler dev

$ mkdir -p src/shared/error && touch src/shared/error/appError.ts
$ mkdir -p src/presentation/http/error
$ touch src/presentation/http/error/errorHandler.ts src/presentation/http/error/errorStatusMap.ts
$ mkdir -p src/generic/user && touch src/generic/user/errors.ts

// ログレベル
export type LogLevel = "info" | "warn" | "error" | "debug";

// 共通エラークラス
export class AppError<TCode extends string = string> extends Error {
  constructor(
    message: string,
    public readonly code: TCode,
    public readonly logLevel: LogLevel = "info",
  ) {
    super(message);
    this.name = "AppError";
  }
}

import type { ErrorHandler } from "hono";
import { AppError } from "../../../shared/error/appError.js";
import { errorStatusMap } from "./errorStatusMap.js";

export const errorHandler: ErrorHandler = (err, c) => {
  const logger = c.get("logger");

  // カスタムエラー用のエラーハンドリング
  // 共通エラークラスを利用してカスタムエラークラスを作成し、
  // エラーコードとHTTPステータスコードのマッピングを行う
  if (err instanceof AppError) {
    const status = errorStatusMap[err.code];

    // エラーコードに対応するHTTPステータスコードが存在する場合は、エラーレスポンスを返す
    if (status) {
      // ログ出力
      logger[err.logLevel]("AppError occurred", {
        error: err,
        requestId: c.get("requestId"),
      });

      return c.json(
        {
          code: err.code,
          message: err.message,
        },
        status,
      );
    }
  }

  logger.error("Unexpected error", {
    error: err,
  });

  return c.json(
    {
      message: "Internal Server Error",
    },
    500,
  );
};

import type { ContentfulStatusCode } from "hono/utils/http-status";
import { userErrorStatusMap } from "../../../generic/user/errors.js";

// 共通エラーコードとHTTPステータスコードのマッピング
export const errorStatusMap: Record<string, ContentfulStatusCode> = {
  ...userErrorStatusMap,
};

import type { ContentfulStatusCode } from "hono/utils/http-status";
import { AppError } from "../../shared/error/appError.js";

// エラーコード（カスタムエラー用）
// 「|」で区切って追加可能
export type UserErrorCode = "USER_NOT_FOUND";

// エラーコードとHTTPステータスコードのマッピング
export const userErrorStatusMap: Record<UserErrorCode, ContentfulStatusCode> = {
  USER_NOT_FOUND: 404,
};

export class UserNotFoundError extends AppError<UserErrorCode> {
  constructor() {
    super("User not found", "USER_NOT_FOUND", "warn");
  }
}

import { Hono } from "hono";
import { cors } from "hono/cors";
import { requestId } from "hono/request-id";
import { errorHandler } from "./presentation/http/error/errorHandler.js";
import { requestLogger } from "./presentation/http/middleware/requestLogger.js";
import type { Logger } from "./shared/logger/logger.js";

// アプリのコンフィグ型
export type AppConfig = {
  env: string;
  corsOrigin: string;
};

// アプリの変数型
export type AppVariables = {
  Variables: {
    requestId: string;
    logger: Logger;
  };
};

export const createApp = (config: AppConfig) => {
  // Honoでルーティングを作る際は、メソッドチェーン推薦
  return (
    new Hono<AppVariables>()
      .get("/", (c) => {
        return c.text("Hello Hono!");
      })
      // エラーハンドラー設定
      .onError(errorHandler)
      // CORS設定
      .use(
        "*",
        cors({
          origin: config.corsOrigin,
          allowHeaders: ["Content-Type", "Authorization"],
          credentials: true,
        }),
      )
      // 共通ミドルウェア設定
      .use("*", requestId())
      .use("*", requestLogger)
  );
};

import type { AppConfig } from "../../app.js";
import type { PgConfig } from "../../infrastructure/database/drizzle/pg/client.js";

// Node環境用のコンフィグ型
export type NodeConfig = AppConfig & {
  port: number;
  db: PgConfig;
};

// Node環境用のコンフィグ設定
export const config: NodeConfig = {
  env: process.env.ENV ?? "local",
  corsOrigin: process.env.CORS_ORIGIN ?? "http://localhost:3000",
  port: Number(process.env.PORT ?? "3000"),
  db: {
    name: process.env.DB_PG_NAME ?? "local-db-pg",
    user: process.env.DB_PG_USER ?? "root",
    password: process.env.DB_PG_PASSWORD ?? "root-pass",
    host: process.env.DB_PG_HOST ?? "localhost",
    port: Number(process.env.DB_PG_PORT ?? "5432"),
    maxOpenConns: Number(process.env.DB_PG_MAX_OPEN_CONNS ?? "2"),
    connMaxLifetime: Number(process.env.DB_PG_CONN_MAX_LIFETIME ?? "300"),
  },
};

$ touch src/generic/user/useCase.ts src/generic/user/useCase.test.ts
$ mkdir -p src/presentation/http/generic/user
$ touch src/presentation/http/generic/user/handler.ts
$ touch src/presentation/http/generic/user/routes.ts src/presentation/http/generic/user/routes.test.ts
$ mkdir -p src/tests/integration/generic/user && touch src/tests/integration/generic/user/user.test.ts

import { eq } from "drizzle-orm";
import type { PgDatabase } from "../../infrastructure/database/drizzle/pg/client.js";
import { users } from "../../infrastructure/database/drizzle/pg/schema/users.js";
import type { Logger } from "../../shared/logger/logger.js";
import { UserNotFoundError } from "./errors.js";

export type CreateUserInput = {
  lastName: string;
  firstName: string;
  totalPurchaseAmount: number;
};

export type FindUserInput = {
  uid: string;
};

export type UpdateUserInput = {
  uid: string;
  lastName: string;
  firstName: string;
  totalPurchaseAmount: number;
};

export type DeleteUserInput = {
  uid: string;
};

// ユーザー作成
export class CreateUserUseCase {
  constructor(private readonly db: PgDatabase) {}

  async execute(logger: Logger, input: CreateUserInput) {
    logger.info("Create user", input);

    const [user] = await this.db
      .insert(users)
      .values({
        lastName: input.lastName,
        firstName: input.firstName,
        totalPurchaseAmount: input.totalPurchaseAmount,
      })
      .returning();

    return user;
  }
}

// 全てのユーザー取得
export class FindUsersUseCase {
  constructor(private readonly db: PgDatabase) {}

  async execute(logger: Logger) {
    logger.info("Find users");

    const result = await this.db.select().from(users);

    return result;
  }
}

// 対象のユーザー取得
export class FindUserUseCase {
  constructor(private readonly db: PgDatabase) {}

  async execute(logger: Logger, input: FindUserInput) {
    logger.info("Find user", input);

    const [user] = await this.db
      .select()
      .from(users)
      .where(eq(users.uid, input.uid))
      .limit(1);

      return user ?? {};
  }
}

// 対象のユーザー更新
export class UpdateUserUseCase {
  constructor(private readonly db: PgDatabase) {}

  async execute(logger: Logger, input: UpdateUserInput) {
    logger.info("Update user", input);

    const user = await this.db.transaction(async (tx) => {
      const [user] = await tx
        .update(users)
        .set({
          lastName: input.lastName,
          firstName: input.firstName,
          totalPurchaseAmount: input.totalPurchaseAmount,
          updatedAt: new Date(),
        })
        .where(eq(users.uid, input.uid))
        .returning();

      if (!user) {
        throw new UserNotFoundError();
      }

      return user;
    });

    return user;
  }
}

// 対象のユーザー削除
export class DeleteUserUseCase {
  constructor(private readonly db: PgDatabase) {}

  async execute(logger: Logger, input: DeleteUserInput) {
    logger.info("Delete user", input);

    const [user] = await this.db
      .delete(users)
      .where(eq(users.uid, input.uid))
      .returning();

    if (!user) {
      throw new UserNotFoundError();
    }

    return user;
  }
}

import { beforeEach, describe, expect, it, vi } from "vitest";
import type { PgDatabase } from "../../infrastructure/database/drizzle/pg/client.js";
import type { Logger } from "../../shared/logger/logger.js";
import { UserNotFoundError } from "./errors.js";
import {
  CreateUserUseCase,
  DeleteUserUseCase,
  FindUsersUseCase,
  FindUserUseCase,
  UpdateUserUseCase,
} from "./useCase.js";

// ロガーのモック化
const createMockLogger = (): Logger => ({
  info: vi.fn(),
  warn: vi.fn(),
  error: vi.fn(),
  debug: vi.fn(),
  withRequestId: vi.fn(),
});

// DBのモック化
const createMockDb = <T extends object>(mock: T): PgDatabase =>
  mock as unknown as PgDatabase;

let logger: Logger;

// テスト前の共通セットアップ
beforeEach(() => {
  logger = createMockLogger();
});

describe("CreateUserUseCase", () => {
  it("ユーザーを作成できること", async () => {
    // DBのモック化
    const user = {
      uid: "00000000-0000-0000-0000-000000000001",
      lastName: "山田",
      firstName: "太郎",
      totalPurchaseAmount: 1000,
    };
    const returning = vi.fn().mockResolvedValue([user]);
    const values = vi.fn().mockReturnValue({ returning });
    const insert = vi.fn().mockReturnValue({ values });
    const db = createMockDb({
      insert,
    });

    // ユースケース作成
    const useCase = new CreateUserUseCase(db);

    // ユースケース実行
    const result = await useCase.execute(logger, {
      lastName: "山田",
      firstName: "太郎",
      totalPurchaseAmount: 1000,
    });

    // 検証
    expect(result).toEqual(user);

    expect(logger.info).toHaveBeenCalledWith("Create user", {
      lastName: "山田",
      firstName: "太郎",
      totalPurchaseAmount: 1000,
    });

    expect(values).toHaveBeenCalledWith({
      lastName: "山田",
      firstName: "太郎",
      totalPurchaseAmount: 1000,
    });
  });
});

describe("FindUsersUseCase", () => {
  it("全てのユーザーを取得できること", async () => {
    // DBのモック化
    const users = [
      {
        uid: "00000000-0000-0000-0000-000000000001",
        lastName: "山田",
        firstName: "太郎",
        totalPurchaseAmount: 1000,
      },
      {
        uid: "00000000-0000-0000-0000-000000000002",
        lastName: "佐藤",
        firstName: "花子",
        totalPurchaseAmount: 2000,
      },
    ];
    const from = vi.fn().mockResolvedValue(users);
    const select = vi.fn().mockReturnValue({ from });
    const db = createMockDb({
      select,
    });

    // ユースケース作成
    const useCase = new FindUsersUseCase(db);

    // ユースケース実行
    const result = await useCase.execute(logger);

    // 検証
    expect(result).toEqual(users);

    expect(logger.info).toHaveBeenCalledWith("Find users");
  });
});

describe("FindUserUseCase", () => {
  it("指定したユーザーを取得できること", async () => {
    // DBのモック化
    const user = {
      uid: "00000000-0000-0000-0000-000000000001",
      lastName: "山田",
      firstName: "太郎",
      totalPurchaseAmount: 1000,
    };
    const limit = vi.fn().mockResolvedValue([user]);
    const where = vi.fn().mockReturnValue({ limit });
    const from = vi.fn().mockReturnValue({ where });
    const select = vi.fn().mockReturnValue({ from });
    const db = createMockDb({
      select,
    });

    // ユースケース作成
    const useCase = new FindUserUseCase(db);

    // ユースケース実行
    const result = await useCase.execute(logger, {
      uid: user.uid,
    });

    // 検証
    expect(result).toEqual(user);

    expect(logger.info).toHaveBeenCalledWith("Find user", {
      uid: user.uid,
    });

    expect(limit).toHaveBeenCalledWith(1);
  });

  it("ユーザーが存在しない場合は空オブジェクトを返すこと", async () => {
    // DBのモック化
    const limit = vi.fn().mockResolvedValue([]);
    const where = vi.fn().mockReturnValue({ limit });
    const from = vi.fn().mockReturnValue({ where });
    const select = vi.fn().mockReturnValue({ from });
    const db = createMockDb({
      select,
    });

    // ユースケース作成
    const useCase = new FindUserUseCase(db);

    // ユースケース実行
    const result = await useCase.execute(logger, {
      uid: "00000000-0000-0000-0000-000000000099",
    });

    // 検証
    expect(result).toEqual({});

    expect(logger.info).toHaveBeenCalledWith("Find user", {
      uid: "00000000-0000-0000-0000-000000000099",
    });
  });
});

describe("UpdateUserUseCase", () => {
  it("ユーザーを更新できること", async () => {
    // DBのモック化
    const user = {
      uid: "00000000-0000-0000-0000-000000000001",
      lastName: "山田",
      firstName: "次郎",
      totalPurchaseAmount: 3000,
    };
    const returning = vi.fn().mockResolvedValue([user]);
    const where = vi.fn().mockReturnValue({ returning });
    const set = vi.fn().mockReturnValue({ where });
    const update = vi.fn().mockReturnValue({ set });
    const transaction = vi.fn(async (callback) => {
      return callback({
        update,
      });
    });
    const db = createMockDb({
      transaction,
    });

    // ユースケース作成
    const useCase = new UpdateUserUseCase(db);

    // ユースケース実行
    const result = await useCase.execute(logger, {
      uid: user.uid,
      lastName: "山田",
      firstName: "次郎",
      totalPurchaseAmount: 3000,
    });

    // 検証
    expect(result).toEqual(user);

    expect(logger.info).toHaveBeenCalledWith("Update user", {
      uid: user.uid,
      lastName: "山田",
      firstName: "次郎",
      totalPurchaseAmount: 3000,
    });

    expect(set).toHaveBeenCalledWith({
      lastName: "山田",
      firstName: "次郎",
      totalPurchaseAmount: 3000,
      updatedAt: expect.any(Date),
    });
  });

  it("ユーザーが存在しない場合はUserNotFoundErrorを投げること", async () => {
    // DBのモック化
    const returning = vi.fn().mockResolvedValue([]);
    const where = vi.fn().mockReturnValue({ returning });
    const set = vi.fn().mockReturnValue({ where });
    const update = vi.fn().mockReturnValue({ set });
    const transaction = vi.fn(async (callback) => {
      return callback({
        update,
      });
    });
    const db = createMockDb({
      transaction,
    });

    // ユースケース作成
    const useCase = new UpdateUserUseCase(db);

    // ユースケース実行・検証
    await expect(
      useCase.execute(logger, {
        uid: "00000000-0000-0000-0000-000000000099",
        lastName: "山田",
        firstName: "次郎",
        totalPurchaseAmount: 3000,
      }),
    ).rejects.toBeInstanceOf(UserNotFoundError);

    expect(logger.info).toHaveBeenCalledWith("Update user", {
      uid: "00000000-0000-0000-0000-000000000099",
      lastName: "山田",
      firstName: "次郎",
      totalPurchaseAmount: 3000,
    });
  });
});

describe("DeleteUserUseCase", () => {
  it("ユーザーを削除できること", async () => {
    // DBのモック化
    const user = {
      uid: "00000000-0000-0000-0000-000000000001",
      lastName: "山田",
      firstName: "太郎",
      totalPurchaseAmount: 1000,
    };
    const returning = vi.fn().mockResolvedValue([user]);
    const where = vi.fn().mockReturnValue({ returning });
    const deleteUser = vi.fn().mockReturnValue({ where });
    const db = createMockDb({
      delete: deleteUser,
    });

    // ユースケース作成
    const useCase = new DeleteUserUseCase(db);

    // ユースケース実行
    const result = await useCase.execute(logger, {
      uid: user.uid,
    });

    // 検証
    expect(result).toEqual(user);

    expect(logger.info).toHaveBeenCalledWith("Delete user", {
      uid: user.uid,
    });
  });

  it("ユーザーが存在しない場合はUserNotFoundErrorを投げること", async () => {
    // DBのモック化
    const returning = vi.fn().mockResolvedValue([]);
    const where = vi.fn().mockReturnValue({ returning });
    const deleteUser = vi.fn().mockReturnValue({ where });
    const db = createMockDb({
      delete: deleteUser,
    });

    // ユースケース作成
    const useCase = new DeleteUserUseCase(db);

    // ユースケース実行・検証
    await expect(
      useCase.execute(logger, {
        uid: "00000000-0000-0000-0000-000000000099",
      }),
    ).rejects.toBeInstanceOf(UserNotFoundError);

    expect(logger.info).toHaveBeenCalledWith("Delete user", {
      uid: "00000000-0000-0000-0000-000000000099",
    });
  });
});

import type { Context } from "hono";
import type {
  CreateUserInput,
  CreateUserUseCase,
  DeleteUserInput,
  DeleteUserUseCase,
  FindUserInput,
  FindUsersUseCase,
  FindUserUseCase,
  UpdateUserInput,
  UpdateUserUseCase,
} from "../../../../generic/user/useCase.js";

export const createCreateUserHandler =
  (useCase: CreateUserUseCase) =>
  async (c: Context, input: CreateUserInput) => {
    // 共通ロガー取得
    const logger = c.get("logger");

    // ユースケース実行
    const result = await useCase.execute(logger, input);

    return c.json(result, 201);
  };

export const createFindUsersHandler =
  (useCase: FindUsersUseCase) => async (c: Context) => {
    // 共通ロガー取得
    const logger = c.get("logger");

    // ユースケース実行
    const result = await useCase.execute(logger);

    return c.json(result);
  };

export const createFindUserHandler =
  (useCase: FindUserUseCase) => async (c: Context, input: FindUserInput) => {
    // 共通ロガー取得
    const logger = c.get("logger");

    // ユースケース実行
    const result = await useCase.execute(logger, input);

    return c.json(result);
  };

export const createUpdateUserHandler =
  (useCase: UpdateUserUseCase) =>
  async (c: Context, input: UpdateUserInput) => {
    // 共通ロガー取得
    const logger = c.get("logger");

    // ユースケース実行
    const result = await useCase.execute(logger, input);

    return c.json(result);
  };

export const createDeleteUserHandler =
  (useCase: DeleteUserUseCase) =>
  async (c: Context, input: DeleteUserInput) => {
    // 共通ロガー取得
    const logger = c.get("logger");

    // ユースケース実行
    const _result = await useCase.execute(logger, input);

    return c.body(null, 204);
  };

import { zValidator } from "@hono/zod-validator";
import { Hono } from "hono";
import { z } from "zod";
import type {
  CreateUserInput,
  CreateUserUseCase,
  DeleteUserInput,
  DeleteUserUseCase,
  FindUserInput,
  FindUsersUseCase,
  FindUserUseCase,
  UpdateUserInput,
  UpdateUserUseCase,
} from "../../../../generic/user/useCase.js";
import {
  createCreateUserHandler,
  createDeleteUserHandler,
  createFindUserHandler,
  createFindUsersHandler,
  createUpdateUserHandler,
} from "./handler.js";

// ユーザー作成用のリクエストボディスキーマ定義
const createUserRequestBodySchema = z.object({
  lastName: z
    .string()
    .min(1, "lastNameは必須です")
    .max(10, "lastNameは10文字以内で入力してください"),
  firstName: z
    .string()
    .min(1, "firstNameは必須です")
    .max(10, "firstNameは10文字以内で入力してください"),
  totalPurchaseAmount: z
    .number()
    .min(0, "totalPurchaseAmountは0以上の数値で入力してください"),
});

// ユーザー取得用のリクエストパラメータのスキーマ定義
const findUserRequestParamSchema = z.object({
  uid: z.uuid().min(1, "uidは必須です"),
});

// ユーザー更新用のリクエストパラメータのスキーマ定義
const updateUserRequestParamSchema = z.object({
  uid: z.uuid().min(1, "uidは必須です"),
});

// ユーザー更新用のリクエストボディスキーマ定義
const updateUserRequestBodySchema = z.object({
  lastName: z
    .string()
    .min(1, "lastNameは必須です")
    .max(10, "lastNameは10文字以内で入力してください"),
  firstName: z
    .string()
    .min(1, "firstNameは必須です")
    .max(10, "firstNameは10文字以内で入力してください"),
  totalPurchaseAmount: z
    .number()
    .min(0, "totalPurchaseAmountは0以上の数値で入力してください"),
});

// ユーザー削除用のリクエストパラメータのスキーマ定義
const deleteUserRequestParamSchema = z.object({
  uid: z.uuid().min(1, "uidは必須です"),
});

export const createUserRoutes = (
  createUserUseCase: CreateUserUseCase,
  findUsersUseCase: FindUsersUseCase,
  findUserUseCase: FindUserUseCase,
  updateUserUseCase: UpdateUserUseCase,
  deleteUserUseCase: DeleteUserUseCase,
) => {
  // Honoでルーティングを作る際は、メソッドチェーン推薦
  const routes = new Hono()
    .post("/", zValidator("json", createUserRequestBodySchema), (c) => {
      // バリデーション済みのリクエストパラメータを取得
      const { lastName, firstName, totalPurchaseAmount } = c.req.valid("json");

      // インプットパラメータ作成
      const input: CreateUserInput = {
        lastName,
        firstName,
        totalPurchaseAmount,
      };

      return createCreateUserHandler(createUserUseCase)(c, input);
    })
    .get("/", createFindUsersHandler(findUsersUseCase))
    .get("/:uid", zValidator("param", findUserRequestParamSchema), (c) => {
      // バリデーション済みのリクエストパラメータを取得
      const { uid } = c.req.valid("param");

      // インプットパラメータ作成
      const input: FindUserInput = { uid };

      return createFindUserHandler(findUserUseCase)(c, input);
    })
    .put(
      "/:uid",
      zValidator("param", updateUserRequestParamSchema),
      zValidator("json", updateUserRequestBodySchema),
      (c) => {
        // バリデーション済みのリクエストパラメータを取得
        const { uid } = c.req.valid("param");
        const { lastName, firstName, totalPurchaseAmount } =
          c.req.valid("json");

        // インプットパラメータ作成
        const input: UpdateUserInput = {
          uid,
          lastName,
          firstName,
          totalPurchaseAmount,
        };

        return createUpdateUserHandler(updateUserUseCase)(c, input);
      },
    )
    .delete("/:uid", zValidator("param", deleteUserRequestParamSchema), (c) => {
      // バリデーション済みのリクエストパラメータを取得
      const { uid } = c.req.valid("param");

      // インプットパラメータ作成
      const input: DeleteUserInput = { uid };

      return createDeleteUserHandler(deleteUserUseCase)(c, input);
    });

  return routes;
};

import { Hono } from "hono";
import { testClient } from "hono/testing";
import { beforeEach, describe, expect, it, vi } from "vitest";
import { createApp } from "../../../../app.js";
import type {
  CreateUserUseCase,
  DeleteUserUseCase,
  FindUsersUseCase,
  FindUserUseCase,
  UpdateUserUseCase,
} from "../../../../generic/user/useCase.js";
import type { NodeConfig } from "../../../../runtime/node/config.js";
import { config } from "../../../../runtime/node/config.js";
import { createUserRoutes } from "./routes.js";

// ログ出力の無効化
vi.spyOn(console, "log").mockImplementation(() => {});

// UseCaseのモック
type MockUseCase = {
  execute: ReturnType<typeof vi.fn>;
};
let createUserUseCase: MockUseCase;
let findUsersUseCase: MockUseCase;
let findUserUseCase: MockUseCase;
let updateUserUseCase: MockUseCase;
let deleteUserUseCase: MockUseCase;

// テスト用クライアント作成関数
const createTestClient = (config: NodeConfig) => {
  // ルーティング設定
  const v1 = new Hono().route(
    "/users",
    createUserRoutes(
      createUserUseCase as unknown as CreateUserUseCase,
      findUsersUseCase as unknown as FindUsersUseCase,
      findUserUseCase as unknown as FindUserUseCase,
      updateUserUseCase as unknown as UpdateUserUseCase,
      deleteUserUseCase as unknown as DeleteUserUseCase,
    ),
  );
  const routes = new Hono().route("/v1", v1);
  const app = createApp(config).route("/api", routes);

  return testClient(app);
};

// テスト用クライアント変数
let client: ReturnType<typeof createTestClient>;

// テスト用コンフィグ変数
let testConfig: NodeConfig;

// テストデータ用のUID
let uid: string;

// テスト前の共通セットアップ
beforeEach(() => {
  // モックの初期化
  createUserUseCase = {
    execute: vi.fn().mockResolvedValue({
      uid: "550e8400-e29b-41d4-a716-446655440000",
      lastName: "山田",
      firstName: "太郎",
      totalPurchaseAmount: 1000,
    }),
  };

  findUsersUseCase = {
    execute: vi.fn().mockResolvedValue([]),
  };

  findUserUseCase = {
    execute: vi.fn().mockResolvedValue({
      uid: "550e8400-e29b-41d4-a716-446655440000",
      lastName: "山田",
      firstName: "太郎",
      totalPurchaseAmount: 1000,
    }),
  };

  updateUserUseCase = {
    execute: vi.fn().mockResolvedValue({
      uid: "550e8400-e29b-41d4-a716-446655440000",
      lastName: "山田",
      firstName: "次郎",
      totalPurchaseAmount: 2000,
    }),
  };

  deleteUserUseCase = {
    execute: vi.fn().mockResolvedValue({
      uid: "550e8400-e29b-41d4-a716-446655440000",
    }),
  };

  testConfig = {
    ...config,
  };

  client = createTestClient(testConfig);

  uid = "550e8400-e29b-41d4-a716-446655440000";
});

describe("POST /api/v1/users", () => {
  it("正常終了すること", async () => {
    // テスト実行
    const response = await client.api.v1.users.$post({
      json: {
        lastName: "山田",
        firstName: "太郎",
        totalPurchaseAmount: 1000,
      },
    });

    // 検証
    expect(response.status).toBe(201);
    expect(createUserUseCase.execute).toHaveBeenCalledTimes(1);
    expect(createUserUseCase.execute).toHaveBeenCalledWith(expect.anything(), {
      lastName: "山田",
      firstName: "太郎",
      totalPurchaseAmount: 1000,
    });
  });

  it("lastNameが未指定の場合にバリデーションエラーになること", async () => {
    // テスト実行
    const response = await client.api.v1.users.$post({
      json: {
        firstName: "太郎",
        totalPurchaseAmount: 1000,
      } as never,
    });

    // 検証
    expect(response.status).toBe(400);
    expect(createUserUseCase.execute).not.toHaveBeenCalled();
  });

   it("firstNameが未指定の場合にバリデーションエラーになること", async () => {
    // テスト実行
    const response = await client.api.v1.users.$post({
      json: {
        lastName: "山田",
        totalPurchaseAmount: 1000,
      } as never,
    });

    // 検証
    expect(response.status).toBe(400);
    expect(createUserUseCase.execute).not.toHaveBeenCalled();
  });

  it("totalPurchaseAmountが未指定の場合にバリデーションエラーになること", async () => {
    // テスト実行
    const response = await client.api.v1.users.$post({
      json: {
        lastName: "山田",
        firstName: "太郎",
      } as never,
    });

    // 検証
    expect(response.status).toBe(400);
    expect(createUserUseCase.execute).not.toHaveBeenCalled();
  });

  it("lastNameが10文字以内の場合に正常終了すること", async () => {
    // テスト実行
    const response = await client.api.v1.users.$post({
      json: {
        lastName: "あいうえおかきくけこ",
        firstName: "太郎",
        totalPurchaseAmount: 1000,
      },
    });

    // 検証
    expect(response.status).toBe(201);
    expect(createUserUseCase.execute).toHaveBeenCalledTimes(1);
  });

  it("lastNameが10文字を超えている場合にバリデーションエラーになること", async () => {
    // テスト実行
    const response = await client.api.v1.users.$post({
      json: {
        lastName: "あいうえおかきくけこさ",
        firstName: "太郎",
        totalPurchaseAmount: 1000,
      },
    });

    // 検証
    expect(response.status).toBe(400);
    expect(createUserUseCase.execute).not.toHaveBeenCalled();
  });

  it("firstNameが10文字以内の場合に正常終了すること", async () => {
    // テスト実行
    const response = await client.api.v1.users.$post({
      json: {
        lastName: "山田",
        firstName: "あいうえおかきくけこ",
        totalPurchaseAmount: 1000,
      },
    });

    // 検証
    expect(response.status).toBe(201);
    expect(createUserUseCase.execute).toHaveBeenCalledTimes(1);
  });

  it("firstNameが10文字を超えている場合にバリデーションエラーになること", async () => {
    // テスト実行
    const response = await client.api.v1.users.$post({
      json: {
        lastName: "山田",
        firstName: "あいうえおかきくけこさ",
        totalPurchaseAmount: 1000,
      },
    });

    // 検証
    expect(response.status).toBe(400);
    expect(createUserUseCase.execute).not.toHaveBeenCalled();
  });

  it("totalPurchaseAmountが0の場合に正常終了すること", async () => {
    // テスト実行
    const response = await client.api.v1.users.$post({
      json: {
        lastName: "山田",
        firstName: "太郎",
        totalPurchaseAmount: 0,
      },
    });

    // 検証
    expect(response.status).toBe(201);
    expect(createUserUseCase.execute).toHaveBeenCalledTimes(1);
  });

  it("totalPurchaseAmountがマイナスの場合にバリデーションエラーになること", async () => {
    // テスト実行
    const response = await client.api.v1.users.$post({
      json: {
        lastName: "山田",
        firstName: "太郎",
        totalPurchaseAmount: -1,
      },
    });

    // 検証
    expect(response.status).toBe(400);
    expect(createUserUseCase.execute).not.toHaveBeenCalled();
  });

  it("totalPurchaseAmountが文字列の場合にバリデーションエラーになること", async () => {
    // テスト実行
    const response = await client.api.v1.users.$post({
      json: {
        lastName: "山田",
        firstName: "太郎",
        totalPurchaseAmount: "1000",
      } as never,
    });

    // 検証
    expect(response.status).toBe(400);
    expect(createUserUseCase.execute).not.toHaveBeenCalled();
  });
});

describe("GET /api/v1/users", () => {
  it("正常終了すること", async () => {
    // テスト実行
    const response = await client.api.v1.users.$get();

    // 検証
    expect(response.status).toBe(200);
    expect(findUsersUseCase.execute).toHaveBeenCalledTimes(1);
  });
});

describe("GET /api/v1/users/:uid", () => {
  it("正常終了すること", async () => {
    // テスト実行
    const response = await client.api.v1.users[":uid"].$get({
      param: {
        uid: uid,
      },
    });

    // 検証
    expect(response.status).toBe(200);
    expect(findUserUseCase.execute).toHaveBeenCalledTimes(1);
    expect(findUserUseCase.execute).toHaveBeenCalledWith(expect.anything(), {
      uid,
    });
  });

  it("uidがUUID形式ではない場合にバリデーションエラーになること", async () => {
    // テスト実行
    const response = await client.api.v1.users[":uid"].$get({
      param: {
        uid: "invalid-uid",
      },
    });

    // 検証
    expect(response.status).toBe(400);
    expect(findUserUseCase.execute).not.toHaveBeenCalled();
  });
});

describe("PUT /api/v1/users/:uid", () => {
  it("正常終了すること", async () => {
    // テスト実行
    const response = await client.api.v1.users[":uid"].$put({
      param: {
        uid: uid,
      },
      json: {
        lastName: "山田",
        firstName: "次郎",
        totalPurchaseAmount: 2000,
      },
    });

    // 検証
    expect(response.status).toBe(200);
    expect(updateUserUseCase.execute).toHaveBeenCalledTimes(1);
    expect(updateUserUseCase.execute).toHaveBeenCalledWith(expect.anything(), {
      uid,
      lastName: "山田",
      firstName: "次郎",
      totalPurchaseAmount: 2000,
    });
  });

  it("uidがUUID形式ではない場合にバリデーションエラーになること", async () => {
    // テスト実行
    const response = await client.api.v1.users[":uid"].$put({
      param: {
        uid: "invalid-uid",
      },
      json: {
        lastName: "山田",
        firstName: "次郎",
        totalPurchaseAmount: 2000,
      },
    });

    // 検証
    expect(response.status).toBe(400);
    expect(updateUserUseCase.execute).not.toHaveBeenCalled();
  });

  it("lastNameが未指定の場合にバリデーションエラーになること", async () => {
    // テスト実行
    const response = await client.api.v1.users[":uid"].$put({
      param: {
        uid: uid,
      },
      json: {
        firstName: "次郎",
        totalPurchaseAmount: 2000,
      } as never,
    });

    // 検証
    expect(response.status).toBe(400);
    expect(updateUserUseCase.execute).not.toHaveBeenCalled();
  });

  it("firstNameが未指定の場合にバリデーションエラーになること", async () => {
    // テスト実行
    const response = await client.api.v1.users[":uid"].$put({
      param: {
        uid: uid,
      },
      json: {
        lastName: "山田",
        totalPurchaseAmount: 2000,
      } as never,
    });

    // 検証
    expect(response.status).toBe(400);
    expect(updateUserUseCase.execute).not.toHaveBeenCalled();
  });

  it("totalPurchaseAmountが未指定の場合にバリデーションエラーになること", async () => {
    // テスト実行
    const response = await client.api.v1.users[":uid"].$put({
      param: {
        uid: uid,
      },
      json: {
        lastName: "山田",
        firstName: "次郎",
      } as never,
    });

    // 検証
    expect(response.status).toBe(400);
    expect(updateUserUseCase.execute).not.toHaveBeenCalled();
  });

  it("lastNameが10文字以内の場合に正常終了すること", async () => {
    // テスト実行
    const response = await client.api.v1.users[":uid"].$put({
      param: {
        uid: uid,
      },
      json: {
        lastName: "あいうえおかきくけこ",
        firstName: "次郎",
        totalPurchaseAmount: 1000,
      },
    });

    // 検証
    expect(response.status).toBe(200);
    expect(updateUserUseCase.execute).toHaveBeenCalledTimes(1);
  });

  it("lastNameが10文字を超えている場合にバリデーションエラーになること", async () => {
    // テスト実行
    const response = await client.api.v1.users[":uid"].$put({
      param: {
        uid: uid,
      },
      json: {
        lastName: "あいうえおかきくけこさ",
        firstName: "次郎",
        totalPurchaseAmount: 1000,
      },
    });

    // 検証
    expect(response.status).toBe(400);
    expect(updateUserUseCase.execute).not.toHaveBeenCalled();
  });

  it("firstNameが10文字以内の場合に正常終了すること", async () => {
    // テスト実行
    const response = await client.api.v1.users[":uid"].$put({
      param: {
        uid: uid,
      },
      json: {
        lastName: "山田",
        firstName: "あいうえおかきくけこ",
        totalPurchaseAmount: 1000,
      },
    });

    // 検証
    expect(response.status).toBe(200);
    expect(updateUserUseCase.execute).toHaveBeenCalledTimes(1);
  });

  it("firstNameが10文字を超えている場合にバリデーションエラーになること", async () => {
    // テスト実行
    const response = await client.api.v1.users[":uid"].$put({
      param: {
        uid: uid,
      },
      json: {
        lastName: "山田",
        firstName: "あいうえおかきくけこさ",
        totalPurchaseAmount: 1000,
      },
    });

    // 検証
    expect(response.status).toBe(400);
    expect(updateUserUseCase.execute).not.toHaveBeenCalled();
  });

  it("totalPurchaseAmountが0の場合に正常終了すること", async () => {
    // テスト実行
    const response = await client.api.v1.users[":uid"].$put({
      param: {
        uid: uid,
      },
      json: {
        lastName: "山田",
        firstName: "太郎",
        totalPurchaseAmount: 0,
      },
    });

    // 検証
    expect(response.status).toBe(200);
    expect(updateUserUseCase.execute).toHaveBeenCalledTimes(1);
  });

  it("totalPurchaseAmountがマイナスの場合にバリデーションエラーになること", async () => {
    // テスト実行
    const response = await client.api.v1.users[":uid"].$put({
      param: {
        uid: uid,
      },
      json: {
        lastName: "山田",
        firstName: "太郎",
        totalPurchaseAmount: -1,
      },
    });

    // 検証
    expect(response.status).toBe(400);
    expect(updateUserUseCase.execute).not.toHaveBeenCalled();
  });
});

describe("DELETE /api/v1/users/:uid", () => {
  it("正常終了すること", async () => {
    // テスト実行
    const response = await client.api.v1.users[":uid"].$delete({
      param: {
        uid: uid,
      },
    });

    // 検証
    expect(response.status).toBe(204);
    expect(deleteUserUseCase.execute).toHaveBeenCalledTimes(1);
    expect(deleteUserUseCase.execute).toHaveBeenCalledWith(expect.anything(), {
      uid,
    });
  });

  it("uidがUUID形式ではない場合にバリデーションエラーになること", async () => {
    // テスト実行
    const response = await client.api.v1.users[":uid"].$delete({
      param: {
        uid: "invalid-uid",
      },
    });

    // 検証
    expect(response.status).toBe(400);
    expect(deleteUserUseCase.execute).not.toHaveBeenCalled();
  });
});

import { eq } from "drizzle-orm";
import { testClient } from "hono/testing";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import type { DbPg } from "../../../../infrastructure/database/drizzle/pg/client.js";
import { createDbPg } from "../../../../infrastructure/database/drizzle/pg/client.js";
import { users } from "../../../../infrastructure/database/drizzle/pg/schema/users.js";
import { createNodeApp } from "../../../../runtime/node/app.js";
import type { NodeConfig } from "../../../../runtime/node/config.js";
import { config } from "../../../../runtime/node/config.js";

// ログ出力の無効化
vi.spyOn(console, "log").mockImplementation(() => {});

// テスト用クライアント作成関数
const createTestClient = (config: NodeConfig) => {
  return testClient(createNodeApp(config));
};

// テスト用クライアント変数
let client: ReturnType<typeof createTestClient>;

let testDbPg: DbPg;

// テスト用コンフィグ変数
let testConfig: NodeConfig;

// テスト前の共通セットアップ
beforeEach(() => {
  testConfig = {
    ...config,
    db: {
      ...config.db,
      name: "testing-db-pg",
    },
  };

  client = createTestClient(testConfig);
  testDbPg = createDbPg(testConfig.db);
});

// テスト後の共通クリーンアップ
afterEach(async () => {
  await testDbPg.db.delete(users);
  await testDbPg.pool.end();
});

describe("POST /api/v1/users", () => {
  it("ユーザーが新規作成され、正常終了すること", async () => {
    // テスト実行
    const response = await client.api.v1.users.$post({
      json: {
        lastName: "山田",
        firstName: "太郎",
        totalPurchaseAmount: 1000,
      },
    });

    // 検証
    expect(response.status).toBe(201);

    // レスポンス結果の検証
    type CreateUserResponse = {
      id: number;
      uid: string;
      lastName: string;
      firstName: string;
      totalPurchaseAmount: number;
      createdAt: string;
      updatedAt: string;
    };
    const body = (await response.json()) as CreateUserResponse;
    expect(body).toEqual({
      id: expect.any(Number),
      uid: expect.any(String),
      lastName: "山田",
      firstName: "太郎",
      totalPurchaseAmount: 1000,
      createdAt: expect.any(String),
      updatedAt: expect.any(String),
    });

    // DBに保存されていることを検証
    const [user] = await testDbPg.db
      .select()
      .from(users)
      .where(eq(users.uid, body.uid))
      .limit(1);

    expect(user).toEqual({
      id: body.id,
      uid: body.uid,
      lastName: body.lastName,
      firstName: body.firstName,
      totalPurchaseAmount: body.totalPurchaseAmount,
      createdAt: new Date(body.createdAt),
      updatedAt: new Date(body.updatedAt),
    });
  });
});

describe("GET /api/v1/users", () => {
  it("全てのユーザーを取得し、正常終了すること", async () => {
    // テストデータ登録
    const resultUsers = await testDbPg.db
      .insert(users)
      .values([
        {
          lastName: "山田",
          firstName: "太郎",
          totalPurchaseAmount: 1000,
        },
        {
          lastName: "佐藤",
          firstName: "花子",
          totalPurchaseAmount: 2000,
        },
      ])
      .returning();
    const expectedUsers = resultUsers.map((user) => ({
      ...user,
      createdAt: user.createdAt.toISOString(),
      updatedAt: user.updatedAt.toISOString(),
    }));

    // テスト実行
    const response = await client.api.v1.users.$get();

    // 検証
    expect(response.status).toBe(200);

    // レスポンス結果の検証
    const body = await response.json();
    expect(body).toHaveLength(2);
    expect(body).toEqual(expectedUsers);
  });
});

describe("GET /api/v1/users/:uid", () => {
  it("対象ユーザーを取得し、正常終了すること", async () => {
    // テストデータ登録
    const [resultUser] = await testDbPg.db
      .insert(users)
      .values({
        lastName: "山田",
        firstName: "太郎",
        totalPurchaseAmount: 1000,
    })
    .returning();
    const expectedUser = {
      ...resultUser,
      createdAt: resultUser.createdAt.toISOString(),
      updatedAt: resultUser.updatedAt.toISOString(),
    };

    // テスト実行
    const response = await client.api.v1.users.$get();

    // 検証
    expect(response.status).toBe(200);

    // レスポンス結果の検証
    const [body] = await response.json();
    expect(body).toEqual(expectedUser);
  });
});

describe("PUT /api/v1/users/:uid", () => {
  it("対象ユーザーを更新し、正常終了すること", async () => {
    // テストデータ登録
    const [resultUser] = await testDbPg.db
      .insert(users)
      .values({
        lastName: "山田",
        firstName: "太郎",
        totalPurchaseAmount: 1000,
      })
      .returning();
    const expectedUser = {
      ...resultUser,
      lastName: "佐藤",
      firstName: "二郎",
      totalPurchaseAmount: 2000,
      createdAt: resultUser.createdAt.toISOString(),
      updatedAt: expect.any(String),
    };

    // テスト実行
    const response = await client.api.v1.users[":uid"].$put({
      param: {
        uid: expectedUser.uid,
      },
      json: {
        lastName: expectedUser.lastName,
        firstName: expectedUser.firstName,
        totalPurchaseAmount: expectedUser.totalPurchaseAmount,
      },
    });

    // 検証
    expect(response.status).toBe(200);

    // レスポンス結果の検証
    const body = await response.json();
    expect(body).toEqual(expectedUser);
    if ("createdAt" in body) {
      expect(body.createdAt).toBe(expectedUser.createdAt);
    }
    if ("updatedAt" in body) {
      expect(body.updatedAt).not.toBe(expectedUser.createdAt);
    }
  });
});

describe("DELETE /api/v1/users/:uid", () => {
  it("対象ユーザーを削除し、正常終了すること", async () => {
    // テストデータ登録
    const [resultUser] = await testDbPg.db
      .insert(users)
      .values({
        lastName: "山田",
        firstName: "太郎",
        totalPurchaseAmount: 1000,
      })
      .returning();

    // テスト実行
    const response = await client.api.v1.users[":uid"].$delete({
      param: {
        uid: resultUser.uid,
      },
    });

    // 検証
    expect(response.status).toBe(204);

    // DBから削除されていることを確認
    const deletedUsers = await testDbPg.db
      .select()
      .from(users)
      .where(eq(users.uid, resultUser.uid));

    expect(deletedUsers).toHaveLength(0);
  });
});

import {
  CreateUserUseCase,
  DeleteUserUseCase,
  FindUsersUseCase,
  FindUserUseCase,
  UpdateUserUseCase,
} from "../generic/user/useCase.js";
import { createDbPg } from "../infrastructure/database/drizzle/pg/client.js";
import type { NodeConfig } from "../runtime/node/config.js";
import {
  SampleHelloUseCase,
  SampleTextUseCase,
} from "../supporting/sample/useCase.js";

export const createNodeContainer = (config: NodeConfig) => {
  // DBインスタンスの初期化
  const dbPg = createDbPg(config.db);

  // サンプル関連のユースケースを初期化
  const sampleHelloUseCase = new SampleHelloUseCase();
  const sampleTextUseCase = new SampleTextUseCase();

  // ユーザー関連のユースケースを初期化
  const createUserUseCase = new CreateUserUseCase(dbPg.db);
  const findUsersUseCase = new FindUsersUseCase(dbPg.db);
  const findUserUseCase = new FindUserUseCase(dbPg.db);
  const updateUserUseCase = new UpdateUserUseCase(dbPg.db);
  const deleteUserUseCase = new DeleteUserUseCase(dbPg.db);

  return {
    sampleHelloUseCase,
    sampleTextUseCase,
    createUserUseCase,
    findUsersUseCase,
    findUserUseCase,
    updateUserUseCase,
    deleteUserUseCase,
  };
};

export type NodeContainer = ReturnType<typeof createNodeContainer>;

import { Hono } from "hono";
import type { NodeContainer } from "../../di/nodeContainer.js";
import { createUserRoutes } from "../http/generic/user/routes.js";
import { createSampleRoutes } from "../http/supporting/sample/routes.js";

export const createRoutesNode = (container: NodeContainer) => {
  /******************************
  * v1用のルーティング
  ******************************/
  // Honoでルーティングを作る際は、メソッドチェーン推薦
  const v1 = new Hono()
    .route(
      "/sample",
      createSampleRoutes(
        container.sampleHelloUseCase,
        container.sampleTextUseCase,
      ),
    )
    .route(
      "/users",
      createUserRoutes(
        container.createUserUseCase,
        container.findUsersUseCase,
        container.findUserUseCase,
        container.updateUserUseCase,
        container.deleteUserUseCase,
      ),
    );
  /******************************
  * ルーティング設定
  ******************************/
  return new Hono().route("/v1", v1);
};

$ pnpm run format
$ pnpm run lint
$ pnpm run test

$ mkdir -p src/core/member/domain
$ touch src/core/member/domain/memberUid.ts src/core/member/domain/memberUid.test.ts
$ touch src/core/member/domain/member.ts src/core/member/domain/member.test.ts
$ touch src/core/member/domain/memberRankService.ts src/core/member/domain/memberRankService.test.ts
$ touch src/core/member/domain/memberRepository.ts
$ mkdir -p src/core/member/infrastructure/persistence/pg/query
$ touch src/core/member/infrastructure/persistence/pg/query/drizzleMemberRepository.ts

export class MemberUid {
  constructor(readonly value: string) {
    if (!MemberUid.isValid(value)) {
      throw new Error(`Invalid MemberUid: ${value}`);
    }
  }

  // uuid形式チェック
  private static isValid(value: string): boolean {
    return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(
      value,
    );
  }
}

import { describe, expect, it } from "vitest";
import { MemberUid } from "./memberUid.js";

describe("MemberUid", () => {
  it("有効なUUIDをMemberUidとして生成できる", () => {
    const value = "550e8400-e29b-41d4-a716-446655440000";

    const memberUid = new MemberUid(value);

    expect(memberUid.value).toBe(value);
  });

  it("不正なUUIDの場合はエラーになる", () => {
    expect(() => {
      new MemberUid("invalid-uuid");
    }).toThrow("Invalid MemberUid: invalid-uuid");
  });

  it("空文字の場合はエラーになる", () => {
    expect(() => {
      new MemberUid("");
    }).toThrow("Invalid MemberUid: ");
  });
});

import type { MemberUid } from "./memberUid.js";

export class Member {
  constructor(
    readonly uid: MemberUid,
    readonly lastName: string,
    readonly firstName: string,
    readonly totalPurchaseAmount: number,
  ) {}

  // フルネームを出力するメソッド
  get fullName(): string {
    return `${this.lastName} ${this.firstName}`;
  }
}

import { describe, expect, it } from "vitest";
import { Member } from "./member.js";
import { MemberUid } from "./memberUid.js";

describe("Member", () => {
  it("メンバー情報を保持する", () => {
    const uid = new MemberUid("550e8400-e29b-41d4-a716-446655440000");

    const member = new Member(uid, "山田", "太郎", 10000);

    expect(member.uid).toBe(uid);
    expect(member.lastName).toBe("山田");
    expect(member.firstName).toBe("太郎");
    expect(member.totalPurchaseAmount).toBe(10000);
  });

  it("fullNameに姓と名を結合した名前を返す", () => {
    const member = new Member(
      new MemberUid("550e8400-e29b-41d4-a716-446655440000"),
      "山田",
      "太郎",
      10000,
    );

    expect(member.fullName).toBe("山田 太郎");
  });
});

import type { Member } from "./member.js";

export type MemberRank = "bronze" | "silver" | "gold" | "platinum";

export class MemberRankService {
  calculate(member: Member): MemberRank {
    // 100万円以上でプラチナ
    if (member.totalPurchaseAmount >= 1_000_000) {
      return "platinum";
    }

    // 10万円以上でゴールド
    if (member.totalPurchaseAmount >= 100_000) {
      return "gold";
    }

    // 1万円以上でシルバー
    if (member.totalPurchaseAmount >= 10_000) {
      return "silver";
    }

    return "bronze";
  }
}

import { describe, expect, it } from "vitest";
import { Member } from "./member.js";
import { MemberRankService } from "./memberRankService.js";
import { MemberUid } from "./memberUid.js";

describe("MemberRankService", () => {
  const service = new MemberRankService();

  const createMember = (totalPurchaseAmount: number) => {
    return new Member(
      new MemberUid("550e8400-e29b-41d4-a716-446655440000"),
      "山田",
      "太郎",
      totalPurchaseAmount,
    );
  };

  it("合計購入金額が10,000円未満ならbronze", () => {
    const member = createMember(9_999);

    expect(service.calculate(member)).toBe("bronze");
  });

  it("合計購入金額が10,000円以上ならsilver", () => {
    const member = createMember(10_000);

    expect(service.calculate(member)).toBe("silver");
  });

  it("合計購入金額が100,000円以上ならgold", () => {
    const member = createMember(100_000);

    expect(service.calculate(member)).toBe("gold");
  });

  it("合計購入金額が1,000,000円以上ならplatinum", () => {
    const member = createMember(1_000_000);

    expect(service.calculate(member)).toBe("platinum");
  });
});

import type { Member } from "./member.js";
import type { MemberUid } from "./memberUid.js";

export interface MemberRepository {
  findByUid(uid: MemberUid): Promise<Member | null>;
}

import { eq } from "drizzle-orm";
import type { PgDbClient } from "../../../../../../infrastructure/database/drizzle/pg/client.js";
import { users } from "../../../../../../infrastructure/database/drizzle/pg/schema/users.js";
import { Member } from "../../../../domain/member.js";
import type { MemberRepository } from "../../../../domain/memberRepository.js";
import { MemberUid } from "../../../../domain/memberUid.js";

export class DrizzleMemberRepository implements MemberRepository {
  constructor(private readonly db: PgDbClient) {}

  async findByUid(uid: MemberUid): Promise<Member | null> {
    // 対象ユーザー取得
    const [user] = await this.db
      .select()
      .from(users)
      .where(eq(users.uid, uid.value))
      .limit(1);

    // ユーザー取得チェック
    if (!user) {
      return null;
    }

    return new Member(
      new MemberUid(user.uid),
      user.lastName,
      user.firstName,
      user.totalPurchaseAmount,
    );
  }
}

$ touch src/infrastructure/database/database.ts
$ mkdir -p src/infrastructure/repository
$ touch src/infrastructure/repository/drizzleRepositoryFactory.ts

import type { PgDbClient } from "./drizzle/pg/client.js";

export class Database {
  constructor(private readonly db: PgDbClient) {}

  getClient(): PgDbClient {
    return this.db;
  }
}

import { DrizzleMemberRepository } from "../../core/member/infrastructure/persistence/pg/query/drizzleMemberRepository.js";
import type { PgDbClient } from "../database/drizzle/pg/client.js";

export class DrizzleRepositoryFactory {
  create(db: PgDbClient) {
    return {
      member: new DrizzleMemberRepository(db),
    };
  }
}

$ mkdir -p src/core/member/usecase
$ touch src/core/member/usecase/calculateMemberRank.ts src/core/member/usecase/calculateMemberRank.test.ts
$ touch src/core/member/usecase/errors.ts

import type { Database } from "../../../infrastructure/database/database.js";
import type { DrizzleRepositoryFactory } from "../../../infrastructure/repository/drizzleRepositoryFactory.js";
import type { Logger } from "../../../shared/logger/logger.js";
import { MemberRankService } from "../domain/memberRankService.js";
import { MemberUid } from "../domain/memberUid.js";
import { MemberNotFoundError } from "./errors.js";

export type CalculateMemberRankUseCaseInput = {
  uid: string;
};

export class CalculateMemberRankUseCase {
  constructor(
    private readonly db: Database,
    private readonly repositoryFactory: DrizzleRepositoryFactory,
  ) {}

  async execute(_logger: Logger, input: CalculateMemberRankUseCaseInput) {
    // リポジトリのインスタンス化
    const repo = this.repositoryFactory.create(this.db.getClient());

    // uidからメンバーを取得
    const member = await repo.member.findByUid(new MemberUid(input.uid));

    // 必須チェック
    if (!member) {
      throw new MemberNotFoundError();
    }

    // メンバーのランク取得
    const rank = new MemberRankService().calculate(member);

    return {
      rank,
    };
  }
}

import { beforeEach, describe, expect, it, vi } from "vitest";
import type { Database } from "../../../infrastructure/database/database.js";
import type { PgDbClient } from "../../../infrastructure/database/drizzle/pg/client.js";
import type { DrizzleRepositoryFactory } from "../../../infrastructure/repository/drizzleRepositoryFactory.js";
import type { Logger } from "../../../shared/logger/logger.js";
import { Member } from "../domain/member.js";
import { MemberUid } from "../domain/memberUid.js";
import { CalculateMemberRankUseCase } from "./calculateMemberRank.js";
import { MemberNotFoundError } from "./errors.js";

// ロガーのモック化
const createMockLogger = (): Logger => ({
  info: vi.fn(),
  warn: vi.fn(),
  error: vi.fn(),
  debug: vi.fn(),
  withRequestId: vi.fn(),
});

// DBのモック化
const createMockDb = <T extends object>(mock: T): PgDbClient =>
  mock as unknown as PgDbClient;

  let logger: Logger;

  beforeEach(() => {
    logger = createMockLogger();
  });

  describe("CalculateMemberRankUseCase", () => {
    it("メンバーのランクを取得できること", async () => {
      // メンバーのモック
      const uid = "550e8400-e29b-41d4-a716-446655440000";

      const member = new Member(new MemberUid(uid), "山田", "太郎", 100_000);

      // Repositoryのモック化
      const findByUid = vi.fn().mockResolvedValue(member);

      const repository = {
        member: {
          findByUid,
        },
      };

      // DBのモック化
      const dbClient = createMockDb({});

      const getClient = vi.fn().mockReturnValue(dbClient);

      const db = {
        getClient,
      } as unknown as Database;

      // RepositoryFactoryのモック化
      const create = vi.fn().mockReturnValue(repository);

      const repositoryFactory = {
        create,
      } as unknown as DrizzleRepositoryFactory;

      // ユースケース作成
      const useCase = new CalculateMemberRankUseCase(db, repositoryFactory);

      // ユースケース実行
      const result = await useCase.execute(logger, {
        uid,
      });

      // 検証
      expect(result).toEqual({
        rank: "gold",
      });
      expect(findByUid).toHaveBeenCalledOnce();
  });

  it("メンバーが存在しない場合はエラーになること", async () => {
    // Repositoryのモック化
    const findByUid = vi.fn().mockResolvedValue(null);

    const repository = {
      member: {
        findByUid,
      },
    };

    // DBのモック化
    const dbClient = createMockDb({});

    const getClient = vi.fn().mockReturnValue(dbClient);

    const db = {
      getClient,
    } as unknown as Database;

    // RepositoryFactoryのモック化
    const create = vi.fn().mockReturnValue(repository);

    const repositoryFactory = {
      create,
    } as unknown as DrizzleRepositoryFactory;

    // ユースケース作成
    const useCase = new CalculateMemberRankUseCase(db, repositoryFactory);

    // ユースケース実行・検証
    await expect(
      useCase.execute(logger, {
        uid: "550e8400-e29b-41d4-a716-446655440000",
      }),
    ).rejects.toBeInstanceOf(MemberNotFoundError);
  });
});

import type { ContentfulStatusCode } from "hono/utils/http-status";
import { AppError } from "../../../shared/error/appError.js";

// エラーコード（カスタムエラー用）
// 「|」で区切って追加可能
export type MemberErrorCode = "MEMBER_NOT_FOUND";

// エラーコードとHTTPステータスコードのマッピング
export const memberErrorStatusMap: Record<
  MemberErrorCode,
  ContentfulStatusCode
> = {
  MEMBER_NOT_FOUND: 404,
};

export class MemberNotFoundError extends AppError<MemberErrorCode> {
  constructor() {
    super("Member not found", "MEMBER_NOT_FOUND", "warn");
  }
}

import { CalculateMemberRankUseCase } from "../core/member/usecase/calculateMemberRank.js";
import {
  CreateUserUseCase,
  DeleteUserUseCase,
  FindUsersUseCase,
  FindUserUseCase,
  UpdateUserUseCase,
} from "../generic/user/useCase.js";
import { Database } from "../infrastructure/database/database.js";
import { createDbPg } from "../infrastructure/database/drizzle/pg/client.js";
import { DrizzleRepositoryFactory } from "../infrastructure/repository/drizzleRepositoryFactory.js";
import type { NodeConfig } from "../runtime/node/config.js";
import {
  SampleHelloUseCase,
  SampleTextUseCase,
} from "../supporting/sample/useCase.js";

export const createNodeContainer = (config: NodeConfig) => {
  // DBインスタンスの初期化
  const dbPg = createDbPg(config.db);

  // サンプル関連のユースケースを初期化
  const sampleHelloUseCase = new SampleHelloUseCase();
  const sampleTextUseCase = new SampleTextUseCase();

  // ユーザー関連のユースケースを初期化
  const createUserUseCase = new CreateUserUseCase(dbPg.db);
  const findUsersUseCase = new FindUsersUseCase(dbPg.db);
  const findUserUseCase = new FindUserUseCase(dbPg.db);
  const updateUserUseCase = new UpdateUserUseCase(dbPg.db);
  const deleteUserUseCase = new DeleteUserUseCase(dbPg.db);

  // メンバードメイン関連のユースケースを初期化
  const database = new Database(dbPg.db);
  const drizzleRepositoryFactory = new DrizzleRepositoryFactory();
  const calculateMemberRankUseCase = new CalculateMemberRankUseCase(
    database,
    drizzleRepositoryFactory,
  );

  return {
    sampleHelloUseCase,
    sampleTextUseCase,
    createUserUseCase,
    findUsersUseCase,
    findUserUseCase,
    updateUserUseCase,
    deleteUserUseCase,
    calculateMemberRankUseCase,
  };
};

export type NodeContainer = ReturnType<typeof createNodeContainer>;

$ mkdir -p src/presentation/http/core/member
$ touch src/presentation/http/core/member/handler.ts
$ touch src/presentation/http/core/member/routes.ts src/presentation/http/core/member/routes.test.ts

import type { Context } from "hono";
import type {
  CalculateMemberRankUseCase,
  CalculateMemberRankUseCaseInput,
} from "../../../../core/member/usecase/calculateMemberRank.js";

export const createCalculateMemberRankHandler =
  (useCase: CalculateMemberRankUseCase) =>
  async (c: Context, input: CalculateMemberRankUseCaseInput) => {
    // 共通ロガー取得
    const logger = c.get("logger");

    // ユースケース実行
    const result = await useCase.execute(logger, input);

    return c.json(result);
  };

import { zValidator } from "@hono/zod-validator";
import { Hono } from "hono";
import { z } from "zod";
import type {
  CalculateMemberRankUseCase,
  CalculateMemberRankUseCaseInput,
} from "../../../../core/member/usecase/calculateMemberRank.js";
import { createCalculateMemberRankHandler } from "./handler.js";

// リクエストパラメータのスキーマ定義
const calculateMemberRankRequestParamSchema = z.object({
  uid: z.uuid().min(1, "uidは必須です"),
});

export const createMemberRoutes = (
  calculateMemberRankUseCase: CalculateMemberRankUseCase,
) => {
  const routes = new Hono().get(
    "/:uid/rank",
    zValidator("param", calculateMemberRankRequestParamSchema),
    (c) => {
      // バリデーション済みのリクエストパラメータを取得
      const { uid } = c.req.valid("param");

      // インプットパラメータ作成
      const input: CalculateMemberRankUseCaseInput = { uid };

      return createCalculateMemberRankHandler(calculateMemberRankUseCase)(
        c,
        input,
      );
    },
  );

  return routes;
};

import { Hono } from "hono";
import { testClient } from "hono/testing";
import { beforeEach, describe, expect, it, vi } from "vitest";
import { createApp } from "../../../../app.js";
import type { CalculateMemberRankUseCase } from "../../../../core/member/usecase/calculateMemberRank.js";
import type { NodeConfig } from "../../../../runtime/node/config.js";
import { config } from "../../../../runtime/node/config.js";
import { createMemberRoutes } from "./routes.js";

// ログ出力の無効化
vi.spyOn(console, "log").mockImplementation(() => {});

// UseCaseのモック
type MockUseCase = {
  execute: ReturnType<typeof vi.fn>;
};
let calculateMemberRankUseCase: MockUseCase;

// テスト用クライアント作成関数
const createTestClient = (config: NodeConfig) => {
  // ルーティング設定
  const v1 = new Hono().route(
    "/members",
    createMemberRoutes(
      calculateMemberRankUseCase as unknown as CalculateMemberRankUseCase,
    ),
  );
  const routes = new Hono().route("/v1", v1);
  const app = createApp(config).route("/api", routes);

  return testClient(app);
};

// テスト用クライアント変数
let client: ReturnType<typeof createTestClient>;

// テスト用コンフィグ変数
let testConfig: NodeConfig;

// テストデータ用のUID
let uid: string;

// テスト前の共通セットアップ
beforeEach(() => {
  // モックの初期化
  calculateMemberRankUseCase = {
    execute: vi.fn().mockResolvedValue({
      rank: "gold",
    }),
  };

  testConfig = {
    ...config,
  };

  client = createTestClient(testConfig);

  uid = "550e8400-e29b-41d4-a716-446655440000";
});

describe("GET /api/v1/members/:uid/rank", () => {
  it("正常終了すること", async () => {
    // テスト実行
    const response = await client.api.v1.members[":uid"].rank.$get({
      param: {
        uid: uid,
      },
    });

    // 検証
    expect(response.status).toBe(200);
    expect(calculateMemberRankUseCase.execute).toHaveBeenCalledTimes(1);
    expect(calculateMemberRankUseCase.execute).toHaveBeenCalledWith(
      expect.anything(),
      {
        uid,
      },
    );
  });

  it("uidがUUID形式ではない場合にバリデーションエラーになること", async () => {
    // テスト実行
    const response = await client.api.v1.members[":uid"].rank.$get({
      param: {
        uid: "invalid-uid",
      },
    });

    // 検証
    expect(response.status).toBe(400);
    expect(calculateMemberRankUseCase.execute).not.toHaveBeenCalled();
  });
});

import { Hono } from "hono";
import type { NodeContainer } from "../../di/nodeContainer.js";
import { createUserRoutes } from "../http/generic/user/routes.js";
import { createSampleRoutes } from "../http/supporting/sample/routes.js";
import { createMemberRoutes } from "./core/member/routes.js";

export const createRoutesNode = (container: NodeContainer) => {
  /******************************
  * v1用のルーティング
  ******************************/
  // Honoでルーティングを作る際は、メソッドチェーン推薦
  const v1 = new Hono()
    .route(
      "/sample",
      createSampleRoutes(
        container.sampleHelloUseCase,
        container.sampleTextUseCase,
      ),
    )
    .route(
      "/users",
      createUserRoutes(
        container.createUserUseCase,
        container.findUsersUseCase,
        container.findUserUseCase,
        container.updateUserUseCase,
        container.deleteUserUseCase,
      ),
    )
    .route(
      "/members",
      createMemberRoutes(container.calculateMemberRankUseCase),
    );

    /******************************
    * ルーティング設定
    ******************************/
    return new Hono().route("/v1", v1);
};

import type { ContentfulStatusCode } from "hono/utils/http-status";
import { memberErrorStatusMap } from "../../../core/member/usecase/errors.js";
import { userErrorStatusMap } from "../../../generic/user/errors.js";

// 共通エラーコードとHTTPステータスコードのマッピング
export const errorStatusMap: Record<string, ContentfulStatusCode> = {
  ...userErrorStatusMap,
  ...memberErrorStatusMap,
};

$ mkdir -p src/tests/integration/core/member
$ touch src/tests/integration/core/member/member.test.ts

import { testClient } from "hono/testing";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import type { DbPg } from "../../../../infrastructure/database/drizzle/pg/client.js";
import { createDbPg } from "../../../../infrastructure/database/drizzle/pg/client.js";
import { users } from "../../../../infrastructure/database/drizzle/pg/schema/users.js";
import { createNodeApp } from "../../../../runtime/node/app.js";
import type { NodeConfig } from "../../../../runtime/node/config.js";
import { config } from "../../../../runtime/node/config.js";

// ログ出力の無効化
vi.spyOn(console, "log").mockImplementation(() => {});

// テスト用クライアント作成関数
const createTestClient = (config: NodeConfig) => {
  return testClient(createNodeApp(config));
};

// テスト用クライアント変数
let client: ReturnType<typeof createTestClient>;

let testDbPg: DbPg;

// テスト用コンフィグ変数
let testConfig: NodeConfig;

// テスト前の共通セットアップ
beforeEach(() => {
  testConfig = {
    ...config,
    db: {
      ...config.db,
      name: "testing-db-pg",
    },
  };

  client = createTestClient(testConfig);
  testDbPg = createDbPg(testConfig.db);
});

// テスト後の共通クリーンアップ
afterEach(async () => {
  await testDbPg.db.delete(users);
  await testDbPg.pool.end();
});

describe("GET /api/v1/members/:uid/rank", () => {
  it("対象メンバーのランクを取得し、正常終了すること", async () => {
    // テストデータ登録
    const [resultUser] = await testDbPg.db
      .insert(users)
      .values([
        {
          lastName: "山田",
          firstName: "太郎",
          totalPurchaseAmount: 10_000,
        },
      ])
      .returning();

    // テスト実行
    const response = await client.api.v1.members[":uid"].rank.$get({
      param: {
        uid: resultUser.uid,
      },
    });

    // 検証
    expect(response.status).toBe(200);

    // レスポンス結果の検証
    const body = await response.json();
    expect(body).toEqual({
      rank: "silver",
    });
  });
});

$ pnpm run format
$ pnpm run lint
$ pnpm run test

$ curl https://get.volta.sh | bash

$ volta -v

$ volta install node@24.15.0

$ node -v

$ volta install corepack

$ corepack -v

$ corepack enable

$ pnpm -v

$ pnpm -v

$ brew install pnpm

$ mkdir next16-aidd && cd next16-aidd
$ pnpm create next-app@latest .

$ pnpm dev

$ touch .npmrc

engine-strict=true

{
  "name": "next16-aidd",
  "version": "0.1.0",
  "private": true,
  "engines": {
    "node": "24.15.0",
    "pnpm": "10.33.2"
  },
  "packageManager": "pnpm@10.33.2",
  "scripts": {

・・・

$ corepack use pnpm@10.33.2

・・・

  "scripts": {
    
    ・・・

    "lint": "biome lint",
    "format": "biome format --write",
    "check": "biome check --write",
    
    ・・・
  },

・・・

・・・

# pnpm
.pnpm-store

$ pnpm create storybook@latest

import type { Preview } from '@storybook/nextjs-vite'
// TailwindCSSの読み込み
import "@/app/globals.css";
// viewportをインポート
import { INITIAL_VIEWPORTS, MINIMAL_VIEWPORTS } from "storybook/viewport";

const preview: Preview = {
  parameters: {
    // viewportの設定追加
    viewport: {
      options: {
        ...INITIAL_VIEWPORTS,
        ...MINIMAL_VIEWPORTS,
      },
    },
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },

    a11y: {
      // 'todo' - show a11y violations in the test UI only
      // 'error' - fail CI on a11y violations
      // 'off' - skip a11y checks entirely
      test: 'todo'
    }
  },
};

export default preview;

{

・・・

  "files": {
    "ignoreUnknown": true,
    "includes": [
      "**",
      "!node_modules",
      "!.next",
      "!dist",
      "!build",
      "!src/stories"
    ]
  },

・・・

$ pnpm add -D jsdom @testing-library/react @testing-library/jest-dom @testing-library/user-event @vitejs/plugin-react msw msw-storybook-addon @playwright/test

$ pnpm approve-builds

$ touch vitest.setup.ts

import "@testing-library/jest-dom";

・・・

// vitest用の設定追加
import react from "@vitejs/plugin-react";

const dirname =
  typeof __dirname !== 'undefined'
  ? __dirname
  : path.dirname(fileURLToPath(import.meta.url));

// エイリアス設定追加
const alias = [
  {
    find: /^@\//,
    replacement: `${path.join(dirname, "src")}/`,
  },
  {
    find: "@",
    replacement: path.join(dirname, "src"),
  },
] as const;

// More info at: https://storybook.js.org/docs/next/writing-tests/integrations/vitest-addon
export default defineConfig({
  // エイリアス設定追加
  resolve: {
    alias,
  },
  test: {
    projects: [
      // ユニットテスト用（integration含む）
      {
        plugins: [react()],
        resolve: {
          alias,
        },
        test: {
          name: "unit",
          environment: "jsdom",
          globals: true,
          setupFiles: ["./vitest.setup.ts"],
          include: [
            "src/**/*.{test,spec}.{ts,tsx}",
            "tests/integration/**/*.{test,spec}.{ts,tsx}",
          ],
        },
      },
      // Storybook用
      {

・・・

・・・

  "scripts": {
    
    ・・・

    "build-storybook": "storybook build", // 末尾に追加するならカンマ追加して下さい
    "test": "vitest run --project unit --reporter=verbose",
    "test:e2e": "playwright test",
    "test:e2e:ui": "playwright test --ui"
  },

・・・

$ mkdir -p src/lib/msw/handlers && touch src/lib/msw/handlers/sample.ts
$ mkdir -p src/lib/msw/setup && touch src/lib/msw/setup/server.ts

import { HttpResponse, http, type RequestHandler } from "msw";

const helloHandler = http.get("http://localhost:3000/hello", () => {
  return HttpResponse.json({
    message: "Hello World !!",
  });
});

export const sampleHandlers: RequestHandler[] = [helloHandler];

import { setupServer } from "msw/node";
import { sampleHandlers } from "../handlers/sample";

// mswの設定
export const server = setupServer(...sampleHandlers);

import "@testing-library/jest-dom";
// mswの設定追加
import { afterAll, afterEach, beforeAll } from "vitest";
import { server } from "./src/lib/msw/setup/server";

beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

$ pnpm exec msw init public --save

{

・・・

  "files": {
    "ignoreUnknown": true,
    "includes": [

      ・・・

      "!src/stories",
      "!public/mockServiceWorker.js"
    ]
  },

・・・

・・・

// mswの設定追加
import { initialize, mswLoader } from "msw-storybook-addon";
import { sampleHandlers } from "@/lib/msw/handlers/sample";

// mswの初期化
initialize({ onUnhandledRequest: "warn" }, [
  ...sampleHandlers,
]);

const preview: Preview = {
  // mswの設定追加
  loaders: [mswLoader],

・・・

};

export default preview;

$ touch playwright.config.ts

import { defineConfig } from "@playwright/test";

export default defineConfig({
  testDir: "./tests/e2e",

  use: {
    baseURL: "http://localhost:3000",
    headless: true,
  },

  webServer: {
    command: "pnpm dev",
    url: "http://localhost:3000",
    reuseExistingServer: !process.env.CI,
  },
});

・・・

# playwright
test-results/
playwright-report/

$ pnpm add -D lefthook

$ pnpm approve-builds

$ pnpm exec lefthook install

pre-commit:
  parallel: true
  commands:
    biome:
      run: pnpm check

pre-push:
  parallel: false
  commands:
    unit-test:
      run: pnpm test
    e2e-test:
      run: pnpm test:e2e

pnpm storybook

pnpm dev

pnpm check

pnpm test

pnpm test:e2e:ui

$ pnpm add react-hook-form @hookform/resolvers

$ pnpm add zod

$ pnpm add swr

/my-project
 ├── /.codex
 |    ├── config.toml  ※codexに関する設定
 |    |
 |    ├── /rules  ※sandbox外で実行できるコマンド制御の設定
 |    |    └── default.rules
 |    |
 |    ├── /agents  ※サブエージェントを利用する場合の例
 |    |    ├── orchestrator.toml  ※指揮者（全体制御）
 |    |    ├── tester.toml        ※テスター（テストコード作成・検証）
 |    |    ├── implementer.toml   ※実装者（テストコードを通すように実装）
 |    |    └── reviewer.toml      ※レビュワー（設計や品質チェック）
 |    |
 |    ├── /workflows  ※ワークフローを利用する場合の例
 |    |    └── sdd_flow.md  ※SDD（Storybook Driven Development）のフロー
 |    |
 |    └── /skills  ※Agent Skillsを利用する場合
 |
 ├── AGENTS.md  ※ルートディレクトリ用（共通ルール）
 |
 ├── /src
 |    └── AGENTS.md  ※サブディレクトリ用（専用ルール）
 |
 └── /docs  ※詳細仕様にファイル分割して格納（各種AGENTS.mdから指定する）
      └── /rules
           ├── architecture.md  ※設計思想のルール定義
           ├── database.md      ※DB設計のルール定義
           ├── sub.md           ※サブディレクトリ用のルール定義
           └── testing.md       ※テスト用のルール定義
 

$ mkdir .codex && touch .codex/config.toml

model = "gpt-5.2"
model_reasoning_effort = "medium"

sandbox_mode = "workspace-write"

[projects."対象のプロジェクトのフルパス"]
trust_level = "trusted"

$ mkdir -p .codex/rules && touch .codex/rules/default.rules

# --- ディスク破壊（即禁止） ---
prefix_rule(
    pattern=["mkfs", "dd if=", "wipefs"],
    decision="forbidden",
    justification="ストレージ破壊操作"
)

# --- Git履歴破壊（即禁止） ---
prefix_rule(
    pattern=["git push --force", "git push -f", "git push --force-with-lease"],
    decision="forbidden",
    justification="履歴改変（強制push）によるリポジトリ破壊の可能性"
)

# --- GitHub CLI 危険操作 ---
prefix_rule(
    pattern=["gh repo delete"],
    decision="forbidden",
    justification="リポジトリ削除（不可逆）"
)

prefix_rule(
    pattern=["gh pr merge --admin"],
    decision="prompt",
    justification="保護ルール無視の強制マージ"
)

prefix_rule(
    pattern=["gh workflow run"],
    decision="prompt",
    justification="CI/CDの強制実行"
)

prefix_rule(
    pattern=["gh secret set", "gh secret delete"],
    decision="prompt",
    justification="機密情報の変更"
)
# --- 危険削除（確認） ---
prefix_rule(
    pattern=["rm -rf", "sudo rm"],
    decision="prompt",
    justification="不可逆削除の可能性"
)

# --- 権限昇格 ---
prefix_rule(
    pattern=["sudo"],
    decision="prompt",
    justification="システム影響が大きい"
)

$ mkdir -p .codex/agents
$ touch .codex/agents/pm.toml .codex/agents/tester.toml .codex/agents/implementer.toml .codex/agents/reviewer.toml

name = "pm"
description = "全体の進行管理とタスク分解を行うプロダクトマネージャー"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"

developer_instructions = """
あなたは開発全体を指揮するプロダクトマネージャーです。

役割：
- 要件を整理し、タスクに分解する
- tester → implementer → reviewer の順でタスクを割り振る
- 各エージェントのアウトプットを評価し、次の行動を決める

ルール：
- 必ずTDDサイクル（RED → GREEN → REVIEW）を守る
- 不完全な実装は次に進めない
- 問題があれば前の工程に差し戻す

出力形式：
- 次に行動するエージェント名
- 依頼内容（具体的に）
"""

name = "tester"
description = "テストコード作成と動作検証を行うTDDエンジニア"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"

developer_instructions = """
あなたはTDDに従うテストエンジニアです。

役割：
- 仕様に基づいたテストコードを書く（RED）
- 実装後にテストを実行し検証する（GREEN）

ルール：
- まず失敗するテストを書く（RED）
- テストは仕様を正確に表現すること
- エッジケースも考慮する
- 実装コードは書かない

出力：
- テストコード
- テストの意図説明
"""

name = "implementer"
description = "テストを通すための実装を行うエンジニア"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"

developer_instructions = """
あなたはTDDに従う実装エンジニアです。

役割：
- テストが通る最小限の実装を書く

ルール：
- テストを通すことを最優先
- 過剰な設計をしない（YAGNI）
- テストを書かない
- リファクタは必要最低限

出力：
- 実装コード
- 実装の簡単な説明
"""

name = "reviewer"
description = "仕様適合性・品質・セキュリティをレビューするエンジニア"
model_reasoning_effort = "high"
sandbox_mode = "read-only"

developer_instructions = """
あなたはコードレビュー担当です。

役割：
- 実装が仕様を満たしているか確認
- バグ・セキュリティ問題を検出
- テスト不足を指摘

観点：
- 正しさ（仕様通りか）
- セキュリティ
- 境界値・異常系
- テスト網羅性

ルール：
- 指摘は具体的に
- 再現手順を書く
- スタイル指摘は重要な場合のみ

出力：
- 指摘一覧（重要度付き）
- 修正提案
"""

$ mkdir -p .codex/workflows && touch .codex/workflows/sdd_flow.md

# SDD開発フロー（Storybook Driven Development）

フロントエンド開発における Storybook Driven Development（SDD）の標準フローを定義する。

- stories は UI仕様書として扱う。
- tests は必要に応じた振る舞い契約として扱う。
- 実装は、stories / tests のレビュー完了後に開始する。
- Storybook は最終的なUI確認およびレビュー環境として扱う。

stories は UI仕様、
tests は振る舞い契約、
実装はそれらを満たすために行う。

---

## 基本原則

### コンポーネントの作成

- コンポーネントは再利用可能なUI単位として設計すること。
- コンポーネントの作成では、まず `.stories.tsx` ファイルを先に作成する。
  - APIを利用している場合は、`.stories.tsx` 内でモック化すること。
- コンポーネントが振る舞いを持つ場合のみ `.test.tsx` ファイルを追加する。
  - `.test.tsx` ファイルを追加した際は、RED（失敗状態）で作成する。
  - APIを利用している場合はモック化すること。
    - `src/lib/msw/handlers` 内にハンドラー用のファイルを作成する。
    - `src/lib/msw/setup/server.ts` でハンドラーファイルの読み込み設定を行う。
- `.stories.tsx` および `.test.tsx` のレビュー完了前に実装を開始してはいけない。
- `.stories.tsx` および `.test.tsx` 作成完了後にレビュー可能状態にすること。
- `.stories.tsx` および `.test.tsx` のレビュー完了後、それらを満たすように実装すること。
  - 実装の際は `.test.tsx` を GREEN にすること。
  - 実装完了後、Storybook で確認可能な状態にすること。
- 実装完了後、Storybook 上で確認およびレビューを行うこと。
- 各レビューで問題があった場合は、修正して再レビューを行うこと。

---

### ページコンポーネントの作成

- 必要な各種コンポーネントの作成完了後、`page.tsx` に配置するページコンポーネントを作成すること。
- ページコンポーネントの作成では、`.stories.tsx` および `.test.tsx` を作成する。
  - APIを利用している場合はモック化すること。
  - `.test.tsx` はインテグレーションテストを含めること。
  - `.test.tsx` は RED（失敗状態）で作成すること。
- `.stories.tsx` および `.test.tsx` のレビュー完了前に実装を開始してはいけない。
- `.stories.tsx` および `.test.tsx` 作成完了後にレビュー可能状態にすること。
- `.stories.tsx` および `.test.tsx` のレビュー完了後、それらを満たすように実装すること。
  - ページコンポーネントは原則としてサーバーコンポーネントで作成すること。
  - クライアント側で状態共有が必要な場合のみクライアントコンポーネント化を許可する。
  - 実装時は `.test.tsx` を GREEN にすること。
  - 実装完了後、Storybook で確認可能な状態にすること。
- 実装完了後、Storybook 上で確認およびレビューを行うこと。
- 各レビューで問題があった場合は、修正して再レビューを行うこと。

---

### ページファイル（page.tsx）の作成

- 必要なページコンポーネントの作成完了後、ページファイル（page.tsx）を作成すること。
- 画面表示時に必要なデータ取得は、原則として page.tsx で行うこと。
- page.tsx で取得したデータはページコンポーネントへ渡すこと。
- page.tsx に複雑なUIロジックや状態管理を書いてはいけない。
- page.tsx の責務は以下に限定すること。
  - routing
  - params handling
  - fetch
  - ページコンポーネント呼び出し
- ページファイル作成完了後、ローカルサーバーを起動して動作確認およびレビューを行うこと。

---

### e2eテストの作成

- 複数ページの作成が完了し、ユーザーのユースケースを満たせる状態になった場合、必要に応じて e2e テストを作成する。
- e2eテストは必須ではない。
- e2eテストは薄く保つこと。
- e2eテストでは実装詳細ではなく、ユーザーユースケースを検証すること。
- e2eテストファイルは `tests/e2e/` 配下に `.spec.ts` として作成すること。

---

## コンポーネントの開発フロー

1. `.stories.tsx` を作成する
  - UI状態を定義する
  - 必要に応じてモックデータを作成する
  - API利用時は Storybook 用にモック化する

2. 振る舞いが必要な場合のみ `.test.tsx` を作成する
  - RED（失敗状態）で作成する
  - interaction / state change / validation を対象とする
  - API利用時は MSW でモック化する

3. `.stories.tsx` と `.test.tsx` をレビューする
  - UI仕様
  - 状態定義
  - interaction
  - accessibility
  - responsive behavior
  - test内容
  を確認する

4. `.stories.tsx` と `.test.tsx` を満たすように実装する
  - 最小実装を優先する
  - stories / tests を書き換えて通してはいけない

5. `.test.tsx` を GREEN にする
  - 全テストを成功させる
  - flaky test を作らない

6. Storybook で確認・レビューする
  - 各状態が正しく表示されること
  - visual consistency
  - accessibility
  - responsive behavior
  を確認する

7. 必要に応じてリファクタリングする
  - stories
  - tests
  を壊さないこと

---

## ページコンポーネントの開発フロー

1. 必要なコンポーネントを組み合わせて設計する

2. `.stories.tsx` を作成する
  - ページ全体のUI状態を定義する
  - Loading / Empty / Error を含める
  - API利用時はモック化する

3. `.test.tsx` を作成する
  - インテグレーションテストを含める
  - RED（失敗状態）で作成する

4. `.stories.tsx` と `.test.tsx` をレビューする
  - ユースケース
  - 状態遷移
  - interaction
  - accessibility
  - responsive behavior
  を確認する

5. `.stories.tsx` と `.test.tsx` を満たすように実装する
  - 原則としてサーバーコンポーネントで作成する
  - 必要な場合のみクライアントコンポーネント化する

6. `.test.tsx` を GREEN にする
  - インテグレーションテストを通す
  - 実装依存テストを避ける

7. Storybook で確認・レビューする
  - ページ全体の表示
  - 各状態
  - responsive behavior
  を確認する

8. 必要に応じてリファクタリングする

---

## ページファイル（page.tsx）の開発フロー

1. 必要なページコンポーネントを完成させる

2. `page.tsx` を作成する
  - routing
  - params handling
  - fetch
  - ページコンポーネント呼び出し
  のみを担当する

3. 画面表示時に必要なデータをフェッチする
  - 原則として page.tsx でフェッチする
  - フェッチしたデータをページコンポーネントへ渡す

4. loading / error handling を実装する

5. ローカルサーバーで確認・レビューする
  - routing
  - navigation
  - fetch
  - rendering
  を確認する

6. 必要に応じてリファクタリングする

---

## e2eテストの開発フロー

1. 対象ユースケースを整理する
  - ユーザー操作
  - 主要画面遷移
  - 主要機能
  を対象とする

2. `tests/e2e/` 配下に `.spec.ts` を作成する

3. ユースケースベースでテストを書く
  - 実装詳細に依存しない
  - UI内部構造に依存しない

4. 必要最小限のテストにする
  - e2eテストは薄く保つ
  - 重複テストを避ける

5. ローカル実行で確認する
  - 画面遷移
  - 入力
  - API連携
  - エラーハンドリング
  を確認する

6. flaky test を作らない
  - wait乱用禁止
  - timeout依存禁止
  - 安定した selector を使用する

---

## 完了条件

### コンポーネント

- `.stories.tsx` 作成済み
- 必要なUI状態が定義済み
- review 完了
- 実装完了
- Storybook で確認済み
- `.test.tsx` がある場合は GREEN

---

### ページコンポーネント

- `.stories.tsx` 作成済み
- Loading / Empty / Error 状態を確認済み
- review 完了
- 実装完了
- integration test がある場合は GREEN
- responsive behavior 確認済み
- Storybook で確認済み

---

### ページファイル（page.tsx）

- App Router に統合済み
- fetch 処理確認済み
- loading / error handling 実装済み
- ローカルサーバーで動作確認済み

---

### e2eテスト

- 必要なユースケースをカバー
- flaky test が存在しない
- ローカル実行で成功

$ mkdir -p .codex/skills/plan-to-issue && touch .codex/skills/plan-to-issue/SKILL.md
$ mkdir -p .codex/skills/plan-to-issue/references && touch .codex/skills/plan-to-issue/references/rules.md
$ mkdir -p .codex/skills/plan-to-issue/assets && touch .codex/skills/plan-to-issue/assets/template.md
$ mkdir -p .codex/skills/plan-to-issue/scripts && touch .codex/skills/plan-to-issue/scripts/create_issue.sh
$ chmod +x .codex/skills/plan-to-issue/scripts/create_issue.sh

---
name: plan-to-issue
description: プランモードで作成した開発計画をGitHub Issue用フォーマットへ変換して自動登録する
---

# plan-to-issue

## 概要

このスキルは、プランモードで作成された開発計画を読み込み、定義された変換ルールに従ってGitHub Issue形式へ構造化し、自動的にGitHubへ登録する。

---

## 重要原則（最重要）

- summary（概要）は要約してよい
- tasks（タスク）は**絶対に要約してはならない（展開必須）**
- tasksは「実装可能な手順レベル」にまで分解する
- 不明点は補完しつつも、実行手順を失わないことを優先する

---

## 参照ファイル

必ず以下を読み込むこと：

- **変換ルール定義**: `references/rules.md`
- **出力テンプレート**: `assets/template.md`
- **登録スクリプト**: `scripts/create_issue.sh`

---

## 入力

プランモードで作成された開発計画（仕様・タスク・背景など）

---

## 出力

GitHub Issue（gh issue create により自動登録）

---

## 実行手順

### 1. 開発計画の解析

- 目的・背景・機能・制約を分解して理解する
- 暗黙的なタスクも抽出する

---

### 2. ルール読み込み

- `references/rules.md` を厳密に適用する

---

### 3. テンプレート適用

- `assets/template.md` に従いIssue構造を生成

---

### 4. タイトル生成

- rules.mdの命名規則に従う

---

### 5. GitHub登録

- `scripts/create_issue.sh` を使用してIssue作成

---

## 品質保証（必須チェック）

- tasksは抽象化されていないか
- 実装手順が復元可能か
- 設計・実装・テストが含まれているか

# 変換ルール定義（plan-to-issue）

## 1. 基本方針

- 1 Issue = 1目的（または1成果物）
- 情報は構造化するが、**実行可能性を失わないことを最優先**
- summaryとtasksは役割を完全に分離する

---

### 最重要ルール

#### summaryとtasksの役割分離

| 項目 | 性質 | ルール |
|------|------|--------|
| summary | 要約 | 圧縮OK |
| tasks | 実行手順 | 圧縮禁止・完全展開必須 |

---

## 2. フィールド対応ルール

### 2-1 summary（概要）

- 目的ベースで1〜3文
- 実装詳細は書かない
- 要約OK

---

### 2-2 background（背景）

- 課題・理由・現状を記述
- 不足は文脈補完可

---

### 2-3 scope（スコープ）

- In Scope / Out of Scope を明示
- 暗黙スコープは必ず明文化

---

## 2-4 tasks

### 絶対ルール

#### 禁止

- 「実装する」
- 「対応する」
- 「作る」
- 「改善する」

→ これらはすべて禁止（抽象語）

---

### 必須ルール

tasksは必ず以下を満たす：

#### 1. 手順分解必須
- 設計 → 実装 → テスト → 検証の順で展開

#### 2. 最小粒度
- 1タスク = 30〜90分単位
- 1タスク = 単一アクション

#### 3. 具体動詞必須
- 「作成する」「定義する」「追加する」「検証する」

---

#### 4. 必須分解カテゴリ

必ず以下を含める：

- 仕様確認
- 設計
- データ構造定義
- 実装
- エラーハンドリング
- テスト
- 動作確認

---

#### 5. タスク展開ルール（強化）

開発計画からタスク化する際は：

- 機能を「手順」に分解
- 暗黙工程も明示化
- 一つの機能を1タスクにしない

---

#### 6. 良い例

##### 悪い
- APIを実装する

##### 良い
- API仕様（リクエスト/レスポンス）を定義する
- エンドポイントルーティングを作成する
- バリデーション処理を実装する
- DBアクセス層を実装する
- エラーハンドリングを追加する
- 単体テストを作成する
- 結合テストを実行する

---

## 2-5 acceptance_criteria

- 「できること」で記述
- 必ずテスト可能であること

例：
- 正常リクエストで200が返ること
- 不正入力でエラーが返ること

---

## 2-6 notes

- 技術制約
- 依存関係
- 未確定事項（要確認）
- 将来対応

---

## 3. タイトル生成ルール

Issueタイトルは以下のルールで生成する

### フォーマット

[種別] 内容の要約

### 種別の分類

- feat: ユーザーに価値を提供する新機能
- fix: 不具合の修正
- refactor: 挙動を変えない内部改善
- docs: ドキュメントの追加・更新
- test: テストの追加・修正
- infra: インフラ・CI/CD・環境構築
- chore: 上記に当てはまらない雑務（極力使わない）

### ルール

- 30〜60文字程度に収める
- 内容が一目で分かるようにする
- summaryの内容をベースに生成する

例:

- feat: ユーザー登録APIを実装する
- fix: ログイン時の認証エラーを修正

---

## 4. Issue分割ルール

- 10タスク以上 → 分割必須
- 独立機能は別Issue
- 依存関係はnotesへ

---

## 5. 不足情報補完

- 合理的推測OK
- 推測はnotesに明記
- 不確定は「要確認」

---

## 6. 禁止事項

- 抽象タスク
- 実行不能なタスク
- tasksの要約
- 背景なしIssue

---

## 7. 出力品質チェック

- tasksが完全手順化されている
- 抽象名詞が存在しない
- 設計〜テストが揃っている
- 実装順が復元可能

## 概要
{{summary}}

## 背景
{{background}}

## スコープ
{{scope}}

## タスク
- [ ] {{tasks}}

## 受け入れ条件
- {{acceptance_criteria}}

## 補足
{{notes}}

#!/usr/bin/env bash

set -euo pipefail

# ===============================
# Usage:
# ./create_issue.sh "タイトル" "本文"
# ===============================

TITLE="${1:-}"
BODY="${2:-}"

# タイトルと本文の入力チェック
if [[ -z "$TITLE" || -z "$BODY" ]]; then
  echo "Usage: $0 \"タイトル\" \"本文\""
  exit 1
fi

# gh コマンド存在チェック
if ! command -v gh &> /dev/null; then
  echo "gh コマンドが見つかりません"
  exit 1
fi

# GitHub認証チェック
if ! gh auth status &> /dev/null; then
  echo "GitHubにログインしていません"
  echo "gh auth login を実行してください"
  exit 1
fi

echo "Issueを作成中..."

# 一時ファイル作成
TMP_FILE=$(mktemp)

# 一時ファイルをスクリプト終了時に削除
trap 'rm -f "$TMP_FILE"' EXIT

# 本文を一時ファイルに書き込み
printf "%s" "$BODY" > "$TMP_FILE"

# Issue作成
gh issue create \
  --title "$TITLE" \
  --body-file "$TMP_FILE"

echo "Issue作成完了"

$ mkdir -p .codex/skills/auto-commit && touch .codex/skills/auto-commit/SKILL.md

$ mkdir -p .codex/skills/auto-pr && touch .codex/skills/auto-pr/SKILL.md
$ mkdir -p .codex/skills/auto-pr/assets && touch .codex/skills/auto-pr/assets/template.md
$ mkdir -p .codex/skills/auto-pr/scripts && touch .codex/skills/auto-pr/scripts/create_pr.sh
$ chmod +x .codex/skills/auto-pr/scripts/create_pr.sh

---
name: auto-pr
description: 直前のコミット内容をもとにPRタイトルと本文を生成し、GitHubのPR用フォーマットへ変換して自動登録する
---

# auto-pr

## 概要

このスキルは、直前のコミット内容をもとにPRタイトルと本文を生成し、GitHubのPR用フォーマットへ変換して自動登録します。

## 参照ファイル

このスキルを実行する際は、以下のファイルを必ず読み込んで使用してください。

- PRテンプレート: `assets/template.md`
- PR作成スクリプト: `scripts/create_pr.sh`

## 入力

直前のコミット情報

## 出力

GitHubのPR（gh pr create により自動登録）

---

## 実行手順

### 1. 直前のコミット情報と変更内容を取得する

```bash
git log -1 --pretty=format:"%h%n%s%n%b"
git show --no-color
```

- git log: 意図（タイトル・背景）
- git show: 変更内容（diff）

---

### 2. 解析して以下を生成する

- summary（概要）
- background（背景・目的）
- implementation（実装内容：箇条書き）
- test_items（テスト確認項目：チェックリスト形式）
- impact（影響範囲：箇条書き）
- future_work（未対応・今後の課題：箇条書き or なし）

---

### 3. PR本文を生成する

`assets/template.md` を読み込み、以下ルールで置換する：

- {{summary}} → summary
- {{background}} → background
- {{implementation}} → implementation
- {{test_items}} → test_items
- {{impact}} → impact
- {{future_work}} → future_work

---

### 4. PRタイトルを生成する

フォーマット：

```text
auto: <summaryの短縮版>
```

---

### 5. PRを作成する

現在のブランチをGitHubへ反映し、そのブランチを元にPRを作成する。

#### 5-1. 現在のブランチをGitHubへプッシュ

```bash
git push -u origin HEAD
```

※ pushに失敗した場合は処理を中断する

#### 5-2. PR作成

`scripts/create_pr.sh` を利用し、生成したPRタイトルと本文をGitHubに登録する

---

## 補足ルール（重要）

### ■ implementation

- diff（git show）に**実際に現れた変更のみ**を記述する
- 推測は禁止

---

### ■ test_items（重要改善）

テスト観点は以下を厳守：

- コマンド実行（例: pnpm test, npm run test など）を書かない
- 「実行手段」ではなく「確認すべき振る舞い」を書く
- diffに基づいたユーザー視点の確認項目にする

#### 良い例

- [ ] ユーザー一覧が正しく取得できる
- [ ] エラー時に適切なメッセージが表示される
- [ ] 新規作成後に一覧へ反映される

#### 悪い例（禁止）

- [ ] pnpm testを実行する
- [ ] テストコマンドを通す

---

### ■ impact

- 影響範囲を事実ベースで記載する（推測禁止）

---

### ■ future_work（重要改善）

以下ルールを厳守：

- diffやコミット内容から**明確に未対応と分かる場合のみ記載**
- 推測や一般論は禁止
- 該当がない場合は必ず以下のいずれかにする：
  - `なし`
  - または空欄（推奨は「なし」）

#### 記載してよい例

- エラーハンドリングの追加が未実装
- 一部APIのリトライ処理が未対応

#### 記載NG例

- パフォーマンス改善が必要（根拠なし）
- 今後リファクタリング予定（根拠なし）

---

## 全体ルール

- implementation / impact / future_work は必ず箇条書き
- test_items は必ずチェックリスト形式（- [ ]）
- diff（git show）を必ず根拠とし、推測のみで生成しない

## 概要
{{summary}}

## 背景・目的
{{background}}

## 実装内容
- {{implementation}}

## テスト確認項目
- [ ] {{test_items}}

## 影響範囲
- {{impact}}

## 未対応・今後の課題
- {{future_work}}

#!/usr/bin/env bash

set -euo pipefail

# ===============================
# Usage:
# ./create_pr.sh "タイトル" "本文"
# ===============================

TITLE="${1:-}"
BODY="${2:-}"

# タイトルと本文の入力チェック
if [[ -z "$TITLE" || -z "$BODY" ]]; then
  echo "Usage: $0 \"タイトル\" \"本文\""
  exit 1
fi

# gh コマンド存在チェック
if ! command -v gh &> /dev/null; then
  echo "gh コマンドが見つかりません"
  exit 1
fi

# GitHub認証チェック
if ! gh auth status &> /dev/null; then
  echo "GitHubにログインしていません"
  echo "gh auth login を実行してください"
  exit 1
fi

echo "PRを作成中..."

# 一時ファイル作成
TMP_FILE=$(mktemp)

# 一時ファイルをスクリプト終了時に削除
trap 'rm -f "$TMP_FILE"' EXIT

# 本文を一時ファイルに書き込み
printf "%s" "$BODY" > "$TMP_FILE"

# PR作成
gh pr create \
  --title "$TITLE" \
  --body-file "$TMP_FILE"

echo "PR作成完了"

$ mkdir -p docs/rules
$ touch docs/rules/ui.md docs/rules/testing.md docs/rules/frontend.md
$ touch src/AGENTS.md AGENTS.md

# UI実装ルール（Storybook）

Storybookを利用したUI実装ルールを定義する。

Storybookは単なる動作確認環境ではなく、UI仕様書およびレビュー環境として扱う。

---

## 基本原則

- stories を先に作成する
- stories はUI仕様書として扱う
- Storybook 単体でレビュー可能な状態にする
- 実装前に stories をレビュー可能状態にする
- stories を満たすように実装する
- UI状態を省略しない
- mock を利用して再現可能な状態を作る
- UI状態は useEffect で作らない

---

## stories の責務

stories は以下を表現すること：

- UI状態
- interaction
- Loading状態
- Empty状態
- Error状態
- Disabled状態
- responsive behavior
- accessibility

---

## stories 作成ルール

### 1 story = 1 state

1つの story では1つの状態のみを表現すること。

悪い例：

```tsx
export const AllStates = () => (
  <>
    <Button />
    <Button disabled />
    <Button loading />
  </>
);
```

良い例：

```tsx
export const Default = {};
export const Loading = {};
export const Error = {};
export const Empty = {};
export const Disabled = {};
```

---

## 必須状態

必要に応じて以下を作成すること：

- Default
- Loading
- Empty
- Error
- Disabled
- Hover
- Active
- Selected
- Mobile
- Tablet
- Desktop
- Dark mode

---

## args を利用する

props 切り替え可能なものは args を利用すること。

固定値を大量に埋め込まないこと。

---

## controls を利用する

レビュー時に変更可能な props は controls を利用すること。

---

## mock データルール

- Storybook 上で完結するモックを作成する
- API通信を実際に行ってはいけない
- API利用時は MSW を利用する
- mock は再利用可能にする

---

## MSW 利用ルール

API利用時は MSW を利用すること。

- handler は `src/lib/msw/handlers` に配置する
- Storybook 用 mock と test 用 mock を共有可能にする
- Loading / Error / Success を切り替え可能にする

---

## レイアウトルール

- Storybook 上で崩れないこと
- 極端な margin 調整に依存しないこと
- 固定高さレイアウトを乱用しないこと

---

## responsive ルール

responsive behavior を確認可能にすること。

最低限確認する：

- Mobile
- Desktop

必要に応じて Tablet も確認すること

---

## accessibility ルール

以下を確認すること：

- keyboard interaction
- focus visibility
- aria-label
- semantic HTML
- color contrast

---

## Tailwind CSS ルール

- utility class を優先する
- className の肥大化を避ける
- 重複 class を避ける
- magic number を乱用しない
- conditional class は整理する

---

## useEffect ルール（重要）

Storybook内のUIコンポーネントにおいて useEffect は「副作用専用」として扱う。

---

### 基本原則

- UI状態の生成に useEffect を使わない
- props → state の同期に使わない
- Storybookの状態は stories / args で表現する
- UIの表示制御目的で useEffect を使わない

---

### 使用してよいケース

- ブラウザAPI操作（window / document）
- event listener の登録・解除
- 外部購読（WebSocketなど）
- DOM操作
- アニメーション制御などの純粋な副作用

---

### 使用禁止・非推奨ケース

- propsからstateを生成する処理
- loading / error などUI状態の制御
- Storybook状態の代替としてのuseEffect
- API fetch目的（Server Component / MSW優先）

---

### Storybookとの関係

- UI状態は story で定義する
- state遷移は story 切替で表現する
- useEffectで状態遷移を作らない
- mock / args で再現する

---

### 依存配列ルール

- 使用している値は必ず依存配列に含める
- eslintルールを無視しない
- stale closure を許容しない

---

### StrictMode考慮

- useEffectは開発時に2回実行される可能性がある
- 副作用は必ず冪等にすること
- 二重実行で壊れる処理は禁止

---

### クリーンアップ必須ケース

- event listener
- interval / timeout
- subscription

必ず cleanup を実装すること

---

## Component 分割ルール

以下の場合は component 分割を検討すること：

- JSX が長すぎる
- 状態責務が増えすぎている
- 再利用可能
- story が複雑になりすぎている

---

## 禁止事項

- 実装前に stories を省略する
- Loading/Error を省略する
- Storybook 上で動作確認できない状態を作る
- API実通信に依存する
- 巨大 story を作る
- 1 story で複数状態を表現する
- UI仕様未定義のまま実装する
- useEffectでUI状態を構築する

---

## レビュー観点

レビュー時は以下を確認する：

- UI仕様が十分か
- 状態が不足していないか
- responsive behavior
- accessibility
- visual consistency
- interaction
- Loading/Error handling
- useEffectの用途が適切か

# テスト実装ルール

フロントエンド開発におけるテスト実装ルールを定義する。

- tests は振る舞い契約として扱う
- 実装詳細ではなく、ユーザーから見た振る舞いを保証することを目的とする

---

## 基本原則

- 必要な場合のみ tests を作成する
- tests は RED（失敗状態）から開始する
- tests を満たすように実装する
- 実装詳細ではなく振る舞いをテストする
- flaky test を作らない
- mock を利用して安定したテストを作る

---

## test が必要な条件

以下を含む場合は `.test.tsx` を作成すること：

- ユーザー操作
- state変更
- form validation
- conditional rendering
- async処理
- accessibility interaction
- integration behavior

---

## test が不要なケース

以下のみの場合は test を省略可能：

- 単純な Presentational Component
- Typography wrapper
- Layout wrapper
- 静的表示のみ

---

## Unit Test ルール

Unit Test では以下を確認すること：

- interaction
- state change
- rendering
- callback
- validation

---

## Integration Test ルール

Integration Test では以下を確認すること：

- Component連携
- 状態遷移
- API integration
- form flow
- user flow

---

## E2E Test ルール

E2E Test は以下を目的とする：

- 主要ユースケース確認
- 回帰防止
- 画面統合確認

E2E Test は薄く保つこと

---

## selector ルール

selector の優先順位は以下とする：

1. role
2. label
3. text
4. placeholder
5. data-testid

可能な限り `data-testid` を避けること

---

## Mocking ルール

API利用時は MSW を利用すること。

- mock を再利用可能にする
- Storybook と test で共有可能にする
- Success / Error / Loading を切り替え可能にする

---

## MSW 利用ルール

- handler は `src/lib/msw/handlers` に配置する
- `src/lib/msw/setup/server.ts` に登録する
- 実API通信を行ってはいけない

---

## useEffect テスト上のルール（重要）

テストにおいて useEffect を含むコンポーネントは「副作用の発火タイミング」に依存しない設計にすること。

---

### 基本原則

- useEffectの実行タイミングをテストで制御しようとしない
- useEffectの内部状態を直接検証しない
- 副作用の結果のみを検証する
- render後の不安定な状態変化を前提にしない

---

### テストしてよい対象

- 副作用の「結果」（UI変化・DOM変化）
- event handler による状態変化
- ユーザー操作後の挙動

---

### テストしてはいけない対象

- useEffect の実行回数
- useEffect 内部のローカル変数
- useEffect のタイミング依存ロジック
- 非同期タイマーの内部状態

---

### 非同期 useEffect の扱い

- waitFor は最小限にする
- 安定したUI結果を待つ
- setTimeout 依存のテストは禁止
- fetch結果は MSW で制御する

---

## 非同期テストルール

- async/await を利用する
- waitFor を最小限にする
- 安定した完了条件を待つ
- timing依存を避ける

---

## accessibility テストルール

必要に応じて以下を確認すること：

- keyboard navigation
- focus movement
- aria attributes
- accessible name

---

## flaky test 防止ルール

- ランダム値に依存しない
- 時刻依存を避ける
- timeout依存を避ける
- 実ネットワーク通信を行わない
- test 間で状態共有しない
- useEffectの非同期タイミングに依存しない

---

## RED / GREEN ルール

### RED

- 失敗する test を先に作成する
- 未実装状態であることを確認する

### GREEN

- 最小実装で test を通す
- test を書き換えて通してはいけない

---

## 禁止事項

- className selector
- implementation detail のテスト
- state 内部値の直接確認
- private function のテスト
- snapshot test の乱用
- waitFor の乱用
- timeout 依存
- sleep/wait の固定時間依存
- useEffectの内部実行制御を前提にしたテスト

---

## レビュー観点

レビュー時は以下を確認すること：

- 振る舞いを保証できているか
- implementation detail に依存していないか
- flaky test の可能性がないか
- accessibility を考慮しているか
- 過剰テストになっていないか
- useEffect依存のテスト設計になっていないか

# フロントエンド開発の実装ルール（Next.js / App Router）

Next.js の App Router を利用したフロントエンド開発の実装ルールを定義する。

各ディレクトリの責務を明確に分離し、UI・状態・データ取得・ルーティングの境界を整理することを目的とする。

---

## 基本原則

- App Router を利用する
- page.tsx は薄く保つ
- UI責務とデータ責務を分離する
- 再利用可能なUIは `src/components` に配置する
- API通信は直接 component に埋め込まない
- Server Component を優先する
- 必要な場合のみ Client Component を利用する
- Storybook でレビュー可能な構成にする

## ディレクトリ責務

### `src/app`

Next.js App Router 用ディレクトリ。

- routing
- page.tsx
- layout.tsx

---

### `src/components`

コンポーネントを管理する。

- UI Components
- Page Components
- stories
- tests

---

### `src/components/common`

共通利用するコンポーネントパーツを管理する。

- Button
- Input
- Dialog
- Card
- Table
- Form Parts

再利用可能なUIはここに配置すること。

---

### `src/contexts`

アプリ全体で共有する状態を管理する。

#### 役割

- グローバル状態管理
- アプリ横断の状態共有

#### 例

- Auth
- Theme
- Locale
- UI設定

#### 禁止事項

- フォーム状態の管理
- 一時的UI状態の管理
- コンポーネント内部状態の代替

---

### `src/hooks`

Reactロジックの再利用を管理する。

#### 役割

- UIロジックの再利用
- interactionロジックの共通化

#### 例

- useModal
- useDebounce
- useMediaQuery
- usePagination

#### 禁止事項

- UIコンポーネントの定義
- pure function（→ libへ）
- APIクライアント（→ libへ）

---

### `src/types`

アプリ全体の型定義を管理する。

#### 役割

- APIレスポンス型
- ドメイン型
- 共通UI型
- フォーム型

---

### `src/lib`

アプリに依存しない純粋な基盤コードを管理する。

#### 役割

- APIクライアント
- APIエンドポイント定義
- utils
- constants
- validators
- MSW

---

### `src/lib/api`

API関連処理を管理する。

#### 構成例

- client.ts（fetchラッパー）
- endpoints.ts（エンドポイント定義）
- users.ts（ドメイン別API）
- auth.ts

---

### `src/lib/api/endpoints.ts`

APIエンドポイントを一元管理する。

#### 目的

- URLの散在防止
- 変更の局所化
- API呼び出しの統一

#### 例

```tsx
export const endpoints = {
  users: "/api/users",
  userDetail: (id: string) => `/api/users/${id}`,
  login: "/api/auth/login",
};
```

#### 禁止事項

- コンポーネント内でURLを直接記述すること
- feature/component側でのエンドポイント定義

---

### `src/lib/msw`

MSW の設定および共通基盤。

---

### `src/lib/msw/handlers`

APIごとの mock handler を管理する。

- users.ts
- auth.ts
- posts.ts

---

### `src/lib/msw/setup/server.ts`

MSW server 設定ファイル。

handler をまとめて読み込む。

---

## App Router ルール

### page.tsx の責務

- routing
- params handling
- fetch
- Page Component 呼び出し

---

## page.tsx の禁止事項

- UIロジックの実装
- 大量の JSX
- state管理
- business logic

---

## Server Component ルール

優先して利用する。

- page.tsx
- Page Components
- fetch専用コンポーネント

---

## Client Component ルール

以下が必要な場合のみ `"use client"` を使用する。

- browser API
- event handler
- useState / useEffect
- client interaction

---

## useEffect ルール（重要）

useEffectは「副作用専用の最終手段」として扱う。

### 基本原則

- UI状態の同期目的では使用しない
- props → state のコピーに使用しない
- 可能な限り Server Component または render計算で代替する
- Reactのレンダリング結果で表現できるものには使わない

---

### 使用してよいケース

- ブラウザAPI操作（window / document）
- event listener の登録・解除
- 外部サービス購読（WebSocketなど）
- DOM依存処理
- クライアント限定の副作用

---

### 使用禁止・非推奨ケース

- propsからstateを生成する処理
- 表示状態の同期（derived state）
- 初期化ロジックの代替
- fetch目的での乱用（Server Component優先）

---

### fetchとの関係

- データ取得は原則 Server Component で行う
- useEffectでのfetchは例外的ケースのみ
- useEffect fetchはUI依存・遅延処理のみ許可

---

### 依存配列ルール

- 使用している値は必ず依存配列に含める
- eslint警告を無視しない
- stale closureを許容しない設計にする

---

### StrictMode考慮

- useEffectは開発時に2回実行される可能性がある
- 副作用は冪等性を持たせること
- 二重実行で破綻する処理は禁止

---

### クリーンアップ必須ケース

- event listener
- interval / timeout
- subscription

必ず cleanup を実装すること

---

## 状態管理ルール

状態はスコープを最小にする。

優先順位：

1. local state
2. component state
3. page state
4. contexts（必要時のみ）

---

## fetch ルール

原則として page.tsx で fetch を行う。

---

## 禁止事項

- page.tsx の肥大化
- 不要な `"use client"`
- component 内での直接API実通信
- UIとfetch責務の混在
- 巨大component
- useEffectによる過剰な状態管理

---

## レビュー観点

- 責務分離できているか
- page.tsx が薄いか
- Server/Client境界が適切か
- Storybookでレビュー可能か
- test可能な構造か
- 再利用可能か
- useEffectが適切な用途か

# フロントエンド開発の全体ルール

Next.js（App Router）におけるフロントエンド開発の全体ルールを定義する。

Codex / AIエージェントを含むすべての実装は、必ずこのルールを前提として動作すること。

## 基本思想

本プロジェクトは以下を前提とする：

- Storybook Driven Development（SDD）
- Test Driven Development（TDD）
- コンポーネント中心設計
- MSWによるAPIモック前提開発
- UIとロジックの責務分離

## 参照ドキュメント

開発時は必ず以下を参照すること：

- UI実装ルール 
  → `docs/rules/ui.md`

- テストルール 
  → `docs/rules/testing.md`

- Next.js実装境界ルール 
  → `docs/rules/frontend.md`

- 実装フロー（SDD） 
  → `.codex/workflows/sdd_flow.md`

## 開発ルールの優先順位

以下の優先順位でルールを適用する：

1. AGENTS.md（本ドキュメント）
2. docs/rules/frontend.md
3. docs/rules/ui.md
4. docs/rules/testing.md
5. .codex/workflows/sdd_flow.md

## 実装フロー

実装手順の詳細は以下を参照すること：

→ `.codex/workflows/sdd_flow.md`

すべての実装は必ずこのフローに従うこと。

## ディレクトリルール

### UI

- `src/components`：UI全般
- `src/components/common`：共通UI

---

### 状態管理

- `src/contexts`：グローバル状態
- `src/hooks`：Reactロジック

---

### 型

- `src/types`：全体型定義

---

### 基盤

- `src/lib`：純粋関数・基盤処理
- `src/lib/api`：API関連
- `src/lib/msw`：モックサーバー

---

## 実装ルール

### UI実装

- 必ず Storybook を先に作成する
- stories はUI仕様書として扱う
- UI状態を省略しない
- MSWでAPIをモック化する

---

### テスト

- 振る舞いがある場合のみ test を作成する
- RED状態から開始する
- MSWを利用する
- 実装依存テストを避ける

---

### page.tsx ルール

- routingのみ担当
- fetchのみ担当
- UIロジックは禁止
- state禁止
- Page Component呼び出しのみ

---

### Server / Client ルール

#### 1. Server Component 優先

- page.tsx
- Page Components
- fetch処理

#### 2. Client Component 条件

以下の場合のみ `"use client"` を許可：

- useState / useEffect
- browser API
- event handler
- client interaction

---

## 禁止事項

以下は禁止：

- storiesなしでの実装開始
- testなしでの振る舞い実装
- APIの直接呼び出し（components内）
- UIとfetchの混在
- page.tsxの肥大化
- 不要な `"use client"`
- URLの直接記述（lib/api/endpoints以外）

## APIルール

### エンドポイント管理

APIのエンドポイントは必ず以下で管理する：

→ `src/lib/api/endpoints.ts`

#### 例

```tsx
export const endpoints = {
  users: "/api/users",
  userDetail: (id: string) => `/api/users/${id}`,
  login: "/api/auth/login",
};
```

---

### APIクライアントルール（重要）

Next.js の標準 `fetch` を優先するため、APIクライアントは必須ではない。

共通処理が必要な場合のみ、`src/lib/api/client.ts` に薄く実装する。

---

#### 役割

- エラーハンドリング統一
- JSON変換補助
- 認証ヘッダー付与
- ログ処理（必要時）

---

#### 原則

- Server Componentでは直接 fetch を使用する
- 無理にラップしない
- Next.js の fetch のキャッシュ機能を損なわない

---

### API呼び出しルール

- UI側から直接fetch禁止
- ドメインごとにAPIファイルを分割する
- endpoint は必ず `src/lib/api/endpoints.ts` を使用する

---

## MSWルール

- `src/lib/msw/handlers` にAPIモックを配置
- `src/lib/msw/setup/server.ts` で統合
- Storybook / test 両方で共有する
- 実API通信は禁止

## 品質保証ルール

コード作成・修正後は必ず以下を実行すること：

```bash
pnpm check
```

### pnpm check の目的

- フォーマット修正
- import整理
- lintチェック（静的コード解析）

## テスト実行ルール（重要）

コード修正・実装完了後は、必ず以下のテストを実行し、
すべてパスしていることを確認すること。

```bash
pnpm test
```

E2Eテストが存在する場合は、必ず以下も実行すること：

```bash
pnpm test:e2e
```

### 必須条件

- pnpm check が通ること
- pnpm test がすべてパスすること
- pnpm test:e2e がある場合はすべてパスすること
- エラー・警告が残っていないこと
- Storybookで表示崩れがないこと

## レビュー観点

AIは以下を常に確認すること：

- UI状態が不足していないか
- storiesが仕様として成立しているか
- testが振る舞いを保証しているか
- 責務分離ができているか
- fetchがUIに侵食していないか
- MSWが適切に使われているか
- page.tsxが薄いか

# 全体のルール定義

## 概要

本プロジェクトはマルチエージェント構成（Codex Agents）を前提とする。

- 各エージェントは、`.codex/agents` に定義されており、すべての開発はこれらの役割分担に従って実行される。 
- Codex / AIエージェントは、必ずこの AGENTS.md を起点として動作する。 
- 開発の基本思想および、各エージェント、ワークフロー、開発のルール群を参照しながら開発を行うこと。

## 開発の基本思想

本プロジェクトは以下を前提とする：

- Storybook Driven Development（SDD）
- Test Driven Development（TDD）
- コンポーネント中心設計
- MSWによるAPIモック前提開発
- マルチエージェント分業開発

---

## マルチエージェント構成

以下のエージェントが役割分担して開発を行う：

- `.codex/agents/pm.toml`
- `.codex/agents/tester.toml`
- `.codex/agents/implementer.toml`
- `.codex/agents/reviewer.toml`

---

## ブランチ運用ルール（重要）

すべての実装・修正・テスト作成は、必ずブランチを切ってから開始すること。

### ブランチ命名規則

```txt
<prefix>/<short-description>
```

例

```txt
feat/user-login-ui
fix/button-disabled-state
test/login-form-validation
refactor/api-client-cleanup
docs/storybook-guideline-update
infra/msw-setup
chore/update-dependencies
```

---

### ブランチプレフィックス定義

#### 種別の分類

- feat: ユーザーに価値を提供する新機能
- fix: 不具合の修正
- refactor: 挙動を変えない内部改善
- docs: ドキュメントの追加・更新
- test: テストの追加・修正
- infra: インフラ・CI/CD・環境構築
- chore: 上記に当てはまらない雑務（極力使わない）

---

### ブランチ作成ルール（必須）

- テスト作成前に必ずブランチを作成する
- 実装開始前に必ずブランチを作成する
- 1タスク = 1ブランチを原則とする
- ブランチは短命に保つ

---

## 各エージェントの責務定義

### PM（Product Manager）

プロダクトの要件と開発方針を定義し、全体の設計意図とタスク構造を決定するエージェント。

#### 責務
- 要件整理・仕様の定義
- ユーザーストーリー作成
- タスク分解および実行順序の決定
- 全体の指揮および各エージェントへのタスク割り振り
- 必要に応じた軽量な設計判断（実装詳細には踏み込まない）

#### 禁止事項
- 実装詳細の決定
- コンポーネント構造の強制
- コードレベル設計への介入
- テストコードの作成

---

### Tester（テスター）

仕様をテストとして具体化し、期待される振る舞いを明確に定義するエージェント。

#### 参照ルール
テスト実装ルールは `docs/rules/testing.md` を参照する

#### 責務
- テスト設計（REDフェーズ）
- テストコード作成
- 期待仕様の定義（UI・挙動・状態）
- unit / integration / e2e テスト作成と実行
- APIレスポンス仕様の定義
- モックデータの設計
- MSWシナリオの定義（成功・失敗・loadingなど）

#### 禁止事項
- 実装コードの作成
- UIコンポーネント構造の決定
- 仕様変更
- テストを通すための仕様改変

---

### Implementer（実装者）

テストとStorybookで定義された仕様を満たすために実装を行うエージェント。

#### 責務
- 実装（GREENフェーズ）
- `.stories.tsx` に基づいたUI実装
- `.test.tsx` のテストを通すための最小実装
- Storybookで確認可能な状態の構築
- 既存MSWシナリオ前提での実装

#### 原則
- 最小実装を優先する
- テストを通すことが唯一の目的
- 仕様変更は禁止

#### 禁止事項
- 仕様の変更
- テストの書き換え
- MSWシナリオの変更
- 過剰設計

---

### Reviewer（レビュワー）

品質・設計・ルール遵守の最終保証を行うエージェント。

#### 責務
- テスト観点のレビュー
- StorybookでのUIレビュー
- コードレビュー
- 設計逸脱の検出
- 品質・構造の検証
- 責務分離の確認

#### 禁止事項
- 実装修正
- テスト修正
- 仕様変更

---

## 実装ワークフロー

すべての開発は以下のワークフローに従う：

```txt
.codex/workflows/sdd_flow.md
```

## フロントエンド開発の全体ルール

フロントエンド開発の実装については、以下のファイルを起点とする：

```txt
src/AGENTS.md
```

### 詳細ルール

- UI実装ルール：`docs/rules/ui.md`
- テストルール：`docs/rules/testing.md`
- フロントエンド開発の実装ルール：`docs/rules/frontend.md`

---

## 開発フロー

1. PM：要件整理・タスク分解
2. PM：ユーザーストーリー作成
3. Tester：ブランチを切る
4. Tester：テスト設計・テストコード作成（RED）
5. Reviewer：テストコードレビュー
6. Implementer：実装（GREEN）
7. Tester：テスト実行による検証およびレビュー
8. Reviewer：最終レビュー
  - 要件を満たしているか確認
  - Storybookでコンポーネント確認（UIチェック）
  - ローカルサーバーを起動してブラウザで確認（UI・動作チェック）
    - ブラウザのデベロッパーツールのコンソールで警告やエラーを確認（必要に応じて修正する）
9. 必要に応じて修正ループ

## 禁止事項

- エージェント責務の逸脱
- implementerによる仕様変更
- tester不在の実装
- storiesなし実装
- レビューなしでの完了扱い
- UIとロジックの混在
- ブランチ未作成での作業開始

## 品質保証ルール

すべてのコード変更後は必ず以下を実行すること：

```bash
pnpm check
```

さらにテストが存在する場合：

```bash
pnpm test
```

E2Eテストが存在する場合：

```bash
pnpm test:e2e
```

---

## 必須条件

- pnpm check が通ること
- pnpm test がすべてパスすること
- pnpm test:e2e がある場合はすべてパスすること
- Storybookで破綻がないこと
- レビューで承認されていること

$ mkdir -p .github/workflows && touch .github/workflows/ci.yml

name: CI

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  changes:
    runs-on: ubuntu-latest

    outputs:
      app: ${{ steps.filter.outputs.app }}

    steps:
      - name: リポジトリをチェックアウト
        uses: actions/checkout@v6

      - name: 差分チェック
        uses: dorny/paths-filter@v4
        id: filter
        with:
          filters: |
            app:
              - 'src/**'
              - 'tests/**'
              - 'public/**'

              # Next.js / build config
              - 'next.config.*'
              - 'tsconfig.json'
              - 'postcss.config.*'

              # package manager
              - 'package.json'
              - 'pnpm-lock.yaml'
              - 'pnpm-workspace.yaml'

              # lint / format
              - 'biome.json'

              # test tools config
              - 'vitest.config.*'
              - 'vitest.setup.*'
              - 'vitest.shims.*'
              - 'playwright.config.*'

  # biome check（フォーマット修正・import整理・lint）
  check:
    needs: changes
    if: needs.changes.outputs.app == 'true'
    runs-on: ubuntu-latest

    steps:
      - name: リポジトリをチェックアウト
        uses: actions/checkout@v6

      - name: Node.jsのインストール
        uses: actions/setup-node@v6
        with:
          node-version: 24.15.0

      - name: Corepackの有効化
        run: corepack enable

      - name: Corepackでpnpmのインストール
        run: corepack prepare pnpm@10.33.2 --activate

      - name: pnpmの「store path」を取得
        id: pnpm-store
        run: echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_OUTPUT

      - name: pnpmのキャッシュを取得
        uses: actions/cache@v5
        with:
          path: ${{ steps.pnpm-store.outputs.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-

      - name: .lockから依存関係をインストール
        run: pnpm install --frozen-lockfile

      - name: biome checkを実行
        run: pnpm check

  # 「unit/integration」tests 
  unit-test:
    needs: changes
    if: needs.changes.outputs.app == 'true'
    runs-on: ubuntu-latest

    steps:
      - name: リポジトリをチェックアウト
        uses: actions/checkout@v6

      - name: Node.jsのインストール
        uses: actions/setup-node@v6
        with:
          node-version: 24.15.0

      - name: Corepackの有効化
        run: corepack enable

      - name: Corepackでpnpmのインストール
        run: corepack prepare pnpm@10.33.2 --activate

      - name: pnpmの「store path」を取得
        id: pnpm-store
        run: echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_OUTPUT

      - name: pnpmのキャッシュを取得
        uses: actions/cache@v5
        with:
          path: ${{ steps.pnpm-store.outputs.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-

      - name: .lockから依存関係をインストール
        run: pnpm install --frozen-lockfile

      - name: テスト「unit/integration」の実行
        run: pnpm test

  # e2e tests
  e2e-test:
    needs: changes
    if: github.ref == 'refs/heads/main' && needs.changes.outputs.app == 'true'
    runs-on: ubuntu-latest

    steps:
      - name: リポジトリをチェックアウト
        uses: actions/checkout@v6

      - name: Node.jsのインストール
        uses: actions/setup-node@v6
        with:
          node-version: 24.15.0

      - name: Corepackの有効化
        run: corepack enable

      - name: Corepackでpnpmのインストール
        run: corepack prepare pnpm@10.33.2 --activate

      - name: pnpmの「store path」を取得
        id: pnpm-store
        run: echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_OUTPUT

      - name: pnpmのキャッシュを取得
        uses: actions/cache@v5
        with:
          path: ${{ steps.pnpm-store.outputs.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-

      - name: .lockから依存関係をインストール
        run: pnpm install --frozen-lockfile

      - name: playwrightのブラウザをインストール
        run: pnpm exec playwright install --with-deps

      - name: テスト「e2e」の実行
        run: pnpm test:e2e

$ git add -A
$ git commit -m "add init"

$ pnpm test:e2e

$ pnpm test:e2e:ui

$ mkdir rails-aidd && cd rails-aidd
$ mkdir -p deploy/docker/local/db && touch deploy/docker/local/db/Dockerfile
$ mkdir -p deploy/docker/local/ruby && touch deploy/docker/local/ruby/Dockerfile
$ mkdir src && touch src/Gemfile src/Gemfile.lock
$ touch .env compose.yml .gitignore

FROM postgres:18.3

ENV LANG ja_JP.utf8

# PostgreSQLの日本語化で「ja_JP.utf8」を使うために必要
RUN apt-get update && \
    apt-get install -y locales && \
    rm -rf /var/lib/apt/lists/* && \
    localedef -i ja_JP -c -f UTF-8 -A /usr/share/locale/locale.alias ja_JP.UTF-8

FROM ruby:4.0.2-slim

RUN apt-get update -qq && \
    apt-get install -y --no-install-recommends \
      locales \
      build-essential \
      git \
      libpq-dev \
      libyaml-dev && \
    rm -rf /var/lib/apt/lists/*

RUN echo "ja_JP.UTF-8 UTF-8" > /etc/locale.gen && \
    locale-gen
WORKDIR /src

COPY src/Gemfile src/Gemfile.lock .

# bundlerのバージョンは固定して実行
RUN gem install bundler -v 4.0.10
RUN bundle _4.0.10_ install

COPY ./src /src

EXPOSE 3000

source 'https://rubygems.org'
gem 'rails', '8.1.3'

ENV=local
RAILS_ENV=development
TZ=Asia/Tokyo
LANG=ja_JP.UTF-8
LC_ALL=ja_JP.UTF-8
PORT=3000
DB_HOST=db
DB_USER=root
DB_PASSWORD=root

services:
  app:
    container_name: rails-app
    build:
      context: .
      dockerfile: ./deploy/docker/local/ruby/Dockerfile
    command: bash -c "rm -f tmp/pids/server.pid && bundle exec rails s -b 0.0.0.0 -p 3000"
    volumes:
      - ./src:/src
    ports:
      - "3000:3000"
    env_file:
      - .env
    tty: true
    stdin_open: true
    depends_on:
      db:
        condition: service_healthy
  db:
    container_name: rails-db
    build:
      context: .
      dockerfile: ./deploy/docker/local/db/Dockerfile
    environment:
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      TZ: ${TZ}
      # ローカル環境でもパスワードを有効化する設定
      POSTGRES_INITDB_ARGS: --auth-local=scram-sha-256 --auth-host=scram-sha-256
    volumes:
      - rails-db-data:/var/lib/postgresql
    ports:
      - "5432:5432"
    env_file:
      - .env
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER}"]
      interval: 5s
      timeout: 5s
      retries: 5
volumes:
  rails-db-data:

.DS_Store
.env

$ docker compose build --no-cache

$ docker compose run --rm app rails new . -d postgresql \
--css=tailwind \
--skip-action-mailer \
--skip-action-mailbox \
--skip-action-text \
--skip-active-storage \
--skip-action-cable \
--skip-jbuilder \
--skip-test \
--skip-system-test

$ docker compose run --rm app rm -r .git

・・・

group :development, :test do
  # See https://guides.rubyonrails.org/debugging_rails_applications.html#debugging-with-the-debug-gem
  gem "debug", platforms: %i[ mri windows ], require: "debug/prelude"

  # Audits gems for known security defects (use config/bundler-audit.yml to ignore issues)
  gem "bundler-audit", require: false

  # Static analysis for security vulnerabilities [https://brakemanscanner.org/]
  gem "brakeman", require: false

  # Omakase Ruby styling [https://github.com/rails/rubocop-rails-omakase/]
  gem "rubocop-rails-omakase", require: false

  # ERB用のlint
  gem "erb_lint", require: false

  # テストライブラリ
  gem "rspec-rails", require: false

  # テストデータ用
  gem "factory_bot_rails", require: false
end

・・・

# テスト用
group :test do
  gem "faker"
  gem "capybara"
  gem "selenium-webdriver"
  gem "webdrivers"
  gem "shoulda-matchers", require: false
end

・・・

module Src
  class Application < Rails::Application
    # Initialize configuration defaults for originally generated Rails version.
    config.load_defaults 8.1

    # Please, add to the `ignore` list any other `lib` subdirectories that do
    # not contain `.rb` files, or that should not be reloaded or eager loaded.
    # Common ones are `templates`, `generators`, or `middleware`, for example.
    config.autoload_lib(ignore: %w[assets tasks])

    # Configuration for the application, engines, and railties goes here.
    #
    # These settings can be overridden in specific environments using the files
    # in config/environments, which are processed later.
    #
    # config.time_zone = "Central Time (US & Canada)"
    # config.eager_load_paths << Rails.root.join("extras")

    # Don't generate system test files.
    config.generators.system_tests = nil

    # タイムゾーン設定
    config.time_zone = ENV.fetch("TZ", "UTC")
  end
end

・・・

default: &default
  adapter: postgresql
  encoding: unicode
  # For details on connection pooling, see Rails configuration guide
  # https://guides.rubyonrails.org/configuring.html#database-pooling
  max_connections: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
  # DB接続設定を追加
  host: <%= ENV.fetch("DB_HOST") { "localhost" } %>
  username: <%= ENV.fetch("DB_USER") { "postgres" } %>
  password: <%= ENV.fetch("DB_PASSWORD") { "password" } %>

・・・

production:
  primary: &primary_production
  <<: *default
  database: src_production
  # コメントアウト
  # username: src
  # password: <%= ENV["SRC_DATABASE_PASSWORD"] %>

・・・

$ docker compose build --no-cache

$ docker compose up -d

$ docker compose ps

$ docker compose exec app rails db:create

$ docker compose exec app rails g rspec:install

--require spec_helper
--color
--format documentation

・・・

module Src
  class Application < Rails::Application
    # Initialize configuration defaults for originally generated Rails version.
    config.load_defaults 8.1

    # Please, add to the `ignore` list any other `lib` subdirectories that do
    # not contain `.rb` files, or that should not be reloaded or eager loaded.
    # Common ones are `templates`, `generators`, or `middleware`, for example.
    config.autoload_lib(ignore: %w[assets tasks])

    # Configuration for the application, engines, and railties goes here.
    #
    # These settings can be overridden in specific environments using the files
    # in config/environments, which are processed later.
    #
    # config.time_zone = "Central Time (US & Canada)"
    # config.eager_load_paths << Rails.root.join("extras")

    # Don't generate system test files.
    config.generators.system_tests = nil

    # タイムゾーン設定
    config.time_zone = ENV.fetch("TZ", "UTC")

    # ジェネレーター設定
    config.generators do |g|
      g.test_framework :rspec
      g.fixture_replacement :factory_bot, dir: "spec/factories"
      g.view_specs false
      g.helper_specs false
      g.routing_specs false
      g.controller_specs false
      g.system_tests nil
    end
  end
end

# This file is copied to spec/ when you run 'rails generate rspec:install'
require 'spec_helper'
# RSpec実行時の環境変数「RAILS_ENV」の値が「test」になるように修正
# ENV['RAILS_ENV'] ||= 'test'
ENV['RAILS_ENV'] = 'test'

・・・

・・・

require 'rspec/rails'
# Add additional requires below this line. Rails is not loaded until this point!

# FactoryBot追加
require "factory_bot_rails"

RSpec.configure do |config|
  # Remove this line if you're not using ActiveRecord or ActiveRecord fixtures
  # fixtureの設定をコメントアウト
  # config.fixture_paths = [
  #   Rails.root.join('spec/fixtures')
  # ]

  # FactoryBotの設定を追加
  config.include FactoryBot::Syntax::Methods
・・・

$ docker compose restart app

$ docker compose exec app bundle exec rspec

・・・

require 'rspec/rails'
# Add additional requires below this line. Rails is not loaded until this point!

# FactoryBot追加
require "factory_bot_rails"

# shoulda-matchers追加
require "shoulda/matchers"

# capybara追加
require 'capybara/rspec'

・・・

RSpec.configure do |config|

〜

end

・・・

# shoulda-matchers設定追加
Shoulda::Matchers.configure do |config|
  config.integrate do |with|
    with.test_framework :rspec
    with.library :rails
  end
end

# capybara設定
Capybara.default_driver = :selenium_chrome_headless

$ docker compose run --rm app bundle exec rubocop -A --only Layout

$ docker compose run --rm app bundle exec rubocop

$ touch src/.erb_lint.yml

linters:
  ErbSafety:
    enabled: true

  FinalNewline:
    enabled: true

  TrailingWhitespace:
    enabled: true

$ docker compose run --rm app bundle exec erb_lint app/views

$ docker compose exec app bundle exec brakeman --no-pager

$ git init
$ git add -A
$ git commit -m "init"

$ brew install lefthook

$ lefthook install

pre-commit:
  parallel: true
  commands:
    rubocop_format:
      run: docker compose run --rm app bundle exec rubocop -A --only Layout
    rubocop_lint:
      run: docker compose run --rm app bundle exec rubocop
    erb_lint:
      run: docker compose run --rm app bundle exec erb_lint app/views
    brakeman:
      run: docker compose run --rm app bundle exec brakeman --no-pager

pre-push:
  commands:
    rspec:
      run: |
        docker compose up -d
        docker compose exec -T app rails db:prepare
        docker compose exec -T app bundle exec rspec

require "active_support/core_ext/integer/time"


Rails.application.configure do


・・・


# ログ出力にリクエストIDを追加
config.log_tags = [ :request_id ]

end

/my-project
 ├── /.codex
 |    ├── config.toml  ※codexに関する設定
 |    |
 |    ├── /rules  ※sandbox外で実行できるコマンド制御の設定
 |    |    └── default.rules
 |    |
 |    ├── /agents  ※サブエージェントを利用する場合の例
 |    |    ├── orchestrator.toml  ※指揮者（全体制御）
 |    |    ├── tester.toml        ※テスター（テストコード作成・検証）
 |    |    ├── implementer.toml   ※実装者（テストコードを通すように実装）
 |    |    └── reviewer.toml      ※レビュワー（設計や品質チェック）
 |    |
 |    ├── /workflows  ※ワークフローを利用する場合の例
 |    |    └── tdd_flow.md  ※TDD（テスト駆動開発）のフロー
 |    |
 |    └── /skills  ※Agent Skillsを利用する場合
 |
 ├── AGENTS.md  ※ルートディレクトリ用（共通ルール）
 |
 ├── /src
 |    └── AGENTS.md  ※サブディレクトリ用（専用ルール）
 |
 └── /docs  ※詳細仕様にファイル分割して格納（各種AGENTS.mdから指定する）
      └── /rules
           ├── architecture.md  ※設計思想のルール定義
           ├── database.md      ※DB設計のルール定義
           ├── sub.md           ※サブディレクトリ用のルール定義
           └── testing.md       ※テスト用のルール定義
 

$ mkdir .codex && touch .codex/config.toml

model = "gpt-5.2"
model_reasoning_effort = "medium"

sandbox_mode = "workspace-write"

[projects."対象のプロジェクトのフルパス"]
trust_level = "trusted"

$ mkdir -p .codex/rules && touch .codex/rules/default.rules

# --- ディスク破壊（即禁止） ---
prefix_rule(
    pattern=["mkfs", "dd if=", "wipefs"],
    decision="forbidden",
    justification="ストレージ破壊操作"
)

# --- Git履歴破壊（即禁止） ---
prefix_rule(
    pattern=["git push --force", "git push -f", "git push --force-with-lease"],
    decision="forbidden",
    justification="履歴改変（強制push）によるリポジトリ破壊の可能性"
)

# --- GitHub CLI 危険操作 ---
prefix_rule(
    pattern=["gh repo delete"],
    decision="forbidden",
    justification="リポジトリ削除（不可逆）"
)

prefix_rule(
    pattern=["gh pr merge --admin"],
    decision="prompt",
    justification="保護ルール無視の強制マージ"
)

prefix_rule(
    pattern=["gh workflow run"],
    decision="prompt",
    justification="CI/CDの強制実行"
)

prefix_rule(
    pattern=["gh secret set", "gh secret delete"],
    decision="prompt",
    justification="機密情報の変更"
)
# --- 危険削除（確認） ---
prefix_rule(
    pattern=["rm -rf", "sudo rm"],
    decision="prompt",
    justification="不可逆削除の可能性"
)

# --- 権限昇格 ---
prefix_rule(
    pattern=["sudo"],
    decision="prompt",
    justification="システム影響が大きい"
)

$ mkdir -p .codex/agents
$ touch .codex/agents/pm.toml .codex/agents/tester.toml .codex/agents/implementer.toml .codex/agents/reviewer.toml

name = "pm"
description = "全体の進行管理とタスク分解を行うプロダクトマネージャー"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"

developer_instructions = """
あなたは開発全体を指揮するプロダクトマネージャーです。

役割：
- 要件を整理し、タスクに分解する
- tester → implementer → reviewer の順でタスクを割り振る
- 各エージェントのアウトプットを評価し、次の行動を決める

ルール：
- 必ずTDDサイクル（RED → GREEN → REVIEW）を守る
- 不完全な実装は次に進めない
- 問題があれば前の工程に差し戻す

出力形式：
- 次に行動するエージェント名
- 依頼内容（具体的に）
"""

name = "tester"
description = "テストコード作成と動作検証を行うTDDエンジニア"
model_reasoning_effort = "high"
sandbox_mode = "workspace-write"

developer_instructions = """
あなたはTDDに従うテストエンジニアです。

役割：
- 仕様に基づいたテストコードを書く（RED）
- 実装後にテストを実行し検証する（GREEN）

ルール：
- まず失敗するテストを書く（RED）
- テストは仕様を正確に表現すること
- エッジケースも考慮する
- 実装コードは書かない

出力：
- テストコード
- テストの意図説明
"""

name = "implementer"
description = "テストを通すための実装を行うエンジニア"
model_reasoning_effort = "medium"
sandbox_mode = "workspace-write"

developer_instructions = """
あなたはTDDに従う実装エンジニアです。

役割：
- テストが通る最小限の実装を書く

ルール：
- テストを通すことを最優先
- 過剰な設計をしない（YAGNI）
- テストを書かない
- リファクタは必要最低限

出力：
- 実装コード
- 実装の簡単な説明
"""

name = "reviewer"
description = "仕様適合性・品質・セキュリティをレビューするエンジニア"
model_reasoning_effort = "high"
sandbox_mode = "read-only"

developer_instructions = """
あなたはコードレビュー担当です。

役割：
- 実装が仕様を満たしているか確認
- バグ・セキュリティ問題を検出
- テスト不足を指摘

観点：
- 正しさ（仕様通りか）
- セキュリティ
- 境界値・異常系
- テスト網羅性

ルール：
- 指摘は具体的に
- 再現手順を書く
- スタイル指摘は重要な場合のみ

出力：
- 指摘一覧（重要度付き）
- 修正提案
"""

$ mkdir -p .codex/workflows && touch .codex/workflows/tdd_flow.md

# TDD開発フロー

本フローは pm の指示を起点として進行するが、
各エージェントは自身の責務に従い独立して実行する。

---
1. pmが要件を整理し、タスクとして分解する
2. testerが失敗するテストを書く（RED）
3. implementerがテストを通す（GREEN）
4. testerがテスト結果を検証する
5. reviewerがレビューを行う
6. 問題があれば修正ループに戻る

---

## ルール

- REDなしで実装しない
- GREEN未達でレビューしない
- レビューNGなら再実装

$ mkdir -p .codex/skills/plan-to-issue && touch .codex/skills/plan-to-issue/SKILL.md
$ mkdir -p .codex/skills/plan-to-issue/references && touch .codex/skills/plan-to-issue/references/rules.md
$ mkdir -p .codex/skills/plan-to-issue/assets && touch .codex/skills/plan-to-issue/assets/template.md
$ mkdir -p .codex/skills/plan-to-issue/scripts && touch .codex/skills/plan-to-issue/scripts/create_issue.sh
$ chmod +x .codex/skills/plan-to-issue/scripts/create_issue.sh

---
name: plan-to-issue
description: プランモードで作成した開発計画をGitHubのIssue用のフォーマットへ変換して自動登録する
---

# plan-to-issue

## 概要
このスキルは、プランモードで作成された開発計画を読み込み、指定されたルールとテンプレートに従ってGitHub Issue用のフォーマットへ変換し、専用のスクリプトを用いてGitHubへ自動登録します。

## 参照ファイル
このスキルを実行する際は、以下のファイルを必ず読み込んで使用してください。

- **変換ルール定義**: `references/rules.md`
- 開発計画からIssueフォーマットへ変換する際のルールや抽出条件が記載されています。
- **出力フォーマット**: `assets/template.md`
- Issueの本文を作成するためのMarkdownテンプレートです。
- **実行用スクリプト**: `scripts/create_issue.sh`
- 作成したIssueデータをGitHubに登録するためのシェルスクリプトです。

## 入力
プランモードで生成された開発計画

## 出力
GitHub Issue（gh issue create により自動登録）

## 実行手順（ワークフロー）
以下のステップに従って処理を実行してください。

1. **開発計画の読み込み**
- 現在のプランモードで作成・合意された開発計画（タスク、目的、要件など）を確認します。

2. **変換ルール定義の読み込み**
- `references/rules.md` を読み込み、開発計画の内容をGitHub Issue用のフォーマットに変換するためのルールを理解します。

3. **出力フォーマットの読み込み、テンプレートの生成**
- `assets/template.md` を読み込み、開発計画の内容を変換ルールに基づいてテンプレートの構造に当てはめ、Issueの本文を生成します。

4. **Issueのタイトルを作成**
- 生成したIssueの本文の内容から、変換ルールに基づいてIssueのタイトルを作成します。

5. **GitHubのIssueを登録**
- `scripts/create_issue.sh` を利用し、作成したIssueのタイトルと本文をGitHubのIssueに登録します。

# 変換ルール定義（plan-to-issue）

このドキュメントは、プランモードで作成された開発計画をGitHub Issue用フォーマットへ変換するためのルールを定義する。

---

## 1. 基本方針

- 開発計画の内容を「1 Issue = 1目的（または1成果物）」の粒度で整理する
- 曖昧な記述は補完し、実行可能な形に正規化する
- 情報が不足している場合は、合理的に補完する（推測可）
- 冗長な説明は要約するが、重要な前提は保持する

---

## 2. フィールド対応ルール

開発計画の内容を以下のIssueテンプレートにマッピングする

### 2.1 概要（summary）
- 開発計画の「目的」「やること」を1〜3文で要約
- 実装内容ではなく「何を達成するか」を中心に記述
- 可能であれば動詞で開始する（例: 「〇〇を実装する」）

---

### 2.2 背景（background）
- なぜこの作業が必要なのかを記述
- 以下の情報を優先的に抽出
- 課題
- 現状の問題点
- ビジネス的/技術的な理由
- 明示されていない場合は、文脈から補完する

---

### 2.3 スコープ（scope）
- 対象範囲を明確化
- 含めるもの（In Scope）と含めないもの（Out of Scope）を整理
- 不明な場合は「暗黙のスコープ」を明文化する

例:
- 含む: API実装、UI変更
- 含まない: インフラ構築、リファクタリング全般

---

### 2.4 タスク（tasks）
- 実装手順をチェックリスト形式に分解
- 1タスク = 1アクション
- 粒度は「1〜3時間程度で完了できる単位」を目安に分割

#### タスク分解ルール
- 「設計」「実装」「テスト」「確認」を含める
- 抽象的な表現は禁止（例: 「いい感じに実装する」）
- 動詞で開始する（例: 「APIエンドポイントを作成する」）

#### 例
- [ ] APIのエンドポイントを定義する
- [ ] データモデルを作成する
- [ ] バリデーションを実装する
- [ ] 単体テストを追加する

---

### 2.5 受け入れ条件（acceptance_criteria）
- 完了とみなす条件を明確にする
- テスト可能・検証可能であることが必須

#### ルール
- 「〜できること」で記述
- 可能な限り具体的に書く
- 曖昧な表現は禁止（例: 「正常に動く」）

#### 例
- 正しいリクエストで200レスポンスが返ること
- 不正な入力時にバリデーションエラーが返ること
- UI上で新機能が操作できること

---

### 2.6 補足（notes）
- 以下の情報を含める
- 技術的な注意点
- 依存関係
- 未確定事項
- 将来対応

---

## 3. タイトル生成ルール

Issueタイトルは以下のルールで生成する

### フォーマット

[種別] 内容の要約

### 種別の分類
- feat: ユーザーに価値を提供する新機能
- fix: 不具合の修正
- refactor: 挙動を変えない内部改善
- docs: ドキュメントの追加・更新
- test: テストの追加・修正
- infra: インフラ・CI/CD・環境構築
- chore: 上記に当てはまらない雑務（極力使わない）

### ルール
- 30〜60文字程度に収める
- 内容が一目で分かるようにする
- summaryの内容をベースに生成する

例:
- feat: ユーザー登録APIを実装する
- fix: ログイン時の認証エラーを修正

---

## 4. Issue分割ルール

以下の場合は複数Issueに分割する

- 明確に独立した機能が複数存在する
- フロントエンドとバックエンドが分離可能
- 実装規模が大きすぎる（タスクが10個以上）

### 分割基準
- 各Issueが独立して完了可能であること
- 依存関係がある場合はnotesに記載

---

## 5. 不足情報の補完ルール

情報が不足している場合は以下に従う

- 文脈から合理的に推測する
- 推測した内容はnotesに明記する
- 重要な不確定要素は「要確認」として記載

---

## 6. 禁止事項

- 曖昧な表現（例: 適切に、いい感じに）
- 実行不可能なタスク分解
- 背景なしのIssue作成
- 受け入れ条件が検証不能な状態

---

## 7. 出力品質チェック

出力前に以下を確認する

- [ ] summaryが目的ベースになっている
- [ ] tasksが具体的で分解されている
- [ ] acceptance criteriaが検証可能である
- [ ] scopeが明確である
- [ ] タイトルが簡潔で分かりやすい

## 概要
{{summary}}

## 背景
{{background}}

## スコープ
{{scope}}

## タスク
- [ ] {{tasks}}

## 受け入れ条件
- {{acceptance_criteria}}

## 補足
{{notes}}

#!/usr/bin/env bash

set -euo pipefail

# ===============================
# Usage:
# ./create_issue.sh "タイトル" "本文"
# ===============================

TITLE="${1:-}"
BODY="${2:-}"

# タイトルと本文の入力チェック
if [[ -z "$TITLE" || -z "$BODY" ]]; then
  echo "Usage: $0 \"タイトル\" \"本文\""
  exit 1
fi

# gh コマンド存在チェック
if ! command -v gh &> /dev/null; then
  echo "gh コマンドが見つかりません"
  exit 1
fi

# GitHub認証チェック
if ! gh auth status &> /dev/null; then
  echo "GitHubにログインしていません"
  echo "gh auth login を実行してください"
  exit 1
fi

echo "Issueを作成中..."

# 一時ファイル作成
TMP_FILE=$(mktemp)

# 一時ファイルをスクリプト終了時に削除
trap 'rm -f "$TMP_FILE"' EXIT

# 本文を一時ファイルに書き込み
printf "%s" "$BODY" > "$TMP_FILE"

# Issue作成
gh issue create \
  --title "$TITLE" \
  --body-file "$TMP_FILE"

echo "Issue作成完了"

$ mkdir -p .codex/skills/auto-commit && touch .codex/skills/auto-commit/SKILL.md

$ mkdir -p .codex/skills/auto-pr && touch .codex/skills/auto-pr/SKILL.md
$ mkdir -p .codex/skills/auto-pr/assets && touch .codex/skills/auto-pr/assets/template.md
$ mkdir -p .codex/skills/auto-pr/scripts && touch .codex/skills/auto-pr/scripts/create_pr.sh
$ chmod +x .codex/skills/auto-pr/scripts/create_pr.sh

---
name: auto-pr
description: 直前のコミット内容をもとにPRタイトルと本文を生成し、GitHubのPR用フォーマットへ変換して自動登録する
---

# auto-pr

## 概要

このスキルは、直前のコミット内容をもとにPRタイトルと本文を生成し、GitHubのPR用フォーマットへ変換して自動登録します。

## 参照ファイル

このスキルを実行する際は、以下のファイルを必ず読み込んで使用してください。

- PRテンプレート: `assets/template.md`
- PR作成スクリプト: `scripts/create_pr.sh`

## 入力

直前のコミット情報

## 出力

GitHubのPR（gh pr create により自動登録）

---

## 実行手順

### 1. 直前のコミット情報と変更内容を取得する

```bash
git log -1 --pretty=format:"%h%n%s%n%b"
git show --no-color
```

- git log: 意図（タイトル・背景）
- git show: 変更内容（diff）

---

### 2. 解析して以下を生成する

- summary（概要）
- background（背景・目的）
- implementation（実装内容：箇条書き）
- test_items（テスト確認項目：チェックリスト形式）
- impact（影響範囲：箇条書き）
- future_work（未対応・今後の課題：箇条書き）

---

### 3. PR本文を生成する

`assets/template.md` を読み込み、以下ルールで置換する：

- {{summary}} → summary
- {{background}} → background
- {{implementation}} → implementation
- {{test_items}} → test_items
- {{impact}} → impact
- {{future_work}} → future_work

---

### 4. PRタイトルを生成する

フォーマット：

```text
auto: <summaryの短縮版>
```

---

### 5. PRを作成する

`scripts/create_pr.sh` を利用し、生成したPRタイトルと本文をGitHubのプルリクエストに登録します。

---

## 補足ルール

- implementation / impact / future_work は必ず箇条書きで出力する
- test_items はチェックリスト形式（- [ ]）で出力する
- diff（git show）を必ず参照し、推測のみで生成しない

## 概要
{{summary}}

## 背景・目的
{{background}}

## 実装内容
- {{implementation}}

## テスト確認項目
- [ ] {{test_items}}

## 影響範囲
- {{impact}}

## 未対応・今後の課題
- {{future_work}}

#!/usr/bin/env bash

set -euo pipefail

# ===============================
# Usage:
# ./create_pr.sh "タイトル" "本文"
# ===============================

TITLE="${1:-}"
BODY="${2:-}"

# タイトルと本文の入力チェック
if [[ -z "$TITLE" || -z "$BODY" ]]; then
  echo "Usage: $0 \"タイトル\" \"本文\""
  exit 1
fi

# gh コマンド存在チェック
if ! command -v gh &> /dev/null; then
  echo "gh コマンドが見つかりません"
  exit 1
fi

# GitHub認証チェック
if ! gh auth status &> /dev/null; then
  echo "GitHubにログインしていません"
  echo "gh auth login を実行してください"
  exit 1
fi

echo "PRを作成中..."

# 一時ファイル作成
TMP_FILE=$(mktemp)

# 一時ファイルをスクリプト終了時に削除
trap 'rm -f "$TMP_FILE"' EXIT

# 本文を一時ファイルに書き込み
printf "%s" "$BODY" > "$TMP_FILE"

# PR作成
gh pr create \
  --title "$TITLE" \
  --body-file "$TMP_FILE"

echo "PR作成完了"

/src
 └── /app
      ├── /controllers（コントローラー定義）
      |    |
      |    ├── /web
      |    |
      |    └── /api （将来的に利用する想定のAPIモード用）
      |
      ├── /models（アプリ全体の共通データ層・ActiveRecordモデル置き場）
      |
      ├── /views（Rails用のビュー）
      |
      ├── /domains（中核の業務領域・ドメイン駆動設計）
      |    |
      |    └── /[domain_name]
      |         |
      |         ├── /domain（ドメイン層）
      |         |    |
      |         |    ├── /entities（エンティティ）
      |         |    |
      |         |    ├── /value_objects（値オブジェクト）
      |         |    |
      |         |    ├── /services（ドメインサービス）
      |         |    |
      |         |    └── /repositories（リポジトリのインターフェース）
      |         |
      |         ├── /use_cases（ユースケース層）
      |         |
      |         └── /infrastructure（インフラストラクチャ層）
      |              |
      |              └── /repositories（リポジトリの実装）
      |                   |
      |                   ├── /command（書き込み）
      |                   |
      |                   └── /query（読み込み）
      |
      ├── /features（補完的な業務領域・トランザクションスクリプト）
      |    |
      |    └── /[feature_name]
      |         |
      |         └── /services（サービス層） 
      |
      ├── /resources（一般的な業務領域・アクティブレコード）
      |     ※例：user.rbやpayment_gateway.rbなどを置く
      |
      └── /shared（横断関心）

$ mkdir -p docs/rules
$ touch docs/rules/architecture.md docs/rules/database.md
$ touch docs/rules/boundaries.md docs/rules/rails.md docs/rules/testing.md
$ touch src/AGENTS.md AGENTS.md

# アーキテクチャ設計のルール定義

## 概要
本プロジェクトはRailsベースのモジュラーモノリス構成かつドメイン駆動設計（DDD）を採用し、業務の複雑さと表現力に応じて以下の3層に分離します。

- 中核の業務領域 → ドメイン駆動設計（DDD）→ domains
- 補完的な業務領域 → トランザクションスクリプト → features
- 一般的な業務領域 → アクティブレコード（単純なCRUD） → resources

---

## ディレクトリ構造の前提

```
/src
 ├── /app
 |    ├── /controllers（コントローラー定義）
 |    |    |
 |    |    ├── /web
 |    |    |
 |    |    └── /api （将来的に利用する想定のAPIモード用）
 |    |
 |    ├── /models（アプリ全体の共通データ層・ActiveRecordモデル置き場）
 |    |
 |    ├── /views（Rails用のビュー）
 |    |
 |    ├── /domains（中核の業務領域・ドメイン駆動設計）
 |    |    |
 |    |    └── /[domain_name]
 |    |         |
 |    |         ├── /domain（ドメイン層）
 |    |         |    |
 |    |         |    ├── /entities（エンティティ）
 |    |         |    |
 |    |         |    ├── /value_objects（値オブジェクト）
 |    |         |    |
 |    |         |    ├── /services（ドメインサービス）
 |    |         |    |
 |    |         |    └── /repositories（リポジトリのインターフェース）
 |    |         |
 |    |         ├── /use_cases（ユースケース層）
 |    |         |
 |    |         └── /infrastructure（インフラストラクチャ層）
 |    |              |
 |    |              └── /repositories（リポジトリの実装）
 |    |                   |
 |    |                   ├── /command（書き込み）
 |    |                   |
 |    |                   └── /query（読み込み）
 |    |
 |    ├── /features（補完的な業務領域・トランザクションスクリプト）
 |    |    |
 |    |    └── /[feature_name]
 |    |         |
 |    |         └── /services（サービス層） 
 |    |
 |    ├── /resources（一般的な業務領域・アクティブレコード）
 |    |     ※例：user.rbやpayment_gateway.rbなどを置く
 |    |
 |    └── /shared（横断関心）
 |
 └── /spec（テストコード）
```

---

## レイヤー構成の定義

### domains（中核の業務領域 / ドメイン駆動設計）

事業の本質的価値を生み出す領域

#### 特徴

- 業務ルールが複雑で変化しやすい
- 意思決定ロジックの中心
- ビジネス競争力に直結する領域
- ドメインモデルが重要になる

#### 設計原則（DDD適用）

- 集約・エンティティ / 値オブジェクト / ドメインサービスを適用する
- ビジネスルールをコードとして明示的に表現する
- 副作用を最小化する
- 可能な限り純粋ロジックとして設計する

#### 構造

- [domain_name]
  - domain（ドメイン層）
    - entities（エンティティ）
    - value_objects（値オブジェクト）
    - services（ドメインサービス）
    - repositories（リポジトリのインターフェース）
  - use_cases（ユースケース層）
  - infrastructure（インフラストラクチャ層）
    - repositories（リポジトリの実装）
      - command（書き込み）
      - query（読み取り）

#### 例

- 与信判断
- 価格最適化
- 予約枠管理
- 配送ルート最適化

---

### features（補完的な業務領域 / トランザクションスクリプト）

中核業務を支える周辺処理領域

#### 特徴

- 業務ルールは存在するが比較的単純
- 処理の流れ（手続き）が中心
- 複数処理や外部処理の調整役

#### 設計原則

- トランザクションスクリプトとしてサービス層に実装する
- ユースケース単位で記述する
- トランザクション境界はサービス層で明確に管理する
- シンプルなデータ操作に限定し、複雑なロジックは持ち込まない
- 可読性を優先し、副作用や永続化は明示的に分離する
- 複雑化・肥大化した場合はdomainsへ移行する

#### 構造

- [feature_name]
  - services（サービス層）

#### 例

- 注文後メール送信
- ポイント付与
- 在庫減算処理
- 単純な承認フロー

---

### resources（一般的な業務領域 / アクティブレコード）

業務固有性が低いデータ管理領域

#### 特徴

- CRUD中心の処理
- ビジネスルールが薄い
- データの保存・取得が主目的

#### 設計原則

- ActiveRecordベースで十分表現可能
- インフラ寄りの扱い
- 業務判断を持たない

#### 構造

- [resource_name.rb]

#### 例

- ユーザー基本情報
- マスターデータ（カテゴリ・都道府県など）
- ログ
- 設定情報

---

## shared（横断関心）

全レイヤーから参照可能な共通処理

### 例

- /utils
- /constants
- /types
- /errors
- /validators
- /formatters
- /time
- /pagenation

---

## models（データ層 / ActiveRecord集約層）

- 全てのActiveRecordのモデルはここに集約する
- データアクセスの唯一の責務を持つ
- 業務ロジックは禁止
- 各レイヤーから利用される基盤層

---

## 依存関係

### 呼び出し方向（実行フロー）

- controller → domains/use_cases または features/services または resources
- domains/use_cases → repositories → models
- features/services → models
- resources → models
- shared （全レイヤーから参照可能）

---

## 基本原則

- controller：HTTPリクエストの受け取り、ユースケースの呼び出し専用
- domains：中核の業務領域、複雑で競争優位性が高いビジネスをここに集約
- features：補完的な業務領域、単純で競争優位性を生み出さないビジネスをここに集約
- resources：一般的な業務領域、複雑だが競争優位性を生み出さずに共通の仕組みを利用するビジネスをここに集約
- shared：横断関心、各レイヤーから利用可能な共通の処理を集約
- models：データ層

---

## 設計判断基準

設計する際の分類基準は以下の通り：

- ルールやビジネスロジックが複雑になり、破綻しやすいもの → domains
- ルールが薄く、単純であり、処理フロー中心のもの → features
- 単純なCRUD処理や、共通の外部サービスを利用するもの → resources

---

## その他の重要ルール

- controllerは直接modelsを呼び出して操作しない
- controllerは必ずユースケース層を経由する
- レイヤー内部の実装詳細は外部から呼ばない

# データベース設計のルール定義

## 基本方針

- ActiveRecordを唯一のORMとして使用する
- DBは永続化の責務のみを持つ

---

## モデル設計

- 全モデルは src/app/models に集約する
- ビジネスロジックは禁止
- scopeは軽量クエリのみ許可

---

## スキーマ設計

- 破壊的変更を避ける
- NULL制約・外部キー制約を積極的に使用
- インデックスは用途ベースで設計する

---

## 禁止事項

- DBに業務ルールを持たせない
- fat model禁止

# コード配置のルール定義・境界ルール定義

## 目的

業務重要度と役割に応じてコードの配置場所を決定する。

---

## ディレクトリ構造の前提

```
/src
 ├── /app
 |    ├── /controllers（コントローラー定義）
 |    |    |
 |    |    ├── /web
 |    |    |
 |    |    └── /api （将来的に利用する想定のAPIモード用）
 |    |
 |    ├── /models（アプリ全体の共通データ層・ActiveRecordモデル置き場）
 |    |
 |    ├── /views（Rails用のビュー）
 |    |
 |    ├── /domains（中核の業務領域・ドメイン駆動設計）
 |    |    |
 |    |    └── /[domain_name]
 |    |         |
 |    |         ├── /domain（ドメイン層）
 |    |         |    |
 |    |         |    ├── /entities（エンティティ）
 |    |         |    |
 |    |         |    ├── /value_objects（値オブジェクト）
 |    |         |    |
 |    |         |    ├── /services（ドメインサービス）
 |    |         |    |
 |    |         |    └── /repositories（リポジトリのインターフェース）
 |    |         |
 |    |         ├── /use_cases（ユースケース層）
 |    |         |
 |    |         └── /infrastructure（インフラストラクチャ層）
 |    |              |
 |    |              └── /repositories（リポジトリの実装）
 |    |                   |
 |    |                   ├── /command（書き込み）
 |    |                   |
 |    |                   └── /query（読み込み）
 |    |
 |    ├── /features（補完的な業務領域・トランザクションスクリプト）
 |    |    |
 |    |    └── /[feature_name]
 |    |         |
 |    |         └── /services（サービス層） 
 |    |
 |    ├── /resources（一般的な業務領域・アクティブレコード）
 |    |     ※例：user.rbやpayment_gateway.rbなどを置く
 |    |
 |    └── /shared（横断関心）
 |
 └── /spec（テストコード）
```

---

## レイヤー定義

### app/controllers（コントローラー）

- HTTPリクエストを受け取り、レスポンスを返すための薄いレイヤー
- パラメータの受け取り・バリデーション・認証/認可の入口を担う
- ユースケース層（app/domains/*/use_cases or app/features/*/services or app/resources/*）を呼び出す
- 業務ロジックは持たない（持ってはいけない）
- レスポンス整形（JSON / HTML）は行うが、ビジネス判断は行わない

#### 依存ルール

- controllers → ユースケース（app/domains/*/use_cases or app/features/*/services or app/resources/*）
- controllers → views（HTMLの場合）

---

### app/models（データ層 / ActiveRecordモデル置き場）

- ActiveRecordベースのDBテーブルとのマッピングを担う
- スキーマ表現・リレーション・スコープなどの永続化に近い関心を持つ
- コールバックやロジックは極力最小限に抑える
- ドメイン層から直接使わず、Infrastructure層経由で利用するのが基本
- 「Fat Model」にしない（ビジネスロジックはドメインへ）

#### 依存ルール

- models ← infrastructure（repositoryなど）

---

### app/views（Rails用のビュー）

- HTMLテンプレートの描画を担う
- 表示ロジック（フォーマット・簡単な条件分岐）のみ許容
- 業務ロジックやドメイン知識は持たない
- instance変数はcontrollerから受け取る

#### 依存ルール

- views ← controllers

---

### app/domains（中核の業務領域 / ドメイン駆動設計）

- アプリケーションの最も重要なビジネスロジックを集約
- 境界づけられたコンテキスト（= domain_name）単位で分割

#### domain/entities

- 同一性（ID）を持つオブジェクト
- ビジネスルール・不変条件を保持
- 永続化手段（ActiveRecordなど）に依存しない

#### domain/value_objects

- 不変オブジェクト
- 値による等価性で比較される
- ドメインルールを内包可能（例：金額、メールアドレス）

#### domain/services

- エンティティやVOに属さないドメインロジック
- 複数のエンティティにまたがるビジネスルールを表現

#### domain/repositories

- リポジトリのインターフェース定義
- 実装部分はinfrastructure/repositoriesで行う
- コマンド・クエリ責務分離（CQRS）設計とし、command（書き込み）とquery（読み取り）に分ける

#### use_cases

- アプリケーションのユースケース単位の処理
- トランザクション境界を管理
- ドメインオブジェクトを組み合わせて処理を実行
- 外部I/F（repositoryなど）はインターフェース経由で利用

#### infrastructure/repositories

- 永続化の具体実装
- ActiveRecord（app/models）を利用してDBアクセスを行う
- ドメイン層に定義されたRepositoryインターフェースを実装
- 外部APIや他システム連携もここに含めてよい

#### 依存ルール

- domain層は他のレイヤーに依存しない
- use_casesはdomainに依存するが、infrastructureの詳細には依存しない（DI前提）
- infrastructureはdomainに依存してよい

---

### app/features（補完的な業務領域 / トランザクションスクリプト）

- ドメインとして切り出すほどではないが、機能としてまとまりがある処理
- シンプルな業務ロジックを扱う
- サービスとして実装する

#### services

- 1サービス1ユースケースとして表現
- ActiveRecord（app/models）を直接利用してよい
- 複雑化したらdomainsへ昇格させる前提

#### 位置づけ

- 軽量なユースケース層
- DDDの厳密さを求めない代わりにスピードを優先

#### 依存ルール

- features → models はOK
- features → domains は原則避ける

---

### app/resources（一般的な業務領域 / アクティブレコード）

- 単純なCRUD処理など、共通の仕組みを利用するような処理

#### 例

- ActiveRecordベースのシンプルなCRUD処理
  - 例：User、PaymentGatewayなど
- 外部サービスのような共通の仕組みを利用する単純な処理
- ビジネスルールが薄い処理

#### 役割

- ドメインに昇格しないActiveRecordベースの共通処理置き場

---

### app/shared（横断関心）

- 全レイヤーから参照可能な共通処理

#### 例

- /utils
- /constants
- /types
- /errors
- /validators
- /formatters
- /time
- /pagenation

---

### spec（テストコード）

#### 基本方針

- レイヤーごとに責務に応じたテストを行う
- 下位レイヤーほど高速・純粋、上位レイヤーほど統合的に検証する
- 「どこで何を保証するか」を明確にし、テストの重複を避ける
- ビジネスロジックは domainsで担保する（他レイヤーで重複して検証しない）

---

#### 主な分類

- controllers：インテグレーションテスト → リクエストスペック
  - HTTPリクエスト/レスポンスの検証（ステータスコード、JSON構造など）
  - 認証・認可の動作確認
  - ユースケースが正しく呼ばれていることの間接確認
  - 業務ロジックの詳細までは検証しない
  - 可能な限りモックを使わず、実際のスタックに近い形で検証する

- models：ユニットテスト → モデルスペック
  - スコープ・バリデーション・リレーションの検証
  - DBに近い振る舞い（クエリ結果など）の確認
  - コールバックは必要最小限にし、テストも最小限に留める
  - ビジネスロジックはテストしない（domainで担保）

- views：E2Eテスト → システムスペック
  - ユーザー操作を通した画面表示の検証
  - フォーム入力〜結果表示までの一連のフロー確認
  - 表示崩れや重要なUI要素の存在確認
  - 細かい文言やHTML構造には依存しすぎない
  - JavaScriptを含む挙動もここで検証

- domains：ユニットテスト
  - ビジネスルール・不変条件の検証
  - エンティティ・ValueObject・ドメインサービスの振る舞い確認
  - 外部依存（DB・API）は排除し、純粋なオブジェクトとしてテスト
  - 境界値・異常系を重点的にテストする
  - 最も網羅的かつ信頼できるテスト層

- features：インテグレーションテスト
  - Request Specを利用
  - サービス単位でのユースケース検証
  - ActiveRecordを含めた一連の処理の動作確認
  - 複雑な分岐や副作用（レコード作成・更新）を検証
  - controller経由 or 直接サービス呼び出しのどちらでもよい
  - domainに昇格すべきロジックが混ざっていないかの検知にも使う

- resources：E2Eテスト
  - API：request spec（統合テスト） / View：system spec（E2Eテスト）
    - API：クライアント視点でリクエストの連携が成立することを担保
    - View：ユーザー操作として一連の体験が成立することを担保
  - 主要なフロー（登録 → 認証 → 操作）の検証
  - 認証・認可・決済など横断的関心の動作確認
  - クライアント視点でAPIが正しく連携できることを担保
  - 成功パターンを中心に最小限のケースに絞る
  - 詳細なバリデーションや分岐ロジックは下位レイヤーで担保

---

#### 補足ポリシー

- ドメイン層は最速で実行できるテストにする（DBアクセス禁止）
- インフラ層（repositoryなど）は必要に応じて統合テストを行う
- モックは「外部境界」に限定して使用する（DB・外部APIなど）
- テストが壊れやすい構造（過度なモック、内部実装依存）を避ける
- 迷った場合は「その責務はどのレイヤーか」に立ち返って配置する

---

## ユースケース呼び出しルール

- controllerは各レイヤーに定義されたユースケースのみ呼び出す。
- 内部実装やモデルは直接呼ばない。

### 例

- domains/use_casesのユースケース
- features/servicesのユースケース
- resourcesのユースケース

---

## 配置判断基準

- HTTP処理 → controllers
- ActiveRecordモデル（永続化） → models
- 画面表示 → views
- ビジネスルール（純粋ロジック） → domains
- ユースケースの流れ制御 → features
- DBに対する単純操作（ロジックなし） → resources
- 共通処理 → shared

---

## 禁止事項

- domainsにCRUDロジックを混ぜる
- controllerに業務ロジックを書く
- レイヤー内部を直接呼び出す

# Rails実装のルール定義

モジュラーモノリス + ドメイン駆動設計（DDD）を併用する

## 1. 目的

本ドキュメントはRailsにおける実装ルールを定義する。

アーキテクチャ判断は `architecture.md` と `boundaries.md` に従い、
本書は「Railsコードの書き方・制約」に特化する。

---

## 2. 基本原則

### 2-1. controllersは薄くする

- HTTP入出力のみ担当
- 業務ロジック禁止
- 必ずユースケース層を呼び出す

#### 許可される処理

- パラメータ取得
- 認証・認可の入口処理
- ユースケースの呼び出し
- レスポンス整形

#### 禁止

- 条件分岐による業務判断
- DB操作
- ドメインロジック

---

### 2-2. modelsは永続化専用

- ActiveRecordはデータ層として扱う
- ビジネスロジック禁止
- scope・validation・associationのみ許可

#### 禁止

- 業務ルール
- 計算ロジック
- ドメイン判断

---

### 2-3. domainsは純粋な業務ロジック

- ActiveRecordに依存しない
- 不変条件を保証する
- 副作用を外に出す

#### 特徴

- エンティティ
- 値オブジェクト
- ドメインサービス

---

### 2-4. domainsのuse_caseはアプリケーション制御

- トランザクション境界を持つ
- domainを組み合わせる
- repository経由でデータアクセス

#### 禁止

- UIロジック
- ActiveRecord直接操作（原則）

---

### 2-5. featuresは軽量ユースケース

- 単純な業務フローを扱う
- ActiveRecord利用OK
- 複雑化したらdomainへ移行

---

### 2-6. resourcesはCRUD専用

- 単純なデータ操作のみ
- ビジネス判断を持たない
- マスタ・設定・ログなど

---

## 3. 依存ルール

### 基本方針

依存は一方向のみ（上位 → 下位）

---

### 3-1. controllers

- controllers → domains/[domain_name]/use_cases
- controllers → features/[feature_name]/services
- controllers → resources

#### ルール

- controllerは業務判断を持たない
- HTTP入出力のみに責務を限定する
- domains/[domain_name] / features/[feature_name] / resourcesのどれを呼ぶかの判断のみ行う

---

### 3-2. models

- models（ActiveRecordのモデルを集約） → DB永続化専用

---

### 3-3. domains（中核の業務領域）

#### domain/*

- domains/*/domain → 無依存（完全独立）
- repositories
- domains/*/domain/repositories（interface）はインターフェース定義のみ
- 実装はdomains/*/infrastructure/repositories（implementation）

#### use_cases

- domains/*/use_cases → domains/*/domain
- domains/*/use_cases → domains/*/domain/repositories（interface）

#### infrastructure

- リポジトリの実装を行う
- domains/*/infrastructure/repositories（implementation） → models
- コマンド・クエリ責務分離（CQRS）設計とし、command（書き込み）とquery（読み取り）に分ける

---

### 3-3. features（補完的な業務領域）

- features/*/services → models

#### ルール

- 単純な業務フローのみ扱う
- 複雑化した場合はdomainsへ移行

---

### 3-4. resources（一般的な業務領域）

- resources → models

#### ルール

- 単純なCRUD処理
- ビジネスロジック禁止

---

### 3-5. shared（横断関心）

- shared → 全レイヤーから参照可能

---

### 3-6. 全体制約

#### domainの絶対ルール

- domainはRailsに依存しない
- domainはActiveRecordを知らない
- domainは純粋なビジネスロジックのみ

#### infrastructureルール

- infrastructure（repositories実装）はmodelsに依存する
- コマンド・クエリ責務分離（CQRS）設計とする

---

### 依存方向まとめ

#### 中核の業務領域

```
controller
↓
domains/*/domain/use_cases 
↓
domain（entities / value_objects / services / repositories（interface））
↓
infrastructure/repositories（implementation）
↓
models（ActiveRecord実装）
```

#### 補完的な業務領域

```
controller
↓
features/*/services
↓
models（ActiveRecord実装）
```

#### 一般的な業務領域

```
controller
↓
resources
↓
models（ActiveRecord実装）
```

#### 共通処理

sharedは例外的に全方向参照可能

---

## 4. Rails特有の制約

### ActiveRecordの扱い

- domainsからは直接参照せず、repository経由でのみアクセスする
- featuresやresourcesは直接参照可能
- modelは純粋なデータ表現

---

### repositoryの責務分離（CQRS）

- Query Repository（読み取り専用）
  - データ取得
  - キャッシュ利用可能
  - パフォーマンス最適化OK
  - domainロジック禁止

- Command Repository（書き込み専用）
  - 作成・更新・削除
  - トランザクション管理の対象
  - domainルールの反映

---

### コールバック禁止方針

- callbackに業務ロジックを書かない
- 副作用はユースケースに集約する

---

### Fat Model禁止

- modelにロジックを集約しない
- 複雑化した場合はドメインモデルへ移動

---

## 5. トランザクション管理

- ユースケース層が唯一のトランザクション境界
- featuresでは必要最小限にし、以下に該当したらdomainsへ移行する
  - 条件分岐が増える
  - 状態遷移（ステータス変更ロジック）が含まれる
  - 複数のドメインルールが絡む
  - ルール変更の影響範囲が広い
  - ビジネス判断がコード内に現れ始める
- modelでは管理しない

---

## 6. 例外ルール

### 許可される例

- modelのバリデーション
- scopeによるクエリ
- 軽量なフォーマット処理（表示用途）

---

### 禁止される例

- 金額計算などの業務ロジック
- 状態遷移の判断
- 複雑な条件分岐

---

## 7. 設計判断基準

実装前に必ず判断する：

### 7-1. Q1: 複雑な業務ルールがあるか？

→ domains

### 7-2. Q2: 複雑な業務ルールはなく、処理フロー中心か？

→ features

### 7-3. Q3: 単純なCRUD処理や、外部サービスなどの共通処理か？

→ resource

### 7-4. Q4: 各レイヤーで共通利用するものか？

→ shared

---

## 8. エージェントルール

- 実装前に必ず配置先を決める
- controllerから設計を始めない
- domains または features または resource から設計を始める
- 判断に迷った場合は `boundaries.md` を参照すること

---

## 9. 禁止事項

- controllersへのロジック追加
- model肥大化
- domainsでの直接のActiveRecord使用
- featuresの無制限増殖
- ルールを無視した直書き実装

# テストのルール定義

## 1. 基本方針

### 責務とテストの一致

- テストの責務境界をコード構造と一致させる
- 各レイヤーの責務 ＝ テストの責務
- 「どこで何を保証するか」を明確にする
- 同一ロジックの重複検証は禁止

---

### テストピラミッド

- E2E（web / api）：少量
- Integration（domains / features / resources）：中量
- Unit（domains）：最大（最も厚くする）
- requests（コントローラーのHTTPテスト）やE2Eは「壊れていないことの確認」に留める

---

### ビジネスロジックの責務

ビジネスロジックは性質ごとに責務を分離し、適切なレイヤーに集約する。

#### domains

- ビジネスの不変ルール（ドメイン知識そのもの）を担当する
- 例：計算ロジック、状態遷移の正当性、制約条件
- システムの「正しさの核」を担う

#### features

- ユースケース単位のビジネスフローおよび軽い判断ロジックを担当する
- 例：複数ドメインをまたぐ処理順序、条件分岐による処理選択
- ドメインルールそのものは持たず、オーケストレーションとアプリケーション判断を担う
- ドメインを利用しない範囲のユースケースを担当する

#### resources

- 単純CRUDなどの標準的なリソース操作を担当する
- ビジネス判断ロジックは持たず、処理の流れの確認に留める

#### 配置判断ルール

- 判断や分岐を伴う場合は features に配置する
- 判断を伴わない単純なCRUDは resources に配置する
- 複雑なビジネスルールが含まれる場合は domains に配置する

#### controllers / models

- ビジネスロジックは持たない
- controllers は I/O のみ
- models は永続化とデータ構造の表現のみに限定する

#### 上位レイヤーの責務

- 上位レイヤーは下位レイヤーの正しさに依存する
- ビジネスルールそのものは domains または features に集約する

### ActiveRecordの位置づけ

- models は永続化モデル（ORM）でありドメインではない
- ビジネスロジックは持たない
- データ構造の表現のみに限定する

---

## 2. specのディレクトリ構成

Railsのテストフレームワークとして「RSpec」を利用するが、`/spec`のテストとしては責務ベースでディレクトリを分離し、ドメイン駆動設計およびモジュラーモノリスの境界と一致させる。

### 基本方針

- レイヤー（unit / integration / requests / e2e）で大分類する
- その中で責務（domains / features / resourcesなど）を分割する
- ドメイン単位での分離を最優先する
- テストの配置はコードの責務境界と一致させる

---

### ディレクトリ構成

```
/spec
 ├── /unit（ユニットテスト）
 |    |
 |    ├── /models
 |    |
 |    ├── /domains
 |    |    |
 |    |    └── /domain_name
 |    |         |
 |    |         ├── /domain
 |    |         |    |
 |    |         |    ├── /entities
 |    |         |    |
 |    |         |    ├── /value_objects
 |    |         |    |
 |    |         |    └── /services
 |    |         |
 |    |         └── /use_cases
 |    |
 |    └── /shared
 |
 |
 ├── /integration（インテグレーションテスト）
 |    |
 |    ├── /domains
 |    |    |
 |    |    └── /domain_name
 |    |         |
 |    |         └── /use_cases
 |    | 
 |    ├── /features
 |    |    |
 |    |    └── /[feature_name]
 |    |         |
 |    |         └── /services（サービス層） 
 |    |
 |    | 
 |    └── /resources
 |
 |
 ├── /requests（コントローラーのHTTPのテスト）
 |    |
 |    ├── /web
 |    |
 |    └── /api（将来的にAPIモードを利用する際に使う想定）
 |
 |
 └── /e2e（E2Eテスト）
      |
      ├── /web
      |
      └── /api（将来的にAPIモードを利用する際に使う想定）
```

---

### 設計意図

#### unit

- models / domains / shared を明確に分離する
- domainsについてはドメインロジックの純粋性を保証する層とする
- domains配下はDDD構造そのものを反映し、純粋なビジネスロジックのみを対象とする

#### integration

- 複数コンポーネントの結合を検証する層
- ドメイン単体などではなく、ユースケースなどの「流れ」を保証する
- featuresは業務機能単位の統合境界として扱う
- HTTPは使用しない（Request Specは禁止）
- サービス・ユースケースを直接呼び出して検証する

#### requests

- HTTP境界の検証に限定する
- Rails controllerの責務確認を目的とする
- ビジネスロジックは一切持たず、入出力の正当性のみを保証する

#### e2e

- ユーザー視点の最終保証レイヤー
- UI / APIを含めた全体フローを確認する
- カバレッジよりも主要シナリオの成立を重視し、最小限に保つ

---

### 命名ルール

- domain_name / feature_name はアプリケーションの業務ドメイン用語を使用する
- 実装クラス名ではなく「業務単位」でディレクトリを切る
- ディレクトリ構造とモジュール境界は一致させることを前提とする

### 補足ルール

- 同一責務のテストは必ず1箇所に集約する
- unit / integration / e2e 間で同じ検証を重複させない
- domains配下が最も安定した設計境界となることを前提とする

---

## 3. レイヤー別テスト定義

### domains（中核の業務領域のレイヤー）

**方針**: 最も重要なテスト層。全ビジネスルールを保証

**ルール**
- ドメインモデル（VO / Entity / Domain Service）は Unit テストで保証する
  - 原則: 純粋ロジック（DB/HTTPなし）
  - 通常は `require "rails_helper"` を使用してよい
  - 高速化したい場合は `require "spec_helper"` のみで実行してよい
- ドメインのユースケースは Integration テストで「処理の流れ」を保証する
  - `require "rails_helper"` の利用を許可する
  - 必要に応じて ActiveRecord/DB を使ってよい（I/O込みの結合検証）
- 同一ロジックの重複検証は禁止（どこで何を保証するかを明確にする）

**必須**
- 境界値テスト
- 異常系テスト
- 不変条件の検証
- 1テスト1ルール

**禁止（Unit に限定）**
- ActiveRecord使用
- FactoryBot使用

---

### features（補完的な業務領域のレイヤー）

**方針**: ユースケースの流れを検証、ドメインを使うような複雑性はない機能の動作確認

**ルール**
- Integrationテスト
- DB使用可
- サービス単位で検証

**必須**
- 1ユースケースにつき
  - 正常系1つ
  - 主要な失敗系のみ

**禁止**
- 複雑な検証
- 分岐網羅
- 過剰なモック

---

### resources（一般的な業務領域のレイヤー）

**方針**: 単純なCRUD処理などを検証

**ルール**
- APIは Request Spec（統合テスト）、Viewは System Spec（E2Eテスト） を使用する
- 1つのリソースにつき「代表的な正常系フロー」を中心に検証する
- CRUDは個別に網羅するのではなく、「一連の操作の流れの中で確認する」
- 認証・認可・決済などの横断的関心を含めて検証する
- テストはクライアント（API）またはユーザー（View）視点で記述する
- ビジネス判断を持たないことを前提とする
- 判断が発生した時点で features へ移動する

**必須**
- 登録 → 認証 → 操作 などの主要フローが成立すること
- 認証・認可が正しく機能すること（未認証・権限違いの最低限の確認）
- リソースの作成・更新・削除のうち、少なくとも1つはフロー内で通すこと
- 正常系のエンドツーエンド動作が通ること

**禁止**
- バリデーションの網羅的テストを書くこと
- 分岐ロジック（条件ごとの挙動）を細かく検証すること
- すべてのCRUDパターンをE2Eで個別にテストすること
- 失敗ケースを過剰に書くこと（詳細は下位レイヤーで担保）
- テストケースを増やしすぎること（フロー単位で最小限に抑える）

---

### models（永続化レイヤー）

**方針**: DB構造と永続化のみ保証

**ルール**
- Model Specを使用
- DB前提

**検証対象**
- validation
- association
- scope
- simple callback（最小限）

**必須**
- DBとの整合性
- クエリ結果の正しさ

**禁止**
- ビジネスロジック
- 複雑ロジック
- ドメイン知識

---

### controllers

**方針**: I/Oのみ検証

**ルール**
- Request Specを使用
- HTTPステータス
- JSON構造
- 認証・認可

**必須**
- レスポンススキーマのみ検証

**禁止**
- ビジネスロジックの結果検証
- DB状態の詳細検証

---

### views（UI）

**方針**: ユーザー体験のみ確認

**ルール**
- System Spec（E2E）を使用
- 主要フローのみ

**必須**
- 文言完全一致に依存しない
- HTML構造に依存しすぎない

---

## 4. 横断ルール

### ４.1 責務ごとのテスト配置

| 検証対象 | 配置場所 |
|----------|----------|
| 複雑なビジネスルール | domains |
| ビジネスフロー（ユースケース） | features |
| 単純なCRUD・リソース操作 | resources |
| DB構造・バリデーション | models |
| API入出力（HTTP境界） | controllers（request spec） |
| UI体験（ユーザー操作） | views（system spec） |

- 同一内容の重複テストは禁止

---

### ４.2 モック使用ルール

**許可**
- 外部API
- 時刻
- UUID
- メール送信

**禁止**
- domainオブジェクト
- ActiveRecord
- 自作クラス同士

**原則**
- モックは外部境界のみに限定

---

### ４.3 テストデータ（FactoryBot）

| レイヤー | 使用可否 |
|----------|----------|
| domains | 原則禁止（例外的に可） |
| features | 可 |
| models | 可 |
| resources | 可 |
| controllers | 可 |

**ルール**
- 最小構成で生成
- traitで意図明示
- letのネスト禁止
- domainsでは可能な限りPORO（Plain Old Ruby Object）でテストする

---

### ４.4 トランザクション

- 各テストは独立
- テスト間依存禁止
- DBは毎回ロールバック

---

### ４.5 命名ルール

- 業務用語で記述
- 条件と結果を明確にする

```ruby
describe "create order" do
  context "when stock is enough" do
    it "creates order"
  end

  context "when stock is insufficient" do
    it "raises error"
  end
end

```

---

## ５. TDD・推奨フロー

### TDDルール

- Red → Green → Refactor
- テストなし実装禁止

### 推奨フロー

- domain → use_case → controller
- domainから開始する
- controllerから始めない

## 6. アンチパターンと対策

| アンチパターン | 対策 |
|----------|----------|
| features肥大化 | domainへ移動 |
| controllerにロジック | requestを薄く |
| domainが薄い | ロジックを集約 |
| fat model | domainへ移動 |
| FactoryBot乱用 | trait整理 |

---

## 7. 追加推奨・レビュー観点

### 推奨

- カバレッジよりも重要なユースケース・分岐の網羅性を重視する
- テストは「仕様として意味があるか」を基準に設計する（カバレッジは補助指標）

### レビュー観点

- 責務とテスト対象が一致しているか
- domainに寄せるべきロジックが適切に切り出されているか
- テストが冗長・重複していないか
- ActiveRecordに過剰なビジネスロジックが混入していないか
- 重要な分岐・例外系が落ちていないか

## まとめ

- 複雑なビジネスロジックは可能な限りdomainに集約する
- modelsは永続化を主責務とし、必要最小限のロジックのみ持つ
- テストは責務ごとに分離する
- 上位は薄く、下位は厚くする
- 配置に迷った場合は「ビジネス判断があるか」で判断する

# Rails専用のルール定義

## 概要

このディレクトリ（src）はRails実装の「実行領域」であり、
設計判断はすべて docs/rules 側に集約されている。

src内では設計判断を行わず、既存ルールを適用するのみとする。

---

## Railsの設計思想（重要）

本プロジェクトはRailsの思想である 
**「設計より規約（Convention over Configuration）」を強く採用する。**

そのため以下を前提とする：

- 明示的な設計よりも、規約（Rails標準・docs/rules）を優先する
- 個別判断やカスタム設計は原則として禁止する
- 「設計を考えること」自体をsrcでは行わない

---

## 規約と設計の関係

本プロジェクトにおける「規約」とは以下を指す：

- Railsのフレームワーク規約
- `docs/rules/*` に定義されたプロジェクト規約

これらは実質的に**設計そのものの代替物**であり、
srcはそれを機械的に適用するだけの層である。

---

## ルール参照構造

すべての実装は以下のルールに従う：

- `docs/rules/architecture.md`（設計思想）
- `docs/rules/boundaries.md`（配置判断）
- `docs/rules/rails.md`（Rails実装ルール）
- `docs/rules/database.md`（データ制約）
- `docs/rules/testing.md`（テスト方針）

---

## src配下の責務

srcは「実装のみを行う領域」であり、
以下の責務に限定される：

- MVC構造の具体的実装
- モジュラーモノリス構造のコード配置
- `docs/rules/rails.md` に従った実装

---

## 実装ルール（重要）

srcでは以下を行ってはならない：

- ルールの解釈や再定義
- 設計判断
- 技術選定の追加判断

実装は常に docs/rules を唯一の判断基準として適用すること。

---

## このディレクトリの役割

- Railsコードの実装専用領域
- MVC構造の具体的なコード表現
- モジュラーモノリス構造の物理実装

---

## 禁止事項

- src配下に設計判断を書くこと
- domains / features / resourcesの定義を再説明すること
- database設計方針を記述すること
- テスト戦略を記述すること
- docs側のルールを上書きすること

---

## エージェントの振る舞い

- 判断はすべて docs/rules に従う
- srcは「適用のみ」を行う
- 迷った場合は `docs/rules/boundaries.md` を最優先で参照する
- 「どう設計するか」は考えない
- 「どの規約に従うか」だけを選択する
- 規約が曖昧な場合のみ docs/rules 側に遷移する

---

## 補足（重要）

srcは「設計を実装する場所」ではなく 
**「規約をコードに写像する機械である」**

---

## 実装後の必須チェック（重要）

コード修正・追加が一段落した場合、エージェントは必ず以下のコマンドを順番に実行し、
警告・エラーが存在しない状態を維持すること。

### コマンド一覧

#### 1. フォーマット修正（レイアウトのみ自動修正）

`docker compose run --rm app bundle exec rubocop -A --only Layout`

---

#### 2. 静的コード解析（Rubocop）

`docker compose run --rm app bundle exec rubocop`

---

#### 3. ビューLint（ビュー変更時のみ）

※ app/views に変更があった場合のみ実行

`docker compose run --rm app bundle exec erb_lint app/views`

---

#### 4. 脆弱性チェック（Brakeman）

`docker compose run --rm app bundle exec brakeman --no-pager`

---

#### 5. テスト実行（RSpec）

`docker compose exec -T app bundle exec rspec`

---

### 実行ルール

- 上記は「実装完了後に必ず順番に実行する」
- エラー・警告がある状態で完了としてはならない
- フォーマット（Layout）のみ自動修正を許可する（rubocop -A --only Layout）
- 上記以外の rubocop の自動修正（-A）は使用してはならない
- rubocop の指摘は自動修正に依存せず、必ずコード側で修正する
- テストが失敗している状態で終了してはならない
- すべてのチェックが通過するまで修正と再実行を繰り返す

---

### 位置づけ

これらのチェックは「設計判断」ではなく、
**規約の適用結果を検証する工程**である。

したがって src の責務に含まれる。

$ mkdir -p .github/workflows && touch .github/workflows/ci.yml

name: CI

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  # 変更ファイル判定（全体トリガー）
  changes:
    runs-on: ubuntu-latest

    outputs:
      app: ${{ steps.filter.outputs.app }}

    steps:
      - name: リポジトリをチェックアウト
        uses: actions/checkout@v6

      - name: 差分チェック
        uses: dorny/paths-filter@v4
        id: filter
        with:
          filters: |
            app:
              - 'src/**/*.rb'
              - 'src/**/*.erb'
              - 'src/Gemfile*'

  # 静的コード解析・脆弱性チェック
  lint:
    needs: changes
    if: needs.changes.outputs.app == 'true'
    runs-on: ubuntu-latest

    steps:
      - name: リポジトリをチェックアウト
        uses: actions/checkout@v6

      - name: 環境変数ファイルをリネーム
        run: cp ./.env.example ./.env

      - name: Dockerコンテナのビルド
        run: docker compose build

      # 静的コード解析
      - name: Rubocop
        run: docker compose run --rm app bundle exec rubocop

      # ビュー用の静的コード解析
      - name: ERB Lint
        run: docker compose run --rm app bundle exec erb_lint app/views

      # Railsの脆弱性チェック
      - name: Brakeman
        run: docker compose run --rm app bundle exec brakeman --no-pager

  # テスト
  test:
    needs: changes
    if: needs.changes.outputs.app == 'true'
    runs-on: ubuntu-latest

    steps:
      - name: リポジトリをチェックアウト
        uses: actions/checkout@v6

      - name: 環境変数ファイルをリネーム
        run: cp ./.env.example ./.env

      - name: Dockerコンテナのビルド
        run: docker compose build

      - name: Dockerコンテナの起動
        run: docker compose up -d

      - name: DB接続待機処理
        run: docker compose exec app bash -c "until pg_isready -h db -U ${DB_USER}; do sleep 1; done"

      - name: DB作成とマイグレーションの実行
        run: docker compose run --rm app bundle exec rails db:prepare

      - name: テストの実行（RSpec）
        run: docker compose exec -T app bundle exec rspec

$ git add -A
$ git commit -m "add harness"

# 追加機能の仕様

## 名言ドメインの仕様

### 1. エンティティ「Quote」

名言ドメインのエンティティ

属性：
- id：Quoteの識別子（主キー / bigint）
- quote_text：値オブジェクト「QuoteText」
  - 値オブジェクトはバリデーションの責務を持つ

---
### 2. 値オブジェクト「QuoteText」

名言の本文を表す値オブジェクト

制約：
- 使用可能文字：
- 全角ひらがな
- 全角カタカナ
- 漢字
- 長音「ー」
- 「。」（句点）
- 「、」（読点）
- 使用不可文字：
- 英数字
- スペース
- 記号（括弧・!・?など含む）
- 正規表現でバリデーションする

正規表現の例：
```
/\A[ぁ-んァ-ヶ一-龥ー。、]+\z/
```
---

### 3. ドメインサービス「QuoteSelector」

「今日の一言」を決定するドメインサービス

役割：
- 日付と名言マスタから1件のQuoteを選定する

選定ロジック：
- 対象日付の「年内日数（day_of_year）」を取得
- quotes数で割った余りを算出
- そのindexのQuoteを返す

例：
```
index = date.yday % quotes.count
```

不変条件：
- 同じ日付 → 必ず同じ結果
- quotesが同じなら結果は完全に決定論的
- うるう年は考慮しない（ydayをそのまま使用）

例外：
- quotesが0件の場合はエラーとして例外を返す


### 4. ユースケースの処理フロー

1. quote_historiesに今日の日付があるか確認
2. あればそれを返す
3. なければ：
  - QuoteSelectorで選定
  - quote_historiesに保存
  - 返却

---

## データベースの仕様
### 1. 名言マスタテーブル「quotes」

| カラム | 型 | 説明 |
| --- | --- | --- | 
| id | bigint | PK |
| text | string | 名言本文 |
| created_at | datetime | |
| updated_at | datetime | |


### 2. 名言履歴テーブル「quote_histories」

| カラム | 型 | 説明 |
| --- | --- | --- | 
| id | bigint | PK |
| date | date | 対象日（UTC日付）、ユニークキーとする |
| quote_id | bigint | 名言マスタのid |
| created_at | datetime | |
| updated_at | datetime | |

---

### 3. 名言マスタの登録値

| id | 名言 |
| --- | --- |
| 1 | 必死に生きる生涯は光を放つ |
| 2 | 我事において後悔せず |
| 3 | 天は人の上に人を造らず人の下に人を造らず |
| 4 | 成功は失敗の積み重ね |
| 5 | 小さなことの積み重ねが遠くへ行く道 |
| 6 | いい作品はいい人生から生まれる |
| 7 | 映画は自分の手でつくるもの |
| 8 | 遠回りは無駄ではない |
| 9 | 人を相手にせず天を相手にせよ |
| 10 | 人は成功するために努力する |

---

## UIの仕様

- トップページ中央に1件表示
- 表示例：`本日の一言：〇〇〇〇〇`
- レスポンシブデザインであること
- CSSにはTailwindCSSを利用する
- 全体的なデザインは落ち着きがあっていい感じにしたい

「今日の一言」をトップページの中央にいい感じに表示させるだけの簡単なアプリを作りたいです。
現在の仕様は以下になるので、これをまとめた上で、確認点があれば質問して下さい。

$ docker compose exec app rails db:prepare
$ docker compose down
$ docker compose up -d

$ docker compose down

$ docker compose up -d db

$ docker build --no-cache -t rails-aidd-app:1.0.0 -f src/Dockerfile src

$ docker run -d \
-p 80:80 \
-e RAILS_MASTER_KEY={src/config/master.keyの中身の値} \
-e DB_HOST=host.docker.internal \
-e DB_USER=root \
-e DB_PASSWORD=root \
rails-aidd-app:1.0.0

$ mkdir django-admin && cd django-admin
$ mkdir -p deploy/docker/local/py && touch deploy/docker/local/py/Dockerfile
$ mkdir -p deploy/docker/local/db && touch deploy/docker/local/db/Dockerfile
$ mkdir -p deploy/docker/local/db/init && touch deploy/docker/local/db/init/init.sql
$ touch .env compose.yml

FROM python:3.14.0-slim-trixie

# タイムゾーン設定
ENV TZ=Asia/Tokyo

# パッケージ管理用のpoetryをインストール
RUN pip3 install --no-cache-dir poetry

# [開発用] 仮想環境を作成
RUN poetry config virtualenvs.in-project true

WORKDIR /py

EXPOSE 8000

FROM postgres:18.1

ENV LANG ja_JP.utf8

# PostgreSQLの日本語化で「ja_JP.utf8」を使うために必要
RUN apt-get update && \
    apt-get install -y locales && \
    rm -rf /var/lib/apt/lists/* && \
    localedef -i ja_JP -c -f UTF-8 -A /usr/share/locale/locale.alias ja_JP.UTF-8

-- usersテーブルの作成
CREATE TABLE "public"."users" ("id" bigint NOT NULL GENERATED BY DEFAULT AS IDENTITY, "uid" character varying NOT NULL, "last_name" character varying NOT NULL, "first_name" character varying NOT NULL, "email" character varying NOT NULL, "created_at" timestamptz NOT NULL, "updated_at" timestamptz NOT NULL, "deleted_at" timestamptz NULL, PRIMARY KEY ("id"));
CREATE INDEX "user_deleted_at" ON "public"."users" ("deleted_at");
CREATE UNIQUE INDEX "users_email_key" ON "public"."users" ("email");
CREATE UNIQUE INDEX "users_uid_key" ON "public"."users" ("uid");

ENV=local
DB_NAME=pg-db
DB_USER=pg-user
DB_PASSWORD=pg-password
DB_HOST=db-django

services:
  django:
    container_name: django-admin
    build:
      context: .
      dockerfile: ./deploy/docker/local/py/Dockerfile
    volumes:
      - .:/py
    ports:
      - "8000:8000"
    env_file:
      - .env
    tty: true
    stdin_open: true

$ docker compose build --no-cache

docker compose run --rm django poetry init

$ docker compose run --rm django poetry add django "psycopg[binary]"
$ docker compose run --rm django poetry add --dev ruff

$ docker compose run --rm django poetry run django-admin startproject myapp ./src

"""
Django settings for myapp project.

Generated by 'django-admin startproject' using Django 6.0.

For more information on this file, see
https://docs.djangoproject.com/en/6.0/topics/settings/

For the full list of settings and their values, see
https://docs.djangoproject.com/en/6.0/ref/settings/
"""

import os
from pathlib import Path

# Build paths inside the project like this: BASE_DIR / 'subdir'.
BASE_DIR = Path(__file__).resolve().parent.parent


# Quick-start development settings - unsuitable for production
# See https://docs.djangoproject.com/en/6.0/howto/deployment/checklist/

# SECURITY WARNING: keep the secret key used in production secret!
SECRET_KEY = 'django-insecure-jr21o1cjct+97fvqon)d$hdjm8oo7h0ko_th=dlv!8@ts#4!&5'

# SECURITY WARNING: don't run with debug turned on in production!
DEBUG = True

ALLOWED_HOSTS = []


# Application definition

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    # プロジェクトのディレクトリ追加
    'myapp'
]

MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
]

ROOT_URLCONF = 'myapp.urls'

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    },
]

WSGI_APPLICATION = 'myapp.wsgi.application'


# Database
# https://docs.djangoproject.com/en/6.0/ref/settings/#databases

DATABASES = {
    # PostgreSQLへの接続設定
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': os.environ['DB_NAME'],
        'USER': os.environ['DB_USER'],
        'PASSWORD': os.environ['DB_PASSWORD'],
        'HOST': os.environ['DB_HOST'],
        'PORT': '5432',
    }
}


# Password validation
# https://docs.djangoproject.com/en/6.0/ref/settings/#auth-password-validators

AUTH_PASSWORD_VALIDATORS = [
    {
        'NAME': 'django.contrib.auth.password_validation.UserAttributeSimilarityValidator',
    },
    {
        'NAME': 'django.contrib.auth.password_validation.MinimumLengthValidator',
    },
    {
        'NAME': 'django.contrib.auth.password_validation.CommonPasswordValidator',
    },
    {
        'NAME': 'django.contrib.auth.password_validation.NumericPasswordValidator',
    },
]


# Internationalization
# https://docs.djangoproject.com/en/6.0/topics/i18n/

# 日本語化設定
LANGUAGE_CODE = 'ja'
TIME_ZONE = 'Asia/Tokyo'

USE_I18N = True

USE_TZ = True


# Static files (CSS, JavaScript, Images)
# https://docs.djangoproject.com/en/6.0/howto/static-files/

STATIC_URL = 'static/'

FROM python:3.14.0-slim-trixie

# タイムゾーン設定
ENV TZ=Asia/Tokyo

# パッケージ管理用のpoetryをインストール
RUN pip3 install --no-cache-dir poetry

# [開発用] 仮想環境を作成
RUN poetry config virtualenvs.in-project true

WORKDIR /py

# poetry.lockから依存関係をインストール
COPY pyproject.toml poetry.lock .
RUN poetry install --no-root

COPY ./src ./src

EXPOSE 8000

services:
  django:
    container_name: django-admin
    build:
      context: .
      dockerfile: ./deploy/docker/local/py/Dockerfile
    command: poetry run python ./src/manage.py runserver 0.0.0.0:8000
    volumes:
      - ./pyproject.toml:/py/pyproject.toml
      - ./poetry.lock:/py/poetry.lock
      - ./src:/py/src
    ports:
      - "8000:8000"
    env_file:
      - .env
    tty: true
    stdin_open: true
    depends_on:
      - db-django
  db-django:
    container_name: django-db
    build:
      context: .
      dockerfile: ./deploy/docker/local/db/Dockerfile
    environment:
      POSTGRES_DB: ${DB_NAME}
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      TZ: Asia/Tokyo
      # ローカル環境でもパスワードを有効化する設定
      POSTGRES_INITDB_ARGS: --auth-local=scram-sha-256 --auth-host=scram-sha-256
    volumes:
      - ./deploy/docker/local/db/init:/docker-entrypoint-initdb.d
      - db-django-data:/var/lib/postgresql
    ports:
      - "5432:5432"
    env_file:
      - .env
volumes:
  db-django-data:

$ docker compose down
$ docker compose build --no-cache
$ docker compose up -d

$ docker compose exec django poetry run python ./src/manage.py inspectdb > ./src/myapp/models.py

from django.db import models
from django.utils.translation import gettext_noop

class Users(models.Model):
    id = models.BigAutoField(primary_key=True)
    uid = models.CharField(unique=True)
    last_name = models.CharField()
    first_name = models.CharField()
    email = models.CharField(unique=True)
    # 作成日と更新日を自動設定するように修正
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)
    deleted_at = models.DateTimeField(blank=True, null=True)

    class Meta:
        managed = False
        db_table = 'users'
        # 表示設定（日本語化で翻訳されないようにgettext_noopを使用）
        verbose_name = gettext_noop("User")
        verbose_name_plural = gettext_noop("Users")

$ touch src/myapp/admin.py

from django.contrib import admin
from django.contrib.admin.models import LogEntry
from .models import Users

# サイト名の設定
admin.site.site_header = "Django Admin"
admin.site.site_title = "Django Admin"

# 操作履歴用にデフォルトであるモデルを管理画面に追加
admin.site.register(LogEntry)

# DBスキーマに関するモデルを管理画面に追加
admin.site.register(Users)

$ docker compose exec django poetry run python ./src/manage.py migrate

$ docker compose exec django poetry run python ./src/manage.py createsuperuser

$ docker compose down
$ docker compose up -d

from django.contrib import admin
from django.contrib.admin.models import LogEntry
from django.utils import timezone

from .models import Users

# サイト名の設定
admin.site.site_header = "Django Admin"
admin.site.site_title = "Django Admin"


###############################
# 操作履歴をメニューに追加する設定
###############################


# デフォルトで存在するモデルを使用する
@admin.register(LogEntry)
class LogEntryAdmin(admin.ModelAdmin):
    # 一覧画面に表示するフィールド設定
    list_display = (
        "action_time",
        "user",
        "content_type",
        "object_repr",
        "action_flag",
    )

    # 一覧画面のフィルター設定
    list_filter = ("action_flag", "content_type")

    # 検索用の対象フィールド
    search_fields = ("object_repr", "change_message", "user__username")

    # 変更不可フィールド設定
    readonly_fields = (
        "action_time",
        "user",
        "content_type",
        "object_repr",
        "action_flag",
    )

    # 詳細画面の表示設定
    fieldsets = (
        (
            None,
            {
                "fields": (
                    "action_time",
                    "user",
                    "content_type",
                    "object_repr",
                    "action_flag",
                ),
            },
        ),
    )


###############################
# 共通フィルター用のクラス定義
###############################


# 削除日用のクラス定義
class DeletedAtFilter(admin.SimpleListFilter):
    title = "削除日（deleted_at）"
    parameter_name = "deleted"

    # 選択肢の設定
    def lookups(self, request, model_admin):
        return (
            ("alive", "未削除"),
            ("deleted", "削除済み"),
        )

    # 選択肢に対するクエリ設定
    def queryset(self, request, queryset):
        value = self.value()
        if value == "alive":
            return queryset.filter(deleted_at__isnull=True)
        if value == "deleted":
            return queryset.filter(deleted_at__isnull=False)
        return queryset


###############################
# DBモデルをメニューに追加する設定
###############################


# usersの設定
@admin.register(Users)
class UsersAdmin(admin.ModelAdmin):
    # 一覧画面に表示するフィールド設定
    list_display = [field.name for field in Users._meta.get_fields()]

    # 一覧画面のフィルター設定
    list_filter = ((DeletedAtFilter),)

    # 検索用の対象フィールド
    search_fields = ("id", "uid", "last_name", "first_name", "email")

    # 変更不可フィールド設定
    readonly_fields = ("id", "created_at", "updated_at")

    # 詳細画面の表示設定
    fieldsets = (
        (
            None,
            {
                "fields": (
                    "id",
                    "uid",
                    "last_name",
                    "first_name",
                    "email",
                    "created_at",
                    "updated_at",
                    "deleted_at",
                ),
            },
        ),
    )

    # 単体用の論理削除設定
    def delete_model(self, request, obj):
        obj.updated_at = timezone.now()
        obj.deleted_at = timezone.now()
        obj.save()

    # 一括用の論理削除設定
    def delete_queryset(self, request, queryset):
        queryset.update(updated_at=timezone.now(), deleted_at=timezone.now())

$ docker compose exec django poetry run ruff format .
$ docker compose exec django poetry run ruff check . --select I --fix

$ docker compose exec django poetry run ruff check .

$ mkdir fastapi-domain && cd fastapi-domain
$ mkdir -p deploy/docker/local/py && touch deploy/docker/local/py/Dockerfile
$ mkdir -p src/myapp && touch src/myapp/__init__.py src/myapp/main.py
$ touch .env compose.yml

FROM python:3.14.0-slim-trixie

# パッケージ管理用のpoetryをインストール
RUN pip3 install --no-cache-dir poetry

# [開発用] 仮想環境を作成
RUN poetry config virtualenvs.in-project true

WORKDIR /py

EXPOSE 9004

from fastapi import FastAPI
from fastapi.responses import PlainTextResponse

app = FastAPI()


@app.get("/", response_class=PlainTextResponse)
def root() -> str:
    return "Hello World !!"

ENV=local
TEST_VALUE=test123

services:
  fastapi:
    container_name: fastapi
    build:
      context: .
      dockerfile: ./deploy/docker/local/py/Dockerfile
    volumes:
      - .:/py
    ports:
      - "9004:9004"
    env_file:
      - .env
    tty: true
    stdin_open: true

$ docker compose build --no-cache

$ docker compose run --rm fastapi poetry init

$ docker compose run --rm fastapi poetry add fastapi uvicorn pydantic
$ docker compose run --rm fastapi poetry add --dev ruff mypy

[project]
name = "fastapi-domain"
version = "0.1.0"
description = ""
authors = [
    {name = "Your Name",email = "you@example.com"}
]
readme = "README.md"
requires-python = ">=3.14"
dependencies = [
    "fastapi (>=0.122.0,<0.123.0)",
    "uvicorn (>=0.38.0,<0.39.0)",
    "pydantic (>=2.12.5,<3.0.0)"
]

# パッケージの読み込み設定
packages = [
    { include = "myapp", from = "src" }
]


[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"

[dependency-groups]
dev = [
    "ruff (>=0.14.7,<0.15.0)",
    "mypy (>=1.19.0,<2.0.0)"
]


# =========================================================
# ruffの設定（フォーマッター + 静的コード解析）
# =========================================================
[tool.ruff]
# Pythonのバージョン指定
target-version = "py314"

# チェック対象外のディレクトリ
exclude = [
    ".venv",
    ".mypy_cache",
    ".ruff_cache",
]

# ==========
# lint設定
# ==========
lint.select = [
    "E", # Pycodestyle エラー
    "F", # Pyflakes
    "B", # bugbear（バグ検出）
    "I", # isort（import整理）
    "UP", # pyupgrade（最新構文）
]

# =========================================================
# mypyの設定（型チェック）
# =========================================================
[tool.mypy]
# Pythonのバージョン指定
python_version = "3.14"

# 厳密モードの有効化
strict = true

# 追加の表示設定
warn_unused_configs = true # 無効な設定や使われていない設定を警告として表示
warn_unreachable = true # 到達不可能コードを警告
show_error_context = true # エラー発生箇所の前後コンテキストを表示
show_column_numbers = true # エラー箇所の列番号を表示

# Pydantic v2の設定
plugins = ["pydantic.mypy"]

# チェック対象外のディレクトリ
exclude = [
    ".venv",
    ".mypy_cache",
    ".ruff_cache",
]

# 外部ライブラリは無視 
ignore_missing_imports = true

FROM python:3.14.0-slim-trixie

# タイムゾーン設定
ENV TZ=Asia/Tokyo

# パッケージ管理用のpoetryをインストール
RUN pip3 install --no-cache-dir poetry

# [開発用] 仮想環境を作成
RUN poetry config virtualenvs.in-project true

WORKDIR /py

# poetry.lockから依存関係をインストール
COPY pyproject.toml poetry.lock .
RUN poetry install --no-root

COPY ./src ./src
EXPOSE 9004

services:
  fastapi:
    container_name: fastapi
    build:
      context: .
      dockerfile: ./deploy/docker/local/py/Dockerfile
    command: poetry run uvicorn myapp.main:app --app-dir src --reload --host 0.0.0.0 --port 9004
    volumes:
      - ./pyproject.toml:/py/pyproject.toml
      - ./poetry.lock:/py/poetry.lock
      - ./src:/py/src
    ports:
      - "9004:9004"
    env_file:
      - .env
    tty: true
    stdin_open: true

$ docker compose down
$ docker compose build --no-cache
$ docker compose up -d

$ docker compose logs

$ docker compose exec fastapi poetry run ruff format .

$ docker compose exec fastapi poetry run ruff check . --select I --fix

$ docker compose exec fastapi poetry run ruff check .

$ docker compose exec fastapi poetry run mypy .

$ mkdir -p src/myapp/infrastructure/config
$ touch src/myapp/infrastructure/__init__.py src/myapp/infrastructure/config/settings.py src/myapp/infrastructure/config/__init__.py
$ mkdir -p src/myapp/infrastructure/logger
$ touch src/myapp/infrastructure/logger/__init__.py src/myapp/infrastructure/logger/logger.py
$ mkdir -p src/myapp/application/context
$ touch src/myapp/application/__init__.py src/myapp/application/context/__init__.py src/myapp/application/context/request_context.py
$ mkdir -p src/myapp/presentation/middleware
$ touch src/myapp/presentation/__init__.py src/myapp/presentation/middleware/__init__.py src/myapp/presentation/middleware/request_middleware.py
$ mkdir -p src/myapp/presentation/exception
$ touch src/myapp/presentation/exception/__init__.py src/myapp/presentation/exception/definitions.py src/myapp/presentation/exception/handlers.py
$ mkdir -p src/myapp/infrastructure/database
$ touch src/myapp/infrastructure/database/__init__.py src/myapp/infrastructure/database/database.py
$ mkdir -p src/myapp/presentation/schema/common
$ touch src/myapp/presentation/schema/__init__.py src/myapp/presentation/schema/common/error.py src/myapp/presentation/schema/common/__init__.py

from pydantic_settings import BaseSettings, SettingsConfigDict


class Settings(BaseSettings):
    env: str = "local"
    # デフォル値を付けない場合は必須になるので注意！
    test_value: str

    model_config = SettingsConfigDict(
        env_file=".env",
    )


# サーバー起動時にインスタンス化
# .envがない場合はOSから環境変数を読み込む
settings = Settings()


def get_settings() -> Settings:
    return settings

from .settings import Settings, get_settings

__all__ = ["Settings", "get_settings"]

import logging
from logging.config import dictConfig

from myapp.application.context import request_id
from myapp.infrastructure.config.settings import get_settings

settings = get_settings()


class EnvFilter(logging.Filter):
    def filter(self, record: logging.LogRecord) -> bool:
        record.env = settings.env
        return True

class RequestIDFilter(logging.Filter):
    def filter(self, record: logging.LogRecord) -> bool:
        record.request_id = request_id.get()
        return True


LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "filters": {
        "request_id_filter": {"()": RequestIDFilter},
        "env_filter": {"()": EnvFilter},
    },
    "formatters": {
        "default": {
            "format": (
                "%(asctime)s [%(levelname)s] "
                "ENV=%(env)s - %(name)s "
                "[request_id=%(request_id)s] "
                "%(message)s"
            )
        }
    },
    "handlers": {
        "console": {
            "class": "logging.StreamHandler",
            "filters": ["request_id_filter", "env_filter"],
            "formatter": "default",
        }
    },
    "root": {
        "level": "INFO",
        "handlers": ["console"],
    },
}


def init_logging() -> None:
    dictConfig(LOGGING)


def get_logger(name: str = "fastapi-domain") -> logging.Logger:
    return logging.getLogger(name)

from .logger import get_logger, init_logging

__all__ = ["init_logging", "get_logger"]

from contextvars import ContextVar

# リクエストID（リクエスト単位で一意のID）
request_id: ContextVar[str | None] = ContextVar("request_id", default=None)

from .request_context import request_id

__all__ = ["request_id"]

import uuid

from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
from starlette.requests import Request
from starlette.responses import Response

from myapp.application.context import request_id
from myapp.infrastructure.logger import get_logger


class RequestMiddleware(BaseHTTPMiddleware):
    async def dispatch(
        self, request: Request, call_next: RequestResponseEndpoint
    ) -> Response:
        # UUIDの取得
        new_uuid = str(uuid.uuid4())

        # リクエストID用コンテキストにUUIDを設定
        request_id.set(new_uuid)

        # レスポンスヘッダーにX-Request-IDを設定
        response = await call_next(request)
        response.headers["X-Request-ID"] = new_uuid

        # リクエスト開始ログ出力
        logger = get_logger()
        logger.info("start request !!")

        return response

from .request_middleware import RequestMiddleware

__all__ = ["RequestMiddleware"]

######################
# 例外定義
######################

# DBエラー
class DatabaseError(Exception):
    def __init__(self, message: str):
        self.message = message
        super().__init__(message)

from typing import cast

from fastapi import Request
from fastapi.exception_handlers import request_validation_exception_handler
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse

from myapp.infrastructure.logger import get_logger

######################
# 例外用のハンドラー定義
######################


# RequestValidationError用
async def request_validation_error_handler(
    request: Request, exc: Exception
) -> JSONResponse:
    cast_exc = cast(RequestValidationError, exc)
    logger = get_logger()
    logger.warning(f"バリデーションエラー: {cast_exc.errors()}")
    return await request_validation_exception_handler(request, cast_exc)

# バリデーションエラー
async def valid_error_exception_handler(
    request: Request, exc: Exception
) -> JSONResponse:
    return JSONResponse(
        status_code=422,
        content={"detail": str(exc)},
    )


# DBエラー
async def db_error_exception_handler(request: Request, exc: Exception) -> JSONResponse:
    return JSONResponse(
        status_code=500,
        content={"detail": str(exc)},
    )


# 共通エラー
async def general_exception_handler(request: Request, exc: Exception) -> JSONResponse:
    return JSONResponse(
        status_code=500,
        content={"detail": f"Internal Server Error: {str(exc)}"},
    )

from .definitions import DatabaseError
from .handlers import (
    db_error_exception_handler,
    general_exception_handler,
    request_validation_error_handler,
    valid_error_exception_handler,
)

__all__ = [
    "request_validation_error_handler",
    "valid_error_exception_handler",
    "DatabaseError",
    "db_error_exception_handler",
    "general_exception_handler",
]

# 今回はDBインスタンスはダミーとする。
def get_db() -> str:
    return "DBインスタンスのダミー"

from .database import get_db

__all__ = ["get_db"]

from pydantic import BaseModel, ConfigDict


# 400 Bad Request
class BadRequestResponse(BaseModel):
    detail: str

    # OpenAPI用設定
    model_config = ConfigDict(
        # 書き換え不可設定
        frozen=True,
        # 「Example Value」に表示されるJSON
        json_schema_extra={
            "example": {
                "detail": "Bad Request",
            }
        },
    )


# 401 Unauthorized
class UnauthorizedResponse(BaseModel):
    detail: str

    # OpenAPI用設定
    model_config = ConfigDict(
        # 書き換え不可設定
        frozen=True,
        # 「Example Value」に表示されるJSON
        json_schema_extra={
            "example": {
                "detail": "Unauthorized",
            }
        },
    )


# 422 Unprocessable Entity
class UnprocessableEntityResponse(BaseModel):
    detail: str

    # OpenAPI用設定
    model_config = ConfigDict(
        # 書き換え不可設定
        frozen=True,
        # 「Example Value」に表示されるJSON
        json_schema_extra={
            "example": {
                "detail": "Unprocessable Entity",
            }
        },
    )


# 500 Internal Server Error
class InternalServerErrorResponse(BaseModel):
    detail: str

    # OpenAPI用設定
    model_config = ConfigDict(
        # 書き換え不可設定
        frozen=True,
        # 「Example Value」に表示されるJSON
        json_schema_extra={
            "example": {
                "detail": "Internal Server Error",
            }
        },
    )

from .error import (
    BadRequestResponse,
    InternalServerErrorResponse,
    UnauthorizedResponse,
    UnprocessableEntityResponse,
)

__all__ = [
    "BadRequestResponse",
    "UnauthorizedResponse",
    "UnprocessableEntityResponse",
    "InternalServerErrorResponse",
]

/src
 ├── /myapp
 |    ├── /application（アプリケーション層）
 |    |    ├── /context（独立した値を持たせるためのコンテキスト変数）
 |    |    └── /usecase（ユースケース層）
 |    |
 |    ├── /di（依存注入によってユースケースのインスタンスをまとめる）
 |    |
 |    ├── /domain（ドメイン層）
 |    |    ├── entity（ドメインモデルの定義）
 |    |    ├── ValueObject（意味のある値を扱うためのオブジェクト定義）
 |    |    ├── repository（リポジトリのインターフェース定義）
 |    |    └── （仮）service（外部サービスのインターフェース定義）
 |    |
 |    ├── /infrastructure（インフラストラクチャー層）
 |    |    ├── /database（データベース設定）
 |    |    ├── /logger（ロガーの実装）
 |    |    ├── /persistence（リポジトリの実装。DB操作による永続化層。）
 |    |    ├── （仮）/cache（キャッシュを含めたリポジトリの実装。インターフェースはリポジトリと同一。）
 |    |    └── （仮）/externalapi（外部サービスの実装）
 |    |
 |    └── /presentation（プレゼンテーション層）
 |         ├── /exception（カスタム例外定義）
 |         ├── /handler（ハンドラー層）
 |         ├── /middleware（ミドルウェア定義）
 |         ├── /router（ルーター定義）
 |         └── /schema（APIの入出力の仕様を決めるスキーマ定義）
 |
 └── /tests（テストコード用ディレクトリ）

$ mkdir src/myapp/domain/post
$ touch src/myapp/domain/__init__.py src/myapp/domain/post/text.py src/myapp/domain/post/entity.py src/myapp/domain/post/repository.py src/myapp/domain/post/__init__.py

# 型ヒントでまだ定義されていないクラス名を文字列として書けるようにする設定
# これによってクラス同士が互いを参照するような場合でも型ヒントが使いやすくなる
from __future__ import annotations

from dataclasses import dataclass


# 値オブジェクトの定義（フィールドは変更不可設定）
@dataclass(frozen=True)
    class Text:
    value: str

def __post_init__(self) -> None:
    ######################
    # バリデーションチェック
    ######################
    if not self.value:
        raise ValueError("テキストの値は必須です。")

    if len(self.value) > 20:
        raise ValueError("テキストの値は20文字以内で入力して下さい。")

    # オブジェクトを文字列として表示する際に呼ばれるメソッド
    # print() や str() を使う時にこのメソッドの戻り値が表示されます
    def __str__(self) -> str:
        return self.value

    # DBからの復元用クラスメソッド（チェック処理無し）
    @classmethod
    def from_raw(cls, raw_value: str) -> Text:
        # __init__を呼ばずにインスタンス作成した値を設定
        obj = cls.__new__(cls)
        object.__setattr__(obj, "value", raw_value)
        return obj

# 型ヒントでまだ定義されていないクラス名を文字列として書けるようにする設定
# これによってクラス同士が互いを参照するような場合でも型ヒントが使いやすくなる
from __future__ import annotations

from dataclasses import dataclass

from .text import Text


@dataclass
class Post:
    text: Text
    id: int = 0

    def __post_init__(self) -> None:
    ######################
    # バリデーションチェック
    ######################
    if self.text is None:
        raise ValueError("textは必須です。")

    # DBからの復元用クラスメソッド（チェック処理無し）
    @classmethod
    def from_raw(cls, raw_id: int, raw_text: Text) -> Post:
        # __init__を呼ばずにインスタンス作成した値を設定
        obj = cls.__new__(cls)
        obj.id = raw_id
        obj.text = raw_text
        return obj

from abc import ABC, abstractmethod

from .entity import Post


class PostRepository(ABC):
    # 今回はDB設定はダミー値を使っているため、dbの型はstrにしている
    @abstractmethod
    async def create(self, db: str, post: Post) -> Post:
        pass

    # 今回はDB設定はダミー値を使っているため、dbの型はstrにしている
    @abstractmethod
    async def find_all(self, db: str) -> list[Post]:
        pass

from .entity import Post
from .repository import PostRepository
from .text import Text

__all__ = ["Post", "PostRepository", "Text"]

$ mkdir -p src/myapp/infrastructure/persistence/post
$ touch src/myapp/infrastructure/persistence/__init__.py src/myapp/infrastructure/persistence/post/post_repo_impl.py src/myapp/infrastructure/persistence/post/__init__.py

from myapp.domain.post import Post, PostRepository, Text
from myapp.presentation.exception import DatabaseError


class PostRepositoryImpl(PostRepository):
    # 今回はDB設定はダミー値を使っているため、dbの型はstrにしている
    async def create(self, db str, post: Post) -> Post:
        try:
            # DBへデータ登録を完了した想定でpostを返す
            return post

        except Exception as e:
            raise DatabaseError(f"DBエラーが発生しました。: {str(e)}") from e

    # 今回はDB設定はダミー値を使っているため、dbの型はstrにしている
    async def find_all(self, db str) -> list[Post]:
        try:
            # DBからデータを取得した想定で固定値を返す
            posts = [
                Post.from_raw(
                    raw_id=1, raw_text=Text.from_raw(raw_value="Postデータ１")
                ),
                Post.from_raw(
                    raw_id=2, raw_text=Text.from_raw(raw_value="Postデータ２")
                ),
            ]

            return posts

        except Exception as e:
            raise DatabaseError(f"DBエラーが発生しました。: {str(e)}") from e

from .post_repo_impl import PostRepositoryImpl

__all__ = ["PostRepositoryImpl"]

$ mkdir -p src/myapp/presentation/schema/post
$ touch src/myapp/presentation/schema/post/request.py src/myapp/presentation/schema/post/response.py src/myapp/presentation/schema/post/__init__.py

from pydantic import BaseModel, ConfigDict, Field


class PostCreateRequest(BaseModel):
    text: str = Field(..., max_length=20, description="テキスト")

    # OpenAPI用設定
    model_config = ConfigDict(
        # 書き換え不可設定
        frozen=True,
        # 「Example Value」に表示されるJSON
        json_schema_extra={
            "example": {
                "text": "Postテキスト",
            }
        },
    )

from pydantic import BaseModel


class PostResponse(BaseModel):
    id: int
    text: str

from .request import PostCreateRequest
from .response import PostResponse

__all__ = ["PostCreateRequest", "PostResponse"]

$ mkdir -p src/myapp/application/usecase/post
$ touch src/myapp/application/usecase/__init__.py src/myapp/application/usecase/post/create_post.py src/myapp/application/usecase/post/get_posts.py src/myapp/application/usecase/post/__init__.py

import logging

from fastapi import HTTPException

from myapp.domain.post import Post, PostRepository, Text
from myapp.presentation.schema.post import PostCreateRequest, PostResponse


class CreatePostUsecase:
    # コンストラクタで依存注入する
    # 今回はDB設定はダミー値を使っているため、dbの型はstrにしている
    def __init__(
        self, logger: logging.Logger, db: str, post_repo: PostRepository
    ) -> None:
        self.logger = logger
        self.db = db
        self.post_repo = post_repo

    async def execute(self, req: PostCreateRequest) -> PostResponse:
        try:
            # 新規Postデータ作成
            newPost = Post(text=Text(req.text))

            # DB登録
            post = await self.post_repo.create(self.db, newPost)
            return PostResponse(id=post.id, text=post.text.value)

        # ValueError発生時の例外処理
        except ValueError as e:
            self.logger.warning("バリデーションエラー: %s", e)
            raise HTTPException(
                status_code=422, detail=f"バリデーションエラー: {str(e)}"
            ) from e

        except Exception as e:
            self.logger.error("DB登録に失敗しました。: %s", e)
            raise e

import logging

from myapp.domain.post import PostRepository
from myapp.presentation.schema.post import PostResponse


class GetPostsUsecase:
    # コンストラクタで依存注入する
    # 今回はDB設定はダミー値を使っているため、dbの型はstrにしている
    def __init__(
        self, logger: logging.Logger, db: str, post_repo: PostRepository
    ) -> None:
        self.logger = logger
        self.db = db
        self.post_repo = post_repo

    async def execute(self) -> list[PostResponse]:
        try:
            # データ取得
            posts = await self.post_repo.find_all(self.db)
            return [PostResponse(id=p.id, text=p.text.value) for p in posts]

        except Exception as e:
            self.logger.error("DBからのデータ取得に失敗しました。: %s", e)
            raise e

from .create_post import CreatePostUsecase
from .get_posts import GetPostsUsecase

__all__ = ["CreatePostUsecase", "GetPostsUsecase"]

$ mkdir -p src/myapp/di
$ touch src/myapp/di/container.py src/myapp/di/__init__.py

import logging
from typing import Annotated

from fastapi import Depends

from myapp.application.usecase.post import CreatePostUsecase, GetPostsUsecase
from myapp.domain.post import PostRepository
from myapp.infrastructure.database import get_db
from myapp.infrastructure.logger import get_logger
from myapp.infrastructure.persistence.post import PostRepositoryImpl


# リポジトリのDI用関数
def get_post_repository() -> PostRepository:
    return PostRepositoryImpl()


# Post用ユースケース
def create_post_usecase(
    logger: Annotated[logging.Logger, Depends(get_logger)],
    # 今回はDB設定はダミー値を使っているため、dbの型はstrにしている
    db: Annotated[str, Depends(get_db)],
    post_repo: Annotated[PostRepository, Depends(get_post_repository)],
) -> CreatePostUsecase:
    return CreatePostUsecase(logger=logger, db=db, post_repo=post_repo)


def get_posts_usecase(
    logger: Annotated[logging.Logger, Depends(get_logger)],
    # 今回はDB設定はダミー値を使っているため、dbの型はstrにしている
    db: Annotated[str, Depends(get_db)],
    post_repo: Annotated[PostRepository, Depends(get_post_repository)],
) -> GetPostsUsecase:
    return GetPostsUsecase(logger=logger, db=db, post_repo=post_repo)

$ mkdir -p src/myapp/presentation/handler/post
$ touch src/myapp/presentation/handler/__init__.py src/myapp/presentation/handler/post/post.py src/myapp/presentation/handler/post/__init__.py

from typing import Annotated

from fastapi import Depends

from myapp.application.usecase.post import CreatePostUsecase, GetPostsUsecase
from myapp.di.container import create_post_usecase, get_posts_usecase
from myapp.presentation.schema.post import PostCreateRequest, PostResponse


class CreatePostHandler:
    def __init__(
        self,
        usecase: Annotated[CreatePostUsecase, Depends(create_post_usecase)],
    ):
        self.usecase = usecase

    async def execute(self, req: PostCreateRequest) -> PostResponse:
        return await self.usecase.execute(req)


class GetPostsHandler:
    def __init__(
        self,
        usecase: Annotated[GetPostsUsecase, Depends(get_posts_usecase)],
    ):
        self.usecase = usecase

    async def execute(self) -> list[PostResponse]:
        return await self.usecase.execute()

from .post import CreatePostHandler, GetPostsHandler

__all__ = ["CreatePostHandler", "GetPostsHandler"]

$ mkdir -p src/myapp/presentation/router
$ touch src/myapp/presentation/router/router.py src/myapp/presentation/router/__init__.py

from typing import Annotated, Any

from fastapi import APIRouter, Depends

from myapp.presentation.handler.post import CreatePostHandler, GetPostsHandler
from myapp.presentation.schema.common import InternalServerErrorResponse
from myapp.presentation.schema.post import PostCreateRequest, PostResponse

router = APIRouter()

# OpenAPI用の共通エラーレスポンス定義
common_error_res: dict[int | str, dict[str, Any]] | None = {
    500: {"description": "サーバーエラー", "model": InternalServerErrorResponse},
}


@router.post(
    "/post",
    response_model=PostResponse,
    status_code=201,
    responses=common_error_res,
    summary="Postデータ新規作成",
    description="Postデータを新規作成する",
    tags=["Post"],
)
async def create_post(
    req: PostCreateRequest,
    handler: Annotated[CreatePostHandler, Depends(CreatePostHandler)],
) -> PostResponse:
    return await handler.execute(req)


@router.get(
    "/posts",
    response_model=list[PostResponse],
    status_code=200,
    responses=common_error_res,
    summary="Postデータ全件取得",
    description="Postデータを全件取得する",
    tags=["Post"],
)
async def get_posts(
    handler: Annotated[GetPostsHandler, Depends(GetPostsHandler)],
) -> list[PostResponse]:
    return await handler.execute()

from .router import router

__all__ = ["router"]

from collections.abc import AsyncIterator
from contextlib import asynccontextmanager

from fastapi import FastAPI
from fastapi.exceptions import RequestValidationError
from fastapi.middleware.cors import CORSMiddleware

from myapp.infrastructure.logger import get_logger, init_logging
from myapp.presentation.exception import (
    DatabaseError,
    db_error_exception_handler,
    general_exception_handler,
    request_validation_error_handler,
    valid_error_exception_handler,
)
from myapp.presentation.middleware import RequestMiddleware
from myapp.presentation.router import router


##########################
# アプリ全体の共通初期化処理
##########################
@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncIterator[None]:
    ############
    # 起動時処理
    ############
    # ロガーの初期化
    init_logging()

    # サーバー起動ログ出力
    logger = get_logger()
    logger.info("start server !!!")
    # アプリ起動
    yield
    ############
    # 終了時処理
    ############
    # サーバー停止ログ出力
    logger.info("stop server !!!")


#############
# ルーター設定
#############
app = FastAPI(
    lifespan=lifespan,
    title="fastapi-domain API",
    description="FastAPIによるDDD構成のAPIです。",
    version="1.0.0",
    # terms_of_service="https://example.com/terms/",
    # contact={
    # "name": "サポート",
    # "url": "https://example.com/contact/",
    # "email": "support@example.com",
    # },
    # license_info={
    # "name": "Apache 2.0",
    # "url": "https://www.apache.org/licenses/LICENSE-2.0.html",
    # },
)
app.include_router(router)

###################
# ミドルウェアの設定
###################

# 許可したいオリジン
origins = [
    "http://localhost:3000",
]

# CORS設定
app.add_middleware(
    CORSMiddleware,
    allow_origins=origins,
    allow_credentials=True,
    allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
    allow_headers=["Content-Type", "Authorization"],
)

# リクエスト用ミドルウェア
app.add_middleware(RequestMiddleware)


###################
# 例外ハンドラー設定
###################
app.add_exception_handler(RequestValidationError, request_validation_error_handler)
app.add_exception_handler(DatabaseError, db_error_exception_handler)
app.add_exception_handler(ValueError, valid_error_exception_handler)
app.add_exception_handler(Exception, general_exception_handler)

$ docker compose exec fastapi poetry run ruff format .
$ docker compose exec fastapi poetry run ruff check . --select I --fix
$ docker compose exec fastapi poetry run ruff check .
$ docker compose exec fastapi poetry run mypy .

$ docker compose down
$ docker compose build --no-cache

$ docker compose up -d

$ docker compose exec fastapi poetry add --dev pytest pytest-asyncio pytest-mock httpx

・・・

# =========================================================
# pytestの設定
# =========================================================
[tool.pytest.ini_options]
# パス設定
pythonpath = ["src"]
testpaths = ["src/tests"]

# マーカー設定
markers = [
    "unit: mark a test as a unit test",
    "integration: mark a test as an integration test"
]

$ docker compose down
$ docker compose build --no-cache
$ docker compose up -d

$ mkdir -p src/tests/domain/post
$ touch src/tests/__init__.py src/tests/domain/__init__.py src/tests/domain/post/test_text.py src/tests/domain/post/test_entity.py src/tests/domain/post/__init__.py
$ mkdir -p src/tests/application/usecase/post
$ touch src/tests/application/__init__.py src/tests/application/usecase/__init__.py src/tests/application/usecase/post/test_create_post.py src/tests/application/usecase/post/test_get_posts.py src/tests/application/usecase/post/__init__.py
$ mkdir -p src/tests/presentation/handler/post
$ touch src/tests/presentation/__init__.py src/tests/presentation/handler/__init__.py src/tests/presentation/handler/post/test_post.py src/tests/presentation/handler/post/__init__.py

import dataclasses

import pytest

from myapp.domain.post import Text


@pytest.mark.unit
class TestText:
    def test_create_text_success(self) -> None:
        text = Text("hello")
        assert text.value == "hello"
        assert str(text) == "hello"

    def test_empty_value_should_raise_error(self) -> None:
        with pytest.raises(ValueError, match="テキストの値は必須です。"):
            Text("")

    def test_over_20_chars_should_raise_error(self) -> None:
        over_text = "a" * 21
        with pytest.raises(
            ValueError, match="テキストの値は20文字以内で入力して下さい。"
        ):
            Text(over_text)

    def test_exactly_20_chars_is_ok(self) -> None:
        t = Text("a" * 20)
        assert t.value == "a" * 20

    def test_frozen_object_cannot_be_modified(self) -> None:
        t = Text("hello")
        with pytest.raises(dataclasses.FrozenInstanceError):
            t.value = "changed" # type: ignore[misc]

    def test_from_raw_should_skip_validation(self) -> None:
        raw = "a" * 100
            t = Text.from_raw(raw)
        assert t.value == raw
        assert isinstance(t, Text)

import pytest

from myapp.domain.post import Post, Text


@pytest.mark.unit
class TestPost:
    def test_create_post_success(self) -> None:
        text = Text("hello")
        post = Post(text=text, id=1)

        assert post.id == 1
        assert post.text == text
        assert isinstance(post.text, Text)

    def test_missing_text_should_raise_error(self) -> None:
        with pytest.raises(ValueError, match="textは必須です。"):
            Post(text=None) # type: ignore[arg-type]

    def test_default_id_is_zero(self) -> None:
        text = Text("hello")
        post = Post(text=text)

        assert post.id == 0

    def test_from_raw_should_skip_validation(self) -> None:
        raw_text = Text.from_raw("raw-text")
        post = Post.from_raw(raw_id=123, raw_text=raw_text)

        assert isinstance(post, Post)
        assert post.id == 123
        assert post.text == raw_text
        assert post.text.value == "raw-text"

import pytest
from pytest_mock import MockerFixture

from myapp.application.usecase.post import CreatePostUsecase
from myapp.domain.post import Post, Text
from myapp.presentation.schema.post import PostCreateRequest, PostResponse


@pytest.mark.unit
@pytest.mark.asyncio
class TestCreatePost:
    # 正常系テスト
    async def test_create_post_success(self, mocker: MockerFixture) -> None:
        # ===================
        # モック作成
        # ===================
        mock_logger = mocker.Mock()
        mock_db = mocker.Mock()
        mock_post_repo = mocker.Mock()

        # リポジトリのモック化
        mock_post_return_value = Post(text=Text("Postデータ"))
        mock_post_return_value.id = 1
        mock_post_repo.create = mocker.AsyncMock(return_value=mock_post_return_value)

        # ユースケースのモック化
        usecase = CreatePostUsecase(
            logger=mock_logger, db=mock_db, post_repo=mock_post_repo
        )

        # ===================
        # リクエストデータ作成
        # ===================
        req = PostCreateRequest(text="Postデータ")

        # ===================
        # テスト実行
        # ===================
        res = await usecase.execute(req)

        # ===================
        # 検証
        # ===================
        assert isinstance(res, PostResponse)
        assert res.id == 1
        assert res.text == "Postデータ"

        # 対象のリポジトリが1回呼ばれること
        mock_post_repo.create.assert_awaited_once()

import pytest
from pytest_mock import MockerFixture

from myapp.application.usecase.post import GetPostsUsecase
from myapp.domain.post import Post, Text
from myapp.presentation.schema.post import PostResponse


@pytest.mark.unit
@pytest.mark.asyncio
class TestGetPosts:
    # 正常系テスト
    async def test_get_posts_success(self, mocker: MockerFixture) -> None:
        # ===================
        # モック作成
        # ===================
        mock_logger = mocker.Mock()
        mock_db = mocker.Mock()
        mock_post_repo = mocker.Mock()

        # リポジトリのモック化
        mock_post_return_value = [
            Post.from_raw(raw_id=1, raw_text=Text.from_raw(raw_value="Postデータ１")),
            Post.from_raw(raw_id=2, raw_text=Text.from_raw(raw_value="Postデータ２")),
        ]
        mock_post_repo.find_all = mocker.AsyncMock(return_value=mock_post_return_value)

        # ユースケースのモック化
        usecase = GetPostsUsecase(
            logger=mock_logger, db=mock_db, post_repo=mock_post_repo
        )

        # ===================
        # テスト実行
        # ===================
        res = await usecase.execute()

        # ===================
        # 検証
        # ===================
        assert isinstance(res, list)
        assert all(isinstance(item, PostResponse) for item in res)
        assert res[0].id == 1
        assert res[0].text == "Postデータ１"
        assert res[1].id == 2
        assert res[1].text == "Postデータ２"

        # 対象のリポジトリが1回呼ばれること
        mock_post_repo.find_all.assert_awaited_once()

import pytest
from fastapi.testclient import TestClient

from myapp.main import app

client = TestClient(app)


@pytest.mark.integration
class TestPostAPI:
    def test_create_post_success(self) -> None:
        # テスト実行
        res = client.post(
            "/post",
            json={"text": "Postテキスト"},
        )

        # 検証
        assert res.status_code == 201
        assert res.json() == {"id": 0, "text": "Postテキスト"}

    def test_create_post_valid_error(self) -> None:
        # テスト実行
        res = client.post(
            "/post",
            json={"text": "aaaaabbbbbcccccddddd1"},
        )

        # 検証
        assert res.status_code == 422
        data = res.json()
        assert "String should have at most 20 characters" in data["detail"][0]["msg"]
        assert data["detail"][0]["ctx"]["max_length"] == 20

    def test_get_posts_success(self) -> None:
        # テスト実行
        res = client.get("/posts")

        # 検証
        assert res.status_code == 200
        assert res.json() == [
            {"id": 1, "text": "Postデータ１"},
            {"id": 2, "text": "Postデータ２"},
        ]

$ docker compose exec fastapi poetry run pytest -m unit 

$ docker compose exec fastapi poetry run pytest -m integration

$ mkdir -p deploy/docker/prod && touch deploy/docker/prod/Dockerfile

####################
# ビルドステージ
####################
FROM python:3.14.0-slim-trixie AS builder

# poetryをインストール
RUN pip3 install --no-cache-dir poetry

# プラグイン「poetry-plugin-export」を追加
RUN poetry self add poetry-plugin-export

WORKDIR /build

# 依存関係のみコピー
COPY pyproject.toml poetry.lock ./

# 本番環境用の依存関係のみをファイル「requirements.txt」に記述
RUN poetry export -f requirements.txt --without-hashes --only main -o requirements.txt

####################
# 実行ステージ
####################
FROM python:3.14.0-slim-trixie AS runner

# 環境変数設定
ENV ENV=production

# テスト用の環境変数設定（ローカルではコマンドで渡す必要があるため）
ARG TEST_VALUE
ENV TEST_VALUE=${TEST_VALUE}

# タイムゾーン設定
ENV TZ=Asia/Tokyo

WORKDIR /py

# 必要なパッケージをインストール
COPY --from=builder /build/requirements.txt .
RUN pip3 install --no-cache-dir -r requirements.txt

COPY ./src/myapp ./src/myapp

# 非rootユーザーを設定
RUN addgroup --system --gid 1001 appuser && \
    adduser --system --uid 1001 appuser
USER appuser

EXPOSE 9004

# k8sやCloud Runなどコンテナ単位でスケールする場合
# Uvicornのみで起動させる
CMD ["uvicorn", "myapp.main:app", "--app-dir", "src", "--host", "0.0.0.0", "--port", "9004"]

$ docker compose exec fastapi poetry add gunicorn

touch gunicorn_conf.py

import os

# サーバー設定
bind = "0.0.0.0:9004"
workers = int(os.getenv("WORKERS", "4"))
worker_class = "uvicorn.workers.UvicornWorker"

# ログ設定
loglevel = "info"
accesslog = "-" # 標準出力に出す
errorlog = "-" # 標準エラー出力に出す

####################
# ビルドステージ
####################
FROM python:3.14.0-slim-trixie AS builder

# poetryをインストール
RUN pip3 install --no-cache-dir poetry

# プラグイン「poetry-plugin-export」を追加
RUN poetry self add poetry-plugin-export

WORKDIR /build

# 依存関係のみコピー
COPY pyproject.toml poetry.lock ./

# 本番環境用の依存関係のみをファイル「requirements.txt」に記述
RUN poetry export -f requirements.txt --without-hashes --only main -o requirements.txt

####################
# 実行ステージ
####################
FROM python:3.14.0-slim-trixie AS runner

# 環境変数設定
ENV ENV=production

# テスト用の環境変数設定（ローカルではコマンドで渡す必要があるため）
ARG TEST_VALUE
ENV TEST_VALUE=${TEST_VALUE}

# タイムゾーン設定
ENV TZ=Asia/Tokyo

WORKDIR /py

# 必要なパッケージをインストール
COPY --from=builder /build/requirements.txt .
RUN pip3 install --no-cache-dir -r requirements.txt

COPY ./src/myapp ./src/myapp

# 非rootユーザーを設定
RUN addgroup --system --gid 1001 appuser && \
    adduser --system --uid 1001 appuser
USER appuser

EXPOSE 9004

# ECSなどでコンテナ一つで複数ワーカーを動かしたい場合
# （Gunicorn + UvicornWorker）の組み合わせ
COPY gunicorn_conf.py .
WORKDIR /py/src
CMD ["gunicorn", "-c", "/py/gunicorn_conf.py", "myapp.main:app"]

$ docker compose down
$ docker build --no-cache --build-arg TEST_VALUE='PROD-VALUE' -f ./deploy/docker/prod/Dockerfile -t fastapi-domain-api:latest .
$ docker run -d -p 80:9004 fastapi-domain-api:latest