그림으로 보는 설명서

OS4U 는 무엇을 만들고 있나

재개발·재건축 현장에서 동의서를 받으러 다니는 사람들의 일을, 종이와 전화에서 하나의 시스템으로 옮기는 일입니다. 이 문서는 개발을 모르는 분이 읽어도 전체가 보이도록 쓴 설명서입니다.

기준 2026-10-01 · 개발 착수 2026-08-26

1

현장에서 벌어지는 일

재개발·재건축을 하려면 그 땅과 건물을 가진 사람들의 동의를 법에 정한 비율만큼 모아야 합니다. 그 동의를 받으러 집집마다 찾아가는 사람들이 있고, 그들을 모으고 배치하고 돈을 지급하는 일을 OS 포유가 합니다.

조합 (발주처) 재개발을 추진하는 주체 OS 포유 (회사) 인력을 모으고 관리·지급 현장 요원 본부장 · 팀장 · 지도사 토지등소유자 그 구역의 집·땅 주인 용역을 맡기고 수수료를 낸다 계약 · 구역 배정 일당 지급 방문 · 설명 · 동의 요청 동의서 제출 동의율을 세는 것은 조합의 일이고, 사람을 움직이는 것이 회사의 일이다
네 주체가 한 바퀴를 돈다. 조합이 회사에 용역을 맡기고, 회사가 요원을 계약·배정하고, 요원이 세대를 찾아가 설명하고, 동의서는 조합으로 돌아갑니다. 동의율을 법적으로 집계하는 것은 조합의 일이고, 회사가 책임지는 것은 「누가 · 언제 · 어디서 · 며칠 일했고 · 얼마를 받아야 하는가」입니다.

현장 요원은 셋으로 나뉩니다. 지도사가 집집마다 찾아가고, 팀장이 지도사 묶음을 맡고, 본부장이 현장 하나를 총괄합니다. 전부 회사와 계약한 개인사업자입니다.

2

지금은 어떻게 하고 있나 — 그리고 무엇이 깨지나

현재 현장은 종이와 전화로 돌아갑니다. 팀장이 수첩에 출퇴근을 적고, 종이 일보를 쓰고, 사무실의 전산 담당이 그것을 엑셀로 옮기고, 본사가 다시 정산 자료로 옮깁니다.

여기서 생기는 고장은 네 가지입니다.

  1. 같은 숫자를 세 번 옮겨 적습니다. 옮길 때마다 틀릴 기회가 생기고, 어느 쪽이 맞는지 아무도 모릅니다.
  2. 「며칠 나왔는가」가 월말에 분쟁이 됩니다. 기록이 수첩에만 있으면 요원의 기억과 팀장의 수첩이 다를 때 판정할 근거가 없습니다.
  3. 정말 그 구역에 갔는지 확인할 방법이 없습니다. 이것이 발주처가 가장 신경 쓰는 지점입니다.
  4. 사람이 빠질 때마다 전화가 수십 통 돕니다. 누가 대신 갈 수 있는지, 자격이 있는지를 매번 사람이 외워서 맞춥니다.
그래서 이 시스템의 목적은 「편리」가 아니라 「기록」입니다. 누가 언제 어디서 일했는지가 다툼 없이 남아야, 요원에게 정확히 지급되고 발주처에 정확히 보고됩니다. 설계 전체가 이 한 가지를 지키려고 만들어졌습니다.

3

시스템이 들어오면 무엇이 달라지나

