⚠️ 본 글은 대학생이 직접 비영리법인 설립허가, 사단법인 등기, 공익법인 지정추천 신청 등을 진행하며 조사한 내용을 바탕으로 작성한 글입니다. 국가전문자격을 갖춘 행정사, 법무사 등이 작성 또는 검토한 글이 아니므로 참고용으로만 사용해 주세요.

비영리단체?

위는 모두 비영리단체입니다. 비영리단체는 지역에서, 사회에서, 국가에서, 세계에서 영리를 추구하지 않는 다양한 활동을 추구하고 있습니다. 우리는 일상생활에서 아래 용어들을 특별히 구분하지 않고 사용하고 있지만, 비영리단체에서 업무를 맡게 되거나, 비영리단체의 특성을 파악하기 위해서는 아래 용어의 의미를 정확히 아는 것이 중요합니다. 오늘 글에서는 아래 용어들을 포함하여 비영리단체가 가지고 있는 법적, 세무적 구분을 명확히 알아보도록 하겠습니다.

💡 비영리단체, 사단법인, 재단, 공익법인, 비영리민간단체, 공익법인등, 공익단체, 기부금단체

법인

먼저 법인의 정의를 정확히 짚고 넘어가도록 하겠습니다. 법인은 “자연인 이외의 것으로서 법률에 의하여 권리능력이 인정된 단체 또는 재산, 법적인 독립체”를 말합니다. 법인의 권리능력을 서술한 법률은 민법, 상법, 법인세법, 상속세 및 증여세법 등 많지만, 법인 성립의 대원칙은 아래 민법의 조항에서 유일하게 서술하고 있습니다.

민법 제3장 법인 제1절 총칙 제31조(법인성립의 준칙) 법인은 법률의 규정에 의함이 아니면 성립하지 못한다.

따라서 위 법률에 따라, “법인”은 법률에 정의된 방법과 절차, 형식에 의해서만 성립할 수 있으며, 관습이나 사회적 합의, 특정 조직 구성원의 단순 합의에 의해서만 성립할 수는 없습니다. 민법에서는 위 조항에 이어 법인의 대분류를 제시하고 있는데, 아래와 같습니다.

민법 제3장 법인 제1절 총칙

제32조(비영리법인의 설립과 허가) 학술, 종교, 자선, 기예, 사교 기타 영리아닌 사업을 목적으로 하는 사단 또는 재단은 주무관청의 허가를 얻어 이를 법인으로 할 수 있다.

민법 제3장 법인 제1절 총칙

제39조(영리법인)

① 영리를 목적으로 하는 사단은 상사회사설립의 조건에 좇아 이를 법인으로 할 수 있다.

② 전항의 사단법인에는 모두 상사회사에 관한 규정을 준용한다.

법인은 영리를 목적으로 하는지에 따라 비영리법인과 영리법인으로 나뉩니다. 여기서 영리의 기준은 “법인이 재산의 이익 또는 수익을 목적으로 활동하는가?”입니다. 다시말해, 비영리법인도 공익 활동을 수행하기 위한 재원을 마련하기 위해 이익 또는 수익을 얻기 위한 활동(국세청에서는 수익사업이라고 부릅니다.)을 할 수 있습니다. 비영리법인 또는 비영리단체가 돈을 벌 수 없다는 것은 흔한 오해입니다.

영리법인은 보통 우리가 “회사”라고 부르며, 상사회사에 관한 규정은 상법으로 대표됩니다. 본 글은 비영리에 관한 용어를 정리하고 있으므로 이 분류는 넘어가도록 하겠습니다.

상법 제1편 총칙 제1장 통칙 제1조(상사적용법규) 상사에 관하여 본법에 규정이 없으면 상관습법에 의하고 상관습법이 없으면 민법의 규정에 의한다.

비영리법인은 다시 사단법인과 재단법인으로 나누어집니다. 사단법인은 “특정한 목적을 위해 모인 사람들의 집합체로 구성된 법인”이고, 재단법인은 “일정한 목적에 바쳐진 재산에 의해 구성된 법인”입니다. 즉, 일정한 목적에 의해 “사람”이 모였는지, “재산”이 모였는지에 의해 구분합니다. 이는 설립 관련 민법 조항에서도 드러납니다.

민법 제3장 법인 제2절 설립

