DEV Community: Kaziu

OCRで名刺を一括登録する機能をつくった話 — “1ページ複数名刺”という落とし穴

Kaziu — Tue, 14 Jul 2026 11:38:57 +0000

はじめに

展示会などでたまっていく紙の名刺を、CRMに手入力するのはなかなか大変です。そこで 「名刺を詰め込んだPDF（や画像）をアップロードすると、取引先・担当者データを自動で一括登録する」 機能を実務にて作りました。

最初は「OCRに投げれば終わりだろう」と思っていたのですが、実際にやってみると OCRは意外と万能ではない こと、そして どこで処理を分けるか という設計判断が肝になることに気づかされました。この記事では、その勘所と、いちばん悩んだ 「1枚のページに複数の名刺が並んでいたらどうするか」 という問題を共有します。

全体の流れ

ファイル（PDF / JPEG / PNG）をアップロード
サーバー側でバリデーション（形式・サイズ・ページ数）
「取り込み中」の履歴レコードをつくり、すぐにレスポンスを返す
重い処理（OCR → 構造化 → 登録/更新）はバックグラウンドジョブで実行
フロントは履歴IDをポーリングして進捗を表示

ポイントは 「受付」と「処理本体」をきっぱり分ける ことです。OCRや名寄せは数十秒〜数分かかることもあるので、リクエストの中で同期的に全部やろうとするとタイムアウトします。受付APIは「ファイルを保存して履歴をつくり、ジョブを起動するところまで」で潔く終わらせます。

OCRは“2段構え”

名刺の読み取りは、実は2つの異なる処理に分かれます。

文字を読む（OCR） … 画像から文字列を抽出する。ここは Google Cloud Vision のような汎用OCRの担当。
項目に振り分ける（構造化） … 抽出したテキストのうち「どれが会社名で、どれが氏名で、どれが電話番号か」を判定する。ここは自前の項目抽出モデルの担当。

名刺画像 → ①OCR(文字を全部読む) → テキスト → ②構造化(項目に仕分け) → { 会社名, 氏名, email... }

「OCR＝構造化まで全部やってくれる」と思いがちですが、①は文字と位置を出すだけ、②はそれを項目に整理するだけ。役割が別なのです。

設計で効いたポイント

バリデーションは“中身”で判定する。
「PDFかどうか」を拡張子やContent-Typeで見ると、画像を .pdf にリネームするだけで突破されてしまいます。ファイル先頭のマジックバイトで実体を判定するのが安全です。

大きいファイルはメモリに載せない。
名刺100枚分ともなるとファイルは大きくなります。ストレージ（S3等）へ送る際は全体をメモリに読み込まず、そのままストリームで流す。サイズチェックもメタデータだけ見て、中身は読みません。

PDFのページ数チェックは軽い読み取りで。
「◯ページまで」を受付時に弾きたいだけなら、画像化ライブラリ（ImageMagick等）は重すぎます。ページ数を数えるだけならレンダリング不要で、軽量なPDFパーサでメタデータを読めば十分です。

いちばん悩んだ問題：「1ページに複数名刺」

要件を詰める中で出てきたのが、1枚のスキャン画像（PDFの1ページ）に名刺が複数枚並んでいるケースです。コピー機やフラットベッドスキャナで数枚まとめて取り込めば、当然こうなります。

OCRは“名刺単位”には分けてくれない

ここが盲点でした。汎用OCR（Vision等）は「ページ内の全文字＋各文字の位置座標」は返してくれますが、「どの文字がどの名刺のものか」を論理的に分離する機能はありません（Google Cloud Vision の公式ドキュメントにも、1ページ上の複数文書を識別・分離する組み込み機能はなく、ブロックの位置を解析する独自ロジックが必要、と明記されています）。

さらに、OCRの「ブロック（文字の塊）」は レイアウト上の近接 でまとめられるため、隣り合う名刺が1つに融合したり、1枚の名刺が複数に割れたりします。「1ブロック＝1名刺」にはなりません。

構造化モデルも「名刺1枚分のテキスト」を仕分ける前提なので、複数名刺のテキストが混ざったまま渡すと、「A社の会社名＋B氏の氏名」が合体した誤ったデータが生まれてしまいます。

つまり「名刺ごとに切り分ける工程」を自前で挟む必要がある

OCR(全文字＋座標) → 【自前】名刺ごとに切り分け → 名刺A分 → 構造化
                                            → 名刺B分 → 構造化 → …

この切り分けの難易度は、名刺の並び方で大きく変わります。

並び方	アプローチ	難易度
固定テンプレート（常に2×3等）	ページを決め打ちで等分	低（ただし全ユーザーが同じ並べ方を強制される）
整然と並ぶが枚数可変	座標の“すき間”から行・列を動的に検出	中（ルールベース。傾き・密着・空きマスに弱い）
完全にバラバラ	名刺領域を検出するAIモデルを用意	高（モデルの学習・運用が必要）

真ん中の「座標から格子を推測する」方法は、こんなイメージのルールベース処理です。

すべての文字の座標を集める
X座標の大きなすき間を「列の境界」とみなす
Y座標の大きなすき間を「行の境界」とみなす
各マスを1名刺として、文字をグルーピングする

AIではなく幾何計算なので比較的軽い一方、傾き・名刺同士の密着・不揃いなサイズ・空きマスがあると崩れます。堅牢にするほど実データでのチューニングが必要になり、突き詰めると「AIで名刺そのものを検出する」方向に近づいていきます。

学び：仕様側で“制約”できると一気にラクになる

技術で無理にバラバラ配置へ対応するよりも、「名刺は等間隔に並べてスキャンしてください」といった入力の制約を設けるほうが、開発コストも精度リスクも大きく下がります。「どこまでの入力を許すか」はエンジニアだけで決めず、プロダクト側と早めにすり合わせるべき論点でした。

重複データの扱い（名寄せ）

一括登録では「すでに登録済みの取引先/担当者」との重複が避けられません。ここは

取引先は「会社名」または「会社名＋住所」で一致判定（支店を区別したいニーズもあるため住所も選べる）
担当者はメールアドレスで一致判定

