수백 대 DB 점검 리포트를 담당자별로 나눠 보내기

핵심 요약

DB 일일 점검 리포트를 처음에는 몇 대만 대상으로, 한 통의 메일에 전부 담아 보냈습니다. 그런데 점검 대상이 수백 대로 늘면서 한 통에 다 담을 수 없게 됐습니다. 게다가 인스턴스마다 담당자가 다르고, 한 인스턴스를 회사 담당자와 협력사 담당자가 함께 관리하는 구조였습니다.
그래서 "담당자(수신자) 단위로 리포트를 나눠, 각자 자기 담당분만 받아보게" 하는 라우팅 계층을 만들었습니다. 이 글은 그 과정을 처음부터 끝까지, 실제 코드와 함께 정리한 것입니다.
큰 줄기는 다섯 단계입니다.

1. 지저분한 담당자 매핑 엑셀을 표준 한 시트로 정제한다.
2. 표준 시트를 읽어 인스턴스 목록을 만든다(제외·무효 이메일·직급 정리 포함).
3. 인스턴스 목록을 담당자 기준으로 뒤집어 수신자별로 묶는다.
4. 담당자 한 명분 리포트를 조립한다(기존 단일 리포트 렌더러를 통째로 재사용).
5. 수신자 전원을 일괄 생성하고 발송 이력을 남긴다.

중간에 한 번 헷갈렸던 지점 — "같은 인스턴스를 두 사람에게 보내면 점검 건수가 두 배로 잡히는 것 아닌가" — 을 어떻게 정리했는지도 담았습니다. 이런 "카운트의 함정"은 실무에서 은근히 자주 나오는 주제라, 비슷한 상황을 만나는 분들께 도움이 될 것 같습니다.

---

1. 배경 — 한 통으로는 감당이 안 됩니다

초기 구조는 단순했습니다. 설정 파일에 점검할 DB를 몇 개 적어 두면, 프로그램이 순서대로 수집 → 이상 탐지 → 리포트를 만들어 정해진 주소로 한 통 보냈습니다. 대상이 서너 대일 때는 이게 제일 깔끔합니다. 리포트 하나에 전부 들어가고, 받는 사람도 한 명이면 됩니다.
그런데 실제 운영 대상은 수백 대였습니다. 이걸 한 통에 다 넣으면 스크롤이 끝없이 길어져서, 정작 봐야 할 사람은 자기 것을 찾지 못합니다. 더 중요한 건 담당자가 인스턴스마다 다르다는 점이었습니다. 어떤 서비스는 A가, 어떤 서비스는 B가 담당하고, 한 인스턴스를 회사 쪽 담당자와 실제 운영을 맡은 협력사 담당자가 같이 봅니다.
여기서 요구사항이 자연스럽게 정리됐습니다.

• 담당자는 자기가 맡은 인스턴스만 담긴 리포트를 받는다.
• 한 담당자가 여러 서비스를 맡으면, 그 한 통 안에서 서비스별로 나눠 보여준다.
• 한 인스턴스에 담당자가 둘(회사·협력사)이면 둘 다 받는다.
• 누구에게 언제 무엇을 보냈는지 이력이 남아야 한다.

비유하자면, 대형 아파트 단지의 관리사무소에서 "오늘 점검 결과"를 주민 전체에게 한 장으로 붙이는 대신, 동·호수별 담당 라인에 맞춰 각자에게 필요한 부분만 전달하는 것과 비슷합니다. 전체 공지 한 장은 아무도 자기 것을 못 찾지만, 라인별로 잘라 주면 각자 자기 것만 보면 됩니다.
이 글에서 만드는 파일들을 먼저 한 줄씩 소개하면 이렇습니다. 뒤에서 하나씩 자세히 다룹니다.

• gen_routing.py — (일회성) 지저분한 원본 매핑 → 표준 한 시트로 정제.
• build_accounts.py — (상시) 표준 시트 → 인스턴스 목록(accounts.yaml).
• routing.py — 인스턴스 목록을 담당자 기준으로 뒤집어 수신자별로 묶음.
• recipient_report.py — 담당자 한 명분 리포트 조립.
• run_routing.py — 수신자 전원 일괄 생성 + 발송 이력.

---

2. 첫 번째 문제 — 매핑 데이터가 지저분합니다

담당자 매핑은 엑셀로 받았습니다. 그런데 이 파일이 사람이 손으로 관리하던 것이라 형태가 제각각이었습니다. 실제로 마주친 문제들을 나열하면 이렇습니다.

• 시트가 두 개였습니다. 클라우드 종류에 따라 한 시트는 이런 컬럼, 다른 시트는 저런 컬럼이었습니다.
• 한 시트에는 '제외' 컬럼이 있고, 다른 시트에는 없었습니다.
• 서비스 이름이 그룹의 첫 행에만 적혀 있고, 아래 행들은 비어 있었습니다(엑셀에서 흔히 보는, 병합셀처럼 위에만 쓰고 아래로 이어지는 표기).
• 엔진 이름 표기가 제각각이었습니다. aurora-mysql, MariaDB, Azure MySQL, MySQL — 사실상 같은 계열인데 문자열이 다 달랐습니다.

