22장 접근 역할 체계

직원이 무엇을 할 수 있는지는 조직과 워크스페이스에 공통인 세 역할(관리자·편집자·조회자)로 정합니다. 조직 계정을 최종 통제하는 책임은 역할이 아니라 「조직 소유」라는 관계로 정합니다. 이 장은 그렇게 정한 이유와 검토한 대안을 설명합니다. 규칙 전체는 공개 표준이 정합니다.

왜 필요한가

2026-10-03 KST에 제품 저장소 17곳의 역할 코드를 조사했습니다. 네 가지 문제가 나왔습니다.

1. 같은 말이 다른 뜻이었습니다. manager는 어떤 제품에서는 중간 업무 등급, 다른 제품에서는 구성원을 관리하는 등급, 또 다른 제품에서는 아무 권한도 주지 않는 값이었습니다. owner는 조직 소유자이면서 CRM 레코드의 담당, 부동산의 소유자이기도 했습니다. 「최고관리자」는 소유자 아래 등급인데 「최고」라고 불렸습니다.
2. 조직 역할이 워크스페이스에 미치는지가 제품마다 달랐습니다. 어떤 제품은 상속했고 어떤 제품은 하지 않았습니다.
3. 역할과 다른 개념이 섞여 있었습니다. 본사 직원인지를 사람별 플래그로 판정하거나, 파트너 직원 역할을 따로 두는 식이었습니다.
4. 화면에서 숨기기만 하고 서버 판정이 없거나, 역할 이름을 곳곳에서 직접 비교했습니다. Leyve는 같은 등급 계산을 SQL·서버 함수·화면에 세 번 썼습니다.

같은 「관리자」가 제품마다 다른 일을 하면 사용자가 헷갈리고, 에이전트는 어떤 비교가 맞는지 알 수 없습니다.

모델

세 역할

값	라벨	할 수 있는 일
admin	관리자	사람·역할·설정·워크스페이스 관리와 모든 업무
editor	편집자	업무 데이터 생성·편집·삭제(복구할 수 있는 삭제). 사람·역할·설정은 바꾸지 않음
viewer	조회자	업무 데이터 조회. 민감한 정보는 제품이 가림

위 등급은 아래 등급의 권한을 모두 가집니다. 조직과 워크스페이스는 같은 세 값을 씁니다.

조직 소유는 관계입니다

조직 소유자(organization.owner)는 계약 체결·해지, 청구 역할의 부여·회수, 조직 소유자 지정·회수·이전, 조직 종료를 맡습니다.

• 조직 소유자는 조직 관리자 역할을 가져야 합니다. 그래서 다른 관리자가 소유자의 관리자 역할을 낮추지 못합니다.
• 유효한 조직 소유자를 언제나 한 명 이상 둡니다. 계정과 소유 지정이 활성이고, 검증된 이메일과 이메일이 아닌 2차 인증을 갖춘 사람만 셉니다. 서버는 그 수를 0으로 만드는 변경을 모두 막습니다. 예외는 계정 탈취 같은 보안 사고에 대응해 운영사가 계정을 잠그는 경우뿐입니다.
• 소유 동작은 이메일이 아닌 2차 인증으로 재인증한 뒤에만 허용합니다.

사용자·조직·현장과 계약의 관계

사용자는 로그인하는 주체이고, 조직은 구성원과 현장을 관리하는 운영 범위입니다. 계약은 조직이 관리하지만 법적 당사자는 계약에 명시적으로 연결한 개인·법인·법인 아닌 단체입니다. 별도 빌링 계정 화면은 조직의 계약·결제로 모으되 기존 계약·청구 식별자와 당시의 당사자 기록은 유지합니다. 사업자등록은 당사자의 세무 증빙으로 따로 둡니다.

이메일·조직·현장 로그인은 유지합니다. 로그인 방법이 소유자를 만들지는 않습니다. 조직 ID도 동일 주체 연결과 활성 조직 소유, 최근 비이메일 재인증이 확인되어야 소유 명령을 할 수 있습니다. 현장 로그인은 계속 그 현장 하나에 묶입니다.

상속과 비공개 워크스페이스