を事前に選ばせ、ヒットしたものは更新、しなかったものは新規登録として扱います。「重複時に既存データを名刺の値で上書きするか」もユーザーが選べるようにしました（勝手に上書きされたくないニーズがあるため）。

まとめ

OCRは「文字を読む」＋「項目に仕分ける」の2段構え。OCRだけで構造化まで完結はしない。
受付と処理本体を分離し、重い処理は非同期ジョブへ。大容量ファイルはストリーム、バリデーションは中身で。
最大の落とし穴は 「1ページ複数名刺」。OCRは名刺単位に分けてくれないので切り分けは自前実装が必要で、並び方次第で難易度が激変する。
だからこそ 「入力をどこまで制約できるか」をプロダクトと握ることが、技術選定と同じくらい重要。

“OCRに投げるだけ”に見える機能ほど、実は要件と制約の設計が肝になる——という良い事例でした。

(後日談)

さんざん「1ページに複数名刺だったらどう切り分けるか…」と唸っていたのですが、プロダクト側に確認したら——

「PDFは1ページに名刺1枚の想定です」

……でした。盛大な取り越し苦労。笑

しかし勉強にはなりました。技術で殴る前に、まず要件を疑う。良い教訓になりましたわい。

Elastic search

Kaziu — Mon, 13 Apr 2026 05:56:56 +0000

(自分用メモ)

Mysqlとの違い

MySQL	ES
データベース	index
行(１件のデータ)	document
カラムの型	mapping

なので「インデックス再構築」はデータベース作り直しってイメージ

データの形

ESはJSON

{
    "deal": {
      "id": 1,
      "name": "TOYOTAへの提案",
      "has_materials": true
    }
  }

検索クエリの書き方

基本形

GET index name/_search
{
  "query": {
    ここに条件を書く
  }
}

query はSQLの WHERE 句

完全一致で検索したいっす (term)

SQLでいうと
WHERE has_materials = true

{
  "query": {
    "term": { "deal.has_materials": true }
  }
}

複数の条件をANDでつなぎたい (= bool + filter)

SQLでいうと
WHERE has_materials = true AND invoice_id = 3

{
  "query": {
    "bool": {
      "filter": [
        { "term": { "deal.has_materials": true } },
        { "term": { "deal.invoice.id": 3 } }
      ]
    }
  }
}

bool + filter の配列に条件を並べるとAND

テキストを部分一致で検索したい（= match）

SQLでいうと
WHERE name LIKE '%トヨタ%'

{
  "query": {
    "match": { "deal.name": "トヨタ" }
  }
}

マッピングって何ですの？

MySQLの「カラムの型定義（int, varchar...）」と同じ。
フィールドの型をあらかじめ宣言しておくもの。

{
  "deal": {
    "id":            { "type": "integer" },
    "name":          { "type": "text" },
    "has_materials": { "type": "boolean" }
  }
}

mapping変更したら？

インデックス作り直しですわ

NestJSの基本アーキテクチャと実プロジェクトでの活用事例

Kaziu — Wed, 18 Feb 2026 04:57:00 +0000

※ 本記事に掲載しているコード例は実際のプロダクトをベースにしていますが、プロジェクト名・サービス名・変数名など、特定のプロダクトを識別できる情報は変更・汎用化して記載しています。

(０から全部自分で書いてなく、AI生成したのを修正しプロジェクトの辞書の様に使用する目的)

NestJSはTypeScriptで構築されたサーバーサイドフレームワークで、Angularに影響を受けたモジュール指向のアーキテクチャが特徴です。本記事ではNestJSの基本概念を解説しつつ、実際のSaaSプロダクト（GraphQL API / マルチテナント構成）でどのように活用しているかを紹介します。

(*追記)↑って立派に書いたけど、そのプロジェクトあまり従事しなかったので、この記事のことあんま頭に入ってないです笑

1. Module（モジュール）

NestJSの基本

NestJSのアプリケーションは Module を単位として構成されます。@Module() デコレータで providers（提供するサービス）、imports（依存するモジュール）、exports（外部に公開するサービス）を定義し、DIコンテナを構成します。

@Module({
  providers: [CatService],
  imports: [DatabaseModule],
  exports: [CatService],
})
export class CatModule {}

実プロジェクトでの活用

本プロジェクトでは、レイヤードアーキテクチャに沿って3層のモジュールに分離しています。

app.module.ts
  ├─ ResolverModule群（interface/di/）  ← プレゼンテーション層
  ├─ UseCaseModule群（app/di/）         ← アプリケーション層
  └─ RepositoryModule群（infra/prisma/di/） ← インフラ層

ディレクトリ構成は以下のようになっています。

packages/api/src/
├── app/                      # Application層
│   ├── di/                   # UseCaseモジュール定義
│   └── useCases/             # UseCase実装
├── domain/                   # Domain層
│   ├── entities/             # ドメインエンティティ・型定義
│   ├── restrictFilters/      # 権限フィルター
│   └── common/               # 共通型・ユーティリティ
├── interface/                # Interface層
│   ├── di/                   # Resolverモジュール定義
│   ├── resolvers/            # GraphQL Resolver
│   ├── schema/               # リクエスト/レスポンス型
│   └── auth/                 # 認証Guard
├── infra/                    # Infrastructure層
│   ├── prisma/               # Repository・Mapper
│   └── ...                   # 外部サービス連携
└── entities/                 # GraphQL ObjectType定義

ResolverModuleは、UseCaseModuleを imports して依存を解決します。

@Module({
  providers: [CommentResolver],
  imports: [
    CommentUseCaseModule,
    UserUseCaseModule,
  ],
})
export class CommentResolverModule {}

UseCaseModuleは、RepositoryModuleや他のServiceModuleを imports します。

@Module({
  providers: [CommentUseCase],
  exports: [CommentUseCase],
  imports: [
    PrismaCommentRepositoryModule,
    PrismaRoomRepositoryModule,
    NotificationServiceModule,
  ],
})
export class CommentUseCaseModule {}

ポイント: NestJSのModule機構を活用して、クリーンアーキテクチャ的な依存の方向（interface → app → domain ← infra）を実現しています。