제40조(사단법인의 정관) 사단법인의 설립자는 다음 각호의 사항을 기재한 정관을 작성하여 기명날인하여야 한다.

1. 목적

2. 명칭

3. 사무소의 소재지

4. 자산에 관한 규정

5. 이사의 임면에 관한 규정

6. 사원자격의 득실에 관한 규정

7. 존립시기나 해산사유를 정하는 때에는 그 시기 또는 사유

민법 제3장 법인 제2절 설립 제43조(재단법인의 정관) 재단법인의 설립자는 일정한 재산을 출연하고 제40조제1호 내지 제5호의 사항을 기재한 정관을 작성하여 기명날인하여야 한다.

본 글에서는 비영리사단법인 중심으로 설명을 이어가도록 하겠습니다. 현재까지 법인의 분류를 살펴보면 아래와 같습니다.

특정한 목적을 위해 모인 집단, 사단

사단은 여러 동음이의어를 가지고 있습니다. 군대에서 사단은 조직 및 편제 단위의 하나로 사용되고, 스포츠 분야에서는 흔히 축구 감독의 이름을 붙여 국가대표팀을 “히딩크 사단”등으로 부르기도 합니다. 오늘 본 글에서 다룰 세번째 동음이의어 사단(社團)은 “특정 목적을 가진 사람들이 모여 결성한 단체”를 말합니다.

흔히 사단법인 OOO으로 시작되는 법인들이 여러분들께 제일 익숙한 형태일 것으로 생각되는데요. 모든 사단이 법인인 것은 아닙니다. 사단의 실질을 가지고 있지만 법인으로 되지 않은 것을 비법인사단이라고 하며, 그 예시는 모두에게 익숙한 아래 단체들입니다.

• 교회와 사찰 등 종교단체

• 아파트입주자대표회의, 부녀회, 아파트관리사무소 등

• 동아리, 학회, 총학생회 등 학생단체

• 정당

이들은 법적으로 법인은 아닙니다. 실무적으로는 법원에 등기를 하지 않아, 등기사항증명서(등기부등본) 열람이 불가능합니다. 비법인사단인 이유는 각 단체마다 다양하겠지만, 큰 이유 중 하나는 법인 설립에 필요한 노력과 비용 대비 그 편익이 크지 않은 경우입니다. 법인 설립은 그 과정에서 공과금에 15만원 이상, 법무사 대행 비용에 추가로 15만원 이상이 발생합니다. 하지만 위의 단체들이 법인격을 가졌을 때 얻을 수 있는 편의는 사실상 없습니다.

그렇다면 법적으로 이들은 보통 어떤 지위를 가지고 있을까요? 단체 운영을 위해 필요한 가장 필수적인 요소 중에 하나는 단연코 단체 명의의 계좌일 것입니다. 유명한 명언을 하나 인용하겠습니다.

 📌 인간에게 피할 수 없는 두 가지가 있다. 하나는 죽음이고 하나는 세금이다.
    (In this world, nothing is certain except death and taxes.)
    - 벤자민 프랭클린

국세청은 더욱 정확하게 세금을 징수해야 하기 때문에, 법인이 아닌 단체 중 그 단체의 계속성과 동질성이 유지되는 것으로 볼 수 있는 단체에 대해 세무서장의 승인을 받은 후 “법인으로 보는 단체”로 승인해 주는 제도를 운영하고 있습니다. “법인으로 보는 단체”로 승인을 받게 되면, “고유번호”가 적혀 있는 “고유번호증”을 받을 수 있게 됩니다. 이 고유번호증이 비로소 은행에서 단체 명의의 계좌를 발급받을 수 있는 서류 중 하나입니다. 아래는 국세기본법에서 세법을 적용할 때, 당연히 법인인 객체와 법인으로 보는 객체를 정의하는 조항입니다.

국세기본법 제1장 총칙 제4절 인격

제13조(법인으로 보는 단체 등)

① 법인(「법인세법」 제2조제1호에 따른 내국법인 및 같은 조 제3호에 따른 외국법인을 말한다. 이하 같다)이 아닌 사단, 재단, 그 밖의 단체(이하 “법인 아닌 단체”라 한다) 중 다음 각 호의 어느 하나에 해당하는 것으로서 수익을 구성원에게 분배하지 아니하는 것은 법인으로 보아 이 법과 세법을 적용한다.

