contexa-core contexa-iam

업무 기록: 판정에 회사 사정 알려 주기

결재 · 티켓 · 담당 · 당직 · 출장 같은 회사 기록을 Contexa에 넣어 두면, 판정은 요청이 평소와 다를 때 그 차이를 설명하는 기록이 있는지 함께 봅니다. 넣을 수 있는 기록, 회사 규칙이 걸리는 요청, 앱이 요청마다 알려 줄 값, 판정이 보는 사실, 넣는 API와 저장 위치를 다룹니다.

한눈에 보기

같은 요청도 회사 사정에 따라 정상일 수도, 위험할 수도 있습니다. 평소 보지 않던 고객 자료 1,000건을 내보내는 요청은 승인된 결재가 있으면 설명되지만, 없으면 의심스럽습니다. 업무 기록은 이런 판단에 필요한 회사 사정을 Contexa에 알려 주는 방법입니다.

업무 기록은 판정을 정하지 않습니다. Contexa는 요청과 기록을 맞대어 본 사실(어떤 결재가 가장 가깝고 어떤 조건이 맞지 않는지 등)과 회사 규칙에 따른 회사의 자체 판단만 적습니다. 그 사실을 보고 허용 · 추가 인증 · 차단을 고르는 것은 AI 모델입니다.

업무 기록이 판정에 닿기까지기록은 미리 넣어 두고, 요청이 올 때마다 그 사람의 기록과 맞대어 봅니다.
  1. 기록 넣기회사 연동이나 관리자가 관리 API로 넣습니다. 앱이 저장소를 직접 둘 수도 있습니다
  2. 규칙이 걸리는 요청행위 · 자원 분류가 회사 규칙에 맞는 요청만 봅니다
  3. 기록과 맞대어 보기요청한 사람(에이전트라면 책임자)의 결재 · 티켓 · 담당 · 당직 · 출장을 요청 시각 기준으로 봅니다
  4. 판정맞대어 본 사실이 판정 프롬프트에 실리고, AI 모델이 대응을 고릅니다

업무 기록은 기본으로 켜져 있지만, 회사 규칙(policies)과 사람 기록(people)을 넣기 전에는 아무 일도 하지 않습니다.

넣을 수 있는 기록

기록은 한 번에 여러 종류를 묶어 JSON 하나로 넣습니다. 칸 이름은 아래 표의 JSON 칸입니다.

종류(JSON 칸)뜻주요 값
PERSON(people)Contexa가 아는 사람. 사람 기록이 없는 사람의 요청은 보지 않습니다.subject(Contexa의 사용자 ID), companyId(회사 시스템이 그 사람을 부르는 ID, 결재자 비교에 씀), displayName
ASSIGNMENT(assignments)대상의 담당자subject, target, responsibility(ACCOUNT_MANAGER이면 고객 담당자), from · until(날짜, 양 끝 포함, 비우면 끝 없음)
APPROVAL(approvals)대상 작업의 결재id, subject, approver, target, purpose, actions(비우면 모든 행위), maxItems, status, validFrom · validUntil, decidedAt, usageReported, recordedBy · recordedAt
TICKET(tickets)티켓 시스템의 티켓id, subject, kind(CHANGE · INCIDENT 등), approver, target, purpose, actions, status, validFrom · validUntil, recordedBy · recordedAt
ON_CALL(onCall)당직id, subject, team, startsAt(포함) · endsAt(제외)
TRAVEL(travel)등록된 출장과 그동안 쓰는 네트워크id, subject, city, country, network(CIDR), validFrom · validUntil
ACCESS_HISTORY(accessDays)그 사람이 대상에서 일한 날subject, target, day
USAGE(usage)앱이 그 사람에게 대상에서 내준 건수(내보내기 · 다운로드)id, subject, target, items, at
POLICY(policies)회사 규칙(아래)id, statement, requirement, actions, categories, exceptions 등
NETWORK(networks)회사 네트워크와 그 구역cidr, zone(CORPORATE · VPN · PARTNER 등)
SOURCE(sources)기록 없이 "이 종류는 연동한다"고만 밝힘종류 이름 목록(예: ["TICKET", "ON_CALL"])
  • 유효한 상태. 결재는 status가 APPROVED · GRANTED · COMPLETED일 때, 티켓은 OPEN · APPROVED · ACTIVE · IN_PROGRESS일 때 요청을 덮습니다. status를 비우면 상태는 따지지 않습니다.
  • 이미 쓴 건수. 결재의 usageReported가 true이면 앱이 usage로 알린 건수를 그 결재에서 이미 쓴 양으로 셉니다. false나 빈 값이면 이미 쓴 양은 "알 수 없음"입니다.
  • 대상(target)은 회사 기록이 대상을 부르는 키입니다(예: 프로젝트 HX-310). 요청이 어떤 대상인지는 앱이 요청마다 알려 줍니다(아래).

