React Native background 작업: 화면이 없어도 일을 어떻게 이어 가는가

사용자 행동       최소 작업 입력과 고정 작업 ID를 영속 저장
scheduler 등록    network·전원 같은 실행 조건과 함께 운영체제에 요청
worker 시작       새 프로세스여도 영속 대기열에서 입력을 다시 읽음
중단·재실행       같은 작업 ID로 다시 실행해도 서버 효과는 한 번
완료              서버 확인 뒤에만 로컬 대기 항목 제거

AppState change          상태 전환을 관찰
Promise·setTimeout       현재 JavaScript 실행 안에서 나중 작업을 예약
운영체제 예약 장치         조건이 맞을 때 앱·worker에 실행 기회를 제공
영속 작업 대기열          새 프로세스가 읽을 작업 입력을 보관

import React, { useState } from 'react'
import { Button, SafeAreaView, StyleSheet, Text, View } from 'react-native'
import AsyncStorage from '@react-native-async-storage/async-storage'
 
const PERSIST_BEFORE_SCHEDULE = false
const SIMULATE_STOP_AFTER_SERVER_APPLY = false
const OUTBOX_KEY = '@background/receipt-upload'
const SERVER_KEY = '@fixture/applied-receipt-uploads'
 
type UploadJob = {
  id: string
  receiptId: string
}
 
type ServerFixture = {
  appliedJobIds: string[]
  applyCount: number
}
 
const FIXED_JOB: UploadJob = {
  id: 'receipt-42-upload-v1',
  receiptId: 'receipt-42',
}
 
function parseUploadJob(raw: string | null): UploadJob | null {
  if (raw === null) {
    return null
  }
 
  try {
    const input: unknown = JSON.parse(raw)
 
    if (
      typeof input === 'object' &&
      input !== null &&
      'id' in input &&
      typeof input.id === 'string' &&
      'receiptId' in input &&
      typeof input.receiptId === 'string'
    ) {
      return { id: input.id, receiptId: input.receiptId }
    }
  } catch {
    return null
  }
 
  return null
}
 
function parseServerFixture(raw: string | null): ServerFixture {
  if (raw === null) {
    return { appliedJobIds: [], applyCount: 0 }
  }
 
  try {
    const input: unknown = JSON.parse(raw)
 
    if (
      typeof input === 'object' &&
      input !== null &&
      'appliedJobIds' in input &&
      Array.isArray(input.appliedJobIds) &&
      input.appliedJobIds.every((id) => typeof id === 'string') &&
      'applyCount' in input &&
      typeof input.applyCount === 'number'
    ) {
      return {
        appliedJobIds: input.appliedJobIds,
        applyCount: input.applyCount,
      }
    }
  } catch {
    return { appliedJobIds: [], applyCount: 0 }
  }
 
  return { appliedJobIds: [], applyCount: 0 }
}
 
async function applyOnFixtureServer(job: UploadJob): Promise<ServerFixture> {
  const current = parseServerFixture(await AsyncStorage.getItem(SERVER_KEY))
 
  if (current.appliedJobIds.includes(job.id)) {
    return current
  }
 
  const next = {
    appliedJobIds: [...current.appliedJobIds, job.id],
    applyCount: current.applyCount + 1,
  }
 
  await AsyncStorage.setItem(SERVER_KEY, JSON.stringify(next))
  return next
}
 
