조편성 TechSpec과 테스트케이스

요약 (Summary)

가장 먼저 테크 스펙을 세 줄 내외로 정리합니다. 테크 스펙의 제안 전체에 대해 누가/무엇을/언제/어디서/왜를 간략하면서도 명확하게 적습니다.

• 조편성이란
  • 누가/무엇을 : 조편성이란 월부에서 함께 수강하는 사람들끼리 부동산 학습을 위해 짝 지어준 스터디 그룹을 말합니다. 조편성 프로그램은 이를 위해, 어드민 관리자 (CM분들)가 조 편성을 하기 위해, 설문 등록부터 조장/운영진 선발, 조원 배치, 노출확정 등의 기능을 제공합니다.
  • 언제/어디서 : 정규강의 신청과 설문 응답이 마감된 이후, 어드민 페이지에서 진행합니다.
  • 왜 : 조편성 작업시간을 단축시키기 위함입니다.

배경 (Background)

프로젝트의 Context를 적습니다. 왜 이 기능을 만드는지, 동기는 무엇인지, 어떤 사용자 문제를 해결하려 하는지, 이전에 이런 시도가 있었는지, 있었다면 해결이 되었는지 등을 포함합니다.

• 기존에도 조원 배치 기능이 존재했습니다. 비즈니스 로직이 프론트엔드에 있었는데, 로직이 정상 동작하지 않았을 뿐 아니라, 속도 측면에서도 너무 느렸습니다. 따라서 CM 분들은 프로그램 사용 없이, 조편성 작업을 수동으로 진행하였습니다.
• CM 분들이 수동으로 2000-3000명 사이의 조편성 인원을 조 편성하는 데, 8시간 정도 필요했습니다. 서버 단에서 조원배치 알고리즘을 통해, 조원 배치 작업을 자동화하여 CM 분들의 조 편성 작업시간을 2시간으로 줄일 수 있었습니다.

목표 (Goals)

예상 결과들을 Bullet Point 형태로 나열합니다. 이 목표들과 측정 가능한 임팩트들을 이용해 추후 이 프로젝트의 성공 여부를 평가합니다.

• 운영진을 등록 할 수 있다.

• 조장 선정 결과를 엑셀 파일로 업로드 할 수 있다.

• 조원을 자동으로 배치한다.

• 데이터 새로고침 : 환불 완료된 인원은 조 편성 관리에서 제외한다.
  • 월부에서는 환불 대기 기간이 존재합니다. 환불을 신청하더라도 CX팀의 환불 방어를 통해 전체 환불 인원의 10%는 환불을 취소합니다. 따라서 환불 대기자는 일단 명단에 함께 노출되어야 합니다. 단, 환불이 완료된 인원은 목록에서 제외해야 합니다. 이를 시스템에서 자동으로 처리하기 어려운 부분이 있어, 별도 버튼으로 만들어, 사용자가 처리할 수 있도록 처리하였습니다.

• 조원을 수동으로 배치 할 수 있다.

• 관리자는 운영진 선정 결과, 조장 선정 결과, 조원 배치 결과를 확인한 후 최종 확정할 수 있다.

 

• 조편성이 완료된 최종 데이터를 엑셀 파일로 다운로드 받을 수 있다.

• 커뮤니티 우측 영역에 ‘수강중인 조원들’ 명단에 관리자가 편성한 조 정보가 반영된다.

목표가 아닌 것 (Non-Goals)

목표가 아닌 것은 프로젝트에 연관되어 있으나 의도적으로 하지 않거나 해결하지 않으려 하는 것을 말합니다. 목표가 아닌 것을 정하면 프로젝트 범위를 더 명확하게 할 수 있고, 이 기능도 붙이자, 저 기능도 붙이자 하는 것을 막을 수 있습니다. 목표처럼 목표가 아닌 것도 Bullet Point 형태로 읽기 쉽게 적어 독자가 직관적으로 이해할 수 있도록 합니다. 목표가 아닌 것을 세부적으로 잘 적으면 프로젝트 범위를 넓게 보려 하는 독자들의 폭주를 막을 수 있습니다.

