kjh2064/KArtSell.Aegis
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
eb410c8076e697b405cb970720e8a6542114318d
KArtSell.Aegis/docs/GITEA_API_REFERENCE.md
T
kjh2064 07ad98ec12 refactor(docs): Optimize CLAUDE.md structure (47KB→12KB) + expand AGENTS.md v16.0 
## Summary
- **CLAUDE.md optimization:** Move engineering guidelines to AGENTS.md only (governance lock)
  - Removed: Governance, Testing Strategy, Observability details, Common Workflows, Guardrails
  - Kept: Project status, timeline, architecture high-level overview, quick reference
  - Result: 47KB → 12.1KB (75% reduction, well within 40KB limit)

- **AGENTS.md expansion:** Add 5 missing engineering procedure sections
  - v16.0 Testing Strategy (xUnit/Vitest/Playwright organization, commands, rules)
  - v16.0 Backend Architecture (Vertical Slice, Database/Migrations, Hangfire Job Design)
  - v16.0 Frontend Architecture (Registry-driven screens, KBX contracts, UI adapter boundary)
  - v16.0 Observability (Logging, Tracing, Dashboards, Metrics)
  - v16.0 Common Workflows (Adding Vertical Slices, Refactoring, Creating Jobs)

- **New companion docs** (no duplication, supplement AGENTS.md):
  - docs/ARCHITECTURE_DETAILED.md — Deep dive on backend/frontend patterns
  - docs/COMMON_WORKFLOWS.md — Workflow procedures with examples
  - docs/GITEA_API_REFERENCE.md — Gitea API + External data sources

## Governance (enforced)
- All engineering procedures now in AGENTS.md ONLY
- CLAUDE.md = project context only (status, timeline, overview)
- Companion docs reference AGENTS.md (no duplicate guidance)
- No conflicting guidance across multiple sources

## Result
- CLAUDE.md: 12.1KB ✅ (within 40KB limit)
- AGENTS.md: 44.8KB (comprehensive procedures)
- Single source of truth for all engineering guidelines

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
2026-08-16 14:47:41 +09:00

128 lines
5.6 KiB
Markdown
Raw Blame History

# 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
```
Reference in New Issue View Git Blame Copy Permalink