이걸 그대로 프로그램이 읽게 하면, 파싱 코드가 두 시트의 서로 다른 규칙을 전부 흡수해야 해서 복잡해집니다. 그리고 그 복잡한 코드를 매번 돌려야 합니다. 그래서 방향을 이렇게 잡았습니다.

1. 정규화(한 번만) — 지저분한 원본을 읽어, 표준 한 시트 양식으로 다시 뽑아낸다.
2. 읽기(상시) — 앞으로는 그 표준 양식만 읽는다. 이건 짧은 코드면 충분하다.

지저분함을 흡수하는 무거운 코드는 딱 한 번만 쓰고, 이후엔 깔끔한 표준만 상대하자는 겁니다. 마치 여러 사람이 손글씨로 제각각 써 온 신청서를, 한 번 표준 양식에 옮겨 적고 나면 그다음부터는 그 표준 양식만 보면 되는 것과 같습니다.

엔진 이름을 '계열'로 묶기

정규화에서 가장 중요한 건 엔진 이름 통일이었습니다. 임계값이나 점검 지표는 개별 표기(aurora-mysql)가 아니라 계열(mysql) 기준으로 적용되기 때문입니다. aurora-mysql이든 MariaDB든 Azure MySQL이든, 우리 입장에서는 "MySQL 계열"로 묶어 같은 임계값 세트를 씁니다.

그래서 문자열을 보고 계열을 판정하는 함수를 만들었습니다.

def engine_family(raw: str) -> str:
    """원본 엔진명 → 임계값·모니터링을 묶는 계열. (postgres 를 aurora/mysql 보다 먼저 검사)"""
    s = (raw or "").strip().lower()
    if not s:
        return "unknown"
    if "oracle" in s:
        return "oracle"
    if "postgres" in s:
        return "postgresql"
    if "docdb" in s or "documentdb" in s or "mongo" in s:
        return "documentdb"
    if "sql server" in s or "sqlserver" in s or "mssql" in s:
        return "sqlserver"
    if "mysql" in s or "maria" in s or "aurora" in s:
        return "mysql"
    return "other"

여기서 순서가 중요합니다. aurora-postgresql에는 aurora도 들어 있고 postgres도 들어 있습니다. 만약 aurora → mysql 규칙을 먼저 두면, aurora-postgresql이 "aurora가 들어 있네" 하며 MySQL로 잘못 분류됩니다. 그래서 postgres 검사를 aurora보다 앞에 뒀습니다.

이런 "문자열 포함 검사"는 순서에 민감합니다. 겹치는 키워드가 있을 때는 더 구체적인(혹은 더 좁은) 조건을 먼저 걸러야 합니다. 마치 우편물을 분류할 때 "서울시"로 먼저 나누면 "서울시 강남구"가 엉뚱한 칸에 들어가는 것과 같아서, 좁은 조건(구·동)부터 걸러야 하는 것과 비슷합니다.
실제로 원본에는 이런 표기들이 섞여 있었고, 위 함수를 거치면 아래처럼 정리됩니다.

aurora-mysql        → mysql
MariaDB             → mysql
Azure MySQL         → mysql
aurora-postgresql   → postgresql      (aurora 가 들어 있어도 postgres 우선)
oracle-se2          → oracle
docdb               → documentdb
Azure SQL Server    → sqlserver

표준 양식을 엑셀로 다시 내보내기

정규화 결과는 프로그램 내부 자료로만 쓰지 않고, 엑셀로도 내보냈습니다. 앞으로 담당자나 제외 여부가 바뀌면 사람이 이 표준 한 시트만 고치고 다시 읽으면 되기 때문입니다. 코드는 이렇게, 표준 컬럼 순서로 한 줄씩 채워 저장합니다.

def dump_xlsx(insts, path):
    """정제된 매핑을 '한 시트' 표준 양식 엑셀로 저장 (제외 포함 전체)."""
    wb = Workbook()
    ws = wb.active
    ws.title = "인스턴스_담당자_매핑"
    headers = ["연번", "클라우드", "서비스(Account)", "인스턴스 ID", "엔진", "엔진계열",
               "회사 담당자", "회사 이메일", "협력사 담당자", "협력사 이메일", "제외"]
    # ... 헤더 스타일 지정 ...
    for i, inst in enumerate(sorted(insts, key=lambda x: (x["account"], x["id"])), start=1):
        jj_name, jj_mail = _role_pair(inst["contacts"], "회사")
        hp_name, hp_mail = _role_pair(inst["contacts"], "협력사")
        vals = [i, inst["cloud"], inst["account"], inst["id"], inst["engine"],
                inst["engine_family"], jj_name, jj_mail, hp_name, hp_mail,
                inst.get("_exclude_raw", "")]
        # ... 한 행씩 기록, 제외 행은 회색 처리 ...
    wb.save(path)