지금 — 종이와 전화 요원이 현장에 도착한다 팀장이 수첩에 적는다 ① 종이 일보로 옮긴다 ② 전산이 엑셀로 옮긴다 ③ 본사가 정산 자료로 옮긴다 ④ 월말 분쟁은 전화로 해결 시스템이 들어오면 요원이 현장에 도착한다 앱에서 출근을 한 번 누른다 시각 · 위치가 그 자리에서 기록 옮겨 적는 단계가 없다 밤에 시스템이 자동으로 마감 명세가 자동으로 산출된다 요원이 자기 화면에서 확인
달라지는 것은 「옮겨 적는 횟수」입니다. 왼쪽은 같은 사실이 네 번 옮겨지고, 그 사이 어디서 틀렸는지 알 수 없어 월말에 전화로 다툽니다. 오른쪽은 현장에서 한 번 기록되면 그 뒤로는 사람 손이 닿지 않습니다 — 그래서 요원도 본사도 같은 숫자를 봅니다.
1차 출시에서는 방문 결과 입력을 켜지 않습니다. 업무 보고는 당분간 기존 오프라인 방식을 유지하고, 먼저 근태와 정산만 시스템으로 옮깁니다. 한꺼번에 바꾸면 현장이 두 체계를 동시에 쓰게 되고, 그때 사람들은 익숙한 쪽으로 돌아갑니다.

4

무엇을 만드는가 — 프로그램 9개

「앱 하나 만든다」가 아닙니다. 서로 다른 일을 하는 프로그램 9개가 맞물려 돌아갑니다. 건물에 비유하면 이해가 빠릅니다 — 창구 · 정문 경비 · 업무 처리실 · 야간 당직 · 기록 서기 · 금고입니다.

사람이 보는 것 요원 앱 (안드로이드) 출퇴근 · 위치 · 신호 없을 때 저장 요원 · 팀장 웹 콜 · 내 근무 · 현장 관리 백오피스 웹 본사 심사 · 승인 · 정산 확정 정문 — 바깥에서 닿을 수 있는 마지막 지점 API 게이트웨이 앱 요청만 받는 경비 웹 서버 화면 대신 서버가 안쪽을 부른다 — 브라우저는 안쪽 주소를 모른다 ↑ 인터넷에서 닿는다 · ↓ 사설망 — 주소를 알아도 밖에서 닿지 않는다 업무 처리실 Core API 모집 · 배정 · 근태 · 금액 계산 Admin API 심사 · 승인 · 정산 확정 · 권한 사람 없이 도는 것 배치 야간 당직 로그 Writer 기록 서기 데이터베이스 — 금고 여기에 직접 닿는 것은 위 네 가지뿐이다. 화면과 정문은 금고를 모른다 구역 자동 추천 · 예측 프로그램은 3차에 추가된다 (9번째)
핵심은 점선입니다. 인터넷에서 닿을 수 있는 것은 점선 위 두 줄까지고, 실제 업무와 금고는 점선 아래 사설망에 있습니다. 누군가 비밀번호를 훔쳐도 안쪽 주소를 알지 못하고, 알아도 밖에서 닿지 않습니다. 이 구조가 「기록의 정확성은 타협하지 않는다」를 기술로 지키는 방법입니다.

9개가 각각 무슨 일을 하나

프로그램쉽게 말하면상태
요원 앱 (안드로이드)현장에서 출퇴근을 누르고, 신호가 없는 곳에서도 기록을 모아 뒀다 나중에 보낸다미착수
요원 · 팀장 웹콜 확인 · 내 근무 조회 · 팀장의 현장 관리 화면화면 완성
백오피스 웹본사 직원이 심사하고 승인하고 정산을 확정하는 화면화면 완성
API 게이트웨이앱이 보내는 요청만 받는 정문 경비. 가짜 앱·낡은 버전을 걸러낸다동작
Core API현장 업무를 실제로 처리하는 곳. 모집 · 배정 · 근태 · 금액 계산동작
Admin API본사 업무 처리. 자격 심사 · 승인 · 정산 확정 · 권한 관리동작
배치야간 당직. 퇴근을 안 누른 근무를 밤에 마감하고, 하루치를 집계하고, 보관기간이 끝난 개인정보를 지운다미착수
로그 Writer기록 서기. 누가 언제 무엇을 했는지를 고칠 수 없는 형태로 적어 둔다 — 분쟁이 생겼을 때 내놓을 증거미착수
구역 최적화 · 예측구역을 자동으로 나눠 추천한다. 3차로 미뤘다 — 현장은 지금 사람이 판단해야 하는 일이 많다3차
눈에 보이는 화면이 전부가 아닙니다. 1차 출시에 필요한 프로그램 중 셋 — 배치 · 로그 Writer · 요원 앱 — 이 아직 코드가 없습니다. 화면은 만들면 바로 보이니 진척이 느껴지는데, 이 셋은 보이지 않아 뒤로 밀리기 쉽습니다. 그런데 이 셋이 없으면 정산을 마감할 수 없고, 분쟁에 내놓을 기록이 없고, 현장에서 위치를 모을 수 없습니다. 10월 1일 회의에서 가장 먼저 짚은 것이 이 지점입니다.