"찾았지만 없음"과 "찾아보지 않음"

ASSIGNMENT · APPROVAL · TICKET · ON_CALL · TRAVEL · ACCESS_HISTORY 여섯 종류는 회사가 그 종류를 연동하는지를 구분합니다.

  • 연동한 종류에 그 사람의 기록이 없으면 판정에는 "찾았지만 없음"으로 실립니다. 예: 티켓을 연동했는데 맞는 티켓이 없음.
  • 연동하지 않은 종류는 "찾아보지 않음"으로 남습니다. 없다는 뜻이 아니므로 판정에서 불리한 사실이 되지 않습니다.
  • 어느 종류든 기록을 한 건이라도 넣으면 그 종류는 연동한 것으로 칩니다. 아직 기록은 없지만 연동한다고 알리려면 sources에 종류 이름을 넣습니다.

회사 규칙: 어떤 요청을 보나

업무 기록은 회사 규칙이 걸리는 요청만 봅니다. 규칙은 "어떤 요청에 무엇이 있어야 하는가"를 적은 기록입니다.

칸뜻비웠을 때
id규칙 ID필수
statement규칙 문장. 판정 프롬프트에 그대로 실립니다없음
requirement요청을 덮어야 하는 기록: APPROVAL(결재) 또는 TICKET(티켓)없음
requiredTicketKind필요한 티켓 종류(예: CHANGE)아무 종류
actions규칙이 걸리는 행위모든 행위
categories규칙이 걸리는 자원 분류(@Protectable(category = ...))모든 분류
exceptions덮는 기록이 없어도 되는 경우(아래). {"kind": "...", "limit": 숫자}예외 없음
records요청과 맞대어 볼 기록 종류requirement · exceptions가 가리키는 종류와 TRAVEL
historyDays판정에 보여 줄 작업 기록(일한 날)의 기간(일)RECENT_WORK의 limit, 그것도 없으면 90일

요청 하나를 보는 조건은 셋입니다. 하나라도 빠지면 그 요청에는 업무 기록이 실리지 않습니다.

  1. 요청의 행위와 자원 분류가 맞는 규칙이 하나 이상 있습니다.
  2. 기록의 주인(아래)이 사람 기록(people)에 있습니다.
  3. 요청 시각을 압니다. 모르면 "요청 시각을 몰라 찾아보지 않았다"는 요약만 실립니다.

규칙의 예외와 회사의 자체 판단

예외(kind)성립하는 때limit
ASSIGNED요청 날짜에 그 대상의 담당자(고객 담당 아님)입니다요청 건수가 이 수 이하일 때만. 건수를 모르면 성립하지 않습니다
ACCOUNT_MANAGER요청이 가리키는 고객(주소의 변수 값) 또는 대상의 고객 담당자입니다쓰지 않음
RECENT_WORK최근 그 대상에서 일한 날이 있습니다며칠 안을 볼지(없으면 historyDays, 그것도 없으면 90일)
TICKET_WHILE_ON_CALL당직 중이고, 조건이 모두 맞는 티켓이 있습니다쓰지 않음

Contexa는 규칙마다 회사의 자체 판단을 적습니다. 예외가 하나라도 성립하면 "덮는 기록이 필요 없음", 하나도 성립하지 않으면 "필요함", 연동하지 않은 종류 때문에 성립 여부를 알 수 없는 예외가 있으면 "모름"입니다. 이 판단도 사실 가운데 하나일 뿐, 대응은 모델이 고릅니다.

앱이 요청마다 알려 줄 값

기록은 회사가 쓰는 키로 대상을 부르지만, 요청 주소만으로는 그 키를 알 수 없습니다. Contexa는 요청의 글을 보고 대상을 짐작하지 않습니다. 앱이 요청 속성으로 알려 줍니다.