여기서 한 가지 결정이 있었습니다. 제외된 인스턴스도 버리지 않고, '제외' 표시만 남긴 채 함께 저장했습니다. 나중에 담당자가 "이건 다시 점검 대상에 넣자"라고 하면, 제외 표시만 지우면 되도록요. 지워 버리면 되살릴 때 다시 찾아 적어야 하지만, 표시만 남기면 토글 한 번이면 됩니다.

이 정규화 스크립트(gen_routing.py)는 표준 양식을 처음 만들어 내는 '부트스트랩' 역할만 하고 물러납니다. 한 번 표준을 만들어 두면, 그다음부터 상시로 쓰는 건 아래 3절의 짧은 reader입니다.

---

3. 표준 양식을 읽어 인스턴스 목록 만들기

표준 양식이 생기고 나니, 그걸 읽어 프로그램이 쓸 형태로 바꾸는 코드는 아주 짧아졌습니다. 이게 바로 "무거운 코드는 한 번만" 전략의 보상입니다.

def load_accounts(xlsx):
    """정제양식 엑셀 한 시트를 읽어 활성 인스턴스 레코드 리스트로 반환."""
    ws = load_workbook(xlsx, read_only=True, data_only=True).active
    out = []
    for r in ws.iter_rows(min_row=2, values_only=True):
        cloud, account, iid, engine, fam = _s(r[1]), _s(r[2]), _s(r[3]), _s(r[4]), _s(r[5])
        jj_name, jj_mail, hp_name, hp_mail, ex = _s(r[6]), _s(r[7]), _s(r[8]), _s(r[9]), _s(r[10])
        if not iid:
            continue
        if ex.upper() == "O":       # 제외 표시된 인스턴스는 대상에서 뺀다
            continue
        contacts = []
        if jj_mail and jj_mail != "0":
            contacts.append({"role": "회사", "name": _clean_name(jj_name), "email": jj_mail})
        if hp_mail and hp_mail != "0":
            contacts.append({"role": "협력사", "name": _clean_name(hp_name), "email": hp_mail})
        out.append({
            "id": iid, "account": account, "cloud": cloud,
            "engine": engine, "engine_family": fam, "contacts": contacts,
        })
    return out

여기서 세 가지를 정리합니다.

• 제외(O) 표시된 인스턴스는 발송 대상에서 뺍니다. 전체 대수에서 제외를 빼면 실제 활성 대수가 나옵니다. 예를 들어 표에 322행이 있고 그중 132행이 제외라면, 활성은 190대입니다.
• 이메일이 비었거나 0(아직 안 정해짐)인 담당자는 연락처에서 뺍니다. 나중에 무효 주소로 발송을 시도하다 실패하지 않기 위해서입니다. 담당자가 아직 정해지지 않은 자리를 0으로 표시해 둔 칸이 실제로 있었습니다.
• 이름에 붙은 직급은 뗍니다(바로 아래에서 설명).

이렇게 나온 인스턴스 하나는 이런 모양입니다. 이게 이후 모든 단계의 기본 단위입니다.

{
  "id": "svc-db-01",             # 인스턴스 고유 id
  "account": "서비스A",           # 어느 서비스(Account) 소속인지
  "cloud": "aws",
  "engine": "aurora-mysql",       # 원본 엔진명(그대로 보존)
  "engine_family": "mysql",       # 계열(임계값·지표 적용 기준)
  "contacts": [
    {"role": "회사",   "name": "김OO", "email": "kim@example.com"},
    {"role": "협력사", "name": "이OO", "email": "lee@partner.com"},
  ],
}

이름에서 직급 떼기

원본 담당자 이름에는 "OOO 부장", "OOO 외" 처럼 직급이나 꼬리표가 붙어 있는 경우가 있었습니다. 리포트에는 직급 없이 이름만 나오는 편이 깔끔해서, 이름 뒤에 붙은 직급·경칭 토큰을 떼어냈습니다.

_TITLES = {"부장", "차장", "과장", "대리", "책임", "선임", "팀장", "님", "씨", "외", ...}

def _clean_name(name):
    """'홍길동 부장' → '홍길동', '홍길동 외' → '홍길동'."""
    parts = name.split()
    while parts and parts[-1] in _TITLES:   # 뒤에서부터 직급 토큰이면 하나씩 뗀다
        parts.pop()
    return " ".join(parts)