5

지금 어디까지 왔나

착수 2026-08-26, 기준 2026-10-01 — 약 5주입니다.

설계 — 무엇을 만들지 정하는 일완료

설계 문서 11종 · 결정 143건 · 데이터 구조 93개 표. 결정 143건은 「이 상황에서는 이렇게 한다」를 하나씩 정해 근거와 함께 적어 둔 것입니다.

화면 그리기 — 종이 도면 단계40화면 완료

먼저 클릭만 되는 가짜 화면(목업)으로 전부 만들어 눈으로 보고 고쳤습니다.

화면 구현 — 실제 코드로 옮기기42화면

요원 14 · 가입·인증 5 · 팀장·본부장 10 · 공개 자격검증 1 · 백오피스 12. 다만 아직 가짜 데이터로 돕니다 — 서버와 연결되지 않았습니다.

서버 — 업무 처리 프로그램3개 중 3개 동작 · 2개 미착수

게이트웨이 · Core API · Admin API 는 돌아가고 자동 검사 130건을 통과합니다. 배치와 로그 Writer 는 아직 없습니다.

화면과 서버 연결시작 전

다음 단계입니다. 여기서부터 「진짜로 도는 것」이 나옵니다.

요원 안드로이드 앱시작 전

현장에서 꼭 필요한 기능만 먼저 만듭니다 — 로그인 · 출퇴근 · 위치 · 알림 받기.

자동 검사 589건이 매번 돌아갑니다. 사람이 「잘 되는지 눌러 보는」 대신, 규칙을 깨는 코드가 들어오면 검사가 먼저 실패해서 멈춥니다. 데이터 구조 검사 459건 + 서버 검사 130건입니다. 혼자 만드는 규모에서는 이것이 품질의 거의 전부입니다.

6

어떻게 만들고 있나

① 설계를 먼저 닫고, 그다음 만든다

설계 단계에서 5주 동안 결정 143건을 정했습니다. 그러고 나서 9월 18일에 방식을 바꿨습니다 — 「만들고 고친다」. 화면을 먼저 만들어 눈으로 보고 고치는 순서입니다. 설계만 계속 다듬으면 종이 위에서는 완벽한데 실제로 눌러 보면 틀린 것이 나오기 때문입니다.

② 한 사람의 판단으로 설계를 확정하지 않는다

중요한 판단이 필요할 때마다 관점이 다른 다섯 검토자를 세웁니다. 사업·도메인 / 기술·시스템 / 보안·법규 / 현장 운영, 그리고 칭찬이 금지된 비판자입니다.

1라운드 — 서로 보지 않고 각자 제출 사업 · 도메인 돈이 도나 기술 · 시스템 만들 수 있나 보안 · 법규 출시해도 되나 현장 운영 현장이 쓰나 서로의 답을 보지 않는다 — 먼저 나온 의견에 끌려가는 것을 막는다 2라운드 — 서로의 제안을 교차 검토 「네 관점에서 이 제안의 결함은 무엇인가」 10월 1일 회의에서는 네 검토자가 모두 자기 주장을 철회했다 — 상대가 근거를 보여줬기 때문이다 3라운드 — 비판자가 합의 전체를 다시 뜯는다 독립 비판자 — 칭찬 금지, 결함만 찾는다 합의안이 사실로 깔고 있던 전제 6건을 반증했고, 확인해 보니 전부 맞았다 4라운드 — 판정하고 계획으로 확정
1라운드를 가리는 것이 이 방식의 핵심입니다. 사람도 AI 도 먼저 나온 답에 끌려갑니다. 각자 독립적으로 제출한 뒤에 부딪히게 하면, 합의가 양보가 아니라 근거로 일어납니다. 실제로 10월 1일 회의에서는 네 검토자가 전부 자기 주장을 철회했고, 마지막 비판 라운드는 계획이 사실로 믿고 있던 전제 6건을 뒤집었습니다.

