busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

semantics

Browse Source
This commit is contained in:
busya
2026-03-27 21:27:31 +03:00
parent 7c85552132
commit 2ed66bfebc
182 changed files with 21186 additions and 10254 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
specs/026-dashboard-health-windows/contracts/modules.md
View File

@@ -2,7 +2,7 @@
## Backend Contracts
### [DEF:ValidationPolicyModel:Class]
# [DEF:ValidationPolicyModel:Class]
# @TIER: STANDARD
# @SEMANTICS: SQLAlchemy, Model
# @PURPOSE: Database model for storing validation scheduling rules.
@@ -10,17 +10,17 @@
# @RELATION: DEPENDS_ON -> SQLAlchemy declarative base
# @PRE: Policy payload contains valid window_start and window_end strings.
# @POST: Policy is persisted with default `is_active=True`.
[/DEF:ValidationPolicyModel]
# [/DEF:ValidationPolicyModel:Class]
### [DEF:ValidationPolicySchema:Class]
# [DEF:ValidationPolicySchema:Class]
# @TIER: TRIVIAL
# @SEMANTICS: Pydantic, Schema
# @PURPOSE: API contract for reading and writing Validation Policies.
# @LAYER: API
# @RELATION: DEPENDS_ON -> ValidationPolicyModel
[/DEF:ValidationPolicySchema]
# [/DEF:ValidationPolicySchema:Class]
### [DEF:HealthService:Class]
# [DEF:HealthService:Class]
# @TIER: CRITICAL
# @SEMANTICS: Service, Aggregation
# @PURPOSE: Aggregates dashboard metadata with the latest ValidationRecord to produce health summaries.
@@ -34,9 +34,9 @@
# @TEST_FIXTURE: test_health_aggregation_success -> mock_dashboards_and_records
# @TEST_EDGE: test_health_aggregation_no_records -> Returns UNKNOWN status for dashboards without records.
# @TEST_INVARIANT: latest_record_wins -> VERIFIED_BY: [test_health_aggregation_success]
[/DEF:HealthService]
# [/DEF:HealthService:Class]
### [DEF:HealthRouter:Module]
# [DEF:HealthRouter:Module]
# @TIER: STANDARD
# @SEMANTICS: FastAPI, Route
# @PURPOSE: API endpoints for the Health Center UI.
@@ -44,9 +44,9 @@
# @RELATION: CALLS -> HealthService
# @PRE: Request includes valid authentication token.
# @POST: Returns JSON list of dashboard health statuses.
[/DEF:HealthRouter]
# [/DEF:HealthRouter:Module]
### [DEF:NotificationService:Class]
# [DEF:NotificationService:Class]
# @TIER: CRITICAL
# @SEMANTICS: Service, PubSub
# @PURPOSE: Evaluates policies and routes formatted notifications to dynamically resolved owners and explicit channels.
@@ -61,18 +61,18 @@
# @TEST_FIXTURE: test_owner_routing -> mock_profile_with_telegram
# @TEST_EDGE: test_missing_profile_contact -> Skips owner if no valid contact info is found without crashing.
# @TEST_INVARIANT: async_dispatch -> VERIFIED_BY: [test_owner_routing]
[/DEF:NotificationService]
# [/DEF:NotificationService:Class]
### [DEF:NotificationProvider:Interface]
# [DEF:NotificationProvider:Class]
# @TIER: STANDARD
# @SEMANTICS: Interface, Strategy
# @PURPOSE: Base abstraction for sending formatted alerts to external systems (SMTP, Slack, Telegram).
# @LAYER: Infra
# @PRE: Receives a standardized AlertPayload (text + image links).
# @POST: Delivers the payload to the external system.
[/DEF:NotificationProvider]
# [/DEF:NotificationProvider:Class]
### [DEF:ThrottledSchedulerConfigurator:Module]
# [DEF:ThrottledSchedulerConfigurator:Module]
# @TIER: CRITICAL
# @SEMANTICS: Scheduler, APScheduler
# @PURPOSE: Reads active ValidationPolicies and generates distributed cron/date triggers within the defined execution window.
@@ -86,11 +86,11 @@
# @TEST_FIXTURE: test_window_distribution -> policy_1hr_60tasks
# @TEST_EDGE: test_window_too_small -> 100 tasks in 1 min -> Falls back to minimum safe interval or logs warning.
# @TEST_INVARIANT: distribution_bounds -> VERIFIED_BY: [test_window_distribution, test_window_too_small]
[/DEF:ThrottledSchedulerConfigurator]
# [/DEF:ThrottledSchedulerConfigurator:Module]
## Frontend Contracts
### [DEF:HealthMatrix:Component]
# [DEF:HealthMatrix:Component]
# @TIER: STANDARD
# @SEMANTICS: Svelte, UI
# @PURPOSE: Displays traffic light summary cards (Pass, Warn, Fail).
@@ -100,9 +100,9 @@
# @POST: Renders three numeric summary cards with distinct colors.
# @UX_STATE: Loading -> Skeleton cards.
# @UX_STATE: Idle -> Distinct colored counts.
[/DEF:HealthMatrix]
# [/DEF:HealthMatrix:Component]
### [DEF:HealthCenterPage:Page]
# [DEF:HealthCenterPage:Component]
# @TIER: CRITICAL
# @SEMANTICS: SvelteKit, Route
# @PURPOSE: Main monitoring view for dashboard validation health.
@@ -115,9 +115,9 @@
# @UX_STATE: Error -> Toast notification and empty state.
# @UX_STATE: Success -> Matrix and populated table.
# @UX_TEST: FilterClick -> {click: "Fail only", expected: table shows only RED rows}
[/DEF:HealthCenterPage]
# [/DEF:HealthCenterPage:Component]
### [DEF:AutomationPoliciesPage:Page]
# [DEF:AutomationPoliciesPage:Component]
# @TIER: STANDARD
# @SEMANTICS: SvelteKit, Route
# @PURPOSE: Settings view to create and manage validation policies.
@@ -127,9 +127,9 @@
# @POST: Renders list of policies and 'Create Rule' modal.
# @UX_STATE: Creating -> Modal is open with form.
# @UX_FEEDBACK: SaveSuccess -> Toast "Policy scheduled".
[/DEF:AutomationPoliciesPage]
# [/DEF:AutomationPoliciesPage:Component]
### [DEF:SidebarHealthBadge:Store]
# [DEF:SidebarHealthBadge:Store]
# @TIER: STANDARD
# @SEMANTICS: Svelte Store
# @PURPOSE: Derived or fetched state to show `[🔴 N]` badge on the sidebar.
@@ -137,4 +137,4 @@
# @RELATION: DEPENDS_ON -> ActivityStore or specific Health poll
# @PRE: User is logged in.
# @POST: Provides integer count of currently failing dashboards.
[/DEF:SidebarHealthBadge]
# [/DEF:SidebarHealthBadge:Store]