쿠고랑
  • [Flutter/SQLite] 원 단위 정수 분담 계산, revision 낙관적 잠금, 4단계 검증

    2026년 11월 21일 15시 50분 00초에 업로드 된 글입니다.
    작성자: kugorang
    728x90

    TL;DR (세 줄 요약)

    1. CakeTogether는 선물 분담금을 소수(double)가 아니라 원 단위 정수(int)로 다룹니다. 10,000원을 3명이 나눌 때도 합계가 어긋나지 않고, 남는 1원은 먼저 등록한 사람부터 받습니다.
    2. SQLite 저장소는 연결을 열 때마다 PRAGMA foreign_keys = ON이 적용됐는지 확인합니다. gift_groups와 participants 테이블의 CHECK 제약, revision 낙관적 잠금, 트랜잭션으로 수정 충돌과 일부만 저장되는 일을 막습니다.
    3. 호스트 단위 테스트 67개와 iOS 시뮬레이터 재실행 검증(PID 57847을 종료한 뒤 PID 58340에서 비교)을 통과했습니다. 실제 기기의 키보드 입력과 배포 검증은 별도의 단계로 나누어 관리합니다.

    여러 사람이 함께 선물을 살 때, 각자의 분담금과 지금까지 낸 금액을 기기 한 대에 기록한다고 하겠습니다. 이때 자주 생기는 오류는 두 가지입니다. 첫째는 나눗셈에서 생기는 1원 단위의 오차입니다. 둘째는 수정하는 도중에 뒤로 가기나 중복 클릭이 겹쳐서 저장 내용이 일부만 반영되는 현상입니다.

    CakeTogether는 쿠고랑(kugorang)이 Flutter로 만드는, 기기 안에 기록을 저장하는 앱입니다(kugorang/caketogether, Flutter 3.41.7, Dart 3.11.5). 이 앱은 두 문제를 정수 계산 규칙과 SQLite 트랜잭션 설계로 나누어 해결했습니다. SQLite는 파일 하나에 데이터를 저장하는 데이터베이스(DB)입니다.

    1. 왜 소수 대신 원 단위 정수로 계산하나요?

    double은 소수를 다루는 자료형입니다. 컴퓨터는 double 값을 2진수로 저장하기 때문에, 10진수 금액을 계산하면 아주 작은 오차가 쌓일 수 있습니다. 예를 들어 10,000원을 3명이 똑같이 나누면 3,333.3333...원이 나옵니다. 화면마다 반올림하는 방식이 다르면 합계가 9,999원이나 10,001원으로 어긋납니다.

    CakeTogether의 도메인 계층(lib/src/domain/money.dart, 1,792바이트)은 모든 금액을 int, 곧 원 단위 정수로만 받습니다. 도메인 계층은 앱의 규칙과 계산을 담는 코드 부분입니다.

    • 금액의 상한은 999,999,999원으로 고정합니다.
    • 똑같이 나누는 함수 splitEqually는 정수 몫(~/)과 나머지(%)를 구합니다.
    • 남는 금액은 먼저 등록한 참여자부터 순서대로 1원씩 더합니다.
    List<int> splitEqually(int targetAmountWon, int participantCount) {
      validateWon(targetAmountWon, allowZero: false, field: '목표금액');
      if (participantCount < 1) {
        throw const CakeTogetherException(
          CakeTogetherError.validation,
          '참여자는 한 명 이상이어야 합니다.',
        );
      }
      final base = targetAmountWon ~/ participantCount;
      final remainder = targetAmountWon % participantCount;
      return List<int>.unmodifiable(
        List<int>.generate(
          participantCount,
          (index) => base + (index < remainder ? 1 : 0),
          growable: false,
        ),
      );
    }

    이 함수를 실행한 결과는 다음과 같습니다.

    나눌 금액인원결과합계
    10,000원3명3,334원, 3,333원, 3,333원10,000원
    1원3명1원, 0원, 0원1원

    돌려주는 리스트는 List.unmodifiable과 growable: false로 만듭니다. 그래서 나중에 화면 코드에서 실수로 길이를 바꾸거나 값을 덮어쓸 수 없습니다.

    2. DB는 잘못된 값을 어떻게 막나요?

    앱 코드의 검증을 통과했더라도, 데이터베이스가 잘못된 값을 받아 주면 잘못된 데이터가 파일에 저장될 수 있습니다. CakeTogether는 lib/src/data/schema.dart(1,700바이트)에서 gift_groups와 participants 두 테이블을 만들 때 CHECK 제약을 SQL 정의 안에 직접 적었습니다. CHECK 제약은 조건에 맞지 않는 값을 저장하지 못하게 하는 테이블 규칙입니다.

    CREATE TABLE gift_groups (
      id TEXT NOT NULL PRIMARY KEY,
      title TEXT NOT NULL CHECK (length(trim(title)) > 0),
      recipient_name TEXT NOT NULL CHECK (length(trim(recipient_name)) > 0),
      target_amount_won INTEGER NOT NULL CHECK (typeof(target_amount_won) = 'integer' AND target_amount_won BETWEEN 1 AND 999999999),
      list_order INTEGER NOT NULL UNIQUE CHECK (typeof(list_order) = 'integer' AND list_order > 0),
      next_participant_no INTEGER NOT NULL CHECK (typeof(next_participant_no) = 'integer' AND next_participant_no > 0),
      revision INTEGER NOT NULL CHECK (typeof(revision) = 'integer' AND revision > 0),
      created_at_utc_ms INTEGER NOT NULL CHECK (typeof(created_at_utc_ms) = 'integer'),
      updated_at_utc_ms INTEGER NOT NULL CHECK (typeof(updated_at_utc_ms) = 'integer')
    )

    참여자 테이블 participants에는 다음 두 가지 제한을 두었습니다.

    • 분담금 share_amount_won은 0 이상 999,999,999 이하의 정수여야 합니다.
    • 지금까지 낸 금액 paid_total_won은 0 이상이고 share_amount_won 이하여야 합니다.

    그래서 앱의 버그 때문에 분담금보다 많은 납부액이 들어오려고 해도 SQLite가 쓰기를 거부합니다.

    3. 연결을 열 때마다 무엇을 다시 확인하나요?

    SQLite는 예전 버전과의 호환 때문에, 새 연결을 열면 외래키 검사가 기본으로 꺼져 있습니다. 외래키는 한 테이블의 행이 다른 테이블의 행을 가리키게 하는 규칙입니다. lib/src/data/repository.dart(20,770바이트)의 CakeTogetherRepository.open은 데이터베이스를 열 때마다 onConfigure에서 PRAGMA foreign_keys = ON을 실행합니다. 그리고 바로 PRAGMA foreign_keys를 조회해서 값이 1인지 확인합니다. PRAGMA는 SQLite의 동작 방식을 바꾸거나 조회하는 명령입니다.

    그다음 _verifyDatabase()가 실행되어 네 가지를 순서대로 확인합니다.

    1. sqlite_master에 있는 테이블의 개수와 CREATE TABLE SQL 원문이 cakeTogetherTableSql과 정확히 같은지 비교합니다. 버전이 다른, 알 수 없는 DB 파일을 만나면 파일을 지우거나 덮어쓰지 않습니다. CakeTogetherError.unsupportedSchema 예외를 던지고 기존 파일을 그대로 둡니다.
    2. PRAGMA quick_check를 실행해서 결과가 'ok' 한 줄인지 확인합니다.
    3. PRAGMA foreign_key_check의 결과가 비어 있는지 확인합니다.
    4. 저장된 모든 gift_groups 행을 _readSnapshot으로 실제로 읽어서 도메인 검증까지 통과하는지 확인합니다.

    4. 수정이 겹치는 것은 어떻게 막나요?

    모임을 만들거나 참여자를 고칠 때, 참여자 목록의 일부만 저장되고 모임 정보의 저장은 실패하면 기록이 서로 맞지 않게 됩니다. CakeTogether는 모든 쓰기 동작을 _database.transaction으로 감쌌습니다. 트랜잭션은 여러 변경을 하나로 묶어 전부 반영하거나 전부 취소하는 단위입니다.

    여기에 revision 번호를 쓰는 낙관적 잠금(Optimistic Concurrency Control)을 더했습니다. 낙관적 잠금은 데이터를 미리 잠그지 않고, 저장하는 순간에 "내가 읽은 뒤로 바뀌지 않았는지"를 확인하는 방법입니다.

    원 단위 정수 입력이 도메인 검증과 SQLite 트랜잭션을 거친 뒤, revision 조건에 맞으면 커밋하고 맞지 않으면 롤백하는 순서도

    수정은 세 단계로 진행됩니다.

    1. 화면이 모임을 읽을 때 현재의 revision 값(예: 1)을 함께 받아 둡니다.
    2. 저장을 누르면 트랜잭션 안에서 _checkRevision(current, expectedRevision)으로 DB의 revision이 여전히 1인지 먼저 확인합니다. 이어서 참여자의 변경과 삭제를 처리합니다.
    3. 마지막으로 _saveChangedGroup이 WHERE id = ? AND revision = ? 조건으로 모임 행의 revision을 expectedRevision + 1로 올립니다.
    Future<void> _saveChangedGroup(
      DatabaseExecutor transaction,
      GiftGroup group,
      int expectedRevision,
    ) async {
      final updated = group.copyWith(
        revision: expectedRevision + 1,
        updatedAtUtcMs: _clock(),
      );
      final count = await transaction.update(
        'gift_groups',
        {
          'title': updated.title,
          'recipient_name': updated.recipientName,
          'target_amount_won': updated.targetAmountWon,
          'next_participant_no': updated.nextParticipantNo,
          'revision': updated.revision,
          'updated_at_utc_ms': updated.updatedAtUtcMs,
        },
        where: 'id = ? AND revision = ?',
        whereArgs: [group.id, expectedRevision],
      );
      if (count != 1) {
        throw const CakeTogetherException(
          CakeTogetherError.conflict,
          'The group changed before this edit could be saved.',
        );
      }
    }

    그 사이에 다른 경로에서 저장이 먼저 끝나서 revision이 2로 바뀌었다면, update가 돌려주는 행 수 count가 0이 됩니다. 이때 예외가 발생합니다. 같은 트랜잭션 안에서 먼저 고친 participants의 변경까지 모두 롤백됩니다. 롤백은 트랜잭션의 변경을 전부 취소하는 것입니다.

    두 가지 규칙이 더 있습니다.

    • 이미 낸 금액이 0보다 큰 참여자를 삭제하려고 하면 CakeTogetherError.paidParticipantRemoval 오류로 막습니다.
    • 같은 납부액을 다시 저장할 때는 revision과 수정 시각을 올리지 않습니다.

    5. 파일마다 어떤 역할을 하나요?

    파일 경로파일 크기역할
    lib/src/domain/errors.dart446바이트검증, 소속, 충돌, 저장, 손상, 지원하지 않는 스키마 오류를 구분합니다.
    lib/src/domain/money.dart1,792바이트원 단위 정수의 상한을 검증하고, 남는 금액을 나누고, UUID v4를 검사합니다.
    lib/src/domain/models.dart10,911바이트바꿀 수 없는 스냅샷 모델을 정의하고, 등록 번호를 보존하고, 합계가 맞는지 검증합니다.
    lib/src/data/schema.dart1,700바이트SQLite 테이블 2개, 정수 범위 CHECK, 외래키 제약을 정의합니다.
    lib/src/data/repository.dart20,770바이트트랜잭션으로 한꺼번에 저장하고, revision으로 충돌을 막고, DB가 올바른 상태인지 확인합니다.
    test/repository_test.dart24,109바이트실제 파일 SQLite로 롤백, 충돌, 다시 열기를 검증하는 테스트 24건이 들어 있습니다.

    스키마는 테이블의 구조를 정한 것입니다. 스냅샷은 어느 한 시점의 데이터를 그대로 담은 값입니다.

    6. 검증은 왜 4단계로 나누나요?

    개발할 때 조심해야 하는 것은 "코드 수정 ≠ 모의 시험 ≠ 실기기 검증 ≠ 운영 반영"을 혼동하는 일입니다. 호스트 컴퓨터(개발에 쓰는 컴퓨터)에서 도메인 함수나 위젯 테스트가 통과했다고 해서, 실제 모바일 OS의 네이티브 SQLite 플러그인(sqflite 2.4.2+1)이 잘 동작하는지, 앱을 다시 실행해도 데이터가 남아 있는지까지 보장되지는 않습니다.

    호스트 단위·위젯 테스트 43개, 파일 SQLite 테스트 24개, iOS 시뮬레이터 재실행, 아직 하지 않은 실기기·배포 검증을 네 계단으로 나타낸 그림

    CakeTogether는 검증을 네 단계로 나누어 기록했습니다. 단계별 결과는 다음과 같습니다.

    검증 단계실행 환경과 도구건수와 상태확인한 범위
    1단계: 도메인과 화면 단위 테스트호스트의 flutter test(domain_test.dart, wizard_widget_test.dart, record_widget_test.dart)24 + 6 + 13 = 43개 통과원 단위 계산, 입력 검증, 취소 경로 4가지, 중복 저장 방지
    2단계: 파일 SQLite 저장소 테스트호스트의 sqflite_common_ffi 2.3.6 + sqlite3 2.9.4(repository_test.dart)24개 통과임시 파일 생성, 트리거로 일으킨 강제 롤백, 연결을 닫은 뒤 다시 조회, 지원하지 않는 DB 파일의 바이트 보존
    3단계: iOS 시뮬레이터 통합 검증iPhone 16 / iOS 18.4(integration_test/ios_flow_test.dart, flutter drive)7단계 흐름 통과네이티브 sqflite 저장. PID 57847을 종료한 뒤 PID 58340으로 다시 실행했을 때 DB와 화면의 합계(목표 30,000원, 납부 25,000원, 잔액 5,000원)가 일치
    4단계: 실기기와 배포 검증실제 iPhone, iPad, Android 기기와 스토어실행하지 않음(NOT_RUN)숫자 키보드가 화면을 가리는 문제, 한글 자모 조합, VoiceOver, 배포 서명은 따로 검증해야 함

    시뮬레이터는 컴퓨터 안에서 휴대폰을 흉내 내어 앱을 실행하는 프로그램입니다. PID는 실행 중인 프로세스에 운영체제가 붙이는 번호입니다.

    • 2단계의 호스트 테스트에서는 실제 SQLite 파일에 오류를 일으키는 트리거를 넣었습니다. 트리거는 특정 변경이 일어날 때 DB가 자동으로 실행하는 동작입니다. 이것으로 트랜잭션이 중간에 실패하면 앞선 변경이 모두 취소되는지 검증했습니다.
    • 3단계에서는 flutter drive --keep-app-running으로 데이터를 유지한 채, 앱 프로세스(PID 57847)를 완전히 종료하고 새 프로세스(PID 58340)로 다시 실행했습니다. 화면에 보이는 금액과 별도의 DB 연결에서 읽은 값이 모두 일치하는지 비교했습니다.

    자주 묻는 질문 (FAQ)

    Q1. 왜 참여자별 납부 내역 테이블을 따로 두지 않고 누적 납부액(paid_total_won)만 저장하나요?

    첫 버전(v1)은 대표자 한 명이 자기 기기에서 전체 납부 진행 상황을 빠르게 고치는 데 초점을 맞췄기 때문입니다. 입금 이력을 여러 행으로 쌓으면, 금액을 낮추거나 0원으로 고칠 때 먼저 넣은 기록을 취소하는 행(역분개 행)이 늘어납니다. 누적 금액만 저장하면 같은 값을 다시 입력해도 revision이 오르지 않습니다. 그리고 paid_total_won BETWEEN 0 AND share_amount_won 제약 하나로 초과 납부를 막을 수 있습니다.

    Q2. 호스트의 flutter test에서 sqflite가 바로 실행되나요?

    실행되지 않습니다. 기본 sqflite 플러그인은 iOS와 Android의 네이티브 채널을 통해 동작하므로, 데스크톱 호스트 테스트에서는 실행되지 않습니다. CakeTogetherRepository.open()이 databaseFactory를 밖에서 넘겨받도록 나누어 두었습니다. 호스트 테스트에서는 sqflite_common_ffi를 넘겨서 실제 파일 SQLite로 테스트합니다. iOS 시뮬레이터 통합 테스트에서는 기본 네이티브 sqflite 팩토리로 따로 검증했습니다.

    Q3. 앱을 업데이트하다가 지원하지 않는 이전 버전이나 손상된 DB 파일을 만나면 어떻게 되나요?

    CakeTogetherRepository.open은 onUpgrade와 onDowngrade를 모두 _unsupportedSchema 예외로 막습니다. _verifyDatabase()에서는 테이블 SQL 원문과 PRAGMA quick_check를 검사합니다. 오류가 나면 연결을 닫고 CakeTogetherError.unsupportedSchema 또는 corruptData를 돌려줍니다. 복구한다는 이유로 기존 SQLite 파일을 지우거나 빈 DB로 덮어쓰지 않습니다.

    수정 안내

    이 글은 2026년 11월 22일에 다시 썼습니다. 코드와 숫자는 그대로 두었습니다. 제목을 줄였고, 그림 설명(alt)을 그림 내용에 맞게 고쳤습니다. 참고 자료와 함께 읽으면 좋은 글을 새로 넣었습니다.

    출처: kugorang/caketogether 저장소(lib/src/domain/money.dart, lib/src/data/schema.dart, lib/src/data/repository.dart, test/repository_test.dart, docs/implementation-report-v0.1.md, docs/ui-implementation-qa-v0.1.md)

    참고 자료

    함께 읽으면 좋은 글: 삭제한 글이 SQLite 파일에 남는 이유와 secure_delete, Flutter 달력에서 날짜 하나만 다시 그리기

    728x90
    728x90
    댓글