2. Controller / Resolver

NestJSの基本

REST APIの場合は @Controller() に @Get() / @Post() などのデコレータを使います。

@Controller('cats')
export class CatController {
  @Get()
  findAll() { return 'All cats'; }

  @Post()
  create(@Body() dto: CreateCatDto) { ... }
}

GraphQLの場合は @Resolver() に @Query() / @Mutation() / @ResolveField() を使います。

実プロジェクトでの活用

本プロジェクトではGraphQLを採用し、Code-Firstアプローチでスキーマを自動生成しています。

// app.module.ts
GraphQLModule.forRoot<ApolloDriverConfig>({
  driver: ApolloDriver,
  autoSchemaFile: join(process.cwd(), 'src/schema.gql'), // TypeScriptから自動生成
  fieldResolverEnhancers: ['guards'],
}),

Resolverの実装例：

@Resolver(() => GqlComment)
export class CommentResolver {
  constructor(private readonly commentUseCase: CommentUseCase) {}

  // Query: データ取得
  @UseGuards(AuthGuard)
  @Query(() => [GqlComment])
  async commentList(
    @Args('input') input: GetCommentListInput,
    @Context() context: OperationContext,
  ) {
    return this.commentUseCase.getCommentList(input, context);
  }

  // Mutation: データ変更
  @UseGuards(AuthGuard)
  @Mutation(() => GqlComment)
  async createComment(
    @Args('input') input: CreateCommentInput,
    @Context() context: OperationContext,
  ) {
    return this.commentUseCase.createComment(input, context);
  }

  // ResolveField: ネストされたフィールドの解決
  @ResolveField('author', () => GqlUser)
  async getAuthor(@Parent() comment: Comment) {
    return this.userUseCase.findOne({ id: comment.userId });
  }
}

主なデコレータ

デコレータ	用途
`@Resolver(() => Type)`	クラスをResolver宣言
`@Query(() => Type)`	GraphQL Query定義
`@Mutation(() => Type)`	GraphQL Mutation定義
`@ResolveField('name', () => Type)`	ネストフィールドの解決
`@Args('input')`	入力引数のバインド
`@Parent()`	親オブジェクトへのアクセス
`@Context()`	GraphQL Context（認証情報等）の取得

InputType（リクエスト型）

GraphQLの入力型もデコレータで定義します。

@InputType()
export class CreateCommentInput {
  @Field(() => GraphQLJSON)
  content: Prisma.JsonObject;

  @Field()
  roomId: string;

  @Field(() => [Int], { nullable: true })
  imageIds?: number[];
}

これにより、以下のGraphQLスキーマが自動生成されます。

input CreateCommentInput {
  content: JSON!
  roomId: ID!
  imageIds: [Int!]
}

3. Service / UseCase

NestJSの基本

@Injectable() デコレータを付けたクラスをServiceとして使い、ビジネスロジックを集約します。

@Injectable()
export class CatService {
  constructor(private readonly catRepository: CatRepository) {}

  findAll() {
    return this.catRepository.findAll();
  }
}

実プロジェクトでの活用

本プロジェクトでは「Service」ではなく 「UseCase」 と命名し、ユースケース単位でクラスを分割しています。

@Injectable()
export class CommentUseCase {
  constructor(
    private readonly commentRepository: PrismaCommentRepository,
    private readonly roomRepository: PrismaRoomRepository,
    private readonly notificationService: NotificationService,
  ) {}

  async createComment(input, context: OperationContext) {
    // 1. ドメイン検証
    const room = CoreAssert.isNotEmpty(
      await this.roomRepository.findOneById({ id: input.roomId }, context),
    );

    // 2. ドメインエンティティ作成
    const comment = createCommentSeed({
      ...input,
      userId: context.executor.userId,
    });

    // 3. DB保存
    const created = await this.commentRepository.create(comment);

    // 4. 通知・外部連携
    await this.notificationService.send({ ... });

    return created;
  }
}

ポイント: UseCase内でドメイン検証 → DB保存 → 副作用（通知・外部連携）の順で処理を組み立てています。Repositoryや外部サービスは全てコンストラクタインジェクションで注入されるため、テスタビリティが高いです。

4. DI（依存性注入）

NestJSの基本

NestJSのDIは、TypeScriptの型情報からプロバイダーを自動解決します。@Injectable() クラスをModuleの providers に登録し、コンストラクタの型で自動注入されます。

実プロジェクトでの活用

層をまたぐ依存は imports / exports で制御しています。

Resolver → constructor(useCase: CommentUseCase)     // 型で自動解決
UseCase  → constructor(repo: PrismaCommentRepository) // 型で自動解決

Module定義側：

// UseCaseModule: CommentUseCaseを外部に公開
@Module({
  providers: [CommentUseCase],
  exports: [CommentUseCase],          // 他のモジュールから利用可能に
  imports: [PrismaCommentRepositoryModule],
})
export class CommentUseCaseModule {}

// ResolverModule: UseCaseModuleをimportして利用
@Module({
  providers: [CommentResolver],
  imports: [CommentUseCaseModule],    // CommentUseCaseが利用可能に
})
export class CommentResolverModule {}

循環依存が発生する場合は forwardRef() で回避します。

@Module({
  imports: [forwardRef(() => RelatedModule)],
})
export class SomeModule {}

5. Guard（認証・認可）

NestJSの基本

CanActivate インターフェースを実装したGuardクラスを作成し、@UseGuards() デコレータで適用します。

@Injectable()
export class AuthGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    const request = context.switchToHttp().getRequest();
    return validateToken(request.headers.authorization);
  }
}

実プロジェクトでの活用

本プロジェクトはマルチユーザー型SaaSのため、ユーザータイプ（管理者 / ゲスト）に応じて異なる認証Guardを振り分けるパターンを採用しています。

@Injectable()
export class MultiUserAuthGuard implements CanActivate {
  constructor(
    private readonly adminAuthGuard: AdminAuthGuard,
    private readonly guestAuthGuard: GuestAuthGuard,
  ) {}