• 설문 등록 및 응답 기능은 이미 시스템화 되어 있습니다. 조편성 시스템에서는 설문은 설문을 조회하여, 응답자의 희망 지역을 조회해오는 등의 기능만 제공합니다.
• 조장 선발은 시스템에서 자동화하지 않습니다. 현재 설문 답변 내용에 존재하는 강의 수강 내역, 지원 동기, 평판 등을 통해 조장을 선발합니다. 지원 동기와 같은 항목은 정성적 평가가 필요하며, 평판은 시스템에서 알 수 없기 때문에 담당자(커뮤니티 매니저)가 담당합니다.

⭐️⭐️ 계획 (Plan)

어떻게 기술적, 엔지니어링적으로 접근할지 상세히 묘사합니다. 만약 어떤 부분을 어떻게 할지 확실히 결정하지 못한 상태라면 어떤 것들을 고려하고 있는지 목록화해서 적습니다. 그렇게 하면 이 문서 리뷰어들이 올바른 결정을 내리도록 도움을 주게 됩니다.

조편성 전체 시나리오 요약

월부에서는 매달마다 정규강의가 오픈한다. 오늘 오픈 상품은 내집마련기초반이다. 관리자는 사전에 (조편성 옵션을 추가하여) 전시상품 등록을 한다. 보통 내집마련기초반에는 1000명-2000명의 신청자가 있다. 신청자들은 관리자가 미리 등록한 설문에 응답하여, 조편성 된다. 조편성은 자신이 희망하는 임장 지역에 따라 편성된다. 본인들이 원하는 지역을 1, 2지망까지 선택하게 된다. 같은 지역을 선택한 사람들끼리 설정한 인원(최소 7명, 최대 10명)으로 조가 구성되며, 조는 조장과 조원로 구성되며, 내부 운영을 위해 등록된 운영진이 있다. 조장이 없으면 조는 만들어질 수 없으며, 조에 조장은 1명이다. 조장은 CM(월부 커뮤니티 매니저)분들이 지원동기와 수강이력 등의 정보를 보고 정해진다. 조장은 해당 지역의 신청 인원에 알맞게 선발한다. 조장의 수가 적절하지 않으면, 비유효 모달이 뜬다. 적정한 조장의 수가 뽑히면, 조원배치 버튼을 눌러, 자동화된 조 선발 로직을 활용하여, 조편성한다. 로직에서 처리 안된 인원들은 UI 상으로 체크박스를 클릭하여, 이미 편성된 조로 보내주거나, 한 조로 묶어 조편성을 완료해줍니다. 미편성 인원이 한 명도 없으면, 노출확정을 누릅니다. 노출확정을 누르면, 커뮤니티 홈에서 함께 수강중인 조원들이 노출됩니다.

전체 데이터 구조

• 테이블에 대한 세부 내용은 DB에서 확인 가능합니다. 주요 필드와 관계만 담았습니다.

데이터 구조 설명

1. 전시상품과 조편성 옵션(1:N)
   1. 조편성 대상 전시상품은 GROUP_YN = 'Y' 인 상품입니다.
   2. 조편성 옵션은 tb_display_option.OPTION_TYPE_CD = 'GROUP' 인 옵션입니다.
   3. 상품을 결제한 유저는 유저 학습 정보 tb_user_study가 생성됩니다.
   4. 조 편성 대상자 정보가 생성되는 시점은 유저가 조편성 대상 전시상품의 조편성 옵션을 선택하여, 결제 한 때 입니다.
   5. tb_user_group_details와 tb_user_study 간의 관계는 1:1입니다.
2. 조와 조장 (1:1), 조와 조원/운영진 (1:N)
   1. 조와 조장은 1:1 관계입니다. 개념적으로 조장이 없이, 조만 생성될 순 없습니다.
   2. 조 편성 대상자 정보는 tb_user_group_details 에 저장됩니다.
   3. 어떤 조에 편성됐는지 확인하려면 tb_user_group_details 의 GROUP_SEQ를 확인하면 됩니다.
   4. 조 정보는 tb_user_group 데이터에 저장됩니다. 생성되는 시점은 조장이 등록될 때 입니다.
   5. 조장과 조원, 운영진은 tb_user_group_details의 type 값으로 구분합니다. [LEADER, MEMBER, MANAGER]