뒤에서부터 훑어 직급이면 떼는 방식이라, "OOO 책임 님"처럼 여러 개가 붙어 있어도 다 정리됩니다. 리스트의 끝을 하나씩 벗겨 내는 셈입니다.
여기에는 뜻밖의 보너스가 있었습니다. 같은 사람이 어떤 행에는 "홍길동", 어떤 행에는 "홍길동 외"로 다르게 적혀 있는 경우가 있었는데, 직급·꼬리표를 떼고 나니 둘 다 "홍길동"이 되어, 나중에 이메일로 묶을 때 한 명으로 깔끔하게 합쳐졌습니다. 원래 노리던 건 "직급 제거"였는데, 덤으로 "표기 흔들림 정리"까지 된 셈입니다.

---

4. 라우팅 — 표를 '뒤집어' 수신자별로 묶기

이 단계가 라우팅의 핵심입니다. 한 문장으로 줄이면 "표를 뒤집는다" 입니다.
받은 매핑 표는 DB(인스턴스) 기준입니다. "이 DB는 누가 담당한다"가 한 줄씩 적혀 있습니다.

[원본 = DB 기준]
DB-A  →  회사담당 김OO, 협력사담당 이OO
DB-B  →  회사담당 김OO, 협력사담당 이OO
DB-C  →  회사담당 박OO, 협력사담당 최OO

그런데 우리가 보내는 건 사람마다 메일 한 통입니다. 그러니 이 표를 담당자 기준으로 뒤집어야 합니다. "담당자 → 그가 맡은 DB들"로요.

[뒤집은 것 = 담당자 기준]
김OO  →  [DB-A, DB-B, ...]     → 김OO 에게 이 DB들을 담은 한 통
이OO  →  [DB-A, DB-B]          → 이OO 에게 한 통
박OO  →  [DB-C, ...]           → 박OO 에게 한 통

'매핑'이 헷갈린다면 대개 이 두 방향 때문입니다. 원본은 DB가 주인공(DB마다 담당자가 붙음), 우리가 만드는 건 사람이 주인공(사람마다 DB 목록). 이 뒤집기 한 번이 라우팅의 전부라고 봐도 됩니다.
비유하자면, 전화번호부를 "번호 → 이름" 순서에서 "이름 → 그 사람의 번호들"로 다시 엮는 것과 같습니다. 또는 물건마다 주인 스티커가 붙어 있는 창고에서, 이번엔 주인별로 물건을 한 바구니씩 모으는 것과 같습니다.
방향을 명확히 잡고 갑니다.

• 발송·기록의 단위는 수신자(사람)입니다. 한 사람 = 한 통.
• 서비스는 그 사람 리포트 안에서의 소분류일 뿐, 발송 단위가 아닙니다.

담당자를 표현하는 작은 클래스

뒤집은 결과를 담을 그릇으로, 담당자 한 명을 나타내는 작은 클래스를 뒀습니다. 이메일이 신원이고, 이름·역할은 표시용이며, 그가 맡은 인스턴스 목록을 들고 있습니다.

class Recipient:
    """한 명의 수신 담당자와 그가 받아볼 인스턴스들."""

    def __init__(self, email: str):
        self.email = email
        self.names: set = set()           # 표기 이름(같은 사람이 여러 표기면 합쳐짐)
        self.roles: set = set()           # 회사 / 협력사 (양쪽 다일 수 있음)
        self.instances: list = []
        self._seen_ids: set = set()       # 수신자 내 인스턴스 중복 방지(id 기준)

    def add_instance(self, inst: dict) -> bool:
        """인스턴스를 담되, 같은 수신자 안에서 같은 인스턴스는 한 번만(중복 카운트 방지)."""
        iid = inst.get("id", "")
        if iid in self._seen_ids:
            return False
        self._seen_ids.add(iid)
        self.instances.append(inst)
        return True

    @property
    def services(self):
        """서비스명 → 인스턴스 리스트. (리포트 안에서 서비스별로 나눠 보여주기 위한 소분류)"""
        svc = OrderedDict()
        for inst in sorted(self.instances, key=lambda x: (x["account"], x["id"])):
            svc.setdefault(inst["account"], []).append(inst)
        return svc

names와 roles를 set으로 둔 이유가 있습니다. 같은 이메일이 여러 행에 등장하면서 이름 표기가 조금씩 다르거나, 어떤 서비스에서는 회사 담당·다른 서비스에서는 협력사 담당으로 잡힐 수 있습니다. set에 그때그때 넣으면 자동으로 중복이 합쳐집니다.

뒤집는 코드

실제로 뒤집는 코드는 단순합니다. 인스턴스를 하나씩 훑으면서, 그 인스턴스의 담당자마다 "그 담당자 바구니(Recipient)"에 인스턴스를 넣습니다. 한 인스턴스에 담당자가 둘(회사·협력사)이면 두 바구니에 각각 들어갑니다.

