diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000000000000000000000000000000000000..e815a785a4cffbfd007a8c524a6a9e5f251c3cf8 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,24 @@ +# تصویر اجرا روی Hugging Face Spaces (Docker SDK) و Render. +# تفاوتش با Dockerfile سرور: درگاه ۷۸۶۰ (قرار HF)، بدون volume، و اجرای برنامه با boot.sh +# که از متغیرهای محیطی، دو حساب را می‌سازد و دروازه را روشن می‌کند. +FROM python:3.13-slim + +ENV PYTHONUNBUFFERED=1 \ + PYTHONDONTWRITEBYTECODE=1 \ + STATION_PORT=7860 + +WORKDIR /app +COPY . /app + +# کاربر غیر ریشه (قرار خود HF) + پوشه‌های نوشتنی برنامه +RUN useradd -m -u 1000 desk \ + && mkdir -p /app/data /app/config /app/export \ + && chmod +x /app/boot.sh \ + && chown -R desk:desk /app +USER desk + +EXPOSE 7860 +HEALTHCHECK --interval=30s --timeout=5s --retries=3 \ + CMD python -c "import urllib.request as u; u.urlopen('http://127.0.0.1:' + __import__('os').environ.get('PORT', '7860') + '/login', timeout=4)" + +CMD ["bash", "boot.sh"] diff --git a/HF-BUNDLE-MANIFEST.json b/HF-BUNDLE-MANIFEST.json new file mode 100644 index 0000000000000000000000000000000000000000..3ceb47ccf2fe9fc1af8ced37257f1b847309ac00 --- /dev/null +++ b/HF-BUNDLE-MANIFEST.json @@ -0,0 +1,26 @@ +{ + "name": "iran-desk-hf", + "files": 148, + "root": [ + "Dockerfile", + "README-HF-FA.md", + "README.md", + "boot.sh", + "desk", + "kodal-alert", + "render.yaml", + "station", + "strategies", + "tools" + ], + "key_files": { + "Dockerfile": "9b941f077aa74a77", + "README.md": "b00e906f1d15480b", + "boot.sh": "2c620a90ffba5922", + "README-HF-FA.md": "7fa085a85f68a812", + "render.yaml": "2adcdff48d7c2c42" + }, + "secret_like_literals_found": 0, + "phone_occurrences": 15, + "note": "ساخته‌شده برای میزبان ابری مجانی: درگاه ۷۸۶۰، دروازه از متغیرهای محیطی، بدون رمز در بسته" +} diff --git a/README-HF-FA.md b/README-HF-FA.md new file mode 100644 index 0000000000000000000000000000000000000000..ecfe5ef791e7d8adc711473ff3bc3b6c1c4ffe3b --- /dev/null +++ b/README-HF-FA.md @@ -0,0 +1,121 @@ +# بردن برنامه روی یک میزبان مجانی (Hugging Face Spaces) + +**این پرونده برای خودت است، نه برای کارفرما.** این‌جا نوشته‌ام چطور در حدود پنج دقیقه برنامه را +روی یک فضای مجانی بالا بیاوری، بدون سرور، بدون دامنه و **بدون کارت بانکی**. حساب کاربری را باید +خودت بسازی (ثبت‌نام به ایمیل خودت نیاز دارد)، ولی همهٔ کار فنی آماده است. + +## چه چیزی مجانی است و چه چیزی نیست (بی‌پرده) + +| موضوع | واقعیت | +| --- | --- | +| هزینه | صفر. HF برای Space با CPU رایگان (۲ vCPU و ۱۶ گیگ رم) کارت بانکی نمی‌خواهد | +| نشانی | آدرس `https` روی دامنهٔ خودشان (`‎*.hf.space`) با گواهی SSL | +| داده | روی دیسک موقت (حدود ۵۰ گیگ)؛ **با هر بازسازی پاک می‌شود** | +| خواب رفتن | بعد از حدود ۴۸ ساعت بی‌کاری می‌خوابد؛ اولین بازدید ۳۰ تا ۹۰ ثانیه بیدارش می‌کند | +| خصوصی بودن | Space مجانی **عمومی** است؛ یعنی آدرسش برای همه باز است. پس دروازه باید روشن بماند و رمزها محرمانه | +| دادهٔ واقعی | **روی HF دادهٔ واقعی معاملات نگذار.** این نسخه برای نمایش و آزمون است | + +## گام‌به‌گام + +۱. **حساب بساز:** [huggingface.co/join](https://huggingface.co/join) (ایمیل و رمز؛ کارت نمی‌خواهد). + +۲. **Space بساز:** [huggingface.co/new-space](https://huggingface.co/new-space) + - **Name:** مثل `desk-station` + - **SDK:** `Docker` · **Template:** `Blank` + - **Space hardware:** `CPU basic · FREE` + - **Visibility:** `Public` → بعد `Create Space` + +۳. **بستهٔ آماده را بالا بگذار.** روی رایانهٔ خودت: + +```bash +# ۱) بسته را بساز (همین یک فرمان؛ خروجی در MATERIALS/money/delivery/iran-desk-hf) +cd MATERIALS/money/gui/deploy +python3 make_hf.py --zip + +# ۲) ابزار آپلود +pip install -U huggingface_hub +hf auth login # توکن را از Settings → Access Tokens بساز و بچسبان + +# ۳) آپلود +hf upload <نام‌کاربری>/desk-station ../../../delivery/iran-desk-hf . --repo-type space +``` + +روش جایگزین با git: + +```bash +git clone https://huggingface.co/spaces/<نام‌کاربری>/desk-station +cp -r ../../../delivery/iran-desk-hf/. desk-station/ +cd desk-station && git add -A && git commit -m "ایستگاه تصمیم مشتقه" && git push +``` + +۴. **پنج مقدار محرمانه** را در `Settings` → `Variables and secrets` → `New secret` بگذار: + +| نام | مقدار | +| --- | --- | +| `STATION_ADMIN_ID` | شناسهٔ مدیر (مثل `mafhoom`) | +| `STATION_ADMIN_PASS` | رمز قوی پنل مدیریت (خودت بساز: ۱۲ نویسهٔ تصادفی) | +| `STATION_GUEST_ID` | شناسهٔ کارفرما (مثل `masoud`) | +| `STATION_GUEST_PASS` | رمز قوی کارفرما (این را به او می‌دهی) | +| `STATION_GUEST_OFF` | اختیاری: `1` یعنی کارفرما فعلاً نتواند وارد شود | + +اگر این‌ها را نگذاری، برنامه موقع بالا آمدن **خودش رمز تصادفی می‌سازد و در گزارش (Logs) چاپ می‌کند** — +کار می‌کند، ولی رمز در گزارش می‌ماند؛ برای آزمون سریع خوب است، برای کار جدی نه. + +۵. وقتی وضعیت Space روی `Running` رفت، این آدرس را باز کن و یک‌بار خودت با حساب مدیر وارد شو: + +``` +https://<نام‌کاربری>-desk-station.hf.space/login +``` + +بعد همان آدرس `‎/login` را با **رمز کارفرما** برایش بفرست. رمز مدیر را هرگز نفرست. + +## مهم: دو راه HF داریم و یکی از آن‌ها مجانی است + +آزمودیم (۲۲ سپتامبر ۲۰۲۶): Space **داکری** روی حساب مجانی HF پاسخ ۴۰۲ می‌دهد و اشتراک PRO لازم +دارد. ولی Space **ایستا** برای همه مجانی است. پس دو ابزار داریم: + +| راه | فرمان | چه می‌دهد | +| --- | --- | --- | +| نمونهٔ ثابت (مجانی) | `./activate_demo_site.sh` | خودِ رابط + تمام خروجی‌های واقعی، روی یک لینک عمومی ثابت، بدون کارتی | +| برنامهٔ زندهٔ داکری | `./activate_hf.sh` | اگر روزی PRO داشتی: سرور کامل با دروازهٔ ورود و دادهٔ زنده | + +نمونهٔ ثابت از این‌ها ساخته می‌شود: `tools/record_static_demo.mjs` (ضبط پاسخ‌های واقعی در حاشیهٔ +همان آزمون ۱۹۲ بررسی) → `deploy/make_demo_site.py` (ساخت سایت ایستا + لایهٔ پاسخ‌های ضبط‌شده) → +`deploy/huggingface/activate_demo_site.py` (نشر + آزمودن زنده با `tools/check_demo_site.mjs`). + +## آزمودن سمت خودت (پیش از آپلود) + +خود `boot.sh` همان کاری را می‌کند که HF می‌کند؛ می‌توانی محلی هم بیازمایی: + +```bash +cd ../../../delivery/iran-desk-hf +STATION_ADMIN_PASS='<رمز-آزمون-مدیر>' STATION_GUEST_ID=masoud STATION_GUEST_PASS='<رمز-آزمون-کارفرما>' \ + STATION_PORT=7860 bash boot.sh +# در مرورگر: http://127.0.0.1:7860 (بدون ورود ۴۰۱ · با حساب کارفرما ۲۰۰ · پنل مدیر ۴۰۳ برای کارفرما) +``` + +## بیدار نگه داشتن (اختیاری، مجانی) + +Space مجانی بعد از حدود ۴۸ ساعت بی‌کاری می‌خوابد. اگر می‌خواهی همیشه بیدار باشد، در یک سرویس +زمان‌بند مجانی (مثل cron-job.org) یک کار بساز که هر یک ساعت آدرس `https://<...>.hf.space/login` +را باز کند. این کار هم مجانی است، ولی تضمین آپ‌تایم نمی‌دهد. + +## خاموش کردن و حذف + +- **خاموش موقت:** در `Settings` → `Pause this Space` +- **حذف کامل:** در `Settings` → `Delete this Space` +- **قطع فقط کارفرما، بدون خواباندن برنامه:** `STATION_GUEST_OFF=1` را در Secrets بگذار (یا در + پنل مدیریت نشست‌های مهمان را ببند) + +هیچ‌چیز این‌جا گروگان نیست: هر وقت سرور یا دامنهٔ خودت را آوردی، همین برنامه را با پوشهٔ `deploy/` +روی آن ببر و Space را حذف کن؛ داده و رمزها سمت خودت می‌مانند. + +## اگر HF را نخواستی: Render + +`deploy/render/render.yaml` هم گذاشته‌ام (یک میزبان مجانی دیگر، بدون کارت بانکی). فرقش: فقط +۵۱۲ مگ رم و ۰٫۱ پردازنده دارد، **بعد از ۱۵ دقیقه بی‌کاری می‌خوابد** و بیدار شدنش ۳۰ تا ۶۰ ثانیه +طول می‌کشد؛ برای نمایش زندهٔ نیم‌ساعته خوب نیست، برای تست‌های گاه‌به‌گاه به‌کار می‌آید. راهش: +کد را روی یک مخزن GitHub بگذار و در Render گزینهٔ `Blueprint` را انتخاب کن. + +> **پرسش باز:** اگر حساب HF یا GitHub داری و می‌خواهی خودم گام‌ها را با تو جلو ببرم، بگو کدام گام +> گیر کردی؛ ولی ساختن حساب و زدن توکن باید دست خودت باشد (رمز و ایمیل تو را نمی‌پرسم). diff --git a/README.md b/README.md new file mode 100644 index 0000000000000000000000000000000000000000..43a427389fdc5f3ba981392dc3fe0f2fb713f824 --- /dev/null +++ b/README.md @@ -0,0 +1,5 @@ +# Iran Desk Station — Docker bundle (for Render / any Docker host) + +Full trading-decision station (Python stdlib server). Build: `docker build .` then run with env: +`STATION_ADMIN_ID`, `STATION_ADMIN_PASS`, `STATION_GUEST_ID`, `STATION_GUEST_PASS`. +Listens on `$PORT` (default 7860). Health check: `/login`. diff --git a/boot.sh b/boot.sh new file mode 100644 index 0000000000000000000000000000000000000000..e9642502d705ebf71f18d677db180414383c86a7 --- /dev/null +++ b/boot.sh @@ -0,0 +1,46 @@ +#!/usr/bin/env bash +# بالا آوردن ایستگاه روی میزبان ابری (Hugging Face Spaces یا Render). +# +# ترتیب کار: از محیط، شناسه و رمزها را می‌خواند → دروازه را روشن می‌کند → برنامه را اجرا می‌کند. +# اگر رمزی در محیط نبود، خودش رمز قوی می‌سازد و در گزارش چاپ می‌کند (برای آزمون سریع). +set -euo pipefail +HERE="$(cd "$(dirname "$0")" && pwd)" +cd "$HERE/station" # برنامه، پوشهٔ «desk» و «kodal-alert» را همسایهٔ خودش می‌خواهد + +# میزبان‌ها درگاه را خودشان می‌دهند: HF انتظار ۷۸۶۰ دارد، Render متغیر PORT می‌فرستد. +PORT="${PORT:-${STATION_PORT:-7860}}" +ADMIN_ID="${STATION_ADMIN_ID:-mafhoom}" +GUEST_ID="${STATION_GUEST_ID:-masoud}" +ADMIN_PASS="${STATION_ADMIN_PASS:-}" +GUEST_PASS="${STATION_GUEST_PASS:-}" + +gen() { python3 -c "import secrets; print('Desk-' + secrets.token_hex(4))"; } + +echo "── ایستگاه تصمیم مشتقه، نسخهٔ میزبان ابری ──" +echo " درگاه: $PORT · شناسهٔ مدیر: $ADMIN_ID · شناسهٔ کارفرما: $GUEST_ID" + +if [ -z "$ADMIN_PASS" ]; then + ADMIN_PASS="$(gen)" + echo " ⚠️ STATION_ADMIN_PASS نبود؛ رمز مدیر ساخته شد: $ADMIN_PASS" + echo " این رمز را در Secrets بگذار (این پیام فقط برای خودت است، ولی در گزارش می‌ماند)." +fi +python3 adminauth.py --set-id "$ADMIN_ID" --set-pass "$ADMIN_PASS" >/dev/null + +if [ -z "$GUEST_PASS" ]; then + GUEST_PASS="$(gen)" + echo " ⚠️ STATION_GUEST_PASS نبود؛ رمز کارفرما ساخته شد: $GUEST_PASS" +fi +python3 gate.py --sync-admin >/dev/null +python3 gate.py --guest-id "$GUEST_ID" --guest-pass "$GUEST_PASS" >/dev/null +if [ "${STATION_GUEST_OFF:-0}" = "1" ]; then + python3 gate.py --guest-off >/dev/null + echo " کارفرما فعلاً بسته است (STATION_GUEST_OFF=1)." +else + python3 gate.py --guest-on >/dev/null +fi +python3 gate.py --on >/dev/null +echo " دروازه روشن است: بدون شناسه و رمز، هیچ صفحه‌ای باز نمی‌شود." +python3 gate.py --status | sed 's/^/ /' + +echo " آماده است. آدرس درگاه: 0.0.0.0:$PORT (بدون ورود: 401)" +exec python3 -m web_server --port "$PORT" --host 0.0.0.0 --no-browser diff --git a/desk/README-FA.md b/desk/README-FA.md new file mode 100644 index 0000000000000000000000000000000000000000..4dda3556711b7d1593bd743d2a7aeeb74eb7b2f1 --- /dev/null +++ b/desk/README-FA.md @@ -0,0 +1,100 @@ +# میز معاملات (دستیار تصمیم با تأیید انسان) — راهنمای فارسی + +نسخهٔ ۰٫۱٫۰ · صفر وابستگی · اجرا روی ویندوز یا لینوکس · بدون اینترنت هم کار می‌کند + +## این برنامه چه کار می‌کند + +۱. یک **اسنپ‌شات بازار** (پروندهٔ JSON ساده) را می‌گیرد: قیمت پایه، زنجیرهٔ آپشن، آتی، اوراق تبعی، وجه تضمین. +۲. هر ردیف را روی **موتور ریاضی** (`../tools/derivatives_scout.py`) می‌گذارد: پایهٔ نقدی‌آتی، باکس اسپرد، تبعی، پوشش‌داده‌شده، تساوی پوت‌کال. +۳. خبرها و هشدارهای **دیده‌بان کدال** را به همان نمادها می‌چسباند (خبر به‌تنهایی سیگنال نیست؛ خبرها موتور را دوباره حساب‌شده نگه می‌دارند). +۴. **دروازه‌های ریسک** را اعمال می‌کند و اندازهٔ هر موقعیت را از بودجهٔ وجه تضمین درمی‌آورد. +۵. یک **داشبورد HTML** می‌سازد و **بستهٔ سفارش** چاپ می‌کند تا **انسان** آن را در سامانهٔ کارگزاری اجرا کند. + +## این برنامه چه کار نمی‌کند (مهم) + +- **هیچ سفارشی ارسال نمی‌کند.** طبق ابلاغیهٔ مهر ۱۳۹۹ سازمان بورس، معاملات الگوریتمی و تقسیم سفارشات توسط مشتریان برخط در بورس و فرابورس «تا اطلاع ثانوی» ممنوع است و کارگزاران موظف‌اند چنین دسترسی‌هایی را ببندند. +- سود تضمین نمی‌کند، قیمت پیش‌بینی نمی‌کند، و هیچ‌جا «سیگنال خرید» به معنای توصیه نمی‌دهد. خروجی، «تفاوت ریاضی با نرخ سد» است. + +## چرخهٔ کار (هفت گام) + +``` +اسنپ‌شات بازار → موتور ریاضی → چسباندن هشدارهای کدال → دروازه‌های ریسک + ↓ +اندازه‌گذاری از بودجهٔ وجه تضمین → داشبورد تصمیم → تأیید یا رد انسانی → بستهٔ سفارش → اجرا در کارگزاری +``` + +## اجرا + +```bash +python desk.py selftest +python desk.py run --market market-demo.json --kodal-db ../kodal-alert/data/demo.sqlite3 +python desk.py list --status pending +python desk.py approve 3ed6c3f0710c --note "ریسک پذیرفته شد و منبع خبر هم بررسی شد" +python desk.py reject f9c3112e6ff2 --note "عمق بازار کافی نیست" +python desk.py packet 3ed6c3f0710c +python -m unittest discover -s tests # ۲۶ آزمون واحد +``` + +## قالب اسنپ‌شات بازار + +```json +{"as_of": "2026-09-22", "hurdle": 0.39, "capital": 20000000000, + "rows": [ + {"symbol": "اهرم", "kind": "basis", "spot": 20000, "future": 22800, "days": 90, + "margin_per_contract": 20000000, "unit": "قرارداد", + "liquidity_contracts_per_day": 900, "spread_pct": 0.005}, + {"symbol": "فولاد", "kind": "covered_call", "spot": 7000, "strike": 7600, + "premium": 400, "days": 45, "margin_per_contract": 7000, "unit": "سهم"} + ]} +``` + +انواع `kind`: `basis` (پایهٔ نقدی‌آتی) · `box` (باکس اسپرد) · `tabei` (اوراق اختیار فروش تبعی) · `covered_call` (فروش کال پوشش‌داده‌شده) · `parity` (تساوی پوت‌کال). + +کلیدهای هر ردیف: `symbol`، `kind`، پارامترهای ریاضی همان راهبرد (مثل `spot`، `future`، `strike`، `premium`، `put_price`، `days`)، `margin_per_contract` (وجه تضمین یا بهای هر واحد)، `unit` (قرارداد یا سهم)، `liquidity_contracts_per_day` و `spread_pct` برای دروازهٔ نقدشوندگی. + +## قواعد ریسک پیش‌فرض (`config.json`) + +| قاعده | پیش‌فرض | معنا | +|---|---|---| +| `max_margin_pct` | ۲۰ درصد | سقف کل سرمایهٔ درگیر در وجه تضمین | +| `max_position_pct` | ۳۵ درصد از بودجه | سقف هر موقعیت، تا یک معامله همهٔ بودجه را نخورد | +| `max_positions` | ۳ | سقف موقعیت‌های تأییدشدهٔ هم‌زمان | +| `min_liquidity_contracts_per_day` | ۲۰ | کف نقدشوندگی | +| `max_spread_pct` | ۳ درصد | سقف اسپرد خرید‌وفروش | +| `min_edge_arbitrage_pct` | ۳ واحد درصد | کف حاشیه برای راهبردهای آربیتراژی | +| `min_edge_leveraged_pct` | ۵ واحد درصد | کف حاشیه برای راهبردهای اهرمی | + +تأیید انسانی هم از همین سقف‌ها عبور نمی‌کند: اگر تأیید سیگنالی سقف ریسک را رد کند، برنامه با کد خروج ۳ متوقف می‌شود و فقط با `--force` و ثبت دلیل در دفتر، رد می‌شود. + +## هفت چیزی که در نمونهٔ آماده می‌بینید + +۱. «اهرم · پایهٔ نقدی‌آتی» با حاشیهٔ ۲۹٫۴۸ واحد درصد منتظر تأیید است، چون نرخ تلویحی آتی از نرخ سد جلوتر است. +۲. «فولاد · پوشش‌داده‌شده» با حاشیهٔ ۱۷٫۵۶ واحد درصد منتظر است؛ پرمیوم گران است. +۳. «کگل · تبعی» با حاشیهٔ ۳٫۳۶ واحد درصد به‌سختی از دروازه رد می‌شود. +۴. «خساپا · تبعی» رد می‌شود، چون بازده تضمینی‌اش از صندوق درآمد ثابت کمتر است؛ این درسِ اصلی این بازار است. +۵. «وبملت · تساوی پوت‌کال» رد می‌شود، چون نیمهٔ دیگر آربیتراژ به فروش استقراضی نیاز دارد و در ایران ممکن نیست. +۶. «شپنا · باکس اسپرد» با وجود بازده خوب رد می‌شود، چون حجم روزانه‌اش ۱۲ و اسپردش ۴٫۵ درصد است. +۷. «طلا · پایهٔ نقدی‌آتی» رد می‌شود، چون مبنای آتی از نرخ صندوق درآمد ثابت کمتر است. + +## وصل شدن به دیده‌بان کدال + +پایگاه‌دادهٔ دیده‌بان را با `--kodal-db` بدهید. برنامه سه کار می‌کند: + +- هشدارهای همان نماد را در داشبورد زیر سیگنال نشان می‌دهد. +- برای نمادهایی که خبر مهم دارند ولی در اسنپ‌شات بازار نیستند، «کار بازبینی» می‌سازد. +- برای سیگنال‌های بدون پشتوانهٔ خبری و حاشیهٔ کم، دروازهٔ اولویت‌پایین فعال می‌شود. + +## اجرا در شرایط ایران + +- روی رایانهٔ خودتان اجرا کنید؛ هیچ سرویس ابری و هیچ پرداخت ارزی لازم نیست. +- اگر اینترنت یا سامانهٔ داده در دسترس نیست، اسنپ‌شات را دستی از سامانهٔ کارگزاری در `market.json` وارد کنید و همان را اجرا کنید. +- پایگاه‌داده روی دیسک است؛ قطعی برق تصمیم‌های ثبت‌شده را از بین نمی‌برد و اجرای بعدی، وضعیت‌ها را حفظ می‌کند. +- تصمیم‌های انسان (تأیید و رد) قفل می‌شوند و اجرای دوبارهٔ `run` آن‌ها را بازنویسی نمی‌کند. + +## قدم بعدی + +اتصال خودکار دادهٔ `tsetmc` و زنجیرهٔ آپشن، و گزارش روزانه‌ای که بازده انتظاری را با نتیجهٔ واقعی مقایسه کند. تا آن زمان، ورود دستی اسنپ‌شات کامل است. + +## تهیه‌کننده + +✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · 📱 [+989126630554](tel:+989126630554) · ✈️ [Telegram: Mojarabian](https://t.me/Mojarabian) · 📸 [Instagram: Mojarabian.Art](https://www.instagram.com/Mojarabian.Art/) diff --git a/desk/config.json b/desk/config.json new file mode 100644 index 0000000000000000000000000000000000000000..99f6ed2b2b079095ab69acb6cad7c83a60f2f42c --- /dev/null +++ b/desk/config.json @@ -0,0 +1,18 @@ +{ + "capital": 5000000000, + "hurdle": 0.39, + "min_edge_arbitrage_pct": 3.0, + "min_edge_leveraged_pct": 5.0, + "max_margin_pct": 0.2, + "max_positions": 3, + "min_liquidity_contracts_per_day": 20, + "max_spread_pct": 0.03, + "alert_score_threshold": 60, + "desk_db": "", + "report_path": "", + "credit": "تهیه‌کننده: Masoud Mojarabian · https://www.instagram.com/Mojarabian.Art/ · tel:+989126630554 · https://t.me/Mojarabian", + "report_title": "میز معاملات — داشبورد تصمیم", + "max_position_pct": 0.35, + "max_plausible_arb_pct": 250.0, + "max_plausible_lev_pct": 400.0 +} \ No newline at end of file diff --git a/desk/desk.py b/desk/desk.py new file mode 100644 index 0000000000000000000000000000000000000000..e5d5a2e64aab11c8d3e734a2ce631b43060f1002 --- /dev/null +++ b/desk/desk.py @@ -0,0 +1,775 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""میز معاملات (دستیار تصمیم با تأیید انسان) — نسخهٔ ۰٫۱٫۰ + +این برنامه سه کار می‌کند: + ۱. دادهٔ بازار (اسنپ‌شات JSON) را روی موتور ریاضی مشتقه می‌گذارد. + ۲. هشدارهای «دیده‌بان کدال» را به سیگنال‌های ریاضی می‌چسباند. + ۳. بستهٔ سفارش آماده می‌کند تا **انسان** آن را در سامانهٔ کارگزاری اجرا کند. + +هیچ سفارشی از این برنامه ارسال نمی‌شود. علت: معاملات الگوریتمی خودکار در +بورس و فرابورس ایران، طبق ابلاغیهٔ مهر ۱۳۹۹ سازمان بورس، «تا اطلاع ثانوی» ممنوع است. + +دستورها: + python desk.py selftest + python desk.py run --market market-demo.json --kodal-db ../kodal-alert/data/demo.sqlite3 + python desk.py list --status pending + python desk.py approve 3f2a... --note "ریسک پذیرفته شد" + python desk.py reject 3f2a... --note "نقدشوندگی کم" + python desk.py packet 3f2a... +""" +from __future__ import annotations + +import argparse +import hashlib +import html +import importlib.util +import json +import sqlite3 +import sys +from dataclasses import dataclass, field +from datetime import datetime, timezone +from pathlib import Path + +VERSION = "0.1.0" +BASE = Path(__file__).resolve().parent +DEFAULT_DB = BASE / "data" / "desk.sqlite3" +DEFAULT_REPORT = BASE / "data" / "dashboard.html" +SCOUT_PATH = (BASE.parent / "tools" / "derivatives_scout.py").resolve() +CREDIT = ("تهیه‌کننده: Masoud Mojarabian · https://www.instagram.com/Mojarabian.Art/ · " + "tel:+989126630554 · https://t.me/Mojarabian") + +DEFAULT_CONFIG: dict = { + "capital": 5_000_000_000, + "hurdle": 0.39, + "min_edge_arbitrage_pct": 3.0, + "min_edge_leveraged_pct": 5.0, + "max_margin_pct": 0.20, + "max_positions": 3, + "max_position_pct": 0.35, + "min_liquidity_contracts_per_day": 20, + "max_spread_pct": 0.03, + "alert_score_threshold": 60, + "max_plausible_arb_pct": 250.0, # سقف باورپذیری بازده سالانهٔ راهبردهای آربیتراژی + "max_plausible_lev_pct": 400.0, # سقف باورپذیری بازده سالانهٔ راهبردهای اهرمی + "desk_db": "", + "report_path": "", + "credit": CREDIT, + "report_title": "میز معاملات — داشبورد تصمیم", +} + +# ---------------------------------------------------------------- دسترسی به موتور ریاضی +_SCOUT_CACHE: dict[str, object] = {} + + +def load_scout(path: Path = SCOUT_PATH): + """موتور ریاضی مشتقه را از پروندهٔ همسایه بارگذاری می‌کند (بدون نصب بسته). + + نتیجه در حافظه می‌ماند: بی این کش، پس‌آزمایی هر سطر یک بار کل موتور را از نو + بارگذاری می‌کرد و صد سطر تاریخ چند ثانیه طول می‌کشید. + """ + key = str(Path(path).resolve()) + cached = _SCOUT_CACHE.get(key) + if cached is not None: + return cached + p = Path(path) + if not p.exists(): + raise FileNotFoundError(f"موتور ریاضی پیدا نشد: {path}") + spec = importlib.util.spec_from_file_location("derivatives_scout", str(p)) + module = importlib.util.module_from_spec(spec) + assert spec.loader is not None + # ثبت در sys.modules پیش از اجرا لازم است، وگرنه dataclass داخل موتور خطا می‌دهد + sys.modules["derivatives_scout"] = module + spec.loader.exec_module(module) + _SCOUT_CACHE[key] = module + return module + + +# ---------------------------------------------------------------- ابزار پایه +def now_iso() -> str: + return datetime.now(timezone.utc).isoformat(timespec="seconds") + + +def g2j(gy: int, gm: int, gd: int) -> tuple[int, int, int]: + g_d_m = [0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334] + gy2 = gy + 1 if gm > 2 else gy + days = 355666 + (365 * gy) + ((gy2 + 3) // 4) - ((gy2 + 99) // 100) + ((gy2 + 399) // 400) + gd + g_d_m[gm - 1] + jy = -1595 + 33 * (days // 12053) + days %= 12053 + jy += 4 * (days // 1461) + days %= 1461 + if days > 365: + jy += (days - 1) // 365 + days = (days - 1) % 365 + jm = 1 + days // 31 if days < 186 else 7 + (days - 186) // 30 + jd = 1 + days % 31 if days < 186 else 1 + (days - 186) % 30 + return jy, jm, jd + + +def fa_time(dt: datetime | None = None) -> str: + dt = dt or datetime.now(timezone.utc) + jy, jm, jd = g2j(dt.year, dt.month, dt.day) + return f"{jy:04d}/{jm:02d}/{jd:02d} {dt.hour:02d}:{dt.minute:02d}" + + +def log(msg: str) -> None: + print(f"[{fa_time()}] {msg}") + + +def load_config(path: str | None = None) -> dict: + cfg = json.loads(json.dumps(DEFAULT_CONFIG, ensure_ascii=False)) + p = Path(path) if path else BASE / "config.json" + if p.exists(): + try: + user = json.loads(p.read_text(encoding="utf-8")) + for k, v in user.items(): + if isinstance(v, dict) and isinstance(cfg.get(k), dict): + cfg[k].update(v) + else: + cfg[k] = v + except json.JSONDecodeError as e: + log(f"تنظیمات خوانده نشد ({e})؛ پیش‌فرض به کار می‌رود.") + return cfg + + +# ---------------------------------------------------------------- داده‌ها +@dataclass +class Signal: + sid: str + symbol: str + kind: str + name: str + annualized_pct: float | None + score_pp: float + go: bool + detail: dict = field(default_factory=dict) + margin_per_contract: float = 0.0 + contracts: int = 0 + margin_locked: float = 0.0 + status: str = "pending" + gate_note: str = "" + alerts: list[dict] = field(default_factory=list) + + @property + def unit(self) -> str: + return str(self.detail.get("unit") or "قرارداد") + + def as_row(self) -> tuple: + return (self.sid, now_iso(), self.symbol, self.kind, self.name, + self.annualized_pct, self.score_pp, int(self.go), + json.dumps(self.detail, ensure_ascii=False), self.margin_per_contract, + self.contracts, self.margin_locked, self.status, self.gate_note, + json.dumps(self.alerts, ensure_ascii=False)) + + @staticmethod + def from_row(row) -> "Signal": + (sid, _ts, symbol, kind, name, annualized, score_pp, go, + detail, margin, contracts, locked, status, gate_note, alerts) = row + return Signal(sid=sid, symbol=symbol, kind=kind, name=name, annualized_pct=annualized, + score_pp=score_pp, go=bool(go), detail=json.loads(detail or "{}"), + margin_per_contract=margin or 0.0, contracts=contracts or 0, + margin_locked=locked or 0.0, status=status, gate_note=gate_note or "", + alerts=json.loads(alerts or "[]")) + + +SIGNAL_SELECT = ("SELECT sid, ts, symbol, kind, name, annualized, score_pp, go, detail, " + "margin_per_contract, contracts, margin_locked, status, gate_note, alerts FROM signals") + + +class Desk: + def __init__(self, path: Path | str = DEFAULT_DB): + self.path = Path(path) + self.path.parent.mkdir(parents=True, exist_ok=True) + self.conn = sqlite3.connect(str(self.path)) + self.conn.executescript(""" + CREATE TABLE IF NOT EXISTS signals ( + sid TEXT PRIMARY KEY, ts TEXT, symbol TEXT, kind TEXT, name TEXT, + annualized REAL, score_pp REAL, go INTEGER, detail TEXT, + margin_per_contract REAL, contracts INTEGER, margin_locked REAL, + status TEXT, gate_note TEXT, alerts TEXT); + CREATE TABLE IF NOT EXISTS decisions ( + id INTEGER PRIMARY KEY AUTOINCREMENT, ts TEXT, sid TEXT, action TEXT, note TEXT); + """) + self.conn.commit() + + # ── بستن تمیز (پایان کار / پرونده‌های موقت) + def close(self) -> None: + """پیوند پایگاه‌داده را می‌بندد. چند بار صدا زدنش بی‌خطر است.""" + try: + self.conn.close() + except Exception: # noqa: BLE001 — بستن نباید برنامه را بیندازد + pass + + def __enter__(self) -> "Desk": + return self + + def __exit__(self, *exc) -> None: + self.close() + + def __del__(self) -> None: + self.close() + + + # ---------- ثبت سیگنال + def upsert(self, sig: Signal, keep_status: bool = True) -> None: + old = self.get(sig.sid) + if old and keep_status: + sig.status = old.status + if old.gate_note and not sig.gate_note: + sig.gate_note = old.gate_note + self.conn.execute("DELETE FROM signals WHERE sid = ?", (sig.sid,)) + self.conn.execute( + "INSERT INTO signals VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)", sig.as_row()) + self.conn.commit() + + def get(self, sid: str) -> Signal | None: + cur = self.conn.execute(SIGNAL_SELECT + " WHERE sid = ?", (sid,)) + row = cur.fetchone() + return Signal.from_row(row) if row else None + + def all(self, status: str | None = None, limit: int = 200) -> list[Signal]: + q = SIGNAL_SELECT + (" WHERE status = ?" if status else "") + " ORDER BY score_pp DESC LIMIT ?" + args = (status, limit) if status else (limit,) + return [Signal.from_row(r) for r in self.conn.execute(q, args).fetchall()] + + def locked_margin(self, exclude_sid: str | None = None) -> float: + cur = self.conn.execute( + "SELECT COALESCE(SUM(margin_locked),0) FROM signals WHERE status = 'approved' AND sid IS NOT ?", + (exclude_sid,)) + return float(cur.fetchone()[0]) + + def decide(self, sid: str, action: str, note: str) -> bool: + sig = self.get(sid) + if not sig: + return False + sig.status = action + if note: + sig.gate_note = note + self.upsert(sig, keep_status=False) # وضعیت تازه، عمداً بر وضعیت قبلی نوشته می‌شود + self.conn.execute("INSERT INTO decisions (ts, sid, action, note) VALUES (?,?,?,?)", + (now_iso(), sid, action, note)) + self.conn.commit() + return True + + def human_decided(self, sid: str) -> bool: + cur = self.conn.execute("SELECT 1 FROM decisions WHERE sid = ? LIMIT 1", (sid,)) + return cur.fetchone() is not None + + def decisions(self, limit: int = 50) -> list[tuple]: + return self.conn.execute( + "SELECT ts, sid, action, note FROM decisions ORDER BY id DESC LIMIT ?", (limit,)).fetchall() + + +# ---------------------------------------------------------------- خواندن هشدارهای کدال +def read_alerts(kodal_db: Path | str, min_score: int = 60, limit: int = 50) -> list[dict]: + """هشدارهای دیده‌بان را می‌خواند. اگر پایگاه‌داده نبود، فهرست خالی برمی‌گرداند.""" + p = Path(kodal_db) + if not p.exists(): + log(f"پایگاه‌داده دیده‌بان پیدا نشد: {p}") + return [] + try: + conn = sqlite3.connect(f"file:{p}?mode=ro", uri=True) + rows = conn.execute( + "SELECT title, symbol, category, direction, score, url FROM items " + "WHERE score >= ? ORDER BY score DESC LIMIT ?", (min_score, limit)).fetchall() + conn.close() + except sqlite3.Error as e: + log(f"خواندن هشدارها ممکن نشد: {e}") + return [] + return [{"title": t, "symbol": s, "category": c, "direction": d, "score": sc, "url": u} + for t, s, c, d, sc, u in rows] + + +def related_alerts(symbol: str, alerts: list[dict]) -> list[dict]: + out = [] + for a in alerts: + sym = (a.get("symbol") or "").strip() + if sym and (sym == symbol or sym in symbol or symbol in sym): + out.append(a) + elif not sym and symbol and symbol in (a.get("title") or ""): + out.append(a) + return out + + +# ---------------------------------------------------------------- موتور ریاضی +KIND_LABELS = { + "basis": "پایهٔ نقدی‌آتی", + "box": "باکس اسپرد", + "tabei": "اوراق تبعی", + "covered_call": "پوشش‌داده‌شده", + "parity": "تساوی پوت‌کال", +} + + +def math_for_row(row: dict, hurdle: float) -> dict: + """هر ردیف اسنپ‌شات را روی موتور ریاضی می‌گذارد و خروجی استاندارد برمی‌گرداند.""" + scout = load_scout() + sc = scout.Scenario(name=row.get("symbol", "?"), rows=[{k: v for k, v in row.items() if k != "margin_per_contract"}], + hurdle=hurdle) + result = scout.run_scenario(sc)[0] + if "error" in result: + raise ValueError(f"ردیف نامعتبر است: {result['error']}") + result["kind"] = row.get("kind", "نامشخص") # برچسب فارسی راهبرد در گزارش‌ها + result["margin_per_contract"] = float(row.get("margin_per_contract", 0) or 0) + return result + + +def signal_from_result(symbol: str, res: dict, cfg: dict) -> Signal: + kind = str(res.get("kind") or res.get("strategy") or "نامشخص") + name = f"{symbol} · {KIND_LABELS.get(kind, kind)}" + annual = res.get("annualized_pct") + sid = hashlib.sha1(f"{symbol}|{kind}|{json.dumps(res.get('detail', res), sort_keys=True, default=str)}" + .encode("utf-8")).hexdigest()[:12] + return Signal(sid=sid, symbol=symbol, kind=kind, name=name, + annualized_pct=annual if isinstance(annual, (int, float)) else None, + score_pp=float(res.get("score_pp", -999)), + go=bool(res.get("go")), detail=res, + margin_per_contract=float(res.get("margin_per_contract", 0) or 0)) + + +def gate_checks(sig: Signal, cfg: dict, desk: Desk) -> list[str]: + """دروازه‌های ریسک بدون اندازه‌گذاری: نقدشوندگی، اسپرد، تأیید موتور، سقف موقعیت.""" + d = sig.detail + reasons: list[str] = [] + if not sig.go: + reasons.append("موتور ریاضی این فرصت را تأیید نکرد.") + edge = sig.score_pp + threshold = (cfg["min_edge_arbitrage_pct"] if sig.kind in ("box", "parity", "tabei") + else cfg["min_edge_leveraged_pct"]) + if edge < threshold: + reasons.append(f"حاشیهٔ {edge:.2f} واحد درصد کمتر از کف {threshold:.2f} درصدی این راهبرد است.") + liq = d.get("liquidity_contracts_per_day", 999) + if isinstance(liq, (int, float)) and liq < cfg["min_liquidity_contracts_per_day"]: + reasons.append(f"حجم روزانهٔ {liq} کمتر از کف نقدشوندگی {cfg['min_liquidity_contracts_per_day']} است.") + # دروازهٔ باورپذیری: بازده غیرمنطقی یعنی داده اشتباه است، نه فرصت تاریخی + ceiling = (cfg.get("max_plausible_arb_pct", 250.0) if sig.kind in ("box", "parity", "tabei") + else cfg.get("max_plausible_lev_pct", 400.0)) + if isinstance(sig.annualized_pct, (int, float)) and abs(sig.annualized_pct) > ceiling: + reasons.append(f"بازده محاسبه‌شده {sig.annualized_pct:,.0f} درصد از سقف باورپذیری ({ceiling:,.0f} درصد) " + f"بیشتر است؛ یعنی یکی از اعداد ورودی غلط یا کهنه است. اول داده را بازبینی کنید.") + spread = d.get("spread_pct", 0) or 0 + if spread > cfg["max_spread_pct"]: + reasons.append(f"اسپرد {spread * 100:.2f} درصد از سقف مجاز بیشتر است.") + if not sig.alerts and edge < threshold * 2: + reasons.append("بدون پشتوانهٔ خبری و با حاشیهٔ کم؛ اولویت پایین است.") + return reasons + + +def size_position(sig: Signal, budget: float) -> str: + """اندازهٔ موقعیت را از بودجهٔ باقی‌مانده حساب می‌کند؛ در صورت نبود جا، پیام دلیل را می‌دهد.""" + unit = sig.unit + if (sig.margin_per_contract or 0) <= 0: + sig.contracts = 0 + return f"نرخ وجه تضمین هر {unit} در اسنپ‌شات مشخص نشده؛ از مشخصات قرارداد بخوانید." + n = int(budget // sig.margin_per_contract) + if n < 1: + sig.contracts = 0 + return f"بودجهٔ وجه تضمین (سقف {sig.margin_per_contract:,.0f} ریال برای هر {unit}) تمام شده است." + sig.contracts = n + sig.margin_locked = n * sig.margin_per_contract + return "" + + +def apply_risk_gates(sig: Signal, cfg: dict, desk: Desk) -> Signal: + """نسخهٔ تک‌سیگنالی (برای آزمون و بازبینی دستی).""" + reasons = gate_checks(sig, cfg, desk) + approved_so_far = len([s for s in desk.all("approved") if s.sid != sig.sid]) + if approved_so_far >= cfg["max_positions"]: + reasons.append(f"سقف {cfg['max_positions']} موقعیت تأییدشده پر است؛ اول یکی را ببندید.") + budget = cfg["capital"] * cfg["max_margin_pct"] - desk.locked_margin(exclude_sid=sig.sid) + budget = max(budget, 0.0) + note = size_position(sig, budget) + if reasons or note: + sig.status = "rejected" + sig.gate_note = " | ".join(reasons + ([note] if note else [])) + else: + sig.status = "pending" + sig.gate_note = (f"حاشیهٔ {sig.score_pp:.2f} واحد درصد · {sig.contracts:,} {sig.unit} · " + f"سرمایهٔ درگیر {sig.margin_locked:,.0f} ریال") + return sig + + +def scan_market(market_path: Path | str, cfg: dict, desk: Desk, + kodal_db: Path | str | None = None) -> list[Signal]: + """محاسبهٔ همهٔ ردیف‌ها، سپس تخصیص بودجهٔ وجه تضمین به‌ترتیب امتیاز.""" + data = json.loads(Path(market_path).read_text(encoding="utf-8")) + hurdle = float(data.get("hurdle", cfg["hurdle"])) + if data.get("capital"): + cfg["capital"] = float(data["capital"]) + alerts = read_alerts(kodal_db, cfg["alert_score_threshold"]) if kodal_db else [] + candidates: list[Signal] = [] + for row in data.get("rows", []): + symbol = str(row.get("symbol", "?")) + try: + res = math_for_row(row, hurdle) + except Exception as e: # ورودی ناقص یا فرمول نامعتبر + log(f"ردیف {symbol} محاسبه نشد: {type(e).__name__}: {e}") + continue + res.setdefault("unit", row.get("unit") or ("سهم" if row.get("kind") in + ("tabei", "covered_call", "parity") else "قرارداد")) + sig = signal_from_result(symbol, res, cfg) + sig.alerts = related_alerts(symbol, alerts) + sig.gate_note = " | ".join(gate_checks(sig, cfg, desk)) + candidates.append(sig) + + candidates.sort(key=lambda s: s.score_pp, reverse=True) + budget_total = max(cfg["capital"] * cfg["max_margin_pct"] - desk.locked_margin(), 0.0) + policy = {"capital": cfg["capital"], "max_margin_pct": cfg["max_margin_pct"], + "cap_total": cfg["capital"] * cfg["max_margin_pct"], + "max_positions": cfg["max_positions"], "hurdle": hurdle} + for sig in candidates: + sig.detail["_policy"] = policy + budget = budget_total + per_position = budget_total * float(cfg.get("max_position_pct", 1.0)) + for sig in candidates: + existing = desk.get(sig.sid) + if existing and desk.human_decided(sig.sid): + # تصمیم انسان بازنویسی نمی‌شود: اندازه و یادداشت همان می‌ماند + sig.status, sig.contracts = existing.status, existing.contracts + sig.margin_locked, sig.gate_note = existing.margin_locked, existing.gate_note + desk.upsert(sig) + continue + if sig.gate_note: + sig.status = "rejected" + else: + note = size_position(sig, max(min(budget, per_position), 0.0)) + if note: + sig.status = "rejected" + sig.gate_note = note + else: + budget -= sig.margin_locked + sig.status = "pending" + sig.gate_note = (f"حاشیهٔ {sig.score_pp:.2f} واحد درصد · {sig.contracts:,} {sig.unit} · " + f"سرمایهٔ درگیر {sig.margin_locked:,.0f} ریال") + desk.upsert(sig) + return candidates + + +def recheck_tasks(cfg: dict, desk: Desk, kodal_db: Path | str, market_path: Path | str) -> list[dict]: + """نمادهایی که خبر مهم داشته‌اند ولی در اسنپ‌شات بازار ردیفی ندارند.""" + data = json.loads(Path(market_path).read_text(encoding="utf-8")) + covered = {str(r.get("symbol", "")) for r in data.get("rows", [])} + out = [] + for a in read_alerts(kodal_db, cfg["alert_score_threshold"]): + sym = (a.get("symbol") or "").strip() + if sym and sym in covered: + continue + if sym: + out.append({"symbol": sym, "reason": "خبر مهم، ولی دادهٔ آپشن/آتی این نماد در اسنپ‌شات نیست", + "alert": a}) + return out + + +# ---------------------------------------------------------------- بستهٔ سفارش +def order_packet(sig: Signal) -> str: + d = sig.detail + lines = [ + "بستهٔ سفارش (اجرا فقط توسط انسان در سامانهٔ کارگزاری)", + "=" * 62, + f"نماد: {sig.symbol} راهبرد: {KIND_LABELS.get(sig.kind, sig.kind)}", + f"شمارهٔ سیگنال: {sig.sid}", + f"بازده سالانهٔ خالص برآوردی: {sig.annualized_pct if sig.annualized_pct is not None else '—'} درصد", + f"امتیاز نسبت به نرخ سد: {sig.score_pp} واحد درصد", + f"تعداد پیشنهادی: {sig.contracts:,} {sig.unit}", + f"سرمایهٔ درگیر (وجه تضمین یا بهای خرید): {sig.margin_locked:,.0f} ریال", + "", + "جزئیات ریاضی:", + ] + for k, v in d.items(): + if k in ("name", "strategy", "kind", "liquidity_contracts_per_day", "spread_pct", "leverage_used"): + continue + lines.append(f" · {k}: {v}") + if sig.alerts: + lines.append("") + lines.append("خبرهای مرتبط (فقط برای زمینه؛ خبر به‌تنهایی سیگنال نیست):") + for a in sig.alerts: + lines.append(f" · [{a.get('score')}] {a.get('title')}") + lines += [ + "", + "یادآوری‌های اجرایی:", + " ۱. پیش از ثبت، قیمت لحظه‌ای و عمق بازار را دوباره ببینید؛ اعداد اسنپ‌شات، تاریخی‌اند.", + " ۲. پاهای آربیتراژ را در یک پنجرهٔ زمانی کوتاه و هم‌زمان اجرا کنید، وگرنه ریسک اجرا می‌گیرید.", + " ۳. این بسته «پیشنهاد» است؛ تصمیم و مسئولیت با شماست. سود تضمینی وجود ندارد.", + ] + return "\n".join(lines) + + +# ---------------------------------------------------------------- داشبورد HTML +def build_dashboard(desk: Desk, cfg: dict, path: Path | str = DEFAULT_REPORT, + tasks: list[dict] | None = None) -> Path: + path = Path(path) + path.parent.mkdir(parents=True, exist_ok=True) + all_sigs = desk.all(limit=500) + pending = [s for s in all_sigs if s.status == "pending"] + approved = [s for s in all_sigs if s.status == "approved"] + rejected = [s for s in all_sigs if s.status == "rejected"] + + def rows(items: list[Signal], show_gate: bool = True) -> str: + out = [] + for s in items: + color = "#0a7d33" if s.score_pp > 10 else ("#8a6d00" if s.score_pp > 0 else "#b3261e") + news = "
".join(html.escape(a.get("title", "")[:110]) for a in s.alerts[:3]) or "—" + out.append(f""" + {html.escape(s.sid)} + {html.escape(s.symbol)} + {html.escape(KIND_LABELS.get(s.kind, s.kind))} + {'' if s.annualized_pct is None else f'{s.annualized_pct:.2f}'} + {s.score_pp:.2f} + {s.contracts:,} {html.escape(s.unit)} + {s.margin_locked:,.0f} + {html.escape(s.status)} + {html.escape(s.gate_note)}{f'
{news}
' if news != '—' else ''} + """) + return "".join(out) or 'موردی نیست.' + + tasks_html = "".join( + f"
  • {html.escape(t['symbol'])} — {html.escape(t['reason'])} " + f"{html.escape(str(t['alert'].get('title', ''))[:120])}
  • " + for t in (tasks or [])) or "
  • موردی نیست.
  • " + + doc = f""" + +{html.escape(cfg['report_title'])} — {fa_time()} + + +
    +

    {html.escape(cfg['report_title'])}

    +
    زمان: {fa_time()} · نسخهٔ {VERSION} · نرخ سد: {cfg['hurdle'] * 100:.1f} درصد
    +
    +
    +
    سرمایه
    {cfg['capital']:,.0f}
    +
    سیگنال منتظر تأیید
    {len(pending)}
    +
    تأییدشده
    {len(approved)}
    +
    وجه تضمین قفل‌شده
    {desk.locked_margin():,.0f}
    +
    رد شده
    {len(rejected)}
    +
    +
    +
    این داشبورد «دستیار تصمیم» است. هیچ سفارشی خودکار ارسال نمی‌شود؛ + معاملات الگوریتمی خودکار در بورس و فرابورس ایران مجاز نیست. تصمیم نهایی و مسئولیت آن با انسان است و هیچ سود تضمینی وجود ندارد.
    + +

    سیگنال‌های منتظر تأیید

    + + + {rows(pending)}
    شناسهنمادراهبردبازده سالانهٔ خالص (٪)حاشیه (واحد ٪)تعدادوجه تضمینوضعیتیادداشت دروازه / خبر مرتبط
    + +

    تأییدشده (آمادهٔ اجرای انسانی)

    + + + {rows(approved)}
    شناسهنمادراهبردبازده سالانهٔ خالص (٪)حاشیه (واحد ٪)تعدادوجه تضمینوضعیتیادداشت دروازه / خبر مرتبط
    + +

    رد‌شده‌ها و دلیل

    + + + {rows(rejected)}
    شناسهنمادراهبردبازده سالانهٔ خالص (٪)حاشیه (واحد ٪)تعدادوجه تضمینوضعیتیادداشت دروازه / خبر مرتبط
    + +

    کارهای بازبینی (خبر مهم بدون دادهٔ بازار)

    + + +

    دستورهای تأیید و اجرا

    + + + +
    """ + path.write_text(doc, encoding="utf-8") + return path + + +# ---------------------------------------------------------------- دستورها +def cmd_scan(args) -> int: + cfg = load_config(args.config) + desk = Desk(cfg.get("desk_db") or DEFAULT_DB) + sigs = scan_market(args.market, cfg, desk, args.kodal_db) + for s in sigs[:20]: + mark = "✅" if s.status == "pending" else ("🟢" if s.status == "approved" else "✖") + ann = f"{s.annualized_pct:.2f}٪" if isinstance(s.annualized_pct, (int, float)) else "—" + print(f"{mark} [{s.sid}] {s.symbol:<8} {KIND_LABELS.get(s.kind, s.kind):<16} بازده {ann:<9} حاشیه {s.score_pp:>7.2f} قرارداد {s.contracts}") + if s.status == "rejected": + print(f" دلیل: {s.gate_note}") + log(f"{len(sigs)} سیگنال محاسبه شد؛ {len([s for s in sigs if s.status == 'pending'])} منتظر تأیید.") + return 0 + + +def cmd_run(args) -> int: + cfg = load_config(args.config) + desk = Desk(cfg.get("desk_db") or DEFAULT_DB) + sigs = scan_market(args.market, cfg, desk, args.kodal_db) + tasks = recheck_tasks(cfg, desk, args.kodal_db, args.market) if args.kodal_db else [] + path = build_dashboard(desk, cfg, cfg.get("report_path") or DEFAULT_REPORT, tasks) + log(f"{len(sigs)} سیگنال · {len(tasks)} کار بازبینی · داشبورد: {path}") + for s in sigs: + if s.status == "pending": + print(f" → منتظر تأیید: [{s.sid}] {s.name} با حاشیهٔ {s.score_pp:.2f} واحد درصد") + return 0 + + +def cmd_list(args) -> int: + cfg = load_config(args.config) + desk = Desk(cfg.get("desk_db") or DEFAULT_DB) + items = desk.all(args.status, args.limit) + if not items: + print("موردی نیست.") + return 0 + for s in items: + ann = f"{s.annualized_pct:.2f}٪" if isinstance(s.annualized_pct, (int, float)) else "—" + print(f"[{s.sid}] {s.status:<9} {s.symbol:<8} {KIND_LABELS.get(s.kind, s.kind):<16} " + f"بازده {ann:<9} حاشیه {s.score_pp:>7.2f} {s.contracts:,} {s.unit}") + if s.gate_note: + print(f" {s.gate_note}") + return 0 + + +def cmd_decide(args, action: str) -> int: + cfg = load_config(args.config) + desk = Desk(cfg.get("desk_db") or DEFAULT_DB) + sig = desk.get(args.sid) + if not sig: + print("شناسه پیدا نشد.") + return 2 + if action == "approved": + policy = sig.detail.get("_policy") or {} + cap = float(policy.get("cap_total") or cfg["capital"] * cfg["max_margin_pct"]) + max_positions = int(policy.get("max_positions") or cfg["max_positions"]) + used = desk.locked_margin(exclude_sid=sig.sid) + sig.margin_locked + count = len([s for s in desk.all("approved") if s.sid != sig.sid]) + if used > cap or count >= max_positions: + print(f"توقف: تأیید این سیگنال سقف ریسک را رد می‌کند " + f"(سرمایهٔ درگیر {used:,.0f} از سقف {cap:,.0f} ریال · موقعیت‌های تأییدشده {count} از {max_positions}).") + if not getattr(args, "force", False): + print("اگر آگاهانه می‌خواهید رد کنید، دستور را با --force تکرار کنید.") + return 3 + print("با --force رد شد؛ این تصمیم در دفتر ثبت می‌شود.") + desk.decide(args.sid, action, args.note or "") + print(f"{'تأیید' if action == 'approved' else 'رد'} شد: {args.sid}") + if action == "approved": + sig = desk.get(args.sid) + assert sig is not None + print() + print(order_packet(sig)) + return 0 + + +def cmd_packet(args) -> int: + cfg = load_config(args.config) + desk = Desk(cfg.get("desk_db") or DEFAULT_DB) + sig = desk.get(args.sid) + if not sig: + print("شناسه پیدا نشد.") + return 2 + if sig.status != "approved": + print(f"هشدار: وضعیت این سیگنال «{sig.status}» است، نه تأییدشده. " + f"برای اجرا اول با دستور approve تأیید کنید.") + print(order_packet(sig)) + return 0 + + +def cmd_stats(args) -> int: + cfg = load_config(args.config) + desk = Desk(cfg.get("desk_db") or DEFAULT_DB) + rows = desk.conn.execute( + "SELECT status, COUNT(*), COALESCE(SUM(margin_locked),0) FROM signals GROUP BY status").fetchall() + print(f"{'وضعیت':<12}{'تعداد':>8}{'وجه تضمین قفل‌شده':>22}") + for st, n, locked in rows: + print(f"{st:<12}{n:>8}{locked:>22,.0f}") + print(f"\nتصمیم‌های ثبت‌شده: {len(desk.decisions(1000))}") + return 0 + + +def cmd_selftest(args) -> int: + checks = 0 + scout = load_scout() + assert hasattr(scout, "box_spread") and hasattr(scout, "tabei_min_yield") + checks += 1 + cfg = json.loads(json.dumps(DEFAULT_CONFIG)) + desk = Desk(BASE / "data" / "_selftest.sqlite3") + desk.conn.execute("DELETE FROM signals") + desk.conn.commit() + market = BASE / "market-demo.json" + if market.exists(): + sigs = scan_market(market, cfg, desk) + assert sigs, "اسنپ‌شات نمونه سیگنالی تولید نکرد" + checks += 1 + assert any(s.status == "pending" for s in sigs) or all(s.gate_note for s in sigs) + checks += 1 + assert g2j(2026, 9, 22) == (1405, 6, 31) + checks += 1 + print(f"خودآزمون: {checks} بررسی موفق") + return 0 + + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description="میز معاملات — دستیار تصمیم با تأیید انسان (بدون ارسال سفارش)") + ap.add_argument("--config", help="مسیر config.json") + sub = ap.add_subparsers(dest="cmd") + + p_scan = sub.add_parser("scan", help="محاسبهٔ ریاضی روی اسنپ‌شات بازار") + p_scan.add_argument("--market", required=True) + p_scan.add_argument("--kodal-db", help="پایگاه‌دادهٔ دیده‌بان کدال") + p_scan.set_defaults(func=cmd_scan) + + p_run = sub.add_parser("run", help="محاسبه + چسباندن خبرها + داشبورد") + p_run.add_argument("--market", required=True) + p_run.add_argument("--kodal-db") + p_run.set_defaults(func=cmd_run) + + p_list = sub.add_parser("list", help="فهرست سیگنال‌ها") + p_list.add_argument("--status", choices=["pending", "approved", "rejected"]) + p_list.add_argument("--limit", type=int, default=50) + p_list.set_defaults(func=cmd_list) + + p_app = sub.add_parser("approve", help="تأیید انسانی سیگنال") + p_app.add_argument("sid") + p_app.add_argument("--note", default="") + p_app.add_argument("--force", action="store_true", help="رد کردن آگاهانهٔ سقف ریسک") + p_app.set_defaults(func=lambda a: cmd_decide(a, "approved")) + + p_rej = sub.add_parser("reject", help="رد سیگنال با دلیل") + p_rej.add_argument("sid") + p_rej.add_argument("--note", default="") + p_rej.set_defaults(func=lambda a: cmd_decide(a, "rejected")) + + p_list.set_defaults(func=cmd_list) # نگهبان + + p_pack = sub.add_parser("packet", help="چاپ بستهٔ سفارش") + p_pack.add_argument("sid") + p_pack.set_defaults(func=cmd_packet) + + sub.add_parser("stats", help="آمار وضعیت‌ها").set_defaults(func=cmd_stats) + sub.add_parser("selftest", help="آزمون سریع").set_defaults(func=cmd_selftest) + sub.add_parser("version", help="نسخه").set_defaults(func=lambda a: (print(f"desk {VERSION}"), 0)[1]) + + args = ap.parse_args(argv) + if not getattr(args, "cmd", None): + ap.print_help() + return 0 + return int(args.func(args) or 0) + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/desk/market-demo.json b/desk/market-demo.json new file mode 100644 index 0000000000000000000000000000000000000000..81675c88b2f5d2b43801766cb9a344c888948989 --- /dev/null +++ b/desk/market-demo.json @@ -0,0 +1,36 @@ +{ + "as_of": "2026-09-22", + "hurdle": 0.39, + "capital": 20000000000, + "note": "اعداد این اسنپ‌شات نمونه و ساختگی‌اند و قیمت واقعی بازار نیستند؛ فقط برای نمایش کارکرد میز معاملات ساخته شده‌اند. وجه تضمین‌ها به ریال است.", + "rows": [ + {"symbol": "اهرم", "kind": "basis", "spot": 20000, "future": 22800, "days": 90, "storage_annual": 0.0, + "margin_per_contract": 20000000, "unit": "قرارداد", + "liquidity_contracts_per_day": 900, "spread_pct": 0.005, "leverage_used": 1}, + + {"symbol": "فولاد", "kind": "covered_call", "spot": 7000, "strike": 7600, "premium": 400, "days": 45, + "margin_per_contract": 7000, "unit": "سهم", + "liquidity_contracts_per_day": 160, "spread_pct": 0.018}, + + {"symbol": "کگل", "kind": "tabei", "stock_price": 9800, "put_price": 40, "strike": 14210, "days": 365, + "margin_per_contract": 9840, "unit": "سهم", + "liquidity_contracts_per_day": 240, "spread_pct": 0.02}, + + {"symbol": "خساپا", "kind": "tabei", "stock_price": 2500, "put_price": 12, "strike": 3000, "days": 270, + "margin_per_contract": 2512, "unit": "سهم", + "liquidity_contracts_per_day": 320, "spread_pct": 0.012}, + + {"symbol": "طلا", "kind": "basis", "spot": 20000, "future": 20600, "days": 60, "storage_annual": 0.01, + "margin_per_contract": 20000000, "unit": "قرارداد", + "liquidity_contracts_per_day": 700, "spread_pct": 0.006}, + + {"symbol": "شپنا", "kind": "box", "call_low": 300, "put_low": 430, "call_high": 175, "put_high": 585, + "strike_low": 1200, "strike_high": 1500, "days": 45, + "margin_per_contract": 250000, "unit": "قرارداد", + "liquidity_contracts_per_day": 12, "spread_pct": 0.045}, + + {"symbol": "وبملت", "kind": "parity", "call": 420, "put": 380, "spot": 9000, "strike": 9000, "days": 30, "rate": 0.39, + "margin_per_contract": 9000, "unit": "سهم", + "liquidity_contracts_per_day": 80, "spread_pct": 0.02} + ] +} diff --git a/desk/run-demo.bat b/desk/run-demo.bat new file mode 100644 index 0000000000000000000000000000000000000000..57d9d7ddb2a32b561f7612531b9c53df763dc873 --- /dev/null +++ b/desk/run-demo.bat @@ -0,0 +1,5 @@ +@echo off +chcp 65001 >nul +cd /d "%~dp0" +python desk.py run --market market-demo.json --kodal-db ..\kodal-alert\data\demo.sqlite3 +start "" "data\dashboard.html" diff --git a/desk/tests/test_desk.py b/desk/tests/test_desk.py new file mode 100644 index 0000000000000000000000000000000000000000..6dab8f56dd4a5f399cfc2d8083086f7841ca0e67 --- /dev/null +++ b/desk/tests/test_desk.py @@ -0,0 +1,304 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""آزمون‌های واحد میز معاملات — فقط کتابخانهٔ استاندارد.""" +from __future__ import annotations + +import json +import sqlite3 +import sys +import tempfile +import unittest +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) + +BASE_MARKET = Path(__file__).resolve().parents[1] / "market-demo.json" + +import desk as dk # noqa: E402 + + +def temp_cfg(tmp: str, **over) -> dict: + cfg = json.loads(json.dumps(dk.DEFAULT_CONFIG, ensure_ascii=False)) + cfg["desk_db"] = str(Path(tmp) / "desk.sqlite3") + cfg["report_path"] = str(Path(tmp) / "dash.html") + cfg.update(over) + return cfg + + +def make_kodal_db(tmp: str, rows: list[tuple]) -> Path: + p = Path(tmp) / "kodal.sqlite3" + conn = sqlite3.connect(str(p)) + conn.execute("CREATE TABLE items (id TEXT PRIMARY KEY, title TEXT, source TEXT, symbol TEXT, company TEXT," + " body TEXT, url TEXT, published_at TEXT, category TEXT, direction TEXT, score INTEGER," + " reason TEXT, ai_note TEXT, provider TEXT, created_at TEXT)") + for i, (title, symbol, score) in enumerate(rows): + conn.execute("INSERT INTO items VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)", + (f"k{i}", title, "کدال", symbol, "", "", "https://codal.ir/x", "", "افزایش سرمایه", + "مثبت", score, "", "", "شاهد محلی", "")) + conn.commit() + conn.close() + return p + + +class TestScoutBridge(unittest.TestCase): + def test_scout_loads(self): + scout = dk.load_scout() + self.assertTrue(hasattr(scout, "box_spread")) + + def test_math_for_tabei_row(self): + res = dk.math_for_row({"symbol": "خ", "kind": "tabei", "stock_price": 2500, "put_price": 12, + "strike": 3125, "days": 90}, 0.39) + self.assertTrue(res["go"]) + self.assertGreater(res["annualized_pct"], 39.0) + + def test_math_for_bad_row_reports(self): + with self.assertRaises(ValueError): + dk.math_for_row({"symbol": "خ", "kind": "box", "call_low": 1}, 0.39) + + def test_math_unknown_kind_reports(self): + with self.assertRaises(ValueError): + dk.math_for_row({"symbol": "خ", "kind": "nope"}, 0.39) + + +class TestScan(unittest.TestCase): + def test_scan_demo_market(self): + with tempfile.TemporaryDirectory() as tmp: + cfg = temp_cfg(tmp) + desk = dk.Desk(cfg["desk_db"]) + sigs = dk.scan_market(Path(dk.BASE) / "market-demo.json", cfg, desk) + self.assertGreaterEqual(len(sigs), 6) + scores = [s.score_pp for s in sigs] + self.assertEqual(scores, sorted(scores, reverse=True)) + self.assertTrue(any(s.status == "pending" for s in sigs)) + self.assertTrue(any(s.status == "rejected" for s in sigs)) + + def test_illiquid_row_is_rejected(self): + with tempfile.TemporaryDirectory() as tmp: + cfg = temp_cfg(tmp) + desk = dk.Desk(cfg["desk_db"]) + sig = dk.Signal(sid="x1", symbol="شپنا", kind="box", name="n", annualized_pct=200.0, + score_pp=100.0, go=True, + detail={"liquidity_contracts_per_day": 3, "spread_pct": 0.01}, + margin_per_contract=1000) + sig = dk.apply_risk_gates(sig, cfg, desk) + self.assertEqual(sig.status, "rejected") + self.assertIn("نقدشوندگی", sig.gate_note) + + def test_wide_spread_is_rejected(self): + with tempfile.TemporaryDirectory() as tmp: + cfg = temp_cfg(tmp) + desk = dk.Desk(cfg["desk_db"]) + sig = dk.Signal(sid="x2", symbol="الف", kind="box", name="n", annualized_pct=200.0, + score_pp=100.0, go=True, + detail={"liquidity_contracts_per_day": 200, "spread_pct": 0.09}, + margin_per_contract=1000) + sig = dk.apply_risk_gates(sig, cfg, desk) + self.assertEqual(sig.status, "rejected") + self.assertIn("اسپرد", sig.gate_note) + + def test_big_margin_blocks_position(self): + with tempfile.TemporaryDirectory() as tmp: + cfg = temp_cfg(tmp) + desk = dk.Desk(cfg["desk_db"]) + sig = dk.Signal(sid="x3", symbol="ب", kind="basis", name="n", annualized_pct=120.0, + score_pp=60.0, go=True, + detail={"liquidity_contracts_per_day": 200, "spread_pct": 0.01}, + margin_per_contract=cfg["capital"]) # بیشتر از سقف ۲۰ درصد + sig = dk.apply_risk_gates(sig, cfg, desk) + self.assertEqual(sig.contracts, 0) + self.assertEqual(sig.status, "rejected") + + def test_margin_math_respects_cap(self): + with tempfile.TemporaryDirectory() as tmp: + cfg = temp_cfg(tmp) + desk = dk.Desk(cfg["desk_db"]) + sig = dk.Signal(sid="x4", symbol="ج", kind="basis", name="n", annualized_pct=120.0, + score_pp=60.0, go=True, + detail={"liquidity_contracts_per_day": 200, "spread_pct": 0.01}, + margin_per_contract=100_000_000) + sig = dk.apply_risk_gates(sig, cfg, desk) + self.assertEqual(sig.contracts, 10) # ۵ میلیارد × ۲۰٪ ÷ ۱۰۰ میلیون + self.assertLessEqual(sig.margin_locked, cfg["capital"] * cfg["max_margin_pct"]) + + def test_status_preserved_on_rescan(self): + with tempfile.TemporaryDirectory() as tmp: + cfg = temp_cfg(tmp) + desk = dk.Desk(cfg["desk_db"]) + market = Path(dk.BASE) / "market-demo.json" + sigs = dk.scan_market(market, cfg, desk) + target = next(s for s in sigs if s.status == "pending") + desk.decide(target.sid, "approved", "تست") + dk.scan_market(market, cfg, desk) + self.assertEqual(desk.get(target.sid).status, "approved") + + +class TestAlertsBridge(unittest.TestCase): + def test_read_and_match_alerts(self): + with tempfile.TemporaryDirectory() as tmp: + p = make_kodal_db(tmp, [("افزایش سرمایه ۴۵۰ درصدی", "خساپا", 96), + ("توقف نماد", "وبملت", 86)]) + alerts = dk.read_alerts(p, 60) + self.assertEqual(len(alerts), 2) + matched = dk.related_alerts("خساپا", alerts) + self.assertEqual(len(matched), 1) + self.assertIn("افزایش سرمایه", matched[0]["title"]) + + def test_missing_db_is_safe(self): + self.assertEqual(dk.read_alerts("/no/such.sqlite3", 60), []) + + def test_recheck_tasks_for_uncovered_symbol(self): + with tempfile.TemporaryDirectory() as tmp: + cfg = temp_cfg(tmp) + desk = dk.Desk(cfg["desk_db"]) + p = make_kodal_db(tmp, [("افزایش سرمایه", "شپدیس", 92)]) + tasks = dk.recheck_tasks(cfg, desk, p, Path(dk.BASE) / "market-demo.json") + self.assertEqual(len(tasks), 1) + self.assertEqual(tasks[0]["symbol"], "شپدیس") + + def test_covered_symbol_not_in_tasks(self): + with tempfile.TemporaryDirectory() as tmp: + cfg = temp_cfg(tmp) + desk = dk.Desk(cfg["desk_db"]) + p = make_kodal_db(tmp, [("خبر مهم", "خساپا", 92)]) + self.assertEqual(dk.recheck_tasks(cfg, desk, p, Path(dk.BASE) / "market-demo.json"), []) + + +class TestWorkflow(unittest.TestCase): + def test_approve_records_decision_and_packet(self): + with tempfile.TemporaryDirectory() as tmp: + cfg = temp_cfg(tmp) + desk = dk.Desk(cfg["desk_db"]) + sigs = dk.scan_market(Path(dk.BASE) / "market-demo.json", cfg, desk) + target = next(s for s in sigs if s.status == "pending") + self.assertTrue(desk.decide(target.sid, "approved", "ریسک پذیرفته شد")) + self.assertEqual(desk.get(target.sid).status, "approved") + self.assertEqual(len(desk.decisions(10)), 1) + packet = dk.order_packet(desk.get(target.sid)) + self.assertIn(target.symbol, packet) + self.assertIn("انسان", packet) + self.assertIn("سود تضمینی وجود ندارد", packet) + + def test_reject_unknown_id_returns_false(self): + with tempfile.TemporaryDirectory() as tmp: + cfg = temp_cfg(tmp) + desk = dk.Desk(cfg["desk_db"]) + self.assertFalse(desk.decide("nope", "approved", "")) + + def test_locked_margin_tracks_approvals(self): + with tempfile.TemporaryDirectory() as tmp: + cfg = temp_cfg(tmp) + desk = dk.Desk(cfg["desk_db"]) + sigs = dk.scan_market(Path(dk.BASE) / "market-demo.json", cfg, desk) + target = next(s for s in sigs if s.status == "pending") + before = desk.locked_margin() + desk.decide(target.sid, "approved", "") + self.assertGreater(desk.locked_margin(), before) + + +class TestDashboard(unittest.TestCase): + def test_dashboard_is_self_contained_and_rtl(self): + with tempfile.TemporaryDirectory() as tmp: + cfg = temp_cfg(tmp) + desk = dk.Desk(cfg["desk_db"]) + sigs = dk.scan_market(Path(dk.BASE) / "market-demo.json", cfg, desk) + path = dk.build_dashboard(desk, cfg, cfg["report_path"], [{"symbol": "شپدیس", "reason": "بدون داده", + "alert": {"title": "خبر"}}]) + body = path.read_text(encoding="utf-8") + self.assertIn('dir="rtl"', body) + self.assertIn(sigs[0].sid, body) + self.assertNotIn(" datetime: + return datetime.now(timezone.utc) + + +def g2j(gy: int, gm: int, gd: int) -> tuple[int, int, int]: + """تبدیل تاریخ میلادی به شمسی (الگوریتم استاندارد).""" + g_d_m = [0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334] + gy2 = gy + 1 if gm > 2 else gy + days = 355666 + (365 * gy) + ((gy2 + 3) // 4) - ((gy2 + 99) // 100) + ((gy2 + 399) // 400) + gd + g_d_m[gm - 1] + jy = -1595 + 33 * (days // 12053) + days %= 12053 + jy += 4 * (days // 1461) + days %= 1461 + if days > 365: + jy += (days - 1) // 365 + days = (days - 1) % 365 + if days < 186: + jm = 1 + days // 31 + jd = 1 + days % 31 + else: + jm = 7 + (days - 186) // 30 + jd = 1 + (days - 186) % 30 + return jy, jm, jd + + +def jalali_str(dt: datetime | None = None) -> str: + dt = dt or now_utc() + jy, jm, jd = g2j(dt.year, dt.month, dt.day) + return f"{jy:04d}/{jm:02d}/{jd:02d} {dt.hour:02d}:{dt.minute:02d}" + + +def log(msg: str) -> None: + print(f"[{jalali_str()}] {msg}") + + +def load_config(path: str | None) -> dict: + cfg = json.loads(json.dumps(DEFAULT_CONFIG, ensure_ascii=False)) # کپی عمیق + p = Path(path) if path else BASE / "config.json" + if p.exists(): + try: + user = json.loads(p.read_text(encoding="utf-8")) + for k, v in user.items(): + if isinstance(v, dict) and isinstance(cfg.get(k), dict): + cfg[k].update(v) + else: + cfg[k] = v + except json.JSONDecodeError as e: + log(f"پروندهٔ تنظیمات خوانده نشد ({e})؛ تنظیمات پیش‌فرض استفاده می‌شود.") + return cfg + + +# ---------------------------------------------------------------- لایهٔ شبکه +def http_get(url: str, cfg: dict, cache_name: str | None = None) -> str | None: + """دریافت متن با retry، timeout، پروکسی و حافظهٔ نهان روی دیسک.""" + if url.startswith("file:"): + try: + return Path(url[5:]).read_text(encoding="utf-8") + except OSError as e: + log(f"خواندن فایل ممکن نشد: {e}") + return None + CACHE_DIR.mkdir(parents=True, exist_ok=True) + cache_file = CACHE_DIR / (cache_name or hashlib.sha1(url.encode()).hexdigest()) + handlers = [] + proxies = {k: v for k, v in (cfg.get("proxies") or {}).items() if v} + if proxies: + handlers.append(urllib.request.ProxyHandler(proxies)) + opener = urllib.request.build_opener(*handlers) + req = urllib.request.Request(url, headers={ + "User-Agent": "Mozilla/5.0 (KodalAlert/0.1; +local)", + "Accept": "application/json, text/xml, application/xml, text/html;q=0.9, */*;q=0.5", + }) + for attempt in range(1, int(cfg.get("retries", 2)) + 2): + try: + with opener.open(req, timeout=float(cfg.get("timeout_seconds", 15))) as resp: + body = resp.read().decode("utf-8", errors="replace") + cache_file.write_text(body, encoding="utf-8") + return body + except (urllib.error.URLError, urllib.error.HTTPError, TimeoutError, OSError) as e: + log(f"تلاش {attempt} برای {url} ناموفق: {e}") + time.sleep(min(2.0 * attempt, 6.0)) + if cache_file.exists(): + log(f"از حافظهٔ نهان استفاده شد: {cache_file.name}") + return cache_file.read_text(encoding="utf-8") + return None + + +# ---------------------------------------------------------------- مدل داده +@dataclass +class Item: + title: str + source: str = "نامشخص" + symbol: str = "" + company: str = "" + body: str = "" + url: str = "" + published_at: str = "" + category: str = "" + direction: str = "نامعلوم" + score: int = 0 + reason: str = "" + ai_note: str = "" + provider: str = "شاهد محلی (قاعده‌محور)" + + def key(self) -> str: + raw = f"{self.source}|{self.title}|{self.symbol}|{self.published_at}".encode("utf-8") + return hashlib.sha1(raw).hexdigest()[:16] + + def to_row(self) -> tuple: + d = asdict(self) + return (self.key(), d["title"], d["source"], d["symbol"], d["company"], d["body"], d["url"], + d["published_at"], d["category"], d["direction"], d["score"], d["reason"], d["ai_note"], d["provider"]) + + +# ---------------------------------------------------------------- دسته‌بندی و امتیازدهی +def classify(title: str, body: str, source_weight: float = 1.0, + published_at: datetime | None = None) -> tuple[str, str, int, str]: + """عنوان بر متن مقدم است تا متن‌های حاشیه‌ای، دسته را از مسیر خارج نکنند.""" + title_l, body_l = title.lower(), body.lower() + best: tuple[str, int, str, str] | None = None + for cat, kws, base, direction, why in CATEGORY_RULES: + t_hits = sum(1 for kw in kws if kw.lower() in title_l) + b_hits = sum(1 for kw in kws if kw.lower() in body_l) + if t_hits == 0 and b_hits < 2: + continue + effective = t_hits * 3 + b_hits + score = base + min(max(effective - 1, 0), 3) * 4 + if t_hits == 0: + score -= 12 # فقط از متن آمده: کمی محافظه‌کارتر + if best is None or score > best[1]: + best = (cat, score, direction, why) + if best is None: + best = ("سایر", 30, "نامعلوم", "دستهٔ مشخصی تشخیص داده نشد؛ عنوان را خودتان بخوانید.") + + cat, score, direction, why = best + if cat == "توقف و بازگشایی نماد": + direction = "مثبت" if ("بازگشایی" in title_l and "توقف نماد" not in title_l) else "منفی" + text = f"{title_l} {body_l}" + pos = sum(1 for w in POSITIVE_WORDS if w in text) + neg = sum(1 for w in NEGATIVE_WORDS if w in text) + if direction == "نامعلوم": + direction = "مثبت" if pos > neg else ("منفی" if neg > pos else "خنثی") + if any(re.search(p, text) for p in NUMERIC_BONUS_PATTERNS): + score += 6 + why += " متن عدد کمّی دارد؛ نسبت آن عدد به اندازهٔ شرکت را حساب کنید." + if published_at is not None: + pa = published_at if published_at.tzinfo else published_at.replace(tzinfo=timezone.utc) + age_h = (now_utc() - pa).total_seconds() / 3600.0 + if age_h <= 6: + score += 8 + elif age_h > 72: + score -= 10 + score = int(max(0, min(100, round(score * source_weight)))) + return cat, direction, score, why + + +def symbol_in_watchlist(item: Item, watchlist: list[str]) -> bool: + blob = f"{item.symbol} {item.title} {item.company}" + return any(w and w in blob for w in watchlist) + + +# ---------------------------------------------------------------- انبار داده +SCHEMA = """ +CREATE TABLE IF NOT EXISTS items ( + id TEXT PRIMARY KEY, title TEXT, source TEXT, symbol TEXT, company TEXT, + body TEXT, url TEXT, published_at TEXT, category TEXT, direction TEXT, + score INTEGER, reason TEXT, ai_note TEXT, provider TEXT, created_at TEXT +); +CREATE TABLE IF NOT EXISTS runs (id INTEGER PRIMARY KEY AUTOINCREMENT, started_at TEXT, items INTEGER, source TEXT); +""" + + +class Store: + def __init__(self, path: Path | str = DEFAULT_DB): + self.path = Path(path) + self.path.parent.mkdir(parents=True, exist_ok=True) + self.conn = sqlite3.connect(str(self.path)) + self.conn.executescript(SCHEMA) + self.conn.commit() + + # ── بستن تمیز (پایان کار / پرونده‌های موقت) + def close(self) -> None: + """پیوند پایگاه‌داده را می‌بندد. چند بار صدا زدنش بی‌خطر است.""" + try: + self.conn.close() + except Exception: # noqa: BLE001 — بستن نباید برنامه را بیندازد + pass + + def __enter__(self) -> "Store": + return self + + def __exit__(self, *exc) -> None: + self.close() + + def __del__(self) -> None: + self.close() + + + def add(self, item: Item) -> bool: + try: + self.conn.execute( + "INSERT INTO items VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)", + item.to_row() + (now_utc().isoformat(timespec="seconds"),)) + return True + except sqlite3.IntegrityError: + return False + + def commit(self) -> None: + self.conn.commit() + + def recent(self, limit: int = 100, min_score: int = 0) -> list[Item]: + cur = self.conn.execute( + "SELECT title,source,symbol,company,body,url,published_at,category,direction,score,reason,ai_note,provider " + "FROM items WHERE score >= ? ORDER BY score DESC, published_at DESC LIMIT ?", (min_score, limit)) + return [Item(*row) for row in cur.fetchall()] + + def count(self) -> int: + return int(self.conn.execute("SELECT COUNT(*) FROM items").fetchone()[0]) + + def log_run(self, source: str, n: int) -> None: + self.conn.execute("INSERT INTO runs (started_at, items, source) VALUES (?,?,?)", + (now_utc().isoformat(timespec="seconds"), n, source)) + self.conn.commit() + + +# ---------------------------------------------------------------- منابع داده +def item_from_dict(d: dict, source_name: str = "", cfg: dict | None = None) -> Item: + cfg = cfg or {} + published = None + raw_date = str(d.get("published_at") or d.get("date") or "").strip() + for fmt in ("%Y-%m-%dT%H:%M:%S", "%Y-%m-%d %H:%M:%S", "%Y-%m-%d", "%Y/%m/%d"): + try: + published = datetime.strptime(raw_date[:19], fmt).replace(tzinfo=timezone.utc) + break + except ValueError: + continue + sw = 1.15 if source_name in ("کدال", "codal") else 1.0 + cat, direction, score, why = classify(str(d.get("title", "")), str(d.get("body", "")), sw, published) + return Item(title=str(d.get("title", "")).strip(), source=source_name or str(d.get("source", "نامشخص")), + symbol=str(d.get("symbol", "")).strip(), company=str(d.get("company", "")).strip(), + body=str(d.get("body", ""))[:2000], url=str(d.get("url", "")), published_at=raw_date, + category=cat, direction=direction, score=score, reason=why) + + +def load_file_source(path: str, cfg: dict) -> list[Item]: + p = Path(path) + if not p.exists(): + log(f"پروندهٔ منبع پیدا نشد: {path}") + return [] + text = p.read_text(encoding="utf-8") + items: list[Item] = [] + if p.suffix.lower() == ".csv": + for row in csv.DictReader(text.splitlines()): + items.append(item_from_dict(row, cfg=cfg)) + else: + data = json.loads(text) + rows = data if isinstance(data, list) else data.get("items", []) + for row in rows: + items.append(item_from_dict(row, cfg=cfg)) + return items + + +def parse_feed(xml_text: str, source_name: str, cfg: dict) -> list[Item]: + items: list[Item] = [] + try: + root = ET.fromstring(xml_text) + except ET.ParseError as e: + log(f"فید خوانده نشد: {e}") + return items + nodes = root.iter("item") if root.findall(".//item") else root.iter("{http://www.w3.org/2005/Atom}entry") + for node in nodes: + def txt(tag: str) -> str: + el = node.find(tag) if node.find(tag) is not None else node.find("{http://www.w3.org/2005/Atom}" + tag) + return (el.text or "").strip() if el is not None and el.text else "" + link = txt("link") or "" + if not link: + el = node.find("{http://www.w3.org/2005/Atom}link") + link = el.get("href", "") if el is not None else "" + title, desc = txt("title"), (txt("description") or txt("summary")) + desc = re.sub(r"<[^>]+>", " ", desc)[:1500] + if title: + items.append(item_from_dict({"title": title, "body": desc, "url": link, + "published_at": txt("pubDate") or txt("updated")}, + source_name=source_name, cfg=cfg)) + return items + + +def fetch_codal(cfg: dict) -> list[Item]: + """تلاش برای خواندن اطلاعیه‌های کدال. اگر سامانه پاسخ ندهد، رشتهٔ خالی برمی‌گردد.""" + src = next((s for s in cfg.get("sources", []) if s.get("type") == "codal"), None) + if not src: + return [] + params = {"PageNumber": "1", "Length": "-1", "Audited": "true", "NotAudited": "true", + "Mains": "true", "Childs": "true", "Publisher": "false", "search": "true", "LetterType": "-1", "Category": "-1"} + url = f"{src.get('url')}?{urllib.parse.urlencode(params)}" + body = http_get(url, cfg, cache_name="codal.json") + if not body: + log("کدال پاسخ نداد؛ از منبع فایلی یا خبری استفاده کنید.") + return [] + out: list[Item] = [] + try: + data = json.loads(body) + for row in data.get("Letters", []) or data.get("letters", []) or []: + title = str(row.get("Title") or row.get("title") or "").strip() + if not title: + continue + out.append(item_from_dict({ + "title": title, + "symbol": str(row.get("Symbol") or row.get("symbol") or ""), + "company": str(row.get("CompanyName") or row.get("companyName") or ""), + "url": "https://codal.ir" + str(row.get("Url") or row.get("url") or ""), + "published_at": str(row.get("PublishDateTime") or row.get("publishDateTime") or ""), + }, source_name="کدال", cfg=cfg)) + except (json.JSONDecodeError, AttributeError, TypeError) as e: + log(f"ساختار پاسخ کدال ناشناخته بود: {e}") + return out + + +def fetch_rss(cfg: dict) -> list[Item]: + out: list[Item] = [] + for src in cfg.get("sources", []): + if src.get("type") != "rss": + continue + xml_text = http_get(src.get("url", ""), cfg, cache_name=f"rss-{src.get('name','feed')}.xml") + if not xml_text: + continue + out.extend(parse_feed(xml_text, src.get("name", "خبر"), cfg)) + return out + + +# ---------------------------------------------------------------- لایهٔ هوش مصنوعی (اختیاری) +LLM_PROMPT = """تو دستیار تحلیل اطلاعیه‌های کدال و خبر بازار سرمایه ایران هستی. +فقط از متن زیر استفاده کن و چیزی از خودت اضافه نکن. خروجی را فقط JSON بده با این کلیدها: +{"رویداد": "...", "جهت": "مثبت|منفی|خنثی", "بزرگی": "کم|متوسط|زیاد", "افق": "کوتاه|میان|بلند", + "اقدام": "یک اقدام بررسی‌محور و نه توصیهٔ خرید و فروش", "اطمینان": 0 تا 100} +هیچ وعدهٔ سود و هیچ دستور معامله‌ای نده. +عنوان: {title} +متن: {body} +""" + + +def llm_enrich(item: Item, cfg: dict) -> None: + """غنی‌سازی با مدل زبانی. اگر کلید یا سرویس نبود، برچسب «شاهد محلی» باقی می‌ماند.""" + conf = cfg.get("llm", {}) + provider = conf.get("provider", "none") + if provider in ("", "none", None): + return + prompt = LLM_PROMPT.replace("{title}", item.title).replace("{body}", item.body or item.title) + text = None + try: + if provider == "ollama": + payload = {"model": conf.get("model") or "qwen2.5:7b", "prompt": prompt, "stream": False, "format": "json"} + req = urllib.request.Request(conf.get("base_url") or "http://127.0.0.1:11434/api/generate", + data=json.dumps(payload).encode(), headers={"Content-Type": "application/json"}) + with urllib.request.urlopen(req, timeout=90) as r: + text = json.loads(r.read().decode()).get("response", "") + item.provider = "Ollama محلی" + elif provider in ("typesafe", "jev"): + key = os.environ.get(conf.get("api_key_env", "TYPESAFE_API_KEY"), "") + if not key: + item.provider = "شاهد محلی (کلید هوش مصنوعی تنظیم نشده)" + return + url = conf.get("base_url") or "https://api.typesafe.ai/v1/chat/completions" + payload = {"model": conf.get("model") or "jev-latest", + "messages": [{"role": "user", "content": prompt}]} + req = urllib.request.Request(url, data=json.dumps(payload).encode(), headers={ + "Content-Type": "application/json", "Authorization": f"Bearer {key}"}) + with urllib.request.urlopen(req, timeout=60) as r: + text = json.loads(r.read().decode())["choices"][0]["message"]["content"] + item.provider = "Jev/TypeSafe" + elif provider == "openrouter": + key = os.environ.get(conf.get("api_key_env", "OPENROUTER_API_KEY"), "") + if not key: + item.provider = "شاهد محلی (کلید هوش مصنوعی تنظیم نشده)" + return + url = conf.get("base_url") or "https://openrouter.ai/api/v1/chat/completions" + payload = {"model": conf.get("model") or "meta-llama/llama-3.1-8b-instruct", + "messages": [{"role": "user", "content": prompt}]} + req = urllib.request.Request(url, data=json.dumps(payload).encode(), headers={ + "Content-Type": "application/json", "Authorization": f"Bearer {key}"}) + with urllib.request.urlopen(req, timeout=60) as r: + text = json.loads(r.read().decode())["choices"][0]["message"]["content"] + item.provider = "OpenRouter" + except Exception as e: # شبکه، کلید، ساختار پاسخ + item.provider = f"شاهد محلی (خطای سرویس: {type(e).__name__})" + return + if not text: + return + m = re.search(r"\{.*\}", text, re.S) + if not m: + return + try: + data = json.loads(m.group(0)) + item.ai_note = (f"رویداد: {data.get('رویداد','')} | جهت: {data.get('جهت','')} | " + f"بزرگی: {data.get('بزرگی','')} | افق: {data.get('افق','')} | " + f"اقدام: {data.get('اقدام','')} | اطمینان: {data.get('اطمینان','')}") + except json.JSONDecodeError: + item.ai_note = text[:300] + + +# ---------------------------------------------------------------- اعلان‌ها +def notify(items: list[Item], cfg: dict) -> None: + hot = [i for i in items if i.score >= int(cfg.get("min_score_to_alert", 45))] + if cfg.get("notifiers", {}).get("console", True): + print("\n" + "=" * 78) + print(f"هشدارهای مهم امروز: {len(hot)} مورد از {len(items)} مورد پردازش‌شده") + print("=" * 78) + for it in hot[:25]: + print(f"[{it.score:>3}] {it.direction:<6} {it.category:<22} {it.symbol or '-':<10} {it.title[:70]}") + print(f" چرا مهم است: {it.reason}") + if it.ai_note: + print(f" {it.provider}: {it.ai_note}") + if it.url: + print(f" {it.url}") + if cfg.get("notifiers", {}).get("file", True): + logfile = BASE / "data" / "alerts.log" + logfile.parent.mkdir(parents=True, exist_ok=True) + with logfile.open("a", encoding="utf-8") as f: + for it in hot: + f.write(f"{jalali_str()} | {it.score} | {it.direction} | {it.title} | {it.url}\n") + for name, url_tpl in (("telegram", "https://api.telegram.org/bot{token}/sendMessage"), + ("bale", "https://tapi.bale.ai/bot{token}/sendMessage")): + conf = cfg.get("notifiers", {}).get(name, {}) + if not conf.get("enabled"): + continue + token = os.environ.get(conf.get("token_env", ""), "") + chat_id = conf.get("chat_id", "") + if not token or not chat_id: + continue + text = "هشدار کدال:\n" + "\n".join(f"• [{i.score}] {i.title[:120]}" for i in hot[:10]) + try: + payload = urllib.parse.urlencode({"chat_id": chat_id, "text": text}).encode() + req = urllib.request.Request(url_tpl.format(token=token), data=payload) + urllib.request.urlopen(req, timeout=20).read() + log(f"اعلان {name} ارسال شد.") + except Exception as e: + log(f"ارسال اعلان {name} ناموفق: {e}") + + +# ---------------------------------------------------------------- گزارش HTML +def build_report(items: list[Item], cfg: dict, path: Path | str = DEFAULT_REPORT) -> Path: + path = Path(path) + path.parent.mkdir(parents=True, exist_ok=True) + rows = [] + for it in items: + color = {"مثبت": "#0a7d33", "منفی": "#b3261e", "خنثی": "#5f6368", "نامعلوم": "#8a6d00"}.get(it.direction, "#5f6368") + rows.append(f""" + {it.score} + {html.escape(it.direction)} + {html.escape(it.category)} + {html.escape(it.symbol or '-')} + {html.escape(it.title)}{f'
    {html.escape(it.provider)}: {html.escape(it.ai_note)}
    ' if it.ai_note else ''} + {html.escape(it.reason)} + {f'منبع' if it.url else '—'} + {html.escape(it.source)} +""") + doc = f""" + +{html.escape(cfg.get('report_title','دیده‌بان'))} — {jalali_str()} + + +
    +

    {html.escape(cfg.get('report_title','دیده‌بان'))}

    +
    زمان گزارش: {jalali_str()} · تعداد رکورد: {len(items)}
    +
    +
    +
    این گزارش «دستیار تصمیم» است، نه توصیهٔ معامله. هیچ سود تضمینی در آن نیست. + امتیاز، ترکیبی از نوع رویداد، تازگی خبر و وجود عدد کمّی است. تصمیم نهایی و مسئولیت آن بر عهدهٔ کاربر است.
    + + + {''.join(rows) or ''} +
    امتیازجهتدستهنمادعنوانچرا مهم استمنبعمأخذ
    رکوردی نیست.
    +
    + ساختهٔ دیده‌بان کدال نسخهٔ {VERSION} · {html.escape(cfg.get('credit', CREDIT))}
    + برای اجرای روزانه: python kodal_alert.py watch --minutes 15 +
    +
    """ + path.write_text(doc, encoding="utf-8") + return path + + +# ---------------------------------------------------------------- خط لوله +def run_pipeline(cfg: dict, store: Store, sources: list[str] | None = None) -> list[Item]: + collected: list[Item] = [] + srcs = sources or [f"rss:{s.get('url')}" if s.get("type") == "rss" else s.get("type", "") + for s in cfg.get("sources", [])] + for spec in srcs: + kind, _, value = spec.partition(":") + if kind == "file": + collected.extend(load_file_source(value, cfg)) + elif kind == "rss": + local = dict(cfg) + local["sources"] = [{"type": "rss", "name": "خبر", "url": value}] + collected.extend(fetch_rss(local)) + elif kind == "codal": + collected.extend(fetch_codal(cfg)) + elif kind == "demo": + collected.extend(load_file_source(str(BASE / "demo" / "announcements.json"), cfg)) + collected.extend(parse_feed((BASE / "demo" / "news.rss").read_text(encoding="utf-8"), "خبر نمونه", cfg)) + else: + log(f"منبع ناشناخته: {spec}") + + fresh: list[Item] = [] + for it in collected: + if it.score >= int(cfg.get("min_score_to_alert", 45)) or symbol_in_watchlist(it, cfg.get("watchlist", [])): + llm_enrich(it, cfg) + if store.add(it): + fresh.append(it) + store.commit() + store.log_run(",".join(srcs), len(fresh)) + return sorted(fresh, key=lambda i: i.score, reverse=True) + + +def cmd_run(args) -> int: + cfg = load_config(args.config) + store = Store(cfg.get("db_path") or DEFAULT_DB) + items = run_pipeline(cfg, store, args.source) + notify(items, cfg) + path = build_report(store.recent(200), cfg, cfg.get("report_path") or DEFAULT_REPORT) + log(f"گزارش ساخته شد: {path}") + return 0 + + +def cmd_watch(args) -> int: + cfg = load_config(args.config) + while True: + cmd_run(args) + log(f"خواب {args.minutes} دقیقه‌ای…") + try: + time.sleep(max(1, args.minutes) * 60) + except KeyboardInterrupt: + log("خارج شد.") + return 0 + + +def cmd_report(args) -> int: + cfg = load_config(args.config) + store = Store(cfg.get("db_path") or DEFAULT_DB) + path = build_report(store.recent(args.limit), cfg, cfg.get("report_path") or DEFAULT_REPORT) + log(f"گزارش از پایگاه‌داده: {path} ({store.count()} رکورد)") + return 0 + + +def cmd_import(args) -> int: + cfg = load_config(args.config) + store = Store(cfg.get("db_path") or DEFAULT_DB) + items = load_file_source(args.file, cfg) + fresh = [i for i in items if store.add(i)] + store.commit() + log(f"{len(fresh)} رکورد تازه از {len(items)} رکورد ورودی ثبت شد.") + notify(fresh, cfg) + return 0 + + +def cmd_stats(args) -> int: + cfg = load_config(args.config) + store = Store(cfg.get("db_path") or DEFAULT_DB) + rows = store.conn.execute( + "SELECT category, COUNT(*), AVG(score) FROM items GROUP BY category ORDER BY COUNT(*) DESC").fetchall() + print(f"کل رکوردها: {store.count()}") + print(f"{'دسته':<24}{'تعداد':>8}{'میانگین امتیاز':>16}") + for cat, n, avg in rows: + print(f"{cat:<24}{n:>8}{avg:>16.1f}") + return 0 + + +def cmd_selftest(args) -> int: + """آزمون سریع درون‌برنامه‌ای (بدون نیاز به unittest).""" + checks = 0 + cat, direction, score, why = classify("افزایش سرمایه از محل تجدید ارزیابی دارایی‌ها", "") + assert cat == "افزایش سرمایه" and direction == "مثبت" and score >= 80, (cat, direction, score) + checks += 1 + cat2, dir2, s2, _ = classify("اعلام توقف نماد به دلیل ابهام در اطلاعات", "") + assert cat2 == "توقف و بازگشایی نماد" and dir2 == "منفی", (cat2, dir2) + checks += 1 + j = g2j(2026, 9, 22) + assert j == (1405, 6, 31), j + checks += 1 + it = Item(title="تست") + assert len(it.key()) == 16 + checks += 1 + print(f"خودآزمون: {checks} بررسی موفق") + return 0 + + +def cmd_demo(args) -> int: + args.source = ["demo"] + cfg = load_config(args.config) + cfg["db_path"] = str(BASE / "data" / "demo.sqlite3") + cfg["report_path"] = str(BASE / "data" / "demo-report.html") + store = Store(cfg["db_path"]) + items = run_pipeline(cfg, store, ["demo"]) + notify(items, cfg) + path = build_report(store.recent(200), cfg, cfg["report_path"]) + log(f"گزارش نمونه ساخته شد: {path}") + return 0 + + +# ---------------------------------------------------------------- CLI +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description="دیده‌بان اطلاعیه‌های کدال و خبر بازار سرمایه (بدون وابستگی بیرونی)") + ap.add_argument("--config", help="مسیر پروندهٔ تنظیمات JSON") + ap.add_argument("--db", help="مسیر پایگاه‌دادهٔ SQLite (پیش‌فرض: data/kodal.sqlite3)") + sub = ap.add_subparsers(dest="cmd") + + p_run = sub.add_parser("run", help="یک بار اجرا") + p_run.add_argument("--source", action="append", help="منبع: demo | file:PATH | rss:URL | codal") + p_run.set_defaults(func=cmd_run) + + p_watch = sub.add_parser("watch", help="اجرای دوره‌ای") + p_watch.add_argument("--minutes", type=int, default=15) + p_watch.add_argument("--source", action="append") + p_watch.set_defaults(func=cmd_watch) + + p_rep = sub.add_parser("report", help="ساخت گزارش از پایگاه‌داده") + p_rep.add_argument("--limit", type=int, default=200) + p_rep.set_defaults(func=cmd_report) + + p_imp = sub.add_parser("import", help="ورود اطلاعیه‌ها از پروندهٔ JSON یا CSV") + p_imp.add_argument("file") + p_imp.set_defaults(func=cmd_import) + + sub.add_parser("stats", help="آمار دسته‌ها").set_defaults(func=cmd_stats) + sub.add_parser("demo", help="اجرای کامل روی دادهٔ نمونه").set_defaults(func=cmd_demo) + sub.add_parser("selftest", help="آزمون سریع").set_defaults(func=cmd_selftest) + sub.add_parser("version", help="نسخه").set_defaults(func=lambda a: (print(f"kodal-alert {VERSION}"), 0)[1]) + + args = ap.parse_args(argv) + if not getattr(args, "cmd", None): + ap.print_help() + return 0 + if getattr(args, "db", None): + args.config = args.config + cfg_override = {"db_path": args.db} + original = load_config + + def patched(path): # اعمال --db روی هر زیرفرمان + cfg = original(path) + cfg.update(cfg_override) + return cfg + + globals()["load_config"] = patched + return int(args.func(args) or 0) + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/kodal-alert/run-daily.bat b/kodal-alert/run-daily.bat new file mode 100644 index 0000000000000000000000000000000000000000..0724bd2acafcfd8c60da795e4c9f5900757559fd --- /dev/null +++ b/kodal-alert/run-daily.bat @@ -0,0 +1,7 @@ +@echo off +chcp 65001 >nul +cd /d "%~dp0" +python kodal_alert.py run --source codal --source rss:https://www.farsnews.ir/rss +echo. +echo گزارش ساخته شد در data\report.html +timeout /t 5 >nul diff --git a/kodal-alert/run-demo.bat b/kodal-alert/run-demo.bat new file mode 100644 index 0000000000000000000000000000000000000000..ebb0603da6c9242ba6fd2a5a6644dd937efad141 --- /dev/null +++ b/kodal-alert/run-demo.bat @@ -0,0 +1,5 @@ +@echo off +chcp 65001 >nul +cd /d "%~dp0" +python kodal_alert.py demo +start "" "data\demo-report.html" diff --git a/kodal-alert/tests/test_kodal_alert.py b/kodal-alert/tests/test_kodal_alert.py new file mode 100644 index 0000000000000000000000000000000000000000..a4dee978acceb93e4d8867bdd5ce46ce41eab83a --- /dev/null +++ b/kodal-alert/tests/test_kodal_alert.py @@ -0,0 +1,194 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""آزمون‌های واحد دیده‌بان کدال — فقط کتابخانهٔ استاندارد (unittest).""" +from __future__ import annotations + +import json +import sys +import tempfile +import unittest +from datetime import datetime, timedelta, timezone +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) + +import kodal_alert as ka # noqa: E402 + + +class TestClassify(unittest.TestCase): + def test_capital_increase_rule(self): + cat, direction, score, why = ka.classify("افزایش سرمایه از محل تجدید ارزیابی دارایی‌ها", "") + self.assertEqual(cat, "افزایش سرمایه") + self.assertEqual(direction, "مثبت") + self.assertGreaterEqual(score, 80) + self.assertIn("قرارداد مشتقه", why) + + def test_halt_symbol_is_negative(self): + cat, direction, score, _ = ka.classify("توقف نماد به دلیل ابهام در اطلاعات", "") + self.assertEqual(cat, "توقف و بازگشایی نماد") + self.assertEqual(direction, "منفی") + + def test_legal_risk_rule(self): + cat, direction, _, _ = ka.classify("دعوی حقوقی و جریمهٔ مالیاتی", "") + self.assertEqual(cat, "دعاوی و ریسک حقوقی") + self.assertEqual(direction, "منفی") + + def test_lexicon_when_no_rule_matches(self): + cat, direction, score, _ = ka.classify("اطلاعیهٔ شمارهٔ ۱۲۳", "شرکت از رشد درآمد خبر داد") + self.assertEqual(cat, "سایر") + self.assertEqual(direction, "مثبت") + self.assertGreater(score, 0) + + def test_numeric_bonus_increases_score(self): + _, _, s_plain, _ = ka.classify("انعقاد قرارداد جدید", "") + _, _, s_number, _ = ka.classify("انعقاد قرارداد جدید به ارزش ۱۲ میلیون یورو", "") + self.assertGreater(s_number, s_plain) + + def test_recency_bonus_and_penalty(self): + now = datetime.now(timezone.utc) + _, _, fresh, _ = ka.classify("انعقاد قرارداد جدید", "", 1.0, now - timedelta(hours=2)) + _, _, old, _ = ka.classify("انعقاد قرارداد جدید", "", 1.0, now - timedelta(days=6)) + self.assertGreater(fresh, old) + + def test_score_bounds(self): + for title in ["توقف نماد", "افزایش سرمایه", "", "خبر بی‌ربط"]: + _, _, score, _ = ka.classify(title, title * 3) + self.assertGreaterEqual(score, 0) + self.assertLessEqual(score, 100) + + def test_source_weight(self): + _, _, s_norm, _ = ka.classify("توقف نماد", "", 1.0) + _, _, s_codal, _ = ka.classify("توقف نماد", "", 1.15) + self.assertGreaterEqual(s_codal, s_norm) + + +class TestDates(unittest.TestCase): + def test_jalali_known_dates(self): + self.assertEqual(ka.g2j(2026, 9, 22), (1405, 6, 31)) + self.assertEqual(ka.g2j(2024, 1, 1), (1402, 10, 11)) + + def test_jalali_string_shape(self): + s = ka.jalali_str(datetime(2026, 9, 22, 8, 5)) + self.assertTrue(s.startswith("1405/06/31")) + + +class TestStore(unittest.TestCase): + def test_insert_and_dedupe(self): + with tempfile.TemporaryDirectory() as tmp: + store = ka.Store(Path(tmp) / "t.sqlite3") + item = ka.Item(title="افزایش سرمایه", symbol="خساپا", score=80) + self.assertTrue(store.add(item)) + self.assertFalse(store.add(item)) # همان کلید، بار دوم رد می‌شود + store.commit() + self.assertEqual(store.count(), 1) + rows = store.recent(10) + self.assertEqual(rows[0].title, "افزایش سرمایه") + + def test_min_score_filter(self): + with tempfile.TemporaryDirectory() as tmp: + store = ka.Store(Path(tmp) / "t.sqlite3") + store.add(ka.Item(title="کم‌اهمیت", score=10)) + store.add(ka.Item(title="مهم", score=90)) + store.commit() + self.assertEqual(len(store.recent(10, min_score=50)), 1) + + def test_run_log(self): + with tempfile.TemporaryDirectory() as tmp: + store = ka.Store(Path(tmp) / "t.sqlite3") + store.log_run("demo", 7) + n = store.conn.execute("SELECT COUNT(*) FROM runs").fetchone()[0] + self.assertEqual(n, 1) + + +class TestFeeds(unittest.TestCase): + def test_parse_demo_rss(self): + text = (Path(__file__).resolve().parents[1] / "demo" / "news.rss").read_text(encoding="utf-8") + items = ka.parse_feed(text, "خبر نمونه", ka.DEFAULT_CONFIG) + self.assertGreaterEqual(len(items), 4) + self.assertTrue(all(i.title for i in items)) + self.assertTrue(any("توقف" in i.title or "بازگشایی" in i.title for i in items)) + + def test_bad_xml_returns_empty(self): + self.assertEqual(ka.parse_feed("", "خراب", ka.DEFAULT_CONFIG), []) + + +class TestSources(unittest.TestCase): + def test_load_json_file(self): + with tempfile.TemporaryDirectory() as tmp: + p = Path(tmp) / "a.json" + p.write_text(json.dumps([{"title": "افزایش سرمایه", "symbol": "فولاد"}], ensure_ascii=False), encoding="utf-8") + items = ka.load_file_source(str(p), ka.DEFAULT_CONFIG) + self.assertEqual(len(items), 1) + self.assertEqual(items[0].category, "افزایش سرمایه") + + def test_load_csv_file(self): + with tempfile.TemporaryDirectory() as tmp: + p = Path(tmp) / "a.csv" + p.write_text("title,symbol\nتوقف نماد,وبملت\n", encoding="utf-8") + items = ka.load_file_source(str(p), ka.DEFAULT_CONFIG) + self.assertEqual(items[0].direction, "منفی") + + def test_missing_file_is_safe(self): + self.assertEqual(ka.load_file_source("/no/such/file.json", ka.DEFAULT_CONFIG), []) + + def test_http_file_scheme(self): + with tempfile.TemporaryDirectory() as tmp: + p = Path(tmp) / "x.txt" + p.write_text("سلام", encoding="utf-8") + self.assertEqual(ka.http_get(f"file:{p}", ka.DEFAULT_CONFIG), "سلام") + + +class TestPipeline(unittest.TestCase): + def test_demo_pipeline_end_to_end(self): + with tempfile.TemporaryDirectory() as tmp: + cfg = json.loads(json.dumps(ka.DEFAULT_CONFIG, ensure_ascii=False)) + cfg["db_path"] = str(Path(tmp) / "demo.sqlite3") + cfg["report_path"] = str(Path(tmp) / "report.html") + cfg["min_score_to_alert"] = 40 + store = ka.Store(cfg["db_path"]) + items = ka.run_pipeline(cfg, store, ["demo"]) + self.assertGreaterEqual(len(items), 5) + scores = [i.score for i in items] + self.assertEqual(scores, sorted(scores, reverse=True)) + path = ka.build_report(store.recent(100), cfg, cfg["report_path"]) + body = path.read_text(encoding="utf-8") + self.assertIn('dir="rtl"', body) + self.assertIn("دیده‌بان", body) + self.assertIn(items[0].title[:20], body) + + def test_report_has_no_external_assets(self): + cfg = ka.DEFAULT_CONFIG + with tempfile.TemporaryDirectory() as tmp: + path = ka.build_report([ka.Item(title="نمونه", score=50)], cfg, Path(tmp) / "r.html") + body = path.read_text(encoding="utf-8") + self.assertNotIn("http://cdn", body) + self.assertNotIn(" int: + cfg = STATION / "config" / "gate.json" + if cfg.exists() and not force: + st = gate.status() + print("رمزها از قبل ساخته شده‌اند (چیزی عوض نشد).") + acc = st.get("accounts", {}) + print(" دروازه: " + ("روشن" if st.get("enabled") else "خاموش")) + print(" مدیر: " + (acc.get("admin", {}).get("id") or "—") + + " · کارفرما: " + (acc.get("guest", {}).get("id") or "—") + + (" (فعال)" if acc.get("guest", {}).get("enabled") else " (قطع)")) + print(" اگر رمزها را گم کرده‌ای: این فایل را با --force اجرا کن (رمز تازه می‌سازد).") + if CRED.exists(): + print(f" پروندهٔ رمز: {CRED}") + return 0 + + admin_pass = "Desk-" + secrets.token_hex(4) + guest_pass = "Desk-" + secrets.token_hex(4) + + adminauth.set_credentials(ADMIN_ID, admin_pass) + gate.sync_admin_from_panel() + gate.set_account("guest", GUEST_ID, guest_pass) + gate.set_enabled_account("guest", True) + gate.set_enabled(True) + + CRED.parent.mkdir(parents=True, exist_ok=True) + CRED.write_text( + f"""ایستگاه تصمیم مشتقه — رمزهای اولین ورود (ساختهٔ MAKE-PASSWORDS.py) +این پرونده را جایی نگه دار که فقط خودت ببینی. هر وقت خواستی رمز تازه بسازی: + python MAKE-PASSWORDS.py --force + +مدیر (پنل مدیریت): {ADMIN_ID} +رمز مدیر : {admin_pass} +کارفرما (مهمان) : {GUEST_ID} +رمز کارفرما : {guest_pass} + +قطع کارفرما همین حالا: python station/gate.py --guest-off +روشن‌کردن دوباره : python station/gate.py --guest-on +""", encoding="utf-8") + CRED.chmod(0o600) + + print("┌───────────────────────────────────────────────┐") + print("│ رمزهای تازه ساخته شد — همین حالا یادداشت کن │") + print("└───────────────────────────────────────────────┘") + print(f" پنل مدیر : {ADMIN_ID} / {admin_pass}") + print(f" کارفرما : {GUEST_ID} / {guest_pass}") + print(f" (همین‌ها در این پرونده هم نوشته شد: {CRED})") + print(" دروازه روشن است: بدون رمز، هیچ صفحه‌ای باز نمی‌شود.") + return 0 + + +if __name__ == "__main__": + raise SystemExit(make(force="--force" in sys.argv)) diff --git a/station/README-FA.md b/station/README-FA.md new file mode 100644 index 0000000000000000000000000000000000000000..d15fe3a69a0cbe1935934ace3cce884dbff65612 --- /dev/null +++ b/station/README-FA.md @@ -0,0 +1,626 @@ +# ایستگاه تصمیم مشتقه — راهنمای فارسی برای کاربر تازه‌کار + +نسخهٔ ۰٫۲٫۰ · ده گام · رابط گرافیکی · بدون نیاز به دانش برنامه‌نویسی · دفتر اتصال، دفتر آزمون زنده، +آزمون ۱۰ دقیقه‌ای و پروندهٔ سرمایه‌گذار + +## این برنامه به پنج سؤال شما جواب می‌دهد + +**۱. رابط گرافیکی گام‌به‌گام، با نتیجه‌ای که مستقیم دست شرکت بدهید.** +یازده گام داریم و هر گام یک کار روشن: خوش‌آمد و پنل مدیریت ← منبع داده ← تنظیمات ← خبر ← محاسبه ← تصمیم ← پس‌آزمایی ← بستهٔ تحویل شرکت ← دفتر آزمون زنده ← آزمون کور سرمایه‌گذار ← راهبردها و ریاضیِ پول. در گام ۸ یک پوشه ساخته می‌شود که همه‌چیز در آن است: گزارش تصمیم‌ها، فهرست سیگنال‌ها، سند روش کار، بسته‌های سفارش، نتیجهٔ پس‌آزمایی، **کارنامهٔ آزمون، برگهٔ آزمون سرمایه‌گذار، پروندهٔ سرمایه‌گذار (با اثر انگشت هر پرونده)**، و یک چک‌لیست نه‌گامی که خودشان در پنج دقیقه راستی‌آزمایی کنند. + +**۲. راهنمای خرید داده و محل اتصال آن در خود برنامه.** +در گام ۲ جدول «راهنمای خرید داده» هست: چه چیزی بخرید، تقریباً چقدر است، کلید را کجا بگذارید، و **بعد از اتصال چه چیزی در برنامه عوض می‌شود**. جای وارد کردن «قالب نشانی» و «مسیر JSON» و «کلید» هم همان‌جاست، با دکمهٔ «آزمایش اتصال». + +**۳. دادهٔ زندهٔ واقعی.** +حالت «دادهٔ زندهٔ واقعی» قیمت را از وب‌سرویس می‌خواند و روی اسنپ‌شات می‌نشاند؛ تازگی داده در نوار بالا سبز می‌شود. اگر سرویس جواب نداد، از حافظهٔ نهان استفاده می‌شود و همه‌چیز متوقف نمی‌شود. + +**۴. پس‌آزمایی روی دادهٔ گذشته.** +گام ۷ همان موتوری را که در تصمیم زنده کار می‌کند روی تاریخ اجرا می‌کند: نرخ برد، خطای مثبت کاذب، فرصت‌های از دست رفته، خطای پیش‌بینی، و منحنی سرمایه. نتیجهٔ واقعی هیچ نقشی در تصمیم ندارد (آزمون ضد آینده‌نگری در `tests` اجرا می‌شود). + +## دو راه اجرا + +### الف. رابط مرورگری، توصیه‌شده + +روی ویندوز: پروندهٔ `run-gui.bat` را دوبار کلیک کنید. مرورگر خودش باز می‌شود. +دستی: + +```bash +cd MATERIALS/money/gui +python web_server.py --port 8765 +``` + +سپس در مرورگر: `http://127.0.0.1:8765` + +چرا مرورگر؟ چون خط فارسی در مرورگر روی همهٔ سیستم‌ها درست و راست‌به‌چپ نشان داده می‌شود. (در آزمایش، نسخهٔ دسکتاپ روی لینوکس فارسی را شکسته نشان داد؛ روی ویندوز معمولاً درست است.) + +### ب. نسخهٔ دسکتاپ، بدون مرورگر + +```bash +python station.py # پنجرهٔ معمولی +python station.py --smoke # آزمون سلامت بدون کلیک کردن +``` + +روی ویندوز: `run-gui-desktop.bat` + +## نصب روی لپ‌تاپ در پنج گام (ویندوز، بدون اینترنت) + +۱. پایتون ۳ را از `python.org` نصب کنید؛ در نخستین پنجرهٔ نصب تیک **Add python.exe to PATH** را بزنید. +۲. پوشهٔ `MATERIALS/money` را کامل روی دسکتاپ کپی کنید (نه فقط یک پرونده). +۳. روی `gui\run-gui.bat` دوبار کلیک کنید؛ مرورگر خودش باز می‌شود. +۴. آزمون سلامت: `run-selftest.bat` (کارنامهٔ ۱۵ موردی، هر عدد دو بار حساب می‌شود) و + `run-investor-test.bat` (آزمون کور سرمایه‌گذار). +۵. برای دموی بی‌هزینه و بی‌اینترنت: `run-mock-feed.bat` را باز بگذارید و در گام ۲ پروفایل + «خوراک آزمایشی محلی» را فعال کنید؛ بعد گام ۵ و ۶ را اجرا کنید. + +هیچ `pip install` لازم نیست: برنامه فقط با کتابخانهٔ استاندارد پایتون و `tkinter` کار می‌کند. +اگر پایتون نصب نباشد، خودِ `run-gui.bat` پیام فارسی می‌دهد و راه نصب را می‌گوید. + +## چرخهٔ کار در عمل (نمونهٔ امروز) + +۱. گام ۱: «باز کردن پنل مدیریت» را بزنید، با شناسه و رمز وارد شوید و «بررسی سلامت برنامه» را اجرا کنید؛ باید همهٔ اجزا سبز باشد. +۲. گام ۲: با «دادهٔ نمونهٔ همراه برنامه» شروع کنید تا همه‌چیز را ببینید. +۳. گام ۳: نرخ سد را از بازده مؤثر صندوق درآمد ثابت همان روز بگذارید (شهریور ۱۴۰۵: حدود ۳۹ تا ۴۰ درصد). +۴. گام ۴: دکمهٔ «اجرای دیده‌بان روی دادهٔ نمونه» تا خبر و هشدار ساخته شود. +۵. گام ۵: «شروع محاسبه»؛ خلاصه و ریز سیگنال‌ها و دلیل رد‌ها را می‌بینید. +۶. گام ۶: یک سیگنال را انتخاب کنید و «تأیید» بزنید؛ بستهٔ سفارش روی صفحه می‌آید تا خودتان در سامانهٔ کارگزاری اجرا کنید. +۷. گام ۷: «اجرای پس‌آزمایی» روی پروندهٔ تاریخ (نمونه‌اش همراه برنامه است). +۸. گام ۸: «ساخت بستهٔ راستی‌آزمایی» و دادن پوشهٔ ساخته‌شده به شرکت. +۹. گام ۹: «ثبت سیگنال‌های گام ۵» در دفتر آزمون زنده، بعد «خواندن قیمت‌های تازه و بازسنجی دفتر»، + و در پایان «ساخت گزارش سرمایه‌گذار». این دفتر همان چیزی است که ارزش برنامه را ثابت می‌کند. +۱۰. گام ۱۰ (جلسهٔ سرمایه‌گذار): «نمایش پرسش‌ها» را بزنید و لپ‌تاپ را دست خودش بدهید. او حدس می‌زند، + بعد «داوری حدس‌های من» پاسخ برنامه را با فرمول و روش دوم رو می‌کند. بعد جدول آستانهٔ ریزش، + حساب‌رسی یک معاملهٔ گذشته، و «ساخت برگهٔ آزمون» برای امضا. تمام. + +## حالت دادهٔ زنده: چه بخرم و چطور وصل کنم + +| گزینه | هزینهٔ تقریبی | فیلدهایی که می‌دهد | پس از اتصال چه تغییر می‌کند | +|---|---|---|---| +| کدال (رسمی) | رایگان | اطلاعیه‌ها و صورت‌های مالی | هشدار و زمینهٔ خبری؛ همین حالا فعال است | +| tsetmc و بسته‌های پایتونی | رایگان ولی بی‌تعهد | قیمت پایانی و ریزمعاملات | قیمت پایه به‌روز می‌شود، بدون تضمین | +| سرویس دادهٔ خریدنی ایرانی | فروشنده تعیین می‌کند؛ در سایتش تأیید کنید | قیمت زنده، ریزمعاملات، دادهٔ تاریخی | تازگی داده سبز، به‌روزرسانی خودکار، و پس‌آزمایی روی تاریخ واقعی | +| دادهٔ تاریخی | معمولاً داخل همان بسته | سری زمانی آپشن و آتی و گواهی سپرده | نرخ برد و خطای پیش‌بینی با عدد واقعی، قابل ارائه به شرکت | + +نکتهٔ مهم: **وجه تضمین و مشخصات قرارداد را هیچ سرویسی به شما نمی‌دهد**؛ آن‌ها را از سامانهٔ کارگزاری بردارید و در پروندهٔ اسنپ‌شات بگذارید. برنامه آن را حدس نمی‌زند. + +## دفتر اتصال: هر وقت سرویس را گرفتم، وصلش کنم + +در گام ۲ یک «دفتر اتصال» اضافه شده است. کارش این است: + +- یک پروفایل از فهرست انتخاب می‌کنید؛ کادرهای قالب نشانی و مسیر JSON خودشان پر می‌شوند. +- «آزمایش اتصال این پروفایل» را می‌زنید و نتیجه را روی همان صفحه می‌بینید. +- «ذخیره و فعال کردن» را می‌زنید. از آن به بعد هر بار که برنامه بالا می‌آید، همین اتصال خودکار + فعال می‌شود (در نسخهٔ دسکتاپ هم). + +پروفایل‌های آمادهٔ رایگان که همین حالا در فهرست هستند: + +| پروفایل | چه می‌دهد | کلید لازم دارد؟ | +|---|---|---| +| خوراک آزمایشی محلی | قیمت ساختگی برای آزمون کل مسیر زنده | نه | +| tgju | دلار و طلا و سکه | نه | +| tsetmc | قیمت پایانی سهام و آپشن (با کد نماد در فیلد `feed_symbol`) | نه | +| صرافی ایرانی | نرخ لحظه‌ای ریالی | نه | +| سرویس خریدنی | قالب نمونه برای کلید خودتان | بله | + +**کاوشگر پاسخ سرویس:** اگر ساختار پاسخ سرویس را نمی‌دانید، نشانی را در کادر کاوشگر بگذارید و دکمه +را بزنید؛ فهرست عددهای داخل پاسخ با مسیرشان می‌آید و با «استفاده» مسیر JSON خودش پر می‌شود. + +**کلید کجا ذخیره می‌شود؟** پیش‌فرض این است که هیچ‌جا: کلید فقط تا بسته‌شدن برنامه در حافظه می‌ماند. +اگر تیک «کلید را روی این رایانه ذخیره کن» را بزنید، در پروندهٔ `config/keys.local.json` ذخیره می‌شود +(فقط روی رایانهٔ خودتان). مشخصات اتصال در `config/connections.json` است و هیچ‌وقت کلید در آن نوشته نمی‌شود. + +## خوراک آزمایشی محلی و دموی سرمایه‌گذار + +`python mock_feed.py` یک بازار ساختگی کوچک روی همان رایانه بالا می‌آورد (پیش‌فرض درگاه ۸۷۸۸) با یک +صفحهٔ زندهٔ قیمت. کارساز مرورگری خودش آن را همراه می‌آورد؛ اگر جدا خواستید: `run-mock-feed.bat`. + +این خوراک برای سه کار است: آزمودن کل مسیر «دادهٔ زنده»، تمرین کردن، و **نمایش دادن به سرمایه‌گذار +بدون هیچ هزینه‌ای**. داده‌اش ساختگی است و برنامه هم همه‌جا همین را با برچسب +«خوراک آزمایشی محلی (ساختگی)» نشان می‌دهد، پس هیچ‌وقت با دادهٔ واقعی اشتباه گرفته نمی‌شود. + +برای دموی سرمایه‌گذار: پروندهٔ `run-investor-demo.bat` را دوبار کلیک کنید و بعد این راهنما را باز کنید: +`DEMO-INVESTOR-FA.md` (سناریوی بیست دقیقه‌ای، هفت لحظهٔ «آها»، پاسخ‌های آماده به پرسش‌های +سرمایه‌گذار، و پروتکل آزمون بی‌پول دو هفته‌ای). پاسخ کوتاه: برای این دمو هیچ خریدی لازم نیست، +نه کلید داده نه مدل زبانی. + +## گام ۹: دفتر آزمون زنده + +هر سیگنال با ساعت دقیق، قیمت‌های همان لحظه، نرخ سد و ورودی‌های ریاضی در یک دفتر ثبت می‌شود +(`data/trial.sqlite3`). بعداً با دکمهٔ «بازسنجی»، همان موتور روی قیمت‌های تازه اجرا می‌شود و دفتر +می‌گوید حاشیهٔ آن سیگنال امروز چقدر است: «بازتر شد»، «کم شد»، «تقریباً ثابت»، یا «زیر کف رفت». + +هر ثبت یک **هش زنجیره‌ای** دارد (هشِ ردیف قبلی داخل خودش است). با «بررسی زنجیرهٔ هش» می‌توانید نشان +بدهید هیچ ردیفی بعد از ثبت عوض نشده؛ اگر کسی عوض کند، زنجیره می‌شکند. گزارش دفتر +(`data/trial-report.html` و CSV آن) سند ارائه به شرکت است. توجه: این گزارش «سود تحقق‌یافته» نیست؛ +تغییر بازده انتظاری در طول زمان است. + +## اتصال خودکار: «برنامه خودش بگردد و ببیند کدام منبع امروز کار می‌کند» + +من نمی‌توانم از جای خودم بررسی کنم که سرویس‌های ایرانی امروز چه پاسخی می‌دهند (شبکهٔ من به +بسیاری از آن‌ها وصل نمی‌شود). ولی خودِ برنامه روی رایانهٔ شما می‌تواند. در گام ۲ دکمهٔ +**«بگرد و گزارش بده»** این کار را می‌کند: + +- چند منبع رایگان را یکی‌یکی امتحان می‌کند (بدون کلید، بدون هزینه). +- پاسخ را می‌خواند و عدد را از نظر عقلی می‌سنجد: تاریخ نباشد، شمارنده نباشد، صفر نباشد، + بیرون بازهٔ باورپذیر نباشد. +- برای هر منبع می‌گوید **چرا** کار کرد یا کار نکرد: «پاسخی نیامد»، «پاسخ JSON نبود»، + «مسیر عدد سالم پیدا نشد»، «عدد شبیه تاریخ است»، «کد نماد پیدا نشد». +- اگر «کد نماد» لازم باشد (مثل قیمت پایانی سهام)، خودش کد هر نماد را پیدا می‌کند و در ستون + «کد نماد» همان ردیف می‌نویسد. +- با دکمهٔ دوم، اولین منبع سالم ذخیره و فعال می‌شود؛ از آن به بعد هر بار خودکار وصل می‌شود. + +خط فرمان و ویندوز: + +```bash +python autoconnect.py # فقط گزارش +python autoconnect.py --save # ذخیره و فعال‌کردن منبع سالم +``` + +روی ویندوز: `run-autoconnect.bat` + +**دو سنجهٔ صداقت که همراه همین بخش هست:** اگر منبعی برای همهٔ نمادها یک عدد بدهد (مثل نرخ ارز)، +وضعیت «جزئی» می‌شود و برچسب «نرخ واحد، نه نماد» می‌خورد تا کسی آن عددها را به‌جای قیمت سهام نگیرد. +و اگر سرویس برای نام نماد فارسی پاسخ ندهد، برنامه خطا را همان‌طور که هست گزارش می‌کند؛ عدد از خودش نمی‌سازد. + +**نتیجهٔ آزمون واقعی در محیط سازنده (شهریور ۱۴۰۵):** از میان چهار منبع رایگان، یکی پاسخ سالم داد: +بازار ریالی یک صرافی ایرانی (نرخ لحظه‌ای، بدون کلید). در همان آزمون، tgju پاسخ خطا داد و +cdn.tsetmc خطای گواهی شبکه. این تفاوت‌ها طبیعی است؛ به همین دلیل «اتصال خودکار» این کار را +روی رایانهٔ **شما** انجام می‌دهد، نه یک‌بار برای همیشه در دفترچهٔ راهنما. + +نکتهٔ صادقانه: نرخ ریالی صرافی، «قیمت پایهٔ سهام» نیست. کاربردش اثبات کارکرد اتصال زندهٔ واقعی +با صفر هزینه است. برای سیگنال روی سهام، یا قیمت زندهٔ نمادی لازم است (سرویس)، یا اعداد کارگزاری +را دستی وارد می‌کنید (پایین). + +## وارد کردن اعداد کارگزاری در جدول (بدون ویرایش JSON) + +در گام ۲، جدول **«وارد کردن اعداد کارگزاری»** را پر می‌کنید و دکمهٔ «ذخیرهٔ اسنپ‌شات امروز» را +می‌زنید. برنامه پروندهٔ تاریخ‌دار می‌سازد: + +``` +data/snapshots/snapshot-YYYY-MM-DD.json +``` + +چرا تاریخ‌دار؟ هر روز پروندهٔ خودش: سابقهٔ قابل ممیزی می‌شود و اشتباه یک روز، روزهای دیگر را +خراب نمی‌کند. + +**قاعدهٔ «روز واقعی»:** پرونده فقط وقتی روز واقعی حساب می‌شود که تیک +«این اعداد را خودم از سامانهٔ کارگزاری برداشتم» را زده باشید. برنامه هم نام پرونده را می‌سنجد +(«نمونه/قالب/demo» ساختگی است) هم همین تیک را. اگر خودتان با ویرایشگر متن پرونده می‌سازید، +خط `"source": "manual-broker"` را در آن بگذارید. +وجه تضمین را حتماً از سامانهٔ کارگزاری بردارید؛ هیچ سرویسی این عدد را نمی‌دهد. + +## چسباندن اعداد کارگزاری، بدون تایپ دستی (گام ۲) + +در کارت «وارد کردن اعداد کارگزاری» یک کادر تازه هست: **متن را از سامانهٔ کارگزاری کپی کنید و +همان‌جا بچسبانید**، بعد «تشخیص خودکار و افزودن به جدول» را بزنید. برنامه رقم فارسی، جداکنندهٔ +هزارگان («7,600»)، کلمهٔ «تومان»/«ریال»، سرستون‌ها («قیمت سهم، اعمال، پرمیوم، روز») و برچسب‌های +داخل ردیف را می‌فهمد و ردیف‌ها را در جدول می‌سازد. هر چیزی که نفهمد، در کادر گزارش صادقانه +می‌گوید (نه بی‌صدا). تیک «عددها به تومان است» فقط قیمت‌ها را ×۱۰ می‌کند، نه «روز» را. +ذخیره همچنان با تیک تأیید خودتان انجام می‌شود؛ پس روز «واقعی» بی‌اجازه ساخته نمی‌شود. + +راهنمای ستون‌به‌ستون هم داخل همان کارت (بازشو) آمده: هر عدد را از کجا بیاورید. +برای کاهش خطای انسانی، اگر سرویس دادهٔ رایگان وصل باشد، همان عددها خودکار خوانده می‌شوند و +دستی فقط برای «وجه تضمین» می‌مانَد (که فقط کارگزاری آن را دارد). + +## گواهی استفادهٔ موفق (پنل مدیریت) + +ورود به پنل: در گام ۱ دکمهٔ «باز کردن پنل مدیریت» یا نشانی `/admin`. شناسهٔ پیش‌فرض `mafhoom` است و +رمز را خودتان با `python3 adminauth.py --set-pass "رمز تازه"` عوض می‌کنید (رمز فقط هش‌شده در +`config/admin.json` می‌ماند؛ توکن ورود یک‌ساعته است و با بستن برنامه پاک می‌شود). +`usage_meter.py` هر کار موفق را در دفتر محلی و **زنجیره‌هش‌دار** ثبت می‌کند: داوری سیگنال، تصمیم +ثبت‌شده، مراسم روزانه، آزمون‌ها، ورود اعداد و بستهٔ شاهد. گواهی دو امضا دارد (شما و شرکت) و هیچ +دادهٔ معاملاتی یا نامی داخلش نیست؛ به اینترنت هم چیزی فرستاده نمی‌شود. کارت آن در **پنل مدیریت** است و +سند تحلیلی‌اش `MATERIALS/money/11-usage-and-percent-fa.md` (مدل درصدگرفتن، با سود و زیان هر مدل). + +## بستهٔ تحویل شرکت (یک فرمان) + +```bash +python3 make_kit.py --zip # می‌سازد: ../delivery/iran-desk-kit و فایل zip همان +``` + +بسته فقط **کد و قالب و سند** را برمی‌دارد؛ گزارش‌ها، دفترها، بسته‌های شاهد، حافظهٔ نهان و رمز پنل را +با خودش نمی‌برد (۸۳ پروندهٔ ساخته‌شده کنار گذاشته می‌شود). اول هر پرونده با اثر انگشت `sha256` در +`KIT-MANIFEST.json` فهرست می‌شود، بعد `START-HERE-FA.md` نصب و ده دقیقهٔ اول و مرزهای صادقانه را +می‌گوید. خودِ همین بسته، جدا از درخت اصلی، آزموده شده است: **۶۵۸ آزمون واحد سبز** و +**۱۹۲ بررسی تعاملی مرورگری، صفر ناموفق** روی درگاه دیگری و با رمز پنل خودش. + +## برگهٔ «پیشنهاد یک‌صفحه‌ای» (گام ۸) + +```bash +python3 offer.py --client "نام شرکت" # برگه با قیمت «توافقی» +python3 offer.py --client "نام شرکت" --monthly 40000000 --setup 100000000 +``` + +دو نسخه می‌سازد: `data/offer-one-pager.html` (چاپی، خودبسنده) و `.md` برای ایمیل و واتساپ. هیچ عدد +سودی در آن نیست، هیچ قیمتی هم از خودش نمی‌سازد؛ اگر مبلغ ندهید «توافقی» می‌ماند. دکمه‌هایش در گام ۸ +است: نام شرکت را بنویسید → «ساخت پیشنهاد یک‌صفحه‌ای» → «نمایش پیشنهاد». + +## بستهٔ پیام‌های معرفی و پیگیری (گام ۸) + +```bash +python3 outreach.py --client "نام مخاطب" --kind brokerage # یا company / teacher / known +python3 outreach.py --checklist # آماده‌سازی پیش از پیام اول +``` + +چهار متن آماده می‌سازد (پیام اول · پیام بعد از جواب · تأیید وقت · پیگیری) به‌همراه اسکریپت تماس +تلفنی و پاسخ چهار مخالفت رایج؛ در گام ۸ با منوی لحن و دو دکمه. قاعده‌ها سخت‌گیرانه‌اند: پیام اول +کوتاه و بدون پیوست، هیچ عدد سودی در هیچ متنی، و پیگیری فقط سه بار (روز ۰، ۳، ۱۰). سند تحلیلی‌اش +`MATERIALS/money/14-first-meeting-fa.md` است. + +## تابلوی پیگیری مخاطبان (گام ۸) + +```bash +python3 prospects.py --add "نام مخاطب" --kind brokerage --channel phone +python3 prospects.py --sent "نام مخاطب" # روز ۰: پیام اول +python3 prospects.py --followup "نام مخاطب" # روز ۳ و روز ۱۰ (بار سوم رد می‌شود) +python3 prospects.py --reply "نام مخاطب" # جواب داد → قرار جلسه +python3 prospects.py --outcome "نام مخاطب" --result "نه" # یا بله / بعداً / بی‌جواب +python3 prospects.py --todo # امروز چه کاری به گردن من است +python3 prospects.py --week # سه عدد هفته: پیام · تماس · جلسه +python3 prospects.py --sheet # برگهٔ چاپی + نسخهٔ متنی +``` + +قاعدهٔ پیگیری در خود کد قفل است: بار سوم پیگیری رد می‌شود («ببند و رهایش کن»)، «بستن پرونده» +نتیجهٔ «بی‌جواب» می‌گذارد تا آمار الکی درست نشود، و هر شمارهٔ تلفن یا عدد دراز در یادداشت +ماسک می‌شود. دفتر پیش‌فرض `data/prospects.json` است (با `IRAN_DESK_PROSPECTS` جای دیگری بگذارید). +در رابط، همین کارت در گام ۸ است و بار اول خودش تابلو را می‌خواند. + +«بعداً» بی‌تاریخ نمی‌ماند: با `--result بعداً --next-on 2026-10-22` تاریخ سر‌زدن ثبت می‌شود و +پیش‌فرض سی روز بعد است؛ همان روز، مخاطب به «کار امروز» برمی‌گردد — یک پیام، نه بیشتر. + +## روز اول مشتری — از «بله» تا پایان هفتهٔ دوم (گام ۸) + +```bash +python3 onboarding.py --client "نام مشتری" # برگهٔ روز اول +python3 onboarding.py --client "نام مشتری" --start 2026-09-22 --monthly 40000000 +python3 onboarding.py --json # خلاصهٔ ماشین‌خوان +``` + +برگهٔ چاپیِ بعد از «بله»: پنج کار روز اول (اجازه‌نامهٔ آزمون نام‌دار، نصب، اتصال رایگان، اعداد +کارگزاری خودشان، مراسم و راستی‌آزمایی)، فهرست «در این دو هفته چه چیزی خریده نمی‌شود»، شرط‌های +کارنامهٔ «آماده» و **روز بازبینی**، سه پلهٔ ارائه با قاعدهٔ «پرداخت در برابر شاهد»، و بخش «اگر +وسط راه پشیمان شدید». سه عدد این برگه دست‌نویس نیستند: طول آزمون از `license.TRIAL_DAYS`، +شرط‌های کارنامه از پیش‌فرض‌های `daily_trial.scorecard`، و عدد بستهٔ تحویل از `KIT-MANIFEST.json` +خوانده می‌شوند. سند تحلیلی‌اش `MATERIALS/money/15-after-meeting-fa.md` است. + +## مراسم فروش امروز — بیست دقیقه (گام ۸) + +```bash +python3 sales_ritual.py # برنامهٔ امروز +python3 sales_ritual.py --sender "مسعود" --on 2026-09-22 # نام امضا و تاریخ دلخواه +python3 sales_ritual.py --sheet # برگهٔ چاپی امروز +python3 sales_ritual.py --json +``` + +تابلوی پیگیری می‌گوید امروز نوبت کیست؛ بستهٔ پیام‌ها متن آماده را دارد. این ماژول همان دو را +کنار هم می‌گذارد و یک **برگهٔ اجرایی** می‌سازد: کدام کار، برای کدام مخاطب، با کدام متن، در چه +دقیقه‌ای — جمعاً بیست دقیقه. اگر کانال مخاطب «تلفن» باشد، کارش با اسکریپت تماس و پنج دقیقه حساب +می‌شود؛ «ثبت نتیجهٔ جلسه» کار دفتری است و متن ندارد. + +سه چیز در خود کد قفل است: **سقف پنج پیام در روز** و **بودجهٔ بیست دقیقه** (هر کاری که جا نشد، با +دلیلش به «فردا» می‌رود و سقف جابه‌جا نمی‌شود) · متن‌ها فقط از `outreach.messages` می‌آیند (تنها +استثنا: پیام «روز موعود» که همین‌جا نوشته شده و همان آزمون‌های سختی را می‌دهد) · **روز خالی، پیام +نمی‌سازد**: اگر نوبت کسی نیست، برگه می‌گوید پنج نام تازه اضافه کن. + +## جلسهٔ بازبینی دو هفته‌ای (گام ۸) + +```bash +python3 review_meeting.py --client "نام مشتری" --start 2026-09-22 +python3 review_meeting.py --client "نام مشتری" --start 2026-09-22 --on 2026-10-06 --monthly 40000000 +python3 review_meeting.py --json +``` + +برگهٔ روز چهاردهم: همان روزی که اجازه‌نامهٔ آزمون تمام می‌شود و باید تصمیم گرفته شود. برگه بیست +دقیقهٔ جلسه را دقیقه‌به‌دقیقه می‌چیند و سه چیز را کنار هم می‌گذارد: **سه شاهد** که خودشان روی همان +لپ‌تاپ اجرا می‌کنند (کارنامه، دفتر استفاده، آزمون ایستگاه — و اختیاری: بستهٔ راستی‌آزمایی)، **پنج +شرط کارنامهٔ «آماده»** که از خود کد خوانده می‌شوند، و **دو خروجی روشن**: ادامه با پرداخت (پله‌ها از +`license.ladder`، قیمت از `offer.price_line` — اگر عددی ندهید «توافقی») یا توقف بی‌گلایه‌مندی. + +هر شاهد دو ستون دارد: «چه چیزی را نشان می‌دهد» و «چه چیزی را نشان نمی‌دهد»؛ مرزِ عدد جلوی چشم +طرف مقابل است. اگر کارنامه آماده نبود، خروجی سوم روشن است: **تمدید یک‌بار و بی‌هزینهٔ چهارده +روزه** با همان شرط‌ها — پس هیچ‌کس تحت فشار تصمیم نمی‌گیرد. اگر همان روز تصمیم نگرفتند، تاریخ سر +زدن (پیش‌فرض سی روز بعد) و دو پیام کوتاه (روز ۳ و روز ۷) روی برگه نوشته شده و در تابلو ثبت می‌شود. +سند تحلیلی‌اش `MATERIALS/money/16-review-meeting-fa.md` است. + +## دروازهٔ ورود: کارفرما از راه دور ببیند، رمز مدیر لو نرود (گام ۱ و ۸) + +اگر می‌خواهید کارفرمایی در شهر دیگر همان برنامهٔ در حال اجرا را ببیند و تست کند، **دروازهٔ ورود** را +روشن کنید. سه فرمان، یک‌بار: + +```bash +python3 gate.py --sync-admin # رمز مدیر دروازه = همان رمز پنل مدیریت +python3 gate.py --guest-id masoud --guest-pass "رمز-کارفرما" # حساب نام‌دار کارفرما (دست‌کم ۸ نویسه) +python3 gate.py --on # روشن: از این لحظه، بدون ورود هیچ صفحه‌ای باز نمی‌شود +python3 gate.py --status # کنترل وضعیت و شمار نشست‌های باز +``` + +از این لحظه، آدرس برنامه **صفحهٔ ورود** می‌آید. کارفرما با حساب مهمان وارد می‌شود: + +| کارفرما (مهمان) | می‌بیند | نمی‌تواند | +| --- | --- | --- | +| یازده گام و محاسبه‌های برنامه | ✅ | — | +| خروجی‌ها و برگه‌های چاپی (پیشنهاد، پیام‌ها، تابلو، راهنمای تازه‌کار، کارنامهٔ بازبینی) | ✅ | — | +| پنل مدیریت، صدور اجازه‌نامه، عوض‌کردن رمزها، خاموش‌کردن برنامه | ❌ | ❌ | + +نشست هر کاربر هشت ساعت پس از آخرین کارش بسته می‌شود؛ رمزها فقط هش‌شده روی دیسک می‌مانند و پنج +تلاش ناموفق، آن نشانی را چند دقیقه قفل می‌کند. روی رایانهٔ خودِ صاحب برنامه، اگر دروازه روشن باشد +باید یک‌بار با حساب مدیر وارد شود؛ برای برگشت به حالت قبل (همین لپ‌تاپ = مدیر) کافی است +`python3 gate.py --off` بزنید. در گام ۱ برنامه، **کارت مدیر** دکمه‌های «روشن/خاموش‌کردن دسترسی +کارفرما»، «بستن نشست‌های باز مهمان» و **«خاموش کردن برنامه»** را دارد؛ همه فقط با حساب مدیر. +سند کامل (دو مسیر آدرس دادن، چک‌لیست جلسه، مرزهای صادقانه) در `docs/17-remote-access-fa.md`. + +### راهنمای کارفرما و امنیت + +- **راهنمای کارفرما** روی مسیر `/guide` سرو می‌شود: پیش از ورود و بعد از ورود باز است، بدون + اینترنت کار می‌کند، و همهٔ نیاز کاربر را در یازده بخش می‌گوید (روز اول، هر روز، تصمیم‌ها، + روز چهاردهم، جدول پیام‌های خطا، بیست پرسش پرتکرار، حریم خصوصی، پشتیبانی). هیچ توضیح فنی و هیچ + فرمولی در آن نیست؛ آزمون `tests/test_guide.py` این را سخت می‌گیرد. +- **بررسی امنیتی** با ۲۲ حملهٔ واقعی (`tests/test_security.py`): پیمایش مسیر، کوکی جعلی، بالا رفتن + از نقش کارفرما، CSRF، روش‌های ناخواسته، بدنهٔ غول‌آسا، و تلاش پی‌درپی رمز. سرآیندهای امنیتی و + پرچم `Secure` کوکی روی HTTPS اضافه شد؛ وضعیت سامانه هم برای ناشناس دیگر شناسه‌ها را لو نمی‌دهد. + گزارش کامل: `../20-security-review-fa.md`. + +### کاربران را خودت می‌سازی و هر وقت خواستی حذف می‌کنی (نسخهٔ ۰٫۲٫۰) + +حساب «مهمان» یکی بود؛ حالا **هر تعداد کاربر** می‌توانی بسازی. شناسه و رمز را خودت تعیین می‌کنی، +رمز فقط هش‌شده می‌ماند، و «حذف» **همان لحظه** نشست بازِ آن کاربر را هم می‌بندد: + +```bash +python3 gate.py --user-add ali "رمز-علی" --user-note "کارشناس شرکت" # کاربر تازه +python3 gate.py --users # فهرست کاربران (بدون رمز و هش) +python3 gate.py --user-off ali # قطع فوری دسترسی (نشستش بسته می‌شود) +python3 gate.py --user-on ali # وصل‌کردن دوباره +python3 gate.py --user-del ali # حذف کامل +python3 gate.py --check ali "رمز-علی" # آزمودن یک جفت شناسه/رمز +``` + +در خود برنامه (گام ۱، کارت مدیر) و در **پنل مدیریت، کارت ۴** هم همین کارها را با دکمه می‌کنی: +ساخت کاربر، فهرست با شمار نشست باز، قطع/وصل، و حذف کامل. در همان کارت، **شناسه و رمز حساب مدیر +(خودت)** را هم می‌توانی تعیین کنی. همهٔ کاربران نقش «مهمان» دارند: کل برنامه و برگه‌ها را می‌بینند، +ولی پنل مدیریت، صدور مجوز، عوض‌کردن رمزها، مدیریت کاربران و خاموش‌کردن برنامه برایشان بسته است. + +## لینک دادن به کارفرما، و بردن برنامه روی سایت + +دو پوشه، دو کار: + +- **`share/`** — لینک موقت برای جلسهٔ نمایش: `bash share/share-gui.sh` (لینوکس/مک) یا دوبار کلیک روی + `share/share-gui.bat` (ویندوز). ایستگاه را روشن می‌کند، لینک `https` می‌گیرد و همان را برای + کارفرما می‌فرستی. بستن پنجره = بسته‌شدن لینک و برنامه (`stop-gui.bat` هم هست). راهنمای فارسی: + `share/README-SHARE-FA.md`. +- **`deploy/`** — نشانی ثابت روی سرور: `Dockerfile`، `docker-compose.yml`، `Caddyfile` (HTTPS + خودکار با یک دامنه)، `station.service` برای systemd، `backup.sh` (پشتیبان روزانه با اثر انگشت) + و راهنمای گام‌به‌گام `deploy/README-DEPLOY-FA.md`. + +هر دو مسیر پشت همان **دروازهٔ ورود** می‌نشینند: بدون شناسه و رمز، هیچ صفحه و هیچ خروجی‌ای باز +نمی‌شود؛ کارفرما (حساب مهمان) همه‌چیز را می‌بیند و تست می‌کند، ولی پنل مدیریت، صدور اجازه‌نامه، +عوض‌کردن رمزها و خاموش‌کردن برنامه برایش بسته است. سند کامل: `docs/17-remote-access-fa.md`. + +## راهنمای کامل برای تازه‌کار (سند جداگانه) + +`MATERIALS/money/13-novice-walkthrough-fa.md`: هر بخش برنامه با نام واقعی دکمه‌ها، جدول عددهایی که +از کارگزاری می‌گیرید و کجای تابلو است، نقشهٔ صادقانهٔ اتوماسیون، و جدول «علامت ← معنا ← کارِ شما». +در خود برنامه هم از گام ۲ و گام ۹ با دکمهٔ «راهنمای هر بخش (برای تازه‌کار)» باز می‌شود. + +## گام‌به‌گام برای تازه‌کار: از صفر تا اولین تصمیم + +۱. `run-gui.bat` را بزنید؛ مرورگر باز می‌شود. +۲. **پنل مدیریت:** «بررسی سلامت برنامه» (باید همه سبز باشد) و بعد «اجرای آزمون ۱۰ دقیقه‌ای». +۳. **گام ۲:** در جدول اعداد، اعداد امروز را از کارگزاری بچسبانید (یا کادر چسباندن را استفاده کنید)، + تیک تأیید را بزنید و «ذخیرهٔ اسنپ‌شات امروز» را بزنید. اگر سرویس رایگان دارید، اول «دفتر اتصال». +۴. **گام ۳:** سرمایه، نرخ سد و سقف ریسک را ببینید و در صورت نیاز عوض کنید (پیش‌فرض‌ها محافظه‌کارانه‌اند). +۵. **گام ۴:** هشدارها و خبرهای کدال را نگاه کنید (اگر پایگاه‌دادهٔ کدال وصل باشد). +۶. **گام ۵:** «اجرا و محاسبه». +۷. **گام ۶:** سیگنال‌ها را ببینید و تأیید یا رد کنید؛ برای داوری سیگنال ابزارهای دیگر، همان کارت را + پر کنید و «داوری کن و برگه بساز» را بزنید. +۸. **گام ۷:** پس‌آزمایی روی تاریخ (برای دیدن رفتار برنامه در گذشته). +۹. **گام ۸:** «بستهٔ تحویل شرکت» را بسازید (پرونده‌های شاهد + مانیفست با اثر انگشت). +۱۰. **گام ۹:** «۰. مراسم امروز» را بزنید تا دفتر و گزارش سرمایه‌گذار به‌روز شود؛ بعد «کارنامه» را ببینید. +۱۱. **گام ۱۰:** لپ‌تاپ را به سرمایه‌گذار بدهید؛ «نمایش پرسش‌ها» و بعد سنجش حدس‌هایش. +۱۲. هر روز فقط گام ۲ و گام ۹؛ شصت ثانیه. کارنامه با ۱۰ روز ثبت و دست‌کم ۵ روز واقعی «آماده» می‌شود. + +## ورودی روزانه، دقیق و مجانی (گام ۲) + +هر روز فقط ده عدد لازم است و همه‌شان مجانی: قیمت پایه، آتی، اعمال، پرمیوم، روز، وجه تضمین، حجم، +اسپرد، نماد و راهبرد. محل هر عدد در راهنمای `MATERIALS/money/10-daily-inputs-fa.md` آمده و از +جدول «وارد کردن اعداد کارگزاری» گام ۲ با دو دکمه باز می‌شود («راهنما: هر روز چه عددی بگیرم؟» و +«نمایش قالب پرونده»). قالب کامل پنج نوع معامله در `data/snapshot-template.json` است. + +## مجوز دسترسی، پشتیبانی و عیب‌یابی (پنل مدیریت) + +این برنامه «فروش نسخه» نیست؛ **اجازه‌نامهٔ دسترسی نام‌دار و زمان‌دار** است: + +- `license.py` مجوز می‌سازد (نام شرکت، مدت، مسئول، امضای `sha256`) و در گام ۱ رابط با دکمه + «صدور مجوز دسترسی» و «وضعیت مجوز» نمایش داده می‌شود؛ همان امضا در بستهٔ شاهد گام ۸ هم می‌آید. +- **سند چاپی اجازه‌نامه** (دکمهٔ «ساخت سند مجوز» در پنل مدیریت یا `python3 license.py --document`): + یک پروندهٔ دواِمضا برای جلسه — نام مشتری، مدت، امضای چک‌سام، و جای خالی امضای دو طرف. +- **در بستهٔ شاهد گام ۸**، ایستگاه خودش این دو سند را تازه می‌سازد و کنار شاهدها می‌گذارد: + `15-license-doc.html` · `16-license-doc.md` (اجازه‌نامه) و `17-usage-statement.html` · + `18-usage-statement.md` (گواهی استفادهٔ موفق). هر چهار پرونده در مانیفست با اثر انگشت می‌آیند. +- `diagnose.py` گزارش عیب‌یابی می‌سازد: نسخه‌ها، سلامت هشت‌جزئی، مجوز، اتصال فعال، اثر انگشت موتور، + وضعیت دفتر و پرونده‌های مهم. یک پرونده برای پشتیبانی کافی است. +- سند تحلیلی «بفروشم یا دسترسی بدهم؟»: `MATERIALS/money/09-sell-or-grant-access-fa.md`. + +## داوری سیگنال ابزارهای دیگر (گام ۶) + +دیده‌بان‌ها و ماشین‌حساب‌های بازار فارسی، قیمت و فیلتر و قیمت تئوری می‌دهند؛ ولی نمی‌گویند آن +سیگنال با کارمزد واقعی، اسپرد، نقدشوندگی و نرخ سد می‌مانَد یا می‌افتد. کارت «داوری سیگنال +ابزارهای دیگر» در گام ۶ همان یک کار را می‌کند: + +- عددهای سیگنال نرم‌افزار فعلی‌تان را (به شکل JSON) وارد کنید و «داوری کن و برگه بساز» را بزنید. +- خروجی: «می‌ماند / می‌افتد» با دلیل دروازه‌ها، **نقطهٔ برگشت** (تا کدام قیمت یا پرمیوم معامله + می‌مانَد)، **فاصله تا مارجین‌کال** با حد نگهداری ۷۰٪ و پول در معرض خطر، اندازهٔ موقعیت، و + **دو روش حساب** برای بازبینی با ماشین‌حساب. +- برگهٔ داوری با اثر انگشت `sha256` ساخته می‌شود (`data/signal-verdict.html`) و همان را می‌توانید + به شرکت بدهید. + +```bash +python signal_judge.py --kind covered --params '{"spot":7000,"strike":7400,"premium":120,"days":30}' --claimed 40 +python signal_judge.py --file my-signal.json --hurdle 0.39 --sheet +``` + +سند تحلیلی تمایز و اعتماد: `MATERIALS/money/08-differentiation-and-trust-fa.md`. + +## آزمون ۱۰ دقیقه‌ای و پروندهٔ سرمایه‌گذار (گام ۹، کارت‌های ۴ و ۵) + +دو چیز تازه که کارشان «اثبات» است، نه «وعده»: + +**آزمون ۱۰ دقیقه‌ای** (`python selftest.py` یا دکمهٔ همان کارت در گام ۹). +پانزده مورد، هر کدام **دو بار** حساب می‌شود: یک بار با موتور واقعی برنامه و یک بار با «حساب دستی» +که همان‌جا در کد نوشته شده و با ماشین‌حساب قابل چک است. اگر این دو از هم جدا شوند، مورد **سرخ** +می‌شود. فهرست کوتاهی از موردها: + +| مورد | چه چیزی را ثابت می‌کند | +|---|---| +| خرید نقدی و فروش آتی، سد و کف حاشیه | تصمیم به عدد بسته است، نه سلیقه | +| کارمزد گران | با کارمزد ۲٪ همان فرصت بسته می‌شود (حساسیت برنامه به هزینهٔ واقعی) | +| تبعی، پوشش‌داده‌شده، تساوی پوت‌کال، باکس اسپرد | فرمول‌ها درست‌اند و سود و ریسک بازار جدا شمرده می‌شوند | +| جریمهٔ نقدشوندگی و اسپرد | فرصت توخالی معرفی نمی‌شود | +| اندازهٔ موقعیت | سقف ۲۰٪ سرمایه در وجه تضمین رعایت می‌شود | +| دادهٔ اشتباه | قیمت جابه‌جا وارد شود، برنامه سود رؤیایی نمی‌سازد؛ «مشکوک» اعلام می‌کند | +| بدون آینده‌نگری | تغییر ستون «نتیجهٔ واقعی گذشته» هیچ تصمیمی را عوض نمی‌کند | +| زنجیرهٔ هش | عوض‌کردن یک ردیف دفتر، همان لحظه لو می‌رود | +| روز واقعی | پروندهٔ نمونه یا تأییدنشده، روز واقعی حساب نمی‌شود | +| شکست دادهٔ زنده | وقتی سرویس جواب نمی‌دهد، عدد ساختگی جای قیمت زنده نمی‌نشیند | +| تکرارپذیری | یک ورودی، همیشه یک جواب؛ در مسیر تصمیم هیچ مدل زبانی و تصادفی نیست | + +خروجی: `data/selftest-report.html` (کارنامه) و `data/exam-sheet.html` (برگهٔ آزمون چاپی). +برگهٔ آزمون را به سرمایه‌گذار بدهید: اول حدس خودش را می‌نویسد، بعد پاسخ و راه چک دستی را می‌بیند. + +**پروندهٔ سرمایه‌گذار** (`python dossier.py` یا دکمهٔ همان کارت). +یک صفحهٔ آمادهٔ چاپ که همهٔ شاهدهای همان اجرا را یک‌جا می‌گذارد: قواعد قفل‌شده، نتیجهٔ آزمون با اثر انگشت +موتور (sha256)، دفتر و کارنامه، پس‌آزمایی، وضعیت اتصال، «آنچه ادعا نمی‌کنیم»، چهار گام راستی‌آزمایی +مستقل، و شناسنامهٔ پرونده‌ها با اثر انگشت هر پرونده. خروجی: `data/investor-dossier.html` و نسخهٔ متنی +`data/investor-dossier.md` برای ایمیل. + +## مراسم روزانه: یک دکمه در روز، برای دو هفته + +کل آزمون دو هفته‌ای در یک کار خلاصه شده است. هر روز کاری یکی از این سه راه را بزنید: + +- در گام ۹: دکمهٔ **«اجرای مراسم امروز»**. +- روی ویندوز: دوبار کلیک روی `run-daily-trial.bat`. +- اگر می‌خواهید یادتان نرود: `schedule-daily-trial.bat` یک زمان‌بندی روزانه در ویندوز می‌سازد + (پیش‌فرض هر روز ساعت ۱۳:۱۵). برای حذف زمان‌بندی: + `schtasks /delete /tn "Station-Daily-Trial" /f` + +در هر اجرا این شش کار انجام می‌شود و هیچ سفارشی ارسال نمی‌شود: + +۱. قیمت‌ها خوانده می‌شود (زنده، وگرنه پروندهٔ دستی، وگرنه دادهٔ نمونه، با برچسب صادق روی صفحه). +۲. موتور ریاضی روی همان قیمت‌ها اجرا می‌شود. +۳. سیگنال‌های امروز با ساعت دقیق در دفتر ثبت می‌شوند (زنجیرهٔ هش). +۴. ردیف‌های قبلی با قیمت‌های تازه بازسنجی می‌شوند. +۵. سالم‌بودن زنجیره بررسی و گزارش سرمایه‌گذار از نو ساخته می‌شود. +۶. «کارنامه» به‌روز می‌شود. هر اجرا یک خط در `data/trial-daily.log` می‌ماند. + +### کارنامه: از کجا بفهمم وقت خرید دادهٔ زنده و جلسهٔ شرکت رسیده؟ + +کارنامه پنج شرط عددی دارد و تا همه جور نشود، «هنوز نه» می‌گوید و می‌گوید کدام شرط کم است: + +| شرط | حد لازم | چرا | +|---|---|---| +| تداوم روزانه | ۱۰ روز ثبت‌شده | سابقه از یک روز درنمی‌آید | +| روزهای با دادهٔ واقعی | ۵ روز غیرساختگی | خوراک آزمایشی برای تمرین است، برای ارائه نه. پرونده‌هایی هم که نامشان «نمونه» یا «demo» یا «template» دارد، روز واقعی حساب نمی‌شوند | +| سهم بازسنجی‌شدهٔ دفتر | ۶۰ درصد | نشان می‌دهد موتور با قیمت تازه هم اجرا می‌شود | +| حرکت واقعی در دفتر | ۳ حرکت معنادار، دست‌کم یکی بازتر و یکی بسته | هم فرصت تازه، هم فرصتی که بازار برداشته | +| زنجیرهٔ هش | سالم | دفتر قابل استناد باشد | + +برای شروع دوباره: `python daily_trial.py --reset --yes` (دفتر، لاگ، گزارش و CSV را پاک می‌کند). + +## قالب پروندهٔ اسنپ‌شات + +```json +{"as_of": "1405/06/31", "hurdle": 0.39, "capital": 20000000000, + "rows": [ + {"symbol": "اهرم", "kind": "basis", "spot": 20000, "future": 22800, "days": 90, + "margin_per_contract": 20000000, "unit": "قرارداد", + "liquidity_contracts_per_day": 900, "spread_pct": 0.005}, + {"symbol": "فولاد", "kind": "covered_call", "spot": 7000, "strike": 7600, "premium": 400, + "days": 45, "margin_per_contract": 7000, "unit": "سهم"} + ]} +``` + +انواع `kind`: `basis` (پایهٔ نقدی‌آتی) · `box` (باکس اسپرد) · `tabei` (تبعی) · `covered_call` (پوشش‌داده‌شده) · `parity` (تساوی پوت‌کال). + +## قالب پروندهٔ پس‌آزمایی (CSV) + +ستون‌های کلیدی: `date, symbol, kind, …` (همان فیلدهای ریاضی هر راهبرد)، `days`، `margin_per_contract`، `liquidity_contracts_per_day`، `spread_pct`، `hurdle`، و مهم‌تر از همه `realized_annualized_pct` = «نتیجهٔ واقعی آن معامله در گذشته». + +فایل نمونه: `demo/history-demo.csv` (ساختگی، ۱۰۰ سطر، برای آموزش). برای ارائه به شرکت، دادهٔ واقعی خودتان را بدهید. + +## پنل مدیریت: دسترسی، ورود و تغییر رمز + +سه بخش از برنامه با ورود باز می‌شوند و روی صفحهٔ اصلی نیستند: **بررسی سلامت**، **مجوز دسترسی و +گزارش عیب‌یابی**، و **گواهی استفادهٔ موفق**. آدرس پنل: `http://127.0.0.1:8765/admin` (یا دکمهٔ +«باز کردن پنل مدیریت» در گام ۱). + +- رمز **متن‌رو** ذخیره نمی‌شود؛ فقط نمک و هش PBKDF2-SHA256 در `config/admin.json` با اجازهٔ + خواندنِ فقط-صاحب-پرونده. +- تغییر رمز: `python3 adminauth.py --set-pass 'رمز-تازه' --set-id mafhoom` +- بی‌رمز و با متغیر محیطی (اگر نمی‌خواهید چیزی روی دیسک بماند): + `STATION_ADMIN_ID` و `STATION_ADMIN_PASS` را ست کنید؛ اولویت با همین‌هاست. +- توکن ورود یک‌ساعته است (با هر استفاده تازه می‌شود) و پنج تلاش ناموفق در پنج دقیقه، ورود را + موقتاً می‌بندد. +- پرونده‌های پنل (گزارش عیب‌یابی، گواهی استفاده، سند بفروشم یا دسترسی بدهم) بدون ورود باز نمی‌شوند؛ + آزمون تعاملی همین را می‌سنجد. + +صادقانه دربارهٔ مرزهایش: پنل برای **همین رایانه** است. اگر آن را روی شبکه باز کردید، HTTP ساده +رمز را در برابر شنود محافظت نمی‌کند؛ پشت `https` یا فقط روی `127.0.0.1` بگذارید. پنل چند کاربر و +نقش ندارد و لاگ دسترسی جدا نمی‌سازد. + +## آزمون‌ها + +```bash +bash run-tests.sh # ۶۵۸ آزمون واحد + آزمون ساخت رابط + پس‌آزمایی نمونه +python3 selftest.py # آزمون ۱۰ دقیقه‌ای (کارنامه + برگهٔ آزمون) +python3 dossier.py # پروندهٔ سرمایه‌گذار +python3 station.py --smoke # آزمون سلامت رابط دسکتاپ +python3 mock_feed.py # خوراک آزمایشی (اختیاری، برای تمرین) +python3 license.py --status # وضعیت اجازه‌نامهٔ دسترسی +python3 license.py --grant "نام شرکت" --months 12 --save # صدور اجازه‌نامهٔ نام‌دار +python3 license.py --ladder # سه پلهٔ پیشنهادی ارائه +python3 diagnose.py # گزارش عیب‌یابی یک‌کلیکی (برای پشتیبانی) +python3 signal_judge.py --kind basis --params '{"spot":20000,"future":22800,"days":50}' \ + --margin 2000000 --contracts 10 --price 20000 # داوری سیگنال ابزار دیگر +python3 investor_test.py --cases # شش پرسش آزمون کور (بدون پاسخ) +python3 investor_test.py --reveal # همان پرسش‌ها با پاسخ و مسیر محاسبه (برای آماده‌سازی شما) +python3 investor_test.py --check box_annual --guess 62 --client "نام سرمایه‌گذار" # داوری و ثبت یک حدس +python3 investor_test.py --ladder # آستانهٔ ریزش راهبردها و اندازهٔ موقعیت +python3 investor_test.py --flip # نقطهٔ برگشت کارمزد پوشش‌داده‌شده +python3 investor_test.py --reconcile --symbol فولاد --entry 7000 --exit 7400 --days 30 --units 10 +python3 investor_test.py --sheet # برگهٔ امضادار آزمون کور (زنجیره‌هش‌دار) +python3 investor_test.py --pledge # پیمان‌نامهٔ نمایش دواِمضا +python3 investor_test.py --verify # بررسی زنجیرهٔ دفتر آزمون +python3 ladder.py # سند «چه بخرم / کِی بفروشم / کِی می‌افتد» +python3 data_sources.py --all # امکان‌سنجی مسیرهای داده پیش از خرید +python3 daily_trial.py # مراسم امروز (خط فرمان) +python3 daily_trial.py --status # فقط کارنامه +python3 autoconnect.py --save # پیدا و فعال‌کردن منبع رایگان سالم +``` + +روی ویندوز، دوبار کلیک: `run-gui.bat` · `run-mock-feed.bat` · `run-investor-demo.bat` · +`run-daily-trial.bat` · `run-selftest.bat` · `build-dossier.bat` · `run-autoconnect.bat` · +`run-investor-test.bat`. + +پوشش آزمون‌ها: لایهٔ داده (سه حالت + کاوش مسیر + سیاست تلاش دوباره)، پس‌آزمایی، دفتر اتصال و کلید، +خوراک آزمایشی محلی، دفتر آزمون زنده و زنجیرهٔ هش، مراسم روزانه و کارنامه، اتصال خودکار منابع رایگان، +اسنپ‌شات تاریخ‌دار دستی، آزمون ۱۰ دقیقه‌ای، پروندهٔ سرمایه‌گذار، و ساخت رابط گرافیکی. + +آزمون تعاملی رابط مرورگری (اگر node روی رایانه داشته باشید): بررسی واقعی دکمه‌های گام‌های +۱ تا ۹، از پنل مدیریت و خوش‌آمد تا اتصال خودکار، فرم اعداد کارگزاری، مراسم روزانه، کارنامه، +آزمون ۱۰ دقیقه‌ای و ساخت پروندهٔ سرمایه‌گذار. + +```bash +cd /home/user && npm i jsdom && node test-interactive.mjs +``` + +## نکات ایمنی و قانونی + +- برنامه **هیچ سفارشی ارسال نمی‌کند**؛ معاملات الگوریتمی خودکار در بورس و فرابورس ایران «تا اطلاع ثانوی» ممنوع است. +- کلید سرویس فقط در حافظهٔ همین برنامه نگه داشته می‌شود؛ ذخیرهٔ آن روی رایانه فقط با تیک صریح خودتان + و در پروندهٔ `config/keys.local.json` انجام می‌شود. آن پرونده را در گیت یا پیام‌رسان نفرستید. +- هیچ سود تضمینی وجود ندارد؛ خروجی «پیشنهاد و هشدار» است و تصمیم با شماست. +- درگاه ریسک «باورپذیری» وجود دارد: هر بازده بزرگ‌تر از ۲۵۰ درصد (آربیتراژ) یا ۴۰۰ درصد (اهرمی) به‌معنای دادهٔ غلط یا کهنه است، نه فرصت تاریخی. + +## تهیه‌کننده و دولوپر + +**دولوپر: مهندس مسعود مجربیان** · همراه: 09126630554 · Telegram: [Mojarabian](https://t.me/Mojarabian) · Instagram: [Mojarabian.Art](https://instagram.com/Mojarabian.Art) + +✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · 📱 [+989126630554](tel:+989126630554) · ✈️ [Telegram: Mojarabian](https://t.me/Mojarabian) · 📸 [Instagram: Mojarabian.Art](https://www.instagram.com/Mojarabian.Art/) diff --git a/station/adminauth.py b/station/adminauth.py new file mode 100644 index 0000000000000000000000000000000000000000..e0ee12fa81f749b74c6079760d00c9db04a41c93 --- /dev/null +++ b/station/adminauth.py @@ -0,0 +1,217 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""پنل مدیریت — احراز هویت محلی با شناسه و رمز (نسخهٔ ۰.۱.۰). + +سه بخش برنامه (بررسی سلامت، مجوز دسترسی/عیب‌یابی، گواهی استفاده) به «پنل مدیریت» رفته‌اند و +این پوشه کلید ورود آن‌ها است: + + · رمز هرگز به‌صورت متن ذخیره نمی‌شود؛ فقط «نمک» و «هش» PBKDF2-SHA256 در `config/admin.json`. + · اگر متغیرهای محیطی `STATION_ADMIN_ID` و `STATION_ADMIN_PASS` ست شده باشند، همان‌ها + اولویت دارند (مناسب زمانی که نمی‌خواهید رمز روی دیسک بماند). + · توکن ورود کوتاه‌عمر است و پنجرهٔ خطای ورود هم محدود می‌شود (پنج تلاش در پنج دقیقه). + · پنل برای همین رایانه است؛ اگر روی شبکه بازش کردید، آن را پشت HTTPS بگذارید. + +کارهایی که این پوشه نمی‌کند (صادقانه): رمز را از رهگیری شبکه در HTTP ساده حفظ نمی‌کند؛ +مدیریت چند کاربر و نقش ندارد؛ لاگِ دسترسی جداگانه نمی‌سازد. +""" +from __future__ import annotations + +import argparse +import hashlib +import hmac +import json +import os +import secrets +import sys +import time +from pathlib import Path + +BASE = Path(__file__).resolve().parent +CONFIG = BASE / "config" / "admin.json" +VERSION = "0.1.0" + +TOKEN_TTL_SECONDS = 60 * 60 # یک ساعت بی‌کاری +FAIL_WINDOW_SECONDS = 5 * 60 +FAIL_LIMIT = 5 +PBKDF2_ROUNDS = 200_000 +MIN_PASS_LENGTH = 8 + +SESSIONS: dict[str, dict] = {} +FAILS: dict[str, list[float]] = {} + + +# ------------------------------------------------------------------ تنظیمات + +def _hash(password: str, salt_hex: str) -> str: + dk = hashlib.pbkdf2_hmac("sha256", password.encode("utf-8"), bytes.fromhex(salt_hex), + PBKDF2_ROUNDS) + return dk.hex() + + +def _same(a, b) -> bool: + """مقایسهٔ زمان‌ثابت که با متن فارسی هم کار می‌کند (compare_digest فقط ASCII می‌پذیرد).""" + return hmac.compare_digest(str(a or "").encode("utf-8"), str(b or "").encode("utf-8")) + + +def env_credentials() -> tuple[str, str] | None: + """اگر متغیرهای محیطی ست باشند، همان‌ها معتبرند و فایل خوانده نمی‌شود.""" + user = os.environ.get("STATION_ADMIN_ID", "").strip() + password = os.environ.get("STATION_ADMIN_PASS", "") + return (user, password) if user and password else None + + +def load_config(path: Path | str | None = None) -> dict | None: + p = Path(path or CONFIG) + if not p.exists(): + return None + try: + data = json.loads(p.read_text(encoding="utf-8")) + except (json.JSONDecodeError, OSError): + return None + return data if isinstance(data, dict) and data.get("id") and data.get("hash") else None + + +def set_credentials(user_id: str, password: str, *, path: Path | str | None = None) -> Path: + """شناسه و رمز را ذخیره می‌کند (فقط هش). رمز کوتاه رد می‌شود.""" + user_id = str(user_id or "").strip() + if not user_id: + raise ValueError("شناسهٔ ورود خالی است.") + if len(str(password or "")) < MIN_PASS_LENGTH: + raise ValueError(f"رمز باید دست‌کم {MIN_PASS_LENGTH} نویسه باشد.") + p = Path(path or CONFIG) + p.parent.mkdir(parents=True, exist_ok=True) + salt = secrets.token_hex(16) + p.write_text(json.dumps({"version": VERSION, "id": user_id, "salt": salt, + "rounds": PBKDF2_ROUNDS, "hash": _hash(password, salt)}, + ensure_ascii=False, indent=1), encoding="utf-8") + try: + p.chmod(0o600) # فقط صاحب پرونده بخواند + except OSError: + pass + return p + + +def is_configured(path: Path | str | None = None) -> bool: + return env_credentials() is not None or load_config(path) is not None + + +def verify_credentials(user_id: str, password: str, *, path: Path | str | None = None) -> bool: + """مقایسهٔ زمان‌ثابت؛ شناسهٔ اشتباه هم همان جواب را می‌دهد (بدون افشای کدام غلط بود).""" + env = env_credentials() + if env: + same_id = _same(user_id, env[0]) + same_pass = _same(password, env[1]) + return bool(same_id and same_pass) + cfg = load_config(path) + if not cfg: + return False + rounds = int(cfg.get("rounds") or PBKDF2_ROUNDS) + salt = str(cfg.get("salt") or "") + try: + dk = hashlib.pbkdf2_hmac("sha256", str(password or "").encode("utf-8"), + bytes.fromhex(salt), rounds) + except ValueError: + return False + same_id = _same(user_id, cfg.get("id")) + same_pass = _same(dk.hex(), cfg.get("hash")) + return bool(same_id and same_pass) + + +# ------------------------------------------------------------------ توکن و محدودیت + +def issue_token(user_id: str, *, now: float | None = None) -> str: + t = now if now is not None else time.time() + token = secrets.token_hex(24) + SESSIONS[token] = {"id": user_id, "expires": t + TOKEN_TTL_SECONDS, "made": t} + return token + + +def check_token(token: str | None, *, now: float | None = None) -> bool: + """توکن معتبر است؟ هر بررسی، عمر توکن را تازه می‌کند (بی‌کاری = انقضا).""" + if not token: + return False + rec = SESSIONS.get(str(token)) + if not rec: + return False + t = now if now is not None else time.time() + if rec["expires"] < t: + SESSIONS.pop(str(token), None) + return False + rec["expires"] = t + TOKEN_TTL_SECONDS + return True + + +def revoke_token(token: str | None) -> bool: + return bool(SESSIONS.pop(str(token), None)) + + +def active_tokens() -> int: + return len(SESSIONS) + + +def rate_limited(ip: str, *, now: float | None = None) -> bool: + """آیا این نشانی تازه بیش از حد خطا زده است؟""" + t = now if now is not None else time.time() + hits = [x for x in FAILS.get(str(ip), []) if t - x < FAIL_WINDOW_SECONDS] + FAILS[str(ip)] = hits + return len(hits) >= FAIL_LIMIT + + +def note_failure(ip: str, *, now: float | None = None) -> int: + t = now if now is not None else time.time() + hits = [x for x in FAILS.get(str(ip), []) if t - x < FAIL_WINDOW_SECONDS] + hits.append(t) + FAILS[str(ip)] = hits + return len(hits) + + +def reset_failures(ip: str) -> None: + FAILS.pop(str(ip), None) + + +def login(user_id: str, password: str, *, ip: str = "؟", path: Path | str | None = None, + now: float | None = None) -> dict: + """یک‌جا: محدودیت، بررسی، توکن. خروجی همیشه «ok» دارد تا کارساز ساده بماند.""" + if not is_configured(path): + return {"ok": False, "error": ("هنوز شناسه و رمز پنل ساخته نشده. یک‌بار این را اجرا " + "کنید: python3 adminauth.py --set-pass <رمز>")} + if rate_limited(ip, now=now): + return {"ok": False, "rate_limited": True, + "error": "تلاش‌های ناموفق زیاد بود؛ چند دقیقه صبر کنید."} + if not verify_credentials(user_id, password, path=path): + left = FAIL_LIMIT - note_failure(ip, now=now) + return {"ok": False, "error": f"شناسه یا رمز درست نیست. {max(left, 0)} تلاش تا قفل موقت."} + reset_failures(ip) + token = issue_token(str(user_id), now=now) + return {"ok": True, "token": token, "ttl_seconds": TOKEN_TTL_SECONDS, + "expires_in_minutes": TOKEN_TTL_SECONDS // 60} + + +# ------------------------------------------------------------------ خط فرمان + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description="کلید ورود پنل مدیریت (شناسه و رمز)") + ap.add_argument("--set-id", default="", help="شناسهٔ ورود") + ap.add_argument("--set-pass", default="", help="رمز ورود (فقط هش ذخیره می‌شود)") + ap.add_argument("--status", action="store_true", help="وضعیت پیکربندی") + ap.add_argument("--check", nargs=2, metavar=("ID", "PASS"), help="آزمودن یک جفت شناسه/رمز") + a = ap.parse_args(argv) + if a.set_pass: + path = set_credentials(a.set_id or "admin", a.set_pass) + print(f"ذخیره شد: {path} (فقط هش؛ رمز روی دیسک نیست)") + return 0 + if a.check: + print("درست است ✅" if verify_credentials(a.check[0], a.check[1]) else "درست نیست ✗") + return 0 if verify_credentials(*a.check) else 1 + if is_configured(): + cfg = load_config() + where = "متغیر محیطی" if env_credentials() else f"پروندهٔ {CONFIG}" + print(f"پنل مدیریت پیکربندی شده است — از {where}" + + (f" · شناسه: {cfg['id']}" if cfg else "")) + return 0 + print("پنل مدیریت هنوز پیکربندی نشده است.") + return 1 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/station/autoconnect.py b/station/autoconnect.py new file mode 100644 index 0000000000000000000000000000000000000000..50febea2c5d2defca40b90737a5ab0902569dba8 --- /dev/null +++ b/station/autoconnect.py @@ -0,0 +1,306 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""اتصال خودکار — «خودت بگرد و ببین کدام منبع رایگان امروز کار می‌کند». + +ایدهٔ ساده است و صادقانه: من (سازندهٔ برنامه) نمی‌توانم از این‌طرف مرزها تست کنم که فلان +سرویس ایرانی امروز چه پاسخی می‌دهد. پس برنامه روی رایانهٔ خودِ شما، یکی‌یکی این منابع را +امتحان می‌کند، پاسخ را می‌خواند، عدد را از نظر عقلی می‌سنجد، و به شما می‌گوید کدام کار کرد +و کدام نه — با دلیل. آخرش، اولین منبع سالم را به‌عنوان اتصال فعال ذخیره می‌کند. + +هیچ کلیدی لازم نیست و هیچ هزینه‌ای ندارد. اگر همه شکست خوردند، برنامه خودش می‌گوید +«برو سراغ پروندهٔ دستی» — که آن هم کار می‌کند. + +اجرا: python autoconnect.py (گزارش کامل، بدون ذخیره) + python autoconnect.py --save (منبع سالم را ذخیره و فعال کن) +""" +from __future__ import annotations + +import argparse +import json +import time +from pathlib import Path + +VERSION = "0.1.0" +BASE = Path(__file__).resolve().parent +import sys + +if str(BASE) not in sys.path: + sys.path.insert(0, str(BASE)) + +import datafeed # noqa: E402 +import connections as conn # noqa: E402 + +# هر داوطلب: نشانی، چند مسیر احتمالی قیمت، و توضیح فارسی برای کاربر. +# نکتهٔ مهم: این‌ها «حدس‌های آزمون‌شدنی» هستند، نه وعده. سرویس‌ها ساختار پاسخشان را عوض می‌کنند. +VERIFIED_NOTE = "آزمون از محیط سازنده (شهریور ۱۴۰۵) پاسخ سالم داد؛ روی رایانهٔ شما دوباره آزموده می‌شود." + +CANDIDATES: list[dict] = [ + { + "name": "tgju-dollar", + "label": "tgju — قیمت دلار آزاد", + "profile_label": "tgju — دلار (رایگان، خودکار پیدا شد)", + "url_template": "https://api.tgju.org/v1/market/indicator/summary-table-data/price_dollar_rl", + "paths": ["data.0.3", "data.0.p", "data.0.price", "data.price", "price"], + "plausible": (10_000, 500_000_000), + "verified": True, + "note": ("قیمت پایانی دلار آزاد در ستون چهارم سطر اول (`data.0.3`). آزمون‌شده: با یک نقطهٔ " + "پایانی مستقل (call1.tgju.org/ajax.json) هم‌خوان بود."), + }, + { + "name": "tgju-coin", + "label": "tgju — سکه امامی", + "profile_label": "tgju — سکه (رایگان، خودکار پیدا شد)", + "url_template": "https://api.tgju.org/v1/market/indicator/summary-table-data/sekeb", + "paths": ["data.0.3", "data.0.p", "data.0.price", "price"], + "plausible": (1_000_000, 20_000_000_000), + "verified": True, + "note": ("سکهٔ امامی (`sekeb`) با همان قالب tgju. نام‌های دیگر همین خانواده: geram18 (گرم " + "طلای ۱۸) · nim (نیم) · rob (ربع)."), + }, + { + "name": "tsetmc-cdn", + "label": "tsetmc — قیمت پایانی (با کد نماد)", + "profile_label": "tsetmc — قیمت پایانی (رایگان، خودکار پیدا شد)", + "url_template": "https://cdn.tsetmc.com/api/ClosingPrice/GetClosingPriceDailyList/{symbol}/0", + "paths": ["closingPriceDaily.0.pClosing", "closingPriceDaily.0.pDrCotVal", + "closingPriceDaily.0.priceYesterday"], + "plausible": (10, 100_000_000), + "needs_code": True, + "search_url": "https://cdn.tsetmc.com/api/Instrument/GetInstrumentSearch/{symbol}", + "search_paths": ["instrumentSearch.0.insCode", "instrumentSearch.0.instrumentID"], + "note": "منبع رسمی و رایگان. در نشانی به‌جای نام نماد، «کد نماد» می‌رود؛ برنامه خودش کد را پیدا می‌کند.", + }, + { + "name": "exchange-irt", + "label": "صرافی ایرانی — نرخ لحظه‌ای ریالی (تأییدشده)", + "profile_label": "صرافی ایرانی — نرخ لحظه‌ای (رایگان، تأییدشده)", + "url_template": "https://api.exir.io/v2/ticker?symbol={symbol}", + "paths": ["last", "close", "data.last"], + "plausible": (1_000, 50_000_000_000), + "verified": True, + "note": ("بازارهای ریالی این صرافی: usdt-irt · btc-irt · eth-irt · ada-irt · ton-irt و چند تای دیگر. " + "برای اینکه هر ردیف قیمت خودش را بگیرد، در فیلد «کد نماد» آن ردیف نام بازار را بنویسید " + "(مثلاً usdt-irt). کاربردش اثبات کارکرد اتصال زندهٔ واقعی بدون کلید است، نه ساختن سیگنال سهام."), + }, +] + +# نشانه‌های عدد بی‌معنی: تاریخ، شمارنده، یا درصد کوچک +TOO_BIG_FOR_PRICE = 1e15 + + +def judge(value: float | None, plausible: tuple[float, float]) -> tuple[bool, str]: + """آیا این عدد می‌تواند «قیمت» باشد؟ نه تاریخ، نه شمارنده، نه صفر.""" + if value is None: + return False, "عدد پیدا نشد" + if value <= 0: + return False, "عدد صفر یا منفی بود" + if value > TOO_BIG_FOR_PRICE: + return False, "عدد شبیه تاریخ یا شمارنده است، نه قیمت" + lo, hi = plausible + if not (lo <= value <= hi): + return False, f"عدد {value:,.0f} بیرون بازهٔ باورپذیر {lo:,.0f} تا {hi:,.0f} است" + return True, "سالم" + + +def try_candidate(cand: dict, *, symbol: str = "اهرم", timeout: float = 10.0, + allow_network: bool = True, resolve_code: bool = True) -> dict: + """یک داوطلب را امتحان می‌کند و نتیجه را با دلیل برمی‌گرداند.""" + out = {"name": cand["name"], "label": cand["label"], "ok": False, "value": None, + "json_path": "", "reason": "", "url": "", "moved": None, "resolved_code": None} + if not allow_network: + out["reason"] = "دسترسی شبکه بسته است" + return out + url_symbol = symbol + if cand.get("needs_code"): + code, why = resolve_symbol_code(cand, symbol, timeout=timeout) + if not code: + out["reason"] = f"کد نماد پیدا نشد ({why})" + return out + url_symbol = str(code) + out["resolved_code"] = str(code) + if not resolve_code: + out["reason"] = "کد نماد پیدا شد ولی استفاده نشد" + return out + from urllib.parse import quote as _q + url = str(cand["url_template"]).replace("{symbol}", _q(str(url_symbol))) + out["url"] = url + text, status = datafeed.fetch(url, timeout=timeout, retries=0, cache_name=f"probe-{cand['name']}.json", + cache_seconds=0, stale_ok=False) + if not text: + out["reason"] = f"پاسخی نیامد ({status})" + return out + try: + payload = json.loads(text) + except Exception: + out["reason"] = "پاسخ JSON نبود (شاید صفحهٔ HTML یا بسته‌شدن دسترسی)" + return out + tried = [] + for path in cand.get("paths", []): + value = datafeed.dig(payload, path) + if isinstance(value, str): + try: + value = float(value.replace(",", "")) + except ValueError: + value = None + if isinstance(value, (int, float)) and not isinstance(value, bool): + ok, why = judge(float(value), cand.get("plausible", (0, TOO_BIG_FOR_PRICE))) + tried.append(f"{path}={float(value):,.0f} → {why}") + if ok: + out.update({"ok": True, "value": float(value), "json_path": path, + "reason": "عدد سالم از مسیر " + path}) + break + else: + tried.append(f"{path}: خالی") + if not out["ok"]: + keys = ", ".join(list(payload)[:6]) if isinstance(payload, dict) else "فهرست" + out["reason"] = "مسیر عدد سالم پیدا نشد · " + " · ".join(tried[:3]) + f" · کلیدهای پاسخ: {keys}" + return out + # آزمون دوم: قیمت در دو خواندن پشت‌سرهم نباید مسخره بپرد + time.sleep(0.4) + text2, _ = datafeed.fetch(url, timeout=timeout, retries=0, cache_name=f"probe2-{cand['name']}.json", + stale_ok=False, + cache_seconds=0) + if text2: + try: + v2 = datafeed.dig(json.loads(text2), out["json_path"]) + if isinstance(v2, (int, float)) and isinstance(out["value"], (int, float)) and out["value"]: + out["moved"] = round(abs(float(v2) - out["value"]) / float(out["value"]), 6) + except Exception: + pass + return out + + +def resolve_symbol_code(cand: dict, symbol: str, *, timeout: float = 10.0) -> tuple[str | None, str]: + """کد نماد (insCode) را از جست‌وجوی tsetmc درمی‌آورد.""" + from urllib.parse import quote as _q + search = str(cand.get("search_url", "")).replace("{symbol}", _q(symbol)) + if not search: + return None, "نشانی جست‌وجو نداشت" + text, status = datafeed.fetch(search, timeout=timeout, retries=0, + cache_name=f"search-{symbol}.json", cache_seconds=0, stale_ok=False) + if not text: + return None, status + try: + payload = json.loads(text) + except Exception: + return None, "پاسخ جست‌وجو JSON نبود" + for path in cand.get("search_paths", []): + value = datafeed.dig(payload, path) + if isinstance(value, (str, int)) and str(value).strip().isdigit(): + return str(value).strip(), "ok" + return None, "کد در پاسخ نبود" + + +def enrich_snapshot_with_codes(rows: list[dict], cand: dict, *, timeout: float = 10.0, + limit: int = 8, progress=None) -> tuple[list[dict], list[str]]: + """برای منابعی که «کد نماد» می‌خواهند، کد هر نماد را پیدا و در ردیف‌ها می‌نویسد. + + این‌طور کاربر لازم نیست برای هر سهم، کد نماد را دستی از سایت بردارد. + """ + notes: list[str] = [] + if not cand.get("needs_code"): + return rows, notes + for row in rows[:limit]: + symbol = str(row.get("symbol", "")).strip() + if not symbol or str(row.get("feed_symbol", "")).strip(): + continue + code, why = resolve_symbol_code(cand, symbol, timeout=timeout) + if code: + row["feed_symbol"] = code + notes.append(f"{symbol}: کد نماد {code} پیدا و در ردیف نوشته شد.") + else: + notes.append(f"{symbol}: کد نماد پیدا نشد ({why}) — دستی از سایت بردارید و در ستون «کد نماد» بنویسید.") + if progress: + progress(notes[-1]) + return rows, notes + + +def autoconnect(*, candidates: list[dict] | None = None, symbol: str = "اهرم", + timeout: float = 10.0, allow_network: bool = True, save: bool = False, + progress=None) -> dict: + """همهٔ داوطلبان را امتحان می‌کند و در صورت خواستن، منبع سالم را ذخیره و فعال می‌کند.""" + cands = candidates if candidates is not None else CANDIDATES + # منابع تأییدشدهٔ قبلی اول امتحان می‌شوند؛ در نتیجه زودتر به جواب می‌رسیم. + cands = sorted(cands, key=lambda c: 0 if c.get("verified") else 1) + results: list[dict] = [] + winner: dict | None = None + for cand in cands: + if progress: + progress(f"امتحان: {cand['label']}") + res = try_candidate(cand, symbol=symbol, timeout=timeout, allow_network=allow_network) + results.append(res) + if res["ok"] and winner is None: + winner = res + saved: dict | None = None + if winner and save: + store = conn.load_store() + cand = next(c for c in cands if c["name"] == winner["name"]) + store["profiles"] = [p for p in store.get("profiles", []) if p.get("name") != cand["name"]] + prof = conn.upsert_profile(store, { + "name": cand["name"], "label": cand.get("profile_label", cand["label"]), + "cost": conn.FREE, "url_template": cand["url_template"], "json_path": winner["json_path"], + "key_header": "", "key_query_name": "", "env_key": "", "tested": True, + "note": f"خودکار پیدا شد ({time.strftime('%Y-%m-%d')}) · {cand.get('note', '')}", + "gives": cand.get("note", ""), + "after": "قیمت پایه از همین منبع خوانده می‌شود و ستون تازگی داده سبز می‌ماند.", + "steps": "همین حالا فعال شد؛ برای عوض‌کردن، از دفتر اتصال پروفایل دیگری انتخاب کنید.", + }) + conn.select_profile(store, prof["name"]) + conn.save_store(store) + saved = prof + working = [r for r in results if r["ok"]] + if working: + summary = (f"{len(working)} منبع رایگان سالم پیدا شد. " + f"بهترین: {working[0]['label']} با قیمت {working[0]['value']:,.0f}.") + else: + summary = ("هیچ‌کدام از منابع رایگان جواب نداد. اشکالی ندارد: پروندهٔ دستی و خوراک آزمایشی " + "هم کار می‌کنند. دلیل هر شکست را در جدول ببینید.") + return {"ok": bool(working), "results": results, "winner": winner, "saved": saved, + "summary": summary, "count_ok": len(working), "tested_at": time.strftime("%Y-%m-%d %H:%M")} + + +def format_report(rep: dict) -> str: + lines = [f"اتصال خودکار — {rep['tested_at']}", rep["summary"], ""] + for r in rep["results"]: + mark = "✓" if r["ok"] else "✗" + lines.append(f" {mark} {r['label']}: {r['reason']}") + if r["url"]: + lines.append(f" نشانی: {r['url']}") + if rep.get("saved"): + lines.append("") + lines.append(f"ذخیره شد: {rep['saved']['label']} (در دفتر اتصال، فعال)") + return "\n".join(lines) + + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description="پیدا کردن خودکار یک منبع دادهٔ رایگان سالم") + ap.add_argument("--save", action="store_true", help="منبع سالم را ذخیره و فعال کن") + ap.add_argument("--symbol", default="اهرم", help="نماد آزمایشی") + ap.add_argument("--timeout", type=float, default=10.0) + ap.add_argument("--offline", action="store_true", help="بدون شبکه (فقط برای آزمون)") + ap.add_argument("--codes", action="store_true", + help="اگر منبع برنده «کد نماد» می‌خواهد، کد نمادهای اسنپ‌شات را پیدا و ذخیره کن") + ap.add_argument("--version", action="store_true") + args = ap.parse_args(argv) + if args.version: + print(f"autoconnect {VERSION}") + return 0 + rep = autoconnect(symbol=args.symbol, timeout=args.timeout, allow_network=not args.offline, + save=args.save, progress=lambda m: print("· " + m)) + if args.codes and rep.get("winner"): + cand = next((c for c in CANDIDATES if c["name"] == rep["winner"]["name"]), {}) + snap = datafeed.load_snapshot_rows(BASE / "data" / "current-snapshot.json") + if snap.get("rows"): + rows, notes = enrich_snapshot_with_codes(snap["rows"], cand, timeout=args.timeout) + if any(r.get("feed_symbol") for r in rows): + out = datafeed.save_dated_snapshot(rows, note="کد نمادها خودکار پر شد") + print(f"کد نمادها در {out} ذخیره شد.") + for n in notes: + print("· " + n) + print() + print(format_report(rep)) + return 0 if rep["ok"] else 1 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/station/backtest.py b/station/backtest.py new file mode 100644 index 0000000000000000000000000000000000000000..550fa91e57533770066e97d3c2d66dbc963b0f27 --- /dev/null +++ b/station/backtest.py @@ -0,0 +1,403 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""پس‌آزمایی (Backtest) — همان موتوری که در تصمیم زنده به کار می‌رود، روی دادهٔ تاریخ. + +چرا مهم است: هر عددی که روی کاغذ خوب به نظر می‌رسد، باید روی دادهٔ واقعی گذشته +آزمایش شود. این برنامه همان دروازه‌های ریسک زنده را روی تاریخ اجرا می‌کند، +«برنده» و «بازنده» را جدا می‌شمارد، و خطای پیش‌بینی را عدد می‌کند. + +قاعدهٔ ضد خطای آینده‌نگری: تصمیم هر سطر فقط از فیلدهای همان سطر (و ستون نرخ سد همان تاریخ) +گرفته می‌شود. ستون `realized_annualized_pct` که «نتیجهٔ واقعی» است، فقط در سنجش +به کار می‌رود و در تصمیم هیچ نقشی ندارد؛ این نکته در آزمون‌ها هم بررسی می‌شود. +""" +from __future__ import annotations + +import csv +import html +import json +import math +import sys +from dataclasses import dataclass, field +from datetime import datetime, timezone +from pathlib import Path + +VERSION = "0.1.0" +BASE = Path(__file__).resolve().parent +DESK_DIR = (BASE.parent / "desk").resolve() + +if str(DESK_DIR) not in sys.path: + sys.path.insert(0, str(DESK_DIR)) + +try: # موتور زنده؛ همین موتور در پس‌آزمایی هم اجرا می‌شود + import desk as live_desk # type: ignore +except Exception as e: # pragma: no cover + live_desk = None # type: ignore + _IMPORT_ERROR = e + +CREDIT = ("تهیه‌کننده: Masoud Mojarabian · https://www.instagram.com/Mojarabian.Art/ · " + "tel:+989126630554 · https://t.me/Mojarabian") + +KIND_LABELS = { + "basis": "پایهٔ نقدی‌آتی", + "box": "باکس اسپرد", + "tabei": "اوراق تبعی", + "covered_call": "پوشش‌داده‌شده", + "parity": "تساوی پوت‌کال", +} + +DEFAULT_RULES = { + "min_edge_arbitrage_pct": 3.0, + "min_edge_leveraged_pct": 5.0, + "min_liquidity_contracts_per_day": 20, + "max_spread_pct": 0.03, + "position_weight": 0.25, # سهم هر معامله از سرمایه در شبیه‌سازی منحنی سرمایه + "max_plausible_arb_pct": 250.0, + "max_plausible_lev_pct": 400.0, +} + +ARBITRAGE_KINDS = {"box", "parity", "tabei"} + + +# ---------------------------------------------------------------- ورودی +def load_history(path: str | Path) -> tuple[list[dict], list[str]]: + """پروندهٔ تاریخی CSV را می‌خواند؛ سطرهای شروع‌شده با # و سطرهای خالی نادیده گرفته می‌شوند.""" + p = Path(path) + problems: list[str] = [] + if not p.exists(): + return [], [f"پروندهٔ تاریخ پیدا نشد: {p}"] + rows: list[dict] = [] + if p.suffix.lower() == ".json": + data = json.loads(p.read_text(encoding="utf-8-sig")) + raw = data if isinstance(data, list) else data.get("rows", []) + else: + raw_text = p.read_text(encoding="utf-8-sig").lstrip("\ufeff") + text = "\n".join(line for line in raw_text.splitlines() + if line.strip() and not line.lstrip().startswith("#")) + raw = list(csv.DictReader(text.splitlines())) + for i, r in enumerate(raw, 1): + if not r.get("kind") or not r.get("symbol"): + problems.append(f"سطر {i}: نماد یا نوع راهبرد خالی است") + continue + row = {} + for k, v in r.items(): + if k is None: + continue + if isinstance(v, str): + v = v.strip() + if v == "": + continue + try: + row[k] = float(v) if any(c.isdigit() for c in v) and k not in ("date", "symbol", "kind", "unit") else v + except ValueError: + row[k] = v + else: + row[k] = v + rows.append(row) + if not rows: + problems.append("هیچ سطر معتبری در پروندهٔ تاریخ نبود") + return rows, problems + + +# ---------------------------------------------------------------- تصمیم و نتیجه +@dataclass +class DecisionRow: + date: str + symbol: str + kind: str + taken: bool + reason: str + expected_annualized_pct: float | None + edge_pp: float + hurdle: float + realized_annualized_pct: float | None + days: float + period_realized_pct: float | None + + def as_dict(self) -> dict: + return { + "date": self.date, "symbol": self.symbol, "kind": self.kind, + "decision": "ورود" if self.taken else "رد", + "reason": self.reason, + "expected_annualized_pct": None if self.expected_annualized_pct is None else round(self.expected_annualized_pct, 3), + "edge_pp": round(self.edge_pp, 3), + "hurdle": self.hurdle, + "realized_annualized_pct": None if self.realized_annualized_pct is None else round(self.realized_annualized_pct, 3), + "period_realized_pct": None if self.period_realized_pct is None else round(self.period_realized_pct, 3), + } + + +def period_return(annualized_pct: float | None, days: float) -> float | None: + """بازده سالانه را به بازده همان دوره ترجمه می‌کند.""" + if annualized_pct is None or days <= 0: + return None + return ((1 + annualized_pct / 100.0) ** (days / 365.0) - 1) * 100.0 + + +def decide_row(row: dict, rules: dict) -> DecisionRow: + """دقیقاً همان دروازه‌های زنده، روی یک سطر تاریخ.""" + if live_desk is None: # pragma: no cover + raise RuntimeError(f"موتور زنده بارگذاری نشد: {_IMPORT_ERROR}") + hurdle = float(row.get("hurdle", 0.39)) + kind = str(row.get("kind")) + payload = {k: v for k, v in row.items() if not k.startswith("realized")} + payload["margin_per_contract"] = float(row.get("margin_per_contract", 0) or 0) + try: + res = live_desk.math_for_row(payload, hurdle) + except Exception as e: + return DecisionRow(date=str(row.get("date", "")), symbol=str(row.get("symbol", "")), kind=kind, + taken=False, reason=f"محاسبه نشد: {type(e).__name__}: {e}", + expected_annualized_pct=None, edge_pp=-999.0, hurdle=hurdle, + realized_annualized_pct=_num(row.get("realized_annualized_pct")), + days=float(row.get("days", 0) or 0), period_realized_pct=None) + + edge = float(res.get("score_pp", -999.0)) + reasons: list[str] = [] + if not res.get("go"): + reasons.append("موتور ریاضی تأیید نکرد") + threshold = rules["min_edge_arbitrage_pct"] if kind in ARBITRAGE_KINDS else rules["min_edge_leveraged_pct"] + if edge < threshold: + reasons.append(f"حاشیهٔ {edge:.2f} کمتر از کف {threshold:.2f}") + ceiling = (rules["max_plausible_arb_pct"] if kind in ARBITRAGE_KINDS else rules["max_plausible_lev_pct"]) + annual = res.get("annualized_pct") + if isinstance(annual, (int, float)) and abs(annual) > ceiling: + reasons.append(f"بازده محاسبه‌شده {annual:,.0f}٪ از سقف باورپذیری ({ceiling:,.0f}٪) بیشتر است؛ داده مشکوک") + liq = row.get("liquidity_contracts_per_day") + if isinstance(liq, (int, float)) and liq < rules["min_liquidity_contracts_per_day"]: + reasons.append(f"نقدشوندگی {liq:.0f} کمتر از کف {rules['min_liquidity_contracts_per_day']}") + spread = row.get("spread_pct") + if isinstance(spread, (int, float)) and spread > rules["max_spread_pct"]: + reasons.append(f"اسپرد {spread * 100:.2f}٪ بیش از سقف") + + realized = _num(row.get("realized_annualized_pct")) + days = float(row.get("days", 0) or 0) + return DecisionRow(date=str(row.get("date", "")), symbol=str(row.get("symbol", "")), kind=kind, + taken=not reasons, reason="؛ ".join(reasons) or "همهٔ دروازه‌ها باز بود", + expected_annualized_pct=res.get("annualized_pct"), edge_pp=edge, hurdle=hurdle, + realized_annualized_pct=realized, days=days, + period_realized_pct=period_return(realized, days)) + + +def _num(v): + if v is None or v == "": + return None + try: + return float(v) + except (TypeError, ValueError): + return None + + +# ---------------------------------------------------------------- اجرا و سنجه‌ها +def run_backtest(history_path: str | Path, rules: dict | None = None, + capital: float = 20_000_000_000) -> dict: + rules = {**DEFAULT_RULES, **(rules or {})} + rows, problems = load_history(history_path) + decisions = [decide_row(r, rules) for r in rows] + taken = [d for d in decisions if d.taken] + skipped = [d for d in decisions if not d.taken] + + def avg(xs: list[float]) -> float | None: + xs = [x for x in xs if x is not None] + return sum(xs) / len(xs) if xs else None + + realized_taken = [d.realized_annualized_pct for d in taken if d.realized_annualized_pct is not None] + realized_skipped = [d.realized_annualized_pct for d in skipped if d.realized_annualized_pct is not None] + hits = [d for d in taken if d.realized_annualized_pct is not None and d.realized_annualized_pct > d.hurdle * 100] + losses = [d for d in taken if d.realized_annualized_pct is not None and d.realized_annualized_pct < 0] + missed = [d for d in skipped if d.realized_annualized_pct is not None and d.realized_annualized_pct > d.hurdle * 100] + errors = [d.realized_annualized_pct - (d.expected_annualized_pct or 0) for d in taken + if d.realized_annualized_pct is not None and d.expected_annualized_pct is not None] + + # منحنی سرمایه: معامله‌ها به ترتیب تاریخ و پشت‌سرهم، با وزن ثابت — فرض ساده و صریح + ordered = sorted([d for d in taken if d.period_realized_pct is not None], + key=lambda d: str(d.date)) + equity = capital + curve = [{"trade": 0, "date": "شروع", "equity": round(equity, 0)}] + for i, d in enumerate(ordered, 1): + equity *= (1 + rules["position_weight"] * d.period_realized_pct / 100.0) + curve.append({"trade": i, "date": d.date, "equity": round(equity, 0)}) + + by_kind: dict[str, dict] = {} + for d in decisions: + slot = by_kind.setdefault(d.kind, {"total": 0, "taken": 0, "hits": 0, + "realized": [], "expected": []}) + slot["total"] += 1 + if d.taken: + slot["taken"] += 1 + if d.realized_annualized_pct is not None: + slot["realized"].append(d.realized_annualized_pct) + if d.realized_annualized_pct > d.hurdle * 100: + slot["hits"] += 1 + if d.expected_annualized_pct is not None: + slot["expected"].append(d.expected_annualized_pct) + + summary = { + "file": str(history_path), + "rows": len(decisions), + "taken": len(taken), + "skipped": len(skipped), + "hit_rate_pct": (100.0 * len(hits) / len(realized_taken)) if realized_taken else None, + "false_positive_rate_pct": (100.0 * len(losses) / len(realized_taken)) if realized_taken else None, + "missed_opportunity_rate_pct": (100.0 * len(missed) / len(realized_skipped)) if realized_skipped else None, + "avg_expected_annualized_pct": avg([d.expected_annualized_pct for d in taken]), + "avg_realized_annualized_pct": avg(realized_taken), + "avg_realized_skipped_pct": avg(realized_skipped), + "avg_forecast_error_pp": avg(errors), + "final_equity": round(equity, 0), + "start_capital": capital, + "equity_change_pct": round((equity / capital - 1) * 100, 2) if capital else None, + "best_trade": max((d.realized_annualized_pct for d in taken if d.realized_annualized_pct is not None), default=None), + "worst_trade": min((d.realized_annualized_pct for d in taken if d.realized_annualized_pct is not None), default=None), + "rules": rules, + "problems": problems, + "generated_at": datetime.now(timezone.utc).isoformat(timespec="seconds"), + } + return {"summary": summary, "decisions": decisions, "equity_curve": curve, + "by_kind": by_kind, "best": sorted([d for d in taken if d.realized_annualized_pct is not None], + key=lambda d: d.realized_annualized_pct, reverse=True)[:3], + "worst": sorted([d for d in taken if d.realized_annualized_pct is not None], + key=lambda d: d.realized_annualized_pct)[:3], + "missed": sorted(missed, key=lambda d: d.realized_annualized_pct, reverse=True)[:5]} + + +# ---------------------------------------------------------------- خروجی‌ها +def write_csv(result: dict, path: str | Path) -> Path: + p = Path(path) + p.parent.mkdir(parents=True, exist_ok=True) + with p.open("w", encoding="utf-8-sig", newline="") as f: + w = csv.DictWriter(f, fieldnames=list(result["decisions"][0].as_dict().keys()) if result["decisions"] else + ["date", "symbol", "kind", "decision", "reason"]) + w.writeheader() + for d in result["decisions"]: + w.writerow(d.as_dict()) + return p + + +def _fmt(v, digits: int = 2, suffix: str = "") -> str: + if v is None: + return "—" + if isinstance(v, (int, float)): + return f"{v:,.{digits}f}{suffix}" + return html.escape(str(v)) + + +def build_report(result: dict, path: str | Path, title: str = "گزارش پس‌آزمایی") -> Path: + p = Path(path) + p.parent.mkdir(parents=True, exist_ok=True) + s = result["summary"] + rows = "".join( + f"{html.escape(d.date)}{html.escape(d.symbol)}" + f"{html.escape(KIND_LABELS.get(d.kind, d.kind))}" + f"{'ورود' if d.taken else 'رد'}" + f"{html.escape(d.reason)}" + f"{_fmt(d.expected_annualized_pct)}" + f"{_fmt(d.edge_pp)}" + f"{_fmt(d.realized_annualized_pct)}" + f"{_fmt(d.period_realized_pct)}" + for d in result["decisions"][:400]) + + kind_rows = "".join( + f"{html.escape(KIND_LABELS.get(k, k))}{v['total']}" + f"{v['taken']}" + f"{_fmt(sum(v['expected']) / len(v['expected']) if v['expected'] else None)}" + f"{_fmt(sum(v['realized']) / len(v['realized']) if v['realized'] else None)}" + f"{(100.0 * v['hits'] / len(v['realized'])) if v['realized'] else None}" + for k, v in sorted(result["by_kind"].items(), key=lambda kv: -kv[1]["total"])) + + def small_table(items, label): + if not items: + return f"

    {label}: موردی نیست.

    " + return f"

    {label}

      " + "".join( + f"
    • {html.escape(d.date)} · {html.escape(d.symbol)} · {html.escape(KIND_LABELS.get(d.kind, d.kind))}" + f" — نتیجهٔ واقعی {_fmt(d.realized_annualized_pct, suffix='٪')} سالانه
    • " for d in items) + "
    " + + doc = f""" +{html.escape(title)} + +
    +

    {html.escape(title)}

    +
    پروندهٔ تاریخ: {html.escape(Path(s['file']).name)} · تاریخ اجرا: {html.escape(s['generated_at'])} + · قواعد: کف آربیتراژ {s['rules']['min_edge_arbitrage_pct']} · کف اهرمی {s['rules']['min_edge_leveraged_pct']} · کف نقدشوندگی {s['rules']['min_liquidity_contracts_per_day']}
    +
    +
    +
    این گزارش با «همان موتوری» ساخته شده که در تصمیم‌گیری زنده به کار می‌رود. هیچ عددی در آن وعدهٔ آینده نیست. + نتیجهٔ هر معامله از ستون «نتیجهٔ واقعی» همان سطر می‌آید و در تصمیم هیچ نقشی نداشته است.
    + +
    +
    کل سطرها
    {s['rows']}
    +
    ورود (تأییدشده)
    {s['taken']}
    +
    رد
    {s['skipped']}
    +
    نرخ برد
    {_fmt(s['hit_rate_pct'], 1, '٪')}
    +
    خطای مثبت کاذب
    {_fmt(s['false_positive_rate_pct'], 1, '٪')}
    +
    فرصت از دست رفته
    {_fmt(s['missed_opportunity_rate_pct'], 1, '٪')}
    +
    میانگین بازده انتظاری (ورودها)
    {_fmt(s['avg_expected_annualized_pct'], 1, '٪')}
    +
    میانگین بازده واقعی (ورودها)
    {_fmt(s['avg_realized_annualized_pct'], 1, '٪')}
    +
    خطای پیش‌بینی
    {_fmt(s['avg_forecast_error_pp'], 1, ' واحد')}
    +
    سرمایهٔ پایانی
    {_fmt(s['final_equity'], 0)}
    +
    تغییر سرمایه
    {_fmt(s['equity_change_pct'], 1, '٪')}
    +
    + +

    تفکیک راهبردها

    + + {kind_rows}
    راهبردسطرورودمیانگین انتظاریمیانگین واقعینرخ برد
    + +

    سه معاملهٔ سودآورتر و سه معاملهٔ زیان‌ده‌تر (از میان ورودها)

    + {small_table(result['best'], 'بهترین‌ها')} + {small_table(result['worst'], 'بدترین‌ها')} + +

    فرصت‌هایی که با دروازه رد شدند ولی نتیجهٔ واقعی خوب داشتند

    + {small_table(result['missed'], 'اگر دروازه‌ها را بازتر می‌کردیم')} + +

    سطر به سطر

    + + + {rows}
    تاریخنمادراهبردتصمیمدلیلبازده انتظاری (٪)حاشیه (واحد)نتیجهٔ واقعی (٪)بازده دورهٔ واقعی (٪)
    + +
    ساختهٔ پس‌آزمای ایستگاه نسخهٔ {VERSION} · {html.escape(CREDIT)}
    + فرض شبیه‌سازی سرمایه: هر معامله {s['rules']['position_weight'] * 100:.0f} درصد سرمایه، معامله‌ها پشت‌سرهم — ساده‌سازی عمدی و صریح.
    +
    """ + p.write_text(doc, encoding="utf-8") + return p + + +def _cli(argv: list[str]) -> int: + import argparse + ap = argparse.ArgumentParser(description="پس‌آزمایی موتور روی دادهٔ تاریخی") + ap.add_argument("history") + ap.add_argument("--out", default=str(BASE / "data" / "backtest.html")) + ap.add_argument("--csv", default=str(BASE / "data" / "backtest.csv")) + ap.add_argument("--capital", type=float, default=20_000_000_000) + args = ap.parse_args(argv) + result = run_backtest(args.history, capital=args.capital) + s = result["summary"] + print(f"سطرها: {s['rows']} · ورود: {s['taken']} · رد: {s['skipped']}") + print(f"نرخ برد: {s['hit_rate_pct']}٪ · خطای مثبت کاذب: {s['false_positive_rate_pct']}٪ · " + f"فرصت از دست رفته: {s['missed_opportunity_rate_pct']}٪") + print(f"میانگین انتظاری: {s['avg_expected_annualized_pct']} · میانگین واقعی: {s['avg_realized_annualized_pct']}") + print(f"گزارش: {build_report(result, args.out)}") + print(f"CSV: {write_csv(result, args.csv)}") + return 0 + + +if __name__ == "__main__": + raise SystemExit(_cli(sys.argv[1:])) diff --git a/station/bankroll.py b/station/bankroll.py new file mode 100644 index 0000000000000000000000000000000000000000..704b263f50416bde1650da0c43fdbdf915c10eb5 --- /dev/null +++ b/station/bankroll.py @@ -0,0 +1,372 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""ریاضیِ پول — «با ریاضی می‌شود ثروتمند شد؟» جواب صادقانه، با عدد. + +جواب کوتاه: بله، ولی نه با یک معاملهٔ خوش‌شانس. سه چیز لازم است و هر سه ریاضی است: + ۱) مزیت مثبت در هر معامله (احتمال برد × سود برد > احتمال باخت × زیان باخت + کارمزد). + ۲) بقا: اندازهٔ موقعیت طوری باشد که «نیم‌شدن حساب» احتمالش کم باشد. + ۳) زمان: رشد مرکب کند است؛ عددها را همین‌جا می‌بینی، نه با شعار. + +این پرونده سه خروجی می‌دهد: + • کسر کِلی (اندازهٔ درست هر معامله) و نسخهٔ محافظه‌کارانهٔ نصف‌کِلی. + • شبیه‌سازی ۲۰٬۰۰۰ مسیر (Monte Carlo) با کارمزد واقعی: احتمال نیم‌شدن حساب، احتمال سود، + میانهٔ دارایی در پایان، و بازهٔ ۱۰٪ تا ۹۰٪. + • مسیر رشد: با این مزیت و این اندازه، چند معامله/چند ماه تا هدف. + +هیچ‌جا «تضمین» نیست؛ اگر عددها بد باشند، همان‌طور نشان داده می‌شوند. برای اینکه شبیه‌سازی +تقلب نکند: کارمزد از هر معامله کسر می‌شود و دانهٔ تصادفی (seed) ثابت است تا نتیجه بازتولیدپذیر باشد. +""" + +from __future__ import annotations + +import argparse +import json +import math +import random +import sys +from pathlib import Path + +BASE = Path(__file__).resolve().parent +if str(BASE) not in sys.path: + sys.path.insert(0, str(BASE)) + +import investor_test as inv # noqa: E402 +import reportkit as rk # noqa: E402 + +VERSION = "0.1.0" +DATA = BASE / "data" +REPORT_HTML = DATA / "bankroll.html" +REPORT_MD = DATA / "bankroll.md" +REPORT_JSON = DATA / "bankroll.json" + +RUIN_LEVEL = 0.50 # «نیم‌شدن حساب» = ورشکستگی عملی برای سرمایهٔ کوچک +DEFAULT_TRIALS = 20_000 +DEFAULT_SEED = 7 +STOCK_ROUND_TRIP_PCT = round((0.00464 + 0.00964) * 100, 4) # خرید+فروش سهم +OPTION_ROUND_TRIP_PCT = round((0.00103 * 2) * 100, 4) # خرید+فروش اختیار + + +def kelly(win_prob: float, win_pct: float, loss_pct: float) -> dict: + """اندازهٔ درست هر معامله: f = (p·b − q) ÷ b که b = سودبرد÷زیان‌باخت. + + خروجی هم کسر کِلی است، هم نصف‌کِلی (محافظه‌کارانه) — چون فرض‌های واقعی از این ساده‌ترند. + """ + p = float(win_prob) + q = 1 - p + w = float(win_pct) / 100 + l = float(loss_pct) / 100 + if w <= 0 or l <= 0: + return {"ok": False, "detail": "سود برد و زیان باخت باید مثبت باشند."} + b = w / l + f = (p * b - q) / b + edge = p * w - q * l + return { + "ok": True, "win_prob": p, "win_pct": win_pct, "loss_pct": loss_pct, + "edge_pct_per_trade": round(edge * 100, 4), + "kelly_fraction": round(max(0.0, f), 4), + "half_kelly_fraction": round(max(0.0, f) / 2, 4), + "positive_edge": edge > 0, + "detail": ("مزیت مثبت است؛ اندازهٔ پیشنهادی = " + f"{max(0.0, f) * 100:.2f}٪ سرمایه در هر " + "معامله و نسخهٔ محافظه‌کارانه نصف آن." if edge > 0 else + "مزیت منفی یا صفر است: با این فرض‌ها معامله‌کردن، پول‌سوزی است. اول مزیت را " + "درست کن، بعد اندازه را."), + } + + +def breakeven_win_rate(win_pct: float, loss_pct: float, fee_pct: float = 0.0) -> dict: + """کم‌ترین نرخ برد برای اینکه بازی سر به سر شود (بعد از کارمزد).""" + w = float(win_pct) / 100 + l = float(loss_pct) / 100 + f = float(fee_pct) / 100 + if w + l <= 0: + return {"ok": False, "detail": "سود و زیان باید مثبت باشند."} + p = (l + f) / (w + l) + return {"ok": True, "breakeven_win_prob": round(p, 4), "breakeven_win_pct": round(p * 100, 2), + "detail": (f"با سود برد {win_pct:.1f}٪ و زیان باخت {loss_pct:.1f}٪ و کارمزد رفت‌وبرگشت " + f"{fee_pct:.3f}٪، کم‌ترین نرخ برد لازم {p * 100:.2f}٪ است. زیر آن، هر " + f"استراتژی‌ای بازنده است — ریاضی، نه نظر.")} + + +def simulate(*, capital: float = 100_000_000.0, win_prob: float = 0.55, win_pct: float = 8.0, + loss_pct: float = 5.0, risk_fraction: float = 0.10, trades: int = 48, + fee_pct: float = STOCK_ROUND_TRIP_PCT, trials: int = DEFAULT_TRIALS, + seed: int = DEFAULT_SEED, ruin_level: float = RUIN_LEVEL, + notional_ratio: float = 1.0) -> dict: + """Monte Carlo: هزاران مسیر ممکن با همان مزیت و همان کارمزد. + + فرض صریح کارمزد: کارمزد رفت‌وبرگشت روی **ارزش معامله** بسته می‌شود + (`notional_ratio` برابر ارزش معامله ÷ سرمایهٔ حساب). با `notional_ratio=1` یعنی هر معامله + به اندازهٔ کل حساب است — همان فرضی که برای معامله‌گر خرد واقع‌بینانه است و عدد را بدبینانه، + نه خوش‌بینانه، نشان می‌دهد. + """ + rng = random.Random(seed) + finals: list[float] = [] + ruin = 0 + reached_double = 0 + best, worst = 0.0, float("inf") + for _ in range(trials): + eq = capital + ruined = False + for _t in range(trades): + fee_cost = notional_ratio * fee_pct / 100 + if rng.random() < win_prob: + eq *= (1 + risk_fraction * win_pct / 100 - fee_cost) + else: + eq *= (1 - risk_fraction * loss_pct / 100 - fee_cost) + if eq <= capital * ruin_level: + ruined = True + break + if ruined: + ruin += 1 + if eq >= capital * 2: + reached_double += 1 + finals.append(eq) + best = max(best, eq) + worst = min(worst, eq) + finals.sort() + + def pct_at(p: float) -> float: + idx = min(len(finals) - 1, max(0, int(p * len(finals)))) + return finals[idx] + + median = pct_at(0.50) + return { + "ok": True, "capital": capital, "trials": trials, "trades": trades, "seed": seed, + "risk_fraction": risk_fraction, "fee_pct": fee_pct, "notional_ratio": notional_ratio, + "ruin_prob": round(ruin / trials, 4), "double_prob": round(reached_double / trials, 4), + "profit_prob": round(sum(1 for f in finals if f > capital) / trials, 4), + "median_final": round(median, 2), + "median_multiple": round(median / capital, 3), + "p10_final": round(pct_at(0.10), 2), "p90_final": round(pct_at(0.90), 2), + "best_final": round(best, 2), "worst_final": round(worst, 2), + "ruin_level": ruin_level, + "detail": (f"در {trials:,} مسیر فرضی با نرخ برد {win_prob * 100:.0f}٪ و اندازهٔ " + f"{risk_fraction * 100:.0f}٪ در هر معامله و کارمزد {fee_pct:.3f}٪ روی ارزش " + f"معامله: احتمال نیم‌شدن حساب {ruin / trials * 100:.2f}٪ · احتمال دوبرابر‌شدن " + f"{reached_double / trials * 100:.2f}٪ · میانهٔ پایان {median / capital:.2f} " + f"برابر شروع."), + } + + +def path(*, capital: float, monthly_return_pct: float, target: float, + fee_drag_pct_month: float = 0.0) -> dict: + """چند ماه تا هدف، با رشد مرکب و کسر کارمزد ماهانه (بدون شعار، فقط لگاریتم).""" + net = monthly_return_pct - fee_drag_pct_month + if target <= capital: + return {"ok": False, "detail": "هدف باید بزرگ‌تر از سرمایهٔ فعلی باشد."} + if net <= 0: + return {"ok": True, "months": None, "years": None, "net_monthly_pct": round(net, 4), + "detail": ("با این بازده و این کارمزد، رشد صفر یا منفی است؛ هدف با هیچ زمانی " + "به‌دست نمی‌آید. اول مزیت را مثبت کن، بعد به زمان فکر کن.")} + months = math.log(target / capital) / math.log(1 + net / 100) + return {"ok": True, "months": round(months, 1), "years": round(months / 12, 1), + "net_monthly_pct": round(net, 4), + "needed_multiple": round(target / capital, 3), + "detail": (f"با {net:.2f}٪ رشد خالص ماهانه، از {capital:,.0f} به {target:,.0f} " + f"می‌رسد در حدود {months:.1f} ماه ({months / 12:.1f} سال) — به‌شرط اینکه " + f"رشد مثبت بماند و هیچ ماه بحرانی حساب را نصف نکند.")} + + +def strategy_path(*, capital: float, annualized_pct: float, target: float, + churn_per_year: float = 1.0, + fee_pct_round_trip: float = STOCK_ROUND_TRIP_PCT) -> dict: + """مسیر رشد با «عدد راهبرد» و «تعداد چرخش در سال». + + برخلاف کِلی که فرض‌های احتمالاتی دارد، این‌جا عدد راهبرد (همان که پلهٔ تصمیم می‌دهد) می‌آید، + چرخش سالانه و کارمزد کسر می‌شود، و بعد زمان رسیدن به هدف حساب می‌شود. + """ + fee_drag_pp = churn_per_year * fee_pct_round_trip + net_annual = float(annualized_pct) - fee_drag_pp + if net_annual <= 0: + return {"ok": True, "net_annual_pct": round(net_annual, 3), "months": None, "years": None, + "churn_per_year": churn_per_year, "fee_drag_pp": round(fee_drag_pp, 3), + "detail": (f"با {churn_per_year:g} چرخش در سال، کارمزد {fee_drag_pp:.2f} واحد درصد " + f"از بازده کم می‌کند و بازده خالص {net_annual:.2f}٪ می‌شود؛ یعنی منفی. " + f"یا مزیت باید بزرگ‌تر شود یا چرخش کمتر.")} + monthly = (1 + net_annual / 100) ** (1 / 12) - 1 + months = math.log(target / capital) / math.log(1 + monthly) if target > capital else 0.0 + return {"ok": True, "net_annual_pct": round(net_annual, 3), "monthly_pct": round(monthly * 100, 4), + "months": round(months, 1), "years": round(months / 12, 1), + "churn_per_year": churn_per_year, "fee_drag_pp": round(fee_drag_pp, 3), + "detail": (f"راهبرد سالانه {annualized_pct:.2f}٪ می‌دهد؛ با {churn_per_year:g} چرخش در " + f"سال و کارمزد {fee_pct_round_trip:.3f}٪، خالص {net_annual:.2f}٪ می‌شود. " + f"با همین رشد مرکب، {target / capital:.1f} برابر شدن حدود {months:.1f} ماه " + f"({months / 12:.1f} سال) طول می‌کشد.")} + + +def honesty_checks(capital: float = 100_000_000.0) -> list[dict]: + """سه آزمون صادقانه: کارمزد، نرخ برد، و اندازهٔ موقعیت — که هرکدام می‌تواند بازی را ببندد.""" + be = breakeven_win_rate(win_pct=8.0, loss_pct=5.0, fee_pct=STOCK_ROUND_TRIP_PCT) + small = simulate(capital=capital, risk_fraction=0.05, trials=6000) + big = simulate(capital=capital, risk_fraction=0.40, trials=6000) + return [ + {"title": "کارمزد رفت‌وبرگشت سهم چقدر است؟", + "value": f"{STOCK_ROUND_TRIP_PCT}٪ (سهم) · {OPTION_ROUND_TRIP_PCT}٪ (اختیار)", + "why": "روزی دو رفت‌وبرگشت با سرمایهٔ کوچک، سالانه بیش از ۳۰٪ سرمایه را کارمزد می‌دهد؛ " + "همین یک عدد، بیشتر معامله‌گران روزانه را بازنده می‌کند.", + "verdict": "پس: چرخش کم، نگه‌داشتن تا سررسید، و پرهیز از معاملهٔ بی‌مزیت."}, + {"title": "کم‌ترین نرخ برد لازم", "value": f"{be['breakeven_win_pct']}٪", + "why": be["detail"], + "verdict": "نرخ برد خودت را از دفتر حساب کن (نه از حافظه) و با این عدد بسنج."}, + {"title": "اندازهٔ موقعیت: ۵٪ در برابر ۴۰٪", + "value": f"نیم‌شدن حساب: {small['ruin_prob'] * 100:.2f}٪ در برابر {big['ruin_prob'] * 100:.2f}٪", + "why": ("با اندازهٔ کوچک‌تر، احتمال دوبرابر‌شدن کمتر ولی احتمال ورشکستگی بسیار کمتر است؛ " + "با اندازهٔ درشت، همان مزیت به ورشکستگی می‌رسد."), + "verdict": "برای سرمایهٔ کوچک، بقا مهم‌تر از سرعت است: اندازهٔ کوچک، عمر طولانی."}, + ] + + +def build(*, capital: float = 100_000_000.0, target: float | None = None, + win_prob: float = 0.55, win_pct: float = 8.0, loss_pct: float = 5.0, + trades: int = 48, trials: int = DEFAULT_TRIALS, strategy_annualized_pct: float = 68.482, + churn_per_year: float = 1.0, write: bool = True, html: Path | str | None = None, + md: Path | str | None = None, jsonf: Path | str | None = None) -> dict: + tgt = float(target or capital * 4) + k = kelly(win_prob, win_pct, loss_pct) + frac = k["half_kelly_fraction"] if k.get("ok") and k["half_kelly_fraction"] else 0.10 + sim = simulate(capital=capital, win_prob=win_prob, win_pct=win_pct, loss_pct=loss_pct, + risk_fraction=frac, trades=trades, trials=trials) + spath = strategy_path(capital=capital, annualized_pct=strategy_annualized_pct, target=tgt, + churn_per_year=churn_per_year) + trades_per_month = 2 + per_month_pct = (k["edge_pct_per_trade"] * frac * trades_per_month) if k.get("ok") else 0.0 + fee_drag = STOCK_ROUND_TRIP_PCT * frac * trades_per_month + plan = path(capital=capital, monthly_return_pct=per_month_pct, target=tgt, + fee_drag_pct_month=fee_drag) + doc = { + "version": VERSION, "capital": capital, "target": tgt, + "kelly": k, "used_risk_fraction": frac, "sim": sim, "path": plan, "strategy_path": spath, + "strategy_annualized_pct": strategy_annualized_pct, "churn_per_year": churn_per_year, + "breakeven": breakeven_win_rate(win_pct=win_pct, loss_pct=loss_pct, + fee_pct=STOCK_ROUND_TRIP_PCT), + "checks": honesty_checks(capital), "trades_per_month": trades_per_month, + "engine_fees_pct": {"stock_round_trip": STOCK_ROUND_TRIP_PCT, + "option_round_trip": OPTION_ROUND_TRIP_PCT}, + "honesty": ("هیچ‌کدام از این عددها وعدهٔ سود نیست. شبیه‌سازی با فرض‌های خودتان اجرا " + "می‌شود؛ اگر نرخ برد واقعی شما کمتر از عدد سر‌به‌سر باشد، همین جدول " + "«زیان» نشان می‌دهد. دانهٔ تصادفی ثابت است تا نتیجه بازتولیدپذیر باشد."), + } + doc["md_text"] = to_md(doc) + if write: + body = ['
    این پرونده وعدهٔ سود نیست؛ ریاضیِ بقا و رشد است. ' + 'می‌گوید با این مزیت و این کارمزد، هزاران مسیر ممکن چه شکلی دارند و کدام‌شان ' + 'حساب را نصف می‌کنند. عددها با فرض‌های خودتان بازتولیدپذیرند.
    ', + f'

    {rk.esc(doc["honesty"])}

    ', + "

    ۱. اندازهٔ درست هر معامله (کِلی)

    ", + f'

    مزیت هر معامله: {k.get("edge_pct_per_trade")}٪ · ' + f'کسر کِلی: {k.get("kelly_fraction")} · ' + f'نصف‌کِلی (محافظه‌کارانه، همان چیزی که این‌جا استفاده شد): ' + f'{doc["used_risk_fraction"]}

    ', + f'

    {rk.esc(k.get("detail", ""))}

    ', + "

    ۲. کم‌ترین نرخ برد لازم

    ", + f'

    {rk.esc(doc["breakeven"]["detail"])}

    ', + "

    ۳. شبیه‌سازی مسیرها

    ", + '', + f'', + f'', + f'', + f'', + f'', + '
    احتمال نیم‌شدن حساب{sim["ruin_prob"] * 100:.2f}٪
    احتمال دوبرابر‌شدن{sim["double_prob"] * 100:.2f}٪
    احتمال سود{sim["profit_prob"] * 100:.2f}٪
    میانهٔ پایان{rk.num(sim["median_final"])} ' + f'({sim["median_multiple"]}× شروع)
    بازهٔ ۱۰٪ تا ۹۰٪{rk.num(sim["p10_final"])} تا ' + f'{rk.num(sim["p90_final"])}
    ', + f'

    {rk.esc(sim["detail"])}

    ', + "

    ۴. چند وقت تا هدف

    ", + f'

    مسیر کِلی (مدل فرضی، کارمزد روی مبلغ ریسک): {rk.esc(plan.get("detail", ""))}

    ', + f'

    مسیر راهبرد (با عدد واقعی برنامه): {rk.esc(spath.get("detail", ""))}

    ', + f'

    عدد راهبرد = {strategy_annualized_pct:.3f}٪ سالانه (میان بر: همبسته ' + f'با «مبنا»ی اسنپ‌شات) · چرخش سالانه {churn_per_year:g} بار · کارمزد رفت‌وبرگشت ' + f'{STOCK_ROUND_TRIP_PCT}٪ (سهم). اگر راهبرد را تا سررسید نگه دارید و سالی یک بار ' + f'بچرخانید، کارمزد کوچک و بازده تقریباً دست‌نخورده می‌ماند؛ اگر ماهی چند بار ' + f'بچرخانید، کارمزد مزیت را می‌خورد.

    ', + "

    ۵. سه آزمون صادقانه

    "] + for c in doc["checks"]: + body.append(f'

    {rk.esc(c["title"])} — {rk.esc(str(c["value"]))}
    ' + f'{rk.esc(c["why"])}
    ' + f'{rk.esc(c["verdict"])}

    ') + body.append('

    ✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · 📱 +989126630554 · ' + '✈️ Telegram: Mojarabian · ' + '📸 Instagram: Mojarabian.Art

    ') + hp = Path(html or REPORT_HTML) + hp.parent.mkdir(parents=True, exist_ok=True) + hp.write_text(rk.page("ریاضیِ پول — بقا، اندازهٔ موقعیت و مسیر رشد", "".join(body), + subtitle=f"سرمایه {rk.num(capital)} · هدف {rk.num(tgt)} · " + f"{sim['trials']:,} مسیر"), + encoding="utf-8") + Path(md or REPORT_MD).write_text(doc["md_text"], encoding="utf-8") + Path(jsonf or REPORT_JSON).write_text(json.dumps(doc, ensure_ascii=False, indent=1), + encoding="utf-8") + doc.update({"html": str(hp), "md": str(md or REPORT_MD), "json": str(jsonf or REPORT_JSON)}) + return doc + + +def to_md(doc: dict) -> str: + k, sim, plan = doc["kelly"], doc["sim"], doc["path"] + L = [f"# ریاضیِ پول — نسخهٔ {VERSION}", "", + f"سرمایه: {doc['capital']:,.0f} · هدف: {doc['target']:,.0f} · " + f"معامله در ماه (فرض): {doc['trades_per_month']}", "", + f"> {doc['honesty']}", "", + "## ۱. اندازهٔ درست هر معامله", "", + f"- مزیت هر معامله: {k.get('edge_pct_per_trade')}٪", + f"- کسر کِلی: {k.get('kelly_fraction')} · نصف‌کِلی: {k.get('half_kelly_fraction')}", + f"- اندازهٔ استفاده‌شده در شبیه‌سازی: {doc['used_risk_fraction']}", + f"- {k.get('detail', '')}", "", + "## ۲. کم‌ترین نرخ برد لازم", "", + f"- {doc['breakeven']['detail']}", "", + "## ۳. شبیه‌سازی مسیرها", "", + f"- احتمال نیم‌شدن حساب: {sim['ruin_prob'] * 100:.2f}٪", + f"- احتمال دوبرابر‌شدن: {sim['double_prob'] * 100:.2f}٪", + f"- احتمال سود: {sim['profit_prob'] * 100:.2f}٪", + f"- میانهٔ پایان: {sim['median_final']:,.0f} ({sim['median_multiple']}× شروع)", + f"- بازهٔ ۱۰٪ تا ۹۰٪: {sim['p10_final']:,.0f} تا {sim['p90_final']:,.0f}", + f"- بدترین مسیر: {sim['worst_final']:,.0f} · بهترین مسیر: {sim['best_final']:,.0f}", "", + "## ۴. چند وقت تا هدف", "", + f"- مسیر کِلی (مدل فرضی، کارمزد روی مبلغ ریسک): {plan.get('detail', '')}", + f"- مسیر راهبرد (عدد واقعی برنامه {doc['strategy_annualized_pct']:.3f}٪ سالانه، " + f"{doc['churn_per_year']:g} چرخش در سال): {doc['strategy_path'].get('detail', '')}", "", + "## ۵. سه آزمون صادقانه", ""] + for c in doc["checks"]: + L += [f"### {c['title']}", f"- عدد: {c['value']}", f"- چرا: {c['why']}", + f"- نتیجه: {c['verdict']}", ""] + return "\n".join(L) + + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description="ریاضیِ پول: کِلی، ورشکستگی، مسیر رشد") + ap.add_argument("--capital", type=float, default=100_000_000.0, help="سرمایه (ریال)") + ap.add_argument("--target", type=float, default=None) + ap.add_argument("--win-prob", type=float, default=0.55) + ap.add_argument("--win", type=float, default=8.0, help="درصد سود برد") + ap.add_argument("--loss", type=float, default=5.0, help="درصد زیان باخت") + ap.add_argument("--trades", type=int, default=48) + ap.add_argument("--trials", type=int, default=DEFAULT_TRIALS) + ap.add_argument("--strategy", type=float, default=68.482, help="بازده سالانهٔ راهبرد (٪)") + ap.add_argument("--churn", type=float, default=1.0, help="چند بار در سال می‌چرخانید") + ap.add_argument("--json", action="store_true") + ap.add_argument("--no-write", action="store_true") + a = ap.parse_args(argv) + doc = build(capital=a.capital, target=a.target, win_prob=a.win_prob, win_pct=a.win, + loss_pct=a.loss, trades=a.trades, trials=a.trials, + strategy_annualized_pct=a.strategy, churn_per_year=a.churn, + write=not a.no_write) + if a.json: + print(json.dumps(doc, ensure_ascii=False, indent=1)) + return 0 + k, sim, plan = doc["kelly"], doc["sim"], doc["path"] + print(f"ریاضیِ پول — سرمایه {a.capital:,.0f} · هدف {doc['target']:,.0f}") + print(f" مزیت هر معامله: {k.get('edge_pct_per_trade')}٪ · کسر کِلی {k.get('kelly_fraction')} · " + f"نصف‌کِلی {k.get('half_kelly_fraction')}") + print(f" کم‌ترین نرخ برد لازم: {doc['breakeven']['breakeven_win_pct']}٪") + print(f" شبیه‌سازی {sim['trials']:,} مسیر: نیم‌شدن {sim['ruin_prob'] * 100:.2f}٪ · " + f"دوبرابر‌شدن {sim['double_prob'] * 100:.2f}٪ · میانه {sim['median_multiple']}× ") + print(f" مسیر کِلی: {plan.get('detail')}") + print(f" مسیر راهبرد: {doc['strategy_path'].get('detail')}") + for c in doc["checks"]: + print(f" · {c['title']}: {c['value']} → {c['verdict']}") + if doc.get("html"): + print(" برگه:", doc["html"]) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/station/build-dossier.bat b/station/build-dossier.bat new file mode 100644 index 0000000000000000000000000000000000000000..d17c54b06909be2d377e31b51811692a43e87577 --- /dev/null +++ b/station/build-dossier.bat @@ -0,0 +1,11 @@ +@echo off +chcp 65001 >nul +cd /d "%~dp0" +echo ============================================================ +echo پروندهٔ سرمایه‌گذار — یک فایل برای جلسه با شرکت +echo قواعد، شاهدها، دفتر، کارنامه، پس‌آزمایی، محدودیت‌ها +echo ============================================================ +python dossier.py +echo. +echo پرونده در پوشهٔ data ساخته شد: investor-dossier.html +pause diff --git a/station/config/connections.json b/station/config/connections.json new file mode 100644 index 0000000000000000000000000000000000000000..12320da32682cf343292d99ab00a774a9ef9ecef --- /dev/null +++ b/station/config/connections.json @@ -0,0 +1,120 @@ +{ + "version": 1, + "selected": "mock-local", + "updated_at": "2026-09-22T21:07:49+00:00", + "profiles": [ + { + "name": "mock-local", + "label": "خوراک آزمایشی محلی (بدون اینترنت، بدون هزینه)", + "cost": "رایگان", + "url_template": "http://127.0.0.1:8788/quote?symbol={symbol}", + "json_path": "data.0.pl", + "key_header": "", + "key_query_name": "", + "env_key": "", + "note": "برای آزمایش کامل برنامه و نشان‌دادن کارکردِ اتصال زنده به سرمایه‌گذار. دادهٔ این خوراک ساختگی است و روی آن هیچ ادعای درآمدی نمی‌شود.", + "gives": "قیمت یک لنگه (قیمت پایه) برای همهٔ نمادها، با نوسان ساختگی و یک رخداد برنامه‌ریزی‌شده برای دیدن سیگنال", + "after": "ستون تازگی داده سبز می‌شود و قیمت‌ها هر چند ثانیه عوض می‌شوند؛ یعنی کل مسیر فنی «زنده» کار می‌کند.", + "steps": "۱) در پوشهٔ ایستگاه دستور `python mock_feed.py` را اجرا کنید (یا خوراک همراه کارساز خودکار بالا می‌آید). ۲) همین پروفایل را انتخاب و آزمایش کنید.", + "tested": true, + "custom": false + }, + { + "name": "tgju-usd", + "label": "tgju — دلار، طلا، سکه (رایگان، آزمون‌شده)", + "cost": "رایگان", + "url_template": "https://api.tgju.org/v1/market/indicator/summary-table-data/{symbol}", + "json_path": "data.0.3", + "key_header": "", + "key_query_name": "", + "env_key": "", + "note": "آزمون‌شده در ۲۲ سپتامبر ۲۰۲۶: پاسخ ۲۰۰ در ۰٫۳ تا ۱٫۸ ثانیه. ستون چهارم سطر اول = قیمت پایانی. پنج شاخص (دلار، گرم طلای ۱۸، سکهٔ امامی، نیم، ربع) با یک نقطهٔ پایانی مستقل (call1.tgju.org/ajax.json) مقایسه شد و هر پنج عدد یکی درآمد؛ پس مسیر «data.0.3» درست است. اگر روزی ساختار عوض شد، با «کاوش پاسخ سرویس» مسیر تازه را پیدا کنید.", + "gives": "قیمت زندهٔ دلار، طلا و سکه. نماد ردیف را نام شاخص tgju بگذارید: price_dollar_rl (دلار) · geram18 (گرم طلای ۱۸) · sekeb (سکهٔ امامی) · sekee (سکهٔ بهار) · nim (نیم) · rob (ربع).", + "after": "تازگی داده سبز می‌شود و برای ردیف‌های دلار/طلا/سکه قیمت واقعی می‌آید. این خوراک برای سهام، آتی و اختیار چیزی نمی‌دهد؛ برای آزمون «قیمت زنده» و برای نرخ طلا/ارز پایهٔ محاسبهٔ آتی طلا کافی است.", + "steps": "۱) ردیف اسنپ‌شات بسازید و در ستون نماد همان نام انگلیسی شاخص را بگذارید (مثل price_dollar_rl). ۲) همین پروفایل را انتخاب و «آزمایش اتصال» را بزنید.", + "tested": true, + "custom": false + }, + { + "name": "tsetmc-cdn", + "label": "tsetmc — قیمت پایانی سهام و آپشن (رایگان، آزمون‌نشده)", + "cost": "رایگان", + "url_template": "https://cdn.tsetmc.com/api/ClosingPrice/GetClosingPriceDailyList/{symbol}/0", + "json_path": "closingPriceDaily.0.pClosing", + "key_header": "", + "key_query_name": "", + "env_key": "", + "note": "منبع رسمی و رایگان است ولی بی‌تعهد. در نشانی، {symbol} باید «کد نماد» (insCode) باشد نه نام نماد؛ کد را در فیلد feed_symbol هر ردیف اسنپ‌شات بگذارید.", + "gives": "قیمت پایانی روز برای سهم و آپشن، بر پایهٔ کد نماد", + "after": "قیمت پایه از منبع رسمی می‌آید؛ ولی نرخ به‌روزرسانی روزانه است، نه لحظه‌ای.", + "steps": "۱) کد نماد هر سهم را از سایت tsetmc بردارید. ۲) در اسنپ‌شات، فیلد feed_symbol هر ردیف را با آن کد پر کنید. ۳) آزمون اتصال.", + "tested": false, + "custom": false + }, + { + "name": "broker-service", + "label": "سرویس دادهٔ خریدنی (کلیددار) — قالب نمونه", + "cost": "خریدنی", + "url_template": "https://api.example.ir/Quote.php?key={key}&l18={symbol}", + "json_path": "data.0.pl", + "key_header": "", + "key_query_name": "key", + "env_key": "MARKET_API_KEY", + "note": "این قالب نمونهٔ عمومی است؛ قالب واقعی را از مستندات فروشنده کپی کنید. معمولاً ۴ چیز می‌دهند: قیمت پایه، ریزمعاملات، زنجیرهٔ آپشن، دادهٔ تاریخی.", + "gives": "قیمت زندهٔ همهٔ نمادها + دادهٔ تاریخی برای پس‌آزمایی", + "after": "قیمت پایه هر ۳۰ ثانیه خودکار تازه می‌شود، تازگی داده سبز می‌ماند، و پس‌آزمایی روی دادهٔ واقعی ممکن می‌شود. وجه تضمین همچنان دستی از کارگزاری می‌آید.", + "steps": "۱) کلید را از فروشنده بگیرید. ۲) قالب نشانی و مسیر JSON را از مستنداتش کپی کنید. ۳) کلید را همین‌جا بگذارید. ۴) آزمون اتصال. ۵) اگر درست بود، «ذخیره» بزنید تا هر بار خودکار وصل شود.", + "tested": false, + "custom": false + }, + { + "name": "custom", + "label": "اتصال دلخواه (خودم پرش می‌کنم)", + "cost": "رایگان", + "url_template": "", + "json_path": "", + "key_header": "", + "key_query_name": "key", + "env_key": "", + "note": "هر سرویسی که خواستید. دو چیز لازم است: نشانی‌ای که {symbol} در آن باشد، و مسیر رسیدن به عدد قیمت در پاسخ JSON.", + "gives": "هر چیزی که سرویس بدهد", + "after": "همان لحظه‌ای که نشانی درست شود، قیمت زنده در همهٔ گام‌ها جاری می‌شود.", + "steps": "۱) «کاوش پاسخ سرویس» را بزنید و نشانی را آزمایش کنید. ۲) از فهرست، مسیر عدد قیمت را انتخاب کنید. ۳) ذخیره.", + "tested": false, + "custom": false + }, + { + "name": "exchange-irt", + "label": "صرافی ایرانی — نرخ لحظه‌ای (رایگان، تأییدشده)", + "cost": "رایگان", + "url_template": "https://api.exir.io/v2/ticker?symbol={symbol}", + "json_path": "last", + "key_header": "", + "key_query_name": "", + "env_key": "", + "note": "خودکار پیدا شد (2026-09-22) · بازارهای ریالی این صرافی: usdt-irt · btc-irt · eth-irt · ada-irt · ton-irt و چند تای دیگر. برای اینکه هر ردیف قیمت خودش را بگیرد، در فیلد «کد نماد» آن ردیف نام بازار را بنویسید (مثلاً usdt-irt). کاربردش اثبات کارکرد اتصال زندهٔ واقعی بدون کلید است، نه ساختن سیگنال سهام.", + "gives": "بازارهای ریالی این صرافی: usdt-irt · btc-irt · eth-irt · ada-irt · ton-irt و چند تای دیگر. برای اینکه هر ردیف قیمت خودش را بگیرد، در فیلد «کد نماد» آن ردیف نام بازار را بنویسید (مثلاً usdt-irt). کاربردش اثبات کارکرد اتصال زندهٔ واقعی بدون کلید است، نه ساختن سیگنال سهام.", + "after": "قیمت پایه از همین منبع خوانده می‌شود و ستون تازگی داده سبز می‌ماند.", + "steps": "همین حالا فعال شد؛ برای عوض‌کردن، از دفتر اتصال پروفایل دیگری انتخاب کنید.", + "tested": true, + "custom": true + }, + { + "name": "tgju-dollar", + "label": "tgju — دلار (رایگان، خودکار پیدا شد)", + "cost": "رایگان", + "url_template": "https://api.tgju.org/v1/market/indicator/summary-table-data/price_dollar_rl", + "json_path": "data.0.3", + "key_header": "", + "key_query_name": "", + "env_key": "", + "note": "خودکار پیدا شد (2026-09-22) · قیمت پایانی دلار آزاد در ستون چهارم سطر اول (`data.0.3`). آزمون‌شده: با یک نقطهٔ پایانی مستقل (call1.tgju.org/ajax.json) هم‌خوان بود.", + "gives": "قیمت پایانی دلار آزاد در ستون چهارم سطر اول (`data.0.3`). آزمون‌شده: با یک نقطهٔ پایانی مستقل (call1.tgju.org/ajax.json) هم‌خوان بود.", + "after": "قیمت پایه از همین منبع خوانده می‌شود و ستون تازگی داده سبز می‌ماند.", + "steps": "همین حالا فعال شد؛ برای عوض‌کردن، از دفتر اتصال پروفایل دیگری انتخاب کنید.", + "tested": true, + "custom": true + } + ], + "preset_version": 3 +} \ No newline at end of file diff --git a/station/connections.py b/station/connections.py new file mode 100644 index 0000000000000000000000000000000000000000..6e34bedfe5feb410c9d5581f084304922779f738 --- /dev/null +++ b/station/connections.py @@ -0,0 +1,367 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""دفترِ اتصال‌ها — «هر وقت سرویس را گرفتم، همین‌جا وصلش کنم و استفاده کنم». + +چه چیزی ذخیره می‌شود: + • `config/connections.json` : مشخصات اتصال (قالب نشانی، مسیر JSON، نام هدر کلید، …) — بدون کلید. + • `config/keys.local.json` : کلیدها، فقط اگر خودتان صریحاً «ذخیرهٔ کلید» را بزنید. + +چرا کلید جدا و اختیاری؟ چون کلید پول است. پیش‌فرض این است که کلید در هیچ پرونده‌ای نوشته نشود +و فقط تا بسته‌شدن برنامه در حافظه بماند. اگر ذخیره کنید، پرونده فقط روی همین رایانه است، +ولی هر کسی که به این پوشه دسترسی داشته باشد می‌تواند آن را ببیند — پس به‌جز رایانهٔ خودتان، +آن را جای دیگری نگه ندارید و در گیت/تلگرام نفرستید. +""" +from __future__ import annotations + +import json +import os +from datetime import datetime, timezone +from pathlib import Path + +VERSION = "0.1.0" +BASE = Path(__file__).resolve().parent +CONFIG_DIR = BASE / "config" +PROFILES_FILE = CONFIG_DIR / "connections.json" +KEYS_FILE = CONFIG_DIR / "keys.local.json" + +FREE = "رایگان" +PAID = "خریدنی" +# با هر تغییر در پروفایل‌های آماده، این شماره را بالا ببرید تا روی نسخه‌های قبلی هم به‌روز شود. +PRESET_VERSION = 3 + +# نگه‌داشته‌شده‌ها «نقطهٔ شروع» هستند، نه وعده: هر کدام را با دکمهٔ «آزمایش اتصال» بررس کنید. +PRESET_PROFILES: list[dict] = [ + { + "name": "mock-local", + "label": "خوراک آزمایشی محلی (بدون اینترنت، بدون هزینه)", + "cost": FREE, + "url_template": "http://127.0.0.1:8788/quote?symbol={symbol}", + "json_path": "data.0.pl", + "key_header": "", "key_query_name": "", "env_key": "", + "tested": True, + "note": "برای آزمایش کامل برنامه و نشان‌دادن کارکردِ اتصال زنده به سرمایه‌گذار. دادهٔ این خوراک ساختگی است و روی آن هیچ ادعای درآمدی نمی‌شود.", + "gives": "قیمت یک لنگه (قیمت پایه) برای همهٔ نمادها، با نوسان ساختگی و یک رخداد برنامه‌ریزی‌شده برای دیدن سیگنال", + "after": "ستون تازگی داده سبز می‌شود و قیمت‌ها هر چند ثانیه عوض می‌شوند؛ یعنی کل مسیر فنی «زنده» کار می‌کند.", + "steps": "۱) در پوشهٔ ایستگاه دستور `python mock_feed.py` را اجرا کنید (یا خوراک همراه کارساز خودکار بالا می‌آید). ۲) همین پروفایل را انتخاب و آزمایش کنید.", + }, + { + "name": "tgju-usd", + "label": "tgju — دلار، طلا، سکه (رایگان، آزمون‌شده)", + "cost": FREE, + "url_template": "https://api.tgju.org/v1/market/indicator/summary-table-data/{symbol}", + "json_path": "data.0.3", + "key_header": "", "key_query_name": "", "env_key": "", + "tested": True, + "note": ("آزمون‌شده در ۲۲ سپتامبر ۲۰۲۶: پاسخ ۲۰۰ در ۰٫۳ تا ۱٫۸ ثانیه. ستون چهارم سطر اول = " + "قیمت پایانی. پنج شاخص (دلار، گرم طلای ۱۸، سکهٔ امامی، نیم، ربع) با یک نقطهٔ " + "پایانی مستقل (call1.tgju.org/ajax.json) مقایسه شد و هر پنج عدد یکی درآمد؛ پس " + "مسیر «data.0.3» درست است. اگر روزی ساختار عوض شد، با «کاوش پاسخ سرویس» مسیر " + "تازه را پیدا کنید."), + "gives": ("قیمت زندهٔ دلار، طلا و سکه. نماد ردیف را نام شاخص tgju بگذارید: price_dollar_rl " + "(دلار) · geram18 (گرم طلای ۱۸) · sekeb (سکهٔ امامی) · sekee (سکهٔ بهار) · " + "nim (نیم) · rob (ربع)."), + "after": ("تازگی داده سبز می‌شود و برای ردیف‌های دلار/طلا/سکه قیمت واقعی می‌آید. این " + "خوراک برای سهام، آتی و اختیار چیزی نمی‌دهد؛ برای آزمون «قیمت زنده» و برای " + "نرخ طلا/ارز پایهٔ محاسبهٔ آتی طلا کافی است."), + "steps": ("۱) ردیف اسنپ‌شات بسازید و در ستون نماد همان نام انگلیسی شاخص را بگذارید " + "(مثل price_dollar_rl). ۲) همین پروفایل را انتخاب و «آزمایش اتصال» را بزنید."), + }, + { + "name": "tsetmc-cdn", + "label": "tsetmc — قیمت پایانی سهام و آپشن (رایگان، آزمون‌نشده)", + "cost": FREE, + "url_template": "https://cdn.tsetmc.com/api/ClosingPrice/GetClosingPriceDailyList/{symbol}/0", + "json_path": "closingPriceDaily.0.pClosing", + "key_header": "", "key_query_name": "", "env_key": "", + "tested": False, + "note": "منبع رسمی و رایگان است ولی بی‌تعهد. در نشانی، {symbol} باید «کد نماد» (insCode) باشد نه نام نماد؛ کد را در فیلد feed_symbol هر ردیف اسنپ‌شات بگذارید.", + "gives": "قیمت پایانی روز برای سهم و آپشن، بر پایهٔ کد نماد", + "after": "قیمت پایه از منبع رسمی می‌آید؛ ولی نرخ به‌روزرسانی روزانه است، نه لحظه‌ای.", + "steps": "۱) کد نماد هر سهم را از سایت tsetmc بردارید. ۲) در اسنپ‌شات، فیلد feed_symbol هر ردیف را با آن کد پر کنید. ۳) آزمون اتصال.", + }, + { + "name": "exchange-irt", + "label": "صرافی ایرانی — نرخ ریالی (رایگان، آزمون‌نشده)", + "cost": FREE, + "url_template": "https://api.exir.io/v2/ticker?symbol={symbol}", + "json_path": "last", + "key_header": "", "key_query_name": "", "env_key": "", + "tested": True, + "note": ("این سرویس در آزمون واقعی پاسخ سالم داد (شهریور ۱۴۰۵). برای هر ردیف، در ستون «کد نماد» " + "نام بازار را بنویسید: usdt-irt · btc-irt · eth-irt و مانند این‌ها. کاربردش اثبات اتصال زندهٔ " + "واقعی بدون کلید است، نه ساختن سیگنال سهام."), + "gives": "نرخ لحظه‌ای ریالی از یک بازار واقعی، بدون کلید و بدون هزینه", + "after": "تازگی داده سبز می‌شود و می‌بینید قیمت واقعی همان لحظه خوانده می‌شود.", + "steps": "۱) پروفایل را انتخاب کنید. ۲) در گام ۲ جدول «وارد کردن اعداد کارگزاری»، در ستون کد نماد نام بازار را بنویسید. ۳) آزمون اتصال.", + }, + { + "name": "broker-service", + "label": "سرویس دادهٔ خریدنی (کلیددار) — قالب نمونه", + "cost": PAID, + "url_template": "https://api.example.ir/Quote.php?key={key}&l18={symbol}", + "json_path": "data.0.pl", + "key_header": "", "key_query_name": "key", "env_key": "MARKET_API_KEY", + "tested": False, + "note": "این قالب نمونهٔ عمومی است؛ قالب واقعی را از مستندات فروشنده کپی کنید. معمولاً ۴ چیز می‌دهند: قیمت پایه، ریزمعاملات، زنجیرهٔ آپشن، دادهٔ تاریخی.", + "gives": "قیمت زندهٔ همهٔ نمادها + دادهٔ تاریخی برای پس‌آزمایی", + "after": "قیمت پایه هر ۳۰ ثانیه خودکار تازه می‌شود، تازگی داده سبز می‌ماند، و پس‌آزمایی روی دادهٔ واقعی ممکن می‌شود. وجه تضمین همچنان دستی از کارگزاری می‌آید.", + "steps": "۱) کلید را از فروشنده بگیرید. ۲) قالب نشانی و مسیر JSON را از مستنداتش کپی کنید. ۳) کلید را همین‌جا بگذارید. ۴) آزمون اتصال. ۵) اگر درست بود، «ذخیره» بزنید تا هر بار خودکار وصل شود.", + }, + { + "name": "custom", + "label": "اتصال دلخواه (خودم پرش می‌کنم)", + "cost": FREE, + "url_template": "", "json_path": "", "key_header": "", "key_query_name": "key", "env_key": "", + "tested": False, + "note": "هر سرویسی که خواستید. دو چیز لازم است: نشانی‌ای که {symbol} در آن باشد، و مسیر رسیدن به عدد قیمت در پاسخ JSON.", + "gives": "هر چیزی که سرویس بدهد", + "after": "همان لحظه‌ای که نشانی درست شود، قیمت زنده در همهٔ گام‌ها جاری می‌شود.", + "steps": "۱) «کاوش پاسخ سرویس» را بزنید و نشانی را آزمایش کنید. ۲) از فهرست، مسیر عدد قیمت را انتخاب کنید. ۳) ذخیره.", + }, +] + +PROFILE_FIELDS = ("name", "label", "cost", "url_template", "json_path", "key_header", + "key_query_name", "env_key", "note", "gives", "after", "steps", "tested", "custom") + + +def _now() -> str: + return datetime.now(timezone.utc).isoformat(timespec="seconds") + + +def _clean(profile: dict) -> dict: + out = {k: profile.get(k, "") for k in PROFILE_FIELDS} + out["name"] = str(out["name"] or "").strip() or "custom" + out["label"] = str(out["label"] or out["name"]).strip() + out["tested"] = bool(out.get("tested")) + out["custom"] = bool(profile.get("custom")) # دست‌کاری کاربر: در به‌روزرسانی‌ها دست نمی‌زنیم + for k in ("url_template", "json_path", "key_header", "key_query_name", "env_key"): + out[k] = str(out[k] or "").strip() + return out + + +def default_store() -> dict: + return {"version": 1, "preset_version": PRESET_VERSION, "selected": "mock-local", + "updated_at": _now(), "profiles": [_clean(p) for p in PRESET_PROFILES]} + + +def _refresh_presets(data: dict) -> tuple[dict, bool]: + """پروفایل‌های آماده را به نسخهٔ تازهٔ برنامه به‌روز می‌کند. + + پروفایل‌هایی که خودِ کاربر ساخته یا دست‌کاری کرده (custom) دست‌نخورده می‌مانند؛ + بدون این کار، کاربر نسخهٔ قدیمی برنامه را نگه می‌داشت و نشانی‌های اصلاح‌شده را نمی‌دید. + """ + changed = False + if int(data.get("preset_version", 1)) >= PRESET_VERSION: + return data, changed + by_name = {p["name"]: _clean(p) for p in PRESET_PROFILES} + out = [] + for prof in data.get("profiles", []): + name = prof.get("name") + if name in by_name and not prof.get("custom"): + out.append(dict(by_name[name], custom=False)) + changed = True + else: + out.append(prof) + data["profiles"] = out + data["preset_version"] = PRESET_VERSION + return data, True + + +def load_store() -> dict: + """دفتر اتصال‌ها را می‌خواند؛ اگر نبود، نسخهٔ پیش‌فرض را می‌سازد.""" + if PROFILES_FILE.exists(): + try: + data = json.loads(PROFILES_FILE.read_text(encoding="utf-8")) + except Exception: + return default_store() + if not isinstance(data, dict) or not isinstance(data.get("profiles"), list): + return default_store() + seen = {p["name"] for p in data["profiles"] if isinstance(p, dict)} + for preset in PRESET_PROFILES: # پروفایل‌های تازهٔ نسخهٔ جدید هم اضافه می‌شوند + if preset["name"] not in seen: + data["profiles"].append(_clean(preset)) + data["profiles"] = [_clean(p) for p in data["profiles"] if isinstance(p, dict)] + data.setdefault("selected", "mock-local") + data, changed = _refresh_presets(data) + if changed: + save_store(data) + return data + return default_store() + + +def save_store(store: dict) -> Path: + CONFIG_DIR.mkdir(parents=True, exist_ok=True) + store = dict(store) + store["version"] = 1 + store["updated_at"] = _now() + store["profiles"] = [_clean(p) for p in store.get("profiles", [])] + PROFILES_FILE.write_text(json.dumps(store, ensure_ascii=False, indent=2), encoding="utf-8") + return PROFILES_FILE + + +def find_profile(store: dict, name: str) -> dict | None: + for p in store.get("profiles", []): + if p.get("name") == name: + return p + return None + + +def upsert_profile(store: dict, profile: dict) -> dict: + prof = _clean(profile) + prof["custom"] = True if profile.get("custom") is None else bool(profile.get("custom")) + existing = find_profile(store, prof["name"]) + if existing: + existing.update(prof) + prof = existing + else: + store.setdefault("profiles", []).append(prof) + return prof + + +def select_profile(store: dict, name: str) -> dict | None: + prof = find_profile(store, name) + if prof is None: + return None + store["selected"] = name + return prof + + +def delete_profile(store: dict, name: str) -> bool: + before = len(store.get("profiles", [])) + store["profiles"] = [p for p in store.get("profiles", []) if p.get("name") != name] + if store.get("selected") == name: + store["selected"] = (store["profiles"][0]["name"] if store["profiles"] else "custom") + return len(store["profiles"]) != before + + +# ---------------------------------------------------------------- کلیدها +def load_keys() -> dict: + if KEYS_FILE.exists(): + try: + data = json.loads(KEYS_FILE.read_text(encoding="utf-8")) + return data if isinstance(data, dict) else {} + except Exception: + return {} + return {} + + +def save_key(name: str, key: str) -> Path: + """کلید را روی رایانهٔ خودتان ذخیره می‌کند (فقط با درخواست صریح شما).""" + CONFIG_DIR.mkdir(parents=True, exist_ok=True) + data = load_keys() + if key: + data[name] = {"key": key, "saved_at": _now()} + else: + data.pop(name, None) + KEYS_FILE.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8") + try: + os.chmod(KEYS_FILE, 0o600) + except OSError: # ویندوز این را نادیده می‌گیرد؛ اشکالی ندارد + pass + return KEYS_FILE + + +def stored_key(name: str) -> str: + rec = load_keys().get(name) or {} + return str(rec.get("key", "")) if isinstance(rec, dict) else "" + + +def resolve_key(profile: dict, *, inline_key: str = "") -> tuple[str, str]: + """کلید را به ترتیب اولویت پیدا می‌کند و می‌گوید از کجا آمد. + + ترتیب: کلیدی که همین حالا در کادر گذاشته‌اید ← کلید ذخیره‌شده ← متغیر محیطی. + هیچ‌وقت کلید را در لاگ یا گزارش چاپ نمی‌کند. + """ + if inline_key: + return inline_key, "کادر همین لحظه" + saved = stored_key(str(profile.get("name", ""))) + if saved: + return saved, "ذخیره‌شده روی همین رایانه" + env_name = str(profile.get("env_key", "") or "").strip() + if env_name: + env_val = os.environ.get(env_name, "") + if env_val: + return env_val, f"متغیر محیطی {env_name}" + return "", "بدون کلید" + + +def key_status(name: str) -> dict: + store = load_store() + prof = find_profile(store, name) or {} + key, where = resolve_key(prof) + env_name = str(prof.get("env_key", "") or "") + return {"stored": bool(stored_key(name)), "where": where, "has_key": bool(key), + "env_key": env_name, "env_set": bool(env_name and os.environ.get(env_name))} + + +def live_config(profile: dict) -> dict: + """پروفایل را به قالب تنظیمات زندهٔ datafeed تبدیل می‌کند.""" + import datafeed # واردکردن تنبل: این ماژول باید مستقل هم کار کند + cfg = dict(datafeed.DEFAULT_LIVE_CONFIG) + cfg["url_template"] = str(profile.get("url_template", "") or "") + cfg["json_path"] = str(profile.get("json_path", "") or "") + cfg["key_header"] = str(profile.get("key_header", "") or "") + cfg["key_query_name"] = str(profile.get("key_query_name", "") or "") + return cfg + + +def apply_profile(store: dict, name: str, *, inline_key: str = "") -> dict: + """پروفایل انتخابی را «فعال» می‌کند: تنظیمات زنده + کلید + یادداشت منبع.""" + prof = select_profile(store, name) + if prof is None: + raise KeyError(f"پروفایل پیدا نشد: {name}") + key, where = resolve_key(prof, inline_key=inline_key) + return {"name": prof["name"], "profile": prof, "live_cfg": live_config(prof), + "key": key, "key_where": where, "is_mock": prof["name"] == "mock-local"} + + +def active_or_none() -> dict | None: + """پروفایل فعالِ ذخیره‌شده را برمی‌گرداند (برای راه‌اندازی خودکار برنامه).""" + store = load_store() + name = store.get("selected") or "" + if not name or find_profile(store, name) is None: + return None + try: + return apply_profile(store, name) + except KeyError: + return None + + +def summary_rows() -> list[list[str]]: + """ردیف‌های خلاصه برای جدول رابط گرافیکی.""" + store = load_store() + rows = [] + for p in store.get("profiles", []): + status = "آزمون‌شده" if p.get("tested") else "آزمون‌نشده" + mark = "★" if p.get("name") == store.get("selected") else "" + rows.append([mark, p.get("label", p["name"]), p.get("cost", ""), status, + p.get("url_template", "") or "—"]) + return rows + + +def main(argv: list[str] | None = None) -> int: + import argparse + ap = argparse.ArgumentParser(description="دفتر اتصال‌های ایستگاه") + ap.add_argument("--list", action="store_true", help="نمایش پروفایل‌ها") + ap.add_argument("--select", help="انتخاب پروفایل با نام") + args = ap.parse_args(argv) + store = load_store() + if args.select: + prof = select_profile(store, args.select) + if prof is None: + print("پروفایل پیدا نشد.") + return 2 + save_store(store) + print(f"پروفایل فعال شد: {prof['label']}") + if args.list or not args.select: + active = store.get("selected") + for row in summary_rows(): + print(" | ".join(str(c) for c in row)) + print(f"فعال: {active}") + print(f"پروندهٔ مشخصات: {PROFILES_FILE}") + print(f"کلیدهای ذخیره‌شده: {'دارد' if load_keys() else 'ندارد'}") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/station/daily_trial.py b/station/daily_trial.py new file mode 100644 index 0000000000000000000000000000000000000000..19cbe38338882c0c870a7c5847aa0f7e1f43d15b --- /dev/null +++ b/station/daily_trial.py @@ -0,0 +1,386 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""مراسم روزانه — یک دستور، تمام کارهای آزمون دو هفته‌ای. + +منطق کار: هر روز کاری یک بار این برنامه را اجرا می‌کنید (یا ویندوز خودش اجرا می‌کند). +شش کار انجام می‌شود و هیچ‌کدام سفارش‌گذاری نیست: + + ۱. قیمت‌ها خوانده می‌شوند (زنده، یا پروندهٔ دستی، یا دادهٔ نمونه — با برچسب صادق). + ۲. موتور ریاضی روی همان قیمت‌ها اجرا می‌شود. + ۳. سیگنال‌های امروز در «دفتر آزمون زنده» ثبت می‌شوند (با زنجیرهٔ هش). + ۴. ردیف‌های قبلی با قیمت‌های تازه بازسنجی می‌شوند. + ۵. سالم‌بودن زنجیره بررسی و گزارش سرمایه‌گذار ساخته می‌شود. + ۶. «کارنامه» به‌روز می‌شود: آیا سابقهٔ ثبت‌شده به‌قدری هست که خرید دادهٔ زنده و رفتن + به جلسهٔ شرکت معنی داشته باشد، یا هنوز نه. + +هر اجرا در `data/trial-daily.log` هم ثبت می‌شود تا روزها قابل شمارش باشند. +""" +from __future__ import annotations + +import argparse +import json +import sys +import time +from datetime import datetime, timezone +from pathlib import Path + +VERSION = "0.1.0" +BASE = Path(__file__).resolve().parent +DATA = BASE / "data" +DESK_DIR = (BASE.parent / "desk").resolve() +KODAL_DIR = (BASE.parent / "kodal-alert").resolve() +LOG_FILE = DATA / "trial-daily.log" +REPORT_FILE = DATA / "trial-report.html" +RUNNING_SNAPSHOT = DATA / "current-snapshot.json" + +for p in (str(BASE), str(DESK_DIR), str(KODAL_DIR)): + if p not in sys.path: + sys.path.insert(0, p) + +import datafeed # noqa: E402 +import live_trial as trial # noqa: E402 + +DEFAULT_RULES = { + "capital": 20_000_000_000, "hurdle": 0.39, + "min_edge_arbitrage_pct": 3.0, "min_edge_leveraged_pct": 5.0, + "max_margin_pct": 0.20, "max_position_pct": 0.35, "max_positions": 3, + "min_liquidity_contracts_per_day": 20, "max_spread_pct": 0.03, + "max_plausible_arb_pct": 250.0, "max_plausible_lev_pct": 400.0, +} + +SYNTHETIC_MARKS = ("ساختگی", "نمونهٔ همراه") +SYNTHETIC_PATH_MARKS = ("demo", "sample", "template", "نمونه", "قالب") + + +def _now() -> str: + return datetime.now(timezone.utc).isoformat(timespec="seconds") + + +def today() -> str: + return time.strftime("%Y-%m-%d") + + +def is_synthetic(source_label: str) -> bool: + """آیا این داده ساختگی است؟ برچسب منبع را می‌خوانیم، نه حدس را.""" + return any(m in str(source_label or "") for m in SYNTHETIC_MARKS) + + +def path_is_synthetic(path) -> bool: + """پروندهٔ نمونه و قالب (مثل market-demo.json) دادهٔ واقعی حساب نمی‌شود. + + بی این سنجه، کسی می‌توانست با دادن پروندهٔ نمونه، روز «واقعی» جعل کند و کارنامه + بی‌دلیل سبز شود. + """ + if not path: + return False + name = str(path).replace("\\", "/").lower() + base = name.rsplit("/", 1)[-1] + if any(m in base for m in SYNTHETIC_PATH_MARKS): + return True + return any(part in ("demo", "samples", "templates") for part in name.split("/")[:-1]) + + +def write_running_snapshot(snap, rules: dict, path: Path | str | None = None) -> Path: + """اسنپ‌شات جاری را به قالب بازار میز معاملات می‌نویسد.""" + rows = [{k: v for k, v in r.items() if not k.startswith("_")} for r in snap.rows] + out = Path(path or RUNNING_SNAPSHOT) + out.parent.mkdir(parents=True, exist_ok=True) + out.write_text(json.dumps({"as_of": time.strftime("%Y-%m-%d %H:%M"), + "hurdle": rules.get("hurdle", 0.39), + "capital": rules.get("capital", 20_000_000_000), + "rows": rows}, ensure_ascii=False, indent=2), encoding="utf-8") + return out + + +def scan_signals(market_path: Path | str, rules: dict, *, desk_db=None, kodal_db=None) -> list: + """موتور میز معاملات را روی اسنپ‌شات اجرا می‌کند و سیگنال‌های خام را برمی‌گرداند.""" + import desk as deskmod + cfg = dict(getattr(deskmod, "DEFAULT_CONFIG", {})) + cfg.update({k: v for k, v in (rules or {}).items() if k in DEFAULT_RULES}) + if desk_db: + cfg["desk_db"] = str(desk_db) + desk_obj = deskmod.Desk(cfg.get("desk_db") or getattr(deskmod, "DEFAULT_DB")) + return deskmod.scan_market(market_path, cfg, desk_obj, kodal_db) + + +def now_map_from_signals(sigs, rules: dict) -> dict: + """حاشیهٔ امروز هر نماد، از سیگنال‌های تازه.""" + out: dict = {} + for s in sigs or []: + kind = getattr(s, "kind", "") + floor = (rules.get("min_edge_arbitrage_pct", 3.0) if kind in ("basis", "arbitrage") + else rules.get("min_edge_leveraged_pct", 5.0)) + detail = getattr(s, "detail", {}) or {} + out[str(getattr(s, "symbol", ""))] = { + "expected_now": getattr(s, "annualized_pct", None), + "floor": floor, + "spot_now": detail.get("spot") or detail.get("stock_price"), + "future_now": detail.get("future"), + } + return out + + +def pick_source(*, mode: str = "auto", file_path=None, live_cfg=None, key: str = "", + allow_network: bool = True, fallback_file=None, progress=None) -> tuple[object, str, list[str]]: + """منبع داده را انتخاب می‌کند: زنده (اگر تنظیم شده) ← پرونده ← نمونه. با برچسب صادق.""" + notes: list[str] = [] + + def say(m: str) -> None: + notes.append(m) + if progress: + progress(m) + + live_cfg = live_cfg or {} + url_ok = bool(str(live_cfg.get("url_template", "")).strip()) + mode = (mode or "auto").lower() + if mode in ("live", "auto") and url_ok and allow_network: + snap = datafeed.build_snapshot("live", file_path=file_path, live_cfg=live_cfg, key=key, + allow_network=True, progress=progress) + if snap.status in ("ok", "partial") and snap.live_prices: + say(f"منبع: {snap.source_label} · {snap.messages[-1] if snap.messages else ''}") + return snap, "live", notes + say(f"دادهٔ زنده نیامد ({snap.status})؛ به منبع پشتیبان می‌رویم.") + if mode == "sim": + snap = datafeed.demo_snapshot() + say("منبع: دادهٔ نمونهٔ همراه برنامه (ساختگی).") + return snap, "sim", notes + path = file_path or fallback_file + if path and Path(path).exists(): + snap = datafeed.load_snapshot_file(path) + say(f"منبع: پروندهٔ دستی {Path(path).name} — تازگی: {snap.freshness_label}") + return snap, "file", notes + snap = datafeed.demo_snapshot() + say("پرونده‌ای داده نشد؛ با دادهٔ نمونهٔ همراه برنامه (ساختگی) ادامه می‌دهیم.") + return snap, "sim", notes + + +def run_daily(*, mode: str = "auto", file_path=None, live_cfg=None, key: str = "", + rules: dict | None = None, note: str = "", db=None, report=None, + allow_network: bool = True, use_kodal: bool = True, add_span: float = 0.0, + fallback_file=None, desk_db=None, progress=None, log_path=None) -> dict: + """مراسم یک روز. خروجی: خلاصهٔ کارهایی که انجام شد (برای نمایش و برای لاگ).""" + rules = {k: (rules or {}).get(k, v) for k, v in DEFAULT_RULES.items()} + notes: list[str] = [] + + def say(m: str) -> None: + notes.append(m) + if progress: + progress(m) + + errors: list[str] = [] + snap, used_mode, src_notes = pick_source(mode=mode, file_path=file_path, live_cfg=live_cfg, + key=key, allow_network=allow_network, + fallback_file=fallback_file, progress=progress) + if not snap.rows: + return {"ok": False, "errors": ["هیچ ردیفی برای محاسبه نیست؛ منبع داده را بررسی کنید."], + "notes": notes, "handled": 0} + + market_path = write_running_snapshot(snap, rules) + kodal_db = None + if use_kodal: + cand = KODAL_DIR / "data" / "demo.sqlite3" + kodal_db = cand if cand.exists() else None + try: + sigs = scan_signals(market_path, rules, kodal_db=kodal_db, desk_db=desk_db) + except Exception as e: # موتور نباید مراسم روزانه را بخواباند + return {"ok": False, "errors": [f"محاسبه انجام نشد: {e}"], "notes": notes, "handled": 0} + say(f"محاسبه انجام شد: {len(sigs)} ردیف.") + + t = trial.Trial(db or trial.DEFAULT_DB) + saved = t.record_from_signals(sigs, source_label=snap.source_label, mode=used_mode, + add_span=add_span) + say(f"دفتر: {len(saved)} ردیف تازه ثبت شد (تکراری‌ها رد شدند).") + marked = t.mark(now_map_from_signals(sigs, rules)) + say(f"دفتر: {len(marked)} ردیف با قیمت‌های امروز بازسنجی شد.") + chain_ok, chain_msg = t.verify_chain() + say(("زنجیرهٔ هش سالم است." if chain_ok else f"هشدار زنجیره: {chain_msg}")) + + report_path = t.write_report(report or REPORT_FILE) + csv_path = t.write_csv(DATA / "trial-entries.csv") + summary = t.summary() + + used_file = None + if used_mode == "file": + candidate = file_path or fallback_file + used_file = str(candidate) if candidate else None + unconfirmed = bool(used_file) and not datafeed.snapshot_confirmed(used_file) + synthetic = (is_synthetic(getattr(snap, "source_label", "")) + or path_is_synthetic(used_file) or unconfirmed) + rec = { + "ts": _now(), "date": today(), "mode": used_mode, + "source": getattr(snap, "source_label", ""), + "data_file": (Path(used_file).name if used_file else ""), + "confirmed_file": (datafeed.snapshot_confirmed(used_file) if used_file else False), + "synthetic": synthetic, + "rows": len(snap.rows), "signals": len(sigs), "recorded": len(saved), + "marked": len(marked), "entries": summary["entries"], "chain_ok": chain_ok, + "note": note, "report": str(report_path), + } + append_log(rec, log_path) # مسیر لاگ را می‌شود داد تا آزمون‌ها به دفتر واقعی دست نزنند + score = scorecard(t, log_records=read_log(log_path)) + return {"ok": True, "notes": notes, "errors": errors, "record": rec, "summary": summary, + "scorecard": score, "report": str(report_path), "csv": str(csv_path), + "handled": len(saved), "source_label": getattr(snap, "source_label", ""), + "synthetic": rec["synthetic"], "market_path": str(market_path), + "snapshot_obj": snap, "signals": len(sigs)} + + +# ---------------------------------------------------------------- لاگ روزانه +def append_log(rec: dict, path: Path | str | None = None) -> Path: + """هر اجرا یک خط؛ مسیر پیش‌فرض در لحظهٔ اجرا خوانده می‌شود تا آزمون‌پذیر باشد.""" + path = Path(path or LOG_FILE) + path.parent.mkdir(parents=True, exist_ok=True) + with path.open("a", encoding="utf-8") as f: + f.write(json.dumps(rec, ensure_ascii=False) + "\n") + return path + + +def read_log(path: Path | str | None = None) -> list[dict]: + path = Path(path or LOG_FILE) + if not path.exists(): + return [] + out = [] + for line in path.read_text(encoding="utf-8").splitlines(): + line = line.strip() + if not line: + continue + try: + out.append(json.loads(line)) + except Exception: + continue + return out + + +# ---------------------------------------------------------------- کارنامه +def scorecard(t=None, *, log_records=None, log_path=None, target_days: int = 10, + target_real_days: int = 5, min_marked_ratio: float = 0.6, min_moves: int = 3) -> dict: + """آیا سابقهٔ ثبت‌شده به‌قدر کافی هست؟ پنج شرط، همه با عدد، هیچ شرط سلیقه‌ای.""" + t = t or trial.Trial() + summary = t.summary() + log_records = read_log(log_path) if log_records is None else log_records + days = sorted({r.get("date") for r in log_records if r.get("date") and r.get("chain_ok", True)}) + real_days = sorted({r["date"] for r in log_records + if r.get("date") and not r.get("synthetic", True)}) + marks = t.latest_marks() + deltas = [m["delta_pp"] for m in marks.values() if isinstance(m.get("delta_pp"), (int, float))] + moved = [d for d in deltas if abs(d) >= 1.0] + up = [d for d in deltas if d >= 1.0] + down = [d for d in deltas if d <= -1.0] + entries = summary.get("entries", 0) + marked = summary.get("marked", 0) + marked_ratio = (marked / entries) if entries else 0.0 + + criteria = [ + {"key": "days", "name": "تداوم روزانه (روزهای ثبت‌شده)", + "have": len(days), "want": target_days, "ok": len(days) >= target_days, + "hint": "هر روز کاری یک بار «مراسم امروز» را اجرا کنید."}, + {"key": "real_days", "name": "روزهای با دادهٔ واقعی (نه ساختگی)", + "have": len(real_days), "want": target_real_days, "ok": len(real_days) >= target_real_days, + "hint": "خوراک آزمایشی برای تمرین است؛ برای ارائه به شرکت روزهای واقعی لازم است."}, + {"key": "marked", "name": "سهم بازسنجی‌شدهٔ دفتر", + "have": round(marked_ratio, 3), "want": min_marked_ratio, "ok": marked_ratio >= min_marked_ratio, + "hint": "بازسنجی نشان می‌دهد موتور با قیمت‌های تازه هم اجرا می‌شود."}, + {"key": "moves", "name": "حرکت واقعی در دفتر (بازتر و بسته)", + "have": {"moved": len(moved), "up": len(up), "down": len(down)}, + "want": {"moved": min_moves, "up": 1, "down": 1}, + "ok": len(moved) >= min_moves and len(up) >= 1 and len(down) >= 1, + "hint": "هم فرصت تازه لازم است، هم فرصتی که بسته شده؛ هر دو نشانهٔ درست‌کاری است."}, + {"key": "chain", "name": "زنجیرهٔ هش سالم", + "have": bool(summary.get("chain_ok")), "want": True, "ok": bool(summary.get("chain_ok")), + "hint": "اگر زنجیره بشکند، یعنی ردیفی دست‌کاری شده؛ تا پیدا نشود به دفتر استناد نکنید."}, + ] + ready = all(c["ok"] for c in criteria) + missing = [c for c in criteria if not c["ok"]] + if ready: + verdict = ("آماده: سابقهٔ ثبت‌شده کافی است. حالا خرید دادهٔ زنده و بردن گزارش دفتر به شرکت معنی دارد.") + else: + verdict = ("هنوز نه: " + " · ".join( + f"{c['name']} ({c['have']} از {c['want']})" for c in missing[:2]) + + " — بعد از انجام، همین دکمه را دوباره بزنید.") + return {"ready": ready, "criteria": criteria, "verdict": verdict, + "days": len(days), "real_days": len(real_days), + "moved": len(moved), "up": len(up), "down": len(down), + "marked_ratio": round(marked_ratio, 3), "entries": entries, "marked": marked, + "last_run": (log_records[-1].get("ts") if log_records else None), + "runs": len(log_records)} + + +def status_text(score: dict) -> str: + lines = ["کارنامهٔ آزمون دو هفته‌ای:"] + for c in score["criteria"]: + mark = "✓" if c["ok"] else "✗" + lines.append(f" {mark} {c['name']}: {c['have']} (لازم: {c['want']}) — {c['hint']}") + lines.append(" " + ("آماده" if score["ready"] else "ناتمام")) + lines.append(" " + score["verdict"]) + return "\n".join(lines) + + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description="مراسم روزانهٔ آزمون زندهٔ ایستگاه") + ap.add_argument("--mode", default="auto", choices=("auto", "live", "file", "sim")) + ap.add_argument("--file", dest="file_path", help="پروندهٔ اسنپ‌شات دستی") + ap.add_argument("--note", default="", help="یادداشت امروز") + ap.add_argument("--status", action="store_true", help="فقط کارنامه را نشان بده") + ap.add_argument("--report", action="store_true", help="فقط گزارش سرمایه‌گذار را بساز") + ap.add_argument("--add-span", type=float, default=0.0, help="کاهش/افزایش انتظار (واحد درصد)") + ap.add_argument("--version", action="store_true") + ap.add_argument("--reset", action="store_true", + help="پاک‌کردن دفتر و لاگ برای شروع دوباره (نیازمند --yes)") + ap.add_argument("--yes", action="store_true", help="تأیید پاک‌کردن") + args = ap.parse_args(argv) + if args.version: + print(f"daily-trial {VERSION}") + return 0 + if args.reset: + if not args.yes: + print("برای پاک‌کردن دفتر، این را با --yes اجرا کنید: python daily_trial.py --reset --yes") + return 1 + removed = [] + for path in (trial.DEFAULT_DB, LOG_FILE, DATA / "trial-entries.csv", REPORT_FILE): + if Path(path).exists(): + Path(path).unlink() + removed.append(Path(path).name) + print("پاک شد: " + ("، ".join(removed) or "چیزی برای پاک‌کردن نبود")) + print("یادآوری: دفتر آزمون پاک شد؛ ردیف‌های قبلی قابل بازگشت نیستند.") + return 0 + + if args.report: + t = trial.Trial() + print(t.write_report(REPORT_FILE)) + print(t.write_csv(DATA / "trial-entries.csv")) + return 0 + if args.status: + print(status_text(scorecard())) + return 0 + + import connections as conn + live_cfg, key = {}, "" + active = conn.active_or_none() + if active: + live_cfg, key = active["live_cfg"], active["key"] + rules_path = BASE / "config" / "daily-rules.json" + rules = DEFAULT_RULES + if rules_path.exists(): + try: + rules = {**DEFAULT_RULES, **json.loads(rules_path.read_text(encoding="utf-8"))} + except Exception: + rules = DEFAULT_RULES + res = run_daily(mode=args.mode, file_path=args.file_path, live_cfg=live_cfg, key=key, + rules=rules, note=args.note, add_span=args.add_span, + fallback_file=DESK_DIR / "market-demo.json", progress=lambda m: print("· " + m)) + if not res["ok"]: + for e in res["errors"]: + print("خطا: " + e) + return 2 + r = res["record"] + print(f"\nامروز ({r['date']}): منبع {r['source'] or '—'} · " + f"{'ساختگی' if r['synthetic'] else 'واقعی'} · ردیف {r['rows']} · ثبت {r['recorded']} · " + f"بازسنجی {r['marked']}") + print("گزارش: " + res["report"]) + print() + print(status_text(res["scorecard"])) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/station/data/data-requirement-sheet.md b/station/data/data-requirement-sheet.md new file mode 100644 index 0000000000000000000000000000000000000000..6fa9d04c896bba49e89dafdb7f0f57e830bce01e --- /dev/null +++ b/station/data/data-requirement-sheet.md @@ -0,0 +1,28 @@ +# برگهٔ نیاز داده (برای فرستادن به فروشنده‌ها) + +سلام. برای یک سامانهٔ تصمیم‌گیری روی اوراق مشتقهٔ بورس تهران، این داده‌ها را لازم دارم. +لطفاً برای هر ردیف بنویسید: دارید یا نه، نرخ به‌روزرسانی، و قیمت ماهانه. + +| داده | نرخ لازم | توضیح | دارید؟ | نرخ به‌روزرسانی | قیمت | +|---|---|---|---|---|---| +| قیمت پایه سهام و صندوق‌ها | ۱ تا ۵ دقیقه | همهٔ نمادهای بورس و فرابورس | | | | +| قیمت قراردادهای آتی | ۱ تا ۵ دقیقه | کالا و اوراق | | | | +| قیمت اعمال و پرمیوم اختیار خرید و فروش | ۱ تا ۵ دقیقه | همهٔ سررسیدها | | | | +| بهترین سفارش خرید و فروش | ۱ تا ۵ دقیقه | برای محاسبهٔ اسپرد و نقدشوندگی | | | | +| سری روزانهٔ قیمت پایانی | روزانه | تاریخچهٔ حداقل ۱۲ ماه برای پس‌آزمایی | | | | +| حجم و ارزش معاملات | روزانه | برای فیلتر نقدشوندگی | | | | +| وضعیت نماد (باز، متوقف) | روزانه | برای جلوگیری از تصمیم روی نماد بسته | | | | + +## پرسش‌های فنی + +۱. قالب دسترسی: REST یا websocket؟ مسیر JSON پاسخ به چه شکل است؟ +۲. احراز هویت: کلید در نشانی یا در هدر؟ محدودیت تعداد درخواست در دقیقه چقدر است؟ +۳. پایداری: ساعت کاری و قطعی‌های معمول؛ در صورت قطع، داده دوباره پر می‌شود؟ +۴. پرداخت: ریالی؟ فاکتور رسمی؟ دورهٔ زمانی و شرایط لغو؟ +۵. اجازهٔ استفاده: آیا استفاده در یک سامانهٔ تحلیل و تصمیم‌یار مجاز است؟ + +## یادآوری برای خودم + +- وجه تضمین را هیچ فروشندهٔ داده‌ای ندارد؛ از سامانهٔ کارگزاری برداشته می‌شود (۶۰ ثانیه در روز). +- تا وقتی کارنامهٔ آزمون «آماده» نشود، خرید داده معنی ندارد: اول باید ببینم موتور روزانه فرصت پیدا می‌کند. +- پیش از امضا، قالب نشانی فروشنده را در گام ۲ ایستگاه می‌گذارم و «آزمایش اتصال» می‌زنم. diff --git a/station/data/history-template.csv b/station/data/history-template.csv new file mode 100644 index 0000000000000000000000000000000000000000..c9e78c8cf76e3cc0063f65ee12bfbf1f8622fdb7 --- /dev/null +++ b/station/data/history-template.csv @@ -0,0 +1,2 @@ +date,symbol,kind,spot,future,strike,premium,put_price,stock_price,days,margin_per_contract,liquidity_contracts_per_day,spread_pct,hurdle,realized_annualized_pct +1405-05-01,اهرم,basis,20000,22800,,,,,90,20000000,900,0.005,0.39,61.0 diff --git a/station/data/snapshot-template.json b/station/data/snapshot-template.json new file mode 100644 index 0000000000000000000000000000000000000000..d18402bd60acc5df8a637774aae4ccb8a34e50c3 --- /dev/null +++ b/station/data/snapshot-template.json @@ -0,0 +1,109 @@ +{ + "note": "این یک قالب است، نه دادهٔ واقعی. عددهای هر ردیف را با عدد امروزِ سامانهٔ کارگزاری خودتان عوض کنید و پرونده را با نام خودتان ذخیره کنید (مثلاً daily-input.json).", + "_units": "hurdle و spread_pct کسری‌اند (0.39 یعنی ۳۹٪ و 0.005 یعنی ۰.۵٪) · capital به ریال · days = روزهای مانده تا سررسید · prices به ریال · margin_per_contract = وجه تضمین هر قرارداد (سهم در این قالب: ارزش یک سهم) · liquidity_contracts_per_day = حجم قرارداد روز", + "_fields_per_kind": { + "basis": [ + "spot", + "future", + "days" + ], + "covered_call": [ + "spot", + "strike", + "premium", + "days" + ], + "tabei": [ + "stock_price", + "put_price", + "strike", + "days" + ], + "box": [ + "call_low", + "put_low", + "call_high", + "put_high", + "strike_low", + "strike_high", + "days" + ], + "parity": [ + "call", + "put", + "spot", + "strike", + "days" + ] + }, + "as_of": "تاریخ امروز", + "hurdle": 0.39, + "capital": 20000000000, + "rows": [ + { + "symbol": "اهرم", + "kind": "basis", + "spot": 20000, + "future": 22800, + "days": 90, + "storage_annual": 0.0, + "margin_per_contract": 20000000, + "unit": "قرارداد", + "liquidity_contracts_per_day": 900, + "spread_pct": 0.005 + }, + { + "symbol": "فولاد", + "kind": "covered_call", + "spot": 7000, + "strike": 7600, + "premium": 400, + "days": 45, + "margin_per_contract": 7000, + "unit": "سهم", + "liquidity_contracts_per_day": 160, + "spread_pct": 0.018 + }, + { + "symbol": "کگل", + "kind": "tabei", + "stock_price": 9800, + "put_price": 40, + "strike": 14210, + "days": 365, + "margin_per_contract": 9840, + "unit": "سهم", + "liquidity_contracts_per_day": 240, + "spread_pct": 0.02 + }, + { + "symbol": "شپنا", + "kind": "box", + "call_low": 300, + "put_low": 430, + "call_high": 175, + "put_high": 585, + "strike_low": 1200, + "strike_high": 1500, + "days": 45, + "margin_per_contract": 250000, + "unit": "قرارداد", + "liquidity_contracts_per_day": 12, + "spread_pct": 0.045 + }, + { + "symbol": "وبملت", + "kind": "parity", + "call": 420, + "put": 380, + "spot": 9000, + "strike": 9000, + "days": 30, + "rate": 0.39, + "margin_per_contract": 9000, + "unit": "سهم", + "liquidity_contracts_per_day": 80, + "spread_pct": 0.02 + } + ] +} \ No newline at end of file diff --git a/station/data_sources.py b/station/data_sources.py new file mode 100644 index 0000000000000000000000000000000000000000..b2b2b6bc14bcf99383c01ff81cfd55c29fd4e4dc --- /dev/null +++ b/station/data_sources.py @@ -0,0 +1,554 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""امکان‌سنجی مسیرهای داده، پیش از خرید: کدام روش واقعاً به کار ایستگاه می‌خورد؟ + +سه روشی که صاحب پرونده نام برد، این‌جا سنجیده می‌شوند: + ۱. خرید وب‌سرویس رسمی (pull، نیازمند کلید و پول) + ۲. سرویس‌های رایگان سایت مرجع (pull، بی‌تعهد، احتمال گپ زمانی) + ۳. پوش لحظه‌ای (websocket / RLC) از کارگزاری یا سازمان بورس + +این ابزار «تبلیغ» نمی‌کند؛ فقط می‌سنجد و می‌گوید: + • کدام نشانی جواب می‌دهد و چقدر طول می‌کشد، + • کدام میدان دادهٔ ایستگاه از آن درمی‌آید و کدام درنمی‌آید، + • دو فراخوانی پشت‌سرهم چه می‌گویند (تازه می‌شود یا همان عدد می‌مانَد)، + • و پوش لحظه‌ای اصلاً دسترسی‌پذیر است یا نه. + +اجرا: + python data_sources.py --all --symbol فولاد + python data_sources.py --ws wss://example.ir/market + python data_sources.py --fixture (نمایش شکل خروجی با دادهٔ ساختگی محلی) + python data_sources.py --sheet (برگهٔ نیاز داده برای فرستادن به فروشنده) +""" +from __future__ import annotations + +import argparse +import json +import random +import socket +import ssl +import sys +import threading +import time +from datetime import datetime, timezone +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer +from pathlib import Path +from urllib.parse import urlparse, parse_qs + +VERSION = "0.1.0" +BASE = Path(__file__).resolve().parent +DATA = BASE / "data" +TSETMC_HOST = "https://cdn.tsetmc.com" + +for p in (str(BASE),): + if p not in sys.path: + sys.path.insert(0, p) + +import datafeed # noqa: E402 +import reportkit as rk # noqa: E402 + +# ---------------------------------------------------------------- نقشهٔ نقاط پایانی +ENDPOINTS: list[dict] = [ + {"name": "symbol_search", "label": "جست‌وجوی نماد و گرفتن کد نماد", + "url": TSETMC_HOST + "/api/Instrument/GetInstrumentSearch/{symbol}", + "needs": "symbol", "gives": "کد نماد (insCode) برای بقیهٔ فراخوانی‌ها، نام کامل، بازار", + "paths": ["instrumentSearch.0.insCode", "instrumentSearch.0.lVal18AFC", "instrumentSearch.0.market"], + "dynamic": False}, + {"name": "price_info", "label": "اطلاعات قیمت یک نماد", + "url": TSETMC_HOST + "/api/ClosingPrice/GetClosingPriceInfo/{code}", + "needs": "code", "gives": "آخرین قیمت، دامنهٔ مجاز، قیمت پایانی", + "paths": ["closingPriceInfo.pDrCotVal", "closingPriceInfo.priceMin", "closingPriceInfo.priceMax", + "closingPriceInfo.pClosing"]}, + {"name": "closing_daily", "label": "قیمت پایانی روزانه (سری زمانی)", + "url": TSETMC_HOST + "/api/ClosingPrice/GetClosingPriceDailyList/{code}/0", + "needs": "code", "gives": "تاریخچهٔ قیمت پایانی، حجم و ارزش معاملات (لازم برای پس‌آزمایی)", + "paths": ["closingPriceDaily.0.pClosing", "closingPriceDaily.0.pDrCotVal", + "closingPriceDaily.0.vol", "closingPriceDaily.0.qTotTran5J"]}, + {"name": "best_limits", "label": "بهترین سفارش‌های خرید و فروش", + "url": TSETMC_HOST + "/api/BestLimits/{code}", + "needs": "code", "gives": "بهترین خرید/فروش و حجمشان (برای محاسبهٔ اسپرد و نقدشوندگی)", + "paths": ["bestLimits.0.pMeDemand", "bestLimits.0.pMeOffer"]}, + {"name": "market_watch", "label": "تابلوی کل بازار", + "url": TSETMC_HOST + "/api/ClosingPrice/GetMarketWatch", + "needs": "", "gives": "قیمت آخرین معاملهٔ همهٔ نمادها در یک درخواست", + "paths": ["marketwatchData.0.pDrCotVal", "marketwatchData.0.lVal18AFC"]}, + {"name": "client_type", "label": "خریدار و فروشندهٔ حقیقی و حقوقی", + "url": TSETMC_HOST + "/api/ClientType/GetClientTypeHistory/{code}", + "needs": "code", "gives": "ترکیب حقیقی/حقوقی (برای تحلیل جریان پول، اختیاری)", + "paths": ["clientType.0.buy_I_Volume", "clientType.0.sell_I_Volume"]}, +] + +# نیازهای خودِ ایستگاه، برای داوری روش‌ها +NEEDS: list[dict] = [ + {"field": "قیمت پایه سهم یا صندوق", "freq": "هر ۱ تا ۵ دقیقه", "route": "pull (رایگان یا پولی)"}, + {"field": "قیمت آتی", "freq": "هر ۱ تا ۵ دقیقه", "route": "pull؛ در سرویس‌های رایگان باید جدا تست شود"}, + {"field": "قیمت اعمال و پرمیوم اختیار", "freq": "هر ۱ تا ۵ دقیقه", "route": "pull؛ پوشش کامل تضمین‌شده نیست"}, + {"field": "نقدشوندگی و اسپرد", "freq": "هر ۱ تا ۵ دقیقه", "route": "pull (بهترین سفارش‌ها)"}, + {"field": "روز تا سررسید", "freq": "روزانه", "route": "محاسبهٔ خودمان از تقویم"}, + {"field": "وجه تضمین هر قرارداد", "freq": "روزانه (اعلامی)", "route": "فقط سامانهٔ کارگزاری، نه سرویس داده"}, + {"field": "تاریخ قیمت برای پس‌آزمایی", "freq": "گذشته", "route": "سری روزانه؛ در سرویس رایگان کوتاه است"}, +] + + +# ---------------------------------------------------------------- سنجش pull +def _top_keys(payload) -> list[str]: + if isinstance(payload, dict): + return list(payload.keys())[:8] + if isinstance(payload, list): + return [f"list[{len(payload)}]"] + return [type(payload).__name__] + + +def probe_endpoint(ep: dict, *, symbol: str = "", code: str = "", host: str = "", + allow_network: bool = True, timeout: float = 12.0) -> dict: + """یک نقطهٔ پایانی را می‌خواند و می‌گوید چه آمد، چقدر طول کشید، و کدام میدان‌ها درآمد.""" + url = ep["url"] + if host: + url = url.replace(TSETMC_HOST, host.rstrip("/")) + if ep["needs"] == "symbol": + if not symbol: + return _fail(ep, "نام نماد داده نشده است.") + url = url.replace("{symbol}", rk_quote(symbol)) + elif ep["needs"] == "code": + if not code: + return _fail(ep, "کد نماد (insCode) نداریم؛ اول جست‌وجوی نماد باید موفق شود.") + url = url.replace("{code}", str(code)) + if not allow_network: + return _fail(ep, "شبکه خاموش است؛ سنجش انجام نشد.", url=url) + + started = time.time() + text, status = datafeed.fetch(url, timeout=timeout, retries=0, cache_name=None, cache_seconds=0, + stale_ok=False) + latency = int((time.time() - started) * 1000) + if not text: + return _fail(ep, f"پاسخی نیامد ({status})", url=url, latency_ms=latency) + try: + payload = json.loads(text) + except Exception: + return _fail(ep, "پاسخ JSON نبود (شاید صفحهٔ HTML باشد)", url=url, latency_ms=latency, + bytes=len(text)) + found: list[dict] = [] + for path in ep["paths"]: + value = datafeed.dig(payload, path) + if value is not None: + found.append({"path": path, "value": value if isinstance(value, (int, float, str)) else str(value)}) + primary = next((f["value"] for f in found + if isinstance(f["value"], (int, float)) and not isinstance(f["value"], bool)), None) + if primary is None: + primary = none_primary(payload) + return {"name": ep["name"], "label": ep["label"], "ok": bool(found), + "url": url, "http": status, "latency_ms": latency, "bytes": len(text), + "top_keys": _top_keys(payload), "fields": found, "count": len(found), + "primary": primary, "reason": "پاسخ سالم آمد" if found else + "پاسخ آمد ولی هیچ‌یک از میدان‌های موردنیاز پیدا نشد؛ ساختار عوض شده است", + "gives": ep["gives"]} + + +def none_primary(payload) -> float | None: + """یک عدد کلیدی برای مقایسهٔ دو فراخوانی (اولین عدد معنادار در پاسخ).""" + for path, value in datafeed.numeric_paths(payload, max_items=6): + if isinstance(value, (int, float)) and value not in (0, 1): + return float(value) + return None + + +def _fail(ep: dict, reason: str, *, url: str = "", latency_ms: int = 0, bytes: int = 0) -> dict: + return {"name": ep["name"], "label": ep["label"], "ok": False, "url": url or ep["url"], + "http": "", "latency_ms": latency_ms, "bytes": bytes, "top_keys": [], "fields": [], + "count": 0, "primary": None, "reason": reason, "gives": ep["gives"]} + + +def stability_check(ep: dict, *, symbol: str = "", code: str = "", host: str = "", + wait: float = 2.0, timeout: float = 12.0) -> dict: + """دو فراخوانی پشت‌سرهم: داده تازه می‌شود یا همان عدد می‌مانَد؟ + + این همان «گپ زمانی» است که خودتان اشاره کردید: سرویس رایگان ممکن است بی‌حرکت باشد. + """ + if not ep.get("dynamic", True): + return {"name": ep["name"], "checked": False, + "reason": "این نشانی قیمت نیست؛ سنجش تازگی برایش معنا ندارد."} + first = probe_endpoint(ep, symbol=symbol, code=code, host=host, timeout=timeout) + if not first["ok"]: + return {"name": ep["name"], "checked": False, "reason": first["reason"]} + time.sleep(max(0.2, wait)) + second = probe_endpoint(ep, symbol=symbol, code=code, host=host, timeout=timeout) + a, b = first.get("primary"), second.get("primary") + if a is None or b is None: + verdict, note = "نامعلوم", "عدد کلیدی برای مقایسه پیدا نشد." + elif a == b: + verdict = "بی‌حرکت" + note = "دو فراخوانی با فاصلهٔ چند ثانیه همان عدد را دادند؛ یعنی نرخ به‌روزرسانی این نشانی کند است." + else: + verdict = "تازه‌شونده" + note = "عدد بین دو فراخوانی عوض شد؛ این نشانی زنده است." + return {"name": ep["name"], "checked": True, "verdict": verdict, "note": note, + "first": a, "second": b, "latency_ms": first["latency_ms"]} + + +def probe_all(*, symbol: str = "فولاد", code: str = "", host: str = "", allow_network: bool = True, + timeout: float = 12.0, with_stability: bool = True) -> dict: + """همهٔ نقاط پایانی رایگان را می‌سنجد و کد نماد را هم در صورت نیاز درمی‌آورد.""" + items = [] + resolved = code + search = next(e for e in ENDPOINTS if e["name"] == "symbol_search") + search_res = probe_endpoint(search, symbol=symbol, host=host, allow_network=allow_network, timeout=timeout) + items.append(search_res) + if not resolved and search_res["ok"]: + for f in search_res["fields"]: + if f["path"].endswith("insCode") and str(f["value"]).strip(): + resolved = str(f["value"]).strip() + break + for ep in ENDPOINTS: + if ep["name"] == "symbol_search": + continue + items.append(probe_endpoint(ep, symbol=symbol, code=resolved, host=host, + allow_network=allow_network, timeout=timeout)) + stability = [] + if with_stability and allow_network: + for ep in ENDPOINTS: + if ep["needs"] == "code" and not resolved: + continue + stability.append(stability_check(ep, symbol=symbol, code=resolved, host=host, timeout=timeout)) + ok_count = len([1 for i in items if i["ok"]]) + return {"ran_at": datetime.now(timezone.utc).isoformat(timespec="seconds"), + "symbol": symbol, "code": resolved, "host": host or TSETMC_HOST, + "items": items, "stability": stability, + "summary": {"total": len(items), "ok": ok_count, "failed": len(items) - ok_count, + "usable_for_engine": ok_count >= 3}, + "verdict": (f"{ok_count} از {len(items)} نشانی جواب داد. " + + ("برای شروع کافی است؛ وجه تضمین را همچنان از کارگزاری بردارید." + if ok_count >= 3 else + "از این محیط به سامانه‌های ایرانی دسترسی نبود یا ساختار عوض شده؛ " + "همین آزمون را روی رایانهٔ خودتان (داخل ایران) اجرا کنید."))} + + +def rk_quote(value: str) -> str: + from urllib.parse import quote + return quote(str(value)) + + +# ---------------------------------------------------------------- سنجش پوش لحظه‌ای +WS_VERDICTS = { + 101: "قابل اتصال و ارتقا؛ اگر توکن داشته باشید، پیام‌ها هم می‌آیند.", + 400: "دسترسی هست ولی درخواست ناقص است (احتمالاً پارامتر یا توکن لازم دارد).", + 401: "سرویس هست ولی احراز هویت می‌خواهد؛ بی توکن راه نمی‌دهد.", + 403: "سرویس هست ولی اجازه نمی‌دهد (دسترسی شما مجاز نیست).", + 404: "نشانی یا مسیر اشتباه است.", + 426: "ارتقا لازم است ولی سرور شرایطش را نپذیرفت.", +} + + +def probe_ws(url: str, *, timeout: float = 8.0, extra_headers: str = "") -> dict: + """آیا اصلاً می‌شود به پوش لحظه‌ای وصل شد؟ (TCP + TLS + تلاش ارتقای HTTP) + + این آزمون نمی‌گوید «داده می‌آید»؛ می‌گوید «سرویس هست یا نه و چه می‌خواهد». + برای خواندن پیام‌ها، توکن و مجوز کارگزاری لازم است. + """ + parsed = urlparse(url) + if parsed.scheme not in ("ws", "wss") or not parsed.hostname: + return {"url": url, "ok": False, "tcp": False, "tls": False, "status": None, + "verdict": "نشانی نامعتبر", "note": "نشانی باید با ws:// یا wss:// شروع شود."} + port = parsed.port or (443 if parsed.scheme == "wss" else 80) + path = parsed.path or "/" + if parsed.query: + path += "?" + parsed.query + out = {"url": url, "ok": False, "tcp": False, "tls": False, "status": None, + "verdict": "", "note": "", "host": parsed.hostname, "port": port} + started = time.time() + try: + sock = socket.create_connection((parsed.hostname, port), timeout=timeout) + out["tcp"] = True + except OSError as e: + out["verdict"] = "دسترس نیست" + out["note"] = f"اتصال TCP ممکن نشد: {type(e).__name__} ({e})" + out["latency_ms"] = int((time.time() - started) * 1000) + return out + try: + if parsed.scheme == "wss": + ctx = ssl.create_default_context() + sock = ctx.wrap_socket(sock, server_hostname=parsed.hostname) + out["tls"] = True + key = "dGhlIHNhbXBsZSBub25jZQ==" + headers = [f"GET {path} HTTP/1.1", f"Host: {parsed.hostname}", + "Upgrade: websocket", "Connection: Upgrade", + f"Sec-WebSocket-Key: {key}", "Sec-WebSocket-Version: 13"] + for line in [x for x in extra_headers.split(";") if x.strip()]: + headers.append(line.strip()) + sock.sendall(("\r\n".join(headers) + "\r\n\r\n").encode("utf-8")) + sock.settimeout(timeout) + raw = sock.recv(4096).decode("utf-8", errors="replace") + first_line = raw.splitlines()[0] if raw else "" + code = None + parts = first_line.split() + if len(parts) >= 2 and parts[1].isdigit(): + code = int(parts[1]) + out["status"] = code + out["ok"] = code == 101 + out["verdict"] = WS_VERDICTS.get(code, f"پاسخ {code or 'ناشناخته'} از سرور") + out["note"] = ("پاسخ سرور: " + first_line) if first_line else "سرور چیزی برنگرداند." + out["response_preview"] = raw[:300] + except (ssl.SSLError, OSError, socket.timeout) as e: + out["verdict"] = "دسترسی شبکه‌ای ناتمام" + out["note"] = f"{type(e).__name__}: {e}" + finally: + try: + sock.close() + except OSError: + pass + out["latency_ms"] = int((time.time() - started) * 1000) + return out + + +def real_ws_read(url: str, *, token: str = "", seconds: float = 5.0) -> dict: + """اگر کتابخانهٔ websocket-client نصب باشد، واقعاً پیام می‌خواند؛ وگرنه صریح می‌گوید نبود.""" + try: + import websocket # type: ignore + except ImportError: + return {"ok": False, "reason": "کتابخانهٔ websocket-client نصب نیست. برای خواندن واقعی پیام‌ها: " + "pip install websocket-client"} + header = [f"Authorization: Bearer {token}"] if token else [] + try: + ws = websocket.create_connection(url, timeout=seconds, header=header) + ws.settimeout(seconds) + msg = ws.recv() + ws.close() + return {"ok": True, "first_message": str(msg)[:400]} + except Exception as e: # پیام روشن، بی استثنای خام + return {"ok": False, "reason": f"{type(e).__name__}: {e}"} + + +# ---------------------------------------------------------------- سرور نمونه (برای نمایش شکل خروجی) +FIXTURE_DATA = { + "instrumentSearch": [{"insCode": "46348559193224090", "lVal18AFC": "فولاد", "market": 1}], + "closingPriceInfo": {"pDrCotVal": 7015, "priceMin": 6650, "priceMax": 7350, "pClosing": 7015}, + "closingPriceDaily": [{"pClosing": 7015, "pDrCotVal": 7015, "vol": 124500000, "qTotTran5J": 8720}], + "bestLimits": [{"pMeDemand": 7010, "pMeOffer": 7020}], + "marketwatchData": [{"lVal18AFC": "فولاد", "pDrCotVal": 7015}], + "clientType": [{"buy_I_Volume": 51230000, "sell_I_Volume": 40110000}], +} + + +class FixtureHandler(BaseHTTPRequestHandler): + """سرور نمونهٔ محلی با همان ساختار نشانی‌های واقعی (داده ساختگی است).""" + + protocol_version = "HTTP/1.1" + hits = 0 + + def log_message(self, fmt, *args): + pass + + def do_GET(self): + u = urlparse(self.path) + type(self).hits += 1 + payload = json.loads(json.dumps(FIXTURE_DATA)) # رونوشت تازه + # هر فراخوانی، قیمت‌ها را کمی جابه‌جا می‌کند تا «بی‌حرکت» به‌نظر نرسد + jitter = random.Random(type(self).hits).uniform(-0.004, 0.004) + info = payload["closingPriceInfo"] + for key in ("pDrCotVal", "pClosing", "priceMin", "priceMax"): + info[key] = round(float(info[key]) * (1 + jitter), 2) + payload["closingPriceDaily"][0]["pDrCotVal"] = round( + 7015 * (1 + jitter), 2) + payload["closingPriceDaily"][0]["pClosing"] = round(7015 * (1 + jitter), 2) + payload["bestLimits"][0]["pMeDemand"] = round(7010 * (1 + jitter), 2) + payload["bestLimits"][0]["pMeOffer"] = round(7020 * (1 + jitter), 2) + payload["marketwatchData"][0]["pDrCotVal"] = round(7015 * (1 + jitter), 2) + body = json.dumps(payload, ensure_ascii=False).encode("utf-8") + self.send_response(200) + self.send_header("Content-Type", "application/json; charset=utf-8") + self.send_header("Content-Length", str(len(body))) + self.send_header("X-Fixture", "synthetic") + self.end_headers() + self.wfile.write(body) + + +def start_fixture(port: int = 0) -> tuple[ThreadingHTTPServer, str]: + """سرور نمونه را روی یک درگاه آزاد بالا می‌آورد و نشانی‌اش را برمی‌گرداند.""" + httpd = ThreadingHTTPServer(("127.0.0.1", port), FixtureHandler) + thread = threading.Thread(target=httpd.serve_forever, daemon=True) + thread.start() + return httpd, f"http://127.0.0.1:{httpd.server_address[1]}" + + +# ---------------------------------------------------------------- خروجی‌ها +def build_matrix() -> list[dict]: + """داوری سه مسیر در برابر نیاز ایستگاه.""" + return [ + {"route": "۱. خرید وب‌سرویس رسمی (pull)", + "gives": "قیمت زنده و تاریخچهٔ کامل، قرارداد و فاکتور", + "misses": "وجه تضمین، و «تصمیم»", + "cost": "بالا (استعلام لازم است)", + "verdict": "فعلاً نه: پول جلوتر از شاهد. اگر خریدار شرکت باشد و فاکتور رسمی لازم داشته باشد، بله.", + "test": "پس از گرفتن کلید: قالب نشانی را در گام ۲ بگذارید و «آزمایش اتصال» بزنید."}, + {"route": "۲. سرویس‌های عمومی سایت مرجع (pull)", + "gives": "قیمت پایه، بخشی از آتی و اختیار، بهترین سفارش‌ها، سری روزانه", + "misses": "وجه تضمین؛ ضمانت ندارد و ممکن است گپ زمانی داشته باشد", + "cost": "صفر", + "verdict": "بله، همین امروز: کافی است. فقط گپ و بی‌حرکتی را با همین ابزار بسنجید.", + "test": "«سنجش نقاط پایانی» + «سنجش دوفراخوانی» در همین صفحه."}, + {"route": "۳. پوش لحظه‌ای (websocket / RLC)", + "gives": "جریان لحظه‌ای، اگر کارگزاری یا سازمان دسترسی بدهد", + "misses": "برای افراد عادی معمولاً بسته است؛ مجوز و قرارداد می‌خواهد", + "cost": "نامعلوم، وابسته به قرارداد", + "verdict": "نیاز نداریم: افق تصمیم این راهبردها دقیقه‌ای است، نه میلی‌ثانیه‌ای.", + "test": "«سنجش پوش لحظه‌ای»: اول ببینید سرویس هست یا نه، بعد سراغ مجوز بروید."}, + ] + + +def requirement_sheet() -> str: + """برگهٔ نیاز داده، برای فرستادن به فروشنده‌ها و گرفتن استعلام قیمت.""" + lines = ["# برگهٔ نیاز داده (برای فرستادن به فروشنده‌ها)", + "", + "سلام. برای یک سامانهٔ تصمیم‌گیری روی اوراق مشتقهٔ بورس تهران، این داده‌ها را لازم دارم.", + "لطفاً برای هر ردیف بنویسید: دارید یا نه، نرخ به‌روزرسانی، و قیمت ماهانه.", + "", + "| داده | نرخ لازم | توضیح | دارید؟ | نرخ به‌روزرسانی | قیمت |", + "|---|---|---|---|---|---|", + "| قیمت پایه سهام و صندوق‌ها | ۱ تا ۵ دقیقه | همهٔ نمادهای بورس و فرابورس | | | |", + "| قیمت قراردادهای آتی | ۱ تا ۵ دقیقه | کالا و اوراق | | | |", + "| قیمت اعمال و پرمیوم اختیار خرید و فروش | ۱ تا ۵ دقیقه | همهٔ سررسیدها | | | |", + "| بهترین سفارش خرید و فروش | ۱ تا ۵ دقیقه | برای محاسبهٔ اسپرد و نقدشوندگی | | | |", + "| سری روزانهٔ قیمت پایانی | روزانه | تاریخچهٔ حداقل ۱۲ ماه برای پس‌آزمایی | | | |", + "| حجم و ارزش معاملات | روزانه | برای فیلتر نقدشوندگی | | | |", + "| وضعیت نماد (باز، متوقف) | روزانه | برای جلوگیری از تصمیم روی نماد بسته | | | |", + "", + "## پرسش‌های فنی", + "", + "۱. قالب دسترسی: REST یا websocket؟ مسیر JSON پاسخ به چه شکل است؟", + "۲. احراز هویت: کلید در نشانی یا در هدر؟ محدودیت تعداد درخواست در دقیقه چقدر است؟", + "۳. پایداری: ساعت کاری و قطعی‌های معمول؛ در صورت قطع، داده دوباره پر می‌شود؟", + "۴. پرداخت: ریالی؟ فاکتور رسمی؟ دورهٔ زمانی و شرایط لغو؟", + "۵. اجازهٔ استفاده: آیا استفاده در یک سامانهٔ تحلیل و تصمیم‌یار مجاز است؟", + "", + "## یادآوری برای خودم", + "", + "- وجه تضمین را هیچ فروشندهٔ داده‌ای ندارد؛ از سامانهٔ کارگزاری برداشته می‌شود (۶۰ ثانیه در روز).", + "- تا وقتی کارنامهٔ آزمون «آماده» نشود، خرید داده معنی ندارد: اول باید ببینم موتور روزانه فرصت پیدا می‌کند.", + "- پیش از امضا، قالب نشانی فروشنده را در گام ۲ ایستگاه می‌گذارم و «آزمایش اتصال» می‌زنم.", + ""] + return "\n".join(lines) + + +def build_report(result: dict, matrix: list[dict], ws: dict | None = None, + path: Path | None = None) -> Path: + out = Path(path or (DATA / "data-feasibility.html")) + out.parent.mkdir(parents=True, exist_ok=True) + rows = "".join( + f'{rk.esc(i["label"])}' + f'{"✅" if i["ok"] else "✗"} {rk.esc(i["reason"])}' + f'{rk.esc(i.get("latency_ms", 0))}' + f'{rk.esc(i.get("http", ""))}' + f'{rk.esc(", ".join(i.get("top_keys") or []) or "—")}' + for i in result["items"]) + stability = "".join( + f'{rk.esc(s["name"])}{rk.esc(s.get("verdict", "سنجیده نشد"))}' + f'{rk.esc(s.get("note", s.get("reason", "")))}' for s in result.get("stability", [])) + mrows = "".join( + f'{rk.esc(m["route"])}{rk.esc(m["gives"])}{rk.esc(m["misses"])}' + f'{rk.esc(m["cost"])}{rk.esc(m["verdict"])}{rk.esc(m["test"])}' + for m in matrix) + needs = "".join(f'{rk.esc(n["field"])}{rk.esc(n["freq"])}' + f'{rk.esc(n["route"])}' for n in NEEDS) + ws_block = "" + if ws: + ws_block = (f'

    سنجش پوش لحظه‌ای

    ' + f'' + f'' + f'' + f'' + f'' + f'
    نشانی{rk.esc(ws.get("url", ""))}
    اتصال TCP{"بله" if ws.get("tcp") else "نه"}
    لایهٔ امن (TLS){"بله" if ws.get("tls") else "نه"}
    کد پاسخ ارتقا{rk.esc(ws.get("status") or "—")}
    داوری{rk.esc(ws.get("verdict", ""))}
    توضیح{rk.esc(ws.get("note", ""))}
    ') + body = [ + '
    این سنجش چه می‌گوید و چه نمی‌گوید. می‌گوید کدام نشانی جواب می‌دهد، ' + 'چقدر طول می‌کشد، و کدام میدان دادهٔ موتور از آن درمی‌آید. نمی‌گوید سود می‌دهد یا نه؛ ' + 'و اگر از بیرون ایران اجرا شود، نبود دسترسی به سامانه‌های ایرانی را باید صریح گزارش کند، نه اینکه ' + 'آن را به‌حساب «خرابی سرویس» بگذارد.
    ', + f'

    زمان اجرا: {rk.esc(result["ran_at"])} · نماد: {rk.esc(result["symbol"])} · ' + f'کد نماد: {rk.esc(result["code"] or "—")} · میزبان: {rk.esc(result["host"])}

    ', + '

    ۱. نیاز واقعی موتور

    ', + '' + + needs + '
    دادههر چند وقتاز کدام مسیر
    ', + '

    ۲. سنجش سرویس‌های رایگان سایت مرجع

    ', + '' + '' + rows + '
    نقطهٔ پایانینتیجهمیلی‌ثانیهHTTPکلیدهای پاسخ
    ', + f'

    {rk.esc(result["verdict"])}

    ', + '

    ۳. گپ زمانی: دو فراخوانی پشت‌سرهم

    ', + '' + + stability + '
    نقطهٔ پایانیداوریتوضیح
    ', + ws_block, + '

    ۴. داوری سه مسیر

    ', + '' + '' + mrows + '
    مسیرچه می‌دهدچه نداردهزینهداوریآزمون
    ', + ] + if result.get("fixture"): + body.insert(1, '
    توجه: این اجرا روی دادهٔ ساختگی محلی انجام شده است ' + 'تا شکل خروجی دیده شود؛ نتیجه‌اش دربارهٔ سرویس‌های واقعی چیزی نمی‌گوید.
    ') + out.write_text(rk.page("امکان‌سنجی مسیرهای داده — پیش از خرید", "".join(body), + subtitle=f"نسخهٔ {VERSION} · {len(result['items'])} نشانی سنجیده شد"), + encoding="utf-8") + return out + + +# ---------------------------------------------------------------- خط فرمان +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description=f"امکان‌سنجی مسیرهای داده — نسخه {VERSION}") + ap.add_argument("--all", action="store_true", help="سنجش همهٔ نقاط پایانی رایگان") + ap.add_argument("--symbol", default="فولاد", help="نام نماد برای سنجش") + ap.add_argument("--code", default="", help="کد نماد (insCode) اگر می‌دانید") + ap.add_argument("--host", default="", help="میزبان جایگزین (پیش‌فرض: cdn.tsetmc.com)") + ap.add_argument("--ws", default="", help="نشانی پوش لحظه‌ای برای سنجش، مثل wss://host/path") + ap.add_argument("--ws-token", default="", help="توکن پوش لحظه‌ای (اگر دارید)") + ap.add_argument("--fixture", action="store_true", help="اجرای آزمایشی روی سرور نمونهٔ محلی (دادهٔ ساختگی)") + ap.add_argument("--sheet", action="store_true", help="نوشتن برگهٔ نیاز داده برای فروشنده") + ap.add_argument("--timeout", type=float, default=12.0, help="مهلت هر درخواست (ثانیه)") + ap.add_argument("--no-stability", action="store_true", help="سنجش دو فراخوانی را انجام نده") + ap.add_argument("--json", action="store_true", help="خروجی ماشین‌خوان") + ap.add_argument("--version", action="version", version=VERSION) + args = ap.parse_args(argv) + + if args.sheet: + out = DATA / "data-requirement-sheet.md" + out.parent.mkdir(parents=True, exist_ok=True) + out.write_text(requirement_sheet(), encoding="utf-8") + print("برگهٔ نیاز داده نوشته شد:", out) + return 0 + + httpd = None + host = args.host + fixture = bool(args.fixture) + if fixture: + httpd, host = start_fixture() + # در حالت ماشین‌خوان، این پیام نباید خروجی JSON را آلوده کند + print(f"سرور نمونهٔ محلی روی {host} بالا آمد (دادهٔ ساختگی).", + file=sys.stderr if args.json else sys.stdout) + + result = probe_all(symbol=args.symbol, code=args.code, host=host, timeout=args.timeout, + with_stability=not args.no_stability) + result["fixture"] = fixture + ws = probe_ws(args.ws) if args.ws else None + if ws and not ws.get("ok") and args.ws_token: + ws["real_read"] = real_ws_read(args.ws, token=args.ws_token) + report = build_report(result, build_matrix(), ws) + if httpd: + httpd.shutdown() + + if args.json: + print(json.dumps({"result": result, "ws": ws, "matrix": build_matrix()}, ensure_ascii=False, indent=2)) + return 0 + print(f"سنجش مسیرهای داده — نماد {result['symbol']} · کد {result['code'] or '—'}") + print("-" * 78) + for item in result["items"]: + mark = "✓" if item["ok"] else "✗" + print(f"[{mark}] {item['label']}: {item['reason']} · {item.get('latency_ms', 0)} میلی‌ثانیه" + + (f" · میدان‌های یافته: {item['count']}" if item["ok"] else "")) + for s in result.get("stability", []): + if s.get("checked"): + print(f" · دو فراخوانی {s['name']}: {s['verdict']} — {s['note']}") + print("-" * 78) + print(result["verdict"]) + if ws: + print(f"پوش لحظه‌ای: {ws['verdict']} — {ws['note']}") + print("گزارش:", report) + return 0 if result["summary"]["ok"] >= 3 else 1 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/station/datafeed.py b/station/datafeed.py new file mode 100644 index 0000000000000000000000000000000000000000..6360b3e268795160b87e39ca78cc6b9e0e3987e5 --- /dev/null +++ b/station/datafeed.py @@ -0,0 +1,671 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""لایهٔ دادهٔ ایستگاه — سه حالت: نمونه، فایل دستی، و دادهٔ زندهٔ واقعی. + +هدف: یک ساختار یکسان (اسنپ‌شات بازار) از سه مسیر مختلف، تا بقیهٔ برنامه +(موتور ریاضی، دروازه‌های ریسک، داشبورد) هیچ‌وقت نفهمد داده از کجا آمده است. + +حالت‌ها: + sim → دادهٔ نمونهٔ همراهِ برنامه (برای آموزش و نمایش بدون هیچ هزینه) + file → پروندهٔ JSON که خودتان از سامانهٔ کارگزاری یا هر منبعی پر می‌کنید + live → قیمت زندهٔ واقعی از یک وب‌سرویس؛ با «قالب نشانی» و «مسیر JSON» + که در همان صفحهٔ رابط گرافیکی تنظیم می‌شود (بدون نیاز به کدنویسی) + +اصل طراحی: هیچ نشانی‌ای در کد ثابت نشده است. همهٔ نشانی‌ها قالب‌اند و در +`config.json` یا در رابط گرافیکی وارد می‌شوند؛ اگر سرویس‌دهنده نشانی‌اش را +عوض کند، فقط همان قالب را ویرایش می‌کنید. +""" +from __future__ import annotations + +import csv +import errno +import json +import socket +import sqlite3 +import time +import urllib.error +import urllib.parse +import urllib.request +from dataclasses import dataclass, field +from datetime import datetime, timezone +from pathlib import Path + +VERSION = "0.1.0" +BASE = Path(__file__).resolve().parent +DESK_DIR = (BASE.parent / "desk").resolve() +KODAL_DIR = (BASE.parent / "kodal-alert").resolve() +CACHE_DIR = BASE / "data" / "cache" + +def coerce_row_numbers(row: dict) -> dict: + """عددهای رشته‌ای را به عدد تبدیل می‌کند (مثل «21,500» یا "21500"). + + کاربر تازه‌کار معمولاً عدد را داخل گیومه می‌گذارد؛ بدون این کار، موتور ریاضی + آن ردیف را با خطا رد می‌کند. این تابع پرونده‌های دستی را قابل‌استفاده می‌کند. + """ + for k in SNAPSHOT_NUM_FIELDS: + v = row.get(k) + if isinstance(v, str): + txt = v.strip().replace(",", "").replace("٬", "") + if txt == "": + continue + try: + row[k] = float(txt) + except ValueError: + pass + return row + + +# ---------------------------------------------------------------- کارت راهنمای خرید داده +# هزینه‌ها «تقریبی و نیازمند تأیید در سایت فروشنده» هستند؛ هیچ عددی اینجا قطعی نیست. +SOURCE_CARDS: dict[str, dict] = { + "sim": { + "label": "دادهٔ نمونهٔ همراه برنامه (بدون هزینه)", + "cost": "رایگان", + "gives": "همهٔ فیلدها: قیمت پایه، آتی، زنجیرهٔ آپشن، تبعی، وجه تضمین", + "after": "همهٔ فیلدها را دستی وارد می‌کنید؛ سیستم کار می‌کند ولی تصمیم روی دادهٔ ساختگی است و برای شرکت قابل ارائه نیست.", + "how": "هیچ کاری لازم نیست؛ همین حالا با دکمهٔ بعد بروید.", + }, + "file": { + "label": "پروندهٔ دستی JSON (بدون هزینه)", + "cost": "رایگان", + "gives": "هر فیلدی که خودتان وارد کنید", + "after": "داده به‌روز نمی‌شود؛ ستون تازگی داده زرد می‌ماند و باید هر روز پرونده را عوض کنید. برای شروع و برای راستی‌آزمایی شرکت کافی است.", + "how": "یک پروندهٔ JSON با قالب نمونه بسازید (راهنما در گام ۲) و مسیرش را بدهید.", + }, + "live": { + "label": "وب‌سرویس داده (ابزار خریدنی؛ توصیهٔ من برای دادهٔ زندهٔ واقعی)", + "cost": "بسته به سرویس‌دهنده؛ معمولاً از چند صد هزار تومان در ماه شروع می‌شود — قیمت را در سایت فروشنده تأیید کنید", + "gives": "قیمت زندهٔ سهم و صندوق، ریزمعاملات، و در بعضی سرویس‌ها دادهٔ تاریخی", + "after": "قیمت پایه هر ۲۰ تا ۶۰ ثانیه خودکار به‌روز می‌شود، ستون تازگی داده سبز می‌شود، و پس‌آزمایی روی دادهٔ واقعی تاریخ ممکن می‌شود. وجه تضمین و مشخصات قرارداد همچنان دستی می‌ماند چون از سامانهٔ کارگزاری می‌آید.", + "how": "۱) از سرویس‌دهندهٔ ایرانی کلید بگیرید. ۲) در همین گام، کلید و «قالب نشانی» و «مسیر JSON» را پر کنید. ۳) دکمهٔ آزمایش اتصال.", + }, +} + +SNAPSHOT_TEMPLATE: dict = { + "note": ("این یک قالب است، نه دادهٔ واقعی. عددهای هر ردیف را با عدد امروزِ سامانهٔ کارگزاری " + "خودتان عوض کنید و پرونده را با نام خودتان ذخیره کنید (مثلاً daily-input.json)."), + "_units": ("hurdle و spread_pct کسری‌اند (0.39 یعنی ۳۹٪ و 0.005 یعنی ۰.۵٪) · capital به ریال · " + "days = روزهای مانده تا سررسید · prices به ریال · margin_per_contract = وجه تضمین " + "هر قرارداد (سهم در این قالب: ارزش یک سهم) · liquidity_contracts_per_day = حجم قرارداد روز"), + "_fields_per_kind": { + "basis": ["spot", "future", "days"], + "covered_call": ["spot", "strike", "premium", "days"], + "tabei": ["stock_price", "put_price", "strike", "days"], + "box": ["call_low", "put_low", "call_high", "put_high", "strike_low", "strike_high", "days"], + "parity": ["call", "put", "spot", "strike", "days"], + }, + "as_of": "تاریخ امروز", + "hurdle": 0.39, + "capital": 20000000000, + "rows": [ + {"symbol": "اهرم", "kind": "basis", "spot": 20000, "future": 22800, "days": 90, + "storage_annual": 0.0, "margin_per_contract": 20000000, "unit": "قرارداد", + "liquidity_contracts_per_day": 900, "spread_pct": 0.005}, + {"symbol": "فولاد", "kind": "covered_call", "spot": 7000, "strike": 7600, "premium": 400, + "days": 45, "margin_per_contract": 7000, "unit": "سهم", + "liquidity_contracts_per_day": 160, "spread_pct": 0.018}, + {"symbol": "کگل", "kind": "tabei", "stock_price": 9800, "put_price": 40, "strike": 14210, + "days": 365, "margin_per_contract": 9840, "unit": "سهم", + "liquidity_contracts_per_day": 240, "spread_pct": 0.02}, + {"symbol": "شپنا", "kind": "box", "call_low": 300, "put_low": 430, "call_high": 175, + "put_high": 585, "strike_low": 1200, "strike_high": 1500, "days": 45, + "margin_per_contract": 250000, "unit": "قرارداد", + "liquidity_contracts_per_day": 12, "spread_pct": 0.045}, + {"symbol": "وبملت", "kind": "parity", "call": 420, "put": 380, "spot": 9000, "strike": 9000, + "days": 30, "rate": 0.39, "margin_per_contract": 9000, "unit": "سهم", + "liquidity_contracts_per_day": 80, "spread_pct": 0.02}, + ], +} + +DEFAULT_LIVE_CONFIG: dict = { + "url_template": "", # مثال: https://api.example.ir/Quote.php?key={key}&l18={symbol} + "json_path": "data.0.pl", # مسیر رسیدن به «قیمت پایه» داخل پاسخ JSON + "key_header": "", # اگر کلید باید در هدر برود، نام هدر را بنویسید + "key_query_name": "key", # اگر کلید در نشانی می‌رود، نام پارامتر + "timeout_seconds": 12, + "retries": 1, + "cache_seconds": 30, + "field_map": { # کدام کلید اسنپ‌شات از کدام فیلد بازار پر شود + "spot": "spot", + "stock_price": "stock_price", + "future": "future", + }, +} + + +# ---------------------------------------------------------------- ابزارها +def now_iso() -> str: + return datetime.now(timezone.utc).isoformat(timespec="seconds") + + +def log(msg: str) -> None: + print(msg) + + +def transient_error(exc: BaseException) -> bool: + """آیا این خطای شبکه «گذرا» است (ارزش تلاش دوباره دارد) یا قطعی؟""" + if isinstance(exc, urllib.error.HTTPError): + return exc.code >= 500 or exc.code in (408, 429) + reason = getattr(exc, "reason", exc) + if isinstance(reason, socket.gaierror): + return False + if isinstance(reason, ConnectionRefusedError): + return False + if getattr(reason, "errno", None) in (errno.ECONNREFUSED, errno.EHOSTUNREACH, errno.ENETUNREACH, + errno.EADDRNOTAVAIL): + return False + return True + + +def fetch(url: str, *, timeout: float = 12, retries: int = 1, + key_header: str = "", key: str = "", cache_name: str | None = None, + cache_seconds: int = 30, use_cache: bool = True, + stale_ok: bool = True) -> tuple[str | None, str]: + """دریافت متن با تلاش مجدد و حافظهٔ نهان. خروجی: (متن یا None، پیام وضعیت). + + stale_ok=False یعنی «اگر شبکه جواب نداد، از حافظهٔ نهان نخوان»؛ این پرچم برای جاهایی + است که خواندن از حافظهٔ کهنه، «موفقیت دروغین» می‌سازد (سنجش منبع، کاوش پاسخ سرویس). + هر جا از حافظهٔ نهان خوانده شود، در پیام وضعیت صریح نوشته می‌شود. + """ + url = ascii_safe_url(url) + if url.startswith("file:"): + try: + return Path(url[5:]).read_text(encoding="utf-8-sig"), "از پروندهٔ محلی خوانده شد" + except OSError as e: + return None, f"خواندن پرونده ممکن نشد: {e}" + CACHE_DIR.mkdir(parents=True, exist_ok=True) + cache_file = CACHE_DIR / (cache_name or "last.json") + if use_cache and cache_file.exists() and cache_seconds > 0: + age = time.time() - cache_file.stat().st_mtime + if age < cache_seconds: + return cache_file.read_text(encoding="utf-8"), f"از حافظهٔ نهان ({int(age)} ثانیه پیش)" + headers = {"User-Agent": "IranDeskStation/0.1 (+local)"} + if key_header and key: + headers[key_header] = key + req = urllib.request.Request(url, headers=headers) + last_err = "" + for attempt in range(1, retries + 2): + try: + with urllib.request.urlopen(req, timeout=timeout) as resp: + body = resp.read().decode("utf-8", errors="replace") + cache_file.write_text(body, encoding="utf-8") + return body, f"دریافت تازه در تلاش {attempt}" + except (urllib.error.URLError, urllib.error.HTTPError, TimeoutError, OSError) as e: + last_err = f"{type(e).__name__}: {e}" + # خطای گذرا: مکث و تلاش دوباره. خطای قطعی (سرویس خاموش، نام دامنهٔ نادرست، + # ۴۰۴/۴۰۱) را نباید مکث کرد؛ وگرنه هر نماد ۱٫۵ ثانیه بی‌دلیل منتظر می‌ماند. + if attempt > retries or not transient_error(e): + break + time.sleep(min(1.0 * attempt, 3.0)) + if stale_ok and cache_file.exists(): + age = int(time.time() - cache_file.stat().st_mtime) + return (cache_file.read_text(encoding="utf-8"), + f"از حافظهٔ نهان {age} ثانیه‌ای استفاده شد، نه از شبکه ({last_err})") + return None, f"دریافت ناموفق: {last_err}" + + +def dig(data, path: str): + """مسیر نقطه‌ای مثل data.0.pl را در ساختار JSON دنبال می‌کند.""" + cur = data + for part in [p for p in path.split(".") if p != ""]: + if isinstance(cur, list): + try: + cur = cur[int(part)] + except (ValueError, IndexError): + return None + elif isinstance(cur, dict): + if part not in cur: + return None + cur = cur[part] + else: + return None + return cur + + +# ---------------------------------------------------------------- نتیجهٔ اسنپ‌شات +@dataclass +class Snapshot: + rows: list[dict] = field(default_factory=list) + mode: str = "sim" + source_label: str = "" + as_of: str = "" + fetched_at: str = "" + freshness_seconds: float | None = None + status: str = "ok" # ok | partial | failed + messages: list[str] = field(default_factory=list) + missing_fields: list[str] = field(default_factory=list) + live_prices: dict[str, float] = field(default_factory=dict) + + @property + def freshness_label(self) -> str: + if self.freshness_seconds is None: + return "نامعلوم" + s = int(self.freshness_seconds) + if s < 90: + return f"زنده ({s} ثانیه پیش)" + if s < 3600: + return f"نسبتاً تازه ({s // 60} دقیقه پیش)" + if s < 86400: + return f"کهنه ({s // 3600} ساعت پیش)" + return f"تاریخی ({s // 86400} روز پیش)" + + def to_dict(self) -> dict: + return {"as_of": self.as_of, "hurdle": self.rows[0].get("_hurdle", 0.39), + "capital": self.rows[0].get("_capital", 0), "rows": self.rows} + + +# ---------------------------------------------------------------- بارگذاری‌ها +def load_snapshot_file(path: str | Path) -> Snapshot: + p = Path(path) + if not p.exists(): + return Snapshot(status="failed", mode="file", source_label="پروندهٔ دستی", + messages=[f"پروندهٔ اسنپ‌شات پیدا نشد: {p}"]) + try: + data = json.loads(p.read_text(encoding="utf-8-sig")) + except json.JSONDecodeError as e: + return Snapshot(status="failed", mode="file", source_label="پروندهٔ دستی", + messages=[f"پروندهٔ JSON خوانده نشد: {e}"]) + rows = [coerce_row_numbers(r) for r in (data.get("rows") or []) if isinstance(r, dict)] + missing: list[str] = [] + for i, r in enumerate(rows): + for k in ("symbol", "kind"): + if not r.get(k): + missing.append(f"ردیف {i + 1}: «{k}» خالی است") + hurdle = float(data.get("hurdle", 0.39)) + capital = float(data.get("capital", 0)) + for r in rows: + r["_hurdle"] = hurdle + r["_capital"] = capital + return Snapshot(rows=rows, mode="file", source_label=f"پروندهٔ دستی: {p.name}", + as_of=str(data.get("as_of", "")), fetched_at=now_iso(), + freshness_seconds=time.time() - p.stat().st_mtime, + status="ok" if rows and not missing else ("partial" if rows else "failed"), + messages=[f"{len(rows)} ردیف خوانده شد"] + missing, + missing_fields=missing) + + +def demo_snapshot() -> Snapshot: + snap = load_snapshot_file(DESK_DIR / "market-demo.json") + snap.mode = "sim" + snap.source_label = "دادهٔ نمونه (ساختگی)" + snap.messages.append("هشدار: اعداد این اسنپ‌شات ساختگی‌اند و قیمت واقعی بازار نیستند.") + snap.freshness_seconds = None + return snap + + +def numeric_paths(payload, *, max_items: int = 40, max_depth: int = 6) -> list[tuple[str, float]]: + """مسیرهای عددی داخل یک پاسخ JSON را پیدا می‌کند تا «مسیر JSON» را حدس نزنیم. + + خروجی: فهرست (مسیر، مقدار) مثل ("data.0.pl", 20150.0) + """ + out: list[tuple[str, float]] = [] + + def walk(node, prefix: str, depth: int) -> None: + if len(out) >= max_items or depth > max_depth: + return + if isinstance(node, dict): + for k, v in node.items(): + walk(v, f"{prefix}.{k}" if prefix else str(k), depth + 1) + elif isinstance(node, list): + for i, v in enumerate(node[:8]): + walk(v, f"{prefix}.{i}" if prefix else str(i), depth + 1) + else: + if isinstance(node, bool) or node is None: + return + if isinstance(node, (int, float)): + out.append((prefix, float(node))) + elif isinstance(node, str): + txt = node.strip().replace(",", "") + try: + out.append((prefix, float(txt))) + except ValueError: + return + + walk(payload, "", 0) + return out + + +def parse_quote_payload(text: str, json_path: str, symbol: str) -> tuple[float | None, str]: + """قیمت را از پاسخ سرویس بیرون می‌کشد. برای هر سرویس، فقط مسیر JSON عوض می‌شود.""" + try: + data = json.loads(text) + except json.JSONDecodeError: + # بعضی سرویس‌ها متن ساده یا CSV برمی‌گردانند + for token in reversed(text.replace(";", ",").replace("|", ",").split(",")): + token = token.strip() + if token and all(c.isdigit() or c in ".-" for c in token): + try: + return float(token), "مقدار از متن ساده استخراج شد (مسیر JSON نادیده گرفته شد)" + except ValueError: + continue + return None, "پاسخ JSON نبود و عددی هم پیدا نشد" + value = dig(data, json_path) if json_path else None + if value is None and isinstance(data, dict): + for k in ("pl", "plc", "price", "last", "close", "pDrCotVal", "lastPrice"): + if k in data: + value = data[k] + break + if value is None: + return None, f"مسیر «{json_path}» در پاسخ پیدا نشد" + try: + return float(str(value).replace(",", "").strip()), "قیمت خوانده شد" + except ValueError: + return None, f"مقدار «{value}» عدد نبود" + + +def finish_live(snap: Snapshot, prices: dict, *, stale_count: int = 0, fail_count: int = 0) -> Snapshot: + """قیمت‌های خوانده‌شده را روی اسنپ‌شات می‌نشاند، سنجهٔ صداقت را می‌گذارد و برچسب می‌زند. + + این تابع از مسیر زندهٔ خودِ برنامه و از «برگهٔ شاهد زنده» (demo_day) یکسان صدا زده می‌شود تا + عددی که در برگهٔ شاهد چاپ می‌شود، دقیقاً همان عددی باشد که برنامه رویش تصمیم می‌گیرد. + """ + ok_count = len(prices) + for row in snap.rows: + symbol = str(row.get("symbol", "")).strip() + if symbol not in prices: + continue + for target in ("spot", "stock_price"): + if isinstance(row.get(target), (int, float)): + # قیمت پایه/سهم با قیمت زنده جابه‌جا می‌شود؛ آتی و مشخصات قرارداد دست‌نخورده می‌ماند. + row[f"{target}_manual"] = row[target] + row[target] = prices[symbol] + snap.live_prices = prices + snap.fetched_at = now_iso() + # تازگی فقط وقتی معنا دارد که قیمت از «شبکه» آمده باشد؛ خواندن از حافظهٔ نهان + # نباید «زندهٔ ۰ ثانیه پیش» جا بزند. + snap.freshness_seconds = 0.0 if (prices and not stale_count) else None + if stale_count: + snap.messages.append(f"{stale_count} نماد از حافظهٔ نهان خوانده شد، نه از شبکه؛ " + f"این عددها قیمت زنده نیستند و برچسب «از حافظهٔ نهان» می‌گیرند.") + snap.source_label = f"{snap.source_label} (از حافظهٔ نهان)" + if snap.status == "ok": + snap.status = "partial" + # سنجهٔ صداقت: اگر قیمت چند نماد عیناً یکی باشد، یعنی این منبع «نرخ واحد» می‌دهد، + # نه قیمت هر نماد. آن‌وقت محاسبهٔ سهام بی‌معنی است و باید بگوییم. + if len(prices) >= 2 and len(set(prices.values())) == 1: + snap.status = "partial" + snap.messages.append("قیمت چند نماد عیناً یکسان آمد؛ یعنی این منبع یک «نرخ واحد» می‌دهد " + "(مثل نرخ ارز)، نه قیمت هر نماد. برای محاسبهٔ سهام، منبع نمادی " + "یا پروندهٔ دستی کارگزاری لازم است — به عددهای زیر استناد نکنید.") + snap.source_label = f"{snap.source_label} (نرخ واحد، نه نماد)" + return snap + if ok_count and not fail_count: + snap.status = "ok" + snap.messages.append(f"قیمت زندهٔ {ok_count} نماد به‌روز شد.") + elif ok_count: + snap.status = "partial" + snap.messages.append(f"قیمت {ok_count} نماد به‌روز شد و {fail_count} نماد نیامد.") + else: + snap.status = "failed" + snap.messages.append("هیچ قیمتی از سرویس نیامد؛ قالب نشانی و مسیر JSON را بررسی کنید.") + return snap + + +def live_snapshot(base: Snapshot | dict, live_cfg: dict, *, key: str = "", + allow_network: bool = True, progress=None) -> Snapshot: + """قیمت‌های زنده را روی یک اسنپ‌شات پایه می‌نشاند. + + دادهٔ پایه (مشخصات قرارداد، وجه تضمین، تعداد روز) از پرونده می‌آید؛ + قیمت‌ها از سرویس. این تفکیک عمدی است: وجه تضمین فقط از کارگزاری می‌آید. + """ + def say(m: str) -> None: + if progress: + progress(m) + log(m) + + if isinstance(base, Snapshot): + snap = base + else: + snap = load_snapshot_file(base) + snap.mode = "live" + url_tpl = (live_cfg.get("url_template") or "").strip() + # صداقت برچسب: اگر نشانی روی همین رایانه باشد، داده ساختگی است، نه بازار واقعی. + local_feed = any(h in url_tpl for h in ("127.0.0.1", "localhost", "0.0.0.0", "::1")) + snap.source_label = "خوراک آزمایشی محلی (ساختگی)" if local_feed else "دادهٔ زندهٔ وب‌سرویس" + if not url_tpl: + snap.status = "failed" + snap.messages.append("قالب نشانی خالی است؛ در همین صفحه نشانی سرویس را وارد کنید.") + return snap + if not allow_network: + snap.status = "failed" + snap.messages.append("دسترسی شبکه در این اجرا بسته است.") + return snap + + prices: dict[str, float] = {} + ok_count, fail_count, stale_count = 0, 0, 0 + for row in snap.rows: + symbol = str(row.get("symbol", "")).strip() + if not symbol: + continue + # feed_symbol اجازه می‌دهد در نشانی به‌جای نام نماد، «کد نماد» (insCode) برود + url_symbol = str(row.get("feed_symbol") or symbol).strip() + url = url_tpl.replace("{symbol}", urllib.parse.quote(url_symbol)) + if live_cfg.get("key_query_name"): + url = url.replace("{key}", urllib.parse.quote(key)) if "{key}" in url_tpl else url + if "{key}" in url: + url = url.replace("{key}", urllib.parse.quote(key)) + text, status = fetch(url, timeout=float(live_cfg.get("timeout_seconds", 12)), + retries=int(live_cfg.get("retries", 1)), + key_header=live_cfg.get("key_header", ""), key=key, + cache_name=f"quote-{symbol}.json", + cache_seconds=int(live_cfg.get("cache_seconds", 30))) + if not text: + fail_count += 1 + say(f"قیمت {symbol} نیامد: {status}") + continue + if "حافظهٔ نهان" in status: + stale_count += 1 + say(f"قیمت {symbol} از حافظهٔ نهان آمد، نه از شبکه") + value, why = parse_quote_payload(text, live_cfg.get("json_path", ""), symbol) + if value is None: + fail_count += 1 + say(f"قیمت {symbol} خوانده نشد: {why}") + continue + prices[symbol] = value + ok_count += 1 + say(f"قیمت زندهٔ {symbol}: {value:,.0f}") + + return finish_live(snap, prices, stale_count=stale_count, fail_count=fail_count) + if ok_count and not fail_count: + snap.status = "ok" + snap.messages.append(f"قیمت زندهٔ {ok_count} نماد به‌روز شد.") + elif ok_count: + snap.status = "partial" + snap.messages.append(f"قیمت {ok_count} نماد به‌روز شد و {fail_count} نماد نیامد.") + else: + snap.status = "failed" + snap.messages.append("هیچ قیمتی از سرویس نیامد؛ قالب نشانی و مسیر JSON را بررسی کنید.") + return snap + + +def build_snapshot(mode: str, *, file_path: str | Path | None = None, live_cfg: dict | None = None, + key: str = "", allow_network: bool = True, progress=None) -> Snapshot: + """دروازهٔ یکسان برای همهٔ حالت‌ها (همان چیزی که رابط گرافیکی صدا می‌زند).""" + if mode == "sim": + return demo_snapshot() + if mode == "file": + if not file_path: + return Snapshot(status="failed", mode="file", messages=["مسیر پرونده داده نشده است."]) + return load_snapshot_file(file_path) + if mode == "live": + base = load_snapshot_file(file_path) if file_path else demo_snapshot() + return live_snapshot(base, live_cfg or DEFAULT_LIVE_CONFIG, key=key, + allow_network=allow_network, progress=progress) + return Snapshot(status="failed", mode=mode, messages=[f"حالت دادهٔ ناشناخته: {mode}"]) + + +# ---------------------------------------------------------------- خواندن هشدارهای کدال +def read_alerts(kodal_db: str | Path, min_score: int = 60, limit: int = 50) -> list[dict]: + p = Path(kodal_db) + if not p.exists(): + return [] + try: + conn = sqlite3.connect(f"file:{p}?mode=ro", uri=True) + rows = conn.execute( + "SELECT title, symbol, category, direction, score, url FROM items " + "WHERE score >= ? ORDER BY score DESC LIMIT ?", (min_score, limit)).fetchall() + conn.close() + except sqlite3.Error: + return [] + return [{"title": t, "symbol": s, "category": c, "direction": d, "score": sc, "url": u} + for t, s, c, d, sc, u in rows] + + +def write_snapshot_template(path: str | Path) -> Path: + """قالب اسنپ‌شات برای کاربر تازه‌کار می‌سازد.""" + p = Path(path) + p.parent.mkdir(parents=True, exist_ok=True) + p.write_text(json.dumps(SNAPSHOT_TEMPLATE, ensure_ascii=False, indent=2), encoding="utf-8") + return p + + +# ---------------------------------------------------------------- اسنپ‌شات دستی تاریخ‌دار +def ascii_safe_url(url: str) -> str: + """نشانی‌هایی که حرف فارسی دارند (مثل نام نماد) را درصد‌کد می‌کند. + + بدون این کار، کتابخانهٔ شبکه با خطای UnicodeEncodeError می‌خوابد؛ این ایراد در آزمون + «اتصال خودکار» با نام نماد فارسی پیدا شد. + """ + try: + str(url).encode("ascii") + return str(url) + except UnicodeEncodeError: + import urllib.parse as _up + return _up.quote(str(url), safe=":/?#[]@!$&'()*+,;=%") + + +SNAPSHOT_NUM_FIELDS = ("spot", "future", "strike", "premium", "stock_price", "put_price", + "days", "margin_per_contract", "liquidity_contracts_per_day", "spread_pct") +SNAPSHOT_KINDS = ("basis", "box", "tabei", "covered_call", "parity") + + +def load_snapshot_rows(path: str | Path) -> dict: + """ردیف‌های یک اسنپ‌شات را برای ویرایش در رابط گرافیکی برمی‌گرداند.""" + p = Path(path) + if not p.exists(): + return {"rows": [], "as_of": "", "hurdle": 0.39, "capital": 20_000_000_000, + "note": "پرونده‌ای نیست", "path": str(p), "exists": False} + try: + data = json.loads(p.read_text(encoding="utf-8-sig")) + except json.JSONDecodeError as e: + return {"rows": [], "as_of": "", "hurdle": 0.39, "capital": 20_000_000_000, + "note": f"پرونده خوانده نشد: {e}", "path": str(p), "exists": True} + rows = [{k: v for k, v in r.items() if not k.startswith("_")} for r in (data.get("rows") or [])] + return {"rows": rows, "as_of": str(data.get("as_of", "")), + "hurdle": float(data.get("hurdle", 0.39)), + "capital": float(data.get("capital", 20_000_000_000)), + "note": str(data.get("note", "")), "source": str(data.get("source", "")), + "confirmed": snapshot_confirmed(p), "path": str(p), "exists": True} + + +def clean_rows(raw_rows: list[dict]) -> tuple[list[dict], list[str]]: + """ردیف‌های فرم را پاکیزه می‌کند: فیلدهای خالی حذف، عددها عدد، ردیف بی‌نماد کنار گذاشته. + + خروجی: (ردیف‌های آماده، هشدارها) + """ + out: list[dict] = [] + problems: list[str] = [] + for i, r in enumerate(raw_rows or []): + if not isinstance(r, dict): + problems.append(f"ردیف {i + 1}: ساختار نامعتبر") + continue + symbol = str(r.get("symbol", "") or "").strip() + if not symbol: + continue # ردیف خالی را بی‌صدا رد می‌کنیم + kind = str(r.get("kind", "") or "basis").strip() or "basis" + if kind not in SNAPSHOT_KINDS: + problems.append(f"ردیف {i + 1} ({symbol}): نوع «{kind}» شناخته نشد؛ «basis» گذاشته شد.") + kind = "basis" + row: dict = {"symbol": symbol, "kind": kind} + for k, v in r.items(): + if k in ("symbol", "kind"): + continue + if isinstance(v, str): + v = v.strip().replace(",", "") + if v in ("", None): + continue + if k in SNAPSHOT_NUM_FIELDS: + try: + row[k] = float(v) + except (TypeError, ValueError): + problems.append(f"ردیف {i + 1} ({symbol}): «{k}» عدد نبود و کنار گذاشته شد.") + continue + row[k] = v + price_fields = ("spot", "stock_price", "future", "strike", "premium", "put_price", + "call", "put", "call_low", "call_high", "put_low", "put_high", + "strike_low", "strike_high") + if not any(isinstance(row.get(k), (int, float)) and row[k] > 0 for k in price_fields): + problems.append(f"ردیف {i + 1} ({symbol}): هیچ قیمتی وارد نشده؛ ردیف می‌ماند ولی سیگنالی نمی‌دهد.") + unit = str(r.get("feed_symbol", "") or "").strip() + if unit: + row["feed_symbol"] = unit + out.append(row) + if not out: + problems.append("هیچ ردیف درستی وارد نشد؛ حداقل یک نماد با قیمت لازم است.") + return out, problems + + +MANUAL_SOURCE = "manual-broker" + + +def snapshot_confirmed(path: str | Path | None) -> bool: + """آیا این پرونده را کاربر از سامانهٔ کارگزاری برداشته و تأیید کرده است؟ + + بدون این تأیید، پرونده «واقعی» حساب نمی‌شود؛ وگرنه هر پرونده‌ای می‌توانست روز واقعی جعل کند. + """ + if not path: + return False + p = Path(path) + if not p.exists(): + return False + try: + data = json.loads(p.read_text(encoding="utf-8-sig")) + except Exception: + return False + return str(data.get("source", "")) == MANUAL_SOURCE + + +def save_dated_snapshot(rows: list[dict], *, as_of: str | None = None, hurdle: float = 0.39, + capital: float = 20_000_000_000, note: str = "", + out_dir: str | Path | None = None, day: str | None = None, + source: str = MANUAL_SOURCE) -> Path: + """اسنپ‌شات را با تاریخ می‌نویسد: `snapshots/snapshot-YYYY-MM-DD.json`. + + چرا تاریخ‌دار؟ چون هر روز پروندهٔ خودش را می‌خواهد: هم سابقهٔ قابل ممیزی می‌شود، + هم اشتباه یک روز، روزهای دیگر را خراب نمی‌کند. + """ + clean, _ = clean_rows(rows) + if not clean: + raise ValueError("هیچ ردیف درستی برای ذخیره نبود.") + d = (Path(out_dir) if out_dir else (BASE / "data" / "snapshots")) + d.mkdir(parents=True, exist_ok=True) + stamp = day or datetime.now().strftime("%Y-%m-%d") + path = d / f"snapshot-{stamp}.json" + payload = {"as_of": as_of or datetime.now().strftime("%Y-%m-%d %H:%M"), + "hurdle": float(hurdle), "capital": float(capital), + "note": note, "source": source, "rows": clean} + path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8") + return path + + +def history_template_rows() -> list[dict]: + """سطر نمونهٔ پروندهٔ پس‌آزمایی، برای اینکه کاربر بداند چه ستون‌هایی لازم است.""" + return [ + {"date": "1405-05-01", "symbol": "اهرم", "kind": "basis", "spot": 20000, "future": 22800, + "days": 90, "margin_per_contract": 20000000, "liquidity_contracts_per_day": 900, + "spread_pct": 0.005, "hurdle": 0.39, "realized_annualized_pct": 61.0}, + ] + + +def write_history_template(path: str | Path) -> Path: + p = Path(path) + p.parent.mkdir(parents=True, exist_ok=True) + cols = ["date", "symbol", "kind", "spot", "future", "strike", "premium", "put_price", "stock_price", + "days", "margin_per_contract", "liquidity_contracts_per_day", "spread_pct", "hurdle", + "realized_annualized_pct"] + with p.open("w", encoding="utf-8", newline="") as f: + w = csv.DictWriter(f, fieldnames=cols) + w.writeheader() + for r in history_template_rows(): + w.writerow({c: r.get(c, "") for c in cols}) + return p diff --git a/station/demo/history-demo.csv b/station/demo/history-demo.csv new file mode 100644 index 0000000000000000000000000000000000000000..7dba7e05b7d8ece925f030d6b02fe24348e16f4e --- /dev/null +++ b/station/demo/history-demo.csv @@ -0,0 +1,103 @@ +# پروندهٔ تاریخ نمونه (سینتتیک) — اعداد واقعی بازار نیستند +# ستون‌ها: تاریخ · نماد · راهبرد · فیلدهای ریاضی · وجه تضمین · نقدشوندگی · اسپرد · نرخ سد · نتیجهٔ واقعی سالانه +date,symbol,kind,spot,future,strike,premium,put_price,stock_price,call,put,call_low,put_low,call_high,put_high,strike_low,strike_high,rate,days,margin_per_contract,liquidity_contracts_per_day,spread_pct,hurdle,realized_annualized_pct +1405-01-15,اهرم,basis,20000,21920,,,,,,,,,,,,,,90,20000000,900,0.005,0.33,29.8 +1405-01-15,طلا,basis,20000,21773,,,,,,,,,,,,,,60,20000000,700,0.006,0.33,44.6 +1405-01-15,فولاد,covered_call,7000,,7600,357,,,,,,,,,,,,45,7000,160,0.018,0.33,47.7 +1405-01-15,شپنا,covered_call,9000,,9600,419,,,,,,,,,,,,30,9000,90,0.02,0.33,48.2 +1405-01-15,کگل,tabei,,,14210,,40,9800,,,,,,,,,,365,9840,240,0.02,0.33,-8.3 +1405-01-15,خساپا,tabei,,,3000,,14,2500,,,,,,,,,,270,2512,320,0.012,0.33,3.8 +1405-01-15,شستا,tabei,,,1320,,8,1200,,,,,,,,,,200,1205,400,0.015,0.33,-56.8 +1405-01-15,وبملت,parity,9000,,9000,,,,638,380,,,,,,,0.39,30,9000,80,0.02,0.33,64.1 +1405-01-15,شپدیس,box,,,,,,,,,89,123,75,164,1200,1500,,45,250000,60,0.025,0.33,36.5 +1405-01-15,فملی,box,,,,,,,,,89,122,75,164,800,1100,,30,200000,45,0.022,0.33,32.4 +1405-02-15,اهرم,basis,20000,22487,,,,,,,,,,,,,,90,20000000,900,0.005,0.34,16.4 +1405-02-15,طلا,basis,20000,21651,,,,,,,,,,,,,,60,20000000,700,0.006,0.34,62.8 +1405-02-15,فولاد,covered_call,7000,,7600,355,,,,,,,,,,,,45,7000,160,0.018,0.34,39.8 +1405-02-15,شپنا,covered_call,9000,,9600,435,,,,,,,,,,,,30,9000,90,0.02,0.34,69.3 +1405-02-15,کگل,tabei,,,14210,,34,9800,,,,,,,,,,365,9840,240,0.02,0.34,50.9 +1405-02-15,خساپا,tabei,,,3000,,14,2500,,,,,,,,,,270,2512,320,0.012,0.34,42.1 +1405-02-15,شستا,tabei,,,1320,,5,1200,,,,,,,,,,200,1205,400,0.015,0.34,65.4 +1405-02-15,وبملت,parity,9000,,9000,,,,641,380,,,,,,,0.39,30,9000,80,0.02,0.34,25.8 +1405-02-15,شپدیس,box,,,,,,,,,89,123,75,164,1200,1500,,45,250000,60,0.025,0.34,108.0 +1405-02-15,فملی,box,,,,,,,,,89,123,75,164,800,1100,,30,200000,45,0.022,0.34,31.0 +1405-03-15,اهرم,basis,20000,22423,,,,,,,,,,,,,,90,20000000,900,0.005,0.35,-27.3 +1405-03-15,طلا,basis,20000,21899,,,,,,,,,,,,,,60,20000000,700,0.006,0.35,53.8 +1405-03-15,فولاد,covered_call,7000,,7600,351,,,,,,,,,,,,45,7000,160,0.018,0.35,45.3 +1405-03-15,شپنا,covered_call,9000,,9600,451,,,,,,,,,,,,30,9000,90,0.02,0.35,54.3 +1405-03-15,کگل,tabei,,,14210,,37,9800,,,,,,,,,,365,9840,240,0.02,0.35,31.8 +1405-03-15,خساپا,tabei,,,3000,,13,2500,,,,,,,,,,270,2512,320,0.012,0.35,31.2 +1405-03-15,شستا,tabei,,,1320,,5,1200,,,,,,,,,,200,1205,400,0.015,0.35,21.4 +1405-03-15,وبملت,parity,9000,,9000,,,,594,380,,,,,,,0.39,30,9000,80,0.02,0.35,-63.5 +1405-03-15,شپدیس,box,,,,,,,,,89,123,75,164,1200,1500,,45,250000,60,0.025,0.35,43.8 +1405-03-15,فملی,box,,,,,,,,,88,121,75,163,800,1100,,30,200000,45,0.022,0.35,27.1 +1405-04-15,اهرم,basis,20000,22883,,,,,,,,,,,,,,90,20000000,900,0.005,0.36,24.7 +1405-04-15,طلا,basis,20000,21736,,,,,,,,,,,,,,60,20000000,700,0.006,0.36,45.2 +1405-04-15,فولاد,covered_call,7000,,7600,362,,,,,,,,,,,,45,7000,160,0.018,0.36,32.4 +1405-04-15,شپنا,covered_call,9000,,9600,452,,,,,,,,,,,,30,9000,90,0.02,0.36,-16.7 +1405-04-15,کگل,tabei,,,14210,,45,9800,,,,,,,,,,365,9840,240,0.02,0.36,21.8 +1405-04-15,خساپا,tabei,,,3000,,8,2500,,,,,,,,,,270,2512,320,0.012,0.36,7.3 +1405-04-15,شستا,tabei,,,1320,,4,1200,,,,,,,,,,200,1205,400,0.015,0.36,21.4 +1405-04-15,وبملت,parity,9000,,9000,,,,643,380,,,,,,,0.39,30,9000,80,0.02,0.36,59.6 +1405-04-15,شپدیس,box,,,,,,,,,88,121,75,163,1200,1500,,45,250000,60,0.025,0.36,34.0 +1405-04-15,فملی,box,,,,,,,,,88,121,75,163,800,1100,,30,200000,45,0.022,0.36,7.8 +1405-05-15,اهرم,basis,20000,23138,,,,,,,,,,,,,,90,20000000,900,0.005,0.37,-38.7 +1405-05-15,طلا,basis,20000,21312,,,,,,,,,,,,,,60,20000000,700,0.006,0.37,17.1 +1405-05-15,فولاد,covered_call,7000,,7600,345,,,,,,,,,,,,45,7000,160,0.018,0.37,40.3 +1405-05-15,شپنا,covered_call,9000,,9600,490,,,,,,,,,,,,30,9000,90,0.02,0.37,85.7 +1405-05-15,کگل,tabei,,,14210,,44,9800,,,,,,,,,,365,9840,240,0.02,0.37,44.1 +1405-05-15,خساپا,tabei,,,3000,,12,2500,,,,,,,,,,270,2512,320,0.012,0.37,-4.6 +1405-05-15,شستا,tabei,,,1320,,6,1200,,,,,,,,,,200,1205,400,0.015,0.37,28.0 +1405-05-15,وبملت,parity,9000,,9000,,,,625,380,,,,,,,0.39,30,9000,80,0.02,0.37,15.7 +1405-05-15,شپدیس,box,,,,,,,,,87,121,75,163,1200,1500,,45,250000,60,0.025,0.37,9.8 +1405-05-15,فملی,box,,,,,,,,,88,121,75,163,800,1100,,30,200000,45,0.022,0.37,1.1 +1405-06-15,اهرم,basis,20000,22803,,,,,,,,,,,,,,90,20000000,900,0.005,0.38,32.1 +1405-06-15,طلا,basis,20000,21237,,,,,,,,,,,,,,60,20000000,700,0.006,0.38,-1.2 +1405-06-15,فولاد,covered_call,7000,,7600,356,,,,,,,,,,,,45,7000,160,0.018,0.38,31.2 +1405-06-15,شپنا,covered_call,9000,,9600,443,,,,,,,,,,,,30,9000,90,0.02,0.38,-6.4 +1405-06-15,کگل,tabei,,,14210,,57,9800,,,,,,,,,,365,9840,240,0.02,0.38,7.9 +1405-06-15,خساپا,tabei,,,3000,,14,2500,,,,,,,,,,270,2512,320,0.012,0.38,3.4 +1405-06-15,شستا,tabei,,,1320,,5,1200,,,,,,,,,,200,1205,400,0.015,0.38,16.3 +1405-06-15,وبملت,parity,9000,,9000,,,,634,380,,,,,,,0.39,30,9000,80,0.02,0.38,2.6 +1405-06-15,شپدیس,box,,,,,,,,,87,121,75,163,1200,1500,,45,250000,60,0.025,0.38,6.6 +1405-06-15,فملی,box,,,,,,,,,87,120,75,163,800,1100,,30,200000,45,0.022,0.38,58.9 +1405-07-15,اهرم,basis,20000,22792,,,,,,,,,,,,,,90,20000000,900,0.005,0.39,-34.1 +1405-07-15,طلا,basis,20000,21191,,,,,,,,,,,,,,60,20000000,700,0.006,0.39,23.4 +1405-07-15,فولاد,covered_call,7000,,7600,337,,,,,,,,,,,,45,7000,160,0.018,0.39,-22.9 +1405-07-15,شپنا,covered_call,9000,,9600,465,,,,,,,,,,,,30,9000,90,0.02,0.39,36.1 +1405-07-15,کگل,tabei,,,14210,,30,9800,,,,,,,,,,365,9840,240,0.02,0.39,6.7 +1405-07-15,خساپا,tabei,,,3000,,15,2500,,,,,,,,,,270,2512,320,0.012,0.39,19.3 +1405-07-15,شستا,tabei,,,1320,,5,1200,,,,,,,,,,200,1205,400,0.015,0.39,8.0 +1405-07-15,وبملت,parity,9000,,9000,,,,649,380,,,,,,,0.39,30,9000,80,0.02,0.39,19.9 +1405-07-15,شپدیس,box,,,,,,,,,87,121,75,163,1200,1500,,45,250000,60,0.025,0.39,-52.6 +1405-07-15,فملی,box,,,,,,,,,87,121,75,163,800,1100,,30,200000,45,0.022,0.39,-25.5 +1405-08-15,اهرم,basis,20000,23367,,,,,,,,,,,,,,90,20000000,900,0.005,0.4,29.6 +1405-08-15,طلا,basis,20000,21616,,,,,,,,,,,,,,60,20000000,700,0.006,0.4,8.0 +1405-08-15,فولاد,covered_call,7000,,7600,327,,,,,,,,,,,,45,7000,160,0.018,0.4,-50.2 +1405-08-15,شپنا,covered_call,9000,,9600,459,,,,,,,,,,,,30,9000,90,0.02,0.4,54.5 +1405-08-15,کگل,tabei,,,14210,,51,9800,,,,,,,,,,365,9840,240,0.02,0.4,52.7 +1405-08-15,خساپا,tabei,,,3000,,10,2500,,,,,,,,,,270,2512,320,0.012,0.4,29.7 +1405-08-15,شستا,tabei,,,1320,,5,1200,,,,,,,,,,200,1205,400,0.015,0.4,16.3 +1405-08-15,وبملت,parity,9000,,9000,,,,684,380,,,,,,,0.39,30,9000,80,0.02,0.4,25.9 +1405-08-15,شپدیس,box,,,,,,,,,88,121,75,163,1200,1500,,45,250000,60,0.025,0.4,40.8 +1405-08-15,فملی,box,,,,,,,,,88,122,75,164,800,1100,,30,200000,45,0.022,0.4,-16.3 +1405-09-15,اهرم,basis,20000,22597,,,,,,,,,,,,,,90,20000000,900,0.005,0.41,14.9 +1405-09-15,طلا,basis,20000,21307,,,,,,,,,,,,,,60,20000000,700,0.006,0.41,8.0 +1405-09-15,فولاد,covered_call,7000,,7600,335,,,,,,,,,,,,45,7000,160,0.018,0.41,33.2 +1405-09-15,شپنا,covered_call,9000,,9600,443,,,,,,,,,,,,30,9000,90,0.02,0.41,23.9 +1405-09-15,کگل,tabei,,,14210,,38,9800,,,,,,,,,,365,9840,240,0.02,0.41,45.8 +1405-09-15,خساپا,tabei,,,3000,,15,2500,,,,,,,,,,270,2512,320,0.012,0.41,53.7 +1405-09-15,شستا,tabei,,,1320,,4,1200,,,,,,,,,,200,1205,400,0.015,0.41,18.9 +1405-09-15,وبملت,parity,9000,,9000,,,,663,380,,,,,,,0.39,30,9000,80,0.02,0.41,64.2 +1405-09-15,شپدیس,box,,,,,,,,,87,121,75,163,1200,1500,,45,250000,60,0.025,0.41,-27.3 +1405-09-15,فملی,box,,,,,,,,,88,121,75,163,800,1100,,30,200000,45,0.022,0.41,40.4 +1405-10-15,اهرم,basis,20000,23187,,,,,,,,,,,,,,90,20000000,900,0.005,0.42,-35.9 +1405-10-15,طلا,basis,20000,21401,,,,,,,,,,,,,,60,20000000,700,0.006,0.42,53.5 +1405-10-15,فولاد,covered_call,7000,,7600,336,,,,,,,,,,,,45,7000,160,0.018,0.42,60.7 +1405-10-15,شپنا,covered_call,9000,,9600,440,,,,,,,,,,,,30,9000,90,0.02,0.42,8.4 +1405-10-15,کگل,tabei,,,14210,,36,9800,,,,,,,,,,365,9840,240,0.02,0.42,17.7 +1405-10-15,خساپا,tabei,,,3000,,14,2500,,,,,,,,,,270,2512,320,0.012,0.42,37.1 +1405-10-15,شستا,tabei,,,1320,,7,1200,,,,,,,,,,200,1205,400,0.015,0.42,20.6 +1405-10-15,وبملت,parity,9000,,9000,,,,661,380,,,,,,,0.39,30,9000,80,0.02,0.42,31.6 +1405-10-15,شپدیس,box,,,,,,,,,88,121,75,163,1200,1500,,45,250000,60,0.025,0.42,74.3 +1405-10-15,فملی,box,,,,,,,,,87,121,75,163,800,1100,,30,200000,45,0.022,0.42,19.5 diff --git a/station/demo_day.py b/station/demo_day.py new file mode 100644 index 0000000000000000000000000000000000000000..02b09d6a2e5e38944f784607128f80c5bf6342a0 --- /dev/null +++ b/station/demo_day.py @@ -0,0 +1,567 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""برگهٔ شاهد زنده — «این عدد را من تایپ نکردم؛ خودِ برنامه از سرویس خواند». + +مسئله‌ای که حل می‌کند: سرمایه‌گذار (یا کارفرما) به عددهای یک اسلاید اعتماد نمی‌کند. اینجا +برای هر عددی که برنامه رویش تصمیم می‌گیرد، سه چیز چاپ می‌شود: + + ۱) نشانی‌ای که همین حالا خوانده شد، و پاسخ خام سرویس (چند بایت اول). + ۲) اثر انگشت sha256 همان پاسخ خام؛ اگر کسی عدد را دست‌کاری کند، هش عوض می‌شود. + ۳) ساعت خواندن (UTC) و مدت خواندن؛ یعنی «الان»، نه «چند هفته پیش». + +بعد از آن، برنامه روی همان عددها یک تصمیم نمونه می‌گیرد و **حساب‌وکتابش را هم می‌نویسد** +تا با ماشین‌حساب گوشی هم بشود راستی‌آزمایی کرد. + +هزینه: صفر. با «خوراک آزمایشی محلی» هم کار می‌کند (بدون اینترنت) و با سرویس خریدنی هم. +صداقت برچسب: اگر نشانی روی همین رایانه باشد، در برگه با حروف درشت نوشته می‌شود که داده +ساختگی است و شاهد فقط «زنده‌بودن مسیر فنی» را نشان می‌دهد، نه بازار واقعی. +""" + +from __future__ import annotations + +import argparse +import hashlib +import json +import sys +import time +import urllib.parse +from datetime import datetime, timezone +from pathlib import Path + +BASE = Path(__file__).resolve().parent +if str(BASE) not in sys.path: + sys.path.insert(0, str(BASE)) + +import datafeed # noqa: E402 +import connections as conn # noqa: E402 +import investor_test as inv # noqa: E402 +import reportkit as rk # noqa: E402 + +VERSION = "0.1.0" + +DATA = BASE / "data" +EXPORT = BASE / "export" +BASE_SNAPSHOT = (BASE.parent / "desk" / "market-demo.json") +PAGE = DATA / "witness-live.html" +MD = DATA / "witness-live.md" +JSONF = DATA / "witness-live.json" + +LOCAL_HOSTS = ("127.0.0.1", "localhost", "0.0.0.0", "::1") + + +def stamps() -> tuple[str, str]: + now = datetime.now(timezone.utc).replace(microsecond=0) + return now.isoformat(), now.astimezone().strftime("%Y-%m-%d %H:%M:%S") + + +def build_url(live_cfg: dict, symbol: str, key: str) -> str: + """نشانی نهایی یک نماد را می‌سازد (همان کاری که مسیر زندهٔ برنامه می‌کند).""" + url = str(live_cfg.get("url_template") or "").replace("{symbol}", urllib.parse.quote(symbol)) + if "{key}" in url: + url = url.replace("{key}", urllib.parse.quote(key or "")) + return url + + +def _blank(symbol: str, url: str, error: str) -> dict: + return {"symbol": symbol, "url": url, "ok": False, "error": error, "sha256": "", "bytes": 0, + "latency_ms": None, "price": None, "fetched_at": stamps()[0], "snippet": "", "source": ""} + + +def probe(profile: dict, symbols: list[str], *, timeout: float = 8.0, key: str = "") -> list[dict]: + """قیمت هر نماد را زنده می‌خواند (بدون حافظهٔ نهان) و شاهد خامش را برمی‌گرداند.""" + cfg = conn.live_config(profile) + if not key: + key, _where = conn.resolve_key(profile) + out: list[dict] = [] + for symbol in symbols: + url = build_url(cfg, symbol, key) + if not url: + out.append(_blank(symbol, "", "قالب نشانی خالی است")) + continue + t0 = time.time() + text, status = datafeed.fetch(url, timeout=timeout, retries=0, + key_header=str(cfg.get("key_header") or ""), key=key, + cache_name=None, use_cache=False, stale_ok=False) + latency = int(round((time.time() - t0) * 1000)) + utc, _local = stamps() + source = ("خوراک آزمایشی محلی (ساختگی)" if any(h in url for h in LOCAL_HOSTS) + else "دادهٔ زندهٔ وب‌سرویس") + record = _blank(symbol, url, "") + record.update({"fetched_at": utc, "latency_ms": latency, "source": source}) + if not text: + record["error"] = status + out.append(record) + continue + record["sha256"] = hashlib.sha256(text.encode("utf-8")).hexdigest() + record["bytes"] = len(text.encode("utf-8")) + record["snippet"] = " ".join(text.split())[:400] + value, why = datafeed.parse_quote_payload(text, str(cfg.get("json_path") or ""), symbol) + if value is None: + record["error"] = f"عدد قیمت خوانده نشد ({why})" + else: + record["ok"] = True + record["price"] = float(value) + record["status_text"] = status + out.append(record) + return out + + +def symbols_of(path: Path | str = BASE_SNAPSHOT) -> list[str]: + """نمادهای پروندهٔ پایه — همان ردیف‌هایی که برنامه رویشان تصمیم می‌گیرد.""" + try: + snap = datafeed.load_snapshot_file(path) + except Exception: + return [] + seen, out = set(), [] + for row in snap.rows: + name = str(row.get("symbol") or "").strip() + if name and name not in seen: + seen.add(name) + out.append(name) + return out + + +def decide(probes: list[dict], *, path: Path | str = BASE_SNAPSHOT, rules: dict | None = None) -> dict: + """عددهای زنده را روی ردیف‌های پروندهٔ پایه می‌نشاند و بهترین ردیف را کامل باز می‌کند. + + عمداً همان تابع‌های خودِ ایستگاه صدا زده می‌شوند (`datafeed.finish_live`، `investor_test.solve`، + `investor_test.ladder_for`) تا عددی که در برگهٔ شاهد چاپ می‌شود، همان عددی باشد که برنامه + رویش تصمیم می‌گیرد — نه حساب‌وکتاب دومِ جداگانه. + """ + out: dict = {"ready": False, "reason": "", "chosen": None, "others": [], + "snapshot": {}, "live_inputs": [], "file_path": str(path)} + try: + snap = datafeed.load_snapshot_file(path) + except Exception as e: # پروندهٔ پایه نبود → باید صریح گفته شود، نه سکوت + out["reason"] = f"پروندهٔ پایهٔ ردیف‌ها خوانده نشد: {type(e).__name__}" + return out + if not getattr(snap, "rows", None): + out["reason"] = f"پروندهٔ پایهٔ ردیف‌ها خوانده نشد یا خالی است: {path}" + return out + prices = {p["symbol"]: p["price"] for p in probes if p.get("ok") and p.get("price") is not None} + fails = len([p for p in probes if not p.get("ok")]) + sources = {p.get("source", "") for p in probes if p.get("ok")} + if sources: + snap.source_label = sorted(sources)[0] + snap.mode = "live" + snap = datafeed.finish_live(snap, prices, stale_count=0, fail_count=fails) + out["snapshot"] = {"status": snap.status, "source_label": snap.source_label, + "messages": list(snap.messages), "rows": len(snap.rows), + "as_of": getattr(snap, "as_of", ""), "mode": snap.mode, + "freshness_seconds": snap.freshness_seconds, + "file": str(path), "file_date": str(getattr(snap, "as_of", "") or "")} + out["live_inputs"] = [{"symbol": p["symbol"], "price": p["price"], "sha256": p["sha256"], + "latency_ms": p["latency_ms"]} for p in probes if p.get("ok")] + out["live"] = bool(prices) + if not prices: + # بدون قیمت زنده، برگهٔ شاهد «شاهد» نیست؛ عددهای پروندهٔ پایه را به اسم تصمیم امروز نمی‌فروشیم. + out["reason"] = ("هیچ قیمتی از سرویس نیامد؛ پس این اجرا «زنده» نیست و تصمیم نمونه ساخته " + "نشد. علت هر نماد در جدول آمده است.") + return out + rows = [r for r in snap.rows if r.get("kind")] + if not rows: + out["reason"] = "هیچ ردیفی با «راهبرد» در پروندهٔ پایه نبود؛ راهبردها را در جدول پر کنید." + return out + scored = [] + for row in rows: + try: + solved = inv.solve(row) + ladder = inv.ladder_for(row) + except Exception as e: + scored.append({"symbol": str(row.get("symbol", "")), "kind": str(row.get("kind", "")), + "error": f"{type(e).__name__}: {e}"}) + continue + scored.append({"symbol": str(row.get("symbol", "")), "kind": str(row.get("kind", "")), + "row": dict(row), "title": solved.get("title", ""), "answer": solved.get("answer"), + "answer_num": solved.get("answer_num"), "unit": solved.get("unit", ""), + "given": solved.get("given", []), "checks": solved.get("checks", []), + "steps": solved.get("steps", []), "extras": solved.get("extras"), + "formula": solved.get("formula", ""), "hurdle_pct": ladder.get("hurdle_pct"), + "margin_pp": ladder.get("margin_pp"), "fees_pct": ladder.get("fees_pct"), + "verdict": ladder.get("verdict", ""), "why": ladder.get("why", ""), + "survives": ladder.get("survives"), "ladder": ladder.get("ladder", [])}) + ranked = [s for s in scored if isinstance(s.get("answer_num"), (int, float))] + if not ranked: + out["reason"] = "هیچ ردیفی عدد قابل‌محاسبه نداد؛ اعداد پروندهٔ پایه را بازبینی کنید." + out["others"] = scored + return out + ranked.sort(key=lambda s: -float(s["answer_num"])) + live_rows = [s for s in ranked + if str(s["row"].get("symbol", "")) in prices + and any(s["row"].get(f"{f}_manual") is not None for f in ("spot", "stock_price"))] + if live_rows: # ردیفی که واقعاً قیمت زنده گرفت، بر ردیف پرونده‌ای مقدم است + pick_from = live_rows + scope = "ردیف‌هایی که قیمت زنده گرفتند" + else: + pick_from = ranked + scope = "همهٔ ردیف‌ها (هیچ ردیفی قیمت زنده نگرفت)" + chosen = pick_from[0] + chosen["provenance"] = provenance_of(chosen, prices, path) + others = [s for s in ranked if s is not chosen] + for other in others: + other["provenance"] = provenance_of(other, prices, path) + out.update({"ready": True, "chosen": chosen, "others": others, "reason": "", + "rank_scope": scope, "live_symbols": sorted(prices)}) + return out + + +FIELD_LABELS = (("spot", "قیمت نقدی"), ("stock_price", "قیمت سهم"), ("future", "قیمت آتی"), + ("strike", "قیمت اعمال"), ("strike_low", "اعمال پایین"), ("strike_high", "اعمال بالا"), + ("premium", "پرمیوم"), ("put_price", "پرمیوم پوت"), ("put", "پرمیوم پوت"), + ("call", "پرمیوم کال"), ("call_low", "کال پایین"), ("call_high", "کال بالا"), + ("put_low", "پوت پایین"), ("put_high", "پوت بالا"), + ("days", "روز تا سررسید"), ("margin_per_contract", "وجه تضمین هر قرارداد")) + + +def provenance_of(chosen: dict, prices: dict, path: Path | str) -> list[dict]: + """هر عدد ورودی از کجا آمد: سرویس زنده، پروندهٔ پایه، یا قاعدهٔ برنامه؟ (شفافیت کامل)""" + row = chosen.get("row") or {} + out: list[dict] = [] + for field, label in FIELD_LABELS: + if field not in row or not isinstance(row.get(field), (int, float)): + continue + live = row.get(f"{field}_manual") is not None + out.append({"label": label, "field": field, "value": row[field], + "source": "زنده از سرویس" if live else "از پروندهٔ پایه", + "detail": (f"قیمت پیش از به‌روزشدن در پرونده: {row[f'{field}_manual']:,.2f}" + if live else Path(path).name)}) + if isinstance(row.get("hurdle"), (int, float)): + out.append({"label": "نرخ سد", "field": "hurdle", "value": row["hurdle"], + "source": "قاعدهٔ برنامه", "detail": "در گام ۱ قابل تغییر است"}) + return out + + +def mixed_sources_note(chosen: dict, live_symbols=None) -> str: + """شفاف‌سازی صریح: چه چیزی زنده آمد، چه چیزی از پرونده آمد، و کدام عدد در تصمیم به‌کار رفت.""" + prov = chosen.get("provenance") or [] + live = [x for x in prov if x["source"] == "زنده از سرویس"] + filed = [x for x in prov if x["source"] == "از پروندهٔ پایه"] + read_live = bool(live_symbols) if live_symbols is not None else bool(live) + if not read_live: + return "هیچ قیمتی از سرویس نیامد؛ پس این اجرا «زنده» نیست و به عددهایش استناد نکنید." + if not live: + return ("قیمت‌های زنده خوانده شد، ولی ردیف برگزیده («" + str(chosen.get("symbol", "")) + + "» · " + str(chosen.get("kind", "")) + ") هیچ قیمت زنده‌ای را در محاسبه به کار نمی‌برد؛ " + "همهٔ عددهایش از پروندهٔ پایهٔ شماست. برای زنده‌شدن همین ردیف، قیمت‌های همان نماد " + "هم باید از سرویس یا تابلوی کارگزار بیایند — وگرنه این عدد «فرصت امروز» نیست.") + if filed: + return ("توجه: بخشی از عددهای این ردیف از پروندهٔ پایهٔ خودتان آمده است (" + + "، ".join(x["label"] for x in filed) + + "). یعنی این عدد «آزمون زندهٔ قیمت پایه» است، نه یک فرصت معاملاتی امروز. " + "برای فرصت واقعی، قیمت هر دو سر معامله باید امروز از سرویس یا از تابلوی " + "کارگزاری بیاید.") + return "همهٔ عددهای این ردیف همین حالا از سرویس خوانده شد و هیچ عددی از پرونده به کار نرفت." + + +def limits_of(doc: dict) -> list[str]: + out = ["سودآوری را اثبات نمی‌کند؛ فقط نشان می‌دهد عددهای همین تصمیم از سرویس خوانده شده‌اند.", + "قیمت لحظهٔ خواندن است؛ قیمت اجرای سفارش شما در کارگزار فری دارد و با آن فرق می‌کند.", + "وجه تضمین را کارگزاری تعیین می‌کند؛ عدد این برگه از کارگزاری نیست.", + "مشخصات قرارداد (قیمت اعمال، سررسید) از پروندهٔ پایهٔ خودتان خوانده شده، نه از سرویس."] + if any(p.get("source", "").startswith("خوراک آزمایشی") for p in doc["probes"]): + out.insert(0, "این اجرا روی «خوراک آزمایشی محلی» بوده؛ یعنی داده ساختگی است و برگه فقط " + "زنده‌بودن مسیر فنی (خواندن، هش، تصمیم) را نشان می‌دهد، نه بازار واقعی.") + if any(not p.get("ok") for p in doc["probes"]): + out.insert(0, "بعضی نمادها خوانده نشد؛ علت هرکدام در جدول آمده است.") + if any(c.get("error") for c in [doc["decision"].get("chosen") or {}]): + out.insert(0, "برای ردیف انتخابی، محاسبه کامل نشد؛ متن خطا در برگه آمده است.") + return out + + +def build(*, symbols: list[str] | None = None, timeout: float = 8.0, profile: dict | None = None, + key: str = "", path: Path | str = BASE_SNAPSHOT, write: bool = True, + page: Path | str | None = None, md: Path | str | None = None, + json_path: Path | str | None = None) -> dict: + """برگهٔ شاهد را می‌سازد (و ذخیره می‌کند).""" + active = conn.active_or_none() + prof = profile or (active or {}).get("profile") or {} + if not prof: + prof = {"name": "custom", "label": "اتصال دلخواه (چیزی انتخاب نشده)", "cost": "", + "url_template": "", "json_path": ""} + key_where = "کادر همین لحظه" if key else (active or {}).get("key_where", "بدون کلید") + names = [s for s in (symbols or []) if s] or symbols_of(path) + utc, local = stamps() + probes = probe(prof, names, timeout=timeout, key=key) + doc = { + "version": VERSION, + "built_at_utc": utc, + "built_at_local": local, + "connection": {"name": prof.get("name", ""), "label": prof.get("label", ""), + "cost": prof.get("cost", ""), "key_where": key_where, + "url_template": prof.get("url_template", ""), + "json_path": prof.get("json_path", "")}, + "probes": probes, + } + doc["decision"] = decide(probes, path=path) + doc["decision"]["mixed_note"] = ( + mixed_sources_note(doc["decision"]["chosen"], + doc["decision"].get("live_symbols") or []) + if doc["decision"].get("chosen") else "") + doc["limits"] = limits_of(doc) + core = json.dumps({"probes": probes, "decision": doc["decision"]}, sort_keys=True, + ensure_ascii=False) + doc["page_hash"] = hashlib.sha256(core.encode("utf-8")).hexdigest()[:16] + doc["text"] = text_of(doc) + if write: + for target, content in ((page or PAGE, _page(doc)), (md or MD, doc["text"]), + (json_path or JSONF, json.dumps(doc, ensure_ascii=False, indent=1))): + pth = Path(target) + pth.parent.mkdir(parents=True, exist_ok=True) + pth.write_text(content, encoding="utf-8") + doc.update({"page": str(page or PAGE), "md": str(md or MD), "json": str(json_path or JSONF)}) + return doc + + +def text_of(doc: dict) -> str: + d = doc["decision"] + L = [f"# برگهٔ شاهد زندهٔ داده — نسخهٔ {VERSION}", "", + f"ساعت خواندن: {doc['built_at_local']} (UTC: {doc['built_at_utc']})", + f"اتصال فعال: {doc['connection']['label']} ({doc['connection']['cost']}) — کلید: {doc['connection']['key_where']}", + f"قالب نشانی: `{doc['connection']['url_template'] or '—'}`", ""] + L += ["## ۱. عددهایی که همین حالا خوانده شد", "", + "| نماد | قیمت | منبع | بایت | اثر انگشت پاسخ خام | تأخیر | وضعیت |", + "| --- | --- | --- | --- | --- | --- | --- |"] + for p in doc["probes"]: + price = f"{p['price']:,.4f}" if p.get("price") is not None else "—" + state = "خوانده شد ✅" if p.get("ok") else f"نشد ❌ {p.get('error', '')}" + L.append(f"| {p['symbol']} | {price} | {p.get('source', '')} | {p.get('bytes', 0)} | " + f"`{p.get('sha256', '')[:16]}` | {p.get('latency_ms', '—')} ms | {state} |") + L += ["", "نشانی‌های خوانده‌شده:"] + [f"- {p['symbol']}: `{p['url']}`" for p in doc["probes"]] + L += ["", "## ۲. تصمیمی که از همین عددها درآمد", ""] + if d.get("ready"): + s = d["chosen"] + L += [f"- عکس زندهٔ بازار: {d['snapshot']['status']} · منبع: {d['snapshot']['source_label']}", + f"- ردیف انتخابی (بالاترین بازده): **{s['symbol']}** · {s['kind']} — {s['title']}", + f"- قیمت‌هایی که زنده خوانده شد: {'، '.join(d.get('live_symbols') or []) or '—'}", + f"- دامنهٔ رتبه‌بندی: {d.get('rank_scope', '—')}"] + if s.get("given"): + L += ["- عددهای ورودی: " + " · ".join(f"{g[0]} {g[1]}" for g in s["given"])] + for g in d["live_inputs"]: + L += [f" - {g['symbol']}: {g['price']:,.4f} (هش `{g['sha256'][:16]}` · {g['latency_ms']} ms)"] + L += ["", f"**پاسخ: {s.get('answer')} {s.get('unit', '')}**", ""] + if s.get("checks"): + L += ["سنجش دو-روشی (هر سطر باید «می‌خواند» باشد):"] + L += [f"- {c.get('note', '')}: `{c.get('value')}` — " + f"{'می‌خواند ✅' if c.get('agree') else 'نمی‌خواند ❌'}" for c in s["checks"]] + if s.get("steps"): + L += ["", "مسیر محاسبه (قابل بازتولید با ماشین‌حساب):"] + L += [f"- {st}" for st in s["steps"]] + if d.get("mixed_note"): + L += ["", "> **" + d["mixed_note"] + "**", ""] + if s.get("provenance"): + L += ["", "هر عدد از کجا آمد:", "", + "| عدد | مقدار | از کجا | توضیح |", "| --- | --- | --- | --- |"] + for pr in s["provenance"]: + val = f"{pr['value']:,.4f}".rstrip("0").rstrip(".") if isinstance(pr["value"], float) \ + else f"{pr['value']:,}" + L.append(f"| {pr['label']} | {val} | {pr['source']} | {pr['detail']} |") + if s.get("ladder"): + L += ["", "پلهٔ خروج — «کِی بفروشم، کِی می‌افتد»:", "", + "| حد | کِی | روی چه قیمتی | کار |", "| --- | --- | --- | --- |"] + for item in s["ladder"]: + price = item.get("price") + price_txt = f"{price:,.3f}" if isinstance(price, (int, float)) else str(price) + L.append(f"| {item.get('label', '')} | {item.get('when', '')} | {price_txt} | " + f"{item.get('action', '')} |") + for key, label in (("verdict", "داوری"), ("why", "چرا"), ("fees_pct", "کارمزد لحاظ‌شده (٪)"), + ("hurdle_pct", "نرخ سد (٪)"), ("margin_pp", "حاشیه روی سد (واحد درصد)")): + if s.get(key) not in (None, ""): + L.append(f"- {label}: {s[key]}") + if d.get("others"): + L += ["", "سایر ردیف‌ها:", "", + "| نماد | راهبرد | پاسخ |", "| --- | --- | --- |"] + for o in d["others"]: + L.append(f"| {o.get('symbol','')} | {o.get('kind','')} | " + f"{o.get('answer','—')} {o.get('unit','')} |") + else: + L.append(f"- تصمیم نمونه ساخته نشد: {d.get('reason', '')}") + L += ["", f"اثر انگشت کل برگه: `{doc['page_hash']}`", "", + "## ۳. راستی‌آزمایی مستقل", "", + "۱) همان نشانی را در مرورگر باز کنید و عدد را ببینید. ۲) پاسخ خام بالا را با ماشین‌حساب " + "بشمارید. ۳) اثر انگشت این برگه را با `data/witness-live.json` بسنجید.", "", + "## ۴. این برگه چه چیزی را اثبات نمی‌کند", ""] + L += [f"- {x}" for x in doc["limits"]] + L += ["", "---", "", + "✍️ تهیه‌کنندهٔ جزوات: **Masoud Mojarabian** · 📱 +989126630554 · " + "✈️ Telegram: [Mojarabian](https://t.me/Mojarabian) · " + "📸 Instagram: [Mojarabian.Art](https://instagram.com/Mojarabian.Art)"] + return "\n".join(L) + + +def _page(doc: dict) -> str: + c, d = doc["connection"], doc["decision"] + mock = any(p.get("source", "").startswith("خوراک آزمایشی") for p in doc["probes"]) + head = [f'
    این برگه با همین ساعت ساخته شده. برای هر عدد، نشانی و ' + f'اثر انگشت پاسخ خام سرویس چاپ شده تا خودتان راستی‌آزمایی کنید. ' + f'{rk.esc(doc["built_at_local"])} (UTC: {rk.esc(doc["built_at_utc"])})
    '] + if mock: + head.append('
    توجه: این اجرا روی خوراک آزمایشی محلی است؛ داده ساختگی ' + 'است. برگه فقط نشان می‌دهد که مسیر «خواندن از سرویس ← هش ← تصمیم» زنده کار ' + 'می‌کند. برای عدد بازار واقعی، پروفایل سرویس واقعی را انتخاب کنید.
    ') + head.append(f'

    اتصال فعال: {rk.esc(c["label"])} · هزینه: {rk.esc(c["cost"])} · ' + f'کلید: {rk.esc(c["key_where"])} · مسیر عدد در پاسخ: {rk.esc(c["json_path"] or "—")}

    ') + rows = [] + for p in doc["probes"]: + if p.get("ok"): + price, state = rk.num(p["price"], 4), 'خوانده شد ✅' + else: + price = "—" + state = ('نشد ❌
    ' + f'{rk.esc(p.get("error", ""))}') + rows.append(f'{rk.esc(p["symbol"])}{price}' + f'{rk.esc(p.get("source", ""))}{p.get("bytes", 0)}' + f'{rk.esc(p.get("sha256", "")[:16])}' + f'{p.get("latency_ms", "—")}{state}') + table = ('' + '' + '' + + "".join(rows) + "
    نمادقیمتمنبعبایتاثر انگشت پاسختأخیر (ms)وضعیت
    ") + raws = "".join(f'

    {rk.esc(p["symbol"])} — {rk.esc(p["url"])}

    ' + f'
    {rk.esc(p["snippet"])}
    ' for p in doc["probes"] if p.get("snippet")) + if d.get("ready"): + s = d["chosen"] + block = ['', + f'', + f''] + if s.get("given"): + block.append('') + for g in d["live_inputs"]: + block.append(f'' + f'') + block.append(f'') + for key, label in (("verdict", "داوری"), ("fees_pct", "کارمزد لحاظ‌شده (٪)"), + ("hurdle_pct", "نرخ سد (٪)"), ("margin_pp", "حاشیه روی سد (واحد درصد)")): + if s.get(key) not in (None, ""): + val = rk.num(s[key], 3) if isinstance(s[key], (int, float)) else rk.esc(s[key]) + block.append(f'') + block.append('
    عکس زندهٔ بازار{rk.esc(d["snapshot"]["status"])} · ' + f'{rk.esc(d["snapshot"]["source_label"])}
    ردیف انتخابی (بالاترین بازده){rk.esc(s["symbol"])} · ' + f'{rk.esc(s["kind"])} — {rk.esc(s.get("title", ""))}
    عددهای ورودی' + + " · ".join(f'{rk.esc(g[0])} {rk.esc(g[1])}' for g in s["given"]) + + '
    قیمت زندهٔ {rk.esc(g["symbol"])}{rk.num(g["price"], 4)} ' + f'(هش {rk.esc(g["sha256"][:16])} · ' + f'{g["latency_ms"]} ms)
    پاسخ{rk.esc(s.get("answer"))} ' + f'{rk.esc(s.get("unit", ""))}
    {rk.esc(label)}{val}
    ') + checks = "" + if s.get("checks"): + checks = ("

    سنجش دو-روشی

      " + "".join( + f'
    • {rk.esc(c.get("note", ""))}: {rk.esc(c.get("value"))} — ' + f'{"می‌خواند ✅" if c.get("agree") else "نمی‌خواند ❌"}
    • ' for c in s["checks"]) + + "
    ") + steps = "" + if s.get("steps"): + steps = ("

    مسیر محاسبه (با ماشین‌حساب هم می‌شود بازتولید کرد)

      " + + "".join(f"
    1. {rk.esc(x)}
    2. " for x in s["steps"]) + "
    ") + prov = "" + if s.get("provenance"): + prows = [] + for pr in s["provenance"]: + val = (rk.num(pr["value"], 4) if isinstance(pr["value"], float) + else f"{pr['value']:,}") + cls = "ok" if pr["source"] == "زنده از سرویس" else "hint" + prows.append(f'{rk.esc(pr["label"])}{val}' + f'{rk.esc(pr["source"])}' + f'{rk.esc(pr["detail"])}') + prov = ('

    هر عدد از کجا آمد

    ' + '' + "".join(prows) + "
    عددمقداراز کجاتوضیح
    ") + ladder = "" + if s.get("ladder"): + lrows = [] + for item in s["ladder"]: + price = item.get("price") + price_txt = (f"{price:,.3f}" if isinstance(price, (int, float)) else str(price)) + lrows.append(f'{rk.esc(item.get("label", ""))}' + f'{rk.esc(item.get("when", ""))}' + f'{rk.esc(price_txt)}' + f'{rk.esc(item.get("action", ""))}') + ladder = ('

    پلهٔ خروج — «کِی بفروشم، کِی می‌افتد»

    ' + '' + + "".join(lrows) + "
    حدکِیروی چه قیمتیکار
    ") + others = "" + if d.get("others"): + orows = "".join(f'{rk.esc(o.get("symbol", ""))}' + f'{rk.esc(o.get("kind", ""))}' + f'{rk.esc(str(o.get("answer", "—")))} ' + f'{rk.esc(o.get("unit", ""))}' for o in d["others"]) + others = ('

    سایر ردیف‌ها

    ' + '' + orows + "
    نمادراهبردپاسخ
    ") + if d.get("mixed_note"): + block.insert(0, f'
    {rk.esc(d["mixed_note"])}
    ') + dec_body = "".join(block) + prov + checks + steps + ladder + others + if s.get("why"): + dec_body += f'

    {rk.esc(s["why"])}

    ' + else: + dec_body = f'

    {rk.esc(d.get("reason", ""))}

    ' + + limits = "".join(f"
  • {rk.esc(x)}
  • " for x in doc["limits"]) + body = "".join(head + [ + "

    ۱. عددهایی که همین حالا خوانده شد

    ", table, + "

    پاسخ خام سرویس (برای راستی‌آزمایی)

    ", + raws or '

    پاسخی ثبت نشد.

    ', + "

    ۲. تصمیمی که از همین عددها درآمد

    ", dec_body, + "

    ۳. راستی‌آزمایی مستقل

    ", + '

    سه راه برای اینکه به حرف برنامه اعتماد نکنید و خودتان بسنجید: ' + '۱) همان نشانی را در مرورگر باز کنید و عدد را ببینید. ۲) پاسخ خام بالا را با ماشین‌حساب ' + 'بشمارید. ۳) اثر انگشت این برگه را با پروندهٔ data/witness-live.json بسنجید.

    ', + f'

    اثر انگشت برگه: {rk.esc(doc["page_hash"])}

    ', + "

    ۴. این برگه چه چیزی را اثبات نمی‌کند

    ", f"
      {limits}
    ", + '

    نسخهٔ ' + VERSION + ' · ✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · ' + '📱 +989126630554 · ✈️ Telegram: Mojarabian · ' + '📸 Instagram: Mojarabian.Art

    ', + ]) + ok = sum(1 for p in doc["probes"] if p.get("ok")) + return rk.page("برگهٔ شاهد زندهٔ داده", body, + subtitle=f"خوانده‌شده از سرویس در {doc['built_at_local']} · " + f"{ok} از {len(doc['probes'])} نماد") + + +def summary_line(doc: dict) -> str: + ok = [p for p in doc["probes"] if p.get("ok")] + d = doc["decision"] + line = f"{len(ok)} از {len(doc['probes'])} قیمت زنده خوانده شد" + if d.get("ready"): + s = d["chosen"] + line += f" · ردیف برگزیده {s.get('symbol', '')} ({s.get('kind', '')})" + if s.get("answer") is not None: + line += f": {s.get('answer')} {s.get('unit', '')}" + if s.get("verdict"): + line += f" · {s['verdict'][:60]}" + else: + line += f" · تصمیم نمونه ساخته نشد: {d.get('reason', '')}" + return line + + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description="برگهٔ شاهد زندهٔ داده (خواندن + هش + تصمیم نمونه)") + ap.add_argument("--symbols", default="", help="نمادها با کاما (پیش‌فرض: نمادهای پروندهٔ پایه)") + ap.add_argument("--file", default=str(BASE_SNAPSHOT), help="پروندهٔ پایهٔ ردیف‌ها") + ap.add_argument("--timeout", type=float, default=8.0) + ap.add_argument("--json", action="store_true") + ap.add_argument("--quiet", action="store_true") + ap.add_argument("--out", default="", help="پوشهٔ خروجی (پیش‌فرض: data/)") + a = ap.parse_args(argv) + symbols = [s.strip() for s in a.symbols.split(",") if s.strip()] + out = Path(a.out) if a.out else None + doc = build(symbols=symbols, timeout=a.timeout, path=a.file, + page=(out / "witness-live.html") if out else None, + md=(out / "witness-live.md") if out else None, + json_path=(out / "witness-live.json") if out else None) + if a.json: + print(json.dumps(doc, ensure_ascii=False, indent=1)) + return 0 + if not a.quiet: + print(summary_line(doc)) + for p in doc["probes"]: + if p.get("ok"): + print(f" · {p['symbol']}: {p['price']:,.4f} (هش {p['sha256'][:12]} · " + f"{p['latency_ms']} ms · {p['source']})") + else: + print(f" ✗ {p['symbol']}: {p.get('error', '')}") + print(f" برگه: {doc.get('page')}") + print(f" نسخهٔ متنی: {doc.get('md')}") + print(f" اثر انگشت برگه: {doc['page_hash']}") + return 0 if any(p.get("ok") for p in doc["probes"]) else 1 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/station/diagnose.py b/station/diagnose.py new file mode 100644 index 0000000000000000000000000000000000000000..b0d85021ebe5e4b41b9ce29ab0400b4cb7389f45 --- /dev/null +++ b/station/diagnose.py @@ -0,0 +1,211 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""گزارش عیب‌یابی یک‌کلیکی — «پشتیبانی بدون دانش فنی». + +کسی که این برنامه را ارائه می‌دهد لازم نیست مهندس پشتیبانی باشد. با یک دکمه، همهٔ چیزهایی که +برای تشخیص لازم است در یک پروندهٔ خوانا جمع می‌شود: نسخه‌ها، سلامت اجزا، وضعیت اجازه‌نامه، +محل پرونده‌ها، اثر انگشت موتور، وضعیت دفتر، و آخرین خطاها. همان پرونده را برای هر تکنسین یا +برای ادامهٔ کار در گفتگو بفرستید؛ دیگر لازم نیست چیزی را دستی توضیح دهید. + +نمونه: + python diagnose.py # ساخت گزارش و ذخیره در data/diagnostic-report.html + python diagnose.py --json # خروجی ماشین‌خوان + python diagnose.py --text # متن ساده برای کپی‌کردن در پیام +""" +from __future__ import annotations + +import argparse +import json +import platform +import subprocess +import sys +from datetime import datetime, timezone +from pathlib import Path + +VERSION = "0.1.0" +BASE = Path(__file__).resolve().parent +DATA = BASE / "data" +REPORT_HTML = DATA / "diagnostic-report.html" +REPORT_TXT = DATA / "diagnostic-report.txt" +for p in (str(BASE), str((BASE.parent / "desk").resolve())): + if p not in sys.path: + sys.path.insert(0, p) + +CREDIT = ("دولوپر: مهندس مسعود مجربیان · تهیه‌کننده: Masoud Mojarabian · https://www.instagram.com/Mojarabian.Art/ · " + "tel:+989126630554 · https://t.me/Mojarabian") + + +def _safe(fn, default): + try: + return fn() + except Exception as e: # هر خطایی خودش یک شاهد در گزارش است + return default if default is not None else {"error": f"{type(e).__name__}: {e}"} + + +def collect(run_tests: bool = True) -> dict: + """همهٔ سنجه‌های تشخیصی، بدون هیچ تغییری در داده‌های کار.""" + out: dict = {"ts": datetime.now(timezone.utc).replace(microsecond=0).isoformat(), + "diagnose_version": VERSION, + "python": sys.version.split()[0], + "platform": f"{platform.system()} {platform.release()} ({platform.machine()})"} + try: + import station as st + ok, items = st.health_report() + out["station_version"] = st.VERSION + out["health"] = {"ok": ok, "items": [{"name": n, "ok": f, "note": r} for n, f, r in items]} + except Exception as e: + out["health"] = {"ok": False, "items": [], "error": f"{type(e).__name__}: {e}"} + + try: + import license as licmod # noqa: A004 (نام ماژول خودمان) + out["license"] = licmod.verify() + except Exception as e: + out["license"] = {"state": "نامعلوم", "ok": False, "detail": f"{type(e).__name__}: {e}"} + + def engine_fp() -> dict: + import hashlib + sys.path.insert(0, str((BASE.parent / "tools").resolve())) + import derivatives_scout as scout # noqa: WPS433 + src = Path(scout.__file__).read_bytes() + return {"path": str(scout.__file__), + "sha256_16": hashlib.sha256(src).hexdigest()[:16], + "version": getattr(scout, "VERSION", "?")} + out["engine"] = _safe(engine_fp, {}) + + def trial_state() -> dict: + import daily_trial as dt + score = dt.scorecard(log_path=DATA / "trial-daily.log") + return {"days": score.get("days"), "real_days": score.get("real_days"), + "ready": score.get("ready"), "hash_chain_ok": score.get("chain_ok")} + out["trial"] = _safe(trial_state, {}) + + def files_state() -> dict: + rows = [] + for name, path in (("اجازه‌نامه", BASE / "config" / "license.json"), + ("دفتر اتصال", BASE / "config" / "connections.json"), + ("کلید ذخیره‌شده", BASE / "config" / "keys.local.json"), + ("دفتر آزمون", DATA / "trial-daily.log"), + ("برگهٔ آزمون", DATA / "exam-sheet.html"), + ("پروندهٔ سرمایه‌گذار", DATA / "investor-dossier.html"), + ("آخرین بستهٔ شاهد", None)): + if path is None: + exports = sorted((BASE / "export").glob("bundle-*")) + path = exports[-1] if exports else None + rows.append({"name": name, "path": str(path) if path else "—", + "exists": bool(path and Path(path).exists()), + "bytes": Path(path).stat().st_size if path and Path(path).exists() else 0}) + return rows + out["files"] = _safe(files_state, []) + + def connections_state() -> dict: + import connections as conn + store = conn.load_store() + active = conn.active_or_none() or {} + return {"profiles": len(store.get("profiles", [])), + "active": active.get("name") or "—", + "active_label": active.get("label") or "—", + "key_where": active.get("key_where") or "—"} + out["connections"] = _safe(connections_state, {}) + + def tests_state() -> dict: + """آزمون‌های واحد را در حالت کوتاه اجرا می‌کند (اگر کند بود، ناموفق گزارش می‌شود).""" + p = subprocess.run([sys.executable, "-m", "unittest", "discover", "-s", "tests"], + cwd=str(BASE), capture_output=True, text=True, timeout=600) + return {"ok": p.returncode == 0, "tail": pick_test_tail(p.stderr)} + out["tests"] = (_safe(tests_state, {"ok": False, "tail": "اجرا نشد"}) if run_tests + else {"ok": True, "tail": "اجرا نشد (حالت سریع)"}) + out["ok"] = bool(out["health"].get("ok", False)) and bool(out.get("tests", {}).get("ok")) + return out + + +def summary_line(rep: dict) -> str: + return (f"سلامت: {'سبز' if rep.get('health', {}).get('ok') else 'سرخ'} · " + f"آزمون‌ها: {'سبز' if rep.get('tests', {}).get('ok') else 'سرخ'} · " + f"مجوز: {rep.get('license', {}).get('state', '—')} · " + f"اتصال فعال: {rep.get('connections', {}).get('active', '—')} · " + f"موتور: {rep.get('engine', {}).get('sha256_16', '—')}") + + +def pick_test_tail(stderr: str) -> str: + """از خروجی آزمون‌ها، خط «نتیجه» را برمی‌دارد و هشدارهای بی‌ربط پایان کار را دور می‌ریزد.""" + lines = [ln.strip() for ln in (stderr or "").strip().splitlines() if ln.strip()] + lines = [ln for ln in lines if "ResourceWarning" not in ln and not ln.startswith(":")] + summary = next((ln for ln in reversed(lines) if ln.startswith(("OK", "FAILED"))), None) + if summary is None: + summary = lines[-1] if lines else "بی‌پاسخ" + reds = [ln for ln in lines if ln.startswith(("FAIL:", "ERROR:"))][:4] + return (" · ".join([summary] + reds) if reds else summary)[:400] + + +def build_report(rep: dict, path: Path | str = REPORT_HTML) -> tuple[Path, Path]: + p = Path(path) + p.parent.mkdir(parents=True, exist_ok=True) + items = "\n".join( + f"{i['name']}{'✅' if i['ok'] else '❌'}{i['note']}" + for i in rep.get("health", {}).get("items", [])) + files = "\n".join( + f"{f['name']}{'✅' if f['exists'] else '—'}" + f"{f['path']}{f['bytes'] or ''}" + for f in rep.get("files", [])) + html = f""" +گزارش عیب‌یابی ایستگاه +
    +

    گزارش عیب‌یابی ایستگاه

    +

    {rep.get('ts')} · نسخهٔ گزارش: {rep.get('diagnose_version')} · {rep.get('platform')} · پایتون {rep.get('python')}

    +

    {summary_line(rep)}

    +

    سلامت اجزا

    +{items}
    جزءوضعیتتوضیح
    +

    پرونده‌های مهم

    +{files}
    پروندههست؟مسیربایت
    +

    اجازه‌نامه و اتصال

    +
    {json.dumps({'license': rep.get('license'), 'connections': rep.get('connections'), 'trial': rep.get('trial')}, ensure_ascii=False, indent=1)}
    +

    موتور ریاضی

    +
    {json.dumps(rep.get('engine'), ensure_ascii=False, indent=1)}
    +
    {CREDIT}
    این گزارش هیچ دادهٔ معاملاتی داخلی را منتقل نمی‌کند؛ فقط وضعیت فنی است.
    +
    +""" + txt = (f"گزارش عیب‌یابی ایستگاه\n{rep.get('ts')} · پایتون {rep.get('python')} · {rep.get('platform')}\n" + f"{summary_line(rep)}\n\n" + + "\n".join(f"- {i['name']}: {'OK' if i['ok'] else 'FAIL'} · {i['note']}" + for i in rep.get("health", {}).get("items", [])) + + "\n\n" + json.dumps({"license": rep.get("license"), "connections": rep.get("connections"), + "engine": rep.get("engine"), "trial": rep.get("trial")}, + ensure_ascii=False, indent=1) + + f"\n\n{CREDIT}\n") + t = Path(REPORT_TXT) + t.write_text(txt, encoding="utf-8") + p.write_text(html, encoding="utf-8") + return p, t + + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description="گزارش عیب‌یابی یک‌کلیکی") + ap.add_argument("--json", action="store_true", help="خروجی ماشین‌خوان") + ap.add_argument("--text", action="store_true", help="متن ساده، برای کپی در پیام") + ap.add_argument("--quick", action="store_true", help="بدون اجرای آزمون‌های واحد") + ap.add_argument("--version", action="version", version=f"diagnose {VERSION}") + args = ap.parse_args(argv) + + rep = collect(run_tests=not args.quick) + h, t = build_report(rep) + if args.json: + print(json.dumps(rep, ensure_ascii=False, indent=1)) + return 0 if rep.get("ok") else 1 + if args.text: + print(t.read_text(encoding="utf-8")) + return 0 if rep.get("ok") else 1 + print(summary_line(rep)) + print(f"گزارش ساخته شد:\n {h}\n {t}") + return 0 if rep.get("ok") else 1 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/station/docs/01-derivatives-iran-fa.md b/station/docs/01-derivatives-iran-fa.md new file mode 100644 index 0000000000000000000000000000000000000000..76fda7765087243bf2d044c15ed687897185e1b0 --- /dev/null +++ b/station/docs/01-derivatives-iran-fa.md @@ -0,0 +1,136 @@ +# مشتقه در ایران: چه چیزی ریاضی است، چه چیزی شانس است + +**پروندهٔ پژوهشی ۱، تاریخ: ۲۲ سپتامبر ۲۰۲۶** +**پرسش صاحب پرونده:** آیا می‌شود با خرید و فروش اوراق مشتقه در ایران، فقط با ریاضیات و بدون شانس، سریع تشخیص داد چه چیزی را چه زمانی بخرم و بفروشم و چقدر سود و با چه احتمالی؟ + +## خلاصهٔ اجرایی (حکم صریح) + +جملهٔ «ریاضیات اگر درست به کار گرفته شود ثروت را تضمین می‌کند» یک جملهٔ نیمه‌درست است. ریاضیات در بازار، **برتری** (edge) می‌سازد، نه **تضمین**. در ایران امروز سه سؤال تعیین‌کننده است و پاسخ هر سه با داده‌های همین گزارش آمدنی است: + +۱. **آیا در ایران معاملهٔ بدون‌شانس (آربیتراژ) وجود دارد؟** بله، ولی کوچک و کوتاه‌عمر: عمدتاً در قالب پایهٔ آتی، باکس‌اسپرد و اوراق اختیار فروش تبعی. +۲. **آیا با سرمایهٔ کوچک (زیر چند صد میلیون تومان) این کار به‌صرفه است؟** در بیشتر روزها نه. چون کارمزد، اسپرد خرید‌وفروش، وجه تضمین و ریسک اجرا، بازدهٔ ریاضی را می‌بلعد. گزینهٔ واقع‌بینانه‌تر با سرمایهٔ خرد، صندوق درآمد ثابت (بازده مؤثر اسمی حدود ۳۹ تا ۴۰ درصد سالانه در شهریور ۱۴۰۵) و صندوق طلا برای پوشش تورم است. +۳. **پس چه چیزی «سلام» و «ریاضی» است؟** ترکیب سه لایه: (الف) لایهٔ امن سرمایه، (ب) لایهٔ آربیتراژهای کوچک با حاشیهٔ اطمینان، (ج) لایهٔ درآمد از مهارت (بخش دوم پرونده). معاملهٔ جهت‌دار روی آپشن، شانس است و نه ریاضی. + +**برآورد صادقانهٔ احتمال موفقیت:** + +| مسیر | تعریف موفقیت | برآورد احتمال | مبنا | +|---|---|---|---| +| آربیتراژ پایه/باکس با انضباط کامل | بازده سالانهٔ بالاتر از صندوق درآمد ثابت، بدون ضرردهی ماهانه | ۳۵ تا ۵۰ درصد | فرصت نادر + ریسک اجرا و نقدشوندگی | +| برداشت بازده تضمینی اوراق تبعی | دریافت کامل مبلغ تضمین در سررسید | ۷۰ تا ۸۵ درصد | تضمین ناشر، ولی مشروط به نگه‌داشتن سبد و ریسک نکول | +| معاملهٔ جهت‌دار آپشن (خرید کال/پوت) | سود خالص سالانه بعد از کارمزد | ۱۰ تا ۲۰ درصد | آمار جهانی: بیش از ۹۰ درصد معامله‌گران خرد بازنده‌اند | +| معاملهٔ نوسانی روزانه روی هر ابزار | سود پایدار در ۱۲ ماه | زیر ۱۵ درصد | مطالعات خرد: تکنیکال + کارمزد = انتقال ثروت به واسطه‌ها | + +این درصدها **برآورد** هستند، نه آمار دولتی؛ روش: ترکیب آمار منتشرشدهٔ بازندگان خرد با واقعیت ساختاری بازار ایران (اسپرد بزرگ، نقدشوندگی کم، محدودیت فروش استقراضی). + +## نقشهٔ بازار (چه چیزی، کجا، با چه قانونی) + +**در بورس اوراق بهادار تهران و فرابورس:** قرارداد اختیار معامله (کال و پوت) روی سهام و صندوق‌های منتخب، به‌صورت ماهانه، با اندازهٔ قرارداد استاندارد (روی سهام معمولاً ۱٬۰۰۰ سهم)، سررسید مشخص، سبک اعمال اروپایی، و دو روش تسویه: نقدی یا فیزیکی. سقف موقعیت هم‌جهت و فاصلهٔ قیمت اعمال، در «مشخصات قرارداد» اعلام می‌شود. + +**در بورس کالای ایران:** قرارداد آتی (شمش و صندوق طلا، زعفران، پسته، زیره)، اختیار معاملهٔ کالا، و گواهی سپردهٔ کالایی (زعفران، شمش و سکه، پسته، سیمان، شیشه، سنگ‌آهن، میلگرد). + +**اوراق اختیار فروش تبعی:** نسخهٔ ایرانی و بسیار مهم این بازار. ناشر (شرکت یا نهاد حمایتی) متعهد می‌شود در سررسید، کمینهٔ بازدهی را بپردازد. در عرضه‌های واقعی، نرخ تضمین در بازهٔ ۲۰ تا ۳۰ درصد دیده شده و **شرط اعتبار، نگه‌داشتن سبد پایه تا سررسید است**. تسویه می‌تواند مابه‌التفاوت نقدی باشد یا خرید سهام توسط ناشر. + +### قوانین و هزینه‌هایی که همه‌چیز را تعیین می‌کند + +- **کارمزد معاملهٔ اختیار معامله:** حدود ۰٫۱۰۳ درصد هر طرف؛ **کارمزد اعمال:** ۰٫۰۵ درصد ارزش قرارداد بر پایهٔ قیمت اعمال؛ **مالیات واگذاری در تسویهٔ فیزیکی:** ۰٫۵ درصد. معاملات مشتقه از مالیات بر درآمد معاف است. +- **کارمزد سهام:** خرید حدود ۰٫۴۶۴ درصد و مجموع کسورات فروش حدود ۰٫۹۶۴ درصد (شامل ۰٫۵ درصد مالیات نقل‌وانتقال). +- **وجه تضمین:** خریدار آپشن وجه تضمین نمی‌دهد؛ **فروشنده** باید وجه تضمین اولیه بگذارد و حداقل ۷۰ درصد آن را نگه دارد، وگرنه اخطاریهٔ افزایش وجه تضمین می‌گیرد. ضوابط وجه تضمین، برای ۱۸ راهبرد استاندارد (پوشش‌داده‌شده، دوپایه‌ای، پروانه‌ای و…) جدول جداگانه دارد. +- **آتی کالا:** وجه تضمین اولیه حدود ۱۰ تا ۲۰ درصد ارزش قرارداد، تسویهٔ روزانهٔ سود و زیان، حداقل ۷۰ درصد به‌عنوان وجه تضمین جبرانی، حد نوسان روزانه معمولاً ۵ درصد. +- **فروش استقراضی سهام در ایران وجود ندارد.** یعنی نیمهٔ دوم آربیتراژهای تبدیل‌پذیر و «reverse conversion» از پیش مسدود است؛ فقط جهتی که با داشتن سهم یا با فروش آتی قابل ساخت است، عملی است. + +{**_نکتهٔ مهم دربارهٔ محدودیت‌ها: بسیاری از فرصت‌های «بدون ریسک» کتابی، در ایران عملاً در یک طرف بسته است. اگر الگوریتمی ساختید که بدون فروش استقراضی سود می‌دهد، قابل اجرا است؛ اگر به آن نیاز دارد، دورش را خط بکشید._**} + +## جعبه‌ابزار ریاضی (همان چیزی که ابزار ساخته‌شده اجرا می‌کند) + +۱. **ارزش منصفانهٔ آتی:** F = S × exp((r + u − y)×T)؛ با r نرخ بهره، u هزینهٔ انبارداری، y منافع نگهداری. +۲. **نرخ تلویحی بازار:** r_implied = ln(F/S)/T. اگر این عدد از نرخ سد شما کمتر بود، خرید نقدی و فروش آتی به‌صرفه نیست. +۳. **پایهٔ نقدی‌آتی (Cash & Carry):** بازده خالص = (قیمت آتی پس از کارمزد فروش − قیمت نقدی پس از کارمزد خرید − هزینهٔ انبار) ÷ هزینهٔ خرید، بعد سالانه‌سازی مرکب. +۴. **تساوی پوت‌کال:** C − P = S − K×exp(−rT). انحراف مثبت و بزرگ‌تر از هزینه‌های گردش = فرصت conversion. +۵. **باکس اسپرد:** خرید کال با اعمال پایین + فروش پوت با اعمال پایین + فروش کال با اعمال بالا + خرید پوت با اعمال بالا. دریافتی قطعی = K₂ − K₁؛ اگر بدهی اولیه کمتر باشد، بازده بدون‌ریسک تا سررسید قفل می‌شود. +۶. **تبعی:** بازده تضمینی = (K پس از کسر کارمزد فروش − (قیمت سهم پس از کارمزد خرید + قیمت پوت)) ÷ همان هزینهٔ کل، بعد سالانه‌سازی. +۷. **نوسان ضمنی در برابر نوسان واقعی:** اگر نوسان ضمنی بازار چند واحد بزرگ‌تر از نوسان واقعی ۳۰ روز گذشتهٔ سهم باشد، فروشندهٔ آپشن (پوشش‌دار) در موقعیت بهتری است؛ عکس آن، خریدار. + +## شش استراتژی، از بی‌ریسک‌تر به پرریسک‌تر + +| # | استراتژی | ماهیت ریاضی | بازده واقع‌بینانه | احتمال موفقیت | شرط اصلی | +|---|---|---|---|---|---| +| ۱ | برداشت بازده اوراق تبعی | تضمین ناشر | ۲۰ تا ۳۰ درصد در دورهٔ نگه‌داری | ۷۰ تا ۸۵ درصد | نگه‌داشتن سبد پایه، بررسی اعتبار ناشر | +| ۲ | باکس اسپرد آپشن | قفل کردن تفاوت دو قیمت اعمال | تا رسیدن به نرخ سد یا بیشتر | ۳۵ تا ۵۰ درصد | هر چهار پا در یک روز و با نقدشوندگی کافی | +| ۳ | پایهٔ آتی (نقد بخر، آتی بفروش) | نرخ تلویحی در برابر نرخ سد | ۵ تا ۳۰ درصد سالانهٔ اضافی | ۳۰ تا ۴۵ درصد | امکان نگه‌داری کالا یا گواهی تا سررسید | +| ۴ | فتوکال پوشش‌داده‌شده روی سهم موجود | فروش نوسان، درآمد پرمیوم | ۲۰ تا ۴۵ درصد سالانه از پرمیوم | ۴۵ تا ۶۰ درصد | داشتن سهم، پذیرش سقف رشد | +| ۵ | پوت محافظ / کالارزان | ساختن کف یا اهرم ارزان | وابسته به روند بازار | ۳۰ تا ۴۵ درصد | تحلیل جهت‌دار؛ دیگر ریاضی محض نیست | +| ۶ | خرید جهت‌دار آپشن | شرط‌بندی روی نوسان | میانگین منفی بعد از کارمزد | ۱۰ تا ۲۰ درصد | توصیه نمی‌شود مگر با مهارت اثبات‌شده | + +نکتهٔ کلیدی دربارهٔ جدول: سه ردیف اول، «بی‌ریسک‌تر» هستند ولی **بازده کمی دارند و به سرمایهٔ بزرگ‌تر حساس‌اند**؛ سه ردیف آخر پرمیوم و داستان دارند، ولی همان جایی است که اکثریت پول از دست می‌دهند. + +## فلوچارت تصمیم (روزانه) + +``` +شروع روز + ├─ ۱. آیا دادهٔ امروز کامل است؟ (قیمت پایانی پایه، کل زنجیرهٔ آپشن، آتی، گواهی سپرده، نرخ سد) + │ نه ⇒ هیچ معامله‌ای نکن؛ دادهٔ ناقص = تصمیم ناقص + ├─ ۲. نرخ سد امروز را چک کن (بازده مؤثر صندوق درآمد ثابت؛ شهریور ۱۴۰۵ حدود ۳۹ تا ۴۰ درصد) + ├─ ۳. غربال نقدشوندگی: حجم روزانه، تعداد سفارش، اسپرد نسبی + │ اسپرد > ۳ درصد یا حجم < ۲۰ قرارداد ⇒ حذف + ├─ ۴. محاسبه برای هر کاندیدا: ارزش منصفانه، نوسان ضمنی، انحراف تساوی، بازده باکس، بازده تبعی، مبنای آتی + ├─ ۵. کسر همهٔ هزینه‌ها: کارمزد دو طرف معامله، کارمزد اعمال، مالیات تسویهٔ فیزیکی، اسپرد + ├─ ۶. مقایسه با نرخ سد + │ حاشیه < ۳ درصد (آربیتراژ) یا < ۵ درصد (با اهرم) ⇒ رد کن + ├─ ۷. بررسی ظرفیت: آیا با سرمایهٔ من، وجه تضمین و سقف موقعیت اجازهٔ اجرا می‌دهد؟ + ├─ ۸. تعیین اندازه: وجه تضمین هر موقعیت حداکثر ۲۰ درصد سرمایه؛ حداقل ۴۰ درصد نقد برای اخطاریه + ├─ ۹. ثبت سفارش هم‌زمان (پاهای آربیتراژ باید در یک پنجرهٔ زمانی کوتاه اجرا شوند) + └─ ۱۰. ثبت در دفتر: دلیل ورود، بازده انتظاری، بازده واقعی، دلیل خروج، درس +``` + +## الگوریتم غربال (شبه‌کد) + +``` +ورودی: داده روز D، نرخ سد H (مثلاً ۰٫۳۷)، سقف ریسک +برای هر گروه هم‌سررسید در هر دارایی پایه: + اگر نقدشوندگی ضعیف ⇒ بعدی + r = سالانه‌سازی (بازده پایه/باکس/تبعی پس از هزینه) + edge = r − H − جریمهٔ نقدشوندگی − جریمهٔ اهرم + اگر edge ≥ ۰٫۰۳ ⇒ به لیست فرصت‌ها اضافه کن +مرتب‌سازی نزولی بر اساس edge +برای هر فرصت به‌ترتیب: + اگر سقف موقعیت و وجه تضمین اجازه بدهد ⇒ ثبت سیگنال با اندازهٔ محاسبه‌شده + وگرنه ⇒ ذخیره در صف انتظار +گزارش: فهرست سیگنال‌ها + توضیح ریاضی هرکدام + ریسک‌های باقی‌مانده +``` + +این الگوریتم عیناً در ابزار `tools/derivatives_scout.py` پیاده شده است. خروجی، «چه بخر و چه بفروش» نیست؛ «کجا تفاوت ریاضی با نرخ سد از حاشیهٔ اطمینان عبور می‌کند» است. + +## مدیریت سرمایه (بخشی که ۹۰ درصد افراد حذف می‌کنند) + +- سقف وجه تضمین درگیر: ۲۰ درصد سرمایه؛ بقیه آزاد. +- حداقل ۴۰ درصد نقد، فقط برای پاسخ به اخطاریهٔ وجه تضمین. +- حداکثر ۳ موقعیت هم‌زمان، و فقط در دارایی‌های پایهٔ غیرهمبسته. +- قاعدهٔ اندازه‌گیری: اگر یک ضرر ۲۵ درصدی در یک موقعیت، کل ماه را منفی می‌کند، اندازه نصف است. +- توقف معاملاتی: پس از سه ضرر پیاپی یا افت ۸ درصدی سرمایه، یک هفته توقف و بازبینی دفتر. + +{**_ریاضیات بدون مدیریت سرمایه، شبیه فرمول درست با باتری خالی است. نفرینِ نسبت‌های ریاضی این است که خروجی مثبت کوچک، با یک خطای اندازه‌گیری بزرگ صفر می‌شود._**} + +## سی روز اول: طرح اعتبارسنجی (بدون سرمایه‌گذاری جدی) + +۱. **روز ۱ تا ۳:** راه‌اندازی داده و ابزار. `python3 tools/derivatives_scout.py --demo --self-test`. +۲. **روز ۴ تا ۱۴:** ثبت روزانهٔ ۱۰ کاندیدا، بدون معامله؛ مقایسهٔ نرخ سد با بازده محاسبه‌شده. هدف: ساختن حافظهٔ تاریخی که بعداً بتوانید کالیبره کنید. +۳. **روز ۱۵ تا ۲۵:** معاملهٔ کاغذی؛ هر سیگنال را ثبت کنید و بازده انتظاری را با بازار واقعی مقایسه کنید. تفاوت، «هزینهٔ اجرا»ی شما را نشان می‌دهد. +۴. **روز ۲۶ تا ۳۰:** بازبینی. اگر در ۲۰ روز گذشته هرگز حاشیهٔ بیش از ۳ درصد ندیدید، بازار فعلی این مسیر را نمی‌دهد و باید سرمایه را جای دیگری ببرید. +۵. **فقط بعد از این چرخه:** شروع با حداقل سرمایهٔ ممکن روی استراتژی تبعی یا باکس. + +## خط قرمزها + +- هیچ‌کس، هیچ سیگنالی، هیچ پکیجی «سود تضمینی» ندارد؛ اگر کسی چنین گفت، کلاهبردار است. +- عضویت در گروه‌های سیگنال، پرداخت برای «آموزش تضمینی»، و واریز پول به حساب شخصی، سه الگوی رایج کلاهبرداری در ایران هستند. +- پلتفرم‌های معاملات ارز و اهرمی غیرمجاز، از نظر قانونی و ریسک ورشکستگی، جای بازی نیستند. +- مالیات، صورت‌حساب و مسیر پول را تمیز نگه دارید؛ شرط «پول سالم» فقط اخلاقی نیست، ریسک حقوقی هم دارد. +- هیچ‌وقت پول قرضی، پول اجاره یا پول تحصیل را وارد مشتقه نکنید. + +## لینک‌های مرجع (بررسی‌شده) + +- دستورالعمل معاملات اختیار معامله و جدول وجه تضمین: `neynavayan.ir` و `nibb.ir` (متن دستورالعمل سازمان بورس) +- آموزش اختیار معامله و کارمزدها: `learning.emofid.com/all-about-stock-options` و `optionbaaz.ir/article/57` +- آتی و تسویهٔ روزانهٔ بورس کالا: `imereport.ir` و `pasargadbroker.ir/blog/2025/07/derivative` +- اوراق اختیار فروش تبعی (فرمول بازده و شرایط نگه‌داری): `arka-invest.com` و اطلاعیه‌های عرضه در `shahrebours.com` +- کارمزد و مالیات معاملات سهام: `khanesarmaye.com/transaction-fees` +- آمار بازندگان خرد و اثر کارمزد: `fardintorkfar.com` و پژوهش‌های Newall & Weiss diff --git a/station/docs/02-ideas-iran-fa.md b/station/docs/02-ideas-iran-fa.md new file mode 100644 index 0000000000000000000000000000000000000000..3347b8382c80558e3dfae9d496a45b0bd9379244 --- /dev/null +++ b/station/docs/02-ideas-iran-fa.md @@ -0,0 +1,75 @@ +# پول سالم در ایران: چهارده مسیر، با احتمال واقعی + +**پروندهٔ پژوهشی ۲، تاریخ: ۲۲ سپتامبر ۲۰۲۶** +**قاعدهٔ بازی:** هر مسیر با پنج عدد سنجیده می‌شود: سرمایهٔ لازم، زمان تا اولین درآمد، درآمد ماهانهٔ واقع‌بینانه (تومان، سطح قیمت پاییز ۱۴۰۴)، احتمال موفقیت، و ریسک اصلی. درصدها **برآورد** کارشناسی‌اند، نه وعده. + +## جدول کامل (مرتب‌شده بر اساس «قابل اجرا بودن برای کسی که سرمایه ندارد») + +| # | مسیر | سرمایه | اولین درآمد | درآمد ماهانهٔ واقع‌بینانه | احتمال موفقیت | ریسک اصلی | +|---|---|---|---|---|---|---| +| ۱ | فروش مهارت به‌صورت پروژه‌ای (طراحی، برنامه‌نویسی، ترجمه) با کارفرمای داخلی | ۰ | ۲ تا ۶ هفته | ۱۵ تا ۶۰ میلیون | ۴۵ درصد | رقابت قیمت، دیرکرد پرداخت | +| ۲ | فروش مهارت به کارفرمای خارجی و دریافت ارز | ۰ تا ۵ میلیون | ۱ تا ۳ ماه | معادل ۴۰ تا ۲۰۰ میلیون | ۳۰ تا ۴۰ درصد | محدودیت پرداخت، تحریم، ریسک واسطه | +| ۳ | خدمات فنی محلی (تعمیر کولر، دوربین، برق، لوله‌کشی) | ۱۵ تا ۶۰ میلیون (ابزار) | ۲ تا ۴ هفته | ۲۵ تا ۷۰ میلیون | ۶۰ تا ۷۰ درصد | کار بدنی، آموزش اولیه | +| ۴ | آموزش خصوصی و کلاس آنلاین (ریاضی، زبان، کنکور) | ۰ | ۱ تا ۴ هفته | ۱۰ تا ۳۵ میلیون | ۵۰ درصد | فصل‌بندی، خستگی | +| ۵ | حسابداری و مالیات برای کسب‌وکارهای کوچک (سامانهٔ مؤدیان) | ۰ تا ۱۰ میلیون | ۳ تا ۸ هفته | ۲۰ تا ۵۰ میلیون | ۴۰ تا ۵۵ درصد | مسئولیت حقوقی، نیاز به آموزش | +| ۶ | طراحی سایت و سئوی محلی برای کسب‌وکارهای شهری | ۰ | ۱ تا ۲ ماه | ۲۵ تا ۸۰ میلیون | ۲۵ تا ۴۰ درصد | پیدا کردن مشتری اول | +| ۷ | خدمات هوش مصنوعی به کسب‌وکارهای کوچک (چت‌بات، محتوا، اتوماسیون) | ۰ تا ۱۰ میلیون | ۱ تا ۳ ماه | ۲۰ تا ۶۰ میلیون | ۲۰ تا ۳۵ درصد | بازار نو، انتظار غیرواقعی مشتری | +| ۸ | ادیت ویدیو، تامبنیل، پادکست برای تولیدکنندگان محتوای داخلی | ۰ تا ۲۰ میلیون | ۲ تا ۶ هفته | ۱۵ تا ۵۰ میلیون | ۳۵ تا ۵۰ درصد | رقابت شدید | +| ۹ | تولید و بسته‌بندی خانگی (غذا، ترشی، شیرینی، صنایع دستی) و فروش آنلاین | ۱۰ تا ۵۰ میلیون | ۱ تا ۳ ماه | ۸ تا ۳۰ میلیون | ۳۰ تا ۴۵ درصد | مجوز، فاسدشدنی | +| ۱۰ | واسطه‌گری کالا (زعفران، خشکبار، پسته) بین تولیدکننده و خریدار | ۲۰ تا ۱۰۰ میلیون | ۱ تا ۳ ماه | ۱۵ تا ۶۰ میلیون (پورسانت) | ۳۰ درصد | اعتماد طرفین، نوسان قیمت | +| ۱۱ | تدریس/مشاورهٔ تخصصی آنلاین برای خارج از ایران (به‌زبان انگلیسی) | ۰ | ۲ تا ۴ ماه | معادل ۳۰ تا ۱۵۰ میلیون | ۲۵ تا ۳۵ درصد | زبان، پیدا کردن بازار | +| ۱۲ | صندوق درآمد ثابت + صندوق طلا (لایهٔ حفظ سرمایه) | هر مقدار | فوری | اسمی ۳۷ تا ۴۰ درصد سالانه | بالا (با ریسک نکول کم) | تورم بالاتر از بازده اسمی | +| ۱۳ | آربیتراژ و مشتقه (پروندهٔ ۱) | بالای چند صد میلیون تومان | ۱ تا ۳ ماه | متغیر، ۰ تا ۳ درصد ماهانه | ۳۵ تا ۵۰ درصد | اجرا و نقدشوندگی | +| ۱۴ | خرید و اجاره‌دهی دارایی مولد (لپ‌تاپ، دوربین، دوچرخه، موتور) | ۵۰ تا ۳۰۰ میلیون | ۱ تا ۲ ماه | ۵ تا ۱۵ درصد ارزش دارایی | ۴۰ تا ۵۵ درصد | خرابی، فرار مشتری | + +## چرا ترتیب جدول مهم است + +سرمایهٔ کم، یعنی ترتیب جدول عملاً بزرگ‌ترین اهرم شما است. ردیف‌های ۱ تا ۸ «سرمایهٔ انسانی» می‌فروشند و از صفر شروع می‌شوند؛ ردیف ۱۲ به بعد دربارهٔ پول است و پول هم ندارید. بزرگ‌ترین بازده ای که در اختیار دارید این است که در ۹۰ روز اول یک مهارت قابل‌فروش به دست بیاورید و آن را به اولین مشتری بفروشید؛ هیچ مسیر مالی دیگری با سرمایهٔ صفر، این سرعت را ندارد. + +{**_محاسبهٔ فرصت: با نرخ سد امروز (بازده مؤثر صندوق درآمد ثابت حدود ۳۷ درصد)، ۱۰ میلیون تومان سرمایه در سال فقط ۳٫۷ میلیون تومان سود می‌دهد؛ در حالی که یک مهارت در ماه اول می‌تواند ۱۵ میلیون به بالا درآمد بسازد. یعنی در این نقطهٔ زندگی، یادگیری و فروش مهارت چند برابر بازار سرمایه برد دارد._**} + +## سه مسیر برتر برای شروع (ترکیب پیشنهادی) + +**الف. خدمات فنی محلی + آموزش مهارت دیجیتال.** اگر توان کار بدنی دارید، تعمیر کولر و نصب دوربین مداربسته در شهرهای متوسط و کوچک، نقدترین بازار ایران است: تقاضا ثابت، رقابت کم، پرداخت نقد. موازی آن، شب‌ها یک مهارت دیجیتال (ادیت ویدیو یا پایتون) یاد بگیرید تا در ماه سوم درآمد دوم بسازید. + +**ب. حسابداری مالیاتی برای کسب‌وکارهای کوچک.** سامانهٔ مؤدیان و صورت‌حساب الکترونیکی، برای میلیون‌ها مغازه و کارگاه دردسر جدید ساخته است و کسی که این کار را بلد باشد، ماهانه ۲ تا ۸ میلیون تومان از هر مشتری می‌گیرد. ورود با آموزش کوتاه ممکن است و درآمدش تکرارشونده (retainer) است. + +**ج. فروش ارزی مهارت، با مدیریت ریسک پرداخت.** درآمد دلاری در ایران شدنی است ولی مسیر پول، ریسک اصلی است. قاعده: فقط با واسطه‌های شناخته‌شده و قرارداد مکتوب؛ هر ۲۰۰ تا ۵۰۰ دلار تسویه کنید، نه ماهانه؛ نقدینگی را در صندوق درآمد ثابت و صندوق طلا پخش کنید. + +## نسخهٔ طلایی: هفت قاعده‌ای که بازده را چند برابر می‌کند + +۱. **به کسی بفروشید که پول دارد.** مشتری B2B، پرداخت بزرگ‌تر و پایدارتر دارد. مغازه‌دار و کارخانه نمی‌توانند مثل مشتری شخصی، پروژه را بی‌خیال شوند. +۲. **درآمد تکرارشونده بسازید.** پشتیبانی ماهانه، اشتراک محتوا، قرارداد نگهداری. یک درآمد ثابت ماهانه، از پنج پروژهٔ یک‌بار مصرف بهتر است. +۳. **نمونهٔ کار قبل از قیمت.** اولین سه کار را با تخفیف بگیرید اما نه مجانی اگر می‌توانید نمونهٔ عمومی بسازید که کارتان را نشان دهد. +۴. **قیمت را بر اساس ارزش، نه ساعت.** بپرسید این کار برای مشتری ماهی چقدر ارزش دارد؛ نرخ خود را از آن بسازید. +۵. **هیچ‌وقت یک مشتری نداشته باشید.** حداقل سه مشتری هم‌زمان؛ ترک یک مشتری نباید درآمد ماه را صفر کند. +۶. **پول اول، کار بعد.** درصد علی‌الحساب، تحویل پله‌ای، و برای مشتری ناشناس پیش‌پرداخت کامل. +۷. **بخشی از هر درآمد را به دارایی مولد ببرید.** قاعدهٔ ساده: ۳۰ درصد درآمد را به خودتان بدهید، ۵۰ درصد خرج زندگی، ۲۰ درصد پس‌انداز. با تورم فعلی، پس‌انداز در صندوق درآمد ثابت و طلا ارزش پول را نگه می‌دارد. + +## نکتهٔ تلخی که هیچ تبلیغی نمی‌گوید + +با تورم سالانهٔ نزدیک به ۷۰ درصد و بازده اسمی ۴۰ درصد، پول در صندوق درآمد ثابت **قدرت خریدش را از دست می‌دهد** (رشد اسمی ۴۰ درصد در برابر تورم ۷۰ درصد). یعنی صندوق درآمد ثابت لایهٔ **نقدینگی و امنیت** است، نه رشد. برای حفظ ارزش باید بخشی از پس‌انداز در دارایی‌های مقاوم به تورم (طلا، صندوق طلا، مسکن کوچک، ارز مولد، تجهیزات قابل اجاره) باشد. ترتیب درست: اول نقدینگی امن برای سه ماه زندگی، بعد مهارت درآمدزا، بعد دارایی مقاوم به تورم، و آخر از همه لایهٔ پرریسک. + +{**_هیچ ترکیبی از صندوق‌ها و طلا، شما را با سرمایهٔ کم ثروتمند نمی‌کند. کاری که واقعاً ثروت می‌سازد، فروش مهارت با قیمت رو به بالا و سپس سرمایه‌گذاری مازاد است. این جمله را با جدول همین پرونده بسنجید: ردیف ۱ با سرمایهٔ صفر، در ماه اول بیشتر از ردیف ۱۲ با ۱۰۰ میلیون تومان درمی‌آورد._**} + +## چه چیزی را هرگز نکنید + +- طرح‌های «ضریب سود تضمینی» با وعدهٔ ۲۰ درصد ماهانه، شبکه‌ای هستند نه سرمایه‌گذاری. +- ترید فارکس و ارز دیجیتال با پلتفرم غیرمجاز، در ایران فاقد حمایت حقوقی است. +- خرید و فروش سیگنال، آموزش‌های گران با وعدهٔ استخدام، و پیش‌فروش محصولی که وجود ندارد. +- قرض گرفتن برای معاملهٔ اهرمی. اهرم برای کسی است که سرمایهٔ اضافه دارد، نه کسی که پول قرض گرفته. + +## برنامهٔ ۹۰ روز + +**روز ۱ تا ۳۰:** انتخاب یک مهارت (از جدول بخش الف یا ب)، دو ساعت تمرین روزانه، ساخت سه نمونه‌کار واقعی. +**روز ۳۱ تا ۶۰:** معرفی به ۵۰ مشتری ممکن (حضوری، اینستاگرام، معرفی دوستان)، اولین پروژهٔ پول‌دار، دریافت بازخورد. +**روز ۶۱ تا ۹۰:** افزایش قیمت، تبدیل دو مشتری به قرارداد ماهانه، و کنار گذاشتن ۲۰ درصد درآمد در «صندوق پایه» (صندوق درآمد ثابت). از روز ۹۱ می‌توانید ۱۰ درصد درآمد را برای اعتبارسنجی مسیرهای بازار سرمایه (پروندهٔ ۱) جدا کنید. + +## نگاشت مهارت‌ها (فهرست پیشنهادی برای ساخت در HARNESSES) + +۱. `iran-derivatives-scout`: دیده‌بان ریاضی مشتقه. **ساخته شد در همین نوبت.** +۲. `income-plan-forge`: گرفتن سرمایه، زمان، مهارت و شهر؛ خروجی: برنامهٔ ۹۰ روزه با هدف عددی و ارزیابی هفتگی. +۳. `price-and-proposal`: ماشین قیمت‌گذاری و نوشتن پیشنهاد کار برای مشتری داخلی و خارجی. +۴. `tax-paperwork-iran`: چک‌لیست سامانهٔ مؤدیان و تعهدات مالیاتی کسب‌وکار کوچک. + +ساخت هر مهارت در این محیط، با سیاست خودش، پیکربندی دروازه و بازبینی skeptic انجام می‌شود؛ ترتیب پیشنهادی همین ترتیب بالا است و به انتخاب صاحب پرونده بستگی دارد. diff --git a/station/docs/03-investor-and-first-money-fa.md b/station/docs/03-investor-and-first-money-fa.md new file mode 100644 index 0000000000000000000000000000000000000000..dc484bfc9ee0704d0d2988b0a6ad42cb14dc62cb --- /dev/null +++ b/station/docs/03-investor-and-first-money-fa.md @@ -0,0 +1,95 @@ +# سرمایه‌گذار و اولین پول: بستهٔ عملی + +**پروندهٔ پژوهشی ۳، تاریخ: ۲۲ سپتامبر ۲۰۲۶** +**درخواست صاحب پرونده:** «اگر سرمایه‌گذار پیدا کنم هم برایم ایده بده… ولی باید توانایی توجیه برای سرمایه‌گذاری را داشته باشم.» + +## صداقت اول، قبل از هر ایده‌ای + +سه واقعیت را پیش از بقیهٔ این پرونده بخوانید، چون جهت همهٔ تصمیم‌ها را عوض می‌کنند: + +۱. **پول دیگران را برای معاملهٔ مشتقه و ارز و سهام نگیرید.** گرفتن پول از دیگران برای سرمایه‌گذاری در بازار، در ایران نیازمند مجوز سازمان بورس (سبدگردانی یا مشاور سرمایه‌گذاری) است؛ بدون مجوز، هم غیرقانونی است و هم اگر پول کم شود، شما بدهکار می‌مانید و آبرویتان می‌رود. سرمایه‌گذار واقعی هم به کسی که پول ندارد و سابقه ندارد، پول نمی‌دهد که در بازار پرنوسان بخورد. +۲. **سرمایه‌گذار برای کسب‌وکار می‌دهد، نه برای امید.** آنچه سرمایه‌جذب می‌کند «مشتری واقعی» است: کسی که امروز پول می‌دهد و کالا یا خدمت می‌گیرد. دو مشتری پرداخت‌کننده، از هر توجیه و طرح رنگی قوی‌تر است. +۳. **ارزان‌ترین سرمایه‌گذار دولت است، نه آشنا و رفیق.** تسهیلات قرض‌الحسنهٔ مشاغل خانگی با کارمزد حدود ۴ درصد سالانه، روی کاغذ از هر شریکی منصف‌تر است و آبروی شما را گرو نمی‌گذارد. + +{**_اشتباه رایج: خیلی‌ها اول دنبال پول می‌روند و بعد دنبال مشتری. ترتیب درست برعکس است: مشتری اول، بعد پول. با مشتری، پول خودش می‌آید؛ با پول و بی‌مشتری، فقط بدهی می‌آید._**} + +## پنج مسیر واقعی برای جذب سرمایه در ایران + +### مسیر ۱. تسهیلات قرض‌الحسنهٔ اشتغال و مشاغل خانگی (بهترین نقطهٔ شروع) + +- سقف فردی حدود ۲۰۰ میلیون تومان با بازپرداخت تا ۶۰ ماه و کارمزد حدود ۴ درصد سالانه؛ برای برخی رسته‌های شغلی مصوب تا حدود ۳۵۰ میلیون تومان. +- تضمین: اعتبارسنجی متقاضی به‌همراه یک ضامن معتبر یا سفته. +- مسیر ثبت‌نام: سامانهٔ مشاغل خانگی به نشانی `smkh.mcls.gov.ir` و سامانهٔ جامع تسهیلات اشتغال `tek.mcls.gov.ir` و پنجرهٔ ملی `my.gov.ir`. +- طرح اشتغال جوانان با همکاری صندوق کارآفرینی امید: نرخ حدود ۱۵ درصد با شرط تأمین حدود ۲۰ درصد آوردهٔ خودِ متقاضی. +- بنیاد برکت: تسهیلات خرد بر پایهٔ فعالیت (مشاغل خانگی تولیدی تا حدود ۱۰۰ میلیون، خدماتی تا حدود ۳۰ میلیون، کشاورزی تا حدود ۵۰ میلیون، روستایی تا حدود ۱۵۰ میلیون). +- شرط عملی قبولی: یک «طرح کسب‌وکار» کوتاه و باورپذیر که در بخش بعد ساختارش را می‌سازیم؛ نه آرزو، بلکه عدد و مشتری. + +### مسیر ۲. مشتری به‌عنوان سرمایه‌گذار: پیش‌فروش + +پول را از کسی بگیرید که کالا یا خدمت را می‌خواهد. پیش‌فروش با تخفیف محدود (مثلاً ۱۰ درصد) فقط به مشتریانی که می‌شناسید، منبع سرمایه در گردش است و ریسک شرعی و قانونی هم ندارد. مثال: ۱۰ سفارش پیش‌فروش ۵ میلیون تومانی مساوی است با ۵۰ میلیون تومان نقدِ بدون بدهی. + +### مسیر ۳. مضاربه: شریکِ پول‌دار و بی‌وقت + +مضاربه یک عقد شرعی و قانونی است: یکی سرمایه می‌دهد، دیگری کار می‌کند، سود طبق نسبت توافق‌شده تقسیم می‌شود و زیان مالی (به‌جز تقصیر) بر عهدهٔ صاحب سرمایه است. این ساختار برای **تجارت کالا** ساخته شده است، نه برای معامله در بازار مشتقه. نمونهٔ کاربردی: سرمایه‌دار پول می‌دهد، شما کالا (زعفران، خشکبار، لوازم جانبی موبایل، پوشاک) را از عمده‌فروشی می‌خرید، می‌فروشید و سود تقسیم می‌شود. برای اینکه این مسیر سالم بماند: قرارداد مکتوب، دفتر حساب شفاف، رسید خرید و فروش، و نسبت سود مشخص از قبل. + +### مسیر ۴. شریک تجهیزاتی + +کسی که تجهیزات دارد و استفاده نمی‌کند (دوربین، لپ‌تاپ، پرینتر، چرخ‌خیاطی، ابزار برق) را شریک کنید: تجهیزات از او، کار و بازار از شما، سود تقسیمی. این نوع شراکت برای سرمایه‌گذار جذاب است چون دارایی‌اش از دست نمی‌رود و برای شما ریسک نقدی صفر دارد. + +### مسیر ۵. شریک مکمل + +دو نفر که مهارت‌های مکمل دارند، هر دو سرمایه‌گذار خودشان هستند. مثال: کسی که ادیت ویدیو بلد است با کسی که فروش و ارتباط با مشتری بلد است. درآمد تقسیم می‌شود، ریسک نصف می‌شود، و برای هر دو نمونه‌کار و سابقه ساخته می‌شود. + +## توجیه سرمایه‌گذاری: ساختار یک‌صفحه‌ای + +هر سرمایه‌گذاری، عاقل یا احمق، پنج سؤال می‌پرسد. اگر یک صفحه داشته باشید که هر پنج را جواب بدهد، از ۹۰ درصد کسانی که فقط حرف می‌زنند جلوترید. + +| بخش | چه چیزی بنویسید | چه اشتباهی نکنید | +|---|---|---| +| فرصت | چه کسی، چه دردی دارد، امروز چقدر پول برای آن می‌دهد | تعریف کلی بازار بدون مشتری مشخص | +| راه‌حل | دقیقاً چه می‌فروشید، به چه قیمتی، با چه هزینه‌ای | توضیح فنی طولانی که سرمایه‌گذار نمی‌فهمد | +| شواهد تقاضا | نام مشتری، تعداد سفارش، پیش‌فروش، پیام واقعی مشتری | وعدهٔ «اگر پول برسد مشتری می‌آید» | +| عددها | قیمت فروش، بهای تمام‌شده، حاشیهٔ سود، هزینهٔ ماهانه، نقطهٔ سربه‌سر، بازگشت سرمایه | خوش‌بینی بدون سناریوی بد | +| بازگشت پول به سرمایه‌گذار | سهم از سود، بازپرداخت اقساطی، یا ترکیب هر دو، با زمان‌بندی روشن | وعدهٔ سود ثابت و تضمینی | +| ریسک و مهار آن | سه ریسک اصلی و پاسخ عملی هرکدام | گفتن «ریسکی ندارد» | +| شفافیت | دفتر حساب، گزارش ماهانه، دسترسی سرمایه‌گذار به اعداد | حساب شخصی و بدون سند | + +سه سناریو همیشه آماده داشته باشید: بد (چقدر طول می‌کشد به سربه‌سر برسیم)، متوسط (عدد واقع‌بینانه)، خوب. سرمایه‌گذارها به سناریوی بد بیشتر اعتماد می‌کنند تا به وعدهٔ خوب؛ چون نشان می‌دهد شما حساب کرده‌اید. + +## متن نمونه: پیشنهاد به سرمایه‌گذار + +> سلام جناب آقای احمدی. من رضا هستم و در کار بسته‌بندی و پخش خشکبار در محلهٔ خودمان فعالیتم را شروع کرده‌ام. یک کسب‌وکار کوچک راه انداخته‌ام که پسته و بادام بسته‌بندی‌شده را به مغازه‌های محله با قیمت هر بسته ۳۵۰ هزار تومان می‌فروشد. تا الان ۱۲ مشتری ثابت داشته‌ام و ۱۸ میلیون تومان فروش کرده‌ام؛ فاکتورها و پیام‌های مشتری‌ها را می‌توانم نشان بدهم. برای افزایش ظرفیت خرید و بسته‌بندی، ۸۰ میلیون تومان سرمایه لازم دارم که صرف موجودی و تجهیزات بسته‌بندی می‌شود. پیشنهادم این است: ۳۰ درصد از سود ماهانه تا سقف بازگشت کامل سرمایه در ۱۰ ماه، به‌همراه گزارش حساب هر ماه. اگر مایل باشید، در ۱۵ دقیقه عددها، سناریوی بد و ریسک‌ها را نشان می‌دهم و بعد تصمیم بگیرید. + +{**_این متن نمونه است؛ نام، کالا و عددها را با واقعیت خودتان عوض کنید، ولی ساختار جمله‌ها را نگه دارید: مشتری، عدد فروش، شواهد، مبلغ درخواستی، ساختار بازگشت، و دعوت به یک جلسهٔ کوتاه._**} + +### پاسخ به پنج مخالفت رایج + +۱. «سودی که می‌گویی زیاد است، باور نمی‌کنم.» پاسخ: «درست است، برای همین سناریوی بد را هم نوشته‌ام: در بدترین حالت [عدد]. بیایید بر مبنای همان تصمیم بگیریم.» +۲. «چرا خودت این کار را نمی‌کنی اگر سود دارد؟» پاسخ: «چون سرمایه‌اش را ندارم؛ کار و بازارش را دارم. برای همین سهم کار و سهم پول را جدا کرده‌ام.» +۳. «تضمین چه می‌دهی؟» پاسخ: «تضمین سود نمی‌دهم؛ هیچ‌کس نباید بدهد. اما حساب‌ها باز است، رسید خرید و فروش هست و هر ماه گزارش می‌دهم.» +۴. «پولم را چه وقت پس می‌گیرم؟» پاسخ دقیق و عددی، با تاریخ. اگر نمی‌توانید تاریخ بدهید، ساختار پیشنهادتان خراب است. +۵. «اگر ضرر شد چه؟» پاسخ شفاف دربارهٔ تقسیم زیان، و این جمله: «اگر شرایط بد شود، اولین کسی که ضرر می‌بیند من هستم، چون کار و زمانم را گذاشته‌ام.» + +## اولین پول در ۱۴ روز (با صفر سرمایه) + +اگر سرمایه و سرمایه‌گذار فعلاً نیست، این ۱۴ روز نان می‌دهد و همان‌زمان «شواهد تقاضا» برای توجیه‌نامه‌تان می‌سازد. + +**مسیر الف. بدنی و خدماتی (پرداخت نقد، شروع امروز):** کارگری روزمزد ساختمان، کمک‌بار، تمیزکاری منزل و دفتر، شست‌وشوی خودرو، جابه‌جایی وسایل، نصب و راه‌اندازی ساده. نرخ نمونهٔ ۱۴۰۴ در شهرهای متوسط: روزانه ۳ تا ۸ میلیون تومان بسته به تخصص و شهر؛ تمیزکاری منزل ۱ تا ۳ میلیون برای هر سفارش. + +**مسیر ب. دیجیتال با موبایل:** تایپ و صفحه‌آرایی، ساخت تامبنیل، ادیت ویدیوهای کوتاه، مدیریت صفحهٔ اینستاگرام مغازه‌ها، تبدیل فایل، ترجمهٔ ساده. مشتری اول در همسایگی خودتان است: آرایشگاه، تعمیرگاه، مطب، فروشگاه لباس. نرخ شروع: ۱٫۵ تا ۵ میلیون برای هر سفارش کوچک. + +**مسیر ج. فروش واسطه‌ای بدون سرمایه:** عکس و مشخصات کالا را از عمده‌فروشی یا تولیدکننده بگیرید، آنلاین آگهی کنید، بعد از پرداخت مشتری خرید کنید. درصد شما ۱۰ تا ۲۰ درصد. فقط با کالای غیرفاسدشدنی و حجم کوچک شروع کنید. + +### چک‌لیست سه روز اول + +روز ۱: انتخاب یک مسیر (فقط یکی)، نوشتن یک پیام فروش دو خطی، فهرست ۲۰ مشتری ممکن از میان آشناها، همسایه‌ها، مغازه‌های محله. +روز ۲: فرستادن ۲۰ پیام یا مراجعهٔ حضوری به ۱۰ مغازه؛ هدف: دو گفت‌وگوی واقعی، نه بیست پیام بی‌پاسخ. شب: قیمت‌گذاری و نوشتن نمونهٔ کار. +روز ۳: انجام اولین سفارش حتی کوچک، گرفتن پول، و درخواست یک معرفی از مشتری. هر روز همین چرخه: پیام، سفارش، تحویل، معرفی. + +## قرمزها + +- کسی که «سرمایه‌گذار» معرفی می‌کند و اول از شما پول یا ودیعه می‌خواهد، کلاهبردار است. +- وعدهٔ «سود ثابت ماهانه» از هر کسی، رد است؛ در قرارداد هم اگر بیاید، باطل است. +- پول قرضی یا تسهیلات را وارد بازار مشتقه و ارز نکنید؛ آن پول باید اقساط بدهد، و بازار اهرمی اقساط نمی‌شناسد. +- با پول شریک، معاملهٔ اهرمی نکنید؛ حتی با مجوز هم این کار نیازمند ساختار رسمی و گزارش‌دهی است. +- هیچ‌وقت دو نفر را هم‌زمان در یک ساختار شفاهی شریک نکنید؛ شراکت شفاهی، پایانش دعوا است. diff --git a/station/docs/04-trading-desk-plan-fa.md b/station/docs/04-trading-desk-plan-fa.md new file mode 100644 index 0000000000000000000000000000000000000000..59d82bdd03d075fd25c6dddb99c0bb4d7aa45069 --- /dev/null +++ b/station/docs/04-trading-desk-plan-fa.md @@ -0,0 +1,105 @@ +# میز معاملات: نقشهٔ عملیاتی برای یک برنامه‌نویس ساده + +**پروندهٔ پژوهشی ۴، تاریخ: ۲۲ سپتامبر ۲۰۲۶** +**درخواست:** شرکتی گفته «چیزی بساز که هر لحظه، با ریاضیات و الگوریتم و تحلیل خبر، خرید و فروش مشتقه را تصمیم بگیرد و برنامه زیر نظر کاربر کار کند». این پرونده می‌گوید این خواسته کجای واقعیت است، چه چیزی از امروز قابل ساختن است، و چه چیزی باید در قرارداد نوشته شود. + +## سه واقعیتی که باید قبل از امضای قرارداد بدانید + +۱. **معاملات الگوریتمی خودکار در بورس و فرابورس ایران مجاز نیست.** سازمان بورس از مهر ۱۳۹۹ استفاده از معاملات الگوریتمی و تقسیم سفارشات توسط مشتریان برخط را «تا اطلاع ثانوی» ممنوع کرد و کارگزاران موظف‌اند دسترسی مشتریانی که امکان معاملات الگوریتمی دارند را غیرفعال کنند. استثنا: بازارگردانان دارای مجوز با شناسهٔ مشخص. پس هر محصولی که «خودکار سفارش بفرستد» بسازید، هم شما و هم شرکت را در معرض تخلف قرار می‌دهد. +۲. **پس تعریف درست محصول، «میز تصمیم و نظارت» است، نه «ربات معامله‌گر».** برنامه می‌شنود، محاسبه می‌کند، هشدار می‌دهد، ریسک را می‌سنجد، سناریو می‌سازد و در یک داشبورد نشان می‌دهد؛ **انسان دستور نهایی را می‌زند.** این هم دقیقاً همان «نظارت کاربر» است که شرکت خواسته، و هم قانونی است. +۳. **هیچ‌کس، هیچ برنامه‌ای روی زمین، سود را تضمین نمی‌کند.** آنچه یک برنامه می‌تواند تضمین کند سه چیز است: سرعت محاسبه، انضباط ریسک، و ثبت دقیق تصمیم‌ها. اگر شرکت «سود تضمینی» می‌خواهد، آن قرارداد را امضا نکنید؛ ضررش را شما می‌دهید. + +{**_جمع‌بندی صادقانه: در بازار ایران، «سریع‌تر معامله کردن» هیچ ارزشی ندارد چون معاملهٔ الگوریتمی ممنوع است. ارزش قابل فروش شما این است که اطلاعات را سریع‌تر از انسان بخوانید و ریسک را دقیق‌تر از انسان بسنجید._**} + +## کارخانهٔ داده: از کجا و با چه چیزی + +| لایهٔ داده | منبع در ایران | وضعیت | +|---|---|---| +| قیمت لحظه‌ای سهام، آپشن، آتی | سامانهٔ `tsetmc` (بازار ناظر) و کتابخانه‌های پایتونی مثل `tsetmc-api` و `codal-tsetmc` (نصب با `pip install tsetmc-api`) | رایگان، ولی بدون تعهد؛ نقطه‌به‌نقطه هر چند ثانیه بخوانید، نه هر میلی‌ثانیه | +| ریزمعاملات و دادهٔ تاریخی | وب‌سرویس‌های تجاری داخلی؛ نمونهٔ عمومی `brsapi.ir` (نیازمند کلید) | پرداختی یا با کلید آزمایشی | +| اطلاعیه‌های رسمی شرکت‌ها | سامانهٔ کدال `codal.ir` (اعلامیه‌ها، صورت‌های مالی، افزایش سرمایه، تقسیم سود) | رایگان و رسمی؛ منبع قانونی برای «خبر مهم» | +| خبر و تحلیل | خبرگزاری‌های داخلی با فید RSS و کانال‌های خبری | رایگان؛ برای امتیاز احساسی خبر استفاده می‌شود | +| کلید سفارش | کارگزاران با وب‌سرویس؛ برخی کارگزاران دسترسی API نمی‌دهند (نمونه: پاسخ کارگزاری آگاه در سال ۱۴۰۱: «این سرویس وجود ندارد») | باید همان شرکت، دسترسی خودش را از کارگزار بگیرد | +| درگاه هوش مصنوعی متن | ابزار `jev-gate.py` در همین محیط، با کلید در متغیر محیطی (`TYPESAFE_API_KEY` یا `AI_GATEWAY_API_KEY` یا `OPENROUTER_API_KEY`) | زیرساخت آماده است؛ کلید زنده باید تأمین شود، وگرنه برچسب «شاهد محلی» می‌خورد | + +## معماری پیشنهادی در یک نگاه + +``` +[۱ منابع داده] tsetmc · کدال · خبرها · آتی و گواهی سپرده + ↓ +[۲ لایهٔ نرمال‌سازی] پاک‌سازی، یکسان‌سازی نمادها، ذخیره در SQLite + فایل روزانه + ↓ +[۳ موتور ریاضی] ارزش منصفانه · نوسان ضمنی · تساوی پوت‌کال · باکس اسپرد · + پایهٔ نقدی‌آتی · کمینهٔ بازده تبعی · نقدشوندگی و اسپرد + ↓ +[۴ لایهٔ خبر و رویداد] کدال و خبر → خلاصهٔ ساخت‌یافته با هوش مصنوعی → + «رویداد تأثیرگذار» با جهت، بزرگی تقریبی و سطح اطمینان + ↓ +[۵ موتور تصمیم] احتمال، ارزش انتظاری، حاشیهٔ اطمینان نسبت به نرخ سد + ↓ +[۶ مدیر ریسک] سقف وجه تضمین · فاصله از اخطاریه · سقف هم‌جهت بودن · + توقف معاملاتی · همبستگی پوزیشن‌ها + ↓ +[۷ داشبورد نظارت] هشدار، دلیل هر پیشنهاد، دکمهٔ «تأیید و ادامه» برای انسان + ↓ +[۸ دفتر و ممیزی] ثبت هر توصیه، هر تأیید، هر رد، بازده انتظاری در برابر واقعی +``` + +نکتهٔ مهندسی: خروجی لایهٔ ۳ و ۴ هرگز مستقیماً به سفارش تبدیل نمی‌شود؛ همیشه از لایهٔ ۶ و ۷ می‌گذرد. این خط، هم قانونی است و هم چیزی است که شما را در برابر «چرا ضرر کردی؟» از شرکت حفظ می‌کند. + +## برنامهٔ تحویل در پنج فاز + +**فاز ۰ (سه روز):** یک صفحه، یک تصمیم. با شرکت روشن کنید خروجی محصول «پیشنهاد و هشدار» است، نه «سفارش خودکار». دامنهٔ دارایی‌ها (فقط آپشن؟ آتی؟ کدام نمادها؟) و سقف سرمایهٔ آزمون را کتبی بگیرید. + +**فاز ۱ (دو هفته):** اسکلت کاری. اتصال به داده (اول شبیه‌ساز، بعد tsetmc)، پایگاه‌دادهٔ محلی، پنل متنی، و همان ابزار ریاضی موجود (`derivatives_scout.py`) به‌عنوان موتور محاسبه. خروجی: هر دقیقه یک گزارش «وضعیت بازار». + +**فاز ۲ (سه تا چهار هفته):** لایهٔ خبر. خواندن کدال و خبر، خلاصه‌سازی با هوش مصنوعی، تشخیص رویدادهای مهم (افزایش سرمایه، تقسیم سود، تعدیل، توقف نماد)، و اتصال آن به موتور تصمیم. خروجی: هشدار «این خبر روی این نماد اثر دارد». + +**فاز ۳ (چهار هفته):** آموزش و اعتبارسنجی. اجرای «معاملهٔ کاغذی» روی دادهٔ گذشته و بعد روی دادهٔ زنده، بدون پول. معیار قبولی: انضباط (چند درصد سیگنال‌ها اجرا شد)، صحت محاسبه، و رفتار سیستم در روز شلوغ. + +**فاز ۴ (پیوسته):** داشبورد نظارت کامل، گزارش هفتگی، و نسخهٔ دوم موتور تصمیم با وزن‌دهی بر پایهٔ نتایج واقعی. + +**فاز ۵ (اختیاری، بعد از شش ماه سابقه):** اگر شرکت مجوز لازم را داشت، گفت‌وگو با کارگزار برای اتصال قانونی و بررسی وضعیت ابلاغیهٔ معاملات الگوریتمی در آن زمان. + +## چه چیزی به شرکت قول بدهید و چه چیزی نه + +**بدهید:** سرعت پایش (صدها نماد به‌جای چند نماد)، محاسبهٔ دقیق بازده پس از کارمزد، هشدار رویداد کدال در چند دقیقه، انضباط ریسک، دفتر ممیزی و گزارش‌های قابل ارائه. +**ندهید:** درصد سود، «تضمین»، «بدون شانس بودن»، و هر عددی که در معاملهٔ کاغذی به دست نیامده است. برای هر عدد، سناریوی بد را هم نشان بدهید. + +## قرارداد: چهار بند حیاتی + +۱. موضوع قرارداد «تحویل نرم‌افزار و مستندات» باشد، نه «تحقق سود». +۲. بند صریح: توصیه‌های نرم‌افزار جنبهٔ کمک‌تصمیم دارد؛ تصمیم نهایی و مسئولیت معامله با کاربر است. +۳. پرداخت پله‌ای بر پایهٔ تحویل فازها (۴۰ درصد پیش، ۳۰ درصد بعد از فاز ۲، ۳۰ درصد بعد از پذیرش فاز ۳). +۴. ممنوعیت استفاده از اطلاعات نهانی، دستکاری قیمت و انتشار سیگنال برای دیگران؛ و تأیید کتبی شرکت که دسترسی‌ها و مجوزهای لازم را دارد. + +## ایده‌های بهتر در همین بازار (با احتمال موفقیت واقع‌بینانه) + +| # | ایده | چه چیزی می‌فروشید | نیاز به مجوز معاملاتی | برآورد احتمال موفقیت | +|---|---|---|---|---| +| ۱ | دستیار تحلیل کدال و خبر برای معامله‌گران | اشتراک ماهانهٔ هشدار و خلاصه | ندارد | ۴۰ تا ۵۵ درصد | +| ۲ | داشبورد ریسک برای معامله‌گران آپشن | اشتراک یا نصب اختصاصی | ندارد | ۳۵ تا ۵۰ درصد | +| ۳ | دیده‌بان ریاضی فرصت‌ها (پایهٔ آتی، باکس، تبعی) | گزارش روزانه یا اشتراک | ندارد | ۳۰ تا ۴۵ درصد | +| ۴ | ساخت سفارشی همین میز برای کارگزاری یا شرکت | پروژهٔ نرم‌افزاری | ندارد | ۳۵ تا ۵۰ درصد | +| ۵ | معاملهٔ حساب خودتان با همین ابزار | سود و زیان خودتان | دارد (محدودیت‌ها) | ۲۰ تا ۳۵ درصد | +| ۶ | ربات ارسال سفارش و سرخطی | فروش نرم‌افزار | تخلف | نزدیک صفر؛ وارد نشوید | + +مقایسهٔ ردیف ۱ با ردیف ۵ مهم‌ترین جملهٔ این پرونده است: **فروش ابزار به معامله‌گران، از معامله‌کردن با ابزار، هم امن‌تر است و هم برای یک برنامه‌نویس با سرمایهٔ صفر، سریع‌تر به پول می‌رسد.** + +## دستمزد و موقعیت شما + +اگر فقط یک برنامه‌نویس ساده هستید، جای شما در این پروژه «سازندهٔ سیستم» است، نه «مدیر سرمایه». سه سناریو: + +- **پروژه‌ای (امن):** مبلغ ثابت برای هر فاز، تحویل کد و مستندات. پیشنهاد: معادل درآمد سه تا شش ماه یک برنامه‌نویس، بسته به دامنه. +- **اشتراک (بهتر):** همان سیستم را به چند شرکت و کارگزاری اجاره بدهید؛ درآمد پیوسته و ریسک پخش‌شده. +- **سهیم در سود (فقط با شرط):** اگر شرکت اصرار داشت، فقط برای رشته‌ای که خودتان قانونی می‌دانید، با سقف مسئولیت مشخص، و با این جمله در قرارداد که «حداکثر ضرر قابل مطالبه، سقف پرداخت دریافتی شماست، نه بیشتر». + +## سه چیز که این پروژه را می‌کشد + +۱. وعدهٔ سود به شرکت، در گفت‌وگوی شفاهی. همان جمله بعداً علیه شما استفاده می‌شود. +۲. اتصال مستقیم سفارش بدون نظارت انسان. تخلف، مسدودی حساب و از دست رفتن کار. +۳. تماس با «کلید دادهٔ رایگان» ناشناس و دادن دسترسی حساب. کلاهبرداری رایج این بازار است. + +## نسخهٔ امروز چه می‌تواند بکند + +همین حالا در همین محیط، یک نمونهٔ کارآمد ساخته شد: موتور ریاضی `derivatives_scout.py` با دروازه‌های نقدشوندگی، محاسبهٔ بازده پس از کارمزد و آزمون‌های واحد. قدم بعدی، وصل کردن آن به tsetmc و کدال و پروندهٔ دفتر معاملات است. برای اجرای آزمایشی روی داده‌های ساختگی، پروندهٔ `README-FA.md` همین پوشه و بخش «اجرا» را ببینید. diff --git a/station/docs/05-data-routes-fa.md b/station/docs/05-data-routes-fa.md new file mode 100644 index 0000000000000000000000000000000000000000..c95f5b2cdd16bb69c36baae1c4054f1255b658e0 --- /dev/null +++ b/station/docs/05-data-routes-fa.md @@ -0,0 +1,159 @@ +# بررسی سه مسیر داده، پیش از هر خرید (۲۲ سپتامبر ۲۰۲۶) + +**پرسش شما:** «قبل از خرید بگو اینها به کار می‌خورد یا نه.» پس این سند هیچ‌چیز نمی‌فروشد؛ فقط +سه مسیر را با نیاز واقعی ایستگاه می‌سنجد و می‌گوید امروز چه بخریم، چه نخریم، و چه چیزی را +اول باید تست کنیم. + +> **داوری کوتاه.** امروز **هیچ‌چیز نخرید**. مسیر رایگان (APIهای عمومی بازار) کار اصلی را +> انجام می‌دهد؛ **وجه تضمین** را هیچ منبع داده‌ای به شما نمی‌دهد و باید از سامانهٔ کارگزاری +> خوانده شود؛ و **پوش لحظه‌ای (وب‌سوکت)** برای این برنامه لازم نیست، چون افق تصمیم این +> راهبردها دقیقه‌ای و ساعتی است، نه میلی‌ثانیه‌ای. + +--- + +## ۱. ایستگاه دقیقاً چه می‌خواهد؟ + +پیش از داوری دربارهٔ فروشنده‌ها، اول فهرست نیاز خودمان. تصمیم‌های ایستگاه روی پنج خانوادهٔ +راهبرد بسته است: پایهٔ نقدی‌آتی، باکس اسپرد، تبعی، پوشش‌داده‌شده، و تساوی پوت‌کال. + +| میدان داده | برای چه راهبردی | تغییرش چقدر تند است؟ | از کجا می‌آید؟ | +| --- | --- | --- | --- | +| قیمت پایه سهم یا صندوق | همه | دقیقه‌ای | رایگان (API عمومی بازار) | +| قیمت آتی | پایهٔ نقدی‌آتی | دقیقه‌ای | رایگان در بعضی سرویس‌ها (نوع «آتی») | +| قیمت اعمال و پرمیوم اختیار | باکس، پوشش‌داده‌شده، تساوی | دقیقه‌ای | نیمه‌رایگان و ناقص؛ بعضی سرویس‌ها دارند | +| روز تا سررسید | همه | روزانه (تاریخ) | قابل محاسبه، از تقویم خودتان | +| نقدشوندگی و اسپرد | دروازهٔ ریسک | دقیقه‌ای | نیمه‌رایگان (ریزمعاملات) | +| **وجه تضمین هر قرارداد** | همهٔ اهرمی‌ها | **روزانه، اعلامی** | **فقط سامانهٔ کارگزاری** | +| تاریخ قیمت‌ها برای پس‌آزمایی | سنجش موتور | گذشته | سرویس پولی، یا ثبت روزانهٔ خودتان | + +**نتیجهٔ مهم این جدول:** شش میدان از هفت میدان با دادهٔ رایگان یا نیمه‌رایگان پر می‌شود. +میدان هفتم (وجه تضمین) **فروشی نیست** و ساختارش هم این‌طور است که کارگزاری هر روز اعلام می‌کند. +پس «خرید داده» مسئلهٔ اصلی این برنامه نیست؛ «ثبت روزانهٔ وجه تضمین» مسئلهٔ اصلی است و +ایستگاه همین را با فرم اعداد کارگزاری حل کرده است (شصت ثانیه در روز). + +--- + +## ۲. مسیر ۱: خرید وب‌سرویس رسمی اطلاعات بورس (پولی) + +**چه چیزی می‌دهد:** دادهٔ رسمی و سازمانی، قیمت پایان روز و ریز داده، قرارداد و فاکتور، +پشتیبانی. برای شرکتی که می‌خواهد سند رسمی داشته باشد، این مهم است. + +**چه چیزی نمی‌دهد:** وجه تضمین قراردادهای شما (آن را کارگزاری اعلام می‌کند)، و +«تصمیم»؛ هیچ سرویس داده‌ای نمی‌گوید چه بخر. + +**هزینه:** در منابع عمومی، خودِ فروشندگان دادهٔ جایگزین، قیمت وب‌سرویس رسمی را «نجومی» +توصیف می‌کنند و همین را دلیل ساخت سرویس رایگانشان می‌دانند +([brsapi](https://brsapi.ir/about-tsetmc-stock-exchange-free-bourse-api/)). عدد دقیق را باید +از خود فروشنده بگیرید؛ ما عدد حدسی نمی‌نویسیم. + +**داوری: فعلاً نه.** سه دلیل: +۱. امروز سابقهٔ ثبت‌شدهٔ شما «صفر روز» است؛ خرید داده پیش از دیدن اینکه موتور روزانه +فرصت پیدا می‌کند یا نه، پول جلوتر از شاهد است. +۲. وجه تضمین را هم پوشش نمی‌دهد؛ پس همان کار دستی سر جایش می‌ماند و «صرفه‌جویی زمانی» کمتر +از آن است که به نظر می‌رسد. +۳. قاعدهٔ کارنامهٔ ایستگاه می‌گوید تا پنج روز کاری با دادهٔ واقعی ثبت نشود، وقت خرید نیست. + +**چه زمانی بله:** اگر (الف) کارنامه «آماده» شد، (ب) دفتر نشان داد روزانه فرصت واقعی وجود دارد، +و (ج) **خریدار شرکت باشد نه شما**، چون آن‌وقت به فاکتور رسمی و قرارداد نیاز دارد و ارزان‌بودن +برای یک شرکت موضوعیت ندارد. در آن حالت، مسیر رسمی انتخاب درست است. + +--- + +## ۳. مسیر ۲: سرویس‌های عمومی بازار (رایگان و نیمه‌رایگان، بدون قرارداد) + +**نمونه‌ها:** سرویس رایگان کلیددار روی دادهٔ tsetmc (شامل نوع «آتی»، ریزمعاملات و اوراق) مانند +[brsapi](https://brsapi.ir/) · سرویس توکن‌دار با کندل دو‌دقیقه‌ای و تاریخچهٔ اختیار مانند +[sourcearena](https://sourcearena.ir/%D9%88%D8%A8-%D8%B3%D8%B1%D9%88%DB%8C%D8%B3-api-%D8%A8%D9%88%D8%B1%D8%B3-%D9%81%D8%B1%D8%A7%D8%A8%D9%88%D8%B1%D8%B3/) · +و بسته‌های پایتونی مانند `tsetmc-api` و `codal-tsetmc`. + +**چه چیزی می‌دهد:** قیمت پایه، بخش زیادی از قیمت آتی و اختیار، ریزمعاملات، و تاریخچهٔ روزانه +برای پس‌آزمایی. هزینه: صفر یا نزدیک صفر. + +**ریسک‌های واقعی که باید بدانید (و در برنامه هم برچسب می‌خورند):** +- این سرویس‌ها رسمی نیستند؛ «بی‌تعهد» هستند و ممکن است قطع شوند یا ساختار خروجی عوض شود. +- داده از پیمایش سایت مرجع می‌آید؛ پس تأخیر دارد و ممکن است در ساعت‌های شلوغ ناقص باشد. +- شرایط استفادهٔ سایت مرجع ممکن است پیمایش خودکار را محدود کند؛ مسئولیتش با شماست. +- هیچ‌کدام «وجه تضمین» نمی‌دهند. + +**داوری: بله، همین امروز.** این مسیر همان کاری را می‌کند که برای این برنامه لازم است: +قیمت هر دقیقه یا هر چند دقیقه، رایگان، بدون کلید بانکی و بدون قرارداد. + +**تست پیش از اتکا (روی رایانهٔ خودتان، نه از بیرون ایران):** در گام ۲ دکمهٔ «اتصال خودکار» +را بزنید؛ ایستگاه چند منبع رایگان را امتحان می‌کند، پاسخ را می‌خواند، عدد را عقلی می‌سنجد +(صفر نباشد، تاریخ نباشد، بیرون بازهٔ معقول نباشد) و دلیل موفقیت یا شکست هر منبع را فارسی +می‌گوید. نتیجهٔ همین آزمون، معیار انتخاب شماست، نه تبلیغ فروشنده. + +> **آنچه در محیط ساخت برنامه دیدیم:** دسترسی به سامانه‌های ایرانی از بیرون کشور بسته است +> (پاسخ `000` و خطای گواهی). یعنی ما نمی‌توانیم به‌جای شما این مسیر را تأیید کنیم؛ به همین +> دلیل کل این آزمون را به‌صورت دکمه در خود برنامه گذاشتیم تا روی رایانهٔ شما اجرا شود. + +--- + +## ۴. مسیر ۳: پوش لحظه‌ای از کارگزاری یا از سازمان بورس (وب‌سوکت) + +**واقعیت بازار:** دسترسی به API سفارش و دادهٔ لحظه‌ای، محصول عمومی کارگزاری‌ها نیست؛ +سامانهٔ معاملات آنلاین رایگان است ولی برای چشم و دست انسان ساخته شده، نه برای برنامه. +گرفتن دسترسی برنامه‌نویسی معمولاً پاسخ «چنین اجازه‌ای داده نمی‌شود» می‌گیرد +([پرسش و پاسخ کارگزاری کاریزما](https://learning.charisma.ir/beginning-investing/%D8%B3%D8%A7%D9%85%D8%A7%D9%86%D9%87-%D9%85%D8%B9%D8%A7%D9%85%D9%84%D8%A7%D8%AA%DB%8C-%DA%86%DB%8C%D8%B3%D8%AA%D8%9F-%D8%A8%D9%87%D8%AA%D8%B1%DB%8C%D9%86-%D8%A2%D9%86-%DA%A9%D8%AF%D8%A7%D9%85-%D8%A7/)). +مسیر مستقیم از سازمان بورس هم عملاً به شرکت‌های دارای مجوز (مثل بازارگردان‌ها) می‌رسد. + +**و نکتهٔ فنی:** برنامهٔ شما به پوش لحظه‌ای **نیاز ندارد**. راهبردهای نقدی‌آتی، باکس، تبعی و +پوشش‌داده‌شده در بازهٔ روز و ساعت بسته می‌شوند، نه در میلی‌ثانیه. تفاوت «خواندن هر پنج دقیقه» +با «پوش لحظه‌ای» در تصمیم این راهبردها صفر است؛ فقط هزینهٔ پیچیدگی را بالا می‌برد. + +**داوری: پیگیری کنید، ولی برنامهٔ کاری‌تان را روی آن نبندید.** اگر کارگزاری‌تان روزی دسترسی +برنامه‌نویسی داد، ایستگاه همین حالا آمادهٔ گرفتن داده است (قالب نشانی و مسیر JSON در گام ۲ +هر ساختاری را می‌پذیرد). تا آن روز، مسیر رایگان کافی است. + +> **یادآوری قانونی:** معاملات الگوریتمی و تفکیک سفارش توسط مشتریان برخط، طبق ابلاغیهٔ +> مهر ۱۳۹۹ «تا اطلاع ثانوی» ممنوع است. ایستگاه به همین دلیل **هیچ سفارشی ارسال نمی‌کند**؛ +> فقط حساب می‌کند و بستهٔ سفارش چاپی برای اجرای انسانی می‌سازد. + +--- + +## ۵. جدول تطبیق: کدام مسیر کدام نیاز را می‌پوشاند + +| نیاز ایستگاه | مسیر ۱ (رسمی پولی) | مسیر ۲ (عمومی رایگان) | مسیر ۳ (پوش لحظه‌ای) | +| --- | --- | --- | --- | +| قیمت پایه و آتی | ✅ | ✅ | ✅ | +| قیمت اعمال و پرمیوم اختیار | ✅ | ⚠️ ناقص؛ باید نماد‌به‌نماد تست شود | ✅ | +| ریزمعاملات و نقدشوندگی | ✅ | ✅ در بعضی سرویس‌ها | ✅ | +| **وجه تضمین** | ❌ | ❌ | ❌ (فقط کارگزاری) | +| تاریخچه برای پس‌آزمایی | ✅ | ⚠️ کوتاه یا ناقص | ❌ | +| هزینه | بالا | صفر | نیازمند قرارداد | +| در دسترس بودن برای شما | قابل خرید | همین حالا | بسته | +| تناسب با افق تصمیم ایستگاه | بیشتر از نیاز | کافی | بیشتر از نیاز | + +**جمع‌بندی جدول:** برای شروع، مسیر ۲ کافی است؛ برای ارائهٔ رسمی به شرکت، مسیر ۱ معنی دارد؛ +مسیر ۳ الان بسته است و نیازی هم به آن نداریم. + +--- + +## ۶. قاعدهٔ خرید: چه زمانی و چه چیزی + +دروازهٔ سه‌شرطی (همان چیزی که کارنامهٔ ایستگاه می‌سنجد): + +۱. **کارنامهٔ آزمون «آماده» شود:** ده روز ثبت‌شده، پنج روز با دادهٔ واقعی، شصت درصد بازسنجی‌شده، + سه حرکت معنادار، زنجیرهٔ سالم. +۲. **دفتر نشان بدهد دادهٔ رایگان کجا کوتاه می‌آید:** مثلاً «چند فرصت را دیر دیدیم چون قیمت + آتی در سرویس رایگان نبود». اگر چنین چیزی در دفتر ثبت نشد، خریدی هم لازم نیست. +۳. **خریدار مشخص باشد:** اگر خودتان می‌خرید، ارزان‌ترین مسیر کافی را انتخاب کنید. اگر شرکت + می‌خرد، مسیر رسمی با فاکتور را انتخاب کنید و بحث قیمت را به آن‌ها بسپارید. + +**چک‌لیست پیش از امضای هر خرید:** نمونهٔ داده را برای نمادهای واقعی خودتان بگیرید · +پوشش «آتی» و «اختیار» را ببینید · تاریخچهٔ حداقل شش‌ماهه برای پس‌آزمایی بخواهید · +شرایط استفاده و محدودیت نرخ درخواست را بخوانید · امکان پرداخت ریالی و صدور فاکتور را بپرسید · +و در پایان، همان قالب نشانی را در گام ۲ ایستگاه بگذارید و «آزمایش اتصال» را بزنید؛ +اگر عدد سالم آمد، تازه آن‌وقت خرید معنی دارد. + +--- + +## ۷. صداقت این سند + +- هیچ‌کدام از سه مسیر را ما نتوانستیم از محیط ساخت برنامه روی دادهٔ واقعی ایرانی آزمایش کنیم + (دسترسی شبکه‌ای از بیرون کشور بسته است). به‌جای ادعای بی‌شاهد، ابزار آزمون را در خود برنامه + گذاشتیم و نتیجه‌اش را به شما سپردیم. +- رتبه‌بندی قیمت‌ها از زبان فروشندگان داده می‌آید، نه از فاکتور. عدد را از فروشنده بگیرید. +- هیچ‌جای این سند وعدهٔ سود نمی‌دهد؛ بحث فقط «چه داده‌ای برای تصمیم لازم است» است. + +✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · 📱 [+989126630554](tel:+989126630554) · ✈️ [Telegram: Mojarabian](https://t.me/Mojarabian) · 📸 [Instagram: Mojarabian.Art](https://instagram.com/Mojarabian.Art) diff --git a/station/docs/06-data-feasibility-fa.md b/station/docs/06-data-feasibility-fa.md new file mode 100644 index 0000000000000000000000000000000000000000..954f112cf4d862a0a71bdee8b421852816804787 --- /dev/null +++ b/station/docs/06-data-feasibility-fa.md @@ -0,0 +1,126 @@ +# چطور مسیرهای داده را بسنجیم و چه زمانی بخریم (۲۲ سپتامبر ۲۰۲۶) + +این سند پاسخ همان جملهٔ شماست: «اول بررسی کن ببین قبل از خرید اینها به کار می‌خورد یا نه». +پس این‌جا هیچ‌چیز فروخته نمی‌شود؛ فقط یک ابزار سنجش، یک قاعدهٔ تصمیم، و یک برگهٔ استعلام قیمت هست. + +> **داوری یک‌خطی:** امروز چیزی نخرید. سنجش رایگان را روی رایانهٔ خودتان اجرا کنید؛ اگر جواب داد، +> همان کافی است. خرید فقط وقتی معنی دارد که کارنامهٔ آزمون «آماده» شود و خریدار (خودتان یا شرکت) +> روشن باشد. سند داوری سه مسیر در `05-data-routes-fa.md` است؛ این سند «چطور بسنجیم» را می‌گوید. + +--- + +## ۱. سنجش، پیش از خرید: چهار پرسش که با عدد جواب می‌گیرند + +هر مسیر داده‌ای که به شما پیشنهاد می‌شود (رایگان یا پولی)، قبل از هر تصمیمی باید چهار پرسش را +با عدد جواب بدهد. ابزار `data_sources.py` همین چهار پرسش را می‌پرسد: + +| پرسش | چرا مهم است | کجا دیده می‌شود | +| --- | --- | --- | +| نشانی جواب می‌دهد؟ | نشانی‌ها و ساختار پاسخ مدام عوض می‌شوند | ستون «HTTP» و «نتیجه» در گزارش | +| چقدر طول می‌کشد؟ | اگر هر درخواست ۵ ثانیه بگیرد، ۵۰ نماد یعنی ۴ دقیقه | ستون «میلی‌ثانیه» | +| دو فراخوانی پشت‌سرهم، عدد را عوض می‌کند؟ | همان «گپ زمانی» که خودتان اشاره کردید | ستون «تازگی (دو فراخوانی)» | +| میدان‌های موردنیاز موتور درمی‌آید؟ | «داده هست» با «دادهٔ لازم هست» یکی نیست | ستون «میدان‌های یافته» | + +نتیجهٔ «بی‌حرکت» در ستون تازگی بد نیست، ولی یک هشدار است: یعنی آن نشانی در بازهٔ چند ثانیه +تغییر نمی‌کند و برای تصمیم دقیقه‌ای باید با احتیاط استفاده شود. + +--- + +## ۲. دستورهای سنجش، همین حالا + +روی رایانهٔ خودتان (داخل ایران) این‌ها را اجرا کنید: + +```bash +cd MATERIALS/money/gui +python data_sources.py --all --symbol فولاد # همهٔ نشانی‌های رایگان سایت مرجع +python data_sources.py --all --symbol اهرم --code 46348559193224090 +python data_sources.py --ws wss://نشانی-کارگزاری/بازار # سنجش دسترسی پوش لحظه‌ای +python data_sources.py --sheet # ساخت برگهٔ نیاز داده برای فروشنده +``` + +و در رابط گرافیکی، گام ۲، کارت **«امکان‌سنجی مسیرهای داده»**: چهار کادر دارد (نماد، نشانی پوش +لحظه‌ای، تیک «دادهٔ ساختگی محلی»، دکمهٔ سنجش) و نتیجه را به شکل جدول نشان می‌دهد. تیک «دادهٔ +ساختگی» فقط برای دیدن شکل خروجی است؛ در گزارش هم صریح برچسب می‌خورد. + +خروجی‌ها: `gui/data/data-feasibility.html` (گزارش کامل) و `gui/data/data-requirement-sheet.md` +(برگهٔ استعلام از فروشنده‌ها). + +--- + +## ۳. نیاز واقعی موتور، و آن میدانی که هیچ‌کس نمی‌فروشد + +| داده | هر چند وقت | از کدام مسیر | +| --- | --- | --- | +| قیمت پایه سهم یا صندوق | هر ۱ تا ۵ دقیقه | pull (رایگان یا پولی) | +| قیمت آتی | هر ۱ تا ۵ دقیقه | pull؛ در سرویس‌های رایگان جداگانه تست شود | +| قیمت اعمال و پرمیوم اختیار | هر ۱ تا ۵ دقیقه | pull؛ پوشش کامل تضمین‌شده نیست | +| نقدشوندگی و اسپرد | هر ۱ تا ۵ دقیقه | pull (بهترین سفارش‌های خرید و فروش) | +| روز تا سررسید | روزانه | محاسبهٔ خودمان از تقویم | +| **وجه تضمین هر قرارداد** | روزانه، اعلامی | **فقط سامانهٔ کارگزاری** | +| تاریخ قیمت برای پس‌آزمایی | گذشته | سری روزانه؛ در سرویس رایگان کوتاه است | + +جملهٔ کلیدی: **وجه تضمین فروشی نیست.** کارگزاری هر روز اعلامش می‌کند و باید از سامانه برداشته شود. +این یعنی بحث «خرید داده» مسئلهٔ اصلی شما نیست؛ مسئلهٔ اصلی ثبت روزانهٔ همان یک عدد است و ایستگاه +همین را با فرم اعداد کارگزاری حل کرده است (شصت ثانیه در روز). + +--- + +## ۴. ایستگاه با دادهٔ گپ‌دار و کهنه چه می‌کند؟ + +سرویس رایگان بی‌تعهد است، پس برنامه باید در برابر گپ و کهنگی صادق باشد: + +- **برچسب تازگی:** نوار بالای صفحه می‌گوید داده «زنده» است یا «از حافظهٔ نهان» یا «کهنه». +- **حافظهٔ نهان با مهلت:** اگر سرویس جواب ندهد، از آخرین پاسخ سالم استفاده می‌شود و همان را + با تاریخ و ثانیهٔ کهنگی اعلام می‌کند؛ عدد قدیمی به‌جای دادهٔ زنده جا زده نمی‌شود. +- **شکست صریح:** اگر هیچ قیمتی نیامد، وضعیت «ناموفق» و پیام «هیچ قیمتی از سرویس نیامد» نشان داده + می‌شود و تازگی «نامعلوم» می‌مانَد (سنجهٔ آزمون، بند «شکست دادهٔ زنده»). +- **سنجهٔ نرخ واحد:** اگر یک نشانی برای چند نماد عیناً یک عدد بدهد (مثل نرخ ارز)، برنامه آن را + «جزئی» اعلام می‌کند و می‌گوید این قیمت هر نماد نیست. +- **تصمیم روی دادهٔ کهنه:** در بازسنجی، برنامه همیشه قیمت تازه می‌خوانَد و حافظهٔ نهان را دور می‌زند؛ + اگر قیمت تازه نیاید، ردیف با وضعیت «دادهٔ تازه نبود» گزارش می‌شود، نه با عدد حدسی. +- **سنجش دو فراخوانی:** همین ابزار به شما می‌گوید کدام نشانی در بازهٔ چند ثانیه تازه می‌شود و + کدام بی‌حرکت است، تا بدانید برای تصمیم دقیقه‌ای به کدام‌شان تکیه کنید. + +--- + +## ۵. برگهٔ نیاز داده: پیش از هر تماس با فروشنده، این را بفرستید + +`python data_sources.py --sheet` یک برگه می‌سازد (`gui/data/data-requirement-sheet.md`) که +همهٔ فروشنده‌ها را با یک معیار مقایسه می‌کند: جدول دادهٔ موردنیاز با نرخ به‌روزرسانی، ستون +«دارید؟»، و پنج پرسش فنی (قالب دسترسی، احراز هویت و محدودیت نرخ درخواست، پایداری و پرکردن +دوبارهٔ داده، پرداخت ریالی و فاکتور، و اجازهٔ استفاده در یک سامانهٔ تصمیم‌یار). + +با این برگه سه استعلام بگیرید و جواب‌ها را کنار هم بگذارید؛ بعد همان قالب نشانی فروشندهٔ برنده +را در گام ۲ ایستگاه بگذارید و «آزمایش اتصال» را بزنید. اگر عدد سالم آمد، تازه آن‌وقت خرید معنی دارد. + +--- + +## ۶. قاعدهٔ خرید (دروازهٔ سه‌شرطی) + +۱. **کارنامهٔ آزمون «آماده» شود:** ده روز ثبت‌شده، پنج روز با دادهٔ واقعی، شصت درصد بازسنجی‌شده، + سه حرکت معنادار (دست‌کم یکی بازتر و یکی بسته)، و زنجیرهٔ هش سالم. +۲. **دفتر نشان بدهد دادهٔ رایگان کجا کوتاه می‌آید:** مثلاً «چند فرصت را دیر دیدیم چون قیمت آتی + در سرویس رایگان نبود». اگر چنین چیزی در دفتر ثبت نشد، خریدی لازم نیست. +۳. **خریدار روشن باشد:** اگر خودتان می‌خرید، ارزان‌ترین مسیر کافی را بردارید. اگر شرکت می‌خرد، + مسیر رسمی با فاکتور و قرارداد را انتخاب کنید و چانه‌زنی قیمت را به آن‌ها بسپارید. + +**دربارهٔ پوش لحظه‌ای (وب‌سوکت و جریان RLC):** اول با `--ws` بسنجید که سرویس اصلاً دسترسی‌پذیر +است یا نه. بعد یادتان باشد که این برنامه به آن نیازی ندارد: راهبردهای نقدی‌آتی، باکس، تبعی و +پوشش‌داده‌شده در بازهٔ ساعت بسته می‌شوند، نه میلی‌ثانیه. اگر روزی کارگزاری دسترسی داد، ایستگاه +همین حالا آمادهٔ گرفتنش است؛ تا آن روز، مسیر pull کافی است. + +**یادآوری قانونی:** معاملات الگوریتمی و تفکیک سفارش توسط مشتریان برخط، طبق ابلاغیهٔ مهر ۱۳۹۹ +«تا اطلاع ثانوی» ممنوع است. ایستگاه هیچ سفارشی ارسال نمی‌کند و فقط حساب می‌کند. + +--- + +## ۷. صداقت این سند + +- سامانه‌های ایرانی از محیط ساخت برنامه در دسترس نیستند (پاسخ خالی و خطای گواهی). پس هر عددی + دربارهٔ سرویس‌های ایرانی باید **روی رایانهٔ خودتان** گرفته شود؛ همین دلیلِ بودنِ دکمهٔ سنجش در + گام ۲ است. +- الگوهای نشانی‌ها در `data_sources.py` نوشته شده‌اند و ممکن است سرویس‌ها تغییرشان بدهند. ابزار + دقیقاً برای همین ساخته شده: اگر ساختار عوض شود، «سرخ» می‌شود و می‌گوید کدام میدان پیدا نشد. +- هیچ‌جای این سند وعدهٔ سود نمی‌دهد و هیچ ادعایی دربارهٔ کیفیت سرویس‌ها بدون سنجش نوشته نشده است. + +✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · 📱 [+989126630554](tel:+989126630554) · ✈️ [Telegram: Mojarabian](https://t.me/Mojarabian) · 📸 [Instagram: Mojarabian.Art](https://instagram.com/Mojarabian.Art) diff --git a/station/docs/07-zero-cost-test-fa.md b/station/docs/07-zero-cost-test-fa.md new file mode 100644 index 0000000000000000000000000000000000000000..fe465c39cd016a53a854797e5e960e82534d6cfd --- /dev/null +++ b/station/docs/07-zero-cost-test-fa.md @@ -0,0 +1,113 @@ +# چرا هیچ‌چیز نمی‌خریم — و با صفر تومان چه تست عملیاتی می‌شود گرفت (۲۲ سپتامبر ۲۰۲۶) + +این سند پاسخ همان دو پرسش شماست: «آیا باید Jev را بخرم؟» و «راه دیگری نیست که کارفرما یک تست +عملیاتی واقعی بگیرد؟». پاسخ کوتاه: **هیچ‌چیز لازم نیست بخرید؛ و بله، راه بیهزینه و قابل‌اتکا هست.** + +> **داوری یک‌خطی:** Jev برای این برنامه لازم نیست. سه مسیر تست بیهزینه هست که امروز روی لپ‌تاپ +> شما اجرا می‌شود؛ هزینهٔ واقعی فقط وقتی معنی پیدا می‌کند که خریدار مشخصی (شرکت) با فاکتور و +> قرارداد پشت میز باشد. + +--- + +## ۱. پرسش «Jev را بخرم؟» — جواب با دلیل + +کل برنامه دو لایه دارد و مهم است این دو را از هم جدا کنیم: + +| لایه | کارش | به سرویس هوش مصنوعی نیاز دارد؟ | +| --- | --- | --- | +| موتور تصمیم (ریاضی) | نرخ سد، بازده سالانه، آربیتراژ، اندازهٔ موقعیت، دروازه‌های ریسک | **نه.** صرفاً حساب است و روی هر لپ‌تاپی بی‌اینترنت هم کار می‌کند. | +| لایهٔ خبر و زبان | خلاصه‌کردن اطلاعیهٔ کدال، خواندن متن فارسی، نوشتن گزارش | نه برای کارکرد؛ ولی بهتر است. | + +لایهٔ دوم الان با **قاعده‌های کلیدواژه‌ای** کار می‌کند: کدال را می‌خواند، کلمه‌های مهم را +می‌شمارد، امتیاز می‌دهد و کنار سیگنال می‌گذارد. کار می‌کند و هزینه ندارد. اگر روزی خواستید +این لایه باهوش‌تر شود، دو راه بیهزینه هست و هیچ‌کدام «خرید سرویس» نیست: + +- **مدل محلی روی همان لپ‌تاپ:** یک مدل کوچک فارسی‌خوان با ابزار آزاد نصب می‌کنید؛ نه کلید می‌خواهد، + نه ماهانه، نه داده‌ای به بیرون می‌رود. (کندتر است، ولی برای خلاصه‌کردن چند اطلاعیه در روز بس است.) +- **همان قاعده‌های فعلی، تا وقتی واقعاً کم بیاید:** معیار ساده است: اگر در دفتر ثبت شد که «فلان + اطلاعیه را دیر فهمیدیم»، آن‌وقت دربارهٔ ارتقا حرف می‌زنیم. تا آن روز، لایهٔ زبانی گلوگاه شما نیست. + +پس: **Jev را نخرید.** خرید سرویس هوش مصنوعی، مسئلهٔ امروز شما نیست؛ مسئلهٔ امروز، اجرای +مراسم روزانه و پرکردن دفتر است. + +--- + +## ۲. سه مسیر تست عملیاتی، همه با هزینهٔ صفر + +| مسیر | چه چیزی را ثابت می‌کند | هزینه | اینترنت لازم دارد؟ | +| --- | --- | --- | --- | +| **الف) خوراک آزمایشی محلی** | کل مسیر فنی زنده کار می‌کند: قیمت می‌آید، تازگی داده سبز می‌شود، دفتر و هشدار و بسته کار می‌کنند | صفر | نه | +| **ب) دادهٔ واقعی رایگان** (سایت مرجع و tgju از داخل ایران) | با دادهٔ واقعی بازار هم همان مسیر کار می‌کند | صفر | بله | +| **ج) اعداد کارگزاری با دست** | استقلال کامل از هر سرویس؛ ۶۰ ثانیه در روز | صفر | نه | + +**مسیر الف (خوراک آزمایشی محلی).** در گام ۲ پروفایل «خوراک آزمایشی محلی» را انتخاب و آزمایش +کنید. قیمت‌ها هر ثانیه تکان می‌خورند و بعد از چند خواندن، یک رخداد برنامه‌ریزی‌شده بازار را +جابه‌جا می‌کند تا ببینید سیگنال چطور ظاهر می‌شود. هر جا این داده نمایش داده شود، برچسب +«ساختگی» می‌خورد — در نوار بالای صفحه، در گزارش، و در بستهٔ تحویل. + +**مسیر ب (دادهٔ واقعی رایگان).** سنجشش با ابزار امکان‌سنجی در گام ۲ انجام می‌شود: نشانی‌ها را +می‌زند، می‌گوید کدام جواب داد، چقدر طول کشید، و با دو فراخوانی پشت‌سرهم می‌سنجد که عدد تازه +می‌شود یا بی‌حرکت است. توجه: سامانه‌های ایرانی از بیرون کشور پاسخ نمی‌دهند؛ این تست را روی +لپ‌تاپ خودتان (داخل ایران) بزنید. + +**مسیر ج (اعداد کارگزاری با دست).** همان کاری که از روز اول گفتیم: هر روز صبح، شصت ثانیه، +عددهای کارگزاری را در فرم گام ۲ وارد می‌کنید. این مسیر هیچ سرویسی نمی‌خواهد و همان چیزی را +می‌دهد که هیچ فروشندهٔ داده نمی‌دهد: **وجه تضمین**. توجه داشته باشید که برچسب این روزها +«اعداد دستی کارگزاری» است و در کارنامه هم از روزهای ساختگی جدا شمرده می‌شود. + +--- + +## ۳. آن تستی که کارفرما را قانع می‌کند: آزمون کور + +مهم‌ترین نکتهٔ این سند همین است. سرمایه‌گذارِ باسواد با «ما سود ساختیم» قانع نمی‌شود؛ با این +قانع می‌شود که **خودش** عددی را حساب کند و ببیند برنامه همان را می‌گوید. + +در گام ۱۰ (آزمون کور سرمایه‌گذار) شش پرسش عددی و بله/خیر مطرح می‌شود و پاسخ‌ها تا لحظهٔ داوری +پنهان می‌مانَد. سرمایه‌گذار اول حدس می‌زند، بعد پاسخ برنامه با فرمول و «روش دوم» — که با +ماشین‌حساب جیبی قابل بازبینی است — رو می‌شود. در همان گام، جدول «آستانهٔ ریزش» نشان می‌دهد +با عوض‌شدن نرخ سد، کدام راهبرد از دروازه می‌افتد؛ و بخش «حساب‌رسی واقعیت» یک معاملهٔ گذشته را +با کارمزدهای واقعی ایران می‌شمارد. + +هر ردیف در دفتر زنجیره‌هش‌دار ثبت می‌شود و در پایان، برگهٔ چاپی با جای امضا ساخته می‌شود. +اگر کسی بعداً عددی را عوض کند، کلید زنجیره می‌شکند و برگه باطل می‌شود. همین «قابل بازبینی بودن» +است که اعتماد می‌سازد، نه وعده. + +--- + +## ۴. پروتکل تست عملیاتی بیهزینهٔ ۱۰ روزه (برای کارفرما) + +۱. **روز صفر:** پروندهٔ سرمایه‌گذار و برگهٔ آزمون کور را بسازید و همان جلسه را با سرمایه‌گذار + برگزار کنید (گام ۱۰ و ۹). او خودش حدس می‌زند و خودش با ماشین‌حساب چک می‌کند. +۲. **روزهای ۱ تا ۱۰ (کاری):** هر روز فقط دکمهٔ «اجرای مراسم امروز» زده می‌شود؛ خوراک + آزمایشی یا اعداد کارگزاری، هر کدام که در دسترس بود. +۳. **در پایان هر روز:** دفتر را ثبت کنید و کارنامه را نگاه کنید. کارنامه سه چیز را جدا + می‌شمارد: روزهای ثبت‌شده، روزهای با دادهٔ واقعی، و بازسنجی‌شده‌ها. +۴. **روز ۱۰:** گزارش دفتر و زنجیرهٔ هش را نشان دهید و همان پرونده را برای شرکت بفرستید. + اگر کارنامه «آماده» شد، تازه دربارهٔ دادهٔ خریدنی و جلسهٔ شرکت حرف می‌زنیم. + +شرط پایانِ صادقانه: اگر کارنامه «آماده» نشد، یعنی ریاضیِ بازار در آن ده روز سود کافی نداشته؛ +این هم نتیجهٔ معتبری است و همان را می‌نویسیم، نه یک عدد آراسته. + +--- + +## ۵. آنچه واقعاً پول لازم دارد (و امروز لازم نیست) + +- **دادهٔ رسمی با قرارداد و فاکتور:** برای وقتی که شرکت تصمیم بگیرد بخرد. تا آن روز، مسیرهای + بیهزینه کافی است. +- **نگه‌داری و زمان انسان:** هر روز شصت ثانیه ثبت. این «هزینه» به پول نیست، به عادت است. +- **سخت‌افزار:** همان لپ‌تاپ خودتان. برنامه به سرور بیرونی وصل نمی‌شود مگر خودتان اجازه بدهید. + +نتیجه: **برای شروع هیچ‌چیز نخرید.** اول ۱۰ روز داده جمع کنید؛ اگر ریاضی درست کار کرد، خرید +داده تازه معنی پیدا می‌کند. + +--- + +## ۶. صداقت این سند + +- هیچ عددی در این سند وعدهٔ سود نیست؛ فقط مسیر و شرط است. +- دسترسی به سامانه‌های ایرانی از بیرون کشور ممکن نیست؛ برای همین همهٔ آزمون‌های واقعی باید روی + رایانهٔ خودتان اجرا شود. +- برنامه هیچ سفارشی نمی‌فرستد (ابلاغیهٔ مهر ۱۳۹۹ معاملات الگوریتمی را ممنوع کرده است)؛ همهٔ کار + تصمیم‌یار است و اجرا با انسان. + +✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · 📱 [989126630554](tel:+989126630554) · ✈️ [Telegram: Mojarabian](https://t.me/Mojarabian) · 📸 [Instagram: Mojarabian.Art](https://instagram.com/Mojarabian.Art) diff --git a/station/docs/08-differentiation-and-trust-fa.md b/station/docs/08-differentiation-and-trust-fa.md new file mode 100644 index 0000000000000000000000000000000000000000..073570c34534d165c3128394ac779b3f4ad4c2e7 --- /dev/null +++ b/station/docs/08-differentiation-and-trust-fa.md @@ -0,0 +1,187 @@ +# تمایز و اعتماد: چرا شرکت برای این برنامه پول می‌دهد (۲۲ سپتامبر ۲۰۲۶) + +پرسش شما سه بخش داشت: چه چیزی در این برنامه هست که در ابزارهای فارسی نبوده، شرکت چطور می‌تواند +مطمئن شود، و نقطهٔ قوتی که باید بولد شود کدام است. این سند پاسخ صادقانهٔ هر سه است، با شاهد داخل +برنامه و دموی یک‌کلیکی برای هر ادعا. + +> **جمله‌ای که باید بولد شود:** +> ابزارهای دیگر می‌گویند «چه چیزی ممکن است سود بدهد»؛ این برنامه می‌گوید «چه چیزی با کارمزد +> واقعی، اسپرد، نقدشوندگی و وجه تضمین شما می‌مانَد» و اگر نمی‌مانَد، دلیلش را با عدد می‌نویسد. + +--- + +## ۱. اول انصاف: بازار فارسی چه دارد و چه ندارد + +ابزارهای خوبی در ایران هست و ما جایگزین‌شان نیستیم: دیده‌بان‌های اختیار معامله با فرمول‌نویسی و +فیلتر (مثل آپشن‌باز و بامبو)، ماشین‌حساب بلک‌شولز، IV و دلتا، نمودار استراتژی، نقشهٔ بازار، و +پنل‌های معاملاتی کارگزاری. همهٔ این‌ها **داده و ابزار تحلیل** می‌دهند. جای خالی جای دیگری است: + +| پرسش | دیده‌بان‌های تحلیل بازار | پنل کارگزاری | این برنامه | +| --- | --- | --- | --- | +| قیمت و IV و دلتا | ✅ | ✅ | از همان‌ها می‌گیرد (یا دستی وارد می‌شود) | +| فیلتر و اسکرینر | ✅ | ➖ | ➖ (کار آن‌ها نیست) | +| سود خالص پس از کارمزد و اسپرد و مالیات ایران | ❌ | ❌ | ✅ موتور با نرخ‌های واقعی | +| «می‌ماند یا می‌افتد» با دلیل دروازه‌ها | ❌ | ❌ | ✅ با رد صریح | +| نقطهٔ برگشت (تا کجا معامله بماند) | ❌ | ❌ | ✅ عدد دقیق | +| فاصله تا مارجین‌کال و پول در معرض خطر | ❌ | ➖ | ✅ با حد نگهداری ۷۰٪ | +| شاهد حسابرسی‌پذیر برای شرکت | ❌ | ➖ | ✅ اثر انگشت + زنجیرهٔ هش + برگهٔ امضا | +| جداسازی روز ساختگی از روز واقعی | (کار آن‌ها نیست) | (کار آن‌ها نیست) | ✅ در کارنامه و دفتر | + +یعنی ما نه رقیب دیده‌بان‌ها هستیم و نه پنل معاملاتی؛ **لایهٔ تصمیم و شاهد** روی همان داده‌ای +هستیم که آن‌ها می‌دهند. این دقیقاً چیزی است که یک شرکت با پول واقعی لازم دارد. + +--- + +## ۲. هشت نقطهٔ قوت، هر کدام با شاهد و دموی یک‌کلیکی + +### ۱) داوری سیگنال ابزار دیگران (بولدترین نقطهٔ تمایز) + +**ادعا:** سیگنال نرم‌افزار فعلی شرکت را می‌گیریم و با کارمزد، اسپرد، نقدشوندگی و نرخ سد خودشان +داوری می‌کنیم. +**شاهد:** `gui/signal_judge.py` و کارت «داوری سیگنال ابزارهای دیگر» در گام ۶. +**دموی یک‌کلیکی:** نوع راهبرد را از فهرست انتخاب کنید، «نمونهٔ آماده» را بزنید، «داوری کن». +**ارزش:** یک سیگنال کاغذی که با کارمزد خورده می‌شود، در همان ثانیه رد می‌شود و دلیلش نوشته می‌شود. + +### ۲) نقطهٔ برگشت (نقطهٔ بی‌تفاوتی) + +**ادعا:** برای هر سیگنال می‌گوییم تا کدام قیمت یا پرمیوم یا قیمت اعمال، معامله می‌مانَد؛ از آن +بدتر، می‌افتد. +**شاهد:** تابع `break_even` با دو نیم‌کردن روی موتور، و آزمونی که دو طرف نقطه را می‌سنجد. +**ارزش:** این عدد زبان مذاکره است: برای قیمت آتی، پرمیوم، یا قیمت اعمالی که کارگزاری اعلام می‌کند. + +### ۳) فاصله تا مارجین‌کال، با عدد کارگزاری خودشان + +**ادعا:** برای هر موقعیت می‌گوییم چند درصد حرکت مخالف، حساب را به حد نگهداری می‌رساند؛ چه مقدار +پول در معرض خطر است؛ و سطح قیمت اخطاریه کجاست. +**شاهد:** تابع `margin_call` با حد نگهداری پیش‌فرض ۷۰٪ (رویهٔ بورس ایران) و وجه تضمین اولیهٔ +اختیار فروش ≈۲۰٪ ارزش قرارداد؛ هر دو قابل جایگزینی با عدد کارگزاری. +**ارزش:** موقعیت‌های «نزدیک لبه» پیش از اخطاریه پیدا می‌شوند، نه بعد از آن. یادآوری: مهلت +رفع اخطاریه ۲۴ ساعت است و تسویه روزانه انجام می‌شود. + +### ۴) دروازه‌های ریسک که «نه» می‌گویند، با دلیل + +**ادعا:** نقدشوندگی کم، اسپرد بزرگ، بازده غیرواقعی، سقف موقعیت، و جهت غیرقابل‌اجرا (فروش +استقراضی) همه رد می‌شوند و دلیل هر رد نوشته می‌شود. +**شاهد:** `gate_checks` در میز + دروازه‌های `signal_judge` + آزمون «فرصت توخالی معرفی نمی‌شود». +**ارزش:** ابزاری که همیشه «بله» می‌گوید، ابزار نیست؛ تبلیغ است. شرکت با «نه»های مستند پول +ذخیره می‌کند. + +### ۵) حسابرسی‌پذیری عدد (برای مدیر ریسک و حسابرس) + +**ادعا:** هر عدد تصمیم، دو بار حساب می‌شود: یک بار با موتور، یک بار با حساب دستی مستقل. خروجی +هر ابزار اثر انگشت دارد؛ دفتر زنجیرهٔ هش دارد. +**شاهد:** آزمون ۱۰ دقیقه‌ای (۱۵ مورد، دو روش)، اثر انگشت موتور در کارنامه، زنجیرهٔ هش دفتر، +بستهٔ شاهد با `sha256[:16]` هر پرونده. +**ارزش:** اگر ردیفی دست‌کاری شود، همان لحظه لو می‌رود. این تفاوت «نرم‌افزار» و «شاهد» است. + +### ۶) صداقت ساختاری (که اعتماد را نگه می‌دارد) + +**ادعا:** پس‌آزمایی بدون آینده‌نگری است؛ روز ساختگی از روز واقعی جدا شمرده می‌شود؛ وقتی سرویس +داده نمی‌دهد، هیچ عدد ساختگی جای قیمت زنده نمی‌نشیند؛ کارنامه تا آماده نشدن، «ناتمام» می‌مانَد. +**شاهد:** آزمون‌های ضد آینده‌نگری، برچسب «خوراک آزمایشی محلی (ساختگی)» در نوار و گزارش، و +«شکست دادهٔ زنده» در کارنامه. +**ارزش:** مدیری که یک بار ببیند برنامه خودش را رسوا می‌کند، بقیهٔ عددهایش را باور می‌کند. + +### ۷) آزمون کور برای سرمایه‌گذار: خودش حساب می‌کند + +**ادعا:** شش پرسش با پاسخ پنهان؛ سرمایه‌گذار اول حدس می‌زند، بعد پاسخ با فرمول و روش دوم رو +می‌شود و با ماشین‌حساب جیبی بازبینی می‌شود؛ برگهٔ امضادار با زنجیرهٔ هش ساخته می‌شود. +**شاهد:** `gui/investor_test.py` و گام ۱۰ رابط گرافیکی. +**ارزش:** اعتماد با «خودش دید» ساخته می‌شود، نه با اسلاید. + +### ۸) استقلال استقرار و انطباق قانونی + +**ادعا:** بدون ابر و بدون اشتراک اجباری روی رایانهٔ خودشان نصب می‌شود؛ هیچ سفارشی ارسال +نمی‌کند (ابلاغیهٔ مهر ۱۳۹۹ معاملات الگوریتمی را ممنوع کرده)؛ وجه تضمین را از کارگزاری می‌گیرد، +نه از فروشندهٔ داده. +**شاهد:** رابط مرورگری و دسکتاپ محلی، `station.py` بدون هیچ ارسال سفارش، سند `05-data-routes-fa.md`. +**ارزش:** ریسک انطباق صفر، و دادهٔ شرکت از رایانهٔ خودشان بیرون نمی‌رود. + +--- + +## ۳. معماری اعتماد: چطور شرکت می‌تواند مطمئن شود + +هفت لایه، از ورودی تا شاهد. هر لایه یک آزمون دارد: + +۱. **ورودی با برچسب تازگی:** دادهٔ زنده، حافظهٔ نهان، یا اعداد دستی کارگزاری؛ هر سه از هم جدا و + برچسب‌دار، و روز ساختگی در کارنامه از روز واقعی جدا شمرده می‌شود. +۲. **دروازه‌های ریسک:** پیش از هر تصمیم، فرصت‌های توخالی رد می‌شوند و دلیل رد ثبت می‌شود. +۳. **دو روش حساب:** عدد تصمیم دو بار به دو راه مستقل درمی‌آید؛ اختلاف بیش از حد، خودش را لو می‌دهد. +۴. **دفتر زنجیره‌هش‌دار:** هر ثبت با گرهٔ هش به ردیف قبل بسته می‌شود؛ عوض‌کردن گذشته، زنجیره را می‌شکند. +۵. **بستهٔ شاهد:** یک پوشه با گزارش تصمیم‌ها، سند روش کار، کارنامهٔ آزمون، برگهٔ آزمون، پروندهٔ + سرمایه‌گذار و اثر انگشت `sha256` هر فایل. +۶. **قابل بازتولید بودن:** همان ورودی، همان جواب؛ در مسیر تصمیم هیچ مدل زبانی و هیچ تصادفی نیست. +۷. **آزمون‌های خودکار:** ۲۵۸ آزمون واحد، ۵ آزمون خط فرمان ابزار داوری، آزمون ساخت رابط گرافیکی، ۷۶ بررسی + تعاملی مرورگری، و اجرای واقعی روی موتور. + +--- + +## ۴. «چطور مطمئن شود بخرد و بفروشد؟» — پروتکل پذیرش پنج‌پله‌ای + +۱. **آزمون ۱۰ دقیقه‌ای در جلسه:** بگذارید خودشان دو مورد را با ماشین‌حساب چک کنند. اگر یک مورد + نخواند، بحث تمام است؛ چون هیچ عددی از قبل «درست» فرض نشده. +۲. **داوری سیگنال‌های امروز خودشان:** سیگنالی که ابزار فعلی یا تحلیلگرشان داده را وارد کنند؛ + خروجی «می‌ماند/می‌افتد» با دلیل، نقطهٔ برگشت، و فاصله تا مارجین‌کال. +۳. **شبیه‌سازی تاریخ:** روی دادهٔ گذشته، با آزمون ضد آینده‌نگری؛ خطای پیش‌بینی منفی هم گزارش می‌شود. +۴. **آزمون کاغذی دو هفته‌ای با دادهٔ واقعی:** بدون سفارش، با اعداد کارگزاری، و دفتر زنجیره‌هش‌دار. +۵. **تصمیم با شاهد:** بستهٔ گام ۸ جلوی مدیر ریسک. اگر کارنامه «آماده» شد، اجرا با انسان؛ اگر نه، + همان «ناتمام» نوشته می‌شود. + +**نکتهٔ قانونی که باید صریح گفته شود:** این برنامه سفارش نمی‌فرستد. معاملات الگوریتمی و تفکیک +سفارش توسط مشتریان برخط طبق ابلاغیهٔ مهر ۱۳۹۹ ممنوع است. پس ما «دستیار تصمیم با شاهد» می‌فروشیم، +نه «ربات معامله‌گر». همین صراحت، ریسک حقوقی شرکت را صفر و اعتماد را بیشتر می‌کند. + +--- + +## ۵. اقتصاد: «هر مبلغی» چه اندازه است؟ + +ارزش را با سه عدد می‌شود نشان داد، نه با شعار: + +- **کارمزد و اسپرد خورنده:** در ایران کارمزد فروش سهم حدود ۰٫۹۶٪ و خرید حدود ۰٫۴۶٪ است (در + اختیار معامله حدود ۰٫۱۰۳٪ هر طرف، به‌علاوهٔ هزینهٔ اعمال). یک معاملهٔ نوسانی که ابزار سادهٔ + دیگر «سود ۳٪» نشانش می‌دهد، پس از کارمزد و اسپرد می‌تواند صفر یا منفی شود. حذف سالانه ده + معاملهٔ کارمزد خورده در پرتفویی متوسط، چند برابر هزینهٔ سالانهٔ این ابزار است. +- **مارجین‌کال:** یک اخطاریهٔ نگرفته، از هر سود پیش‌بینی‌شده‌ای گران‌تر است. فاصلهٔ مارجین‌کال + پیش از ورود، اجازهٔ «حد ضرر منطقی» می‌دهد. +- **شاهد حسابرسی:** برای شرکت، «می‌دانیم چرا این معامله را کردیم و چرا رد شد» به‌تنهایی ارزش + سازمانی دارد؛ در جلسهٔ هیئت‌مدیره و برای حسابرس قابل ارائه است. + +**مدل قیمت پیشنهادی (سه پله):** ۱) نصب و آموزش یک‌باره؛ ۲) اشتراک پشتیبانی و به‌روزرسانی +ماهانه؛ ۳) سفارشی‌سازی و گزارش ماهانه به هیئت‌مدیره. قیمت هر پله را با یک معیار ساده ببندید: +**حق اشتراک سالانه باید کسری از «کارمزد ذخیره‌شده + زیان پرهیزشده» باشد.** اگر با اعداد واقعی +شرکت این نسبت زیر یک‌سوم بود، قیمت شما فروش راحت دارد؛ اگر نه، اول ارزش را ثابت کنید. + +--- + +## ۶. سه پرسشی که در جلسه می‌پرسند، و پاسخ آماده + +**«دادهٔ شما از کجاست و چقدر به‌روز است؟»** +از همان مسیرهای رسمی و رایگان یا سرویس خودتان؛ تازگی داده و منبعش روی نوار بالای صفحه و در +گزارش نوشته می‌شود، و اگر سرویس جواب ندهد، وضعیت «کهنه/ناموفق» اعلام می‌شود، نه عدد حدسی. + +**«اگر اشتباه کند چه؟»** +هر عدد دو بار حساب می‌شود، هر تصمیم اثر انگشت دارد، و دفتر زنجیره‌هش‌دار است. کارنامه تا +آماده‌نشدن «ناتمام» می‌مانَد و خطای منفی گزارش می‌شود. همین طراحی، اشتباه را سریع پیدا می‌کند. + +**«قبلاً هم نرم‌افزار داشتیم؛ چه چیزی تازه است؟»** +آزمون زنده در همان جلسه: سیگنال نرم‌افزار فعلی‌شان را وارد کنید. در چند ثانیه می‌بینید آن +سیگنال با کارمزد و ریسک واقعی می‌مانَد یا می‌افتد، تا چه قیمتی می‌مانَد، و چقدر تا اخطاریهٔ +مارجین فاصله دارد. این چیزی است که در جلسه باید **دیده** شود، نه گفته. + +--- + +## ۷. آنچه ادعا نمی‌کنیم + +- سود تضمینی نیست؛ هیچ عددی در این اسناد وعدهٔ سود نمی‌دهد. +- ما جایگزین دیده‌بان‌ها و تحلیل‌های بازار نیستیم؛ لایهٔ تصمیم و شاهد روی آن‌ها هستیم. +- بسته به کیفیت دادهٔ ورودی، دقت عددها بالا و پایین می‌شود؛ برای همین برچسب تازگی و «شکست + دادهٔ زنده» عمداً سخت‌گیرانه است. +- کارگزاری‌ها هر روز وجه تضمین را به‌روزرسانی می‌کنند؛ فاصلهٔ مارجین‌کال باید روزانه با عدد + تازه بازخوانی شود، نه یک بار برای همیشه. + +--- + +**خلاصهٔ یک‌خطی برای مدیرعامل:** ابزارهای دیگر «فرصت» نشان می‌دهند؛ این برنامه «فرصت‌های باقی‌مانده +پس از کارمزد و ریسک» را نشان می‌دهد، و برای هر عدد شاهد دارد. + +✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · 📱 [989126630554](tel:+989126630554) · ✈️ [Telegram: Mojarabian](https://t.me/Mojarabian) · 📸 [Instagram: Mojarabian.Art](https://instagram.com/Mojarabian.Art) diff --git a/station/docs/09-sell-or-grant-access-fa.md b/station/docs/09-sell-or-grant-access-fa.md new file mode 100644 index 0000000000000000000000000000000000000000..aefb5aabcaed356c7924071b0821e6c9dbfb755a --- /dev/null +++ b/station/docs/09-sell-or-grant-access-fa.md @@ -0,0 +1,120 @@ +# بفروشم یا دسترسی بدهم؟ راهنمای واقع‌بینانه برای کسی که تنهاست (۲۲ سپتامبر ۲۰۲۶) + +این سند پاسخ همان جملهٔ شماست: «من این برنامه را نمی‌فروشم؛ در اختیارت می‌گذارم، تو استفاده کن و +من همیشه بهترش می‌کنم.» اول صریح می‌گویم: **این جمله، بهترین ایدهٔ این چند روز است.** ولی با یک +شرط: باید به شکل **قرارداد** گفته شود، نه به شکل تعارف. این سند همان تفاوت را قدم‌به‌قدم می‌گوید. + +> **داوری یک‌خطی:** نسخه نفروشید. **اجازهٔ استفادهٔ نام‌دار بدهید، پشتیبانی را بخشی از همان +> قرارداد کنید، و مالکیت و حق بهبود را نزد خودتان نگه دارید.** این مدل، هم پشتیبانی را پوشش +> می‌دهد، هم درآمد ماهانه می‌سازد، هم لازم نیست مهندس پشتیبانی باشید. + +--- + +## ۱. سه راه پیش پای شما، با سود و زیان واقعی‌شان + +| راه | چه می‌گیرید | چه از دست می‌دهید | مناسب شما؟ | +| --- | --- | --- | --- | +| **الف) فروش نسخه (یک‌باره)** | پول یک‌باره | پشتیبانی و عیب‌یابی برای همیشه، بی‌درآمد بعدی؛ و اگر کد را دستشان بدهید، دیگر لازم نیست شما را نگه دارند | نه | +| **ب) فروش کد و مالکیت** | پول بیشتر در لحظه | کل ارزش آینده؛ از فردا شما بیرون بازی هستید | نه | +| **ج) اجازه‌نامهٔ دسترسی + پشتیبانی (پیشنهاد)** | درآمد تکرارشونده، مالکیت نزد شما، هر بهبودی که من می‌دهم ارزش قرارداد شما را بیشتر می‌کند | باید هر ماه چند ساعت وقت بگذارید | **بله** | + +راه «ج» همان جملهٔ خودتان است، فقط با یک قید: **دسترسی زمان‌دار و نام‌دار**، نه «هر وقت خواستی +بردار». برای همین در برنامه دو ابزار تازه ساخته شد: + +- `gui/license.py` — اجازه‌نامهٔ نام‌دار می‌سازد: نام شرکت، مدت، مسئول، امضای `sha256`. + (`python license.py --grant "نام شرکت" --months 12 --save`) +- **نمایش وضعیت مجوز در گام ۱ رابط** و **آمدن همان امضا در بستهٔ شاهد (گام ۸)**؛ یعنی شرکت + می‌بیند این نسخه به نام خودش است و تا چه تاریخی حق استفاده دارد. + +این کار «DRM» نیست و نمی‌خواهد باشد؛ یک **سند روشن** است: من نسخه نفروختم، اجازه دادم. + +--- + +## ۲. جملاتی که می‌توانید همین فردا بگویید + +۱. «من این برنامه را نمی‌فروشم. استفادهٔ نام‌دار به نام شرکت شما را می‌دهم، به‌همراه پشتیبانی و + به‌روزرسانی. اگر یک روز نخواستید ادامه بدهید، فقط دسترسی تمام می‌شود؛ چیزی خراب نمی‌شود.» +۲. «قیمت سه پله دارد: راه‌اندازی و آموزش (یک‌باره)، استفاده و پشتیبانی (ماهانه یا سالانه)، و + گزارش ماهانه و سفارشی‌سازی (در صورت نیاز).» +۳. «هر بهبودی که من می‌دهم، بدون هزینهٔ اضافه به نسخهٔ شما هم می‌آید؛ چون نسخهٔ شما همان نسخهٔ + من است، فقط به نام شما.» +۴. «داده‌های معاملاتی شما از رایانهٔ خودتان بیرون نمی‌رود. هیچ سفارشی هم از این برنامه ارسال + نمی‌شود؛ اجرا در سامانهٔ کارگزاری با آدم‌های خودتان است.» + +نکتهٔ مهم: پلهٔ اول را **کوچک** ببندید. «یک هفته راه‌اندازی و آموزش» بفروشید، نه «قرارداد سالانه». +اعتماد از پلهٔ اول سبز ساخته می‌شود. + +--- + +## ۳. «من سواد پشتیبانی ندارم» — چهار کار که این بار را برمی‌دارد + +۱. **خودِ برنامه عیب‌یاب است:** گام ۱ دکمهٔ «بررسی سلامت» دارد (هشت جزء)، گام ۹ آزمون دو روشه، و + در کارنامه «شکست دادهٔ زنده» و «ذخیرهٔ کهنه» صریح گزارش می‌شود. یعنی خودش می‌گوید کجا مشکل است. +۲. **گزارش عیب‌یابی یک‌کلیکی:** دکمهٔ تازه در گام ۱ (`python diagnose.py`) یک پروندهٔ خوانا + می‌سازد: نسخهٔ پایتون، سلامت اجزا، وضعیت مجوز و اتصال، اثر انگشت موتور، وضعیت دفتر، و پرونده‌های + مهم. همان یک فایل را برای پشتیبانی بفرستید؛ لازم نیست اصطلاح فنی بدانید. +۳. **پشتیبانی شما، من هستم:** هر تغییری لازم شد، همین‌جا در گفتگو بگویید؛ من نسخهٔ به‌روز را + می‌سازم و شما فقط فایل را جای‌گزین می‌کنید. قرارداد هم ببندید که «رفع اشکال و به‌روزرسانی + عددها» داخل پشتیبانی ماهانه است؛ پس وقتی کاری نمی‌کنید، درآمد قطع نمی‌شود. +۴. **دور نگه‌داشتن پشتیبانی سنگین در قرارداد:** سه بند ساده بنویسید: (الف) پشتیبانی برای «خرابی + نرم‌افزار» و «تغییر قواعد بازار»، (ب) آموزش کاربران جدید فقط با هزینهٔ افزوده، (ج) درخواست + خارج از فهرست، پروژهٔ جدا حساب می‌شود. همین سه بند، ۸۰ درصد دردسرها را حذف می‌کند. + +--- + +## ۴. عمر طولانی و «لحظهٔ Jev [dʒɛv]»: چرا این برنامه سال‌ها بدون به‌روزرسانی کار می‌کند + +این سؤال بسیار درست است. پاسخی که می‌دهم، ویژگی طراحی این برنامه است، نه آرزو: + +- **هیچ وابستگی جانبی ندارد.** فقط کتابخانهٔ استاندارد پایتون و `tkinter`؛ نه سرور، نه پایگاه‌دادهٔ + ابری، نه اشتراک. چیزی که وابستگی نداشته باشد، «از مُد افتادن» ندارد. +- **در مسیر تصمیم، هیچ مدل زبانی نیست.** همهٔ عددهای تصمیم از ریاضی درمی‌آید. اگر فردا یک فناوری + تازه ترند شد (مثل Jev [dʒɛv])، برنامه بدون آن هم همان جواب را می‌دهد. مدل زبانی برای این برنامه + «تزیین» است، نه «ستون». +- **عددهای بازار در پروندهٔ تنظیمات است، نه در کد.** کارمزدها، نرخ سد، حد نگهداری وجه تضمین و کف + نقدشوندگی همه در `config` و در گام ۳ قابل تغییرند. وقتی سازمان بورس عددی را عوض کرد، شما در + سی ثانیه عدد را عوض می‌کنید؛ نه کد. +- **خودش تغییر را لو می‌دهد.** «اتصال خودکار» و «کاوش پاسخ سرویس» وقتی نشانی سرویس‌ها عوض شود، + خودشان مسیر تازه را پیدا می‌کنند؛ و اگر ساختار پاسخ عوض شود، آزمون‌ها سرخ می‌شوند و می‌گویند + کجا. یعنی عیب پیدا می‌شود، پنهان نمی‌شود. +- **شاهدهای قدیمی ارزششان را از دست نمی‌دهند.** اثر انگشت هر پرونده و زنجیرهٔ هش، سال‌ها بعد هم + قابل بازبینی است. این چیزی است که یک شرکت برای حسابرسی می‌خواهد. + +**اگر واقعاً فناوری تازه‌ای لازم شد**، قاعده یکی است: به شکل **افزودنی** وصل می‌شود، نه در قلب +تصمیم. نمونه‌اش همین حالا در برنامه هست: «دفتر اتصال» اجازه می‌دهد هر منبع دادهٔ تازه‌ای را +بدون تغییر در موتور وصل کنید. برای لایهٔ زبانی هم سر جای خودش نشسته است؛ نه گلوگاه تصمیم است، +نه اگر فردا عوض شود چیزی می‌شکند. + +--- + +## ۵. پول و واقعیت: چه چیزی در انتظار شماست، و چه چیزی نیست + +باید صریح باشم، چون به شما احترام می‌گذارم: **هیچ‌کس از یک قرارداد با یک شرکت، پولدار نمی‌شود.** +پول درست‌وحساب، از **تکرار** می‌آید: چند مشتری، چند سال، درآمد کم اما ماهانه. این مسیر واقعی است، +ولی زمان می‌برد و به سه چیز بستگی دارد: (۱) یک مشتری اول که نتیجه بگیرد، (۲) همان نتیجه به شکل +عدد و شاهد، (۳) صبر برای آمدن مشتری دوم. + +سه کار که امروز **از شما** لازم است و هیچ‌کدام پول نمی‌خواهد: + +۱. **مراسم روزانهٔ ده‌روزه** را روی لپ‌تاپ خودتان اجرا کنید (شصت ثانیه در روز) تا کارنامه از + «ناتمام» به «آماده» برسد. این تنها چیزی است که مشتری به آن نگاه می‌کند. +۲. **یک اجازه‌نامهٔ دو هفته‌ای آزمون** برای همان شرکتی که در ذهن دارید صادر کنید + (`python license.py --trial --grant "نام شرکت" --save`) و در جلسه نشان بدهید؛ این «تعهد صفر، + اعتماد کامل» است. +۳. **قرارداد ساده** را با من بنویسید (سه پله و سه بند پشتیبانی در بند ۱ و ۳ همین سند آماده است). + +و آن بخش انسانی: سرکوفت و فشار خانه، معیار خوبی برای تصمیم‌گیری نیست. تصمیم درست، قراردادی است +که شما را از پشتیبانی سنگین و از دست دادن مالکیت حفظ کند؛ نه قراردادی که امروز پول بیشتری بدهد و +شش ماه بعد شما را بیکار کند. + +--- + +## ۶. آنچه ادعا نمی‌کنم + +- تضمین درآمد ندارم؛ هیچ عددی در این سند وعدهٔ سود نیست. +- مدل «اجازه‌نامهٔ دسترسی» بدون قرارداد و بدون مشتری مشخص، هیچ درآمدی نمی‌سازد. +- اگر شرکتی بخواهد کد را در اختیار بگیرد، تنها راه مقاومت شما **توافق روشن** است، نه پنهان‌کاری؛ + و ارزش واقعی شما در ادامهٔ بهبود و آموزش است، نه در یک فایل. +- پشتیبانی ماهانه، تعهد ماهانه هم دارد؛ قرارداد را به‌اندازهٔ توان خودتان ببندید. + +✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · 📱 [989126630554](tel:+989126630554) · ✈️ [Telegram: Mojarabian](https://t.me/Mojarabian) · 📸 [Instagram: Mojarabian.Art](https://instagram.com/Mojarabian.Art) diff --git a/station/docs/10-daily-inputs-fa.md b/station/docs/10-daily-inputs-fa.md new file mode 100644 index 0000000000000000000000000000000000000000..fe4b63cbe51542a94071435f9dfcb250cb6ab147 --- /dev/null +++ b/station/docs/10-daily-inputs-fa.md @@ -0,0 +1,94 @@ +# هر روز چه چیزی وارد کنم؟ از کجا بگیرم؟ مجانی است؟ (۲۲ سپتامبر ۲۰۲۶) + +پاسخ کوتاه: **روزی یک بار، حدود شصت ثانیه، ده عدد در هر ردیف؛ همه‌شان مجانی.** هیچ اشتراکی +لازم نیست. همهٔ این عددها روی تابلوی کارگزاری خودتان یا در سایت‌های عمومی بورس هست و برای دیدنشان +هیچ پولی نمی‌دهید. + +> **قانون طلایی:** عددها را **از سامانهٔ کارگزاری خودتان** بردارید و در گام ۲ برنامه در جدول +> «وارد کردن اعداد کارگزاری» بنویسید، بعد «ذخیرهٔ اسنپ‌شات امروز» را بزنید. همین کار، روز شما را +> در کارنامه یک **روز واقعی** حساب می‌کند (نه روز ساختگی). در پایان همان کادر یک تیک هست: +> «این اعداد را خودم از سامانهٔ کارگزاری برداشتم». + +--- + +## ۱. ده عددی که هر روز لازم است (و محل مجانی هرکدام) + +| عدد | در برنامه با این نام | از کجا (مجانی) | +| --- | --- | --- | +| نماد و راهبرد | `symbol` · `kind` | از خودتان؛ نماد را از تابلوی کارگزاری و راهبرد را از نوع معامله‌تان بردارید | +| قیمت پایه (نقدی سهم یا دارایی) | `spot` یا `stock_price` | تابلوی کارگزاری، یا سایت `tsetmc.com`، تب «مشاهدهٔ زنده» همان نماد | +| قیمت آتی | `future` | تب «آتی» همان نماد در سایت بورس کالا و سامانهٔ کارگزاری | +| قیمت اعمال | `strike` یا `strike_low` و `strike_high` | تب «اختیار معامله» نماد؛ ستون قیمت اعمال قرارداد | +| پرمیوم اختیار خرید | `premium` یا `call_low` و `call_high` | همان تابلوی اختیار معامله؛ ستون «آخرین قیمت» اختیار خرید | +| پرمیوم اختیار فروش | `put_price` یا `put` | ستون «آخرین قیمت» اختیار فروش همان سررسید | +| روزهای مانده تا سررسید | `days` | تاریخ سررسید در تابلوی همان قرارداد منهای امروز (سایت خودش می‌نویسد) | +| وجه تضمین هر قرارداد | `margin_per_contract` | **فقط از کارگزاری** (اطلاعیهٔ وجه تضمین). هیچ سایت عمومی این عدد را دقیق نمی‌دهد | +| نقدشوندگی روز | `liquidity_contracts_per_day` | ستون «حجم» همان قرارداد در تابلوی امروز | +| اسپرد | `spread_pct` | اختلاف قیمت خرید و فروش تقسیم بر میانگین‌شان؛ تقریبی هم کافی است | + +نکتهٔ واحدها: `hurdle` و `spread_pct` **کسری**اند (۰٫۳۹ یعنی ۳۹٪ و ۰٫۰۰۵ یعنی نیم درصد)، +`capital` به ریال است، و بقیهٔ قیمت‌ها به ریال. + +--- + +## ۲. هر نوع معامله چه عددی می‌خواهد (فقط همان‌ها را پر کنید) + +| نوع معامله | چه عددهایی لازم است | +| --- | --- | +| خرید نقدی و فروش آتی (کری) | `spot` · `future` · `days` | +| پوشش‌داده‌شده (فروش اختیار خرید روی سهم) | `spot` · `strike` · `premium` · `days` | +| تبعی (تضمین فروش) | `stock_price` · `put_price` · `strike` · `days` | +| باکس اسپرد | `call_low` · `put_low` · `call_high` · `put_high` · `strike_low` · `strike_high` · `days` | +| تساوی پوت‌کال | `call` · `put` · `spot` · `strike` · `days` | + +برای هر ردیف، این سه همیشه لازم است: `margin_per_contract` · `liquidity_contracts_per_day` · +`spread_pct`. اگر راهبرد شما در این پنج نوع نیست، همان نزدیک‌ترین را بگذارید و در یادداشت بنویسید؛ +برنامه خودش می‌گوید عدد قابل محاسبه است یا نه. + +--- + +## ۳. چهار راه دادن داده، با هزینهٔ صادقانه + +| راه | هزینه | چه وقت مناسب است | +| --- | --- | --- | +| **۱. جدول داخل برنامه (پیشنهاد امروز)** | صفر | هر روز، همان شصت ثانیه. مطمئن، آفلاین، و روز واقعی حساب می‌شود | +| **۲. قالب پرونده (`data/snapshot-template.json`)** | صفر | اگر ترجیح می‌دهید عددها را در فایل بنویسید؛ قالب را با نام خودتان ذخیره کنید (`daily-input.json`) و عددهای واقعی بگذارید | +| **۳. سرویس عمومی وب (رایگان)** | صفر | اگر می‌خواهید برنامه خودش قیمت بخواند؛ گام ۲ «دفتر اتصال» و «بگرد و گزارش بده». رایگان است ولی «با شانس»: ممکن است کند یا قطع باشد | +| **۴. وب‌سرویس رسمی/خصوصی** | پول لازم دارد | **الان لازم نیست**؛ تا وقتی کارنامه «آماده» شده و خریدار مشخص نشده، هیچ پولی خرج نمی‌کنید (سند ۰۵ و ۰۶) | + +راه چهارم یعنی پایان کار با دست: در سایت `tsetmc.com` و در اطلاعیه‌های کدال (`codal.ir`) همهٔ +عددها هست؛ فقط باید خودتان بردارید. اگر روزی مشتری جدی آمد، همان زمان تصمیم می‌گیرید. + +--- + +## ۴. شصت ثانیهٔ روزانه، گام‌به‌گام (با نام دکمه‌های واقعی برنامه) + +۱. **گام ۲** → جدول «وارد کردن اعداد کارگزاری»: عددهای امروز را بنویسید (یا «خواندن اعداد فعلی» + را بزنید و ویرایش کنید) → تیک تأیید → **«ذخیرهٔ اسنپ‌شات امروز»**. +۲. **گام ۵** → **«اجرا و محاسبه»** روی همین منبع. +۳. **گام ۶** → هر سیگنال را ببینید و تأیید یا رد کنید (اجرا با خودِ شماست؛ برنامه سفارش نمی‌فرستد). +۴. **گام ۹** → **«۰. مراسم امروز»** (یا جداگانه «ثبت سیگنال‌های امروز» و «بازسنجی با قیمت‌های تازه»). +۵. **گام ۹** → **«کارنامهٔ آزمون»**: ببینید چند روز ثبت شده و آیا به «آماده» رسیده است. + +یا اگر عجله دارید: **گام ۹ → «۰. مراسم امروز»** خودش همهٔ این پنج کار را با یک دکمه انجام می‌دهد. + +--- + +## ۵. چه چیزی را هرگز وارد نکنید + +- **رمز و کد ورود سامانهٔ کارگزاری**: هیچ‌وقت. برنامه به سامانهٔ شما وارد نمی‌شود و لازم هم ندارد. +- **شمارهٔ حساب، کد بورسی، و اطلاعات هویتی**: لازم نیست. +- **سفارش و شمارهٔ سفارش**: برنامه سفارش نمی‌دهد و نمی‌گیرد؛ اجرا در سامانهٔ کارگزاری با خود شماست. +- **عدد حدسی**: عدد ساختگی هم صادقانه برچسب می‌خورد و آن روز «روز ساختگی» شمرده می‌شود، نه روز + واقعی. برای کارنامه و جلسهٔ شرکت فقط روزهای واقعی ارزش دارند (هدف: ۱۰ روز ثبت، دست‌کم ۵ روز با + دادهٔ واقعی). + +--- + +## ۶. اگر یک روز نتوانستم؟ + +هیچ چیزی خراب نمی‌شود. آن روز را ثبت نکنید و روز بعد ادامه بدهید؛ کارنامه روزها را می‌شمارد و +چیزی از شما کم نمی‌شود. سخت‌ترین بخش این کار، همین برداشتن ده عدد در روز اول است؛ از روز دوم +فقط جای اعداد در جدول عوض می‌شود. + +✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · 📱 [989126630554](tel:+989126630554) · ✈️ [Telegram: Mojarabian](https://t.me/Mojarabian) · 📸 [Instagram: Mojarabian.Art](https://instagram.com/Mojarabian.Art) diff --git a/station/docs/11-usage-and-percent-fa.md b/station/docs/11-usage-and-percent-fa.md new file mode 100644 index 0000000000000000000000000000000000000000..6c67963af7e7267c16b095d048deb4f090ef1c1d --- /dev/null +++ b/station/docs/11-usage-and-percent-fa.md @@ -0,0 +1,157 @@ +# ایدهٔ «شمارش استفادهٔ موفق» و درصدگرفتن — بررسی صادقانه (نسخهٔ ۰٫۱٫۱ · ۲۲ سپتامبر ۲۰۲۶) + +ایدهٔ شما: «هر کار موفقی که برنامه می‌کند جایی نگه دارد تا مطمئن شوم کارفرما چقدر از آن استفادهٔ +موفق داشته و بر همان پایه درصد بگیرم.» این ایده **نیمه‌اش درست و نیمه‌اش خطرناک** است. این سند +همان دو نیمه را جدا می‌کند، و همه‌جا می‌گوید کدام مدل **ساخته شده** و کدام فقط روی کاغذ است. + +> **داوری یک‌خطی:** «چقدر از برنامه استفاده شده» شمردنی است و همین حالا ساخته شده +> (`gui/usage_meter.py` + کارت «گواهی استفادهٔ موفق» در پنل مدیریت). «درصد از سود معاملات» را +> نمی‌شود بی‌دادهٔ کارگزاری اثبات کرد و توصیه نمی‌کنم؛ ولی «درصدِ کوچک بر پایهٔ شاهدِ امضاشدهٔ +> همان ماه» قابل دفاع و قابل امضا است. + +--- + +## ۱. نیمهٔ درست ایده: کارهای موفق **قابل شمردن**اند + +دفتر استفادهٔ موفق، شانزده نوع کار را می‌شناسد. این فهرست از خودِ برنامه می‌آید +(`KIND_LABELS` در `usage_meter.py`)، نه از تخیل من: + +| نوع کار | کلید انگلیسی | چرا «موفق» حساب می‌شود | +| --- | --- | --- | +| اجرای موتور روی دادهٔ روز | `run` | موتور روی اسنپ‌شات امروز اجرا شد و سیگنال‌ها بازتولیدشدنی‌اند | +| داوری سیگنال (می‌ماند یا می‌افتد) | `judge` | سیگنال ابزار دیگران با کارمزد، اسپرد، نقدشوندگی و نرخ سد سنجیده شد | +| تصمیم ثبت‌شده (خرید/فروش/رد) | `decision` | تأیید یا ردِ سیگنال با دلیل در دفتر تاریخ‌دار نشست | +| مراسم روزانهٔ شصت‌ثانیه‌ای | `ritual` | آن روز، آزمون دو هفته‌ای یک گام جلو رفت | +| آزمون ۱۰ دقیقه‌ای ایستگاه | `exam` | ۱۵ سنجه، هر کدام دو بار (موتور و حساب دستی) اجرا شد | +| بستهٔ شاهد شرکت | `bundle` | پوشهٔ تحویل به مدیر ریسک ساخته شد و اثر انگشت پرونده‌ها ثبت شد | +| آزمون کور سرمایه‌گذار | `blind` | خودِ سرمایه‌گذار حدس زد؛ شاهد بی‌طرف از بیرون آمد | +| برگهٔ شاهد زندهٔ داده | `witness` | قیمت از منبع واقعی خوانده شد و هش پاسخ خام ثبت شد | +| پلهٔ تصمیم (چه بخرم/کِی بفروشم) | `ladder` | جدول آستانهٔ خرید و فروش و افتادن ساخته شد | +| پیمان‌نامهٔ نمایش | `pledge` | سند دواِمضای جلسه آماده شد | +| مجوز دسترسی و پشتیبانی | `license` | اجازه‌نامهٔ نام‌دار و سند چاپی‌اش صادر شد | +| پروندهٔ سرمایه‌گذار | `dossier` | پروندهٔ نه‌بخشی با اثر انگشت هر پرونده ساخته شد | +| ثبت اعداد روز | `snapshot` | اعداد کارگزاری امروز، تاریخ‌دار، ذخیره شد | +| ورود اعداد از متن کارگزاری | `import` | جدول چسبانده‌شده خوانده و به اعداد پاکیزه تبدیل شد | +| برگهٔ راهبردها و شوک‌آزمون | `strategy` | جزوهٔ راهبردها و جدول «اگر این‌طور شد چه می‌شود» ساخته شد | +| ریاضیِ بقا و مسیر رشد | `math` | کِلی، احتمال نیم‌شدن حساب و مسیر تا هدف حساب شد | + +چهار ویژگی دفتر، همان چیزی است که آن را به «شاهد» تبدیل می‌کند: + +**محلی است.** فایل دفتر `gui/data/usage-ledger.json` روی رایانهٔ خودِ شرکت می‌ماند و هیچ رشتهٔ +شبکه‌ای در آن نیست. برای بازبینی هم فقط همان فایل لازم است. + +**زنجیره‌هش‌دار است.** هر ردیف، اثر انگشت `sha256` ردیف پیشین را در خود دارد. اگر کسی ردیفی را +کم یا عوض کند، زنجیره می‌شکند و همان‌جا نوشته می‌شود «شکسته ⚠️ (ردیف N)»؛ نه اینکه به‌جای عدد، +سکوت بگذارد. + +**بی‌دادهٔ مالی است.** دفتر فقط «نوع کار» و «توضیح کوتاه» و ساعت را نگه می‌دارد. عددهای یادداشت +هم قبل از ثبت پاک‌سازی می‌شوند: هر عدد بلند یا جداکننده‌دار به «‹عدد›» تبدیل می‌شود و تلفن و +ایمیل هم ماسک می‌شوند، تا اشتباهی چیزی وارد دفتر نشود که نباید. + +**دو امضا دارد.** گواهی، جای امضای ارائه‌دهنده و امضای شرکت را دارد و در پایان می‌نویسد با +یک فرمان می‌شود همه‌اش را بازتولید کرد: + +```bash +cd /home/user/MATERIALS/money/gui +python3 usage_meter.py --summary --verify # عددها + سالم‌بودن زنجیره +python3 usage_meter.py --statement --client "نام شرکت" # گواهی دواِمضا (HTML و متن) +``` + +## ۲. نیمهٔ خطرناک: «درصد از سود» را نمی‌شود اثبات کرد + +۱. **بدون دادهٔ کارگزاری، سود را نمی‌شود سنجید.** برنامه سفارش نمی‌فرستد، پس نمی‌داند کدام پیشنهاد + اجرا شد و به چه قیمتی. هر عدد سودی که برنامه «حساب» کند، قابل اعتراض است. +۲. **تعارض منافع و ریسک حقوقی.** اگر درآمد شما به سود گره بخورد، انگیزه‌تان به «معاملهٔ بیشتر» + می‌رود؛ همان چیزی که در این بازار بیشتر آدم‌ها را می‌بازد. شرکت هم می‌تواند هر زیان را به گردن + شما بیندازد. +۳. **تناقض با موضع خودمان.** شما همه‌جا نوشته‌اید «سود تضمین نمی‌شود». مدل درصد از سود، خلاف این + جمله است و اعتماد را خراب می‌کند. + +خودِ برنامه هم همین را به زبان ماشین می‌گوید. `percent_model()` در `usage_meter.py` برای +«درصد از سود» حکم **«رد می‌کنم»** دارد، با سه دلیل: سود تضمینی نیست · اندازه‌گیری سود به دفتر +سرمایهٔ مشتری گره می‌خورد · ریسک را به طرف ضعیف‌تر قرارداد منتقل می‌کند. برای دیدنش: + +```bash +python3 usage_meter.py --percent-model +``` + +## ۳. مدل قابل دفاع: درصدِ کوچک بر پایهٔ **شاهدِ امضاشده** + +سه جایگزینِ ساخته‌شده و راستی‌آزمایی‌پذیر (همان خروجی `--percent-model`): + +| مدل | چه چیزی سندِ آن است | برای چه کسی | +| --- | --- | --- | +| **اشتراک ماهانه** | تاریخ پرداخت و شمارش کارهای همان ماه | شرکت یا کارگزاری که برنامه را روزانه به کار می‌برد | +| **اشتراک به‌ازای روز فعال** | «روزهای فعال» همین دفتر؛ عددی که هر دو طرف می‌توانند بازتولید کنند | کسی که بعضی روزها کار می‌کند؛ از ماهانهٔ ثابت منصفانه‌تر است | +| **پاداش به‌ازای شاهد** | برگهٔ شاهد زنده یا آزمون کور که اثر انگشت دارد | هر تحویل قابل‌سنجش، بدون وعدهٔ سود | + +قاعدهٔ ساده، اگر خواستید پاداش را به «کارِ انجام‌شده» گره بزنید: **نرخ توافقی × شمارشِ همان ماه** +با سه قید: سقف ماهانه داشته باشد، فقط روی شاهدهای امضاشدهٔ همان ماه حساب شود، و پایهٔ محاسبه +(کارمزد خرید ۰٫۴۶٪ و فروش ۰٫۹۶٪ سهام؛ مشتقه ارزان‌تر) در قرارداد نوشته شود. عدد «ارزش کار» را هم +برنامه فقط با **فرض صریح** می‌سازد: ۱٫۵۰۰٫۰۰۰ ریال برای هر دقیقه کار انسانی و پنج دقیقه برای هر +کار. اگر این فرض را قبول نکنید، همان ستون شمارش و اثر انگشت زنجیره می‌ماند؛ گواهی با فرض قبول +نشده هم کار می‌کند. + +## ۴. چهار مدل، با سود و زیان + +| مدل | برای شما | برای شرکت | داوری | +| --- | --- | --- | --- | +| **الف) اشتراک ثابت** (راه‌اندازی + ماهانه) | درآمد پایدار و ساده | هزینهٔ قابل پیش‌بینی | **پیشنهاد اصلی** | +| **ب) اشتراک به‌ازای روز فعال** | منصفانه‌تر، درآمد کمی پرنوسان‌تر | پول در برابر روزهایی که واقعاً کار شده | **خوب؛ عددِ سندش داخل خود دفتر است** | +| **ج) پاداش به‌ازای شاهد** (با شاهد امضاشده) | سقف درآمد بالاتر | پول فقط وقتی کارِ قابل‌نشان تحویل شده | **خوب، اگر قاعده نوشته شود** | +| **د) درصد از سود معاملات** | پرنوسان، پرتنش | انگیزهٔ معاملهٔ بیشتر | **توصیه نمی‌کنم** | + +## ۵. جملهٔ آماده برای جلسه + +«من نمی‌خواهم از سود معاملات شما سهم بگیرم؛ نمی‌توانم و نمی‌خواهم آن را اثبات کنم. پیشنهاد من +این است: یک اجازه‌نامهٔ دسترسی با حق ثابت، و اگر خواستید، پاداش کوچکی بر پایهٔ گزارش ماهانه‌ای +که هر ردیفش سند دارد؛ یا روزهای فعالی که خودتان هم می‌توانید بشمارید، یا برگه‌های شاهد +اثرانگشت‌دار. هر ماه همین گواهی را امضا می‌کنیم و اگر سندش نبود، پولی بابت آن گرفته نمی‌شود.» + +## ۶. حریم خصوصی: این را در جلسه بگویید، فروش را آسان می‌کند + +دفتر استفاده **روی رایانهٔ خودشان** است، به اینترنت وصل نمی‌شود، و هیچ دادهٔ مالی یا اسمی در آن +نیست. بازبینی‌اش هم یک فرمان است: + +```bash +python3 usage_meter.py --summary | grep حریم +# دفتر پاکیزه است: هیچ کلید مالی (قیمت/سود/موجودی/حساب) در آن نیست. +``` + +برنامه ۲۱ کلید ممنوع را می‌شناسد (قیمت، سود، موجودی، حساب، مبلغ، سپرده و مانند آن) و اگر روزی +یکی از آن‌ها به دفتر برسد، در همان گزارش نامش را می‌گوید. همین را در قرارداد به‌شکل یک بند +بنویسید: «ابزار هیچ داده‌ای را به بیرون منتقل نمی‌کند.» شرکتی که این را بداند، خیلی راحت‌تر +امضا می‌کند. + +## ۷. گواهی، داخل بستهٔ شاهد هم می‌رود + +وقتی گام ۸ بستهٔ تحویل شرکت را می‌سازد، برنامه خودش گواهی استفاده را از دفتر همان رایانه تازه +می‌کند و کنار بقیهٔ شاهدها می‌گذارد (`17-usage-statement.html` و `18-usage-statement.md`)، همراه +با اثر انگشت `sha256` و ساعت ساخت. پس مدیر ریسک لازم نیست چیزی از شما بخواهد؛ سند داخل پوشه است. + +## ۸. قرارداد فنی این دفتر (برای بازبینی شرکت یا برنامه‌نویس خودشان) + +| کار | فرمان یا تابع | +| --- | --- | +| ثبت یک کار | `python3 usage_meter.py --record judge --label "داوری سیگنال فولاد"` | +| خلاصهٔ عددها | `python3 usage_meter.py --summary` یا `--json` برای ماشین‌خوان | +| سالم‌بودن زنجیره | `python3 usage_meter.py --verify` → `chain_ok` و `broken_at` و اثر انگشت `last_chain` | +| گواهی دواِمضا | `--statement --client "نام شرکت" --period "مهر ۱۴۰۵"` | +| مدل درصد | `--percent-model` | +| ارزش فرضی کار | `avoided_cost(summary)` با فرض صریح؛ ادعا نیست | +| در کد | `record` · `record_event(kind, label, note, path=…)` · `verify_chain(path)` · `privacy_check(path)` · `summary(path)` · `build_statement(summary, client=…)` | + +خلاصهٔ ماشین‌خوان این کلیدها را می‌دهد: `success_total` · `today` · `last_7_days` · +`active_days` · `by_kind` (انگلیسی) و `by_kind_label` (فارسی) · `chain_ok` · `broken_at` · +`kept_local` · `privacy` · `trial_days` و `real_days` (روزهای تمرینی و واقعی، جدا). + +## ۹. آنچه ادعا نمی‌کنم + +- گواهی استفاده، **سود** یا **درصد موفقیت در بازار** را اثبات نمی‌کند؛ فقط شمارش کارها و تمامیت + دفتر را نشان می‌دهد. +- شمارش، «کارِ انجام‌شده» را می‌شمارد نه «کیفیت کار». کیفیت را پروندهٔ سرمایه‌گذار، آزمون کور و + پس‌آزمایی نشان می‌دهند؛ سه سند دیگر. +- مدل پاداش، بدون شاهدِ امضاشدهٔ همان ماه، قابل مطالبه نیست؛ و همین است که آن را قابل دفاع می‌کند. +- هیچ‌کدام از این مدل‌ها، مشتری تضمین‌شده نمی‌سازد؛ مشتری اول، کارِ بیرون از این پرونده است. + +✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · 📱 [989126630554](tel:+989126630554) · ✈️ [Telegram: Mojarabian](https://t.me/Mojarabian) · 📸 [Instagram: Mojarabian.Art](https://instagram.com/Mojarabian.Art) diff --git a/station/docs/12-wealth-math-and-no-purchase-fa.md b/station/docs/12-wealth-math-and-no-purchase-fa.md new file mode 100644 index 0000000000000000000000000000000000000000..96aaaadd93520caa90e0f61e47889ab479c5ce63 --- /dev/null +++ b/station/docs/12-wealth-math-and-no-purchase-fa.md @@ -0,0 +1,154 @@ +# با ریاضی می‌شود ثروتمند شد؟ — جواب صادقانه، با عدد و با مرزها + +**نسخهٔ ۰٫۱٫۰ · شهریور ۱۴۰۵** + +این سند جواب همان چیزی است که پرسیدید: «امکانش نیست برنامه را تقویت کنی که واقعاً ازش بشه +پول‌های خوبی درآورد؟ ایده‌های جدید بده و مطمئن شو ایده‌های قبلی واقعاً جواب می‌دهند؟» + +جواب کوتاه: **بله، با ریاضی می‌شود، ولی نه با پیش‌بینی. با سه چیز:** هر سه هم ریاضی است و هم +در همین ایستگاه سنجیده شده: + +۱. **مزیت عددی**: در هر معامله باید عددی قفل‌شده از نرخ سد بگذرد. این عدد امروز هست یا نیست؛ + حدس نیست. +۲. **بقا**: اندازهٔ هر موقعیت باید کوچک باشد تا نیم‌شدن حساب احتمالش کم شود. با سرمایهٔ کم، + بقا مهم‌تر از سرعت است. +۳. **زمان**: رشد مرکب کند است. عددش را می‌شود حساب کرد؛ وعده‌اش را نمی‌شود داد. + +سه سند تازهٔ همین هفته دقیقاً همین سه را می‌سازد: **جزوهٔ راهبردها** (مزیت)، **شوک‌آزمون** +(آیا ایده‌های قبلی زیر شرایط بد هم می‌مانند؟)، و **ریاضیِ پول** (بقا و زمان). هیچ‌کدام وعدهٔ +درصد سود نمی‌دهد و هیچ‌جا عددی بدون برچسب روش منتشر نشده است. + +--- + +## ۱. ایده‌های جدید (و ایده‌های قبلی) با درصد امروزشان + +هر عدد دو روش دارد: **موتور ایستگاه** و **محاسبهٔ دستی دوم**. اگر این دو نخوانند، در جدول +علامت «مخالف» می‌خورد و عدد دور انداخته می‌شود. برچسب روش هم سه حالت دارد: + +- **قطعی**: در لحظهٔ وارد‌شدن قفل می‌شود (تبعی، باکس، مبنا). +- **مدل‌محور**: با نوسانِ ضمنیِ خودِ بازار و فرض بلک-شولز حساب می‌شود. تخمین است، نه پیش‌بینی. +- **نقل‌شده**: از منبع بیرونی، با نام منبع. + +| راهبرد | دسته عدد | عدد امروز (اسنپ‌شات خود شما) | بعد از شوک‌ها | +| --- | --- | --- | --- | +| مبنا (خرید نقدی + فروش آتی) | قطعی | **۶۸٫۴۸۲٪ سالانه** (نماد اهرم) | سخت‌جان: هر پنج شوک را رد کرد | +| پوشش‌داده‌شده (فروش اختیار خرید) | قطعی + مدل | **۵۶٫۵۵۸٪ سالانه** (نماد فولاد) · احتمال مدل‌محور ماندن زیر اعمال ۶۱٫۹٪ | سخت‌جان | +| اوراق تبعی (کمینهٔ تضمینی) | قطعی | **۴۲٫۳۶۱٪ سالانه** (نماد کگل) | لبِ مرز: با نرخ سد ۴۵٪ می‌افتد | +| باکس اسپرد | قطعی | **۶۷٫۸۶۸٪ سالانه** (نماد شپنا) | لبِ مرز: لغزش ۰٫۵٪ حاشیه را تا ۳۵٫۸٪ می‌آورد | +| اوراق تبعی (ردیف دوم) | قطعی | **۲۴٫۶۹۲٪ سالانه** (نماد خساپا) | نمی‌ارزد: از قبل زیر نرخ سد است | +| مبنا (ردیف دوم) | قطعی | **۱۶٫۸۲۳٪ سالانه** (نماد طلا) | نمی‌ارزد: از قبل زیر نرخ سد است | +| تساوی پوت-کال | قطعی | **نه** (شکاف از کارمزد سه پایه بزرگ‌تر نیست) | نمی‌ارزد | +| صندوق درآمد ثابت (خط پایه) | نقل‌شده | ۳۹ تا ۴۰٪ مؤثر (شهریور ۱۴۰۵) | خط پایهٔ مقایسه، نه معامله | + +**نکتهٔ مهم جدول:** عدد بزرگ دلیل خوبی نیست. «مبنا ۶۸٪» فقط به این معناست که اگر همان قرارداد +را تا سررسید نگه دارید و دو پا را هم‌زمان ببندید، عدد روی کاغذ همان است؛ ریسک واقعی‌اش +مارجین‌کال و نقدشوندگی است. برای همین سند دوم ساخته شد. + +## ۲. شوک‌آزمون: مطمئن شدن اینکه ایده‌های قبلی واقعاً جواب می‌دهند + +هر راهبرد با پنج بدترشدن دوباره حساب می‌شود و جواب «می‌ماند / می‌افتد» می‌گیرد. سه دسته: + +- **سخت‌جان** (همهٔ پنج شوک را رد کرد): مبنا (اهرم)، پوشش‌داده‌شده (فولاد). +- **لبِ مرز** (رد کرد، ولی حاشیهٔ پس از شوک کمتر از ۵ واحد درصد شد): باکس اسپرد (شپنا)، + اوراق تبعی (کگل). یعنی این دو با یک بدترشدن کوچک می‌افتند. +- **تلاش‌های بی‌نتیجه که در سند می‌مانند**: تساوی پوت-کال (وبملت)، تبعی خساپا، مبنای طلا. + این‌ها حذف نمی‌شوند، چون «چه چیزی نخر» هم بخشی از تصمیم است. + +عددهای مرزی که برای شما از همه مهم‌ترند: + +- **فاصله تا اخطاریهٔ مارجین‌کال: ۶٪ حرکت مخالف.** این از قاعدهٔ بورس می‌آید (حد نگهداری ۷۰٪ + وجه تضمین اولیه؛ با نسبت اولیهٔ ۲۰٪، یعنی ۲۰٪ × ۳۰٪ = ۶٪). پس حد ضرر منطقی باید نزدیک‌تر + از ۶٪ باشد، نه دورتر. +- **تحمل کارمزد**: مبنا و پوشش‌داده‌شده تا ۱۲ برابر کارمزد امروز هم می‌مانند؛ بستهٔ اسپرد و تبعی + زودتر می‌افتند (تبعی کگل: با ۴٫۶۷ برابر). +- **باکس اسپرد با لغزش اجرای ۰٫۵٪** از ۶۷٫۸٪ به ۳۵٫۸٪ می‌افتد: یعنی این راهبرد عملاً به + نقدشوندگی و اسپرد واقعی زنده است. + +## ۳. ریاضیِ بقا و زمان (همان چیزی که «ثروتمند شدن» به آن بسته است) + +سه عدد، سه درس: + +۱. **اندازهٔ درست هر معامله (کِلی، برگرفته از کار جان کِلی /ˈkɛli/)**: با نرخ برد ۵۵٪ و سود برد ۸٪ و زیان باخت ۵٪، مزیت هر + معامله ۲٫۱۵٪ و کسر کِلی ۰٫۲۷ و نسخهٔ محافظه‌کارانهٔ آن (نصف‌کِلی) ۰٫۱۳ است. یعنی حدود + ۱۳٪ سرمایه در هر معامله، نه ۱۰۰٪. عدد بزرگ‌تر، پول بیشتر نمی‌آورد؛ ورشکستگی می‌آورد. + +۲. **کم‌ترین نرخ برد لازم (سر‌به‌سر)**: با سود ۸٪ و زیان ۵٪ و کارمزد رفت‌وبرگشت سهم + (۱٫۴۲۸٪)، کم‌ترین نرخ برد **۴۹٫۴۵٪** است. زیر این عدد، هر راهبردی بازنده است: ریاضی، + نه نظر. نرخ برد خودتان را از دفتر حساب در بیاورید، نه از حافظه. + +۳. **مسیر رشد راهبرد**: عدد ۶۸٫۴۸٪ سالانه با یک بار چرخش در سال، خالص ۶۷٫۰۵٪ می‌شود و + ۴ برابر شدن سرمایه حدود **۳۲ ماه (۲٫۷ سال)** طول می‌کشد، به شرط اینکه رشد مثبت بماند و + هیچ ماه بحرانی حساب را نصف نکند. اگر ماهی چند بار بچرخانید، کارمزد همان مزیت را می‌خورد. + +شبیه‌سازی ۲۰٬۰۰۰ مسیر فرضی هم این را نشان می‌دهد: با اندازهٔ کوچک، احتمال نیم‌شدن حساب کمتر +از یک درصد می‌شود؛ با اندازهٔ درشت، همان مزیت به ورشکستگی می‌رسد. + +**پس «ثروتمند شدن با ریاضی» دقیقاً این است:** مزیت را قفل کن، اندازه را کوچک نگه دار، کارمزد +را کم کن، و زمان بده. هیچ‌کدام از این چهار تا «شانس» نیست، ولی هیچ‌کدام هم «تضمین» نیست. + +## ۴. آیا باید چیزی بخرید؟ نه. + +| پرسش | جواب | +| --- | --- | +| آیا برای این برنامه باید **Jev** بخرم؟ | **نه.** Jev فقط لایهٔ خلاصه‌سازی خبر و متن است؛ کل ریاضی، داوری سیگنال، پلهٔ تصمیم و برگهٔ شاهد بدون آن کار می‌کند. | +| پس Jev به چه کار می‌آید؟ | برای خواندن انبوه خبر کدال و تلخیص فارسی. «خوبی» است، نه «لازم». | +| جایگزین رایگانش چیست؟ | ۱. همان قواعد کلیدواژه‌ای و امتیازدهی که در ایستگاه هست؛ ۲. اگر خواستید، یک مدل کوچک محلی (`Ollama`) روی همین رایانه، بدون کلید و بدون هزینه؛ ۳. حتی بدون هیچ‌کدام، تصمیم‌ها با عدد بازار گرفته می‌شود، نه با خبر. | +| آیا باید وب‌سرویس دادهٔ پولی بخرم؟ | **نه.** خوراک آزمایشی محلی (رایگان، ساختگی ولی کامل) برای نشان‌دادن کارکرد کافی است. برای دادهٔ **واقعی** هم یک مسیر رایگان و بدون کلید آزموده شد: tgju برای دلار، گرم طلای ۱۸، سکهٔ امامی، نیم و ربع (پاسخ ۲۰۰ در ۰٫۳ تا ۱٫۸ ثانیه؛ پنج عدد با یک نقطهٔ پایانی مستقل مقایسه و تأیید شد). شاهد با هش پاسخ خام: `gui/data/real-feed-proof.md`. سهام و آتی و اختیار از محیط من بسته بود (۰ از ۶ نشانی TSETMC)؛ همین آزمون را روی رایانهٔ خودتان بزنید: `python3 data_sources.py --all`. وجه تضمین را فقط کارگزاری می‌دهد. | +| پس پول به چه چیزی می‌رود؟ | به **جای دیگری نروید**: سرمایهٔ خودتان فقط وقتی سر کار می‌رود که عددها می‌گذرند. تا آن‌وقت، خروجی کار شما «شاهد» است، نه خرید سرویس. | + +اگر روزی Jev یا ابزار مشابهی ترند شد و مشتری‌ها آن را خواستند، همان‌جا ارزش دارد: چون کار شما +«داوری سیگنال با ریاضی» است و آن‌ها «تولید متن». دو کار جدا هستند. + +## ۵. چطور ارزشش را به سرمایه‌گذار ثابت کنیم (آزمون عملیاتی بی‌پول) + +پنج گام، همه روی همین رایانه، همه با هزینهٔ صفر: + +۱. **گام ۱۱ را باز کنید، «ساخت جزوه + شوک‌آزمون» را بزنید.** برگهٔ چاپی را بدهید دستش؛ بگذارید + خودش یک عدد را با ماشین‌حساب بازتولید کند. +۲. **برگهٔ شاهد زنده** (گام ۲): نشان می‌دهد قیمت‌ها همین حالا از سرویس خوانده شده‌اند، با ساعت، + نشانی و اثر انگشت پاسخ خام. این برای رفع شک «عددها را خودت نوشتی» است. +۳. **آزمون کور** (گام ۱۰): شش پرسش؛ اول او حدس می‌زند، بعد پاسخ برنامه با فرمول و روش دوم رو + می‌شود. اگر ماشین‌حساب او با برنامه نخواند، برگه اعتبار ندارد. +۴. **دفتر آزمون زنده** (گام ۹): پنج روز کاری، هر روز شصت ثانیه ثبت. آخر هفته برگهٔ کارنامه با + زنجیرهٔ هش بیرون می‌آید: هیچ سطری بعد از ثبت عوض نشده است. +۵. **پیمان‌نامهٔ نمایش** (گام ۱۰، کارت ۴): یک برگ دو امضا: چه چیزی اثبات می‌شود (بازتولید عدد، + کارمزد واقعی، آستانهٔ افتادن، زنجیرهٔ هش) و چه چیزی نه (سود آینده، پیش‌بینی قیمت). + +اگر پرسید «درصد سودت چقدر است؟»، جواب درست این است: «درصد سود را وعده نمی‌دهم. نشان می‌دهم +چه چیزی ریاضی می‌ماند و چه چیزی می‌افتد، با کارمزد واقعی و با عددی که خودتان روی ماشین‌حساب +بازتولید می‌کنید.» + +## ۶. کاری که فقط خودتان می‌توانید بکنید (کوتاه و بدون دور زدن) + +- **عدد وجه تضمین** را از کارگزاری بگیرید (یا از پنل برخط) و در گام ۳ وارد کنید. تا وقتی این + عدد نباشد، فاصلهٔ مارجین‌کال با فرض ۲۰٪ حساب می‌شود، نه با عدد واقعی. +- **شصت ثانیهٔ ضبط روزانه** (مراسم گام ۹): این تنها کاری است که سیستم نمی‌تواند به‌جای شما + انجام دهد و دقیقاً همان چیزی است که یک کارفرما برایش پول می‌دهد. +- **سه تماس**: سه کارگزاری بپرسید «آیا برای مشتری، وب‌سرویس یا فایل روزانه می‌دهید؟» جواب‌ها را + در گام ۲ همان دفتر اتصال وارد کنید. هزینه‌اش صفر است. + +## ۷. خط قرمزها (که در همین سند رعایت شده) + +- هیچ‌جا نگفته‌ایم «درصد موفقیت فلان راهبرد ۹۰٪ است». هر عدد یا قفل‌شده است، یا مدل‌محور با + فرض صریح، یا نقل‌شده با نام منبع. +- «نرخ تاب‌آوری» احتمال سود نیست؛ سهم شوک‌هایی است که راهبرد از آن‌ها سالم بیرون آمده. +- دادهٔ تاریخی بلند در این محیط در دسترس نبود، پس هیچ «درصد برد تاریخی» ادعا نشده است. +- ابزار سنجش منبع، هرگز از حافظهٔ کهنه «موفقیت تازه» نمی‌سازد؛ اگر شبکه جواب ندهد، صریح می‌گوید «پاسخی نیامد». (قفل آزمون: `tests/test_datafeed_honesty.py`.) +- هیچ سفارشی به کارگزاری فرستاده نمی‌شود؛ تصمیم‌گیری انسانی است. (الزام ابلاغیهٔ مهر ۱۳۹۹ + دربارهٔ معاملات الگوریتمی مشتریان برخط.) + +## ۸. از کجا شروع کنم (سه فرمان، همین امشب) + +```bash +cd MATERIALS/money/gui +python3 strategy_audit.py # جزوهٔ راهبردها + حسابرسی دو-روشی +python3 edge_stress.py # شوک‌آزمون: کجا می‌افتد +python3 bankroll.py --capital 100000000 --target 400000000 # ریاضیِ بقا و زمان +``` + +خروجی‌ها: `data/strategy-library.html`، `data/edge-stress.html`، `data/bankroll.html` و نسخه‌های +متنی همین‌ها. در رابط مرورگری هم همه‌شان با یک دکمه در **گام ۱۱** ساخته می‌شوند. + +--- + +✍️ تهیه‌کنندهٔ جزوات: **Masoud Mojarabian** · 📱 +989126630554 · ✈️ [Telegram: Mojarabian](https://t.me/Mojarabian) · 📸 [Instagram: Mojarabian.Art](https://instagram.com/Mojarabian.Art) diff --git a/station/docs/13-novice-walkthrough-fa.md b/station/docs/13-novice-walkthrough-fa.md new file mode 100644 index 0000000000000000000000000000000000000000..c83f8b3ba390faea909dab3d17736db4c73be4e0 --- /dev/null +++ b/station/docs/13-novice-walkthrough-fa.md @@ -0,0 +1,298 @@ +# راهنمای هر بخش، برای کسی که تازه‌کار است + نقشهٔ صادقانهٔ اتوماسیون (نسخهٔ ۰٫۱٫۰ · ۲۲ سپتامبر ۲۰۲۶) + +این سند برای کسی نوشته شده که **هیچ شناختی** از مشتقه و آپشن ندارد. دو کار می‌کند: بخش‌به‌بخشِ +برنامه را با نام واقعی دکمه‌ها توضیح می‌دهد، و صادقانه می‌گوید کدام ورودی خودکار است، کدام +نیمه‌خودکار، و کدام دستی می‌مانَد و **چرا**. + +**چهار قانون که همه‌جای برنامه برقرار است:** هیچ سفارشی از این برنامه به کارگزاری نمی‌رود · هیچ +سودی تضمین نمی‌شود · هر عدد کلیدی با دو روش حساب می‌شود و بازتولیدشدنی است · هر چه وارد می‌کنید +روی همین رایانه می‌ماند و جایی فرستاده نمی‌شود. + +--- + +## ۱. پیش از هر چیز: باز کردن برنامه + +**ویندوز:** `run-gui.bat` را دوبار کلیک کنید. **لینوکس/مک:** در پوشهٔ `MATERIALS/money/gui` بزنید +`python3 web_server.py --port 8765` و بعد در مرورگر بروید به `http://localhost:8765`. اگر برنامهٔ +دسکتاپ می‌خواهید، `station.py` همان یازده گام را پنجره‌ای باز می‌کند. + +کنار صفحه فهرست گام‌ها است. هر گامی که تمام شود، شماره‌اش سبز می‌شود؛ پس همیشه می‌دانید کجای +کار ایستاده‌اید. اگر چیزی باز نشد یا خطا داد، اول **گام ۱ → باز کردن پنل مدیریت → بررسی سلامت +برنامه**؛ اگر همهٔ اجزا سالم بود، مشکل از آن بخش است نه از نصب شما. + +--- + +## ۲. بخش‌به‌بخش، با دکمه‌های واقعی + +### بخش ۰. پنل مدیریت (نشانی `/admin` — از گام ۱ هم دکمه‌اش هست) + +**چه کار می‌کند:** سه کاری که نباید دست مشتری باشد: بررسی سلامت · مجوز دسترسی و عیب‌یابی · گواهی +استفادهٔ موفق. +**چه می‌خواهد:** شناسه و رمز. پیش‌فرض `mafhoom` است و رمز را خودتان عوض می‌کنید: +`python3 adminauth.py --set-pass "رمز تازه"` (رمز فقط هش‌شده ذخیره می‌شود، متن آن هیچ‌جا نمی‌ماند). +**چه بزنید:** ۱) «بررسی سلامت برنامه» → باید بنویسد **۸ از ۸ سالم**. ۲) در بخش مجوز: نام شرکت و +مدت را بنویسید، «صدور مجوز»، بعد «ساخت سند مجوز (چاپی)» تا پروندهٔ دواِمضا آماده شود. ۳) در بخش +گواهی: «ساخت گواهی استفاده» و «نمایش». +**چه چیزی خوب است:** توکن ورود یک‌ساعته است و سهلایه اشتباه رمز، پنج دقیقه قفل می‌شود. اگر نوشت +«توکن نامعتبر یا منقضی»، یعنی یک ساعت گذشته؛ دوباره وارد شوید. + +### گام ۱. خوش‌آمد + +**چه کار می‌کند:** خانهٔ شروع و دکمهٔ پنل مدیریت. +**چه بزنید:** اگر اولین بار است، همین‌جا پنل را باز کنید و سلامت را ببینید؛ بعد بروید گام ۲. + +### گام ۲. منبع داده — مهم‌ترین گام برای شما + +این گام چهار کاربلوک دارد. لازم نیست همه را انجام بدهید؛ **فقط یکی** که به کارتان می‌آید: + +**الف) دیدن برنامه بدون هیچ راه‌اندازی.** «ساخت قالب نمونه» → «آزمایش خواندن این پرونده». قالب در +`data/snapshot.json` ساخته می‌شود، برنامه هم همان را می‌خواند و می‌گوید چند ردیف خواند. + +**ب) دادهٔ زندهٔ رایگان و بدون کلید.** از کادر «دفتر اتصال» یک پروفایل انتخاب کنید → «آزمایش اتصال +این پروفایل» → اگر سبز شد «ذخیره و فعال کردن». اگر مطمئن نیستید کدام کار می‌کند، «بگرد و گزارش +بده (ذخیره نکن)» را بزنید؛ برنامه خودش چند منبع رایگان را امتحان می‌کند و می‌گوید کدام امروز +سالم است. با «بگرد، منبع سالم را ذخیره و فعال کن» خودش بهترین را فعال می‌کند. + +**ج) اتصال سرویس خریدنی (اگر روزی خریدید).** «قالب نشانی» را با نشانی سرویس پر کنید +(`{symbol}` و `{key}` جای نماد و کلید)، «مسیر JSON» را بگذارید، کلید را در کادر رمزمانند بنویسید، +بعد «آزمایش اتصال و خواندن قیمت زنده». اگر نمی‌دانید مسیر JSON کدام است، «کاوش پاسخ سرویس» را +بزنید: برنامه خودِ پاسخ را می‌خواند و فهرست عددها را نشان می‌دهد؛ روی عدد درست «استفاده» بزنید تا +مسیر خودش پر شود. بعد «ذخیره به‌عنوان پروفایل تازه» و اگر خواستید تیک «کلید را روی این رایانه ذخیره کن» +(اگر تیک نزنید، کلید روی دیسک نمی‌ماند و هر بار می‌پرسد). + +**د) جدول اعداد کارگزاری، همان شصت ثانیهٔ روزانه.** عددهای امروز را در جدول بنویسید یا از سامانهٔ +کارگزاری کپی کنید و در کادر چسباندن بریزید و «تشخیص خودکار و افزودن به جدول» را بزنید. بعد تیک +«این اعداد را خودم از سامانهٔ کارگزاری برداشتم»، اگر عددها به تومان است تیک «تومان»، یادداشت +اختیاری، و **«ذخیرهٔ اسنپ‌شات امروز»**. دو دکمهٔ راهنما همین‌جاست: «راهنما: هر روز چه عددی بگیرم؟» +و «نمایش قالب پرونده». («خواندن اعداد فعلی» اعداد آخرین اسنپ‌شات را برای ویرایش می‌آورد؛ «افزودن +ردیف» برای وقتی است که با موبایل عددها را از اپلیکیشن کارگزاری می‌خوانید و کپی کردن سخت است.) +**چه چیزی خوب است:** روزهای واقعی در کارنامه جدا از روزهای ساختگی شمرده می‌شوند و فقط روزِ +تیک‌خورده «واقعی» حساب می‌شود. + +### گام ۳. تنظیمات ریاضی و ریسک + +**چه کار می‌کند:** ده عددِ قاعدهٔ تصمیم‌گیری را نگه می‌دارد (سرمایه، نرخ سد، کف حاشیه، سقف +موقعیت، کف نقدشوندگی، سقف اسپرد و…). +**چه بزنید:** فقط **یک عدد** را عوض کنید: «نرخ سد سالانه» را از بازده مؤثر صندوق درآمد ثابت همان +روز بگذارید (شهریور ۱۴۰۵: حدود ۰٫۳۹ یعنی ۳۹ درصد). بقیه را دست نزنید تا تجربه پیدا کنید. +**چه چیزی خوب است:** دکمهٔ «بازخوانی پیش‌فرض‌ها» همیشه هست؛ اگر چیزی را خراب کردید، برگردید به +حالت اول. این عددها همان چیزی است که در بستهٔ شاهد شرکت هم چاپ می‌شود. + +### گام ۴. خبر و هشدار (اختیاری) + +**چه کار می‌کند:** هشدارهای کدال را کنار سیگنال‌ها می‌گذارد (افزایش سرمایه، تعدیل، توقف نماد). +**چه بزنید:** «اجرای دیده‌بان روی دادهٔ نمونه» تا ببینید چه شکلی است؛ «نمایش هشدارهای فعلی». +**چه چیزی خوب است:** این گام هیچ تأثیری روی عددهای ریاضی ندارد؛ فقط «دلیل» را کامل‌تر می‌کند. +اگر خالی باشد، محاسبه‌ها کار می‌کنند. + +### گام ۵. اجرا و محاسبه + +**چه کار می‌کند:** همان موتور ریاضی را روی دادهٔ امروز اجرا می‌کند. +**چه بزنید:** «شروع محاسبه». +**چه ببینید:** چند سیگنال ماند، چند افتاد، و برای هر کدام **دلیل رد** نوشته شده. «نمایش داشبورد» +خلاصه را برای چاپ باز می‌کند. + +### گام ۶. نتیجه و تصمیم + +**چه کار می‌کند:** سیگنال را به «بستهٔ سفارش» تبدیل می‌کند یا با دلیل رد می‌کند؛ اجرای واقعی +کارِ شما در سامانهٔ کارگزاری است. +**چه بزنید:** «به‌روزرسانی فهرست» → یک سیگنال را انتخاب کنید → یادداشت بنویسید → «تأیید سیگنال +انتخابی» یا «رد با دلیل» → «کپی در حافظه» برای بردن بستهٔ سفارش. پایین همین گام، «داوری سیگنال +ابزارهای دیگر» است: حرف خودتان یا ابزار دیگری («بازدهی که ابزار شما گفت»)، نرخ سد، وجه تضمین، +تعداد قرارداد، قیمت پایه → «داوری کن و برگه بساز». برنامه می‌گوید سیگنال آن ابزار **می‌ماند یا +می‌افتد** و فاصله تا ماخطار را نشان می‌دهد. «نمونهٔ آماده» برای وقتی است که می‌خواهید اول شکل کار +را ببینید. + +### گام ۷. پس‌آزمایی روی دادهٔ تاریخ + +**چه کار می‌کند:** همان موتور را روی گذشته اجرا می‌کند: نرخ برد، خطای مثبت کاذب، فرصت‌های ازدست‌رفته. +**چه بزنید:** «ساخت قالب ستون‌ها» → پروندهٔ تاریخ را در کادر بگذارید → «اجرای پس‌آزمایی» → «نمایش +گزارش». اگر پروندهٔ تاریخ ندارید، نمونه‌اش همراه برنامه است. +**چه چیزی خوب است:** نتیجهٔ واقعی هیچ نقشی در تصمیم امروز ندارد (آزمون ضد آینده‌نگری)، پس عدد +پس‌آزمایی را برای «توجیه» استفاده نکنید؛ برای «فهمیدن» استفاده کنید. + +### گام ۸. بستهٔ تحویل شرکت + +**چه کار می‌کند:** یک پوشه می‌سازد با همه‌چیز: داشبورد، فهرست سیگنال‌ها، سند روش کار، بسته‌های +سفارش، پس‌آزمایی، کارنامهٔ آزمون، برگهٔ آزمون، پروندهٔ سرمایه‌گذار، **سند چاپی اجازه‌نامه** و +**گواهی استفادهٔ موفق**، هر پرونده با اثر انگشت `sha256` و ساعت ساخت. +**چه بزنید:** «ساخت بستهٔ راستی‌آزمایی» → پوشه را بدهید. داخلش `README-FA.md` یک چک‌لیست +نه‌گامی دارد که خودشان در پنج دقیقه راستی‌آزمایی کنند. «نمایش سند روش کار» هم همان سند را در +مرورگر باز می‌کند. + +دو دکمهٔ دیگر همین‌جاست: نام شرکت را در کادر بنویسید و **«ساخت پیشنهاد یک‌صفحه‌ای»** را بزنید +(برگهٔ چاپی `data/offer-one-pager.html` و نسخهٔ متنی‌اش ساخته می‌شود؛ اگر مبلغی ندهید، جای قیمت +«توافقی» می‌ماند) و بعد **«نمایش پیشنهاد»** تا همان صفحه را ببینید و چاپ کنید. + +### گام ۹. آزمون زنده و دفتر سرمایه‌گذار + +**چه کار می‌کند:** سیگنال‌های امروز را در دفتر تاریخ‌دار زنجیره‌هش‌دار ثبت می‌کند و کارنامه +می‌سازد. +**چه بزنید:** اگر عجله دارید فقط «اجرای مراسم امروز»؛ اگر می‌خواهید خطای اجرا کمتر شود، «اجرای +مراسم با حاشیهٔ محافظه‌کارانه» (دو واحد سخت‌گیرتر). بعد «به‌روزرسانی جدول»، «بررسی زنجیرهٔ هش»، +«ساخت گزارش سرمایه‌گذار (HTML + CSV)» و در پایان «اجرای آزمون ۱۰ دقیقه‌ای» و «نمایش کارنامهٔ آزمون». +**چه چیزی خوب است:** کارنامه پنج شرط دارد و تا «آماده» نشود، خرید هیچ داده‌ای پیشنهاد نمی‌شود. +«برگهٔ آزمون چاپی» و «ساخت پروندهٔ سرمایه‌گذار» هم از همین‌جاست. + +### گام ۱۰. آزمون کور سرمایه‌گذار + +**چه کار می‌کند:** لپ‌تاپ را دست خودش می‌دهید؛ او حدس می‌زند، بعد برنامه پاسخ را با فرمول و +**روش دوم** رو می‌کند؛ در پایان برگهٔ امضادار و پیمان‌نامهٔ نمایش و سند «چه بخرم / کِی بفروشم / +کِی می‌افتد». +**چه بزنید:** «نمایش پرسش‌ها» → حدس‌ها را بنویسید → «داوری حدس‌های من» → «محاسبهٔ جدول» → +«حساب کن» (حساب‌رسی معاملهٔ گذشته با کارمزد واقعی) → «ساخت برگهٔ آزمون» و «ساخت پیمان‌نامهٔ نمایش +(دواِمضا)». «نمونهٔ پرشده» فقط برای دیدن شکل برگه است. + +### گام ۱۱. راهبردها، شوک‌آزمون و ریاضیِ پول + +**چه کار می‌کند:** جزوهٔ راهبردها با درصد هرکدام، شوک‌آزمون (لغزش، حرکت مخالف، کارمزد دو و سه +برابر، نرخ سد سخت‌تر)، و ریاضیِ بقا (کِلی، احتمال نیم‌شدن حساب، مسیر تا هدف). +**چه بزنید:** «ساخت جزوه + شوک‌آزمون» → «حساب کن» → «محاسبه کن». در کارت ریاضیِ پول، سرمایه و +هدف و نرخ برد و سود/زیان و بازده راهبرد و چرخش را می‌توانید عوض کنید و «محاسبه کن». +**چه چیزی خوب است:** هر کارت «نسخهٔ متنی» و «برگه» دارد؛ برگه‌ای که مدیر ریسک می‌پسندد، همان +نسخهٔ چاپی است، نه حرف شما. + +--- + +## ۳. گرفتن اعداد از کارگزاری — دقیقاً کجا و چطور + +این همان قسمتی است که همه گیر می‌کنند. مسیر واقعی این است: + +**۱. ورود.** به سامانهٔ معاملات آنلاین کارگزاری خودتان وارد شوید (یا اپلیکیشن موبایل کارگزاری). +برنامه به سامانهٔ شما وارد نمی‌شود و رمز شما را نمی‌خواهد؛ این کار دستِ خودتان است. + +**۲. تابلوی نماد.** در «مشاهدهٔ بازار» یا «تابلو» نماد را باز کنید: برای سهم، فولاد/خساپا/شپنا؛ +برای طلا، صندوق‌های طلا یا قراردادهای آتی و اختیار طلا. در وب‌سایت `tsetmc.com` هم همین‌ها را +می‌بینید: «مشاهدهٔ زنده» → نماد → تب‌های «آتی» و «اختیار معامله». + +**۳. ده عددی که لازم دارید و جای هرکدام:** + +| عدد | در تابلوی کارگزاری کجاست | +| --- | --- | +| قیمت پایه (`spot` / `stock_price`) | ستون «قیمت پایانی» یا «آخرین قیمت» خودِ نماد | +| قیمت آتی (`future`) | تب «آتی» همان نماد، ستون آخرین قیمت | +| قیمت اعمال (`strike`) | تابلوی اختیار معامله، ستون «قیمت اعمال» | +| پرمیوم اختیار خرید (`premium`) | همان تابلو، ستون «آخرین قیمت» سطر اختیار **خرید** | +| پرمیوم اختیار فروش (`put_price`) | همان تابلو، ستون «آخرین قیمت» سطر اختیار **فروش** | +| روزهای مانده (`days`) | تاریخ سررسید همان قرارداد منهای امروز | +| وجه تضمین هر قرارداد (`margin_per_contract`) | **فقط از کارگزاری**: اطلاعیهٔ وجه تضمین یا ستونش در سامانه | +| نقدشوندگی روز (`liquidity_contracts_per_day`) | ستون «حجم» همان قرارداد | +| اسپرد (`spread_pct`) | اختلاف قیمت خرید و فروش تقسیم بر میانگین‌شان؛ تقریبی کافی است | +| نماد و راهبرد (`symbol` / `kind`) | خودتان: «فولاد» و اینکه چه نوع معامله‌ای است | + +**۴. کپی، نه تایپ.** سطرها را در سامانه انتخاب کنید و `Ctrl+C`؛ در برنامه در کادر چسباندن +`Ctrl+V` و «تشخیص خودکار و افزودن به جدول». یک نمونهٔ واقعی از چیزی که می‌شود چسباند: + +``` +فولاد پوشش‌داده‌شده ۷۰۰۰ ۷۵۰۰ ۴۵۰ ۳۰ ۲,۰۰۰,۰۰۰ ۱۵۰ ۰٫۰۰۵ +``` + +برنامه خودش رقم‌های فارسی را به لاتین برمی‌گرداند، جداکننده‌ها را می‌فهمد، از روی کلمهٔ «پوشش‌داده‌شده» +راهبرد را می‌فهمد، و اگر جدول شما سرستون داشته باشد («قیمت پایه، اعمال، پرمیوم، روز») عددها را +بر پایهٔ همان سرستون‌ها می‌چیند. + +**۵. اگر روی موبایل هستید.** انتخاب و کپی جدول در اپلیکیشن سخت است؛ عددها را بخوانید و در گام ۲ +با «افزودن ردیف» بنویسید. برای کم‌کردن خطای تایپ، همیشه از همان روزهای اول سطرها را در جدول +بگذارید و یک بار بلند بخوانید و چک کنید؛ برنامه هم خودش بازبینی عقلی می‌کند (بخش ۵). + +--- + +## ۴. نقشهٔ صادقانهٔ اتوماسیون: چه چیزی خودکار است، چه چیزی نه + +| کار | امروز | چرا | کارِ شما | +| --- | --- | --- | --- | +| قیمت دلار، طلا، سکه | **خودکار** (رایگان، آزمون‌شده) | منبع عمومی بدون کلید، مسیر `data.0.3` | فقط نام شاخص را در ردیف بنویسید: `price_dollar_rl` · `geram18` · `sekeb` · `nim` · `rob` | +| قیمت پایانی سهام و آپشن | نیمه‌خودکار | منبع رایگان `tsetmc` هست ولی از بیرون ایران همیشه پاسخ نمی‌دهد | اگر سالم بود خودکار؛ اگر نه، از تابلو کپی کنید | +| نرخ لحظه‌ای صرافی | خودکار وقتی سرویس باز است | سرویس رایگان ولی گاهی ۵۰۳ می‌دهد | پروفایل فعال را نگه دارید؛ اگر قطع شد چسباندن | +| قیمت آتی و زنجیرهٔ آپشن | **دستی** | هیچ منبع رایگانِ پایدار برای زنجیرهٔ آپشن و آتی وجود ندارد | کپی از تابلو یا اپلیکیشن | +| وجه تضمین هر قرارداد | **دستی، فقط از کارگزاری** | هیچ سایت عمومی این عدد را دقیق نمی‌دهد و کارگزاری هم API نمی‌دهد | از اطلاعیهٔ وجه تضمین بگیرید؛ این عدد را جایی حدس نزنید | +| نقدشوندگی و اسپرد | دستی (تقریبی کافی است) | ستون حجم تابلوی امروز | کپی | +| تشخیص راهبرد و جاکردن عددها | **خودکار** | `snapshot_import` سرستون‌ها و کلمه‌ها را می‌شناسد | فقط بچسبانید و بعد یک نگاه تأییدی بیندازید | +| محاسبه، دروازه‌ها، بستهٔ سفارش | **خودکار** | موتور ریاضی و دو روش حساب | تصمیم را خودتان می‌گیرید | +| پس‌آزمایی، دفتر، کارنامه، بستهٔ شاهد، گواهی | **خودکار** | یک دکمه؛ هر پرونده با اثر انگشت | تشویق نمی‌خواهد؛ فقط دکمه‌ها را بزنید | +| اخبار و هشدارهای کدال | نیمه‌خودکار | دسترسی خودکار کدال امروز بسته است | با دادهٔ نمونه کار کنید یا هشدار را دستی وارد کنید | +| تصمیم معامله | **هرگز خودکار** | مسئولیت حقوقی و اخلاقی با انسان است | خودتان تأیید یا رد می‌کنید | +| ارسال سفارش به کارگزاری | **هرگز، و کدی هم برایش نوشته نشده** | طبق ابلاغیهٔ مهر ۱۳۹۹ معاملات الگوریتمی خودکار در بورس ایران «تا اطلاع ثانوی» مجاز نیست | اجرا در سامانهٔ کارگزاری، دستِ خودتان | + +**پاسخ صادقانه به «نمی‌شود همه‌اش خودکار شود؟»** آنچه خودکارشدنی بود، خودکار شده: قیمت‌های +رایگان، همهٔ محاسبه‌ها، پرونده‌سازی، و پاک‌سازی عددهای چسبانده‌شده. آنچه خودکار نمی‌شود، به تنبلی +ما نیست: **کارگزاری‌ها API نمی‌دهند** (سه مسیر خرید در سند ۰۵ بررسی شده)، **زنجیرهٔ آپشن منبع +رایگان پایدار ندارد**، و **وجه تضمین فقط در سامانهٔ کارگزاری است**. پس راه درست، کم‌کردن خطای +انسان است نه حذف انسان: چسباندن به‌جای تایپ، تبدیل خودکار رقم و واحد، و بازبینی عقلی. + +--- + +## ۵. نُه ترمز ضد خطای انسانی که همین حالا در برنامه هست + +۱. **رقم‌های فارسی و عربی** خودشان لاتین می‌شوند؛ لازم نیست دستی عوض کنید. +۲. **جداکننده‌ها و واحدها:** برنامه `۲۰٬۰۰۰ ریال` و `20,000` و `1.5` را یکسان می‌خواند؛ با تیک +۲. **جداکننده‌ها و واحدها:** برنامه `۲۰٬۰۰۰ ریال` و `20,000` و `1.5` را یکسان می‌خواند؛ تیک «تومان» عددها را یک‌بار به ریال برمی‌گرداند و خطای رایج «تومان با ریال قاطی شده» همان‌جا گرفته می‌شود. + + می‌شود. +۳. **تشخیص راهبرد از خودِ متن**: کلمه‌هایی مثل «کری»، «پوشش‌داده‌شده»، «تبعی»، «باکس»، «تساوی» + خودشان راهبرد را می‌گویند. +۴. **تشخیص از تعداد عددها** وقتی کلمه‌ای ننوشته‌اید؛ و اگر دو راهبرد با آن عددها بخواند، صریح + می‌گوید **دوپهلو** است تا خودتان انتخاب کنید. +۵. **گفتن تعارض**: اگر «سرستون‌ها» یک خوانش بدهند و «ترتیب معمولی» خوانش دیگری، برنامه هر دو را + می‌گوید (نه اینکه یکی را ساکت انتخاب کند). +۶. **بازبینی عقلی**: عددهایی که از نظر اقتصادی محال‌اند بی‌صدا رد نمی‌شوند؛ مثلاً در + پوشش‌داده‌شده اعمال باید بالاتر از قیمت پایه باشد، و در تبعی اعمال از قیمت سهم پایین‌تر. +۷. **گیر افتادن واحد در مارجین**: اگر وجه تضمین را تومان و ارزش قرارداد را ریال بدهید، برنامه عدد + نامعقول چاپ نمی‌کند؛ می‌گوید «احتمالاً دو واحد قاطی شده» و راه درست را می‌گوید. +۸. **دو روش حساب روی هر عدد کلیدی**: هر جا موتور عددی می‌دهد، فرمول و روش دستی مستقل هم چاپ + می‌شود تا اختلاف صفر باشد. `selftest.py` ۱۵ سنجه را همین‌طور دو بار می‌سنجد. +۹. **زنجیرهٔ هش و اثر انگشت**: دفترها و پرونده‌ها اثر انگشت دارند؛ اگر ردیفی بعد از ثبت عوض شود، + در بازبینی «شکسته» دیده می‌شود. برچسب «ساختگی/واقعی» و نوار تازگی هم نمی‌گذارد روز ساختگی را + جای روز واقعی جا بزنید. + +--- + +## ۶. چیزهایی که هرگز خودکار نمی‌شوند (و این به نفع شماست) + +- **سفارش‌گذاری**: کدش هم وجود ندارد؛ نه به‌خاطر تنبلی، به‌خاطر قانون. +- **تصمیم**: عدد و دلیل را برنامه می‌دهد، تصمیم را شما. +- **رمز سامانهٔ کارگزاری**: هیچ‌وقت وارد نکنید؛ برنامه هیچ‌جا از شما نمی‌خواهد. +- **حدس عددی**: جای عدد نامعلوم (مثل وجه تضمین) عدد حدسی نگذارید. عدد حدسی، دلیلِ ساختگی + می‌سازد و آن روز هم ساختگی شمرده می‌شود. + +اگر روزی کسی به شما گفت برنامه‌اش «خودش می‌خرد و می‌فروشد» و «سود تضمینی» دارد، دو احتمال دارد: +یا بیرون از قانون کار می‌کند، یا دارد اغراق می‌کند. شما لازم نیست هیچ‌کدام باشید. + +--- + +## ۷. تمرین ده دقیقه‌ای: اولین روز کامل + +۱. `run-gui.bat` (یا `python3 web_server.py --port 8765`) → مرورگر. +۲. گام ۱: پنل مدیریت را باز کنید، وارد شوید، «بررسی سلامت برنامه» (باید ۸ از ۸ سالم باشد). +۳. گام ۲: «ساخت قالب نمونه» و «آزمایش خواندن این پرونده» تا مطمئن شوید برنامه داده می‌خواند. +۴. گام ۲: یک پروفایل رایگان را «آزمایش اتصال» و اگر سبز بود «ذخیره و فعال کردن». +۵. گام ۲: سطر واقعی امروز را از سامانهٔ کارگزاری بچسبانید، تیک تأیید را بزنید، «ذخیرهٔ اسنپ‌شات + امروز». +۶. گام ۳: نرخ سد را از صندوق درآمد ثابت بگذارید و «ذخیرهٔ تنظیمات». +۷. گام ۵: «شروع محاسبه». +۸. گام ۶: یک سیگنال را تأیید یا با دلیل رد کنید. +۹. گام ۹: «اجرای مراسم امروز» → «به‌روزرسانی جدول» → «بررسی زنجیرهٔ هش» (باید سالم باشد). +۱۰. گام ۸: «ساخت بستهٔ راستی‌آزمایی» و پوشهٔ ساخته‌شده را باز کنید؛ داخلش `README-FA.md` را بخوانید. + +از فردا فقط بند ۵ (شصت ثانیه) و بند ۹ تکرار می‌شود. + +--- + +## ۸. اگر جایی گیر کردید: علامت، معنا، کارِ شما + +| پیامی که می‌بینید | معنا | کارِ شما | +| --- | --- | --- | +| «پاسخی نیامد (دریافت ناموفق ۵۰۳…)» | آن سرویس عمومی امروز پایین است | پروفایل دیگر را بیازمایید، یا سطر را دستی بچسبانید | +| «هیچ ردیفی برای محاسبه نیست» | جدول اعداد خالی است | دکمهٔ «ساخت قالب نمونه» یا چسباندن اعداد امروز | +| «عدد نامعقول… دو واحد قاطی شده» | تومان و ریال قاطی شده | تیک «تومان» را بزنید یا ریال بنویسید | +| «دوپهلو: … می‌تواند باشد» | راهبرد از عددها یکتا درنمی‌آید | نام راهبرد را در سطر بنویسید | +| «اثر انگشت زنجیرهٔ دفتر: شکسته» | فایلی بعد از ثبت عوض شده | پرونده را بازنگرید؛ برای جلسه از نسخهٔ سالم استفاده کنید | +| «۴۰۳ … از /admin وارد شوید» | این بخش فقط در پنل مدیریت باز می‌شود | وارد پنل شوید (توکن یک‌ساعته است) | +| «شناسه یا رمز درست نیست. n تلاش تا قفل» | رمز اشتباه | رمز را با `adminauth.py --set-pass` عوض کنید | + +--- + +هر بخشی از این سند را که در جلسه لازم دارید، همان‌جا نشان بدهید؛ لازم نیست از حافظه چیزی +بگویید. برنامه هر عدد را روی صفحه می‌آورد و شما فقط باید بدانید کدام دکمه، کدام گام است. + +✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · 📱 [989126630554](tel:+989126630554) · ✈️ [Telegram: Mojarabian](https://t.me/Mojarabian) · 📸 [Instagram: Mojarabian.Art](https://instagram.com/Mojarabian.Art) diff --git a/station/docs/14-first-meeting-fa.md b/station/docs/14-first-meeting-fa.md new file mode 100644 index 0000000000000000000000000000000000000000..766a1a72ea68ad19363f3e10225ad401764d75ad --- /dev/null +++ b/station/docs/14-first-meeting-fa.md @@ -0,0 +1,132 @@ +# از صفر تا اولین جلسه (و اولین پول) — نسخهٔ ۰٫۱٫۰ · ۲۲ سپتامبر ۲۰۲۶ + +این سند دربارهٔ ساختن نیست؛ دربارهٔ **گرفتن جلسه** است. برنامه ساخته شده، بستهٔ تحویل آماده است، +برگهٔ پیشنهاد چاپ می‌شود. آن‌چه بین تو و اولین پول ایستاده، فقط یک چیز است: نیم‌ساعت وقت با کسی +که این عددها برایش مسئله است. + +> **قاعدهٔ سند:** من هیچ عدد بازدهی نمی‌دهم و هیچ وعده‌ای نمی‌دهم؛ چون تجربهٔ آماری‌اش را ندارم و +> هر عددی که بسازم، دروغ است. تنها چیزی که می‌شود شمرد، **کارِ انجام‌شده** است: چند پیام، چند +> تماس، چند جلسه. پس هر هفته فقط این سه عدد را برای خودت یادداشت کن. + +--- + +## ۱. مسیر، در شش دروازه + +| دروازه | چه چیزی لازم است | نشانهٔ عبور | +| --- | --- | --- | +| ۱. دیده‌شدن | یک پیام کوتاه یا یک تماس کوتاه | «جواب داد» | +| ۲. جلسه | نیم‌ساعت، روی لپ‌تاپ خودشان | «نشست و دکمه زد» | +| ۳. آزمون بی‌پول | دو هفته استفاده با دادهٔ خودشان | کارنامهٔ «آماده» یا چند روز واقعی ثبت‌شده | +| ۴. توافق | اجازه‌نامهٔ نام‌دار و زمان‌دار + سند چاپی | امضای دو طرف | +| ۵. تحویل | بستهٔ شاهد، سند مجوز، گواهی استفاده | پوشه در دستشان | +| ۶. تکرار | گزارش ماهانه و پلهٔ سوم | قرارداد ماه بعد | + +دروازهٔ اول، سخت‌ترین است: نه چون سخت است، چون **ناخوشایند** است. بقیهٔ دروازه‌ها را یک برنامه +انجام می‌دهد؛ این یکی را آدم. + +## ۲. چرا «دموی نیم‌ساعته» تنها چیزی است که می‌فروشد + +در این بازار، آدم‌ها از دو چیز خسته‌اند: سیگنالِ بی‌دلیل، و وعدهٔ سود. پس هر چیزی که شبیه این دو +باشد، در سه ثانیه رد می‌شود. چیزی که رد نمی‌شود، یک لحظهٔ مشخص است: **وقتی خودشان یک سیگنال واقعی +خودشان را روی صفحه می‌بینند و برنامه در چند ثانیه می‌گوید می‌مانَد یا می‌افتد، با کارمزد و فاصله تا +اخطاریهٔ مارجین.** + +پس هدف پیام اول فقط یک چیز است: نیم‌ساعت. نه معرفی شرکت، نه توضیح فنی، نه فرستادن پرونده. +پیام‌های آماده‌اش را بستهٔ `outreach.py` می‌سازد (چهار متن + اسکریپت تماس + پاسخ چهار مخالفت): + +```bash +cd MATERIALS/money/gui +python3 outreach.py --client "نام مخاطب" --kind brokerage # لحن کارگزاری +python3 outreach.py --client "آقای رضایی" --kind known # لحن آشنای بازار +python3 outreach.py --checklist # آماده‌سازی پیش از پیام اول +``` + +## ۳. کانال‌ها، با هزینهٔ صادقانه + +| کانال | هزینه | چقدر جواب می‌دهد | نکتهٔ کاری | +| --- | --- | --- | --- | +| کارگزاری و تأمین سرمایه (آموزش یا مدیریت ریسک) | صفر | کم‌تعداد ولی جدی | پیام کوتاه به واحد آموزش، نه به مدیرعامل | +| شرکت‌های غیرمالی با ریسک قیمت (تولیدی، بازرگانی، طلا و جواهر) | صفر | متوسط | این‌ها «سیگنال» نمی‌خواهند؛ «حساب قیمت» می‌خواهند | +| مدرس‌ها و تحلیلگرهای بازار | صفر | متوسط | یک نیم‌ساعت با آن‌ها، هم تمرین ارائه است هم مسیر معرفی | +| آشنایانی که خودشان معامله می‌کنند | صفر | بیشترین | صادق‌ترین آزمون؛ اگر بی‌علاقه بودند، اول متن را عوض کن | +| دانشگاه و انجمن علمی مالی | صفر | کم ولی بی‌ریسک | تمرین ارائه جلوی آدم فنی | +| شبکه‌های اجتماعی خودت (اینستاگرام، لینکدین) | صفر | کند ولی انبار شونده | متن پیام کوتاه را همان‌جا بگذار؛ پیام مستقیم نده | +| خرید آگهی یا لیست شماره | پول و ریسک | **توصیه نمی‌کنم** | در این بازار، اسپم یعنی سوختن نام | + +## ۴. ریتم هفتگی (کم ولی منظم) + +| روز | کار | +| --- | --- | +| شنبه | انتخاب ۵ مخاطب و نوشتن نامشان (نه بیشتر؛ کیفیت مهم‌تر از تعداد است) | +| یک‌شنبه | فرستادن پیام ۱ برای همان ۵ نفر | +| دوشنبه تا چهارشنبه | جواب دادن، و یکی‌دو تماس کوتاه برای جدی‌ترین‌ها | +| پنجشنبه | پیگیری روز ۳ برای بی‌جواب‌ها + ثبت سه عدد هفته (چند پیام، چند تماس، چند جلسه) | + +هفتهٔ بعد، همان پنج پیام برای پنج مخاطب تازه. پیگیری روز ۱۰ هم همان‌جا انجام می‌شود؛ بعد از آن، +پروندهٔ آن مخاطب را ببند. **این ریتم را می‌شود بی‌پایان ادامه داد، چون به شانس وابسته نیست.** + +## ۵. پنج قاعده‌ای که نمی‌شکنیم + +۱. **هیچ عدد سودی در هیچ پیامی نیست.** نه وعده، نه پیش‌بینی، نه «فلان‌قدر در فلان‌ماه». +۲. **پیام اول هیچ پیوستی ندارد.** پیوست در پیام اول، آدم را فروشنده نشان می‌دهد. +۳. **پیگیری سه بار: روز ۰، ۳، ۱۰.** بعد رهایش کن. سوزاندن آدم بدتر از نگرفتن جلسه است. +۴. **هر پیام با یک سؤال تمام می‌شود، نه با یک ادعا.** سؤال، جواب می‌آورد؛ ادعا، سکوت. +۵. **کد و بستهٔ تحویل، پیش از توافق دست کسی نمی‌رود.** آن‌چه در جلسه نشان می‌دهی، «عملِ برنامه» + است نه فایل‌ها. راستی‌آزمایی هم‌جا انجام می‌شود: دو فرمان روی لپ‌تاپ خودشان. + +## ۶. پیش از اولین پیام، شش چیز را آماده کن + +۱. شمارهٔ تماس و پیام‌رسان در دسترس (و در امضا). ۲. برگهٔ پیشنهاد چاپ‌شده در کیف. ۳. یک سیگنال +واقعی نمونه با تاریخ همان روز. ۴. پوشهٔ بستهٔ تحویل روی لپ‌تاپ یا فلش. ۵. تمرین دو دقیقه‌ای جملهٔ +تمایز: «سیگنال خودتان را داوری می‌کنم: می‌مانَد یا می‌افتد». ۶. پاسخ چهار مخالفت (همان بستهٔ +پیام‌ها). فرمان `python3 outreach.py --checklist` همین فهرست را با دلیل هرکدام می‌چاپ می‌کند. + +## ۷. جلسهٔ نیم‌ساعته، با ساعت + +| دقیقه | کار | چه می‌گویی | +| --- | --- | --- | +| ۰ تا ۲ | لپ‌تاپ را باز کن، گام ۱، پنل مدیریت، بررسی سلامت | «هشت جز را چک می‌کند؛ اگر همه سالم بود، نصب درست است» | +| ۲ تا ۵ | سیگنال خودش را بگیر و در گام ۶ در کارت «داوری سیگنال» بگذار | «عددهای خودتان را می‌زنیم، نه عددهای من» | +| ۵ تا ۱۰ | نتیجه: می‌مانَد یا می‌افتد، با دلیل دروازه‌ها و فاصله تا ماخطار | «حالا بگویید این را پیش از سفارش داشتن، چه چیزی عوض می‌کرد» | +| ۱۰ تا ۱۴ | حساب‌رسی یک معاملهٔ گذشتهٔ خودش (گام ۱۰) | «کارمزد واقعی کم می‌شود؛ ببینید چه می‌مانَد» | +| ۱۴ تا ۱۸ | پس‌آزمایی و شوک‌آزمون (گام‌های ۷ و ۱۱) | «با کارمزد دو برابر و حرکت مخالف، چه چیزی زنده می‌مانَد» | +| ۱۸ تا ۲۲ | لپ‌تاپ را بده دست خودش؛ پرسش‌های آزمون کور | «شما حدس بزنید، بعد برنامه با فرمول نشان می‌دهد» | +| ۲۲ تا ۲۶ | بستهٔ شاهد (گام ۸) و برگهٔ پیشنهاد | «این پوشه و این یک صفحه، مال شماست» | +| ۲۶ تا ۳۰ | سه سؤال تو: چه چیزی ارزش دارد؟ چه چیزی کم است؟ قدم بعدی چه باشد؟ | «اگر صلاح می‌دانید، دو هفته با دادهٔ خودتان امتحان کنیم» | + +## ۸. بعد از جلسه: دو پیام، نه بیشتر + +**۲۴ ساعت بعد:** «ممنون از وقتی که گذاشتید. پوشهٔ شاهد و برگهٔ پیشنهاد را همان‌جا گذاشتم. اگر +سؤالی پیش آمد، همین‌جا بنویسید.» (بدون فروش، بدون یادآوری مهلت.) + +**۱۰ روز بعد:** «سلام؛ اگر دوست داشتید، دو هفته با دادهٔ خودتان امتحان کنیم و بعد خودتان بگویید. +اگر هم موضوع تمام شده، همان یک جمله را بنویسید که چه چیزی کم بود؛ برای من ارزش دارد.» + +اگر گفت نه، همین یک سؤال را بپرس: **«چه چیزی را باید ببینید تا نظرتان عوض شود؟»** جوابش، +دستور کار نسخهٔ بعدی برنامه است. + +## ۹. سه اشتباهی که جلسهٔ بعدی را می‌سوزاند + +۱. **توضیح فنی زیاد.** ابزار را نشان بده، معماری را توضیح نده. (تو خودت گفته‌ای برنامه‌نویس + ساده‌ای؛ همین را بگو و بگذر.) +۲. **حرف از سود.** همان لحظه، در ذهن طرف مقابل می‌شوی «یکی از آن‌ها». عدد و دلیل بده، نه نتیجهٔ + حساب‌نشده. +۳. **تحویل فایل پیش از توافق.** اگر فایل بدهی، هم راستی‌آزمایی معنایش را از دست می‌دهد و هم + اجازه‌نامهٔ نام‌دار بی‌معنا می‌شود. + +## ۱۰. اگر یک هفته هیچ جوابی نیامد + +سه چیز را عوض کن، به همین ترتیب: **پیام** (کوتاه‌تر، سؤالی‌تر)، **مخاطب** (از آشنایان بازار شروع +کن، نه از شرکت‌های بزرگ)، **لحظهٔ تماس** (آخر وقت اداری بدترین زمان است). اگر بعد از سه دور +تغییر باز هم هیچ‌کس جواب نداد، مشکل پیام نیست؛ مشکل انتخاب مخاطب است: سراغ کسانی برو که **هر روز** +با تصمیم قیمتی سر و کار دارند، نه کسانی که به‌عنوان سرگرمی معامله می‌کنند. + +## ۱۱. آنچه ادعا نمی‌کنم + +- هیچ عدد جلسه و هیچ عدد درآمدی در این سند نیست؛ آن‌ها به بازار و به تو بستگی دارند، نه به متن. +- هیچ‌کدام از این پیام‌ها به‌تنهایی مشتری نمی‌سازد؛ کار واقعی، «نیم‌ساعت نشستن» است. +- برنامه، خودش تقاضا نمی‌سازد. تقاضا از دیدنِ همان یک لحظه روی صفحه می‌آید. +- و یک چیز را قطعی می‌دانم: اگر این ریتم را چهار هفته نگه داری، دست‌کم چند جلسه خواهی داشت. + بقیهٔ مسیر، دیگر به شانس وابسته نیست. + +✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · 📱 [989126630554](tel:+989126630554) · ✈️ [Telegram: Mojarabian](https://t.me/Mojarabian) · 📸 [Instagram: Mojarabian.Art](https://instagram.com/Mojarabian.Art) diff --git a/station/docs/15-after-meeting-fa.md b/station/docs/15-after-meeting-fa.md new file mode 100644 index 0000000000000000000000000000000000000000..3fc6e05503743f2b3b41ab912d5c75b93b65d087 --- /dev/null +++ b/station/docs/15-after-meeting-fa.md @@ -0,0 +1,103 @@ +# بعد از جلسه: سه دروازه، و آنچه در دو هفتهٔ اول می‌گذرد + +این سند ادامهٔ `14-first-meeting-fa.md` است. آن سند تا لحظهٔ نشستن سر میز را می‌گفت؛ این سند از +لحظهٔ بلند شدن از میز شروع می‌شود، یعنی جایی که بیشترِ کارهای تازه شکست می‌خورند: نه در جلسه، +بلکه در روزهای بعدش. + +جلسه سه جور تمام می‌شود: **بله** · **بعداً** · **نه**. هر سه محترم است و برای هر سه کار روشنی +داریم. هیچ‌کدامشان «تلاش دوباره برای گرفتن تأیید» نیست. + +## دروازهٔ یک: «بله» + +اگر گفتند بله، فردا صبح پنج کار به همین ترتیب: + +| # | کار | کجا | چرا | +| --- | --- | --- | --- | +| ۱ | اجازه‌نامهٔ آزمون دو هفته‌ای، نام‌دار | `python3 license.py --grant "نام مشتری" --trial --save` و بعد `python3 license.py --document` | تا پایان آزمون هیچ تعهد ماهانه‌ای گرفته نمی‌شود؛ سندش امضاشده و روزشمار است | +| ۲ | نصب روی رایانهٔ خودشان | بستهٔ تحویل، `START-HERE-FA.md` | همه‌چیز محلی است؛ هیچ رمزی از سامانهٔ کارگزاری پرسیده نمی‌شود | +| ۳ | اتصال دادهٔ رایگان | گام ۲، «امتحان منابع رایگان» | صفر خرید؛ خرید داده فقط بعد از کارنامهٔ آماده معنی دارد | +| ۴ | اعداد امروز از کارگزاری خودشان | گام ۲، جدول اسنپ‌شات یا چسباندن از سامانه | موتور با عدد آن‌ها کار می‌کند، نه با نمونهٔ ما | +| ۵ | مراسم امروز و راستی‌آزمایی به دست خودشان | گام ۹ و بعد `python3 selftest.py` | ادعا را از دهان ما نمی‌شنوند؛ خودشان اجرا می‌کنند | + +برگهٔ چاپی همین پنج کار، با نام مشتری و تاریخ‌ها، از خود برنامه درمی‌آید: **«برگهٔ روز اول +مشتری»** (گام ۸ → «ساخت برگهٔ روز اول مشتری»). همان برگه را روز اول امضا می‌کنید و نسخهٔ +خودشان را نگه می‌دارند. + +### در این دو هفته چه چیزی فروخته نمی‌شود + +- هیچ دادهٔ خریدنی. +- هیچ سفارشی (کد ما به کارگزاری وصل نمی‌شود؛ ابلاغیهٔ مهر ۱۳۹۹). +- هیچ سرمایه‌ای از طرف آن‌ها درگیر نمی‌شود. +- هیچ پرداخت ماهانه‌ای؛ فقط پلهٔ راه‌اندازی و آموزش. + +این «نه گفتن» به پولِ زودتر، همان چیزی است که دو هفته بعد اجازه می‌دهد با پرونده حرف بزنید، نه +با وعده. اگر همان روز اول اشتراک ماهانه بگیرید، روز دهم باید از عددی دفاع کنید که هنوز ساخته +نشده است. + +### روز بازبینی و شرط‌هایش + +پایان آزمون، همان **روز بازبینی** است (تاریخ آزمون از خود برنامه خوانده می‌شود، نه از حافظهٔ +من). آن روز یک نشست کوتاه با یک نگاه به کارنامه: + +| شرط | عدد لازم | +| --- | --- | +| تداوم روزانه | ده روز ثبت‌شده | +| روزهای با دادهٔ واقعی | پنج روز واقعی (نه ساختگی) | +| بازسنجی دفتر | دست‌کم شصت درصد ردیف‌ها | +| حرکت واقعی در دفتر | سه حرکت معنادار (دست‌کم یکی بازتر، یکی بسته) | +| زنجیرهٔ هش دفتر | سالم، بدون ردیف دست‌کاری‌شده | + +اگر هر پنج شرط سبز بود، پلهٔ دوم (اجازه‌نامهٔ نام‌دار + پشتیبانی) معنی دارد. اگر نبود، بازبینی +عقب می‌افتد و همان دو هفته بررسی می‌شود. **هیچ‌وقت شرط را جابه‌جا نمی‌کنیم تا پرداخت زودتر +بگیریم**؛ اگر عدد آماده نیست، همان را می‌گوییم. + +### همان شب، دو پیام کوتاه + +۱. برای مسئول پروژه: «امروز نصب شد، این پنج کار انجام شد، این دو کار مانده. روز بازبینی: …». +بدون تعریف از خودتان، بدون عدد درآمد. + +۲. برای خودتان در دفتر تابلو: تاریخ روز بازبینی و کاری که آن روز باید آماده باشد. اگر این را +ننویسید، روز بازبینی از دست می‌رود. + +## دروازهٔ دو: «بعداً» + +«بعداً» بی‌تاریخ یعنی «نه». پس **همان‌جا یک تاریخ بگیرید**: «باشد، سی روز دیگر، همان ساعت، یک +تماس کوتاه. اگر تا آن موقع بودجه‌تان آماده نشد، خودم یک پیام می‌فرستم و دیگر مزاحم نمی‌شوم.» + +بعد در تابلو ثبتش کنید: نتیجه «بعداً»، با تاریخ سر‌زدن. خود برنامه سی روز بعد همان روز این +مخاطب را روی «کار امروز» برمی‌گرداند تا فراموش نشود: یک پیام کوتاه در روز موعود، نه ده پیام در +سی روز. اگر آن روز هم «بعداً» گرفتید، این بار پرونده را ببندید و تا سه ماه به آن برنگردید. + +## دروازهٔ سه: «نه» + +«نه» داده است، نه شکست. سه کار: + +۱. تشکر بی‌کم‌وکاست، بدون یک جملهٔ اضافه برای عوض کردن نظرشان. +۲. همان یک سؤال: «چه چیزی را باید ببینید تا نظرتان عوض شود؟» و جوابش را همان‌جا بنویسید. +۳. ثبت در تابلو: نتیجه «نه»، و در یادداشت همان جملهٔ آن‌ها (با ماسک‌شده؛ دفتر ما جای شماره و +عدد نیست). + +اگر دو ماه بعد همان سؤال جواب گرفت، یک پیام کوتاه بفرستید و به سؤال خودشان جواب بدهید. این +تنها راه برگشتن است؛ فرستادن پیشنهاد تازه به کسی که «نه» گفته، درِ بسته را قفل می‌کند. + +## سه اشتباه که قرارداد را می‌سوزانند + +۱. **گرفتن پول ماهانه پیش از کارنامهٔ آماده.** عددی که پشتش نیست، دیر یا زود باید پس داده شود، +و این بار با آبرو پس داده می‌شود. +۲. **وعدهٔ سود یا عدد درآمد.** نه در پیام، نه در جلسه، نه در قرارداد. حتی یک مثال فرضی هم +شکل وعده به خودش می‌گیرد. جای این حرف، عدد و دلیل است. +۳. **واگذاری نسخهٔ برنامه یا کلید پنل** برای اینکه کار زودتر پیش برود. دسترسی، نام‌دار و +زمان‌دار است؛ مالکیت کد نزد شما می‌ماند و دسترسی آن‌ها روزشمار است. + +## آنچه در این سند ادعا نمی‌کنم + +- هیچ عدد درآمدی، هیچ نرخ تبدیل جلسه به قرارداد، و هیچ تضمینی برای گرفتن کار نیست. +- هیچ وعدهٔ سودی برای مشتری نیست؛ خروجی ایستگاه «عدد و دلیل» است و تصمیم، تصمیم آن‌ها است. +- هیچ‌کدام از این حرف‌ها جای مشاورهٔ حقوقی و مالیاتی را نمی‌گیرد؛ برای قرارداد رسمی، نظر + حسابدار و وکیل خودتان را بگیرید. + +## یک خط جمع‌بندی + +قرارداد با **شاهد** شروع می‌شود، نه با وعده: اول پرونده، بعد پول. + +✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · 📱 +989126630554 · ✈️ Telegram: Mojarabian · 📸 Instagram: Mojarabian.Art diff --git a/station/docs/16-review-meeting-fa.md b/station/docs/16-review-meeting-fa.md new file mode 100644 index 0000000000000000000000000000000000000000..e24a8d11656fa997ceadbcd36eed4fd6d1db2c2a --- /dev/null +++ b/station/docs/16-review-meeting-fa.md @@ -0,0 +1,125 @@ +# جلسهٔ بازبینی دو هفته‌ای: سه شاهد، دو خروجی، یک تصمیم + +این سند برای **روز چهاردهم** است؛ همان روزی که اجازه‌نامهٔ آزمون تمام می‌شود. تا این‌جا سه چیز ساخته +شده است: برگهٔ پیشنهاد پیش از جلسه، بستهٔ پیام‌ها برای گرفتن جلسه، و برگهٔ روز اول مشتری. آن‌چه +می‌مانَد یک تصمیم است. اگر این نشست برگزار نشود، پرونده‌های خوب هم بی‌صدا رها می‌شوند. + +برگهٔ این جلسه را خودِ برنامه می‌سازد: گام ۸ ← «ساخت برگهٔ جلسهٔ بازبینی». کافی است نام مشتری، +روز شروع و روز جلسه را بدهید. + +## بیست دقیقه، دقیقه‌به‌دقیقه + +| دقیقه | کار | +| --- | --- | +| ۰ تا ۳ | سه شاهد روی همان لپ‌تاپ اجرا می‌شود | +| ۳ تا ۸ | کارنامه خوانده می‌شود | +| ۸ تا ۱۲ | سه پرسش پایان | +| ۱۲ تا ۱۷ | انتخاب یکی از دو خروجی | +| ۱۷ تا ۲۰ | اگر تصمیم نگرفتند: ثبت تاریخ سر زدن | + +یک قاعدهٔ کوچک که همه‌چیز را عوض می‌کند: **فرمان را خودشان می‌زنند، شما دست به صفحه نمی‌زنید.** +عددی که خودشان روی صفحهٔ خودشان دیده‌اند، با عددی که شما نشانشان داده‌اید یکی نیست. + +## سه شاهد (و یک شاهد اختیاری) + +| شاهد | فرمان | چه چیزی را نشان می‌دهد | چه چیزی را نشان نمی‌دهد | +| --- | --- | --- | --- | +| کارنامهٔ دو هفته | `python3 daily_trial.py --status` | پنج شرط تداوم، دادهٔ واقعی، بازسنجی، حرکت، زنجیره | کدام تصمیم سود داد | +| دفتر استفادهٔ موفق | `python3 usage_meter.py --summary --verify` | چه کاری چند بار، با دو امضا و زنجیرهٔ سالم | درست‌بودن تصمیم‌ها | +| آزمون خودِ ایستگاه | `python3 selftest.py` | پانزده سنجه، هر کدام دو بار | آینده | +| بستهٔ راستی‌آزمایی (اختیاری) | گام ۸ ← «ساخت بستهٔ راستی‌آزمایی» | همان عددها با اثر انگشت `sha256` | هیچ عدد تازه‌ای | + +نوشتن ستون «نشان نمی‌دهد» در خودِ برگه، از این نترسیدن می‌آید که طرف مقابل بپرسد «خب که چه؟». +وقتی خودت مرز عددت را می‌گویی، حرف بعدی‌ات وزن دارد. + +## کارنامهٔ «آماده» یعنی چه + +«آماده» یعنی **همهٔ پنج شرط با هم**. عددها دست‌نویس نیستند: از خودِ کد خوانده می‌شوند. اگر در +آینده کسی شرط‌ها را عوض کند، برگه هم با همان عددها ساخته می‌شود. + +| شرط | عدد لازم | +| --- | --- | +| تداوم روزانه | ده روز ثبت‌شده | +| روزهای با دادهٔ واقعی | پنج روز واقعی، نه ساختگی | +| بازسنجی دفتر | دست‌کم شصت درصد ردیف‌ها | +| حرکت واقعی در دفتر | سه حرکت معنادار، دست‌کم یکی بازتر و یکی بسته | +| زنجیرهٔ هش دفتر | سالم | + +اگر یکی از شرط‌ها مانده باشد، تصمیم امروز **تمدید** است، نه پرداخت: یک بار، بی‌هزینه، چهارده روز +دیگر، با همان شرط‌ها. این قاعده را همان‌جا بگویید؛ کسی که می‌داند تحت فشار نیست، راحت‌تر تصمیم +می‌گیرد. + +## دو خروجی، بدون حالت سومی + +**خروجی یک: ادامه با پرداخت.** پلهٔ دوم از امروز شروع می‌شود و صورت‌کار همان دو هفته ضمیمه‌اش +است: کارنامه، دفتر استفاده و بستهٔ شاهد. قاعده یکی است: **پرداخت در برابر پروندهٔ همان پله**، نه +در برابر وعده. جملهٔ آماده: «هزینهٔ پلهٔ دوم از امروز شروع می‌شود؛ صورت‌کار این دو هفته هم ضمیمه +است و هر عددش را خودتان می‌توانید بازتولید کنید.» + +**خروجی دو: توقف.** سه کار همان شب: نتیجهٔ «نه» در تابلو ثبت شود؛ اجازه‌نامه سر تاریخ نام‌دار +خودش تمام می‌شود؛ پرونده‌ها و دفترها روی رایانهٔ خودشان می‌مانَد. جملهٔ آماده: «امروز کار تمام +است؛ اجازه‌نامه سر تاریخ خودش تمام می‌شود و چیزی بدهکار نیستید.» حالت سومی نداریم؛ نه «قرار +شد بعداً خبر بدهم» و نه «شاید ادامه بدهم». + +## چهار پرسش سختی که ممکن است بپرسند + +۱. **«چقدر سود می‌دهد؟»** جواب: سود را وعده نمی‌دهم. پنج عدد نشان می‌دهم: کارنامه، دفتر استفاده، +آزمون ایستگاه، بستهٔ شاهد و زنجیرهٔ سالم؛ تصمیم با خودتان است. هر کس به شما عدد سود بدهد، یک جای +حسابش خالی است. + +۲. **«خودم می‌توانم این عددها را دربیاورم؛ چرا پول بدهم؟»** جواب: عدد درآوردن یک چیز است، سرِ +وقت درآوردن و ماندن روی قاعده چیز دیگری است؛ کاری که در این دو هفته خریدید «ایستگاه + پرونده + +پشتیبانی» بود، نه پیش‌بینی. + +۳. **«تخفیف می‌دهی؟»** جواب: از پله‌ها کم می‌کنیم، نه از شاهد. اگر پول کم است، پلهٔ سوم را برای +بعد می‌گذاریم؛ اما آن‌چه تحویل داده می‌شود بی‌کم‌وکاست می‌مانَد. + +۴. **«اگر کارنامه آماده نشد چه؟»** جواب: تمدید بی‌هزینه، یک بار، با همان شرط‌های نوشته‌شده. + +## اگر همان روز تصمیم نگرفتند + +فشار نیاورید و پیام‌های پی‌درپی نفرستید. در تابلو «بعداً» را با یک تاریخ ثبت کنید؛ پیش‌فرض سی روز +بعد است. دو پیام کوتاه هم روی برگه نوشته شده: یکی روز سوم، یکی روز هفتم. بعد ساکت. همان قاعدهٔ +سه‌بارِ پیگیری، بدون پیام سوم. + +```bash +python3 prospects.py --outcome "نام مشتری" --result "بعداً" --next-on 2026-11-05 +``` + +## اگر «نه» گفتند + +- تشکر بی‌کم‌وکاست؛ این جلسه هم یک شاهد ساخته است. +- یک سؤال: «چه چیزی را باید می‌دیدید تا بگویید ارزش داشت؟» جواب همان سؤال، جلسهٔ بعدی را با + مخاطب بعدی بهتر می‌کند. +- در تابلو پرونده را با احترام ببندید؛ دلیلش را در یادداشت بنویسید. +- اگر بعد از سه ماه چیزی تازه داشتید، می‌توانید یک پیام بفرستید؛ نه بیشتر. + +## سه اشتباهی که قرارداد را می‌سوزاند + +۱. **فشار آوردن برای تصمیم همان جلسه.** تصمیم دیرهنگام بهتر از تصمیم کور است و مشتریِ تحت فشار، +دو هفتهٔ دیگر پشیمان می‌شود. + +۲. **نشان دادن سود فرضی.** یک عدد فرضی که با آن طرف مقابل ذوق کند، بعداً به یک گلایه تبدیل می‌شود +و پرونده‌های واقعی را هم بی‌اعتبار می‌کند. + +۳. **وعدهٔ تاریخ پول.** وعدهٔ پرداخت به آیندهٔ بازار داده نمی‌شود؛ به **تحویل** داده می‌شود. هر +پله، پروندهٔ خودش را دارد. + +## آنچه ادعا نمی‌کنم + +- هیچ سود تضمینی و هیچ پیش‌بینی قیمت در کار نیست؛ خروجی این ایستگاه «عدد و دلیل» است. +- هیچ سفارشی به کارگزاری فرستاده نمی‌شود و کدی هم برایش نوشته نشده (ابلاغیهٔ مهر ۱۳۹۹). +- هیچ درصدی از سود گرفته نمی‌شود؛ اگر کسی چنین چیزی پیشنهاد داد، همان‌جا رد کنید. +- عددهای کارنامه، عددهای ایستگاه است، نه عددهای بازار؛ بازده گذشته هم تضمین آینده نیست. + +## پیوست: فرمان‌های همین جلسه + +```bash +cd station +python3 daily_trial.py --status # کارنامهٔ دو هفته +python3 usage_meter.py --summary --verify # دفتر استفاده + سالم‌بودن زنجیره +python3 selftest.py # پانزده سنجه، هر کدام دو بار +python3 review_meeting.py --client "نام مشتری" --start 2026-09-22 --on 2026-10-06 +``` + +یک خط جمع‌بندی برای خودت: **قرارداد با شاهد بسته می‌شود، نه با وعده.** diff --git a/station/docs/17-remote-access-fa.md b/station/docs/17-remote-access-fa.md new file mode 100644 index 0000000000000000000000000000000000000000..8c5f989e7976b281cde99ddeadcb07d3b011d773 --- /dev/null +++ b/station/docs/17-remote-access-fa.md @@ -0,0 +1,150 @@ +# از راه دور، کارفرما برنامه را ببیند — دروازهٔ ورود و آدرس + +**این سند برای چه کسی است:** برای کسی که برنامه روی لپ‌تاپ خودش اجرا می‌شود و می‌خواهد +کارفرمایی در شهر دیگر، بدون حضور، همان برنامهٔ در حال اجرا را ببیند و تست کند. +**نتیجه در یک خط:** برنامه یک «دروازهٔ ورود» دارد؛ با روشن‌کردن آن، هر کسی که آدرس را داشته +باشد بدون شناسه و رمز چیزی نمی‌بیند، و کارفرما با حساب نام‌دار خودش وارد می‌شود. + +## ۱. چرا دروازه، و چرا رمز مدیر را نمی‌دهیم + +سه چیز را با هم حل می‌کند، و هر سه تای آن در جلسهٔ نمایش به چشم می‌آید: + +| مسئله | بدون دروازه | با دروازه | +| --- | --- | --- | +| رمز مدیر | باید در اختیار کارفرما گذاشته شود؛ صاحب برنامه دیگر نه | دست خودِ صاحب برنامه می‌ماند | +| حس «حساب واقعی» | کارفرما می‌داند رمز مشترک است، پس ارزشی برایش ندارد | برایش حساب نام‌دار ساخته می‌شود؛ حس می‌کند مهم است | +| غریبه | هر کسی آدرس را داشته باشد وارد می‌شود | بدون رمز، هیچ صفحه‌ای و هیچ خروجی‌ای باز نمی‌شود | + +نکتهٔ چهارمی هم هست که به کار خودتان می‌آید: **در جلسهٔ نمایش، شما کارفرما هستید.** با حساب +مدیر پنل، مجوز، رمزها و کلید خاموش‌کردن برنامه را نشان می‌دهید؛ این کاری است که کارفرمای واقعی +نمی‌تواند بکند. + +## ۲. راه‌اندازی، سه فرمان (یک‌بار) + +همه از پوشهٔ `station` اجرا می‌شود: + +```bash +python3 gate.py --sync-admin # ۱. رمز مدیر دروازه = همان رمز پنل +python3 gate.py --guest-id masoud --guest-pass "رمز-کارفرما" # ۲. حساب کارفرما (دست‌کم ۸ نویسه) +python3 gate.py --on # ۳. روشن‌کردن دروازه +python3 gate.py --status # کنترل: روشن است؟ حساب‌ها فعال‌اند؟ +``` + +پس از فرمان سه، آدرس برنامه را باز کنید: **صفحهٔ ورود** می‌آید، نه برنامه. +فرمان‌های روزمره: + +| کار | فرمان | +| --- | --- | +| وضعیت و شمار نشست‌های باز | `python3 gate.py --status` | +| آزمودن یک جفت شناسه/رمز | `python3 gate.py --check masoud "رمز-کارفرما"` | +| عوض‌کردن رمز کارفرما | `python3 gate.py --guest-id masoud --guest-pass "رمز-تازه"` | +| قطع‌کردن کارفرما (نشست بازش هم همان لحظه بسته می‌شود) | `python3 gate.py --guest-off` | +| روشن‌کردن دوبارهٔ دسترسی کارفرما | `python3 gate.py --guest-on` | +| خاموش‌کردن دروازه (برگشت به حالت قبل: همین لپ‌تاپ = مدیر) | `python3 gate.py --off` | + +رمزها فقط به‌شکل هش روی دیسک می‌مانند؛ در پروندهٔ `config/gate.json` هیچ رمزی نیست. مدیر دروازه +عمداً همان رمز پنل مدیریت است تا دو رمز برای به‌خاطر‌سپردن نداشته باشید. + +## ۳. کارفرما چه می‌بیند و چه نمی‌تواند + +| کارفرما (حساب مهمان) | می‌بیند | نمی‌تواند | +| --- | --- | --- | +| یازده گام برنامه | ✅ همه | — | +| خروجی‌ها و برگه‌های چاپی (پیشنهاد، پیام‌ها، تابلوی پیگیری، راهنمای تازه‌کار، کارنامهٔ بازبینی) | ✅ همه | — | +| دکمه‌های ساخت و اجرای محاسبه | ✅ (تست کامل، با خطر ریسک صفر چون سفارشی نمی‌رود) | — | +| پنل مدیریت (سلامت، مجوز، عیب‌یابی، گواهی استفاده) | ❌ | ❌ | +| صدور اجازه‌نامهٔ نام‌دار | ❌ | ❌ | +| عوض‌کردن رمزها و روشن/خاموش‌کردن دروازه | ❌ | ❌ | +| خاموش‌کردن برنامه | ❌ | ❌ | + +اگر کارفرما در صفحهٔ ورود، آدرس یک بخش را بزند، پس از ورود همان بخش باز می‌شود؛ اگر بی‌اجازه +سراغ مسیرهای مدیریت برود، پاسخ «این بخش فقط با حساب مدیر باز می‌شود» را می‌گیرد. + +## ۳.۵ چند کاربر: شناسه و رمز را خودت می‌سازی، هر وقت خواستی حذف می‌کنی + +لازم نیست همه با یک حساب وارد شوند. برای هر نفر یک کاربر بساز: + +```bash +python3 gate.py --user-add ali "رمز-علی" --user-note "کارشناس شرکت" # ساخت +python3 gate.py --users # فهرست (شناسه، وضعیت، یادداشت، نشست باز) +python3 gate.py --user-off ali # قطع فوری (نشست بازش هم بسته می‌شود) +python3 gate.py --user-on ali # وصل‌کردن دوباره +python3 gate.py --user-del ali # حذف کامل +``` + +همین کارها با دکمه هم هست: **در خود برنامه**، گام ۱، کارت مدیر (ردیف «ساخت کاربر» و فهرست کاربران +زیر آن)، و در **پنل مدیریت، کارت ۴**. رمز هیچ‌جا به‌صورت متن نمی‌ماند؛ فقط هش‌شده روی دیسک. + +سه نکتهٔ صادقانه: + +1. **حذف، همان لحظه اثر می‌کند**: نشست باز آن کاربر بی‌درنگ می‌میرد (نه با ری‌استارت برنامه). +2. **همهٔ کاربران نقش «مهمان» دارند**: کل برنامه و برگه‌ها را می‌بینند، ولی به پنل مدیریت، مجوز، + عوض‌کردن رمزها، مدیریت کاربران و خاموش‌کردن برنامه دسترسی ندارند. +3. **شناسه و رمز حساب مدیر (خودت)** را هم از پنل مدیریت، کارت ۴ می‌توانی تعیین کنی؛ بعد از عوض‌کردن، + با شناسهٔ تازه وارد شو و رمز قدیمی دیگر کار نمی‌کند. + +## ۴. آدرس دادن به کارفرمای شهر دیگر + +برنامه روی لپ‌تاپ شما اجرا می‌شود و در شبکهٔ محلی خودتان است؛ برای دیدن از بیرون، یک پل لازم است. +دو مسیر واقعی هست؛ مسیر اول برای امروز، مسیر دوم برای همیشه: + +| مسیر | چه زمانی | هزینه و کار | نکته | +| --- | --- | --- | --- | +| پل موقت (تونل) | جلسهٔ امروز یا فردا | صفر | آدرس تا وقتی برنامه باز است زنده می‌ماند؛ پس از جلسه ببندید | +| سایت ثابت | وقتی می‌خواهید همیشه یک نشانی داشته باشید | دامنه و میزبانی | ایستگاه روی یک میزبان ابری کوچک اجرا می‌شود و پشت همان دروازه می‌نشیند | + +مسیر پیشنهادی برای امروز: پل موقت. روی همان لپ‌تاپی که برنامه اجرا شده، در ترمینال دوم یک تونل +امن باز کنید و آدرس `https` را برای کارفرما بفرستید. نمونهٔ رایج و بی‌هزینه‌اش Cloudflare Tunnel +است؛ فایل اجرایی‌اش را از سایت خودش می‌گیرید و در ترمینال دوم می‌زنید: + +```bash +cloudflared tunnel --url http://localhost:8765 +``` + +سپس آدرسی شبیه `https://یک-نام-تصادفی.trycloudflare.com` چاپ می‌شود؛ همان را برای کارفرما +بفرستید (ابزارهای مشابه مثل ngrok هم همین کار را می‌کنند). این آدرس تا وقتی آن ترمینال باز است +زنده می‌ماند؛ برای جلسهٔ نمایش کافی است و پس از جلسه ببندید. دروازه جلوی برنامه می‌ایستد، پس حتی +اگر آدرس دستِ دیگری بیفتد، بدون رمز چیزی باز نمی‌شود. +هر آدرسی که برای کارفرما فرستاده می‌شود، باید سه ویژگی داشته باشد: + +1. **https باشد** (رمز ورود روی خط نرود)؛ +2. برنامه روی همان رایانه‌ای باشد که خروجی‌های زنده را دارد (نه یک رونوشت دستی)؛ +3. دروازه روشن باشد (فرمان ۳ بالا). + +اگر ترجیح می‌دهید نسخهٔ سایت‌شده بیاورم (می‌زبانی + دامنه + دروازه + پشتیبان‌گیری)، همان کار را +انجام می‌دهم؛ فقط بدانید که هزینهٔ میزبانی ماهانه به عهدهٔ شماست و تا آن روز، پل موقت هیچ هزینه‌ای +ندارد. + +## ۵. چک‌لیست ۵ دقیقه‌ای پیش از جلسهٔ نمایش + +| ☐ | کار | فرمان یا جای دکمه | +| --- | --- | --- | +| ☐ | برنامه بالا باشد | `run-gui` (ویندوز: دوبار کلیک روی `run-gui.bat`) | +| ☐ | سلامت اجزا سبز باشد | گام ۱ → کارت سلامت (یا پنل مدیریت → بررسی سلامت) | +| ☐ | دروازه روشن و حساب کارفرما فعال باشد | `python3 gate.py --status` | +| ☐ | برگه‌های جلسه ساخته باشند | گام ۸ → پیشنهاد، پیام‌ها، تابلو، مراسم امروز، جلسهٔ بازبینی | +| ☐ | آدرس https آماده باشد | ترمینال دوم → تونل | +| ☐ | یک بار خودتان با حساب کارفرما وارد شوید | `python3 gate.py --check masoud "رمز-کارفرما"` | +| ☐ | در پایان جلسه، نشست‌های کارفرما را ببندید | کارت مدیر → «بستن نشست‌های باز مهمان» | + +## ۶. آنچه ادعا نمی‌کنم + +- **داده از رایانهٔ شما بیرون نمی‌رود.** دروازه فقط در را باز می‌کند؛ هیچ خروجی‌ای به سرویس + بیرونی فرستاده نمی‌شود. +- **دروازه، «امنیت بانکی» نیست.** یک ورود ساده با رمز کوتاه‌عمر است؛ کارِ اصلی را https و رمز + یک‌بارمصرف تونل می‌کند. برای دادهٔ مالی واقعی، همین دو لایه کافی است، ولی اگر کسی به لپ‌تاپ + دسترسی فیزیکی داشته باشد، دروازه چیزی را از او پنهان نمی‌کند. +- **هیچ سودی، هیچ پیش‌بینی قیمت و هیچ سفارش خودکاری در این مسیر نیست.** برنامه عدد و دلیل + می‌گذارد روی میز؛ ثبت سفارش در سامانهٔ کارگزاری کارِ معامله‌گر است. +- **کارفرما همه‌چیز را می‌بیند** — خروجی‌ها، محاسبه‌ها و خطاها. این عمدی است: چیزی برای پنهان‌کردن + طراحی نشده؛ فقط کلیدهای خطرناک (مجوز، رمز، خاموشی) دست او نیست. + +## ۷. پیوست: پرونده‌های این بخش + +| پرونده | کار | +| --- | --- | +| `station/gate.py` | دروازه: حساب‌ها، ورود/خروج، نقش‌ها، نشست‌ها، فرمان‌های خط فرمان | +| `station/web/login.html` | صفحهٔ ورود (فارسی، ساده، بدون هیچ منبع بیرونی) | +| `station/config/gate.json` | نمک و هش رمزها + روشن/خاموش‌بودن دروازه (بدون رمز) | +| `station/tests/test_gate.py` | ۱۹ آزمون: هش‌شدن رمز، نقش مهمان، بستن نشست، قفل پس از پنج خطا، نگهبانی مسیرها | +| `station/web_server.py` | نگهبانی همهٔ مسیرها، `/api/login`، `/api/logout`، `/api/gate/update`، `/api/shutdown` | diff --git a/station/docs/18-client-value-fa.md b/station/docs/18-client-value-fa.md new file mode 100644 index 0000000000000000000000000000000000000000..4220d4146eb144c78ff2b85937723ec50e74ae50 --- /dev/null +++ b/station/docs/18-client-value-fa.md @@ -0,0 +1,101 @@ +# خروجی‌های این برنامه به کارفرما چه می‌دهند — و چه فرقی با برنامه‌های دیگر دارد + +**این سند برای چه کسی است:** برای معامله‌گر مشتقه‌ای که می‌خواهد بداند «این برنامه در عمل چه +کاری برایم می‌کند»، و برای کسی که می‌خواهد همین را در جلسه به شرکت یا کارفرما نشان بدهد. +**جملهٔ کوتاه:** بقیهٔ ابزارهای فارسی «چه بخر» را نشان می‌دهند؛ این ایستگاه «چرا بخر، با چه +کارمزدی، تا کجا خطر داری، و از کجا بفهمیم اشتباه نبوده» را روی میز می‌گذارد. + +## ۱. دوازده خروجی، و کاری که هرکدام انجام می‌دهد + +| خروجی | به کدام سؤال کارفرما جواب می‌دهد | چه چیزی را نشان *نمی‌دهد* | +| --- | --- | --- | +| **جدول سیگنال‌ها** (گام ۶) | امروز کجا تفاوت ریاضی قیمت از حاشیهٔ اطمینان عبور کرده؟ | سود آینده؛ فقط همان لحظه را می‌سنجد | +| **داوری سیگنال ابزارهای دیگر** | سیگنالی که در کانال/سایت دیگری دیدم، **می‌ماند یا می‌افتد**؟ با چه دلیلی؟ | درستی آن سیگنال؛ فقط «ماند» یا «افتاد» را با دلیل می‌گوید | +| **پلهٔ تصمیم** | چه بخرم، چه زمانی بفروشم، چه زمانی بپرم بیرون | قیمت هدف؛ نقطهٔ برگشت با نرخ سد امروز حساب می‌شود | +| **فاصله تا مارجین‌کال** | با این موقعیت، تا اخطاریهٔ کارگزاری چقدر فاصله دارم؟ | تضمین اینکه اخطاریه نمی‌آید | +| **کارنامهٔ آمادگی پنج‌شرطی** | دو هفته کار ما به کجا رسید؟ آماده‌ایم یا نه؟ | سود؛ فقط «آماده/ناتمام» با پنج شرط عددی | +| **دفتر استفادهٔ زنجیره‌هش‌دار** | چند کار موفق انجام شد، در چه روزهایی | سود، درستی تصمیم بازار، درصد موفقیت معامله | +| **آزمون ۱۰ دقیقه‌ای (۱۵ سنجه، هر کدام دو بار)** | عددهای برنامه بازتولیدشدنی‌اند؟ | کیفیت تصمیم؛ فقط درستی حساب و موتور | +| **سند مجوز دوامضا** | چه چیزی تحویل داده شد، تا چه زمانی، با چه تعهدی | پشتیبانی بی‌پایان؛ دورهٔ اعتبار روشن است | +| **پیشنهاد یک‌صفحه‌ای** | این برنامه چه می‌دهد و قیمتش چیست | وعدهٔ درآمد؛ قیمت در جلسه با هم گذاشته می‌شود | +| **برگهٔ روز اول / جلسهٔ بازبینی ۱۴ روزه** | بعد از خرید چه می‌شود و روز چهاردهم چه تصمیمی می‌گیریم | «دفعهٔ بعد»ی مبهم؛ دو خروجی روشن دارد | +| **تابلوی پیگیری مخاطبان** | من با شرکت‌ها چطور پیش می‌روم (برای فروشندهٔ راه‌حل) | ندارد | +| **بستهٔ شاهد شرکت** (گام ۸) | همهٔ بالا، در یک پوشهٔ تاریخ‌دار با فهرست و اثر انگشت هر پرونده | دست‌کاریِ بعدی را لو می‌دهد، نه جعل حرفه‌ای | + +## ۲. سه استفادهٔ عملی برای کارفرما + +۱. **قبل از هر سفارش، عدد و دلیل.** کارفرما (یا تحلیلگرش) پیش از ثبت سفارش می‌بیند: تفاوت +ریاضی چقدر است، کارمزد خرید و فروش و اعمال چقدر است، با چه نرخ سدی سیگنال می‌افتد، و اگر بازار +بر خلاف رفت چند درصد تا اخطاریهٔ مارجین فاصله هست. یعنی تصمیم روی عدد می‌نشیند، نه روی حس. + +۲. **دفاع در برابر اشتباه، نه وعدهٔ سود.** هر عدد با **دو روش** بازتولید می‌شود (موتور ریاضی و +حساب دستی مستقل)، دفتر کارها **زنجیرهٔ هش** دارد، و اگر کسی بعداً ردیفی را عوض کند، +`python3 usage_meter.py --summary --verify` می‌گوید کدام ردیف. این همان چیزی است که در جلسهٔ +حسابرسی یا جلسهٔ شرکت، برنامه را از «ادعا» جدا می‌کند. + +۳. **تصمیم روی شاهد، نه روی قول.** دو هفته کار با کارنامهٔ پنج‌شرطی سنجیده می‌شود؛ روز چهاردهم +یا پرداخت در برابر پروندهٔ همان پله است یا توقف بی‌گلایه‌مندی. اگر کارنامه «آماده» نبود، یک +تمدید بی‌هزینهٔ چهارده‌روزه هست. کارفرما هیچ‌وقت زیر فشار «همین امروز تصمیم بگیر» نیست. + +## ۳. تفاوت با برنامه‌های فارسی موجود + +| موضوع | ابزارهای رایج (دیده‌بان آپشن، اسکرینرها، کانال‌های سیگنال) | این ایستگاه | +| --- | --- | --- | +| کار اصلی | نمایش: زنجیرهٔ قرارداد، فیلتر، ماشین‌حساب قیمت، تحلیل روزانه | **داوری**: سیگنال می‌ماند یا می‌افتد، با دلیل و نقطهٔ برگشت | +| کارمزد و هزینه | معمولاً نادیده یا سرانگشتی | کارمزد خرید/فروش/اعمال و مالیات تسویهٔ فیزیکی، با عدد کارگزاری خودتان | +| خطر | بی‌خبر از فاصله تا مارجین‌کال | حد نگهداری ۷۰٪ و فاصله تا اخطاریه، روی خودِ موقعیت | +| حرف خودش را اثبات می‌کند؟ | نه؛ کاربر باید اعتماد کند | هر عدد دو بار (موتور + حساب دستی) + برگهٔ آزمون قابل بازتولید | +| ردیابی کارها | ندارد | دفتر زنجیره‌هش‌دار + گواهی استفادهٔ قابل بازبینی | +| دستور خودکار | برخی اتصال به کارگزاری پیشنهاد می‌دهند | **عمداً ندارد**؛ طبق ابلاغیهٔ مهر ۱۳۹۹ معاملات الگوریتمی خودکار مجاز نیست؛ سفارش را کاربر ثبت می‌کند | +| داده | بعضی فقط با اشتراک پولی کار می‌کنند | با دادهٔ رایگان آزمون‌شده (دلار/طلا/سکه/صرافی) کار می‌کند؛ سرویس خریدنی اختیاری است | +| پیگیری مشتری | ندارد | برگهٔ روز اول، مراسم بیست‌دقیقه‌ای، تابلو با قاعدهٔ پیگیری ۰/۳/۱۰، جلسهٔ بازبینی ۱۴ روزه | +| محل اجرا | سرویس ابری (داده بیرون می‌رود) | همه‌چیز روی لپ‌تاپ خودتان؛ هیچ داده‌ای به بیرون نمی‌رود | + +## ۴. آنچه ادعا نمی‌کنم (همین را در جلسه هم بگویید) + +- **هیچ سود تضمینی و هیچ پیش‌بینی قیمت نیست.** خروجی، «عدد و دلیل» است؛ تصمیم با شماست. +- **درصد موفقیت معاملات را ادعا نمی‌کنیم.** چیزی که شمرده می‌شود «کارهای موفق انجام‌شده» است + (مثل ساخت برگه و اجرای داوری)، نه سود. +- **بازار ایران با ابلاغیه عوض می‌شود.** اگر قاعده‌ای عوض شد، عدد قدیمی بی‌اعتبار است؛ به‌همین + دلیل همهٔ سودها با نرخ سد و کارمزدِ روز حساب می‌شوند، نه با عدد ثابت. +- **اعداد وجه تضمین و مشخصات قرارداد از کارگزاری می‌آید.** برنامه جای آن را دارد، ولی منبع، + کارگزاری شماست. +- **بازۀ دادهٔ تاریخی برای پس‌آزمایی محدود است.** هر ادعای فراتر از آن، ادعای بی‌شاهد است. + +## ۵. ده دقیقهٔ دمو: چه چیزی را به چه ترتیبی نشان دهیم + +| دقیقه | کار | چرا این‌جا | +| --- | --- | --- | +| ۰–۱ | گام ۱: سلامت اجزا + جملهٔ «سفارش را خودتان می‌فرستید» | اعتماد اول از صداقت می‌آید | +| ۱–۳ | گام ۲: اتصال خودکار (منبع رایگان) + یک برگهٔ شاهد زنده | «الان واقعاً وصل است» | +| ۳–۵ | گام ۶: یک سیگنال واقعی → داوری → فاصله تا مارجین‌کال | قلب برنامه | +| ۵–۶ | گام ۶: داوری سیگنال یک ابزار دیگر (ورودی دستی) | بولدترین نقطهٔ تمایز | +| ۶–۷ | گام ۷: پس‌آزمایی روی دادهٔ تاریخ | «آینده‌نگری» ممنوع است، خودش می‌گوید | +| ۷–۸ | گام ۹: مراسم روزانه + کارنامهٔ پنج‌شرطی | «از کجا بفهمیم آماده‌ایم» | +| ۸–۹ | گام ۱۰: آزمون کور (کارفرما حدس می‌زند، بعد پاسخ را می‌بیند) | کارفرما **خودش** تست می‌کند | +| ۹–۱۰ | گام ۸: بستهٔ شاهد + کارت امضا | «همهٔ این‌ها را با خودتان ببرید» | + +## ۶. اگر کارفرما سه سؤال سخت بپرسد + +| پرسش | پاسخ صادقانه | +| --- | --- | +| «چقدر سود می‌دهد؟» | «عدد سود نمی‌دهم؛ چون هیچ‌کس نمی‌داند و هرکس بگوید، دارد چیزی را می‌فروشد که ندارد. چیزی که می‌دهم این است: هر تصمیم با کارمزد واقعی، فاصله تا مارجین‌کال و نقطهٔ برگشت عددی. سود، نتیجهٔ اجرای منظم همین است، نه وعدهٔ من.» | +| «این اعداد را از کجا آورده‌ای؟» | «همین حالا نشان می‌دهم: `python3 selftest.py` پانزده سنجه را دو بار حساب می‌کند و برگهٔ آزمون می‌سازد؛ دفتر کارها هم زنجیرهٔ هش دارد و اگر عوض شده باشد، خودش می‌گوید.» | +| «خودم هم می‌توانم این را بسازم.» | «شاید؛ ولی دو هفته کار لازم دارد: لایهٔ داده، موتور کارمزد ایران، شاهدها، برگه‌ها و مراسم فروش. اگر خودتان ترجیح می‌دهید، همین بستهٔ شاهد را بردارید و در تیم خودتان اجرا کنید؛ فقط بدانید پشتیبانی و روز بازبینی هم بخشی از خروجی است.» | + +## ۷. پیوست: کدام فایل، کدام فرمان + +| خروجی | جای دیدن در برنامه | فرمان خط فرمان | +| --- | --- | --- | +| پیشنهاد یک‌صفحه‌ای | گام ۸ | `python3 offer.py --client "نام شرکت"` | +| پیام‌های معرفی و پیگیری | گام ۸ | `python3 outreach.py --client "نام"` | +| روز اول مشتری | گام ۸ | `python3 onboarding.py --client "نام" --start 2026-09-22` | +| جلسهٔ بازبینی دو هفته‌ای | گام ۸ | `python3 review_meeting.py --client "نام" --start 2026-09-22` | +| مراسم بیست‌دقیقه‌ای فروش | گام ۸ | `python3 sales_ritual.py --sheet` | +| تابلوی پیگیری مخاطبان | گام ۸ | `python3 prospects.py --sheet` | +| کارنامهٔ آمادگی | گام ۹ | `python3 daily_trial.py --status` | +| دفتر و گواهی استفاده | پنل مدیریت | `python3 usage_meter.py --summary --verify` | +| آزمون ۱۰ دقیقه‌ای و پروندهٔ سرمایه‌گذار | گام ۹ | `python3 selftest.py` · `python3 dossier.py` | +| آزمون کور و پلهٔ تصمیم | گام ۱۰ | `python3 investor_test.py --cases` · `--ladder` | +| راهبردها، شوک‌آزمون و ریاضیِ پول | گام ۱۱ | `python3 strategy_audit.py` · `edge_stress.py` · `bankroll.py` | +| بستهٔ شاهد شرکت | گام ۸ | دکمهٔ «ساخت بستهٔ راستی‌آزمایی» | diff --git a/station/docs/19-demo-offline-decision-fa.md b/station/docs/19-demo-offline-decision-fa.md new file mode 100644 index 0000000000000000000000000000000000000000..4b005141d264e144e11ca6e893c0f69d1eaa9aa6 --- /dev/null +++ b/station/docs/19-demo-offline-decision-fa.md @@ -0,0 +1,73 @@ +# ۱۹ — تصمیم «نمایش آفلاین»: کوله‌پشتی دمو + +> تاریخ تصمیم: ۱ مهر ۱۴۰۵ (۲۲ سپتامبر ۲۰۲۶) · تصمیم‌گیر: خودکار، بر پایهٔ شواهد اینترنت ایران در ۲۰۲۶ +> نتیجهٔ یک‌خطی: **ستون فقرات نمایش به کارفرما دیگر به هیچ لینک اینترنتی گره نمی‌خورد.** + +## ۱) چرا این تصمیم؟ + +سه شاهد بیرونی (نه حدس): + +1. در ۲۰۲۶ اینترنت ایران دورهٔ خاموشی سراسری و «وایت‌لیست» را گذراند؛ گزارش‌ها از افت ترافیک تا حدود یک درصد در آوریل ۲۰۲۶ و بازگشت تدریجی با طرح گران‌تر «Internet Pro» خبر می‌دهند. +2. کاربر ایرانی در آوریل ۲۰۲۶ نوشته است: **به `huggingface.co` دسترسی ندارم**؛ یعنی همان جایی که دموی ما منتشر شده. +3. سرویس‌های `pages.dev` و `workers.dev` جداگانه و مستقل فیلتر می‌شوند؛ پس «لینک رایگان خارجی» برای ما یک راه‌حل شکننده است، نه یک راه‌حل. + +نتیجهٔ عملی: اگر کارفرما بخواهد برنامه را ببیند، **نباید** بگوییم «به این لینک بروید» و امیدوار باشیم باز شود. + +## ۲) سه راه، با شرایط واقعی + +| راه | برای چه کسی | نیاز به اینترنتِ باز | نیاز به پول | شکنندگی | +|---|---|---|---|---| +| **کوله‌پشتی آفلاین** (این سند) | نمایش در جلسه، روی لپ‌تاپ خودمان | **ندارد** | ندارد | **کم**: همه‌چیز داخل خود پوشه است | +| راه‌اندازی روی رایانهٔ خودمان + لینک موقت تونل | نمایش از راه دور برای کارفرمای غیرحاضر | دارد (کارفرما) | ندارد | متوسط — لینک با بستن برنامه می‌میرد | +| Space روی Hugging Face (Static) | «اگر اینترنت باز بود، نشانش بده» | دارد | ندارد | **زیاد**: از ایران معمولاً باز نمی‌شود | + +تصمیم: راه اول ستون فقرات؛ راه دوم برای حالت «کارفرما بیرون از جلسه است»؛ راه سوم **مکمل** و اختیاری می‌ماند و هیچ وعدهٔ نمایش به آن گره نمی‌خورد. + +## ۳) کوله‌پشتی دمو چیست؟ + +یک پوشهٔ خودکفا که با دو کلیک بالا می‌آید و برای کارفرما هم یک صفحهٔ «شروع از اینجا» دارد: + +- `demo/` (**نمونهٔ ثابت دمو**): خروجی‌های واقعی برنامه که از اجرای واقعی ضبط شده‌اند و از فایل محلی اجرا می‌شوند (بدون سرور، بدون اینترنت). +- `station/` (**برنامهٔ زنده** روی همان لپ‌تاپ، روی شبکهٔ محلی). +- `python/` ((اختیاری) پایتون قابل‌حمل ویندوز)؛ اگر لپ‌تاپ کارفرما پایتون نداشت هم برنامه بالا می‌آید. +- `RUN-LIVE-WINDOWS.bat` / `RUN-LIVE-LINUX.sh`: برنامهٔ زنده + **ساخت رمز اولین اجرا** + روشن‌کردن دروازه. +- `RUN-DEMO-LAN-WINDOWS.bat` / `RUN-DEMO-LAN-LINUX.sh`: نمونهٔ ثابت برای نشان دادن روی گوشی/لپ‌تاپ کارفرما در همان وای‌فای. +- `CHECK-WINDOWS.bat` / `CHECK-LINUX.sh`: آزمون سلامت خود بسته («چه چیزی هست، چه چیزی نیست»). + +## ۴) شرایط نمایش (بی‌کم‌وکاست) + +1. **رمزها**: اولین اجرا رمز می‌سازد و در `station/config/CREDENTIALS-FIRST-LOGIN.txt` می‌نویسد (فقط مدیر و کارفرما می‌بینند). اگر رمزها را عوض کردیم، همان فایل را دوباره `--force` می‌کنیم. +2. **دادهٔ واقعی روی دستگاه عمومی نمی‌ماند**: برای نمایش، خروجی‌ها را از همان ایستگاه خودمان می‌گیریم؛ روی لپ‌تاپ کارفرما فقط چیزی می‌رود که می‌خواهیم نشان دهیم. +3. **دو صداقت که در جلسه گفته می‌شود**: (الف) `demo/` **نمونهٔ ثابت** است؛ عکس‌های واقعی از خروجی‌های واقعی، نه اتصال زنده؛ (ب) نسخهٔ زنده روی همان لپ‌تاپ و با **دادهٔ واقعیِ همان لحظه** کار می‌کند، ولی تا وقتی رمز کارگزاری نخریده‌ایم، دستور نمی‌دهد و فقط داوری می‌کند. +4. **پورت**: اگر ۸۷۶۵ روی آن لپ‌تاپ پر بود: `set STATION_PORT=9000` (ویندوز) یا `STATION_PORT=9000 bash RUN-LIVE-LINUX.sh`. + +## ۵) «راه زندهٔ کامل» چه زمانی می‌آید؟ + +سه مسیر، به‌ترتیب هزینه؛ هر کدام را کاربر بتواند، همان روز راه می‌افتد: + +1. **رایانهٔ خودمان** (صفر تومان، امروز کار می‌کند): برنامه و لینک موقت برای کارفرمای غیرحاضر. +2. **Render روی پلن مجانی با یک مخزن GitHub** (صفر تومان؛ خواب بعد از ۱۵ دقیقهٔ بی‌کاری و بیدارشدن ۳۰–۶۰ ثانیه‌ای). +3. **HF PRO ماهانه ~۹ دلار**: تنها راه میزبانی داکری/گرادیو روی Hugging Face (پلن مجانی برای این دو، پاسخ ۴۰۲ می‌دهد). + +## ۶) آزمون‌هایی که این تصمیم را پشتیبان می‌کند + +- **آفلاین**: اجرای نمونهٔ ثابت از خود فایل → «۱۱ گام · همه باز · صفر خطا» (بدون هیچ شبکه‌ای). +- **زندهٔ محلی روی بستهٔ تحویلی**: رمز اولین اجرا ساخته می‌شود · بدون ورود ۴۰۱ · ورود کارفرما ۲۰۰ · پنل مدیر برای کارفرما ۴۰۳. +- **آزمون درخت اصلی**: `gui/tests/test_backpack.py`: ساختار بسته، نحو اسکریپت‌های ویندوز/لینوکس، نبود راز، و بالا آمدن زنده. +- **آنچه آزمون‌پذیر نیست**: اینکه Internet کارفرما باز باشد؛ پس همان‌جا گفتیم نمایش به اینترنت گره نخورده است. + +## ۷) فعال‌سازی برنامهٔ زنده و کاربران (۲۲ سپتامبر ۲۰۲۶) + +برنامهٔ **زنده** همان ایستگاه واقعی است (نه نمونهٔ ثابت): با دروازهٔ ورود، پنل مدیر، موتور ریاضی و +دفتر زنجیره‌هش‌دار. سه تصمیم این دور: + +1. **کاربران را خودِ صاحب برنامه می‌سازد**: هر تعداد کاربر با شناسه و رمز دلخواه (برنامه، پنل مدیریت، + یا خط فرمان)؛ رمز فقط هش‌شده ذخیره می‌شود. +2. **حذف، همان لحظه اثر می‌کند**: با «حذف کامل» یا «قطع دسترسی»، نشست باز آن کاربر بی‌درنگ می‌میرد. +3. **بیرون از ورود هیچ‌چیز درز نمی‌کند**: وضعیت سامانه برای ناشناس، نه شناسهٔ مدیر را می‌گوید و نه + فهرست کاربران را (این یکی در همان دور اصلاح شد). + +دربارهٔ «کجا زنده باشد»، ترتیب صادقانه همان است که در بخش ۲ آمد: روی رایانهٔ خودت (امروز، بدون هزینه)، +یا Render با مخزن GitHub (مجانی، با خواب ۱۵ دقیقه‌ای)، یا میزبان داکری پولی. هر کدام از این‌ها را +خواستی، همان روز بالا می‌آید؛ و «حذف کامل» همیشه با خودت است: دکمهٔ خاموش‌کردن برنامه در گام ۱، +یا پاک‌کردن کامپوننت/سرویس روی میزبان. diff --git a/station/docs/20-security-review-fa.md b/station/docs/20-security-review-fa.md new file mode 100644 index 0000000000000000000000000000000000000000..e4de78e141ec968b9e84c25a8f7c146f6cc71508 --- /dev/null +++ b/station/docs/20-security-review-fa.md @@ -0,0 +1,80 @@ +# ۲۰ — بررسی امنیتی: «می‌شود این برنامه را هک کرد؟» + +> تاریخ بررسی: ۱ مهر ۱۴۰۵ (۲۲ سپتامبر ۲۰۲۶) · روش: **حملهٔ واقعی** به یک نسخهٔ در حال اجرا، نه بازخوانی کد +> پروندهٔ آزمون: `MATERIALS/money/gui/tests/test_security.py` (۲۲ آزمون) — همه سبز +> جمع آزمون‌های درخت اصلی در همین تاریخ: **۶۵۸ سبز · ۱ رد · ۰ خطا** + +## ۱) خلاصهٔ صادقانه در سه خط + +۱. هیچ راهی پیدا نشد که کسی **بدون شناسه و رمز** به برنامه یا به عددهای شرکت برسد. +۲. سه ایراد واقعی پیدا و همان‌جا بسته شد (لو رفتن شناسه‌ها، قفل شدن همهٔ کاربران با خطای یک نفر، و + نبود سرآیندهای امنیتی). یک لایهٔ سخت‌گیرانه هم روی مسیر پرونده‌ها گذاشته شد. +۳. این برنامه **جای امنیت بانکی نیست**: هیچ رمز بانکی و شمارهٔ حسابی در آن وارد نمی‌شود، و اگر خود + رایانه لو برود، هیچ نرم‌افزاری نمی‌تواند جلویش را بگیرد. + +## ۲) چه چیزهایی آزموده شد (و نتیجه) + +| حمله | چه کاری کردیم | نتیجه | +| --- | --- | --- | +| خواندن پروندهٔ رازها با پیمایش مسیر | `..`، شکل درصدی‌شده، بک‌اسلش، نویسهٔ صفر، و ترکیب‌های چندلایه | **بسته**: پاسخ ۴۰۰/۴۰۳/۴۰۴، هیچ پرونده‌ای بیرون از پوشهٔ مجاز سرو نمی‌شود | +| فهرست‌کردن پوشه‌ها | درخواست `/files/`، `/web/`، `/data/` | **بسته**: هیچ فهرستی برنمی‌گردد | +| ورود بدون رمز / کوکی جعلی | کوکی ساختگی، کوکی خالی، نویسهٔ صفر در کوکی | **بسته**: همه به صفحهٔ ورود برمی‌گردند | +| بالا رفتن از نقش کارفرما به مدیر | پنل، صدور مجوز، عوض‌کردن رمز، ساخت کاربر، خاموش کردن برنامه | **بسته**: همه ۴۰۳ (آزمون تعاملی هم همین را می‌سنجد) | +| فهمیدن اینکه کدام شناسه وجود دارد | ورود با شناسهٔ ناموجود و با شناسهٔ موجود | **یکسان**: پیام یکی است، کد یکی است | +| تلاش پی‌درپی برای شکستن رمز | پنج تلاش ناموفق | **قفل کوتاه** برای همان نشانی (با نشانی ساختگی ۲۰۳.۰.۱۱۳.۷۷ هم آزمودیم که دور نمی‌زند) | +| درخواست از سایت دیگر (CSRF) | درخواست با مبدأ `evil.example` | **۴۰۳**: فقط میزبان خودمان پذیرفته می‌شود | +| روش‌های ناخواسته | PUT/DELETE/PATCH/TRACE/OPTIONS | **۴۰۵/۲۰۴** با فهرست مجاز روش‌ها | +| بدنهٔ غول‌آسا (پرکردن حافظه) | ۳ مگابایت در یک درخواست | **۴۱۳** و بستن همان اتصال؛ سرور سرپا می‌ماند | +| بدنهٔ خراب | JSON ناقص | پاسخ خطا، سرور سالم | +| درز راز در پاسخ‌های عمومی | وضعیت سامانه برای ناشناس، خروجی‌های چاپی | **پاک**: نه شناسه، نه فهرست کاربران، نه هیچ بخشی از رمز | +| راز روی دیسک | خواندن پروندهٔ تنظیمات | فقط **هش**؛ رمز به شکل خوانا نیست | + +## ۳) سه ایراد واقعی که پیدا شد و بسته شد + +1. **لو رفتن شناسه‌ها پیش از ورود.** پیش‌تر `/api/gate/status` برای هر کسی که صفحهٔ ورود را باز می‌کرد، + شناسهٔ مدیر و کارفرما را برمی‌گرداند. حالا برای ناشناس فقط «روشن/خاموش، قاعدهٔ دروازه، عمر نشست» + می‌رود؛ شناسه‌ها و فهرست کاربران فقط با حساب مدیر. +2. **قفل شدن همه با خطای یک نفر.** قفل تلاش ناموفق به نشانی سوکت گره خورده بود؛ پشت تونل، نشانی همه + یکی می‌شود. حالا اگر درخواست از یک پروکسی معتبر بیاید، نشانی واقعی کاربر از هدر خوانده می‌شود + (`STATION_TRUST_PROXY=1`) و آزمون نشان می‌دهد خطای یک نفر، بقیهٔ کاربران را قفل نمی‌کند. پیش‌فرض + همان حالت سخت‌گیرانه است (هدرها باور نمی‌شوند). +3. **نبود سرآیندهای امنیتی و کوکی ناقص.** اضافه شد: `X-Content-Type-Options`، `X-Frame-Options: DENY` + (برنامه در قاب سایت دیگری جا نمی‌گیرد)، `Referrer-Policy`، `X-Robots-Tag` (ایندکس‌نشدن)، + `Permissions-Policy`، و سیاست محتوا (CSP) برای صفحه‌های خودمان. کوکی نشست هم روی مسیر HTTPS + پرچم `Secure` می‌گیرد و همچنان `HttpOnly` و `SameSite=Lax` است. + +لایهٔ سخت‌گیرانهٔ تازه (حتی بدون ایراد قبلی، برای اطمینان): نام پروندهٔ خروجی پاک‌سازی می‌شود و مسیر +نهایی پرونده حتماً باید داخل پوشه‌های مجاز باشد؛ وگرنه ۴۰۳. + +## ۴) آن‌چه **ادعا نمی‌کنم** + +1. **آدرس برنامه عمومی است.** هر کسی که نشانی را بداند، صفحهٔ ورود را می‌بیند (این عمدی است تا کارفرما + بتواند وارد شود). سپر اصلی، شناسه و رمز است؛ پس رمز کوتاه و ساده نگذارید. +2. **رمزها را خودتان می‌سازید.** اگر رمز ضعیف بگذارید، هیچ برنامه‌ای نمی‌تواند نجاتش دهد. کمینهٔ + نویسه رعایت می‌شود، ولی برای کارکنان همراه رمز به‌تری بدهید. +3. **ورود دولایه (۲FA) ندارد.** اگر لازم است، بگویید تا برای کاربران مدیر اضافه شود. +4. **اگر خودِ رایانه لو برود** (ویروس، دسترسی فیزیکی، پشتیبان بدون رمز)، هیچ‌چیز نرم‌افزاری جلویش را + نمی‌گیرد. پشتیبان‌ها را جدا و مطمئن نگه دارید. +5. **تونل موقت، تضمین پایداری ندارد.** برای نمایش و کار روزمره خوب است؛ برای «همیشه‌ باز» بودن باید + روی میزبان خودتان (رایانهٔ شرکت یا سرور) بالا بیاید. +6. **آزمون امنیتی، پایان‌ناپذیر است.** من ۲۲ حملهٔ شناخته‌شده را آزمودم و همه بسته بودند؛ این + «مصونیت کامل» نیست، «سطح حملهٔ کم و شناخته‌شده» است. + +## ۵) کارهایی که خودتان باید بکنید (سه دقیقه) + +1. رمز مدیر را از پیش‌فرض عوض کنید (پنل مدیریت، کارت ۴) و رمز تازه را جایی امن نگه دارید. +2. برای هر نفر کاربر جدا بسازید (نه یک رمز مشترک) تا اگر کسی رفت، همان لحظه حذفش کنید. +3. وقتی نمایش تمام شد، برنامه را خاموش کنید یا دسترسی کاربران کارفرما را قطع کنید. +4. آدرس را فقط به کسانی بدهید که باید ببینند؛ روی سایت یا گروه عمومی نگذارید. +5. اگر برنامه را روی میزبان همیشه‌باز بردید، آن‌جا هم HTTPS و رمزهای جدا لازم است (بستهٔ `deploy/` + همین را انجام می‌دهد). + +## ۶) پیوست: فرمان‌های بازتولید نتیجه‌ها + +```bash +cd MATERIALS/money/gui +python3 -m pytest tests/test_security.py -q # ۲۲ آزمون حمله — همه سبز +python3 -m pytest tests/test_users.py -q # ۱۸ آزمون کاربران +python3 -m pytest tests/test_guide.py -q # ۱۵ آزمون راهنمای کارفرما +STATION_GUEST_ID=... STATION_GUEST_PASS=... node /home/user/test-interactive.mjs # ۲۰۶ بررسی زنده +``` diff --git a/station/docs/21-positive-result-plan-fa.md b/station/docs/21-positive-result-plan-fa.md new file mode 100644 index 0000000000000000000000000000000000000000..009ad036e9883efecd50a9898789eceec40134bd --- /dev/null +++ b/station/docs/21-positive-result-plan-fa.md @@ -0,0 +1,74 @@ +# ۲۱ — چطور در ۱۴ روز به «نتیجهٔ مثبت» می‌رسی (برنامهٔ روزشمار) + +> این برگه پاسخ روشن یک پرسش است: «اگر امروز شروع کنم، کِی و از کجا بفهمم برنامه کار کرده؟» +> تاریخ: ۱ مهر ۱۴۰۵ (۲۲ سپتامبر ۲۰۲۶) · خواننده: مدیر شرکت · بدون اصطلاح فنی + +## ۱) «نتیجهٔ مثبت» دقیقاً یعنی چه؟ + +سه چیز، و هر سه‌شان امروز **قابل اندازه‌گیری** هستند: + +| نشانه | امروز چه وضعی دارد | از کجا ببینم | +| --- | --- | --- | +| تصمیم روشن روی هر نماد | ✔ آماده | جدول سیگنال‌ها در صفحهٔ اصلی: «بخر / نگه‌دار / بفروش / دست نزن» با دلیل و عدد | +| زنجیرهٔ شاهد سالم (هیچ سابقه‌ای دست‌کاری نشده) | ✔ آماده | دکمهٔ «کارنامهٔ آماده‌بودن» و ستون «شاهد» | +| آزمون سلامت برنامه | ✔ آماده | آزمون خودکار: همهٔ بخش‌ها سبز؛ گزارشش را می‌توانی چاپ کنی | + +آن‌چه **هنوز** تیک نخورده، این است: **«آماده» شدن کارنامه**. و این نه با پول و نه با هیچ +میان‌بُری نمی‌آید؛ فقط با روزهای واقعی. برنامه خودش این را سخت می‌گیرد — و همین سخت‌گیری همان +چیزی است که کارنامه را برای سرمایه‌گذار و برای خودت باورپذیر می‌کند. + +## ۲) پنج شرط کارنامه (همان‌ها که در برنامه دیده می‌شوند) + +۱. **ده روز ثبت‌شده** — هر روز یکی؛ ده بار در یک روز، «یک روز» حساب می‌شود. +۲. **دست‌کم پنج روز با دادهٔ واقعی بازار** — روزهایی که با عدد ساختگی پر شده باشند، شمرده نمی‌شوند. +۳. **شصت ثانیهٔ کار روزانه** برای هر روز ثبت‌شده (تاریخ، سه نماد، تصمیم، دلیل کوتاه). +۴. **سبز بودن آزمون سلامت** در همان روز. +۵. **جلسهٔ بازبینی** در پایان دوره. + +نکتهٔ صادقانه: آزمودم و دیدم ده بار پرکردن فرم در یک نشست، **یک روز** می‌شود و بس. پس کارنامهٔ +«آماده» یک‌شبه به دست نمی‌آید؛ کسی هم نمی‌تواند به تو بگوید به دست می‌آید. + +## ۳) برنامهٔ روزشمار (روزهای کاری) + +| روز | کار تو (چند دقیقه) | خروجی همان روز | +| --- | --- | --- | +| ۱ | ورود، نگاه به پنج کارِ روز اول، وصل‌کردن منبع داده، یک ثبت تمرینی | برنامه با عدد واقعی کار می‌کند؛ کارنامه: ۱ روز | +| ۲ | شصت ثانیه ثبت + خواندن تصمیم‌های روز | جدول تصمیم‌ها؛ اگر سیگنالی روشن باشد، تأیید یا ردّ تو ثبت می‌شود | +| ۳ | همان ثبت + یک بار «چرا این تصمیم؟» را ورق بزن | عادت شصت‌ثانیه‌ای پیدا می‌شود | +| ۴ | همان ثبت | کارنامه: ۴ روز | +| ۵ | همان ثبت + نگاه به ستون شاهد | مطمئن می‌شوی هیچ سابقه‌ای پاک/عوض نشده | +| ۶ | همان ثبت | — | +| ۷ | همان ثبت + **نیم‌نگاه به نتیجهٔ هفته** (جدول هفتگی) | می‌بینی کدام تصمیم بهتر بوده، با عدد نه با حس | +| ۸ | همان ثبت | — | +| ۹ | همان ثبت | — | +| ۱۰ | همان ثبت | **شرط اول کامل: ۱۰ روز** | +| ۱۱ | ثبت + بررسی روزهای واقعی | باید حداقل ۵ روزش با دادهٔ واقعی باشد | +| ۱۲ | ثبت | — | +| ۱۳ | ثبت + آماده‌کردن پرسش‌هایت برای جلسه | — | +| ۱۴ | ثبت + **جلسهٔ بازبینی** (بیست دقیقه) | کارنامه سبز یا فهرست روشن از آن‌چه مانده | + +اگر یک روز جا بماند، برنامه سرزنش نمی‌کند؛ فقط آن روز شمرده نمی‌شود و دوره همان‌قدر جلو می‌رود. + +## ۴) در جلسهٔ بازبینی چه می‌بینی؟ + +۱. کارنامه: چند روز ثبت‌شده، چند روز واقعی، وضعیت شاهد و آزمون. +۲. جدول تصمیم‌ها: هر تصمیم با دلیل و عدد پشتش (نه حدس، نه وعده). +۳. فهرست آن‌چه **کار نکرده** و چه چیزی لازم است — همان‌طور که هست، بدون گردکردن گوشه‌ها. +۴. تصمیم خودت: ادامهٔ دوره، تمدید بی‌هزینه، یا بس‌کردن. فشار و پیگیری خودکار وجود ندارد. + +## ۵) چهار چیزی که این برنامه **نیست** (تا انتظار غلط نسازی) + +۱. وعدهٔ سود نیست. هیچ عددی در آن «تضمین» نیست؛ همه‌چیز دلیل و سابقه دارد. +۲. سفارش خودکار نمی‌فرستد. خرید و فروش را تو تأیید می‌کنی؛ بدون تو هیچ سفارشی نمی‌رود. +۳. جای مشاور سرمایه‌گذاری نیست و مسئولیت تصمیم نهایی با خود توست. +۴. کارنامهٔ «آماده» جای ریسک را نمی‌گیرد؛ فقط می‌گوید «این برنامه روی دادهٔ واقعیِ خودت، + آن‌طور که باید، کار کرده است یا نه». + +## ۶) اگر خواستی همین امروز چیزی برای گفتن داشته باشی + +همین یک خط کافی است: «برنامه امروز روی نمادهای من، با عدد واقعی، تصمیم روشن می‌دهد و سابقهٔ +شاهد سالم دارد؛ برای برچسب «آماده» ده روز واقعی لازم است که از امروز شروع شده.» + +--- + +تهیه‌کنندهٔ جزوات: **Masoud Mojarabian** · ۰۹۱۲۶۶۳۰۵۵۴ · Telegram: [Mojarabian](https://t.me/Mojarabian) · Instagram: [Mojarabian.Art](https://instagram.com/Mojarabian.Art) diff --git a/station/docs/22-hf-live-deploy-fa.md b/station/docs/22-hf-live-deploy-fa.md new file mode 100644 index 0000000000000000000000000000000000000000..cb0a52823838caf1bc21dcde645aeea9d7544599 --- /dev/null +++ b/station/docs/22-hf-live-deploy-fa.md @@ -0,0 +1,151 @@ +# ۲۲ — برنامهٔ کامل روی Hugging Face (نه نمونه) — انجام شد + +> تاریخ: ۱ مهر ۱۴۰۵ (۲۲ سپتامبر ۲۰۲۶) · جواب به: «کارفرما به Hugging Face دسترسی دارد؛ همه را همان‌جا بگذار و نمونه نمی‌خواهم، برنامهٔ کامل و واقعاً اجرایی» +> +> **نشانی برنامهٔ زنده:** `https://delaris-desk-live.hf.space` · راهنمای کارفرما بدون ورود: `/guide` + +## ۱) کوتاه + +**انجام شد.** خودِ برنامه — نه نمونه — روی Hugging Face بالا است و از بیرون آزموده شد: **۱۴ بررسی، ۱۴ سبز**، +به‌علاوهٔ دادهٔ زندهٔ واقعی («زنده (۰ ثانیه پیش)» با ۷ ردیف از منبع رایگان tgju). + +دو حساب همان‌های امروز است: مدیر `mafhoom` / `Smm@1101001` · کارفرما `masoud` / `09126630554`. +رمزها در **Secrets** خود Space نشسته‌اند (نه در مخزن، نه در پرونده). + +## ۲) چه چیزی سر راه بود و چه‌کار شد + +| مانع واقعی | چطور حل شد | +| --- | --- | +| HF روی حساب مجانی، ساخت Space **داکری** را با ۴۰۲ رد می‌کند | قالب **گرادیو** انتخاب شد | +| Space گرادیو روی سخت‌افزار معمولی هم «Paid» است | سخت‌افزار **ZeroGPU** (دو Space مجانی برای هر حساب شخصی) | +| موتور ZeroGPU هنگام روشن‌شدن دنبال تابع `@spaces.GPU` می‌گردد و بی‌آن، Space را با خطا می‌بندد (آزمودیم: «No @spaces.GPU function detected») | یک **پوستهٔ کوچک گرادیو** با یک «قلاب گرافیک» که هیچ‌وقت صدا زده نمی‌شود؛ خودِ برنامه CPU-only است | +| HF برای هر «کامیت» سهمیه دارد (**۱۲۸ در ساعت**) و آپلود پرونده‌به‌پرونده سهمیه را سوزاند | آپلود با **یک `git push`** (نه صدها درخواست) | +| کارساز ما HTTP خام است و پوستهٔ گرادیو درگاه ۷۸۶۰ را می‌خواهد | ایستگاه روی `127.0.0.1:8790` بالا می‌آید و پوسته **همهٔ** درخواست‌ها را بی‌کم‌وکاست به آن می‌دهد (کد، کوکی، سرآیند، ریدایرکت) | +| ضدجعل درخواست (CSRF) پشت پروکسی HF گیر می‌کرد | متغیر `STATION_ALLOW_HOSTS` فقط نام عمومی Space را می‌پذیرد؛ میزبان بیگانه هنوز ۴۰۳ می‌گیرد | +| دیسک Space مجانی بادوام نیست (بعد از خواب، پرونده‌ها پاک می‌شوند) | نگهبان وضعیت: هر ۵ دقیقه و پیش از خواب، وضعیت در **مخزن دادهٔ خصوصی** `delaris/desk-state` پشتیبان می‌شود و سر بوت برمی‌گردد | +| ممکن بود نسخهٔ پشتیبان، «خوراک آزمایشی محلی» را برگرداند و قیمت‌ها بیفتد | تابع `ensure_connection()` پیش از روشن‌شدن، اتصال را روی **منبع واقعی رایگان** (`tgju-usd`) می‌گذارد | +| سندهای چاپی (`/files/walkthrough` و مانند آن) در بسته نبودند و ۴۰۴ می‌دادند | پوشهٔ `station/docs/` به بسته اضافه شد (۲۳ سند) | + +## ۳) نتیجهٔ آزمون از بیرون (همین حالا) + +| بررسی | نتیجه | +| --- | --- | +| صفحهٔ ورود | ۲۰۰ | +| راهنمای کارفرما بدون ورود | ۲۰۰ | +| خروجی‌ها بدون ورود | ۴۰۱ (بسته) | +| صفحهٔ نخست بی‌ورود | ۳۰۲ → ورود | +| ورود کارفرما | ۲۰۰ | +| صفحهٔ اصلی کارفرما | ۲۰۰ | +| سیگنال‌ها برای کارفرما | ۲۰۰ | +| راهنمای گام‌به‌گام تازه‌کار | ۲۰۰ | +| پنل مدیریت برای کارفرما | ۴۰۳ (بسته) | +| ورود مدیر و پنل | ۲۰۰ / ۲۰۰ | +| بررسی سلامت با توکن پنل | ۲۰۰ | +| دادهٔ زندهٔ بازار | «زنده (۰ ثانیه پیش)» · ۷ ردیف · منبع رایگان | + +فرمان بازتولید همین آزمون: `bash deploy/huggingface-live/verify_live_space.sh` + +## ۴) آن‌چه باید بدانی (بی‌تعارف) + +۱. **یک تا دو دقیقهٔ اول** پس از هر روشن‌شدن، صفحهٔ پوستهٔ HF دیده می‌شود؛ بعد از آن، خودِ برنامه + روی `/` می‌نشیند. اگر کسی همان لحظه آدرس را زد، چند ثانیه بعد دوباره بزند. +۲. **خواب بعد از ۴۸ ساعت بی‌بیننده**: Space می‌خوابد؛ با اولین بازدید بیدار می‌شود (حدود یک دقیقه) و + کاربران و ثبت‌ها از نسخهٔ پشتیبان خصوصی برمی‌گردند. +۳. **این جای مجانی، جای «دموی گرافیکی» است.** ما آن را برای یک برنامهٔ CPU-only باز کرده‌ایم؛ تابع + گرافیک عمداً کاری نمی‌کند. رعایت ادبش این است که بار سنگین روی آن نگذاریم (این برنامه بار سبکی دارد). + سیاست HF ممکن است عوض شود؛ برای همین دو راه پشتیبان نفس‌گیر نشده‌اند: Render مجانی و رایانهٔ خودت. +۴. **رمزها دست خودت است.** هر وقت خواستی، در Settings → Variables and secrets عوض کن؛ هر وقت + خواستی دسترسی کارفرما را قطع کنی، پنل مدیریت → کارت کاربران. +۵. **توکن** بعد از کار، از `settings/tokens` پاک شود (نمونه و Space هر دو مستقل کار می‌کنند). + +## ۵) چه چیزی روی HF هست و چه چیزی نیست + +| | `desk-live` (برنامهٔ کامل) | `desk-demo` (نمونهٔ ثابت) | +| --- | --- | --- | +| نشانی | `delaris-desk-live.hf.space` | `delaris-desk-demo.static.hf.space` | +| ورود | دروازهٔ واقعی، دو حساب | ندارد | +| داده | زنده + عددهای خودت | ضبط‌شده | +| کد | همه در `station/` | نه | +| نقش | **برنامهٔ اصلی** | کارت ویزیت و پشتیبان نمایش | + +صفحهٔ نخست نمونه هم اکنون به برنامهٔ زنده پیوند دارد. + +## ۶) بسته‌ها (بازساخته با همین کد) + +| بسته | پرونده | حجم | zip (تقریبی — هر ساخت چند کیلوبایت جابه‌جا می‌شود) | +| --- | --- | --- | --- | +| `iran-desk-live` (برنامهٔ زندهٔ روی HF) | ۱۴۹ | ۲۳۰۰ کیلوبایت | ≈۷۳۹ کیلوبایت | +| `iran-desk-kit` (بستهٔ شرکت) | ۱۸۸ | ۳۳۸۳ کیلوبایت | ≈۹۷۶ کیلوبایت | +| `iran-desk-backpack` (کوله‌پشتی + پایتون قابل‌حمل) | ۲۴۹ | ۲۵۰۵۰ کیلوبایت | ≈۱۱٫۸ مگابایت | +| `iran-desk-hf` (نسخهٔ داکری/Render) | ۱۲۹ | ۲۲۰۰ کیلوبایت | ≈۷۱۶ کیلوبایت | +| `iran-desk-demo` (نمونهٔ ثابت) | ۱۸ | ۱۰۲۵ کیلوبایت | ≈۱۶۷ کیلوبایت | + +جمع آزمون‌های درخت اصلی: **۶۹۱ سبز · ۱ رد · ۰ خطا** (شامل ۲۹ آزمون مخصوص همین کار). + +## ۷) وضعیت پایانی و درس‌های واقعی این کار + +| سنجه | عدد پایانی | +| --- | --- | +| نشانی برنامهٔ زنده | `https://delaris-desk-live.hf.space` (RUNNING) | +| آزمون از بیرون (`verify_live_space.sh`) | **۱۴ از ۱۴** | +| سلامت اجزا روی Space | **۸ از ۸** | +| آزمون درون‌برنامه (۱۰ دقیقه‌ای) | **۱۵ از ۱۵** | +| آزمون تعاملی واقعی (`test-interactive.mjs`) | **۲۰۶ موفق · ۰ ناموفق** | +| گزارش عیب‌یابی (`/api/admin/diagnose`) | `ok:true` · آزمون‌ها سبز · «OK (skipped=107)» | +| دادهٔ زندهٔ بازار | ۷ ردیف از tgju («زنده (۰ ثانیه پیش)») | + +سه نکته که در همین کار به‌دست آمد و برای آیندهٔ نگه‌داشت لازم است: + +۱) **بستهٔ تحویلی و آزمون‌ها نباید به ابزار ساخت نیاز داشته باشند.** پوشهٔ `deploy/` عمداً داخل +بستهٔ شرکت نیست؛ پس هر آزمونی که به آن وابسته است باید «نگهبان بستهٔ تحویلی» داشته باشد و +در نبود ابزار تمیز رد شود. وگرنه پنل «گزارش عیب‌یابی» به کاربر دروغ می‌گوید (سرخ نشان می‌دهد). + +۲) **هر پیوند پایگاه‌داده باید بسته شود.** `Store` و `Desk` پیوند را در سازنده باز می‌کردند و +نمی‌بستند؛ در سرور همیشه‌روشن این یعنی انباشت پیوند و در آزمون‌ها یعنی هشدار پایان کار. + +۳) **روی میزبان دور، آزمون باید رفتار کاربر واقعی را بسنجد.** خوراک آزمایشی محلی +(`mock-local`) روی اینترنت وجود ندارد؛ پس آزمون تعاملی حالا منبع واقعی رایگان (`tgju-usd`) +را انتخاب می‌کند و همان ۲۰۶ بررسی محلی، از بیرون هم سبز می‌شود. + +## ۸) نگهبانِ دیدنی و آزمون جان‌سختی (کارِ بعدی روی همان Space) + +مشکلی که حل شد: قبلاً نگهبان وضعیت کار می‌کرد ولی **دیده نمی‌شد** — کاربر (و مدیر) هیچ‌جا نمی‌دید +آخرین پشتیبان کِی بوده، چه چیزی زیر نگهبانی است، و اگر لازم شد خودش می‌توانست یکی بگیرد یا نه. +پس: + +- در پنل مدیر، بخش تازهٔ **«پشتیبان ابری وضعیت (نگهبان همیشه‌روشن)»** اضافه شد: تعداد پرونده‌های + زیر نگهبانی، حجم، فاصلهٔ پشتیبان‌گیری، **زمان آخرین پشتیبان**، تعداد پرونده‌های برگشته سرِ روشن‌شدن، + و نام مخزن خصوصی. دو دکمه هم دارد: «نمایش وضعیت نگهبان» و **«پشتیبان‌گیری الان»**. +- نشانی‌های تازه: `GET /api/admin/state` و `POST /api/admin/backup` (هر دو فقط با توکن پنل مدیر؛ + بی‌توکن ۴۰۳). روی رایانهٔ خودِ کاربر که نگهبان نیست، همان مسیر **صادقانه «خاموش»** می‌گوید، نه خطا. +- **یادداشت «آخرین پشتیبان» داخل خودِ بستهٔ پشتیبان** می‌رود (`station/data/keeper-last.json`)، + وگرنه پس از خواب یا ری‌استارت، پنل نمی‌توانست بگوید آخرین پشتیبان کِی بوده. + +**آزمون جان‌سختی (چهار بار ری‌استارت واقعی از API هوگینگ‌فیس):** هر بار Space در ۳۰–۴۰ ثانیه +`RUNNING` شد، و نگهبان سرِ بوت وضعیت را برگرداند: + +``` +[23:05:44] 38 پرونده از نسخهٔ پشتیبان برگشت. +[23:05:44] دروازه روشن است · حساب‌ها از وضعیت بازگردانده‌شده خوانده شدند +پنل: آخرین پشتیبان 2026-09-22 23:05:28 · 38 پرونده · 78 کیلوبایت · «درخواست مدیر از پنل · دورهٔ پیش» +مخزن: delaris/desk-state → state.zip = 80,124 بایت +``` + +یعنی: کارِ کاربر (شماره‌های کارگزاری، روزهای ثبت‌شده، خروجی‌های چاپی) روی میزبان مجانی +**از خواب/ری‌استارت جان سالم می‌برد**؛ و اگر مدیر بخواهد، با یک دکمه نسخهٔ تازه می‌گیرد. + +### به‌روز کردنِ بعدی (برای خودت یا هر وقت کسی خواست بازساز کند) + +``` +cd MATERIALS/money/gui +python3 deploy/huggingface-live/make_live_space.py --zip # ساخت بسته و zip +python3 -c "import sys; sys.path.insert(0,'deploy/huggingface-live');import activate_live_space as A; print(A.skippable('station/data/x.sqlite3'))" # فیلتر آپلود +# کپی بسته در کلون /tmp/space-git (فقط پرونده‌های مجاز) و: git add -A && git commit && git push +sleep 90 # Space پس از هر push یک تا دو دقیقه گرم می‌شود؛ زودتر آزمون نگیر +bash deploy/huggingface-live/verify_live_space.sh https://delaris-desk-live.hf.space +``` + + +--- + +تهیه‌کنندهٔ جزوات: **Masoud Mojarabian** · ۰۹۱۲۶۶۳۰۵۵۴ · Telegram: [Mojarabian](https://t.me/Mojarabian) · Instagram: [Mojarabian.Art](https://instagram.com/Mojarabian.Art) diff --git a/station/docs/README-FA.md b/station/docs/README-FA.md new file mode 100644 index 0000000000000000000000000000000000000000..976aa36a9252531f769ef0d2ed7d272baab0247d --- /dev/null +++ b/station/docs/README-FA.md @@ -0,0 +1,86 @@ +# پوشهٔ «پول» — مشتقه و مسیرهای درآمد در ایران + +این پوشه پاسخ دو درخواست صاحب پرونده است: (۱) تحقیق روی خرید و فروش اوراق مشتقه در ایران و ساختن فلوچارت و الگوریتمی که «بدون شانس، فقط با ریاضیات» بگوید چه بخر و چه بفروش، با درصد سود و موفقیت؛ (۲) فهرست مسیرهای درآمد سالم در ایران با درصد موفقیت هر مسیر. + +## فایل‌ها + +| فایل | چیست | +|---|---| +| `01-derivatives-iran-fa.md` | پروندهٔ پژوهشی مشتقه: نقشهٔ بازار و قوانین واقعی، جعبه‌ابزار ریاضی، شش استراتژی با درصد موفقیت، فلوچارت تصمیم روزانه، شبه‌کد الگوریتم غربال، مدیریت سرمایه، طرح اعتبارسنجی ۳۰ روزه | +| `02-ideas-iran-fa.md` | چهارده مسیر درآمد سالم با سرمایهٔ کم تا متوسط، پنج عدد سنجش برای هر مسیر، سه مسیر برتر برای شروع، هفت قاعدهٔ طلایی، برنامهٔ ۹۰ روزه | +| `03-investor-and-first-money-fa.md` | بستهٔ سرمایه‌گذار و اولین پول: سه واقعیت پیش از هر ایده، پنج مسیر قانونی جذب سرمایه (تسهیلات مشاغل خانگی، پیش‌فروش، مضاربه، شریک تجهیزاتی، شریک مکمل)، ساختار توجیه سرمایه‌گذاری یک‌صفحه‌ای، متن نمونهٔ پیشنهاد و پاسخ پنج مخالفت رایج، «اولین پول در ۱۴ روز» و قرمزها | +| `04-trading-desk-plan-fa.md` | نقشهٔ عملیاتی «میز معاملات» برای یک شرکت سرمایه‌گذاری: سه واقعیت پیش از قرارداد (ممنوعیت معاملات الگوریتمی در ایران)، نقشهٔ منابع داده، معماری هشت‌لایه، پنج فاز تحویل، «چه قول بدهیم و چه ندهیم»، چهار بند حیاتی قرارداد، ایده‌های بهتر با درصد موفقیت، و سه عامل مرگ پروژه | +| `05-data-routes-fa.md` | بررسی سه مسیر داده پیش از هر خرید: سرویس رسمی پولی، سرویس‌های عمومی رایگان، و پوش لحظه‌ای کارگزاری. جدول تطبیق با نیاز ایستگاه (از جمله وجه تضمین که هیچ سرویس داده‌ای نمی‌دهد)، قاعدهٔ سه‌شرطی خرید، و چک‌لیست پیش از امضای هر خرید | +| `06-data-feasibility-fa.md` | «چطور بسنجیم و چه بخریم»: چهار پرسش عددی برای هر مسیر داده، دستورهای سنجش، نیاز واقعی موتور و آن میدانی که هیچ فروشنده‌ای نمی‌دهد (وجه تضمین)، رفتار ایستگاه با دادهٔ گپ‌دار و کهنه، برگهٔ استعلام قیمت از فروشنده، و دروازهٔ سه‌شرطی خرید | +| `12-wealth-math-and-no-purchase-fa.md` | جواب صادقانه به «با ریاضی می‌شود ثروتمند شد؟»: ایده‌های جدید با درصد، شوک‌آزمون ایده‌های قبلی، ریاضیِ بقا و زمان، «چه چیزی لازم نیست بخرید» (از جمله Jev)، و پروتکل اثبات ارزش به سرمایه‌گذار با هزینهٔ صفر | +| `delivery/` | **سه بستهٔ تحویلی**: (۱) `iran-desk-kit` (بستهٔ تحویل شرکت): پوشهٔ تمیزی از کد، قالب‌ها، جزوه و اسناد که روی هر رایانه‌ای با پایتون اجرا می‌شود و در آن هیچ گزارش یا دفترِ ازپیش‌ساخته‌ای نیست — همه روی رایانهٔ خودشان از صفر ساخته می‌شود · (۲) `iran-desk-demo` + `iran-desk-hf`: **نمونهٔ ثابت نمایشی** (خروجی‌های واقعی ضبط‌شده، بی‌سرور و بی‌اینترنت) و بستهٔ میزبانی آن روی HF Static Space · (۳) `iran-desk-backpack`: **کوله‌پشتی دمو** — پوشهٔ خودکفا با دو اسکریپت ویندوز/لینوکس (نمونهٔ ثابت روی همان دستگاه + برنامهٔ زنده روی وای‌فای جلسه)، رمزسازی اولین اجرا، و (اختیاری) پایتون قابل‌حمل ویندوز؛ **بدون هیچ نیاز به اینترنت** · فهرست و اثر انگشت هر پرونده در `KIT-MANIFEST.json`/`BACKPACK-MANIFEST.json` · بازساخت با `gui/make_kit.py` و `gui/make_backpack.py` | +| `14-first-meeting-fa.md` | «از صفر تا اولین جلسه (و اولین پول)»: مسیر در شش دروازه، هفت کانال با هزینهٔ صادقانه، ریتم هفتگی، جلسهٔ نیم‌ساعته با ساعت، دو پیام بعد از جلسه، و سه اشتباهی که جلسهٔ بعدی را می‌سوزاند — بدون هیچ عدد درآمدی | +| `15-after-meeting-fa.md` | «بعد از جلسه»: سه دروازه (بله · بعداً · نه)، پنج کار روز اول مشتری، دو هفته‌ای که هیچ‌چیز خریده نمی‌شود، شرط‌های کارنامهٔ «آماده» و روز بازبینی، قاعدهٔ پرداخت در برابر شاهد، و سه اشتباهی که قرارداد را می‌سوزاند — بدون هیچ عدد درآمدی | +| `16-review-meeting-fa.md` | «جلسهٔ بازبینی دو هفته‌ای»: بیست دقیقه دقیقه‌به‌دقیقه، سه شاهد و مرزِ هر شاهد («چه چیزی را نشان نمی‌دهد»)، پنج شرط کارنامه، دو خروجی (ادامه با پرداخت / توقف بی‌گلایه‌مندی)، چهار پرسش سخت با جواب صادقانه، پیگیری تاریخ‌دار، و سه اشتباهی که قرارداد را می‌سوزاند — بدون هیچ عدد درآمدی | +| `17-remote-access-fa.md` | «دسترسی از راه دور برای کارفرما»: چرا دروازهٔ ورود لازم است، راه‌اندازی سه‌فرمانی، جدول «کارفرما چه می‌بیند و چه نمی‌تواند»، دو مسیر آدرس دادن (پل موقت امروز، سایت ثابت بعداً)، چک‌لیست پنج‌دقیقه‌ای پیش از جلسه، مرزهای صادقانه (داده از رایانه بیرون نمی‌رود · دروازه جای امنیت بانکی نیست) و پیوست پرونده‌ها | +| `18-client-value-fa.md` | «خروجی‌ها برای کارفرما چه می‌کنند و چه فرقی با برنامه‌های دیگر دارند»: جدول دوازده خروجی با «چه چیزی را نشان نمی‌دهد»، سه استفادهٔ عملی، جدول تفاوت با ابزارهای رایج فارسی، مرزهای صادقانه، ده دقیقهٔ دمو دقیقه‌به‌دقیقه، پاسخ سه پرسش سخت کارفرما، و پیوست «کدام فایل، کدام فرمان» | +| `22-hf-live-deploy-fa.md` | **برنامهٔ کامل روی Hugging Face — انجام‌شده**: نشانی زنده `delaris-desk-live.hf.space`، آزمون ۱۴ از ۱۴ از بیرون، سلامت ۸ از ۸، آزمون درون‌برنامه ۱۵ از ۱۵، آزمون تعاملی ۲۰۶ از ۲۰۶، دادهٔ زندهٔ tgju، پوستهٔ گرادیو/ZeroGPU و علت‌هایش، نگهبان وضعیت در مخزن خصوصی، و آن‌چه صادقانه باید بدانی (خواب ۴۸ ساعته، گرم‌شدن یک‌دقیقه‌ای) | +| `21-positive-result-plan-fa.md` | **برنامهٔ روزشمار نتیجهٔ مثبت**: «نتیجهٔ مثبت» یعنی چه (سه نشانهٔ امروز + یک برچسب که فقط با روز واقعی می‌آید)، پنج شرط کارنامه، جدول چهارده روزه با خروجی هر روز، آن‌چه در جلسهٔ بازبینی دیده می‌شود، و چهار چیزی که برنامه نیست | +| `20-security-review-fa.md` | **بررسی امنیتی «می‌شود هک کرد؟»**: ۲۲ حملهٔ واقعی به نسخهٔ در حال اجرا (پیمایش مسیر، کوکی جعلی، بالا رفتن از نقش کارفرما، CSRF، بدنهٔ غول‌آسا، تلاش پی‌درپی رمز)، سه ایراد واقعی که پیدا و بسته شد، و پنج چیزی که صادقانه ادعا نمی‌کنم | +| `19-demo-offline-decision-fa.md` | **تصمیم «نمایش آفلاین»**: چرا در اینترنت محدود ایران ستون فقرات نمایش نباید به هیچ لینک خارجی گره بخورد (سه شاهد بیرونی)، جدول مقایسهٔ سه راه نمایش با شرایط واقعی، محتوای کوله‌پشتی، شرایط نمایش (رمز، داده، دو صداقتی که در جلسه گفته می‌شود، پورت)، و سه مسیر «راه زندهٔ کامل» با ترتیب هزینه | +| `13-novice-walkthrough-fa.md` | راهنمای هر بخش برای کاربر تازه‌کار با نام واقعی دکمه‌ها، جدول «گرفتن اعداد از کارگزاری»، **نقشهٔ صادقانهٔ اتوماسیون** (چه خودکار است و چه هرگز نمی‌شود)، نُه ترمز ضد خطای انسانی، تمرین ده‌دقیقه‌ای روز اول، و جدول «علامت ← معنا ← کارِ شما» | +| `11-usage-and-percent-fa.md` | ایدهٔ «شمارش استفادهٔ موفق و درصدگرفتن»: چه چیزی قابل شمردن است، چرا «درصد از سود» قابل اثبات و توصیه‌شدنی نیست، مدل قابل دفاع «درصد کوچک از هزینهٔ پرهیزشده با شاهد»، سه مدل با سود و زیان، و حریم خصوصی به‌عنوان برگ برندهٔ فروش | +| `10-daily-inputs-fa.md` | ورودی روزانه: ده عدد لازم، محل مجانی هر عدد (تابلوی کارگزاری و سایت‌های عمومی)، فیلدهای هر نوع معامله، چهار راه دادن داده با هزینهٔ صادقانه، شصت ثانیهٔ روزانه با نام دکمه‌های واقعی برنامه، و آنچه هرگز وارد نمی‌شود | +| `09-sell-or-grant-access-fa.md` | بفروشم یا دسترسی بدهم؟ سه راه با سود و زیان واقعی، جملات آماده برای گفتن به کارفرما، چهار کار برای برداشتن بار پشتیبانی از دوش کاربر، دلیل عمر طولانی برنامه بدون به‌روزرسانی و پاسخ به «لحظهٔ ترند یک فناوری تازه»، و واقعیت صادقانهٔ درآمد تکرارشونده | +| `08-differentiation-and-trust-fa.md` | تمایز و اعتماد: جدول صادقانهٔ «بازار فارسی چه دارد و چه ندارد»، هشت نقطهٔ قوت با شاهد و دموی یک‌کلیکی (بولدترین: داوری سیگنال ابزار دیگران)، معماری هفت‌لایهٔ اعتماد، پروتکل پذیرش پنج‌پله‌ای، اقتصاد و مدل قیمت سه‌پله‌ای، سه پرسش جلسهٔ شرکت و پاسخ آماده | +| `07-zero-cost-test-fa.md` | پاسخ «باید چیزی بخریم؟»: چرا Jev لازم نیست، سه مسیر تست با هزینهٔ صفر (خوراک آزمایشی محلی، دادهٔ واقعی رایگان، اعداد کارگزاری با دست)، معرفی آزمون کور سرمایه‌گذار، و پروتکل ده‌روزهٔ تست عملیاتی بیهزینه | +| `gui/` | **ایستگاه تصمیم مشتقه** (نسخهٔ ۰٫۲٫۰): رابط گرافیکی یازده‌گامی: مرورگری (`web_server.py`) و دسکتاپ (`station.py`)؛ لایهٔ دادهٔ سه‌حالته (نمونه · پروندهٔ دستی · زندهٔ واقعی با قالب نشانی و مسیر JSON)، پس‌آزمای روی دادهٔ تاریخ با آزمون ضد آینده‌نگری، و ساخت «بستهٔ راستی‌آزمایی» برای شرکت (سند مجوز و گواهی استفاده هم خودکار داخل بسته می‌روند) · `connections.py` (دفتر اتصال با ذخیرهٔ خودکار و کاوشگر پاسخ سرویس) · `mock_feed.py` (خوراک آزمایشی محلی بدون هزینه) · `live_trial.py` (دفتر آزمون زنده با زنجیرهٔ هش) · `daily_trial.py` (مراسم روزانه یک‌دکمه‌ای + کارنامهٔ آمادگی پنج‌شرطی) · `autoconnect.py` (پیدا کردن خودکار منبع رایگان سالم + حلقهٔ کد نماد) · `selftest.py` (آزمون ۱۰ دقیقه‌ای: ۱۵ مورد، هر کدام دو بار (موتور و حساب دستی مستقل) + برگهٔ آزمون چاپی) · `dossier.py` (پروندهٔ سرمایه‌گذار: نه بخش شاهددار با اثر انگشت sha256 هر پرونده) · `data_sources.py` (امکان‌سنجی مسیرهای داده پیش از خرید: شش نشانی، سنجش تازگی با دو فراخوانی، سنجش پوش لحظه‌ای، برگهٔ نیاز داده) · `investor_test.py` (آزمون کور سرمایه‌گذار: شش پرسش با پاسخ محاسبه‌شده، جدول آستانهٔ ریزش، حساب‌رسی معاملهٔ گذشته، برگهٔ امضادار زنجیره‌هش‌دار، سند پلهٔ تصمیم برای خرید و فروش و افتادن، و پیمان‌نامهٔ نمایش دواِمضا) · `snapshot_import.py` (چسباندن اعداد کارگزاری: رقم فارسی، جداکنندهٔ هزارگان، سرستون، تشخیص راهبرد) · `usage_meter.py` (گواهی استفادهٔ موفقِ محلی و زنجیره‌هش‌دار با دو امضا) · `license.py` (اجازه‌نامهٔ دسترسی نام‌دار با امضای sha256 + سه پلهٔ ارائه + سند چاپی دواِمضا) · `offer.py` (برگهٔ «پیشنهاد یک‌صفحه‌ای» برای دست دادن به شرکت) · `outreach.py` (چهار متن آماده + اسکریپت تماس + پاسخ چهار مخالفت، برای گرفتن جلسهٔ نیم‌ساعته) · `onboarding.py` (برگهٔ «روز اول مشتری»: پنج کار روز اول، دو هفته بدون خرید، شرط‌های کارنامه، و روز بازبینی که از خود کد خوانده می‌شود) · `prospects.py` (تابلوی پیگیری مخاطبان: پنج نام در هفته، قاعدهٔ پیگیری ۰/۳/۱۰ قفل‌شده در کد، سه عدد هفته، برگهٔ چاپی؛ یادداشت‌ها با ماسک شماره و عدد) · `sales_ritual.py` (مراسم بیست‌دقیقه‌ای فروش: از تابلو و بستهٔ پیام‌ها، یک برگهٔ اجرایی برای امروز با سقف پنج پیام و بودجهٔ بیست دقیقه؛ هر چه جا نشد، فردا) · `review_meeting.py` (برگهٔ «جلسهٔ بازبینی دو هفته‌ای»: سه شاهد که خودشان می‌سازند، پنج شرط کارنامه، دو خروجی روشن، و پیگیری تاریخ‌دار اگر تصمیم نگرفتند) · `diagnose.py` (گزارش عیب‌یابی یک‌کلیکی برای پشتیبانی) · `strategy_audit.py` (جزوهٔ ۸ راهبرد با درصد و برچسب روش، قاعدهٔ بستن، و حسابرسی دو-روشی) · `edge_stress.py` (شوک‌آزمون: لغزش اجرا، حرکت مخالف، کارمزد دو و سه برابر، نرخ سد ۴۵٪ + تحمل کارمزد و فاصله تا مارجین‌کال) · `bankroll.py` (ریاضیِ کِلی، احتمال نیم‌شدن حساب با شبیه‌سازی، و مسیر رشد تا هدف) · `signal_judge.py` (داوری سیگنال ابزارهای دیگر: می‌ماند/می‌افتد با دلیل دروازه‌ها، نقطهٔ برگشت، فاصله تا مارجین‌کال با حد نگهداری ۷۰٪، دو روش حساب، اثر انگشت) · `adminauth.py` + `web/admin.html` (پنل مدیریت با ورود شناسه/رمز: بررسی سلامت، مجوز دسترسی و گزارش عیب‌یابی، گواهی استفادهٔ موفق؛ رمز فقط هش‌شده) · `DEMO-INVESTOR-FA.md` (سناریوی دموی بیست‌وپنج‌دقیقه‌ای + بخش «چطور اثبات کنیم») · `web/guide.html` (**راهنمای کارفرما**: یازده بخش، بی‌زبان فنی و بی‌فرمول؛ از روز اول تا جلسهٔ بازبینی، جدول پیام‌های خطا، بیست پرسش پرتکرار، حریم خصوصی، و پشتیبانی؛ بدون اینترنت هم باز می‌شود) · `gate.py` + `web/login.html` (دروازهٔ ورود برنامه: نقش مدیر برای صاحب برنامه و نقش **مهمان** برای کارفرما، نشست هشت‌ساعتهٔ PBKDF2، قفل پنج خطا، بستن نشست مهمان به‌یک‌فرمان؛ خاموش‌کردن برنامه و پنل مدیریت فقط دست مدیر) · `share/` (اسکریپت‌های «لینک دادن به کارفرما»: تونل امن + کلید خاموشی + راهنمای تازه‌کار) · `deploy/huggingface/` + `make_hf.py` + `activate_hf.py` + `activate_demo_site.py` (بستهٔ **میزبان مجانی**: [`Hugging Face Spaces`](https://huggingface.co/new-space) با `Dockerfile` درگاه ۷۸۶۰، کارت Space، `boot.sh` که از متغیرهای محیطی دو حساب می‌سازد و دروازه را روشن می‌کند، · `activate_hf.py` (با یک توکن، خودش Space می‌سازد، پرونده‌ها را بالا می‌گذارد، رمزها را می‌نشاند، تا `RUNNING` شدن می‌پرسد و چهار عدد دروازه را از بیرون می‌آزماید) · **نمونهٔ ثابت نمایشی روی HF Static Space** (`make_demo_site.py` + `tools/record_static_demo.mjs` ضبط پاسخ‌های واقعی + `tools/check_demo_site.mjs` ۲۲ بررسی زنده) · `SIGNUP-FA.md` (راهنمای ثبت‌نام گام‌به‌گام) · `security_scan.py` (اسکن «مقدار شبیه رمز» برای بسته‌های عمومی) · و `render.yaml` برای میزبان دوم؛ بدون کارت بانکی، بدون سرور) · `deploy/` (بردن روی سایت با **یک فرمان**: `deploy.sh` (بازبینی → راه‌اندازی → ساخت رمزها → روشن‌کردن دروازه → چهار آزمون دروازه → چاپ آدرس) + `preflight.sh` (بازبینی سرور: پایتون، داکر یا systemd، درگاه، دیسک، DNS دامنه) + `setup-domain.sh` (نشاندن دامنه با پشتیبان‌گیری) + `Dockerfile`، compose، Caddy برای HTTPS خودکار، service برای systemd، `install-backup.sh` (نصب یک‌فرمانی پشتیبان روزانه: cron یا تایمر systemd) + `backup.sh` (گرفتن، `--verify`، `--list`) + `restore.sh` (بازگردانی با کنترل اثر انگشت، پشتیبان امن پیش از بازنویسی، و `--check`)، و راهنمای فارسی با بخش‌های «خاموش کردن و حذف کامل» و «پشتیبان‌گیری و بازگردانی») · ۶۵۸ آزمون واحد + آزمون ساخت رابط گرافیکی + ۱۹۲ بررسی تعاملی مرورگری | +| `strategies/` | **جزوهٔ راهبردها** (نسخهٔ ۰٫۱٫۰): هشت راهبرد با درصد امروز، برچسب روش عدد، قاعدهٔ بستن موقعیت، ریسک‌ها، منابع، و حسابرسی دو-روشی · `strategy-library-fa.md` · `strategy-library.html` (چاپی) · `references-fa.md` · `README-FA.md` | +| `desk/` | **میز معاملات** (نسخهٔ ۰٫۱٫۰): اسنپ‌شات بازار را روی موتور ریاضی می‌گذارد، هشدارهای دیده‌بان کدال را می‌چسباند، دروازه‌های ریسک را اعمال و اندازهٔ موقعیت را از بودجهٔ وجه تضمین درمی‌آورد، داشبورد تصمیم می‌سازد و «بستهٔ سفارش» برای اجرای انسانی چاپ می‌کند. بدون ارسال هیچ سفارشی (الزام قانونی) · ۲۶ آزمون واحد · صفر وابستگی | +| `kodal-alert/` | **دیده‌بان کدال و خبر** (نسخهٔ ۰٫۱٫۰): برنامهٔ فارسی و بدون وابستگی بیرونی که اطلاعیه‌های کدال و خبر بازار را می‌خواند، دسته‌بندی و امتیازدهی می‌کند، دلیل اهمیت هر خبر را می‌گوید، گزارش HTML می‌سازد و در صورت نیاز به تلگرام یا بله هشدار می‌فرستد. شامل `demo/`، `tests/` (۲۶ آزمون) و پرونده‌های اجرای ویندوز | +| `tools/derivatives_scout.py` | دیده‌بان ریاضی بازار مشتقه: پایهٔ آتی، تساوی پوت‌کال، باکس اسپرد، بازده تضمینی تبعی، پوشش‌داده‌شده، اندازهٔ موقعیت و امتیازدهی | +| `tools/test_derivatives_scout.py` | ۲۰ آزمون واحد برای همان ابزار | + +## اجرا + +```bash +cd MATERIALS/money/tools +python3 derivatives_scout.py --self-test # خودآزمون ریاضی (۶ بررسی) +python3 derivatives_scout.py --demo # سناریوی نمونه با اعداد فرضی +python3 derivatives_scout.py --input scenario.json +python3 -m unittest test_derivatives_scout # ۲۰ آزمون واحد +``` + +قالب پروندهٔ ورودی: + +```json +{ + "name": "بازار امروز", + "hurdle": 0.39, + "rows": [ + {"name": "باکس اسپرد نماد الف", "kind": "box", + "call_low": 300, "put_low": 420, "call_high": 180, "put_high": 560, + "strike_low": 1200, "strike_high": 1500, "days": 45, + "liquidity_contracts_per_day": 120, "spread_pct": 0.02}, + {"name": "آتی صندوق طلا", "kind": "basis", + "spot": 20000, "future": 22800, "days": 60, "storage_annual": 0.0}, + {"name": "تبعی", "kind": "tabei", + "stock_price": 50000, "put_price": 200, "strike": 62500, "days": 90}, + {"name": "تساوی پوت‌کال", "kind": "parity", + "call": 420, "put": 380, "spot": 9000, "strike": 9000, "days": 30, "rate": 0.39} + ] +} +``` + +`kind` می‌تواند `box`، `basis`، `tabei`، `parity` یا `covered_call` باشد. نرخ سد (`hurdle`) را با بازده مؤثر صندوق درآمد ثابت همان روز پر کنید، نه با عدد ثابت. + +## محدودیت‌ها (صادقانه) + +- اعداد `--demo` **ساختگی** هستند و فقط برای نمایش کارکرد ابزار؛ هیچ‌کدام قیمت واقعی بازار نیستند. +- خروجی ابزار «تفاوت ریاضی با نرخ سد» است. ریسک نکول ناشر، ریسک اجرای هم‌زمان پاها، صف سفارش و توقف نماد در آن لحاظ نشده. +- داده‌های ورودی (قیمت‌های سهام، آپشن، آتی و گواهی سپرده) باید از سامانهٔ کارگزاری یا پروندهٔ رسمی بازار همان روز تأمین شود؛ ابزار خودش داده جمع نمی‌کند. + +## وضعیت اعتبار اعداد قانونی + +- **بررسی‌شده در همین نوبت (سپتامبر ۲۰۲۶):** کارمزد معاملهٔ آپشن ۰٫۱۰۳ درصد، کارمزد اعمال ۰٫۰۵ درصد، مالیات تسویهٔ فیزیکی ۰٫۵ درصد؛ کارمزد سهام خرید ۰٫۴۶۴ درصد و کسورات فروش ۰٫۹۶۴ درصد؛ معافیت مالیاتی مشتقه؛ بازده مؤثر صندوق‌های درآمد ثابت شهریور ۱۴۰۵ در محدودهٔ ۳۹ تا ۴۰ درصد؛ تورم سالانه رسماً نزدیک ۷۰ درصد گزارش‌شده؛ نرخ تضمین عرضه‌های واقعی تبعی ۲۰ درصد («همیار») و ۳۰ درصد («هموطن») با شرط نگه‌داشتن سبد پایه. +- **نیازمند بازبینی جای دیگری:** درصد وجه تضمین اولیهٔ آتی هر کالا و اعداد «سقف موقعیت هم‌جهت» باید از مشخصات قرارداد فعال همان نماد خوانده شود؛ در این پرونده بازهٔ ۱۰ تا ۲۰ درصد آمده و به‌عنوان عدد قطعی تجویز نشده است. + +## قدم بعدی + +- ساخت مهارت `iran-derivatives-scout` در `HARNESSES/skills/` با سیاست، پیکربندی دروازه و بازبینی skeptic (به تأیید صاحب پرونده). +- پس از آن: `income-plan-forge`، `price-and-proposal`، `tax-paperwork-iran`. diff --git a/station/dossier.py b/station/dossier.py new file mode 100644 index 0000000000000000000000000000000000000000..139dcd42b81e60d413160a22413084331535a4c0 --- /dev/null +++ b/station/dossier.py @@ -0,0 +1,432 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""پروندهٔ سرمایه‌گذار — یک فایل برای جلسه، ساخته‌شده از شاهدهای همان اجرا. + +چه می‌کند؟ همهٔ شاهدهای موجود را از روی پرونده‌های واقعی برنامه جمع می‌کند: +قواعد قفل‌شده، نتیجهٔ «آزمون ۱۰ دقیقه‌ای»، دفتر آزمون و کارنامه، پس‌آزمایی تاریخی، +وضعیت داده و اتصال، و شناسنامهٔ پرونده‌ها با اثر انگشت (sha256). +بعد همه را در یک صفحهٔ HTML آمادهٔ چاپ و یک نسخهٔ متنی می‌ریزد. + +چه نمی‌کند؟ هیچ عددی از خودش نمی‌سازد، هیچ سودی وعده نمی‌دهد، و هیچ داده‌ای بیرون نمی‌فرستد. + +اجرا: python dossier.py (ساخت پرونده در پوشهٔ data) + python dossier.py --json (شاهدهای خام، ماشین‌خوان) + python dossier.py --out <مسیر پروندهٔ HTML> +""" +from __future__ import annotations + +import argparse +import json +import sys +from datetime import datetime, timezone +from pathlib import Path + +VERSION = "0.1.0" +BASE = Path(__file__).resolve().parent +DESK_DIR = (BASE.parent / "desk").resolve() +DATA = BASE / "data" + +for p in (str(BASE), str(DESK_DIR)): + if p not in sys.path: + sys.path.insert(0, p) + +import reportkit as rk # noqa: E402 +import selftest # noqa: E402 + +DEFAULT_RULES: dict = { + "capital": 20_000_000_000, "hurdle": 0.39, + "min_edge_arbitrage_pct": 3.0, "min_edge_leveraged_pct": 5.0, + "max_margin_pct": 0.20, "max_position_pct": 0.35, "max_positions": 3, + "min_liquidity_contracts_per_day": 20, "max_spread_pct": 0.03, + "max_plausible_arb_pct": 250.0, "max_plausible_lev_pct": 400.0, +} + +RULE_NOTES = { + "capital": "سرمایهٔ فرضی آزمون (ریال)", + "hurdle": "نرخ سد: کمترین بازدهی که برای قبول‌کردن یک فرصت لازم است", + "min_edge_arbitrage_pct": "کف حاشیه برای راهبردهای آربیتراژی (واحد درصد)", + "min_edge_leveraged_pct": "کف حاشیه برای راهبردهای اهرمی (واحد درصد)", + "max_margin_pct": "سقف سهم سرمایه در وجه تضمین", + "max_position_pct": "سقف هر موقعیت نسبت به سرمایه", + "max_positions": "بیشترین تعداد موقعیت باز هم‌زمان", + "min_liquidity_contracts_per_day": "کف نقدشوندگی (قرارداد در روز)", + "max_spread_pct": "سقف اسپرد خرید و فروش", + "max_plausible_arb_pct": "سقف باورپذیری بازده سالانهٔ آربیتراژ (بالاتر از آن یعنی داده مشکوک)", + "max_plausible_lev_pct": "سقف باورپذیری بازده سالانهٔ اهرمی", +} + +LIMITATIONS = [ + "هیچ سفارشی به‌صورت خودکار ارسال نمی‌شود؛ خروجی برنامه پیشنهاد و هشدار است.", + "هیچ سود تضمینی وجود ندارد؛ هیچ برنامه‌ای در هیچ بازاری سود را تضمین نمی‌کند.", + "وجه تضمین و مشخصات هر قرارداد باید از سامانهٔ کارگزاری خوانده شود، نه از حافظه.", + "بازده‌های گزارش‌شده، «بازده سالانهٔ محاسبه‌شده از اختلاف قیمت‌ها» هستند، نه سود محقق‌شده.", + "روزهایی که با خوراک آزمایشی ثبت شوند، ساختی‌اند و در کارنامه از روزهای واقعی جدا شمرده می‌شوند.", + "دادهٔ رایگان و بی‌تعهد ممکن است با تأخیر یا خطا بیاید؛ برنامه این را صریح گزارش می‌کند.", +] + +VERIFY_STEPS = [ + ("گام ۱", "خودتان «آزمون ۱۰ دقیقه‌ای» را اجرا کنید", + "python selftest.py", "کارنامهٔ سبز/سرخ را همان‌جا می‌بینید؛ سه موردش را با ماشین‌حساب چک کنید."), + ("گام ۲", "خودتان دموی هزینهٔ صفر را اجرا کنید", + "run-investor-demo.bat (ویندوز) یا bash run-investor-demo", "خوراک آزمایشی محلی می‌آید؛ هیچ اینترنتی لازم نیست."), + ("گام ۳", "زنجیرهٔ دفتر را بیازمانید", + "python live_trial.py --verify", "اگر ردیفی عوض شده باشد، همین دستور می‌گوید کدام ردیف."), + ("گام ۴", "یک روز را با اعداد کارگزاری خودتان جایگزین کنید", + "در گام ۵ رابط گرافیکی، جدول اعداد را پر کنید", "برنامه با همان اعداد دوباره محاسبه می‌کند و حکم را می‌گوید."), +] + + +# ---------------------------------------------------------------- گردآوری شاهدها +def _file_digest(path: Path) -> dict: + from hashlib import sha256 + if not path.exists(): + return {"file": str(path), "exists": False} + data = path.read_bytes() + return {"file": path.name, "exists": True, "bytes": len(data), + "sha256": sha256(data).hexdigest()[:16], + "modified": datetime.fromtimestamp(path.stat().st_mtime).strftime("%Y-%m-%d %H:%M")} + + +def collect(state: dict | None = None, *, run_selftest: bool = True) -> dict: + """شاهدهای پرونده را از پرونده‌های برنامه جمع می‌کند. هیچ عددی ساخته نمی‌شود.""" + import datafeed as df + import connections as conn + import live_trial as trialmod + import daily_trial as dailytrial + import backtest as bt + + state = dict(state or {}) + rules = dict(DEFAULT_RULES) + rules.update({k: v for k, v in (state.get("rules") or {}).items() if k in DEFAULT_RULES}) + + # اتصال فعال (کلیدها هرگز در پرونده نمی‌آیند) + active = None + try: + active = conn.active_or_none() + except Exception: + active = None + connection = dict(state.get("connection") or {}) + if active: + connection.setdefault("name", active["profile"]["name"]) + connection.setdefault("label", active["profile"]["label"]) + connection["key_where"] = active.get("key_where") or "بدون کلید" + connection["is_mock"] = bool(active.get("is_mock")) + + # اسنپ‌شات + snap_path = Path(state.get("file_path") or (DESK_DIR / "market-demo.json")) + snap = df.load_snapshot_rows(snap_path) + dated = sorted((BASE / "data" / "snapshots").glob("snapshot-*.json")) \ + if (BASE / "data" / "snapshots").exists() else [] + + # دفتر آزمون و کارنامه + t = trialmod.Trial(state.get("trial_db") or trialmod.DEFAULT_DB) + summary = t.summary() + log = dailytrial.read_log() + score = dailytrial.scorecard(t, log_records=log) + entries = t.all(limit=5000) + chain_ok, chain_msg = t.verify_chain() + + # پس‌آزمایی تاریخی (روی دادهٔ نمونهٔ همراه؛ صریح برچسب می‌خورد) + backtest = None + hist = BASE / "demo" / "history-demo.csv" + if hist.exists(): + try: + res = bt.run_backtest(hist, rules) + backtest = {"summary": res["summary"], "rows": len(res.get("decisions", [])), + "source": hist.name, "synthetic": True} + except Exception as e: + backtest = {"error": f"{type(e).__name__}: {e}", "source": hist.name, "synthetic": True} + + self_test = None + if run_selftest: + st = selftest.run_all() + self_test = {"summary": st["summary"], "engine": st["engine"], + "cases": [{"id": c["id"], "title": c["title"], "why": c["why"], + "ok": c["ok"], "hand": c["hand"], + "inputs": c["inputs"], "rows": c["rows"]} for c in st["cases"]]} + + files = [_file_digest(p) for p in ( + BASE / "station.py", BASE / "web_server.py", BASE / "daily_trial.py", BASE / "datafeed.py", + BASE / "autoconnect.py", BASE / "connections.py", selftest.TOOLS_DIR / "derivatives_scout.py", + DESK_DIR / "desk.py", BASE / "README-FA.md", BASE / "DEMO-INVESTOR-FA.md")] + + return { + "version": VERSION, + "built_at": datetime.now(timezone.utc).isoformat(timespec="seconds"), + "station_mode": state.get("mode", "sim"), + "rules": rules, + "connection": connection, + "snapshot": {"path": str(snap_path), "rows": len(snap.get("rows") or []), + "as_of": snap.get("as_of", ""), "confirmed": bool(snap.get("confirmed")), + "source": snap.get("source", ""), + "dated_files": [f.name for f in dated]}, + "trial": {"entries": summary.get("entries"), "marked": summary.get("marked"), + "chain_ok": bool(chain_ok), "chain_message": chain_msg, + "buckets": summary.get("buckets") or {}, "avg_expected": summary.get("avg_expected"), + "last_ts": summary.get("last_ts"), + "first_rows": [{"symbol": e["symbol"], "kind": e["kind"], "expected": e["expected"], + "ts": e["ts"], "hash": e["hash"][:12]} for e in entries[:5]]}, + "scorecard": score, + "backtest": backtest, + "self_test": self_test, + "files": files, + } + + +# ---------------------------------------------------------------- ساخت پرونده +def _summary_html(evidence: dict) -> str: + st = evidence.get("self_test") or {} + s = st.get("summary") or {} + sc = evidence["scorecard"] + kpis = [ + (f'{s.get("passed", 0)}/{s.get("total", 0)}', "آزمون‌های سبز موتور و فرایند"), + (evidence["trial"]["entries"], "ردیف در دفتر آزمون"), + (evidence["scorecard"]["days"], "روز ثبت‌شده در کارنامه"), + (evidence["scorecard"]["real_days"], "روز با دادهٔ واقعی کارگزاری"), + ("سالم" if evidence["trial"]["chain_ok"] else "شکسته", "زنجیرهٔ هش دفتر"), + ] + cards = "".join(f'
    {rk.esc(v)}{rk.esc(k)}
    ' for v, k in kpis) + verdict = ("آمادهٔ جلسه: آزمون‌ها سبز است و دفتر سالم." + if (s.get("ok") and evidence["trial"]["chain_ok"] and sc.get("ready")) else + "برای جلسهٔ «خرید داده» هنوز زود است: " + rk.esc(sc.get("verdict", "کارنامه ناتمام است."))) + return f'
    {cards}
    {verdict}
    ' + + +def _rules_html(evidence: dict) -> str: + rows = "".join(f'{rk.esc(k)}{rk.esc(v)}' + f'{rk.esc(RULE_NOTES.get(k, ""))}' for k, v in evidence["rules"].items()) + return ('' + '' + rows + "
    پارامترمقدار قفل‌شدهمعنایش در تصمیم
    ") + + +def _selftest_html(evidence: dict) -> str: + st = evidence.get("self_test") + if not st: + return '
    آزمون در این اجرا کنار گذاشته شده است.
    ' + s = st["summary"] + badge = f'{"همه سبز" if s["ok"] else "سرخ"}' + rows = "".join(f'{rk.esc(c["id"])}' + f'{rk.esc(c["title"])}{rk.esc(c["why"])}' + f'{"سبز" if c["ok"] else "سرخ"}' for c in st["cases"]) + picks = [c for c in st["cases"] if c["id"] in ("fees-kill-edge", "tamper-chain", "position-size")] + samples = "".join(f'
  • {rk.esc(c["title"])}: {rk.esc(c["hand"])}
  • ' for c in picks) + return (f'

    {badge} · {s["passed"]} از {s["total"]} مورد · موتور ' + f'{rk.esc(st["engine"]["version"])} · اثر انگشت ' + f'{rk.esc(st["engine"]["sha256"])}

    ' + '' + '' + rows + "
    موردعنوانچه چیزی را ثابت می‌کندوضعیت
    " + f'

    سه مورد که خودتان می‌توانید با ماشین‌حساب چک کنید:

      {samples}
    ') + + +def _trial_html(evidence: dict) -> str: + t = evidence["trial"] + sc = evidence["scorecard"] + rows = "".join(f'{rk.esc(c["name"])}' + f'{rk.esc(c["have"])}{rk.esc(c["want"])}' + f'{rk.esc(c["hint"])}' for c in sc["criteria"]) + first = "".join(f'
  • {rk.esc(e["hash"])} · {rk.esc(e["symbol"])} · ' + f'{rk.esc(e["kind"])} · انتظار {rk.esc(e["expected"])} واحد درصد · {rk.esc(e["ts"])}
  • ' + for e in t["first_rows"]) or "
  • هنوز ردیفی ثبت نشده است.
  • " + return (f'

    ردیف‌های ثبت‌شده: {rk.esc(t["entries"])} · بازسنجی‌شده: {rk.esc(t["marked"])} · ' + f'وضعیت زنجیره: {rk.esc(t["chain_message"])}

    ' + '' + '' + rows + "
    شرط کارنامهداریملازمراهنمای عمل
    " + f'

    حکم کارنامه: {rk.esc(sc["verdict"])}

    ' + f'

    نمونهٔ ردیف‌های دفتر با هش هر ردیف:

      {first}
    ') + + +def _backtest_html(evidence: dict) -> str: + b = evidence.get("backtest") + if not b: + return '
    پس‌آزمایی اجرا نشده است.
    ' + if b.get("error"): + return f'
    پس‌آزمایی اجرا نشد: {rk.esc(b["error"])}
    ' + s = b["summary"] + pairs = [(k, v) for k, v in s.items() if isinstance(v, (int, float, str))] + rows = "".join(f'{rk.esc(k)}{rk.esc(v)}' + for k, v in pairs) + return ('

    این پس‌آزمایی روی دادهٔ نمونهٔ همراه برنامه اجرا شده است، نه روی ' + 'قیمت‌های واقعی بازار؛ عددهایش برای نشان‌دادن «روش» است نه پیش‌بینی سود.

    ' + '' + + rows + "
    کمیتمقدار
    ") + + +def _data_html(evidence: dict) -> str: + c = evidence["connection"] + snap = evidence["snapshot"] + label = c.get("label") or "تنظیم‌نشده" + mock = " · خوراک آزمایشی محلی (ساختگی)" if c.get("is_mock") else "" + rows = [ + ("پروفایل اتصال فعال", f'{label}{mock}'), + ("محل کلید", c.get("key_where") or "بدون کلید"), + ("پروندهٔ دادهٔ فعلی", snap["path"]), + ("تعداد ردیف", snap["rows"]), + ("تاریخ داده", snap.get("as_of") or "—"), + ("تأییدشده از سامانهٔ کارگزاری", "بله" if snap.get("confirmed") else "خیر"), + ("اسنپ‌شات‌های تاریخ‌دار", "، ".join(snap.get("dated_files") or []) or "—"), + ] + body = "".join(f'{rk.esc(k)}{rk.esc(v)}' for k, v in rows) + return ('' + + body + "
    موردوضعیت
    " + + '

    برنامه از بیرون ایران نمی‌تواند به سامانه‌های ایرانی وصل شود؛ ' + 'به همین دلیل اتصال روی رایانهٔ خودتان آزمایش می‌شود و نتیجه در همین پرونده می‌نشیند.

    ') + + +def _verify_html(evidence: dict) -> str: + rows = "".join(f'{rk.esc(step)}{rk.esc(title)}' + f'{rk.esc(cmd)}{rk.esc(expect)}' + for step, title, cmd, expect in VERIFY_STEPS) + return ('' + '' + rows + "
    گامکار شمادستورچه می‌بینید
    ") + + +def _files_html(evidence: dict) -> str: + rows = [] + for f in evidence["files"]: + if f.get("exists"): + rows.append(f'{rk.esc(f["file"])}{rk.esc(f["bytes"])}' + f'{rk.esc(f["sha256"])}' + f'{rk.esc(f["modified"])}') + else: + rows.append(f'{rk.esc(f["file"])}نیست——') + return ('' + '' + + "".join(rows) + "
    پروندهبایتsha256 (۱۶ رقم اول)آخرین تغییر
    ") + + +def build_html(evidence: dict) -> str: + body = [ + '
    این پرونده چیست؟ یک گزارش راستی‌آزمایی برای تصمیم‌گیری دربارهٔ ' + 'خرید داده و شروع کار. هر عددی که می‌بینید از پرونده‌های همان اجرا خوانده شده و ' + 'اثر انگشت پرونده‌ها در پایان آمده است. هیچ سود تضمینی و هیچ سفارش خودکاری در کار نیست.
    ', + _summary_html(evidence), + "

    ۱. مسئله‌ای که حل می‌شود

    ", + "

    در بازار مشتقهٔ ایران، گرفتن تصمیم درست به سه چیز بسته است: دیدن قیمت‌های پایه، آتی و اعمال " + "در یک جا؛ حساب‌کردن بازده خالص با کارمزد و وجه تضمین؛ و نگه‌داشتن سابقهٔ تصمیم‌ها تا معلوم شود " + "کدام فرصت واقعاً باز ماند. برنامهٔ ایستگاه همین سه کار را با هم انجام می‌دهد: خواندن داده، " + "محاسبهٔ قاعده‌محور، و ثبت دفتر با هش زنجیره‌ای. تصمیم نهایی و اجرا دست انسان و کارگزاری است.

    ", + "

    ۲. قواعد قفل‌شده

    ", + "

    این پارامترها در پروندهٔ تنظیمات نشسته‌اند و در «آزمون ۱۰ دقیقه‌ای» هم تغییر نکرده‌اند؛ " + "هر تغییری در آن‌ها باید آگاهانه و ثبت‌شده باشد.

    ", + _rules_html(evidence), + "

    ۳. شاهد یک: آزمون ۱۰ دقیقه‌ای

    ", + "

    هر مورد دو بار حساب می‌شود: یک بار با موتور برنامه، یک بار با حساب دستی که همان‌جا در کد " + "نوشته شده و با ماشین‌حساب قابل چک است. جدا شدن این دو، مورد را سرخ می‌کند.

    ", + _selftest_html(evidence), + "

    ۴. شاهد دو: دفتر آزمون و کارنامه

    ", + "

    دفتر، سابقهٔ زندهٔ برنامه است: هر سیگنال با ساعت، ورودی‌ها و انتظارش ثبت می‌شود و بعداً با " + "قیمت‌های تازه بازسنجی می‌شود. هر ردیف هشی دارد که به ردیف قبل زنجیر است.

    ", + _trial_html(evidence), + "

    ۵. شاهد سه: پس‌آزمایی روی دادهٔ تاریخ

    ", + _backtest_html(evidence), + "

    ۶. داده و اتصال

    ", + _data_html(evidence), + "

    ۷. آنچه ادعا نمی‌کنیم

    ", + "
      " + "".join(f"
    • {rk.esc(x)}
    • " for x in LIMITATIONS) + "
    ", + "

    ۸. راستی‌آزمایی مستقل توسط شما

    ", + _verify_html(evidence), + "

    ۹. شناسنامهٔ پرونده‌ها

    ", + _files_html(evidence), + ] + html = rk.page("پروندهٔ سرمایه‌گذار — ایستگاه تصمیم مشتقه", + "".join(body), + subtitle=f"ساخته‌شده از شاهدهای اجرای {evidence['built_at']} · " + f"نسخهٔ ایستگاه {evidence['version']}") + return html + + +def build_markdown(evidence: dict) -> str: + st = evidence.get("self_test") or {} + s = st.get("summary") or {} + sc = evidence["scorecard"] + lines = [ + "# پروندهٔ سرمایه‌گذار — ایستگاه تصمیم مشتقه", + "", + f"ساخته‌شده از شاهدهای اجرای {evidence['built_at']} · نسخهٔ ایستگاه {evidence['version']}", + "", + "## خلاصه", + "", + f"- آزمون‌های سبز: {s.get('passed', 0)} از {s.get('total', 0)}", + f"- ردیف‌های دفتر آزمون: {evidence['trial']['entries']} (بازسنجی‌شده: {evidence['trial']['marked']})", + f"- روزهای ثبت‌شده در کارنامه: {sc['days']} · روز واقعی: {sc['real_days']}", + f"- زنجیرهٔ هش: {evidence['trial']['chain_message']}", + f"- حکم کارنامه: {sc['verdict']}", + "", + "## قواعد قفل‌شده", + "", + ] + for k, v in evidence["rules"].items(): + lines.append(f"- `{k}` = {v} — {RULE_NOTES.get(k, '')}") + lines += ["", "## آزمون ۱۰ دقیقه‌ای", ""] + for c in (st.get("cases") or []): + lines.append(f"- [{'سبز' if c['ok'] else 'سرخ'}] **{c['title']}**: {c['why']}") + lines.append(f" - چک دستی: {c['hand']}") + lines += ["", "## آنچه ادعا نمی‌کنیم", ""] + lines += [f"- {x}" for x in LIMITATIONS] + lines += ["", "## راستی‌آزمایی مستقل", ""] + lines += [f"{step}. {title}: `{cmd}` → {expect}" for step, title, cmd, expect in VERIFY_STEPS] + lines += ["", "## شناسنامهٔ پرونده‌ها", ""] + for f in evidence["files"]: + lines.append(f"- {f['file']}: " + (f"`{f.get('sha256')}` ({f.get('bytes')} بایت)" if f.get("exists") + else "نیست")) + lines += ["", "---", "", rk.CREDIT_HTML.replace("", "]")] + return "\n".join(lines) + "\n" + + +def build(state: dict | None = None, *, out: Path | None = None, write_md: bool = True, + run_selftest: bool = True) -> dict: + """پرونده را می‌سازد: HTML + Markdown + JSON ماشین‌خوان. مسیرها را برمی‌گرداند.""" + evidence = collect(state, run_selftest=run_selftest) + html = build_html(evidence) + out_html = Path(out or (DATA / "investor-dossier.html")) + out_html.parent.mkdir(parents=True, exist_ok=True) + out_html.write_text(html, encoding="utf-8") + paths = {"html": str(out_html), "md": None, "json": None, + "sha256": rk.sha256_text(html)[:16], + "summary": {"selftest": (evidence.get("self_test") or {}).get("summary"), + "chain_ok": evidence["trial"]["chain_ok"], + "scorecard_ready": evidence["scorecard"]["ready"], + "entries": evidence["trial"]["entries"]}} + if write_md: + md_path = out_html.with_suffix(".md") + md_path.write_text(build_markdown(evidence), encoding="utf-8") + paths["md"] = str(md_path) + json_path = out_html.with_suffix(".json") + json_path.write_text(json.dumps(evidence, ensure_ascii=False, indent=2), encoding="utf-8") + paths["json"] = str(json_path) + return paths + + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description=f"پروندهٔ سرمایه‌گذار — نسخه {VERSION}") + ap.add_argument("--out", help="مسیر پروندهٔ HTML (پیش‌فرض: data/investor-dossier.html)") + ap.add_argument("--json", action="store_true", help="شاهدهای خام را چاپ کن") + ap.add_argument("--no-md", action="store_true", help="نسخهٔ متنی نساز") + ap.add_argument("--no-selftest", action="store_true", help="آزمون را دوباره اجرا نکن") + ap.add_argument("--open", action="store_true", help="پرونده را در مرورگر باز کن") + ap.add_argument("--version", action="version", version=VERSION) + args = ap.parse_args(argv) + + if args.json: + print(json.dumps(collect(run_selftest=not args.no_selftest), ensure_ascii=False, indent=2)) + return 0 + + res = build(out=Path(args.out) if args.out else None, write_md=not args.no_md, + run_selftest=not args.no_selftest) + print("پروندهٔ سرمایه‌گذار ساخته شد:") + for key in ("html", "md", "json"): + if res.get(key): + print(f" {key}: {res[key]}") + print(f" اثر انگشت (sha256، ۱۶ رقم اول): {res['sha256']}") + s = res["summary"] + st = s.get("selftest") or {} + print(f" آزمون: {st.get('passed', 0)}/{st.get('total', 0)} · زنجیره: " + f"{'سالم' if s['chain_ok'] else 'شکسته'} · کارنامه: {'آماده' if s['scorecard_ready'] else 'ناتمام'}") + if args.open: + import webbrowser + webbrowser.open(Path(res["html"]).as_uri()) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/station/edge_stress.py b/station/edge_stress.py new file mode 100644 index 0000000000000000000000000000000000000000..498f0bf636fcb46525068c6aed06a103718544d8 --- /dev/null +++ b/station/edge_stress.py @@ -0,0 +1,518 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""آزمون تاب‌آوری — «مطمئن شو ایده‌های قبلی واقعاً جواب می‌دهند». + +ایدهٔ خوب، ایده‌ای نیست که فقط در بهترین حالت سود نشان بدهد؛ ایده‌ای است که وقتی شرایط +بدتر شد هم بدانی کجا می‌افتد. این پرونده همین کار را می‌کند: + + • هر راهبرد را با شرایط بدتر (لغزش اجرا، حرکت مخالف قیمت، کارمزد بیشتر، نرخ سد بالاتر، + وجه تضمین گران‌تر، نقدشوندگی کمتر) دوباره حل می‌کند — با همان موتور خودِ برنامه. + • «نقطهٔ مرگ» هر راهبرد را با جست‌وجوی دودویی پیدا می‌کند: کارمزد تا چند برابر بالا برود + که سود از بین برود؟ نرخ سد تا کجا بالا برود که سیگنال بیفتد؟ + • فاصله تا اخطاریهٔ مارجین‌کال را حساب می‌کند (مهم‌ترین عدد برای سرمایهٔ کوچک). + • «نرخ تاب‌آوری» می‌دهد: چند درصدِ شوک‌ها را سالم رد کرده. این **احتمال سود نیست**؛ + فقط می‌گوید در بدترین حالت‌ها چقدر مقاوم است. هیچ‌جا ادعای تضمین سود نمی‌شود. + +هر عددی که این‌جا ساخته می‌شود، بازتولیدپذیر است: با حالت خنثی (بدون شوک) دقیقاً همان عدد +موتور بیرون می‌آید — آزمون‌ها همین را قفل کرده‌اند. +""" + +from __future__ import annotations + +import argparse +import json +import sys +from pathlib import Path + +BASE = Path(__file__).resolve().parent +if str(BASE) not in sys.path: + sys.path.insert(0, str(BASE)) + +import investor_test as inv # noqa: E402 +import signal_judge as sj # noqa: E402 +import reportkit as rk # noqa: E402 + +VERSION = "0.1.0" +DATA = BASE / "data" +REPORT_HTML = DATA / "edge-stress.html" +REPORT_MD = DATA / "edge-stress.md" +REPORT_JSON = DATA / "edge-stress.json" + +HURDLE_STRESS = 0.45 # نرخ سد بالاتر: بازده مؤثر صندوق‌ها بالا می‌رود +SLIP_PCT = 0.5 # لغزش اجرا: خرید گران‌تر، فروش ارزان‌تر +PRICE_SHOCK_PCT = 1.0 # ۱٪ حرکت مخالف قیمت پایه +MARGIN_STRESS = 1.2 # کارگزاری وجه تضمین را ۲۰٪ بالا می‌برد + +# کدام عدد در هر راهبرد «خرید» است و کدام «فروش» → لغزش کدام‌طرف را بدتر می‌کند +BUY_FIELDS = {"basis": ("spot",), "tabei": ("stock_price", "put_price"), + "covered_call": ("spot",), "box": ("call_low", "put_high"), + "parity": ("spot_like",)} +SELL_FIELDS = {"basis": ("future",), "covered_call": ("premium",), "box": ("put_low", "call_high")} + + +def engine(): + return inv.engine() + + +def _scale(row: dict, fields: tuple, factor: float) -> dict: + out = dict(row) + for f in fields: + if isinstance(out.get(f), (int, float)): + out[f] = float(out[f]) * factor + return out + + +def shocked_row(row: dict, *, slip_pct: float = 0.0, price_shock_pct: float = 0.0) -> dict: + """قیمت‌ها را بدتر می‌کند: پایه‌های خرید گران‌تر، پایه‌های فروش ارزان‌تر (بدون دست‌زدن به مشخصات قرارداد).""" + kind = row.get("kind") + out = dict(row) + if slip_pct: + out = _scale(out, BUY_FIELDS.get(kind, ()), 1 + slip_pct / 100) + out = _scale(out, SELL_FIELDS.get(kind, ()), 1 - slip_pct / 100) + if price_shock_pct: + # حرکت مخالف قیمت پایه: در «مبنا» و «پوشش‌داده‌شده» و «تبعی» دارایی گران‌تر می‌شود + if kind == "basis": + out = _scale(out, ("spot",), 1 + price_shock_pct / 100) + elif kind == "covered_call": + out = _scale(out, ("spot",), 1 + price_shock_pct / 100) + elif kind == "tabei": + out = _scale(out, ("stock_price",), 1 + price_shock_pct / 100) + # باکس اسپرد و تساوی، نسبت به حرکت قیمت پایه حساس نیستند (جهت‌شان خنثی است) + return out + + +def annualized(row: dict, *, fee_mult: float = 1.0, hurdle: float | None = None) -> dict: + """بازده سالانه را با کارمزد ضرب‌شده و نرخ سد دلخواه دوباره حساب می‌کند. + + برای راهبردهایی که موتور کارمزد را ورودی می‌گیرد (مبنا، تبعی، پوشش‌داده‌شده) حساب دقیق + است. برای «باکس اسپرد» کارمزد داخل موتور ثابت است؛ آن‌جا همان فرمول دستی‌ای که آزمون + دو-روشی تأییدش کرده به کار می‌رود و در خروجی هم برچسب «مسیر دستی» می‌گیرد. + """ + E = engine() + kind = row.get("kind") + fb, fs, fo = inv._fees(row, kind) + h = float(row.get("hurdle") or (hurdle if hurdle is not None else inv.HURDLE_DEFAULT)) + if hurdle is not None: + h = float(hurdle) + + if kind == "basis": + res = E.basis_opportunity(row["spot"], row["future"], row["days"], h, fb * fee_mult, + fs * fee_mult, row.get("storage_annual", 0.0)) + return {"annualized_pct": res["annualized_pct"], "path": "موتور", "hurdle": h} + if kind == "tabei": + res = E.tabei_min_yield(row["stock_price"], row["put_price"], row["strike"], row["days"], + fb * fee_mult, fs * fee_mult) + # موتور نرخ سد را در خروجی نمی‌آورد؛ خودمان مقایسه می‌کنیم + return {"annualized_pct": res["annualized_pct"], "path": "موتور", "hurdle": h} + if kind == "covered_call": + res = E.covered_call(row["spot"], row["strike"], row["premium"], row["days"], fb * fee_mult, + fs * fee_mult, fo * fee_mult) + return {"annualized_pct": res["premium_annualized_pct"], "path": "موتور", "hurdle": h} + if kind == "box": + res = E.box_spread(row["call_low"], row["put_low"], row["call_high"], row["put_high"], + row["strike_low"], row["strike_high"], row["days"]) + debit = (row["call_low"] + row["put_high"]) - (row["put_low"] + row["call_high"]) + payoff = row["strike_high"] - row["strike_low"] + legs = row["call_low"] + row["put_low"] + row["call_high"] + row["put_high"] + fees = legs * fo * fee_mult + if debit <= 0: + return {"annualized_pct": None, "path": "مسیر دستی (فرمول تأییدشده)", + "engine_pct": res.get("annualized_pct"), "hurdle": h, + "note": "پرداخت خالص باکس صفر یا منفی است؛ بازده سالانه معنا ندارد."} + # نکتهٔ مهم: پرداخت خالص (debit) یک‌بار می‌آید؛ فرمول سالانه‌کردن روی خودِ نسبت است. + annual = ((payoff - fees) / debit) ** (365.0 / row["days"]) - 1 + return {"annualized_pct": round(annual * 100, 3), "path": "مسیر دستی (فرمول تأییدشده)", + "engine_pct": res.get("annualized_pct"), "hurdle": h} + if kind == "parity": + res = E.put_call_parity(row["call"], row["put"], row["spot"], row["strike"], row["days"], + row.get("rate", h)) + return {"annualized_pct": None, "go": bool(res.get("go")), "path": "موتور", + "edge": res.get("conversion_edge_per_unit"), "hurdle": h} + raise ValueError(f"نوع ناشناخته: {kind}") + + +def survives(row: dict, *, fee_mult: float = 1.0, hurdle: float | None = None, + slip_pct: float = 0.0, price_shock_pct: float = 0.0) -> dict: + """پس از شوک، سیگنال می‌ماند یا می‌افتد؟ (بر پایهٔ همان قاعدهٔ نرخ سد)""" + r = shocked_row(row, slip_pct=slip_pct, price_shock_pct=price_shock_pct) + out = annualized(r, fee_mult=fee_mult, hurdle=hurdle) + if row.get("kind") == "parity": + return {**out, "survives": bool(out.get("go"))} + annual = out["annualized_pct"] + return {**out, "survives": bool(annual is not None and annual > out["hurdle"] * 100)} + + +def fee_tolerance(row: dict, *, hi: float = 12.0) -> dict: + """کارمزد تا چند برابر بالاتر برود که سیگنال بیفتد (جست‌وجوی دودویی).""" + if row.get("kind") == "parity": + base = survives(row) + return {"multiple": None, "detail": "تساوی به کارمزد به‌شدت حساس است؛ کارمزد سه پایه " + "همیشه اول کسر می‌شود و «نه» فعلی هم از همین است.", + "survives_now": base["survives"]} + if not survives(row)["survives"]: + return {"multiple": None, "survives_now": False, + "detail": "این ردیف همین امروز هم زیر نرخ سد است؛ «تحمل کارمزد» معنا ندارد — " + "اول باید خودِ سیگنال زنده شود."} + lo, mid = 0.0, 1.0 + if survives(row, fee_mult=hi)["survives"]: + return {"multiple": None, "detail": f"با کارمزد {hi:g} برابر هم می‌ماند؛ کارمزد قاتل این " + f"راهبرد نیست.", "survives_now": True} + for _ in range(50): + mid = (lo + hi) / 2 + if survives(row, fee_mult=mid)["survives"]: + lo = mid + else: + hi = mid + return {"multiple": round((lo + hi) / 2, 3), + "detail": f"اگر کارمزد کل از {round((lo + hi) / 2, 2)} برابر امروز بگذرد، این راهبرد " + f"از نرخ سد می‌افتد.", "survives_now": survives(row)["survives"]} + + +def hurdle_ceiling(row: dict) -> dict: + """نرخ سد تا کجا بالا برود که سیگنال بماند؛ بالاتر از آن می‌افتد.""" + base = annualized(row) + if row.get("kind") == "parity" or base["annualized_pct"] is None: + return {"ceiling_pct": None, "detail": "این ردیف بازده سالانه ندارد (بله/نه است)."} + ceiling = float(base["annualized_pct"]) + survives_now = bool(survives(row)["survives"]) + if not survives_now: + detail = (f"سقف نرخ سد این ردیف {ceiling:.3f}٪ است، ولی همین امروز نرخ سد فعلی از آن " + f"بالاتر است؛ یعنی این سیگنال حالا نمی‌گذرد و این سقف بی‌فایده است.") + else: + detail = (f"تا وقتی بازده مؤثر جایگزین (نرخ سد) زیر {ceiling:.3f}٪ بماند، این ردیف " + f"می‌ماند؛ از آن بالاتر می‌افتد.") + return {"ceiling_pct": round(ceiling, 3), "annualized_pct": round(ceiling, 3), + "survives_now": survives_now, "detail": detail} + + +def margin_distance(row: dict) -> dict: + """چند درصد حرکت مخالف، حساب را به اخطاریهٔ مارجین‌کال می‌رساند. + + واحدها باید یکی باشند (تومان با تومان یا ریال با ریال). اگر وجه تضمین و ارزش قرارداد در دو + واحد متفاوت وارد شده باشند، عدد بی‌معنا می‌شود؛ پس این‌جا سازگاری هم سنجیده می‌شود و در صورت + ناهم‌خوانی، صریح گفته می‌شود — نه اینکه عدد عجیب چاپ شود. + """ + if row.get("kind") == "sizing": + return {"ok": False, "detail": "ردیف اندازهٔ موقعیت، معامله نیست."} + + def num(x) -> float: + try: + return float(x or 0.0) + except (TypeError, ValueError): + return 0.0 + + margin = num(row.get("margin_per_contract")) + price = num(row.get("strike") or row.get("future") or row.get("spot") + or row.get("stock_price")) + size = num(row.get("contract_size")) + notional = num(row.get("notional_per_contract")) + src: list[str] = [] + estimated = False + + if not notional and size and price: + notional = size * price + src.append(f"ارزش قرارداد = اندازهٔ قرارداد ({size:,.0f}) × قیمت ({price:,.0f})") + if not notional and margin: + notional = margin / sj.INITIAL_RATIO_DEFAULT + estimated = True + src.append(f"ارزش قرارداد از وجه تضمین ثبت‌شده ÷ نسبت اولیهٔ " + f"{int(sj.INITIAL_RATIO_DEFAULT * 100)}٪ برآورد شد") + if not notional and price: + notional = price + estimated = True + src.append("فقط قیمت واحد در دست بود؛ ارزش قرارداد تقریبی است") + if not margin: + margin = notional * sj.INITIAL_RATIO_DEFAULT + estimated = True + src.append(f"وجه تضمین با نسبت اولیهٔ {int(sj.INITIAL_RATIO_DEFAULT * 100)}٪ برآورد شد") + if not notional or not margin: + return {"ok": False, "detail": "بدون وجه تضمین و ارزش قرارداد، فاصله تا مارجین‌کال " + "حساب نمی‌شود. این دو عدد را از کارگزاری بگیرید."} + + out = sj.margin_call(contracts=1, margin_per_contract=margin, notional_per_contract=notional) + if not out.get("ok"): + return out + if out["move_pct"] >= 100: + return {"ok": False, "unit_mismatch": True, + "margin_per_contract": margin, "notional_per_contract": notional, + "detail": (f"عدد به‌دست‌آمده ({out['move_pct']:.0f}٪ حرکت مخالف) نامعقول است؛ " + f"معمولاً یعنی وجه تضمین ({margin:,.0f}) و ارزش قرارداد " + f"({notional:,.0f}) در دو واحد متفاوت (تومان/ریال) نوشته شده‌اند. " + f"هر دو را به یک واحد برگردانید.")} + out["estimated"] = estimated + out["source"] = ("حد نگهداری ۷۰٪ وجه تضمین اولیه (رویهٔ بورس) و تسویهٔ روزانه؛ عدد برای " + "لحظهٔ ورود است." + ((" · " + " · ".join(src)) if src else "")) + return out + + +def sizing_stress(row: dict, *, capital: float = 20_000_000_000.0, risk_pct: float = 0.20) -> dict: + """اگر کارگزاری وجه تضمین را گران کند، چند قرارداد کم می‌شود؟""" + E = engine() + margin = float(row.get("margin_per_contract") or 0.0) + if not margin: + return {"ok": False, "detail": "وجه تضمین این ردیف در اسنپ‌شات نیست."} + base = E.position_size(capital, margin, risk_pct) + worse = E.position_size(capital, margin * MARGIN_STRESS, risk_pct) + return {"ok": True, "contracts_now": base["contracts"], "contracts_if_margin_up": worse["contracts"], + "margin_now": margin, "margin_if_up": margin * MARGIN_STRESS, + "lost_pct": (round((base["contracts"] - worse["contracts"]) / base["contracts"] * 100, 1) + if base["contracts"] else 0.0)} + + +def feasibility(row: dict, *, min_liquidity: int = 20, max_spread_pct: float = 0.03) -> dict: + """اجرا شدنی است یا نه: نقدشوندگی و اسپرد. شوک این‌جا روی «بازده» اثر ندارد، روی «شدن/نشدن» دارد.""" + liq = row.get("liquidity_contracts_per_day") + spread = row.get("spread_pct") + half = (liq / 2) if isinstance(liq, (int, float)) else None + triple = (spread * 3) if isinstance(spread, (int, float)) else None + return { + "liquidity": liq, "liquidity_half": half, + "liquidity_ok_now": (liq is None or liq >= min_liquidity), + "liquidity_ok_if_half": (half is None or half >= min_liquidity), + "spread_pct": (round(spread * 100, 4) if isinstance(spread, (int, float)) else None), + "spread_x3_pct": (round(triple * 100, 4) if isinstance(triple, (int, float)) else None), + "spread_ok_now": (spread is None or spread <= max_spread_pct), + "spread_ok_if_x3": (triple is None or triple <= max_spread_pct), + "rules": f"حداقل حجم روز {min_liquidity} قرارداد · حداکثر اسپرد {max_spread_pct * 100:.1f}٪", + } + + +SHOCKS = ( + ("لغزش اجرا ۰٫۵٪", {"slip_pct": SLIP_PCT}), + (f"حرکت مخالف {PRICE_SHOCK_PCT:g}٪ قیمت پایه", {"price_shock_pct": PRICE_SHOCK_PCT}), + ("کارمزد دو برابر", {"fee_mult": 2.0}), + ("کارمزد سه برابر", {"fee_mult": 3.0}), + (f"نرخ سد {HURDLE_STRESS * 100:.0f}٪", {"hurdle": HURDLE_STRESS}), +) + + +def row_label(row: dict, title: str) -> str: + """عنوان ردیف + نماد، تا دو ردیف هم‌نام (مثلاً دو «مبنا») با هم قاطی نشوند.""" + sym = str(row.get("symbol") or "").strip() + return f"{title} · {sym}" if sym and sym not in title else title + + +def stress_row(row: dict) -> dict: + """یک راهبرد را زیر همهٔ شوک‌ها می‌گذارد و خلاصهٔ تاب‌آوری‌اش را می‌دهد.""" + base = inv.ladder_for(row) + neutral = survives(row) + # سنجهٔ صداقت: حالت خنثی باید عیناً همان عدد موتور باشد + neutral_matches = (row.get("kind") == "parity" + or (base.get("annualized_pct") is not None + and abs(float(neutral["annualized_pct"]) - float(base["annualized_pct"])) < 0.01)) + results = [] + for label, kw in SHOCKS: + got = survives(row, **kw) + annual = got.get("annualized_pct") + if row.get("kind") == "parity": + ok = bool(got.get("survives")) + value = "صرفه دارد" if ok else "صرفه ندارد" + else: + ok = bool(got.get("survives")) + value = "—" if annual is None else f"{annual:.3f}٪" + results.append({"shock": label, "value": value, "survives": ok, + "value_raw": (None if row.get("kind") == "parity" else annual)}) + passed = sum(1 for r in results if r["survives"]) + fate = next((r["shock"] for r in results if not r["survives"]), "") + if not base["survives"]: + # ردیفی که امروز هم زیر نرخ سد است، «شکستِ شوک» ندارد؛ از قبل افتاده. + fate = "از قبل زیر نرخ سد است" + # کم‌ترین حاشیهٔ پس از شوک: «رد کرد ولی لبِ مرز» با «راحت رد کرد» یکی نیست. + margins = [float(r["value_raw"]) - base["hurdle_pct"] for r in results + if isinstance(r.get("value_raw"), (int, float))] + min_margin = round(min(margins), 3) if margins else None + dist = margin_distance(row) + return { + "kind": row.get("kind"), "title": row_label(row, base["title"]), "given": base["given"], + "annualized_pct": base["annualized_pct"], "hurdle_pct": base["hurdle_pct"], + "margin_pp": base["margin_pp"], "survives_today": base["survives"], + "neutral_matches_engine": neutral_matches, + "shocks": results, "shocks_total": len(results), "shocks_passed": passed, + "resilience_pct": round(passed / len(results) * 100, 1), + "first_failure": fate, "min_margin_pp": min_margin, + "fee_tolerance": fee_tolerance(row), "hurdle_ceiling": hurdle_ceiling(row), + "margin": dist, "sizing": sizing_stress(row) if row.get("kind") == "basis" else None, + "feasibility": feasibility(row), + "fees_pct": base.get("fees_pct"), + "verdict_today": base.get("verdict"), + } + + +def stress(rows: list[dict] | None = None) -> dict: + """همهٔ راهبردهای دارای «نوع» را می‌سنجد (بدون ردیف اندازهٔ موقعیت).""" + rows = rows if rows is not None else inv.fallback_rows() + out_rows = [] + for row in rows: + if not row.get("kind") or row.get("kind") == "sizing": + continue + out_rows.append(stress_row(row)) + out_rows.sort(key=lambda r: (-(r["survives_today"] or False), -r["resilience_pct"])) + solid = [r for r in out_rows if r["survives_today"] and r["resilience_pct"] >= 80 + and (r["min_margin_pp"] is None or r["min_margin_pp"] >= 5)] + weak = [r for r in out_rows if r["survives_today"] and r["resilience_pct"] < 80] + marginal = [r for r in out_rows if r["survives_today"] and r["resilience_pct"] >= 80 + and r["min_margin_pp"] is not None and r["min_margin_pp"] < 5] + dead = [r for r in out_rows if not r["survives_today"]] + return { + "version": VERSION, + "rows": out_rows, + "counts": {"checked": len(out_rows), "solid": len(solid), "weak": len(weak), + "marginal": len(marginal), "dead": len(dead)}, + "solid": [r["title"] for r in solid], + "weak": [r["title"] for r in weak], + "marginal": [r["title"] for r in marginal], + "dead": [r["title"] for r in dead], + "shocks": [s[0] for s in SHOCKS], + "honesty": ("«نرخ تاب‌آوری» یعنی سهم شوک‌هایی که راهبرد از آن‌ها سالم بیرون آمده است؛ " + "این عدد احتمال سود نیست و هیچ‌جا به‌عنوان احتمال سود به کار نمی‌رود."), + } + + +def to_md(doc: dict) -> str: + L = [f"# آزمون تاب‌آوری راهبردها — نسخهٔ {VERSION}", "", + f"سنجیده‌شده: {doc['counts']['checked']} راهبرد · شوک‌های آزمون: {'، '.join(doc['shocks'])}", "", + f"> {doc['honesty']}", ""] + L += ["## ۱. خلاصهٔ یک‌نگاهی", "", + "| راهبرد | بازده امروز | نرخ سد | می‌ماند؟ | تاب‌آوری | اولین شوکی که می‌اندازد |", + "| --- | --- | --- | --- | --- | --- |"] + for r in doc["rows"]: + annual = "—" if r["annualized_pct"] is None else f"{r['annualized_pct']:.3f}٪" + L.append(f"| {r['title']} | {annual} | {r['hurdle_pct']:.1f}٪ | " + f"{'بله' if r['survives_today'] else 'نه'} | {r['resilience_pct']:.0f}٪ | " + f"{r['first_failure'] or '— سخت‌جان'} |") + L += ["", "## ۲. زیر هر شوک، چه اتفاقی می‌افتد", ""] + for r in doc["rows"]: + L += [f"### {r['title']}", "", + f"- بازده امروز: {r['annualized_pct'] if r['annualized_pct'] is not None else '—'} · " + f"حاشیهٔ روی سد: {r['margin_pp']} واحد درصد · کارمزد لحاظ‌شده: {r['fees_pct']}٪", "", + "| شوک | نتیجه | می‌ماند؟ |", "| --- | --- | --- |"] + for s in r["shocks"]: + L.append(f"| {s['shock']} | {s['value']} | {'بله' if s['survives'] else 'نه'} |") + if r["kind"] != "parity": + ft = r["fee_tolerance"] + hc = r["hurdle_ceiling"] + L += ["", f"- **کارمزد چه‌قدر قابل تحمل است:** {ft['detail']}"] + L += [f"- **سقف نرخ سد:** {hc['detail']}"] + mg = r["margin"] + if mg.get("ok"): + L += [f"- **فاصله تا اخطاریهٔ مارجین‌کال:** {mg['move_pct']:.2f}٪ حرکت مخالف " + f"(بر پایهٔ {mg['maintenance_pct']}٪ حد نگهداری). {mg['source']}"] + if mg.get("price_level"): + L += [f" - {mg['price_note']}"] + else: + L += [f"- **مارجین‌کال:** {mg.get('detail')}"] + if r.get("sizing") and r["sizing"].get("ok"): + s = r["sizing"] + L += [f"- **اگر وجه تضمین ۲۰٪ گران شود:** از {s['contracts_now']} قرارداد به " + f"{s['contracts_if_margin_up']} قرارداد می‌رسد ({s['lost_pct']}٪ کوچک‌تر)."] + f = r["feasibility"] + L += [f"- **اجرا شدنی بودن:** {f['rules']} — نقدشوندگی فعلی {f['liquidity']} قرارداد " + f"(نصف شود: {'می‌شود' if f['liquidity_ok_if_half'] else 'نمی‌شود'}) · اسپرد فعلی " + f"{f['spread_pct']}٪ (سه برابر شود: {'می‌شود' if f['spread_ok_if_x3'] else 'نمی‌شود'})", ""] + L += ["## ۳. نتیجه‌گیری صادقانه", "", + f"- سخت‌جان‌ها (همهٔ شوک‌ها را رد کردند): {'، '.join(doc['solid']) or '—'}", + f"- لرزان‌ها (با شوک کوچک می‌افتند): {'، '.join(doc['weak']) or '—'}", + f"- لبِ مرز (رد کردند، ولی حاشیهٔ پس از شوک کمتر از ۵ واحد درصد): " + f"{'، '.join(doc.get('marginal') or []) or '—'}", + f"- امروز افتاده‌ها: {'، '.join(doc['dead']) or '—'}", "", + "هرچه نرخ تاب‌آوری پایین‌تر باشد، آن ردیف بیشتر به «حالت خوبِ بازار» وابسته است؛ با " + "سرمایهٔ کوچک، فقط ردیف‌های سخت‌جان ارزش بررسی دارند.", ""] + return "\n".join(L) + + +def build(rows: list[dict] | None = None, *, write: bool = True, + html: Path | str | None = None, md: Path | str | None = None, + jsonf: Path | str | None = None) -> dict: + doc = stress(rows) + doc["md_text"] = to_md(doc) + if write: + body = ['
    این پرونده شوک‌آزمون است، نه تبلیغ. هر راهبرد را با ' + 'شرایطی که واقعاً پیش می‌آید دوباره حساب می‌کنیم و می‌گوییم کجا می‌افتد. ' + '«نرخ تاب‌آوری» احتمال سود نیست: فقط نشان می‌دهد راهبرد با بدترشدن شرایط چقدر ' + 'دوام می‌آورد.
    ', + f"

    {rk.esc(doc['honesty'])}

    ", + "

    ۱. خلاصهٔ یک‌نگاهی

    ", + '' + '' + ''] + for r in doc["rows"]: + annual = "—" if r["annualized_pct"] is None else f"{r['annualized_pct']:.3f}٪" + body.append(f"" + f"" + f"" + f"" + f"") + body.append("
    راهبردبازده امروزنرخ سدمی‌ماند؟تاب‌آوریاولین شوکی که می‌اندازد
    {rk.esc(r['title'])}{annual}{r['hurdle_pct']:.1f}٪{'بله ✅' if r['survives_today'] else 'نه ❌'}{r['resilience_pct']:.0f}٪{rk.esc(r['first_failure'] or '— سخت‌جان')}

    ۲. زیر هر شوک

    ") + for r in doc["rows"]: + body.append(f"

    {rk.esc(r['title'])}

    ") + if r["kind"] != "parity": + body.append(f"

    بازده امروز {annual_of(r)} · حاشیه روی سد " + f"{r['margin_pp']} واحد درصد · کارمزد {r['fees_pct']}٪

    ") + body.append('' + '') + for s in r["shocks"]: + body.append(f"" + f"") + body.append("
    شوکنتیجهمی‌ماند؟
    {rk.esc(s['shock'])}{rk.esc(s['value'])}{'بله ✅' if s['survives'] else 'نه ❌'}
    ") + ft, hc = r["fee_tolerance"], r["hurdle_ceiling"] + if r["kind"] != "parity": + body.append(f"

    کارمزد: {rk.esc(ft['detail'])}
    " + f"سقف نرخ سد: {rk.esc(hc['detail'])}

    ") + mg = r["margin"] + if mg.get("ok"): + body.append(f"

    مارجین‌کال: {mg['move_pct']:.2f}٪ حرکت مخالف. " + f"{rk.esc(mg.get('source', ''))}

    ") + f = r["feasibility"] + body.append(f"

    اجرا شدنی بودن — {rk.esc(f['rules'])}: نقدشوندگی " + f"{f['liquidity']} (نصف: {'می‌شود' if f['liquidity_ok_if_half'] else 'نمی‌شود'}) · " + f"اسپرد {f['spread_pct']}٪ (سه‌برابر: " + f"{'می‌شود' if f['spread_ok_if_x3'] else 'نمی‌شود'})

    ") + body += ["

    ۳. نتیجه‌گیری

      ", + f"
    • سخت‌جان‌ها: {rk.esc('، '.join(doc['solid']) or '—')}
    • ", + f"
    • لرزان‌ها: {rk.esc('، '.join(doc['weak']) or '—')}
    • ", + f"
    • لبِ مرز: {rk.esc('، '.join(doc.get('marginal') or []) or '—')}
    • ", + f"
    • امروز افتاده‌ها: {rk.esc('، '.join(doc['dead']) or '—')}
    ", + '

    ✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · 📱 +989126630554 · ' + '✈️ Telegram: Mojarabian · ' + '📸 Instagram: Mojarabian.Art

    '] + hp = Path(html or REPORT_HTML) + hp.parent.mkdir(parents=True, exist_ok=True) + hp.write_text(rk.page("آزمون تاب‌آوری راهبردها", "".join(body), + subtitle=f"{doc['counts']['checked']} راهبرد × " + f"{len(doc['shocks'])} شوک"), encoding="utf-8") + Path(md or REPORT_MD).write_text(doc["md_text"], encoding="utf-8") + Path(jsonf or REPORT_JSON).write_text(json.dumps(doc, ensure_ascii=False, indent=1), + encoding="utf-8") + doc.update({"html": str(hp), "md": str(md or REPORT_MD), "json": str(jsonf or REPORT_JSON)}) + return doc + + +def annual_of(r: dict) -> str: + return "—" if r["annualized_pct"] is None else f"{r['annualized_pct']:.3f}٪" + + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description="آزمون تاب‌آوری راهبردها زیر شوک‌های واقعی") + ap.add_argument("--json", action="store_true") + ap.add_argument("--no-write", action="store_true") + a = ap.parse_args(argv) + doc = build(write=not a.no_write) + if a.json: + print(json.dumps(doc, ensure_ascii=False, indent=1)) + return 0 + print(f"آزمون تاب‌آوری — {doc['counts']['checked']} راهبرد · شوک‌ها: {'، '.join(doc['shocks'])}") + for r in doc["rows"]: + print(f" · {r['title']}: بازده {annual_of(r)} · می‌ماند: " + f"{'بله' if r['survives_today'] else 'نه'} · تاب‌آوری {r['resilience_pct']:.0f}٪" + + (f" · اولین باخت: {r['first_failure']}" if r["first_failure"] else "")) + print(f" سخت‌جان: {'، '.join(doc['solid']) or '—'}") + print(f" لرزان: {'، '.join(doc['weak']) or '—'}") + print(f" لبِ مرز: {'، '.join(doc.get('marginal') or []) or '—'}") + print(f" افتاده: {'، '.join(doc['dead']) or '—'}") + if doc.get("html"): + print(" برگه:", doc["html"]) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/station/gate.py b/station/gate.py new file mode 100644 index 0000000000000000000000000000000000000000..24e47293ae91bb77a81b58a01b1a4aab28928ce7 --- /dev/null +++ b/station/gate.py @@ -0,0 +1,469 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""دروازهٔ ورود برنامه — «مدیر» برای خودت، و کاربران مهمان (کارفرما/همکاران) (نسخهٔ ۰.۲.۰). + +چرا این ماژول هست: برنامه روی رایانهٔ خودت می‌مانَد و می‌خواهی کارفرمایی در شهر دیگر از +طریق یک نشانی، همان برنامه را ببیند. دروازه دو کار می‌کند: + + · کسی که شناسه و رمز ندارد، به خودِ برنامه نمی‌رسد (نه فقط پنل مدیریت). + · حساب «مهمان» می‌سازد که می‌تواند همه‌چیز را اجرا و تست کند، ولی نمی‌تواند مجوز صادر کند، + رمز عوض کند، یا برنامه را خاموش کند. + +سه قاعدهٔ صادقانه: + + ۱. رمز به‌صورت متن ذخیره نمی‌شود؛ همان PBKDF2-SHA256 پنل مدیریت (نمک + هش). + ۲. **دروازهٔ خاموش = همان اعتماد محلی قبلی**: هر کسی که به این رایانه دسترسی دارد، مدیر است. + پس اگر برنامه را روی اینترنت می‌گذاری، دروازه باید روشن باشد. + ۳. نشست‌ها در حافظه‌اند؛ با بستن برنامه پاک می‌شوند. اگر رمز مهمان لو رفت، `--guest-off` + همان لحظه دسترسی را می‌بندد (و `--set-guest-pass` رمز را عوض می‌کند). + +اجرا: + python3 gate.py --sync-admin # رمز مدیر = همان رمز پنل مدیریت + python3 gate.py --on --guest-id masoud --guest-pass "رمز-مهمان" + python3 gate.py --user-add ali "رمز-علی" --user-note "کارشناس شرکت" # کاربر تازه (خودت می‌سازی) + python3 gate.py --users # فهرست کاربران + python3 gate.py --user-off ali # قطع فوری دسترسی یک کاربر + python3 gate.py --user-del ali # حذف کامل کاربر (نشستش هم می‌بندد) + python3 gate.py --status + python3 gate.py --guest-off # قطع فوری حساب مهمانِ قدیمی + python3 gate.py --off # خاموش کردن دروازه +""" +from __future__ import annotations + +import argparse +import json +import secrets +import sys +import time +from pathlib import Path + +BASE = Path(__file__).resolve().parent +if str(BASE) not in sys.path: + sys.path.insert(0, str(BASE)) + +import adminauth as panel # noqa: E402 (همان طرح هشِ پنل مدیریت، یک منبع) + +VERSION = "0.2.0" +# مسیر پیکربندی: با STATION_GATE_CONFIG می‌شود پیکربندی دیگری را آزمود (مثلاً در تست‌ها) +import os # noqa: E402 +CONFIG = Path(os.environ.get("STATION_GATE_CONFIG") or (BASE / "config" / "gate.json")) +COOKIE = "station_gate" +TTL_SECONDS = 8 * 60 * 60 # یک روز کاری: کارفرما وسط دمو بیرون نیفتد +ROLES = ("admin", "guest") + +SESSIONS: dict[str, dict] = {} + + +# ------------------------------------------------------------------ خواندن و نوشتن + +def load(path: Path | str | None = None) -> dict | None: + p = Path(path or CONFIG) + if not p.exists(): + return None + try: + data = json.loads(p.read_text(encoding="utf-8")) + except (json.JSONDecodeError, OSError): + return None + return data if isinstance(data, dict) else None + + +def save(cfg: dict, path: Path | str | None = None) -> Path: + p = Path(path or CONFIG) + p.parent.mkdir(parents=True, exist_ok=True) + cfg = dict(cfg) + cfg["version"] = VERSION + p.write_text(json.dumps(cfg, ensure_ascii=False, indent=1), encoding="utf-8") + try: + p.chmod(0o600) + except OSError: + pass + return p + + +def enabled(path: Path | str | None = None) -> bool: + cfg = load(path) + return bool(cfg and cfg.get("enabled")) + + +def set_enabled(flag: bool, *, path: Path | str | None = None) -> dict: + cfg = load(path) or {} + cfg["enabled"] = bool(flag) + save(cfg, path) + return status(path) + + +def _account(cfg: dict, role: str) -> dict: + row = cfg.get(role) or {} + return row if isinstance(row, dict) else {} + + +def accounts(path: Path | str | None = None) -> dict: + """وضعیت حساب‌ها — بدون هیچ هش و رمزی.""" + cfg = load(path) or {} + out = {} + for role in ROLES: + row = _account(cfg, role) + out[role] = {"id": row.get("id") or "", "set": bool(row.get("hash") and row.get("salt")), + "enabled": bool(row.get("enabled", role == "admin"))} + return out + + +def set_account(role: str, user_id: str, password: str, *, + path: Path | str | None = None) -> dict: + """حساب یک نقش را می‌سازد/عوض می‌کند. رمز کوتاه رد می‌شود (همان قاعدهٔ پنل).""" + if role not in ROLES: + raise ValueError(f"نقش ناشناخته: {role} (باید یکی از {ROLES} باشد)") + user_id = str(user_id or "").strip() + if not user_id: + raise ValueError("شناسه خالی است.") + if len(str(password or "")) < panel.MIN_PASS_LENGTH: + raise ValueError(f"رمز باید دست‌کم {panel.MIN_PASS_LENGTH} نویسه باشد.") + cfg = load(path) or {} + salt = secrets.token_hex(16) + cfg[role] = {"id": user_id, "salt": salt, "rounds": panel.PBKDF2_ROUNDS, + "hash": panel._hash(password, salt), "enabled": True, + "made": int(time.time())} + save(cfg, path) + return accounts(path)[role] + + +def _users(cfg: dict) -> list[dict]: + rows = cfg.get("users") + return [r for r in rows if isinstance(r, dict)] if isinstance(rows, list) else [] + + +def users(path: Path | str | None = None) -> list[dict]: + """فهرست کاربران مهمان — بدون هیچ هش و رمزی.""" + out = [] + for row in _users(load(path) or {}): + uid = str(row.get("id") or "") + out.append({"id": uid, "enabled": bool(row.get("enabled", True)), + "note": str(row.get("note") or ""), "made": int(row.get("made") or 0), + "sessions": len([1 for v in SESSIONS.values() if v.get("id") == uid])}) + return out + + +def find_user(user_id: str, *, path: Path | str | None = None) -> dict | None: + uid = str(user_id or "").strip() + return next((r for r in _users(load(path) or {}) if str(r.get("id")) == uid), None) + + +def add_user(user_id: str, password: str, *, note: str = "", + path: Path | str | None = None) -> dict: + """یک کاربر مهمان تازه می‌سازد. رمز فقط هش می‌شود. شناسهٔ تکراری رد می‌شود.""" + uid = str(user_id or "").strip() + if not uid: + raise ValueError("شناسه خالی است.") + if len(uid) > 32 or any(c.isspace() for c in uid): + raise ValueError("شناسه باید بی‌فاصله و کوتاه‌تر از ۳۲ نویسه باشد.") + if len(str(password or "")) < panel.MIN_PASS_LENGTH: + raise ValueError(f"رمز باید دست‌کم {panel.MIN_PASS_LENGTH} نویسه باشد.") + cfg = load(path) or {} + admin_id = str(_account(cfg, "admin").get("id") or "") + if uid == admin_id: + raise ValueError("این شناسه برای حساب مدیر است؛ شناسهٔ دیگری بردارید.") + if find_user(uid, path=path): + raise ValueError(f"کاربر «{uid}» از قبل هست. برای عوض‌کردن رمزش، اول حذفش کن.") + salt = secrets.token_hex(16) + row = {"id": uid, "salt": salt, "rounds": panel.PBKDF2_ROUNDS, + "hash": panel._hash(password, salt), "enabled": True, + "note": str(note or ""), "made": int(time.time())} + rows = _users(cfg) + rows.append(row) + cfg["users"] = rows + save(cfg, path) + return {"id": uid, "enabled": True, "note": row["note"], "made": row["made"], "sessions": 0} + + +def delete_user(user_id: str, *, path: Path | str | None = None) -> dict: + """کاربر را کامل حذف می‌کند و نشست‌های بازش را همان لحظه می‌بندد.""" + uid = str(user_id or "").strip() + cfg = load(path) or {} + rows = _users(cfg) + left = [r for r in rows if str(r.get("id")) != uid] + if len(left) == len(rows): + raise ValueError(f"کاربری با شناسهٔ «{uid}» پیدا نشد.") + cfg["users"] = left + save(cfg, path) + closed = close_sessions(user_id=uid) + return {"id": uid, "closed": closed, "left": len(left)} + + +def set_user_enabled(user_id: str, flag: bool, *, + path: Path | str | None = None) -> dict: + """قطع/وصل دسترسی یک کاربر. قطع = بستن نشست‌های بازش.""" + uid = str(user_id or "").strip() + cfg = load(path) or {} + rows = _users(cfg) + row = next((r for r in rows if str(r.get("id")) == uid), None) + if row is None: + raise ValueError(f"کاربری با شناسهٔ «{uid}» پیدا نشد.") + row["enabled"] = bool(flag) + cfg["users"] = rows + save(cfg, path) + closed = 0 if flag else close_sessions(user_id=uid) + return {"id": uid, "enabled": bool(flag), "closed": closed} + + +def _user_alive(cfg: dict, user_id: str) -> bool: + """آیا این کاربرِ مهمان همین حالا اجازهٔ ورود دارد؟ (برای نقش مهمانِ نشست‌های باز)""" + uid = str(user_id or "") + if uid and uid == str(_account(cfg, "guest").get("id") or ""): + return bool(_account(cfg, "guest").get("enabled")) + row = next((r for r in _users(cfg) if str(r.get("id")) == uid), None) + return bool(row and row.get("enabled", True)) + + +def set_enabled_account(role: str, flag: bool, *, path: Path | str | None = None) -> dict: + cfg = load(path) or {} + row = _account(cfg, role) + if not row: + raise ValueError(f"حساب «{role}» ساخته نشده است.") + row["enabled"] = bool(flag) + cfg[role] = row + save(cfg, path) + if not flag: # قطع دسترسی = بستن نشست‌های باز همان نقش + for tok in [k for k, v in SESSIONS.items() if v.get("role") == role]: + SESSIONS.pop(tok, None) + return accounts(path)[role] + + +def sync_admin_from_panel(panel_path: Path | str | None = None, *, + path: Path | str | None = None) -> dict: + """رمز مدیر دروازه را با رمز پنل مدیریت یکی می‌کند (بدون نیاز به دانستن رمز).""" + cfgp = panel.load_config(panel_path) + if not cfgp: + raise ValueError("پنل مدیریت هنوز رمز ندارد؛ اول این را اجرا کنید: " + "python3 adminauth.py --set-id ID --set-pass PASS") + cfg = load(path) or {} + cfg["admin"] = {"id": cfgp.get("id"), "salt": cfgp.get("salt"), + "rounds": int(cfgp.get("rounds") or panel.PBKDF2_ROUNDS), + "hash": cfgp.get("hash"), "enabled": True} + save(cfg, path) + return accounts(path)["admin"] + + +# ------------------------------------------------------------------ ورود و نشست + +def role_of(token: str | None, *, path: Path | str | None = None, + now: float | None = None) -> str | None: + """نقش این نشست. **دروازهٔ خاموش = مدیر** (اعتماد محلی، مثل قبل از این ماژول).""" + if not enabled(path): + return "admin" + if not token: + return None + rec = SESSIONS.get(str(token)) + if not rec: + return None + t = now if now is not None else time.time() + if rec["expires"] < t: + SESSIONS.pop(str(token), None) + return None + cfg = load(path) or {} + if rec["role"] == "admin": + if not _account(cfg, "admin").get("enabled", True): + SESSIONS.pop(str(token), None) # حساب مدیر قطع شده است + return None + elif not _user_alive(cfg, rec.get("id")): + SESSIONS.pop(str(token), None) # کاربر حذف/قطع شده است + return None + rec["expires"] = t + TTL_SECONDS + return rec["role"] + + +def _verify_row(row: dict, user_id: str, password: str, *, role: str = "guest") -> bool: + """یک ردیف حساب (هر نقشی) را با شناسه و رمز داده‌شده می‌سنجد.""" + if not (row.get("hash") and row.get("salt")): + return False + if not row.get("enabled", role == "admin"): + return False + rounds = int(row.get("rounds") or panel.PBKDF2_ROUNDS) + try: + import hashlib + dk = hashlib.pbkdf2_hmac("sha256", str(password or "").encode("utf-8"), + bytes.fromhex(str(row.get("salt"))), rounds) + except ValueError: + return False + return bool(panel._same(user_id, row.get("id")) and panel._same(dk.hex(), row.get("hash"))) + + +def _verify(role: str, user_id: str, password: str, cfg: dict) -> bool: + return _verify_row(_account(cfg, role), user_id, password, role=role) + + +def login(user_id: str, password: str, *, ip: str = "؟", path: Path | str | None = None, + now: float | None = None) -> dict: + """ورود یکی از دو نقش. خروجی همیشه کلید «ok» دارد.""" + cfg = load(path) + if not cfg or not cfg.get("enabled"): + return {"ok": False, "gate_off": True, + "error": "دروازه خاموش است؛ ورود لازم نیست (همین رایانه = مدیر)."} + if panel.rate_limited(ip, now=now): + return {"ok": False, "rate_limited": True, + "error": "تلاش‌های ناموفق زیاد بود؛ چند دقیقه صبر کنید."} + if not any(_account(cfg, r).get("hash") for r in ROLES) and not _users(cfg): + return {"ok": False, "error": "هیچ حسابی ساخته نشده. اول: python3 gate.py --sync-admin"} + role = next((r for r in ROLES if _verify(r, user_id, password, cfg)), None) + if role is None: # شاید کاربرِ مهمانِ تازه‌ای باشد + for row in _users(cfg): + if _verify_row(row, user_id, password): + role = "guest" + break + if not role: + left = panel.FAIL_LIMIT - panel.note_failure(ip, now=now) + return {"ok": False, "error": f"شناسه یا رمز درست نیست. {max(left, 0)} تلاش تا قفل موقت."} + panel.reset_failures(ip) + t = now if now is not None else time.time() + token = secrets.token_hex(24) + SESSIONS[token] = {"id": str(user_id), "role": role, "expires": t + TTL_SECONDS, "made": t} + return {"ok": True, "token": token, "role": role, "id": str(user_id), + "expires_in_minutes": TTL_SECONDS // 60} + + +def who(token: str | None, *, path: Path | str | None = None) -> dict | None: + """شناسه و نقش این نشست (برای نمایش «وارد شدهاید: …» در رابط).""" + role = role_of(token, path=path) + if not role: + return None + if not enabled(path): + return {"id": "—", "role": role, "local": True} + rec = SESSIONS.get(str(token)) or {} + return {"id": rec.get("id") or "—", "role": role, "local": False} + + +def close_sessions(role: str | None = None, *, user_id: str | None = None) -> int: + """همهٔ نشست‌ها (یا نشست‌های یک نقش / یک کاربر) را می‌بندد.""" + doomed = [k for k, v in SESSIONS.items() + if (role is None or v.get("role") == role) + and (user_id is None or str(v.get("id")) == str(user_id))] + for k in doomed: + SESSIONS.pop(k, None) + return len(doomed) + + +def logout(token: str | None) -> bool: + return bool(SESSIONS.pop(str(token), None)) + + +def active_sessions() -> int: + return len(SESSIONS) + + +def status(path: Path | str | None = None) -> dict: + """وضعیت برای نمایش در رابط و پنل — بدون هیچ رمز و هشی.""" + cfg = load(path) + acc = accounts(path) + return {"version": VERSION, "enabled": bool(cfg and cfg.get("enabled")), + "backend": "متغیر محیطی" if panel.env_credentials() else f"پروندهٔ {CONFIG}", + "accounts": acc, "users": users(path), "cookie": COOKIE, + "ttl_hours": TTL_SECONDS // 3600, + "open_sessions": active_sessions(), + "rule": ("دروازه خاموش است: هر کسی که به این رایانه دسترسی دارد، مدیر است." + if not (cfg and cfg.get("enabled")) else + "دروازه روشن است: بدون شناسه و رمز، برنامه باز نمی‌شود.")} + + +# ------------------------------------------------------------------ خط فرمان + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description="دروازهٔ ورود برنامه (مدیر و مهمان/کارفرما)") + ap.add_argument("--on", action="store_true", help="دروازه را روشن کن") + ap.add_argument("--off", action="store_true", help="دروازه را خاموش کن") + ap.add_argument("--sync-admin", action="store_true", help="رمز مدیر = رمز پنل مدیریت") + ap.add_argument("--admin-id", default="", help="شناسهٔ مدیر (با --admin-pass)") + ap.add_argument("--admin-pass", default="", help="رمز مدیر") + ap.add_argument("--guest-id", default="", help="شناسهٔ مهمان/کارفرما (با --guest-pass)") + ap.add_argument("--guest-pass", default="", help="رمز مهمان/کارفرما") + ap.add_argument("--guest-on", action="store_true", help="دسترسی مهمان را روشن کن") + ap.add_argument("--guest-off", action="store_true", help="دسترسی مهمان را همین حالا قطع کن") + ap.add_argument("--status", action="store_true", help="وضعیت دروازه و حساب‌ها") + ap.add_argument("--users", action="store_true", help="فهرست کاربران مهمان") + ap.add_argument("--user-add", nargs=2, metavar=("ID", "PASS"), help="کاربر مهمان تازه بساز") + ap.add_argument("--user-note", default="", help="یادداشت کاربر تازه (اختیاری)") + ap.add_argument("--user-del", default="", help="کاربر را کامل حذف کن (نشستش هم بسته می‌شود)") + ap.add_argument("--user-on", default="", help="دسترسی این کاربر را وصل کن") + ap.add_argument("--user-off", default="", help="دسترسی این کاربر را قطع کن") + ap.add_argument("--check", nargs=2, metavar=("ID", "PASS"), help="آزمودن یک جفت شناسه/رمز") + ap.add_argument("--config", default="", help="مسیر پروندهٔ دروازه (پیش‌فرض: config/gate.json)") + ap.add_argument("--version", action="version", version=f"gate {VERSION}") + a = ap.parse_args(argv) + cfg_path = a.config or None + + try: + if a.sync_admin: + acc = sync_admin_from_panel(path=cfg_path) + print(f"رمز مدیر دروازه با پنل مدیریت یکی شد · شناسه: {acc['id']}") + if a.admin_id and a.admin_pass: + acc = set_account("admin", a.admin_id, a.admin_pass, path=cfg_path) + print(f"حساب مدیر ذخیره شد · شناسه: {acc['id']} (فقط هش روی دیسک)") + if a.guest_id and a.guest_pass: + acc = set_account("guest", a.guest_id, a.guest_pass, path=cfg_path) + print(f"حساب مهمان (کارفرما) ذخیره شد · شناسه: {acc['id']} (فقط هش روی دیسک)") + if a.guest_on: + set_enabled_account("guest", True, path=cfg_path) + print("دسترسی مهمان روشن شد.") + if a.guest_off: + set_enabled_account("guest", False, path=cfg_path) + print("دسترسی مهمان قطع شد (نشست‌های باز هم بی‌اعتبار می‌شوند).") + if a.on: + set_enabled(True, path=cfg_path) + print("دروازه روشن شد.") + if a.off: + set_enabled(False, path=cfg_path) + print("دروازه خاموش شد: همین رایانه = مدیر.") + if a.user_add: + u = add_user(a.user_add[0], a.user_add[1], note=a.user_note, path=cfg_path) + print(f"کاربر مهمان ساخته شد · شناسه: {u['id']} (فقط هش روی دیسک)") + if a.user_del: + out = delete_user(a.user_del, path=cfg_path) + print(f"کاربر «{out['id']}» حذف شد · {out['closed']} نشستش هم بسته شد · " + f"{out['left']} کاربر دیگر مانده.") + if a.user_on: + u = set_user_enabled(a.user_on, True, path=cfg_path) + print(f"دسترسی «{u['id']}» وصل شد.") + if a.user_off: + u = set_user_enabled(a.user_off, False, path=cfg_path) + print(f"دسترسی «{u['id']}» قطع شد · {u['closed']} نشست بازش بسته شد.") + if a.users and not a.status: + rows = users(cfg_path) + if not rows: + print("هیچ کاربر مهمانی ساخته نشده است.") + for u in rows: + print(f" · {u['id']} — " + ("فعال" if u["enabled"] else "قطع‌شده") + + (f" · یادداشت: {u['note']}" if u["note"] else "") + + (f" · نشست باز: {u['sessions']}" if u["sessions"] else "")) + if a.check: + cfg = load(cfg_path) or {} + role = next((r for r in ROLES if _verify(r, a.check[0], a.check[1], cfg)), None) + if role is None and any(_verify_row(u, a.check[0], a.check[1]) for u in _users(cfg)): + role = "guest" + print(f"درست است ✅ (نقش: {role})" if role else "درست نیست ✗") + return 0 if role else 1 + except ValueError as e: + print(f"خطا: {e}", file=sys.stderr) + return 2 + + if a.status or not any([a.on, a.off, a.sync_admin, a.admin_pass, a.guest_pass, + a.guest_on, a.guest_off, a.users, a.user_add, a.user_del, + a.user_on, a.user_off]): + s = status(cfg_path) + acc = s["accounts"] + print(f"دروازه: {'روشن' if s['enabled'] else 'خاموش'} · {s['rule']}") + print(f" مدیر: {'ساخته شده — ' + acc['admin']['id'] if acc['admin']['set'] else 'ساخته نشده'}") + print(f" مهمان (کارفرما): " + + (f"{acc['guest']['id']} — " + ("فعال" if acc['guest']['enabled'] else "قطع‌شده") + if acc['guest']['set'] else "ساخته نشده")) + rows = s.get("users") or [] + if rows: + print(" کاربران مهمان: " + " · ".join( + f"{u['id']} (" + ("فعال" if u['enabled'] else "قطع‌شده") + ")" for u in rows)) + else: + print(" کاربران مهمان: هیچ‌کدام (می‌توانی بسازی: gate.py --user-add ID PASS)") + print(f" عمر نشست: {s['ttl_hours']} ساعت · نشست‌های باز: {s['open_sessions']}") + if not s["enabled"]: + print(" برای دیدن برنامه توسط کارفرما: python3 gate.py --on --guest-id ... --guest-pass ...") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/station/investor_test.py b/station/investor_test.py new file mode 100644 index 0000000000000000000000000000000000000000..531ffa8818342c9dcd7678bba3a65a58e756f16f --- /dev/null +++ b/station/investor_test.py @@ -0,0 +1,1060 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""آزمون کور سرمایه‌گذار — «عدد را او می‌گوید، بعد جواب برنامه رو می‌شود». + +این پرونده برای روز نمایش و پس از آن ساخته شده و چهار کار می‌کند: + +۱) از دادهٔ همین اسنپ‌شات چند پرسش عددی می‌سازد که سرمایه‌گذار بتواند با ماشین‌حساب + معمولی بازتولیدشان کند؛ +۲) حدس سرمایه‌گذار را ثبت می‌کند و با جواب موتور می‌سنجد (دفتر زنجیره‌هش‌دار)؛ +۳) برگهٔ چاپی دواِمضا می‌سازد: پرسش، حدس، جواب، مسیر محاسبه، محاسبهٔ دستی دوم، + «کِی می‌افتد» و اثر انگشت دفتر؛ +۴) پیمان‌نامهٔ نمایش می‌نویسد: چه چیزی اثبات می‌شود و چه چیزی نه. + +قاعده‌های صداقت که در کد اعمال شده‌اند: +- هیچ عدد سودی «تضمین‌شده» نیست؛ همه از قیمت‌های همین اسنپ‌شات و کارمزدهای واقعی می‌آید. +- هر جواب یک «محاسبهٔ دستی دوم» جدا دارد (کسر دقیق + فرمول قابل اجرا) و اگر نخواند، + آزمون می‌افتد تا سند بی‌اعتبار لو برود. +- هیچ چیزی به بیرون فرستاده نمی‌شود؛ دفتر و برگه‌ها محلی‌اند. +""" + +from __future__ import annotations + +import argparse +import hashlib +import importlib.util +import json +import sys +from datetime import datetime, timezone +from fractions import Fraction +from pathlib import Path + +VERSION = "0.1.0" + +BASE = Path(__file__).resolve().parent +DATA = BASE / "data" +TOOLS = (BASE.parent / "tools").resolve() +DESK = (BASE.parent / "desk").resolve() +LOG_FILE = DATA / "investor-blind-test.json" +SHEET_HTML = DATA / "investor-blind-test.html" +SHEET_MD = DATA / "investor-blind-test.md" +PLEDGE_MD = DATA / "investor-pledge.md" + +HURDLE_DEFAULT = 0.35 # نرخ سد پیش‌فرض (همان عدد ایستگاه، قابل جایگزینی با عدد شرکت) +GO_THRESHOLD = 0.03 # آستانهٔ «ارزش دارد» برای پوشش‌داده + +CREDIT_HTML = ( + '✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · ' + '📱 +989126630554 · ' + '✈️ Telegram: Mojarabian · ' + '📸 Instagram: Mojarabian.Art') +CREDIT_MD = ("✍️ تهیه‌کنندهٔ جزوات: **Masoud Mojarabian** · 📱 +989126630554 · " + "✈️ Telegram: [Mojarabian](https://t.me/Mojarabian) · " + "📸 Instagram: [Mojarabian.Art](https://instagram.com/Mojarabian.Art)") + +KIND_TITLES = { + "basis": "مبنا (خرید نقدی + فروش آتی)", + "box": "باکس اسپرد", + "tabei": "اوراق تبعی", + "covered_call": "پوشش‌داده‌شده (فروش اختیار خرید)", + "parity": "تساوی پوت-کال", +} + +TAKE_PROFIT_FRACTION = 0.50 # برداشت سود: ۵۰٪ بازده انتظاری +STOP_LOSS_FRACTION = 0.40 # توقف ضرر: ۴۰٪ بازده انتظاری +STRATEGY_CAP_FRACTION = 0.75 # سقف هر راهبرد از سرمایهٔ تخصیص‌یافته + + +# ------------------------------------------------------------------ موتور +_ENGINE = None + + +def engine(): + """موتور مشتقه را از tools/ می‌خواند (بدون نصب، بدون اینترنت).""" + global _ENGINE + if _ENGINE is not None: + return _ENGINE + path = TOOLS / "derivatives_scout.py" + if not path.exists(): + raise FileNotFoundError(f"موتور پیدا نشد: {path}") + spec = importlib.util.spec_from_file_location("derivatives_scout", path) + mod = importlib.util.module_from_spec(spec) + sys.modules["derivatives_scout"] = mod # لازم برای @dataclass داخل موتور + spec.loader.exec_module(mod) + _ENGINE = mod + return mod + + +def demo_rows() -> list[dict]: + """ردیف‌ها: اول پروندهٔ بازار ایستگاه، بعد نمونهٔ خود موتور.""" + f = DESK / "market-demo.json" + if f.exists(): + try: + data = json.loads(f.read_text(encoding="utf-8")) + got = data.get("rows") if isinstance(data, dict) else data + rows = [r for r in (got or []) if isinstance(r, dict) and r.get("kind")] + if rows: + return rows + except (json.JSONDecodeError, OSError): + pass + return list(engine().DEMO["rows"]) + + +def fallback_rows() -> list[dict]: + try: + return demo_rows() + except (FileNotFoundError, OSError): + return list(engine().DEMO["rows"]) + + +def _pick(kind: str, rows: list[dict] | None = None) -> dict: + for r in (rows if rows is not None else fallback_rows()): + if r.get("kind") == kind: + return r + raise LookupError(f"ردیفی با نوع «{kind}» پیدا نشد") + + +# ------------------------------------------------------------------ ابزار نمایش عدد +def money(x) -> str: + if x is None: + return "—" + if isinstance(x, Fraction): + x = float(x) + if isinstance(x, float): + return f"{x:,.3f}".rstrip("0").rstrip(".") + return f"{x:,}" + + +def pct(x, digits: int = 3) -> str: + if x is None: + return "—" + return f"{round(float(x), digits):,}٪" + + +def rule(x) -> str: + """عدد داخل فرمول قابل اجرا: بدون جداکننده، بدون نماد درصد.""" + if isinstance(x, Fraction): + x = float(x) + if isinstance(x, float): + return repr(round(x, 8)) + return repr(x) + + +# ------------------------------------------------------------------ محاسبه + سنجش دوم +def _fees(row: dict, kind: str) -> tuple[float, float, float]: + E = engine() + if kind == "basis": + return row.get("fee_buy", E.FEE_FUND_ETF), row.get("fee_sell", E.FEE_FUND_ETF), 0.0 + if kind == "covered_call": + return E.FEE_STOCK_BUY, E.FEE_STOCK_SELL, E.FEE_OPTION_TRADE + if kind == "tabei": + return E.FEE_STOCK_BUY, E.FEE_STOCK_SELL, 0.0 + return 0.0, 0.0, E.FEE_OPTION_TRADE + + +def _annual(period: Fraction, days: float) -> float: + """سالانه‌سازی با کسر دقیق (محاسبهٔ دوم، جدا از کد موتور).""" + t = Fraction(int(days), 365) + return (1 + float(period)) ** (1 / float(t)) - 1 + + +def plain_annual(period_expr: str, days: float) -> str: + """فرمول قابل‌اجرا برای ماشین‌حساب/پایتون: بازده دوره → بازده سالانه → درصد.""" + return f"((({period_expr}) + 1) ** (365.0/{rule(days)}) - 1) * 100" + + +def _agree(got: float, hand: float, tol: float = 0.02) -> bool: + return abs(got - hand) <= max(abs(got) * tol, 0.001) + + +def _given(row: dict, kind: str) -> list[tuple[str, str]]: + if kind == "basis": + return [("قیمت نقدی", money(row["spot"])), ("قیمت آتی", money(row["future"])), + ("روز تا سررسید", money(row["days"]))] + if kind == "box": + return [("کال اعمال پایین", money(row["call_low"])), ("پوت اعمال پایین", money(row["put_low"])), + ("کال اعمال بالا", money(row["call_high"])), ("پوت اعمال بالا", money(row["put_high"])), + ("اعمال پایین", money(row["strike_low"])), ("اعمال بالا", money(row["strike_high"])), + ("روز تا سررسید", money(row["days"]))] + if kind == "tabei": + return [("قیمت سهم", money(row["stock_price"])), ("قیمت پوت", money(row["put_price"])), + ("قیمت اعمال تضمینی", money(row["strike"])), ("روز تا سررسید", money(row["days"]))] + if kind == "covered_call": + return [("قیمت سهم", money(row["spot"])), ("قیمت اعمال کال", money(row["strike"])), + ("پرمیوم کال", money(row["premium"])), ("روز تا سررسید", money(row["days"]))] + if kind == "sizing": + return [("سرمایه", money(row.get("capital", 20_000_000_000.0)) + " ریال"), + ("سقف ریسک", pct(float(row.get("risk_pct", 0.20)) * 100, 0)), + ("وجه تضمین هر قرارداد", money(row.get("margin_per_contract", 2_000_000_000.0)) + " ریال")] + if kind == "parity": + return [("قیمت کال", money(row["call"])), ("قیمت پوت", money(row["put"])), + ("قیمت سهم", money(row["spot"])), ("قیمت اعمال", money(row["strike"])), + ("روز تا سررسید", money(row["days"])), + ("نرخ بدون ریسک", pct(row.get("rate", 0.35) * 100, 0))] + return [] + + +def solve(row: dict) -> dict: + """هر ردیف را حل می‌کند و کنار جواب موتور، محاسبهٔ دستی دوم و فرمول اجراپذیر می‌گذارد.""" + E = engine() + kind = row.get("kind") + fb, fs, fo = _fees(row, kind) + hurdle = float(row.get("hurdle") or HURDLE_DEFAULT) + out: dict = {"kind": kind, "title": row.get("name") or KIND_TITLES.get(kind, kind), + "given": _given(row, kind), "hurdle": hurdle, "checks": [], "steps": [], + "extras": {}, "answer_num": None, "answer": None, "unit": "", "formula": "", + "formula_plain": ""} + + if kind == "basis": + res = E.basis_opportunity(row["spot"], row["future"], row["days"], hurdle, fb, fs, + row.get("storage_annual", 0.0)) + buy = Fraction(str(row["spot"])) * (1 + Fraction(str(fb)).limit_denominator(10 ** 6)) + sell = Fraction(str(row["future"])) * (1 - Fraction(str(fs)).limit_denominator(10 ** 6)) + hand = _annual((sell - buy) / buy, row["days"]) * 100 + out.update( + answer_num=res["annualized_pct"], answer=res["annualized_pct"], unit="٪ سالانه", + formula=(f"سود هر واحد = {money(row['future'])}×(۱−{pct(fs * 100)}) − " + f"{money(row['spot'])}×(۱+{pct(fb * 100)}) = {money(res['net_gain_per_unit'])}، " + f"بعد بازده دوره ÷ قیمت تمام‌شده و توان ۳۶۵÷{row['days']}"), + formula_plain=plain_annual( + f"({rule(row['future'])}*(1-{rule(fs)}) - {rule(row['spot'])}*(1+{rule(fb)})) / " + f"({rule(row['spot'])}*(1+{rule(fb)}))", row["days"]), + steps=[f"بازده دوره = سود ÷ قیمت تمام‌شده = {pct(res['period_return_pct'])}", + f"بازده سالانه = (۱+بازده دوره)^(۳۶۵÷{row['days']}) − ۱ = {pct(res['annualized_pct'])}", + f"نرخ سد امروز {pct(hurdle * 100, 1)} و حاشیه " + f"{money(res['edge_pp'])} واحد درصد است"], + extras={"سود هر واحد": money(res["net_gain_per_unit"]), + "بازده دوره": pct(res["period_return_pct"]), + "کارمزد خرید و فروش": f"{pct(fb * 100)} + {pct(fs * 100)}"}, + checks=[{"note": "محاسبهٔ دستی با کسر دقیق (بدون کد موتور)", "value": round(hand, 3), + "agree": _agree(res["annualized_pct"], hand)}]) + elif kind == "box": + res = E.box_spread(row["call_low"], row["put_low"], row["call_high"], row["put_high"], + row["strike_low"], row["strike_high"], row["days"]) + debit = Fraction(str((row["call_low"] + row["put_high"]) - (row["put_low"] + row["call_high"]))) + payoff = Fraction(str(row["strike_high"] - row["strike_low"])) + legs = Fraction(str(row["call_low"] + row["put_low"] + row["call_high"] + row["put_high"])) + fees = legs * Fraction(str(E.FEE_OPTION_TRADE)).limit_denominator(10 ** 6) + hand = _annual((payoff - debit - fees) / debit, row["days"]) * 100 + out.update( + answer_num=res["annualized_pct"], answer=res["annualized_pct"], unit="٪ سالانه", + formula=(f"بدهی امروز = {money(debit)} · دریافتی قطعی در سررسید = {money(payoff)} · " + f"کارمزد چهار طرف = {money(float(fees))}"), + formula_plain=plain_annual( + f"({rule(payoff)} - {rule(debit)} - " + f"(({rule(row['call_low'])}+{rule(row['put_low'])}+{rule(row['call_high'])}" + f"+{rule(row['put_high'])})*{rule(E.FEE_OPTION_TRADE)})) / ({rule(debit)})", + row["days"]), + steps=[f"سود خالص = دریافتی − بدهی − کارمزد = {money(res['net_profit'])}", + f"بازده سالانه = (۱+سود÷بدهی)^(۳۶۵÷{row['days']}) − ۱ = {pct(res['annualized_pct'])}"], + extras={"بدهی": money(debit), "دریافتی قطعی": money(payoff), + "کارمزد چهار طرف": money(float(fees)), "سود خالص": money(res["net_profit"])}, + checks=[{"note": "محاسبهٔ دستی با کسر دقیق روی چهار پایه", "value": round(hand, 3), + "agree": _agree(res["annualized_pct"], hand)}]) + elif kind == "tabei": + res = E.tabei_min_yield(row["stock_price"], row["put_price"], row["strike"], row["days"], fb, fs) + cost = (Fraction(str(row["stock_price"])) * (1 + Fraction(str(fb)).limit_denominator(10 ** 6)) + + Fraction(str(row["put_price"]))) + proceeds = Fraction(str(row["strike"])) * (1 - Fraction(str(fs)).limit_denominator(10 ** 6)) + hand = _annual((proceeds - cost) / cost, row["days"]) * 100 + out.update( + answer_num=res["annualized_pct"], answer=res["annualized_pct"], + unit="٪ سالانه (کمینهٔ تضمینی)", + formula=(f"هزینهٔ خرید = {money(row['stock_price'])}×(۱+{pct(fb * 100)}) + پوت " + f"{money(row['put_price'])} = {money(res['cost_basis'])} · دریافتی تضمینی = " + f"{money(row['strike'])}×(۱−{pct(fs * 100)}) = {money(res['guaranteed_proceeds'])}"), + formula_plain=plain_annual( + f"({rule(row['strike'])}*(1-{rule(fs)}) - " + f"({rule(row['stock_price'])}*(1+{rule(fb)}) + {rule(row['put_price'])})) / " + f"({rule(row['stock_price'])}*(1+{rule(fb)}) + {rule(row['put_price'])})", + row["days"]), + steps=[f"بازده دوره = (دریافتی تضمینی − هزینهٔ خرید) ÷ هزینهٔ خرید = " + f"{pct(res['period_return_pct'])}", + f"بازده سالانه = (۱+بازده دوره)^(۳۶۵÷{row['days']}) − ۱ = {pct(res['annualized_pct'])}"], + extras={"هزینهٔ خرید": money(res["cost_basis"]), + "دریافتی تضمینی": money(res["guaranteed_proceeds"])}, + checks=[{"note": "محاسبهٔ دستی با کسر دقیق (کارمزد سهم + پوت)", "value": round(hand, 3), + "agree": _agree(res["annualized_pct"], hand)}]) + elif kind == "covered_call": + res = E.covered_call(row["spot"], row["strike"], row["premium"], row["days"], fb, fs, fo) + base = Fraction(str(row["spot"])) * (1 + Fraction(str(fb)).limit_denominator(10 ** 6)) + prem = Fraction(str(row["premium"])) * (1 - Fraction(str(fo)).limit_denominator(10 ** 6)) + hand = _annual(prem / base, row["days"]) * 100 + out.update( + answer_num=res["premium_annualized_pct"], answer=res["premium_annualized_pct"], + unit="٪ سالانه (فقط پرمیوم)", + formula=(f"پرمیوم خالص = {money(row['premium'])}×(۱−{pct(fo * 100)}) = {money(float(prem))} " + f"÷ قیمت تمام‌شدهٔ سهم {money(float(base))}"), + formula_plain=plain_annual( + f"({rule(row['premium'])}*(1-{rule(fo)})) / ({rule(row['spot'])}*(1+{rule(fb)}))", + row["days"]), + steps=[f"درآمد پرمیوم دوره = {pct(float(prem / base) * 100)}", + f"بازده سالانهٔ پرمیوم = (۱+درآمد دوره)^(۳۶۵÷{row['days']}) − ۱ = " + f"{pct(res['premium_annualized_pct'])}", + f"سقف رشد سهم با این پوشش = {pct(res['upside_capped_at_pct'])} " + f"(بخش بازار-ریسک، جدا از پرمیوم)"], + extras={"سقف رشد سهم": pct(res["upside_capped_at_pct"]), + "ارزش دارد؟": "بله" if res.get("go") else "نه", + "بازده دوره": pct(round(float(prem / base) * 100, 3))}, + checks=[{"note": "محاسبهٔ دستی پرمیوم با کسر دقیق", "value": round(hand, 3), + "agree": _agree(res["premium_annualized_pct"], hand)}]) + elif kind == "parity": + res = E.put_call_parity(row["call"], row["put"], row["spot"], row["strike"], row["days"], + row.get("rate", HURDLE_DEFAULT)) + editable = float(res["gap"]) - float(res["costs_estimate"]) + hand_agree = abs(editable - float(res["conversion_edge_per_unit"])) < 0.01 + out.update( + answer="بله" if res.get("go") else "نه", answer_bool=bool(res.get("go")), + unit="بله/نه", answer_num=None, + formula=(f"سمت چپ کال−پوت = {money(res['lhs_call_minus_put'])} · سمت راست سهم−ارزش فعلی " + f"اعمال = {money(res['rhs_spot_minus_pv_strike'])} · شکاف = {money(res['gap'])} · " + f"کارمزد سه پایه = {money(res['costs_estimate'])}"), + formula_plain="", + steps=[f"اختلاف قابل برداشت = شکاف − کارمزد = {money(res['conversion_edge_per_unit'])}", + f"داوری: {'صرفه دارد' if res.get('go') else 'صرفه ندارد'} — سمت معکوس در ایران " + f"ممکن نیست (فروش استقراضی نداریم)"], + extras={"شکاف": money(res["gap"]), "کارمزد سه پایه": money(res["costs_estimate"]), + "اختلاف قابل برداشت": money(res["conversion_edge_per_unit"])}, + checks=[{"note": "محاسبهٔ دستی: شکاف منهای کارمزد سه پایه", "value": round(editable, 2), + "agree": hand_agree}]) + elif kind == "sizing": + capital = float(row.get("capital", 20_000_000_000.0)) + margin = float(row.get("margin_per_contract", 2_000_000_000.0)) + risk = float(row.get("risk_pct", 0.20)) + res = E.position_size(capital, margin, risk) + out.update( + answer_num=res["contracts"], answer=res["contracts"], unit="قرارداد", + formula=(f"بودجهٔ ریسک = {money(capital)} × {pct(risk * 100, 0)} = {money(capital * risk)} " + f"÷ وجه تضمین هر قرارداد {money(margin)}"), + formula_plain=f"{rule(capital)}*{rule(risk)}//{rule(margin)}", + steps=[f"تعداد قرارداد = کف({money(capital * risk)} ÷ {money(margin)}) = {res['contracts']}", + f"وجه تضمین قفل‌شده = {money(res['margin_locked'])} · نقد آزاد = {money(res['free_cash'])}"], + extras={"سرمایه": money(capital), "سقف ریسک": pct(risk * 100, 0), + "وجه تضمین هر قرارداد": money(margin)}, + checks=[{"note": "محاسبهٔ دستی: تقسیم صحیح بودجهٔ ریسک بر وجه تضمین", + "value": int(capital * risk // margin), + "agree": int(capital * risk // margin) == res["contracts"]}]) + else: + raise ValueError(f"نوع ناشناخته: {kind}") + return out + + +# ------------------------------------------------------------------ پلهٔ «کِی می‌افتد» +def _exit_price(row: dict, annual_pct: float, *, mode: str) -> float | None: + base = row.get("spot") or row.get("stock_price") or row.get("strike") or row.get("strike_low") + days = float(row.get("days") or 0) + if not base or days <= 0: + return None + period = (1 + annual_pct / 100) ** (days / 365) - 1 + frac = TAKE_PROFIT_FRACTION if mode == "take_profit" else -STOP_LOSS_FRACTION + return round(float(base) * (1 + period * frac), 3) + + +def _fees_total_pct(row: dict) -> float: + kind = row.get("kind") + E = engine() + if kind == "basis": + return round((row.get("fee_buy", E.FEE_FUND_ETF) + row.get("fee_sell", E.FEE_FUND_ETF)) * 100, 4) + if kind == "covered_call": + return round((E.FEE_STOCK_BUY + E.FEE_STOCK_SELL + E.FEE_OPTION_TRADE) * 100, 4) + if kind == "tabei": + return round((E.FEE_STOCK_BUY + E.FEE_STOCK_SELL) * 100, 4) + if kind in ("box", "parity"): + return round(E.FEE_OPTION_TRADE * (4 if kind == "box" else 3) * 100, 4) + return 0.0 + + +def ladder_for(row: dict, *, hurdle: float | None = None) -> dict: + """برای یک ردیف می‌گوید: می‌ماند یا می‌افتد، و سه حد خروج کجاست.""" + solved = solve(row) + kind = row.get("kind") + base = float(row.get("hurdle") or (hurdle if hurdle is not None else HURDLE_DEFAULT)) + if hurdle is not None: + base = float(hurdle) + annual = float(solved.get("answer_num") or 0.0) + days = float(row.get("days") or 0) + fees = _fees_total_pct(row) + + if kind == "parity": + return {"kind": kind, "title": solved["title"], "given": solved["given"], "ladder": [], + "survives": False, "annualized_pct": None, "hurdle_pct": round(base * 100, 3), + "margin_pp": None, "fees_pct": fees, + "verdict": ("امروز «نه»: انحراف تساوی از کارمزد سه پایه کمتر است، پس چیزی برای " + "برداشتن نیست. هر وقت شکاف بزرگ‌تر شد، همین خط دوباره چک می‌شود."), + "why": (f"کارمزد سه پایه ({fees}٪) اول از شکاف کسر می‌شود و بعد نتیجه با نرخ سد " + f"سنجیده می‌شود؛ سمت معکوس هم در ایران عملی نیست."), + "check": solved["checks"]} + + survives = annual > base * 100 and annual > 0 + ladder = [ + {"label": "برداشت سود", "when": f"{int(TAKE_PROFIT_FRACTION * 100)}٪ بازده انتظاری", + "price": _exit_price(row, annual, mode="take_profit"), "action": "خروج و ثبت در دفتر"}, + {"label": "توقف ضرر", "when": f"{int(STOP_LOSS_FRACTION * 100)}٪ بازده انتظاری", + "price": _exit_price(row, annual, mode="stop_loss"), "action": "خروج بی‌مذاکره"}, + {"label": "سررسید", "when": f"{int(days)} روز" if days else "—", + "price": "—", "action": "خروج در سررسید، حتی اگر هدف نخورده باشد"}, + ] + if annual <= 0: + verdict = (f"«می‌افتد»: بازده خالص منفی است ({annual:.3f}٪). این ردیف فقط ثبت می‌شود و " + f"اجرا نمی‌شود.") + elif not survives: + verdict = (f"«می‌افتد»: بازده سالانهٔ امروز {annual:.3f}٪ از نرخ سد {base * 100:.1f}٪ عبور " + f"نمی‌کند؛ پس هیچ اقدامی نمی‌کنیم.") + else: + verdict = (f"«می‌ماند» با حاشیهٔ {annual - base * 100:.3f} واحد درصد: تا وقتی نرخ سد زیر " + f"{annual:.3f}٪ بماند، این معامله ارزش بررسی دارد.") + why = (f"عدد خالص است: اول کارمزد ({fees}٪ مجموع) کسر شده، بعد با نرخ سد سنجیده شده. " + f"نقطهٔ برگشت روشن است: اگر نرخ سد از {annual:.3f}٪ بگذرد، همین سیگنال می‌افتد؛ " + f"و اگر کارمزد کارگزاری شما جای دیگری بود، همان عدد را در برنامه جایگزین می‌کنیم.") + return {"kind": kind, "title": solved["title"], "given": solved["given"], "ladder": ladder, + "survives": survives, "annualized_pct": round(annual, 3), + "hurdle_pct": round(base * 100, 3), "margin_pp": round(annual - base * 100, 3), + "fees_pct": fees, "verdict": verdict, "why": why, "check": solved["checks"], + "capital_pct": STRATEGY_CAP_FRACTION * 100} + + +def sensitivity(rows: list[dict] | None = None) -> dict: + """شکنندگی: نرخ سد، کارمزد، اسپرد/نقدشوندگی — همه با عدد.""" + rows = rows if rows is not None else fallback_rows() + out = {"rows": [], "fee_break": None, "spread_note": ""} + for kind in ("basis", "box", "tabei", "covered_call"): + try: + row = _pick(kind, rows) + except LookupError: + continue + lead = ladder_for(row) + out["rows"].append({"kind": kind, "title": lead["title"], + "annualized_pct": lead["annualized_pct"], "hurdle_now_pct": lead["hurdle_pct"], + "breaks_if_hurdle_above_pct": lead["annualized_pct"], + "survives": lead["survives"], "margin_pp": lead["margin_pp"]}) + try: + out["fee_break"] = fee_flip(_pick("covered_call", rows)) + except LookupError: + pass + spreads = [float(r.get("spread_pct") or 0) * 100 for r in rows if r.get("spread_pct")] + liq = [r.get("liquidity_contracts_per_day") for r in rows if r.get("liquidity_contracts_per_day")] + out["spread_note"] = ( + f"بیشترین اسپرد ثبت‌شده {pct(max(spreads))} و کم‌ترین نقدشوندگی " + f"{money(min(liq))} قرارداد در روز است؛ هر ردیفی که نقدشوندگی‌اش کم باشد در تصمیم " + f"علامت می‌خورد." if spreads or liq else + "اسپرد و نقدشوندگی در اسنپ‌شات ثبت نشده است؛ بدون آن‌ها هم برنامه تصمیم نمی‌سازد.") + return out + + +def fee_flip(row: dict | None = None, *, target: float = GO_THRESHOLD, hi: float = 0.60) -> dict: + """کارمزد فروش سهم تا چند درصد بالا برود که پوشش‌داده دیگر ارزش نداشته باشد.""" + E = engine() + row = row or _pick("covered_call") + + def annual(fee: float) -> float: + r = E.covered_call(row["spot"], row["strike"], row["premium"], row["days"], + E.FEE_STOCK_BUY, fee, E.FEE_OPTION_TRADE) + return r["premium_annualized_pct"] / 100 + + lo = 0.0 + if annual(hi) > target: + return {"name": row.get("name") or KIND_TITLES["covered_call"], + "fee_now_pct": E.FEE_STOCK_SELL * 100, "fee_flip_pct": None, "sensitive": False, + "threshold_pct": target * 100, "days": row["days"], "searched_to_pct": hi * 100, + "meaning": (f"این معامله به کارمزد فروش سهم حساس نیست: حتی با کارمزد " + f"{pct(hi * 100, 0)} هم درآمد پرمیوم بالای آستانهٔ {pct(target * 100)} " + f"می‌ماند. چیزی که این تصمیم را عوض می‌کند کارمزد نیست؛ نرخ سد و " + f"ریسک بازار است.")} + for _ in range(60): + mid = (lo + hi) / 2 + if annual(mid) > target: + lo = mid + else: + hi = mid + flip = round((lo + hi) / 2 * 100, 3) + return {"name": row.get("name") or KIND_TITLES["covered_call"], + "fee_now_pct": E.FEE_STOCK_SELL * 100, "fee_flip_pct": flip, "sensitive": True, + "threshold_pct": target * 100, "days": row["days"], "searched_to_pct": 60.0, + "meaning": (f"اگر کارمزد فروش سهم از {flip}٪ بگذرد، این پوشش‌داده کم‌تر از آستانهٔ " + f"{pct(target * 100)} سالانه می‌دهد و باید رد شود.")} + + +# ------------------------------------------------------------------ پرسش‌ها +QUESTIONS = { + "basis": ("اگر امروز این دارایی را نقد بخری و همان لحظه در بازار آتی بفروشی و تا سررسید " + "نگه داری، بازده سالانه‌ات بعد از کارمزد چند درصد می‌شود؟"), + "box": ("در این باکس اسپرد امروز چه‌قدر پول می‌دهی و در سررسید چه‌قدر قطعی می‌گیری؟ " + "بازده سالانه‌اش چند درصد است؟"), + "tabei": ("اگر این سهم را امروز بخری و این پوت تبعی را بخری و تا سررسید نگه داری، " + "کمینهٔ بازده تضمینی‌ات سالانه چند درصد است؟"), + "covered_call": ("اگر امروز این سهم را بخری و این اختیار خرید را بفروشی و سررسید اعمال شود، " + "درآمد سالانه‌ات فقط از پرمیوم چند درصد است؟"), + "parity": ("در این تساوی پوت-کال، اگر سهم را بخری و پوت را بخری و کال را بفروشی، " + "با توجه به کارمزدها صرفه دارد یا نه؟"), + "sizing": ("با این سرمایه و این سقف ریسک و این وجه تضمین، حداکثر چند قرارداد می‌شود باز کرد؟"), +} + +_HIDDEN = ("answer", "answer_num", "answer_bool", "formula", "formula_plain", "steps", "extras", + "checks", "ladder", "hand") + + +def cases(reveal: bool = False, *, rows: list[dict] | None = None, + capital: float = 20_000_000_000.0, margin_per_contract: float = 2_000_000_000.0, + risk_pct: float = 0.20) -> list[dict]: + """پرسش‌ها. تا وقتی reveal=True نشود، هیچ جوابی داخلشان نیست (آزمون کور واقعی).""" + rows = rows if rows is not None else fallback_rows() + out: list[dict] = [] + for kind in ("basis", "box", "tabei", "covered_call", "parity"): + try: + row = _pick(kind, rows) + except LookupError: + continue + s = solve(row) + out.append({"id": f"{kind}_{'annual' if s['answer_num'] is not None else 'yn'}", + "kind": kind, "title": s["title"], "question": QUESTIONS[kind], + "given": s["given"], "ladder": ladder_for(row), **s}) + sizing_row = {"kind": "sizing", "capital": capital, "margin_per_contract": margin_per_contract, + "risk_pct": risk_pct} + s = solve(sizing_row) + out.append({"id": "sizing", "kind": "sizing", "title": "اندازهٔ موقعیت — چند قرارداد؟", + "question": QUESTIONS["sizing"], "given": s["given"], + "ladder": ladder_for(sizing_row), **s}) + if not reveal: + out = [{k: v for k, v in c.items() if k not in _HIDDEN} for c in out] + return out + + +def answer_text(case: dict) -> str: + ans = case.get("answer") + if isinstance(ans, bool): + return "بله" if ans else "نه" + if isinstance(ans, (int, float)): + return f"{money(ans)} {case.get('unit', '')}".strip() + return str(ans) + + +def find_case(case_id: str, **kw) -> dict: + for c in cases(reveal=True, **kw): + if c["id"] == case_id: + return c + raise KeyError(f"پرسش «{case_id}» پیدا نشد") + + +# ------------------------------------------------------------------ دفتر زنجیره‌هش‌دار +def _prev_chain(path: Path) -> str: + rows = read_log(path) + return rows[-1].get("chain", "0" * 16) if rows else "0" * 16 + + +def chain_hash(payload: dict, prev: str) -> str: + body = json.dumps(payload, sort_keys=True, ensure_ascii=False) + return hashlib.sha256(f"{prev}|{body}".encode("utf-8")).hexdigest()[:16] + + +def read_log(path: Path | str | None = None) -> list[dict]: + p = Path(path or LOG_FILE) + if not p.exists(): + return [] + try: + data = json.loads(p.read_text(encoding="utf-8")) + return data if isinstance(data, list) else [] + except (json.JSONDecodeError, OSError): + return [] + + +def append_guess(record: dict, *, path: Path | str | None = None) -> dict: + p = Path(path or LOG_FILE) + p.parent.mkdir(parents=True, exist_ok=True) + rows = read_log(p) + rec = dict(record) + rec["ts"] = rec.get("ts") or datetime.now(timezone.utc).isoformat(timespec="seconds") + rec["chain"] = chain_hash({k: v for k, v in rec.items() if k != "chain"}, _prev_chain(p)) + rows.append(rec) + p.write_text(json.dumps(rows, ensure_ascii=False, indent=1), encoding="utf-8") + return rec + + +def verify_chain(path: Path | str | None = None) -> dict: + rows = read_log(path) + prev = "0" * 16 + for i, r in enumerate(rows): + want = chain_hash({k: v for k, v in r.items() if k != "chain"}, prev) + if want != r.get("chain"): + return {"ok": False, "rows": len(rows), "broken_at": i + 1, "chain": prev, + "last_fingerprint": prev, + "detail": f"سطر {i + 1} با اثر انگشت زنجیره نمی‌خواند؛ یعنی بعد از ثبت " + f"دست‌کاری شده است."} + prev = r["chain"] + return {"ok": True, "rows": len(rows), "broken_at": None, "chain": prev, + "last_fingerprint": prev, + "detail": ("زنجیره سالم است؛ هیچ سطر دست‌کاری‌شده‌ای پیدا نشد." if rows else + "دفتر هنوز خالی است؛ بعد از اولین ثبت پر می‌شود.")} + + +# ------------------------------------------------------------------ سنجش حدس +_YES = {"بله", "بلی", "اره", "آره", "درست", "yes", "y", "true", "1"} +_NO = {"نه", "خیر", "نادرست", "no", "n", "false", "0"} + + +def _as_bool(v) -> bool | None: + s = str(v).strip().lower().replace("‌", "") + if s in _YES: + return True + if s in _NO: + return False + return None + + +def _as_number(v) -> float | None: + if v is None: + return None + s = str(v).replace(",", "").replace("٬", "").replace("٪", "").replace("%", "").strip() + try: + return float(s) + except ValueError: + return None + + +def judge(guess, note: str | None = None, *, case_id: str, client: str = "", + path: Path | str | None = None, **kw) -> dict: + """حدس سرمایه‌گذار را ثبت و داوری می‌کند: دقیقاً درست / نزدیک / دور / درست / نادرست / بی‌عدد.""" + case = find_case(case_id, **kw) + status, delta = "بی‌عدد", None + if case.get("answer_bool") is not None: + g = _as_bool(guess) + if g is None: + status = "بی‌عدد" + else: + status = "درست" if g == bool(case["answer_bool"]) else "نادرست" + guess_val = None if g is None else g + else: + g = _as_number(guess) + guess_val = g + if g is None: + status = "بی‌عدد" + else: + a = float(case["answer_num"]) + delta = round(abs(g - a) / max(abs(a), 1e-9) * 100, 3) if a else round(abs(g) * 100, 3) + status = "دقیقاً درست" if delta < 2 else ("نزدیک" if delta < 10 else "دور") + notes = {"دقیقاً درست": "دقیقاً همان عددی که موتور می‌دهد.", + "نزدیک": "خیلی نزدیک؛ اختلاف از گرد کردن یا ترتیب کارمزدها است.", + "دور": "فاصله زیاد است؛ همین‌جا ارزش برنامه معلوم می‌شود: کارمزد و سالانه‌سازی و نرخ سد.", + "درست": "درست گفتید؛ با کارمزد واقعی این معامله برداشتنی نیست.", + "نادرست": "اینجا اختلاف است؛ همین مسیر محاسبه را با هم می‌بینیم.", + "بی‌عدد": "عدد یا «بله/نه» روشنی ثبت نشد، پس داوری نشد."} + rec = append_guess({"kind": "guess", "case": case_id, "title": case["title"], "client": client, + "guess_raw": str(guess), "guess": guess_val, "note": note or "", + "answer": case.get("answer"), "unit": case.get("unit", ""), + "delta_pct": delta, "status": status, + "engine": getattr(engine(), "VERSION", "?")}, path=path) + return {"case_id": case_id, "case": case, "status": status, "delta_pct": delta, + "note": notes[status], "record": rec} + + +def check(case_id: str, guess, *, client: str = "", path: Path | str | None = None, + **kw) -> dict: + """شکل سازگار با گام ۱۰ رابط: همان داوری، با کلیدهایی که کارت‌های مرورگری می‌خوانند.""" + try: + res = judge(guess, None, case_id=case_id, client=client, path=path, **kw) + except KeyError as e: + return {"ok": False, "error": str(e)} + c = res["case"] + return {"ok": True, "id": case_id, "title": c["title"], "answer": answer_text(c), + "unit": c.get("unit", ""), "verdict": res["status"], "off_pct": res["delta_pct"], + "formula": c.get("formula", ""), "second": "; ".join( + f"{ch['note']} = {money(ch['value'])}" for ch in c.get("checks", [])), + "note": res["note"], "chain": res["record"]["chain"]} + + +def strategy_table(rows: list[dict] | None = None, + hurdles: tuple[float, ...] = (0.30, 0.35, 0.40, 0.50)) -> dict: + """جدول آستانهٔ ریزش: برای هر راهبرد، با هر نرخ سد می‌گذرد یا می‌افتد.""" + rows = rows if rows is not None else fallback_rows() + out_rows = [] + for row in rows: + if not row.get("kind"): + continue + try: + s = solve(row) + except (KeyError, ValueError, ZeroDivisionError): + continue + annual = s.get("answer_num") + cells = {} + for h in hurdles: + edge = None if annual is None else round(float(annual) - h * 100, 3) + cells[str(h)] = {"go": bool(annual is not None and float(annual) > h * 100), + "edge_pp": edge} + out_rows.append({"name": s["title"], "kind": row.get("kind"), + "annualized_pct": annual, "cells": cells}) + passed = len([1 for r in out_rows if r["cells"].get(str(hurdles[0]), {}).get("go")]) + verdict = (f"{len(out_rows)} راهبرد سنجیده شد؛ با نرخ سد {hurdles[0] * 100:.0f}٪ " + f"{passed} راهبرد از سد عبور می‌کند. عددها بعد از کارمزد واقعی‌اند و هیچ‌کدام " + f"تضمین سود نیست؛ ستون‌ها نشان می‌دهند با بالا رفتن نرخ سد کدام راهبرد می‌افتد.") + return {"hurdles": list(hurdles), "rows": out_rows, "verdict": verdict} + + +def size_sensitivity(capital: float = 100_000_000.0, margin_per_contract: float = 2_000_000.0, + caps: tuple[float, ...] = (0.10, 0.20, 0.30, 0.40)) -> list[dict]: + """اندازهٔ موقعیت در چند سقف ریسک (عددها فقط نشان می‌دهند وجه تضمین چقدر قفل می‌شود).""" + E = engine() + out = [] + for cap in caps: + res = E.position_size(capital, margin_per_contract, cap) + out.append({"risk_pct": round(cap * 100, 1), "contracts": res["contracts"], + "margin_locked": round(res["margin_locked"], 2), + "free_cash": round(res["free_cash"], 2)}) + return out + + +def reconcile(*, symbol: str = "بدون‌نام", entry, exit, days=30, units=1, expected=None, + path: Path | str | None = None) -> dict: + """حساب‌رسی یک معاملهٔ گذشتهٔ سهم با کارمزد واقعی ایران (بدون اینترنت).""" + E = engine() + try: + e, x, u = float(str(entry).replace(",", "")), float(str(exit).replace(",", "")), float(str(units or 1)) + d = float(str(days or 30)) + except (TypeError, ValueError): + return {"ok": False, "error": "عددهای قیمت خرید، فروش، تعداد و روز باید عدد باشند."} + cost = e * u * (1 + E.FEE_STOCK_BUY) + proceeds = x * u * (1 - E.FEE_STOCK_SELL) + profit = proceeds - cost + period = profit / cost + annual = (1 + period) ** (365 / d) - 1 if d > 0 else None + verdict = ("سود" if profit > 0 else "زیان") + ( + f" · بازده سالانه {pct(annual * 100)}" if annual is not None else "") + compare = "—" + if expected not in (None, "", "—"): + try: + exp = float(str(expected).replace(",", "").replace("٪", "")) + gap = round((annual or 0) * 100 - exp, 3) + compare = (f"انتظار برنامه {exp}٪ سالانه بود؛ نتیجهٔ واقعی " + f"{pct((annual or 0) * 100)} شد؛ اختلاف {money(gap)} واحد درصد. " + f"{'نتیجه بهتر از انتظار بود.' if gap > 0 else 'نتیجه بدتر از انتظار بود.'}") + except ValueError: + compare = "عدد انتظار برنامه خوانده نشد، پس مقایسه انجام نشد." + rec = append_guess({"kind": "reconcile", "symbol": symbol, "entry": e, "exit": x, "units": u, + "days": d, "profit": round(profit, 2), "period_pct": round(period * 100, 3), + "annualized_pct": round(annual * 100, 3) if annual is not None else None, + "expected_pct": expected or "", "note": compare}, path=path) + return {"ok": True, "symbol": symbol, "cost": round(cost, 2), "proceeds": round(proceeds, 2), + "profit": round(profit, 2), "period_pct": round(period * 100, 3), + "annualized_pct": round(annual * 100, 3) if annual is not None else None, + "verdict": verdict, "compare": compare, + "note": (f"کارمزد خرید {pct(E.FEE_STOCK_BUY * 100)} و فروش {pct(E.FEE_STOCK_SELL * 100)} " + f"کسر شده است. این عدد «حساب‌رسی گذشته» است، نه پیش‌بینی آینده."), + "chain": verify_chain(path)} + + +def append_log(record: dict, *, path: Path | str | None = None) -> dict: + """نام سازگار با رابط قدیمی؛ همان دفتر زنجیره‌هش‌دار.""" + return append_guess(record, path=path) + + +def scorecard(*, path: Path | str | None = None) -> dict: + rows = [r for r in read_log(path) if r.get("kind") == "guess"] + close = [r for r in rows if r.get("status") in ("دقیقاً درست", "نزدیک", "درست")] + scored = [r for r in rows if r.get("status") != "بی‌عدد"] + return {"guesses": len(rows), "scored": len(scored), "near": len(close), + "fair_pp": round(len(close) / len(scored) * 100, 1) if scored else None, + "cases_available": len(cases()), "verify": verify_chain(path)} + + +# ------------------------------------------------------------------ برگهٔ چاپی و پیمان‌نامه +def build_sheet(*, client: str = "", sheet_html: Path | str | None = None, + sheet_md: Path | str | None = None, log_path: Path | str | None = None, + rows: list[dict] | None = None) -> dict: + """برگهٔ چاپی دواِمضا: پرسش، حدس، جواب، مسیر محاسبه، «کِی می‌افتد» و اثر انگشت دفتر.""" + import reportkit as rk + + html_path = Path(sheet_html or SHEET_HTML) + md_path = Path(sheet_md or SHEET_MD) + log = read_log(log_path) + guesses = {r["case"]: r for r in log if r.get("kind") == "guess"} + cs = cases(reveal=True, rows=rows) + body = [ + '
    این برگه چه را اثبات می‌کند و چه را نه. ' + 'هر پرسش از دادهٔ همین اسنپ‌شات ساخته شده و سرمایه‌گذار می‌تواند با ماشین‌حساب خودش ' + 'جوابش را بازتولید کند؛ مسیر محاسبه، کارمزدهای فرض‌شده و محاسبهٔ دستیِ دوم در همین ' + 'برگه نوشته شده است. اگر جواب برنامه با محاسبهٔ دستی نخواند، این برگه ارزشی ندارد و ' + 'باید پاره شود. این برگه هیچ ادعایی دربارهٔ سود آینده نمی‌کند و تضمین سود نمی‌کند.
    ', + f'

    سرمایه‌گذار: {rk.esc(client or "—")} · ' + f'تاریخ: {rk.esc(datetime.now().strftime("%Y-%m-%d"))} · نسخهٔ برگزارکننده: {VERSION}

    ', + ] + if not guesses: + body.append('

    هنوز حدسی ثبت نشده است؛ پرسش‌ها را بپرسید و با کادر ' + '«داوری حدس» ثبت کنید تا این برگه پر شود.

    ') + for c in cs: + g = guesses.get(c["id"], {}) + given = "".join(f'{rk.esc(k)}{rk.esc(v)}' + for k, v in c["given"]) + steps = "".join(f"
  • {rk.esc(s)}
  • " for s in c.get("steps", [])) + extras = "".join(f'{rk.esc(k)}{rk.esc(v)}' + for k, v in (c.get("extras") or {}).items()) + checks = "".join( + f'
  • {rk.esc(ch["note"])}: {rk.esc(money(ch["value"]))} — ' + f'{"موافق موتور ✅" if ch["agree"] else "مخالف ⚠️"}
  • ' for ch in c.get("checks", [])) + lead = c.get("ladder") or {} + ladder_rows = "".join( + f'{rk.esc(s["label"])}{rk.esc(s["when"])}' + f'{rk.esc(money(s["price"]) if isinstance(s["price"], (int, float)) else s["price"])}' + f'{rk.esc(s["action"])}' for s in lead.get("ladder", [])) + guess_txt = rk.esc(str(g.get("guess_raw", "—"))) + body.append( + f'

    {rk.esc(c["title"])}

    ' + f'

    {rk.esc(c["question"])}

    ' + f'' + f'{given}
    دادهٔ ورودیعدد
    ' + f'

    پاسخ برنامه: {rk.esc(answer_text(c))}

    ' + f'

    حدس سرمایه‌گذار: {guess_txt} — داوری: ' + f'{rk.esc(str(g.get("status", "ثبت نشده")))}' + + (f' (فاصله {g.get("delta_pct")}٪)' if g.get("delta_pct") is not None else '') + '

    ' + + (f'
    مسیر محاسبهٔ برنامه

    {rk.esc(c.get("formula", ""))}

    ' + f'
      {steps}
    {checks and "
      " + checks + "
    "}' + f'{extras and "" + extras + "
    "}
    ' + if c.get("steps") else '') + + (f'

    این ردیف چه زمانی می‌افتد: {rk.esc(str(lead.get("verdict", "")))}' + f'

    ' + (f'' + f'{ladder_rows}
    حدکِیقیمت/سطحاقدام
    ' + if lead.get("ladder") else '') if lead else '')) + sens = sensitivity(rows) + if sens["rows"]: + grows = "".join( + f'{rk.esc(e["title"])}{pct(e["annualized_pct"])}' + f'{pct(e["hurdle_now_pct"], 1)}' + f'{pct(e["breaks_if_hurdle_above_pct"])}' + f'{money(e["margin_pp"])} واحد درصد' + f'{"می‌ماند ✅" if e["survives"] else "می‌افتد ✗"}' for e in sens["rows"]) + fb = sens["fee_break"] or {} + body.append('

    کِی می‌افتد؟ — نقطهٔ برگشت هر ردیف

    ' + '

    برنامه فقط نمی‌گوید «بخر»؛ می‌گوید با چه نرخی این تصمیم ' + 'می‌افتد. ستون آخر = بازده امروز منهای نرخ سد.

    ' + '' + '' + '' + + grows + '
    راهبردبازده سالانهٔ امروزنرخ سد امروزاگر نرخ سد از این بگذرد می‌افتدحاشیهٔ اطمینانوضعیت
    ' + + (f'

    کارمزد: {rk.esc(fb.get("meaning", ""))}

    ' if fb else '') + + f'

    اسپرد و نقدشوندگی: {rk.esc(sens["spread_note"])}

    ' + '

    این جدول همان چیزی است که «تصمیم» را از «عدد» جدا می‌کند: ' + 'با یک حرکت در نرخ سد، سیگنال می‌افتد و برنامه خودش می‌گوید نه.

    ') + card = scorecard(path=log_path) + if card["scored"]: + body.append(f'
    کارنامهٔ همین جلسه: {card["scored"]} پرسش سنجیده شد و ' + f'{card["near"]} پاسخ نزدیک یا درست بود ({card["fair_pp"]}٪). این عدد دربارهٔ ' + f'سود نمی‌گوید؛ دربارهٔ شهود می‌گوید.
    ') + body.append('

    امضا و شاهد

    ' + f'' + f'' + f'' + '
    اثر انگشت دفتر آزمون{rk.esc(card["verify"]["chain"])}
    تعداد سطر دفتر{len(log)}
    تمامیت زنجیرهٔ هش{"سالم ✅" if card["verify"]["ok"] else "شکسته ⚠️"}
    ' + '

    امضای برگزارکننده: ..................................... · ' + 'امضای سرمایه‌گذار: .....................................

    ' + f'

    {CREDIT_HTML}

    ') + html_path.parent.mkdir(parents=True, exist_ok=True) + html_path.write_text(rk.page("برگهٔ آزمون کور سرمایه‌گذار — عدد را او می‌گوید، بعد جواب برنامه", + "".join(body), + subtitle=f"نسخهٔ {VERSION} · {len(cs)} پرسش از دادهٔ همین اسنپ‌شات"), + encoding="utf-8") + md_path.write_text(_sheet_md(cs, guesses, card, client), encoding="utf-8") + return {"html": str(html_path), "md": str(md_path), "scorecard": card} + + +def _sheet_md(cs: list[dict], guesses: dict, card: dict, client: str) -> str: + L = [f"# برگهٔ آزمون کور سرمایه‌گذار (نسخهٔ {VERSION})", "", + f"سرمایه‌گذار: {client or '—'} · تاریخ: {datetime.now().strftime('%Y-%m-%d')} · " + f"{len(cs)} پرسش از دادهٔ همین اسنپ‌شات", "", + "هر پرسش با ماشین‌حساب معمولی قابل بازتولید است. اگر جواب برنامه با محاسبهٔ دستی " + "نخواند، این برگه بی‌اعتبار است.", ""] + for c in cs: + g = guesses.get(c["id"], {}) + L += [f"## {c['title']}", "", c["question"], "", "| داده | عدد |", "|---|---|"] + L += [f"| {k} | {v} |" for k, v in c["given"]] + L += ["", f"**پاسخ برنامه:** {answer_text(c)}", ""] + for ch in c.get("checks", []): + L.append(f"- محاسبهٔ دستی: {ch['note']} = {money(ch['value'])} " + f"({'موافق' if ch['agree'] else 'مخالف ⚠️'})") + L += ["", f"**حدس سرمایه‌گذار:** {g.get('guess_raw', '—')} — {g.get('status', 'ثبت نشده')}", ""] + for s in c.get("steps", []): + L.append(f"- {s}") + lead = c.get("ladder") or {} + if lead.get("verdict"): + L += ["", f"**کِی می‌افتد:** {lead['verdict']}", f"**چرا:** {lead.get('why', '')}"] + for s in lead.get("ladder", []): + L.append(f" - {s['label']} — {s['when']} → {s['price']} → {s['action']}") + L.append("") + sens = sensitivity() + if sens["rows"]: + L += ["# کِی می‌افتد؟ (نقطهٔ برگشت هر ردیف)", "", + "| راهبرد | بازده سالانه امروز | نرخ سد | نقطهٔ برگشت نرخ سد | حاشیه (واحد درصد) | وضعیت |", + "|---|---|---|---|---|---|"] + for e in sens["rows"]: + L.append(f"| {e['title']} | {pct(e['annualized_pct'])} | {pct(e['hurdle_now_pct'], 1)} | " + f"{pct(e['breaks_if_hurdle_above_pct'])} | {money(e['margin_pp'])} | " + f"{'می‌ماند' if e['survives'] else 'می‌افتد'} |") + if sens.get("fee_break"): + L.append(f"\n**کارمزد:** {sens['fee_break']['meaning']}") + L.append(f"\n**اسپرد و نقدشوندگی:** {sens['spread_note']}\n") + if card["scored"]: + L += [f"# کارنامهٔ جلسه", "", + f"{card['scored']} پرسش سنجیده شد · {card['near']} پاسخ نزدیک یا درست " + f"({card['fair_pp']}٪) — دربارهٔ شهود، نه سود.", ""] + L += ["# امضا و شاهد", "", + f"- اثر انگشت دفتر آزمون: `{card['verify']['chain']}`", + f"- تعداد سطر دفتر: {card['verify']['rows']} · تمامیت زنجیره: " + f"{'سالم' if card['verify']['ok'] else 'شکسته'}", + "- امضای برگزارکننده: ............................. · امضای سرمایه‌گذار: .............................", "", + CREDIT_MD, ""] + return "\n".join(L) + + +def build_pledge(*, client: str = "", path: Path | str | None = None, + log_path: Path | str | None = None) -> str: + """پیمان‌نامهٔ نمایش: چه چیزی اثبات می‌شود، چه چیزی نه، و حدهای خروج کجاست.""" + card = scorecard(path=log_path) + text = "\n".join([ + f"# پیمان‌نامهٔ نمایش و آزمون — نسخهٔ {VERSION}", "", + f"**طرف‌ها:** برگزارکننده (نگه‌دارندهٔ ایستگاه تصمیم) و سرمایه‌گذار: **{client or '—'}**", "", + "## ۱. موضوع", + "این سند نتیجهٔ چند ساعت کار مشترک روی همین رایانه است: عددهای بازار امروز، محاسبهٔ " + "کارمزد واقعی، و داوری «بماند یا بیفتد».", "", + "## ۲. چه چیزی با شاهد اثبات می‌شود", + "- هر عدد با ماشین‌حساب معمولی روی همان دادهٔ ورودی بازتولید می‌شود (محاسبهٔ دستی دوم در برگه).", + "- کارمزد خرید/فروش سهم، اختیار و اعمال در همهٔ عددها کسر شده است.", + "- نقطهٔ برگشت هر تصمیم نوشته شده: با چه نرخ سدی سیگنال می‌افتد.", + "- دفتر آزمون زنجیره‌هش‌دار است؛ دست‌کاری بعدی در آن لو می‌رود.", + "- هر چیزی که اثبات نشد (سود آینده، پیش‌بینی قیمت، موفقیت تضمینی) در همین سند " + "«اثبات‌نشده» علامت خورده و هیچ عددی برایش ساخته نشده.", "", + "## ۳. چه چیزی اثبات نمی‌شود (و هیچ‌وقت ادعا نشد)", + "- این برنامه تضمین سود نمی‌کند و آیندهٔ قیمت را پیش‌بینی نمی‌کند.", + "- بازار ایران با ابلاغیه و محدودیت عوض می‌شود؛ اگر قاعده‌ای عوض شد، عدد قدیمی بی‌اعتبار است.", + "- فقط با عدد کارگزاری: وجه تضمین و کارمزد نهایی را کارگزاری می‌گوید؛ عدد کارگزاری مقدّم " + "بر هر عدد این برنامه است.", + "- دادهٔ تاریخی کوتاه برای پس‌آزمایی: هر ادعایی بیش از آن بازه، ادعای بی‌شاهد است.", "", + "## ۴. حدهای خروج (پیش از هر خرید نوشته می‌شود)", + f"- برداشت سود در {int(TAKE_PROFIT_FRACTION * 100)}٪ بازده انتظاری.", + f"- توقف ضرر در {int(STOP_LOSS_FRACTION * 100)}٪ بازده انتظاری، بی‌مذاکره.", + "- خروج در سررسید، حتی اگر هیچ‌کدام نخورده باشد.", + f"- سقف هر راهبرد {int(STRATEGY_CAP_FRACTION * 100)}٪ سرمایهٔ تخصیص‌یافته و سقف کل " + "باز در حد سقف ریسک توافق‌شده.", "", + "## ۵. شاهد فنی", + f"- اثر انگشت دفتر آزمون: `{card['verify']['chain']}`", + f"- تعداد سطر دفتر حدس‌ها: {card['verify']['rows']} · تمامیت زنجیرهٔ هش: " + f"{'سالم' if card['verify']['ok'] else 'شکسته'}", + f"- تعداد پرسش‌های آماده: {card['cases_available']} · بهترتیب دلخواه: {card['guesses']} ثبت شد", + "- هیچ دادهٔ شخصی یا مالی از این رایانه بیرون نمی‌رود؛ دفتر و برگه‌ها محلی‌اند.", "", + "## ۶. امضا", + "امضای برگزارکننده: ............................. امضای سرمایه‌گذار: .............................", "", + "تاریخ: .............................", "", + CREDIT_MD, "", + ]) + p = Path(path or PLEDGE_MD) + p.parent.mkdir(parents=True, exist_ok=True) + p.write_text(text, encoding="utf-8") + return text + + +# ------------------------------------------------------------------ خط فرمان +def _print_cases(show_answers: bool) -> None: + cs = cases(reveal=show_answers) + print(f"آزمون کور سرمایه‌گذار — نسخهٔ {VERSION} — {len(cs)} پرسش") + print("=" * 74) + for c in cs: + print(f"\n[{c['id']}] {c['title']}") + print(" پرسش:", c["question"]) + for k, v in c["given"]: + print(f" · {k}: {v}") + if show_answers: + print(" جواب موتور:", answer_text(c)) + for s in c.get("steps", []): + print(" -", s) + for ch in c.get("checks", []): + print(f" ✓ {ch['note']}: {money(ch['value'])} " + f"({'موافق' if ch['agree'] else 'مخالف ⚠️'})") + lead = c.get("ladder") or {} + if lead.get("verdict"): + print(" کِی می‌افتد:", lead["verdict"]) + + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description="آزمون کور سرمایه‌گذار (محلی، بدون اینترنت)") + ap.add_argument("--cases", action="store_true", help="پرسش‌ها بدون جواب") + ap.add_argument("--reveal", action="store_true", help="پرسش‌ها با جواب و مسیر محاسبه") + ap.add_argument("--check", metavar="CASE_ID", help="ثبت حدس سرمایه‌گذار") + ap.add_argument("--guess", help="عدد یا بله/نه حدس") + ap.add_argument("--client", default="", help="نام سرمایه‌گذار") + ap.add_argument("--flip", action="store_true", help="نقطهٔ برگشت کارمزد") + ap.add_argument("--reconcile", action="store_true", help="حساب‌رسی یک معاملهٔ گذشته") + ap.add_argument("--symbol", default="بدون‌نام") + ap.add_argument("--entry", help="قیمت خرید") + ap.add_argument("--exit", help="قیمت فروش") + ap.add_argument("--days", default="30") + ap.add_argument("--units", default="1") + ap.add_argument("--expected", help="انتظار برنامه (٪ سالانه، اختیاری)") + ap.add_argument("--ladder", action="store_true", help="پلهٔ تصمیم: چه بخرم، کِی بفروشم") + ap.add_argument("--sheet", action="store_true", help="ساخت برگهٔ چاپی") + ap.add_argument("--pledge", action="store_true", help="ساخت پیمان‌نامهٔ نمایش") + ap.add_argument("--verify", action="store_true", help="بررسی زنجیرهٔ هش") + ap.add_argument("--json", action="store_true", help="خروجی JSON") + ap.add_argument("--version", action="store_true") + a = ap.parse_args(argv) + + if a.version: + print(f"investor_test {VERSION}") + return 0 + if a.verify: + v = verify_chain() + print(("زنجیره سالم است" if v["ok"] else f"زنجیره در سطر {v['broken_at']} شکسته") + + f" · {v['rows']} سطر · اثر انگشت {v['chain']}") + return 0 if v["ok"] else 1 + if a.flip: + print(json.dumps(fee_flip(), ensure_ascii=False, indent=1)) + return 0 + if a.ladder: + import ladder as ladder_mod + doc = ladder_mod.build(client=a.client, path_md=ladder_mod.LADDER_MD) + print(doc["md"] if not a.json else json.dumps(doc, ensure_ascii=False, indent=1)) + return 0 + if a.reconcile: + if a.entry is None or a.exit is None: + print("برای حساب‌رسی، --entry و --exit لازم است (اختیاری: --days --units --expected).") + return 2 + rec = reconcile(symbol=a.symbol, entry=a.entry, exit=a.exit, days=a.days, units=a.units, + expected=a.expected) + if not rec.get("ok"): + print("خطا:", rec.get("error")) + return 2 + print(f"{rec['symbol']}: هزینهٔ کل {money(rec['cost'])} · دریافتی خالص " + f"{money(rec['proceeds'])} · سود/زیان {money(rec['profit'])}") + print(f"بازده دوره {pct(rec['period_pct'])} · سالانه {pct(rec['annualized_pct'])} → " + f"{rec['verdict']}") + if rec.get("compare") and rec["compare"] != "—": + print(rec["compare"]) + print(rec["note"]) + print("زنجیره:", "سالم" if rec["chain"]["ok"] else "شکسته", + "· کلید", rec["chain"]["last_fingerprint"]) + return 0 + + if a.check: + if a.guess is None: + print("عدد یا بله/نه را با --guess بدهید.") + return 2 + res = check(a.guess, client=a.client, case_id=a.check) + print(f"{res['case']['title']}: حدس «{a.guess}» → جواب موتور {answer_text(res['case'])} · " + f"داوری: {res['status']}" + + (f" (فاصله {res['delta_pct']}٪)" if res["delta_pct"] is not None else "")) + print(" ", res["note"], "· زنجیره:", res["record"]["chain"]) + return 0 + if a.pledge: + text = build_pledge(client=a.client) + print(f"پیمان‌نامه ساخته شد: {PLEDGE_MD}") + print(text[:600]) + return 0 + if a.sheet: + out = build_sheet(client=a.client) + print("برگه ساخته شد:", out["html"]) + print("نسخهٔ متن:", out["md"]) + print("کارنامه:", json.dumps(out["scorecard"], ensure_ascii=False)) + return 0 + if a.json: + print(json.dumps(cases(reveal=True), ensure_ascii=False, indent=1)) + return 0 + _print_cases(show_answers=bool(a.reveal)) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/station/ladder.py b/station/ladder.py new file mode 100644 index 0000000000000000000000000000000000000000..afb88c02dba937e6dc8c84d2412a75b6a78d5ea9 --- /dev/null +++ b/station/ladder.py @@ -0,0 +1,138 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""پلهٔ تصمیم — سند «چه چیزی بخرم، چه زمانی بفروشم، چه زمانی می‌افتد». + +این پرونده یک سند می‌سازد؛ محاسبه‌ها در `investor_test.py` هستند (یک موتور، نه دو تا). +خروجی: سه بخش روشن. + +۱) بخش «چه چیزی بخرم»: ردیف‌هایی که امروز از نرخ سد عبور می‌کنند (به‌ترتیب بازده). +۲) بخش «چه چیزی نخر»: ردیف‌هایی که می‌افتند، با دلیل عددی — نه حذف‌شده و نه بی‌توضیح. +۳) برای هر ردیف: سه حد خروج (برداشت سود، توقف ضرر، سررسید) و نقطهٔ برگشت نرخ سد. + +هیچ‌جا نمی‌گوییم «بخر»؛ می‌گوییم «اگر بخری، این سه حد این‌جاست و با این نرخ می‌افتد». +""" + +from __future__ import annotations + +import argparse +import json +from pathlib import Path + +import investor_test as inv + +VERSION = "0.1.0" + +BASE = Path(__file__).resolve().parent +DATA = BASE / "data" +LADDER_MD = DATA / "investor-ladder.md" +LADDER_JSON = DATA / "investor-ladder.json" + + +def build(rows: list[dict] | None = None, *, capital: float = 20_000_000_000.0, + risk_pct: float = 0.20, margin_per_contract: float = 2_000_000_000.0, + client: str = "", path_md: Path | str | None = None, + path_json: Path | str | None = None) -> dict: + """سند کامل را می‌سازد و (اختیاری) می‌نویسد.""" + rows = rows if rows is not None else inv.fallback_rows() + entries = [] + for row in rows: + if not row.get("kind"): + continue + try: + entries.append(inv.ladder_for(row)) + except (KeyError, ValueError, ZeroDivisionError) as e: + entries.append({"kind": row.get("kind"), "title": inv.KIND_TITLES.get(row.get("kind"), "?"), + "given": [], "ladder": [], "survives": False, "annualized_pct": None, + "hurdle_pct": None, "margin_pp": None, "fees_pct": 0.0, + "verdict": f"دادهٔ این ردیف کامل نیست، پس بررسی نشد ({e}).", + "why": "ردیف ناقص را حذف نمی‌کنیم؛ همان‌طور که هست گزارش می‌شود.", + "check": []}) + live = sorted([e for e in entries if e.get("survives") and (e.get("annualized_pct") or 0) > 0], + key=lambda e: e.get("annualized_pct") or -999, reverse=True) + dead = [e for e in entries if e not in live] + sizing = inv.engine().position_size(capital, margin_per_contract, risk_pct) if margin_per_contract else {} + doc = { + "version": VERSION, + "client": client, + "buy": live, + "no_buy": dead, + "counts": {"checked": len(entries), "actionable": len(live), "no_action": len(dead)}, + "sizing": {"capital": capital, "risk_pct": risk_pct, + "margin_per_contract": margin_per_contract, **sizing}, + "caps_note": (f"سقف هر راهبرد: {int(inv.STRATEGY_CAP_FRACTION * 100)}٪ سرمایهٔ تخصیص‌یافته؛ " + f"سقف کل باز: {int(risk_pct * 100)}٪ سرمایهٔ موجود برای وجه تضمین."), + "fees_note": "همهٔ عددها بعد از کسر کارمزد واقعی (خرید سهم ۰.۴۶۴٪، فروش سهم ۰.۹۶۴٪، " + "اختیار ۰.۱۰۳٪ هر طرف) و در برابر نرخ سد سنجیده شده‌اند.", + "honest": ("این فهرست پیشنهاد خرید نیست؛ خروجی محاسبه است. اگر کارگزاری شما عدد دیگری " + "برای کارمزد یا وجه تضمین می‌دهد، همان عدد مقدم است و در برنامه جایگزین می‌شود. " + "هیچ سودی تضمین نمی‌شود."), + "verify": inv.verify_chain(), + } + doc["md"] = to_md(doc) + if path_md: + Path(path_md).write_text(doc["md"], encoding="utf-8") + doc["path_md"] = str(path_md) + if path_json: + Path(path_json).write_text(json.dumps(doc, ensure_ascii=False, indent=1), encoding="utf-8") + doc["path_json"] = str(path_json) + return doc + + +def _block(e: dict) -> list[str]: + out = [f"## {e['title']}", ""] + if e.get("annualized_pct") is not None: + out.append(f"- بازده سالانهٔ امروز (بعد از کارمزد {e['fees_pct']}٪): " + f"**{e['annualized_pct']}٪** · نرخ سد: {e['hurdle_pct']}٪ · " + f"حاشیه: {e['margin_pp']} واحد درصد") + out += [f"- **داوری:** {e['verdict']}", f"- **چرا:** {e['why']}"] + for step in e.get("ladder", []): + out.append(f" - {step['label']} — {step['when']} → حد: **{step['price']}** → " + f"اقدام: {step['action']}") + for ch in e.get("check", []): + out.append(f" - محاسبهٔ دستی: {ch['note']} = {ch['value']} " + f"({'موافق' if ch['agree'] else 'مخالف ⚠️'})") + out.append("") + return out + + +def to_md(doc: dict) -> str: + L = [f"# پلهٔ تصمیم — چه بخرم، چه زمانی بفروشم، چه زمانی می‌افتد (نسخهٔ {doc['version']})", ""] + if doc.get("client"): + L += [f"سرمایه‌گذار: **{doc['client']}**", ""] + L += [doc["fees_note"], "", + f"- ردیف بررسی‌شده: {doc['counts']['checked']} · قابل اجرا: {doc['counts']['actionable']} · " + f"بدون اقدام: {doc['counts']['no_action']}", + f"- {doc['caps_note']}", "", "# بخش ۱ — چه چیزی بخرم", ""] + if doc["buy"]: + for e in doc["buy"]: + L += _block(e) + else: + L += ["امروز هیچ ردیفی از نرخ سد عبور نمی‌کند. این هم یک جواب است و بهترین جواب: نخر.", ""] + L += ["# بخش ۲ — چه چیزی نخر (و چرا)", ""] + for e in doc["no_buy"]: + L += _block(e) + s = doc.get("sizing") or {} + if s.get("contracts") is not None: + L += ["# بخش ۳ — اندازه: چند تا؟", "", + f"- سرمایه: {s['capital']:,.0f} ریال · سقف ریسک: {int(s['risk_pct'] * 100)}٪ · " + f"وجه تضمین هر قرارداد: {s['margin_per_contract']:,.0f} ریال", + f"- حداکثر قرارداد: **{s['contracts']}** · وجه تضمین قفل‌شده: {s['margin_locked']:,.0f} " + f"· نقد آزاد: {s['free_cash']:,.0f}", ""] + L += [doc["honest"], "", + f"اثر انگشت دفتر: `{doc['verify']['chain']}` · تمامیت زنجیره: " + f"{'سالم' if doc['verify']['ok'] else 'شکسته'}", "", inv.CREDIT_MD, ""] + return "\n".join(L) + + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description="پلهٔ تصمیم: چه بخرم، کِی بفروشم، کِی می‌افتد") + ap.add_argument("--client", default="") + ap.add_argument("--json", action="store_true") + a = ap.parse_args(argv) + doc = build(client=a.client, path_md=LADDER_MD, path_json=LADDER_JSON) + print(json.dumps(doc, ensure_ascii=False, indent=1) if a.json else doc["md"]) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/station/license.py b/station/license.py new file mode 100644 index 0000000000000000000000000000000000000000..d578743eea76db5f4580ce5fb122900f5fb7e866 --- /dev/null +++ b/station/license.py @@ -0,0 +1,294 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""اجازه‌نامهٔ دسترسی — «نمی‌فروشم؛ دسترسی می‌دهم». + +چرا این پرونده هست: کاربر این برنامه یک برنامه‌نویس حرفه‌ای نیست و نمی‌خواهد/نمی‌تواند +محصول را بفروشد و پشتیبانی سنگین بدهد. راه‌حل، فروش نسخه نیست؛ **اجازه‌نامهٔ دسترسی** است: +نرم‌افزار نزد تهیه‌کننده می‌مانَد و شرکت اجازهٔ استفادهٔ نام‌دار و زمان‌دار می‌گیرد، همراه با +پشتیبانی. همین پرونده آن اجازه‌نامه را می‌سازد و در رابط برنامه نشان می‌دهد. + +نمونه: + python license.py --status # وضعیت فعلی + python license.py --grant "شرکت نمونه" --months 12 --contact "آقای ..." --save + python license.py --check # فقط بررسی اعتبار +""" +from __future__ import annotations + +import argparse +import hashlib +import json +import os +from datetime import date, datetime, timedelta, timezone +from pathlib import Path + +VERSION = "0.1.0" +BASE = Path(__file__).resolve().parent +# پوشهٔ تنظیمات را می‌توان با متغیر محیطی جدا کرد (برای چند مشتری روی یک رایانه) +CONFIG = Path(os.environ.get("IRAN_DESK_CONFIG_DIR") or (BASE / "config")) +LICENSE_FILE = CONFIG / "license.json" +CREDIT = ("دولوپر: مهندس مسعود مجربیان · تهیه‌کننده: Masoud Mojarabian · https://www.instagram.com/Mojarabian.Art/ · " + "tel:+989126630554 · https://t.me/Mojarabian") +TRIAL_DAYS = 14 +SALT = "iran-desk-station-access-v1" # فقط برای یکدست‌کردن امضا؛ کلید رمزنگاری نیست + + +def _now() -> date: + return datetime.now(timezone.utc).date() + + +def _sign(payload: dict) -> str: + body = json.dumps(payload, sort_keys=True, ensure_ascii=False) + return hashlib.sha256(f"{SALT}|{body}".encode("utf-8")).hexdigest()[:16] + + +def make_license(client: str, *, months: int = 12, contact: str = "", modules: str = "همه", + note: str = "", start: date | None = None) -> dict: + start = start or _now() + end = start + timedelta(days=30 * max(1, int(months))) + lic = { + "client": client.strip() or "بدون نام", + "contact": contact.strip(), + "modules": modules, + "note": note.strip(), + "start": start.isoformat(), + "end": end.isoformat(), + "months": int(months), + "kind": "اجازه‌نامهٔ دسترسی نام‌دار (نه فروش نسخه)", + "issued": datetime.now(timezone.utc).replace(microsecond=0).isoformat(), + "owner": CREDIT, + } + lic["signature"] = _sign({k: v for k, v in lic.items() if k != "signature"}) + return lic + + +def make_trial(client: str = "آزمون ارزیابی", *, days: int = TRIAL_DAYS) -> dict: + """اجازه‌نامهٔ آزمون روزشمار (پیش‌فرض ۱۴ روز) برای ارزیابی شرکت.""" + start = _now() + lic = { + "client": client.strip() or "آزمون ارزیابی", "contact": "", "modules": "همه", + "note": f"آزمون {int(days)} روزهٔ ارزیابی (بدون تعهد)", + "start": start.isoformat(), "end": (start + timedelta(days=int(days))).isoformat(), + "months": 0, "days": int(days), + "kind": "اجازه‌نامهٔ آزمون (نه فروش نسخه)", + "issued": datetime.now(timezone.utc).replace(microsecond=0).isoformat(), "owner": CREDIT, + } + lic["signature"] = _sign({k: v for k, v in lic.items() if k != "signature"}) + return lic + + +def read_license(path: Path | str | None = None) -> dict | None: + p = Path(path or LICENSE_FILE) + if not p.exists(): + return None + try: + return json.loads(p.read_text(encoding="utf-8")) + except (OSError, json.JSONDecodeError): + return None + + +def write_license(lic: dict, path: Path | str | None = None) -> Path: + p = Path(path or LICENSE_FILE) + p.parent.mkdir(parents=True, exist_ok=True) + p.write_text(json.dumps(lic, ensure_ascii=False, indent=1), encoding="utf-8") + return p + + +def verify(lic: dict | None = None) -> dict: + """اعتبار امضا و تاریخ را بررسی می‌کند. بدون اجازه‌نامه، برنامه در حالت «آزمون» کار می‌کند.""" + lic = lic if lic is not None else read_license() + if not lic: + return {"state": "بدون اجازه‌نامه", "ok": True, "client": "—", "days_left": None, + "detail": ("اجازه‌نامه‌ای ثبت نشده؛ برنامه در حالت آزاد و بدون نامِ مشتری کار می‌کند. " + "برای شرکت، اجازه‌نامهٔ نام‌دار بسازید: python license.py --grant \"نام شرکت\" --save")} + want = _sign({k: v for k, v in lic.items() if k != "signature"}) + if want != lic.get("signature"): + return {"state": "امضا نامعتبر", "ok": False, "client": lic.get("client", "—"), + "days_left": None, + "detail": "فایل اجازه‌نامه دست‌کاری شده است؛ امضا نمی‌خواند."} + try: + end = date.fromisoformat(str(lic.get("end"))) + except ValueError: + return {"state": "تاریخ نامعتبر", "ok": False, "client": lic.get("client", "—"), + "days_left": None, "detail": "تاریخ پایان اجازه‌نامه خوانده نشد."} + left = (end - _now()).days + if left < 0: + return {"state": "منقضی", "ok": False, "client": lic.get("client", "—"), "days_left": left, + "detail": f"اجازه‌نامه در {lic.get('end')} تمام شده ({abs(left)} روز پیش). " + "برای ادامهٔ استفاده، اجازه‌نامهٔ تازه صادر کنید."} + return {"state": "معتبر", "ok": True, "client": lic.get("client", "—"), "days_left": left, + "modules": lic.get("modules", "—"), + "detail": f"اجازه‌نامهٔ «{lic.get('client')}» تا {lic.get('end')} معتبر است " + f"({left} روز باقی مانده)."} + + +def ladder() -> list[dict]: + """سه پلهٔ پیشنهادی ارائه: چه چیزی داده می‌شود و در برابر چه چیزی.""" + return [ + {"step": "۱. راه‌اندازی و آموزش", + "what": "نصب روی رایانهٔ خودشان، تنظیم اتصال، آموزش گام‌به‌گام روی دادهٔ خودشان", + "basis": "یک‌باره (بر پایهٔ روز کار)", + "why": "پیش از این پله، هیچ تعهد ماهانه‌ای گرفته نمی‌شود."}, + {"step": "۲. اجازه‌نامهٔ دسترسی + پشتیبانی", + "what": "استفادهٔ نام‌دار و زمان‌دار، رفع اشکال، به‌روزرسانی عددها و قواعد بازار", + "basis": "ماهانه/سالانه (درآمد تکرارشونده)", + "why": "همین پله است که درآمد پایدار می‌سازد و پشتیبانی را هم پوشش می‌دهد."}, + {"step": "۳. گزارش ماهانه و سفارشی‌سازی", + "what": "گزارش ماهانه برای مدیر، افزودن دروازه‌ها یا راهبردهای موردنظرشان", + "basis": "ماهانه یا پروژه‌ای", + "why": "رشد درآمد بدون فروش نسخه؛ چون نرم‌افزار نزد شما می‌مانَد."}, + ] + + +# ------------------------------------------------------------------ سند چاپی + +DATA = BASE / "data" +DOC_MD = DATA / "license-doc.md" +DOC_HTML = DATA / "license-doc.html" + + +def build_document(lic: dict | None = None, *, path: Path | str | None = None, + html_path: Path | str | None = None) -> tuple[Path, Path]: + """سند چاپی اجازه‌نامهٔ دسترسی — برای جلسه و برای بستهٔ شاهد شرکت. + + خروجی: (مسیر HTML، مسیر متن). اگر اجازه‌نامه‌ای صادر نشده باشد، سند «آزمون» ساخته می‌شود + و همان را هم صریح می‌نویسد؛ سندِ خالی و مبهم نمی‌سازیم. + """ + import reportkit as rk + lic = lic if lic is not None else read_license() + state = verify(lic) + mp = Path(path) if path else DOC_MD + hp = Path(html_path) if html_path else DOC_HTML + mp.parent.mkdir(parents=True, exist_ok=True) + hp.parent.mkdir(parents=True, exist_ok=True) + + if lic: + head = [f"**کارفرما/مشتری:** {lic.get('client', '—')}", + f"**نوع:** {lic.get('kind', '—')} · **بخش‌ها:** {lic.get('modules', '—')}", + f"**شروع:** {lic.get('start', '—')} · **پایان:** {lic.get('end', '—')} " + f"({lic.get('months', '—')} ماه)", + f"**امضا (چکسام):** `{lic.get('signature', '—')}`", + f"**وضعیت بازبینی:** {state.get('state', '—')} — {state.get('detail', '')}"] + else: + head = ["**هنوز اجازه‌نامه‌ای صادر نشده است.**", + "این برنامه در حالت آزاد کار می‌کند. برای جلسه، از پنل مدیریت " + "(بخش «مجوز دسترسی») یا با این فرمان بسازید:", + "", + "```bash", + 'python3 license.py --grant "نام شرکت" --save', + "```"] + + md = "\n".join([ + "# اجازه‌نامهٔ دسترسی — ایستگاه تصمیم مشتقه", "", + f"نسخهٔ ایستگاه: {VERSION} · تاریخ سند: {_now().isoformat()}", "", + *head, "", + "## این اجازه‌نامه چه چیزی می‌دهد", "", + "- استفادهٔ **نام‌دار و زمان‌دار** از ایستگاه روی رایانهٔ خود کارفرما (فروش نسخه نیست).", + "- پشتیبانی و رفع اشکال در دورهٔ اعتبار، و به‌روزرسانی عددهای بازار (کارمزد، نرخ سد، " + "حد نگهداری) در همان دوره.", + "- سندِ روش کار و بستهٔ شاهد، تا هر عددی را خودشان بازتولید کنند.", "", + "## این اجازه‌نامه چه چیزی نمی‌دهد", "", + "- **هیچ سود تضمینی؛** هیچ وعدهٔ بازدهی. خروجی برنامه «عدد و دلیل» است.", + "- **هیچ سفارش خودکاری:** ایستگاه به کارگزاری سفارش نمی‌فرستد (معاملات الگوریتمی خودکار " + "در ایران مجاز نیست) و تصمیم نهایی با کاربر است.", + "- هیچ حق انحصاری روی روش‌های عمومی بازار و هیچ تعهد حجم معامله.", "", + "## چطور بازبینی کنند (یک فرمان)", "", + "```bash", "cd MATERIALS/money/gui && python3 license.py --check", "```", "", + "امضا یک **چکسام sha256** است (کلید خصوصی ندارد): کارش این است که دست‌کاری سهوی یا سادهٔ " + "پرونده را لو بدهد، نه اینکه در برابر جاعل حرفه‌ای امنیت بدهد. همین را در جلسه بگویید.", "", + "---", "", + "امضای ارائه‌دهنده: ____________________ امضای کارفرما/مشتری: ____________________", "", + CREDIT, "", + ]) + mp.write_text(md, encoding="utf-8") + + rows = "".join(f'{rk.esc(k)}{rk.esc(v)}' + for k, v in (("نام مشتری", lic.get("client", "—")), + ("نوع", lic.get("kind", "—")), + ("بخش‌ها", lic.get("modules", "—")), + ("شروع", lic.get("start", "—")), + ("پایان", lic.get("end", "—")), + ("امضا (چکسام)", lic.get("signature", "—")), + ("وضعیت", f"{state.get('state', '—')} — {state.get('detail', '')}")) + ) if lic else 'اجازه‌نامه‌ای صادر نشده است.' + body = "".join([ + '
    این سند «فروش نسخه» نیست؛ اجازه‌نامهٔ دسترسی نام‌دار و زمان‌دار ' + 'است. هیچ سود تضمینی و هیچ سفارش خودکاری در آن نیست.
    ', + f'

    نسخهٔ ایستگاه: {VERSION} · تاریخ سند: {_now().isoformat()}

    ', + '

    ۱. مشخصات اجازه‌نامه

    ', + f'{rows}
    ', + '

    ۲. تعهدهای دو طرف

    ', + '
    • ارائه‌دهنده: نصب و آموزش، پشتیبانی و رفع اشکال در دورهٔ اعتبار، ' + 'به‌روزرسانی عددهای بازار، و تحویل بستهٔ شاهد.
    • ' + '
    • کارفرما: استفادهٔ درون‌سازمانی، تصمیم و سفارش‌گذاری با کاربر خودش، و نگه‌داشتن ' + 'فایل‌های شاهد.
    ', + '

    ۳. بازبینی مستقل

    ', + '

    هر کسی می‌تواند با python3 license.py --check همین امضا و ' + 'تاریخ را بازتولید کند. امضا چکسام sha256 است؛ دست‌کاری ساده را لو می‌دهد، نه جعل حرفه‌ای.

    ', + '

    امضای ارائه‌دهنده: ____________________    ' + 'امضای کارفرما/مشتری: ____________________

    ', + f'

    {rk.DEVELOPER_HTML if hasattr(rk, "DEVELOPER_HTML") else rk.esc(CREDIT)}

    ', + ]) + hp.write_text(rk.page("اجازه‌نامهٔ دسترسی — ایستگاه تصمیم مشتقه", body, + subtitle=f"{lic.get('client', 'بدون مشتری') if lic else 'آزمون'} · " + f"نسخهٔ {VERSION}"), encoding="utf-8") + return hp, mp + + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description="اجازه‌نامهٔ دسترسی (نه فروش نسخه)") + ap.add_argument("--status", action="store_true", help="وضعیت اجازه‌نامهٔ فعلی") + ap.add_argument("--check", action="store_true", help="بررسی اعتبار") + ap.add_argument("--document", action="store_true", help="ساخت سند چاپی اجازه‌نامه") + ap.add_argument("--grant", metavar="نام مشتری", help="صدور اجازه‌نامهٔ نام‌دار") + ap.add_argument("--months", type=int, default=12, help="مدت (ماه)") + ap.add_argument("--contact", default="", help="نام و راه تماس مسئول شرکت") + ap.add_argument("--note", default="", help="یادداشت قرارداد (شمارهٔ پیش‌فاکتور و مانند آن)") + ap.add_argument("--trial", action="store_true", help="صدور اجازه‌نامهٔ آزمون دو هفته‌ای") + ap.add_argument("--save", action="store_true", help="ذخیره در config/license.json") + ap.add_argument("--json", action="store_true", help="خروجی ماشین‌خوان") + ap.add_argument("--ladder", action="store_true", help="نمایش سه پلهٔ پیشنهادی ارائه") + ap.add_argument("--version", action="version", version=f"license {VERSION}") + args = ap.parse_args(argv) + + if args.ladder: + for row in ladder(): + print(f"{row['step']}\n چه می‌دهید: {row['what']}\n در برابر: {row['basis']}\n چرا: {row['why']}\n") + return 0 + + if args.grant or args.trial: + lic = (make_trial(args.grant or "آزمون ارزیابی") if args.trial else + make_license(args.grant, months=args.months, contact=args.contact, note=args.note)) + if args.save: + path = write_license(lic) + else: + path = LICENSE_FILE + out = {"license": lic, "saved": str(path) if args.save else None, "status": verify(lic)} + span = (f"{lic['days']} روز" if lic.get("days") else f"{lic['months']} ماه") + print(json.dumps(out, ensure_ascii=False, indent=1) if args.json else + f"اجازه‌نامهٔ «{lic['client']}» صادر شد: {lic['start']} تا {lic['end']} " + f"({span}) · امضا {lic['signature']}" + + (f"\nذخیره شد: {path}" if args.save else "\n(ذخیره نشد؛ با --save ذخیره کنید)")) + if args.document: + h, m = build_document() + print("سند چاپی:", h) + print("نسخهٔ متنی برای ایمیل:", m) + return 0 + + if args.document: + h, m = build_document() + print("سند چاپی:", h) + print("نسخهٔ متنی برای ایمیل:", m) + return 0 + + st = verify() + if args.json: + print(json.dumps({"status": st, "license": read_license()}, ensure_ascii=False)) + return 0 if st["ok"] else 1 + print(f"وضعیت اجازه‌نامه: {st['state']} · مشتری: {st['client']}" + + (f" · {st['days_left']} روز باقی‌مانده" if st.get("days_left") is not None else "")) + print(st["detail"]) + return 0 if st["ok"] else 1 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/station/live_trial.py b/station/live_trial.py new file mode 100644 index 0000000000000000000000000000000000000000..d1caa56a8f4f5340b9f7c51b9ca9cceda89376d8 --- /dev/null +++ b/station/live_trial.py @@ -0,0 +1,397 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""دفتر آزمون زنده — «برنامه چه گفت، بازار چه کرد». + +این پرونده سه کار می‌کند و هیچ‌کدام ادعای سود نیست: + +۱) **ثبت**: هر سیگنالی که موتور می‌سازد، با ساعت دقیق، قیمت‌های همان لحظه، نرخ سد و همهٔ + ورودی‌های ریاضی، در یک دفتر می‌نشیند. این دفتر پاک نمی‌شود و بازنویسی نمی‌شود. +۲) **بازسنجی**: وقتی دوباره قیمت‌ها را می‌خوانید، همان موتور روی قیمت‌های تازه اجرا می‌شود و + دفتر می‌گوید «حاشیهٔ آن سیگنال امروز چقدر است» — یعنی فرصت بازتر شد، بسته شد، یا زیر کف رفت. +۳) **زنجیرهٔ هش**: هر ثبت، هشِ ثبت قبلی را در خود دارد. اگر کسی بعداً یک ردیف را دست‌کاری یا + حذف کند، زنجیره می‌شکند و گزارش همان را نشان می‌دهد. این «اثبات دست‌کاری‌ناپذیری مطلق» نیست، + ولی برای ممیزی داخلی شرکت کافی است: تاریخ و ترتیب ثبت‌ها قابل بازسازی است. + +چرا این مهم است؟ چون ارزش برنامه را با حرف نمی‌شود ثابت کرد، با سابقهٔ ثبت‌شده ثابت می‌شود. +""" +from __future__ import annotations + +import csv +import hashlib +import json +import sqlite3 +from contextlib import contextmanager +from datetime import datetime, timedelta, timezone +from pathlib import Path + +VERSION = "0.1.0" +BASE = Path(__file__).resolve().parent +DATA = BASE / "data" +DEFAULT_DB = DATA / "trial.sqlite3" +DEFAULT_REPORT = DATA / "trial-report.html" +CREDIT = ("✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · 📱 [+989126630554](tel:+989126630554) · " + "✈️ [Telegram: Mojarabian](https://t.me/Mojarabian) · " + "📸 [Instagram: Mojarabian.Art](https://instagram.com/Mojarabian.Art)") + +CORE_FIELDS = ("ts", "symbol", "kind", "decision", "expected", "note", "legs", + "source_label", "mode") + + +def _now() -> str: + return datetime.now(timezone.utc).isoformat(timespec="seconds") + + +def digest(payload: dict, prev_hash: str) -> str: + body = json.dumps(payload, ensure_ascii=False, sort_keys=True, separators=(",", ":")) + return hashlib.sha256((prev_hash + "|" + body).encode("utf-8")).hexdigest() + + +class Trial: + """دفتر آزمون زنده روی sqlite؛ سبک، بدون وابستگی بیرونی.""" + + def __init__(self, db_path: str | Path = DEFAULT_DB): + self.path = Path(db_path) + self.path.parent.mkdir(parents=True, exist_ok=True) + self._init() + + # ---------- پایه + def _conn(self) -> sqlite3.Connection: + conn = sqlite3.connect(self.path) + conn.row_factory = sqlite3.Row + return conn + + @contextmanager + def _use(self): + """پیوند sqlite را می‌سازد، کار را انجام می‌دهد و همیشه می‌بندد (بی‌هشدار).""" + conn = sqlite3.connect(self.path) + conn.row_factory = sqlite3.Row + try: + yield conn + conn.commit() + except Exception: + conn.rollback() + raise + finally: + conn.close() + + def _init(self) -> None: + with self._use() as c: + c.execute("""CREATE TABLE IF NOT EXISTS entries ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + ts TEXT, symbol TEXT, kind TEXT, decision TEXT, expected REAL, + note TEXT, legs TEXT, source_label TEXT, mode TEXT, + prev_hash TEXT, hash TEXT)""") + c.execute("""CREATE TABLE IF NOT EXISTS marks ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + entry_id INTEGER, ts TEXT, expected_now REAL, floor REAL, + spot_now REAL, future_now REAL, delta_pp REAL, status TEXT)""") + + # ---------- ثبت + def _last_hash(self, conn: sqlite3.Connection) -> str: + row = conn.execute("SELECT hash FROM entries ORDER BY id DESC LIMIT 1").fetchone() + return row["hash"] if row else "GENESIS" + + def record(self, items: list[dict], *, source_label: str = "", mode: str = "", + dedupe_hours: float = 1.0) -> list[dict]: + """سیگنال‌ها را ثبت می‌کند. هر آیتم: symbol, kind, expected, decision, note, legs.""" + saved: list[dict] = [] + cutoff = (datetime.now(timezone.utc) - timedelta(hours=max(0.0, dedupe_hours))).isoformat(timespec="seconds") + with self._use() as c: + prev = self._last_hash(c) + for it in items: + symbol = str(it.get("symbol", "")).strip() + kind = str(it.get("kind", "")).strip() + decision = str(it.get("decision", "recorded")).strip() + if not symbol or not kind: + continue + if dedupe_hours: + dup = c.execute("""SELECT id FROM entries WHERE symbol=? AND kind=? AND decision=? AND ts>=? + ORDER BY id DESC LIMIT 1""", + (symbol, kind, decision, cutoff)).fetchone() + if dup: + continue + expected = it.get("expected") + try: + expected = float(expected) if expected is not None else None + except (TypeError, ValueError): + expected = None + payload = { + "ts": _now(), "symbol": symbol, "kind": kind, "decision": decision, + "expected": expected, "note": str(it.get("note", "") or ""), + "legs": it.get("legs") or {}, "source_label": str(source_label or ""), + "mode": str(mode or ""), + } + h = digest({k: payload[k] for k in CORE_FIELDS}, prev) + cur = c.execute("""INSERT INTO entries (ts, symbol, kind, decision, expected, note, legs, + source_label, mode, prev_hash, hash) + VALUES (?,?,?,?,?,?,?,?,?,?,?)""", + (payload["ts"], symbol, kind, decision, expected, payload["note"], + json.dumps(payload["legs"], ensure_ascii=False), payload["source_label"], + payload["mode"], prev, h)) + payload["id"] = int(cur.lastrowid) + payload["hash"] = h + payload["prev_hash"] = prev + prev = h + saved.append(payload) + return saved + + def record_from_signals(self, signals: list, *, source_label: str = "", mode: str = "", + add_span: float = 0.0) -> list[dict]: + """از فهرست سیگنال‌های میز معاملات، ردیف‌های دفتر را می‌سازد. + + add_span: چند واحد درصد به بازده انتظاری اضافه شود؟ (حاشیهٔ موتور + اسپرد اجرا) + """ + items = [] + for s in signals: + expected = getattr(s, "annualized_pct", None) + if not isinstance(expected, (int, float)): + continue + legs = {"score_pp": getattr(s, "score_pp", None)} + detail = getattr(s, "detail", {}) or {} + for k in ("spot", "future", "strike", "premium", "stock_price", "put_price", + "days", "hurdle", "buy_fee_pct", "sell_fee_pct"): + if k in detail: + legs[k] = detail[k] + items.append({"symbol": getattr(s, "symbol", ""), "kind": getattr(s, "kind", ""), + "expected": round(float(expected) + float(add_span), 4), + "decision": getattr(s, "status", "recorded"), + "note": (getattr(s, "gate_note", "") or ""), "legs": legs}) + return self.record(items, source_label=source_label, mode=mode) + + # ---------- خواندن + def all(self, limit: int = 500) -> list[dict]: + with self._use() as c: + rows = c.execute("SELECT * FROM entries ORDER BY id DESC LIMIT ?", (limit,)).fetchall() + out = [] + for r in rows: + d = dict(r) + try: + d["legs"] = json.loads(d.get("legs") or "{}") + except Exception: + d["legs"] = {} + out.append(d) + return out + + def count(self) -> int: + with self._use() as c: + return int(c.execute("SELECT COUNT(*) AS n FROM entries").fetchone()["n"]) + + def verify_chain(self) -> tuple[bool, str]: + with self._use() as c: + rows = c.execute("SELECT * FROM entries ORDER BY id").fetchall() + prev = "GENESIS" + for r in rows: + payload = {k: (json.loads(r["legs"]) if k == "legs" else r[k]) for k in CORE_FIELDS} + if r["legs"] and not isinstance(payload["legs"], dict): + payload["legs"] = {} + want = digest(payload, prev) + if r["prev_hash"] != prev: + return False, f"زنجیره در ردیف {r['id']} شکسته است: پیوند قبلی جور نیست." + if r["hash"] != want: + return False, f"زنجیره در ردیف {r['id']} شکسته است: محتوا با هش ثبت‌شده نمی‌خواند." + prev = r["hash"] + return True, f"زنجیرهٔ {len(rows)} ثبت سالم است." + + # ---------- بازسنجی + def mark(self, now_map: dict[str, dict]) -> list[dict]: + """حاشیهٔ امروز هر نماد را با حاشیهٔ روز ثبت مقایسه می‌کند. + + now_map: {نماد: {"expected_now": عدد یا None, "floor": عدد, "spot_now": …, "future_now": …}} + """ + out: list[dict] = [] + stamps = _now() + with self._use() as c: + for e in self.all(limit=1000): + info = now_map.get(str(e["symbol"])) + if not info: + continue + now_val = info.get("expected_now") + floor = info.get("floor") + delta = None + if isinstance(now_val, (int, float)) and isinstance(e.get("expected"), (int, float)): + delta = float(now_val) - float(e["expected"]) + if not isinstance(now_val, (int, float)): + status = "دادهٔ تازه نبود" + elif isinstance(floor, (int, float)) and now_val < float(floor): + status = "زیر کف رفت" + elif delta is None: + status = "بدون مقایسه" + elif delta <= -1.0: + status = "کم شد" + elif delta >= 1.0: + status = "بازتر شد" + else: + status = "تقریباً ثابت" + c.execute("""INSERT INTO marks (entry_id, ts, expected_now, floor, spot_now, + future_now, delta_pp, status) VALUES (?,?,?,?,?,?,?,?)""", + (e["id"], stamps, now_val if isinstance(now_val, (int, float)) else None, + floor if isinstance(floor, (int, float)) else None, + info.get("spot_now"), info.get("future_now"), delta, status)) + row = dict(e) + row.update({"expected_now": now_val, "delta_pp": delta, "status_now": status, + "marked_at": stamps}) + out.append(row) + return out + + def latest_marks(self) -> dict[int, dict]: + with self._use() as c: + rows = c.execute("""SELECT m.* FROM marks m JOIN + (SELECT entry_id, MAX(id) AS mid FROM marks GROUP BY entry_id) t + ON m.id = t.mid""").fetchall() + return {int(r["entry_id"]): dict(r) for r in rows} + + def summary(self) -> dict: + entries = self.all(limit=5000) + marks = self.latest_marks() + with_marks = [e for e in entries if e["id"] in marks] + deltas = [marks[e["id"]]["delta_pp"] for e in with_marks if marks[e["id"]]["delta_pp"] is not None] + buckets: dict[str, int] = {} + for e in with_marks: + buckets[marks[e["id"]]["status"]] = buckets.get(marks[e["id"]]["status"], 0) + 1 + ok, chain_msg = self.verify_chain() + return { + "entries": len(entries), + "marked": len(with_marks), + "unmarked": len(entries) - len(with_marks), + "avg_expected": (sum(e["expected"] for e in entries if isinstance(e["expected"], (int, float))) + / len([e for e in entries if isinstance(e["expected"], (int, float))])) + if any(isinstance(e["expected"], (int, float)) for e in entries) else None, + "avg_delta_pp": (sum(deltas) / len(deltas)) if deltas else None, + "best_delta_pp": max(deltas) if deltas else None, + "worst_delta_pp": min(deltas) if deltas else None, + "buckets": buckets, + "chain_ok": ok, "chain_message": chain_msg, + "first_ts": entries[-1]["ts"] if entries else None, + "last_ts": entries[0]["ts"] if entries else None, + } + + # ---------- گزارش + def write_csv(self, path: str | Path = DATA / "trial-entries.csv") -> Path: + path = Path(path) + path.parent.mkdir(parents=True, exist_ok=True) + marks = self.latest_marks() + cols = ["id", "ts", "symbol", "kind", "decision", "expected", "expected_now", "delta_pp", + "status_now", "marked_at", "note", "source_label", "hash"] + with path.open("w", encoding="utf-8-sig", newline="") as f: + w = csv.writer(f) + w.writerow(["شناسه", "زمان ثبت", "نماد", "راهبرد", "تصمیم", "انتظار در ثبت (٪)", + "انتظار امروز (٪)", "تغییر (واحد درصد)", "وضعیت بازسنجی", "زمان بازسنجی", + "یادداشت", "منبع داده", "هش"]) + for e in self.all(limit=5000): + m = marks.get(e["id"], {}) + w.writerow([e["id"], e["ts"], e["symbol"], e["kind"], e["decision"], e["expected"], + m.get("expected_now"), m.get("delta_pp"), m.get("status", ""), + m.get("ts", ""), e["note"], e["source_label"], e["hash"]]) + w.writerow(cols) # نام ستون‌های فنی برای مصرف برنامه‌ای + return path + + def write_report(self, path: str | Path = DEFAULT_REPORT) -> Path: + path = Path(path) + path.parent.mkdir(parents=True, exist_ok=True) + s = self.summary() + marks = self.latest_marks() + entries = self.all(limit=5000) + + def fa(x, nd=2): + return "—" if not isinstance(x, (int, float)) else f"{x:,.{nd}f}" + + rows = [] + for e in entries: + m = marks.get(e["id"], {}) + delta = m.get("delta_pp") + color = "#0a7d33" if isinstance(delta, (int, float)) and delta >= 1 else ( + "#b3261e" if isinstance(delta, (int, float)) and delta <= -1 else "#6b7280") + rows.append( + f"{e['id']}{e['ts']}" + f"{e['symbol']}{e['kind']}{e['decision']}" + f"{fa(e['expected'])}{fa(m.get('expected_now'))}" + f"{fa(delta)}" + f"{m.get('status', 'بازسنجی‌نشده')}" + f"{(e['source_label'] or '—')}" + f"{e['hash'][:16]}…") + buckets = " · ".join(f"{k}: {v}" for k, v in sorted(s["buckets"].items())) or "—" + html = f""" + +دفتر آزمون زندهٔ ایستگاه +
    +

    دفتر آزمون زنده — «برنامه چه گفت، بازار چه کرد»

    +
    هر ثبت با ساعت دقیق و هشِ زنجیره‌ای ذخیره شده است؛ +این پرونده برای نشان‌دادن به سرمایه‌گذار ساخته می‌شود، نه برای وعدهٔ سود.
    + +
    +
    ثبت‌ها
    {s['entries']}
    +
    بازسنجی‌شده
    {s['marked']}
    +
    میانگین انتظار در ثبت (٪)
    {fa(s['avg_expected'])}
    +
    میانگین تغییر (واحد درصد)
    {fa(s['avg_delta_pp'])}
    +
    بهترین تغییر
    {fa(s['best_delta_pp'])}
    +
    بدترین تغییر
    {fa(s['worst_delta_pp'])}
    +
    + +

    وضعیت زنجیرهٔ ثبت

    +
    {s['chain_message']} +{'— هیچ ردیفی دست‌کاری نشده است.' if s['chain_ok'] else '— به این دفتر اعتماد نکنید تا علت پیدا شود.'}
    + +

    خلاصهٔ بازسنجی

    +
    {buckets}
    +بازهٔ ثبت‌ها: از {s['first_ts'] or '—'} تا {s['last_ts'] or '—'}
    +«انتظار» یعنی بازده سالانهٔ انتظاری موتور در لحظهٔ ثبت؛ «تغییر» یعنی همین عدد امروز چقدر است. +عدد منفی یعنی فرصت بسته شده — این عادی و درست است؛ فرصت ریاضی به‌سرعت توسط بازار برداشته می‌شود.
    + +

    ردیف‌های دفتر

    + + + +{''.join(rows) or ''}
    #زمان ثبتنمادراهبردتصمیمانتظار در ثبتانتظار امروزتغییروضعیتمنبع دادههش
    هنوز چیزی ثبت نشده است.
    + +

    چه چیزی این گزارش نیست

    +
    این گزارش «سود تحقق‌یافته» نیست. عددها بازده سالانهٔ انتظاری موتور در تاریخ‌های +مختلف‌اند و تغییر آن‌ها نشان می‌دهد فرصت بازتر شده یا بسته. برای سود تحقق‌یافته، فایل معاملات واقعی +کارگزاری لازم است. هیچ‌جای این دفتر عددی دست‌کاری یا بازنویسی نمی‌شود؛ اگر عددی اشتباه وارد شده باشد، +ردیف جدید ثبت می‌شود و ردیف قدیمی با یادداشت اصلاح باقی می‌ماند.
    + +
    {CREDIT}
    +
    """ + path.write_text(html, encoding="utf-8") + return path + + +def main(argv: list[str] | None = None) -> int: + import argparse + ap = argparse.ArgumentParser(description="دفتر آزمون زنده") + ap.add_argument("--db", default=str(DEFAULT_DB)) + ap.add_argument("--report", action="store_true", help="ساخت گزارش HTML") + ap.add_argument("--csv", action="store_true", help="ساخت CSV") + ap.add_argument("--verify", action="store_true", help="بررسی زنجیرهٔ هش") + args = ap.parse_args(argv) + t = Trial(args.db) + if args.verify: + ok, msg = t.verify_chain() + print(("✓ " if ok else "✗ ") + msg) + if args.report: + print(t.write_report()) + if args.csv: + print(t.write_csv()) + if not (args.report or args.csv or args.verify): + s = t.summary() + print(json.dumps(s, ensure_ascii=False, indent=2)) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/station/make_backpack.py b/station/make_backpack.py new file mode 100644 index 0000000000000000000000000000000000000000..4c0214e84da87fb991fb1837b2f70e1d2496d8ec --- /dev/null +++ b/station/make_backpack.py @@ -0,0 +1,520 @@ +#!/usr/bin/env python3 +"""ساخت «کوله‌پشتی دمو» — بسته‌ای که بدون اینترنت هم کار می‌کند. + +چرا: اینترنت ایران در ۲۰۲۶ به‌شدت محدود است (خاموشی سراسری، وایت‌لیست، و بسته‌شدن مکرر +سرویس‌های خارجی). پس ستون فقرات دمو نباید هیچ لینک خارجی باشد. این بسته سه راه دارد: + + ۱) **نمونهٔ ثابت** (`demo/`): با دوبار کلیک روی `شروع-از-اینجا.html` باز می‌شود؛ **بدون اینترنت**. + ۲) **دمو روی شبکهٔ محلی** (`RUN-DEMO-LAN.*`): همان نمونه از روی خود لپ‌تاپ سرو می‌شود و کارفرما + با گوشی/لپ‌تاپ خودش، در همان اتاق، باز می‌کند. باز هم بدون اینترنت. + ۳) **برنامهٔ زنده** (`RUN-LIVE-*`): ایستگاه واقعی (دروازهٔ ورود، ورود اعداد، موتور ریاضی) روی + لپ‌تاپ اجرا می‌شود و در شبکهٔ محلی در دسترس است. اگر پایتون روی ویندوز نصب نیست، + `python/` (نسخهٔ قابل‌حمل، بدون نصب) را کنارش می‌گذارد. + +اجرا: + python3 make_backpack.py # بستهٔ سبک (نمونه + برنامه + اسکریپت‌ها) + python3 make_backpack.py --with-python # به‌همراه پایتون قابل‌حمل ویندوز (برای RUN-LIVE روی ویندوز) + python3 make_backpack.py --zip +""" +from __future__ import annotations + +import argparse +import hashlib +import json +import shutil +import sys +import zipfile +from pathlib import Path + +BASE = Path(__file__).resolve().parent # .../money/gui +MONEY = BASE.parent +HERE_DELIVERY = MONEY / "delivery" +NAME = "iran-desk-backpack" +DEMO_SRC = HERE_DELIVERY / "iran-desk-demo" # ساختهٔ make_demo_site.py +PY_EMBED = Path("/tmp/py-embed.zip") # اگر باشد، در بسته می‌رود + +sys.path.insert(0, str(BASE)) +import make_kit # noqa: E402 + +START_HTML = """ + + + + +کوله‌پشتی دمو — ایستگاه تصمیم مشتقه + + + +
    +

    کوله‌پشتی دمو — ایستگاه تصمیم مشتقه

    +

    سه راه، از بی‌خطرترین به کامل‌ترین. همه‌شان بدون اینترنت کار می‌کنند.

    +
    +
    + +
    + اینترنت لازم نیست. کارفرما در اینترنت ایران ممکن است به سرویس‌های خارجی دسترسی نداشته باشد؛ + برای همین هیچ‌کدام از این سه راه به اینترنت بیرونی وابسته نیست. همه‌چیز از روی همین لپ‌تاپ اجرا می‌شود. +
    + +
    +
    راه ۱ · بدون هیچ نصب
    +

    نمونهٔ ثابت را نشان بده

    +

    خودِ رابط برنامه با اعداد یک اجرای واقعی. روی فایل زیر دوبار کلیک کن (یا این دکمه را بزن):

    +

    بازکردن نمونهٔ ثابت →

    + + + + +
    می‌بینییعنی چه
    ۱۱ گام برنامههمان چیزی که کارفرما با آن کار می‌کند
    خروجی‌های واقعیبرگهٔ پیشنهاد، جلسهٔ بازبینی، روز اول مشتری، مراسم فروش و…
    +

    در این نسخه اعداد با ورودی تغییر نمی‌کنند (روی فایل ذخیره شده‌اند). برای «زنده» راه ۳ را ببین.

    +
    + +
    +
    راه ۲ · بدون اینترنت، روی گوشی کارفرما
    +

    نمونه را روی شبکهٔ محلی باز کن

    +

    کارفرما با گوشی یا لپ‌تاپ خودش، در همان اتاق، آدرس را باز می‌کند. فقط باید هر دو روی یک وای‌فای باشید.

    + + + + +
    سیستمچه فایلی را اجرا کن
    ویندوزRUN-DEMO-LAN-WINDOWS.bat (دوبار کلیک)
    لینوکس/مکbash RUN-DEMO-LAN-LINUX.sh
    +

    اسکریپت خودش آدرس شبکهٔ محلی را چاپ می‌کند (مثل http://192.168.1.5:8080). همان را روی گوشی کارفرما بزن.

    +
    + +
    +
    راه ۳ · کامل (زنده)
    +

    برنامهٔ واقعی را اجرا کن

    +

    ایستگاه واقعی: دروازهٔ ورود، پنل مدیر، ورود اعداد، موتور ریاضی، دفتر زنجیره‌هش‌دار. + کارفرما با حساب مهمان وارد می‌شود و پنل مدیریت برایش بسته است.

    + + + + +
    سیستمچه فایلیشرط
    ویندوزRUN-LIVE-WINDOWS.batپوشهٔ python کنار بسته باشد (نسخهٔ قابل‌حمل) یا خود ویندوز پایتون داشته باشد
    لینوکس/مکbash RUN-LIVE-LINUX.shپایتون ۳.۱۱+
    +

    راهنمای دقیق دموی زنده (چک‌لیست ۱۰ دقیقه‌ای) →

    +

    اگر مرورگر خودش باز نشد، آدرس چاپ‌شده در پنجرهٔ سیاه را دستی بزن.

    +
    + +
    +
    آزمون سلامت
    +

    قبل از جلسه، یک بار آزمون کن

    +

    این اسکریپت‌ها چک می‌کنند همه‌چیز سر جایش باشد (فایل‌ها، پایتون، دروازه):

    + + + +
    ویندوزCHECK-WINDOWS.bat
    لینوکس/مکbash CHECK-LINUX.sh
    +
    + +
    + رمزها خودشان ساخته می‌شوند. اولین بار که RUN-LIVE را اجرا کنی، دو رمز تصادفی ساخته می‌شود و + در station/config/CREDENTIALS-FIRST-LOGIN.txt نوشته می‌شود: یکی برای پنل مدیر (خودت) و یکی برای + کارفرما (حساب مهمان؛ پنل مدیریت برایش بسته است). آن پرونده را جدا کن و به کسی نده. + اگر رمزها را گم کردی یا خواستی عوض کنی: python3 MAKE-PASSWORDS.py --force + (ویندوز: python MAKE-PASSWORDS.py --force). روش کار در docs/17-remote-access-fa.md. +
    + +
    +
    چرا این‌طور؟
    +

    تصمیم «نمایش آفلاین»

    +

    چرا ستون فقرات نمایش به هیچ لینک اینترنتی گره نخورده، هر راه چه شرایطی دارد، و + «راه زندهٔ کامل» چه زمانی می‌آید:

    +

    خواندن سند تصمیم →

    +
    + +
    + تهیه‌کنندهٔ جزوات: Masoud Mojarabian · + 📱 __PHONE__ · + ✈️ Telegram: Mojarabian · + 📸 Instagram: Mojarabian.Art +
    +
    + + +""" + +LIVE_GUIDE = """# دموی زنده در ۱۰ دقیقه (روی لپ‌تاپ خودت، بدون اینترنت) + +## پیش از جلسه (۵ دقیقه) + +۱. `CHECK-WINDOWS.bat` (ویندوز) یا `bash CHECK-LINUX.sh` (لینوکس/مک) را بزن و ببین «همه‌چیز آماده» می‌دهد. +۲. رمزها را تازه کن (یک بار برای همیشه): + +```bash +cd station +python3 adminauth.py --set-id mafhoom --set-pass "<رمز-قوی-خودت>" +python3 gate.py --sync-admin +python3 gate.py --guest-id masoud --guest-pass "<رمز-کارفرما>" +python3 gate.py --on +python3 gate.py --status +``` + +۳. `RUN-LIVE-WINDOWS.bat` را بزن. پنجرهٔ سیاه آدرس شبکهٔ محلی را چاپ می‌کند؛ همان را یادداشت کن. + +## سر جلسه (۱۰ دقیقه) + +| دقیقه | چه کار کن | چه چیزی نشان می‌دهد | +| --- | --- | --- | +| ۰-۱ | گوشی/لپ‌تاپ کارفرما را به همان وای‌فای وصل کن و آدرس را باز کن | وارد صفحهٔ ورود می‌شود؛ بدون رمز هیچ صفحه‌ای باز نیست | +| ۱-۲ | خودش با حساب مهمان وارد شود (شناسه: masoud) | «حس مهمان‌بودن»: پنل مدیریت برایش ۴۰۳ است | +| ۲-۴ | گام ۴: «داوری سیگنال» را بزن | یک سیگنال می‌ماند یا می‌افتد، با دلیل دروازه‌ها | +| ۴-۶ | گام ۵: شوک‌آزمون با کارمزد سه‌برابر | با بدترین فرض‌ها هم جواب می‌دهد | +| ۶-۷ | گام ۶: ریاضیِ کِلی و احتمال نیم‌شدن حساب | عدد، نه وعده | +| ۷-۸ | گام ۷: برگهٔ پیشنهاد و جلسهٔ بازبینی | خروجی آمادهٔ دست‌دادن به شرکت | +| ۸-۹ | گام ۹: آزمون کور سرمایه‌گذار | خودشان امتحان می‌کنند؛ ۶ پرسش با پاسخ محاسبه‌شده | +| ۹-۱۰ | سند `docs/18-client-value-fa.md` و «سه پرسش سخت» | پاسخ آماده برای سخت‌ترین سؤال‌ها | + +## اگر کارفرما خواست خودش بعداً نگاه کند + +- **بدون اینترنت:** پوشهٔ `demo` را در فلش مموری بده؛ روی هر رایانه‌ای با دوبار کلیک روی + `demo/index.html` باز می‌شود. +- **با اینترنت (اگر باز بود):** لینک نمونهٔ ثابت را بفرست (فایل `LINK-FA.txt`). +- **حساب مهمان:** با `gate.py --guest-off` هر وقت خواستی قطعش کن؛ با `--guest-on` برگردان. + +## مرزهای صادقانه که خودت بگو (پیش از آنکه بپرسند) + +- برنامه **سفارش خودکار نمی‌دهد** و **سود تضمینی** وعده نمی‌دهد؛ تصمیم نهایی با کاربر است. +- درصدها با بدترین حالت‌ها (کارمزد، لغزش، حرکت مخالف) هم سنجیده شده‌اند. +- این نسخه برای تصمیم واقعی، با دادهٔ بازار واقعی کار می‌کند؛ دادهٔ نمایشی برای تمرین است. +""" + +RUN_LIVE_WIN = r"""@echo off +chcp 65001 >nul +title ایستگاه تصمیم مشتقه — اجرای زنده +cd /d "%~dp0" + +if exist "python\python.exe" ( + set "PY=python\python.exe" +) else ( + where python >nul 2>nul + if errorlevel 1 ( + echo. + echo [!] پایتون پیدا نشد. + echo یا پوشهٔ "python" را از بستهٔ قابل‌حمل کنار همین فایل بگذار، + echo یا پایتون ۳.۱۱+ را نصب کن: https://www.python.org/downloads/ + echo. + pause + exit /b 1 + ) + set "PY=python" +) + +if not exist "station\config\gate.json" ( + echo ── اولین اجرا: ساخت رمزها ── + "%PY%" MAKE-PASSWORDS.py + echo. +) +echo ── ایستگاه تصمیم مشتقه: اجرای زنده روی شبکهٔ محلی ── +echo. +echo حساب مدیر (پنل): mafhoom +echo حساب کارفرما (مهمان): masoud +echo (رمزها در پروندهٔ station\config\CREDENTIALS-FIRST-LOGIN.txt هم هست) +echo. +echo آدرس‌هایی که کارفرما می‌تواند باز کند: +echo http://127.0.0.1:8765 (روی همین لپ‌تاپ) +for /f "tokens=2 delims=:" %%a in ('ipconfig ^| findstr /c:"IPv4 Address"') do ( + for /f "tokens=* delims= " %%b in ("%%a") do echo http://%%b:%STATION_PORT% (روی گوشی/لپ‌تاپ کارفرما در همان وای‌فای) +) +echo. +echo برای بستن: همین پنجره را ببند یا Ctrl+C بزن. +echo. +"%PY%" station\web_server.py --port %STATION_PORT% --host 0.0.0.0 +pause +""" + +RUN_LIVE_SH = """#!/usr/bin/env bash +# اجرای زنده روی شبکهٔ محلی (لینوکس/مک). پیش‌نیاز: پایتون ۳.۱۱+ +set -euo pipefail +cd "$(dirname "$0")" +if [ ! -f station/config/gate.json ]; then + echo "── اولین اجرا: ساخت رمزها ──" + python3 MAKE-PASSWORDS.py + echo +fi +echo "── ایستگاه تصمیم مشتقه: اجرای زنده روی شبکهٔ محلی ──" +echo " حساب مدیر (پنل): mafhoom" +echo " حساب کارفرما (مهمان): masoud" +echo " (رمزها در پروندهٔ station/config/CREDENTIALS-FIRST-LOGIN.txt هم هست)" +IP="$(hostname -I 2>/dev/null | awk '{print $1}')" +PORT="${STATION_PORT:-8765}" +echo " آدرس‌ها:" +echo " http://127.0.0.1:$PORT (روی همین دستگاه)" +[ -n "$IP" ] && echo " http://$IP:$PORT (روی گوشی/لپ‌تاپ کارفرما در همان شبکه)" +echo " برای بستن: Ctrl+C" +exec python3 station/web_server.py --port "${STATION_PORT:-8765}" --host 0.0.0.0 +""" + +RUN_DEMO_WIN = r"""@echo off +chcp 65001 >nul +title نمونهٔ ثابت — روی شبکهٔ محلی +cd /d "%~dp0" +if "%STATION_PORT%"=="" set "STATION_PORT=8765" +if exist "python\python.exe" ( set "PY=python\python.exe" ) else ( + where python >nul 2>nul + if errorlevel 1 ( + echo [!] برای این راه به پایتون نیاز است. راه ساده‌تر: خودِ فایل demo\index.html را دوبار کلیک کن. + echo (یا پوشهٔ "python" قابل‌حمل را کنار این فایل بگذار.) + pause + exit /b 1 + ) + set "PY=python" +) +echo ── نمونهٔ ثابت روی شبکهٔ محلی ── +echo آدرس‌ها: +echo http://127.0.0.1:8080 (روی همین لپ‌تاپ) +for /f "tokens=2 delims=:" %%a in ('ipconfig ^| findstr /c:"IPv4 Address"') do ( + for /f "tokens=* delims= " %%b in ("%%a") do echo http://%%b:8080 (روی گوشی کارفرما در همان وای‌فای) +) +echo برای بستن: Ctrl+C +echo. +"%PY%" -m http.server 8080 --bind 0.0.0.0 --directory demo +pause +""" + +RUN_DEMO_SH = """#!/usr/bin/env bash +set -euo pipefail +cd "$(dirname "$0")" +IP="$(hostname -I 2>/dev/null | awk '{print $1}')" +echo "── نمونهٔ ثابت روی شبکهٔ محلی ──" +echo " http://127.0.0.1:8080" +[ -n "$IP" ] && echo " http://$IP:8080 (گوشی کارفرما در همان وای‌فای)" +echo " برای بستن: Ctrl+C" +exec python3 -m http.server 8080 --bind 0.0.0.0 --directory demo +""" + +CHECK_WIN = r"""@echo off +chcp 65001 >nul +title آزمون سلامت کوله‌پشتی +cd /d "%~dp0" +setlocal enabledelayedexpansion +set OK=0 +set BAD=0 + +echo ── آزمون سلامت کوله‌پشتی دمو ── +echo. + +if exist "demo\index.html" ( echo [OK] نمونهٔ ثابت هست & set /a OK+=1 ) else ( echo [--] نمونهٔ ثابت نیست & set /a BAD+=1 ) +if exist "station\web_server.py" ( echo [OK] برنامهٔ زنده هست & set /a OK+=1 ) else ( echo [--] برنامهٔ زنده نیست & set /a BAD+=1 ) +if exist "station\gate.py" ( echo [OK] دروازهٔ ورود هست & set /a OK+=1 ) else ( echo [--] دروازه نیست & set /a BAD+=1 ) +if exist "docs\18-client-value-fa.md" ( echo [OK] سندهای تحویلی هست & set /a OK+=1 ) else ( echo [--] سندها نیستند & set /a BAD+=1 ) + +if exist "python\python.exe" ( + echo [OK] پایتون قابل‌حمل هست ^& set /a OK+=1 + set /a OK+=1 + "python\python.exe" -c "import json,http.server,sqlite3,hashlib,secrets" ^& if errorlevel 1 ( echo [--] ماژول‌های پایتون ناقص‌اند ^& set /a BAD+=1 ) else ( echo [OK] ماژول‌های لازم پایتون سالم‌اند ^& set /a OK+=1 ) +) else ( + where python >nul 2>nul + if errorlevel 1 ( + echo [!!] پایتون نیست: برای «برنامهٔ زنده» به آن نیاز داری ^(راه ۱ و ۲ بدون پایتون هم کار می‌کنند^) + ) else ( + echo [OK] پایتون روی سیستم هست ^& set /a OK+=1 + python -c "import json,http.server,sqlite3,hashlib,secrets" ^& if errorlevel 1 ( echo [--] ماژول‌های پایتون ناقص‌اند ^& set /a BAD+=1 ) else ( echo [OK] ماژول‌های لازم پایتون سالم‌اند ^& set /a OK+=1 ) + ) +) + +if exist "station\config\gate.json" ( + echo [OK] رمزها ساخته شده‌اند ^(پروندهٔ station\config\CREDENTIALS-FIRST-LOGIN.txt^) +) else ( + echo [..] رمزها هنوز ساخته نشده: با اجرای RUN-LIVE دوباره خودش می‌سازد +) + +echo. +echo ── نتیجه: %OK% درست · %BAD% ناقص ── +echo. +echo برای دیدن نمونهٔ ثابت: روی demo\index.html دوبار کلیک کن (بدون اینترنت هم کار می‌کند). +pause +""" + +CHECK_SH = """#!/usr/bin/env bash +# آزمون سلامت کوله‌پشتی (لینوکس/مک) +set -uo pipefail +cd "$(dirname "$0")" +OK=0; BAD=0 +say() { printf ' %s %s\\n' "$1" "$2"; } +chk() { local path="$1" desc="$2"; if [ -e "$path" ]; then say "[OK]" "$desc"; OK=$((OK+1)); else say "[--]" "$desc"; BAD=$((BAD+1)); fi; } + +echo "── آزمون سلامت کوله‌پشتی دمو ──" +chk demo/index.html "نمونهٔ ثابت هست" +chk station/web_server.py "برنامهٔ زنده هست" +chk station/gate.py "دروازهٔ ورود هست" +chk docs/18-client-value-fa.md "سندهای تحویلی هست" +if command -v python3 >/dev/null 2>&1; then + say "[OK]" "پایتون $(python3 -c 'import sys;print("%d.%d"%sys.version_info[:2])')"; OK=$((OK+1)) + if python3 -c 'import json,http.server,sqlite3,hashlib,secrets' 2>/dev/null; then + say "[OK]" "ماژول‌های لازم پایتون سالم‌اند"; OK=$((OK+1)) + else + say "[--]" "ماژول‌های پایتون ناقص‌اند (json/sqlite3/hashlib/secrets)"; BAD=$((BAD+1)) + fi +else + say "[!!]" "پایتون نیست (راه ۱ و ۲ بدون پایتون هم کار می‌کنند)" +fi +echo "── نتیجه: $OK درست · $BAD ناقص ──" +""" + +README = """# کوله‌پشتی دمو — چطور استفاده کنم؟ + +**یک قاعده:** برای هیچ‌کدام از این راه‌ها به اینترنت نیاز نداری. همه‌چیز از روی همین لپ‌تاپ اجرا می‌شود. + +| می‌خواهم… | فایل | پیش‌نیاز | +| --- | --- | --- | +| فقط نشان بدهم | `demo/index.html` را دوبار کلیک کن | هیچ | +| کارفرما با گوشی خودش ببیند | `RUN-DEMO-LAN-WINDOWS.bat` | پایتون (یا پوشهٔ `python` کنار بسته) | +| برنامهٔ زنده را نشان بدهم | `RUN-LIVE-WINDOWS.bat` | همان بالا | +| مطمئن شوم همه‌چیز سالم است | `CHECK-WINDOWS.bat` | هیچ | + +روی لینوکس/مک، همان فایل‌های `.sh` را با `bash` اجرا کن. + +**اول این را بخوان:** `شروع-از-اینجا.html` (با دوبار کلیک باز می‌شود؛ همه‌چیز را گام‌به‌گام می‌گوید). +**برای دموی زنده:** `LIVE-DEMO-FA.md`. +**چرا بدون اینترنت؟** چون اینترنت ایران محدود است و نمی‌خواهیم نمایش کارفرما به یک لینک خارجی گره بخورد. + +✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · 📱 09126630554 · ✈️ Telegram: Mojarabian · 📸 Instagram: Mojarabian.Art +""" + + +def sha16(p: Path) -> str: + h = hashlib.sha256() + with p.open("rb") as f: + for chunk in iter(lambda: f.read(1 << 16), b""): + h.update(chunk) + return h.hexdigest()[:16] + + +def demo_ready() -> bool: + """آیا نمونهٔ ثابت دمو (که کوله‌پشتی از آن ساخته می‌شود) آماده است؟ + + در بستهٔ تحویلی ممکن است این پوشه نباشد؛ در آن حالت آزمون‌ها «رد» می‌شوند نه «خطا». + """ + # شرط باید دقیقاً همان باشد که ساخت می‌سنجد، وگرنه یک پوشهٔ نیمه‌ساخته می‌تواند + # «آماده» گزارش شود و ساخت وسط کار بترکد. + need = (DEMO_SRC / "index.html", DEMO_SRC / "app" / "index.html", + DEMO_SRC / "DEMO-MANIFEST.json") + return all(x.exists() for x in need) + + +def build(out: Path, *, with_python: bool, link_note: str = "") -> dict: + if out.exists(): + shutil.rmtree(out) + out.mkdir(parents=True) + stats = {"copied": 0, "skipped": 0} + + # ۱) خودِ برنامه (station + desk + kodal-alert + tools + strategies) — همان چیدمانی که برنامه می‌خواهد + make_kit.copy_tree(BASE, out / "station", data_allow=make_kit.DATA_ALLOW, + config_allow=make_kit.CONFIG_ALLOW, stats=stats) + (out / "desk").mkdir(exist_ok=True) + make_kit.copy_tree(MONEY / "desk", out / "desk", data_allow=set(), config_allow=None, stats=stats) + make_kit.copy_tree(MONEY / "kodal-alert", out / "kodal-alert", + data_allow=make_kit.KODAL_DATA_ALLOW, stats=stats) + for extra in ("tools", "strategies"): + src = MONEY / extra + if src.exists(): + make_kit.copy_tree(src, out / extra, stats=stats) + + # ۲) نمونهٔ ثابت (باید از قبل با make_demo_site.py ساخته شده باشد) + if not (DEMO_SRC / "index.html").exists(): + raise SystemExit("⛔ نمونهٔ ثابت ساخته نشده. اول: python3 deploy/huggingface/make_demo_site.py") + shutil.copytree(DEMO_SRC, out / "demo", dirs_exist_ok=True) + + # ۳) سندهای تحلیلی + (out / "docs").mkdir(exist_ok=True) + for doc in sorted(MONEY.glob("*.md")): + shutil.copy2(doc, out / "docs" / doc.name) + + # ۳.۵) کمکیِ اولین اجرا (ساخت رمزها بدون هیچ فرمانی) + shutil.copy2(BASE / "MAKE-PASSWORDS.py", out / "MAKE-PASSWORDS.py") + + # ۴) اسکریپت‌ها و راهنماها + (out / "شروع-از-اینجا.html").write_text(START_HTML.replace("__PHONE__", "09126630554"), encoding="utf-8") + (out / "LIVE-DEMO-FA.md").write_text(LIVE_GUIDE, encoding="utf-8") + (out / "README-FA.md").write_text(README, encoding="utf-8") + (out / "LINK-FA.txt").write_text(link_note or + "لینک نمونهٔ ثابت (فقط اگر اینترنت کارفرما باز بود): در بستهٔ تحویلی، بخش «نمونهٔ ثابت» را ببین.\n" + "یادت باشد: اینترنت ایران محدود است؛ ستون فقرات دمو، همین پوشهٔ آفلاین است.\n", encoding="utf-8") + files = {"RUN-LIVE-WINDOWS.bat": RUN_LIVE_WIN, "RUN-DEMO-LAN-WINDOWS.bat": RUN_DEMO_WIN, + "CHECK-WINDOWS.bat": CHECK_WIN, "RUN-LIVE-LINUX.sh": RUN_LIVE_SH, + "RUN-DEMO-LAN-LINUX.sh": RUN_DEMO_SH, "CHECK-LINUX.sh": CHECK_SH} + for name, body in files.items(): + p = out / name + p.write_text(body, encoding="utf-8", newline="\r\n" if name.endswith(".bat") else "\n") + if name.endswith(".sh"): + p.chmod(0o755) + + # ۵) پایتون قابل‌حمل (اختیاری، برای ویندوز): بدون نصب، بدون اینترنت + if with_python: + if not PY_EMBED.exists(): + raise SystemExit(f"⛔ نسخهٔ قابل‌حمل پایتون نیست: {PY_EMBED}\n" + " دانلود: https://www.python.org/ftp/python/3.13.7/python-3.13.7-embed-amd64.zip") + (out / "python").mkdir(exist_ok=True) + with zipfile.ZipFile(PY_EMBED) as z: + z.extractall(out / "python") + # اجازهٔ واردکردن پوشه‌های کنار بسته (پیش‌فرض embed فقط کتابخانهٔ خودش را می‌بیند) + (out / "python" / "python313._pth").write_text( + "python313.zip\n.\n..\\station\n", encoding="utf-8") + + # ۶) اسکن راز و مانیفست + sys.path.insert(0, str(BASE / "deploy")) + from security_scan import find_secret_literals # noqa: E402 + leaked = [x for f in sorted(out.rglob("*")) if f.is_file() for x in find_secret_literals(f)] + if leaked: + raise SystemExit("⛔ مقدار شبیه رمز در کوله‌پشتی: \n " + "\n ".join(leaked)) + for banned in ("station/config/gate.json", "station/config/admin.json"): + if (out / banned).exists(): + raise SystemExit(f"⛔ پروندهٔ راز در کوله‌پشتی: {banned}") + + all_files = sorted(f for f in out.rglob("*") if f.is_file()) + manifest = { + "name": NAME, "files": len(all_files), + "size_kb": sum(f.stat().st_size for f in all_files) // 1024, + "has_python": bool(with_python and (out / "python" / "python.exe").exists()), + "offline_demo": True, + "key_files": {n: sha16(out / n) for n in + ("شروع-از-اینجا.html", "LIVE-DEMO-FA.md", "RUN-LIVE-WINDOWS.bat", + "RUN-LIVE-LINUX.sh", "CHECK-WINDOWS.bat", "demo/index.html") + if (out / n).exists()}, + "note": "کوله‌پشتی دمو: آفلاین کار می‌کند · نمونهٔ ثابت + برنامهٔ زنده روی شبکهٔ محلی + آزمون سلامت", + } + (out / "BACKPACK-MANIFEST.json").write_text( + json.dumps(manifest, ensure_ascii=False, indent=2) + "\n", encoding="utf-8") + return manifest + + +def main() -> int: + ap = argparse.ArgumentParser(description="ساخت کوله‌پشتی دمو (آفلاین)") + ap.add_argument("--out", default=str(HERE_DELIVERY / NAME)) + ap.add_argument("--with-python", action="store_true", help="پایتون قابل‌حمل ویندوز را هم بگذار") + ap.add_argument("--link-note", default="", help="متن لینک نمونهٔ ثابت برای فایل LINK-FA.txt") + ap.add_argument("--zip", action="store_true") + a = ap.parse_args() + out = Path(a.out) + m = build(out, with_python=a.with_python, link_note=a.link_note) + print(f"کوله‌پشتی ساخته شد: {out}") + print(f" پرونده: {m['files']} · حجم: {m['size_kb']} کیلوبایت · " + f"پایتون قابل‌حمل: {'هست' if m['has_python'] else 'نیست'} · اسکن راز: پاکیزه ✅") + if a.zip: + arch = shutil.make_archive(str(out), "zip", out.parent, out.name) + print(f" zip: {arch}") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/station/make_kit.py b/station/make_kit.py new file mode 100644 index 0000000000000000000000000000000000000000..9b94b723969f3801ce04f1fd2813d4d422015550 --- /dev/null +++ b/station/make_kit.py @@ -0,0 +1,342 @@ +"""ساخت «بستهٔ تحویل شرکت» از همین درخت کد — یک پوشهٔ تمیز و قابل کپی روی هر رایانه. + +چه می‌کند: کد و قالب‌ها و اسناد را برمی‌دارد، ولی **آنچه با اجرا ساخته شده** (گزارش‌ها، دفترها، +بسته‌های شاهد، حافظهٔ نهان، خروجی آزمون‌ها) را با خودش نمی‌برد؛ چون شرکت باید از صفر خودش +بسازد و راستی‌آزمایی کند. اثر انگشت هر پرونده هم در `KIT-MANIFEST.json` می‌آید تا بشود بسته را +بعداً بازبینی کرد. + +اجرا (از پوشهٔ همین پرونده): + python3 make_kit.py # ساخت پوشه در ../delivery/iran-desk-kit + python3 make_kit.py --zip # + ساخت فایل zip برای تحویل + python3 make_kit.py --out /مسیر/دلخواه +""" +from __future__ import annotations + +import argparse +import hashlib +import json +import shutil +import sys +from datetime import datetime, timezone +from pathlib import Path + +VERSION = "1.0.0" + +BASE = Path(__file__).resolve().parent # .../money/gui +MONEY = BASE.parent # .../money +DEFAULT_OUT = MONEY / "delivery" +KIT_NAME = "iran-desk-kit" + +# پوشه‌ها/پسوندهایی که هرگز به بسته نمی‌روند +SKIP_DIRS = {"__pycache__", ".cache", ".pytest_cache", "export", ".git", "node_modules"} +SKIP_SUFFIX = {".pyc", ".pyo", ".log"} + +# از پوشهٔ داده، فقط قالب‌ها می‌روند (نه گزارش و دفتر و حافظهٔ نهان) +DATA_ALLOW = {"snapshot-template.json", "history-template.csv", "history-demo.csv", + "data-requirement-sheet.md"} +# از پوشهٔ تنظیمات: اتصال‌های آماده می‌روند، ولی رمز پنل نه (کاربر خودش می‌سازد) +CONFIG_ALLOW = {"connections.json"} +# از دادهٔ دیده‌بان: نمونهٔ همراه برنامه بماند +KODAL_DATA_ALLOW = {"demo.sqlite3"} + +RUN_HINT = """ +## اجرا + +**ویندوز:** روی `station\\run-gui.bat` دوبار کلیک کنید. +**لینوکس/مک:** + +```bash +cd station +python3 web_server.py --port 8765 +``` + +بعد در مرورگر بروید به `http://localhost:8765`. (نسخهٔ دسکتاپ: `python3 station.py`.) +""" + + +def sha16(path: Path) -> str: + h = hashlib.sha256() + with path.open("rb") as f: + for chunk in iter(lambda: f.read(1 << 16), b""): + h.update(chunk) + return h.hexdigest()[:16] + + +def ignored(p: Path) -> bool: + if p.name in SKIP_DIRS: + return True + return p.suffix in SKIP_SUFFIX + + +def copy_tree(src: Path, dst: Path, *, data_allow: set[str] | None = None, + config_allow: set[str] | None = None, kodal_data_allow: set[str] | None = None, + stats: dict | None = None) -> int: + """کپی درخت با فیلترها. تعداد پروندهٔ کپی‌شده را برمی‌گرداند.""" + n = 0 + for item in sorted(src.rglob("*")): + rel = item.relative_to(src) + if any(part in SKIP_DIRS for part in rel.parts): + continue + if item.suffix in SKIP_SUFFIX: + continue + if item.is_dir(): + continue + top = rel.parts[0] if len(rel.parts) > 1 else "" + name = rel.name + if top == "data" and data_allow is not None and name not in data_allow: + if stats is not None: + stats["skipped"] += 1 + continue + if top == "config" and config_allow is not None and name not in config_allow: + if stats is not None: + stats["skipped"] += 1 + continue + if src.name == "data" and kodal_data_allow is not None and name not in kodal_data_allow: + if stats is not None: + stats["skipped"] += 1 + continue + target = dst / rel + target.parent.mkdir(parents=True, exist_ok=True) + shutil.copy2(item, target) + n += 1 + return n + + +def build(out_root: Path, *, zip_it: bool = False) -> dict: + kit = out_root / KIT_NAME + if kit.exists(): + shutil.rmtree(kit) + (kit / "docs").mkdir(parents=True) + stats = {"skipped": 0, "copied": 0} + + # ۱) خودِ ایستگاه (gui) — قالب‌های داده بمانند، ساخته‌شده‌ها نه + stats["copied"] += copy_tree(BASE, kit / "station", data_allow=DATA_ALLOW, + config_allow=CONFIG_ALLOW, stats=stats) + + # ۲) میز معاملات (desk) — بدون پایگاه داده و داشبورد اجراشده + (kit / "desk").mkdir(exist_ok=True) + stats["copied"] += copy_tree(MONEY / "desk", kit / "desk", + data_allow=set(), config_allow=None, stats=stats) + + # ۳) دیده‌بان کدال — فقط نمونهٔ همراه + stats["copied"] += copy_tree(MONEY / "kodal-alert", kit / "kodal-alert", + data_allow=KODAL_DATA_ALLOW, stats=stats) + + # ۴) موتور ریاضی مشتقه و آزمونش + stats["copied"] += copy_tree(MONEY / "tools", kit / "tools", stats=stats) + + # ۵) جزوهٔ راهبردها + stats["copied"] += copy_tree(MONEY / "strategies", kit / "strategies", stats=stats) + + # ۶) سندهای تحلیلی + for doc in sorted(MONEY.glob("*.md")): + shutil.copy2(doc, kit / "docs" / doc.name) + stats["copied"] += 1 + + # ۶.۵) آزمون تعاملی مرورگری (شاهد آزمون‌پذیری؛ با node اجرا می‌شود) + jsdom_test = None + probe = BASE + for _ in range(4): # آزمون تعاملی چند پله بالاتر است؛ تا چهار پله می‌جوییم + cand = probe / "test-interactive.mjs" + if cand.exists(): + jsdom_test = cand + break + probe = probe.parent + if jsdom_test: + shutil.copy2(jsdom_test, kit / "station" / "tools" / "test-interactive.mjs") + stats["copied"] += 1 + + # ۷) راهنمای شروع + (kit / "START-HERE-FA.md").write_text(start_here(), encoding="utf-8") + stats["copied"] += 1 + + # ۸) فهرست و اثر انگشت هر پرونده + files = [] + for p in sorted(kit.rglob("*")): + if p.is_file() and p.name != "KIT-MANIFEST.json": + files.append({"path": str(p.relative_to(kit)).replace("\\", "/"), + "bytes": p.stat().st_size, "sha256": sha16(p)}) + manifest = { + "kit": KIT_NAME, + "version": VERSION, + "built_at": datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC"), + "files_count": len(files), + "bytes": sum(f["bytes"] for f in files), + "skipped_generated": stats["skipped"], + "note": ("این بسته فقط کد و قالب و سند دارد؛ هر گزارش و دفتر و بستهٔ شاهد، روی رایانهٔ " + "خودتان از صفر ساخته می‌شود تا راستی‌آزمایی ممکن باشد. اثر انگشت هر پرونده " + "اینجا آمده تا بشود بازبینی کرد که چیزی بعداً عوض نشده."), + "files": files, + } + (kit / "KIT-MANIFEST.json").write_text( + json.dumps(manifest, ensure_ascii=False, indent=1), encoding="utf-8") + + out = {"kit": str(kit), "files": len(files) + 1, + "bytes": manifest["bytes"], "skipped": stats["skipped"]} + if zip_it: + arch = shutil.make_archive(str(out_root / KIT_NAME), "zip", out_root, KIT_NAME) + out["zip"] = arch + out["zip_bytes"] = Path(arch).stat().st_size + return out + + +def start_here() -> str: + return f"""# از این‌جا شروع کنید — مجموعهٔ ابزار تصمیم‌گیری مشتقه (نسخهٔ بستهٔ {VERSION}) + +این پوشه، «بستهٔ تحویل» است: کد و قالب‌ها و سندها. **هیچ گزارش یا دفتر آماده‌ای داخلش نیست**؛ +و همین نقطهٔ قوتش است: هر عددی که می‌بینید، روی همین رایانه از صفر ساخته می‌شود و خودتان +می‌توانید بازتولیدش کنید. + +## چه چیزی داخل بسته است + +| پوشه | چیست | +| --- | --- | +| `station/` | ایستگاه تصمیم مشتقه: یازده گام، رابط مرورگری و دسکتاپ، پنل مدیریت | +| `desk/` | میز معاملات: اسنپ‌شات بازار روی موتور ریاضی، دروازه‌های ریسک، بستهٔ سفارش برای اجرای انسانی | +| `kodal-alert/` | دیده‌بان خبر و هشدار کدال (نمونهٔ همراه برنامه برای دمو) | +| `tools/` | موتور ریاضی مشتقه (`derivatives_scout.py`) + آزمونش | +| `strategies/` | جزوهٔ راهبردها با درصد هرکدام، شوک‌آزمون، و منابع | +| `share/` | اسکریپت‌های «لینک دادن به کارفرما» (تونل امن + کلید خاموشی) و راهنمای تازه‌کار | +| `deploy/huggingface/` | میزبان مجانی: **نمونهٔ ثابت نمایشی روی HF Static Space** (رابط واقعی + پاسخ‌های ضبط‌شدهٔ یک اجرای واقعی + همهٔ خروجی‌ها؛ `activate_demo_site.sh` و `make_demo_site.py`) · برای Space داکری (نیازمند PRO): Dockerfile درگاه ۷۸۶۰، `boot.sh`، `render.yaml`، `activate_hf.sh` | +| `deploy/` | بردن روی سایت با یک فرمان: `deploy.sh` + `preflight.sh` + `setup-domain.sh` + Dockerfile/compose/Caddy/systemd + پشتیبان روزانه (`install-backup.sh`/`backup.sh`) و بازگردانی (`restore.sh`) + راهنمای فارسی (خاموش‌کردن، حذف، و تمرین بازیابی هم نوشته شده) | +| `docs/` | نوزده سند تحلیلی فارسی: از ایده‌های درآمدی تا ریاضیِ پول، راهنمای تازه‌کار، راهنمای گرفتن اولین جلسه، راهنمای بعد از جلسه (روز اول مشتری)، راهنمای جلسهٔ بازبینی دو هفته‌ای، راهنمای دسترسی از راه دور، و سند «خروجی‌ها برای کارفرما» | +| `START-HERE-FA.md` | همین پرونده | +| `KIT-MANIFEST.json` | فهرست همهٔ پرونده‌ها با اثر انگشت `sha256` (برای بازبینی) | + +## نصب لازم نیست + +فقط **پایتون ۳٫۱۰ یا بالاتر** لازم است؛ هیچ بستهٔ بیرونی، هیچ اینترنت اجباری، هیچ کلیدی، هیچ +هزینهٔ ماهانه. (کارت گرافیک، داکر، سرور هم لازم نیست.) +{RUN_HINT} +## ده دقیقهٔ اول (به همین ترتیب) + +۱. **پنل مدیریت.** گام ۱ → «باز کردن پنل مدیریت» (یا نشانی `http://localhost:8765/admin`). + بار اول می‌نویسد که شناسه و رمز ساخته نشده. در پوشهٔ `station` یک بار این را بزنید و + رمز خودتان را بگذارید و جای دیگری نگه دارید: + +```bash +python3 adminauth.py --set-id mafhoom --set-pass "رمز-خودتان" +``` + +۲. داخل پنل: «بررسی سلامت برنامه» باید **۸ از ۸ سالم** بدهد. اگر همه سالم بود، نصب درست است. + +۳. **گام ۲:** «ساخت قالب نمونه» و بعد «آزمایش خواندن این پرونده» (برنامه داده می‌خواند). + بعد یک پروفایل رایگان را «آزمایش اتصال این پروفایل» و اگر سبز شد «ذخیره و فعال کردن». + +۴. **گام ۵:** «شروع محاسبه» — سیگنال‌ها با دلیل «می‌ماند یا می‌افتد» می‌آیند. + +۵. **گام ۹:** «اجرای مراسم امروز» → «به‌روزرسانی جدول» → «بررسی زنجیرهٔ هش» (باید سالم باشد). + +۶. **گام ۸:** «ساخت بستهٔ راستی‌آزمایی». پوشه‌ای می‌سازد با داشبورد، فهرست سیگنال‌ها، سند روش + کار، کارنامه، پروندهٔ سرمایه‌گذار، و یک `README-FA.md` با چک‌لیست نه‌گامی برای خودتان. + +۷. **گام ۸، دو دکمهٔ دیگر:** نام شرکت را بنویسید و «ساخت پیشنهاد یک‌صفحه‌ای» را بزنید — برگهٔ + چاپی `data/offer-one-pager.html` و نسخهٔ متنی‌اش ساخته می‌شود. این همان برگه‌ای است که **پیش از** + توافق دست شرکت می‌دهید: مسئله، سه چیزی که اضافه می‌شود، پله‌های ارائه، مرزهای صادقانه، و دو + فرمان راستی‌آزمایی. اگر مبلغی ندهید، جای قیمت «توافقی» می‌ماند؛ برگه از خودش قیمت نمی‌سازد. + +۸. **گام ۸، پیام‌های معرفی:** لحن مخاطب را از منو انتخاب کنید (شرکت، کارگزاری، مدرس، آشنای + بازار) و «ساخت پیام‌های معرفی» را بزنید — چهار متن آماده می‌گیرید: پیام اول، پیام بعد از جواب، + تأیید وقت، و پیگیری، به‌همراه اسکریپت تماس تلفنی و پاسخ چهار مخالفت رایج. هدف پیام اول فقط یک + چیز است: نیم‌ساعت وقت. سند راهنمای همین کار: `docs/14-first-meeting-fa.md`. + + **تابلوی پیگیری مخاطبان** هم در همین کارت است: اسم مخاطب را بنویسید و «افزودن به تابلو» را + بزنید؛ بعد از هر پیام «پیام اول رفت» و بعد از هر جواب «جواب داد» را بزنید. + قاعده در خود برنامه قفل است: پیگیری فقط سه بار (روز ۰، ۳، ۱۰) و کار امروز خودش بالای کارت + می‌آید. سه عدد هفته (پیام · تماس · جلسه) هدف را نشان می‌دهد، نه بازار را. برگهٔ چاپی هم دارد. + نتیجهٔ «بعداً» را با یک تاریخ سر‌زدن ثبت کنید؛ همان روز خودش به «کار امروز» برمی‌گردد. + + و اگر خواستید بدانید امروز دقیقاً چه کاری و در چه دقیقه‌ای بکنید، «مراسم فروش امروز» را بزنید: + بیست دقیقه، پنج پیام حداکثر، متن آمادهٔ هر مخاطب کنار کارش. + + روز چهاردهم که آزمون تمام شد، «ساخت برگهٔ جلسهٔ بازبینی» را بزنید: سه شاهد که خودشان اجرا + می‌کنند، پنج شرط کارنامه، و دو خروجی روشن — ادامه با پرداخت، یا توقف بی‌گلایه‌مندی. + + وقتی جوابشان «بله» شد، «ساخت برگهٔ روز اول مشتری» را بزنید: پنج کار روز اول، دو هفته‌ای که + در آن هیچ‌چیز خریده نمی‌شود، شرط‌های کارنامهٔ «آماده» با روز بازبینی، و قاعدهٔ پرداخت در برابر + شاهد. سند راهنمایش: `docs/15-after-meeting-fa.md`. + +راهنمای هر بخش، دکمه‌به‌دکمه و برای تازه‌کار: `docs/13-novice-walkthrough-fa.md` (در خود برنامه هم +از گام ۲ و گام ۹ باز می‌شود). + +## سه کاری که فقط یک بار لازم است (و بعد فراموش کنید) + +| کار | فرمان یا جای دکمه | +| --- | --- | +| گذاشتن رمز پنل (بار اول اجباری) | `python3 adminauth.py --set-id mafhoom --set-pass "رمز-خودتان"` — تا این کار را نکنید، ورود پنل انجام نمی‌شود و برنامه خودش همین فرمان را نشان می‌دهد | +| صدور اجازه‌نامهٔ نام‌دار + سند چاپی | پنل مدیریت ← بخش «مجوز دسترسی» (سند دوامضا) | +| ساخت بستهٔ شاهد برای شرکت یا سرمایه‌گذار | گام ۸ → «ساخت بستهٔ راستی‌آزمایی» | +| دسترسی از راه دور برای کارفرما (اختیاری) | `python3 gate.py --sync-admin` بعد `--guest-id masoud --guest-pass "رمز-کارفرما"` و در آخر `--on` (سند: `docs/17-remote-access-fa.md`) | + +بستهٔ شاهد، سند مجوز و گواهی استفادهٔ موفق را **خودش** تازه می‌سازد و کنار شاهدها می‌گذارد +(`15-license-doc.html` · `17-usage-statement.html` و نسخه‌های متنی‌شان). + +## چطور راستی‌آزمایی کنیم (عددها را خودتان بسازید) + +```bash +cd station +python3 -m unittest discover -s tests # انتظار: ۶۵۹ آزمون (۶۵۸ سبز + ۱ رد) +python3 selftest.py # آزمون ۱۰ دقیقه‌ای ایستگاه: ۱۵ سنجه، هر کدام دو بار +python3 usage_meter.py --summary --verify # گواهی استفاده + سالم‌بودن زنجیرهٔ دفتر +python3 license.py --check # وضعیت اجازه‌نامه +``` + +آزمون تعاملی مرورگری (اختیاری، همان آزمونی که خودش دکمه‌ها را می‌زند): کارساز را بالا نگه دارید و +در ترمینال دیگر بزنید + +```bash +cd station +npm i jsdom +python3 adminauth.py --set-id mafhoom --set-pass "رمز-پنل" # اگر هنوز رمز نساخته‌اید +python3 gate.py --sync-admin # دروازه: رمز مدیر = همین رمز پنل +python3 gate.py --guest-id masoud --guest-pass "رمز-کارفرما" # حساب کارفرما برای آزمون گام ۱۵ +python3 gate.py --on +STATION_ADMIN_PASS="رمز-پنل" STATION_GUEST_ID=masoud STATION_GUEST_PASS="رمز-کارفرما" \ + node tools/test-interactive.mjs # انتظار: ۱۹۲ بررسی، صفر ناموفق +python3 gate.py --status # و در پایان، اگر خواستید: python3 gate.py --off +``` + +(اگر ایستگاه را روی درگاه دیگری بالا آورده‌اید، `STATION_URL` و `STATION_MOCK_URL` را هم بدهید.) +نتیجهٔ همین آزمون روی نسخهٔ بسته‌بندی‌شده، پیش از تحویل گرفته شده است: **۱۹۲ بررسی، صفر ناموفق**. + +## مرزهای صادقانه (همین‌ها را در جلسه هم بگویید) + +- **هیچ سفارشی به کارگزاری فرستاده نمی‌شود** و کدی هم برایش نوشته نشده؛ طبق ابلاغیهٔ مهر ۱۳۹۹ + سازمان بورس، معاملات الگوریتمی خودکار در بورس ایران «تا اطلاع ثانوی» مجاز نیست. اجرا در + سامانهٔ کارگزاری کارِ کاربر است. +- **هیچ سود تضمینی و هیچ پیش‌بینی قیمت در کار نیست.** خروجی، «عدد و دلیل» است؛ تصمیم با کاربر. +- **دادهٔ خریدنی لازم نیست.** پروفایل‌های رایگان (دلار، طلا، سکه، صرافی) آزمون‌شده‌اند؛ اگر روزی + سرویس خریدنی گرفتید، جای کلید و قالب نشانی در گام ۲ است. +- **دفترها محلی‌اند.** هیچ داده‌ای به بیرون فرستاده نمی‌شود؛ گواهی استفاده هم عمداً هیچ عدد مالی + ندارد. +- **عدد بدون منبع، وارد نمی‌شود.** جای عدد نامعلوم (مثل وجه تضمین) هیچ عدد حدسی نمی‌نویسیم؛ عدد + واقعی را از سامانهٔ کارگزاری بردارید. + +## پشتیبانی و تماس + +دولوپر: مهندس مسعود مجربیان · همراه: [09126630554](tel:+989126630554) · +Telegram: [Mojarabian](https://t.me/Mojarabian) · Instagram: [Mojarabian.Art](https://instagram.com/Mojarabian.Art) + +✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · 📱 [989126630554](tel:+989126630554) · +✈️ [Telegram: Mojarabian](https://t.me/Mojarabian) · 📸 [Instagram: Mojarabian.Art](https://instagram.com/Mojarabian.Art) +""" + + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description="ساخت بستهٔ تحویل شرکت از درخت کد") + ap.add_argument("--out", default=str(DEFAULT_OUT), help="پوشهٔ خروجی") + ap.add_argument("--zip", action="store_true", help="ساخت فایل zip هم") + a = ap.parse_args(argv) + out_root = Path(a.out) + out_root.mkdir(parents=True, exist_ok=True) + out = build(out_root, zip_it=a.zip) + print(f"بسته ساخته شد: {out['kit']}") + print(f" پرونده: {out['files']} · حجم: {out['bytes']/1024:.0f} کیلوبایت " + f"· کنارگذاشته‌شده (ساخته‌شده‌ها): {out['skipped']}") + if out.get("zip"): + print(f" zip: {out['zip']} ({out['zip_bytes']/1024:.0f} کیلوبایت)") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/station/mock_feed.py b/station/mock_feed.py new file mode 100644 index 0000000000000000000000000000000000000000..87e9c91fbb76bc8b377d56c54e55009334ab5c66 --- /dev/null +++ b/station/mock_feed.py @@ -0,0 +1,217 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""خوراک آزمایشی محلی — «قیمت زنده بدون هزینه، بدون اینترنت، بدون کلید». + +این برنامه یک بازار ساختگی کوچک را روی همین رایانه سرو می‌کند تا: + • کل مسیر فنی «دادهٔ زنده» ایستگاه آزمایش شود (اتصال، تازگی داده، به‌روزرسانی، سیگنال)، + • و بتوانید کارکرد برنامه را جلوی سرمایه‌گذار بگذارید، بدون هیچ هزینه‌ای. + +صادق باشید: این قیمت‌ها ساختگی‌اند. ایستگاه هم همه‌جا همین را برچسب می‌زند. +برای اعداد واقعی، از پروفایل‌های رایگان در گام ۲ یا سرویس خریدنی استفاده کنید. + +اجرا: python mock_feed.py (روی درگاه ۸۷۸۸) + python mock_feed.py --port 9001 --event-after 6 --speed 2 +""" +from __future__ import annotations + +import argparse +import json +import math +import random +import threading +import time +from datetime import datetime, timezone +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer +from pathlib import Path +from urllib.parse import urlparse, parse_qs + +VERSION = "0.1.0" +BASE = Path(__file__).resolve().parent +HISTORY_CSV = BASE / "demo" / "history-demo.csv" + +# قیمت‌های شروع ساختگی، فقط برای اینکه جدول پر به‌نظر برسد. +START_PRICES: dict[str, float] = { + "اهرم": 20_000.0, "فولاد": 7_000.0, "کگل": 9_800.0, "شپنا": 12_500.0, + "خساپا": 2_100.0, "طلا": 46_000_000.0, "وبملت": 5_400.0, "شاخص": 2_450_000.0, +} +VOLATILITY: dict[str, float] = {"default": 0.0016, "طلا": 0.0030, "اهرم": 0.0035} + + +class Market: + """بازار ساختگی: گشت تصادفی آرام + یک رخداد برنامه‌ریزی‌شده برای دیدن سیگنال.""" + + def __init__(self, *, seed: int = 1405, speed: float = 1.0, event_after: int = 10): + self.rng = random.Random(seed) + self.speed = max(0.1, float(speed)) + self.event_after = max(0, int(event_after)) + self.t0 = time.time() + self.hits = 0 + self.event_on = False + self.lock = threading.Lock() + + def tick(self, symbol: str) -> float: + base = START_PRICES.get(symbol) + if base is None: # نماد ناشناس: از درهم‌سازی نام یک قیمت پایدار بساز + base = 1_000.0 + (abs(hash(symbol)) % 9_000) + vol = VOLATILITY.get(symbol, VOLATILITY["default"]) + elapsed = time.time() - self.t0 + # گشت تصادفی + موج آرام، تا نمودار زنده و باورپذیر باشد + wave = math.sin(elapsed / 21.0) * 0.35 + math.sin(elapsed / 7.0) * 0.15 + noise = self.rng.gauss(0, 1) * vol # نوسان دیدنی هر خواندن (مثل نوار قیمت) + bias = -0.02 if (symbol == "اهرم" and self.event_on) else 0.0 # رخداد: مبنای آتی باز می‌شود + rel = 0.03 * wave + noise * math.sqrt(self.speed) + bias + return round(base * (1.0 + rel), 2) + + def hit(self) -> bool: + with self.lock: + self.hits += 1 + if self.event_after and self.hits >= self.event_after and not self.event_on: + self.event_on = True + return True + return False + + +MARKET = Market() + + +class Handler(BaseHTTPRequestHandler): + protocol_version = "HTTP/1.1" + + def log_message(self, fmt, *args): # لاگ پیش‌فرض را ساکت می‌کنیم + pass + + def _send(self, code: int, body: bytes, ctype: str = "application/json; charset=utf-8") -> None: + self.send_response(code) + self.send_header("Content-Type", ctype) + self.send_header("Content-Length", str(len(body))) + self.send_header("Cache-Control", "no-store") + self.end_headers() + self.wfile.write(body) + + def _json(self, payload: dict, code: int = 200) -> None: + self._send(code, json.dumps(payload, ensure_ascii=False).encode("utf-8")) + + def do_GET(self): + u = urlparse(self.path) + q = parse_qs(u.query) + + if u.path == "/quote": + symbol = (q.get("symbol") or [""])[0].strip() + if not symbol: + return self._json({"ok": False, "error": "پارامتر symbol لازم است"}, 400) + just = MARKET.hit() + price = MARKET.tick(symbol) + return self._json({ + "ok": True, + "data": [{"symbol": symbol, "pl": price, + "ts": datetime.now(timezone.utc).isoformat(timespec="seconds"), + "source": "خوراک آزمایشی محلی (ساختگی)"}], + "event": just, + }) + + if u.path == "/symbols": + return self._json({"ok": True, "symbols": list(START_PRICES), + "event_after": MARKET.event_after, "hits": MARKET.hits}) + + if u.path == "/history.csv": + if HISTORY_CSV.exists(): + return self._send(200, HISTORY_CSV.read_bytes(), "text/csv; charset=utf-8") + return self._json({"ok": False, "error": "پروندهٔ تاریخ نمونه پیدا نشد"}, 404) + + if u.path in ("/", "/index.html"): + return self._send(200, page_html(MARKET).encode("utf-8"), "text/html; charset=utf-8") + + return self._json({"ok": False, "error": "مسیر ناشناخته"}, 404) + + +def page_html(market: Market) -> str: + """صفحهٔ نمایش قیمت‌های زنده — تک‌پرونده و آفلاین (فقط برای چشم سرمایه‌گذار).""" + symbols = "،".join(f"«{s}»" for s in START_PRICES) + return f""" + + +خوراک آزمایشی محلی — بازار ساختگی +
    +

    خوراک آزمایشی محلی — بازار ساختگی

    +
    این قیمت‌ها ساختگی هستند و از هیچ بازار واقعی نمی‌آیند. کاربردشان فقط این است که +مسیر «دادهٔ زنده» ایستگاه، بدون هزینه و بدون اینترنت، آزمایش و نمایش داده شود. +برای قیمت واقعی، در گام ۲ ایستگاه یکی از پروفایل‌های رایگان را آزمایش کنید.
    +

    نمادهای این خوراک: {symbols} — نشانی قیمت برای ایستگاه: +http://127.0.0.1:{getattr(market, "port", 8788)}/quote?symbol={{symbol}}

    + +
    نمادقیمت ساختگیتغییرآخرین به‌روزرسانی
    در حال خواندن…
    +

    هر دو ثانیه خودکار تازه می‌شود. رخداد برنامه‌ریزی‌شده بعد از +{market.event_after} درخواست فعال می‌شود (برای دیدن اینکه ایستگاه چطور یک سیگنال تازه را می‌گیرد).

    +
    """ + + +def serve(port: int = 8788, host: str = "127.0.0.1") -> ThreadingHTTPServer: + httpd = ThreadingHTTPServer((host, port), Handler) + return httpd + + +def main(argv: list[str] | None = None) -> int: + global MARKET + ap = argparse.ArgumentParser(description="خوراک آزمایشی محلی ایستگاه (دادهٔ ساختگی)") + ap.add_argument("--host", default="127.0.0.1") + ap.add_argument("--port", type=int, default=8788) + ap.add_argument("--seed", type=int, default=1405) + ap.add_argument("--speed", type=float, default=1.0) + ap.add_argument("--event-after", type=int, default=10, help="بعد از چند درخواست، رخداد سیگنال‌ساز فعال شود") + ap.add_argument("--quiet", action="store_true") + args = ap.parse_args(argv) + MARKET = Market(seed=args.seed, speed=args.speed, event_after=args.event_after) + httpd = serve(args.port, args.host) + if not args.quiet: + print(f"خوراک آزمایشی محلی روی http://127.0.0.1:{args.port}/ آماده است (دادهٔ ساختگی).") + print(f"نشانی قیمت برای ایستگاه: http://127.0.0.1:{args.port}/quote?symbol={{symbol}}") + print("برای بستن، کلید Ctrl+C را بزنید.") + try: + httpd.serve_forever() + except KeyboardInterrupt: + print("\nبسته شد.") + finally: + httpd.server_close() + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/station/offer.py b/station/offer.py new file mode 100644 index 0000000000000000000000000000000000000000..e2a0803af47d1d1998694daf7b2d44a85afe8b74 --- /dev/null +++ b/station/offer.py @@ -0,0 +1,224 @@ +"""پیشنهاد یک‌صفحه‌ای — برگه‌ای که دست شرکت یا کارگزاری می‌دهید. + +چرا جدا از «سند مجوز» است: آن سند، پس از توافق امضا می‌شود؛ این برگه، **پیش از** توافق دست +طرف مقابل می‌افتد و در یک صفحه می‌گوید مسئله چیست، چه چیزی تحویل داده می‌شود، چطور راستی‌آزمایی +می‌کنند، و مرزها کجاست. هیچ عدد سودی در آن نیست و هیچ قیمتی هم از خودش نمی‌سازد: اگر قیمتی +نگویید، جای آن می‌نویسد «توافقی». + +اجرا: + python3 offer.py --client "نام شرکت" # ساخت برگه + python3 offer.py --client "نام شرکت" --monthly 40000000 + python3 offer.py --json # خلاصهٔ ماشین‌خوان +""" +from __future__ import annotations + +import argparse +import json +import sys +from datetime import datetime, timezone +from pathlib import Path + +BASE = Path(__file__).resolve().parent +if str(BASE) not in sys.path: + sys.path.insert(0, str(BASE)) + +import license as licmod # noqa: E402 +import reportkit as rk # noqa: E402 + +VERSION = "0.1.0" +DATA = BASE / "data" +OFFER_MD = DATA / "offer-one-pager.md" +OFFER_HTML = DATA / "offer-one-pager.html" + +_DIGITS = str.maketrans("0123456789", "۰۱۲۳۴۵۶۷۸۹") + + +def fa(value) -> str: + """عدد را با رقم فارسی می‌نویسد (برگه دست شرکت می‌رود، پس فارسی‌خوان باشد).""" + return str(value).translate(_DIGITS) + + +def fa_num(value: int) -> str: + return fa(f"{int(value):,}").replace(",", "٬") + + +def _kit_facts() -> dict: + """اگر بستهٔ تحویل ساخته شده باشد، عددهای واقعی‌اش را برمی‌دارد (نه عدد حدسی).""" + # دو جا: درخت اصلی (پوشهٔ delivery) و خودِ بسته (وقتی همین کد داخل بسته اجرا می‌شود) + for kit in (BASE.parent / "delivery" / "iran-desk-kit", BASE.parent): + manifest = kit / "KIT-MANIFEST.json" + if manifest.exists() and (kit / "docs").exists(): + try: + m = json.loads(manifest.read_text(encoding="utf-8")) + docs = len([p for p in (kit / "docs").glob("*.md") if p.name[:2].isdigit()]) + return {"kit": kit.name, "files": m.get("files_count"), "version": m.get("version"), + "bytes_kb": round((m.get("bytes") or 0) / 1024), "docs": docs or None} + except (json.JSONDecodeError, OSError): + break + return {} + + +def _docs_phrase(facts: dict) -> str: + """شمار سندهای تحلیلی از خودِ پوشه خوانده می‌شود؛ عدد ثابت در متن نمی‌نویسیم.""" + return (f"{fa(facts['docs'])} سند تحلیلی فارسی" if facts.get("docs") + else "مجموعهٔ اسناد تحلیلی فارسی") + + +def price_line(monthly_rial: int = 0, setup_rial: int = 0) -> dict: + """جملهٔ قیمت. عددی که ندهید، ساخته نمی‌شود.""" + if not monthly_rial and not setup_rial: + return {"text": "توافقی؛ عدد را در جلسه با هم می‌گذاریم (اول راه‌اندازی، بعد ماهانه).", + "given": False} + parts = [] + if setup_rial: + parts.append(f"راه‌اندازی یک‌باره: {fa_num(setup_rial)} ریال") + if monthly_rial: + parts.append(f"ماهانه: {fa_num(monthly_rial)} ریال") + return {"text": " · ".join(parts), "given": True} + + +def build_offer(client: str = "", *, monthly_rial: int = 0, setup_rial: int = 0, + html_path: Path | str | None = None, + md_path: Path | str | None = None) -> tuple[Path, Path]: + """برگهٔ پیشنهاد را می‌سازد. خروجی: (مسیر HTML، مسیر متن).""" + hp = Path(html_path) if html_path else OFFER_HTML + mp = Path(md_path) if md_path else OFFER_MD + hp.parent.mkdir(parents=True, exist_ok=True) + mp.parent.mkdir(parents=True, exist_ok=True) + + client_txt = client.strip() or "نام شرکت / کارگزاری شما" + today = fa(datetime.now(timezone.utc).strftime("%Y-%m-%d")) + kit = _kit_facts() + price = price_line(monthly_rial, setup_rial) + ladder = licmod.ladder() + + kit_sentence = ( + f"بستهٔ کد و اسناد (`{kit['kit']}`) با {fa(kit['files'])} پرونده و اثر انگشت `sha256` هر پرونده — " + "روی رایانهٔ خودتان، بدون نصب چیزی جز پایتون." + if kit.get("files") else + "بستهٔ کد و اسناد، همراه قالب‌های داده و اثر انگشت هر پرونده — روی رایانهٔ خودتان، " + "بدون نصب چیزی جز پایتون.") + + md = "\n".join([ + "# پیشنهاد یک‌صفحه‌ای — ایستگاه تصمیم مشتقه", "", + f"**برای:** {client_txt} · **تاریخ:** {today}", "", + "## مسئله‌ای که می‌بینم", "", + "سیگنال‌ها و نرم‌افزارهای زیادی «کجا سود هست» می‌گویند؛ هیچ‌کدام نمی‌گویند با **کارمزد، " + "اسپرد و فاصله تا اخطاریهٔ مارجین** آن سیگنال می‌مانَد یا می‌افتد. نتیجه‌اش معامله‌هایی است " + "که روی کاغذ سود داشتند و روی صورتحساب، زیان.", "", + "## سه چیزی که این ایستگاه اضافه می‌کند", "", + "۱. **داوری سیگنال** (می‌مانَد یا می‌افتد): هر سیگنال — از هر ابزاری — روی موتور ریاضی " + "می‌رود و با دلیل روشن می‌گوید کدام دروازه را رد کرد.", + "۲. **اندازه‌گیری ریسک پیش از سفارش**: وجه تضمین، سقف موقعیت، فاصله تا مارجین‌کال، نرخ برد " + "سر‌به‌سر، و اینکه با شوک قیمت یا کارمزد دو برابر، معامله زنده می‌مانَد یا نه.", + "۳. **بستهٔ شاهد بازتولیدپذیر**: همهٔ عددها همراه روش حساب و اثر انگشت `sha256` تحویل می‌شود؛ " + "مدیر ریسک شما هر ردیف را خودش می‌تواند بازتولید کند.", "", + "## چه چیزی تحویل داده می‌شود", "", + f"- {kit_sentence}", + f"- میز معاملات و دیده‌بان خبر، ایستگاه یازده‌گامی، جزوهٔ راهبردها با درصد هر کدام، و " + f"{_docs_phrase(kit)} (از سنجش مسیرهای داده تا ریاضیِ بقا).", + "- یک مجموعهٔ آزمون که **خودتان** اجرا می‌کنید و یک برگهٔ امضادار آزمون کور، تا ادعا را " + "از دهان من نشنوید.", "", + "## هزینه تا اولین تصمیم: صفر", "", + "- سه پروفایل دادهٔ **رایگان و بدون کلید** همراه برنامه است (نرخ دلار، طلا و سکه، و یک " + "صرافی ریالی). تا وقتی کارنامهٔ دو هفته‌ای «آماده» نشده، هیچ خرید داده‌ای پیشنهاد نمی‌شود.", + "- روی رایانهٔ خودتان اجرا می‌شود؛ داده‌ای به بیرون نمی‌رود و رمز سامانهٔ کارگزاری هم " + "هیچ‌وقت پرسیده نمی‌شود.", "", + "## شکل ارائه", "", + *[f"- **{row['step']}**: {row['what']} — {row['basis']}" for row in ladder], "", + f"**قیمت:** {price['text']}", "", + "## مرزها (همین‌ها را بی‌کم‌وکاست می‌گویم)", "", + "- **هیچ سود تضمینی و هیچ پیش‌بینی قیمت در کار نیست.** خروجی، «عدد و دلیل» است.", + "- **هیچ سفارشی به کارگزاری فرستاده نمی‌شود** و کدی هم برایش نوشته نشده؛ طبق ابلاغیهٔ مهر " + "۱۳۹۹ سازمان بورس، معاملات الگوریتمی خودکار در بورس ایران مجاز نیست. اجرا با کاربر است.", + "- **درصد از سود نمی‌گیرم**؛ حق دسترسی و پشتیبانی، مبلغ روشن و قابل پیش‌بینی است.", + "- هیچ عدد بدون منبع وارد نمی‌شود؛ جای عدد ناشناخته (مثل وجه تضمین) عدد حدسی نمی‌نویسیم.", "", + "## راستی‌آزمایی پیش از امضا", "", + "جلسهٔ ۲۵ دقیقه‌ای روی لپ‌تاپ خودتان: سلامت برنامه، داوری یک سیگنال واقعی خودتان، " + "حساب‌رسی یک معاملهٔ گذشته با کارمزد واقعی، و ساخت بستهٔ شاهد. بعد هم این فرمان‌ها را " + "خودتان اجرا کنید:", "", + "```bash", + "cd station && python3 -m unittest discover -s tests # مجموعهٔ آزمون همراه بسته", + "python3 selftest.py # آزمون ۱۰ دقیقه‌ای، هر سنجه دو بار", + "```", "", + "---", "", + "امضای ارائه‌دهنده: ____________________ امضای شما: ____________________", "", + rk.DEVELOPER_HTML if hasattr(rk, "DEVELOPER_HTML") else licmod.CREDIT, "", + ]) + mp.write_text(md, encoding="utf-8") + + body = "".join([ + '
    یک‌صفحه، بدون وعده: این برگه هیچ سودی را پیش‌بینی نمی‌کند و ' + 'هیچ سفارشی نمی‌فرستد؛ فقط می‌گوید چه چیزی تحویل می‌شود و چطور خودتان بازبینی می‌کنید.
    ', + f'

    برای: {rk.esc(client_txt)} · تاریخ: {rk.esc(today)}

    ', + "

    ۱. مسئله‌ای که می‌بینم

    ", + '

    سیگنال‌ها و نرم‌افزارهای زیادی «کجا سود هست» می‌گویند؛ هیچ‌کدام نمی‌گویند با ' + 'کارمزد، اسپرد و فاصله تا اخطاریهٔ مارجین آن سیگنال می‌مانَد یا می‌افتد. نتیجه‌اش ' + 'معامله‌هایی است که روی کاغذ سود داشتند و روی صورتحساب، زیان.

    ', + "

    ۲. سه چیزی که این ایستگاه اضافه می‌کند

    ", + "
    1. داوری سیگنال (می‌مانَد یا می‌افتد): هر سیگنال، از هر ابزاری، روی موتور " + "ریاضی می‌رود و با دلیل روشن می‌گوید کدام دروازه را رد کرد.
    2. " + "
    3. اندازه‌گیری ریسک پیش از سفارش: وجه تضمین، سقف موقعیت، فاصله تا مارجین‌کال، " + "نرخ برد سر‌به‌سر، و آزمون شوک (کارمزد دو و سه برابر، حرکت مخالف).
    4. " + "
    5. بستهٔ شاهد بازتولیدپذیر: عددها همراه روش حساب و اثر انگشت sha256 " + "تحویل می‌شود.
    ", + "

    ۳. چه چیزی تحویل داده می‌شود

    ", + f'
    • {rk.esc(kit_sentence)}
    • ' + f"
    • میز معاملات و دیده‌بان خبر، ایستگاه یازده‌گامی، جزوهٔ راهبردها، و " + f"{_docs_phrase(kit)}.
    • " + "
    • یک مجموعهٔ آزمون که خودتان اجرا می‌کنید و یک برگهٔ امضادار آزمون کور.
    ", + "

    ۴. هزینه تا اولین تصمیم: صفر

    ", + "
    • سه پروفایل دادهٔ رایگان و بدون کلید همراه برنامه است. تا وقتی کارنامهٔ " + "دو هفته‌ای «آماده» نشده، هیچ خرید داده‌ای پیشنهاد نمی‌شود.
    • " + "
    • روی رایانهٔ خودتان اجرا می‌شود؛ داده‌ای به بیرون نمی‌رود و رمز سامانهٔ کارگزاری " + "هیچ‌وقت پرسیده نمی‌شود.
    ", + "

    ۵. شکل ارائه

    ", + "" + + "".join(f"" + f"" for row in ladder) + + "
    پلهچه چیزیدر برابر چه چیزی
    {rk.esc(row['step'])}{rk.esc(row['what'])}{rk.esc(row['basis'])}
    ", + f'

    قیمت: {rk.esc(price["text"])}

    ', + "

    ۶. مرزها

    ", + "
    • هیچ سود تضمینی و هیچ پیش‌بینی قیمت در کار نیست. خروجی، «عدد و دلیل» است.
    • " + "
    • هیچ سفارشی به کارگزاری فرستاده نمی‌شود؛ طبق ابلاغیهٔ مهر ۱۳۹۹ سازمان بورس، " + "معاملات الگوریتمی خودکار در بورس ایران مجاز نیست.
    • " + "
    • درصد از سود نمی‌گیرم؛ حق دسترسی و پشتیبانی، مبلغ روشن و قابل پیش‌بینی است.
    • " + "
    • هیچ عدد بدون منبع وارد نمی‌شود؛ جای عدد ناشناخته عدد حدسی نمی‌نویسیم.
    ", + "

    ۷. راستی‌آزمایی پیش از امضا

    ", + '

    جلسهٔ ۲۵ دقیقه‌ای روی لپ‌تاپ خودتان: سلامت برنامه، داوری یک سیگنال واقعی ' + 'خودتان، حساب‌رسی یک معاملهٔ گذشته با کارمزد واقعی، و ساخت بستهٔ شاهد. بعد این دو فرمان را ' + 'خودتان اجرا کنید: python3 -m unittest discover -s tests و ' + 'python3 selftest.py.

    ', + '

    امضای ارائه‌دهنده: ____________________    ' + 'امضای شما: ____________________

    ', + f'

    {rk.DEVELOPER_HTML}

    ', + ]) + hp.write_text(rk.page("پیشنهاد یک‌صفحه‌ای — ایستگاه تصمیم مشتقه", body, + subtitle=f"{client_txt} · {today}"), encoding="utf-8") + return hp, mp + + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description="پیشنهاد یک‌صفحه‌ای برای شرکت یا کارگزاری") + ap.add_argument("--client", default="", help="نام شرکت یا کارگزاری") + ap.add_argument("--monthly", type=int, default=0, help="حق دسترسی ماهانه (ریال)؛ ندهید، «توافقی» می‌شود") + ap.add_argument("--setup", type=int, default=0, help="مبلغ راه‌اندازی (ریال)") + ap.add_argument("--json", action="store_true", help="خروجی ماشین‌خوان") + ap.add_argument("--version", action="version", version=f"offer {VERSION}") + a = ap.parse_args(argv) + + h, m = build_offer(a.client, monthly_rial=a.monthly, setup_rial=a.setup) + if a.json: + print(json.dumps({"html": str(h), "md": str(m), "client": a.client or None, + "price_given": bool(a.monthly or a.setup), "kit": _kit_facts()}, + ensure_ascii=False)) + return 0 + print("پیشنهاد یک‌صفحه‌ای ساخته شد:") + print(" برگهٔ چاپی:", h) + print(" نسخهٔ متنی (برای ایمیل/واتساپ):", m) + print(" قیمت:", price_line(a.monthly, a.setup)["text"]) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/station/onboarding.py b/station/onboarding.py new file mode 100644 index 0000000000000000000000000000000000000000..2c6d2d7de94e545cff346239d449363a8a020ea0 --- /dev/null +++ b/station/onboarding.py @@ -0,0 +1,294 @@ +"""روز اول مشتری — برگهٔ «از بله تا پایان هفتهٔ دوم». + +جای این برگه در زنجیره: `offer.py` پیش از جلسه دست طرف مقابل می‌افتد، `outreach.py` جلسه را +می‌گیرد، `prospects.py` پیگیری را نگه می‌دارد. این برگه برای لحظهٔ بعد از «بله» است و یک چیز را +جواب می‌دهد: **فردا صبح چه کار کنم و در دو هفتهٔ اول چه چیزی نمی‌فروشم؟** + +سه قاعده که در خود برگه قفل شده‌اند و از جای دیگری خوانده می‌شوند (نه دست‌نویس): + +- **طول آزمون**: از `license.TRIAL_DAYS` (روزشمار اجازه‌نامهٔ آزمون) — پس تاریخ بازبینی، خودِ + همان روزی است که اجازه‌نامهٔ آزمون تمام می‌شود. +- **شرط‌های «کارنامهٔ آماده»**: از پیش‌فرض‌های `daily_trial.scorecard` (ده روز ثبت، پنج روز واقعی، + شصت درصد بازسنجی، سه حرکت معنادار، زنجیرهٔ سالم). +- **عددهای بستهٔ تحویل**: از `KIT-MANIFEST.json` — عدد حدسی روی این برگه نمی‌رود. + +اجرا: + python3 onboarding.py --client "نام مشتری" + python3 onboarding.py --client "نام مشتری" --start 2026-09-22 --monthly 40000000 + python3 onboarding.py --json +""" +from __future__ import annotations + +import argparse +import inspect +import json +import sys +from datetime import date, datetime, timedelta, timezone +from pathlib import Path + +BASE = Path(__file__).resolve().parent +if str(BASE) not in sys.path: + sys.path.insert(0, str(BASE)) + +import daily_trial as dailytrial # noqa: E402 +import license as licmod # noqa: E402 +import reportkit as rk # noqa: E402 +from offer import _kit_facts as kit_facts, fa, fa_num, price_line # noqa: E402 + +VERSION = "0.1.0" +DATA = BASE / "data" +PACK_MD = DATA / "onboarding-pack.md" +PACK_HTML = DATA / "onboarding-pack.html" + +def trial_days() -> int: + """طول آزمون دو هفته‌ای — از خود ماژول اجازه‌نامه، نه از حافظهٔ من.""" + return int(getattr(licmod, "TRIAL_DAYS", 14)) + + +def _today() -> date: + return datetime.now(timezone.utc).date() + + +def _parse(value: str | None) -> date: + if not value: + return _today() + try: + return date.fromisoformat(str(value)[:10]) + except ValueError as exc: # تاریخ خراب = خطای روشن، نه سکوت + raise ValueError(f"تاریخ «{value}» خوانده نشد؛ قالب درست: YYYY-MM-DD") from exc + + +def gate_conditions() -> list[dict]: + """پنج شرط «کارنامهٔ آماده» با عددهای خودِ کد (اگر کسی شرط‌ها را عوض کند، برگه هم عوض می‌شود).""" + p = inspect.signature(dailytrial.scorecard).parameters + days = int(p["target_days"].default) + real_days = int(p["target_real_days"].default) + ratio = int(round(float(p["min_marked_ratio"].default) * 100)) + moves = int(p["min_moves"].default) + return [ + {"name": "تداوم روزانه", "want": f"{fa(days)} روز ثبت‌شده", + "why": f"هر روز کاری یک بار «مراسم امروز»؛ {fa(days)} روز یعنی دو هفتهٔ کاری."}, + {"name": "روزهای با دادهٔ واقعی", "want": f"{fa(real_days)} روز واقعی (نه ساختگی)", + "why": "خوراک آزمایشی برای تمرین است؛ برای تصمیم، روز واقعی لازم است."}, + {"name": "بازسنجی دفتر", "want": f"دست‌کم {fa(ratio)}٪ ردیف‌ها بازسنجی‌شده", + "why": "بازسنجی نشان می‌دهد موتور با قیمت‌های تازه هم اجرا می‌شود."}, + {"name": "حرکت واقعی در دفتر", "want": f"{fa(moves)} حرکت معنادار (دست‌کم یکی بازتر، یکی بسته)", + "why": "هم فرصت تازه لازم است، هم فرصتی که بسته شده؛ هر دو نشانهٔ درست‌کاری است."}, + {"name": "زنجیرهٔ هش دفتر", "want": "سالم (هیچ ردیفی دست‌کاری نشده)", + "why": "اگر زنجیره بشکند، تا پیدا نشود به دفتر استناد نکنید."}, + ] + + +def first_day_steps(client: str) -> list[dict]: + """پنج کار روز اول، به همین ترتیب. هر ردیف: چه کاری، کجا، و چرا.""" + name = client.strip() or "نام مشتری" + return [ + {"n": 1, "title": "اجازه‌نامهٔ آزمون دو هفته‌ای، نام‌دار", + "where": "ترمینال، در پوشهٔ station", + "cmd": f'python3 license.py --grant "{name}" --trial --save', + "then": "python3 license.py --document", + "why": f"تا پایان این {fa(trial_days())} روز هیچ تعهد ماهانه‌ای گرفته نمی‌شود؛ دسترسی " + "روزشمار، نام‌دار و امضاشده است. سند چاپی‌اش را همان روز بدهید."}, + {"n": 2, "title": "نصب روی رایانهٔ خودشان", + "where": "بستهٔ تحویل → `iran-desk-kit.zip` → `START-HERE-FA.md` → `run-gui.bat`", + "cmd": None, "then": None, + "why": "همه‌چیز محلی است: نه حسابی ساخته می‌شود، نه رمز سامانهٔ کارگزاری پرسیده می‌شود، " + "نه داده‌ای به بیرون می‌رود."}, + {"n": 3, "title": "اتصال داده: سه پروفایل رایگان، صفر خرید", + "where": "گام ۲ → «امتحان منابع رایگان»", + "cmd": None, "then": None, + "why": "تا کارنامه آماده نشود، هیچ خرید داده‌ای پیشنهاد نمی‌شود؛ اگر روزی سرویس خریدنی " + "گرفتید، جایش در همان گام ۲ است."}, + {"n": 4, "title": "اعداد امروز از کارگزاری خودشان", + "where": "گام ۲ → جدول اسنپ‌شات (دستی یا «چسباندن از سامانهٔ کارگزاری»)", + "cmd": None, "then": None, + "why": "موتور با عدد واقعی خودشان کار می‌کند، نه با نمونهٔ ما؛ وجه تضمین و کارمزد جزو " + "همان عددهای ورودی است."}, + {"n": 5, "title": "مراسم امروز و راستی‌آزمایی به دست خودشان", + "where": "گام ۹ → «اجرای مراسم امروز» و بعد پروندهٔ سرمایه‌گذار", + "cmd": "python3 selftest.py", + "then": "python3 -m unittest discover -s tests", + "why": "روز اول کارنامه زرد و قرمز است — این طبیعی است. عددها ساختهٔ ما نیستند؛ خودشان " + "می‌توانند هر ردیف را بازتولید کنند."}, + ] + + +def no_buy_gate() -> list[str]: + """دو هفتهٔ اول چه چیزی خریده نمی‌شود (سرمایهٔ خودشان دست‌نخورده می‌مانَد).""" + d = fa(trial_days()) + return [ + f"**هیچ دادهٔ خریدنی** لازم نیست؛ در این {d} روز فقط پروفایل‌های رایگان و اسنپ‌شات خودتان.", + "**هیچ سفارشی** به کارگزاری فرستاده نمی‌شود و کدی هم برایش نوشته نشده (ابلاغیهٔ مهر ۱۳۹۹).", + "**هیچ سرمایه‌ای** از طرف شما درگیر نمی‌شود؛ تمرین روی همان حساب واقعی خودتان، با اندازهٔ " + "کوچک، تصمیم خودتان.", + f"**هیچ پرداخت ماهانه‌ای** در این {d} روز گرفته نمی‌شود؛ فقط پلهٔ راه‌اندازی/آموزش.", + ] + + +def build_onboarding(client: str = "", *, start: str | None = None, monthly_rial: int = 0, + setup_rial: int = 0, html_path: Path | str | None = None, + md_path: Path | str | None = None) -> tuple[Path, Path]: + """برگهٔ روز اول را می‌سازد. خروجی: (مسیر HTML، مسیر متن).""" + hp = Path(html_path) if html_path else PACK_HTML + mp = Path(md_path) if md_path else PACK_MD + hp.parent.mkdir(parents=True, exist_ok=True) + mp.parent.mkdir(parents=True, exist_ok=True) + + client_txt = client.strip() or "نام مشتری" + day0 = _parse(start) + review = day0 + timedelta(days=trial_days()) + steps = first_day_steps(client_txt) + gates = gate_conditions() + kit = kit_facts() + price = price_line(monthly_rial, setup_rial) + ladder = licmod.ladder() + + kit_sentence = ( + f"بستهٔ `{kit['kit']}` با {fa(kit['files'])} پرونده و اثر انگشت `sha256` هر پرونده" + if kit.get("files") else + "بستهٔ کد و اسناد با اثر انگشت `sha256` هر پرونده") + + md = "\n".join([ + "# روز اول مشتری — از «بله» تا پایان هفتهٔ دوم", "", + f"**برای:** {client_txt} · **شروع:** {fa(day0.isoformat())} · " + f"**روز بازبینی:** {fa(review.isoformat())}", "", + f"**قرار امروز:** دسترسی آزمون {fa(trial_days())} روزه، بدون هیچ تعهد ماهانه.", "", + "## پنج کار روز اول (به همین ترتیب)", "", + *[f"{fa(s['n'])}. **{s['title']}** — {s['where']}" + + (f" \n `{s['cmd']}`" if s.get("cmd") else "") + + (f" \n بعد: `{s['then']}`" if s.get("then") else "") + f" \n چرا: {s['why']}" + for s in steps], + "", + "## در این دو هفته چه چیزی خریده نمی‌شود", "", + *[f"- {row}" for row in no_buy_gate()], + "", + "## شرط‌های پایان هفتهٔ دوم (کارنامهٔ «آماده»)", "", + "| شرط | عدد لازم | چرا |", "| --- | --- | --- |", + *[f"| {g['name']} | {g['want']} | {g['why']} |" for g in gates], "", + f"روز بازبینی: **{fa(review.isoformat())}**. اگر کارنامه «آماده» بود، پلهٔ دوم معنی دارد؛ " + "اگر نبود، بازبینی را عقب می‌اندازیم و همان دو هفته‌ای که هست را بررسی می‌کنیم — بدون " + "ادعا و بدون عجله.", "", + "## پله‌ها و قاعدهٔ پرداخت", "", + *[f"- **{row['step']}**: {row['what']} — {row['basis']}" for row in ladder], + "", + f"**قیمت:** {price['text']}", "", + "پرداخت در برابر **شاهد** است، نه وعده: هر پله پس از تحویل پروندهٔ همان پله. " + "**درصدی از سود گرفته نمی‌شود**؛ اگر روزی کسی چنین چیزی پیشنهاد داد، همان‌جا رد کنید.", "", + "**هیچ سود تضمینی و هیچ پیش‌بینی قیمت در کار نیست**؛ خروجی این ایستگاه «عدد و دلیل» است " + "و تصمیم، تصمیم خودتان.", "", + "## ریتم روز شما (شصت ثانیه)", "", + "- هر روز کاری: «مراسم امروز» (گام ۹) — یک بار، همان ساعت.", + "- هفتهٔ اول: فقط ثبت و نگاه؛ هیچ تصمیم بزرگی بر پایهٔ کارنامهٔ ناتمام گرفته نمی‌شود.", + f"- پایان {fa(trial_days())} روز: بازبینی با هم، روی همان لپ‌تاپ، با پروندهٔ سرمایه‌گذار و " + "زنجیرهٔ سالم.", "", + "## اگر وسط راه پشیمان شدید", "", + "- دسترسی در همان تاریخ نام‌دار تمام می‌شود؛ هیچ قفلی روی برنامه نیست.", + "- پرونده‌ها، دفترها و اعداد روی رایانهٔ خودتان می‌مانَد (مالکیت با شماست).", + "- دادهٔ شما هیچ‌وقت جایی فرستاده نشده که پس گرفته شود.", "", + "## سؤال پایان بازبینی", "", + "«چه چیزی را باید در این دو هفته ببینید تا بگویید ارزش داشت؟» — جواب همین سؤال، کارِ " + "هفتهٔ سوم را تعیین می‌کند.", "", + "---", "", + f"اجرا و آموزش (پلهٔ ۱): پرداخت‌شده · اجازه‌نامهٔ آزمون تا {fa(review.isoformat())}", "", + "امضای ارائه‌دهنده: ____________________ امضای شما: ____________________", "", + f"تحویل داده می‌شود: {kit_sentence}.", "", + rk.DEVELOPER_HTML if hasattr(rk, "DEVELOPER_HTML") else licmod.CREDIT, "", + ]) + mp.write_text(md, encoding="utf-8") + + def steps_html() -> str: + rows = [] + for s in steps: + cmd = f'
    {rk.esc(s["cmd"])}' if s.get("cmd") else "" + then = f'
    بعد: {rk.esc(s["then"])}' if s.get("then") else "" + rows.append(f'
  • {rk.esc(s["title"])} — {rk.esc(s["where"])}' + f'{cmd}{then}
    چرا: {rk.esc(s["why"])}
  • ') + return "
      " + "".join(rows) + "
    " + + body = "".join([ + '
    این برگه بعد از «بله» است، نه قبل از آن. دو هفتهٔ اول، ' + 'دسترسی آزمون است و هیچ تعهد ماهانه‌ای گرفته نمی‌شود؛ هدف این دو هفته فقط یک چیز است: ' + 'دیدن اینکه کارنامه «آماده» می‌شود یا نه.
    ', + f'

    برای: {rk.esc(client_txt)} · شروع: {fa(day0.isoformat())} · ' + f'روز بازبینی: {fa(review.isoformat())}

    ', + "

    ۱. پنج کار روز اول

    ", steps_html(), + "

    ۲. در این دو هفته چه چیزی خریده نمی‌شود

    ", + "
      " + "".join(f"
    • {rk.esc(row.replace('**', ''))}
    • " for row in no_buy_gate()) + "
    ", + "

    ۳. شرط‌های پایان هفتهٔ دوم (کارنامهٔ «آماده»)

    ", + "" + + "".join(f"" + f"" for g in gates) + + "
    شرطعدد لازمچرا
    {rk.esc(g['name'])}{rk.esc(g['want'])}{rk.esc(g['why'])}
    ", + f'

    روز بازبینی {fa(review.isoformat())} است. اگر کارنامه «آماده» بود، ' + 'پلهٔ دوم معنی دارد؛ اگر نبود، بازبینی عقب می‌افتد و همان دو هفته بررسی می‌شود.

    ', + "

    ۴. پله‌ها و قاعدهٔ پرداخت

    ", + "" + + "".join(f"" + f"" for r in ladder) + + "
    پلهچه چیزیدر برابر چه چیزی
    {rk.esc(r['step'])}{rk.esc(r['what'])}{rk.esc(r['basis'])}
    ", + f'

    قیمت: {rk.esc(price["text"])}

    ', + '

    پرداخت در برابر شاهد است، نه وعده: هر پله پس از تحویل پروندهٔ همان پله. ' + 'هیچ درصدی از سود گرفته نمی‌شود.

    ', + '

    هیچ سود تضمینی و هیچ پیش‌بینی قیمت در کار نیست؛ خروجی این ایستگاه «عدد و ' + 'دلیل» است و تصمیم، تصمیم خودتان.

    ', + "

    ۵. ریتم روز شما (شصت ثانیه)

    ", + "
    • هر روز کاری، همان ساعت: «مراسم امروز» در گام ۹.
    • " + "
    • هفتهٔ اول فقط ثبت و نگاه؛ هیچ تصمیم بزرگی بر پایهٔ کارنامهٔ ناتمام.
    • " + f"
    • پایان {fa(trial_days())} روز: بازبینی با هم، روی همان لپ‌تاپ.
    ", + "

    ۶. اگر وسط راه پشیمان شدید

    ", + "
    • دسترسی در همان تاریخ نام‌دار تمام می‌شود؛ هیچ قفلی روی برنامه نیست.
    • " + "
    • پرونده‌ها و دفترها روی رایانهٔ خودتان می‌مانَد؛ مالکیت با شماست.
    • " + "
    • داده‌ای جایی فرستاده نشده که پس گرفته شود.
    ", + "

    ۷. سؤال پایان بازبینی

    ", + '

    «چه چیزی را باید در این دو هفته ببینید تا بگویید ارزش داشت؟» — ' + 'جواب همین سؤال، کارِ هفتهٔ سوم را تعیین می‌کند.

    ', + f'

    اجرا و آموزش (پلهٔ ۱): پرداخت‌شده · اجازه‌نامهٔ آزمون تا ' + f'{fa(review.isoformat())}

    ', + '

    امضای ارائه‌دهنده: ____________________    ' + 'امضای شما: ____________________

    ', + f'

    تحویل داده می‌شود: {rk.esc(kit_sentence)}.

    ', + f'

    {rk.DEVELOPER_HTML}

    ', + ]) + hp.write_text(rk.page("روز اول مشتری — ایستگاه تصمیم مشتقه", body, + subtitle=f"{client_txt} · {fa(day0.isoformat())}"), + encoding="utf-8") + return hp, mp + + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description="برگهٔ روز اول مشتری (از «بله» تا پایان هفتهٔ دوم)") + ap.add_argument("--client", default="", help="نام مشتری یا شرکت") + ap.add_argument("--start", default="", help="روز شروع YYYY-MM-DD (پیش‌فرض: امروز)") + ap.add_argument("--monthly", type=int, default=0, help="حق دسترسی ماهانه (ریال)؛ ندهید، «توافقی»") + ap.add_argument("--setup", type=int, default=0, help="مبلغ راه‌اندازی/آموزش (ریال)") + ap.add_argument("--json", action="store_true", help="خروجی ماشین‌خوان") + ap.add_argument("--version", action="version", version=f"onboarding {VERSION}") + a = ap.parse_args(argv) + + try: + h, m = build_onboarding(a.client, start=a.start or None, + monthly_rial=a.monthly, setup_rial=a.setup) + except ValueError as exc: + print(f"خطا: {exc}", file=sys.stderr) + return 2 + + day0 = _parse(a.start or None) + if a.json: + print(json.dumps({"html": str(h), "md": str(m), "client": a.client or None, + "start": day0.isoformat(), + "review": (day0 + timedelta(days=trial_days())).isoformat(), + "trial_days": trial_days(), "price_given": bool(a.monthly or a.setup), + "kit": kit_facts(), + "gates": [{"name": g["name"], "want": g["want"]} for g in gate_conditions()]}, + ensure_ascii=False)) + return 0 + print("برگهٔ روز اول مشتری ساخته شد:") + print(" برگهٔ چاپی:", h) + print(" نسخهٔ متنی (برای ایمیل/واتساپ):", m) + print(f" روز بازبینی: {fa((day0 + timedelta(days=trial_days())).isoformat())}") + print(" قیمت:", price_line(a.monthly, a.setup)["text"]) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/station/outreach.py b/station/outreach.py new file mode 100644 index 0000000000000000000000000000000000000000..0d6de144a64bb3c1eeb37e04ab94da97332cd410 --- /dev/null +++ b/station/outreach.py @@ -0,0 +1,267 @@ +"""پیام‌های معرفی و پیگیری — همان چیزی که باید بفرستی تا اولین جلسه گرفته شود. + +چرا جدا از برگهٔ «پیشنهاد» است: آن برگه بعد از جلسه معنا دارد؛ این بسته، پیش از جلسه. چهار +متن آماده می‌سازد (پیام اول، پیام بعد از جواب، تأیید وقت، و پیگیری)، به‌همراه یک اسکریپت تماس +تلفنی و پاسخ چهار مخالفت رایج — همه با نام خودت و نام مخاطب، آمادهٔ کپی. + +قاعده‌ای که در متن‌ها سخت‌گیرانه رعایت می‌شود: هیچ وعدهٔ سود، هیچ عدد سود، هیچ فوریت ساختگی، +و هیچ پیوستی در پیام اول. هدفِ پیام اول فقط یک چیز است: **گرفتن نیم‌ساعت وقت**. + +اجرا: + python3 outreach.py --client "نام مخاطب" # ساخت بستهٔ پیام‌ها + python3 outreach.py --client "..." --kind brokerage # لحن مناسب کارگزاری + python3 outreach.py --json +""" +from __future__ import annotations + +import argparse +import json +import sys +from datetime import datetime, timezone +from pathlib import Path + +BASE = Path(__file__).resolve().parent +if str(BASE) not in sys.path: + sys.path.insert(0, str(BASE)) + +import reportkit as rk # noqa: E402 + +VERSION = "0.1.0" +DATA = BASE / "data" +PACK_MD = DATA / "outreach-pack.md" +PACK_HTML = DATA / "outreach-pack.html" + +# لحن‌ها: کدام دسته از مخاطب قرار است این را بخواند +KINDS = { + "brokerage": "کارگزاری یا شرکت تأمین سرمایه", + "company": "شرکت غیرمالی (تولیدی، بازرگانی، طلا و ارز)", + "teacher": "مدرس یا تحلیلگر بازار سرمایه", + "known": "آشنای خودت که در بازار است", +} + +_DIGITS = str.maketrans("0123456789", "۰۱۲۳۴۵۶۷۸۹") + + +def fa(value) -> str: + return str(value).translate(_DIGITS) + + +def messages(client: str = "", *, kind: str = "company", sender: str = "مسعود") -> dict: + """چهار متن آماده + اسکریپت تماس. هر متن با نام مخاطب و امضای خودت پر می‌شود.""" + who = client.strip() + tone = KINDS.get(kind, KINDS["company"]) + # خطاب با نام کوچک، فقط وقتی مخاطب «آدم» است؛ برای شرکت و کارگزاری، خطاب سرد و رسمی درست‌تر است + greet = (f"سلام {who}، وقتتان بخیر." if (who and kind in ("known", "teacher")) + else "سلام، وقتتان بخیر.") + + first = ( + f"{greet}\n\n" + "من یک ابزار کوچک نوشته‌ام که کارش «داوری سیگنال» است: سیگنالی که شما یا ابزارتان " + "می‌بینید را با کارمزد واقعی، اسپرد و فاصله تا اخطاریهٔ مارجین می‌سنجد و می‌گوید " + "می‌مانَد یا می‌افتد.\n\n" + "دنبال فروش چیزی نیستم. اگر صلاح می‌دانید، نیم‌ساعت وقت بگیریم و روی لپ‌تاپ خودتان " + "یک سیگنال واقعی را با هم بسنجیم؛ بعد خودتان بگویید به کارتان می‌آید یا نه." + ) + + second = ( + "ممنون که جواب دادید.\n\n" + "یک سؤال که جوابش برایم مهم است: الان وقتی یک سیگنال می‌رسد، با چه چیزی تصمیم می‌گیرید " + "که ارزش ورود دارد؟ (کارمزد؟ حجم؟ فاصله تا مارجین؟ تجربهٔ خودتان؟)\n\n" + "اگر بخواهید، همان جواب شما را می‌گذاریم روی میز و من نشان می‌دهم ابزارم چه چیزی به آن " + "اضافه می‌کند. نیم‌ساعت، روی لپ‌تاپ خودتان، بدون هیچ تعهدی." + ) + + confirm = ( + f"{greet}\n\nوقت جلسه را تأیید می‌کنم.\n\n" + "برای نیم‌ساعت، این سه چیز لازم است: (۱) لپ‌تاپ خودتان با پایتون نصب‌شده، (۲) یک سیگنال " + "واقعی که همین هفته دیده‌اید، با عددهای همان روز، و (۳) اگر شد، وجه تضمینی که کارگزاری " + "می‌دهد (این عدد را هیچ سایتی نمی‌دهد).\n\n" + "من فقط لپ‌تاپ را می‌گذارم جلوی خودتان؛ دکمه‌ها را خودتان می‌زنید." + ) + + followup = ( + f"{greet}\n\nمزاحم نمی‌شوم؛ فقط یک یادآوری کوتاه که جلسه‌مان هیچ تعهدی ندارد و اگر وقتش " + "نشد، اشکالی ندارد.\n\n" + "اگر موضوع برایتان جالب بود، همین‌جا بگویید و یک نیم‌ساعت می‌گذاریم. اگر هم نه، همان " + "یک جمله برایم بنویسید که چرا؛ خودش برای من ارزش دارد." + ) + + call = ( + "۴۰ ثانیهٔ اول تماس (آرام، بدون اصطلاح فنی):\n" + "\"سلام، وقتتان بخیر. من مسعودم؛ یک ابزار کوچک نوشته‌ام که سیگنال‌های بازار را قبل از " + "ورود می‌سنجد. وقتتان یک دقیقه آزاد است که بگویم چطور؟\"\n\n" + "اگر گفت بله، همین دو جمله:\n" + "\"بیشتر نرم‌افزارها می‌گویند کجا سود هست. ابزار من می‌گوید با کارمزد و اسپرد واقعی و " + "فاصله تا اخطاریهٔ مارجین، همان سیگنال می‌مانَد یا می‌افتد. برای همین می‌خواهم نیم‌ساعت " + "با هم یک سیگنال واقعی خودتان را بسنجیم.\"\n\n" + "سه سؤالی که می‌پرسی (و زیاد حرف نزن):\n" + "۱. الان تصمیم ورود را با چه چیزی می‌گیرید؟\n" + "۲. آخرین بار با چه چیزی فهمیدید یک سیگنال ارزش نداشت؟\n" + "۳. اگر عدد همان روز را پیش از سفارش می‌داشتید، چه چیزی در کارتان عوض می‌شد؟\n\n" + "جملهٔ بستن: \"اجازه می‌دهید نیم‌ساعت وقت بگیریم؟ من می‌آیم یا آنلاین، هر جور راحت‌ترید.\"" + ) + + objections = [ + ("این را خودتان نوشته‌اید؟ از کجا بدانم کار می‌کند؟", + "بله، خودم نوشته‌ام و پنهان نمی‌کنم که برنامه‌نویس ساده‌ام. برای همین روی لپ‌تاپ " + "خودتان نشان می‌دهم و آزمون‌هایش را خودتان اجرا می‌کنید: هر عددی کلیدی است دو بار و " + "با دو روش حساب می‌شود، و برگهٔ آزمون چاپی دارد. باور نکنید تا خودتان ببینید."), + ("ما نرم‌افزار و سیگنال خودمان را داریم.", + "خوب است؛ من نمی‌آیم جای آن را بگیرم. ابزار من سیگنال خودتان را داوری می‌کند: می‌مانَد " + "یا می‌افتد. اگر کار نکند، همان‌جا در نیم‌ساعت معلوم می‌شود."), + ("داده‌اش را از کجا می‌آورید؟ پولش چقدر است؟", + "هیچ خرید داده‌ای پیشنهاد نمی‌کنم. برنامه با منابع رایگان کار می‌کند (نرخ دلار، طلا و " + "سکه و یک صرافی)؛ عددهای قرارداد را هم از سامانهٔ خودتان برمی‌داریم، چون بعضی از آن‌ها " + "(مثل وجه تضمین) را هیچ سایتی نمی‌دهد. تا وقتی فایده‌اش ثابت نشود، یک ریال هم هزینه " + "ندارد."), + ("ما اجازهٔ معاملهٔ الگوریتمی نداریم.", + "درست است و من هم هیچ سفارشی نمی‌فرستم. کدِ ارسال سفارش هم در برنامه نیست. خروجی، " + "«عدد و دلیل» است و سفارش را خودتان در سامانه می‌زنید."), + ] + + return { + "kind": kind, + "kind_label": tone, + "sender": sender, + "client": client.strip() or None, + "first_message": first, + "second_message": second, + "confirm_message": confirm, + "followup_message": followup, + "call_script": call, + "objections": [{"objection": o, "answer": a} for o, a in objections], + "rules": [ + "پیام اول کوتاه است و هیچ پیوستی ندارد؛ هدفش فقط نیم‌ساعت وقت است.", + "هیچ عدد سودی، هیچ بازدهی، و هیچ فوریت ساختگی در هیچ پیامی نیست.", + "پیگیری فقط سه بار: روز ۰، روز ۳، روز ۱۰. بعد رهایش کن؛ سوزاندن آدم، بدتر از نگرفتن جلسه است.", + "هر پیام با یک سؤال تمام می‌شود، نه با یک ادعا.", + "هیچ‌وقت پیام یکسان برای چند نفر در یک گروه؛ همان لحظه به‌عنوان اسپم شناخته می‌شوی.", + ], + } + + +def build_pack(client: str = "", *, kind: str = "company", sender: str = "مسعود", + md_path: Path | str | None = None, + html_path: Path | str | None = None) -> tuple[Path, Path]: + """بستهٔ پیام‌ها را می‌سازد. خروجی: (مسیر HTML، مسیر متن).""" + mp = Path(md_path) if md_path else PACK_MD + hp = Path(html_path) if html_path else PACK_HTML + mp.parent.mkdir(parents=True, exist_ok=True) + hp.parent.mkdir(parents=True, exist_ok=True) + m = messages(client, kind=kind, sender=sender) + today = fa(datetime.now(timezone.utc).strftime("%Y-%m-%d")) + + md = "\n".join([ + "# بستهٔ پیام‌های معرفی و پیگیری", "", + f"**مخاطب:** {m['client'] or '«نام مخاطب را در کادر بنویسید»'} · " + f"**لحن:** {m['kind_label']} · **تاریخ:** {today}", "", + "هدفِ تنها: گرفتن یک نیم‌ساعت وقت. نه فروش، نه توضیح فنی.", "", + "## ۱. پیام اول (کپی کن و بفرست)", "", "```text", m["first_message"], "```", "", + "> اگر جواب داد، برو سراغ پیام ۲. اگر جواب نداد، تا روز ۳ صبر کن.", "", + "## ۲. پیام بعد از جواب", "", "```text", m["second_message"], "```", "", + "## ۳. تأیید وقت جلسه", "", "```text", m["confirm_message"], "```", "", + "## ۴. پیگیری (فقط دو بار)", "", "```text", m["followup_message"], "```", "", + "## ۵. اسکریپت تماس تلفنی", "", "```text", m["call_script"], "```", "", + "## ۶. چهار مخالفت و پاسخ صادقانه", "", + *[f"**«{o['objection']}»**\n\n{o['answer']}\n" for o in m["objections"]], + "## ۷. پنج قاعده که نمی‌شکنیم", "", + *[f"- {r}" for r in m["rules"]], "", + "## ۸. جاهایی که ارزش شروع دارند", "", + "- **کارگزاری‌ها و شرکت‌های تأمین سرمایه:** واحد آموزش یا مدیریت ریسک. آن‌ها روزی چند " + "سیگنال می‌بینند و دقیقاً همان‌جا جای داوری خالی است.", + "- **شرکت‌های غیرمالی که با ارز، طلا یا مواد اولیه کار می‌کنند:** تولیدی، بازرگانی، طلا و " + "جواهر. برایشان «قیمت پایه» مسئلهٔ روز است، نه بازی.", + "- **مدرس‌ها و تحلیلگرهای بازار سرمایه:** با یک نیم‌ساعت، هم ابزار را می‌بینند و هم " + "می‌توانند معرف باشند.", + "- **آشنایانی که خودشان معامله می‌کنند:** صادق‌ترین آزمون اول همین‌جاست؛ اگر آن‌ها بی‌علاقه " + "باشند، احتمالاً پیام هم مشکل دارد.", + "- **دانشگاه و انجمن علمی مالی:** جلسهٔ نیم‌ساعته با استاد یا انجمن، هم تمرین ارائه است " + "و هم گاهی مسیر مشتری.", "", + "✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · 📱 [989126630554](tel:+989126630554) · " + "✈️ [Telegram: Mojarabian](https://t.me/Mojarabian) · " + "📸 [Instagram: Mojarabian.Art](https://instagram.com/Mojarabian.Art)", "", + ]) + mp.write_text(md, encoding="utf-8") + + def block(title: str, text: str) -> str: + return (f"

    {rk.esc(title)}

    " + f'
    {rk.esc(text)}
    ') + + body = "".join([ + '
    هدف این بسته یک چیز است: گرفتن یک نیم‌ساعت وقت. هیچ وعدهٔ ' + 'سودی در هیچ‌کدام از این متن‌ها نیست و هیچ پیوستی هم در پیام اول نمی‌رود.
    ', + f'

    مخاطب: {rk.esc(m["client"] or "«نام مخاطب را در کادر بنویسید»")}' + f' · لحن: {rk.esc(m["kind_label"])} · تاریخ: {today}

    ', + block("۱. پیام اول", m["first_message"]), + block("۲. پیام بعد از جواب", m["second_message"]), + block("۳. تأیید وقت جلسه", m["confirm_message"]), + block("۴. پیگیری (فقط دو بار)", m["followup_message"]), + block("۵. اسکریپت تماس تلفنی", m["call_script"]), + "

    ۶. چهار مخالفت و پاسخ صادقانه

    ", + "".join(f'

    «{rk.esc(o["objection"])}»
    {rk.esc(o["answer"])}

    ' + for o in m["objections"]), + "

    ۷. پنج قاعده که نمی‌شکنیم

    ", + "
      " + "".join(f"
    • {rk.esc(r)}
    • " for r in m["rules"]) + "
    ", + "

    ۸. جاهایی که ارزش شروع دارند

    ", + "
    • کارگزاری‌ها و شرکت‌های تأمین سرمایه: واحد آموزش یا مدیریت ریسک.
    • " + "
    • شرکت‌های غیرمالی با ریسک قیمت: تولیدی، بازرگانی، طلا و جواهر.
    • " + "
    • مدرس‌ها و تحلیلگرهای بازار سرمایه.
    • " + "
    • آشنایانی که خودشان معامله می‌کنند: صادق‌ترین آزمون اول.
    • " + "
    • دانشگاه و انجمن علمی مالی.
    ", + f'

    {rk.DEVELOPER_HTML}

    ', + ]) + hp.write_text(rk.page("بستهٔ پیام‌های معرفی و پیگیری", body, + subtitle=f"{m['client'] or 'بدون نام'} · {m['kind_label']}"), + encoding="utf-8") + return hp, mp + + +def checklist() -> list[dict]: + """کارهای آماده‌سازی پیش از اولین پیام؛ هرکدام با دلیلش.""" + return [ + {"task": "یک شمارهٔ تماس و یک پیام‌رسان که همیشه در دسترس است", + "why": "اولین پیام بی‌جواب می‌ماند اگر راه برگشت نداشته باشد."}, + {"task": "برگهٔ پیشنهاد یک‌صفحه‌ای چاپ‌شده در کیف", + "why": "در جلسه دستش می‌دهی؛ فرستادنش در پیام اول، آدم را فروشنده نشان می‌دهد."}, + {"task": "یک سیگنال واقعی نمونه روی لپ‌تاپ (با تاریخ روز)", + "why": "جلسه بدون نمونهٔ واقعی، تبدیل به حرف می‌شود."}, + {"task": "پوشهٔ بستهٔ تحویل روی فلش یا لپ‌تاپ", + "why": "اگر خواست، همان‌جا نشان می‌دهی که تحویل واقعی داری."}, + {"task": "یک تمرین دو دقیقه‌ای از جملهٔ تمایز", + "why": "«سیگنال شما را داوری می‌کنم: می‌مانَد یا می‌افتد» باید بی‌لکنت گفته شود."}, + {"task": "آماده بودن پاسخ چهار مخالفت (همین بسته)", + "why": "مخالفت، پایان جلسه نیست؛ اگر جواب کوتاه و صادقانه باشد، ادامه می‌دهد."}, + ] + + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description="بستهٔ پیام‌های معرفی و پیگیری") + ap.add_argument("--client", default="", help="نام مخاطب (روی پیام‌ها می‌آید)") + ap.add_argument("--kind", default="company", choices=sorted(KINDS), help="لحن مناسب مخاطب") + ap.add_argument("--sender", default="مسعود", help="نام خودت در امضا") + ap.add_argument("--json", action="store_true") + ap.add_argument("--checklist", action="store_true", help="فهرست آماده‌سازی پیش از پیام اول") + ap.add_argument("--version", action="version", version=f"outreach {VERSION}") + a = ap.parse_args(argv) + + if a.checklist: + for i, row in enumerate(checklist(), 1): + print(f"{fa(i)}. {row['task']}\n چرا: {row['why']}") + return 0 + + h, m = build_pack(a.client, kind=a.kind, sender=a.sender) + if a.json: + print(json.dumps({"html": str(h), "md": str(m), "kind": a.kind, + "client": a.client or None, + "messages": len(messages(a.client, kind=a.kind, sender=a.sender)) - 4}, + ensure_ascii=False)) + return 0 + print("بستهٔ پیام‌ها ساخته شد:") + print(" برگهٔ چاپی:", h) + print(" نسخهٔ متنی (برای کپی):", m) + print(f" لحن: {KINDS.get(a.kind, a.kind)}") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/station/prospects.py b/station/prospects.py new file mode 100644 index 0000000000000000000000000000000000000000..c346ada662f2f85d984daa8fdb7ff9d92bced714 --- /dev/null +++ b/station/prospects.py @@ -0,0 +1,492 @@ +"""تابلوی پیگیری مخاطبان — همان «پنج نام» هفتگی که سند ۱۴ می‌گوید. + +چرا این ابزار: سند `14-first-meeting-fa.md` یک ریتم هفتگی دارد (پنج مخاطب، پیام، پیگیری روز ۳ و +روز ۱۰) و سه عدد که هر هفته باید شمرده شود. انجام دادنش با دفتر کاغذی ممکن است، ولی خیلی زود +«کی را باید پیگیری کنم؟» از دست می‌رود. این ابزار فقط همان کار را می‌کند و بس: + +- فهرست محلی مخاطبان روی همین رایانه (هیچ شبکه‌ای در کار نیست). +- می‌گوید **امروز** چه کسی پیگیری لازم دارد (روز ۳، روز ۱۰، قرار جلسه، ثبت نتیجه). +- سه عدد هفته را می‌شمارد: چند پیام، چند تماس، چند جلسه. +- یک برگهٔ چاپی «تابلوی پیگیری» می‌سازد تا روی میز باشد. + +قاعده‌های اخلاقی که در خودِ ابزار قفل شده‌اند: پیگیری فقط سه بار (روز ۰، ۳، ۱۰) · هیچ فوریت +ساختگی · هیچ شمارهٔ تلفنی در دفتر ذخیره نمی‌شود (شماره جای دیگری است، این‌جا فقط نام و وضعیت) · +«بعداً» بی‌تاریخ نمی‌مانَد: سی روز بعد، همان روز به «کار امروز» برمی‌گردد (یک پیام، نه بیشتر). + +اجرا: + python3 prospects.py --add "نام مخاطب" --kind brokerage --channel telegram + python3 prospects.py --sent "نام مخاطب" + python3 prospects.py --reply "نام مخاطب" --note "پرسید داده از کجاست" + python3 prospects.py --meeting "نام مخاطب" --date 2026-09-27 + python3 prospects.py --outcome "نام مخاطب" --result بله + python3 prospects.py --outcome "نام مخاطب" --result بعداً --next-on 2026-10-22 + python3 prospects.py --todo # امروز چه کسی را پیگیری کنم + python3 prospects.py --week # سه عدد این هفته + python3 prospects.py --sheet # برگهٔ چاپی تابلوی پیگیری +""" +from __future__ import annotations + +import argparse +import json +import os +import re +import sys +from datetime import date, datetime, timedelta, timezone +from pathlib import Path + +BASE = Path(__file__).resolve().parent +if str(BASE) not in sys.path: + sys.path.insert(0, str(BASE)) + +import reportkit as rk # noqa: E402 + +VERSION = "0.1.0" +DATA = BASE / "data" +STORE = Path(os.environ.get("IRAN_DESK_PROSPECTS") or (DATA / "prospects.json")) +SHEET_MD = DATA / "prospects-board.md" +SHEET_HTML = DATA / "prospects-board.html" + +# کانال‌ها و لحن‌ها همان چیزهایی است که سند ۱۴ و بستهٔ پیام‌ها می‌شناسند +CHANNELS = {"telegram": "تلگرام", "whatsapp": "واتساپ", "phone": "تلفن", + "inperson": "حضوری", "linkedin": "لینکدین", "email": "ایمیل"} +KINDS = {"brokerage": "کارگزاری / تأمین سرمایه", "company": "شرکت غیرمالی", + "teacher": "مدرس یا تحلیلگر", "known": "آشنای بازار", "university": "دانشگاه / انجمن علمی"} +RESULTS = ("بله", "نه", "بعداً", "بی‌جواب") +FOLLOWUP_DAYS = (3, 10) # فقط دو پیگیری؛ بار سوم یعنی «ببند» +LATER_DAYS = 30 # «بعداً» یعنی سی روز دیگر سر بزن؛ بی‌تاریخ، فراموش می‌شود +WEEKLY_TARGET = {"messages": 5, "calls": 1, "meetings": 1} + +_DIGITS = str.maketrans("0123456789", "۰۱۲۳۴۵۶۷۸۹") + + +def fa(value) -> str: + return str(value).translate(_DIGITS) + + +def _today() -> date: + return datetime.now(timezone.utc).date() + + +def _iso(d: date) -> str: + return d.isoformat() + + +def _parse(value: str | None) -> date | None: + if not value: + return None + try: + return date.fromisoformat(str(value)[:10]) + except ValueError: + return None + + +# ------------------------------------------------------------------ انبار محلی + +def load(path: Path | str | None = None) -> list[dict]: + p = Path(path) if path else STORE + if not p.exists(): + return [] + try: + data = json.loads(p.read_text(encoding="utf-8")) + except (json.JSONDecodeError, OSError): + return [] + rows = data if isinstance(data, list) else data.get("prospects", []) + return [r for r in rows if isinstance(r, dict) and r.get("name")] + + +def save(rows: list[dict], path: Path | str | None = None) -> Path: + p = Path(path) if path else STORE + p.parent.mkdir(parents=True, exist_ok=True) + p.write_text(json.dumps(rows, ensure_ascii=False, indent=1), encoding="utf-8") + return p + + + +_MASK = ( + (re.compile(r"\b\d{1,3}(?:[٬,]\d{3})+\b"), "‹عدد›"), # عدد جداکننده‌دار (مبلغ) + (re.compile(r"\b\d{7,}\b"), "‹عدد›"), # عدد بلند (شمارهٔ حساب/تلفن) + (re.compile(r"(?:\+?98|0)\d{9,10}"), "‹تلفن›"), # شمارهٔ تلفن +) + + +def clean_note(text: str) -> str: + """یادداشت را از عدد و شماره پاک می‌کند؛ این دفتر محلی است و نباید جای دادهٔ حساس شود.""" + out = (text or "").strip()[:200] + for pat, rep in _MASK: + out = pat.sub(rep, out) + return out + + +def _find(rows: list[dict], name: str) -> dict | None: + name = name.strip() + for r in rows: + if r.get("name") == name: + return r + return None + + +def add(name: str, *, kind: str = "company", channel: str = "telegram", + note: str = "", path: Path | str | None = None, when: str | None = None) -> dict: + """مخاطب تازه. نام تکراری ساخته نمی‌شود.""" + name = (name or "").strip() + if not name: + raise ValueError("نام مخاطب خالی است.") + rows = load(path) + if _find(rows, name): + return {"ok": False, "detail": f"«{name}» از قبل در تابلو هست.", "row": _find(rows, name)} + row = {"name": name, "kind": kind if kind in KINDS else "company", + "channel": channel if channel in CHANNELS else "telegram", + "note": clean_note(note), "created": _iso(_parse(when) or _today()), + "sent": None, "followup": [], "replied": None, "meeting": None, "result": None, + "history": []} + rows.append(row) + save(rows, path) + return {"ok": True, "row": row, "count": len(rows)} + + +def mark(name: str, event: str, *, when: str | None = None, note: str = "", + result: str = "", next_on: str | None = None, + path: Path | str | None = None) -> dict: + """یک گام را ثبت می‌کند: sent | followup | reply | meeting | outcome.""" + rows = load(path) + row = _find(rows, name) + if not row: + return {"ok": False, "detail": f"«{name}» در تابلو نیست."} + day = _parse(when) or _today() + stamp = _iso(day) + if event == "sent": + row["sent"] = row.get("sent") or stamp + row.setdefault("history", []).append(f"پیام اول — {stamp}") + elif event == "followup": + # فقط دو پیگیری؛ بار سوم رد می‌شود (قاعدهٔ سند ۱۴) + if len(row.get("followup") or []) >= len(FOLLOWUP_DAYS): + return {"ok": False, "detail": "دو پیگیری ثبت شده؛ قاعده این است که ببندی و رهایش کنی.", + "row": row} + row.setdefault("followup", []).append(stamp) + row.setdefault("history", []).append(f"پیگیری {len(row['followup'])} — {stamp}") + elif event == "reply": + row["replied"] = stamp + if note: + row["note"] = clean_note(note) + row.setdefault("history", []).append(f"جواب داد — {stamp}" + (f" · {note}" if note else "")) + elif event == "meeting": + row["meeting"] = stamp + row.setdefault("history", []).append(f"جلسه — {stamp}") + elif event == "outcome": + if result not in RESULTS: + return {"ok": False, "detail": f"نتیجه باید یکی از این‌ها باشد: {' · '.join(RESULTS)}", + "row": row} + row["result"] = result + if result == "بعداً": + # «بعداً» بی‌تاریخ یعنی فراموشی؛ پس تاریخ سر‌زدن هم ثبت می‌شود + back = _parse(next_on) if next_on else (day + timedelta(days=LATER_DAYS)) + if not back: + return {"ok": False, "detail": "تاریخ سر‌زدن خوانده نشد؛ قالب: YYYY-MM-DD", + "row": row} + row["next_on"] = _iso(back) + row.setdefault("history", []).append( + f"نتیجه: بعداً — {stamp} · سر زدن: {_iso(back)}" + (f" · {note}" if note else "")) + else: + row.pop("next_on", None) + row.setdefault("history", []).append(f"نتیجه: {result} — {stamp}" + + (f" · {note}" if note else "")) + else: + return {"ok": False, "detail": f"گام ناشناخته: {event}"} + save(rows, path) + return {"ok": True, "row": row, "event": event, "when": stamp} + + + +def _within(value: str | None, start: date, end: date) -> bool: + """آیا این تاریخ (رشته) داخل بازه است؟ رشتهٔ خراب یا خالی، «نه» است.""" + d = _parse(value) + return bool(d) and start <= d <= end + + +def todo(rows: list[dict] | None = None, *, on: str | None = None, + path: Path | str | None = None) -> list[dict]: + """امروز چه کاری برای چه کسی لازم است (بر پایهٔ روز ۳ و روز ۱۰).""" + rows = rows if rows is not None else load(path) + day = _parse(on) or _today() + out: list[dict] = [] + for r in rows: + if r.get("result"): + if r["result"] == "بعداً": + back = _parse(r.get("next_on")) or ((_parse(r.get("created")) or day) + + timedelta(days=LATER_DAYS)) + if day >= back: + out.append({"name": r["name"], + "action": "روز موعود رسید — یک پیام صادقانه بفرست", + "why": f"قرار بود {fa(_iso(back))} سر بزنیم و کارشان را ببینیم.", + "urgent": (day - back).days >= 7}) + continue + sent = _parse(r.get("sent")) + fups = [d for d in (_parse(x) for x in (r.get("followup") or [])) if d] + if r.get("meeting"): + mday = _parse(r["meeting"]) + if day >= mday: + out.append({"name": r["name"], "action": "نتیجهٔ جلسه را ثبت کن", + "why": f"جلسه {fa(mday.isoformat())} بود.", "urgent": day > mday}) + continue + if not sent and not r.get("replied"): + out.append({"name": r["name"], "action": "پیام اول را بفرست", + "why": f"از {fa(r.get('created', '—'))} در تابلو است و هنوز پیامی نرفته.", + "urgent": (day - (_parse(r.get("created")) or day)).days >= 2}) + continue + if r.get("replied") and not r.get("meeting"): + out.append({"name": r["name"], "action": "قرار جلسه را بگذار", + "why": f"روز {fa((day - _parse(r['replied'])).days)} پیش جواب داد.", + "urgent": (day - _parse(r["replied"])).days >= 2}) + continue + # هنوز جوابی نداده: نوبت پیگیری است؟ + if sent is None: # جواب داده ولی «پیام اول» ثبت نشده + out.append({"name": r["name"], "action": "قرار جلسه را بگذار", + "why": "جواب داده است؛ ثبت «پیام اول» جا افتاده، ولی کار بعدی روشن است.", + "urgent": False}) + continue + gap = (day - sent).days + for i, need in enumerate(FOLLOWUP_DAYS): + if gap >= need and len(fups) <= i: + out.append({"name": r["name"], + "action": f"پیگیری {fa(i + 1)} (روز {fa(need)})", + "why": f"{fa(gap)} روز از پیام اول گذشته و جوابی نیامده.", + "urgent": gap >= need + 3}) + break + else: + if len(fups) >= len(FOLLOWUP_DAYS) and gap > FOLLOWUP_DAYS[-1] + 7: + out.append({"name": r["name"], "action": "ببند و رهایش کن", + "why": f"{fa(gap)} روز و دو پیگیری؛ قاعده می‌گوید بس است.", + "urgent": False}) + return sorted(out, key=lambda x: (not x["urgent"], x["name"])) + + +def week_numbers(rows: list[dict] | None = None, *, on: str | None = None, + path: Path | str | None = None) -> dict: + """سه عدد هفته: پیام فرستاده‌شده، تماس، جلسه — با هدف هفتگی.""" + rows = rows if rows is not None else load(path) + day = _parse(on) or _today() + since = day - timedelta(days=6) + messages, followups, calls, meetings, replies = [], [], [], [], [] + for r in rows: + name = r["name"] + if _within(r.get("sent"), since, day): + messages.append(name) + if r.get("channel") == "phone": + calls.append(name) + if any(_within(x, since, day) for x in (r.get("followup") or [])): + followups.append(name) + if _within(r.get("meeting"), since, day): + meetings.append(name) + if _within(r.get("replied"), since, day): + replies.append(name) + return {"from": _iso(since), "to": _iso(day), + "messages": len(messages), "followups": len(followups), "calls": len(calls), + "meetings": len(meetings), "replies": len(replies), + "targets": dict(WEEKLY_TARGET), + "names": {"messages": messages, "meetings": meetings, "replies": replies}, + "note": ("این سه عدد را کنترل می‌کنی، نه بازار را. هدف هفته: پنج پیام، یک تماس، " + "یک جلسه.")} + + +def close(name: str, *, path: Path | str | None = None) -> dict: + """پرونده را می‌بندد (بدون نتیجهٔ «بله»): از فهرست پیگیری بیرون می‌رود.""" + rows = load(path) + row = _find(rows, name) + if not row: + return {"ok": False, "detail": f"«{name}» در تابلو نیست."} + row["result"] = row.get("result") or "بی‌جواب" + row.setdefault("history", []).append("بسته شد — بدون نتیجه") + save(rows, path) + return {"ok": True, "row": row} + + +def build_sheet(rows: list[dict] | None = None, *, md_path: Path | str | None = None, + html_path: Path | str | None = None, on: str | None = None, + path: Path | str | None = None) -> tuple[Path, Path]: + """برگهٔ چاپی تابلوی پیگیری: هر مخاطب، وضعیت، کار بعدی، و سه عدد هفته.""" + rows = rows if rows is not None else load(path) + mp = Path(md_path) if md_path else SHEET_MD + hp = Path(html_path) if html_path else SHEET_HTML + mp.parent.mkdir(parents=True, exist_ok=True) + hp.parent.mkdir(parents=True, exist_ok=True) + day = _parse(on) or _today() + items = todo(rows, on=day.isoformat()) + wk = week_numbers(rows, on=day.isoformat()) + todo_by_name = {i["name"]: i for i in items} + + def status(r: dict) -> str: + if r.get("result"): + if r["result"] == "بعداً": + back = r.get("next_on") or _iso((_parse(r.get("created")) or day) + + timedelta(days=LATER_DAYS)) + return f"بعداً — سر زدن {fa(back)}" + return f"بسته — {r['result']}" + if r.get("meeting"): + return f"جلسه: {fa(r['meeting'])}" + if r.get("replied"): + return "جواب داده، قرار جلسه مانده" + if r.get("sent"): + return f"پیام رفته ({fa(len(r.get('followup') or []))} پیگیری)" + return "هنوز پیامی نرفته" + + md = "\n".join([ + "# تابلوی پیگیری مخاطبان", "", + f"**تاریخ:** {fa(day.isoformat())} · **در تابلو:** {fa(len(rows))} · " + f"**کار امروز:** {fa(len(items))}", "", + "## سه عدد این هفته", "", + f"- پیام فرستاده‌شده: **{fa(wk['messages'])}** (هدف {fa(WEEKLY_TARGET['messages'])}) · " + f"تماس: **{fa(wk['calls'])}** (هدف {fa(WEEKLY_TARGET['calls'])}) · " + f"جلسه: **{fa(wk['meetings'])}** (هدف {fa(WEEKLY_TARGET['meetings'])})", + f"- پیگیری‌های رفته: {fa(wk['followups'])} · جواب‌های آمده: {fa(wk['replies'])}", "", + "## کار امروز (به همین ترتیب)", "", + *([f"{fa(i + 1)}. **{t['name']}** — {t['action']}" + (" ⚡" if t["urgent"] else "") + + f" \n چرا: {t['why']}" for i, t in enumerate(items)] + if items else ["امروز کاری در نوبت نیست. اگر تازه‌کاری، پنج نام این هفته را اضافه کن."]), + "", "## تابلو", "", + "| مخاطب | دسته | کانال | وضعیت | کار بعدی |", "| --- | --- | --- | --- | --- |", + *[f"| {r['name']} | {KINDS.get(r.get('kind'), '—')} | {CHANNELS.get(r.get('channel'), '—')} | " + f"{status(r)} | {todo_by_name.get(r['name'], {}).get('action', '—')} |" for r in rows], + "", "## قاعده‌ها", "", + "- پیگیری فقط سه بار: روز ۰ (پیام اول)، روز ۳، روز ۱۰. بعد پرونده را ببند.", + "- هیچ عدد سودی در هیچ پیامی نمی‌رود؛ هدف هر پیام، گرفتن یک نیم‌ساعت وقت است.", + "- شمارهٔ تلفن و نشانی هیچ‌جا در این دفتر ذخیره نمی‌شود؛ این دفتر محلی است و به هیچ " + "شبکه‌ای وصل نیست.", + "", "✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · 📱 [989126630554](tel:+989126630554) · " + "✈️ [Telegram: Mojarabian](https://t.me/Mojarabian) · " + "📸 [Instagram: Mojarabian.Art](https://instagram.com/Mojarabian.Art)", "", + ]) + mp.write_text(md, encoding="utf-8") + + def row_html(r: dict) -> str: + nxt = todo_by_name.get(r["name"], {}) + urgent = " ⚡" if nxt.get("urgent") else "" + return (f"{rk.esc(r['name'])}{rk.esc(KINDS.get(r.get('kind'), '—'))}" + f"{rk.esc(CHANNELS.get(r.get('channel'), '—'))}" + f"{rk.esc(status(r))}" + f"{rk.esc(nxt.get('action', '—'))}{urgent}") + + body = "".join([ + '
    این دفتر محلی است و به هیچ شبکه‌ای وصل نیست. هدفش یک چیز است: ' + 'هر هفته پنج پیام، و آن‌که نوبتش است از دست نرود.
    ', + f'

    تاریخ: {fa(day.isoformat())} · در تابلو: {fa(len(rows))} · ' + f'کار امروز: {fa(len(items))}

    ', + "

    ۱. سه عدد این هفته

    ", + f'

    پیام فرستاده‌شده: {fa(wk["messages"])} (هدف {fa(WEEKLY_TARGET["messages"])}) · ' + f'تماس: {fa(wk["calls"])} (هدف {fa(WEEKLY_TARGET["calls"])}) · ' + f'جلسه: {fa(wk["meetings"])} (هدف {fa(WEEKLY_TARGET["meetings"])}) · ' + f'پیگیری‌های رفته: {fa(wk["followups"])} · جواب‌های آمده: {fa(wk["replies"])}

    ', + "

    ۲. کار امروز

    ", + ("
      " + "".join(f'
    1. {rk.esc(t["name"])} — {rk.esc(t["action"])}' + f'{" ⚡" if t["urgent"] else ""}
      ' + f'چرا: {rk.esc(t["why"])}
    2. ' for t in items) + + "
    ") if items else '

    امروز کاری در نوبت نیست.

    ', + "

    ۳. تابلو

    ", + "" + "" + + "".join(row_html(r) for r in rows) + "
    مخاطبدستهکانالوضعیتکار بعدی
    ", + "

    ۴. قاعده‌ها

    ", + '
    • پیگیری فقط سه بار: روز ۰، روز ۳، روز ۱۰. بعد پرونده را ببند.
    • ' + '
    • هیچ عدد سودی در هیچ پیامی نمی‌رود؛ هدف هر پیام، گرفتن یک نیم‌ساعت وقت است.
    • ' + '
    • شمارهٔ تلفن و نشانی در این دفتر ذخیره نمی‌شود.
    ', + f'

    {rk.DEVELOPER_HTML}

    ', + ]) + hp.write_text(rk.page("تابلوی پیگیری مخاطبان", body, + subtitle=f"{fa(day.isoformat())} · {fa(len(rows))} مخاطب"), + encoding="utf-8") + return hp, mp + + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description="تابلوی پیگیری مخاطبان (محلی، بدون شبکه)") + ap.add_argument("--add", metavar="نام", help="مخاطب تازه") + ap.add_argument("--sent", metavar="نام", help="پیام اول فرستاده شد") + ap.add_argument("--followup", metavar="نام", help="پیگیری رفته (روز ۳ یا ۱۰)") + ap.add_argument("--reply", metavar="نام", help="جواب داد") + ap.add_argument("--meeting", metavar="نام", help="جلسه گذاشته شد") + ap.add_argument("--outcome", metavar="نام", help="نتیجهٔ جلسه") + ap.add_argument("--close", metavar="نام", help="پرونده را ببند") + ap.add_argument("--kind", default="company", choices=sorted(KINDS)) + ap.add_argument("--channel", default="telegram", choices=sorted(CHANNELS)) + ap.add_argument("--date", default="", help="تاریخ YYYY-MM-DD (پیش‌فرض: امروز)") + ap.add_argument("--note", default="") + ap.add_argument("--result", default="", choices=[""] + list(RESULTS)) + ap.add_argument("--next-on", default="", help="برای نتیجهٔ «بعداً»: روز سر‌زدن YYYY-MM-DD " + f"(پیش‌فرض: {LATER_DAYS} روز بعد)") + ap.add_argument("--todo", action="store_true", help="امروز چه کسی را پیگیری کنم") + ap.add_argument("--week", action="store_true", help="سه عدد این هفته") + ap.add_argument("--sheet", action="store_true", help="برگهٔ چاپی تابلوی پیگیری") + ap.add_argument("--json", action="store_true") + ap.add_argument("--version", action="version", version=f"prospects {VERSION}") + a = ap.parse_args(argv) + + when = a.date or None + ops = [("--add", a.add, lambda: add(a.add, kind=a.kind, channel=a.channel, note=a.note, when=when)), + ("--sent", a.sent, lambda: mark(a.sent, "sent", when=when, note=a.note)), + ("--followup", a.followup, lambda: mark(a.followup, "followup", when=when, note=a.note)), + ("--reply", a.reply, lambda: mark(a.reply, "reply", when=when, note=a.note)), + ("--meeting", a.meeting, lambda: mark(a.meeting, "meeting", when=when, note=a.note)), + ("--outcome", a.outcome, lambda: mark(a.outcome, "outcome", when=when, note=a.note, + result=a.result, next_on=a.next_on or None)), + ("--close", a.close, lambda: close(a.close))] + for _, value, fn in ops: + if value: + out = fn() + if a.json: + print(json.dumps(out, ensure_ascii=False)) + else: + print(("✅ " if out.get("ok") else "⚠️ ") + str(out.get("detail") or "ثبت شد.")) + return 0 if out.get("ok") else 1 + + if a.sheet: + h, m = build_sheet() + print("برگهٔ چاپی:", h) + print("نسخهٔ متنی:", m) + return 0 + + if a.todo: + items = todo() + if a.json: + print(json.dumps(items, ensure_ascii=False, indent=1)) + return 0 + if not items: + print("امروز کاری در نوبت نیست.") + return 0 + for i, t in enumerate(items, 1): + print(f"{fa(i)}. {t['name']} — {t['action']}{' ⚡' if t['urgent'] else ''}") + print(f" چرا: {t['why']}") + return 0 + + if a.week: + wk = week_numbers() + if a.json: + print(json.dumps(wk, ensure_ascii=False)) + return 0 + print(f"هفته {fa(wk['from'])} تا {fa(wk['to'])}") + print(f" پیام: {fa(wk['messages'])} (هدف {fa(WEEKLY_TARGET['messages'])}) · " + f"تماس: {fa(wk['calls'])} (هدف {fa(WEEKLY_TARGET['calls'])}) · " + f"جلسه: {fa(wk['meetings'])} (هدف {fa(WEEKLY_TARGET['meetings'])})") + print(f" پیگیری رفته: {fa(wk['followups'])} · جواب آمده: {fa(wk['replies'])}") + print(f" {wk['note']}") + return 0 + + rows = load() + if a.json: + print(json.dumps({"prospects": rows, "todo": todo(rows), "week": week_numbers(rows)}, + ensure_ascii=False)) + return 0 + print(f"تابلوی پیگیری — {fa(len(rows))} مخاطب · دفتر محلی: {STORE}") + for r in rows: + print(f" · {r['name']} ({KINDS.get(r.get('kind'), '—')}) — " + + (f"نتیجه: {r['result']}" if r.get("result") else + f"جلسه {fa(r['meeting'])}" if r.get("meeting") else + "جواب داده" if r.get("replied") else + f"پیام رفته {fa(r['sent'])}" if r.get("sent") else "هنوز پیامی نرفته")) + items = todo(rows) + print(f" کار امروز: {fa(len(items))}") + for t in items: + print(f" → {t['name']}: {t['action']}") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/station/reportkit.py b/station/reportkit.py new file mode 100644 index 0000000000000000000000000000000000000000..b038237ff254a7832d932fea85b9953c1a5317d4 --- /dev/null +++ b/station/reportkit.py @@ -0,0 +1,116 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""جعبه‌ابزار گزارش: صفحهٔ HTML خودبسندهٔ فارسی (راست‌به‌چپ، آمادهٔ چاپ). + +چرا جدا؟ هم «کارنامهٔ آزمون» و هم «پروندهٔ سرمایه‌گذار» یک ظاهر و یک سربرگ +داشته باشند. همه‌چیز درون‌خطی است تا صفحه آفلاین هم درست دیده شود. +""" +from __future__ import annotations + +import hashlib +import html +from datetime import datetime + +VERSION = "0.1.0" + +DEVELOPER_HTML = ( + 'دولوپر: مهندس مسعود مجربیان · همراه: 09126630554 · Telegram: Mojarabian · Instagram: Mojarabian.Art' +) + +CREDIT_HTML = ( + 'تهیه‌کنندهٔ جزوات: ' + "Masoud Mojarabian · " + '+989126630554 · ' + 'Telegram: Mojarabian · ' + 'Instagram: Mojarabian.Art' +) + +CSS = """ +:root { color-scheme: light; } +* { box-sizing: border-box; } +body { font-family: "Vazirmatn", "Tahoma", "Segoe UI", sans-serif; margin: 0; padding: 28px 20px 60px; + background: #f6f7f9; color: #1e2430; line-height: 1.9; direction: rtl; } +.wrap { max-width: 1000px; margin: 0 auto; background: #fff; border: 1px solid #e3e6ec; border-radius: 14px; + padding: 26px 28px 34px; box-shadow: 0 2px 10px rgba(20,30,50,.06); } +h1 { font-size: 24px; margin: 0 0 6px; } +h2 { font-size: 19px; margin: 26px 0 8px; padding-bottom: 6px; border-bottom: 2px solid #eef1f6; } +h3 { font-size: 16px; margin: 18px 0 6px; } +p, li { font-size: 14.5px; } +.sub { color: #5a6473; font-size: 13px; margin: 0 0 14px; } +table { width: 100%; border-collapse: collapse; margin: 10px 0 6px; font-size: 13.5px; } +th, td { border: 1px solid #e3e6ec; padding: 7px 9px; text-align: right; vertical-align: top; } +th { background: #f2f4f8; font-weight: 700; } +td.num, th.num { font-variant-numeric: tabular-nums; direction: ltr; text-align: left; } +tr.pass td:first-child { border-inline-start: 4px solid #1f9d55; } +tr.fail td:first-child { border-inline-start: 4px solid #d64545; } +.kpis { display: flex; flex-wrap: wrap; gap: 10px; margin: 12px 0; } +.kpi { flex: 1 1 150px; border: 1px solid #e3e6ec; border-radius: 10px; padding: 10px 12px; background: #fbfcfe; } +.kpi b { display: block; font-size: 20px; } +.kpi span { font-size: 12.5px; color: #5a6473; } +.badge { display: inline-block; padding: 2px 9px; border-radius: 999px; font-size: 12.5px; font-weight: 700; } +.badge.ok { background: #e6f6ec; color: #157347; border: 1px solid #b7e2c6; } +.badge.no { background: #fdeaea; color: #b02a2a; border: 1px solid #f3c2c2; } +.note { background: #fff8e6; border: 1px solid #f2dca9; border-radius: 10px; padding: 10px 12px; font-size: 13.5px; } +.honest { background: #eef6ff; border: 1px solid #cfe2fb; border-radius: 10px; padding: 10px 12px; font-size: 13.5px; } +code { background: #f2f4f8; padding: 1px 5px; border-radius: 5px; font-size: 12.8px; direction: ltr; + display: inline-block; } +.foot { margin-top: 26px; padding-top: 12px; border-top: 1px solid #e3e6ec; color: #5a6473; font-size: 12.5px; } +.foot a { color: #2b5fb0; text-decoration: none; } +.lines { border-bottom: 1px dashed #b9c0cc; height: 22px; margin: 6px 0; } +details { margin: 8px 0; } +summary { cursor: pointer; font-weight: 700; } +@media print { body { background: #fff; padding: 0; } .wrap { border: none; box-shadow: none; } } +""" + + +def esc(value) -> str: + return html.escape(str(value), quote=True) + + +def num(value, digits: int = 2) -> str: + """عدد فارسی‌خوان: جداکننده هزارگان + رقم اعشار ثابت.""" + if value is None: + return "—" + try: + f = float(value) + except (TypeError, ValueError): + return esc(value) + if abs(f) >= 1000: + return f"{f:,.{digits}f}" + return f"{f:.{digits}f}" + + +def page(title: str, body: str, *, subtitle: str = "", extra_css: str = "") -> str: + """یک صفحهٔ HTML کامل، خودبسنده و آمادهٔ چاپ.""" + stamp = datetime.now().strftime("%Y-%m-%d %H:%M") + return f""" + + + + +{esc(title)} + + + +
    +

    {esc(title)}

    +

    {esc(subtitle) if subtitle else ""} · ساخته‌شده: {esc(stamp)}

    +{body} +
    +

    {DEVELOPER_HTML}

    +

    {CREDIT_HTML}

    +

    این صفحه با کد ساخته شده است و همهٔ عددهایش از پرونده‌های همان اجرا خوانده می‌شود؛ + هیچ داده‌ای از اینترنت نمی‌آید و هیچ سود تضمینی در آن ادعا نمی‌شود.

    +
    +
    + + +""" + + +def sha256_text(text: str) -> str: + return hashlib.sha256(text.encode("utf-8")).hexdigest() + + +def digest_line(label: str, digest: str) -> str: + return f'

    {esc(label)}: {esc(digest)}

    ' diff --git a/station/review_meeting.py b/station/review_meeting.py new file mode 100644 index 0000000000000000000000000000000000000000..e885f5d34f4e805a1b6ffe23d182e00c0453d3bf --- /dev/null +++ b/station/review_meeting.py @@ -0,0 +1,407 @@ +"""جلسهٔ بازبینی دو هفته‌ای — سه شاهد، دو خروجی، یک تصمیم. + +جای این برگه در زنجیره: `outreach.py` جلسه را می‌گیرد، `onboarding.py` روز اول را راه می‌اندازد، +`sales_ritual.py` کار روزانه را نگه می‌دارد. این برگه برای **روز چهاردهم** است: همان جایی که +آزمون تمام می‌شود و باید تصمیم گرفته شود — ادامه با پرداخت، تمدید بی‌هزینه، یا توقف. + +قاعده‌ها از جای دیگری خوانده می‌شوند، نه از حافظهٔ من: + +- **طول آزمون** و **روز بازبینی**: از `license.TRIAL_DAYS` (`start + TRIAL_DAYS`). +- **شرط‌های «کارنامهٔ آماده»**: از `daily_trial.scorecard` (همان پنج شرطی که `onboarding.py` هم + نشان می‌دهد؛ یک منبع، دو برگه). +- **سه پلهٔ ارائه**: از `license.ladder()` · **قیمت**: از `offer.price_line` (اگر عددی داده نشود، + «توافقی» — قیمت خودساخته روی برگه نمی‌رود). +- **عددهای بستهٔ تحویل**: از `KIT-MANIFEST.json`. + +اجرا: + python3 review_meeting.py --client "نام مشتری" --start 2026-09-22 + python3 review_meeting.py --client "نام مشتری" --on 2026-10-06 --monthly 40000000 + python3 review_meeting.py --json +""" +from __future__ import annotations + +import argparse +import json +import sys +from datetime import date, datetime, timedelta, timezone +from pathlib import Path + +BASE = Path(__file__).resolve().parent +if str(BASE) not in sys.path: + sys.path.insert(0, str(BASE)) + +import license as licmod # noqa: E402 +import reportkit as rk # noqa: E402 +from offer import _kit_facts as kit_facts, fa, fa_num, price_line # noqa: E402 +from onboarding import gate_conditions # noqa: E402 (یک منبع برای پنج شرط کارنامه) + +VERSION = "0.1.0" +DATA = BASE / "data" +REVIEW_MD = DATA / "review-meeting.md" +REVIEW_HTML = DATA / "review-meeting.html" + +# پیگیری بعد از جلسه: اگر همان روز تصمیم نگرفتند، روز سرزدن پیش‌فرض یک ماه بعد است. +FOLLOW_ON_DAYS = 30 + + +def trial_days() -> int: + """طول آزمون — از خود ماژول اجازه‌نامه.""" + return int(getattr(licmod, "TRIAL_DAYS", 14)) + + +def _today() -> date: + return datetime.now(timezone.utc).date() + + +def _parse(value: str | None) -> date: + if not value: + return _today() + try: + return date.fromisoformat(str(value)[:10]) + except ValueError as exc: # تاریخ خراب = خطای روشن، نه سکوت + raise ValueError(f"تاریخ «{value}» خوانده نشد؛ قالب درست: YYYY-MM-DD") from exc + + +def review_day(start: str | None = None) -> date: + """روز بازبینی: همان روزی که اجازه‌نامهٔ آزمون تمام می‌شود.""" + return _parse(start) + timedelta(days=trial_days()) + + +def days_left(start: str | None = None, on: str | None = None) -> int: + """چند روز تا بازبینی مانده (منفی یعنی گذشته).""" + return (review_day(start) - _parse(on)).days + + +def status_line(start: str | None = None, on: str | None = None) -> str: + """وضعیت امروز نسبت به روز بازبینی — بدون فشار و بدون اغراق.""" + left = days_left(start, on) + if left > 0: + return f"{fa(left)} روز تا روز بازبینی مانده؛ این برگه را برای همان روز نگه دارید." + if left == 0: + return "امروز روز بازبینی است؛ همین نشست، تصمیم را روشن می‌کند." + return (f"{fa(-left)} روز از روز بازبینی گذشته است. جلسه را عقب نیندازید: همین هفته، " + "همان نیم‌ساعت.") + + +def witness_rows() -> list[dict]: + """سه شاهد (و یک شاهد اختیاری برای شرکت): چه فرمانی، چه چیزی را نشان می‌دهد، چه چیزی را نه.""" + return [ + {"n": 1, "name": "کارنامهٔ دو هفته", + "where": "ترمینال، در پوشهٔ station", + "cmd": "python3 daily_trial.py --status", + "shows": "پنج شرط دو هفته: تداوم روزانه، روزهای با دادهٔ واقعی، بازسنجی دفتر، حرکت " + "معنادار، و سالم‌بودن زنجیرهٔ هش.", + "not_shows": "این‌که کدام تصمیم سود داد — کارنامه کیفیت کار است، نه پیش‌بینی."}, + {"n": 2, "name": "دفتر استفادهٔ موفق", + "where": "ترمینال، در پوشهٔ station", + "cmd": "python3 usage_meter.py --summary --verify", + "shows": "چه کاری چند بار انجام شده، با دو امضا (ارائه‌دهنده و شرکت) و اثر انگشت " + "زنجیرهٔ دفتر.", + "not_shows": "درست‌بودن تصمیم‌ها؛ فقط نشان می‌دهد بعد از ثبت، کسی عدد را جای دیگری " + "عوض نکرده است."}, + {"n": 3, "name": "آزمون خودِ ایستگاه", + "where": "ترمینال، در پوشهٔ station", + "cmd": "python3 selftest.py", + "shows": "پانزده سنجه، هر کدام دو بار: یک بار با موتور و یک بار با حساب دستی مستقل.", + "not_shows": "آینده را؛ فقط نشان می‌دهد حساب‌ها امروز درست بسته می‌شوند."}, + {"n": 4, "name": "بستهٔ راستی‌آزمایی (اختیاری، برای شرکت)", + "where": "گام ۸ → «ساخت بستهٔ راستی‌آزمایی»", + "cmd": None, + "shows": "همان عددها با اثر انگشت `sha256` هر پرونده و چک‌لیست پنج‌دقیقه‌ای، برای " + "بازبینی توسط شخص سوم.", + "not_shows": "هیچ عدد تازه‌ای؛ برای بازبینی است، نه برای تبلیغ."}, + ] + + +def outcomes(monthly_rial: int = 0, setup_rial: int = 0) -> list[dict]: + """دو خروجی روشن جلسه: ادامه با پرداخت، یا توقف بی‌گلایه‌مندی.""" + price = price_line(monthly_rial, setup_rial) + ladder = licmod.ladder() + return [ + {"key": "continue", "title": "خروجی یک — ادامه با پرداخت", + "lines": [ + "**پله‌ها:** " + " · ".join(f"{r['step']} ({r['basis']})" for r in ladder), + f"**قیمت:** {price['text']}", + "**قاعده:** پرداخت در برابر **پروندهٔ همان پله** است، نه وعده. صورت‌جلسهٔ همین دو " + "هفته ضمیمهٔ پلهٔ دوم می‌شود: کارنامه، دفتر استفاده و بستهٔ شاهد.", + "**جملهٔ آماده برای گفتن:** «پلهٔ دوم را از امروز شروع می‌کنیم؛ صورت‌کار این دو هفته " + "هم ضمیمه است — هر عددش را خودتان می‌توانید بازتولید کنید.»", + ]}, + {"key": "stop", "title": "خروجی دو — توقف، بی‌گلایه‌مندی", + "lines": [ + "**سه کار همان شب:** (۱) در تابلو نتیجهٔ «نه» ثبت شود؛ (۲) اجازه‌نامه در همان تاریخ " + "نام‌دار تمام می‌شود و هیچ قفلی روی برنامه نیست؛ (۳) پرونده‌ها و دفترها روی رایانهٔ " + "خودشان می‌مانَد.", + "**خروجی‌ها را با خودشان ببرند:** `python3 usage_meter.py --statement` · " + "`python3 investor_test.py --sheet` · بستهٔ تحویل (`iran-desk-kit.zip`).", + "**جملهٔ آماده برای گفتن:** «امروز کار تمام است؛ اجازه‌نامه سر تاریخ خودش تمام می‌شود " + "و چیزی بدهکار نیستید. هر وقت خواستید، همان عددها اینجا هست.»", + ]}, + ] + + +def follow_up(on: str | None = None, follow_on: str | None = None) -> dict: + """اگر همان روز تصمیم نگرفتند: روز سرزدن تاریخ‌دار + دو پیام کوتاه، بدون عدد و بدون فشار.""" + day = _parse(on) + nxt = _parse(follow_on) if follow_on else day + timedelta(days=FOLLOW_ON_DAYS) + return { + "on": day.isoformat(), + "next_on": nxt.isoformat(), + "days": (nxt - day).days, + "messages": [ + {"when": "روز ۳", + "text": "سلام، وقتتان بخیر. فقط یک یادآوری کوچک: صورت‌جلسهٔ بازبینی و کارنامهٔ دو " + "هفته در همان پرونده است. اگر سؤالی دربارهٔ یکی از عددها داشتید، همان را " + "جواب می‌دهم."}, + {"when": "روز ۷", + "text": "سلام. نمی‌خواهم وقتتان را بگیرم؛ فقط بگویم پرونده دست‌نخورده و آماده است. " + "اگر خواستید، همان نیم‌ساعت را می‌گذاریم و تصمیم را با هم روشن می‌کنیم."}, + ], + "rule": "حداکثر همین دو پیام؛ بعد ساکت. اگر جواب نداد، پرونده در تابلو با تاریخ سرزدن " + "بسته می‌شود — همان قاعدهٔ سه‌بارِ پیگیری، بدون پیام سوم.", + } + + +QUESTIONS = [ + "چه چیزی را باید در این دو هفته می‌دیدید تا بگویید ارزش داشت؟", + "کدام عدد برایتان مهم‌تر بود: کارنامه، دفتر استفاده، یا آزمون ایستگاه؟", + "اگر فقط یک چیز را عوض کنیم، چه باشد؟", +] + +MISTAKES = [ + "**فشار آوردن برای تصمیم همان جلسه**؛ تصمیم دیرهنگام بهتر از تصمیم کور است.", + "**نشان دادن سود فرضی یا عدد ساخته**؛ اگر عددی نیست، «توافقی» و «کارنامه» جواب است.", + "**وعدهٔ تاریخ پول**؛ وعدهٔ پرداخت به آیندهٔ بازار داده نمی‌شود، به تحویل پرونده داده می‌شود.", +] + +BOUNDARIES = [ + "**هیچ سود تضمینی** و **هیچ پیش‌بینی قیمت** در کار نیست؛ خروجی این ایستگاه «عدد و دلیل» است.", + "**هیچ سفارشی** به کارگزاری فرستاده نمی‌شود و کدی هم برایش نوشته نشده (ابلاغیهٔ مهر ۱۳۹۹).", + "**هیچ درصدی از سود** گرفته نمی‌شود؛ اگر کسی چنین چیزی پیشنهاد داد، همان‌جا رد کنید.", + "**تصمیم، تصمیم خودشان است**؛ برنامه عدد و دلیل می‌دهد، نه دستور.", +] + + +def checklist(monthly_rial: int = 0, setup_rial: int = 0) -> list[str]: + """چک‌لیست دقیقه‌به‌دقیقهٔ همان جلسه (بیست دقیقه).""" + return [ + "دقیقهٔ ۰–۳: سه شاهد روی همان لپ‌تاپ اجرا شود؛ آن‌ها فرمان را می‌زنند، شما دست به " + "صفحه نمی‌زنید.", + "دقیقهٔ ۳–۸: کارنامه خوانده شود؛ هر شرطی که نشده، همان‌جا گفته شود.", + "دقیقهٔ ۸–۱۲: سه پرسش پایان، یکی‌یکی و با گوش دادن.", + "دقیقهٔ ۱۲–۱۷: خروجی روشن — ادامه با پرداخت، تمدید بی‌هزینه، یا توقف.", + "دقیقهٔ ۱۷–۲۰: اگر تصمیم نگرفتند، تاریخ سرزدن را همین‌جا در تابلو ثبت کنید.", + ] + + +def build_review(client: str = "", *, start: str | None = None, on: str | None = None, + monthly_rial: int = 0, setup_rial: int = 0, follow_on: str | None = None, + html_path: Path | str | None = None, + md_path: Path | str | None = None) -> tuple[Path, Path]: + """برگهٔ جلسهٔ بازبینی را می‌سازد. خروجی: (مسیر HTML، مسیر متن).""" + hp = Path(html_path) if html_path else REVIEW_HTML + mp = Path(md_path) if md_path else REVIEW_MD + hp.parent.mkdir(parents=True, exist_ok=True) + mp.parent.mkdir(parents=True, exist_ok=True) + + client_txt = client.strip() or "نام مشتری" + day0 = _parse(start) + today_on = _parse(on) + review = review_day(start) + witnesses = witness_rows() + gates = gate_conditions() + exits = outcomes(monthly_rial, setup_rial) + after = follow_up(on, follow_on) + status = status_line(start, on) + kit = kit_facts() + rows = checklist(monthly_rial, setup_rial) + + kit_sentence = ( + f"پروندهٔ کد و اسناد (`{kit['kit']}`) هم با اثر انگشت هر پرونده تحویل شده است." + if kit.get("files") else + "پروندهٔ کد و اسناد با اثر انگشت هر پرونده تحویل شده است.") + + header = (f"**برای:** {client_txt} · **شروع:** {fa(day0.isoformat())} · " + f"**روز بازبینی:** {fa(review.isoformat())} · **امروز:** {fa(today_on.isoformat())}") + witness_rows_md = [ + f"{fa(w['n'])}. **{w['name']}** — {w['where']}" + + (f" \n `{w['cmd']}`" if w.get("cmd") else "") + + f" \n نشان می‌دهد: {w['shows']} \n نشان نمی‌دهد: {w['not_shows']}" + for w in witnesses] + gate_rows_md = [f"| {g['name']} | {g['want']} | {g['why']} |" for g in gates] + exit_md: list[str] = [] + for e in exits: + exit_md.append(f"### {e['title']}") + exit_md.append("") + exit_md.extend(f"- {line}" for line in e["lines"]) + exit_md.append("") + follow_md = [ + f"- **تاریخ سرزدن پیش‌فرض:** {fa(after['next_on'])} (امروز + {fa(after['days'])} روز).", + f"- **ثبت در تابلو:** `python3 prospects.py --outcome \"{client_txt}\" --result \"بعداً\" " + f"--next-on {after['next_on']}`", + ] + for msg in after["messages"]: + follow_md.append(f"- **{msg['when']}:** «{msg['text']}»") + + md = "\n".join([ + "# جلسهٔ بازبینی دو هفته‌ای — سه شاهد، دو خروجی، یک تصمیم", + "", + header, + "", + f"**وضعیت:** {status}", + "", + "## ۱. بیست دقیقهٔ همین جلسه", + "", + *[f"- {row}" for row in rows], + "", + "## ۲. سه شاهد که خودشان می‌سازند", + "", + *[line for row in witness_rows_md for line in (row, "")], + "", + "## ۳. کارنامهٔ «آماده» — پنج شرط", + "", + "| شرط | عدد لازم | چرا |", + "| --- | --- | --- |", + *gate_rows_md, + "", + f"«آماده» یعنی همهٔ پنج شرط با هم. اگر یکی مانده، تصمیم امروز **تمدید** است، نه پرداخت: " + f"یک بار، بی‌هزینه، {fa(trial_days())} روز دیگر، با همان شرط‌ها.", + "", + "## ۴. دو خروجی روشن", + "", + *exit_md, + "## ۵. سه پرسش پایان", + "", + *[f"- {q}" for q in QUESTIONS], + "", + "## ۶. اگر امروز تصمیم نگرفتند", + "", + *follow_md, + "", + f"**قاعده:** {after['rule']}", + "", + "## ۷. سه اشتباه در این جلسه", + "", + *[f"- {m}" for m in MISTAKES], + "", + "## ۸. آنچه ادعا نمی‌کنم", + "", + *[f"- {b}" for b in BOUNDARIES], + "", + "---", + "", + f"شرکت: {client_txt} · تاریخ جلسه: {fa(today_on.isoformat())}", + "", + "امضای ارائه‌دهنده: ____________________ امضای شما: ____________________", + "", + kit_sentence, + "", + "سند راهنمای این جلسه: `MATERIALS/money/16-review-meeting-fa.md`.", + "", + rk.DEVELOPER_HTML, + "", + ]) + mp.write_text(md, encoding="utf-8") + + witness_html = [ + f'
  • {rk.esc(w["name"])} — {rk.esc(w["where"])}' + + (f'
    {rk.esc(w["cmd"])}' if w.get("cmd") else "") + + f'
    نشان می‌دهد: {rk.esc(w["shows"])}' + + f'
    نشان نمی‌دهد: {rk.esc(w["not_shows"])}
  • ' + for w in witnesses] + exits_html = [ + f'

    {rk.esc(e["title"])}

      ' + + "".join(f"
    • {rk.esc(line.replace('**', ''))}
    • " for line in e["lines"]) + + "
    " + for e in exits] + body = "".join([ + '
    این برگه برای روز چهاردهم است. سه شاهد روی همان لپ‌تاپ اجرا ' + 'می‌شود، بعد یک تصمیم روشن گرفته می‌شود: ادامه با پرداخت، تمدید بی‌هزینه، یا توقف — ' + 'بی‌گلایه‌مندی.
    ', + f'

    برای: {rk.esc(client_txt)} · شروع: {fa(day0.isoformat())} · ' + f'روز بازبینی: {fa(review.isoformat())} · امروز: {fa(today_on.isoformat())}

    ', + f'

    {rk.esc(status)}

    ', + "

    ۱. بیست دقیقهٔ همین جلسه

    ", + "
      " + "".join(f"
    • {rk.esc(row)}
    • " for row in rows) + "
    ", + "

    ۲. سه شاهد که خودشان می‌سازند

    ", + "
      " + "".join(witness_html) + "
    ", + "

    ۳. کارنامهٔ «آماده» — پنج شرط

    ", + "" + + "".join(f"" + f"" for g in gates) + + "
    شرطعدد لازمچرا
    {rk.esc(g['name'])}{rk.esc(g['want'])}{rk.esc(g['why'])}
    ", + f'

    «آماده» یعنی همهٔ پنج شرط با هم. اگر یکی مانده، تصمیم امروز تمدید است، نه ' + f'پرداخت: یک بار، بی‌هزینه، {fa(trial_days())} روز دیگر.

    ', + "

    ۴. دو خروجی روشن

    ", "".join(exits_html), + "

    ۵. سه پرسش پایان

    ", + "
      " + "".join(f"
    • {rk.esc(q)}
    • " for q in QUESTIONS) + "
    ", + "

    ۶. اگر امروز تصمیم نگرفتند

    ", + f'

    تاریخ سرزدن: {fa(after["next_on"])} (امروز + {fa(after["days"])} روز). ' + f'ثبت در تابلو: python3 prospects.py --outcome "{rk.esc(client_txt)}" ' + f'--result "بعداً" --next-on {after["next_on"]}

    ', + "
      " + "".join(f'
    • {rk.esc(m["when"])}: «{rk.esc(m["text"])}»
    • ' + for m in after["messages"]) + "
    ", + f'

    {rk.esc(after["rule"])}

    ', + "

    ۷. سه اشتباه در این جلسه

    ", + "
      " + "".join(f"
    • {rk.esc(m.replace('**', ''))}
    • " for m in MISTAKES) + "
    ", + "

    ۸. آنچه ادعا نمی‌کنم

    ", + "
      " + "".join(f"
    • {rk.esc(b.replace('**', ''))}
    • " for b in BOUNDARIES) + "
    ", + f'

    تاریخ جلسه: {fa(today_on.isoformat())} · ' + 'امضای ارائه‌دهنده: ____________________    امضای شما: ____________________

    ', + f'

    {rk.esc(kit_sentence)}

    ', + f'

    {rk.DEVELOPER_HTML}

    ', + ]) + hp.write_text(rk.page("جلسهٔ بازبینی دو هفته‌ای — ایستگاه تصمیم مشتقه", body, + subtitle=f"{client_txt} · {fa(review.isoformat())}"), + encoding="utf-8") + return hp, mp + + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description="برگهٔ جلسهٔ بازبینی دو هفته‌ای (سه شاهد، دو خروجی)") + ap.add_argument("--client", default="", help="نام مشتری یا شرکت") + ap.add_argument("--start", default="", help="روز شروع آزمون YYYY-MM-DD (پیش‌فرض: امروز)") + ap.add_argument("--on", default="", help="روز جلسهٔ بازبینی YYYY-MM-DD (پیش‌فرض: امروز)") + ap.add_argument("--monthly", type=int, default=0, help="حق دسترسی ماهانه (ریال)؛ ندهید، «توافقی»") + ap.add_argument("--setup", type=int, default=0, help="مبلغ راه‌اندازی/آموزش (ریال)") + ap.add_argument("--follow-on", default="", help="تاریخ سرزدن اگر تصمیم نگرفتند (پیش‌فرض: +۳۰ روز)") + ap.add_argument("--html", default="", help="مسیر برگهٔ چاپی (پیش‌فرض: data/review-meeting.html)") + ap.add_argument("--md", default="", help="مسیر نسخهٔ متنی (پیش‌فرض: data/review-meeting.md)") + ap.add_argument("--json", action="store_true", help="خروجی ماشین‌خوان") + ap.add_argument("--version", action="version", version=f"review_meeting {VERSION}") + a = ap.parse_args(argv) + + try: + h, m = build_review(a.client, start=a.start or None, on=a.on or None, + monthly_rial=a.monthly, setup_rial=a.setup, + follow_on=a.follow_on or None, + html_path=a.html or None, md_path=a.md or None) + except ValueError as exc: + print(f"خطا: {exc}", file=sys.stderr) + return 2 + + left = days_left(a.start or None, a.on or None) + if a.json: + print(json.dumps({"html": str(h), "md": str(m), "client": a.client or None, + "start": _parse(a.start or None).isoformat(), + "on": _parse(a.on or None).isoformat(), + "review": review_day(a.start or None).isoformat(), + "days_left": left, "trial_days": trial_days(), + "follow_on": follow_up(a.on or None, + a.follow_on or None)["next_on"], + "price_given": bool(a.monthly or a.setup), + "kit": kit_facts(), + "gates": [{"name": g["name"], "want": g["want"]} for g in gate_conditions()], + "outcomes": [e["key"] for e in outcomes(a.monthly, a.setup)]}, + ensure_ascii=False)) + return 0 + print("برگهٔ جلسهٔ بازبینی ساخته شد:") + print(" برگهٔ چاپی:", h) + print(" نسخهٔ متنی (برای ایمیل/واتساپ):", m) + print(" روز بازبینی:", fa(review_day(a.start or None).isoformat()), "·", status_line(a.start or None, a.on or None)) + print(" قیمت:", price_line(a.monthly, a.setup)["text"]) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/station/run-autoconnect.bat b/station/run-autoconnect.bat new file mode 100644 index 0000000000000000000000000000000000000000..2162e6b84d493fa098ab53179fe103aa733f8acb --- /dev/null +++ b/station/run-autoconnect.bat @@ -0,0 +1,13 @@ +@echo off +REM --------------------------------------------------------------------------- +REM اتصال خودکار: منابع رایگان را امتحان می‌کند و سالم‌ترین را ذخیره و فعال می‌کند. +REM اگر منبعی «کد نماد» بخواهد، کد نمادهای اسنپ‌شات را هم خودش پیدا می‌کند. +REM --------------------------------------------------------------------------- +chcp 65001 >nul +cd /d "%~dp0" +echo. +echo در حال امتحان منابع رایگان داده (چند ثانیه طول می‌کشد)... +echo. +python autoconnect.py --save --codes +echo. +pause diff --git a/station/run-daily-trial.bat b/station/run-daily-trial.bat new file mode 100644 index 0000000000000000000000000000000000000000..1c29054717e45f91b3a53e2e17af1067829e4e33 --- /dev/null +++ b/station/run-daily-trial.bat @@ -0,0 +1,15 @@ +@echo off +REM --------------------------------------------------------------------------- +REM مراسم روزانه — هر روز کاری یک بار دوبار کلیک کنید. +REM قیمت تازه می‌خواند، محاسبه می‌کند، در دفتر ثبت می‌کند، بازسنجی می‌کند، +REM گزارش سرمایه‌گذار را به‌روز می‌کند و کارنامه را نشان می‌دهد. هیچ سفارشی ارسال نمی‌شود. +REM --------------------------------------------------------------------------- +chcp 65001 >nul +cd /d "%~dp0" +echo. +echo مراسم روزانهٔ آزمون زنده — شروع +echo. +python daily_trial.py %* +echo. +echo گزارش سرمایه‌گذار: data\trial-report.html +pause diff --git a/station/run-gui-desktop.bat b/station/run-gui-desktop.bat new file mode 100644 index 0000000000000000000000000000000000000000..6fee4c2a06b954dd235559270eef398422797670 --- /dev/null +++ b/station/run-gui-desktop.bat @@ -0,0 +1,6 @@ +@echo off +chcp 65001 >nul +cd /d "%~dp0" +echo نسخهٔ دسکتاپ (اگر مرورگر را نمی‌خواهید) +python station.py +pause diff --git a/station/run-gui.bat b/station/run-gui.bat new file mode 100644 index 0000000000000000000000000000000000000000..4f3c34b5d05d0d0fb0c3c2267ede5471a7d710cb --- /dev/null +++ b/station/run-gui.bat @@ -0,0 +1,6 @@ +@echo off +chcp 65001 >nul +cd /d "%~dp0" +echo ایستگاه تصمیم مشتقه در حال روشن شدن است... +python web_server.py --port 8765 +pause diff --git a/station/run-investor-demo.bat b/station/run-investor-demo.bat new file mode 100644 index 0000000000000000000000000000000000000000..f42a83d9c14db732de1383c9718afe4853a3acf6 --- /dev/null +++ b/station/run-investor-demo.bat @@ -0,0 +1,13 @@ +@echo off +REM --------------------------------------------------------------------------- +REM دموی سرمایه‌گذار — ایستگاه + خوراک آزمایشی محلی، بدون هزینه و بدون اینترنت. +REM روی ویندوز دوبار کلیک کنید. مرورگر خودش باز می‌شود. +REM --------------------------------------------------------------------------- +chcp 65001 >nul +cd /d "%~dp0" +echo. +echo ایستگاه تصمیم مشتقه — دموی سرمایه‌گذار +echo (خوراک آزمایشی محلی هم خودکار بالا می‌آید: دادهٔ ساختگی، بدون هزینه) +echo. +python web_server.py --port 8765 +pause diff --git a/station/run-investor-test.bat b/station/run-investor-test.bat new file mode 100644 index 0000000000000000000000000000000000000000..cd38f0edbc46d0f2c0a53ea545b508ef94ea9ded --- /dev/null +++ b/station/run-investor-test.bat @@ -0,0 +1,34 @@ +@echo off +chcp 65001 >nul +REM آزمون کور سرمایه‌گذار: پرسش‌ها، پاسخ‌های برنامه با فرمول، و برگهٔ امضادار +cd /d "%~dp0" +echo ============================================================ +echo آزمون کور سرمایه‌گذار — اول حدس، بعد عدد +echo ============================================================ +echo. +echo 1) شش پرسش بدون پاسخ (لپ‌تاپ را به سرمایه‌گذار بدهید): +echo python investor_test.py --cases +echo. +echo 2) پاسخ‌ها با فرمول و روش دوم: +echo python investor_test.py --reveal +echo. +echo 3) آستانهٔ ریزش راهبردها و اندازهٔ موقعیت: +echo python investor_test.py --ladder +echo. +echo 4) حساب‌رسی یک معاملهٔ واقعی گذشته (نمونه): +echo python investor_test.py --reconcile --symbol فولاد --entry 7000 --exit 7400 --days 30 +echo. +echo 5) برگهٔ چاپی و بررسی زنجیره: +echo python investor_test.py --sheet +echo python investor_test.py --verify +echo. +dir /b investor_test.py >nul 2>&1 +if errorlevel 1 ( + echo [خطا] investor_test.py در همین پوشه پیدا نشد. + pause + exit /b 1 +) +python investor_test.py --cases +echo. +echo برای برگهٔ چاپی، این دستور را بزنید: python investor_test.py --sheet +pause diff --git a/station/run-mock-feed.bat b/station/run-mock-feed.bat new file mode 100644 index 0000000000000000000000000000000000000000..b6bb61db5b064cdbcd2aae535db3df3e85db76a2 --- /dev/null +++ b/station/run-mock-feed.bat @@ -0,0 +1,9 @@ +@echo off +REM خوراک آزمایشی محلی — قیمت ساختگی برای آزمایش و نمایش (بدون هزینه، بدون اینترنت) +chcp 65001 >nul +cd /d "%~dp0" +echo. +echo خوراک آزمایشی محلی روی http://127.0.0.1:8788/ بالا می‌آید. داده ساختگی است. +echo. +python mock_feed.py --port 8788 +pause diff --git a/station/run-selftest.bat b/station/run-selftest.bat new file mode 100644 index 0000000000000000000000000000000000000000..8f92a2346190a063c146be19225180899d4fb0b9 --- /dev/null +++ b/station/run-selftest.bat @@ -0,0 +1,12 @@ +@echo off +chcp 65001 >nul +cd /d "%~dp0" +echo ============================================================ +echo آزمون ۱۰ دقیقه‌ای ایستگاه — کارنامهٔ شاهد +echo هر مورد دو بار حساب می‌شود: موتور برنامه و حساب دستی مستقل. +echo ============================================================ +python selftest.py +echo. +echo کارنامه: data\selftest-report.html +echo برگهٔ آزمون سرمایه‌گذار: data\exam-sheet.html +pause diff --git a/station/run-tests.sh b/station/run-tests.sh new file mode 100644 index 0000000000000000000000000000000000000000..31f47db46213c6af400f53144f984d0e630fe472 --- /dev/null +++ b/station/run-tests.sh @@ -0,0 +1,15 @@ +#!/usr/bin/env bash +# آزمون کامل ایستگاه: آزمون‌های واحد + آزمون ساخت رابط گرافیکی + اجرای پس‌آزمایی نمونه +set -e +cd "$(dirname "$0")" +echo "— آزمون‌های واحد —" +python3 -m unittest discover -s tests +echo "— آزمون ساخت رابط گرافیکی دسکتاپ (نیازمند Xvfb روی لینوکس) —" +if command -v xvfb-run >/dev/null 2>&1; then + xvfb-run -a python3 station.py --smoke | tail -4 +else + python3 station.py --smoke | tail -4 +fi +echo "— پس‌آزمایی روی دادهٔ نمونه —" +python3 backtest.py demo/history-demo.csv --out data/backtest.html --csv data/backtest.csv | tail -4 +echo "همه سبز." diff --git a/station/sales_ritual.py b/station/sales_ritual.py new file mode 100644 index 0000000000000000000000000000000000000000..26cd79f5e0077fa1c1746cd1afe0d98a263f3459 --- /dev/null +++ b/station/sales_ritual.py @@ -0,0 +1,295 @@ +"""مراسم بیست‌دقیقه‌ای فروش — برگهٔ امروز، آماده برای اجرا. + +جای این ماژول در زنجیره: `prospects.py` می‌گوید امروز نوبت کدام مخاطب است؛ `outreach.py` متن +آماده را دارد. این ماژول همان دو را کنار هم می‌گذارد و یک برگهٔ اجرایی می‌سازد: کدام کار، برای +کدام مخاطب، با کدام متن، و در چه دقیقه‌ای — جمعاً بیست دقیقه. + +سه چیزی که در خود کد قفل است: + +- **سقف پنج پیام در روز** (`MAX_MESSAGES_PER_DAY`) و **سقف بیست دقیقه** (`BUDGET_MIN`): هر کاری + که جا نشد، با دلیلش به «فردا» می‌رود. هیچ‌وقت لیست را کش نمی‌دهیم تا کار بیشتر شود. +- **متن‌ها فقط از `outreach.messages` می‌آید**؛ این ماژول خودش متن تازه نمی‌سازد (تنها استثنا: + پیام «روز موعود» که همین‌جا نوشته شده و همان آزمون‌های سختی را می‌دهد که متن‌های outreach). +- **روزِ خالی، پیام نمی‌سازد**: اگر «کار امروز» خالی است، برگه می‌گوید پنج نام تازه اضافه کن؛ به + کسی که در نوبت نیست پیام نمی‌فرستیم تا عدد هفته پر شود. + +اجرا: + python3 sales_ritual.py # برنامهٔ امروز + python3 sales_ritual.py --sender "مسعود" # امضای پیام‌ها + python3 sales_ritual.py --sheet # برگهٔ چاپی امروز + python3 sales_ritual.py --json +""" +from __future__ import annotations + +import argparse +import json +import sys +from datetime import datetime, timezone +from pathlib import Path + +BASE = Path(__file__).resolve().parent +if str(BASE) not in sys.path: + sys.path.insert(0, str(BASE)) + +import outreach as outreachmod # noqa: E402 +import prospects as prospectsmod # noqa: E402 +import reportkit as rk # noqa: E402 + +VERSION = "0.1.0" +DATA = BASE / "data" +SHEET_MD = DATA / "sales-today.md" +SHEET_HTML = DATA / "sales-today.html" + +BUDGET_MIN = 20 +COST = {"message": 3, "call": 5, "internal": 2} +MAX_MESSAGES_PER_DAY = 5 + +# پیام «روز موعود» (نتیجهٔ «بعداً»): یک بار، بی‌فشار، بدون هیچ عددی +LATER_MESSAGE = ( + "سلام، وقتتان بخیر.\n\n" + "قرارمان امروز بود که سر بزنم؛ فقط همین یک پیام. اگر آن موضوع قبلی هنوز برایتان باز است، " + "همان نیم‌ساعت را بگذاریم؟\n\n" + "اگر بسته شده است، همین یک جمله کافی است و من دیگر مزاحم نمی‌شوم." +) + +RESULT_QUESTIONS = [ + "جوابشان دقیقاً چه بود: بله · بعداً · نه · بی‌جواب؟", + "یک جملهٔ خودشان را عیناً بنویس (همان جمله، نه برداشت تو).", + "تاریخ بعدی چه شد — و اگر «نه» بود، جواب سؤال «چه چیزی را باید ببینید؟» چه بود؟", +] + +RULE_LINES = [ + "هر مخاطب در روز فقط یک پیام؛ پیام یکسان برای چند نفر، اسپم شناخته می‌شود.", + "پیگیری فقط سه بار: روز ۰، ۳، ۱۰. بار سوم یعنی تمام — نه چهارمی.", + "هیچ عدد سود، هیچ بازدهی و هیچ فوریت ساختگی در هیچ پیامی نیست.", + "اگر «کار امروز» خالی است، پیام تازه نساز؛ پنج نام این هفته را اضافه کن.", +] + +_DIGITS = str.maketrans("0123456789", "۰۱۲۳۴۵۶۷۸۹") + + +def fa(value) -> str: + return str(value).translate(_DIGITS) + + +def _classify(item: dict, *, sender: str, kind: str, channel: str) -> dict: + """کار امروز را به یک کار اجرایی تبدیل می‌کند: پیام، تماس، یا کار دفتری.""" + action = item["action"] + m = outreachmod.messages(item["name"], kind=kind, sender=sender) + row = {"name": item["name"], "action": action, "why": item.get("why", ""), + "urgent": bool(item.get("urgent")), "kind_label": m["kind_label"], + "channel": channel, "channel_label": prospectsmod.CHANNELS.get(channel, "—"), + "text": None, "note": "", "minutes": 0, "start_min": None, "kind": None} + if action.startswith("پیام اول"): + row.update(kind="message", text=m["first_message"], minutes=COST["message"]) + elif action.startswith("پیگیری"): + row.update(kind="message", text=m["followup_message"], minutes=COST["message"]) + row["note"] = ("آخرین پیگیری (روز ۱۰)؛ بعد از این پرونده بسته می‌شود." + if "۲" in action else "پیگیری اول (روز ۳).") + elif action.startswith("قرار جلسه"): + row.update(kind="message", text=m["confirm_message"], minutes=COST["message"]) + elif action.startswith("روز موعود"): + row.update(kind="message", text=LATER_MESSAGE, minutes=COST["message"], + note="یک بار، بی‌فشار؛ اگر جواب نداد، پرونده بسته می‌شود.") + elif action.startswith("نتیجهٔ جلسه"): + row.update(kind="internal", minutes=COST["internal"], checklist=list(RESULT_QUESTIONS)) + elif action.startswith("ببند"): + row.update(kind="internal", minutes=COST["internal"], + note="پیامی نمی‌فرستی؛ پرونده را در تابلو ببند.") + else: + row.update(kind="internal", minutes=COST["internal"]) + if row["kind"] in ("message", "call") and channel == "phone": + # تماس تلفنی همان کار است، ولی گران‌تر: هزینه‌اش پنج دقیقه و متنش اسکریپت تماس + row.update(kind="call", text=m["call_script"], minutes=COST["call"], + note=(row["note"] + " " if row["note"] else "") + "کانال تلفنی است؛ اسکریپت تماس، نه پیام.") + return row + + +def plan(rows: list[dict] | None = None, *, on: str | None = None, sender: str = "مسعود", + path: Path | str | None = None) -> dict: + """برنامهٔ امروز: چه کاری، برای چه کسی، با چه متن، در چه دقیقه‌ای.""" + rows = rows if rows is not None else prospectsmod.load(path) + day = prospectsmod._parse(on) or datetime.now(timezone.utc).date() + items = prospectsmod.todo(rows, on=day.isoformat()) + by_name = {r["name"]: r for r in rows} + + scheduled: list[dict] = [] + deferred: list[dict] = [] + used = 0 + sent_messages = 0 + for item in items: + row = by_name.get(item["name"], {}) + work = _classify(item, sender=sender, kind=row.get("kind", "company"), + channel=row.get("channel", "telegram")) + if work["kind"] == "message" and sent_messages >= MAX_MESSAGES_PER_DAY: + deferred.append({"name": work["name"], "action": work["action"], + "reason": f"سقف {fa(MAX_MESSAGES_PER_DAY)} پیام امروز پر شد."}) + continue + if used + work["minutes"] > BUDGET_MIN: + deferred.append({"name": work["name"], "action": work["action"], + "reason": f"بودجهٔ {fa(BUDGET_MIN)} دقیقه پر شد."}) + continue + work["start_min"] = used + used += work["minutes"] + if work["kind"] == "message": + sent_messages += 1 + scheduled.append(work) + + counts = {"messages": len([x for x in scheduled if x["kind"] == "message"]), + "calls": len([x for x in scheduled if x["kind"] == "call"]), + "internal": len([x for x in scheduled if x["kind"] == "internal"]), + "deferred": len(deferred)} + if scheduled: + note = (f"هدف امروز {fa(counts['messages'] + counts['calls'])} پیام است، نه " + f"{fa(counts['messages'] + counts['calls'])} فروش. وقتی پیام رفت، کار امروز تمام است.") + elif rows: + note = ("امروز کسی در نوبت نیست؛ به کسی که نوبتش نیست پیام نمی‌فرستیم. " + "اگر تازه‌کاری، پنج نام این هفته را به تابلو اضافه کن.") + else: + note = ("تابلو خالی است. مرحلهٔ اول، اضافه‌کردن پنج نام است — تا آن‌ها نباشد، " + "مراسم امروز کاری برای انجام‌دادن ندارد.") + return {"date": day.isoformat(), "sender": sender, "budget": BUDGET_MIN, + "used_minutes": used, "items": scheduled, "deferred": deferred, "counts": counts, + "week": prospectsmod.week_numbers(rows, on=day.isoformat()), + "board": len(rows), "targets": dict(prospectsmod.WEEKLY_TARGET), "note": note, + "rules": list(RULE_LINES)} + + +def build_sheet(rows: list[dict] | None = None, *, on: str | None = None, sender: str = "مسعود", + md_path: Path | str | None = None, html_path: Path | str | None = None, + path: Path | str | None = None) -> tuple[Path, Path]: + """برگهٔ چاپی امروز: برنامه، متن‌های آماده، کار دفتری، و فردا.""" + p = plan(rows, on=on, sender=sender, path=path) + mp = Path(md_path) if md_path else SHEET_MD + hp = Path(html_path) if html_path else SHEET_HTML + mp.parent.mkdir(parents=True, exist_ok=True) + hp.parent.mkdir(parents=True, exist_ok=True) + + def slot(i: dict) -> str: + return f"دقیقهٔ {fa(i['start_min'])} تا {fa(i['start_min'] + i['minutes'])}" + + cap_line = (f"سقف امروز: {fa(MAX_MESSAGES_PER_DAY)} پیام و {fa(BUDGET_MIN)} دقیقه؛ هر کاری " + "که جا نشد، با دلیلش به «فردا» می‌رود. سقف را جابه‌جا نمی‌کنیم تا لیست پر شود.") + rules = [cap_line] + list(RULE_LINES) + plan_rows = [f"| {slot(i)} | {i['action']} | {i['name']} | {i['channel_label']} |" + for i in p["items"]] or ["| — | امروز کاری در نوبت نیست | — | — |"] + blocks = [f"### {i['name']} — {i['channel_label']} · {slot(i)}" + + (f"\n\n> {i['note']}" if i["note"] else "") + + f"\n\n```text\n{i['text']}\n```\n\n" + + "فرستادم ☐ جواب آمد ☐ جوابش را در تابلو ثبت کردم ☐\n" + for i in p["items"] if i["kind"] in ("message", "call")] or \ + ["امروز متن تازه‌ای برای فرستادن نیست."] + desk_rows = [f"**{i['name']}** — {i['action']}" + + (f" · {i['note']}" if i["note"] else "") + "\n" + + "".join(f" - {q}\n" for q in (i.get("checklist") or [])) + for i in p["items"] if i["kind"] == "internal"] or ["—"] + defer_rows = [f"- {d['name']} — {d['action']} ({d['reason']})" for d in p["deferred"]] or ["—"] + + md = "\n".join([ + "# برگهٔ فروش امروز — مراسم بیست‌دقیقه‌ای", "", + f"**تاریخ:** {fa(p['date'])} · **امضا:** {p['sender']} · " + f"**بودجه:** {fa(p['budget'])} دقیقه · **خرج‌شده:** {fa(p['used_minutes'])} دقیقه", "", + f"**{p['note']}**", "", + "## ۱. برنامهٔ امروز", "", + "| دقیقه | کار | مخاطب | کانال |", "| --- | --- | --- | --- |", + *plan_rows, "", + "## ۲. متن‌های آماده (کپی کن و بفرست)", "", + *blocks, + "## ۳. کار دفتری (بدون پیام)", "", + *desk_rows, "", + "## ۴. فردا (اگر جا نشد)", "", + *defer_rows, "", + "## ۵. سه عدد این هفته", "", + f"- پیام: **{fa(p['week']['messages'])}** (هدف {fa(p['targets']['messages'])}) · " + f"تماس: **{fa(p['week']['calls'])}** (هدف {fa(p['targets']['calls'])}) · " + f"جلسه: **{fa(p['week']['meetings'])}** (هدف {fa(p['targets']['meetings'])})", "", + "## ۶. قاعده‌ها", "", + *[f"- {r}" for r in rules], "", + rk.DEVELOPER_HTML if hasattr(rk, "DEVELOPER_HTML") else "", "", + ]) + mp.write_text(md, encoding="utf-8") + + rows_html = "".join( + f"{slot(i)}{rk.esc(i['action'])}{rk.esc(i['name'])}" + f"{rk.esc(i['channel_label'])}" for i in p["items"] + ) or 'امروز کاری در نوبت نیست.' + + boxes = '
    ' + ("".join( + f'

    {rk.esc(i["name"])} — ' + f'{rk.esc(i["channel_label"])} · {slot(i)}

    ' + + (f'

    {rk.esc(i["note"])}

    ' if i["note"] else "") + + f'
    {rk.esc(i["text"])}
    ' + '

    فرستادم ☐    جواب آمد ☐    در تابلو ثبت کردم ☐

    ' + for i in p["items"] if i["kind"] in ("message", "call") + ) or '

    امروز متن تازه‌ای برای فرستادن نیست.

    ') + "
    " + + desk = "".join( + f'

    {rk.esc(i["name"])} — {rk.esc(i["action"])}' + + (f' · {rk.esc(i["note"])}' if i["note"] else "") + + "

      " + "".join(f"
    • {rk.esc(q)}
    • " for q in (i.get("checklist") or [])) + + "
    " for i in p["items"] if i["kind"] == "internal" + ) or '

    کار دفتری‌ای نمانده است.

    ' + + body = "".join([ + f'
    {rk.esc(p["note"])}
    ', + f'

    تاریخ: {fa(p["date"])} · امضا: {rk.esc(p["sender"])} · ' + f'بودجه: {fa(p["budget"])} دقیقه · خرج‌شده: {fa(p["used_minutes"])} دقیقه

    ', + "

    ۱. برنامهٔ امروز

    ", + "" + f"{rows_html}
    دقیقهکارمخاطبکانال
    ", + "

    ۲. متن‌های آماده (کپی کن و بفرست)

    ", boxes, + "

    ۳. کار دفتری (بدون پیام)

    ", desk, + "

    ۴. فردا (اگر جا نشد)

    ", + "
      " + ("".join(f'
    • {rk.esc(d["name"])} — {rk.esc(d["action"])} ' + f'({rk.esc(d["reason"])})
    • ' + for d in p["deferred"]) or "
    • —
    • ") + "
    ", + "

    ۵. سه عدد این هفته

    ", + f'

    پیام: {fa(p["week"]["messages"])} (هدف {fa(p["targets"]["messages"])}) · ' + f'تماس: {fa(p["week"]["calls"])} (هدف {fa(p["targets"]["calls"])}) · ' + f'جلسه: {fa(p["week"]["meetings"])} (هدف {fa(p["targets"]["meetings"])})

    ', + "

    ۶. قاعده‌ها

    ", + "
      " + "".join(f"
    • {rk.esc(r)}
    • " for r in rules) + "
    ", + f'

    {rk.DEVELOPER_HTML}

    ', + ]) + hp.write_text(rk.page("برگهٔ فروش امروز — مراسم بیست‌دقیقه‌ای", body, + subtitle=f"{fa(p['date'])} · {fa(p['used_minutes'])} از " + f"{fa(p['budget'])} دقیقه"), + encoding="utf-8") + return hp, mp + + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description="مراسم بیست‌دقیقه‌ای فروش (برگهٔ امروز)") + ap.add_argument("--sender", default="مسعود", help="نام خودت در امضای پیام‌ها") + ap.add_argument("--on", default="", help="تاریخ YYYY-MM-DD (پیش‌فرض: امروز)") + ap.add_argument("--sheet", action="store_true", help="برگهٔ چاپی امروز") + ap.add_argument("--json", action="store_true") + ap.add_argument("--version", action="version", version=f"sales_ritual {VERSION}") + a = ap.parse_args(argv) + + if a.sheet: + h, m = build_sheet(on=a.on or None, sender=a.sender) + print("برگهٔ چاپی امروز:", h) + print("نسخهٔ متنی (برای کپی متن‌ها):", m) + return 0 + + p = plan(on=a.on or None, sender=a.sender) + if a.json: + print(json.dumps(p, ensure_ascii=False)) + return 0 + print(f"مراسم فروش — {fa(p['date'])} · بودجه {fa(p['budget'])} دقیقه " + f"(خرج‌شده {fa(p['used_minutes'])})") + if not p["items"]: + print(" " + p["note"]) + return 0 + for i in p["items"]: + mark = "☎" if i["kind"] == "call" else ("✉" if i["kind"] == "message" else "▣") + print(f" {mark} دقیقهٔ {fa(i['start_min'])} — {i['name']} ({i['channel_label']}): {i['action']}") + for d in p["deferred"]: + print(f" ↷ فردا — {d['name']}: {d['action']} ({d['reason']})") + print(" " + p["note"]) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/station/schedule-daily-trial.bat b/station/schedule-daily-trial.bat new file mode 100644 index 0000000000000000000000000000000000000000..f5d6ba9b0a048fdc26cb0e569caaea97d7a2d0b3 --- /dev/null +++ b/station/schedule-daily-trial.bat @@ -0,0 +1,21 @@ +@echo off +REM --------------------------------------------------------------------------- +REM زمان‌بندی خودکار مراسم روزانه در ویندوز (کارهای زمان‌بندی‌شده). +REM پیش‌فرض: هر روز ساعت 13:15. برای تغییر ساعت، عدد را عوض کنید. +REM برای حذف: schtasks /delete /tn "Station-Daily-Trial" /f +REM --------------------------------------------------------------------------- +chcp 65001 >nul +cd /d "%~dp0" +set TASK=Station-Daily-Trial +set TIME=13:15 +set PY=%~dp0daily_trial.py +schtasks /create /tn "%TASK%" /tr "python \"%PY%\"" /sc daily /st %TIME% /f +if errorlevel 1 ( + echo. + echo ساخت زمان‌بندی نشد. پنجرهٔ فرمان را با «اجرا به‌عنوان مدیر» باز کنید و دوباره امتحان کنید. +) else ( + echo. + echo زمان‌بندی ساخته شد: هر روز ساعت %TIME% مراسم روزانه خودش اجرا می‌شود. + echo کارنامه و لاگ هر روز در پوشهٔ data به‌روز می‌شود. +) +pause diff --git a/station/selftest.py b/station/selftest.py new file mode 100644 index 0000000000000000000000000000000000000000..ea447ef648c5265cce4b72152cb8d9272b975368 --- /dev/null +++ b/station/selftest.py @@ -0,0 +1,600 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""آزمون ۱۰ دقیقه‌ای ایستگاه — کارنامهٔ شاهد، برای نشان‌دادن به سرمایه‌گذار. + +منطق کار ساده است: هر مورد **دو بار** حساب می‌شود. +یک بار با موتور واقعی برنامه، یک بار با «حساب دستی» که همان‌جا در کد نوشته شده +و عددش را می‌شود با ماشین‌حساب هم چک کرد. اگر این دو از هم جدا شوند، مورد رد می‌شود. + +هیچ عددی دروغین نیست: اگر موتور عوض شود، کارنامه سرخ می‌شود. موردهای فرایندی +(زنجیرهٔ هش، روز واقعی، نبود آینده‌نگری، شکست صادقانهٔ دادهٔ زنده) هم همین‌جا سنجیده می‌شوند. + +اجرا: python selftest.py (کارنامه در کنسول + فایل HTML) + python selftest.py --json (خروجی ماشین‌خوان) + python selftest.py --only carry-90d,fees-kill-edge + python selftest.py --list +""" +from __future__ import annotations + +import argparse +import contextlib +import importlib.util +import io +import json +import sqlite3 +import sys +import tempfile +import time +from datetime import datetime, timezone +from pathlib import Path + +VERSION = "0.1.0" +BASE = Path(__file__).resolve().parent +DESK_DIR = (BASE.parent / "desk").resolve() +TOOLS_DIR = (BASE.parent / "tools").resolve() +DATA = BASE / "data" + +for p in (str(BASE), str(DESK_DIR)): + if p not in sys.path: + sys.path.insert(0, p) + +import reportkit as rk # noqa: E402 + +_ENGINE = None + + +def engine(): + """موتور ریاضی مشتقه — همان پرونده‌ای که ایستگاه در تصمیم زنده استفاده می‌کند.""" + global _ENGINE + if _ENGINE is None: + path = TOOLS_DIR / "derivatives_scout.py" + spec = importlib.util.spec_from_file_location("derivatives_scout", str(path)) + module = importlib.util.module_from_spec(spec) + assert spec.loader is not None + sys.modules["derivatives_scout"] = module # لازم برای dataclass داخل موتور + spec.loader.exec_module(module) + _ENGINE = module + return _ENGINE + + +def engine_fingerprint() -> dict: + from hashlib import sha256 + path = TOOLS_DIR / "derivatives_scout.py" + return {"file": str(path), "sha256": sha256(path.read_bytes()).hexdigest()[:16], + "version": getattr(engine(), "VERSION", "?"), "bytes": path.stat().st_size} + + +# ---------------------------------------------------------------- ابزار سنجش +def _cmp(got: dict, expected: dict, *, tol: float = 0.02) -> tuple[bool, list[dict]]: + """مقایسهٔ عدد/وضعیت با تلورانس کوچک (گرد کردن نمایش).""" + rows: list[dict] = [] + ok_all = True + for key, exp in expected.items(): + g = got.get(key) + if isinstance(exp, bool) or isinstance(exp, str) or exp is None: + good = g == exp + else: + try: + gv, ev = float(g), float(exp) + diff = abs(gv - ev) + good = diff <= tol or (ev != 0 and diff / abs(ev) <= 1e-9) + except (TypeError, ValueError): + good = False + ok_all = ok_all and good + rows.append({"key": key, "got": g, "expected": exp, "ok": good}) + return ok_all, rows + + +def _case(cid: str, title: str, why: str, inputs: dict, got: dict, expected: dict, + hand: str, *, tol: float = 0.02, notes: str = "") -> dict: + ok, rows = _cmp(got, expected, tol=tol) + return {"id": cid, "title": title, "why": why, "inputs": inputs, "got": got, + "expected": expected, "hand": hand, "rows": rows, "ok": ok, "notes": notes, + "kind": "engine"} + + +def _process_case(cid: str, title: str, why: str, inputs: dict, checks: list[dict], + hand: str, *, notes: str = "") -> dict: + """مورد فرایندی: چند ادعا، هر کدام با شاهد روشن.""" + ok = all(c["ok"] for c in checks) + return {"id": cid, "title": title, "why": why, "inputs": inputs, + "got": {c["key"]: c["got"] for c in checks}, + "expected": {c["key"]: c["expected"] for c in checks}, + "rows": checks, "hand": hand, "ok": ok, "notes": notes, "kind": "process"} + + +# ---------------------------------------------------------------- موردهای موتور +def case_carry(ctx) -> dict: + e = engine() + spot, future, days, hurdle, fee = 1000.0, 1145.0, 90.0, 0.39, 0.0012 + res = e.basis_opportunity(spot, future, days, hurdle, fee_buy=fee, fee_sell=fee) + net = future * (1 - fee) - spot * (1 + fee) # حساب دستی + base = spot * (1 + fee) + annual = ((1 + net / base) ** (365.0 / days) - 1) * 100 + return _case( + "carry-90d", "خرید نقدی و فروش آتی، ۹۰ روز", + "همان معاملهٔ پایهٔ بازار: کالا را نقد می‌خری و آتی‌اش را می‌فروشی؛ فقط اختلاف قیمت و کارمزد می‌ماند.", + {"قیمت نقدی": spot, "قیمت آتی": future, "روز تا سررسید": days, + "نرخ سد": hurdle, "کارمزد هر سمت": fee}, + {"annualized_pct": res["annualized_pct"], "net_gain_per_unit": res["net_gain_per_unit"], + "period_return_pct": res["period_return_pct"], "go": res["go"]}, + {"annualized_pct": round(annual, 3), "net_gain_per_unit": round(net, 2), + "period_return_pct": round(net / base * 100, 3), "go": True}, + hand=f"سود هر واحد = {future}×(۱−{fee}) − {spot}×(۱+{fee}) = {net:,.2f} ریال · " + f"سرمایهٔ درگیر = {spot}×{1 + fee} = {base:,.2f} · " + f"بازده دوره = {net / base * 100:.3f}٪ · سالانه = (۱+بازده دوره)^(۳۶۵/۹۰) − ۱ = {annual:.2f}٪", + notes="نرخ سد ۳۹٪ است (نرخ سود مؤثر بازار)؛ ۷۱٪ یعنی این معامله از سد رد می‌شود.") + + +def case_carry_hurdle(ctx) -> dict: + e = engine() + args = dict(spot=1000.0, future=1145.0, days=90.0, fee_buy=0.0012, fee_sell=0.0012) + low = e.basis_opportunity(hurdle=0.39, **args) + high = e.basis_opportunity(hurdle=0.72, **args) + annual = low["annualized_pct"] + return _case( + "carry-hurdle", "یک فرصت، دو نرخ سد", + "نشان می‌دهد تصمیم به عدد بسته است نه سلیقه: با سد ۳۹٪ همین معامله باز است، با سد ۷۲٪ بسته می‌شود.", + {"فرصت": f"بازده سالانهٔ {annual}٪", "سد اول": 0.39, "سد دوم": 0.72, + "کف حاشیهٔ ایستگاه": "۳ واحد درصد"}, + {"go_hurdle_39": low["go"], "go_hurdle_72": high["go"], + "edge_pp_39": low["edge_pp"], "edge_pp_72": high["edge_pp"]}, + {"go_hurdle_39": True, "go_hurdle_72": False, + "edge_pp_39": round(annual - 39.0, 3), "edge_pp_72": round(annual - 72.0, 3)}, + hand=f"حاشیه = بازده سالانه − سد · با سد ۳۹٪: {annual}−۳۹ = {annual - 39:.2f} واحد درصد (باز) · " + f"با سد ۷۲٪: {annual}−۷۲ = {annual - 72:.2f} واحد درصد (زیر کف ۳ → بسته)", + notes="قاعدهٔ ایستگاه: راهبرد آربیتراژی به کف ۳ واحد درصد نیاز دارد؛ پس سد ۷۲٪ آن را می‌بندد.") + + +def case_fees_kill_edge(ctx) -> dict: + e = engine() + spot, future, days, hurdle = 1000.0, 1100.0, 90.0, 0.39 + + def hand(fee: float) -> tuple[float, float]: + net = future * (1 - fee) - spot * (1 + fee) + base = spot * (1 + fee) + return net, ((1 + net / base) ** (365.0 / days) - 1) * 100 + + cheap = e.basis_opportunity(spot=spot, future=future, days=days, hurdle=hurdle, + fee_buy=0.0012, fee_sell=0.0012) + dear = e.basis_opportunity(spot=spot, future=future, days=days, hurdle=hurdle, + fee_buy=0.02, fee_sell=0.02) + cheap_annual, dear_annual = hand(0.0012)[1], hand(0.02)[1] + return _case( + "fees-kill-edge", "کارمزد گران، فرصت را می‌کُشد", + "لحظهٔ اعتماد: قیمت‌ها تکان نمی‌خورد، فقط کارمزد از ۰٫۱۲٪ به ۲٪ می‌رود و حکم برنامه عوض می‌شود.", + {"قیمت نقدی": spot, "قیمت آتی": future, "روز": days, "کارمزد ارزان": 0.0012, "کارمزد گران": 0.02}, + {"annualized_cheap_pct": cheap["annualized_pct"], "annualized_dear_pct": dear["annualized_pct"], + "go_cheap": cheap["go"], "go_dear": dear["go"]}, + {"annualized_cheap_pct": round(cheap_annual, 3), "annualized_dear_pct": round(dear_annual, 3), + "go_cheap": True, "go_dear": False}, + hand=f"ارزان: ({future}×۰٫۹۹۸۸ − {spot}×۱٫۰۰۱۲)/۱۰۰۱٫۲ = ۹٫۷۴٪ در ۹۰ روز → سالانه {cheap_annual:.2f}٪ · " + f"گران: ({future}×۰٫۹۸ − {spot}×۱٫۰۲)/۱۰۲۰ = ۵٫۶۹٪ در ۹۰ روز → سالانه {dear_annual:.2f}٪ " + f"(زیر سد ۳۹٪ → رد)", + notes="این مورد ثابت می‌کند برنامه به کارمزد حساس است؛ اگر کسی کارمزد را دستی کم بگذارد، کارنامه او را لو می‌دهد.") + + +def case_tabei(ctx) -> dict: + e = engine() + stock, put, strike, days = 10000.0, 1000.0, 12000.0, 180.0 + res = e.tabei_min_yield(stock, put, strike, days) + buy_total = stock * (1 + e.FEE_STOCK_BUY) + put + sell_net = strike * (1 - e.FEE_STOCK_SELL) + annual = ((sell_net / buy_total) ** (365.0 / days) - 1) * 100 + return _case( + "tabei-180d", "اوراق تبعی: کمینهٔ بازده تضمین‌شده", + "اینجا «تضمین» به معنای واقعی است: با خرید سهم + پوت تبعی، کمینهٔ بازده تا سررسید قفل می‌شود.", + {"قیمت سهم": stock, "قیمت پوت": put, "قیمت اعمال": strike, "روز": days, + "کارمزد خرید سهم": e.FEE_STOCK_BUY, "کارمزد فروش سهم": e.FEE_STOCK_SELL}, + {"annualized_pct": res["annualized_pct"], "period_return_pct": res["period_return_pct"], + "cost_basis": res["cost_basis"], "guaranteed_proceeds": res["guaranteed_proceeds"], "go": res["go"]}, + {"annualized_pct": round(annual, 3), "period_return_pct": round((sell_net - buy_total) / buy_total * 100, 3), + "cost_basis": round(buy_total, 2), "guaranteed_proceeds": round(sell_net, 2), "go": True}, + hand=f"بهای تمام‌شده = {stock}×۱٫۰۰۴۶۴ + {put} = {buy_total:,.1f} · " + f"دریافتی قفل‌شده = {strike}×۰٫۹۹۰۳۶ = {sell_net:,.1f} · " + f"بازده = {((sell_net / buy_total) - 1) * 100:.2f}٪ در ۱۸۰ روز → سالانه {annual:.2f}٪") + + +def case_covered_call(ctx) -> dict: + e = engine() + spot, strike, premium, days = 5000.0, 6000.0, 180.0, 60.0 + res = e.covered_call(spot, strike, premium, days) + basis = spot * (1 + e.FEE_STOCK_BUY) + prem_net = premium * (1 - e.FEE_OPTION_TRADE) + prem_annual = ((1 + prem_net / basis) ** (365.0 / days) - 1) * 100 + return _case( + "covered-call-60d", "فروش اختیار خرید پوشش‌داده‌شده", + "برنامه فقط «درآمد پرمیوم» را تصمیم می‌گیرد و سقف سود را جدا نشان می‌دهد؛ دو عدد را قاطی نمی‌کند.", + {"قیمت سهم": spot, "قیمت اعمال": strike, "پرمیوم دریافتی": premium, "روز": days}, + {"annualized_pct": res["annualized_pct"], "premium_annualized_pct": res["premium_annualized_pct"], + "upside_capped_at_pct": res["upside_capped_at_pct"], "premium_yield_pct": res["premium_yield_pct"], + "go": res["go"]}, + {"annualized_pct": round(prem_annual, 3), "premium_annualized_pct": round(prem_annual, 3), + "upside_capped_at_pct": round((strike - spot) / spot * 100, 2), + "premium_yield_pct": round(premium / spot * 100, 3), "go": True}, + hand=f"پرمیوم خالص = {premium}×۰٫۹۹۸۹۷ = {prem_net:,.2f} · پایه = {spot}×۱٫۰۰۴۶۴ = {basis:,.1f} · " + f"بازده ۶۰ روزه = {prem_net / basis * 100:.3f}٪ → سالانه {prem_annual:.2f}٪ · " + f"سقف سود = ({strike}−{spot})/{spot} = ۲۰٪ (جدا شمرده می‌شود)") + + +def case_parity(ctx) -> dict: + e = engine() + call, put, spot, strike, days, rate = 900.0, 350.0, 5000.0, 4800.0, 45.0, 0.30 + res = e.put_call_parity(call, put, spot, strike, days, rate) + import math + t = days / 365.0 + right = spot - strike * math.exp(-rate * t) + gap = (call - put) - right + costs = (call + put + spot) * e.FEE_OPTION_TRADE + edge = gap - costs + basis = spot + put - call + annual = ((1 + edge / basis) ** (1 / t) - 1) * 100 if basis > 0 else None + return _case( + "parity-gap", "انحراف از تساوی پوت-کال", + "رابطهٔ ریاضی که همیشه باید برقرار باشد؛ هر انحرافش یک معاملهٔ بدون جهت بازار است — به‌شرط اینکه از کارمزد بزرگ‌تر باشد.", + {"کال": call, "پوت": put, "قیمت سهم": spot, "قیمت اعمال": strike, "روز": days, "نرخ بی‌ریسک": rate}, + {"gap": res["gap"], "conversion_edge_per_unit": res["conversion_edge_per_unit"], + "annualized_pct": res["annualized_pct"], "direction": res["direction"], "go": res["go"]}, + {"gap": round(gap, 2), "conversion_edge_per_unit": round(edge, 2), + "annualized_pct": round(annual, 3) if annual else None, "direction": "conversion", "go": True}, + hand=f"سمت چپ = {call}−{put} = {call - put:,.0f} · سمت راست = {spot} − {strike}×e^(−۰٫۳×{t:.4f}) = {right:,.2f} · " + f"شکاف = {gap:,.2f} · کارمزدها = {costs:,.2f} · سود هر واحد = {edge:,.2f} → سالانه {annual:.2f}٪") + + +def case_box(ctx) -> dict: + e = engine() + res = e.box_spread(600.0, 150.0, 280.0, 250.0, 4000.0, 4500.0, 120.0) + debit = (600.0 + 250.0) - (150.0 + 280.0) + payoff = 500.0 + fees = (600.0 + 150.0 + 280.0 + 250.0) * e.FEE_OPTION_TRADE + net = payoff - debit - fees + annual = ((1 + net / debit) ** (365.0 / 120.0) - 1) * 100 + return _case( + "box-spread", "باکس اسپرد: سود بی‌جهت‌بازار", + "چهار قرارداد که هم‌زمان بسته می‌شوند و نتیجه‌اش عددی ثابت است؛ اگر بدهی اولیه کمتر از فاصلهٔ قیمت اعمال باشد، سود قطعی است.", + {"کال/پوت اعمال ۴۰۰۰": "۶۰۰ / ۱۵۰", "کال/پوت اعمال ۴۵۰۰": "۲۸۰ / ۲۵۰", "روز": 120.0}, + {"debit": res["debit"], "payoff": res["payoff"], "fees_estimate": res["fees_estimate"], + "net_profit": res["net_profit"], "annualized_pct": res["annualized_pct"], "go": res["go"]}, + {"debit": round(debit, 2), "payoff": payoff, "fees_estimate": round(fees, 2), + "net_profit": round(net, 2), "annualized_pct": round(annual, 3), "go": True}, + hand=f"بدهی = (۶۰۰+۲۵۰) − (۱۵۰+۲۸۰) = {debit:,.0f} · دریافتی قطعی = ۴۵۰۰−۴۰۰۰ = {payoff:,.0f} · " + f"کارمزد = ۱۲۸۰×۰٫۰۰۱۰۳ = {fees:,.2f} · سود = {net:,.2f} → سالانه {annual:.2f}٪") + + +def case_liquidity_penalty(ctx) -> dict: + e = engine() + clean = {"annualized_pct": 60.0, "liquidity_contracts_per_day": 100, "spread_pct": 0.01, "leverage_used": 1} + dirty = {"annualized_pct": 60.0, "liquidity_contracts_per_day": 5, "spread_pct": 0.06, "leverage_used": 3} + s1 = e.score(clean, hurdle=0.39) + s2 = e.score(dirty, hurdle=0.39) + return _case( + "liquidity-penalty", "جریمهٔ نقدشوندگی و اسپرد", + "بازده یکسان، دو بازار متفاوت: بازار کم‌معامله و پراسپرد جریمه می‌خورد تا برنامه فرصت توخالی معرفی نکند.", + {"بازده سالانه": 60.0, "نقدشوندگی خوب/بد": "۱۰۰ / ۵ قرارداد در روز", + "اسپرد خوب/بد": 0.01, "اهرم خوب/بد": 1}, + {"score_clean": s1, "score_dirty": s2, "penalty_pp": round(s1 - s2, 3)}, + {"score_clean": 21.0, "score_dirty": 8.0, "penalty_pp": 13.0}, + hand="امتیاز = (بازده − سد)×۱۰۰ − جریمه‌ها · تمیز: (۰٫۶−۰٫۳۹)×۱۰۰ = ۲۱ · " + "بد: ۲۱ − (۵+۵+۳) = ۸ (نقدشوندگی ۵، اسپرد ۵، اهرم ۳)") + + +def case_position_size(ctx) -> dict: + e = engine() + capital, margin = 20_000_000_000.0, 1_850_000.0 + res = e.position_size(capital, margin, risk_pct=0.20) + budget = capital * 0.20 + n = int(budget // margin) + return _case( + "position-size", "اندازهٔ موقعیت: چند قرارداد؟", + "برنامه هرگز بیشتر از ۲۰٪ سرمایه را در وجه تضمین قفل نمی‌کند؛ این عدد را می‌شود با یک تقسیم ساده چک کرد.", + {"سرمایه": capital, "وجه تضمین هر قرارداد": margin, "سقف ریسک": 0.20}, + {"contracts": res["contracts"], "margin_locked": res["margin_locked"], "free_cash": res["free_cash"]}, + {"contracts": n, "margin_locked": round(n * margin, 2), "free_cash": round(capital - n * margin, 2)}, + hand=f"بودجه = {capital:,.0f}×۰٫۲۰ = {budget:,.0f} · تعداد = {budget:,.0f} ÷ {margin:,.0f} = {n} قرارداد · " + f"قفل‌شده = {n:,}×{margin:,.0f} = {n * margin:,.0f} ریال") + + +def case_implausible(ctx) -> dict: + import backtest as bt + rules = {"min_edge_arbitrage_pct": 3.0, "min_edge_leveraged_pct": 5.0, "max_plausible_arb_pct": 250.0, + "max_plausible_lev_pct": 400.0, "min_liquidity_contracts_per_day": 20, "max_spread_pct": 0.03} + row = {"date": "۱۴۰۵-۰۶-۰۱", "symbol": "آزمون", "kind": "basis", "spot": 1000.0, "future": 10000.0, + "days": 30.0, "margin_per_contract": 1_000_000.0} + d = bt.decide_row(row, rules) + absurd = float(d.expected_annualized_pct or 0) / 250.0 # چند برابر سقف باورپذیری؟ + return _process_case( + "implausible-data", "دادهٔ اشتباه رد می‌شود", + "اگر کسی قیمت آتی را جابه‌جا وارد کند (ده برابر نقدی)، برنامه سود رؤیایی نمی‌سازد؛ آن را مشکوک اعلام می‌کند.", + {"قیمت نقدی": 1000.0, "قیمت آتی (اشتباه)": 10000.0, "روز": 30.0, "سقف باورپذیری": 250.0}, + [{"key": "decision_taken", "got": bool(d.taken), "expected": False, "ok": d.taken is False}, + {"key": "reason_mentions_ceiling", "got": "سقف باورپذیری" in d.reason, "expected": True, + "ok": "سقف باورپذیری" in d.reason}, + {"key": "annualized_x_ceiling", "got": f"{absurd:,.0f}× سقف", + "expected": "بزرگ‌تر از ۱× سقف", "ok": absurd > 1}], + hand="بازده بیرون‌آمده از این ورودی میلیون‌ها برابر سقف باورپذیری (۲۵۰٪ برای آربیتراژ) است؛ " + "دروازه همین بزرگی را نشانهٔ خطای ورودی می‌داند و تصمیم را می‌بندد؛ پس عدد به‌عنوان «سود» روی میز نمی‌آید.", + notes="عدد سالانه در این مورد عمداً غول‌آسا است؛ خودش شاهدِ خرابی داده است، نه سود.") + + +def case_no_look_ahead(ctx) -> dict: + import backtest as bt + rules = {"min_edge_arbitrage_pct": 3.0, "min_edge_leveraged_pct": 5.0, "max_plausible_arb_pct": 250.0, + "max_plausible_lev_pct": 400.0, "min_liquidity_contracts_per_day": 20, "max_spread_pct": 0.03} + rows, problems = bt.load_history(BASE / "demo" / "history-demo.csv") + sample = rows[:6] + first = [bt.decide_row(r, rules) for r in sample] + tampered = [] + for r in sample: + r2 = dict(r) + if isinstance(r2.get("realized_annualized_pct"), (int, float)): + r2["realized_annualized_pct"] = float(r2["realized_annualized_pct"]) * 5 + tampered.append(bt.decide_row(r2, rules)) + same = all((a.taken, a.reason, a.expected_annualized_pct) == (b.taken, b.reason, b.expected_annualized_pct) + for a, b in zip(first, tampered)) + return _process_case( + "no-look-ahead", "بدون آینده‌نگری", + "ستون «نتیجهٔ واقعی گذشته» پنج برابر می‌شود؛ اگر تصمیم‌های برنامه تکان بخورد، یعنی برنامه دارد از آینده تقلب می‌کند.", + {"ردیف‌های آزمون": len(sample), "ستون دست‌کاری‌شده": "realized_annualized_pct", "ضریب تغییر": 5}, + [{"key": "decisions_identical", "got": bool(same), "expected": True, "ok": bool(same)}, + {"key": "rows_loaded", "got": len(rows), "expected": len(rows), "ok": len(rows) > 0}, + {"key": "problems", "got": len(problems), "expected": len(problems), "ok": True}], + hand="موتور در گام تصمیم، هر کلیدی که با realized شروع شود را کنار می‌گذارد؛ پس تغییر آن ستون نباید هیچ تصمیمی را عوض کند.") + + +def case_tamper_chain(ctx) -> dict: + import live_trial as trial + with tempfile.TemporaryDirectory() as tmp: + db = Path(tmp) / "trial.sqlite3" + t = trial.Trial(db) + t.record([{"symbol": "الف", "kind": "basis", "decision": "recorded", "expected": 40.0}, + {"symbol": "ب", "kind": "tabei", "decision": "recorded", "expected": 22.0}], + source_label="آزمون", mode="sim", dedupe_hours=0) + ok_before, why_before = t.verify_chain() + con = sqlite3.connect(db) + con.execute("UPDATE entries SET expected = 999 WHERE id = 1") + con.commit() + con.close() + ok_after, why_after = t.verify_chain() + return _process_case( + "tamper-chain", "زنجیرهٔ هش: دست‌کاری لو می‌رود", + "کسی عدد دفتر را در پایگاه‌داده عوض می‌کند؛ بررسی زنجیره باید همان لحظه سرخ شود. این یعنی سابقهٔ شما قابل جعل نیست.", + {"ردیف‌های ثبت‌شده": 2, "تغییر انجام‌شده": "انتظار ردیف ۱ → ۹۹۹"}, + [{"key": "chain_ok_before", "got": bool(ok_before), "expected": True, "ok": bool(ok_before)}, + {"key": "chain_ok_after_tamper", "got": bool(ok_after), "expected": False, "ok": ok_after is False}, + {"key": "message_names_problem", "got": why_after[:60], "expected": "شکسته/ناسازگار", + "ok": any(w in why_after for w in ("شکسته", "ناساز", "دست‌کاری", "نامعتبر"))}], + hand="هر ردیف هش sha256 از (هش ردیف قبل + محتوای خودش) دارد؛ تغییر محتوا بدون بازنویسی همهٔ ردیف‌های بعدی، زنجیره را می‌شکند.") + + +def case_real_day(ctx) -> dict: + import datafeed as df + import daily_trial as dt + with tempfile.TemporaryDirectory() as tmp: + tmpdir = Path(tmp) + fake = tmpdir / "market-demo.json" + fake.write_text(json.dumps({"rows": []}, ensure_ascii=False), encoding="utf-8") + confirmed = tmpdir / "snapshot-manual.json" + confirmed.write_text(json.dumps({"rows": [], "source": df.MANUAL_SOURCE}, ensure_ascii=False), + encoding="utf-8") + unconfirmed = tmpdir / "snapshot-plain.json" + unconfirmed.write_text(json.dumps({"rows": []}, ensure_ascii=False), encoding="utf-8") + checks = [ + {"key": "demo_path_is_synthetic", "got": bool(dt.path_is_synthetic(fake)), "expected": True, + "ok": dt.path_is_synthetic(fake) is True}, + {"key": "manual_snapshot_confirmed", "got": bool(df.snapshot_confirmed(confirmed)), "expected": True, + "ok": df.snapshot_confirmed(confirmed) is True}, + {"key": "plain_file_not_confirmed", "got": bool(df.snapshot_confirmed(unconfirmed)), "expected": False, + "ok": df.snapshot_confirmed(unconfirmed) is False}, + {"key": "absent_file_not_confirmed", "got": bool(df.snapshot_confirmed(tmpdir / "nope.json")), + "expected": False, "ok": df.snapshot_confirmed(tmpdir / "nope.json") is False}, + ] + return _process_case( + "real-day-gate", "روز «واقعی» جعل‌شدنی نیست", + "برای اینکه یک روز در کارنامه «واقعی» شمرده شود، پرونده باید هم از مسیر نمونه نباشد و هم شما تأییدش کرده باشید.", + {"پروندهٔ نمونه": "market-demo.json", "پروندهٔ تأییدشده": "source = manual-broker", "پروندهٔ بی‌برچسب": "بدون source"}, + checks, + hand="دو شرط با هم: نام/مسیر نمونه نباشد و برچسب منبع، «برداشته‌شده از سامانهٔ کارگزاری» باشد.") + + +def case_live_failure_honest(ctx) -> dict: + import datafeed as df + cfg = dict(df.DEFAULT_LIVE_CONFIG) + cfg.update({"url_template": "http://127.0.0.1:9/quote?symbol={symbol}", "json_path": "last", + "timeout_seconds": 2, "retries": 0, "cache_seconds": 0}) + buf = io.StringIO() + with contextlib.redirect_stdout(buf): # پیام‌های موتور نباید خروجی JSON را آلوده کند + snap = df.build_snapshot("live", file_path=DESK_DIR / "market-demo.json", live_cfg=cfg, + allow_network=True) + engine_lines = [ln for ln in buf.getvalue().strip().splitlines() if ln.strip()] + says_failed = any("نیامد" in m or "نشد" in m for m in snap.messages) + return _process_case( + "live-failure-honest", "شکست دادهٔ زنده، بی‌سروصدا نمی‌ماند", + "سرویس جواب نمی‌دهد؛ برنامه نباید عدد ساختگی جای قیمت زنده بگذارد. باید صریح بگوید «نیامد» و تازگی را نامعلوم بگذارد.", + {"نشانی آزمایشی": "http://127.0.0.1:9/quote (عمداً بسته)", "حالت": "live"}, + [{"key": "status", "got": snap.status, "expected": "failed", "ok": snap.status == "failed"}, + {"key": "freshness_unknown", "got": snap.freshness_label, "expected": "نامعلوم", + "ok": snap.freshness_label == "نامعلوم"}, + {"key": "says_not_came", "got": says_failed, "expected": True, "ok": says_failed}, + {"key": "live_prices_empty", "got": len(snap.live_prices), "expected": 0, + "ok": len(snap.live_prices) == 0}, + {"key": "engine_said_why", "got": engine_lines[0] if engine_lines else "—", + "expected": "پیام دلیل برای هر نماد", "ok": bool(engine_lines)}], + hand="قاعده: هیچ عددی بدون منبعِ خوانده‌شده روی میز نمی‌آید. شکست در «پیام‌ها» می‌نشیند و وضعیت را failed می‌کند.") + + +def case_determinism(ctx) -> dict: + e = engine() + args = dict(spot=1000.0, future=1145.0, days=90.0, hurdle=0.39, fee_buy=0.0012, fee_sell=0.0012) + a = json.dumps(e.basis_opportunity(**args), sort_keys=True, ensure_ascii=False) + b = json.dumps(e.basis_opportunity(**args), sort_keys=True, ensure_ascii=False) + t1 = {"annualized_pct": 60.0, "liquidity_contracts_per_day": 10, "spread_pct": 0.01, "leverage_used": 3} + s1 = e.score(t1, hurdle=0.39) + s2 = e.score(dict(t1), hurdle=0.39) + return _process_case( + "determinism", "تکرارپذیری: یک ورودی، یک جواب", + "دو بار اجرا با ورودی یکسان باید بیت‌به‌بیت یک جواب بدهد. در مسیر تصمیم هیچ مدل زبانی و هیچ تصادفی نیست.", + {"ورودی": "مورد carry-90d و یک امتیازدهی نمونه", "تعداد تکرار": 2}, + [{"key": "engine_output_identical", "got": a == b, "expected": True, "ok": a == b}, + {"key": "score_identical", "got": s1 == s2, "expected": True, "ok": s1 == s2}, + {"key": "score_value", "got": s1, "expected": 13.0, "ok": abs(s1 - 13.0) < 0.02}], + hand="امتیاز = (۰٫۶−۰٫۳۹)×۱۰۰ − ۸ = ۱۳ (نقدشوندگی ۵، اهرم ۳)؛ همان عدد در هر اجرا.") + + +CASES = [case_carry, case_carry_hurdle, case_fees_kill_edge, case_tabei, case_covered_call, + case_parity, case_box, case_liquidity_penalty, case_position_size, case_implausible, + case_no_look_ahead, case_tamper_chain, case_real_day, case_live_failure_honest, + case_determinism] + + +def run_all(*, only: list[str] | None = None, cases: list | None = None, quiet: bool = False) -> dict: + """همهٔ موردها را اجرا می‌کند و کارنامهٔ ماشین‌خوان برمی‌گرداند.""" + started = time.time() + chosen = cases or CASES + results: list[dict] = [] + for fn in chosen: + r = fn({}) + if only and r["id"] not in only: + continue + results.append(r) + passed = len([1 for r in results if r["ok"]]) + return { + "version": VERSION, + "ran_at": datetime.now(timezone.utc).isoformat(timespec="seconds"), + "duration_ms": int((time.time() - started) * 1000), + "engine": engine_fingerprint(), + "python": sys.version.split()[0], + "summary": {"total": len(results), "passed": passed, "failed": len(results) - passed, + "ok": passed == len(results) and bool(results)}, + "cases": results, + } + + +# ---------------------------------------------------------------- نمایش +def console(result: dict) -> None: + s = result["summary"] + print(f"آزمون ایستگاه — نسخه {result['version']} · موتور {result['engine']['version']} " + f"(sha256:{result['engine']['sha256']}) · {result['ran_at']}") + print(f"نتیجه: {s['passed']}/{s['total']} سبز · زمان {result['duration_ms']} میلی‌ثانیه") + print("-" * 78) + for c in result["cases"]: + mark = "سبز" if c["ok"] else "سرخ" + print(f"[{mark}] {c['id']} — {c['title']}") + for row in c["rows"]: + flag = "✓" if row["ok"] else "✗" + print(f" {flag} {row['key']}: برنامه={row['got']!r} · مستقل={row['expected']!r}") + print("-" * 78) + print("برگهٔ آزمون سرمایه‌گذار و کارنامهٔ HTML در پوشهٔ data ساخته شد." if s["ok"] else "کارنامه سرخ است؛ پیش از نمایش به سرمایه‌گذار حلش کنید.") + + +def table_html(result: dict) -> str: + s = result["summary"] + badge = f'{"همه سبز" if s["ok"] else "سرخ"}' + kpis = (f'
    ' + f'
    {s["passed"]}/{s["total"]}مورد سبز
    ' + f'
    {s["failed"]}مورد سرخ
    ' + f'
    {result["duration_ms"]}میلی‌ثانیه
    ' + f'
    {rk.esc(result["engine"]["version"])}نسخهٔ موتور ریاضی
    ' + f'
    {badge}وضعیت کلی
    ') + rows = [] + for c in result["cases"]: + cls = "pass" if c["ok"] else "fail" + detail = " · ".join(f'{rk.esc(r["key"])}={rk.esc(r["got"])}' for r in c["rows"]) + rows.append(f'{rk.esc(c["id"])}
    {rk.esc(c["title"])}' + f'{rk.esc(c["why"])}{detail}' + f'{"سبز" if c["ok"] else "سرخ"}') + table = ('' + '' + + "".join(rows) + "
    موردچه چیزی را ثابت می‌کندخروجی برنامهوضعیت
    ") + return kpis + table + + +def build_report(result: dict, path: Path | None = None) -> Path: + out = Path(path or (DATA / "selftest-report.html")) + out.parent.mkdir(parents=True, exist_ok=True) + body = [ + '
    این کارنامه چه چیزی را ثابت می‌کند و چه چیزی را نه. ' + 'ثابت می‌کند حساب‌وکتاب برنامه با حساب دستی یکی است، زنجیرهٔ دفتر جعل‌ناپذیر است، ' + 'و برنامه در نبود داده، عدد جعل نمی‌کند. ثابت نمی‌کند که این معامله‌ها سود می‌دهند؛ ' + 'سودآوری به قیمت اجرا، نقدشوندگی و بازار واقعی بسته است.
    ', + rk.digest_line("اثر انگشت موتور ریاضی (sha256، ۱۶ رقم اول)", result["engine"]["sha256"]), + table_html(result), + "

    جزئیات هر مورد

    ", + ] + for c in result["cases"]: + inputs = " · ".join(f"{rk.esc(k)}: {rk.esc(v)}" for k, v in c["inputs"].items()) + rows = "".join( + f'{rk.esc(r["key"])}{rk.esc(r["got"])}' + f'{rk.esc(r["expected"])}{"✓" if r["ok"] else "✗"}' + for r in c["rows"]) + body.append( + f'

    {rk.esc(c["id"])} — {rk.esc(c["title"])} {"✅" if c["ok"] else "❌"}

    ' + f'

    {rk.esc(c["why"])}

    ' + f'

    ورودی‌ها: {inputs}

    ' + f'' + f'{rows}
    کمیتخروجی برنامهحساب دستی مستقلتطابق
    ' + f'

    راه چک با ماشین‌حساب: {rk.esc(c["hand"])}

    ' + + (f'

    {rk.esc(c["notes"])}

    ' if c.get("notes") else "")) + out.write_text(rk.page("کارنامهٔ آزمون ایستگاه (۱۰ دقیقه)", "".join(body), + subtitle=f"{result['summary']['passed']} از {result['summary']['total']} مورد سبز · " + f"اجرا در {result['ran_at']}"), encoding="utf-8") + return out + + +def build_exam_sheet(result: dict, path: Path | None = None) -> Path: + """برگهٔ آزمون برای سرمایه‌گذار: اول حدس خودش، بعد پاسخ برنامه و راه چک دستی.""" + out = Path(path or (DATA / "exam-sheet.html")) + out.parent.mkdir(parents=True, exist_ok=True) + body = [ + '
    روش استفاده: این برگه را چاپ کنید یا روی صفحه بدهید. ' + 'برای هر سؤال اول حدس خودتان را بنویسید، بعد صفحه را برگردانید و پاسخ برنامه و ' + 'راه چک با ماشین‌حساب را ببینید. اگر پاسخ‌ها را با ماشین‌حساب تأیید کردید، ' + 'یعنی خودتان مستقل راستی‌آزمایی کرده‌اید — همان چیزی که این برنامه ادعا می‌کند.
    ', + "

    بخش یک: سؤال‌ها (پاسخ‌ها در صفحهٔ بعد)

    ", + ] + for i, c in enumerate(result["cases"], start=1): + inputs = " · ".join(f"{rk.esc(k)}: {rk.esc(v)}" for k, v in c["inputs"].items()) + body.append(f'

    سؤال {i}: {rk.esc(c["title"])}

    {rk.esc(c["why"])}

    ' + f'

    ورودی‌ها — {inputs}

    ' + '

    حدس شما:

    ') + body.append('

    بخش دو: پاسخ‌ها و راه چک دستی

    ') + for i, c in enumerate(result["cases"], start=1): + got = " · ".join(f"{rk.esc(r['key'])} = {rk.esc(r['got'])}" for r in c["rows"]) + body.append(f'

    پاسخ {i}: {rk.esc(c["title"])}

    ' + f'

    {got}

    ' + f'

    چک با ماشین‌حساب: {rk.esc(c["hand"])}

    ') + out.write_text(rk.page("برگهٔ آزمون سرمایه‌گذار", "".join(body), + subtitle=f"{len(result['cases'])} سؤال · پاسخ‌ها از همان موتوری است که در تصمیم زنده کار می‌کند"), + encoding="utf-8") + return out + + +# ---------------------------------------------------------------- خط فرمان +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description=f"آزمون ۱۰ دقیقه‌ای ایستگاه — نسخه {VERSION}") + ap.add_argument("--only", help="فقط موردهای فهرست‌شده، جداشده با ویرگول") + ap.add_argument("--json", action="store_true", help="خروجی ماشین‌خوان") + ap.add_argument("--list", action="store_true", help="فهرست موردها") + ap.add_argument("--no-report", action="store_true", help="فایل HTML نساز") + ap.add_argument("--version", action="version", version=VERSION) + args = ap.parse_args(argv) + + only = [x.strip() for x in (args.only or "").replace("،", ",").split(",") if x.strip()] + if args.list: + for fn in CASES: + r = fn({}) + print(f"{r['id']:>22} · {r['title']}") + return 0 + + result = run_all(only=only or None) + if args.json: + print(json.dumps(result, ensure_ascii=False, indent=2)) + else: + console(result) + if not args.no_report: + print("کارنامه:", build_report(result)) + print("برگهٔ آزمون:", build_exam_sheet(result)) + return 0 if result["summary"]["ok"] else 1 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/station/signal_judge.py b/station/signal_judge.py new file mode 100644 index 0000000000000000000000000000000000000000..e6c179b4ce72938496032d5e863c2210c20196bc --- /dev/null +++ b/station/signal_judge.py @@ -0,0 +1,484 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""داوری سیگنال بیرونی — «سیگنال نرم‌افزار فعلی‌تان را بیاورید؛ این‌جا می‌سنجیمش». + +مسئله: ابزارهای فارسی بازار (دیده‌بان‌ها، ماشین‌حساب‌های بلک‌شولز، فیلترها) سیگنال می‌سازند؛ +ولی هیچ‌کدام نمی‌گویند آن سیگنال **با کارمزد واقعی، نقدشوندگی، نرخ سد و وجه تضمین** می‌مانَد یا +می‌افتد. این ابزار همان یک کار را با عدد و دلیل انجام می‌دهد و در پایان، «فاصله تا مارجین‌کال» +هر موقعیت را هم می‌گوید. + +نمونه: + python signal_judge.py --kind basis --params '{"spot":20000,"future":22800,"days":50}' --json + python signal_judge.py --file my-signal.json --hurdle 0.39 --capital 100000000 + python signal_judge.py --kind covered --params '{"spot":7000,"strike":7400,"premium":220,"days":30}' + python signal_judge.py --kind basis --params '{"spot":20000,"future":22800,"days":50}' --sheet + +مفروضات مارجین (اعلامی، نه حدسی): حد نگهداری = ۷۰٪ وجه تضمین اولیه (رویهٔ بورس ایران) و +وجه تضمین اولیهٔ اختیار فروش ≈ ۲۰٪ ارزش قرارداد. هر دو را می‌توانید با عدد کارگزاری خودتان +عوض کنید؛ اگر کارگزاری عدد دیگری بدهد، همان را بگذارید. +""" +from __future__ import annotations + +import argparse +import hashlib +import json +import sys +from datetime import datetime, timezone +from pathlib import Path + +VERSION = "0.1.0" +BASE = Path(__file__).resolve().parent +DATA = BASE / "data" +TOOLS_DIR = (BASE.parent / "tools").resolve() +SHEET_HTML = DATA / "signal-verdict.html" +SHEET_MD = DATA / "signal-verdict.md" +CREDIT = ("تهیه‌کننده: Masoud Mojarabian · https://www.instagram.com/Mojarabian.Art/ · " + "tel:+989126630554 · https://t.me/Mojarabian") +HURDLE_DEFAULT = 0.39 # نرخ سد پیش‌فرض (بازده مؤثر صندوق درآمد ثابت، شهریور ۱۴۰۵) +MAINTENANCE_DEFAULT = 0.70 # حد نگهداری وجه تضمین (رویهٔ بورس ایران) +INITIAL_RATIO_DEFAULT = 0.20 # وجه تضمین اولیهٔ اختیار فروش ≈ ۲۰٪ ارزش قرارداد +LIQUIDITY_FLOOR = 20 # کف قرارداد معامله‌شده در روز +SPREAD_CAP = 0.03 # سقف اسپرد نسبی +PLAUSIBLE_CAP = 5.0 # بیش از ۵۰۰٪ سالانه = مشکوک به دادهٔ اشتباه + +for p in (str(TOOLS_DIR), str((BASE.parent / "desk").resolve())): + if p not in sys.path: + sys.path.insert(0, p) + +KINDS = { + "basis": "خرید نقدی و فروش آتی (کری) ، نرخ‌های لازم: spot, future, days[, storage_annual, spread_pct, liquidity_contracts_per_day]", + "box": "باکس اسپرد ، call_low, put_low, call_high, put_high, strike_low, strike_high, days", + "tabei": "تبعی (تضمین فروش) ، stock_price, put_price, strike, days", + "covered": "پوشش‌داده‌شده ، spot, strike, premium, days", + "parity": "تساوی پوت‌کال ، call, put, spot, strike, days[, rate]", +} + +# کلیدی که برای «نقطهٔ برگشت» جابه‌جا می‌شود: تا کجا بشود و معامله همچنان بماند +KIND_LABELS = {"basis": "خرید نقدی و فروش آتی (کری)", "box": "باکس اسپرد", + "tabei": "تبعی (تضمین فروش)", "covered": "پوشش‌داده‌شده (کاورد کال)", + "parity": "تساوی پوت‌کال"} + +FLIP_KEY = {"basis": "future", "covered": "premium", "tabei": "strike", "box": "call_low", + "parity": "spot"} +FLIP_LABEL = {"basis": "کم‌ترین قیمت آتی که معامله بماند", "covered": "کم‌ترین پرمیوم که معامله بماند", + "tabei": "کم‌ترین قیمت اعمال که معامله بماند", "box": "کم‌ترین قیمت پاها که معامله بماند", + "parity": "قیمتی که فاصله را از هزینه رد می‌کند"} + + +def load_engine(): + import derivatives_scout as scout # noqa: WPS433 + return scout + + +def now_iso() -> str: + return datetime.now(timezone.utc).replace(microsecond=0).isoformat() + + +def fa_num(x, digits: int = 2) -> str: + if x is None: + return "—" + if isinstance(x, float): + out = f"{x:,.{digits}f}" + if digits > 0 and "." in out: + out = out.rstrip("0").rstrip(".") + return out + return f"{x:,}" + + +def fingerprint(payload: dict) -> str: + body = json.dumps(payload, sort_keys=True, ensure_ascii=False, default=str) + return hashlib.sha256(body.encode("utf-8")).hexdigest()[:16] + + +# ---------------------------------------------------------------- هستهٔ داوری +ENGINE_KIND = {"covered": "covered_call"} + + +def _row(kind: str, params: dict) -> dict: + row = dict(params) + row["kind"] = ENGINE_KIND.get(kind, kind) + row.setdefault("liquidity_contracts_per_day", 99) + row.setdefault("spread_pct", 0.0) + row.setdefault("storage_annual", 0.0) + row.setdefault("rate", HURDLE_DEFAULT) + return row + + +def _run(kind: str, params: dict, hurdle: float) -> dict: + scout = load_engine() + res = scout.run_scenario(scout.Scenario(name=KINDS.get(kind, kind), rows=[_row(kind, params)], + hurdle=hurdle))[0] + if "error" in res: + raise ValueError(res["error"]) + return res + + +def hand_annualized(kind: str, params: dict, res: dict) -> dict: + """حساب دستی مستقل از موتور، برای همان عدد تصمیم (روش دوم، قابل بازبینی با ماشین‌حساب).""" + if kind == "basis": + spot, future, days = float(params["spot"]), float(params["future"]), float(params["days"]) + net = future - spot - (spot + future) * 0.0012 # کارمزد صندوق دو طرف + period = net / spot + elif kind == "tabei": + stock, put, strike, days = (float(params["stock_price"]), float(params["put_price"]), + float(params["strike"]), float(params["days"])) + cost = stock * 1.00464 + put * 1.00103 + proceeds = strike * (1 - 0.00964) + period = (proceeds - cost) / cost + elif kind == "covered": + spot, premium, days = float(params["spot"]), float(params["premium"]), float(params["days"]) + period = (premium * (1 - 0.00103)) / (spot * 1.00464) + elif kind == "box": + diff = float(params["strike_high"]) - float(params["strike_low"]) + debit = float(res.get("debit") or 0) + period = (diff - debit - float(res.get("fees_estimate") or 0)) / debit if debit else 0.0 + days = float(params["days"]) + else: + return {"method": "حساب دستی برای این راهبرد تعریف نشده", "period_pct": None, + "annualized_pct": res.get("annualized_pct")} + annual = ((1 + period) ** (365 / days) - 1) * 100 if days else None + return {"method": "سود دوره ÷ سرمایه، بعد (۱+بازده)^(۳۶۵÷روز) − ۱", + "period_pct": round(period * 100, 3), + "annualized_pct": round(annual, 2) if annual is not None else None} + + +def break_even(kind: str, params: dict, hurdle: float, *, lo: float | None = None, + hi: float | None = None, tol: float = 1e-4) -> dict | None: + """نقطهٔ برگشت: مقدار آن ورودی که معامله دقیقاً به نرخ سد می‌رسد.""" + key = FLIP_KEY.get(kind) + if key is None or key not in params: + return None + base = float(params[key]) + if base == 0: + return None + try: + if _run(kind, params, hurdle).get("annualized_pct") is None: + return {"key": key, "label": FLIP_LABEL[kind], "value": None, + "note": ("این ساختار بازده سالانهٔ سد‌محور ندارد؛ تصمیمش ساختاری است " + "(تساوی پوت‌کال با هزینهٔ اجرا سنجیده می‌شود)، پس «نقطهٔ برگشت سد» " + "برای آن معنا ندارد.")} + except (ValueError, KeyError, ZeroDivisionError): + return None + lo = base * 0.2 if lo is None else lo + hi = base * 3.0 if hi is None else hi + + def edge(value: float) -> float: + p = dict(params) + p[key] = value + try: + res = _run(kind, p, hurdle) + except (ValueError, ZeroDivisionError): + return -999.0 + annual = res.get("annualized_pct") + if annual is None: + return -999.0 + return float(annual) - hurdle * 100 + + e_lo, e_hi = edge(lo), edge(hi) + increasing = e_hi > e_lo + if (e_lo > 0) == (e_hi > 0): + return {"key": key, "label": FLIP_LABEL[kind], "value": None, + "note": "در این بازه نقطهٔ برگشت پیدا نشد؛ یعنی با این ورودی‌ها تصمیم عوض نمی‌شود."} + for _ in range(90): + mid = (lo + hi) / 2 + e_mid = edge(mid) + if e_mid == 0: + lo = hi = mid + break + if (e_mid > 0) == increasing: # ریشه بین lo و mid است + hi, e_hi = mid, e_mid + else: + lo, e_lo = mid, e_mid + if abs(hi - lo) <= tol * max(1.0, abs(base)): + break + value = (lo + hi) / 2 + return {"key": key, "label": FLIP_LABEL[kind], "value": round(value, 3), + "note": ("اگر این ورودی از این عدد بدتر شود، معامله از دروازه می‌افتد؛ " + "این همان «نقطهٔ بی‌تفاوتی» است که در ابزارهای نمایش‌دادهٔ بازار پیدا نمی‌شود.")} + + +def margin_call(*, contracts: float, margin_per_contract: float, notional_per_contract: float, + maintenance: float = MAINTENANCE_DEFAULT, current_price: float | None = None, + direction: str = "long") -> dict: + """فاصله تا اخطاریهٔ مارجین‌کال: چند درصد حرکت مخالف، حساب را به حد نگهداری می‌رساند. + + مبنا: حد نگهداری = ۷۰٪ وجه تضمین اولیه (رویهٔ بورس ایران). تسویهٔ روزانه است، پس هر روز + دوباره محاسبه می‌شود؛ عدد این‌جا برای همان لحظهٔ ورود است. + """ + if contracts <= 0 or margin_per_contract <= 0 or notional_per_contract <= 0: + return {"ok": False, "detail": "برای محاسبهٔ مارجین‌کال، تعداد قرارداد، وجه تضمین و ارزش قرارداد لازم است."} + buffer_per_contract = margin_per_contract * (1 - maintenance) + loss_pct_notional = buffer_per_contract / notional_per_contract * 100 + money_at_risk = buffer_per_contract * contracts + out = { + "ok": True, "contracts": contracts, "margin_per_contract": margin_per_contract, + "notional_per_contract": notional_per_contract, "maintenance": maintenance, + "maintenance_pct": round(maintenance * 100, 1), + "buffer_per_contract": round(buffer_per_contract, 2), + "move_pct": round(loss_pct_notional, 3), + "money_at_risk": round(money_at_risk, 2), + "margin_locked": round(margin_per_contract * contracts, 2), + "formula": ("فاصله = وجه تضمین × (۱ − حد نگهداری) ÷ ارزش قرارداد. " + f"اینجا: {fa_num(margin_per_contract)} × {1 - maintenance:.2f} ÷ " + f"{fa_num(notional_per_contract)} = {loss_pct_notional:.2f}٪ حرکت مخالف."), + "note": (" حرکت مخالف به همین اندازه، حساب را به حد نگهداری می‌رساند و اخطاریه می‌آید؛ " + "پس حد ضرر منطقی باید نزدیک‌تر از این عدد باشد، نه دورتر."), + } + if current_price: + level = (current_price * (1 - loss_pct_notional / 100) if direction != "short" + else current_price * (1 + loss_pct_notional / 100)) + out["price_level"] = round(level, 2) + out["price_note"] = (f"با قیمت فعلی {fa_num(current_price)}، سطح اخطاریه حدود " + f"{fa_num(level)} است.") + return out + + +def judge(kind: str, params: dict, *, hurdle: float = HURDLE_DEFAULT, capital: float = 100_000_000, + margin_per_contract: float = 0.0, contracts: float = 0.0, + notional_per_contract: float | None = None, maintenance: float = MAINTENANCE_DEFAULT, + initial_ratio: float = INITIAL_RATIO_DEFAULT, current_price: float | None = None, + claimed_return_pct: float | None = None, direction: str = "long") -> dict: + """داوری کامل یک سیگنال بیرونی: می‌ماند یا می‌افتد، چرا، تا کجا، و فاصله تا مارجین‌کال.""" + if kind not in KINDS: + return {"ok": False, "detail": f"نوع راهبرد «{kind}» شناخته نشد. گزینه‌ها: " + + "، ".join(KINDS)} + try: + res = _run(kind, params, hurdle) + except (ValueError, KeyError, ZeroDivisionError) as e: + return {"ok": False, "detail": f"عددهای ورودی کامل یا درست نیست: {e}"} + + annual = res.get("annualized_pct") + annual_f = float(annual) if isinstance(annual, (int, float)) else None + edge_pp = (annual_f - hurdle * 100) if annual_f is not None else None + reasons: list[str] = [] + gates: list[dict] = [] + + def gate(name: str, ok: bool, detail: str): + gates.append({"gate": name, "ok": bool(ok), "detail": detail}) + if not ok: + reasons.append(detail) + + gate("موتور ریاضی", bool(res.get("go")), "موتور خودش این معامله را پذیرفت." + if res.get("go") else "موتور ریاضی این ساختار را از پایه رد می‌کند (مثلاً جهت لازم ممکن نیست).") + if annual_f is None: + structural = kind == "parity" + gate("بازده قابل محاسبه", structural, + "این ساختار بازده سالانهٔ ساده ندارد؛ تصمیمش با تساوی پوت‌کال گرفته می‌شود." + if structural else "بازده سالانه از این عددها درنمی‌آید؛ ورودی‌ها را کامل کنید.") + else: + ok_hurdle = edge_pp is not None and edge_pp > 0 + gate("نرخ سد", ok_hurdle, + f"بازده سالانه {annual_f:.1f}٪ در برابر نرخ سد {hurdle * 100:.0f}٪ → " + f"{'مثبت' if ok_hurdle else 'منفی'} ({edge_pp:+.1f} واحد درصد).") + gate("معقول‌بودن عدد", not (annual_f is not None and annual_f / 100 > PLAUSIBLE_CAP), + "بازده سالانه معقول است." if annual_f / 100 <= PLAUSIBLE_CAP else + f"بازده سالانه {annual_f:.0f}٪ غیرواقعی است؛ احتمالاً قیمت جابه‌جا وارد شده.") + liq = res.get("liquidity_contracts_per_day", 99) + gate("نقدشوندگی", liq >= LIQUIDITY_FLOOR, + f"نقدشوندگی {liq} قرارداد در روز " + ("کافی است." if liq >= LIQUIDITY_FLOOR + else f"کمتر از کف {LIQUIDITY_FLOOR} است؛ خروج از موقعیت ممکن است گران تمام شود.")) + spread = float(res.get("spread_pct") or 0.0) + gate("اسپرد", spread <= SPREAD_CAP, + f"اسپرد {spread * 100:.1f}٪ " + ("قابل قبول است." if spread <= SPREAD_CAP + else f"از سقف {SPREAD_CAP * 100:.0f}٪ بیشتر است؛ سود کاغذی است.")) + if kind == "parity": + d = str(res.get("direction") or "") + gate("قابل اجرا بودن جهت", not d.startswith("reverse"), + "جهت معامله در ایران قابل اجرا است." if not d.startswith("reverse") + else f"جهت لازم «{d}» است؛ فروش استقراضی در ایران ممکن نیست.") + + verdict = "می‌ماند" if not reasons else "می‌افتد" + if contracts and margin_per_contract and notional_per_contract is None: + notional_per_contract = margin_per_contract / max(initial_ratio, 1e-9) + mc = (margin_call(contracts=contracts or 1, margin_per_contract=margin_per_contract, + notional_per_contract=notional_per_contract or 0.0, + maintenance=maintenance, current_price=current_price, direction=direction) + if (margin_per_contract and notional_per_contract) else + {"ok": False, "detail": "برای فاصلهٔ مارجین‌کال، وجه تضمین هر قرارداد و ارزش قرارداد را بدهید."}) + + hand = hand_annualized(kind, params, res) + diff = (None if (hand.get("annualized_pct") is None or annual_f is None) + else round(float(hand["annualized_pct"]) - annual_f, 3)) + + size = None + if capital and margin_per_contract: + engine = load_engine() + size = engine.position_size(capital=capital, margin_per_contract=margin_per_contract, + risk_pct=0.20, concurrent=1) + + payload = { + "ok": True, "ts": now_iso(), "kind": kind, + "kind_label": KIND_LABELS.get(kind, kind), "params": params, + "hurdle": hurdle, "capital": capital, "annualized_pct": annual_f, "edge_pp": edge_pp, + "engine_go": bool(res.get("go")), "score_pp": res.get("score_pp"), + "verdict": verdict, "reasons": reasons, "gates": gates, + "break_even": break_even(kind, params, hurdle), "margin": mc, "size": size, + "hand": hand, "hand_diff_pp": diff, + "claimed_return_pct": claimed_return_pct, + "claim_note": (None if claimed_return_pct is None else + f"ابزار شما {claimed_return_pct:.1f}٪ سالانه گفته؛ محاسبهٔ خالص این‌جا " + f"{annual_f:.1f}٪ است ({annual_f - claimed_return_pct:+.1f} واحد درصد). " + "اختلاف معمولاً از کارمزد، اسپرد و مالیات می‌آید که در آن عدد لحاظ نشده."), + "res": res, + } + payload["fingerprint"] = fingerprint({k: v for k, v in payload.items() if k != "fingerprint"}) + return payload + + +# ---------------------------------------------------------------- برگهٔ داوری +def _html(j: dict) -> str: + if not j.get("ok"): + return f"

    {j.get('detail')}

    " + ok = j["verdict"] == "می‌ماند" + color = "#0a7f4f" if ok else "#b32020" + rows = "\n".join( + f"{g['gate']}{'✅' if g['ok'] else '❌'}" + f"{g['detail']}" for g in j["gates"]) + be = j.get("break_even") or {} + mc = j.get("margin") or {} + sz = j.get("size") or {} + return f""" +داوری سیگنال — {j['kind_label']} +
    +

    داوری سیگنال بیرونی

    +

    {j['ts']} · نسخهٔ {VERSION} · اثر انگشت: {j['fingerprint']}

    +

    سیگنال: {j['kind_label']}

    +
    داوری: {j['verdict']}
    +
    + بازده سالانهٔ خالص{fa_num(j['annualized_pct'])}٪ + نرخ سد{j['hurdle'] * 100:.0f}٪ + حاشیه بر سد{fa_num(j['edge_pp'])} واحد +
    +{"

    ⚠️ " + " · ".join(j["reasons"]) + "

    " if j["reasons"] else ""} +

    دروازه‌ها

    +{rows}
    دروازهنتیجهتوضیح
    +

    نقطهٔ برگشت (تا کجا می‌مانَد)

    +

    {('در «' + be.get('label', '') + '»: ' + str(be.get('value')) + ' — ' + be.get('note', '') + if be and be.get('value') is not None else (be or {}).get('note', '—'))}

    +

    فاصله تا مارجین‌کال

    +{("

    " + mc.get("formula", "") + "

    حد نگهداری " + str(mc.get("maintenance_pct")) + + "٪ · پول در معرض خطر: " + fa_num(mc.get("money_at_risk"), 0) + " · " + mc.get("note", "") + + (" " + mc.get("price_note", "") if mc.get("price_note") else "") + "

    ") + if mc.get("ok") else "

    " + mc.get("detail", "—") + "

    "} +

    اندازهٔ موقعیت و دو روش حساب

    +{("

    با سرمایهٔ " + fa_num(j["capital"], 0) + " و وجه تضمین " + + fa_num(mc.get("margin_per_contract") or 0, 0) + " در هر قرارداد: " + str(sz.get("contracts")) + + " قرارداد (درگیر " + fa_num(sz.get("margin_locked"), 0) + "، آزاد " + fa_num(sz.get("free_cash"), 0) + ").

    ") + if sz else ""} +

    محاسبهٔ دوم (مستقل از موتور): {j['hand']['method']} → {j['hand']['annualized_pct']}٪ سالانه + (اختلاف با موتور: {j['hand_diff_pp']} واحد درصد). عددها را با ماشین‌حساب جیبی هم می‌توان بازبینی کرد.

    +{j.get("claim_note") or ""} +
    {CREDIT}
    هیچ سفارشی از این برنامه ارسال نمی‌شود؛ اجرا در سامانهٔ کارگزاری با انسان است. +عددها روی ورودی‌های همین برگه بسته شده‌اند و اثر انگشت بالا تغییرشان را لو می‌دهد.
    +
    +""" + + +def _md(j: dict) -> str: + if not j.get("ok"): + return f"# داوری سیگنال\n\n{j.get('detail')}\n" + L = [f"# داوری سیگنال بیرونی — {j['kind_label']}\n", + f"تاریخ: {j['ts']} · اثر انگشت: {j['fingerprint']}\n", f"## داوری: {j['verdict']}\n", + f"- بازده سالانهٔ خالص: {j['annualized_pct']}٪ (نرخ سد {j['hurdle'] * 100:.0f}٪، " + f"حاشیه {j['edge_pp']} واحد)", "\n## دروازه‌ها\n", "| دروازه | نتیجه | توضیح |", "| --- | --- | --- |"] + for g in j["gates"]: + L.append(f"| {g['gate']} | {'✅' if g['ok'] else '❌'} | {g['detail']} |") + be = j.get("break_even") or {} + mc = j.get("margin") or {} + L += ["\n## نقطهٔ برگشت\n", (f"{be.get('label')}: {be.get('value')} — {be.get('note')}" + if be.get("value") is not None else be.get("note", "—"))] + L += ["\n## فاصله تا مارجین‌کال\n", mc.get("formula", mc.get("detail", "—")), + (f"حد نگهداری {mc.get('maintenance_pct')}٪ · پول در معرض خطر {mc.get('money_at_risk')}" + if mc.get("ok") else "")] + L += [f"\n## دو روش حساب\n", f"موتور: {j['annualized_pct']}٪ · دستی: {j['hand']['annualized_pct']}٪ " + f"(اختلاف {j['hand_diff_pp']} واحد)", f"\n{j.get('claim_note') or ''}", f"\n{CREDIT}"] + return "\n".join(L) + "\n" + + +def build_sheet(j: dict, path_html: Path | str = SHEET_HTML, + path_md: Path | str = SHEET_MD) -> tuple[Path, Path]: + h, m = Path(path_html), Path(path_md) + h.parent.mkdir(parents=True, exist_ok=True) + h.write_text(_html(j), encoding="utf-8") + m.write_text(_md(j), encoding="utf-8") + return h, m + + +# ---------------------------------------------------------------- خط فرمان +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description="داوری سیگنال ابزارهای دیگر با کارمزد و ریسک واقعی") + ap.add_argument("--kind", choices=sorted(KINDS), help="نوع راهبرد") + ap.add_argument("--params", default="", help="عددهای ورودی به شکل JSON") + ap.add_argument("--file", default="", help="پروندهٔ JSON با کلیدهای kind و params") + ap.add_argument("--hurdle", type=float, default=HURDLE_DEFAULT, help="نرخ سد سالانه (۰٫۳۹ = ۳۹٪)") + ap.add_argument("--capital", type=float, default=100_000_000, help="سرمایه (ریال/تومان)") + ap.add_argument("--margin", type=float, default=0.0, help="وجه تضمین اولیهٔ هر قرارداد") + ap.add_argument("--contracts", type=float, default=0.0, help="تعداد قرارداد") + ap.add_argument("--notional", type=float, default=None, help="ارزش هر قرارداد") + ap.add_argument("--maintenance", type=float, default=MAINTENANCE_DEFAULT, help="حد نگهداری (۰٫۷)") + ap.add_argument("--price", type=float, default=None, help="قیمت فعلی دارایی پایه") + ap.add_argument("--claimed", type=float, default=None, help="بازدهی که ابزار فعلی شما گفته (٪)") + ap.add_argument("--sheet", action="store_true", help="ساخت برگهٔ چاپی داوری") + ap.add_argument("--json", action="store_true", help="خروجی ماشین‌خوان") + ap.add_argument("--version", action="version", version=f"signal_judge {VERSION}") + args = ap.parse_args(argv) + + if args.file: + blob = json.loads(Path(args.file).read_text(encoding="utf-8")) + kind = blob.get("kind") or args.kind + params = blob.get("params") or {} + args.hurdle = blob.get("hurdle", args.hurdle) + for k in ("capital", "margin", "contracts", "notional", "maintenance", "price", "claimed"): + if k in blob: + setattr(args, k, blob[k]) + else: + kind = args.kind + params = json.loads(args.params) if args.params else {} + if not kind: + print("نوع راهبرد را بدهید: " + "، ".join(sorted(KINDS)), file=sys.stderr) + return 2 + + j = judge(kind, params, hurdle=args.hurdle, capital=args.capital, + margin_per_contract=args.margin, contracts=args.contracts, + notional_per_contract=args.notional, maintenance=args.maintenance, + current_price=args.price, claimed_return_pct=args.claimed) + if args.sheet and j.get("ok"): + h, m = build_sheet(j) + j["sheet_html"], j["sheet_md"] = str(h), str(m) + if args.json: + print(json.dumps(j, ensure_ascii=False, indent=1)) + return 0 if j.get("ok") else 2 + if not j.get("ok"): + print(j.get("detail")) + return 2 + ann = "قابل محاسبه نیست" if j["annualized_pct"] is None else f"{j['annualized_pct']}٪" + print(f"داوری: {j['verdict']} (بازده سالانهٔ خالص {ann} در برابر سد {j['hurdle'] * 100:.0f}٪)") + for g in j["gates"]: + print(f" {'✓' if g['ok'] else '✗'} {g['gate']}: {g['detail']}") + be = j.get("break_even") or {} + if be.get("value") is not None: + print(f"نقطهٔ برگشت — {be['label']}: {be['value']}") + mc = j.get("margin") or {} + if mc.get("ok"): + print(f"مارجین‌کال: {mc['move_pct']}٪ حرکت مخالف · پول در معرض خطر {fa_num(mc['money_at_risk'], 0)}" + + (f" · سطح اخطاریه {mc.get('price_level')}" if mc.get("price_level") else "")) + print(f"دو روش: موتور {j['annualized_pct']}٪ · دستی {j['hand']['annualized_pct']}٪ " + f"(اختلاف {j['hand_diff_pp']} واحد) · اثر انگشت {j['fingerprint']}") + if j.get("sheet_html"): + print("برگهٔ داوری: " + j["sheet_html"]) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/station/snapshot_import.py b/station/snapshot_import.py new file mode 100644 index 0000000000000000000000000000000000000000..48104c932dbccbec3f196b7da3ae3318c12ce075 --- /dev/null +++ b/station/snapshot_import.py @@ -0,0 +1,526 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""ورود اعداد کارگزاری از متن کپی‌شده — برای کم‌کردن خطای انسانی. + +کاربر نوآموز این اعداد را از سامانهٔ کارگزاری یا سایت مرجع کپی می‌کند. به‌جای تایپ دستی، متن را +این‌جا می‌چسباند و برنامه خودش ردیف‌ها را می‌سازد: رقم‌های فارسی، جداکنندهٔ هزارگان، «تومان»، +و خط‌های کج‌وکوله را می‌فهمد و هر چیزی را که نفهمید، صادقانه به‌عنوان «مشکل» برمی‌گرداند. + +قالب سادهٔ پیشنهادی (هر خط یک ردیف): + نماد , راهبرد , عددها... + اهرم , basis , 20000 , 22800 , 90 , 20000000 , 900 , 0.005 + فولاد , covered_call , 7000 , 7600 , 400 , 45 , 7000 , 160 , 0.018 + +اگر نام راهبرد را ننویسید، از روی تعداد و بزرگی عددها حدس زده می‌شود و در «هشدارها» گفته می‌شود +که جای حدس است. این ماژول هیچ‌وقت خودش ذخیره نمی‌کند؛ ذخیره فقط با تیک تأیید خودِ کاربر انجام +می‌شود تا روز «واقعی» بی‌اجازه ساخته نشود. +""" +from __future__ import annotations + +import argparse +import json +import re +import sys +from pathlib import Path + +VERSION = "0.2.0" +BASE = Path(__file__).resolve().parent +if str(BASE) not in sys.path: + sys.path.insert(0, str(BASE)) + +import datafeed as df # noqa: E402 + +PERSIAN_DIGITS = str.maketrans("۰۱۲۳۴۵۶۷۸۹٠١٢٣٤٥٦٧٨٩", "01234567890123456789") + +KIND_WORDS = { + "basis": "basis", "کری": "basis", "نقدی": "basis", "cash": "basis", + "covered_call": "covered_call", "covered": "covered_call", "پوشش": "covered_call", + "پوشش‌داده‌شده": "covered_call", "کاورد": "covered_call", + "tabei": "tabei", "تبعی": "tabei", "تضمین": "tabei", + "box": "box", "باکس": "box", "جعبه": "box", + "parity": "parity", "تساوی": "parity", "پوت‌کال": "parity", +} + +# ترتیب عددها برای هر راهبرد (همان ترتیبی که موتور می‌خواند) +NUM_ORDER = { + "basis": ("spot", "future", "days"), + "covered_call": ("spot", "strike", "premium", "days"), + "tabei": ("stock_price", "put_price", "strike", "days"), + "box": ("call_low", "put_low", "call_high", "put_high", "strike_low", "strike_high", "days"), + "parity": ("call", "put", "spot", "strike", "days"), +} +OPTIONAL_ORDER = ("margin_per_contract", "liquidity_contracts_per_day", "spread_pct") + +PRICE_FIELDS = ("spot", "stock_price", "future", "strike", "strike_low", "strike_high", "premium", + "put_price", "call", "put", "call_low", "call_high", "put_low", "put_high", + "margin_per_contract") + +HEADER_MAP = { + "قیمت پایه": "spot", "قیمت نقدی": "spot", "قیمت سهم": "stock_price", "نقدی": "spot", + "پایه": "spot", "سهم": "stock_price", "آتی": "future", "اعمال": "strike", + "پرمیوم": "premium", "پوت": "put", "کال": "call", "روز": "days", "سررسید": "days", + "وجه تضمین": "margin_per_contract", "تضمین": "margin_per_contract", + "حجم": "liquidity_contracts_per_day", "نقدشوندگی": "liquidity_contracts_per_day", + "اسپرد": "spread_pct", +} + +_SEP = re.compile(r"\t|,|،|;|؛|\s{2,}|\|") +_THOUSANDS = re.compile(r"(?<=\d),(?=\d{3}(?!\d))") # «7,600» عدد است، نه دو ستون +_NUM = re.compile(r"^-?\d+(?:\.\d+)?$") + + +def norm_digits(text: str) -> str: + """رقم‌های فارسی/عربی را به لاتین برمی‌گرداند و نویسه‌های مزاحم را پاک می‌کند.""" + out = str(text or "").translate(PERSIAN_DIGITS) + out = out.replace("٬", ",").replace("،", ",").replace("\u200f", "").replace("\u200e", "") + out = re.sub(r"\u200c", " ", out) # نیم‌فاصله + return out + + +def to_number(token: str) -> float | None: + """'۲۰٬۰۰۰ ریال' یا '20,000' یا '1.5' را به عدد می‌گرداند؛ اگر عدد نبود None.""" + t = norm_digits(token).strip().strip('"').strip("'") + if not t: + return None + t = re.sub(r"(ریال|تومان|درصد|٪|%)", "", t).strip() + t = t.replace(" ", "").replace(",", "") + if not _NUM.match(t): + return None + try: + return float(t) + except ValueError: + return None + + + +def _is_label(token: str) -> bool: + """آیا این کلمه یک برچسب شناخته‌شده است (نام راهبرد یا نام ستون)؟""" + t = norm_digits(token).strip().lower() + if t in KIND_WORDS: + return True + return any(word in t for word in HEADER_MAP) + + +def map_headers(parts: list[str]) -> list[str | None]: + """سرستون‌های فارسی را به نام فیلد تبدیل می‌کند (هر چه نفهمید None).""" + out: list[str | None] = [] + for p in parts: + t = norm_digits(p).strip() + hit = None + for word, field in HEADER_MAP.items(): + if word in t: + hit = field + break + out.append(hit) + return out + + +FAMILY = { + "spot": "price", "stock_price": "price", "future": "future", + "strike": "strike", "strike_low": "strike_low", "strike_high": "strike_high", + "premium": "premium", "put_price": "premium", + "call": "call", "call_low": "call", "call_high": "call", + "put": "put", "put_low": "put", "put_high": "put", + "days": "days", "margin_per_contract": "margin", + "liquidity_contracts_per_day": "liquidity", "spread_pct": "spread", +} + + +def kind_from_headers(fields: list[str | None]) -> str | None: + """راهبرد را از روی خانوادهٔ سرستون‌ها می‌فهمد (قیمت/اعمال/پرمیوم/روز و مانند آن).""" + fams = {FAMILY[f] for f in fields if f} + if {"call", "put", "price", "strike", "days"} <= fams: + return "parity" + if {"strike_low", "strike_high", "call", "put", "days"} <= fams: + return "box" + if {"price", "future", "days"} <= fams: + return "basis" + if {"price", "strike", "days"} <= fams and "put" in fams and "call" not in fams: + return "tabei" # «قیمت سهم + پوت + اعمال» یعنی تضمین فروش + if {"price", "strike", "premium", "days"} <= fams: + return "covered_call" # با «قیمت سهم و پرمیوم» می‌خواند؛ دوپهلو گزارش می‌شود + if {"price", "strike", "days"} <= fams: + return "covered_call" + return None + + +def candidates(numbers: list[float]) -> list[tuple[str, int]]: + """راهبردهایی که با این تعداد عدد می‌خوانند (عددهای اختیاری: وجه تضمین، حجم، اسپرد).""" + n = len(numbers) + out = [] + for kind, order in NUM_ORDER.items(): + need = len(order) + if need <= n <= need + len(OPTIONAL_ORDER): + # «روز» باید کوچک و مثبت باشد، وگرنه این حدس بی‌معنی است + if 0 < numbers[need - 1] <= 1500: + out.append((kind, need)) + return out + + +def pick_kind(numbers: list[float], kind_token: str = "", default_kind: str | None = None, + header_kind: str | None = None) -> tuple[str, str, bool]: + """(راهبرد، دلیل، دوپهلو؟) — اولویت: راهبرد نوشته‌شده، بعد سرستون، بعد حدس.""" + if kind_token: + key = kind_token.strip().lower() + if key in KIND_WORDS: + return KIND_WORDS[key], "راهبرد از خودِ متن خوانده شد", False + if default_kind: + return default_kind, "راهبرد پیش‌فرض انتخاب‌شده", False + if header_kind: + return header_kind, "راهبرد از روی سرستون‌ها فهمیده شد", False + cand = candidates(numbers) + if not cand: + kind, why = guess_kind(numbers) + return kind, why, True + cand.sort(key=lambda k: -k[1]) # بزرگ‌ترین تعداد لازم، محافظه‌کارانه‌تر است + kind, need = cand[0] + ambiguous = len(cand) > 1 + return kind, f"{len(numbers)} عدد ⇒ {kind} ({need} عدد لازم + {len(numbers) - need} عدد اختیاری)", ambiguous + + + +# اسلات هر فیلد در سرستون‌ها (نام‌های هم‌معنی پذیرفته می‌شوند) +SLOT = { + "spot": "price", "stock_price": "price", "future": "future", + "strike": "strike", "strike_low": "strike_low", "strike_high": "strike_high", + "premium": "premium", "put_price": "put_price", + "call": "call", "call_low": "call_low", "call_high": "call_high", + "put": "put", "put_low": "put_low", "put_high": "put_high", + "days": "days", "margin_per_contract": "margin", + "liquidity_contracts_per_day": "liquidity", "spread_pct": "spread", +} + +# برای هر راهبرد: (فیلد موتور، اسلات‌های پذیرفته‌شده) +KIND_FIELD_SLOTS = { + "basis": [("spot", {"price"}), ("future", {"future"}), ("days", {"days"})], + "covered_call": [("spot", {"price"}), ("strike", {"strike"}), + ("premium", {"premium", "call", "call_low", "call_high"}), ("days", {"days"})], + "tabei": [("stock_price", {"price"}), ("put_price", {"put_price", "put", "premium"}), + ("strike", {"strike"}), ("days", {"days"})], + "parity": [("call", {"call"}), ("put", {"put"}), ("spot", {"price"}), + ("strike", {"strike"}), ("days", {"days"})], +} + + +def fill_by_headers(row: dict, kind: str, numbers: list[float], + header_fields: list[str | None]) -> tuple[int, list[str]]: + """عددها را بر پایهٔ نام سرستون‌ها در جای درست می‌گذارد. (تعداد مصرف‌شده، هشدارها)""" + warnings: list[str] = [] + plan = [[field, set(accept), False] for field, accept in KIND_FIELD_SLOTS[kind]] + used = 0 + for name in header_fields: + if used >= len(numbers): + break + slot = SLOT.get(name) if name else None + value = numbers[used] + used += 1 + if slot is None: + warnings.append("یک سرستون ناشناخته بود؛ شمارهٔ آن نادیده گرفته شد") + continue + for item in plan: + if not item[2] and slot in item[1]: + row[item[0]] = value + item[2] = True + break + else: + warnings.append(f"عدد مربوط به «{slot}» در جای شناخته‌شده‌ای جا نگرفت") + missing = [item[0] for item in plan if not item[2]] + return used, warnings, missing + + + +def row_header_fields(tokens: list[str]) -> list[str | None]: + """اگر خودِ ردیف برچسب داشته باشد («قیمت سهم، پوت، اعمال، روز»)، همان‌ها را سرستون می‌گیریم. + + خروجی: فهرستی هم‌طول با تعداد برچسب‌ها؛ برای هر برچسب، نام فیلد (یا None). + """ + labels = [norm_digits(t).strip() for t in tokens + if to_number(t) is None and _is_label(t)] + if len(labels) < 2: + return [] + names: list[str | None] = [] + for lab in labels: + hit = None + for word, field in HEADER_MAP.items(): + if word in lab: + hit = field + break + names.append(hit) + return names + + +def numbers_by_labels(tokens: list[str]) -> list[float]: + """عددهایی که پشت هر برچسب آمده‌اند، به همان ترتیب برچسب‌ها.""" + out: list[float] = [] + for t in tokens: + v = to_number(t) + if v is not None: + out.append(v) + return out + + +def _split(line: str) -> list[str]: + guarded = _THOUSANDS.sub("\u0001", line.strip()) # جداکنندهٔ هزارگان را نگه می‌داریم + parts = [p.strip() for p in _SEP.split(guarded) if p.strip()] + if len(parts) <= 1: # تک‌فاصله‌ای، مثل «اهرم 20000 22800 90» + parts = [p for p in re.split(r"\s+", guarded) if p] + return [p.replace("\u0001", ",") for p in parts] + + +CONFLICT_FIELDS = ("spot", "stock_price", "strike", "premium", "put_price", "call", "put", "days") + + +def conflict_hint(symbol: str, kind: str, row: dict, numbers: list[float]) -> str: + """اگر «سرستون‌ها» یک خوانش بدهند و «ترتیب معمولی» خوانش دیگری، صریح بگو. + + این تنها جایی است که می‌تواند خطای انسانی بسازد: جدولی که سرستونش با ترتیب + عددهایش نمی‌خواند. به‌جای اینکه بی‌صدا یکی را انتخاب کنیم، هر دو خوانش را نشان می‌دهیم. + """ + order = NUM_ORDER.get(kind) or [] + if not order or len(numbers) < len(order): + return "" + pairs = [] + for field, value in zip(order, numbers): + if field in CONFLICT_FIELDS and field in row: + got, alt = float(row[field]), float(value) + if got and abs(got - alt) > max(abs(got), abs(alt)) * 0.2: + pairs.append(f"{field}: سرستون {got:,.0f} ↔ ترتیب {alt:,.0f}") + if not pairs: + return "" + return (f"{symbol}: سرستون‌ها و ترتیب معمولی با هم نمی‌خوانند؛ بازبینی کنید → " + + " · ".join(pairs[:3])) + + +def sanity_problems(symbol: str, kind: str, row: dict) -> list[str]: + """بازبینی عقلی: عددهایی که از نظر اقتصادی محال‌اند، بی‌صدا رد نمی‌شوند. + + این جدول برای تازه‌کار است: اگر ستون‌ها جابه‌جا چسبیده باشند، معمولاً همین‌جا لو می‌رود. + """ + out: list[str] = [] + def num(k): + v = row.get(k) + return float(v) if isinstance(v, (int, float)) else None + for f in PRICE_FIELDS: + v = num(f) + if v is not None and v <= 0: + out.append(f"{symbol}: «{f}» صفر یا منفی است") + if kind == "covered_call": + sp, st, pr = num("spot"), num("strike"), num("premium") + if sp and st and st < sp: + out.append(f"{symbol}: قیمت اعمال ({st:,.0f}) از قیمت سهم ({sp:,.0f}) کمتر است؛ " + f"در پوشش‌داده‌شده اعمال باید بالاتر باشد") + if sp and pr and pr > sp * 0.3: + out.append(f"{symbol}: پرمیوم ({pr:,.0f}) نسبت به قیمت سهم ({sp:,.0f}) بزرگ است؛ " + f"احتمالاً ستون‌ها جابه‌جا چسبیده‌اند") + if kind == "tabei": + sp, st = num("stock_price"), num("strike") + if sp and st and st < sp: + out.append(f"{symbol}: در تبعی، قیمت اعمال ({st:,.0f}) باید از قیمت سهم ({sp:,.0f}) " + f"بیشتر باشد؛ این اعداد جابه‌جا شده‌اند") + if kind == "basis": + sp, fu = num("spot"), num("future") + if sp and fu and fu < sp: + out.append(f"{symbol}: قیمت آتی ({fu:,.0f}) از نقدی ({sp:,.0f}) کمتر است؛ مبنای منفی " + f"معمولاً یعنی ستون‌ها جابه‌جا شده‌اند") + if kind == "box": + low, high = num("strike_low"), num("strike_high") + if low and high and high <= low: + out.append(f"{symbol}: اعمال بالا باید از پایین بزرگ‌تر باشد") + return out + + +def guess_kind(numbers: list[float], symbol_hint: str = "") -> tuple[str, str]: + """راهبرد را از تعداد و بزرگی عددها حدس می‌زند؛ (راهبرد، دلیل) برمی‌گرداند.""" + n = len(numbers) + if symbol_hint: + key = symbol_hint.strip().lower() + if key in KIND_WORDS: + return KIND_WORDS[key], "راهبرد از خودِ متن خوانده شد" + if n <= 3: + return "basis", f"{n} عدد ⇒ کری (نقدی/آتی/روز)" + if n == 5: + return "parity", "۵ عدد ⇒ تساوی پوت‌کال" + if n >= 7: + return "box", f"{n} عدد ⇒ باکس اسپرد" + # چهار عدد: یا پوشش‌داده‌شده یا تبعی + if n == 4: + if numbers[1] > numbers[0] and numbers[2] < numbers[0]: + return "covered_call", "۴ عدد و ترتیب شبیه پوشش‌داده‌شده" + if numbers[1] < numbers[0] and numbers[3] > 200: + return "tabei", "۴ عدد و ترتیب شبیه تبعی" + return "covered_call", "۴ عدد؛ راهبرد حدس زده شد، لطفاً در جدول بازبینی کنید" + return "basis", f"{n} عدد؛ راهبرد حدس زده شد" + + +def parse_paste(text: str, *, toman_to_rial: bool = False, + default_kind: str | None = None) -> dict: + """متن چسبانده‌شده را به ردیف‌های اسنپ‌شات تبدیل می‌کند (بدون ذخیره‌کردن).""" + rows: list[dict] = [] + problems: list[str] = [] + hints: list[str] = [] + header_fields: list[str | None] = [] + header_kind: str | None = None + scaled = False + header_seen = False + + for raw in str(text or "").splitlines(): + line = raw.strip() + if not line or line.startswith("#") or line.startswith("//"): + continue + parts = _split(line) + if not parts: + continue + + head = norm_digits(parts[0]).strip() + if head.lower().startswith(("نماد", "symbol")): + header_fields = map_headers(parts[1:]) + header_kind = kind_from_headers(header_fields) + header_seen = True + continue + + symbol = "" + if to_number(parts[0]) is None: + symbol = head + parts = parts[1:] + else: + problems.append(f"بی‌نماد: خط «{raw.strip()[:40]}» نماد ندارد؛ رد شد") + continue + + kind_token = "" + if parts and to_number(parts[0]) is None and \ + norm_digits(parts[0]).strip().lower() in KIND_WORDS: + kind_token = norm_digits(parts[0]).strip() + parts = parts[1:] + + numbers: list[float] = [] + dropped: list[str] = [] + for p in parts: + v = to_number(p) + if v is None: + if not _is_label(p): + dropped.append(norm_digits(p).strip()) + else: + numbers.append(v) + + local_headers = row_header_fields(parts) # برچسب‌های داخل خودِ ردیف + if local_headers and not kind_token and not default_kind: + local_kind = kind_from_headers(local_headers) + if local_kind: + kind_token = local_kind # راهبرد از برچسب‌های ردیف + if local_headers: + header_fields, header_kind = local_headers, kind_from_headers(local_headers) + dropped = [d for d in dropped if not _is_label(d)] + if dropped: + hints.append(f"{symbol}: این‌ها عدد نبودند و نادیده گرفته شد → {'، '.join(dropped[:4])}") + if not numbers: + problems.append(f"{symbol}: هیچ عددی پیدا نشد") + continue + + kind, why, ambiguous = pick_kind(numbers, kind_token, default_kind, header_kind) + order = NUM_ORDER.get(kind) + if not order: + problems.append(f"{symbol}: راهبرد ناشناخته «{kind}»") + continue + + row: dict = {"symbol": symbol, "kind": kind, "unit": "قرارداد" if kind != "tabei" else "سهم"} + used = 0 + if header_fields and header_kind == kind and kind in KIND_FIELD_SLOTS: + used, warns, missing = fill_by_headers(row, kind, numbers, header_fields) + for w in warns: + hints.append(f"{symbol}: {w}") + if missing: + problems.append(f"{symbol}: از روی سرستون‌ها این‌ها جا نیفتاد → {'، '.join(missing)}") + continue + for field in OPTIONAL_ORDER: # عددهای باقی‌مانده = وجه تضمین/حجم/اسپرد + if used < len(numbers) and field not in row: + row[field] = numbers[used] + used += 1 + else: + main = numbers[:len(order)] + extras = numbers[len(order):] + if len(main) < len(order): + problems.append( + f"{symbol}: برای «{kind}» به {len(order)} عدد نیاز است ولی {len(main)} عدد داده شد. " + f"ترتیب لازم: {' , '.join(order)}") + continue + for field, value in zip(order, main): + row[field] = value + for field, value in zip(OPTIONAL_ORDER, extras): + row[field] = value + used = len(order) + min(len(extras), len(OPTIONAL_ORDER)) + if len(numbers) > used: + hints.append(f"{symbol}: {len(numbers) - used} عدد اضافه بود و نادیده گرفته شد") + + if "spread_pct" in row and row["spread_pct"] > 1: # ۱٫۸ یعنی ۱٫۸٪ + row["spread_pct"] = round(row["spread_pct"] / 100, 6) + hints.append(f"{symbol}: اسپرد به درصد داده شده بود؛ به کسری تبدیل شد") + for f in ("spot", "stock_price", "future", "strike", "strike_low", "strike_high", "premium", + "put_price", "call", "put", "call_low", "call_high", "put_low", "put_high", + "days", "margin_per_contract", "liquidity_contracts_per_day"): + if f in row: + row[f] = int(row[f]) if float(row[f]).is_integer() else float(row[f]) + if not row.get("days") or int(row["days"]) <= 0: + problems.append(f"{symbol}: «روز» درست خوانده نشد") + continue + missing_opt = [f for f in OPTIONAL_ORDER if f not in row] + if missing_opt: + hints.append(f"{symbol}: {'، '.join(missing_opt)} داده نشد؛ در جدول خودتان پر کنید") + for warn in sanity_problems(symbol, kind, row): + problems.append(warn) + conflict = conflict_hint(symbol, kind, row, numbers) + if conflict: + hints.append(conflict) + if not kind_token and not default_kind: + note = "راهبرد حدس زده شد" + (" (دوپهلو: از فهرست جدول بازبینی کنید)" if ambiguous else "") + hints.append(f"{symbol}: {note} ({kind})") + hints.append(f"{symbol}: {why}") + if toman_to_rial: + for f in PRICE_FIELDS: + if f in row: + row[f] = row[f] * 10 + scaled = True + rows.append(row) + + if header_seen: + named = [f for f in header_fields if f] + hints.append("سرستون خوانده شد: " + " | ".join(named or ["(ناشناخته)"])) + if scaled: + hints.append("عددهای قیمتی ×۱۰ شد (تومان به ریال)") + return {"ok": bool(rows), "rows": rows, "problems": problems, "hints": hints, + "count": len(rows), "version": VERSION} + + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description="ورود اعداد از متن کپی‌شده") + ap.add_argument("--text", help="متن چندخطی (اگر ندهید، از ورودی استاندارد می‌خواند)") + ap.add_argument("--file", help="مسیر پروندهٔ متنی") + ap.add_argument("--toman", action="store_true", help="عددها به تومان است (×۱۰ می‌شود)") + ap.add_argument("--kind", help="راهبرد پیش‌فرض برای همهٔ خط‌ها") + ap.add_argument("--json", action="store_true", help="خروجی ماشین‌خوان") + ap.add_argument("--version", action="version", version=f"snapshot_import {VERSION}") + args = ap.parse_args(argv) + + text = args.text or "" + if args.file: + text = Path(args.file).read_text(encoding="utf-8-sig") + if not text and not sys.stdin.isatty(): + text = sys.stdin.read() + res = parse_paste(text, toman_to_rial=args.toman, default_kind=args.kind) + if args.json: + print(json.dumps(res, ensure_ascii=False, indent=1)) + return 0 if res["ok"] else 1 + print(f"{res['count']} ردیف خوانده شد.") + for row in res["rows"]: + print(" •", json.dumps(row, ensure_ascii=False)) + for p in res["problems"]: + print(" ✗", p) + for h in res["hints"]: + print(" ·", h) + checks = df.clean_rows(res["rows"])[1] if res["rows"] else [] + for c in checks: + print(" !", c) + return 0 if res["ok"] else 1 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/station/station.py b/station/station.py new file mode 100644 index 0000000000000000000000000000000000000000..0300d7acf67e8743e3394e82ee7b9ffa6dad221b --- /dev/null +++ b/station/station.py @@ -0,0 +1,1370 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""ایستگاه — رابط گرافیکی گام‌به‌گام برای جذب، محاسبه، تصمیم و راستی‌آزمایی. + +هشت گام، هر گام یک کار روشن: + ۱) خوش‌آمد و بررسی سلامت + ۲) منبع داده (نمونه / دستی / زندهٔ واقعی) + راهنمای خرید داده + ۳) تنظیمات ریاضی و ریسک + ۴) خبر و هشدار (اختیاری) + ۵) اجرا و محاسبه + ۶) نتیجه و تصمیم (تأیید یا رد انسانی) + ۷) پس‌آزمایی روی دادهٔ تاریخ + ۸) بستهٔ تحویل شرکت (برای راستی‌آزمایی آن‌ها) + +قانون آهنین برنامه: هیچ سفارشی خودکار فرستاده نمی‌شود. تصمیم و مسئولیت با انسان است. +اجرای دستی برنامهٔ واقعی: python station.py +""" +from __future__ import annotations + +import csv +import hashlib +import json +import os +import queue +import shutil +import subprocess +import sys +import threading +import time +import traceback +import webbrowser +from datetime import datetime, timezone +from pathlib import Path + +VERSION = "0.1.0" +BASE = Path(__file__).resolve().parent +DATA = BASE / "data" +EXPORT = BASE / "export" +DEMO_HISTORY = BASE / "demo" / "history-demo.csv" +SNAPSHOT_FILE = DATA / "current-snapshot.json" +DASHBOARD_FILE = DATA / "dashboard.html" +BACKTEST_HTML = DATA / "backtest.html" +BACKTEST_CSV = DATA / "backtest.csv" +DESK_DIR = (BASE.parent / "desk").resolve() +KODAL_DIR = (BASE.parent / "kodal-alert").resolve() +TOOLS_DIR = (BASE.parent / "tools").resolve() +CREDIT = ("تهیه‌کننده: Masoud Mojarabian · https://www.instagram.com/Mojarabian.Art/ · " + "tel:+989126630554 · https://t.me/Mojarabian") + +for p in (str(BASE), str(DESK_DIR), str(KODAL_DIR), str(TOOLS_DIR)): + if p not in sys.path: + sys.path.insert(0, p) + +import datafeed # noqa: E402 +import backtest as bt # noqa: E402 + +try: + import desk as deskmod # noqa: E402 +except Exception as e: # pragma: no cover + deskmod = None # type: ignore + _DESK_IMPORT_ERROR = e + +try: + import kodal_alert as kodal # noqa: E402 +except Exception as e: # pragma: no cover + kodal = None # type: ignore + _KODAL_IMPORT_ERROR = e + +STEPS = [ + ("health", "خوش‌آمد و بررسی سلامت"), + ("data", "منبع داده"), + ("settings", "تنظیمات ریاضی و ریسک"), + ("news", "خبر و هشدار"), + ("run", "اجرا و محاسبه"), + ("decide", "نتیجه و تصمیم"), + ("backtest", "پس‌آزمایی روی تاریخ"), + ("bundle", "بستهٔ تحویل شرکت"), +] + +API_GUIDE_ROWS = [ + ("کدال (رسمی)", "اطلاعیه‌ها، صورت‌های مالی، افزایش سرمایه", "رایگان", + "بدون کلید؛ همین حالا در گام خبر فعال است", + "هیچ هزینه‌ای ندارد و همین امروز فعال می‌شود."), + ("tsetmc / مدیریت فناوری", "قیمت پایانی و ریزمعاملات سهام و آپشن", "رایگان ولی بی‌تعهد", + "بستهٔ پایتونی tsetmc-api یا خواندن مستقیم با قالب نشانی", + "قیمت پایه به‌روز می‌شود؛ ولی بدون تضمین و بدون پشتیبانی."), + ("سرویس دادهٔ خریدنی ایرانی", "قیمت زنده، ریزمعاملات، دادهٔ تاریخی", + "تقریبی: از چند صد هزار تومان در ماه — در سایت فروشنده تأیید کنید", + "کلید + قالب نشانی + مسیر JSON در همین گام", + "قیمت پایه هر ۳۰ ثانیه تازه می‌شود، تازگی داده سبز می‌ماند، و پس‌آزمایی روی داد تاریخ واقعی ممکن می‌شود. وجه تضمین همچنان دستی است."), + ("دادهٔ تاریخی برای پس‌آزمایی", "سری زمانی قیمت آپشن، آتی و گواهی سپرده", "معمولاً داخل همان بستهٔ خریدنی", + "پروندهٔ CSV با ستون‌های قالب پس‌آزمایی", + "می‌توانید نرخ برد و خطای پیش‌بینی موتور را با عدد واقعی به شرکت نشان دهید."), +] + +CHECK_ITEMS = [ + ("پایتون", lambda: f"نسخهٔ {sys.version.split()[0]}"), + ("موتور ریاضی", lambda: str(TOOLS_DIR / "derivatives_scout.py")), + ("میز معاملات", lambda: str(DESK_DIR / "desk.py")), + ("دیده‌بان کدال", lambda: str(KODAL_DIR / "kodal_alert.py")), + ("اسنپ‌شات نمونه", lambda: str(DESK_DIR / "market-demo.json")), + ("تاریخ نمونه", lambda: str(DEMO_HISTORY)), +] + + +def now_fa() -> str: + return datetime.now().strftime("%Y-%m-%d %H:%M") + + +# ---------------------------------------------------------------- بررسی سلامت +def health_report() -> tuple[bool, list[tuple[str, bool, str]]]: + items: list[tuple[str, bool, str]] = [] + items.append(("پایتون", True, f"نسخهٔ {sys.version.split()[0]}")) + try: + import tkinter # noqa: F401 + items.append(("کتابخانهٔ گرافیکی tkinter", True, "نصب است")) + except Exception as e: + items.append(("کتابخانهٔ گرافیکی tkinter", False, f"نصب نیست: {e} — روی ویندوز پایتون را با گزینهٔ tcl/tk نصب کنید")) + if deskmod is not None: + items.append(("میز معاملات", True, f"بارگذاری شد · نسخهٔ {getattr(deskmod, 'VERSION', '?')}")) + try: + scout = deskmod.load_scout() + items.append(("موتور ریاضی مشتقه", True, + f"بارگذاری شد · توابع: {', '.join(n for n in ('box_spread','tabei_min_yield','basis_opportunity') if hasattr(scout, n))}")) + except Exception as e: + items.append(("موتور ریاضی مشتقه", False, f"بارگذاری نشد: {e}")) + else: + items.append(("میز معاملات", False, f"بارگذاری نشد: {_DESK_IMPORT_ERROR}")) + if kodal is not None: + items.append(("دیده‌بان کدال", True, f"بارگذاری شد · نسخهٔ {getattr(kodal, 'VERSION', '?')}")) + else: + items.append(("دیده‌بان کدال", False, f"بارگذاری نشد: {_KODAL_IMPORT_ERROR}")) + for name, path in (("اسنپ‌شات نمونه", DESK_DIR / "market-demo.json"), + ("تاریخ نمونهٔ پس‌آزمایی", DEMO_HISTORY), + ("پایگاه‌دادهٔ نمونهٔ کدال", KODAL_DIR / "data" / "demo.sqlite3")): + items.append((name, Path(path).exists(), str(path))) + ok = all(flag for _, flag, _ in items if "نمونهٔ کدال" not in _) + return ok, items + + +# ---------------------------------------------------------------- بستهٔ تحویل شرکت +def build_method_html(state: dict) -> str: + """سند روش کار؛ همان چیزی که شرکت برای راستی‌آزمایی می‌خواند.""" + snap = state.get("snapshot") + rules = state.get("rules", {}) + src_label = getattr(snap, "source_label", "—") + freshness = getattr(snap, "freshness_label", "—") + rows = getattr(snap, "rows", []) + messages = getattr(snap, "messages", []) + return f""" +سند روش کار — ایستگاه تصمیم مشتقه + +

    سند روش کار — ایستگاه تصمیم مشتقه

    +
    نسخهٔ {VERSION} · تاریخ ساخت سند: {now_fa()}
    +
    +
    این سند چه چیزی را اثبات نمی‌کند: هیچ سود تضمینی در این سیستم وجود ندارد. +خروجی برنامه «پیشنهاد و هشدار» است، نه دستور معامله. تصمیم و مسئولیت حقوقی آن با کاربر انسانی است. +دلیل فنی: طبق ابلاغیهٔ مهر ۱۳۹۹ سازمان بورس، معاملات الگوریتمی خودکار در بورس و فرابورس ایران «تا اطلاع ثانوی» مجاز نیست.
    + +

    ۱. سیستم چه می‌کند

    +
      +
    1. اسنپ‌شات بازار را می‌خواند (قیمت پایه، زنجیرهٔ آپشن، آتی، اوراق تبعی، وجه تضمین).
    2. +
    3. هر ردیف را روی موتور ریاضی می‌گذارد: ارزش منصفانه، نرخ تلویحی، تساوی پوت‌کال، باکس‌اسپرد، بازده تبعی، پوشش‌داده‌شده.
    4. +
    5. هزینه‌ها را کسر می‌کند: کارمزد معاملهٔ آپشن ۰٫۱۰۳٪ هر طرف، کارمزد اعمال ۰٫۰۵٪، مالیات تسویهٔ فیزیکی ۰٫۵٪، کارمزد سهام ۰٫۴۶۴٪ خرید و ۰٫۹۶۴٪ فروش، کارمزد صندوق کالایی ۰٫۱۲٪ هر طرف.
    6. +
    7. نتیجه را با «نرخ سد» مقایسه می‌کند (بازده مؤثر صندوق درآمد ثابت همان روز).
    8. +
    9. دروازه‌های ریسک را اعمال و اندازهٔ هر موقعیت را از بودجهٔ وجه تضمین درمی‌آورد.
    10. +
    11. هشدارهای کدال را به‌عنوان زمینه کنار سیگنال می‌گذارد (خبر به‌تنهایی سیگنال نیست).
    12. +
    + +

    ۲. وضعیت داده در این بسته

    + + + +
    منبع داده{src_label}
    تازگی داده{freshness}
    تعداد ردیف محاسبه‌شده{len(rows)}
    پیام‌های لایهٔ داده{' · '.join(messages) if messages else '—'}
    + +

    ۳. قواعد ریسک فعال (همان‌ها که در محاسبه اجرا شد)

    + + + + + + + + + + + +
    سرمایهٔ مبنا{rules.get('capital', 0):,.0f}
    نرخ سد (سالانه){rules.get('hurdle', 0) * 100:.2f} درصد
    کف حاشیهٔ راهبردهای آربیتراژی{rules.get('min_edge_arbitrage_pct')} واحد درصد
    کف حاشیهٔ راهبردهای اهرمی{rules.get('min_edge_leveraged_pct')} واحد درصد
    سقف کل وجه تضمین{rules.get('max_margin_pct', 0) * 100:.0f} درصد سرمایه
    سقف هر موقعیت{rules.get('max_position_pct', 0) * 100:.0f} درصد بودجهٔ وجه تضمین
    سقف موقعیت‌های هم‌زمان{rules.get('max_positions')}
    کف نقدشوندگی{rules.get('min_liquidity_contracts_per_day')} قرارداد در روز
    سقف اسپرد خرید‌وفروش{rules.get('max_spread_pct', 0) * 100:.1f} درصد
    سقف باورپذیری بازده{rules.get('max_plausible_arb_pct'):,.0f} درصد (آربیتراژ) و {rules.get('max_plausible_lev_pct'):,.0f} درصد (اهمی)
    + +

    ۴. راستی‌آزمایی توسط شما (هفت گام)

    +
      +
    1. در همین رایانه، پوشهٔ میز معاملات را باز کنید و python desk.py list را اجرا کنید؛ باید همان سیگنال‌های فایل 02-signals.csv را ببینید.
    2. +
    3. python desk.py packet <شناسه> را اجرا کنید؛ باید همان متن 04-packets.txt بیرون بیاید.
    4. +
    5. یک سیگنال را با ماشین‌حساب دستی بازبینی کنید: فرمول‌ها در بخش ۵ همین سند آمده است.
    6. +
    7. پروندهٔ 05-backtest.html را باز کنید و ببینید موتور روی دادهٔ تاریخ چه نرخ برد و چه خطای پیش‌بینی‌ای داشته است.
    8. +
    9. یک روز را با اعداد واقعی کارگزاری خودتان عوض کنید و بگذارید سیستم دوباره محاسبه کند؛ خروجی باید با محاسبهٔ دستی شما بخواند.
    10. +
    11. نرخ سد را با بازده مؤثر صندوق درآمد ثابت همان روز عوض کنید؛ ببینید کدام سیگنال‌ها از دروازه رد می‌شوند.
    12. +
    13. هر اختلافی دیدید، همان عدد و همان ردیف را برگردانید؛ رفع آن، بخشی از تحویل است.
    14. +
    + +

    ۵. فرمول‌های به‌کاررفته

    +
      +
    • ارزش منصفانهٔ آتی: F = S × exp((r + u − y) × T)
    • +
    • نرخ تلویحی: r = ln(F / S) / T
    • +
    • تساوی پوت‌کال: C − P = S − K × exp(−rT)
    • +
    • باکس‌اسپرد: دریافتی قطعی = K₂ − K₁ منهای بدهی اولیه و کارمزدها
    • +
    • اوراق تبعی: بازده = (قیمت اعمال پس از کارمزد فروش − (قیمت سهم پس از کارمزد خرید + قیمت پوت)) ÷ همان هزینهٔ کل
    • +
    • پوشش‌داده‌شده: بازده پرمیوم = پرمیوم پس از کارمزد ÷ بهای سهم پس از کارمزد
    • +
    • سالانه‌سازی: (۱ + بازده دوره)^(۳۶۵ ÷ روز) − ۱
    • +
    + +

    ۶. محدودیت‌هایی که باید بدانید

    +
      +
    • وجه تضمین و مشخصات قرارداد از سامانهٔ کارگزاری می‌آید؛ برنامه آن را حدس نمی‌زند.
    • +
    • در ایران فروش استقراضی وجود ندارد؛ پس نیمهٔ دوم بعضی آربیتراژها (reverse conversion) عملاً بسته است و برنامه آن را رد می‌کند.
    • +
    • ریسک اجرا (نگرفتن پاها هم‌زمان)، توقف نماد، و نکول ناشر در محاسبهٔ ریاضی نیست و فقط در دروازه‌ها هشدار داده شده است.
    • +
    • دادهٔ نمونه‌ای که همراه برنامه است ساختگی است؛ برای نمایش کارکرد است و برای ارائه به شرکت کافی نیست.
    • +
    + +
    ساختهٔ ایستگاه نسخهٔ {VERSION} · {CREDIT}
    +
    """ + + +def signals_csv(db_path: Path, path: Path) -> int: + """همهٔ سیگنال‌های پایگاه‌داده را در CSV می‌ریزد؛ اگر پایگاه‌داده نبود، صفر.""" + if deskmod is None: + return 0 + try: + d = deskmod.Desk(db_path) + except Exception: + return 0 + sigs = d.all(limit=1000) + cols = ["sid", "ts", "symbol", "kind", "name", "annualized_pct", "score_pp", "go", + "status", "contracts", "unit", "margin_locked", "gate_note"] + with path.open("w", encoding="utf-8-sig", newline="") as f: + w = csv.DictWriter(f, fieldnames=cols) + w.writeheader() + for s in sigs: + w.writerow({"sid": s.sid, "ts": "", "symbol": s.symbol, "kind": s.kind, + "name": deskmod.KIND_LABELS.get(s.kind, s.kind), + "annualized_pct": s.annualized_pct, "score_pp": s.score_pp, + "go": int(s.go), "status": s.status, "contracts": s.contracts, + "unit": s.unit, "margin_locked": round(s.margin_locked, 0), + "gate_note": s.gate_note}) + return len(sigs) + + +def _count(db_path: Path, status: str) -> int: + if deskmod is None: + return 0 + try: + return len(deskmod.Desk(db_path).all(status, 500)) + except Exception: + return 0 + + + +def _usage_block() -> dict: + """خلاصهٔ گواهی استفادهٔ موفق برای مانیفست بسته (بدون شمارهٔ حساب و بدون عدد مالی).""" + try: + import usage_meter as usagemod + s = usagemod.summary() + return {"success_total": s.get("success_total"), "active_days": s.get("active_days"), + "today": s.get("today"), "chain_ok": s.get("chain_ok"), + "broken_at": s.get("broken_at"), "kept_local": s.get("kept_local"), + "detail": ("دفتر استفادهٔ موفق فقط روی همین رایانه است و هیچ عدد مالی در آن نیست؛ " + "برای ساخت گواهی دواِمضا: پنل مدیریت ← گواهی استفادهٔ موفق.")} + except Exception as e: + return {"error": f"{type(e).__name__}: {e}"} + + +def build_bundle(state: dict, out_dir: Path | None = None, evidence_dir: Path | None = None) -> Path: + """بستهٔ راستی‌آزمایی برای شرکت: گزارش، سیگنال‌ها، بسته‌های سفارش، روش کار، پس‌آزمایی، شاهدها و مانیفست. + + شاهدها = کارنامهٔ آزمون، برگهٔ آزمون سرمایه‌گذار و پروندهٔ سرمایه‌گذار (اگر ساخته شده باشند). + """ + stamp = datetime.now().strftime("%Y%m%d-%H%M") + out = Path(out_dir) if out_dir else EXPORT / f"bundle-{stamp}" + out.mkdir(parents=True, exist_ok=True) + + files: list[dict] = [] + admin_notes: list[str] = [] + if not DASHBOARD_FILE.exists() and deskmod is not None: + # نصب تازه: داشبورد هنوز ساخته نشده. خودمان می‌سازیم تا چک‌لیست بسته به پروندهٔ نبوده + # اشاره نکند (حتی اگر خالی باشد، صریح می‌گوید «هنوز تصمیمی ثبت نشده»). + try: + cfg = dict(getattr(deskmod, "DEFAULT_CONFIG", {})) + cfg.update({k: v for k, v in (state.get("rules") or {}).items() if k in cfg} or {}) + deskmod.build_dashboard(deskmod.Desk(), cfg, DASHBOARD_FILE) + admin_notes.append("داشبورد تازه ساخته شد (هنوز تصمیمی ثبت نشده بود) و در بسته آمد.") + except Exception as e: + admin_notes.append(f"داشبورد ساخته نشد ({type(e).__name__}: {e})؛ در گام ۵ " + "«نمایش داشبورد» را بزنید و بسته را دوباره بگیرید.") + if DASHBOARD_FILE.exists(): + shutil.copy2(DASHBOARD_FILE, out / "01-dashboard.html") + files.append({"file": "01-dashboard.html", "desc": "داشبورد تصمیم‌ها (تأیید، رد، انتظار تأیید)"}) + + db_path = (DESK_DIR / "data" / "desk.sqlite3") + n = signals_csv(db_path, out / "02-signals.csv") + files.append({"file": "02-signals.csv", "desc": f"فهرست کامل {n} سیگنال با دلیل دروازه‌ها"}) + + (out / "03-method.html").write_text(build_method_html(state), encoding="utf-8") + files.append({"file": "03-method.html", "desc": "سند روش کار و چک‌لیست راستی‌آزمایی شرکت"}) + + packets: list[str] = [] + if deskmod is not None: + try: + d = deskmod.Desk(db_path) + for s in d.all("approved", 200) + d.all("pending", 200): + packets.append(deskmod.order_packet(s)) + except Exception as e: + packets.append(f"خواندن پایگاه‌داده ممکن نشد: {type(e).__name__}: {e}") + (out / "04-packets.txt").write_text("\n\n" + "=" * 70 + "\n\n".join(packets) if packets + else "بستهٔ سفارشی تأیید نشده است.", encoding="utf-8") + files.append({"file": "04-packets.txt", "desc": "بستهٔ سفارش سیگنال‌های تأییدشده و منتظر تأیید"}) + + if state.get("backtest_result"): + if BACKTEST_HTML.exists(): + shutil.copy2(BACKTEST_HTML, out / "05-backtest.html") + files.append({"file": "05-backtest.html", "desc": "گزارش پس‌آزمایی روی دادهٔ تاریخ"}) + if BACKTEST_CSV.exists(): + shutil.copy2(BACKTEST_CSV, out / "06-backtest-rows.csv") + files.append({"file": "06-backtest-rows.csv", "desc": "سطر به سطر نتیجهٔ پس‌آزمایی"}) + + # اجازه‌نامه و گواهی استفاده: اگر صادر شده‌اند، سند چاپی‌شان تازه ساخته می‌شود تا در بسته بیاید + ev_for_doc = Path(evidence_dir) if evidence_dir else DATA + client_name = "________________" + try: + import license as licmod + if licmod.read_license(): + client_name = str((licmod.read_license() or {}).get("client") or client_name) + licmod.build_document(path=ev_for_doc / "license-doc.md", + html_path=ev_for_doc / "license-doc.html") + admin_notes.append("سند چاپی اجازه‌نامه از پروندهٔ فعلی ساخته شد.") + else: + admin_notes.append("اجازه‌نامه‌ای صادر نشده؛ سند مجوز در بسته نیست. " + "از پنل مدیریت (بخش «مجوز دسترسی») بسازید و بسته را دوباره بگیرید.") + except Exception as e: + admin_notes.append(f"ساخت سند مجوز ممکن نشد: {type(e).__name__}: {e}") + + # گواهی استفاده هم تازه ساخته شود تا بسته، عددهای لحظهٔ ساخت را نشان دهد (نه فایل قدیمی) + try: + import usage_meter as usagemod + h, m = usagemod.build_statement(usagemod.summary(), client=client_name, + html_path=ev_for_doc / "usage-statement.html", + md_path=ev_for_doc / "usage-statement.md") + admin_notes.append("گواهی استفاده از دفتر همین رایانه ساخته شد.") + except Exception as e: + admin_notes.append(f"گواهی استفاده ساخته نشد ({type(e).__name__}: {e})؛ " + "در پنل مدیریت بخش «گواهی استفادهٔ موفق» بسازید.") + + # شاهدهای آزمون و پرونده: اگر ساخته شده‌اند، داخل بسته هم می‌روند تا شرکت خودش بازبینی کند + evidence: list[dict] = [] + ev_dir = Path(evidence_dir) if evidence_dir else DATA + for src_name, out_name, desc in ( + ("selftest-report.html", "08-selftest-report.html", + "کارنامهٔ آزمون ۱۰ دقیقه‌ای: هر مورد دو بار حساب شده، موتور و حساب دستی مستقل"), + ("exam-sheet.html", "09-exam-sheet.html", + "برگهٔ آزمون سرمایه‌گذار: اول حدس خودش، بعد پاسخ و راه چک با ماشین‌حساب"), + ("investor-dossier.html", "10-investor-dossier.html", + "پروندهٔ سرمایه‌گذار: قواعد، سه شاهد، محدودیت‌ها، و اثر انگشت پرونده‌ها"), + ("investor-dossier.md", "11-investor-dossier.md", + "نسخهٔ متنی پروندهٔ سرمایه‌گذار برای ایمیل"), + ("signal-verdict.html", "12-signal-verdict.html", + "برگهٔ داوری سیگنال بیرونی: می‌ماند/می‌افتد، نقطهٔ برگشت و فاصله تا مارجین‌کال"), + ("investor-blind-test.html", "13-blind-test-sheet.html", + "برگهٔ آزمون کور سرمایه‌گذار با جای امضا و کلید زنجیره"), + ("diagnostic-report.html", "14-diagnostic-report.html", + "گزارش عیب‌یابی: نسخه‌ها، سلامت اجزا، وضعیت اتصال (برای پشتیبانی)"), + ("license-doc.html", "15-license-doc.html", + "سند چاپی اجازه‌نامهٔ دسترسی: نام مشتری، مدت، امضای چکسام و جای امضای دو طرف"), + ("license-doc.md", "16-license-doc.md", "نسخهٔ متنی اجازه‌نامه برای ایمیل"), + ("usage-statement.html", "17-usage-statement.html", + "گواهی استفادهٔ موفق: چه کاری چند بار انجام شد، با اثر انگشت زنجیرهٔ دفتر"), + ("usage-statement.md", "18-usage-statement.md", "نسخهٔ متنی گواهی استفاده برای ایمیل")): + src = ev_dir / src_name + if src.exists(): + shutil.copy2(src, out / out_name) + data = src.read_bytes() + files.append({"file": out_name, "desc": desc}) + evidence.append({"file": out_name, "bytes": len(data), + "sha256": hashlib.sha256(data).hexdigest()[:16], + "built_at": datetime.fromtimestamp(src.stat().st_mtime).strftime("%Y-%m-%d %H:%M")}) + + access = None + try: + import license as licmod # noqa: A004 + access = licmod.verify() + except Exception as e: # نبود اجازه‌نامه، خطا نیست + access = {"state": "نامعلوم", "ok": True, "detail": f"{type(e).__name__}: {e}"} + + manifest = { + "built_at": datetime.now(timezone.utc).isoformat(timespec="seconds"), + "station_version": VERSION, + "data_mode": state.get("data_mode"), + "data_source_label": getattr(state.get("snapshot"), "source_label", "—"), + "data_freshness": getattr(state.get("snapshot"), "freshness_label", "—"), + "rows": len(getattr(state.get("snapshot"), "rows", [])), + "rules": state.get("rules", {}), + "signals": {"total": n, "pending": _count(db_path, "pending"), "approved": _count(db_path, "approved")}, + "backtest_summary": (state.get("backtest_result") or {}).get("summary"), + "files": files, + "evidence": evidence, + "access": access, + "usage_certificate": _usage_block(), + "admin_notes": admin_notes, + "limitations": ["هیچ سفارش خودکاری ارسال نمی‌شود", + "هیچ سود تضمینی وجود ندارد", + "وجه تضمین و مشخصات قرارداد باید از کارگزاری تأیید شود"], + "credit": CREDIT, + } + (out / "07-manifest.json").write_text(json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8") + files.append({"file": "07-manifest.json", "desc": "شناسنامهٔ فنی بسته (نسخه‌ها، پارامترها، شمارش‌ها)"}) + + checklist = [ + "# چک‌لیست راستی‌آزمایی برای شرکت (پنج دقیقه)", + "", + "۱. `03-method.html` را باز کنید و بخش «راستی‌آزمایی توسط شما» را گام‌به‌گام اجرا کنید.", + "۲. `02-signals.csv` را با خروجی `python desk.py list` در پوشهٔ میز معاملات مقایسه کنید؛ باید یکی باشد.", + "۳. یک ردیف را با ماشین‌حساب دستی بازبینی کنید (فرمول‌ها در `03-method.html` بخش ۵).", + "۴. `05-backtest.html` را ببینید: نرخ برد، خطای مثبت کاذب، و خطای پیش‌بینی.", + "۵. `08-selftest-report.html` را ببینید و دو موردش را با ماشین‌حساب چک کنید؛ `09-exam-sheet.html` همین را برای پرسیدن از خودتان دارد.", + "۶. یک روز را با اعداد واقعی کارگزاری خودتان جایگزین کنید و بگذارید سیستم دوباره محاسبه کند.", + "۷. `07-manifest.json` را برای نسخه‌ها، پارامترها و اثر انگشت شاهدها ببینید.", + "۸. `10-investor-dossier.html` خلاصهٔ همهٔ این‌ها را در یک صفحه آورده است.", + "۹. `15-license-doc.html` و `17-usage-statement.html` را ببینید: مجوز دسترسی (با امضا) و " + "گواهی استفادهٔ موفق؛ هر دو با یک فرمان بازتولیدشدنی‌اند.", + "", + "یادآوری: خروجی این بسته «پیشنهاد و هشدار» است؛ هیچ سفارشی خودکار ارسال نشده و هیچ سود تضمینی وجود ندارد.", + "", + *[f"- {n}" for n in admin_notes], + ] + (out / "README-FA.md").write_text("\n".join(checklist), encoding="utf-8") + files.append({"file": "README-FA.md", "desc": "چک‌لیست راستی‌آزمایی"}) + + state["bundle_dir"] = out + return out + + +def open_path(path: Path) -> None: + """باز کردن پوشه یا پرونده با برنامهٔ پیش‌فرض سیستم.""" + try: + if sys.platform.startswith("win"): + os.startfile(str(path)) # type: ignore[attr-defined] + elif sys.platform == "darwin": + subprocess.Popen(["open", str(path)]) + else: + subprocess.Popen(["xdg-open", str(path)]) + except Exception: + pass + + +# ---------------------------------------------------------------- رابط گرافیکی +def import_tk(): + try: + import tkinter as tk + from tkinter import ttk, filedialog, messagebox + return tk, ttk, filedialog, messagebox + except Exception as e: # pragma: no cover + print("کتابخانهٔ گرافیکی tkinter نصب نیست:", e) + print("روی ویندوز: پایتون را از سایت رسمی با گزینهٔ «tcl/tk and IDLE» نصب کنید.") + print("روی لینوکس: sudo apt install python3-tk") + raise SystemExit(2) + + +class Station: + def __init__(self, root, tk, ttk, filedialog, messagebox): + self.tk, self.ttk, self.filedialog, self.messagebox = tk, ttk, filedialog, messagebox + self.root = root + self.queue: queue.Queue[tuple[str, object]] = queue.Queue() + self.frames: dict[int, object] = {} + self.index = 0 + self.state: dict = { + "data_mode": "sim", + "file_path": "", + "live_cfg": dict(datafeed.DEFAULT_LIVE_CONFIG), + "key": "", + "snapshot": None, + "rules": { + "capital": 20_000_000_000, "hurdle": 0.39, + "min_edge_arbitrage_pct": 3.0, "min_edge_leveraged_pct": 5.0, + "max_margin_pct": 0.20, "max_position_pct": 0.35, "max_positions": 3, + "min_liquidity_contracts_per_day": 20, "max_spread_pct": 0.03, + "max_plausible_arb_pct": 250.0, "max_plausible_lev_pct": 400.0, + }, + "use_kodal": True, + "kodal_db": str(KODAL_DIR / "data" / "demo.sqlite3"), + "backtest_result": None, + "bundle_dir": None, + } + # اتصالی که در رابط مرورگری ذخیره کرده‌اید، در نسخهٔ دسکتاپ هم خودکار فعال می‌شود. + try: + import connections as _conn + _active = _conn.active_or_none() + except Exception: + _active = None + if _active: + self.state["data_mode"] = "live" + self.state["live_cfg"] = _active["live_cfg"] + self.state["key"] = _active["key"] + self.font = self.pick_font() + self.build_window() + self.show_step(0) + self.root.after(150, self.drain_queue) + + # ---------- پایه‌ها + def pick_font(self) -> tuple[str, int]: + try: + from tkinter import font as tkfont + families = set(tkfont.families()) + for name in ("Tahoma", "Segoe UI", "Vazirmatn", "Noto Naskh Arabic", "DejaVu Sans"): + if name in families: + return (name, 10) + except Exception: + pass + return ("TkDefaultFont", 10) + + def f(self, size: int = 10, bold: bool = False) -> tuple: + return (self.font[0], size, "bold") if bold else (self.font[0], size) + + def build_window(self) -> None: + self.root.title(f"ایستگاه تصمیم مشتقه — نسخهٔ {VERSION}") + self.root.geometry("1180x760") + self.root.minsize(980, 640) + + head = self.tk.Frame(self.root, bg="#0b3d2e", height=64) + head.pack(side="top", fill="x") + self.tk.Label(head, text="ایستگاه تصمیم مشتقه", bg="#0b3d2e", fg="white", + font=self.f(15, True)).pack(anchor="e", padx=14, pady=(8, 0)) + self.tk.Label(head, text="محاسبه · هشدار · تأیید انسانی · بستهٔ راستی‌آزمایی برای شرکت", + bg="#0b3d2e", fg="#cfe6dd", font=self.f(9)).pack(anchor="e", padx=14) + self.badge = self.tk.Label(head, text="منبع داده: تنظیم نشده", bg="#0b3d2e", fg="#ffe08a", + font=self.f(9, True)) + self.badge.pack(anchor="w", padx=14, pady=(0, 8)) + + body = self.tk.Frame(self.root) + body.pack(side="top", fill="both", expand=True) + + side = self.tk.Frame(body, bg="#f0f2f5", width=250) + side.pack(side="right", fill="y") + self.tk.Label(side, text="گام‌ها", bg="#f0f2f5", font=self.f(11, True)).pack(anchor="e", padx=12, pady=(10, 6)) + self.step_labels: list = [] + for i, (_, title) in enumerate(STEPS): + lbl = self.tk.Label(side, text=f"{i + 1}. {title}", bg="#f0f2f5", fg="#333", + font=self.f(10), anchor="e", justify="right", wraplength=225) + lbl.pack(anchor="e", fill="x", padx=10, pady=2) + lbl.bind("", lambda _e, idx=i: self.show_step(idx)) + self.step_labels.append(lbl) + + self.content = self.tk.Frame(body, bg="white") + self.content.pack(side="left", fill="both", expand=True) + + foot = self.tk.Frame(self.root, bg="#eef2f7", height=46) + foot.pack(side="bottom", fill="x") + self.btn_next = self.ttk.Button(foot, text="گام بعد ▶", command=self.next_step) + self.btn_next.pack(side="left", padx=10, pady=8) + self.btn_back = self.ttk.Button(foot, text="◀ گام قبل", command=self.prev_step) + self.btn_back.pack(side="left", padx=4, pady=8) + self.status = self.tk.Label(foot, text="آماده", bg="#eef2f7", fg="#333", font=self.f(10, True)) + self.status.pack(side="right", padx=14) + + # ---------- ناوبری + @property + def key(self) -> str: + return STEPS[self.index][0] + + def show_step(self, index: int) -> None: + """گام‌ها یک بار ساخته و نگه داشته می‌شوند؛ برای نمایش، فقط جابه‌جا می‌شوند.""" + index = max(0, min(index, len(STEPS) - 1)) + self.index = index + if index not in self.frames: + builder = getattr(self, f"build_{STEPS[index][0]}") + self.frames[index] = builder(self.content) + for i, frame in self.frames.items(): + try: + if i == index: + frame.pack(fill="both", expand=True) + else: + frame.pack_forget() + except Exception: + pass + for i, lbl in enumerate(self.step_labels): + lbl.configure(bg="#d7e6df" if i == index else "#f0f2f5", + font=self.f(10, True) if i == index else self.f(10)) + self.btn_back.configure(state="normal" if index > 0 else "disabled") + self.btn_next.configure(text="پایان" if index == len(STEPS) - 1 else "گام بعد ▶") + self.status.configure(text=f"گام {index + 1} از {len(STEPS)}: {STEPS[index][1]}") + + def next_step(self) -> None: + self.show_step(self.index + 1 if self.index < len(STEPS) - 1 else self.index) + + def prev_step(self) -> None: + self.show_step(self.index - 1) + + # ---------- رشته و وظیفه‌های پس‌زمینه + def log_box(self, parent, height: int = 12): + frame = self.tk.Frame(parent, bg="white") + text = self.tk.Text(frame, height=height, font=("Consolas", 9), bg="#0f172a", fg="#d7e6dd", + wrap="word", padx=8, pady=6) + text.pack(side="left", fill="both", expand=True) + sb = self.ttk.Scrollbar(frame, command=text.yview) + sb.pack(side="right", fill="y") + text.configure(yscrollcommand=sb.set, state="disabled") + frame.pack(fill="both", expand=True, pady=6) + return text + + def push(self, text: str) -> None: + self.queue.put(("log", text)) + + def drain_queue(self) -> None: + try: + while True: + kind, payload = self.queue.get_nowait() + if kind == "log": + for box in self.frames.values(): + for widget in getattr(box, "winfo_children", lambda: [])(): + self.append_log_deep(widget, str(payload)) + self.status.configure(text=str(payload)[:110]) + elif kind == "done": + callback = payload + if callable(callback): + callback() + except queue.Empty: + pass + self.root.after(150, self.drain_queue) + + def append_log_deep(self, widget, text: str) -> None: + try: + if not widget.winfo_exists(): + return + if isinstance(widget, self.tk.Text): + widget.configure(state="normal") + widget.insert("end", text + "\n") + widget.see("end") + widget.configure(state="disabled") + for child in widget.winfo_children(): + self.append_log_deep(child, text) + except Exception: + return + + def run_async(self, func, on_done=None) -> None: + def worker(): + try: + result = func() + self.queue.put(("done", (lambda r=result: on_done(r)) if on_done else None)) + except Exception as e: + self.queue.put(("log", f"خطا: {type(e).__name__}: {e}")) + self.queue.put(("log", traceback.format_exc(limit=3))) + self.queue.put(("done", None)) + threading.Thread(target=worker, daemon=True).start() + + def card(self, parent, title: str, keys: list[tuple[str, str]]): + box = self.ttk.LabelFrame(parent, text=title, padding=8) + box.pack(fill="x", pady=6) + box.columnconfigure(1, weight=1) + entries = {} + for i, (label, key) in enumerate(keys): + self.tk.Label(box, text=label, font=self.f(10)).grid(row=i, column=0, sticky="e", padx=4, pady=3) + var = self.tk.StringVar(value=str(self.state["rules"].get(key, ""))) + ent = self.ttk.Entry(box, textvariable=var, width=18) + ent.grid(row=i, column=1, sticky="e", padx=4, pady=3) + entries[key] = var + return box, entries + + # ---------- گام ۱ + def build_health(self, parent): + frame = self.tk.Frame(parent, bg="white") + frame.pack(fill="both", expand=True) + self.tk.Label(frame, text="۱. خوش‌آمد و بررسی سلامت", bg="white", font=self.f(14, True)).pack(anchor="e", padx=14, pady=(12, 4)) + intro = ("این ایستگاه به شما می‌گوید «کجا تفاوت ریاضی قیمت‌ها با نرخ سد از حاشیهٔ اطمینان عبور می‌کند»،\n" + "هشدارهای کدال را کنار همان سیگنال می‌گذارد، اندازهٔ هر موقعیت را از بودجهٔ وجه تضمین درمی‌آورد،\n" + "و در پایان یک بستهٔ راستی‌آزمایی برای شرکت می‌سازد.\n\n" + "قاعدهٔ خودِ ایستگاه: سفارشی خودکار به کارگزاری فرستاده نمی‌شود و هیچ سودی تضمین نمی‌شود؛\n" + "خروجی، «عدد و دلیل» است و تصمیم دستِ کاربر می‌ماند.\n\n" + "دولوپر: مهندس مسعود مجربیان · همراه: 09126630554 · Telegram: [Mojarabian](https://t.me/Mojarabian) · Instagram: [Mojarabian.Art](https://instagram.com/Mojarabian.Art)") + self.tk.Label(frame, text=intro, bg="white", justify="right", font=self.f(10)).pack(anchor="e", padx=16) + self.ttk.Button(frame, text="بررسی سلامت برنامه", command=self.do_health).pack(anchor="e", padx=16, pady=8) + self.log_box(frame, height=14) + return frame + + def do_health(self) -> None: + self.push("در حال بررسی اجزای برنامه…") + ok, items = health_report() + for name, flag, note in items: + self.push(("✓ " if flag else "✗ ") + f"{name}: {note}") + passed = len([1 for _, flag, _ in items if flag]) + self.push(f"نتیجه: {passed} از {len(items)} بررسی موفق." + ("" if ok else " موارد ناقص را رفع کنید یا به من بگویید.")) + + # ---------- گام ۲ + def build_data(self, parent): + frame = self.tk.Frame(parent, bg="white") + frame.pack(fill="both", expand=True) + self.tk.Label(frame, text="۲. منبع داده", bg="white", font=self.f(14, True)).pack(anchor="e", padx=14, pady=(12, 4)) + self.tk.Label(frame, text="یکی از سه مسیر را انتخاب کنید. «زندهٔ واقعی» یعنی قیمت‌ها خودکار به‌روز می‌شوند؛\n" + "اما تا کلید نخریده‌اید، با دادهٔ نمونه یا پروندهٔ دستی هم می‌توانید تمام گام‌ها را ببینید.\n" + "برای همهٔ حالت‌ها، وجه تضمین و مشخصات قرارداد از سامانهٔ کارگزاری خودتان می‌آید.", + bg="white", justify="right", font=self.f(10)).pack(anchor="e", padx=16) + + self.mode_var = self.tk.StringVar(value=self.state["data_mode"]) + row = self.tk.Frame(frame, bg="white") + row.pack(anchor="e", fill="x", padx=16, pady=4) + for value, label in (("sim", "دادهٔ نمونهٔ همراه برنامه"), ("file", "پروندهٔ دستی JSON (بدون هزینه)"), + ("live", "دادهٔ زندهٔ واقعی (سرویس خریدنی)")): + self.ttk.Radiobutton(row, text=label, value=value, variable=self.mode_var, + command=self.on_mode_change).pack(side="right", padx=8) + + self.mode_text = self.tk.Text(frame, height=5, wrap="word", font=self.f(10), bg="#f8fafc", padx=8, pady=6) + self.mode_text.pack(fill="x", padx=16, pady=6) + self.mode_text.configure(state="disabled") + + self.file_card = self.ttk.LabelFrame(frame, text="پروندهٔ اسنپ‌شات (برای حالت دستی و پایهٔ حالت زنده)", padding=8) + self.file_card.pack(fill="x", padx=16, pady=4) + self.file_var = self.tk.StringVar(value=self.state.get("file_path", "")) + self.ttk.Entry(self.file_card, textvariable=self.file_var, width=64).pack(side="right", padx=4) + self.ttk.Button(self.file_card, text="انتخاب پرونده…", command=self.pick_file).pack(side="right", padx=4) + self.ttk.Button(self.file_card, text="ساخت قالب نمونه", command=self.make_template).pack(side="right", padx=4) + + self.live_card = self.ttk.LabelFrame(frame, text="اتصال سرویس دادهٔ زنده (کلید و قالب نشانی)", padding=8) + self.live_card.pack(fill="x", padx=16, pady=4) + self.live_vars = {} + rows = [("قالب نشانی سرویس", "url_template", 60, ""), + ("مسیر قیمت در پاسخ JSON", "json_path", 24, ""), + ("نام هدر کلید (اختیاری)", "key_header", 18, ""), + ("نام پارامتر کلید در نشانی", "key_query_name", 18, ""), + ("کلید سرویس (فقط در همین رایانه)", "key", 34, "*")] + for label, key, width, mask in rows: + line = self.tk.Frame(self.live_card, bg="white") + line.pack(fill="x", pady=2) + self.tk.Label(line, text=label, font=self.f(10), width=26, anchor="e").pack(side="right", padx=4) + var = self.tk.StringVar(value=str(self.state["live_cfg"].get(key, "") or self.state.get("key", ""))) + ent = self.ttk.Entry(line, textvariable=var, width=width, show=mask) + ent.pack(side="right", padx=4) + self.live_vars[key] = var + self.ttk.Button(self.live_card, text="آزمایش اتصال و خواندن قیمت زنده", + command=self.test_live).pack(anchor="e", padx=4, pady=6) + + self.api_tree = self.ttk.Treeview(frame, columns=("svc", "gives", "cost", "how"), show="headings", height=5) + for col, title, width in (("svc", "گزینه", 180), ("gives", "چه می‌دهد", 250), + ("cost", "هزینهٔ تقریبی (در سایت فروشنده تأیید کنید)", 300), + ("how", "نحوهٔ اتصال", 320)): + self.api_tree.heading(col, text=title) + self.api_tree.column(col, width=width, anchor="e") + for r in API_GUIDE_ROWS: + self.api_tree.insert("", "end", values=r) + self.api_tree.pack(fill="x", padx=16, pady=6) + + self.log_box(frame, height=8) + self.on_mode_change() + return frame + + def on_mode_change(self) -> None: + mode = self.mode_var.get() + self.state["data_mode"] = mode + card = datafeed.SOURCE_CARDS[mode] + text = (f"انتخاب شما: {card['label']}\n" + f"هزینه: {card['cost']}\n" + f"چه می‌دهد: {card['gives']}\n" + f"پس از اتصال، چه تغییر می‌کند: {card['after']}\n" + f"چگونه: {card['how']}") + self.mode_text.configure(state="normal") + self.mode_text.delete("1.0", "end") + self.mode_text.insert("1.0", text) + self.mode_text.configure(state="disabled") + + def pick_file(self) -> None: + path = self.filedialog.askopenfilename(title="انتخاب پروندهٔ اسنپ‌شات JSON", + filetypes=[("JSON", "*.json"), ("همه", "*.*")]) + if path: + self.file_var.set(path) + self.state["file_path"] = path + + def make_template(self) -> None: + p = datafeed.write_snapshot_template(DATA / "snapshot-template.json") + self.file_var.set(str(p)) + self.state["file_path"] = str(p) + self.messagebox.showinfo("قالب ساخته شد", f"قالب اسنپ‌شات ساخته شد:\n{p}\n\n" + "این پرونده را با اعداد واقعی کارگزاری خود پر کنید و همین مسیر را نگه دارید.") + + def test_live(self) -> None: + for key, var in self.live_vars.items(): + if key == "key": + self.state["key"] = var.get().strip() + else: + self.state["live_cfg"][key] = var.get().strip() + self.state["file_path"] = self.file_var.get().strip() or self.state.get("file_path", "") + self.push("آزمایش اتصال…" + (" (کلید وارد نشده؛ بدون کلید هم تلاش می‌شود)" if not self.state["key"] else "")) + + def work(): + snap = datafeed.build_snapshot("live", file_path=self.state["file_path"] or None, + live_cfg=self.state["live_cfg"], key=self.state["key"], + progress=self.push) + self.state["snapshot"] = snap + return snap + + def done(snap): + if snap is None: + return + self.push(f"وضعیت: {snap.status} · تازگی: {snap.freshness_label} · ردیف‌ها: {len(snap.rows)}") + for m in snap.messages: + self.push("· " + m) + self.update_badge() + if snap.status == "ok": + self.push("از این پس: قیمت پایه هر ۳۰ ثانیه از سرویس خوانده می‌شود و در گزارش، تازگی داده سبز می‌ماند.") + else: + self.push("راهنمای رفع: قالب نشانی و مسیر JSON را از مستندات فروشنده بردارید؛ " + "اگر عدد در پاسخ تغییر کند، فقط همین دو خط را عوض کنید.") + + self.run_async(work, done) + + def update_badge(self) -> None: + snap = self.state.get("snapshot") + if snap is None: + self.badge.configure(text="منبع داده: تنظیم نشده", fg="#ffe08a") + return + color = {"ok": "#9ae6b4", "partial": "#ffe08a", "failed": "#feb2b2"}.get(snap.status, "#ffe08a") + self.badge.configure(text=f"منبع: {snap.source_label} · تازگی: {snap.freshness_label} · " + f"ردیف: {len(snap.rows)}", fg=color) + + # ---------- گام ۳ + def build_settings(self, parent): + frame = self.tk.Frame(parent, bg="white") + frame.pack(fill="both", expand=True) + self.tk.Label(frame, text="۳. تنظیمات ریاضی و ریسک", bg="white", font=self.f(14, True)).pack(anchor="e", padx=14, pady=(12, 4)) + self.tk.Label(frame, text="این اعداد، تصمیم را عوض می‌کنند. پیش‌فرض‌ها محافظه‌کارانه انتخاب شده‌اند؛\n" + "هر عدد را بنا به شرایط خودتان عوض کنید و بعد دوباره محاسبه بگیرید.", + bg="white", justify="right", font=self.f(10)).pack(anchor="e", padx=16) + + box, self.rule_vars = self.card(frame, "پارامترهای اصلی", [ + ("سرمایه (ریال)", "capital"), + ("نرخ سد سالانه (اعشار، مثلاً 0.39)", "hurdle"), + ("کف حاشیهٔ آربیتراژ (واحد درصد)", "min_edge_arbitrage_pct"), + ("کف حاشیهٔ اهرمی (واحد درصد)", "min_edge_leveraged_pct"), + ]) + box2, self.rule_vars2 = self.card(frame, "دروازه‌های ریسک", [ + ("سقف کل وجه تضمین (اعشار، مثلاً 0.20)", "max_margin_pct"), + ("سقف هر موقعیت از بودجه (اعشار)", "max_position_pct"), + ("حداکثر موقعیت هم‌زمان", "max_positions"), + ("کف نقدشوندگی (قرارداد در روز)", "min_liquidity_contracts_per_day"), + ("سقف اسپرد (اعشار، مثلاً 0.03)", "max_spread_pct"), + ("سقف باورپذیری بازدهٔ آربیتراژ", "max_plausible_arb_pct"), + ("سقف باورپذیری بازدهٔ اهرمی", "max_plausible_lev_pct"), + ]) + hint = ("نرخ سد را از کجا بیاورم؟ از «بازده مؤثر سالانه» صندوق درآمد ثابت همان روز.\n" + "در شهریور ۱۴۰۵ این عدد حدود ۳۹ تا ۴۰ درصد بود. اگر نرخ سد را اشتباه بگذارید، همهٔ سیگنال‌ها اشتباه می‌شوند.") + self.tk.Label(frame, text=hint, bg="#f8fafc", justify="right", font=self.f(10)).pack(anchor="e", padx=16, pady=8) + + def save(): + for source in (self.rule_vars, self.rule_vars2): + for key, var in source.items(): + raw = var.get().strip().replace("٬", "").replace(",", "") + try: + self.state["rules"][key] = float(raw) if "." in raw else int(raw) + except ValueError: + self.messagebox.showwarning("عدد نامعتبر", f"مقدار «{key}» عدد نیست: {raw}") + return + self.push("تنظیمات ذخیره شد: " + json.dumps(self.state["rules"], ensure_ascii=False)) + self.ttk.Button(frame, text="ذخیرهٔ تنظیمات", command=save).pack(anchor="e", padx=16, pady=6) + self.log_box(frame, height=8) + return frame + + # ---------- گام ۴ + def build_news(self, parent): + frame = self.tk.Frame(parent, bg="white") + frame.pack(fill="both", expand=True) + self.tk.Label(frame, text="۴. خبر و هشدار (اختیاری)", bg="white", font=self.f(14, True)).pack(anchor="e", padx=14, pady=(12, 4)) + self.tk.Label(frame, text="خبر به‌تنهایی سیگنال نیست. کارکردش سه چیز است: زمینه، اولویت‌بندی، و ساختن\n" + "«کار بازبینی» برای نمادهایی که خبر مهم دارند ولی در اسنپ‌شات شما نیستند.", + bg="white", justify="right", font=self.f(10)).pack(anchor="e", padx=16) + self.use_kodal = self.tk.BooleanVar(value=self.state["use_kodal"]) + self.ttk.Checkbutton(frame, text="از هشدارهای دیده‌بان کدال استفاده کن", + variable=self.use_kodal, command=self.toggle_kodal).pack(anchor="e", padx=16, pady=4) + line = self.tk.Frame(frame, bg="white") + line.pack(fill="x", padx=16) + self.kodal_var = self.tk.StringVar(value=self.state["kodal_db"]) + self.ttk.Entry(line, textvariable=self.kodal_var, width=70).pack(side="right", padx=4) + self.ttk.Button(line, text="انتخاب پایگاه‌داده…", command=self.pick_kodal).pack(side="right", padx=4) + btns = self.tk.Frame(frame, bg="white") + btns.pack(anchor="e", padx=16, pady=6) + self.ttk.Button(btns, text="اجرای دیده‌بان روی دادهٔ نمونه", command=self.run_kodal_demo).pack(side="right", padx=4) + self.ttk.Button(btns, text="وارد کردن پروندهٔ اطلاعیه‌ها…", command=self.import_announcements).pack(side="right", padx=4) + self.ttk.Button(btns, text="نمایش هشدارهای فعلی", command=self.show_alerts).pack(side="right", padx=4) + self.log_box(frame, height=14) + return frame + + def toggle_kodal(self) -> None: + self.state["use_kodal"] = bool(self.use_kodal.get()) + + def pick_kodal(self) -> None: + path = self.filedialog.askopenfilename(title="پایگاه‌دادهٔ دیده‌بان کدال", + filetypes=[("SQLite", "*.sqlite3 *.db"), ("همه", "*.*")]) + if path: + self.kodal_var.set(path) + self.state["kodal_db"] = path + + def run_kodal_demo(self) -> None: + if kodal is None: + self.messagebox.showerror("دیده‌بان نیست", "پوشهٔ kodal-alert پیدا نشد.") + return + self.push("اجرای دیده‌بان روی دادهٔ نمونه…") + + def work(): + cfg = json.loads(json.dumps(kodal.DEFAULT_CONFIG, ensure_ascii=False)) + cfg["db_path"] = str(KODAL_DIR / "data" / "demo.sqlite3") + cfg["report_path"] = str(KODAL_DIR / "data" / "demo-report.html") + cfg["min_score_to_alert"] = 40 + store = kodal.Store(cfg["db_path"]) + items = kodal.run_pipeline(cfg, store, ["demo"]) + return items + + def done(items): + if not items: + self.push("خروجی نداشت؛ پوشهٔ نمونه را بررسی کنید.") + return + for it in items[:12]: + self.push(f"[{it.score}] {it.direction} · {it.category} · {it.symbol or '-'} · {it.title[:70]}") + self.state["kodal_db"] = str(KODAL_DIR / "data" / "demo.sqlite3") + self.kodal_var.set(self.state["kodal_db"]) + self.push(f"{len(items)} هشدار ساخته شد و در پایگاه‌داده ثبت شد.") + + self.run_async(work, done) + + def import_announcements(self) -> None: + path = self.filedialog.askopenfilename(title="پروندهٔ اطلاعیه‌ها (JSON یا CSV)", + filetypes=[("JSON/CSV", "*.json *.csv"), ("همه", "*.*")]) + if not path or kodal is None: + return + self.push(f"وارد کردن اطلاعیه‌ها از {path} …") + + def work(): + cfg = json.loads(json.dumps(kodal.DEFAULT_CONFIG, ensure_ascii=False)) + cfg["db_path"] = self.state["kodal_db"] + store = kodal.Store(cfg["db_path"]) + items = kodal.load_file_source(path, cfg) + fresh = [i for i in items if store.add(i)] + store.commit() + return fresh + + def done(fresh): + self.push(f"{len(fresh)} اطلاعیهٔ تازه ثبت شد.") + self.show_alerts() + + self.run_async(work, done) + + def show_alerts(self) -> None: + alerts = datafeed.read_alerts(self.state["kodal_db"], 55, 25) + if not alerts: + self.push("هشداری نیست (یا پایگاه‌داده خالی است).") + return + for a in alerts: + self.push(f"[{a['score']}] {a['direction']} · {a['category']} · {a['symbol'] or '-'} · {a['title'][:70]}") + + # ---------- گام ۵ + def build_run(self, parent): + frame = self.tk.Frame(parent, bg="white") + frame.pack(fill="both", expand=True) + self.tk.Label(frame, text="۵. اجرا و محاسبه", bg="white", font=self.f(14, True)).pack(anchor="e", padx=14, pady=(12, 4)) + self.tk.Label(frame, text="با یک دکمه: اسنپ‌شات خوانده می‌شود، موتور ریاضی هر ردیف را حساب می‌کند،\n" + "دروازه‌های ریسک اعمال می‌شوند، و داشبورد تصمیم ساخته می‌شود.", + bg="white", justify="right", font=self.f(10)).pack(anchor="e", padx=16) + self.progress = self.ttk.Progressbar(frame, mode="indeterminate") + self.progress.pack(fill="x", padx=16, pady=8) + row = self.tk.Frame(frame, bg="white") + row.pack(anchor="e", padx=16) + self.ttk.Button(row, text="شروع محاسبه", command=self.do_run).pack(side="right", padx=4) + self.ttk.Button(row, text="رفتن به گام نتیجه", command=lambda: self.show_step(5)).pack(side="right", padx=4) + self.ttk.Button(row, text="بازکردن داشبورد در مرورگر", + command=lambda: open_path(DASHBOARD_FILE)).pack(side="right", padx=4) + self.log_box(frame, height=16) + return frame + + def materialize_snapshot(self, snap) -> Path: + rows = [] + for r in snap.rows: + clean = {k: v for k, v in r.items() if not k.startswith("_")} + rows.append(clean) + data = {"as_of": now_fa(), "hurdle": self.state["rules"]["hurdle"], + "capital": self.state["rules"]["capital"], "rows": rows} + SNAPSHOT_FILE.parent.mkdir(parents=True, exist_ok=True) + SNAPSHOT_FILE.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8") + return SNAPSHOT_FILE + + def do_run(self) -> None: + if deskmod is None: + self.messagebox.showerror("میز معاملات نیست", "پوشهٔ desk پیدا نشد؛ به من بگویید تا مسیرش را درست کنم.") + return + self.progress.start(12) + self.push("شروع محاسبه…") + + def work(): + mode = self.state["data_mode"] + if self.state.get("snapshot") is None or mode != "live": + snap = datafeed.build_snapshot(mode, file_path=self.state.get("file_path") or None, + live_cfg=self.state["live_cfg"], key=self.state.get("key"), + progress=self.push) + self.state["snapshot"] = snap + snap = self.state["snapshot"] + self.push(f"منبع: {snap.source_label} · تازگی: {snap.freshness_label} · ردیف: {len(snap.rows)}") + for m in snap.messages: + self.push("· " + m) + if not snap.rows: + self.push("هیچ ردیفی برای محاسبه نیست؛ پرونده یا منبع داده را بررسی کنید.") + return None + path = self.materialize_snapshot(snap) + cfg = json.loads(json.dumps(deskmod.DEFAULT_CONFIG, ensure_ascii=False)) + cfg.update(self.state["rules"]) + cfg["capital"] = float(self.state["rules"]["capital"]) + cfg["hurdle"] = float(self.state["rules"]["hurdle"]) + desk = deskmod.Desk() + kodal_db = self.state["kodal_db"] if self.state.get("use_kodal") else None + sigs = deskmod.scan_market(path, cfg, desk, kodal_db) + tasks = deskmod.recheck_tasks(cfg, desk, kodal_db, path) if kodal_db else [] + dash = deskmod.build_dashboard(desk, cfg, DASHBOARD_FILE, tasks) + return sigs, tasks, dash + + def done(payload): + self.progress.stop() + if not payload: + return + sigs, tasks, dash = payload + pending = [s for s in sigs if s.status == "pending"] + approved = [s for s in sigs if s.status == "approved"] + rejected = [s for s in sigs if s.status == "rejected"] + self.push(f"خلاصه: {len(sigs)} سیگنال · {len(pending)} منتظر تأیید · " + f"{len(approved)} تأییدشده · {len(rejected)} رد") + for s in sigs[:25]: + mark = {"pending": "✅", "approved": "🟢", "rejected": "✖"}.get(s.status, "•") + ann = f"{s.annualized_pct:.2f}٪" if isinstance(s.annualized_pct, (int, float)) else "—" + self.push(f"{mark} {s.symbol} · {deskmod.KIND_LABELS.get(s.kind, s.kind)} · " + f"بازده {ann} · حاشیه {s.score_pp:,.2f} · {s.contracts:,} {s.unit}") + if s.status == "rejected": + self.push(f" دلیل رد: {s.gate_note}") + for a in s.alerts[:2]: + self.push(f" خبر: [{a['score']}] {a['title'][:70]}") + if tasks: + self.push("کار بازبینی (خبر مهم بدون دادهٔ بازار):") + for t in tasks[:10]: + self.push(f" · {t['symbol']}: {t['reason']}") + self.push(f"داشبورد ساخته شد: {dash}") + self.update_badge() + self.show_step(5) + + self.run_async(work, done) + + # ---------- گام ۶ + def build_decide(self, parent): + frame = self.tk.Frame(parent, bg="white") + frame.pack(fill="both", expand=True) + self.tk.Label(frame, text="۶. نتیجه و تصمیم", bg="white", font=self.f(14, True)).pack(anchor="e", padx=14, pady=(12, 4)) + self.tk.Label(frame, text="هر سیگنال را ببینید، دلیل دروازه‌ها را بخوانید، و اگر پذیرفتید تأیید کنید.\n" + "تأیید شما در دفتر ثبت می‌شود و اجرای دوبارهٔ برنامه آن را بازنویسی نمی‌کند.", + bg="white", justify="right", font=self.f(10)).pack(anchor="e", padx=16, pady=(0, 6)) + + cols = ("sid", "symbol", "kind", "annual", "edge", "size", "margin", "status", "note") + heads = [("sid", "شناسه", 90), ("symbol", "نماد", 80), ("kind", "راهبرد", 140), + ("annual", "بازده سالانه٪", 90), ("edge", "حاشیه", 70), ("size", "اندازه", 110), + ("margin", "سرمایه (ریال)", 130), ("status", "وضعیت", 80), ("note", "دلیل / خبر", 360)] + self.tree = self.ttk.Treeview(frame, columns=cols, show="headings", height=12) + for c, title, width in heads: + self.tree.heading(c, text=title) + self.tree.column(c, width=width, anchor="e") + self.tree.pack(fill="both", expand=True, padx=16) + self.tree.bind("<>", self.on_select_signal) + + actions = self.tk.Frame(frame, bg="white") + actions.pack(fill="x", padx=16, pady=6) + self.note_var = self.tk.StringVar() + self.tk.Label(actions, text="یادداشت تصمیم:", font=self.f(10)).pack(side="right", padx=4) + self.ttk.Entry(actions, textvariable=self.note_var, width=58).pack(side="right", padx=4) + self.ttk.Button(actions, text="رد با دلیل", command=lambda: self.decide("rejected")).pack(side="right", padx=4) + self.ttk.Button(actions, text="تأیید و ساخت بستهٔ سفارش", command=lambda: self.decide("approved")).pack(side="right", padx=4) + self.ttk.Button(actions, text="به‌روزرسانی فهرست", command=self.refresh_signals).pack(side="right", padx=4) + + self.log_box(frame, height=7) + self.refresh_signals() + return frame + + def refresh_signals(self) -> None: + if deskmod is None: + return + for item in self.tree.get_children(): + self.tree.delete(item) + desk = deskmod.Desk() + self.state["_signals"] = desk.all(limit=300) + for s in self.state["_signals"]: + ann = f"{s.annualized_pct:,.2f}" if isinstance(s.annualized_pct, (int, float)) else "—" + news = " | ".join(a["title"][:60] for a in s.alerts[:1]) + note = (s.gate_note or "") + (f" | خبر: {news}" if news else "") + self.tree.insert("", "end", iid=s.sid, values=(s.sid, s.symbol, + deskmod.KIND_LABELS.get(s.kind, s.kind), + ann, f"{s.score_pp:,.2f}", + f"{s.contracts:,} {s.unit}", + f"{s.margin_locked:,.0f}", s.status, note)) + + def on_select_signal(self, _event=None) -> None: + sel = self.tree.selection() + if not sel: + return + sid = sel[0] + sig = next((s for s in self.state.get("_signals", []) if s.sid == sid), None) + if sig: + self.push(f"— {sig.symbol} · {sig.kind} · وضعیت {sig.status}") + self.push(" " + json.dumps(sig.detail, ensure_ascii=False)[:400]) + if sig.alerts: + for a in sig.alerts[:3]: + self.push(f" خبر: [{a['score']}] {a['title']}") + + def decide(self, action: str) -> None: + sel = self.tree.selection() + if not sel: + self.messagebox.showinfo("انتخاب نشده", "اول یک ردیف از جدول را انتخاب کنید.") + return + sid = sel[0] + note = self.note_var.get().strip() + desk = deskmod.Desk() + sig = desk.get(sid) + if sig is None: + return + if action == "approved": + cap = (sig.detail.get("_policy") or {}).get("cap_total") + used = desk.locked_margin(exclude_sid=sid) + sig.margin_locked + count = len([s for s in desk.all("approved") if s.sid != sid]) + max_pos = (sig.detail.get("_policy") or {}).get("max_positions", self.state["rules"]["max_positions"]) + if (cap and used > cap) or count >= max_pos: + ok = self.messagebox.askyesno( + "سقف ریسک", + f"تأیید این سیگنال سقف ریسک را رد می‌کند:\n" + f"سرمایهٔ درگیر {used:,.0f} از سقف {cap:,.0f} ریال\n" + f"موقعیت‌های تأییدشده {count} از {max_pos}\n\n" + "باز هم تأیید می‌کنید؟ (در دفتر با برچسب «رد سقف» ثبت می‌شود)") + if not ok: + return + note = (note + " | تأیید با رد سقف ریسک").strip(" |") + desk.decide(sid, action, note) + self.push(("تأیید شد: " if action == "approved" else "رد شد: ") + sid) + if action == "approved": + packet = deskmod.order_packet(desk.get(sid)) + self.show_packet(packet) + self.refresh_signals() + + def show_packet(self, packet: str) -> None: + win = self.tk.Toplevel(self.root) + win.title("بستهٔ سفارش — اجرا فقط توسط انسان در سامانهٔ کارگزاری") + win.geometry("820x600") + txt = self.tk.Text(win, font=("Consolas", 10), wrap="word", padx=10, pady=10) + txt.pack(fill="both", expand=True) + txt.insert("1.0", packet) + self.ttk.Button(win, text="کپی در حافظه", + command=lambda: (self.root.clipboard_clear(), self.root.clipboard_append(packet))).pack(pady=6) + self.ttk.Button(win, text="بستن", command=win.destroy).pack(pady=(0, 8)) + + # ---------- گام ۷ + def build_backtest(self, parent): + frame = self.tk.Frame(parent, bg="white") + frame.pack(fill="both", expand=True) + self.tk.Label(frame, text="۷. پس‌آزمایی روی دادهٔ تاریخ", bg="white", font=self.f(14, True)).pack(anchor="e", padx=14, pady=(12, 4)) + self.tk.Label(frame, text="همان موتوری که در تصمیم زنده کار می‌کند، روی دادهٔ گذشته اجرا می‌شود:\n" + "نرخ برد، خطای مثبت کاذب، فرصت‌های از دست رفته، و خطای پیش‌بینی (انتظار منهای واقعیت) حساب می‌شود.", + bg="white", justify="right", font=self.f(10)).pack(anchor="e", padx=16) + line = self.tk.Frame(frame, bg="white") + line.pack(fill="x", padx=16, pady=6) + self.hist_var = self.tk.StringVar(value=str(DEMO_HISTORY)) + self.ttk.Entry(line, textvariable=self.hist_var, width=70).pack(side="right", padx=4) + self.ttk.Button(line, text="انتخاب پرونده…", command=self.pick_history).pack(side="right", padx=4) + self.ttk.Button(line, text="ساخت قالب ستون‌ها", command=self.make_history_template).pack(side="right", padx=4) + btns = self.tk.Frame(frame, bg="white") + btns.pack(anchor="e", padx=16) + self.ttk.Button(btns, text="اجرای پس‌آزمایی", command=self.do_backtest).pack(side="right", padx=4) + self.ttk.Button(btns, text="بازکردن گزارش در مرورگر", command=lambda: open_path(BACKTEST_HTML)).pack(side="right", padx=4) + self.summary = self.tk.Text(frame, height=6, wrap="word", bg="#f8fafc", font=self.f(10), padx=8, pady=6) + self.summary.pack(fill="x", padx=16, pady=6) + self.summary.configure(state="disabled") + self.log_box(frame, height=10) + return frame + + def pick_history(self) -> None: + path = self.filedialog.askopenfilename(title="پروندهٔ تاریخ (CSV یا JSON)", + filetypes=[("CSV", "*.csv"), ("JSON", "*.json"), ("همه", "*.*")]) + if path: + self.hist_var.set(path) + + def make_history_template(self) -> None: + p = datafeed.write_history_template(DATA / "history-template.csv") + self.messagebox.showinfo("قالب ساخته شد", f"قالب ستون‌های پس‌آزمایی:\n{p}\n\n" + "ستون کلیدی: realized_annualized_pct یعنی «نتیجهٔ واقعی» آن معامله در گذشته. " + "این ستون در تصمیم هیچ نقشی ندارد و فقط برای سنجش است.") + + def do_backtest(self) -> None: + path = self.hist_var.get().strip() + self.push(f"اجرای پس‌آزمایی روی {path} …") + + def work(): + result = bt.run_backtest(path, rules={"min_edge_arbitrage_pct": self.state["rules"]["min_edge_arbitrage_pct"], + "min_edge_leveraged_pct": self.state["rules"]["min_edge_leveraged_pct"], + "min_liquidity_contracts_per_day": self.state["rules"]["min_liquidity_contracts_per_day"], + "max_spread_pct": self.state["rules"]["max_spread_pct"], + "max_plausible_arb_pct": self.state["rules"]["max_plausible_arb_pct"], + "max_plausible_lev_pct": self.state["rules"]["max_plausible_lev_pct"]}, + capital=float(self.state["rules"]["capital"])) + bt.build_report(result, BACKTEST_HTML) + bt.write_csv(result, BACKTEST_CSV) + self.state["backtest_result"] = result + return result + + def done(result): + if not result: + return + s = result["summary"] + for p in s["problems"][:5]: + self.push("· " + p) + text = (f"سطرها: {s['rows']} · ورود: {s['taken']} · رد: {s['skipped']}\n" + f"نرخ برد: {s['hit_rate_pct']:.1f}٪ · خطای مثبت کاذب: {s['false_positive_rate_pct']:.1f}٪ · " + f"فرصت از دست رفته: {s['missed_opportunity_rate_pct']:.1f}٪\n" + f"میانگین بازده انتظاری ورودها: {s['avg_expected_annualized_pct']:.1f}٪ · " + f"میانگین بازده واقعی: {s['avg_realized_annualized_pct']:.1f}٪\n" + f"خطای پیش‌بینی (واقعی منهای انتظار): {s['avg_forecast_error_pp']:.1f} واحد درصد\n" + f"سرمایه: از {s['start_capital']:,.0f} به {s['final_equity']:,.0f} " + f"({s['equity_change_pct']:.1f}٪)\n" + + ("هشدار: این پرونده نمونهٔ ساختگی است؛ برای ارائه به شرکت، دادهٔ واقعی خودتان را بدهید." + if "history-demo" in str(s["file"]) else "")) + self.summary.configure(state="normal") + self.summary.delete("1.0", "end") + self.summary.insert("1.0", text) + self.summary.configure(state="disabled") + self.push(f"گزارش پس‌آزمایی: {BACKTEST_HTML}") + self.push("درسِ کلیدی: اگر میانگین واقعی از میانگین انتظاری کمتر است، انتظار موتور خوش‌بینانه است؛ " + "با دادهٔ خودتان این فاصله را اندازه بگیرید و کف حاشیه را بالا ببرید.") + + self.run_async(work, done) + + # ---------- گام ۸ + def build_bundle(self, parent): + frame = self.tk.Frame(parent, bg="white") + frame.pack(fill="both", expand=True) + self.tk.Label(frame, text="۸. بستهٔ تحویل شرکت", bg="white", font=self.f(14, True)).pack(anchor="e", padx=14, pady=(12, 4)) + self.tk.Label(frame, text="این بسته، همه‌چیز را برای راستی‌آزمایی شرکت در یک پوشه می‌گذارد:\n" + "گزارش تصمیم‌ها، فهرست سیگنال‌ها، سند روش کار، بسته‌های سفارش، نتیجهٔ پس‌آزمایی،\n" + "و یک چک‌لیست که خودشان در پنج دقیقه راستی‌آزمایی کنند.", + bg="white", justify="right", font=self.f(10)).pack(anchor="e", padx=16) + btns = self.tk.Frame(frame, bg="white") + btns.pack(anchor="e", padx=16, pady=8) + self.ttk.Button(btns, text="ساخت بستهٔ راستی‌آزمایی", command=self.do_bundle).pack(side="right", padx=4) + self.ttk.Button(btns, text="بازکردن پوشهٔ بسته", command=self.open_bundle).pack(side="right", padx=4) + self.ttk.Button(btns, text="نمایش سند روش کار", command=lambda: self.open_method()).pack(side="right", padx=4) + self.log_box(frame, height=16) + return frame + + def do_bundle(self) -> None: + if self.state.get("snapshot") is None: + self.messagebox.showinfo("داده‌ای نیست", "اول در گام ۲ یک منبع داده انتخاب کنید و در گام ۵ محاسبه بگیرید.") + return + try: + out = build_bundle(self.state) + except Exception as e: + self.messagebox.showerror("ساخت بسته ناموفق", f"{type(e).__name__}: {e}") + return + self.push(f"بسته ساخته شد: {out}") + for f in sorted(Path(out).iterdir()): + self.push(f" · {f.name} ({f.stat().st_size:,} بایت)") + self.push("پیشنهاد ارائه: فایل 03-method.html را بخوانند، بعد 01-dashboard.html را ببینند، " + "و بر اساس README-FA.md راستی‌آزمایی کنند.") + + def open_bundle(self) -> None: + d = self.state.get("bundle_dir") + if d: + open_path(Path(d)) + else: + self.messagebox.showinfo("بسته‌ای ساخته نشده", "اول دکمهٔ ساخت بسته را بزنید.") + + def open_method(self) -> None: + p = DATA / "method-preview.html" + p.write_text(build_method_html(self.state), encoding="utf-8") + open_path(p) + + +# ---------------------------------------------------------------- اجرا +def demo_state(station: "Station") -> None: + """حالت نمایش برای آزمون و تصویرسازی: دادهٔ نمونه + یک بار محاسبه.""" + station.state["data_mode"] = "sim" + snap = datafeed.build_snapshot("sim") + station.state["snapshot"] = snap + station.update_badge() + mode_var = getattr(station, "mode_var", None) + if mode_var is not None: + mode_var.set("sim") + station.on_mode_change() + + +def main(argv: list[str]) -> int: + import argparse + + ap = argparse.ArgumentParser(description="ایستگاه تصمیم مشتقه — رابط گرافیکی گام‌به‌گام") + ap.add_argument("--smoke", action="store_true", help="آزمون ساخت همهٔ گام‌ها بدون تعامل") + ap.add_argument("--step", type=int, default=0, help="با کدام گام باز شود (۱ تا ۸)") + ap.add_argument("--demo-state", action="store_true", help="پر کردن وضعیت با دادهٔ نمونه") + ap.add_argument("--autorun", action="store_true", help="اجرای خودکار محاسبه و پس‌آزمایی") + ap.add_argument("--shot", help="گرفتن تصویر از پنجره در این مسیر و بستن برنامه") + ap.add_argument("--shot-delay", type=float, default=2200, help="تأخیر تصویربرداری (میلی‌ثانیه)") + ap.add_argument("--version", action="store_true") + args = ap.parse_args(argv) + + if args.version: + print(f"station {VERSION}") + return 0 + + tk, ttk, filedialog, messagebox = import_tk() + root = tk.Tk() + app = Station(root, tk, ttk, filedialog, messagebox) + + if args.demo_state and not args.smoke: + demo_state(app) + if args.step: + app.show_step(max(0, args.step - 1)) + + if args.smoke: + errors = [] + for i in range(len(STEPS)): + try: + app.show_step(i) + root.update() + except Exception as e: + errors.append(f"گام {i + 1}: {type(e).__name__}: {e}") + try: + demo_state(app) + app.show_step(5) + root.update() + app.refresh_signals() + root.update() + except Exception as e: + errors.append(f"حالت نمونه: {type(e).__name__}: {e}") + ok, items = health_report() + print("آزمون ساخت گام‌ها:") + for i, (_, title) in enumerate(STEPS): + print(f" گام {i + 1} — {title}: ساخته شد") + for e in errors: + print(" خطا →", e) + print(f"بررسی سلامت: {len([1 for _, f, _ in items if f])} از {len(items)} موفق") + print("SMOKE " + ("OK" if not errors else "FAILED")) + root.destroy() + return 0 if not errors else 1 + + if args.autorun: + app.show_step(4) + app.do_run() + root.after(2500, app.do_backtest) + + if args.shot: + def shoot(): + root.update() + os.system(f'scrot -o "{args.shot}"') + root.after(200, root.destroy) + root.after(int(args.shot_delay), shoot) + + root.mainloop() + return 0 + + +if __name__ == "__main__": + raise SystemExit(main(sys.argv[1:])) diff --git a/station/strategy_audit.py b/station/strategy_audit.py new file mode 100644 index 0000000000000000000000000000000000000000..d9a0b91f1854627c4f1979c176f50141c1a03060 --- /dev/null +++ b/station/strategy_audit.py @@ -0,0 +1,644 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""کتابخانهٔ راهبردها + حسابرسی عددها — «جزوهٔ راهبردهای موفق، با درصد و قاعدهٔ بستن». + +این پرونده سه کار می‌کند: + +۱) **متن آموزشی هر راهبرد**: اصل کار (چرا کار می‌کند)، چه وقت استفاده می‌شود، چه چیزی + لازم دارد، و **قاعدهٔ بستن موقعیت** (کِی بفروشم، کِی حساب را ببندم، از کجا خارج شوم). + +۲) **حسابرسی عددها**: هر عددِ راهبرد با موتور خودِ ایستگاه حساب می‌شود، با یک محاسبهٔ دستی + دوم مقایسه می‌شود (دو-روشی)، و برچسب روش می‌گیرد: + • «قطعی» = در لحظهٔ ورود قفل و قابل محاسبه است (مثل تبعی، باکس، مبنا). + • «مدل‌محور» = با فرض حرکت لگنرمال و نوسانِ ضمنیِ استخراج‌شده از قیمت خودِ بازار + (نه وعدهٔ واقعیت). + • «نقل‌شده» = از منبع بیرونی، با نام منبع؛ هیچ‌وقت بدون برچسب استفاده نمی‌شود. + +۳) **ریسک‌ها را هم عدد می‌کند**: فاصله تا اخطاریهٔ مارجین‌کال، تحمل کارمزد، حساسیت به لغزش + اجرا، نقدشوندگی و اسپرد — همان چیزهایی که راهبرد خوب را در عمل می‌کشد. + +هیچ‌جا «تضمین سود» نیست؛ جایی هم که عدد «قطعی» است، فقط در صورت انجام‌شدن همان قرارداد قطعی +است (مثل اعمال تبعی)، نه وعدهٔ ثروت. +""" + +from __future__ import annotations + +import argparse +import json +import math +import os +import sys +from pathlib import Path + +BASE = Path(__file__).resolve().parent +if str(BASE) not in sys.path: + sys.path.insert(0, str(BASE)) + +import investor_test as inv # noqa: E402 +import edge_stress as stresser # noqa: E402 +import reportkit as rk # noqa: E402 + +VERSION = "0.1.0" +# پوشهٔ جزوه؛ می‌شود با متغیر محیطی جابه‌جا شد تا کل مجموعه روی هر رایانه‌ای کار کند +OUT = Path(os.environ.get("IRAN_DESK_MONEY_DIR") or (BASE.parent / "strategies")) +GUI_DATA = BASE / "data" +LIB_MD = OUT / "strategy-library-fa.md" +LIB_HTML = OUT / "strategy-library.html" +LIB_JSON = OUT / "strategy-library.json" +REF_MD = OUT / "references-fa.md" +INDEX_MD = OUT / "README-FA.md" + +CREDIT = ("✍️ تهیه‌کنندهٔ جزوات: **Masoud Mojarabian** · 📱 +989126630554 · " + "✈️ Telegram: [Mojarabian](https://t.me/Mojarabian) · " + "📸 Instagram: [Mojarabian.Art](https://instagram.com/Mojarabian.Art)") + + +# ----------------------------------------------------------------- نوسان و احتمال +def _N(x: float) -> float: + """تابع توزیع تجمعی نرمال استاندارد.""" + return 0.5 * (1 + math.erf(x / math.sqrt(2))) + + +def bs_call(s: float, k: float, days: float, r: float, sigma: float) -> float: + """قیمت نظری اختیار خرید اروپایی (بلک-شولز).""" + t = max(days, 0.01) / 365.0 + if s <= 0 or k <= 0 or sigma <= 0: + return 0.0 + d1 = (math.log(s / k) + (r + sigma * sigma / 2) * t) / (sigma * math.sqrt(t)) + d2 = d1 - sigma * math.sqrt(t) + return s * _N(d1) - k * math.exp(-r * t) * _N(d2) + + +def bs_put(s: float, k: float, days: float, r: float, sigma: float) -> float: + """قیمت نظری اختیار فروش اروپایی (از تساوی پوت-کال — مستقل از کد خرید).""" + t = max(days, 0.01) / 365.0 + if s <= 0 or k <= 0 or sigma <= 0: + return 0.0 + d1 = (math.log(s / k) + (r + sigma * sigma / 2) * t) / (sigma * math.sqrt(t)) + d2 = d1 - sigma * math.sqrt(t) + return k * math.exp(-r * t) * _N(-d2) - s * _N(-d1) + + +def implied_vol(price: float, s: float, k: float, days: float, r: float, kind: str = "call", + lo: float = 0.01, hi: float = 12.0) -> dict: + """نوسان ضمنی را از قیمت خودِ بازار درمی‌آورد (نصف‌کردن بازه). + + اگر قیمت بازار از هر دو سر بازه هم پایین‌تر/بالاتر باشد، صریح گفته می‌شود که عدد + «از بازه بیرون است» — نه اینکه عدد ساختگی بدهیم. + """ + f = bs_call if kind == "call" else bs_put + p_lo, p_hi = f(s, k, days, r, lo), f(s, k, days, r, hi) + if price <= p_lo: + return {"ok": False, "detail": f"قیمت بازار ({price:.4f}) از نظری‌ترین حالتِ نوسان کم " + f"({p_lo:.4f}) هم کمتر است؛ نوسان ضمنی در بازه نیست."} + if price >= p_hi: + return {"ok": False, "detail": f"قیمت بازار ({price:.4f}) از نظری‌ترین حالتِ نوسان زیاد " + f"({p_hi:.4f}) هم بیشتر است؛ یا دادهٔ ورودی جابه‌جاست یا " + f"قیمت بازار با مدل نمی‌خواند."} + for _ in range(200): + mid = (lo + hi) / 2 + pm = f(s, k, days, r, mid) + if pm < price: + lo = mid + else: + hi = mid + sigma = (lo + hi) / 2 + check = f(s, k, days, r, sigma) + return {"ok": True, "sigma": round(sigma, 4), "sigma_pct": round(sigma * 100, 2), + "model_price": round(check, 4), "market_price": round(price, 4), + "gap_pct": round((check - price) / price * 100, 3), + "detail": (f"نوسان ضمنی سالانه ≈ {sigma * 100:.2f}٪ (از قیمت بازار " + f"{price:,.4f} و مدل بلک-شولز با نرخ {r * 100:.1f}٪). " + f"بازسازی مدل با همین نوسان: {check:,.4f}.")} + + +def prob_under(s: float, k: float, days: float, r: float, sigma: float) -> float: + """احتمال مدل‌محور اینکه قیمت در سررسید زیر قیمت اعمال بماند.""" + t = max(days, 0.01) / 365.0 + d2 = (math.log(s / k) + (r - sigma * sigma / 2) * t) / (sigma * math.sqrt(t)) + return _N(-d2) + + +def expected_move(s: float, days: float, sigma: float) -> float: + """حرکت مورد انتظار قیمت تا سررسید (یک انحراف معیار).""" + return s * sigma * math.sqrt(max(days, 0.01) / 365.0) + + +# ----------------------------------------------------------------- متن راهبردها +STRATEGIES: list[dict] = [ + { + "id": "basis", + "name": "مبنا / کری نقدی-آتی", + "en": "Cash-and-carry basis", + "class": "قطعی (در لحظهٔ ورود قفل می‌شود)", + "idea": "یک دارایی (یا صندوق) را نقد می‌خری و همان لحظه معادلش را در بازار آتی " + "می‌فروشید. تفاوت قیمت آتی و نقدی، تا سررسید مال توست؛ چون دو طرف را همین حالا " + "بسته‌ای، عدد در لحظهٔ ورود قفل است (به آن «بازده قفل‌شده» می‌گویند).", + "when": "وقتی قیمت آتی از نقدی به‌قدری بالاتر است که بعد از کارمزد دو طرف، از نرخ سد " + "(بازده بی‌ریسک) بگذرد. این تفاوت معمولاً وقتی باز می‌شود که تقاضای آتی بالا " + "رفته یا نقدشوندگی نقدی کم شده باشد.", + "requires": "دسترسی به بازار آتی، وجه تضمین فروشندهٔ آتی، و نقدشوندگی هر دو سر.", + "closing": ["برداشت سود: با رسیدن به ۵۰٪ بازده انتظاری، هر دو پا را هم‌زمان ببندید.", + "توقف ضرر: اگر قیمت پایه ۶٪ خلاف شما رفت (فاصله تا اخطاریهٔ مارجین‌کال)، " + "ببندید؛ یا وجه تضمین اضافه کن، ولی آن‌وقت بازده کل پایین می‌آید.", + "سررسید: اگر هیچ‌کدام نخورد، در سررسید ببندید (تسویهٔ نقدی/فیزیکی بر پایهٔ " + "قیمت تسویهٔ روز آخر).", + "قاعدهٔ طلایی: دو پا را هم‌زمان ببندید، وگرنه از «معاملهٔ قفل‌شده» به " + "«معاملهٔ جهت‌دار» تبدیل می‌شود."], + "risks": ["اخطاریهٔ مارجین‌کال در پاى آتی (تسویهٔ روزانه).", + "گپ نقدشوندگی در سررسید و اسپرد بزرگ.", + "تغییر ابلاغیه/وجه تضمین وسط راه.", + "قیمت تسویهٔ روز آخر (میانگین وزنی نیم‌ساعت پایانی) نه قیمتی که شما دیده‌ای."], + "refs": ["قواعد وجه تضمین و تسویهٔ روزانهٔ بورس کالا (حداقل ۷۰٪ وجه تضمین اولیه، " + "اخطاریهٔ مارجین‌کال) — جمع‌بندی‌شده در `05-data-routes-fa.md` و " + "محدودیت‌های معاملاتی ایران."], + }, + { + "id": "covered_call", + "name": "پوشش‌داده‌شده (فروش اختیار خرید روی سهم)", + "en": "Covered call", + "class": "مدل‌محور + درآمد پرمیوم", + "idea": "سهم را دارید و روی همان سهم اختیار خرید می‌فروشید. پرمیوم را همین حالا می‌گیرید؛ " + "در عوض سقف سود شما را روی قیمت اعمال قفل می‌کنید. اگر سهم زیر اعمال بماند، پرمیوم " + "خالص سود توست.", + "when": "بازاری که فکر می‌کنید تا سررسید صعود تند ندارد، ولی نوسان (و بنابراین پرمیوم) " + "گران است. بازده پرمیوم سالانه‌شده باید از نرخ سد بگذرد.", + "requires": "سهم + دسترسی به بازار اختیار + کارمزد پایین (این راهبرد به کارمزد حساس است).", + "closing": ["برداشت سود: ۵۰٪ بازده انتظاری، یا وقتی پرمیوم باقی‌مانده به کمتر از ۲۰٪ " + "پرمیوم اولیه رسید (خرید بازخرید اختیار).", + "توقف ضرر: روی خودِ سهم، همان حد ضرر سهم؛ پرمیوم فقط کمی آن را نرم می‌کند " + "(پرمیوم ۴۰۰ روی سهم ۷٬۰۰۰ فقط ۵٫۷٪ حاشیه است).", + "سررسید: اگر اعمال شد، سهم در قیمت اعمال تحویل می‌رود؛ اگر نشد، اختیار " + "بی‌ارزش تمام می‌شود و سهم می‌ماند.", + "قاعدهٔ بستن: پیش از سررسید و اگر سهم به اعمال نزدیک شد، یا بپذیر تحویل، یا " + "اختیار را بازخرید کن — تصمیم را به روز آخر نگذار."], + "risks": ["سقف سود (صعود تند، شما را از سود باز می‌دارد).", + "ریسک نزولی سهم تقریباً کامل می‌ماند.", + "کارمزد سهم + کارمزد اختیار + مالیات فروش سهم از پرمیوم کم می‌شود."], + "refs": ["کارمزد فروش سهم ۰٫۹۶۴٪ و خرید ۰٫۴۶۴٪ (کارگزاری‌ها/خانِ سرمایه)، کارمزد اختیار " + "≈۰٫۱۰۳٪ هر طرف و اعمال ۰٫۰۵٪ (بازار مشتقه)."], + }, + { + "id": "tabei", + "name": "اوراق تبعی (اختیار فروش تضمینی)", + "en": "Guaranteed put-back (tabei)", + "class": "قطعی (تعهد ناشر/بازارساز)", + "idea": "سهم را می‌خری و رویش «تبعی» (اختیار فروش با تعهد بازخرید) می‌خری. از این لحظه، " + "کمترین بازدهی‌ات تا سررسید قفل است: حتی اگر سهم بریزد، تبعی به قیمت اعمال " + "خریداری می‌شود. رشد بالاتر از اعمال هم مال توست.", + "when": "وقتی کمینهٔ بازده تبعی از نرخ سد بگذرد؛ برای پرتفوی کم‌ریسک و نگه‌دارید تا " + "سررسید عالی است. قدرت اهرمی هم دارد (هموطن ≈۱٫۳ برابر، همیار ≈۱٫۲ برابر).", + "requires": "دسترسی به نمادهای تبعی + نقدشوندگی همان نماد تبعی (این نقطهٔ ضعف اصلی است).", + "closing": ["برداشت سود: اگر سهم از قیمت اعمال بالا رفت، سهم را در بازار بفروشید و " + "تبعی را رها کن (کمترین بازده دیگر لازم نیست).", + "توقف ضرر: ذاتاً لازم نیست — تعهد بازخرید در اعمال، سقف ضرر است؛ ولی اگر " + "ناشر به تعهدش عمل نکند یا نماد بسته شود، این توقف می‌شکند.", + "سررسید: در پنجرهٔ اعمال، سهم را به قیمت اعمال به تبعی بفروشید (یا بسته به " + "نوع تبعی، تسویهٔ تفاوت).", + "قاعدهٔ بستن: شمارهٔ پنجرهٔ اعمال را از قبل در تقویم بگذارید؛ دیرکرد در اعمال " + "= از دست دادن تضمین."], + "risks": ["ریسک تعهد (ناشر/بازارساز) و ریسک عملیاتی پنجرهٔ اعمال.", + "نقدشوندگی: اگر تبعی نقدشونده نباشد، بازده روی کاغذ می‌ماند.", + "کارمزد دو سر و مالیات فروش سهم از کمینهٔ بازده کم می‌شود."], + "refs": ["ساختار تبعی و اهرم‌ها: گزارش‌های بازار سرمایه (سهم‌بورس/رصد)، اسناد اوراق " + "تبعی ناشر."], + }, + { + "id": "box", + "name": "باکس اسپرد (چهار پایه، بدون ریسک جهت)", + "en": "Box spread", + "class": "قطعی (پرداخت ثابت در سررسید)", + "idea": "چهار اختیار را طوری می‌چینی که پرداخت سررسید همیشه ثابت باشد (مثلاً ۳٬۰۰۰). " + "آن‌وقت معامله به «خرید یک قرض قطعی با تخفیف» تبدیل می‌شود؛ ریسک جهت و نوسان " + "صفر است.", + "when": "وقتی «بدهی امروزِ» باکس از ارزش فعلی پرداخت قطعی‌اش کمتر باشد، یعنی بازار " + "کوپن بالاتر از نرخ سد می‌دهد.", + "requires": "چهار پایهٔ نقدشونده با اسپرد کم — وگرنه سرسری می‌افتد.", + "closing": ["برداشت سود: نگه‌داشتن تا سررسید (پرداخت قطعی)؛ یا اگر بدهی بازار بزرگ‌تر " + "شد، بستن زودهنگام با سود.", + "توقف ضرر: ذاتاً ندارد؛ اما اگر نقدشوندگی یکی از پایه‌ها خشک شود، خروج " + "زودهنگام ممکن نمی‌شود.", + "سررسید: بستن در سررسید (تحویل/تسویهٔ هر چهار پایه).", + "قاعدهٔ بستن: هرچه بدهی خالص کوچک‌تر باشد، حساسیت به لغزش اجرا بیشتر است؛ " + "باکسی که بدهی‌اش فقط ۲۸۰ روی سپردهٔ ۳۰۰ است، با ۰٫۵٪ لغزش اجرا می‌افتد."], + "risks": ["حساسیت شدید به لغزش اجرا و اسپرد (آزمون شوک: ۰٪ تاب‌آوری زیر لغزش ۰٫۵٪).", + "کارمزد چهار طرف.", + "نبود امکان فروش استقراضی برای سمت معکوس."], + "refs": ["ساختار باکس/تساوی: تئوری آربیتراژ آپشن (پاریتی)، ابزارهای مقایسهٔ آپشن بورس " + "کالا."], + }, + { + "id": "parity", + "name": "تبدیل تساوی پوت-کال", + "en": "Put-call parity conversion", + "class": "قطعی (در لحظهٔ اجرا)، ولی کم‌بسامد", + "idea": "قانون تساوی می‌گوید: کال − پوت باید برابر باشد با سهم − ارزش فعلی اعمال. اگر " + "شکاف از کارمزد سه پایه بزرگ‌تر شد، با خرید سهم + پوت و فروش کال، بازار را " + "در یک قفس قفل می‌کنید.", + "when": "شکاف‌های بزرگ (وقتی یکی از پایه‌ها نقدشوندگی‌اش را از دست داده). در شرایط " + "عادی، کارمزد سه پایه شکاف را می‌خورد و جواب «نه» است.", + "requires": "سه پایهٔ هم‌سررسید با اعمال یکسان + امکان فروش اختیار (وجه تضمین).", + "closing": ["باد ventilation صریح: اگر شکاف بسته شد، سود را بردارید و ببندید.", + "توقف ضرر: انحراف بیش از حد انتظار = نشانهٔ دادهٔ اشتباه یا اعمال متفاوت " + "سررسید؛ جای صبر نیست، بستن.", + "سررسید: نگه‌داشتن تا سررسید، اعمال خودکار تعهدها.", + "قاعدهٔ بستن: سمت معکوس (reverse conversion) در ایران ممکن نیست؛ چون فروش " + "استقراضی سهم وجود ندارد. پس فقط یک جهت."], + "risks": ["کارمزد سه پایه؛ شکاف کاذب از دادهٔ بی‌کیفیت.", + "عدم امکان اجرای سمت معکوس (محدودیت بازار ایران).", + "پورتال‌های داده اشتباه زیاد دارند؛ اول با داوری سیگنال، اعتبار داده را بسنجید."], + "refs": ["تساوی پوت-کال و کژشکاف‌ها: مبانی مالی مشتقه؛ فیلترهای مقایسه‌ای ابزارهای آپشن."], + }, + { + "id": "leveraged_fund", + "name": "صندوق اهرمی و نرخ مبنای درآمد ثابت", + "en": "Leveraged fund / fixed-income baseline", + "class": "ریسکی (اهرم) + خط پایهٔ قطعی", + "idea": "دو کار متفاوت: (الف) نرخ مؤثر اوراق/صندوق درآمد ثابت را «خط پایهٔ» خودتان بگذارید؛ " + "هر راهبردی که از آن نمی‌گذرد، ارزش ریسک ندارد. (ب) صندوق اهرمی بازده بازار را " + "چند برابر می‌کند، هم بالا و هم پایین.", + "when": "خط پایه همیشه؛ صندوق اهرمی فقط وقتی بازوی تحمل ریزش دارید (اهرم روزانه تسویه " + "می‌شود).", + "requires": "دسترسی به صندوق‌ها/اوراق؛ برای اهرمی، تحمل نوسان.", + "closing": ["خط پایه: نگه‌داشتن تا سررسید یا فروش در صندوق (نقدشوندگی روزانه).", + "اهرمی: حد ضرر سخت (مثلاً ۱۰٪) بگذارید و از تسویهٔ روزانه غافل نشو.", + "قاعدهٔ بستن: اهرم را فقط با پولی ببر که ریزش ۳۰٪ برایت فاجعه نیست."], + "risks": ["اهرم، زیان را همان‌قدر بزرگ می‌کند که سود را.", + "کارمزد مدیریت صندوق از بازده کم می‌کند.", + "تسویهٔ روزانه در ابزارهای اهرمی/آتی می‌تواند پیش از برگشت بازار، شما را بیرون " + "بیندازد."], + "refs": ["بازده مؤثر صندوق درآمد ثابت شهریور ۱۴۰۵: ۳۹ تا ۴۰٪؛ سپردهٔ بانکی ۲۰٫۵ تا " + "۲۲٫۵٪ (گزارش‌های بازار، ناب‌ز قیمت/بورس‌نیوز)."], + }, + { + "id": "naked_put", + "name": "فروش اختیار فروش بدون پوشش (کارگاه بقا)", + "en": "Naked short put", + "class": "ریسکی — برای آموزش ریاضیِ ورشکستگی", + "idea": "پرمیوم می‌گیرید و تعهد می‌دهی که در قیمت اعمال بخرید. اگر بازار بالای اعمال " + "بماند، پرمیوم مال توست؛ اگر بریزد، زیان تقریباً بی‌سقف است. وجه تضمین اولیه " + "≈۲۰٪ ارزش قرارداد، حد نگهداری ۷۰٪ آن، تسویهٔ روزانه.", + "when": "فقط برای کسی که بقا را می‌فهمد (اندازهٔ کوچک و نقد آماده).", + "requires": "وجه تضمین + تحمل مارجین‌کال.", + "closing": ["برداشت سود: ۵۰٪ پرمیوم (خرید بازخرید).", + "توقف ضرر: قبل از رسیدن به فاصلهٔ اخطاریهٔ مارجین‌کال ببندید (عدد فاصله در " + "حسابرسی همین جزوه آمده).", + "سررسید: اگر زیر اعمال بماند، تسویه/خرید سهم.", + "قاعدهٔ بستن: هرگز با تمام وجه تضمین یک موقعیت نگیر؛ تسویهٔ روزانه، حساب را " + "وسط راه می‌بندد."], + "risks": ["زیان دنباله (tail risk) و اخطاریهٔ مارجین‌کال.", + "ریسک ابلاغی/قانونی بازار مشتقه.", + "خودفریبی «پرمیوم همیشه مال من است»."], + "refs": ["حداقل وجه تضمین ۷۰٪ و اخطاریهٔ مارجین‌کال (بورس کالا)، وجه تضمین فروشندهٔ " + "اختیار ≈۲۰٪ ارزش قرارداد."], + }, + { + "id": "income_no_capital", + "name": "درآمد بدون سرمایه: فروش «تصمیم و شاهد»", + "en": "Selling verified decisions (service)", + "class": "درآمدی (بدون بازار) — اهرم اصلی شما", + "idea": "اگر ریاضیِ بالا را دارید، می‌توانی بدون سرمایه از آن درآمد بسازی: برای کارگزاری، " + "شرکت یا معامله‌گر، سیگنال‌های ابزارهای دیگر را «داوری» کنید و شاهد بدهی: این " + "سیگنال با کارمزد واقعی، وجه تضمین و نقدشوندگی واقعی می‌ماند یا می‌افتد.", + "when": "همین حالا. هیچ بازار، هیچ سرمایه و هیچ مجوزی لازم نیست؛ فقط همین ایستگاه و " + "توانایی توضیح دادن.", + "requires": "ارائهٔ شاهد قابل راستی‌آزمایی (زنجیرهٔ هش، آزمون دو-روشی، تضمین ساختاری) و " + "صداقت در گفتن «نمی‌دانم».", + "closing": ["این «موقعیت» موقعیت بازار نیست؛ موقعیت شغلی است.", + "قاعدهٔ بستن: اگر شاهد از کار افتاد یا مشتری عدد کارگزاری متفاوتی گرفت، " + "فوراً اعلام کن و اصلاح کن — اعتماد، تنها دارایی این کار است."], + "risks": ["هیچ سود تضمینی‌ای در بازار نیست؛ درآمد شما از «شاهد» می‌آید، نه از وعدهٔ سود.", + "بدون تضمین ساختاری، این کار به «سیگنال‌فروشی» تبدیل می‌شود — و اعتبار می‌سوزد."], + "refs": ["سند تفاوت‌بگذارید و اعتماد: `08-differentiation-and-trust-fa.md` (سنجش ابزارهای " + "موجود ایران: دیده‌بان آپشن، بامبو، آپشن‌اسکول)."], + }, +] + +NUMERIC_KINDS = {"basis": "basis", "covered_call": "covered_call", "tabei": "tabei", "box": "box", + "parity": "parity"} + + +def audit_strategy(sid: str, rows: list[dict] | None = None) -> dict: + """برای راهبردهایی که عدد می‌پذیرند، حسابرسی کامل می‌سازد (موتور + دستی + شوک‌ها).""" + rows = rows if rows is not None else inv.fallback_rows() + kind = NUMERIC_KINDS.get(sid) + if not kind: + return {"ok": False, "detail": "این راهبرد عدد بازار نمی‌گیرد (درآمدی/آموزشی است)."} + try: + row = inv._pick(kind, rows) + except LookupError: + return {"ok": False, "detail": "داده‌ای برای این راهبرد در اسنپ‌شات نبود."} + solved = inv.solve(row) + ladder = inv.ladder_for(row) + stress = stresser.stress_row(row) + out = { + "ok": True, "kind": kind, "given": solved["given"], "formula": solved["formula"], + "steps": solved["steps"], "answer": solved["answer"], "unit": solved["unit"], + "checks": solved["checks"], "engine_value": solved["answer_num"], + "hand_value": (solved["checks"][0]["value"] if solved.get("checks") else None), + "hand_agrees": all(c.get("agree") for c in solved.get("checks", [])) if solved.get("checks") else None, + "closing": ladder.get("ladder", []), "verdict": ladder.get("verdict"), + "fees_pct": ladder.get("fees_pct"), "hurdle_pct": ladder.get("hurdle_pct"), + "margin_pp": ladder.get("margin_pp"), "survives": ladder.get("survives"), + "resilience_pct": stress.get("resilience_pct"), + "first_failure": stress.get("first_failure"), + "fee_tolerance": stress.get("fee_tolerance"), + "shocks": stress.get("shocks"), + "margin_call": stress.get("margin"), + "extras": solved.get("extras", {}), + } + # احتمال مدل‌محور برای راهبردهای اختیاری (با نوسان ضمنی خودِ بازار) + prob = None + rate = float(row.get("rate") or inv.HURDLE_DEFAULT) + if kind == "covered_call" and row.get("premium") and row.get("strike") and row.get("days"): + iv = implied_vol(float(row["premium"]), float(row["spot"]), float(row["strike"]), + float(row["days"]), rate, "call") + if iv.get("ok"): + p_under = prob_under(float(row["spot"]), float(row["strike"]), float(row["days"]), + rate, iv["sigma"]) + prob = {"iv": iv, "prob_under_strike_pct": round(p_under * 100, 2), + "prob_assigned_pct": round((1 - p_under) * 100, 2), + "expected_move": round(expected_move(float(row["spot"]), float(row["days"]), + iv["sigma"]), 2), + "detail": (f"با نوسان ضمنی {iv['sigma_pct']}٪، احتمال مدل‌محور اینکه سهم زیر " + f"اعمال بماند (پرمیوم کامل مال شما) ≈{p_under * 100:.1f}٪ و احتمال " + f"اعمال‌شدن ≈{(1 - p_under) * 100:.1f}٪ است. این عدد «احتمال " + f"ریاضی تحت فرض بلک-شولز» است، نه پیش‌بینی بازار.")} + elif kind == "basis" and row.get("spot") and row.get("future"): + iv = None + prob = {"detail": ("این راهبرد جهت‌دار نیست؛ احتمال «سود/زیان» معنا ندارد. عددش قفل‌شده " + "است و ریسک اصلی‌اش مارجین‌کال و نقدشوندگی است.")} + out["model_probability"] = prob + return out + + +def as_percent_table(audits: dict) -> list[dict]: + """جدول یک‌نگاهی: چه راهبردی، چه عددی، با چه برچسب روش.""" + rows = [] + for s in STRATEGIES: + a = audits.get(s["id"], {}) + if a.get("ok"): + unit = (a.get("unit") or "").strip() + value = f"{a.get('answer')} {unit}".strip() + if unit in ("بله/نه", "بله یا نه"): + value = str(a.get("answer")) # تساوی: فقط «بله» یا «نه» + method = "قطعی/مدل‌محور (موتور ایستگاه + محاسبهٔ دستی دوم)" + if a.get("model_probability") and a["model_probability"].get("prob_under_strike_pct"): + value += (f" · احتمال ماندن زیر اعمال " + f"{a['model_probability']['prob_under_strike_pct']}٪") + method = "قطعی + مدل بلک-شولز (نوسان ضمنی از قیمت بازار)" + else: + value, method = "ندارد", "بدون دادهٔ عددی امروز (از منبع یا ورودی شما)" + rows.append({"id": s["id"], "name": s["name"], "class": s["class"], + "value": value, "method": method, + "resilience": a.get("resilience_pct"), "survives": a.get("survives"), + "closing_count": len(a.get("closing") or s.get("closing") or [])}) + return rows + + +def study_path() -> list[str]: + return [ + "۱. اول مفهوم «خط پایه» را بفهم: نرخ مؤثر اوراق/صندوق درآمد ثابت. هر چیزی که از آن " + "نگذرد، ارزش ریسک ندارد (سند: راهبرد اهرمی/درآمد ثابت، همین جزوه فصل ۶).", + "۲. بعد «قفل‌شده» را یاد بگیرید: مبنا و تبعی. این‌ها عددِ لحظهٔ ورود دارند، نه پیش‌بینی.", + "۳. بعد «پرمیوم» را: پوشش‌داده‌شده. این‌جا اولین بار احتمال (نوسان ضمنی) وارد می‌شود.", + "۴. بعد «چهارپایه» را: باکس و تساوی. این‌ها کارمزد و نقدشوندگی را به شما نشان می‌دهند.", + "۵. آخر «بقا»: کارگاه فروش پوت بدون پوشش + ریاضیِ ورشکستگی (فایل bankroll). اگر این را " + "یاد بگیرید، بقیه امن است.", + ] + + +def build(*, rows: list[dict] | None = None, write: bool = True) -> dict: + audits = {} + for s in STRATEGIES: + if s["id"] in NUMERIC_KINDS: + audits[s["id"]] = audit_strategy(s["id"], rows) + table = as_percent_table(audits) + doc = {"version": VERSION, "strategies": [{k: v for k, v in s.items()} for s in STRATEGIES], + "audits": audits, "table": table, "study_path": study_path(), + "honesty": ("درصدها سه نوع‌اند و برچسب دارند: «قطعی» (قفل‌شده در لحظهٔ ورود)، " + "«مدل‌محور» (با نوسان ضمنیِ خودِ بازار و فرض بلک-شولز)، و «نقل‌شده» " + "(از منبع با نام). هیچ‌کدام وعدهٔ سود نیست."), + "md_text": "", "ref_md": "", "index_md": ""} + doc["md_text"] = to_md(doc) + doc["ref_md"] = references_md(doc) + doc["index_md"] = index_md(doc) + if write: + OUT.mkdir(parents=True, exist_ok=True) + LIB_MD.write_text(doc["md_text"], encoding="utf-8") + REF_MD.write_text(doc["ref_md"], encoding="utf-8") + INDEX_MD.write_text(doc["index_md"], encoding="utf-8") + LIB_JSON.write_text(json.dumps(doc, ensure_ascii=False, indent=1), encoding="utf-8") + GUI_DATA.mkdir(parents=True, exist_ok=True) + (GUI_DATA / "strategy-library.html").write_text(to_html(doc), encoding="utf-8") + doc.update({"md": str(LIB_MD), "html": str(GUI_DATA / "strategy-library.html"), + "json": str(LIB_JSON), "refs": str(REF_MD), "index": str(INDEX_MD)}) + return doc + + +def to_md(doc: dict) -> str: + L = [f"# جزوهٔ راهبردهای موفق — با درصد، قاعدهٔ بستن و حسابرسی — نسخهٔ {VERSION}", "", + f"> {doc['honesty']}", "", + "## ۰. راهنمای خواندن این جزوه", ""] + L += [f"- {x}" for x in doc["study_path"]] + L += ["", "## ۱. جدول یک‌نگاهی", "", + "| راهبرد | دسته | عدد امروز | روش عدد | تاب‌آوری زیر شوک | حد بستن |", + "| --- | --- | --- | --- | --- | --- |"] + for t in doc["table"]: + res = "سنجیده نشد" if t["resilience"] is None else f"{t['resilience']:.0f}٪" + L.append(f"| {t['name']} | {t['class']} | {t['value']} | {t['method']} | {res} | " + f"{t['closing_count']} حد |") + for i, s in enumerate(doc["strategies"], start=2): + a = doc["audits"].get(s["id"], {}) + L += ["", f"## {i}. {s['name']} ({s['en']})", "", + f"**دسته:** {s['class']}", "", + "### اصل کار", s["idea"], "", + "### چه وقت استفاده می‌شود", s["when"], "", + "### چه چیزی لازم دارد", s["requires"], "", + "### قاعدهٔ بستن موقعیت", ""] + L += [f"- {c}" for c in s["closing"]] + L += ["", "### ریسک‌ها", ""] + L += [f"- {r}" for r in s["risks"]] + if a.get("ok"): + L += ["", "### حسابرسی عددهای امروز (با موتور ایستگاه)", "", + f"- عددهای ورودی: " + " · ".join(f"{g[0]} {g[1]}" for g in a["given"]), + f"- فرمول: {a['formula']}", + f"- **پاسخ موتور:** {a['answer']} {a['unit']}", + f"- محاسبهٔ دستی دوم: {a['hand_value']} — " + f"{'موافق ✅' if a['hand_agrees'] else 'مخالف ⚠️ (باید بررسی شود)'}"] + for st in a["steps"]: + L.append(f" - {st}") + L += [f"- کارمزد لحاظ‌شده: {a['fees_pct']}٪ · نرخ سد: {a['hurdle_pct']}٪ · " + f"حاشیه: {a['margin_pp']} واحد درصد", + f"- داوری: {a['verdict']}"] + if a.get("fee_tolerance"): + L.append(f"- تحمل کارمزد: {a['fee_tolerance']['detail']}") + mg = a.get("margin_call") or {} + if mg.get("ok"): + L.append(f"- فاصله تا اخطاریهٔ مارجین‌کال: {mg['move_pct']:.2f}٪ حرکت مخالف " + f"(پول در معرض خطر: {mg['money_at_risk']:,.0f} ریال بر پایهٔ " + f"{mg['maintenance_pct']}٪ حد نگهداری)") + if a.get("model_probability"): + L.append(f"- احتمال مدل‌محور: {a['model_probability'].get('detail', '')}") + L += ["", f"### تاب‌آوری زیر شوک‌ها ({a.get('resilience_pct')}٪ شوک‌ها را رد کرد)", "", + "| شوک | نتیجه | می‌ماند؟ |", "| --- | --- | --- |"] + for sh in (a.get("shocks") or []): + L.append(f"| {sh['shock']} | {sh['value']} | {'بله' if sh['survives'] else 'نه'} |") + L += ["", "### منابع", ""] + L += [f"- {r}" for r in s["refs"]] + L += ["", "## پیوست: منابع، اعتبار و محدودیت‌ها", "", + "فهرست کامل منابع و محدودیت‌های این جزوه در پروندهٔ `references-fa.md` در همین پوشه " + "آمده است؛ هر عددی که برچسب روش ندارد، قابل استناد نیست.", "", + CREDIT, ""] + return "\n".join(L) + + +def to_html(doc: dict) -> str: + body = [f'
    {rk.esc(doc["honesty"])}
    ', + "

    ۰. راهنمای خواندن

      "] + for x in doc["study_path"]: + body.append(f"
    • {rk.esc(x)}
    • ") + body += ["

    ۱. جدول یک‌نگاهی

    ", + '' + ''] + for t in doc["table"]: + res = "سنجیده نشد" if t["resilience"] is None else f"{t['resilience']:.0f}٪" + body.append(f'' + f'' + f'') + body.append("
    راهبرددستهعدد امروزروش عددتاب‌آوریحد بستن
    {rk.esc(t["name"])}{rk.esc(t["class"])}{rk.esc(t["value"])}{rk.esc(t["method"])}{res}{t["closing_count"]}
    ") + for s in doc["strategies"]: + a = doc["audits"].get(s["id"], {}) + body.append(f'

    {rk.esc(s["name"])} ({rk.esc(s["en"])})

    ') + body.append(f'

    {rk.esc(s["class"])}

    ') + body.append(f'

    اصل کار: {rk.esc(s["idea"])}

    ') + body.append(f'

    چه وقت: {rk.esc(s["when"])}

    ') + body.append(f'

    چه لازم دارد: {rk.esc(s["requires"])}

    ') + body.append("

    قاعدهٔ بستن موقعیت:

      ") + for c in s["closing"]: + body.append(f"
    • {rk.esc(c)}
    • ") + body.append("

    ریسک‌ها:

      ") + for r in s["risks"]: + body.append(f"
    • {rk.esc(r)}
    • ") + body.append("
    ") + if a.get("ok"): + body.append("

    حسابرسی عددها (موتور ایستگاه + دستی):

    ") + body.append('' + f'' + f'' + f'' + f'' + f'' + '
    عددهای ورودی{rk.esc(" · ".join(f"{g[0]} {g[1]}" for g in a["given"]))}
    فرمول{rk.esc(a["formula"])}
    پاسخ موتور{rk.esc(str(a["answer"]))} ' + f'{rk.esc(a["unit"])}
    محاسبهٔ دستی{rk.esc(str(a["hand_value"]))} — ' + f'{"موافق ✅" if a["hand_agrees"] else "مخالف ⚠️"}
    کارمزد / نرخ سد / حاشیه{a["fees_pct"]}٪ / ' + f'{a["hurdle_pct"]}٪ / {a["margin_pp"]}
    ') + if a.get("model_probability"): + body.append(f'

    {rk.esc(a["model_probability"].get("detail", ""))}

    ') + mg = a.get("margin_call") or {} + if mg.get("ok"): + body.append(f'

    مارجین‌کال: با {mg["move_pct"]:.2f}٪ حرکت مخالف، ' + f'حساب به حد نگهداری می‌رسد؛ پول در معرض خطر {mg["money_at_risk"]:,.0f} ' + f'ریال.

    ') + body.append(f'

    تاب‌آوری زیر شوک: {a.get("resilience_pct")}٪ ' + f'(اولین شوک: {rk.esc(str(a.get("first_failure") or "—"))})

    ') + body.append("

    منابع: " + rk.esc(" | ".join(s["refs"])) + "

    ") + body.append(f'

    پیوست

    فهرست کامل منابع و محدودیت‌ها در فایل ' + f'references-fa.md همین پوشه است.

    ') + body.append(f'

    {CREDIT}

    ') + return rk.page("جزوهٔ راهبردهای موفق", "".join(body), + subtitle=f"{len(doc['strategies'])} راهبرد · حسابرسی دو-روشی · نسخهٔ {VERSION}") + + +def references_md(doc: dict) -> str: + L = ["# منابع و اعتبارسنجی عددها", "", + "سه دسته منبع داریم و برچسب هر عدد می‌گوید از کدام دسته آمده. منابع تبلیغاتی " + "(که درصد موفقیت وعده می‌دهند) عمداً حذف شده‌اند؛ چیزی که قابل راستی‌آزمایی نباشد، " + "در این جزوه عدد نیست.", "", + "## ۱. منبع خودِ برنامه (بازتولیدپذیر)", "", + "- موتور ایستگاه (`tools/derivatives_scout.py`) + آزمون دو-روشی: هر عدد با یک محاسبهٔ " + "دستی دوم (کسری دقیق) مقایسه می‌شود و در جدول «موافق/مخالف» علامت می‌خورد.", + "- آزمون تاب‌آوری (`edge_stress.py`): هر راهبرد زیر ۵ شوک واقعی سنجیده می‌شود.", + "- فایل‌های شاهد: `data/edge-stress.html`، `data/witness-live.html`، " + "`data/investor-ladder.md`.", "", + "## ۲. منابع بیرونی استفاده‌شده (با نام، برای قواعد بازار)", ""] + for i, r in enumerate(sorted({ref for s in doc["strategies"] for ref in s["refs"]}), start=1): + L.append(f"{i}. {r}") + L += ["", "## ۳. قواعد بازار که عددها روی آن‌ها بسته شده", "", + "- کارمزد سهم: خرید ۰٫۴۶۴٪ و فروش ۰٫۹۶۴٪ (گزارش کارگزاری‌ها و خانِ سرمایه).", + "- کارمزد اختیار: ≈۰٫۱۰۳٪ هر طرف · اعمال ۰٫۰۵٪ × قیمت اعمال (دو طرف).", + "- وجه تضمین: فروشندهٔ اختیار ≈۲۰٪ ارزش قرارداد؛ حداقل وجه تضمین ۷۰٪ وجه تضمین اولیه؛ " + "اخطاریهٔ مارجین‌کال و مهلت ۲۴ ساعت؛ تسویهٔ روزانه بر پایهٔ قیمت تسویه.", + "- تسویهٔ آتی بر پایهٔ میانگین وزنی نیم‌ساعت پایانی روز آخر است.", + "- مالیات: معاملات مشتقه معاف؛ فروش فیزیکی کالا ۰٫۵٪.", + "- ممنوعیت معاملات الگوریتمی برای مشتریان برخط (ابلاغیهٔ مهر ۱۳۹۹، «تا اطلاع ثانوی») " + "— به همین دلیل این ایستگاه هیچ سفارشی نمی‌فرستد.", "", + "## ۴. چطور عددهای این جزوه را خودتان بازتولید کنید (سه فرمان)", "", + "۱. جزوه و شوک‌آزمون را بسازید: `python3 strategy_audit.py` و سپس " + "`python3 edge_stress.py` (هر دو در پوشهٔ `gui`).", + "۲. ریاضیِ بقا و مسیر رشد را ببینید: `python3 bankroll.py --capital 100000000 " + "--target 400000000`.", + "۳. آزمون‌ها را اجرا کنید: `python3 -m unittest discover -s tests -q`؛ اگر همه سبز شد، " + "عددهای این جزوه روی همین ماشین بازتولید شدند.", "", + "## ۵. واژه‌نامهٔ برچسب‌های روش", "", + "- «قطعی» یعنی پرداخت یا تعهد در همان لحظهٔ وارد‌شدن مشخص است (تبعی، باکس، مبنا).", + "- «مدل‌محور» یعنی با فرض حرکت لگنرمال و نوسانِ ضمنیِ استخراج‌شده از قیمت خودِ بازار " + "حساب شده است؛ این فرض می‌تواند غلط باشد و عدد را باید «تخمین» خواند، نه واقعیت.", + "- «نقل‌شده» یعنی از منبع بیرونی آمده و نام منبع کنارش نوشته شده است.", "", + "## ۶. محدودیت‌های صادقانه این جزوه", "", + "- دادهٔ تاریخی بلند و معتبر در این محیط در دسترس نبود؛ پس **هیچ درصد «برد تاریخی» " + "ادعا نمی‌کنیم**. آنچه می‌دهیم: عددهای قفل‌شدهٔ لحظهٔ ورود، احتمال مدل‌محور با نوسان " + "ضمنی خودِ بازار، و نرخ‌های نقل‌شده با نام منبع.", + "- «نرخ تاب‌آوری» احتمال سود نیست؛ سهم شوک‌هایی است که راهبرد از آن‌ها سالم بیرون آمده.", + "- عددهای امروز به اسنپ‌شات امروز شما بسته‌اند؛ فردا عوض می‌شوند. برای روز خودتان، " + "همین اسکریپت را اجرا کنید.", "", + "", CREDIT] + return "\n".join(L) + + +def index_md(doc: dict) -> str: + return "\n".join([ + "# پوشهٔ راهبردها — از کجا شروع کنم؟", "", + "| پرونده | چیست |", "| --- | --- |", + "| `strategy-library-fa.md` | جزوهٔ کامل: هر راهبرد، اصل، قاعدهٔ بستن، ریسک، حسابرسی عدد |", + "| `strategy-library.html` | همان جزوه، چاپی و خوانا (برای پرینت گرفتن و مطالعه) |", + "| `strategy-library.json` | دادهٔ ماشین‌خوان همین جزوه (برای برنامه‌نویسی) |", + "| `references-fa.md` | منابع، قواعد بازار، و محدودیت‌های صادقانه |", "", + "## سه برچسب عدد (اگر این را بفهمید، بقیه روشن می‌شود)", "", + "- «قطعی»: عدد در لحظهٔ وارد‌شدن قفل می‌شود. مثل کمینهٔ بازده تبعی و پرداخت ثابت باکس.", + "- «مدل‌محور»: عدد با فرض حرکت لگنرمال و نوسانِ ضمنیِ خودِ بازار حساب می‌شود. تخمین است، " + "نه پیش‌بینی.", + "- «نقل‌شده»: از منبع بیرونی با نام منبع. اگر برچسب نبود، عدد به کار نمی‌آید.", + "", "## چطور خودم عددها را بسازم؟", "", + "- در رابط مرورگری به گام ۱۱ بروید و «ساخت جزوه + شوک‌آزمون» را بزنید.", + "- یا در خط فرمان: `python3 strategy_audit.py` و `python3 edge_stress.py` و " + "`python3 bankroll.py`.", + "- آزمون‌ها: `python3 -m unittest discover -s tests -q` — اگر سبز شد، عددها بازتولید شدند.", + "", "## مسیر مطالعهٔ پیشنهادی", ""] + [f"- {x}" for x in doc["study_path"]] + [ + "", "> هر عددی که می‌خوانی، برچسب روش دارد: «قطعی» / «مدل‌محور» / «نقل‌شده». " + "اگر عددی برچسب نداشت، به آن استناد نکنید.", "", + "", CREDIT, ""]) + + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description="کتابخانهٔ راهبردها + حسابرسی عددها") + ap.add_argument("--json", action="store_true") + ap.add_argument("--no-write", action="store_true") + a = ap.parse_args(argv) + doc = build(write=not a.no_write) + if a.json: + print(json.dumps({k: v for k, v in doc.items() if not k.endswith("_md")}, + ensure_ascii=False, indent=1)) + return 0 + print(f"جزوهٔ راهبردها — {len(doc['strategies'])} راهبرد · نسخهٔ {VERSION}") + for t in doc["table"]: + print(f" · {t['name']}: {t['value']} — {t['method'][:52]}" + + (f" · تاب‌آوری {t['resilience']:.0f}٪" if t["resilience"] is not None else "")) + print(" جزوه:", doc.get("md")) + print(" نسخهٔ چاپی:", doc.get("html")) + print(" منابع:", doc.get("refs")) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/station/tests/test_adminauth.py b/station/tests/test_adminauth.py new file mode 100644 index 0000000000000000000000000000000000000000..b5199a7d3b1f4a3ea462f4e8a6585ada85b9a1a6 --- /dev/null +++ b/station/tests/test_adminauth.py @@ -0,0 +1,122 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""آزمون‌های پنل مدیریت: هش رمز، توکن، انقضا، محدودیت تلاش، و متغیر محیطی. + +هیچ آزمونی پروندهٔ واقعی `config/admin.json` را دست نمی‌زند؛ همه در پوشهٔ موقتی کار می‌کنند. +""" + +import json +import os +import pathlib +import sys +import tempfile +import unittest +from unittest import mock + +BASE = pathlib.Path(__file__).resolve().parents[1] +if str(BASE) not in sys.path: + sys.path.insert(0, str(BASE)) + +import adminauth as aa # noqa: E402 + +# رمز آزمونی: از محیط می‌آید یا هر بار ساخته می‌شود. هیچ رمز واقعی در این پرونده نیست، +# چون این پرونده در بسته‌های تحویلی هم می‌رود و نمی‌شود رمز واقعی کسی را با خودش برد. +ADMIN_PASS = os.environ.get("STATION_TEST_ADMIN_PASS") or "Test-Admin-" + __import__("secrets").token_hex(4) + + +class Credentials(unittest.TestCase): + def setUp(self): + self.tmp = tempfile.TemporaryDirectory() + self.cfg = pathlib.Path(self.tmp.name) / "admin.json" + os.environ.pop("STATION_ADMIN_ID", None) + os.environ.pop("STATION_ADMIN_PASS", None) + + def tearDown(self): + self.tmp.cleanup() + + def test_password_is_never_stored_in_plain_text(self): + aa.set_credentials("mafhoom", ADMIN_PASS, path=self.cfg) + raw = self.cfg.read_text(encoding="utf-8") + self.assertNotIn(ADMIN_PASS, raw) + self.assertIn("hash", json.loads(raw)) + + def test_correct_pair_passes_and_wrong_pair_fails(self): + aa.set_credentials("mafhoom", ADMIN_PASS, path=self.cfg) + self.assertTrue(aa.verify_credentials("mafhoom", ADMIN_PASS, path=self.cfg)) + self.assertFalse(aa.verify_credentials("mafhoom", "غلط", path=self.cfg)) + self.assertFalse(aa.verify_credentials("دیگری", ADMIN_PASS, path=self.cfg)) + + def test_short_password_is_refused(self): + with self.assertRaises(ValueError): + aa.set_credentials("mafhoom", "123", path=self.cfg) + self.assertFalse(self.cfg.exists()) + + def test_env_pair_overrides_file(self): + aa.set_credentials("mafhoom", ADMIN_PASS, path=self.cfg) + with mock.patch.dict(os.environ, {"STATION_ADMIN_ID": "بهرام", + "STATION_ADMIN_PASS": "P@ssw0rdX"}): + self.assertTrue(aa.verify_credentials("بهرام", "P@ssw0rdX", path=self.cfg)) + self.assertFalse(aa.verify_credentials("mafhoom", ADMIN_PASS, path=self.cfg)) + + def test_missing_config_is_not_configured(self): + self.assertFalse(aa.is_configured(self.cfg)) + self.assertFalse(aa.verify_credentials("mafhoom", ADMIN_PASS, path=self.cfg)) + out = aa.login("mafhoom", ADMIN_PASS, path=self.cfg) + self.assertFalse(out["ok"]) + self.assertIn("شناسه و رمز پنل", out["error"]) + + +class Tokens(unittest.TestCase): + def setUp(self): + aa.SESSIONS.clear() + aa.FAILS.clear() + + def test_token_lifecycle_and_sliding_expiry(self): + tok = aa.issue_token("mafhoom", now=1000.0) + self.assertTrue(aa.check_token(tok, now=1000.0)) + self.assertTrue(aa.check_token(tok, now=1000.0 + aa.TOKEN_TTL_SECONDS - 1)) + self.assertFalse(aa.check_token(tok, now=1000.0 + 2 * aa.TOKEN_TTL_SECONDS)) + self.assertFalse(aa.check_token("چیزنامعتبر")) + self.assertFalse(aa.check_token(None)) + + def test_revoke_and_unknown_token(self): + tok = aa.issue_token("mafhoom") + self.assertTrue(aa.revoke_token(tok)) + self.assertFalse(aa.check_token(tok)) + self.assertFalse(aa.revoke_token("نبود")) + + +class RateLimit(unittest.TestCase): + def setUp(self): + aa.SESSIONS.clear() + aa.FAILS.clear() + self.tmp = tempfile.TemporaryDirectory() + self.cfg = pathlib.Path(self.tmp.name) / "admin.json" + aa.set_credentials("mafhoom", ADMIN_PASS, path=self.cfg) + + def tearDown(self): + self.tmp.cleanup() + + def test_five_wrong_tries_lock_the_window(self): + for i in range(aa.FAIL_LIMIT): + out = aa.login("mafhoom", "غلط", ip="1.2.3.4", path=self.cfg, now=1000.0) + self.assertFalse(out["ok"]) + locked = aa.login("mafhoom", ADMIN_PASS, ip="1.2.3.4", path=self.cfg, now=1000.0) + self.assertTrue(locked.get("rate_limited")) + later = aa.login("mafhoom", ADMIN_PASS, ip="1.2.3.4", path=self.cfg, + now=1000.0 + aa.FAIL_WINDOW_SECONDS + 1) + self.assertTrue(later["ok"], "بعد از پنجرهٔ قفل باید دوباره باز شود") + self.assertTrue(later["token"]) + + def test_successful_login_clears_failures(self): + aa.login("mafhoom", "غلط", ip="9.9.9.9", path=self.cfg) + aa.login("mafhoom", ADMIN_PASS, ip="9.9.9.9", path=self.cfg) + self.assertFalse(aa.rate_limited("9.9.9.9")) + + def test_session_counter(self): + aa.login("mafhoom", ADMIN_PASS, ip="7.7.7.7", path=self.cfg) + self.assertEqual(aa.active_tokens(), 1) + + +if __name__ == "__main__": + unittest.main(verbosity=2) diff --git a/station/tests/test_autoconnect.py b/station/tests/test_autoconnect.py new file mode 100644 index 0000000000000000000000000000000000000000..526340a0e1286a74c15a6b2f0841588d6d8c7d3a --- /dev/null +++ b/station/tests/test_autoconnect.py @@ -0,0 +1,273 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""آزمون «اتصال خودکار»: پیدا کردن منبع سالم، سنجش عدد، و ذخیرهٔ برنده. + +سرویس‌های واقعی از این‌طرف مرزها در دسترس نیستند، پس اینجا سرویس‌های تقلبی محلی +با همان شکل پاسخ ساخته می‌شوند تا منطق تصمیم‌گیری برنامه آزموده شود. +""" +from __future__ import annotations + +import json +import sys +import tempfile +import threading +import unittest +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer +from pathlib import Path + +BASE = Path(__file__).resolve().parent.parent +sys.path.insert(0, str(BASE)) + +import autoconnect as ac # noqa: E402 +import connections as conn # noqa: E402 +import mock_feed # noqa: E402 + + +class FakeService(BaseHTTPRequestHandler): + protocol_version = "HTTP/1.1" + + def log_message(self, *a): + pass + + def _send(self, body: bytes, ctype="application/json; charset=utf-8", code=200): + self.send_response(code) + self.send_header("Content-Type", ctype) + self.send_header("Content-Length", str(len(body))) + self.end_headers() + self.wfile.write(body) + + def do_GET(self): + path = self.path.split("?")[0] + if path == "/tgju-like": + return self._send(json.dumps({"data": [{"p": "1,234,567"}]}).encode()) + if path == "/nested-like": + return self._send(json.dumps({"response": {"quote": {"last": 92_500}}}).encode()) + if path == "/html-like": + return self._send(b"blocked", "text/html; charset=utf-8") + if path == "/empty-like": + return self._send(json.dumps({"data": []}).encode()) + if path == "/timestamp-like": + return self._send(json.dumps({"data": [{"p": 1_760_000_000_000}]}).encode()) + if path == "/search-ok": + return self._send(json.dumps({"instrumentSearch": [{"insCode": "46348559193224090"}]}).encode()) + if path == "/search-empty": + return self._send(json.dumps({"instrumentSearch": []}).encode()) + if path.startswith("/quote-ok/"): + return self._send(json.dumps({"closingPriceDaily": [{"pClosing": 7_050}]}).encode()) + return self._send(b"{}", code=404) + + +def candidate(base: str, path: str, **kw) -> dict: + cand = {"name": kw.pop("name", "c-1"), "label": kw.pop("label", "داوطلب"), + "url_template": base + path, "paths": kw.pop("paths", ["data.0.p"]), + "plausible": kw.pop("plausible", (10, 500_000_000))} + cand.update(kw) + return cand + + +class JudgeTests(unittest.TestCase): + def test_plausible_price_passes(self): + ok, why = ac.judge(1_234_567.0, (10_000, 500_000_000)) + self.assertTrue(ok, why) + + def test_zero_and_negative_rejected(self): + self.assertFalse(ac.judge(0.0, (1, 10))[0]) + self.assertFalse(ac.judge(-5.0, (1, 10))[0]) + + def test_timestamp_rejected(self): + ok, why = ac.judge(1_760_000_000_000.0, (10, 500_000_000)) + self.assertFalse(ok) + self.assertTrue("تاریخ" in why or "بیرون بازه" in why) + + def test_missing_value_rejected(self): + self.assertFalse(ac.judge(None, (1, 10))[0]) + + +class TryCandidateTests(unittest.TestCase): + @classmethod + def setUpClass(cls): + cls.httpd = ThreadingHTTPServer(("127.0.0.1", 0), FakeService) + cls.port = cls.httpd.server_address[1] + cls.base = f"http://127.0.0.1:{cls.port}" + threading.Thread(target=cls.httpd.serve_forever, daemon=True).start() + + @classmethod + def tearDownClass(cls): + cls.httpd.shutdown() + cls.httpd.server_close() + + def test_finds_value_on_first_path(self): + res = ac.try_candidate(candidate(self.base, "/tgju-like")) + self.assertTrue(res["ok"], res["reason"]) + self.assertEqual(res["json_path"], "data.0.p") + self.assertEqual(res["value"], 1_234_567.0) + + def test_falls_back_to_next_path(self): + res = ac.try_candidate(candidate(self.base, "/nested-like", + paths=["data.0.p", "response.quote.last"])) + self.assertTrue(res["ok"], res["reason"]) + self.assertEqual(res["json_path"], "response.quote.last") + + def test_html_response_is_reported_as_json_problem(self): + res = ac.try_candidate(candidate(self.base, "/html-like")) + self.assertFalse(res["ok"]) + self.assertIn("JSON", res["reason"]) + + def test_empty_list_is_reported(self): + res = ac.try_candidate(candidate(self.base, "/empty-like")) + self.assertFalse(res["ok"]) + self.assertIn("مسیر عدد سالم پیدا نشد", res["reason"]) + + def test_timestamp_is_rejected_with_reason(self): + res = ac.try_candidate(candidate(self.base, "/timestamp-like")) + self.assertFalse(res["ok"]) + self.assertIn("بازهٔ باورپذیر", res["reason"]) + + def test_symbol_code_is_resolved_then_used(self): + cand = candidate(self.base, "/quote-ok/{symbol}", name="tsetmc-like", + paths=["closingPriceDaily.0.pClosing"], needs_code=True, + search_url=self.base + "/search-ok?q={symbol}", + search_paths=["instrumentSearch.0.insCode"]) + res = ac.try_candidate(cand) + self.assertTrue(res["ok"], res["reason"]) + self.assertEqual(res["resolved_code"], "46348559193224090") + self.assertIn("46348559193224090", res["url"]) + + def test_missing_code_is_reported(self): + cand = candidate(self.base, "/quote-ok/{symbol}", name="tsetmc-like", + needs_code=True, search_url=self.base + "/search-empty", + search_paths=["instrumentSearch.0.insCode"]) + res = ac.try_candidate(cand) + self.assertFalse(res["ok"]) + self.assertIn("کد نماد", res["reason"]) + + def test_network_can_be_disabled(self): + res = ac.try_candidate(candidate(self.base, "/tgju-like"), allow_network=False) + self.assertFalse(res["ok"]) + self.assertIn("شبکه", res["reason"]) + + def test_works_against_the_local_demo_feed(self): + """همان مسیری که کاربر با خوراک آزمایشی می‌رود هم باید سالم تشخیص داده شود.""" + httpd = mock_feed.serve(0) + try: + threading.Thread(target=httpd.serve_forever, daemon=True).start() + port = httpd.server_address[1] + res = ac.try_candidate(candidate(f"http://127.0.0.1:{port}", "/quote?symbol={symbol}", + paths=["data.0.p", "data.0.pl"])) + finally: + httpd.shutdown() + httpd.server_close() + self.assertTrue(res["ok"], res["reason"]) + + +class CodeEnrichmentTests(unittest.TestCase): + @classmethod + def setUpClass(cls): + cls.httpd = ThreadingHTTPServer(("127.0.0.1", 0), FakeService) + cls.port = cls.httpd.server_address[1] + cls.base = f"http://127.0.0.1:{cls.port}" + threading.Thread(target=cls.httpd.serve_forever, daemon=True).start() + + @classmethod + def tearDownClass(cls): + cls.httpd.shutdown() + cls.httpd.server_close() + + def _cand(self, search="/search-ok"): + return {"name": "tsetmc-like", "label": "شبیه‌ساز tsetmc", "needs_code": True, + "url_template": self.base + "/quote-ok/{symbol}", + "search_url": self.base + search + "?q={symbol}", + "search_paths": ["instrumentSearch.0.insCode"]} + + def test_codes_are_written_into_rows(self): + rows = [{"symbol": "اهرم", "kind": "basis", "spot": 20000}, + {"symbol": "فولاد", "kind": "basis", "spot": 7000}] + out, notes = ac.enrich_snapshot_with_codes(rows, self._cand()) + self.assertTrue(all(r.get("feed_symbol") == "46348559193224090" for r in out)) + self.assertEqual(len(notes), 2) + + def test_existing_code_is_not_overwritten(self): + rows = [{"symbol": "اهرم", "kind": "basis", "feed_symbol": "999"}] + out, notes = ac.enrich_snapshot_with_codes(rows, self._cand()) + self.assertEqual(out[0]["feed_symbol"], "999") + self.assertEqual(notes, []) + + def test_missing_code_is_reported_not_invented(self): + rows = [{"symbol": "اهرم", "kind": "basis"}] + out, notes = ac.enrich_snapshot_with_codes(rows, self._cand(search="/search-empty")) + self.assertNotIn("feed_symbol", out[0]) + self.assertTrue(any("دستی" in n for n in notes)) + + def test_non_code_candidate_is_untouched(self): + rows = [{"symbol": "اهرم", "kind": "basis"}] + out, notes = ac.enrich_snapshot_with_codes(rows, {"name": "x", "label": "y"}) + self.assertEqual(out, rows) + self.assertEqual(notes, []) + + +class AutoConnectFlowTests(unittest.TestCase): + @classmethod + def setUpClass(cls): + cls.httpd = ThreadingHTTPServer(("127.0.0.1", 0), FakeService) + cls.port = cls.httpd.server_address[1] + cls.base = f"http://127.0.0.1:{cls.port}" + threading.Thread(target=cls.httpd.serve_forever, daemon=True).start() + + @classmethod + def tearDownClass(cls): + cls.httpd.shutdown() + cls.httpd.server_close() + + def setUp(self): + self.tmp = tempfile.TemporaryDirectory() + self.dir = Path(self.tmp.name) + self._old = (conn.CONFIG_DIR, conn.PROFILES_FILE, conn.KEYS_FILE) + conn.CONFIG_DIR = self.dir + conn.PROFILES_FILE = self.dir / "connections.json" + conn.KEYS_FILE = self.dir / "keys.local.json" + + def tearDown(self): + conn.CONFIG_DIR, conn.PROFILES_FILE, conn.KEYS_FILE = self._old + self.tmp.cleanup() + + def test_first_working_candidate_wins(self): + cands = [candidate(self.base, "/html-like", name="bad", label="خراب"), + candidate(self.base, "/tgju-like", name="good", label="سالم")] + rep = ac.autoconnect(candidates=cands) + self.assertTrue(rep["ok"]) + self.assertEqual(rep["count_ok"], 1) + self.assertEqual(rep["winner"]["name"], "good") + self.assertIn("سالم", rep["summary"]) + + def test_all_failing_is_reported_honestly(self): + cands = [candidate(self.base, "/html-like", name="a"), candidate(self.base, "/empty-like", name="b")] + rep = ac.autoconnect(candidates=cands) + self.assertFalse(rep["ok"]) + self.assertIn("هیچ‌کدام", rep["summary"]) + self.assertEqual(len(rep["results"]), 2) + + def test_save_creates_and_selects_profile(self): + cands = [candidate(self.base, "/tgju-like", name="winner-x", label="برنده", + profile_label="برندهٔ آزمون")] + rep = ac.autoconnect(candidates=cands, save=True) + self.assertTrue(rep["ok"]) + self.assertIsNotNone(rep["saved"]) + store = conn.load_store() + self.assertEqual(store["selected"], "winner-x") + prof = conn.find_profile(store, "winner-x") + self.assertTrue(prof["tested"]) + self.assertEqual(prof["json_path"], "data.0.p") + + def test_report_text_mentions_each_candidate(self): + cands = [candidate(self.base, "/tgju-like", name="ok1", label="اول"), + candidate(self.base, "/html-like", name="bad1", label="دوم")] + rep = ac.autoconnect(candidates=cands) + text = ac.format_report(rep) + self.assertIn("اول", text) + self.assertIn("دوم", text) + self.assertIn("✓", text) + self.assertIn("✗", text) + + +if __name__ == "__main__": + unittest.main() diff --git a/station/tests/test_backpack.py b/station/tests/test_backpack.py new file mode 100644 index 0000000000000000000000000000000000000000..29719f328302044f65749226b93d980ac0a44e42 --- /dev/null +++ b/station/tests/test_backpack.py @@ -0,0 +1,279 @@ +"""آزمون «کوله‌پشتی دمو» — بسته‌ای که بدون اینترنت کار می‌کند. + +چرا این آزمون‌ها مهم‌اند: در اینترنت محدود ایران، نمایش کارفرما نباید به هیچ لینک بیرونی گره بخورد. +پس سه چیز را می‌سنجیم: (۱) ساختار بسته درست است؛ (۲) **نمونهٔ ثابت روی فایل محلی** (بدون شبکه) +در jsdom بالا می‌آید و همهٔ گام‌ها باز می‌شوند؛ (۳) برنامهٔ زنده روی شبکهٔ محلی بالا می‌آید و +دروازه‌اش کار می‌کند و رمزهای اولین اجرا خودشان ساخته می‌شوند. + +همه‌چیز در پوشهٔ موقت ساخته و آزموده می‌شود؛ چیزی از بستهٔ اصلی (delivery) دست‌کاری نمی‌شود. +""" +from __future__ import annotations + +import json +import os +import re +import socket +import subprocess +import sys +import tempfile +import time +import unittest +import urllib.error +import urllib.request +from pathlib import Path + +BASE = Path(__file__).resolve().parents[1] # .../money/gui +TOOLING_NEEDED = ("make_backpack.py", "deploy/huggingface/make_demo_site.py") + + +# ── نگهبان بستهٔ تحویلی ───────────────────────────────────────────────────── +# این آزمون به ابزارهای «ساخت بسته» در پوشهٔ deploy نیاز دارد. آن ابزارها عمداً داخل بستهٔ +# تحویلی شرکت نیستند؛ پس اگر نبودند، باید تمیز «رد» شود نه اینکه هنگام بارگذاری بترکد +# (وگرنه «گزارش عیب‌یابی» در خودِ بسته، آزمون‌ها را سرخ نشان می‌دهد). +def _tooling_ready() -> tuple[bool, str]: + for rel in TOOLING_NEEDED: + if not (BASE / rel).exists(): + return False, f"ابزار ساخت در این بسته نیست: {rel}" + return True, "" + + +TOOLING_OK, WHY_NO_TOOLING = _tooling_ready() + +sys.path.insert(0, str(BASE)) # خودِ سازندهٔ کوله‌پشتی +sys.path.insert(0, str(BASE / "deploy")) +try: # بستهٔ تحویلی: ابزار ساخت نیست + from security_scan import find_secret_literals + import make_backpack as BP +except Exception as _e: # noqa: BLE001 + find_secret_literals = None + BP = None + _IMPORT_ERROR = f"{type(_e).__name__}: {_e}" + +DEMO_READY = bool(BP) and BP.demo_ready() # در بستهٔ تحویلی نمونهٔ ثابت نیست → آزمون «رد» می‌شود +WHY_SKIP = "نمونهٔ ثابت دمو در این بسته نیست (اول make_demo_site.py)" + +def build_or_skip(out, **kw): + """ساخت کوله‌پشتی؛ اگر پیش‌نیازش در این بسته نبود «رد» می‌شویم، نه «خطا».""" + try: + return BP.build(out, **kw) + except SystemExit as e: + raise unittest.SkipTest(str(e)) + +def jsdom_available() -> bool: + """jsdom از افزوده‌های بیرونی است و در پیمان‌های کاری (snapshot) نگه داشته نمی‌شود.""" + for base in (Path("/home/user"), Path(__file__).resolve().parents[1]): + if (base / "node_modules" / "jsdom").exists(): + return True + return False + + +WHY_NO_JSDOM = "jsdom نصب نیست (برای آزمون‌های مرورگری لازم است؛ در بستهٔ تحویلی نصب می‌شود)" + + +OFFLINE_CHECK = Path("/home/user/offline-check.mjs") # آزمون آفلاین (jsdom از روی فایل) + + +def free_port() -> int: + s = socket.socket() + s.bind(("127.0.0.1", 0)) + p = s.getsockname()[1] + s.close() + return p + + +def code(url: str, *, cookie: str | None = None, data: bytes | None = None) -> int: + req = urllib.request.Request(url, data=data, + headers={"Content-Type": "application/json"} if data else {}) + if cookie: + req.add_header("Cookie", cookie) + try: + with urllib.request.urlopen(req, timeout=15) as r: + return r.status + except urllib.error.HTTPError as e: + return e.code + + +@unittest.skipUnless(DEMO_READY, WHY_SKIP) +@unittest.skipUnless(TOOLING_OK, WHY_NO_TOOLING) +class TestBackpackBuild(unittest.TestCase): + @classmethod + def setUpClass(cls): + B = BP + cls.tmp = tempfile.TemporaryDirectory() + cls.out = Path(cls.tmp.name) / "backpack" + cls.manifest = build_or_skip(cls.out, with_python=False) + + @classmethod + def tearDownClass(cls): + cls.tmp.cleanup() + + def test_structure(self): + for rel in ("شروع-از-اینجا.html", "README-FA.md", "LIVE-DEMO-FA.md", "LINK-FA.txt", + "MAKE-PASSWORDS.py", "demo/index.html", "demo/app/app.js", + "station/web_server.py", "station/gate.py", "desk/desk.py", + "kodal-alert/kodal_alert.py", "docs/18-client-value-fa.md", + "RUN-LIVE-WINDOWS.bat", "RUN-LIVE-LINUX.sh", "RUN-DEMO-LAN-WINDOWS.bat", + "RUN-DEMO-LAN-LINUX.sh", "CHECK-WINDOWS.bat", "CHECK-LINUX.sh"): + self.assertTrue((self.out / rel).exists(), rel) + + def test_scripts_are_valid_and_mention_the_essentials(self): + for name in ("RUN-LIVE-LINUX.sh", "RUN-DEMO-LAN-LINUX.sh", "CHECK-LINUX.sh"): + r = subprocess.run(["bash", "-n", str(self.out / name)], capture_output=True, text=True) + self.assertEqual(0, r.returncode, f"{name}: {r.stderr}") + win = (self.out / "RUN-LIVE-WINDOWS.bat").read_text(encoding="utf-8") + for needle in ("chcp 65001", "python\\python.exe", "station\\web_server.py", + "0.0.0.0", "MAKE-PASSWORDS.py", "ipconfig"): + self.assertIn(needle, win) + lan = (self.out / "RUN-DEMO-LAN-WINDOWS.bat").read_text(encoding="utf-8") + self.assertIn("http.server 8080", lan) + self.assertIn("--directory demo", lan) + + def test_start_page_links_all_exist(self): + t = (self.out / "شروع-از-اینجا.html").read_text(encoding="utf-8") + for needle in ("demo/index.html", "LIVE-DEMO-FA.md", "RUN-LIVE-WINDOWS.bat", + "RUN-LIVE-LINUX.sh", "RUN-DEMO-LAN-WINDOWS.bat", + "RUN-DEMO-LAN-LINUX.sh", "CHECK-WINDOWS.bat", "CHECK-LINUX.sh"): + self.assertIn(needle, t) + # هر پیوند نسبی باید پرونده‌اش موجود باشد + for href in re.findall(r'href="([^"#]+)"', t): + if href.startswith(("http", "tel:", "mailto:")): + continue + self.assertTrue((self.out / href).exists(), f"پیوند شکسته: {href}") + + def test_no_secrets_and_no_outputs(self): + for f in self.out.rglob("*"): + if f.is_file(): + self.assertEqual([], find_secret_literals(f), f"{f} مشکوک است") + self.assertFalse((self.out / "station" / "config" / "gate.json").exists()) + self.assertFalse((self.out / "station" / "config" / "admin.json").exists()) + self.assertEqual([], list((self.out / "station" / "export").glob("*"))) + self.assertEqual([], [p for p in self.out.rglob("__pycache__")]) + + def test_manifest(self): + m = json.loads((self.out / "BACKPACK-MANIFEST.json").read_text(encoding="utf-8")) + self.assertTrue(m["offline_demo"]) + self.assertFalse(m["has_python"]) + self.assertIn("demo/index.html", m["key_files"]) + self.assertGreater(m["files"], 100) + + +@unittest.skipUnless(DEMO_READY, WHY_SKIP) +@unittest.skipUnless(TOOLING_OK, WHY_NO_TOOLING) +class TestOfflineDemo(unittest.TestCase): + """نمونهٔ ثابت باید **بدون شبکه** کار کند؛ همین را با jsdom از روی فایل می‌سنجیم.""" + + @classmethod + def setUpClass(cls): + B = BP + cls.tmp = tempfile.TemporaryDirectory() + cls.out = Path(cls.tmp.name) / "backpack" + build_or_skip(cls.out, with_python=False) + + @classmethod + def tearDownClass(cls): + cls.tmp.cleanup() + + @unittest.skipUnless(OFFLINE_CHECK.exists(), "آزمون‌گر آفلاین نیست") + @unittest.skipUnless(jsdom_available(), WHY_NO_JSDOM) + def test_demo_index_opens_from_file_without_network(self): + # نکته: صفحهٔ برنامه «demo/app/index.html» است؛ «demo/index.html» فقط صفحهٔ راهنماست + r = subprocess.run(["node", str(OFFLINE_CHECK), str(self.out / "demo" / "app" / "index.html")], + capture_output=True, text=True, timeout=600) + self.assertEqual(0, r.returncode, r.stdout + r.stderr) + self.assertIn("بازشده: 11", r.stdout) + + def test_demo_launcher_points_to_app(self): + t = (self.out / "demo" / "index.html").read_text(encoding="utf-8") + self.assertIn("app/index.html", t) + + def test_demo_pages_have_no_external_assets(self): + for f in (self.out / "demo").rglob("*.html"): + text = f.read_text(encoding="utf-8", errors="ignore") + for bad in ("http://cdn", "https://cdn", "https://fonts.", "src=\"http"): + self.assertNotIn(bad, text, f"{f} منبع بیرونی دارد") + + +@unittest.skipUnless(DEMO_READY, WHY_SKIP) +@unittest.skipUnless(TOOLING_OK, WHY_NO_TOOLING) +class TestBackpackLive(unittest.TestCase): + """اولین اجرا: رمز ساخته می‌شود، دروازه روشن است، مهمان وارد می‌شود و پنل برایش بسته است.""" + + @classmethod + def setUpClass(cls): + B = BP + cls.tmp = tempfile.TemporaryDirectory() + cls.out = Path(cls.tmp.name) / "backpack" + build_or_skip(cls.out, with_python=False) + cls.port = free_port() + env = {**os.environ, "STATION_PORT": str(cls.port), "PYTHONDONTWRITEBYTECODE": "1"} + cls.proc = subprocess.Popen(["bash", "RUN-LIVE-LINUX.sh"], cwd=str(cls.out), env=env, + stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True) + base = f"http://127.0.0.1:{cls.port}" + for _ in range(40): + try: + if code(f"{base}/login") == 200: + break + except Exception: + pass + time.sleep(0.5) + + @classmethod + def tearDownClass(cls): + cls.proc.terminate() + try: + cls.proc.wait(timeout=10) + except subprocess.TimeoutExpired: + cls.proc.kill() + cls.tmp.cleanup() + + def test_first_run_made_credentials_and_gate_is_on(self): + cred = self.out / "station" / "config" / "CREDENTIALS-FIRST-LOGIN.txt" + self.assertTrue(cred.exists(), "پروندهٔ رمزهای اولین اجرا ساخته نشد") + self.assertEqual(0o600, cred.stat().st_mode & 0o777) + text = cred.read_text(encoding="utf-8") + guest_pass = re.search(r"رمز کارفرما\s*:\s*(\S+)", text).group(1) + operator_pass = re.search(r"رمز مدیر\s*:\s*(\S+)", text).group(1) + self.assertNotEqual(guest_pass, operator_pass) + self.assertGreaterEqual(len(guest_pass), 12) + + base = f"http://127.0.0.1:{self.port}" + self.assertEqual(401, code(f"{base}/files/offer")) # بدون ورود + body = json.dumps({"id": "masoud", "pass": guest_pass}).encode() + req = urllib.request.Request(f"{base}/api/login", data=body, + headers={"Content-Type": "application/json"}) + with urllib.request.urlopen(req, timeout=15) as r: + self.assertEqual(200, r.status) + cookie = r.headers.get("Set-Cookie", "").split(";")[0] + self.assertEqual(200, code(f"{base}/", cookie=cookie)) + self.assertEqual(403, code(f"{base}/admin", cookie=cookie)) # پنل برای کارفرما بسته است + + +@unittest.skipUnless(TOOLING_OK, WHY_NO_TOOLING) +class TestBackpackSkills(unittest.TestCase): + def test_make_passwords_is_idempotent(self): + t = (BASE / "MAKE-PASSWORDS.py").read_text(encoding="utf-8") + self.assertIn("--force", t) + self.assertIn("gate.set_account", t) + self.assertIn("gate.sync_admin_from_panel", t) + self.assertIn("chmod(0o600)", t) + self.assertIn("CREDENTIALS-FIRST-LOGIN.txt", t) + + def test_builder_requires_the_demo_first(self): + t = (BASE / "make_backpack.py").read_text(encoding="utf-8") + self.assertIn("نمونهٔ ثابت ساخته نشده", t) + self.assertIn("--with-python", t) + self.assertIn("BACKPACK-MANIFEST.json", t) + + def test_demo_ready_helper_matches_reality(self): + demo = BP.DEMO_SRC / "app" / "index.html" + self.assertEqual(BP.demo_ready(), demo.exists()) + + def test_offline_checker_exists_for_future_runs(self): + self.assertTrue(OFFLINE_CHECK.exists()) + t = OFFLINE_CHECK.read_text(encoding="utf-8") + self.assertIn("JSDOM.fromFile", t) + self.assertIn("/api/state", t) + + +if __name__ == "__main__": + unittest.main(verbosity=2) diff --git a/station/tests/test_bankroll.py b/station/tests/test_bankroll.py new file mode 100644 index 0000000000000000000000000000000000000000..2cb4303bf03e0b1fa5fa9b0e090064633f4d42c6 --- /dev/null +++ b/station/tests/test_bankroll.py @@ -0,0 +1,114 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""آزمون‌های math-pool (bankroll) — ریاضیِ بقا و رشد باید بازتولیدپذیر و صادق باشد. + +قفل‌های اصلی: + ۱) کسر کِلی با کسرِ دستی می‌خواند: f = (p·b − q) ÷ b. + ۲) نرخ برد سر‌به‌سر با کسر دستی می‌خواند. + ۳) شبیه‌سازی با دانهٔ ثابت، نتیجهٔ یکسان می‌دهد (بازتولیدپذیری). + ۴) کارمزد بیشتر ⇒ میانهٔ پایان کمتر (یکنوا)، و ریسک درشت ⇒ ورشکستگی بیشتر. + ۵) مسیر رشد با لگاریتم می‌خواند، و بازده خالص منفی ⇒ «هیچ‌وقت». +""" +from __future__ import annotations + +import math +import sys +import unittest +from pathlib import Path + +GUI = Path(__file__).resolve().parents[1] +if str(GUI) not in sys.path: + sys.path.insert(0, str(GUI)) + +import bankroll as bk # noqa: E402 + + +class TestKelly(unittest.TestCase): + def test_kelly_hand_math(self): + k = bk.kelly(0.55, 8.0, 5.0) # b = 1.6 · f = (0.88−0.45)÷1.6 + self.assertTrue(k["ok"]) + self.assertAlmostEqual(k["kelly_fraction"], 0.2688, places=4) + self.assertAlmostEqual(k["half_kelly_fraction"], 0.1344, places=4) + self.assertAlmostEqual(k["edge_pct_per_trade"], 2.15, places=2) + + def test_negative_edge_is_refused(self): + k = bk.kelly(0.30, 8.0, 5.0) + self.assertFalse(k["positive_edge"]) + self.assertEqual(k["kelly_fraction"], 0.0) + self.assertIn("پول‌سوزی", k["detail"]) + + def test_breakeven_hand_math(self): + be = bk.breakeven_win_rate(win_pct=8.0, loss_pct=5.0, fee_pct=1.428) + self.assertAlmostEqual(be["breakeven_win_prob"], (5 + 1.428) / 13.0, places=4) + self.assertAlmostEqual(be["breakeven_win_pct"], 49.45, places=2) + + +class TestSimulation(unittest.TestCase): + def test_same_seed_same_result(self): + a = bk.simulate(trials=500, seed=3) + b = bk.simulate(trials=500, seed=3) + self.assertEqual(a["median_final"], b["median_final"]) + self.assertEqual(a["ruin_prob"], b["ruin_prob"]) + + def test_fee_drag_reduces_median(self): + cheap = bk.simulate(trials=800, fee_pct=0.0) + dear = bk.simulate(trials=800, fee_pct=4.0) + self.assertLess(dear["median_final"], cheap["median_final"]) + + def test_bigger_size_means_more_ruin(self): + small = bk.simulate(risk_fraction=0.05, trials=800, win_prob=0.45) + big = bk.simulate(risk_fraction=0.40, trials=800, win_prob=0.45) + self.assertGreaterEqual(big["ruin_prob"], small["ruin_prob"]) + self.assertGreaterEqual(big["ruin_prob"], 0.0) + + def test_probabilities_are_in_range(self): + s = bk.simulate(trials=300) + for key in ("ruin_prob", "double_prob", "profit_prob"): + self.assertGreaterEqual(s[key], 0.0) + self.assertLessEqual(s[key], 1.0) + self.assertLessEqual(s["p10_final"], s["median_final"]) + self.assertLessEqual(s["median_final"], s["p90_final"]) + + +class TestPath(unittest.TestCase): + def test_months_hand_math(self): + p = bk.path(capital=100_000_000.0, monthly_return_pct=10.0, target=400_000_000.0) + expected = math.log(4) / math.log(1.10) + self.assertAlmostEqual(p["months"], expected, places=1) + + def test_zero_growth_never_reaches(self): + p = bk.path(capital=100_000_000.0, monthly_return_pct=1.0, target=400_000_000.0, + fee_drag_pct_month=1.0) + self.assertIsNone(p["months"]) + self.assertIn("هیچ زمانی", p["detail"]) + + def test_strategy_path_subtracts_churn_fees(self): + sp = bk.strategy_path(capital=100_000_000.0, annualized_pct=68.482, + target=400_000_000.0, churn_per_year=1.0) + self.assertAlmostEqual(sp["net_annual_pct"], 68.482 - 1.428, places=2) + self.assertGreater(sp["months"], 24) + self.assertLess(sp["months"], 42) + + def test_strategy_path_negative_when_churn_eats_edge(self): + sp = bk.strategy_path(capital=100_000_000.0, annualized_pct=1.0, + target=400_000_000.0, churn_per_year=1.0) + self.assertIsNone(sp["months"]) + self.assertIn("منفی", sp["detail"]) + + +class TestBuild(unittest.TestCase): + def test_build_without_writing(self): + doc = bk.build(write=False) + self.assertEqual(len(doc["checks"]), 3) + self.assertIn("وعدهٔ سود نیست", doc["honesty"]) + self.assertIn("## ۳.", doc["md_text"]) + self.assertIn("نیم‌شدن حساب", doc["md_text"]) + + def test_used_fraction_is_conservative(self): + doc = bk.build(write=False) + k = doc["kelly"] + self.assertLessEqual(doc["used_risk_fraction"], k["kelly_fraction"] + 1e-9) + + +if __name__ == "__main__": + unittest.main(verbosity=2) diff --git a/station/tests/test_connections.py b/station/tests/test_connections.py new file mode 100644 index 0000000000000000000000000000000000000000..e4b898d3e7c77b06c8ef4430048db79a1b2bc00d --- /dev/null +++ b/station/tests/test_connections.py @@ -0,0 +1,202 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""آزمون دفتر اتصال‌ها و کاوشگر پاسخ سرویس.""" +from __future__ import annotations + +import json +import os +import sys +import tempfile +import unittest +from pathlib import Path + +BASE = Path(__file__).resolve().parent.parent +sys.path.insert(0, str(BASE)) + +import connections as conn # noqa: E402 +import datafeed # noqa: E402 + + +class ConnectionStoreTests(unittest.TestCase): + def setUp(self): + self.tmp = tempfile.TemporaryDirectory() + self.dir = Path(self.tmp.name) + self._old_cfg, self._old_keys = conn.CONFIG_DIR, conn.KEYS_FILE + self._old_profiles = conn.PROFILES_FILE + conn.CONFIG_DIR = self.dir + conn.PROFILES_FILE = self.dir / "connections.json" + conn.KEYS_FILE = self.dir / "keys.local.json" + + def tearDown(self): + conn.CONFIG_DIR, conn.KEYS_FILE = self._old_cfg, self._old_keys + conn.PROFILES_FILE = self._old_profiles + self.tmp.cleanup() + + def test_tgju_preset_is_verified_and_uses_symbol_template(self): + """پروفایل رایگان tgju باید آزمون‌شده باشد و مسیر تأییدشده را داشته باشد.""" + store = conn.default_store() + prof = conn.find_profile(store, "tgju-usd") + self.assertIsNotNone(prof) + self.assertTrue(prof["tested"]) + self.assertIn("{symbol}", prof["url_template"]) + self.assertEqual(prof["json_path"], "data.0.3") + self.assertEqual(prof["cost"], conn.FREE) + self.assertEqual(prof["env_key"], "") + + def test_default_store_has_presets_and_mock_selected(self): + store = conn.load_store() + names = {p["name"] for p in store["profiles"]} + self.assertIn("mock-local", names) + self.assertIn("custom", names) + self.assertEqual(store["selected"], "mock-local") + + def test_default_store_has_free_profiles(self): + store = conn.load_store() + free = [p for p in store["profiles"] if p["cost"] == conn.FREE] + self.assertGreaterEqual(len(free), 4) # رایگان‌ها همیشه باید موجود باشند + + def test_upsert_save_and_reload(self): + store = conn.load_store() + conn.upsert_profile(store, {"name": "my-broker", "label": "سرویس من", + "url_template": "https://x.ir/q?symbol={symbol}", "json_path": "a.b"}) + conn.select_profile(store, "my-broker") + conn.save_store(store) + again = conn.load_store() + prof = conn.find_profile(again, "my-broker") + self.assertIsNotNone(prof) + self.assertEqual(prof["json_path"], "a.b") + self.assertEqual(again["selected"], "my-broker") + + def test_store_file_never_contains_keys(self): + store = conn.load_store() + conn.upsert_profile(store, {"name": "k1", "url_template": "https://x/{key}"}) + conn.save_store(store) + conn.save_key("k1", "SECRET-123") + text = conn.PROFILES_FILE.read_text(encoding="utf-8") + self.assertNotIn("SECRET-123", text) + self.assertEqual(conn.stored_key("k1"), "SECRET-123") + + def test_delete_profile_removes_it(self): + store = conn.load_store() + conn.upsert_profile(store, {"name": "temp-prof"}) + conn.save_store(store) + store = conn.load_store() + self.assertTrue(conn.delete_profile(store, "temp-prof")) + conn.save_store(store) + self.assertIsNone(conn.find_profile(conn.load_store(), "temp-prof")) + + def test_new_presets_are_added_to_old_file(self): + old = {"version": 1, "selected": "custom", "profiles": [dict(conn.PRESET_PROFILES[0])]} + conn.PROFILES_FILE.write_text(json.dumps(old, ensure_ascii=False), encoding="utf-8") + store = conn.load_store() + self.assertGreater(len(store["profiles"]), 1) + + def test_presets_are_upgraded_but_user_profiles_untouched(self): + # نسخهٔ قدیمی: پروفایل آمادهٔ «modified» با نشانی عوض‌شده توسط کاربر + پروفایل خودساخته + old = {"version": 1, "selected": "my-own", "profiles": [ + {"name": "exchange-irt", "label": "صرافی (نسخهٔ قدیمی)", "url_template": "https://old/x", + "custom": True}, + {"name": "my-own", "label": "سرویس خودم", "url_template": "https://mine/x", "custom": True}, + {"name": "tgju-usd", "label": "tgju (نسخهٔ قدیمی)", "url_template": "https://old/tgju"}]} + conn.PROFILES_FILE.write_text(json.dumps(old, ensure_ascii=False), encoding="utf-8") + store = conn.load_store() + self.assertEqual(conn.find_profile(store, "exchange-irt")["url_template"], "https://old/x") + self.assertEqual(conn.find_profile(store, "my-own")["url_template"], "https://mine/x") + refreshed = conn.find_profile(store, "tgju-usd") + self.assertNotEqual(refreshed["url_template"], "https://old/tgju") + + def test_preset_version_is_stored(self): + store = conn.load_store() + conn.save_store(store) + again = json.loads(conn.PROFILES_FILE.read_text(encoding="utf-8")) + self.assertEqual(again["preset_version"], conn.PRESET_VERSION) + + def test_corrupt_file_falls_back_to_defaults(self): + conn.PROFILES_FILE.write_text("{ this is not json", encoding="utf-8") + store = conn.load_store() + self.assertEqual(store["selected"], "mock-local") + + +class KeyResolutionTests(unittest.TestCase): + def setUp(self): + self.tmp = tempfile.TemporaryDirectory() + self.dir = Path(self.tmp.name) + self._old_cfg, self._old_keys = conn.CONFIG_DIR, conn.KEYS_FILE + conn.CONFIG_DIR = self.dir + conn.KEYS_FILE = self.dir / "keys.local.json" + self.prof = {"name": "p1", "env_key": "TEST_MARKET_KEY"} + + def tearDown(self): + conn.CONFIG_DIR, conn.KEYS_FILE = self._old_cfg, self._old_keys + os.environ.pop("TEST_MARKET_KEY", None) + self.tmp.cleanup() + + def test_inline_key_wins(self): + conn.save_key("p1", "SAVED") + os.environ["TEST_MARKET_KEY"] = "FROM_ENV" + key, where = conn.resolve_key(self.prof, inline_key="TYPED") + self.assertEqual(key, "TYPED") + self.assertIn("کادر", where) + + def test_saved_key_beats_env(self): + conn.save_key("p1", "SAVED") + os.environ["TEST_MARKET_KEY"] = "FROM_ENV" + key, where = conn.resolve_key(self.prof) + self.assertEqual(key, "SAVED") + self.assertIn("ذخیره", where) + + def test_env_used_when_nothing_saved(self): + os.environ["TEST_MARKET_KEY"] = "FROM_ENV" + key, where = conn.resolve_key(self.prof) + self.assertEqual(key, "FROM_ENV") + self.assertIn("محیطی", where) + + def test_no_key_at_all(self): + key, where = conn.resolve_key(self.prof) + self.assertEqual(key, "") + self.assertEqual(where, "بدون کلید") + + def test_clearing_saved_key(self): + conn.save_key("p1", "SAVED") + conn.save_key("p1", "") + self.assertEqual(conn.stored_key("p1"), "") + + +class ProfileApplicationTests(unittest.TestCase): + def test_mock_profile_maps_to_live_config(self): + store = conn.load_store() + active = conn.apply_profile(store, "mock-local") + self.assertTrue(active["is_mock"]) + self.assertIn("{symbol}", active["live_cfg"]["url_template"]) + self.assertEqual(active["live_cfg"]["json_path"], "data.0.pl") + + def test_unknown_profile_raises(self): + with self.assertRaises(KeyError): + conn.apply_profile(conn.load_store(), "does-not-exist") + + def test_active_or_none_returns_dict_or_none(self): + active = conn.active_or_none() + self.assertTrue(active is None or "profile" in active) + + def test_summary_rows_mark_selected(self): + rows = conn.summary_rows() + self.assertTrue(any(r[0] == "★" for r in rows)) + + +class PeekHelperTests(unittest.TestCase): + def test_numeric_paths_finds_nested_numbers(self): + payload = {"data": [{"pl": "20,150", "name": "اهرم"}], "meta": {"count": 3}, "ok": True} + paths = dict(datafeed.numeric_paths(payload)) + self.assertEqual(paths["data.0.pl"], 20150.0) + self.assertEqual(paths["meta.count"], 3.0) + + def test_numeric_paths_respects_limit(self): + payload = {f"k{i}": i for i in range(100)} + self.assertLessEqual(len(datafeed.numeric_paths(payload, max_items=10)), 10) + + def test_numeric_paths_ignores_text(self): + self.assertEqual(datafeed.numeric_paths({"name": "اهرم", "null": None, "b": False}), []) + + +if __name__ == "__main__": + unittest.main() diff --git a/station/tests/test_daily_inputs_template.py b/station/tests/test_daily_inputs_template.py new file mode 100644 index 0000000000000000000000000000000000000000..1daa4cbd456baf210f067c39d7d7ee2e7a427527 --- /dev/null +++ b/station/tests/test_daily_inputs_template.py @@ -0,0 +1,109 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""آزمون «ورودی روزانه»: قالب اسنپ‌شات و راهنمای آن. + +هدف دو چیز است: + ۱. قالب هیچ‌وقت ناقص نماند (هر پنج نوع معامله با فیلدهای درست). + ۲. همان قالب هرگز به‌اشتباه یک «روز واقعی» در کارنامه ثبت نکند. +""" +from __future__ import annotations + +import json +import sys +import tempfile +import unittest +from pathlib import Path + +HERE = Path(__file__).resolve().parent +GUI = HERE.parent +sys.path.insert(0, str(GUI)) + +import datafeed as df # noqa: E402 +import daily_trial as dt # noqa: E402 + +def _doc(name: str) -> Path: + for cand in (GUI.parent / name, GUI.parent / "docs" / name, GUI / "docs" / name): + if cand.exists(): + return cand + return GUI.parent / name + + +DOC = _doc("10-daily-inputs-fa.md") +NEEDED = { + "basis": ("spot", "future", "days"), + "covered_call": ("spot", "strike", "premium", "days"), + "tabei": ("stock_price", "put_price", "strike", "days"), + "box": ("call_low", "put_low", "call_high", "put_high", "strike_low", "strike_high", "days"), + "parity": ("call", "put", "spot", "strike", "days"), +} + + +class TestTemplate(unittest.TestCase): + def setUp(self): + self.raw = json.loads(json.dumps(df.SNAPSHOT_TEMPLATE, ensure_ascii=False)) + + def test_template_names_all_five_kinds(self): + kinds = {r["kind"] for r in self.raw["rows"]} + self.assertEqual(set(NEEDED), kinds) + + def test_every_kind_has_its_numbers(self): + for row in self.raw["rows"]: + for field in NEEDED[row["kind"]]: + self.assertIn(field, row, f"{row['symbol']}: «{field}» نیست") + self.assertGreater(float(row[field]), 0, f"{row['symbol']}: «{field}» باید مثبت باشد") + + def test_common_fields_present(self): + for row in self.raw["rows"]: + for field in ("symbol", "margin_per_contract", "liquidity_contracts_per_day", "spread_pct"): + self.assertIn(field, row, f"{row['symbol']}: «{field}» نیست") + + def test_rules_and_help_blocks_present(self): + self.assertIn("hurdle", self.raw) + self.assertIn("capital", self.raw) + self.assertIn("قالب", self.raw["note"]) + for kind in NEEDED: + self.assertIn(kind, self.raw["_fields_per_kind"]) + + def test_written_template_loads_as_snapshot(self): + """قالبِ نوشته‌شده روی دیسک باید بدون خطا خوانده شود (پنج ردیف).""" + with tempfile.TemporaryDirectory() as tmp: + p = df.write_snapshot_template(Path(tmp) / "snapshot-template.json") + snap = df.build_snapshot("file", file_path=p) + self.assertEqual("ok", snap.status, snap.messages) + self.assertEqual(5, len(snap.rows)) + self.assertIn("دستی", snap.source_label) + + +class TestHonesty(unittest.TestCase): + def test_template_name_is_synthetic(self): + """نام قالب هرگز روز «واقعی» حساب نمی‌شود.""" + self.assertTrue(dt.path_is_synthetic("data/snapshot-template.json")) + + def test_renamed_copy_is_real(self): + """اگر کاربر عددهای واقعی خودش را با نام خودش ذخیره کند، روز واقعی است.""" + self.assertFalse(dt.path_is_synthetic("data/daily-input.json")) + + def test_note_field_says_it_is_a_template(self): + self.assertIn("واقعی", df.SNAPSHOT_TEMPLATE["note"]) + + +class TestDoc(unittest.TestCase): + def test_doc_exists_and_names_the_free_sources(self): + text = DOC.read_text(encoding="utf-8") + for needle in ("tsetmc", "کدال", "کارگزاری", "مجانی", "snapshot-template.json"): + self.assertIn(needle, text) + + def test_doc_lists_field_names_of_every_kind(self): + text = DOC.read_text(encoding="utf-8") + for field in ("spot", "future", "strike", "premium", "put_price", + "call_low", "put_high", "margin_per_contract", "liquidity_contracts_per_day"): + self.assertIn(field, text) + + def test_doc_says_what_not_to_enter(self): + text = DOC.read_text(encoding="utf-8") + for needle in ("رمز", "سفارش"): + self.assertIn(needle, text) + + +if __name__ == "__main__": + unittest.main(verbosity=2) diff --git a/station/tests/test_daily_trial.py b/station/tests/test_daily_trial.py new file mode 100644 index 0000000000000000000000000000000000000000..0553404bedbc88bc4f8faf97a9aeba15ac9d8551 --- /dev/null +++ b/station/tests/test_daily_trial.py @@ -0,0 +1,255 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""آزمون مراسم روزانه و کارنامهٔ آزمون دو هفته‌ای.""" +from __future__ import annotations + +import json +import sys +import tempfile +import unittest +from pathlib import Path + +BASE = Path(__file__).resolve().parent.parent +sys.path.insert(0, str(BASE)) +sys.path.insert(0, str(BASE.parent / "desk")) + +import daily_trial as dt # noqa: E402 +import live_trial as lt # noqa: E402 + + +class LabelTests(unittest.TestCase): + def test_synthetic_labels_are_detected(self): + for label in ("خوراک آزمایشی محلی (ساختگی)", "دادهٔ نمونهٔ همراه برنامه", + "دادهٔ نمونهٔ همراه برنامه (بدون هزینه)"): + self.assertTrue(dt.is_synthetic(label), label) + + def test_demo_and_template_files_are_synthetic(self): + for path in ("desk/market-demo.json", "data/snapshot-template.json", + "/tmp/نمونهٔ-تاریخ.csv", "demo/history.csv"): + self.assertTrue(dt.path_is_synthetic(path), path) + + def test_user_files_are_not_synthetic(self): + for path in ("/home/me/broker-1405-06-31.json", "C:/market/daily.json", None, ""): + self.assertFalse(dt.path_is_synthetic(path), str(path)) + + def test_real_labels_are_not_synthetic(self): + for label in ("دادهٔ زندهٔ وب‌سرویس", "پروندهٔ دستی کاربر", ""): + self.assertFalse(dt.is_synthetic(label), label) + + +class ScorecardTests(unittest.TestCase): + def setUp(self): + self.tmp = tempfile.TemporaryDirectory() + self.dir = Path(self.tmp.name) + self.db = self.dir / "trial.sqlite3" + + def tearDown(self): + self.tmp.cleanup() + + def _logs(self, days, synthetic=False): + return [{"date": d, "synthetic": synthetic, "chain_ok": True, "ts": f"{d}T10:00:00+00:00"} + for d in days] + + def test_empty_journal_is_not_ready(self): + score = dt.scorecard(lt.Trial(self.db), log_records=[]) + self.assertFalse(score["ready"]) + self.assertEqual(score["days"], 0) + self.assertIn("هنوز نه", score["verdict"]) + + def test_five_criteria_always_present(self): + score = dt.scorecard(lt.Trial(self.db), log_records=[]) + self.assertEqual(len(score["criteria"]), 5) + keys = {c["key"] for c in score["criteria"]} + self.assertEqual(keys, {"days", "real_days", "marked", "moves", "chain"}) + + def test_synthetic_days_do_not_count_as_real(self): + score = dt.scorecard(lt.Trial(self.db), log_records=self._logs( + [f"2026-09-{d:02d}" for d in range(1, 13)], synthetic=True)) + self.assertEqual(score["days"], 12) + self.assertEqual(score["real_days"], 0) + real = [c for c in score["criteria"] if c["key"] == "real_days"][0] + self.assertFalse(real["ok"]) + + def test_becoming_ready_when_everything_is_there(self): + t = lt.Trial(self.db) + # یازده روز واقعی، دفتر پر و بازسنجی‌شده + logs = self._logs([f"2026-09-{d:02d}" for d in range(1, 12)]) + for i in range(6): + t.record([{"symbol": f"نماد{i}", "kind": "basis", "expected": 20.0}], dedupe_hours=0) + t.mark({f"نماد{i}": {"expected_now": 20.0 + (3 - i), "floor": 3.0} for i in range(6)}) + score = dt.scorecard(t, log_records=logs) + self.assertGreaterEqual(score["days"], 10) + self.assertEqual(score["real_days"], 11) + self.assertGreaterEqual(score["up"], 1) + self.assertGreaterEqual(score["down"], 1) + self.assertTrue(score["ready"], score["verdict"]) + self.assertIn("آماده", score["verdict"]) + + def test_verdict_names_what_is_missing(self): + t = lt.Trial(self.db) + t.record([{"symbol": "اهرم", "kind": "basis", "expected": 20.0}]) + score = dt.scorecard(t, log_records=self._logs(["2026-09-01"])) + self.assertFalse(score["ready"]) + self.assertIn("تداوم", score["verdict"]) + + def test_chain_break_blocks_readiness(self): + t = lt.Trial(self.db) + t.record([{"symbol": "اهرم", "kind": "basis", "expected": 20.0}]) + import sqlite3 + c = sqlite3.connect(self.db) + c.execute("UPDATE entries SET expected = 1.0") + c.commit() + c.close() + score = dt.scorecard(t, log_records=self._logs([f"2026-09-{d:02d}" for d in range(1, 12)])) + self.assertFalse(score["ready"]) + chain = [x for x in score["criteria"] if x["key"] == "chain"][0] + self.assertFalse(chain["ok"]) + + def test_status_text_lists_every_criterion(self): + text = dt.status_text(dt.scorecard(lt.Trial(self.db), log_records=[])) + for name in ("تداوم", "روزهای با دادهٔ واقعی", "بازسنجی", "حرکت واقعی", "زنجیرهٔ هش"): + self.assertIn(name, text) + + +class LogTests(unittest.TestCase): + def setUp(self): + self.tmp = tempfile.TemporaryDirectory() + self.path = Path(self.tmp.name) / "trial-daily.log" + + def tearDown(self): + self.tmp.cleanup() + + def test_append_and_read(self): + dt.append_log({"date": "2026-09-22", "recorded": 3}, self.path) + dt.append_log({"date": "2026-09-23", "recorded": 1}, self.path) + rows = dt.read_log(self.path) + self.assertEqual(len(rows), 2) + self.assertEqual(rows[1]["recorded"], 1) + + def test_broken_line_is_skipped(self): + self.path.write_text('{"date":"x"}\nnot json\n{"date":"y"}\n', encoding="utf-8") + self.assertEqual(len(dt.read_log(self.path)), 2) + + def test_missing_file_reads_empty(self): + self.assertEqual(dt.read_log(Path(self.tmp.name) / "nope.log"), []) + + +class SourcePickTests(unittest.TestCase): + def setUp(self): + self.tmp = tempfile.TemporaryDirectory() + self.dir = Path(self.tmp.name) + self.snap_path = self.dir / "snap.json" + self.snap_path.write_text(json.dumps({ + "as_of": "2026-09-22", "hurdle": 0.39, "capital": 20_000_000_000, + "rows": [{"symbol": "اهرم", "kind": "basis", "spot": 20000, "future": 22800, + "days": 90, "margin_per_contract": 20_000_000, "unit": "قرارداد", + "liquidity_contracts_per_day": 900, "spread_pct": 0.005}]}, + ensure_ascii=False), encoding="utf-8") + + def tearDown(self): + self.tmp.cleanup() + + def test_auto_without_url_uses_file(self): + snap, used, notes = dt.pick_source(mode="auto", file_path=self.snap_path, live_cfg={}) + self.assertEqual(used, "file") + self.assertEqual(len(snap.rows), 1) + self.assertTrue(any("پرونده" in n for n in notes)) + + def test_auto_without_anything_falls_back_to_demo(self): + snap, used, notes = dt.pick_source(mode="auto", live_cfg={}) + self.assertEqual(used, "sim") + self.assertTrue(dt.is_synthetic(snap.source_label)) + + def test_live_mode_without_url_falls_back(self): + snap, used, notes = dt.pick_source(mode="live", file_path=self.snap_path, live_cfg={"url_template": ""}) + self.assertEqual(used, "file") + + def test_network_can_be_blocked(self): + snap, used, notes = dt.pick_source( + mode="live", file_path=self.snap_path, allow_network=False, + live_cfg={"url_template": "http://127.0.0.1:9/quote?symbol={symbol}"}) + self.assertEqual(used, "file") + + def test_write_running_snapshot_makes_market_file(self): + snap, _, _ = dt.pick_source(mode="file", file_path=self.snap_path) + out = dt.write_running_snapshot(snap, dt.DEFAULT_RULES, self.dir / "market.json") + data = json.loads(out.read_text(encoding="utf-8")) + self.assertEqual(data["rows"][0]["symbol"], "اهرم") + self.assertIn("hurdle", data) + + +class RunDailyTests(unittest.TestCase): + def setUp(self): + self.tmp = tempfile.TemporaryDirectory() + self.dir = Path(self.tmp.name) + self.db = self.dir / "trial.sqlite3" + self.report = self.dir / "report.html" + self.market = self.dir / "market.json" + self.log = self.dir / "daily.log" + self._old = (dt.LOG_FILE, dt.RUNNING_SNAPSHOT, dt.REPORT_FILE, dt.DATA) + dt.LOG_FILE = self.log + dt.RUNNING_SNAPSHOT = self.market + dt.REPORT_FILE = self.report + # دفتر آزمون در همین پوشهٔ موقت ساخته شود + self._old_desk_db = None + + def tearDown(self): + dt.LOG_FILE, dt.RUNNING_SNAPSHOT, dt.REPORT_FILE, dt.DATA = self._old + self.tmp.cleanup() + + def test_run_daily_with_demo_data_records_and_reports(self): + res = dt.run_daily(mode="sim", rules=dt.DEFAULT_RULES, db=self.db, report=self.report, + log_path=self.log, + use_kodal=False, desk_db=self.dir / "desk.sqlite3") + self.assertTrue(res["ok"], res.get("errors")) + self.assertEqual(res["record"]["mode"], "sim") + self.assertTrue(res["record"]["synthetic"]) + self.assertGreater(res["record"]["signals"], 0) + self.assertTrue(res["report"].endswith("report.html")) + self.assertTrue(Path(res["report"]).exists()) + self.assertTrue(self.log.exists()) + self.assertTrue(res["scorecard"]["criteria"]) + self.assertFalse(res["scorecard"]["ready"]) # یک روز کافی نیست + + def test_run_daily_is_idempotent_for_the_same_signals(self): + first = dt.run_daily(mode="sim", db=self.db, report=self.report, use_kodal=False, log_path=self.log, + desk_db=self.dir / "desk.sqlite3") + second = dt.run_daily(mode="sim", db=self.db, report=self.report, use_kodal=False, log_path=self.log, + desk_db=self.dir / "desk.sqlite3") + self.assertGreater(first["record"]["recorded"], 0) + self.assertEqual(second["record"]["recorded"], 0) # تکراری‌ها ثبت نمی‌شوند + self.assertGreaterEqual(second["summary"]["marked"], 1) + + def test_demo_file_does_not_count_as_real_day(self): + demo = self.dir / "market-demo.json" + demo.write_text(json.dumps({ + "as_of": "2026-09-22", "hurdle": 0.39, "capital": 20_000_000_000, + "rows": [{"symbol": "اهرم", "kind": "basis", "spot": 20000, "future": 22800, "days": 90, + "margin_per_contract": 20_000_000, "unit": "قرارداد", + "liquidity_contracts_per_day": 900, "spread_pct": 0.005}]}, + ensure_ascii=False), encoding="utf-8") + res = dt.run_daily(mode="file", file_path=demo, db=self.db, report=self.report, log_path=self.log, + use_kodal=False, desk_db=self.dir / "desk.sqlite3") + self.assertTrue(res["ok"]) + self.assertEqual(res["record"]["mode"], "file") + self.assertTrue(res["record"]["synthetic"]) # پروندهٔ نمونه، روز واقعی نیست + self.assertEqual(res["scorecard"]["real_days"], 0) + + def test_failed_source_does_not_crash(self): + res = dt.run_daily(mode="file", file_path=self.dir / "missing.json", db=self.db, + report=self.report, use_kodal=False, log_path=self.log, + desk_db=self.dir / "desk.sqlite3") + self.assertTrue(res["ok"]) # به دادهٔ نمونه برمی‌گردد + self.assertEqual(res["record"]["mode"], "sim") + + def test_log_records_one_line_per_run(self): + dt.run_daily(mode="sim", db=self.db, report=self.report, use_kodal=False, + desk_db=self.dir / "desk.sqlite3", log_path=self.log, note="جلسهٔ اول") + rows = dt.read_log(self.log) + self.assertEqual(len(rows), 1) + self.assertEqual(rows[0]["note"], "جلسهٔ اول") + self.assertIn("source", rows[0]) + + +if __name__ == "__main__": + unittest.main() diff --git a/station/tests/test_data_sources.py b/station/tests/test_data_sources.py new file mode 100644 index 0000000000000000000000000000000000000000..2d1a1f1597ffcd9d539432a00983fc71c8a53529 --- /dev/null +++ b/station/tests/test_data_sources.py @@ -0,0 +1,241 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""آزمون «امکان‌سنجی مسیرهای داده»: آیا سنجش، راست می‌گوید یا فقط عدد نشان می‌دهد؟""" +from __future__ import annotations + +import json +import os +import socket +import subprocess +import sys +import tempfile +import threading +import time +import unittest +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer +from pathlib import Path + +GUI = Path(__file__).resolve().parent.parent +if str(GUI) not in sys.path: + sys.path.insert(0, str(GUI)) + +import data_sources as ds # noqa: E402 + + +class FixtureProbeTests(unittest.TestCase): + """سنجش روی سرور نمونهٔ محلی با همان ساختار نشانی‌های واقعی.""" + + @classmethod + def setUpClass(cls): + cls.httpd, cls.host = ds.start_fixture() + + @classmethod + def tearDownClass(cls): + cls.httpd.shutdown() + cls.httpd.server_close() + + def test_all_endpoints_detected_and_code_resolved(self): + res = ds.probe_all(host=self.host, with_stability=False, timeout=5) + self.assertEqual(len(ds.ENDPOINTS), res["summary"]["total"]) + self.assertEqual(res["summary"]["total"], res["summary"]["ok"], [i["reason"] for i in res["items"]]) + self.assertEqual("46348559193224090", res["code"]) # کد نماد از جست‌وجو درآمد + self.assertTrue(res["summary"]["usable_for_engine"]) + + def test_declared_paths_are_the_source_of_truth(self): + ep = next(e for e in ds.ENDPOINTS if e["name"] == "price_info") + item = ds.probe_endpoint(ep, code="46348559193224090", host=self.host, timeout=5) + paths = [f["path"] for f in item["fields"]] + self.assertIn("closingPriceInfo.pDrCotVal", paths) + self.assertEqual(4, item["count"]) + + def test_wrong_paths_make_endpoint_unusable(self): + """اگر ساختار سرویس عوض شود، باید «سرخ» شود، نه اینکه بی‌صدا قبول شود.""" + ep = {"name": "broken", "label": "نشانی با ساختار عوض‌شده", + "url": self.host + "/api/ClosingPrice/GetClosingPriceInfo/{code}", + "needs": "code", "gives": "", "paths": ["nope.0.notHere"]} + item = ds.probe_endpoint(ep, code="1", host=self.host, timeout=5) + self.assertFalse(item["ok"]) + self.assertIn("ساختار", item["reason"]) + + def test_stability_detects_a_moving_price(self): + ep = next(e for e in ds.ENDPOINTS if e["name"] == "price_info") + s = ds.stability_check(ep, code="46348559193224090", host=self.host, wait=0.3, timeout=5) + self.assertTrue(s["checked"]) + self.assertEqual("تازه‌شونده", s["verdict"]) + + def test_stability_skips_non_price_endpoints(self): + ep = next(e for e in ds.ENDPOINTS if e["name"] == "symbol_search") + s = ds.stability_check(ep, symbol="فولاد", host=self.host, wait=0.2, timeout=5) + self.assertFalse(s["checked"]) + self.assertIn("قیمت نیست", s["reason"]) + + def test_missing_code_is_reported_in_persian(self): + ep = next(e for e in ds.ENDPOINTS if e["name"] == "closing_daily") + item = ds.probe_endpoint(ep, code="", host=self.host, timeout=5) + self.assertFalse(item["ok"]) + self.assertIn("insCode", item["reason"]) + + def test_offline_flag_does_not_touch_network(self): + ep = next(e for e in ds.ENDPOINTS if e["name"] == "market_watch") + item = ds.probe_endpoint(ep, host="http://127.0.0.1:9", allow_network=False, timeout=1) + self.assertFalse(item["ok"]) + self.assertIn("شبکه خاموش", item["reason"]) + + def test_report_and_sheet_are_written(self): + res = ds.probe_all(host=self.host, with_stability=False, timeout=5) + with tempfile.TemporaryDirectory() as tmp: + report = ds.build_report(res, ds.build_matrix(), path=Path(tmp) / "f.html") + html = report.read_text(encoding="utf-8") + self.assertIn('dir="rtl"', html) + self.assertIn("Masoud Mojarabian", html) + self.assertIn("وجه تضمین", html) + self.assertNotIn("http://cdn", html) + sheet = ds.requirement_sheet() + self.assertIn("برگهٔ نیاز داده", sheet) + self.assertIn("وجه تضمین", sheet) + for q in ("قالب دسترسی", "احراز هویت", "پایداری", "پرداخت", "اجازهٔ استفاده"): + self.assertIn(q, sheet) # پنج پرسش فنی از فروشنده + + def test_matrix_covers_three_routes_with_verdicts(self): + m = ds.build_matrix() + self.assertEqual(3, len(m)) + for row in m: + for key in ("route", "gives", "misses", "cost", "verdict", "test"): + self.assertTrue(row[key], key) + self.assertIn("نیاز نداریم", m[2]["verdict"]) # پوش لحظه‌ای + + def test_ws_block_appears_only_when_probed(self): + res = ds.probe_all(host=self.host, with_stability=False, timeout=5) + with tempfile.TemporaryDirectory() as tmp: + plain = ds.build_report(res, ds.build_matrix(), path=Path(tmp) / "a.html").read_text(encoding="utf-8") + with_ws = ds.build_report(res, ds.build_matrix(), + ws={"url": "wss://x/y", "tcp": True, "tls": True, "status": 401, + "verdict": "سرویس هست ولی احراز هویت می‌خواهد", "note": "پاسخ 401"}, + path=Path(tmp) / "b.html").read_text(encoding="utf-8") + self.assertNotIn("

    سنجش پوش لحظه‌ای

    ", plain) + self.assertIn("

    سنجش پوش لحظه‌ای

    ", with_ws) + self.assertIn("401", with_ws) + + +class FakeWsServer: + """سرور خام برای آزمون دست‌دادن websocket (پاسخ ثابت، بدون کتابخانه).""" + + def __init__(self, response: bytes | None): + self.response = response + self.sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM) + self.sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) + self.sock.bind(("127.0.0.1", 0)) + self.sock.listen(2) + self.port = self.sock.getsockname()[1] + self.thread = threading.Thread(target=self._serve, daemon=True) + self.thread.start() + + def _serve(self): + try: + conn, _ = self.sock.accept() + except OSError: + return + try: + conn.recv(2048) + if self.response: + conn.sendall(self.response) + else: + time.sleep(1.0) # سرور ساکت: پاسخ نمی‌دهد + except OSError: + pass + finally: + conn.close() + self.sock.close() + + def close(self): + try: + self.sock.close() + except OSError: + pass + + +class WsProbeTests(unittest.TestCase): + def test_upgrade_101_is_reachable(self): + srv = FakeWsServer(b"HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\n" + b"Connection: Upgrade\r\nSec-WebSocket-Accept: x\r\n\r\n") + try: + res = ds.probe_ws(f"ws://127.0.0.1:{srv.port}/market", timeout=3) + self.assertTrue(res["tcp"]) + self.assertEqual(101, res["status"]) + self.assertTrue(res["ok"]) + self.assertIn("ارتقا", res["verdict"]) + finally: + srv.close() + + def test_401_is_reachable_but_needs_auth(self): + srv = FakeWsServer(b"HTTP/1.1 401 Unauthorized\r\nContent-Length: 0\r\n\r\n") + try: + res = ds.probe_ws(f"ws://127.0.0.1:{srv.port}/market", timeout=3) + self.assertEqual(401, res["status"]) + self.assertFalse(res["ok"]) + self.assertIn("احراز هویت", res["verdict"]) + finally: + srv.close() + + def test_silent_server_reports_timeout_honestly(self): + srv = FakeWsServer(None) + try: + res = ds.probe_ws(f"ws://127.0.0.1:{srv.port}/market", timeout=1) + self.assertFalse(res["ok"]) + self.assertTrue(res["verdict"]) + self.assertNotIn("101", str(res.get("status"))) + finally: + srv.close() + + def test_closed_port_is_unreachable(self): + res = ds.probe_ws("ws://127.0.0.1:9/market", timeout=1) + self.assertFalse(res["tcp"]) + self.assertEqual("دسترس نیست", res["verdict"]) + + def test_invalid_url_is_rejected(self): + res = ds.probe_ws("https://example.ir/market") + self.assertEqual("نشانی نامعتبر", res["verdict"]) + + def test_real_read_says_what_is_missing(self): + res = ds.real_ws_read("ws://127.0.0.1:9/x", seconds=1) + self.assertFalse(res["ok"]) + self.assertTrue(res.get("reason")) + + +class DataSourcesCliTests(unittest.TestCase): + def _run(self, *args): + return subprocess.run([sys.executable, str(GUI / "data_sources.py"), *args], + capture_output=True, text=True, timeout=180, cwd=str(GUI)) + + def test_sheet_command_writes_file(self): + with tempfile.TemporaryDirectory() as tmp: + out = Path(tmp) / "sheet.md" + code = ("import sys, pathlib; sys.path.insert(0, r'%s'); import data_sources as ds; " + "pathlib.Path(r'%s').write_text(ds.requirement_sheet(), encoding='utf-8')" + % (GUI, out)) + r = subprocess.run([sys.executable, "-c", code], capture_output=True, text=True, timeout=60) + self.assertEqual(0, r.returncode, r.stderr) + self.assertIn("وجه تضمین", out.read_text(encoding="utf-8")) + + def test_fixture_json_run_is_usable(self): + r = self._run("--fixture", "--json", "--no-stability") + self.assertEqual(0, r.returncode, r.stderr[:400]) + data = json.loads(r.stdout) + self.assertTrue(data["result"]["fixture"]) + self.assertGreaterEqual(data["result"]["summary"]["ok"], 3) + self.assertEqual(3, len(data["matrix"])) + + def test_ws_probe_cli_on_unreachable_host(self): + r = self._run("--ws", "ws://127.0.0.1:9/x", "--symbol", "فولاد", "--timeout", "1", + "--host", "http://127.0.0.1:9") + self.assertIn("پوش لحظه‌ای", r.stdout) + self.assertIn("دسترس نیست", r.stdout) + + def test_version_flag(self): + r = self._run("--version") + self.assertEqual(0, r.returncode) + self.assertEqual(ds.VERSION, r.stdout.strip()) + + +if __name__ == "__main__": + unittest.main() diff --git a/station/tests/test_datafeed_honesty.py b/station/tests/test_datafeed_honesty.py new file mode 100644 index 0000000000000000000000000000000000000000..3bcd92525d95ad2bbc4323b954b52d119c02a723 --- /dev/null +++ b/station/tests/test_datafeed_honesty.py @@ -0,0 +1,174 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""آزمون‌های صداقت لایهٔ داده — «موفقیت دروغین» نباید ساخته شود. + +این پرونده یک اشکال واقعی را قفل می‌کند: اگر شبکه جواب ندهد، خواندنِ خودکار از حافظهٔ +نهان (فایل last.json یا probe-*.json) باعث می‌شد سنجش سرویس‌ها بگوید «۶ از ۶ جواب داد» +در حالی که هیچ پاسخ تازه‌ای نیامده بود. حالا هر خواندن از حافظهٔ نهان یا ممنوع است +(stale_ok=False) یا صریح اعلام می‌شود. + +همهٔ آزمون‌ها محلی‌اند: هیچ درخواست شبکه‌ای زده نمی‌شود (نشانی‌های درگاه بسته/نامعتبر). +""" + +import json +import os +import pathlib +import shutil +import sys +import tempfile +import time +import unittest +from pathlib import Path +from unittest import mock + +BASE = pathlib.Path(__file__).resolve().parents[1] +if str(BASE) not in sys.path: + sys.path.insert(0, str(BASE)) + +import datafeed # noqa: E402 +import data_sources # noqa: E402 + +DEAD_URL = "http://127.0.0.1:9/quote" # درگاه ۹: همیشه بسته، بدون تماس شبکه‌ای واقعی + + +class StaleCacheIsHonest(unittest.TestCase): + """حافظهٔ نهان: ممنوع یا برچسب‌دار، هرگز بی‌سروصدا.""" + + def setUp(self): + self.tmp = tempfile.TemporaryDirectory() + self.cache = pathlib.Path(self.tmp.name) + self.patch = mock.patch.object(datafeed, "CACHE_DIR", self.cache) + self.patch.start() + self.file = self.cache / "probe-x.json" + self.file.write_text(json.dumps({"last": 227860}), encoding="utf-8") + old = time.time() - 3600 + import os + os.utime(self.file, (old, old)) + + def tearDown(self): + self.patch.stop() + self.tmp.cleanup() + + def test_stale_not_used_when_disallowed(self): + text, status = datafeed.fetch(DEAD_URL, timeout=2, retries=0, + cache_name="probe-x.json", cache_seconds=0, + stale_ok=False) + self.assertIsNone(text, "خواندن از حافظهٔ کهنه نباید «پاسخ» حساب شود") + self.assertIn("ناموفق", status) + + def test_stale_is_labeled_when_allowed(self): + text, status = datafeed.fetch(DEAD_URL, timeout=2, retries=0, + cache_name="probe-x.json", cache_seconds=0, + stale_ok=True) + self.assertIsNotNone(text) + self.assertIn("حافظهٔ نهان", status, "باید صریح بگوید از شبکه نیامده") + self.assertIn("نه از شبکه", status) + + def test_probe_endpoint_reports_failure(self): + res = data_sources.probe_endpoint( + {"name": "نمونه", "label": "نمونه", "url": DEAD_URL, "needs": "", + "gives": "هیچ", "paths": ["last"]}, + timeout=2) + self.assertFalse(res["ok"], "نشانی بی‌پاسخ نباید سالم اعلام شود") + self.assertIn("پاسخی نیامد", res["reason"]) + + def test_probe_all_verdict_asks_user_to_run_locally(self): + result = data_sources.probe_all(symbol="فولاد", host="http://127.0.0.1:9", + timeout=2, with_stability=False) + self.assertEqual(result["summary"]["ok"], 0) + self.assertIn("دسترسی نبود", result["verdict"]) + self.assertFalse(result["summary"]["usable_for_engine"]) + + +class LiveSnapshotFreshness(unittest.TestCase): + """قیمتِ حافظهٔ نهان نباید برچسب «زندهٔ ۰ ثانیه پیش» بگیرد.""" + + def _snap(self): + return datafeed.Snapshot( + rows=[{"name": "الف", "kind": "basis", "symbol": "فولاد", "spot": 7000, "future": 7600, + "days": 30}, + {"name": "ب", "kind": "covered_call", "symbol": "خساپا", "spot": 1200, + "strike": 1300, "premium": 40, "days": 30}], + as_of="2026-09-22", source_label="پروندهٔ دستی") + + def test_stale_prices_are_marked_and_freshness_unknown(self): + def fake_fetch(url, **kw): + return json.dumps({"last": 7000}), "از حافظهٔ نهان ۴۰۰ ثانیه‌ای استفاده شد، نه از شبکه" + + with mock.patch.object(datafeed, "fetch", fake_fetch): + snap = datafeed.live_snapshot(self._snap(), + {"url_template": "http://example.ir/q?s={symbol}", + "json_path": "last", "cache_seconds": 0}, + allow_network=True) + self.assertIsNone(snap.freshness_seconds, "تازگی ناشناخته باید None باشد، نه صفر") + self.assertIn("حافظهٔ نهان", snap.source_label) + self.assertTrue(any("حافظهٔ نهان" in m for m in snap.messages)) + self.assertEqual(snap.status, "partial") + + def test_fresh_prices_keep_zero_freshness(self): + calls = {"n": 0} + + def fake_fetch(url, **kw): + calls["n"] += 1 + return json.dumps({"last": 7000 + calls["n"]}), "دریافت تازه در تلاش ۱" + + with mock.patch.object(datafeed, "fetch", fake_fetch): + snap = datafeed.live_snapshot(self._snap(), + {"url_template": "http://example.ir/q?s={symbol}", + "json_path": "last", "cache_seconds": 0}, + allow_network=True) + self.assertEqual(snap.freshness_seconds, 0.0) + self.assertIn("زندهٔ وب‌سرویس", snap.source_label) + self.assertNotIn("حافظهٔ نهان", snap.source_label) + + +class FixturePath(unittest.TestCase): + """مسیر نمایشی (سرور نمونهٔ محلی) باید همچنان کار کند: همان شکل، برچسب ساختگی.""" + + def test_fixture_still_serves_six_endpoints(self): + httpd, host = data_sources.start_fixture() + try: + result = data_sources.probe_all(symbol="فولاد", host=host, timeout=5, + with_stability=False) + finally: + httpd.shutdown() + self.assertGreaterEqual(result["summary"]["ok"], 5, result["verdict"]) + self.assertTrue(all(i["bytes"] >= 0 for i in result["items"])) + + +if __name__ == "__main__": + unittest.main(verbosity=2) + + +class TestStaleCacheHonesty(unittest.TestCase): + """قفل صداقت: جایزه‌ای که از حافظهٔ کهنه می‌آید نباید «موفقیت تازه» جا بزند.""" + + def setUp(self): + self.tmp = tempfile.mkdtemp() + self._old = datafeed.CACHE_DIR + datafeed.CACHE_DIR = Path(self.tmp) + + def tearDown(self): + datafeed.CACHE_DIR = self._old + shutil.rmtree(self.tmp, ignore_errors=True) + + def _write_stale(self, name, body): + f = Path(self.tmp) / name + f.write_text(body, encoding="utf-8") + old = time.time() - 3600 + os.utime(f, (old, old)) + + def test_stale_ok_false_never_returns_cached_body(self): + self._write_stale("probe.json", '{"cached": 12345}') + text, status = datafeed.fetch("http://127.0.0.1:9/none", timeout=1, retries=0, + cache_name="probe.json", cache_seconds=0, stale_ok=False) + self.assertIsNone(text) + self.assertNotIn("12345", status) + self.assertIn("دریافت ناموفق", status) + + def test_stale_ok_true_marks_the_number_as_cached(self): + self._write_stale("probe.json", '{"cached": 12345}') + text, status = datafeed.fetch("http://127.0.0.1:9/none", timeout=1, retries=0, + cache_name="probe.json", cache_seconds=0, stale_ok=True) + self.assertIsNotNone(text) + self.assertIn("حافظهٔ نهان", status) diff --git a/station/tests/test_demo_day.py b/station/tests/test_demo_day.py new file mode 100644 index 0000000000000000000000000000000000000000..0f9b90fec0b446c3e4009242f472b21a281481c9 --- /dev/null +++ b/station/tests/test_demo_day.py @@ -0,0 +1,225 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""آزمون‌های برگهٔ شاهد زنده — همه آفلاین: سرور نمونهٔ محلی جای سرویس واقعی می‌نشیند. + +هیچ آزمونی به اینترنت نمی‌رود و هیچ آزمونی پرونده‌های اصلی `data/witness-live.*` را دست نمی‌زند. +""" + +import hashlib +import json +import pathlib +import subprocess +import sys +import tempfile +import threading +import unittest +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer +from urllib.parse import parse_qs, urlparse + +BASE = pathlib.Path(__file__).resolve().parents[1] +if str(BASE) not in sys.path: + sys.path.insert(0, str(BASE)) + +import demo_day # noqa: E402 +import datafeed # noqa: E402 + +DESK_FILE = BASE.parent / "desk" / "market-demo.json" # نسبی: روی هر رایانهٔ دیگری هم کار می‌کند + + +class QuoteHandler(BaseHTTPRequestHandler): + """سرور نمونهٔ محلی: برای هر نماد یک قیمت متفاوت می‌دهد (تا سنجهٔ «نرخ واحد» گیر نکند).""" + + protocol_version = "HTTP/1.1" + same_for_all = False + hits = 0 + + def log_message(self, fmt, *args): + pass + + def do_GET(self): + u = urlparse(self.path) + symbol = (parse_qs(u.query).get("symbol") or [""])[0] + type(self).hits += 1 + table = {"اهرم": 19_500.0, "فولاد": 6_980.0, "کگل": 9_810.0, "خساپا": 2_090.0, + "طلا": 45_700_000.0, "شپنا": 12_450.0, "وبملت": 5_380.0} + if type(self).same_for_all: + price = 7_000.0 # عیناً یک نرخ برای همه (آزمون سنجهٔ صداقت) + else: + price = table.get(symbol, 5_000.0) + (type(self).hits % 7) * 0.5 + body = json.dumps({"data": [{"pl": price, "symbol": symbol}]}, + ensure_ascii=False).encode("utf-8") + self.send_response(200) + self.send_header("Content-Type", "application/json; charset=utf-8") + self.send_header("Content-Length", str(len(body))) + self.end_headers() + self.wfile.write(body) + + +class Fixture(unittest.TestCase): + """یک سرور محلی برای همهٔ آزمون‌های این پرونده.""" + + same_for_all = False + + @classmethod + def setUpClass(cls): + QuoteHandler.same_for_all = cls.same_for_all + cls.httpd = ThreadingHTTPServer(("127.0.0.1", 0), QuoteHandler) + cls.thread = threading.Thread(target=cls.httpd.serve_forever, daemon=True) + cls.thread.start() + cls.base = f"http://127.0.0.1:{cls.httpd.server_address[1]}" + cls.profile = {"name": "test-local", "label": "سرور نمونهٔ آزمون", "cost": "رایگان", + "url_template": cls.base + "/quote?symbol={symbol}", + "json_path": "data.0.pl", "key_header": "", "key_query_name": "", + "env_key": ""} + + @classmethod + def tearDownClass(cls): + cls.httpd.shutdown() + cls.httpd.server_close() + + def tmpdir(self): + d = tempfile.TemporaryDirectory() + self.addCleanup(d.cleanup) + return pathlib.Path(d.name) + + +class ProbeTests(Fixture): + def test_probe_reads_price_with_hash_and_latency(self): + probes = demo_day.probe(self.profile, ["اهرم", "فولاد"], timeout=4) + self.assertEqual([p["ok"] for p in probes], [True, True]) + for p in probes: + self.assertEqual(len(p["sha256"]), 64) + self.assertGreater(p["bytes"], 10) + self.assertGreaterEqual(p["latency_ms"], 0) + self.assertIn("آزمایشی محلی", p["source"]) + self.assertIn("data", p["snippet"]) + self.assertNotEqual(probes[0]["price"], probes[1]["price"]) + + def test_probe_reports_dead_endpoint_honestly(self): + dead = dict(self.profile, url_template="http://127.0.0.1:9/quote?symbol={symbol}") + probes = demo_day.probe(dead, ["اهرم"], timeout=2) + self.assertFalse(probes[0]["ok"]) + self.assertEqual(probes[0]["sha256"], "") + self.assertTrue(probes[0]["error"]) + + def test_empty_url_template_is_a_clear_error(self): + probes = demo_day.probe(dict(self.profile, url_template=""), ["اهرم"], timeout=2) + self.assertFalse(probes[0]["ok"]) + self.assertIn("قالب نشانی", probes[0]["error"]) + + def test_key_is_not_leaked_into_the_sheet(self): + prof = dict(self.profile, url_template=self.base + "/quote?key={key}&symbol={symbol}") + probes = demo_day.probe(prof, ["اهرم"], timeout=4, key="SECRETKEY123") + blob = json.dumps(probes, ensure_ascii=False) + self.assertIn("SECRETKEY123", probes[0]["url"]) # در نشانی هست (لازم است) + self.assertNotIn("SECRETKEY123", blob.replace(probes[0]["url"], "")) # ولی جای دیگری نه + + +class DecisionTests(Fixture): + def test_decision_uses_app_path_and_labels_sources(self): + probes = demo_day.probe(self.profile, ["اهرم", "فولاد"], timeout=4) + d = demo_day.decide(probes, path=DESK_FILE) + self.assertTrue(d["ready"], d.get("reason")) + chosen = d["chosen"] + self.assertIn("answer_num", chosen) + self.assertEqual(len(chosen["ladder"]), 3) + self.assertTrue(any(c.get("agree") for c in chosen["checks"])) + prov = {p["field"]: p for p in chosen["provenance"]} + if "spot" in prov: + self.assertEqual(prov["spot"]["source"], "زنده از سرویس") + if "future" in prov: + self.assertEqual(prov["future"]["source"], "از پروندهٔ پایه") + note = demo_day.mixed_sources_note(chosen) + self.assertIn("فرصت معاملاتی امروز", note) + + def test_decision_without_any_price_is_not_ready(self): + d = demo_day.decide([], path=DESK_FILE) + self.assertFalse(d["ready"]) + self.assertTrue(d["reason"]) + + def test_missing_base_file_is_reported(self): + d = demo_day.decide([], path="/tmp/definitely-not-here.json") + self.assertFalse(d["ready"]) + self.assertIn("خوانده نشد", d["reason"]) + + +class SingleRateGuard(Fixture): + """اگر سرویس برای همهٔ نمادها یک نرخ بدهد، باید صریح گفته شود نه اینکه عدد ساخته شود.""" + + same_for_all = True + + def test_identical_prices_are_flagged(self): + probes = demo_day.probe(self.profile, ["اهرم", "فولاد", "کگل"], timeout=4) + d = demo_day.decide(probes, path=DESK_FILE) + messages = " ".join(d["snapshot"]["messages"]) + self.assertIn("نرخ واحد", messages) + self.assertEqual(d["snapshot"]["status"], "partial") + + +class SheetTests(Fixture): + def test_sheet_files_and_honest_limits(self): + out = self.tmpdir() + doc = demo_day.build(profile=self.profile, symbols=["اهرم", "فولاد"], timeout=4, + path=DESK_FILE, page=out / "w.html", md=out / "w.md", + json_path=out / "w.json") + html = (out / "w.html").read_text(encoding="utf-8") + md = (out / "w.md").read_text(encoding="utf-8") + stored = json.loads((out / "w.json").read_text(encoding="utf-8")) + self.assertIn("Masoud Mojarabian", html) + self.assertIn("اثبات نمی‌کند", html) + self.assertIn("اثر انگشت", html) + self.assertIn("خوراک آزمایشی محلی", html) + self.assertIn("اثبات نمی‌کند", md) + self.assertIn("هر عدد از کجا آمد", md) + self.assertEqual(stored["page_hash"], doc["page_hash"]) + self.assertTrue(doc["limits"]) + + def test_page_hash_is_reproducible_from_the_json(self): + out = self.tmpdir() + doc = demo_day.build(profile=self.profile, symbols=["اهرم"], timeout=4, path=DESK_FILE, + page=out / "w.html", md=out / "w.md", json_path=out / "w.json") + core = json.dumps({"probes": doc["probes"], "decision": doc["decision"]}, + sort_keys=True, ensure_ascii=False) + self.assertEqual(doc["page_hash"], hashlib.sha256(core.encode("utf-8")).hexdigest()[:16]) + + def test_no_price_still_builds_an_honest_sheet(self): + out = self.tmpdir() + dead = dict(self.profile, url_template="http://127.0.0.1:9/quote?symbol={symbol}") + doc = demo_day.build(profile=dead, symbols=["اهرم"], timeout=2, path=DESK_FILE, + page=out / "w.html", md=out / "w.md", json_path=out / "w.json") + self.assertFalse(doc["decision"]["ready"]) + md = (out / "w.md").read_text(encoding="utf-8") + self.assertIn("تصمیم نمونه ساخته نشد", md) + self.assertIn("اثبات نمی‌کند", md) + + +class Helpers(Fixture): + def test_symbols_of_desk_file(self): + names = demo_day.symbols_of(DESK_FILE) + self.assertGreaterEqual(len(names), 3) + self.assertEqual(len(names), len(set(names))) + + def test_build_url_quotes_symbol_and_hides_missing_key(self): + cfg = {"url_template": "http://x/{symbol}?k={key}"} + self.assertEqual(demo_day.build_url(cfg, "فولاد", ""), "http://x/%D9%81%D9%88%D9%84%D8%A7%D8%AF?k=") + self.assertNotIn("{key}", demo_day.build_url(cfg, "فولاد", "abc")) + + +class CliTests(unittest.TestCase): + """خط فرمان با --out، بدون دست‌زدن به پرونده‌های اصلی.""" + + def test_cli_json_and_out_dir(self): + with tempfile.TemporaryDirectory() as d: + r = subprocess.run([sys.executable, "demo_day.py", "--json", "--out", d, + "--symbols", "اهرم", "--timeout", "2"], + cwd=str(BASE), capture_output=True, text=True, timeout=120) + self.assertIn(r.returncode, (0, 1), r.stderr) + self.assertNotIn("Traceback", r.stderr) + doc = json.loads(r.stdout) + self.assertIn("probes", doc) + self.assertTrue((pathlib.Path(d) / "witness-live.json").exists()) + self.assertTrue((pathlib.Path(d) / "witness-live.md").exists()) + + +if __name__ == "__main__": + unittest.main(verbosity=2) diff --git a/station/tests/test_demo_site.py b/station/tests/test_demo_site.py new file mode 100644 index 0000000000000000000000000000000000000000..5a0940e19c2823ea370a45df60af370588ac3e94 --- /dev/null +++ b/station/tests/test_demo_site.py @@ -0,0 +1,217 @@ +"""آزمون «نمونهٔ ثابت نمایشی» روی Hugging Face Static Space. + +چه می‌سنجیم: (۱) بستهٔ نمایشی از ضبط واقعی درست ساخته می‌شود (رابط + خروجی‌ها + لایهٔ ثابت)؛ +(۲) هیچ رمزی در آن نیست؛ (۳) **واقعاً کار می‌کند**: روی یک سرور محلی سرو می‌شود و آزمون‌گر +`tools/check_demo_site.mjs` (که خودش با jsdom گام‌ها را کلیک می‌کند) همهٔ ۲۲ بررسی را سبز می‌دهد؛ +(۴) ابزارهای نشر (`activate_demo_site.py`/`activate_hf.py`) معناشان درست است. + +این آزمون به شبکه بیرونی نیاز ندارد؛ سرور محلی روی درگاه آزاد خودش بالا می‌آید. +""" +from __future__ import annotations + +import json +import os +import socket +import subprocess +import sys +import tempfile +import time +import unittest +from pathlib import Path + +BASE = Path(__file__).resolve().parents[1] # .../money/gui +TOOLING_NEEDED = ("deploy/huggingface/make_demo_site.py", "deploy/huggingface/activate_demo_site.py") + + +# ── نگهبان بستهٔ تحویلی ───────────────────────────────────────────────────── +# این آزمون به ابزارهای «ساخت بسته» در پوشهٔ deploy نیاز دارد. آن ابزارها عمداً داخل بستهٔ +# تحویلی شرکت نیستند؛ پس اگر نبودند، باید تمیز «رد» شود نه اینکه هنگام بارگذاری بترکد +# (وگرنه «گزارش عیب‌یابی» در خودِ بسته، آزمون‌ها را سرخ نشان می‌دهد). +def _tooling_ready() -> tuple[bool, str]: + for rel in TOOLING_NEEDED: + if not (BASE / rel).exists(): + return False, f"ابزار ساخت در این بسته نیست: {rel}" + return True, "" + + +TOOLING_OK, WHY_NO_TOOLING = _tooling_ready() + +sys.path.insert(0, str(BASE / "deploy")) +sys.path.insert(0, str(BASE / "deploy" / "huggingface")) +try: + from security_scan import find_secret_literals +except Exception as _e: # noqa: BLE001 + find_secret_literals = None + _IMPORT_ERROR = f"{type(_e).__name__}: {_e}" + +HF = BASE / "deploy" / "huggingface" +RECORDING = BASE / "demo" / "static-recording.json" +def jsdom_available() -> bool: + """jsdom از افزوده‌های بیرونی است و در پیمان‌های کاری (snapshot) نگه داشته نمی‌شود.""" + for base in (Path("/home/user"), Path(__file__).resolve().parents[1]): + if (base / "node_modules" / "jsdom").exists(): + return True + return False + + +WHY_NO_JSDOM = "jsdom نصب نیست (برای آزمون‌های مرورگری لازم است؛ در بستهٔ تحویلی نصب می‌شود)" + + +CHECKER = BASE / "tools" / "check_demo_site.mjs" + + +def free_port() -> int: + s = socket.socket() + s.bind(("127.0.0.1", 0)) + port = s.getsockname()[1] + s.close() + return port + + +@unittest.skipUnless(TOOLING_OK, WHY_NO_TOOLING) +class TestDemoBundle(unittest.TestCase): + @classmethod + def setUpClass(cls): + import make_demo_site as M + cls.tmp = tempfile.TemporaryDirectory() + cls.out = Path(cls.tmp.name) / "iran-desk-demo" + cls.manifest = M.build(RECORDING, cls.out) + + @classmethod + def tearDownClass(cls): + cls.tmp.cleanup() + + def test_recording_is_checked_in_and_rich(self): + rec = json.loads(RECORDING.read_text(encoding="utf-8")) + self.assertGreater(len(rec), 30, "ضبط باید پاسخ‌های زیادی داشته باشد") + self.assertTrue(any(k.startswith("GET /api/") for k in rec)) + self.assertTrue(any(k.startswith("POST /api/") for k in rec)) + import make_demo_site as M + clean = M.sanitize(rec) + self.assertTrue(all(v["status"] < 400 for v in clean.values()), "پاسخ خطا نباید در دمو بماند") + self.assertLess(len(clean), len(rec) + 1) # پاک‌سازی چیزی را خراب نمی‌کند + + def test_bundle_structure(self): + for rel in ("README.md", "index.html", "app/index.html", "app/app.js", "app/recording.js", + "app/static-backend.js", "app/file-map.js", "DEMO-MANIFEST.json"): + self.assertTrue((self.out / rel).exists(), rel) + self.assertGreaterEqual(self.manifest["output_pages"], 8) + self.assertGreaterEqual(self.manifest["responses"], 30) + + def test_employer_guide_ships_with_the_bundle(self): + """راهنمای کارفرما باید داخل نمونه باشد و از صفحهٔ نخست پیوند بخورد.""" + g = self.out / "guide.html" + self.assertTrue(g.exists(), "راهنمای کارفرما در نمونه نیست") + body = g.read_text(encoding="utf-8") + self.assertIn("راهنمای", body) + self.assertNotIn('href="http://', body, "پیوند ناامن در راهنما") + home = (self.out / "index.html").read_text(encoding="utf-8") + self.assertIn('href="guide.html"', home) + self.assertEqual(self.manifest.get("guide"), "guide.html") + + def test_space_card_is_static(self): + t = (self.out / "README.md").read_text(encoding="utf-8") + self.assertTrue(t.startswith("---\n")) + for needle in ("sdk: static", "title:", "Masoud Mojarabian", "09126630554"): + self.assertIn(needle, t) + + def test_shim_has_no_browser_only_globals(self): + """لایهٔ ثابت باید در jsdom هم کار کند، پس Response/Headers مرورگر را لازم ندارد.""" + t = (self.out / "app" / "static-backend.js").read_text(encoding="utf-8") + self.assertNotIn("new Response(", t) + self.assertNotIn("new Headers(", t) + for needle in ("window.fetch", "__DEMO_RECORDING__", "/api/gate/status", "نمونهٔ ثابت"): + self.assertIn(needle, t) + + def test_no_secret_and_no_token_in_the_public_bundle(self): + for f in self.out.rglob("*"): + if f.is_file(): + self.assertEqual([], find_secret_literals(f), f"{f} مشکوک است") + text = f.read_text(encoding="utf-8", errors="ignore") + self.assertNotIn('"token"', text.replace(" ", ""), f"{f} توکن دارد") + self.assertNotIn("station_gate", text, f"{f} کوکی نشست دارد") + + def test_files_links_are_rewritten_to_saved_pages(self): + t = (self.out / "app" / "index.html").read_text(encoding="utf-8") + self.assertIn("static-backend.js", t) + self.assertIn("recording.js", t) + fmap = json.loads((self.out / "DEMO-MANIFEST.json").read_text(encoding="utf-8"))["file_map"] + self.assertIn("offer", fmap) + self.assertEqual("offer.html", fmap["offer"]) + self.assertTrue((self.out / "files" / "offer.html").exists()) + self.assertTrue((self.out / "files" / "walkthrough.txt").exists()) + + def test_home_page_says_the_honest_things(self): + t = (self.out / "index.html").read_text(encoding="utf-8") + for needle in ("نمونهٔ ثابت", "سود تضمینی", "سفارش خودکار", "Masoud Mojarabian", "app/index.html"): + self.assertIn(needle, t) + + +@unittest.skipUnless(TOOLING_OK, WHY_NO_TOOLING) +class TestDemoServers(unittest.TestCase): + """بسته را روی سرور محلی می‌گذاریم و همان آزمون‌گر زنده را می‌زنیم.""" + + @classmethod + def setUpClass(cls): + import make_demo_site as M + cls.tmp = tempfile.TemporaryDirectory() + cls.out = Path(cls.tmp.name) / "demo" + M.build(RECORDING, cls.out) + cls.port = free_port() + cls.srv = subprocess.Popen([sys.executable, "-m", "http.server", str(cls.port), + "--bind", "127.0.0.1"], cwd=str(cls.out), + stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL) + time.sleep(2.5) + + @classmethod + def tearDownClass(cls): + cls.srv.terminate() + try: + cls.srv.wait(timeout=10) + except subprocess.TimeoutExpired: + cls.srv.kill() + cls.tmp.cleanup() + + @unittest.skipUnless(jsdom_available(), WHY_NO_JSDOM) + def test_checker_is_all_green_against_the_built_site(self): + r = subprocess.run(["node", str(CHECKER), f"http://127.0.0.1:{self.port}"], + capture_output=True, text=True, cwd=str(BASE), timeout=600) + last = [ln for ln in r.stdout.strip().splitlines() if ln.strip()][-1] + self.assertEqual(0, r.returncode, r.stdout[-800:] + r.stderr[-400:]) + self.assertRegex(last, r"\d+ موفق · 0 ناموفق") + self.assertGreaterEqual(int(last.split("موفق")[0].strip().split()[-1]), 20) + + +@unittest.skipUnless(TOOLING_OK, WHY_NO_TOOLING) +class TestPublishTools(unittest.TestCase): + def test_tools_exist_and_parse(self): + for name in ("activate_demo_site.py", "activate_demo_site.sh", "make_demo_site.py"): + self.assertTrue((HF / name).exists(), name) + r = subprocess.run(["bash", "-n", str(HF / "activate_demo_site.sh")], + capture_output=True, text=True) + self.assertEqual(0, r.returncode, r.stderr) + + def test_static_space_url_comes_from_the_api(self): + """ایستاها روی دامنهٔ static.hf.space سرو می‌شوند؛ آدرس نباید حدسی باشد.""" + t = (HF / "activate_demo_site.py").read_text(encoding="utf-8") + for needle in ('.get("host")', "static.hf.space", "check_demo_site.mjs", + "desk-demo", "── تمام ──"): + self.assertIn(needle, t) + + def test_pro_message_explains_the_free_route(self): + t = (HF / "activate_hf.py").read_text(encoding="utf-8") + self.assertIn("Space داکری را اجازه نمی‌دهد", t) + self.assertIn("activate_demo_site.sh", t) # راه مجانی را نشان می‌دهد + self.assertIn("Render", t) + + def test_dry_run_of_demo_publisher_is_safe(self): + r = subprocess.run([sys.executable, str(HF / "activate_demo_site.py"), "--dry-run", + "--bundle", str(Path(tempfile.mkdtemp()) / "d")], + capture_output=True, text=True, cwd=str(HF), + env={k: v for k, v in os.environ.items() if k != "HF_TOKEN"}) + self.assertEqual(0, r.returncode, r.stderr) + self.assertIn("برای اجرای واقعی", r.stdout) + + +if __name__ == "__main__": + unittest.main(verbosity=2) diff --git a/station/tests/test_diagnose.py b/station/tests/test_diagnose.py new file mode 100644 index 0000000000000000000000000000000000000000..ab536e79966f9ba1f387a6c540e029c475e0bdcb --- /dev/null +++ b/station/tests/test_diagnose.py @@ -0,0 +1,108 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""آزمون «گزارش عیب‌یابی» (diagnose.py) — سبک، بدون اجرای آزمون‌های واحد درونی.""" +from __future__ import annotations + +import json +import subprocess +import sys +import tempfile +import unittest +from pathlib import Path + +HERE = Path(__file__).resolve().parent +GUI = HERE.parent +sys.path.insert(0, str(GUI)) + +import diagnose as dg # noqa: E402 + + +class TestCollect(unittest.TestCase): + @classmethod + def setUpClass(cls): + cls.rep = dg.collect(run_tests=False) + + def test_core_sections_present(self): + for key in ("ts", "python", "platform", "health", "license", "engine", "files", + "connections", "tests"): + self.assertIn(key, self.rep) + + def test_health_has_items(self): + items = self.rep["health"]["items"] + self.assertGreaterEqual(len(items), 5) + self.assertTrue(all({"name", "ok", "note"} <= set(i) for i in items)) + + def test_engine_fingerprint_recorded(self): + self.assertEqual(16, len(self.rep["engine"]["sha256_16"])) + + def test_files_section_marks_existence(self): + names = [f["name"] for f in self.rep["files"]] + self.assertIn("دفتر اتصال", names) + self.assertTrue(all(isinstance(f["exists"], bool) for f in self.rep["files"])) + + def test_quick_mode_skips_tests_but_stays_ok(self): + self.assertTrue(self.rep["tests"]["ok"]) + self.assertIn("سریع", self.rep["tests"]["tail"]) + + def test_summary_line_mentions_key_facts(self): + line = dg.summary_line(self.rep) + self.assertIn("سلامت", line) + self.assertIn("مجوز", line) + + +class TestReport(unittest.TestCase): + def test_report_files_written(self): + rep = dg.collect(run_tests=False) + with tempfile.TemporaryDirectory() as tmp: + h, t = dg.build_report(rep, Path(tmp) / "d.html") + html = h.read_text(encoding="utf-8") + txt = t.read_text(encoding="utf-8") + for needle in ("گزارش عیب‌یابی", "سلامت اجزا", "پرونده‌های مهم", + "Masoud Mojarabian", rep["engine"]["sha256_16"]): + self.assertIn(needle, html) + self.assertIn("سلامت", txt) + self.assertIn("engine", txt) + + def test_report_does_not_leak_account_data(self): + """گزارش فقط وضعیت فنی است؛ نباید حاوی راز یا کلید باشد.""" + rep = dg.collect(run_tests=False) + with tempfile.TemporaryDirectory() as tmp: + h, _ = dg.build_report(rep, Path(tmp) / "d.html") + body = h.read_text(encoding="utf-8") + for bad in ("api_key", "apiKey", "token=", "password"): + self.assertNotIn(bad, body) + + +class TestCli(unittest.TestCase): + def _run(self, *args): + return subprocess.run([sys.executable, str(GUI / "diagnose.py"), *args], + capture_output=True, text=True, timeout=300) + + def test_json_quick(self): + r = self._run("--json", "--quick") + self.assertIn(r.returncode, (0, 1)) + data = json.loads(r.stdout) + self.assertIn("health", data) + self.assertIn("engine", data) + + def test_tail_prefers_summary_and_hides_warnings(self): + """خط «نتیجه» باید گویا باشد، نه هشدار بی‌ربط پایان کار پایتون.""" + noisy = ("..\n" + "Ran 691 tests in 32.044s\n" + "OK (skipped=107)\n" + "sys:1: ResourceWarning: unclosed file <_io.TextIOWrapper name=9 encoding='UTF-8'>\n") + self.assertEqual(dg.pick_test_tail(noisy), "OK (skipped=107)") + red = "FAILED (errors=2)\nERROR: test_x (test_y.TestZ.test_x)\nFAIL: test_w (test_v.T.test_w)\n" + tail = dg.pick_test_tail(red) + self.assertTrue(tail.startswith("FAILED (errors=2)")) + self.assertIn("test_x", tail) + self.assertEqual(dg.pick_test_tail("").strip(), "بی‌پاسخ") + + def test_text_quick(self): + r = self._run("--text", "--quick") + self.assertIn("گزارش عیب‌یابی", r.stdout) + self.assertIn("سلامت", r.stdout) + + +if __name__ == "__main__": + unittest.main(verbosity=2) diff --git a/station/tests/test_dossier.py b/station/tests/test_dossier.py new file mode 100644 index 0000000000000000000000000000000000000000..3cf99c4cce800b71b5355d285d30d3dc4aa6fbf6 --- /dev/null +++ b/station/tests/test_dossier.py @@ -0,0 +1,141 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""آزمون «پروندهٔ سرمایه‌گذار»: آیا سند از شاهدهای واقعی ساخته می‌شود و ادعای اضافه نمی‌کند؟""" +from __future__ import annotations + +import json +import subprocess +import sys +import tempfile +import unittest +from pathlib import Path + +GUI = Path(__file__).resolve().parent.parent +if str(GUI) not in sys.path: + sys.path.insert(0, str(GUI)) + +import dossier as ds # noqa: E402 + + +class DossierEvidenceTests(unittest.TestCase): + def setUp(self): + self.tmp = tempfile.TemporaryDirectory() + self.dir = Path(self.tmp.name) + self.evidence = ds.collect(run_selftest=False) + + def tearDown(self): + self.tmp.cleanup() + + def test_evidence_has_every_section_source(self): + for key in ("rules", "connection", "snapshot", "trial", "scorecard", "self_test", "files"): + self.assertIn(key, self.evidence) + + def test_rules_are_the_station_defaults(self): + self.assertEqual(ds.DEFAULT_RULES["capital"], self.evidence["rules"]["capital"]) + self.assertEqual(0.39, self.evidence["rules"]["hurdle"]) + self.assertEqual(0.20, self.evidence["rules"]["max_margin_pct"]) + + def test_no_secret_leaks_into_evidence(self): + text = json.dumps(self.evidence, ensure_ascii=False).lower() + for forbidden in ("api_key", "apikey", "token", "secret", "password"): + self.assertNotIn(forbidden, text) + + def test_files_section_reports_digests_for_existing_files(self): + existing = [f for f in self.evidence["files"] if f.get("exists")] + self.assertGreater(len(existing), 3) + for f in existing: + self.assertEqual(16, len(f["sha256"])) + + def test_backtest_section_is_labelled_synthetic(self): + bt = self.evidence["backtest"] + self.assertIsNotNone(bt) + self.assertTrue(bt["synthetic"]) # دادهٔ نمونه هرگز «واقعی» جا زده نمی‌شود + self.assertIn("hit_rate_pct", bt["summary"]) + + def test_rules_cover_every_documented_parameter(self): + for key in self.evidence["rules"]: + self.assertIn(key, ds.RULE_NOTES, f"برای {key} توضیح فارسی ننوشته‌ایم") + + +class DossierOutputTests(unittest.TestCase): + def setUp(self): + self.tmp = tempfile.TemporaryDirectory() + self.dir = Path(self.tmp.name) + self.paths = ds.build(out=self.dir / "dossier.html", run_selftest=True) + + def tearDown(self): + self.tmp.cleanup() + + def test_builds_html_md_and_json(self): + for key in ("html", "md", "json"): + self.assertTrue(Path(self.paths[key]).exists(), key) + + def test_html_is_self_contained_and_has_credit(self): + html = Path(self.paths["html"]).read_text(encoding="utf-8") + self.assertIn('dir="rtl"', html) + self.assertIn("Masoud Mojarabian", html) + self.assertIn("instagram.com/Mojarabian.Art", html) + self.assertNotIn(" + + diff --git a/station/web/admin.js b/station/web/admin.js new file mode 100644 index 0000000000000000000000000000000000000000..f1fea5dc7646889a888a2516de16985503008e82 --- /dev/null +++ b/station/web/admin.js @@ -0,0 +1,304 @@ +/* پنل مدیریت ایستگاه — ورود، بررسی سلامت، مجوز/عیب‌یابی، گواهی استفاده. + همهٔ درخواست‌ها با سرآیند X-Admin-Token می‌روند؛ توکن فقط در همین مرورگر می‌ماند. */ + +const CREDIT = 'دولوپر: مهندس مسعود مجربیان · همراه: 09126630554 · ' + + 'Telegram: Mojarabian · ' + + 'Instagram: Mojarabian.Art'; + +const KEY = "station-admin-token"; +const $ = (id) => document.getElementById(id); + +const token = () => sessionStorage.getItem(KEY) || ""; +function setToken(t) { if (t) sessionStorage.setItem(KEY, t); else sessionStorage.removeItem(KEY); } + +function logTo(id, line) { + const box = $(id); + if (!box) return; + const t = new Date().toLocaleTimeString("fa-IR"); + box.textContent = (box.dataset.fresh === "1" ? "" : box.textContent + "\n") + `[${t}] ${line}`; + box.dataset.fresh = "0"; + box.scrollTop = box.scrollHeight; +} +function resetLog(id, line) { + const box = $(id); + if (!box) return; + box.textContent = line || ""; + box.dataset.fresh = "1"; +} + +async function api(path, body) { + const r = await fetch(path, { + method: "POST", + headers: { "Content-Type": "application/json", "X-Admin-Token": token() }, + body: JSON.stringify(body || {}), + }); + let data = {}; + try { data = await r.json(); } catch (e) { data = { error: "پاسخ خوانده نشد" }; } + data.__status = r.status; + return data; +} + +function showArea(on) { + $("admin-area").classList.toggle("hidden", !on); + $("login-card").classList.toggle("hidden", on); + $("who").textContent = on ? "وارد شده‌اید — دسترسی مدیر" : "وارد نشده‌اید"; +} + +async function doLogin() { + const id = $("admin-id").value.trim(); + const pass = $("admin-password").value; + if (!id || !pass) { logTo("login-box", "شناسه و رمز را پر کنید."); return; } + const d = await api("/api/admin/login", { id, pass }); + if (!d.ok) { logTo("login-box", "ورود ناموفق: " + (d.error || "دلیل نامشخص")); return; } + setToken(d.token); + resetLog("login-box", `ورود موفق · اعتبار توکن: ${d.expires_in_minutes} دقیقه بی‌کاری.`); + $("admin-password").value = ""; + showArea(true); + await licenseStatus(); +} + +async function whoami() { + if (!token()) { showArea(false); return false; } + const d = await api("/api/admin/whoami"); + if (!d.ok) { setToken(""); showArea(false); logTo("login-box", "توکن منقضی شده؛ دوباره وارد شوید."); return false; } + showArea(true); + return true; +} + +async function logout() { + if (token()) await api("/api/admin/logout"); + setToken(""); + showArea(false); + resetLog("login-box", "از پنل خارج شدید."); +} + +/* ---------------------------------------------------- ۱. بررسی سلامت */ + +async function doHealth() { + resetLog("log-health", "در حال بررسی…"); + const d = await api("/api/admin/health"); + if (!d.ok && !d.items) { logTo("log-health", "خطا: " + (d.error || "نامشخص")); return; } + const rows = (d.items || []).map((it) => + `${it.ok ? "✅" : "⚠️"}${it.name}${it.note || ""}`).join(""); + $("health-table").innerHTML = + `

    نسخهٔ ایستگاه: ${d.version || "—"} · گذشت ${d.passed || 0} از ${d.total || 0} جزء.

    + ${rows}
    جزءتوضیح
    `; + resetLog("log-health", d.ok ? "همهٔ اجزا سالم‌اند." : "بعضی اجزا هشدار دادند؛ به جدول بالا نگاه کنید."); +} + +/* ------------------------------------------- ۲. مجوز و عیب‌یابی */ + +function licPayload(extra) { + return Object.assign({ + client: $("lic-client").value.trim(), + months: parseInt($("lic-months").value || "12", 10), + contact: $("lic-contact").value.trim(), + }, extra || {}); +} + +async function licenseStatus() { + const d = await api("/api/admin/license", { action: "status" }); + const lic = d.license || {}; + $("license-state").innerHTML = lic.client + ? `

    مجوز فعلی: ${lic.client} · ${lic.months} ماه · صادر: ${lic.issued_on || "—"} + · انقضا: ${lic.expires_on || "—"} · امضا: ${lic.signature || "—"}

    ` + : `

    هیچ مجوزی صادر نشده است. نام شرکت را بنویسید و «صدور مجوز دسترسی» را بزنید.

    `; + resetLog("log-access", "وضعیت مجوز خوانده شد."); +} + +async function grantLicense() { + if (!$("lic-client").value.trim()) { logTo("log-access", "اول نام شرکت را بنویسید."); return; } + const d = await api("/api/admin/license", licPayload({ action: "grant" })); + if (!d.ok) { logTo("log-access", "خطا: " + (d.error || "صدور ناموفق")); return; } + logTo("log-access", `مجوز برای «${d.license.client}» صادر شد · مسیر: ${d.path}`); + logTo("log-access", `امضا: ${d.license.signature} · انقضا: ${d.license.expires_on}`); + await licenseStatus(); + logTo("log-access", "مجوز نام‌دار صادر شد."); + logTo("log-access", "قدم بعدی: «ساخت سند مجوز (چاپی)» و بعد بستهٔ شاهد گام ۸ — مجوز و گواهی خودکار داخل بسته می‌روند."); +} + +async function licenseDocument() { + const d = await api("/api/admin/license", { action: "document" }); + if (!d.ok) { logTo("log-access", "خطا: " + (d.error || "ساخت سند ناموفق")); return; } + logTo("log-access", `سند چاپی اجازه‌نامه: ${d.html}`); + logTo("log-access", `نسخهٔ متنی برای ایمیل: ${d.md}`); +} + +async function makeTrialLicense() { + const d = await api("/api/admin/license", licPayload({ action: "trial" })); + logTo("log-access", d.ok ? `مجوز آزمون ارزیابی ساخته شد · ${d.path}` : "خطا: " + (d.error || "—")); + await licenseStatus(); +} + +async function revokeLicense() { + if (!confirm("مجوز فعلی باطل شود؟")) return; + const d = await api("/api/admin/license", { action: "revoke" }); + logTo("log-access", d.ok ? "مجوز باطل شد." : "خطا: " + (d.error || "—")); + await licenseStatus(); +} + +async function runDiagnose() { + logTo("log-access", "در حال ساخت گزارش عیب‌یابی…"); + const d = await api("/api/admin/diagnose", {}); + if (!d.ok) { logTo("log-access", "خطا: " + (d.error || "ساخت ناموفق")); return; } + logTo("log-access", `گزارش ساخته شد: ${d.path || d.html}`); + if (d.fingerprint) logTo("log-access", `اثر انگشت موتور: ${d.fingerprint}`); +} + +/* ------------------------------------------- ۳′. پشتیبان ابری وضعیت */ + +async function loadStateInfo() { + const d = await api("/api/admin/state", {}); + if (!d || d.error) { logTo("log-state", "خطا: " + ((d && d.error) || "نامشخص")); return; } + if (!d.online) { + el("state-box").textContent = d.note || "پشتیبان ابری در این نسخه نیست."; + logTo("log-state", "پشتیبان ابری خاموش است (برنامه سالم است)."); + return; + } + const last = d.last || {}; + const done = last.ok ? `${last.at} · ${last.files} پرونده · ${last.kb} کیلوبایت` : "هنوز نه"; + el("state-box").innerHTML = + `زیر نگهبانی: ${d.files} پرونده · ${d.kb} کیلوبایت · هر ${Math.round((d.interval_seconds || 0) / 60)} دقیقه
    ` + + `آخرین پشتیبان: ${done}${last.reason ? " (" + last.reason + ")" : ""}
    ` + + `سرِ روشن‌شدن برگشت: ${(d.restored && d.restored.files) || 0} پرونده` + + `${(d.restored && d.restored.at) ? " (" + d.restored.at + ")" : ""}
    ` + + `مخزن: ${d.repo || "—"}`; + logTo("log-state", "وضعیت نگهبان خوانده شد."); +} + +async function backupNow() { + logTo("log-state", "در حال پشتیبان‌گیری…"); + const d = await api("/api/admin/backup", {}); + if (!d || d.error) { logTo("log-state", "خطا: " + ((d && d.error) || "نامشخص")); return; } + if (!d.ok) { logTo("log-state", d.note || "انجام نشد."); return; } + const last = d.last || {}; + logTo("log-state", `پشتیبان گرفته شد: ${last.files} پرونده · ${last.kb} کیلوبایت · ${last.at}`); + await loadStateInfo(); +} + +/* ------------------------------------------- ۳. گواهی استفاده */ + +async function loadUsage() { + const d = await api("/api/admin/usage", { action: "summary" }); + if (!d.ok) { logTo("usage-box", "خطا: " + (d.error || "نامشخص")); return; } + const s = d.summary || {}; + resetLog("usage-box", ""); + logTo("usage-box", + `مجموع کارهای موفق: ${s.success_total} · روزهای فعال: ${s.active_days} · امروز: ${s.today}` + + ` · زنجیره: ${s.chain_ok ? "سالم" : "شکسته در ردیف " + s.broken_at}`); + Object.entries(s.by_kind_label || s.by_kind || {}).forEach(([k, n]) => logTo("usage-box", `· ${k}: ${n}`)); + if (!s.rows) logTo("usage-box", "هنوز کاری ثبت نشده؛ با اجرای گام ۵ یا یک داوری سیگنال شروع می‌شود."); + $("usage-kpis").innerHTML = [ + ["کار موفق", s.success_total], ["روزهای فعال", s.active_days], + ["هفت روز گذشته", s.last_7_days], ["زنجیره", s.chain_ok ? "سالم ✅" : "شکسته ⚠️"], + ].map(([k, v]) => `
    ${v}${k}
    `).join(""); +} + +async function buildUsageStatement() { + const d = await api("/api/admin/usage", + { action: "statement", client: $("usage-client").value.trim() }); + if (!d.ok) { logTo("usage-box", "خطا: " + (d.error || "نامشخص")); return; } + logTo("usage-box", `گواهی ساخته شد: ${d.html}`); + logTo("usage-box", `نسخهٔ متنی برای ایمیل: ${d.md}`); + if (d.summary) logTo("usage-box", `کارهای موفق در این گواهی: ${d.summary.success_total} · زنجیره: ` + + (d.summary.chain_ok ? "سالم" : "شکسته در ردیف " + d.summary.broken_at)); +} + +/* ------------------------------------------- ۴. کاربران (شناسه/رمز دست خودت) */ + +async function gateUpdate(payload) { + /* دروازه با کوکیِ ورودِ خودش کار می‌کند؛ درخواست از همین صفحه فرستاده می‌شود */ + const r = await fetch("/api/gate/update", { method: "POST", + headers: { "Content-Type": "application/json" }, body: JSON.stringify(payload) }); + return await r.json(); +} + +function renderUsers(rows) { + const box = $("users-table"); + if (!rows || !rows.length) { + box.innerHTML = '
    هیچ کاربر مهمانی ساخته نشده است. ' + + 'می‌توانی همین‌جا برای هر نفر یک شناسه/رمز بسازی.
    '; + return; + } + box.innerHTML = "" + + "" + rows.map((u) => + `` + + `` + + `` + + `` + + ``).join("") + "
    شناسهوضعیتیادداشتنشست بازکار
    ${u.id}${u.enabled ? "فعال" : "قطع‌شده"}${u.note || "—"}${u.sessions || 0}` + + ` ` + + `` + + `
    "; +} + +async function loadUsers() { + const d = await fetch("/api/gate/status").then((r) => r.json()).catch(() => ({})); + renderUsers(d.users); + logTo("log-users", d.users ? `فهرست خوانده شد: ${d.users.length} کاربر (به‌جز حساب مهمانِ قدیمی).` + : "فهرست خوانده نشد؛ مطمئن شو با حساب مدیر وارد شده‌ای."); +} + +async function addUser() { + const id = $("new-user-id").value.trim(); + const pass = $("new-user-pass").value; + const note = $("new-user-note").value.trim(); + if (!id || !pass) { logTo("log-users", "شناسه و رمز را بنویس."); return; } + const res = await gateUpdate({ action: "user-add", id, pass, note }); + if (res.error) { logTo("log-users", "خطا: " + res.error); return; } + logTo("log-users", res.note); + $("new-user-pass").value = ""; + renderUsers(res.users); +} + +async function toggleUser(id, enable) { + const res = await gateUpdate({ action: enable ? "user-on" : "user-off", id }); + if (res.error) { logTo("log-users", "خطا: " + res.error); return; } + logTo("log-users", res.note); + renderUsers(res.users); +} + +async function deleteUser(id) { + if (!confirm(`کاربر «${id}» کامل حذف شود؟ نشست بازش هم همین حالا بسته می‌شود.`)) return; + const res = await gateUpdate({ action: "user-del", id }); + if (res.error) { logTo("log-users", "خطا: " + res.error); return; } + logTo("log-users", res.note); + renderUsers(res.users); +} + +async function setAdminCreds() { + const id = $("admin-new-id").value.trim(); + const pass = $("admin-new-pass").value; + if (!id || !pass) { logTo("log-admin-creds", "شناسه و رمز تازه را بنویس."); return; } + if (!confirm(`شناسهٔ ورود به «${id}» عوض شود؟ از این به بعد با همین وارد می‌شوی.`)) return; + const res = await gateUpdate({ action: "set-admin", id, pass }); + if (res.error) { logTo("log-admin-creds", "خطا: " + res.error); return; } + $("admin-new-pass").value = ""; + logTo("log-admin-creds", res.note + ` · شناسهٔ فعلی مدیر: ${res.admin.id}`); +} + +/* ------------------------------------------- پرونده‌های پنل (با توکن) */ + +async function openAdminFile(key) { + try { + const r = await fetch("/files/" + encodeURIComponent(key), + { headers: { "X-Admin-Token": token() } }); + if (!r.ok) { logTo(token() ? "log-access" : "login-box", "پرونده در دسترس نیست (" + r.status + ")"); return; } + const blob = await r.blob(); + window.open(URL.createObjectURL(blob), "_blank"); + } catch (e) { + logTo("log-access", "باز کردن پرونده ناموفق: " + e.message); + } +} + +/* ---------------------------------------------------- راه‌اندازی */ + +$("dev-credit").innerHTML = CREDIT; +window.addUser = addUser; window.loadUsers = loadUsers; +window.toggleUser = toggleUser; window.deleteUser = deleteUser; +window.setAdminCreds = setAdminCreds; +$("admin-id").addEventListener("keydown", (e) => { if (e.key === "Enter") doLogin(); }); +$("admin-password").addEventListener("keydown", (e) => { if (e.key === "Enter") doLogin(); }); +window.bootAdmin = async function bootAdmin() { await whoami(); if (token()) await loadUsers(); }; +window.addEventListener("load", () => window.bootAdmin()); diff --git a/station/web/app.js b/station/web/app.js new file mode 100644 index 0000000000000000000000000000000000000000..c92452d651025c845e75555772af7de9cf7d9fea --- /dev/null +++ b/station/web/app.js @@ -0,0 +1,1389 @@ +/* ایستگاه تصمیم مشتقه — منطق رابط گرافیکی مرورگری محلی */ +"use strict"; + +const STEPS = [ + ["health", "خوش‌آمد و پنل مدیریت"], + ["data", "منبع داده"], + ["settings", "تنظیمات ریاضی و ریسک"], + ["news", "خبر و هشدار"], + ["run", "اجرا و محاسبه"], + ["decide", "نتیجه و تصمیم"], + ["backtest", "پس‌آزمایی روی تاریخ"], + ["bundle", "بستهٔ تحویل شرکت"], + ["trial", "آزمون زنده و دفتر سرمایه‌گذار"], + ["blind", "آزمون کور سرمایه‌گذار"], + ["math", "راهبردها و ریاضیِ پول"], +]; + +const RULE_LABELS = { + capital: "سرمایه (ریال)", + hurdle: "نرخ سد سالانه (اعشار، مثلاً 0.39)", + min_edge_arbitrage_pct: "کف حاشیهٔ آربیتراژ (واحد درصد)", + min_edge_leveraged_pct: "کف حاشیهٔ اهرمی (واحد درصد)", + max_margin_pct: "سقف کل وجه تضمین (اعشار)", + max_position_pct: "سقف هر موقعیت از بودجه (اعشار)", + max_positions: "حداکثر موقعیت هم‌زمان", + min_liquidity_contracts_per_day: "کف نقدشوندگی (قرارداد در روز)", + max_spread_pct: "سقف اسپرد (اعشار، مثلاً 0.03)", + max_plausible_arb_pct: "سقف باورپذیری بازدهٔ آربیتراژ (درصد)", + max_plausible_lev_pct: "سقف باورپذیری بازدهٔ اهرمی (درصد)", +}; + +let current = 0; +let rules = {}; +let signals = []; +let selectedSid = null; +let packetText = ""; + +function el(id) { return document.getElementById(id); } + +function logTo(id, text) { + const box = el(id); + if (!box) return; + box.textContent += "\n" + text; + box.scrollTop = box.scrollHeight; +} + +function resetLog(id, text) { const box = el(id); if (box) box.textContent = text; } + +async function api(path, options) { + const res = await fetch(path, options); + if (res.status === 401) { // دروازه: نشست بسته شده است + const back = encodeURIComponent(location.pathname + location.search); + location.href = "/login?next=" + back; + return { error: "نشست بسته شد؛ دوباره وارد شوید." }; + } + const text = await res.text(); + try { return JSON.parse(text); } catch (e) { return { error: text || ("HTTP " + res.status) }; } +} + +function busy(id, on) { const b = el(id); if (b) b.classList.toggle("on", !!on); } + + +/* ---------------- گام ۱۱: راهبردها، شوک‌آزمون و ریاضی پول ---------------- */ +function faNum(x, digits) { + const n = Number(x); + if (!isFinite(n)) return "—"; + return n.toLocaleString("fa-IR", { maximumFractionDigits: digits === undefined ? 3 : digits }); +} + +function esc(v) { + return String(v === null || v === undefined ? "" : v) + .replace(/&/g, "&").replace(//g, ">") + .replace(/"/g, """).replace(/'/g, "'"); +} + +function table(headers, rows) { + const th = headers.map((h) => `${esc(h)}`).join(""); + const tr = rows.map((r) => `${r.map((c) => `${c}`).join("")}`).join(""); + return `${th}${tr}
    `; +} + +async function buildStrategies() { + busy("busy-strategies", true); + const res = await api("/api/strategies/sheet", { method: "POST", body: "{}" }); + busy("busy-strategies", false); + if (res.error) { resetLog("strategy-table", "خطا: " + res.error); return; } + const rows = (res.table || []).map((t) => [esc(t.name), esc(t.class), esc(t.value), + `${esc(t.method)}`, + t.resilience === null || t.resilience === undefined ? "—" : faNum(t.resilience, 0) + "٪"]); + let html = table(["راهبرد", "دسته", "عدد امروز", "روش عدد", "تاب‌آوری"], rows); + const sr = (res.stress_rows || []).map((r) => [esc(r.title), + r.annualized_pct === null ? "—" : faNum(r.annualized_pct) + "٪", + r.survives_today ? "می‌ماند ✅" : "می‌افتد ❌", + faNum(r.resilience_pct, 0) + "٪", + esc(r.first_failure || "— سخت‌جان"), + r.neutral_matches_engine ? "موتور ✅" : "ناهم‌خوان ⚠️"]); + html += `

    شوک‌آزمون — ${esc((res.counts && res.counts.checked) || 0)} ردیف بررسی شد؛ + سخت‌جان: ${esc((res.solid || []).join("، ") || "—")} · لبِ مرز: ${esc((res.marginal || []).join("، ") || "—")} + · افتاده: ${esc((res.dead || []).join("، ") || "—")}

    `; + html += table(["راهبرد", "بازده امروز", "می‌ماند؟", "تاب‌آوری", "اولین شوک", "حالت خنثی = موتور؟"], sr); + html += `

    ${esc(res.honesty || "")}

    `; + el("strategy-table").innerHTML = html; +} + +async function buildStress() { + const res = await api("/api/edge-stress/sheet", { method: "POST", body: "{}" }); + if (res.error) { resetLog("stress-table", "خطا: " + res.error); return; } + const rows = (res.rows || []).map((r) => [esc(r.title), + r.annualized_pct === null ? "—" : faNum(r.annualized_pct) + "٪", + r.survives_today ? "می‌ماند ✅" : "می‌افتد ❌", + faNum(r.resilience_pct, 0) + "٪", esc(r.first_failure || "— سخت‌جان"), + esc(r.fee_tolerance || "")]); + el("stress-table").innerHTML = table(["راهبرد", "بازده امروز", "می‌ماند؟", "تاب‌آوری", + "اولین شوک", "تحمل کارمزد"], rows); +} + +async function buildBankroll() { + busy("busy-bankroll", true); + const body = JSON.stringify({ + capital: Number(el("bk-capital").value || 0) || undefined, + target: Number(el("bk-target").value || 0) || undefined, + win_prob: Number(el("bk-winprob").value || 0) || undefined, + win_pct: Number(el("bk-win").value || 0) || undefined, + loss_pct: Number(el("bk-loss").value || 0) || undefined, + strategy_pct: Number(el("bk-strategy").value || 0) || undefined, + churn: Number(el("bk-churn").value || 0) || undefined, + }); + const res = await api("/api/bankroll/sheet", { method: "POST", body }); + busy("busy-bankroll", false); + if (res.error) { resetLog("bankroll-box", "خطا: " + res.error); return; } + const k = res.kelly || {}, s = res.sim || {}, p = res.path || {}, sp = res.strategy_path || {}; + let html = `

    اندازهٔ درست هر معامله: کِلی ${faNum(k.kelly_fraction)} · + نصف‌کِلی (محافظه‌کارانه) ${faNum(k.half_kelly_fraction)} · مزیت هر معامله + ${faNum(k.edge_pct_per_trade, 3)}٪

    `; + html += `

    کم‌ترین نرخ برد لازم: ${faNum((res.breakeven || {}).breakeven_win_pct, 2)}٪ — + زیر این عدد، هر راهبردی بازنده است.

    `; + html += table(["شبیه‌سازی (فرضی)", "عدد"], [ + ["احتمال نیم‌شدن حساب", faNum(s.ruin_prob) + " ‏(" + faNum(100 * (s.ruin_prob || 0), 2) + "٪)"], + ["احتمال دوبرابر‌شدن", faNum(100 * (s.double_prob || 0), 2) + "٪"], + ["احتمال سود", faNum(100 * (s.profit_prob || 0), 2) + "٪"], + ["میانهٔ پایان", faNum(s.median_final, 0) + " (" + faNum(s.median_multiple) + "× شروع)"], + ["بازهٔ ۱۰٪ تا ۹۰٪", faNum(s.p10_final, 0) + " تا " + faNum(s.p90_final, 0)], + ["مسیر کِلی (مدل فرضی)", esc(p.detail || "")], + ["مسیر راهبرد", esc(sp.detail || "")], + ]); + html += `

    ${esc(res.honesty || "")}

    `; + el("bankroll-box").innerHTML = html; +} + +/* ---------------- ناوبری ---------------- */ +function buildNav() { + const nav = el("nav"); + STEPS.forEach((s, i) => { + const a = document.createElement("a"); + a.href = "#"; + a.id = "nav-" + s[0]; + a.innerHTML = `${i + 1}${s[1]}`; + a.onclick = (e) => { e.preventDefault(); showStep(i); }; + nav.appendChild(a); + }); +} + +function showStep(i) { + current = Math.max(0, Math.min(i, STEPS.length - 1)); + STEPS.forEach((s, idx) => { + const sec = el("s-" + s[0]); + if (sec) sec.classList.toggle("active", idx === current); + const a = el("nav-" + s[0]); + if (a) a.classList.toggle("active", idx === current); + }); +} + +function go(delta) { showStep(current + delta); } + +/* ---------------- گام ۱: سلامت ---------------- */ + +/* ---------------- گام ۲: داده ---------------- */ +function modeNow() { return document.querySelector('input[name=mode]:checked').value; } + +async function pickMode() { + const mode = modeNow(); + const cards = { sim: 0, file: 0, live: 0 }; + const data = await api("/api/mode-info?mode=" + mode); + if (!data.error) { + el("mode-text").innerHTML = `انتخاب شما: ${data.label}
    هزینه: ${data.cost}
    ` + + `چه می‌دهد: ${data.gives}
    پس از اتصال چه تغییر می‌کند: ${data.after}
    چگونه: ${data.how}`; + cards.sim = cards.file = cards.live = 1; + } + el("card-file").style.display = (mode === "sim") ? "none" : "block"; + el("card-live").style.display = (mode === "live") ? "block" : "none"; + await api("/api/mode", { method: "POST", headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ mode }) }); +} + +async function loadGuide() { + const data = await api("/api/data-guide"); + if (data.error) return; + el("api-guide").innerHTML = data.rows.map((r) => + `${r[0]}${r[1]}${r[2]}${r[3]}${r[4]}`).join(""); + if (data.snapshot_template) el("file-path").value = data.snapshot_template; + if (data.history_template) el("hist-path").value = data.history_template; + if (data.kodal_db) el("kodal-db").value = data.kodal_db; +} + +async function makeTemplate() { + const data = await api("/api/template", { method: "POST", headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ kind: "snapshot" }) }); + if (data.error) { logTo("log-data", "خطا: " + data.error); return; } + el("file-path").value = data.path; + logTo("log-data", "قالب اسنپ‌شات ساخته شد: " + data.path); +} + +async function testData() { + resetLog("log-data", "آزمایش خواندن پرونده…"); + const data = await api("/api/test-data", { method: "POST", headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ mode: modeNow(), file_path: el("file-path").value }) }); + (data.messages || []).forEach((m) => logTo("log-data", "· " + m)); + logTo("log-data", `وضعیت: ${data.status} · ردیف‌ها: ${data.rows} · تازگی: ${data.freshness}`); + updateBadge(data.status, data.source_label, data.freshness, data.rows); +} + +async function testLive() { + resetLog("log-data", "آزمایش اتصال سرویس…"); + const cfg = { url_template: el("live-url").value, json_path: el("live-path").value, + key_header: el("live-header").value, key_query_name: el("live-qname").value }; + const data = await api("/api/test-live", { method: "POST", headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ live_cfg: cfg, key: el("live-key").value, + file_path: el("file-path").value }) }); + (data.messages || []).forEach((m) => logTo("log-data", "· " + m)); + logTo("log-data", `وضعیت: ${data.status} · تازگی: ${data.freshness} · ردیف: ${data.rows}`); + if (data.status === "ok") logTo("log-data", "از این پس قیمت پایه از سرویس خوانده می‌شود و تازگی داده سبز می‌ماند."); + else logTo("log-data", "راهنما: قالب نشانی و مسیر JSON را از مستندات فروشنده بردارید؛ اگر عدد در پاسخ تغییر کند، فقط همین دو خط را عوض کنید."); + updateBadge(data.status, data.source_label, data.freshness, data.rows); +} + +function updateBadge(status, label, freshness, rows) { + const color = status === "ok" ? "#9ae6b4" : (status === "partial" ? "#ffe08a" : "#feb2b2"); + el("badge").textContent = `منبع: ${label || "—"} · تازگی: ${freshness || "—"} · ردیف: ${rows || 0}`; + el("badge").style.color = color; +} + +/* ---------------- گام ۳: تنظیمات ---------------- */ +async function loadRules() { + const data = await api("/api/state"); + rules = data.rules || {}; + el("rules-box").innerHTML = Object.keys(rules).map((k) => + `
    `).join(""); +} + +async function saveRules() { + const out = {}; + Object.keys(rules).forEach((k) => { const v = el("rule-" + k).value.trim(); out[k] = isNaN(v) ? v : Number(v); }); + const data = await api("/api/rules", { method: "POST", headers: { "Content-Type": "application/json" }, + body: JSON.stringify(out) }); + resetLog("log-settings", data.error ? ("خطا: " + data.error) : ("ذخیره شد: " + JSON.stringify(data.rules))); + rules = data.rules || rules; +} + +/* ---------------- گام ۴: خبر ---------------- */ +async function runKodalDemo() { + resetLog("log-news", "اجرای دیده‌بان روی دادهٔ نمونه…"); + const data = await api("/api/kodal/demo", { method: "POST" }); + (data.items || []).forEach((it) => logTo("log-news", `[${it.score}] ${it.direction} · ${it.category} · ${it.symbol || "-"} · ${it.title}`)); + if (data.kodal_db) el("kodal-db").value = data.kodal_db; + logTo("log-news", `${(data.items || []).length} هشدار ساخته و ثبت شد.`); +} + +async function showAlerts() { + const data = await api("/api/alerts?db=" + encodeURIComponent(el("kodal-db").value)); + resetLog("log-news", "هشدارهای فعلی:"); + (data.items || []).forEach((a) => logTo("log-news", `[${a.score}] ${a.direction} · ${a.category} · ${a.symbol || "-"} · ${a.title}`)); + if (!(data.items || []).length) logTo("log-news", "هشداری نیست یا پایگاه‌داده خالی است."); +} + +/* ---------------- گام ۵: اجرا ---------------- */ +async function doRun() { + resetLog("log-run", "شروع محاسبه…"); + busy("busy-run", true); + const payload = { mode: modeNow(), file_path: el("file-path").value, key: el("live-key").value, + live_cfg: { url_template: el("live-url").value, json_path: el("live-path").value, + key_header: el("live-header").value, key_query_name: el("live-qname").value }, + use_kodal: el("use-kodal").checked, kodal_db: el("kodal-db").value, rules }; + const data = await api("/api/run", { method: "POST", headers: { "Content-Type": "application/json" }, + body: JSON.stringify(payload) }); + busy("busy-run", false); + if (data.error) { logTo("log-run", "خطا: " + data.error); return; } + (data.messages || []).forEach((m) => logTo("log-run", "· " + m)); + const c = data.counts || {}; + el("run-kpis").innerHTML = [ + ["کل سیگنال", c.total], ["منتظر تأیید", c.pending], ["تأییدشده", c.approved], ["رد شده", c.rejected], + ["کار بازبینی", c.tasks], ["سرمایهٔ درگیر (ریال)", (c.locked || 0).toLocaleString("fa-IR")], + ].map(([k, v]) => `
    ${k}
    ${v}
    `).join(""); + (data.signals || []).forEach((s) => { + logTo("log-run", `${s.mark} ${s.symbol} · ${s.kind_label} · بازده ${s.annualized} · حاشیه ${s.edge} · ${s.size}`); + if (s.status === "rejected" && s.gate_note) logTo("log-run", " دلیل رد: " + s.gate_note); + (s.alerts || []).slice(0, 2).forEach((a) => logTo("log-run", ` خبر: [${a.score}] ${a.title}`)); + }); + (data.tasks || []).forEach((t) => logTo("log-run", `کار بازبینی: ${t.symbol} — ${t.reason}`)); + updateBadge(data.status, data.source_label, data.freshness, data.rows); + logTo("log-run", "داشبورد به‌روز شد؛ از دکمهٔ «نمایش داشبورد» ببینید."); + await loadSignals(); +} + +/* ---------------- گام ۶: تصمیم ---------------- */ +async function loadSignals() { + const data = await api("/api/signals"); + signals = data.signals || []; + const body = document.querySelector("#signals-table tbody"); + body.innerHTML = signals.map((s) => ` + ${s.sid}${s.symbol}${s.kind_label} + ${s.annualized}${s.edge}${s.size} + ${(s.margin_locked || 0).toLocaleString("fa-IR")} + ${s.status_label} + ${s.gate_note || ""}${(s.alerts || []).length ? " | خبر: " + s.alerts[0].title : ""} + `).join("") || `سیگنالی نیست؛ اول گام ۵ را اجرا کنید.`; +} + +function selectSignal(sid) { + selectedSid = sid; + const s = signals.find((x) => x.sid === sid); + if (!s) return; + resetLog("log-decide", `— ${s.symbol} · ${s.kind_label} · وضعیت ${s.status_label}`); + logTo("log-decide", " جزئیات ریاضی: " + JSON.stringify(s.detail).slice(0, 400)); + (s.alerts || []).forEach((a) => logTo("log-decide", ` خبر: [${a.score}] ${a.title}`)); +} + +async function decide(action) { + if (!selectedSid) { logTo("log-decide", "اول یک ردیف از جدول را انتخاب کنید."); return; } + const data = await api("/api/decide", { method: "POST", headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ sid: selectedSid, action, + note: el("decide-note").value }) }); + if (data.error) { logTo("log-decide", "خطا: " + data.error); return; } + if (data.blocked) { + if (!confirm(data.message + "\n\nباز هم تأیید می‌کنید؟ (در دفتر با برچسب «رد سقف» ثبت می‌شود)")) { + logTo("log-decide", "تأیید نشد؛ سیگنال همان‌طور منتظر تأیید ماند."); + return; + } + const forced = await api("/api/decide", { method: "POST", headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ sid: selectedSid, action, force: true, + note: (el("decide-note").value + " | تأیید با رد سقف ریسک") }) }); + if (forced.error) { logTo("log-decide", "خطا: " + forced.error); return; } + /* پاسخ نخست «سقف رد شد» بود و بستهٔ سفارش نداشت؛ بسته را از همین تأییدِ رد‌سقف‌شده برمی‌داریم */ + data.packet = forced.packet || data.packet || ""; + logTo("log-decide", "یادآوری: این تأیید سقف ریسک را رد کرد؛ در دفتر با برچسب «رد سقف» ثبت شد."); + } + logTo("log-decide", (action === "approved" ? "تأیید شد: " : "رد شد: ") + selectedSid); + packetText = data.packet || ""; + if (packetText) { + el("packet-card").style.display = "block"; + el("packet").textContent = packetText; + logTo("log-decide", "بستهٔ سفارش بالا آمده؛ آن را در سامانهٔ کارگزاری خودتان اجرا کنید."); + } + await loadSignals(); +} + +function copyPacket() { + navigator.clipboard.writeText(packetText).then(() => logTo("log-decide", "بستهٔ سفارش در حافظه کپی شد."), + () => logTo("log-decide", "کپی نشد؛ متن را دستی انتخاب کنید.")); +} + +/* ---------------- گام ۷: پس‌آزمایی ---------------- */ +async function makeHistTemplate() { + const data = await api("/api/template", { method: "POST", headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ kind: "history" }) }); + if (data.path) { el("hist-path").value = data.path; logTo("log-bt", "قالب ستون‌ها ساخته شد: " + data.path); } +} + +async function doBacktest() { + resetLog("log-bt", "اجرای پس‌آزمایی…"); + busy("busy-bt", true); + const data = await api("/api/backtest", { method: "POST", headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ path: el("hist-path").value, rules }) }); + busy("busy-bt", false); + if (data.error) { logTo("log-bt", "خطا: " + data.error); return; } + (data.problems || []).forEach((p) => logTo("log-bt", "· " + p)); + const s = data.summary || {}; + el("bt-kpis").innerHTML = [ + ["سطرها", s.rows], ["ورود", s.taken], ["رد", s.skipped], + ["نرخ برد", s.hit_rate_pct == null ? "—" : s.hit_rate_pct.toFixed(1) + "٪"], + ["خطای مثبت کاذب", s.false_positive_rate_pct == null ? "—" : s.false_positive_rate_pct.toFixed(1) + "٪"], + ["فرصت از دست رفته", s.missed_opportunity_rate_pct == null ? "—" : s.missed_opportunity_rate_pct.toFixed(1) + "٪"], + ["میانگین انتظاری", s.avg_expected_annualized_pct == null ? "—" : s.avg_expected_annualized_pct.toFixed(1) + "٪"], + ["میانگین واقعی", s.avg_realized_annualized_pct == null ? "—" : s.avg_realized_annualized_pct.toFixed(1) + "٪"], + ["خطای پیش‌بینی", s.avg_forecast_error_pp == null ? "—" : s.avg_forecast_error_pp.toFixed(1)], + ["سرمایهٔ پایانی", s.final_equity == null ? "—" : s.final_equity.toLocaleString("fa-IR")], + ].map(([k, v]) => `
    ${k}
    ${v}
    `).join(""); + logTo("log-bt", `نرخ برد ${s.hit_rate_pct?.toFixed(1)}٪ · خطای مثبت کاذب ${s.false_positive_rate_pct?.toFixed(1)}٪ · ` + + `خطای پیش‌بینی ${s.avg_forecast_error_pp?.toFixed(1)} واحد درصد`); + if (s.avg_forecast_error_pp != null && s.avg_forecast_error_pp < 0) { + logTo("log-bt", "درس: میانگین واقعی از انتظار کمتر است؛ یعنی موتور خوش‌بینانه است. کف حاشیه را بالا ببرید یا انتظار را کم کنید."); + } + if ((data.file || "").includes("demo")) logTo("log-bt", "هشدار: این پرونده نمونهٔ ساختگی است؛ برای ارائه به شرکت دادهٔ واقعی خودتان را بدهید."); +} + +/* ---------------- گام ۸: بسته ---------------- */ +async function doBundle() { + resetLog("log-bundle", "ساخت بسته…"); + busy("busy-bundle", true); + const data = await api("/api/bundle", { method: "POST" }); + busy("busy-bundle", false); + if (data.error) { logTo("log-bundle", "خطا: " + data.error); return; } + logTo("log-bundle", "بسته ساخته شد: " + data.path); + el("bundle-list").innerHTML = `` + + (data.files || []).map((f) => ` + `).join("") + `
    پروندهتوضیح
    ${f.file}${f.desc}
    `; + (data.files || []).forEach((f) => logTo("log-bundle", " · " + f.file)); + logTo("log-bundle", "پیشنهاد ارائه: اول سند روش کار، بعد داشبورد، و در پایان چک‌لیست راستی‌آزمایی."); +} + +/* ---------------- گام ۲: دفتر اتصال ---------------- */ +let CONN = { profiles: [], selected: "", active: {} }; + +async function loadConnections() { + const data = await api("/api/connections"); + if (data.error) return; + CONN = data; + const sel = el("conn-select"); + sel.innerHTML = (data.profiles || []).map((p) => { + const star = p.name === data.selected ? "★ " : ""; + const tested = p.tested ? " · آزمون‌شده" : ""; + return ``; + }).join(""); + sel.value = data.selected || (data.profiles || [])[0]?.name || ""; + renderConnInfo(); + await loadProfile(); +} + +function renderConnInfo() { + const p = (CONN.profiles || []).find((x) => x.name === el("conn-select").value) || {}; + const a = CONN.active || {}; + const ks = (CONN.key_status || {})[p.name] || {}; + el("conn-info").innerHTML = + `${p.label || "—"} — هزینه: ${p.cost || "—"}
    ` + + `چه می‌دهد: ${p.gives || "—"}
    ` + + `پس از اتصال چه تغییر می‌کند: ${p.after || "—"}
    ` + + `چگونه: ${p.steps || "—"}` + + (p.note ? `
    ${p.note}` : "") + + `
    وضعیت کلید: ${ks.has_key ? ks.where : "بدون کلید"} · ` + + `${ks.env_key ? "متغیر محیطی: " + ks.env_key : "متغیر محیطی تنظیم نشده"} · ` + + `فعال‌شده: ${a.label || "—"}`; + el("key-status").textContent = ks.stored ? "کلید این پروفایل روی رایانه ذخیره شده است." : "کلیدی ذخیره نشده است."; +} + +async function loadProfile() { + const name = el("conn-select").value; + const p = (CONN.profiles || []).find((x) => x.name === name); + if (!p) return; + el("live-url").value = p.url_template || ""; + el("live-path").value = p.json_path || ""; + el("live-header").value = p.key_header || ""; + el("live-qname").value = p.key_query_name || ""; + el("conn-name").value = p.name; + el("conn-label").value = p.label || ""; + el("conn-env").value = p.env_key || ""; + el("peek-url").value = p.url_template || ""; + renderConnInfo(); +} + +function currentConnectionForm() { + return { + name: (el("conn-name").value || el("conn-select").value || "custom").trim(), + label: (el("conn-label").value || "").trim(), + url_template: el("live-url").value.trim(), + json_path: el("live-path").value.trim(), + key_header: el("live-header").value.trim(), + key_query_name: el("live-qname").value.trim(), + env_key: (el("conn-env").value || "").trim(), + cost: ((CONN.profiles || []).find((x) => x.name === el("conn-select").value) || {}).cost || "", + tested: false, + }; +} + +async function saveProfile() { + const body = { profile: currentConnectionForm(), key: el("live-key").value, + save_key: el("save-key").checked, select: true }; + const data = await api("/api/connections/save", { method: "POST", headers: { "Content-Type": "application/json" }, + body: JSON.stringify(body) }); + if (data.error) { logTo("log-data", "خطا: " + data.error); return; } + logTo("log-data", `پروفایل «${data.profile.label || data.profile.name}» ذخیره و فعال شد.` + + (el("save-key").checked ? " کلید هم روی همین رایانه ذخیره شد." : " کلید فقط در حافظه ماند.")); + await loadConnections(); +} + +async function saveAsNew() { + el("conn-select").value = ""; // تا نام تازه جای دیگری را عوض نکند + await saveProfile(); + logTo("log-data", "اگر نام کوتاه را به یک نام تازه عوض کنید، یک پروفایل مستقل ساخته می‌شود."); +} + +async function deleteProfile() { + const name = el("conn-select").value; + if (!confirm(`پروفایل «${name}» و کلید ذخیره‌شدهٔ آن پاک شود؟`)) return; + const data = await api("/api/connections/delete", { method: "POST", headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ name }) }); + logTo("log-data", data.error ? ("خطا: " + data.error) : `پروفایل ${name} پاک شد.`); + await loadConnections(); +} + +async function saveKey() { + const name = el("conn-name").value || el("conn-select").value; + const data = await api("/api/connections/key", { method: "POST", headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ name, key: el("live-key").value, + save: el("save-key").checked }) }); + if (data.error) { logTo("log-data", "خطا: " + data.error); return; } + logTo("log-data", data.saved ? "کلید روی همین رایانه ذخیره شد (فقط برای همین کاربر)." + : "کلید فقط در حافظهٔ همین اجرا نگه داشته شد و ذخیره نشد."); + await loadConnections(); +} + +async function testProfile() { + resetLog("log-data", "آزمایش اتصال پروفایل…"); + const name = el("conn-select").value; + const sel = await api("/api/connections/select", { method: "POST", headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ name, key: el("live-key").value }) }); + if (sel.error) { logTo("log-data", "خطا: " + sel.error); return; } + if (sel.is_mock) logTo("log-data", "یادآوری: این خوراک ساختگی است (برای آزمایش و نمایش)."); + await testLive(); +} + +async function peekService() { + const box = el("peek-result"); + box.innerHTML = "در حال خواندن پاسخ سرویس…"; + const data = await api("/api/peek", { method: "POST", headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ url: el("peek-url").value, key: el("live-key").value, + key_header: el("live-header").value }) }); + if (data.error) { box.innerHTML = `خطا: ${data.error}`; return; } + const rows = (data.paths || []).map((x) => + `${x.path}${x.value.toLocaleString("fa-IR")} + `).join(""); + box.innerHTML = `پاسخ آمد (${data.bytes} بایت). مسیرهای عددی پیدا‌شده: + ${rows || + ''}
    مسیرمقدار
    عدد قابل‌استفاده‌ای در پاسخ نبود؛ شاید پاسخ HTML است.
    +
    پیش‌نمایش پاسخ خام
    ${(data.preview || "").replace(/
    `; +} + +function usePeekPath(path) { + el("live-path").value = path; + logTo("log-data", "مسیر JSON انتخاب شد: " + path + " — حالا «آزمایش اتصال» را بزنید."); +} + +/* ---------------- گام ۹: دفتر آزمون زنده ---------------- */ +async function loadTrial() { + const data = await api("/api/trial"); + if (data.error) return; + renderTrial(data); +} + +function renderTrial(data) { + const s = data.summary || {}; + renderScorecard(data.scorecard, data.runs); + const fa = (x, nd = 2) => (x == null ? "—" : Number(x).toLocaleString("fa-IR", { maximumFractionDigits: nd })); + el("trial-kpis").innerHTML = [ + ["ثبت‌ها", s.entries], ["بازسنجی‌شده", s.marked], ["بازسنجی‌نشده", s.unmarked], + ["میانگین انتظار در ثبت (٪)", fa(s.avg_expected)], + ["میانگین تغییر (واحد درصد)", fa(s.avg_delta_pp)], + ["بهترین تغییر", fa(s.best_delta_pp)], ["بدترین تغییر", fa(s.worst_delta_pp)], + ].map(([k, v]) => `
    ${k}
    ${v}
    `).join(""); + const buckets = s.buckets || {}; + el("chain-status").innerHTML = `وضعیت زنجیره: ${s.chain_ok ? "✅ " : "✗ "}${s.chain_message || "—"}` + + ` · ${Object.keys(buckets).map((k) => k + ": " + buckets[k]).join(" · ") || "بازسنجی‌ای ثبت نشده"}`; + const body = document.querySelector("#trial-table tbody"); + const rows = (data.entries || []).map((e) => { + const d = e.delta_pp; + const color = d == null ? "" : (d >= 1 ? "var(--ok)" : (d <= -1 ? "var(--bad)" : "var(--muted)")); + return `${e.id}${e.ts}${e.symbol} + ${e.kind}${e.decision} + ${fa(e.expected)}${fa(e.expected_now)} + ${fa(d)} + ${e.status_now}${e.source_label || "—"} + ${e.hash}`; + }).join(""); + body.innerHTML = rows || `هنوز چیزی ثبت نشده است؛ از دکمهٔ بالا شروع کنید.`; +} + +async function runDaily(conservative) { + resetLog("log-trial", "اجرای مراسم امروز…"); + busy("busy-daily", true); + const data = await api("/api/trial/daily", { method: "POST", headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ note: el("daily-note").value, + add_span: conservative ? -2 : 0 }) }); + busy("busy-daily", false); + if (data.error) { logTo("log-trial", "خطا: " + data.error); return; } + (data.notes || []).forEach((m) => logTo("log-trial", "· " + m)); + const r = data.record || {}; + logTo("log-trial", `امروز ${r.date} · منبع: ${data.source_label || "—"} · ` + + `ثبت ${r.recorded} · بازسنجی ${r.marked}`); + if (data.synthetic) logTo("log-trial", "توجه: دادهٔ امروز ساختگی بود؛ برای ارائه به شرکت روزهای واقعی لازم است."); + if (data.report) logTo("log-trial", "گزارش سرمایه‌گذار به‌روز شد: " + data.report); + renderTrial(data.trial || {}); +} + +function renderScorecard(score, runs) { + if (!score) return; + const fa = (x) => (x == null ? "—" : String(x)); + el("score-kpis").innerHTML = [ + ["روزهای ثبت‌شده", score.days], ["روزهای واقعی (نه ساختگی)", score.real_days], + ["اجراها", score.runs], ["ردیف‌های دفتر", score.entries], ["بازسنجی‌شده", score.marked], + ["حرکت‌های معنادار", score.moved], ["فرصت بازتر", score.up], ["فرصت بسته", score.down], + ].map(([k, v]) => `
    ${k}
    ${fa(v)}
    `).join(""); + el("score-verdict").innerHTML = (score.ready ? "✅ " : "⏳ ") + score.verdict; + el("score-verdict").style.background = score.ready ? "#e7f6ec" : ""; + el("score-verdict").style.borderColor = score.ready ? "#b7e0c6" : ""; + document.querySelector("#score-table tbody").innerHTML = (score.criteria || []).map((c) => { + const have = typeof c.have === "object" ? JSON.stringify(c.have) : c.have; + const want = typeof c.want === "object" ? JSON.stringify(c.want) : c.want; + return `${c.ok ? "✅" : "✗"}${c.name}${have} + ${want}${c.hint}`; + }).join(""); + el("runs-list").innerHTML = (runs || []).map((r) => + `${r.ts || ""} · ${r.mode || ""} · ${r.synthetic ? "ساختگی" : "واقعی"} · ثبت ${r.recorded} · ` + + `بازسنجی ${r.marked}${r.note ? " · " + r.note : ""}`).join("
    ") || "—"; +} + +async function recordTrial(conservative) { + resetLog("log-trial", "ثبت در دفتر…"); + const body = { note: el("trial-note").value, add_span: conservative ? -2 : 0 }; + const data = await api("/api/trial/record", { method: "POST", headers: { "Content-Type": "application/json" }, + body: JSON.stringify(body) }); + if (data.error) { logTo("log-trial", "خطا: " + data.error); return; } + logTo("log-trial", `${data.saved} ردیف ثبت شد` + (data.skipped ? ` · ${data.skipped} ردیف تکراری رد شد.` : ".")); + renderTrial(data.trial || {}); +} + +async function markTrial() { + resetLog("log-trial", "خواندن قیمت‌های تازه و بازسنجی…"); + busy("busy-trial", true); + const data = await api("/api/trial/mark", { method: "POST", headers: { "Content-Type": "application/json" }, + body: JSON.stringify({}) }); + busy("busy-trial", false); + if (data.error) { logTo("log-trial", "خطا: " + data.error); return; } + logTo("log-trial", `${data.marked_now} ردیف با قیمت‌های امروز بازسنجی شد.`); + Object.entries(data.now_map || {}).forEach(([sym, v]) => + logTo("log-trial", ` ${sym}: حاشیهٔ امروز ${v.expected_now == null ? "—" : Number(v.expected_now).toFixed(2)} · کف ${v.floor}`)); + logTo("log-trial", "یادآوری: عدد منفی یعنی فرصت بسته شده — این نشانهٔ درست‌کاری موتور است، نه خرابی آن."); + renderTrial(data); +} + +async function verifyChain() { + const data = await api("/api/trial/verify", { method: "POST" }); + logTo("log-trial", (data.ok ? "✅ " : "✗ ") + data.message); + await loadTrial(); +} + +async function makeTrialReport() { + resetLog("log-trial", "ساخت گزارش…"); + const data = await api("/api/trial/report", { method: "POST" }); + if (data.error) { logTo("log-trial", "خطا: " + data.error); return; } + logTo("log-trial", "گزارش ساخته شد: " + data.html); + logTo("log-trial", "پروندهٔ CSV برای دفتر شرکت: " + data.csv); + logTo("log-trial", "این دو پرونده را در بستهٔ تحویل شرکت هم می‌شود گذاشت."); + renderTrial(data); +} + +/* ---------------- آزمون ۱۰ دقیقه‌ای و پروندهٔ سرمایه‌گذار ---------------- */ +async function runSelftest() { + resetLog("log-trial", "اجرای آزمون ۱۰ دقیقه‌ای…"); + busy("busy-exam", true); + const data = await api("/api/selftest", { method: "POST", headers: { "Content-Type": "application/json" }, + body: JSON.stringify({}) }); + busy("busy-exam", false); + if (data.error) { logTo("log-trial", "خطا: " + data.error); return; } + renderSelftest(data); + const s = data.summary || {}; + logTo("log-trial", `نتیجه: ${s.passed} از ${s.total} مورد سبز · موتور ${data.engine ? data.engine.version : "?"} ` + + `(اثر انگشت ${data.engine ? data.engine.sha256 : "?"}) · ${data.duration_ms} میلی‌ثانیه`); + if (!s.ok) logTo("log-trial", "کارنامه سرخ است؛ موردهای سرخ را پیش از نمایش به سرمایه‌گذار حل کنید."); + logTo("log-trial", "کارنامه و برگهٔ آزمون ساخته شد؛ با دکمه‌های بالای همین کارت بازشان کنید."); +} + +function renderSelftest(data) { + const s = data.summary || {}; + const fa = (x) => (x == null ? "—" : String(x)); + el("exam-kpis").innerHTML = [ + ["مورد سبز", `${fa(s.passed)}/${fa(s.total)}`], ["مورد سرخ", fa(s.failed)], + ["زمان اجرا (میلی‌ثانیه)", fa(data.duration_ms)], + ["نسخهٔ موتور ریاضی", data.engine ? data.engine.version : "—"], + ["اثر انگشت موتور", data.engine ? data.engine.sha256 : "—"], + ].map(([k, v]) => `
    ${k}
    ${v}
    `).join(""); + document.querySelector("#exam-table tbody").innerHTML = (data.cases || []).map((c) => { + const detail = (c.rows || []).map((r) => `${r.key}=${r.got}`).join(" · "); + return `` + + `${c.ok ? "✅" : "✗"} ${c.id}
    ${c.title} + ${c.why}${detail} + ${c.ok ? "سبز" : "سرخ"}`; + }).join("") || `آزمون اجرا نشده است.`; +} + +async function buildDossier() { + busy("busy-dossier", true); + const data = await api("/api/dossier", { method: "POST", headers: { "Content-Type": "application/json" }, + body: JSON.stringify({}) }); + busy("busy-dossier", false); + const box = el("dossier-info"); + if (data.error) { box.textContent = "خطا: " + data.error; return; } + const st = (data.summary && data.summary.selftest) || {}; + box.innerHTML = `ساخته شد: ${data.html}
    + آزمون ${st.passed || 0}/${st.total || 0} · زنجیرهٔ دفتر: ${data.summary && data.summary.chain_ok ? "سالم" : "شکسته"} · + کارنامه: ${data.summary && data.summary.scorecard_ready ? "آماده" : "ناتمام"} · + اثر انگشت پرونده: ${data.sha256}
    + نسخهٔ متنی برای ایمیل: ${data.md || ""}`; + logTo("log-trial", "پروندهٔ سرمایه‌گذار ساخته شد: " + data.html); +} + +/* ---------------- گام ۲: امکان‌سنجی مسیرهای داده (پیش از خرید) ---------------- */ +async function probeSources() { + resetLog("log-src", "در حال سنجش مسیرهای داده…"); + busy("busy-src", true); + const body = { symbol: (el("src-symbol").value || "فولاد").trim(), + ws_url: (el("src-ws").value || "").trim(), + fixture: el("src-fixture").checked, timeout: 8 }; + const data = await api("/api/sources/feasibility", { method: "POST", + headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) }); + busy("busy-src", false); + if (data.error) { logTo("log-src", "خطا: " + data.error); return; } + renderSources(data); + const s = data.summary || {}; + logTo("log-src", `${s.ok} از ${s.total} نشانی جواب داد · کد نماد: ${data.code || "—"}`); + logTo("log-src", data.verdict || ""); + if (data.fixture) logTo("log-src", "توجه: این اجرا روی دادهٔ ساختگی محلی بود؛ دربارهٔ سرویس واقعی چیزی نمی‌گوید."); + if (data.ws) logTo("log-src", "پوش لحظه‌ای: " + data.ws.verdict + " — " + data.ws.note); + logTo("log-src", "گزارش ساخته شد: " + data.report); +} + +function renderSources(data) { + const s = data.summary || {}; + const fa = (x) => (x == null ? "—" : String(x)); + el("src-kpis").innerHTML = [ + ["نشانی‌های سالم", `${fa(s.ok)}/${fa(s.total)}`], ["کد نماد", fa(data.code)], + ["نماد", fa(data.symbol)], ["میزبان", data.fixture ? "سرور نمونهٔ محلی (ساختگی)" : fa(data.host)], + ].map(([k, v]) => `
    ${k}
    ${v}
    `).join(""); + const stab = {}; + (data.stability || []).forEach((x) => { stab[x.name] = x.checked ? x.verdict : (x.reason || "—"); }); + document.querySelector("#src-table tbody").innerHTML = (data.items || []).map((i) => ` + ${i.ok ? "✅" : "✗"} ${i.label} + ${i.reason} + ${fa(i.latency_ms)} + ${fa(i.count)}${i.top_keys && i.top_keys.length ? " · " + i.top_keys.join(", ") : ""} + ${stab[i.name] || "—"}`).join("") || + `سنجشی انجام نشده است.`; + const ws = data.ws; + el("src-ws-box").innerHTML = ws + ? `پوش لحظه‌ای: ${ws.verdict} · TCP: ${ws.tcp ? "بله" : "نه"} · TLS: ${ws.tls ? "بله" : "نه"} · + کد پاسخ: ${ws.status || "—"}
    ${ws.note}` + : "نشانی پوش لحظه‌ای وارد نشده است؛ اگر کارگزاری‌تان نشانی داده، اینجا بگذارید تا وضعیت دسترسی‌اش را بگویید."; +} + +async function makeVendorSheet() { + const data = await api("/api/sources/sheet", { method: "POST", + headers: { "Content-Type": "application/json" }, body: JSON.stringify({}) }); + if (data.error) { logTo("log-src", "خطا: " + data.error); return; } + logTo("log-src", "برگهٔ نیاز داده ساخته شد: " + data.path + " — همین را برای فروشنده‌ها بفرستید."); +} + +async function makeWitness() { + const box = el("witness-box"); + resetLog("witness-box", "در حال خواندن قیمت‌ها از سرویس فعال (بدون حافظهٔ نهان)…"); + busy("busy-witness", true); + const data = await api("/api/witness", { method: "POST", + headers: { "Content-Type": "application/json" }, body: JSON.stringify({}) }); + busy("busy-witness", false); + if (data.error) { logTo("witness-box", "خطا: " + data.error); return; } + logTo("witness-box", data.summary); + const faN = (x) => Number(x).toLocaleString("fa-IR"); + logTo("witness-box", `اتصال: ${data.connection} · ${faN(data.probes_ok)} از ${faN(data.probes_total)} قیمت خوانده شد`); + logTo("witness-box", `اثر انگشت برگه: ${data.hash} — همین را با پروندهٔ data/witness-live.json بسنجید.`); + if (data.note) logTo("witness-box", "هشدار صداقت: " + data.note); + if (!data.ready && data.reason) logTo("witness-box", "تصمیم نمونه: " + data.reason); + logTo("witness-box", "برگه: " + data.page + " · نسخهٔ متنی: " + data.md); + logTo("witness-box", "برای نشان‌دادن به سرمایه‌گذار: «نمایش برگه» را بزنید و همان نشانی‌ها را در مرورگر باز کنید."); +} + +function openDemoDoc() { window.open("/files/demo-investor", "_blank"); } + +function openFile(name) { + const map = { method: "method.html", backtest: "backtest.html", exam: "exam", + selftest: "selftest", dossier: "dossier", dossierMd: "dossier-md", + feasibility: "feasibility", requirementSheet: "requirement-sheet", + dataStrategy: "data-strategy" }; + window.open("/files/" + (map[name] || name), "_blank"); +} + +/* ---------------- راه‌اندازی (بازنویسی‌شده) ---------------- */ +/* ---------------- گام ۲: اتصال خودکار ---------------- */ +async function autoConnect(save) { + const box = el("auto-result"); + box.innerHTML = "در حال امتحان منابع رایگان… (هر منبع چند ثانیه)"; + busy("busy-auto", true); + const data = await api("/api/autoconnect", { method: "POST", headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ save: !!save, symbol: "اهرم" }) }); + busy("busy-auto", false); + if (data.error) { box.innerHTML = `خطا: ${data.error}`; return; } + const rows = (data.results || []).map((r) => + `${r.ok ? "✅" : "✗"}${r.label} + ${r.value == null ? "—" : Number(r.value).toLocaleString("fa-IR")} + ${r.json_path || "—"}${r.reason}`).join(""); + box.innerHTML = `${data.summary}
    آزمون در ${data.tested_at} + + ${rows}
    منبعقیمتمسیر JSONنتیجه و دلیل
    `; + (data.results || []).forEach((r) => logTo("log-data", (r.ok ? "✓ " : "✗ ") + r.label + ": " + r.reason)); + logTo("log-data", data.summary); + if (data.saved) { + logTo("log-data", "منبع سالم ذخیره و فعال شد: " + data.saved.label); + if (CONN.profiles) await loadConnections(); + } + if (!data.ok) { + logTo("log-data", "راه جایگزین: «خوراک آزمایشی محلی» برای تمرین، یا پروندهٔ دستی با اعداد کارگزاری."); + } +} + +/* ---------------- گام ۲: اسنپ‌شات دستی ---------------- */ +const SNAP_COLS = [["symbol", "text"], ["kind", "kind"], ["spot", "num"], ["future", "num"], + ["strike", "num"], ["premium", "num"], ["days", "num"], + ["margin_per_contract", "num"], ["liquidity_contracts_per_day", "num"], + ["spread_pct", "num"], ["feed_symbol", "text"]]; +const SNAP_KINDS = [["basis", "پایهٔ نقدی‌آتی"], ["box", "باکس اسپرد"], ["tabei", "تبعی"], + ["covered_call", "پوشش‌داده‌شده"], ["parity", "تساوی پوت‌کال"]]; + +function snapRowHtml(r, i) { + const cells = SNAP_COLS.map(([key, type]) => { + if (type === "kind") { + return ``; + } + const v = r[key] == null ? "" : r[key]; + return ``; + }).join(""); + return `${cells}`; +} + +async function loadSnapRows() { + const data = await api("/api/snapshot/rows"); + if (data.error) { el("snap-status").textContent = "خطا: " + data.error; return; } + const rows = (data.rows || []).length ? data.rows : [{ symbol: "", kind: "basis" }]; + document.querySelector("#snap-table tbody").innerHTML = rows.map(snapRowHtml).join(""); + el("snap-note").value = data.note || ""; + el("snap-status").textContent = (data.exists ? `خوانده شد از ${data.path}` : "پرونده‌ای نبود؛ جدول خالی است") + + (data.last_dated?.length ? ` · آخرین اسنپ‌شات‌های تاریخ‌دار: ${data.last_dated.join("، ")}` : ""); + logTo("log-data", "اعداد فعلی در جدول آمد؛ هر عددی را عوض کنید و «ذخیرهٔ اسنپ‌شات امروز» را بزنید."); +} + +function addSnapRow() { + document.querySelector("#snap-table tbody").insertAdjacentHTML("beforeend", snapRowHtml({ kind: "basis" }, -1)); +} + +function collectSnapRows() { + return [...document.querySelectorAll("#snap-table tbody tr")].map((tr) => { + const row = {}; + tr.querySelectorAll("[data-f]").forEach((input) => { row[input.dataset.f] = input.value.trim(); }); + return row; + }); +} + +async function saveSnapForm() { + const rows = collectSnapRows(); + el("snap-problems").textContent = "در حال ذخیره…"; + const data = await api("/api/snapshot/save", { method: "POST", headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ rows, note: el("snap-note").value, + confirm_real: el("snap-confirm").checked }) }); + if (data.error) { + el("snap-problems").innerHTML = `${data.error}` + (data.problems || []).join(" · "); + return; + } + el("snap-status").textContent = `ذخیره شد: ${data.path} (${data.rows} ردیف)`; + el("snap-problems").innerHTML = (data.problems || []).join("
    ") || "بدون مشکل."; + logTo("log-data", "اسنپ‌شات تاریخ‌دار ذخیره شد: " + data.path); + (data.checklist || []).forEach((c) => logTo("log-data", " · " + c)); + if (data.snapshot) updateBadge(data.snapshot.status, data.snapshot.source_label, data.snapshot.freshness, data.snapshot.rows); +} + +/* ---------- دروازه: چه کسی وارد شده، کارفرما، و کلید خاموشی ---------- */ +let GATE = { enabled: false, role: "admin", id: "—" }; + +async function loadGate() { + try { + const s = await api("/api/gate/status"); + GATE = s || GATE; + const badge = el("whoami"); + if (badge) { + const who = GATE.role === "guest" ? "کارفرما (مهمان)" : "مدیر"; + badge.textContent = GATE.enabled + ? `دروازهٔ ورود: روشن · وارد‌شده: ${who}${GATE.id && GATE.id !== "—" ? " (" + GATE.id + ")" : ""}` + : "دروازهٔ ورود: خاموش (همین رایانه = مدیر)"; + if (GATE.role === "guest") badge.style.background = "#fef3c7", badge.style.color = "#92400e"; + } + const card = el("gate-card"); + if (card) card.style.display = GATE.role === "admin" ? "block" : "none"; + const adminCard = el("card-access"); // کارفرما پنل مدیریت ندارد؛ دکمهٔ بی‌نتیجه هم نمی‌بیند + if (adminCard) adminCard.style.display = GATE.role === "guest" ? "none" : "block"; + gateMeter(); + renderGateUsers(); + } catch (e) { /* اگر وضعیت خوانده نشد، چیزی را قایم نمی‌کنیم */ } +} + +function gateMeter() { + const box = el("gate-state"); + if (!box) return; + const g = GATE.guest || {}; + const users = GATE.users || []; + box.textContent = (GATE.enabled ? "دروازه: روشن" : "دروازه: خاموش") + + ` · مهمان (کارفرما): ` + (g.set ? `${g.id} — ${g.enabled ? "فعال" : "قطع‌شده"}` : "ساخته نشده") + + ` · کاربران تازه: ${users.length ? users.map((u) => u.id + (u.enabled ? "" : " (قطع)")).join("، ") : "هیچ‌کدام"}` + + ` · نشست‌های باز: ${GATE.open_sessions ?? 0}`; +} + +function renderGateUsers() { + const box = el("gate-users"); + if (!box) return; + const users = GATE.users || []; + if (!users.length) { + box.innerHTML = "هیچ کاربر مهمانی ساخته نشده است. بالا شناسه و رمز بنویس و «ساخت کاربر» را بزن."; + return; + } + box.innerHTML = users.map((u) => + `` + + `${u.id} ${u.enabled ? "فعال" : "قطع‌شده"}${u.sessions ? ` · نشست باز: ${u.sessions}` : ""} ` + + `حذف · ` + + `` + + `${u.enabled ? "قطع" : "وصل"}`).join(""); +} + +async function addGateUser() { + const id = (el("new-gate-user").value || "").trim(); + const pass = el("new-gate-pass").value || ""; + const note = (el("new-gate-note").value || "").trim(); + if (!id || !pass) { logTo("log-gate", "شناسه و رمز کاربر تازه را بنویس."); return; } + const res = await api("/api/gate/update", { method: "POST", + body: JSON.stringify({ action: "user-add", id, pass, note }) }); + if (res.error) { logTo("log-gate", "خطا: " + res.error); return; } + logTo("log-gate", res.note); + el("new-gate-pass").value = ""; + GATE.users = res.users; renderGateUsers(); gateMeter(); +} + +async function delGateUser(id) { + if (!confirm(`کاربر «${id}» کامل حذف شود؟ نشست بازش هم همین حالا بسته می‌شود.`)) return; + const res = await api("/api/gate/update", { method: "POST", + body: JSON.stringify({ action: "user-del", id }) }); + if (res.error) { logTo("log-gate", "خطا: " + res.error); return; } + logTo("log-gate", res.note); + GATE.users = res.users; renderGateUsers(); gateMeter(); +} + +async function toggleGateUser(id, enable) { + const res = await api("/api/gate/update", { method: "POST", + body: JSON.stringify({ action: enable ? "user-on" : "user-off", id }) }); + if (res.error) { logTo("log-gate", "خطا: " + res.error); return; } + logTo("log-gate", res.note); + GATE.users = res.users; renderGateUsers(); gateMeter(); +} + +async function gateAction(action) { + logTo("log-gate", "در حال اجرا: " + action); + const res = await api("/api/gate/update", { method: "POST", + body: JSON.stringify({ action }) }); + if (res.error) { logTo("log-gate", "خطا: " + res.error); return; } + if (res.users) { GATE.users = res.users; renderGateUsers(); } + logTo("log-gate", res.note + (res.guest ? ` · مهمان: ${res.guest.set ? res.guest.id : "—"} ${res.guest.enabled ? "(فعال)" : "(قطع)"}` : "")); + GATE.enabled = res.enabled; GATE.guest = res.guest; + gateMeter(); +} + +async function saveGuest() { + const id = (el("guest-id").value || "").trim(); + const pass = el("guest-pass").value || ""; + if (!id || !pass) { logTo("log-gate", "شناسه و رمز مهمان را بنویسید."); return; } + logTo("log-gate", "در حال ذخیرهٔ رمز مهمان…"); + const res = await api("/api/gate/update", { method: "POST", + body: JSON.stringify({ action: "set-guest", id, pass }) }); + if (res.error) { logTo("log-gate", "خطا: " + res.error); return; } + logTo("log-gate", res.note + " · کارفرما با همین شناسه وارد می‌شود؛ رمز را خودش می‌داند."); + el("guest-pass").value = ""; + GATE.guest = res.guest; gateMeter(); +} + +async function shutdownApp() { + if (!confirm("برنامه همین حالا خاموش شود؟ کارفرما هم بیرون می‌افتد.")) return; + const res = await api("/api/shutdown", { method: "POST", body: JSON.stringify({ confirm: true }) }); + if (res.error) { logTo("log-gate", "خطا: " + res.error); return; } + logTo("log-gate", res.note); + document.body.innerHTML = '
    ' + + "

    برنامه خاموش شد.

    برای روشن‌کردن دوباره، همان میان‌بر/فرمان همیشگی را بزنید.

    "; +} + +async function logoutApp() { + await api("/api/logout", { method: "POST", body: "{}" }); + location.href = "/login"; +} + +async function boot() { + buildNav(); // نوار گام‌ها اول، تا صفحه حتی بدون شبکه شکل داشته باشد + await loadGate(); + await loadGuide(); + await pickMode(); + await loadConnections(); // دفتر اتصال + پروفایل فعال ذخیره‌شده + await loadSnapRows(); // جدول اعداد کارگزاری + await loadRules(); + await loadTrial(); + await prospectLoad(); // تابلوی پیگیری مخاطبان (گام ۸) + showStep(0); +} + +document.addEventListener("DOMContentLoaded", boot); + +/* ---------------- گام ۱۰: آزمون کور سرمایه‌گذار ---------------- */ +let CASES_CACHE = []; + +async function loadCases() { + busy("busy-blind", true); + const data = await api("/api/investor/cases", { method: "POST", + headers: { "Content-Type": "application/json" }, body: JSON.stringify({}) }); + busy("busy-blind", false); + if (data.error) { logTo("log-blind", "خطا: " + data.error); return; } + CASES_CACHE = data.cases || []; + el("blind-list").innerHTML = CASES_CACHE.map((c) => ` +
    + ${c.title} +
    ${c.question}
    + ${c.given.map(([k, v]) => ``).join("")}
    ${k}${v}
    +
    + حدس شما (${c.unit}): + +
    +
    +
    `).join(""); + logTo("log-blind", "شش پرسش نمایش داده شد. حدس‌های خودتان را بنویسید، بعد «داوری حدس‌های من» را بزنید."); +} + +async function checkGuesses() { + if (!CASES_CACHE.length) { await loadCases(); } + busy("busy-blind", true); + let done = 0; + for (const c of CASES_CACHE) { + const box = el("guess-" + c.id); + const guess = box ? box.value.trim() : ""; + if (!guess) { continue; } + const res = await api("/api/investor/check", { method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ id: c.id, guess }) }); + const t = el("res-" + c.id); + if (res.error || !res.ok) { t.innerHTML = `${res.error || res.detail}`; continue; } + done++; + const off = (res.off_pct == null) ? "" : ` · فاصله ${res.off_pct}٪`; + t.innerHTML = `
    پاسخ برنامه: ${res.answer} ${res.unit || ""} + · داوری: ${res.verdict}${off}
    +
    فرمول: ${res.formula}
    +
    روش دوم (برای بازبینی با ماشین‌حساب): ${res.second || "—"}
    +
    ${res.note || ""}
    `; + } + busy("busy-blind", false); + logTo("log-blind", done ? `${done} پرسش داوری شد و در دفتر زنجیره‌هش‌دار ثبت شد.` : + "هیچ حدسی نوشته نشده بود؛ اول حدس‌ها را بنویسید."); +} + +async function loadLadder() { + const data = await api("/api/investor/ladder", { method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ client: (el("blind-client") ? el("blind-client").value.trim() : "") }) }); + if (data.error) { el("ladder-box").textContent = "خطا: " + data.error; return; } + const doc = data.doc || {}; + const docLine = doc.counts && doc.counts.checked + ? `
    سند پلهٔ تصمیم: ${doc.counts.checked} ردیف بررسی شد · ` + + `${doc.counts.actionable} ردیف قابل اجرا · ${doc.counts.no_action} ردیف بدون اقدام` + + (doc.titles && doc.titles.length ? ` · فهرست: ${doc.titles.join("، ")}` : "") + + ` · نقطهٔ برگشت هر ردیف در سند نوشته شده است.` + + (doc.verify && doc.verify.ok === false ? " ⚠️ زنجیرهٔ دفتر شکسته است." : "") + "
    " + : ""; + const hs = data.ladder.hurdles; + const head = `راهبردبازده سالانه${hs.map((h) => `سد ${h}٪`).join("")}`; + const rows = data.ladder.rows.map((t) => `${t.name} + ${t.annualized_pct == null ? "—" : t.annualized_pct + "٪"} + ${hs.map((h) => `${t.cells[h].go ? "می‌گذرد" : "می‌افتد"}`).join("")}`).join(""); + const sz = data.sizing.map((x) => `${x.risk_pct}٪${x.contracts} + ${x.margin_locked.toLocaleString("fa-IR")}${x.free_cash.toLocaleString("fa-IR")}`).join(""); + el("ladder-box").innerHTML = `${head}${rows}
    +
    ${data.ladder.verdict}
    +

    اندازهٔ موقعیت: ۱۰۰ میلیون تومان، وجه تضمین ۲ میلیون

    + ${sz}
    سقف ریسکقراردادوجه تضمین درگیرنقد آزاد
    ` + + docLine; +} + +async function makePledge() { + busy("busy-blind", true); + const data = await api("/api/investor/pledge", { method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ client: (el("blind-client") ? el("blind-client").value.trim() : "") }) }); + busy("busy-blind", false); + if (data.error) { logTo("log-blind", "خطا: " + data.error); return; } + logTo("log-blind", `پیمان‌نامهٔ نمایش ساخته شد (${data.chars} نویسه): ${data.path}`); + logTo("log-blind", `زنجیره: ${data.verify.ok ? "سالم" : "شکسته"} ` + + `· ${data.verify.rows} ردیف · ${data.verify.detail}`); + logTo("log-blind", "پیمان‌نامه می‌گوید چه چیزی اثبات می‌شود و چه چیزی نه؛ همان را قبل از نمایش بخوانید."); +} + +async function doReconcile() { + resetLog("log-rec", "در حال حساب…"); + busy("busy-rec", true); + const body = { symbol: el("rec-symbol").value.trim(), entry: el("rec-entry").value.trim(), + exit: el("rec-exit").value.trim(), days: el("rec-days").value.trim(), + units: el("rec-units").value.trim(), expected: el("rec-expected").value.trim() }; + const data = await api("/api/investor/reconcile", { method: "POST", + headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) }); + busy("busy-rec", false); + if (data.error) { logTo("log-rec", "خطا: " + data.error); return; } + logTo("log-rec", `${data.symbol}: هزینهٔ کل ${data.cost.toLocaleString("fa-IR")} · ` + + `دریافتی خالص ${data.proceeds.toLocaleString("fa-IR")} · سود/زیان ${data.profit.toLocaleString("fa-IR")}`); + logTo("log-rec", `بازده دوره ${data.period_pct}٪ · سالانه ${data.annualized_pct}٪ → ${data.verdict}`); + if (data.compare && data.compare !== "—") { logTo("log-rec", data.compare); } + logTo("log-rec", data.note); + logTo("log-rec", `زنجیره: ${data.chain.ok ? "سالم" : "شکسته"} · کلید آخر ${data.chain.last_fingerprint}`); +} + +async function buildBlindSheet() { + const data = await api("/api/investor/sheet", { method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ client: (el("blind-client") ? el("blind-client").value.trim() : "") }) }); + if (data.error) { logTo("log-blind", "خطا: " + data.error); return; } + logTo("log-blind", "برگهٔ آزمون ساخته شد: " + data.html); + logTo("log-blind", "نسخهٔ متنی: " + data.md); + const ch = data.scorecard ? data.scorecard.verify : data.chain; + logTo("log-blind", `زنجیره: ${ch.ok ? "سالم" : "شکسته"} · ${ch.rows} ردیف · کلید ${ch.last_fingerprint}`); + if (data.scorecard && data.scorecard.scored) { + logTo("log-blind", `${data.scorecard.scored} پرسش سنجیده شد و ${data.scorecard.near} پاسخ ` + + `نزدیک یا درست بود (${data.scorecard.fair_pp}٪). این عدد دربارهٔ شهود است، نه سود.`); + } +} + +async function verifyBlindChain() { + const data = await api("/api/investor/verify", { method: "POST", + headers: { "Content-Type": "application/json" }, body: JSON.stringify({}) }); + logTo("log-blind", `زنجیره: ${data.ok ? "سالم" : "شکسته"} · ردیف ${data.rows} · ${data.detail}`); +} + +/* ---------------- داوری سیگنال ابزارهای دیگر ---------------- */ +const JUDGE_PRESETS = { + basis: '{"spot":20000,"future":22800,"days":50,"spread_pct":0.005,"liquidity_contracts_per_day":900}', + covered: '{"spot":7000,"strike":7400,"premium":120,"days":30}', + tabei: '{"stock_price":50000,"put_price":200,"strike":62500,"days":90}', + box: '{"call_low":300,"put_low":420,"call_high":180,"put_high":560,"strike_low":1200,"strike_high":1500,"days":45}', + parity: '{"call":420,"put":380,"spot":9000,"strike":9000,"days":30}', +}; + +function judgePreset() { + const k = el("judge-kind").value; + el("judge-params").value = JUDGE_PRESETS[k] || "{}"; + el("judge-margin").value = el("judge-margin").value || "2000000"; + el("judge-contracts").value = el("judge-contracts").value || "10"; + el("judge-price").value = el("judge-price").value || (k === "basis" ? "20000" : "7000"); + logTo("log-judge", "نمونهٔ آماده برای «" + k + "» گذاشته شد؛ «داوری کن» را بزنید."); +} + +async function judgeSignal(sheet) { + busy("busy-judge", true); + let params = {}; + try { params = JSON.parse(el("judge-params").value || "{}"); } + catch (e) { busy("busy-judge", false); logTo("log-judge", "عددهای ورودی JSON درست نیستند."); return; } + const body = { kind: el("judge-kind").value, params, sheet: !!sheet, + hurdle: el("judge-hurdle").value ? Number(el("judge-hurdle").value) / 100 : null, + claimed: el("judge-claimed").value || null, + margin: el("judge-margin").value || null, + contracts: el("judge-contracts").value || null, + price: el("judge-price").value || null }; + const data = await api("/api/judge", { method: "POST", + headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) }); + busy("busy-judge", false); + if (data.error || !data.ok) { logTo("log-judge", "خطا: " + (data.error || data.detail)); return; } + const ann = data.annualized_pct == null ? "—" : data.annualized_pct + "٪"; + el("judge-kpis").innerHTML = [ + ["داوری", data.verdict], ["بازده سالانهٔ خالص", ann], + ["حاشیه بر نرخ سد", (data.edge_pp == null ? "—" : data.edge_pp + " واحد")], + ["فاصله تا مارجین‌کال", (data.margin && data.margin.ok ? data.margin.move_pct + "٪" : "—")], + ["اثر انگشت", data.fingerprint], + ].map(([k, v]) => `
    ${k}
    ${v}
    `).join(""); + (data.gates || []).forEach((g) => logTo("log-judge", (g.ok ? "✓ " : "✗ ") + g.gate + ": " + g.detail)); + if (data.break_even && data.break_even.value != null) { + logTo("log-judge", "نقطهٔ برگشت — " + data.break_even.label + ": " + data.break_even.value); + } else if (data.break_even) { logTo("log-judge", data.break_even.note); } + if (data.margin && data.margin.ok) { + logTo("log-judge", "مارجین‌کال: " + data.margin.formula + + (data.margin.price_note ? " " + data.margin.price_note : "")); + } else if (data.margin) { logTo("log-judge", data.margin.detail); } + logTo("log-judge", `دو روش حساب: موتور ${data.annualized_pct}٪ · دستی ${data.hand.annualized_pct}٪ (اختلاف ${data.hand_diff_pp} واحد)`); + if (data.claim_note) logTo("log-judge", data.claim_note); + if (data.sheet_html) logTo("log-judge", "برگهٔ داوری ساخته شد: " + data.sheet_html); + logTo("log-judge", "حالا می‌توانید همین برگه را به شرکت یا سرمایه‌گذار بدهید."); +} + +/* ---------------- مجوز دسترسی، پشتیبانی و عیب‌یابی ---------------- */ + + + +/* ---------------- چسباندن اعداد کارگزاری و تشخیص خودکار ---------------- */ +async function importPaste() { + const text = (el("snap-paste").value || "").trim(); + if (!text) { logTo("paste-report", "کادر خالی است؛ متن را از سامانهٔ کارگزاری بچسبانید."); return; } + logTo("paste-report", "در حال خواندن متن…"); + const d = await api("/api/snapshot/import", { + method: "POST", headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ text, toman: el("paste-toman").checked }), + }); + if (d.error) { logTo("paste-report", "خطا: " + d.error); return; } + const tbody = document.querySelector("#snap-table tbody"); + const before = tbody.querySelectorAll("tr").length; + (d.rows || []).forEach((r, i) => tbody.insertAdjacentHTML("beforeend", snapRowHtml(r, before + i))); + logTo("paste-report", `${d.count} ردیف خوانده و به جدول اضافه شد (جمع: ${tbody.querySelectorAll("tr").length}).`); + (d.hints || []).slice(0, 8).forEach((h) => logTo("paste-report", "· " + h)); + (d.problems || []).forEach((p) => logTo("paste-report", "✗ " + p)); + if (!d.count) logTo("paste-report", "هیچ ردیفی خوانده نشد؛ راهنمای ستون‌ها را ببینید."); + el("snap-status").textContent = "ردیف‌های تازه اضافه شدند؛ عددها را بازبینی کنید و بعد «ذخیرهٔ اسنپ‌شات امروز» را بزنید."; +} + +/* ---------------- گواهی استفادهٔ موفق ---------------- */ + + +/* ---------------- تابلوی پیگیری مخاطبان (گام ۸) ---------------- */ + +function prospectPayload(extra) { + return Object.assign({ + name: (el("prospect-name").value || "").trim(), + kind: el("prospect-kind").value, + channel: el("prospect-channel").value, + date: (el("prospect-date").value || "").trim(), + }, extra || {}); +} + +function paintProspects(res) { + const wk = res.week || {}; + const todo = res.todo || []; + const kpi = el("prospect-kpis"); + if (kpi) { + kpi.innerHTML = + `
    ${wk.messages ?? 0}پیام این هفته (هدف ${wk.targets?.messages ?? 5})
    ` + + `
    ${wk.calls ?? 0}تماس (هدف ${wk.targets?.calls ?? 1})
    ` + + `
    ${wk.meetings ?? 0}جلسه (هدف ${wk.targets?.meetings ?? 1})
    ` + + `
    ${todo.length}کار امروز
    `; + } + if (todo.length) { + todo.forEach((t) => logTo("log-prospects", + `→ ${t.name}: ${t.action}${t.urgent ? " ⚡" : ""} — ${t.why}`)); + } else { + logTo("log-prospects", "امروز کاری در نوبت نیست."); + } +} + +async function prospectCall(payload, okMsg) { + const res = await api("/api/prospects", { method: "POST", body: JSON.stringify(payload) }); + if (res.error) { logTo("log-prospects", "خطا: " + res.error); return null; } + logTo("log-prospects", okMsg); + paintProspects(res); + return res; +} + +async function prospectAdd() { + const p = prospectPayload({ action: "add", note: "" }); + if (!p.name) { logTo("log-prospects", "اول نام مخاطب را بنویسید."); return; } + const res = await prospectCall(p, `«${p.name}» به تابلو اضافه شد.`); + if (res) { el("prospect-name").value = ""; } +} + +async function prospectMark(event) { + const p = prospectPayload({ action: event }); + if (!p.name) { logTo("log-prospects", "نام مخاطب را بنویسید."); return; } + const labels = { sent: "پیام اول ثبت شد", followup: "پیگیری ثبت شد", + reply: "جواب ثبت شد", meeting: "جلسه ثبت شد" }; + await prospectCall(p, `${labels[event] || event}: ${p.name}`); +} + +async function prospectOutcome() { + const p = prospectPayload({ action: "outcome", result: el("prospect-result").value }); + if (!p.name) { logTo("log-prospects", "نام مخاطب را بنویسید."); return; } + await prospectCall(p, `نتیجهٔ جلسه ثبت شد (${p.result}): ${p.name}`); +} + +async function prospectClose() { + const p = prospectPayload({ action: "close" }); + if (!p.name) { logTo("log-prospects", "نام مخاطب را بنویسید."); return; } + await prospectCall(p, `پروندهٔ «${p.name}» بسته شد.`); +} + +async function prospectSheet() { + const res = await api("/api/prospects", { method: "POST", body: JSON.stringify({ action: "sheet" }) }); + if (res.error) { logTo("log-prospects", "خطا: " + res.error); return; } + logTo("log-prospects", `برگهٔ تابلو ساخته شد: ${res.html}`); + logTo("log-prospects", `نسخهٔ متنی: ${res.md}`); + paintProspects(res); +} + +async function prospectLoad() { + const res = await api("/api/prospects", { method: "POST", body: JSON.stringify({ action: "list" }) }); + if (res.error) return; + paintProspects(res); +} + +async function buildOutreach() { + const client = (el("offer-client").value || "").trim(); + const kind = el("outreach-kind").value || "company"; + logTo("log-bundle", "در حال ساخت پیام‌های معرفی…"); + const res = await api("/api/outreach", { method: "POST", body: JSON.stringify({ client, kind }) }); + if (res.error) { logTo("log-bundle", "خطا: " + res.error); return; } + logTo("log-bundle", `پیام‌ها ساخته شد (${res.kind_label}): ${res.md}`); + logTo("log-bundle", "چهار متن آماده: پیام اول، پیام بعد از جواب، تأیید وقت، و پیگیری " + + "— به‌همراه اسکریپت تماس و پاسخ چهار مخالفت. هدف پیام اول فقط نیم‌ساعت وقت است."); + logTo("log-bundle", "قاعده: پیگیری فقط سه بار (روز ۰، ۳، ۱۰) و هیچ عدد سودی در هیچ پیامی نیست."); +} + +async function buildReviewMeeting() { + const client = (el("offer-client").value || "").trim(); + const start = (el("onboard-start").value || "").trim(); + const on = (el("review-on").value || "").trim(); + logTo("log-bundle", "در حال ساخت برگهٔ جلسهٔ بازبینی…"); + const res = await api("/api/review-meeting", { method: "POST", + body: JSON.stringify({ client, start, on }) }); + if (res.error) { logTo("log-bundle", "خطا: " + res.error); return; } + logTo("log-bundle", `برگهٔ جلسهٔ بازبینی ساخته شد: ${res.html}`); + logTo("log-bundle", `روز بازبینی: ${res.review} — ${res.status}`); + logTo("log-bundle", `نسخهٔ متنی: ${res.md}`); + logTo("log-bundle", "روی برگه: سه شاهد، پنج شرط کارنامه، دو خروجی (ادامه با پرداخت / توقف) و پیگیری تاریخ‌دار."); + if (!res.price_given) logTo("log-bundle", "قیمت روی برگه «توافقی» است؛ عدد در جلسه گذاشته می‌شود."); +} + +async function buildSalesRitual() { + const sender = (el("ritual-sender").value || "").trim() || "مسعود"; + const on = (el("ritual-on").value || "").trim(); + resetLog("log-ritual", "در حال خواندن تابلو و چیدن کار امروز…"); + const res = await api("/api/sales-ritual", { method: "POST", body: JSON.stringify({ sender, on }) }); + if (res.error) { logTo("log-ritual", "خطا: " + res.error); return; } + const c = res.counts || {}; + const faN = (x) => Number(x || 0).toLocaleString("fa-IR"); // رقم فارسی، مثل بقیهٔ صفحه + logTo("log-ritual", `${res.date} · ${faN(res.used_minutes)} از ${faN(res.budget)} دقیقه — ` + + `${faN(c.messages)} پیام · ${faN(c.calls)} تماس · ${faN(c.internal)} کار دفتری`); + (res.items || []).forEach((i) => logTo("log-ritual", + `→ ${i.name} (${i.channel_label}): ${i.action}`)); + (res.deferred || []).forEach((d) => logTo("log-ritual", `↷ فردا: ${d.name} — ${d.reason}`)); + logTo("log-ritual", res.note); + logTo("log-ritual", `برگهٔ امروز ساخته شد: ${res.html} · نسخهٔ متنی: ${res.md}`); +} + +async function buildOnboarding() { + const client = (el("offer-client").value || "").trim(); + const start = (el("onboard-start").value || "").trim(); + logTo("log-bundle", "در حال ساخت برگهٔ روز اول مشتری…"); + const res = await api("/api/onboarding", { method: "POST", + body: JSON.stringify({ client, start }) }); + if (res.error) { logTo("log-bundle", "خطا: " + res.error); return; } + logTo("log-bundle", `برگهٔ روز اول ساخته شد: ${res.html}`); + logTo("log-bundle", `نسخهٔ متنی: ${res.md}`); + logTo("log-bundle", `آزمون ${res.trial_days} روزه · روز بازبینی: ${res.review} — ` + + "پنج کار روز اول، دو هفته بدون خرید، و شرط‌های کارنامه روی برگه است."); + if (!res.price_given) logTo("log-bundle", "قیمت روی برگه «توافقی» است؛ عدد در جلسه گذاشته می‌شود."); +} + +async function buildOffer() { + const client = (el("offer-client").value || "").trim(); + logTo("log-bundle", "در حال ساخت پیشنهاد یک‌صفحه‌ای…"); + const res = await api("/api/offer", { method: "POST", body: JSON.stringify({ client }) }); + if (res.error) { logTo("log-bundle", "خطا: " + res.error); return; } + logTo("log-bundle", `پیشنهاد ساخته شد: ${res.html}`); + logTo("log-bundle", `نسخهٔ متنی برای ایمیل/واتساپ: ${res.md}`); + if (!res.price_given) { + logTo("log-bundle", "قیمت روی برگه «توافقی» نوشته شد؛ عدد را در جلسه بگذارید (یا با مبلغ بسازید)."); + } + if (res.kit && res.kit.files) { + logTo("log-bundle", `روی برگه نوشته شد: بستهٔ ${res.kit.files} پرونده‌ای آمادهٔ تحویل.`); + } +} + +function openAdminPanel() { + window.open("/admin", "_blank", "noopener"); +} +window.openAdminPanel = openAdminPanel; +window.buildOffer = buildOffer; +window.buildOnboarding = buildOnboarding; +window.buildSalesRitual = buildSalesRitual; +window.gateAction = gateAction; +window.addGateUser = addGateUser; +window.delGateUser = delGateUser; +window.toggleGateUser = toggleGateUser; +window.saveGuest = saveGuest; +window.shutdownApp = shutdownApp; +window.logoutApp = logoutApp; +window.loadGate = loadGate; +window.buildReviewMeeting = buildReviewMeeting; +window.buildOutreach = buildOutreach; +window.prospectAdd = prospectAdd; +window.prospectMark = prospectMark; +window.prospectOutcome = prospectOutcome; +window.prospectClose = prospectClose; +window.prospectSheet = prospectSheet; +window.prospectLoad = prospectLoad; + diff --git a/station/web/guide.html b/station/web/guide.html new file mode 100644 index 0000000000000000000000000000000000000000..bf34ab0b4a7fed495a584871f8cfa538b7d88339 --- /dev/null +++ b/station/web/guide.html @@ -0,0 +1,240 @@ + + + + + +راهنمای کارفرما — ایستگاه تصمیم + + + +
    +

    راهنمای کارفرما — ایستگاه تصمیم

    +

    هر چیزی که برای کار کردن با این برنامه لازم داری، همین‌جا نوشته شده. اگر جایی گیر کردی، بخش «اگر این پیام را دیدی» یا «پرسش‌های پرتکرار» را ببین.

    +
    + +
    + + + +
    +

    ۱) این برنامه برای تو چه می‌کند

    +

    این برنامه به تو یک تصمیم روشن می‌دهد: بخری، بفروشی، نگه داری، یا دست نزنی — همراه با + عدد ورود، عدد خروج، حد ضرر، و اندازهٔ معامله نسبت به پولت.

    +

    هر تصمیم با شاهد ثبت می‌شود: دفتری که ردیف‌هایش تغییرپذیر نیستند و می‌توانی هر لحظه + درستی‌اش را بسنجی. یعنی بعداً کسی نمی‌تواند بگوید «این عدد را خودت دستی نوشتی».

    +

    سفارش نمی‌فرستد و هیچ‌چیز را خودش نمی‌خرد و نمی‌فروشد. تصمیم را تو می‌گیری و اجرا می‌کنی؛ + این عمدی است، چون در ایران کارگزاری‌ها سفارش خودکار را اجازه نمی‌دهند.

    +
    + دقت کن: هیچ‌جای این برنامه وعدهٔ سود نمی‌دهد و سرمایه‌گذاری هم توصیه نمی‌کند. + آن‌چه می‌گیری، عدد و دلیل روشن است تا تصمیم تو روی هوا نباشد. +
    +
    + +
    +

    ۲) امروز چه چیزی به دستت می‌آید

    + + + + + + + + +
    خروجیبه چه کاری می‌آید
    برگهٔ تصمیمروی هر معامله: چه‌کار کنی، کجا بیرون بروی، چند واحد بگیری، حد ضررت کجاست.
    صفحهٔ روش کاربا زبان ساده می‌گوید هر عدد از کجا آمده و چرا.
    دفتر شاهدتاریخ همهٔ کارها، با اثر انگشت؛ برای نشان دادن به مدیرعامل یا حسابرس.
    کارنامهٔ آماده‌بودنپنج شرط ساده؛ تا سبز نشوند، برنامهٔ زنده جدی گرفته نمی‌شود.
    برگهٔ جلسهٔ بازبینیروز چهاردهم: چه چیزی دیدیم، چه نتیجه‌ای گرفتیم، ادامه می‌دهیم یا نه.
    گواهی استفادهیک صفحه که نشان می‌دهد شرکت چقدر و کجا از برنامه استفاده کرده.
    +

    همهٔ این‌ها روی همین رایانه ساخته می‌شوند و می‌توانی چاپشان کنی یا به‌صورت پرونده نگه داری.

    +
    + +
    +

    ۳) روز اول تو — پنج کار، بدون فوت وقت

    +
    کار ۱. در گام ۱ برنامه، پول و شرایطت را بنویس (چقدر سرمایه، چه بخشی از آن را + می‌خواهی درگیر کنی).
    +
    کار ۲. گام ۳ را بزن و ببین برنامه راه‌های داده را می‌شناسد و یکی را انتخاب + می‌کند. اگر چیزی نمی‌خواهی بخری، «خوراک آزمایشی» کافی است؛ هزینه‌اش صفر است.
    +
    کار ۳. یک تصمیم نمونه بگیر و برگهٔ تصمیم را باز کن و بخوان.
    +
    کار ۴. یک‌بار «آزمون» را بزن تا خودت ببینی محاسبه‌ها درست درمی‌آیند.
    +
    کار ۵. امشب هیچ‌چیز نخر. روز اول فقط آشنایی است.
    +
    هیچ‌چیز لازم نیست بخری. نه اشتراک، نه سرویس، نه ابزار. اگر جایی از تو پول + خواست، اول از پشتیبانی بپرس (بخش ۱۱).
    +
    + +
    +

    ۴) هر روز، شصت ثانیه

    +

    هر روز فقط یک کار: دکمهٔ «کار امروز» را بزن و ده عددی که برنامه می‌خواهد را از تابلوی + کارگزاری خودت بردار و پر کن. کل کار، شصت ثانیه است.

    +
    +
    عددهایی که وارد می‌کنی: قیمت خرید و فروش هر نماد، تعداد خرید و فروش، مبلغ آخرین + تسویه، و وجه تضمین. همهٔ این‌ها در تابلوی کارگزاری خودت پیدا می‌شود.
    +
    عددهایی که باید نگیری: «پیش‌بینی» یا «نظر» هیچ‌کس. برنامه از عدد واقعی کار می‌کند، + نه از حدس.
    +
    +

    بعد از زدن دکمه، برنامه سراغ دفترش می‌رود و کارنامهٔ همان روز را به‌روز می‌کند. اگر روزی را از + دست دادی، اشکالی ندارد؛ تعداد روزهای فعال را خودش می‌شمارد.

    +
    + ریتم درست: هر روز، سر یک ساعت مشخص (مثلاً پیش از باز شدن بازار). روزهایی که «دست نزن» + می‌گوید هم ارزش دارند و شمرده می‌شوند. +
    +
    + +
    +

    ۵) چه تصمیمی می‌گیری

    + + + + + + + +
    برنامه می‌گویدیعنیکار تو
    بخرشرایط ورود جور است و اندازهٔ معامله هم گفته شده.با همان عدد و همان اندازه سفارش بده (خودت، در کارگزاری).
    نگه دارمعاملهٔ قبلی هنوز در محدودهٔ درست است.کاری نکن؛ حد ضرر را جابه‌جا نکن.
    بفروشبه حد سود یا حد ضرر رسیده، یا شرط ادامه از بین رفته.همان‌جا بیرون بیا و در برنامه ثبت کن.
    دست نزنهیچ شرطی جور نیست؛ بازار برای تو خرید نیست.هیچ کاری نکن. این هم یک تصمیم است، نه بی‌توجهی.
    +

    اگر برنامه گفت «دست نزن» و تو وارد شدی، دفتر شاهد این را ثبت می‌کند و روز بازبینی معلوم می‌شود. + همین که این‌جا صادق باشی، ارزش کل کار بالا می‌رود.

    +
    + +
    +

    ۶) دو هفته بعد چه می‌شود

    +

    دو هفته (چهارده روز کاری) کار روزانه، یک چیز می‌سازد که به آن می‌گوییم کارنامهٔ آماده‌بودن. + این کارنامه پنج شرط ساده دارد و همه‌شان از کارهای خودِ تو درمی‌آید، نه از حرف ما:

    +
      +
    1. روزهای فعال به حد لازم رسیده باشد (یعنی واقعاً روزها را کار کرده باشی).
    2. +
    3. دفتر شاهد سالم و بی‌دستکاری باشد (خودش این را می‌سنجد و یک عدد نشان می‌دهد).
    4. +
    5. تصمیم‌های ثبت‌شده کافی باشند.
    6. +
    7. آزمون‌ها سبز باشند (همان دکمهٔ آزمون روز اول).
    8. +
    9. خروجی‌های چاپی ساخته شده باشند.
    10. +
    +

    روز چهاردهم، برنامه برگهٔ جلسهٔ بازبینی می‌سازد: بیست دقیقه گفت‌وگو، سه شاهد که خودت + اجرا می‌کنی، و در پایان دو راه روشن:

    +
    ادامه: اگر کارنامه سبز است و می‌خواهی ادامه دهی، پرداخت در برابر همان + برگه‌ها انجام می‌شود.
    +
    توقف: اگر سبز نشد یا نخواستی، همان‌جا تمام؛ هیچ آلودگی و هیچ بهانه‌ای + نیست. یک تمدید چهارده‌روزهٔ بی‌هزینه هم یک‌بار هست.
    +

    هیچ‌کس تو را برای تصمیم‌گرفتن تحت فشار نمی‌گذارد. اگر عددها آماده نبودند، پیگیری + تاریخ‌دار می‌شود و بعد ساکت می‌مانیم.

    +
    + +
    +

    ۷) اگر این پیام را دیدی

    + + + + + + + + + + + + +
    پیامیعنی چهکار درست
    «شناسه یا رمز درست نیست»حرف یا رقم را اشتباه زده‌ای.دوباره وارد شو. پنج بار پشت‌سرهم اشتباه، ورود را چند دقیقه می‌بندد؛ چند دقیقه صبر کن.
    «این بخش فقط با حساب مدیر باز می‌شود»این قسمت مخصوص مدیر است، نه تو.کاری لازم نیست؛ همان صفحهٔ قبل را ادامه بده.
    «برای دیدن برنامه اول وارد شوید»نشست تو بسته شده (هشت ساعت بعد از آخرین کار).یک بار دیگر وارد شو.
    «پرونده ساخته نشده است»آن خروجی هنوز درست نشده، چون گام‌های قبلی کامل نشده.گام‌ها را به ترتیب ۱ تا ۸ برو و آن بخش را دوباره بساز.
    «عدد را بخوان و درست وارد کن»جای عدد، حرف یا فاصلهٔ اضافه گذاشته‌ای.عدد را بدون کاما و بدون حرف وارد کن (یا مستقیم از کارگزاری بچسبان).
    «داده کهنه است»تابلویی که پرش کرده‌ای امروز به‌روز نشده.تابلوی روز جاری کارگزاری را پر کن.
    «شرط‌های ورود جور نیست»برنامه عمداً چیزی برای خرید پیشنهاد نمی‌کند.همان «دست نزن» را ثبت کن؛ فردا دوباره نگاه کن.
    «دفتر شاهد سالم نیست»ردیفی در دفتر تغییر کرده یا پرونده جابه‌جا شده.به پشتیبانی بگو؛ این پیام برای اطمینان توست، نه برای پنهان‌کاری.
    «برنامه خاموش می‌شود»مدیر (صاحب برنامه) دکمهٔ خاموشی را زده.دوباره از مدیر بخواه روشن کند؛ کارهای ثبت‌شده هم می‌مانند.
    صفحه سفید یا باز نمی‌شوداتصال یا آدرس مشکل دارد.یک بار صفحه را نو کن؛ اگر نشد، آدرس را دوباره از مدیر بگیر.
    +
    + +
    +

    ۸) پرسش‌های پرتکرار (بیست پرسش)

    +
    ۱. آیا این برنامه خودش معامله می‌کند؟

    نه. تصمیم و عدد را می‌دهد؛ سفارش را خودت در کارگزاری می‌زنی.

    +
    ۲. باید چیزی بخرم یا اشتراک بگیرم؟

    نه. هیچ‌چیز لازم نیست بخری. منبع دادهٔ رایگان و «خوراک آزمایشی» کافی است.

    +
    ۳. چقدر سود می‌دهد؟

    هیچ‌کس نمی‌تواند عدد سود را از پیش بگوید و ما هم وعده نمی‌دهیم. کاری که می‌کنیم: تصمیم روشن، اندازهٔ درست، و شاهد.

    +
    ۴. چقدر وقت می‌گیرد؟

    هر روز شصت ثانیه. روز چهاردهم یک جلسهٔ بیست‌دقیقه‌ای.

    +
    ۵. باید برنامه‌نویس یا کارشناس ریاضی داشته باشم؟

    نه. همه‌چیز آماده است و همین راهنما کافی است.

    +
    ۶.اگر پولم کم باشد؟

    عدد و اندازهٔ معامله نسبت به همان پول حساب می‌شود. «دست نزن» بیشتر می‌شود؛ همین.

    +
    ۷. عددها از کجا می‌آید؟

    از تابلوی کارگزاری خودت و منابع رایگان عمومی. برنامه هیچ عدد دلخواهی از خودش نمی‌سازد.

    +
    ۸. اگر یک روز را از دست بدهم؟

    اشکالی ندارد؛ روزهای فعال شمرده می‌شوند و مسیر دو هفته‌ای فقط کمی جلو می‌رود.

    +
    ۹. اگر اشتباه وارد کنم؟

    همان عدد را دوباره درست وارد کن. اشتباه هم در دفتر ثبت می‌شود؛ پنهان‌کاری لازم نیست.

    +
    ۱۰. چند نفر می‌توانند هم‌زمان وارد شوند؟

    هر تعداد کاربری که مدیر بسازد. هر نفر شناسه و رمز خودش.

    +
    ۱۱. کارهای من را کس دیگری می‌بیند؟

    فقط کاربران همین برنامه. هیچ عددی جایی فرستاده نمی‌شود.

    +
    ۱۲. اگر رمزم را گم کنم؟

    معمول رمز را بگو تا مدیر برایت کاربر تازه بسازد و رمز قبلی را حذف کند.

    +
    ۱۳. اگر برنامه خاموش شود؟

    کارهایی که ثبت شده‌اند می‌مانند؛ فقط باید دوباره روشن شود.

    +
    ۱۴. آیا می‌توانم چاپ بگیرم؟

    بله. هر خروجی صفحهٔ چاپی دارد؛ یا از همین صفحه، دکمهٔ چاپ راهنما را بزن.

    +
    ۱۵. اگر بازار بد شود چه می‌شود؟

    برنامه معاملهٔ جدید پیشنهاد نمی‌کند یا «بفروش» می‌گوید؛ چیزی که نمی‌توانی تحمل کنی از تو گرفته نمی‌شود.

    +
    ۱۶. کارنامهٔ «آماده» چقدر طول می‌کشد؟

    دو هفته کار روزانه. اگر شرطی جا بماند، یک تمدید بی‌هزینه هست.

    +
    ۱۷. آیا این برنامه در بازار ایران کار می‌کند؟

    بله؛ با قواعد همین بازار ساخته شده و کارمزد و تسویهٔ روزانه را حساب می‌کند.

    +
    ۱۸. کجا نصب می‌شود؟

    روی یک رایانه در شرکت. از هر مرورگری (لپ‌تاپ یا گوشی) با آدرس و رمز خودت وارد می‌شوی.

    +
    ۱۹. اگر بخواهم قطع کنم چه؟

    با مدیر بگو؛ دسترسی هر کاربر را می‌توان همان لحظه بست یا کامل حذف کرد.

    +
    ۲۰. سؤال دیگری داشته باشم؟

    بخش ۱۱ را نگاه کن؛ شماره و راه‌های تماس همان‌جاست.

    +
    + +
    +

    ۹) حریم خصوصی و دسترسی، در یک نگاه

    +
      +
    • عددها و دفتر، روی همان رایانهٔ شرکت می‌مانند و جایی فرستاده نمی‌شوند.
    • +
    • هر کاربر فقط با شناسه و رمز خودش وارد می‌شود؛ رمزها به شکل خوانا نگه‌داری نمی‌شوند.
    • +
    • کارهای مدیریتی (خاموش‌کردن برنامه، عوض‌کردن رمزها، صدور گواهی) فقط دست مدیر است.
    • +
    • هیچ شمارهٔ حساب بانکی و هیچ رمز بانکی جایی وارد این برنامه نمی‌شود؛ نیازی نیست.
    • +
    • اگر کارمندی از شرکت بیرون رفت، مدیر می‌تواند همان لحظه دسترسی‌اش را ببندد.
    • +
    +
    + +
    +

    ۱۰) این برنامه چه نیست

    +
    وعدهٔ پول‌دار کردن نیست. هر کسی که چنین وعده‌ای بدهد، دارد اشتباه می‌گوید.
    +
    مشاور سرمایه‌گذاری نیست. تصمیم نهایی همیشه مال توست.
    +
    ربات معامله‌گر نیست. سفارش نمی‌زند و نمی‌تواند هم بزند.
    +
    سیستم امنیت بانکی نیست. جای رمز بانکی و اطلاعات حساب اینجا نیست.
    +
    برندهٔ قرعه‌کشی یا بازار سیاه نیست. هر چیزی که «سود تضمینی» یا «اطلاعات داخلی» + بفروشد، از این برنامه نیست.
    +
    + +
    +

    ۱۱) پشتیبانی — اینجا را بخوان، بعد اگر شد تماس بگیر

    +

    اگر پاسخ‌ات در بخش‌های ۷ و ۸ نبود، همین‌ها را آماده کن و تماس بگیر؛ سرِ کار سریع حل می‌شود:

    +
      +
    1. چه کاری می‌کردی و چه دکمه‌ای زدی.
    2. +
    3. چه پیامی دیدی (همان جمله را بخوان).
    4. +
    5. روز و ساعتش.
    6. +
    +

    اگر کارمند هستی، اول به مدیر برنامه بگو؛ مدیر می‌تواند بیشترِ کارها را همان لحظه درست کند.

    +
    + +
    + تهیه‌کنندهٔ جزوات: Masoud Mojarabian · + 📱 09126630554 · + ✈️ Telegram: Mojarabian · + 📸 Instagram: Mojarabian.Art +
    +
    + + + + diff --git a/station/web/index.html b/station/web/index.html new file mode 100644 index 0000000000000000000000000000000000000000..a5f6fae0442b545f24bf36d3ec0f5d8c92ffa5ad --- /dev/null +++ b/station/web/index.html @@ -0,0 +1,853 @@ + + + + + +ایستگاه تصمیم مشتقه — نسخهٔ ۰٫۱٫۰ + + + +
    +

    ایستگاه تصمیم مشتقه

    +
    نه گام: منبع داده و اتصال ← تنظیمات ← خبر ← محاسبه ← تصمیم ← پس‌آزمایی ← بستهٔ تحویل شرکت ← آزمون زنده و دفتر سرمایه‌گذار
    +
    منبع داده: تنظیم نشده
    +
    دسترسی: در حال بررسی…
    + +
    + +
    + + +
    + +
    +

    ۱. خوش‌آمد

    +

    این ایستگاه می‌گوید «کجا تفاوت ریاضی قیمت‌ها از حاشیهٔ اطمینان عبور می‌کند»، +هشدارهای کدال را کنار همان سیگنال می‌گذارد، اندازهٔ هر موقعیت را از بودجهٔ وجه تضمین درمی‌آورد، +و در پایان یک بستهٔ راستی‌آزمایی برای شرکت می‌سازد. + +سفارش را خودتان در سامانهٔ کارگزاری ثبت می‌کنید؛ ایستگاه عدد، دلیل، کارمزد و فاصله تا خطر را +روی میز می‌گذارد تا تصمیم شما روی عدد باشد، نه روی حدس.

    +

    راهنمای کارفرما

    + +
    +

    پنل مدیریت (دسترسی محدود)

    +

    بررسی سلامت برنامه، صدور مجوز دسترسی و گزارش عیب‌یابی، و گواهی استفادهٔ موفق + به پنل مدیریت منتقل شده‌اند و با شناسه و رمز باز می‌شوند.

    +
    + + دسترسی با شناسه و رمز؛ توکن ورود یک‌ساعته است. +
    +
    +
    +

    این ایستگاه برای چه کسی ساخته شده

    +

    برای معامله‌گری که می‌خواهد پیش از هر سفارش، «عدد، کارمزد، شانس و فاصله تا + اخطاریهٔ مارجین‌کال» را ببیند و بتواند همه را بازتولید کند. اگر تازه‌کارید، از گام ۲ شروع + کنید: راهنمای ستون‌به‌ستون و مسیر اتصال آن‌جا است.

    +
    +
    + +
    +

    ۲. منبع داده

    +

    یکی از سه مسیر را انتخاب کنید. «زندهٔ واقعی» یعنی قیمت‌ها خودکار به‌روز می‌شوند؛ +اما تا کلید نخریده‌اید، با دادهٔ نمونه یا پروندهٔ دستی هم می‌توانید تمام گام‌ها را ببینید. +برای همهٔ حالت‌ها، وجه تضمین و مشخصات قرارداد از سامانهٔ کارگزاری خودتان می‌آید.

    +
    +
    + + + +
    +
    +
    + +
    +

    پروندهٔ اسنپ‌شات (برای حالت دستی، و پایهٔ حالت زنده)

    +
    + + + +
    +

    قالب را با اعداد واقعی کارگزاری پر کنید: قیمت پایه، آتی، زنجیرهٔ آپشن، تبعی، و وجه تضمین هر قرارداد.

    +
    + +
    +

    اتصال سرویس دادهٔ زنده (کلید و قالب نشانی)

    +
    +
    +
    +
    +
    +
    +
    +
    +
    +
    +
    + + اگر سرویس ایرانی باشد، باید از داخل ایران اجرا شود. +
    +
    + + +
    +

    امکان‌سنجی مسیرهای داده: ببینید قبل از خرید چه چیزی واقعاً کار می‌کند

    +

    همهٔ نشانی‌های رایگان سایت مرجع را می‌زند، پاسخ را می‌خواند، می‌گوید کدام میدان + دادهٔ موتور از آن درمی‌آید، چقدر طول می‌کشد، و با دو فراخوانی پشت‌سرهم می‌سنجد که داده تازه + می‌شود یا بی‌حرکت می‌مانَد. اگر نشانی پوش لحظه‌ای (websocket) دارید، وضعیت دسترسی‌اش را هم می‌گوید.

    +
    + + + + + در حال سنجش… +
    +

    توجه: سامانه‌های ایرانی از بیرون کشور در دسترس نیستند؛ اگر اینجا «دسترس نیست» دیدید، + همان سنجش را روی رایانهٔ خودتان (داخل ایران) اجرا کنید. گزینهٔ «دادهٔ ساختگی محلی» فقط برای دیدن + شکل خروجی است و در گزارش هم صریح برچسب می‌خورد.

    +
    + + + + +
    نقطهٔ پایانینتیجهمیلی‌ثانیهمیدان‌های یافتهتازگی (دو فراخوانی)
    +
    +
    + + + + +
    +
    آماده.
    +
    + +
    +

    پیش از خرید داده، این را بخوانید

    +

    سه مسیر داده (سرویس رسمی پولی، سرویس‌های عمومی، پوش لحظه‌ای کارگزاری) با نیاز + واقعی همین ایستگاه سنجیده شده‌اند؛ از جمله اینکه وجه تضمین را هیچ سرویس داده‌ای نمی‌دهد. + نتیجه: امروز هیچ‌چیز نخرید؛ اول سابقهٔ ثبت‌شده بسازید.

    +
    + +
    +
    + +
    +

    دفتر اتصال — «هر وقت سرویس را گرفتم، همین‌جا وصلش کنم»

    +

    یک پروفایل انتخاب کنید، کادرهای بالا خودشان پر می‌شوند، آزمایش کنید و ذخیره کنید. + از آن به بعد، هر بار که برنامه بالا بیاید همین اتصال خودکار فعال می‌شود.

    +
    + + + + +
    +
    در حال خواندن دفتر اتصال‌ها…
    +
    + + + +
    +
    + یک اتصال تازه بسازم یا پروفایل فعلی را عوض کنم +
    +
    +
    +
    +
    +
    + + قالب نشانی، مسیر JSON و کلید از همان کادرهای بالای صفحه خوانده می‌شود. +
    +
    +
    + +
    +

    کاوش پاسخ سرویس — پیدا کردن «مسیر JSON» در یک دقیقه

    +

    نشانی سرویس را بگذارید، دکمه را بزنید، و از فهرست عددهایی که پیدا می‌شود + روی «استفاده» بزنید تا مسیر درست خودش پر شود. دیگر لازم نیست ساختار پاسخ را حدس بزنید.

    +
    + + +
    +
    +
    + + +
    +

    برگهٔ شاهد زنده — برای نشان‌دادن به سرمایه‌گذار یا کارفرما

    +

    + نود ثانیه وقت می‌گیرد. عددها را همین حالا از سرویس فعال می‌خواند، نشانی و + اثر انگشت پاسخ خام و ساعت خواندن را چاپ می‌کند، و یک تصمیم نمونه با پاسخ، + مسیر محاسبه و پلهٔ خروج می‌سازد. جملهٔ محوری‌اش این است: «این عدد را من تایپ نکردم». +

    + + + در حال خواندن از سرویس… +
    هنوز ساخته نشده است.
    +
    +
    +

    اتصال خودکار — «خودت بگرد ببین کدام منبع رایگان امروز کار می‌کند»

    +

    من نمی‌توانم از جای خودم بررسی کنم که سرویس‌های ایرانی امروز چه پاسخی می‌دهند؛ + ولی خودِ برنامه روی رایانهٔ شما می‌تواند. این دکمه چند منبع رایگان را یکی‌یکی امتحان می‌کند، + پاسخ را می‌خواند، عدد را عقلی می‌سنجد، و می‌گوید کدام کار کرد و چرا آن یکی کار نکرد. + هیچ کلیدی لازم نیست و هیچ هزینه‌ای ندارد.

    +
    + + + در حال امتحان منابع… +
    +
    +
    + +
    +

    وارد کردن اعداد کارگزاری — اسنپ‌شات تاریخ‌دار

    +

    این اعداد را از سامانهٔ کارگزاری خودتان بردارید و همین‌جا در جدول بنویسید؛ + برنامه آن‌ها را با تاریخ امروز ذخیره می‌کند (data/snapshots/snapshot-YYYY-MM-DD.json). + پروندهٔ تاریخ‌دار یعنی سابقهٔ قابل ممیزی، و روز «واقعی» در کارنامه حساب می‌شود. + وجه تضمین را حتماً از سامانه بردارید؛ هیچ سرویسی این عدد را نمی‌دهد.

    +
    + + + + هنوز خوانده نشده است. +
    +
    + + + + +
    نمادراهبردقیمت پایهآتیاعمالپرمیومروزوجه تضمین هر قراردادنقدشوندگی روزاسپردکد نماد
    +
    + + + + +
    +
    + + +
    +

    تا این تیک را نزنید، پرونده ذخیره نمی‌شود و روز «واقعی» حساب نمی‌شود. + این شرط عمدی است: کارنامه باید روی اعداد واقعی بایستد، نه روی دادهٔ تمرینی.

    +
    + راهنمای ستون‌به‌ستون — هر عدد را از کجا بیاورم؟ (برای تازه‌کارها) +
      +
    • نماد: نام نماد روی تابلوی کارگزاری (مثل «فولاد»). اگر سهم است، کد نماد لازم است؛ + دکمهٔ «پیدا کردن کد نمادها» در کارت اتصال، آن را خودش پر می‌کند.
    • +
    • راهبرد: نوع معاملهٔ خودتان؛ اگر نمی‌دانید، «کری» یا «پوشش‌داده‌شده» را بگذارید و + برنامه خودش می‌گوید محاسبه‌پذیر است یا نه.
    • +
    • قیمت پایه: قیمت لحظه‌ای سهم یا دارایی در «مشاهدهٔ زنده» کارگزاری.
    • +
    • آتی: قیمت قرارداد آتی همان دارایی (تابلوی آتی در کارگزاری).
    • +
    • اعمال: قیمت اعمال اختیار (ستون «قیمت اعمال» در تابلوی اختیار معامله).
    • +
    • پرمیوم: قیمت خودِ اختیار (ستون «آخرین قیمت» در تابلوی اختیار).
    • +
    • روز: فاصلهٔ امروز تا سررسید، به روز (کارگزاری می‌نویسد).
    • +
    • وجه تضمین هر قرارداد: فقط سامانهٔ کارگزاری دارد؛ این عدد مهم است و هیچ سایت + عمومی جای آن را نمی‌گیرد.
    • +
    • نقدشوندگی روز: ستون «حجم» همان قرارداد در امروز.
    • +
    • اسپرد: اختلاف قیمت خریدن و فروختن تقسیم بر میانگین؛ ۱٫۸٪ را بنویسید «1.8».
    • +
    +
    +
    + +
    +
    + + + +
    +
    هنوز متنی نچسبانده‌اید.
    +
    +
    + +
    +

    راهنمای خرید داده: چه بخرم و چرا

    + + + +
    گزینهچه می‌دهدهزینهٔ تقریبی (در سایت فروشنده تأیید کنید)نحوهٔ اتصالپس از اتصال چه تغییر می‌کند
    +
    +
    آماده.
    +
    + + +
    +

    ۳. تنظیمات ریاضی و ریسک

    +

    این اعداد تصمیم را عوض می‌کنند. پیش‌فرض‌ها محافظه‌کارانه‌اند؛ هر عدد را بنا به شرایط خودتان عوض کنید و دوباره محاسبه بگیرید.

    +
    +
    نرخ سد را از کجا بیاورم؟ از «بازده مؤثر سالانه» صندوق درآمد ثابت همان روز. +در شهریور ۱۴۰۵ این عدد حدود ۳۹ تا ۴۰ درصد بود. اگر نرخ سد اشتباه باشد، همهٔ سیگنال‌ها اشتباه می‌شوند.
    +
    +
    +
    آماده.
    +
    + + +
    +

    ۴. خبر و هشدار (اختیاری)

    +

    خبر به‌تنهایی سیگنال نیست. کارکردش سه چیز است: زمینه، اولویت‌بندی، و ساختن «کار بازبینی» +برای نمادهایی که خبر مهم دارند ولی در اسنپ‌شات شما نیستند.

    +
    + +
    + + + +
    +
    +
    آماده.
    +
    + + +
    +

    ۵. اجرا و محاسبه

    +

    با یک دکمه: اسنپ‌شات خوانده می‌شود، موتور ریاضی هر ردیف را حساب می‌کند، +دروازه‌های ریسک اعمال می‌شوند، و داشبورد تصمیم ساخته می‌شود.

    +
    + + در حال محاسبه…
    +
    +
    آماده.
    +
    + + +
    +

    ۶. نتیجه و تصمیم

    +

    هر سیگنال را ببینید، دلیل دروازه‌ها را بخوانید، و اگر پذیرفتید تأیید کنید. +تأیید شما در دفتر ثبت می‌شود و اجرای دوبارهٔ برنامه آن را بازنویسی نمی‌کند.

    +
    +
    + + + + +
    +
    + + + + +
    شناسهنمادراهبردبازده سالانه٪حاشیهاندازهسرمایه (ریال)وضعیتدلیل دروازه / خبر
    + +
    +

    داوری سیگنال ابزارهای دیگر — «سیگنال نرم‌افزار فعلی‌تان را بیاورید»

    +

    دیده‌بان‌ها و ماشین‌حساب‌های بازار، سیگنال و قیمت تئوری می‌دهند؛ ولی نمی‌گویند آن + سیگنال با کارمزد واقعی، اسپرد، نقدشوندگی و نرخ سد می‌مانَد یا می‌افتد. عددهای سیگنال آن‌ها را + این‌جا بگذارید تا داوری، «نقطهٔ برگشت» و «فاصله تا مارجین‌کال» را بگیرید.

    +
    + + + عددهای ورودی (JSON): +
    +
    + +
    +
    + + + + + + + در حال داوری… +
    +
    +
    + + + +
    +
    آماده.
    +
    +
    آماده.
    +
    + + +
    +

    ۷. پس‌آزمایی روی دادهٔ تاریخ

    +

    همان موتوری که در تصمیم زنده کار می‌کند، روی دادهٔ گذشته اجرا می‌شود: +نرخ برد، خطای مثبت کاذب، فرصت‌های از دست رفته، و خطای پیش‌بینی (انتظار منهای واقعیت) حساب می‌شود.

    +
    +
    + + + + + در حال اجرا… +
    +

    ستون کلیدی پروندهٔ تاریخ: realized_annualized_pct یعنی «نتیجهٔ واقعی» آن معامله در گذشته. + این ستون در تصمیم هیچ نقشی ندارد و فقط برای سنجش است (آزمون ضد آینده‌نگری در تست‌ها اجرا می‌شود).

    +
    +
    +
    آماده.
    +
    + + +
    +

    ۸. بستهٔ تحویل شرکت

    +

    این بسته همه‌چیز را برای راستی‌آزمایی شرکت در یک پوشه می‌گذارد: +گزارش تصمیم‌ها، فهرست سیگنال‌ها، سند روش کار، بسته‌های سفارش، نتیجهٔ پس‌آزمایی، +و چک‌لیستی که خودشان در پنج دقیقه راستی‌آزمایی کنند.

    +
    + + + + + + + + + + + + + + +
    +
    +

    تابلوی پیگیری مخاطبان — «پنج نام این هفته»

    +

    فقط برای خودتان و روی همین رایانه: نام مخاطب، دسته، کانال، وضعیت. برنامه + خودش می‌گوید امروز چه کسی پیگیری لازم دارد (روز ۳ و روز ۱۰) و سه عدد هفته را می‌شمارد: + چند پیام، چند تماس، چند جلسه. شمارهٔ تلفن در این دفتر ذخیره نمی‌شود.

    +
    + + + + + + + + +
    +
    + + + + + + +
    +
    هنوز خوانده نشده است.
    +
    آماده.
    +
    +
    +

    مراسم فروش امروز — بیست دقیقه

    +

    تابلو را می‌خواند و کار امروز را با متن آمادهٔ همان مخاطب و لحن درستش + کنار هم می‌گذارد: کدام کار، در چه دقیقه‌ای. سقف پنج پیام در روز و بودجهٔ بیست دقیقه در خود + برنامه قفل است؛ هر کاری که جا نشد، با دلیلش به «فردا» می‌رود. اگر امروز نوبت کسی نباشد، + پیام تازه‌ای ساخته نمی‌شود.

    +
    + + + + +
    +
    آماده.
    + در حال ساخت… +
    +

    محتوای بسته

    هنوز ساخته نشده است.
    +
    آماده.
    +
    + + + +
    +

    ۹. آزمون زنده و دفتر سرمایه‌گذار

    +

    اینجا همان چیزی است که ارزش برنامه را ثابت می‌کند: نه وعدهٔ سود، بلکه سابقهٔ ثبت‌شده. +هر سیگنالی که برنامه می‌سازد، با ساعت دقیق و همهٔ ورودی‌های ریاضی در دفتر می‌نشیند. +بعداً با خواندن قیمت‌های تازه، دفتر می‌گوید همان فرصت امروز بازتر شد، بسته شد، یا زیر کف رفت. +هر ثبت یک هش زنجیره‌ای دارد؛ اگر کسی ردیفی را عوض کند، زنجیره می‌شکند و گزارش همان را نشان می‌دهد.

    + +
    +

    ۰. مراسم امروز — یک دکمه، تمام کارهای امروز

    +

    این دکمه همان کاری را می‌کند که هر روز کاری باید بشود: قیمت تازه می‌خواند، + محاسبه می‌کند، سیگنال‌های امروز را ثبت می‌کند، ردیف‌های قبلی را بازسنجی می‌کند، زنجیره را + بررسی می‌کند، گزارش می‌سازد، و کارنامه را به‌روز می‌کند. هیچ سفارشی ارسال نمی‌شود.

    +
    + + + + در حال اجرا… +
    +
    + +
    +

    کارنامهٔ آزمون: آیا وقت خرید دادهٔ زنده و رفتن به جلسهٔ شرکت رسیده؟

    +
    +
    هنوز مراسمی اجرا نشده است.
    + + + +
    شرطوضعیتلازمراهنمای عمل
    +
    تاریخ اجراهای قبلی
    —
    +
    + +
    +

    ۱. ثبت سیگنال‌های امروز در دفتر

    +
    + + + +
    +

    «ثبت با حاشیهٔ محافظه‌کارانه» انتظار را دو واحد درصد پایین‌تر می‌نویسد تا فرض‌ها + واقع‌بینانه‌تر شود؛ این کار سابقهٔ شما را برای شرکت معتبرتر می‌کند، نه ضعیف‌تر.

    +
    + +
    +

    ۲. بازسنجی با قیمت‌های تازه

    +
    + + + در حال خواندن… +
    +

    این دکمه همان موتور گام ۵ را روی قیمت‌های امروز اجرا می‌کند و تفاوت را در دفتر می‌نویسد. + برای این کار منبع داده باید فعال باشد (خوراک آزمایشی محلی هم کافی است).

    +
    + +
    + +
    +

    ۳. دفتر ثبت‌ها

    +
    + + + +
    +
    + + + + + +
    #زمان ثبتنمادراهبردتصمیمانتظار در ثبتانتظار امروزتغییروضعیتمنبع دادههش
    +
    + +
    +

    ۴. آزمون ۱۰ دقیقه‌ای: بگذارید خودش امتحانش کند

    +

    پانزده مورد، هر کدام دو بار حساب می‌شود: یک بار با موتور واقعی برنامه، یک بار + با «حساب دستی» که همان‌جا در کد نوشته شده و با ماشین‌حساب قابل چک است. برگهٔ آزمون را به سرمایه‌گذار + بدهید تا اول حدس خودش را بنویسد، بعد پاسخ و راه چک را ببیند. هیچ عددی از قبل «درست» فرض نشده است.

    +
    + + + + در حال اجرا… +
    +
    + + + + +
    موردچه چیزی را ثابت می‌کندخروجی برنامه در برابر حساب مستقلوضعیت
    +
    + +
    +

    ۵. پروندهٔ سرمایه‌گذار: یک فایل برای جلسه

    +

    قواعد قفل‌شده، نتیجهٔ آزمون، دفتر و کارنامه، پس‌آزمایی، وضعیت اتصال، آنچه ادعا + نمی‌کنیم، و اثر انگشت (sha256) پرونده‌ها را در یک صفحهٔ آمادهٔ چاپ می‌ریزد؛ همین را به شرکت بدهید. + هیچ داده‌ای بیرون نمی‌رود و هیچ سودی وعده داده نمی‌شود.

    +
    + + + + در حال ساخت… +
    +
    هنوز ساخته نشده است.
    +
    + +
    +

    ۶. برنامهٔ ۱۵ دقیقه‌ای جلوی سرمایه‌گذار

    +

    راهنمای کامل و متن گفتگو در پروندهٔ DEMO-INVESTOR-FA.md است (دکمهٔ زیر بازش می‌کند). + خلاصه‌اش این است:

    +

    برای دورهٔ دو هفته‌ای، هر روز کاری فقط دکمهٔ «اجرای مراسم امروز» را بزنید؛ + بقیه‌اش خودکار است. روی ویندوز می‌توانید با schedule-daily-trial.bat بگذارید + هر روز خودش اجرا شود و شما فقط کارنامه را ببینید.

    +
      +
    1. گام ۲: پروفایل «خوراک آزمایشی محلی» را آزمایش کنید — نشان دهید قیمت زنده می‌آید و نوار تازگی سبز می‌شود، بدون هیچ هزینه.
    2. +
    3. گام ۵: محاسبه بگیرید — سیگنال‌ها با عدد و دلیل دروازه روی میز می‌آیند.
    4. +
    5. خودش امتحان کند: بگویید «کارمزد را از ۰٫۴۶٪ به ۲٪ تغییر بده» — ببینید سیگنال‌ها یکی‌یکی محو می‌شوند. این لحظهٔ اعتماد است.
    6. +
    7. گام ۷: پس‌آزمایی روی تاریخ — خطای پیش‌بینی منفی را هم نشان دهید؛ صداقت عدد، بهترین تبلیغ است.
    8. +
    9. گام ۹: دفتر را ثبت کنید و همان‌جا زنجیرهٔ هش را بررسی کنید؛ قرار بگذارید دو هفته بعد بازسنجی شود.
    10. +
    11. آزمون: دکمهٔ «اجرای آزمون ۱۰ دقیقه‌ای» را بزنید و بگذارید خودش دو مورد را با ماشین‌حساب چک کند.
    12. +
    13. پرونده: پروندهٔ سرمایه‌گذار را بسازید و همان فایل را به شرکت بدهید.
    14. +
    +
    + + +
    +
    +
    آماده.
    +
    + +
    +

    ۱۰. آزمون کور سرمایه‌گذار — «خودش بپرسد، خودش حساب کند، خودش باور کند»

    +

    بهترین راه متقاعدکردن سرمایه‌گذار باسواد این نیست که سود نشانش بدهیم؛ این است که + خودش یک عدد را روی کاغذ حساب کند و ببیند برنامه همان را می‌گوید. این گام سه کار می‌کند: + شش پرسش کور می‌پرسد و پاسخ‌ها را پنهان نگه می‌دارد، آستانهٔ ریزش راهبردها را نشان می‌دهد، + و یک معاملهٔ واقعی گذشته را با کارمزدهای ایران حساب می‌کند. هیچ‌کدام از این عددها وعدهٔ سود نیست؛ + حساب است.

    +
    +

    ۱. شش پرسش کور: اول شما حدس بزنید، بعد برنامه پاسخ می‌دهد

    +

    ابتدا فقط پرسش‌ها می‌آید. عدد یا «بله/خیر» خودتان را بنویسید، بعد دکمهٔ داوری را بزنید تا + پاسخ برنامه با فرمول و روش دوم (برای بازبینی با ماشین‌حساب) رو شود.

    +
    + + + در حال کار… +
    +
    هنوز پرسشی نمایش داده نشده است.
    +
    +
    +

    ۲. آستانهٔ ریزش: با هر نرخ سد شما، کدام راهبرد می‌ماند و کدام می‌افتد

    +

    نرخ سد را در گام ۳ می‌گذارید. این جدول همان را روی همهٔ راهبردها اعمال می‌کند تا + ببینید کدام راهبرد به تصمیم شما حساس است.

    +
    +
    هنوز محاسبه نشده است.
    +
    +
    +

    ۳. حساب‌رسی واقعیت: یک معاملهٔ گذشته با عدد کارگزاری

    +

    این کار به اینترنت نیاز ندارد. اگر سرمایه‌گذار بگوید «من فلان روز فلان سهم را + خریدم و فلان‌روز فروختم»، عددها را اینجا بگذارید تا کارمزد و مالیات کم شود و نتیجهٔ واقعی درآید.

    +
    + + + + + + + + در حال حساب… +
    +
    آماده.
    +
    +
    +

    ۴. برگهٔ چاپی و زنجیرهٔ هش

    +

    این برگه چکیدهٔ همین جلسه است: حدس‌های سرمایه‌گذار، پاسخ‌های برنامه، جدول آستانهٔ + ریزش و حساب‌رسی‌ها، با جای امضا. کلید زنجیره در پایین برگه می‌آید؛ اگر عددی بعداً عوض شود، + کلید می‌شکند.

    +
    + + + + + + + +
    +
    + + + + +
    +
    آماده.
    +
    +
    + +
    +

    ۱۱. راهبردها، شوک‌آزمون و ریاضیِ پول — «ایده‌های پول‌ساز، با عدد و با مرزِ افتادن»

    +

    این گام سه سند می‌سازد. هیچ‌کدام وعدهٔ سود نیست: یکی می‌گوید هر راهبرد چه وقت + به‌کار می‌آید و کِی باید ببندی، یکی راهبردها را زیر شرایط بد می‌گذارد تا ببینی کجا می‌افتند، + و یکی ریاضیِ بقا را می‌گوید (اندازهٔ درست هر معامله، احتمال نیم‌شدن حساب، و چند وقت تا هدف).

    +
    +

    ۱. جزوهٔ راهبردها: درصدِ هر راهبرد، با روشِ عدد و قاعدهٔ بستن

    +

    هر عدد یک برچسب روش دارد: «قطعی» (در لحظهٔ ورود قفل می‌شود، مثل تبعی و باکس)، + «مدل‌محور» (با نوسان ضمنی خودِ قیمت بازار حساب می‌شود)، و «نقل‌شده» (از منبع، با نام منبع). + هر عدد با دو روش حساب می‌شود: موتور ایستگاه + محاسبهٔ دستی دوم؛ اگر نخوانند، همان‌جا علامت مخالف می‌خورد.

    +
    + + + + + در حال ساخت… +
    +
    هنوز ساخته نشده است.
    +
    +
    +

    ۲. شوک‌آزمون: «مطمئن شو ایده‌های قبلی واقعاً جواب می‌دهند»

    +

    هر راهبرد با پنج بدترشدن دوباره حساب می‌شود: لغزش اجرا ۰٫۵٪، حرکت مخالف قیمت، + کارمزد دو و سه برابر، و نرخ سد ۴۵٪. سه دسته می‌آید: سخت‌جان، لرزان، و + لبِ مرز (رد کرد ولی حاشیه‌اش کمتر از ۵ واحد درصد شد). «نرخ تاب‌آوری» احتمال سود نیست.

    +
    + + + +
    +
    هنوز حساب نشده است.
    +
    +
    +

    ۳. ریاضیِ پول: اندازهٔ درست، احتمال ورشکستگی، و زمان تا هدف

    +

    سرمایهٔ کوچک با اندازهٔ درشت می‌میرد و با اندازهٔ درست عمر می‌کند. این کارت + کسر کِلی (و نسخهٔ نصف‌کِلی محافظه‌کارانه) را حساب می‌کند، هزاران مسیر ممکن را شبیه‌سازی می‌کند + و می‌گوید با این مزیت و این کارمزد، رسیدن به هدف چند ماه/سال طول می‌کشد — و کجا احتمال نیم‌شدن حساب هست.

    +
    + + + + + + + + + + + در حال حساب… +
    +
    هنوز حساب نشده است.
    +
    +
    +

    ۴. چرا این‌ها «وعدهٔ پول» نیستند (و چطور با این حال پول درمی‌آید)

    +

    سه چیز در این گام قفل شده است: کارمزد واقعی از هر معامله کسر می‌شود، عددها با + دو روش حساب می‌شوند، و راهبردِ بی‌مزیت با پرچم «نمی‌ارزد» بیرون می‌آید. پول درآوردن از این‌جا + می‌آید: کارهای بی‌مزیت را رد کن، کارهای قفل‌شده (تبعی/مبنا) را با اندازهٔ درست بگیر، + و دفتر شاهد بساز تا دیگری هم بتواند راستی‌آزمایی کند. اگر سرمایه‌گذار بپرسد «درصد سودت چقدر + است؟»، جواب درست این است: «سود را وعده نمی‌دهم؛ این‌جا نشان می‌دهم چه چیزی ریاضی می‌ماند و چه + چیزی می‌افتد — و همه را با ماشین‌حساب خودتان بازتولید می‌کنید.»

    +
    +
    + +
    + + +
    +
    +
    + + + + + + diff --git a/station/web/login.html b/station/web/login.html new file mode 100644 index 0000000000000000000000000000000000000000..021dbd4674e54a54dd2dfe6ff26dc1ec4c8724c9 --- /dev/null +++ b/station/web/login.html @@ -0,0 +1,111 @@ + + + + + +ورود — ایستگاه تصمیم مشتقه + + + +
    +
    + دسترسی نام‌دار · نسخهٔ محلی +

    ایستگاه تصمیم مشتقه — ورود

    +

    این برنامه روی رایانهٔ خودِ ارائه‌دهنده اجرا می‌شود؛ عددها از بازار خوانده و + محلی حساب می‌شوند و هیچ سفارشی به کارگزاری فرستاده نمی‌شود.

    + + + + + + +
    + +
    + کارفرما با حسابی که برایش ساخته شده وارد می‌شود (دسترسی «مهمان»): همهٔ گام‌ها و همهٔ + خروجی‌ها را می‌بیند و تست می‌کند، ولی نمی‌تواند مجوز صادر کند، رمز عوض کند یا برنامه را + خاموش کند. اگر رمز را ندارید، از ارائه‌دهنده بخواهید. +
    +
    +

    + اولین بار است؟ راهنمای کارفرما را بخوان: + روز اول چه کار کنی، هر روز چه بزنی، و هر پیامی که ممکن است ببینی. +

    +
    +
    + + + diff --git a/station/web_server.py b/station/web_server.py new file mode 100644 index 0000000000000000000000000000000000000000..2867a879f9620e21f865e4e1df2eb72e5dab60f5 --- /dev/null +++ b/station/web_server.py @@ -0,0 +1,1775 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""کارساز محلی ایستگاه — رابط گرافیکی مرورگری (بهترین نمایش فارسی روی هر سیستم). + +اجرا: python web_server.py (پیش‌فرض روی درگاه ۸۷۶۵) + python web_server.py --port 9000 --host 0.0.0.0 + python web_server.py --no-browser (باز کردن خودکار مرورگر را خاموش می‌کند) + +چرا مرورگر؟ خط و نشان فارسی در tb/tk روی لینوکس شکسته و برعکس رندر می‌شود؛ +مرورگر روی همهٔ سیستم‌ها فارسی را درست و راست‌به‌چپ نشان می‌دهد. +این کارساز فقط روی همین رایانه سرو می‌کند و هیچ داده‌ای جایی نمی‌فرستد. +""" +from __future__ import annotations + +import argparse +import json +import mimetypes +import os +import sys +import threading +import traceback +import time +import webbrowser +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer +from datetime import timedelta +from pathlib import Path +from urllib.parse import urlparse, parse_qs, quote + +VERSION = "0.1.0" +BASE = Path(__file__).resolve().parent +GUI = BASE # پوشهٔ خودِ ایستگاه (شامل station.py، web/، data/، demo/) +DESK_DIR = (GUI.parent / "desk").resolve() +KODAL_DIR = (GUI.parent / "kodal-alert").resolve() +DATA = GUI / "data" +WEB = GUI / "web" +EXPORT = GUI / "export" + +for p in (str(GUI), str(DESK_DIR), str(KODAL_DIR)): + if p not in sys.path: + sys.path.insert(0, p) + +import ladder as laddermod # noqa: E402 +import datafeed # noqa: E402 +import backtest as bt # noqa: E402 +import station as st # noqa: E402 +import connections as conn # noqa: E402 +import live_trial as trial # noqa: E402 +import mock_feed # noqa: E402 +import daily_trial as dailytrial # noqa: E402 +import autoconnect as autoconn # noqa: E402 +import selftest as selfcheck # noqa: E402 +import dossier as dossier_mod # noqa: E402 +import data_sources as sourcesmod # noqa: E402 +import investor_test as invtest # noqa: E402 +import signal_judge as judger # noqa: E402 +import license as licmod # noqa: A004 +import diagnose as diagmod # noqa: E402 +import snapshot_import as snapimp # noqa: E402 +import adminauth as admauth # noqa: E402 +import usage_meter as usagemod # noqa: E402 +import offer as offermod # noqa: E402 +import outreach as outreachmod # noqa: E402 +import prospects as prospectsmod # noqa: E402 +import onboarding as onbmod # noqa: E402 +import sales_ritual as ritualmod # noqa: E402 +import review_meeting as reviewmod # noqa: E402 +import gate as gatemod # noqa: E402 +import strategy_audit as stratmod # noqa: E402 +import edge_stress as stressmod # noqa: E402 +import bankroll as bankmod # noqa: E402 +import demo_day as demoday # noqa: E402 + +import desk as deskmod # noqa: E402 +import kodal_alert as kodal # noqa: E402 + +STATE: dict = { + "mode": "sim", + "file_path": str(DESK_DIR / "market-demo.json"), + "live_cfg": dict(datafeed.DEFAULT_LIVE_CONFIG), + "key": "", + "use_kodal": True, + "kodal_db": str(KODAL_DIR / "data" / "demo.sqlite3"), + "rules": { + "capital": 20_000_000_000, "hurdle": 0.39, + "min_edge_arbitrage_pct": 3.0, "min_edge_leveraged_pct": 5.0, + "max_margin_pct": 0.20, "max_position_pct": 0.35, "max_positions": 3, + "min_liquidity_contracts_per_day": 20, "max_spread_pct": 0.03, + "max_plausible_arb_pct": 250.0, "max_plausible_lev_pct": 400.0, + }, + "snapshot": None, + "backtest_result": None, + "bundle_dir": None, + "connection": {"name": "", "label": "", "key_where": "بدون کلید", "is_mock": False}, + "trial_db": str(trial.DEFAULT_DB), + "last_sigs": [], + "trial_last_mark": [], +} + +# ---------------------------------------------------------------- دفتر اتصال و دفتر آزمون +def apply_saved_connection() -> dict: + """پروفایل فعالِ ذخیره‌شده را روی وضعیت برنامه می‌نشاند (هر بار که برنامه بالا می‌آید).""" + active = conn.active_or_none() + if not active: + return STATE["connection"] + prof = active["profile"] + STATE["live_cfg"] = active["live_cfg"] + if active["key"]: + STATE["key"] = active["key"] + STATE["mode"] = "live" + STATE["connection"] = {"name": prof["name"], "label": prof["label"], + "key_where": active["key_where"], "is_mock": active["is_mock"]} + return STATE["connection"] + + +def connection_payload() -> dict: + store = conn.load_store() + keys = {p["name"]: conn.key_status(p["name"]) for p in store.get("profiles", [])} + return {"profiles": store.get("profiles", []), "selected": store.get("selected", ""), + "active": STATE["connection"], "store_file": str(conn.PROFILES_FILE), + "keys_file": str(conn.KEYS_FILE), "keys_stored": bool(conn.load_keys()), + "key_status": keys} + + +def peek_payload(body: dict) -> dict: + """پاسخ خام سرویس را می‌خواند و مسیرهای عددی‌اش را نشان می‌دهد (برای پیدا کردن مسیر JSON).""" + url = str(body.get("url") or "").strip() + if not url: + return {"ok": False, "error": "نشانی خالی است."} + key = str(body.get("key") or "") + if "{key}" in url and not key: + return {"ok": False, "error": "این نشانی {key} دارد ولی کلید خالی است."} + url = url.replace("{key}", urlparse_quote(key)) + text, status = datafeed.fetch(url, timeout=float(body.get("timeout_seconds", 12)), retries=1, + key_header=str(body.get("key_header") or ""), key=key, + cache_name="peek.json", cache_seconds=0, stale_ok=False) + if not text: + return {"ok": False, "error": f"پاسخی نیامد ({status}). نشانی و اینترنت را بررسی کنید.", "status": status} + try: + payload = json.loads(text) + except Exception: + return {"ok": False, "status": status, "error": "پاسخ JSON نبود (شاید صفحهٔ HTML است).", + "preview": text[:600]} + paths = datafeed.numeric_paths(payload) + out = {"ok": True, "status": status, "bytes": len(text), + "preview": text[:800], "paths": [{"path": p, "value": v} for p, v in paths], + "count": len(paths)} + # اگر کاربر مسیری را که در تنظیمات دارد هم بفرستد، صریح می‌گوییم «همین مسیر عدد دارد یا نه». + wanted = str(body.get("json_path") or "").strip() + if wanted: + value = datafeed.dig(payload, wanted) + out["json_path"] = wanted + out["path_ok"] = value is not None + out["path_value"] = value + out["path_hint"] = (f"مسیر «{wanted}» در پاسخ هست و مقدارش {value} است؛ همین را در " + f"تنظیمات بگذارید." if value is not None else + f"مسیر «{wanted}» در پاسخ نبود. از فهرست بالا یکی از مسیرهای عددی را " + f"بردارید و در تنظیمات بگذارید.") + return out + + +def urlparse_quote(value: str) -> str: + from urllib.parse import quote + return quote(str(value)) + + +def build_now_map(sigs) -> dict: + """از سیگنال‌های تازه، حاشیهٔ امروز هر نماد را درمی‌آورد.""" + cfg = STATE["rules"] + out: dict = {} + for s in sigs or []: + kind = getattr(s, "kind", "") + floor = (cfg["min_edge_arbitrage_pct"] if kind in ("basis", "arbitrage") + else cfg["min_edge_leveraged_pct"]) + detail = getattr(s, "detail", {}) or {} + out[str(getattr(s, "symbol", ""))] = { + "expected_now": getattr(s, "annualized_pct", None), + "floor": floor, + "spot_now": detail.get("spot") or detail.get("stock_price"), + "future_now": detail.get("future"), + } + return out + + +def trial_payload() -> dict: + t = trial.Trial(STATE["trial_db"]) + marks = t.latest_marks() + entries = [] + for e in t.all(limit=200): + m = marks.get(e["id"], {}) + entries.append({"id": e["id"], "ts": e["ts"], "symbol": e["symbol"], "kind": e["kind"], + "decision": e["decision"], "expected": e["expected"], + "expected_now": m.get("expected_now"), "delta_pp": m.get("delta_pp"), + "status_now": m.get("status", "بازسنجی‌نشده"), "marked_at": m.get("ts"), + "note": e["note"], "source_label": e["source_label"] or "", + "hash": e["hash"][:16] + "…"}) + score = dailytrial.scorecard(t, log_records=dailytrial.read_log()) + runs = dailytrial.read_log()[-8:] + return {"summary": t.summary(), "entries": entries, "db": str(t.path), + "report_ready": (GUI / "data" / "trial-report.html").exists(), + "scorecard": score, "runs": runs} + + +# ------------------------------------------------------------------ پنل مدیریت + +# این سه دسته از برنامه به پنل مدیریت رفته‌اند و بدون ورود، پاسخ نمی‌دهند. +ADMIN_ENDPOINTS = ("/api/health", "/api/license", "/api/diagnose", "/api/usage", "/api/state/info") +ADMIN_MAP = { + "/api/admin/health": "/api/health", + "/api/admin/license": "/api/license", + "/api/admin/diagnose": "/api/diagnose", + "/api/admin/usage": "/api/usage", + "/api/admin/state": "/api/state/info", + "/api/admin/backup": "/api/state/backup", +} +ADMIN_FILE_KEYS = ("diagnostic", "usage", "usage-md", "grant-doc", + "license-doc", "license-doc-md") + + + +def state_keeper(): + """نگهبان وضعیت ابری را می‌آورد — فقط در نسخهٔ روی Hugging Face این پرونده وجود دارد. + + چرا این‌جا و با این احتیاط: روی رایانهٔ خودِ کاربر (`kit`/`backpack`) پشتیبان‌گیری محلی + سرِ جای خود است و این پرونده نیست؛ پس نبودنش خطا نیست و پنل باید صادقانه «خاموش» بگوید. + """ + for base in (Path(__file__).resolve().parent.parent, Path(__file__).resolve().parent): + if not (base / "space_state.py").exists(): + continue + if str(base) not in sys.path: + sys.path.insert(0, str(base)) + try: + import importlib + return importlib.import_module("space_state") + except Exception as e: # noqa: BLE001 + log(f"نگهبان وضعیت بار نشد: {type(e).__name__}: {e}") + return None + return None + + +OFFLINE_STATE = {"ok": True, "online": False, "files": 0, "interval_seconds": 0, "last": {}, "restored": {}, + "note": "این نسخه روی میزبان ابری نیست؛ پشتیبان‌گیری محلی سرِ جای خود است."} + + +def doc_path(name: str) -> Path: + """سندها را در چند جای ممکن می‌جوید تا بستهٔ کپی‌شده روی هر رایانه‌ای کار کند. + + ترتیب: پوشهٔ «money» (کنار desk و gui) ← زیرپوشهٔ «docs» همان پا (بستهٔ تحویل شرکت) + ← پوشهٔ «docs» داخل خودِ ایستگاه. + """ + for cand in (DESK_DIR.parent / name, DESK_DIR.parent / "docs" / name, GUI / "docs" / name): + if cand.exists(): + return cand + return DESK_DIR.parent / name # اگر نبود، همان مسیر پیش‌فرض را برگردان + + +def doc_dir(name: str) -> Path: + """پوشهٔ اسناد چندبخشی (مثل جزوهٔ راهبردها).""" + for cand in (DESK_DIR.parent / name, DESK_DIR.parent / "docs" / name, GUI / "docs" / name): + if cand.exists(): + return cand + return DESK_DIR.parent / name + + +SERVED_FILES = { + "dashboard": GUI / "data" / "dashboard.html", + "backtest": GUI / "data" / "backtest.html", + "backtest.csv": GUI / "data" / "backtest.csv", + "method": GUI / "data" / "method-preview.html", + "05-backtest.html": GUI / "data" / "backtest.html", + "07-manifest.json": None, # از پوشهٔ بسته پر می‌شود + "03-method.html": GUI / "data" / "method-preview.html", + "trial": GUI / "data" / "trial-report.html", + "trial-report.html": GUI / "data" / "trial-report.html", + "trial-entries.csv": GUI / "data" / "trial-entries.csv", + "selftest": GUI / "data" / "selftest-report.html", + "exam": GUI / "data" / "exam-sheet.html", + "exam-sheet.html": GUI / "data" / "exam-sheet.html", + "dossier": GUI / "data" / "investor-dossier.html", + "dossier-md": GUI / "data" / "investor-dossier.md", + "demo-investor": GUI / "DEMO-INVESTOR-FA.md", + "readme": GUI / "README-FA.md", + "data-routes": doc_path("05-data-routes-fa.md"), + "feasibility": GUI / "data" / "data-feasibility.html", + "requirement-sheet": GUI / "data" / "data-requirement-sheet.md", + "data-strategy": doc_path("06-data-feasibility-fa.md"), + "blind-sheet": GUI / "data" / "investor-blind-test.html", + "blind-md": GUI / "data" / "investor-blind-test.md", + "blind-sample": GUI / "data" / "investor-blind-test-sample.html", + "ladder": GUI / "data" / "investor-ladder.md", + "ladder-json": GUI / "data" / "investor-ladder.json", + "pledge": GUI / "data" / "investor-pledge.md", + "strategies": GUI / "data" / "strategy-library.html", + "strategies-md": doc_dir("strategies") / "strategy-library-fa.md", + "strategies-index": doc_dir("strategies") / "README-FA.md", + "strategies-refs": doc_dir("strategies") / "references-fa.md", + "stress": GUI / "data" / "edge-stress.html", + "stress-md": GUI / "data" / "edge-stress.md", + "bankroll": GUI / "data" / "bankroll.html", + "bankroll-md": GUI / "data" / "bankroll.md", + "judge": GUI / "data" / "signal-verdict.html", + "judge-md": GUI / "data" / "signal-verdict.md", + "differentiation": doc_path("08-differentiation-and-trust-fa.md"), + "grant-doc": doc_path("09-sell-or-grant-access-fa.md"), + "diagnostic": GUI / "data" / "diagnostic-report.html", + "prospects": GUI / "data" / "prospects-board.html", + "prospects-md": GUI / "data" / "prospects-board.md", + "outreach": GUI / "data" / "outreach-pack.html", + "outreach-md": GUI / "data" / "outreach-pack.md", + "offer": GUI / "data" / "offer-one-pager.html", + "offer-md": GUI / "data" / "offer-one-pager.md", + "onboarding": GUI / "data" / "onboarding-pack.html", + "onboarding-md": GUI / "data" / "onboarding-pack.md", + "sales-today": GUI / "data" / "sales-today.html", + "sales-today-md": GUI / "data" / "sales-today.md", + "review-meeting": GUI / "data" / "review-meeting.html", + "review-meeting-md": GUI / "data" / "review-meeting.md", + "license-doc": GUI / "data" / "license-doc.html", + "license-doc-md": GUI / "data" / "license-doc.md", + "usage": GUI / "data" / "usage-statement.html", + "usage-md": GUI / "data" / "usage-statement.md", + "daily-inputs": doc_path("10-daily-inputs-fa.md"), + "walkthrough": doc_path("13-novice-walkthrough-fa.md"), + "snapshot-template": GUI / "data" / "snapshot-template.json", + "zero-cost": doc_path("07-zero-cost-test-fa.md"), + "witness": GUI / "data" / "witness-live.html", + "witness-md": GUI / "data" / "witness-live.md", +} + + +# ---------------------------------------------------------------- کارهای مشترک +def snapshot_payload(snap) -> dict: + label = snap.source_label + if STATE.get("connection", {}).get("is_mock"): + label = f"{label} · خوراک آزمایشی محلی (ساختگی)" # هرگز دادهٔ ساختگی را واقعی جا نزنیم + return { + "status": snap.status, + "source_label": label, + "freshness": snap.freshness_label, + "rows": len(snap.rows), + "messages": list(snap.messages), + "missing_fields": list(snap.missing_fields), + "mode": snap.mode, + } + + +def build_snapshot_for_state(mode: str | None = None, *, allow_network: bool = True, + live_cfg: dict | None = None): + mode = mode or STATE["mode"] + snap = datafeed.build_snapshot(mode, file_path=STATE.get("file_path") or None, + live_cfg=live_cfg or STATE.get("live_cfg"), key=STATE.get("key"), + allow_network=allow_network) + STATE["snapshot"] = snap + return snap + + +def fresh_live_cfg() -> dict: + """نسخه‌ای از تنظیمات زنده که حافظهٔ نهان را دور می‌زند (برای بازسنجی دفتر).""" + cfg = dict(STATE.get("live_cfg") or {}) + cfg["cache_seconds"] = 0 + return cfg + + +def materialize(snap) -> Path: + rows = [{k: v for k, v in r.items() if not k.startswith("_")} for r in snap.rows] + out = DATA / "current-snapshot.json" + out.parent.mkdir(parents=True, exist_ok=True) + out.write_text(json.dumps({"as_of": time.strftime("%Y-%m-%d %H:%M"), "hurdle": STATE["rules"]["hurdle"], + "capital": STATE["rules"]["capital"], "rows": rows}, + ensure_ascii=False, indent=2), encoding="utf-8") + return out + + +def desk_config() -> dict: + cfg = json.loads(json.dumps(deskmod.DEFAULT_CONFIG, ensure_ascii=False)) + cfg.update(STATE["rules"]) + return cfg + + +def signal_payload(s) -> dict: + return { + "sid": s.sid, "symbol": s.symbol, "kind": s.kind, + "kind_label": deskmod.KIND_LABELS.get(s.kind, s.kind), + "annualized": f"{s.annualized_pct:,.2f}" if isinstance(s.annualized_pct, (int, float)) else "—", + "edge": f"{s.score_pp:,.2f}", "status": s.status, + "status_label": {"pending": "منتظر تأیید", "approved": "تأییدشده", "rejected": "رد شده"}.get(s.status, s.status), + "size": f"{s.contracts:,} {s.unit}", "contracts": s.contracts, "unit": s.unit, + "margin_locked": s.margin_locked, "gate_note": s.gate_note, "alerts": s.alerts, + "detail": {k: v for k, v in s.detail.items() if k != "_policy"}, + "mark": {"pending": "✅", "approved": "🟢", "rejected": "✖"}.get(s.status, "•"), + } + + +def run_scan() -> dict: + snap = STATE.get("snapshot") or build_snapshot_for_state() + if not snap.rows: + return {"error": "هیچ ردیفی برای محاسبه نیست؛ منبع داده را در گام ۲ بررسی کنید."} + path = materialize(snap) + cfg = desk_config() + desk = deskmod.Desk() + kodal_db = STATE["kodal_db"] if STATE.get("use_kodal") else None + sigs = deskmod.scan_market(path, cfg, desk, kodal_db) + STATE["last_sigs"] = sigs + tasks = deskmod.recheck_tasks(cfg, desk, kodal_db, path) if kodal_db else [] + dash = deskmod.build_dashboard(desk, cfg, GUI / "data" / "dashboard.html", tasks) + payloads = [signal_payload(s) for s in sigs] + counts = { + "total": len(payloads), + "pending": len([s for s in sigs if s.status == "pending"]), + "approved": len([s for s in sigs if s.status == "approved"]), + "rejected": len([s for s in sigs if s.status == "rejected"]), + "tasks": len(tasks), + "locked": desk.locked_margin(), + } + return {"signals": payloads, "tasks": tasks, "counts": counts, "dashboard": str(dash), + **snapshot_payload(snap)} + + +def decide(sid: str, action: str, note: str, force: bool = False) -> dict: + desk = deskmod.Desk() + sig = desk.get(sid) + if not sig: + return {"error": "شناسه پیدا نشد."} + if action == "approved": + policy = sig.detail.get("_policy") or {} + cap = float(policy.get("cap_total") or STATE["rules"]["capital"] * STATE["rules"]["max_margin_pct"]) + max_positions = int(policy.get("max_positions") or STATE["rules"]["max_positions"]) + used = desk.locked_margin(exclude_sid=sid) + sig.margin_locked + count = len([s for s in desk.all("approved") if s.sid != sid]) + if (used > cap or count >= max_positions) and not force: + return {"blocked": True, + "message": f"تأیید این سیگنال سقف ریسک را رد می‌کند: سرمایهٔ درگیر {used:,.0f} از سقف {cap:,.0f} ریال · " + f"موقعیت‌های تأییدشده {count} از {max_positions}."} + if force: + note = (note + " | تأیید با رد سقف ریسک").strip(" |") + desk.decide(sid, action, note) + packet = deskmod.order_packet(desk.get(sid)) if action == "approved" else "" + return {"ok": True, "status": action, "packet": packet} + + +def do_backtest(path: str) -> dict: + rules = {k: STATE["rules"][k] for k in ("min_edge_arbitrage_pct", "min_edge_leveraged_pct", + "min_liquidity_contracts_per_day", "max_spread_pct", + "max_plausible_arb_pct", "max_plausible_lev_pct")} + result = bt.run_backtest(path, rules=rules, capital=float(STATE["rules"]["capital"])) + bt.build_report(result, GUI / "data" / "backtest.html") + bt.write_csv(result, GUI / "data" / "backtest.csv") + STATE["backtest_result"] = result + return {"summary": result["summary"], "problems": result["summary"].get("problems", []), + "file": str(path), + "by_kind": {k: {kk: vv for kk, vv in v.items() if kk != "realized" and kk != "expected"} + for k, v in result["by_kind"].items()}} + + +def do_bundle() -> dict: + snap = STATE.get("snapshot") or build_snapshot_for_state() + state = {"data_mode": STATE["mode"], "snapshot": snap, "rules": STATE["rules"], + "backtest_result": STATE.get("backtest_result")} + out = st.build_bundle(state) + STATE["bundle_dir"] = out + files = [] + for f in sorted(Path(out).iterdir()): + files.append({"file": f.name, "desc": _describe(f.name), "size": f.stat().st_size}) + return {"path": str(out), "files": files} + + +def _describe(name: str) -> str: + table = { + "01-dashboard.html": "داشبورد تصمیم‌ها (تأیید، رد، منتظر تأیید)", + "02-signals.csv": "فهرست کامل سیگنال‌ها با دلیل دروازه‌ها", + "03-method.html": "سند روش کار و چک‌لیست راستی‌آزمایی شرکت", + "04-packets.txt": "بستهٔ سفارش سیگنال‌های تأییدشده و منتظر تأیید", + "05-backtest.html": "گزارش پس‌آزمایی روی دادهٔ تاریخ", + "06-backtest-rows.csv": "سطر به سطر نتیجهٔ پس‌آزمایی", + "07-manifest.json": "شناسنامهٔ فنی بسته (نسخه‌ها، پارامترها، شمارش‌ها)", + "README-FA.md": "چک‌لیست راستی‌آزمایی برای شرکت", + } + return table.get(name, "پروندهٔ همراه بسته") + + +# ---------------------------------------------------------------- کارساز + +def _allowed_roots() -> list[Path]: + """پوشه‌هایی که سرو کردن پرونده از آن‌ها مجاز است (هر چیز دیگر = ۴۰۳).""" + # سندهای تحلیلی کنار خودِ ایستگاه می‌نشینند (پوشهٔ money) و باید سرو شوند؛ + # نام پرونده پیش‌تر پاک‌سازی می‌شود، پس از این پوشه‌ها هم چیزی بیرون نمی‌رود. + roots = [WEB, GUI / "data", GUI / "demo", GUI / "docs", GUI.parent] + bundle = (STATE.get("bundle_dir") if isinstance(STATE, dict) else None) + if bundle: + roots.append(Path(bundle)) + return roots + + +def _inside_allowed(path: Path) -> bool: + try: + target = Path(path).resolve() + except OSError: + return False + for root in _allowed_roots(): + try: + if target.is_relative_to(Path(root).resolve()): + return True + except (OSError, ValueError): + continue + return False + + +def _safe_output_name(raw: str) -> str | None: + """نام پروندهٔ خروجی را پاک می‌کند؛ هر چیز مشکوک (اسلش، بازگشت به عقب، نویسهٔ صفر) رد می‌شود.""" + name = str(raw or "").strip().strip("\x00") + if not name or "/" in name or "\\" in name or ".." in name or name.startswith("."): + return None + if len(name) > 120 or any(c in name for c in ("\n", "\r", "\t")): + return None + return name + + +def _meter(kind: str, label: str = "") -> None: + """یک کار را در «دفتر استفاده» ثبت می‌کند؛ در برابر هر خطا ساکت است تا کار اصلی نشکند.""" + try: + usagemod.record_event(kind, label=label) + except Exception: + pass + +MAX_BODY_BYTES = 2 * 1024 * 1024 # سقف بدنهٔ درخواست: ۲ مگابایت (ضد پرکردن حافظه) +CSP = ("default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; " + "script-src 'self' 'unsafe-inline'; connect-src 'self'; frame-ancestors 'none'; " + "form-action 'self'; base-uri 'none'") +TRUST_PROXY = str(os.environ.get("STATION_TRUST_PROXY") or "").strip() in ("1", "true", "yes") + +# میزبان‌هایی که درخواستشان «همان برنامه» حساب می‌شود (وقتی پروکسی، هدر Host را عوض می‌کند). +# پیش‌فرض خالی است؛ روی میزبان ابری مثل Hugging Face، نام Space اینجا گذاشته می‌شود. +ALLOW_HOSTS = tuple(h.strip().lower() for h in + str(os.environ.get("STATION_ALLOW_HOSTS") or "").split(",") if h.strip()) + + +class Handler(BaseHTTPRequestHandler): + server_version = f"IranDeskStation/{VERSION}" + + def log_message(self, fmt, *args): # ساکت کردن لاگ پیش‌فرض + return + + # ---------- کمکی‌های امنیتی + def _client_ip(self) -> str: + """نشانی برای قفل تلاش‌های ناموفق. + + پیش‌فرض: نشانی واقعی سوکت (هدرها را باور نمی‌کنیم). اگر STATION_TRUST_PROXY=1 باشد و + درخواست از پروکسی (تونل/بازکنندهٔ HTTPS) بیاید، نشانی کاربر از هدر خوانده می‌شود تا + خطای یک نفر، بقیه را قفل نکند. + """ + if TRUST_PROXY: + for key in ("CF-Connecting-IP", "X-Real-IP", "X-Forwarded-For"): + val = str(self.headers.get(key) or "").split(",")[0].strip() + if val: + return val + return str(self.client_address[0]) + + def _secure_cookie(self) -> bool: + """اگر درخواست از مسیر HTTPS آمده، کوکی Secure هم بشود.""" + proto = str(self.headers.get("X-Forwarded-Proto") or "").split(",")[0].strip().lower() + if not proto: + visitor = str(self.headers.get("CF-Visitor") or "") + proto = "https" if '"https"' in visitor else "" + return proto == "https" + + def _guard(self, method: str, run) -> None: + """هر خطای پیش‌بینی‌نشده را به پاسخ ۵۰۰ خوانا تبدیل می‌کند. + + چرا: پیش‌تر اگر وسط یک درخواست خطایی رخ می‌داد، کارساز بدون پاسخ اتصال را می‌بست و + کلاینت فقط «اتصال قطع شد» می‌دید (روی میزبان ابری همین اتفاق افتاد و ریشه‌یابی را سخت + کرد). حالا هم پیام روشن برمی‌گردد، هم ردِ خطا در گزارش می‌ماند. + """ + try: + run() + except (BrokenPipeError, ConnectionResetError): + pass # کلاینت خودش رفت؛ کاری لازم نیست + except Exception as e: # noqa: BLE001 — نگهبانِ آخر + tb = traceback.format_exc(limit=6) + print(f"[{method}] خطای پیش‌بینی‌نشده: {e}\n{tb}", flush=True) + try: + self._json({"error": f"خطای داخلی برنامه: {type(e).__name__} — {str(e)[:200]}", + "path": self.path, "kind": "internal_error"}, 500) + except Exception: + pass + + def _reject_method(self) -> None: + self._send(405, '{"error": "این روش درخواست پشتیبانی نمی‌شود."}'.encode("utf-8"), + headers={"Allow": "GET, POST"}) + + do_PUT = do_DELETE = do_PATCH = do_TRACE = _reject_method + + def do_OPTIONS(self): + self._send(204, b"", headers={"Allow": "GET, POST"}) + + # ---------- کمکی‌ها + def _send(self, code: int, body: bytes, ctype: str = "application/json; charset=utf-8", + headers: dict | None = None) -> None: + self.send_response(code) + self.send_header("Content-Type", ctype) + self.send_header("Content-Length", str(len(body))) + self.send_header("Cache-Control", "no-store") + # سرآیندهای امنیتی: برنامه در قاب سایت دیگری جا نگیرد، مرورگر محتوا را جور دیگری + # تفسیر نکند، و موتور جست‌وجو ایندکسش نکند. + self.send_header("X-Content-Type-Options", "nosniff") + self.send_header("X-Frame-Options", "DENY") + self.send_header("Referrer-Policy", "no-referrer") + self.send_header("X-Robots-Tag", "noindex, nofollow, noarchive") + self.send_header("Permissions-Policy", "geolocation=(), microphone=(), camera=()") + if ctype.startswith("text/html"): + self.send_header("Content-Security-Policy", CSP) + for k, v in (headers or {}).items(): + self.send_header(k, v) + self.end_headers() + try: + self.wfile.write(body) + except BrokenPipeError: + pass + + # ---------- دروازهٔ ورود (مدیر / مهمان) + LOGIN_OPEN = ("/login", "/login.html", "/guide", "/guide.html", "/api/login", + "/api/gate/status", "/favicon.ico", "/api/admin/login") +# «/api/admin/login» عمداً باز است: رمز پنل همان رمز مدیر دروازه است و خودش قفل تلاش و +# محدودیت دارد؛ باز بودنش فقط یک ورودِ اضافی را حذف می‌کند، نه یک درِ تازه باز می‌کند. + + def _cookies(self) -> dict: + out: dict[str, str] = {} + for part in str(self.headers.get("Cookie") or "").split(";"): + if "=" in part: + k, v = part.split("=", 1) + out[k.strip()] = v.strip() + return out + + def _drain_body(self, limit: int = 32 * 1024 * 1024) -> None: + """بدنهٔ رهاشده را تکه‌تکه می‌خواند و دور می‌ریزد تا پاسخ ما به دست کاربر برسد.""" + try: + left = min(int(self.headers.get("Content-Length", 0) or 0), limit) + except ValueError: + left = 0 + while left > 0: + chunk = self.rfile.read(min(65536, left)) + if not chunk: + break + left -= len(chunk) + self.close_connection = True + + def _csrf_ok(self) -> bool: + """اگر مرورگر مبدأ بفرستد، باید همان میزبان ما باشد (ضد CSRF).""" + origin = str(self.headers.get("Origin") or "").strip() + if not origin or origin == "null": + return True + try: + netloc = urlparse(origin).netloc + except ValueError: + return False + host = str(self.headers.get("Host") or "").strip().lower() + if netloc == host: + return True + # پشت پروکسی میزبان ابری، هدر Host ممکن است نام داخلی باشد؛ پس نام عمومی Space را هم + # می‌پذیریم — ولی فقط همان نام‌هایی که خودمان در محیط گذاشته‌ایم (بدون الگوی عام). + return netloc in ALLOW_HOSTS + + def _gate_token(self) -> str | None: + return self._cookies().get(gatemod.COOKIE) or None + + def _role(self) -> str | None: + return gatemod.role_of(self._gate_token()) + + def _role_id(self) -> str: + return (gatemod.who(self._gate_token()) or {}).get("id") or "—" + + @staticmethod + def _guest_blocked(path: str) -> bool: + """چیزهایی که مهمان/کارفرما نباید ببیند: پنل مدیریت، صدور مجوز، دروازه، خاموشی.""" + return (path == "/admin" or path.startswith("/admin") or path.startswith("/api/admin") + or path.startswith("/api/license") or path in ("/api/shutdown", "/api/gate/update")) + + def _gate_guard(self, path: str) -> bool: + """True = بگذر. اگر پاسخ داده شد (۴۰۱/۴۰۳/ریدایرکت)، False.""" + if not gatemod.enabled() or path in self.LOGIN_OPEN: + return True + role = self._role() + if role is None: + if path.startswith(("/api/", "/files/")): + self._json({"error": "برای دیدن برنامه اول وارد شوید.", "login_required": True}, 401) + else: + self._send(302, b"", "text/plain; charset=utf-8", + headers={"Location": "/login?next=" + quote(path)}) + return False + if role == "guest" and self._guest_blocked(path): + if path.startswith(("/api/", "/files/")): + self._json({"error": "این بخش فقط با حساب مدیر باز می‌شود.", + "guest_blocked": True}, 403) + else: + body = ("" + "" + "فقط با حساب مدیر" + "" + "
    " + "

    این بخش فقط با حساب مدیر باز می‌شود

    " + "

    این بخش برای صدور " + "اجازه‌نامه، عوض‌کردن رمزها و خاموش‌کردن برنامه است. حساب کارفرما (مهمان) به آن " + "دسترسی ندارد؛ باقی برنامه و همهٔ خروجی‌ها باز است.

    " + "بازگشت به برنامه" + "
    ") + self._send(403, body.encode("utf-8"), "text/html; charset=utf-8") + return False + return True + + def _token(self, body: dict | None = None) -> str: + """توکن پنل را از سرآیند، پارامتر نشانی یا بدنهٔ درخواست می‌خواند.""" + head = str(self.headers.get("X-Admin-Token") or "").strip() + if head: + return head + q = parse_qs(urlparse(self.path).query) + if (q.get("token") or [""])[0]: + return str((q.get("token") or [""])[0]) + return str((body or {}).get("token") or "").strip() + + def _json(self, payload: dict, code: int = 200, headers: dict | None = None) -> None: + self._send(code, json.dumps(payload, ensure_ascii=False).encode("utf-8"), headers=headers) + + def _read_json(self) -> dict: + length = int(self.headers.get("Content-Length", 0) or 0) + if not length: + return {} + if length > MAX_BODY_BYTES: + raise ValueError(f"بدنهٔ درخواست بسیار بزرگ است ({length} بایت).") + raw = self.rfile.read(length) + try: + return json.loads(raw.decode("utf-8")) + except json.JSONDecodeError: + return {} + + def _serve_file(self, path: Path) -> None: + # لایهٔ دوم نگهبانی: مسیر نهایی باید داخل پوشه‌های مجاز باشد + if not _inside_allowed(path): + return self._json({"error": "دسترسی به این مسیر مجاز نیست."}, 403) + if not path.exists(): + self._json({"error": f"پرونده پیدا نشد: {path}"}, 404) + return + ctype = mimetypes.guess_type(str(path))[0] or "application/octet-stream" + if path.suffix == ".html": + ctype = "text/html; charset=utf-8" + elif path.suffix == ".json": + ctype = "application/json; charset=utf-8" + elif path.suffix in (".md", ".csv", ".txt"): + ctype = "text/plain; charset=utf-8" + self._send(200, path.read_bytes(), ctype) + + # ---------- مسیرها + def do_GET(self): + return self._guard("GET", self._do_get) + + def _do_get(self): + u = urlparse(self.path) + q = parse_qs(u.query) + if not self._gate_guard(u.path): + return + + if u.path in ("/login", "/login.html"): + return self._serve_file(WEB / "login.html") + if u.path in ("/guide", "/guide.html"): + # راهنمای کارفرما: پیش از ورود هم باز است تا کسی بی‌راهنما نماند + return self._serve_file(WEB / "guide.html") + if u.path in ("/api/state/info", "/api/admin/state"): + if not admauth.check_token(self._token()): + return self._json({"error": "این بخش فقط با ورود به پنل مدیریت در دسترس است.", + "needs_admin": True}, 403) + sk = state_keeper() + return self._json(sk.info() if sk else OFFLINE_STATE) + + if u.path == "/api/gate/status": + s = gatemod.status() + role = self._role() + # شناسه‌ها و فهرست کاربران فقط برای مدیر؛ بیرون از ورود، حداقل اطلاعات + payload = {"enabled": s["enabled"], "logged_in": role is not None, "role": role, + "id": self._role_id() if role else "—", "rule": s["rule"], + "ttl_hours": s["ttl_hours"], "open_sessions": s["open_sessions"]} + if role == "admin": + payload.update({"guest": s["accounts"]["guest"], "admin": s["accounts"]["admin"], + "users": s["users"]}) + return self._json(payload) + + if u.path in ("/", "/index.html"): + return self._serve_file(WEB / "index.html") + if u.path == "/app.js": + return self._serve_file(WEB / "app.js") + if u.path in ("/admin", "/admin.html"): + return self._serve_file(WEB / "admin.html") + if u.path == "/admin.js": + return self._serve_file(WEB / "admin.js") + if u.path == "/favicon.ico": + return self._send(204, b"") + + if u.path == "/api/health": + # «بررسی سلامت» به پنل مدیریت منتقل شده است؛ خواندنش هم با توکن ورود می‌شود. + if not admauth.check_token(self._token()): + return self._json({"error": "بررسی سلامت به پنل مدیریت منتقل شده است؛ از /admin وارد شوید.", + "needs_admin": True}, 403) + ok, items = st.health_report() + return self._json({"items": [{"name": n, "ok": f, "note": r} for n, f, r in items], + "passed": len([1 for _, f, _ in items if f]), "total": len(items), + "ok": ok, "version": VERSION}) + + if u.path == "/api/state": + return self._json({"rules": STATE["rules"], "mode": STATE["mode"], + "file_path": STATE.get("file_path"), "kodal_db": STATE["kodal_db"], + "use_kodal": STATE["use_kodal"], "connection": STATE["connection"]}) + + if u.path == "/api/data-guide": + return self._json({ + "rows": [list(r) for r in st.API_GUIDE_ROWS], + "snapshot_template": STATE.get("file_path") or str(DESK_DIR / "market-demo.json"), + "history_template": str(GUI / "demo" / "history-demo.csv"), + "kodal_db": STATE["kodal_db"], + }) + + if u.path == "/api/mode-info": + mode = (q.get("mode") or ["sim"])[0] + card = datafeed.SOURCE_CARDS.get(mode, {}) + return self._json({"mode": mode, **{k: card.get(k, "") for k in ("label", "cost", "gives", "after", "how")}}) + + if u.path == "/api/snapshot/rows": + path = STATE.get("file_path") or str(DESK_DIR / "market-demo.json") + data = datafeed.load_snapshot_rows(path) + data["mode"] = STATE["mode"] + data["dir"] = str(GUI / "data" / "snapshots") + data["last_dated"] = sorted([f.name for f in (GUI / "data" / "snapshots").glob("snapshot-*.json")])[-3:] \ + if (GUI / "data" / "snapshots").exists() else [] + return self._json(data) + + if u.path == "/api/connections": + return self._json(connection_payload()) + + if u.path == "/api/trial": + return self._json(trial_payload()) + + if u.path == "/api/signals": + db = deskmod.Desk() + return self._json({"signals": [signal_payload(s) for s in db.all(limit=300)]}) + + if u.path == "/api/alerts": + dbs = (q.get("db") or [STATE["kodal_db"]])[0] + return self._json({"items": datafeed.read_alerts(dbs, 55, 30)}) + + if u.path.startswith("/files/"): + name = _safe_output_name(u.path[len("/files/"):]) + if name is None: + return self._json({"error": "نام پروندهٔ نامعتبر."}, 400) + if name in ("method", "03-method.html"): + # سند روش کار از وضعیت همین لحظه ساخته می‌شود تا دکمهٔ «نمایش سند روش کار» خالی نماند + target = GUI / "data" / "method-preview.html" + try: + rk_write = st.build_method_html(STATE) + except Exception as e: # نباید پنهان بماند + return self._json({"error": f"ساخت سند روش کار ناموفق: {type(e).__name__}: {e}"}, 500) + target.parent.mkdir(parents=True, exist_ok=True) + target.write_text(rk_write, encoding="utf-8") + return self._serve_file(target) + if name in ADMIN_FILE_KEYS and not admauth.check_token(self._token()): + return self._json({"error": "این پرونده از پنل مدیریت است؛ اول وارد شوید.", + "needs_admin": True}, 403) + if name in SERVED_FILES: + target = SERVED_FILES[name] or (Path(STATE["bundle_dir"]) / name if STATE.get("bundle_dir") else None) + if target: + return self._serve_file(Path(target)) + if STATE.get("bundle_dir"): + cand = Path(STATE["bundle_dir"]) / name + if cand.exists(): + return self._serve_file(cand) + return self._json({"error": "پروندهٔ خواسته‌شده ساخته نشده است."}, 404) + + return self._json({"error": "مسیر ناشناخته"}, 404) + + def do_POST(self): + return self._guard("POST", self._do_post) + + def _do_post(self): + u = urlparse(self.path) + try: + body = self._read_json() + except ValueError as e: # بدنهٔ بزرگ یا خراب + self._drain_body() # بقیهٔ بدنه را بی‌آنکه نگه داریم می‌خوانیم + return self._json({"error": str(e)}, 413, headers={"Connection": "close"}) + if not self._csrf_ok(): # درخواست از سایت دیگر + return self._json({"error": "این درخواست از جای دیگری آمده و پذیرفته نمی‌شود."}, 403) + if not self._gate_guard(u.path): + return + + # --- دروازه: ورود، خروج، مدیریت دسترسی، خاموشی --- + if u.path == "/api/login": + out = gatemod.login(str((body or {}).get("id") or ""), + str((body or {}).get("pass") or ""), + ip=self._client_ip()) + if not out.get("ok"): + return self._json(out, 401) + cookie = (f"{gatemod.COOKIE}={out['token']}; Path=/; HttpOnly; SameSite=Lax; " + f"Max-Age={gatemod.TTL_SECONDS}" + ("; Secure" if self._secure_cookie() else "")) + return self._json({"ok": True, "role": out["role"], "id": out["id"], + "expires_in_minutes": out["expires_in_minutes"]}, + headers={"Set-Cookie": cookie}) + if u.path == "/api/logout": + closed = gatemod.logout(self._gate_token()) + return self._json({"ok": True, "closed": closed}, + headers={"Set-Cookie": f"{gatemod.COOKIE}=; Path=/; Max-Age=0" + + ("; Secure" if self._secure_cookie() else "")}) + if u.path == "/api/gate/update": + if self._role() != "admin": + return self._json({"error": "این کار فقط با حساب مدیر.", "guest_blocked": True}, 403) + action = str((body or {}).get("action") or "") + try: + if action == "gate-on": + gatemod.set_enabled(True); note = "دروازه روشن شد." + elif action == "gate-off": + gatemod.set_enabled(False); note = "دروازه خاموش شد: همین رایانه = مدیر." + elif action == "guest-on": + gatemod.set_enabled_account("guest", True); note = "دسترسی مهمان روشن شد." + elif action == "guest-off": + gatemod.set_enabled_account("guest", False) + note = "دسترسی مهمان قطع شد؛ نشست باز او هم بسته شد." + elif action == "close-guest-sessions": + n = gatemod.close_sessions("guest") + note = f"{n} نشست مهمان بسته شد." + elif action == "set-guest": + gatemod.set_account("guest", str((body or {}).get("id") or ""), + str((body or {}).get("pass") or "")) + note = "شناسه و رمز مهمان عوض شد." + elif action == "user-add": + u = gatemod.add_user(str((body or {}).get("id") or ""), + str((body or {}).get("pass") or ""), + note=str((body or {}).get("note") or "")) + note = (f"کاربر «{u['id']}» ساخته شد؛ با همین شناسه و رمز وارد می‌شود " + "(فقط هش روی دیسک می‌ماند).") + elif action in ("user-del", "user-delete"): + out = gatemod.delete_user(str((body or {}).get("id") or "")) + note = (f"کاربر «{out['id']}» کامل حذف شد؛ {out['closed']} نشست بازش هم " + f"بسته شد. {out['left']} کاربر دیگر مانده.") + elif action == "user-on": + u = gatemod.set_user_enabled(str((body or {}).get("id") or ""), True) + note = f"دسترسی «{u['id']}» وصل شد." + elif action == "user-off": + u = gatemod.set_user_enabled(str((body or {}).get("id") or ""), False) + note = (f"دسترسی «{u['id']}» قطع شد؛ {u['closed']} نشست بازش هم بسته شد.") + elif action == "set-admin": + gatemod.set_account("admin", str((body or {}).get("id") or ""), + str((body or {}).get("pass") or "")) + note = "شناسه و رمز مدیر عوض شد." + else: + return self._json({"error": f"کار ناشناخته: {action or '—'}"}, 400) + except ValueError as e: + return self._json({"error": str(e)}, 400) + s = gatemod.status() + return self._json({"ok": True, "note": note, "enabled": s["enabled"], + "guest": s["accounts"]["guest"], "admin": s["accounts"]["admin"], + "users": s["users"]}) + if u.path == "/api/shutdown": + if self._role() != "admin": + return self._json({"error": "خاموش کردن برنامه فقط با حساب مدیر.", + "guest_blocked": True}, 403) + if (body or {}).get("dry"): + return self._json({"ok": True, "would_stop": True, + "note": "بررسی خشک: هیچ‌چیز خاموش نشد."}) + if not (body or {}).get("confirm"): + return self._json({"error": "برای خاموش کردن، confirm بفرستید."}, 400) + + def _stop(): + try: + self.server.shutdown() + finally: + time.sleep(0.4) + os._exit(0) # خوراک آزمایشی و هر رشتهٔ دیگری هم می‌رود + + threading.Timer(0.7, _stop).start() + return self._json({"ok": True, "note": "برنامه خاموش می‌شود؛ برای روشن کردن دوباره، " + "همان run-gui را بزنید."}) + + # --- پنل مدیریت: ورود، خروج، و نگهبانیِ سه بخش منتقل‌شده --- + if u.path == "/api/admin/login": + out = admauth.login(str((body or {}).get("id") or ""), + str((body or {}).get("pass") or ""), + ip=self._client_ip()) + return self._json(out, 200 if out.get("ok") else 401) + if u.path == "/api/admin/whoami": + ok = admauth.check_token(self._token(body)) + return self._json({"ok": ok, "error": "" if ok else "توکن نامعتبر یا منقضی است."}, + 200 if ok else 401) + if u.path == "/api/admin/logout": + admauth.revoke_token(self._token(body)) + return self._json({"ok": True}) + if u.path in ADMIN_MAP: + if not admauth.check_token(self._token(body)): + return self._json({"error": "این بخش فقط با ورود به پنل مدیریت در دسترس است.", + "needs_admin": True}, 403) + if u.path == "/api/admin/health": + ok, items = st.health_report() + return self._json({"items": [{"name": n, "ok": f, "note": r} for n, f, r in items], + "passed": len([1 for _, f, _ in items if f]), "total": len(items), + "ok": ok, "version": VERSION}) + u = u._replace(path=ADMIN_MAP[u.path]) + elif u.path in ADMIN_ENDPOINTS and not admauth.check_token(self._token(body)): + return self._json({"error": "این بخش به پنل مدیریت منتقل شده است؛ از /admin وارد شوید.", + "needs_admin": True}, 403) + + if u.path == "/api/state/info": + sk = state_keeper() + return self._json(sk.info() if sk else OFFLINE_STATE) + if u.path == "/api/state/backup": + sk = state_keeper() + if not sk: + return self._json({**OFFLINE_STATE, "ok": False}) + return self._json(sk.backup_now("درخواست مدیر از پنل")) + + if u.path == "/api/autoconnect": + rep = autoconn.autoconnect( + symbol=str(body.get("symbol") or "اهرم"), + timeout=float(body.get("timeout") or 10.0), + allow_network=not bool(body.get("offline")), + save=bool(body.get("save"))) + if rep.get("saved"): + active = conn.apply_profile(conn.load_store(), rep["saved"]["name"]) + STATE["live_cfg"] = active["live_cfg"] + if active["key"]: + STATE["key"] = active["key"] + STATE["mode"] = "live" + STATE["connection"] = {"name": active["name"], "label": active["profile"]["label"], + "key_where": active["key_where"], "is_mock": active["is_mock"]} + rep["active"] = STATE["connection"] + cand = next((c for c in autoconn.CANDIDATES if c["name"] == rep["saved"]["name"]), {}) + if cand.get("needs_code"): + snap_data = datafeed.load_snapshot_rows(STATE.get("file_path") or "") + if snap_data.get("rows"): + rows, notes = autoconn.enrich_snapshot_with_codes( + snap_data["rows"], cand, timeout=float(body.get("timeout") or 10.0)) + if any(r.get("feed_symbol") for r in rows): + out = datafeed.save_dated_snapshot(rows, note="کد نمادها خودکار پر شد") + STATE["file_path"] = str(out) + STATE["mode"] = "live" + rep["codes_file"] = str(out) + rep["code_notes"] = notes + rep["connections"] = connection_payload() + return self._json(rep, 200 if rep.get("ok") else 200) + + if u.path == "/api/snapshot/import": + _meter("import", "ورود اعداد از متن کارگزاری") + text = str((body or {}).get("text") or "") + res = snapimp.parse_paste(text, toman_to_rial=bool((body or {}).get("toman")), + default_kind=(str((body or {}).get("kind") or "").strip() or None)) + if res.get("rows"): + clean, problems = datafeed.clean_rows(res["rows"]) + res["rows"] = clean + res["problems"] = list(res.get("problems") or []) + list(problems) + res["count"] = len(clean) + res["ok"] = bool(clean) + return self._json(res) + + if u.path == "/api/snapshot/save": + _meter("snapshot", "ذخیرهٔ اسنپ‌شات تاریخ‌دار") + if not body.get("confirm_real"): + return self._json({"error": "برای ذخیره، تیک «این اعداد را خودم از سامانهٔ کارگزاری برداشتم» " + "را بزنید. بدون آن، این پرونده روز «واقعی» حساب نمی‌شود."}, 400) + rows = body.get("rows") or [] + clean, problems = datafeed.clean_rows(rows) + if not clean: + return self._json({"error": "هیچ ردیف درستی وارد نشد.", "problems": problems}, 400) + path = datafeed.save_dated_snapshot( + clean, as_of=body.get("as_of") or None, + hurdle=float(body.get("hurdle") or STATE["rules"]["hurdle"]), + capital=float(body.get("capital") or STATE["rules"]["capital"]), + note=str(body.get("note") or "")) + STATE["file_path"] = str(path) + STATE["mode"] = "file" + snap = build_snapshot_for_state("file", allow_network=False) + return self._json({"ok": True, "path": str(path), "problems": problems, + "rows": len(clean), + "checklist": ["عکس صفحهٔ سامانهٔ کارگزاری را هم برای همین تاریخ نگه دارید", + "وجه تضمین هر قرارداد را از سامانه بردارید، نه از حافظه", + "این پرونده با تاریخ ذخیره شد و روز «واقعی» حساب می‌شود"], + "snapshot": snapshot_payload(snap)}) + + if u.path == "/api/connections/save": + store = conn.load_store() + prof = conn.upsert_profile(store, body.get("profile") or {}) + if body.get("select", True): + conn.select_profile(store, prof["name"]) + conn.save_store(store) + key = str(body.get("key") or "") + if body.get("save_key"): + conn.save_key(prof["name"], key) + elif key: + pass # کلید فقط در حافظه می‌ماند + active = conn.apply_profile(conn.load_store(), prof["name"], inline_key=key) + STATE["live_cfg"] = active["live_cfg"] + if active["key"]: + STATE["key"] = active["key"] + STATE["connection"] = {"name": prof["name"], "label": prof["label"], + "key_where": active["key_where"], "is_mock": active["is_mock"]} + return self._json({"ok": True, "profile": prof, "active": STATE["connection"], + "keys_stored": bool(conn.load_keys()), + "saved_to": str(conn.PROFILES_FILE)}) + + if u.path == "/api/connections/select": + store = conn.load_store() + name = str(body.get("name") or "") + if conn.find_profile(store, name) is None: + return self._json({"error": "پروفایل پیدا نشد."}, 404) + conn.select_profile(store, name) + conn.save_store(store) + active = conn.apply_profile(conn.load_store(), name, inline_key=str(body.get("key") or "")) + STATE["live_cfg"] = active["live_cfg"] + if active["key"]: + STATE["key"] = active["key"] + STATE["mode"] = "live" + STATE["connection"] = {"name": active["name"], "label": active["profile"]["label"], + "key_where": active["key_where"], "is_mock": active["is_mock"]} + return self._json({"ok": True, "active": STATE["connection"], "live_cfg": STATE["live_cfg"], + "is_mock": active["is_mock"]}) + + if u.path == "/api/connections/delete": + store = conn.load_store() + name = str(body.get("name") or "") + if name in ("mock-local", "custom") and conn.find_profile(store, name): + return self._json({"error": "این دو پروفایل پایه‌اند و پاک نمی‌شوند."}, 400) + gone = conn.delete_profile(store, name) + conn.save_store(store) + conn.save_key(name, "") # کلید ذخیره‌شدهٔ آن هم پاک شود + return self._json({"ok": True, "deleted": gone, "selected": conn.load_store().get("selected")}) + + if u.path == "/api/connections/key": + name = str(body.get("name") or STATE["connection"].get("name") or "") + key = str(body.get("key") or "") + if not name: + return self._json({"error": "اول یک پروفایل انتخاب کنید."}, 400) + if body.get("save"): + conn.save_key(name, key) + STATE["key"] = key + return self._json({"ok": True, "saved": bool(body.get("save")), + "key_status": conn.key_status(name)}) + + if u.path == "/api/peek": + return self._json(peek_payload(body)) + + if u.path == "/api/trial/record": + sigs = STATE.get("last_sigs") or [] + if not sigs: + return self._json({"error": "اول گام ۵ (اجرا و محاسبه) را بزنید تا سیگنالی برای ثبت باشد."}, 400) + wanted = body.get("sids") or [] + if wanted: + sigs = [x for x in sigs if getattr(x, "sid", "") in set(wanted)] + t = trial.Trial(STATE["trial_db"]) + snap = STATE.get("snapshot") + label = getattr(snap, "source_label", "") if snap else "" + saved = t.record_from_signals(sigs, source_label=str(label), + mode=STATE.get("mode", ""), + add_span=float(body.get("add_span") or 0.0)) + return self._json({"ok": True, "saved": len(saved), + "skipped": len(sigs) - len(saved), + "trial": trial_payload()}) + + if u.path == "/api/sources/feasibility": + fixture = bool(body.get("fixture")) + httpd = None + host = "" + try: + if fixture: + httpd, host = sourcesmod.start_fixture() + result = sourcesmod.probe_all( + symbol=str(body.get("symbol") or "فولاد"), + host=host, + timeout=float(body.get("timeout") or 8.0), + with_stability=not bool(body.get("no_stability")), + code=str(body.get("code") or "")) + result["fixture"] = fixture + ws = sourcesmod.probe_ws(str(body["ws_url"]), timeout=float(body.get("timeout") or 8.0)) \ + if body.get("ws_url") else None + report = sourcesmod.build_report(result, sourcesmod.build_matrix(), ws) + finally: + if httpd: + httpd.shutdown() + return self._json({"ok": True, **result, "ws": ws, "matrix": sourcesmod.build_matrix(), + "report": str(report), "needs": sourcesmod.NEEDS}) + + if u.path == "/api/sources/sheet": + out = GUI / "data" / "data-requirement-sheet.md" + out.parent.mkdir(parents=True, exist_ok=True) + out.write_text(sourcesmod.requirement_sheet(), encoding="utf-8") + return self._json({"ok": True, "path": str(out)}) + + if u.path == "/api/license": + action = str((body or {}).get("action") or "status") + if action == "grant": + months = int((body or {}).get("months") or 12) + row = licmod.make_license(str((body or {}).get("client") or "بدون نام"), + months=months, + contact=str((body or {}).get("contact") or ""), + note=str((body or {}).get("note") or "")) + path = licmod.write_license(row) + _meter("license", f"صدور مجوز دسترسی: {months} ماه") + return self._json({"ok": True, "license": row, "path": str(path), + "status": licmod.verify(row), "ladder": licmod.ladder()}) + if action == "document": + try: + h, m = licmod.build_document() + except (OSError, ValueError) as e: + return self._json({"error": f"ساخت سند ناموفق: {e}"}, 500) + _meter("license", "سند چاپی اجازه‌نامه") + return self._json({"ok": True, "html": str(h), "md": str(m), + "status": licmod.verify()}) + + if action == "trial": + row = licmod.make_trial(str((body or {}).get("client") or "آزمون ارزیابی")) + path = licmod.write_license(row) + _meter("license", "صدور مجوز آزمون ارزیابی") + return self._json({"ok": True, "license": row, "path": str(path), + "status": licmod.verify(row)}) + if action == "revoke": + p = Path(licmod.LICENSE_FILE) + if p.exists(): + p.unlink() + _meter("license", "باطل‌کردن مجوز") + return self._json({"ok": True, "status": licmod.verify(None)}) + return self._json({"ok": True, "status": licmod.verify(), + "license": licmod.read_license(), "ladder": licmod.ladder()}) + + if u.path == "/api/prospects": + action = str((body or {}).get("action") or "list") + name = str((body or {}).get("name") or "").strip() + when = str((body or {}).get("date") or "") or None + if action == "add": + try: + out = prospectsmod.add(name, kind=str((body or {}).get("kind") or "company"), + channel=str((body or {}).get("channel") or "telegram"), + note=str((body or {}).get("note") or ""), when=when) + except ValueError as e: + return self._json({"error": str(e)}, 400) + if out.get("ok"): + _meter("prospect", f"مخاطب تازه: {name}") + elif action in ("sent", "followup", "reply", "meeting", "outcome"): + out = prospectsmod.mark(name, action, when=when, + note=str((body or {}).get("note") or ""), + result=str((body or {}).get("result") or "")) + if out.get("ok"): + _meter("prospect", f"{action}: {name}") + elif action == "close": + out = prospectsmod.close(name) + elif action == "sheet": + h, m = prospectsmod.build_sheet() + _meter("prospect", "برگهٔ تابلوی پیگیری") + return self._json({"ok": True, "html": str(h), "md": str(m), + "week": prospectsmod.week_numbers(), + "todo": prospectsmod.todo()}) + else: + out = {"ok": True} + if not out.get("ok"): + return self._json({"error": out.get("detail") or "انجام نشد.", "row": out.get("row")}, 400) + rows = prospectsmod.load() + return self._json({"ok": True, "row": out.get("row"), "prospects": rows, + "todo": prospectsmod.todo(rows), + "week": prospectsmod.week_numbers(rows)}) + + if u.path == "/api/outreach": + client = str((body or {}).get("client") or "") + kind = str((body or {}).get("kind") or "company") + if kind not in outreachmod.KINDS: + kind = "company" + h, m = outreachmod.build_pack(client, kind=kind) + _meter("outreach", f"پیام معرفی برای {client or 'بدون نام'} ({kind})") + return self._json({"ok": True, "html": str(h), "md": str(m), "kind": kind, + "kind_label": outreachmod.KINDS[kind], + "rules": len(outreachmod.messages(client, kind=kind)["rules"])}) + + if u.path == "/api/offer": + client = str((body or {}).get("client") or "") + try: + monthly = int((body or {}).get("monthly") or 0) + setup = int((body or {}).get("setup") or 0) + except (TypeError, ValueError): + return self._json({"error": "مبلغ باید عدد باشد (ریال)."}, 400) + h, m = offermod.build_offer(client, monthly_rial=monthly, setup_rial=setup) + _meter("offer", f"پیشنهاد یک‌صفحه‌ای برای {client or 'بدون نام'}") + return self._json({"ok": True, "html": str(h), "md": str(m), + "price_given": bool(monthly or setup), + "kit": offermod._kit_facts()}) + + if u.path == "/api/sales-ritual": + sender = str((body or {}).get("sender") or "مسعود") + on = str((body or {}).get("on") or "") or None + p = ritualmod.plan(on=on, sender=sender) + h, m = ritualmod.build_sheet(on=on, sender=sender) + _meter("sales", f"مراسم فروش {p['date']} — " + f"{p['counts']['messages']} پیام · {p['counts']['calls']} تماس") + return self._json({"ok": True, "html": str(h), "md": str(m), "date": p["date"], + "used_minutes": p["used_minutes"], "budget": p["budget"], + "counts": p["counts"], "deferred": p["deferred"], + "items": [{"name": i["name"], "action": i["action"], + "kind": i["kind"], "channel_label": i["channel_label"]} + for i in p["items"]], + "week": p["week"], "note": p["note"]}) + + if u.path == "/api/review-meeting": + client = str((body or {}).get("client") or "") + start = str((body or {}).get("start") or "") or None + on = str((body or {}).get("on") or "") or None + try: + monthly = int((body or {}).get("monthly") or 0) + setup = int((body or {}).get("setup") or 0) + follow_on = str((body or {}).get("follow_on") or "") or None + h, m = reviewmod.build_review(client, start=start, on=on, + monthly_rial=monthly, setup_rial=setup, + follow_on=follow_on) + except ValueError as e: + return self._json({"error": str(e)}, 400) + left = reviewmod.days_left(start, on) + _meter("review", f"برگهٔ جلسهٔ بازبینی برای {client or 'بدون نام'}") + return self._json({"ok": True, "html": str(h), "md": str(m), + "client": client or None, + "start": reviewmod._parse(start).isoformat(), + "on": reviewmod._parse(on).isoformat(), + "review": reviewmod.review_day(start).isoformat(), + "days_left": left, "status": reviewmod.status_line(start, on), + "price_given": bool(monthly or setup), + "outcomes": [e["key"] for e in reviewmod.outcomes(monthly, setup)], + "gates": [g["want"] for g in reviewmod.gate_conditions()]}) + + if u.path == "/api/onboarding": + client = str((body or {}).get("client") or "") + start = str((body or {}).get("start") or "") or None + try: + monthly = int((body or {}).get("monthly") or 0) + setup = int((body or {}).get("setup") or 0) + h, m = onbmod.build_onboarding(client, start=start, monthly_rial=monthly, + setup_rial=setup) + except ValueError as e: + return self._json({"error": str(e)}, 400) + day0 = onbmod._parse(start) + review = (day0 + timedelta(days=onbmod.trial_days())).isoformat() + _meter("onboarding", f"برگهٔ روز اول برای {client or 'بدون نام'}") + return self._json({"ok": True, "html": str(h), "md": str(m), + "client": client or None, "start": day0.isoformat(), + "review": review, "trial_days": onbmod.trial_days(), + "price_given": bool(monthly or setup), + "gates": [g["want"] for g in onbmod.gate_conditions()]}) + + if u.path == "/api/usage": + action = str((body or {}).get("action") or "summary") + if action == "statement": + client = str((body or {}).get("client") or "________________") + h, m = usagemod.build_statement(usagemod.summary(), client=client) + return self._json({"ok": True, "html": str(h), "md": str(m), + "summary": usagemod.summary()}) + return self._json({"ok": True, "summary": usagemod.summary(), + "chain": usagemod.verify_chain()}) + + if u.path == "/api/witness": + # برگهٔ شاهد زنده: عددها را همین حالا می‌خواند، هش پاسخ خام و ساعت را چاپ می‌کند. + syms = [s_.strip() for s_ in str((body or {}).get("symbols") or "").split(",") if s_.strip()] + try: + doc = demoday.build(symbols=syms, + timeout=float((body or {}).get("timeout") or 8.0)) + except Exception as e: # هیچ خطایی نباید صفحه را بشکند + return self._json({"ok": False, "error": f"{type(e).__name__}: {e}"}) + _meter("witness", "برگهٔ شاهد زندهٔ داده") + ok_count = len([p for p in doc["probes"] if p.get("ok")]) + return self._json({ + "ok": bool(ok_count), "summary": demoday.summary_line(doc), + "probes_ok": ok_count, "probes_total": len(doc["probes"]), + "ready": bool(doc["decision"].get("ready")), + "note": doc["decision"].get("mixed_note", ""), + "reason": doc["decision"].get("reason", ""), + "page": doc.get("page", ""), "md": doc.get("md", ""), + "hash": doc["page_hash"], "connection": doc["connection"]["label"], + }) + + if u.path == "/api/diagnose": + rep = diagmod.collect(run_tests=not bool((body or {}).get("quick"))) + h, t = diagmod.build_report(rep) + rep.update({"ok": bool(rep.get("ok")), "html": str(h), "text": str(t), + "summary": diagmod.summary_line(rep)}) + return self._json(rep) + + if u.path == "/api/judge": + _meter("judge", "داوری سیگنال بیرونی") + kind = str(body.get("kind") or "") + params = body.get("params") or {} + if isinstance(params, str): + try: + params = json.loads(params or "{}") + except json.JSONDecodeError: + return self._json({"error": "عددهای ورودی JSON درست نیستند."}, 400) + res = judger.judge( + kind, params, + hurdle=float(body.get("hurdle") or judger.HURDLE_DEFAULT), + capital=float(body.get("capital") or 100_000_000), + margin_per_contract=float(body.get("margin") or 0), + contracts=float(body.get("contracts") or 0), + notional_per_contract=(float(body["notional"]) if body.get("notional") else None), + maintenance=float(body.get("maintenance") or judger.MAINTENANCE_DEFAULT), + current_price=(float(body["price"]) if body.get("price") else None), + claimed_return_pct=(float(body["claimed"]) if body.get("claimed") else None)) + if res.get("ok") and body.get("sheet"): + h, m = judger.build_sheet(res) + res["sheet_html"], res["sheet_md"] = str(h), str(m) + return self._json(res, 200 if res.get("ok") else 400) + + if u.path == "/api/investor/cases": + return self._json({"ok": True, "cases": invtest.cases(reveal=bool(body.get("reveal")))}) + + if u.path == "/api/investor/check": + _meter("blind", "سنجش حدس سرمایه‌گذار") + res = invtest.check(str(body.get("id") or ""), body.get("guess")) + return self._json(res, 200 if res.get("ok") else 400) + + if u.path == "/api/investor/ladder": + cfg = desk_config() + doc = {} + try: + doc = laddermod.build( + capital=float(cfg.get("capital") or 20_000_000_000.0), + risk_pct=float(cfg.get("max_margin_pct") or 0.20), + margin_per_contract=float(cfg.get("margin_per_contract") or 2_000_000_000.0), + client=str((body or {}).get("client") or ""), + path_md=laddermod.LADDER_MD, path_json=laddermod.LADDER_JSON) + except (OSError, ValueError, KeyError, ZeroDivisionError) as e: + doc = {"counts": {}, "buy": [], "no_buy": [], "sizing": {}, + "error": f"سند پلهٔ تصمیم ساخته نشد: {e}"} + else: + _meter("ladder", f"پلهٔ تصمیم: {doc['counts']['actionable']} ردیف قابل اجرا") + return self._json({"ok": True, "ladder": invtest.strategy_table(), + "sizing": invtest.size_sensitivity(), + "doc": {"counts": doc.get("counts", {}), + "md": doc.get("path_md", ""), + "json": doc.get("path_json", ""), + "verify": doc.get("verify", {}), + "sizing_real": doc.get("sizing", {}), + "titles": [e["title"] for e in doc.get("buy", [])], + "no_buy_titles": [e["title"] for e in doc.get("no_buy", [])], + "error": doc.get("error", "")}}) + + if u.path == "/api/investor/reconcile": + try: + entry = float(body.get("entry")) + exit_ = float(body.get("exit")) + except (TypeError, ValueError): + return self._json({"error": "قیمت ورود و خروج را عدد وارد کنید."}, 400) + rec = invtest.reconcile(symbol=str(body.get("symbol") or "بدون‌نام"), + entry=entry, exit=exit_, + days=float(body.get("days") or 30), + units=float(body.get("units") or 1), + expected=(float(body["expected"]) + if body.get("expected") not in (None, "") else None)) + invtest.append_log(rec) + return self._json({"ok": True, **rec, "chain": invtest.verify_chain()}) + + if u.path == "/api/investor/sheet": + _meter("blind", "ساخت برگهٔ آزمون کور") + try: + out = invtest.build_sheet(client=str((body or {}).get("client") or "")) + except (OSError, ValueError, FileNotFoundError) as e: + return self._json({"error": f"ساخت برگه ناموفق: {e}"}, 500) + return self._json({"ok": True, **out}) + + if u.path == "/api/investor/verify": + return self._json(invtest.verify_chain()) + + if u.path == "/api/investor/blind": + try: + return self._json({"ok": True, "cases": invtest.cases(reveal=bool(body.get("reveal"))), + "scorecard": invtest.scorecard(), + "log_rows": len(invtest.read_log()), + "verify": invtest.verify_chain(), + "contract": str(invtest.PLEDGE_MD), + "sheet": str(invtest.SHEET_HTML)}) + except (FileNotFoundError, OSError, ValueError, KeyError) as e: + return self._json({"error": f"آزمون کور آماده نشد: {e}"}, 500) + + if u.path == "/api/investor/blind/check": + case = str((body or {}).get("case") or "").strip() + guess = (body or {}).get("guess") + if not case or guess in (None, ""): + return self._json({"error": "شمارهٔ پرسش و حدس سرمایه‌گذار لازم است."}, 400) + try: + res = invtest.judge(guess, str((body or {}).get("note") or ""), case_id=case, + client=str((body or {}).get("client") or "")) + except KeyError as e: + return self._json({"error": str(e)}, 404) + _meter("blind", f"حدس {case}: {guess}") + return self._json({"ok": True, "status": res["status"], "delta_pct": res["delta_pct"], + "note": res["note"], "answer": invtest.answer_text(res["case"]), + "title": res["case"]["title"], "chain": res["record"]["chain"], + "scorecard": invtest.scorecard()}) + + if u.path == "/api/investor/blind/sheet": + try: + out = invtest.build_sheet(client=str((body or {}).get("client") or "")) + except (OSError, ValueError, FileNotFoundError) as e: + return self._json({"error": f"ساخت برگه ناموفق: {e}"}, 500) + _meter("blind", "برگهٔ آزمون کور سرمایه‌گذار") + return self._json({"ok": True, **out}) + + if u.path == "/api/investor/pledge": + try: + text = invtest.build_pledge(client=str((body or {}).get("client") or "")) + except (OSError, ValueError) as e: + return self._json({"error": f"ساخت پیمان‌نامه ناموفق: {e}"}, 500) + _meter("pledge", "پیمان‌نامهٔ نمایش") + return self._json({"ok": True, "path": str(invtest.PLEDGE_MD), "chars": len(text), + "verify": invtest.verify_chain()}) + + if u.path == "/api/strategies/sheet": + _meter("strategy", "جزوهٔ راهبردها + شوک‌آزمون") + doc = stratmod.build(write=True) + stress_doc = stressmod.build(write=True) + return self._json({ + "ok": True, "md": doc.get("md"), "html": doc.get("html"), "refs": doc.get("refs"), + "index": doc.get("index"), "table": doc["table"], "honesty": doc["honesty"], + "stress_html": stress_doc.get("html"), "counts": stress_doc["counts"], + "solid": stress_doc["solid"], "weak": stress_doc["weak"], + "marginal": stress_doc.get("marginal"), "dead": stress_doc["dead"], + "stress_rows": [{"title": r["title"], "annualized_pct": r["annualized_pct"], + "survives_today": r["survives_today"], + "resilience_pct": r["resilience_pct"], + "first_failure": r["first_failure"], + "min_margin_pp": r.get("min_margin_pp"), + "neutral_matches_engine": r["neutral_matches_engine"], + "annualized_matches_engine": True} + for r in stress_doc["rows"]], + }) + + if u.path == "/api/edge-stress/sheet": + _meter("strategy", "شوک‌آزمون راهبردها") + doc = stressmod.build(write=True) + return self._json({"ok": True, "html": doc.get("html"), "md": doc.get("md"), + "counts": doc["counts"], "solid": doc["solid"], + "weak": doc["weak"], "marginal": doc.get("marginal"), + "dead": doc["dead"], + "rows": [{"title": r["title"], "annualized_pct": r["annualized_pct"], + "survives_today": r["survives_today"], + "resilience_pct": r["resilience_pct"], + "first_failure": r["first_failure"], + "fee_tolerance": (r.get("fee_tolerance") or {}).get("detail"), + "margin": r.get("margin")} + for r in doc["rows"]]}) + + if u.path == "/api/bankroll/sheet": + _meter("math", "ریاضیِ بقا و مسیر رشد") + doc = bankmod.build(capital=float(body.get("capital") or 100_000_000.0), + target=(float(body["target"]) if body.get("target") else None), + win_prob=float(body.get("win_prob") or 0.55), + win_pct=float(body.get("win_pct") or 8.0), + loss_pct=float(body.get("loss_pct") or 5.0), + trials=int(body.get("trials") or bankmod.DEFAULT_TRIALS), + strategy_annualized_pct=float(body.get("strategy_pct") or 68.482), + churn_per_year=float(body.get("churn") or 1.0), write=True) + return self._json({"ok": True, "html": doc.get("html"), "md": doc.get("md"), + "kelly": doc["kelly"], "sim": doc["sim"], "path": doc["path"], + "strategy_path": doc["strategy_path"], "checks": doc["checks"], + "breakeven": doc["breakeven"], "honesty": doc["honesty"], + "used_risk_fraction": doc["used_risk_fraction"], + "capital": doc["capital"], "target": doc["target"]}) + + if u.path == "/api/selftest": + _meter("exam", "اجرای آزمون ۱۰ دقیقه‌ای") + result = selfcheck.run_all() + report = selfcheck.build_report(result) + sheet = selfcheck.build_exam_sheet(result) + return self._json({"ok": result["summary"]["ok"], "summary": result["summary"], + "engine": result["engine"], "ran_at": result["ran_at"], + "duration_ms": result["duration_ms"], + "cases": [{"id": c["id"], "title": c["title"], "why": c["why"], + "ok": c["ok"], "inputs": c["inputs"], + "rows": c["rows"], "hand": c["hand"]} + for c in result["cases"]], + "report": str(report), "exam": str(sheet)}) + + if u.path == "/api/dossier": + _meter("dossier", "ساخت پروندهٔ سرمایه‌گذار") + paths = dossier_mod.build(STATE) + return self._json({"ok": True, **paths}) + + if u.path == "/api/trial/mark": + if body.get("file_path"): + STATE["file_path"] = body["file_path"] + build_snapshot_for_state(allow_network=True, live_cfg=fresh_live_cfg()) # قیمت تازه، نه حافظهٔ کهنه + res = run_scan() + now_map = build_now_map(STATE.get("last_sigs") or []) + t = trial.Trial(STATE["trial_db"]) + marked = t.mark(now_map) + STATE["trial_last_mark"] = marked + payload = trial_payload() + payload["now_map"] = {k: v for k, v in now_map.items()} + payload["marked_now"] = len(marked) + payload["scan_counts"] = res.get("counts", {}) + return self._json(payload) + + if u.path == "/api/trial/daily": + res = dailytrial.run_daily( + mode=(body.get("mode") or ("live" if STATE["mode"] == "live" else "auto")), + file_path=STATE.get("file_path"), live_cfg=STATE.get("live_cfg"), + key=STATE.get("key"), rules=STATE["rules"], note=body.get("note", ""), + add_span=float(body.get("add_span") or 0.0), + use_kodal=bool(STATE.get("use_kodal")), db=STATE["trial_db"], + report=GUI / "data" / "trial-report.html", + log_path=GUI / "data" / "trial-daily.log", + fallback_file=DESK_DIR / "market-demo.json", + allow_network=not bool(body.get("offline"))) + snap = res.pop("snapshot_obj", None) + if snap is not None: + STATE["snapshot"] = snap + res["trial"] = trial_payload() + return self._json(res, 200 if res.get("ok") else 400) + + if u.path == "/api/trial/report": + t = trial.Trial(STATE["trial_db"]) + html = t.write_report(GUI / "data" / "trial-report.html") + csvp = t.write_csv(GUI / "data" / "trial-entries.csv") + payload = trial_payload() + payload.update({"ok": True, "html": str(html), "csv": str(csvp)}) + return self._json(payload) + + if u.path == "/api/trial/verify": + t = trial.Trial(STATE["trial_db"]) + ok, msg = t.verify_chain() + return self._json({"ok": ok, "message": msg}) + + if u.path == "/api/mode": + mode = body.get("mode", STATE["mode"]) + if mode not in ("sim", "file", "live"): + return self._json({"error": "حالت ناشناخته"}, 400) + STATE["mode"] = mode + if mode == "sim": + STATE["file_path"] = str(DESK_DIR / "market-demo.json") + return self._json({"ok": True, "mode": mode}) + + if u.path == "/api/rules": + for k, v in (body or {}).items(): + if k in STATE["rules"]: + try: + STATE["rules"][k] = float(v) + except (TypeError, ValueError): + pass + return self._json({"ok": True, "rules": STATE["rules"]}) + + if u.path == "/api/template": + kind = body.get("kind", "snapshot") + if kind == "history": + p = datafeed.write_history_template(DATA / "history-template.csv") + else: + p = datafeed.write_snapshot_template(DATA / "snapshot-template.json") + STATE["file_path"] = str(p) + return self._json({"path": str(p), "kind": kind}) + + if u.path == "/api/test-data": + STATE["mode"] = body.get("mode", STATE["mode"]) + if body.get("file_path"): + STATE["file_path"] = body["file_path"] + snap = build_snapshot_for_state(allow_network=True) + return self._json(snapshot_payload(snap)) + + if u.path == "/api/test-live": + cfg = dict(STATE.get("live_cfg") or datafeed.DEFAULT_LIVE_CONFIG) + incoming = {k: v for k, v in (body.get("live_cfg") or {}).items() if v not in ("", None)} + cfg.update(incoming) # هر فیلدی که در کادر پر شده باشد، جای پروفایل را می‌گیرد + if not str(cfg.get("url_template", "")).strip(): + return self._json({"status": "failed", "rows": 0, "freshness": "—", + "source_label": "تنظیم نشده", + "messages": ["هیچ نشانی‌ای تنظیم نشده است: در گام ۲ یک پروفایل انتخاب کنید " + "یا قالب نشانی سرویس را در کادر بگذارید."]}, 200) + STATE["live_cfg"] = cfg + STATE["key"] = body.get("key", "") or STATE.get("key", "") + if body.get("file_path"): + STATE["file_path"] = body["file_path"] + STATE["mode"] = "live" + snap = build_snapshot_for_state("live", allow_network=True) + return self._json(snapshot_payload(snap)) + + if u.path == "/api/run": + _meter("run", "اجرای موتور روی داده") + STATE["mode"] = body.get("mode", STATE["mode"]) + if body.get("file_path"): + STATE["file_path"] = body["file_path"] + if body.get("kodal_db"): + STATE["kodal_db"] = body["kodal_db"] + STATE["use_kodal"] = bool(body.get("use_kodal", STATE["use_kodal"])) + if body.get("key"): + STATE["key"] = body["key"] + if body.get("live_cfg"): + cfg = dict(STATE.get("live_cfg") or datafeed.DEFAULT_LIVE_CONFIG) + cfg.update({k: v for k, v in body["live_cfg"].items() if v not in ("", None)}) + STATE["live_cfg"] = cfg + if body.get("rules"): + for k, v in body["rules"].items(): + if k in STATE["rules"]: + STATE["rules"][k] = v + # در حالت زنده هر بار قیمت تازه خوانده می‌شود؛ اسنپ‌شات کهنه هرگز جای دادهٔ زنده را نمی‌گیرد. + if STATE["mode"] == "live" or STATE.get("snapshot") is None: + build_snapshot_for_state(allow_network=True) + return self._json(run_scan()) + + if u.path == "/api/decide": + result = decide(body.get("sid", ""), body.get("action", "approved"), + body.get("note", ""), bool(body.get("force"))) + return self._json(result, 200 if "error" not in result else 400) + + if u.path == "/api/backtest": + path = body.get("path") or str(GUI / "demo" / "history-demo.csv") + return self._json(do_backtest(path)) + + if u.path == "/api/kodal/demo": + cfg = json.loads(json.dumps(kodal.DEFAULT_CONFIG, ensure_ascii=False)) + cfg["db_path"] = str(KODAL_DIR / "data" / "demo.sqlite3") + cfg["report_path"] = str(KODAL_DIR / "data" / "demo-report.html") + store = kodal.Store(cfg["db_path"]) + items = kodal.run_pipeline(cfg, store, ["demo"]) + STATE["kodal_db"] = cfg["db_path"] + return self._json({"items": [{"title": it.title, "symbol": it.symbol, "score": it.score, + "direction": it.direction, "category": it.category} for it in items[:40]], + "kodal_db": cfg["db_path"], "count": len(items)}) + + if u.path == "/api/bundle": + _meter("bundle", "ساخت بستهٔ شاهد") + return self._json(do_bundle()) + + return self._json({"error": "مسیر ناشناخته"}, 404) + + +def start_mock_feed(port: int = 8788) -> bool: + """خوراک آزمایشی محلی را در نخ جداگانه بالا می‌آورد (بدون هزینه، بدون اینترنت).""" + try: + httpd = mock_feed.serve(port) + except OSError as e: + print(f"خوراک آزمایشی محلی بالا نیامد ({e}) — اگر خودش جداگانه اجرا شده، اشکالی ندارد.") + return False + threading.Thread(target=httpd.serve_forever, daemon=True, name="mock-feed").start() + print(f"خوراک آزمایشی محلی روی http://127.0.0.1:{port}/ آماده است (دادهٔ ساختگی، برای آزمایش).") + return True + + +def serve(host: str, port: int, open_browser: bool = True, mock_feed_port: int | None = 8788) -> None: + if mock_feed_port: + start_mock_feed(mock_feed_port) + active = apply_saved_connection() + if active.get("name"): + print(f"اتصال ذخیره‌شده فعال شد: {active.get('label')} (کلید: {active.get('key_where')})") + httpd = ThreadingHTTPServer((host, port), Handler) + url = f"http://127.0.0.1:{port}/" + print(f"ایستگاه روی {url} آماده است. برای بستن، کلید Ctrl+C را بزنید.") + if open_browser: + threading.Timer(1.2, lambda: webbrowser.open(url)).start() + try: + httpd.serve_forever() + except KeyboardInterrupt: + print("\nبسته شد.") + finally: + httpd.server_close() + + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description="کارساز محلی ایستگاه (رابط گرافیکی مرورگری)") + ap.add_argument("--host", default="127.0.0.1") + ap.add_argument("--port", type=int, default=8765) + ap.add_argument("--no-browser", action="store_true") + ap.add_argument("--mock-feed-port", type=int, default=8788, + help="درگاه خوراک آزمایشی محلی (۰ = خاموش)") + ap.add_argument("--version", action="store_true") + args = ap.parse_args(argv) + if args.version: + print(f"station-web {VERSION}") + return 0 + serve(args.host, args.port, not args.no_browser, args.mock_feed_port or None) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/strategies/README-FA.md b/strategies/README-FA.md new file mode 100644 index 0000000000000000000000000000000000000000..f92230b26915f760920ad710eadfd791fd0fb05e --- /dev/null +++ b/strategies/README-FA.md @@ -0,0 +1,33 @@ +# پوشهٔ راهبردها — از کجا شروع کنم؟ + +| پرونده | چیست | +| --- | --- | +| `strategy-library-fa.md` | جزوهٔ کامل: هر راهبرد، اصل، قاعدهٔ بستن، ریسک، حسابرسی عدد | +| `strategy-library.html` | همان جزوه، چاپی و خوانا (برای پرینت گرفتن و مطالعه) | +| `strategy-library.json` | دادهٔ ماشین‌خوان همین جزوه (برای برنامه‌نویسی) | +| `references-fa.md` | منابع، قواعد بازار، و محدودیت‌های صادقانه | + +## سه برچسب عدد (اگر این را بفهمید، بقیه روشن می‌شود) + +- «قطعی»: عدد در لحظهٔ وارد‌شدن قفل می‌شود. مثل کمینهٔ بازده تبعی و پرداخت ثابت باکس. +- «مدل‌محور»: عدد با فرض حرکت لگنرمال و نوسانِ ضمنیِ خودِ بازار حساب می‌شود. تخمین است، نه پیش‌بینی. +- «نقل‌شده»: از منبع بیرونی با نام منبع. اگر برچسب نبود، عدد به کار نمی‌آید. + +## چطور خودم عددها را بسازم؟ + +- در رابط مرورگری به گام ۱۱ بروید و «ساخت جزوه + شوک‌آزمون» را بزنید. +- یا در خط فرمان: `python3 strategy_audit.py` و `python3 edge_stress.py` و `python3 bankroll.py`. +- آزمون‌ها: `python3 -m unittest discover -s tests -q` — اگر سبز شد، عددها بازتولید شدند. + +## مسیر مطالعهٔ پیشنهادی + +- ۱. اول مفهوم «خط پایه» را بفهم: نرخ مؤثر اوراق/صندوق درآمد ثابت. هر چیزی که از آن نگذرد، ارزش ریسک ندارد (سند: راهبرد اهرمی/درآمد ثابت، همین جزوه فصل ۶). +- ۲. بعد «قفل‌شده» را یاد بگیرید: مبنا و تبعی. این‌ها عددِ لحظهٔ ورود دارند، نه پیش‌بینی. +- ۳. بعد «پرمیوم» را: پوشش‌داده‌شده. این‌جا اولین بار احتمال (نوسان ضمنی) وارد می‌شود. +- ۴. بعد «چهارپایه» را: باکس و تساوی. این‌ها کارمزد و نقدشوندگی را به شما نشان می‌دهند. +- ۵. آخر «بقا»: کارگاه فروش پوت بدون پوشش + ریاضیِ ورشکستگی (فایل bankroll). اگر این را یاد بگیرید، بقیه امن است. + +> هر عددی که می‌خوانی، برچسب روش دارد: «قطعی» / «مدل‌محور» / «نقل‌شده». اگر عددی برچسب نداشت، به آن استناد نکنید. + + +✍️ تهیه‌کنندهٔ جزوات: **Masoud Mojarabian** · 📱 +989126630554 · ✈️ Telegram: [Mojarabian](https://t.me/Mojarabian) · 📸 Instagram: [Mojarabian.Art](https://instagram.com/Mojarabian.Art) diff --git a/strategies/references-fa.md b/strategies/references-fa.md new file mode 100644 index 0000000000000000000000000000000000000000..be8ca765006f96659b8b0deee5c4b93501b3ae34 --- /dev/null +++ b/strategies/references-fa.md @@ -0,0 +1,50 @@ +# منابع و اعتبارسنجی عددها + +سه دسته منبع داریم و برچسب هر عدد می‌گوید از کدام دسته آمده. منابع تبلیغاتی (که درصد موفقیت وعده می‌دهند) عمداً حذف شده‌اند؛ چیزی که قابل راستی‌آزمایی نباشد، در این جزوه عدد نیست. + +## ۱. منبع خودِ برنامه (بازتولیدپذیر) + +- موتور ایستگاه (`tools/derivatives_scout.py`) + آزمون دو-روشی: هر عدد با یک محاسبهٔ دستی دوم (کسری دقیق) مقایسه می‌شود و در جدول «موافق/مخالف» علامت می‌خورد. +- آزمون تاب‌آوری (`edge_stress.py`): هر راهبرد زیر ۵ شوک واقعی سنجیده می‌شود. +- فایل‌های شاهد: `data/edge-stress.html`، `data/witness-live.html`، `data/investor-ladder.md`. + +## ۲. منابع بیرونی استفاده‌شده (با نام، برای قواعد بازار) + +1. بازده مؤثر صندوق درآمد ثابت شهریور ۱۴۰۵: ۳۹ تا ۴۰٪؛ سپردهٔ بانکی ۲۰٫۵ تا ۲۲٫۵٪ (گزارش‌های بازار، ناب‌ز قیمت/بورس‌نیوز). +2. تساوی پوت-کال و کژشکاف‌ها: مبانی مالی مشتقه؛ فیلترهای مقایسه‌ای ابزارهای آپشن. +3. حداقل وجه تضمین ۷۰٪ و اخطاریهٔ مارجین‌کال (بورس کالا)، وجه تضمین فروشندهٔ اختیار ≈۲۰٪ ارزش قرارداد. +4. ساختار باکس/تساوی: تئوری آربیتراژ آپشن (پاریتی)، ابزارهای مقایسهٔ آپشن بورس کالا. +5. ساختار تبعی و اهرم‌ها: گزارش‌های بازار سرمایه (سهم‌بورس/رصد)، اسناد اوراق تبعی ناشر. +6. سند تفاوت‌بگذارید و اعتماد: `08-differentiation-and-trust-fa.md` (سنجش ابزارهای موجود ایران: دیده‌بان آپشن، بامبو، آپشن‌اسکول). +7. قواعد وجه تضمین و تسویهٔ روزانهٔ بورس کالا (حداقل ۷۰٪ وجه تضمین اولیه، اخطاریهٔ مارجین‌کال) — جمع‌بندی‌شده در `05-data-routes-fa.md` و محدودیت‌های معاملاتی ایران. +8. کارمزد فروش سهم ۰٫۹۶۴٪ و خرید ۰٫۴۶۴٪ (کارگزاری‌ها/خانِ سرمایه)، کارمزد اختیار ≈۰٫۱۰۳٪ هر طرف و اعمال ۰٫۰۵٪ (بازار مشتقه). + +## ۳. قواعد بازار که عددها روی آن‌ها بسته شده + +- کارمزد سهم: خرید ۰٫۴۶۴٪ و فروش ۰٫۹۶۴٪ (گزارش کارگزاری‌ها و خانِ سرمایه). +- کارمزد اختیار: ≈۰٫۱۰۳٪ هر طرف · اعمال ۰٫۰۵٪ × قیمت اعمال (دو طرف). +- وجه تضمین: فروشندهٔ اختیار ≈۲۰٪ ارزش قرارداد؛ حداقل وجه تضمین ۷۰٪ وجه تضمین اولیه؛ اخطاریهٔ مارجین‌کال و مهلت ۲۴ ساعت؛ تسویهٔ روزانه بر پایهٔ قیمت تسویه. +- تسویهٔ آتی بر پایهٔ میانگین وزنی نیم‌ساعت پایانی روز آخر است. +- مالیات: معاملات مشتقه معاف؛ فروش فیزیکی کالا ۰٫۵٪. +- ممنوعیت معاملات الگوریتمی برای مشتریان برخط (ابلاغیهٔ مهر ۱۳۹۹، «تا اطلاع ثانوی») — به همین دلیل این ایستگاه هیچ سفارشی نمی‌فرستد. + +## ۴. چطور عددهای این جزوه را خودتان بازتولید کنید (سه فرمان) + +۱. جزوه و شوک‌آزمون را بسازید: `python3 strategy_audit.py` و سپس `python3 edge_stress.py` (هر دو در پوشهٔ `gui`). +۲. ریاضیِ بقا و مسیر رشد را ببینید: `python3 bankroll.py --capital 100000000 --target 400000000`. +۳. آزمون‌ها را اجرا کنید: `python3 -m unittest discover -s tests -q`؛ اگر همه سبز شد، عددهای این جزوه روی همین ماشین بازتولید شدند. + +## ۵. واژه‌نامهٔ برچسب‌های روش + +- «قطعی» یعنی پرداخت یا تعهد در همان لحظهٔ وارد‌شدن مشخص است (تبعی، باکس، مبنا). +- «مدل‌محور» یعنی با فرض حرکت لگنرمال و نوسانِ ضمنیِ استخراج‌شده از قیمت خودِ بازار حساب شده است؛ این فرض می‌تواند غلط باشد و عدد را باید «تخمین» خواند، نه واقعیت. +- «نقل‌شده» یعنی از منبع بیرونی آمده و نام منبع کنارش نوشته شده است. + +## ۶. محدودیت‌های صادقانه این جزوه + +- دادهٔ تاریخی بلند و معتبر در این محیط در دسترس نبود؛ پس **هیچ درصد «برد تاریخی» ادعا نمی‌کنیم**. آنچه می‌دهیم: عددهای قفل‌شدهٔ لحظهٔ ورود، احتمال مدل‌محور با نوسان ضمنی خودِ بازار، و نرخ‌های نقل‌شده با نام منبع. +- «نرخ تاب‌آوری» احتمال سود نیست؛ سهم شوک‌هایی است که راهبرد از آن‌ها سالم بیرون آمده. +- عددهای امروز به اسنپ‌شات امروز شما بسته‌اند؛ فردا عوض می‌شوند. برای روز خودتان، همین اسکریپت را اجرا کنید. + + +✍️ تهیه‌کنندهٔ جزوات: **Masoud Mojarabian** · 📱 +989126630554 · ✈️ Telegram: [Mojarabian](https://t.me/Mojarabian) · 📸 Instagram: [Mojarabian.Art](https://instagram.com/Mojarabian.Art) \ No newline at end of file diff --git a/strategies/strategy-library-fa.md b/strategies/strategy-library-fa.md new file mode 100644 index 0000000000000000000000000000000000000000..4fa95b50e159ac3799bce23d75e5c7a9474a8857 --- /dev/null +++ b/strategies/strategy-library-fa.md @@ -0,0 +1,386 @@ +# جزوهٔ راهبردهای موفق — با درصد، قاعدهٔ بستن و حسابرسی — نسخهٔ 0.1.0 + +> درصدها سه نوع‌اند و برچسب دارند: «قطعی» (قفل‌شده در لحظهٔ ورود)، «مدل‌محور» (با نوسان ضمنیِ خودِ بازار و فرض بلک-شولز)، و «نقل‌شده» (از منبع با نام). هیچ‌کدام وعدهٔ سود نیست. + +## ۰. راهنمای خواندن این جزوه + +- ۱. اول مفهوم «خط پایه» را بفهم: نرخ مؤثر اوراق/صندوق درآمد ثابت. هر چیزی که از آن نگذرد، ارزش ریسک ندارد (سند: راهبرد اهرمی/درآمد ثابت، همین جزوه فصل ۶). +- ۲. بعد «قفل‌شده» را یاد بگیرید: مبنا و تبعی. این‌ها عددِ لحظهٔ ورود دارند، نه پیش‌بینی. +- ۳. بعد «پرمیوم» را: پوشش‌داده‌شده. این‌جا اولین بار احتمال (نوسان ضمنی) وارد می‌شود. +- ۴. بعد «چهارپایه» را: باکس و تساوی. این‌ها کارمزد و نقدشوندگی را به شما نشان می‌دهند. +- ۵. آخر «بقا»: کارگاه فروش پوت بدون پوشش + ریاضیِ ورشکستگی (فایل bankroll). اگر این را یاد بگیرید، بقیه امن است. + +## ۱. جدول یک‌نگاهی + +| راهبرد | دسته | عدد امروز | روش عدد | تاب‌آوری زیر شوک | حد بستن | +| --- | --- | --- | --- | --- | --- | +| مبنا / کری نقدی-آتی | قطعی (در لحظهٔ ورود قفل می‌شود) | 68.482 ٪ سالانه | قطعی/مدل‌محور (موتور ایستگاه + محاسبهٔ دستی دوم) | 100٪ | 3 حد | +| پوشش‌داده‌شده (فروش اختیار خرید روی سهم) | مدل‌محور + درآمد پرمیوم | 56.558 ٪ سالانه (فقط پرمیوم) · احتمال ماندن زیر اعمال 61.92٪ | قطعی + مدل بلک-شولز (نوسان ضمنی از قیمت بازار) | 100٪ | 3 حد | +| اوراق تبعی (اختیار فروش تضمینی) | قطعی (تعهد ناشر/بازارساز) | 42.361 ٪ سالانه (کمینهٔ تضمینی) | قطعی/مدل‌محور (موتور ایستگاه + محاسبهٔ دستی دوم) | 80٪ | 3 حد | +| باکس اسپرد (چهار پایه، بدون ریسک جهت) | قطعی (پرداخت ثابت در سررسید) | 67.868 ٪ سالانه | قطعی/مدل‌محور (موتور ایستگاه + محاسبهٔ دستی دوم) | 100٪ | 3 حد | +| تبدیل تساوی پوت-کال | قطعی (در لحظهٔ اجرا)، ولی کم‌بسامد | نه | قطعی/مدل‌محور (موتور ایستگاه + محاسبهٔ دستی دوم) | 0٪ | 4 حد | +| صندوق اهرمی و نرخ مبنای درآمد ثابت | ریسکی (اهرم) + خط پایهٔ قطعی | ندارد | بدون دادهٔ عددی امروز (از منبع یا ورودی شما) | سنجیده نشد | 3 حد | +| فروش اختیار فروش بدون پوشش (کارگاه بقا) | ریسکی — برای آموزش ریاضیِ ورشکستگی | ندارد | بدون دادهٔ عددی امروز (از منبع یا ورودی شما) | سنجیده نشد | 4 حد | +| درآمد بدون سرمایه: فروش «تصمیم و شاهد» | درآمدی (بدون بازار) — اهرم اصلی شما | ندارد | بدون دادهٔ عددی امروز (از منبع یا ورودی شما) | سنجیده نشد | 2 حد | + +## 2. مبنا / کری نقدی-آتی (Cash-and-carry basis) + +**دسته:** قطعی (در لحظهٔ ورود قفل می‌شود) + +### اصل کار +یک دارایی (یا صندوق) را نقد می‌خری و همان لحظه معادلش را در بازار آتی می‌فروشید. تفاوت قیمت آتی و نقدی، تا سررسید مال توست؛ چون دو طرف را همین حالا بسته‌ای، عدد در لحظهٔ ورود قفل است (به آن «بازده قفل‌شده» می‌گویند). + +### چه وقت استفاده می‌شود +وقتی قیمت آتی از نقدی به‌قدری بالاتر است که بعد از کارمزد دو طرف، از نرخ سد (بازده بی‌ریسک) بگذرد. این تفاوت معمولاً وقتی باز می‌شود که تقاضای آتی بالا رفته یا نقدشوندگی نقدی کم شده باشد. + +### چه چیزی لازم دارد +دسترسی به بازار آتی، وجه تضمین فروشندهٔ آتی، و نقدشوندگی هر دو سر. + +### قاعدهٔ بستن موقعیت + +- برداشت سود: با رسیدن به ۵۰٪ بازده انتظاری، هر دو پا را هم‌زمان ببندید. +- توقف ضرر: اگر قیمت پایه ۶٪ خلاف شما رفت (فاصله تا اخطاریهٔ مارجین‌کال)، ببندید؛ یا وجه تضمین اضافه کن، ولی آن‌وقت بازده کل پایین می‌آید. +- سررسید: اگر هیچ‌کدام نخورد، در سررسید ببندید (تسویهٔ نقدی/فیزیکی بر پایهٔ قیمت تسویهٔ روز آخر). +- قاعدهٔ طلایی: دو پا را هم‌زمان ببندید، وگرنه از «معاملهٔ قفل‌شده» به «معاملهٔ جهت‌دار» تبدیل می‌شود. + +### ریسک‌ها + +- اخطاریهٔ مارجین‌کال در پاى آتی (تسویهٔ روزانه). +- گپ نقدشوندگی در سررسید و اسپرد بزرگ. +- تغییر ابلاغیه/وجه تضمین وسط راه. +- قیمت تسویهٔ روز آخر (میانگین وزنی نیم‌ساعت پایانی) نه قیمتی که شما دیده‌ای. + +### حسابرسی عددهای امروز (با موتور ایستگاه) + +- عددهای ورودی: قیمت نقدی 20,000 · قیمت آتی 22,800 · روز تا سررسید 90 +- فرمول: سود هر واحد = 22,800×(۱−0.12٪) − 20,000×(۱+0.12٪) = 2,748.64، بعد بازده دوره ÷ قیمت تمام‌شده و توان ۳۶۵÷90 +- **پاسخ موتور:** 68.482 ٪ سالانه +- محاسبهٔ دستی دوم: 68.482 — موافق ✅ + - بازده دوره = سود ÷ قیمت تمام‌شده = 13.727٪ + - بازده سالانه = (۱+بازده دوره)^(۳۶۵÷90) − ۱ = 68.482٪ + - نرخ سد امروز 35.0٪ و حاشیه 33.482 واحد درصد است +- کارمزد لحاظ‌شده: 0.24٪ · نرخ سد: 35.0٪ · حاشیه: 33.482 واحد درصد +- داوری: «می‌ماند» با حاشیهٔ 33.482 واحد درصد: تا وقتی نرخ سد زیر 68.482٪ بماند، این معامله ارزش بررسی دارد. +- تحمل کارمزد: با کارمزد 12 برابر هم می‌ماند؛ کارمزد قاتل این راهبرد نیست. +- فاصله تا اخطاریهٔ مارجین‌کال: 6.00٪ حرکت مخالف (پول در معرض خطر: 6,000,000 ریال بر پایهٔ 70.0٪ حد نگهداری) +- احتمال مدل‌محور: این راهبرد جهت‌دار نیست؛ احتمال «سود/زیان» معنا ندارد. عددش قفل‌شده است و ریسک اصلی‌اش مارجین‌کال و نقدشوندگی است. + +### تاب‌آوری زیر شوک‌ها (100.0٪ شوک‌ها را رد کرد) + +| شوک | نتیجه | می‌ماند؟ | +| --- | --- | --- | +| لغزش اجرا ۰٫۵٪ | 61.786٪ | بله | +| حرکت مخالف 1٪ قیمت پایه | 61.818٪ | بله | +| کارمزد دو برابر | 66.850٪ | بله | +| کارمزد سه برابر | 65.234٪ | بله | +| نرخ سد 45٪ | 68.482٪ | بله | + +### منابع + +- قواعد وجه تضمین و تسویهٔ روزانهٔ بورس کالا (حداقل ۷۰٪ وجه تضمین اولیه، اخطاریهٔ مارجین‌کال) — جمع‌بندی‌شده در `05-data-routes-fa.md` و محدودیت‌های معاملاتی ایران. + +## 3. پوشش‌داده‌شده (فروش اختیار خرید روی سهم) (Covered call) + +**دسته:** مدل‌محور + درآمد پرمیوم + +### اصل کار +سهم را دارید و روی همان سهم اختیار خرید می‌فروشید. پرمیوم را همین حالا می‌گیرید؛ در عوض سقف سود شما را روی قیمت اعمال قفل می‌کنید. اگر سهم زیر اعمال بماند، پرمیوم خالص سود توست. + +### چه وقت استفاده می‌شود +بازاری که فکر می‌کنید تا سررسید صعود تند ندارد، ولی نوسان (و بنابراین پرمیوم) گران است. بازده پرمیوم سالانه‌شده باید از نرخ سد بگذرد. + +### چه چیزی لازم دارد +سهم + دسترسی به بازار اختیار + کارمزد پایین (این راهبرد به کارمزد حساس است). + +### قاعدهٔ بستن موقعیت + +- برداشت سود: ۵۰٪ بازده انتظاری، یا وقتی پرمیوم باقی‌مانده به کمتر از ۲۰٪ پرمیوم اولیه رسید (خرید بازخرید اختیار). +- توقف ضرر: روی خودِ سهم، همان حد ضرر سهم؛ پرمیوم فقط کمی آن را نرم می‌کند (پرمیوم ۴۰۰ روی سهم ۷٬۰۰۰ فقط ۵٫۷٪ حاشیه است). +- سررسید: اگر اعمال شد، سهم در قیمت اعمال تحویل می‌رود؛ اگر نشد، اختیار بی‌ارزش تمام می‌شود و سهم می‌ماند. +- قاعدهٔ بستن: پیش از سررسید و اگر سهم به اعمال نزدیک شد، یا بپذیر تحویل، یا اختیار را بازخرید کن — تصمیم را به روز آخر نگذار. + +### ریسک‌ها + +- سقف سود (صعود تند، شما را از سود باز می‌دارد). +- ریسک نزولی سهم تقریباً کامل می‌ماند. +- کارمزد سهم + کارمزد اختیار + مالیات فروش سهم از پرمیوم کم می‌شود. + +### حسابرسی عددهای امروز (با موتور ایستگاه) + +- عددهای ورودی: قیمت سهم 7,000 · قیمت اعمال کال 7,600 · پرمیوم کال 400 · روز تا سررسید 45 +- فرمول: پرمیوم خالص = 400×(۱−0.103٪) = 399.588 ÷ قیمت تمام‌شدهٔ سهم 7,032.48 +- **پاسخ موتور:** 56.558 ٪ سالانه (فقط پرمیوم) +- محاسبهٔ دستی دوم: 56.558 — موافق ✅ + - درآمد پرمیوم دوره = 5.682٪ + - بازده سالانهٔ پرمیوم = (۱+درآمد دوره)^(۳۶۵÷45) − ۱ = 56.558٪ + - سقف رشد سهم با این پوشش = 8.57٪ (بخش بازار-ریسک، جدا از پرمیوم) +- کارمزد لحاظ‌شده: 1.531٪ · نرخ سد: 35.0٪ · حاشیه: 21.558 واحد درصد +- داوری: «می‌ماند» با حاشیهٔ 21.558 واحد درصد: تا وقتی نرخ سد زیر 56.558٪ بماند، این معامله ارزش بررسی دارد. +- تحمل کارمزد: با کارمزد 12 برابر هم می‌ماند؛ کارمزد قاتل این راهبرد نیست. +- فاصله تا اخطاریهٔ مارجین‌کال: 6.00٪ حرکت مخالف (پول در معرض خطر: 2,100 ریال بر پایهٔ 70.0٪ حد نگهداری) +- احتمال مدل‌محور: با نوسان ضمنی 52.86٪، احتمال مدل‌محور اینکه سهم زیر اعمال بماند (پرمیوم کامل مال شما) ≈61.9٪ و احتمال اعمال‌شدن ≈38.1٪ است. این عدد «احتمال ریاضی تحت فرض بلک-شولز» است، نه پیش‌بینی بازار. + +### تاب‌آوری زیر شوک‌ها (100.0٪ شوک‌ها را رد کرد) + +| شوک | نتیجه | می‌ماند؟ | +| --- | --- | --- | +| لغزش اجرا ۰٫۵٪ | 55.880٪ | بله | +| حرکت مخالف 1٪ قیمت پایه | 55.884٪ | بله | +| کارمزد دو برابر | 56.175٪ | بله | +| کارمزد سه برابر | 55.796٪ | بله | +| نرخ سد 45٪ | 56.558٪ | بله | + +### منابع + +- کارمزد فروش سهم ۰٫۹۶۴٪ و خرید ۰٫۴۶۴٪ (کارگزاری‌ها/خانِ سرمایه)، کارمزد اختیار ≈۰٫۱۰۳٪ هر طرف و اعمال ۰٫۰۵٪ (بازار مشتقه). + +## 4. اوراق تبعی (اختیار فروش تضمینی) (Guaranteed put-back (tabei)) + +**دسته:** قطعی (تعهد ناشر/بازارساز) + +### اصل کار +سهم را می‌خری و رویش «تبعی» (اختیار فروش با تعهد بازخرید) می‌خری. از این لحظه، کمترین بازدهی‌ات تا سررسید قفل است: حتی اگر سهم بریزد، تبعی به قیمت اعمال خریداری می‌شود. رشد بالاتر از اعمال هم مال توست. + +### چه وقت استفاده می‌شود +وقتی کمینهٔ بازده تبعی از نرخ سد بگذرد؛ برای پرتفوی کم‌ریسک و نگه‌دارید تا سررسید عالی است. قدرت اهرمی هم دارد (هموطن ≈۱٫۳ برابر، همیار ≈۱٫۲ برابر). + +### چه چیزی لازم دارد +دسترسی به نمادهای تبعی + نقدشوندگی همان نماد تبعی (این نقطهٔ ضعف اصلی است). + +### قاعدهٔ بستن موقعیت + +- برداشت سود: اگر سهم از قیمت اعمال بالا رفت، سهم را در بازار بفروشید و تبعی را رها کن (کمترین بازده دیگر لازم نیست). +- توقف ضرر: ذاتاً لازم نیست — تعهد بازخرید در اعمال، سقف ضرر است؛ ولی اگر ناشر به تعهدش عمل نکند یا نماد بسته شود، این توقف می‌شکند. +- سررسید: در پنجرهٔ اعمال، سهم را به قیمت اعمال به تبعی بفروشید (یا بسته به نوع تبعی، تسویهٔ تفاوت). +- قاعدهٔ بستن: شمارهٔ پنجرهٔ اعمال را از قبل در تقویم بگذارید؛ دیرکرد در اعمال = از دست دادن تضمین. + +### ریسک‌ها + +- ریسک تعهد (ناشر/بازارساز) و ریسک عملیاتی پنجرهٔ اعمال. +- نقدشوندگی: اگر تبعی نقدشونده نباشد، بازده روی کاغذ می‌ماند. +- کارمزد دو سر و مالیات فروش سهم از کمینهٔ بازده کم می‌شود. + +### حسابرسی عددهای امروز (با موتور ایستگاه) + +- عددهای ورودی: قیمت سهم 9,800 · قیمت پوت 40 · قیمت اعمال تضمینی 14,210 · روز تا سررسید 365 +- فرمول: هزینهٔ خرید = 9,800×(۱+0.464٪) + پوت 40 = 9,885.47 · دریافتی تضمینی = 14,210×(۱−0.964٪) = 14,073.02 +- **پاسخ موتور:** 42.361 ٪ سالانه (کمینهٔ تضمینی) +- محاسبهٔ دستی دوم: 42.361 — موافق ✅ + - بازده دوره = (دریافتی تضمینی − هزینهٔ خرید) ÷ هزینهٔ خرید = 42.361٪ + - بازده سالانه = (۱+بازده دوره)^(۳۶۵÷365) − ۱ = 42.361٪ +- کارمزد لحاظ‌شده: 1.428٪ · نرخ سد: 35.0٪ · حاشیه: 7.361 واحد درصد +- داوری: «می‌ماند» با حاشیهٔ 7.361 واحد درصد: تا وقتی نرخ سد زیر 42.361٪ بماند، این معامله ارزش بررسی دارد. +- تحمل کارمزد: اگر کارمزد کل از 4.67 برابر امروز بگذرد، این راهبرد از نرخ سد می‌افتد. +- فاصله تا اخطاریهٔ مارجین‌کال: 6.00٪ حرکت مخالف (پول در معرض خطر: 2,952 ریال بر پایهٔ 70.0٪ حد نگهداری) + +### تاب‌آوری زیر شوک‌ها (80.0٪ شوک‌ها را رد کرد) + +| شوک | نتیجه | می‌ماند؟ | +| --- | --- | --- | +| لغزش اجرا ۰٫۵٪ | 41.652٪ | بله | +| حرکت مخالف 1٪ قیمت پایه | 40.957٪ | بله | +| کارمزد دو برابر | 40.329٪ | بله | +| کارمزد سه برابر | 38.317٪ | بله | +| نرخ سد 45٪ | 42.361٪ | نه | + +### منابع + +- ساختار تبعی و اهرم‌ها: گزارش‌های بازار سرمایه (سهم‌بورس/رصد)، اسناد اوراق تبعی ناشر. + +## 5. باکس اسپرد (چهار پایه، بدون ریسک جهت) (Box spread) + +**دسته:** قطعی (پرداخت ثابت در سررسید) + +### اصل کار +چهار اختیار را طوری می‌چینی که پرداخت سررسید همیشه ثابت باشد (مثلاً ۳٬۰۰۰). آن‌وقت معامله به «خرید یک قرض قطعی با تخفیف» تبدیل می‌شود؛ ریسک جهت و نوسان صفر است. + +### چه وقت استفاده می‌شود +وقتی «بدهی امروزِ» باکس از ارزش فعلی پرداخت قطعی‌اش کمتر باشد، یعنی بازار کوپن بالاتر از نرخ سد می‌دهد. + +### چه چیزی لازم دارد +چهار پایهٔ نقدشونده با اسپرد کم — وگرنه سرسری می‌افتد. + +### قاعدهٔ بستن موقعیت + +- برداشت سود: نگه‌داشتن تا سررسید (پرداخت قطعی)؛ یا اگر بدهی بازار بزرگ‌تر شد، بستن زودهنگام با سود. +- توقف ضرر: ذاتاً ندارد؛ اما اگر نقدشوندگی یکی از پایه‌ها خشک شود، خروج زودهنگام ممکن نمی‌شود. +- سررسید: بستن در سررسید (تحویل/تسویهٔ هر چهار پایه). +- قاعدهٔ بستن: هرچه بدهی خالص کوچک‌تر باشد، حساسیت به لغزش اجرا بیشتر است؛ باکسی که بدهی‌اش فقط ۲۸۰ روی سپردهٔ ۳۰۰ است، با ۰٫۵٪ لغزش اجرا می‌افتد. + +### ریسک‌ها + +- حساسیت شدید به لغزش اجرا و اسپرد (آزمون شوک: ۰٪ تاب‌آوری زیر لغزش ۰٫۵٪). +- کارمزد چهار طرف. +- نبود امکان فروش استقراضی برای سمت معکوس. + +### حسابرسی عددهای امروز (با موتور ایستگاه) + +- عددهای ورودی: کال اعمال پایین 300 · پوت اعمال پایین 430 · کال اعمال بالا 175 · پوت اعمال بالا 585 · اعمال پایین 1,200 · اعمال بالا 1,500 · روز تا سررسید 45 +- فرمول: بدهی امروز = 280 · دریافتی قطعی در سررسید = 300 · کارمزد چهار طرف = 1.535 +- **پاسخ موتور:** 67.868 ٪ سالانه +- محاسبهٔ دستی دوم: 67.868 — موافق ✅ + - سود خالص = دریافتی − بدهی − کارمزد = 18.47 + - بازده سالانه = (۱+سود÷بدهی)^(۳۶۵÷45) − ۱ = 67.868٪ +- کارمزد لحاظ‌شده: 0.412٪ · نرخ سد: 35.0٪ · حاشیه: 32.868 واحد درصد +- داوری: «می‌ماند» با حاشیهٔ 32.868 واحد درصد: تا وقتی نرخ سد زیر 67.868٪ بماند، این معامله ارزش بررسی دارد. +- تحمل کارمزد: اگر کارمزد کل از 6.15 برابر امروز بگذرد، این راهبرد از نرخ سد می‌افتد. +- فاصله تا اخطاریهٔ مارجین‌کال: 6.00٪ حرکت مخالف (پول در معرض خطر: 75,000 ریال بر پایهٔ 70.0٪ حد نگهداری) + +### تاب‌آوری زیر شوک‌ها (100.0٪ شوک‌ها را رد کرد) + +| شوک | نتیجه | می‌ماند؟ | +| --- | --- | --- | +| لغزش اجرا ۰٫۵٪ | 35.659٪ | بله | +| حرکت مخالف 1٪ قیمت پایه | 67.868٪ | بله | +| کارمزد دو برابر | 60.994٪ | بله | +| کارمزد سه برابر | 54.367٪ | بله | +| نرخ سد 45٪ | 67.868٪ | بله | + +### منابع + +- ساختار باکس/تساوی: تئوری آربیتراژ آپشن (پاریتی)، ابزارهای مقایسهٔ آپشن بورس کالا. + +## 6. تبدیل تساوی پوت-کال (Put-call parity conversion) + +**دسته:** قطعی (در لحظهٔ اجرا)، ولی کم‌بسامد + +### اصل کار +قانون تساوی می‌گوید: کال − پوت باید برابر باشد با سهم − ارزش فعلی اعمال. اگر شکاف از کارمزد سه پایه بزرگ‌تر شد، با خرید سهم + پوت و فروش کال، بازار را در یک قفس قفل می‌کنید. + +### چه وقت استفاده می‌شود +شکاف‌های بزرگ (وقتی یکی از پایه‌ها نقدشوندگی‌اش را از دست داده). در شرایط عادی، کارمزد سه پایه شکاف را می‌خورد و جواب «نه» است. + +### چه چیزی لازم دارد +سه پایهٔ هم‌سررسید با اعمال یکسان + امکان فروش اختیار (وجه تضمین). + +### قاعدهٔ بستن موقعیت + +- باد ventilation صریح: اگر شکاف بسته شد، سود را بردارید و ببندید. +- توقف ضرر: انحراف بیش از حد انتظار = نشانهٔ دادهٔ اشتباه یا اعمال متفاوت سررسید؛ جای صبر نیست، بستن. +- سررسید: نگه‌داشتن تا سررسید، اعمال خودکار تعهدها. +- قاعدهٔ بستن: سمت معکوس (reverse conversion) در ایران ممکن نیست؛ چون فروش استقراضی سهم وجود ندارد. پس فقط یک جهت. + +### ریسک‌ها + +- کارمزد سه پایه؛ شکاف کاذب از دادهٔ بی‌کیفیت. +- عدم امکان اجرای سمت معکوس (محدودیت بازار ایران). +- پورتال‌های داده اشتباه زیاد دارند؛ اول با داوری سیگنال، اعتبار داده را بسنجید. + +### حسابرسی عددهای امروز (با موتور ایستگاه) + +- عددهای ورودی: قیمت کال 420 · قیمت پوت 380 · قیمت سهم 9,000 · قیمت اعمال 9,000 · روز تا سررسید 30 · نرخ بدون ریسک 39.0٪ +- فرمول: سمت چپ کال−پوت = 40 · سمت راست سهم−ارزش فعلی اعمال = 283.92 · شکاف = -243.92 · کارمزد سه پایه = 10.09 +- **پاسخ موتور:** نه بله/نه +- محاسبهٔ دستی دوم: -254.01 — موافق ✅ + - اختلاف قابل برداشت = شکاف − کارمزد = -254.01 + - داوری: صرفه ندارد — سمت معکوس در ایران ممکن نیست (فروش استقراضی نداریم) +- کارمزد لحاظ‌شده: 0.309٪ · نرخ سد: 35.0٪ · حاشیه: None واحد درصد +- داوری: امروز «نه»: انحراف تساوی از کارمزد سه پایه کمتر است، پس چیزی برای برداشتن نیست. هر وقت شکاف بزرگ‌تر شد، همین خط دوباره چک می‌شود. +- تحمل کارمزد: تساوی به کارمزد به‌شدت حساس است؛ کارمزد سه پایه همیشه اول کسر می‌شود و «نه» فعلی هم از همین است. +- فاصله تا اخطاریهٔ مارجین‌کال: 6.00٪ حرکت مخالف (پول در معرض خطر: 2,700 ریال بر پایهٔ 70.0٪ حد نگهداری) + +### تاب‌آوری زیر شوک‌ها (0.0٪ شوک‌ها را رد کرد) + +| شوک | نتیجه | می‌ماند؟ | +| --- | --- | --- | +| لغزش اجرا ۰٫۵٪ | صرفه ندارد | نه | +| حرکت مخالف 1٪ قیمت پایه | صرفه ندارد | نه | +| کارمزد دو برابر | صرفه ندارد | نه | +| کارمزد سه برابر | صرفه ندارد | نه | +| نرخ سد 45٪ | صرفه ندارد | نه | + +### منابع + +- تساوی پوت-کال و کژشکاف‌ها: مبانی مالی مشتقه؛ فیلترهای مقایسه‌ای ابزارهای آپشن. + +## 7. صندوق اهرمی و نرخ مبنای درآمد ثابت (Leveraged fund / fixed-income baseline) + +**دسته:** ریسکی (اهرم) + خط پایهٔ قطعی + +### اصل کار +دو کار متفاوت: (الف) نرخ مؤثر اوراق/صندوق درآمد ثابت را «خط پایهٔ» خودتان بگذارید؛ هر راهبردی که از آن نمی‌گذرد، ارزش ریسک ندارد. (ب) صندوق اهرمی بازده بازار را چند برابر می‌کند، هم بالا و هم پایین. + +### چه وقت استفاده می‌شود +خط پایه همیشه؛ صندوق اهرمی فقط وقتی بازوی تحمل ریزش دارید (اهرم روزانه تسویه می‌شود). + +### چه چیزی لازم دارد +دسترسی به صندوق‌ها/اوراق؛ برای اهرمی، تحمل نوسان. + +### قاعدهٔ بستن موقعیت + +- خط پایه: نگه‌داشتن تا سررسید یا فروش در صندوق (نقدشوندگی روزانه). +- اهرمی: حد ضرر سخت (مثلاً ۱۰٪) بگذارید و از تسویهٔ روزانه غافل نشو. +- قاعدهٔ بستن: اهرم را فقط با پولی ببر که ریزش ۳۰٪ برایت فاجعه نیست. + +### ریسک‌ها + +- اهرم، زیان را همان‌قدر بزرگ می‌کند که سود را. +- کارمزد مدیریت صندوق از بازده کم می‌کند. +- تسویهٔ روزانه در ابزارهای اهرمی/آتی می‌تواند پیش از برگشت بازار، شما را بیرون بیندازد. + +### منابع + +- بازده مؤثر صندوق درآمد ثابت شهریور ۱۴۰۵: ۳۹ تا ۴۰٪؛ سپردهٔ بانکی ۲۰٫۵ تا ۲۲٫۵٪ (گزارش‌های بازار، ناب‌ز قیمت/بورس‌نیوز). + +## 8. فروش اختیار فروش بدون پوشش (کارگاه بقا) (Naked short put) + +**دسته:** ریسکی — برای آموزش ریاضیِ ورشکستگی + +### اصل کار +پرمیوم می‌گیرید و تعهد می‌دهی که در قیمت اعمال بخرید. اگر بازار بالای اعمال بماند، پرمیوم مال توست؛ اگر بریزد، زیان تقریباً بی‌سقف است. وجه تضمین اولیه ≈۲۰٪ ارزش قرارداد، حد نگهداری ۷۰٪ آن، تسویهٔ روزانه. + +### چه وقت استفاده می‌شود +فقط برای کسی که بقا را می‌فهمد (اندازهٔ کوچک و نقد آماده). + +### چه چیزی لازم دارد +وجه تضمین + تحمل مارجین‌کال. + +### قاعدهٔ بستن موقعیت + +- برداشت سود: ۵۰٪ پرمیوم (خرید بازخرید). +- توقف ضرر: قبل از رسیدن به فاصلهٔ اخطاریهٔ مارجین‌کال ببندید (عدد فاصله در حسابرسی همین جزوه آمده). +- سررسید: اگر زیر اعمال بماند، تسویه/خرید سهم. +- قاعدهٔ بستن: هرگز با تمام وجه تضمین یک موقعیت نگیر؛ تسویهٔ روزانه، حساب را وسط راه می‌بندد. + +### ریسک‌ها + +- زیان دنباله (tail risk) و اخطاریهٔ مارجین‌کال. +- ریسک ابلاغی/قانونی بازار مشتقه. +- خودفریبی «پرمیوم همیشه مال من است». + +### منابع + +- حداقل وجه تضمین ۷۰٪ و اخطاریهٔ مارجین‌کال (بورس کالا)، وجه تضمین فروشندهٔ اختیار ≈۲۰٪ ارزش قرارداد. + +## 9. درآمد بدون سرمایه: فروش «تصمیم و شاهد» (Selling verified decisions (service)) + +**دسته:** درآمدی (بدون بازار) — اهرم اصلی شما + +### اصل کار +اگر ریاضیِ بالا را دارید، می‌توانی بدون سرمایه از آن درآمد بسازی: برای کارگزاری، شرکت یا معامله‌گر، سیگنال‌های ابزارهای دیگر را «داوری» کنید و شاهد بدهی: این سیگنال با کارمزد واقعی، وجه تضمین و نقدشوندگی واقعی می‌ماند یا می‌افتد. + +### چه وقت استفاده می‌شود +همین حالا. هیچ بازار، هیچ سرمایه و هیچ مجوزی لازم نیست؛ فقط همین ایستگاه و توانایی توضیح دادن. + +### چه چیزی لازم دارد +ارائهٔ شاهد قابل راستی‌آزمایی (زنجیرهٔ هش، آزمون دو-روشی، تضمین ساختاری) و صداقت در گفتن «نمی‌دانم». + +### قاعدهٔ بستن موقعیت + +- این «موقعیت» موقعیت بازار نیست؛ موقعیت شغلی است. +- قاعدهٔ بستن: اگر شاهد از کار افتاد یا مشتری عدد کارگزاری متفاوتی گرفت، فوراً اعلام کن و اصلاح کن — اعتماد، تنها دارایی این کار است. + +### ریسک‌ها + +- هیچ سود تضمینی‌ای در بازار نیست؛ درآمد شما از «شاهد» می‌آید، نه از وعدهٔ سود. +- بدون تضمین ساختاری، این کار به «سیگنال‌فروشی» تبدیل می‌شود — و اعتبار می‌سوزد. + +### منابع + +- سند تفاوت‌بگذارید و اعتماد: `08-differentiation-and-trust-fa.md` (سنجش ابزارهای موجود ایران: دیده‌بان آپشن، بامبو، آپشن‌اسکول). + +## پیوست: منابع، اعتبار و محدودیت‌ها + +فهرست کامل منابع و محدودیت‌های این جزوه در پروندهٔ `references-fa.md` در همین پوشه آمده است؛ هر عددی که برچسب روش ندارد، قابل استناد نیست. + +✍️ تهیه‌کنندهٔ جزوات: **Masoud Mojarabian** · 📱 +989126630554 · ✈️ Telegram: [Mojarabian](https://t.me/Mojarabian) · 📸 Instagram: [Mojarabian.Art](https://instagram.com/Mojarabian.Art) diff --git a/strategies/strategy-library.json b/strategies/strategy-library.json new file mode 100644 index 0000000000000000000000000000000000000000..078479b14607306382cd7ff15c439339bd9a6dbe --- /dev/null +++ b/strategies/strategy-library.json @@ -0,0 +1,921 @@ +{ + "version": "0.1.0", + "strategies": [ + { + "id": "basis", + "name": "مبنا / کری نقدی-آتی", + "en": "Cash-and-carry basis", + "class": "قطعی (در لحظهٔ ورود قفل می‌شود)", + "idea": "یک دارایی (یا صندوق) را نقد می‌خری و همان لحظه معادلش را در بازار آتی می‌فروشید. تفاوت قیمت آتی و نقدی، تا سررسید مال توست؛ چون دو طرف را همین حالا بسته‌ای، عدد در لحظهٔ ورود قفل است (به آن «بازده قفل‌شده» می‌گویند).", + "when": "وقتی قیمت آتی از نقدی به‌قدری بالاتر است که بعد از کارمزد دو طرف، از نرخ سد (بازده بی‌ریسک) بگذرد. این تفاوت معمولاً وقتی باز می‌شود که تقاضای آتی بالا رفته یا نقدشوندگی نقدی کم شده باشد.", + "requires": "دسترسی به بازار آتی، وجه تضمین فروشندهٔ آتی، و نقدشوندگی هر دو سر.", + "closing": [ + "برداشت سود: با رسیدن به ۵۰٪ بازده انتظاری، هر دو پا را هم‌زمان ببندید.", + "توقف ضرر: اگر قیمت پایه ۶٪ خلاف شما رفت (فاصله تا اخطاریهٔ مارجین‌کال)، ببندید؛ یا وجه تضمین اضافه کن، ولی آن‌وقت بازده کل پایین می‌آید.", + "سررسید: اگر هیچ‌کدام نخورد، در سررسید ببندید (تسویهٔ نقدی/فیزیکی بر پایهٔ قیمت تسویهٔ روز آخر).", + "قاعدهٔ طلایی: دو پا را هم‌زمان ببندید، وگرنه از «معاملهٔ قفل‌شده» به «معاملهٔ جهت‌دار» تبدیل می‌شود." + ], + "risks": [ + "اخطاریهٔ مارجین‌کال در پاى آتی (تسویهٔ روزانه).", + "گپ نقدشوندگی در سررسید و اسپرد بزرگ.", + "تغییر ابلاغیه/وجه تضمین وسط راه.", + "قیمت تسویهٔ روز آخر (میانگین وزنی نیم‌ساعت پایانی) نه قیمتی که شما دیده‌ای." + ], + "refs": [ + "قواعد وجه تضمین و تسویهٔ روزانهٔ بورس کالا (حداقل ۷۰٪ وجه تضمین اولیه، اخطاریهٔ مارجین‌کال) — جمع‌بندی‌شده در `05-data-routes-fa.md` و محدودیت‌های معاملاتی ایران." + ] + }, + { + "id": "covered_call", + "name": "پوشش‌داده‌شده (فروش اختیار خرید روی سهم)", + "en": "Covered call", + "class": "مدل‌محور + درآمد پرمیوم", + "idea": "سهم را دارید و روی همان سهم اختیار خرید می‌فروشید. پرمیوم را همین حالا می‌گیرید؛ در عوض سقف سود شما را روی قیمت اعمال قفل می‌کنید. اگر سهم زیر اعمال بماند، پرمیوم خالص سود توست.", + "when": "بازاری که فکر می‌کنید تا سررسید صعود تند ندارد، ولی نوسان (و بنابراین پرمیوم) گران است. بازده پرمیوم سالانه‌شده باید از نرخ سد بگذرد.", + "requires": "سهم + دسترسی به بازار اختیار + کارمزد پایین (این راهبرد به کارمزد حساس است).", + "closing": [ + "برداشت سود: ۵۰٪ بازده انتظاری، یا وقتی پرمیوم باقی‌مانده به کمتر از ۲۰٪ پرمیوم اولیه رسید (خرید بازخرید اختیار).", + "توقف ضرر: روی خودِ سهم، همان حد ضرر سهم؛ پرمیوم فقط کمی آن را نرم می‌کند (پرمیوم ۴۰۰ روی سهم ۷٬۰۰۰ فقط ۵٫۷٪ حاشیه است).", + "سررسید: اگر اعمال شد، سهم در قیمت اعمال تحویل می‌رود؛ اگر نشد، اختیار بی‌ارزش تمام می‌شود و سهم می‌ماند.", + "قاعدهٔ بستن: پیش از سررسید و اگر سهم به اعمال نزدیک شد، یا بپذیر تحویل، یا اختیار را بازخرید کن — تصمیم را به روز آخر نگذار." + ], + "risks": [ + "سقف سود (صعود تند، شما را از سود باز می‌دارد).", + "ریسک نزولی سهم تقریباً کامل می‌ماند.", + "کارمزد سهم + کارمزد اختیار + مالیات فروش سهم از پرمیوم کم می‌شود." + ], + "refs": [ + "کارمزد فروش سهم ۰٫۹۶۴٪ و خرید ۰٫۴۶۴٪ (کارگزاری‌ها/خانِ سرمایه)، کارمزد اختیار ≈۰٫۱۰۳٪ هر طرف و اعمال ۰٫۰۵٪ (بازار مشتقه)." + ] + }, + { + "id": "tabei", + "name": "اوراق تبعی (اختیار فروش تضمینی)", + "en": "Guaranteed put-back (tabei)", + "class": "قطعی (تعهد ناشر/بازارساز)", + "idea": "سهم را می‌خری و رویش «تبعی» (اختیار فروش با تعهد بازخرید) می‌خری. از این لحظه، کمترین بازدهی‌ات تا سررسید قفل است: حتی اگر سهم بریزد، تبعی به قیمت اعمال خریداری می‌شود. رشد بالاتر از اعمال هم مال توست.", + "when": "وقتی کمینهٔ بازده تبعی از نرخ سد بگذرد؛ برای پرتفوی کم‌ریسک و نگه‌دارید تا سررسید عالی است. قدرت اهرمی هم دارد (هموطن ≈۱٫۳ برابر، همیار ≈۱٫۲ برابر).", + "requires": "دسترسی به نمادهای تبعی + نقدشوندگی همان نماد تبعی (این نقطهٔ ضعف اصلی است).", + "closing": [ + "برداشت سود: اگر سهم از قیمت اعمال بالا رفت، سهم را در بازار بفروشید و تبعی را رها کن (کمترین بازده دیگر لازم نیست).", + "توقف ضرر: ذاتاً لازم نیست — تعهد بازخرید در اعمال، سقف ضرر است؛ ولی اگر ناشر به تعهدش عمل نکند یا نماد بسته شود، این توقف می‌شکند.", + "سررسید: در پنجرهٔ اعمال، سهم را به قیمت اعمال به تبعی بفروشید (یا بسته به نوع تبعی، تسویهٔ تفاوت).", + "قاعدهٔ بستن: شمارهٔ پنجرهٔ اعمال را از قبل در تقویم بگذارید؛ دیرکرد در اعمال = از دست دادن تضمین." + ], + "risks": [ + "ریسک تعهد (ناشر/بازارساز) و ریسک عملیاتی پنجرهٔ اعمال.", + "نقدشوندگی: اگر تبعی نقدشونده نباشد، بازده روی کاغذ می‌ماند.", + "کارمزد دو سر و مالیات فروش سهم از کمینهٔ بازده کم می‌شود." + ], + "refs": [ + "ساختار تبعی و اهرم‌ها: گزارش‌های بازار سرمایه (سهم‌بورس/رصد)، اسناد اوراق تبعی ناشر." + ] + }, + { + "id": "box", + "name": "باکس اسپرد (چهار پایه، بدون ریسک جهت)", + "en": "Box spread", + "class": "قطعی (پرداخت ثابت در سررسید)", + "idea": "چهار اختیار را طوری می‌چینی که پرداخت سررسید همیشه ثابت باشد (مثلاً ۳٬۰۰۰). آن‌وقت معامله به «خرید یک قرض قطعی با تخفیف» تبدیل می‌شود؛ ریسک جهت و نوسان صفر است.", + "when": "وقتی «بدهی امروزِ» باکس از ارزش فعلی پرداخت قطعی‌اش کمتر باشد، یعنی بازار کوپن بالاتر از نرخ سد می‌دهد.", + "requires": "چهار پایهٔ نقدشونده با اسپرد کم — وگرنه سرسری می‌افتد.", + "closing": [ + "برداشت سود: نگه‌داشتن تا سررسید (پرداخت قطعی)؛ یا اگر بدهی بازار بزرگ‌تر شد، بستن زودهنگام با سود.", + "توقف ضرر: ذاتاً ندارد؛ اما اگر نقدشوندگی یکی از پایه‌ها خشک شود، خروج زودهنگام ممکن نمی‌شود.", + "سررسید: بستن در سررسید (تحویل/تسویهٔ هر چهار پایه).", + "قاعدهٔ بستن: هرچه بدهی خالص کوچک‌تر باشد، حساسیت به لغزش اجرا بیشتر است؛ باکسی که بدهی‌اش فقط ۲۸۰ روی سپردهٔ ۳۰۰ است، با ۰٫۵٪ لغزش اجرا می‌افتد." + ], + "risks": [ + "حساسیت شدید به لغزش اجرا و اسپرد (آزمون شوک: ۰٪ تاب‌آوری زیر لغزش ۰٫۵٪).", + "کارمزد چهار طرف.", + "نبود امکان فروش استقراضی برای سمت معکوس." + ], + "refs": [ + "ساختار باکس/تساوی: تئوری آربیتراژ آپشن (پاریتی)، ابزارهای مقایسهٔ آپشن بورس کالا." + ] + }, + { + "id": "parity", + "name": "تبدیل تساوی پوت-کال", + "en": "Put-call parity conversion", + "class": "قطعی (در لحظهٔ اجرا)، ولی کم‌بسامد", + "idea": "قانون تساوی می‌گوید: کال − پوت باید برابر باشد با سهم − ارزش فعلی اعمال. اگر شکاف از کارمزد سه پایه بزرگ‌تر شد، با خرید سهم + پوت و فروش کال، بازار را در یک قفس قفل می‌کنید.", + "when": "شکاف‌های بزرگ (وقتی یکی از پایه‌ها نقدشوندگی‌اش را از دست داده). در شرایط عادی، کارمزد سه پایه شکاف را می‌خورد و جواب «نه» است.", + "requires": "سه پایهٔ هم‌سررسید با اعمال یکسان + امکان فروش اختیار (وجه تضمین).", + "closing": [ + "باد ventilation صریح: اگر شکاف بسته شد، سود را بردارید و ببندید.", + "توقف ضرر: انحراف بیش از حد انتظار = نشانهٔ دادهٔ اشتباه یا اعمال متفاوت سررسید؛ جای صبر نیست، بستن.", + "سررسید: نگه‌داشتن تا سررسید، اعمال خودکار تعهدها.", + "قاعدهٔ بستن: سمت معکوس (reverse conversion) در ایران ممکن نیست؛ چون فروش استقراضی سهم وجود ندارد. پس فقط یک جهت." + ], + "risks": [ + "کارمزد سه پایه؛ شکاف کاذب از دادهٔ بی‌کیفیت.", + "عدم امکان اجرای سمت معکوس (محدودیت بازار ایران).", + "پورتال‌های داده اشتباه زیاد دارند؛ اول با داوری سیگنال، اعتبار داده را بسنجید." + ], + "refs": [ + "تساوی پوت-کال و کژشکاف‌ها: مبانی مالی مشتقه؛ فیلترهای مقایسه‌ای ابزارهای آپشن." + ] + }, + { + "id": "leveraged_fund", + "name": "صندوق اهرمی و نرخ مبنای درآمد ثابت", + "en": "Leveraged fund / fixed-income baseline", + "class": "ریسکی (اهرم) + خط پایهٔ قطعی", + "idea": "دو کار متفاوت: (الف) نرخ مؤثر اوراق/صندوق درآمد ثابت را «خط پایهٔ» خودتان بگذارید؛ هر راهبردی که از آن نمی‌گذرد، ارزش ریسک ندارد. (ب) صندوق اهرمی بازده بازار را چند برابر می‌کند، هم بالا و هم پایین.", + "when": "خط پایه همیشه؛ صندوق اهرمی فقط وقتی بازوی تحمل ریزش دارید (اهرم روزانه تسویه می‌شود).", + "requires": "دسترسی به صندوق‌ها/اوراق؛ برای اهرمی، تحمل نوسان.", + "closing": [ + "خط پایه: نگه‌داشتن تا سررسید یا فروش در صندوق (نقدشوندگی روزانه).", + "اهرمی: حد ضرر سخت (مثلاً ۱۰٪) بگذارید و از تسویهٔ روزانه غافل نشو.", + "قاعدهٔ بستن: اهرم را فقط با پولی ببر که ریزش ۳۰٪ برایت فاجعه نیست." + ], + "risks": [ + "اهرم، زیان را همان‌قدر بزرگ می‌کند که سود را.", + "کارمزد مدیریت صندوق از بازده کم می‌کند.", + "تسویهٔ روزانه در ابزارهای اهرمی/آتی می‌تواند پیش از برگشت بازار، شما را بیرون بیندازد." + ], + "refs": [ + "بازده مؤثر صندوق درآمد ثابت شهریور ۱۴۰۵: ۳۹ تا ۴۰٪؛ سپردهٔ بانکی ۲۰٫۵ تا ۲۲٫۵٪ (گزارش‌های بازار، ناب‌ز قیمت/بورس‌نیوز)." + ] + }, + { + "id": "naked_put", + "name": "فروش اختیار فروش بدون پوشش (کارگاه بقا)", + "en": "Naked short put", + "class": "ریسکی — برای آموزش ریاضیِ ورشکستگی", + "idea": "پرمیوم می‌گیرید و تعهد می‌دهی که در قیمت اعمال بخرید. اگر بازار بالای اعمال بماند، پرمیوم مال توست؛ اگر بریزد، زیان تقریباً بی‌سقف است. وجه تضمین اولیه ≈۲۰٪ ارزش قرارداد، حد نگهداری ۷۰٪ آن، تسویهٔ روزانه.", + "when": "فقط برای کسی که بقا را می‌فهمد (اندازهٔ کوچک و نقد آماده).", + "requires": "وجه تضمین + تحمل مارجین‌کال.", + "closing": [ + "برداشت سود: ۵۰٪ پرمیوم (خرید بازخرید).", + "توقف ضرر: قبل از رسیدن به فاصلهٔ اخطاریهٔ مارجین‌کال ببندید (عدد فاصله در حسابرسی همین جزوه آمده).", + "سررسید: اگر زیر اعمال بماند، تسویه/خرید سهم.", + "قاعدهٔ بستن: هرگز با تمام وجه تضمین یک موقعیت نگیر؛ تسویهٔ روزانه، حساب را وسط راه می‌بندد." + ], + "risks": [ + "زیان دنباله (tail risk) و اخطاریهٔ مارجین‌کال.", + "ریسک ابلاغی/قانونی بازار مشتقه.", + "خودفریبی «پرمیوم همیشه مال من است»." + ], + "refs": [ + "حداقل وجه تضمین ۷۰٪ و اخطاریهٔ مارجین‌کال (بورس کالا)، وجه تضمین فروشندهٔ اختیار ≈۲۰٪ ارزش قرارداد." + ] + }, + { + "id": "income_no_capital", + "name": "درآمد بدون سرمایه: فروش «تصمیم و شاهد»", + "en": "Selling verified decisions (service)", + "class": "درآمدی (بدون بازار) — اهرم اصلی شما", + "idea": "اگر ریاضیِ بالا را دارید، می‌توانی بدون سرمایه از آن درآمد بسازی: برای کارگزاری، شرکت یا معامله‌گر، سیگنال‌های ابزارهای دیگر را «داوری» کنید و شاهد بدهی: این سیگنال با کارمزد واقعی، وجه تضمین و نقدشوندگی واقعی می‌ماند یا می‌افتد.", + "when": "همین حالا. هیچ بازار، هیچ سرمایه و هیچ مجوزی لازم نیست؛ فقط همین ایستگاه و توانایی توضیح دادن.", + "requires": "ارائهٔ شاهد قابل راستی‌آزمایی (زنجیرهٔ هش، آزمون دو-روشی، تضمین ساختاری) و صداقت در گفتن «نمی‌دانم».", + "closing": [ + "این «موقعیت» موقعیت بازار نیست؛ موقعیت شغلی است.", + "قاعدهٔ بستن: اگر شاهد از کار افتاد یا مشتری عدد کارگزاری متفاوتی گرفت، فوراً اعلام کن و اصلاح کن — اعتماد، تنها دارایی این کار است." + ], + "risks": [ + "هیچ سود تضمینی‌ای در بازار نیست؛ درآمد شما از «شاهد» می‌آید، نه از وعدهٔ سود.", + "بدون تضمین ساختاری، این کار به «سیگنال‌فروشی» تبدیل می‌شود — و اعتبار می‌سوزد." + ], + "refs": [ + "سند تفاوت‌بگذارید و اعتماد: `08-differentiation-and-trust-fa.md` (سنجش ابزارهای موجود ایران: دیده‌بان آپشن، بامبو، آپشن‌اسکول)." + ] + } + ], + "audits": { + "basis": { + "ok": true, + "kind": "basis", + "given": [ + [ + "قیمت نقدی", + "20,000" + ], + [ + "قیمت آتی", + "22,800" + ], + [ + "روز تا سررسید", + "90" + ] + ], + "formula": "سود هر واحد = 22,800×(۱−0.12٪) − 20,000×(۱+0.12٪) = 2,748.64، بعد بازده دوره ÷ قیمت تمام‌شده و توان ۳۶۵÷90", + "steps": [ + "بازده دوره = سود ÷ قیمت تمام‌شده = 13.727٪", + "بازده سالانه = (۱+بازده دوره)^(۳۶۵÷90) − ۱ = 68.482٪", + "نرخ سد امروز 35.0٪ و حاشیه 33.482 واحد درصد است" + ], + "answer": 68.482, + "unit": "٪ سالانه", + "checks": [ + { + "note": "محاسبهٔ دستی با کسر دقیق (بدون کد موتور)", + "value": 68.482, + "agree": true + } + ], + "engine_value": 68.482, + "hand_value": 68.482, + "hand_agrees": true, + "closing": [ + { + "label": "برداشت سود", + "when": "50٪ بازده انتظاری", + "price": 21372.672, + "action": "خروج و ثبت در دفتر" + }, + { + "label": "توقف ضرر", + "when": "40٪ بازده انتظاری", + "price": 18901.862, + "action": "خروج بی‌مذاکره" + }, + { + "label": "سررسید", + "when": "90 روز", + "price": "—", + "action": "خروج در سررسید، حتی اگر هدف نخورده باشد" + } + ], + "verdict": "«می‌ماند» با حاشیهٔ 33.482 واحد درصد: تا وقتی نرخ سد زیر 68.482٪ بماند، این معامله ارزش بررسی دارد.", + "fees_pct": 0.24, + "hurdle_pct": 35.0, + "margin_pp": 33.482, + "survives": true, + "resilience_pct": 100.0, + "first_failure": "", + "fee_tolerance": { + "multiple": null, + "detail": "با کارمزد 12 برابر هم می‌ماند؛ کارمزد قاتل این راهبرد نیست.", + "survives_now": true + }, + "shocks": [ + { + "shock": "لغزش اجرا ۰٫۵٪", + "value": "61.786٪", + "survives": true, + "value_raw": 61.786 + }, + { + "shock": "حرکت مخالف 1٪ قیمت پایه", + "value": "61.818٪", + "survives": true, + "value_raw": 61.818 + }, + { + "shock": "کارمزد دو برابر", + "value": "66.850٪", + "survives": true, + "value_raw": 66.85 + }, + { + "shock": "کارمزد سه برابر", + "value": "65.234٪", + "survives": true, + "value_raw": 65.234 + }, + { + "shock": "نرخ سد 45٪", + "value": "68.482٪", + "survives": true, + "value_raw": 68.482 + } + ], + "margin_call": { + "ok": true, + "contracts": 1, + "margin_per_contract": 20000000.0, + "notional_per_contract": 100000000.0, + "maintenance": 0.7, + "maintenance_pct": 70.0, + "buffer_per_contract": 6000000.0, + "move_pct": 6.0, + "money_at_risk": 6000000.0, + "margin_locked": 20000000.0, + "formula": "فاصله = وجه تضمین × (۱ − حد نگهداری) ÷ ارزش قرارداد. اینجا: 20,000,000 × 0.30 ÷ 100,000,000 = 6.00٪ حرکت مخالف.", + "note": " حرکت مخالف به همین اندازه، حساب را به حد نگهداری می‌رساند و اخطاریه می‌آید؛ پس حد ضرر منطقی باید نزدیک‌تر از این عدد باشد، نه دورتر.", + "estimated": true, + "source": "حد نگهداری ۷۰٪ وجه تضمین اولیه (رویهٔ بورس) و تسویهٔ روزانه؛ عدد برای لحظهٔ ورود است. · ارزش قرارداد از وجه تضمین ثبت‌شده ÷ نسبت اولیهٔ 20٪ برآورد شد" + }, + "extras": { + "سود هر واحد": "2,748.64", + "بازده دوره": "13.727٪", + "کارمزد خرید و فروش": "0.12٪ + 0.12٪" + }, + "model_probability": { + "detail": "این راهبرد جهت‌دار نیست؛ احتمال «سود/زیان» معنا ندارد. عددش قفل‌شده است و ریسک اصلی‌اش مارجین‌کال و نقدشوندگی است." + } + }, + "covered_call": { + "ok": true, + "kind": "covered_call", + "given": [ + [ + "قیمت سهم", + "7,000" + ], + [ + "قیمت اعمال کال", + "7,600" + ], + [ + "پرمیوم کال", + "400" + ], + [ + "روز تا سررسید", + "45" + ] + ], + "formula": "پرمیوم خالص = 400×(۱−0.103٪) = 399.588 ÷ قیمت تمام‌شدهٔ سهم 7,032.48", + "steps": [ + "درآمد پرمیوم دوره = 5.682٪", + "بازده سالانهٔ پرمیوم = (۱+درآمد دوره)^(۳۶۵÷45) − ۱ = 56.558٪", + "سقف رشد سهم با این پوشش = 8.57٪ (بخش بازار-ریسک، جدا از پرمیوم)" + ], + "answer": 56.558, + "unit": "٪ سالانه (فقط پرمیوم)", + "checks": [ + { + "note": "محاسبهٔ دستی پرمیوم با کسر دقیق", + "value": 56.558, + "agree": true + } + ], + "engine_value": 56.558, + "hand_value": 56.558, + "hand_agrees": true, + "closing": [ + { + "label": "برداشت سود", + "when": "50٪ بازده انتظاری", + "price": 7198.87, + "action": "خروج و ثبت در دفتر" + }, + { + "label": "توقف ضرر", + "when": "40٪ بازده انتظاری", + "price": 6840.904, + "action": "خروج بی‌مذاکره" + }, + { + "label": "سررسید", + "when": "45 روز", + "price": "—", + "action": "خروج در سررسید، حتی اگر هدف نخورده باشد" + } + ], + "verdict": "«می‌ماند» با حاشیهٔ 21.558 واحد درصد: تا وقتی نرخ سد زیر 56.558٪ بماند، این معامله ارزش بررسی دارد.", + "fees_pct": 1.531, + "hurdle_pct": 35.0, + "margin_pp": 21.558, + "survives": true, + "resilience_pct": 100.0, + "first_failure": "", + "fee_tolerance": { + "multiple": null, + "detail": "با کارمزد 12 برابر هم می‌ماند؛ کارمزد قاتل این راهبرد نیست.", + "survives_now": true + }, + "shocks": [ + { + "shock": "لغزش اجرا ۰٫۵٪", + "value": "55.880٪", + "survives": true, + "value_raw": 55.88 + }, + { + "shock": "حرکت مخالف 1٪ قیمت پایه", + "value": "55.884٪", + "survives": true, + "value_raw": 55.884 + }, + { + "shock": "کارمزد دو برابر", + "value": "56.175٪", + "survives": true, + "value_raw": 56.175 + }, + { + "shock": "کارمزد سه برابر", + "value": "55.796٪", + "survives": true, + "value_raw": 55.796 + }, + { + "shock": "نرخ سد 45٪", + "value": "56.558٪", + "survives": true, + "value_raw": 56.558 + } + ], + "margin_call": { + "ok": true, + "contracts": 1, + "margin_per_contract": 7000.0, + "notional_per_contract": 35000.0, + "maintenance": 0.7, + "maintenance_pct": 70.0, + "buffer_per_contract": 2100.0, + "move_pct": 6.0, + "money_at_risk": 2100.0, + "margin_locked": 7000.0, + "formula": "فاصله = وجه تضمین × (۱ − حد نگهداری) ÷ ارزش قرارداد. اینجا: 7,000 × 0.30 ÷ 35,000 = 6.00٪ حرکت مخالف.", + "note": " حرکت مخالف به همین اندازه، حساب را به حد نگهداری می‌رساند و اخطاریه می‌آید؛ پس حد ضرر منطقی باید نزدیک‌تر از این عدد باشد، نه دورتر.", + "estimated": true, + "source": "حد نگهداری ۷۰٪ وجه تضمین اولیه (رویهٔ بورس) و تسویهٔ روزانه؛ عدد برای لحظهٔ ورود است. · ارزش قرارداد از وجه تضمین ثبت‌شده ÷ نسبت اولیهٔ 20٪ برآورد شد" + }, + "extras": { + "سقف رشد سهم": "8.57٪", + "ارزش دارد؟": "بله", + "بازده دوره": "5.682٪" + }, + "model_probability": { + "iv": { + "ok": true, + "sigma": 0.5286, + "sigma_pct": 52.86, + "model_price": 400.0, + "market_price": 400.0, + "gap_pct": 0.0, + "detail": "نوسان ضمنی سالانه ≈ 52.86٪ (از قیمت بازار 400.0000 و مدل بلک-شولز با نرخ 35.0٪). بازسازی مدل با همین نوسان: 400.0000." + }, + "prob_under_strike_pct": 61.92, + "prob_assigned_pct": 38.08, + "expected_move": 1299.23, + "detail": "با نوسان ضمنی 52.86٪، احتمال مدل‌محور اینکه سهم زیر اعمال بماند (پرمیوم کامل مال شما) ≈61.9٪ و احتمال اعمال‌شدن ≈38.1٪ است. این عدد «احتمال ریاضی تحت فرض بلک-شولز» است، نه پیش‌بینی بازار." + } + }, + "tabei": { + "ok": true, + "kind": "tabei", + "given": [ + [ + "قیمت سهم", + "9,800" + ], + [ + "قیمت پوت", + "40" + ], + [ + "قیمت اعمال تضمینی", + "14,210" + ], + [ + "روز تا سررسید", + "365" + ] + ], + "formula": "هزینهٔ خرید = 9,800×(۱+0.464٪) + پوت 40 = 9,885.47 · دریافتی تضمینی = 14,210×(۱−0.964٪) = 14,073.02", + "steps": [ + "بازده دوره = (دریافتی تضمینی − هزینهٔ خرید) ÷ هزینهٔ خرید = 42.361٪", + "بازده سالانه = (۱+بازده دوره)^(۳۶۵÷365) − ۱ = 42.361٪" + ], + "answer": 42.361, + "unit": "٪ سالانه (کمینهٔ تضمینی)", + "checks": [ + { + "note": "محاسبهٔ دستی با کسر دقیق (کارمزد سهم + پوت)", + "value": 42.361, + "agree": true + } + ], + "engine_value": 42.361, + "hand_value": 42.361, + "hand_agrees": true, + "closing": [ + { + "label": "برداشت سود", + "when": "50٪ بازده انتظاری", + "price": 11875.689, + "action": "خروج و ثبت در دفتر" + }, + { + "label": "توقف ضرر", + "when": "40٪ بازده انتظاری", + "price": 8139.449, + "action": "خروج بی‌مذاکره" + }, + { + "label": "سررسید", + "when": "365 روز", + "price": "—", + "action": "خروج در سررسید، حتی اگر هدف نخورده باشد" + } + ], + "verdict": "«می‌ماند» با حاشیهٔ 7.361 واحد درصد: تا وقتی نرخ سد زیر 42.361٪ بماند، این معامله ارزش بررسی دارد.", + "fees_pct": 1.428, + "hurdle_pct": 35.0, + "margin_pp": 7.361, + "survives": true, + "resilience_pct": 80.0, + "first_failure": "نرخ سد 45٪", + "fee_tolerance": { + "multiple": 4.668, + "detail": "اگر کارمزد کل از 4.67 برابر امروز بگذرد، این راهبرد از نرخ سد می‌افتد.", + "survives_now": true + }, + "shocks": [ + { + "shock": "لغزش اجرا ۰٫۵٪", + "value": "41.652٪", + "survives": true, + "value_raw": 41.652 + }, + { + "shock": "حرکت مخالف 1٪ قیمت پایه", + "value": "40.957٪", + "survives": true, + "value_raw": 40.957 + }, + { + "shock": "کارمزد دو برابر", + "value": "40.329٪", + "survives": true, + "value_raw": 40.329 + }, + { + "shock": "کارمزد سه برابر", + "value": "38.317٪", + "survives": true, + "value_raw": 38.317 + }, + { + "shock": "نرخ سد 45٪", + "value": "42.361٪", + "survives": false, + "value_raw": 42.361 + } + ], + "margin_call": { + "ok": true, + "contracts": 1, + "margin_per_contract": 9840.0, + "notional_per_contract": 49200.0, + "maintenance": 0.7, + "maintenance_pct": 70.0, + "buffer_per_contract": 2952.0, + "move_pct": 6.0, + "money_at_risk": 2952.0, + "margin_locked": 9840.0, + "formula": "فاصله = وجه تضمین × (۱ − حد نگهداری) ÷ ارزش قرارداد. اینجا: 9,840 × 0.30 ÷ 49,200 = 6.00٪ حرکت مخالف.", + "note": " حرکت مخالف به همین اندازه، حساب را به حد نگهداری می‌رساند و اخطاریه می‌آید؛ پس حد ضرر منطقی باید نزدیک‌تر از این عدد باشد، نه دورتر.", + "estimated": true, + "source": "حد نگهداری ۷۰٪ وجه تضمین اولیه (رویهٔ بورس) و تسویهٔ روزانه؛ عدد برای لحظهٔ ورود است. · ارزش قرارداد از وجه تضمین ثبت‌شده ÷ نسبت اولیهٔ 20٪ برآورد شد" + }, + "extras": { + "هزینهٔ خرید": "9,885.47", + "دریافتی تضمینی": "14,073.02" + }, + "model_probability": null + }, + "box": { + "ok": true, + "kind": "box", + "given": [ + [ + "کال اعمال پایین", + "300" + ], + [ + "پوت اعمال پایین", + "430" + ], + [ + "کال اعمال بالا", + "175" + ], + [ + "پوت اعمال بالا", + "585" + ], + [ + "اعمال پایین", + "1,200" + ], + [ + "اعمال بالا", + "1,500" + ], + [ + "روز تا سررسید", + "45" + ] + ], + "formula": "بدهی امروز = 280 · دریافتی قطعی در سررسید = 300 · کارمزد چهار طرف = 1.535", + "steps": [ + "سود خالص = دریافتی − بدهی − کارمزد = 18.47", + "بازده سالانه = (۱+سود÷بدهی)^(۳۶۵÷45) − ۱ = 67.868٪" + ], + "answer": 67.868, + "unit": "٪ سالانه", + "checks": [ + { + "note": "محاسبهٔ دستی با کسر دقیق روی چهار پایه", + "value": 67.868, + "agree": true + } + ], + "engine_value": 67.868, + "hand_value": 67.868, + "hand_agrees": true, + "closing": [ + { + "label": "برداشت سود", + "when": "50٪ بازده انتظاری", + "price": 1239.568, + "action": "خروج و ثبت در دفتر" + }, + { + "label": "توقف ضرر", + "when": "40٪ بازده انتظاری", + "price": 1168.345, + "action": "خروج بی‌مذاکره" + }, + { + "label": "سررسید", + "when": "45 روز", + "price": "—", + "action": "خروج در سررسید، حتی اگر هدف نخورده باشد" + } + ], + "verdict": "«می‌ماند» با حاشیهٔ 32.868 واحد درصد: تا وقتی نرخ سد زیر 67.868٪ بماند، این معامله ارزش بررسی دارد.", + "fees_pct": 0.412, + "hurdle_pct": 35.0, + "margin_pp": 32.868, + "survives": true, + "resilience_pct": 100.0, + "first_failure": "", + "fee_tolerance": { + "multiple": 6.155, + "detail": "اگر کارمزد کل از 6.15 برابر امروز بگذرد، این راهبرد از نرخ سد می‌افتد.", + "survives_now": true + }, + "shocks": [ + { + "shock": "لغزش اجرا ۰٫۵٪", + "value": "35.659٪", + "survives": true, + "value_raw": 35.659 + }, + { + "shock": "حرکت مخالف 1٪ قیمت پایه", + "value": "67.868٪", + "survives": true, + "value_raw": 67.868 + }, + { + "shock": "کارمزد دو برابر", + "value": "60.994٪", + "survives": true, + "value_raw": 60.994 + }, + { + "shock": "کارمزد سه برابر", + "value": "54.367٪", + "survives": true, + "value_raw": 54.367 + }, + { + "shock": "نرخ سد 45٪", + "value": "67.868٪", + "survives": true, + "value_raw": 67.868 + } + ], + "margin_call": { + "ok": true, + "contracts": 1, + "margin_per_contract": 250000.0, + "notional_per_contract": 1250000.0, + "maintenance": 0.7, + "maintenance_pct": 70.0, + "buffer_per_contract": 75000.0, + "move_pct": 6.0, + "money_at_risk": 75000.0, + "margin_locked": 250000.0, + "formula": "فاصله = وجه تضمین × (۱ − حد نگهداری) ÷ ارزش قرارداد. اینجا: 250,000 × 0.30 ÷ 1,250,000 = 6.00٪ حرکت مخالف.", + "note": " حرکت مخالف به همین اندازه، حساب را به حد نگهداری می‌رساند و اخطاریه می‌آید؛ پس حد ضرر منطقی باید نزدیک‌تر از این عدد باشد، نه دورتر.", + "estimated": true, + "source": "حد نگهداری ۷۰٪ وجه تضمین اولیه (رویهٔ بورس) و تسویهٔ روزانه؛ عدد برای لحظهٔ ورود است. · ارزش قرارداد از وجه تضمین ثبت‌شده ÷ نسبت اولیهٔ 20٪ برآورد شد" + }, + "extras": { + "بدهی": "280", + "دریافتی قطعی": "300", + "کارمزد چهار طرف": "1.535", + "سود خالص": "18.47" + }, + "model_probability": null + }, + "parity": { + "ok": true, + "kind": "parity", + "given": [ + [ + "قیمت کال", + "420" + ], + [ + "قیمت پوت", + "380" + ], + [ + "قیمت سهم", + "9,000" + ], + [ + "قیمت اعمال", + "9,000" + ], + [ + "روز تا سررسید", + "30" + ], + [ + "نرخ بدون ریسک", + "39.0٪" + ] + ], + "formula": "سمت چپ کال−پوت = 40 · سمت راست سهم−ارزش فعلی اعمال = 283.92 · شکاف = -243.92 · کارمزد سه پایه = 10.09", + "steps": [ + "اختلاف قابل برداشت = شکاف − کارمزد = -254.01", + "داوری: صرفه ندارد — سمت معکوس در ایران ممکن نیست (فروش استقراضی نداریم)" + ], + "answer": "نه", + "unit": "بله/نه", + "checks": [ + { + "note": "محاسبهٔ دستی: شکاف منهای کارمزد سه پایه", + "value": -254.01, + "agree": true + } + ], + "engine_value": null, + "hand_value": -254.01, + "hand_agrees": true, + "closing": [], + "verdict": "امروز «نه»: انحراف تساوی از کارمزد سه پایه کمتر است، پس چیزی برای برداشتن نیست. هر وقت شکاف بزرگ‌تر شد، همین خط دوباره چک می‌شود.", + "fees_pct": 0.309, + "hurdle_pct": 35.0, + "margin_pp": null, + "survives": false, + "resilience_pct": 0.0, + "first_failure": "از قبل زیر نرخ سد است", + "fee_tolerance": { + "multiple": null, + "detail": "تساوی به کارمزد به‌شدت حساس است؛ کارمزد سه پایه همیشه اول کسر می‌شود و «نه» فعلی هم از همین است.", + "survives_now": false + }, + "shocks": [ + { + "shock": "لغزش اجرا ۰٫۵٪", + "value": "صرفه ندارد", + "survives": false, + "value_raw": null + }, + { + "shock": "حرکت مخالف 1٪ قیمت پایه", + "value": "صرفه ندارد", + "survives": false, + "value_raw": null + }, + { + "shock": "کارمزد دو برابر", + "value": "صرفه ندارد", + "survives": false, + "value_raw": null + }, + { + "shock": "کارمزد سه برابر", + "value": "صرفه ندارد", + "survives": false, + "value_raw": null + }, + { + "shock": "نرخ سد 45٪", + "value": "صرفه ندارد", + "survives": false, + "value_raw": null + } + ], + "margin_call": { + "ok": true, + "contracts": 1, + "margin_per_contract": 9000.0, + "notional_per_contract": 45000.0, + "maintenance": 0.7, + "maintenance_pct": 70.0, + "buffer_per_contract": 2700.0, + "move_pct": 6.0, + "money_at_risk": 2700.0, + "margin_locked": 9000.0, + "formula": "فاصله = وجه تضمین × (۱ − حد نگهداری) ÷ ارزش قرارداد. اینجا: 9,000 × 0.30 ÷ 45,000 = 6.00٪ حرکت مخالف.", + "note": " حرکت مخالف به همین اندازه، حساب را به حد نگهداری می‌رساند و اخطاریه می‌آید؛ پس حد ضرر منطقی باید نزدیک‌تر از این عدد باشد، نه دورتر.", + "estimated": true, + "source": "حد نگهداری ۷۰٪ وجه تضمین اولیه (رویهٔ بورس) و تسویهٔ روزانه؛ عدد برای لحظهٔ ورود است. · ارزش قرارداد از وجه تضمین ثبت‌شده ÷ نسبت اولیهٔ 20٪ برآورد شد" + }, + "extras": { + "شکاف": "-243.92", + "کارمزد سه پایه": "10.09", + "اختلاف قابل برداشت": "-254.01" + }, + "model_probability": null + } + }, + "table": [ + { + "id": "basis", + "name": "مبنا / کری نقدی-آتی", + "class": "قطعی (در لحظهٔ ورود قفل می‌شود)", + "value": "68.482 ٪ سالانه", + "method": "قطعی/مدل‌محور (موتور ایستگاه + محاسبهٔ دستی دوم)", + "resilience": 100.0, + "survives": true, + "closing_count": 3 + }, + { + "id": "covered_call", + "name": "پوشش‌داده‌شده (فروش اختیار خرید روی سهم)", + "class": "مدل‌محور + درآمد پرمیوم", + "value": "56.558 ٪ سالانه (فقط پرمیوم) · احتمال ماندن زیر اعمال 61.92٪", + "method": "قطعی + مدل بلک-شولز (نوسان ضمنی از قیمت بازار)", + "resilience": 100.0, + "survives": true, + "closing_count": 3 + }, + { + "id": "tabei", + "name": "اوراق تبعی (اختیار فروش تضمینی)", + "class": "قطعی (تعهد ناشر/بازارساز)", + "value": "42.361 ٪ سالانه (کمینهٔ تضمینی)", + "method": "قطعی/مدل‌محور (موتور ایستگاه + محاسبهٔ دستی دوم)", + "resilience": 80.0, + "survives": true, + "closing_count": 3 + }, + { + "id": "box", + "name": "باکس اسپرد (چهار پایه، بدون ریسک جهت)", + "class": "قطعی (پرداخت ثابت در سررسید)", + "value": "67.868 ٪ سالانه", + "method": "قطعی/مدل‌محور (موتور ایستگاه + محاسبهٔ دستی دوم)", + "resilience": 100.0, + "survives": true, + "closing_count": 3 + }, + { + "id": "parity", + "name": "تبدیل تساوی پوت-کال", + "class": "قطعی (در لحظهٔ اجرا)، ولی کم‌بسامد", + "value": "نه", + "method": "قطعی/مدل‌محور (موتور ایستگاه + محاسبهٔ دستی دوم)", + "resilience": 0.0, + "survives": false, + "closing_count": 4 + }, + { + "id": "leveraged_fund", + "name": "صندوق اهرمی و نرخ مبنای درآمد ثابت", + "class": "ریسکی (اهرم) + خط پایهٔ قطعی", + "value": "ندارد", + "method": "بدون دادهٔ عددی امروز (از منبع یا ورودی شما)", + "resilience": null, + "survives": null, + "closing_count": 3 + }, + { + "id": "naked_put", + "name": "فروش اختیار فروش بدون پوشش (کارگاه بقا)", + "class": "ریسکی — برای آموزش ریاضیِ ورشکستگی", + "value": "ندارد", + "method": "بدون دادهٔ عددی امروز (از منبع یا ورودی شما)", + "resilience": null, + "survives": null, + "closing_count": 4 + }, + { + "id": "income_no_capital", + "name": "درآمد بدون سرمایه: فروش «تصمیم و شاهد»", + "class": "درآمدی (بدون بازار) — اهرم اصلی شما", + "value": "ندارد", + "method": "بدون دادهٔ عددی امروز (از منبع یا ورودی شما)", + "resilience": null, + "survives": null, + "closing_count": 2 + } + ], + "study_path": [ + "۱. اول مفهوم «خط پایه» را بفهم: نرخ مؤثر اوراق/صندوق درآمد ثابت. هر چیزی که از آن نگذرد، ارزش ریسک ندارد (سند: راهبرد اهرمی/درآمد ثابت، همین جزوه فصل ۶).", + "۲. بعد «قفل‌شده» را یاد بگیرید: مبنا و تبعی. این‌ها عددِ لحظهٔ ورود دارند، نه پیش‌بینی.", + "۳. بعد «پرمیوم» را: پوشش‌داده‌شده. این‌جا اولین بار احتمال (نوسان ضمنی) وارد می‌شود.", + "۴. بعد «چهارپایه» را: باکس و تساوی. این‌ها کارمزد و نقدشوندگی را به شما نشان می‌دهند.", + "۵. آخر «بقا»: کارگاه فروش پوت بدون پوشش + ریاضیِ ورشکستگی (فایل bankroll). اگر این را یاد بگیرید، بقیه امن است." + ], + "honesty": "درصدها سه نوع‌اند و برچسب دارند: «قطعی» (قفل‌شده در لحظهٔ ورود)، «مدل‌محور» (با نوسان ضمنیِ خودِ بازار و فرض بلک-شولز)، و «نقل‌شده» (از منبع با نام). هیچ‌کدام وعدهٔ سود نیست.", + "md_text": "# جزوهٔ راهبردهای موفق — با درصد، قاعدهٔ بستن و حسابرسی — نسخهٔ 0.1.0\n\n> درصدها سه نوع‌اند و برچسب دارند: «قطعی» (قفل‌شده در لحظهٔ ورود)، «مدل‌محور» (با نوسان ضمنیِ خودِ بازار و فرض بلک-شولز)، و «نقل‌شده» (از منبع با نام). هیچ‌کدام وعدهٔ سود نیست.\n\n## ۰. راهنمای خواندن این جزوه\n\n- ۱. اول مفهوم «خط پایه» را بفهم: نرخ مؤثر اوراق/صندوق درآمد ثابت. هر چیزی که از آن نگذرد، ارزش ریسک ندارد (سند: راهبرد اهرمی/درآمد ثابت، همین جزوه فصل ۶).\n- ۲. بعد «قفل‌شده» را یاد بگیرید: مبنا و تبعی. این‌ها عددِ لحظهٔ ورود دارند، نه پیش‌بینی.\n- ۳. بعد «پرمیوم» را: پوشش‌داده‌شده. این‌جا اولین بار احتمال (نوسان ضمنی) وارد می‌شود.\n- ۴. بعد «چهارپایه» را: باکس و تساوی. این‌ها کارمزد و نقدشوندگی را به شما نشان می‌دهند.\n- ۵. آخر «بقا»: کارگاه فروش پوت بدون پوشش + ریاضیِ ورشکستگی (فایل bankroll). اگر این را یاد بگیرید، بقیه امن است.\n\n## ۱. جدول یک‌نگاهی\n\n| راهبرد | دسته | عدد امروز | روش عدد | تاب‌آوری زیر شوک | حد بستن |\n| --- | --- | --- | --- | --- | --- |\n| مبنا / کری نقدی-آتی | قطعی (در لحظهٔ ورود قفل می‌شود) | 68.482 ٪ سالانه | قطعی/مدل‌محور (موتور ایستگاه + محاسبهٔ دستی دوم) | 100٪ | 3 حد |\n| پوشش‌داده‌شده (فروش اختیار خرید روی سهم) | مدل‌محور + درآمد پرمیوم | 56.558 ٪ سالانه (فقط پرمیوم) · احتمال ماندن زیر اعمال 61.92٪ | قطعی + مدل بلک-شولز (نوسان ضمنی از قیمت بازار) | 100٪ | 3 حد |\n| اوراق تبعی (اختیار فروش تضمینی) | قطعی (تعهد ناشر/بازارساز) | 42.361 ٪ سالانه (کمینهٔ تضمینی) | قطعی/مدل‌محور (موتور ایستگاه + محاسبهٔ دستی دوم) | 80٪ | 3 حد |\n| باکس اسپرد (چهار پایه، بدون ریسک جهت) | قطعی (پرداخت ثابت در سررسید) | 67.868 ٪ سالانه | قطعی/مدل‌محور (موتور ایستگاه + محاسبهٔ دستی دوم) | 100٪ | 3 حد |\n| تبدیل تساوی پوت-کال | قطعی (در لحظهٔ اجرا)، ولی کم‌بسامد | نه | قطعی/مدل‌محور (موتور ایستگاه + محاسبهٔ دستی دوم) | 0٪ | 4 حد |\n| صندوق اهرمی و نرخ مبنای درآمد ثابت | ریسکی (اهرم) + خط پایهٔ قطعی | ندارد | بدون دادهٔ عددی امروز (از منبع یا ورودی شما) | سنجیده نشد | 3 حد |\n| فروش اختیار فروش بدون پوشش (کارگاه بقا) | ریسکی — برای آموزش ریاضیِ ورشکستگی | ندارد | بدون دادهٔ عددی امروز (از منبع یا ورودی شما) | سنجیده نشد | 4 حد |\n| درآمد بدون سرمایه: فروش «تصمیم و شاهد» | درآمدی (بدون بازار) — اهرم اصلی شما | ندارد | بدون دادهٔ عددی امروز (از منبع یا ورودی شما) | سنجیده نشد | 2 حد |\n\n## 2. مبنا / کری نقدی-آتی (Cash-and-carry basis)\n\n**دسته:** قطعی (در لحظهٔ ورود قفل می‌شود)\n\n### اصل کار\nیک دارایی (یا صندوق) را نقد می‌خری و همان لحظه معادلش را در بازار آتی می‌فروشید. تفاوت قیمت آتی و نقدی، تا سررسید مال توست؛ چون دو طرف را همین حالا بسته‌ای، عدد در لحظهٔ ورود قفل است (به آن «بازده قفل‌شده» می‌گویند).\n\n### چه وقت استفاده می‌شود\nوقتی قیمت آتی از نقدی به‌قدری بالاتر است که بعد از کارمزد دو طرف، از نرخ سد (بازده بی‌ریسک) بگذرد. این تفاوت معمولاً وقتی باز می‌شود که تقاضای آتی بالا رفته یا نقدشوندگی نقدی کم شده باشد.\n\n### چه چیزی لازم دارد\nدسترسی به بازار آتی، وجه تضمین فروشندهٔ آتی، و نقدشوندگی هر دو سر.\n\n### قاعدهٔ بستن موقعیت\n\n- برداشت سود: با رسیدن به ۵۰٪ بازده انتظاری، هر دو پا را هم‌زمان ببندید.\n- توقف ضرر: اگر قیمت پایه ۶٪ خلاف شما رفت (فاصله تا اخطاریهٔ مارجین‌کال)، ببندید؛ یا وجه تضمین اضافه کن، ولی آن‌وقت بازده کل پایین می‌آید.\n- سررسید: اگر هیچ‌کدام نخورد، در سررسید ببندید (تسویهٔ نقدی/فیزیکی بر پایهٔ قیمت تسویهٔ روز آخر).\n- قاعدهٔ طلایی: دو پا را هم‌زمان ببندید، وگرنه از «معاملهٔ قفل‌شده» به «معاملهٔ جهت‌دار» تبدیل می‌شود.\n\n### ریسک‌ها\n\n- اخطاریهٔ مارجین‌کال در پاى آتی (تسویهٔ روزانه).\n- گپ نقدشوندگی در سررسید و اسپرد بزرگ.\n- تغییر ابلاغیه/وجه تضمین وسط راه.\n- قیمت تسویهٔ روز آخر (میانگین وزنی نیم‌ساعت پایانی) نه قیمتی که شما دیده‌ای.\n\n### حسابرسی عددهای امروز (با موتور ایستگاه)\n\n- عددهای ورودی: قیمت نقدی 20,000 · قیمت آتی 22,800 · روز تا سررسید 90\n- فرمول: سود هر واحد = 22,800×(۱−0.12٪) − 20,000×(۱+0.12٪) = 2,748.64، بعد بازده دوره ÷ قیمت تمام‌شده و توان ۳۶۵÷90\n- **پاسخ موتور:** 68.482 ٪ سالانه\n- محاسبهٔ دستی دوم: 68.482 — موافق ✅\n - بازده دوره = سود ÷ قیمت تمام‌شده = 13.727٪\n - بازده سالانه = (۱+بازده دوره)^(۳۶۵÷90) − ۱ = 68.482٪\n - نرخ سد امروز 35.0٪ و حاشیه 33.482 واحد درصد است\n- کارمزد لحاظ‌شده: 0.24٪ · نرخ سد: 35.0٪ · حاشیه: 33.482 واحد درصد\n- داوری: «می‌ماند» با حاشیهٔ 33.482 واحد درصد: تا وقتی نرخ سد زیر 68.482٪ بماند، این معامله ارزش بررسی دارد.\n- تحمل کارمزد: با کارمزد 12 برابر هم می‌ماند؛ کارمزد قاتل این راهبرد نیست.\n- فاصله تا اخطاریهٔ مارجین‌کال: 6.00٪ حرکت مخالف (پول در معرض خطر: 6,000,000 ریال بر پایهٔ 70.0٪ حد نگهداری)\n- احتمال مدل‌محور: این راهبرد جهت‌دار نیست؛ احتمال «سود/زیان» معنا ندارد. عددش قفل‌شده است و ریسک اصلی‌اش مارجین‌کال و نقدشوندگی است.\n\n### تاب‌آوری زیر شوک‌ها (100.0٪ شوک‌ها را رد کرد)\n\n| شوک | نتیجه | می‌ماند؟ |\n| --- | --- | --- |\n| لغزش اجرا ۰٫۵٪ | 61.786٪ | بله |\n| حرکت مخالف 1٪ قیمت پایه | 61.818٪ | بله |\n| کارمزد دو برابر | 66.850٪ | بله |\n| کارمزد سه برابر | 65.234٪ | بله |\n| نرخ سد 45٪ | 68.482٪ | بله |\n\n### منابع\n\n- قواعد وجه تضمین و تسویهٔ روزانهٔ بورس کالا (حداقل ۷۰٪ وجه تضمین اولیه، اخطاریهٔ مارجین‌کال) — جمع‌بندی‌شده در `05-data-routes-fa.md` و محدودیت‌های معاملاتی ایران.\n\n## 3. پوشش‌داده‌شده (فروش اختیار خرید روی سهم) (Covered call)\n\n**دسته:** مدل‌محور + درآمد پرمیوم\n\n### اصل کار\nسهم را دارید و روی همان سهم اختیار خرید می‌فروشید. پرمیوم را همین حالا می‌گیرید؛ در عوض سقف سود شما را روی قیمت اعمال قفل می‌کنید. اگر سهم زیر اعمال بماند، پرمیوم خالص سود توست.\n\n### چه وقت استفاده می‌شود\nبازاری که فکر می‌کنید تا سررسید صعود تند ندارد، ولی نوسان (و بنابراین پرمیوم) گران است. بازده پرمیوم سالانه‌شده باید از نرخ سد بگذرد.\n\n### چه چیزی لازم دارد\nسهم + دسترسی به بازار اختیار + کارمزد پایین (این راهبرد به کارمزد حساس است).\n\n### قاعدهٔ بستن موقعیت\n\n- برداشت سود: ۵۰٪ بازده انتظاری، یا وقتی پرمیوم باقی‌مانده به کمتر از ۲۰٪ پرمیوم اولیه رسید (خرید بازخرید اختیار).\n- توقف ضرر: روی خودِ سهم، همان حد ضرر سهم؛ پرمیوم فقط کمی آن را نرم می‌کند (پرمیوم ۴۰۰ روی سهم ۷٬۰۰۰ فقط ۵٫۷٪ حاشیه است).\n- سررسید: اگر اعمال شد، سهم در قیمت اعمال تحویل می‌رود؛ اگر نشد، اختیار بی‌ارزش تمام می‌شود و سهم می‌ماند.\n- قاعدهٔ بستن: پیش از سررسید و اگر سهم به اعمال نزدیک شد، یا بپذیر تحویل، یا اختیار را بازخرید کن — تصمیم را به روز آخر نگذار.\n\n### ریسک‌ها\n\n- سقف سود (صعود تند، شما را از سود باز می‌دارد).\n- ریسک نزولی سهم تقریباً کامل می‌ماند.\n- کارمزد سهم + کارمزد اختیار + مالیات فروش سهم از پرمیوم کم می‌شود.\n\n### حسابرسی عددهای امروز (با موتور ایستگاه)\n\n- عددهای ورودی: قیمت سهم 7,000 · قیمت اعمال کال 7,600 · پرمیوم کال 400 · روز تا سررسید 45\n- فرمول: پرمیوم خالص = 400×(۱−0.103٪) = 399.588 ÷ قیمت تمام‌شدهٔ سهم 7,032.48\n- **پاسخ موتور:** 56.558 ٪ سالانه (فقط پرمیوم)\n- محاسبهٔ دستی دوم: 56.558 — موافق ✅\n - درآمد پرمیوم دوره = 5.682٪\n - بازده سالانهٔ پرمیوم = (۱+درآمد دوره)^(۳۶۵÷45) − ۱ = 56.558٪\n - سقف رشد سهم با این پوشش = 8.57٪ (بخش بازار-ریسک، جدا از پرمیوم)\n- کارمزد لحاظ‌شده: 1.531٪ · نرخ سد: 35.0٪ · حاشیه: 21.558 واحد درصد\n- داوری: «می‌ماند» با حاشیهٔ 21.558 واحد درصد: تا وقتی نرخ سد زیر 56.558٪ بماند، این معامله ارزش بررسی دارد.\n- تحمل کارمزد: با کارمزد 12 برابر هم می‌ماند؛ کارمزد قاتل این راهبرد نیست.\n- فاصله تا اخطاریهٔ مارجین‌کال: 6.00٪ حرکت مخالف (پول در معرض خطر: 2,100 ریال بر پایهٔ 70.0٪ حد نگهداری)\n- احتمال مدل‌محور: با نوسان ضمنی 52.86٪، احتمال مدل‌محور اینکه سهم زیر اعمال بماند (پرمیوم کامل مال شما) ≈61.9٪ و احتمال اعمال‌شدن ≈38.1٪ است. این عدد «احتمال ریاضی تحت فرض بلک-شولز» است، نه پیش‌بینی بازار.\n\n### تاب‌آوری زیر شوک‌ها (100.0٪ شوک‌ها را رد کرد)\n\n| شوک | نتیجه | می‌ماند؟ |\n| --- | --- | --- |\n| لغزش اجرا ۰٫۵٪ | 55.880٪ | بله |\n| حرکت مخالف 1٪ قیمت پایه | 55.884٪ | بله |\n| کارمزد دو برابر | 56.175٪ | بله |\n| کارمزد سه برابر | 55.796٪ | بله |\n| نرخ سد 45٪ | 56.558٪ | بله |\n\n### منابع\n\n- کارمزد فروش سهم ۰٫۹۶۴٪ و خرید ۰٫۴۶۴٪ (کارگزاری‌ها/خانِ سرمایه)، کارمزد اختیار ≈۰٫۱۰۳٪ هر طرف و اعمال ۰٫۰۵٪ (بازار مشتقه).\n\n## 4. اوراق تبعی (اختیار فروش تضمینی) (Guaranteed put-back (tabei))\n\n**دسته:** قطعی (تعهد ناشر/بازارساز)\n\n### اصل کار\nسهم را می‌خری و رویش «تبعی» (اختیار فروش با تعهد بازخرید) می‌خری. از این لحظه، کمترین بازدهی‌ات تا سررسید قفل است: حتی اگر سهم بریزد، تبعی به قیمت اعمال خریداری می‌شود. رشد بالاتر از اعمال هم مال توست.\n\n### چه وقت استفاده می‌شود\nوقتی کمینهٔ بازده تبعی از نرخ سد بگذرد؛ برای پرتفوی کم‌ریسک و نگه‌دارید تا سررسید عالی است. قدرت اهرمی هم دارد (هموطن ≈۱٫۳ برابر، همیار ≈۱٫۲ برابر).\n\n### چه چیزی لازم دارد\nدسترسی به نمادهای تبعی + نقدشوندگی همان نماد تبعی (این نقطهٔ ضعف اصلی است).\n\n### قاعدهٔ بستن موقعیت\n\n- برداشت سود: اگر سهم از قیمت اعمال بالا رفت، سهم را در بازار بفروشید و تبعی را رها کن (کمترین بازده دیگر لازم نیست).\n- توقف ضرر: ذاتاً لازم نیست — تعهد بازخرید در اعمال، سقف ضرر است؛ ولی اگر ناشر به تعهدش عمل نکند یا نماد بسته شود، این توقف می‌شکند.\n- سررسید: در پنجرهٔ اعمال، سهم را به قیمت اعمال به تبعی بفروشید (یا بسته به نوع تبعی، تسویهٔ تفاوت).\n- قاعدهٔ بستن: شمارهٔ پنجرهٔ اعمال را از قبل در تقویم بگذارید؛ دیرکرد در اعمال = از دست دادن تضمین.\n\n### ریسک‌ها\n\n- ریسک تعهد (ناشر/بازارساز) و ریسک عملیاتی پنجرهٔ اعمال.\n- نقدشوندگی: اگر تبعی نقدشونده نباشد، بازده روی کاغذ می‌ماند.\n- کارمزد دو سر و مالیات فروش سهم از کمینهٔ بازده کم می‌شود.\n\n### حسابرسی عددهای امروز (با موتور ایستگاه)\n\n- عددهای ورودی: قیمت سهم 9,800 · قیمت پوت 40 · قیمت اعمال تضمینی 14,210 · روز تا سررسید 365\n- فرمول: هزینهٔ خرید = 9,800×(۱+0.464٪) + پوت 40 = 9,885.47 · دریافتی تضمینی = 14,210×(۱−0.964٪) = 14,073.02\n- **پاسخ موتور:** 42.361 ٪ سالانه (کمینهٔ تضمینی)\n- محاسبهٔ دستی دوم: 42.361 — موافق ✅\n - بازده دوره = (دریافتی تضمینی − هزینهٔ خرید) ÷ هزینهٔ خرید = 42.361٪\n - بازده سالانه = (۱+بازده دوره)^(۳۶۵÷365) − ۱ = 42.361٪\n- کارمزد لحاظ‌شده: 1.428٪ · نرخ سد: 35.0٪ · حاشیه: 7.361 واحد درصد\n- داوری: «می‌ماند» با حاشیهٔ 7.361 واحد درصد: تا وقتی نرخ سد زیر 42.361٪ بماند، این معامله ارزش بررسی دارد.\n- تحمل کارمزد: اگر کارمزد کل از 4.67 برابر امروز بگذرد، این راهبرد از نرخ سد می‌افتد.\n- فاصله تا اخطاریهٔ مارجین‌کال: 6.00٪ حرکت مخالف (پول در معرض خطر: 2,952 ریال بر پایهٔ 70.0٪ حد نگهداری)\n\n### تاب‌آوری زیر شوک‌ها (80.0٪ شوک‌ها را رد کرد)\n\n| شوک | نتیجه | می‌ماند؟ |\n| --- | --- | --- |\n| لغزش اجرا ۰٫۵٪ | 41.652٪ | بله |\n| حرکت مخالف 1٪ قیمت پایه | 40.957٪ | بله |\n| کارمزد دو برابر | 40.329٪ | بله |\n| کارمزد سه برابر | 38.317٪ | بله |\n| نرخ سد 45٪ | 42.361٪ | نه |\n\n### منابع\n\n- ساختار تبعی و اهرم‌ها: گزارش‌های بازار سرمایه (سهم‌بورس/رصد)، اسناد اوراق تبعی ناشر.\n\n## 5. باکس اسپرد (چهار پایه، بدون ریسک جهت) (Box spread)\n\n**دسته:** قطعی (پرداخت ثابت در سررسید)\n\n### اصل کار\nچهار اختیار را طوری می‌چینی که پرداخت سررسید همیشه ثابت باشد (مثلاً ۳٬۰۰۰). آن‌وقت معامله به «خرید یک قرض قطعی با تخفیف» تبدیل می‌شود؛ ریسک جهت و نوسان صفر است.\n\n### چه وقت استفاده می‌شود\nوقتی «بدهی امروزِ» باکس از ارزش فعلی پرداخت قطعی‌اش کمتر باشد، یعنی بازار کوپن بالاتر از نرخ سد می‌دهد.\n\n### چه چیزی لازم دارد\nچهار پایهٔ نقدشونده با اسپرد کم — وگرنه سرسری می‌افتد.\n\n### قاعدهٔ بستن موقعیت\n\n- برداشت سود: نگه‌داشتن تا سررسید (پرداخت قطعی)؛ یا اگر بدهی بازار بزرگ‌تر شد، بستن زودهنگام با سود.\n- توقف ضرر: ذاتاً ندارد؛ اما اگر نقدشوندگی یکی از پایه‌ها خشک شود، خروج زودهنگام ممکن نمی‌شود.\n- سررسید: بستن در سررسید (تحویل/تسویهٔ هر چهار پایه).\n- قاعدهٔ بستن: هرچه بدهی خالص کوچک‌تر باشد، حساسیت به لغزش اجرا بیشتر است؛ باکسی که بدهی‌اش فقط ۲۸۰ روی سپردهٔ ۳۰۰ است، با ۰٫۵٪ لغزش اجرا می‌افتد.\n\n### ریسک‌ها\n\n- حساسیت شدید به لغزش اجرا و اسپرد (آزمون شوک: ۰٪ تاب‌آوری زیر لغزش ۰٫۵٪).\n- کارمزد چهار طرف.\n- نبود امکان فروش استقراضی برای سمت معکوس.\n\n### حسابرسی عددهای امروز (با موتور ایستگاه)\n\n- عددهای ورودی: کال اعمال پایین 300 · پوت اعمال پایین 430 · کال اعمال بالا 175 · پوت اعمال بالا 585 · اعمال پایین 1,200 · اعمال بالا 1,500 · روز تا سررسید 45\n- فرمول: بدهی امروز = 280 · دریافتی قطعی در سررسید = 300 · کارمزد چهار طرف = 1.535\n- **پاسخ موتور:** 67.868 ٪ سالانه\n- محاسبهٔ دستی دوم: 67.868 — موافق ✅\n - سود خالص = دریافتی − بدهی − کارمزد = 18.47\n - بازده سالانه = (۱+سود÷بدهی)^(۳۶۵÷45) − ۱ = 67.868٪\n- کارمزد لحاظ‌شده: 0.412٪ · نرخ سد: 35.0٪ · حاشیه: 32.868 واحد درصد\n- داوری: «می‌ماند» با حاشیهٔ 32.868 واحد درصد: تا وقتی نرخ سد زیر 67.868٪ بماند، این معامله ارزش بررسی دارد.\n- تحمل کارمزد: اگر کارمزد کل از 6.15 برابر امروز بگذرد، این راهبرد از نرخ سد می‌افتد.\n- فاصله تا اخطاریهٔ مارجین‌کال: 6.00٪ حرکت مخالف (پول در معرض خطر: 75,000 ریال بر پایهٔ 70.0٪ حد نگهداری)\n\n### تاب‌آوری زیر شوک‌ها (100.0٪ شوک‌ها را رد کرد)\n\n| شوک | نتیجه | می‌ماند؟ |\n| --- | --- | --- |\n| لغزش اجرا ۰٫۵٪ | 35.659٪ | بله |\n| حرکت مخالف 1٪ قیمت پایه | 67.868٪ | بله |\n| کارمزد دو برابر | 60.994٪ | بله |\n| کارمزد سه برابر | 54.367٪ | بله |\n| نرخ سد 45٪ | 67.868٪ | بله |\n\n### منابع\n\n- ساختار باکس/تساوی: تئوری آربیتراژ آپشن (پاریتی)، ابزارهای مقایسهٔ آپشن بورس کالا.\n\n## 6. تبدیل تساوی پوت-کال (Put-call parity conversion)\n\n**دسته:** قطعی (در لحظهٔ اجرا)، ولی کم‌بسامد\n\n### اصل کار\nقانون تساوی می‌گوید: کال − پوت باید برابر باشد با سهم − ارزش فعلی اعمال. اگر شکاف از کارمزد سه پایه بزرگ‌تر شد، با خرید سهم + پوت و فروش کال، بازار را در یک قفس قفل می‌کنید.\n\n### چه وقت استفاده می‌شود\nشکاف‌های بزرگ (وقتی یکی از پایه‌ها نقدشوندگی‌اش را از دست داده). در شرایط عادی، کارمزد سه پایه شکاف را می‌خورد و جواب «نه» است.\n\n### چه چیزی لازم دارد\nسه پایهٔ هم‌سررسید با اعمال یکسان + امکان فروش اختیار (وجه تضمین).\n\n### قاعدهٔ بستن موقعیت\n\n- باد ventilation صریح: اگر شکاف بسته شد، سود را بردارید و ببندید.\n- توقف ضرر: انحراف بیش از حد انتظار = نشانهٔ دادهٔ اشتباه یا اعمال متفاوت سررسید؛ جای صبر نیست، بستن.\n- سررسید: نگه‌داشتن تا سررسید، اعمال خودکار تعهدها.\n- قاعدهٔ بستن: سمت معکوس (reverse conversion) در ایران ممکن نیست؛ چون فروش استقراضی سهم وجود ندارد. پس فقط یک جهت.\n\n### ریسک‌ها\n\n- کارمزد سه پایه؛ شکاف کاذب از دادهٔ بی‌کیفیت.\n- عدم امکان اجرای سمت معکوس (محدودیت بازار ایران).\n- پورتال‌های داده اشتباه زیاد دارند؛ اول با داوری سیگنال، اعتبار داده را بسنجید.\n\n### حسابرسی عددهای امروز (با موتور ایستگاه)\n\n- عددهای ورودی: قیمت کال 420 · قیمت پوت 380 · قیمت سهم 9,000 · قیمت اعمال 9,000 · روز تا سررسید 30 · نرخ بدون ریسک 39.0٪\n- فرمول: سمت چپ کال−پوت = 40 · سمت راست سهم−ارزش فعلی اعمال = 283.92 · شکاف = -243.92 · کارمزد سه پایه = 10.09\n- **پاسخ موتور:** نه بله/نه\n- محاسبهٔ دستی دوم: -254.01 — موافق ✅\n - اختلاف قابل برداشت = شکاف − کارمزد = -254.01\n - داوری: صرفه ندارد — سمت معکوس در ایران ممکن نیست (فروش استقراضی نداریم)\n- کارمزد لحاظ‌شده: 0.309٪ · نرخ سد: 35.0٪ · حاشیه: None واحد درصد\n- داوری: امروز «نه»: انحراف تساوی از کارمزد سه پایه کمتر است، پس چیزی برای برداشتن نیست. هر وقت شکاف بزرگ‌تر شد، همین خط دوباره چک می‌شود.\n- تحمل کارمزد: تساوی به کارمزد به‌شدت حساس است؛ کارمزد سه پایه همیشه اول کسر می‌شود و «نه» فعلی هم از همین است.\n- فاصله تا اخطاریهٔ مارجین‌کال: 6.00٪ حرکت مخالف (پول در معرض خطر: 2,700 ریال بر پایهٔ 70.0٪ حد نگهداری)\n\n### تاب‌آوری زیر شوک‌ها (0.0٪ شوک‌ها را رد کرد)\n\n| شوک | نتیجه | می‌ماند؟ |\n| --- | --- | --- |\n| لغزش اجرا ۰٫۵٪ | صرفه ندارد | نه |\n| حرکت مخالف 1٪ قیمت پایه | صرفه ندارد | نه |\n| کارمزد دو برابر | صرفه ندارد | نه |\n| کارمزد سه برابر | صرفه ندارد | نه |\n| نرخ سد 45٪ | صرفه ندارد | نه |\n\n### منابع\n\n- تساوی پوت-کال و کژشکاف‌ها: مبانی مالی مشتقه؛ فیلترهای مقایسه‌ای ابزارهای آپشن.\n\n## 7. صندوق اهرمی و نرخ مبنای درآمد ثابت (Leveraged fund / fixed-income baseline)\n\n**دسته:** ریسکی (اهرم) + خط پایهٔ قطعی\n\n### اصل کار\nدو کار متفاوت: (الف) نرخ مؤثر اوراق/صندوق درآمد ثابت را «خط پایهٔ» خودتان بگذارید؛ هر راهبردی که از آن نمی‌گذرد، ارزش ریسک ندارد. (ب) صندوق اهرمی بازده بازار را چند برابر می‌کند، هم بالا و هم پایین.\n\n### چه وقت استفاده می‌شود\nخط پایه همیشه؛ صندوق اهرمی فقط وقتی بازوی تحمل ریزش دارید (اهرم روزانه تسویه می‌شود).\n\n### چه چیزی لازم دارد\nدسترسی به صندوق‌ها/اوراق؛ برای اهرمی، تحمل نوسان.\n\n### قاعدهٔ بستن موقعیت\n\n- خط پایه: نگه‌داشتن تا سررسید یا فروش در صندوق (نقدشوندگی روزانه).\n- اهرمی: حد ضرر سخت (مثلاً ۱۰٪) بگذارید و از تسویهٔ روزانه غافل نشو.\n- قاعدهٔ بستن: اهرم را فقط با پولی ببر که ریزش ۳۰٪ برایت فاجعه نیست.\n\n### ریسک‌ها\n\n- اهرم، زیان را همان‌قدر بزرگ می‌کند که سود را.\n- کارمزد مدیریت صندوق از بازده کم می‌کند.\n- تسویهٔ روزانه در ابزارهای اهرمی/آتی می‌تواند پیش از برگشت بازار، شما را بیرون بیندازد.\n\n### منابع\n\n- بازده مؤثر صندوق درآمد ثابت شهریور ۱۴۰۵: ۳۹ تا ۴۰٪؛ سپردهٔ بانکی ۲۰٫۵ تا ۲۲٫۵٪ (گزارش‌های بازار، ناب‌ز قیمت/بورس‌نیوز).\n\n## 8. فروش اختیار فروش بدون پوشش (کارگاه بقا) (Naked short put)\n\n**دسته:** ریسکی — برای آموزش ریاضیِ ورشکستگی\n\n### اصل کار\nپرمیوم می‌گیرید و تعهد می‌دهی که در قیمت اعمال بخرید. اگر بازار بالای اعمال بماند، پرمیوم مال توست؛ اگر بریزد، زیان تقریباً بی‌سقف است. وجه تضمین اولیه ≈۲۰٪ ارزش قرارداد، حد نگهداری ۷۰٪ آن، تسویهٔ روزانه.\n\n### چه وقت استفاده می‌شود\nفقط برای کسی که بقا را می‌فهمد (اندازهٔ کوچک و نقد آماده).\n\n### چه چیزی لازم دارد\nوجه تضمین + تحمل مارجین‌کال.\n\n### قاعدهٔ بستن موقعیت\n\n- برداشت سود: ۵۰٪ پرمیوم (خرید بازخرید).\n- توقف ضرر: قبل از رسیدن به فاصلهٔ اخطاریهٔ مارجین‌کال ببندید (عدد فاصله در حسابرسی همین جزوه آمده).\n- سررسید: اگر زیر اعمال بماند، تسویه/خرید سهم.\n- قاعدهٔ بستن: هرگز با تمام وجه تضمین یک موقعیت نگیر؛ تسویهٔ روزانه، حساب را وسط راه می‌بندد.\n\n### ریسک‌ها\n\n- زیان دنباله (tail risk) و اخطاریهٔ مارجین‌کال.\n- ریسک ابلاغی/قانونی بازار مشتقه.\n- خودفریبی «پرمیوم همیشه مال من است».\n\n### منابع\n\n- حداقل وجه تضمین ۷۰٪ و اخطاریهٔ مارجین‌کال (بورس کالا)، وجه تضمین فروشندهٔ اختیار ≈۲۰٪ ارزش قرارداد.\n\n## 9. درآمد بدون سرمایه: فروش «تصمیم و شاهد» (Selling verified decisions (service))\n\n**دسته:** درآمدی (بدون بازار) — اهرم اصلی شما\n\n### اصل کار\nاگر ریاضیِ بالا را دارید، می‌توانی بدون سرمایه از آن درآمد بسازی: برای کارگزاری، شرکت یا معامله‌گر، سیگنال‌های ابزارهای دیگر را «داوری» کنید و شاهد بدهی: این سیگنال با کارمزد واقعی، وجه تضمین و نقدشوندگی واقعی می‌ماند یا می‌افتد.\n\n### چه وقت استفاده می‌شود\nهمین حالا. هیچ بازار، هیچ سرمایه و هیچ مجوزی لازم نیست؛ فقط همین ایستگاه و توانایی توضیح دادن.\n\n### چه چیزی لازم دارد\nارائهٔ شاهد قابل راستی‌آزمایی (زنجیرهٔ هش، آزمون دو-روشی، تضمین ساختاری) و صداقت در گفتن «نمی‌دانم».\n\n### قاعدهٔ بستن موقعیت\n\n- این «موقعیت» موقعیت بازار نیست؛ موقعیت شغلی است.\n- قاعدهٔ بستن: اگر شاهد از کار افتاد یا مشتری عدد کارگزاری متفاوتی گرفت، فوراً اعلام کن و اصلاح کن — اعتماد، تنها دارایی این کار است.\n\n### ریسک‌ها\n\n- هیچ سود تضمینی‌ای در بازار نیست؛ درآمد شما از «شاهد» می‌آید، نه از وعدهٔ سود.\n- بدون تضمین ساختاری، این کار به «سیگنال‌فروشی» تبدیل می‌شود — و اعتبار می‌سوزد.\n\n### منابع\n\n- سند تفاوت‌بگذارید و اعتماد: `08-differentiation-and-trust-fa.md` (سنجش ابزارهای موجود ایران: دیده‌بان آپشن، بامبو، آپشن‌اسکول).\n\n## پیوست: منابع، اعتبار و محدودیت‌ها\n\nفهرست کامل منابع و محدودیت‌های این جزوه در پروندهٔ `references-fa.md` در همین پوشه آمده است؛ هر عددی که برچسب روش ندارد، قابل استناد نیست.\n\n✍️ تهیه‌کنندهٔ جزوات: **Masoud Mojarabian** · 📱 +989126630554 · ✈️ Telegram: [Mojarabian](https://t.me/Mojarabian) · 📸 Instagram: [Mojarabian.Art](https://instagram.com/Mojarabian.Art)\n", + "ref_md": "# منابع و اعتبارسنجی عددها\n\nسه دسته منبع داریم و برچسب هر عدد می‌گوید از کدام دسته آمده. منابع تبلیغاتی (که درصد موفقیت وعده می‌دهند) عمداً حذف شده‌اند؛ چیزی که قابل راستی‌آزمایی نباشد، در این جزوه عدد نیست.\n\n## ۱. منبع خودِ برنامه (بازتولیدپذیر)\n\n- موتور ایستگاه (`tools/derivatives_scout.py`) + آزمون دو-روشی: هر عدد با یک محاسبهٔ دستی دوم (کسری دقیق) مقایسه می‌شود و در جدول «موافق/مخالف» علامت می‌خورد.\n- آزمون تاب‌آوری (`edge_stress.py`): هر راهبرد زیر ۵ شوک واقعی سنجیده می‌شود.\n- فایل‌های شاهد: `data/edge-stress.html`، `data/witness-live.html`، `data/investor-ladder.md`.\n\n## ۲. منابع بیرونی استفاده‌شده (با نام، برای قواعد بازار)\n\n1. بازده مؤثر صندوق درآمد ثابت شهریور ۱۴۰۵: ۳۹ تا ۴۰٪؛ سپردهٔ بانکی ۲۰٫۵ تا ۲۲٫۵٪ (گزارش‌های بازار، ناب‌ز قیمت/بورس‌نیوز).\n2. تساوی پوت-کال و کژشکاف‌ها: مبانی مالی مشتقه؛ فیلترهای مقایسه‌ای ابزارهای آپشن.\n3. حداقل وجه تضمین ۷۰٪ و اخطاریهٔ مارجین‌کال (بورس کالا)، وجه تضمین فروشندهٔ اختیار ≈۲۰٪ ارزش قرارداد.\n4. ساختار باکس/تساوی: تئوری آربیتراژ آپشن (پاریتی)، ابزارهای مقایسهٔ آپشن بورس کالا.\n5. ساختار تبعی و اهرم‌ها: گزارش‌های بازار سرمایه (سهم‌بورس/رصد)، اسناد اوراق تبعی ناشر.\n6. سند تفاوت‌بگذارید و اعتماد: `08-differentiation-and-trust-fa.md` (سنجش ابزارهای موجود ایران: دیده‌بان آپشن، بامبو، آپشن‌اسکول).\n7. قواعد وجه تضمین و تسویهٔ روزانهٔ بورس کالا (حداقل ۷۰٪ وجه تضمین اولیه، اخطاریهٔ مارجین‌کال) — جمع‌بندی‌شده در `05-data-routes-fa.md` و محدودیت‌های معاملاتی ایران.\n8. کارمزد فروش سهم ۰٫۹۶۴٪ و خرید ۰٫۴۶۴٪ (کارگزاری‌ها/خانِ سرمایه)، کارمزد اختیار ≈۰٫۱۰۳٪ هر طرف و اعمال ۰٫۰۵٪ (بازار مشتقه).\n\n## ۳. قواعد بازار که عددها روی آن‌ها بسته شده\n\n- کارمزد سهم: خرید ۰٫۴۶۴٪ و فروش ۰٫۹۶۴٪ (گزارش کارگزاری‌ها و خانِ سرمایه).\n- کارمزد اختیار: ≈۰٫۱۰۳٪ هر طرف · اعمال ۰٫۰۵٪ × قیمت اعمال (دو طرف).\n- وجه تضمین: فروشندهٔ اختیار ≈۲۰٪ ارزش قرارداد؛ حداقل وجه تضمین ۷۰٪ وجه تضمین اولیه؛ اخطاریهٔ مارجین‌کال و مهلت ۲۴ ساعت؛ تسویهٔ روزانه بر پایهٔ قیمت تسویه.\n- تسویهٔ آتی بر پایهٔ میانگین وزنی نیم‌ساعت پایانی روز آخر است.\n- مالیات: معاملات مشتقه معاف؛ فروش فیزیکی کالا ۰٫۵٪.\n- ممنوعیت معاملات الگوریتمی برای مشتریان برخط (ابلاغیهٔ مهر ۱۳۹۹، «تا اطلاع ثانوی») — به همین دلیل این ایستگاه هیچ سفارشی نمی‌فرستد.\n\n## ۴. چطور عددهای این جزوه را خودتان بازتولید کنید (سه فرمان)\n\n۱. جزوه و شوک‌آزمون را بسازید: `python3 strategy_audit.py` و سپس `python3 edge_stress.py` (هر دو در پوشهٔ `gui`).\n۲. ریاضیِ بقا و مسیر رشد را ببینید: `python3 bankroll.py --capital 100000000 --target 400000000`.\n۳. آزمون‌ها را اجرا کنید: `python3 -m unittest discover -s tests -q`؛ اگر همه سبز شد، عددهای این جزوه روی همین ماشین بازتولید شدند.\n\n## ۵. واژه‌نامهٔ برچسب‌های روش\n\n- «قطعی» یعنی پرداخت یا تعهد در همان لحظهٔ وارد‌شدن مشخص است (تبعی، باکس، مبنا).\n- «مدل‌محور» یعنی با فرض حرکت لگنرمال و نوسانِ ضمنیِ استخراج‌شده از قیمت خودِ بازار حساب شده است؛ این فرض می‌تواند غلط باشد و عدد را باید «تخمین» خواند، نه واقعیت.\n- «نقل‌شده» یعنی از منبع بیرونی آمده و نام منبع کنارش نوشته شده است.\n\n## ۶. محدودیت‌های صادقانه این جزوه\n\n- دادهٔ تاریخی بلند و معتبر در این محیط در دسترس نبود؛ پس **هیچ درصد «برد تاریخی» ادعا نمی‌کنیم**. آنچه می‌دهیم: عددهای قفل‌شدهٔ لحظهٔ ورود، احتمال مدل‌محور با نوسان ضمنی خودِ بازار، و نرخ‌های نقل‌شده با نام منبع.\n- «نرخ تاب‌آوری» احتمال سود نیست؛ سهم شوک‌هایی است که راهبرد از آن‌ها سالم بیرون آمده.\n- عددهای امروز به اسنپ‌شات امروز شما بسته‌اند؛ فردا عوض می‌شوند. برای روز خودتان، همین اسکریپت را اجرا کنید.\n\n\n✍️ تهیه‌کنندهٔ جزوات: **Masoud Mojarabian** · 📱 +989126630554 · ✈️ Telegram: [Mojarabian](https://t.me/Mojarabian) · 📸 Instagram: [Mojarabian.Art](https://instagram.com/Mojarabian.Art)", + "index_md": "# پوشهٔ راهبردها — از کجا شروع کنم؟\n\n| پرونده | چیست |\n| --- | --- |\n| `strategy-library-fa.md` | جزوهٔ کامل: هر راهبرد، اصل، قاعدهٔ بستن، ریسک، حسابرسی عدد |\n| `strategy-library.html` | همان جزوه، چاپی و خوانا (برای پرینت گرفتن و مطالعه) |\n| `strategy-library.json` | دادهٔ ماشین‌خوان همین جزوه (برای برنامه‌نویسی) |\n| `references-fa.md` | منابع، قواعد بازار، و محدودیت‌های صادقانه |\n\n## سه برچسب عدد (اگر این را بفهمید، بقیه روشن می‌شود)\n\n- «قطعی»: عدد در لحظهٔ وارد‌شدن قفل می‌شود. مثل کمینهٔ بازده تبعی و پرداخت ثابت باکس.\n- «مدل‌محور»: عدد با فرض حرکت لگنرمال و نوسانِ ضمنیِ خودِ بازار حساب می‌شود. تخمین است، نه پیش‌بینی.\n- «نقل‌شده»: از منبع بیرونی با نام منبع. اگر برچسب نبود، عدد به کار نمی‌آید.\n\n## چطور خودم عددها را بسازم؟\n\n- در رابط مرورگری به گام ۱۱ بروید و «ساخت جزوه + شوک‌آزمون» را بزنید.\n- یا در خط فرمان: `python3 strategy_audit.py` و `python3 edge_stress.py` و `python3 bankroll.py`.\n- آزمون‌ها: `python3 -m unittest discover -s tests -q` — اگر سبز شد، عددها بازتولید شدند.\n\n## مسیر مطالعهٔ پیشنهادی\n\n- ۱. اول مفهوم «خط پایه» را بفهم: نرخ مؤثر اوراق/صندوق درآمد ثابت. هر چیزی که از آن نگذرد، ارزش ریسک ندارد (سند: راهبرد اهرمی/درآمد ثابت، همین جزوه فصل ۶).\n- ۲. بعد «قفل‌شده» را یاد بگیرید: مبنا و تبعی. این‌ها عددِ لحظهٔ ورود دارند، نه پیش‌بینی.\n- ۳. بعد «پرمیوم» را: پوشش‌داده‌شده. این‌جا اولین بار احتمال (نوسان ضمنی) وارد می‌شود.\n- ۴. بعد «چهارپایه» را: باکس و تساوی. این‌ها کارمزد و نقدشوندگی را به شما نشان می‌دهند.\n- ۵. آخر «بقا»: کارگاه فروش پوت بدون پوشش + ریاضیِ ورشکستگی (فایل bankroll). اگر این را یاد بگیرید، بقیه امن است.\n\n> هر عددی که می‌خوانی، برچسب روش دارد: «قطعی» / «مدل‌محور» / «نقل‌شده». اگر عددی برچسب نداشت، به آن استناد نکنید.\n\n\n✍️ تهیه‌کنندهٔ جزوات: **Masoud Mojarabian** · 📱 +989126630554 · ✈️ Telegram: [Mojarabian](https://t.me/Mojarabian) · 📸 Instagram: [Mojarabian.Art](https://instagram.com/Mojarabian.Art)\n" +} \ No newline at end of file diff --git a/tools/derivatives_scout.py b/tools/derivatives_scout.py new file mode 100644 index 0000000000000000000000000000000000000000..756b68fb0e6257faf6ecc5c21812e6b3a8bf90d4 --- /dev/null +++ b/tools/derivatives_scout.py @@ -0,0 +1,396 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""دیده‌بان ریاضی بازار مشتقه ایران — ابزار محاسبهٔ بازده بدون‌شانس. + +هیچ پیش‌بینی‌ای انجام نمی‌شود؛ فقط رابطه‌های ریاضی قیمت‌گذاری (ارزش منصفانه، +تساوی پوت‌کال، باکس اسپرد، مبنای آتی، بازده تضمینی اوراق تبعی) روی اعداد بازار +اجرا و با نرخ سد (benchmark) مقایسه می‌شود. خروجی: فهرست فرصت‌ها با بازده +سالانهٔ خالص و حاشیهٔ اطمینان. + +اجرا: + python3 derivatives_scout.py --demo + python3 derivatives_scout.py --input scenario.json + python3 derivatives_scout.py --self-test +""" +from __future__ import annotations + +import argparse +import json +import math +import sys +from dataclasses import dataclass, field +from typing import Iterable + +# ---------------------------------------------------------------- هزینه‌های بازار ایران +# کارمزد معاملهٔ اختیار معامله: ۰٫۱۰۳٪ ارزش معامله (هر طرف)؛ کارمزد اعمال ۰٫۰۵٪ ارزش قرارداد +# بر پایهٔ قیمت اعمال؛ مالیات واگذاری در تسویهٔ فیزیکی ۰٫۵٪. +FEE_OPTION_TRADE = 0.00103 +FEE_OPTION_EXERCISE = 0.0005 +TAX_PHYSICAL_SETTLE = 0.005 +# سهام: کارمزد خرید ۰٫۴۶۴٪ و کسورات فروش ۰٫۹۶۴٪ (شامل ۰٫۵٪ مالیات). +FEE_STOCK_BUY = 0.00464 +FEE_STOCK_SELL = 0.00964 +# صندوق کالایی/زعفران: ۰٫۱۲٪ هر طرف. +FEE_FUND_ETF = 0.0012 + +DAYS = 365.0 + + +# ---------------------------------------------------------------- ابزارهای پایه +def years(days: float) -> float: + if days <= 0: + raise ValueError("روز تا سررسید باید مثبت باشد") + return days / DAYS + + +def exp(x: float) -> float: + return math.exp(x) + + +def _npdf(x: float) -> float: + return math.exp(-0.5 * x * x) / math.sqrt(2 * math.pi) + + +def _ncdf(x: float) -> float: + return 0.5 * (1.0 + math.erf(x / math.sqrt(2.0))) + + +def black_scholes(spot: float, strike: float, days: float, rate: float, + vol: float, kind: str = "call") -> float: + """قیمت نظری اروپایی؛ rate و vol سالانه‌اند و اعشاری وارد می‌شوند.""" + if spot <= 0 or strike <= 0 or vol < 0: + raise ValueError("ورودی نامعتبر") + t = years(max(days, 1e-9)) + disc = exp(-rate * t) + if vol == 0: + intrinsic = max(spot - strike * disc, 0.0) if kind == "call" else max(strike * disc - spot, 0.0) + return intrinsic + d1 = (math.log(spot / strike) + (rate + 0.5 * vol * vol) * t) / (vol * math.sqrt(t)) + d2 = d1 - vol * math.sqrt(t) + if kind == "call": + return spot * _ncdf(d1) - strike * disc * _ncdf(d2) + return strike * disc * _ncdf(-d2) - spot * _ncdf(-d1) + + +def implied_vol(price: float, spot: float, strike: float, days: float, + rate: float, kind: str = "call", + lo: float = 1e-4, hi: float = 5.0, tol: float = 1e-6) -> float | None: + """نوسان ضمنی با روش نصف‌کردن بازه؛ اگر قیمت بیرون از بازهٔ معتبر باشد None.""" + t = years(max(days, 1e-9)) + intrinsic = max(spot - strike * exp(-rate * t), 0.0) if kind == "call" else \ + max(strike * exp(-rate * t) - spot, 0.0) + if price < intrinsic - 1e-9: + return None + if black_scholes(spot, strike, days, rate, hi, kind) < price: + return None + for _ in range(200): + mid = 0.5 * (lo + hi) + if black_scholes(spot, strike, days, rate, mid, kind) < price: + lo = mid + else: + hi = mid + if hi - lo < tol: + break + return 0.5 * (lo + hi) + + +# ---------------------------------------------------------------- رابطه‌های آربیتراژ +def futures_fair(spot: float, days: float, rate: float, + storage: float = 0.0, convenience: float = 0.0) -> float: + """F = S · e^((r + انبارداری − راحتی)·T)""" + t = years(days) + return spot * exp((rate + storage - convenience) * t) + + +def implied_rate(spot: float, future: float, days: float) -> float: + """نرخ تلویحی (سالانه) از مبنای آتی: ln(F/S)/T""" + t = years(days) + return math.log(future / spot) / t + + +def basis_opportunity(spot: float, future: float, days: float, + hurdle: float, fee_buy: float = FEE_FUND_ETF, + fee_sell: float = FEE_FUND_ETF, + storage_annual: float = 0.0) -> dict: + """خرید نقدی + فروش آتی: بازده سالانهٔ خالص در برابر نرخ سد.""" + t = years(days) + cost_buy = spot * (1 + fee_buy) + proceeds = future * (1 - fee_sell) + storage = spot * storage_annual * t + net_gain = proceeds - cost_buy - storage + ret_period = net_gain / cost_buy + annual = (1 + ret_period) ** (1 / t) - 1 + return { + "strategy": "basis_cash_and_carry", + "net_gain_per_unit": round(net_gain, 2), + "period_return_pct": round(ret_period * 100, 3), + "annualized_pct": round(annual * 100, 3), + "hurdle_pct": round(hurdle * 100, 3), + "edge_pp": round((annual - hurdle) * 100, 3), + "go": annual - hurdle >= 0.03, + } + + +def put_call_parity(call: float, put: float, spot: float, strike: float, + days: float, rate: float, + fee: float = FEE_OPTION_TRADE) -> dict: + """انحراف از تساوی C − P = S − K·e^(−rT).""" + t = years(days) + left = call - put + right = spot - strike * exp(-rate * t) + gap = left - right + costs = (call + put + spot) * fee + conversion_edge = gap - costs # خرید سهم + خرید پوت + فروش کال + basis = spot + put - call + annual = None + if basis > 0 and conversion_edge > 0: + annual = (1 + conversion_edge / basis) ** (1 / t) - 1 + return { + "strategy": "put_call_parity", + "lhs_call_minus_put": round(left, 2), + "rhs_spot_minus_pv_strike": round(right, 2), + "gap": round(gap, 2), + "costs_estimate": round(costs, 2), + "conversion_edge_per_unit": round(conversion_edge, 2), + "annualized_pct": round(annual * 100, 3) if annual is not None else None, + "direction": "conversion" if conversion_edge > 0 else "reverse (نیازمند فروش استقراضی: در ایران ممکن نیست)", + "go": conversion_edge > 0, + } + + +def box_spread(call_low: float, put_low: float, call_high: float, put_high: float, + strike_low: float, strike_high: float, days: float, + fee: float = FEE_OPTION_TRADE) -> dict: + """باکس اسپرد: بدهی اولیه در برابر دریافتی قطعی (K₂−K₁). + + خرید کال با اعمال پایین + فروش پوت با اعمال پایین + + فروش کال با اعمال بالا + خرید پوت با اعمال بالا. + """ + t = years(days) + if strike_high <= strike_low: + raise ValueError("قیمت اعمال بالا باید بزرگ‌تر باشد") + debit = (call_low + put_high) - (put_low + call_high) + payoff = strike_high - strike_low + fees = (call_low + put_low + call_high + put_high) * fee + payoff * FEE_OPTION_EXERCISE * 0 + net = payoff - debit - fees + if debit <= 0: + return {"strategy": "box_spread", "debit": round(debit, 2), "note": "بدهی غیرمثبت: داده را بررسی کنید", "go": False} + period = net / debit + annual = (1 + period) ** (1 / t) - 1 + return { + "strategy": "box_spread", + "debit": round(debit, 2), + "payoff": round(payoff, 2), + "fees_estimate": round(fees, 2), + "net_profit": round(net, 2), + "period_return_pct": round(period * 100, 3), + "annualized_pct": round(annual * 100, 3), + "go": annual > 0, + } + + +def tabei_min_yield(stock_price: float, put_price: float, strike: float, days: float, + fee_stock_buy: float = FEE_STOCK_BUY, + fee_stock_sell: float = FEE_STOCK_SELL) -> dict: + """اوراق اختیار فروش تبعی: کمینهٔ بازده در صورت نگه‌داشتن تا سررسید.""" + t = years(days) + buy_total = stock_price * (1 + fee_stock_buy) + put_price + sell_net = strike * (1 - fee_stock_sell) + period = (sell_net - buy_total) / buy_total + annual = (1 + period) ** (1 / t) - 1 + return { + "strategy": "tabei_put_min_yield", + "cost_basis": round(buy_total, 2), + "guaranteed_proceeds": round(sell_net, 2), + "period_return_pct": round(period * 100, 3), + "annualized_pct": round(annual * 100, 3), + "go": annual > 0, + } + + +def covered_call(spot: float, strike: float, premium: float, days: float, + fee_stock_buy: float = FEE_STOCK_BUY, + fee_stock_sell: float = FEE_STOCK_SELL, + fee_option: float = FEE_OPTION_TRADE) -> dict: + """فروش اختیار خرید پوشش‌داده‌شده روی سهم موجود.""" + t = years(days) + basis = spot * (1 + fee_stock_buy) + proceeds = strike * (1 - fee_stock_sell) + premium * (1 - fee_option) + period = (proceeds - basis) / basis + annual = (1 + period) ** (1 / t) - 1 + capped_upside = round((strike - spot) / spot * 100, 2) + prem_period = (premium * (1 - fee_option)) / basis + prem_annual = (1 + prem_period) ** (1 / t) - 1 + return { + "strategy": "covered_call", + "period_return_if_exercised_pct": round(period * 100, 3), + "annualized_if_exercised_pct": round(annual * 100, 3), + "premium_yield_pct": round(premium / spot * 100, 3), + "premium_annualized_pct": round(prem_annual * 100, 3), + # معیار تصمیم: فقط درآمد پرمیوم (بخش بازار-ریسک جدا شمرده می‌شود) + "annualized_pct": round(prem_annual * 100, 3), + "upside_capped_at_pct": capped_upside, + "go": prem_annual > 0.03, + } + + +def position_size(capital: float, margin_per_contract: float, + risk_pct: float = 0.20, concurrent: int = 1) -> dict: + """چند قرارداد می‌توان باز کرد تا وجه تضمین از سقف ریسک رد نشود.""" + budget = capital * risk_pct * concurrent + n = int(budget // margin_per_contract) if margin_per_contract > 0 else 0 + return { + "contracts": n, + "margin_locked": round(n * margin_per_contract, 2), + "free_cash": round(capital - n * margin_per_contract, 2), + "min_cash_ratio": 0.40, + } + + +def score(opportunity: dict, hurdle: float = 0.35) -> float: + """امتیازدهی: بازده سالانه منهای نرخ سد، با جریمهٔ نقدشوندگی و اهرم.""" + annual = opportunity.get("annualized_pct") + if annual is None: + return -999.0 + edge = annual / 100.0 - hurdle + penalty = 0.0 + if opportunity.get("liquidity_contracts_per_day", 99) < 20: + penalty += 0.05 + if opportunity.get("spread_pct", 0) > 0.03: + penalty += 0.05 + if opportunity.get("leverage_used", 0) > 2: + penalty += 0.03 + return round((edge - penalty) * 100, 3) + + +# ---------------------------------------------------------------- گزارش +@dataclass +class Scenario: + name: str + rows: list[dict] = field(default_factory=list) + hurdle: float = 0.35 + + +def run_scenario(sc: Scenario) -> list[dict]: + out: list[dict] = [] + for r in sc.rows: + kind = r.get("kind") + try: + if kind == "basis": + res = basis_opportunity(r["spot"], r["future"], r["days"], sc.hurdle, + r.get("fee_buy", FEE_FUND_ETF), + r.get("fee_sell", FEE_FUND_ETF), + r.get("storage_annual", 0.0)) + elif kind == "parity": + res = put_call_parity(r["call"], r["put"], r["spot"], r["strike"], + r["days"], r.get("rate", 0.35)) + elif kind == "box": + res = box_spread(r["call_low"], r["put_low"], r["call_high"], r["put_high"], + r["strike_low"], r["strike_high"], r["days"]) + elif kind == "tabei": + res = tabei_min_yield(r["stock_price"], r["put_price"], r["strike"], r["days"]) + elif kind == "covered_call": + res = covered_call(r["spot"], r["strike"], r["premium"], r["days"]) + else: + out.append({"name": r.get("name", "?"), "error": f"نوع ناشناخته: {kind}"}) + continue + except (KeyError, ValueError, ZeroDivisionError) as e: + out.append({"name": r.get("name", "?"), "error": str(e)}) + continue + res["name"] = r.get("name", kind) + res["liquidity_contracts_per_day"] = r.get("liquidity_contracts_per_day", 99) + res["spread_pct"] = r.get("spread_pct", 0.0) + res["leverage_used"] = r.get("leverage_used", 0) + res["score_pp"] = score(res, sc.hurdle) + out.append(res) + return sorted(out, key=lambda x: x.get("score_pp", -999), reverse=True) + + +def print_report(items: Iterable[dict], hurdle: float, caveat: bool = True) -> None: + print(f"نرخ سد (بازده بدون ریسک فرضی): {hurdle * 100:.1f}٪ سالانه") + if caveat: + print("یادآوری: خروجی فقط تفاوت ریاضی قیمت‌ها با نرخ سد است؛ ریسک اجرا، نقدشوندگی،") + print(" وجه تضمین و نکول ناشر در آن لحاظ نشده. اعداد نمونه، واقعی بازار نیستند.") + print("-" * 72) + for it in items: + if "error" in it: + print(f"× {it['name']}: {it['error']}") + continue + annual = it.get("annualized_pct") + tag = "✅" if it.get("go") else ("✖" if "go" in it else "◻") + annual_txt = f"{annual:.2f}٪" if isinstance(annual, (int, float)) else "—" + print(f"{tag} {it['name']:<28} بازده سالانهٔ خالص: {annual_txt:<10} امتیاز: {it['score_pp']}") + for k, v in it.items(): + if k in {"name", "strategy", "go", "score_pp", "annualized_pct"}: + continue + print(f" · {k}: {v}") + print() + + +DEMO = { + "hurdle": 0.35, + "rows": [ + {"name": "آتی صندوق طلا (۶۰ روز)", "kind": "basis", "spot": 20000, "future": 22800, + "days": 60, "storage_annual": 0.0, "liquidity_contracts_per_day": 900, "spread_pct": 0.005}, + {"name": "باکس اسپرد خساپا (۴۵ روز)", "kind": "box", "call_low": 300, "put_low": 420, + "call_high": 180, "put_high": 560, "strike_low": 1200, "strike_high": 1500, "days": 45}, + {"name": "تبعی نمونه (۹۰ روز، ۲۵٪ تضمین)", "kind": "tabei", "stock_price": 50000, + "put_price": 200, "strike": 62500, "days": 90}, + {"name": "پوشش‌داده‌شده فولاد (۳۰ روز)", "kind": "covered_call", "spot": 7000, + "strike": 7400, "premium": 220, "days": 30}, + {"name": "تساوی پوت‌کال شپنا (۳۰ روز)", "kind": "parity", "call": 420, "put": 380, + "spot": 9000, "strike": 9000, "days": 30, "rate": 0.35}, + ], +} + + +def self_test() -> int: + ok = 0 + # ارزش نظری بلک‌شولز با مقدار مرجع + c = black_scholes(100, 100, 365, 0.0, 0.20, "call") + assert abs(c - 7.9656) < 0.01, c + ok += 1 + # تقارن پوت‌کال در مدل + p = black_scholes(100, 100, 365, 0.0, 0.20, "put") + assert abs((c - p) - 0.0) < 1e-9, (c, p) # r=0 ⇒ C=P + ok += 1 + # نرخ تلویحی + assert abs(implied_rate(100, 110, 365) - math.log(1.1)) < 1e-9 + ok += 1 + # نوسان ضمنی رفت‌وبرگشت + iv = implied_vol(c, 100, 100, 365, 0.0, "call") + assert iv is not None and abs(iv - 0.20) < 1e-4, iv + ok += 1 + # باکس اسپرد: بازده قطعی مثبت و سالانه‌سازی درست + b = box_spread(300, 420, 180, 560, 1200, 1500, 45) + assert b["payoff"] == 300 + assert b["annualized_pct"] > 0 + ok += 1 + # تبعی: بازده تضمینی مثبت + t = tabei_min_yield(50000, 0, 62500, 90) + assert t["annualized_pct"] > 0.25 * 100 + ok += 1 + print(f"خودآزمون: {ok} بررسی موفق") + return 0 + + +def main(argv: list[str] | None = None) -> int: + ap = argparse.ArgumentParser(description="دیده‌بان ریاضی بازار مشتقه ایران") + ap.add_argument("--demo", action="store_true", help="اجرای سناریوی نمونه") + ap.add_argument("--input", help="پروندهٔ JSON سناریو") + ap.add_argument("--self-test", action="store_true") + args = ap.parse_args(argv) + + if args.self_test: + return self_test() + data = DEMO if args.demo else (json.load(open(args.input, encoding="utf-8")) if args.input else None) + if data is None: + ap.print_help() + return 0 + sc = Scenario(name=data.get("name", "سناریو"), rows=data["rows"], hurdle=data.get("hurdle", 0.35)) + print_report(run_scenario(sc), sc.hurdle, caveat=bool(args.demo)) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tools/test_derivatives_scout.py b/tools/test_derivatives_scout.py new file mode 100644 index 0000000000000000000000000000000000000000..8522c1110dacc5fd420abd31c70c8913f7ade790 --- /dev/null +++ b/tools/test_derivatives_scout.py @@ -0,0 +1,137 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +"""آزمون‌های واحد ابزار دیده‌بان مشتقه — فقط کتابخانهٔ استاندارد.""" +from __future__ import annotations + +import math +import unittest + +from derivatives_scout import ( + FEE_FUND_ETF, + Scenario, + basis_opportunity, + black_scholes, + box_spread, + covered_call, + futures_fair, + implied_rate, + implied_vol, + position_size, + put_call_parity, + run_scenario, + score, + tabei_min_yield, + years, +) + + +class TestPricing(unittest.TestCase): + def test_black_scholes_reference_value(self): + # S=K=100، T=1 سال، r=0، σ=0.2 ⇒ C ≈ 7.9656 + self.assertAlmostEqual(black_scholes(100, 100, 365, 0.0, 0.20, "call"), 7.9656, places=3) + + def test_model_parity(self): + c = black_scholes(100, 100, 365, 0.10, 0.25, "call") + p = black_scholes(100, 100, 365, 0.10, 0.25, "put") + self.assertAlmostEqual(c - p, 100 - 100 * math.exp(-0.10), places=8) + + def test_zero_vol_is_intrinsic(self): + # با نوسان صفر: C = S − K·e^(−rT) + expected = 110 - 100 * math.exp(-0.3 * 30 / 365) + self.assertAlmostEqual(black_scholes(110, 100, 30, 0.3, 0.0, "call"), expected, places=6) + + def test_implied_vol_round_trip(self): + price = black_scholes(100, 100, 365, 0.0, 0.20, "call") + iv = implied_vol(price, 100, 100, 365, 0.0, "call") + self.assertIsNotNone(iv) + self.assertAlmostEqual(iv, 0.20, places=4) + + def test_implied_vol_rejects_below_intrinsic(self): + self.assertIsNone(implied_vol(1.0, 100, 50, 30, 0.0, "call")) + + def test_days_must_be_positive(self): + with self.assertRaises(ValueError): + years(0) + + +class TestArbitrage(unittest.TestCase): + def test_implied_rate_identity(self): + self.assertAlmostEqual(implied_rate(100, 110, 365), math.log(1.1), places=10) + + def test_futures_fair_round_trip(self): + f = futures_fair(1000, 180, 0.35) + self.assertAlmostEqual(implied_rate(1000, f, 180), 0.35, places=10) + + def test_basis_go_when_above_hurdle(self): + # ۲۰٪ بازده دوره‌ای در ۶۰ روز ⇒ سالانه بسیار بالاتر از سد ۳۵٪ + r = basis_opportunity(1000, 1220, 60, 0.35) + self.assertTrue(r["go"]) + self.assertGreater(r["annualized_pct"], 35.0) + + def test_basis_no_go_when_below_hurdle(self): + r = basis_opportunity(1000, 1005, 365, 0.35) + self.assertFalse(r["go"]) + self.assertLess(r["annualized_pct"], 35.0) + + def test_box_payoff_is_strike_gap(self): + r = box_spread(300, 420, 180, 560, 1200, 1500, 45) + self.assertEqual(r["payoff"], 300) + self.assertGreater(r["annualized_pct"], 0) + + def test_box_rejects_inverted_strikes(self): + with self.assertRaises(ValueError): + box_spread(300, 420, 180, 560, 1500, 1200, 45) + + def test_parity_gap_sign(self): + # C − P بزرگ‌تر از S − PV(K) ⇒ فرصت conversion + r = put_call_parity(500, 100, 1000, 1000, 30, 0.0) + self.assertGreater(r["gap"], 0) + self.assertEqual(r["direction"], "conversion") + + def test_tabei_min_yield_hand_computation(self): + r = tabei_min_yield(50000, 0, 62500, 365) + # بدون کارمزد: ۲۵٪ در یک سال (کمی کمتر با کارمزد خرید و فروش) + self.assertLess(r["period_return_pct"], 25.0) + self.assertGreater(r["period_return_pct"], 23.0) + + def test_covered_call_premium_annualized(self): + r = covered_call(7000, 7400, 220, 30) + self.assertGreater(r["premium_annualized_pct"], 30.0) + self.assertIn("upside_capped_at_pct", r) + + +class TestSizing(unittest.TestCase): + def test_position_size_respects_cap(self): + r = position_size(1_000_000_000, 150_000_000, risk_pct=0.20) + self.assertEqual(r["contracts"], 1) + self.assertGreaterEqual(r["free_cash"], 0) + self.assertEqual(r["min_cash_ratio"], 0.40) + + def test_score_penalizes_illiquidity(self): + base = {"annualized_pct": 60.0, "liquidity_contracts_per_day": 500, "spread_pct": 0.005} + illq = dict(base, liquidity_contracts_per_day=5) + self.assertGreater(score(base), score(illq)) + + +class TestRunner(unittest.TestCase): + def test_runner_sorts_and_reports_errors(self): + sc = Scenario(name="t", rows=[ + {"name": "bad", "kind": "nope"}, + {"name": "weak", "kind": "basis", "spot": 1000, "future": 1005, "days": 365}, + {"name": "strong", "kind": "basis", "spot": 1000, "future": 1220, "days": 60}, + ], hurdle=0.35) + out = run_scenario(sc) + self.assertEqual(out[0]["name"], "strong") + self.assertIn("error", out[-1]) + + def test_missing_key_is_error_not_crash(self): + sc = Scenario(name="t", rows=[{"name": "x", "kind": "box", "call_low": 1}], hurdle=0.35) + out = run_scenario(sc) + self.assertIn("error", out[0]) + + def test_fee_constant_is_expected_value(self): + self.assertAlmostEqual(FEE_FUND_ETF, 0.0012, places=10) + + +if __name__ == "__main__": + unittest.main(verbosity=2)