성당 앱 v2 업그레이드 프로젝트

상3동성당 주보앱을 성당 생활 허브로 확장하기 위한 v2 업그레이드 프로젝트 기록입니다.

프로젝트 개요

이 프로젝트는 기존 상3동성당 주보앱을 v2로 업그레이드하는 작업입니다. v1이 종이 주보를 모바일에서 확인하는 데 집중했다면, v2는 주보, 전례력, 미사 정보, 본당 소식을 한곳에서 확인할 수 있는 성당 생활 허브를 목표로 합니다.

기간: YYYY-MM ~ YYYY-MM
구분: 개인 프로젝트
역할: 기획, 모바일 앱 개발, 백엔드 개발, 배포, 운영
주요 기술: React Native, Spring Boot, PostgreSQL, Docker
링크: 확인 필요

v1에서 확인한 문제

v1은 최신 주보를 빠르게 확인할 수 있다는 점에서 의미가 있었지만, 기능 범위가 주보 중심으로 제한되어 있었습니다. 사용자가 앱을 반복해서 열 이유를 만들려면 주보 외에도 미사 시간, 전례력, 본당 일정처럼 성당 생활과 직접 연결되는 정보를 안정적으로 제공해야 했습니다.

주보 외 핵심 정보 접근성이 낮음
콘텐츠 업데이트 흐름이 운영자 친화적이지 않음
모바일 화면 구조가 장기 확장에 적합하지 않음
공지, 일정, 전례 데이터의 출처와 갱신 정책이 명확하지 않음

v2 목표

v2의 목표는 단순한 PDF 뷰어가 아니라 성당 생활에 필요한 정보를 쉽게 확인하는 앱으로 확장하는 것입니다. 특히 연령대가 높은 사용자도 헤매지 않도록 홈 화면에서 핵심 정보를 바로 확인하고, 각 기능은 짧은 이동 경로로 접근할 수 있게 설계합니다.

홈에서 오늘 필요한 정보를 먼저 보여주기
주보, 전례력, 미사, 더보기 중심의 단순한 정보 구조 유지
콘텐츠 관리와 앱 표시 로직 분리
서버 API 기반으로 데이터 갱신 흐름 안정화
v1 사용 경험을 해치지 않는 단계적 마이그레이션

핵심 사용자 흐름

홈

앱을 열었을 때 사용자가 가장 먼저 확인해야 하는 정보를 모읍니다.

최신 주보 바로가기
오늘의 전례 정보
다음 미사 시간
중요 공지

주보

주보는 v1의 핵심 기능이므로 접근성을 유지하면서 탐색과 보관 기능을 개선합니다.

최신 주보 보기
지난 주보 목록
PDF 또는 이미지 기반 열람
다운로드 실패, 로딩 실패 상태 처리

전례력

전례력은 날짜 기반 정보이므로 오늘 화면과 목록 화면을 분리합니다.

오늘의 전례
월별 전례 목록
축일, 기념일, 전례 색상
데이터 출처와 갱신 주기

미사

미사 정보는 사용자가 반복적으로 확인하는 영역이므로 고정 정보와 예외 일정을 분리합니다.

평일 미사 시간
주일 미사 시간
특별 미사와 변경 공지
본당 사정에 따른 임시 변경 안내

기능 범위

이번 버전에 포함할 것

홈 화면 개편
주보 목록과 상세 보기 정리
전례력 화면 추가
미사 정보 화면 추가
서버 API 기반 콘텐츠 조회
운영자가 관리하기 쉬운 데이터 구조 설계

이번 버전에서 제외할 것

사용자 계정
게시판
채팅
헌금, 결제, 개인정보가 필요한 기능
관리자 페이지의 과도한 기능 확장

데이터 설계 메모

v2에서는 앱이 외부 페이지를 직접 긁어서 화면을 구성하기보다, 백엔드가 콘텐츠를 소유하거나 안정적으로 캐싱한 뒤 모바일 앱에 제공합니다.

bulletins: 주보 제목, 발행일, 파일 경로, 공개 여부
announcements: 공지 제목, 본문, 중요도, 게시 기간
mass_schedules: 미사 유형, 요일, 시간, 예외 일정
liturgical_days: 날짜, 전례명, 등급, 전례 색상
app_versions: 최소 지원 버전, 업데이트 안내

Spring 백엔드 보강 설계

v1에서는 모바일 앱이 최신 주보를 보여주는 데 집중했기 때문에 백엔드의 역할이 비교적 단순했습니다. 하지만 v2에서는 주보, 공지, 전례력, 미사 시간, 앱 버전 정책이 함께 움직입니다. 이 데이터를 모바일 앱 안에 직접 넣으면 정보가 바뀔 때마다 앱 업데이트가 필요하고, 외부 페이지 구조가 바뀌었을 때 앱이 바로 영향을 받습니다.