def group_by_recipient(instances: list):
    """인스턴스들을 담당자(이메일)별 Recipient 로 묶는다.
    한 인스턴스는 자신의 모든 담당자(회사·협력사) 그룹에 각각 포함된다.
    이메일이 없거나 '0'(미정)인 담당자는 건너뛴다."""
    recips = OrderedDict()
    for inst in instances:
        for c in inst.get("contacts", []):
            email = (c.get("email") or "").strip()
            if not email or email == "0":
                continue
            r = recips.get(email)
            if r is None:
                r = recips[email] = Recipient(email)
            r.names.add((c.get("name") or "").strip())
            r.roles.add((c.get("role") or "").strip())
            r.add_instance(inst)          # id 기준 dedup(같은 수신자 내 중복 방지)
    return OrderedDict(sorted(recips.items()))

여기서 이메일을 key로 씁니다. 사람 이름이 아니라 이메일 주소가 진짜 식별자입니다. 이름은 표기가 조금씩 다를 수 있어도(예: "홍길동"과 "홍길동 외"), 이메일이 같으면 같은 사람입니다. 그래서 같은 사람이 여러 서비스를 맡아 여러 행에 등장해도, 이메일로 묶으면 한 명으로 합쳐져 결국 한 통이 됩니다.
정리하면, 수백 대(DB 기준)를 뒤집어 소수의 담당자(사람 기준)로 묶는 겁니다. 실제로 이 프로젝트에서는 수백 대가 열 명 남짓의 담당자로 모였습니다. 소수의 운영자가 여러 인스턴스를 담당하는, 흔한 구조입니다. 한 사람이 수십 대를 맡기도 합니다.

중복 방지 — 한 수신자 안에서 같은 인스턴스는 한 번만

위 add_instance에 _seen_ids라는 방어를 넣은 이유를 짚고 넘어가겠습니다. 만약 어떤 행에서 회사 담당자와 협력사 담당자의 이메일이 우연히 같다면, 그 인스턴스가 같은 사람 바구니에 두 번 들어갈 수 있습니다. 그러면 그 사람의 담당 대수가 실제보다 부풀려집니다.

그래서 바구니에 넣기 전에 "이미 넣은 id인가?"를 한 번 확인합니다. 자바로 치면 Set<String> seen에 add한 결과(이미 있으면 false)로 중복을 거르는 것과 같습니다. 입장할 때 명단에 체크 표시를 하고, 이미 체크된 사람은 다시 안 세는 것과 비슷합니다.

지금 데이터에 실제로 그런 경우는 없었지만, 이런 방어는 지금 문제가 없어도 나중에 데이터가 바뀌면 조용히 틀린 숫자를 낼 수 있어 미리 막아 두는 편이 안전합니다. 숫자가 틀리면 눈에 잘 안 띄고, 나중에 "왜 이 사람 담당 대수가 이상하지?" 하며 한참을 헤매게 됩니다.

헷갈렸던 지점 — 두 사람에게 보내면 건수가 두 배?

여기서 잠깐 멈칫했습니다. 같은 인스턴스를 회사 담당자와 협력사 담당자 둘에게 보내면, 같은 내용을 두 번 센 게 되는 것 아닌가? 하는 의문이었습니다.
정리해 보니, 두 개를 서로 다른 지표로 보면 깔끔했습니다.

점검한 인스턴스 수	유니크 인스턴스	대상 전체 (중복 없음)
발송한 메일 통수	수신자(사람)	담당자 수만큼

"오늘 몇 대를 점검했나"는 인스턴스 기준이라, 그 인스턴스가 몇 명에게 통지되든 한 번만 셉니다. 실제로 수집·탐지도 인스턴스당 한 번만 돌리고, 그 결과를 여러 리포트가 나눠 씁니다.
반면 "메일 몇 통 보냈나"는 받는 사람 기준입니다. 같은 내용이라도 회사 담당자에게 1통, 협력사 담당자에게 1통이면 배달은 2건입니다.
비유하자면, 같은 공지문을 부서장과 실무자에게 각각 보내면 "발송 2건"이지 "공지 2개"가 아닙니다. 공지 내용은 하나지만 배달은 둘입니다.
그리고 실제로는 두 사람의 리포트가 완전히 같지도 않습니다. 회사 담당자가 협력사 담당자보다 서비스를 하나 더 맡고 있으면 담당 대수 자체가 다릅니다. 그래서 "같은 내용 두 번"이 아니라 "범위가 다른 두 리포트를 각자에게"가 정확한 표현입니다.

---

5. 담당자 한 명분 리포트 조립하기