export default function App() {
  const [status, setStatus] = useState('아직 실행하지 않음')
  const [memoryJob, setMemoryJob] = useState<UploadJob | null>(null)
  const [persistedJob, setPersistedJob] = useState(false)
  const [serverApplyCount, setServerApplyCount] = useState(0)
  const [busy, setBusy] = useState(false)
 
  async function inspectFixture() {
    const [jobRaw, serverRaw] = await Promise.all([
      AsyncStorage.getItem(OUTBOX_KEY),
      AsyncStorage.getItem(SERVER_KEY),
    ])
 
    setPersistedJob(parseUploadJob(jobRaw) !== null)
    setServerApplyCount(parseServerFixture(serverRaw).applyCount)
  }
 
  async function run(action: () => Promise<void>) {
    setBusy(true)
 
    try {
      await action()
    } catch {
      setStatus('fixture 작업 오류')
    } finally {
      setBusy(false)
    }
  }
 
  async function resetFixture() {
    await run(async () => {
      await Promise.all([
        AsyncStorage.removeItem(OUTBOX_KEY),
        AsyncStorage.removeItem(SERVER_KEY),
      ])
      setMemoryJob(null)
      await inspectFixture()
      setStatus('fixture 초기화 완료')
    })
  }
 
  async function enqueueUpload() {
    await run(async () => {
      if (PERSIST_BEFORE_SCHEDULE) {
        await AsyncStorage.setItem(OUTBOX_KEY, JSON.stringify(FIXED_JOB))
      }
 
      setMemoryJob(FIXED_JOB)
      await inspectFixture()
      setStatus('scheduler 요청 완료')
    })
  }
 
  async function runWorkerFixture() {
    await run(async () => {
      const job = parseUploadJob(await AsyncStorage.getItem(OUTBOX_KEY))
 
      if (job === null) {
        await inspectFixture()
        setStatus('worker: 영속 대기 작업 없음')
        return
      }
 
      await applyOnFixtureServer(job)
 
      if (SIMULATE_STOP_AFTER_SERVER_APPLY) {
        await inspectFixture()
        setStatus('worker: 서버 적용 뒤 중단 대역')
        return
      }
 
      await AsyncStorage.removeItem(OUTBOX_KEY)
      await inspectFixture()
      setStatus('worker: 업로드 확인 뒤 대기 작업 제거')
    })
  }
 
  return (
    <SafeAreaView style={styles.screen}>
      <Text style={styles.title}>background 업로드 대기열</Text>
      <Text>
        mode: {PERSIST_BEFORE_SCHEDULE ? 'durable' : 'memory-only'}
      </Text>
      <Text>상태: {status}</Text>
      <Text>메모리 작업: {memoryJob === null ? '없음' : memoryJob.id}</Text>
      <Text>영속 대기 작업: {persistedJob ? '있음' : '없음'}</Text>
      <Text>서버 적용 횟수: {serverApplyCount}</Text>
      <View style={styles.actions}>
        <Button
          title="fixture 초기화"
          disabled={busy}
          onPress={() => void resetFixture()}
        />
        <Button
          title="영수증 업로드 등록"
          disabled={busy}
          onPress={() => void enqueueUpload()}
        />
        <Button
          title="영속 상태 확인"
          disabled={busy}
          onPress={() => void run(inspectFixture)}
        />
        <Button
          title="worker 실행 대역"
          disabled={busy}
          onPress={() => void runWorkerFixture()}
        />
      </View>
    </SafeAreaView>
  )
}
 
const styles = StyleSheet.create({
  screen: { flex: 1, padding: 16, gap: 12 },
  title: { fontSize: 22, fontWeight: '700' },
  actions: { gap: 8 },
})

mode: memory-only
상태: scheduler 요청 완료
메모리 작업: receipt-42-upload-v1
영속 대기 작업: 없음
서버 적용 횟수: 0

mode: memory-only
상태: worker: 영속 대기 작업 없음
메모리 작업: 없음
영속 대기 작업: 없음
서버 적용 횟수: 0

const PERSIST_BEFORE_SCHEDULE = true

mode: durable
상태: scheduler 요청 완료
메모리 작업: receipt-42-upload-v1
영속 대기 작업: 있음
서버 적용 횟수: 0

mode: durable
상태: 아직 실행하지 않음
메모리 작업: 없음
영속 대기 작업: 있음
서버 적용 횟수: 0

mode: durable
상태: worker: 업로드 확인 뒤 대기 작업 제거
메모리 작업: 없음
영속 대기 작업: 없음
서버 적용 횟수: 1

잘못된 순서  scheduler 요청 → 메모리에만 작업 생성
교정 순서    영속 대기열 쓰기 성공 → scheduler 요청
worker 순서  영속 입력 읽기 → 서버 적용 확인 → 로컬 완료 기록·대기 항목 삭제

const SIMULATE_STOP_AFTER_SERVER_APPLY = true

상태: worker: 서버 적용 뒤 중단 대역
영속 대기 작업: 있음
서버 적용 횟수: 1

상태: worker: 업로드 확인 뒤 대기 작업 제거
영속 대기 작업: 없음
서버 적용 횟수: 1

작업 의도       어떤 사용자·서버 사건이 작업을 만들었는가
영속 입력       새 프로세스에 필요한 최소 ID와 상태는 어디에 기록하는가
저장 순서       대기열 쓰기 성공 뒤 scheduler를 요청하는가
플랫폼 선택     Android WorkManager / iOS의 작업 성격별 API
실행 조건       네트워크, 전원, 배터리, 사용자 가시성, 지연 허용 범위
중복 계약       작업 ID, 서버 중복 키, 고유 작업 이름, 동시 worker
중단·재시도     제한 시간, 만료, 재시도 간격을 점차 늘리는 규칙, 취소, 다음 실행
완료 조건       서버 확인 뒤 로컬 대기 항목을 언제 지우는가
관찰            대기·시작·성공·재시도·만료 기록과 민감 정보 가림
검증 환경       fixture, emulator·Simulator, 지원 실기기, 운영 지연

문제       영수증 업로드 입력이 React state에만 있어 새 실행에서 사라짐
오판       background callback·Promise·타이머가 끝날 때까지 앱을 살려 둠
관찰       Reload 뒤 영속 대기 작업 없음, worker 적용 0회
원인       실행 요청과 복원 가능한 작업 입력을 분리하지 않음
행동       영속 대기열 쓰기 → 플랫폼 예약 API 선택·등록 → worker가 대기열 읽기
재실행     고정 작업 ID와 서버 중복 제거로 적용 효과 1회 유지
플랫폼     Android WorkManager, iOS 작업 성격별 API의 다른 시작·중단 계약
경계       fixture는 작업 함수만 증명하고 실제 scheduler·기기 정책은 별도 검증