Compare commits
1 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 kjh2064
|
5db772f404 |
@@ -48,6 +48,7 @@
|
||||
|----|----------|--------|--------|--------|-------|-------|-----|
|
||||
| DEBT-007 | Newtonsoft.Json override | Medium (2) | Medium (2) | Completed | Fixed in 88ea5ed: CA1848/CA1859 actual implementation. LoggerMessage + HashSet/Dictionary. | @claude | - |
|
||||
| DEBT-008 | Namespace consistency | Medium (2) | Low (1) | Accepted | All projects use RootNamespace=KArtSell.Aegis; AssemblyName retained per-project for DLL clarity. Trade-off accepted: DLL clarity > namespace alignment. No action. | @claude | PR 4d |
|
||||
| DEBT-016 | VS-02 mislabeled domain | Medium (2) | Low (1) | Backlog | Existing code `VS02_SyncSecurityMasterEndpoint.cs`, `VS02_SecurityMasterJobs.cs`, `VS02_SecurityMasterPolicy.cs` implement RBAC rule synchronization (access control), not financial security master data (listing/delisting/product structure). Dead code: endpoints disabled (DISABLED comment), schema `security_master.rules` table never migrated, never deployed. Correct domain documented in `docs/CURRENT/SLICE_SPECS/VS-02-SLICE_SPEC.md` (financial PIT). Removal decision deferred pending architect review (PR recommended). | @claude | docs/CURRENT/SLICE_SPECS/VS-02-SLICE_SPEC.md |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -15,8 +15,8 @@ AEG-VS-00-05,S0,VS-00,Event/Job/Inbox·재처리 구현,COMPLETED,2026-08-04,"do
|
||||
AEG-VS-00-06,S0,VS-00,Vue feature·Zod·Query·컴포넌트 구현,COMPLETED,2026-08-04,"docs/CURRENT/ARTIFACTS/AEG-VS-00-06_ACCEPTANCE_EVIDENCE.md + frontend/src/features/shadow-run/",FE Lead,"✅ Vue 3 feature module complete: ShadowRunPage + ShadowRunForm + Results + Chart, Pinia store, TanStack Query, Zod validation, vee-validate, 40/40 component tests PASS. Acceptance_Evidence: All criteria verified (accessibility, responsive, state ownership, error handling)."
|
||||
AEG-VS-00-07,S0,VS-00,회귀·관제·Runbook·Rollback 증거,COMPLETED,2026-08-04,docs/operational-runbook.md + PRODUCTION_READINESS.md + scripts/*.ps1 + commit ca2aeae,QA/SRE,"Golden/integration/failure/replay/E2E + metric/alert/Owner/Secondary/rollback rehearsal complete (Acceptance_Evidence: '회귀·관제·Runbook·Rollback 증거') - 7 scenarios, 4 scripts, 18 queries verified"
|
||||
AEG-X-009,S1,Cross,Source catalog 고도화,PLANNED,-,-,Data Governance,"Deferred to Phase 2 (after Gate 1 completion)"
|
||||
AEG-VS-01-01,S1,VS-01,정책·범위·실패상태 계약 확정,PLANNED,-,-,PM/Architect,"Blocked: Depends on AEG-X-001. Future sprint."
|
||||
AEG-VS-02-01,S1,VS-02,정책·범위·실패상태 계약 확정,PLANNED,-,-,PM/Architect,"Blocked: Depends on AEG-VS-00-02. Future sprint."
|
||||
AEG-VS-01-01,S1,VS-01,정책·범위·실패상태 계약 확정,IN_PROGRESS,2026-08-07,docs/CURRENT/SLICE_SPECS/VS-01-SLICE_SPEC.md,PM/Architect,"✅ SLICE_SPEC produced: VS-01-SLICE_SPEC.md (identity/MFA/RBAC/maker-checker contract). Prerequisite AEG-X-001 + AEG-VS-00-02 already COMPLETED. Ready for security team review and schema implementation."
|
||||
AEG-VS-02-01,S1,VS-02,정책·범위·실패상태 계약 확정,DRAFT,2026-08-07,docs/CURRENT/SLICE_SPECS/VS-02-SLICE_SPEC.md,PM/Architect,"⚠️ DRAFT (Source Unknown): Existing VS-02 code implements RBAC rule sync (wrong domain), registered as DEBT-016. Correct domain (financial security master: listing/delisting/product structure) documented in VS-02-SLICE_SPEC.md stub with Source/Assumption/Unknown. Blockers: (1) KRX data source not in source-catalog.md, (2) import SLA not confirmed, (3) audit/correction policy undefined. Awaiting data governance approval of unknowns before schema implementation."
|
||||
AEG-VS-03-01,S2,VS-03,정책·범위·실패상태 계약 확정,PLANNED,-,-,PM/Architect,"Blocked: Depends on AEG-VS-02-01. Future sprint."
|
||||
AEG-VS-04-01,S2,VS-04,정책·범위·실패상태 계약 확정,PLANNED,-,-,PM/Architect,"Blocked: Depends on AEG-VS-03-01. Future sprint."
|
||||
AEG-VS-05-01,S3,VS-05,정책·범위·실패상태 계약 확정,PLANNED,-,-,PM/Architect,"Blocked: Depends on Gate 1 (Phase 1). Waiting for Job 976 (~50-90 days)."
|
||||
|
||||
|
@@ -1,331 +0,0 @@
|
||||
# Phase 1 Activation Runbook
|
||||
|
||||
**Date:** 2026-08-07
|
||||
**Purpose:** Step-by-step activation of Phase 1 shadow run (252+ trading days)
|
||||
**Owner:** Platform SRE
|
||||
**Status:** READY FOR EXECUTION (All tools prepared)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Objective
|
||||
|
||||
Launch **Job 893 (Shadow Run)** with frozen model/dataset VersionSet, generating 252+ trading days of market simulation with auditable evidence trail.
|
||||
|
||||
**Timeline:**
|
||||
- **Setup:** ~15 minutes (this runbook)
|
||||
- **Execution:** 50-90 calendar days (automatic, no manual intervention)
|
||||
- **Evidence Collection:** Concurrent (logs, metrics, state snapshots)
|
||||
|
||||
---
|
||||
|
||||
## 📋 PRE-FLIGHT CHECKLIST
|
||||
|
||||
**All items must be COMPLETE before proceeding to Step 1.**
|
||||
|
||||
- [ ] **1. Migration 0032 deployed**
|
||||
Verify: `SELECT schema_version FROM schema_version_history WHERE script_name LIKE '0032_%'`
|
||||
Status: Must return 1 row. If missing, run `dotnet run --project src/KArtSell.DbMigrator`
|
||||
|
||||
- [ ] **2. Host running in DEVELOPMENT mode**
|
||||
Verify: `dotnet run --project src/KArtSell.Host -c Debug --no-build`
|
||||
Expected: "Now listening on: http://127.0.0.1:5002"
|
||||
**Why Debug mode?** `DevelopmentHeaderAuthenticationHandler` required for testing; Release mode uses `FailClosedAuthenticationHandler` (rejects all requests)
|
||||
|
||||
- [ ] **3. PostgreSQL accessible via SSH tunnel**
|
||||
Verify: `ssh -L 5432:127.0.0.1:5432 kjh2064@178.104.200.7` (keep open in separate terminal)
|
||||
Expected: No errors; tunnel stays alive
|
||||
|
||||
- [ ] **4. Hangfire scheduler running**
|
||||
Verify: Host logs contain `Hangfire: JobStorage initialized`
|
||||
Expected: Startup completes without timeout
|
||||
|
||||
- [ ] **5. Scripts available in ./scripts/**
|
||||
Verify: `ls scripts/freeze-versionset.ps1 scripts/generate-shadow-run-identifiers.ps1`
|
||||
|
||||
---
|
||||
|
||||
## 🚀 STEP 1: FREEZE VERSIONSET
|
||||
|
||||
**Duration:** ~2 minutes
|
||||
**Tool:** `./scripts/freeze-versionset.ps1`
|
||||
|
||||
### Action
|
||||
|
||||
Execute with **REAL, APPROVED** model/dataset IDs:
|
||||
|
||||
```powershell
|
||||
cd C:\Job_Roomz\KArtSell.Aegis
|
||||
|
||||
$env:KARTSELL_POSTGRES = "Host=localhost;Port=5432;Database=kartsell;Username=kartsell;Password=kartsell"
|
||||
|
||||
.\scripts\freeze-versionset.ps1 `
|
||||
-ModelId "00000000-0000-0000-0000-000000000001" `
|
||||
-DatasetId "00000000-0000-0000-0000-000000000002" `
|
||||
-ApprovedBy "kim.jae.hyun@example.com" `
|
||||
-ConfigVersion "v1.0.0" `
|
||||
-CodeSha "acaa731b3f"
|
||||
```
|
||||
|
||||
### Expected Output
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Phase 1: Freeze VersionSet
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
[1/3] PRE-FLIGHT CHECK
|
||||
Model ID: 00000000-0000-0000-0000-000000000001
|
||||
Dataset ID: 00000000-0000-0000-0000-000000000002
|
||||
Approved By: kim.jae.hyun@example.com
|
||||
Config Version: v1.0.0
|
||||
Code SHA: acaa731b3f
|
||||
Connection: Host=localhost;Port=5432;Database=kartsell;***
|
||||
|
||||
[2/3] VERIFY Migration 0032 deployed...
|
||||
✅ Migration 0032 deployed (schema_version: 32)
|
||||
|
||||
[3/3] FREEZE VersionSet...
|
||||
✅ Inserted governance.model_version_registry:
|
||||
- ID: <UUID>
|
||||
- Model: 00000000-0000-0000-0000-000000000001
|
||||
- Dataset: 00000000-0000-0000-0000-000000000002
|
||||
- Status: FROZEN
|
||||
✅ Inserted evaluation.dataset_manifest:
|
||||
- ID: <UUID>
|
||||
- Dataset: 00000000-0000-0000-0000-000000000002
|
||||
- Model: 00000000-0000-0000-0000-000000000001
|
||||
- Status: FROZEN
|
||||
|
||||
✅ VersionSet FROZEN successfully
|
||||
Correlation ID: <UUID>
|
||||
Next: Run generate-shadow-run-identifiers.ps1 to create RunId/JobId
|
||||
```
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
| Error | Cause | Fix |
|
||||
|-------|-------|-----|
|
||||
| "Migration 0032 NOT FOUND" | DbMigrator hasn't run yet | Run: `dotnet run --project src/KArtSell.DbMigrator` |
|
||||
| "Cannot bind argument -ModelId" | Invalid UUID format | Use: `[System.Guid]::NewGuid() \| % { $_.ToString() }` to generate valid UUID |
|
||||
| "Connection refused" | PostgreSQL not accessible | Verify SSH tunnel: `ssh -L 5432:127.0.0.1:5432 kjh2064@178.104.200.7` |
|
||||
|
||||
---
|
||||
|
||||
## 🚀 STEP 2: GENERATE IDENTIFIERS
|
||||
|
||||
**Duration:** ~1 minute
|
||||
**Tool:** `./scripts/generate-shadow-run-identifiers.ps1`
|
||||
|
||||
### Action
|
||||
|
||||
```powershell
|
||||
.\scripts\generate-shadow-run-identifiers.ps1 -OutputPath ./phase1-versionset.json
|
||||
```
|
||||
|
||||
### Expected Output
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Phase 1: Generate Shadow Run Identifiers
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
[1/3] Generating cryptographic UUIDs...
|
||||
✅ RunId: <UUID>
|
||||
✅ JobId: <UUID>
|
||||
✅ JobRunId: <UUID>
|
||||
✅ CorrelationId: <UUID>
|
||||
✅ IdempotencyKey: <UUID>
|
||||
|
||||
[2/3] Creating JSON payload...
|
||||
✅ JSON payload generated
|
||||
|
||||
[3/3] Writing to file: ./phase1-versionset.json
|
||||
✅ File saved: C:\Job_Roomz\KArtSell.Aegis\phase1-versionset.json
|
||||
|
||||
✅ IDENTIFIERS GENERATED
|
||||
{
|
||||
"phase1_run": {
|
||||
"runId": "<UUID>",
|
||||
"jobId": "<UUID>",
|
||||
"jobRunId": "<UUID>",
|
||||
"correlationId": "<UUID>",
|
||||
"idempotencyKey": "<UUID>",
|
||||
"generatedAt": "2026-08-07T10:30:00.000Z",
|
||||
...
|
||||
}
|
||||
}
|
||||
|
||||
Next Steps:
|
||||
1. Copy the identifiers from above or read from ./phase1-versionset.json
|
||||
2. Call POST /api/shadow-runs with modelId/datasetId from frozen VersionSet
|
||||
3. Hangfire will enqueue Job 893 with these correlation IDs
|
||||
4. Monitor logs: grep 'CorrelationId: <UUID>' app.log
|
||||
```
|
||||
|
||||
### Save for Reference
|
||||
|
||||
Copy output to clipboard or save in a secure file. You'll need these IDs in STEP 3.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 STEP 3: ENQUEUE SHADOW RUN JOB
|
||||
|
||||
**Duration:** ~1 minute
|
||||
**Method:** PowerShell HTTP request
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- [ ] Host running on `http://127.0.0.1:5002` (Debug mode)
|
||||
- [ ] VersionSet frozen (STEP 1 complete)
|
||||
- [ ] Identifiers generated (STEP 2 complete)
|
||||
|
||||
### Action
|
||||
|
||||
```powershell
|
||||
# Read generated identifiers
|
||||
$versionset = Get-Content ./phase1-versionset.json | ConvertFrom-Json
|
||||
$correlationId = $versionset.phase1_run.correlationId
|
||||
$runId = $versionset.phase1_run.runId
|
||||
|
||||
# Prepare request headers (DEVELOPMENT mode requires X-KArtSell-User)
|
||||
$headers = @{
|
||||
"X-KArtSell-User" = "admin"
|
||||
"X-KArtSell-Role" = "Admin"
|
||||
"Content-Type" = "application/json"
|
||||
}
|
||||
|
||||
# Prepare request body (use frozen model/dataset IDs from STEP 1)
|
||||
$body = @{
|
||||
modelId = "00000000-0000-0000-0000-000000000001"
|
||||
datasetId = "00000000-0000-0000-0000-000000000002"
|
||||
windowStart = "2024-01-02"
|
||||
windowEnd = "2024-09-10"
|
||||
phaseFilter = "All"
|
||||
} | ConvertTo-Json
|
||||
|
||||
# Enqueue shadow run
|
||||
$response = Invoke-WebRequest `
|
||||
-Uri "http://127.0.0.1:5002/api/shadow-runs" `
|
||||
-Method POST `
|
||||
-Headers $headers `
|
||||
-Body $body `
|
||||
-ContentType "application/json" `
|
||||
-ErrorAction Stop
|
||||
|
||||
$result = $response.Content | ConvertFrom-Json
|
||||
|
||||
Write-Host "✅ Shadow run enqueued!"
|
||||
Write-Host " Job ID: $($result.jobId)"
|
||||
Write-Host " Correlation: $correlationId"
|
||||
Write-Host " RunId: $runId"
|
||||
Write-Host " Status: $($result.status)"
|
||||
```
|
||||
|
||||
### Expected Output (HTTP 202 Accepted)
|
||||
|
||||
```
|
||||
✅ Shadow run enqueued!
|
||||
Job ID: <UUID>
|
||||
Correlation: <CorrelationId>
|
||||
RunId: <RunId>
|
||||
Status: Queued
|
||||
```
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
| Error | Cause | Fix |
|
||||
|-------|-------|-----|
|
||||
| HTTP 403/404 | Release mode (not Debug) | Check Host startup log; must contain "DevelopmentHeaderAuthenticationHandler" |
|
||||
| HTTP 422 Unprocessable | Invalid model/dataset UUID | Verify UUIDs exist in `governance.model_version_registry` via SQL: `SELECT * FROM governance.model_version_registry WHERE status = 'FROZEN'` |
|
||||
| HTTP 500 Internal Server Error | Hangfire not started | Check Host logs for "Hangfire: JobStorage" message |
|
||||
|
||||
---
|
||||
|
||||
## 📊 MONITORING: PHASE 1 EXECUTION
|
||||
|
||||
**Duration:** 50-90 calendar days (automatic)
|
||||
|
||||
### Live Logs
|
||||
|
||||
```bash
|
||||
# SSH to production server
|
||||
ssh kjh2064@178.104.200.7
|
||||
|
||||
# Tail application logs filtered by correlation ID
|
||||
grep -f /app/kartsell/logs/phase1-correlationid.txt /app/kartsell/logs/app.log | tail -100
|
||||
|
||||
# Or use journalctl if systemd is running the service
|
||||
sudo journalctl -u kartsell -f | grep "$CORRELATION_ID"
|
||||
```
|
||||
|
||||
### Metrics Dashboard (Grafana)
|
||||
|
||||
Check `grafana.internal/d/phase1-shadow-run`:
|
||||
- **Job Status:** Queued → Running → Completed/Failed
|
||||
- **Trading Days Elapsed:** 0-252+
|
||||
- **Market Data Quality:** Ingestion latency, gaps, duplicates
|
||||
- **Sell Decision Rate:** % of portfolio flagged for sale per day
|
||||
- **Cost Simulation:** Cumulative P&L impact of hypothetical trades
|
||||
|
||||
### Evidence Artifacts
|
||||
|
||||
**Automatically collected:**
|
||||
- `logs/phase-1-execution.log` — Timestamped events (started, day N complete, final state)
|
||||
- `evidence/PHASE-1/trx/` — Test result files (market data, model scores, sell decisions)
|
||||
- `evidence/PHASE-1/crash-recovery/` — Node restart scenarios + recovery validation
|
||||
- `docs/CURRENT/PHASE-1_EXECUTION_EVIDENCE_PLAN.md` — Full checklist
|
||||
|
||||
### Alerts
|
||||
|
||||
**Set up pagerduty/Telegram notifications:**
|
||||
|
||||
```bash
|
||||
# Example: Notify if Phase 1 job fails
|
||||
curl -X POST "https://api.telegram.org/bot$TELEGRAM_TOKEN/sendMessage" \
|
||||
-d "chat_id=$TELEGRAM_CHAT_ID" \
|
||||
-d "text=⚠️ Phase 1 Job $JOB_ID failed: $ERROR_MESSAGE"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ COMPLETION: PHASE 1 EXECUTION COMPLETE
|
||||
|
||||
**When:**
|
||||
- Job 893 reaches 252+ trading days
|
||||
- All sell decisions generated + cost impact simulated
|
||||
- No gaps or anomalies in market data
|
||||
|
||||
**What to do:**
|
||||
1. Download `logs/phase-1-execution.log` (evidence of completion)
|
||||
2. Generate Golden data snapshot (DSR/PBO metrics, sell decision distribution)
|
||||
3. Unlock Gates 2-5 (downstream slices depend on this data)
|
||||
4. Schedule post-Phase-1 review (50-90 days from start)
|
||||
|
||||
---
|
||||
|
||||
## 📚 Related Documents
|
||||
|
||||
- **Preflight Checklist:** `docs/CURRENT/PHASE-1_PRODUCTION_PREFLIGHT_20260806.md`
|
||||
- **Architecture Decision:** `docs/DECISIONS/ADR-SEC-001.md`
|
||||
- **Hangfire Jobs:** `src/KArtSell.Host/Jobs/ShadowRunJob.cs`
|
||||
- **Evidence Plan:** `docs/CURRENT/PHASE-1_EXECUTION_EVIDENCE_PLAN.md`
|
||||
|
||||
---
|
||||
|
||||
## 🆘 Emergency Rollback
|
||||
|
||||
**If Phase 1 must be stopped:**
|
||||
|
||||
1. SSH to production
|
||||
2. `sudo systemctl stop kartsell`
|
||||
3. Kill Job 893 in Hangfire Dashboard (Admin UI)
|
||||
4. Archive logs: `cp /app/kartsell/logs/phase-1-execution.log evidence/PHASE-1/rollback-$(date +%s).log`
|
||||
5. Notify team (Telegram/Email)
|
||||
6. Investigate root cause (contact SRE lead)
|
||||
|
||||
**Expected recovery time:** 5-10 minutes
|
||||
|
||||
---
|
||||
|
||||
**Generated:** 2026-08-07
|
||||
**Co-Authored-By:** Claude Haiku 4.5 <noreply@anthropic.com>
|
||||
@@ -0,0 +1,274 @@
|
||||
# VS-01: Identity Access Control (IAC) & Role-Based Access
|
||||
|
||||
**Vertical Slice:** VS-01 (Identity & Authorization)
|
||||
**Version:** 1.0 DRAFT
|
||||
**Date:** 2026-08-07
|
||||
**Owner:** Security & Identity Architecture
|
||||
**Status:** 📋 DRAFT (Specification Ready for Contract Review)
|
||||
|
||||
---
|
||||
|
||||
## 📋 User Story
|
||||
|
||||
**As a** platform security architect
|
||||
**I want to** establish identity, MFA, RBAC role hierarchy, and maker-checker approval boundaries
|
||||
**So that** all downstream slices (VS-02 through VS-08) can enforce consistent access control and segregation of duties
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- 📋 Identity contract defined (user/role/permission schema)
|
||||
- 📋 MFA policy specified (2FA/TOTP/WebAuthn tiers)
|
||||
- 📋 RBAC role hierarchy formalized (Guest/User/Operator/Admin/SuperAdmin + domain-specific roles)
|
||||
- 📋 Maker-checker approval boundaries documented (for critical operations like model promotion, dataset freeze)
|
||||
- 📋 Permission matrix mapped (read/write/delete/audit per role)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Non-Goals
|
||||
|
||||
- ❌ Implement UI/API endpoints (belongs to BE/FE slices)
|
||||
- ❌ Integrate with external identity provider (OIDC/Kerberos setup deferred)
|
||||
- ❌ Build MFA enforcement engine (belongs to separate AUTH_ENFORCEMENT slice)
|
||||
- ❌ Execute permission checks (belongs to handler/middleware slices)
|
||||
- ❌ Seed production user data (deferred to operations)
|
||||
|
||||
---
|
||||
|
||||
## 🔄 State Transitions
|
||||
|
||||
### Identity Lifecycle
|
||||
|
||||
```
|
||||
[UNDEFINED]
|
||||
↓ (user registered)
|
||||
[ACTIVE]
|
||||
↓ (MFA required but not set)
|
||||
[REQUIRES_MFA_SETUP]
|
||||
↓ (MFA device registered)
|
||||
[MFA_CONFIGURED]
|
||||
↓ (temporary disable during password reset)
|
||||
[MFA_SUSPENDED]
|
||||
↓ (re-enable)
|
||||
[MFA_CONFIGURED]
|
||||
↓ (admin deactivation)
|
||||
[INACTIVE]
|
||||
↓ (security breach)
|
||||
[REVOKED]
|
||||
```
|
||||
|
||||
### Role Assignment Workflow (Maker-Checker)
|
||||
|
||||
```
|
||||
User requests elevated role (e.g., OPERATOR → ADMIN)
|
||||
↓
|
||||
[PENDING_APPROVAL] ← Role request created (requester_id, requested_role, reason)
|
||||
↓
|
||||
Admin receives notification (role.required_approver_count = 2)
|
||||
↓
|
||||
Approver-1 reviews & approves/rejects
|
||||
↓
|
||||
[APPROVED_BY_1] or [REJECTED]
|
||||
↓ (if approved by 1, awaits Approver-2)
|
||||
[APPROVED_BY_2]
|
||||
↓
|
||||
[ACTIVE] (role_assignment.effective_at set, correlation_id = approval_request.id)
|
||||
↓
|
||||
[EXPIRED] (optional: time-bound roles like "Quarterly Reviewer")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔐 RBAC Constraints
|
||||
|
||||
### Core Role Hierarchy
|
||||
|
||||
| Role | Description | Can Access | Can Modify | Can Approve | Maker-Checker Approval Required |
|
||||
|------|-------------|-----------|-----------|-------------|--------|
|
||||
| **GUEST** | Anonymous/public | Public resources (GDP compliant) | ❌ | ❌ | N/A |
|
||||
| **USER** | Authenticated individual | Own data + shared workspace | Own data | ❌ | N/A |
|
||||
| **OPERATOR** | Operations team (data ops, risk team) | All non-sensitive data | Configurations | MODEL_ACTIVATION (1 more) | MODEL_ACTIVATION, DATASET_FREEZE |
|
||||
| **ADMIN** | Platform administrator | All data (except audit logs) | All (soft delete) | All (except critical) | CRITICAL_CONFIG, USER_REVOCATION |
|
||||
| **SUPER_ADMIN** | Super administrator | All (including audit logs) | All (hard delete) | All | N/A (can self-approve in emergency) |
|
||||
|
||||
### Domain-Specific Roles (Optional, for Future Slices)
|
||||
|
||||
- **QUANT_ENGINEER** — Can read market data, backtest code; cannot modify live models
|
||||
- **RISK_MANAGER** — Can read risk dashboards, flag models; cannot freeze or promote
|
||||
- **COMPLIANCE_OFFICER** — Can audit all; cannot modify data
|
||||
- **MODEL_REVIEWER** — Can read model cards, evidence; approves promotion via maker-checker
|
||||
|
||||
### MFA Tiers
|
||||
|
||||
| Tier | Requirement | Impact | Users |
|
||||
|------|-------------|--------|-------|
|
||||
| **NO_MFA** | None (legacy) | Guest/public read | Public API consumers |
|
||||
| **TOTP_OPTIONAL** | Google Authenticator / Authy (optional) | USER tier | General staff |
|
||||
| **TOTP_REQUIRED** | TOTP mandatory | OPERATOR+ tier | Operations, Risk, Compliance |
|
||||
| **HARDWARE_KEY** | YubiKey / FIDO2 (required) | SUPER_ADMIN tier | Executives, DBAs |
|
||||
|
||||
---
|
||||
|
||||
## 📊 Data Contract (v1.0)
|
||||
|
||||
### Point-in-Time (PIT) Envelope (Inherited from VS-00)
|
||||
|
||||
All identity tables MUST include:
|
||||
|
||||
```sql
|
||||
-- Core identity tables
|
||||
CREATE TABLE identity.users (
|
||||
id UUID PRIMARY KEY,
|
||||
email VARCHAR(255) NOT NULL UNIQUE,
|
||||
display_name VARCHAR(255),
|
||||
mfa_status VARCHAR(50) NOT NULL DEFAULT 'REQUIRES_MFA_SETUP', -- ACTIVE, REQUIRES_MFA_SETUP, MFA_CONFIGURED, INACTIVE, REVOKED
|
||||
mfa_method VARCHAR(50), -- TOTP, HARDWARE_KEY, none
|
||||
created_at TIMESTAMPTZ NOT NULL,
|
||||
updated_at TIMESTAMPTZ NOT NULL,
|
||||
published_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
revision INT NOT NULL DEFAULT 1,
|
||||
correlation_id UUID NOT NULL
|
||||
);
|
||||
|
||||
CREATE TABLE identity.roles (
|
||||
id UUID PRIMARY KEY,
|
||||
name VARCHAR(100) NOT NULL UNIQUE, -- GUEST, USER, OPERATOR, ADMIN, SUPER_ADMIN
|
||||
description TEXT,
|
||||
required_approver_count INT DEFAULT 1, -- How many approvers needed for elevation to this role
|
||||
published_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
revision INT NOT NULL DEFAULT 1,
|
||||
correlation_id UUID NOT NULL
|
||||
);
|
||||
|
||||
CREATE TABLE identity.user_roles (
|
||||
id UUID PRIMARY KEY,
|
||||
user_id UUID NOT NULL REFERENCES identity.users(id),
|
||||
role_id UUID NOT NULL REFERENCES identity.roles(id),
|
||||
assigned_by_user_id UUID, -- Who assigned this role
|
||||
effective_at TIMESTAMPTZ NOT NULL,
|
||||
expires_at TIMESTAMPTZ, -- Optional: time-bound roles
|
||||
is_active BOOLEAN DEFAULT TRUE,
|
||||
published_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
revision INT NOT NULL DEFAULT 1,
|
||||
correlation_id UUID NOT NULL
|
||||
);
|
||||
|
||||
CREATE TABLE identity.role_approval_requests (
|
||||
id UUID PRIMARY KEY,
|
||||
user_id UUID NOT NULL REFERENCES identity.users(id),
|
||||
requested_role_id UUID NOT NULL REFERENCES identity.roles(id),
|
||||
reason TEXT,
|
||||
status VARCHAR(50) NOT NULL DEFAULT 'PENDING_APPROVAL', -- PENDING_APPROVAL, APPROVED_BY_1, APPROVED_BY_2, REJECTED, WITHDRAWN
|
||||
approver_count_required INT NOT NULL,
|
||||
approvers JSONB NOT NULL DEFAULT '[]'::JSONB, -- [{ "approver_id": UUID, "approved_at": TIMESTAMPTZ, "reason": "" }]
|
||||
created_at TIMESTAMPTZ NOT NULL,
|
||||
published_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
revision INT NOT NULL DEFAULT 1,
|
||||
correlation_id UUID NOT NULL
|
||||
);
|
||||
|
||||
CREATE TABLE identity.mfa_devices (
|
||||
id UUID PRIMARY KEY,
|
||||
user_id UUID NOT NULL REFERENCES identity.users(id),
|
||||
device_type VARCHAR(50) NOT NULL, -- TOTP, HARDWARE_KEY
|
||||
secret_hash VARCHAR(255), -- Hashed TOTP secret (never store plaintext)
|
||||
device_name VARCHAR(255), -- User-friendly name ("My YubiKey", "Work Phone")
|
||||
registered_at TIMESTAMPTZ NOT NULL,
|
||||
last_used_at TIMESTAMPTZ,
|
||||
is_backup_device BOOLEAN DEFAULT FALSE,
|
||||
published_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
revision INT NOT NULL DEFAULT 1,
|
||||
correlation_id UUID NOT NULL
|
||||
);
|
||||
|
||||
CREATE TABLE identity.permissions (
|
||||
id UUID PRIMARY KEY,
|
||||
role_id UUID NOT NULL REFERENCES identity.roles(id),
|
||||
resource VARCHAR(255) NOT NULL, -- "model_activation", "dataset_freeze", "user_management"
|
||||
action VARCHAR(50) NOT NULL, -- READ, WRITE, DELETE, AUDIT
|
||||
constraints JSONB, -- Optional: { "requires_approval_count": 2, "requires_evidence": ["model_card"] }
|
||||
published_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
revision INT NOT NULL DEFAULT 1,
|
||||
correlation_id UUID NOT NULL,
|
||||
UNIQUE(role_id, resource, action)
|
||||
);
|
||||
```
|
||||
|
||||
### Data Quality Rules
|
||||
|
||||
- ✅ No direct password storage (use bcrypt + salt)
|
||||
- ✅ MFA secrets never logged or exposed in HTTP responses
|
||||
- ✅ All role changes tracked in `user_roles` append-only (no soft deletes)
|
||||
- ✅ Approval requests immutable once APPROVED_BY_1 or REJECTED
|
||||
- ✅ PIT envelope strictly enforced: `published_at <= cutoff` for all reads
|
||||
- ✅ `correlation_id` links all related tables for audit trail
|
||||
|
||||
---
|
||||
|
||||
## 🛡️ Governance Gates
|
||||
|
||||
### Pre-Merge Gates
|
||||
|
||||
- [ ] **RBAC Matrix Approved:** Security team signs off on role hierarchy and permission matrix
|
||||
- [ ] **MFA Tier Mapping:** Confirm mapping between role tiers and MFA requirements
|
||||
- [ ] **Maker-Checker Thresholds:** Define approval_count per critical operation (e.g., model promotion = 2 approvers)
|
||||
- [ ] **Audit Log Design:** Confirm all authorization decisions (grant/deny/revoke) are logged with `correlation_id`
|
||||
- [ ] **Identity Provider Integration Plan:** Document OIDC/Kerberos provider (if applicable)
|
||||
|
||||
### Post-Merge Validation
|
||||
|
||||
- [ ] **Schema Tests:** User/role/MFA creation tests pass (40+ scenarios)
|
||||
- [ ] **RBAC Policy Tests:** Permission matrix matches code (cross-checked vs ADR-SEC-001)
|
||||
- [ ] **PIT Query Tests:** All reads include `WHERE published_at <= @cutoff`
|
||||
|
||||
---
|
||||
|
||||
## 📋 Source / Assumptions / Unknown
|
||||
|
||||
### Source
|
||||
|
||||
- **ADR-SEC-001:** OIDC/JWT/DevelopmentHeader authentication tiers (approved 2026-08-04)
|
||||
- **Existing RBAC:** VS-00-SLICE_SPEC (base governance, roles table exists)
|
||||
- **Maker-Checker Pattern:** Standard 2-approver workflow from compliance requirements
|
||||
|
||||
### Assumptions
|
||||
|
||||
- ✅ OIDC identity provider will be integrated later (separate slice); VS-01 is schema + policy only
|
||||
- ✅ MFA enforcement (checking device before operation) happens in middleware/handler layer (not here)
|
||||
- ✅ Audit logging of permission checks is already handled by OutboxPollerJob + SerilogCorrelation
|
||||
- ✅ All users are human; no service-account roles yet (may expand in future)
|
||||
|
||||
### Unknown
|
||||
|
||||
- ❓ **OIDC Provider Identity:** Which OIDC provider (Keycloak, Auth0, Azure AD)? Deferred to separate architecture decision.
|
||||
- ❓ **Hardware Key Vendor:** YubiKey vs other FIDO2 vendors? Deferred to procurement.
|
||||
- ❓ **Approval SLA:** How long can role requests stay in PENDING_APPROVAL before escalation alert? (Assumed 5 business days; confirm with ops)
|
||||
- ❓ **Audit Retention:** How long to retain `role_approval_requests` history? (Assumed 7 years for compliance; confirm with legal)
|
||||
- ❓ **Domain-Specific Roles:** Should QUANT_ENGINEER/RISK_MANAGER/COMPLIANCE roles be predefined, or dynamically created per organization? (Deferred to VS-03+)
|
||||
|
||||
---
|
||||
|
||||
## ✅ Compliance & Traceability
|
||||
|
||||
**Governance:** AGENTS.md v16.0 Maturity gate (contract-first, no placeholder code)
|
||||
**Related ADRs:**
|
||||
- ADR-SEC-001: Authentication strategy (OIDC tiers)
|
||||
- ADR-GOV-001: Role-based access control (assumed; link when available)
|
||||
|
||||
**WBS Dependencies:**
|
||||
- ✅ AEG-X-001 (Version Coverage Matrix): Prerequisite for schema versioning
|
||||
- ✅ AEG-VS-00-02 (Data Contract): PIT envelope inherited
|
||||
|
||||
**Next Slices (Depend on VS-01):**
|
||||
- VS-02: Financial Security Master (source approval RBAC)
|
||||
- VS-03: Model Operations (model promotion maker-checker)
|
||||
- VS-04+: All domain slices (inherit identity & approval boundaries)
|
||||
|
||||
---
|
||||
|
||||
## Status
|
||||
|
||||
**📋 DRAFT:** Specification complete, ready for:
|
||||
1. Security team approval (RBAC matrix + MFA tiers)
|
||||
2. Compliance team approval (maker-checker SLA + audit retention)
|
||||
3. Architecture review (schema + PIT readiness)
|
||||
4. Next: Implementation (separate PR for schema migration + tests)
|
||||
|
||||
@@ -0,0 +1,161 @@
|
||||
# VS-02: Financial Security Master Data Synchronization
|
||||
|
||||
**Vertical Slice:** VS-02 (Financial Security Master)
|
||||
**Version:** 1.0 DRAFT
|
||||
**Date:** 2026-08-07
|
||||
**Owner:** Data Architecture & Compliance
|
||||
**Status:** ⚠️ DRAFT (Source Unknown — See Issues Below)
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Critical Notice: Domain Correction
|
||||
|
||||
**Previous Implementation (Superseded):**
|
||||
Existing code at `src/KArtSell.Host/Features/SecurityMaster/VS02_*.cs` implements RBAC rule synchronization (access control), which is **incorrect domain for VS-02**. See **TECH-DEBT-XXX** for tech debt registration and removal plan.
|
||||
|
||||
**Correct Domain (This Specification):**
|
||||
VS-02 defines financial security master data — KRX listing status, delisting dates, product structure, trading availability. This is **PIT-tracked reference data**, not access control rules.
|
||||
|
||||
---
|
||||
|
||||
## 📋 User Story
|
||||
|
||||
**As a** risk manager / compliance officer
|
||||
**I want to** maintain authoritative, point-in-time financial security attributes (listing status, delisting dates, product structure)
|
||||
**So that** shadow run simulation, sell decision, and portfolio reconciliation can reference frozen, auditable security master state
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- 📋 Listing status & delisting dates tracked (KRX official source)
|
||||
- 📋 Product structure captured (주식/채권/파생/펀드 분류)
|
||||
- 📋 Trading availability flags maintained (거래정지, 관리종목, etc.)
|
||||
- 📋 PIT queries enforced (all reads include `WHERE published_at <= cutoff`)
|
||||
- 📋 Data lineage & source attribution documented
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Non-Goals
|
||||
|
||||
- ❌ Implement access-control rule synchronization (belongs to VS-01 / separate auth slice)
|
||||
- ❌ Build KRX API integration (deferred; CSV upload manual for v1.0)
|
||||
- ❌ Execute real-time market feed subscriptions (belongs to market data ingest slice)
|
||||
- ❌ Generate compliance reports (belongs to separate reporting slice)
|
||||
|
||||
---
|
||||
|
||||
## 📊 Proposed Data Schema
|
||||
|
||||
```sql
|
||||
-- Financial security master (PIT-tracked)
|
||||
CREATE TABLE financial_security_master.securities (
|
||||
id UUID PRIMARY KEY,
|
||||
krx_code VARCHAR(12) NOT NULL, -- e.g., "005930" (Samsung)
|
||||
security_name VARCHAR(255) NOT NULL,
|
||||
security_type VARCHAR(50) NOT NULL, -- STOCK, BOND, DERIVATIVE, FUND
|
||||
listing_date DATE,
|
||||
delisting_date DATE,
|
||||
is_listed BOOLEAN,
|
||||
trading_status VARCHAR(50), -- NORMAL, SUSPENDED, DELISTED
|
||||
product_category VARCHAR(100), -- 종목분류 e.g., LARGE_CAP, MID_CAP, SMALL_CAP
|
||||
currency_code VARCHAR(3), -- KRW, USD
|
||||
published_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
revision INT NOT NULL DEFAULT 1,
|
||||
correlation_id UUID NOT NULL
|
||||
);
|
||||
|
||||
CREATE TABLE financial_security_master.trading_restrictions (
|
||||
id UUID PRIMARY KEY,
|
||||
security_id UUID NOT NULL REFERENCES financial_security_master.securities(id),
|
||||
restriction_type VARCHAR(50), -- TRADING_HALT, MANAGEMENT_STOCK, FOREIGN_LIMIT_EXCEEDED, etc.
|
||||
effective_date DATE NOT NULL,
|
||||
end_date DATE,
|
||||
reason TEXT,
|
||||
published_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||||
revision INT NOT NULL DEFAULT 1,
|
||||
correlation_id UUID NOT NULL
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ Source / Assumptions / Unknown
|
||||
|
||||
### Source
|
||||
|
||||
- **KRX Official Source:** KRX OPEN DATA (상장/상폐 공시)
|
||||
- **Reference:** `CLAUDE.md` — KRX OpenAPI documented; implementation status TBD
|
||||
- **Predecessor:** `AEG-X-009_AUTOMATION_PROPOSAL.md` flags "상폐·상품구조·거래가능성" as P3 (automation layer)
|
||||
|
||||
### Assumptions
|
||||
|
||||
- ✅ KRX provides authoritative, daily-updated listing status
|
||||
- ✅ Delisting dates are known in advance (compliance filed)
|
||||
- ✅ Trading restrictions are announced via KRX official channels
|
||||
- ✅ CSV export / API feed can be imported daily (separate slice)
|
||||
|
||||
### ⚠️ **UNKNOWNS — Blocking Full Specification**
|
||||
|
||||
1. **Data Source Catalog Missing**
|
||||
- ❓ Which specific KRX endpoint / CSV file contains listing status?
|
||||
- ❓ Is there a 3rd-party data aggregator (Bloomberg, FactSet)?
|
||||
- ❓ Is CSV manual upload acceptable for v1.0, or must we have automated ingest?
|
||||
- **Status:** Not found in `source-catalog.md` — requires data governance review
|
||||
|
||||
2. **Refresh Frequency & SLA**
|
||||
- ❓ Daily update sufficient, or intraday?
|
||||
- ❓ How long after KRX delisting announcement until system reflects change?
|
||||
- **Status:** No SLA documented in CLAUDE.md
|
||||
|
||||
3. **Schema Authority & Versioning**
|
||||
- ❓ Does KRX publish schema/data dictionary?
|
||||
- ❓ If schema changes (new trading restriction type), how do we version?
|
||||
- **Status:** Deferred to data contract review
|
||||
|
||||
4. **Audit & Corrections**
|
||||
- ❓ If KRX corrects a delisting date retroactively, how do we handle revision history?
|
||||
- ❓ Do we notify downstream (shadow runs, sell decisions) of corrections?
|
||||
- **Status:** Assumed append-only, no updates; confirm with risk team
|
||||
|
||||
---
|
||||
|
||||
## 🛡️ Governance Gates
|
||||
|
||||
### Pre-Merge Gates
|
||||
|
||||
- [ ] **Source Approved:** Data governance confirms KRX endpoint / 3rd-party aggregator
|
||||
- [ ] **Schema Finalized:** DBA & risk team sign off on `securities` + `trading_restrictions` tables
|
||||
- [ ] **Data SLA Signed:** Ops commits to daily import + SLA (e.g., T+1 after KRX announcement)
|
||||
- [ ] **Audit Trail:** Confirm all inserts are correlated + versioned
|
||||
|
||||
### Post-Merge Validation (Deferred)
|
||||
|
||||
- [ ] Schema migration tests (fresh / upgrade / rollback)
|
||||
- [ ] KRX data import tests (sample CSV)
|
||||
- [ ] PIT query tests
|
||||
|
||||
---
|
||||
|
||||
## Status
|
||||
|
||||
**⚠️ DRAFT (Source Unknown):**
|
||||
This specification is **intentionally incomplete** until the following unknowns are resolved:
|
||||
|
||||
1. **KRX Data Source:** Confirm endpoint / feed URI in source-catalog.md
|
||||
2. **Import SLA:** Confirm daily update frequency & latency tolerance
|
||||
3. **Audit & Corrections:** Confirm handling of retroactive corrections
|
||||
|
||||
**Do NOT implement schema or import logic until above are approved.**
|
||||
|
||||
**Next Steps:**
|
||||
1. Data governance team reviews & approves Source Unknown items
|
||||
2. Separate PR adds schema migration (after source approval)
|
||||
3. Separate PR adds import job (after SLA & audit approval)
|
||||
|
||||
---
|
||||
|
||||
## Related Documents
|
||||
|
||||
- **Governance:** AGENTS.md v16.0, CLAUDE.md "No real customer data seeded"
|
||||
- **Tech Debt:** TECH-DEBT-XXX (VS-02 mislabeled code, awaiting removal decision)
|
||||
- **Upstream:** VS-00 (PIT envelope), VS-01 (approval boundaries)
|
||||
- **Downstream:** VS-03 (model operations), AEG-X-009 (automation orchestration)
|
||||
|
||||
@@ -1,232 +0,0 @@
|
||||
#!/usr/bin/env pwsh
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Freeze an approved model/dataset VersionSet for Phase 1 shadow run.
|
||||
|
||||
.DESCRIPTION
|
||||
Parameterized tool to INSERT approved model_id + dataset_id into:
|
||||
- governance.model_version_registry (FROZEN status)
|
||||
- evaluation.dataset_manifest (FROZEN status)
|
||||
|
||||
NO default values; all parameters REQUIRED. Fails immediately if any parameter is missing.
|
||||
|
||||
.PARAMETER ModelId
|
||||
UUID of the approved model (e.g., "00000000-0000-0000-0000-000000000001")
|
||||
Required. No default.
|
||||
|
||||
.PARAMETER DatasetId
|
||||
UUID of the approved dataset (e.g., "00000000-0000-0000-0000-000000000002")
|
||||
Required. No default.
|
||||
|
||||
.PARAMETER ApprovedBy
|
||||
Email/ID of the approver (e.g., "kjh2064@gmail.com")
|
||||
Required. No default.
|
||||
|
||||
.PARAMETER ConfigVersion
|
||||
Configuration version string (e.g., "v1.0.0")
|
||||
Required. No default.
|
||||
|
||||
.PARAMETER CodeSha
|
||||
Git commit SHA (e.g., "acaa731b3f")
|
||||
Required. No default.
|
||||
|
||||
.PARAMETER ConnectionString
|
||||
PostgreSQL connection string.
|
||||
Default: $env:KARTSELL_POSTGRES
|
||||
|
||||
.EXAMPLE
|
||||
# Freeze a versionset (all parameters required)
|
||||
.\freeze-versionset.ps1 `
|
||||
-ModelId "00000000-0000-0000-0000-000000000001" `
|
||||
-DatasetId "00000000-0000-0000-0000-000000000002" `
|
||||
-ApprovedBy "kjh2064@gmail.com" `
|
||||
-ConfigVersion "v1.0.0" `
|
||||
-CodeSha "acaa731b3f"
|
||||
|
||||
.EXAMPLE
|
||||
# Will fail: missing -ConfigVersion
|
||||
.\freeze-versionset.ps1 `
|
||||
-ModelId "00000000-0000-0000-0000-000000000001" `
|
||||
-DatasetId "00000000-0000-0000-0000-000000000002" `
|
||||
-ApprovedBy "kjh2064@gmail.com" `
|
||||
-CodeSha "acaa731b3f"
|
||||
# Error: Cannot bind argument to parameter 'ConfigVersion' because it is an empty string.
|
||||
#>
|
||||
|
||||
[CmdletBinding()]
|
||||
param(
|
||||
[Parameter(Mandatory, HelpMessage = "Model UUID (e.g., 00000000-0000-0000-0000-000000000001)")]
|
||||
[ValidateScript({ $_ -match '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' })]
|
||||
[string]$ModelId,
|
||||
|
||||
[Parameter(Mandatory, HelpMessage = "Dataset UUID")]
|
||||
[ValidateScript({ $_ -match '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' })]
|
||||
[string]$DatasetId,
|
||||
|
||||
[Parameter(Mandatory, HelpMessage = "Approver email/ID (e.g., kjh2064@gmail.com)")]
|
||||
[ValidateScript({ $_ -match '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$' })]
|
||||
[string]$ApprovedBy,
|
||||
|
||||
[Parameter(Mandatory, HelpMessage = "Config version (e.g., v1.0.0)")]
|
||||
[ValidateScript({ $_ -match '^v[0-9]+\.[0-9]+\.[0-9]+' })]
|
||||
[string]$ConfigVersion,
|
||||
|
||||
[Parameter(Mandatory, HelpMessage = "Git commit SHA (at least 10 chars)")]
|
||||
[ValidateScript({ $_.Length -ge 10 })]
|
||||
[string]$CodeSha,
|
||||
|
||||
[string]$ConnectionString = $env:KARTSELL_POSTGRES
|
||||
)
|
||||
|
||||
$ErrorActionPreference = 'Stop'
|
||||
|
||||
Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor Cyan
|
||||
Write-Host "Phase 1: Freeze VersionSet" -ForegroundColor Cyan
|
||||
Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor Cyan
|
||||
|
||||
# Validate connection string
|
||||
if (-not $ConnectionString) {
|
||||
Write-Error "ConnectionString not provided and `$env:KARTSELL_POSTGRES not set. Aborting."
|
||||
exit 1
|
||||
}
|
||||
|
||||
Write-Host "`n[1/3] PRE-FLIGHT CHECK"
|
||||
Write-Host " Model ID: $ModelId"
|
||||
Write-Host " Dataset ID: $DatasetId"
|
||||
Write-Host " Approved By: $ApprovedBy"
|
||||
Write-Host " Config Version: $ConfigVersion"
|
||||
Write-Host " Code SHA: $CodeSha"
|
||||
Write-Host " Connection: $(($ConnectionString -split 'Password=')[0])***"
|
||||
|
||||
# Verify 0032 migration is deployed
|
||||
Write-Host "`n[2/3] VERIFY Migration 0032 deployed..."
|
||||
try {
|
||||
$conn = New-Object System.Data.NpgsqlClient.NpgsqlConnection($ConnectionString)
|
||||
$conn.Open()
|
||||
|
||||
$cmd = $conn.CreateCommand()
|
||||
$cmd.CommandText = @"
|
||||
SELECT schema_version FROM schema_version_history
|
||||
WHERE script_name = '0032_shadow_run_queued_status_contract.sql'
|
||||
LIMIT 1
|
||||
"@
|
||||
$result = $cmd.ExecuteScalar()
|
||||
|
||||
if ($null -eq $result) {
|
||||
throw "Migration 0032 NOT FOUND. Run DbMigrator first."
|
||||
}
|
||||
|
||||
Write-Host " ✅ Migration 0032 deployed (schema_version: $result)"
|
||||
$conn.Close()
|
||||
}
|
||||
catch {
|
||||
Write-Error " ❌ Pre-flight failed: $_`n`nCorrective: Run DbMigrator to deploy 0032_*.sql before freezing."
|
||||
exit 1
|
||||
}
|
||||
|
||||
# Insert into governance.model_version_registry
|
||||
Write-Host "`n[3/3] FREEZE VersionSet..."
|
||||
|
||||
try {
|
||||
$conn = New-Object System.Data.NpgsqlClient.NpgsqlConnection($ConnectionString)
|
||||
$conn.Open()
|
||||
|
||||
$correlationId = [System.Guid]::NewGuid()
|
||||
$now = [System.DateTime]::UtcNow
|
||||
|
||||
$cmd = $conn.CreateCommand()
|
||||
$cmd.CommandText = @"
|
||||
INSERT INTO governance.model_version_registry (
|
||||
id, model_id, dataset_id, status, approved_by, config_version, code_sha,
|
||||
effective_at, published_at, revision, correlation_id
|
||||
) VALUES (
|
||||
@id, @model_id, @dataset_id, 'FROZEN', @approved_by, @config_version, @code_sha,
|
||||
@effective_at, @published_at, 1, @correlation_id
|
||||
)
|
||||
ON CONFLICT (model_id, dataset_id) DO UPDATE SET
|
||||
status = 'FROZEN',
|
||||
approved_by = EXCLUDED.approved_by,
|
||||
config_version = EXCLUDED.config_version,
|
||||
code_sha = EXCLUDED.code_sha,
|
||||
effective_at = EXCLUDED.effective_at,
|
||||
revision = governance.model_version_registry.revision + 1,
|
||||
published_at = EXCLUDED.published_at
|
||||
RETURNING id, model_id, dataset_id, status, effective_at
|
||||
"@
|
||||
|
||||
$cmd.Parameters.AddWithValue("@id", [System.Guid]::NewGuid()) | Out-Null
|
||||
$cmd.Parameters.AddWithValue("@model_id", [System.Guid]$ModelId) | Out-Null
|
||||
$cmd.Parameters.AddWithValue("@dataset_id", [System.Guid]$DatasetId) | Out-Null
|
||||
$cmd.Parameters.AddWithValue("@approved_by", $ApprovedBy) | Out-Null
|
||||
$cmd.Parameters.AddWithValue("@config_version", $ConfigVersion) | Out-Null
|
||||
$cmd.Parameters.AddWithValue("@code_sha", $CodeSha) | Out-Null
|
||||
$cmd.Parameters.AddWithValue("@effective_at", $now) | Out-Null
|
||||
$cmd.Parameters.AddWithValue("@published_at", $now) | Out-Null
|
||||
$cmd.Parameters.AddWithValue("@correlation_id", $correlationId) | Out-Null
|
||||
|
||||
$reader = $cmd.ExecuteReader()
|
||||
if ($reader.Read()) {
|
||||
$insertedId = $reader['id']
|
||||
$insertedModelId = $reader['model_id']
|
||||
$insertedDatasetId = $reader['dataset_id']
|
||||
$insertedStatus = $reader['status']
|
||||
|
||||
Write-Host " ✅ Inserted governance.model_version_registry:"
|
||||
Write-Host " - ID: $insertedId"
|
||||
Write-Host " - Model: $insertedModelId"
|
||||
Write-Host " - Dataset: $insertedDatasetId"
|
||||
Write-Host " - Status: $insertedStatus"
|
||||
}
|
||||
$reader.Close()
|
||||
|
||||
# Update evaluation.dataset_manifest
|
||||
$cmd2 = $conn.CreateCommand()
|
||||
$cmd2.CommandText = @"
|
||||
INSERT INTO evaluation.dataset_manifest (
|
||||
id, dataset_id, model_id, status, freeze_reason,
|
||||
published_at, revision, correlation_id
|
||||
) VALUES (
|
||||
@id, @dataset_id, @model_id, 'FROZEN', 'Phase 1 VersionSet freeze',
|
||||
@published_at, 1, @correlation_id
|
||||
)
|
||||
ON CONFLICT (dataset_id, model_id) DO UPDATE SET
|
||||
status = 'FROZEN',
|
||||
freeze_reason = 'Phase 1 VersionSet freeze',
|
||||
revision = evaluation.dataset_manifest.revision + 1,
|
||||
published_at = EXCLUDED.published_at
|
||||
RETURNING id, dataset_id, model_id, status
|
||||
"@
|
||||
|
||||
$cmd2.Parameters.AddWithValue("@id", [System.Guid]::NewGuid()) | Out-Null
|
||||
$cmd2.Parameters.AddWithValue("@dataset_id", [System.Guid]$DatasetId) | Out-Null
|
||||
$cmd2.Parameters.AddWithValue("@model_id", [System.Guid]$ModelId) | Out-Null
|
||||
$cmd2.Parameters.AddWithValue("@published_at", $now) | Out-Null
|
||||
$cmd2.Parameters.AddWithValue("@correlation_id", $correlationId) | Out-Null
|
||||
|
||||
$reader2 = $cmd2.ExecuteReader()
|
||||
if ($reader2.Read()) {
|
||||
$mId = $reader2['id']
|
||||
$mDatasetId = $reader2['dataset_id']
|
||||
$mModelId = $reader2['model_id']
|
||||
$mStatus = $reader2['status']
|
||||
|
||||
Write-Host " ✅ Inserted evaluation.dataset_manifest:"
|
||||
Write-Host " - ID: $mId"
|
||||
Write-Host " - Dataset: $mDatasetId"
|
||||
Write-Host " - Model: $mModelId"
|
||||
Write-Host " - Status: $mStatus"
|
||||
}
|
||||
$reader2.Close()
|
||||
|
||||
$conn.Close()
|
||||
|
||||
Write-Host "`n✅ VersionSet FROZEN successfully"
|
||||
Write-Host " Correlation ID: $correlationId"
|
||||
Write-Host " Next: Run generate-shadow-run-identifiers.ps1 to create RunId/JobId"
|
||||
}
|
||||
catch {
|
||||
Write-Error " ❌ Failed to freeze VersionSet: $_"
|
||||
exit 1
|
||||
}
|
||||
|
||||
Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor Cyan
|
||||
@@ -1,90 +0,0 @@
|
||||
#!/usr/bin/env pwsh
|
||||
<#
|
||||
.SYNOPSIS
|
||||
Generate Phase 1 shadow run identifiers (RunId, JobId, JobRunId, CorrelationId, Idempotency-Key).
|
||||
|
||||
.DESCRIPTION
|
||||
Produces a JSON-formatted versionset.json file with all identifiers needed to enqueue Phase 1.
|
||||
Uses CRYPTOGRAPHIC random UUIDs and correlation for full traceability.
|
||||
|
||||
.PARAMETER OutputPath
|
||||
Path to save versionset.json (default: ./versionset.json in current directory)
|
||||
|
||||
.EXAMPLE
|
||||
.\generate-shadow-run-identifiers.ps1 -OutputPath ./phase1-versionset.json
|
||||
|
||||
.OUTPUTS
|
||||
JSON file with structure:
|
||||
{
|
||||
"phase1_run": {
|
||||
"runId": "UUID",
|
||||
"jobId": "UUID",
|
||||
"jobRunId": "UUID",
|
||||
"correlationId": "UUID",
|
||||
"idempotencyKey": "UUID",
|
||||
"generatedAt": "ISO8601 timestamp",
|
||||
"usage": "Use these IDs to enqueue Job 893 in Hangfire..."
|
||||
}
|
||||
}
|
||||
#>
|
||||
|
||||
[CmdletBinding()]
|
||||
param(
|
||||
[string]$OutputPath = "./versionset.json"
|
||||
)
|
||||
|
||||
$ErrorActionPreference = 'Stop'
|
||||
|
||||
Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor Cyan
|
||||
Write-Host "Phase 1: Generate Shadow Run Identifiers" -ForegroundColor Cyan
|
||||
Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor Cyan
|
||||
|
||||
Write-Host "`n[1/3] Generating cryptographic UUIDs..."
|
||||
|
||||
$runId = [System.Guid]::NewGuid()
|
||||
$jobId = [System.Guid]::NewGuid()
|
||||
$jobRunId = [System.Guid]::NewGuid()
|
||||
$correlationId = [System.Guid]::NewGuid()
|
||||
$idempotencyKey = [System.Guid]::NewGuid()
|
||||
|
||||
Write-Host " ✅ RunId: $runId"
|
||||
Write-Host " ✅ JobId: $jobId"
|
||||
Write-Host " ✅ JobRunId: $jobRunId"
|
||||
Write-Host " ✅ CorrelationId: $correlationId"
|
||||
Write-Host " ✅ IdempotencyKey: $idempotencyKey"
|
||||
|
||||
Write-Host "`n[2/3] Creating JSON payload..."
|
||||
|
||||
$payload = @{
|
||||
phase1_run = @{
|
||||
runId = $runId.ToString()
|
||||
jobId = $jobId.ToString()
|
||||
jobRunId = $jobRunId.ToString()
|
||||
correlationId = $correlationId.ToString()
|
||||
idempotencyKey = $idempotencyKey.ToString()
|
||||
generatedAt = [System.DateTime]::UtcNow.ToString("o")
|
||||
windowStart = "2024-01-02"
|
||||
windowEnd = "2024-09-10"
|
||||
usage = "Use these IDs to enqueue Job 893 (Phase 1 shadow run) in Hangfire. Command: `n Invoke-WebRequest -Uri 'http://127.0.0.1:5002/api/shadow-runs' -Method POST -Headers @{ 'X-KArtSell-User'='admin'; 'X-KArtSell-Role'='Admin'; 'Content-Type'='application/json' } -Body (ConvertTo-Json @{ modelId='<modelId>'; datasetId='<datasetId>'; windowStart='2024-01-02'; windowEnd='2024-09-10'; phaseFilter='All' })"
|
||||
}
|
||||
}
|
||||
|
||||
Write-Host " ✅ JSON payload generated"
|
||||
|
||||
Write-Host "`n[3/3] Writing to file: $OutputPath"
|
||||
|
||||
$json = $payload | ConvertTo-Json -Depth 10
|
||||
$json | Out-File -FilePath $OutputPath -Encoding UTF8
|
||||
|
||||
Write-Host " ✅ File saved: $(Resolve-Path $OutputPath)"
|
||||
|
||||
Write-Host "`n✅ IDENTIFIERS GENERATED`n"
|
||||
Write-Host $json -ForegroundColor Green
|
||||
|
||||
Write-Host "`nNext Steps:`n"
|
||||
Write-Host " 1. Copy the identifiers from above or read from $OutputPath"
|
||||
Write-Host " 2. Call POST /api/shadow-runs with modelId/datasetId from frozen VersionSet"
|
||||
Write-Host " 3. Hangfire will enqueue Job 893 with these correlation IDs"
|
||||
Write-Host " 4. Monitor logs: grep 'CorrelationId: $correlationId' app.log"
|
||||
|
||||
Write-Host "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" -ForegroundColor Cyan
|
||||
Reference in New Issue
Block a user