1. 주무관청의 허가 또는 인가를 받아 설립되거나 법령에 따라 주무관청에 등록한 사단, 재단, 그 밖의 단체로서 등기되지 아니한 것

2. 공익을 목적으로 출연(出捐)된 기본재산이 있는 재단으로서 등기되지 아니한 것

② 제1항에 따라 법인으로 보는 사단, 재단, 그 밖의 단체 외의 법인 아닌 단체 중 다음 각 호의 요건을 모두 갖춘 것으로서 대표자나 관리인이 관할 세무서장에게 신청하여 승인을 받은 것도 법인으로 보아 이 법과 세법을 적용한다. 이 경우 해당 사단, 재단, 그 밖의 단체의 계속성과 동질성이 유지되는 것으로 본다.

1. 사단, 재단, 그 밖의 단체의 조직과 운영에 관한 규정(規程)을 가지고 대표자나 관리인을 선임하고 있을 것

2. 사단, 재단, 그 밖의 단체 자신의 계산과 명의로 수익과 재산을 독립적으로 소유ㆍ관리할 것

3. 사단, 재단, 그 밖의 단체의 수익을 구성원에게 분배하지 아니할 것

③ 제2항에 따라 법인으로 보는 법인 아닌 단체는 그 신청에 대하여 관할 세무서장의 승인을 받은 날이 속하는 과세기간과 그 과세기간이 끝난 날부터 3년이 되는 날이 속하는 과세기간까지는 「소득세법」에 따른 거주자 또는 비거주자로 변경할 수 없다. 다만, 제2항 각 호의 요건을 갖추지 못하게 되어 승인취소를 받는 경우에는 그러하지 아니하다.

④ 제1항과 제2항에 따라 법인으로 보는 법인 아닌 단체(이하 “법인으로 보는 단체”라 한다)의 국세에 관한 의무는 그 대표자나 관리인이 이행하여야 한다.

⑤ 법인으로 보는 단체는 국세에 관한 의무 이행을 위하여 대표자나 관리인을 선임하거나 변경한 경우에는 대통령령으로 정하는 바에 따라 관할 세무서장에게 신고하여야 한다.

⑥ 법인으로 보는 단체가 제5항에 따른 신고를 하지 아니한 경우에는 관할 세무서장은 그 단체의 구성원 또는 관계인 중 1명을 국세에 관한 의무를 이행하는 사람으로 지정할 수 있다.

⑦ 법인으로 보는 단체의 신청ㆍ승인과 납세번호 등의 부여 및 승인취소에 필요한 사항은 대통령령으로 정한다.

⑧ (전환 국립대학 법인에 대한 조항이므로 생략)

마지막으로 비영리사단법인 중 특수한 형태의 법인이 하나 있는데요, 바로 아래 특별법에 의한 공익법인입니다. 학술 및 자선 분야에 대한 기부를 장려하기 위해 만든 특별법이나, 비영리사단법인과 실질적으로 큰 차이가 있지는 않습니다.

공익법인의 설립ㆍ운영에 관한 법률

제1조(목적)

이 법은 법인의 설립ㆍ운영 등에 관한 「민법」의 규정을 보완하여 법인으로 하여금 그 공익성을 유지하며 건전한 활동을 할 수 있도록 함을 목적으로 한다.

제2조(적용 범위)

이 법은 재단법인이나 사단법인으로서 사회 일반의 이익에 이바지하기 위하여 학자금ㆍ장학금 또는 연구비의 보조나 지급, 학술, 자선(慈善)에 관한 사업을 목적으로 하는 법인(이하 “공익법인”이라 한다)에 대하여 적용한다.

여기까지 비영리사단의 종류를 모두 정리해 보면 아래와 같습니다.

기부금은 어떤 형태를 갖추면 수령할 수 있을까?

비영리법인에 대해 많은 사람들이 가지고 있는 이미지 중 하나는 바로 기부를 받는다는 것입니다. 기부금을 통해 비영리법인은 더욱 다양한 활동을 전개할 수 있게 되고, 국가는 이를 장려하기 위해, 기부금 중 일정 부분에 대해 연말정산에서 세액공제를 해줍니다. 결국 법적으로 중요한 것은, 소득세법과 법인세법에서 기부금으로 인정받는 법인의 형태입니다.

