---
template: policy-doc@1
doc_id: 05-agency-corp
title: 대리점·기업 도메인 — 계약 과금방식 · 조직 부분트리 · 영업 채널 · 고객사 분석 · 기업FC 범위 · 추천 혜택 · 권한명·허용 IP 마스터 · 기업 마이페이지와 대외 리포트 미배포
config: ../_meta/template-config.yaml
last_verified: 4d798f55
policies:
  - id: AGENCY_CONTRACT_BILLING
    status: active-prod
    evidence: [S-constant, S-schema]
    limitations:
      - 계약이 과금방식 축을 갖는다는 것까지가 관측이다. 각 방식이 정산 시점에 어떤 계산으로 이어지는지는 이 문서가 옮기지 않는다
      - 계약이 여러 건일 때 어느 것이 유효한지는 최신 한 건을 고르는 자리로만 관측했다
    anchors:
      - insuniverse-server/apps/api/src/modules/agency/contract/contract.entity.ts:8
      - insuniverse-server/apps/api/src/modules/agency/contract/contract-admin.controller.ts:27
      - insuniverse-server/apps/api/src/modules/agency/agency/agency.entity.ts:6
  - id: ORG_SUBTREE_SCOPE
    status: active-prod
    evidence: [S-contract, S-guard]
    limitations:
      - 부분트리 산출이 경로 문자열 한 열로 이뤄진다는 것까지가 관측이다. 그 경로가 갱신되지 않은 채 조직이 옮겨졌을 때의 동작은 이 문서가 판정하지 않는다
      - 깊이 상한과 순환 방어는 세지 않았다
    anchors:
      - insuniverse-server/apps/api/src/modules/agency/organization/organization.repository.ts:49
      - insuniverse-server/apps/api/src/modules/agency/organization/organization-corp.controller.ts:39
      - insuniverse-server/apps/api/src/modules/agency/organization/organization.entity.ts:18
  - id: SALES_CHANNEL_TREE
    status: active-prod
    evidence: [S-roles, S-schema]
    limitations:
      - 영업 조직이 대리점과 채널 두 단이라는 것까지가 관측이다. 채널 아래 더 내려가는 단이 있는지는 세지 않았다
      - 대표 대리점을 고르는 자리는 열되 그 선택 기준은 이 문서가 판정하지 않는다
    anchors:
      - insuniverse-server/apps/api/src/modules/sales-agency/sales-agency.entity.ts:6
      - insuniverse-server/apps/api/src/modules/sales-agency/channel/sales-agency-channel-admin.controller.ts:29
      - insuniverse-server/apps/api/src/modules/sales-agency/channel/sales-agency-channel.entity.ts:6
  - id: CLIENT_ANALYSIS_SEPARATE
    status: active-prod
    evidence: [S-roles, S-guard]
    limitations:
      - 고객사 분석이 일반 분석과 다른 입구·자료를 쓴다는 것까지가 관측이다. 두 축의 결과 형태가 같은지는 이 문서가 대조하지 않았다
      - 열람 토큰 경로의 계약 자체는 총론 권한 축이 진다
    anchors:
      - insuniverse-server/apps/api/src/modules/client/analyze/client-analyze-admin.controller.ts:39
      - insuniverse-server/apps/api/src/modules/client/analyze/client-analyze-admin-view.controller.ts:36
  - id: CORP_FC_WRITE_SCOPE
    status: active-prod
    evidence: [S-guard, S-contract]
    limitations:
      - 기업FC 쓰기가 조직 범위 판정을 거친다는 것까지가 관측이다. 그 판정이 일괄 업로드 경로까지 덮는지는 전수로 세지 않았다
      - 회원 종류 어휘가 담긴 자리는 열되 각 값의 뜻은 적지 않는다
    anchors:
      - insuniverse-server/apps/api/src/modules/fc/fc.entity.ts:14
      - insuniverse-server/apps/api/src/modules/fc/agency/agency-fc.repository.ts:120
      - insuniverse-server/apps/api/src/modules/fc/agency/fc-agency.service.ts:93
  - id: REFERRAL_BENEFIT_MASTER
    status: active-prod
    evidence: [S-roles, S-route]
    limitations:
      - 추천 혜택이 단일 마스터 값이고 편집이 관리자 한 종류라는 것까지가 관측이다. 그 값이 실제 지급으로 이어지는 경로는 `04-settlement-money.md` 축이며 여기서 다시 쓰지 않는다
      - 혜택 값의 이력 보존 여부는 세지 않았다
    anchors:
      - insuniverse-server/apps/api/src/modules/referral/referral-admin.controller.ts:24
      - insuniverse-server/apps/api/src/modules/referral/referral.repository.ts:22
  - id: AUTHORITY_NAME_MASTER
    status: active-prod
    evidence: [S-schema, S-route]
    limitations:
      - 권한명이 별도 마스터 자료로 관리된다는 것까지가 관측이다. 그 이름이 실제 판정 층에 어떻게 연결되는지는 이 문서가 추적하지 않았고 그 자리는 총론 권한 축이다
      - 이 마스터가 화면 노출 축과 같은 것을 가리키는지는 대조하지 않았다
    anchors:
      - insuniverse-server/apps/api/src/modules/authority/authority.entity.ts:6
      - insuniverse-server/apps/api/src/modules/authority/authority.service.ts:21
      - insuniverse-server/apps/api/src/modules/authority/authority-adimin.controller.ts:29
      - insuniverse-server/apps/api/src/modules/authority/authority-adimin.controller.ts:30
  - id: ALLOW_IP_MASTER
    status: active-prod
    evidence: [S-schema, S-route]
    limitations:
      - 이 입구에 판정 층이 결선돼 있지 않다는 것까지가 관측이다. 다른 층(역방향 프록시·망 분리 등)이 앞에서 막는지는 이 저장소가 말하지 않는다
      - 이 목록을 실제로 대조하는 층이 어디인지는 이 문서가 세지 않았다 — 목록만 있고 강제가 없을 가능성을 배제하지 않는다
      - 자료에 조직 식별자 열이 없어 기업별 목록이 아니라 전역 목록이다
    anchors:
      - insuniverse-server/apps/api/src/modules/allow-ip/allow-ip.entity.ts:5
      - insuniverse-server/apps/api/src/modules/allow-ip/allow-ip-admin.controller.ts:15
      - insuniverse-server/apps/api/src/modules/allow-ip/allow-ip-admin.controller.ts:17
  - id: CORP_MYPAGE_SELF_EDIT
    status: staged-only
    evidence: [S-roles, A-release]
    limitations:
      - 미도달 판정의 근거는 이 앵커 행의 최종 변경 커밋 하나다. 그 행이 뒤에 다른 커밋으로 밀리면 같은 규칙이 도달로 뒤집힐 수 있다
      - 비밀번호 재확인이 어느 조작까지를 덮는지는 이 문서가 전수로 세지 않았다
    anchors:
      - insuniverse-server/apps/api/src/modules/agency/agency/corp-my.controller.ts:53
  - id: SALES_EXTERNAL_REPORT
    status: staged-only
    evidence: [S-component, A-release]
    limitations:
      - 미도달 판정의 근거는 이 앵커 행의 최종 변경 커밋 하나다. 그 행이 뒤에 다른 커밋으로 밀리면 같은 규칙이 도달로 뒤집힐 수 있다
      - 수신처와 발송 주기는 실행 환경 값이라 적지 않는다
    anchors:
      - insuniverse-server/apps/api/src/modules/sales-agency/samsung-s2-report.service.ts:66
