From b6de32c1dd0824fc093377885f2f63a50a855cf7 Mon Sep 17 00:00:00 2001 From: Yun Chan Date: Tue, 27 Oct 2026 11:20:44 +0900 Subject: [PATCH] =?UTF-8?q?=EA=B4=80=EB=A6=AC=EC=9E=90=20=EC=83=81?= =?UTF-8?q?=ED=83=9C=20=EA=B8=B0=EB=A1=9D=20=EB=B3=B4=EC=A1=B4=20=EC=A0=95?= =?UTF-8?q?=EC=B1=85=EC=9D=84=20API=20=EC=95=88=EC=97=90=EC=84=9C=20?= =?UTF-8?q?=ED=95=98=EB=A3=A8=20=ED=95=9C=20=EB=B2=88=20=EC=8B=A4=ED=96=89?= =?UTF-8?q?=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 소유자가 2026-10-27 실제 적용과 정기 실행을 승인했다. 원본 90일·집계 365일· 집계 대상 7일 창은 2026-10-20 운영 dry-run과 같은 값으로 고정하고, 데이터를 지우는 작업이라 기본값은 꺼짐이다. DB 풀이 정상일 때만 예약하며 실패는 기록만 하고 다음 회차를 계속한다. NAS compose는 환경변수를 명시 전달하므로 설정 3개를 api 환경에 추가한다. --- apps/api/app/config.py | 17 +++ apps/api/app/main.py | 6 + .../app/services/admin_health_maintenance.py | 64 ++++++++++ .../test_admin_health_retention_scheduler.py | 114 ++++++++++++++++++ infra/.env.example | 5 + infra/docker-compose.nas.yml | 4 + 6 files changed, 210 insertions(+) create mode 100644 apps/api/app/test_admin_health_retention_scheduler.py diff --git a/apps/api/app/config.py b/apps/api/app/config.py index 3ab0727..e70a65e 100644 --- a/apps/api/app/config.py +++ b/apps/api/app/config.py @@ -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( diff --git a/apps/api/app/main.py b/apps/api/app/main.py index 1cc30ea..fda610a 100644 --- a/apps/api/app/main.py +++ b/apps/api/app/main.py @@ -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() diff --git a/apps/api/app/services/admin_health_maintenance.py b/apps/api/app/services/admin_health_maintenance.py index 832ff29..9bd4646 100644 --- a/apps/api/app/services/admin_health_maintenance.py +++ b/apps/api/app/services/admin_health_maintenance.py @@ -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 diff --git a/apps/api/app/test_admin_health_retention_scheduler.py b/apps/api/app/test_admin_health_retention_scheduler.py new file mode 100644 index 0000000..288d575 --- /dev/null +++ b/apps/api/app/test_admin_health_retention_scheduler.py @@ -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() diff --git a/infra/.env.example b/infra/.env.example index f2c40c7..be15f9c 100644 --- a/infra/.env.example +++ b/infra/.env.example @@ -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=[] diff --git a/infra/docker-compose.nas.yml b/infra/docker-compose.nas.yml index f74823f..629a4b5 100644 --- a/infra/docker-compose.nas.yml +++ b/infra/docker-compose.nas.yml @@ -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}