세법에서는 이를 “공익법인등”이라고 부르고 있으며, 상속세 및 증여세법, 소득세법 및 법인세법에서 그 설명이 이루어지고 있습니다. 여기서 주의할 점은, 세법에서 “공익법인등”은 위에서 소개한 “공익법인의 설립ㆍ운영에 관한 법률”에서의 “공익법인”과 완전히 별개의 개념입니다.

“공익법인등”의 범위를 소개하고 있는 “상속세 및 증여세법 시행령”을 소개합니다. 아래 조항 중 제9항의 공익법인등, 공익단체가 바로 국세청에서 기부금 수령을 인가받은 법인/단체에 대한 내용입니다. “공익법인등”은 법인, “공익단체”는 법인으로 보는 단체에 해당하며, 이외의 차이는 크게 없습니다. “공익법인등”으로 지정받는 조건과 절차에 대해서는 별도 글로 다루도록 하겠습니다.

• “공익법인등”의 2021년 이전 명칭은 지정기부금단체입니다.

• 일반기부금단체, 지정기부금단체, 특례기부금단체는 지금은 사용하지 않는 과거 용어입니다.

상속세 및 증여세법 시행령

제12조(공익법인등의 범위)

법 제16조제1항에서 “대통령령으로 정하는 사업을 하는 자”란 다음 각 호의 어느 하나에 해당하는 사업을 하는 자(이하 “공익법인등”이라 한다)를 말한다. 다만, 제9호를 적용할 때 설립일부터 1년 이내에 「법인세법 시행령」 제39조제1항제1호바목에 따른 공익법인등으로 고시된 경우에는 그 설립일부터 공익법인등에 해당하는 것으로 본다.

1. (종교 관련 사업, 학교, 유치원, 사회복지법인, 의료법인)

2. 삭제

8. 「법인세법」 제24조제2항제1호에 해당하는 기부금을 받는 자가 해당 기부금으로 운영하는 사업

9. 「법인세법 시행령」 제39조제1항제1호 각 목에 따른 공익법인등 및 「소득세법 시행령」 제80조제1항제5호에 따른 공익단체가 운영하는 고유목적사업. 다만, 회원의 친목 또는 이익을 증진시키거나 영리를 목적으로 대가를 수수하는 등 공익성이 있다고 보기 어려운 고유목적사업은 제외한다.

10. 「법인세법 시행령」 제39조제1항제2호다목에 해당하는 기부금을 받는 자가 해당 기부금으로 운영하는 사업. 다만, 회원의 친목 또는 이익을 증진시키거나 영리를 목적으로 대가를 수수하는 등 공익성이 있다고 보기 어려운 고유목적사업은 제외한다.

11. 삭제

지방자치단체로부터 지원을 받으려면?

비영리단체는 또한 지방자치단체로부터 지원을 받을 수 있도록 되어 있습니다. 법인인지의 여부와 관계없이, 아래 요건을 갖춘 단체를 “비영리민간단체”라 합니다. “비영리민간단체”의 경우, 매년 소속된 지방자치단체의 지원사업에 참여하여, 지원금을 지급받을 수 있습니다.

비영리민간단체 지원법

제2조(정의)

이 법에 있어서 “비영리민간단체”라 함은 영리가 아닌 공익활동을 수행하는 것을 주된 목적으로 하는 민간단체로서 다음 각호의 요건을 갖춘 단체를 말한다.

1. 사업의 직접 수혜자가 불특정 다수일 것

2. 구성원 상호간에 이익분배를 하지 아니할 것

3. 사실상 특정정당 또는 선출직 후보를 지지ㆍ지원 또는 반대할 것을 주된 목적으로 하거나, 특정 종교의 교리전파를 주된 목적으로 설립ㆍ운영되지 아니할 것

4. 상시 구성원수가 100인 이상일 것

5. 최근 1년 이상 공익활동실적이 있을 것

6. 법인이 아닌 단체일 경우에는 대표자 또는 관리인이 있을 것

비영리민간단체 지원법 제5조(비영리민간단체에 대한 지원 등) ① 비영리민간단체의 활동은 자율성이 보장되어야 한다. ② 행정안전부장관, 시ㆍ도지사나 특례시의 장은 공익활동에 참여하는 비영리민간단체에 대하여 필요한 행정지원 및 이 법이 정하는 재정지원을 할 수 있다.