요청 속성형식쓰임
resourceScope이름=값(예: projectKey=HX-310). 이름은 영문자로 시작하는 영숫자 · _ 64자 이하, 값은 영숫자와 . _ : -로 128자 이하. 형식이 맞지 않으면 버립니다요청의 대상. 값(HX-310)을 기록의 target과 비교합니다. 없으면 대상이 필요한 비교(담당 · 결재 · 티켓 · 일한 날)를 하지 않습니다
requestItems숫자요청이 다루는 건수. 결재의 maxItems, ASSIGNED의 limit와 비교합니다
claimedRecord티켓 키요청자가 "이 티켓이 근거"라고 내민 키. 근거로 믿지 않고, 그 사람의 티켓에 정말 있는지와 조건이 맞는지를 확인해 적습니다
// 컨트롤러나 필터에서, 보호하는 메서드를 부르기 전에
request.setAttribute("resourceScope", "projectKey=" + project.getKey());
request.setAttribute("requestItems", rows.size());
request.setAttribute("claimedRecord", form.getTicketKey()); // 요청자가 적은 티켓 키(있을 때만)

행위와 자원 분류는 @Protectable(actions = ..., category = ...)로 밝힙니다(@Protectable). 행위를 밝히지 않으면 Contexa가 요청에서 추정한 행위 계열(READ · WRITE · EXPORT · DELETE · ADMIN · EXECUTE)로 규칙을 맞춥니다.

누구의 기록을 보나

  • 사람이 직접 한 요청은 그 사람의 기록을 봅니다.
  • 에이전트의 요청은 책임자의 기록을 봅니다. 위임받은 에이전트는 위임자, 스스로 일하는 에이전트는 등록된 후원자입니다. 에이전트에게는 담당 · 당직 · 티켓이 따로 없기 때문입니다. 판정 프롬프트에는 누구의 기록인지(본인 · 위임자 · 후원자)가 함께 실립니다(에이전트를 보안 주체로).
  • 테넌트. 그 사람의 기록은 요청 테넌트의 기록과 테넌트 없이 넣은(배포 공용) 기록을 함께 봅니다. 규칙과 네트워크는 테넌트의 것이 있으면 그것만, 없으면 공용의 것을 씁니다.

판정이 보는 것

규칙이 걸린 요청에는 다음 사실이 판정 프롬프트에 실립니다.

사실내용
걸린 규칙규칙 문장, 필요한 기록, 예외, 회사의 자체 판단(필요함 · 필요 없음 · 모름)
가장 가까운 결재 · 티켓그 사람의 결재 · 티켓 가운데 요청을 가장 잘 덮는 것과 맞지 않는 조건: APPROVER(본인이 결재), TARGET(다른 대상), PURPOSE(다른 행위), ITEMS(건수 초과, 결재만), VALIDITY(기간 밖), STATUS(유효한 상태 아님)
요청자가 내민 티켓그런 티켓이 있는지(없으면 NO_TICKET), 있으면 위와 같은 조건 확인
담당 · 작업 기록 · 당직요청 날짜의 담당(또는 고객 담당) 여부, 최근 그 대상에서 일한 날, 요청 시각의 당직 여부
네트워크 구역요청 주소가 속한 회사 네트워크의 구역, 출장 네트워크(TRAVEL), 그 밖(EXTERNAL, 회사 네트워크를 넣었을 때만)
요청 시각 기준 계산엔진이 다시 계산합니다: 결재가 요청보다 먼저 결정되었는지, 기간 안인지, 건수 한도를 이번 요청만으로 또는 같은 세션에서 이미 내보낸 것과 합쳐 넘는지, 규칙이 기록이나 예외로 지켜졌는지

실리는 자리는 프롬프트 버전에 따라 다릅니다(판정 프롬프트).

버전자리
모든 버전RECORDS AND COMPARISONS 블록. 엔진의 결론은 빼고 기록과 비교만 싣고, 지시문이 모델에게 "평소와 다른 점마다 그 차이를 대상 · 목적 · 기간 · 한도 · 결정 시각으로 설명하는 기록이 있는지, 요청 시각에 규칙이 지켜졌는지"를 직접 확인하라고 합니다
준비된 부분 "판정 규칙"을 넣은 버전같은 블록에 엔진의 결론 줄 DeviationsExplained(차이마다 설명되지 않음 또는 그 차이를 덮는 기록) · PolicySatisfied(규칙이 지켜졌는지와 이유)가 더 실립니다

기록 넣기: 관리 API

모든 API는 ADMIN 역할이 필요합니다. 기록을 넣거나 지울 때마다 누가 무엇을 했는지 감사 로그에 남습니다(COMPANY_RECORDS_RECORDED · COMPANY_RECORDS_DELETED).