---

# 대리점·기업 도메인 — 계약 과금방식 · 조직 부분트리 · 영업 채널 · 고객사 분석 · 기업FC 범위 · 추천 혜택 · 권한명·허용 IP 마스터 · 기업 마이페이지와 대외 리포트 미배포

**누가 어느 조직에 속해 무엇까지 닿는가**를 다룬다. 기업 계약의 과금방식, 조직 트리와 그 부분트리 산출, 영업 대리점과 채널 두 단, 고객사 분석의 별도 축, 기업FC 쓰기 범위, 추천 혜택 마스터, 그리고 관리자가 운영하는 권한명·허용 IP 두 마스터가 여기 있다.

**여기 없는 것** — 권한 층 자체의 정의와 우선순위, 로그인 주체 축의 어휘는 총론 소관이며 이 문서는 그 층이 이 도메인 자료에 걸리는 자리만 낸다. 조직 범위가 구독·주문 목록에 걸리는 자리는 `03-subscription-order.md`, 머니 지급에 걸리는 자리는 `04-settlement-money.md` 가 각각 진다.

**두 마스터를 여기 둔 판정** — 권한명과 허용 IP 는 접근 통제의 재료지만 총론 어느 정책도 그 두 모듈을 앵커로 갖지 않는다. 통제 **층**은 총론이 지고 이 문서는 그 층이 읽는 **운영 마스터**를 진다. 경계 판정의 근거는 `.claude/notes/insuniverse-docs-50-domain-m8.md` §모듈 배정 원장 에 있다.

