관리자 상태 기록 보존 정책을 API 안에서 하루 한 번 실행한다

소유자가 2026-10-27 실제 적용과 정기 실행을 승인했다. 원본 90일·집계 365일·
집계 대상 7일 창은 2026-10-20 운영 dry-run과 같은 값으로 고정하고, 데이터를
지우는 작업이라 기본값은 꺼짐이다. DB 풀이 정상일 때만 예약하며 실패는 기록만
하고 다음 회차를 계속한다. NAS compose는 환경변수를 명시 전달하므로 설정 3개를
api 환경에 추가한다.
This commit is contained in:
Yun Chan 2026-10-27 11:20:44 +09:00
parent 8d6201e19e
commit b6de32c1dd
6 changed files with 210 additions and 0 deletions

View file

@ -341,6 +341,23 @@ class Settings(BaseSettings):
le=300.0,
validation_alias="VIGNETTE_SUPERVISION_RESEARCH_PRODUCER_STARTUP_DELAY_SECONDS",
)
# 관리자 헬스 표본 보존 정책은 데이터를 삭제하므로 기본값은 꺼짐이며,
# 운영 env에서만 명시적으로 켠다.
admin_health_retention_enabled: bool = Field(
default=False,
validation_alias="VIGNETTE_ADMIN_HEALTH_RETENTION_ENABLED",
)
admin_health_retention_interval_seconds: float = Field(
default=86400.0,
ge=3600.0,
validation_alias="VIGNETTE_ADMIN_HEALTH_RETENTION_INTERVAL_SECONDS",
)
admin_health_retention_startup_delay_seconds: float = Field(
default=300.0,
ge=0.0,
le=3600.0,
validation_alias="VIGNETTE_ADMIN_HEALTH_RETENTION_STARTUP_DELAY_SECONDS",
)
# G8 automation qualification is research-only and independently revocable;
# no development token is synthesized when the setting is absent.
continuous_improvement_internal_token: SecretStr = Field(

View file

@ -60,6 +60,7 @@ from .routes import voice as voice_routes
from .services.notifications import ensure_notification_tables
from .services.protocol_registry import ensure_protocol_tables
from .services import (
admin_health_maintenance,
alliance_measurement,
continuous_improvement_producer,
supervision_research_producer,
@ -84,6 +85,7 @@ async def lifespan(app: FastAPI):
DB 미가용(Docker off / NAS 연결불가)이면 store 인메모리 폴백으로 degraded 기동한다.
"""
db_pool_ready = False
measurement_schema_ready = False
outcome_trajectory_schema_ready = False
rupture_repair_schema_ready = False
@ -229,6 +231,7 @@ async def lifespan(app: FastAPI):
if settings.auto_seed_personas:
await materialize_seed_personas()
await admin_routes.apply_engine_config_from_store()
db_pool_ready = True
except Exception as exc: # DB 없어도 store 폴백으로 1턴 동작 (dev/로컬)
if settings.environment != "dev" or upload_manifest_proof is not None:
raise
@ -254,11 +257,14 @@ async def lifespan(app: FastAPI):
supervision_research_producer.schedule_supervision_research_producer()
if continuous_improvement_schema_ready:
continuous_improvement_producer.schedule_continuous_improvement_producer()
if db_pool_ready:
admin_health_maintenance.schedule_admin_health_retention()
try:
yield
finally:
await continuous_improvement_producer.stop_continuous_improvement_producer()
await supervision_research_producer.stop_supervision_research_producer()
await admin_health_maintenance.stop_admin_health_retention()
session_routes.cancel_missing_session_evaluation_recovery()
await voice_service.shutdown()
await jev_client.shutdown()

View file

@ -2,11 +2,23 @@
from __future__ import annotations
import asyncio
from dataclasses import dataclass
import logging
import re
from ..config import settings
from ..db import acquire
# 2026-10-20 운영 dry-run과 같은 값으로 소유자가 승인한 고정 보존 창이다.
# 설정으로 노출하지 않는다.
_RETENTION_ROLLUP_DAYS = 7
_RETENTION_RETENTION_DAYS = 90
_RETENTION_ROLLUP_RETENTION_DAYS = 365
_RETENTION_TASK: asyncio.Task[None] | None = None
logger = logging.getLogger(__name__)
@dataclass(frozen=True)
class AdminHealthMaintenanceResult:
@ -266,3 +278,55 @@ async def maintain_admin_health_events(
prunable_rollup_count=_row_int(rollup_prune_stats, "rollup_count"),
deleted_rollups=deleted_rollups,
)
async def _retention_loop() -> None:
delay = settings.admin_health_retention_startup_delay_seconds
if delay:
await asyncio.sleep(delay)
while True:
try:
result = await maintain_admin_health_events(
rollup_days=_RETENTION_ROLLUP_DAYS,
retention_days=_RETENTION_RETENTION_DAYS,
rollup_retention_days=_RETENTION_ROLLUP_RETENTION_DAYS,
apply=True,
)
logger.info(
"관리자 헬스 보존 정책 적용 완료: deleted_events=%d deleted_rollups=%d "
"upserted_rollups=%d",
result.deleted_events,
result.deleted_rollups,
result.upserted_rollups,
)
except asyncio.CancelledError:
raise
except Exception:
logger.exception("관리자 헬스 보존 정책 scheduler cycle 실패")
await asyncio.sleep(settings.admin_health_retention_interval_seconds)
def schedule_admin_health_retention() -> asyncio.Task[None] | None:
global _RETENTION_TASK
if not settings.admin_health_retention_enabled:
return None
if _RETENTION_TASK is not None and not _RETENTION_TASK.done():
return _RETENTION_TASK
_RETENTION_TASK = asyncio.create_task(
_retention_loop(),
name="admin-health-retention",
)
return _RETENTION_TASK
async def stop_admin_health_retention() -> None:
global _RETENTION_TASK
task = _RETENTION_TASK
_RETENTION_TASK = None
if task is None or task.done():
return
task.cancel()
try:
await task
except asyncio.CancelledError:
pass

View file

@ -0,0 +1,114 @@
"""관리자 헬스 표본 보존 정책 일일 자동 실행 스케줄러 테스트.
실제 DB 접속이나 real-time sleep 없이 `_retention_loop` / `schedule_admin_health_retention` /
`stop_admin_health_retention`의 동작을 검증한다.
"""
from __future__ import annotations
import asyncio
from unittest import IsolatedAsyncioTestCase
from unittest.mock import AsyncMock, patch
from .services import admin_health_maintenance as maintenance
def _result(
*, deleted_events: int = 0, deleted_rollups: int = 0, upserted_rollups: int = 0
) -> maintenance.AdminHealthMaintenanceResult:
return maintenance.AdminHealthMaintenanceResult(
applied=True,
rollup_days=7,
retention_days=90,
rollup_retention_days=365,
rollup_event_count=0,
rollup_bucket_count=0,
upserted_rollups=upserted_rollups,
prunable_event_count=0,
deleted_events=deleted_events,
prunable_rollup_count=0,
deleted_rollups=deleted_rollups,
)
class AdminHealthRetentionSchedulerTest(IsolatedAsyncioTestCase):
async def test_schedule_returns_none_when_disabled_by_default(self) -> None:
# 데이터를 지우는 작업이라 설정 기본값 자체가 꺼짐이어야 한다.
self.assertIs(
type(maintenance.settings).model_fields["admin_health_retention_enabled"].default,
False,
)
with patch.object(
maintenance.settings,
"admin_health_retention_enabled",
False,
):
self.assertIsNone(maintenance.schedule_admin_health_retention())
async def test_loop_applies_maintenance_with_fixed_retention_windows(self) -> None:
maintain = AsyncMock(return_value=_result())
with (
patch.object(maintenance.settings, "admin_health_retention_enabled", True),
patch.object(
maintenance.settings, "admin_health_retention_startup_delay_seconds", 0.0
),
patch.object(maintenance, "maintain_admin_health_events", maintain),
patch.object(
maintenance.asyncio,
"sleep",
AsyncMock(side_effect=asyncio.CancelledError()),
),
):
with self.assertRaises(asyncio.CancelledError):
await maintenance._retention_loop()
maintain.assert_awaited_once_with(
rollup_days=7,
retention_days=90,
rollup_retention_days=365,
apply=True,
)
async def test_loop_continues_after_maintenance_failure(self) -> None:
maintain = AsyncMock(side_effect=[RuntimeError("boom"), _result()])
sleep = AsyncMock(side_effect=[None, asyncio.CancelledError()])
with (
patch.object(maintenance.settings, "admin_health_retention_enabled", True),
patch.object(
maintenance.settings, "admin_health_retention_startup_delay_seconds", 0.0
),
patch.object(maintenance, "maintain_admin_health_events", maintain),
patch.object(maintenance.asyncio, "sleep", sleep),
):
with self.assertRaises(asyncio.CancelledError):
await maintenance._retention_loop()
self.assertEqual(maintain.await_count, 2)
self.assertEqual(sleep.await_count, 2)
async def test_stop_cancels_and_clears_scheduled_task(self) -> None:
maintain = AsyncMock(return_value=_result())
with (
patch.object(maintenance.settings, "admin_health_retention_enabled", True),
patch.object(
maintenance.settings, "admin_health_retention_startup_delay_seconds", 0.0
),
patch.object(
maintenance.settings, "admin_health_retention_interval_seconds", 0.01
),
patch.object(maintenance, "maintain_admin_health_events", maintain),
):
task = maintenance.schedule_admin_health_retention()
self.assertIsNotNone(task)
await asyncio.sleep(0.05)
await maintenance.stop_admin_health_retention()
self.assertTrue(task.cancelled() or task.done())
self.assertIsNone(maintenance._RETENTION_TASK)
maintain.assert_awaited()
if __name__ == "__main__":
import unittest
unittest.main()

View file

@ -31,6 +31,11 @@ VIGNETTE_CONTINUOUS_IMPROVEMENT_ROLLBACK_EXECUTOR_ENABLED=false
VIGNETTE_CONTINUOUS_IMPROVEMENT_ROLLBACK_EXECUTOR_ENDPOINT=
VIGNETTE_CONTINUOUS_IMPROVEMENT_ROLLBACK_EXECUTOR_TOKEN=
VIGNETTE_CONTINUOUS_IMPROVEMENT_ROLLBACK_EXECUTOR_TIMEOUT_SECONDS=30
# 관리자 헬스 표본 보존 정책 일일 자동 실행. 데이터를 삭제하므로 운영에서만
# 명시적으로 켠다.
VIGNETTE_ADMIN_HEALTH_RETENTION_ENABLED=false
VIGNETTE_ADMIN_HEALTH_RETENTION_INTERVAL_SECONDS=86400
VIGNETTE_ADMIN_HEALTH_RETENTION_STARTUP_DELAY_SECONDS=300
AUTH_ALLOWED_EMAIL_DOMAINS=["hs.ac.kr","twentyoz.kr"]
AUTH_TEACHER_EMAILS=[]
AUTH_ADMIN_EMAILS=[]

View file

@ -183,6 +183,10 @@ services:
VIGNETTE_CONTINUOUS_IMPROVEMENT_PRODUCER_STARTUP_DELAY_SECONDS: ${VIGNETTE_CONTINUOUS_IMPROVEMENT_PRODUCER_STARTUP_DELAY_SECONDS:-30}
VIGNETTE_CONTINUOUS_IMPROVEMENT_PRODUCER_RETRY_DELAY_SECONDS: ${VIGNETTE_CONTINUOUS_IMPROVEMENT_PRODUCER_RETRY_DELAY_SECONDS:-300}
VIGNETTE_CONTINUOUS_IMPROVEMENT_PRODUCER_LEASE_TIMEOUT_SECONDS: ${VIGNETTE_CONTINUOUS_IMPROVEMENT_PRODUCER_LEASE_TIMEOUT_SECONDS:-1800}
# 관리자 헬스 표본 보존 정책(원본 90일·집계 365일) 일일 실행. 2026-10-27 소유자 승인, env.nas에서만 켠다.
VIGNETTE_ADMIN_HEALTH_RETENTION_ENABLED: ${VIGNETTE_ADMIN_HEALTH_RETENTION_ENABLED:-false}
VIGNETTE_ADMIN_HEALTH_RETENTION_INTERVAL_SECONDS: ${VIGNETTE_ADMIN_HEALTH_RETENTION_INTERVAL_SECONDS:-86400}
VIGNETTE_ADMIN_HEALTH_RETENTION_STARTUP_DELAY_SECONDS: ${VIGNETTE_ADMIN_HEALTH_RETENTION_STARTUP_DELAY_SECONDS:-300}
VIGNETTE_CONTINUOUS_IMPROVEMENT_PRODUCER_ENGINE_TIMEOUT_SECONDS: ${VIGNETTE_CONTINUOUS_IMPROVEMENT_PRODUCER_ENGINE_TIMEOUT_SECONDS:-300}
VIGNETTE_CONTINUOUS_IMPROVEMENT_PRODUCER_BATCH_SIZE: ${VIGNETTE_CONTINUOUS_IMPROVEMENT_PRODUCER_BATCH_SIZE:-1}
VIGNETTE_CONTINUOUS_IMPROVEMENT_DRIFT_TRIGGER_ENABLED: ${VIGNETTE_CONTINUOUS_IMPROVEMENT_DRIFT_TRIGGER_ENABLED:-false}