nomadcode/agent-ops/rules/domain/core/persistence/rules.md

persistence

목적 / 책임

PostgreSQL schema, SQL query, sqlc 생성 코드, storage wrapper를 담당한다.

포함 경로

• internal/storage/ — workflow가 사용하는 저장소 wrapper
• internal/db/ — sqlc 생성 코드와 DB pool
• migrations/ — goose migration
• queries/ — sqlc query 정의
• sqlc.yaml — sqlc 설정

제외 경로

• internal/workflow/ — 업무 상태 전이와 유스케이스
• internal/http/ — HTTP handler/router
• internal/scheduler/ — River job 처리

주요 구성 요소

• Store — workflow용 persistence facade
• db.Queries — sqlc query 집합
• tasks.sql — task 관련 query 정의
• 00001_create_tasks.sql — 초기 task schema

유지할 패턴

• schema 변경은 migration, query, generated code 순서로 반영한다.
• 생성 파일은 직접 수정하지 않고 ./bin/sqlc로 갱신한다.

다른 도메인과의 경계

• workflow: 저장소 메서드는 workflow 유스케이스가 필요한 단위로 제공한다.
• scheduler: worker가 상태를 갱신할 때도 Store 경계를 우선 사용한다.

금지 사항

• internal/db/* 생성 파일을 직접 편집하지 않는다.
• workflow 상태 전이 규칙을 SQL query에 숨기지 않는다.