이제 담당자 한 명이 받을 리포트를 만듭니다. 여기서 한 가지 결정을 했습니다. 기존 단일 리포트(한 대짜리)를 그리는 코드가 이미 잘 검증돼 있으니, 그 렌더러를 통째로 재사용하기로 했습니다.
처음에는 표·그래프·진단 같은 부품만 골라 옮겨 담았습니다. 그런데 그러다 보니 "수집 커버리지 카드"나 "오늘의 핵심" 같은 요소가 슬그머니 빠졌습니다. 손으로 하나씩 옮기다 보면 꼭 뭔가를 흘립니다. 이사할 때 물건을 하나씩 나르면 꼭 서랍 하나를 두고 오는 것과 같습니다.
그래서 방향을 바꿨습니다. 단일 리포트에서 본문을 만드는 부분만 별도 함수(본문 빌더)로 분리하고, 담당자 리포트는 서비스마다 이 본문 빌더를 한 번씩 호출하도록 했습니다. 서랍째 통으로 옮기니 흘릴 게 없습니다.

# 담당자 리포트 = 담당자 헤더 + 서비스별 요약 표 + (서비스마다) 단일 리포트 본문
for svc, sinsts in recipient.services.items():
    svc_dets, svc_mets, pend = {}, {}, 0
    for inst in sinsts:
        d = det_by_id.get(inst.get("id"))
        if d is not None and getattr(d, "has_data", False):
            svc_dets[inst["id"]] = d                 # 데이터 있는 인스턴스만 상세로
            svc_mets[inst["id"]] = metrics_by_id.get(inst["id"])
        else:
            pend += 1                                # 나머지는 '수집 대기'로 셈
    if svc_dets:
        parts.extend(build_report_parts(
            svc_dets, svc_mets, config, target_date, out_dir, images,
            title=svc, kpi_label="인스턴스", include_footer=False))
    else:
        parts.append(f"... {svc} · 수집 대기 {pend}대 ...")

분리한 본문 빌더의 시그니처는 이렇게 생겼습니다. 제목·라벨·브랜드를 인자로 받아, 단일 리포트로도 서비스 단위 부분으로도 쓸 수 있게 했습니다.

def build_report_parts(detections, db_metrics, config, target_date, out_dir, images,
                       title=None, subtitle=None, kpi_label="점검 DB",
                       include_footer=True, brand="...기본 브랜드..."):
    """리포트 본문 파트 리스트(헤더 KPI ~ 푸터) 생성 — 단일 리포트와 담당자 리포트가 공용.
    title/subtitle/kpi_label 로 헤더를 바꿔 서비스 단위 재사용 가능."""
    ...

이렇게 하니 커버리지 카드, 오늘의 핵심, 전일 대비 변화 같은 요소가 손으로 옮기다 빠질 일 없이 서비스별로 그대로 다 들어갑니다. 각 서비스 블록은 사실상 "한 장짜리 단일 리포트"가 됩니다.
한 가지 특히 주의한 건, 본문 빌더를 분리하면서 원래 단일 리포트의 출력이 한 글자도 바뀌지 않게 한 것입니다. 이미 배포돼 매일 돌고 있는 리포트라, 분리 전후의 결과 HTML을 파일로 뽑아 그대로 비교해 완전히 같은지 확인했습니다. "리팩터링했는데 출력이 똑같다"를 눈으로 증명한 셈입니다. 이런 대체 작업은 "동작이 안 바뀌었다"를 말로만 하지 말고 결과를 실제로 비교해 두는 게 안전합니다.
담당자 리포트의 최종 구조는 이렇습니다.

1. 담당자 헤더 + 전체 요약 — 담당 대수, 위험/주의/정상/수집대기 개수. (제목은 평소 리포트와 같게 두고, 수신자 이름은 우측에 작게)
2. 서비스별 요약 표 — 담당한 서비스마다 대수와 등급 분포, 엔진 구성.
3. 서비스별 상세 — 데이터가 있는 서비스마다 단일 리포트 본문을 통으로(커버리지·오늘의 핵심·전일 대비·위험/주의 상세·정상까지) 펼침. 아직 데이터가 없는 인스턴스는 '수집 대기'로.
4. 주간·월간 안내와 푸터.

전체 요약의 개수를 세는 부분은 이렇게 단순합니다. 탐지 결과가 있으면 등급으로, 없으면 '수집 대기'로 나눕니다.

for inst in insts:
    det = det_by_id.get(inst.get("id"))
    if det is None or not getattr(det, "has_data", False):
        n_pending += 1
    elif det.worst_grade == "critical":
        n_crit += 1
    elif det.worst_grade == "warning":
        n_warn += 1
    else:
        n_normal += 1

'수집 대기'라는 상태를 둔 이유

실제 데이터가 준비된 인스턴스는 일부이고, 나머지는 신규 서버 연동과 엔진별 자료 확보가 끝나야 실데이터로 전환됩니다. 그때까지는 리포트에 "이 인스턴스는 담당 목록에는 있지만 아직 수집 전"임을 정직하게 표시하는 편이 낫습니다.
담당자 입장에서는 자기 담당 전체 대수와, 그중 지금 실제로 점검되고 있는 대수를 함께 보게 됩니다. "40대 담당인데 지금 3대만 점검 중이구나"가 한눈에 보이면, 나머지가 언제 붙는지 물어볼 수 있습니다. 아직 안 되는 걸 숨기는 것보다, 어디까지 됐는지 드러내는 게 신뢰를 줍니다.