3. 설문과 질문(1:N), 질문과 객관식 답안(1:N)
   1. 조편성 대상자 중 설문에 응답하지 않은 유저(user_survey_answer 값이 없는 유저)는 조원배치 대상이 될 수 없습니다. 조편성은 설문 응답을 기반으로 하기 때문입니다.
   2. 조편성 대상이 되는 질문은 각 설문의 첫번째 객관식 항목입니다. (당시 개발 시간이 빠듯하여, CM 분들과 협의 하에 그렇게 처리해뒀습니다. 별도로 특수 항목으로 빼고 question type으로 구분할 수도 있어 보입니다.)
4. 전시상품과 지역별 최대 인원 정보 (1:N), 조와 객관식 답안 (1:N)
   1. 복수지역 조편성 대상에는 조에는 최종 지역이 노출됩니다. 최종지역이란 1, 2 지망 중 조편성 기준이 되며, 실제 조원배치가 된 지역을 말합니다. tb_user_group 테이블의 survey_question_selection_id 필드입니다.
   2. 복수지역 조편성 대상 조편성에는 survey_question_selections_capacities 테이블이 따로 존재합니다. UI 상에서 지역 별 최대 인원으로 노출되는 데이터입니다. 조편성 희망권역이 2개 이상인 경우 필요한 정보입니다.

조원배치 핵심 알고리즘 1 [조 인원을 균등하게 나누는 로직]

Use Case Name	지역 별로 조장 인원에 맞게, 조 인원을 균등하게 나눈다.
목표	지역 별로 조장 인원에 맞게, 조 인원을 균등하게 나눠져야 한다.
Primary Actor	어드민 관리자
Secondary Actor	N/A
Pre-condition	유저들은 자신의 1지망 임장 지역에 대한 질문에 설문 응답을 완료해야 한다.
Basic Flow	해당 지역을 선택한 조장 수와 전체 인원을 조회한다. ex) 전주 지역의 조장은 9명이고 조원은 72명이다. 총원은 81명. ex) 인천 지역의 조장은 4명이고 조원은 27명이다. 총원은 31명. 계산된 조 인원만큼 전체 인원에서 조원을 조회하여, 같은 조로 편성한다. 조장은 고유한 조 번호를 갖고 있는데, 조장의 번호를 조원들이 받는다. 같은 방식으로 다른 조에 필요한 인원을 구한다. 2000명에서 3000명이 신청하면 대략 200-300개 조가 존재합니다. 해당 조를 확정 상태로 변경합니다.
Exceptional Flow	(1-a) 선택된 지역의 조장의 인원이 0명 일 수는 없다. (1-b) 선택된 지역의 조장의 인원이 0명 일 수는 없다. (1-c) 선택된 지역의 전체 인원이 7명 이하 일 수 없다. (2-a) 선택된 지역의 전체 인원이 11명 이상 13명 이하 일 수 없다. (엣지케이스) 조장이 1명일 경우, 10명을 초과하고 조장이 2명일 경우, 각 조의 인원이 7명 이하가 되기 때문. (3-a) 주어진 범위 안의 조장 인원이 선별이 되어야 한다. 첫번째 81명인 경우, 최소 조장이 9명이고 최대 조장이 11명이다. 두번째 31명인 경우, 조장이 4명이어야 한다.
Post-condition	조 편성이 완료된 조들은 확정 처리가 되어야 한다.
Special Requirements	N/A

조원배치 핵심 알고리즘 2 [1, 2지망을 고려한 지역별 조장, 조원 인원 선별]