요청하는 일응답
POST /contexa/admin/api/company-records?tenantId=...기록 넣기. 본문은 위 종류들을 담은 JSON. 한 번에 최대 20,000건. 같은 종류 · 같은 키의 기록은 바꿔 씁니다{"records": 넣은 수, "integratedKinds": [...]}
GET /contexa/admin/api/company-records기록 보기. tenantId · kind · subject · target로 거르고, 최근에 넣은 것부터 limit건(기본 200, 최대 1,000)기록 목록(종류 · 키 · 사람 · 대상 · 내용 · 넣은 사람 · 넣은 시각)
POST /contexa/admin/api/company-records/delete키로 지우기. 본문 {"tenantId": ..., "kind": "TICKET", "keys": ["CHG-1042"]}{"removed": 지운 수}

tenantId를 비우면 배포 공용 기록입니다. 필수 값이 빠지거나 기간이 거꾸로인 기록이 하나라도 있으면 아무것도 넣지 않고 400과 문제 목록(problems)을 돌려줍니다.

{
  "people": [
    { "subject": "alice", "companyId": "E1024", "displayName": "Alice Kim" }
  ],
  "assignments": [
    { "subject": "alice", "target": "HX-310", "from": "2026-10-01" }
  ],
  "approvals": [{
    "id": "APR-7781", "subject": "alice", "approver": "E2001", "target": "HX-310",
    "purpose": "분기 감사 자료", "actions": ["EXPORT"], "maxItems": 1000, "status": "APPROVED",
    "validFrom": "2026-11-01T00:00:00Z", "validUntil": "2026-11-08T00:00:00Z",
    "decidedAt": "2026-10-31T09:12:00Z", "usageReported": true
  }],
  "policies": [{
    "id": "EXPORT-NEEDS-APPROVAL", "statement": "고객 자료를 내보내려면 결재가 있어야 한다",
    "requirement": "APPROVAL", "actions": ["EXPORT"], "categories": ["customer-data"],
    "exceptions": [{ "kind": "ASSIGNED", "limit": 100 }]
  }],
  "networks": [
    { "cidr": "10.0.0.0/8", "zone": "CORPORATE" }
  ]
}

이 예에서 @Protectable(actions = "EXPORT", category = "customer-data")로 보호한 메서드로 alice가 projectKey=HX-310인 고객 자료 1,000건을 11월 3일 사내망에서 내보내면, 규칙 EXPORT-NEEDS-APPROVAL이 걸립니다. 담당자이지만 건수가 예외 한도(100)를 넘으므로 회사의 자체 판단은 "결재 필요"이고, 결재 APR-7781은 대상 · 행위 · 건수 · 기간 · 상태가 모두 맞는 기록으로 실립니다.

관리 콘솔의 보안 → 업무 기록(/contexa/admin/company-records)에서 넣은 기록을 종류 · 사람 · 대상 · 테넌트로 걸러 최근 200건까지 볼 수 있습니다. 화면은 보기만 하고 아무것도 판단하지 않습니다(관리 콘솔).

각 종류의 키: 사람은 subject, 담당은 subject · target · responsibility · from의 조합, 일한 날은 subject · target · day의 조합, 사용량은 id(없으면 subject · target · at), 네트워크는 cidr, 나머지는 id입니다.

기록이 저장되는 곳

  • Contexa DB가 있으면 ctxa_company_record 표에 저장합니다(contexa-iam). 없으면 메모리에 두므로 재시작하면 사라집니다.
  • 회사 기록이 다른 곳에 있으면 CompanyRecordStore 빈을 직접 선언합니다. 그러면 기본 저장소 대신 그 빈을 씁니다. 메서드는 넣기(put), 지우기(delete), 사람의 기록(ofSubject), 회사의 규칙 · 네트워크(company), 목록(list), 사람의 기록 모두 지우기(deleteSubject)입니다.
  • 계정을 지우면 그 사람의 업무 기록도 모든 테넌트에서 함께 지웁니다.
  • 앱이 FrictionContextProvider 빈을 따로 두면, 업무 기록과 나란히 돌며 같은 맥락에 앱의 기록을 더 보탤 수 있습니다.

기록이 정말 쓰였는지 확인하기

프롬프트 검수의 SOURCE_TRUTH 검사는 봉인된 판정마다 업무 기록과 위임 기록을 저장소에서 요청 시각 기준으로 다시 읽어, 프롬프트에 실린 당직 · 담당 · 결재(결재자, 건수 한도, 이미 쓴 건수) · 위임 줄이 기록과 맞는지 봅니다. 계정이 지워져 기록이 없으면 "보관하지 않음"으로 보고합니다(프롬프트 검수와 재생).

다음에 읽을 곳