  async canActivate(context: ExecutionContext): Promise<boolean> {
    const ctx = GqlExecutionContext.create(context);
    const request = ctx.getContext().req;
    const userType = request.headers['x-user-type'];

    if (userType === 'Admin') {
      // JWT検証（外部認証サービス）
      return this.adminAuthGuard.canActivate(context);
    } else if (userType === 'Guest') {
      // セッショントークン検証
      return this.guestAuthGuard.canActivate(context);
    }

    throw new UnauthorizedException();
  }
}

さらに @ResolveField レベルでの細かい権限制御も実装しています。

@ResolveField('author', () => GqlUser)
@UseGuards(UserTypesGuard)
@RequiredUserTypes('ADMIN')  // カスタムデコレータでメタデータ指定
async getAuthor(@Parent() comment: Comment) {
  return this.userUseCase.findOne({ id: comment.userId });
}

UserTypesGuard は Reflector を使ってメタデータを読み取り、権限チェックを行います。

@Injectable()
export class UserTypesGuard implements CanActivate {
  constructor(private reflector: Reflector) {}

  canActivate(context: ExecutionContext): boolean {
    const requiredTypes = this.reflector.get<string[]>(
      'requiredUserTypes',
      context.getHandler(),
    );
    if (!requiredTypes) return true;

    const gqlContext = GqlExecutionContext.create(context);
    const user = gqlContext.getContext().req.user;
    return requiredTypes.includes(user.executor.userType);
  }
}

6. Entity定義の多層構造

NestJSの基本

一般的なNestJSアプリケーションでは、1つのEntityクラスがDB定義とAPI定義を兼ねることが多いです。

実プロジェクトでの活用

本プロジェクトでは3層のEntity定義を使い分けています。

層	ファイル例	用途
GraphQL Entity	`entities/Comment.entity.ts`	`@ObjectType()` でAPI出力型を定義
Domain Entity	`domain/entities/Comment/index.ts`	Brand型による型安全なビジネスモデル
Prisma Model	`prisma/schema.prisma`	DBスキーマ定義

GraphQL Entity（API層）

@ObjectType()
export class Comment {
  @Field(() => Int)
  id: number;

  @Field(() => GraphQLJSON)
  content: Prisma.JsonObject;

  @Field()
  createdAt: Date;

  @Field(() => [CommentImage])
  commentImages: CommentImage[];  // ネストフィールド
}

Domain Entity（ドメイン層）

Brand型を使って、同じ number 型でもIDの種類を区別します。

// Brand型の定義
type Brand<T, U> = T & { __brand: U };

// IDを型レベルで区別
export type CommentId = Brand<number, 'CommentId'>;
export type UserId = Brand<number, 'UserId'>;

// 型エラー: CommentId と UserId は互換性がない
const commentId: CommentId = 1 as CommentId;
const userId: UserId = commentId; // コンパイルエラー!

ドメインエンティティの定義：

export type Comment = {
  id: CommentId;
  content: Prisma.JsonObject;
  roomId: RoomId;
  userId: UserId;
  tenantId: TenantId;
  createdAt: Date;
  updatedAt: Date;
};

// ファクトリ関数
export const createCommentSeed = (payload: CommentSeed): CommentSeed => {
  return { ...payload };
};

Prisma Model（DB層）

model Comment {
  id        Int       @id @default(autoincrement())
  content   Json?
  roomId    String
  Room      Room      @relation(fields: [roomId], references: [id], onDelete: Cascade)
  userId    Int
  createdAt DateTime  @default(now())
  updatedAt DateTime  @default(now()) @updatedAt
}

ポイント: 3層に分けることで、API仕様の変更がドメインロジックに影響しない、DBスキーマの変更がAPI層に漏れないという利点があります。

7. Prisma連携（Repository + Mapper）

NestJSの基本

NestJSではTypeORMやPrismaを直接サービスから利用するのが一般的です。

実プロジェクトでの活用

本プロジェクトではRepository + Mapperパターンを採用し、Prismaの型をドメイン型に変換しています。

Repository

@Injectable()
export class PrismaCommentRepository {
  async create(input: CommentSeed, db = client): Promise<Comment> {
    const prismaComment = await db.comment.create({
      data: {
        contentJson: input.content,
        roomId: input.roomId,
      },
      include: { Room: true },
    });

    // Prisma型 → Domain型への変換
    return PrismaCommentMapper.toDomainComment(prismaComment);
  }

  async findList(input, context, db = client): Promise<Comment[]> {
    const results = await db.comment.findMany({
      where: {
        roomId: input.roomId,
        Room: { tenantId: context.tenantId }, // テナント隔離
      },
      orderBy: { createdAt: 'asc' },
    });
    return results.map(PrismaCommentMapper.toDomainComment);
  }
}

Mapper

export class PrismaCommentMapper {
  static toDomainComment(prismaComment): Comment {
    return {
      id: prismaComment.id as CommentId,
      content: prismaComment.contentJson as Prisma.JsonObject,
      roomId: prismaComment.roomId as RoomId,
      userId: prismaComment.userId as UserId,
      tenantId: prismaComment.Room.tenantId as TenantId,
      createdAt: prismaComment.createdAt,
      updatedAt: prismaComment.updatedAt,
    };
  }
}

トランザクション

複数テーブルにまたがる操作は prisma.$transaction() で原子性を保証します。

const result = await prisma.$transaction(async (db) => {
  const room = await this.roomRepository.create(roomData, context, db);
  await this.memberRepository.create(memberData, db);
  return room;
});

ポイント: Repositoryメソッドはオプショナルな db 引数を受け取り、トランザクション内でもスタンドアロンでも動作するよう設計されています。

8. 認証コンテキストの流れ

マルチテナントSaaSにおける認証情報の伝搬フローです。

1. GraphQLリクエスト
   ├─ Header: Authorization: "Bearer <JWT>"
   └─ Header: x-user-type: "Admin" or "Guest"

2. Guard（認証処理）
   ├─ Admin → JWT検証 → OperationContext生成
   └─ Guest → セッション検証 → OperationContext生成
   └─ request.user = OperationContext にセット