Use Case Name	1, 2지망을 고려하여 조원 배치한다.
목표	희망지역이 2개인 경우, 1지망을 우선 고려하되 지역별 최대 인원만큼 편성하고 남은 인원들은 2지망을 기준으로 편성한다.
Primary Actor	어드민 관리자
Secondary Actor	N/A
Pre-condition	유저들은 자신의 1, 2 지망 임장 지역에 대한 질문에 설문 응답을 완료해야 한다. 지역별 최대 편성 인원이 선정 되어야 한다.
Basic Flow	지역별 최대 편성 인원을 조회한다. 지역별 조장, 조원의 1, 2지망 응답을 조회한다. 해당 지역에 필요한 조장, 조원 수를 계산한다. 해당 지역 희망 인원 수가 최대 편성 인원을 초과하면, 최대 편성 인원을 고려하여 조장, 조원 수를 계산한다. 초과하지 않으면, 신청한 인원 수를 기반으로 해당 지역에 필요한 조장, 조원 수를 계산한다. 1지망 신청자 수보다 최대 편성 인원이 크면, 1지망 인원 안에서 선별을 완료한다. 1지망 신청자 수가 최대 편성 인원을 초과하지 않으면, 2지망 인원을 추가로 받는다. 지역별 최소 조장 수보다 1지망 조장 수가 작으면, 최대 조장 범위를 초과하지 않는 선에서 2지망 조장을 추가로 선별한다. 지역별 최소 조장 수보다 1지망 조원 수가 작으면, 최대 조원 범위를 초과하지 않는 선에서 2지망 조원을 추가로 선별한다. 짝 지어진대로 조를 편성한다. 1, 2지망에도 들지 못하는 경우에는 미편성 인원으로 편성된다.
Exceptional Flow	(1-a) 지역별 최대 편성 인원이 0일 수 없다. (2-a) 선택된 지역의 조장/조원의 인원이 0명 일 수는 없다. (3-a) 선택된 지역의 전체 인원이 7명 이하 일 수 없다. (5-a) 이미 한 조에 편성된 인원이 다른 조로 편성될 수 없다. (6-a) 선택된 지역의 전체 인원이 11명 이상 13명 이하 일 수 없다. 조장이 1명일 경우, 10명을 초과하고 조장이 2명일 경우, 각 조의 인원이 7명 이하가 되기 때문. (6-a) 주어진 범위 안의 조장 인원이 선별이 되어야 한다. 첫번째 81명인 경우, 최소 조장이 9명이고 최대 조장이 11명이다. 두번째 31명인 경우, 조장이 4명이어야 한다.
Post-condition	조 편성이 완료된 조들은 확정 처리가 되어야 한다.
Special Requirements	N/A

이외 고려 사항들 (Other Considerations)

고려했었으나 하지 않기로 결정된 사항들을 적습니다. 이렇게 함으로써 이전에 논의되었던 주제가 다시 나오지 않도록 할 수 있고, 이미 논의되었던 내용이더라도 리뷰어들이 다시 살펴볼 수 있습니다.

마일스톤 (Milestones)

프로젝트를 제 시간에 맞추기 위해 테크 스펙의 내용을 바탕으로 추정한 마일스톤을 공유합니다. 실험 계획, 배포 날짜를 포함해 최대한 자세히 적습니다.

• 1차 배포날짜 : 4월 초 (기본 로직 개발)
• 2차 배포날짜 : 4월 말 (리팩토링 및 설계 일부 변경)
• 3차 배포날짜 : 8월 말 (복수지역 대상 조편성 고도화)

 

조편성 테스트케이스

