사내 서비스 통합 포탈

진도는 '어디까지 갔나'가 아니라 '어디를 지났나'로 센다

온라인 교육의 유일한 자산은 수강 기록입니다. 처음에는 최대 재생 위치만 저장했는데, 그러면 스크롤바를 맨 뒤로 한 번 끄는 것만으로 이수가 끝나 버립니다. 그래서 영상을 10초 단위 칸으로 쪼개고, 화면이 5초마다 보내오는 위치로 지나간 칸만 채우도록 바꿨습니다.

직전 위치와의 차이가 30초 이내면 이어 본 것으로 인정해 1.5배·2배속 시청은 정상적으로 기록되고, 차이가 크면 건너뛴 것으로 보고 지금 칸 하나만 채웁니다 - 맨 뒤로 끌어도 중간이 비어 이수 처리되지 않습니다. 영상은 유튜브가 재생하고 이 앱은 위치만 받아 적기 때문에 서버 부하도 거의 없습니다.

반려 사유를 적어 보내지 않고, 고칠 프롬프트를 만들어 준다

앱을 만들어 보내는 쪽이 대부분 비개발 부서입니다. 그래서 검사에서 걸렸을 때 "규칙 14 위반 - 바깥 포트 금지"라고 적어 보내면 거기서 멈춥니다. 받는 사람이 모르는 건 무엇이 틀렸는지가 아니라, 쓰던 AI 에 무엇을 말해야 하는지입니다. 사유만 적어 보내면 결국 담당자에게 다시 물어보게 되고, 셀프서비스로 만든 의미가 없어집니다.

그래서 검사 문구 27가지마다 왜 막는지 · 어디를 고치는지 · 붙여넣을 코드를 붙여 두고, 걸린 항목만 모아 한 덩어리 글로 만들어 줍니다. 그대로 복사해 쓰던 AI 에 붙여넣으면 됩니다. 도커 설정처럼 큰 항목이 걸리면 그 아래 딸린 작은 항목들은 접습니다 - 같은 파일을 두 번 고치라고 하면 사람이 헷갈립니다.

포탈이 세지 않고, 앱에게 물어본다

첫 화면 앱 카드에 "결재 3건" 같은 숫자를 띄우려면 포탈이 그 앱의 일을 알아야 합니다. 그 방식은 앱이 하나 늘 때마다 포탈을 한 번 더 고치게 만듭니다 - 앱이 계속 추가되는 것이 이 플랫폼의 전제인데, 추가할 때마다 관문을 건드려야 한다면 구조가 잘못된 것입니다.

그래서 포탈은 개수를 세지 않고 앱마다 GET api/badge 를 한 번씩 물어봅니다. 앱은 {"count": 2, "label": "검토 요청 2건"} 만 내놓으면 되고, 만들지 않은 앱은 404 가 돌아와 조용히 넘어갑니다. 덕분에 기존 앱을 한 줄도 고치지 않고 붙었고, 앞으로 만들 앱은 규칙 문서의 한 문단만 보면 됩니다.

권한은 토큰이 아니라 DB를 본다

JWT 안의 값만 믿으면 관리자 권한을 회수해도 토큰이 만료되는 시간 동안 예전 권한이 그대로 살아 있습니다 - 화면에서 메뉴가 안 사라지는 정도가 아니라 관리자 API가 계속 열려 있다는 뜻입니다. 그래서 요청마다 DB를 한 번 다시 조회하도록 했습니다. SQLite 조회 하나라 이 규모에서는 체감되는 지연이 없습니다.

흔한 컨테이너 이름을 쓰지 않는다 (실제로 사고가 날 뻔했다)

컨테이너 이름이 portal · proxy · it-asset처럼 흔했습니다. docker compose는 이름을 안 적으면 폴더 이름으로 프로젝트를 정하기 때문에, 받는 쪽 PC에 같은 이름의 폴더가 있으면 남의 컨테이너를 이 프로젝트 것으로 착각해 명령을 그 안에서 실행할 수 있습니다. 실제로 그런 일이 있었고, 그 앱에 해당 파일이 없어서 실패로 끝났을 뿐 있었다면 남의 데이터가 덮였을 상황이었습니다.

이후 모든 컨테이너·네트워크 이름을 프로젝트 전용 접두사로 못 박고, 자료를 넣는 명령도 이름 하나만 정확히 지정하는 방식으로 바꿔 같은 사고가 구조적으로 재발하지 않도록 했습니다.