개발 원칙

두 가지 역할

MAJUHAN 개발자는 Flutter·API·MSSQL·Firebase·R2를 다루는 제품 개발자이면서, 외국인 학습자를 가르치는 한국어교육 설계자다. 교육 기능은 코드와 콘텐츠를 분리해 완료할 수 없다.

출시 수준 우선

• 교육과정, 대화, 문법, 어휘, 문항, 배치평가, 게시 상태, 에셋 연결과 학습 결과의 단일 원천은 MSSQL이다.
• 앱 코드에 운영 콘텐츠, 게시 단원 목록, 정답·해설과 문제은행을 상수로 넣지 않는다.
• 문항 선택·순서·정규화·판정은 버전이 기록된 서버 세션이 확정한다.
• 기기에는 서버 버전과 무결성을 확인할 수 있는 캐시와 미전송 작업만 저장한다.
• 공개 동선에는 목업 화면, 가짜 데이터, 빈 버튼을 넣지 않는다.
• 미구현 기능은 동작하는 것처럼 보이게 하지 않고 진입 조건을 명시한다.
• 진도·점수·숙달도·인사이트는 추적 가능한 원천 데이터가 있을 때만 표시한다.
• 첫 구현부터 인증, 저장, 재시도, 중단 재개, 오류와 빈 상태를 함께 설계한다.
• 앱의 DB 접근은 승인된 저장 프로시저를 호출하는 API만 사용한다.

교육 품질 우선

단원은 상황 제시 → 이해 가능한 입력 → 표현·문법 설명 → 안내된 연습 → 응용·전이 순서를 갖는다. 학습자가 혼자 공부하더라도 왜 그렇게 말하는지 이해할 수 있어야 한다.

문항의 오답은 문법적으로 이상한 문장이 아니라, 실제 초급 학습자가 혼동할 만한 오류에서 만든다. 해설은 정답 이유와 오답 차이를 설명한다.

완료 조건

1. 운영 데이터 계약과 인증·권한 경계에 연결한다.
2. 종료·재접속·재로그인·다른 기기의 복구 정책을 확인한다.
3. 로딩·콘텐츠·빈 상태·오프라인·오류·재시도를 구현한다.
4. 다국어 긴 문자열, 접근성, Safe Area와 화면 크기를 검증한다.
5. 단위·위젯·계약·DB 무결성 테스트와 실제 양 플랫폼 화면을 확인한다.
6. 코드와 현황 문서를 같은 변경에서 갱신한다.

부분 구현은 완료라고 부르지 않는다. 구현됨, 제한 운영, 차단됨, 출시 검수 완료를 구분한다.