마무리

오늘은 아래 용어들의 관계와 의미를 정리할 수 있는 글을 공유드렸습니다. 이 글을 통해 대한민국에서 비영리 분야 사업을 시작하고자 하시는 분들에게 많은 도움이 되길 바랍니다.

💡 비영리단체, 사단법인, 재단, 공익법인, 비영리민간단체, 공익법인등, 공익단체, 기부금단체

출처

• https://ko.wikipedia.org/wiki/사단

• https://ko.wikipedia.org/wiki/사단법인

• https://ko.wikipedia.org/wiki/재단법인

• https://ko.wikipedia.org/wiki/법인

• https://ko.wikipedia.org/wiki/비영리_단체

• 민법 [시행 2024. 5. 17.] [법률 제19409호, 2023. 5. 16., 타법개정]

• 상법 [시행 2020. 12. 29.] [법률 제17764호, 2020. 12. 29., 일부개정]

• 공익법인의 설립ㆍ운영에 관한 법률 ( 약칭: 공익법인법 ) [시행 2017. 12. 12.] [법률 제15149호, 2017. 12. 12., 일부개정]

• 국세기본법 [시행 2025. 1. 1.] [법률 제20611호, 2024. 12. 31., 일부개정]

• 상속세 및 증여세법 시행령 [시행 2024. 9. 15.] [대통령령 제34881호, 2024. 9. 10., 타법개정]

• 비영리민간단체 지원법 ( 약칭: 비영리단체법 ) [시행 2023. 4. 27.] [법률 제18846호, 2022. 4. 26., 일부개정]

• 국세청 > 국세신고안내 > 법인신고안내 > 공익법인 > 공익법인 개요https://www.nts.go.kr/nts/cm/cntnts/cntntsView.do?mi=2388&cntntsId=7751

• https://brunch.co.kr/@fundraising/10

최근 Google Play 개발자 계정에 대해 새로운 정책이 적용되었습니다. 모든 개발자 계정은 아래 정보를 제공해야 하는데요. 여기서 제일 중요한 변경점은 단체를 등록할 때 DUNS 번호를 제공해야 된다는 점일 것입니다.

• Legal name and address

• D-U-N-S number, if registering as an organization

• Contact email address and phone number

• Developer email address and phone number shown on Google Play where applicable

• Payment methods where applicable

• Google payment profile linked to your developer account

DUNS 번호란 무엇일까요? iOS 앱을 개발하시는 개발자 분들께는 아마 익숙한 번호일 것입니다.

D-U-N-S 번호는 9자리의 고유 번호로서 지역을 기준으로 사업체를 식별하는 번호입니다. D&B(Dun & Bradstreet)가 할당하고 관리하는 D-U-N-S 번호는 널리 사용되는 표준 사업체 식별자입니다.

위 애플 개발자 지원 홈페이지의 설명처럼, DUNS 번호는 전세계에서 통용되는 사업자등록번호처럼 사용되고 있습니다. 한국에서는 (주)나이스디앤비 에서 등록 및 관리를 대행하고 있습니다. 등록 수수료는 무료이나, 사업자등록번호증 또는 고유번호증의 번역 공증을 받아 제출해야 하기 때문에 번역공증 수수료가 발생합니다. SPARCS는 이미 작년 애플 개발자 계정을 생성할 때, DUNS 번호를 발급받아 놓았으므로, 해당 번호를 조회하여 입력할 수 있었습니다.

Google Play Console에 들어가면 개발자 계정 인증 시작하기 화면이 뜨는 것을 보실 수 있습니다. 기존 계정을 계속 사용하고 싶은 개발자 분들이라면, “시작하기” 버튼을 눌러 정보를 입력하시면 됩니다. 하지만 SPARCS 에서는 이번 기회에 계정 소유자를 이전하기 위해 새 계정에서 확인을 진행했습니다.

처음 SPARCS 단체 계정을 생성할 때는 SPARCS가 Google Workspace를 사용하고 있지 않은 상태였습니다. 따라서 개인 계정인 sparcs.kaist@gmail.com 으로 구글 개발자 계정을 생성하여 운영하고 있었습니다. 하지만 이제 계정 관리의 편의성을 위해 app@sparcs.org 으로 업무용 계정을 생성하여 운영하고자 합니다.

