원장 분류 태그
원장 내역에 브랜드 등 분류 태그를 붙이고, 태그 기준으로 타임라인을 봅니다.
원장 분류 태그
한 기업이 여러 브랜드를 운영할 때, 기업 계정을 쪼개지 않고 내역만 갈라 보기 위한 라벨입니다.
태그는 잔액 계산 규칙을 바꾸지 않습니다. DB 에 저장된 balanceAfter 는 기업 전체 기준
그대로이고, 태그별 잔액은 조회할 때 그 태그 행들만 모아 계산한 파생값입니다.
태그는 자유 문자열이고 한 행에 하나만 붙습니다. 등록 절차가 없어 아무 이름이나 쓸 수 있으므로, 화면 드롭다운은 아래 목록 조회로 채워 표기 흔들림을 줄이세요.
태그 부여 · 해제
PUT /ai/admin/finance/ledger/tags?adminId={adminId}
Authorization: Bearer {access_token}
Content-Type: application/json{ "txIds": [619, 620, 621], "tag": "브랜드A" }| 파라미터 | 위치 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
txIds | body | Long[] | 예 | 태그를 적용할 원장 행 id 목록 |
tag | body | String | 아니오 | 붙일 태그. null 이나 공백이면 해제. 최대 60자, 앞뒤 공백은 잘라 저장 |
adminId | query | String | 아니오 | 처리자 ID |
txIds 는 모두 같은 기업의 행이어야 합니다. 섞여 있으면 400 입니다. 태그가 기업을
넘나들면 집계가 무의미해집니다.
응답 (200 OK)
{
"status": 200,
"message": "태그 적용 완료",
"data": {
"businessAccountId": 418,
"tag": "브랜드A",
"updatedCount": 2,
"unchangedCount": 1
}
}| 필드 | 설명 |
|---|---|
tag | 적용한 태그. 해제면 null |
updatedCount | 실제로 값이 바뀐 행 수 |
unchangedCount | 이미 같은 태그라 손대지 않은 행 수 |
에러
| 상태 코드 | 설명 |
|---|---|
400 | txIds 가 비었거나, 서로 다른 기업의 행이 섞였거나, 태그가 60자 초과 |
404 | 존재하지 않는 행 id 가 섞임 |
태그 목록 조회
GET /ai/admin/finance/ledger/business/{businessAccountId}/tags이 기업 원장에 실제로 붙어 있는 태그를 많이 쓰인 순, 같으면 이름순으로 돌려줍니다. 소프트 삭제된 행은 세지 않습니다.
{
"status": 200,
"message": "태그 목록 조회 완료",
"data": [
{ "tag": "브랜드A", "count": 42 },
{ "tag": "브랜드B", "count": 17 }
]
}태그 기준으로 타임라인 보기
별도 조회 API 를 만들지 않았습니다. 기존 기업 상세에 tag 쿼리 파라미터만 더하면 됩니다.
응답 형태가 같아 화면에서 탭만 바꿔 끼울 수 있습니다.
GET /ai/admin/finance/business/{businessAccountId} # 전체 (지금과 동일)
GET /ai/admin/finance/business/{businessAccountId}?tag=브랜드A # 태그 기준tag 를 주면 두 가지가 달라집니다.
globalTimeline이 그 태그가 붙은 행으로 좁혀집니다- 각 행의
balanceAfter가 그 태그 안에서 0 부터 누적한 값으로 바뀝니다
그리고 응답에 태그 합계 네 필드가 채워집니다. tag 없이 조회하면 모두 null 입니다.
| 필드 | 설명 |
|---|---|
tag | 적용된 태그 |
tagInflow | 이 태그의 유입 합 (양수 금액의 합) |
tagOutflow | 이 태그의 유출 합 (음수 금액의 절대값 합) |
tagNetBalance | 순액 = tagInflow - tagOutflow. 타임라인 마지막 행의 balanceAfter 와 같음 |
계산 규칙
전체 원장과 같습니다 — occurredAt ASC, id ASC 정렬, 소프트 삭제 행 제외,
BUDGET_ADJUST 합산 제외. 다른 것은 시작값이 이월분이 아니라 0 이라는 점뿐입니다.
태그별 순액을 다 더해도 기업 전체 잔액과 맞지 않습니다. 미분류 행이 빠지고, 원장 도입 이전 이월분도 들어가지 않기 때문입니다. 정의상 그런 것이지 오류가 아니니 화면에서 검산 경고를 띄우지 마세요.
충전 행에도 태그를 달아야 의미가 있습니다. 지출만 태그하면 그 브랜드 잔액이 계속 마이너스로 보입니다.
미분류 행
태그가 없는 행은 전체 타임라인에서만 보입니다. 태그 조회는 태그가 붙은 행만 대상입니다.
전체 타임라인의 각 행에도 tag 필드가 내려가므로, 화면에서 비어 있는 것을 골라 태그를
붙이면 됩니다.