번호	전체 프로세스					검증조건
1	관리자 전시상품 등록	조편성 전시상품으로 지정	조편성 옵션 포함하여 등록			전시상품이 생성된다.
2			조편성 옵션 미포함하여 등록			전시상품이 생성된다.
3	관리자 전시상품 수정	조편성 전시상품으로 지정	조편성 옵션 포함하여 등록			전시상품이 수정된다.
4			조편성 옵션 미포함하여 등록			전시상품이 수정된다.
5	관리자 설문 등록	단일 지역 설문 등록	질문을 등록하지 않는다.			설문이 생성된다.
6			전시상품을 등록하지 않는다.			설문이 생성된다. 전시상품과 설문 매핑이 생성되지 않는다.
7			전시상품을 등록한다.	질문을 등록하지 않는다.		설문이 생성된다. 전시상품과 설문 매핑이 생성된다.
8				질문을 등록한다.	첫번째 질문으로 조편성 희망지역 질문을 등록하지 않는다.	설문과 질문이 생성된다. 전시상품과 설문 매핑이 생성된다.
9					첫번째 질문으로 조편성 희망지역 질문을 등록한다.	설문과 질문이 생성된다. 전시상품과 설문 매핑이 생성된다. 질문 답변 갯수가 1개여야 한다.
10		복수 지역 설문 등록	질문을 등록하지 않는다.
11			전시상품을 등록하지 않는다.
12			전시상품을 등록한다.	질문을 등록하지 않는다.
13				질문을 등록한다.	첫번째 질문으로 조편성 희망지역 질문을 등록하지 않는다.	설문이 생성된다. 전시상품과 설문 매핑이 생성된다.
14					첫번째 질문으로 조편성 희망지역 질문을 등록한다.	조편성 질문이 된다. 질문 답변 갯수가 2개여야 한다. 지역별 최대 인원 정보가 등록되어야 한다.
15	고객 조편성 상품 구매	강의 Only 상품 구매				조원 정보가 생성되지 않는다.
16		온라인 조편성 상품 구매				조원 정보가 정상적으로 생성된다.
17		오프라인 조편성 상품 구매				조원 정보가 정상적으로 생성된다.
18			구매 후 환불	온라인 조편성 고객 설문 답변	기간내 환불 요청	환불 대기 상태로 변경되어야 한다.
19					기간 이후 환불 요청	환불 처리가 되지 않는다.
20				오프라인 조편성 고객 설문 답변	기간내 환불 요청	환불 대기 상태로 변경되어야 한다.
21					기간 이후 환불 요청	환불 처리가 되지 않는다.
22	고객 조편성 설문 답변	단일지역 고객 답변				정상적으로 답변 처리된다.
23		2개지역 고객 답변				정상적으로 답변 처리된다.
24	운영진 선발	운영진으로 선발한다.	액셀 업로드를 통해 등록한다.			이전 운영진 선택 내역이 초기화 된다. 운영진으로 선발 처리 된다. 해당 상품을 구매하지 않은 유저는 운영진으로 선발될 수 없다.
25			조장 모달에서 검색해서 등록한다.			운영진으로 선발 처리 된다. 해당 상품을 구매하지 않은 유저는 운영진으로 선발될 수 없다.
26	관리자 조장 선발	조장으로 선발한다.	액셀 업로드를 통해 등록한다.			이전 조장 선택 내역이 초기화 된다. 조장으로 선발 처리 된다. 설문에 응답하지 않은 유저는 조장으로 선발 될 수 없다. 이미 조가 확정된 경우에는 변경 불가능하다.
27			조장 모달에서 검색해서 등록한다.			조장으로 선발 처리 된다. 설문에 응답하지 않은 유저는 조장으로 선발 될 수 없다.
28	관리자 조원 배치	단일 지역 조원 배치	단일지역 0~6명 신청			미편성 인원으로 이동된다.
29			단일지역 11명~13명 신청			미편성 인원으로 이동된다.
30			단일지역 14명 이상 신청	조장 희망자가 필요 인원보다 적은 경우		비유효 모달이 뜬다.
31				조장 희망자가 필요 인원보다 큰 경우		비유효 모달이 뜬다.
32				조장 희망자가 필요 인원만큼 선발된 경우		조원배치가 된다.
33		복수 지역 조원 배치	지역별 최대 인원 정보가 설정되지 않은 경우			지역별 최대 인원을 설정하라는 모달이 뜬다.
34			지역별 최대 인원 정보가 설정된 경우	복수지역 0~6명 신청		미편성 인원으로 이동된다.
35				복수지역 11명~13명 신청		미편성 인원으로 이동된다.
36				복수지역 14명 이상 신청	조장 희망자가 필요 인원보다 적은 경우	비유효 모달이 뜬다.
37					조장 희망자가 필요 인원보다 큰 경우	비유효 모달이 뜬다.
38					조장 희망자가 필요 인원만큼 선발된 경우	정상적으로 조원배치 된다.
39	관리자 데이터 새로고침	환불 완료자가 존재하지 않는 경우
40		환불 완료자가 존재하는 경우	조에 이미 편성 안된 경우
41			조에 이미 편성된 경우	환불자가 조원인 경우	환불자가 빠져도 조 인원이 7명 이상인 경우
42					환불자가 빠지면 조 인원이 7명 이하인 경우	조 확정 취소되고 조 인원은 미편성 인원으로 변경된다.
43				환불자가 조장인 경우		조 확정 취소되고 조 인원은 미편성 인원으로 변경된다.
44	관리자 노출 확정	미편성 인원이 남아 있는 경우
45		미편성 인원이 남아 있지 않는 경우	함께 수강 중인 조원들이 조회된다.			노출 확정 처리가 된다. 함께 수강 중인 조원들이 조회된다.