• 조직 역할은 그 조직의 공개 워크스페이스에 같은 값으로 적용됩니다. 직접 역할은 상속 역할보다 높을 때만 둡니다.
• 비공개 워크스페이스에는 상속이 없습니다. 직접 역할이 없는 사람에게는 없는 워크스페이스처럼 보입니다. 조직 관리자는 사유를 남기고 참여할 수 있고, 그 참여는 감사 기록에 남습니다.
• 워크스페이스 관리자의 부여·회수는 조직 관리자만 합니다. 같은 워크스페이스의 관리자끼리 서로 낮추지 못하므로 조직이 지정한 현장 책임자가 유지됩니다.

권한 키와 서버 판정

기능 코드는 role === 'admin'처럼 역할 이름을 비교하지 않습니다. can(principal, key, target)처럼 권한 키로 묻습니다. 권한 키는 {domain}.{resource}.{action} 형식입니다. 예: crm.lead.update, access.role.grant. 역할에서 권한 키로 가는 표는 제품마다 한 곳에 두고, 서버 판정이 정본입니다. 화면은 같은 표로 숨김과 비활성만 보여 줍니다. 판정의 기본값은 거부입니다.

역할이 아닌 것도 정했습니다. 소속, 로그인 방법, 접점 유형, 조직 자격(운영사·파트너), 모듈 이용, 담당, 직위·직책, 결재선, 입주민·유권자 같은 이용자 관계는 역할 값으로 저장하지 않습니다. 팀장이 곧 관리자는 아닙니다. 본인 근태·휴가·급여명세서는 역할이 아니라 활성 소속으로 허용하므로, 셀프서비스를 쓰게 하려고 모든 직원에게 콘솔 역할을 줄 필요가 없습니다.

행위 주체

업무 기록에 「누가 했는가」를 남길 때는 역할 라벨이 아니라 「{동사} 주체」를 씁니다. 생성 주체, 편집 주체, 승인 주체처럼 씁니다. 필드는 editedAt·editedBy처럼 {동사}edAt·{동사}edBy이고, {동사}edBy는 주체 유형(사람·조직·소프트웨어·알 수 없음)과 식별자를 가진 참조입니다.

상황	기록
AI가 제안하고 사람이 검토·저장	사람이 편집 주체
사람의 요청을 받은 AI가 직접 편집	AI 에이전트가 편집 주체, 요청한 사람은 requestedBy
예약 작업이 자동으로 변경	식별된 예약 작업이 행위 주체

행위 주체로 기록된다고 접근을 얻지는 않습니다. 판정 대상은 인증 주체(principal)입니다. 소프트웨어가 사람의 요청으로 일하면 두 주체를 각각 판정하고 둘 다 가진 권한만 씁니다. 주체를 모르면 「알 수 없음」으로 보이고 「시스템」으로 채우지 않습니다.

청구 추가 역할과 운영사

청구 업무만 맡길 사람을 위해 추가 역할 세 단계를 등록했습니다. billing_viewer(청구 조회자), billing_editor(청구 편집자), billing_admin(청구 관리자)입니다. 업무 데이터 접근은 주지 않고, 조직 소유자만 부여합니다.

슈퍼 관리자는 없습니다. Leysys 본사는 운영사 자격을 가진 조직이고, 본사 직원은 그 조직에서 같은 세 역할을 받습니다. 본사 직원이 고객 조직 안의 데이터를 볼 때는 고객이 승인한 지원 접근을 씁니다. 요청은 72시간 안에 응답이 없으면 만료되고, 접근은 기본 24시간·최대 7일이며 지원 사건이 닫히면 끝납니다. 모든 동작은 고객 조직의 감사 기록에 「Leysys 지원」 소속으로 남습니다.

유효 조직 소유자가 0명이 되면 운영사가 소유 복구 절차를 엽니다. 사고 대응 잠금으로 0명이 됐으면 기존 소유자가 본인 확인으로 복귀하는 길을 먼저 엽니다. 새 소유자를 지정할 때는 계약 당사자가 개인·법인·법인 아닌 단체인지에 맞는 본인·대표·위임 증빙과 기존 계약·결제·관리 관계를 확인하고, 7일 동안 이의를 받습니다. 사업자등록이 있는 경우 그 증빙도 확인하지만 비사업 개인에게 요구하지는 않습니다. 개인 진술이나 신분 확인만으로는 지정하지 않습니다.