더불어, 현실적인 문제도 존재했습니다. 기존 계정에서는 유료 앱이나 인앱 구매가 포함된 앱을 배포하는 계정으로 설정되어 있어, 사업자 등록 번호, 통신판매 신고 번호 및 통신판매업 신고를 받은 기관 이름(시/군/구청)을 입력해야 했습니다. (위 스크린샷의 마지막 화면 참조) 저희 SPARCS는 유료 앱 판매 계획이 없어 아직 사업자 등록 및 통신판매업 신고를 진행하지 않았기 때문에, 더욱 기존 계정 확인 절차를 진행하기 어려웠습니다.

새로운 Google Play Console 계정 생성

먼저 구글 워크스페이스 Admin Console에서 app@sparcs.org 계정을 생성한 후 Google Play 개발자 계정을 생성했습니다. 생성하는 과정은 인터넷에 설명하는 글이 많으니 따로 작성하지 않겠습니다. 25달러 결제가 필요하며, Organization 인증을 위해 고유번호증 또는 사업자등록증 한국어 원본 문서 업로드가 필요합니다. 승인 절차가 필요하다고 안내되는데, 저의 경우 추석 연휴 기간이었음에도 불구하고 만 하루 내에 처리되었습니다.

새로운 개발자 계정으로 앱 이전

이제 마지막으로 새롭게 생성한 개발자 계정으로 앱을 이전하여 보겠습니다. 과거에는 구글에 직접 이메일로 앱 이전을 문의하여야 했지만, 이제는 Google Play Console 내의 메뉴로 바로 이전이 가능합니다. 그 과정을 함께 살펴보겠습니다.

Google Play Console에서 “설정”을 클릭한 뒤 “앱 이전”을 클릭합니다.

새 개발자 계정 ID의 경우 Google Play Console에 접속했을 때 첫 화면에 나오는 ID를 입력하면 됩니다. 이전 이유과 비즈니스 관계는 적절한 옵션을 선택해 주시면 되고, 전송할 앱 역시 원하는 앱을 골라 선택하면 됩니다. 여기서는 기존 계정과 새 계정의 트랜잭션 ID를 찾기가 어려운데요.

https://payments.google.com/

위 링크에 접속합니다. 이때 “아직 활동 없음”이라고 조회되어도 오른쪽 위에서 알맞는 프로필을 선택하면 구매 내역을 확인할 수 있습니다. 저희 SPARCS의 경우 Google Play 게시용 결제 프로필과, 실제 결제용 담당자 프로필이 분리되어 있었습니다.

거래내역에서 “Developer Registration Fee”라고 되어있는 항목을 클릭해서, 오른쪽 세부내용을 확인하면 거래 ID를 확인할 수 있습니다. “PDS.”로 시작하는 이 아이디 전체를 복사하여 트랜잭션 ID에 붙여넣으면 됩니다. (PDS도 포함해서 붙여넣어 주세요) 새 계정의 트랜잭션 ID도 동일하게 조회하여 입력하면 됩니다.

SPARCS의 경우 동일한 법인에서 두 계정을 소유했으며, 계정의 기본 이메일 주소를 변경하기 위해 앱을 이전하고자 합니다. 이전 대상인 앱은 Ara, OTL, Taxi 3개입니다.

그럼 이제 기존 계정에서는 이전 요청이 대기중이라고 뜨는 것을 볼 수 있습니다. 반대로 새 계정에서 동일한 페이지로 접속하면, “나에게 이전 중인 앱” 섹션에 대기중인 요청이 조회됩니다. “요청 검토”를 클릭한 후, “동의 및 이전을 누르면 수락이 완료됩니다. 수락 직후 바로 이전이 완료되는 것은 아니며, 새 계정에서 앱을 관리할 수 있게 되면 이메일 알림이 온다고 합니다.

• 앱 이전 요청 수락

글에서는 Google Play 개발자 계정에서 변경된 점과, 새롭게 앱을 이전하는 방법에 대해서 다루었습니다. 모두 즐거운 안드로이드 앱 개발 되시길 바랍니다. 감사합니다 :)

출처

Play Console Requirements - Play Console Help

D-U-N-S® 번호 - 지원 - Apple Developer

https://www.nicednb.com/index_new.do

https://www.dnb.com/de-de/upik-en.html

