# Gitea API & External Data Sources

## Gitea Actions Secrets

**External API keys are stored in Gitea Actions Secrets (not in .env or code).**

**Location:** `https://gitea.taxbaik.com/kjh2064/KArtSell.Aegis/settings/actions/secrets`

**Available secrets:**
- `KRX_OPENAPI` — Korea Exchange OpenAPI (stock prices, indices, market data)
- `OPENDART_API` — OpenDart financial disclosure & quarterly reporting
- `KIS_APP_KEY` / `KIS_APP_SECRET` — Korea Investment & Securities trading API

**Usage in CI/CD (`.gitea/workflows/*.yml`):**
```yaml
env:
  KRX_OPENAPI: ${{ secrets.KRX_OPENAPI }}
  OPENDART_API: ${{ secrets.OPENDART_API }}
  KIS_APP_KEY: ${{ secrets.KIS_APP_KEY }}
  KIS_APP_SECRET: ${{ secrets.KIS_APP_SECRET }}
```

**For local development:** Ask team lead for local sandbox keys or use mock fixtures in tests.

---

## External Data APIs

### KRX OpenAPI (Korea Exchange)
**Official Guide:** https://openapi.krx.co.kr/contents/OPP/INFO/service/OPPINFO004.cmd

**Available Services:**
| Service | Link | Endpoint | Method | Auth |
|---------|------|----------|--------|------|
| **지수 (Indices)** | https://openapi.krx.co.kr/contents/OPP/USES/service/OPPUSES001_S1.cmd | `/svc/apis/idx/krx_dd_trd` | POST | AUTH_KEY header |
| **주식 (Stocks)** | https://openapi.krx.co.kr/contents/OPP/USES/service/OPPUSES002_S1.cmd | `/svc/apis/sco/...` | POST | AUTH_KEY header |
| **증권상품** | https://openapi.krx.co.kr/contents/OPP/USES/service/OPPUSES003_S1.cmd | `/svc/apis/sec/...` | POST | AUTH_KEY header |
| **채권** | https://openapi.krx.co.kr/contents/OPP/USES/service/OPPUSES004_S1.cmd | `/svc/apis/bon/...` | POST | AUTH_KEY header |
| **파생상품** | https://openapi.krx.co.kr/contents/OPP/USES/service/OPPUSES005_S1.cmd | `/svc/apis/drv/...` | POST | AUTH_KEY header |
| **일반상품** | https://openapi.krx.co.kr/contents/OPP/USES/service/OPPUSES006_S1.cmd | `/svc/apis/gen/...` | POST | AUTH_KEY header |
| **ESG** | https://openapi.krx.co.kr/contents/OPP/USES/service/OPPUSES007_S1.cmd | `/svc/apis/esg/...` | POST | AUTH_KEY header |

**Current Implementation:**
- ✅ Indices API: `/svc/apis/idx/krx_dd_trd` (POST + JSON body `{"basDd":"YYYYMMDD"}`)
- 📍 Location: `src/KArtSell.Modules.ModelOperations/ShadowRun/Services/KrxDataService.cs`
- 📍 Automatic Fallback: API failure → stub data (realistic values for testing)

### OpenDart API (Financial Disclosure)
**Official Guide:** https://opendart.fss.or.kr/guide/main.do

**Available API Groups:**
| Group | Link | Endpoint | Method | Auth | Purpose |
|-------|------|----------|--------|------|---------|
| **공시정보** | https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS001 | `/api/list.json` | GET | crtfc_key | Disclosure search |
| **정기보고서 주요정보** | https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS002 | `/api/...` | GET | crtfc_key | Annual report highlights |
| **정기보고서 재무정보** | https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS003 | `/api/...` | GET | crtfc_key | Quarterly financial data |
| **지분공시 종합정보** | https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS004 | `/api/...` | GET | crtfc_key | Equity disclosure |
| **주요사항보고서** | https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS005 | `/api/...` | GET | crtfc_key | Material event reports |
| **증권신고서** | https://opendart.fss.or.kr/guide/detail.do?apiGrpCd=DS006 | `/api/...` | GET | crtfc_key | Security registration |

**Current Implementation:**
- ✅ Disclosure Info: `/api/list.json?crtfc_key=KEY&corp_code=CODE` (GET)
- 📍 Location: `src/KArtSell.Host/Observability/OpenDartService.cs`
- 📍 Note: Current endpoint returns disclosure listings, not quarterly financial data
- 📍 For financial data: Use DS003 group (정기보고서 재무정보)

---

## Gitea API Automation (Optional)

### Environment Setup
```bash
# Enable Gitea API automation (optional)
$env:GITEA_TOKEN_TAXBAIK = "your-gitea-api-token"  # Windows PowerShell
export GITEA_TOKEN_TAXBAIK="your-gitea-api-token"  # macOS/Linux
```

### Common Tasks

**1. Verify PR Build Status**
```bash
# After successful build/test, comment on PR:
curl -X POST \
  -H "Authorization: token $GITEA_TOKEN_TAXBAIK" \
  -H "Content-Type: application/json" \
  -d '{"body":"✅ Build: PASS\n✅ Tests: 41/41 PASS\n✅ Security: Clean"}' \
  https://gitea.taxbaik.com/api/v1/repos/kjh2064/KArtSell.Aegis/issues/{PR_NUMBER}/comments
```

**2. Auto-Label PRs by Module**
```bash
# Label PR with affected modules
curl -X POST \
  -H "Authorization: token $GITEA_TOKEN_TAXBAIK" \
  -d '["architecture","performance","observability"]' \
  https://gitea.taxbaik.com/api/v1/repos/kjh2064/KArtSell.Aegis/issues/{PR_NUMBER}/labels
```

**3. Link to Tech Debt Registry**
```bash
# Reference debt in commit message (e.g., in CI job):
git commit -m "fix: CA1822 static method hints - TECH-001

Resolves technical debt from NoWarn bypass.
Part of quarterly paydown target (20% per quarter).

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>"
```

**4. Gitea Actions Integration** (`.gitea/workflows/ci.yml`)
```yaml
- name: Post PR verification results
  if: always()
  run: |
    BODY="## Verification Results
    - Build: ${{ job.status }}
    - Tests: 41/41 ✅
    - Debt Paydown: TECH-001 resolved
    
    [See full logs](https://gitea.taxbaik.com/kjh2064/KArtSell.Aegis/actions)"
    
    curl -X POST \
      -H "Authorization: token ${{ secrets.GITEA_TOKEN }}" \
      -H "Content-Type: application/json" \
      -d "{\"body\":\"$BODY\"}" \
      https://gitea.taxbaik.com/api/v1/repos/kjh2064/KArtSell.Aegis/issues/${{ github.event.pull_request.number }}/comments
```