# 당직근무 제작 매뉴얼 3 · 구조와 저장 및 동기화

**URL:** <https://forum.itosm.co.kr/t/topic/239>\
**Category:** 당직근무\
**Created:** [11월 20, 2026, 9:59오전 UTC](https://forum.itosm.co.kr/t/topic/239 "2026-11-20T09:59:33Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![syskiller](https://forum.itosm.co.kr/user_avatar/forum.itosm.co.kr/syskiller/32/33_2.png) [@syskiller](https://forum.itosm.co.kr/u/syskiller)\
**Post date:** [11월 20, 2026, 9:59오전 UTC](https://forum.itosm.co.kr/t/topic/239/1 "2026-11-20T09:59:33Z")

</div>

# 소스 구조와 자료 흐름

제작자 블리어 (이창현) · 0.13.0

## 폴더별 역할

| 위치 | 역할 |
| --- | --- |
| `app/src/main/java/kr/co/itosm/dutycalendar` | 앱 화면과 계산 및 저장과 연동 |
| `app/src/main/res` | 위젯 레이아웃과 아이콘 및 한국어 문구 |
| `app/src/main/assets` | 기본 공휴일과 음력 변환표 및 근무 예시 |
| `app/src/test` | 근무와 날짜 계산 단위 검사 |
| `app/src/androidTest` | 실제 Android 저장소와 위젯 및 설치 검사 |
| `server/app.py` | 회원과 인증 및 일정 API와 웹 배포 |
| `server/company.py` | 소속과 초대 및 근무표 공유 |
| `server/personal.py` | 기념일과 개인 표시 설정 검증 |
| `server/holiday_store.py` | 공휴일 수신 검증과 마지막 정상 자료 보관 |
| `server/web` | 브라우저 화면과 날짜 계산 및 버전 안내 |
| `tools/build_lunar.py` | 한국 음력 월 시작일 자료 만들기 |

## 근무 계산

기준일을 배열 첫째 날로 두고 날짜 차이를 반복 배열 길이로 나눈 나머지를 사용합니다. 기준일보다 이전 날짜도 같은 규칙으로 계산합니다. 앱 화면과 위젯은 `Schedule` 계산을 공유합니다. 웹의 대응 계산과 공통 예시 자료도 함께 관리합니다. 공휴일 색상과 당직일 평일색 및 비번 빨간색은 실제 근무 순서와 구분합니다.

새 근무 유형을 추가하면 앱과 웹의 계산 및 선택 화면과 `work-patterns.json`을 함께 확인합니다. 파일 이름만 바꾸거나 한쪽에만 유형을 추가하면 다른 기기에서 저장한 값을 읽지 못할 수 있습니다.

## 개인 자료와 서버

앱의 근무와 일정은 먼저 기기 저장소에 기록합니다. 회원 연결 상태에서는 변경 식별자와 기준 버전을 붙여 서버에 보냅니다. 서버의 `items`는 캘린더별 항목과 버전을 저장하고 삭제도 기록으로 남깁니다. 같은 변경이 다시 전송돼도 중복 적용하지 않습니다. 기준 버전이 오래됐으면 충돌을 알려 내용을 고르게 합니다.

회원마다 캘린더와 개인 옵션을 분리합니다. 계정이 바뀌었을 때 이전 회원의 서버 자료를 새 회원에게 섞어 올리지 않도록 연결 전후 상태를 구분합니다. 기념일과 개인 표시 옵션은 회원 자료입니다. 위젯 모양은 홈 화면 배치와 배경에 따라 달라 `widget_style` 기기 설정으로 따로 보관합니다.

## 갱신 주기와 오프라인

전체 자료는 마지막 수신 후 30일이 지났을 때와 수동 새로고침 및 실제 변경이 있을 때 받습니다. 화면을 열어 둔 동안에는 변경 표식을 기다려 자료가 바뀌었을 때만 다시 받습니다. 변경 대기 알림이 메모리에 있으므로 서버 작업자는 한 개를 사용합니다.

앱을 닫아도 마지막 자료로 달력과 위젯을 계산합니다. 오프라인 수정은 전송 대기 목록에 남기고 연결이 가능해지면 보냅니다. 위젯의 날짜 변경 갱신과 서버 전체 수신은 별개입니다. 실시간 푸시 서비스는 없으며 운영체제의 예약 작업 시점에 따라 백그라운드 갱신이 늦어질 수 있습니다.

웹은 회원별 마지막 수신 자료를 브라우저에 보관합니다. 처음 여는 브라우저와 로그인 및 서버 복원에는 연결이 필요합니다. 앱 전체를 다시 설치했을 때 서버에 전송하지 못했던 기기 자료까지 복원하는 것은 아닙니다.

## 위젯 표시 흐름

`WidgetKind`가 월간과 두 주 및 목록과 오늘의 네 공급자를 구분합니다. `DutyWidget`은 월간의 42칸을 표시하고 작은 세 종류는 `CompactWidgetViews`로 보냅니다. 모든 갱신과 꾸미기 목록은 네 공급자의 위젯 번호를 함께 조회합니다. 월과 기간 및 모양은 위젯 번호별로 따로 읽습니다. 가로·세로 크기 변경은 `onAppWidgetOptionsChanged`로 받아 다시 표시합니다. Android 12 이상은 전달받은 크기 목록별 RemoteViews를 구성합니다. 자동 배치는 현재 방향의 높이를 보고 간단한 배치와 상세 배치를 고릅니다. 글자 배율은 RemoteViews의 실제 글자 크기에 적용합니다.

투명도는 배경의 알파값만 바꿉니다. 글자까지 흐려지지 않게 색상을 따로 유지합니다. 위젯마다 다른 설정 키를 사용하며 전체 적용을 선택하면 개별 키를 비우고 기본값을 저장합니다. 삭제된 위젯의 모양 키도 함께 정리합니다. 손상된 값은 기본 모양으로 복구해 달력이 사라지지 않게 합니다.

## 일정과 음력

시간 일정은 시작과 종료를 저장하고 선택 날짜와 겹치는 부분을 보여 줍니다. 자정이 넘는 일정은 다음 날짜에도 나타납니다. 반복은 매일과 요일별 매주 및 매월과 매년을 처리합니다. 원본 반복 항목을 수정하는 방식이며 개별 회차 예외 편집은 별도 기능이 아닙니다.

음력은 월 시작일 표를 사용합니다. 일반 월과 윤달은 별도 행입니다. 범위는 1900~2050년이며 범위 밖에는 값을 억지로 계산하지 않습니다. 자료 재생성은 별도 개발 환경에 `korean-lunar-calendar==0.3.1`을 설치한 뒤 `python tools/build_lunar.py`로 수행합니다. 결과와 라이선스가 앱과 웹에 같은 내용으로 들어가는지 확인합니다.

## 변경할 때 확인할 것

- 저장 형식을 바꾸기 전 기존 항목과 삭제 기록 및 충돌 처리 경로를 읽습니다.
- 앱과 웹이 함께 쓰는 값은 두 구현과 서버 검증을 모두 맞춥니다.
- 소속 공유 자료에 개인 일정과 기념일이 섞이지 않는지 검사합니다.
- 공휴일 수신 실패와 잘못된 JSON 및 빈 응답에서 마지막 정상 자료가 남는지 검사합니다.
- 화면만 바꾼 작업에 DB 변경을 끼워 넣지 않습니다. 자료 이전은 백업과 복구 절차를 따로 준비합니다.

## 주 시작 저장과 호환

개인 표시 설정의 `weekStart`는 일요일 0과 월요일 1만 허용합니다. 앱과 웹의 요일 머리글과 첫 날짜는 같은 설정으로 계산합니다. 토요일과 일요일 색상은 열 번호가 아니라 실제 요일을 기준으로 합니다.

구버전이 해당 필드를 보내지 않으면 서버는 이미 저장한 값을 유지합니다. 명시한 0은 일요일로 바꾸는 요청입니다. 반복 근무와 개인 설정은 기존 버전 비교와 같은 트랜잭션에서 맞춥니다. 새 DB 테이블이나 자료 일괄 이전은 없습니다.

## 이름 표시와 기본 달력 및 구독

`name_rule`은 기존 개인 items 저장소를 사용한다. 입력 검증과 최대 20개 제한 및 버전 충돌 처리와 회원 격리를 동일하게 적용한다. 이름 규칙은 소속 공유 목록에 넣지 않는다. 사람 연결은 식별자로 찾으며 삭제된 사람을 다른 사람으로 대체하지 않는다.

Android `CalendarMirror`는 사용자 선택 달력에 지난 30일부터 앞으로 366일의 사본을 쓴다. 보존 영역의 기기 식별자와 원본 종류 및 식별자와 회차 날짜로 전용 URI를 만든다. 쓰기와 삭제에는 이벤트 ID와 앱 패키지 및 전용 URI를 함께 확인한다. 반복 회차를 펼친 뒤 기존 사본과 비교해 등록과 수정 및 삭제를 적용한다. 전체 목록 계산에 실패하면 삭제 단계에 들어가지 않는다. 이 기기의 표식은 기기 백업으로 옮기지 않는다. 기본 달력에서 역방향으로 수정하는 기능은 없다.

`calendar_feeds`는 기존 DB에 추가하는 테이블이다. 캘린더별 해시와 공유 항목 및 발급 시각과 내용 해시 및 버전과 변경 시각을 보관한다. 비밀 주소 원문은 DB에 저장하지 않는다. 주소를 새로 만들면 기존 해시를 교체하며 종료하면 해당 공유 행만 삭제한다. 기존 회원과 일정 및 근무 설정은 이전하지 않는다.

서버 `calendar_export.py`는 같은 자료를 RFC 5545 형식으로 만든다. 하루 종일 일정은 종료일을 하루 뒤로 쓰고 시간 일정은 한국 시간을 UTC로 변환한다. 한글은 UTF-8 75바이트 이내로 줄을 접으며 제목과 메모의 줄바꿈 및 구분 문자를 이스케이프한다. UID는 원본과 회차 날짜로 고정하고 내용이 바뀌면 SEQUENCE와 ETag를 갱신한다. 구독 응답 전 회원 활성 상태와 공유 범위를 다시 확인한다.

관련 기준: [Android Calendar Provider](https://developer.android.com/identity/providers/calendar-provider) · [iCalendar RFC 5545](https://www.rfc-editor.org/rfc/rfc5545.html)

## 0.14.0 근무 계획과 협업 구조

WorkPlan은 적용일과 반복 기준일을 분리한 Regime 목록 및 날짜별 DayOverride와 근무 시간표를 가진다. 날짜별 변경 → 해당 날짜의 유효 제도 → 기본 제도 순서로 계산한다. Schedule.shiftOn과 날짜 색상 계산을 통하므로 화면과 위젯 및 CalendarMirror가 같은 결과를 사용한다. PlanJson은 기존 rotation 항목의 workPlan 필드로 저장한다. 구버전 클라이언트에서 필드 없이 수정하더라도 서버는 기존 계획을 보존한다. 근무 계획은 UTF-8 120000바이트 이내이며 전송은 건수와 바이트 수를 함께 제한한다.

날짜와 반복 및 시간 검증은 앱과 웹 및 서버에서 수행한다. WorkTools는 시간 일정의 반복과 자정 넘김 및 전날 근무를 대조한다. 통계는 설정된 근무표 예정시간만 합산한다. PlannerStore는 일괄 복사의 전체 입력을 먼저 검사하고 메모리 사본을 한 번 저장한다. 삭제 항목은 원래 내용을 보관한다. 화면에 일반 문장으로 변경 기록을 보여 주며 개인 계획 변경 충돌은 기존 항목 버전을 따른다.

PlanExportActivity는 출력 전용 사본을 만들고 시스템 문서 선택기로 저장한다. 공유 Provider는 외부에 공개하지 않으며 공유를 받은 수신 앱에 읽기 권한만 일시 부여한다. 파일 이름과 확장자 및 정규 경로를 검사해 출력 캐시 이외의 파일은 읽지 못하게 한다. PNG와 PDF에는 기본적으로 개인 일정 제목을 넣지 않는다. PDF는 한 페이지 그림으로 내보낸다.

서버 work\_plan.py가 근무 계산과 검증을 담당하고 calendar\_export.py의 구독 출력도 같은 계산을 사용한다. company.py는 공유할 근무제와 날짜별 근무만 추려 개인 메모와 시간 설정을 제외한다. work\_team.py는 work\_history와 work\_team\_settings 및 work\_swaps와 work\_handovers 및 work\_team\_history의 다섯 테이블을 추가한다. 기존 테이블의 행을 변환하지 않는다. 외래 키는 회원과 소속 삭제 정책을 따르며 개인 및 소속 변경 기록은 최근 200건을 유지한다.

교환 처리는 쓰기 트랜잭션 안에서 회원과 소속 및 역할과 양쪽 근무표 버전을 다시 검사한다. 확정 시 두 근무표와 양쪽 달력 수정 번호를 함께 올린다. 한쪽만 바뀌는 중간 상태는 저장하지 않는다. 본문과 확인 목록 및 읽음 표시는 인수인계 버전을 비교한다. 요청별 승인 정책을 보관하므로 설정 변경으로 기존 요청의 절차가 달라지지 않는다. 같은 소속만 조회 가능하며 전송량과 항목 수 및 날짜 범위를 제한한다.

새 서버 표는 추가 전용이다. 복구할 때 현재 DB를 덮어쓰지 말고 현재 자료를 따로 보관한 뒤 이전 서버 소스를 복원한다. 새 근무 종류와 계획을 작성한 뒤에는 해당 기능을 지원하는 앱 버전을 유지한다. APK의 낮은 설치 번호로 되돌아가기 위해 앱을 삭제하지 않는다.

## 0.14.1 휴가 저장과 설치 차단 상태

ANNUAL\_LEAVE와 MONTHLY\_LEAVE 및 VACATION과 OFFICIAL\_LEAVE 및 FAMILY\_LEAVE를 새 근무 값으로 추가했다. 기존 LEAVE는 그대로 읽고 쓴다. Shift.working과 웹 WorkPlan.working 및 서버 WORKING에서 휴가를 근무시간 합계와 시간 겹침 및 근무 중인 소속 회원 표시에서 제외한다. 날짜별 override가 주5일제 토요일보다 우선하는 기존 규칙을 유지한다. calendar\_export의 표시 이름도 함께 확장했다. DB 구조 변경과 기존 항목 일괄 변환은 없다.

설치 결과 STATUS\_FAILURE\_BLOCKED는 blocked 상태로 처리한다. 설치 완료로 표시하지 않고 같은 파일을 자동 재시도하지 않는다. 이 분기는 보안 검사나 기기 정책의 차단을 알리는 것이며 구체적인 Play 프로텍트 탐지 이유를 알아내거나 차단을 해제하지 않는다. 기존 PackageInstaller 사용과 동의한 업데이트 다운로드 및 해시·서명 검증은 유지한다.