왜 이렇게 정했는가

오너가 2026-10-03 KST와 2026-10-04 KST에 여덟 가지 질문에 답했습니다. 모두 권장안으로 정했고, 검토한 다른 선택지도 기록에 남겼습니다. 대표적인 것은 다음과 같습니다.

질문	정한 것	검토한 대안과 버린 이유
업무 등급의 이름	editor · 편집자	member(구성원 여부와 섞임), manager(이미 세 가지 뜻), staff(대상 이름), writer(기록의 작성자와 겹침)
소유의 위치	사다리 밖의 조직 관계	사다리 맨 위 역할: 조직과 워크스페이스의 값 집합이 달라지고, 최소 인원 같은 소유 제약이 역할 규칙에 섞임
워크스페이스 접근	상속 + 비공개 워크스페이스	모든 워크스페이스 명시 참여, 상속만 두고 비공개 없음
행위 주체 라벨	「{동사} 주체」	「{동사}한 사람」(소프트웨어 주체를 담지 못함), 「편집자」(역할과 겹침)
청구 추가 역할	세 단계	billing_editor 하나: 다시 보니 요금제·모듈 변경은 되돌릴 수 있는 설정이라 관리자 등급의 고유한 일이 됨

외부 공식 문서도 근거로 확인했습니다. 확인한 11개 시스템에서 가장 흔한 형태는 「소유자 > 관리자 > 쓰기 > 조회」였습니다. Kubernetes의 edit가 편집자와 같은 뜻이고, WordPress.com은 소유를 Administrator 역할과 따로 둡니다. NIST SP 800-63B-4는 이메일을 대역 외 인증에 쓰지 말라고 하므로, 소유 동작의 재인증에서 이메일을 뺐습니다.

경계와 예외

• 이 장과 공개 표준은 문서입니다. 각 제품은 저장소별 PR로 채택하며, 채택 전의 차이는 차단 사유가 아니라 내부 경고(alert)입니다.
• 제품은 자기 업무 권한 키를 세 등급에 배치하고 더 엄격한 규칙만 더할 수 있습니다.
• 입주민·조합원·유권자 같은 포털 이용자는 직원 역할 체계 밖에 둡니다.
• docs:read 같은 콜론 표기는 유료 이용권 범위 문자열이며 사람 권한 키와 다른 개념입니다.
• 403 화면·역할 배지·문구 같은 접근 UX는 leysys-design이, 제품별 권한 표는 제품 저장소가 소유합니다.

정리

• 역할은 조직·워크스페이스 공통의 admin > editor > viewer 세 단계입니다.
• 조직 소유는 역할이 아닌 관계이고, 유효 소유자를 언제나 한 명 이상 둡니다.
• 기능은 역할 이름이 아니라 {domain}.{resource}.{action} 권한 키로 판정하고, 서버가 정본입니다.
• 행위 주체는 「{동사} 주체」로 쓰고, 기록된다는 사실이 접근을 만들지 않습니다.
• 슈퍼 관리자는 없고, 운영사의 고객 데이터 접근은 고객이 승인한 기한 있는 예외입니다.

정본

• 접근 역할 체계 — 역할, 조직 소유, 판정, 부여 규칙, 화면 표현, 식별자 전체
• 사용자·조직·현장과 계약·결제 — 계정 관계, 로그인 범위, 당사자와 이력
• leysys-design docs/decisions/ACCESS-ROLE-SYSTEM-2026-10-03.md — 결정 기록과 오너 결정, 벤치마크
• leysys-design docs/decisions/OPERATOR-SUPPORT-ACCESS-AND-RECOVERY-2026-10-04.md — 지원 접근, 사고 대응 잠금, 소유 복구
• leysys-design 제품 저장소 기본 블록 9항 — 각 제품의 AGENTS.md에 복사하는 역할 체계 요약