안녕하세요, SPARCS OTL 팀 Tech Lead 오승빈입니다.

저희 KAIST 학부 총학생회 산하 SPARCS는 인턴 제도를 운영하고 있는데요. 매 학기 단체에 새로 들어온 신입 회원들은 한학기동안 신입생 세미나와 신입생 프로그램이라는 공통 온보딩 교육을 듣게 됩니다. 하지만 이 제도의 경우 이미 개발을 어느 정도 경험한 회원들은 이미 알고 있는 내용으로 구성된 세미나를 다시 들어야 하고, 신입생 프로젝트가 발표 및 심사용으로만 개발되고 버려진다는 문제점이 있습니다. 그래서 제가 회장으로 취임한 2022년 봄학기부터 인턴 제도를 신설하게 되었습니다! 인턴으로 선발된 팀원들은 첫 학기동안 프로젝트 팀에 소속되서 실제 배포되는 기능에 기여하고, 해당 내용으로 발표를 진행하여 준회원에서 정회원으로 승급합니다.

이번 2024년 봄학기 OTL 팀에서는 두명의 인턴 분께서 참여해 주셨습니다. 앱 파트 정재현(edge)님과 디자인 파트 김희진(gimme)님이신데요. 오늘은 정재현 님과 OTL 앱 졸업플래너 탭 기능추가를 하며 겪은 이야기를 해볼까 합니다.

OTL팀 앱 인턴 과제

이번 앱 파트 인턴 과제는 아래의 순서로 구성하였습니다.

1. Github Issue, Pull Request 등 팀 협업 방식 온보딩

2. OTL App README.md에 Contributor 추가하기

3. 시간표가 하나만 남았을 때, 삭제 불가능 다이얼로그 띄우기

4. 만든 사람들 페이지를 단일 SVG에서 컴포넌트로 리팩터링

5. 과목 후기가 무한 로딩되는 버그 고치기

6. Figma 디자인을 받아 졸업플래너 탭 구현하기

OTL 팀 Project Manager이신 조유민(yumyum)님과 협의하여, 팀 협업부터 코드 구조 파악, 컴포넌트 제작, 버그 수정, 그리고 마지막으로 디자이너와의 협업을 통한 신규 페이지 추가까지 점진적으로 큰 업무에 기여하실 수 있도록 설계하였습니다.

5월이 되어 마지막 과제에 다다르고, 정재현 님께서 졸업플래너 탭이 어느정도 개발이 완료되었다는 슬랙 메세지를 보내주셨고, 저는 테스트를 위해 Testflight로 앱을 빌드에서 팀 내부에 전파했습니다. 그런데 문제가 발생했습니다. Testflight를 통해 설치한 앱을 실행해 보니, 회색 화면밖에 나오지 않았던 것입니다.

Firebase Crashlytics를 통한 오류 원인 확인

릴리즈된 앱의 오류 분석을 위해 저희 OTL 팀은 Firebase Crashlytics를 사용하고 있습니다. 콘솔에서 앱 버전, 제가 앱을 사용한 시각과 플랫폼, iOS 버전 등을 대조해본 결과 아래 이벤트를 발견할 수 있었습니다.

배포 과정에서 발생한 문제가 아니라, Flutter Widget 관련되어 발생한 문제임을 확인할 수 있었습니다. 더 자세한 디버깅을 위해서, 로컬 개발 환경에서 릴리즈 설정으로 빌드하여 테스트해 보기로 합니다.

Flutter 앱 로컬 개발 환경에서 릴리즈 빌드하기

이런 문제가 발생한 경우, 앱을 Debug 설정으로 빌드 했을때와 Release 설정으로 빌드 했을때 결과물에 차이가 있기 때문입니다. 따라서, 로컬 개발 환경에서 Release 설정으로 앱을 빌드하여 테스트해보아야 하며, 그 명령어는 아래와 같습니다.

flutter run --release

iOS 앱을 빌드할 때에는 위의 설정만으로 충분하지만, Android 앱의 경우 추가 설정이 필요합니다. android/app/build.gradle 파일에서 아래 signingConfigs와 buildTypes를 변경해야합니다.

android {
		....
    signingConfigs {
        release {
            keyAlias keystoreProperties['keyAlias']
            keyPassword keystoreProperties['keyPassword']
            storeFile keystoreProperties['storeFile'] ? file(keystoreProperties['storeFile']) : null
            storePassword keystoreProperties['storePassword']
        }
    }
    ....
}