3. Resolver
   └─ @Context() context: OperationContext で取得

4. UseCase / Repository
   └─ contextを利用した権限制御・テナント隔離

OperationContext はZodスキーマで型安全に定義されています。

export const operationContextSchema = z.object({
  tenantId: tenantIdSchema,
  executor: z.union([
    z.object({
      userType: z.literal('ADMIN'),
      userId: userIdSchema,
      role: roleSchema,
    }),
    z.object({
      userType: z.literal('GUEST'),
      userId: userIdSchema,
    }),
  ]),
});

export type OperationContext = z.infer<typeof operationContextSchema>;

カスタムデコレータ @Context() でResolverに注入します。

export const Context = createParamDecorator(
  (data: unknown, context: ExecutionContext) => {
    const ctx = GqlExecutionContext.create(context);
    return ctx.getContext().req.user as OperationContext;
  },
);

権限フィルターでDB操作時のテナント隔離を行います。

export const commentRestrictFilter = (
  context: OperationContext,
): Prisma.CommentWhereInput[] => {
  return [{ Room: { tenantId: context.tenantId } }];
};

// 使用例
const comments = await prisma.comment.findMany({
  where: { AND: commentRestrictFilter(context) },
});

9. まとめ：NestJS標準 vs 実プロジェクト

観点	NestJS標準	実プロジェクト
API方式	REST (`@Controller`)	GraphQL Code-First (`@Resolver`)
ビジネスロジック	Service	UseCase（ユースケース単位で分割）
データアクセス	ORM直接利用	Repository + Mapper パターン
認証	単一Guard	MultiUser振り分けGuard
型安全	TypeScript標準	Brand型 + Zod バリデーション
テナント隔離	なし	OperationContext + RestrictFilter
Entity	単一定義	3層（GraphQL / Domain / Prisma）
Module構成	機能単位	レイヤー単位（Resolver / UseCase / Repository）

おわりに

NestJSはそのままでも十分に強力なフレームワークですが、プロジェクトの規模や要件に応じてアーキテクチャをカスタマイズできる柔軟性も持っています。

本プロジェクトでは、NestJSのDI機構を活かしつつ、以下のような工夫を加えています。

レイヤードアーキテクチャ: Module単位でレイヤーを分離し、依存の方向を制御
Code-First GraphQL: TypeScriptのデコレータからスキーマを自動生成
Brand型: IDの取り違えをコンパイル時に検出
RestrictFilter: マルチテナントのデータ隔離をパターン化

NestJSの基本概念（Module / DI / Guard / Decorator）を理解しておけば、プロジェクトの要件に合わせた拡張も容易です。ぜひ参考にしてみてください。

たった1枚の引き伸ばされた画像から、AWS Lambdaのコード移行とCI/CD構築に至った話

Kaziu — Sat, 08 Nov 2025 00:42:07 +0000

始まり

ある日、開発中の画面でサムネイル画像が不自然に引き伸ばされて表示されていることに気づきました。

「ああ、このパターンな。CSSのobject-fitがcoverになってるのをcontainにすれば直るやつじゃ」

そう高を括ってコードを修正。しかし、表示は変わらず引き伸ばされたまま。ブラウザの開発者ツールで画像のURLを直接開いてみると、Amazon S3から返されている画像そのものが既に引き伸ばされていました

「まじすか先輩」

しかし、わしはプロジェクトに参加したばかりでしかもインフラはよぉ知らん。該当の画像生成処理がどこに書かれているのか見当もつきませんので同僚に聞いてみましたわ

「すんまへん、このサムネイル画像、どうもAWS側でリサイズされてるっぽいんですが、どこの処理か分かりますか？」

すると、同僚から

「ああ、その処理は別のインフラ用リポジトリにあるLambda関数がやってるんですよ。ただ、そのリポジトリを直接編集しても意味なくて、今のアプリケーション用リポジトリにコードを移行して、CI/CDを再設定する必要があるんですわこりゃ」

わしの頭の中は「あーLambda聞いたことあるわー、awsのやつじゃわー」て感じでしたが、とりあえずやってみました。

STEP1: Lambdaてそもそもなんですの？

これは「特定のイベントをきっかけに、自動で動いてくれる小さなプログラム」で、サーバーの管理を自分でする必要がない「サーバーレス」という仕組みの一つで、例えば以下のようなイベントをきっかけに処理を実行できます。

Amazon S3にファイルがアップロードされた時
API Gatewayにリクエストが来た時
特定の時間になった時 (cronのように)

今回のケースでは、「S3バケットにオリジナル画像がアップロードされたら、Lambda関数が起動してサムネイル画像を生成し、別のS3バケットに保存する」という処理が行われていたのです。これなら、画像が引き伸ばされている原因も、Lambda関数のコードを修正すれば解決できそうです

STEP 2: Lambda関数の移行とCI/CDの構築

旧インフラリポジトリから、Lambda関数のソースコードを現在のアプリケーションリポジトリに持ってくる。
持ってきたコードを修正し、画像が引き伸ばされないようにする。（今回はリサイズのロジックを修正、resize methodをthumbnail methodに変）
コードが更新されたら、自動でAWS上のLambda関数にデプロイされる仕組み（CI/CD）をGitHub Actionsで構築する。

▼ GitHub ActionsでLambdaに自動デプロイ
GitHub Actionsのワークフローを使い、特定のブランチ（例: main）にコードがプッシュされたら、自動でAWS Lambdaにデプロイされるように設定します。.github/workflowsの中に設定します

# sample code
name: Deploy to AWS Lambda

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'デプロイ先の環境を選択してください'
        required: true
        type: choice
        options:
          - release-candidate
          - staging
          - production

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ github.event.inputs.environment }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      # ... (Node.jsやPythonのセットアップ、依存パッケージのインストールなど) ...

      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v2
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: ap-northeast-1

      - name: Build and Zip
        run: |
          # ビルドやパッケージングの処理
          zip -r function.zip .

      - name: Deploy to Lambda
        run: |
          aws lambda update-function-code \
            --function-name ${{ secrets.YOUR_LAMBDA_FUNCTION_NAME }} \
            --zip-file fileb://function.zip