그래서 v2에서는 Spring Boot 백엔드를 성당 콘텐츠의 기준 저장소로 두는 방향을 잡았습니다. 모바일 앱은 화면과 사용자 경험에 집중하고, Spring 서버는 콘텐츠 정규화, 공개 상태, 파일 메타데이터, 조회 API를 담당합니다.

React Native App
  -> Spring Boot API
  -> PostgreSQL
  -> File Storage

Spring 백엔드가 맡을 책임은 다음과 같습니다.

책임	내용
콘텐츠 소유	주보, 공지, 미사 시간, 전례력 데이터를 앱과 분리해 관리
공개 상태 관리	`draft`, `published`, `archived` 상태와 게시 기간 관리
파일 메타데이터 관리	PDF나 이미지 파일 자체는 저장소에 두고, DB에는 경로와 크기, 타입, 공개 여부 저장
모바일 API 제공	홈, 주보, 전례력, 미사, 더보기 화면에 맞춘 읽기 전용 API 제공
운영 안정성	외부 데이터 수집 실패나 파일 누락을 앱 오류가 아니라 서버 상태로 다룸

API 초안

모바일 앱은 많은 데이터를 한 번에 받기보다 화면 단위로 필요한 정보만 조회하는 구조가 적합합니다. 특히 연령대가 높은 사용자가 많을 수 있으므로, 앱 첫 화면은 빠르게 뜨고 실패 상태가 명확해야 합니다.

화면	API	응답 목적
홈	`GET /api/v1/home`	최신 주보, 오늘 전례, 다음 미사, 중요 공지 요약
주보	`GET /api/v1/bulletins/current`	현재 주보 상세와 파일 정보
주보 목록	`GET /api/v1/bulletins?cursor=&limit=`	지난 주보 목록 페이지네이션
공지	`GET /api/v1/announcements?cursor=&limit=`	공개 중인 공지 목록
전례력	`GET /api/v1/liturgical-days?from=&to=`	월별 전례 정보
미사	`GET /api/v1/schedules`	평일, 주일, 특별 미사 시간
본당 정보	`GET /api/v1/church-info`	본당 소개, 위치, 문의 정보
앱 버전	`GET /api/v1/app-version`	최소 지원 버전과 업데이트 안내

PostgreSQL 테이블 방향

PostgreSQL은 구조가 안정적인 성당 콘텐츠를 다루기에 적합합니다. 주보, 공지, 미사 일정처럼 조회 조건이 명확한 데이터는 정규화된 테이블로 관리하고, 외부 출처에서 가져온 원문이나 확장 가능한 메타데이터만 jsonb로 제한적으로 둡니다.

테이블	주요 필드	설계 포인트
`bulletins`	`id`, `title`, `published_date`, `file_id`, `status`, `visible_from`, `visible_until`	최신 주보와 아카이브 조회 기준
`files`	`id`, `storage_key`, `content_type`, `size_bytes`, `checksum`, `public_url`	PDF/이미지 파일 메타데이터만 저장
`announcements`	`id`, `title`, `body`, `priority`, `status`, `visible_from`, `visible_until`	중요 공지와 게시 기간 관리
`mass_schedules`	`id`, `mass_type`, `day_of_week`, `time`, `note`, `status`	반복 미사 시간 관리
`mass_exceptions`	`id`, `date`, `title`, `time`, `reason`, `status`	성탄, 부활, 행사 등 예외 일정 관리
`liturgical_days`	`id`, `date`, `name`, `rank`, `color`, `metadata`	날짜 기반 전례 정보 조회
`church_info`	`id`, `name`, `address`, `phone`, `links`, `updated_at`	더보기 화면의 본당 정보
`app_versions`	`id`, `platform`, `minimum_version`, `latest_version`, `message`	강제/권장 업데이트 판단

파일은 PostgreSQL에 직접 저장하지 않습니다. DB에는 파일을 찾기 위한 storage_key, content_type, size_bytes, checksum만 저장하고, 실제 PDF나 이미지는 NAS 볼륨이나 객체 저장소에 둡니다. 이렇게 해야 DB 백업 크기를 줄이고, 나중에 파일 저장소를 바꾸더라도 API 계약을 유지할 수 있습니다.

Spring 패키지 구조 초안

Spring 서버는 기능별로 controller, service, repository, entity, dto를 섞어두기보다 도메인 단위로 나누는 편이 유지보수에 유리합니다.

src/main/java/.../church/
  bulletin/
    api/
    application/
    domain/
    infrastructure/
  announcement/
  liturgy/
  mass/
  file/
  appversion/

api: Controller와 request/response DTO
application: 화면 단위 use case와 transaction 처리
domain: Entity, enum, 도메인 규칙
infrastructure: Repository, 파일 저장소 adapter, 외부 데이터 수집 adapter