## 정책 (기획)

### AGENCY_CONTRACT_BILLING

**기업 계약은 과금방식 축을 갖는다.** 미리 내는 방식, 나중에 내는 방식, 값을 받지 않는 방식이 코드값으로 갈린다. 계약은 기업에 여러 건 붙을 수 있고, 현재 유효한 것을 고를 때는 최신 한 건을 본다.

### ORG_SUBTREE_SCOPE

**기업 조직은 트리이고, 범위 판정은 한 조직이 아니라 그 아래 전부를 분모로 삼는다.** 부분트리는 조직마다 갖고 있는 경로 값 하나로 구해지며, 기업 측 주체는 자기 조직을 기준으로 목록이 좁혀진다.

### SALES_CHANNEL_TREE

**영업 조직은 대리점과 채널 두 단이다.** 대리점 아래 채널이 붙고, 대리점 목록은 관리자만, 채널 목록은 관리자와 영업 주체가 연다. 대표로 쓰이는 대리점을 고르는 자리가 따로 있다.

### CLIENT_ANALYSIS_SEPARATE

**고객사 분석은 일반 분석과 다른 축이다.** 자기 입구와 자기 자료를 갖고, 관리자용 입구와 열람 토큰용 입구가 따로 있다.

### CORP_FC_WRITE_SCOPE

**기업FC 를 고치려면 그 대상이 요청자의 조직 범위 안이어야 한다.** 회원 종류가 코드값으로 갈리고, 쓰기 전에 대상 회원과 대상 조직 양쪽이 범위 안인지 확인된다.

### REFERRAL_BENEFIT_MASTER

**추천 혜택은 단일 마스터 값이다.** 조회는 열려 있고 편집은 관리자 한 종류만 한다.

### AUTHORITY_NAME_MASTER

**권한명은 별도 마스터 자료로 운영된다.** 이름과 생성·수정 시각만 담는 얇은 자료이며, 입구에 인증과 역할 판정이 함께 결선돼 관리자만 목록·상세를 연다.

### ALLOW_IP_MASTER

**허용 IP 는 별도 마스터 자료로 운영된다.** 사용자명·주소·사용 장소를 담는다. **이 목록에 조직 식별자 열이 없어 기업별 목록이 아니라 전역 목록이다.**

**경로 이름은 관리자용이지만 그 입구에 판정 층이 걸려 있지 않다.** 인증 층을 붙이는 줄이 주석 처리된 채로 남아 있어, 이 마스터의 목록·등록·수정이 로그인 없이 닿는다. 이 문서는 그 사실을 관측으로 적고 고치지 않는다 — 코드 수정은 이 PRD 밖이며 이월 원장이 그 자리를 진다.

## 강제 지점 (개발)

### AGENCY_CONTRACT_BILLING

과금방식 어휘는 `insuniverse-server/apps/api/src/modules/agency/contract/contract.entity.ts:8` 의 열거형이고, 계약 편집 입구의 허용 역할은 `insuniverse-server/apps/api/src/modules/agency/contract/contract-admin.controller.ts:27` 이 선언한다. 기업 자료형은 `insuniverse-server/apps/api/src/modules/agency/agency/agency.entity.ts:6` 이다.

### ORG_SUBTREE_SCOPE

부분트리 산출은 `insuniverse-server/apps/api/src/modules/agency/organization/organization.repository.ts:49`, 기업 측 조회 입구의 허용 역할은 `insuniverse-server/apps/api/src/modules/agency/organization/organization-corp.controller.ts:39`, 조직 자료형은 `insuniverse-server/apps/api/src/modules/agency/organization/organization.entity.ts:18` 이다. 쓰기 범위 층 자체는 `../02-access/03-authz-capabilities.md#ORG_WRITE_SCOPE` 가 진다.