③ 비판 라운드가 실제로 무엇을 찾았나

예를 하나 들면 이해가 빠릅니다. 계획은 「데이터 구조는 완료됐다」를 사실로 깔고 있었습니다. 비판자가 실제 파일을 열어 보니, 정산에 꼭 필요한 항목 몇 가지가 설계 문서에는 있는데 실제 데이터 구조에는 없었습니다. 그 상태로 정산을 만들면 세금 증빙 없이 「지급 완료」를 찍는 코드가 먼저 생깁니다.

그래서 계획에 단계 하나를 끼워 넣었습니다. 문서가 아니라 실제 파일을 열어 확인하는 것, 이것이 비판 라운드를 두는 이유입니다.

7

앞으로 남은 일

8개 묶음으로 나눴습니다. 순서이면서 통과 기준입니다 — 앞 묶음이 기준을 넘지 못하면 다음으로 가지 않습니다.

1 · 기반 연결 통로 · 타입 계약 외부 신청 접수 2 · 첫 연동 용역 개설 · 자격 승인 인력 배정 3 · 근태 출퇴근 · 위치 · 앱 구역 밖 출근 승인 4 · 마감 야간 당직 · 집계 기록 서기 5 · 정산 선결 구조 비판 라운드가 찾아 추가된 단계 6 · 정산 마감 → 명세 → 확정 지급 완료 7 · 잔여 모집콜 · 가입 심사 공지 · 고객센터 R · 출시 준비 배포 · 경보 · 복구 처음부터 병행 금액이 맞는지 여기서 가장 먼저 확인한다 1차 출시에서 끄는 것 — 방문 결과 입력 · 토지소유자 명부(2차) · 구역 자동 추천(3차)
2단계 끝의 파란 점이 이 계획에서 가장 값싼 보험입니다. 원래 계획은 6단계(정산)에 가서야 금액이 맞는지 알 수 있었습니다. 그런데 정산 기록은 한 번 확정되면 고칠 수 없게 만들어 뒀습니다 — 요율 설정이 2단계에서 틀렸다면 6단계에서 발견해도 이미 늦습니다. 그래서 2단계 끝에 「한 사람 · 하루치」만 끝까지 통과시켜 금액을 손계산과 맞춰 보는 단계를 넣었습니다. 반나절이면 됩니다.

출시는 세 번에 나눠서 합니다

차수무엇을 켜나
1차자격증 관리 · 본사 운영 · 지도사 앱(모집콜 · 출퇴근 · 내 수당 · 근무구역) · 출퇴근 위치. 업무 보고는 오프라인 유지
2차업무 표준화·전산화 · 토지소유자 명부 관리
3차본부장·팀장 모드 확장 · 구역 자동 추천(AI)

이건 출시 범위이지 개발 순서가 아닙니다. 2차·3차 기능도 이미 만들어 둔 것이 있고, 1차에서는 켜지 않을 뿐입니다.

8

지금 정해야 하는 것

10월 1일 회의가 끝까지 풀지 못한 것이 네 가지입니다. 기술로 풀 문제가 아니라 「어떻게 할지」를 정해야 풀리는 것들입니다.

① 1차에 위치를 켜는가 — 가장 먼저 정해야 합니다

이 한 가지가 근태 · 마감 · 개인정보 보관 · 동의 받는 방식 · 앱 일정을 동시에 결정합니다.

켠다면 — 요원 앱이 먼저 있어야 합니다(웹 브라우저는 화면이 꺼지면 위치가 끊깁니다). 위치기반서비스 신고와 구글 플레이 심사도 선행합니다. 둘 다 리드타임이 깁니다.

끈다면 — 앱 없이 먼저 시작할 수 있지만, 정말 그 구역에 갔는지 확인할 방법이 없습니다. 발주처가 가장 신경 쓰는 지점을 1차에서 못 보여줍니다.