위 설정은 Release 빌드 과정에서 Google Play Store에 앱 번들을 업로드할 수 있도록 Upload용 인증서의 파일 위치와 비밀번호 등을 설정해 주는 부분인데요. 저희 팀에서는 Upload용 인증서와 CI용 인증서를 분리해서 관리하고 있기 때문에 아래 코드로 변경해 줍니다.

android {
		....
    signingConfigs {
        release {
            keyAlias 'ci'
            keyPassword '123456'
            storeFile file('../ci.jks')
            storePassword '123456'
        }
    }
    ....
}

문제의 원인

• 문제의 원인을 찾고 해결하는 모든 과정은 정재현(edge)님께서 수행해 주셨습니다.

실행한 후 터미널을 확인하면 아래 에러 로그를 확인할 수 있습니다.

I/flutter ( 9959): type 'StackParentData' is not a subtype of type 'FlexParentData' in type cast
I/flutter ( 9959): #0      Flexible.applyParentData (package:flutter/src/widgets/basic.dart:5219)
I/flutter ( 9959): #1      RenderObjectElement._updateParentData (package:flutter/src/widgets/framework.dart:6553)
I/flutter ( 9959): #2      RenderObjectElement.attachRenderObject (package:flutter/src/widgets/framework.dart:6594)
I/flutter ( 9959): #3      RenderObjectElement.mount (package:flutter/src/widgets/framework.dart:6458)
I/flutter ( 9959): #4      MultiChildRenderObjectElement.mount (package:flutter/src/widgets/framework.dart:6900)
I/flutter ( 9959): #5      Element.inflateWidget (package:flutter/src/widgets/framework.dart:4335)

결론은 Expanded widget을 잘못써서 생기는 에러였습니다. Stack Overflow에서 검색해보면, 아래 답변을 찾을 수 있습니다.

Expanded cannot be used inside a Stack.
You should use Expanded only within a Column, Row or Flex

https://stackoverflow.com/a/56766847/9341454

문제가 되었던 코드는 lib/pages/planner_page.dart 파일에서 OTLLayout의 body로 Expanded 위젯을 지정한 부분입니다.

class _PlannerPageState extends State<PlannerPage> {
  @override
  Widget build(BuildContext context) {
    final planners = Provider.of<PlannerModel>(context);

    if (!planners.isLoaded) {
      return OTLLayout(
        body: Expanded(
	        ....

왜냐하면 OTLLayout 위젯을 뜯어보면 body를 Stack이 감싸고 있거든요.

class _OTLLayoutState extends State<OTLLayout> {
  final bool canPopRightLeft = OTLNavigator.canPopRightLeft;
  final bool canPopDownUp = OTLNavigator.canPopDownUp;

  @override
  Widget build(BuildContext context) {
    final ScaffoldState? scaffold = Scaffold.maybeOf(context);
    final bool hasDrawer = scaffold?.hasDrawer ?? false;
    final bool hasEndDrawer = scaffold?.hasEndDrawer ?? false;

    return Stack(
      fit: StackFit.expand,
      alignment: Alignment.topCenter,
      children: [
        Positioned.fill(
          top: widget.extendBodyBehindAppBar ? 0 : kToolbarHeight,
          child: widget.body,
        ),
        ....

재현님께서 원인 파악 후, 로딩 화면을 불러오는 로직과 위젯을 모두 수정하여 문제를 해결해 주셨습니다.

Wrap-up

개발자들을 놀라게 하는 이벤트 중 하나는 분명, 내 개발환경에서는 잘 돌아갔던 코드가 프로덕션/릴리즈 환경에서 작동하지 않는 상황일 것입니다. 우리는 이럴 때 두가지를 집중적으로 바라보아야 합니다.

• 릴리즈/프로덕션으로 배포하는 과정상의 문제인지? 코드 자체의 문제인지?

• 내 개발환경에서 릴리즈/프로덕션 설정을 모방하여 테스트해볼 수 있는지?

다행히 이번 상황에서는 Firebase Crashlytics를 통해 코드 관련 문제임을 빠르게 파악하고 담당자에게 전파할 수 있었던 것 같습니다.

감사합니다!

Subscribe now