### SALES_CHANNEL_TREE

대리점 자료형은 `insuniverse-server/apps/api/src/modules/sales-agency/sales-agency.entity.ts:6`, 채널 자료형은 `insuniverse-server/apps/api/src/modules/sales-agency/channel/sales-agency-channel.entity.ts:6`, 채널 입구의 허용 역할은 `insuniverse-server/apps/api/src/modules/sales-agency/channel/sales-agency-channel-admin.controller.ts:29` 가 선언한다.

### CLIENT_ANALYSIS_SEPARATE

관리자용 입구의 허용 역할은 `insuniverse-server/apps/api/src/modules/client/analyze/client-analyze-admin.controller.ts:39`, 열람 토큰용 입구의 결선 층은 `insuniverse-server/apps/api/src/modules/client/analyze/client-analyze-admin-view.controller.ts:36` 이다. 토큰 계약 자체는 `../02-access/05-admin-view-token.md#VIEW_TOKEN_DELIVERY` 가 진다.

### CORP_FC_WRITE_SCOPE

회원 종류 어휘는 `insuniverse-server/apps/api/src/modules/fc/fc.entity.ts:14` 의 열거형이고, 대상 회원의 범위 확인은 `insuniverse-server/apps/api/src/modules/fc/agency/agency-fc.repository.ts:120`, 쓰기 전 단언은 `insuniverse-server/apps/api/src/modules/fc/agency/fc-agency.service.ts:93` 이 진다.

### REFERRAL_BENEFIT_MASTER

편집 입구의 허용 역할은 `insuniverse-server/apps/api/src/modules/referral/referral-admin.controller.ts:24`, 값 조회는 `insuniverse-server/apps/api/src/modules/referral/referral.repository.ts:22` 다.

### AUTHORITY_NAME_MASTER

자료형은 `insuniverse-server/apps/api/src/modules/authority/authority.entity.ts:6`, 목록 조회는 `insuniverse-server/apps/api/src/modules/authority/authority.service.ts:21` 이다. 입구의 결선 층은 `insuniverse-server/apps/api/src/modules/authority/authority-adimin.controller.ts:29`, 허용 역할은 `insuniverse-server/apps/api/src/modules/authority/authority-adimin.controller.ts:30` 이 선언한다 — **같은 절의 허용 IP 마스터와 달리 이쪽은 결선돼 있다.** 역할 어휘 자체는 `../02-access/02-authz-roles.md#ROLE_VOCABULARY` 가 진다.

### ALLOW_IP_MASTER

자료형은 `insuniverse-server/apps/api/src/modules/allow-ip/allow-ip.entity.ts:5`, 입구는 `insuniverse-server/apps/api/src/modules/allow-ip/allow-ip-admin.controller.ts:17` 이다. **그 입구에 판정 층이 없다** — 인증 층 결선 줄이 `insuniverse-server/apps/api/src/modules/allow-ip/allow-ip-admin.controller.ts:15` 에 주석으로 남아 있고 다른 결선이 이 파일에 없다.

### CORP_MYPAGE_SELF_EDIT

기업 측 마이페이지의 비밀번호 재확인 입구는 `insuniverse-server/apps/api/src/modules/agency/agency/corp-my.controller.ts:53` 이다. 그 행의 최종 변경 커밋이 릴리스 인덱스의 미도달 집합에 있다.

### SALES_EXTERNAL_REPORT

대외 리포트 발송 처리기는 `insuniverse-server/apps/api/src/modules/sales-agency/samsung-s2-report.service.ts:66` 이다. 그 행의 최종 변경 커밋이 릴리스 인덱스의 미도달 집합에 있다.

## 적용 범위 (actor × 서비스)