한 번 정하면 되돌리기 어렵습니다 — 요원에게 받는 동의 기록은 나중에 고칠 수 없게 만들어 뒀습니다.

② 구역 밖에서 출근을 눌렀을 때, 승인이 늦어지면 어떻게 하나

지도 주소가 틀려서 구역 밖으로 찍히는 일은 생깁니다. 승인이 안 나면 그날 일당이 들어가지 않습니다.

당일 18시까지 처리가 안 되면 자동으로 승인할지, 위로 보고할지 정해야 합니다. 그리고 월말에 반려하는 것은 금지해야 합니다 — 이미 일한 사람에게 집행할 수 없습니다.

③ 성과급을 무슨 기준으로 나누나

지금 설계는 개별 성과 비례 하나뿐입니다. 동의율이나 접촉률로 나누는 안도 있습니다.

다만 1차에서는 업무 보고가 오프라인이라 동의율·접촉률을 계산할 수 없습니다 — 1차는 현행 방식 유지가 사실상 전제입니다.

④ 승인 화면에 요원의 위치를 띄울까

본사가 구역 밖 출근을 판단하려면 정보가 필요한데, 좌표를 그대로 띄우는 것은 개인위치정보 노출입니다.

제안: 지도와 좌표 없이 구역 경계로부터의 거리와 방향, 그리고 같은 현장·같은 시각에 다른 요원들은 성공했는지만 보여줍니다. 지도 주소 오류는 보통 여러 명이 동시에 틀리기 때문에, 이것이 가장 강한 단서입니다.

이 밖에 변호사 확인이 필요한 항목 4건을 따로 정리해 뒀습니다 — 기록 보관 방식이 법이 요구하는 「보존」에 해당하는지, 사내 근태 목적의 위치 수집이 신고 대상인지 등입니다. 법 해석이 필요한 것은 추측하지 않고 표시만 해 두는 것이 이 프로젝트의 원칙입니다.

9

용어 사전

이 문서와 설계 자료에 나오는 말들입니다.

API
프로그램끼리 주고받는 창구. 사람이 보는 화면이 아니라, 화면 뒤에서 「이 사람 출근 처리해 줘」를 주고받는 통로입니다.
백오피스
본사 직원만 쓰는 관리 화면. 요원이 보는 화면과 완전히 분리해서 만듭니다 — 권한이 센 기능이 섞이면 사고가 번집니다.
배치
사람이 누르지 않아도 정해진 시각에 혼자 도는 프로그램. 밤에 마감하고 집계하고, 보관기간이 끝난 개인정보를 지웁니다.
목업
클릭만 되는 가짜 화면. 데이터는 없고 모양만 있습니다. 코드로 옮기기 전에 눈으로 보고 고치려고 먼저 만듭니다.
지오펜스
지도 위에 그려 둔 울타리. 그 안에서 출근을 눌렀는지 판정하는 데 씁니다.
데이터베이스 · 스키마
데이터를 담는 금고와 그 설계도. 「어떤 정보를 어떤 모양으로 담는가」를 미리 정해 두면, 틀린 데이터가 들어오는 것을 금고가 막아 줍니다.
커밋
작업 한 덩이를 기록으로 남기는 것. 「무엇을 왜 바꿨는가」가 함께 남아 나중에 되돌릴 수 있습니다. 현재 116건.
결정 로그
「이 상황에서는 이렇게 한다」를 번호 붙여 근거와 함께 적어 둔 목록. 현재 143번까지. 근거 없는 결정은 다음 사람이 되돌려 버립니다.
자동 검사
사람이 눌러 보는 대신 컴퓨터가 매번 확인하는 규칙. 규칙을 깨는 코드가 들어오면 검사가 먼저 실패해 멈춥니다. 현재 589건.
해시체인
기록을 사슬처럼 엮어서, 중간 하나를 고치면 뒤가 전부 어긋나 들통나게 만드는 방식. 「나중에 기록을 고쳤다」는 의심을 막기 위해 씁니다.