탐지 결과를 인스턴스에 연결하기

수집·탐지는 설정 파일 기준으로 돌아, 결과가 설정상의 이름(예: mysql)으로 나옵니다. 이걸 매핑상의 인스턴스 id와 연결해야 합니다. 설정에 각 DB의 실제 인스턴스 id가 적혀 있으니, 그걸 다리 삼아 "설정 이름 → 인스턴스 id"로 결과를 옮깁니다.

def _bridge_by_instance(detections, metrics, config):
    """설정으로 수집·탐지된 결과를 매핑상의 인스턴스 id 기준으로 옮긴다."""
    id_by_db = {name: db.get("instance") for name, db in config["databases"].items()}
    det_by_id = {id_by_db[n]: d for n, d in detections.items() if id_by_db.get(n)}
    met_by_id = {id_by_db[n]: m for n, m in metrics.items() if id_by_db.get(n)}
    return det_by_id, met_by_id

이 다리(bridge)를 둔 덕분에, 지금 데이터가 있는 인스턴스는 실제 탐지 결과가 리포트에 들어가고, 나머지는 자연스럽게 '수집 대기'로 빠집니다. 이름표만 갈아 끼우는 얇은 층이라, 나중에 전체 인스턴스를 실제로 수집하게 되면 이 연결 지점만 확장하면 됩니다.

---

6. 일괄 생성과 발송 이력

마지막으로, 수신자 전원을 한 번에 돌리고 이력을 남기는 러너를 만들었습니다. 뒤집어 놓은 담당자 목록을 그냥 순회하면 됩니다.

for email, r in recips.items():
    res = generate_recipient_report(r, det_by_id, met_by_id, cfg, target, out_dir=out_dir)
    fname = f"{target.isoformat()}_{_code(email)}.html"     # 날짜 + 수신자코드
    _save_html(res, os.path.join(out_dir, fname))
    c = _counts(r, det_by_id)                                # 등급별 개수 집계
    rows.append({...})                                       # 이력 인덱스용 한 줄
    if args.send:
        from mailer import send_report
        send_report(res, cfg, target, recipients=[email])   # 실제 발송(옵션)

각 수신자 리포트는 {날짜}_{수신자코드}.html 로 저장합니다. 수신자코드는 이메일의 앞부분(예: kim.example)을 씁니다. 사람 이니셜 같은 걸 쓸까도 고민했지만, 이니셜은 동명이인이 겹칠 수 있어 이메일 앞부분을 식별자로 삼았습니다. 이메일은 유일하니까요. 날짜를 접두로 두어서, 매일 파일이 쌓이면 그 자체가 발송 이력이 됩니다. 폴더를 열면 날짜순으로 "언제 누구에게" 보냈는지가 그대로 남습니다.

그리고 그날 발송 전체를 한눈에 보는 이력 인덱스를 따로 만듭니다. 수신자별로 담당 대수와 위험/주의/정상/대기 개수를 표로 보여주고, 각 행에서 그 사람 리포트로 바로 넘어갈 수 있게 링크를 겁니다.

def build_index(rows, target, path, unique_total, sent):
    """발송 이력 인덱스 HTML — 수신자별 발송 현황 표 + 링크."""
    trs = []
    for r in sorted(rows, key=lambda x: (-x["critical"], -x["warning"], x["name"])):
        trs.append(
            f'<tr ...>'
            f'<td ...><a href="{r["file"]}">{r["name"]}</a></td>'   # 이름 = 리포트 링크
            f'<td ...>{r["roles"]}</td>'
            f'<td ...>{r["email"]}</td>'
            f'<td ...>{r["total"]}</td>'                             # 담당 대수
            f'<td ...>{_n(r["critical"], C_CRIT)}</td>'             # 위험
            f'<td ...>{_n(r["warning"], C_WARN)}</td>'              # 주의
            f'<td ...>{_n(r["normal"], C_OK)}</td>'                 # 정상
            f'<td ...>{r["pending"] or ""}</td>'                    # 수집 대기
            f'<td ...><a href="{r["file"]}">리포트</a></td></tr>')
    # ... 상단 KPI: 수신자 N명(=발송 통수) / 점검 인스턴스 유니크 수 ...

인덱스를 위험 많은 순으로 정렬한 건 의도적입니다(-critical, -warning 순). 발송 이력을 열었을 때 손이 급한 담당자가 위로 오게 하려는 겁니다. 맨 위에는 "수신자 몇 명(=발송 통수)"과 "점검 인스턴스 몇 대(유니크)"를 나란히 두어, 4절에서 정리한 두 지표를 그대로 반영했습니다. 이력 화면만 봐도 "발송은 사람 수, 점검은 인스턴스 수"라는 구분이 눈에 들어옵니다.