| 정책 id | server | site | admin |
|---|---|---|---|
| AGENCY_CONTRACT_BILLING | 과금 어휘 · 편집 역할 선언 · 기업 자료형 | — | 계약 관리 화면 |
| ORG_SUBTREE_SCOPE | 부분트리 산출 · 기업 입구 역할 · 조직 자료형 | — | 조직 관리 화면 |
| SALES_CHANNEL_TREE | 두 자료형 · 채널 입구 역할 선언 | — | 영업 관리 화면 |
| CLIENT_ANALYSIS_SEPARATE | 두 입구의 결선 층·역할 선언 | 열람 토큰 경로가 이 입구를 부른다 | 고객사 분석 화면 |
| CORP_FC_WRITE_SCOPE | 종류 어휘 · 범위 확인 · 쓰기 전 단언 | — | 기업FC 관리 화면 |
| REFERRAL_BENEFIT_MASTER | 편집 역할 선언 · 값 조회 | 혜택 안내 화면 | 혜택 편집 화면 |
| AUTHORITY_NAME_MASTER | 자료형 · 목록 조회 · 결선 층·역할 선언 | — | 권한 관리 화면 |
| ALLOW_IP_MASTER | 자료형 · 입구 · 결선 부재 | — | 허용 IP 관리 화면 |
| CORP_MYPAGE_SELF_EDIT | 재확인 입구 · 역할 선언 | — | 기업 마이페이지 |
| SALES_EXTERNAL_REPORT | 발송 처리기 | — | — |

`—` = 그 서비스가 이 정책의 경로에 등장하지 않음.

이 표의 열은 서비스 3종이며 actor 는 열이 아니다. 이 문서의 축은 조직·계약 자원에 걸리는 판정이라 actor 를 열로 두면 서버 한 칸만 차는 표가 된다. 열 이름 집합과 순서는 `../_meta/template-config.yaml` 의 `services` 를 그대로 따른다.

## 예외·폴백

| 정책 id | 예외 조건 | 폴백 동작 | 확인 근거 |
|---|---|---|---|
| AGENCY_CONTRACT_BILLING | 계약이 여러 건일 때 | 최신 한 건을 고른다. 겹치는 기간의 처리는 이 문서가 판정하지 않는다 | `insuniverse-server/apps/api/src/modules/agency/agency/corp-my.service.ts:30` |
| AGENCY_CONTRACT_BILLING | 관리자가 아닌 주체가 계약을 고칠 때 | 역할 판정에서 거부된다 | `insuniverse-server/apps/api/src/modules/agency/contract/contract-admin.controller.ts:27` |
| ORG_SUBTREE_SCOPE | 경로 값이 갱신되지 않은 조직일 때 | 부분트리 산출이 그 값을 그대로 쓴다. 갱신 보장은 이 문서가 판정하지 않는다 | `insuniverse-server/apps/api/src/modules/agency/organization/organization.repository.ts:49` |
| SALES_CHANNEL_TREE | 영업 주체가 대리점 목록을 열려 할 때 | 대리점 입구는 관리자만이라 거부된다. 채널 입구는 열린다 | `insuniverse-server/apps/api/src/modules/sales-agency/channel/sales-agency-channel-admin.controller.ts:29` |
| CLIENT_ANALYSIS_SEPARATE | 일반 분석 입구로 고객사 건을 열려 할 때 | 자료와 입구가 달라 그 경로로 가지 않는다 | `insuniverse-server/apps/api/src/modules/client/analyze/client-analyze-admin.controller.ts:39` |
| CORP_FC_WRITE_SCOPE | 대상 회원이 요청자 범위 밖일 때 | 쓰기 전 단언에서 거부된다 | `insuniverse-server/apps/api/src/modules/fc/agency/fc-agency.service.ts:93` |
| REFERRAL_BENEFIT_MASTER | 관리자가 아닌 주체가 혜택을 고칠 때 | 역할 판정에서 거부된다. 조회는 별도 입구라 영향받지 않는다 | `insuniverse-server/apps/api/src/modules/referral/referral-admin.controller.ts:24` |
| AUTHORITY_NAME_MASTER | 관리자가 아닌 주체가 이 마스터에 닿을 때 | 역할 판정에서 거부된다 | `insuniverse-server/apps/api/src/modules/authority/authority-adimin.controller.ts:30` |
| AUTHORITY_NAME_MASTER | 이 마스터의 이름을 판정 층이 참조하는지 물을 때 | 이 문서는 답하지 않는다. 연결 여부를 추적하지 않았다 | `insuniverse-server/apps/api/src/modules/authority/authority.service.ts:21` |
| ALLOW_IP_MASTER | 목록에 없는 주소로 접속할 때 | 이 문서는 차단을 주장하지 않는다. 대조 층의 실재를 세지 않았다 | `insuniverse-server/apps/api/src/modules/allow-ip/allow-ip.entity.ts:5` |
| ALLOW_IP_MASTER | 로그인하지 않고 이 입구를 쓸 때 | 판정 층이 결선돼 있지 않아 요청이 막히지 않는다 | `insuniverse-server/apps/api/src/modules/allow-ip/allow-ip-admin.controller.ts:15` |
| CORP_MYPAGE_SELF_EDIT | 이 규칙이 배포에 도달하지 않은 환경일 때 | 기업 측 마이페이지 입구 자체가 없다 | `insuniverse-server/apps/api/src/modules/agency/agency/corp-my.controller.ts:53` |
| SALES_EXTERNAL_REPORT | 이 규칙이 배포에 도달하지 않은 환경일 때 | 대외 리포트가 나가지 않는다 | `insuniverse-server/apps/api/src/modules/sales-agency/samsung-s2-report.service.ts:66` |

