모듈 플랫폼 문서 묶음

작성 2026-10-04 · 표준 버전 1 한 번 만든 기능(라이센스 보호·설치기·업데이트 도우미·메신저·SaaS/단독 뼈대 …)을 여러 프로그램이 가져다 쓰고, 어느 프로그램에서든 고친 것을 다시 올려 모두 함께 좋아지게 하려는 문서입니다.

이 폴더의 문서

다른 프로그램에서 쓸 때는 이 폴더(docs/module-platform/)를 그 저장소에 통째로 복사한 뒤, 03 문서 끝의 「Claude 요청문」을 붙여 넣으면 됩니다.

한 장 요약

                      모듈 사이트 (lic.isolo.co.kr 「모듈」 메뉴)
           이름표·버전·사용처·검사 결과·서명을 관리 — 소스는 보관하지 않음
                 ▲ 등록(CI)          │ 발행 알림          ▲ 사용 보고
                 │                   ▼                    │
   원본 저장소 hnbbos/isolo_modules ──► 부품: npm(GitHub Packages)·pip(git 태그)
   (모듈 소스는 여기 한 곳)            서비스: ghcr.io 이미지 + 화면 끼워 넣기
                                       시작 틀: 새 프로그램 만들 때 복사
                 │ 가져오기 / 새 버전 받기 (modctl add · update)
                 ▼
   나혼자워크 · 제로라벨 · 바코드 WMS · PadCAD · 라이센스 서버 …
   (각자 modules.lock.json 에 「어떤 모듈 몇 번」을 적어 둔다)
                 │ 묶음(서명) → 업데이트 도우미
                 ▼
   고객 서버(단독 설치)

기본 모듈 — 모든 프로그램이 같은 것을 씀

라이센스 보호 장치(license-guard) · 설치기(installer) · 업데이트 도우미(update-agent) 는 모듈 사이트에 올라가는 기본 모듈입니다. 단독 설치로 파는 제품은 이 셋이 반드시 들어가야 하고, 빠지면 모듈 사이트가 고객용 묶음을 만들지 않습니다(01 §2.5, 02 §8).

모듈 사이트에 올라가지 않는 것은 두 가지입니다.

• 라이센스 서버 자체(발급·검증·서명 키): 모듈 사이트가 들어 있는 「본부」
• 각 프로그램의 고유 업무 기능

지켜야 할 규칙 3가지

1. 원본은 한 곳. 프로그램 안의 사본은 고치지 않습니다. 고칠 일이 생기면 원본을 고치고 번호를 올립니다.
2. 변경의 크기는 번호로 알립니다. 고침 1.4.1, 기능 추가 1.5.0, 크게 바뀜 2.0.0.
3. 올리기 전에 그 모듈을 쓰는 모든 프로그램에서 검사합니다. 한 곳에서 좋아진 변경이 다른 곳을 망가뜨리면 안 됩니다.

왜 필요한가 — 지금 실제로 생긴 일 (2026-10-04 저장소 확인)

이미 있어서 그대로 쓰는 것

• 라이센스 서버: 제품 표, 연동 키(api_keys), 관리자 인증(requireAdmin/requireRoleAdmin), 감사 기록(auditLicense), Ed25519 서명(vendor-sign.js의 signPayload, canonical), 업데이트 패키지 표, 알림 설정
• 나혼자워크: 패키지 센터(외부 카탈로그 { programs: [...] } 수신), OAuth 2.1 인가 서버·MCP 창구(서비스 모듈의 로그인 연결에 사용)
• 제로라벨: ghcr.io 이미지 배포 경험(docker-compose.watchtower.yml)
• 바코드 WMS: 연결부 방식의 메신저 이식 묶음, Claude용 이식 요청서 형식

권하는 진행 순서