모바일 앱에는 JPA Entity를 그대로 반환하지 않고 화면에 맞춘 DTO를 반환합니다. 예를 들어 홈 화면은 Bulletin, Announcement, MassSchedule 전체를 그대로 받는 것이 아니라, 오늘 필요한 정보만 모은 HomeResponse를 받는 구조가 더 안정적입니다.

HomeResponse
  latestBulletin
  todayLiturgy
  nextMass
  importantNotices[]

기술 선택

기존 모바일 경험은 React Native 기반으로 이어가되, 서버는 장기 운영과 데이터 관리 편의성을 고려해 Spring Boot와 PostgreSQL 조합을 검토합니다.

모바일: React Native
백엔드: Spring Boot
데이터베이스: PostgreSQL
배포: Docker, NAS reverse proxy
운영: Cloudflare, NAS reverse proxy

Spring Boot를 선택하는 이유는 기능 수보다 데이터의 성격 때문입니다. v2의 핵심 데이터는 사용자가 직접 쓰는 게시판보다 운영자가 관리하는 읽기 중심 콘텐츠입니다. 이 경우 명확한 테이블 구조, 공개 상태, 게시 기간, 파일 메타데이터, 마이그레이션 이력이 중요합니다. Spring Boot와 PostgreSQL 조합은 이런 콘텐츠 관리형 백엔드에 적합하다고 판단했습니다.

또한 이후 관리자 기능을 추가하더라도 같은 도메인 모델을 확장할 수 있습니다. 초기에는 모바일 조회 API만 만들고, 운영이 필요해지는 시점에 관리자 입력 API나 간단한 관리자 화면을 붙이는 단계적 확장이 가능합니다.

구현 계획

1단계: v2 정보 구조 확정

홈 / 주보 / 전례력 / 미사 / 더보기 탭 구조 확정
v1 기능 중 유지할 화면과 제거할 화면 정리
콘텐츠별 원본 데이터와 갱신 주기 정의

2단계: 백엔드 기반 데이터 조회

주보, 공지, 미사, 전례력 API 설계
PostgreSQL 스키마 설계
파일 저장 정책 정리
관리자 입력 또는 데이터 수집 방식 결정
Flyway 기반 DB migration 도입
공개 상태, 게시 기간, 최신 주보 조회 기준 구현
모바일 홈 화면용 GET /api/v1/home 응답 DTO 설계

3단계: 모바일 화면 개편

홈 화면 우선 구현
주보 화면 마이그레이션
전례력과 미사 화면 추가
로딩, 빈 상태, 오류 상태 정리

4단계: 배포와 운영

Docker 기반 서버 배포
NAS reverse proxy 연결
모바일 앱 테스트 배포
사용자 피드백 반영

검증 체크리스트

앱 첫 화면에서 최신 주보와 오늘 정보가 바로 보이는가
연령대가 높은 사용자도 주요 기능을 1~2번 탭 안에 찾을 수 있는가
네트워크 실패 시 빈 화면이 아니라 이해 가능한 상태가 보이는가
주보 파일이 느리게 열리거나 실패할 때 복구 흐름이 있는가
본당 일정 변경을 앱 업데이트 없이 반영할 수 있는가
개인정보나 관리자 기능이 불필요하게 노출되지 않는가
Spring API 응답이 화면 단위로 충분히 작고 안정적인가
게시 기간이 지난 공지나 비공개 주보가 모바일에 노출되지 않는가
파일이 누락되었을 때 앱이 깨지는 대신 대체 상태를 보여주는가

구현 중 고민한 점

작성 예정입니다.

v1을 유지하면서 v2로 전환하는 방법
주보 PDF를 계속 사용할지, 구조화된 콘텐츠로 전환할지
관리자 기능을 어디까지 만들지
전례력 데이터를 어떤 방식으로 검증하고 갱신할지
Spring 백엔드를 어디까지 먼저 만들고, 어떤 기능은 정적 데이터나 수동 입력으로 시작할지
파일 저장소를 NAS 볼륨으로 시작할지, 객체 저장소로 바로 분리할지

결과

작성 예정입니다.

출시 버전:
배포 방식:
사용자 수:
주요 피드백:

배운 점

작성 예정입니다.

기술적으로 배운 점
제품 설계에서 배운 점
운영 과정에서 배운 점
다음 버전에서 개선할 점

성당 앱 v2 업그레이드 프로젝트

프로젝트 개요

v1에서 확인한 문제

v2 목표

핵심 사용자 흐름

홈

주보

전례력

미사

더보기

기능 범위

이번 버전에 포함할 것

이번 버전에서 제외할 것

데이터 설계 메모

Spring 백엔드 보강 설계

API 초안

PostgreSQL 테이블 방향

Spring 패키지 구조 초안

기술 선택

구현 계획

1단계: v2 정보 구조 확정

2단계: 백엔드 기반 데이터 조회

3단계: 모바일 화면 개편

4단계: 배포와 운영

검증 체크리스트

구현 중 고민한 점

결과

배운 점