このワークフローのポイントは2つです

1. 環境に応じたSecretsの利用

GitHubリポジトリの Settings > Environments で release-candidate, staging, production の各環境がありました。なのでそれぞれの環境のSecretsに YOUR_LAMBDA_FUNCTION_NAMEというキーで、対応するLambda関数名（例: rc-YourLambdaFunctionName）を登録しておきます。
ワークフローが実行されると、選択された環境に応じて適切な関数名が自動で読み込まれるため、デプロイ先を間違えるリスクを低減できます。

2. 手動トリガーによる安全なデプロイ

on: push を使わず on: workflow_dispatch を使うことで、意図しない自動デプロイを防ぎます。開発者はGitHubのActionsタブから「Run workflow」ボタンを押し、デプロイしたい環境を選択するだけで、安全かつ確実にリリース作業を行えます。

🔥 つまずきポイント：GitHub Actionsの「Run workflow」が表示されない！

ワークフローを作成し、いざ手動で実行テストをしようとした時のことです。GitHubリポジトリのActionsタブを見ても、手動実行ボタンである「Run workflow」が表示されません。

原因は単純で、workflow_dispatch を含むワークフローファイルが、リポジポジトリのデフォルトブランチ（mainやmaster）にマージされていないと、手動実行のUIは表示されないという仕様でした。
開発ブランチでいくら試行錯誤してもボタンは現れません。この仕様を知らずに、githubと戦っておりました

まとめ

たった1枚の引き伸ばされた画像でしたが、AWS Lambda、そしてCI/CDの世界に飛び込めました

表示の不具合は、必ずしもフロントエンド、バックエンドが原因とは限らない。
AWS Lambdaは、イベント駆動で動く便利な自動処理プログラム。
ワークフローの手動実行（workflow_dispatch）は、デフォルトブランチでしか有効にならない。

てなわけでバグも修正され、気持ちよくなりましたわ〜

A better way to call functions in a child component from a parent component in React

Kaziu — Thu, 06 Mar 2025 07:49:18 +0000

❓Question

// should define in child component (<Body>) 
//   to follow the Container-Presenter pattern, but how?
const handleUpdate = useCallback(() => {
  hoge()
}, [])

return (
  <Body />
  <Footer>
    <Button onCliCk={handleUpdate} />
  <Footer />
)

ChatGPT's answer

In this situation, ChatGPT might suggest using useRef and useImperativeHandle, which works, but there is a better way, I think.

That approach often adds complicated code, and some engineers may not be familiar with them

My answer

set a useState in parent component to store function states, and assign functions themselves in initial useEffect in child component

▼ Parent component

const [{handleUpdate, ....}, setHandlers] = useState({
  handleUpdate: undefined,
  hoge: undefined,
  .........
})

return (
  <Body setHandlers={setHandlers} />
  <Footer>
    <Button onCliCk={handleUpdate} />
  <Footer />
)

▼ Child component <Body>

const onUpdate = useCallback(() => {
  update()
}, [])

useEffect(() => {
  setHandlers({
    handleUpdate: onUpdate,
    hoge: onHoge,
    .............
  })
},[])

It would be simpler than using useRef and useImperativeHandle.
This pattern is kind of Function Injection

Your answer

what do you think?

Things to watch out for when using multiple ag-Grids on the same page

Kaziu — Thu, 13 Feb 2025 01:37:15 +0000

