init

2026-06-11 15:16:51 +09:00
commit 083505c952
30 changed files with 8530 additions and 0 deletions
@@ -0,0 +1,119 @@
+# AI Agentic Coding Setup — damn-my-slow-skt
+
+> **이 문서는 AI 에이전트(Codex, Claude Code, OpenCode 등)가 이 프로젝트를 개발/테스트할 때 필요한 환경 설정을 안내합니다.**
+> 사람 개발자가 AI 코딩 환경을 구성할 때도 참고하세요.
+
+---
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────┐
+│                   damn-my-slow-skt                    │
+│                                                      │
+│  CLI (Commander)                                     │
+│    ├── init      → 설정 wizard + 스케줄 등록          │
+│    ├── run       → Playwright → myspeed.skbroadband.com 측정    │
+│    ├── history   → SQLite/JSON DB 조회               │
+│    ├── report    → 월간 통계                          │
+│    └── schedule  → launchd/systemd/cron 등록         │
+│                                                      │
+│  Storage: SQLite (Node 22+) / JSON fallback (20+)   │
+│  Config:  ~/.damn-my-slow-isp/config-skt.yaml        │
+│  Terms:   SKT/SK Broadband agreement required        │
+│  No external DB/Redis/Docker required!              │
+└─────────────────────────────────────────────────────┘
+```
+
+---
+
+## Quick Setup (Local Development)
+
+```bash
+# 1. Install dependencies
+npm install
+
+# 2. Install Playwright browsers (headless Chromium)
+npx playwright install chromium
+
+# 3. Build
+npm run build
+
+# 4. Create test config (optional — only needed for actual SKT/SK브로드밴드 measurement)
+cp config.yaml.example ~/.damn-my-slow-isp/config-skt.yaml
+# Edit with your SKT/B world credentials and keep the terms block accepted only after reviewing the official URLs
+
+# 5. Run type check + lint + tests
+npm run typecheck
+npm run lint
+npm test
+```
+
+---
+
+## Codex Cloud Setup (Ubuntu 24.04)
+
+> **Codex Cloud는 Docker를 사용할 수 없습니다.**
+> 이 프로젝트는 외부 서비스(MySQL, Redis 등)가 불필요하므로 바로 사용 가능합니다.
+
+### Setup Script (네트워크 접근 가능 시)
+
+```bash
+#!/bin/bash
+# Codex Cloud: 초기 설정 (network enabled)
+npm install
+npx playwright install-deps chromium  # 시스템 의존성 (Ubuntu)
+npx playwright install chromium       # Chromium 브라우저 바이너리
+npm run build
+```
+
+### Maintain Script (브랜치 전환 후)
+
+```bash
+#!/bin/bash
+# Codex Cloud: 브랜치 체크아웃 후 유지보수
+npm install
+npm run build
+```
+
+---
+
+## Required Secrets
+
+| Secret | Required | Purpose |
+|--------|----------|---------|
+| SKT/B world ID/Password | **Yes** (for `run` only) | SKT/B world 계정 — `config-skt.yaml`에 설정 |
+| SKT/SK Broadband Terms Acceptance | **Yes** (for `run` only) | `terms` block in `config-skt.yaml`; generated by `init` or v4 migration |
+| Discord Webhook | No | 결과 알림 |
+| Telegram Token | No | 결과 알림 |
+
+> **개발/테스트 시에는 credential 없이도** `build`, `typecheck`, `lint`, `test` 모두 실행 가능합니다.
+> `run` 명령만 실제 SKT/B world 계정이 필요합니다. 단, 실행 전 현재 SKT/SK브로드밴드 공식 이용약관 동의(`terms.accepted`, `version`, `accepted_at`)도 필요합니다.
+
+---
+
+## Available Commands
+
+| Command | Description | Needs Credential |
+|---------|-------------|-----------------|
+| `npm run build` | TypeScript → JavaScript 컴파일 | No |
+| `npm run typecheck` | `tsc --noEmit` 타입 체크 | No |
+| `npm run lint` | ESLint 정적 분석 | No |
+| `npm test` | Vitest 단위 테스트 | No |
+| `npm run dev` | ts-node 개발 모드 | No |
+
+---
+
+## Tech Stack Summary
+
+| Component | Technology | Notes |
+|-----------|-----------|-------|
+| Language | TypeScript (ES2020, CommonJS) | `strict: true` |
+| Runtime | Node.js 20+ | Node 22+ 권장 (native SQLite) |
+| CLI | Commander + Inquirer + Chalk v4 | CJS 호환 버전 |
+| Browser | Playwright (Chromium) | SKT/SK브로드밴드 SLA 측정 자동화 |
+| Storage | node:sqlite / JSON fallback | 외부 DB 불필요 |
+| HTTP | Axios | 알림, npm 업데이트 체크 |
+| Config | YAML (js-yaml) | `~/.damn-my-slow-isp/config-skt.yaml`; v4 includes SKT terms acceptance |
+| Lint | ESLint + typescript-eslint | `eslint.config.mjs` |
+| Test | Vitest | `tests/` directory |