## 부록

이 절의 정책은 **앵커 행의 최종 변경 커밋이 릴리스 인덱스의 미도달 집합에 있어 현행 배포를 판정하지 못한다.** 배치의 정본은 `../_meta/template-config.yaml` 의 `statuses` 이며, 도달이 확인되면 상태가 바뀌고 배치도 함께 옮긴다.

### CORP_MYPAGE_SELF_EDIT

**기업 측 주체가 자기 정보를 직접 고치는 자리가 있고, 그 앞에 비밀번호 재확인이 걸려 있다.** 이 층이 도달한 환경에서는 기업 담당자가 스스로 고칠 수 있고, 도달하지 않은 환경에서는 그 입구가 없다.

### SALES_EXTERNAL_REPORT

**영업 축에 외부로 나가는 정기 리포트 발송 경로가 있다.** 이 경로가 도달한 환경에서는 집계 결과가 통합문서로 조립돼 나가고, 도달하지 않은 환경에서는 발송이 없다.

## 연혁

릴리스 태그가 존재하지 않는다. 릴리스 열은 `—` 로 두고 커밋 SHA 로 추적한다.

| 릴리스 | 날짜 | SHA | 변경 요약 |
|---|---|---|---|
| — | 2024-11-11 | `fd1954cd` | 허용 IP 마스터 신설 |
| — | 2024-11-11 | `d64d7613` | 허용 IP 관리자 입구 정리 |
| — | 2024-11-13 | `d992254d` | 권한명 마스터 자료형 정리 |
| — | 2024-11-14 | `911cd24f` | 기업 자료형 신설 |
| — | 2025-03-19 | `36915d9e` | 기업FC 자료와 회원 종류 어휘 신설 |
| — | 2025-04-03 | `644f841b` | 권한 관리 입구 신설 |
| — | 2025-04-03 | `afdbf4df` | 권한 목록 조회 처리기 신설 |
| — | 2025-05-13 | `3b3c1afd` | 영업 대리점 자료형 신설 |
| — | 2025-06-24 | `780e6b64` | 고객사 분석 관리자 입구에 역할 기반 판정 도입 |
| — | 2025-06-25 | `b4027706` | 영업 채널 관리 입구 신설과 역할 정리 |
| — | 2025-11-17 | `8e2c7575` | 추천 혜택 마스터와 관리자 편집 입구 신설 |
| — | 2026-05-20 | `8be772db` | 기업과 기업상품의 관계가 일대다로 바뀌며 조직 조회 입구 정리 |
| — | 2026-07-01 | `f0ce46c8` | 조직 부분트리 산출과 기업FC 범위 확인 도입 |
| — | 2026-07-01 | `55c4eaac` | 고객사 분석에 열람 토큰 전용 입구 신설 |
| — | 2026-07-11 | `d4513a79` | 계약에 과금방식 축 추가 |
| — | 2026-07-23 | `6733fa99` | 영업 축 대외 리포트 발송 경로 추가 |
| — | 2026-07-31 | `bbb09d1b` | 기업 측 마이페이지와 비밀번호 재확인 입구 추가 |