(I took notes because multiple ag-Grids on a single page didn't work well)

When I was trying to create multiple ag-grid' table on same page by map() function of javascript, data was overwritten by last one.

the solution is to pass gridOptions as different referenced objects.
(I used spread operator)

// react
{
  items.map((item) => (
    <AgGrid
      gridOptions={{...gridOptions}}
      (others....)
    />
  )
}

▼ issue
looks still this bug doesn't fixed (2025/2/13), or it's just specification? 仕様ですかい？
https://github.com/ag-grid/ag-grid/issues/3354

▼ ag-grid
frontend table library
https://www.ag-grid.com/

Modal with ReactDOM.createPortal

Kaziu — Wed, 20 Nov 2024 00:07:38 +0000

https://react.dev/reference/react-dom/createPortal

What is that

We can specify DOM element for rendering

When we could use it

For example, If we want to write <Modal /> component in some component, but want to rendering other parent component (ex. document.body)

We could write Modal, Popover component easily ignoring parent CSS effect like overflow: hidden.

And no matter what it is, easy to read code.

Example

this is example that modal opens center of window by using createPortal

import React, { useState } from 'react';
import ReactDOM from 'react-dom';

function Modal({ isOpen, onClose, children }) {
  if (!isOpen) return null;

  return ReactDOM.createPortal(
    <div style={styles.overlay}>
      <div style={styles.modal}>
        {children}
        <button onClick={onClose} style={styles.closeButton}>Close</button>
      </div>
    </div>,
    document.body // ⭐️ the rendering destination of Portal
  );
}

export default function App() {
  const [isModalOpen, setIsModalOpen] = useState(false);

  return (
    <div>
      <button onClick={() => setIsModalOpen(true)}>Open Modal</button>
      <Modal isOpen={isModalOpen} onClose={() => setIsModalOpen(false)}>
        <h1>Hello, Modal!</h1>
      </Modal>
    </div>
  );
}

const styles = {
  overlay: {
    ⭐️ position: 'fixed',
    ⭐️ top: 0,
    ⭐️ left: 0,
    ⭐️ width: '100vw',
    ⭐️ height: '100vh',
    backgroundColor: 'rgba(0, 0, 0, 0.5)',
    display: 'flex',
    justifyContent: 'center',
    alignItems: 'center',
    zIndex: 1000,
  },
  modal: {
    ...
  },
  closeButton: {
    ...
  },
};

define type of 'hoge_hoge_1' in typescript

Kaziu — Mon, 18 Nov 2024 23:13:32 +0000

I had a opportunity to define like this type hoge_hoge_1 which last character changes of number as string.

How to do

1. define `hoge_hoge` in the string.

this is easy, just add type of with template literal

${typeof 'hoge_hoge'}

2. define number which change as string.

number can define like this

type Number = number

in this time I need to define number as string, so just add template literal

type Number = `${number}`

▼ This is final code

const PREFIX_ITEM_NAME = "hoge_hoge"

type NumericString = `${number}`
type HogeItemName =
  `${typeof PREFIX_ITEM_NAME}_${NumericString}`

Problem

On my editor (webstorm), some errors appeared

I found that it is supported starting from TypeScript 4.1.
So I just fixed my setting of my editor and everything changed fine 😀

Explain what is higher order function by Pikachu

Kaziu — Wed, 06 Dec 2023 09:45:29 +0000

What is higher order function?

function that take in a function as an argument
function that returns a function

-> I'm gonna explain by using 2 in this time

Super simple Higher order function

This might be simplest example.
function getPikachu() returns a function which invoke console.log()

function getPikachu() {
  return function() {
    console.log('10000 volts!')
  }
}

Now please guess what is the result of this code?

❓
const pikachu = getPikachu()

the answer is getting definition of function

function () {
  console.log('10000 volts!')
}

What if we want to get string of '10000 volts!'?
Just invoke this function by adding ()

const pikachu = getPikachu()
pikachu() // '10000 volts!'

▼ Difference between pikachu and pikachu()

pikachu : just definition
pikachu() : invoke this definition ⚡⚡⚡⚡⚡⚡⚡⚡⚡

The other way to invoke function

Actually you can invoke function in different way.

getPikachu()

As you already know, when you execute getPikachu(), you get definition of function.
And now How do you invoke function? adding () right?
Yeah so if you add () to getPikachu(), you can get string 10000 volts!

getPikachu()() // '10000 volts!'

It looks a bit weird at first time, but if you think logically with higher other function, it's gonna be so simple.

What is "return" in useEffect

Kaziu — Sat, 02 Dec 2023 08:52:48 +0000

Clean up function

There is like this code

useEffect(() => {
  console.log('effect execute !!')
  return () => {
    console.log('in return function')
  };
}, [something]);

this function of return is called clean up function

When does clean up function execute

When component unmounts
Just Before useEffect executes

Real life example

useEffect(() => {
  document.addEventListener('keydown', handleKeyDown);
}, [something]);

If you write this code, keydown event adds every time when something changes. At the worst case, it causes a memory leak

so you should add clean up function, to remove event just before useEffect executes (= after state of something changes)

useEffect(() => {
  document.addEventListener('keydown', handleKeyDown);
  return () => {
    document.removeEventListener('keydown', handleKeyDown);
  };
}, [something]);

Difference between Logical OR (||) and Nullish coalescing operator(??)

Kaziu — Thu, 03 Aug 2023 05:45:30 +0000

Have you came across like this situation ?

obj.name ? obj.name : "I don't know"

If you so, better write code like that

obj.name || "I don't know"

|| is called Locgical OR. When left-hand is undefined or null returns right-hand

🤔 Is it the same as ??

?? is called Nullish coalescing operator, it's like Logical OR except falsy values like "", 0

// example
const obj = {
  zero: 0,
  one: 1,
  emptyString: '',
  null: null,
  undefined: undefined,
}

console.log(obj.zero || 'Hello')// Hello
⭐ console.log(obj.zero ?? 'Hello')// 0

console.log(obj.one || 'Hello')// 1
console.log(obj.one ?? 'Hello')// 1

console.log(obj.emptyString || 'Hello')// Hello
⭐ console.log(obj.emptyString ?? 'Hello')// ""

console.log(obj.null || 'Hello')// Hello
console.log(obj.null ?? 'Hello')// Hello

console.log(obj.undefined || 'Hello')// Hello
console.log(obj.undefined ?? 'Hello')// Hello

So the reason why I wrote you should use || is that normally you just need to recognise "undefined" or "null" in that case, not falsy value.

it's just my opinion and of course it depends on situation!

17 Frontend code reviews in real project (react, typescript)

Kaziu — Tue, 25 Apr 2023 07:33:11 +0000

mainly javascript/typescript and react, let's get start it

💎 1. Use `date-fns` instead of `moment`

moment weights 241kb which is so heavy, and before checking this PR, I've known that date-fns exists in this project so proposed this one.
Besides in our slack, I found engineers had already talked about it even long time ago, like We wanna remove moment someday

you can use no-restricted-imports option of ESLint in your project just like this

💎 2. Don't use magic number

there was like this code

const handleHogeChange = () => {
  setIsOpen(false)
  setTimeout(() => {
    // do something
  }, 170)
}

magic number in this code is 170, if other engineer see this code at first time, they couldn't get what it is asap.
↓

const HOGE_TRANSITION = 170

const handleHogeChange = () => {
  setIsOpen(false)
  setTimeout(() => {
    // do something
  }, HOGE_TRANSITION)
}

(actually this HOGE_TRANSITION is assigned in other const define file, but now I just wrote like that to get easily)

💎 3. DRY

Don't Repeat Yourself
If you don't know this one, you would find easily on the internet what it is

💎 4. Don't pass useState to child component

when you want to change state in child component, you shouldn't pass useState to child component directory. Because it makes so hard to get in which component this state is controlled.

↓ so just use callback function like this
https://www.webtips.dev/solutions/pass-data-from-child-to-parent-in-react

💎 5. Don't use type `any` in event argument in React

I found like this code

onClick={(e: any) => handleActionClick(e, action.id)}

and I thought engineer have tried code like that once

but as you can see error appeared and he gave up.
(just my imagination though lol)

React prepares own event for support cross browser, so you should use it
https://reactjs.org/docs/events.html#mouse-events

onClick={(e: React.MouseEvent) => handleActionClick(e, action.id)}

by the way, library preact which is similar to react doesn't implement like this code. It's one of the reason why it's lighter than react
https://preactjs.com/guide/v8/differences-to-react/

Synthetic Events: Preact's browser support target does not require this extra overhead

💎 6. Avoid hard coding

What is hard coding?
it means practice of embedding values directly into the source code of a program instead of using variables or other abstractions

useState('admin_user')

↓

const ADMIN_USER = 'admin_user'
useState(ADMIN_USER)

it is too simple to get for what I defined variable, but if you write code in big project, it would cause bug.

When I see hard code in project, my brain reacts instinctively like "🤨🤨🤨🤨🤨🤨🤨 hmmmmmmmm", even in train, bathroom, toilet, bed. So avoid it please lol

💎 7. UseState() of toggle button

// write in this way, it's simpler than write "true" and "false" each time
useState(prev => !prev)

💎 8. Use object not case in like this condition

I've modified like this way ↓
when conditionally rendering component based on some string enum (like a role), use an object to map enum values to components.

💎 9. Use meaningful Names

// (before)
const m = moment(value, valueFormat[type])

↓

// (after)
const inputDate = moment(value, valueFormat[type])

💎 10. Set default argument value, if it is possible. Specially in utility function

I found like this code about debounce

const DELAY = 200
.
.
.
const debouncedQuery = useDebounce(name, DELAY)

I was like "What is 200? Where is it from??", this related to Magic number which I've already written before.
After searching using places debouncedQuery, I realised the reason why he wrote 200 is that DELAY = 200 is written in 5 other files as well.
So I proposed adding default argument in useDebounce function like this

const useDebounce = (value, delay = 200) => {
....(some codes)
}

💎 11. Don't set JSX in useState value

I found like this code, but JSX shouldn't be managed in useState.
React decides to re-render or not by observing state(=data), but if JSX which is result of rendering sets in state, it would be like destroying react concept itself.
It works without any problem though

const [hogeComponent, setHogeComponent] = React.useState<JSX.Element>(hogeComponentRenderer)

💎 12. Add meaningful name in if condition

Actually it's not only if condition, but people somehow add meaningless name in if condition easily

// 🤔 What's that ...?
if(template.id > 0) {
...
}

↓

const existsTemplate = template.id > 0
if(existsTemplate) {
...
}

💎 13. Don't use negative condition, if you don't have reason

!isAdmin ? first() : second()

↓

isAdmin ? second() : first()

💎 14. Eliminate unnecessary rendering

I've often seen people forgot adding useCallback in proper places.
Or one one big object of useState manages a lot of form.
If I found unnecessary rendering components which are caused by onChange event, I would warn it. It could be heavy action for browser.

How I find it?

I useReact developper tools in chrome.
↓ Check Highlight updates when components render, and you can see which component render

💎 15. use debounce

For example, when you implement input which request to server each onChange event, you have to add debounce. Otherwise, you know server cries.

In my case

In my project, I've found like this input(↑), and debounce time was 200ms. But Even if I wrote so quickly, requests were sent on each onChange event. So I proposed changing this time to 500ms

There are some examples, which you need to add debounce like animation, changing window size ....

💎 16. Use controlled and uncontrolled component depending on situation

When the form appears in code, I start to think about it.
Simply put ↓

- controlled
  you need to watch and render on every onChange event
- uncontrolled
  1. you don't need to watch and render on every onChange event, in case of simple form
  2. If user can add number of form, also you should use uncontrolled

💎 17. Don't manipulate DOM directly without special reason

I found like this code

const currentVal = form.querySelector('input[type="text"]').value

If you need to manipulate DOM, you should use useRef in react.js.
Specially when you need to change/get something that has no related to react life cycle, for example getting dom width, height or scroll height

You shouldn't use useRef only because you want to change some data

💎 (I will keep writing each time when I find interesting code review)

.
.
.
😀

DEV Community: Kaziu

OCRで名刺を一括登録する機能をつくった話 — “1ページ複数名刺”という落とし穴

はじめに

全体の流れ

OCRは“2段構え”

設計で効いたポイント

いちばん悩んだ問題：「1ページに複数名刺」

OCRは“名刺単位”には分けてくれない

つまり「名刺ごとに切り分ける工程」を自前で挟む必要がある

学び：仕様側で“制約”できると一気にラクになる

重複データの扱い（名寄せ）

まとめ

(後日談)

Elastic search

Mysqlとの違い

データの形

検索クエリの書き方

基本形

完全一致で検索したいっす (term)

複数の条件をANDでつなぎたい (= bool + filter)

テキストを部分一致で検索したい（= match）

マッピングって何ですの？

mapping変更したら？

NestJSの基本アーキテクチャと実プロジェクトでの活用事例

目次

1. Module（モジュール）

NestJSの基本

実プロジェクトでの活用

2. Controller / Resolver

NestJSの基本

実プロジェクトでの活用

主なデコレータ

InputType（リクエスト型）

3. Service / UseCase

NestJSの基本

実プロジェクトでの活用

4. DI（依存性注入）

NestJSの基本

実プロジェクトでの活用

5. Guard（認証・認可）

NestJSの基本

実プロジェクトでの活用

6. Entity定義の多層構造

NestJSの基本

実プロジェクトでの活用

GraphQL Entity（API層）

Domain Entity（ドメイン層）

Prisma Model（DB層）

7. Prisma連携（Repository + Mapper）

NestJSの基本

実プロジェクトでの活用

Repository

Mapper

トランザクション

8. 認証コンテキストの流れ

9. まとめ：NestJS標準 vs 実プロジェクト

おわりに

たった1枚の引き伸ばされた画像から、AWS Lambdaのコード移行とCI/CD構築に至った話

始まり

STEP1: Lambdaてそもそもなんですの？

STEP 2: Lambda関数の移行とCI/CDの構築

1. 環境に応じたSecretsの利用

2. 手動トリガーによる安全なデプロイ

🔥 つまずきポイント：GitHub Actionsの「Run workflow」が表示されない！

まとめ

A better way to call functions in a child component from a parent component in React

❓Question

ChatGPT's answer

My answer

Your answer

Things to watch out for when using multiple ag-Grids on the same page

Modal with ReactDOM.createPortal

What is that

When we could use it

Example

define type of 'hoge_hoge_1' in typescript

How to do

1. define hoge_hoge in the string.

2. define number which change as string.

▼ This is final code

1. define `hoge_hoge` in the string.

💎 1. Use `date-fns` instead of `moment`

💎 5. Don't use type `any` in event argument in React