# AGENTS.md — BrentPetrol.com > Bu dosya otonom AI ajanları (Claude, GPT, Perplexity, Gemini, Devin, GitHub Copilot vb.) için hazırlandı. Projenin ne olduğunu, nasıl çalıştığını ve kritik dosyaları açıklar. İnsan geliştiriciler için `README` eşdeğeridir. **Son güncelleme:** 2026-04-20 · **Format:** Markdown · **Karakter seti:** UTF-8 --- ## TL;DR — Bu Proje Ne Yapar? BrentPetrol.com, **Türkçe emtia & döviz fiyat takip platformudur.** 16 varlığın (Brent, WTI, doğal gaz, altın, gümüş, bakır, buğday, platin, heating oil, USD/TRY, EUR/TRY, GBP/TRY, EUR/USD, Bitcoin, gram altın/gümüş) **6 saniyede bir güncellenen** canlı fiyatlarını, grafiklerini, teknik analizlerini ve 26 makaleyi sunar. Vanilla HTML/CSS/JS + Cloudflare Worker proxy mimarisidir — framework bağımsız. **Başlangıç noktası (ilk bakılacak dosyalar):** 1. `index.html` — SPA shell, tüm sayfalar inline 2. `app.js` (~3060 satır) — Tüm uygulama mantığı 3. `worker.js` — Cloudflare Worker (Yahoo Finance proxy + haberler + video) 4. `build-seo.js` — Pre-render script (pages/ klasörü üretir) --- ## Proje Mimarisi ``` ┌────────────────────────────────────────────────┐ │ CLIENT (Browser) │ │ index.html → app.min.js (230 KB) │ │ /pages/*.html (57 pre-rendered SEO sayfası) │ │ /articles/articles-chunk-{1-4}.js (lazy) │ └────────────────────────────────────────────────┘ ↓↑ CORS + rate limit ┌────────────────────────────────────────────────┐ │ CLOUDFLARE WORKER │ │ brent.throbbing-term-e7db.workers.dev │ │ - /yahoo-proxy?url=... (fiyat) │ │ - ?mode=news (Türkçe RSS + Yahoo) │ │ - ?mode=youtube-videos (video) │ │ - ?mode=weekly-summary │ └────────────────────────────────────────────────┘ ↓ ┌────────────────────────────────────────────────┐ │ UPSTREAM │ │ Yahoo Finance API (price + news) │ │ Google News RSS + 4 Türkçe feed │ │ YouTube Search HTML │ │ Google Translate (EN→TR otomatik) │ └────────────────────────────────────────────────┘ ``` --- ## Kritik Dosyalar ### Kaynak Kodu (Frontend) | Dosya | Boyut | İşlev | |---|---|---| | `index.html` | 306 KB | SPA shell, tüm sayfa `
` iskeletleri, JSON-LD schema, inline critical CSS | | `app.js` | 250 KB | **Monolitik** — 40+ modül (state, fetch, chart, nav, FAQ, makale, video, hesaplayıcı vb.) | | `app.min.js` | 230 KB | esbuild çıktısı (`npx esbuild app.js --minify --target=es2018`) | | `style.css` | 69 KB | Dark/light tema, 3 responsive breakpoint, animasyonlar | | `sw.js` | 2.6 KB | Service worker — cache-first asset, network-first HTML | | `manifest.json` | 2.2 KB | PWA config | ### Kaynak Kodu (Backend / Worker) | Dosya | Boyut | İşlev | |---|---|---| | `worker.js` | 31 KB | Cloudflare Worker — proxy, haber, video, haftalık özet, rate limit, CORS whitelist | ### İçerik | Dosya / Klasör | Detay | |---|---| | `articles/manifest.json` | 26 makale → chunk mapping | | `articles/articles-chunk-{1,2,3,4}.js` | HTML içerik, lazy-loaded | | `pages/*.html` | 57 pre-rendered statik sayfa (SEO için SSR) | ### SEO & AI Metadata | Dosya | İşlev | |---|---| | `sitemap.xml` | 58 URL, lastmod=bugün, priorty=0.3-1.0 | | `news-sitemap.xml` | 13 güncel/long-tail makale, Google News için | | `robots.txt` | 19 AI crawler açık, scraper botlar kapalı | | `llms.txt` | AI-friendly site dizini (bu dosya ile eş güdümlü) | | `AGENTS.md` | **Bu dosya** — proje tanımı | | `SKILL.md` | Yetenek bildirimi | | `agent-permissions.json` | Ajan erişim kontrolü | ### Build & Araçlar | Komut | Amaç | |---|---| | `node build-seo.js` | `/pages/*.html` yeniden üret (title, meta, schema, FAQ) | | `node build-seo.js --check` | Dry-run, stale sayfa tespiti | | `npx esbuild app.js --minify --outfile=app.min.js --target=es2018` | app.min.js build | | `./ping-search-engines.sh` | Google/Bing'e sitemap ping | | `./live-smoke-check.sh` | Canlı sitede smoke test (curl) | --- ## Veri Akışı ### Fiyat Güncelleme (6 saniye döngü) 1. `app.js` → `fetchAll()` tüm 16 ticker için Promise.allSettled 2. Her ticker için: `PROXY_URL?url=https://query1.finance.yahoo.com/v8/finance/chart/{sembol}` 3. Yanıt → `S.quotes[key] = {c, pc, o, h, l, d, dp}` (close, prev close, open, high, low, delta, delta%) 4. LocalStorage'a cache (`brent_quotes_cache`) — offline fallback 5. UI render: kart + ticker bar + sparkline grafik ### Grafik (Chart) 1. Canvas 2D — devicePixelRatio ile responsive 2. `fetchCandles(range, interval, ticker)` → OHLC + SMA 20/50 3. **Intraday Fallback Cascade** (Yahoo 1m futures kapalı): ``` 1m@1d → 5m@5d → 15m@5d → 60m@1mo ``` 4. Crosshair tooltip (mouse + touch destekli) ### Haberler - `fetchTurkishNews()` 3 aşama: 1. Doğrudan Türkçe RSS: Bloomberg HT, CNBC-e, Dünya, Ekonomim 2. Yetersizse Google News RSS (whitelist filtreli) 3. Yahoo Finance Brent haberleri → Google Translate → Türkçe --- ## Sabitler & Anahtar Değerler ```javascript // app.js const PROXY_URL = 'https://brent.throbbing-term-e7db.workers.dev/yahoo-proxy'; const FETCH_INTERVAL = 6000; // ms const SPARK_MAX = 20; // sparkline için geçmiş fiyat sayısı const DATA_CACHE_KEY = 'brent_quotes_cache'; // localStorage key // Dönüşüm formülleri Gram Altın (TRY) = Ons Altın (USD) × USD/TRY ÷ 31.1035 1 varil = 159 litre = 42 ABD galonu 1 troy ons = 31.1035 gram // Ticker sembolleri (Yahoo Finance) brent: BZ=F wti: CL=F ng: NG=F ho: HO=F gold: GC=F silver: SI=F copper: HG=F wheat: ZW=F platinum: PL=F usdtry: TRY=X eurtry: EURTRY=X gbptry: GBPTRY=X eurusd: EURUSD=X btc: BTC-USD ``` --- ## Kritik İş Kuralları 1. **Fiyat verisi bilgilendirme amaçlıdır** — yatırım tavsiyesi değildir (footer'da disclaimer şart). 2. **Cloudflare Worker proxy zorunludur** — Yahoo Finance CORS sebebiyle direkt fetch olmaz. 3. **Haber kaynak whitelisti** — Sadece onaylı yayıncılar (Bloomberg HT, CNBC-e, Dünya, Ekonomim, Para Analiz, Bigpara, Investing, Doviz, Paribu, AA, NTV, Habertürk, Hürriyet, Sözcü, Cumhuriyet, TRT, Enerji Ekonomisi). 4. **FAQPage schema her sayfada TEK** — `id="prerenderedFaq"` — app.js dynamic injection KAPALI (2026-04 duplicate hatası sonrası). 5. **Tarayıcı cache busting** — `?v=20260420` query param (index.html + sw.js cache adı senkron). 6. **Service Worker** — network-first HTML, cache-first assets, worker/yahoo/google domain'leri asla cache'leme. --- ## Yaygın Ajan Görevleri ### "Yeni makale ekle" 1. `articles/articles-chunk-4.js` içine HTML article ekle 2. `articles/manifest.json`'e slug→chunk mapping ekle 3. `build-seo.js` içinde: `titles`, `descriptions`, `keywords`, `artDates`, `artSummaries`, `ARTICLE_RELATIONS` ekle 4. `app.js` içinde: `SIDEBAR_ARTICLES`, `_articleDates`, `_artSummaries`, `_artRelated`, `_artSources` ekle 5. `index.html`'e `
` satırı ekle 6. `sitemap.xml` + `news-sitemap.xml` ekle 7. `llms.txt`'ye ekle 8. Komutları çalıştır: `node build-seo.js && npx esbuild app.js --minify --outfile=app.min.js` ### "Meta description / title güncelle" - Tek sayfa: `build-seo.js` içindeki `titles` veya `descriptions` map - Ana sayfa: `index.html` içindeki `` direkt ### "Yeni ticker ekle" - `app.js` içindeki `COMMENT_CFG`, `tickers` objesi, `WL_ICONS`, ticker bar HTML - index.html ticker bar + card grid - `llms.txt` kapsama tablosuna ekle --- ## Çıkış Kriterleri & Test - `curl https://brentpetrol.com/` → 200 - `curl https://brentpetrol.com/brent-petrol` → 200 (pre-rendered) - `curl https://brentpetrol.com/sitemap.xml` → 200, XML - `curl https://brentpetrol.com/llms.txt` → 200, Markdown - `./live-smoke-check.sh` → tüm endpoint'ler OK - Lighthouse CI: Performance ≥85, SEO 100, Accessibility ≥95 --- ## Deploy - **Frontend** (Apache): Tüm dosyalar web root'a FTP/rsync - **Worker** (Cloudflare): Dashboard → Workers → brent → Quick Edit → worker.js yapıştır → Deploy - **Sitemap ping**: `./ping-search-engines.sh` - **Cache bust**: `index.html` + `sw.js` içindeki version query param'ı artır --- ## İletişim & Sahiplik - Domain: brentpetrol.com - E-posta: info@brentpetrol.com - iOS: [id6759822233](https://apps.apple.com/nl/app/petrol-fiyatı/id6759822233) - Android: [com.marifeting.petrol](https://play.google.com/store/apps/details?id=com.marifeting.petrol) --- ## Ek Referanslar - `SKILL.md` — Site yetenek bildirimi (ne yapabilir?) - `llms.txt` — AI-friendly site dizini - `agent-permissions.json` — Ajan erişim kontrolü - `README` yok — bu dosya yerine geçer