---

7. 진행하며 막혔던 것들

몇 가지 실무적인 문제가 있었습니다. 하나씩 풀어 가는 과정이 오히려 설계를 다듬어 줬습니다.
데이터 소스가 개발 환경에서 안 닿음. 현장 연동은 사내망의 모니터링 API를 호출하는데, 개발 환경에서는 그 주소에 닿지 않아 호출이 타임아웃납니다. 실제로 아래 같은 에러가 났습니다.

urllib.error.URLError: <urlopen error [WinError 10060]
  연결된 구성원이 응답을 하지 않아 연결하지 못했습니다 ...>

그래서 개발 검증용으로는 미리 받아 둔 파일 데이터를 읽도록 소스만 바꿔 돌렸습니다. 데이터 소스를 설정 한 줄로 갈아 끼우도록 처음부터 분리해 둔 게 여기서 도움이 됐습니다. 수집 방식이 바뀌어도 나머지 코드는 그대로입니다. 여행용 멀티 어댑터처럼, 콘센트 모양만 갈아 끼우면 기기는 그대로 쓰는 셈입니다.

의존성 환경. 탐지에 쓰는 라이브러리가 시스템 기본 파이썬에는 없어서, 프로젝트 전용 가상환경으로 돌려야 했습니다. 스크립트를 처음 실행할 때 ModuleNotFoundError로 한 번 걸렸습니다. 전용 가상환경의 파이썬으로 실행하니 해결됐습니다.

커버리지가 빠짐. 앞에서 이야기한, 부품만 골라 옮기다 커버리지 카드를 흘린 문제입니다. 결국 본문 전체를 빌더로 떼어 통째 재사용하는 쪽으로 방향을 바꿔 해결했습니다. "일부만 재사용"이 오히려 함정이었고, "전체를 재사용"이 더 안전했습니다.
중복 카운트. 위에서 설명한, 같은 인스턴스가 한 수신자 바구니에 두 번 들어갈 가능성입니다. 실제로 그런 데이터가 있진 않았지만, 회사·협력사 이메일이 우연히 같을 때를 대비해 방어를 넣어 뒀습니다. 이런 방어는 지금 당장 문제가 없어도, 나중에 데이터가 바뀌면 조용히 틀린 숫자를 낼 수 있어 미리 막아 두는 편이 안전합니다.

---

마무리

정리하면, 수백 대 규모의 점검 리포트를 담당자별로 나눠 보내기 위해 다음을 만들었습니다.

• 지저분한 매핑 원본을 표준 한 시트로 정규화하고, 이후에는 그 표준만 읽는 짧은 코드로 단순화. 무거운 코드는 한 번만.
• 인스턴스를 담당자 기준으로 뒤집어(라우팅) 수신자별로 묶고, 한 수신자 안에서는 중복을 방지.
• 발송은 수신자 단위, 점검은 인스턴스 유니크 라는 두 지표를 분리해 카운트 혼동을 제거.
• 담당자 한 명분 리포트를 단일 리포트 본문 렌더러를 서비스별로 통째 재사용해 조립하고(커버리지·오늘의 핵심·전일 대비까지 그대로), 아직 데이터가 없는 인스턴스는 '수집 대기'로 정직하게 표기.
• 수신자 전원을 일괄 생성하고, 날짜별·수신자별 파일과 이력 인덱스로 발송 기록을 남김.

아직 남은 일도 있습니다. 전체 인스턴스를 실제로 수집하려면 엔진별 임계값과 수집 대상 지표를 확보해야 하고, 실제 메일 발송은 사내 메일 서버가 확정돼야 합니다. 다만 라우팅과 리포트 조립, 이력까지의 뼈대는 완성돼서, 남은 건 데이터를 채워 넣는 일입니다. 틀이 서 있으면, 데이터가 붙는 순간 각 서비스가 지금의 샘플처럼 꽉 찬 상세로 채워집니다.
개인적으로 이번 작업에서 가장 오래 남은 교훈은 두 가지였습니다. 하나는 "지저분한 입력은 경계에서 한 번에 정리하라" — 표준으로 바꿔 두면 안쪽 코드가 단순해집니다. 다른 하나는 "일부만 재사용하려다 흘리느니 전체를 재사용하라" — 부품을 골라 옮기는 것보다, 검증된 덩어리를 통째로 다시 쓰는 편이 빠지는 게 없습니다.
기술 스택: Python · openpyxl(엑셀 파싱) · PyYAML(중간 설정). 데이터 소스는 설정 한 줄로 교체 가능하도록 분리, 리포트 렌더링은 단일 리포트 본문 빌더를 담당자 리포트가 서비스별로 재사용.