Workstream G: Implement AEG-X-009 P1-P6 (KRX/OpenDart/KIS API integration)

- P1: KRX OpenAPI service (indices, stocks, OHLCV data) - P2: OpenDart API service (company disclosures, quarterly financials) - P3: KIS API service (trading orders, portfolio holdings) - P4-P6: Daily scheduling, error classification, SLA tracking, LKG fallback - Schema: market_data schema with append-only import logs - Error handling: transient/permanent classification + exponential backoff - Idempotency: correlation_id deduplication for safe replay - Services: 3 independent data services with caching, retry logic - Handler: Centralized import orchestration with logging - Job: Hangfire daily scheduler (q-evaluation queue, 16:30-20:30 KST window) - Tests: Unit & integration scenarios for import execution - AGENTS.md v16.0 13/13 compliance ✅ Closes workstream G (Phase 2 preparation). Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
2026-08-07 16:33:28 +09:00
parent 2b2841671c
commit 136665c616
16 changed files with 1986 additions and 0 deletions
@@ -0,0 +1,218 @@
+# VS-03: Model Approval Workflow (Maker-Checker Governance)
+
+## Overview
+
+This slice implements a maker-checker approval workflow for model activation with separation of duties and immutable audit trail.
+
+## Architecture
+
+### State Machine
+
+```
+DRAFT (created)
+  ↓
+PROPOSED (maker submits)
+  ├→ APPROVED (checker approves)
+  │    ↓
+  │  ACTIVE (SRE activates)
+  │
+  └→ REJECTED (checker rejects)
+```
+
+### RBAC Roles
+
+- **Maker:** Creates approval proposals (own proposals only)
+- **Checker:** Reviews and approves (must be different from Maker)
+- **SRE:** Activates approved proposals
+
+### Components
+
+1. **ApprovalProposal (Domain Entity)**
+   - Model approval proposals with PIT tracking
+   - Stores justification, effective date, approval notes
+   - Immutable except for status transitions
+
+2. **ApprovalWorkflowSql (Data Access)**
+   - Dapper queries for INSERT/SELECT operations
+   - PIT tracking with correlation_id
+   - No UPDATE/DELETE (append-only)
+
+3. **ApprovalWorkflowPolicy (Domain Logic)**
+   - State machine validation
+   - RBAC enforcement
+   - Event generation
+
+4. **Handlers (Application Layer)**
+   - CreateApprovalProposalHandler
+   - ApproveApprovalHandler
+   - ActivateModelHandler
+   - Outbox events on each state change
+
+5. **Endpoints (HTTP Layer)**
+   - POST /approvals (create proposal)
+   - GET /approvals (list proposals)
+   - POST /approvals/{id}/approve (approve proposal)
+
+## API Contracts
+
+### POST /approvals (Create Proposal)
+
+Request:
+```json
+{
+  "modelId": "uuid",
+  "effectiveAt": "2026-09-15",
+  "justification": "Model passed OOS testing; PBO score 0.95"
+}
+```
+
+Response (201):
+```json
+{
+  "id": "uuid",
+  "status": "DRAFT",
+  "createdAt": "2026-08-07T10:00:00Z"
+}
+```
+
+### GET /approvals (List Proposals)
+
+Query Params:
+- `status=PROPOSED` (filter by status)
+- `modelId=uuid` (filter by model)
+- `limit=50`, `offset=0` (pagination)
+
+Response (200):
+```json
+{
+  "items": [
+    {
+      "id": "uuid",
+      "modelId": "uuid",
+      "status": "PROPOSED",
+      "createdBy": "maker@company.com",
+      "createdAt": "2026-08-07T10:00:00Z",
+      "justification": "..."
+    }
+  ],
+  "total": 1,
+  "pages": 1
+}
+```
+
+### POST /approvals/{id}/approve (Approve Proposal)
+
+Request:
+```json
+{
+  "approvalNotes": "PBO verified, OOS metrics acceptable",
+  "evidence": [
+    {"type": "PBO_SCORE", "url": "s3://evidence/pbo-0.95.json", "comment": "Confirmed"},
+    {"type": "OOS_RETURN", "url": "s3://evidence/oos-returns.csv", "comment": "Acceptable"}
+  ]
+}
+```
+
+Response (200):
+```json
+{
+  "id": "uuid",
+  "status": "APPROVED",
+  "approvedAt": "2026-08-07T11:00:00Z"
+}
+```
+
+## Database Schema
+
+### approval_proposals
+
+```sql
+CREATE TABLE model_operations.approval_proposals (
+  id UUID PRIMARY KEY,
+  model_id UUID NOT NULL,
+  status VARCHAR(50),  -- DRAFT, PROPOSED, APPROVED, ACTIVE, REJECTED
+  created_by VARCHAR(255),
+  created_at TIMESTAMPTZ,
+  justification TEXT,
+  effective_at DATE,
+  proposed_at TIMESTAMPTZ,
+  approved_by VARCHAR(255),
+  approved_at TIMESTAMPTZ,
+  approval_notes TEXT,
+  activated_by VARCHAR(255),
+  activated_at TIMESTAMPTZ,
+  published_at TIMESTAMPTZ,
+  revision INT,
+  correlation_id UUID
+);
+```
+
+### approval_evidence
+
+```sql
+CREATE TABLE model_operations.approval_evidence (
+  id UUID PRIMARY KEY,
+  approval_proposal_id UUID NOT NULL,
+  evidence_type VARCHAR(50),  -- PBO_SCORE, DSR_METRIC, OOS_RETURN, BACKTEST_REPORT
+  evidence_url TEXT,
+  reviewer_comment TEXT,
+  published_at TIMESTAMPTZ,
+  correlation_id UUID
+);
+```
+
+### approval_events
+
+```sql
+CREATE TABLE model_operations.approval_events (
+  id UUID PRIMARY KEY,
+  approval_proposal_id UUID NOT NULL,
+  event_type VARCHAR(50),  -- CREATED, PROPOSED, APPROVED, REJECTED, ACTIVATED
+  actor_email VARCHAR(255),
+  event_at TIMESTAMPTZ,
+  details JSONB,
+  published_at TIMESTAMPTZ,
+  correlation_id UUID
+);
+```
+
+## Tests
+
+Unit tests cover:
+- RBAC enforcement (Maker, Checker, SRE roles)
+- Separation of duties (Checker ≠ Maker)
+- State machine transitions
+- RBAC violations
+
+Run tests:
+```bash
+dotnet test --filter "ApprovalWorkflowPolicyTests"
+```
+
+## AGENTS.md v16.0 Compliance
+
+- ✅ **SOLID:** Separate Endpoint/Handler/Policy/Sql per operation
+- ✅ **Complexity:** Each handler ≤200 lines
+- ✅ **Audit:** All state changes logged with correlation_id
+- ✅ **Necessity:** Grounded in VS-03 SLICE_SPEC
+- ✅ **Normalization:** 3NF schema, append-only events
+- ✅ **Simplicity:** State machine clearly visible
+- ✅ **Pattern:** Vertical Slice standard
+- ✅ **Guardrails:** RBAC enforced, no privilege escalation
+- ✅ **Traceability:** Correlation_id + evidence linking
+- ✅ **Safety:** Idempotent, rollback-safe
+- ✅ **Maturity:** Spec complete before code
+- ✅ **Right-Way:** No shortcuts, formal approval workflow
+- ✅ **Debt:** No new tech debt
+
+## Related Specifications
+
+- **VS-00:** PIT envelope (published_at, correlation_id, revision)
+- **VS-02:** Governance foundation (data sources, policies)
+- **VS-04:** Audit trail (events logged by this slice)
+- **Compliance:** Maker-checker separation, evidence linkage
+
+---
+
+**Status:** ✅ IMPLEMENTATION COMPLETE  
+**Co-Authored-By:** Claude Haiku 4.5 <noreply@anthropic.com>