a commited on
Commit
87dd0fa
·
0 Parent(s):

بستهٔ داکر ایستگاه برای میزبان رندر

Browse files
This view is limited to 50 files because it contains too many changes.   See raw diff
Files changed (50) hide show
  1. Dockerfile +24 -0
  2. HF-BUNDLE-MANIFEST.json +26 -0
  3. README-HF-FA.md +121 -0
  4. README.md +5 -0
  5. boot.sh +46 -0
  6. desk/README-FA.md +100 -0
  7. desk/config.json +18 -0
  8. desk/desk.py +775 -0
  9. desk/market-demo.json +36 -0
  10. desk/run-demo.bat +5 -0
  11. desk/tests/test_desk.py +304 -0
  12. kodal-alert/README-FA.md +112 -0
  13. kodal-alert/config.json +22 -0
  14. kodal-alert/data/demo.sqlite3 +0 -0
  15. kodal-alert/kodal_alert.py +769 -0
  16. kodal-alert/run-daily.bat +7 -0
  17. kodal-alert/run-demo.bat +5 -0
  18. kodal-alert/tests/test_kodal_alert.py +194 -0
  19. render.yaml +25 -0
  20. station/DEMO-INVESTOR-FA.md +295 -0
  21. station/MAKE-PASSWORDS.py +76 -0
  22. station/README-FA.md +626 -0
  23. station/adminauth.py +217 -0
  24. station/autoconnect.py +306 -0
  25. station/backtest.py +403 -0
  26. station/bankroll.py +372 -0
  27. station/build-dossier.bat +11 -0
  28. station/config/connections.json +120 -0
  29. station/connections.py +367 -0
  30. station/daily_trial.py +386 -0
  31. station/data/data-requirement-sheet.md +28 -0
  32. station/data/history-template.csv +2 -0
  33. station/data/snapshot-template.json +109 -0
  34. station/data_sources.py +554 -0
  35. station/datafeed.py +671 -0
  36. station/demo/history-demo.csv +103 -0
  37. station/demo_day.py +567 -0
  38. station/diagnose.py +211 -0
  39. station/docs/01-derivatives-iran-fa.md +136 -0
  40. station/docs/02-ideas-iran-fa.md +75 -0
  41. station/docs/03-investor-and-first-money-fa.md +95 -0
  42. station/docs/04-trading-desk-plan-fa.md +105 -0
  43. station/docs/05-data-routes-fa.md +159 -0
  44. station/docs/06-data-feasibility-fa.md +126 -0
  45. station/docs/07-zero-cost-test-fa.md +113 -0
  46. station/docs/08-differentiation-and-trust-fa.md +187 -0
  47. station/docs/09-sell-or-grant-access-fa.md +120 -0
  48. station/docs/10-daily-inputs-fa.md +94 -0
  49. station/docs/11-usage-and-percent-fa.md +157 -0
  50. station/docs/12-wealth-math-and-no-purchase-fa.md +154 -0
Dockerfile ADDED
@@ -0,0 +1,24 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # تصویر اجرا روی Hugging Face Spaces (Docker SDK) و Render.
2
+ # تفاوتش با Dockerfile سرور: درگاه ۷۸۶۰ (قرار HF)، بدون volume، و اجرای برنامه با boot.sh
3
+ # که از متغیرهای محیطی، دو حساب را می‌سازد و دروازه را روشن می‌کند.
4
+ FROM python:3.13-slim
5
+
6
+ ENV PYTHONUNBUFFERED=1 \
7
+ PYTHONDONTWRITEBYTECODE=1 \
8
+ STATION_PORT=7860
9
+
10
+ WORKDIR /app
11
+ COPY . /app
12
+
13
+ # کاربر غیر ریشه (قرار خود HF) + پوشه‌های نوشتنی برنامه
14
+ RUN useradd -m -u 1000 desk \
15
+ && mkdir -p /app/data /app/config /app/export \
16
+ && chmod +x /app/boot.sh \
17
+ && chown -R desk:desk /app
18
+ USER desk
19
+
20
+ EXPOSE 7860
21
+ HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
22
+ CMD python -c "import urllib.request as u; u.urlopen('http://127.0.0.1:' + __import__('os').environ.get('PORT', '7860') + '/login', timeout=4)"
23
+
24
+ CMD ["bash", "boot.sh"]
HF-BUNDLE-MANIFEST.json ADDED
@@ -0,0 +1,26 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "name": "iran-desk-hf",
3
+ "files": 148,
4
+ "root": [
5
+ "Dockerfile",
6
+ "README-HF-FA.md",
7
+ "README.md",
8
+ "boot.sh",
9
+ "desk",
10
+ "kodal-alert",
11
+ "render.yaml",
12
+ "station",
13
+ "strategies",
14
+ "tools"
15
+ ],
16
+ "key_files": {
17
+ "Dockerfile": "9b941f077aa74a77",
18
+ "README.md": "b00e906f1d15480b",
19
+ "boot.sh": "2c620a90ffba5922",
20
+ "README-HF-FA.md": "7fa085a85f68a812",
21
+ "render.yaml": "2adcdff48d7c2c42"
22
+ },
23
+ "secret_like_literals_found": 0,
24
+ "phone_occurrences": 15,
25
+ "note": "ساخته‌شده برای میزبان ابری مجانی: درگاه ۷۸۶۰، دروازه از متغیرهای محیطی، بدون رمز در بسته"
26
+ }
README-HF-FA.md ADDED
@@ -0,0 +1,121 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # بردن برنامه روی یک میزبان مجانی (Hugging Face Spaces)
2
+
3
+ **این پرونده برای خودت است، نه برای کارفرما.** این‌جا نوشته‌ام چطور در حدود پنج دقیقه برنامه را
4
+ روی یک فضای مجانی بالا بیاوری، بدون سرور، بدون دامنه و **بدون کارت بانکی**. حساب کاربری را باید
5
+ خودت بسازی (ثبت‌نام به ایمیل خودت نیاز دارد)، ولی همهٔ کار فنی آماده است.
6
+
7
+ ## چه چیزی مجانی است و چه چیزی نیست (بی‌پرده)
8
+
9
+ | موضوع | واقعیت |
10
+ | --- | --- |
11
+ | هزینه | صفر. HF برای Space با CPU رایگان (۲ vCPU و ۱۶ گیگ رم) کارت بانکی نمی‌خواهد |
12
+ | نشانی | آدرس `https` روی دامنهٔ خودشان (`‎*.hf.space`) با گواهی SSL |
13
+ | داده | روی دیسک موقت (حدود ۵۰ گیگ)؛ **با هر بازسازی پاک می‌شود** |
14
+ | خواب رفتن | بعد از حدود ۴۸ ساعت بی‌کاری می‌خوابد؛ اولین بازدید ۳۰ تا ۹۰ ثانیه بیدارش می‌کند |
15
+ | خصوصی بودن | Space مجانی **عمومی** است؛ یعنی آدرسش برای همه باز است. پس دروازه باید روشن بماند و رمزها محرمانه |
16
+ | دادهٔ واقعی | **روی HF دادهٔ واقعی معاملات نگذار.** این نسخه برای نمایش و آزمون است |
17
+
18
+ ## گام‌به‌گام
19
+
20
+ ۱. **حساب بساز:** [huggingface.co/join](https://huggingface.co/join) (ایمیل و رمز؛ کارت نمی‌خواهد).
21
+
22
+ ۲. **Space بساز:** [huggingface.co/new-space](https://huggingface.co/new-space)
23
+ - **Name:** مثل `desk-station`
24
+ - **SDK:** `Docker` · **Template:** `Blank`
25
+ - **Space hardware:** `CPU basic · FREE`
26
+ - **Visibility:** `Public` → بعد `Create Space`
27
+
28
+ ۳. **بستهٔ آماده را بالا بگذار.** روی رایانهٔ خودت:
29
+
30
+ ```bash
31
+ # ۱) بسته را بساز (همین یک فرمان؛ خروجی در MATERIALS/money/delivery/iran-desk-hf)
32
+ cd MATERIALS/money/gui/deploy
33
+ python3 make_hf.py --zip
34
+
35
+ # ۲) ابزار آپلود
36
+ pip install -U huggingface_hub
37
+ hf auth login # توکن را از Settings → Access Tokens بساز و بچسبان
38
+
39
+ # ۳) آپلود
40
+ hf upload <نام‌کاربری>/desk-station ../../../delivery/iran-desk-hf . --repo-type space
41
+ ```
42
+
43
+ روش جایگزین با git:
44
+
45
+ ```bash
46
+ git clone https://huggingface.co/spaces/<نام‌کاربری>/desk-station
47
+ cp -r ../../../delivery/iran-desk-hf/. desk-station/
48
+ cd desk-station && git add -A && git commit -m "ایستگاه تصمیم مشتقه" && git push
49
+ ```
50
+
51
+ ۴. **پنج مقدار محرمانه** را در `Settings` → `Variables and secrets` → `New secret` بگذار:
52
+
53
+ | نام | مقدار |
54
+ | --- | --- |
55
+ | `STATION_ADMIN_ID` | شناسهٔ مدیر (مثل `mafhoom`) |
56
+ | `STATION_ADMIN_PASS` | رمز قوی پنل مدیریت (خودت بساز: ۱۲ نویسهٔ تصادفی) |
57
+ | `STATION_GUEST_ID` | شناسهٔ کارفرما (مثل `masoud`) |
58
+ | `STATION_GUEST_PASS` | رمز قوی کارفرما (این را به او می‌دهی) |
59
+ | `STATION_GUEST_OFF` | اختیاری: `1` یعنی کارفرما فعلاً نتواند وارد شود |
60
+
61
+ اگر این‌ها را نگذاری، برنامه موقع بالا آمدن **خودش رمز تصادفی می‌سازد و در گزارش (Logs) چاپ می‌کند** —
62
+ کار می‌کند، ولی رمز در گزارش می‌ماند؛ برای آزمون سریع خوب است، برای کار جدی نه.
63
+
64
+ ۵. وقتی وضعیت Space روی `Running` رفت، این آدرس را باز کن و یک‌بار خودت با حساب مدیر وارد شو:
65
+
66
+ ```
67
+ https://<نام‌کاربری>-desk-station.hf.space/login
68
+ ```
69
+
70
+ بعد همان آدرس `‎/login` را با **رمز کارفرما** برایش بفرست. رمز مدیر را هرگز نفرست.
71
+
72
+ ## مهم: دو راه HF داریم و یکی از آن‌ها مجانی است
73
+
74
+ آزمودیم (۲۲ سپتامبر ۲۰۲۶): Space **داکری** روی حساب مجانی HF پاسخ ۴۰۲ می‌دهد و اشتراک PRO لازم
75
+ دارد. ولی Space **ایستا** برای همه مجانی است. پس دو ابزار داریم:
76
+
77
+ | راه | فرمان | چه می‌دهد |
78
+ | --- | --- | --- |
79
+ | نمونهٔ ثابت (مجانی) | `./activate_demo_site.sh` | خودِ رابط + تمام خروجی‌های واقعی، روی یک لینک عمومی ثابت، بدون کارتی |
80
+ | برنامهٔ زندهٔ داکری | `./activate_hf.sh` | اگر روزی PRO داشتی: سرور کامل با دروازهٔ ورود و دادهٔ زنده |
81
+
82
+ نمونهٔ ثابت از این‌ها ساخته می‌شود: `tools/record_static_demo.mjs` (ضبط پاسخ‌های واقعی در حاشیهٔ
83
+ همان آزمون ۱۹۲ بررسی) → `deploy/make_demo_site.py` (ساخت سایت ایستا + لایهٔ پاسخ‌های ضبط‌شده) →
84
+ `deploy/huggingface/activate_demo_site.py` (نشر + آزمودن زنده با `tools/check_demo_site.mjs`).
85
+
86
+ ## آزمودن سمت خودت (پیش از آپلود)
87
+
88
+ خود `boot.sh` همان کاری را می‌کند که HF می‌کند؛ می‌توانی محلی هم بیازمایی:
89
+
90
+ ```bash
91
+ cd ../../../delivery/iran-desk-hf
92
+ STATION_ADMIN_PASS='<رمز-آزمون-مدیر>' STATION_GUEST_ID=masoud STATION_GUEST_PASS='<رمز-آزمون-کارفرما>' \
93
+ STATION_PORT=7860 bash boot.sh
94
+ # در مرورگر: http://127.0.0.1:7860 (بدون ورود ۴۰۱ · با حساب کارفرما ۲۰۰ · پنل مدیر ۴۰۳ برای کارفرما)
95
+ ```
96
+
97
+ ## بیدار نگه داشتن (اختیاری، مجانی)
98
+
99
+ Space مجانی بعد از حدود ۴۸ ساعت بی‌کاری می‌خوابد. اگر می‌خواهی همیشه بیدار باشد، در یک سرویس
100
+ زمان‌بند مجانی (مثل cron-job.org) یک کار بساز که هر یک ساعت آدرس `https://<...>.hf.space/login`
101
+ را باز کند. این کار هم مجانی است، ولی تضمین آپ‌تایم نمی‌دهد.
102
+
103
+ ## خاموش کردن و حذف
104
+
105
+ - **خاموش موقت:** در `Settings` → `Pause this Space`
106
+ - **حذف کامل:** در `Settings` → `Delete this Space`
107
+ - **قطع فقط کارفرما، بدون خواباندن برنامه:** `STATION_GUEST_OFF=1` را در Secrets بگذار (یا در
108
+ پنل مدیریت نشست‌های مهمان را ببند)
109
+
110
+ هیچ‌چیز این‌جا گروگان نیست: هر وقت سرور یا دامنهٔ خودت را آوردی، همین برنامه را با پوشهٔ `deploy/`
111
+ روی آن ببر و Space را حذف کن؛ داده و رمزها سمت خودت می‌مانند.
112
+
113
+ ## اگر HF را نخواستی: Render
114
+
115
+ `deploy/render/render.yaml` هم گذاشته‌ام (یک میزبان مجانی دیگر، بدون کارت بانکی). فرقش: فقط
116
+ ۵۱۲ مگ رم و ۰٫۱ پردازنده دارد، **بعد از ۱۵ دقیقه بی‌کاری می‌خوابد** و بیدار شدنش ۳۰ تا ۶۰ ثانیه
117
+ طول می‌کشد؛ برای نمایش زندهٔ نیم‌ساعته خوب نیست، برای تست‌های گاه‌به‌گاه به‌کار می‌آید. راهش:
118
+ کد را روی یک مخزن GitHub بگذار و در Render گزینهٔ `Blueprint` را انتخاب کن.
119
+
120
+ > **پرسش باز:** اگر حساب HF یا GitHub داری و می‌خواهی خودم گام‌ها را با تو جلو ببرم، بگو کدام گام
121
+ > گیر کردی؛ ولی ساختن حساب و زدن توکن باید دست خودت باشد (رمز و ایمیل تو را نمی‌پرسم).
README.md ADDED
@@ -0,0 +1,5 @@
 
 
 
 
 
 
1
+ # Iran Desk Station — Docker bundle (for Render / any Docker host)
2
+
3
+ Full trading-decision station (Python stdlib server). Build: `docker build .` then run with env:
4
+ `STATION_ADMIN_ID`, `STATION_ADMIN_PASS`, `STATION_GUEST_ID`, `STATION_GUEST_PASS`.
5
+ Listens on `$PORT` (default 7860). Health check: `/login`.
boot.sh ADDED
@@ -0,0 +1,46 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env bash
2
+ # بالا آوردن ایستگاه روی میزبان ابری (Hugging Face Spaces یا Render).
3
+ #
4
+ # ترتیب کار: از محیط، شناسه و رمزها را می‌خواند → دروازه را روشن می‌کند → برنامه را اجرا می‌کند.
5
+ # اگر رمزی در محیط نبود، خودش رمز قوی می‌سازد و در گزارش چاپ می‌کند (برای آزمون سریع).
6
+ set -euo pipefail
7
+ HERE="$(cd "$(dirname "$0")" && pwd)"
8
+ cd "$HERE/station" # برنامه، پوشهٔ «desk» و «kodal-alert» را همسایهٔ خودش می‌خواهد
9
+
10
+ # میزبان‌ها درگاه را خودشان می‌دهند: HF انتظار ۷۸۶۰ دارد، Render متغیر PORT می‌فرستد.
11
+ PORT="${PORT:-${STATION_PORT:-7860}}"
12
+ ADMIN_ID="${STATION_ADMIN_ID:-mafhoom}"
13
+ GUEST_ID="${STATION_GUEST_ID:-masoud}"
14
+ ADMIN_PASS="${STATION_ADMIN_PASS:-}"
15
+ GUEST_PASS="${STATION_GUEST_PASS:-}"
16
+
17
+ gen() { python3 -c "import secrets; print('Desk-' + secrets.token_hex(4))"; }
18
+
19
+ echo "── ایستگاه تصمیم مشتقه، نسخهٔ میزبان ابری ──"
20
+ echo " درگاه: $PORT · شناسهٔ مدیر: $ADMIN_ID · شناسهٔ کارفرما: $GUEST_ID"
21
+
22
+ if [ -z "$ADMIN_PASS" ]; then
23
+ ADMIN_PASS="$(gen)"
24
+ echo " ⚠️ STATION_ADMIN_PASS نبود؛ رمز مدیر ساخته شد: $ADMIN_PASS"
25
+ echo " این رمز را در Secrets بگذار (این پیام فقط برای خودت است، ولی در گزارش می‌ماند)."
26
+ fi
27
+ python3 adminauth.py --set-id "$ADMIN_ID" --set-pass "$ADMIN_PASS" >/dev/null
28
+
29
+ if [ -z "$GUEST_PASS" ]; then
30
+ GUEST_PASS="$(gen)"
31
+ echo " ⚠️ STATION_GUEST_PASS نبود؛ رمز کارفرما ساخته شد: $GUEST_PASS"
32
+ fi
33
+ python3 gate.py --sync-admin >/dev/null
34
+ python3 gate.py --guest-id "$GUEST_ID" --guest-pass "$GUEST_PASS" >/dev/null
35
+ if [ "${STATION_GUEST_OFF:-0}" = "1" ]; then
36
+ python3 gate.py --guest-off >/dev/null
37
+ echo " کارفرما فعلاً بسته است (STATION_GUEST_OFF=1)."
38
+ else
39
+ python3 gate.py --guest-on >/dev/null
40
+ fi
41
+ python3 gate.py --on >/dev/null
42
+ echo " دروازه روشن است: بدون شناسه و رمز، هیچ صفحه‌ای باز نمی‌شود."
43
+ python3 gate.py --status | sed 's/^/ /'
44
+
45
+ echo " آماده است. آدرس درگاه: 0.0.0.0:$PORT (بدون ورود: 401)"
46
+ exec python3 -m web_server --port "$PORT" --host 0.0.0.0 --no-browser
desk/README-FA.md ADDED
@@ -0,0 +1,100 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # میز معاملات (دستیار تصمیم با تأیید انسان) — راهنمای فارسی
2
+
3
+ نسخهٔ ۰٫۱٫۰ · صفر وابستگی · اجرا روی ویندوز یا لینوکس · بدون اینترنت هم کار می‌کند
4
+
5
+ ## این برنامه چه کار می‌کند
6
+
7
+ ۱. یک **اسنپ‌شات بازار** (پروندهٔ JSON ساده) را می‌گیرد: قیمت پایه، زنجیرهٔ آپشن، آتی، اوراق تبعی، وجه تضمین.
8
+ ۲. هر ردیف را روی **موتور ریاضی** (`../tools/derivatives_scout.py`) می‌گذارد: پایهٔ نقدی‌آتی، باکس اسپرد، تبعی، پوشش‌داده‌شده، تساوی پوت‌کال.
9
+ ۳. خبرها و هشدارهای **دیده‌بان کدال** را به همان نمادها می‌چسباند (خبر به‌تنهایی سیگنال نیست؛ خبرها موتور را دوباره حساب‌شده نگه می‌دارند).
10
+ ۴. **دروازه‌های ریسک** را اعمال می‌کند و اندازهٔ هر موقعیت را از بودجهٔ وجه تضمین درمی‌آورد.
11
+ ۵. یک **داشبورد HTML** می‌سازد و **بستهٔ سفارش** چاپ می‌کند تا **انسان** آن را در سامانهٔ کارگزاری اجرا کند.
12
+
13
+ ## این برنامه چه کار نمی‌کند (مهم)
14
+
15
+ - **هیچ سفارشی ارسال نمی‌کند.** طبق ابلاغیهٔ مهر ۱۳۹۹ سازمان بورس، معاملات الگوریتمی و تقسیم سفارشات توسط مشتریان برخط در بورس و فرابورس «تا اطلاع ثانوی» ممنوع است و کارگزاران موظف‌اند چنین دسترسی‌هایی را ببندند.
16
+ - سود تضمین نمی‌کند، قیمت پیش‌بینی نمی‌کند، و هیچ‌جا «سیگنال خرید» به معنای توصیه نمی‌دهد. خروجی، «تفاوت ریاضی با نرخ سد» است.
17
+
18
+ ## چرخهٔ کار (هفت گام)
19
+
20
+ ```
21
+ اسنپ‌شات بازار → موتور ریاضی → چسباندن هشدارهای کدال → دروازه‌های ریسک
22
+ ↓
23
+ اندازه‌گذاری از بودجهٔ وجه تضمین → داشبورد تصمیم → تأیید یا رد انسانی → بستهٔ سفارش → اجرا در کارگزاری
24
+ ```
25
+
26
+ ## اجرا
27
+
28
+ ```bash
29
+ python desk.py selftest
30
+ python desk.py run --market market-demo.json --kodal-db ../kodal-alert/data/demo.sqlite3
31
+ python desk.py list --status pending
32
+ python desk.py approve 3ed6c3f0710c --note "ریسک پذیرفته شد و منبع خبر هم بررسی شد"
33
+ python desk.py reject f9c3112e6ff2 --note "عمق بازار کافی نیست"
34
+ python desk.py packet 3ed6c3f0710c
35
+ python -m unittest discover -s tests # ۲۶ آزمون واحد
36
+ ```
37
+
38
+ ## قالب اسنپ‌شات بازار
39
+
40
+ ```json
41
+ {"as_of": "2026-09-22", "hurdle": 0.39, "capital": 20000000000,
42
+ "rows": [
43
+ {"symbol": "اهرم", "kind": "basis", "spot": 20000, "future": 22800, "days": 90,
44
+ "margin_per_contract": 20000000, "unit": "قرارداد",
45
+ "liquidity_contracts_per_day": 900, "spread_pct": 0.005},
46
+ {"symbol": "فولاد", "kind": "covered_call", "spot": 7000, "strike": 7600,
47
+ "premium": 400, "days": 45, "margin_per_contract": 7000, "unit": "سهم"}
48
+ ]}
49
+ ```
50
+
51
+ انواع `kind`: `basis` (پایهٔ نقدی‌آتی) · `box` (باکس اسپرد) · `tabei` (اوراق اختیار فروش تبعی) · `covered_call` (فروش کال پوشش‌داده‌شده) · `parity` (تساوی پوت‌کال).
52
+
53
+ کلیدهای هر ردیف: `symbol`، `kind`، پارامترهای ریاضی همان راهبرد (مثل `spot`، `future`، `strike`، `premium`، `put_price`، `days`)، `margin_per_contract` (وجه تضمین یا بهای هر واحد)، `unit` (قرارداد یا سهم)، `liquidity_contracts_per_day` و `spread_pct` برای دروازهٔ نقدشوندگی.
54
+
55
+ ## قواعد ریسک پیش‌فرض (`config.json`)
56
+
57
+ | قاعده | پیش‌فرض | معنا |
58
+ |---|---|---|
59
+ | `max_margin_pct` | ۲۰ درصد | سقف کل سرمایهٔ درگیر در وجه تضمین |
60
+ | `max_position_pct` | ۳۵ درصد از بودجه | سقف هر موقعیت، تا یک معامله همهٔ بودجه را نخورد |
61
+ | `max_positions` | ۳ | سقف موقعیت‌های تأییدشدهٔ هم‌زمان |
62
+ | `min_liquidity_contracts_per_day` | ۲۰ | کف نقدشوندگی |
63
+ | `max_spread_pct` | ۳ درصد | سقف اسپرد خرید‌وفروش |
64
+ | `min_edge_arbitrage_pct` | ۳ واحد درصد | کف حاشیه برای راهبردهای آربیتراژی |
65
+ | `min_edge_leveraged_pct` | ۵ واحد درصد | کف حاشیه برای راهبردهای اهرمی |
66
+
67
+ تأیید انسانی هم از همین سقف‌ها عبور نمی‌کند: اگر تأیید سیگنالی سقف ریسک را رد کند، برنامه با کد خروج ۳ متو��ف می‌شود و فقط با `--force` و ثبت دلیل در دفتر، رد می‌شود.
68
+
69
+ ## هفت چیزی که در نمونهٔ آماده می‌بینید
70
+
71
+ ۱. «اهرم · پایهٔ نقدی‌آتی» با حاشیهٔ ۲۹٫۴۸ واحد درصد منتظر تأیید است، چون نرخ تلویحی آتی از نرخ سد جلوتر است.
72
+ ۲. «فولاد · پوشش‌داده‌شده» با حاشیهٔ ۱۷٫۵۶ واحد درصد منتظر است؛ پرمیوم گران است.
73
+ ۳. «کگل · تبعی» با حاشیهٔ ۳٫۳۶ واحد درصد به‌سختی از دروازه رد می‌شود.
74
+ ۴. «خساپا · تبعی» رد می‌شود، چون بازده تضمینی‌اش از صندوق درآمد ثابت کمتر است؛ این درسِ اصلی این بازار است.
75
+ ۵. «وبملت · تساوی پوت‌کال» رد می‌شود، چون نیمهٔ دیگر آربیتراژ به فروش استقراضی نیاز دارد و در ایران ممکن نیست.
76
+ ۶. «شپنا · باکس اسپرد» با وجود بازده خوب رد می‌شود، چون حجم روزانه‌اش ۱۲ و اسپردش ۴٫۵ درصد است.
77
+ ۷. «طلا · پایهٔ نقدی‌آتی» رد می‌شود، چون مبنای آتی از نرخ صندوق درآمد ثابت کمتر است.
78
+
79
+ ## وصل شدن به دیده‌بان کدال
80
+
81
+ پایگاه‌دادهٔ دیده‌بان را با `--kodal-db` بدهید. برنامه سه کار می‌کند:
82
+
83
+ - هشدارهای همان نماد را در داشبورد زیر سیگنال نشان می‌دهد.
84
+ - برای نمادهایی که خبر مهم دارند ولی در اسنپ‌شات بازار نیستند، «کار بازبینی» می‌سازد.
85
+ - برای سیگنال‌های بدون پشتوانهٔ خبری و حاشیهٔ کم، دروازهٔ اولویت‌پایین فعال می‌شود.
86
+
87
+ ## اجرا در شرایط ایران
88
+
89
+ - روی رایانهٔ خودتان اجرا کنید؛ هیچ سرویس ابری و هیچ پرداخت ارزی لازم نیست.
90
+ - اگر اینترنت یا سامانهٔ داده در دسترس نیست، اسنپ‌شات را دستی از سامانهٔ کارگزاری در `market.json` وارد کنید و همان را اجرا کنید.
91
+ - پایگاه‌داده روی دیسک است؛ قطعی برق تصمیم‌های ثبت‌شده را از بین نمی‌برد و اجرای بعدی، وضعیت‌ها را حفظ می‌کند.
92
+ - تصمیم‌های انسان (تأیید و رد) قفل می‌شوند و اجرای دوبارهٔ `run` آن‌ها را بازنویسی نمی‌کند.
93
+
94
+ ## قدم بعدی
95
+
96
+ اتصال خودکار دادهٔ `tsetmc` و زنجیرهٔ آپشن، و گزارش روزانه‌ای که بازده انتظاری را با نتیجهٔ واقعی مقایسه کند. تا آن زمان، ورود دستی اسنپ‌شات کامل است.
97
+
98
+ ## تهیه‌کننده
99
+
100
+ ✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · 📱 [+989126630554](tel:+989126630554) · ✈️ [Telegram: Mojarabian](https://t.me/Mojarabian) · 📸 [Instagram: Mojarabian.Art](https://www.instagram.com/Mojarabian.Art/)
desk/config.json ADDED
@@ -0,0 +1,18 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "capital": 5000000000,
3
+ "hurdle": 0.39,
4
+ "min_edge_arbitrage_pct": 3.0,
5
+ "min_edge_leveraged_pct": 5.0,
6
+ "max_margin_pct": 0.2,
7
+ "max_positions": 3,
8
+ "min_liquidity_contracts_per_day": 20,
9
+ "max_spread_pct": 0.03,
10
+ "alert_score_threshold": 60,
11
+ "desk_db": "",
12
+ "report_path": "",
13
+ "credit": "تهیه‌کننده: Masoud Mojarabian · https://www.instagram.com/Mojarabian.Art/ · tel:+989126630554 · https://t.me/Mojarabian",
14
+ "report_title": "میز معاملات — داشبورد تصمیم",
15
+ "max_position_pct": 0.35,
16
+ "max_plausible_arb_pct": 250.0,
17
+ "max_plausible_lev_pct": 400.0
18
+ }
desk/desk.py ADDED
@@ -0,0 +1,775 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env python3
2
+ # -*- coding: utf-8 -*-
3
+ """میز معاملات (دستیار تصمیم با تأیید انسان) — نسخهٔ ۰٫۱٫۰
4
+
5
+ این برنامه سه کار می‌کند:
6
+ ۱. دادهٔ بازار (اسنپ‌شات JSON) را روی موتور ریاضی مشتقه می‌گذارد.
7
+ ۲. هشدارهای «دیده‌بان کدال» را به سیگنال‌های ریاضی می‌چسباند.
8
+ ۳. بستهٔ سفارش آماده می‌کند تا **انسان** آن را در سامانهٔ کارگزاری اجرا کند.
9
+
10
+ هیچ سفارشی از این برنامه ارسال نمی‌شود. علت: معاملات الگوریتمی خودکار در
11
+ بورس و فرابورس ایران، طبق ابلاغیهٔ مهر ۱۳۹۹ سازمان بورس، «تا اطلاع ثانوی» ممنوع است.
12
+
13
+ دستورها:
14
+ python desk.py selftest
15
+ python desk.py run --market market-demo.json --kodal-db ../kodal-alert/data/demo.sqlite3
16
+ python desk.py list --status pending
17
+ python desk.py approve 3f2a... --note "ریسک پذیرفته شد"
18
+ python desk.py reject 3f2a... --note "نقدشوندگی کم"
19
+ python desk.py packet 3f2a...
20
+ """
21
+ from __future__ import annotations
22
+
23
+ import argparse
24
+ import hashlib
25
+ import html
26
+ import importlib.util
27
+ import json
28
+ import sqlite3
29
+ import sys
30
+ from dataclasses import dataclass, field
31
+ from datetime import datetime, timezone
32
+ from pathlib import Path
33
+
34
+ VERSION = "0.1.0"
35
+ BASE = Path(__file__).resolve().parent
36
+ DEFAULT_DB = BASE / "data" / "desk.sqlite3"
37
+ DEFAULT_REPORT = BASE / "data" / "dashboard.html"
38
+ SCOUT_PATH = (BASE.parent / "tools" / "derivatives_scout.py").resolve()
39
+ CREDIT = ("تهیه‌کننده: Masoud Mojarabian · https://www.instagram.com/Mojarabian.Art/ · "
40
+ "tel:+989126630554 · https://t.me/Mojarabian")
41
+
42
+ DEFAULT_CONFIG: dict = {
43
+ "capital": 5_000_000_000,
44
+ "hurdle": 0.39,
45
+ "min_edge_arbitrage_pct": 3.0,
46
+ "min_edge_leveraged_pct": 5.0,
47
+ "max_margin_pct": 0.20,
48
+ "max_positions": 3,
49
+ "max_position_pct": 0.35,
50
+ "min_liquidity_contracts_per_day": 20,
51
+ "max_spread_pct": 0.03,
52
+ "alert_score_threshold": 60,
53
+ "max_plausible_arb_pct": 250.0, # سقف باورپذیری بازده سالانهٔ راهبردهای آربیتراژی
54
+ "max_plausible_lev_pct": 400.0, # سقف باورپذیری بازده سالانهٔ راهبردهای اهرمی
55
+ "desk_db": "",
56
+ "report_path": "",
57
+ "credit": CREDIT,
58
+ "report_title": "میز معاملات — داشبورد تصمیم",
59
+ }
60
+
61
+ # ---------------------------------------------------------------- دسترسی به موتور ریاضی
62
+ _SCOUT_CACHE: dict[str, object] = {}
63
+
64
+
65
+ def load_scout(path: Path = SCOUT_PATH):
66
+ """موتور ریاضی مشتقه را از پروندهٔ همسایه بارگذاری می‌کند (بدون نصب بسته).
67
+
68
+ نتیجه در حافظه می‌ماند: بی این کش، پس‌آزمایی هر سطر یک بار کل موتور را از نو
69
+ بارگذاری می‌کرد و صد سطر تاریخ چند ثانیه طول می‌کشید.
70
+ """
71
+ key = str(Path(path).resolve())
72
+ cached = _SCOUT_CACHE.get(key)
73
+ if cached is not None:
74
+ return cached
75
+ p = Path(path)
76
+ if not p.exists():
77
+ raise FileNotFoundError(f"موتور ریاضی پیدا نشد: {path}")
78
+ spec = importlib.util.spec_from_file_location("derivatives_scout", str(p))
79
+ module = importlib.util.module_from_spec(spec)
80
+ assert spec.loader is not None
81
+ # ثبت در sys.modules پیش از اجرا لازم است، وگرنه dataclass داخل موتور خطا می‌دهد
82
+ sys.modules["derivatives_scout"] = module
83
+ spec.loader.exec_module(module)
84
+ _SCOUT_CACHE[key] = module
85
+ return module
86
+
87
+
88
+ # ---------------------------------------------------------------- ابزار پایه
89
+ def now_iso() -> str:
90
+ return datetime.now(timezone.utc).isoformat(timespec="seconds")
91
+
92
+
93
+ def g2j(gy: int, gm: int, gd: int) -> tuple[int, int, int]:
94
+ g_d_m = [0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334]
95
+ gy2 = gy + 1 if gm > 2 else gy
96
+ days = 355666 + (365 * gy) + ((gy2 + 3) // 4) - ((gy2 + 99) // 100) + ((gy2 + 399) // 400) + gd + g_d_m[gm - 1]
97
+ jy = -1595 + 33 * (days // 12053)
98
+ days %= 12053
99
+ jy += 4 * (days // 1461)
100
+ days %= 1461
101
+ if days > 365:
102
+ jy += (days - 1) // 365
103
+ days = (days - 1) % 365
104
+ jm = 1 + days // 31 if days < 186 else 7 + (days - 186) // 30
105
+ jd = 1 + days % 31 if days < 186 else 1 + (days - 186) % 30
106
+ return jy, jm, jd
107
+
108
+
109
+ def fa_time(dt: datetime | None = None) -> str:
110
+ dt = dt or datetime.now(timezone.utc)
111
+ jy, jm, jd = g2j(dt.year, dt.month, dt.day)
112
+ return f"{jy:04d}/{jm:02d}/{jd:02d} {dt.hour:02d}:{dt.minute:02d}"
113
+
114
+
115
+ def log(msg: str) -> None:
116
+ print(f"[{fa_time()}] {msg}")
117
+
118
+
119
+ def load_config(path: str | None = None) -> dict:
120
+ cfg = json.loads(json.dumps(DEFAULT_CONFIG, ensure_ascii=False))
121
+ p = Path(path) if path else BASE / "config.json"
122
+ if p.exists():
123
+ try:
124
+ user = json.loads(p.read_text(encoding="utf-8"))
125
+ for k, v in user.items():
126
+ if isinstance(v, dict) and isinstance(cfg.get(k), dict):
127
+ cfg[k].update(v)
128
+ else:
129
+ cfg[k] = v
130
+ except json.JSONDecodeError as e:
131
+ log(f"تنظیمات خوانده نشد ({e})؛ پیش‌فرض به کار می‌رود.")
132
+ return cfg
133
+
134
+
135
+ # ---------------------------------------------------------------- داده‌ها
136
+ @dataclass
137
+ class Signal:
138
+ sid: str
139
+ symbol: str
140
+ kind: str
141
+ name: str
142
+ annualized_pct: float | None
143
+ score_pp: float
144
+ go: bool
145
+ detail: dict = field(default_factory=dict)
146
+ margin_per_contract: float = 0.0
147
+ contracts: int = 0
148
+ margin_locked: float = 0.0
149
+ status: str = "pending"
150
+ gate_note: str = ""
151
+ alerts: list[dict] = field(default_factory=list)
152
+
153
+ @property
154
+ def unit(self) -> str:
155
+ return str(self.detail.get("unit") or "قرارداد")
156
+
157
+ def as_row(self) -> tuple:
158
+ return (self.sid, now_iso(), self.symbol, self.kind, self.name,
159
+ self.annualized_pct, self.score_pp, int(self.go),
160
+ json.dumps(self.detail, ensure_ascii=False), self.margin_per_contract,
161
+ self.contracts, self.margin_locked, self.status, self.gate_note,
162
+ json.dumps(self.alerts, ensure_ascii=False))
163
+
164
+ @staticmethod
165
+ def from_row(row) -> "Signal":
166
+ (sid, _ts, symbol, kind, name, annualized, score_pp, go,
167
+ detail, margin, contracts, locked, status, gate_note, alerts) = row
168
+ return Signal(sid=sid, symbol=symbol, kind=kind, name=name, annualized_pct=annualized,
169
+ score_pp=score_pp, go=bool(go), detail=json.loads(detail or "{}"),
170
+ margin_per_contract=margin or 0.0, contracts=contracts or 0,
171
+ margin_locked=locked or 0.0, status=status, gate_note=gate_note or "",
172
+ alerts=json.loads(alerts or "[]"))
173
+
174
+
175
+ SIGNAL_SELECT = ("SELECT sid, ts, symbol, kind, name, annualized, score_pp, go, detail, "
176
+ "margin_per_contract, contracts, margin_locked, status, gate_note, alerts FROM signals")
177
+
178
+
179
+ class Desk:
180
+ def __init__(self, path: Path | str = DEFAULT_DB):
181
+ self.path = Path(path)
182
+ self.path.parent.mkdir(parents=True, exist_ok=True)
183
+ self.conn = sqlite3.connect(str(self.path))
184
+ self.conn.executescript("""
185
+ CREATE TABLE IF NOT EXISTS signals (
186
+ sid TEXT PRIMARY KEY, ts TEXT, symbol TEXT, kind TEXT, name TEXT,
187
+ annualized REAL, score_pp REAL, go INTEGER, detail TEXT,
188
+ margin_per_contract REAL, contracts INTEGER, margin_locked REAL,
189
+ status TEXT, gate_note TEXT, alerts TEXT);
190
+ CREATE TABLE IF NOT EXISTS decisions (
191
+ id INTEGER PRIMARY KEY AUTOINCREMENT, ts TEXT, sid TEXT, action TEXT, note TEXT);
192
+ """)
193
+ self.conn.commit()
194
+
195
+ # ── بستن تمیز (پایان کار / پرونده‌های موقت)
196
+ def close(self) -> None:
197
+ """پیوند پایگاه‌داده را می‌بندد. چند بار صدا زدنش بی‌خطر است."""
198
+ try:
199
+ self.conn.close()
200
+ except Exception: # noqa: BLE001 — بستن نباید برنامه را بیندازد
201
+ pass
202
+
203
+ def __enter__(self) -> "Desk":
204
+ return self
205
+
206
+ def __exit__(self, *exc) -> None:
207
+ self.close()
208
+
209
+ def __del__(self) -> None:
210
+ self.close()
211
+
212
+
213
+ # ---------- ثبت سیگنال
214
+ def upsert(self, sig: Signal, keep_status: bool = True) -> None:
215
+ old = self.get(sig.sid)
216
+ if old and keep_status:
217
+ sig.status = old.status
218
+ if old.gate_note and not sig.gate_note:
219
+ sig.gate_note = old.gate_note
220
+ self.conn.execute("DELETE FROM signals WHERE sid = ?", (sig.sid,))
221
+ self.conn.execute(
222
+ "INSERT INTO signals VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)", sig.as_row())
223
+ self.conn.commit()
224
+
225
+ def get(self, sid: str) -> Signal | None:
226
+ cur = self.conn.execute(SIGNAL_SELECT + " WHERE sid = ?", (sid,))
227
+ row = cur.fetchone()
228
+ return Signal.from_row(row) if row else None
229
+
230
+ def all(self, status: str | None = None, limit: int = 200) -> list[Signal]:
231
+ q = SIGNAL_SELECT + (" WHERE status = ?" if status else "") + " ORDER BY score_pp DESC LIMIT ?"
232
+ args = (status, limit) if status else (limit,)
233
+ return [Signal.from_row(r) for r in self.conn.execute(q, args).fetchall()]
234
+
235
+ def locked_margin(self, exclude_sid: str | None = None) -> float:
236
+ cur = self.conn.execute(
237
+ "SELECT COALESCE(SUM(margin_locked),0) FROM signals WHERE status = 'approved' AND sid IS NOT ?",
238
+ (exclude_sid,))
239
+ return float(cur.fetchone()[0])
240
+
241
+ def decide(self, sid: str, action: str, note: str) -> bool:
242
+ sig = self.get(sid)
243
+ if not sig:
244
+ return False
245
+ sig.status = action
246
+ if note:
247
+ sig.gate_note = note
248
+ self.upsert(sig, keep_status=False) # وضعیت تازه، عمداً بر وضعیت قبلی نوشته می‌شود
249
+ self.conn.execute("INSERT INTO decisions (ts, sid, action, note) VALUES (?,?,?,?)",
250
+ (now_iso(), sid, action, note))
251
+ self.conn.commit()
252
+ return True
253
+
254
+ def human_decided(self, sid: str) -> bool:
255
+ cur = self.conn.execute("SELECT 1 FROM decisions WHERE sid = ? LIMIT 1", (sid,))
256
+ return cur.fetchone() is not None
257
+
258
+ def decisions(self, limit: int = 50) -> list[tuple]:
259
+ return self.conn.execute(
260
+ "SELECT ts, sid, action, note FROM decisions ORDER BY id DESC LIMIT ?", (limit,)).fetchall()
261
+
262
+
263
+ # ---------------------------------------------------------------- خواندن هشدارهای کدال
264
+ def read_alerts(kodal_db: Path | str, min_score: int = 60, limit: int = 50) -> list[dict]:
265
+ """هشدارهای دیده‌بان را می‌خواند. اگر پایگاه‌داده نبود، فهرست خالی برمی‌گرداند."""
266
+ p = Path(kodal_db)
267
+ if not p.exists():
268
+ log(f"پایگاه‌داده دیده‌بان پیدا نشد: {p}")
269
+ return []
270
+ try:
271
+ conn = sqlite3.connect(f"file:{p}?mode=ro", uri=True)
272
+ rows = conn.execute(
273
+ "SELECT title, symbol, category, direction, score, url FROM items "
274
+ "WHERE score >= ? ORDER BY score DESC LIMIT ?", (min_score, limit)).fetchall()
275
+ conn.close()
276
+ except sqlite3.Error as e:
277
+ log(f"خواندن هشدارها ممکن نشد: {e}")
278
+ return []
279
+ return [{"title": t, "symbol": s, "category": c, "direction": d, "score": sc, "url": u}
280
+ for t, s, c, d, sc, u in rows]
281
+
282
+
283
+ def related_alerts(symbol: str, alerts: list[dict]) -> list[dict]:
284
+ out = []
285
+ for a in alerts:
286
+ sym = (a.get("symbol") or "").strip()
287
+ if sym and (sym == symbol or sym in symbol or symbol in sym):
288
+ out.append(a)
289
+ elif not sym and symbol and symbol in (a.get("title") or ""):
290
+ out.append(a)
291
+ return out
292
+
293
+
294
+ # ---------------------------------------------------------------- موتور ریاضی
295
+ KIND_LABELS = {
296
+ "basis": "پایهٔ نقدی‌آتی",
297
+ "box": "باکس اسپرد",
298
+ "tabei": "اوراق تبعی",
299
+ "covered_call": "پوشش‌داده‌شده",
300
+ "parity": "تساوی پوت‌کال",
301
+ }
302
+
303
+
304
+ def math_for_row(row: dict, hurdle: float) -> dict:
305
+ """هر ردیف اسنپ‌شات را روی موتور ریاضی می‌گذارد و خروجی استاندارد برمی‌گرداند."""
306
+ scout = load_scout()
307
+ sc = scout.Scenario(name=row.get("symbol", "?"), rows=[{k: v for k, v in row.items() if k != "margin_per_contract"}],
308
+ hurdle=hurdle)
309
+ result = scout.run_scenario(sc)[0]
310
+ if "error" in result:
311
+ raise ValueError(f"ردیف نامعتبر است: {result['error']}")
312
+ result["kind"] = row.get("kind", "نامشخص") # برچسب فارسی راهبرد در گزارش‌ها
313
+ result["margin_per_contract"] = float(row.get("margin_per_contract", 0) or 0)
314
+ return result
315
+
316
+
317
+ def signal_from_result(symbol: str, res: dict, cfg: dict) -> Signal:
318
+ kind = str(res.get("kind") or res.get("strategy") or "نامشخص")
319
+ name = f"{symbol} · {KIND_LABELS.get(kind, kind)}"
320
+ annual = res.get("annualized_pct")
321
+ sid = hashlib.sha1(f"{symbol}|{kind}|{json.dumps(res.get('detail', res), sort_keys=True, default=str)}"
322
+ .encode("utf-8")).hexdigest()[:12]
323
+ return Signal(sid=sid, symbol=symbol, kind=kind, name=name,
324
+ annualized_pct=annual if isinstance(annual, (int, float)) else None,
325
+ score_pp=float(res.get("score_pp", -999)),
326
+ go=bool(res.get("go")), detail=res,
327
+ margin_per_contract=float(res.get("margin_per_contract", 0) or 0))
328
+
329
+
330
+ def gate_checks(sig: Signal, cfg: dict, desk: Desk) -> list[str]:
331
+ """دروازه‌های ریسک بدون اندازه‌گذاری: نقدشوندگی، اسپرد، تأیید موتور، سقف موقعیت."""
332
+ d = sig.detail
333
+ reasons: list[str] = []
334
+ if not sig.go:
335
+ reasons.append("موتور ریاضی این فرصت را تأیید نکرد.")
336
+ edge = sig.score_pp
337
+ threshold = (cfg["min_edge_arbitrage_pct"] if sig.kind in ("box", "parity", "tabei")
338
+ else cfg["min_edge_leveraged_pct"])
339
+ if edge < threshold:
340
+ reasons.append(f"حاشیهٔ {edge:.2f} واحد درصد کمتر از کف {threshold:.2f} درصدی این راهبرد است.")
341
+ liq = d.get("liquidity_contracts_per_day", 999)
342
+ if isinstance(liq, (int, float)) and liq < cfg["min_liquidity_contracts_per_day"]:
343
+ reasons.append(f"حجم روزانهٔ {liq} کمتر از کف نقدشوندگی {cfg['min_liquidity_contracts_per_day']} است.")
344
+ # دروازهٔ باورپذیری: بازده غیرمنطقی یعنی داده اشتباه است، نه فرصت تاریخی
345
+ ceiling = (cfg.get("max_plausible_arb_pct", 250.0) if sig.kind in ("box", "parity", "tabei")
346
+ else cfg.get("max_plausible_lev_pct", 400.0))
347
+ if isinstance(sig.annualized_pct, (int, float)) and abs(sig.annualized_pct) > ceiling:
348
+ reasons.append(f"بازده محاسبه‌شده {sig.annualized_pct:,.0f} درصد از سقف باورپذیری ({ceiling:,.0f} درصد) "
349
+ f"بیشتر است؛ یعنی یکی از اعداد ورودی غلط یا کهنه است. اول داده را بازبینی کنید.")
350
+ spread = d.get("spread_pct", 0) or 0
351
+ if spread > cfg["max_spread_pct"]:
352
+ reasons.append(f"اسپرد {spread * 100:.2f} درصد از سقف مجاز بیشتر است.")
353
+ if not sig.alerts and edge < threshold * 2:
354
+ reasons.append("بدون پشتوانهٔ خبری و با حاشیهٔ کم؛ اولویت پایین است.")
355
+ return reasons
356
+
357
+
358
+ def size_position(sig: Signal, budget: float) -> str:
359
+ """اندازهٔ موقعیت را از بودجهٔ باقی‌مانده حساب می‌کند؛ در صورت نبود جا، پیام دلیل را می‌دهد."""
360
+ unit = sig.unit
361
+ if (sig.margin_per_contract or 0) <= 0:
362
+ sig.contracts = 0
363
+ return f"نرخ وجه تضمین هر {unit} در اسنپ‌شات مشخص نشده؛ از مشخصات قرارداد بخوانید."
364
+ n = int(budget // sig.margin_per_contract)
365
+ if n < 1:
366
+ sig.contracts = 0
367
+ return f"بودجهٔ وجه تضمین (سقف {sig.margin_per_contract:,.0f} ریال برای هر {unit}) تمام شده است."
368
+ sig.contracts = n
369
+ sig.margin_locked = n * sig.margin_per_contract
370
+ return ""
371
+
372
+
373
+ def apply_risk_gates(sig: Signal, cfg: dict, desk: Desk) -> Signal:
374
+ """نسخهٔ تک‌سیگنالی (برای آزمون و بازبینی دستی)."""
375
+ reasons = gate_checks(sig, cfg, desk)
376
+ approved_so_far = len([s for s in desk.all("approved") if s.sid != sig.sid])
377
+ if approved_so_far >= cfg["max_positions"]:
378
+ reasons.append(f"سقف {cfg['max_positions']} موقعیت تأییدشده پر است؛ اول یکی را ببندید.")
379
+ budget = cfg["capital"] * cfg["max_margin_pct"] - desk.locked_margin(exclude_sid=sig.sid)
380
+ budget = max(budget, 0.0)
381
+ note = size_position(sig, budget)
382
+ if reasons or note:
383
+ sig.status = "rejected"
384
+ sig.gate_note = " | ".join(reasons + ([note] if note else []))
385
+ else:
386
+ sig.status = "pending"
387
+ sig.gate_note = (f"حاشیهٔ {sig.score_pp:.2f} واحد درصد · {sig.contracts:,} {sig.unit} · "
388
+ f"سرمایهٔ درگیر {sig.margin_locked:,.0f} ریال")
389
+ return sig
390
+
391
+
392
+ def scan_market(market_path: Path | str, cfg: dict, desk: Desk,
393
+ kodal_db: Path | str | None = None) -> list[Signal]:
394
+ """محاسبهٔ همهٔ ردیف‌ها، سپس تخصیص بودجهٔ وجه تضمین به‌ترتیب امتیاز."""
395
+ data = json.loads(Path(market_path).read_text(encoding="utf-8"))
396
+ hurdle = float(data.get("hurdle", cfg["hurdle"]))
397
+ if data.get("capital"):
398
+ cfg["capital"] = float(data["capital"])
399
+ alerts = read_alerts(kodal_db, cfg["alert_score_threshold"]) if kodal_db else []
400
+ candidates: list[Signal] = []
401
+ for row in data.get("rows", []):
402
+ symbol = str(row.get("symbol", "?"))
403
+ try:
404
+ res = math_for_row(row, hurdle)
405
+ except Exception as e: # ورودی ناقص یا فرمول نامعتبر
406
+ log(f"ردیف {symbol} محاسبه نشد: {type(e).__name__}: {e}")
407
+ continue
408
+ res.setdefault("unit", row.get("unit") or ("سهم" if row.get("kind") in
409
+ ("tabei", "covered_call", "parity") else "قرارداد"))
410
+ sig = signal_from_result(symbol, res, cfg)
411
+ sig.alerts = related_alerts(symbol, alerts)
412
+ sig.gate_note = " | ".join(gate_checks(sig, cfg, desk))
413
+ candidates.append(sig)
414
+
415
+ candidates.sort(key=lambda s: s.score_pp, reverse=True)
416
+ budget_total = max(cfg["capital"] * cfg["max_margin_pct"] - desk.locked_margin(), 0.0)
417
+ policy = {"capital": cfg["capital"], "max_margin_pct": cfg["max_margin_pct"],
418
+ "cap_total": cfg["capital"] * cfg["max_margin_pct"],
419
+ "max_positions": cfg["max_positions"], "hurdle": hurdle}
420
+ for sig in candidates:
421
+ sig.detail["_policy"] = policy
422
+ budget = budget_total
423
+ per_position = budget_total * float(cfg.get("max_position_pct", 1.0))
424
+ for sig in candidates:
425
+ existing = desk.get(sig.sid)
426
+ if existing and desk.human_decided(sig.sid):
427
+ # تصمیم انسان بازنویسی نمی‌شود: اندازه و یادداشت همان می‌ماند
428
+ sig.status, sig.contracts = existing.status, existing.contracts
429
+ sig.margin_locked, sig.gate_note = existing.margin_locked, existing.gate_note
430
+ desk.upsert(sig)
431
+ continue
432
+ if sig.gate_note:
433
+ sig.status = "rejected"
434
+ else:
435
+ note = size_position(sig, max(min(budget, per_position), 0.0))
436
+ if note:
437
+ sig.status = "rejected"
438
+ sig.gate_note = note
439
+ else:
440
+ budget -= sig.margin_locked
441
+ sig.status = "pending"
442
+ sig.gate_note = (f"حاشیهٔ {sig.score_pp:.2f} واحد درصد · {sig.contracts:,} {sig.unit} · "
443
+ f"سرمایهٔ درگیر {sig.margin_locked:,.0f} ریال")
444
+ desk.upsert(sig)
445
+ return candidates
446
+
447
+
448
+ def recheck_tasks(cfg: dict, desk: Desk, kodal_db: Path | str, market_path: Path | str) -> list[dict]:
449
+ """نمادهایی که خبر مهم داشته‌اند ولی در اسنپ‌شات بازار ردیفی ندارند."""
450
+ data = json.loads(Path(market_path).read_text(encoding="utf-8"))
451
+ covered = {str(r.get("symbol", "")) for r in data.get("rows", [])}
452
+ out = []
453
+ for a in read_alerts(kodal_db, cfg["alert_score_threshold"]):
454
+ sym = (a.get("symbol") or "").strip()
455
+ if sym and sym in covered:
456
+ continue
457
+ if sym:
458
+ out.append({"symbol": sym, "reason": "خبر مهم، ولی دادهٔ آپشن/آتی این نماد در اسنپ‌شات نیست",
459
+ "alert": a})
460
+ return out
461
+
462
+
463
+ # ---------------------------------------------------------------- بستهٔ سفارش
464
+ def order_packet(sig: Signal) -> str:
465
+ d = sig.detail
466
+ lines = [
467
+ "بستهٔ سفارش (اجرا فقط توسط انسان در سامانهٔ کارگزاری)",
468
+ "=" * 62,
469
+ f"نماد: {sig.symbol} راهبرد: {KIND_LABELS.get(sig.kind, sig.kind)}",
470
+ f"شمارهٔ سیگنال: {sig.sid}",
471
+ f"بازده سالانهٔ خالص برآوردی: {sig.annualized_pct if sig.annualized_pct is not None else '—'} درصد",
472
+ f"امتیاز نسبت به نرخ سد: {sig.score_pp} واحد درصد",
473
+ f"تعداد پیشنهادی: {sig.contracts:,} {sig.unit}",
474
+ f"سرمایهٔ درگیر (وجه تضمین یا بهای خرید): {sig.margin_locked:,.0f} ریال",
475
+ "",
476
+ "جزئیات ریاضی:",
477
+ ]
478
+ for k, v in d.items():
479
+ if k in ("name", "strategy", "kind", "liquidity_contracts_per_day", "spread_pct", "leverage_used"):
480
+ continue
481
+ lines.append(f" · {k}: {v}")
482
+ if sig.alerts:
483
+ lines.append("")
484
+ lines.append("خبرهای مرتبط (فقط برای زمینه؛ خبر به‌تنهایی سیگنال نیست):")
485
+ for a in sig.alerts:
486
+ lines.append(f" · [{a.get('score')}] {a.get('title')}")
487
+ lines += [
488
+ "",
489
+ "یادآوری‌های اجرایی:",
490
+ " ۱. پیش از ثبت، قیمت لحظه‌ای و عمق بازار را دوباره ببینید؛ اعداد اسنپ‌شات، تاریخی‌اند.",
491
+ " ۲. پاهای آربیتراژ را در یک پنجرهٔ زمانی کوتاه و هم‌زمان اجرا کنید، وگرنه ریسک اجرا می‌گیرید.",
492
+ " ۳. این بسته «پیشنهاد» است؛ تصمیم و مسئولیت با شماست. سود تضمینی وجود ندارد.",
493
+ ]
494
+ return "\n".join(lines)
495
+
496
+
497
+ # ---------------------------------------------------------------- داشبورد HTML
498
+ def build_dashboard(desk: Desk, cfg: dict, path: Path | str = DEFAULT_REPORT,
499
+ tasks: list[dict] | None = None) -> Path:
500
+ path = Path(path)
501
+ path.parent.mkdir(parents=True, exist_ok=True)
502
+ all_sigs = desk.all(limit=500)
503
+ pending = [s for s in all_sigs if s.status == "pending"]
504
+ approved = [s for s in all_sigs if s.status == "approved"]
505
+ rejected = [s for s in all_sigs if s.status == "rejected"]
506
+
507
+ def rows(items: list[Signal], show_gate: bool = True) -> str:
508
+ out = []
509
+ for s in items:
510
+ color = "#0a7d33" if s.score_pp > 10 else ("#8a6d00" if s.score_pp > 0 else "#b3261e")
511
+ news = "<br>".join(html.escape(a.get("title", "")[:110]) for a in s.alerts[:3]) or "—"
512
+ out.append(f"""<tr>
513
+ <td class="id">{html.escape(s.sid)}</td>
514
+ <td>{html.escape(s.symbol)}</td>
515
+ <td>{html.escape(KIND_LABELS.get(s.kind, s.kind))}</td>
516
+ <td class="num">{'' if s.annualized_pct is None else f'{s.annualized_pct:.2f}'}</td>
517
+ <td class="num" style="color:{color}">{s.score_pp:.2f}</td>
518
+ <td class="num">{s.contracts:,} {html.escape(s.unit)}</td>
519
+ <td class="num">{s.margin_locked:,.0f}</td>
520
+ <td class="status">{html.escape(s.status)}</td>
521
+ <td class="note">{html.escape(s.gate_note)}{f'<div class="news">{news}</div>' if news != '—' else ''}</td>
522
+ </tr>""")
523
+ return "".join(out) or '<tr><td colspan="9">موردی نیست.</td></tr>'
524
+
525
+ tasks_html = "".join(
526
+ f"<li><b>{html.escape(t['symbol'])}</b> — {html.escape(t['reason'])} "
527
+ f"<span class='news'>{html.escape(str(t['alert'].get('title', ''))[:120])}</span></li>"
528
+ for t in (tasks or [])) or "<li>موردی نیست.</li>"
529
+
530
+ doc = f"""<!DOCTYPE html>
531
+ <html lang="fa" dir="rtl"><head><meta charset="utf-8">
532
+ <title>{html.escape(cfg['report_title'])} — {fa_time()}</title>
533
+ <style>
534
+ body {{ font-family: Tahoma, "Segoe UI", "Vazirmatn", sans-serif; margin: 0; background: #f6f7f9; color: #1d1d1f; }}
535
+ header {{ background: #0b3d2e; color: #fff; padding: 18px 22px; }}
536
+ header h1 {{ margin: 0 0 6px; font-size: 20px; }}
537
+ header .meta {{ font-size: 12px; opacity: .85; }}
538
+ .cards {{ display: flex; gap: 12px; flex-wrap: wrap; padding: 16px 22px 0; }}
539
+ .card {{ background: #fff; border: 1px solid #e3e6ea; border-radius: 10px; padding: 12px 14px; min-width: 170px; }}
540
+ .card .k {{ font-size: 12px; color: #6b7280; }}
541
+ .card .v {{ font-size: 18px; font-weight: bold; margin-top: 4px; }}
542
+ main {{ padding: 14px 22px 40px; }}
543
+ h2 {{ font-size: 16px; margin: 22px 0 8px; }}
544
+ table {{ width: 100%; border-collapse: collapse; background: #fff; font-size: 12.5px; }}
545
+ th, td {{ border-bottom: 1px solid #e6e8ec; padding: 7px 9px; text-align: right; vertical-align: top; }}
546
+ th {{ background: #eef2f7; font-size: 12px; }}
547
+ .num {{ font-variant-numeric: tabular-nums; }}
548
+ .id {{ font-family: Consolas, monospace; font-size: 11.5px; color: #0b5394; }}
549
+ .note {{ color: #444; max-width: 330px; }}
550
+ .news {{ color: #0b5394; font-size: 11.5px; margin-top: 4px; }}
551
+ .status {{ font-weight: bold; }}
552
+ .warn {{ background: #fff8e1; border: 1px solid #f0e0a8; border-radius: 8px; padding: 10px 12px; font-size: 12.5px; margin: 10px 0 0; }}
553
+ ul {{ margin: 6px 0 0; padding-right: 20px; font-size: 12.5px; }}
554
+ footer {{ margin-top: 22px; font-size: 11.5px; color: #6b7280; line-height: 1.9; }}
555
+ </style></head>
556
+ <body>
557
+ <header>
558
+ <h1>{html.escape(cfg['report_title'])}</h1>
559
+ <div class="meta">زمان: {fa_time()} · نسخهٔ {VERSION} · نرخ سد: {cfg['hurdle'] * 100:.1f} درصد</div>
560
+ </header>
561
+ <div class="cards">
562
+ <div class="card"><div class="k">سرمایه</div><div class="v">{cfg['capital']:,.0f}</div></div>
563
+ <div class="card"><div class="k">سیگنال منتظر تأیید</div><div class="v">{len(pending)}</div></div>
564
+ <div class="card"><div class="k">تأییدشده</div><div class="v">{len(approved)}</div></div>
565
+ <div class="card"><div class="k">وجه تضمین قفل‌شده</div><div class="v">{desk.locked_margin():,.0f}</div></div>
566
+ <div class="card"><div class="k">رد شده</div><div class="v">{len(rejected)}</div></div>
567
+ </div>
568
+ <main>
569
+ <div class="warn">این داشبورد «دستیار تصمیم» است. هیچ سفارشی خودکار ارسال نمی‌شود؛
570
+ معاملات الگوریتمی خودکار در بورس و فرابورس ایران مجاز نیست. تصمیم نهایی و مسئولیت آن با انسان است و هیچ سود تضمینی وجود ندارد.</div>
571
+
572
+ <h2>سیگنال‌های منتظر تأیید</h2>
573
+ <table><thead><tr><th>شناسه</th><th>نماد</th><th>راهبرد</th><th>بازده سالانهٔ خالص (٪)</th>
574
+ <th>حاشیه (واحد ٪)</th><th>تعداد</th><th>وجه تضمین</th><th>وضعیت</th><th>یادداشت دروازه / خبر مرتبط</th></tr></thead>
575
+ <tbody>{rows(pending)}</tbody></table>
576
+
577
+ <h2>تأییدشده (آمادهٔ اجرای انسانی)</h2>
578
+ <table><thead><tr><th>شناسه</th><th>نماد</th><th>راهبرد</th><th>بازده سالانهٔ خالص (٪)</th>
579
+ <th>حاشیه (واحد ٪)</th><th>تعداد</th><th>وجه تضمین</th><th>وضعیت</th><th>یادداشت دروازه / خبر مرتبط</th></tr></thead>
580
+ <tbody>{rows(approved)}</tbody></table>
581
+
582
+ <h2>رد‌شده‌ها و دلیل</h2>
583
+ <table><thead><tr><th>شناسه</th><th>نماد</th><th>راهبرد</th><th>بازده سالانهٔ خالص (٪)</th>
584
+ <th>حاشیه (واحد ٪)</th><th>تعداد</th><th>وجه تضمین</th><th>وضعیت</th><th>یادداشت دروازه / خبر مرتبط</th></tr></thead>
585
+ <tbody>{rows(rejected)}</tbody></table>
586
+
587
+ <h2>کارهای بازبینی (خبر مهم بدون دادهٔ بازار)</h2>
588
+ <ul>{tasks_html}</ul>
589
+
590
+ <h2>دستورهای تأیید و اجرا</h2>
591
+ <ul>
592
+ <li><code>python desk.py list --status pending</code> فهرست سیگنال‌ها</li>
593
+ <li><code>python desk.py approve &lt;شناسه&gt; --note "ریسک پذیرفته شد"</code> تأیید انسانی</li>
594
+ <li><code>python desk.py reject &lt;شناسه&gt; --note "نقدشوندگی کم"</code> رد با دلیل</li>
595
+ <li><code>python desk.py packet &lt;شناسه&gt;</code> چاپ بستهٔ سفارش برای اجرا در سامانهٔ کارگزاری</li>
596
+ </ul>
597
+
598
+ <footer>ساختهٔ میز معاملات نسخهٔ {VERSION} · {html.escape(cfg['credit'])}</footer>
599
+ </main></body></html>"""
600
+ path.write_text(doc, encoding="utf-8")
601
+ return path
602
+
603
+
604
+ # ---------------------------------------------------------------- دستورها
605
+ def cmd_scan(args) -> int:
606
+ cfg = load_config(args.config)
607
+ desk = Desk(cfg.get("desk_db") or DEFAULT_DB)
608
+ sigs = scan_market(args.market, cfg, desk, args.kodal_db)
609
+ for s in sigs[:20]:
610
+ mark = "✅" if s.status == "pending" else ("🟢" if s.status == "approved" else "✖")
611
+ ann = f"{s.annualized_pct:.2f}٪" if isinstance(s.annualized_pct, (int, float)) else "—"
612
+ 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}")
613
+ if s.status == "rejected":
614
+ print(f" دلیل: {s.gate_note}")
615
+ log(f"{len(sigs)} سیگنال محاسبه شد؛ {len([s for s in sigs if s.status == 'pending'])} منتظر تأیید.")
616
+ return 0
617
+
618
+
619
+ def cmd_run(args) -> int:
620
+ cfg = load_config(args.config)
621
+ desk = Desk(cfg.get("desk_db") or DEFAULT_DB)
622
+ sigs = scan_market(args.market, cfg, desk, args.kodal_db)
623
+ tasks = recheck_tasks(cfg, desk, args.kodal_db, args.market) if args.kodal_db else []
624
+ path = build_dashboard(desk, cfg, cfg.get("report_path") or DEFAULT_REPORT, tasks)
625
+ log(f"{len(sigs)} سیگنال · {len(tasks)} کار بازبینی · داشبورد: {path}")
626
+ for s in sigs:
627
+ if s.status == "pending":
628
+ print(f" → منتظر تأیید: [{s.sid}] {s.name} با حاشیهٔ {s.score_pp:.2f} واحد درصد")
629
+ return 0
630
+
631
+
632
+ def cmd_list(args) -> int:
633
+ cfg = load_config(args.config)
634
+ desk = Desk(cfg.get("desk_db") or DEFAULT_DB)
635
+ items = desk.all(args.status, args.limit)
636
+ if not items:
637
+ print("موردی نیست.")
638
+ return 0
639
+ for s in items:
640
+ ann = f"{s.annualized_pct:.2f}٪" if isinstance(s.annualized_pct, (int, float)) else "—"
641
+ print(f"[{s.sid}] {s.status:<9} {s.symbol:<8} {KIND_LABELS.get(s.kind, s.kind):<16} "
642
+ f"بازده {ann:<9} حاشیه {s.score_pp:>7.2f} {s.contracts:,} {s.unit}")
643
+ if s.gate_note:
644
+ print(f" {s.gate_note}")
645
+ return 0
646
+
647
+
648
+ def cmd_decide(args, action: str) -> int:
649
+ cfg = load_config(args.config)
650
+ desk = Desk(cfg.get("desk_db") or DEFAULT_DB)
651
+ sig = desk.get(args.sid)
652
+ if not sig:
653
+ print("شناسه پیدا نشد.")
654
+ return 2
655
+ if action == "approved":
656
+ policy = sig.detail.get("_policy") or {}
657
+ cap = float(policy.get("cap_total") or cfg["capital"] * cfg["max_margin_pct"])
658
+ max_positions = int(policy.get("max_positions") or cfg["max_positions"])
659
+ used = desk.locked_margin(exclude_sid=sig.sid) + sig.margin_locked
660
+ count = len([s for s in desk.all("approved") if s.sid != sig.sid])
661
+ if used > cap or count >= max_positions:
662
+ print(f"توقف: تأیید این سیگنال سقف ریسک را رد می‌کند "
663
+ f"(سرمایهٔ درگیر {used:,.0f} از سقف {cap:,.0f} ریال · موقعیت‌های تأییدشده {count} از {max_positions}).")
664
+ if not getattr(args, "force", False):
665
+ print("اگر آگاهانه می‌خواهید رد کنید، دستور را با --force تکرار کنید.")
666
+ return 3
667
+ print("با --force رد شد؛ این تصمیم در دفتر ثبت می‌شود.")
668
+ desk.decide(args.sid, action, args.note or "")
669
+ print(f"{'تأیید' if action == 'approved' else 'رد'} شد: {args.sid}")
670
+ if action == "approved":
671
+ sig = desk.get(args.sid)
672
+ assert sig is not None
673
+ print()
674
+ print(order_packet(sig))
675
+ return 0
676
+
677
+
678
+ def cmd_packet(args) -> int:
679
+ cfg = load_config(args.config)
680
+ desk = Desk(cfg.get("desk_db") or DEFAULT_DB)
681
+ sig = desk.get(args.sid)
682
+ if not sig:
683
+ print("شناسه پیدا نشد.")
684
+ return 2
685
+ if sig.status != "approved":
686
+ print(f"هشدار: وضعیت این سیگنال «{sig.status}» است، نه تأییدشده. "
687
+ f"برای اجرا اول با دستور approve تأیید کنید.")
688
+ print(order_packet(sig))
689
+ return 0
690
+
691
+
692
+ def cmd_stats(args) -> int:
693
+ cfg = load_config(args.config)
694
+ desk = Desk(cfg.get("desk_db") or DEFAULT_DB)
695
+ rows = desk.conn.execute(
696
+ "SELECT status, COUNT(*), COALESCE(SUM(margin_locked),0) FROM signals GROUP BY status").fetchall()
697
+ print(f"{'وضعیت':<12}{'تعداد':>8}{'وجه تضمین قفل‌شده':>22}")
698
+ for st, n, locked in rows:
699
+ print(f"{st:<12}{n:>8}{locked:>22,.0f}")
700
+ print(f"\nتصمیم‌های ثبت‌شده: {len(desk.decisions(1000))}")
701
+ return 0
702
+
703
+
704
+ def cmd_selftest(args) -> int:
705
+ checks = 0
706
+ scout = load_scout()
707
+ assert hasattr(scout, "box_spread") and hasattr(scout, "tabei_min_yield")
708
+ checks += 1
709
+ cfg = json.loads(json.dumps(DEFAULT_CONFIG))
710
+ desk = Desk(BASE / "data" / "_selftest.sqlite3")
711
+ desk.conn.execute("DELETE FROM signals")
712
+ desk.conn.commit()
713
+ market = BASE / "market-demo.json"
714
+ if market.exists():
715
+ sigs = scan_market(market, cfg, desk)
716
+ assert sigs, "اسنپ‌شات نمونه سیگنالی تولید نکرد"
717
+ checks += 1
718
+ assert any(s.status == "pending" for s in sigs) or all(s.gate_note for s in sigs)
719
+ checks += 1
720
+ assert g2j(2026, 9, 22) == (1405, 6, 31)
721
+ checks += 1
722
+ print(f"خودآزمون: {checks} بررسی موفق")
723
+ return 0
724
+
725
+
726
+ def main(argv: list[str] | None = None) -> int:
727
+ ap = argparse.ArgumentParser(description="میز معاملات — دستیار تصمیم با تأیید انسان (بدون ارسال سفارش)")
728
+ ap.add_argument("--config", help="مسیر config.json")
729
+ sub = ap.add_subparsers(dest="cmd")
730
+
731
+ p_scan = sub.add_parser("scan", help="محاسبهٔ ریاضی روی اسنپ‌شات بازار")
732
+ p_scan.add_argument("--market", required=True)
733
+ p_scan.add_argument("--kodal-db", help="پایگاه‌دادهٔ دیده‌بان کدال")
734
+ p_scan.set_defaults(func=cmd_scan)
735
+
736
+ p_run = sub.add_parser("run", help="محاسبه + چسباندن خبرها + داشبورد")
737
+ p_run.add_argument("--market", required=True)
738
+ p_run.add_argument("--kodal-db")
739
+ p_run.set_defaults(func=cmd_run)
740
+
741
+ p_list = sub.add_parser("list", help="فهرست سیگنال‌ها")
742
+ p_list.add_argument("--status", choices=["pending", "approved", "rejected"])
743
+ p_list.add_argument("--limit", type=int, default=50)
744
+ p_list.set_defaults(func=cmd_list)
745
+
746
+ p_app = sub.add_parser("approve", help="تأیید انسانی سیگنال")
747
+ p_app.add_argument("sid")
748
+ p_app.add_argument("--note", default="")
749
+ p_app.add_argument("--force", action="store_true", help="رد کردن آگاهانهٔ سقف ریسک")
750
+ p_app.set_defaults(func=lambda a: cmd_decide(a, "approved"))
751
+
752
+ p_rej = sub.add_parser("reject", help="رد سیگنال با دلیل")
753
+ p_rej.add_argument("sid")
754
+ p_rej.add_argument("--note", default="")
755
+ p_rej.set_defaults(func=lambda a: cmd_decide(a, "rejected"))
756
+
757
+ p_list.set_defaults(func=cmd_list) # نگهبان
758
+
759
+ p_pack = sub.add_parser("packet", help="چاپ بستهٔ سفارش")
760
+ p_pack.add_argument("sid")
761
+ p_pack.set_defaults(func=cmd_packet)
762
+
763
+ sub.add_parser("stats", help="آمار وضعیت‌ها").set_defaults(func=cmd_stats)
764
+ sub.add_parser("selftest", help="آزمون سریع").set_defaults(func=cmd_selftest)
765
+ sub.add_parser("version", help="نسخه").set_defaults(func=lambda a: (print(f"desk {VERSION}"), 0)[1])
766
+
767
+ args = ap.parse_args(argv)
768
+ if not getattr(args, "cmd", None):
769
+ ap.print_help()
770
+ return 0
771
+ return int(args.func(args) or 0)
772
+
773
+
774
+ if __name__ == "__main__":
775
+ sys.exit(main())
desk/market-demo.json ADDED
@@ -0,0 +1,36 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "as_of": "2026-09-22",
3
+ "hurdle": 0.39,
4
+ "capital": 20000000000,
5
+ "note": "اعداد این اسنپ‌شات نمونه و ساختگی‌اند و قیمت واقعی بازار نیستند؛ فقط برای نمایش کارکرد میز معاملات ساخته شده‌اند. وجه تضمین‌ها به ریال است.",
6
+ "rows": [
7
+ {"symbol": "اهرم", "kind": "basis", "spot": 20000, "future": 22800, "days": 90, "storage_annual": 0.0,
8
+ "margin_per_contract": 20000000, "unit": "قرارداد",
9
+ "liquidity_contracts_per_day": 900, "spread_pct": 0.005, "leverage_used": 1},
10
+
11
+ {"symbol": "فولاد", "kind": "covered_call", "spot": 7000, "strike": 7600, "premium": 400, "days": 45,
12
+ "margin_per_contract": 7000, "unit": "سهم",
13
+ "liquidity_contracts_per_day": 160, "spread_pct": 0.018},
14
+
15
+ {"symbol": "کگل", "kind": "tabei", "stock_price": 9800, "put_price": 40, "strike": 14210, "days": 365,
16
+ "margin_per_contract": 9840, "unit": "سهم",
17
+ "liquidity_contracts_per_day": 240, "spread_pct": 0.02},
18
+
19
+ {"symbol": "خساپا", "kind": "tabei", "stock_price": 2500, "put_price": 12, "strike": 3000, "days": 270,
20
+ "margin_per_contract": 2512, "unit": "سهم",
21
+ "liquidity_contracts_per_day": 320, "spread_pct": 0.012},
22
+
23
+ {"symbol": "طلا", "kind": "basis", "spot": 20000, "future": 20600, "days": 60, "storage_annual": 0.01,
24
+ "margin_per_contract": 20000000, "unit": "قرارداد",
25
+ "liquidity_contracts_per_day": 700, "spread_pct": 0.006},
26
+
27
+ {"symbol": "شپنا", "kind": "box", "call_low": 300, "put_low": 430, "call_high": 175, "put_high": 585,
28
+ "strike_low": 1200, "strike_high": 1500, "days": 45,
29
+ "margin_per_contract": 250000, "unit": "قرارداد",
30
+ "liquidity_contracts_per_day": 12, "spread_pct": 0.045},
31
+
32
+ {"symbol": "وبملت", "kind": "parity", "call": 420, "put": 380, "spot": 9000, "strike": 9000, "days": 30, "rate": 0.39,
33
+ "margin_per_contract": 9000, "unit": "سهم",
34
+ "liquidity_contracts_per_day": 80, "spread_pct": 0.02}
35
+ ]
36
+ }
desk/run-demo.bat ADDED
@@ -0,0 +1,5 @@
 
 
 
 
 
 
1
+ @echo off
2
+ chcp 65001 >nul
3
+ cd /d "%~dp0"
4
+ python desk.py run --market market-demo.json --kodal-db ..\kodal-alert\data\demo.sqlite3
5
+ start "" "data\dashboard.html"
desk/tests/test_desk.py ADDED
@@ -0,0 +1,304 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env python3
2
+ # -*- coding: utf-8 -*-
3
+ """آزمون‌های واحد میز معاملات — فقط کتابخانهٔ استاندارد."""
4
+ from __future__ import annotations
5
+
6
+ import json
7
+ import sqlite3
8
+ import sys
9
+ import tempfile
10
+ import unittest
11
+ from pathlib import Path
12
+
13
+ sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
14
+
15
+ BASE_MARKET = Path(__file__).resolve().parents[1] / "market-demo.json"
16
+
17
+ import desk as dk # noqa: E402
18
+
19
+
20
+ def temp_cfg(tmp: str, **over) -> dict:
21
+ cfg = json.loads(json.dumps(dk.DEFAULT_CONFIG, ensure_ascii=False))
22
+ cfg["desk_db"] = str(Path(tmp) / "desk.sqlite3")
23
+ cfg["report_path"] = str(Path(tmp) / "dash.html")
24
+ cfg.update(over)
25
+ return cfg
26
+
27
+
28
+ def make_kodal_db(tmp: str, rows: list[tuple]) -> Path:
29
+ p = Path(tmp) / "kodal.sqlite3"
30
+ conn = sqlite3.connect(str(p))
31
+ conn.execute("CREATE TABLE items (id TEXT PRIMARY KEY, title TEXT, source TEXT, symbol TEXT, company TEXT,"
32
+ " body TEXT, url TEXT, published_at TEXT, category TEXT, direction TEXT, score INTEGER,"
33
+ " reason TEXT, ai_note TEXT, provider TEXT, created_at TEXT)")
34
+ for i, (title, symbol, score) in enumerate(rows):
35
+ conn.execute("INSERT INTO items VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
36
+ (f"k{i}", title, "کدال", symbol, "", "", "https://codal.ir/x", "", "افزایش سرمایه",
37
+ "مثبت", score, "", "", "شاهد محلی", ""))
38
+ conn.commit()
39
+ conn.close()
40
+ return p
41
+
42
+
43
+ class TestScoutBridge(unittest.TestCase):
44
+ def test_scout_loads(self):
45
+ scout = dk.load_scout()
46
+ self.assertTrue(hasattr(scout, "box_spread"))
47
+
48
+ def test_math_for_tabei_row(self):
49
+ res = dk.math_for_row({"symbol": "خ", "kind": "tabei", "stock_price": 2500, "put_price": 12,
50
+ "strike": 3125, "days": 90}, 0.39)
51
+ self.assertTrue(res["go"])
52
+ self.assertGreater(res["annualized_pct"], 39.0)
53
+
54
+ def test_math_for_bad_row_reports(self):
55
+ with self.assertRaises(ValueError):
56
+ dk.math_for_row({"symbol": "خ", "kind": "box", "call_low": 1}, 0.39)
57
+
58
+ def test_math_unknown_kind_reports(self):
59
+ with self.assertRaises(ValueError):
60
+ dk.math_for_row({"symbol": "خ", "kind": "nope"}, 0.39)
61
+
62
+
63
+ class TestScan(unittest.TestCase):
64
+ def test_scan_demo_market(self):
65
+ with tempfile.TemporaryDirectory() as tmp:
66
+ cfg = temp_cfg(tmp)
67
+ desk = dk.Desk(cfg["desk_db"])
68
+ sigs = dk.scan_market(Path(dk.BASE) / "market-demo.json", cfg, desk)
69
+ self.assertGreaterEqual(len(sigs), 6)
70
+ scores = [s.score_pp for s in sigs]
71
+ self.assertEqual(scores, sorted(scores, reverse=True))
72
+ self.assertTrue(any(s.status == "pending" for s in sigs))
73
+ self.assertTrue(any(s.status == "rejected" for s in sigs))
74
+
75
+ def test_illiquid_row_is_rejected(self):
76
+ with tempfile.TemporaryDirectory() as tmp:
77
+ cfg = temp_cfg(tmp)
78
+ desk = dk.Desk(cfg["desk_db"])
79
+ sig = dk.Signal(sid="x1", symbol="شپنا", kind="box", name="n", annualized_pct=200.0,
80
+ score_pp=100.0, go=True,
81
+ detail={"liquidity_contracts_per_day": 3, "spread_pct": 0.01},
82
+ margin_per_contract=1000)
83
+ sig = dk.apply_risk_gates(sig, cfg, desk)
84
+ self.assertEqual(sig.status, "rejected")
85
+ self.assertIn("نقدشوندگی", sig.gate_note)
86
+
87
+ def test_wide_spread_is_rejected(self):
88
+ with tempfile.TemporaryDirectory() as tmp:
89
+ cfg = temp_cfg(tmp)
90
+ desk = dk.Desk(cfg["desk_db"])
91
+ sig = dk.Signal(sid="x2", symbol="الف", kind="box", name="n", annualized_pct=200.0,
92
+ score_pp=100.0, go=True,
93
+ detail={"liquidity_contracts_per_day": 200, "spread_pct": 0.09},
94
+ margin_per_contract=1000)
95
+ sig = dk.apply_risk_gates(sig, cfg, desk)
96
+ self.assertEqual(sig.status, "rejected")
97
+ self.assertIn("اسپرد", sig.gate_note)
98
+
99
+ def test_big_margin_blocks_position(self):
100
+ with tempfile.TemporaryDirectory() as tmp:
101
+ cfg = temp_cfg(tmp)
102
+ desk = dk.Desk(cfg["desk_db"])
103
+ sig = dk.Signal(sid="x3", symbol="ب", kind="basis", name="n", annualized_pct=120.0,
104
+ score_pp=60.0, go=True,
105
+ detail={"liquidity_contracts_per_day": 200, "spread_pct": 0.01},
106
+ margin_per_contract=cfg["capital"]) # بیشتر از سقف ۲۰ درصد
107
+ sig = dk.apply_risk_gates(sig, cfg, desk)
108
+ self.assertEqual(sig.contracts, 0)
109
+ self.assertEqual(sig.status, "rejected")
110
+
111
+ def test_margin_math_respects_cap(self):
112
+ with tempfile.TemporaryDirectory() as tmp:
113
+ cfg = temp_cfg(tmp)
114
+ desk = dk.Desk(cfg["desk_db"])
115
+ sig = dk.Signal(sid="x4", symbol="ج", kind="basis", name="n", annualized_pct=120.0,
116
+ score_pp=60.0, go=True,
117
+ detail={"liquidity_contracts_per_day": 200, "spread_pct": 0.01},
118
+ margin_per_contract=100_000_000)
119
+ sig = dk.apply_risk_gates(sig, cfg, desk)
120
+ self.assertEqual(sig.contracts, 10) # ۵ میلیارد × ۲۰٪ ÷ ۱۰۰ میلیون
121
+ self.assertLessEqual(sig.margin_locked, cfg["capital"] * cfg["max_margin_pct"])
122
+
123
+ def test_status_preserved_on_rescan(self):
124
+ with tempfile.TemporaryDirectory() as tmp:
125
+ cfg = temp_cfg(tmp)
126
+ desk = dk.Desk(cfg["desk_db"])
127
+ market = Path(dk.BASE) / "market-demo.json"
128
+ sigs = dk.scan_market(market, cfg, desk)
129
+ target = next(s for s in sigs if s.status == "pending")
130
+ desk.decide(target.sid, "approved", "تست")
131
+ dk.scan_market(market, cfg, desk)
132
+ self.assertEqual(desk.get(target.sid).status, "approved")
133
+
134
+
135
+ class TestAlertsBridge(unittest.TestCase):
136
+ def test_read_and_match_alerts(self):
137
+ with tempfile.TemporaryDirectory() as tmp:
138
+ p = make_kodal_db(tmp, [("افزایش سرمایه ۴۵۰ درصدی", "خساپا", 96),
139
+ ("توقف نماد", "وبملت", 86)])
140
+ alerts = dk.read_alerts(p, 60)
141
+ self.assertEqual(len(alerts), 2)
142
+ matched = dk.related_alerts("خساپا", alerts)
143
+ self.assertEqual(len(matched), 1)
144
+ self.assertIn("افزایش سرمایه", matched[0]["title"])
145
+
146
+ def test_missing_db_is_safe(self):
147
+ self.assertEqual(dk.read_alerts("/no/such.sqlite3", 60), [])
148
+
149
+ def test_recheck_tasks_for_uncovered_symbol(self):
150
+ with tempfile.TemporaryDirectory() as tmp:
151
+ cfg = temp_cfg(tmp)
152
+ desk = dk.Desk(cfg["desk_db"])
153
+ p = make_kodal_db(tmp, [("افزایش سرمایه", "شپدیس", 92)])
154
+ tasks = dk.recheck_tasks(cfg, desk, p, Path(dk.BASE) / "market-demo.json")
155
+ self.assertEqual(len(tasks), 1)
156
+ self.assertEqual(tasks[0]["symbol"], "شپدیس")
157
+
158
+ def test_covered_symbol_not_in_tasks(self):
159
+ with tempfile.TemporaryDirectory() as tmp:
160
+ cfg = temp_cfg(tmp)
161
+ desk = dk.Desk(cfg["desk_db"])
162
+ p = make_kodal_db(tmp, [("خبر مهم", "خساپا", 92)])
163
+ self.assertEqual(dk.recheck_tasks(cfg, desk, p, Path(dk.BASE) / "market-demo.json"), [])
164
+
165
+
166
+ class TestWorkflow(unittest.TestCase):
167
+ def test_approve_records_decision_and_packet(self):
168
+ with tempfile.TemporaryDirectory() as tmp:
169
+ cfg = temp_cfg(tmp)
170
+ desk = dk.Desk(cfg["desk_db"])
171
+ sigs = dk.scan_market(Path(dk.BASE) / "market-demo.json", cfg, desk)
172
+ target = next(s for s in sigs if s.status == "pending")
173
+ self.assertTrue(desk.decide(target.sid, "approved", "ریسک پذیرفته شد"))
174
+ self.assertEqual(desk.get(target.sid).status, "approved")
175
+ self.assertEqual(len(desk.decisions(10)), 1)
176
+ packet = dk.order_packet(desk.get(target.sid))
177
+ self.assertIn(target.symbol, packet)
178
+ self.assertIn("انسان", packet)
179
+ self.assertIn("سود تضمینی وجود ندارد", packet)
180
+
181
+ def test_reject_unknown_id_returns_false(self):
182
+ with tempfile.TemporaryDirectory() as tmp:
183
+ cfg = temp_cfg(tmp)
184
+ desk = dk.Desk(cfg["desk_db"])
185
+ self.assertFalse(desk.decide("nope", "approved", ""))
186
+
187
+ def test_locked_margin_tracks_approvals(self):
188
+ with tempfile.TemporaryDirectory() as tmp:
189
+ cfg = temp_cfg(tmp)
190
+ desk = dk.Desk(cfg["desk_db"])
191
+ sigs = dk.scan_market(Path(dk.BASE) / "market-demo.json", cfg, desk)
192
+ target = next(s for s in sigs if s.status == "pending")
193
+ before = desk.locked_margin()
194
+ desk.decide(target.sid, "approved", "")
195
+ self.assertGreater(desk.locked_margin(), before)
196
+
197
+
198
+ class TestDashboard(unittest.TestCase):
199
+ def test_dashboard_is_self_contained_and_rtl(self):
200
+ with tempfile.TemporaryDirectory() as tmp:
201
+ cfg = temp_cfg(tmp)
202
+ desk = dk.Desk(cfg["desk_db"])
203
+ sigs = dk.scan_market(Path(dk.BASE) / "market-demo.json", cfg, desk)
204
+ path = dk.build_dashboard(desk, cfg, cfg["report_path"], [{"symbol": "شپدیس", "reason": "بدون داده",
205
+ "alert": {"title": "خبر"}}])
206
+ body = path.read_text(encoding="utf-8")
207
+ self.assertIn('dir="rtl"', body)
208
+ self.assertIn(sigs[0].sid, body)
209
+ self.assertNotIn("<script", body)
210
+ self.assertNotIn("fonts.googleapis", body)
211
+ self.assertIn("معاملات الگوریتمی خودکار", body)
212
+
213
+ def test_credit_present(self):
214
+ cfg = json.loads(json.dumps(dk.DEFAULT_CONFIG))
215
+ with tempfile.TemporaryDirectory() as tmp:
216
+ path = dk.build_dashboard(dk.Desk(Path(tmp) / "d.sqlite3"), cfg, Path(tmp) / "d.html", [])
217
+ self.assertIn("Mojarabian", path.read_text(encoding="utf-8"))
218
+
219
+
220
+ class TestPortfolioSizing(unittest.TestCase):
221
+ def test_units_follow_kind(self):
222
+ with tempfile.TemporaryDirectory() as tmp:
223
+ cfg = temp_cfg(tmp)
224
+ desk = dk.Desk(cfg["desk_db"])
225
+ sigs = dk.scan_market(Path(dk.BASE) / "market-demo.json", cfg, desk)
226
+ units = {s.kind: s.unit for s in sigs}
227
+ self.assertEqual(units["basis"], "قرارداد")
228
+ self.assertEqual(units["tabei"], "سهم")
229
+ self.assertEqual(units["covered_call"], "سهم")
230
+ self.assertEqual(units["parity"], "سهم")
231
+ self.assertEqual(units["box"], "قرارداد")
232
+
233
+ def test_per_position_cap_is_respected(self):
234
+ with tempfile.TemporaryDirectory() as tmp:
235
+ cfg = temp_cfg(tmp)
236
+ desk = dk.Desk(cfg["desk_db"])
237
+ sigs = dk.scan_market(Path(dk.BASE) / "market-demo.json", cfg, desk)
238
+ data = json.loads((Path(dk.BASE) / "market-demo.json").read_text(encoding="utf-8"))
239
+ budget = data["capital"] * cfg["max_margin_pct"]
240
+ for s in sigs:
241
+ if s.status == "pending":
242
+ self.assertLessEqual(s.margin_locked, budget * cfg["max_position_pct"] + 1)
243
+
244
+ def test_total_allocation_within_cap(self):
245
+ with tempfile.TemporaryDirectory() as tmp:
246
+ cfg = temp_cfg(tmp)
247
+ desk = dk.Desk(cfg["desk_db"])
248
+ sigs = dk.scan_market(Path(dk.BASE) / "market-demo.json", cfg, desk)
249
+ data = json.loads((Path(dk.BASE) / "market-demo.json").read_text(encoding="utf-8"))
250
+ cap = data["capital"] * cfg["max_margin_pct"]
251
+ total = sum(s.margin_locked for s in sigs if s.status == "pending")
252
+ self.assertLessEqual(total, cap + 1)
253
+ self.assertGreaterEqual(len([s for s in sigs if s.status == "pending"]), 2)
254
+
255
+ def test_budget_exhaustion_marks_rejected(self):
256
+ with tempfile.TemporaryDirectory() as tmp:
257
+ cfg = temp_cfg(tmp, capital=1_000_000, max_margin_pct=0.2, max_position_pct=1.0)
258
+ market = Path(tmp) / "m.json"
259
+ row = {"symbol": "الف", "kind": "basis", "spot": 100, "future": 130, "days": 60,
260
+ "margin_per_contract": 60_000, "liquidity_contracts_per_day": 500, "spread_pct": 0.01}
261
+ row2 = dict(row, symbol="ب")
262
+ market.write_text(json.dumps({"hurdle": 0.39, "capital": 1_000_000, "rows": [row, row2]}),
263
+ encoding="utf-8")
264
+ desk = dk.Desk(cfg["desk_db"])
265
+ sigs = dk.scan_market(market, cfg, desk)
266
+ statuses = sorted(s.status for s in sigs)
267
+ self.assertIn("pending", statuses)
268
+ self.assertIn("rejected", statuses)
269
+
270
+
271
+ class TestApprovalGuard(unittest.TestCase):
272
+ def test_approve_blocks_beyond_max_positions(self):
273
+ with tempfile.TemporaryDirectory() as tmp:
274
+ cfg = temp_cfg(tmp, max_positions=1)
275
+ cfg_file = Path(tmp) / "config.json"
276
+ cfg_file.write_text(json.dumps(cfg, ensure_ascii=False), encoding="utf-8")
277
+ market = Path(BASE_MARKET)
278
+ args = type("A", (), {})()
279
+ args.config = str(cfg_file)
280
+ args.market = str(market)
281
+ args.kodal_db = None
282
+ self.assertEqual(dk.cmd_run(args), 0)
283
+ desk = dk.Desk(cfg["desk_db"])
284
+ pending = [s for s in desk.all("pending")]
285
+ self.assertGreaterEqual(len(pending), 2)
286
+ first, second = pending[0], pending[1]
287
+ a1 = type("B", (), {"config": str(cfg_file), "sid": first.sid, "note": "", "force": False})()
288
+ self.assertEqual(dk.cmd_decide(a1, "approved"), 0)
289
+ a2 = type("B", (), {"config": str(cfg_file), "sid": second.sid, "note": "", "force": False})()
290
+ self.assertEqual(dk.cmd_decide(a2, "approved"), 3) # بدون --force رد می‌شود
291
+ a3 = type("B", (), {"config": str(cfg_file), "sid": second.sid, "note": "آگاهانه", "force": True})()
292
+ self.assertEqual(dk.cmd_decide(a3, "approved"), 0)
293
+
294
+
295
+ class TestCli(unittest.TestCase):
296
+ def test_selftest(self):
297
+ self.assertEqual(dk.main(["selftest"]), 0)
298
+
299
+ def test_version(self):
300
+ self.assertEqual(dk.main(["version"]), 0)
301
+
302
+
303
+ if __name__ == "__main__":
304
+ unittest.main(verbosity=2)
kodal-alert/README-FA.md ADDED
@@ -0,0 +1,112 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # دیده‌بان کدال و خبر بازار — راهنمای فارسی
2
+
3
+ نسخهٔ ۰٫۱٫۰ · بدون هیچ وابستگی بیرونی · اجرا روی ویندوز یا لینوکس · بدون اینترنت هم کار می‌کند
4
+
5
+ ## این برنامه چه کار می‌کند
6
+
7
+ ۱. اطلاعیه‌های کدال و خبرهای بازار را می‌خواند (از اینترنت، از فایل، یا از دادهٔ نمونه).
8
+ ۲. هر مورد را دسته‌بندی می‌کند: افزایش سرمایه، تعدیل، توقف و بازگشایی، قرارداد، دعوی، تبعی و بقیهٔ دوازده دسته.
9
+ ۳. جهت را حدس می‌زند (مثبت، منفی، خنثی) و یک **امتیاز ۰ تا ۱۰۰** می‌دهد.
10
+ ۴. برای هر مورد توضیح می‌دهد **چرا مهم است** و اثرش روی ابزار مشتقه را یادآوری می‌کند.
11
+ ۵. گزارش HTML فارسی و راست‌به‌چپ می‌سازد، فهرست هشدارها را در پایگاه‌داده نگه می‌دارد، و در صورت تمایل به تلگرام یا بله می‌فرستد.
12
+
13
+ ## این برنامه چه کاری نمی‌کند
14
+
15
+ - **سفارش نمی‌فرستد.** معاملات الگوریتمی خودکار در بورس و فرابورس ایران مجاز نیست؛ این برنامه «دستیار تصمیم» است و تصمیم نهایی با انسان است.
16
+ - سود تضمین نمی‌کند و هیچ‌جا عدد سود وعده نمی‌دهد. امتیاز، فقط ترکیبی از نوع رویداد، تازگی و وجود عدد کمّی است.
17
+
18
+ ## راه‌اندازی (سه دقیقه)
19
+
20
+ پایتون ۳٫۱۰ یا بالاتر لازم است. روی ویندوز از سایت رسمی پایتون نصب کنید و در هنگام نصب تیک «Add Python to PATH» را بزنید. هیچ بستهٔ اضافی لازم نیست و هیچ اتصالی به پی‌پی‌آی وجود ندارد.
21
+
22
+ ```bash
23
+ python kodal_alert.py selftest # آزمون سلامت (۴ بررسی)
24
+ python kodal_alert.py demo # اجرای کامل روی دادهٔ نمونهٔ آفلاین
25
+ python -m unittest discover -s tests # ۲۶ آزمون واحد
26
+ ```
27
+
28
+ پس از اجرای `demo`، پروندهٔ `data/demo-report.html` را در مرورگر باز کنید.
29
+
30
+ ## اجرای واقعی
31
+
32
+ ```bash
33
+ # یک بار: از کدال و یک فید خبری
34
+ python kodal_alert.py run --source codal --source rss:https://www.farsnews.ir/rss
35
+
36
+ # دوره‌ای: هر ۱۵ دقیقه
37
+ python kodal_alert.py watch --minutes 15 --source codal
38
+
39
+ # ورود دستی اطلاعیه‌ها (وقتی اینترنت یا سامانه در دسترس نیست)
40
+ python kodal_alert.py import my-announcements.json
41
+
42
+ # گزارش و آمار
43
+ python kodal_alert.py report --limit 200
44
+ python kodal_alert.py stats
45
+ ```
46
+
47
+ ورود دستی، ستون فقرات پایداری این برنامه است. اگر اینترنت قطع شد، کافی است اطلاعیه‌ها را در یک پروندهٔ JSON یا CSV بریزید و همان را وارد کنید. قالب JSON:
48
+
49
+ ```json
50
+ [{"title": "افزایش سرمایه ۴۵۰ درصدی", "symbol": "خساپا", "company": "سایپا",
51
+ "source": "کدال", "published_at": "2026-09-22 09:10:00", "url": "https://codal.ir/...",
52
+ "body": "متن کامل اطلاعیه"}]
53
+ ```
54
+
55
+ و قالب CSV با سرسطر `title,symbol,company,source,published_at,url,body`.
56
+
57
+ ## منابع داده و شرایط ایران
58
+
59
+ | منبع | چگونه | هزینه |
60
+ |---|---|---|
61
+ | کدال | تنظیم‌شده در `config.json` با نوع `codal` | رایگان |
62
+ | فید خبری داخلی | نوع `rss` با نشانی فید | رایگان |
63
+ | فایل دستی | نوع `file` یا زیرفرمان `import` | رایگان |
64
+ | ریزمعاملات و دادهٔ تاریخی تجاری | افزودن نشانی وب‌سرویس و کلید در `config.json` | پرداختی با ریال یا کلید آزمایشی |
65
+ | قیمت لحظه‌ای سهام و آپشن | از کتابخانه‌های `tsetmc-api` و `codal-tsetmc` (نصب با `pip install tsetmc-api`) در مرحلهٔ بعد | رایگان |
66
+
67
+ **نکتهٔ مهم تجربی:** سامانه‌های ایرانی از بیرون ایران (سندباکس خارجی) پاسخ نمی‌دهند؛ این برنامه باید **از داخل ایران** اجرا شود. به همین دلیل، حالت آفلاین و ورود دستی از ابتدا در برنامه گذاشته شده است.
68
+
69
+ ## لایهٔ هوش مصنوعی (اختیاری)
70
+
71
+ حالت پیش‌فرض `none` است و همه‌چیز با قواعد فارسی کار می‌کند؛ در گزارش، برچسب «شاهد محلی (قاعده‌محور)» می‌خورد. سه گزینهٔ دیگر:
72
+
73
+ - **Ollama محلی:** رایگان، بدون کلید، بدون تحری��. اگر رایانه‌تان ۸ گیگابایت رم یا بیشتر دارد: `ollama pull qwen2.5:7b` و در `config.json` مقدار `provider` را `ollama` بگذارید.
74
+ - **Jev/TypeSafe:** برای وقتی که کلید دارید. کلید را در متغیر محیطی `TYPESAFE_API_KEY` بگذارید، نه در پروندهٔ تنظیمات.
75
+ - **OpenRouter:** با متغیر محیطی `OPENROUTER_API_KEY`.
76
+
77
+ اگر کلید نبود یا سرویس جواب نداد، برنامه با همان قواعد فارسی کار می‌کند و فقط برچسب منبع را عوض می‌کند. هیچ‌وقت خروجی مدل، «توصیهٔ معامله» نیست؛ فقط خلاصهٔ ساخت‌یافتهٔ رویداد است.
78
+
79
+ ## تنظیمات مهم `config.json`
80
+
81
+ | کلید | معنا | پیش‌فرض |
82
+ |---|---|---|
83
+ | `watchlist` | نمادهایی که همیشه بررسی می‌شوند | خساپا، شپنا، فولاد، وبملت، شستا، اهرم، طلا، زعفران |
84
+ | `min_score_to_alert` | کف امتیاز برای هشدار | ۴۵ |
85
+ | `proxies` | پروکسی برای دسترسی به بیرون | خالی |
86
+ | `timeout_seconds` و `retries` | رفتار شبکه | ۱۵ و ۲ |
87
+ | `notifiers` | کنسول، فایل، تلگرام، بله | کنسول و فایل روشن |
88
+
89
+ ## زمان‌بندی خودکار
90
+
91
+ - ویندوز: `run-daily.bat` را بسازید (در همین پوشه هست) و در «Task Scheduler» روزهای شنبه تا چهارشنبه ساعت ۸:۵۰ و ۱۲:۴۰ اجرا کنید.
92
+ - لینوکس: `*/15 8-12 * * 0-4 python3 /path/kodal_alert.py run --source codal`
93
+
94
+ ## قطعی برق و اینترنت
95
+
96
+ - هر فراخوانی شبکه، timeout و سه تلاش دارد و پاسخ‌ها در `data/cache/` می‌مانند؛ اگر سامانه نخوابد، برنامه از حافظهٔ نهان کار می‌کند.
97
+ - پایگاه‌داده SQLite است و در برابر بستهٔ ناگهانی مقاوم؛ اجرای بعدی، کار ناتمام را ادامه می‌دهد.
98
+ - هر رکورد کلید یکتای خودش را دارد؛ اجرای دوباره باعث تکرار هشدار نمی‌شود.
99
+
100
+ ## امنیت و اخلاق کار
101
+
102
+ - کلیدها فقط در متغیر محیطی، هرگز داخل `config.json` یا کد.
103
+ - این ابزار هیچ سفارشی نمی‌فرستد؛ پس رمز سامانهٔ معاملاتی را در هیچ‌جای این پروژه نگذارید.
104
+ - از اطلاعات نهانی استفاده نکنید و خروجی را به‌عنوان «توصیهٔ سرمایه‌گذاری» به دیگران نفروشید؛ فروش سیگنال در ایران مسئولیت حقوقی دارد.
105
+
106
+ ## قدم بعدی این پروژه
107
+
108
+ اتصال دو طرفه: خروجی همین برنامه به موتور ریاضی `MATERIALS/money/tools/derivatives_scout.py` داده می‌شود تا وقتی خبر مهمی روی یک پایهٔ دارای آپشن یا آتی می‌آید، بازده تضمینی تبعی، بازده باکس و فاصله از نرخ سد دوباره حساب شود و در همان داشبورد نشان داده شود. نقشهٔ کامل در `MATERIALS/money/04-trading-desk-plan-fa.md` آمده است.
109
+
110
+ ## تهیه‌کننده
111
+
112
+ ✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · 📱 [+989126630554](tel:+989126630554) · ✈️ [Telegram: Mojarabian](https://t.me/Mojarabian) · 📸 [Instagram: Mojarabian.Art](https://www.instagram.com/Mojarabian.Art/)
kodal-alert/config.json ADDED
@@ -0,0 +1,22 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "watchlist": ["خساپا", "شپنا", "فولاد", "وبملت", "شستا", "اهرم", "طلا", "زعفران"],
3
+ "sources": [
4
+ {"type": "codal", "name": "کدال", "url": "https://search.codal.ir/api/search/v2/q"},
5
+ {"type": "rss", "name": "فارس", "url": "https://www.farsnews.ir/rss"}
6
+ ],
7
+ "proxies": {"http": "", "https": ""},
8
+ "timeout_seconds": 15,
9
+ "retries": 2,
10
+ "min_score_to_alert": 45,
11
+ "db_path": "",
12
+ "report_path": "",
13
+ "llm": {"provider": "none", "model": "", "base_url": "", "api_key_env": "TYPESAFE_API_KEY"},
14
+ "notifiers": {
15
+ "console": true,
16
+ "file": true,
17
+ "telegram": {"enabled": false, "token_env": "TELEGRAM_BOT_TOKEN", "chat_id": ""},
18
+ "bale": {"enabled": false, "token_env": "BALE_BOT_TOKEN", "chat_id": ""}
19
+ },
20
+ "credit": "تهیه‌کننده: Masoud Mojarabian · https://www.instagram.com/Mojarabian.Art/ · tel:+989126630554 · https://t.me/Mojarabian",
21
+ "report_title": "دیده‌بان کدال و خبر بازار"
22
+ }
kodal-alert/data/demo.sqlite3 ADDED
Binary file (32.8 kB). View file
 
kodal-alert/kodal_alert.py ADDED
@@ -0,0 +1,769 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env python3
2
+ # -*- coding: utf-8 -*-
3
+ """دیده‌بان اطلاعیه‌های کدال و خبر بازار سرمایه — نسخهٔ ۰٫۱٫۰
4
+
5
+ بدون هیچ وابستگی بیرونی (فقط کتابخانهٔ استاندارد پایتون) تا روی هر ویندوز و
6
+ لینوکسی، بدون دسترسی به پی‌پی‌آی و بدون پرداخت ارزی، اجرا شود.
7
+
8
+ اصول طراحی (برای شرایط ایران):
9
+ • آفلاین‌محور: اگر اینترنت یا سامانه در دسترس نبود، از دادهٔ نمونه یا دادهٔ ذخیره‌شده کار می‌کند.
10
+ • بدون کلید و بدون هزینه: حالت پیش‌فرض «شاهد محلی» است؛ لایهٔ هوش مصنوعی اختیاری است.
11
+ • قابل‌سرویس‌دهی از داخل ایران: همهٔ فراخوانی‌ها با timeout و retry، و پشتیبانی پروکسی.
12
+ • هیچ توصیهٔ سوددهی تضمینی‌ای تولید نمی‌کند؛ خروجی «هشدار و زمینه» است، نه دستور معامله.
13
+
14
+ دستورها:
15
+ python kodal_alert.py demo اجرای کامل روی دادهٔ نمونه (آفلاین)
16
+ python kodal_alert.py import FILE ورود اطلاعیه‌ها از فایل JSON/CSV
17
+ python kodal_alert.py run --source rss:URL --source codal
18
+ python kodal_alert.py watch --minutes 10 اجرای دوره‌ای
19
+ python kodal_alert.py report ساخت گزارش HTML از پایگاه‌داده
20
+ python kodal_alert.py stats | version | selftest
21
+ """
22
+ from __future__ import annotations
23
+
24
+ import argparse
25
+ import csv
26
+ import hashlib
27
+ import html
28
+ import json
29
+ import os
30
+ import re
31
+ import sqlite3
32
+ import sys
33
+ import time
34
+ import urllib.error
35
+ import urllib.parse
36
+ import urllib.request
37
+ import xml.etree.ElementTree as ET
38
+ from dataclasses import dataclass, field, asdict
39
+ from datetime import datetime, timedelta, timezone
40
+ from pathlib import Path
41
+
42
+ VERSION = "0.1.0"
43
+ BASE = Path(__file__).resolve().parent
44
+ DEFAULT_DB = BASE / "data" / "kodal.sqlite3"
45
+ DEFAULT_REPORT = BASE / "data" / "report.html"
46
+ CACHE_DIR = BASE / "data" / "cache"
47
+ CREDIT = ("تهیه‌کننده: Masoud Mojarabian · "
48
+ "https://www.instagram.com/Mojarabian.Art/ · "
49
+ "tel:+989126630554 · https://t.me/Mojarabian")
50
+
51
+ # ---------------------------------------------------------------- تنظیمات پیش‌فرض
52
+ DEFAULT_CONFIG: dict = {
53
+ "watchlist": ["خساپا", "شپنا", "فولاد", "وبملت", "شستا", "اهرم", "طلا", "زعفران"],
54
+ "sources": [
55
+ {"type": "rss", "name": "فارس", "url": "https://www.farsnews.ir/rss"},
56
+ {"type": "rss", "name": "ایبنا", "url": "https://www.ibena.ir/rss"},
57
+ {"type": "codal", "name": "کدال", "url": "https://search.codal.ir/api/search/v2/q"}
58
+ ],
59
+ "proxies": {"http": "", "https": ""},
60
+ "timeout_seconds": 15,
61
+ "retries": 2,
62
+ "min_score_to_alert": 45,
63
+ "llm": {"provider": "none", "model": "", "base_url": "", "api_key_env": "TYPESAFE_API_KEY"},
64
+ "notifiers": {"console": True, "file": True,
65
+ "telegram": {"enabled": False, "token_env": "TELEGRAM_BOT_TOKEN", "chat_id": ""},
66
+ "bale": {"enabled": False, "token_env": "BALE_BOT_TOKEN", "chat_id": ""}},
67
+ "credit": CREDIT,
68
+ "report_title": "دیده‌بان کدال و خبر بازار",
69
+ }
70
+
71
+ # ---------------------------------------------------------------- دسته‌بندی رویدادها
72
+ # (دسته، کلیدواژه‌ها، امتیاز پایه، جهت، توضیح چرایی)
73
+ CATEGORY_RULES: list[tuple[str, list[str], int, str, str]] = [
74
+ ("افزایش سرمایه", ["افزایش سرمایه", "تجدید ارزیابی", "آورده نقدی", "سهام جایزه"], 80, "مثبت",
75
+ "افزایش سرمایه ساختار ترازنامه را عوض می‌کند و روی تعداد سهام، قیمت پایه و اندازهٔ قرارداد مشتقه اثر می‌گذارد."),
76
+ ("تعدیل پیش‌بینی", ["تعدیل", "پیش‌بینی درآمد", "پیش‌بینی سود", "eps"], 78, "نامعلوم",
77
+ "تعدیل پیش‌بینی، محرک اصلی انتظارات سود است؛ جهت تعدیل (مثبت یا منفی) را از متن بخوانید."),
78
+ ("تقسیم سود", ["تقسیم سود", "مجمع عمومی", "سود نقدی", "dps"], 60, "نامعلوم",
79
+ "مجمع و تقسیم سود، تاریخ توقف نماد و قیمت پایهٔ پس از مجمع را تغییر می‌دهد."),
80
+ ("قرارداد و فروش", ["انعقاد قرارداد", "قرارداد جدید", "افزایش نرخ فروش", "صادرات", "سفارش خرید"], 62, "مثبت",
81
+ "قرارداد یا افزایش نرخ فروش، جریان درآمد آینده را تغییر می‌دهد؛ به مبلغ و مدت قرارداد نگاه کنید."),
82
+ ("تولید و فروش ماهانه", ["گزارش فعالیت ماهانه", "میزان تولید", "میزان فروش", "فروش ماهانه"], 48, "نامعلوم",
83
+ "گزارش ماهانه بهترین نمای نزدیک از روند واقعی شرکت است؛ روند سه‌ماهه مهم‌تر از یک ماه است."),
84
+ ("توقف و بازگشایی نماد", ["توقف نماد", "بازگشایی نماد", "شناور شدن"], 70, "منفی",
85
+ "توقف و بازگشایی، نقدشوندگی را از بین می‌برد یا برمی‌گرداند؛ در زمان توقف، آپشن و آتی همان پایه پرریسک می‌شوند."),
86
+ ("شفاف‌سازی", ["شفاف‌سازی", "توضیحات در خصوص", "پاسخ به استعلام"], 55, "نامعلوم",
87
+ "شفاف‌سازی معمولاً واکنش به شایعه یا نوسان غیرعادی است؛ متن را کامل بخوانید."),
88
+ ("دارایی و سرمایه‌گذاری", ["واگذاری دارایی", "خرید سهام", "سرمایه‌گذاری", "فروش زمین", "فروش ساختمان"], 58, "نامعلوم",
89
+ "خرید یا فروش دارایی می‌تواند سود غیرعملیاتی بسازد؛ تکرارشدنی بودنش را بسنجید."),
90
+ ("دعاوی و ریسک حقوقی", ["دعوی", "شکایت", "محکومیت", "جریمه", "مالیات معوق", "بدهی"], 66, "منفی",
91
+ "ریسک حقوقی و بدهی، پیش‌بینی سود را بی‌اعتبار می‌کند؛ مبلغ ادعا را با سرمایهٔ شرکت مقایسه کنید."),
92
+ ("مدیریت و مالکیت", ["تغییر مدیرعامل", "استعفا", "انتخاب اعضای هیئت مدیره", "سهامدار عمده"], 52, "نامعلوم",
93
+ "تغییر مدیریت یا مالکیت، جهت راهبرد شرکت را عوض می‌کند؛ پیامدش دیرهنگام ظاهر می‌شود."),
94
+ ("ابزار مشتقه و تبعی", ["اختیار فروش تبعی", "اوراق تبعی", "قرارداد آتی", "اختیار معامله", "صندوق طلا"], 75, "مثبت",
95
+ "عرضهٔ تبعی، کفِ بازده را تضمین می‌کند؛ بازده تضمینی و شرط نگه‌داشتن سبد را دقیق حساب کنید."),
96
+ ("پذیرش و عرضه", ["پذیرش در فرابورس", "عرضه اولیه", "پذیره‌نویسی"], 63, "نامعلوم",
97
+ "پذیرش و عرضهٔ اولیه، عرضه و تقاضای سهم را جابه‌جا می‌کند."),
98
+ ]
99
+
100
+ POSITIVE_WORDS = ["افزایش", "رشد", "سود", "مثبت", "توسعه", "بهبود", "رکورد", "قرارداد", "صادرات", "تعدیل مثبت"]
101
+ NEGATIVE_WORDS = ["کاهش", "زیان", "منفی", "توقف", "لغو", "شکایت", "دعوی", "محکومیت", "جریمه", "افت", "تعدیل منفی", "بدهی"]
102
+ NUMERIC_BONUS_PATTERNS = [r"\d[\d,\.]*\s*میلیارد", r"\d[\d,\.]*\s*میلیون", r"\d+\s*درصد", r"\d[\d,\.]*\s*ریال"]
103
+
104
+ # ---------------------------------------------------------------- ابزار پایه
105
+ def now_utc() -> datetime:
106
+ return datetime.now(timezone.utc)
107
+
108
+
109
+ def g2j(gy: int, gm: int, gd: int) -> tuple[int, int, int]:
110
+ """تبدیل تاریخ میلادی به شمسی (الگوریتم استاندارد)."""
111
+ g_d_m = [0, 31, 59, 90, 120, 151, 181, 212, 243, 273, 304, 334]
112
+ gy2 = gy + 1 if gm > 2 else gy
113
+ days = 355666 + (365 * gy) + ((gy2 + 3) // 4) - ((gy2 + 99) // 100) + ((gy2 + 399) // 400) + gd + g_d_m[gm - 1]
114
+ jy = -1595 + 33 * (days // 12053)
115
+ days %= 12053
116
+ jy += 4 * (days // 1461)
117
+ days %= 1461
118
+ if days > 365:
119
+ jy += (days - 1) // 365
120
+ days = (days - 1) % 365
121
+ if days < 186:
122
+ jm = 1 + days // 31
123
+ jd = 1 + days % 31
124
+ else:
125
+ jm = 7 + (days - 186) // 30
126
+ jd = 1 + (days - 186) % 30
127
+ return jy, jm, jd
128
+
129
+
130
+ def jalali_str(dt: datetime | None = None) -> str:
131
+ dt = dt or now_utc()
132
+ jy, jm, jd = g2j(dt.year, dt.month, dt.day)
133
+ return f"{jy:04d}/{jm:02d}/{jd:02d} {dt.hour:02d}:{dt.minute:02d}"
134
+
135
+
136
+ def log(msg: str) -> None:
137
+ print(f"[{jalali_str()}] {msg}")
138
+
139
+
140
+ def load_config(path: str | None) -> dict:
141
+ cfg = json.loads(json.dumps(DEFAULT_CONFIG, ensure_ascii=False)) # کپی عمیق
142
+ p = Path(path) if path else BASE / "config.json"
143
+ if p.exists():
144
+ try:
145
+ user = json.loads(p.read_text(encoding="utf-8"))
146
+ for k, v in user.items():
147
+ if isinstance(v, dict) and isinstance(cfg.get(k), dict):
148
+ cfg[k].update(v)
149
+ else:
150
+ cfg[k] = v
151
+ except json.JSONDecodeError as e:
152
+ log(f"پروندهٔ تنظیمات خوانده نشد ({e})؛ تنظیمات پیش‌فرض استفاده می‌شود.")
153
+ return cfg
154
+
155
+
156
+ # ---------------------------------------------------------------- لایهٔ شبکه
157
+ def http_get(url: str, cfg: dict, cache_name: str | None = None) -> str | None:
158
+ """دریافت متن با retry، timeout، پروکسی و حافظهٔ نهان روی دیسک."""
159
+ if url.startswith("file:"):
160
+ try:
161
+ return Path(url[5:]).read_text(encoding="utf-8")
162
+ except OSError as e:
163
+ log(f"خواندن فایل ممکن نشد: {e}")
164
+ return None
165
+ CACHE_DIR.mkdir(parents=True, exist_ok=True)
166
+ cache_file = CACHE_DIR / (cache_name or hashlib.sha1(url.encode()).hexdigest())
167
+ handlers = []
168
+ proxies = {k: v for k, v in (cfg.get("proxies") or {}).items() if v}
169
+ if proxies:
170
+ handlers.append(urllib.request.ProxyHandler(proxies))
171
+ opener = urllib.request.build_opener(*handlers)
172
+ req = urllib.request.Request(url, headers={
173
+ "User-Agent": "Mozilla/5.0 (KodalAlert/0.1; +local)",
174
+ "Accept": "application/json, text/xml, application/xml, text/html;q=0.9, */*;q=0.5",
175
+ })
176
+ for attempt in range(1, int(cfg.get("retries", 2)) + 2):
177
+ try:
178
+ with opener.open(req, timeout=float(cfg.get("timeout_seconds", 15))) as resp:
179
+ body = resp.read().decode("utf-8", errors="replace")
180
+ cache_file.write_text(body, encoding="utf-8")
181
+ return body
182
+ except (urllib.error.URLError, urllib.error.HTTPError, TimeoutError, OSError) as e:
183
+ log(f"تلاش {attempt} برای {url} ناموفق: {e}")
184
+ time.sleep(min(2.0 * attempt, 6.0))
185
+ if cache_file.exists():
186
+ log(f"از حافظهٔ نهان استفاده شد: {cache_file.name}")
187
+ return cache_file.read_text(encoding="utf-8")
188
+ return None
189
+
190
+
191
+ # ---------------------------------------------------------------- مدل داده
192
+ @dataclass
193
+ class Item:
194
+ title: str
195
+ source: str = "نامشخص"
196
+ symbol: str = ""
197
+ company: str = ""
198
+ body: str = ""
199
+ url: str = ""
200
+ published_at: str = ""
201
+ category: str = ""
202
+ direction: str = "نامعلوم"
203
+ score: int = 0
204
+ reason: str = ""
205
+ ai_note: str = ""
206
+ provider: str = "شاهد محلی (قاعده‌محور)"
207
+
208
+ def key(self) -> str:
209
+ raw = f"{self.source}|{self.title}|{self.symbol}|{self.published_at}".encode("utf-8")
210
+ return hashlib.sha1(raw).hexdigest()[:16]
211
+
212
+ def to_row(self) -> tuple:
213
+ d = asdict(self)
214
+ return (self.key(), d["title"], d["source"], d["symbol"], d["company"], d["body"], d["url"],
215
+ d["published_at"], d["category"], d["direction"], d["score"], d["reason"], d["ai_note"], d["provider"])
216
+
217
+
218
+ # ---------------------------------------------------------------- دسته‌بندی و امتیازدهی
219
+ def classify(title: str, body: str, source_weight: float = 1.0,
220
+ published_at: datetime | None = None) -> tuple[str, str, int, str]:
221
+ """عنوان بر متن مقدم است تا متن‌های حاشیه‌ای، دسته را از مسیر خارج نکنند."""
222
+ title_l, body_l = title.lower(), body.lower()
223
+ best: tuple[str, int, str, str] | None = None
224
+ for cat, kws, base, direction, why in CATEGORY_RULES:
225
+ t_hits = sum(1 for kw in kws if kw.lower() in title_l)
226
+ b_hits = sum(1 for kw in kws if kw.lower() in body_l)
227
+ if t_hits == 0 and b_hits < 2:
228
+ continue
229
+ effective = t_hits * 3 + b_hits
230
+ score = base + min(max(effective - 1, 0), 3) * 4
231
+ if t_hits == 0:
232
+ score -= 12 # فقط از متن آمده: کمی محافظه‌کارتر
233
+ if best is None or score > best[1]:
234
+ best = (cat, score, direction, why)
235
+ if best is None:
236
+ best = ("سایر", 30, "نامعلوم", "دستهٔ مشخصی تشخیص داده نشد؛ عنوان را خودتان بخوانید.")
237
+
238
+ cat, score, direction, why = best
239
+ if cat == "توقف و بازگشایی نماد":
240
+ direction = "مثبت" if ("بازگشایی" in title_l and "توقف نماد" not in title_l) else "منفی"
241
+ text = f"{title_l} {body_l}"
242
+ pos = sum(1 for w in POSITIVE_WORDS if w in text)
243
+ neg = sum(1 for w in NEGATIVE_WORDS if w in text)
244
+ if direction == "نامعلوم":
245
+ direction = "مثبت" if pos > neg else ("منفی" if neg > pos else "خنثی")
246
+ if any(re.search(p, text) for p in NUMERIC_BONUS_PATTERNS):
247
+ score += 6
248
+ why += " متن عدد کمّی دارد؛ نسبت آن عدد به اندازهٔ شرکت را حساب کنید."
249
+ if published_at is not None:
250
+ pa = published_at if published_at.tzinfo else published_at.replace(tzinfo=timezone.utc)
251
+ age_h = (now_utc() - pa).total_seconds() / 3600.0
252
+ if age_h <= 6:
253
+ score += 8
254
+ elif age_h > 72:
255
+ score -= 10
256
+ score = int(max(0, min(100, round(score * source_weight))))
257
+ return cat, direction, score, why
258
+
259
+
260
+ def symbol_in_watchlist(item: Item, watchlist: list[str]) -> bool:
261
+ blob = f"{item.symbol} {item.title} {item.company}"
262
+ return any(w and w in blob for w in watchlist)
263
+
264
+
265
+ # ---------------------------------------------------------------- انبار داده
266
+ SCHEMA = """
267
+ CREATE TABLE IF NOT EXISTS items (
268
+ id TEXT PRIMARY KEY, title TEXT, source TEXT, symbol TEXT, company TEXT,
269
+ body TEXT, url TEXT, published_at TEXT, category TEXT, direction TEXT,
270
+ score INTEGER, reason TEXT, ai_note TEXT, provider TEXT, created_at TEXT
271
+ );
272
+ CREATE TABLE IF NOT EXISTS runs (id INTEGER PRIMARY KEY AUTOINCREMENT, started_at TEXT, items INTEGER, source TEXT);
273
+ """
274
+
275
+
276
+ class Store:
277
+ def __init__(self, path: Path | str = DEFAULT_DB):
278
+ self.path = Path(path)
279
+ self.path.parent.mkdir(parents=True, exist_ok=True)
280
+ self.conn = sqlite3.connect(str(self.path))
281
+ self.conn.executescript(SCHEMA)
282
+ self.conn.commit()
283
+
284
+ # ── بستن تمیز (پایان کار / پرونده‌های موقت)
285
+ def close(self) -> None:
286
+ """پیوند پایگاه‌داده را می‌بندد. چند بار صدا زدنش بی‌خطر است."""
287
+ try:
288
+ self.conn.close()
289
+ except Exception: # noqa: BLE001 — بستن نباید برنامه را بیندازد
290
+ pass
291
+
292
+ def __enter__(self) -> "Store":
293
+ return self
294
+
295
+ def __exit__(self, *exc) -> None:
296
+ self.close()
297
+
298
+ def __del__(self) -> None:
299
+ self.close()
300
+
301
+
302
+ def add(self, item: Item) -> bool:
303
+ try:
304
+ self.conn.execute(
305
+ "INSERT INTO items VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)",
306
+ item.to_row() + (now_utc().isoformat(timespec="seconds"),))
307
+ return True
308
+ except sqlite3.IntegrityError:
309
+ return False
310
+
311
+ def commit(self) -> None:
312
+ self.conn.commit()
313
+
314
+ def recent(self, limit: int = 100, min_score: int = 0) -> list[Item]:
315
+ cur = self.conn.execute(
316
+ "SELECT title,source,symbol,company,body,url,published_at,category,direction,score,reason,ai_note,provider "
317
+ "FROM items WHERE score >= ? ORDER BY score DESC, published_at DESC LIMIT ?", (min_score, limit))
318
+ return [Item(*row) for row in cur.fetchall()]
319
+
320
+ def count(self) -> int:
321
+ return int(self.conn.execute("SELECT COUNT(*) FROM items").fetchone()[0])
322
+
323
+ def log_run(self, source: str, n: int) -> None:
324
+ self.conn.execute("INSERT INTO runs (started_at, items, source) VALUES (?,?,?)",
325
+ (now_utc().isoformat(timespec="seconds"), n, source))
326
+ self.conn.commit()
327
+
328
+
329
+ # ---------------------------------------------------------------- منابع داده
330
+ def item_from_dict(d: dict, source_name: str = "", cfg: dict | None = None) -> Item:
331
+ cfg = cfg or {}
332
+ published = None
333
+ raw_date = str(d.get("published_at") or d.get("date") or "").strip()
334
+ for fmt in ("%Y-%m-%dT%H:%M:%S", "%Y-%m-%d %H:%M:%S", "%Y-%m-%d", "%Y/%m/%d"):
335
+ try:
336
+ published = datetime.strptime(raw_date[:19], fmt).replace(tzinfo=timezone.utc)
337
+ break
338
+ except ValueError:
339
+ continue
340
+ sw = 1.15 if source_name in ("کدال", "codal") else 1.0
341
+ cat, direction, score, why = classify(str(d.get("title", "")), str(d.get("body", "")), sw, published)
342
+ return Item(title=str(d.get("title", "")).strip(), source=source_name or str(d.get("source", "نامشخص")),
343
+ symbol=str(d.get("symbol", "")).strip(), company=str(d.get("company", "")).strip(),
344
+ body=str(d.get("body", ""))[:2000], url=str(d.get("url", "")), published_at=raw_date,
345
+ category=cat, direction=direction, score=score, reason=why)
346
+
347
+
348
+ def load_file_source(path: str, cfg: dict) -> list[Item]:
349
+ p = Path(path)
350
+ if not p.exists():
351
+ log(f"پروندهٔ منبع پیدا نشد: {path}")
352
+ return []
353
+ text = p.read_text(encoding="utf-8")
354
+ items: list[Item] = []
355
+ if p.suffix.lower() == ".csv":
356
+ for row in csv.DictReader(text.splitlines()):
357
+ items.append(item_from_dict(row, cfg=cfg))
358
+ else:
359
+ data = json.loads(text)
360
+ rows = data if isinstance(data, list) else data.get("items", [])
361
+ for row in rows:
362
+ items.append(item_from_dict(row, cfg=cfg))
363
+ return items
364
+
365
+
366
+ def parse_feed(xml_text: str, source_name: str, cfg: dict) -> list[Item]:
367
+ items: list[Item] = []
368
+ try:
369
+ root = ET.fromstring(xml_text)
370
+ except ET.ParseError as e:
371
+ log(f"فید خوانده نشد: {e}")
372
+ return items
373
+ nodes = root.iter("item") if root.findall(".//item") else root.iter("{http://www.w3.org/2005/Atom}entry")
374
+ for node in nodes:
375
+ def txt(tag: str) -> str:
376
+ el = node.find(tag) if node.find(tag) is not None else node.find("{http://www.w3.org/2005/Atom}" + tag)
377
+ return (el.text or "").strip() if el is not None and el.text else ""
378
+ link = txt("link") or ""
379
+ if not link:
380
+ el = node.find("{http://www.w3.org/2005/Atom}link")
381
+ link = el.get("href", "") if el is not None else ""
382
+ title, desc = txt("title"), (txt("description") or txt("summary"))
383
+ desc = re.sub(r"<[^>]+>", " ", desc)[:1500]
384
+ if title:
385
+ items.append(item_from_dict({"title": title, "body": desc, "url": link,
386
+ "published_at": txt("pubDate") or txt("updated")},
387
+ source_name=source_name, cfg=cfg))
388
+ return items
389
+
390
+
391
+ def fetch_codal(cfg: dict) -> list[Item]:
392
+ """تلاش برای خواندن اطلاعیه‌های کدال. اگر سامانه پاسخ ندهد، رشتهٔ خالی برمی‌گردد."""
393
+ src = next((s for s in cfg.get("sources", []) if s.get("type") == "codal"), None)
394
+ if not src:
395
+ return []
396
+ params = {"PageNumber": "1", "Length": "-1", "Audited": "true", "NotAudited": "true",
397
+ "Mains": "true", "Childs": "true", "Publisher": "false", "search": "true", "LetterType": "-1", "Category": "-1"}
398
+ url = f"{src.get('url')}?{urllib.parse.urlencode(params)}"
399
+ body = http_get(url, cfg, cache_name="codal.json")
400
+ if not body:
401
+ log("کدال پاسخ نداد؛ از منبع فایلی یا خبری استفاده کنید.")
402
+ return []
403
+ out: list[Item] = []
404
+ try:
405
+ data = json.loads(body)
406
+ for row in data.get("Letters", []) or data.get("letters", []) or []:
407
+ title = str(row.get("Title") or row.get("title") or "").strip()
408
+ if not title:
409
+ continue
410
+ out.append(item_from_dict({
411
+ "title": title,
412
+ "symbol": str(row.get("Symbol") or row.get("symbol") or ""),
413
+ "company": str(row.get("CompanyName") or row.get("companyName") or ""),
414
+ "url": "https://codal.ir" + str(row.get("Url") or row.get("url") or ""),
415
+ "published_at": str(row.get("PublishDateTime") or row.get("publishDateTime") or ""),
416
+ }, source_name="کدال", cfg=cfg))
417
+ except (json.JSONDecodeError, AttributeError, TypeError) as e:
418
+ log(f"ساختار پاسخ کدال ناشناخته بود: {e}")
419
+ return out
420
+
421
+
422
+ def fetch_rss(cfg: dict) -> list[Item]:
423
+ out: list[Item] = []
424
+ for src in cfg.get("sources", []):
425
+ if src.get("type") != "rss":
426
+ continue
427
+ xml_text = http_get(src.get("url", ""), cfg, cache_name=f"rss-{src.get('name','feed')}.xml")
428
+ if not xml_text:
429
+ continue
430
+ out.extend(parse_feed(xml_text, src.get("name", "خبر"), cfg))
431
+ return out
432
+
433
+
434
+ # ---------------------------------------------------------------- لایهٔ هوش مصنوعی (اختیاری)
435
+ LLM_PROMPT = """تو دستیار تحلیل اطلاعیه‌های کدال و خبر بازار سرمایه ایران هستی.
436
+ فقط از متن زیر استفاده کن و چیزی از خودت اضافه نکن. خروجی را فقط JSON بده با این کلیدها:
437
+ {"رویداد": "...", "جهت": "مثبت|منفی|خنثی", "بزرگی": "کم|متوسط|زیاد", "افق": "کوتاه|میان|بلند",
438
+ "اقدام": "یک اقدام بررسی‌محور و نه توصیهٔ خرید و فروش", "اطمینان": 0 تا 100}
439
+ هیچ وعدهٔ سود و هیچ دستور معامله‌ای نده.
440
+ عنوان: {title}
441
+ متن: {body}
442
+ """
443
+
444
+
445
+ def llm_enrich(item: Item, cfg: dict) -> None:
446
+ """غنی‌سازی با مدل زبانی. اگر کلید یا سرویس نبود، برچسب «شاهد محلی» باقی می‌ماند."""
447
+ conf = cfg.get("llm", {})
448
+ provider = conf.get("provider", "none")
449
+ if provider in ("", "none", None):
450
+ return
451
+ prompt = LLM_PROMPT.replace("{title}", item.title).replace("{body}", item.body or item.title)
452
+ text = None
453
+ try:
454
+ if provider == "ollama":
455
+ payload = {"model": conf.get("model") or "qwen2.5:7b", "prompt": prompt, "stream": False, "format": "json"}
456
+ req = urllib.request.Request(conf.get("base_url") or "http://127.0.0.1:11434/api/generate",
457
+ data=json.dumps(payload).encode(), headers={"Content-Type": "application/json"})
458
+ with urllib.request.urlopen(req, timeout=90) as r:
459
+ text = json.loads(r.read().decode()).get("response", "")
460
+ item.provider = "Ollama محلی"
461
+ elif provider in ("typesafe", "jev"):
462
+ key = os.environ.get(conf.get("api_key_env", "TYPESAFE_API_KEY"), "")
463
+ if not key:
464
+ item.provider = "شاهد محلی (کلید هوش مصنوعی تنظیم نشده)"
465
+ return
466
+ url = conf.get("base_url") or "https://api.typesafe.ai/v1/chat/completions"
467
+ payload = {"model": conf.get("model") or "jev-latest",
468
+ "messages": [{"role": "user", "content": prompt}]}
469
+ req = urllib.request.Request(url, data=json.dumps(payload).encode(), headers={
470
+ "Content-Type": "application/json", "Authorization": f"Bearer {key}"})
471
+ with urllib.request.urlopen(req, timeout=60) as r:
472
+ text = json.loads(r.read().decode())["choices"][0]["message"]["content"]
473
+ item.provider = "Jev/TypeSafe"
474
+ elif provider == "openrouter":
475
+ key = os.environ.get(conf.get("api_key_env", "OPENROUTER_API_KEY"), "")
476
+ if not key:
477
+ item.provider = "شاهد محلی (کلید هوش مصنوعی تنظیم نشده)"
478
+ return
479
+ url = conf.get("base_url") or "https://openrouter.ai/api/v1/chat/completions"
480
+ payload = {"model": conf.get("model") or "meta-llama/llama-3.1-8b-instruct",
481
+ "messages": [{"role": "user", "content": prompt}]}
482
+ req = urllib.request.Request(url, data=json.dumps(payload).encode(), headers={
483
+ "Content-Type": "application/json", "Authorization": f"Bearer {key}"})
484
+ with urllib.request.urlopen(req, timeout=60) as r:
485
+ text = json.loads(r.read().decode())["choices"][0]["message"]["content"]
486
+ item.provider = "OpenRouter"
487
+ except Exception as e: # شبکه، کلید، ساختار پاسخ
488
+ item.provider = f"شاهد محلی (خطای سرویس: {type(e).__name__})"
489
+ return
490
+ if not text:
491
+ return
492
+ m = re.search(r"\{.*\}", text, re.S)
493
+ if not m:
494
+ return
495
+ try:
496
+ data = json.loads(m.group(0))
497
+ item.ai_note = (f"رویداد: {data.get('رویداد','')} | جهت: {data.get('جهت','')} | "
498
+ f"بزرگی: {data.get('بزرگی','')} | افق: {data.get('افق','')} | "
499
+ f"اقدام: {data.get('اقدام','')} | اطمینان: {data.get('اطمینان','')}")
500
+ except json.JSONDecodeError:
501
+ item.ai_note = text[:300]
502
+
503
+
504
+ # ---------------------------------------------------------------- اعلان‌ها
505
+ def notify(items: list[Item], cfg: dict) -> None:
506
+ hot = [i for i in items if i.score >= int(cfg.get("min_score_to_alert", 45))]
507
+ if cfg.get("notifiers", {}).get("console", True):
508
+ print("\n" + "=" * 78)
509
+ print(f"هشدارهای مهم امروز: {len(hot)} مورد از {len(items)} مورد پردازش‌شده")
510
+ print("=" * 78)
511
+ for it in hot[:25]:
512
+ print(f"[{it.score:>3}] {it.direction:<6} {it.category:<22} {it.symbol or '-':<10} {it.title[:70]}")
513
+ print(f" چرا مهم است: {it.reason}")
514
+ if it.ai_note:
515
+ print(f" {it.provider}: {it.ai_note}")
516
+ if it.url:
517
+ print(f" {it.url}")
518
+ if cfg.get("notifiers", {}).get("file", True):
519
+ logfile = BASE / "data" / "alerts.log"
520
+ logfile.parent.mkdir(parents=True, exist_ok=True)
521
+ with logfile.open("a", encoding="utf-8") as f:
522
+ for it in hot:
523
+ f.write(f"{jalali_str()} | {it.score} | {it.direction} | {it.title} | {it.url}\n")
524
+ for name, url_tpl in (("telegram", "https://api.telegram.org/bot{token}/sendMessage"),
525
+ ("bale", "https://tapi.bale.ai/bot{token}/sendMessage")):
526
+ conf = cfg.get("notifiers", {}).get(name, {})
527
+ if not conf.get("enabled"):
528
+ continue
529
+ token = os.environ.get(conf.get("token_env", ""), "")
530
+ chat_id = conf.get("chat_id", "")
531
+ if not token or not chat_id:
532
+ continue
533
+ text = "هشدار کدال:\n" + "\n".join(f"• [{i.score}] {i.title[:120]}" for i in hot[:10])
534
+ try:
535
+ payload = urllib.parse.urlencode({"chat_id": chat_id, "text": text}).encode()
536
+ req = urllib.request.Request(url_tpl.format(token=token), data=payload)
537
+ urllib.request.urlopen(req, timeout=20).read()
538
+ log(f"اعلان {name} ارسال شد.")
539
+ except Exception as e:
540
+ log(f"ارسال اعلان {name} ناموفق: {e}")
541
+
542
+
543
+ # ---------------------------------------------------------------- گزارش HTML
544
+ def build_report(items: list[Item], cfg: dict, path: Path | str = DEFAULT_REPORT) -> Path:
545
+ path = Path(path)
546
+ path.parent.mkdir(parents=True, exist_ok=True)
547
+ rows = []
548
+ for it in items:
549
+ color = {"مثبت": "#0a7d33", "منفی": "#b3261e", "خنثی": "#5f6368", "نامعلوم": "#8a6d00"}.get(it.direction, "#5f6368")
550
+ rows.append(f"""<tr>
551
+ <td class="score">{it.score}</td>
552
+ <td><span class="badge" style="background:{color}">{html.escape(it.direction)}</span></td>
553
+ <td>{html.escape(it.category)}</td>
554
+ <td>{html.escape(it.symbol or '-')}</td>
555
+ <td class="title">{html.escape(it.title)}{f'<div class="ai">{html.escape(it.provider)}: {html.escape(it.ai_note)}</div>' if it.ai_note else ''}</td>
556
+ <td class="why">{html.escape(it.reason)}</td>
557
+ <td>{f'<a href="{html.escape(it.url)}">منبع</a>' if it.url else '—'}</td>
558
+ <td class="src">{html.escape(it.source)}</td>
559
+ </tr>""")
560
+ doc = f"""<!DOCTYPE html>
561
+ <html lang="fa" dir="rtl"><head><meta charset="utf-8">
562
+ <title>{html.escape(cfg.get('report_title','دیده‌بان'))} — {jalali_str()}</title>
563
+ <style>
564
+ :root {{ color-scheme: light; }}
565
+ body {{ font-family: Tahoma, "Segoe UI", "Vazirmatn", sans-serif; margin: 0; background: #f7f7f9; color: #1d1d1f; }}
566
+ header {{ background: #102a43; color: #fff; padding: 18px 22px; }}
567
+ header h1 {{ margin: 0 0 6px; font-size: 20px; }}
568
+ header .meta {{ font-size: 12px; opacity: .85; }}
569
+ main {{ padding: 18px 22px 40px; }}
570
+ table {{ width: 100%; border-collapse: collapse; background: #fff; font-size: 13px; }}
571
+ th, td {{ border-bottom: 1px solid #e5e7eb; padding: 8px 10px; text-align: right; vertical-align: top; }}
572
+ th {{ background: #eef2f7; font-size: 12.5px; }}
573
+ .score {{ font-weight: bold; font-variant-numeric: tabular-nums; }}
574
+ .badge {{ color: #fff; border-radius: 10px; padding: 2px 8px; font-size: 11.5px; }}
575
+ .title {{ min-width: 260px; }}
576
+ .why {{ color: #444; max-width: 320px; }}
577
+ .src, .meta {{ color: #6b7280; font-size: 12px; }}
578
+ .ai {{ margin-top: 4px; color: #0b5394; font-size: 12px; }}
579
+ footer {{ margin-top: 18px; font-size: 11.5px; color: #6b7280; line-height: 1.9; }}
580
+ .note {{ background: #fff8e1; border: 1px solid #f0e0a8; padding: 10px 12px; border-radius: 8px; font-size: 12.5px; margin-bottom: 14px; }}
581
+ @media print {{ body {{ background: #fff; }} }}
582
+ </style></head>
583
+ <body>
584
+ <header>
585
+ <h1>{html.escape(cfg.get('report_title','دیده‌بان'))}</h1>
586
+ <div class="meta">زمان گزارش: {jalali_str()} · تعداد رکورد: {len(items)}</div>
587
+ </header>
588
+ <main>
589
+ <div class="note">این گزارش «دستیار تصمیم» است، نه توصیهٔ معامله. هیچ سود تضمینی در آن نیست.
590
+ امتیاز، ترکیبی از نوع رویداد، تازگی خبر و وجود عدد کمّی است. تصمیم نهایی و مسئولیت آن بر عهدهٔ کاربر است.</div>
591
+ <table>
592
+ <thead><tr><th>امتیاز</th><th>جهت</th><th>دسته</th><th>نماد</th><th>عنوان</th><th>چرا مهم است</th><th>منبع</th><th>مأخذ</th></tr></thead>
593
+ <tbody>{''.join(rows) or '<tr><td colspan="8">رکوردی نیست.</td></tr>'}</tbody>
594
+ </table>
595
+ <footer>
596
+ ساختهٔ دیده‌بان کدال نسخهٔ {VERSION} · {html.escape(cfg.get('credit', CREDIT))}<br>
597
+ برای اجرای روزانه: <code>python kodal_alert.py watch --minutes 15</code>
598
+ </footer>
599
+ </main></body></html>"""
600
+ path.write_text(doc, encoding="utf-8")
601
+ return path
602
+
603
+
604
+ # ---------------------------------------------------------------- خط لوله
605
+ def run_pipeline(cfg: dict, store: Store, sources: list[str] | None = None) -> list[Item]:
606
+ collected: list[Item] = []
607
+ srcs = sources or [f"rss:{s.get('url')}" if s.get("type") == "rss" else s.get("type", "")
608
+ for s in cfg.get("sources", [])]
609
+ for spec in srcs:
610
+ kind, _, value = spec.partition(":")
611
+ if kind == "file":
612
+ collected.extend(load_file_source(value, cfg))
613
+ elif kind == "rss":
614
+ local = dict(cfg)
615
+ local["sources"] = [{"type": "rss", "name": "خبر", "url": value}]
616
+ collected.extend(fetch_rss(local))
617
+ elif kind == "codal":
618
+ collected.extend(fetch_codal(cfg))
619
+ elif kind == "demo":
620
+ collected.extend(load_file_source(str(BASE / "demo" / "announcements.json"), cfg))
621
+ collected.extend(parse_feed((BASE / "demo" / "news.rss").read_text(encoding="utf-8"), "خبر نمونه", cfg))
622
+ else:
623
+ log(f"منبع ناشناخته: {spec}")
624
+
625
+ fresh: list[Item] = []
626
+ for it in collected:
627
+ if it.score >= int(cfg.get("min_score_to_alert", 45)) or symbol_in_watchlist(it, cfg.get("watchlist", [])):
628
+ llm_enrich(it, cfg)
629
+ if store.add(it):
630
+ fresh.append(it)
631
+ store.commit()
632
+ store.log_run(",".join(srcs), len(fresh))
633
+ return sorted(fresh, key=lambda i: i.score, reverse=True)
634
+
635
+
636
+ def cmd_run(args) -> int:
637
+ cfg = load_config(args.config)
638
+ store = Store(cfg.get("db_path") or DEFAULT_DB)
639
+ items = run_pipeline(cfg, store, args.source)
640
+ notify(items, cfg)
641
+ path = build_report(store.recent(200), cfg, cfg.get("report_path") or DEFAULT_REPORT)
642
+ log(f"گزارش ساخته شد: {path}")
643
+ return 0
644
+
645
+
646
+ def cmd_watch(args) -> int:
647
+ cfg = load_config(args.config)
648
+ while True:
649
+ cmd_run(args)
650
+ log(f"خواب {args.minutes} دقیقه‌ای…")
651
+ try:
652
+ time.sleep(max(1, args.minutes) * 60)
653
+ except KeyboardInterrupt:
654
+ log("خارج شد.")
655
+ return 0
656
+
657
+
658
+ def cmd_report(args) -> int:
659
+ cfg = load_config(args.config)
660
+ store = Store(cfg.get("db_path") or DEFAULT_DB)
661
+ path = build_report(store.recent(args.limit), cfg, cfg.get("report_path") or DEFAULT_REPORT)
662
+ log(f"گزارش از پایگاه‌داده: {path} ({store.count()} رکورد)")
663
+ return 0
664
+
665
+
666
+ def cmd_import(args) -> int:
667
+ cfg = load_config(args.config)
668
+ store = Store(cfg.get("db_path") or DEFAULT_DB)
669
+ items = load_file_source(args.file, cfg)
670
+ fresh = [i for i in items if store.add(i)]
671
+ store.commit()
672
+ log(f"{len(fresh)} رکورد تازه از {len(items)} رکورد ورودی ثبت شد.")
673
+ notify(fresh, cfg)
674
+ return 0
675
+
676
+
677
+ def cmd_stats(args) -> int:
678
+ cfg = load_config(args.config)
679
+ store = Store(cfg.get("db_path") or DEFAULT_DB)
680
+ rows = store.conn.execute(
681
+ "SELECT category, COUNT(*), AVG(score) FROM items GROUP BY category ORDER BY COUNT(*) DESC").fetchall()
682
+ print(f"کل رکوردها: {store.count()}")
683
+ print(f"{'دسته':<24}{'تعداد':>8}{'میانگین امتیاز':>16}")
684
+ for cat, n, avg in rows:
685
+ print(f"{cat:<24}{n:>8}{avg:>16.1f}")
686
+ return 0
687
+
688
+
689
+ def cmd_selftest(args) -> int:
690
+ """آزمون سریع درون‌برنامه‌ای (بدون نیاز به unittest)."""
691
+ checks = 0
692
+ cat, direction, score, why = classify("افزایش سرمایه از محل تجدید ارزیابی دارایی‌ها", "")
693
+ assert cat == "افزایش سرمایه" and direction == "مثبت" and score >= 80, (cat, direction, score)
694
+ checks += 1
695
+ cat2, dir2, s2, _ = classify("اعلام توقف نماد به دلیل ابهام در اطلاعات", "")
696
+ assert cat2 == "توقف و بازگشایی نماد" and dir2 == "منفی", (cat2, dir2)
697
+ checks += 1
698
+ j = g2j(2026, 9, 22)
699
+ assert j == (1405, 6, 31), j
700
+ checks += 1
701
+ it = Item(title="تست")
702
+ assert len(it.key()) == 16
703
+ checks += 1
704
+ print(f"خودآزمون: {checks} بررسی موفق")
705
+ return 0
706
+
707
+
708
+ def cmd_demo(args) -> int:
709
+ args.source = ["demo"]
710
+ cfg = load_config(args.config)
711
+ cfg["db_path"] = str(BASE / "data" / "demo.sqlite3")
712
+ cfg["report_path"] = str(BASE / "data" / "demo-report.html")
713
+ store = Store(cfg["db_path"])
714
+ items = run_pipeline(cfg, store, ["demo"])
715
+ notify(items, cfg)
716
+ path = build_report(store.recent(200), cfg, cfg["report_path"])
717
+ log(f"گزارش نمونه ساخته شد: {path}")
718
+ return 0
719
+
720
+
721
+ # ---------------------------------------------------------------- CLI
722
+ def main(argv: list[str] | None = None) -> int:
723
+ ap = argparse.ArgumentParser(description="دیده‌بان اطلاعیه‌های کدال و خبر بازار سرمایه (بدون وابستگی بیرونی)")
724
+ ap.add_argument("--config", help="مسیر پروندهٔ تنظیمات JSON")
725
+ ap.add_argument("--db", help="مسیر پایگاه‌دادهٔ SQLite (پیش‌فرض: data/kodal.sqlite3)")
726
+ sub = ap.add_subparsers(dest="cmd")
727
+
728
+ p_run = sub.add_parser("run", help="یک بار اجرا")
729
+ p_run.add_argument("--source", action="append", help="منبع: demo | file:PATH | rss:URL | codal")
730
+ p_run.set_defaults(func=cmd_run)
731
+
732
+ p_watch = sub.add_parser("watch", help="اجرای دوره‌ای")
733
+ p_watch.add_argument("--minutes", type=int, default=15)
734
+ p_watch.add_argument("--source", action="append")
735
+ p_watch.set_defaults(func=cmd_watch)
736
+
737
+ p_rep = sub.add_parser("report", help="ساخت گزارش از پایگاه‌داده")
738
+ p_rep.add_argument("--limit", type=int, default=200)
739
+ p_rep.set_defaults(func=cmd_report)
740
+
741
+ p_imp = sub.add_parser("import", help="ورود اطلاعیه‌ها از پروندهٔ JSON یا CSV")
742
+ p_imp.add_argument("file")
743
+ p_imp.set_defaults(func=cmd_import)
744
+
745
+ sub.add_parser("stats", help="آمار دسته‌ها").set_defaults(func=cmd_stats)
746
+ sub.add_parser("demo", help="اجرای کامل روی دادهٔ نمونه").set_defaults(func=cmd_demo)
747
+ sub.add_parser("selftest", help="آزمون سریع").set_defaults(func=cmd_selftest)
748
+ sub.add_parser("version", help="نسخه").set_defaults(func=lambda a: (print(f"kodal-alert {VERSION}"), 0)[1])
749
+
750
+ args = ap.parse_args(argv)
751
+ if not getattr(args, "cmd", None):
752
+ ap.print_help()
753
+ return 0
754
+ if getattr(args, "db", None):
755
+ args.config = args.config
756
+ cfg_override = {"db_path": args.db}
757
+ original = load_config
758
+
759
+ def patched(path): # اعمال --db روی هر زیرفرمان
760
+ cfg = original(path)
761
+ cfg.update(cfg_override)
762
+ return cfg
763
+
764
+ globals()["load_config"] = patched
765
+ return int(args.func(args) or 0)
766
+
767
+
768
+ if __name__ == "__main__":
769
+ sys.exit(main())
kodal-alert/run-daily.bat ADDED
@@ -0,0 +1,7 @@
 
 
 
 
 
 
 
 
1
+ @echo off
2
+ chcp 65001 >nul
3
+ cd /d "%~dp0"
4
+ python kodal_alert.py run --source codal --source rss:https://www.farsnews.ir/rss
5
+ echo.
6
+ echo گزارش ساخته شد در data\report.html
7
+ timeout /t 5 >nul
kodal-alert/run-demo.bat ADDED
@@ -0,0 +1,5 @@
 
 
 
 
 
 
1
+ @echo off
2
+ chcp 65001 >nul
3
+ cd /d "%~dp0"
4
+ python kodal_alert.py demo
5
+ start "" "data\demo-report.html"
kodal-alert/tests/test_kodal_alert.py ADDED
@@ -0,0 +1,194 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env python3
2
+ # -*- coding: utf-8 -*-
3
+ """آزمون‌های واحد دیده‌بان کدال — فقط کتابخانهٔ استاندارد (unittest)."""
4
+ from __future__ import annotations
5
+
6
+ import json
7
+ import sys
8
+ import tempfile
9
+ import unittest
10
+ from datetime import datetime, timedelta, timezone
11
+ from pathlib import Path
12
+
13
+ sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
14
+
15
+ import kodal_alert as ka # noqa: E402
16
+
17
+
18
+ class TestClassify(unittest.TestCase):
19
+ def test_capital_increase_rule(self):
20
+ cat, direction, score, why = ka.classify("افزایش سرمایه از محل تجدید ارزیابی دارایی‌ها", "")
21
+ self.assertEqual(cat, "افزایش سرمایه")
22
+ self.assertEqual(direction, "مثبت")
23
+ self.assertGreaterEqual(score, 80)
24
+ self.assertIn("قرارداد مشتقه", why)
25
+
26
+ def test_halt_symbol_is_negative(self):
27
+ cat, direction, score, _ = ka.classify("توقف نماد به دلیل ابهام در اطلاعات", "")
28
+ self.assertEqual(cat, "توقف و بازگشایی نماد")
29
+ self.assertEqual(direction, "منفی")
30
+
31
+ def test_legal_risk_rule(self):
32
+ cat, direction, _, _ = ka.classify("دعوی حقوقی و جریمهٔ مالیاتی", "")
33
+ self.assertEqual(cat, "دعاوی و ریسک حقوقی")
34
+ self.assertEqual(direction, "منفی")
35
+
36
+ def test_lexicon_when_no_rule_matches(self):
37
+ cat, direction, score, _ = ka.classify("اطلاعیهٔ شمارهٔ ۱۲۳", "شرکت از رشد درآمد خبر داد")
38
+ self.assertEqual(cat, "سایر")
39
+ self.assertEqual(direction, "مثبت")
40
+ self.assertGreater(score, 0)
41
+
42
+ def test_numeric_bonus_increases_score(self):
43
+ _, _, s_plain, _ = ka.classify("انعقاد قرارداد جدید", "")
44
+ _, _, s_number, _ = ka.classify("انعقاد قرارداد جدید به ارزش ۱۲ میلیون یورو", "")
45
+ self.assertGreater(s_number, s_plain)
46
+
47
+ def test_recency_bonus_and_penalty(self):
48
+ now = datetime.now(timezone.utc)
49
+ _, _, fresh, _ = ka.classify("انعقاد قرارداد جدید", "", 1.0, now - timedelta(hours=2))
50
+ _, _, old, _ = ka.classify("انعقاد قرارداد جدید", "", 1.0, now - timedelta(days=6))
51
+ self.assertGreater(fresh, old)
52
+
53
+ def test_score_bounds(self):
54
+ for title in ["توقف نماد", "افزایش سرمایه", "", "خبر بی‌ربط"]:
55
+ _, _, score, _ = ka.classify(title, title * 3)
56
+ self.assertGreaterEqual(score, 0)
57
+ self.assertLessEqual(score, 100)
58
+
59
+ def test_source_weight(self):
60
+ _, _, s_norm, _ = ka.classify("توقف نماد", "", 1.0)
61
+ _, _, s_codal, _ = ka.classify("توقف نماد", "", 1.15)
62
+ self.assertGreaterEqual(s_codal, s_norm)
63
+
64
+
65
+ class TestDates(unittest.TestCase):
66
+ def test_jalali_known_dates(self):
67
+ self.assertEqual(ka.g2j(2026, 9, 22), (1405, 6, 31))
68
+ self.assertEqual(ka.g2j(2024, 1, 1), (1402, 10, 11))
69
+
70
+ def test_jalali_string_shape(self):
71
+ s = ka.jalali_str(datetime(2026, 9, 22, 8, 5))
72
+ self.assertTrue(s.startswith("1405/06/31"))
73
+
74
+
75
+ class TestStore(unittest.TestCase):
76
+ def test_insert_and_dedupe(self):
77
+ with tempfile.TemporaryDirectory() as tmp:
78
+ store = ka.Store(Path(tmp) / "t.sqlite3")
79
+ item = ka.Item(title="افزایش سرمایه", symbol="خساپا", score=80)
80
+ self.assertTrue(store.add(item))
81
+ self.assertFalse(store.add(item)) # همان کلید، بار دوم رد می‌شود
82
+ store.commit()
83
+ self.assertEqual(store.count(), 1)
84
+ rows = store.recent(10)
85
+ self.assertEqual(rows[0].title, "افزایش سرمایه")
86
+
87
+ def test_min_score_filter(self):
88
+ with tempfile.TemporaryDirectory() as tmp:
89
+ store = ka.Store(Path(tmp) / "t.sqlite3")
90
+ store.add(ka.Item(title="کم‌اهمیت", score=10))
91
+ store.add(ka.Item(title="مهم", score=90))
92
+ store.commit()
93
+ self.assertEqual(len(store.recent(10, min_score=50)), 1)
94
+
95
+ def test_run_log(self):
96
+ with tempfile.TemporaryDirectory() as tmp:
97
+ store = ka.Store(Path(tmp) / "t.sqlite3")
98
+ store.log_run("demo", 7)
99
+ n = store.conn.execute("SELECT COUNT(*) FROM runs").fetchone()[0]
100
+ self.assertEqual(n, 1)
101
+
102
+
103
+ class TestFeeds(unittest.TestCase):
104
+ def test_parse_demo_rss(self):
105
+ text = (Path(__file__).resolve().parents[1] / "demo" / "news.rss").read_text(encoding="utf-8")
106
+ items = ka.parse_feed(text, "خبر نمونه", ka.DEFAULT_CONFIG)
107
+ self.assertGreaterEqual(len(items), 4)
108
+ self.assertTrue(all(i.title for i in items))
109
+ self.assertTrue(any("توقف" in i.title or "بازگشایی" in i.title for i in items))
110
+
111
+ def test_bad_xml_returns_empty(self):
112
+ self.assertEqual(ka.parse_feed("<rss><channel>", "خراب", ka.DEFAULT_CONFIG), [])
113
+
114
+
115
+ class TestSources(unittest.TestCase):
116
+ def test_load_json_file(self):
117
+ with tempfile.TemporaryDirectory() as tmp:
118
+ p = Path(tmp) / "a.json"
119
+ p.write_text(json.dumps([{"title": "افزایش سرمایه", "symbol": "فولاد"}], ensure_ascii=False), encoding="utf-8")
120
+ items = ka.load_file_source(str(p), ka.DEFAULT_CONFIG)
121
+ self.assertEqual(len(items), 1)
122
+ self.assertEqual(items[0].category, "افزایش سرمایه")
123
+
124
+ def test_load_csv_file(self):
125
+ with tempfile.TemporaryDirectory() as tmp:
126
+ p = Path(tmp) / "a.csv"
127
+ p.write_text("title,symbol\nتوقف نماد,وبملت\n", encoding="utf-8")
128
+ items = ka.load_file_source(str(p), ka.DEFAULT_CONFIG)
129
+ self.assertEqual(items[0].direction, "منفی")
130
+
131
+ def test_missing_file_is_safe(self):
132
+ self.assertEqual(ka.load_file_source("/no/such/file.json", ka.DEFAULT_CONFIG), [])
133
+
134
+ def test_http_file_scheme(self):
135
+ with tempfile.TemporaryDirectory() as tmp:
136
+ p = Path(tmp) / "x.txt"
137
+ p.write_text("سلام", encoding="utf-8")
138
+ self.assertEqual(ka.http_get(f"file:{p}", ka.DEFAULT_CONFIG), "سلام")
139
+
140
+
141
+ class TestPipeline(unittest.TestCase):
142
+ def test_demo_pipeline_end_to_end(self):
143
+ with tempfile.TemporaryDirectory() as tmp:
144
+ cfg = json.loads(json.dumps(ka.DEFAULT_CONFIG, ensure_ascii=False))
145
+ cfg["db_path"] = str(Path(tmp) / "demo.sqlite3")
146
+ cfg["report_path"] = str(Path(tmp) / "report.html")
147
+ cfg["min_score_to_alert"] = 40
148
+ store = ka.Store(cfg["db_path"])
149
+ items = ka.run_pipeline(cfg, store, ["demo"])
150
+ self.assertGreaterEqual(len(items), 5)
151
+ scores = [i.score for i in items]
152
+ self.assertEqual(scores, sorted(scores, reverse=True))
153
+ path = ka.build_report(store.recent(100), cfg, cfg["report_path"])
154
+ body = path.read_text(encoding="utf-8")
155
+ self.assertIn('dir="rtl"', body)
156
+ self.assertIn("دیده‌بان", body)
157
+ self.assertIn(items[0].title[:20], body)
158
+
159
+ def test_report_has_no_external_assets(self):
160
+ cfg = ka.DEFAULT_CONFIG
161
+ with tempfile.TemporaryDirectory() as tmp:
162
+ path = ka.build_report([ka.Item(title="نمونه", score=50)], cfg, Path(tmp) / "r.html")
163
+ body = path.read_text(encoding="utf-8")
164
+ self.assertNotIn("http://cdn", body)
165
+ self.assertNotIn("<script", body)
166
+ self.assertNotIn("fonts.googleapis", body)
167
+
168
+ class TestTitlePriority(unittest.TestCase):
169
+ def test_title_beats_body_noise(self):
170
+ cat, _, _, _ = ka.classify("شفاف‌سازی در خصوص نوسان قیمت سهم",
171
+ "شرکت اعلام کرد برنامهٔ افزایش سرمایه در دست بررسی است", 1.0)
172
+ self.assertEqual(cat, "شفاف‌سازی")
173
+
174
+ def test_reopening_is_positive(self):
175
+ cat, direction, _, _ = ka.classify("بازگشایی نماد پس از شفاف‌سازی", "")
176
+ self.assertEqual(cat, "توقف و بازگشایی نماد")
177
+ self.assertEqual(direction, "مثبت")
178
+
179
+ def test_dividend_not_misread_as_halt(self):
180
+ cat, _, _, _ = ka.classify("تقسیم سود نقدی هر سهم و زمان برگزاری مجمع",
181
+ "تاریخ توقف نماد پیش از مجمع اعلام خواهد شد", 1.0)
182
+ self.assertEqual(cat, "تقسیم سود")
183
+
184
+
185
+ class TestCli(unittest.TestCase):
186
+ def test_selftest_command(self):
187
+ self.assertEqual(ka.main(["selftest"]), 0)
188
+
189
+ def test_version_command(self):
190
+ self.assertEqual(ka.main(["version"]), 0)
191
+
192
+
193
+ if __name__ == "__main__":
194
+ unittest.main(verbosity=2)
render.yaml ADDED
@@ -0,0 +1,25 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # میزبان مجانی جایگزین (Render) — کارآمد، ولی ضعیف‌تر از Hugging Face.
2
+ # ۵۱۲ مگ رم و ۰٫۱ پردازنده · بعد از ۱۵ دقیقه بی‌کاری می‌خوابد (بیدار شدن ۳۰ تا ۶۰ ثانیه) ·
3
+ # دیسک ماندگار ندارد (داده با هر بازسازی پاک می‌شود) · کارت بانکی نمی‌خواهد.
4
+ #
5
+ # راه: کد را روی یک مخزن GitHub بگذار (همان بستهٔ iran-desk-hf) و در Render گزینهٔ
6
+ # «New → Blueprint» را بزن و همین پرونده را انتخاب کن. بعد رمزها را در Environment بگذار.
7
+ services:
8
+ - type: web
9
+ name: iran-desk-station
10
+ runtime: docker
11
+ plan: free
12
+ dockerfilePath: ./Dockerfile
13
+ healthCheckPath: /login
14
+ autoDeploy: false
15
+ envVars:
16
+ - key: STATION_ADMIN_ID
17
+ value: mafhoom
18
+ - key: STATION_ADMIN_PASS
19
+ sync: false # در داشبورد خودت پرش کن؛ در مخزن نوشته نمی‌شود
20
+ - key: STATION_GUEST_ID
21
+ value: masoud
22
+ - key: STATION_GUEST_PASS
23
+ sync: false
24
+ - key: STATION_GUEST_OFF
25
+ value: "0"
station/DEMO-INVESTOR-FA.md ADDED
@@ -0,0 +1,295 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # دموی سرمایه‌گذار، چطور ارزش برنامه را در بیست‌وپنج دقیقه نشان بدهیم
2
+
3
+ این پرونده برای این نوشته شده که شما با یک رایانه و **بدون پرداخت هیچ هزینه‌ای**، جلوی
4
+ سرمایه‌گذار بنشینید و بگذارید خودش برنامه را بچرخاند. راستش را هم می‌گوید: می‌گوید چه چیزی
5
+ ارزش است، چه چیزی نیست، و کجا باید صادقانه بگویید «نمی‌دانم».
6
+
7
+ ---
8
+
9
+ ## بخش ۰. پاسخ کوتاه به چهار پرسش شما
10
+
11
+ **۱. برای این کار باید Jev بخرم؟** نه. Jev دادهٔ بازار نمی‌فروشد؛ دسترسی به یک مدل است.
12
+ ایستگاه برای کارکرد کامل (محاسبه، دروازهٔ ریسک، پس‌آزمایی، دفتر آزمون) هیچ مدل زبانی لازم ندارد.
13
+ لایهٔ مدل فقط یک کار اضافه دارد: خلاصه‌کردن متن خبر. اگر بعداً خواستید، رایگان هم ممکن است
14
+ (بخش ۷). الان برای دموی سرمایه‌گذار، **صفر ریال** لازم است.
15
+
16
+ **۲. پس چه چیزی بخرم؟** برای نمایش، هیچ. برای کار جدی روی دادهٔ واقعی، فقط یک چیز:
17
+ سرویس دادهٔ زنده (بخش ۷). اگر نخرید هم برنامه کار می‌کند، ولی قیمت‌ها دستی یا رایگان می‌مانند.
18
+
19
+ **۳. چطور بدون هزینه، تست عملیاتی واقعی بگیرم؟** سه راه رایگان در بخش ۱، و یک آزمون
20
+ دو هفته‌ای بی‌پول در بخش ۶. آزمون دو هفت‌ای همان چیزی است که سرمایه‌گذار را قانع می‌کند،
21
+ نه اسلاید.
22
+
23
+ **۴. چطور بگذارم خودش امتحان بگیرد؟** دو کارت تازه در گام ۹:
24
+ «اجرای آزمون ۱۰ دقیقه‌ای» که پانزده مورد را دو بار حساب می‌کند (موتور برنامه و حساب دستی مستقل)،
25
+ و «ساخت پروندهٔ سرمایه‌گذار» که همهٔ شاهدها را در یک فایل آمادهٔ چاپ می‌ریزد. بخش ۹ همین را
26
+ گام‌به‌گام توضیح می‌دهد.
27
+
28
+ ---
29
+
30
+ ## بخش ۰.۵. چند ثانیهٔ اول: بگویید هزینهٔ داده صفر است
31
+
32
+ پیش از هر چیز بگویید: «تا امروز یک ریال هم برای داده نداده‌ام.» بعد در گام ۲ جدول «وارد کردن اعداد
33
+ کارگزاری» را باز کنید و بگویید این ده عدد را خودم از سامانهٔ کارگزاری برداشته‌ام و همه مجانی است
34
+ (راهنمای کامل: `MATERIALS/money/10-daily-inputs-fa.md`). برای سرمایه‌گذار باتجربه این جمله از هر
35
+ نموداری قوی‌تر است: یعنی ریسک پیاده‌سازی و هزینهٔ پنهان ندارد.
36
+
37
+ ## بخش ۱. سه راه رایگان برای اینکه سرمایه‌گذار دادهٔ زنده ببیند
38
+
39
+ ### راه ۱. خوراک آزمایشی محلی (صفر ریال، صفر اینترنت)
40
+ در پوشهٔ ایستگاه، `run-investor-demo.bat` را دوبار کلیک کنید یا در ترمینال بزنید:
41
+
42
+ ```
43
+ python web_server.py --port 8765
44
+ ```
45
+
46
+ خوراک آزمایشی خودش بالا می‌آید و در گام ۲ پروفایل «خوراک آزمایشی محلی» یک کلیک است.
47
+ **چه چیزی را ثابت می‌کند:** کل مسیر فنی دادهٔ زنده کار می‌کند؛ نوار تازگی سبز می‌شود، قیمت‌ها
48
+ هر ثانیه عوض می‌شوند، سیگنال‌ها به‌روز می‌شوند، دفتر آزمون پر می‌شود.
49
+ **چه چیزی را ثابت نمی‌کند:** هیچ ادعای درآمدی. این قیمت‌ها ساختگی‌اند و برنامه هم همه‌جا
50
+ همین را با برچسب «خوراک آزمایشی محلی (ساختگی)» نشان می‌دهد. همین برچسب، خودش یک امتیاز است:
51
+ برنامه‌ای که دادهٔ ساختگی را ساختگی صدا می‌زند، دادهٔ واقعی را هم واقعی می‌داند.
52
+
53
+ ### راه ۲. پروفایل‌های رایگان با قیمت واقعی (بدون کلید، بدون پرداخت)
54
+
55
+ **سریع‌ترین راه:** در گام ۲ دکمهٔ «بگرد و گزارش بده» را بزنید. برنامه خودش چند منبع رایگان را
56
+ امتحان می‌کند و می‌گوید کدام امروز کار می‌کند و بقیه چرا نه. در آزمون واقعی سازنده، یکی از این
57
+ منابع پاسخ سالم داد (نرخ لحظه‌ای ریالی از یک بازار واقعی) و با یک دکمه ذخیره و فعال شد.
58
+ این لحظه را جلوی سرم��یه‌گذار حتماً نشان بدهید: برنامه بدون هیچ کلیدی، خودش اتصال زنده می‌سازد.
59
+ در گام ۲، سه پروفایل رایگان آماده است: tgju برای دلار و طلا و سکه، tsetmc برای قیمت پایانی
60
+ سهام و آپشن، و یک صرافی ایرانی برای نرخ لحظه‌ای ریالی. هیچ‌کدام کلید نمی‌خواهند.
61
+
62
+ اگر ساختار پاسخ سرویس عوض شده بود، **کاوشگر پاسخ** کار را در یک دقیقه تمام می‌کند:
63
+ نشانی را در کادر بگذارید، دکمه را بزنید، و از فهرست عددهایی که پیدا می‌شود روی «استفاده» بزنید
64
+ تا مسیر درست خودش پر شود. این لحظه برای سرمایه‌گذار فنی، خودش یک نمایش است: برنامه به‌جای
65
+ حدس‌زدن، از سرویس می‌پرسد.
66
+
67
+ ### راه ۳. دادهٔ دستی از سامانهٔ کارگزاری خودتان (دقیق‌ترین)
68
+
69
+ برای این کار لازم نیست JSON بنویسید: در گام ۲ جدول «وارد کردن اعداد کارگزاری» را پر کنید و
70
+ «ذخیرهٔ اسنپ‌شات امروز» را بزنید. پرونده با تاریخ همان روز ذخیره می‌شود و روز «واقعی» حساب می‌شود
71
+ (با تیک تأیید). این سریع‌ترین راه پر کردن پنج روز واقعیِ کارنامه بدون خرید هیچ سرویسی است.
72
+ پروندهٔ JSON قالب را با اعداد واقعی همان روز پر کنید: قیمت پایه، آتی، زنجیرهٔ آپشن، تبعی، و
73
+ **وجه تضمین هر قرارداد از سامانهٔ کارگزاری**. این حالت از همه دقیق‌تر است، چون آن عددی که فقط
74
+ کارگزاری می‌داند، از خود کارگزاری می‌آید. برای راستی‌آزمایی شرکت هم همین را تحویل بدهید.
75
+
76
+ ---
77
+
78
+ ## بخش ۲. چه چیزی سرمایه‌گذار را شگفت‌زده می‌کند (و چه چیزی نه)
79
+
80
+ ### شش لحظهٔ «آها»، با آدرس دقیق
81
+ ۱. **حساسیت به کارمزد.** در گام ۳، کارمزد خرید و فروش را از مقدار واقعی به دو درصد برسانید و
82
+ گام ۵ را دوباره بزنید. ببینید چطور سیگنال‌ها یکی‌یکی محو می‌شوند. اینجا سرمایه‌گذار می‌فهمد
83
+ برنامه دنبال «فرصت کاغذی» نیست؛ فرصتی می‌خواهد که بعد از کارمزد باقی بماند.
84
+ ۲. **نرخ سد.** نرخ سد را از ۳۹ درصد به ۶۰ ببرید: همه‌چیز رد می‌شود. توضیح بدهید: نرخ سد، همان
85
+ بازده بی‌دردسر صندوق درآمد ثابت است؛ تا وقتی فرصتی از آن بیشتر ندهد، معامله‌کردن ضرر است.
86
+ ۳. **درآوردن بازده از قیمت‌های ظاهراً بی‌ربط.** در گام ۶، جزئیات ریاضی یک سیگنال را باز کنید:
87
+ مبنا، نرخ بهرهٔ ضمنی، بازده تبعی. سرمایه‌گذار عددهای بازار را می‌شناسد؛ وقتی ببیند برنامه از
88
+ همان عددها یک بازده سالانه درمی‌آورد، جدی می‌گیرد.
89
+ ۴. **امتناع از ساختن عدد.** در گام ۲، نشانی سرویس را عمداً خراب کنید و آزمایش بگیرید.
90
+ برنامه دادهٔ کهنه را «تازه» جا نمی‌زند و نوار تازگی قرمز می‌شود. بیشترین اعتماد از همین‌جا می‌آید.
91
+ ۵. **صداقت عدد پس‌آزمایی.** در گام ۷، عدد «خطای پیش‌بینی» منفی را نشان بدهید و بگویید:
92
+ «این یعنی موتور خوش‌بین است و ما کف حاشیه را بالا بردیم.» برنامه‌ای که ضعف خودش را نشان می‌دهد،
93
+ برای شرکت قابل اتکاتر از برنامه‌ای است که همه‌چیز را سبز نشان می‌دهد.
94
+ ۶. **دفتر آزمون زنده و زنجیرهٔ هش.** در گام ۹ سیگنال‌های امروز را ثبت کنید، بعد دکمهٔ
95
+ «بررسی زنجیرهٔ هش» را بزنید و بگویید: «هر ردیف هشِ ردیف قبلی را در خود دارد؛ اگر فردا کسی
96
+ عددی را عوض کند، زنجیره می‌شکند.» بعد گزارش را بسازید و همان‌جا به سرمایه‌گذار تحویل بدهید.
97
+
98
+ ### چه چیزی را نگویید
99
+ سود تضمینی، معاملهٔ خودکار بدون انسان، پیش‌بینی قیمت، یا «فقط ریاضیات، بدون ریسک».
100
+ این چهار حرف در ایران هم غیرقانونی است هم قابل رد کردن: معاملات الگوریتمی خود��ار از مهر ۱۳۹۹
101
+ ممنوع اعلام شده و فقط کارگزاران دارای مجوز اجازهٔ سفارش‌گذاری خودکار دارند.
102
+
103
+ ---
104
+
105
+ ## بخش ۳. سناریوی بیست‌وپنج‌دقیقه‌ای، دقیقه به دقیقه
106
+
107
+ | دقیقه | چه کاری | چه بگویید |
108
+ | --- | --- | --- |
109
+ | ۰ تا ۲ | `run-investor-demo.bat` را باز کنید، گام ۱: «باز کردن پنل مدیریت» و «بررسی سلامت برنامه» | «هشت بخش برنامه را چک می‌کند تا معلوم شود چیزی جا نیفتاده؛ پنل با شناسه و رمز باز می‌شود.» |
110
+ | ۲ تا ۴ | گام ۲: پروفایل «خوراک آزمایشی محلی» را انتخاب و آزمایش کنید | «قیمت زنده می‌آید، بدون هزینه و بدون کلید. این خوراک ساختگی است و خودش هم می‌گوید.» |
111
+ | ۴ تا ۶ | گام ۵: «شروع محاسبه» | «هفت ردیف می‌شود؛ سه‌تا منتظر تأیید، چهارتا رد شده با دلیل.» |
112
+ | ۶ تا ۸ | گام ۳: کارمزد را به ۲ درصد ببرید، گام ۵ را دوباره بزنید | «ببینید چند سیگنال محو شد. برنامه دنبال فرصت واقعی است، نه فرصت کاغذی.» |
113
+ | ۸ تا ۱۰ | گام ۶: یک سیگنال را تأیید کنید، بستهٔ سفارش را ببینید | «تصمیم نهایی مال انسان است؛ برنامه فقط بستهٔ سفارش می‌سازد.» |
114
+ | ۱۰ تا ۱۴ | **گام ۶، کارت «داوری سیگنال ابزارهای دیگر»**: نوع راهبرد را انتخاب کنید، «نمونهٔ آماده»، «داوری کن و برگه بساز». بعد عددهای سیگنال امروزِ ابزار خودش را وارد کنید | «سیگنال نرم‌افزار فعلی‌تان را بدهید؛ در چند ثانیه می‌بینیم با کارمزد و ریسک واقعی می‌مانَد یا می‌افتد، تا چه قیمتی می‌مانَد، و چقدر تا اخطاریهٔ مارجین فاصله دارید.» |
115
+ | ۱۴ تا ۱۶ | گام ۷: پس‌آزمایی روی تاریخ نمونه | «خطای پیش‌بینی منفی است. این را برای شرکت می‌نویسیم، پنهان نمی‌کنیم.» |
116
+ | ۱۶ تا ۱۷ | گام ۹: ثبت، بازسنجی، بررسی زنجیره | «حالا دفتر دارد. دو هفته دیگر همین را باز کنیم و ببینیم بازار چه کرد.» |
117
+ | ۱۷ تا ۲۰ | گام ۱۰: «نمایش پرسش‌ها»، بعد لپ‌تاپ را به خودش بدهید: حدس بزند، «داوری حدس‌های من» را بزند | «شما اول حدس بزنید؛ بعد برنامه پاسخ را با فرمول نشان می‌دهد تا خودتان با ماشین‌حساب چک کنید.» |
118
+ | ۲۰ تا ۲۲ | گام ۱۰: یک معاملهٔ گذشتهٔ خودش را در کارت «حساب‌رسی واقعیت» وارد کنید | «عدد کارگزاری خودتان؛ کارمزد کم می‌شود و نتیجهٔ واقعی همان‌جا درمی‌آید.» |
119
+ | ۲۲ تا ۲۴ | گام ۸: «ساخت بستهٔ راستی‌آزمایی»، بعد نام شرکت را بنویسید و «ساخت پیشنهاد یک‌صفحه‌ای» | «یک صفحه، بدون وعدهٔ سود: چه چیزی تحویل می‌شود، چطور خودتان راستی‌آزمایی می‌کنید، و قیمت توافقی. همین برگه را ببرید.» |
120
+ | ۲۴ تا ۲۵ | پوشهٔ بسته را به او بدهید؛ برگهٔ آزمون کور را چاپ و امضا کنید | «داخل بسته، سند مجوز و گواهی استفاده هم خودکار آمده — با اثر انگشت. پوشه را بدهید؛ تمام.» |
121
+ | اگر وقت داشت | گام ۹، کارت ۴: «اجرای آزمون ۱۰ دقیقه‌ای» و بعد دکمهٔ «برگهٔ آزمون چاپی» | «بگذارید خودتان دو موردش را با ماشین‌حساب چک کنید. اگر با هم نخواند، همان‌جا می‌بینید.» |
122
+ | آخرین کار | گام ۹، کارت ۵: «ساخت پروندهٔ سرمایه‌گذار» و دادن همان فایل | «این پرونده را ببرید؛ اثر انگشت تک‌تک پرونده‌ها داخلش است.» |
123
+
124
+ اگر سرمایه‌گذار خودش پشت رایانه نشست، بگذارید همین یک دکمه را هم بزند: «اجرای مراسم امروز» در گام ۹.
125
+ دیدن اینکه یک دکمه هم قیمت می‌خواند، هم ثبت می‌کند، هم کارنامه را به‌روز می‌کند، از ده دقیقه اسلاید
126
+ بیشتر اثر دارد.
127
+
128
+ **نکتهٔ مهم:** بگذارید خودش دکمه بزند. معدل اعتماد وقتی بالا می‌رود که دست خودش روی برنامه باشد،
129
+ نه وقتی شما نمایش می‌دهید.
130
+
131
+ ---
132
+
133
+ ## بخش ۴. انصاف علمی: چرا «عدد شگفت‌انگیز» کم پیدا می‌شود
134
+
135
+ بازار تا حد زیادی کارآمد است: هرکس این تفاوت قیمت را ببیند، سریع معامله می‌کند و تفاوت بسته می‌شود.
136
+ پس انتظار نداشته باشید برنامه هر روز بازده‌های بزرگ نشان بدهد. ارزش برنامه در چهار چیز است:
137
+
138
+ ۱. **سرعت پایش:** کاری که دستی نیم ساعت طول می‌کشد، در چند ثانیه با همهٔ نمادها حساب می‌شود.
139
+ ۲. **دقت پس از کارمزد:** حاشیه‌ای که بعد از کسر کارمزد و اسپرد می‌ماند، معیار واقعی است.
140
+ ۳. **انضباط ریسک:** سقف وجه تضمین، سقف هر موقعیت،کف نقدشوندگی، و دروازهٔ «باورپذیری» که
141
+ عددهای مسخره (بالای ۲۵۰ و ۴۰۰ درصد) را به‌جای تأیید، به‌عنوان خطای داده بیرون می‌اندازد.
142
+ ۴. **ممیزی:** دفتر ثبت‌شده با تاریخ و هش، بستهٔ راستی‌آزمایی برای شرکت، و گزارش دفتر آزمون زنده.
143
+
144
+ اگر سرمایه‌گذار بپرسد «خب سودش چقدر است؟» پاسخ صادقانه این است:
145
+ «این برنامه سود نمی‌سازد؛ **بازده را با حساب‌وکتاب نشان می‌دهد و جلوی معاملهٔ بد را می‌گیرد**.
146
+ عدد سود را فقط بازار می‌دهد و باید با آزمون بی‌پول دو هفته‌ای سنجیده شود.»
147
+
148
+ ---
149
+
150
+ ## بخش ۵. اگر سرمایه‌گذار پرسید، پاسخ‌های آماده
151
+
152
+ | پرسش | پاسخ کوتاه |
153
+ | --- | --- |
154
+ | خودش معامله می‌کند؟ | نه. بستهٔ سفارش می‌سازد؛ اجرا با انسان در سامانهٔ کارگزاری. سفارش خودکار در ایران ممنوع است. |
155
+ | داده را از کجا می‌آورد؟ | سه حالت: نمونه، پروندهٔ دستی شما، یا سرویس زنده. برنامه منبع را همیشه روی صفحه نشان می‌دهد. |
156
+ | اگر سرویس قطع شود؟ | از حافظهٔ نهان کار می‌کند، ستون تازگی زرد یا قرمز می‌شود، و هیچ عددی را جعل نمی‌کند. |
157
+ | وجه تضمین را از کجا می‌داند؟ | از شما؛ چون فقط سامانهٔ کارگزاری این عدد را می‌دهد. |
158
+ | پول من در خطر است؟ | در حالت آزمون بی‌پول، هیچ سفارشی ارسال نمی‌شود. سرمایهٔ درگیر فقط عدد محاسبه است. |
159
+ | چند نفر لازم است؟ | یک نفر با نظارت خودتان. |
160
+ | چه چیزی الان کم دارد؟ | کلید سرویس دادهٔ زنده، و دو هفته سابقهٔ ثبت‌شده. هر دو در همین برنامه انجام می‌شود. |
161
+ | چرا سابقه هنوز خالی است؟ | چون امروز اولین روزش است. برای همین هست که از امروز شروع می‌کنیم، نه از فردا. |
162
+
163
+ ---
164
+
165
+ ## بخش ۶. آزمون بی‌پول دو هفته‌ای، پروتکل دقیق
166
+
167
+ هدف: ساختن «سابقهٔ ثبت‌شده» بدون اینکه یک ریال معامله شود. این همان چیزی است که در جلسهٔ دوم
168
+ ارائه، کار می‌کند.
169
+
170
+ **کل دوره در یک دکمه خلاصه شده است.** هر روز کاری فقط «اجرای مراسم امروز» را بزنید (یا دوبار کلیک
171
+ روی `run-daily-trial.bat`، یا بگذارید `schedule-daily-trial.bat` خودش هر روز اجرا کند). برنامه
172
+ خودش قیمت تازه می‌خواند، محاسبه می‌کند، در دفتر ثبت می‌کند، ردیف‌های قبلی را بازسنجی می‌کند، زنجیره را
173
+ بررسی می‌کند، گزارش را از نو می‌سازد و کارنامه را به‌روز می‌کند.
174
+
175
+ - **روز ۱:** دادهٔ امروز را بگذارید (رایگان یا دستی)، گام ۵، بعد گام ۹ و دکمهٔ «ثبت سیگنال‌های گام ۵».
176
+ - **روزهای بعد، سر هر روز کاری:** گام ۹ و دکمهٔ «خواندن قیمت‌های تازه و بازسنجی دفتر». مهم نیست
177
+ بازار حرکت کرده یا نه؛ ثبت همان تغییر است که ارزش دارد.
178
+ - **روز ۱۴:** «ساخت گزارش سرمایه‌گذار»، بعد دکمهٔ «بررسی زنجیرهٔ هش»، و گزارش را برای شرکت ببرید.
179
+
180
+ **کارنامه خودش می‌گوید چه زمانی آماده‌اید.** پنج شرط عددی، و تا همه جور نشود و «هنوز نه» می‌گوید، در جلسه
181
+ ادعای آمادگی نکنید: ده روز ثبت‌شده، پنج روز با دادهٔ واقعی (نه خوراک ساختگی)، شصت درصد دفتر
182
+ بازسنجی‌شده، سه حرکت معنادار در دفتر (دست‌کم یکی بازتر و یکی بسته)، و زنجیرهٔ هش سالم.
183
+ پرونده‌های نمونه هم روز واقعی حساب نمی‌شوند؛ پس «واقعی» یعنی یا قیمت زنده از سرویس، یا پروندهٔ
184
+ دستی که خودتان از سامانهٔ کارگزاری پر کرده‌اید.
185
+ وقتی کارنامه «آماده» شد، آن‌وقت خرید دادهٔ زنده معنی دارد.
186
+
187
+ معیار موفقیت آزمون این‌هاست، نه سود:
188
+
189
+ ۱. برنامه هر روز کاری داده‌ای داشته و عدد ساخته، بدون دخالت شما.
190
+ ۲. بسیاری از سیگنال‌ها بعد از یک یا دو روز «کم شد» یا «زیر کف رفت»، یعنی موتور فرصت‌های زودگذر را
191
+ درست شناسایی کرده، نه اینکه ثابت بماند.
192
+ ۳. حداقل یک مورد برعکس: سیگنال تأییدشده‌ای که فرصتش «بازتر شد»؛ این نشان می‌دهد فیلترها
193
+ خلوت‌گر نبوده‌اند.
194
+ ۴. زنجیره در پایان دوره سالم باشد.
195
+
196
+ اگر بعد از دو هفته هر چهار مورد جور بود، آن‌وقت خرید سرویس دادهٔ زنده معنی دارد: چون دلیلی
197
+ دارید، نه امیدی.
198
+
199
+ ---
200
+
201
+ ## بخش ۷. اگر خواستید جدی‌تر شود: چه بخرید، چه نخرید
202
+
203
+ | چه چیزی | برای چه کاری | هزینهٔ تقریبی |
204
+ | --- | --- | --- |
205
+ | سرویس دادهٔ زندهٔ ایرانی | قیمت زنده همهٔ نمادها + دادهٔ تاریخی برای پس‌آزمایی | از چند صد هزار تومان در ماه شروع می‌شود؛ در سایت فروشنده تأیید کنید |
206
+ | Jev (TypeSafe) | فقط لایهٔ زبانی: خلاصه و توضیح متون خبری | آن را برای دادهٔ بازار نخرید؛ دادهٔ بازار نمی‌دهد |
207
+ | مدل محلی روی رایانهٔ خودتان | همان کار بالا، ولی رایگان و آفلاین | صفر ریال؛ فقط کمی وقت نصب |
208
+ | هیچ‌چیز | شروع، آزمایش، و ساختن سابقه | صفر ریال |
209
+
210
+ برای پرداخت‌های ارزی هم به یاد داشته باشید: از داخل ایران کارت بین‌المللی مستقیم کار نمی‌کند و
211
+ راه‌های واسط ریسک خودشان را دارند؛ پس هر خریدی که «کلید ایرانی» می‌خواهد، بی‌دردسرتر است.
212
+
213
+ ---
214
+
215
+ ## بخش ۸. چه پرونده‌هایی را دست سرمایه‌گذار بدهید
216
+
217
+ ۱. **پروندهٔ سرمایه‌گذار** `data/investor-dossier.html` (دکمهٔ گام ۹ یا `build-dossier.bat`):
218
+ قواعد قفل‌شده، شاهد آزمون، دفتر و کارنامه، پس‌آزمایی، محدودیت‌ها، چهار گام راستی‌آزمایی مستقل،
219
+ و اثر انگشت هر پرونده. همین یک فایل را بدهید و بقیه را ضمیمه کنید.
220
+ ۲. **کارنامهٔ آزمون** `data/selftest-report.html` و **برگهٔ آزمون** `data/exam-sheet.html`.
221
+ ۳. **برگهٔ «پیشنهاد یک‌صفحه‌ای»** (`data/offer-one-pager.html` و نسخهٔ متنی‌اش): دکمه‌اش در گام ۸ است؛
222
+ نام شرکت را می‌نویسید و چاپ می‌کنید. مسئله، سه چیزی که اضافه می‌شود، پله‌های ارائه، مرزها و
223
+ «چطور خودتان راستی‌آزمایی کنید» در یک صفحه — قیمت اگر عدد ندهید «توافقی» می‌ماند.
224
+ ۴. پوشهٔ `export/bundle-…` که گام ۸ می‌سازد: داشبورد، فهرست سیگنال‌ها، سند روش کار با چک‌لیست
225
+ نه‌گامی، بسته‌های سفارش، گزارش پس‌آزمایی، شناسنامهٔ فنی، راهنمای دسکتاپ، و دو سند اداری که
226
+ ایستگاه خودش می‌سازد: **سند چاپی اجازه‌نامه** (`15/16`) و **گواهی استفادهٔ موفق** (`17/18`).
227
+ اگر مجوزی صادر نشده باشد، ایستگاه در یادداشتِ بسته همین را می‌گوید تا چیزی جا نماند.
228
+ ۵. گزارش دفتر آزمون زنده `data/trial-report.html` و پروندهٔ CSV همان دفتر.
229
+ ۶. این پرونده، به‌عنوان متن گفتگوی شما با او.
230
+
231
+ ## بخش ۹. چطور «اثبات» کنیم برنامه واقعاً کار می‌کند (و چه چیزی اثبات نمی‌شود)
232
+
233
+ **آزمون کور، قوی‌ترین بخش اثبات.** در گام ۱۰ شش پرسش هست و پاسخ‌ها تا لحظهٔ د��وری پنهان است.
234
+ سرمایه‌گذار حدس می‌زند، برنامه پاسخ می‌دهد، و برای هر پاسخ «فرمول» و «روش دوم» نوشته می‌شود تا
235
+ با ماشین‌حساب جیبی قابل بازبینی باشد. این جلسه در دفتر زنجیره‌هش‌دار ثبت می‌شود و در پایان،
236
+ برگهٔ چاپی با جای امضا ساخته می‌شود; اگر کسی بعداً عددی را عوض کند، کلید زنجیره می‌شکند و برگه باطل می‌شود.
237
+
238
+ **و آنچه اثبات نمی‌شود:** اینکه «سال بعد هم همین‌قدر سود می‌شود». هیچ‌جای این برنامه چنین وعده‌ای
239
+ نمی‌دهد؛ همهٔ عددها حسابِ امروز است. برای همین «دفتر آزمون زنده» ساخته شده: ده روز بعد،
240
+ هم شما و هم او می‌بینید بازار چه کرد و برنامه چه گفت.
241
+
242
+ **سند همراه:** `07-zero-cost-test-fa.md` (در پوشهٔ `MATERIALS/money/`) پاسخ همان پرسش «باید چیزی
243
+ بخریم؟» است: هیچ‌چیز، و سه مسیر تست بیهزینه با پروتکل ده‌روزه.
244
+
245
+
246
+ پنج شاهد که هرکدام را می‌شود بی‌نیاز از اعتماد به ما بازبینی کرد:
247
+
248
+ | شاهد | چطور خودش بازبینی کند |
249
+ | --- | --- |
250
+ | **دو محاسبهٔ مستقل** | «کارنامهٔ آزمون» هر مورد را با موتور برنامه و با حساب دستی حساب می‌کند؛ فرمول دستی همان‌جا نوشته شده. با ماشین‌حساب می‌شود چک کرد |
251
+ | **دفتر جعل‌ناپذیر** | هر ردیف دفتر هشی دارد که به ردیف قبل زنجیر است؛ با `python live_trial.py --verify` هر دست‌کاری لو می‌رود |
252
+ | **بدون آینده‌نگری** | در آزمون، ستون «نتیجهٔ واقعی گذشته» پنج برابر می‌شود و هیچ تصمیمی عوض نمی‌شود؛ یعنی تصمیم از آینده تقلب نمی‌گیرد |
253
+ | **صداقت در نبود داده** | اگر سرویس جواب ندهد، برنامه «نیامد» می‌گوید و تازگی را «نامعلوم» می‌گذارد؛ عدد ساختگی جای قیمت زنده نمی‌نشیند |
254
+ | **تکرارپذیری** | یک ورودی، یک جواب، همیشه؛ اثر انگشت موتور ریاضی در کارنامه و پرونده نوشته می‌شود |
255
+
256
+ و آنچه **اثبات نمی‌شود**: اینکه این معامله‌ها سود می‌دهند. سود به قیمت اجرا، نقدشوندگی،
257
+ کارمزد واقعی کارگزاری و شرایط بازار بسته است. برنامه سرعت، نظم، حساب‌وکتاب و سابقه می‌دهد؛
258
+ سود را وعده نمی‌دهد و نمی‌تواند بدهد. همین جمله را بلند بگویید؛ اعتماد از همین‌جا می‌آید.
259
+
260
+ ## جملهٔ پایانی که پیشنهاد می‌کنم بگویید
261
+
262
+ «من ادعا نمی‌کنم سود تضمینی دارم. من یک ماشین حساب دقیق و یک دفتر ثبت‌شده دارم که نشان می‌دهد
263
+ کجا فرصت هست، کجا نیست، و هر روز چه چیزی عوض شده. بیایید دو هفته با داده واقعی و بدون پول
264
+ اجرا کنیم؛ بعد خودتان تصمیم بگیرید.»
265
+
266
+ ✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · 📱 [+989126630554](tel:+989126630554) · ✈️ [Telegram: Mojarabian](https://t.me/Mojarabian) · 📸 [Instagram: Mojarabian.Art](https://instagram.com/Mojarabian.Art)
267
+
268
+ ## بخش ۱۰. آزمون کور، پلهٔ تصمیم و پیمان‌نامه — سه چیزی که در گام ۱۰ ساخته می‌شود
269
+
270
+ در **گام ۱۰** رابط مرورگری سه پرونده ساخته می‌شود؛ هر سه برای روز نمایش است و هر سه محلی است
271
+ (هیچ‌چیز به بیرون نمی‌رود):
272
+
273
+ ۱. **آزمون کور:** شش پرسش از دادهٔ همان اسنپ‌شات. اول فقط پرسش و عددهای ورودی می‌آید؛ خود
274
+ سرمایه‌گذار حدس می‌زند، بعد «داوری حدس‌های من» را می‌زنید و پاسخ برنامه با **مسیر محاسبه** و
275
+ **روش دوم (حساب دستی با کسر دقیق)** رو می‌شود. اگر پاسخ برنامه با ماشین‌حساب او نخواند، برگه
276
+ اعتبار ندارد و باید پاره شود؛ همین جمله را بلند بگویید.
277
+ ۲. **پلهٔ تصمیم:** سند «چه بخرم / چه زمانی بفروشم / چه زمانی می‌افتد». برای هر ردیف سه حد می‌نویسد
278
+ (برداشت سود، توقف ضرر، سررسید) و نقطهٔ برگشت عددی: «اگر نرخ سد از این عدد بگذرد، همین سیگنال
279
+ می‌افتد». ردیف‌هایی که می‌افتند هم در سند می‌مانند («چه چیزی نخر و چرا») و حذف نمی‌شوند.
280
+ ۳. **پیمان‌نامهٔ نمایش:** یک برگ دو امضا: چه چیزی اثبات می‌شود (بازتولید با ماشین‌حساب، کارمزد
281
+ واقعی، نقطهٔ برگشت، زنجیرهٔ هش دفتر) و چه چیزی نه (سود آینده، پیش‌بینی قیمت، اعتبار بیشتر از
282
+ بازهٔ دادهٔ موجود). سقف هر راهبرد و سقف کل باز هم در همین برگ نوشته می‌شود.
283
+
284
+ **گام ۱۱ (راهبردها و ریاضیِ پول) — تازه:** سه دکمه. «ساخت جزوه + شوک‌آزمون» جزوهٔ هشت راهبرد (با قاعدهٔ بستن) و برگهٔ شوک‌آزمون را می‌سازد؛ «حساب کن» در کارت ریاضی، کِلی و احتمال نیم‌شدن حساب و ماه‌های تا هدف را عدد می‌کند. اگر سرمایه‌گذار پرسید «درصد سود چقدر است؟»، همین‌جا جواب اوست: عددهای قفل‌شده و مرز افتادن، نه وعده.
285
+
286
+ **ترتیب دقیق کلیک‌ها در روز نمایش:** گام ۱ (سلامت) → گام ۱۰ کارت ۱: «نمایش پرسش‌ها» → حدس‌ها را
287
+ او بگوید و شما بنویسید → «داوری حدس‌های من» → کارت ۲: «محاسبهٔ جدول» (اگر گفت با این نرخ سد
288
+ می‌شود پول درآورد، همین جدول جوابش است) → کارت ۳: یک معاملهٔ گذشتهٔ خودش را در «حساب‌رسی واقعیت»
289
+ بزنید تا کارمزد و مالیات از سودش کم شود → کارت ۴: «ساخت برگهٔ آزمون» و «ساخت پیمان‌نامهٔ نمایش» →
290
+ امضا.
291
+
292
+ **یک هشدار لازم:** اگر سرمایه‌گذار از همهٔ شش پرسش جلو بزند، این برد اوست، نه باخت برنامه. آن‌جا
293
+ بگویید: «شما حرفه‌ای هستید؛ کاری که برنامه اضافه می‌کند سرعت، نظم و دفتر ثبت‌شده است، نه
294
+ جایگزینی شما.»
295
+
station/MAKE-PASSWORDS.py ADDED
@@ -0,0 +1,76 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """اولین اجرا: اگر رمزها ساخته نشده‌اند، همین حالا ساخته می‌شوند و چاپ می‌شوند.
2
+
3
+ این پرونده بخشی از «کوله‌پشتی دمو» است (نه بستهٔ تحویلی). کارش فقط این است که کاربر تازه‌کار
4
+ بدون هیچ فرمانی، رمز مدیر و کارفرما داشته باشد. رمزها را در پروندهٔ زیر هم می‌نویسد:
5
+ `station/config/CREDENTIALS-FIRST-LOGIN.txt` (دسترسی ۶۰۰) تا گم نشوند.
6
+ """
7
+ from __future__ import annotations
8
+
9
+ import json
10
+ import pathlib
11
+ import secrets
12
+ import sys
13
+
14
+ HERE = pathlib.Path(__file__).resolve().parent
15
+ STATION = HERE / "station"
16
+ sys.path.insert(0, str(STATION))
17
+
18
+ import adminauth # noqa: E402
19
+ import gate # noqa: E402
20
+
21
+ CRED = STATION / "config" / "CREDENTIALS-FIRST-LOGIN.txt"
22
+ ADMIN_ID, GUEST_ID = "mafhoom", "masoud"
23
+
24
+
25
+ def make(force: bool = False) -> int:
26
+ cfg = STATION / "config" / "gate.json"
27
+ if cfg.exists() and not force:
28
+ st = gate.status()
29
+ print("رمزها از قبل ساخته شده‌اند (چیزی عوض نشد).")
30
+ acc = st.get("accounts", {})
31
+ print(" دروازه: " + ("روشن" if st.get("enabled") else "خاموش"))
32
+ print(" مدیر: " + (acc.get("admin", {}).get("id") or "—") +
33
+ " · کارفرما: " + (acc.get("guest", {}).get("id") or "—") +
34
+ (" (فعال)" if acc.get("guest", {}).get("enabled") else " (قطع)"))
35
+ print(" اگر رمزها را گم کرده‌ای: این فایل را با --force اجرا کن (رمز تازه می‌سازد).")
36
+ if CRED.exists():
37
+ print(f" پروندهٔ رمز: {CRED}")
38
+ return 0
39
+
40
+ admin_pass = "Desk-" + secrets.token_hex(4)
41
+ guest_pass = "Desk-" + secrets.token_hex(4)
42
+
43
+ adminauth.set_credentials(ADMIN_ID, admin_pass)
44
+ gate.sync_admin_from_panel()
45
+ gate.set_account("guest", GUEST_ID, guest_pass)
46
+ gate.set_enabled_account("guest", True)
47
+ gate.set_enabled(True)
48
+
49
+ CRED.parent.mkdir(parents=True, exist_ok=True)
50
+ CRED.write_text(
51
+ f"""ایستگاه تصمیم مشتقه — رمزهای اولین ورود (ساختهٔ MAKE-PASSWORDS.py)
52
+ این پرونده را جایی نگه دار که فقط خودت ببینی. هر وقت خواستی رمز تازه بسازی:
53
+ python MAKE-PASSWORDS.py --force
54
+
55
+ مدیر (پنل مدیریت): {ADMIN_ID}
56
+ رمز مدیر : {admin_pass}
57
+ کارفرما (مهمان) : {GUEST_ID}
58
+ رمز کارفرما : {guest_pass}
59
+
60
+ قطع کارفرما همین حالا: python station/gate.py --guest-off
61
+ روشن‌کردن دوباره : python station/gate.py --guest-on
62
+ """, encoding="utf-8")
63
+ CRED.chmod(0o600)
64
+
65
+ print("┌───────────────────────────────────────────────┐")
66
+ print("│ رمزهای تازه ساخته شد — همین حالا یادداشت کن │")
67
+ print("└───────────────────────────────────────────────┘")
68
+ print(f" پنل مدیر : {ADMIN_ID} / {admin_pass}")
69
+ print(f" کارفرما : {GUEST_ID} / {guest_pass}")
70
+ print(f" (همین‌ها در این پرونده هم نوشته شد: {CRED})")
71
+ print(" دروازه روشن است: بدون رمز، هیچ صفحه‌ای باز نمی‌شود.")
72
+ return 0
73
+
74
+
75
+ if __name__ == "__main__":
76
+ raise SystemExit(make(force="--force" in sys.argv))
station/README-FA.md ADDED
@@ -0,0 +1,626 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # ایستگاه تصمیم مشتقه — راهنمای فارسی برای کاربر تازه‌کار
2
+
3
+ نسخهٔ ۰٫۲٫۰ · ده گام · رابط گرافیکی · بدون نیاز به دانش برنامه‌نویسی · دفتر اتصال، دفتر آزمون زنده،
4
+ آزمون ۱۰ دقیقه‌ای و پروندهٔ سرمایه‌گذار
5
+
6
+ ## این برنامه به پنج سؤال شما جواب می‌دهد
7
+
8
+ **۱. رابط گرافیکی گام‌به‌گام، با نتیجه‌ای که مستقیم دست شرکت بدهید.**
9
+ یازده گام داریم و هر گام یک کار روشن: خوش‌آمد و پنل مدیریت ← منبع داده ← تنظیمات ← خبر ← محاسبه ← تصمیم ← پس‌آزمایی ← بستهٔ تحویل شرکت ← دفتر آزمون زنده ← آزمون کور سرمایه‌گذار ← راهبردها و ریاضیِ پول. در گام ۸ یک پوشه ساخته می‌شود که همه‌چیز در آن است: گزارش تصمیم‌ها، فهرست سیگنال‌ها، سند روش کار، بسته‌های سفارش، نتیجهٔ پس‌آزمایی، **کارنامهٔ آزمون، برگهٔ آزمون سرمایه‌گذار، پروندهٔ سرمایه‌گذار (با اثر انگشت هر پرونده)**، و یک چک‌لیست نه‌گامی که خودشان در پنج دقیقه راستی‌آزمایی کنند.
10
+
11
+ **۲. راهنمای خرید داده و محل اتصال آن در خود برنامه.**
12
+ در گام ۲ جدول «راهنمای خرید داده» هست: چه چیزی بخرید، تقریباً چقدر است، کلید را کجا بگذارید، و **بعد از اتصال چه چیزی در برنامه عوض می‌شود**. جای وارد کردن «قالب نشانی» و «مسیر JSON» و «کلید» هم همان‌جاست، با دکمهٔ «آزمایش اتصال».
13
+
14
+ **۳. دادهٔ زندهٔ واقعی.**
15
+ حالت «دادهٔ زندهٔ واقعی» قیمت را از وب‌سرویس می‌خواند و روی اسنپ‌شات می‌نشاند؛ تازگی داده در نوار بالا سبز می‌شود. اگر سرویس جواب نداد، از حافظهٔ نهان استفاده می‌شود و همه‌چیز متوقف نمی‌شود.
16
+
17
+ **۴. پس‌آزمایی روی دادهٔ گذشته.**
18
+ گام ۷ همان موتوری را که در تصمیم زنده کار می‌کند روی تاریخ اجرا می‌کند: نرخ برد، خطای مثبت کاذب، فرصت‌های از دست رفته، خطای پیش‌بینی، و منحنی سرمایه. نتیجهٔ واقعی هیچ نقشی در تصمیم ندارد (آزمون ضد آینده‌نگری در `tests` اجرا می‌شود).
19
+
20
+ ## دو راه اجرا
21
+
22
+ ### الف. رابط مرورگری، توصیه‌شده
23
+
24
+ روی ویندوز: پروندهٔ `run-gui.bat` را دوبار کلیک کنید. مرورگر خودش باز می‌شود.
25
+ دستی:
26
+
27
+ ```bash
28
+ cd MATERIALS/money/gui
29
+ python web_server.py --port 8765
30
+ ```
31
+
32
+ سپس در مرورگر: `http://127.0.0.1:8765`
33
+
34
+ چرا مرورگر؟ چون خط فارسی در مرورگر روی همهٔ سیستم‌ها درست و راست‌به‌چپ نشان داده می‌شود. (در آزمایش، نسخهٔ دسکتاپ روی لینوکس فارسی را شکسته نشان داد؛ روی ویندوز معمولاً درست است.)
35
+
36
+ ### ب. نسخهٔ دسکتاپ، بدون مرورگر
37
+
38
+ ```bash
39
+ python station.py # پنجرهٔ معمولی
40
+ python station.py --smoke # آزمون سلامت بدون کلیک کردن
41
+ ```
42
+
43
+ روی ویندوز: `run-gui-desktop.bat`
44
+
45
+ ## نصب روی لپ‌تاپ در پنج گام (ویندوز، بدون اینترنت)
46
+
47
+ ۱. پایتون ۳ را از `python.org` نصب کنید؛ در نخستین پنجرهٔ نصب تیک **Add python.exe to PATH** را بزنید.
48
+ ۲. پوشهٔ `MATERIALS/money` را کامل روی دسکتاپ کپی کنید (نه فقط یک پرونده).
49
+ ۳. روی `gui\run-gui.bat` دوبار کلیک کنید؛ مرورگر خودش باز می‌شود.
50
+ ۴. آزمون سلامت: `run-selftest.bat` (کارنامهٔ ۱۵ موردی، هر عدد دو بار حساب می‌شود) و
51
+ `run-investor-test.bat` (آزمون کور سرمایه‌گذار).
52
+ ۵. برای دموی بی‌هزینه و بی‌اینترنت: `run-mock-feed.bat` را باز بگذارید و در گام ۲ پروفایل
53
+ «خوراک آزمایشی محلی» را فعال کنید؛ بعد گام ۵ و ۶ را اجرا کنید.
54
+
55
+ هیچ `pip install` لازم نیست: برنامه فقط با کتابخانهٔ استاندارد پایتون و `tkinter` کار می‌کند.
56
+ اگر پایتون نصب نباشد، خودِ `run-gui.bat` پیام فارسی می‌دهد و راه نصب را می‌گوید.
57
+
58
+ ## چرخهٔ کار در عمل (نمونهٔ امروز)
59
+
60
+ ۱. گام ۱: «باز کردن پنل مدیریت» را بزنید، با شناسه و رمز وارد شوید و «بررسی سلامت برنامه» را اجرا کنید؛ باید همهٔ اجزا سبز باشد.
61
+ ۲. گام ۲: با «دادهٔ نمونهٔ همراه برنامه» شروع کنید تا همه‌چیز را ببینید.
62
+ ۳. گام ۳: نرخ سد را از بازده مؤثر صندوق درآمد ثابت همان روز بگذارید (شهریور ۱۴۰۵: حدود ۳۹ تا ۴۰ درصد).
63
+ ۴. گام ۴: دکمهٔ «اجرای دیده‌بان روی دادهٔ نمونه» تا خبر و هشدار ساخته شود.
64
+ ۵. گام ۵: «شروع محاسبه»؛ خلاصه و ریز سیگنال‌ها و دلیل رد‌ها را می‌بینید.
65
+ ۶. گام ۶: یک سیگنال را انتخاب کنید و «تأیید» بزنید؛ بستهٔ سفارش روی صفحه می‌آید تا خودتان در سامانهٔ کارگزاری اجرا کنید.
66
+ ۷. گام ۷: «اجرای پس‌آزمایی» روی پروندهٔ تاریخ (نمونه‌اش همراه برنامه است).
67
+ ۸. گام ۸: «ساخت بستهٔ راستی‌آزمایی» و دادن پوشهٔ ساخته‌شده به شرکت.
68
+ ۹. گام ۹: «ثبت سیگنال‌های گام ۵» در دفتر آزمون زنده، بعد «خواندن قیمت‌های تازه و بازسنجی دفتر»،
69
+ و در پایان «ساخت گزارش سرمایه‌گذار». این دفتر همان چیزی است که ارزش برنامه را ثابت می‌کند.
70
+ ۱۰. گام ۱۰ (جلسهٔ سرمایه‌گذار): «نمایش پرسش‌ها» را بزنید و لپ‌تاپ را دست خودش بدهید. او حدس می‌زند،
71
+ بعد «داوری حدس‌های من» پاسخ برنامه را با فرمول و روش دوم رو می‌کند. بعد جدول آستانهٔ ریزش،
72
+ حساب‌رسی یک معاملهٔ گذشته، و «ساخت برگهٔ آزمون» برای امضا. تمام.
73
+
74
+ ## حالت دادهٔ زنده: چه بخرم و چطور وصل کنم
75
+
76
+ | گزینه | هزینهٔ تقریبی | فیلدهایی که می‌دهد | پس از اتصال چه تغییر می‌کند |
77
+ |---|---|---|---|
78
+ | کدال (رسمی) | رایگان | اطلاعیه‌ها و صورت‌های مالی | هشدار و زمینهٔ خبری؛ همین حالا فعال است |
79
+ | tsetmc و بسته‌های پایتونی | رایگان ولی بی‌تعهد | قیمت پایانی و ریزمعاملات | قیمت پایه به‌روز می‌شود، بدون تضمین |
80
+ | سرویس دادهٔ خریدنی ایرانی | فروشنده تعیین می‌کند؛ در سایتش تأیید کنید | قیمت زنده، ریزمعاملات، دادهٔ تاریخی | تازگی داده سبز، به‌روزرسانی خودکار، و پس‌آزمایی روی تاریخ واقعی |
81
+ | دادهٔ تاریخی | معمولاً داخل همان بسته | سری زمانی آپشن و آتی و گواهی سپرده | نرخ برد و خطای پیش‌بینی با عدد واقعی، قابل ارائه به شرکت |
82
+
83
+ نکتهٔ مهم: **وجه تضمین و مشخصات قرارداد را هیچ سرویسی به شما نمی‌دهد**؛ آن‌ها را از سامانهٔ کارگزاری بردارید و در پروندهٔ اسنپ‌شات بگذارید. برنامه آن را حدس نمی‌زند.
84
+
85
+ ## دفتر اتصال: هر وقت سرویس را گرفتم، وصلش کنم
86
+
87
+ در گام ۲ یک «دفتر اتصال» اضافه شده است. کارش این است:
88
+
89
+ - یک پروفایل از فهرست انتخاب می‌کنید؛ کادرهای قالب نشانی و مسیر JSON خودشان پر می‌شوند.
90
+ - «آزمایش اتصال این پروفایل» را می‌زنید و نتیجه را روی همان صفحه می‌بینید.
91
+ - «ذخیره و فعال کردن» را می‌زنید. از آن به بعد هر بار که برنامه بالا می‌آید، همین اتصال خودکار
92
+ فعال می‌شود (در نسخهٔ دسکتاپ هم).
93
+
94
+ پروفایل‌های آمادهٔ رایگان که همین حالا در فهرست هستند:
95
+
96
+ | پروفایل | چه می‌دهد | کلید لازم دارد؟ |
97
+ |---|---|---|
98
+ | خوراک آزمایشی محلی | قیمت ساختگی برای آزمون کل مسیر زنده | نه |
99
+ | tgju | دلار و طلا و سکه | نه |
100
+ | tsetmc | قیمت پایانی سهام و آپشن (با کد نماد در فیلد `feed_symbol`) | نه |
101
+ | صرافی ایرانی | نرخ لحظه‌ای ریالی | نه |
102
+ | سرویس خریدنی | قالب نمونه برای کلید خودتان | بله |
103
+
104
+ **کاوشگر پاسخ سرویس:** اگر ساختار پاسخ سرویس را نمی‌دانید، نشانی را در کادر کاوشگر بگذارید و دکمه
105
+ را بزنید؛ فهرست عددهای داخل پاسخ با مسیرشان می‌آید و با «استفاده» مسیر JSON خودش پر می‌شود.
106
+
107
+ **کلید کجا ذخیره می‌شود؟** پیش‌فرض این است که هیچ‌جا: کلید فقط تا بسته‌شدن برنامه در حافظه می‌ماند.
108
+ اگر تیک «کلید را روی این رایانه ذخیره کن» را بزنید، در پروندهٔ `config/keys.local.json` ذخیره می‌شود
109
+ (فقط روی رایانهٔ خودتان). مشخصات اتصال در `config/connections.json` است و هیچ‌وقت کلید در آن نوشته نمی‌شود.
110
+
111
+ ## خوراک آزمایشی محلی و دموی سرمایه‌گذار
112
+
113
+ `python mock_feed.py` یک بازار ساختگی کوچک روی همان رایانه بالا می‌آورد (پیش‌فرض درگاه ۸۷۸۸) با یک
114
+ صفحهٔ زندهٔ قیمت. کارساز مرورگری خودش آن را همراه می‌آورد؛ اگر جدا خواستید: `run-mock-feed.bat`.
115
+
116
+ این خوراک برای سه کار است: آزمودن کل مسیر «دادهٔ زنده»، تمرین کردن، و **نمایش دادن به سرمایه‌گذار
117
+ بدون هیچ هزینه‌ای**. داده‌اش ساختگی است و برنامه هم همه‌جا همین را با برچسب
118
+ «خوراک آزمایشی محلی (ساختگی)» نشان می‌دهد، پس هیچ‌وقت با دادهٔ واقعی اشتباه گرفته نمی‌شود.
119
+
120
+ برای دموی سرمایه‌گذار: پروندهٔ `run-investor-demo.bat` را دوبار کلیک کنید و بعد این راهنما را باز کنید:
121
+ `DEMO-INVESTOR-FA.md` (سناریوی بیست دقیقه‌ای، هفت لحظهٔ «آها»، پاسخ‌های آماده به پرسش‌های
122
+ سرمایه‌گذار، و پروتکل آزمون بی‌پول دو هفته‌ای). پاسخ کوتاه: برای این دمو هیچ خریدی لازم نیست،
123
+ نه کلید داده نه مدل زبانی.
124
+
125
+ ## گام ۹: دفتر آزمون زنده
126
+
127
+ هر سیگنال با ساعت دقیق، قیمت‌های همان لحظه، نرخ سد و ورودی‌های ریاضی در یک دفتر ثبت می‌شود
128
+ (`data/trial.sqlite3`). بعداً با دکمهٔ «بازسنجی»، همان موتور روی قیمت‌های تازه اجرا می‌شود و دفتر
129
+ می‌گوید حاشیهٔ آن سیگنال امروز چقدر است: «بازتر شد»، «کم شد»، «تقریباً ثابت»، یا «زیر کف رفت».
130
+
131
+ هر ثبت یک **هش زنجیره‌ای** دارد (هشِ ردیف قبلی داخل خودش است). با «بررسی زنجیرهٔ هش» می‌توانید نشان
132
+ بدهید هیچ ردیفی بعد از ثبت عوض نشده؛ اگر کسی عوض کند، زنجیره می‌شکند. گزارش دفتر
133
+ (`data/trial-report.html` و CSV آن) سند ارائه به شرکت است. توجه: این گزارش «سود تحقق‌یافته» نیست؛
134
+ تغییر بازده انتظاری در طول زمان است.
135
+
136
+ ## اتصال خودکار: «برنامه خودش بگردد و ببیند کدام منبع امروز کار می‌کند»
137
+
138
+ من نمی‌توانم از جای خودم بررسی کنم که سرویس‌های ایرانی امروز چه پاسخی می‌دهند (شبکهٔ من به
139
+ بسیاری از آن‌ها وصل نمی‌شود). ولی خودِ برنامه روی رایانهٔ شما می‌تواند. در گام ۲ دکمهٔ
140
+ **«بگرد و گزارش بده»** این کار را می‌کند:
141
+
142
+ - چند منبع رایگان را یکی‌یکی امتحان می‌کند (بدون کلید، بدون هزینه).
143
+ - پاسخ را می‌خواند و عدد را از نظر عقلی می‌سنجد: تاریخ نباشد، شمارنده نباشد، صفر نباشد،
144
+ بیرون بازهٔ باورپذیر نباشد.
145
+ - برای هر منبع می‌گوید **چرا** کار کرد یا کار نکرد: «پاسخی نیامد»، «پاسخ JSON نبود»،
146
+ «مسیر عدد سالم پیدا نشد»، «عدد شبیه تاریخ است»، «کد نماد پیدا نشد».
147
+ - اگر «کد نماد» لازم باشد (مثل قیمت پایانی سهام)، خودش کد هر نماد را پیدا می‌کند و در ستون
148
+ «کد نماد» همان ردیف می‌نویسد.
149
+ - با دکمهٔ دوم، اولین منبع سالم ذخیره و فعال می‌شود؛ از آن به بعد هر بار خودکار وصل می‌شود.
150
+
151
+ خط فرمان و ویندوز:
152
+
153
+ ```bash
154
+ python autoconnect.py # فقط گزارش
155
+ python autoconnect.py --save # ذخیره و فعال‌کردن منبع سالم
156
+ ```
157
+
158
+ روی ویندوز: `run-autoconnect.bat`
159
+
160
+ **دو سنجهٔ صداقت که همراه همین بخش هست:** اگر منبعی برای همهٔ نمادها یک عدد بدهد (مثل نرخ ارز)،
161
+ وضعیت «جزئی» می‌شود و برچسب «نرخ واحد، نه نماد» می‌خورد تا کسی آن عددها را به‌جای قیمت سهام نگیرد.
162
+ و اگر سرویس برای نام نماد فارسی پاسخ ندهد، برنامه خطا را همان‌طور که هست گزارش می‌کند؛ عدد از خودش نمی‌سازد.
163
+
164
+ **نتیجهٔ آزمون واقعی در محیط سازنده (شهریور ۱۴۰۵):** از میان چهار منبع رایگان، یکی پاسخ سالم داد:
165
+ بازار ریالی یک صرافی ایرانی (نرخ لحظه‌ای، بدون کلید). در همان آزمون، tgju پاسخ خطا داد و
166
+ cdn.tsetmc خطای گواهی شبکه. این تفاوت‌ها طبیعی است؛ به همین دلیل «اتصال خودکار» این کار را
167
+ روی رایانهٔ **شما** انجام می‌دهد، نه یک‌بار برای همیشه در دفترچهٔ راهنما.
168
+
169
+ نکتهٔ صادقانه: نرخ ریالی صرافی، «قیمت پایهٔ سهام» نیست. کاربردش اثبات کارکرد اتصال زندهٔ واقعی
170
+ با صفر هزینه است. برای سیگنال روی سهام، یا قیمت زندهٔ نمادی لازم است (سرویس)، یا اعداد کارگزاری
171
+ را دستی وارد می‌کنید (پایین).
172
+
173
+ ## وارد کردن اعداد کارگزاری در جدول (بدون ویرایش JSON)
174
+
175
+ در گام ۲، جدول **«وارد کردن اعداد کارگزاری»** را پر می‌کنید و دکمهٔ «ذخیرهٔ اسنپ‌شات امروز» را
176
+ می‌زنید. برنامه پروندهٔ تاریخ‌دار می‌سازد:
177
+
178
+ ```
179
+ data/snapshots/snapshot-YYYY-MM-DD.json
180
+ ```
181
+
182
+ چرا تاریخ‌دار؟ هر روز پروندهٔ خودش: سابقهٔ قابل ممیزی می‌شود و اشتباه یک روز، روزهای دیگر را
183
+ خراب نمی‌کند.
184
+
185
+ **قاعدهٔ «روز واقعی»:** پرونده فقط وقتی روز واقعی حساب می‌شود که تیک
186
+ «این اعداد را خودم از سامانهٔ کارگزاری برداشتم» را زده باشید. برنامه هم نام پرونده را می‌سنجد
187
+ («نمونه/قالب/demo» ساختگی است) هم همین تیک را. اگر خودتان با ویرایشگر متن پرونده می‌سازید،
188
+ خط `"source": "manual-broker"` را در آن بگذارید.
189
+ وجه تضمین را حتماً از سامانهٔ کارگزاری بردارید؛ هیچ سرویسی این عدد را نمی‌دهد.
190
+
191
+ ## چسباندن اعداد کارگزاری، بدون تایپ دستی (گام ۲)
192
+
193
+ در کارت «وارد کردن اعداد کارگزاری» یک کادر تازه هست: **متن را از سامانهٔ کارگزاری کپی کنید و
194
+ همان‌جا بچسبانید**، بعد «تشخیص خودکار و افزودن به جدول» را بزنید. برنامه رقم فارسی، جداکنندهٔ
195
+ هزارگان («7,600»)، کلمهٔ «تومان»/«ریال»، سرستون‌ها («قیمت سهم، اعمال، پرمیوم، روز») و برچسب‌های
196
+ داخل ردیف را می‌فهمد و ردیف‌ها را در جدول می‌سازد. هر چیزی که نفهمد، در کادر گزارش صادقانه
197
+ می‌گوید (نه بی‌صدا). تیک «عددها به تومان است» فقط قیمت‌ها را ×۱۰ می‌کند، نه «روز» را.
198
+ ذخیره همچنان با تیک تأیید خودتان انجام می‌شود؛ پس روز «واقعی» بی‌اجازه ساخته نمی‌شود.
199
+
200
+ راهنمای ستون‌به‌ستون هم داخل همان کارت (بازشو) آمده: هر عدد را از کجا بیاورید.
201
+ برای کاهش خطای انسانی، اگر سرویس دادهٔ رایگان وصل باشد، همان عددها خودکار خوانده می‌شوند و
202
+ دستی فقط برای «وجه تضمین» می‌مانَد (که فقط کارگزاری آن را دارد).
203
+
204
+ ## گواهی استفادهٔ موفق (پنل مدیریت)
205
+
206
+ ورود به پنل: در گام ۱ دکمهٔ «باز کردن پنل مدیریت» یا نشانی `/admin`. شناسهٔ پیش‌فرض `mafhoom` است و
207
+ رمز را خودتان با `python3 adminauth.py --set-pass "رمز تازه"` عوض می‌کنید (رمز فقط هش‌شده در
208
+ `config/admin.json` می‌ماند؛ توکن ورود یک‌ساعته است و با بستن برنامه پاک می‌شود).
209
+ `usage_meter.py` هر کار موفق را در دفتر محلی و **زنجیره‌هش‌دار** ثبت می‌کند: داوری سیگنال، تصمیم
210
+ ثبت‌شده، مراسم روزانه، آزمون‌ها، ورود اعداد و بستهٔ شاهد. گواهی دو امضا دارد (شما و شرکت) و هیچ
211
+ دادهٔ معاملاتی یا نامی داخلش نیست؛ به ��ینترنت هم چیزی فرستاده نمی‌شود. کارت آن در **پنل مدیریت** است و
212
+ سند تحلیلی‌اش `MATERIALS/money/11-usage-and-percent-fa.md` (مدل درصدگرفتن، با سود و زیان هر مدل).
213
+
214
+ ## بستهٔ تحویل شرکت (یک فرمان)
215
+
216
+ ```bash
217
+ python3 make_kit.py --zip # می‌سازد: ../delivery/iran-desk-kit و فایل zip همان
218
+ ```
219
+
220
+ بسته فقط **کد و قالب و سند** را برمی‌دارد؛ گزارش‌ها، دفترها، بسته‌های شاهد، حافظهٔ نهان و رمز پنل را
221
+ با خودش نمی‌برد (۸۳ پروندهٔ ساخته‌شده کنار گذاشته می‌شود). اول هر پرونده با اثر انگشت `sha256` در
222
+ `KIT-MANIFEST.json` فهرست می‌شود، بعد `START-HERE-FA.md` نصب و ده دقیقهٔ اول و مرزهای صادقانه را
223
+ می‌گوید. خودِ همین بسته، جدا از درخت اصلی، آزموده شده است: **۶۵۸ آزمون واحد سبز** و
224
+ **۱۹۲ بررسی تعاملی مرورگری، صفر ناموفق** روی درگاه دیگری و با رمز پنل خودش.
225
+
226
+ ## برگهٔ «پیشنهاد یک‌صفحه‌ای» (گام ۸)
227
+
228
+ ```bash
229
+ python3 offer.py --client "نام شرکت" # برگه با قیمت «توافقی»
230
+ python3 offer.py --client "نام شرکت" --monthly 40000000 --setup 100000000
231
+ ```
232
+
233
+ دو نسخه می‌سازد: `data/offer-one-pager.html` (چاپی، خودبسنده) و `.md` برای ایمیل و واتساپ. هیچ عدد
234
+ سودی در آن نیست، هیچ قیمتی هم از خودش نمی‌سازد؛ اگر مبلغ ندهید «توافقی» می‌ماند. دکمه‌هایش در گام ۸
235
+ است: نام شرکت را بنویسید → «ساخت پیشنهاد یک‌صفحه‌ای» → «نمایش پیشنهاد».
236
+
237
+ ## بستهٔ پیام‌های معرفی و پیگیری (گام ۸)
238
+
239
+ ```bash
240
+ python3 outreach.py --client "نام مخاطب" --kind brokerage # یا company / teacher / known
241
+ python3 outreach.py --checklist # آماده‌سازی پیش از پیام اول
242
+ ```
243
+
244
+ چهار متن آماده می‌سازد (پیام اول · پیام بعد از جواب · تأیید وقت · پیگیری) به‌همراه اسکریپت تماس
245
+ تلفنی و پاسخ چهار مخالفت رایج؛ در گام ۸ با منوی لحن و دو دکمه. قاعده‌ها سخت‌گیرانه‌اند: پیام اول
246
+ کوتاه و بدون پیوست، هیچ عدد سودی در هیچ متنی، و پیگیری فقط سه بار (روز ۰، ۳، ۱۰). سند تحلیلی‌اش
247
+ `MATERIALS/money/14-first-meeting-fa.md` است.
248
+
249
+ ## تابلوی پیگیری مخاطبان (گام ۸)
250
+
251
+ ```bash
252
+ python3 prospects.py --add "نام مخاطب" --kind brokerage --channel phone
253
+ python3 prospects.py --sent "نام مخاطب" # روز ۰: پیام اول
254
+ python3 prospects.py --followup "نام مخاطب" # روز ۳ و روز ۱۰ (بار سوم رد می‌شود)
255
+ python3 prospects.py --reply "نام مخاطب" # جواب داد → قرار جلسه
256
+ python3 prospects.py --outcome "نام مخاطب" --result "نه" # یا بله / بعداً / بی‌جواب
257
+ python3 prospects.py --todo # امروز چه کاری به گردن من است
258
+ python3 prospects.py --week # سه عدد هفته: پیام · تماس · جلسه
259
+ python3 prospects.py --sheet # برگهٔ چاپی + نسخهٔ متنی
260
+ ```
261
+
262
+ قاعدهٔ پیگیری در خود کد قفل است: بار سوم پیگیری رد می‌شود («ببند و رهایش کن»)، «بستن پرونده»
263
+ نتیجهٔ «بی‌جواب» می‌گذارد تا آمار الکی درست نشود، و هر شمارهٔ تلفن یا عدد دراز در یادداشت
264
+ ماسک می‌شود. دفتر پیش‌فرض `data/prospects.json` است (با `IRAN_DESK_PROSPECTS` جای دیگری بگذارید).
265
+ در رابط، همین کارت در گام ۸ است و بار اول خودش تابلو را می‌خواند.
266
+
267
+ «بعداً» بی‌تاریخ نمی‌ماند: با `--result بعداً --next-on 2026-10-22` تاریخ سر‌زدن ثبت می‌شود و
268
+ پیش‌فرض سی روز بعد است؛ همان روز، مخاطب به «کار امروز» برمی‌گردد — یک پیام، نه بیشتر.
269
+
270
+ ## روز اول مشتری — از «بله» تا پایان هفتهٔ دوم (گام ۸)
271
+
272
+ ```bash
273
+ python3 onboarding.py --client "نام مشتری" # برگهٔ روز اول
274
+ python3 onboarding.py --client "نام مشتری" --start 2026-09-22 --monthly 40000000
275
+ python3 onboarding.py --json # خلاصهٔ ماشین‌خوان
276
+ ```
277
+
278
+ برگهٔ چاپیِ بعد از «بله»: پنج کار روز اول (اجازه‌نامهٔ آزمون نام‌دار، نصب، اتصال رایگان، اعداد
279
+ کارگزاری خودشان، مراسم و راستی‌آزمایی)، فهرست «در این دو هفته چه چیزی خریده نمی‌شود»، شرط‌های
280
+ کارنامهٔ «آماده» و **روز بازبینی**، سه پلهٔ ارائه با قاعدهٔ «پرداخت در برابر شاهد»، و بخش «اگر
281
+ وسط راه پشیمان شدید». سه عدد این برگه دست‌نویس نیستند: طول آزمون از `license.TRIAL_DAYS`،
282
+ شرط‌های کارنامه از پیش‌فرض‌های `daily_trial.scorecard`، و عدد بستهٔ تحویل از `KIT-MANIFEST.json`
283
+ خوانده می‌شوند. سند تحلیلی‌اش `MATERIALS/money/15-after-meeting-fa.md` است.
284
+
285
+ ## مراسم فروش امروز — بیست دقیقه (گام ۸)
286
+
287
+ ```bash
288
+ python3 sales_ritual.py # برنامهٔ امروز
289
+ python3 sales_ritual.py --sender "مسعود" --on 2026-09-22 # نام امضا و تاریخ دلخواه
290
+ python3 sales_ritual.py --sheet # برگهٔ چاپی امروز
291
+ python3 sales_ritual.py --json
292
+ ```
293
+
294
+ تابلوی پیگیری می‌گوید امروز نوبت کیست؛ بستهٔ پیام‌ها متن آماده را دارد. این ماژول همان دو را
295
+ کنار هم می‌گذارد و یک **برگهٔ اجرایی** می‌سازد: کدام کار، برای کدام مخاطب، با کدام متن، در چه
296
+ دقیقه‌ای — جمعاً بیست دقیقه. اگر کانال مخاطب «تلفن» باشد، کارش با اسکریپت تماس و پنج دقیقه حساب
297
+ می‌شود؛ «ثبت نتیجهٔ جلسه» کار دفتری است و متن ندارد.
298
+
299
+ سه چیز در خود کد قفل است: **سقف پنج پیام در روز** و **بودجهٔ بیست دقیقه** (هر کاری که جا نشد، با
300
+ دلیلش به «فردا» می‌رود و سقف جابه‌جا نمی‌شود) · متن‌ها فقط از `outreach.messages` می‌آیند (تنها
301
+ استثنا: پیام «روز موعود» که همین‌جا نوشته شده و همان آزمون‌های سختی را می‌دهد) · **روز خالی، پیام
302
+ نمی‌سازد**: اگر نوبت کسی نیست، برگه می‌گوید پنج نام تازه اضافه کن.
303
+
304
+ ## جلسهٔ بازبینی دو هفته‌ای (گام ۸)
305
+
306
+ ```bash
307
+ python3 review_meeting.py --client "نام مشتری" --start 2026-09-22
308
+ python3 review_meeting.py --client "نام مشتری" --start 2026-09-22 --on 2026-10-06 --monthly 40000000
309
+ python3 review_meeting.py --json
310
+ ```
311
+
312
+ برگهٔ روز چهاردهم: همان روزی که اجازه‌نامهٔ آزمون تمام می‌شود و باید تصمیم گرفته شود. برگه بیست
313
+ دقیقهٔ جلسه را دقیقه‌به‌دقیقه می‌چیند و سه چیز را کنار هم می‌گذارد: **سه شاهد** که خودشان روی همان
314
+ لپ‌تاپ اجرا می‌کنند (کارنامه، دفتر استفاده، آزمون ایستگاه — و اختیاری: بستهٔ راستی‌آزمایی)، **پنج
315
+ شرط کارنامهٔ «آماده»** که از خود کد خوانده می‌شوند، و **دو خروجی روشن**: ادامه با پرداخت (پله‌ها از
316
+ `license.ladder`، قیمت از `offer.price_line` — اگر عددی ندهید «توافقی») یا توقف بی‌گلایه‌مندی.
317
+
318
+ هر شاهد دو ستون دارد: «چه چیزی را نشان می‌دهد» و «چه چیزی را نشان نمی‌دهد»؛ مرزِ عدد جلوی چشم
319
+ طرف مقابل است. اگر کارنامه آماده نبود، خروجی سوم روشن است: **تمدید یک‌بار و بی‌هزینهٔ چهارده
320
+ روزه** با همان شرط‌ها — پس هیچ‌کس تحت فشار تصمیم نمی‌گیرد. اگر همان روز تصمیم نگرفتند، تاریخ سر
321
+ زدن (پیش‌فرض سی روز بعد) و دو پیام کوتاه (روز ۳ و روز ۷) روی برگه نوشته شده و در تابلو ثبت می‌شود.
322
+ سند تحلیلی‌اش `MATERIALS/money/16-review-meeting-fa.md` است.
323
+
324
+ ## دروازهٔ ورود: کارفرما از راه دور ببیند، رمز مدیر لو نرود (گام ۱ و ۸)
325
+
326
+ اگر می‌خواهید کارفرمایی در شهر دیگر همان برنامهٔ در حال اجرا را ببیند و تست کند، **دروازهٔ ورود** را
327
+ روشن کنید. سه فرمان، یک‌بار:
328
+
329
+ ```bash
330
+ python3 gate.py --sync-admin # رمز مدیر دروازه = همان رمز پنل مدیریت
331
+ python3 gate.py --guest-id masoud --guest-pass "رمز-کارفرما" # حساب نام‌دار کارفرما (دست‌کم ۸ نویسه)
332
+ python3 gate.py --on # روشن: از این لحظه، بدون ورود هیچ صفحه‌ای باز نمی‌شود
333
+ python3 gate.py --status # کنترل وضعیت و شمار نشست‌های باز
334
+ ```
335
+
336
+ از این لحظه، آدرس برنامه **صفحهٔ ورود** می‌آید. کارفرما با حساب مهمان وارد می‌شود:
337
+
338
+ | کارفرما (مهمان) | می‌بیند | نمی‌تواند |
339
+ | --- | --- | --- |
340
+ | یازده گام و محاسبه‌های برنامه | ✅ | — |
341
+ | خروجی‌ها و برگه‌های چاپی (پیشنهاد، پیام‌ها، تابلو، راهنمای تازه‌کار، کارنامهٔ بازبینی) | ✅ | — |
342
+ | پنل مدیریت، صدور اجازه‌نامه، عوض‌کردن رمزها، خاموش‌کردن برنامه | ❌ | ❌ |
343
+
344
+ نشست هر کاربر هشت ساعت پس از آخرین کارش بسته می‌شود؛ رمزها فقط هش‌شده روی دیسک می‌مانند و پنج
345
+ تلاش ناموفق، آن نشانی را چند دقیقه قفل می‌کند. روی رایانهٔ خودِ صاحب برنامه، اگر دروازه روشن باشد
346
+ باید یک‌بار با حساب مدیر وارد شود؛ برای برگشت به حالت قبل (همین لپ‌تاپ = مدیر) کافی است
347
+ `python3 gate.py --off` بزنید. در گام ۱ برنامه، **کارت مدیر** دکمه‌های «روشن/خاموش‌کردن دسترسی
348
+ کارفرما»، «بستن نشست‌های باز مهمان» و **«خاموش کردن برنامه»** را دارد؛ همه فقط با حساب مدیر.
349
+ سند کامل (دو مسیر آدرس دادن، چک‌لیست جلسه، مرزهای صادقانه) در `docs/17-remote-access-fa.md`.
350
+
351
+ ### راهنمای کارفرما و امنیت
352
+
353
+ - **راهنمای کارفرما** روی مسیر `/guide` سرو می‌شود: پیش از ورود و بعد از ورود باز است، بدون
354
+ اینترنت کار می‌کند، و همهٔ نیاز کاربر را در یازده بخش می‌گوید (روز اول، هر روز، تصمیم‌ها،
355
+ روز چهاردهم، جدول پیام‌های خطا، بیست پرسش پرتکرار، حریم خصوصی، پشتیبانی). هیچ توضیح فنی و هیچ
356
+ فرمولی در آن نیست؛ آزمون `tests/test_guide.py` این را سخت می‌گیرد.
357
+ - **بررسی امنیتی** با ۲۲ حملهٔ واقعی (`tests/test_security.py`): پیمایش مسیر، کوکی جعلی، بالا رفتن
358
+ از نقش کارفرما، CSRF، روش‌های ناخواسته، بدنهٔ غول‌آسا، و تلاش پی‌درپی رمز. سرآیندهای امنیتی و
359
+ پرچم `Secure` کوکی روی HTTPS اضافه شد؛ وضعیت سامانه هم برای ناشناس دیگر شناسه‌ها را لو نمی‌دهد.
360
+ گزارش کامل: `../20-security-review-fa.md`.
361
+
362
+ ### کاربران را خودت می‌سازی و هر وقت خواستی حذف می‌کنی (نسخهٔ ۰٫۲٫۰)
363
+
364
+ حساب «مهمان» یکی بود؛ حالا **هر تعداد کاربر** می‌توانی بسازی. شناسه و رمز را خودت تعیین می‌کنی،
365
+ رمز فقط هش‌شده می‌ماند، و «حذف» **همان لحظه** نشست بازِ آن کاربر را هم می‌بندد:
366
+
367
+ ```bash
368
+ python3 gate.py --user-add ali "رمز-علی" --user-note "کارشناس شرکت" # کاربر تازه
369
+ python3 gate.py --users # فهرست کاربران (بدون رمز و هش)
370
+ python3 gate.py --user-off ali # قطع فوری دسترسی (نشستش بسته می‌شود)
371
+ python3 gate.py --user-on ali # وصل‌کردن دوباره
372
+ python3 gate.py --user-del ali # حذف کامل
373
+ python3 gate.py --check ali "رمز-علی" # آزمودن یک جفت شناسه/رمز
374
+ ```
375
+
376
+ در خود برنامه (گام ۱، کارت مدیر) و در **پنل مدیریت، کارت ۴** هم همین کارها را با دکمه می‌کنی:
377
+ ساخت کاربر، فهرست با شمار نشست باز، قطع/وصل، و حذف کامل. در همان کارت، **شناسه و رمز حساب مدیر
378
+ (خودت)** را هم می‌توانی تعیین کنی. همهٔ کاربران نقش «مهمان» دارند: کل برنامه و برگه‌ها را می‌بینند،
379
+ ولی پنل مدیریت، صدور مجوز، عوض‌کردن رمزها، مدیریت کاربران و خاموش‌کردن برنامه برایشان بسته است.
380
+
381
+ ## لینک دادن به کارفرما، و بردن برنامه روی سایت
382
+
383
+ دو پوشه، دو کار:
384
+
385
+ - **`share/`** — لینک موقت برای جلسهٔ نمایش: `bash share/share-gui.sh` (لینوکس/مک) یا دوبار کلیک روی
386
+ `share/share-gui.bat` (ویندوز). ایستگاه را روشن می‌کند، لینک `https` می‌گیرد و همان را برای
387
+ کارفرما می‌فرستی. بستن پنجره = بسته‌شدن لینک و برنامه (`stop-gui.bat` هم هست). راهنمای فارسی:
388
+ `share/README-SHARE-FA.md`.
389
+ - **`deploy/`** — نشانی ثابت روی سرور: `Dockerfile`، `docker-compose.yml`، `Caddyfile` (HTTPS
390
+ خودکار با یک دامنه)، `station.service` برای systemd، `backup.sh` (پشتیبان روزانه با اثر انگشت)
391
+ و راهنمای گام‌به‌گام `deploy/README-DEPLOY-FA.md`.
392
+
393
+ هر دو مسیر پشت همان **دروازهٔ ورود** می‌نشینند: بدون شناسه و رمز، هیچ صفحه و هیچ خروجی‌ای باز
394
+ نمی‌شود؛ کارفرما (حساب مهمان) همه‌چیز را می‌بیند و تست می‌کند، ولی پنل مدیریت، صدور اجازه‌نامه،
395
+ عوض‌کردن رمزها و خاموش‌کردن برنامه برایش بسته است. سند کامل: `docs/17-remote-access-fa.md`.
396
+
397
+ ## راهنمای کامل برای تازه‌کار (سند جداگانه)
398
+
399
+ `MATERIALS/money/13-novice-walkthrough-fa.md`: هر بخش برنامه با نام واقعی دکمه‌ها، جدول عددهایی که
400
+ از کارگزاری می‌گیرید و کجای تابلو است، نقشهٔ صادقانهٔ اتوماسیون، و جدول «علامت ← معنا ← کارِ شما».
401
+ در خود برنامه هم از گام ۲ و گام ۹ با دکمهٔ «راهنمای هر بخش (برای تازه‌کار)» باز می‌شود.
402
+
403
+ ## گام‌به‌گام برای تازه‌کار: از صفر تا اولین تصمیم
404
+
405
+ ۱. `run-gui.bat` را بزنید؛ مرورگر باز می‌شود.
406
+ ۲. **پنل مدیریت:** «بررسی سلامت برنامه» (باید همه سبز باشد) و بعد «اجرای آزمون ۱۰ دقیقه‌ای».
407
+ ۳. **گام ۲:** در جدول اعداد، اعداد امروز را از کارگزاری بچسبانید (یا کادر چسباندن را استفاده کنید)،
408
+ تیک تأیید را بزنید و «ذخیرهٔ اسنپ‌شات امروز» را بزنید. اگر سرویس رایگان دارید، اول «دفتر اتصال».
409
+ ۴. **گام ۳:** سرمایه، نرخ سد و سقف ریسک را ببینید و در صورت نیاز عوض کنید (پیش‌فرض‌ها محافظه‌کارانه‌اند).
410
+ ۵. **گام ۴:** هشدارها و خبرهای کدال را نگاه کنید (اگر پایگاه‌دادهٔ کدال وصل باشد).
411
+ ۶. **گام ۵:** «اجرا و محاسبه».
412
+ ۷. **گام ۶:** سیگنال‌ها را ببینید و تأیید یا رد کنید؛ برای داوری سیگنال ابزارهای دیگر، همان کارت را
413
+ پر کنید و «داوری کن و برگه بساز» را بزنید.
414
+ ۸. **گام ۷:** پس‌آزمایی روی تاریخ (برای دیدن رفتار برنامه در گذشته).
415
+ ۹. **گام ۸:** «بستهٔ تحویل شرکت» را بسازید (پرونده‌های شاهد + مانیفست با اثر انگشت).
416
+ ۱۰. **گام ۹:** «۰. مراسم امروز» را بزنید تا دفتر و گزارش سرمایه‌گذار به‌روز شود؛ بعد «کارنامه» را ببینید.
417
+ ۱۱. **گام ۱۰:** لپ‌تاپ را به سرمایه‌گذار بدهید؛ «نمایش پرسش‌ها» و بعد سنجش حدس‌هایش.
418
+ ۱۲. هر روز فقط گام ۲ و گام ۹؛ شصت ثانیه. کارنامه با ۱۰ روز ثبت و دست‌کم ۵ روز واقعی «آماده» می‌شود.
419
+
420
+ ## ورودی روزانه، دقیق و مجانی (گام ۲)
421
+
422
+ هر روز فقط ده عدد لازم است و همه‌شان مجانی: قیمت پایه، آتی، اعمال، پرمیوم، روز، وجه تضمین، حجم،
423
+ اسپرد، نماد و راهبرد. محل هر عدد در راهنمای `MATERIALS/money/10-daily-inputs-fa.md` آمده و از
424
+ جدول «وارد کردن اعداد کارگزاری» گام ۲ با دو دکمه باز می‌شود («راهنما: هر روز چه عددی بگیرم؟» و
425
+ «نمایش قالب پرونده»). قالب کامل پنج نوع معامله در `data/snapshot-template.json` است.
426
+
427
+ ## مجوز دسترسی، پشتیبانی و عیب‌یابی (پنل مدیریت)
428
+
429
+ این برنامه «فروش نسخه» نیست؛ **اجازه‌نامهٔ دسترسی نام‌دار و زمان‌دار** است:
430
+
431
+ - `license.py` مجوز می‌سازد (نام شرکت، مدت، مسئول، امضای `sha256`) و در گام ۱ رابط با دکمه
432
+ «صدور مجوز دسترسی» و «وضعیت مجوز» نمایش داده می‌شود؛ همان امضا در بستهٔ شاهد گام ۸ هم می‌آید.
433
+ - **سند چاپی اجازه‌نامه** (دکمهٔ «ساخت سند مجوز» در پنل مدیریت یا `python3 license.py --document`):
434
+ یک پروندهٔ دواِمضا برای جلسه — نام مشتری، مدت، امضای چک‌سام، و جای خالی امضای دو طرف.
435
+ - **در بستهٔ شاهد گام ۸**، ایستگاه خودش این دو سند را تازه می‌سازد و کنار شاهدها می‌گذارد:
436
+ `15-license-doc.html` · `16-license-doc.md` (اجازه‌نامه) و `17-usage-statement.html` ·
437
+ `18-usage-statement.md` (گواهی استفادهٔ موفق). هر چهار پرونده در مانیفست با اثر انگشت می‌آیند.
438
+ - `diagnose.py` گزارش عیب‌یابی می‌سازد: نسخه‌ها، سلامت هشت‌جزئی، مجوز، اتصال فعال، اثر انگشت موتور،
439
+ وضعیت دفتر و پرونده‌های مهم. یک پرونده برای پشتیبانی کافی است.
440
+ - سند تحلیلی «بفروشم یا دسترسی بدهم؟»: `MATERIALS/money/09-sell-or-grant-access-fa.md`.
441
+
442
+ ## داوری سیگنال ابزارهای دیگر (گام ۶)
443
+
444
+ دیده‌بان‌ها و ماشین‌حساب‌های بازار فارسی، قیمت و فیلتر و قیمت تئوری می‌دهند؛ ولی نمی‌گویند آن
445
+ سیگنال با کارمزد واقعی، اسپرد، نقدشوندگی و نرخ سد می‌مانَد یا می‌افتد. کارت «داوری سیگنال
446
+ ابزارهای دیگر» در گام ۶ همان یک کار را می‌کند:
447
+
448
+ - عددهای سیگنال نرم‌افزار فعلی‌تان را (به شکل JSON) وارد کنید و «داوری کن و برگه بساز» را بزنید.
449
+ - خروجی: «می‌ماند / می‌افتد» با دلیل دروازه‌ها، **نقطهٔ برگشت** (تا کدام قیمت یا پرمیوم معامله
450
+ می‌مانَد)، **فاصله تا مارجین‌کال** با حد نگهداری ۷۰٪ و پول در معرض خطر، اندازهٔ موقعیت، و
451
+ **دو روش حساب** برای بازبینی با ماشین‌حساب.
452
+ - برگهٔ داوری با اثر انگشت `sha256` ساخته می‌شود (`data/signal-verdict.html`) و همان را می‌توانید
453
+ به شرکت بدهید.
454
+
455
+ ```bash
456
+ python signal_judge.py --kind covered --params '{"spot":7000,"strike":7400,"premium":120,"days":30}' --claimed 40
457
+ python signal_judge.py --file my-signal.json --hurdle 0.39 --sheet
458
+ ```
459
+
460
+ سند تحلیلی تمایز و اعتماد: `MATERIALS/money/08-differentiation-and-trust-fa.md`.
461
+
462
+ ## آزمون ۱۰ دقیقه‌ای و پروندهٔ سرمایه‌گذار (گام ۹، کارت‌های ۴ و ۵)
463
+
464
+ دو چیز تازه که کارشان «اثبات» است، نه «وعده»:
465
+
466
+ **آزمون ۱۰ دقیقه‌ای** (`python selftest.py` یا دکمهٔ همان کارت در گام ۹).
467
+ پانزده مورد، هر کدام **دو بار** حساب می‌شود: یک بار با موتور واقعی برنامه و یک بار با «حساب دستی»
468
+ که همان‌جا در کد نوشته شده و با ماشین‌حساب قابل چک است. اگر این دو از هم جدا شوند، مورد **سرخ**
469
+ می‌شود. فهرست کوتاهی از موردها:
470
+
471
+ | مورد | چه چیزی را ثابت می‌کند |
472
+ |---|---|
473
+ | خرید نقدی و فروش آتی، سد و کف حاشیه | تصمیم به عدد بسته است، نه سلیقه |
474
+ | کارمزد گران | با کارمزد ۲٪ همان فرصت بسته می‌شود (حساسیت برنامه به هزینهٔ واقعی) |
475
+ | تبعی، پوشش‌داده‌شده، تساوی پوت‌کال، باکس اسپرد | فرمول‌ها درست‌اند و سود و ریسک بازار جدا شمرده می‌شوند |
476
+ | جریمهٔ نقدشوندگی و اسپرد | فرصت توخالی معرفی نمی‌شود |
477
+ | اندازهٔ موقعیت | سقف ۲۰٪ سرمایه در وجه تضمین رعایت می‌شود |
478
+ | دادهٔ اشتباه | قیمت جابه‌جا وارد شود، برنامه سود رؤیایی نمی‌سازد؛ «مشکوک» اعلام می‌کند |
479
+ | بدون آینده‌نگری | تغییر ستون «نتیجهٔ واقعی گذشته» هیچ تصمیمی را عوض نمی‌کند |
480
+ | زنجیرهٔ هش | عوض‌کردن یک ردیف دفتر، همان لحظه لو می‌رود |
481
+ | روز واقعی | پروندهٔ نمونه یا تأییدنشده، روز واقعی حساب نمی‌شود |
482
+ | شکست دادهٔ زنده | وقتی سرویس جواب نمی‌دهد، عدد ساختگی جای قیمت زنده نمی‌نشیند |
483
+ | تکرارپذیری | یک ورودی، همیشه یک جواب؛ در مسیر تصمیم هیچ مدل زبانی و تصادفی نیست |
484
+
485
+ خروجی: `data/selftest-report.html` (کارنامه) و `data/exam-sheet.html` (برگهٔ آزمون چاپی).
486
+ برگهٔ آزمون را به سرمایه‌گذ��ر بدهید: اول حدس خودش را می‌نویسد، بعد پاسخ و راه چک دستی را می‌بیند.
487
+
488
+ **پروندهٔ سرمایه‌گذار** (`python dossier.py` یا دکمهٔ همان کارت).
489
+ یک صفحهٔ آمادهٔ چاپ که همهٔ شاهدهای همان اجرا را یک‌جا می‌گذارد: قواعد قفل‌شده، نتیجهٔ آزمون با اثر انگشت
490
+ موتور (sha256)، دفتر و کارنامه، پس‌آزمایی، وضعیت اتصال، «آنچه ادعا نمی‌کنیم»، چهار گام راستی‌آزمایی
491
+ مستقل، و شناسنامهٔ پرونده‌ها با اثر انگشت هر پرونده. خروجی: `data/investor-dossier.html` و نسخهٔ متنی
492
+ `data/investor-dossier.md` برای ایمیل.
493
+
494
+ ## مراسم روزانه: یک دکمه در روز، برای دو هفته
495
+
496
+ کل آزمون دو هفته‌ای در یک کار خلاصه شده است. هر روز کاری یکی از این سه راه را بزنید:
497
+
498
+ - در گام ۹: دکمهٔ **«اجرای مراسم امروز»**.
499
+ - روی ویندوز: دوبار کلیک روی `run-daily-trial.bat`.
500
+ - اگر می‌خواهید یادتان نرود: `schedule-daily-trial.bat` یک زمان‌بندی روزانه در ویندوز می‌سازد
501
+ (پیش‌فرض هر روز ساعت ۱۳:۱۵). برای حذف زمان‌بندی:
502
+ `schtasks /delete /tn "Station-Daily-Trial" /f`
503
+
504
+ در هر اجرا این شش کار انجام می‌شود و هیچ سفارشی ارسال نمی‌شود:
505
+
506
+ ۱. قیمت‌ها خوانده می‌شود (زنده، وگرنه پروندهٔ دستی، وگرنه دادهٔ نمونه، با برچسب صادق روی صفحه).
507
+ ۲. موتور ریاضی روی همان قیمت‌ها اجرا می‌شود.
508
+ ۳. سیگنال‌های امروز با ساعت دقیق در دفتر ثبت می‌شوند (زنجیرهٔ هش).
509
+ ۴. ردیف‌های قبلی با قیمت‌های تازه بازسنجی می‌شوند.
510
+ ۵. سالم‌بودن زنجیره بررسی و گزارش سرمایه‌گذار از نو ساخته می‌شود.
511
+ ۶. «کارنامه» به‌روز می‌شود. هر اجرا یک خط در `data/trial-daily.log` می‌ماند.
512
+
513
+ ### کارنامه: از کجا بفهمم وقت خرید دادهٔ زنده و جلسهٔ شرکت رسیده؟
514
+
515
+ کارنامه پنج شرط عددی دارد و تا همه جور نشود، «هنوز نه» می‌گوید و می‌گوید کدام شرط کم است:
516
+
517
+ | شرط | حد لازم | چرا |
518
+ |---|---|---|
519
+ | تداوم روزانه | ۱۰ روز ثبت‌شده | سابقه از یک روز درنمی‌آید |
520
+ | روزهای با دادهٔ واقعی | ۵ روز غیرساختگی | خوراک آزمایشی برای تمرین است، برای ارائه نه. پرونده‌هایی هم که نامشان «نمونه» یا «demo» یا «template» دارد، روز واقعی حساب نمی‌شوند |
521
+ | سهم بازسنجی‌شدهٔ دفتر | ۶۰ درصد | نشان می‌دهد موتور با قیمت تازه هم اجرا می‌شود |
522
+ | حرکت واقعی در دفتر | ۳ حرکت معنادار، دست‌کم یکی بازتر و یکی بسته | هم فرصت تازه، هم فرصتی که بازار برداشته |
523
+ | زنجیرهٔ هش | سالم | دفتر قابل استناد باشد |
524
+
525
+ برای شروع دوباره: `python daily_trial.py --reset --yes` (دفتر، لاگ، گزارش و CSV را پاک می‌کند).
526
+
527
+ ## قالب پروندهٔ اسنپ‌شات
528
+
529
+ ```json
530
+ {"as_of": "1405/06/31", "hurdle": 0.39, "capital": 20000000000,
531
+ "rows": [
532
+ {"symbol": "اهرم", "kind": "basis", "spot": 20000, "future": 22800, "days": 90,
533
+ "margin_per_contract": 20000000, "unit": "قرارداد",
534
+ "liquidity_contracts_per_day": 900, "spread_pct": 0.005},
535
+ {"symbol": "فولاد", "kind": "covered_call", "spot": 7000, "strike": 7600, "premium": 400,
536
+ "days": 45, "margin_per_contract": 7000, "unit": "سهم"}
537
+ ]}
538
+ ```
539
+
540
+ انواع `kind`: `basis` (پایهٔ نقدی‌آتی) · `box` (باکس اسپرد) · `tabei` (تبعی) · `covered_call` (پوشش‌داده‌شده) · `parity` (تساوی پوت‌کال).
541
+
542
+ ## قالب پروندهٔ پس‌آزمایی (CSV)
543
+
544
+ ستون‌های کلیدی: `date, symbol, kind, …` (همان فیلدهای ریاضی هر راهبرد)، `days`، `margin_per_contract`، `liquidity_contracts_per_day`، `spread_pct`، `hurdle`، و مهم‌تر از همه `realized_annualized_pct` = «نتیجهٔ واقعی آن معامله در گذشته».
545
+
546
+ فایل نمونه: `demo/history-demo.csv` (ساختگی، ۱۰۰ سطر، برای آموزش). برای ارائه به شرکت، دادهٔ واقعی خودتان را بدهید.
547
+
548
+ ## پنل مدیریت: دسترسی، ورود و تغییر رمز
549
+
550
+ سه بخش از برنامه با ورود باز می‌شوند و روی صفحهٔ اص��ی نیستند: **بررسی سلامت**، **مجوز دسترسی و
551
+ گزارش عیب‌یابی**، و **گواهی استفادهٔ موفق**. آدرس پنل: `http://127.0.0.1:8765/admin` (یا دکمهٔ
552
+ «باز کردن پنل مدیریت» در گام ۱).
553
+
554
+ - رمز **متن‌رو** ذخیره نمی‌شود؛ فقط نمک و هش PBKDF2-SHA256 در `config/admin.json` با اجازهٔ
555
+ خواندنِ فقط-صاحب-پرونده.
556
+ - تغییر رمز: `python3 adminauth.py --set-pass 'رمز-تازه' --set-id mafhoom`
557
+ - بی‌رمز و با متغیر محیطی (اگر نمی‌خواهید چیزی روی دیسک بماند):
558
+ `STATION_ADMIN_ID` و `STATION_ADMIN_PASS` را ست کنید؛ اولویت با همین‌هاست.
559
+ - توکن ورود یک‌ساعته است (با هر استفاده تازه می‌شود) و پنج تلاش ناموفق در پنج دقیقه، ورود را
560
+ موقتاً می‌بندد.
561
+ - پرونده‌های پنل (گزارش عیب‌یابی، گواهی استفاده، سند بفروشم یا دسترسی بدهم) بدون ورود باز نمی‌شوند؛
562
+ آزمون تعاملی همین را می‌سنجد.
563
+
564
+ صادقانه دربارهٔ مرزهایش: پنل برای **همین رایانه** است. اگر آن را روی شبکه باز کردید، HTTP ساده
565
+ رمز را در برابر شنود محافظت نمی‌کند؛ پشت `https` یا فقط روی `127.0.0.1` بگذارید. پنل چند کاربر و
566
+ نقش ندارد و لاگ دسترسی جدا نمی‌سازد.
567
+
568
+ ## آزمون‌ها
569
+
570
+ ```bash
571
+ bash run-tests.sh # ۶۵۸ آزمون واحد + آزمون ساخت رابط + پس‌آزمایی نمونه
572
+ python3 selftest.py # آزمون ۱۰ دقیقه‌ای (کارنامه + برگهٔ آزمون)
573
+ python3 dossier.py # پروندهٔ سرمایه‌گذار
574
+ python3 station.py --smoke # آزمون سلامت رابط دسکتاپ
575
+ python3 mock_feed.py # خوراک آزمایشی (اختیاری، برای تمرین)
576
+ python3 license.py --status # وضعیت اجازه‌نامهٔ دسترسی
577
+ python3 license.py --grant "نام شرکت" --months 12 --save # صدور اجازه‌نامهٔ نام‌دار
578
+ python3 license.py --ladder # سه پلهٔ پیشنهادی ارائه
579
+ python3 diagnose.py # گزارش عیب‌یابی یک‌کلیکی (برای پشتیبانی)
580
+ python3 signal_judge.py --kind basis --params '{"spot":20000,"future":22800,"days":50}' \
581
+ --margin 2000000 --contracts 10 --price 20000 # داوری سیگنال ابزار دیگر
582
+ python3 investor_test.py --cases # شش پرسش آزمون کور (بدون پاسخ)
583
+ python3 investor_test.py --reveal # همان پرسش‌ها با پاسخ و مسیر محاسبه (برای آماده‌سازی شما)
584
+ python3 investor_test.py --check box_annual --guess 62 --client "نام سرمایه‌گذار" # داوری و ثبت یک حدس
585
+ python3 investor_test.py --ladder # آستانهٔ ریزش راهبردها و اندازهٔ موقعیت
586
+ python3 investor_test.py --flip # نقطهٔ برگشت کارمزد پوشش‌داده‌شده
587
+ python3 investor_test.py --reconcile --symbol فولاد --entry 7000 --exit 7400 --days 30 --units 10
588
+ python3 investor_test.py --sheet # برگهٔ امضادار آزمون کور (زنجیره‌هش‌دار)
589
+ python3 investor_test.py --pledge # پیمان‌نامهٔ نمایش دواِمضا
590
+ python3 investor_test.py --verify # بررسی زنجیرهٔ دفتر آزمون
591
+ python3 ladder.py # سند «چه بخرم / کِی بفروشم / کِی می‌افتد»
592
+ python3 data_sources.py --all # امکان‌سنجی مسیرهای داده پیش از خرید
593
+ python3 daily_trial.py # مراسم امروز (خط فرمان)
594
+ python3 daily_trial.py --status # فقط کارنامه
595
+ python3 autoconnect.py --save # پیدا و فعال‌کردن منبع رایگان سالم
596
+ ```
597
+
598
+ روی ویندوز، دوبار کلیک: `run-gui.bat` · `run-mock-feed.bat` · `run-investor-demo.bat` ·
599
+ `run-daily-trial.bat` · `run-selftest.bat` · `build-dossier.bat` · `run-autoconnect.bat` ·
600
+ `run-investor-test.bat`.
601
+
602
+ پوشش آزمون‌ها: لایهٔ داده (سه حالت + کاوش مسیر + سیاست تلاش دوباره)، پس‌آزمایی، دفتر اتصال و کلید،
603
+ خوراک آزمایشی محلی، دفتر آزمون زنده و زنجیرهٔ هش، مراسم روزانه و کارنامه، اتصال خودکار منابع رایگان،
604
+ اسنپ‌شات تاریخ‌دار دستی، آزمون ۱۰ دقیقه‌ای، پروندهٔ سرمایه‌گذار، و ساخت رابط گرافیکی.
605
+
606
+ آزمون تعاملی رابط مرورگری (اگر node روی رایانه داشته باشید): بررسی واقعی دکمه‌های گام‌ها��
607
+ ۱ تا ۹، از پنل مدیریت و خوش‌آمد تا اتصال خودکار، فرم اعداد کارگزاری، مراسم روزانه، کارنامه،
608
+ آزمون ۱۰ دقیقه‌ای و ساخت پروندهٔ سرمایه‌گذار.
609
+
610
+ ```bash
611
+ cd /home/user && npm i jsdom && node test-interactive.mjs
612
+ ```
613
+
614
+ ## نکات ایمنی و قانونی
615
+
616
+ - برنامه **هیچ سفارشی ارسال نمی‌کند**؛ معاملات الگوریتمی خودکار در بورس و فرابورس ایران «تا اطلاع ثانوی» ممنوع است.
617
+ - کلید سرویس فقط در حافظهٔ همین برنامه نگه داشته می‌شود؛ ذخیرهٔ آن روی رایانه فقط با تیک صریح خودتان
618
+ و در پروندهٔ `config/keys.local.json` انجام می‌شود. آن پرونده را در گیت یا پیام‌رسان نفرستید.
619
+ - هیچ سود تضمینی وجود ندارد؛ خروجی «پیشنهاد و هشدار» است و تصمیم با شماست.
620
+ - درگاه ریسک «باورپذیری» وجود دارد: هر بازده بزرگ‌تر از ۲۵۰ درصد (آربیتراژ) یا ۴۰۰ درصد (اهرمی) به‌معنای دادهٔ غلط یا کهنه است، نه فرصت تاریخی.
621
+
622
+ ## تهیه‌کننده و دولوپر
623
+
624
+ **دولوپر: مهندس مسعود مجربیان** · همراه: 09126630554 · Telegram: [Mojarabian](https://t.me/Mojarabian) · Instagram: [Mojarabian.Art](https://instagram.com/Mojarabian.Art)
625
+
626
+ ✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · 📱 [+989126630554](tel:+989126630554) · ✈️ [Telegram: Mojarabian](https://t.me/Mojarabian) · 📸 [Instagram: Mojarabian.Art](https://www.instagram.com/Mojarabian.Art/)
station/adminauth.py ADDED
@@ -0,0 +1,217 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env python3
2
+ # -*- coding: utf-8 -*-
3
+ """پنل مدیریت — احراز هویت محلی با شناسه و رمز (نسخهٔ ۰.۱.۰).
4
+
5
+ سه بخش برنامه (بررسی سلامت، مجوز دسترسی/عیب‌یابی، گواهی استفاده) به «پنل مدیریت» رفته‌اند و
6
+ این پوشه کلید ورود آن‌ها است:
7
+
8
+ · رمز هرگز به‌صورت متن ذخیره نمی‌شود؛ فقط «نمک» و «هش» PBKDF2-SHA256 در `config/admin.json`.
9
+ · اگر متغیرهای محیطی `STATION_ADMIN_ID` و `STATION_ADMIN_PASS` ست شده باشند، همان‌ها
10
+ اولویت دارند (مناسب زمانی که نمی‌خواهید رمز روی دیسک بماند).
11
+ · توکن ورود کوتاه‌عمر است و پنجرهٔ خطای ورود هم محدود می‌شود (پنج تلاش در پنج دقیقه).
12
+ · پنل برای همین رایانه است؛ اگر روی شبکه بازش کردید، آن را پشت HTTPS بگذارید.
13
+
14
+ کارهایی که این پوشه نمی‌کند (صادقانه): رمز را از رهگیری شبکه در HTTP ساده حفظ نمی‌کند؛
15
+ مدیریت چند کاربر و نقش ندارد؛ لاگِ دسترسی جداگانه نمی‌سازد.
16
+ """
17
+ from __future__ import annotations
18
+
19
+ import argparse
20
+ import hashlib
21
+ import hmac
22
+ import json
23
+ import os
24
+ import secrets
25
+ import sys
26
+ import time
27
+ from pathlib import Path
28
+
29
+ BASE = Path(__file__).resolve().parent
30
+ CONFIG = BASE / "config" / "admin.json"
31
+ VERSION = "0.1.0"
32
+
33
+ TOKEN_TTL_SECONDS = 60 * 60 # یک ساعت بی‌کاری
34
+ FAIL_WINDOW_SECONDS = 5 * 60
35
+ FAIL_LIMIT = 5
36
+ PBKDF2_ROUNDS = 200_000
37
+ MIN_PASS_LENGTH = 8
38
+
39
+ SESSIONS: dict[str, dict] = {}
40
+ FAILS: dict[str, list[float]] = {}
41
+
42
+
43
+ # ------------------------------------------------------------------ تنظیمات
44
+
45
+ def _hash(password: str, salt_hex: str) -> str:
46
+ dk = hashlib.pbkdf2_hmac("sha256", password.encode("utf-8"), bytes.fromhex(salt_hex),
47
+ PBKDF2_ROUNDS)
48
+ return dk.hex()
49
+
50
+
51
+ def _same(a, b) -> bool:
52
+ """مقایسهٔ زمان‌ثابت که با متن فارسی هم کار می‌کند (compare_digest فقط ASCII می‌پذیرد)."""
53
+ return hmac.compare_digest(str(a or "").encode("utf-8"), str(b or "").encode("utf-8"))
54
+
55
+
56
+ def env_credentials() -> tuple[str, str] | None:
57
+ """اگر متغیرهای محیطی ست باشند، همان‌ها معتبرند و فایل خوانده نمی‌شود."""
58
+ user = os.environ.get("STATION_ADMIN_ID", "").strip()
59
+ password = os.environ.get("STATION_ADMIN_PASS", "")
60
+ return (user, password) if user and password else None
61
+
62
+
63
+ def load_config(path: Path | str | None = None) -> dict | None:
64
+ p = Path(path or CONFIG)
65
+ if not p.exists():
66
+ return None
67
+ try:
68
+ data = json.loads(p.read_text(encoding="utf-8"))
69
+ except (json.JSONDecodeError, OSError):
70
+ return None
71
+ return data if isinstance(data, dict) and data.get("id") and data.get("hash") else None
72
+
73
+
74
+ def set_credentials(user_id: str, password: str, *, path: Path | str | None = None) -> Path:
75
+ """شناسه و رمز را ذخیره می‌کند (فقط هش). رمز کوتاه رد می‌شود."""
76
+ user_id = str(user_id or "").strip()
77
+ if not user_id:
78
+ raise ValueError("شناسهٔ ورود خالی است.")
79
+ if len(str(password or "")) < MIN_PASS_LENGTH:
80
+ raise ValueError(f"رمز باید دست‌کم {MIN_PASS_LENGTH} نویسه باشد.")
81
+ p = Path(path or CONFIG)
82
+ p.parent.mkdir(parents=True, exist_ok=True)
83
+ salt = secrets.token_hex(16)
84
+ p.write_text(json.dumps({"version": VERSION, "id": user_id, "salt": salt,
85
+ "rounds": PBKDF2_ROUNDS, "hash": _hash(password, salt)},
86
+ ensure_ascii=False, indent=1), encoding="utf-8")
87
+ try:
88
+ p.chmod(0o600) # فقط صاحب پرونده بخواند
89
+ except OSError:
90
+ pass
91
+ return p
92
+
93
+
94
+ def is_configured(path: Path | str | None = None) -> bool:
95
+ return env_credentials() is not None or load_config(path) is not None
96
+
97
+
98
+ def verify_credentials(user_id: str, password: str, *, path: Path | str | None = None) -> bool:
99
+ """مقایسهٔ زمان‌ثابت؛ شناسهٔ اشتباه هم همان جواب را می‌دهد (بدون افشای کدام غلط بود)."""
100
+ env = env_credentials()
101
+ if env:
102
+ same_id = _same(user_id, env[0])
103
+ same_pass = _same(password, env[1])
104
+ return bool(same_id and same_pass)
105
+ cfg = load_config(path)
106
+ if not cfg:
107
+ return False
108
+ rounds = int(cfg.get("rounds") or PBKDF2_ROUNDS)
109
+ salt = str(cfg.get("salt") or "")
110
+ try:
111
+ dk = hashlib.pbkdf2_hmac("sha256", str(password or "").encode("utf-8"),
112
+ bytes.fromhex(salt), rounds)
113
+ except ValueError:
114
+ return False
115
+ same_id = _same(user_id, cfg.get("id"))
116
+ same_pass = _same(dk.hex(), cfg.get("hash"))
117
+ return bool(same_id and same_pass)
118
+
119
+
120
+ # ------------------------------------------------------------------ توکن و محدودیت
121
+
122
+ def issue_token(user_id: str, *, now: float | None = None) -> str:
123
+ t = now if now is not None else time.time()
124
+ token = secrets.token_hex(24)
125
+ SESSIONS[token] = {"id": user_id, "expires": t + TOKEN_TTL_SECONDS, "made": t}
126
+ return token
127
+
128
+
129
+ def check_token(token: str | None, *, now: float | None = None) -> bool:
130
+ """توکن معتبر است؟ هر بررسی، عمر توکن را تازه می‌کند (بی‌کاری = انقضا)."""
131
+ if not token:
132
+ return False
133
+ rec = SESSIONS.get(str(token))
134
+ if not rec:
135
+ return False
136
+ t = now if now is not None else time.time()
137
+ if rec["expires"] < t:
138
+ SESSIONS.pop(str(token), None)
139
+ return False
140
+ rec["expires"] = t + TOKEN_TTL_SECONDS
141
+ return True
142
+
143
+
144
+ def revoke_token(token: str | None) -> bool:
145
+ return bool(SESSIONS.pop(str(token), None))
146
+
147
+
148
+ def active_tokens() -> int:
149
+ return len(SESSIONS)
150
+
151
+
152
+ def rate_limited(ip: str, *, now: float | None = None) -> bool:
153
+ """آیا این نشانی تازه بیش از حد خطا زده است؟"""
154
+ t = now if now is not None else time.time()
155
+ hits = [x for x in FAILS.get(str(ip), []) if t - x < FAIL_WINDOW_SECONDS]
156
+ FAILS[str(ip)] = hits
157
+ return len(hits) >= FAIL_LIMIT
158
+
159
+
160
+ def note_failure(ip: str, *, now: float | None = None) -> int:
161
+ t = now if now is not None else time.time()
162
+ hits = [x for x in FAILS.get(str(ip), []) if t - x < FAIL_WINDOW_SECONDS]
163
+ hits.append(t)
164
+ FAILS[str(ip)] = hits
165
+ return len(hits)
166
+
167
+
168
+ def reset_failures(ip: str) -> None:
169
+ FAILS.pop(str(ip), None)
170
+
171
+
172
+ def login(user_id: str, password: str, *, ip: str = "؟", path: Path | str | None = None,
173
+ now: float | None = None) -> dict:
174
+ """یک‌جا: محدودیت، بررسی، توکن. خروجی همیشه «ok» دارد تا کارساز ساده بماند."""
175
+ if not is_configured(path):
176
+ return {"ok": False, "error": ("هنوز شناسه و رمز پنل ساخته نشده. یک‌بار این را اجرا "
177
+ "کنید: python3 adminauth.py --set-pass <رمز>")}
178
+ if rate_limited(ip, now=now):
179
+ return {"ok": False, "rate_limited": True,
180
+ "error": "تلاش‌های ناموفق زیاد بود؛ چند دقیقه صبر کنید."}
181
+ if not verify_credentials(user_id, password, path=path):
182
+ left = FAIL_LIMIT - note_failure(ip, now=now)
183
+ return {"ok": False, "error": f"شناسه یا رمز درست نیست. {max(left, 0)} تلاش تا قفل موقت."}
184
+ reset_failures(ip)
185
+ token = issue_token(str(user_id), now=now)
186
+ return {"ok": True, "token": token, "ttl_seconds": TOKEN_TTL_SECONDS,
187
+ "expires_in_minutes": TOKEN_TTL_SECONDS // 60}
188
+
189
+
190
+ # ------------------------------------------------------------------ خط فرمان
191
+
192
+ def main(argv: list[str] | None = None) -> int:
193
+ ap = argparse.ArgumentParser(description="کلید ورود پنل مدیریت (شناسه و رمز)")
194
+ ap.add_argument("--set-id", default="", help="شناسهٔ ورود")
195
+ ap.add_argument("--set-pass", default="", help="رمز ورود (فقط هش ذخیره می‌شود)")
196
+ ap.add_argument("--status", action="store_true", help="وضعیت پیکربندی")
197
+ ap.add_argument("--check", nargs=2, metavar=("ID", "PASS"), help="آزمودن یک جفت شناسه/رمز")
198
+ a = ap.parse_args(argv)
199
+ if a.set_pass:
200
+ path = set_credentials(a.set_id or "admin", a.set_pass)
201
+ print(f"ذخیره شد: {path} (فقط هش؛ رمز روی دیسک نیست)")
202
+ return 0
203
+ if a.check:
204
+ print("درست است ✅" if verify_credentials(a.check[0], a.check[1]) else "درست نیست ✗")
205
+ return 0 if verify_credentials(*a.check) else 1
206
+ if is_configured():
207
+ cfg = load_config()
208
+ where = "متغیر محیطی" if env_credentials() else f"پروندهٔ {CONFIG}"
209
+ print(f"پنل مدیریت پیکربندی شده است — از {where}"
210
+ + (f" · شناسه: {cfg['id']}" if cfg else ""))
211
+ return 0
212
+ print("پنل مدیریت هنوز پیکربندی نشده است.")
213
+ return 1
214
+
215
+
216
+ if __name__ == "__main__":
217
+ raise SystemExit(main())
station/autoconnect.py ADDED
@@ -0,0 +1,306 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env python3
2
+ # -*- coding: utf-8 -*-
3
+ """اتصال خودکار — «خودت بگرد و ببین کدام منبع رایگان امروز کار می‌کند».
4
+
5
+ ایدهٔ ساده است و صادقانه: من (سازندهٔ برنامه) نمی‌توانم از این‌طرف مرزها تست کنم که فلان
6
+ سرویس ایرانی امروز چه پاسخی می‌دهد. پس برنامه روی رایانهٔ خودِ شما، یکی‌یکی این منابع را
7
+ امتحان می‌کند، پاسخ را می‌خواند، عدد را از نظر عقلی می‌سنجد، و به شما می‌گوید کدام کار کرد
8
+ و کدام نه — با دلیل. آخرش، اولین منبع سالم را به‌عنوان اتصال فعال ذخیره می‌کند.
9
+
10
+ هیچ کلیدی لازم نیست و هیچ هزینه‌ای ندارد. اگر همه شکست خوردند، برنامه خودش می‌گوید
11
+ «برو سراغ پروندهٔ دستی» — که آن هم کار می‌کند.
12
+
13
+ اجرا: python autoconnect.py (گزارش کامل، بدون ذخیره)
14
+ python autoconnect.py --save (منبع سالم را ذخیره و فعال کن)
15
+ """
16
+ from __future__ import annotations
17
+
18
+ import argparse
19
+ import json
20
+ import time
21
+ from pathlib import Path
22
+
23
+ VERSION = "0.1.0"
24
+ BASE = Path(__file__).resolve().parent
25
+ import sys
26
+
27
+ if str(BASE) not in sys.path:
28
+ sys.path.insert(0, str(BASE))
29
+
30
+ import datafeed # noqa: E402
31
+ import connections as conn # noqa: E402
32
+
33
+ # هر داوطلب: نشانی، چند مسیر احتمالی قیمت، و توضیح فارسی برای کاربر.
34
+ # نکتهٔ مهم: این‌ها «حدس‌های آزمون‌شدنی» هستند، نه وعده. سرویس‌ها ساختار پاسخشان را عوض می‌کنند.
35
+ VERIFIED_NOTE = "آزمون از محیط سازنده (شهریور ۱۴۰۵) پاسخ سالم داد؛ روی رایانهٔ شما دوباره آزموده می‌شود."
36
+
37
+ CANDIDATES: list[dict] = [
38
+ {
39
+ "name": "tgju-dollar",
40
+ "label": "tgju — قیمت دلار آزاد",
41
+ "profile_label": "tgju — دلار (رایگان، خودکار پیدا شد)",
42
+ "url_template": "https://api.tgju.org/v1/market/indicator/summary-table-data/price_dollar_rl",
43
+ "paths": ["data.0.3", "data.0.p", "data.0.price", "data.price", "price"],
44
+ "plausible": (10_000, 500_000_000),
45
+ "verified": True,
46
+ "note": ("قیمت پایانی دلار آزاد در ستون چهارم سطر اول (`data.0.3`). آزمون‌شده: با یک نقطهٔ "
47
+ "پایانی مستقل (call1.tgju.org/ajax.json) هم‌خوان بود."),
48
+ },
49
+ {
50
+ "name": "tgju-coin",
51
+ "label": "tgju — سکه امامی",
52
+ "profile_label": "tgju — سکه (رایگان، خودکار پیدا شد)",
53
+ "url_template": "https://api.tgju.org/v1/market/indicator/summary-table-data/sekeb",
54
+ "paths": ["data.0.3", "data.0.p", "data.0.price", "price"],
55
+ "plausible": (1_000_000, 20_000_000_000),
56
+ "verified": True,
57
+ "note": ("سکهٔ امامی (`sekeb`) با همان قالب tgju. نام‌های دیگر همین خانواده: geram18 (گرم "
58
+ "طلای ۱۸) · nim (نیم) · rob (ربع)."),
59
+ },
60
+ {
61
+ "name": "tsetmc-cdn",
62
+ "label": "tsetmc — قیمت پایانی (با کد نماد)",
63
+ "profile_label": "tsetmc — قیمت پایانی (رایگان، خودکار پیدا شد)",
64
+ "url_template": "https://cdn.tsetmc.com/api/ClosingPrice/GetClosingPriceDailyList/{symbol}/0",
65
+ "paths": ["closingPriceDaily.0.pClosing", "closingPriceDaily.0.pDrCotVal",
66
+ "closingPriceDaily.0.priceYesterday"],
67
+ "plausible": (10, 100_000_000),
68
+ "needs_code": True,
69
+ "search_url": "https://cdn.tsetmc.com/api/Instrument/GetInstrumentSearch/{symbol}",
70
+ "search_paths": ["instrumentSearch.0.insCode", "instrumentSearch.0.instrumentID"],
71
+ "note": "منبع رسمی و رایگان. در نشانی به‌جای نام نماد، «کد نماد» می‌رود؛ برنامه خودش کد را پیدا می‌کند.",
72
+ },
73
+ {
74
+ "name": "exchange-irt",
75
+ "label": "صرافی ایرانی — نرخ لحظه‌ای ریالی (تأییدشده)",
76
+ "profile_label": "صرافی ایرانی — نرخ لحظه‌ای (رایگان، تأییدشده)",
77
+ "url_template": "https://api.exir.io/v2/ticker?symbol={symbol}",
78
+ "paths": ["last", "close", "data.last"],
79
+ "plausible": (1_000, 50_000_000_000),
80
+ "verified": True,
81
+ "note": ("بازارهای ریالی این صرافی: usdt-irt · btc-irt · eth-irt · ada-irt · ton-irt و چند تای دیگر. "
82
+ "برای اینکه هر ردیف قیمت خودش را بگیرد، در فیلد «کد نماد» آن ردیف نام ��ازار را بنویسید "
83
+ "(مثلاً usdt-irt). کاربردش اثبات کارکرد اتصال زندهٔ واقعی بدون کلید است، نه ساختن سیگنال سهام."),
84
+ },
85
+ ]
86
+
87
+ # نشانه‌های عدد بی‌معنی: تاریخ، شمارنده، یا درصد کوچک
88
+ TOO_BIG_FOR_PRICE = 1e15
89
+
90
+
91
+ def judge(value: float | None, plausible: tuple[float, float]) -> tuple[bool, str]:
92
+ """آیا این عدد می‌تواند «قیمت» باشد؟ نه تاریخ، نه شمارنده، نه صفر."""
93
+ if value is None:
94
+ return False, "عدد پیدا نشد"
95
+ if value <= 0:
96
+ return False, "عدد صفر یا منفی بود"
97
+ if value > TOO_BIG_FOR_PRICE:
98
+ return False, "عدد شبیه تاریخ یا شمارنده است، نه قیمت"
99
+ lo, hi = plausible
100
+ if not (lo <= value <= hi):
101
+ return False, f"عدد {value:,.0f} بیرون بازهٔ باورپذیر {lo:,.0f} تا {hi:,.0f} است"
102
+ return True, "سالم"
103
+
104
+
105
+ def try_candidate(cand: dict, *, symbol: str = "اهرم", timeout: float = 10.0,
106
+ allow_network: bool = True, resolve_code: bool = True) -> dict:
107
+ """یک داوطلب را امتحان می‌کند و نتیجه را با دلیل برمی‌گرداند."""
108
+ out = {"name": cand["name"], "label": cand["label"], "ok": False, "value": None,
109
+ "json_path": "", "reason": "", "url": "", "moved": None, "resolved_code": None}
110
+ if not allow_network:
111
+ out["reason"] = "دسترسی شبکه بسته است"
112
+ return out
113
+ url_symbol = symbol
114
+ if cand.get("needs_code"):
115
+ code, why = resolve_symbol_code(cand, symbol, timeout=timeout)
116
+ if not code:
117
+ out["reason"] = f"کد نماد پیدا نشد ({why})"
118
+ return out
119
+ url_symbol = str(code)
120
+ out["resolved_code"] = str(code)
121
+ if not resolve_code:
122
+ out["reason"] = "کد نماد پیدا شد ولی استفاده نشد"
123
+ return out
124
+ from urllib.parse import quote as _q
125
+ url = str(cand["url_template"]).replace("{symbol}", _q(str(url_symbol)))
126
+ out["url"] = url
127
+ text, status = datafeed.fetch(url, timeout=timeout, retries=0, cache_name=f"probe-{cand['name']}.json",
128
+ cache_seconds=0, stale_ok=False)
129
+ if not text:
130
+ out["reason"] = f"پاسخی نیامد ({status})"
131
+ return out
132
+ try:
133
+ payload = json.loads(text)
134
+ except Exception:
135
+ out["reason"] = "پاسخ JSON نبود (شاید صفحهٔ HTML یا بسته‌شدن دسترسی)"
136
+ return out
137
+ tried = []
138
+ for path in cand.get("paths", []):
139
+ value = datafeed.dig(payload, path)
140
+ if isinstance(value, str):
141
+ try:
142
+ value = float(value.replace(",", ""))
143
+ except ValueError:
144
+ value = None
145
+ if isinstance(value, (int, float)) and not isinstance(value, bool):
146
+ ok, why = judge(float(value), cand.get("plausible", (0, TOO_BIG_FOR_PRICE)))
147
+ tried.append(f"{path}={float(value):,.0f} → {why}")
148
+ if ok:
149
+ out.update({"ok": True, "value": float(value), "json_path": path,
150
+ "reason": "عدد سالم از مسیر " + path})
151
+ break
152
+ else:
153
+ tried.append(f"{path}: خالی")
154
+ if not out["ok"]:
155
+ keys = ", ".join(list(payload)[:6]) if isinstance(payload, dict) else "فهرست"
156
+ out["reason"] = "مسیر عدد سالم پیدا نشد · " + " · ".join(tried[:3]) + f" · کلیدهای پاسخ: {keys}"
157
+ return out
158
+ # آزمون دوم: قیمت در دو خواندن پشت‌سرهم نباید مسخره بپرد
159
+ time.sleep(0.4)
160
+ text2, _ = datafeed.fetch(url, timeout=timeout, retries=0, cache_name=f"probe2-{cand['name']}.json",
161
+ stale_ok=False,
162
+ cache_seconds=0)
163
+ if text2:
164
+ try:
165
+ v2 = datafeed.dig(json.loads(text2), out["json_path"])
166
+ if isinstance(v2, (int, float)) and isinstance(out["value"], (int, float)) and out["value"]:
167
+ out["moved"] = round(abs(float(v2) - out["value"]) / float(out["value"]), 6)
168
+ except Exception:
169
+ pass
170
+ return out
171
+
172
+
173
+ def resolve_symbol_code(cand: dict, symbol: str, *, timeout: float = 10.0) -> tuple[str | None, str]:
174
+ """کد نماد (insCode) را از جست‌وجوی tsetmc درمی‌آورد."""
175
+ from urllib.parse import quote as _q
176
+ search = str(cand.get("search_url", "")).replace("{symbol}", _q(symbol))
177
+ if not search:
178
+ return None, "نشانی جست‌وجو نداشت"
179
+ text, status = datafeed.fetch(search, timeout=timeout, retries=0,
180
+ cache_name=f"search-{symbol}.json", cache_seconds=0, stale_ok=False)
181
+ if not text:
182
+ return None, status
183
+ try:
184
+ payload = json.loads(text)
185
+ except Exception:
186
+ return None, "پاسخ جست‌وجو JSON نبود"
187
+ for path in cand.get("search_paths", []):
188
+ value = datafeed.dig(payload, path)
189
+ if isinstance(value, (str, int)) and str(value).strip().isdigit():
190
+ return str(value).strip(), "ok"
191
+ return None, "کد در پاسخ نبود"
192
+
193
+
194
+ def enrich_snapshot_with_codes(rows: list[dict], cand: dict, *, timeout: float = 10.0,
195
+ limit: int = 8, progress=None) -> tuple[list[dict], list[str]]:
196
+ """برای منابعی که «کد نماد» می‌خواهند، کد هر نماد را پیدا و در ردیف‌ها می‌نویسد.
197
+
198
+ این‌طور کاربر لازم نیست برای هر سهم، کد نماد را دستی از سایت بردارد.
199
+ """
200
+ notes: list[str] = []
201
+ if not cand.get("needs_code"):
202
+ return rows, notes
203
+ for row in rows[:limit]:
204
+ symbol = str(row.get("symbol", "")).strip()
205
+ if not symbol or str(row.get("feed_symbol", "")).strip():
206
+ continue
207
+ code, why = resolve_symbol_code(cand, symbol, timeout=timeout)
208
+ if code:
209
+ row["feed_symbol"] = code
210
+ notes.append(f"{symbol}: کد نماد {code} پیدا و در ردیف نوشته شد.")
211
+ else:
212
+ notes.append(f"{symbol}: کد نماد پیدا نشد ({why}) — دستی از سایت بردارید و در ستون «کد نماد» بنویسید.")
213
+ if progress:
214
+ progress(notes[-1])
215
+ return rows, notes
216
+
217
+
218
+ def autoconnect(*, candidates: list[dict] | None = None, symbol: str = "اهرم",
219
+ timeout: float = 10.0, allow_network: bool = True, save: bool = False,
220
+ progress=None) -> dict:
221
+ """همهٔ داوطلبان را امتحان می‌کند و در صورت خواستن، منبع سالم را ذخیره و فعال می‌کند."""
222
+ cands = candidates if candidates is not None else CANDIDATES
223
+ # منابع تأییدشدهٔ قبلی اول امتحان می‌شوند؛ در نتیجه زودتر به جواب می‌رسیم.
224
+ cands = sorted(cands, key=lambda c: 0 if c.get("verified") else 1)
225
+ results: list[dict] = []
226
+ winner: dict | None = None
227
+ for cand in cands:
228
+ if progress:
229
+ progress(f"امتحان: {cand['label']}")
230
+ res = try_candidate(cand, symbol=symbol, timeout=timeout, allow_network=allow_network)
231
+ results.append(res)
232
+ if res["ok"] and winner is None:
233
+ winner = res
234
+ saved: dict | None = None
235
+ if winner and save:
236
+ store = conn.load_store()
237
+ cand = next(c for c in cands if c["name"] == winner["name"])
238
+ store["profiles"] = [p for p in store.get("profiles", []) if p.get("name") != cand["name"]]
239
+ prof = conn.upsert_profile(store, {
240
+ "name": cand["name"], "label": cand.get("profile_label", cand["label"]),
241
+ "cost": conn.FREE, "url_template": cand["url_template"], "json_path": winner["json_path"],
242
+ "key_header": "", "key_query_name": "", "env_key": "", "tested": True,
243
+ "note": f"خودکار پیدا شد ({time.strftime('%Y-%m-%d')}) · {cand.get('note', '')}",
244
+ "gives": cand.get("note", ""),
245
+ "after": "قیمت پایه از همین منبع خوانده می‌شود و ستون تازگی داده سبز می‌ماند.",
246
+ "steps": "همین حالا فعال شد؛ برای عوض‌کردن، از دفتر اتصال پروفایل دیگری انتخاب کنید.",
247
+ })
248
+ conn.select_profile(store, prof["name"])
249
+ conn.save_store(store)
250
+ saved = prof
251
+ working = [r for r in results if r["ok"]]
252
+ if working:
253
+ summary = (f"{len(working)} منبع رایگان سالم پیدا شد. "
254
+ f"بهترین: {working[0]['label']} با قیمت {working[0]['value']:,.0f}.")
255
+ else:
256
+ summary = ("هیچ‌کدام از منابع رایگان جواب نداد. اشکالی ندارد: پروندهٔ دستی و خوراک آزمایشی "
257
+ "هم کار می‌کنند. دلیل هر شکست را در جدول ببینید.")
258
+ return {"ok": bool(working), "results": results, "winner": winner, "saved": saved,
259
+ "summary": summary, "count_ok": len(working), "tested_at": time.strftime("%Y-%m-%d %H:%M")}
260
+
261
+
262
+ def format_report(rep: dict) -> str:
263
+ lines = [f"اتصال خودکار — {rep['tested_at']}", rep["summary"], ""]
264
+ for r in rep["results"]:
265
+ mark = "✓" if r["ok"] else "✗"
266
+ lines.append(f" {mark} {r['label']}: {r['reason']}")
267
+ if r["url"]:
268
+ lines.append(f" نشانی: {r['url']}")
269
+ if rep.get("saved"):
270
+ lines.append("")
271
+ lines.append(f"ذخیره شد: {rep['saved']['label']} (در دفتر اتصال، فعال)")
272
+ return "\n".join(lines)
273
+
274
+
275
+ def main(argv: list[str] | None = None) -> int:
276
+ ap = argparse.ArgumentParser(description="پیدا کردن خودکار یک منبع دادهٔ رایگان سالم")
277
+ ap.add_argument("--save", action="store_true", help="منبع سالم را ذخیره و فعال کن")
278
+ ap.add_argument("--symbol", default="اهرم", help="نماد آزمایشی")
279
+ ap.add_argument("--timeout", type=float, default=10.0)
280
+ ap.add_argument("--offline", action="store_true", help="بدون شبکه (فقط برای آزمون)")
281
+ ap.add_argument("--codes", action="store_true",
282
+ help="اگر منبع برنده «کد نماد» می‌خواهد، کد نمادهای اسنپ‌شات را پیدا و ذخیره کن")
283
+ ap.add_argument("--version", action="store_true")
284
+ args = ap.parse_args(argv)
285
+ if args.version:
286
+ print(f"autoconnect {VERSION}")
287
+ return 0
288
+ rep = autoconnect(symbol=args.symbol, timeout=args.timeout, allow_network=not args.offline,
289
+ save=args.save, progress=lambda m: print("· " + m))
290
+ if args.codes and rep.get("winner"):
291
+ cand = next((c for c in CANDIDATES if c["name"] == rep["winner"]["name"]), {})
292
+ snap = datafeed.load_snapshot_rows(BASE / "data" / "current-snapshot.json")
293
+ if snap.get("rows"):
294
+ rows, notes = enrich_snapshot_with_codes(snap["rows"], cand, timeout=args.timeout)
295
+ if any(r.get("feed_symbol") for r in rows):
296
+ out = datafeed.save_dated_snapshot(rows, note="کد نمادها خودکار پر شد")
297
+ print(f"کد نمادها در {out} ذخیره شد.")
298
+ for n in notes:
299
+ print("· " + n)
300
+ print()
301
+ print(format_report(rep))
302
+ return 0 if rep["ok"] else 1
303
+
304
+
305
+ if __name__ == "__main__":
306
+ raise SystemExit(main())
station/backtest.py ADDED
@@ -0,0 +1,403 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env python3
2
+ # -*- coding: utf-8 -*-
3
+ """پس‌آزمایی (Backtest) — همان موتوری که در تصمیم زنده به کار می‌رود، روی دادهٔ تاریخ.
4
+
5
+ چرا مهم است: هر عددی که روی کاغذ خوب به نظر می‌رسد، باید روی دادهٔ واقعی گذشته
6
+ آزمایش شود. این برنامه همان دروازه‌های ریسک زنده را روی تاریخ اجرا می‌کند،
7
+ «برنده» و «بازنده» را جدا می‌شمارد، و خطای پیش‌بینی را عدد می‌کند.
8
+
9
+ قاعدهٔ ضد خطای آینده‌نگری: تصمیم هر سطر فقط از فیلدهای همان سطر (و ستون نرخ سد همان تاریخ)
10
+ گرفته می‌شود. ستون `realized_annualized_pct` که «نتیجهٔ واقعی» است، فقط در سنجش
11
+ به کار می‌رود و در تصمیم هیچ نقشی ندارد؛ این نکته در آزمون‌ها هم بررسی می‌شود.
12
+ """
13
+ from __future__ import annotations
14
+
15
+ import csv
16
+ import html
17
+ import json
18
+ import math
19
+ import sys
20
+ from dataclasses import dataclass, field
21
+ from datetime import datetime, timezone
22
+ from pathlib import Path
23
+
24
+ VERSION = "0.1.0"
25
+ BASE = Path(__file__).resolve().parent
26
+ DESK_DIR = (BASE.parent / "desk").resolve()
27
+
28
+ if str(DESK_DIR) not in sys.path:
29
+ sys.path.insert(0, str(DESK_DIR))
30
+
31
+ try: # موتور زنده؛ همین موتور در پس‌آزمایی هم اجرا می‌شود
32
+ import desk as live_desk # type: ignore
33
+ except Exception as e: # pragma: no cover
34
+ live_desk = None # type: ignore
35
+ _IMPORT_ERROR = e
36
+
37
+ CREDIT = ("تهیه‌کننده: Masoud Mojarabian · https://www.instagram.com/Mojarabian.Art/ · "
38
+ "tel:+989126630554 · https://t.me/Mojarabian")
39
+
40
+ KIND_LABELS = {
41
+ "basis": "پایهٔ نقدی‌آتی",
42
+ "box": "باکس اسپرد",
43
+ "tabei": "اوراق تبعی",
44
+ "covered_call": "پوشش‌داده‌شده",
45
+ "parity": "تساوی پوت‌کال",
46
+ }
47
+
48
+ DEFAULT_RULES = {
49
+ "min_edge_arbitrage_pct": 3.0,
50
+ "min_edge_leveraged_pct": 5.0,
51
+ "min_liquidity_contracts_per_day": 20,
52
+ "max_spread_pct": 0.03,
53
+ "position_weight": 0.25, # سهم هر معامله از سرمایه در شبیه‌سازی منحنی سرمایه
54
+ "max_plausible_arb_pct": 250.0,
55
+ "max_plausible_lev_pct": 400.0,
56
+ }
57
+
58
+ ARBITRAGE_KINDS = {"box", "parity", "tabei"}
59
+
60
+
61
+ # ---------------------------------------------------------------- ورودی
62
+ def load_history(path: str | Path) -> tuple[list[dict], list[str]]:
63
+ """پروندهٔ تاریخی CSV را می‌خواند؛ سطرهای شروع‌شده با # و سطرهای خالی نادیده گرفته می‌شوند."""
64
+ p = Path(path)
65
+ problems: list[str] = []
66
+ if not p.exists():
67
+ return [], [f"پروندهٔ تاریخ پیدا نشد: {p}"]
68
+ rows: list[dict] = []
69
+ if p.suffix.lower() == ".json":
70
+ data = json.loads(p.read_text(encoding="utf-8-sig"))
71
+ raw = data if isinstance(data, list) else data.get("rows", [])
72
+ else:
73
+ raw_text = p.read_text(encoding="utf-8-sig").lstrip("\ufeff")
74
+ text = "\n".join(line for line in raw_text.splitlines()
75
+ if line.strip() and not line.lstrip().startswith("#"))
76
+ raw = list(csv.DictReader(text.splitlines()))
77
+ for i, r in enumerate(raw, 1):
78
+ if not r.get("kind") or not r.get("symbol"):
79
+ problems.append(f"سطر {i}: نماد یا نوع راهبرد خالی است")
80
+ continue
81
+ row = {}
82
+ for k, v in r.items():
83
+ if k is None:
84
+ continue
85
+ if isinstance(v, str):
86
+ v = v.strip()
87
+ if v == "":
88
+ continue
89
+ try:
90
+ row[k] = float(v) if any(c.isdigit() for c in v) and k not in ("date", "symbol", "kind", "unit") else v
91
+ except ValueError:
92
+ row[k] = v
93
+ else:
94
+ row[k] = v
95
+ rows.append(row)
96
+ if not rows:
97
+ problems.append("هیچ سطر معتبری در پروندهٔ تاریخ نبود")
98
+ return rows, problems
99
+
100
+
101
+ # ---------------------------------------------------------------- تصمیم و نتیجه
102
+ @dataclass
103
+ class DecisionRow:
104
+ date: str
105
+ symbol: str
106
+ kind: str
107
+ taken: bool
108
+ reason: str
109
+ expected_annualized_pct: float | None
110
+ edge_pp: float
111
+ hurdle: float
112
+ realized_annualized_pct: float | None
113
+ days: float
114
+ period_realized_pct: float | None
115
+
116
+ def as_dict(self) -> dict:
117
+ return {
118
+ "date": self.date, "symbol": self.symbol, "kind": self.kind,
119
+ "decision": "ورود" if self.taken else "رد",
120
+ "reason": self.reason,
121
+ "expected_annualized_pct": None if self.expected_annualized_pct is None else round(self.expected_annualized_pct, 3),
122
+ "edge_pp": round(self.edge_pp, 3),
123
+ "hurdle": self.hurdle,
124
+ "realized_annualized_pct": None if self.realized_annualized_pct is None else round(self.realized_annualized_pct, 3),
125
+ "period_realized_pct": None if self.period_realized_pct is None else round(self.period_realized_pct, 3),
126
+ }
127
+
128
+
129
+ def period_return(annualized_pct: float | None, days: float) -> float | None:
130
+ """بازده سالانه را به بازده همان دوره ترجمه می‌کند."""
131
+ if annualized_pct is None or days <= 0:
132
+ return None
133
+ return ((1 + annualized_pct / 100.0) ** (days / 365.0) - 1) * 100.0
134
+
135
+
136
+ def decide_row(row: dict, rules: dict) -> DecisionRow:
137
+ """دقیقاً همان دروازه‌های زنده، روی یک سطر تاریخ."""
138
+ if live_desk is None: # pragma: no cover
139
+ raise RuntimeError(f"موتور زنده بارگذاری نشد: {_IMPORT_ERROR}")
140
+ hurdle = float(row.get("hurdle", 0.39))
141
+ kind = str(row.get("kind"))
142
+ payload = {k: v for k, v in row.items() if not k.startswith("realized")}
143
+ payload["margin_per_contract"] = float(row.get("margin_per_contract", 0) or 0)
144
+ try:
145
+ res = live_desk.math_for_row(payload, hurdle)
146
+ except Exception as e:
147
+ return DecisionRow(date=str(row.get("date", "")), symbol=str(row.get("symbol", "")), kind=kind,
148
+ taken=False, reason=f"محاسبه نشد: {type(e).__name__}: {e}",
149
+ expected_annualized_pct=None, edge_pp=-999.0, hurdle=hurdle,
150
+ realized_annualized_pct=_num(row.get("realized_annualized_pct")),
151
+ days=float(row.get("days", 0) or 0), period_realized_pct=None)
152
+
153
+ edge = float(res.get("score_pp", -999.0))
154
+ reasons: list[str] = []
155
+ if not res.get("go"):
156
+ reasons.append("موتور ریاضی تأیید نکرد")
157
+ threshold = rules["min_edge_arbitrage_pct"] if kind in ARBITRAGE_KINDS else rules["min_edge_leveraged_pct"]
158
+ if edge < threshold:
159
+ reasons.append(f"حاشیهٔ {edge:.2f} کمتر از کف {threshold:.2f}")
160
+ ceiling = (rules["max_plausible_arb_pct"] if kind in ARBITRAGE_KINDS else rules["max_plausible_lev_pct"])
161
+ annual = res.get("annualized_pct")
162
+ if isinstance(annual, (int, float)) and abs(annual) > ceiling:
163
+ reasons.append(f"بازده محاسبه‌شده {annual:,.0f}٪ از سقف باورپذیری ({ceiling:,.0f}٪) بیشتر است؛ داده مشکوک")
164
+ liq = row.get("liquidity_contracts_per_day")
165
+ if isinstance(liq, (int, float)) and liq < rules["min_liquidity_contracts_per_day"]:
166
+ reasons.append(f"نقدشوندگی {liq:.0f} کمتر از کف {rules['min_liquidity_contracts_per_day']}")
167
+ spread = row.get("spread_pct")
168
+ if isinstance(spread, (int, float)) and spread > rules["max_spread_pct"]:
169
+ reasons.append(f"اسپرد {spread * 100:.2f}٪ بیش از سقف")
170
+
171
+ realized = _num(row.get("realized_annualized_pct"))
172
+ days = float(row.get("days", 0) or 0)
173
+ return DecisionRow(date=str(row.get("date", "")), symbol=str(row.get("symbol", "")), kind=kind,
174
+ taken=not reasons, reason="؛ ".join(reasons) or "همهٔ دروازه‌ها باز بود",
175
+ expected_annualized_pct=res.get("annualized_pct"), edge_pp=edge, hurdle=hurdle,
176
+ realized_annualized_pct=realized, days=days,
177
+ period_realized_pct=period_return(realized, days))
178
+
179
+
180
+ def _num(v):
181
+ if v is None or v == "":
182
+ return None
183
+ try:
184
+ return float(v)
185
+ except (TypeError, ValueError):
186
+ return None
187
+
188
+
189
+ # ---------------------------------------------------------------- اجرا و سنجه‌ها
190
+ def run_backtest(history_path: str | Path, rules: dict | None = None,
191
+ capital: float = 20_000_000_000) -> dict:
192
+ rules = {**DEFAULT_RULES, **(rules or {})}
193
+ rows, problems = load_history(history_path)
194
+ decisions = [decide_row(r, rules) for r in rows]
195
+ taken = [d for d in decisions if d.taken]
196
+ skipped = [d for d in decisions if not d.taken]
197
+
198
+ def avg(xs: list[float]) -> float | None:
199
+ xs = [x for x in xs if x is not None]
200
+ return sum(xs) / len(xs) if xs else None
201
+
202
+ realized_taken = [d.realized_annualized_pct for d in taken if d.realized_annualized_pct is not None]
203
+ realized_skipped = [d.realized_annualized_pct for d in skipped if d.realized_annualized_pct is not None]
204
+ hits = [d for d in taken if d.realized_annualized_pct is not None and d.realized_annualized_pct > d.hurdle * 100]
205
+ losses = [d for d in taken if d.realized_annualized_pct is not None and d.realized_annualized_pct < 0]
206
+ missed = [d for d in skipped if d.realized_annualized_pct is not None and d.realized_annualized_pct > d.hurdle * 100]
207
+ errors = [d.realized_annualized_pct - (d.expected_annualized_pct or 0) for d in taken
208
+ if d.realized_annualized_pct is not None and d.expected_annualized_pct is not None]
209
+
210
+ # منحنی سرمایه: معامله‌ها به ترتیب تاریخ و پشت‌سرهم، با وزن ثابت — فرض ساده و صریح
211
+ ordered = sorted([d for d in taken if d.period_realized_pct is not None],
212
+ key=lambda d: str(d.date))
213
+ equity = capital
214
+ curve = [{"trade": 0, "date": "شروع", "equity": round(equity, 0)}]
215
+ for i, d in enumerate(ordered, 1):
216
+ equity *= (1 + rules["position_weight"] * d.period_realized_pct / 100.0)
217
+ curve.append({"trade": i, "date": d.date, "equity": round(equity, 0)})
218
+
219
+ by_kind: dict[str, dict] = {}
220
+ for d in decisions:
221
+ slot = by_kind.setdefault(d.kind, {"total": 0, "taken": 0, "hits": 0,
222
+ "realized": [], "expected": []})
223
+ slot["total"] += 1
224
+ if d.taken:
225
+ slot["taken"] += 1
226
+ if d.realized_annualized_pct is not None:
227
+ slot["realized"].append(d.realized_annualized_pct)
228
+ if d.realized_annualized_pct > d.hurdle * 100:
229
+ slot["hits"] += 1
230
+ if d.expected_annualized_pct is not None:
231
+ slot["expected"].append(d.expected_annualized_pct)
232
+
233
+ summary = {
234
+ "file": str(history_path),
235
+ "rows": len(decisions),
236
+ "taken": len(taken),
237
+ "skipped": len(skipped),
238
+ "hit_rate_pct": (100.0 * len(hits) / len(realized_taken)) if realized_taken else None,
239
+ "false_positive_rate_pct": (100.0 * len(losses) / len(realized_taken)) if realized_taken else None,
240
+ "missed_opportunity_rate_pct": (100.0 * len(missed) / len(realized_skipped)) if realized_skipped else None,
241
+ "avg_expected_annualized_pct": avg([d.expected_annualized_pct for d in taken]),
242
+ "avg_realized_annualized_pct": avg(realized_taken),
243
+ "avg_realized_skipped_pct": avg(realized_skipped),
244
+ "avg_forecast_error_pp": avg(errors),
245
+ "final_equity": round(equity, 0),
246
+ "start_capital": capital,
247
+ "equity_change_pct": round((equity / capital - 1) * 100, 2) if capital else None,
248
+ "best_trade": max((d.realized_annualized_pct for d in taken if d.realized_annualized_pct is not None), default=None),
249
+ "worst_trade": min((d.realized_annualized_pct for d in taken if d.realized_annualized_pct is not None), default=None),
250
+ "rules": rules,
251
+ "problems": problems,
252
+ "generated_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
253
+ }
254
+ return {"summary": summary, "decisions": decisions, "equity_curve": curve,
255
+ "by_kind": by_kind, "best": sorted([d for d in taken if d.realized_annualized_pct is not None],
256
+ key=lambda d: d.realized_annualized_pct, reverse=True)[:3],
257
+ "worst": sorted([d for d in taken if d.realized_annualized_pct is not None],
258
+ key=lambda d: d.realized_annualized_pct)[:3],
259
+ "missed": sorted(missed, key=lambda d: d.realized_annualized_pct, reverse=True)[:5]}
260
+
261
+
262
+ # ---------------------------------------------------------------- خروجی‌ها
263
+ def write_csv(result: dict, path: str | Path) -> Path:
264
+ p = Path(path)
265
+ p.parent.mkdir(parents=True, exist_ok=True)
266
+ with p.open("w", encoding="utf-8-sig", newline="") as f:
267
+ w = csv.DictWriter(f, fieldnames=list(result["decisions"][0].as_dict().keys()) if result["decisions"] else
268
+ ["date", "symbol", "kind", "decision", "reason"])
269
+ w.writeheader()
270
+ for d in result["decisions"]:
271
+ w.writerow(d.as_dict())
272
+ return p
273
+
274
+
275
+ def _fmt(v, digits: int = 2, suffix: str = "") -> str:
276
+ if v is None:
277
+ return "—"
278
+ if isinstance(v, (int, float)):
279
+ return f"{v:,.{digits}f}{suffix}"
280
+ return html.escape(str(v))
281
+
282
+
283
+ def build_report(result: dict, path: str | Path, title: str = "گزارش پس‌آزمایی") -> Path:
284
+ p = Path(path)
285
+ p.parent.mkdir(parents=True, exist_ok=True)
286
+ s = result["summary"]
287
+ rows = "".join(
288
+ f"<tr><td>{html.escape(d.date)}</td><td>{html.escape(d.symbol)}</td>"
289
+ f"<td>{html.escape(KIND_LABELS.get(d.kind, d.kind))}</td>"
290
+ f"<td class='{'ok' if d.taken else 'no'}'>{'ورود' if d.taken else 'رد'}</td>"
291
+ f"<td class='why'>{html.escape(d.reason)}</td>"
292
+ f"<td class='num'>{_fmt(d.expected_annualized_pct)}</td>"
293
+ f"<td class='num'>{_fmt(d.edge_pp)}</td>"
294
+ f"<td class='num'>{_fmt(d.realized_annualized_pct)}</td>"
295
+ f"<td class='num'>{_fmt(d.period_realized_pct)}</td></tr>"
296
+ for d in result["decisions"][:400])
297
+
298
+ kind_rows = "".join(
299
+ f"<tr><td>{html.escape(KIND_LABELS.get(k, k))}</td><td class='num'>{v['total']}</td>"
300
+ f"<td class='num'>{v['taken']}</td>"
301
+ f"<td class='num'>{_fmt(sum(v['expected']) / len(v['expected']) if v['expected'] else None)}</td>"
302
+ f"<td class='num'>{_fmt(sum(v['realized']) / len(v['realized']) if v['realized'] else None)}</td>"
303
+ f"<td class='num'>{(100.0 * v['hits'] / len(v['realized'])) if v['realized'] else None}</td></tr>"
304
+ for k, v in sorted(result["by_kind"].items(), key=lambda kv: -kv[1]["total"]))
305
+
306
+ def small_table(items, label):
307
+ if not items:
308
+ return f"<p class='muted'>{label}: موردی نیست.</p>"
309
+ return f"<p class='muted'>{label}</p><ul>" + "".join(
310
+ f"<li>{html.escape(d.date)} · {html.escape(d.symbol)} · {html.escape(KIND_LABELS.get(d.kind, d.kind))}"
311
+ f" — نتیجهٔ واقعی {_fmt(d.realized_annualized_pct, suffix='٪')} سالانه</li>" for d in items) + "</ul>"
312
+
313
+ doc = f"""<!DOCTYPE html>
314
+ <html lang="fa" dir="rtl"><head><meta charset="utf-8"><title>{html.escape(title)}</title>
315
+ <style>
316
+ body {{ font-family: Tahoma, "Segoe UI", "Vazirmatn", sans-serif; margin: 0; background: #f6f7f9; color: #1d1d1f; }}
317
+ header {{ background: #3b2f63; color: #fff; padding: 16px 22px; }}
318
+ header h1 {{ margin: 0 0 6px; font-size: 19px; }}
319
+ header .meta {{ font-size: 12px; opacity: .85; }}
320
+ .cards {{ display: flex; gap: 10px; flex-wrap: wrap; padding: 14px 22px 0; }}
321
+ .card {{ background: #fff; border: 1px solid #e3e6ea; border-radius: 10px; padding: 10px 12px; min-width: 165px; }}
322
+ .card .k {{ font-size: 11.5px; color: #6b7280; }}
323
+ .card .v {{ font-size: 17px; font-weight: bold; margin-top: 3px; }}
324
+ main {{ padding: 12px 22px 40px; }}
325
+ h2 {{ font-size: 15px; margin: 20px 0 8px; }}
326
+ table {{ width: 100%; border-collapse: collapse; background: #fff; font-size: 12.5px; }}
327
+ th, td {{ border-bottom: 1px solid #e6e8ec; padding: 6px 8px; text-align: right; vertical-align: top; }}
328
+ th {{ background: #eef2f7; font-size: 12px; }}
329
+ .num {{ font-variant-numeric: tabular-nums; }}
330
+ .ok {{ color: #0a7d33; font-weight: bold; }}
331
+ .no {{ color: #b3261e; }}
332
+ .why {{ color: #444; max-width: 300px; }}
333
+ .muted {{ color: #6b7280; font-size: 12.5px; }}
334
+ .warn {{ background: #fff8e1; border: 1px solid #f0e0a8; border-radius: 8px; padding: 10px 12px; font-size: 12.5px; margin-bottom: 12px; }}
335
+ footer {{ margin-top: 20px; font-size: 11.5px; color: #6b7280; }}
336
+ </style></head><body>
337
+ <header>
338
+ <h1>{html.escape(title)}</h1>
339
+ <div class="meta">پروندهٔ تاریخ: {html.escape(Path(s['file']).name)} · تاریخ اجرا: {html.escape(s['generated_at'])}
340
+ · قواعد: کف آربیتراژ {s['rules']['min_edge_arbitrage_pct']} · کف اهرمی {s['rules']['min_edge_leveraged_pct']} · کف نقدشوندگی {s['rules']['min_liquidity_contracts_per_day']}</div>
341
+ </header>
342
+ <main>
343
+ <div class="warn">این گزارش با «همان موتوری» ساخته شده که در تصمیم‌گیری زنده به کار می‌رود. هیچ عددی در آن وعدهٔ آینده نیست.
344
+ نتیجهٔ هر معامله از ستون «نتیجهٔ واقعی» همان سطر می‌آید و در تصمیم هیچ نقشی نداشته است.</div>
345
+
346
+ <div class="cards">
347
+ <div class="card"><div class="k">کل سطرها</div><div class="v">{s['rows']}</div></div>
348
+ <div class="card"><div class="k">ورود (تأییدشده)</div><div class="v">{s['taken']}</div></div>
349
+ <div class="card"><div class="k">رد</div><div class="v">{s['skipped']}</div></div>
350
+ <div class="card"><div class="k">نرخ برد</div><div class="v">{_fmt(s['hit_rate_pct'], 1, '٪')}</div></div>
351
+ <div class="card"><div class="k">خطای مثبت کاذب</div><div class="v">{_fmt(s['false_positive_rate_pct'], 1, '٪')}</div></div>
352
+ <div class="card"><div class="k">فرصت از دست رفته</div><div class="v">{_fmt(s['missed_opportunity_rate_pct'], 1, '٪')}</div></div>
353
+ <div class="card"><div class="k">میانگین بازده انتظاری (ورودها)</div><div class="v">{_fmt(s['avg_expected_annualized_pct'], 1, '٪')}</div></div>
354
+ <div class="card"><div class="k">میانگین بازده واقعی (ورودها)</div><div class="v">{_fmt(s['avg_realized_annualized_pct'], 1, '٪')}</div></div>
355
+ <div class="card"><div class="k">خطای پیش‌بینی</div><div class="v">{_fmt(s['avg_forecast_error_pp'], 1, ' واحد')}</div></div>
356
+ <div class="card"><div class="k">سرمایهٔ پایانی</div><div class="v">{_fmt(s['final_equity'], 0)}</div></div>
357
+ <div class="card"><div class="k">تغییر سرمایه</div><div class="v">{_fmt(s['equity_change_pct'], 1, '٪')}</div></div>
358
+ </div>
359
+
360
+ <h2>تفکیک راهبردها</h2>
361
+ <table><thead><tr><th>راهبرد</th><th>سطر</th><th>ورود</th><th>میانگین انتظاری</th><th>میانگین واقعی</th><th>نرخ برد</th></tr></thead>
362
+ <tbody>{kind_rows}</tbody></table>
363
+
364
+ <h2>سه معاملهٔ سودآورتر و سه معاملهٔ زیان‌ده‌تر (از میان ورودها)</h2>
365
+ {small_table(result['best'], 'بهترین‌ها')}
366
+ {small_table(result['worst'], 'بدترین‌ها')}
367
+
368
+ <h2>فرصت‌هایی که با دروازه رد شدند ولی نتیجهٔ واقعی خوب داشتند</h2>
369
+ {small_table(result['missed'], 'اگر دروا��ه‌ها را بازتر می‌کردیم')}
370
+
371
+ <h2>سطر به سطر</h2>
372
+ <table><thead><tr><th>تاریخ</th><th>نماد</th><th>راهبرد</th><th>تصمیم</th><th>دلیل</th>
373
+ <th>بازده انتظاری (٪)</th><th>حاشیه (واحد)</th><th>نتیجهٔ واقعی (٪)</th><th>بازده دورهٔ واقعی (٪)</th></tr></thead>
374
+ <tbody>{rows}</tbody></table>
375
+
376
+ <footer>ساختهٔ پس‌آزمای ایستگاه نسخهٔ {VERSION} · {html.escape(CREDIT)}<br>
377
+ فرض شبیه‌سازی سرمایه: هر معامله {s['rules']['position_weight'] * 100:.0f} درصد سرمایه، معامله‌ها پشت‌سرهم — ساده‌سازی عمدی و صریح.</footer>
378
+ </main></body></html>"""
379
+ p.write_text(doc, encoding="utf-8")
380
+ return p
381
+
382
+
383
+ def _cli(argv: list[str]) -> int:
384
+ import argparse
385
+ ap = argparse.ArgumentParser(description="پس‌آزمایی موتور روی دادهٔ تاریخی")
386
+ ap.add_argument("history")
387
+ ap.add_argument("--out", default=str(BASE / "data" / "backtest.html"))
388
+ ap.add_argument("--csv", default=str(BASE / "data" / "backtest.csv"))
389
+ ap.add_argument("--capital", type=float, default=20_000_000_000)
390
+ args = ap.parse_args(argv)
391
+ result = run_backtest(args.history, capital=args.capital)
392
+ s = result["summary"]
393
+ print(f"سطرها: {s['rows']} · ورود: {s['taken']} · رد: {s['skipped']}")
394
+ print(f"نرخ برد: {s['hit_rate_pct']}٪ · خطای مثبت کاذب: {s['false_positive_rate_pct']}٪ · "
395
+ f"فرصت از دست رفته: {s['missed_opportunity_rate_pct']}٪")
396
+ print(f"میانگین انتظاری: {s['avg_expected_annualized_pct']} · میانگین واقعی: {s['avg_realized_annualized_pct']}")
397
+ print(f"گزارش: {build_report(result, args.out)}")
398
+ print(f"CSV: {write_csv(result, args.csv)}")
399
+ return 0
400
+
401
+
402
+ if __name__ == "__main__":
403
+ raise SystemExit(_cli(sys.argv[1:]))
station/bankroll.py ADDED
@@ -0,0 +1,372 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env python3
2
+ # -*- coding: utf-8 -*-
3
+ """ریاضیِ پول — «با ریاضی می‌شود ثروتمند شد؟» جواب صادقانه، با عدد.
4
+
5
+ جواب کوتاه: بله، ولی نه با یک معاملهٔ خوش‌شانس. سه چیز لازم است و هر سه ریاضی است:
6
+ ۱) مزیت مثبت در هر معامله (احتمال برد × سود برد > احتمال باخت × زیان باخت + کارمزد).
7
+ ۲) بقا: اندازهٔ موقعیت طوری باشد که «نیم‌شدن حساب» احتمالش کم باشد.
8
+ ۳) زمان: رشد مرکب کند است؛ عددها را همین‌جا می‌بینی، نه با شعار.
9
+
10
+ این پرونده سه خروجی می‌دهد:
11
+ • کسر کِلی (اندازهٔ درست هر معامله) و نسخهٔ محافظه‌کارانهٔ نصف‌کِلی.
12
+ • شبیه‌سازی ۲۰٬۰۰۰ مسیر (Monte Carlo) با کارمزد واقعی: احتمال نیم‌شدن حساب، احتمال سود،
13
+ میانهٔ دارایی در پایان، و بازهٔ ۱۰٪ تا ۹۰٪.
14
+ • مسیر رشد: با این مزیت و این اندازه، چند معامله/چند ماه تا هدف.
15
+
16
+ هیچ‌جا «تضمین» نیست؛ اگر عددها بد باشند، همان‌طور نشان داده می‌شوند. برای اینکه شبیه‌سازی
17
+ تقلب نکند: کارمزد از هر معامله کسر می‌شود و دانهٔ تصادفی (seed) ثابت است تا نتیجه بازتولیدپذیر باشد.
18
+ """
19
+
20
+ from __future__ import annotations
21
+
22
+ import argparse
23
+ import json
24
+ import math
25
+ import random
26
+ import sys
27
+ from pathlib import Path
28
+
29
+ BASE = Path(__file__).resolve().parent
30
+ if str(BASE) not in sys.path:
31
+ sys.path.insert(0, str(BASE))
32
+
33
+ import investor_test as inv # noqa: E402
34
+ import reportkit as rk # noqa: E402
35
+
36
+ VERSION = "0.1.0"
37
+ DATA = BASE / "data"
38
+ REPORT_HTML = DATA / "bankroll.html"
39
+ REPORT_MD = DATA / "bankroll.md"
40
+ REPORT_JSON = DATA / "bankroll.json"
41
+
42
+ RUIN_LEVEL = 0.50 # «نیم‌شدن حساب» = ورشکستگی عملی برای سرمایهٔ کوچک
43
+ DEFAULT_TRIALS = 20_000
44
+ DEFAULT_SEED = 7
45
+ STOCK_ROUND_TRIP_PCT = round((0.00464 + 0.00964) * 100, 4) # خرید+فروش سهم
46
+ OPTION_ROUND_TRIP_PCT = round((0.00103 * 2) * 100, 4) # خرید+فروش اختیار
47
+
48
+
49
+ def kelly(win_prob: float, win_pct: float, loss_pct: float) -> dict:
50
+ """اندازهٔ درست هر معامله: f = (p·b − q) ÷ b که b = سودبرد÷زیان‌باخت.
51
+
52
+ خروجی هم کسر کِلی است، هم نصف‌کِلی (محافظه‌کارانه) — چون فرض‌های واقعی از این ساده‌ترند.
53
+ """
54
+ p = float(win_prob)
55
+ q = 1 - p
56
+ w = float(win_pct) / 100
57
+ l = float(loss_pct) / 100
58
+ if w <= 0 or l <= 0:
59
+ return {"ok": False, "detail": "سود برد و زیان باخت باید مثبت باشند."}
60
+ b = w / l
61
+ f = (p * b - q) / b
62
+ edge = p * w - q * l
63
+ return {
64
+ "ok": True, "win_prob": p, "win_pct": win_pct, "loss_pct": loss_pct,
65
+ "edge_pct_per_trade": round(edge * 100, 4),
66
+ "kelly_fraction": round(max(0.0, f), 4),
67
+ "half_kelly_fraction": round(max(0.0, f) / 2, 4),
68
+ "positive_edge": edge > 0,
69
+ "detail": ("مزیت مثبت است؛ اندازهٔ پیشنهادی = " + f"{max(0.0, f) * 100:.2f}٪ سرمایه در هر "
70
+ "معامله و نسخهٔ محافظه‌کارانه نصف آن." if edge > 0 else
71
+ "مزیت منفی یا صفر است: با این فرض‌ها معامله‌کردن، پول‌سوزی است. اول مزیت را "
72
+ "درست کن، بعد اندازه را."),
73
+ }
74
+
75
+
76
+ def breakeven_win_rate(win_pct: float, loss_pct: float, fee_pct: float = 0.0) -> dict:
77
+ """کم‌ترین نرخ برد برای اینکه بازی سر به سر شود (بعد از کارمزد)."""
78
+ w = float(win_pct) / 100
79
+ l = float(loss_pct) / 100
80
+ f = float(fee_pct) / 100
81
+ if w + l <= 0:
82
+ return {"ok": False, "detail": "سود و زیان باید مثبت باشند."}
83
+ p = (l + f) / (w + l)
84
+ return {"ok": True, "breakeven_win_prob": round(p, 4), "breakeven_win_pct": round(p * 100, 2),
85
+ "detail": (f"با سود برد {win_pct:.1f}٪ و زیان باخت {loss_pct:.1f}٪ و کارمزد رفت‌وبرگشت "
86
+ f"{fee_pct:.3f}٪، کم‌ترین نرخ برد لازم {p * 100:.2f}٪ است. زیر آن، هر "
87
+ f"استراتژی‌ای بازنده است — ریاضی، نه نظر.")}
88
+
89
+
90
+ def simulate(*, capital: float = 100_000_000.0, win_prob: float = 0.55, win_pct: float = 8.0,
91
+ loss_pct: float = 5.0, risk_fraction: float = 0.10, trades: int = 48,
92
+ fee_pct: float = STOCK_ROUND_TRIP_PCT, trials: int = DEFAULT_TRIALS,
93
+ seed: int = DEFAULT_SEED, ruin_level: float = RUIN_LEVEL,
94
+ notional_ratio: float = 1.0) -> dict:
95
+ """Monte Carlo: هزاران مسیر ممکن با همان مزیت و همان کارمزد.
96
+
97
+ فرض صریح کارمزد: کارمزد رفت‌وبرگشت روی **ارزش معامله** بسته می‌شود
98
+ (`notional_ratio` برابر ارزش معامله ÷ سرمایهٔ حساب). با `notional_ratio=1` یعنی هر معامله
99
+ به اندازهٔ کل حساب است — همان فرضی که برای معامله‌گر خرد واقع‌بینانه است و عدد را بدبینانه،
100
+ نه خوش‌بینانه، نشان می‌دهد.
101
+ """
102
+ rng = random.Random(seed)
103
+ finals: list[float] = []
104
+ ruin = 0
105
+ reached_double = 0
106
+ best, worst = 0.0, float("inf")
107
+ for _ in range(trials):
108
+ eq = capital
109
+ ruined = False
110
+ for _t in range(trades):
111
+ fee_cost = notional_ratio * fee_pct / 100
112
+ if rng.random() < win_prob:
113
+ eq *= (1 + risk_fraction * win_pct / 100 - fee_cost)
114
+ else:
115
+ eq *= (1 - risk_fraction * loss_pct / 100 - fee_cost)
116
+ if eq <= capital * ruin_level:
117
+ ruined = True
118
+ break
119
+ if ruined:
120
+ ruin += 1
121
+ if eq >= capital * 2:
122
+ reached_double += 1
123
+ finals.append(eq)
124
+ best = max(best, eq)
125
+ worst = min(worst, eq)
126
+ finals.sort()
127
+
128
+ def pct_at(p: float) -> float:
129
+ idx = min(len(finals) - 1, max(0, int(p * len(finals))))
130
+ return finals[idx]
131
+
132
+ median = pct_at(0.50)
133
+ return {
134
+ "ok": True, "capital": capital, "trials": trials, "trades": trades, "seed": seed,
135
+ "risk_fraction": risk_fraction, "fee_pct": fee_pct, "notional_ratio": notional_ratio,
136
+ "ruin_prob": round(ruin / trials, 4), "double_prob": round(reached_double / trials, 4),
137
+ "profit_prob": round(sum(1 for f in finals if f > capital) / trials, 4),
138
+ "median_final": round(median, 2),
139
+ "median_multiple": round(median / capital, 3),
140
+ "p10_final": round(pct_at(0.10), 2), "p90_final": round(pct_at(0.90), 2),
141
+ "best_final": round(best, 2), "worst_final": round(worst, 2),
142
+ "ruin_level": ruin_level,
143
+ "detail": (f"در {trials:,} مسیر فرضی با نرخ برد {win_prob * 100:.0f}٪ و اندازهٔ "
144
+ f"{risk_fraction * 100:.0f}٪ در هر معامله و کارمزد {fee_pct:.3f}٪ روی ارزش "
145
+ f"معامله: احتمال نیم‌شدن حساب {ruin / trials * 100:.2f}٪ · احتمال دوبرابر‌شدن "
146
+ f"{reached_double / trials * 100:.2f}٪ · میانهٔ پایان {median / capital:.2f} "
147
+ f"برابر شروع."),
148
+ }
149
+
150
+
151
+ def path(*, capital: float, monthly_return_pct: float, target: float,
152
+ fee_drag_pct_month: float = 0.0) -> dict:
153
+ """چند ماه تا هدف، با رشد مرکب و کسر کارمزد ماهانه (بدون شعار، فقط لگاریتم)."""
154
+ net = monthly_return_pct - fee_drag_pct_month
155
+ if target <= capital:
156
+ return {"ok": False, "detail": "هدف باید بزرگ‌تر از سرمایهٔ فعلی باشد."}
157
+ if net <= 0:
158
+ return {"ok": True, "months": None, "years": None, "net_monthly_pct": round(net, 4),
159
+ "detail": ("با این بازده و این کارمزد، رشد صفر یا منفی است؛ هدف با هیچ زمانی "
160
+ "به‌دست نمی‌آید. اول مزیت را مثبت کن، بعد به زمان فکر کن.")}
161
+ months = math.log(target / capital) / math.log(1 + net / 100)
162
+ return {"ok": True, "months": round(months, 1), "years": round(months / 12, 1),
163
+ "net_monthly_pct": round(net, 4),
164
+ "needed_multiple": round(target / capital, 3),
165
+ "detail": (f"با {net:.2f}٪ رشد خالص ماهانه، از {capital:,.0f} به {target:,.0f} "
166
+ f"می‌رسد در حدود {months:.1f} ماه ({months / 12:.1f} سال) — به‌شرط اینکه "
167
+ f"رشد مثبت بماند و هیچ ماه بحرانی حساب را نصف نکند.")}
168
+
169
+
170
+ def strategy_path(*, capital: float, annualized_pct: float, target: float,
171
+ churn_per_year: float = 1.0,
172
+ fee_pct_round_trip: float = STOCK_ROUND_TRIP_PCT) -> dict:
173
+ """مسیر رشد با «عدد راهبرد» و «تعداد چرخش در سال».
174
+
175
+ برخلاف کِلی که فرض‌های احتمالاتی دارد، این‌جا عدد راهبرد (همان که پلهٔ تصمیم می‌دهد) می‌آید،
176
+ چرخش سالانه و کارمزد کسر می‌شود، و بعد زمان رسیدن به هدف حساب می‌شود.
177
+ """
178
+ fee_drag_pp = churn_per_year * fee_pct_round_trip
179
+ net_annual = float(annualized_pct) - fee_drag_pp
180
+ if net_annual <= 0:
181
+ return {"ok": True, "net_annual_pct": round(net_annual, 3), "months": None, "years": None,
182
+ "churn_per_year": churn_per_year, "fee_drag_pp": round(fee_drag_pp, 3),
183
+ "detail": (f"با {churn_per_year:g} چرخش در سال، کارمزد {fee_drag_pp:.2f} واحد درصد "
184
+ f"از بازده کم می‌کند و بازده خالص {net_annual:.2f}٪ می‌شود؛ یعنی منفی. "
185
+ f"یا مزیت باید بزرگ‌تر شود یا چرخش کمتر.")}
186
+ monthly = (1 + net_annual / 100) ** (1 / 12) - 1
187
+ months = math.log(target / capital) / math.log(1 + monthly) if target > capital else 0.0
188
+ return {"ok": True, "net_annual_pct": round(net_annual, 3), "monthly_pct": round(monthly * 100, 4),
189
+ "months": round(months, 1), "years": round(months / 12, 1),
190
+ "churn_per_year": churn_per_year, "fee_drag_pp": round(fee_drag_pp, 3),
191
+ "detail": (f"راهبرد سالانه {annualized_pct:.2f}٪ می‌دهد؛ با {churn_per_year:g} چرخش در "
192
+ f"سال و کارمزد {fee_pct_round_trip:.3f}٪، خالص {net_annual:.2f}٪ می‌شود. "
193
+ f"با همین رشد مرکب، {target / capital:.1f} برابر شدن حدود {months:.1f} ماه "
194
+ f"({months / 12:.1f} سال) طول می‌کشد.")}
195
+
196
+
197
+ def honesty_checks(capital: float = 100_000_000.0) -> list[dict]:
198
+ """سه آزمون صادقانه: کارمزد، نرخ برد، و اندازهٔ موقعیت — که هرکدام می‌تواند بازی را ببندد."""
199
+ be = breakeven_win_rate(win_pct=8.0, loss_pct=5.0, fee_pct=STOCK_ROUND_TRIP_PCT)
200
+ small = simulate(capital=capital, risk_fraction=0.05, trials=6000)
201
+ big = simulate(capital=capital, risk_fraction=0.40, trials=6000)
202
+ return [
203
+ {"title": "کارمزد رفت‌وبرگشت سهم چقدر است؟",
204
+ "value": f"{STOCK_ROUND_TRIP_PCT}٪ (سهم) · {OPTION_ROUND_TRIP_PCT}٪ (اختیار)",
205
+ "why": "روزی دو رفت‌وبرگشت با سرمایهٔ کوچک، سالانه بیش از ۳۰٪ سرمایه را کارمزد می‌دهد؛ "
206
+ "همین یک عدد، بیشتر معامله‌گران روزانه را بازنده می‌کند.",
207
+ "verdict": "پس: چرخش کم، نگه‌داشتن تا سررسید، و پرهیز از معاملهٔ بی‌مزیت."},
208
+ {"title": "کم‌ترین نرخ برد لازم", "value": f"{be['breakeven_win_pct']}٪",
209
+ "why": be["detail"],
210
+ "verdict": "نرخ برد خودت را از دفتر حساب کن (نه از حافظه) و با این عدد بسنج."},
211
+ {"title": "اندازهٔ موقعیت: ۵٪ در برابر ۴۰٪",
212
+ "value": f"نیم‌شدن حساب: {small['ruin_prob'] * 100:.2f}٪ در برابر {big['ruin_prob'] * 100:.2f}٪",
213
+ "why": ("با اندازهٔ کوچک‌تر، احتمال دوبرابر‌شدن کمتر ولی احتمال ورشکستگی بسیار کمتر است؛ "
214
+ "با اندازهٔ درشت، همان مزیت به ورشکستگی می‌رسد."),
215
+ "verdict": "برای سرمایهٔ کوچک، بقا مهم‌تر از سرعت است: اندازهٔ کوچک، عمر طولانی."},
216
+ ]
217
+
218
+
219
+ def build(*, capital: float = 100_000_000.0, target: float | None = None,
220
+ win_prob: float = 0.55, win_pct: float = 8.0, loss_pct: float = 5.0,
221
+ trades: int = 48, trials: int = DEFAULT_TRIALS, strategy_annualized_pct: float = 68.482,
222
+ churn_per_year: float = 1.0, write: bool = True, html: Path | str | None = None,
223
+ md: Path | str | None = None, jsonf: Path | str | None = None) -> dict:
224
+ tgt = float(target or capital * 4)
225
+ k = kelly(win_prob, win_pct, loss_pct)
226
+ frac = k["half_kelly_fraction"] if k.get("ok") and k["half_kelly_fraction"] else 0.10
227
+ sim = simulate(capital=capital, win_prob=win_prob, win_pct=win_pct, loss_pct=loss_pct,
228
+ risk_fraction=frac, trades=trades, trials=trials)
229
+ spath = strategy_path(capital=capital, annualized_pct=strategy_annualized_pct, target=tgt,
230
+ churn_per_year=churn_per_year)
231
+ trades_per_month = 2
232
+ per_month_pct = (k["edge_pct_per_trade"] * frac * trades_per_month) if k.get("ok") else 0.0
233
+ fee_drag = STOCK_ROUND_TRIP_PCT * frac * trades_per_month
234
+ plan = path(capital=capital, monthly_return_pct=per_month_pct, target=tgt,
235
+ fee_drag_pct_month=fee_drag)
236
+ doc = {
237
+ "version": VERSION, "capital": capital, "target": tgt,
238
+ "kelly": k, "used_risk_fraction": frac, "sim": sim, "path": plan, "strategy_path": spath,
239
+ "strategy_annualized_pct": strategy_annualized_pct, "churn_per_year": churn_per_year,
240
+ "breakeven": breakeven_win_rate(win_pct=win_pct, loss_pct=loss_pct,
241
+ fee_pct=STOCK_ROUND_TRIP_PCT),
242
+ "checks": honesty_checks(capital), "trades_per_month": trades_per_month,
243
+ "engine_fees_pct": {"stock_round_trip": STOCK_ROUND_TRIP_PCT,
244
+ "option_round_trip": OPTION_ROUND_TRIP_PCT},
245
+ "honesty": ("هیچ‌کدام از این عددها وعدهٔ سود نیست. شبیه‌سازی با فرض‌های خودتان اجرا "
246
+ "می‌شود؛ اگر نرخ برد واقعی شما کمتر از عدد سر‌به‌سر باشد، همین جدول "
247
+ "«زیان» نشان می‌دهد. دانهٔ تصادفی ثابت است تا نتیجه بازتولیدپذیر باشد."),
248
+ }
249
+ doc["md_text"] = to_md(doc)
250
+ if write:
251
+ body = ['<div class="honest"><b>این پرونده وعدهٔ سود نیست؛ ریاضیِ بقا و رشد است.</b> '
252
+ 'می‌گوید با این مزیت و این کارمزد، هزاران مسیر ممکن چه شکلی دارند و کدام‌شان '
253
+ 'حساب را نصف می‌کنند. عددها با فرض‌های خودتان بازتولیدپذیرند.</div>',
254
+ f'<p class="sub">{rk.esc(doc["honesty"])}</p>',
255
+ "<h2>۱. اندازهٔ درست هر معامله (کِلی)</h2>",
256
+ f'<p><b>مزیت هر معامله:</b> {k.get("edge_pct_per_trade")}٪ · '
257
+ f'<b>کسر کِلی:</b> {k.get("kelly_fraction")} · '
258
+ f'<b>نصف‌کِلی (محافظه‌کارانه، همان چیزی که این‌جا استفاده شد):</b> '
259
+ f'{doc["used_risk_fraction"]}</p>',
260
+ f'<p class="note">{rk.esc(k.get("detail", ""))}</p>',
261
+ "<h2>۲. کم‌ترین نرخ برد لازم</h2>",
262
+ f'<p>{rk.esc(doc["breakeven"]["detail"])}</p>',
263
+ "<h2>۳. شبیه‌سازی مسیرها</h2>",
264
+ '<table><tbody>',
265
+ f'<tr><td>احتمال نیم‌شدن حساب</td><td class="num">{sim["ruin_prob"] * 100:.2f}٪</td></tr>',
266
+ f'<tr><td>احتمال دوبرابر‌شدن</td><td class="num">{sim["double_prob"] * 100:.2f}٪</td></tr>',
267
+ f'<tr><td>احتمال سود</td><td class="num">{sim["profit_prob"] * 100:.2f}٪</td></tr>',
268
+ f'<tr><td>میانهٔ پایان</td><td class="num">{rk.num(sim["median_final"])} '
269
+ f'({sim["median_multiple"]}× شروع)</td></tr>',
270
+ f'<tr><td>بازهٔ ۱۰٪ تا ۹۰٪</td><td class="num">{rk.num(sim["p10_final"])} تا '
271
+ f'{rk.num(sim["p90_final"])}</td></tr>',
272
+ '</tbody></table>',
273
+ f'<p class="note">{rk.esc(sim["detail"])}</p>',
274
+ "<h2>۴. چند وقت تا هدف</h2>",
275
+ f'<p><b>مسیر کِلی (مدل فرضی، کارمزد روی مبلغ ریسک):</b> {rk.esc(plan.get("detail", ""))}</p>',
276
+ f'<p><b>مسیر راهبرد (با عدد واقعی برنامه):</b> {rk.esc(spath.get("detail", ""))}</p>',
277
+ f'<p class="sub">عدد راهبرد = {strategy_annualized_pct:.3f}٪ سالانه (میان بر: همبسته '
278
+ f'با «مبنا»ی اسنپ‌شات) · چرخش سالانه {churn_per_year:g} بار · کارمزد رفت‌وبرگشت '
279
+ f'{STOCK_ROUND_TRIP_PCT}٪ (سهم). اگر راهبرد را تا سررسید نگه دارید و سالی یک بار '
280
+ f'بچرخانید، کارمزد کوچک و بازده تقریباً دست‌نخورده می‌ماند؛ اگر ماهی چند بار '
281
+ f'بچرخانید، کارمزد مزیت را می‌خورد.</p>',
282
+ "<h2>۵. سه آزمون صادقانه</h2>"]
283
+ for c in doc["checks"]:
284
+ body.append(f'<p><b>{rk.esc(c["title"])}</b> — {rk.esc(str(c["value"]))}<br>'
285
+ f'<span class="hint">{rk.esc(c["why"])}</span><br>'
286
+ f'<span class="ok">{rk.esc(c["verdict"])}</span></p>')
287
+ body.append('<p class="sub">✍️ تهیه‌کنندهٔ جزوات: <b>Masoud Mojarabian</b> · 📱 +989126630554 · '
288
+ '✈️ <a href="https://t.me/Mojarabian">Telegram: Mojarabian</a> · '
289
+ '📸 <a href="https://instagram.com/Mojarabian.Art">Instagram: Mojarabian.Art</a></p>')
290
+ hp = Path(html or REPORT_HTML)
291
+ hp.parent.mkdir(parents=True, exist_ok=True)
292
+ hp.write_text(rk.page("ریاضیِ پول — بقا، اندازهٔ موقعیت و مسیر رشد", "".join(body),
293
+ subtitle=f"سرمایه {rk.num(capital)} · هدف {rk.num(tgt)} · "
294
+ f"{sim['trials']:,} مسیر"),
295
+ encoding="utf-8")
296
+ Path(md or REPORT_MD).write_text(doc["md_text"], encoding="utf-8")
297
+ Path(jsonf or REPORT_JSON).write_text(json.dumps(doc, ensure_ascii=False, indent=1),
298
+ encoding="utf-8")
299
+ doc.update({"html": str(hp), "md": str(md or REPORT_MD), "json": str(jsonf or REPORT_JSON)})
300
+ return doc
301
+
302
+
303
+ def to_md(doc: dict) -> str:
304
+ k, sim, plan = doc["kelly"], doc["sim"], doc["path"]
305
+ L = [f"# ریاضیِ پول — نسخهٔ {VERSION}", "",
306
+ f"سرمایه: {doc['capital']:,.0f} · هدف: {doc['target']:,.0f} · "
307
+ f"معامله در ماه (فرض): {doc['trades_per_month']}", "",
308
+ f"> {doc['honesty']}", "",
309
+ "## ۱. اندازهٔ درست هر معامله", "",
310
+ f"- مزیت هر معامله: {k.get('edge_pct_per_trade')}٪",
311
+ f"- کسر کِلی: {k.get('kelly_fraction')} · نصف‌کِلی: {k.get('half_kelly_fraction')}",
312
+ f"- اندازهٔ استفاده‌شده در شبیه‌سازی: {doc['used_risk_fraction']}",
313
+ f"- {k.get('detail', '')}", "",
314
+ "## ۲. کم‌ترین نرخ برد لازم", "",
315
+ f"- {doc['breakeven']['detail']}", "",
316
+ "## ۳. شبیه‌سازی مسیرها", "",
317
+ f"- احتمال نیم‌شدن حساب: {sim['ruin_prob'] * 100:.2f}٪",
318
+ f"- احتمال دوبرابر‌شدن: {sim['double_prob'] * 100:.2f}٪",
319
+ f"- احتمال سود: {sim['profit_prob'] * 100:.2f}٪",
320
+ f"- میانهٔ پایان: {sim['median_final']:,.0f} ({sim['median_multiple']}× شروع)",
321
+ f"- بازهٔ ۱۰٪ تا ۹۰٪: {sim['p10_final']:,.0f} تا {sim['p90_final']:,.0f}",
322
+ f"- بدترین مسیر: {sim['worst_final']:,.0f} · بهترین مسیر: {sim['best_final']:,.0f}", "",
323
+ "## ۴. چند وقت تا هدف", "",
324
+ f"- مسیر کِلی (مدل فرضی، کارمزد روی مبلغ ریسک): {plan.get('detail', '')}",
325
+ f"- مسیر راهبرد (عدد واقعی برنامه {doc['strategy_annualized_pct']:.3f}٪ سالانه، "
326
+ f"{doc['churn_per_year']:g} چرخش در سال): {doc['strategy_path'].get('detail', '')}", "",
327
+ "## ۵. سه آزمون صادقانه", ""]
328
+ for c in doc["checks"]:
329
+ L += [f"### {c['title']}", f"- عدد: {c['value']}", f"- چرا: {c['why']}",
330
+ f"- نتیجه: {c['verdict']}", ""]
331
+ return "\n".join(L)
332
+
333
+
334
+ def main(argv: list[str] | None = None) -> int:
335
+ ap = argparse.ArgumentParser(description="ریاضیِ پول: کِلی، ورشکستگی، مسیر رشد")
336
+ ap.add_argument("--capital", type=float, default=100_000_000.0, help="سرمایه (ریال)")
337
+ ap.add_argument("--target", type=float, default=None)
338
+ ap.add_argument("--win-prob", type=float, default=0.55)
339
+ ap.add_argument("--win", type=float, default=8.0, help="درصد سود برد")
340
+ ap.add_argument("--loss", type=float, default=5.0, help="درصد زیان باخت")
341
+ ap.add_argument("--trades", type=int, default=48)
342
+ ap.add_argument("--trials", type=int, default=DEFAULT_TRIALS)
343
+ ap.add_argument("--strategy", type=float, default=68.482, help="بازده سالانهٔ راهبرد (٪)")
344
+ ap.add_argument("--churn", type=float, default=1.0, help="چند بار در سال می‌چرخانید")
345
+ ap.add_argument("--json", action="store_true")
346
+ ap.add_argument("--no-write", action="store_true")
347
+ a = ap.parse_args(argv)
348
+ doc = build(capital=a.capital, target=a.target, win_prob=a.win_prob, win_pct=a.win,
349
+ loss_pct=a.loss, trades=a.trades, trials=a.trials,
350
+ strategy_annualized_pct=a.strategy, churn_per_year=a.churn,
351
+ write=not a.no_write)
352
+ if a.json:
353
+ print(json.dumps(doc, ensure_ascii=False, indent=1))
354
+ return 0
355
+ k, sim, plan = doc["kelly"], doc["sim"], doc["path"]
356
+ print(f"ریاضیِ پول — سرمایه {a.capital:,.0f} · هدف {doc['target']:,.0f}")
357
+ print(f" مزیت هر معامله: {k.get('edge_pct_per_trade')}٪ · کسر کِلی {k.get('kelly_fraction')} · "
358
+ f"نصف‌کِلی {k.get('half_kelly_fraction')}")
359
+ print(f" کم‌ترین نرخ برد لازم: {doc['breakeven']['breakeven_win_pct']}٪")
360
+ print(f" شبیه‌سازی {sim['trials']:,} مسیر: نیم‌شدن {sim['ruin_prob'] * 100:.2f}٪ · "
361
+ f"دوبرابر‌شدن {sim['double_prob'] * 100:.2f}٪ · میانه {sim['median_multiple']}× ")
362
+ print(f" مسیر کِلی: {plan.get('detail')}")
363
+ print(f" مسیر راهبرد: {doc['strategy_path'].get('detail')}")
364
+ for c in doc["checks"]:
365
+ print(f" · {c['title']}: {c['value']} → {c['verdict']}")
366
+ if doc.get("html"):
367
+ print(" برگه:", doc["html"])
368
+ return 0
369
+
370
+
371
+ if __name__ == "__main__":
372
+ raise SystemExit(main())
station/build-dossier.bat ADDED
@@ -0,0 +1,11 @@
 
 
 
 
 
 
 
 
 
 
 
 
1
+ @echo off
2
+ chcp 65001 >nul
3
+ cd /d "%~dp0"
4
+ echo ============================================================
5
+ echo پروندهٔ سرمایه‌گذار — یک فایل برای جلسه با شرکت
6
+ echo قواعد، شاهدها، دفتر، کارنامه، پس‌آزمایی، محدودیت‌ها
7
+ echo ============================================================
8
+ python dossier.py
9
+ echo.
10
+ echo پرونده در پوشهٔ data ساخته شد: investor-dossier.html
11
+ pause
station/config/connections.json ADDED
@@ -0,0 +1,120 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "version": 1,
3
+ "selected": "mock-local",
4
+ "updated_at": "2026-09-22T21:07:49+00:00",
5
+ "profiles": [
6
+ {
7
+ "name": "mock-local",
8
+ "label": "خوراک آزمایشی محلی (بدون اینترنت، بدون هزینه)",
9
+ "cost": "رایگان",
10
+ "url_template": "http://127.0.0.1:8788/quote?symbol={symbol}",
11
+ "json_path": "data.0.pl",
12
+ "key_header": "",
13
+ "key_query_name": "",
14
+ "env_key": "",
15
+ "note": "برای آزمایش کامل برنامه و نشان‌دادن کارکردِ اتصال زنده به سرمایه‌گذار. دادهٔ این خوراک ساختگی است و روی آن هیچ ادعای درآمدی نمی‌شود.",
16
+ "gives": "قیمت یک لنگه (قیمت پایه) برای همهٔ نمادها، با نوسان ساختگی و یک رخداد برنامه‌ریزی‌شده برای دیدن سیگنال",
17
+ "after": "ستون تازگی داده سبز می‌شود و قیمت‌ها هر چند ثانیه عوض می‌شوند؛ یعنی کل مسیر فنی «زنده» کار می‌کند.",
18
+ "steps": "۱) در پوشهٔ ایستگاه دستور `python mock_feed.py` را اجرا کنید (یا خوراک همراه کارساز خودکار بالا می‌آید). ۲) همین پروفایل را انتخاب و آزمایش کنید.",
19
+ "tested": true,
20
+ "custom": false
21
+ },
22
+ {
23
+ "name": "tgju-usd",
24
+ "label": "tgju — دلار، طلا، سکه (رایگان، آزمون‌شده)",
25
+ "cost": "رایگان",
26
+ "url_template": "https://api.tgju.org/v1/market/indicator/summary-table-data/{symbol}",
27
+ "json_path": "data.0.3",
28
+ "key_header": "",
29
+ "key_query_name": "",
30
+ "env_key": "",
31
+ "note": "آزمون‌شده در ۲۲ سپتامبر ۲۰۲۶: پاسخ ۲۰۰ در ۰٫۳ تا ۱٫۸ ثانیه. ستون چهارم سطر اول = قیمت پایانی. پنج شاخص (دلار، گرم طلای ۱۸، سکهٔ امامی، نیم، ربع) با یک نقطهٔ پایانی مستقل (call1.tgju.org/ajax.json) مقایسه شد و هر پنج عدد یکی درآمد؛ پس مسیر «data.0.3» درست است. اگر روزی ساختار عوض شد، با «کاوش پاسخ سرویس» مسیر تازه را پیدا کنید.",
32
+ "gives": "قیمت زندهٔ دلار، طلا و سکه. نماد ردیف را نام شاخص tgju بگذارید: price_dollar_rl (دلار) · geram18 (گرم طلای ۱۸) · sekeb (سکهٔ امامی) · sekee (سکهٔ بهار) · nim (نیم) · rob (ربع).",
33
+ "after": "تازگی داده سبز می‌شود و برای ردیف‌های دلار/طلا/سکه قیمت واقعی می‌آید. این خوراک برای سهام، آتی و اختیار چیزی نمی‌دهد؛ برای آزمون «قیمت زنده» و برای نرخ طلا/ارز پایهٔ محاسبهٔ آتی طلا کافی است.",
34
+ "steps": "۱) ردیف اسنپ‌شات بسازید و در ستون نماد همان نام انگلیسی شاخص را بگذارید (مثل price_dollar_rl). ۲) همین پروفایل را انتخاب و «آزمایش اتصال» را بزنید.",
35
+ "tested": true,
36
+ "custom": false
37
+ },
38
+ {
39
+ "name": "tsetmc-cdn",
40
+ "label": "tsetmc — قیمت پایانی سهام و آپشن (رایگان، آزمون‌نشده)",
41
+ "cost": "رایگان",
42
+ "url_template": "https://cdn.tsetmc.com/api/ClosingPrice/GetClosingPriceDailyList/{symbol}/0",
43
+ "json_path": "closingPriceDaily.0.pClosing",
44
+ "key_header": "",
45
+ "key_query_name": "",
46
+ "env_key": "",
47
+ "note": "منبع رسمی و رایگان است ولی بی‌تعهد. در نشانی، {symbol} باید «کد نماد» (insCode) باشد نه نام نماد؛ کد را در فیلد feed_symbol هر ردیف اسنپ‌شات بگذارید.",
48
+ "gives": "قیمت پایانی روز برای سهم و آپشن، بر پایهٔ کد نماد",
49
+ "after": "قیمت پایه از منبع رسمی می‌آید؛ ولی نرخ به‌روزرسانی روزانه است، نه لحظه‌ای.",
50
+ "steps": "۱) کد نماد هر سهم را از سایت tsetmc بردارید. ۲) در اسنپ‌شات، فیلد feed_symbol هر ردیف را با آن کد پر کنید. ۳) آزمون اتصال.",
51
+ "tested": false,
52
+ "custom": false
53
+ },
54
+ {
55
+ "name": "broker-service",
56
+ "label": "سرویس دادهٔ خریدنی (کلیددار) — قالب نمونه",
57
+ "cost": "خریدنی",
58
+ "url_template": "https://api.example.ir/Quote.php?key={key}&l18={symbol}",
59
+ "json_path": "data.0.pl",
60
+ "key_header": "",
61
+ "key_query_name": "key",
62
+ "env_key": "MARKET_API_KEY",
63
+ "note": "این قالب نمونهٔ عمومی است؛ قالب واقعی را از مستندات فروشنده کپی کنید. معمولاً ۴ چیز می‌دهند: قیمت پایه، ریزمعاملات، زنجیرهٔ آپشن، دادهٔ تاریخی.",
64
+ "gives": "قیمت زندهٔ همهٔ نمادها + دادهٔ تاریخی برای پس‌آزمایی",
65
+ "after": "قیمت پایه هر ۳۰ ثانیه خودکار تازه می‌شود، تازگی داده سبز می‌ماند، و پس‌آزمایی روی دادهٔ واقعی ممکن می‌شود. وجه تضمین همچنان دستی از کارگزاری می‌آید.",
66
+ "steps": "۱) کلید را از فروشنده بگیرید. ۲) قالب نشانی و مسیر JSON را از مستنداتش کپی کنید. ۳) کلید را همین‌جا بگذارید. ۴) آزمون اتصال. ۵) اگر درست بود، «ذخیره» بزنید تا هر بار خودکار وصل شود.",
67
+ "tested": false,
68
+ "custom": false
69
+ },
70
+ {
71
+ "name": "custom",
72
+ "label": "اتصال دلخواه (خودم پرش می‌کنم)",
73
+ "cost": "رایگان",
74
+ "url_template": "",
75
+ "json_path": "",
76
+ "key_header": "",
77
+ "key_query_name": "key",
78
+ "env_key": "",
79
+ "note": "هر سرویسی که خواستید. دو چیز لازم است: نشانی‌ای که {symbol} در آن باشد، و مسیر رسیدن به عدد قیمت در پاسخ JSON.",
80
+ "gives": "هر چیزی که سرویس بدهد",
81
+ "after": "همان لحظه‌ای که نشانی درست شود، قیمت زنده در همهٔ گام‌ها جاری می‌شود.",
82
+ "steps": "۱) «کاوش پاسخ سرویس» را بزنید و نشانی را آزمایش کنید. ۲) از فهرست، مسیر عدد قیمت را انتخاب کنید. ۳) ذخیره.",
83
+ "tested": false,
84
+ "custom": false
85
+ },
86
+ {
87
+ "name": "exchange-irt",
88
+ "label": "صرافی ایرانی — نرخ لحظه‌ای (رایگان، تأییدشده)",
89
+ "cost": "رایگان",
90
+ "url_template": "https://api.exir.io/v2/ticker?symbol={symbol}",
91
+ "json_path": "last",
92
+ "key_header": "",
93
+ "key_query_name": "",
94
+ "env_key": "",
95
+ "note": "خودکار پیدا شد (2026-09-22) · بازارهای ریالی این صرافی: usdt-irt · btc-irt · eth-irt · ada-irt · ton-irt و چند تای دیگر. برای اینکه هر ردیف قیمت خودش را بگیرد، در فیلد «کد نماد» آن ردیف نام بازار را بنویسید (مثلاً usdt-irt). کاربردش اثبات کارکرد اتصال زندهٔ واقعی بدون کلید است، نه ساختن سیگنال سهام.",
96
+ "gives": "بازارهای ریالی این صرافی: usdt-irt · btc-irt · eth-irt · ada-irt · ton-irt و چند تای دیگر. برای اینکه هر ردیف قیمت خودش را بگیرد، در فیلد «کد نماد» آن ردیف نام بازار را بنویسید (مثلاً usdt-irt). کاربردش اثبات کارکرد اتصال زندهٔ واقعی بدون کلید است، نه ساختن سیگنال سهام.",
97
+ "after": "قیمت پایه از همین منبع خوانده می‌شود و ستون تازگی داده سبز می‌ماند.",
98
+ "steps": "همین حالا فعال شد؛ برای عوض‌کردن، از دفتر اتصال پروفایل دیگری انتخاب کنید.",
99
+ "tested": true,
100
+ "custom": true
101
+ },
102
+ {
103
+ "name": "tgju-dollar",
104
+ "label": "tgju — دلار (رایگان، خودکار پیدا شد)",
105
+ "cost": "رایگان",
106
+ "url_template": "https://api.tgju.org/v1/market/indicator/summary-table-data/price_dollar_rl",
107
+ "json_path": "data.0.3",
108
+ "key_header": "",
109
+ "key_query_name": "",
110
+ "env_key": "",
111
+ "note": "خودکار پیدا شد (2026-09-22) · قیمت پایانی دلار آزاد در ستون چهارم سطر اول (`data.0.3`). آزمون‌شده: با یک نقطهٔ پایانی مستقل (call1.tgju.org/ajax.json) هم‌خوان بود.",
112
+ "gives": "قیمت پایانی دلار آزاد در ستون چهارم سطر اول (`data.0.3`). آزمون‌شده: با یک نقطهٔ پایانی مستقل (call1.tgju.org/ajax.json) هم‌خوان بود.",
113
+ "after": "قیمت پایه از همین منبع خوانده می‌شود و ستون تازگی داده سبز می‌ماند.",
114
+ "steps": "همین حالا فعال شد؛ برای عوض‌کردن، از دفتر اتصال پروفایل دیگری انتخاب کنید.",
115
+ "tested": true,
116
+ "custom": true
117
+ }
118
+ ],
119
+ "preset_version": 3
120
+ }
station/connections.py ADDED
@@ -0,0 +1,367 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env python3
2
+ # -*- coding: utf-8 -*-
3
+ """دفترِ اتصال‌ها — «هر وقت سرویس را گرفتم، همین‌جا وصلش کنم و استفاده کنم».
4
+
5
+ چه چیزی ذخیره می‌شود:
6
+ • `config/connections.json` : مشخصات اتصال (قالب نشانی، مسیر JSON، نام هدر کلید، …) — بدون کلید.
7
+ • `config/keys.local.json` : کلیدها، فقط اگر خودتان صریحاً «ذخیرهٔ کلید» را بزنید.
8
+
9
+ چرا کلید جدا و اختیاری؟ چون کلید پول است. پیش‌فرض این است که کلید در هیچ پرونده‌ای نوشته نشود
10
+ و فقط تا بسته‌شدن برنامه در حافظه بماند. اگر ذخیره کنید، پرونده فقط روی همین رایانه است،
11
+ ولی هر کسی که به این پوشه دسترسی داشته باشد می‌تواند آن را ببیند — پس به‌جز رایانهٔ خودتان،
12
+ آن را جای دیگری نگه ندارید و در گیت/تلگرام نفرستید.
13
+ """
14
+ from __future__ import annotations
15
+
16
+ import json
17
+ import os
18
+ from datetime import datetime, timezone
19
+ from pathlib import Path
20
+
21
+ VERSION = "0.1.0"
22
+ BASE = Path(__file__).resolve().parent
23
+ CONFIG_DIR = BASE / "config"
24
+ PROFILES_FILE = CONFIG_DIR / "connections.json"
25
+ KEYS_FILE = CONFIG_DIR / "keys.local.json"
26
+
27
+ FREE = "رایگان"
28
+ PAID = "خریدنی"
29
+ # با هر تغییر در پروفایل‌های آماده، این شماره را بالا ببرید تا روی نسخه‌های قبلی هم به‌روز شود.
30
+ PRESET_VERSION = 3
31
+
32
+ # نگه‌داشته‌شده‌ها «نقطهٔ شروع» هستند، نه وعده: هر کدام را با دکمهٔ «آزمایش اتصال» بررس کنید.
33
+ PRESET_PROFILES: list[dict] = [
34
+ {
35
+ "name": "mock-local",
36
+ "label": "خوراک آزمایشی محلی (بدون اینترنت، بدون هزینه)",
37
+ "cost": FREE,
38
+ "url_template": "http://127.0.0.1:8788/quote?symbol={symbol}",
39
+ "json_path": "data.0.pl",
40
+ "key_header": "", "key_query_name": "", "env_key": "",
41
+ "tested": True,
42
+ "note": "برای آزمایش کامل برنامه و نشان‌دادن کارکردِ اتصال زنده به سرمایه‌گذار. دادهٔ این خوراک ساختگی است و روی آن هیچ ادعای درآمدی نمی‌شود.",
43
+ "gives": "قیمت یک لنگه (قیمت پایه) برای همهٔ نمادها، با نوسان ساختگی و یک رخداد برنامه‌ریزی‌شده برای دیدن سیگنال",
44
+ "after": "ستون تازگی داده سبز می‌شود و قیمت‌ها هر چند ثانیه عوض می‌شوند؛ یعنی کل مسیر فنی «زنده» کار می‌کند.",
45
+ "steps": "۱) در پوشهٔ ایستگاه دستور `python mock_feed.py` را اجرا کنید (یا خوراک همراه کارساز خودکار بالا می‌آید). ۲) همین پروفایل را انتخاب و آزمایش کنید.",
46
+ },
47
+ {
48
+ "name": "tgju-usd",
49
+ "label": "tgju — دلار، طلا، سکه (رایگان، آزمون‌شده)",
50
+ "cost": FREE,
51
+ "url_template": "https://api.tgju.org/v1/market/indicator/summary-table-data/{symbol}",
52
+ "json_path": "data.0.3",
53
+ "key_header": "", "key_query_name": "", "env_key": "",
54
+ "tested": True,
55
+ "note": ("آزمون‌شده در ۲۲ سپتامبر ۲۰۲۶: پاسخ ۲۰۰ در ۰٫۳ تا ۱٫۸ ثانیه. ستون چهارم سطر اول = "
56
+ "قیمت پایانی. پنج شاخص (دلار، گرم طلای ۱۸، سکهٔ امامی، نیم، ربع) با یک نقطهٔ "
57
+ "پایانی مستقل (call1.tgju.org/ajax.json) مقایسه شد و هر پنج عدد یکی درآمد؛ پس "
58
+ "مسیر «data.0.3» درست است. اگر روزی ساختار عوض شد، با «کاوش پاسخ سرویس» مسیر "
59
+ "تازه را پیدا کنید."),
60
+ "gives": ("قیمت زندهٔ دلار، طلا و سکه. نماد ردیف را نام شاخص tgju بگذارید: price_dollar_rl "
61
+ "(دلار) · geram18 (گرم طلای ۱۸) · sekeb (سکهٔ امامی) · sekee (سکهٔ بهار) · "
62
+ "nim (نیم) · rob (ربع)."),
63
+ "after": ("تازگی داده سبز می‌شود و برای ردیف‌های دلار/طلا/سکه قیمت واقعی می‌آید. این "
64
+ "خوراک برای سهام، آتی و اختیار چیزی نمی‌دهد؛ برای آزمون «قیمت زنده» و برای "
65
+ "نرخ طلا/ارز پایهٔ محاسبهٔ آتی طلا کافی است."),
66
+ "steps": ("۱) ردیف اسنپ‌شات بسازید و در ستون نماد همان نام انگلیسی شاخص را بگذارید "
67
+ "(مثل price_dollar_rl). ۲) همین پروفایل را انتخاب و «آزمایش اتصال» را بزنید."),
68
+ },
69
+ {
70
+ "name": "tsetmc-cdn",
71
+ "label": "tsetmc — قیمت پایانی سهام و آپشن (رایگان، آزمون‌نشده)",
72
+ "cost": FREE,
73
+ "url_template": "https://cdn.tsetmc.com/api/ClosingPrice/GetClosingPriceDailyList/{symbol}/0",
74
+ "json_path": "closingPriceDaily.0.pClosing",
75
+ "key_header": "", "key_query_name": "", "env_key": "",
76
+ "tested": False,
77
+ "note": "منبع رسمی و رایگان است ولی بی‌تعهد. در نشانی، {symbol} باید «کد نماد» (insCode) باشد نه نام نماد؛ کد را در فیلد feed_symbol هر ردیف اسنپ‌شات بگذارید.",
78
+ "gives": "قیمت پایانی روز برای سهم و آپشن، بر پایهٔ کد نماد",
79
+ "after": "قیمت پایه از منبع رسمی می‌آید؛ ولی نرخ به‌روزرسانی روزانه است، نه لحظه‌ای.",
80
+ "steps": "۱) کد نماد هر سهم را از سایت tsetmc بردارید. ۲) در اسنپ‌شات، فیلد feed_symbol هر ردیف را با آن کد پر کنید. ۳) آزمون اتصال.",
81
+ },
82
+ {
83
+ "name": "exchange-irt",
84
+ "label": "صرافی ایرانی — نرخ ریالی (رایگان، آزمون‌نشده)",
85
+ "cost": FREE,
86
+ "url_template": "https://api.exir.io/v2/ticker?symbol={symbol}",
87
+ "json_path": "last",
88
+ "key_header": "", "key_query_name": "", "env_key": "",
89
+ "tested": True,
90
+ "note": ("این سرویس در آزمون واقعی پاسخ سالم داد (شهریور ۱۴۰۵). برای هر ردیف، در ستون «کد نماد» "
91
+ "نام بازار را بنویسید: usdt-irt · btc-irt · eth-irt و مانند این‌ها. کاربردش اثبات اتصال زندهٔ "
92
+ "واقعی بدون کلید است، نه ساختن سیگنال سهام."),
93
+ "gives": "نرخ لحظه‌ای ریالی از یک بازار واقعی، بدون کلید و بدون هزینه",
94
+ "after": "تازگی داده سبز می‌شود و می‌بینید قیمت واقعی همان لحظه خوانده می‌شود.",
95
+ "steps": "۱) پروفایل را انتخاب کنید. ۲) در گام ۲ جدول «وارد کردن اعداد کارگزاری»، در ستون کد نماد نام بازار را بنویسید. ۳) آزمون اتصال.",
96
+ },
97
+ {
98
+ "name": "broker-service",
99
+ "label": "سرویس دادهٔ خریدنی (کلیددار) — قالب نمونه",
100
+ "cost": PAID,
101
+ "url_template": "https://api.example.ir/Quote.php?key={key}&l18={symbol}",
102
+ "json_path": "data.0.pl",
103
+ "key_header": "", "key_query_name": "key", "env_key": "MARKET_API_KEY",
104
+ "tested": False,
105
+ "note": "این قالب نمونهٔ عمومی است؛ قالب واقعی را از مستندات فروشنده کپی کنید. معمولاً ۴ چیز می‌دهند: قیمت پایه، ریزمعاملات، زنجیرهٔ آپشن، دادهٔ تاریخی.",
106
+ "gives": "قیمت زندهٔ همهٔ نمادها + دادهٔ تاریخی برای پس‌آزمایی",
107
+ "after": "قیمت پایه هر ۳۰ ثانیه خودکار تازه می‌شود، تازگی داده سبز می‌ماند، و پس‌آزمایی روی دادهٔ واقعی ممکن می‌شود. وجه تضمین همچنان دستی از کارگزاری می‌آید.",
108
+ "steps": "۱) کلید را از فروشنده بگیرید. ۲) قالب نشانی و مسیر JSON را از مستنداتش کپی کنید. ۳) کلید را همین‌جا بگذارید. ۴) آزمون اتصال. ۵) اگر درست بود، «ذخیره» بزنید تا هر بار خودکار وصل شود.",
109
+ },
110
+ {
111
+ "name": "custom",
112
+ "label": "اتصال دلخواه (خودم پرش می‌کنم)",
113
+ "cost": FREE,
114
+ "url_template": "", "json_path": "", "key_header": "", "key_query_name": "key", "env_key": "",
115
+ "tested": False,
116
+ "note": "هر سرویسی که خواستید. دو چیز لازم است: نشانی‌ای که {symbol} در آن باشد، و مسیر رسیدن به عدد قیمت در پاسخ JSON.",
117
+ "gives": "هر چیزی که سرویس بدهد",
118
+ "after": "همان لحظه‌ای که نشانی درست شود، قیمت زنده در همهٔ گام‌ها جاری می‌شود.",
119
+ "steps": "۱) «کاوش پاسخ سرویس» را بزنید و نشانی را آزمایش کنید. ۲) از فهرست، مسیر عدد قیمت را انتخاب کنید. ۳) ذخیره.",
120
+ },
121
+ ]
122
+
123
+ PROFILE_FIELDS = ("name", "label", "cost", "url_template", "json_path", "key_header",
124
+ "key_query_name", "env_key", "note", "gives", "after", "steps", "tested", "custom")
125
+
126
+
127
+ def _now() -> str:
128
+ return datetime.now(timezone.utc).isoformat(timespec="seconds")
129
+
130
+
131
+ def _clean(profile: dict) -> dict:
132
+ out = {k: profile.get(k, "") for k in PROFILE_FIELDS}
133
+ out["name"] = str(out["name"] or "").strip() or "custom"
134
+ out["label"] = str(out["label"] or out["name"]).strip()
135
+ out["tested"] = bool(out.get("tested"))
136
+ out["custom"] = bool(profile.get("custom")) # دست‌کاری کاربر: در به‌روزرسانی‌ها دست نمی‌زنیم
137
+ for k in ("url_template", "json_path", "key_header", "key_query_name", "env_key"):
138
+ out[k] = str(out[k] or "").strip()
139
+ return out
140
+
141
+
142
+ def default_store() -> dict:
143
+ return {"version": 1, "preset_version": PRESET_VERSION, "selected": "mock-local",
144
+ "updated_at": _now(), "profiles": [_clean(p) for p in PRESET_PROFILES]}
145
+
146
+
147
+ def _refresh_presets(data: dict) -> tuple[dict, bool]:
148
+ """پروفایل‌های آماده را به نسخهٔ تازهٔ برنامه به‌روز می‌کند.
149
+
150
+ پروفایل‌هایی که خودِ کاربر ساخته یا دست‌کاری کرده (custom) دست‌نخورده می‌مانند؛
151
+ بدون این کار، کاربر نسخهٔ قدیمی برنامه را نگه می‌داشت و نشانی‌های اصلاح‌شده را نمی‌دید.
152
+ """
153
+ changed = False
154
+ if int(data.get("preset_version", 1)) >= PRESET_VERSION:
155
+ return data, changed
156
+ by_name = {p["name"]: _clean(p) for p in PRESET_PROFILES}
157
+ out = []
158
+ for prof in data.get("profiles", []):
159
+ name = prof.get("name")
160
+ if name in by_name and not prof.get("custom"):
161
+ out.append(dict(by_name[name], custom=False))
162
+ changed = True
163
+ else:
164
+ out.append(prof)
165
+ data["profiles"] = out
166
+ data["preset_version"] = PRESET_VERSION
167
+ return data, True
168
+
169
+
170
+ def load_store() -> dict:
171
+ """دفتر اتصال‌ها را می‌خواند؛ اگر نبود، نسخهٔ پیش‌فرض را می‌سازد."""
172
+ if PROFILES_FILE.exists():
173
+ try:
174
+ data = json.loads(PROFILES_FILE.read_text(encoding="utf-8"))
175
+ except Exception:
176
+ return default_store()
177
+ if not isinstance(data, dict) or not isinstance(data.get("profiles"), list):
178
+ return default_store()
179
+ seen = {p["name"] for p in data["profiles"] if isinstance(p, dict)}
180
+ for preset in PRESET_PROFILES: # پروفایل‌های تازهٔ نسخهٔ جدید هم اضافه می‌شوند
181
+ if preset["name"] not in seen:
182
+ data["profiles"].append(_clean(preset))
183
+ data["profiles"] = [_clean(p) for p in data["profiles"] if isinstance(p, dict)]
184
+ data.setdefault("selected", "mock-local")
185
+ data, changed = _refresh_presets(data)
186
+ if changed:
187
+ save_store(data)
188
+ return data
189
+ return default_store()
190
+
191
+
192
+ def save_store(store: dict) -> Path:
193
+ CONFIG_DIR.mkdir(parents=True, exist_ok=True)
194
+ store = dict(store)
195
+ store["version"] = 1
196
+ store["updated_at"] = _now()
197
+ store["profiles"] = [_clean(p) for p in store.get("profiles", [])]
198
+ PROFILES_FILE.write_text(json.dumps(store, ensure_ascii=False, indent=2), encoding="utf-8")
199
+ return PROFILES_FILE
200
+
201
+
202
+ def find_profile(store: dict, name: str) -> dict | None:
203
+ for p in store.get("profiles", []):
204
+ if p.get("name") == name:
205
+ return p
206
+ return None
207
+
208
+
209
+ def upsert_profile(store: dict, profile: dict) -> dict:
210
+ prof = _clean(profile)
211
+ prof["custom"] = True if profile.get("custom") is None else bool(profile.get("custom"))
212
+ existing = find_profile(store, prof["name"])
213
+ if existing:
214
+ existing.update(prof)
215
+ prof = existing
216
+ else:
217
+ store.setdefault("profiles", []).append(prof)
218
+ return prof
219
+
220
+
221
+ def select_profile(store: dict, name: str) -> dict | None:
222
+ prof = find_profile(store, name)
223
+ if prof is None:
224
+ return None
225
+ store["selected"] = name
226
+ return prof
227
+
228
+
229
+ def delete_profile(store: dict, name: str) -> bool:
230
+ before = len(store.get("profiles", []))
231
+ store["profiles"] = [p for p in store.get("profiles", []) if p.get("name") != name]
232
+ if store.get("selected") == name:
233
+ store["selected"] = (store["profiles"][0]["name"] if store["profiles"] else "custom")
234
+ return len(store["profiles"]) != before
235
+
236
+
237
+ # ---------------------------------------------------------------- کلیدها
238
+ def load_keys() -> dict:
239
+ if KEYS_FILE.exists():
240
+ try:
241
+ data = json.loads(KEYS_FILE.read_text(encoding="utf-8"))
242
+ return data if isinstance(data, dict) else {}
243
+ except Exception:
244
+ return {}
245
+ return {}
246
+
247
+
248
+ def save_key(name: str, key: str) -> Path:
249
+ """کلید را روی رایانهٔ خودتان ذخیره می‌کند (فقط با درخواست صریح شما)."""
250
+ CONFIG_DIR.mkdir(parents=True, exist_ok=True)
251
+ data = load_keys()
252
+ if key:
253
+ data[name] = {"key": key, "saved_at": _now()}
254
+ else:
255
+ data.pop(name, None)
256
+ KEYS_FILE.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
257
+ try:
258
+ os.chmod(KEYS_FILE, 0o600)
259
+ except OSError: # ویندوز این را نادیده می‌گیرد؛ اشکالی ندارد
260
+ pass
261
+ return KEYS_FILE
262
+
263
+
264
+ def stored_key(name: str) -> str:
265
+ rec = load_keys().get(name) or {}
266
+ return str(rec.get("key", "")) if isinstance(rec, dict) else ""
267
+
268
+
269
+ def resolve_key(profile: dict, *, inline_key: str = "") -> tuple[str, str]:
270
+ """کلید را به ترتیب اولویت پیدا می‌کند و می‌گوید از کجا آمد.
271
+
272
+ ترتیب: کلیدی که همین حالا در کادر گذاشته‌اید ← کلید ذخیره‌شده ← متغیر محیطی.
273
+ هیچ‌وقت کلید را در لاگ یا گزارش چاپ نمی‌کند.
274
+ """
275
+ if inline_key:
276
+ return inline_key, "کادر همین لحظه"
277
+ saved = stored_key(str(profile.get("name", "")))
278
+ if saved:
279
+ return saved, "ذخیره‌شده روی همین رایانه"
280
+ env_name = str(profile.get("env_key", "") or "").strip()
281
+ if env_name:
282
+ env_val = os.environ.get(env_name, "")
283
+ if env_val:
284
+ return env_val, f"متغیر محیطی {env_name}"
285
+ return "", "بدون کلید"
286
+
287
+
288
+ def key_status(name: str) -> dict:
289
+ store = load_store()
290
+ prof = find_profile(store, name) or {}
291
+ key, where = resolve_key(prof)
292
+ env_name = str(prof.get("env_key", "") or "")
293
+ return {"stored": bool(stored_key(name)), "where": where, "has_key": bool(key),
294
+ "env_key": env_name, "env_set": bool(env_name and os.environ.get(env_name))}
295
+
296
+
297
+ def live_config(profile: dict) -> dict:
298
+ """پروفایل را به قالب تنظیمات زندهٔ datafeed تبدیل می‌کند."""
299
+ import datafeed # واردکردن تنبل: این ماژول باید مستقل هم کار کند
300
+ cfg = dict(datafeed.DEFAULT_LIVE_CONFIG)
301
+ cfg["url_template"] = str(profile.get("url_template", "") or "")
302
+ cfg["json_path"] = str(profile.get("json_path", "") or "")
303
+ cfg["key_header"] = str(profile.get("key_header", "") or "")
304
+ cfg["key_query_name"] = str(profile.get("key_query_name", "") or "")
305
+ return cfg
306
+
307
+
308
+ def apply_profile(store: dict, name: str, *, inline_key: str = "") -> dict:
309
+ """پروفایل انتخابی را «فعال» می‌کند: تنظیمات زنده + کلید + یادداشت منبع."""
310
+ prof = select_profile(store, name)
311
+ if prof is None:
312
+ raise KeyError(f"پروفایل پیدا نشد: {name}")
313
+ key, where = resolve_key(prof, inline_key=inline_key)
314
+ return {"name": prof["name"], "profile": prof, "live_cfg": live_config(prof),
315
+ "key": key, "key_where": where, "is_mock": prof["name"] == "mock-local"}
316
+
317
+
318
+ def active_or_none() -> dict | None:
319
+ """پروفایل فعالِ ذخیره‌شده را برمی‌گرداند (برای راه‌اندازی خودکار برنامه)."""
320
+ store = load_store()
321
+ name = store.get("selected") or ""
322
+ if not name or find_profile(store, name) is None:
323
+ return None
324
+ try:
325
+ return apply_profile(store, name)
326
+ except KeyError:
327
+ return None
328
+
329
+
330
+ def summary_rows() -> list[list[str]]:
331
+ """ردیف‌های خلاصه برای جدول رابط گرافیکی."""
332
+ store = load_store()
333
+ rows = []
334
+ for p in store.get("profiles", []):
335
+ status = "آزمون‌شده" if p.get("tested") else "آزمون‌نشده"
336
+ mark = "★" if p.get("name") == store.get("selected") else ""
337
+ rows.append([mark, p.get("label", p["name"]), p.get("cost", ""), status,
338
+ p.get("url_template", "") or "—"])
339
+ return rows
340
+
341
+
342
+ def main(argv: list[str] | None = None) -> int:
343
+ import argparse
344
+ ap = argparse.ArgumentParser(description="دفتر اتصال‌های ایستگاه")
345
+ ap.add_argument("--list", action="store_true", help="نمایش پروفایل‌ها")
346
+ ap.add_argument("--select", help="انتخاب پروفایل با نام")
347
+ args = ap.parse_args(argv)
348
+ store = load_store()
349
+ if args.select:
350
+ prof = select_profile(store, args.select)
351
+ if prof is None:
352
+ print("پروفایل پیدا نشد.")
353
+ return 2
354
+ save_store(store)
355
+ print(f"پروفایل فعال شد: {prof['label']}")
356
+ if args.list or not args.select:
357
+ active = store.get("selected")
358
+ for row in summary_rows():
359
+ print(" | ".join(str(c) for c in row))
360
+ print(f"فعال: {active}")
361
+ print(f"پروندهٔ مشخصات: {PROFILES_FILE}")
362
+ print(f"کلیدهای ذخیره‌شده: {'دارد' if load_keys() else 'ندارد'}")
363
+ return 0
364
+
365
+
366
+ if __name__ == "__main__":
367
+ raise SystemExit(main())
station/daily_trial.py ADDED
@@ -0,0 +1,386 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env python3
2
+ # -*- coding: utf-8 -*-
3
+ """مراسم روزانه — یک دستور، تمام کارهای آزمون دو هفته‌ای.
4
+
5
+ منطق کار: هر روز کاری یک بار این برنامه را اجرا می‌کنید (یا ویندوز خودش اجرا می‌کند).
6
+ شش کار انجام می‌شود و هیچ‌کدام سفارش‌گذاری نیست:
7
+
8
+ ۱. قیمت‌ها خوانده می‌شوند (زنده، یا پروندهٔ دستی، یا دادهٔ نمونه — با برچسب صادق).
9
+ ۲. موتور ریاضی روی همان قیمت‌ها اجرا می‌شود.
10
+ ۳. سیگنال‌های امروز در «دفتر آزمون زنده» ثبت می‌شوند (با زنجیرهٔ هش).
11
+ ۴. ردیف‌های قبلی با قیمت‌های تازه بازسنجی می‌شوند.
12
+ ۵. سالم‌بودن زنجیره بررسی و گزارش سرمایه‌گذار ساخته می‌شود.
13
+ ۶. «کارنامه» به‌روز می‌شود: آیا سابقهٔ ثبت‌شده به‌قدری هست که خرید دادهٔ زنده و رفتن
14
+ به جلسهٔ شرکت معنی داشته باشد، یا هنوز نه.
15
+
16
+ هر اجرا در `data/trial-daily.log` هم ثبت می‌شود تا روزها قابل شمارش باشند.
17
+ """
18
+ from __future__ import annotations
19
+
20
+ import argparse
21
+ import json
22
+ import sys
23
+ import time
24
+ from datetime import datetime, timezone
25
+ from pathlib import Path
26
+
27
+ VERSION = "0.1.0"
28
+ BASE = Path(__file__).resolve().parent
29
+ DATA = BASE / "data"
30
+ DESK_DIR = (BASE.parent / "desk").resolve()
31
+ KODAL_DIR = (BASE.parent / "kodal-alert").resolve()
32
+ LOG_FILE = DATA / "trial-daily.log"
33
+ REPORT_FILE = DATA / "trial-report.html"
34
+ RUNNING_SNAPSHOT = DATA / "current-snapshot.json"
35
+
36
+ for p in (str(BASE), str(DESK_DIR), str(KODAL_DIR)):
37
+ if p not in sys.path:
38
+ sys.path.insert(0, p)
39
+
40
+ import datafeed # noqa: E402
41
+ import live_trial as trial # noqa: E402
42
+
43
+ DEFAULT_RULES = {
44
+ "capital": 20_000_000_000, "hurdle": 0.39,
45
+ "min_edge_arbitrage_pct": 3.0, "min_edge_leveraged_pct": 5.0,
46
+ "max_margin_pct": 0.20, "max_position_pct": 0.35, "max_positions": 3,
47
+ "min_liquidity_contracts_per_day": 20, "max_spread_pct": 0.03,
48
+ "max_plausible_arb_pct": 250.0, "max_plausible_lev_pct": 400.0,
49
+ }
50
+
51
+ SYNTHETIC_MARKS = ("ساختگی", "نمونهٔ همراه")
52
+ SYNTHETIC_PATH_MARKS = ("demo", "sample", "template", "نمونه", "قالب")
53
+
54
+
55
+ def _now() -> str:
56
+ return datetime.now(timezone.utc).isoformat(timespec="seconds")
57
+
58
+
59
+ def today() -> str:
60
+ return time.strftime("%Y-%m-%d")
61
+
62
+
63
+ def is_synthetic(source_label: str) -> bool:
64
+ """آیا این داده ساختگی است؟ برچسب منبع را می‌خوانیم، نه حدس را."""
65
+ return any(m in str(source_label or "") for m in SYNTHETIC_MARKS)
66
+
67
+
68
+ def path_is_synthetic(path) -> bool:
69
+ """پروندهٔ نمونه و قالب (مثل market-demo.json) دادهٔ واقعی حساب نمی‌شود.
70
+
71
+ بی این سنجه، کسی می‌توانست با دادن پروندهٔ نمونه، روز «واقعی» جعل کند و کارنامه
72
+ بی‌دلیل سبز شود.
73
+ """
74
+ if not path:
75
+ return False
76
+ name = str(path).replace("\\", "/").lower()
77
+ base = name.rsplit("/", 1)[-1]
78
+ if any(m in base for m in SYNTHETIC_PATH_MARKS):
79
+ return True
80
+ return any(part in ("demo", "samples", "templates") for part in name.split("/")[:-1])
81
+
82
+
83
+ def write_running_snapshot(snap, rules: dict, path: Path | str | None = None) -> Path:
84
+ """اسنپ‌شات جاری را به قالب بازار میز معاملات می‌نویسد."""
85
+ rows = [{k: v for k, v in r.items() if not k.startswith("_")} for r in snap.rows]
86
+ out = Path(path or RUNNING_SNAPSHOT)
87
+ out.parent.mkdir(parents=True, exist_ok=True)
88
+ out.write_text(json.dumps({"as_of": time.strftime("%Y-%m-%d %H:%M"),
89
+ "hurdle": rules.get("hurdle", 0.39),
90
+ "capital": rules.get("capital", 20_000_000_000),
91
+ "rows": rows}, ensure_ascii=False, indent=2), encoding="utf-8")
92
+ return out
93
+
94
+
95
+ def scan_signals(market_path: Path | str, rules: dict, *, desk_db=None, kodal_db=None) -> list:
96
+ """موتور میز معاملات را روی اسنپ‌شات اجرا می‌کند و سیگنال‌های خام را برمی‌گرداند."""
97
+ import desk as deskmod
98
+ cfg = dict(getattr(deskmod, "DEFAULT_CONFIG", {}))
99
+ cfg.update({k: v for k, v in (rules or {}).items() if k in DEFAULT_RULES})
100
+ if desk_db:
101
+ cfg["desk_db"] = str(desk_db)
102
+ desk_obj = deskmod.Desk(cfg.get("desk_db") or getattr(deskmod, "DEFAULT_DB"))
103
+ return deskmod.scan_market(market_path, cfg, desk_obj, kodal_db)
104
+
105
+
106
+ def now_map_from_signals(sigs, rules: dict) -> dict:
107
+ """حاشیهٔ امروز هر نماد، از سیگنال‌های تازه."""
108
+ out: dict = {}
109
+ for s in sigs or []:
110
+ kind = getattr(s, "kind", "")
111
+ floor = (rules.get("min_edge_arbitrage_pct", 3.0) if kind in ("basis", "arbitrage")
112
+ else rules.get("min_edge_leveraged_pct", 5.0))
113
+ detail = getattr(s, "detail", {}) or {}
114
+ out[str(getattr(s, "symbol", ""))] = {
115
+ "expected_now": getattr(s, "annualized_pct", None),
116
+ "floor": floor,
117
+ "spot_now": detail.get("spot") or detail.get("stock_price"),
118
+ "future_now": detail.get("future"),
119
+ }
120
+ return out
121
+
122
+
123
+ def pick_source(*, mode: str = "auto", file_path=None, live_cfg=None, key: str = "",
124
+ allow_network: bool = True, fallback_file=None, progress=None) -> tuple[object, str, list[str]]:
125
+ """منبع داده را انتخاب می‌کند: زنده (اگر تنظیم شده) ← پرونده ← نمونه. با برچسب صادق."""
126
+ notes: list[str] = []
127
+
128
+ def say(m: str) -> None:
129
+ notes.append(m)
130
+ if progress:
131
+ progress(m)
132
+
133
+ live_cfg = live_cfg or {}
134
+ url_ok = bool(str(live_cfg.get("url_template", "")).strip())
135
+ mode = (mode or "auto").lower()
136
+ if mode in ("live", "auto") and url_ok and allow_network:
137
+ snap = datafeed.build_snapshot("live", file_path=file_path, live_cfg=live_cfg, key=key,
138
+ allow_network=True, progress=progress)
139
+ if snap.status in ("ok", "partial") and snap.live_prices:
140
+ say(f"منبع: {snap.source_label} · {snap.messages[-1] if snap.messages else ''}")
141
+ return snap, "live", notes
142
+ say(f"دادهٔ زنده نیامد ({snap.status})؛ به منبع پشتیبان می‌رویم.")
143
+ if mode == "sim":
144
+ snap = datafeed.demo_snapshot()
145
+ say("منبع: دادهٔ نمونهٔ همراه برنامه (ساختگی).")
146
+ return snap, "sim", notes
147
+ path = file_path or fallback_file
148
+ if path and Path(path).exists():
149
+ snap = datafeed.load_snapshot_file(path)
150
+ say(f"منبع: پروندهٔ دستی {Path(path).name} — تازگی: {snap.freshness_label}")
151
+ return snap, "file", notes
152
+ snap = datafeed.demo_snapshot()
153
+ say("پرونده‌ای داده نشد؛ با دادهٔ نمونهٔ همراه برنامه (ساختگی) ادامه می‌دهیم.")
154
+ return snap, "sim", notes
155
+
156
+
157
+ def run_daily(*, mode: str = "auto", file_path=None, live_cfg=None, key: str = "",
158
+ rules: dict | None = None, note: str = "", db=None, report=None,
159
+ allow_network: bool = True, use_kodal: bool = True, add_span: float = 0.0,
160
+ fallback_file=None, desk_db=None, progress=None, log_path=None) -> dict:
161
+ """مراسم یک روز. خروجی: خلاصهٔ کارهایی که انجام شد (برای نمایش و برای لاگ)."""
162
+ rules = {k: (rules or {}).get(k, v) for k, v in DEFAULT_RULES.items()}
163
+ notes: list[str] = []
164
+
165
+ def say(m: str) -> None:
166
+ notes.append(m)
167
+ if progress:
168
+ progress(m)
169
+
170
+ errors: list[str] = []
171
+ snap, used_mode, src_notes = pick_source(mode=mode, file_path=file_path, live_cfg=live_cfg,
172
+ key=key, allow_network=allow_network,
173
+ fallback_file=fallback_file, progress=progress)
174
+ if not snap.rows:
175
+ return {"ok": False, "errors": ["هیچ ردیفی برای محاسبه نیست؛ منبع داده را بررسی کنید."],
176
+ "notes": notes, "handled": 0}
177
+
178
+ market_path = write_running_snapshot(snap, rules)
179
+ kodal_db = None
180
+ if use_kodal:
181
+ cand = KODAL_DIR / "data" / "demo.sqlite3"
182
+ kodal_db = cand if cand.exists() else None
183
+ try:
184
+ sigs = scan_signals(market_path, rules, kodal_db=kodal_db, desk_db=desk_db)
185
+ except Exception as e: # موتور نباید مراسم روزانه را بخواباند
186
+ return {"ok": False, "errors": [f"محاسبه انجام نشد: {e}"], "notes": notes, "handled": 0}
187
+ say(f"محاسبه انجام شد: {len(sigs)} ردیف.")
188
+
189
+ t = trial.Trial(db or trial.DEFAULT_DB)
190
+ saved = t.record_from_signals(sigs, source_label=snap.source_label, mode=used_mode,
191
+ add_span=add_span)
192
+ say(f"دفتر: {len(saved)} ردیف تازه ثبت شد (تکراری‌ها رد شدند).")
193
+ marked = t.mark(now_map_from_signals(sigs, rules))
194
+ say(f"دفتر: {len(marked)} ردیف با قیمت‌های امروز بازسنجی شد.")
195
+ chain_ok, chain_msg = t.verify_chain()
196
+ say(("زنجیرهٔ هش سالم است." if chain_ok else f"هشدار زنجیره: {chain_msg}"))
197
+
198
+ report_path = t.write_report(report or REPORT_FILE)
199
+ csv_path = t.write_csv(DATA / "trial-entries.csv")
200
+ summary = t.summary()
201
+
202
+ used_file = None
203
+ if used_mode == "file":
204
+ candidate = file_path or fallback_file
205
+ used_file = str(candidate) if candidate else None
206
+ unconfirmed = bool(used_file) and not datafeed.snapshot_confirmed(used_file)
207
+ synthetic = (is_synthetic(getattr(snap, "source_label", ""))
208
+ or path_is_synthetic(used_file) or unconfirmed)
209
+ rec = {
210
+ "ts": _now(), "date": today(), "mode": used_mode,
211
+ "source": getattr(snap, "source_label", ""),
212
+ "data_file": (Path(used_file).name if used_file else ""),
213
+ "confirmed_file": (datafeed.snapshot_confirmed(used_file) if used_file else False),
214
+ "synthetic": synthetic,
215
+ "rows": len(snap.rows), "signals": len(sigs), "recorded": len(saved),
216
+ "marked": len(marked), "entries": summary["entries"], "chain_ok": chain_ok,
217
+ "note": note, "report": str(report_path),
218
+ }
219
+ append_log(rec, log_path) # مسیر لاگ را می‌شود داد تا آزمون‌ها به دفتر واقعی دست نزنند
220
+ score = scorecard(t, log_records=read_log(log_path))
221
+ return {"ok": True, "notes": notes, "errors": errors, "record": rec, "summary": summary,
222
+ "scorecard": score, "report": str(report_path), "csv": str(csv_path),
223
+ "handled": len(saved), "source_label": getattr(snap, "source_label", ""),
224
+ "synthetic": rec["synthetic"], "market_path": str(market_path),
225
+ "snapshot_obj": snap, "signals": len(sigs)}
226
+
227
+
228
+ # ---------------------------------------------------------------- لاگ روزانه
229
+ def append_log(rec: dict, path: Path | str | None = None) -> Path:
230
+ """هر اجرا یک خط؛ مسیر پیش‌فرض در لحظهٔ اجرا خوانده می‌شود تا آزمون‌پذیر باشد."""
231
+ path = Path(path or LOG_FILE)
232
+ path.parent.mkdir(parents=True, exist_ok=True)
233
+ with path.open("a", encoding="utf-8") as f:
234
+ f.write(json.dumps(rec, ensure_ascii=False) + "\n")
235
+ return path
236
+
237
+
238
+ def read_log(path: Path | str | None = None) -> list[dict]:
239
+ path = Path(path or LOG_FILE)
240
+ if not path.exists():
241
+ return []
242
+ out = []
243
+ for line in path.read_text(encoding="utf-8").splitlines():
244
+ line = line.strip()
245
+ if not line:
246
+ continue
247
+ try:
248
+ out.append(json.loads(line))
249
+ except Exception:
250
+ continue
251
+ return out
252
+
253
+
254
+ # ---------------------------------------------------------------- کارنامه
255
+ def scorecard(t=None, *, log_records=None, log_path=None, target_days: int = 10,
256
+ target_real_days: int = 5, min_marked_ratio: float = 0.6, min_moves: int = 3) -> dict:
257
+ """آیا سابقهٔ ثبت‌شده به‌قدر کافی هست؟ پنج شرط، همه با عدد، هیچ شرط سلیقه‌ای."""
258
+ t = t or trial.Trial()
259
+ summary = t.summary()
260
+ log_records = read_log(log_path) if log_records is None else log_records
261
+ days = sorted({r.get("date") for r in log_records if r.get("date") and r.get("chain_ok", True)})
262
+ real_days = sorted({r["date"] for r in log_records
263
+ if r.get("date") and not r.get("synthetic", True)})
264
+ marks = t.latest_marks()
265
+ deltas = [m["delta_pp"] for m in marks.values() if isinstance(m.get("delta_pp"), (int, float))]
266
+ moved = [d for d in deltas if abs(d) >= 1.0]
267
+ up = [d for d in deltas if d >= 1.0]
268
+ down = [d for d in deltas if d <= -1.0]
269
+ entries = summary.get("entries", 0)
270
+ marked = summary.get("marked", 0)
271
+ marked_ratio = (marked / entries) if entries else 0.0
272
+
273
+ criteria = [
274
+ {"key": "days", "name": "تداوم روزانه (روزهای ثبت‌شده)",
275
+ "have": len(days), "want": target_days, "ok": len(days) >= target_days,
276
+ "hint": "هر روز کاری یک بار «مراسم امروز» را اجرا کنید."},
277
+ {"key": "real_days", "name": "روزهای با دادهٔ واقعی (نه ساختگی)",
278
+ "have": len(real_days), "want": target_real_days, "ok": len(real_days) >= target_real_days,
279
+ "hint": "خوراک آزمایشی برای تمرین است؛ برای ارائه به شرکت روزهای واقعی لازم است."},
280
+ {"key": "marked", "name": "سهم بازسنجی‌شدهٔ دفتر",
281
+ "have": round(marked_ratio, 3), "want": min_marked_ratio, "ok": marked_ratio >= min_marked_ratio,
282
+ "hint": "بازسنجی نشان می‌دهد موتور با قیمت‌های تازه هم اجرا می‌شود."},
283
+ {"key": "moves", "name": "حرکت واقعی در دفتر (بازتر و بسته)",
284
+ "have": {"moved": len(moved), "up": len(up), "down": len(down)},
285
+ "want": {"moved": min_moves, "up": 1, "down": 1},
286
+ "ok": len(moved) >= min_moves and len(up) >= 1 and len(down) >= 1,
287
+ "hint": "هم فرصت تازه لازم است، هم فرصتی که بسته شده؛ هر دو نشانهٔ درست‌کاری است."},
288
+ {"key": "chain", "name": "زنجیرهٔ هش سالم",
289
+ "have": bool(summary.get("chain_ok")), "want": True, "ok": bool(summary.get("chain_ok")),
290
+ "hint": "اگر زنجیره بشکند، یعنی ردیفی دست‌کاری شده؛ تا پیدا نشود به دفتر استناد نکنید."},
291
+ ]
292
+ ready = all(c["ok"] for c in criteria)
293
+ missing = [c for c in criteria if not c["ok"]]
294
+ if ready:
295
+ verdict = ("آماده: سابقهٔ ثبت‌شده کافی است. حالا خرید دادهٔ زنده و بردن گزارش دفتر به شرکت معنی دارد.")
296
+ else:
297
+ verdict = ("هنوز نه: " + " · ".join(
298
+ f"{c['name']} ({c['have']} از {c['want']})" for c in missing[:2]) +
299
+ " — بعد از انجام، همین دکمه را دوباره بزنید.")
300
+ return {"ready": ready, "criteria": criteria, "verdict": verdict,
301
+ "days": len(days), "real_days": len(real_days),
302
+ "moved": len(moved), "up": len(up), "down": len(down),
303
+ "marked_ratio": round(marked_ratio, 3), "entries": entries, "marked": marked,
304
+ "last_run": (log_records[-1].get("ts") if log_records else None),
305
+ "runs": len(log_records)}
306
+
307
+
308
+ def status_text(score: dict) -> str:
309
+ lines = ["کارنامهٔ آزمون دو هفته‌ای:"]
310
+ for c in score["criteria"]:
311
+ mark = "✓" if c["ok"] else "✗"
312
+ lines.append(f" {mark} {c['name']}: {c['have']} (لازم: {c['want']}) — {c['hint']}")
313
+ lines.append(" " + ("آماده" if score["ready"] else "ناتمام"))
314
+ lines.append(" " + score["verdict"])
315
+ return "\n".join(lines)
316
+
317
+
318
+ def main(argv: list[str] | None = None) -> int:
319
+ ap = argparse.ArgumentParser(description="مراسم روزانهٔ آزمون زندهٔ ایستگاه")
320
+ ap.add_argument("--mode", default="auto", choices=("auto", "live", "file", "sim"))
321
+ ap.add_argument("--file", dest="file_path", help="پروندهٔ اسنپ‌شات دستی")
322
+ ap.add_argument("--note", default="", help="یادداشت امروز")
323
+ ap.add_argument("--status", action="store_true", help="فقط کارنامه را نشان بده")
324
+ ap.add_argument("--report", action="store_true", help="فقط گزارش سرمایه‌گذار را بساز")
325
+ ap.add_argument("--add-span", type=float, default=0.0, help="کاهش/افزایش انتظار (واحد درصد)")
326
+ ap.add_argument("--version", action="store_true")
327
+ ap.add_argument("--reset", action="store_true",
328
+ help="پاک‌کردن دفتر و لاگ برای شروع دوباره (نیازمند --yes)")
329
+ ap.add_argument("--yes", action="store_true", help="تأیید پاک‌کردن")
330
+ args = ap.parse_args(argv)
331
+ if args.version:
332
+ print(f"daily-trial {VERSION}")
333
+ return 0
334
+ if args.reset:
335
+ if not args.yes:
336
+ print("برای پاک‌کردن دفتر، این را با --yes اجرا کنید: python daily_trial.py --reset --yes")
337
+ return 1
338
+ removed = []
339
+ for path in (trial.DEFAULT_DB, LOG_FILE, DATA / "trial-entries.csv", REPORT_FILE):
340
+ if Path(path).exists():
341
+ Path(path).unlink()
342
+ removed.append(Path(path).name)
343
+ print("پاک شد: " + ("، ".join(removed) or "چیزی برای پاک‌کردن نبود"))
344
+ print("یادآوری: دفتر آزمون پاک شد؛ ردیف‌های قبلی قابل بازگشت نیستند.")
345
+ return 0
346
+
347
+ if args.report:
348
+ t = trial.Trial()
349
+ print(t.write_report(REPORT_FILE))
350
+ print(t.write_csv(DATA / "trial-entries.csv"))
351
+ return 0
352
+ if args.status:
353
+ print(status_text(scorecard()))
354
+ return 0
355
+
356
+ import connections as conn
357
+ live_cfg, key = {}, ""
358
+ active = conn.active_or_none()
359
+ if active:
360
+ live_cfg, key = active["live_cfg"], active["key"]
361
+ rules_path = BASE / "config" / "daily-rules.json"
362
+ rules = DEFAULT_RULES
363
+ if rules_path.exists():
364
+ try:
365
+ rules = {**DEFAULT_RULES, **json.loads(rules_path.read_text(encoding="utf-8"))}
366
+ except Exception:
367
+ rules = DEFAULT_RULES
368
+ res = run_daily(mode=args.mode, file_path=args.file_path, live_cfg=live_cfg, key=key,
369
+ rules=rules, note=args.note, add_span=args.add_span,
370
+ fallback_file=DESK_DIR / "market-demo.json", progress=lambda m: print("· " + m))
371
+ if not res["ok"]:
372
+ for e in res["errors"]:
373
+ print("خطا: " + e)
374
+ return 2
375
+ r = res["record"]
376
+ print(f"\nامروز ({r['date']}): منبع {r['source'] or '—'} · "
377
+ f"{'ساختگی' if r['synthetic'] else 'واقعی'} · ردیف {r['rows']} · ثبت {r['recorded']} · "
378
+ f"بازسنجی {r['marked']}")
379
+ print("گزارش: " + res["report"])
380
+ print()
381
+ print(status_text(res["scorecard"]))
382
+ return 0
383
+
384
+
385
+ if __name__ == "__main__":
386
+ raise SystemExit(main())
station/data/data-requirement-sheet.md ADDED
@@ -0,0 +1,28 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # برگهٔ نیاز داده (برای فرستادن به فروشنده‌ها)
2
+
3
+ سلام. برای یک سامانهٔ تصمیم‌گیری روی اوراق مشتقهٔ بورس تهران، این داده‌ها را لازم دارم.
4
+ لطفاً برای هر ردیف بنویسید: دارید یا نه، نرخ به‌روزرسانی، و قیمت ماهانه.
5
+
6
+ | داده | نرخ لازم | توضیح | دارید؟ | نرخ به‌روزرسانی | قیمت |
7
+ |---|---|---|---|---|---|
8
+ | قیمت پایه سهام و صندوق‌ها | ۱ تا ۵ دقیقه | همهٔ نمادهای بورس و فرابورس | | | |
9
+ | قیمت قراردادهای آتی | ۱ تا ۵ دقیقه | کالا و اوراق | | | |
10
+ | قیمت اعمال و پرمیوم اختیار خرید و فروش | ۱ تا ۵ دقیقه | همهٔ سررسیدها | | | |
11
+ | بهترین سفارش خرید و فروش | ۱ تا ۵ دقیقه | برای محاسبهٔ اسپرد و نقدشوندگی | | | |
12
+ | سری روزانهٔ قیمت پایانی | روزانه | تاریخچهٔ حداقل ۱۲ ماه برای پس‌آزمایی | | | |
13
+ | حجم و ارزش معاملات | روزانه | برای فیلتر نقدشوندگی | | | |
14
+ | وضعیت نماد (باز، متوقف) | روزانه | برای جلوگیری از تصمیم روی نماد بسته | | | |
15
+
16
+ ## پرسش‌های فنی
17
+
18
+ ۱. قالب دسترسی: REST یا websocket؟ مسیر JSON پاسخ به چه شکل است؟
19
+ ۲. احراز هویت: کلید در نشانی یا در هدر؟ محدودیت تعداد درخواست در دقیقه چقدر است؟
20
+ ۳. پایداری: ساعت کاری و قطعی‌های معمول؛ در صورت قطع، داده دوباره پر می‌شود؟
21
+ ۴. پرداخت: ریالی؟ فاکتور رسمی؟ دورهٔ زمانی و شرایط لغو؟
22
+ ۵. اجازهٔ استفاده: آیا استفاده در یک سامانهٔ تحلیل و تصمیم‌یار مجاز است؟
23
+
24
+ ## یادآوری برای خودم
25
+
26
+ - وجه تضمین را هیچ فروشندهٔ داده‌ای ندارد؛ از سامانهٔ کارگزاری برداشته می‌شود (۶۰ ثانیه در روز).
27
+ - تا وقتی کارنامهٔ آزمون «آماده» نشود، خرید داده معنی ندارد: اول باید ببینم موتور روزانه فرصت پیدا می‌کند.
28
+ - پیش از امضا، قالب نشانی فروشنده را در گام ۲ ایستگاه می‌گذارم و «آزمایش اتصال» می‌زنم.
station/data/history-template.csv ADDED
@@ -0,0 +1,2 @@
 
 
 
1
+ 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
2
+ 1405-05-01,اهرم,basis,20000,22800,,,,,90,20000000,900,0.005,0.39,61.0
station/data/snapshot-template.json ADDED
@@ -0,0 +1,109 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "note": "این یک قالب است، نه دادهٔ واقعی. عددهای هر ردیف را با عدد امروزِ سامانهٔ کارگزاری خودتان عوض کنید و پرونده را با نام خودتان ذخیره کنید (مثلاً daily-input.json).",
3
+ "_units": "hurdle و spread_pct کسری‌اند (0.39 یعنی ۳۹٪ و 0.005 یعنی ۰.۵٪) · capital به ریال · days = روزهای مانده تا سررسید · prices به ریال · margin_per_contract = وجه تضمین هر قرارداد (سهم در این قالب: ارزش یک سهم) · liquidity_contracts_per_day = حجم قرارداد روز",
4
+ "_fields_per_kind": {
5
+ "basis": [
6
+ "spot",
7
+ "future",
8
+ "days"
9
+ ],
10
+ "covered_call": [
11
+ "spot",
12
+ "strike",
13
+ "premium",
14
+ "days"
15
+ ],
16
+ "tabei": [
17
+ "stock_price",
18
+ "put_price",
19
+ "strike",
20
+ "days"
21
+ ],
22
+ "box": [
23
+ "call_low",
24
+ "put_low",
25
+ "call_high",
26
+ "put_high",
27
+ "strike_low",
28
+ "strike_high",
29
+ "days"
30
+ ],
31
+ "parity": [
32
+ "call",
33
+ "put",
34
+ "spot",
35
+ "strike",
36
+ "days"
37
+ ]
38
+ },
39
+ "as_of": "تاریخ امروز",
40
+ "hurdle": 0.39,
41
+ "capital": 20000000000,
42
+ "rows": [
43
+ {
44
+ "symbol": "اهرم",
45
+ "kind": "basis",
46
+ "spot": 20000,
47
+ "future": 22800,
48
+ "days": 90,
49
+ "storage_annual": 0.0,
50
+ "margin_per_contract": 20000000,
51
+ "unit": "قرارداد",
52
+ "liquidity_contracts_per_day": 900,
53
+ "spread_pct": 0.005
54
+ },
55
+ {
56
+ "symbol": "فولاد",
57
+ "kind": "covered_call",
58
+ "spot": 7000,
59
+ "strike": 7600,
60
+ "premium": 400,
61
+ "days": 45,
62
+ "margin_per_contract": 7000,
63
+ "unit": "سهم",
64
+ "liquidity_contracts_per_day": 160,
65
+ "spread_pct": 0.018
66
+ },
67
+ {
68
+ "symbol": "کگل",
69
+ "kind": "tabei",
70
+ "stock_price": 9800,
71
+ "put_price": 40,
72
+ "strike": 14210,
73
+ "days": 365,
74
+ "margin_per_contract": 9840,
75
+ "unit": "سهم",
76
+ "liquidity_contracts_per_day": 240,
77
+ "spread_pct": 0.02
78
+ },
79
+ {
80
+ "symbol": "شپنا",
81
+ "kind": "box",
82
+ "call_low": 300,
83
+ "put_low": 430,
84
+ "call_high": 175,
85
+ "put_high": 585,
86
+ "strike_low": 1200,
87
+ "strike_high": 1500,
88
+ "days": 45,
89
+ "margin_per_contract": 250000,
90
+ "unit": "قرارداد",
91
+ "liquidity_contracts_per_day": 12,
92
+ "spread_pct": 0.045
93
+ },
94
+ {
95
+ "symbol": "وبملت",
96
+ "kind": "parity",
97
+ "call": 420,
98
+ "put": 380,
99
+ "spot": 9000,
100
+ "strike": 9000,
101
+ "days": 30,
102
+ "rate": 0.39,
103
+ "margin_per_contract": 9000,
104
+ "unit": "سهم",
105
+ "liquidity_contracts_per_day": 80,
106
+ "spread_pct": 0.02
107
+ }
108
+ ]
109
+ }
station/data_sources.py ADDED
@@ -0,0 +1,554 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env python3
2
+ # -*- coding: utf-8 -*-
3
+ """امکان‌سنجی مسیرهای داده، پیش از خرید: کدام روش واقعاً به کار ایستگاه می‌خورد؟
4
+
5
+ سه روشی که صاحب پرونده نام برد، این‌جا سنجیده می‌شوند:
6
+ ۱. خرید وب‌سرویس رسمی (pull، نیازمند کلید و پول)
7
+ ۲. سرویس‌های رایگان سایت مرجع (pull، بی‌تعهد، احتمال گپ زمانی)
8
+ ۳. پوش لحظه‌ای (websocket / RLC) از کارگزاری یا سازمان بورس
9
+
10
+ این ابزار «تبلیغ» نمی‌کند؛ فقط می‌سنجد و می‌گوید:
11
+ • کدام نشانی جواب می‌دهد و چقدر طول می‌کشد،
12
+ • کدام میدان دادهٔ ایستگاه از آن درمی‌آید و کدام درنمی‌آید،
13
+ • دو فراخوانی پشت‌سرهم چه می‌گویند (تازه می‌شود یا همان عدد می‌مانَد)،
14
+ • و پوش لحظه‌ای اصلاً دسترسی‌پذیر است یا نه.
15
+
16
+ اجرا:
17
+ python data_sources.py --all --symbol فولاد
18
+ python data_sources.py --ws wss://example.ir/market
19
+ python data_sources.py --fixture (نمایش شکل خروجی با دادهٔ ساختگی محلی)
20
+ python data_sources.py --sheet (برگهٔ نیاز داده برای فرستادن به فروشنده)
21
+ """
22
+ from __future__ import annotations
23
+
24
+ import argparse
25
+ import json
26
+ import random
27
+ import socket
28
+ import ssl
29
+ import sys
30
+ import threading
31
+ import time
32
+ from datetime import datetime, timezone
33
+ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
34
+ from pathlib import Path
35
+ from urllib.parse import urlparse, parse_qs
36
+
37
+ VERSION = "0.1.0"
38
+ BASE = Path(__file__).resolve().parent
39
+ DATA = BASE / "data"
40
+ TSETMC_HOST = "https://cdn.tsetmc.com"
41
+
42
+ for p in (str(BASE),):
43
+ if p not in sys.path:
44
+ sys.path.insert(0, p)
45
+
46
+ import datafeed # noqa: E402
47
+ import reportkit as rk # noqa: E402
48
+
49
+ # ---------------------------------------------------------------- نقشهٔ نقاط پایانی
50
+ ENDPOINTS: list[dict] = [
51
+ {"name": "symbol_search", "label": "جست‌وجوی نماد و گرفتن کد نماد",
52
+ "url": TSETMC_HOST + "/api/Instrument/GetInstrumentSearch/{symbol}",
53
+ "needs": "symbol", "gives": "کد نماد (insCode) برای بقیهٔ فراخوانی‌ها، نام کامل، بازار",
54
+ "paths": ["instrumentSearch.0.insCode", "instrumentSearch.0.lVal18AFC", "instrumentSearch.0.market"],
55
+ "dynamic": False},
56
+ {"name": "price_info", "label": "اطلاعات قیمت یک نماد",
57
+ "url": TSETMC_HOST + "/api/ClosingPrice/GetClosingPriceInfo/{code}",
58
+ "needs": "code", "gives": "آخرین قیمت، دامنهٔ مجاز، قیمت پایانی",
59
+ "paths": ["closingPriceInfo.pDrCotVal", "closingPriceInfo.priceMin", "closingPriceInfo.priceMax",
60
+ "closingPriceInfo.pClosing"]},
61
+ {"name": "closing_daily", "label": "قیمت پایانی روزانه (سری زمانی)",
62
+ "url": TSETMC_HOST + "/api/ClosingPrice/GetClosingPriceDailyList/{code}/0",
63
+ "needs": "code", "gives": "تاریخچهٔ قیمت پایانی، حجم و ارزش معاملات (لازم برای پس‌آزمایی)",
64
+ "paths": ["closingPriceDaily.0.pClosing", "closingPriceDaily.0.pDrCotVal",
65
+ "closingPriceDaily.0.vol", "closingPriceDaily.0.qTotTran5J"]},
66
+ {"name": "best_limits", "label": "بهترین سفارش‌های خرید و فروش",
67
+ "url": TSETMC_HOST + "/api/BestLimits/{code}",
68
+ "needs": "code", "gives": "بهترین خرید/فروش و حجمشان (برای محاسبهٔ اسپرد و نقدشوندگی)",
69
+ "paths": ["bestLimits.0.pMeDemand", "bestLimits.0.pMeOffer"]},
70
+ {"name": "market_watch", "label": "تابلوی کل بازار",
71
+ "url": TSETMC_HOST + "/api/ClosingPrice/GetMarketWatch",
72
+ "needs": "", "gives": "قیمت آخرین معاملهٔ همهٔ نمادها در یک درخواست",
73
+ "paths": ["marketwatchData.0.pDrCotVal", "marketwatchData.0.lVal18AFC"]},
74
+ {"name": "client_type", "label": "خریدار و فروشندهٔ حقیقی و حقوقی",
75
+ "url": TSETMC_HOST + "/api/ClientType/GetClientTypeHistory/{code}",
76
+ "needs": "code", "gives": "ترکیب حقیقی/حقوقی (برای تحلیل جریان پول، اختیاری)",
77
+ "paths": ["clientType.0.buy_I_Volume", "clientType.0.sell_I_Volume"]},
78
+ ]
79
+
80
+ # نیازهای خودِ ایستگاه، برای داوری روش‌ها
81
+ NEEDS: list[dict] = [
82
+ {"field": "قیمت پایه سهم یا صندوق", "freq": "هر ۱ تا ۵ دقیقه", "route": "pull (رایگان یا پولی)"},
83
+ {"field": "قیمت آتی", "freq": "هر ۱ تا ۵ دقیقه", "route": "pull؛ در سرویس‌های رایگان باید جدا تست شود"},
84
+ {"field": "قیمت اعمال و پرمیوم اختیار", "freq": "هر ۱ تا ۵ دقیقه", "route": "pull؛ پوشش کامل تضمین‌شده نیست"},
85
+ {"field": "نقدشوندگی و اسپرد", "freq": "هر ۱ تا ۵ دقیقه", "route": "pull (بهترین سفارش‌ها)"},
86
+ {"field": "روز تا سررسید", "freq": "روزانه", "route": "محاسبهٔ خودمان از تقویم"},
87
+ {"field": "وجه تضمین هر قرارداد", "freq": "روزانه (اعلامی)", "route": "فقط سامانهٔ کارگزاری، نه سرویس داده"},
88
+ {"field": "تاریخ قیمت برای پس‌آزمایی", "freq": "گذشته", "route": "سری روزانه؛ در سرویس رایگان کوتاه است"},
89
+ ]
90
+
91
+
92
+ # ---------------------------------------------------------------- سنجش pull
93
+ def _top_keys(payload) -> list[str]:
94
+ if isinstance(payload, dict):
95
+ return list(payload.keys())[:8]
96
+ if isinstance(payload, list):
97
+ return [f"list[{len(payload)}]"]
98
+ return [type(payload).__name__]
99
+
100
+
101
+ def probe_endpoint(ep: dict, *, symbol: str = "", code: str = "", host: str = "",
102
+ allow_network: bool = True, timeout: float = 12.0) -> dict:
103
+ """یک نقطهٔ پایانی را می‌خواند و می‌گوید چه آمد، چقدر طول کشید، و کدام میدان‌ها درآمد."""
104
+ url = ep["url"]
105
+ if host:
106
+ url = url.replace(TSETMC_HOST, host.rstrip("/"))
107
+ if ep["needs"] == "symbol":
108
+ if not symbol:
109
+ return _fail(ep, "نام نماد داده نشده است.")
110
+ url = url.replace("{symbol}", rk_quote(symbol))
111
+ elif ep["needs"] == "code":
112
+ if not code:
113
+ return _fail(ep, "کد نماد (insCode) نداریم؛ اول جست‌وجوی نماد باید موفق شود.")
114
+ url = url.replace("{code}", str(code))
115
+ if not allow_network:
116
+ return _fail(ep, "شبکه خاموش است؛ سنجش انجام نشد.", url=url)
117
+
118
+ started = time.time()
119
+ text, status = datafeed.fetch(url, timeout=timeout, retries=0, cache_name=None, cache_seconds=0,
120
+ stale_ok=False)
121
+ latency = int((time.time() - started) * 1000)
122
+ if not text:
123
+ return _fail(ep, f"پاسخی نیامد ({status})", url=url, latency_ms=latency)
124
+ try:
125
+ payload = json.loads(text)
126
+ except Exception:
127
+ return _fail(ep, "پاسخ JSON نبود (شاید صفحهٔ HTML باشد)", url=url, latency_ms=latency,
128
+ bytes=len(text))
129
+ found: list[dict] = []
130
+ for path in ep["paths"]:
131
+ value = datafeed.dig(payload, path)
132
+ if value is not None:
133
+ found.append({"path": path, "value": value if isinstance(value, (int, float, str)) else str(value)})
134
+ primary = next((f["value"] for f in found
135
+ if isinstance(f["value"], (int, float)) and not isinstance(f["value"], bool)), None)
136
+ if primary is None:
137
+ primary = none_primary(payload)
138
+ return {"name": ep["name"], "label": ep["label"], "ok": bool(found),
139
+ "url": url, "http": status, "latency_ms": latency, "bytes": len(text),
140
+ "top_keys": _top_keys(payload), "fields": found, "count": len(found),
141
+ "primary": primary, "reason": "پاسخ سالم آمد" if found else
142
+ "پاسخ آمد ولی هیچ‌یک از میدان‌های موردنیاز پیدا نشد؛ ساختار عوض شده است",
143
+ "gives": ep["gives"]}
144
+
145
+
146
+ def none_primary(payload) -> float | None:
147
+ """یک عدد کلیدی برای مقایسهٔ دو فراخوانی (اولین عدد معنادار در پاسخ)."""
148
+ for path, value in datafeed.numeric_paths(payload, max_items=6):
149
+ if isinstance(value, (int, float)) and value not in (0, 1):
150
+ return float(value)
151
+ return None
152
+
153
+
154
+ def _fail(ep: dict, reason: str, *, url: str = "", latency_ms: int = 0, bytes: int = 0) -> dict:
155
+ return {"name": ep["name"], "label": ep["label"], "ok": False, "url": url or ep["url"],
156
+ "http": "", "latency_ms": latency_ms, "bytes": bytes, "top_keys": [], "fields": [],
157
+ "count": 0, "primary": None, "reason": reason, "gives": ep["gives"]}
158
+
159
+
160
+ def stability_check(ep: dict, *, symbol: str = "", code: str = "", host: str = "",
161
+ wait: float = 2.0, timeout: float = 12.0) -> dict:
162
+ """دو فراخوانی پشت‌سرهم: داده تازه می‌شود یا همان عدد می‌مانَد؟
163
+
164
+ این همان «گپ زمانی» است که خودتان اشاره کردید: سرویس رایگان ممکن است بی‌حرکت باشد.
165
+ """
166
+ if not ep.get("dynamic", True):
167
+ return {"name": ep["name"], "checked": False,
168
+ "reason": "این نشانی قیمت نیست؛ سنجش تازگی برایش معنا ندارد."}
169
+ first = probe_endpoint(ep, symbol=symbol, code=code, host=host, timeout=timeout)
170
+ if not first["ok"]:
171
+ return {"name": ep["name"], "checked": False, "reason": first["reason"]}
172
+ time.sleep(max(0.2, wait))
173
+ second = probe_endpoint(ep, symbol=symbol, code=code, host=host, timeout=timeout)
174
+ a, b = first.get("primary"), second.get("primary")
175
+ if a is None or b is None:
176
+ verdict, note = "نامعلوم", "عدد کلیدی برای مقایسه پیدا نشد."
177
+ elif a == b:
178
+ verdict = "بی‌حرکت"
179
+ note = "دو فراخوانی با فاصلهٔ چند ثانیه همان عدد را دادند؛ یعنی نرخ به‌روزرسانی این نشانی کند است."
180
+ else:
181
+ verdict = "تازه‌شونده"
182
+ note = "عدد بین دو فراخوانی عوض شد؛ این نشانی زنده است."
183
+ return {"name": ep["name"], "checked": True, "verdict": verdict, "note": note,
184
+ "first": a, "second": b, "latency_ms": first["latency_ms"]}
185
+
186
+
187
+ def probe_all(*, symbol: str = "فولاد", code: str = "", host: str = "", allow_network: bool = True,
188
+ timeout: float = 12.0, with_stability: bool = True) -> dict:
189
+ """همهٔ نقاط پایانی رایگان را می‌سنجد و کد نماد را هم در صورت نیاز درمی‌آورد."""
190
+ items = []
191
+ resolved = code
192
+ search = next(e for e in ENDPOINTS if e["name"] == "symbol_search")
193
+ search_res = probe_endpoint(search, symbol=symbol, host=host, allow_network=allow_network, timeout=timeout)
194
+ items.append(search_res)
195
+ if not resolved and search_res["ok"]:
196
+ for f in search_res["fields"]:
197
+ if f["path"].endswith("insCode") and str(f["value"]).strip():
198
+ resolved = str(f["value"]).strip()
199
+ break
200
+ for ep in ENDPOINTS:
201
+ if ep["name"] == "symbol_search":
202
+ continue
203
+ items.append(probe_endpoint(ep, symbol=symbol, code=resolved, host=host,
204
+ allow_network=allow_network, timeout=timeout))
205
+ stability = []
206
+ if with_stability and allow_network:
207
+ for ep in ENDPOINTS:
208
+ if ep["needs"] == "code" and not resolved:
209
+ continue
210
+ stability.append(stability_check(ep, symbol=symbol, code=resolved, host=host, timeout=timeout))
211
+ ok_count = len([1 for i in items if i["ok"]])
212
+ return {"ran_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
213
+ "symbol": symbol, "code": resolved, "host": host or TSETMC_HOST,
214
+ "items": items, "stability": stability,
215
+ "summary": {"total": len(items), "ok": ok_count, "failed": len(items) - ok_count,
216
+ "usable_for_engine": ok_count >= 3},
217
+ "verdict": (f"{ok_count} از {len(items)} نشانی جواب داد. "
218
+ + ("برای شروع کافی است؛ وجه تضمین را همچنان از کارگزاری بردارید."
219
+ if ok_count >= 3 else
220
+ "از این محیط به سامانه‌های ایرانی دسترسی نبود یا ساختار عوض شده؛ "
221
+ "همین آزمون را روی رایانهٔ خودتان (داخل ایران) اجرا کنید."))}
222
+
223
+
224
+ def rk_quote(value: str) -> str:
225
+ from urllib.parse import quote
226
+ return quote(str(value))
227
+
228
+
229
+ # ---------------------------------------------------------------- سنجش پوش لحظه‌ای
230
+ WS_VERDICTS = {
231
+ 101: "قابل اتصال و ارتقا؛ اگر توکن داشته باشید، پیام‌ها هم می‌آیند.",
232
+ 400: "دسترسی هست ولی درخواست ناقص است (احتمالاً پارامتر یا توکن لازم دارد).",
233
+ 401: "سرویس هست ولی احراز هویت می‌خواهد؛ بی توکن راه نمی‌دهد.",
234
+ 403: "سرویس هست ولی اجازه نمی‌دهد (دسترسی شما مجاز نیست).",
235
+ 404: "نشانی یا مسیر اشتباه است.",
236
+ 426: "ارتقا لازم است ولی سرور شرایطش را نپذیرفت.",
237
+ }
238
+
239
+
240
+ def probe_ws(url: str, *, timeout: float = 8.0, extra_headers: str = "") -> dict:
241
+ """آیا اصلاً می‌شود به پوش لحظه‌ای وصل شد؟ (TCP + TLS + تلاش ارتقای HTTP)
242
+
243
+ این آزمون نمی‌گوید «داده می‌آید»؛ می‌گوید «سرویس هست یا نه و چه می‌خواهد».
244
+ برای خواندن پیام‌ها، توکن و مجوز کارگزاری لازم است.
245
+ """
246
+ parsed = urlparse(url)
247
+ if parsed.scheme not in ("ws", "wss") or not parsed.hostname:
248
+ return {"url": url, "ok": False, "tcp": False, "tls": False, "status": None,
249
+ "verdict": "نشانی نامعتبر", "note": "نشانی باید با ws:// یا wss:// شروع شود."}
250
+ port = parsed.port or (443 if parsed.scheme == "wss" else 80)
251
+ path = parsed.path or "/"
252
+ if parsed.query:
253
+ path += "?" + parsed.query
254
+ out = {"url": url, "ok": False, "tcp": False, "tls": False, "status": None,
255
+ "verdict": "", "note": "", "host": parsed.hostname, "port": port}
256
+ started = time.time()
257
+ try:
258
+ sock = socket.create_connection((parsed.hostname, port), timeout=timeout)
259
+ out["tcp"] = True
260
+ except OSError as e:
261
+ out["verdict"] = "دسترس نیست"
262
+ out["note"] = f"اتصال TCP ممکن نشد: {type(e).__name__} ({e})"
263
+ out["latency_ms"] = int((time.time() - started) * 1000)
264
+ return out
265
+ try:
266
+ if parsed.scheme == "wss":
267
+ ctx = ssl.create_default_context()
268
+ sock = ctx.wrap_socket(sock, server_hostname=parsed.hostname)
269
+ out["tls"] = True
270
+ key = "dGhlIHNhbXBsZSBub25jZQ=="
271
+ headers = [f"GET {path} HTTP/1.1", f"Host: {parsed.hostname}",
272
+ "Upgrade: websocket", "Connection: Upgrade",
273
+ f"Sec-WebSocket-Key: {key}", "Sec-WebSocket-Version: 13"]
274
+ for line in [x for x in extra_headers.split(";") if x.strip()]:
275
+ headers.append(line.strip())
276
+ sock.sendall(("\r\n".join(headers) + "\r\n\r\n").encode("utf-8"))
277
+ sock.settimeout(timeout)
278
+ raw = sock.recv(4096).decode("utf-8", errors="replace")
279
+ first_line = raw.splitlines()[0] if raw else ""
280
+ code = None
281
+ parts = first_line.split()
282
+ if len(parts) >= 2 and parts[1].isdigit():
283
+ code = int(parts[1])
284
+ out["status"] = code
285
+ out["ok"] = code == 101
286
+ out["verdict"] = WS_VERDICTS.get(code, f"پاسخ {code or 'ناشناخته'} از سرور")
287
+ out["note"] = ("پاسخ سرور: " + first_line) if first_line else "سرور چیزی برنگرداند."
288
+ out["response_preview"] = raw[:300]
289
+ except (ssl.SSLError, OSError, socket.timeout) as e:
290
+ out["verdict"] = "دسترسی شبکه‌ای ناتمام"
291
+ out["note"] = f"{type(e).__name__}: {e}"
292
+ finally:
293
+ try:
294
+ sock.close()
295
+ except OSError:
296
+ pass
297
+ out["latency_ms"] = int((time.time() - started) * 1000)
298
+ return out
299
+
300
+
301
+ def real_ws_read(url: str, *, token: str = "", seconds: float = 5.0) -> dict:
302
+ """اگر کتابخانهٔ websocket-client نصب باشد، واقعاً پیام می‌خواند؛ وگرنه صریح می‌گوید نبود."""
303
+ try:
304
+ import websocket # type: ignore
305
+ except ImportError:
306
+ return {"ok": False, "reason": "کتابخانهٔ websocket-client نصب نیست. برای خواندن واقعی پیام‌ها: "
307
+ "pip install websocket-client"}
308
+ header = [f"Authorization: Bearer {token}"] if token else []
309
+ try:
310
+ ws = websocket.create_connection(url, timeout=seconds, header=header)
311
+ ws.settimeout(seconds)
312
+ msg = ws.recv()
313
+ ws.close()
314
+ return {"ok": True, "first_message": str(msg)[:400]}
315
+ except Exception as e: # پیام روشن، بی استثنای خام
316
+ return {"ok": False, "reason": f"{type(e).__name__}: {e}"}
317
+
318
+
319
+ # ---------------------------------------------------------------- سرور نمونه (برای نمایش شکل خروجی)
320
+ FIXTURE_DATA = {
321
+ "instrumentSearch": [{"insCode": "46348559193224090", "lVal18AFC": "فولاد", "market": 1}],
322
+ "closingPriceInfo": {"pDrCotVal": 7015, "priceMin": 6650, "priceMax": 7350, "pClosing": 7015},
323
+ "closingPriceDaily": [{"pClosing": 7015, "pDrCotVal": 7015, "vol": 124500000, "qTotTran5J": 8720}],
324
+ "bestLimits": [{"pMeDemand": 7010, "pMeOffer": 7020}],
325
+ "marketwatchData": [{"lVal18AFC": "فولاد", "pDrCotVal": 7015}],
326
+ "clientType": [{"buy_I_Volume": 51230000, "sell_I_Volume": 40110000}],
327
+ }
328
+
329
+
330
+ class FixtureHandler(BaseHTTPRequestHandler):
331
+ """سرور نمونهٔ محلی با همان ساختار نشانی‌های واقعی (داده ساختگی است)."""
332
+
333
+ protocol_version = "HTTP/1.1"
334
+ hits = 0
335
+
336
+ def log_message(self, fmt, *args):
337
+ pass
338
+
339
+ def do_GET(self):
340
+ u = urlparse(self.path)
341
+ type(self).hits += 1
342
+ payload = json.loads(json.dumps(FIXTURE_DATA)) # رونوشت تازه
343
+ # هر فراخوانی، قیمت‌ها را کمی جابه‌جا می‌کند تا «بی‌حرکت» به‌نظر نرسد
344
+ jitter = random.Random(type(self).hits).uniform(-0.004, 0.004)
345
+ info = payload["closingPriceInfo"]
346
+ for key in ("pDrCotVal", "pClosing", "priceMin", "priceMax"):
347
+ info[key] = round(float(info[key]) * (1 + jitter), 2)
348
+ payload["closingPriceDaily"][0]["pDrCotVal"] = round(
349
+ 7015 * (1 + jitter), 2)
350
+ payload["closingPriceDaily"][0]["pClosing"] = round(7015 * (1 + jitter), 2)
351
+ payload["bestLimits"][0]["pMeDemand"] = round(7010 * (1 + jitter), 2)
352
+ payload["bestLimits"][0]["pMeOffer"] = round(7020 * (1 + jitter), 2)
353
+ payload["marketwatchData"][0]["pDrCotVal"] = round(7015 * (1 + jitter), 2)
354
+ body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
355
+ self.send_response(200)
356
+ self.send_header("Content-Type", "application/json; charset=utf-8")
357
+ self.send_header("Content-Length", str(len(body)))
358
+ self.send_header("X-Fixture", "synthetic")
359
+ self.end_headers()
360
+ self.wfile.write(body)
361
+
362
+
363
+ def start_fixture(port: int = 0) -> tuple[ThreadingHTTPServer, str]:
364
+ """سرور نمونه را روی یک درگاه آزاد بالا می‌آورد و نشانی‌اش را برمی‌گرداند."""
365
+ httpd = ThreadingHTTPServer(("127.0.0.1", port), FixtureHandler)
366
+ thread = threading.Thread(target=httpd.serve_forever, daemon=True)
367
+ thread.start()
368
+ return httpd, f"http://127.0.0.1:{httpd.server_address[1]}"
369
+
370
+
371
+ # ---------------------------------------------------------------- خروجی‌ها
372
+ def build_matrix() -> list[dict]:
373
+ """داوری سه مسیر در برابر نیاز ایستگاه."""
374
+ return [
375
+ {"route": "۱. خرید وب‌سرویس رسمی (pull)",
376
+ "gives": "قیمت زنده و تاریخچهٔ کامل، قرارداد و فاکتور",
377
+ "misses": "وجه تضمین، و «تصمیم»",
378
+ "cost": "بالا (استعلام لازم است)",
379
+ "verdict": "فعلاً نه: پول جلوتر از شاهد. اگر خریدار شرکت باشد و فاکتور رسمی لازم داشته باشد، بله.",
380
+ "test": "پس از گرفتن کلید: قالب نشانی را در گام ۲ بگذارید و «آزمایش اتصال» بزنید."},
381
+ {"route": "۲. سرویس‌های عمومی سایت مرجع (pull)",
382
+ "gives": "قیمت پایه، بخشی از آتی و اختیار، بهترین سفارش‌ها، سری روزانه",
383
+ "misses": "وجه تضمین؛ ضمانت ندارد و ممکن است گپ زمانی داشته باشد",
384
+ "cost": "صفر",
385
+ "verdict": "بله، همین امروز: کافی است. فقط گپ و بی‌حرکتی را با همین ابزار بسنجید.",
386
+ "test": "«سنجش نقاط پایانی» + «سنجش دوفراخوانی» در همین صفحه."},
387
+ {"route": "۳. پوش لحظه‌ای (websocket / RLC)",
388
+ "gives": "جریان لحظه‌ای، اگر کارگزاری یا سازمان دسترسی بدهد",
389
+ "misses": "برای افراد عادی معمولاً بسته است؛ مجوز و قرارداد می‌خواهد",
390
+ "cost": "نامعلوم، وابسته به قرارداد",
391
+ "verdict": "نیاز نداریم: افق تصمیم این راهبردها دقیقه‌ای است، نه میلی‌ثانیه‌ای.",
392
+ "test": "«سنجش پوش لحظه‌ای»: اول ببینید سرویس هست یا نه، بعد سراغ مجوز بروید."},
393
+ ]
394
+
395
+
396
+ def requirement_sheet() -> str:
397
+ """برگهٔ نیاز داده، برای فرستادن به فروشنده‌ها و گرفتن استعلام قیمت."""
398
+ lines = ["# برگهٔ نیاز داده (برای فرستادن به فروشنده‌ها)",
399
+ "",
400
+ "سلام. برای یک سامانهٔ تصمیم‌گیری روی اوراق مشتقهٔ بورس تهران، این داده‌ها را لازم دارم.",
401
+ "لطفاً برای هر ردیف بنویسید: دارید یا نه، نرخ به‌روزرسانی، و قیمت ماهانه.",
402
+ "",
403
+ "| داده | نرخ لازم | توضیح | دارید؟ | نرخ به‌روزرسانی | قیمت |",
404
+ "|---|---|---|---|---|---|",
405
+ "| قیمت پایه سهام و صندوق‌ها | ۱ تا ۵ دقیقه | همهٔ نمادهای بورس و فرابورس | | | |",
406
+ "| قیمت قراردادهای آتی | ۱ تا ۵ دقیقه | کالا و اوراق | | | |",
407
+ "| قیمت اعمال و پرمیوم اختیار خرید و فروش | ۱ تا ۵ دقیقه | همهٔ سررسیدها | | | |",
408
+ "| بهترین سفارش خرید و فروش | ۱ تا ۵ دقیقه | برای محاسبهٔ اسپرد و نقدشوندگی | | | |",
409
+ "| سری روزانهٔ قیمت پایانی | روزانه | تاریخچهٔ حداقل ۱۲ ماه برای پس‌آزمایی | | | |",
410
+ "| حجم و ارزش معاملات | روزانه | برای فیلتر نقدشوندگی | | | |",
411
+ "| وضعیت نماد (باز، متوقف) | روزانه | برای جلوگیری از تصمیم روی نماد بسته | | | |",
412
+ "",
413
+ "## پرسش‌های فنی",
414
+ "",
415
+ "۱. قالب دسترسی: REST یا websocket؟ مسیر JSON پاسخ به چه شکل است؟",
416
+ "۲. احراز هویت: کلید در نشانی یا در هدر؟ محدودیت تعداد درخواست در دقیقه چقدر است؟",
417
+ "۳. پایداری: ساعت کاری و قطعی‌های معمول؛ در صورت قطع، داده د��باره پر می‌شود؟",
418
+ "۴. پرداخت: ریالی؟ فاکتور رسمی؟ دورهٔ زمانی و شرایط لغو؟",
419
+ "۵. اجازهٔ استفاده: آیا استفاده در یک سامانهٔ تحلیل و تصمیم‌یار مجاز است؟",
420
+ "",
421
+ "## یادآوری برای خودم",
422
+ "",
423
+ "- وجه تضمین را هیچ فروشندهٔ داده‌ای ندارد؛ از سامانهٔ کارگزاری برداشته می‌شود (۶۰ ثانیه در روز).",
424
+ "- تا وقتی کارنامهٔ آزمون «آماده» نشود، خرید داده معنی ندارد: اول باید ببینم موتور روزانه فرصت پیدا می‌کند.",
425
+ "- پیش از امضا، قالب نشانی فروشنده را در گام ۲ ایستگاه می‌گذارم و «آزمایش اتصال» می‌زنم.",
426
+ ""]
427
+ return "\n".join(lines)
428
+
429
+
430
+ def build_report(result: dict, matrix: list[dict], ws: dict | None = None,
431
+ path: Path | None = None) -> Path:
432
+ out = Path(path or (DATA / "data-feasibility.html"))
433
+ out.parent.mkdir(parents=True, exist_ok=True)
434
+ rows = "".join(
435
+ f'<tr class="{"pass" if i["ok"] else "fail"}"><td>{rk.esc(i["label"])}</td>'
436
+ f'<td>{"✅" if i["ok"] else "✗"} {rk.esc(i["reason"])}</td>'
437
+ f'<td class="num">{rk.esc(i.get("latency_ms", 0))}</td>'
438
+ f'<td class="num">{rk.esc(i.get("http", ""))}</td>'
439
+ f'<td class="num">{rk.esc(", ".join(i.get("top_keys") or []) or "—")}</td></tr>'
440
+ for i in result["items"])
441
+ stability = "".join(
442
+ f'<tr><td>{rk.esc(s["name"])}</td><td>{rk.esc(s.get("verdict", "سنجیده نشد"))}</td>'
443
+ f'<td>{rk.esc(s.get("note", s.get("reason", "")))}</td></tr>' for s in result.get("stability", []))
444
+ mrows = "".join(
445
+ f'<tr><td>{rk.esc(m["route"])}</td><td>{rk.esc(m["gives"])}</td><td>{rk.esc(m["misses"])}</td>'
446
+ f'<td>{rk.esc(m["cost"])}</td><td>{rk.esc(m["verdict"])}</td><td class="hint">{rk.esc(m["test"])}</td></tr>'
447
+ for m in matrix)
448
+ needs = "".join(f'<tr><td>{rk.esc(n["field"])}</td><td>{rk.esc(n["freq"])}</td>'
449
+ f'<td>{rk.esc(n["route"])}</td></tr>' for n in NEEDS)
450
+ ws_block = ""
451
+ if ws:
452
+ ws_block = (f'<h2>سنجش پوش لحظه‌ای</h2><table><tbody>'
453
+ f'<tr><td>نشانی</td><td class="num">{rk.esc(ws.get("url", ""))}</td></tr>'
454
+ f'<tr><td>اتصال TCP</td><td class="num">{"بله" if ws.get("tcp") else "نه"}</td></tr>'
455
+ f'<tr><td>لایهٔ امن (TLS)</td><td class="num">{"بله" if ws.get("tls") else "نه"}</td></tr>'
456
+ f'<tr><td>کد پاسخ ارتقا</td><td class="num">{rk.esc(ws.get("status") or "—")}</td></tr>'
457
+ f'<tr><td>داوری</td><td>{rk.esc(ws.get("verdict", ""))}</td></tr>'
458
+ f'<tr><td>توضیح</td><td>{rk.esc(ws.get("note", ""))}</td></tr></tbody></table>')
459
+ body = [
460
+ '<div class="honest"><b>این سنجش چه می‌گوید و چه نمی‌گوید.</b> می‌گوید کدام نشانی جواب می‌دهد، '
461
+ 'چقدر طول می‌کشد، و کدام میدان دادهٔ موتور از آن درمی‌آید. نمی‌گوید سود می‌دهد یا نه؛ '
462
+ 'و اگر از بیرون ایران اجرا شود، نبود دسترسی به سامانه‌های ایرانی را باید صریح گزارش کند، نه اینکه '
463
+ 'آن را به‌حساب «خرابی سرویس» بگذارد.</div>',
464
+ f'<p class="sub">زمان اجرا: {rk.esc(result["ran_at"])} · نماد: {rk.esc(result["symbol"])} · '
465
+ f'کد نماد: <code>{rk.esc(result["code"] or "—")}</code> · میزبان: <code>{rk.esc(result["host"])}</code></p>',
466
+ '<h2>۱. نیاز واقعی موتور</h2>',
467
+ '<table><thead><tr><th>داده</th><th>هر چند وقت</th><th>از کدام مسیر</th></tr></thead><tbody>'
468
+ + needs + '</tbody></table>',
469
+ '<h2>۲. سنجش سرویس‌های رایگان سایت مرجع</h2>',
470
+ '<table><thead><tr><th>نقطهٔ پایانی</th><th>نتیجه</th><th class="num">میلی‌ثانیه</th>'
471
+ '<th class="num">HTTP</th><th class="num">کلیدهای پاسخ</th></tr></thead><tbody>' + rows + '</tbody></table>',
472
+ f'<p class="note">{rk.esc(result["verdict"])}</p>',
473
+ '<h2>۳. گپ زمانی: دو فراخوانی پشت‌سرهم</h2>',
474
+ '<table><thead><tr><th>نقطهٔ پایانی</th><th>داوری</th><th>توضیح</th></tr></thead><tbody>'
475
+ + stability + '</tbody></table>',
476
+ ws_block,
477
+ '<h2>۴. داوری سه مسیر</h2>',
478
+ '<table><thead><tr><th>مسیر</th><th>چه می‌دهد</th><th>چه ندارد</th><th>هزینه</th>'
479
+ '<th>داوری</th><th>آزمون</th></tr></thead><tbody>' + mrows + '</tbody></table>',
480
+ ]
481
+ if result.get("fixture"):
482
+ body.insert(1, '<div class="note"><b>توجه:</b> این اجرا روی <b>دادهٔ ساختگی محلی</b> انجام شده است '
483
+ 'تا شکل خروجی دیده شود؛ نتیجه‌اش دربارهٔ سرویس‌های واقعی چیزی نمی‌گوید.</div>')
484
+ out.write_text(rk.page("امکان‌سنجی مسیرهای داده — پیش از خرید", "".join(body),
485
+ subtitle=f"نسخهٔ {VERSION} · {len(result['items'])} نشانی سنجیده شد"),
486
+ encoding="utf-8")
487
+ return out
488
+
489
+
490
+ # ---------------------------------------------------------------- خط فرمان
491
+ def main(argv: list[str] | None = None) -> int:
492
+ ap = argparse.ArgumentParser(description=f"امکان‌سنجی مسیرهای داده — نسخه {VERSION}")
493
+ ap.add_argument("--all", action="store_true", help="سنجش همهٔ نقاط پایانی رایگان")
494
+ ap.add_argument("--symbol", default="فولاد", help="نام نماد برای سنجش")
495
+ ap.add_argument("--code", default="", help="کد نماد (insCode) اگر می‌دانید")
496
+ ap.add_argument("--host", default="", help="میزبان جایگزین (پیش‌فرض: cdn.tsetmc.com)")
497
+ ap.add_argument("--ws", default="", help="نشانی پوش لحظه‌ای برای سنجش، مثل wss://host/path")
498
+ ap.add_argument("--ws-token", default="", help="توکن پوش لحظه‌ای (اگر دارید)")
499
+ ap.add_argument("--fixture", action="store_true", help="اجرای آزمایشی روی سرور نمونهٔ محلی (دادهٔ ساختگی)")
500
+ ap.add_argument("--sheet", action="store_true", help="نوشتن برگهٔ نیاز داده برای فروشنده")
501
+ ap.add_argument("--timeout", type=float, default=12.0, help="مهلت هر درخواست (ثانیه)")
502
+ ap.add_argument("--no-stability", action="store_true", help="سنجش دو فراخوانی را انجام نده")
503
+ ap.add_argument("--json", action="store_true", help="خروجی ماشین‌خوان")
504
+ ap.add_argument("--version", action="version", version=VERSION)
505
+ args = ap.parse_args(argv)
506
+
507
+ if args.sheet:
508
+ out = DATA / "data-requirement-sheet.md"
509
+ out.parent.mkdir(parents=True, exist_ok=True)
510
+ out.write_text(requirement_sheet(), encoding="utf-8")
511
+ print("برگهٔ نیاز داده نوشته شد:", out)
512
+ return 0
513
+
514
+ httpd = None
515
+ host = args.host
516
+ fixture = bool(args.fixture)
517
+ if fixture:
518
+ httpd, host = start_fixture()
519
+ # در حالت ماشین‌خوان، این پیام نباید خروجی JSON را آلوده کند
520
+ print(f"سرور نمونهٔ محلی روی {host} بالا آمد (دادهٔ ساختگی).",
521
+ file=sys.stderr if args.json else sys.stdout)
522
+
523
+ result = probe_all(symbol=args.symbol, code=args.code, host=host, timeout=args.timeout,
524
+ with_stability=not args.no_stability)
525
+ result["fixture"] = fixture
526
+ ws = probe_ws(args.ws) if args.ws else None
527
+ if ws and not ws.get("ok") and args.ws_token:
528
+ ws["real_read"] = real_ws_read(args.ws, token=args.ws_token)
529
+ report = build_report(result, build_matrix(), ws)
530
+ if httpd:
531
+ httpd.shutdown()
532
+
533
+ if args.json:
534
+ print(json.dumps({"result": result, "ws": ws, "matrix": build_matrix()}, ensure_ascii=False, indent=2))
535
+ return 0
536
+ print(f"سنجش مسیرهای داده — نماد {result['symbol']} · کد {result['code'] or '—'}")
537
+ print("-" * 78)
538
+ for item in result["items"]:
539
+ mark = "✓" if item["ok"] else "✗"
540
+ print(f"[{mark}] {item['label']}: {item['reason']} · {item.get('latency_ms', 0)} میلی‌ثانیه"
541
+ + (f" · میدان‌های یافته: {item['count']}" if item["ok"] else ""))
542
+ for s in result.get("stability", []):
543
+ if s.get("checked"):
544
+ print(f" · دو فراخوانی {s['name']}: {s['verdict']} — {s['note']}")
545
+ print("-" * 78)
546
+ print(result["verdict"])
547
+ if ws:
548
+ print(f"پوش لحظه‌ای: {ws['verdict']} — {ws['note']}")
549
+ print("گزارش:", report)
550
+ return 0 if result["summary"]["ok"] >= 3 else 1
551
+
552
+
553
+ if __name__ == "__main__":
554
+ raise SystemExit(main())
station/datafeed.py ADDED
@@ -0,0 +1,671 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env python3
2
+ # -*- coding: utf-8 -*-
3
+ """لایهٔ دادهٔ ایستگاه — سه حالت: نمونه، فایل دستی، و دادهٔ زندهٔ واقعی.
4
+
5
+ هدف: یک ساختار یکسان (اسنپ‌شات بازار) از سه مسیر مختلف، تا بقیهٔ برنامه
6
+ (موتور ریاضی، دروازه‌های ریسک، داشبورد) هیچ‌وقت نفهمد داده از کجا آمده است.
7
+
8
+ حالت‌ها:
9
+ sim → دادهٔ نمونهٔ همراهِ برنامه (برای آموزش و نمایش بدون هیچ هزینه)
10
+ file → پروندهٔ JSON که خودتان از سامانهٔ کارگزاری یا هر منبعی پر می‌کنید
11
+ live → قیمت زندهٔ واقعی از یک وب‌سرویس؛ با «قالب نشانی» و «مسیر JSON»
12
+ که در همان صفحهٔ رابط گرافیکی تنظیم می‌شود (بدون نیاز به کدنویسی)
13
+
14
+ اصل طراحی: هیچ نشانی‌ای در کد ثابت نشده است. همهٔ نشانی‌ها قالب‌اند و در
15
+ `config.json` یا در رابط گرافیکی وارد می‌شوند؛ اگر سرویس‌دهنده نشانی‌اش را
16
+ عوض کند، فقط همان قالب را ویرایش می‌کنید.
17
+ """
18
+ from __future__ import annotations
19
+
20
+ import csv
21
+ import errno
22
+ import json
23
+ import socket
24
+ import sqlite3
25
+ import time
26
+ import urllib.error
27
+ import urllib.parse
28
+ import urllib.request
29
+ from dataclasses import dataclass, field
30
+ from datetime import datetime, timezone
31
+ from pathlib import Path
32
+
33
+ VERSION = "0.1.0"
34
+ BASE = Path(__file__).resolve().parent
35
+ DESK_DIR = (BASE.parent / "desk").resolve()
36
+ KODAL_DIR = (BASE.parent / "kodal-alert").resolve()
37
+ CACHE_DIR = BASE / "data" / "cache"
38
+
39
+ def coerce_row_numbers(row: dict) -> dict:
40
+ """عددهای رشته‌ای را به عدد تبدیل می‌کند (مثل «21,500» یا "21500").
41
+
42
+ کاربر تازه‌کار معمولاً عدد را داخل گیومه می‌گذارد؛ بدون این کار، موتور ریاضی
43
+ آن ردیف را با خطا رد می‌کند. این تابع پرونده‌های دستی را قابل‌استفاده می‌کند.
44
+ """
45
+ for k in SNAPSHOT_NUM_FIELDS:
46
+ v = row.get(k)
47
+ if isinstance(v, str):
48
+ txt = v.strip().replace(",", "").replace("٬", "")
49
+ if txt == "":
50
+ continue
51
+ try:
52
+ row[k] = float(txt)
53
+ except ValueError:
54
+ pass
55
+ return row
56
+
57
+
58
+ # ---------------------------------------------------------------- کارت راهنمای خرید داده
59
+ # هزینه‌ها «تقریبی و نیازمند تأیید در سایت فروشنده» هستند؛ هیچ عددی اینجا قطعی نیست.
60
+ SOURCE_CARDS: dict[str, dict] = {
61
+ "sim": {
62
+ "label": "دادهٔ نمونهٔ همراه برنامه (بدون هزینه)",
63
+ "cost": "رایگان",
64
+ "gives": "همهٔ فیلدها: قیمت پایه، آتی، زنجیرهٔ آپشن، تبعی، وجه تضمین",
65
+ "after": "همهٔ فیلدها را دستی وارد می‌کنید؛ سیستم کار می‌کند ولی تصمیم روی دادهٔ ساختگی است و برای شرکت قابل ارائه نیست.",
66
+ "how": "هیچ کاری لازم نیست؛ همین حالا با دکمهٔ بعد بروید.",
67
+ },
68
+ "file": {
69
+ "label": "پروندهٔ دستی JSON (بدون هزینه)",
70
+ "cost": "رایگان",
71
+ "gives": "هر فیلدی که خودتان وارد کنید",
72
+ "after": "داده به‌روز نمی‌شود؛ ستون تازگی داده زرد می‌ماند و باید هر روز پرونده را عوض کنید. برای شروع و برای راستی‌آزمایی شرکت کافی است.",
73
+ "how": "یک پروندهٔ JSON با قالب نمونه بسازید (راهنما در گام ۲) و مسیرش را بدهید.",
74
+ },
75
+ "live": {
76
+ "label": "وب‌سرویس داده (ابزار خریدنی؛ توصیهٔ من برای دادهٔ زندهٔ واقعی)",
77
+ "cost": "بسته به سرویس‌دهنده؛ معمولاً از چند صد هزار تومان در ماه شروع می‌شود — قیمت را در سایت فروشنده تأیید کنید",
78
+ "gives": "قیمت زندهٔ سهم و صندوق، ریزمعاملات، و در بعضی سرویس‌ها دادهٔ تاریخی",
79
+ "after": "قیمت پایه هر ۲۰ تا ۶۰ ثانیه خودکار به‌روز می‌شود، ستون تازگی داده سبز می‌شود، و پس‌آزمایی روی دادهٔ واقعی تاریخ ممکن می‌شود. وجه تضمین و مشخصات قرارداد همچنان دستی می‌ماند چون از سامانهٔ کارگزاری می‌آید.",
80
+ "how": "۱) از سرویس‌دهندهٔ ایرانی کلید بگیرید. ۲) در همین گام، کلید و «قالب نشانی» و «مسیر JSON» را پر کنید. ۳) دکمهٔ آزمایش اتصال.",
81
+ },
82
+ }
83
+
84
+ SNAPSHOT_TEMPLATE: dict = {
85
+ "note": ("این یک قالب است، نه دادهٔ واقعی. عددهای هر ردیف را با عدد امروزِ سامانهٔ کارگزاری "
86
+ "خودتان عوض کنید و پرونده را با نام خودتان ذخیره کنید (مثلاً daily-input.json)."),
87
+ "_units": ("hurdle و spread_pct کسری‌اند (0.39 یعنی ۳۹٪ و 0.005 یعنی ۰.۵٪) · capital به ریال · "
88
+ "days = روزهای مانده تا سررسید · prices به ریال · margin_per_contract = وجه تضمین "
89
+ "هر قرارداد (سهم در این قالب: ارزش یک سهم) · liquidity_contracts_per_day = حجم قرارداد روز"),
90
+ "_fields_per_kind": {
91
+ "basis": ["spot", "future", "days"],
92
+ "covered_call": ["spot", "strike", "premium", "days"],
93
+ "tabei": ["stock_price", "put_price", "strike", "days"],
94
+ "box": ["call_low", "put_low", "call_high", "put_high", "strike_low", "strike_high", "days"],
95
+ "parity": ["call", "put", "spot", "strike", "days"],
96
+ },
97
+ "as_of": "تاریخ امروز",
98
+ "hurdle": 0.39,
99
+ "capital": 20000000000,
100
+ "rows": [
101
+ {"symbol": "اهرم", "kind": "basis", "spot": 20000, "future": 22800, "days": 90,
102
+ "storage_annual": 0.0, "margin_per_contract": 20000000, "unit": "قرارداد",
103
+ "liquidity_contracts_per_day": 900, "spread_pct": 0.005},
104
+ {"symbol": "فولاد", "kind": "covered_call", "spot": 7000, "strike": 7600, "premium": 400,
105
+ "days": 45, "margin_per_contract": 7000, "unit": "سهم",
106
+ "liquidity_contracts_per_day": 160, "spread_pct": 0.018},
107
+ {"symbol": "کگل", "kind": "tabei", "stock_price": 9800, "put_price": 40, "strike": 14210,
108
+ "days": 365, "margin_per_contract": 9840, "unit": "سهم",
109
+ "liquidity_contracts_per_day": 240, "spread_pct": 0.02},
110
+ {"symbol": "شپنا", "kind": "box", "call_low": 300, "put_low": 430, "call_high": 175,
111
+ "put_high": 585, "strike_low": 1200, "strike_high": 1500, "days": 45,
112
+ "margin_per_contract": 250000, "unit": "قرارداد",
113
+ "liquidity_contracts_per_day": 12, "spread_pct": 0.045},
114
+ {"symbol": "وبملت", "kind": "parity", "call": 420, "put": 380, "spot": 9000, "strike": 9000,
115
+ "days": 30, "rate": 0.39, "margin_per_contract": 9000, "unit": "سهم",
116
+ "liquidity_contracts_per_day": 80, "spread_pct": 0.02},
117
+ ],
118
+ }
119
+
120
+ DEFAULT_LIVE_CONFIG: dict = {
121
+ "url_template": "", # مثال: https://api.example.ir/Quote.php?key={key}&l18={symbol}
122
+ "json_path": "data.0.pl", # مسیر رسیدن به «قیمت پایه» داخل پاسخ JSON
123
+ "key_header": "", # اگر کلید باید در هدر برود، نام هدر را بنویسید
124
+ "key_query_name": "key", # اگر کلید در نشانی می‌رود، نام پارامتر
125
+ "timeout_seconds": 12,
126
+ "retries": 1,
127
+ "cache_seconds": 30,
128
+ "field_map": { # کدام کلید اسنپ‌شات از کدام فیلد بازار پر شود
129
+ "spot": "spot",
130
+ "stock_price": "stock_price",
131
+ "future": "future",
132
+ },
133
+ }
134
+
135
+
136
+ # ---------------------------------------------------------------- ابزارها
137
+ def now_iso() -> str:
138
+ return datetime.now(timezone.utc).isoformat(timespec="seconds")
139
+
140
+
141
+ def log(msg: str) -> None:
142
+ print(msg)
143
+
144
+
145
+ def transient_error(exc: BaseException) -> bool:
146
+ """آیا این خطای شبکه «گذرا» است (ارزش تلاش دوباره دارد) یا قطعی؟"""
147
+ if isinstance(exc, urllib.error.HTTPError):
148
+ return exc.code >= 500 or exc.code in (408, 429)
149
+ reason = getattr(exc, "reason", exc)
150
+ if isinstance(reason, socket.gaierror):
151
+ return False
152
+ if isinstance(reason, ConnectionRefusedError):
153
+ return False
154
+ if getattr(reason, "errno", None) in (errno.ECONNREFUSED, errno.EHOSTUNREACH, errno.ENETUNREACH,
155
+ errno.EADDRNOTAVAIL):
156
+ return False
157
+ return True
158
+
159
+
160
+ def fetch(url: str, *, timeout: float = 12, retries: int = 1,
161
+ key_header: str = "", key: str = "", cache_name: str | None = None,
162
+ cache_seconds: int = 30, use_cache: bool = True,
163
+ stale_ok: bool = True) -> tuple[str | None, str]:
164
+ """دریافت متن با تلاش مجدد و حافظهٔ نهان. خروجی: (متن یا None، پیام وضعیت).
165
+
166
+ stale_ok=False یعنی «اگر شبکه جواب نداد، از حافظهٔ نهان نخوان»؛ این پرچم برای جاهایی
167
+ است که خواندن از حافظهٔ کهنه، «موفقیت دروغین» می‌سازد (سنجش منبع، کاوش پاسخ سرویس).
168
+ هر جا از ح��فظهٔ نهان خوانده شود، در پیام وضعیت صریح نوشته می‌شود.
169
+ """
170
+ url = ascii_safe_url(url)
171
+ if url.startswith("file:"):
172
+ try:
173
+ return Path(url[5:]).read_text(encoding="utf-8-sig"), "از پروندهٔ محلی خوانده شد"
174
+ except OSError as e:
175
+ return None, f"خواندن پرونده ممکن نشد: {e}"
176
+ CACHE_DIR.mkdir(parents=True, exist_ok=True)
177
+ cache_file = CACHE_DIR / (cache_name or "last.json")
178
+ if use_cache and cache_file.exists() and cache_seconds > 0:
179
+ age = time.time() - cache_file.stat().st_mtime
180
+ if age < cache_seconds:
181
+ return cache_file.read_text(encoding="utf-8"), f"از حافظهٔ نهان ({int(age)} ثانیه پیش)"
182
+ headers = {"User-Agent": "IranDeskStation/0.1 (+local)"}
183
+ if key_header and key:
184
+ headers[key_header] = key
185
+ req = urllib.request.Request(url, headers=headers)
186
+ last_err = ""
187
+ for attempt in range(1, retries + 2):
188
+ try:
189
+ with urllib.request.urlopen(req, timeout=timeout) as resp:
190
+ body = resp.read().decode("utf-8", errors="replace")
191
+ cache_file.write_text(body, encoding="utf-8")
192
+ return body, f"دریافت تازه در تلاش {attempt}"
193
+ except (urllib.error.URLError, urllib.error.HTTPError, TimeoutError, OSError) as e:
194
+ last_err = f"{type(e).__name__}: {e}"
195
+ # خطای گذرا: مکث و تلاش دوباره. خطای قطعی (سرویس خاموش، نام دامنهٔ نادرست،
196
+ # ۴۰۴/۴۰۱) را نباید مکث کرد؛ وگرنه هر نماد ۱٫۵ ثانیه بی‌دلیل منتظر می‌ماند.
197
+ if attempt > retries or not transient_error(e):
198
+ break
199
+ time.sleep(min(1.0 * attempt, 3.0))
200
+ if stale_ok and cache_file.exists():
201
+ age = int(time.time() - cache_file.stat().st_mtime)
202
+ return (cache_file.read_text(encoding="utf-8"),
203
+ f"از حافظهٔ نهان {age} ثانیه‌ای استفاده شد، نه از شبکه ({last_err})")
204
+ return None, f"دریافت ناموفق: {last_err}"
205
+
206
+
207
+ def dig(data, path: str):
208
+ """مسیر نقطه‌ای مثل data.0.pl را در ساختار JSON دنبال می‌کند."""
209
+ cur = data
210
+ for part in [p for p in path.split(".") if p != ""]:
211
+ if isinstance(cur, list):
212
+ try:
213
+ cur = cur[int(part)]
214
+ except (ValueError, IndexError):
215
+ return None
216
+ elif isinstance(cur, dict):
217
+ if part not in cur:
218
+ return None
219
+ cur = cur[part]
220
+ else:
221
+ return None
222
+ return cur
223
+
224
+
225
+ # ---------------------------------------------------------------- نتیجهٔ اسنپ‌شات
226
+ @dataclass
227
+ class Snapshot:
228
+ rows: list[dict] = field(default_factory=list)
229
+ mode: str = "sim"
230
+ source_label: str = ""
231
+ as_of: str = ""
232
+ fetched_at: str = ""
233
+ freshness_seconds: float | None = None
234
+ status: str = "ok" # ok | partial | failed
235
+ messages: list[str] = field(default_factory=list)
236
+ missing_fields: list[str] = field(default_factory=list)
237
+ live_prices: dict[str, float] = field(default_factory=dict)
238
+
239
+ @property
240
+ def freshness_label(self) -> str:
241
+ if self.freshness_seconds is None:
242
+ return "نامعلوم"
243
+ s = int(self.freshness_seconds)
244
+ if s < 90:
245
+ return f"زنده ({s} ثانیه پیش)"
246
+ if s < 3600:
247
+ return f"نسبتاً تازه ({s // 60} دقیقه پیش)"
248
+ if s < 86400:
249
+ return f"کهنه ({s // 3600} ساعت پیش)"
250
+ return f"تاریخی ({s // 86400} روز پیش)"
251
+
252
+ def to_dict(self) -> dict:
253
+ return {"as_of": self.as_of, "hurdle": self.rows[0].get("_hurdle", 0.39),
254
+ "capital": self.rows[0].get("_capital", 0), "rows": self.rows}
255
+
256
+
257
+ # ---------------------------------------------------------------- بارگذاری‌ها
258
+ def load_snapshot_file(path: str | Path) -> Snapshot:
259
+ p = Path(path)
260
+ if not p.exists():
261
+ return Snapshot(status="failed", mode="file", source_label="پروندهٔ دستی",
262
+ messages=[f"پروندهٔ اسنپ‌شات پیدا نشد: {p}"])
263
+ try:
264
+ data = json.loads(p.read_text(encoding="utf-8-sig"))
265
+ except json.JSONDecodeError as e:
266
+ return Snapshot(status="failed", mode="file", source_label="پروندهٔ دستی",
267
+ messages=[f"پروندهٔ JSON خوانده نشد: {e}"])
268
+ rows = [coerce_row_numbers(r) for r in (data.get("rows") or []) if isinstance(r, dict)]
269
+ missing: list[str] = []
270
+ for i, r in enumerate(rows):
271
+ for k in ("symbol", "kind"):
272
+ if not r.get(k):
273
+ missing.append(f"ردیف {i + 1}: «{k}» خالی است")
274
+ hurdle = float(data.get("hurdle", 0.39))
275
+ capital = float(data.get("capital", 0))
276
+ for r in rows:
277
+ r["_hurdle"] = hurdle
278
+ r["_capital"] = capital
279
+ return Snapshot(rows=rows, mode="file", source_label=f"پروندهٔ دستی: {p.name}",
280
+ as_of=str(data.get("as_of", "")), fetched_at=now_iso(),
281
+ freshness_seconds=time.time() - p.stat().st_mtime,
282
+ status="ok" if rows and not missing else ("partial" if rows else "failed"),
283
+ messages=[f"{len(rows)} ردیف خوانده شد"] + missing,
284
+ missing_fields=missing)
285
+
286
+
287
+ def demo_snapshot() -> Snapshot:
288
+ snap = load_snapshot_file(DESK_DIR / "market-demo.json")
289
+ snap.mode = "sim"
290
+ snap.source_label = "دادهٔ نمونه (ساختگی)"
291
+ snap.messages.append("هشدار: اعداد این اسنپ‌شات ساختگی‌اند و قیمت واقعی بازار نیستند.")
292
+ snap.freshness_seconds = None
293
+ return snap
294
+
295
+
296
+ def numeric_paths(payload, *, max_items: int = 40, max_depth: int = 6) -> list[tuple[str, float]]:
297
+ """مسیرهای عددی داخل یک پاسخ JSON را پیدا می‌کند تا «مسیر JSON» را حدس نزنیم.
298
+
299
+ خروجی: فهرست (مسیر، مقدار) مثل ("data.0.pl", 20150.0)
300
+ """
301
+ out: list[tuple[str, float]] = []
302
+
303
+ def walk(node, prefix: str, depth: int) -> None:
304
+ if len(out) >= max_items or depth > max_depth:
305
+ return
306
+ if isinstance(node, dict):
307
+ for k, v in node.items():
308
+ walk(v, f"{prefix}.{k}" if prefix else str(k), depth + 1)
309
+ elif isinstance(node, list):
310
+ for i, v in enumerate(node[:8]):
311
+ walk(v, f"{prefix}.{i}" if prefix else str(i), depth + 1)
312
+ else:
313
+ if isinstance(node, bool) or node is None:
314
+ return
315
+ if isinstance(node, (int, float)):
316
+ out.append((prefix, float(node)))
317
+ elif isinstance(node, str):
318
+ txt = node.strip().replace(",", "")
319
+ try:
320
+ out.append((prefix, float(txt)))
321
+ except ValueError:
322
+ return
323
+
324
+ walk(payload, "", 0)
325
+ return out
326
+
327
+
328
+ def parse_quote_payload(text: str, json_path: str, symbol: str) -> tuple[float | None, str]:
329
+ """قیمت را از پاسخ سرویس بیرون می‌کشد. برای هر سرویس، فقط مسیر JSON عوض می‌شود."""
330
+ try:
331
+ data = json.loads(text)
332
+ except json.JSONDecodeError:
333
+ # بعضی سرویس‌ها متن ساده یا CSV برمی‌گردانند
334
+ for token in reversed(text.replace(";", ",").replace("|", ",").split(",")):
335
+ token = token.strip()
336
+ if token and all(c.isdigit() or c in ".-" for c in token):
337
+ try:
338
+ return float(token), "مقدار از متن ساده استخراج شد (مسیر JSON نادیده گرفته شد)"
339
+ except ValueError:
340
+ continue
341
+ return None, "پاسخ JSON نبود و عددی هم پیدا نشد"
342
+ value = dig(data, json_path) if json_path else None
343
+ if value is None and isinstance(data, dict):
344
+ for k in ("pl", "plc", "price", "last", "close", "pDrCotVal", "lastPrice"):
345
+ if k in data:
346
+ value = data[k]
347
+ break
348
+ if value is None:
349
+ return None, f"مسیر «{json_path}» در پاسخ پیدا نشد"
350
+ try:
351
+ return float(str(value).replace(",", "").strip()), "قیمت خوانده شد"
352
+ except ValueError:
353
+ return None, f"مقدار «{value}» عدد نبود"
354
+
355
+
356
+ def finish_live(snap: Snapshot, prices: dict, *, stale_count: int = 0, fail_count: int = 0) -> Snapshot:
357
+ """قیمت‌های خوانده‌شده را روی اسنپ‌شات می‌نشاند، سنجهٔ صداقت را می‌گذارد و برچسب می‌زند.
358
+
359
+ این تابع از مسیر زندهٔ خودِ برنامه و از «برگهٔ شاهد زنده» (demo_day) یکسان صدا زده می‌شود تا
360
+ عددی که در برگهٔ شاهد چاپ می‌شود، دقیقاً همان عددی باشد که برنامه رویش تصمیم می‌گیرد.
361
+ """
362
+ ok_count = len(prices)
363
+ for row in snap.rows:
364
+ symbol = str(row.get("symbol", "")).strip()
365
+ if symbol not in prices:
366
+ continue
367
+ for target in ("spot", "stock_price"):
368
+ if isinstance(row.get(target), (int, float)):
369
+ # قیمت پایه/سهم با قیمت زنده جابه‌جا می‌شود؛ آتی و مشخصات قرارداد دست‌نخورده می‌ماند.
370
+ row[f"{target}_manual"] = row[target]
371
+ row[target] = prices[symbol]
372
+ snap.live_prices = prices
373
+ snap.fetched_at = now_iso()
374
+ # تازگی فقط وقتی معنا دارد که قیمت از «شبکه» آمده باشد؛ خواندن از حافظهٔ نهان
375
+ # نباید «زندهٔ ۰ ثانیه پیش» جا بزند.
376
+ snap.freshness_seconds = 0.0 if (prices and not stale_count) else None
377
+ if stale_count:
378
+ snap.messages.append(f"{stale_count} نماد از حافظهٔ نهان خوانده شد، نه از شبکه؛ "
379
+ f"این عددها قیمت زنده نیستند و برچسب «از حافظهٔ نهان» می‌گیرند.")
380
+ snap.source_label = f"{snap.source_label} (از حافظهٔ نهان)"
381
+ if snap.status == "ok":
382
+ snap.status = "partial"
383
+ # سنجهٔ صداقت: اگر قیمت چند نماد عیناً یکی باشد، یعنی این منبع «نرخ واحد» می‌دهد،
384
+ # نه قیمت هر نماد. آن‌وقت محاسبهٔ سهام بی‌معنی است و باید بگوییم.
385
+ if len(prices) >= 2 and len(set(prices.values())) == 1:
386
+ snap.status = "partial"
387
+ snap.messages.append("قیمت چند نماد عیناً یکسان آمد؛ یعنی این منبع یک «نرخ واحد» می‌دهد "
388
+ "(مثل نرخ ارز)، نه قیمت هر نماد. برای محاسبهٔ سهام، منبع نمادی "
389
+ "یا پروندهٔ دستی کارگزاری لازم است — به عددهای زیر استناد نکنید.")
390
+ snap.source_label = f"{snap.source_label} (نرخ واحد، نه نماد)"
391
+ return snap
392
+ if ok_count and not fail_count:
393
+ snap.status = "ok"
394
+ snap.messages.append(f"قیمت زندهٔ {ok_count} نماد به‌روز شد.")
395
+ elif ok_count:
396
+ snap.status = "partial"
397
+ snap.messages.append(f"قیمت {ok_count} نماد به‌روز شد و {fail_count} نماد نیامد.")
398
+ else:
399
+ snap.status = "failed"
400
+ snap.messages.append("هیچ قیمتی از سرویس نیامد؛ قالب نشانی و مسیر JSON را بررسی کنید.")
401
+ return snap
402
+
403
+
404
+ def live_snapshot(base: Snapshot | dict, live_cfg: dict, *, key: str = "",
405
+ allow_network: bool = True, progress=None) -> Snapshot:
406
+ """قیمت‌های زنده را روی یک اسنپ‌شات پایه می‌نشاند.
407
+
408
+ دادهٔ پایه (مشخصات قرارداد، وجه تضمین، تعداد روز) از پرونده می‌آید؛
409
+ قیمت‌ها از سرویس. این تفکیک عمدی است: وجه تضمین فقط از کارگزاری می‌آید.
410
+ """
411
+ def say(m: str) -> None:
412
+ if progress:
413
+ progress(m)
414
+ log(m)
415
+
416
+ if isinstance(base, Snapshot):
417
+ snap = base
418
+ else:
419
+ snap = load_snapshot_file(base)
420
+ snap.mode = "live"
421
+ url_tpl = (live_cfg.get("url_template") or "").strip()
422
+ # صداقت برچسب: اگر نشانی روی همین رایانه باشد، داده ساختگی است، نه بازار واقعی.
423
+ local_feed = any(h in url_tpl for h in ("127.0.0.1", "localhost", "0.0.0.0", "::1"))
424
+ snap.source_label = "خوراک آزمایشی محلی (ساختگی)" if local_feed else "دادهٔ زندهٔ وب‌سرویس"
425
+ if not url_tpl:
426
+ snap.status = "failed"
427
+ snap.messages.append("قالب نشانی خالی است؛ در همین صفحه نشانی سرویس را وارد کنید.")
428
+ return snap
429
+ if not allow_network:
430
+ snap.status = "failed"
431
+ snap.messages.append("دسترسی شبکه در این اجرا بسته است.")
432
+ return snap
433
+
434
+ prices: dict[str, float] = {}
435
+ ok_count, fail_count, stale_count = 0, 0, 0
436
+ for row in snap.rows:
437
+ symbol = str(row.get("symbol", "")).strip()
438
+ if not symbol:
439
+ continue
440
+ # feed_symbol اجازه می‌دهد در نشانی به‌جای نام نماد، «کد نماد» (insCode) برود
441
+ url_symbol = str(row.get("feed_symbol") or symbol).strip()
442
+ url = url_tpl.replace("{symbol}", urllib.parse.quote(url_symbol))
443
+ if live_cfg.get("key_query_name"):
444
+ url = url.replace("{key}", urllib.parse.quote(key)) if "{key}" in url_tpl else url
445
+ if "{key}" in url:
446
+ url = url.replace("{key}", urllib.parse.quote(key))
447
+ text, status = fetch(url, timeout=float(live_cfg.get("timeout_seconds", 12)),
448
+ retries=int(live_cfg.get("retries", 1)),
449
+ key_header=live_cfg.get("key_header", ""), key=key,
450
+ cache_name=f"quote-{symbol}.json",
451
+ cache_seconds=int(live_cfg.get("cache_seconds", 30)))
452
+ if not text:
453
+ fail_count += 1
454
+ say(f"قیمت {symbol} نیامد: {status}")
455
+ continue
456
+ if "حافظهٔ نهان" in status:
457
+ stale_count += 1
458
+ say(f"قیمت {symbol} از حافظهٔ نهان آمد، نه از شبکه")
459
+ value, why = parse_quote_payload(text, live_cfg.get("json_path", ""), symbol)
460
+ if value is None:
461
+ fail_count += 1
462
+ say(f"قیمت {symbol} خوانده نشد: {why}")
463
+ continue
464
+ prices[symbol] = value
465
+ ok_count += 1
466
+ say(f"قیمت زندهٔ {symbol}: {value:,.0f}")
467
+
468
+ return finish_live(snap, prices, stale_count=stale_count, fail_count=fail_count)
469
+ if ok_count and not fail_count:
470
+ snap.status = "ok"
471
+ snap.messages.append(f"قیمت زندهٔ {ok_count} نماد به‌روز شد.")
472
+ elif ok_count:
473
+ snap.status = "partial"
474
+ snap.messages.append(f"قیمت {ok_count} نماد به‌روز شد و {fail_count} نماد نیامد.")
475
+ else:
476
+ snap.status = "failed"
477
+ snap.messages.append("هیچ قیمتی از سرویس نیامد؛ قالب نشانی و مسیر JSON را بررسی کنید.")
478
+ return snap
479
+
480
+
481
+ def build_snapshot(mode: str, *, file_path: str | Path | None = None, live_cfg: dict | None = None,
482
+ key: str = "", allow_network: bool = True, progress=None) -> Snapshot:
483
+ """دروازهٔ یکسان برای همهٔ حالت‌ها (همان چیزی که رابط گرافیکی صدا می‌زند)."""
484
+ if mode == "sim":
485
+ return demo_snapshot()
486
+ if mode == "file":
487
+ if not file_path:
488
+ return Snapshot(status="failed", mode="file", messages=["مسیر پرونده داده نشده است."])
489
+ return load_snapshot_file(file_path)
490
+ if mode == "live":
491
+ base = load_snapshot_file(file_path) if file_path else demo_snapshot()
492
+ return live_snapshot(base, live_cfg or DEFAULT_LIVE_CONFIG, key=key,
493
+ allow_network=allow_network, progress=progress)
494
+ return Snapshot(status="failed", mode=mode, messages=[f"حالت دادهٔ ناشناخته: {mode}"])
495
+
496
+
497
+ # ---------------------------------------------------------------- خواندن هشدارهای کدال
498
+ def read_alerts(kodal_db: str | Path, min_score: int = 60, limit: int = 50) -> list[dict]:
499
+ p = Path(kodal_db)
500
+ if not p.exists():
501
+ return []
502
+ try:
503
+ conn = sqlite3.connect(f"file:{p}?mode=ro", uri=True)
504
+ rows = conn.execute(
505
+ "SELECT title, symbol, category, direction, score, url FROM items "
506
+ "WHERE score >= ? ORDER BY score DESC LIMIT ?", (min_score, limit)).fetchall()
507
+ conn.close()
508
+ except sqlite3.Error:
509
+ return []
510
+ return [{"title": t, "symbol": s, "category": c, "direction": d, "score": sc, "url": u}
511
+ for t, s, c, d, sc, u in rows]
512
+
513
+
514
+ def write_snapshot_template(path: str | Path) -> Path:
515
+ """قالب اسنپ‌شات برای کاربر تازه‌کار می‌سازد."""
516
+ p = Path(path)
517
+ p.parent.mkdir(parents=True, exist_ok=True)
518
+ p.write_text(json.dumps(SNAPSHOT_TEMPLATE, ensure_ascii=False, indent=2), encoding="utf-8")
519
+ return p
520
+
521
+
522
+ # ---------------------------------------------------------------- اسنپ‌شات دستی تاریخ‌دار
523
+ def ascii_safe_url(url: str) -> str:
524
+ """نشانی‌هایی که حرف فارسی دارند (مثل نام نماد) را درصد‌کد می‌کند.
525
+
526
+ بدون این کار، کتابخانهٔ شبکه با خطای UnicodeEncodeError می‌خوابد؛ این ایراد در آزمون
527
+ «اتصال خودکار» با نام نماد فارسی پیدا شد.
528
+ """
529
+ try:
530
+ str(url).encode("ascii")
531
+ return str(url)
532
+ except UnicodeEncodeError:
533
+ import urllib.parse as _up
534
+ return _up.quote(str(url), safe=":/?#[]@!$&'()*+,;=%")
535
+
536
+
537
+ SNAPSHOT_NUM_FIELDS = ("spot", "future", "strike", "premium", "stock_price", "put_price",
538
+ "days", "margin_per_contract", "liquidity_contracts_per_day", "spread_pct")
539
+ SNAPSHOT_KINDS = ("basis", "box", "tabei", "covered_call", "parity")
540
+
541
+
542
+ def load_snapshot_rows(path: str | Path) -> dict:
543
+ """ردیف‌های یک اسنپ‌شات را برای ویرایش در رابط گرافیکی برمی‌گرداند."""
544
+ p = Path(path)
545
+ if not p.exists():
546
+ return {"rows": [], "as_of": "", "hurdle": 0.39, "capital": 20_000_000_000,
547
+ "note": "پرونده‌ای نیست", "path": str(p), "exists": False}
548
+ try:
549
+ data = json.loads(p.read_text(encoding="utf-8-sig"))
550
+ except json.JSONDecodeError as e:
551
+ return {"rows": [], "as_of": "", "hurdle": 0.39, "capital": 20_000_000_000,
552
+ "note": f"پرونده خوانده نشد: {e}", "path": str(p), "exists": True}
553
+ rows = [{k: v for k, v in r.items() if not k.startswith("_")} for r in (data.get("rows") or [])]
554
+ return {"rows": rows, "as_of": str(data.get("as_of", "")),
555
+ "hurdle": float(data.get("hurdle", 0.39)),
556
+ "capital": float(data.get("capital", 20_000_000_000)),
557
+ "note": str(data.get("note", "")), "source": str(data.get("source", "")),
558
+ "confirmed": snapshot_confirmed(p), "path": str(p), "exists": True}
559
+
560
+
561
+ def clean_rows(raw_rows: list[dict]) -> tuple[list[dict], list[str]]:
562
+ """ردیف‌های فرم را پاکیزه می‌کند: فیلدهای خالی حذف، عددها عدد، ردیف بی‌نماد کنار گذاشته.
563
+
564
+ خروجی: (ردیف‌های آماده، هشدارها)
565
+ """
566
+ out: list[dict] = []
567
+ problems: list[str] = []
568
+ for i, r in enumerate(raw_rows or []):
569
+ if not isinstance(r, dict):
570
+ problems.append(f"ردیف {i + 1}: ساختار نامعتبر")
571
+ continue
572
+ symbol = str(r.get("symbol", "") or "").strip()
573
+ if not symbol:
574
+ continue # ردیف خالی را بی‌صدا رد می‌کنیم
575
+ kind = str(r.get("kind", "") or "basis").strip() or "basis"
576
+ if kind not in SNAPSHOT_KINDS:
577
+ problems.append(f"ردیف {i + 1} ({symbol}): نوع «{kind}» شناخته نشد؛ «basis» گذاشته شد.")
578
+ kind = "basis"
579
+ row: dict = {"symbol": symbol, "kind": kind}
580
+ for k, v in r.items():
581
+ if k in ("symbol", "kind"):
582
+ continue
583
+ if isinstance(v, str):
584
+ v = v.strip().replace(",", "")
585
+ if v in ("", None):
586
+ continue
587
+ if k in SNAPSHOT_NUM_FIELDS:
588
+ try:
589
+ row[k] = float(v)
590
+ except (TypeError, ValueError):
591
+ problems.append(f"ردیف {i + 1} ({symbol}): «{k}» عدد نبود و کنار گذاشته شد.")
592
+ continue
593
+ row[k] = v
594
+ price_fields = ("spot", "stock_price", "future", "strike", "premium", "put_price",
595
+ "call", "put", "call_low", "call_high", "put_low", "put_high",
596
+ "strike_low", "strike_high")
597
+ if not any(isinstance(row.get(k), (int, float)) and row[k] > 0 for k in price_fields):
598
+ problems.append(f"ردیف {i + 1} ({symbol}): هیچ قیمتی وارد نشده؛ ردیف می‌ماند ولی سیگنالی نمی‌دهد.")
599
+ unit = str(r.get("feed_symbol", "") or "").strip()
600
+ if unit:
601
+ row["feed_symbol"] = unit
602
+ out.append(row)
603
+ if not out:
604
+ problems.append("هیچ ردیف درستی وارد نشد؛ حداقل یک نماد با قیمت لازم است.")
605
+ return out, problems
606
+
607
+
608
+ MANUAL_SOURCE = "manual-broker"
609
+
610
+
611
+ def snapshot_confirmed(path: str | Path | None) -> bool:
612
+ """آیا این پرونده را کاربر از سامانهٔ کارگزاری برداشته و تأیید کرده است؟
613
+
614
+ بدون این تأیید، پرونده «واقعی» حساب نمی‌شود؛ وگرنه هر پرونده‌ای می‌توانست روز واقعی جعل کند.
615
+ """
616
+ if not path:
617
+ return False
618
+ p = Path(path)
619
+ if not p.exists():
620
+ return False
621
+ try:
622
+ data = json.loads(p.read_text(encoding="utf-8-sig"))
623
+ except Exception:
624
+ return False
625
+ return str(data.get("source", "")) == MANUAL_SOURCE
626
+
627
+
628
+ def save_dated_snapshot(rows: list[dict], *, as_of: str | None = None, hurdle: float = 0.39,
629
+ capital: float = 20_000_000_000, note: str = "",
630
+ out_dir: str | Path | None = None, day: str | None = None,
631
+ source: str = MANUAL_SOURCE) -> Path:
632
+ """اسنپ‌شات را با تاریخ می‌نویسد: `snapshots/snapshot-YYYY-MM-DD.json`.
633
+
634
+ چرا تاریخ‌دار؟ چون هر روز پروندهٔ خودش را می‌خواهد: هم سابقهٔ قابل ممیزی می‌شود،
635
+ هم اشتباه یک روز، روزهای دیگر را خراب نمی‌کند.
636
+ """
637
+ clean, _ = clean_rows(rows)
638
+ if not clean:
639
+ raise ValueError("هیچ ردیف درستی برای ذخیره نبود.")
640
+ d = (Path(out_dir) if out_dir else (BASE / "data" / "snapshots"))
641
+ d.mkdir(parents=True, exist_ok=True)
642
+ stamp = day or datetime.now().strftime("%Y-%m-%d")
643
+ path = d / f"snapshot-{stamp}.json"
644
+ payload = {"as_of": as_of or datetime.now().strftime("%Y-%m-%d %H:%M"),
645
+ "hurdle": float(hurdle), "capital": float(capital),
646
+ "note": note, "source": source, "rows": clean}
647
+ path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
648
+ return path
649
+
650
+
651
+ def history_template_rows() -> list[dict]:
652
+ """سطر نمونهٔ پروندهٔ پس‌آزمایی، برای اینکه کاربر بداند چه ستون‌هایی لازم است."""
653
+ return [
654
+ {"date": "1405-05-01", "symbol": "اهرم", "kind": "basis", "spot": 20000, "future": 22800,
655
+ "days": 90, "margin_per_contract": 20000000, "liquidity_contracts_per_day": 900,
656
+ "spread_pct": 0.005, "hurdle": 0.39, "realized_annualized_pct": 61.0},
657
+ ]
658
+
659
+
660
+ def write_history_template(path: str | Path) -> Path:
661
+ p = Path(path)
662
+ p.parent.mkdir(parents=True, exist_ok=True)
663
+ cols = ["date", "symbol", "kind", "spot", "future", "strike", "premium", "put_price", "stock_price",
664
+ "days", "margin_per_contract", "liquidity_contracts_per_day", "spread_pct", "hurdle",
665
+ "realized_annualized_pct"]
666
+ with p.open("w", encoding="utf-8", newline="") as f:
667
+ w = csv.DictWriter(f, fieldnames=cols)
668
+ w.writeheader()
669
+ for r in history_template_rows():
670
+ w.writerow({c: r.get(c, "") for c in cols})
671
+ return p
station/demo/history-demo.csv ADDED
@@ -0,0 +1,103 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # پروندهٔ تاریخ نمونه (سینتتیک) — اعداد واقعی بازار نیستند
2
+ # ستون‌ها: تاریخ · نماد · راهبرد · فیلدهای ریاضی · وجه تضمین · نقدشوندگی · اسپرد · نرخ سد · نتیجهٔ واقعی سالانه
3
+ 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
4
+ 1405-01-15,اهرم,basis,20000,21920,,,,,,,,,,,,,,90,20000000,900,0.005,0.33,29.8
5
+ 1405-01-15,طلا,basis,20000,21773,,,,,,,,,,,,,,60,20000000,700,0.006,0.33,44.6
6
+ 1405-01-15,فولاد,covered_call,7000,,7600,357,,,,,,,,,,,,45,7000,160,0.018,0.33,47.7
7
+ 1405-01-15,شپنا,covered_call,9000,,9600,419,,,,,,,,,,,,30,9000,90,0.02,0.33,48.2
8
+ 1405-01-15,کگل,tabei,,,14210,,40,9800,,,,,,,,,,365,9840,240,0.02,0.33,-8.3
9
+ 1405-01-15,خساپا,tabei,,,3000,,14,2500,,,,,,,,,,270,2512,320,0.012,0.33,3.8
10
+ 1405-01-15,شستا,tabei,,,1320,,8,1200,,,,,,,,,,200,1205,400,0.015,0.33,-56.8
11
+ 1405-01-15,وبملت,parity,9000,,9000,,,,638,380,,,,,,,0.39,30,9000,80,0.02,0.33,64.1
12
+ 1405-01-15,شپدیس,box,,,,,,,,,89,123,75,164,1200,1500,,45,250000,60,0.025,0.33,36.5
13
+ 1405-01-15,فملی,box,,,,,,,,,89,122,75,164,800,1100,,30,200000,45,0.022,0.33,32.4
14
+ 1405-02-15,اهرم,basis,20000,22487,,,,,,,,,,,,,,90,20000000,900,0.005,0.34,16.4
15
+ 1405-02-15,طلا,basis,20000,21651,,,,,,,,,,,,,,60,20000000,700,0.006,0.34,62.8
16
+ 1405-02-15,فولاد,covered_call,7000,,7600,355,,,,,,,,,,,,45,7000,160,0.018,0.34,39.8
17
+ 1405-02-15,شپنا,covered_call,9000,,9600,435,,,,,,,,,,,,30,9000,90,0.02,0.34,69.3
18
+ 1405-02-15,کگل,tabei,,,14210,,34,9800,,,,,,,,,,365,9840,240,0.02,0.34,50.9
19
+ 1405-02-15,خساپا,tabei,,,3000,,14,2500,,,,,,,,,,270,2512,320,0.012,0.34,42.1
20
+ 1405-02-15,شستا,tabei,,,1320,,5,1200,,,,,,,,,,200,1205,400,0.015,0.34,65.4
21
+ 1405-02-15,وبملت,parity,9000,,9000,,,,641,380,,,,,,,0.39,30,9000,80,0.02,0.34,25.8
22
+ 1405-02-15,شپدیس,box,,,,,,,,,89,123,75,164,1200,1500,,45,250000,60,0.025,0.34,108.0
23
+ 1405-02-15,فملی,box,,,,,,,,,89,123,75,164,800,1100,,30,200000,45,0.022,0.34,31.0
24
+ 1405-03-15,اهرم,basis,20000,22423,,,,,,,,,,,,,,90,20000000,900,0.005,0.35,-27.3
25
+ 1405-03-15,طلا,basis,20000,21899,,,,,,,,,,,,,,60,20000000,700,0.006,0.35,53.8
26
+ 1405-03-15,فولاد,covered_call,7000,,7600,351,,,,,,,,,,,,45,7000,160,0.018,0.35,45.3
27
+ 1405-03-15,شپنا,covered_call,9000,,9600,451,,,,,,,,,,,,30,9000,90,0.02,0.35,54.3
28
+ 1405-03-15,کگل,tabei,,,14210,,37,9800,,,,,,,,,,365,9840,240,0.02,0.35,31.8
29
+ 1405-03-15,خساپا,tabei,,,3000,,13,2500,,,,,,,,,,270,2512,320,0.012,0.35,31.2
30
+ 1405-03-15,شستا,tabei,,,1320,,5,1200,,,,,,,,,,200,1205,400,0.015,0.35,21.4
31
+ 1405-03-15,وبملت,parity,9000,,9000,,,,594,380,,,,,,,0.39,30,9000,80,0.02,0.35,-63.5
32
+ 1405-03-15,شپدیس,box,,,,,,,,,89,123,75,164,1200,1500,,45,250000,60,0.025,0.35,43.8
33
+ 1405-03-15,فملی,box,,,,,,,,,88,121,75,163,800,1100,,30,200000,45,0.022,0.35,27.1
34
+ 1405-04-15,اهرم,basis,20000,22883,,,,,,,,,,,,,,90,20000000,900,0.005,0.36,24.7
35
+ 1405-04-15,طلا,basis,20000,21736,,,,,,,,,,,,,,60,20000000,700,0.006,0.36,45.2
36
+ 1405-04-15,فولاد,covered_call,7000,,7600,362,,,,,,,,,,,,45,7000,160,0.018,0.36,32.4
37
+ 1405-04-15,شپنا,covered_call,9000,,9600,452,,,,,,,,,,,,30,9000,90,0.02,0.36,-16.7
38
+ 1405-04-15,کگل,tabei,,,14210,,45,9800,,,,,,,,,,365,9840,240,0.02,0.36,21.8
39
+ 1405-04-15,خساپا,tabei,,,3000,,8,2500,,,,,,,,,,270,2512,320,0.012,0.36,7.3
40
+ 1405-04-15,شستا,tabei,,,1320,,4,1200,,,,,,,,,,200,1205,400,0.015,0.36,21.4
41
+ 1405-04-15,وبملت,parity,9000,,9000,,,,643,380,,,,,,,0.39,30,9000,80,0.02,0.36,59.6
42
+ 1405-04-15,شپدیس,box,,,,,,,,,88,121,75,163,1200,1500,,45,250000,60,0.025,0.36,34.0
43
+ 1405-04-15,فملی,box,,,,,,,,,88,121,75,163,800,1100,,30,200000,45,0.022,0.36,7.8
44
+ 1405-05-15,اهرم,basis,20000,23138,,,,,,,,,,,,,,90,20000000,900,0.005,0.37,-38.7
45
+ 1405-05-15,طلا,basis,20000,21312,,,,,,,,,,,,,,60,20000000,700,0.006,0.37,17.1
46
+ 1405-05-15,فولاد,covered_call,7000,,7600,345,,,,,,,,,,,,45,7000,160,0.018,0.37,40.3
47
+ 1405-05-15,شپنا,covered_call,9000,,9600,490,,,,,,,,,,,,30,9000,90,0.02,0.37,85.7
48
+ 1405-05-15,کگل,tabei,,,14210,,44,9800,,,,,,,,,,365,9840,240,0.02,0.37,44.1
49
+ 1405-05-15,خساپا,tabei,,,3000,,12,2500,,,,,,,,,,270,2512,320,0.012,0.37,-4.6
50
+ 1405-05-15,شستا,tabei,,,1320,,6,1200,,,,,,,,,,200,1205,400,0.015,0.37,28.0
51
+ 1405-05-15,وبملت,parity,9000,,9000,,,,625,380,,,,,,,0.39,30,9000,80,0.02,0.37,15.7
52
+ 1405-05-15,شپدیس,box,,,,,,,,,87,121,75,163,1200,1500,,45,250000,60,0.025,0.37,9.8
53
+ 1405-05-15,فملی,box,,,,,,,,,88,121,75,163,800,1100,,30,200000,45,0.022,0.37,1.1
54
+ 1405-06-15,اهرم,basis,20000,22803,,,,,,,,,,,,,,90,20000000,900,0.005,0.38,32.1
55
+ 1405-06-15,طلا,basis,20000,21237,,,,,,,,,,,,,,60,20000000,700,0.006,0.38,-1.2
56
+ 1405-06-15,فولاد,covered_call,7000,,7600,356,,,,,,,,,,,,45,7000,160,0.018,0.38,31.2
57
+ 1405-06-15,شپنا,covered_call,9000,,9600,443,,,,,,,,,,,,30,9000,90,0.02,0.38,-6.4
58
+ 1405-06-15,کگل,tabei,,,14210,,57,9800,,,,,,,,,,365,9840,240,0.02,0.38,7.9
59
+ 1405-06-15,خساپا,tabei,,,3000,,14,2500,,,,,,,,,,270,2512,320,0.012,0.38,3.4
60
+ 1405-06-15,شستا,tabei,,,1320,,5,1200,,,,,,,,,,200,1205,400,0.015,0.38,16.3
61
+ 1405-06-15,وبملت,parity,9000,,9000,,,,634,380,,,,,,,0.39,30,9000,80,0.02,0.38,2.6
62
+ 1405-06-15,شپدیس,box,,,,,,,,,87,121,75,163,1200,1500,,45,250000,60,0.025,0.38,6.6
63
+ 1405-06-15,فملی,box,,,,,,,,,87,120,75,163,800,1100,,30,200000,45,0.022,0.38,58.9
64
+ 1405-07-15,اهرم,basis,20000,22792,,,,,,,,,,,,,,90,20000000,900,0.005,0.39,-34.1
65
+ 1405-07-15,طلا,basis,20000,21191,,,,,,,,,,,,,,60,20000000,700,0.006,0.39,23.4
66
+ 1405-07-15,فولاد,covered_call,7000,,7600,337,,,,,,,,,,,,45,7000,160,0.018,0.39,-22.9
67
+ 1405-07-15,شپنا,covered_call,9000,,9600,465,,,,,,,,,,,,30,9000,90,0.02,0.39,36.1
68
+ 1405-07-15,کگل,tabei,,,14210,,30,9800,,,,,,,,,,365,9840,240,0.02,0.39,6.7
69
+ 1405-07-15,خساپا,tabei,,,3000,,15,2500,,,,,,,,,,270,2512,320,0.012,0.39,19.3
70
+ 1405-07-15,شستا,tabei,,,1320,,5,1200,,,,,,,,,,200,1205,400,0.015,0.39,8.0
71
+ 1405-07-15,وبملت,parity,9000,,9000,,,,649,380,,,,,,,0.39,30,9000,80,0.02,0.39,19.9
72
+ 1405-07-15,شپدیس,box,,,,,,,,,87,121,75,163,1200,1500,,45,250000,60,0.025,0.39,-52.6
73
+ 1405-07-15,فملی,box,,,,,,,,,87,121,75,163,800,1100,,30,200000,45,0.022,0.39,-25.5
74
+ 1405-08-15,اهرم,basis,20000,23367,,,,,,,,,,,,,,90,20000000,900,0.005,0.4,29.6
75
+ 1405-08-15,طلا,basis,20000,21616,,,,,,,,,,,,,,60,20000000,700,0.006,0.4,8.0
76
+ 1405-08-15,فولاد,covered_call,7000,,7600,327,,,,,,,,,,,,45,7000,160,0.018,0.4,-50.2
77
+ 1405-08-15,شپنا,covered_call,9000,,9600,459,,,,,,,,,,,,30,9000,90,0.02,0.4,54.5
78
+ 1405-08-15,کگل,tabei,,,14210,,51,9800,,,,,,,,,,365,9840,240,0.02,0.4,52.7
79
+ 1405-08-15,خساپا,tabei,,,3000,,10,2500,,,,,,,,,,270,2512,320,0.012,0.4,29.7
80
+ 1405-08-15,شستا,tabei,,,1320,,5,1200,,,,,,,,,,200,1205,400,0.015,0.4,16.3
81
+ 1405-08-15,وبملت,parity,9000,,9000,,,,684,380,,,,,,,0.39,30,9000,80,0.02,0.4,25.9
82
+ 1405-08-15,شپدیس,box,,,,,,,,,88,121,75,163,1200,1500,,45,250000,60,0.025,0.4,40.8
83
+ 1405-08-15,فملی,box,,,,,,,,,88,122,75,164,800,1100,,30,200000,45,0.022,0.4,-16.3
84
+ 1405-09-15,اهرم,basis,20000,22597,,,,,,,,,,,,,,90,20000000,900,0.005,0.41,14.9
85
+ 1405-09-15,طلا,basis,20000,21307,,,,,,,,,,,,,,60,20000000,700,0.006,0.41,8.0
86
+ 1405-09-15,فولاد,covered_call,7000,,7600,335,,,,,,,,,,,,45,7000,160,0.018,0.41,33.2
87
+ 1405-09-15,شپنا,covered_call,9000,,9600,443,,,,,,,,,,,,30,9000,90,0.02,0.41,23.9
88
+ 1405-09-15,کگل,tabei,,,14210,,38,9800,,,,,,,,,,365,9840,240,0.02,0.41,45.8
89
+ 1405-09-15,خساپا,tabei,,,3000,,15,2500,,,,,,,,,,270,2512,320,0.012,0.41,53.7
90
+ 1405-09-15,شستا,tabei,,,1320,,4,1200,,,,,,,,,,200,1205,400,0.015,0.41,18.9
91
+ 1405-09-15,وبملت,parity,9000,,9000,,,,663,380,,,,,,,0.39,30,9000,80,0.02,0.41,64.2
92
+ 1405-09-15,شپدیس,box,,,,,,,,,87,121,75,163,1200,1500,,45,250000,60,0.025,0.41,-27.3
93
+ 1405-09-15,فملی,box,,,,,,,,,88,121,75,163,800,1100,,30,200000,45,0.022,0.41,40.4
94
+ 1405-10-15,اهرم,basis,20000,23187,,,,,,,,,,,,,,90,20000000,900,0.005,0.42,-35.9
95
+ 1405-10-15,طلا,basis,20000,21401,,,,,,,,,,,,,,60,20000000,700,0.006,0.42,53.5
96
+ 1405-10-15,فولاد,covered_call,7000,,7600,336,,,,,,,,,,,,45,7000,160,0.018,0.42,60.7
97
+ 1405-10-15,شپنا,covered_call,9000,,9600,440,,,,,,,,,,,,30,9000,90,0.02,0.42,8.4
98
+ 1405-10-15,کگل,tabei,,,14210,,36,9800,,,,,,,,,,365,9840,240,0.02,0.42,17.7
99
+ 1405-10-15,خساپا,tabei,,,3000,,14,2500,,,,,,,,,,270,2512,320,0.012,0.42,37.1
100
+ 1405-10-15,شستا,tabei,,,1320,,7,1200,,,,,,,,,,200,1205,400,0.015,0.42,20.6
101
+ 1405-10-15,وبملت,parity,9000,,9000,,,,661,380,,,,,,,0.39,30,9000,80,0.02,0.42,31.6
102
+ 1405-10-15,شپدیس,box,,,,,,,,,88,121,75,163,1200,1500,,45,250000,60,0.025,0.42,74.3
103
+ 1405-10-15,فملی,box,,,,,,,,,87,121,75,163,800,1100,,30,200000,45,0.022,0.42,19.5
station/demo_day.py ADDED
@@ -0,0 +1,567 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env python3
2
+ # -*- coding: utf-8 -*-
3
+ """برگهٔ شاهد زنده — «این عدد را من تایپ نکردم؛ خودِ برنامه از سرویس خواند».
4
+
5
+ مسئله‌ای که حل می‌کند: سرمایه‌گذار (یا کارفرما) به عددهای یک اسلاید اعتماد نمی‌کند. اینجا
6
+ برای هر عددی که برنامه رویش تصمیم می‌گیرد، سه چیز چاپ می‌شود:
7
+
8
+ ۱) نشانی‌ای که همین حالا خوانده شد، و پاسخ خام سرویس (چند بایت اول).
9
+ ۲) اثر انگشت sha256 همان پاسخ خام؛ اگر کسی عدد را دست‌کاری کند، هش عوض می‌شود.
10
+ ۳) ساعت خواندن (UTC) و مدت خواندن؛ یعنی «الان»، نه «چند هفته پیش».
11
+
12
+ بعد از آن، برنامه روی همان عددها یک تصمیم نمونه می‌گیرد و **حساب‌وکتابش را هم می‌نویسد**
13
+ تا با ماشین‌حساب گوشی هم بشود راستی‌آزمایی کرد.
14
+
15
+ هزینه: صفر. با «خوراک آزمایشی محلی» هم کار می‌کند (بدون اینترنت) و با سرویس خریدنی هم.
16
+ صداقت برچسب: اگر نشانی روی همین رایانه باشد، در برگه با حروف درشت نوشته می‌شود که داده
17
+ ساختگی است و شاهد فقط «زنده‌بودن مسیر فنی» را نشان می‌دهد، نه بازار واقعی.
18
+ """
19
+
20
+ from __future__ import annotations
21
+
22
+ import argparse
23
+ import hashlib
24
+ import json
25
+ import sys
26
+ import time
27
+ import urllib.parse
28
+ from datetime import datetime, timezone
29
+ from pathlib import Path
30
+
31
+ BASE = Path(__file__).resolve().parent
32
+ if str(BASE) not in sys.path:
33
+ sys.path.insert(0, str(BASE))
34
+
35
+ import datafeed # noqa: E402
36
+ import connections as conn # noqa: E402
37
+ import investor_test as inv # noqa: E402
38
+ import reportkit as rk # noqa: E402
39
+
40
+ VERSION = "0.1.0"
41
+
42
+ DATA = BASE / "data"
43
+ EXPORT = BASE / "export"
44
+ BASE_SNAPSHOT = (BASE.parent / "desk" / "market-demo.json")
45
+ PAGE = DATA / "witness-live.html"
46
+ MD = DATA / "witness-live.md"
47
+ JSONF = DATA / "witness-live.json"
48
+
49
+ LOCAL_HOSTS = ("127.0.0.1", "localhost", "0.0.0.0", "::1")
50
+
51
+
52
+ def stamps() -> tuple[str, str]:
53
+ now = datetime.now(timezone.utc).replace(microsecond=0)
54
+ return now.isoformat(), now.astimezone().strftime("%Y-%m-%d %H:%M:%S")
55
+
56
+
57
+ def build_url(live_cfg: dict, symbol: str, key: str) -> str:
58
+ """نشانی نهایی یک نماد را می‌سازد (همان کاری که مسیر زندهٔ برنامه می‌کند)."""
59
+ url = str(live_cfg.get("url_template") or "").replace("{symbol}", urllib.parse.quote(symbol))
60
+ if "{key}" in url:
61
+ url = url.replace("{key}", urllib.parse.quote(key or ""))
62
+ return url
63
+
64
+
65
+ def _blank(symbol: str, url: str, error: str) -> dict:
66
+ return {"symbol": symbol, "url": url, "ok": False, "error": error, "sha256": "", "bytes": 0,
67
+ "latency_ms": None, "price": None, "fetched_at": stamps()[0], "snippet": "", "source": ""}
68
+
69
+
70
+ def probe(profile: dict, symbols: list[str], *, timeout: float = 8.0, key: str = "") -> list[dict]:
71
+ """قیمت هر نماد را زنده می‌خواند (بدون حافظهٔ نهان) و شاهد خامش را برمی‌گرداند."""
72
+ cfg = conn.live_config(profile)
73
+ if not key:
74
+ key, _where = conn.resolve_key(profile)
75
+ out: list[dict] = []
76
+ for symbol in symbols:
77
+ url = build_url(cfg, symbol, key)
78
+ if not url:
79
+ out.append(_blank(symbol, "", "قالب نشانی خالی است"))
80
+ continue
81
+ t0 = time.time()
82
+ text, status = datafeed.fetch(url, timeout=timeout, retries=0,
83
+ key_header=str(cfg.get("key_header") or ""), key=key,
84
+ cache_name=None, use_cache=False, stale_ok=False)
85
+ latency = int(round((time.time() - t0) * 1000))
86
+ utc, _local = stamps()
87
+ source = ("خوراک آزمایشی محلی (ساختگی)" if any(h in url for h in LOCAL_HOSTS)
88
+ else "دادهٔ زندهٔ وب‌سرویس")
89
+ record = _blank(symbol, url, "")
90
+ record.update({"fetched_at": utc, "latency_ms": latency, "source": source})
91
+ if not text:
92
+ record["error"] = status
93
+ out.append(record)
94
+ continue
95
+ record["sha256"] = hashlib.sha256(text.encode("utf-8")).hexdigest()
96
+ record["bytes"] = len(text.encode("utf-8"))
97
+ record["snippet"] = " ".join(text.split())[:400]
98
+ value, why = datafeed.parse_quote_payload(text, str(cfg.get("json_path") or ""), symbol)
99
+ if value is None:
100
+ record["error"] = f"عدد قیمت خوانده نشد ({why})"
101
+ else:
102
+ record["ok"] = True
103
+ record["price"] = float(value)
104
+ record["status_text"] = status
105
+ out.append(record)
106
+ return out
107
+
108
+
109
+ def symbols_of(path: Path | str = BASE_SNAPSHOT) -> list[str]:
110
+ """نمادهای پروندهٔ پایه — همان ردیف‌هایی که برنامه رویشان تصمیم می‌گیرد."""
111
+ try:
112
+ snap = datafeed.load_snapshot_file(path)
113
+ except Exception:
114
+ return []
115
+ seen, out = set(), []
116
+ for row in snap.rows:
117
+ name = str(row.get("symbol") or "").strip()
118
+ if name and name not in seen:
119
+ seen.add(name)
120
+ out.append(name)
121
+ return out
122
+
123
+
124
+ def decide(probes: list[dict], *, path: Path | str = BASE_SNAPSHOT, rules: dict | None = None) -> dict:
125
+ """عددهای زنده را روی ردیف‌های پروندهٔ پایه می‌نشاند و بهترین ردیف را کامل باز می‌کند.
126
+
127
+ عمداً همان تابع‌های خودِ ایستگاه صدا زده می‌شوند (`datafeed.finish_live`، `investor_test.solve`،
128
+ `investor_test.ladder_for`) تا عددی که در برگهٔ شاهد چاپ می‌شود، همان عددی باشد که برنامه
129
+ رویش تصمیم می‌گیرد — نه حساب‌وکتاب دومِ جداگانه.
130
+ """
131
+ out: dict = {"ready": False, "reason": "", "chosen": None, "others": [],
132
+ "snapshot": {}, "live_inputs": [], "file_path": str(path)}
133
+ try:
134
+ snap = datafeed.load_snapshot_file(path)
135
+ except Exception as e: # پروندهٔ پایه نبود → باید صریح گفته شود، نه سکوت
136
+ out["reason"] = f"پروندهٔ پایهٔ ردیف‌ها خوانده نشد: {type(e).__name__}"
137
+ return out
138
+ if not getattr(snap, "rows", None):
139
+ out["reason"] = f"پروندهٔ پایهٔ ردیف‌ها خوانده نشد یا خالی است: {path}"
140
+ return out
141
+ prices = {p["symbol"]: p["price"] for p in probes if p.get("ok") and p.get("price") is not None}
142
+ fails = len([p for p in probes if not p.get("ok")])
143
+ sources = {p.get("source", "") for p in probes if p.get("ok")}
144
+ if sources:
145
+ snap.source_label = sorted(sources)[0]
146
+ snap.mode = "live"
147
+ snap = datafeed.finish_live(snap, prices, stale_count=0, fail_count=fails)
148
+ out["snapshot"] = {"status": snap.status, "source_label": snap.source_label,
149
+ "messages": list(snap.messages), "rows": len(snap.rows),
150
+ "as_of": getattr(snap, "as_of", ""), "mode": snap.mode,
151
+ "freshness_seconds": snap.freshness_seconds,
152
+ "file": str(path), "file_date": str(getattr(snap, "as_of", "") or "")}
153
+ out["live_inputs"] = [{"symbol": p["symbol"], "price": p["price"], "sha256": p["sha256"],
154
+ "latency_ms": p["latency_ms"]} for p in probes if p.get("ok")]
155
+ out["live"] = bool(prices)
156
+ if not prices:
157
+ # بدون قیمت زنده، برگهٔ شاهد «شاهد» نیست؛ عددهای پروندهٔ پایه را به اسم تصمیم امروز نمی‌فروشیم.
158
+ out["reason"] = ("هیچ قیمتی از سرویس نیامد؛ پس این اجرا «زنده» نیست و تصمیم نمونه ساخته "
159
+ "نشد. علت هر نماد در جدول آمده است.")
160
+ return out
161
+ rows = [r for r in snap.rows if r.get("kind")]
162
+ if not rows:
163
+ out["reason"] = "هیچ ردیفی با «راهبرد» در پروندهٔ پایه نبود؛ راهبردها را در جدول پر کنید."
164
+ return out
165
+ scored = []
166
+ for row in rows:
167
+ try:
168
+ solved = inv.solve(row)
169
+ ladder = inv.ladder_for(row)
170
+ except Exception as e:
171
+ scored.append({"symbol": str(row.get("symbol", "")), "kind": str(row.get("kind", "")),
172
+ "error": f"{type(e).__name__}: {e}"})
173
+ continue
174
+ scored.append({"symbol": str(row.get("symbol", "")), "kind": str(row.get("kind", "")),
175
+ "row": dict(row), "title": solved.get("title", ""), "answer": solved.get("answer"),
176
+ "answer_num": solved.get("answer_num"), "unit": solved.get("unit", ""),
177
+ "given": solved.get("given", []), "checks": solved.get("checks", []),
178
+ "steps": solved.get("steps", []), "extras": solved.get("extras"),
179
+ "formula": solved.get("formula", ""), "hurdle_pct": ladder.get("hurdle_pct"),
180
+ "margin_pp": ladder.get("margin_pp"), "fees_pct": ladder.get("fees_pct"),
181
+ "verdict": ladder.get("verdict", ""), "why": ladder.get("why", ""),
182
+ "survives": ladder.get("survives"), "ladder": ladder.get("ladder", [])})
183
+ ranked = [s for s in scored if isinstance(s.get("answer_num"), (int, float))]
184
+ if not ranked:
185
+ out["reason"] = "هیچ ردیفی عدد قابل‌محاسبه نداد؛ اعداد پروندهٔ پایه را بازبینی کنید."
186
+ out["others"] = scored
187
+ return out
188
+ ranked.sort(key=lambda s: -float(s["answer_num"]))
189
+ live_rows = [s for s in ranked
190
+ if str(s["row"].get("symbol", "")) in prices
191
+ and any(s["row"].get(f"{f}_manual") is not None for f in ("spot", "stock_price"))]
192
+ if live_rows: # ردیفی که واقعاً قیمت زنده گرفت، بر ردیف پرونده‌ای مقدم است
193
+ pick_from = live_rows
194
+ scope = "ردیف‌هایی که قیمت زنده گرفتند"
195
+ else:
196
+ pick_from = ranked
197
+ scope = "همهٔ ردیف‌ها (هیچ ردیفی قیمت زنده نگرفت)"
198
+ chosen = pick_from[0]
199
+ chosen["provenance"] = provenance_of(chosen, prices, path)
200
+ others = [s for s in ranked if s is not chosen]
201
+ for other in others:
202
+ other["provenance"] = provenance_of(other, prices, path)
203
+ out.update({"ready": True, "chosen": chosen, "others": others, "reason": "",
204
+ "rank_scope": scope, "live_symbols": sorted(prices)})
205
+ return out
206
+
207
+
208
+ FIELD_LABELS = (("spot", "قیمت نقدی"), ("stock_price", "قیمت سهم"), ("future", "قیمت آتی"),
209
+ ("strike", "قیمت اعمال"), ("strike_low", "اعمال پایین"), ("strike_high", "اعمال بالا"),
210
+ ("premium", "پرمیوم"), ("put_price", "پرمیوم پوت"), ("put", "پرمیوم پوت"),
211
+ ("call", "پرمیوم کال"), ("call_low", "کال پایین"), ("call_high", "کال بالا"),
212
+ ("put_low", "پوت پایین"), ("put_high", "پوت بالا"),
213
+ ("days", "روز تا سررسید"), ("margin_per_contract", "وجه تضمین هر قرارداد"))
214
+
215
+
216
+ def provenance_of(chosen: dict, prices: dict, path: Path | str) -> list[dict]:
217
+ """هر عدد ورودی از کجا آمد: سرویس زنده، پروندهٔ پایه، یا قاعدهٔ برنامه؟ (شفافیت کامل)"""
218
+ row = chosen.get("row") or {}
219
+ out: list[dict] = []
220
+ for field, label in FIELD_LABELS:
221
+ if field not in row or not isinstance(row.get(field), (int, float)):
222
+ continue
223
+ live = row.get(f"{field}_manual") is not None
224
+ out.append({"label": label, "field": field, "value": row[field],
225
+ "source": "زنده از سرویس" if live else "از پروندهٔ پایه",
226
+ "detail": (f"قیمت پیش از به‌روزشدن در پرونده: {row[f'{field}_manual']:,.2f}"
227
+ if live else Path(path).name)})
228
+ if isinstance(row.get("hurdle"), (int, float)):
229
+ out.append({"label": "نرخ سد", "field": "hurdle", "value": row["hurdle"],
230
+ "source": "قاعدهٔ برنامه", "detail": "در گام ۱ قابل تغییر است"})
231
+ return out
232
+
233
+
234
+ def mixed_sources_note(chosen: dict, live_symbols=None) -> str:
235
+ """شفاف‌سازی صریح: چه چیزی زنده آمد، چه چیزی از پرونده آمد، و کدام عدد در تصمیم به‌کار رفت."""
236
+ prov = chosen.get("provenance") or []
237
+ live = [x for x in prov if x["source"] == "زنده از سرویس"]
238
+ filed = [x for x in prov if x["source"] == "از پروندهٔ پایه"]
239
+ read_live = bool(live_symbols) if live_symbols is not None else bool(live)
240
+ if not read_live:
241
+ return "هیچ قیمتی از سرویس نیامد؛ پس این اجرا «زنده» نیست و به عددهایش استناد نکنید."
242
+ if not live:
243
+ return ("قیمت‌های زنده خوانده شد، ولی ردیف برگزیده («" + str(chosen.get("symbol", "")) +
244
+ "» · " + str(chosen.get("kind", "")) + ") هیچ قیمت زنده‌ای را در محاسبه به کار نمی‌برد؛ "
245
+ "همهٔ عددهایش از پروندهٔ پایهٔ شماست. برای زنده‌شدن همین ردیف، قیمت‌های همان نماد "
246
+ "هم باید از سرویس یا تابلوی کارگزار بیایند — وگرنه این عدد «فرصت امروز» نیست.")
247
+ if filed:
248
+ return ("توجه: بخشی از عددهای این ردیف از پروندهٔ پایهٔ خودتان آمده است ("
249
+ + "، ".join(x["label"] for x in filed)
250
+ + "). یعنی این عدد «آزمون زندهٔ قیمت پایه» است، نه یک فرصت معاملاتی امروز. "
251
+ "برای فرصت واقعی، قیمت هر دو سر معامله باید امروز از سرویس یا از تابلوی "
252
+ "کارگزاری بیاید.")
253
+ return "همهٔ عددهای این ردیف همین حالا از سرویس خوانده شد و هیچ عددی از پرونده به کار نرفت."
254
+
255
+
256
+ def limits_of(doc: dict) -> list[str]:
257
+ out = ["سودآوری را اثبات نمی‌کند؛ فقط نشان می‌دهد عددهای همین تصمیم از سرویس خوانده شده‌اند.",
258
+ "قیمت لحظهٔ خواندن است؛ قیمت اجرای سفارش شما در کارگزار فری دارد و با آن فرق می‌کند.",
259
+ "وجه تضمین را کارگزاری تعیین می‌کند؛ عدد این برگه از کارگزاری نیست.",
260
+ "مشخصات قرارداد (قیمت اعمال، سررسید) از پروندهٔ پایهٔ خودتان خوانده شده، نه از سرویس."]
261
+ if any(p.get("source", "").startswith("خوراک آزمایشی") for p in doc["probes"]):
262
+ out.insert(0, "این اجرا روی «خوراک آزمایشی محلی» بوده؛ یعنی داده ساختگی است و برگه فقط "
263
+ "زنده‌بودن مسیر فنی (خواندن، هش، تصمیم) را نشان می‌دهد، نه بازار واقعی.")
264
+ if any(not p.get("ok") for p in doc["probes"]):
265
+ out.insert(0, "بعضی نمادها خوانده نشد؛ علت هرکدام در جدول آمده است.")
266
+ if any(c.get("error") for c in [doc["decision"].get("chosen") or {}]):
267
+ out.insert(0, "برای ردیف انتخابی، محاسبه کامل نشد؛ متن خطا در برگه آمده است.")
268
+ return out
269
+
270
+
271
+ def build(*, symbols: list[str] | None = None, timeout: float = 8.0, profile: dict | None = None,
272
+ key: str = "", path: Path | str = BASE_SNAPSHOT, write: bool = True,
273
+ page: Path | str | None = None, md: Path | str | None = None,
274
+ json_path: Path | str | None = None) -> dict:
275
+ """برگهٔ شاهد را می‌سازد (و ذخیره می‌کند)."""
276
+ active = conn.active_or_none()
277
+ prof = profile or (active or {}).get("profile") or {}
278
+ if not prof:
279
+ prof = {"name": "custom", "label": "اتصال دلخواه (چیزی انتخاب نشده)", "cost": "",
280
+ "url_template": "", "json_path": ""}
281
+ key_where = "کادر همین لحظه" if key else (active or {}).get("key_where", "بدون کلید")
282
+ names = [s for s in (symbols or []) if s] or symbols_of(path)
283
+ utc, local = stamps()
284
+ probes = probe(prof, names, timeout=timeout, key=key)
285
+ doc = {
286
+ "version": VERSION,
287
+ "built_at_utc": utc,
288
+ "built_at_local": local,
289
+ "connection": {"name": prof.get("name", ""), "label": prof.get("label", ""),
290
+ "cost": prof.get("cost", ""), "key_where": key_where,
291
+ "url_template": prof.get("url_template", ""),
292
+ "json_path": prof.get("json_path", "")},
293
+ "probes": probes,
294
+ }
295
+ doc["decision"] = decide(probes, path=path)
296
+ doc["decision"]["mixed_note"] = (
297
+ mixed_sources_note(doc["decision"]["chosen"],
298
+ doc["decision"].get("live_symbols") or [])
299
+ if doc["decision"].get("chosen") else "")
300
+ doc["limits"] = limits_of(doc)
301
+ core = json.dumps({"probes": probes, "decision": doc["decision"]}, sort_keys=True,
302
+ ensure_ascii=False)
303
+ doc["page_hash"] = hashlib.sha256(core.encode("utf-8")).hexdigest()[:16]
304
+ doc["text"] = text_of(doc)
305
+ if write:
306
+ for target, content in ((page or PAGE, _page(doc)), (md or MD, doc["text"]),
307
+ (json_path or JSONF, json.dumps(doc, ensure_ascii=False, indent=1))):
308
+ pth = Path(target)
309
+ pth.parent.mkdir(parents=True, exist_ok=True)
310
+ pth.write_text(content, encoding="utf-8")
311
+ doc.update({"page": str(page or PAGE), "md": str(md or MD), "json": str(json_path or JSONF)})
312
+ return doc
313
+
314
+
315
+ def text_of(doc: dict) -> str:
316
+ d = doc["decision"]
317
+ L = [f"# برگهٔ شاهد زندهٔ داده — نسخهٔ {VERSION}", "",
318
+ f"ساعت خواندن: {doc['built_at_local']} (UTC: {doc['built_at_utc']})",
319
+ f"اتصال فعال: {doc['connection']['label']} ({doc['connection']['cost']}) — کلید: {doc['connection']['key_where']}",
320
+ f"قالب نشانی: `{doc['connection']['url_template'] or '—'}`", ""]
321
+ L += ["## ۱. عددهایی که همین حالا خوانده شد", "",
322
+ "| نماد | قیمت | منبع | بایت | اثر انگشت پاسخ خام | تأخیر | وضعیت |",
323
+ "| --- | --- | --- | --- | --- | --- | --- |"]
324
+ for p in doc["probes"]:
325
+ price = f"{p['price']:,.4f}" if p.get("price") is not None else "—"
326
+ state = "خوانده شد ✅" if p.get("ok") else f"نشد ❌ {p.get('error', '')}"
327
+ L.append(f"| {p['symbol']} | {price} | {p.get('source', '')} | {p.get('bytes', 0)} | "
328
+ f"`{p.get('sha256', '')[:16]}` | {p.get('latency_ms', '—')} ms | {state} |")
329
+ L += ["", "نشانی‌های خوانده‌شده:"] + [f"- {p['symbol']}: `{p['url']}`" for p in doc["probes"]]
330
+ L += ["", "## ۲. تصمیمی که از همین عددها درآمد", ""]
331
+ if d.get("ready"):
332
+ s = d["chosen"]
333
+ L += [f"- عکس زندهٔ بازار: {d['snapshot']['status']} · منبع: {d['snapshot']['source_label']}",
334
+ f"- ردیف انتخابی (بالاترین بازده): **{s['symbol']}** · {s['kind']} — {s['title']}",
335
+ f"- قیمت‌هایی که زنده خوانده شد: {'، '.join(d.get('live_symbols') or []) or '—'}",
336
+ f"- دامنهٔ رتبه‌بندی: {d.get('rank_scope', '—')}"]
337
+ if s.get("given"):
338
+ L += ["- عددهای ورودی: " + " · ".join(f"{g[0]} {g[1]}" for g in s["given"])]
339
+ for g in d["live_inputs"]:
340
+ L += [f" - {g['symbol']}: {g['price']:,.4f} (هش `{g['sha256'][:16]}` · {g['latency_ms']} ms)"]
341
+ L += ["", f"**پاسخ: {s.get('answer')} {s.get('unit', '')}**", ""]
342
+ if s.get("checks"):
343
+ L += ["سنجش دو-روشی (هر سطر باید «می‌خواند» باشد):"]
344
+ L += [f"- {c.get('note', '')}: `{c.get('value')}` — "
345
+ f"{'می‌خواند ✅' if c.get('agree') else 'نمی‌خواند ❌'}" for c in s["checks"]]
346
+ if s.get("steps"):
347
+ L += ["", "مسیر محاسبه (قابل بازتولید با ماشین‌حساب):"]
348
+ L += [f"- {st}" for st in s["steps"]]
349
+ if d.get("mixed_note"):
350
+ L += ["", "> **" + d["mixed_note"] + "**", ""]
351
+ if s.get("provenance"):
352
+ L += ["", "هر عدد از کجا آمد:", "",
353
+ "| عدد | مقدار | از کجا | توضیح |", "| --- | --- | --- | --- |"]
354
+ for pr in s["provenance"]:
355
+ val = f"{pr['value']:,.4f}".rstrip("0").rstrip(".") if isinstance(pr["value"], float) \
356
+ else f"{pr['value']:,}"
357
+ L.append(f"| {pr['label']} | {val} | {pr['source']} | {pr['detail']} |")
358
+ if s.get("ladder"):
359
+ L += ["", "پلهٔ خروج — «کِی بفروشم، کِی می‌افتد»:", "",
360
+ "| حد | کِی | روی چه قیمتی | کار |", "| --- | --- | --- | --- |"]
361
+ for item in s["ladder"]:
362
+ price = item.get("price")
363
+ price_txt = f"{price:,.3f}" if isinstance(price, (int, float)) else str(price)
364
+ L.append(f"| {item.get('label', '')} | {item.get('when', '')} | {price_txt} | "
365
+ f"{item.get('action', '')} |")
366
+ for key, label in (("verdict", "داوری"), ("why", "چرا"), ("fees_pct", "کارمزد لحاظ‌شده (٪)"),
367
+ ("hurdle_pct", "نرخ سد (٪)"), ("margin_pp", "حاشیه روی سد (واحد درصد)")):
368
+ if s.get(key) not in (None, ""):
369
+ L.append(f"- {label}: {s[key]}")
370
+ if d.get("others"):
371
+ L += ["", "سایر ردیف‌ها:", "",
372
+ "| نماد | راهبرد | پاسخ |", "| --- | --- | --- |"]
373
+ for o in d["others"]:
374
+ L.append(f"| {o.get('symbol','')} | {o.get('kind','')} | "
375
+ f"{o.get('answer','—')} {o.get('unit','')} |")
376
+ else:
377
+ L.append(f"- تصمیم نمونه ساخته نشد: {d.get('reason', '')}")
378
+ L += ["", f"اثر انگشت کل برگه: `{doc['page_hash']}`", "",
379
+ "## ۳. راستی‌آزمایی مستقل", "",
380
+ "۱) همان نشانی را در مرورگر باز کنید و عدد را ببینید. ۲) پاسخ خام بالا را با ماشین‌حساب "
381
+ "بشمارید. ۳) اثر انگشت این برگه را با `data/witness-live.json` بسنجید.", "",
382
+ "## ۴. این برگه چه چیزی را اثبات نمی‌کند", ""]
383
+ L += [f"- {x}" for x in doc["limits"]]
384
+ L += ["", "---", "",
385
+ "✍️ تهیه‌کنندهٔ جزوات: **Masoud Mojarabian** · 📱 +989126630554 · "
386
+ "✈️ Telegram: [Mojarabian](https://t.me/Mojarabian) · "
387
+ "📸 Instagram: [Mojarabian.Art](https://instagram.com/Mojarabian.Art)"]
388
+ return "\n".join(L)
389
+
390
+
391
+ def _page(doc: dict) -> str:
392
+ c, d = doc["connection"], doc["decision"]
393
+ mock = any(p.get("source", "").startswith("خوراک آزمایشی") for p in doc["probes"])
394
+ head = [f'<div class="honest"><b>این برگه با همین ساعت ساخته شده.</b> برای هر عدد، نشانی و '
395
+ f'اثر انگشت پاسخ خام سرویس چاپ شده تا خودتان راستی‌آزمایی کنید. '
396
+ f'{rk.esc(doc["built_at_local"])} (UTC: <code>{rk.esc(doc["built_at_utc"])}</code>)</div>']
397
+ if mock:
398
+ head.append('<div class="warnbox"><b>توجه: این اجرا روی خوراک آزمایشی محلی است؛ داده ساختگی '
399
+ 'است.</b> برگه فقط نشان می‌دهد که مسیر «خواندن از سرویس ← هش ← تصمیم» زنده کار '
400
+ 'می‌کند. برای عدد بازار واقعی، پروفایل سرویس واقعی را انتخاب کنید.</div>')
401
+ head.append(f'<p class="sub">اتصال فعال: <b>{rk.esc(c["label"])}</b> · هزینه: {rk.esc(c["cost"])} · '
402
+ f'کلید: {rk.esc(c["key_where"])} · مسیر عدد در پاسخ: <code>{rk.esc(c["json_path"] or "—")}</code></p>')
403
+ rows = []
404
+ for p in doc["probes"]:
405
+ if p.get("ok"):
406
+ price, state = rk.num(p["price"], 4), '<span class="ok">خوانده شد ✅</span>'
407
+ else:
408
+ price = "—"
409
+ state = ('<span class="bad">نشد ❌</span><br>'
410
+ f'<span class="hint">{rk.esc(p.get("error", ""))}</span>')
411
+ rows.append(f'<tr><td>{rk.esc(p["symbol"])}</td><td class="num">{price}</td>'
412
+ f'<td>{rk.esc(p.get("source", ""))}</td><td class="num">{p.get("bytes", 0)}</td>'
413
+ f'<td class="num"><code>{rk.esc(p.get("sha256", "")[:16])}</code></td>'
414
+ f'<td class="num">{p.get("latency_ms", "—")}</td><td>{state}</td></tr>')
415
+ table = ('<table><thead><tr><th>نماد</th><th class="num">قیمت</th><th>منبع</th>'
416
+ '<th class="num">بایت</th><th class="num">اثر انگشت پاسخ</th>'
417
+ '<th class="num">تأخیر (ms)</th><th>وضعیت</th></tr></thead><tbody>'
418
+ + "".join(rows) + "</tbody></table>")
419
+ raws = "".join(f'<p class="sub"><b>{rk.esc(p["symbol"])}</b> — <code>{rk.esc(p["url"])}</code></p>'
420
+ f'<pre>{rk.esc(p["snippet"])}</pre>' for p in doc["probes"] if p.get("snippet"))
421
+ if d.get("ready"):
422
+ s = d["chosen"]
423
+ block = ['<table><tbody>',
424
+ f'<tr><td>عکس زندهٔ بازار</td><td>{rk.esc(d["snapshot"]["status"])} · '
425
+ f'{rk.esc(d["snapshot"]["source_label"])}</td></tr>',
426
+ f'<tr><td>ردیف انتخابی (بالاترین بازده)</td><td><b>{rk.esc(s["symbol"])}</b> · '
427
+ f'<code>{rk.esc(s["kind"])}</code> — {rk.esc(s.get("title", ""))}</td></tr>']
428
+ if s.get("given"):
429
+ block.append('<tr><td>عددهای ورودی</td><td class="num">'
430
+ + " · ".join(f'{rk.esc(g[0])} {rk.esc(g[1])}' for g in s["given"])
431
+ + '</td></tr>')
432
+ for g in d["live_inputs"]:
433
+ block.append(f'<tr><td>قیمت زندهٔ {rk.esc(g["symbol"])}</td>'
434
+ f'<td class="num">{rk.num(g["price"], 4)} '
435
+ f'<span class="hint">(هش <code>{rk.esc(g["sha256"][:16])}</code> · '
436
+ f'{g["latency_ms"]} ms)</span></td></tr>')
437
+ block.append(f'<tr><td><b>پاسخ</b></td><td class="num"><b>{rk.esc(s.get("answer"))}</b> '
438
+ f'{rk.esc(s.get("unit", ""))}</td></tr>')
439
+ for key, label in (("verdict", "داوری"), ("fees_pct", "کارمزد لحاظ‌شده (٪)"),
440
+ ("hurdle_pct", "نرخ سد (٪)"), ("margin_pp", "حاشیه روی سد (واحد درصد)")):
441
+ if s.get(key) not in (None, ""):
442
+ val = rk.num(s[key], 3) if isinstance(s[key], (int, float)) else rk.esc(s[key])
443
+ block.append(f'<tr><td>{rk.esc(label)}</td><td class="num">{val}</td></tr>')
444
+ block.append('</tbody></table>')
445
+ checks = ""
446
+ if s.get("checks"):
447
+ checks = ("<h3>سنجش دو-روشی</h3><ul>" + "".join(
448
+ f'<li>{rk.esc(c.get("note", ""))}: <code>{rk.esc(c.get("value"))}</code> — '
449
+ f'{"می‌خواند ✅" if c.get("agree") else "نمی‌خواند ❌"}</li>' for c in s["checks"])
450
+ + "</ul>")
451
+ steps = ""
452
+ if s.get("steps"):
453
+ steps = ("<h3>مسیر محاسبه (با ماشین‌حساب هم می‌شود بازتولید کرد)</h3><ol>"
454
+ + "".join(f"<li>{rk.esc(x)}</li>" for x in s["steps"]) + "</ol>")
455
+ prov = ""
456
+ if s.get("provenance"):
457
+ prows = []
458
+ for pr in s["provenance"]:
459
+ val = (rk.num(pr["value"], 4) if isinstance(pr["value"], float)
460
+ else f"{pr['value']:,}")
461
+ cls = "ok" if pr["source"] == "زنده از سرویس" else "hint"
462
+ prows.append(f'<tr><td>{rk.esc(pr["label"])}</td><td class="num">{val}</td>'
463
+ f'<td><span class="{cls}">{rk.esc(pr["source"])}</span></td>'
464
+ f'<td><span class="hint">{rk.esc(pr["detail"])}</span></td></tr>')
465
+ prov = ('<h3>هر عدد از کجا آمد</h3><table><thead><tr><th>عدد</th><th class="num">مقدار</th>'
466
+ '<th>از کجا</th><th>توضیح</th></tr></thead><tbody>' + "".join(prows) + "</tbody></table>")
467
+ ladder = ""
468
+ if s.get("ladder"):
469
+ lrows = []
470
+ for item in s["ladder"]:
471
+ price = item.get("price")
472
+ price_txt = (f"{price:,.3f}" if isinstance(price, (int, float)) else str(price))
473
+ lrows.append(f'<tr><td>{rk.esc(item.get("label", ""))}</td>'
474
+ f'<td>{rk.esc(item.get("when", ""))}</td>'
475
+ f'<td class="num">{rk.esc(price_txt)}</td>'
476
+ f'<td>{rk.esc(item.get("action", ""))}</td></tr>')
477
+ ladder = ('<h3>پلهٔ خروج — «کِی بفروشم، کِی می‌افتد»</h3><table><thead><tr><th>حد</th>'
478
+ '<th>کِی</th><th class="num">روی چه قیمتی</th><th>کار</th></tr></thead><tbody>'
479
+ + "".join(lrows) + "</tbody></table>")
480
+ others = ""
481
+ if d.get("others"):
482
+ orows = "".join(f'<tr><td>{rk.esc(o.get("symbol", ""))}</td>'
483
+ f'<td>{rk.esc(o.get("kind", ""))}</td>'
484
+ f'<td class="num">{rk.esc(str(o.get("answer", "—")))} '
485
+ f'{rk.esc(o.get("unit", ""))}</td></tr>' for o in d["others"])
486
+ others = ('<h3>سایر ردیف‌ها</h3><table><thead><tr><th>نماد</th><th>راهبرد</th>'
487
+ '<th class="num">پاسخ</th></tr></thead><tbody>' + orows + "</tbody></table>")
488
+ if d.get("mixed_note"):
489
+ block.insert(0, f'<div class="warnbox"><b>{rk.esc(d["mixed_note"])}</b></div>')
490
+ dec_body = "".join(block) + prov + checks + steps + ladder + others
491
+ if s.get("why"):
492
+ dec_body += f'<p class="note">{rk.esc(s["why"])}</p>'
493
+ else:
494
+ dec_body = f'<p class="warn">{rk.esc(d.get("reason", ""))}</p>'
495
+
496
+ limits = "".join(f"<li>{rk.esc(x)}</li>" for x in doc["limits"])
497
+ body = "".join(head + [
498
+ "<h2>۱. عددهایی که همین حالا خوانده شد</h2>", table,
499
+ "<h3>پاسخ خام سرویس (برای راستی‌آزمایی)</h3>",
500
+ raws or '<p class="hint">پاسخی ثبت نشد.</p>',
501
+ "<h2>۲. تصمیمی که از همین عددها درآمد</h2>", dec_body,
502
+ "<h2>۳. راستی‌آزمایی مستقل</h2>",
503
+ '<p class="note">سه راه برای اینکه به حرف برنامه اعتماد نکنید و خودتان بسنجید: '
504
+ '۱) همان نشانی را در مرورگر باز کنید و عدد را ببینید. ۲) پاسخ خام بالا را با ماشین‌حساب '
505
+ 'بشمارید. ۳) اثر انگشت این برگه را با پروندهٔ <code>data/witness-live.json</code> بسنجید.</p>',
506
+ f'<p class="sub">اثر انگشت برگه: <code>{rk.esc(doc["page_hash"])}</code></p>',
507
+ "<h2>۴. این برگه چه چیزی را اثبات نمی‌کند</h2>", f"<ul>{limits}</ul>",
508
+ '<p class="sub">نسخهٔ ' + VERSION + ' · ✍️ تهیه‌کنندهٔ جزوات: <b>Masoud Mojarabian</b> · '
509
+ '📱 +989126630554 · ✈️ <a href="https://t.me/Mojarabian">Telegram: Mojarabian</a> · '
510
+ '📸 <a href="https://instagram.com/Mojarabian.Art">Instagram: Mojarabian.Art</a></p>',
511
+ ])
512
+ ok = sum(1 for p in doc["probes"] if p.get("ok"))
513
+ return rk.page("برگهٔ شاهد زندهٔ داده", body,
514
+ subtitle=f"خوانده‌شده از سرویس در {doc['built_at_local']} · "
515
+ f"{ok} از {len(doc['probes'])} نماد")
516
+
517
+
518
+ def summary_line(doc: dict) -> str:
519
+ ok = [p for p in doc["probes"] if p.get("ok")]
520
+ d = doc["decision"]
521
+ line = f"{len(ok)} از {len(doc['probes'])} قیمت زنده خوانده شد"
522
+ if d.get("ready"):
523
+ s = d["chosen"]
524
+ line += f" · ردیف برگزیده {s.get('symbol', '')} ({s.get('kind', '')})"
525
+ if s.get("answer") is not None:
526
+ line += f": {s.get('answer')} {s.get('unit', '')}"
527
+ if s.get("verdict"):
528
+ line += f" · {s['verdict'][:60]}"
529
+ else:
530
+ line += f" · تصمیم نمونه ساخته نشد: {d.get('reason', '')}"
531
+ return line
532
+
533
+
534
+ def main(argv: list[str] | None = None) -> int:
535
+ ap = argparse.ArgumentParser(description="برگهٔ شاهد زندهٔ داده (خواندن + هش + تصمیم نمونه)")
536
+ ap.add_argument("--symbols", default="", help="نمادها با کاما (پیش‌فرض: نمادهای پروندهٔ پایه)")
537
+ ap.add_argument("--file", default=str(BASE_SNAPSHOT), help="پروندهٔ پایهٔ ردیف‌ها")
538
+ ap.add_argument("--timeout", type=float, default=8.0)
539
+ ap.add_argument("--json", action="store_true")
540
+ ap.add_argument("--quiet", action="store_true")
541
+ ap.add_argument("--out", default="", help="پوشهٔ خروجی (پیش‌فرض: data/)")
542
+ a = ap.parse_args(argv)
543
+ symbols = [s.strip() for s in a.symbols.split(",") if s.strip()]
544
+ out = Path(a.out) if a.out else None
545
+ doc = build(symbols=symbols, timeout=a.timeout, path=a.file,
546
+ page=(out / "witness-live.html") if out else None,
547
+ md=(out / "witness-live.md") if out else None,
548
+ json_path=(out / "witness-live.json") if out else None)
549
+ if a.json:
550
+ print(json.dumps(doc, ensure_ascii=False, indent=1))
551
+ return 0
552
+ if not a.quiet:
553
+ print(summary_line(doc))
554
+ for p in doc["probes"]:
555
+ if p.get("ok"):
556
+ print(f" · {p['symbol']}: {p['price']:,.4f} (هش {p['sha256'][:12]} · "
557
+ f"{p['latency_ms']} ms · {p['source']})")
558
+ else:
559
+ print(f" ✗ {p['symbol']}: {p.get('error', '')}")
560
+ print(f" برگه: {doc.get('page')}")
561
+ print(f" نسخهٔ متنی: {doc.get('md')}")
562
+ print(f" اثر انگشت برگه: {doc['page_hash']}")
563
+ return 0 if any(p.get("ok") for p in doc["probes"]) else 1
564
+
565
+
566
+ if __name__ == "__main__":
567
+ raise SystemExit(main())
station/diagnose.py ADDED
@@ -0,0 +1,211 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env python3
2
+ # -*- coding: utf-8 -*-
3
+ """گزارش عیب‌یابی یک‌کلیکی — «پشتیبانی بدون دانش فنی».
4
+
5
+ کسی که این برنامه را ارائه می‌دهد لازم نیست مهندس پشتیبانی باشد. با یک دکمه، همهٔ چیزهایی که
6
+ برای تشخیص لازم است در یک پروندهٔ خوانا جمع می‌شود: نسخه‌ها، سلامت اجزا، وضعیت اجازه‌نامه،
7
+ محل پرونده‌ها، اثر انگشت موتور، وضعیت دفتر، و آخرین خطاها. همان پرونده را برای هر تکنسین یا
8
+ برای ادامهٔ کار در گفتگو بفرستید؛ دیگر لازم نیست چیزی را دستی توضیح دهید.
9
+
10
+ نمونه:
11
+ python diagnose.py # ساخت گزارش و ذخیره در data/diagnostic-report.html
12
+ python diagnose.py --json # خروجی ماشین‌خوان
13
+ python diagnose.py --text # متن ساده برای کپی‌کردن در پیام
14
+ """
15
+ from __future__ import annotations
16
+
17
+ import argparse
18
+ import json
19
+ import platform
20
+ import subprocess
21
+ import sys
22
+ from datetime import datetime, timezone
23
+ from pathlib import Path
24
+
25
+ VERSION = "0.1.0"
26
+ BASE = Path(__file__).resolve().parent
27
+ DATA = BASE / "data"
28
+ REPORT_HTML = DATA / "diagnostic-report.html"
29
+ REPORT_TXT = DATA / "diagnostic-report.txt"
30
+ for p in (str(BASE), str((BASE.parent / "desk").resolve())):
31
+ if p not in sys.path:
32
+ sys.path.insert(0, p)
33
+
34
+ CREDIT = ("دولوپر: مهندس مسعود مجربیان · تهیه‌کننده: Masoud Mojarabian · https://www.instagram.com/Mojarabian.Art/ · "
35
+ "tel:+989126630554 · https://t.me/Mojarabian")
36
+
37
+
38
+ def _safe(fn, default):
39
+ try:
40
+ return fn()
41
+ except Exception as e: # هر خطایی خودش یک شاهد در گزارش است
42
+ return default if default is not None else {"error": f"{type(e).__name__}: {e}"}
43
+
44
+
45
+ def collect(run_tests: bool = True) -> dict:
46
+ """همهٔ سنجه‌های تشخیصی، بدون هیچ تغییری در داده‌های کار."""
47
+ out: dict = {"ts": datetime.now(timezone.utc).replace(microsecond=0).isoformat(),
48
+ "diagnose_version": VERSION,
49
+ "python": sys.version.split()[0],
50
+ "platform": f"{platform.system()} {platform.release()} ({platform.machine()})"}
51
+ try:
52
+ import station as st
53
+ ok, items = st.health_report()
54
+ out["station_version"] = st.VERSION
55
+ out["health"] = {"ok": ok, "items": [{"name": n, "ok": f, "note": r} for n, f, r in items]}
56
+ except Exception as e:
57
+ out["health"] = {"ok": False, "items": [], "error": f"{type(e).__name__}: {e}"}
58
+
59
+ try:
60
+ import license as licmod # noqa: A004 (نام ماژول خودمان)
61
+ out["license"] = licmod.verify()
62
+ except Exception as e:
63
+ out["license"] = {"state": "نامعلوم", "ok": False, "detail": f"{type(e).__name__}: {e}"}
64
+
65
+ def engine_fp() -> dict:
66
+ import hashlib
67
+ sys.path.insert(0, str((BASE.parent / "tools").resolve()))
68
+ import derivatives_scout as scout # noqa: WPS433
69
+ src = Path(scout.__file__).read_bytes()
70
+ return {"path": str(scout.__file__),
71
+ "sha256_16": hashlib.sha256(src).hexdigest()[:16],
72
+ "version": getattr(scout, "VERSION", "?")}
73
+ out["engine"] = _safe(engine_fp, {})
74
+
75
+ def trial_state() -> dict:
76
+ import daily_trial as dt
77
+ score = dt.scorecard(log_path=DATA / "trial-daily.log")
78
+ return {"days": score.get("days"), "real_days": score.get("real_days"),
79
+ "ready": score.get("ready"), "hash_chain_ok": score.get("chain_ok")}
80
+ out["trial"] = _safe(trial_state, {})
81
+
82
+ def files_state() -> dict:
83
+ rows = []
84
+ for name, path in (("اجازه‌نامه", BASE / "config" / "license.json"),
85
+ ("دفتر اتصال", BASE / "config" / "connections.json"),
86
+ ("کلید ذخیره‌شده", BASE / "config" / "keys.local.json"),
87
+ ("دفتر آزمون", DATA / "trial-daily.log"),
88
+ ("برگهٔ آزمون", DATA / "exam-sheet.html"),
89
+ ("پروندهٔ سرمایه‌گذار", DATA / "investor-dossier.html"),
90
+ ("آخرین بستهٔ شاهد", None)):
91
+ if path is None:
92
+ exports = sorted((BASE / "export").glob("bundle-*"))
93
+ path = exports[-1] if exports else None
94
+ rows.append({"name": name, "path": str(path) if path else "—",
95
+ "exists": bool(path and Path(path).exists()),
96
+ "bytes": Path(path).stat().st_size if path and Path(path).exists() else 0})
97
+ return rows
98
+ out["files"] = _safe(files_state, [])
99
+
100
+ def connections_state() -> dict:
101
+ import connections as conn
102
+ store = conn.load_store()
103
+ active = conn.active_or_none() or {}
104
+ return {"profiles": len(store.get("profiles", [])),
105
+ "active": active.get("name") or "—",
106
+ "active_label": active.get("label") or "—",
107
+ "key_where": active.get("key_where") or "—"}
108
+ out["connections"] = _safe(connections_state, {})
109
+
110
+ def tests_state() -> dict:
111
+ """آزمون‌های واحد را در حالت کوتاه اجرا می‌کند (اگر کند بود، ناموفق گزارش می‌شود)."""
112
+ p = subprocess.run([sys.executable, "-m", "unittest", "discover", "-s", "tests"],
113
+ cwd=str(BASE), capture_output=True, text=True, timeout=600)
114
+ return {"ok": p.returncode == 0, "tail": pick_test_tail(p.stderr)}
115
+ out["tests"] = (_safe(tests_state, {"ok": False, "tail": "اجرا نشد"}) if run_tests
116
+ else {"ok": True, "tail": "اجرا نشد (حالت سریع)"})
117
+ out["ok"] = bool(out["health"].get("ok", False)) and bool(out.get("tests", {}).get("ok"))
118
+ return out
119
+
120
+
121
+ def summary_line(rep: dict) -> str:
122
+ return (f"سلامت: {'سبز' if rep.get('health', {}).get('ok') else 'سرخ'} · "
123
+ f"آزمون‌ها: {'سبز' if rep.get('tests', {}).get('ok') else 'سرخ'} · "
124
+ f"مجوز: {rep.get('license', {}).get('state', '—')} · "
125
+ f"اتصال فعال: {rep.get('connections', {}).get('active', '—')} · "
126
+ f"موتور: {rep.get('engine', {}).get('sha256_16', '—')}")
127
+
128
+
129
+ def pick_test_tail(stderr: str) -> str:
130
+ """از خروجی آزمون‌ها، خط «نتیجه» را برمی‌دارد و هشدارهای بی‌ربط پایان کار را دور می‌ریزد."""
131
+ lines = [ln.strip() for ln in (stderr or "").strip().splitlines() if ln.strip()]
132
+ lines = [ln for ln in lines if "ResourceWarning" not in ln and not ln.startswith("<sys>:")]
133
+ summary = next((ln for ln in reversed(lines) if ln.startswith(("OK", "FAILED"))), None)
134
+ if summary is None:
135
+ summary = lines[-1] if lines else "بی‌پاسخ"
136
+ reds = [ln for ln in lines if ln.startswith(("FAIL:", "ERROR:"))][:4]
137
+ return (" · ".join([summary] + reds) if reds else summary)[:400]
138
+
139
+
140
+ def build_report(rep: dict, path: Path | str = REPORT_HTML) -> tuple[Path, Path]:
141
+ p = Path(path)
142
+ p.parent.mkdir(parents=True, exist_ok=True)
143
+ items = "\n".join(
144
+ f"<tr><td>{i['name']}</td><td>{'✅' if i['ok'] else '❌'}</td><td class='hint'>{i['note']}</td></tr>"
145
+ for i in rep.get("health", {}).get("items", []))
146
+ files = "\n".join(
147
+ f"<tr><td>{f['name']}</td><td>{'✅' if f['exists'] else '—'}</td>"
148
+ f"<td class='hint'>{f['path']}</td><td class='num'>{f['bytes'] or ''}</td></tr>"
149
+ for f in rep.get("files", []))
150
+ html = f"""<!DOCTYPE html>
151
+ <html lang="fa" dir="rtl"><head><meta charset="utf-8"><title>گزارش عیب‌یابی ایستگاه</title>
152
+ <style>
153
+ body{{font-family:Tahoma,system-ui,sans-serif;background:#f6f7fb;color:#151a26;margin:0;padding:26px}}
154
+ .wrap{{max-width:900px;margin:auto;background:#fff;border:1px solid #e3e6ef;border-radius:14px;padding:24px}}
155
+ h1{{font-size:19px;margin:0 0 6px}} h2{{font-size:15px;margin:18px 0 6px}}
156
+ table{{width:100%;border-collapse:collapse}} th,td{{border:1px solid #e3e6ef;padding:6px 9px;font-size:13px;text-align:right}}
157
+ th{{background:#f2f4fa}} .hint{{color:#5b6478;font-size:12px}} .num{{font-variant-numeric:tabular-nums}}
158
+ pre{{background:#f8f9fd;border:1px dashed #ccd3e6;border-radius:8px;padding:10px;font-size:12px;direction:ltr;text-align:left}}
159
+ .foot{{margin-top:16px;border-top:1px solid #e3e6ef;padding-top:8px;color:#5b6478;font-size:12px}}
160
+ </style></head><body><div class="wrap">
161
+ <h1>گزارش عیب‌یابی ایستگاه</h1>
162
+ <p class="hint">{rep.get('ts')} · نسخهٔ گزارش: {rep.get('diagnose_version')} · {rep.get('platform')} · پایتون {rep.get('python')}</p>
163
+ <p><b>{summary_line(rep)}</b></p>
164
+ <h2>سلامت اجزا</h2>
165
+ <table><thead><tr><th>جزء</th><th>وضعیت</th><th>توضیح</th></tr></thead><tbody>{items}</tbody></table>
166
+ <h2>پرونده‌های مهم</h2>
167
+ <table><thead><tr><th>پرونده</th><th>هست؟</th><th>مسیر</th><th>بایت</th></tr></thead><tbody>{files}</tbody></table>
168
+ <h2>اجازه‌نامه و اتصال</h2>
169
+ <pre>{json.dumps({'license': rep.get('license'), 'connections': rep.get('connections'), 'trial': rep.get('trial')}, ensure_ascii=False, indent=1)}</pre>
170
+ <h2>موتور ریاضی</h2>
171
+ <pre>{json.dumps(rep.get('engine'), ensure_ascii=False, indent=1)}</pre>
172
+ <div class="foot">{CREDIT}<br>این گزارش هیچ دادهٔ معاملاتی داخلی را منتقل نمی‌کند؛ فقط وضعیت فنی است.</div>
173
+ </div></body></html>
174
+ """
175
+ txt = (f"گزارش عیب‌یابی ایستگاه\n{rep.get('ts')} · پایتون {rep.get('python')} · {rep.get('platform')}\n"
176
+ f"{summary_line(rep)}\n\n"
177
+ + "\n".join(f"- {i['name']}: {'OK' if i['ok'] else 'FAIL'} · {i['note']}"
178
+ for i in rep.get("health", {}).get("items", []))
179
+ + "\n\n" + json.dumps({"license": rep.get("license"), "connections": rep.get("connections"),
180
+ "engine": rep.get("engine"), "trial": rep.get("trial")},
181
+ ensure_ascii=False, indent=1)
182
+ + f"\n\n{CREDIT}\n")
183
+ t = Path(REPORT_TXT)
184
+ t.write_text(txt, encoding="utf-8")
185
+ p.write_text(html, encoding="utf-8")
186
+ return p, t
187
+
188
+
189
+ def main(argv: list[str] | None = None) -> int:
190
+ ap = argparse.ArgumentParser(description="گزارش عیب‌یابی یک‌کلیکی")
191
+ ap.add_argument("--json", action="store_true", help="خروجی ماشین‌خوان")
192
+ ap.add_argument("--text", action="store_true", help="متن ساده، برای کپی در پیام")
193
+ ap.add_argument("--quick", action="store_true", help="بدون اجرای آزمون‌های واحد")
194
+ ap.add_argument("--version", action="version", version=f"diagnose {VERSION}")
195
+ args = ap.parse_args(argv)
196
+
197
+ rep = collect(run_tests=not args.quick)
198
+ h, t = build_report(rep)
199
+ if args.json:
200
+ print(json.dumps(rep, ensure_ascii=False, indent=1))
201
+ return 0 if rep.get("ok") else 1
202
+ if args.text:
203
+ print(t.read_text(encoding="utf-8"))
204
+ return 0 if rep.get("ok") else 1
205
+ print(summary_line(rep))
206
+ print(f"گزارش ساخته شد:\n {h}\n {t}")
207
+ return 0 if rep.get("ok") else 1
208
+
209
+
210
+ if __name__ == "__main__":
211
+ raise SystemExit(main())
station/docs/01-derivatives-iran-fa.md ADDED
@@ -0,0 +1,136 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # مشتقه در ایران: چه چیزی ریاضی است، چه چیزی شانس است
2
+
3
+ **پروندهٔ پژوهشی ۱، تاریخ: ۲۲ سپتامبر ۲۰۲۶**
4
+ **پرسش صاحب پرونده:** آیا می‌شود با خرید و فروش اوراق مشتقه در ایران، فقط با ریاضیات و بدون شانس، سریع تشخیص داد چه چیزی را چه زمانی بخرم و بفروشم و چقدر سود و با چه احتمالی؟
5
+
6
+ ## خلاصهٔ اجرایی (حکم صریح)
7
+
8
+ جملهٔ «ریاضیات اگر درست به کار گرفته شود ثروت را تضمین می‌کند» یک جملهٔ نیمه‌درست است. ریاضیات در بازار، **برتری** (edge) می‌سازد، نه **تضمین**. در ایران امروز سه سؤال تعیین‌کننده است و پاسخ هر سه با داده‌های همین گزارش آمدنی است:
9
+
10
+ ۱. **آیا در ایران معاملهٔ بدون‌شانس (آربیتراژ) وجود دارد؟** بله، ولی کوچک و کوتاه‌عمر: عمدتاً در قالب پایهٔ آتی، باکس‌اسپرد و اوراق اختیار فروش تبعی.
11
+ ۲. **آیا با سرمایهٔ کوچک (زیر چند صد میلیون تومان) این کار به‌صرفه است؟** در بیشتر روزها نه. چون کارمزد، اسپرد خرید‌وفروش، وجه تضمین و ریسک اجرا، بازدهٔ ریاضی را می‌بلعد. گزینهٔ واقع‌بینانه‌تر با سرمایهٔ خرد، صندوق درآمد ثابت (بازده مؤثر اسمی حدود ۳۹ تا ۴۰ درصد سالانه در شهریور ۱۴۰۵) و صندوق طلا برای پوشش تورم است.
12
+ ۳. **پس چه چیزی «سلام» و «ریاضی» است؟** ترکیب سه لایه: (الف) لایهٔ امن سرمایه، (ب) لایهٔ آربیتراژهای کوچک با حاشیهٔ اطمینان، (ج) لایهٔ درآمد از مهارت (بخش دوم پرونده). معاملهٔ جهت‌دار روی آپشن، شانس است و نه ریاضی.
13
+
14
+ **برآورد صادقانهٔ احتمال موفقیت:**
15
+
16
+ | مسیر | تعریف موفقیت | برآورد احتمال | مبنا |
17
+ |---|---|---|---|
18
+ | آربیتراژ پایه/باکس با انضباط کامل | بازده سالانهٔ بالاتر از صندوق درآمد ثابت، بدون ضرردهی ماهانه | ۳۵ تا ۵۰ درصد | فرصت نادر + ریسک اجرا و نقدشوندگی |
19
+ | برداشت بازده تضمینی اوراق تبعی | دریافت کامل مبلغ تضمین در سررسید | ۷۰ تا ۸۵ درصد | تضمین ناشر، ولی مشروط به نگه‌داشتن سبد و ریسک نکول |
20
+ | معاملهٔ جهت‌دار آپشن (خرید کال/پوت) | سود خالص سالانه بعد از کارمزد | ۱۰ تا ۲۰ درصد | آمار جهانی: بیش از ۹۰ درصد معامله‌گران خرد بازنده‌اند |
21
+ | معاملهٔ نوسانی روزانه روی هر ابزار | سود پایدار در ۱۲ ماه | زیر ۱۵ درصد | مطالعات خرد: تکنیکال + کارمزد = انتقال ثروت به واسطه‌ها |
22
+
23
+ این درصدها **برآورد** هستند، نه آمار دولتی؛ روش: ترکیب آمار منتشرشدهٔ بازندگان خرد با واقعیت ساختاری بازار ایران (اسپرد بزرگ، نقدشوندگی کم، محدودیت فروش استقراضی).
24
+
25
+ ## نقشهٔ بازار (چه چیزی، کجا، با چه قانونی)
26
+
27
+ **در بورس اوراق بهادار تهران و فرابورس:** قرارداد اختیار معامله (کال و پوت) روی سهام و صندوق‌های منتخب، به‌صورت ماهانه، با اندازهٔ قرارداد استاندارد (روی سهام معمولاً ۱٬۰۰۰ سهم)، سررسید مشخص، سبک اعمال اروپایی، و دو روش تسویه: نقدی یا فیزیکی. سقف موقعیت هم‌جهت و فاصلهٔ قیمت اعمال، در «مشخصات قرارداد» اعلام می‌شود.
28
+
29
+ **در بورس کالای ایران:** قرارداد آتی (شمش و صندوق طلا، زعفران، پسته، زیره)، اختیار معاملهٔ کالا، و گواهی سپردهٔ کالایی (زعفران، شمش و سکه، پسته، سیمان، شیشه، سنگ‌آهن، میلگرد).
30
+
31
+ **اوراق اختیار فروش تبعی:** نسخهٔ ایرانی و بسیار مهم این بازار. ناشر (شرکت یا نهاد حمایتی) متعهد می‌شود در سررسید، کمینهٔ بازدهی را بپردازد. در عرضه‌های واقعی، نرخ تضمین در بازهٔ ۲۰ تا ۳۰ درصد دیده شده و **شرط اعتبار، نگه‌داشتن سبد پایه تا سررسید است**. تسویه می‌تواند مابه‌التف��وت نقدی باشد یا خرید سهام توسط ناشر.
32
+
33
+ ### قوانین و هزینه‌هایی که همه‌چیز را تعیین می‌کند
34
+
35
+ - **کارمزد معاملهٔ اختیار معامله:** حدود ۰٫۱۰۳ درصد هر طرف؛ **کارمزد اعمال:** ۰٫۰۵ درصد ارزش قرارداد بر پایهٔ قیمت اعمال؛ **مالیات واگذاری در تسویهٔ فیزیکی:** ۰٫۵ درصد. معاملات مشتقه از مالیات بر درآمد معاف است.
36
+ - **کارمزد سهام:** خرید حدود ۰٫۴۶۴ درصد و مجموع کسورات فروش حدود ۰٫۹۶۴ درصد (شامل ۰٫۵ درصد مالیات نقل‌وانتقال).
37
+ - **وجه تضمین:** خریدار آپشن وجه تضمین نمی‌دهد؛ **فروشنده** باید وجه تضمین اولیه بگذارد و حداقل ۷۰ درصد آن را نگه دارد، وگرنه اخطاریهٔ افزایش وجه تضمین می‌گیرد. ضوابط وجه تضمین، برای ۱۸ راهبرد استاندارد (پوشش‌داده‌شده، دوپایه‌ای، پروانه‌ای و…) جدول جداگانه دارد.
38
+ - **آتی کالا:** وجه تضمین اولیه حدود ۱۰ تا ۲۰ درصد ارزش قرارداد، تسویهٔ روزانهٔ سود و زیان، حداقل ۷۰ درصد به‌عنوان وجه تضمین جبرانی، حد نوسان روزانه معمولاً ۵ درصد.
39
+ - **فروش استقراضی سهام در ایران وجود ندارد.** یعنی نیمهٔ دوم آربیتراژهای تبدیل‌پذیر و «reverse conversion» از پیش مسدود است؛ فقط جهتی که با داشتن سهم یا با فروش آتی قابل ساخت است، عملی است.
40
+
41
+ {**_نکتهٔ مهم دربارهٔ محدودیت‌ها: بسیاری از فرصت‌های «بدون ریسک» کتابی، در ایران عملاً در یک طرف بسته است. اگر الگوریتمی ساختید که بدون فروش استقراضی سود می‌دهد، قابل اجرا است؛ اگر به آن نیاز دارد، دورش را خط بکشید._**}
42
+
43
+ ## جعبه‌ابزار ریاضی (همان چیزی که ابزار ساخته‌شده اجرا می‌کند)
44
+
45
+ ۱. **ارزش منصفانهٔ آتی:** F = S × exp((r + u − y)×T)؛ با r نرخ بهره، u هزینهٔ انبارداری، y منافع نگهداری.
46
+ ۲. **نرخ تلویحی بازار:** r_implied = ln(F/S)/T. اگر این عدد از نرخ سد شما کمتر بود، خرید نقدی و فروش آتی به‌صرفه نیست.
47
+ ۳. **پایهٔ نقدی‌آتی (Cash & Carry):** بازده خالص = (قیمت آتی پس از کارمزد فروش − قیمت نقدی پس از کارمزد خرید − هزینهٔ انبار) ÷ هزینهٔ خرید، بعد سالانه‌سازی مرکب.
48
+ ۴. **تساوی پوت‌کال:** C − P = S − K×exp(−rT). انحراف مثبت و بزرگ‌تر از هزینه‌های گردش = فرصت conversion.
49
+ ۵. **باکس اسپرد:** خرید کال با اعمال پایین + فروش پوت با اعمال پایین + فروش کال با اعمال بالا + خرید پوت با اعمال بالا. دریافتی قطعی = K₂ − K₁؛ اگر بدهی اولیه کمتر باشد، بازده بدون‌ریسک تا سررسید قفل می‌شود.
50
+ ۶. **تبعی:** بازده تضمینی = (K پس از کسر کارمزد فروش − (قیمت سهم پس از کارمزد خرید + قیمت پوت)) ÷ همان هزینهٔ کل، بعد سالانه‌سازی.
51
+ ۷. **نوسان ضمنی در برابر نوسان واقعی:** اگر نوسان ضمنی بازار چند واحد بزرگ‌تر از نوسان واقعی ۳۰ روز گذشتهٔ سهم باشد، فروشندهٔ آپشن (پوشش‌دار) در موقعیت بهتری است؛ عکس آن، خریدار.
52
+
53
+ ## شش استراتژی، از بی‌ریسک‌تر به پرریسک‌تر
54
+
55
+ | # | استراتژی | ماهیت ریاضی | بازده واقع‌بینانه | احتمال موفقیت | شرط اصلی |
56
+ |---|---|---|---|---|---|
57
+ | ۱ | برداشت بازده اوراق تبعی | تضمین ناشر | ۲۰ تا ۳۰ درصد در دورهٔ نگه‌داری | ۷۰ تا ۸۵ درصد | نگه‌داشتن سبد پایه، بررسی اعتبار ناشر |
58
+ | ۲ | باکس اسپرد آپشن | قفل کردن تفاوت دو قیمت اعمال | تا رسیدن به نرخ سد یا بیشتر | ۳۵ تا ۵۰ درصد | هر چهار پا در یک روز و با نقدشوندگی کافی |
59
+ | ۳ | پایهٔ آتی (نقد بخر، آتی بفروش) | نرخ تلویحی در برابر نرخ سد | ۵ تا ۳۰ درصد سالانهٔ اضافی | ۳۰ تا ۴۵ درصد | امکان نگه‌داری کالا یا گواهی تا سررسید |
60
+ | ۴ | فتوکال پوشش‌داده‌شده روی سهم موجود | ف��وش نوسان، درآمد پرمیوم | ۲۰ تا ۴۵ درصد سالانه از پرمیوم | ۴۵ تا ۶۰ درصد | داشتن سهم، پذیرش سقف رشد |
61
+ | ۵ | پوت محافظ / کالارزان | ساختن کف یا اهرم ارزان | وابسته به روند بازار | ۳۰ تا ۴۵ درصد | تحلیل جهت‌دار؛ دیگر ریاضی محض نیست |
62
+ | ۶ | خرید جهت‌دار آپشن | شرط‌بندی روی نوسان | میانگین منفی بعد از کارمزد | ۱۰ تا ۲۰ درصد | توصیه نمی‌شود مگر با مهارت اثبات‌شده |
63
+
64
+ نکتهٔ کلیدی دربارهٔ جدول: سه ردیف اول، «بی‌ریسک‌تر» هستند ولی **بازده کمی دارند و به سرمایهٔ بزرگ‌تر حساس‌اند**؛ سه ردیف آخر پرمیوم و داستان دارند، ولی همان جایی است که اکثریت پول از دست می‌دهند.
65
+
66
+ ## فلوچارت تصمیم (روزانه)
67
+
68
+ ```
69
+ شروع روز
70
+ ├─ ۱. آیا دادهٔ امروز کامل است؟ (قیمت پایانی پایه، کل زنجیرهٔ آپشن، آتی، گواهی سپرده، نرخ سد)
71
+ │ نه ⇒ هیچ معامله‌ای نکن؛ دادهٔ ناقص = تصمیم ناقص
72
+ ├─ ۲. نرخ سد امروز را چک کن (بازده مؤثر صندوق درآمد ثابت؛ شهریور ۱۴۰۵ حدود ۳۹ تا ۴۰ درصد)
73
+ ├─ ۳. غربال نقدشوندگی: حجم روزانه، تعداد سفارش، اسپرد نسبی
74
+ │ اسپرد > ۳ درصد یا حجم < ۲۰ قرارداد ⇒ حذف
75
+ ├─ ۴. محاسبه برای هر کاندیدا: ارزش منصفانه، نوسان ضمنی، انحراف تساوی، بازده باکس، بازده تبعی، مبنای آتی
76
+ ├─ ۵. کسر همهٔ هزینه‌ها: کارمزد دو طرف معامله، کارمزد اعمال، مالیات تسویهٔ فیزیکی، اسپرد
77
+ ├─ ۶. مقایسه با نرخ سد
78
+ │ حاشیه < ۳ درصد (آربیتراژ) یا < ۵ درصد (با اهرم) ⇒ رد کن
79
+ ├─ ۷. بررسی ظرفیت: آیا با سرمایهٔ من، وجه تضمین و سقف موقعیت اجازهٔ اجرا می‌دهد؟
80
+ ├─ ۸. تعیین اندازه: وجه تضمین هر موقعیت حداکثر ۲۰ درصد سرمایه؛ حداقل ۴۰ درصد نقد برای اخطاریه
81
+ ├─ ۹. ثبت سفارش هم‌زمان (پاهای آربیتراژ باید در یک پنجرهٔ زمانی کوتاه اجرا شوند)
82
+ └─ ۱۰. ثبت در دفتر: دلیل ورود، بازده انتظاری، بازده واقعی، دلیل خروج، درس
83
+ ```
84
+
85
+ ## الگوریتم غربال (شبه‌کد)
86
+
87
+ ```
88
+ ورودی: داده روز D، نرخ سد H (مثلاً ۰٫۳۷)، سقف ریسک
89
+ برای هر گروه هم‌سررسید در هر دارایی پایه:
90
+ اگر نقدشوندگی ضعیف ⇒ بعدی
91
+ r = سالانه‌سازی (بازده پایه/باکس/تبعی پس از هزینه)
92
+ edge = r − H − جریمهٔ نقدشوندگی − جریمهٔ اهرم
93
+ اگر edge ≥ ۰٫۰۳ ⇒ به لیست فرصت‌ها اضافه کن
94
+ مرتب‌سازی نزولی بر اساس edge
95
+ برای هر فرصت به‌ترتیب:
96
+ اگر سقف موقعیت و وجه تضمین اجازه بدهد ⇒ ثبت سیگنال با اندازهٔ محاسبه‌شده
97
+ وگرنه ⇒ ذخیره در صف انتظار
98
+ گزارش: فهرست سیگنال‌ها + توضیح ریاضی هرکدام + ریسک‌های باقی‌مانده
99
+ ```
100
+
101
+ این الگوریتم عیناً در ابزار `tools/derivatives_scout.py` پیاده شده است. خروجی، «چه بخر و چه بفروش» نیست؛ «کجا تفاوت ریاضی با نرخ سد از حاشیهٔ اطمینان عبور می‌کند» است.
102
+
103
+ ## مدیریت سرمایه (بخشی که ۹۰ درصد افراد حذف می‌کنند)
104
+
105
+ - سقف وجه تضمین درگیر: ۲۰ درصد سرمایه؛ بقیه آزاد.
106
+ - حداقل ۴۰ درصد نقد، فقط برای پاسخ به اخطاریهٔ وجه تضمین.
107
+ - حداکثر ۳ موقعیت هم‌زمان، و فقط در دارایی‌های پایهٔ غیرهمبسته.
108
+ - قاعدهٔ اندازه‌گیری: اگر یک ضرر ۲۵ درصدی در یک موقعیت، کل ماه را منفی می‌کند، اندازه نصف است.
109
+ - توقف معاملاتی: پس از سه ضرر پیاپی یا افت ۸ درصدی سرمایه، یک هفته توقف و بازبینی دفتر.
110
+
111
+ {**_ریاضیات بدون مدیریت سرمایه، شبیه فرمول درست با باتری خالی است. نفرینِ نسبت‌های ریاضی این است که خروجی مثبت کوچک، با یک خطای اندازه‌گیری بزرگ صفر می‌شود._**}
112
+
113
+ ## سی روز اول: طرح اعتبارسنجی (بدون سرما��ه‌گذاری جدی)
114
+
115
+ ۱. **روز ۱ تا ۳:** راه‌اندازی داده و ابزار. `python3 tools/derivatives_scout.py --demo --self-test`.
116
+ ۲. **روز ۴ تا ۱۴:** ثبت روزانهٔ ۱۰ کاندیدا، بدون معامله؛ مقایسهٔ نرخ سد با بازده محاسبه‌شده. هدف: ساختن حافظهٔ تاریخی که بعداً بتوانید کالیبره کنید.
117
+ ۳. **روز ۱۵ تا ۲۵:** معاملهٔ کاغذی؛ هر سیگنال را ثبت کنید و بازده انتظاری را با بازار واقعی مقایسه کنید. تفاوت، «هزینهٔ اجرا»ی شما را نشان می‌دهد.
118
+ ۴. **روز ۲۶ تا ۳۰:** بازبینی. اگر در ۲۰ روز گذشته هرگز حاشیهٔ بیش از ۳ درصد ندیدید، بازار فعلی این مسیر را نمی‌دهد و باید سرمایه را جای دیگری ببرید.
119
+ ۵. **فقط بعد از این چرخه:** شروع با حداقل سرمایهٔ ممکن روی استراتژی تبعی یا باکس.
120
+
121
+ ## خط قرمزها
122
+
123
+ - هیچ‌کس، هیچ سیگنالی، هیچ پکیجی «سود تضمینی» ندارد؛ اگر کسی چنین گفت، کلاهبردار است.
124
+ - عضویت در گروه‌های سیگنال، پرداخت برای «آموزش تضمینی»، و واریز پول به حساب شخصی، سه الگوی رایج کلاهبرداری در ایران هستند.
125
+ - پلتفرم‌های معاملات ارز و اهرمی غیرمجاز، از نظر قانونی و ریسک ورشکستگی، جای بازی نیستند.
126
+ - مالیات، صورت‌حساب و مسیر پول را تمیز نگه دارید؛ شرط «پول سالم» فقط اخلاقی نیست، ریسک حقوقی هم دارد.
127
+ - هیچ‌وقت پول قرضی، پول اجاره یا پول تحصیل را وارد مشتقه نکنید.
128
+
129
+ ## لینک‌های مرجع (بررسی‌شده)
130
+
131
+ - دستورالعمل معاملات اختیار معامله و جدول وجه تضمین: `neynavayan.ir` و `nibb.ir` (متن دستورالعمل سازمان بورس)
132
+ - آموزش اختیار معامله و کارمزدها: `learning.emofid.com/all-about-stock-options` و `optionbaaz.ir/article/57`
133
+ - آتی و تسویهٔ روزانهٔ بورس کالا: `imereport.ir` و `pasargadbroker.ir/blog/2025/07/derivative`
134
+ - اوراق اختیار فروش تبعی (فرمول بازده و شرایط نگه‌داری): `arka-invest.com` و اطلاعیه‌های عرضه در `shahrebours.com`
135
+ - کارمزد و مالیات معاملات سهام: `khanesarmaye.com/transaction-fees`
136
+ - آمار بازندگان خرد و اثر کارمزد: `fardintorkfar.com` و پژوهش‌های Newall & Weiss
station/docs/02-ideas-iran-fa.md ADDED
@@ -0,0 +1,75 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # پول سالم در ایران: چهارده مسیر، با احتمال واقعی
2
+
3
+ **پروندهٔ پژوهشی ۲، تاریخ: ۲۲ سپتامبر ۲۰۲۶**
4
+ **قاعدهٔ بازی:** هر مسیر با پنج عدد سنجیده می‌شود: سرمایهٔ لازم، زمان تا اولین درآمد، درآمد ماهانهٔ واقع‌بینانه (تومان، سطح قیمت پاییز ۱۴۰۴)، احتمال موفقیت، و ریسک اصلی. درصدها **برآورد** کارشناسی‌اند، نه وعده.
5
+
6
+ ## جدول کامل (مرتب‌شده بر اساس «قابل اجرا بودن برای کسی که سرمایه ندارد»)
7
+
8
+ | # | مسیر | سرمایه | اولین درآمد | درآمد ماهانهٔ واقع‌بینانه | احتمال موفقیت | ریسک اصلی |
9
+ |---|---|---|---|---|---|---|
10
+ | ۱ | فروش مهارت به‌صورت پروژه‌ای (طراحی، برنامه‌نویسی، ترجمه) با کارفرمای داخلی | ۰ | ۲ تا ۶ هفته | ۱۵ تا ۶۰ میلیون | ۴۵ درصد | رقابت قیمت، دیرکرد پرداخت |
11
+ | ۲ | فروش مهارت به کارفرمای خارجی و دریافت ارز | ۰ تا ۵ میلیون | ۱ تا ۳ ماه | معادل ۴۰ تا ۲۰۰ میلیون | ۳۰ تا ۴۰ درصد | محدودیت پرداخت، تحریم، ریسک واسطه |
12
+ | ۳ | خدمات فنی محلی (تعمیر کولر، دوربین، برق، لوله‌کشی) | ۱۵ تا ۶۰ میلیون (ابزار) | ۲ تا ۴ هفته | ۲۵ تا ۷۰ میلیون | ۶۰ تا ۷۰ درصد | کار بدنی، آموزش اولیه |
13
+ | ۴ | آموزش خصوصی و کلاس آنلاین (ریاضی، زبان، کنکور) | ۰ | ۱ تا ۴ هفته | ۱۰ تا ۳۵ میلیون | ۵۰ درصد | فصل‌بندی، خستگی |
14
+ | ۵ | حسابداری و مالیات برای کسب‌وکارهای کوچک (سامانهٔ مؤدیان) | ۰ تا ۱۰ میلیون | ۳ تا ۸ هفته | ۲۰ تا ۵۰ میلیون | ۴۰ تا ۵۵ درصد | مسئولیت حقوقی، نیاز به آموزش |
15
+ | ۶ | طراحی سایت و سئوی محلی برای کسب‌وکارهای شهری | ۰ | ۱ تا ۲ ماه | ۲۵ تا ۸۰ میلیون | ۲۵ تا ۴۰ درصد | پیدا کردن مشتری اول |
16
+ | ۷ | خدمات هوش مصنوعی به کسب‌وکارهای کوچک (چت‌بات، محتوا، اتوماسیون) | ۰ تا ۱۰ میلیون | ۱ تا ۳ ماه | ۲۰ تا ۶۰ میلیون | ۲۰ تا ۳۵ درصد | بازار نو، انتظار غیرواقعی مشتری |
17
+ | ۸ | ادیت ویدیو، تامبنیل، پادکست برای تولیدکنندگان محتوای داخلی | ۰ تا ۲۰ میلیون | ۲ تا ۶ هفته | ۱۵ تا ۵۰ میلیون | ۳۵ تا ۵۰ درصد | رقابت شدید |
18
+ | ۹ | تولید و بسته‌بندی خانگی (غذا، ترشی، شیرینی، صنایع دستی) و فروش آنلاین | ۱۰ تا ۵۰ میلیون | ۱ تا ۳ ماه | ۸ تا ۳۰ میلیون | ۳۰ تا ۴۵ درصد | مجوز، فاسدشدنی |
19
+ | ۱۰ | واسطه‌گری کالا (زعفران، خشکبار، پسته) بین تولیدکننده و خریدار | ۲۰ تا ۱۰۰ میلیون | ۱ تا ۳ ماه | ۱۵ تا ۶۰ میلیون (پورسانت) | ۳۰ درصد | اعتماد طرفین، نوسان قیمت |
20
+ | ۱۱ | تدریس/مشاورهٔ تخصصی آنلاین برای خارج از ایران (به‌زبان انگلیسی) | ۰ | ۲ تا ۴ ماه | معادل ۳۰ تا ۱۵۰ میلیون | ۲۵ تا ۳۵ درصد | زبان، پیدا کردن بازار |
21
+ | ۱۲ | صندوق درآمد ثابت + صندوق طلا (لایهٔ حفظ سرمایه) | هر مقدار | فوری | اسمی ۳۷ تا ۴۰ درصد سالانه | بالا (با ریسک نکول کم) | تورم بالاتر از بازده اسمی |
22
+ | ۱۳ | آربیتراژ و مشتقه (پروندهٔ ۱) | بالای چند صد میلیون تومان | ۱ تا ۳ ماه | متغیر، ۰ تا ۳ درصد ماهانه | ۳۵ تا ۵۰ درصد | اجرا و نقدشوندگی |
23
+ | ۱۴ | خرید و اجاره‌دهی دارایی مولد (لپ‌تاپ، دوربین، دوچرخه، موتور) | ۵۰ تا ۳۰۰ میلیون | ۱ تا ۲ ماه | ۵ تا ۱۵ درصد ارزش دارایی | ۴۰ تا ۵۵ درصد | خرابی، فرار مشتری |
24
+
25
+ ## چرا ترتیب جدول مهم است
26
+
27
+ سرمایهٔ کم، یعنی ترتیب جدول عملاً بزرگ‌ترین اهرم شما است. ردیف‌های ۱ تا ۸ «سرمایهٔ انسانی» می‌فروشند و از صفر شروع می‌شوند؛ ردیف ۱۲ به بعد دربارهٔ پول است و پول هم ندارید. بزرگ‌ترین بازده ای که در اختیار دارید این است که در ۹۰ روز اول یک مهارت قابل‌فروش به دست بیاورید و آن را به اولین مشتری بفروشید؛ هیچ مسیر مالی دیگری با سرمایهٔ صفر، این سرعت را ندارد.
28
+
29
+ {**_محاسبهٔ فرصت: با نرخ سد امروز (بازده مؤثر صندوق درآمد ثابت حدود ۳۷ درصد)، ۱۰ میلیون تومان سرمایه در سال فقط ۳٫۷ میلیون تومان سود می‌دهد؛ در حالی که یک مهارت در ماه اول می‌تواند ۱۵ میلیون به بالا درآمد بسازد. یعنی در این نقطهٔ زندگی، یادگیری و فروش مهارت چند برابر بازار سرمایه برد دارد._**}
30
+
31
+ ## سه مسیر برتر برای شروع (ترکیب پیشنهادی)
32
+
33
+ **الف. خدمات فنی محلی + آموزش مهارت دیجیتال.** اگر توان کار بدنی دارید، تعمیر کولر و نصب دوربین مداربسته در شهرهای متوسط و کوچک، نقدترین بازار ایران است: تقاضا ثابت، رقابت کم، پرداخت نقد. موازی آن، شب‌ها یک مهارت دیجیتال (ادیت ویدیو یا پایتون) یاد بگیرید تا در ماه سوم درآمد دوم بسازید.
34
+
35
+ **ب. حسابداری مالیاتی برای کسب‌وکارهای کوچک.** سامانهٔ مؤدیان و صورت‌حساب الکترونیکی، برای میلیون‌ها مغازه و کارگاه دردسر جدید ساخته است و کسی که این کار را بلد باشد، ماهانه ۲ تا ۸ میلیون تومان از هر مشتری می‌گیرد. ورود با آموزش کوتاه ممکن است و درآمدش تکرارشونده (retainer) است.
36
+
37
+ **ج. فروش ارزی مهارت، با مدیریت ریسک پرداخت.** درآمد دلاری در ایران شدنی است ولی مسیر پول، ریسک اصلی است. قاعده: فقط با واسطه‌های شناخته‌شده و قرارداد مکتوب؛ هر ۲۰۰ تا ۵۰۰ دلار تسویه کنید، نه ماهانه؛ نقدینگی را در صندوق درآمد ثابت و صندوق طلا پخش کنید.
38
+
39
+ ## نسخهٔ طلایی: هفت قاعده‌ای که بازده را چند برابر می‌کند
40
+
41
+ ۱. **به کسی بفروشید که پول دارد.** مشتری B2B، پرداخت بزرگ‌تر و پایدارتر دارد. مغازه‌دار و کارخانه نمی‌توانند مثل مشتری شخصی، پروژه را بی‌خیال شوند.
42
+ ۲. **درآمد تکرارشونده بسازید.** پشتیبانی ماهانه، اشتراک محتوا، قرارداد نگهداری. یک درآمد ثابت ماهانه، از پنج پروژهٔ یک‌بار مصرف بهتر است.
43
+ ۳. **نمونهٔ کار قبل از قیمت.** اولین سه کار را با تخفیف بگیرید اما نه مجانی اگر می‌توانید نمونهٔ عمومی بسازید که کارتان را نشان دهد.
44
+ ۴. **قیمت را بر اساس ارزش، نه ساعت.** بپرسید این کار برای مشتری ماهی چقدر ارزش دارد؛ نرخ خود را از آن بسازید.
45
+ ۵. **هیچ‌وقت یک مشتری نداشته باشید.** حداقل سه مشتری هم‌زمان؛ ترک یک مشتری نباید درآمد ماه را صفر کند.
46
+ ۶. **پول اول، کار بعد.** درصد علی‌الحساب، تحویل پله‌ای، و برای مشتری ناشناس پیش‌پرداخت کامل.
47
+ ۷. **بخشی از هر درآمد را به دارایی مولد ببرید.** قاعدهٔ ساده: ۳۰ درصد درآمد را به خودتان بدهید، ۵۰ درصد خرج زندگی، ۲۰ درصد پس‌انداز. با تورم فعلی، پس‌انداز در صندوق درآمد ثابت و طلا ارزش پول را نگه می‌دارد.
48
+
49
+ ## نکتهٔ تلخی که هیچ تبلیغی نمی‌گوید
50
+
51
+ با تورم سالانهٔ نزدیک به ۷۰ درصد و بازده اسمی ۴۰ درصد، پول در صندوق درآمد ثابت **قدرت خریدش را از دست می‌دهد** (رشد اسمی ۴۰ درصد در برابر تورم ۷۰ درصد). یعنی صندوق درآمد ثابت لایهٔ **نقدینگی و امنیت** است، نه رشد. برای حفظ ارزش باید بخشی از پس‌انداز در دارایی‌های مقاوم به تورم (طلا، صندوق طلا، مسکن کوچک، ارز مولد، تجهیزات قابل اجاره) باشد. ترتیب درست: اول نقدینگی امن برای سه ماه زندگی، بعد مهارت درآمدزا، بعد دارایی مقاوم به تورم، و آخر از همه لایهٔ پرریسک.
52
+
53
+ {**_هیچ ترکیبی از صندوق‌ها و طلا، شما را با سرمایهٔ کم ثروتمند نمی‌کند. کاری که واقعاً ثروت می‌سازد، فروش مهارت با قیمت رو به بالا و سپس سرمایه‌گذاری مازاد است. این جمله را با جدول همین پرونده بسنجید: ردیف ۱ با سرمایهٔ صفر، در ماه اول بیشتر از ردیف ۱۲ با ۱۰۰ میلیون تومان درمی‌آورد._**}
54
+
55
+ ## چه چیزی را هرگز نکنید
56
+
57
+ - طرح‌های «ضریب سود تضمینی» با وعدهٔ ۲۰ درصد ماهانه، شبکه‌ای هستند نه سرمایه‌گذاری.
58
+ - ترید فارکس و ارز دیجیتال با پلتفرم غیرمجاز، در ایران فاقد حمایت حقوقی است.
59
+ - خرید و فروش سیگنال، آموزش‌های گران با وعدهٔ استخدام، و پیش‌فروش محصولی که وجود ندارد.
60
+ - قرض گرفتن برای معاملهٔ اهرمی. اهرم برای کسی است که سرمایهٔ اضافه دارد، نه کسی که پول قرض گرفته.
61
+
62
+ ## برنامهٔ ۹۰ روز
63
+
64
+ **روز ۱ تا ۳۰:** انتخاب یک مهارت (از جدول بخش الف یا ب)، دو ساعت تمرین روزانه، ساخت سه نمونه‌کار واقعی.
65
+ **روز ۳۱ تا ۶۰:** معرفی به ۵۰ مشتری ممکن (حضوری، اینستاگرام، معرفی دوستان)، اولین پروژهٔ پول‌دار، دریافت بازخورد.
66
+ **روز ۶۱ تا ۹۰:** افزایش قیمت، تبدیل دو مشتری به قرارداد ماهانه، و کنار گذاشتن ۲۰ درصد درآمد در «صندوق پایه» (صندوق درآمد ثابت). از روز ۹۱ می‌توانید ۱۰ درصد درآمد را برای اعتبارسنجی مسیرهای بازار سرمایه (پروندهٔ ۱) جدا کنید.
67
+
68
+ ## نگاشت مهارت‌ها (فهرست پیشنهادی برای ساخت در HARNESSES)
69
+
70
+ ۱. `iran-derivatives-scout`: دیده‌بان ریاضی مشتقه. **ساخته شد در همین نوبت.**
71
+ ۲. `income-plan-forge`: گرفتن سرمایه، زمان، مهارت و شهر؛ خروجی: برنامهٔ ۹۰ روزه با هدف عددی و ارزیابی هفتگی.
72
+ ۳. `price-and-proposal`: ماشین قیمت‌گذاری و نوشتن پیشنهاد کار برای مشتری داخلی و خارجی.
73
+ ۴. `tax-paperwork-iran`: چک‌لیست سامانهٔ مؤدیان و تعهدات مالیاتی کسب‌وکار کوچک.
74
+
75
+ ساخت هر مهارت در این محیط، با سیاست خودش، پیکربندی دروازه و بازبینی skeptic انجام می‌شود؛ ترتیب پیشنهادی همین ترتیب بالا است و به انتخاب صاحب پرونده بستگی دارد.
station/docs/03-investor-and-first-money-fa.md ADDED
@@ -0,0 +1,95 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # سرمایه‌گذار و اولین پول: بستهٔ عملی
2
+
3
+ **پروندهٔ پژوهشی ۳، تاریخ: ۲۲ سپتامبر ۲۰۲۶**
4
+ **درخواست صاحب پرونده:** «اگر سرمایه‌گذار پیدا کنم هم برایم ایده بده… ولی باید توانایی توجیه برای سرمایه‌گذاری را داشته باشم.»
5
+
6
+ ## صداقت اول، قبل از هر ایده‌ای
7
+
8
+ سه واقعیت را پیش از بقیهٔ این پرونده بخوانید، چون جهت همهٔ تصمیم‌ها را عوض می‌کنند:
9
+
10
+ ۱. **پول دیگران را برای معاملهٔ مشتقه و ارز و سهام نگیرید.** گرفتن پول از دیگران برای سرمایه‌گذاری در بازار، در ایران نیازمند مجوز سازمان بورس (سبدگردانی یا مشاور سرمایه‌گذاری) است؛ بدون مجوز، هم غیرقانونی است و هم اگر پول کم شود، شما بدهکار می‌مانید و آبرویتان می‌رود. سرمایه‌گذار واقعی هم به کسی که پول ندارد و سابقه ندارد، پول نمی‌دهد که در بازار پرنوسان بخورد.
11
+ ۲. **سرمایه‌گذار برای کسب‌وکار می‌دهد، نه برای امید.** آنچه سرمایه‌جذب می‌کند «مشتری واقعی» است: کسی که امروز پول می‌دهد و کالا یا خدمت می‌گیرد. دو مشتری پرداخت‌کننده، از هر توجیه و طرح رنگی قوی‌تر است.
12
+ ۳. **ارزان‌ترین سرمایه‌گذار دولت است، نه آشنا و رفیق.** تسهیلات قرض‌الحسنهٔ مشاغل خانگی با کارمزد حدود ۴ درصد سالانه، روی کاغذ از هر شریکی منصف‌تر است و آبروی شما را گرو نمی‌گذارد.
13
+
14
+ {**_اشتباه رایج: خیلی‌ها اول دنبال پول می‌روند و بعد دنبال مشتری. ترتیب درست برعکس است: مشتری اول، بعد پول. با مشتری، پول خودش می‌آید؛ با پول و بی‌مشتری، فقط بدهی می‌آید._**}
15
+
16
+ ## پنج مسیر واقعی برای جذب سرمایه در ایران
17
+
18
+ ### مسیر ۱. تسهیلات قرض‌الحسنهٔ اشتغال و مشاغل خانگی (بهترین نقطهٔ شروع)
19
+
20
+ - سقف فردی حدود ۲۰۰ میلیون تومان با بازپرداخت تا ۶۰ ماه و کارمزد حدود ۴ درصد سالانه؛ برای برخی رسته‌های شغلی مصوب تا حدود ۳۵۰ میلیون تومان.
21
+ - تضمین: اعتبارسنجی متقاضی به‌همراه یک ضامن معتبر یا سفته.
22
+ - مسیر ثبت‌نام: سامانهٔ مشاغل خانگی به نشانی `smkh.mcls.gov.ir` و سامانهٔ جامع تسهیلات اشتغال `tek.mcls.gov.ir` و پنجرهٔ ملی `my.gov.ir`.
23
+ - طرح اشتغال جوانان با همکاری صندوق کارآفرینی امید: نرخ حدود ۱۵ درصد با شرط تأمین حدود ۲۰ درصد آوردهٔ خودِ متقاضی.
24
+ - بنیاد برکت: تسهیلات خرد بر پایهٔ فعالیت (مشاغل خانگی تولیدی تا حدود ۱۰۰ میلیون، خدماتی تا حدود ۳۰ میلیون، کشاورزی تا حدود ۵۰ میلیون، روستایی تا حدود ۱۵۰ میلیون).
25
+ - شرط عملی قبولی: یک «طرح کسب‌وکار» کوتاه و باورپذیر که در بخش بعد ساختارش را می‌سازیم؛ نه آرزو، بلکه عدد و مشتری.
26
+
27
+ ### مسیر ۲. مشتری به‌عنوان سرمایه‌گذار: پیش‌فروش
28
+
29
+ پول را از کسی بگیرید که کالا یا خدمت را می‌خواهد. پیش‌فروش با تخفیف محدود (مثلاً ۱۰ درصد) فقط به مشتریانی که می‌شناسید، منبع سرمایه در گردش است و ریسک شرعی و قانونی هم ندارد. مثال: ۱۰ سفارش پیش‌فروش ۵ میلیون تومانی مساوی است با ۵۰ میلیون تومان نقدِ بدون بدهی.
30
+
31
+ ### مسیر ۳. مضاربه: شریکِ پول‌دار و بی‌وقت
32
+
33
+ مضاربه یک عقد شرعی و قانونی است: یکی سرمایه می‌دهد، دیگری کار می‌کند، سود طبق نسبت توافق‌شده تقسیم می‌شود و زیان مالی (به‌جز تقصیر) بر عهدهٔ صاحب سرمایه است. این ساختار برای **تجارت کالا** ساخته شده است، نه برای معامله در بازار مشتقه. نمونهٔ کاربردی: سرمایه‌دار پول می‌دهد، شما کالا (زعفران، خشکبار، لوازم جانبی موبایل، پوشاک) را از عمده‌فروشی می‌خرید، می‌فروشید و سود تقسیم می‌شود. برای اینکه این مسیر سالم بماند: قرارداد مکتوب، دفتر حساب شفاف، رسید خرید و فروش، و نسبت سود مشخص از قبل.
34
+
35
+ ### مسیر ۴. شریک تجهیزاتی
36
+
37
+ کسی که تجهیزات دارد و استفاده نمی‌کند (دوربین، لپ‌تاپ، پرینتر، چرخ‌خیاطی، ابزار برق) را شریک کنید: تجهیزات از او، کار و بازار از شما، سود تقسیمی. این نوع شراکت برای سرمایه‌گذار جذاب است چون دارایی‌اش از دست نمی‌رود و برای شما ریسک نقدی صفر دارد.
38
+
39
+ ### مسیر ۵. شریک مکمل
40
+
41
+ دو نفر که مهارت‌های مکمل دارند، هر دو سرمایه‌گذار خودشان هستند. مثال: کسی که ادیت ویدیو بلد است با کسی که فروش و ارتباط با مشتری بلد است. درآمد تقسیم می‌شود، ریسک نصف می‌شود، و برای هر دو نمونه‌کار و سابقه ساخته می‌شود.
42
+
43
+ ## توجیه سرمایه‌گذاری: ساختار یک‌صفحه‌ای
44
+
45
+ هر سرمایه‌گذاری، عاقل یا احمق، پنج سؤال می‌پرسد. اگر یک صفحه داشته باشید که هر پنج را جواب بدهد، از ۹۰ درصد کسانی که فقط حرف می‌زنند جلوترید.
46
+
47
+ | بخش | چه چیزی بنویسید | چه اشتباهی نکنید |
48
+ |---|---|---|
49
+ | فرصت | چه کسی، چه دردی دارد، امروز چقدر پول برای آن می‌دهد | تعریف کلی بازار بدون مشتری مشخص |
50
+ | راه‌حل | دقیقاً چه می‌فروشید، به چه قیمتی، با چه هزینه‌ای | توضیح فنی طولانی که سرمایه‌گذار نمی‌فهمد |
51
+ | شواهد تقاضا | نام مشتری، تعداد سفارش، پیش‌فروش، پیام واقعی مشتری | وعدهٔ «اگر پول برسد مشتری می‌آید» |
52
+ | عددها | قیمت فروش، بهای تمام‌شده، حاشیهٔ سود، هزینهٔ ماهانه، نقطهٔ سربه‌سر، بازگشت سرمایه | خوش‌بینی بدون سناریوی بد |
53
+ | بازگشت پول به سرمایه‌گذار | سهم از سود، بازپرداخت اقساطی، یا ترکیب هر دو، با زمان‌بندی روشن | وعدهٔ سود ثابت و تضمینی |
54
+ | ریسک و مهار آن | سه ریسک اصلی و پاسخ عملی هرکدام | گفتن «ریسکی ندارد» |
55
+ | شفافیت | دفتر حساب، گزارش ماهانه، دسترسی سرمایه‌گذار به اعداد | حساب شخصی و بدون سند |
56
+
57
+ سه سناریو همیشه آماده داشته باشید: بد (چقدر طول می‌کشد به سربه‌سر برسیم)، متوسط (عدد واقع‌بینانه)، خوب. سرمایه‌گذارها به سناریوی بد بیشتر اعتماد می‌کنند تا به وعدهٔ خوب؛ چون نشان می‌دهد شما حساب کرده‌اید.
58
+
59
+ ## متن نمونه: پیشنهاد به سرمایه‌گذار
60
+
61
+ > سلام جناب آقای احمدی. من رضا هستم و در کار بسته‌بندی و پخش خشکبار در محلهٔ خودمان فعالیتم را شروع کرده‌ام. یک کسب‌وکار کوچک راه انداخته‌ام که پسته و بادام بسته‌بندی‌شده را به مغازه‌های محله با قیمت هر بسته ۳۵۰ هزار تومان می‌فروشد. تا الان ۱۲ مشتری ثابت داشته‌ام و ۱۸ میلیون تومان فروش کرده‌ام؛ فاکتورها و پیام‌های مشتری‌ها را می‌توانم نشان بدهم. برای افزایش ظرفیت خرید و بسته‌بندی، ۸۰ میلیون تومان سرمایه لازم دارم که صرف موجودی و تجهیزات بسته‌بندی می‌شود. پیشنهادم این است: ۳۰ درصد از سود ماهانه تا سقف بازگشت کامل سرمایه در ۱۰ ماه، به‌همراه گزارش حساب هر ماه. اگر مایل باشید، در ۱۵ دقیقه عددها، سناریوی بد و ریسک‌ها را نشان می‌دهم و بعد تصمیم بگیرید.
62
+
63
+ {**_این متن نمونه است؛ نام، کالا و عددها را با واقعیت خودتان عوض کنید، ولی ساختار جمله‌ها را نگه دارید: مشتری، عدد فروش، شواهد، مبلغ درخواستی، ساختار بازگشت، و دعوت به یک جلسهٔ کوتاه._**}
64
+
65
+ ### پاسخ به پنج مخالفت رایج
66
+
67
+ ۱. «سودی که می‌گویی زیاد است، باور نمی‌کنم.» پاسخ: «درست است، برای همین سناریوی بد را هم نوشته‌ام: در بدترین حالت [عدد]. بیایید بر مبنای ه��ان تصمیم بگیریم.»
68
+ ۲. «چرا خودت این کار را نمی‌کنی اگر سود دارد؟» پاسخ: «چون سرمایه‌اش را ندارم؛ کار و بازارش را دارم. برای همین سهم کار و سهم پول را جدا کرده‌ام.»
69
+ ۳. «تضمین چه می‌دهی؟» پاسخ: «تضمین سود نمی‌دهم؛ هیچ‌کس نباید بدهد. اما حساب‌ها باز است، رسید خرید و فروش هست و هر ماه گزارش می‌دهم.»
70
+ ۴. «پولم را چه وقت پس می‌گیرم؟» پاسخ دقیق و عددی، با تاریخ. اگر نمی‌توانید تاریخ بدهید، ساختار پیشنهادتان خراب است.
71
+ ۵. «اگر ضرر شد چه؟» پاسخ شفاف دربارهٔ تقسیم زیان، و این جمله: «اگر شرایط بد شود، اولین کسی که ضرر می‌بیند من هستم، چون کار و زمانم را گذاشته‌ام.»
72
+
73
+ ## اولین پول در ۱۴ روز (با صفر سرمایه)
74
+
75
+ اگر سرمایه و سرمایه‌گذار فعلاً نیست، این ۱۴ روز نان می‌دهد و همان‌زمان «شواهد تقاضا» برای توجیه‌نامه‌تان می‌سازد.
76
+
77
+ **مسیر الف. بدنی و خدماتی (پرداخت نقد، شروع امروز):** کارگری روزمزد ساختمان، کمک‌بار، تمیزکاری منزل و دفتر، شست‌وشوی خودرو، جابه‌جایی وسایل، نصب و راه‌اندازی ساده. نرخ نمونهٔ ۱۴۰۴ در شهرهای متوسط: روزانه ۳ تا ۸ میلیون تومان بسته به تخصص و شهر؛ تمیزکاری منزل ۱ تا ۳ میلیون برای هر سفارش.
78
+
79
+ **مسیر ب. دیجیتال با موبایل:** تایپ و صفحه‌آرایی، ساخت تامبنیل، ادیت ویدیوهای کوتاه، مدیریت صفحهٔ اینستاگرام مغازه‌ها، تبدیل فایل، ترجمهٔ ساده. مشتری اول در همسایگی خودتان است: آرایشگاه، تعمیرگاه، مطب، فروشگاه لباس. نرخ شروع: ۱٫۵ تا ۵ میلیون برای هر سفارش کوچک.
80
+
81
+ **مسیر ج. فروش واسطه‌ای بدون سرمایه:** عکس و مشخصات کالا را از عمده‌فروشی یا تولیدکننده بگیرید، آنلاین آگهی کنید، بعد از پرداخت مشتری خرید کنید. درصد شما ۱۰ تا ۲۰ درصد. فقط با کالای غیرفاسدشدنی و حجم کوچک شروع کنید.
82
+
83
+ ### چک‌لیست سه روز اول
84
+
85
+ روز ۱: انتخاب یک مسیر (فقط یکی)، نوشتن یک پیام فروش دو خطی، فهرست ۲۰ مشتری ممکن از میان آشناها، همسایه‌ها، مغازه‌های محله.
86
+ روز ۲: فرستادن ۲۰ پیام یا مراجعهٔ حضوری به ۱۰ مغازه؛ هدف: دو گفت‌وگوی واقعی، نه بیست پیام بی‌پاسخ. شب: قیمت‌گذاری و نوشتن نمونهٔ کار.
87
+ روز ۳: انجام اولین سفارش حتی کوچک، گرفتن پول، و درخواست یک معرفی از مشتری. هر روز همین چرخه: پیام، سفارش، تحویل، معرفی.
88
+
89
+ ## قرمزها
90
+
91
+ - کسی که «سرمایه‌گذار» معرفی می‌کند و اول از شما پول یا ودیعه می‌خواهد، کلاهبردار است.
92
+ - وعدهٔ «سود ثابت ماهانه» از هر کسی، رد است؛ در قرارداد هم اگر بیاید، باطل است.
93
+ - پول قرضی یا تسهیلات را وارد بازار مشتقه و ارز نکنید؛ آن پول باید اقساط بدهد، و بازار اهرمی اقساط نمی‌شناسد.
94
+ - با پول شریک، معاملهٔ اهرمی نکنید؛ حتی با مجوز هم این کار نیازمند ساختار رسمی و گزارش‌دهی است.
95
+ - هیچ‌وقت دو نفر را هم‌زمان در یک ساختار شفاهی شریک نکنید؛ شراکت شفاهی، پایانش دعوا است.
station/docs/04-trading-desk-plan-fa.md ADDED
@@ -0,0 +1,105 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # میز معاملات: نقشهٔ عملیاتی برای یک برنامه‌نویس ساده
2
+
3
+ **پروندهٔ پژوهشی ۴، تاریخ: ۲۲ سپتامبر ۲۰۲۶**
4
+ **درخواست:** شرکتی گفته «چیزی بساز که هر لحظه، با ریاضیات و الگوریتم و تحلیل خبر، خرید و فروش مشتقه را تصمیم بگیرد و برنامه زیر نظر کاربر کار کند». این پرونده می‌گوید این خواسته کجای واقعیت است، چه چیزی از امروز قابل ساختن است، و چه چیزی باید در قرارداد نوشته شود.
5
+
6
+ ## سه واقعیتی که باید قبل از امضای قرارداد بدانید
7
+
8
+ ۱. **معاملات الگوریتمی خودکار در بورس و فرابورس ایران مجاز نیست.** سازمان بورس از مهر ۱۳۹۹ استفاده از معاملات الگوریتمی و تقسیم سفارشات توسط مشتریان برخط را «تا اطلاع ثانوی» ممنوع کرد و کارگزاران موظف‌اند دسترسی مشتریانی که امکان معاملات الگوریتمی دارند را غیرفعال کنند. استثنا: بازارگردانان دارای مجوز با شناسهٔ مشخص. پس هر محصولی که «خودکار سفارش بفرستد» بسازید، هم شما و هم شرکت را در معرض تخلف قرار می‌دهد.
9
+ ۲. **پس تعریف درست محصول، «میز تصمیم و نظارت» است، نه «ربات معامله‌گر».** برنامه می‌شنود، محاسبه می‌کند، هشدار می‌دهد، ریسک را می‌سنجد، سناریو می‌سازد و در یک داشبورد نشان می‌دهد؛ **انسان دستور نهایی را می‌زند.** این هم دقیقاً همان «نظارت کاربر» است که شرکت خواسته، و هم قانونی است.
10
+ ۳. **هیچ‌کس، هیچ برنامه‌ای روی زمین، سود را تضمین نمی‌کند.** آنچه یک برنامه می‌تواند تضمین کند سه چیز است: سرعت محاسبه، انضباط ریسک، و ثبت دقیق تصمیم‌ها. اگر شرکت «سود تضمینی» می‌خواهد، آن قرارداد را امضا نکنید؛ ضررش را شما می‌دهید.
11
+
12
+ {**_جمع‌بندی صادقانه: در بازار ایران، «سریع‌تر معامله کردن» هیچ ارزشی ندارد چون معاملهٔ الگوریتمی ممنوع است. ارزش قابل فروش شما این است که اطلاعات را سریع‌تر از انسان بخوانید و ریسک را دقیق‌تر از انسان بسنجید._**}
13
+
14
+ ## کارخانهٔ داده: از کجا و با چه چیزی
15
+
16
+ | لایهٔ داده | منبع در ایران | وضعیت |
17
+ |---|---|---|
18
+ | قیمت لحظه‌ای سهام، آپشن، آتی | سامانهٔ `tsetmc` (بازار ناظر) و کتابخانه‌های پایتونی مثل `tsetmc-api` و `codal-tsetmc` (نصب با `pip install tsetmc-api`) | رایگان، ولی بدون تعهد؛ نقطه‌به‌نقطه هر چند ثانیه بخوانید، نه هر میلی‌ثانیه |
19
+ | ریزمعاملات و دادهٔ تاریخی | وب‌سرویس‌های تجاری داخلی؛ نمونهٔ عمومی `brsapi.ir` (نیازمند کلید) | پرداختی یا با کلید آزمایشی |
20
+ | اطلاعیه‌های رسمی شرکت‌ها | سامانهٔ کدال `codal.ir` (اعلامیه‌ها، صورت‌های مالی، افزایش سرمایه، تقسیم سود) | رایگان و رسمی؛ منبع قانونی برای «خبر مهم» |
21
+ | خبر و تحلیل | خبرگزاری‌های داخلی با فید RSS و کانال‌های خبری | رایگان؛ برای امتیاز احساسی خبر استفاده می‌شود |
22
+ | کلید سفارش | کارگزاران با وب‌سرویس؛ برخی کارگزاران دسترسی API نمی‌دهند (نمونه: پاسخ کارگزاری آگاه در سال ۱۴۰۱: «این سرویس وجود ندارد») | باید همان شرکت، دسترسی خودش را از کارگزار بگیرد |
23
+ | درگاه هوش مصنوعی متن | ابزار `jev-gate.py` در همین محیط، با کلید در متغیر محیطی (`TYPESAFE_API_KEY` یا `AI_GATEWAY_API_KEY` یا `OPENROUTER_API_KEY`) | زیرساخت آماده است؛ کلید زنده باید تأمین شود، وگرنه برچسب «شاهد محلی» می‌خورد |
24
+
25
+ ## معماری پیشنهادی در یک نگاه
26
+
27
+ ```
28
+ [۱ منابع داده] tsetmc · کدال · خبرها · آتی و گواهی سپرده
29
+ ↓
30
+ [۲ لایهٔ نرمال‌سازی] پاک‌سازی، یکسان‌سازی نمادها، ذخیره در SQLite + فایل روزانه
31
+ ↓
32
+ [۳ موتور ریاضی] ارزش منصفانه · نوسان ضمنی · تساوی پوت‌کال · باکس اسپرد ·
33
+ پایهٔ نقدی‌آتی · کمینهٔ بازده تبعی · نقدشوندگی و اسپرد
34
+ ↓
35
+ [۴ لایهٔ خبر و رویداد] کدال و خبر → خلاصهٔ ساخت‌یافته با هوش مصنوعی →
36
+ «رویداد تأثیرگذار» با جهت، بزرگی تقریبی و سطح اطمینان
37
+ ↓
38
+ [۵ موتور تصمیم] احتمال، ارزش انتظاری، حاشیهٔ اطمینان نسبت به نرخ سد
39
+ ↓
40
+ [۶ مدیر ریسک] سقف وجه تضمین · فاصله از اخطاریه · سقف هم‌جهت بودن ·
41
+ توقف معاملاتی · همبستگی پوزیشن‌ها
42
+ ↓
43
+ [۷ داشبورد نظارت] هشدار، دلیل هر پیشنهاد، دکمهٔ «تأیید و ادامه» برای انسان
44
+ ↓
45
+ [۸ دفتر و ممیزی] ثبت هر توصیه، هر تأیید، هر رد، بازده انتظاری در برابر واقعی
46
+ ```
47
+
48
+ نکتهٔ مهندسی: خروجی لایهٔ ۳ و ۴ هرگز مستقیماً به سفارش تبدیل نمی‌شود؛ همیشه از لایهٔ ۶ و ۷ می‌گذرد. این خط، هم قانونی است و هم چیزی است که شما را در برابر «چرا ضرر کردی؟» از شرکت حفظ می‌کند.
49
+
50
+ ## برنامهٔ تحویل در پنج فاز
51
+
52
+ **فاز ۰ (سه روز):** یک صفحه، یک تصمیم. با شرکت روشن کنید خروجی محصول «پیشنهاد و هشدار» است، نه «سفارش خودکار». دامنهٔ دارایی‌ها (فقط آپشن؟ آتی؟ کدام نمادها؟) و سقف سرمایهٔ آزمون را کتبی بگیرید.
53
+
54
+ **فاز ۱ (دو هفته):** اسکلت کاری. اتصال به داده (اول شبیه‌ساز، بعد tsetmc)، پایگاه‌دادهٔ محلی، پنل متنی، و همان ابزار ریاضی موجود (`derivatives_scout.py`) به‌عنوان موتور محاسبه. خروجی: هر دقیقه یک گزارش «وضعیت بازار».
55
+
56
+ **فاز ۲ (سه تا چهار هفته):** لایهٔ خبر. خواندن کدال و خبر، خلاصه‌سازی با هوش مصنوعی، تشخیص رویدادهای مهم (افزایش سرمایه، تقسیم سود، تعدیل، توقف نماد)، و اتصال آن به موتور تصمیم. خروجی: هشدار «این خبر روی این نماد اثر دارد».
57
+
58
+ **فاز ۳ (چهار هفته):** آموزش و اعتبارسنجی. اجرای «معاملهٔ کاغذی» روی دادهٔ گذشته و بعد روی دادهٔ زنده، بدون پول. معیار قبولی: انضباط (چند درصد سیگنال‌ها اجرا شد)، صحت محاسبه، و رفتار سیستم در روز شلوغ.
59
+
60
+ **فاز ۴ (پیوسته):** داشبورد نظارت کامل، گزارش هفتگی، و نسخهٔ دوم موتور تصمیم با وزن‌دهی بر پایهٔ نتایج واقعی.
61
+
62
+ **فاز ۵ (اختیاری، بعد از شش ماه سابقه):** اگر شرکت مجوز لازم را داشت، گفت‌وگو با کارگزار برای اتصال قانونی و بررسی وضعیت ابلاغیهٔ معاملات الگوریتمی در آن زمان.
63
+
64
+ ## چه چیزی به شرکت قول بدهید و چه چیزی نه
65
+
66
+ **بدهید:** سرعت پایش (صدها نماد به‌جای چند نماد)، محاسبهٔ دقیق بازده پس از کارمزد، هشدار رویداد کدال در چند دقیقه، انضباط ریسک، دفتر ممیزی و گزارش‌های قابل ارائه.
67
+ **ندهید:** درصد سود، «تضمین»، «بدون شانس بودن»، و هر عددی که در معاملهٔ کاغذی به دست نیامده است. برای هر عدد، سناریوی بد را هم نشان بدهید.
68
+
69
+ ## قرارداد: چهار بند حیاتی
70
+
71
+ ۱. موضوع قرارداد «تحویل نرم‌افزار و مستندات» باشد، نه «تحقق سود».
72
+ ۲. بند صریح: توصیه‌های نرم‌افزار جنبهٔ کمک‌تصمیم دارد؛ تصمیم نهایی و مسئولیت معامله با کاربر است.
73
+ ۳. پرداخت پله‌ای بر پایهٔ تحویل فازها (۴۰ درصد پیش، ۳۰ درصد بعد از فاز ۲، ۳۰ درصد بعد از پذیرش فاز ۳).
74
+ ۴. ممنوعیت استفاده از اطلاعات نهانی، دستکاری قیمت و انتشار سیگنال برای دیگران؛ و تأیید کتبی شرکت که دسترسی‌ها و مجوزهای لازم را دارد.
75
+
76
+ ## ایده‌های بهتر در همین بازار (با احتمال موفقیت واقع‌بینانه)
77
+
78
+ | # | ایده | چه چیزی می‌فروشید | نیاز به مجوز معاملاتی | برآورد احتمال موفقیت |
79
+ |---|---|---|---|---|
80
+ | ۱ | دستیار تحلیل کدال و خبر برای معامله‌گران | اشتراک ماهانهٔ هشدار و خلاصه | ندارد | ۴۰ تا ۵۵ درصد |
81
+ | ۲ | داشبورد ریسک برای معامله‌گران آپشن | اشتراک یا نصب اختصاصی | ندارد | ۳۵ تا ۵۰ درصد |
82
+ | ۳ | دیده‌بان ریاضی فرصت‌ها (پایهٔ آتی، باکس، تبعی) | گزارش روزانه یا اشتراک | ندارد | ۳۰ تا ۴۵ درصد |
83
+ | ۴ | ساخت سفارشی همین میز برای کارگزاری یا شرکت | پروژهٔ نرم‌افزاری | ندارد | ۳۵ تا ۵۰ درصد |
84
+ | ۵ | معاملهٔ حساب خودتان با همین ابزار | سود و زیان خودتان | دارد (محدودیت‌ها) | ۲۰ تا ۳۵ درصد |
85
+ | ۶ | ربات ارسال سفارش و سرخطی | فروش نرم‌افزار | تخلف | نزدیک صفر؛ وارد نشوید |
86
+
87
+ مقایسهٔ ردیف ۱ با ردیف ۵ مهم‌ترین جملهٔ این پرونده است: **فروش ابزار به معامله‌گران، از معامله‌کردن با ابزار، هم امن‌تر است و هم برای یک برنامه‌نویس با سرمایهٔ صفر، سریع‌تر به پول می‌رسد.**
88
+
89
+ ## دستمزد و موقعیت شما
90
+
91
+ اگر فقط یک برنامه‌نویس ساده هستید، جای شما در این پروژه «سازندهٔ سیستم» است، نه «مدیر سرمایه». سه سناریو:
92
+
93
+ - **پروژه‌ای (امن):** مبلغ ثابت برای هر فاز، تحویل کد و مستندات. پیشنهاد: معادل درآمد سه تا شش ماه یک برنامه‌نویس، بسته به دامنه.
94
+ - **اشتراک (بهتر):** همان سیستم را به چند شرکت و کارگزاری اجاره بدهید؛ درآمد پیوسته و ریسک پخش‌شده.
95
+ - **سهیم در سود (فقط با شرط):** اگر شرکت اصرار داشت، فقط برای رشته‌ای که خودتان قانونی می‌دانید، با سقف مسئولیت مشخص، و با این جمله در قرارداد که «حداکثر ضرر قابل مطالبه، سقف پرداخت دریافتی شماست، نه بیشتر».
96
+
97
+ ## سه چیز که این پروژه را می‌کشد
98
+
99
+ ۱. وعدهٔ سود به شرکت، در گفت‌وگوی شفاهی. همان جمله بعداً علیه شما استفاده می‌شود.
100
+ ۲. اتصال مستقیم سفارش بدون نظارت انسان. تخلف، مسدودی حساب و از دست رفتن کار.
101
+ ۳. تماس با «کلید دادهٔ رایگان» ناشناس و دادن دسترسی حساب. کلاهبرداری رایج این بازار است.
102
+
103
+ ## نسخهٔ امروز چه می‌تواند بکند
104
+
105
+ همین حالا در همین محیط، یک نمونهٔ کارآمد ساخته شد: موتور ریاضی `derivatives_scout.py` با دروازه‌های نقدشوندگی، محاسبهٔ بازده پس از کارمزد و آزمون‌های واحد. قدم بعدی، وصل کردن آن به tsetmc و کدال و پروندهٔ دفتر معاملات است. برای اجرای آزمایشی روی داده‌های ساختگی، پروندهٔ `README-FA.md` همین پوشه و بخش «اجرا» را ببینید.
station/docs/05-data-routes-fa.md ADDED
@@ -0,0 +1,159 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # بررسی سه مسیر داده، پیش از هر خرید (۲۲ سپتامبر ۲۰۲۶)
2
+
3
+ **پرسش شما:** «قبل از خرید بگو اینها به کار می‌خورد یا نه.» پس این سند هیچ‌چیز نمی‌فروشد؛ فقط
4
+ سه مسیر را با نیاز واقعی ایستگاه می‌سنجد و می‌گوید امروز چه بخریم، چه نخریم، و چه چیزی را
5
+ اول باید تست کنیم.
6
+
7
+ > **داوری کوتاه.** امروز **هیچ‌چیز نخرید**. مسیر رایگان (APIهای عمومی بازار) کار اصلی را
8
+ > انجام می‌دهد؛ **وجه تضمین** را هیچ منبع داده‌ای به شما نمی‌دهد و باید از سامانهٔ کارگزاری
9
+ > خوانده شود؛ و **پوش لحظه‌ای (وب‌سوکت)** برای این برنامه لازم نیست، چون افق تصمیم این
10
+ > راهبردها دقیقه‌ای و ساعتی است، نه میلی‌ثانیه‌ای.
11
+
12
+ ---
13
+
14
+ ## ۱. ایستگاه دقیقاً چه می‌خواهد؟
15
+
16
+ پیش از داوری دربارهٔ فروشنده‌ها، اول فهرست نیاز خودمان. تصمیم‌های ایستگاه روی پنج خانوادهٔ
17
+ راهبرد بسته است: پایهٔ نقدی‌آتی، باکس اسپرد، تبعی، پوشش‌داده‌شده، و تساوی پوت‌کال.
18
+
19
+ | میدان داده | برای چه راهبردی | تغییرش چقدر تند است؟ | از کجا می‌آید؟ |
20
+ | --- | --- | --- | --- |
21
+ | قیمت پایه سهم یا صندوق | همه | دقیقه‌ای | رایگان (API عمومی بازار) |
22
+ | قیمت آتی | پایهٔ نقدی‌آتی | دقیقه‌ای | رایگان در بعضی سرویس‌ها (نوع «آتی») |
23
+ | قیمت اعمال و پرمیوم اختیار | باکس، پوشش‌داده‌شده، تساوی | دقیقه‌ای | نیمه‌رایگان و ناقص؛ بعضی سرویس‌ها دارند |
24
+ | روز تا سررسید | همه | روزانه (تاریخ) | قابل محاسبه، از تقویم خودتان |
25
+ | نقدشوندگی و اسپرد | دروازهٔ ریسک | دقیقه‌ای | نیمه‌رایگان (ریزمعاملات) |
26
+ | **وجه تضمین هر قرارداد** | همهٔ اهرمی‌ها | **روزانه، اعلامی** | **فقط سامانهٔ کارگزاری** |
27
+ | تاریخ قیمت‌ها برای پس‌آزمایی | سنجش موتور | گذشته | سرویس پولی، یا ثبت روزانهٔ خودتان |
28
+
29
+ **نتیجهٔ مهم این جدول:** شش میدان از هفت میدان با دادهٔ رایگان یا نیمه‌رایگان پر می‌شود.
30
+ میدان هفتم (وجه تضمین) **فروشی نیست** و ساختارش هم این‌طور است که کارگزاری هر روز اعلام می‌کند.
31
+ پس «خرید داده» مسئلهٔ اصلی این برنامه نیست؛ «ثبت روزانهٔ وجه تضمین» مسئلهٔ اصلی است و
32
+ ایستگاه همین را با فرم اعداد کارگزاری حل کرده است (شصت ثانیه در روز).
33
+
34
+ ---
35
+
36
+ ## ۲. مسیر ۱: خرید وب‌سرویس رسمی اطلاعات بورس (پولی)
37
+
38
+ **چه چیزی می‌دهد:** دادهٔ رسمی و سازمانی، قیمت پایان روز و ریز داده، قرارداد و فاکتور،
39
+ پشتیبانی. برای شرکتی که می‌خواهد سند رسمی داشته باشد، این مهم است.
40
+
41
+ **چه چیزی نمی‌دهد:** وجه تضمین قراردادهای شما (آن را کارگزاری اعلام می‌کند)، و
42
+ «تصمیم»؛ هیچ سرویس داده‌ای نمی‌گوید چه بخر.
43
+
44
+ **هزینه:** در منابع عمومی، خودِ فروشندگان دادهٔ جایگزین، قیمت وب‌سرویس رسمی را «نجومی»
45
+ توصیف می‌کنند و همین را دلیل ساخت سرویس رایگانشان می‌دانند
46
+ ([brsapi](https://brsapi.ir/about-tsetmc-stock-exchange-free-bourse-api/)). عدد دقیق را باید
47
+ از خود فروشنده بگیرید؛ ما عدد حدسی نمی‌نویسیم.
48
+
49
+ **داوری: فعلاً نه.** سه دلیل:
50
+ ۱. امروز سابقهٔ ثبت‌شدهٔ شما «صفر روز» است؛ خرید داده پیش از دیدن اینکه موتور روزانه
51
+ فرصت پیدا می‌کند یا نه، پول جلوتر از شاهد است.
52
+ ۲. وجه تضمین را هم پوشش نمی‌دهد؛ پس همان کار دستی سر جایش می‌ماند و «صرفه‌جویی زمانی» کمتر
53
+ از آن است که به نظر می‌رسد.
54
+ ۳. قاعدهٔ کارنامهٔ ایستگاه می‌گوید تا پنج روز کاری با دادهٔ واقعی ثبت نشود، وقت خرید نیست.
55
+
56
+ **چه زمانی بله:** اگر (الف) کارنامه «آماده» شد، (ب) دفتر نشان داد روزان�� فرصت واقعی وجود دارد،
57
+ و (ج) **خریدار شرکت باشد نه شما**، چون آن‌وقت به فاکتور رسمی و قرارداد نیاز دارد و ارزان‌بودن
58
+ برای یک شرکت موضوعیت ندارد. در آن حالت، مسیر رسمی انتخاب درست است.
59
+
60
+ ---
61
+
62
+ ## ۳. مسیر ۲: سرویس‌های عمومی بازار (رایگان و نیمه‌رایگان، بدون قرارداد)
63
+
64
+ **نمونه‌ها:** سرویس رایگان کلیددار روی دادهٔ tsetmc (شامل نوع «آتی»، ریزمعاملات و اوراق) مانند
65
+ [brsapi](https://brsapi.ir/) · سرویس توکن‌دار با کندل دو‌دقیقه‌ای و تاریخچهٔ اختیار مانند
66
+ [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/) ·
67
+ و بسته‌های پایتونی مانند `tsetmc-api` و `codal-tsetmc`.
68
+
69
+ **چه چیزی می‌دهد:** قیمت پایه، بخش زیادی از قیمت آتی و اختیار، ریزمعاملات، و تاریخچهٔ روزانه
70
+ برای پس‌آزمایی. هزینه: صفر یا نزدیک صفر.
71
+
72
+ **ریسک‌های واقعی که باید بدانید (و در برنامه هم برچسب می‌خورند):**
73
+ - این سرویس‌ها رسمی نیستند؛ «بی‌تعهد» هستند و ممکن است قطع شوند یا ساختار خروجی عوض شود.
74
+ - داده از پیمایش سایت مرجع می‌آید؛ پس تأخیر دارد و ممکن است در ساعت‌های شلوغ ناقص باشد.
75
+ - شرایط استفادهٔ سایت مرجع ممکن است پیمایش خودکار را محدود کند؛ مسئولیتش با شماست.
76
+ - هیچ‌کدام «وجه تضمین» نمی‌دهند.
77
+
78
+ **داوری: بله، همین امروز.** این مسیر همان کاری را می‌کند که برای این برنامه لازم است:
79
+ قیمت هر دقیقه یا هر چند دقیقه، رایگان، بدون کلید بانکی و بدون قرارداد.
80
+
81
+ **تست پیش از اتکا (روی رایانهٔ خودتان، نه از بیرون ایران):** در گام ۲ دکمهٔ «اتصال خودکار»
82
+ را بزنید؛ ایستگاه چند منبع رایگان را امتحان می‌کند، پاسخ را می‌خواند، عدد را عقلی می‌سنجد
83
+ (صفر نباشد، تاریخ نباشد، بیرون بازهٔ معقول نباشد) و دلیل موفقیت یا شکست هر منبع را فارسی
84
+ می‌گوید. نتیجهٔ همین آزمون، معیار انتخاب شماست، نه تبلیغ فروشنده.
85
+
86
+ > **آنچه در محیط ساخت برنامه دیدیم:** دسترسی به سامانه‌های ایرانی از بیرون کشور بسته است
87
+ > (پاسخ `000` و خطای گواهی). یعنی ما نمی‌توانیم به‌جای شما این مسیر را تأیید کنیم؛ به همین
88
+ > دلیل کل این آزمون را به‌صورت دکمه در خود برنامه گذاشتیم تا روی رایانهٔ شما اجرا شود.
89
+
90
+ ---
91
+
92
+ ## ۴. مسیر ۳: پوش لحظه‌ای از کارگزاری یا از سازمان بورس (وب‌سوکت)
93
+
94
+ **واقعیت بازار:** دسترسی به API سفارش و دادهٔ لحظه‌ای، محصول عمومی کارگزاری‌ها نیست؛
95
+ سامانهٔ معاملات آنلاین رایگان است ولی برای چشم و دست انسان ساخته شده، نه برای برنامه.
96
+ گرفتن دسترسی برنامه‌نویسی معمولاً پاسخ «چنین اجازه‌ای داده نمی‌شود» می‌گیرد
97
+ ([پرسش و پاسخ کارگزاری کاریزما](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/)).
98
+ مسیر مستقیم از سازمان بورس هم عملاً به شرکت‌های دارای مجوز (مثل بازارگردان‌ها) می‌رسد.
99
+
100
+ **و نکتهٔ فنی:** برنامهٔ شما به پوش لحظه‌ای **نیاز ندارد**. راهبردهای نقدی‌آتی، باکس، تبعی و
101
+ پوشش‌داده‌شده در بازهٔ روز و ساعت بسته می‌شوند، نه در میلی‌ثانیه. تفاوت «خواندن هر پنج دقیقه»
102
+ با «پوش لحظه‌ای» در تصمیم این راهبردها صفر است؛ فقط هزینهٔ پیچیدگی را بالا می‌برد.
103
+
104
+ **داوری: پیگیری کنید، ولی برنامهٔ کاری‌تان را روی آن نبندید.** اگر کارگزاری‌تان روزی دسترسی
105
+ برنامه‌نویسی داد، ایستگاه همین حالا آمادهٔ گرفتن داده است (قالب نشانی و مسیر JSON در گام ۲
106
+ هر ساختاری را می‌پذیرد). تا آن روز، مسیر رایگان کافی است.
107
+
108
+ > **یادآوری قانونی:** معاملات الگوریتمی و تفکیک سفارش توسط مشتریان برخط، طبق ابلاغیهٔ
109
+ > مهر ۱۳۹۹ «تا اطلاع ثانوی» ممنوع است. ایستگاه به همین دلیل **هیچ سفارشی ارسال نمی‌کند**؛
110
+ > فقط حساب می‌کند و بستهٔ سفارش چاپی برای اجرای انسانی می‌سازد.
111
+
112
+ ---
113
+
114
+ ## ۵. جدول تطبیق: کدام مسیر کدام نیاز را می‌پوشاند
115
+
116
+ | نیاز ایستگاه | مسیر ۱ (رسمی پولی) | مسیر ۲ (عمومی رایگان) | مسیر ۳ (پوش لحظه‌ای) |
117
+ | --- | --- | --- | --- |
118
+ | قیمت پایه و آتی | ✅ | ✅ | ✅ |
119
+ | قیمت اعمال و پرمیوم اختیار | ✅ | ⚠️ ناقص؛ باید نماد‌به‌نماد تست شود | ✅ |
120
+ | ریزمعاملات و نقدشوندگی | ✅ | ✅ در بعضی سرویس‌ها | ✅ |
121
+ | **وجه تضمین** | ❌ | ❌ | ❌ (فقط کارگزاری) |
122
+ | تاریخچه برای پس‌آزمایی | ✅ | ⚠️ کوتاه یا ناقص | ❌ |
123
+ | هزینه | بالا | صفر | نیازمند قرارداد |
124
+ | در دسترس بودن برای شما | قابل خرید | همین حالا | بسته |
125
+ | تناسب با افق تصمیم ایستگاه | بیشتر از نیاز | کافی | بیشتر از نیاز |
126
+
127
+ **جمع‌بندی جدول:** برای شروع، مسیر ۲ کافی است؛ برای ارائهٔ رسمی به شرکت، مسیر ۱ معنی دارد؛
128
+ مسیر ۳ الان بسته است و نیازی هم به آن نداریم.
129
+
130
+ ---
131
+
132
+ ## ۶. قاعدهٔ خرید: چه زمانی و چه چیزی
133
+
134
+ دروازهٔ سه‌شرطی (همان چیزی که کارنامهٔ ایستگاه می‌سنجد):
135
+
136
+ ۱. **کارنامهٔ آزمون «آماده» شود:** ده روز ثبت‌شده، پنج روز با دادهٔ واقعی، شصت درصد بازسنجی‌شده،
137
+ سه حرکت معنادار، زنجیرهٔ سالم.
138
+ ۲. **دفتر نشان بدهد دادهٔ رایگان کجا کوتاه می‌آید:** مثلاً «چند فرصت را دیر دیدیم چون قیمت
139
+ آتی در سرویس رایگان نبود». اگر چنین چیزی در دفتر ثبت نشد، خریدی هم لازم نیست.
140
+ ۳. **خریدار مشخص باشد:** اگر خودتان می‌خرید، ارزان‌ترین مسیر کافی را انتخاب کنید. اگر شرکت
141
+ می‌خرد، مسیر رسمی با فاکتور را انتخاب کنید و بحث قیمت را به آن‌ها بسپارید.
142
+
143
+ **چک‌لیست پیش از امضای هر خرید:** نمونهٔ داده را برای نمادهای واقعی خودتان بگیرید ·
144
+ پوشش «آتی» و «اختیار» را ببینید · تاریخچهٔ حداقل شش‌ماهه برای پس‌آزمایی بخواهید ·
145
+ شرایط استفاده و محدودیت نرخ درخواست را بخوانید · امکان پرداخت ریالی و صدور فاکتور را بپرسید ·
146
+ و در پایان، همان قالب نشانی را در گام ۲ ایستگاه بگذارید و «آزمایش اتصال» را بزنید؛
147
+ اگر عدد سالم آمد، تازه آن‌وقت خرید معنی دارد.
148
+
149
+ ---
150
+
151
+ ## ۷. صداقت این سند
152
+
153
+ - هیچ‌کدام از سه مسیر را ما نتوانستیم از محیط ساخت برنامه روی دادهٔ واقعی ایرانی آزمایش کنیم
154
+ (دسترسی شبکه‌ای از بیرون کشور بسته است). به‌جای ادعای بی‌شاهد، ابزار آزمون را در خود برنامه
155
+ گذاشتیم و نتیجه‌اش را به شما سپردیم.
156
+ - رتبه‌بندی قیمت‌ها از زبان فروشندگان داده می‌آید، نه از فاکتور. عدد را از فروشنده بگیرید.
157
+ - هیچ‌جای این سند وعدهٔ سود نمی‌دهد؛ بحث فقط «چه داده‌ای برای تصمیم لازم است» است.
158
+
159
+ ✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · 📱 [+989126630554](tel:+989126630554) · ✈️ [Telegram: Mojarabian](https://t.me/Mojarabian) · 📸 [Instagram: Mojarabian.Art](https://instagram.com/Mojarabian.Art)
station/docs/06-data-feasibility-fa.md ADDED
@@ -0,0 +1,126 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # چطور مسیرهای داده را بسنجیم و چه زمانی بخریم (۲۲ سپتامبر ۲۰۲۶)
2
+
3
+ این سند پاسخ همان جملهٔ شماست: «اول بررسی کن ببین قبل از خرید اینها به کار می‌خورد یا نه».
4
+ پس این‌جا هیچ‌چیز فروخته نمی‌شود؛ فقط یک ابزار سنجش، یک قاعدهٔ تصمیم، و یک برگهٔ استعلام قیمت هست.
5
+
6
+ > **داوری یک‌خطی:** امروز چیزی نخرید. سنجش رایگان را روی رایانهٔ خودتان اجرا کنید؛ اگر جواب داد،
7
+ > همان کافی است. خرید فقط وقتی معنی دارد که کارنامهٔ آزمون «آماده» شود و خریدار (خودتان یا شرکت)
8
+ > روشن باشد. سند داوری سه مسیر در `05-data-routes-fa.md` است؛ این سند «چطور بسنجیم» را می‌گوید.
9
+
10
+ ---
11
+
12
+ ## ۱. سنجش، پیش از خرید: چهار پرسش که با عدد جواب می‌گیرند
13
+
14
+ هر مسیر داده‌ای که به شما پیشنهاد می‌شود (رایگان یا پولی)، قبل از هر تصمیمی باید چهار پرسش را
15
+ با عدد جواب بدهد. ابزار `data_sources.py` همین چهار پرسش را می‌پرسد:
16
+
17
+ | پرسش | چرا مهم است | کجا دیده می‌شود |
18
+ | --- | --- | --- |
19
+ | نشانی جواب می‌دهد؟ | نشانی‌ها و ساختار پاسخ مدام عوض می‌شوند | ستون «HTTP» و «نتیجه» در گزارش |
20
+ | چقدر طول می‌کشد؟ | اگر هر درخواست ۵ ثانیه بگیرد، ۵۰ نماد یعنی ۴ دقیقه | ستون «میلی‌ثانیه» |
21
+ | دو فراخوانی پشت‌سرهم، عدد را عوض می‌کند؟ | همان «گپ زمانی» که خودتان اشاره کردید | ستون «تازگی (دو فراخوانی)» |
22
+ | میدان‌های موردنیاز موتور درمی‌آید؟ | «داده هست» با «دادهٔ لازم هست» یکی نیست | ستون «میدان‌های یافته» |
23
+
24
+ نتیجهٔ «بی‌حرکت» در ستون تازگی بد نیست، ولی یک هشدار است: یعنی آن نشانی در بازهٔ چند ثانیه
25
+ تغییر نمی‌کند و برای تصمیم دقیقه‌ای باید با احتیاط استفاده شود.
26
+
27
+ ---
28
+
29
+ ## ۲. دستورهای سنجش، همین حالا
30
+
31
+ روی رایانهٔ خودتان (داخل ایران) این‌ها را اجرا کنید:
32
+
33
+ ```bash
34
+ cd MATERIALS/money/gui
35
+ python data_sources.py --all --symbol فولاد # همهٔ نشانی‌های رایگان سایت مرجع
36
+ python data_sources.py --all --symbol اهرم --code 46348559193224090
37
+ python data_sources.py --ws wss://نشانی-کارگزاری/بازار # سنجش دسترسی پوش لحظه‌ای
38
+ python data_sources.py --sheet # ساخت برگهٔ نیاز داده برای فروشنده
39
+ ```
40
+
41
+ و در رابط گرافیکی، گام ۲، کارت **«امکان‌سنجی مسیرهای داده»**: چهار کادر دارد (نماد، نشانی پوش
42
+ لحظه‌ای، تیک «دادهٔ ساختگی محلی»، دکمهٔ سنجش) و نتیجه را به شکل جدول نشان می‌دهد. تیک «دادهٔ
43
+ ساختگی» فقط برای دیدن شکل خروجی است؛ در گزارش هم صریح برچسب می‌خورد.
44
+
45
+ خروجی‌ها: `gui/data/data-feasibility.html` (گزارش کامل) و `gui/data/data-requirement-sheet.md`
46
+ (برگهٔ استعلام از فروشنده‌ها).
47
+
48
+ ---
49
+
50
+ ## ۳. نیاز واقعی موتور، و آن میدانی که هیچ‌کس نمی‌فروشد
51
+
52
+ | داده | هر چند وقت | از کدام مسیر |
53
+ | --- | --- | --- |
54
+ | قیمت پایه سهم یا صندوق | هر ۱ تا ۵ دقیقه | pull (رایگان یا پولی) |
55
+ | قیمت آتی | هر ۱ تا ۵ دقیقه | pull؛ در سرویس‌های رایگان جداگانه تست شود |
56
+ | قیمت اعمال و پرمیوم اختیار | هر ۱ تا ۵ دقیقه | pull؛ پوشش کامل تضمین‌شده نیست |
57
+ | نقدشوندگی و اسپرد | هر ۱ تا ۵ دقیقه | pull (بهترین سفارش‌های خرید و فروش) |
58
+ | روز تا سررسید | روزانه | محاسبهٔ خودمان از تقویم |
59
+ | **وجه تضمین هر قرارداد** | روزانه، اعلامی | **فقط سامانهٔ کارگزاری** |
60
+ | تاریخ قیمت برای پس‌آزمایی | گذشته | سری روزانه؛ در سرویس رایگان کوتاه است |
61
+
62
+ جملهٔ کلیدی: **وجه تضمین فروشی نیست.** کارگزاری هر روز اعلامش می‌کند و باید از سامانه برداشته شود.
63
+ این یعنی بحث «خرید داده» مسئلهٔ اصلی شما نیست؛ مسئلهٔ اصلی ثبت روزانه�� همان یک عدد است و ایستگاه
64
+ همین را با فرم اعداد کارگزاری حل کرده است (شصت ثانیه در روز).
65
+
66
+ ---
67
+
68
+ ## ۴. ایستگاه با دادهٔ گپ‌دار و کهنه چه می‌کند؟
69
+
70
+ سرویس رایگان بی‌تعهد است، پس برنامه باید در برابر گپ و کهنگی صادق باشد:
71
+
72
+ - **برچسب تازگی:** نوار بالای صفحه می‌گوید داده «زنده» است یا «از حافظهٔ نهان» یا «کهنه».
73
+ - **حافظهٔ نهان با مهلت:** اگر سرویس جواب ندهد، از آخرین پاسخ سالم استفاده می‌شود و همان را
74
+ با تاریخ و ثانیهٔ کهنگی اعلام می‌کند؛ عدد قدیمی به‌جای دادهٔ زنده جا زده نمی‌شود.
75
+ - **شکست صریح:** اگر هیچ قیمتی نیامد، وضعیت «ناموفق» و پیام «هیچ قیمتی از سرویس نیامد» نشان داده
76
+ می‌شود و تازگی «نامعلوم» می‌مانَد (سنجهٔ آزمون، بند «شکست دادهٔ زنده»).
77
+ - **سنجهٔ نرخ واحد:** اگر یک نشانی برای چند نماد عیناً یک عدد بدهد (مثل نرخ ارز)، برنامه آن را
78
+ «جزئی» اعلام می‌کند و می‌گوید این قیمت هر نماد نیست.
79
+ - **تصمیم روی دادهٔ کهنه:** در بازسنجی، برنامه همیشه قیمت تازه می‌خوانَد و حافظهٔ نهان را دور می‌زند؛
80
+ اگر قیمت تازه نیاید، ردیف با وضعیت «دادهٔ تازه نبود» گزارش می‌شود، نه با عدد حدسی.
81
+ - **سنجش دو فراخوانی:** همین ابزار به شما می‌گوید کدام نشانی در بازهٔ چند ثانیه تازه می‌شود و
82
+ کدام بی‌حرکت است، تا بدانید برای تصمیم دقیقه‌ای به کدام‌شان تکیه کنید.
83
+
84
+ ---
85
+
86
+ ## ۵. برگهٔ نیاز داده: پیش از هر تماس با فروشنده، این را بفرستید
87
+
88
+ `python data_sources.py --sheet` یک برگه می‌سازد (`gui/data/data-requirement-sheet.md`) که
89
+ همهٔ فروشنده‌ها را با یک معیار مقایسه می‌کند: جدول دادهٔ موردنیاز با نرخ به‌روزرسانی، ستون
90
+ «دارید؟»، و پنج پرسش فنی (قالب دسترسی، احراز هویت و محدودیت نرخ درخواست، پایداری و پرکردن
91
+ دوبارهٔ داده، پرداخت ریالی و فاکتور، و اجازهٔ استفاده در یک سامانهٔ تصمیم‌یار).
92
+
93
+ با این برگه سه استعلام بگیرید و جواب‌ها را کنار هم بگذارید؛ بعد همان قالب نشانی فروشندهٔ برنده
94
+ را در گام ۲ ایستگاه بگذارید و «آزمایش اتصال» را بزنید. اگر عدد سالم آمد، تازه آن‌وقت خرید معنی دارد.
95
+
96
+ ---
97
+
98
+ ## ۶. قاعدهٔ خرید (دروازهٔ سه‌شرطی)
99
+
100
+ ۱. **کارنامهٔ آزمون «آماده» شود:** ده روز ثبت‌شده، پنج روز با دادهٔ واقعی، شصت درصد بازسنجی‌شده،
101
+ سه حرکت معنادار (دست‌کم یکی بازتر و یکی بسته)، و زنجیرهٔ هش سالم.
102
+ ۲. **دفتر نشان بدهد دادهٔ رایگان کجا کوتاه می‌آید:** مثلاً «چند فرصت را دیر دیدیم چون قیمت آتی
103
+ در سرویس رایگان نبود». اگر چنین چیزی در دفتر ثبت نشد، خریدی لازم نیست.
104
+ ۳. **خریدار روشن باشد:** اگر خودتان می‌خرید، ارزان‌ترین مسیر کافی را بردارید. اگر شرکت می‌خرد،
105
+ مسیر رسمی با فاکتور و قرارداد را انتخاب کنید و چانه‌زنی قیمت را به آن‌ها بسپارید.
106
+
107
+ **دربارهٔ پوش لحظه‌ای (وب‌سوکت و جریان RLC):** اول با `--ws` بسنجید که سرویس اصلاً دسترسی‌پذیر
108
+ است یا نه. بعد یادتان باشد که این برنامه به آن نیازی ندارد: راهبردهای نقدی‌آتی، باکس، تبعی و
109
+ پوشش‌داده‌شده در بازهٔ ساعت بسته می‌شوند، نه میلی‌ثانیه. اگر روزی کارگزاری دسترسی داد، ایستگاه
110
+ همین حالا آمادهٔ گرفتنش است؛ تا آن روز، مسیر pull کافی است.
111
+
112
+ **یادآوری قانونی:** معاملات الگوریتمی و تفکیک سفارش توسط مشتریان برخط، طبق ابلاغیهٔ مهر ۱۳۹۹
113
+ «تا اطلاع ثانوی» ممنوع است. ایستگاه هیچ سفارشی ارسال نمی‌کند و فقط حساب می‌کند.
114
+
115
+ ---
116
+
117
+ ## ۷. صداقت این سند
118
+
119
+ - سامانه‌های ایرانی از محیط ساخت برنامه در دسترس نیستند (پاسخ خالی و خطای گواهی). پس هر عددی
120
+ دربارهٔ سرویس‌های ایرانی باید **روی رایانهٔ خودتان** گرفته شود؛ همین دلیلِ بودنِ دکمهٔ سنجش در
121
+ گام ۲ است.
122
+ - الگوهای نشانی‌ها در `data_sources.py` نوشته شده‌اند و ممکن است سرویس‌ها تغییرشان بدهند. ابزار
123
+ دقیقاً برای همین ساخته شده: اگر ساختار عوض شود، «سرخ» می‌شود و می‌گوید کدام میدان پیدا نشد.
124
+ - هیچ‌جای این سند وعدهٔ سود نمی‌دهد و هیچ ادعایی دربارهٔ کیفیت سرویس‌ها بدون سنجش نوشته نشده است.
125
+
126
+ ✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · 📱 [+989126630554](tel:+989126630554) · ✈️ [Telegram: Mojarabian](https://t.me/Mojarabian) · 📸 [Instagram: Mojarabian.Art](https://instagram.com/Mojarabian.Art)
station/docs/07-zero-cost-test-fa.md ADDED
@@ -0,0 +1,113 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # چرا هیچ‌چیز نمی‌خریم — و با صفر تومان چه تست عملیاتی می‌شود گرفت (۲۲ سپتامبر ۲۰۲۶)
2
+
3
+ این سند پاسخ همان دو پرسش شماست: «آیا باید Jev را بخرم؟» و «راه دیگری نیست که کارفرما یک تست
4
+ عملیاتی واقعی بگیرد؟». پاسخ کوتاه: **هیچ‌چیز لازم نیست بخرید؛ و بله، راه بیهزینه و قابل‌اتکا هست.**
5
+
6
+ > **داوری یک‌خطی:** Jev برای این برنامه لازم نیست. سه مسیر تست بیهزینه هست که امروز روی لپ‌تاپ
7
+ > شما اجرا می‌شود؛ هزینهٔ واقعی فقط وقتی معنی پیدا می‌کند که خریدار مشخصی (شرکت) با فاکتور و
8
+ > قرارداد پشت میز باشد.
9
+
10
+ ---
11
+
12
+ ## ۱. پرسش «Jev را بخرم؟» — جواب با دلیل
13
+
14
+ کل برنامه دو لایه دارد و مهم است این دو را از هم جدا کنیم:
15
+
16
+ | لایه | کارش | به سرویس هوش مصنوعی نیاز دارد؟ |
17
+ | --- | --- | --- |
18
+ | موتور تصمیم (ریاضی) | نرخ سد، بازده سالانه، آربیتراژ، اندازهٔ موقعیت، دروازه‌های ریسک | **نه.** صرفاً حساب است و روی هر لپ‌تاپی بی‌اینترنت هم کار می‌کند. |
19
+ | لایهٔ خبر و زبان | خلاصه‌کردن اطلاعیهٔ کدال، خواندن متن فارسی، نوشتن گزارش | نه برای کارکرد؛ ولی بهتر است. |
20
+
21
+ لایهٔ دوم الان با **قاعده‌های کلیدواژه‌ای** کار می‌کند: کدال را می‌خواند، کلمه‌های مهم را
22
+ می‌شمارد، امتیاز می‌دهد و کنار سیگنال می‌گذارد. کار می‌کند و هزینه ندارد. اگر روزی خواستید
23
+ این لایه باهوش‌تر شود، دو راه بیهزینه هست و هیچ‌کدام «خرید سرویس» نیست:
24
+
25
+ - **مدل محلی روی همان لپ‌تاپ:** یک مدل کوچک فارسی‌خوان با ابزار آزاد نصب می‌کنید؛ نه کلید می‌خواهد،
26
+ نه ماهانه، نه داده‌ای به بیرون می‌رود. (کندتر است، ولی برای خلاصه‌کردن چند اطلاعیه در روز بس است.)
27
+ - **همان قاعده‌های فعلی، تا وقتی واقعاً کم بیاید:** معیار ساده است: اگر در دفتر ثبت شد که «فلان
28
+ اطلاعیه را دیر فهمیدیم»، آن‌وقت دربارهٔ ارتقا حرف می‌زنیم. تا آن روز، لایهٔ زبانی گلوگاه شما نیست.
29
+
30
+ پس: **Jev را نخرید.** خرید سرویس هوش مصنوعی، مسئلهٔ امروز شما نیست؛ مسئلهٔ امروز، اجرای
31
+ مراسم روزانه و پرکردن دفتر است.
32
+
33
+ ---
34
+
35
+ ## ۲. سه مسیر تست عملیاتی، همه با هزینهٔ صفر
36
+
37
+ | مسیر | چه چیزی را ثابت می‌کند | هزینه | اینترنت لازم دارد؟ |
38
+ | --- | --- | --- | --- |
39
+ | **الف) خوراک آزمایشی محلی** | کل مسیر فنی زنده کار می‌کند: قیمت می‌آید، تازگی داده سبز می‌شود، دفتر و هشدار و بسته کار می‌کنند | صفر | نه |
40
+ | **ب) دادهٔ واقعی رایگان** (سایت مرجع و tgju از داخل ایران) | با دادهٔ واقعی بازار هم همان مسیر کار می‌کند | صفر | بله |
41
+ | **ج) اعداد کارگزاری با دست** | استقلال کامل از هر سرویس؛ ۶۰ ثانیه در روز | صفر | نه |
42
+
43
+ **مسیر الف (خوراک آزمایشی محلی).** در گام ۲ پروفایل «خوراک آزمایشی محلی» را انتخاب و آزمایش
44
+ کنید. قیمت‌ها هر ثانیه تکان می‌خورند و بعد از چند خواندن، یک رخداد برنامه‌ریزی‌شده بازار را
45
+ جابه‌جا می‌کند تا ببینید سیگنال چطور ظاهر می‌شود. هر جا این داده نمایش داده شود، برچسب
46
+ «ساختگی» می‌خورد — در نوار بالای صفحه، در گزارش، و در بستهٔ تحویل.
47
+
48
+ **مسیر ب (دادهٔ واقعی رایگان).** سنجشش با ابزار امکان‌سنجی در گام ۲ انجام می‌شود: نشانی‌ها را
49
+ می‌زند، می‌گوید کدام جواب داد، چقدر طول کشید، و با دو فراخوانی پشت‌سرهم می‌سنجد که عدد تازه
50
+ می‌شود یا بی‌حرکت است. توجه: سامانه‌های ایرانی از بیرون کشور پاسخ نمی‌دهند؛ این تست را روی
51
+ لپ‌تاپ خودتان (داخل ایران) بزنید.
52
+
53
+ **مسیر ج (اعداد کارگزاری با دست).** همان کاری که از روز اول گفتیم: هر روز صبح، شصت ثانیه،
54
+ عددهای کارگزاری را در فرم گام ۲ وارد می‌کنید. این مسیر هیچ سرویسی نمی‌خواهد و همان چیزی را
55
+ می‌دهد که هیچ فروشندهٔ داده نمی‌دهد: **وجه تضمین**. توجه داشته باشید که برچسب این روزها
56
+ «اعداد دستی کارگزاری» است و در کارنامه هم از روزهای ساختگی جدا شمرده می‌شود.
57
+
58
+ ---
59
+
60
+ ## ۳. آن تستی که کارفرما را قانع می‌کند: آزمون کور
61
+
62
+ مهم‌ترین نکتهٔ این سند همین است. سرمایه‌گذارِ باسواد با «ما سود ساختیم» قانع نمی‌شود؛ با این
63
+ قانع می‌شود که **خودش** عددی را حساب کند و ببیند برنامه همان را می‌گوید.
64
+
65
+ در گام ۱۰ (آزمون کور سرمایه‌گذار) شش پرسش عددی و بله/خیر مطرح می‌شود و پاسخ‌ها تا لحظهٔ داوری
66
+ پنهان می‌مانَد. سرمایه‌گذار اول حدس می‌زند، بعد پاسخ برنامه با فرمول و «روش دوم» — که با
67
+ ماشین‌حساب جیبی قابل بازبینی است — رو می‌شود. در همان گام، جدول «آستانهٔ ریزش» نشان می‌دهد
68
+ با عوض‌شدن نرخ سد، کدام راهبرد از دروازه می‌افتد؛ و بخش «حساب‌رسی واقعیت» یک معاملهٔ گذشته را
69
+ با کارمزدهای واقعی ایران می‌شمارد.
70
+
71
+ هر ردیف در دفتر زنجیره‌هش‌دار ثبت می‌شود و در پایان، برگهٔ چاپی با جای امضا ساخته می‌شود.
72
+ اگر کسی بعداً عددی را عوض کند، کلید زنجیره می‌شکند و برگه باطل می‌شود. همین «قابل بازبینی بودن»
73
+ است که اعتماد می‌سازد، نه وعده.
74
+
75
+ ---
76
+
77
+ ## ۴. پروتکل تست عملیاتی بیهزینهٔ ۱۰ روزه (برای کارفرما)
78
+
79
+ ۱. **روز صفر:** پروندهٔ سرمایه‌گذار و برگهٔ آزمون کور را بسازید و همان جلسه را با سرمایه‌گذار
80
+ برگزار کنید (گام ۱۰ و ۹). او خودش حدس می‌زند و خودش با ماشین‌حساب چک می‌کند.
81
+ ۲. **روزهای ۱ تا ۱۰ (کاری):** هر روز فقط دکمهٔ «اجرای مراسم امروز» زده می‌شود؛ خوراک
82
+ آزمایشی یا اعداد کارگزاری، هر کدام که در دسترس بود.
83
+ ۳. **در پایان هر روز:** دفتر را ثبت کنید و کارنامه را نگاه کنید. کارنامه سه چیز را جدا
84
+ می‌شمارد: روزهای ثبت‌شده، روزهای با دادهٔ واقعی، و بازسنجی‌شده‌ها.
85
+ ۴. **روز ۱۰:** گزارش دفتر و زنجیرهٔ هش را نشان دهید و همان پرونده را برای شرکت بفرستید.
86
+ اگر کارنامه «آماده» شد، تازه دربارهٔ دادهٔ خریدنی و جلسهٔ شرکت حرف می‌زنیم.
87
+
88
+ شرط پایانِ صادقانه: اگر کارنامه «آماده» نشد، یعنی ریاضیِ بازار در آن ده روز سود کافی نداشته؛
89
+ این هم نتیجهٔ معتبری است و همان را می‌نویسیم، نه یک عدد آراسته.
90
+
91
+ ---
92
+
93
+ ## ۵. آنچه واقعاً پول لازم دارد (و امروز لازم نیست)
94
+
95
+ - **دادهٔ رسمی با قرارداد و فاکتور:** برای وقتی که شرکت تصمیم بگیرد بخرد. تا آن روز، مسیرهای
96
+ بیهزینه کافی است.
97
+ - **نگه‌داری و زمان انسان:** هر روز شصت ثانیه ثبت. این «هزینه» به پول نیست، به عادت است.
98
+ - **سخت‌افزار:** همان لپ‌تاپ خودتان. برنامه به سرور بیرونی وصل نمی‌شود مگر خودتان اجازه بدهید.
99
+
100
+ نتیجه: **برای شروع هیچ‌چیز نخرید.** اول ۱۰ روز داده جمع کنید؛ اگر ریاضی درست کار کرد، خرید
101
+ داده تازه معنی پیدا می‌کند.
102
+
103
+ ---
104
+
105
+ ## ۶. صداقت این سند
106
+
107
+ - هیچ عددی در این سند وعدهٔ سود نیست؛ فقط مسیر و شرط است.
108
+ - دسترسی به سامانه‌های ایرانی از بیرون کشور ممکن نیست؛ برای همین همهٔ آزمون‌های واقعی باید روی
109
+ رایانهٔ خودتان اجرا شود.
110
+ - برنامه هیچ سفارشی نمی‌فرستد (ابلاغیهٔ مهر ۱۳۹۹ معاملات الگوریتمی را ممنوع کرده است)؛ همهٔ کار
111
+ تصمیم‌یار است و اجرا با انسان.
112
+
113
+ ✍️ تهیه���کنندهٔ جزوات: Masoud Mojarabian · 📱 [989126630554](tel:+989126630554) · ✈️ [Telegram: Mojarabian](https://t.me/Mojarabian) · 📸 [Instagram: Mojarabian.Art](https://instagram.com/Mojarabian.Art)
station/docs/08-differentiation-and-trust-fa.md ADDED
@@ -0,0 +1,187 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # تمایز و اعتماد: چرا شرکت برای این برنامه پول می‌دهد (۲۲ سپتامبر ۲۰۲۶)
2
+
3
+ پرسش شما سه بخش داشت: چه چیزی در این برنامه هست که در ابزارهای فارسی نبوده، شرکت چطور می‌تواند
4
+ مطمئن شود، و نقطهٔ قوتی که باید بولد شود کدام است. این سند پاسخ صادقانهٔ هر سه است، با شاهد داخل
5
+ برنامه و دموی یک‌کلیکی برای هر ادعا.
6
+
7
+ > **جمله‌ای که باید بولد شود:**
8
+ > ابزارهای دیگر می‌گویند «چه چیزی ممکن است سود بدهد»؛ این برنامه می‌گوید «چه چیزی با کارمزد
9
+ > واقعی، اسپرد، نقدشوندگی و وجه تضمین شما می‌مانَد» و اگر نمی‌مانَد، دلیلش را با عدد می‌نویسد.
10
+
11
+ ---
12
+
13
+ ## ۱. اول انصاف: بازار فارسی چه دارد و چه ندارد
14
+
15
+ ابزارهای خوبی در ایران هست و ما جایگزین‌شان نیستیم: دیده‌بان‌های اختیار معامله با فرمول‌نویسی و
16
+ فیلتر (مثل آپشن‌باز و بامبو)، ماشین‌حساب بلک‌شولز، IV و دلتا، نمودار استراتژی، نقشهٔ بازار، و
17
+ پنل‌های معاملاتی کارگزاری. همهٔ این‌ها **داده و ابزار تحلیل** می‌دهند. جای خالی جای دیگری است:
18
+
19
+ | پرسش | دیده‌بان‌های تحلیل بازار | پنل کارگزاری | این برنامه |
20
+ | --- | --- | --- | --- |
21
+ | قیمت و IV و دلتا | ✅ | ✅ | از همان‌ها می‌گیرد (یا دستی وارد می‌شود) |
22
+ | فیلتر و اسکرینر | ✅ | ➖ | ➖ (کار آن‌ها نیست) |
23
+ | سود خالص پس از کارمزد و اسپرد و مالیات ایران | ❌ | ❌ | ✅ موتور با نرخ‌های واقعی |
24
+ | «می‌ماند یا می‌افتد» با دلیل دروازه‌ها | ❌ | ❌ | ✅ با رد صریح |
25
+ | نقطهٔ برگشت (تا کجا معامله بماند) | ❌ | ❌ | ✅ عدد دقیق |
26
+ | فاصله تا مارجین‌کال و پول در معرض خطر | ❌ | ➖ | ✅ با حد نگهداری ۷۰٪ |
27
+ | شاهد حسابرسی‌پذیر برای شرکت | ❌ | ➖ | ✅ اثر انگشت + زنجیرهٔ هش + برگهٔ امضا |
28
+ | جداسازی روز ساختگی از روز واقعی | (کار آن‌ها نیست) | (کار آن‌ها نیست) | ✅ در کارنامه و دفتر |
29
+
30
+ یعنی ما نه رقیب دیده‌بان‌ها هستیم و نه پنل معاملاتی؛ **لایهٔ تصمیم و شاهد** روی همان داده‌ای
31
+ هستیم که آن‌ها می‌دهند. این دقیقاً چیزی است که یک شرکت با پول واقعی لازم دارد.
32
+
33
+ ---
34
+
35
+ ## ۲. هشت نقطهٔ قوت، هر کدام با شاهد و دموی یک‌کلیکی
36
+
37
+ ### ۱) داوری سیگنال ابزار دیگران (بولدترین نقطهٔ تمایز)
38
+
39
+ **ادعا:** سیگنال نرم‌افزار فعلی شرکت را می‌گیریم و با کارمزد، اسپرد، نقدشوندگی و نرخ سد خودشان
40
+ داوری می‌کنیم.
41
+ **شاهد:** `gui/signal_judge.py` و کارت «داوری سیگنال ابزارهای دیگر» در گام ۶.
42
+ **دموی یک‌کلیکی:** نوع راهبرد را از فهرست انتخاب کنید، «نمونهٔ آماده» را بزنید، «داوری کن».
43
+ **ارزش:** یک سیگنال کاغذی که با کارمزد خورده می‌شود، در همان ثانیه رد می‌شود و دلیلش نوشته می‌شود.
44
+
45
+ ### ۲) نقطهٔ برگشت (نقطهٔ بی‌تفاوتی)
46
+
47
+ **ادعا:** برای هر سیگنال می‌گوییم تا کدام قیمت یا پرمیوم یا قیمت اعمال، معامله می‌مانَد؛ از آن
48
+ بدتر، می‌افتد.
49
+ **شاهد:** تابع `break_even` با دو نیم‌کردن روی موتور، و آزمونی که دو طرف نقطه را می‌سنجد.
50
+ **ارزش:** این عدد زبان مذاکره است: برای قیمت آتی، پرمیوم، یا قیمت اعمالی که کارگزاری اعلام می‌کند.
51
+
52
+ ### ۳) فاصله تا مارجین‌کال، با عدد کارگزاری خودشان
53
+
54
+ **ادعا:** برای هر موقعیت می‌گوییم چند درصد حرکت مخالف، حساب را به حد نگهداری می‌رساند؛ چه مقدار
55
+ پول در معرض خطر است؛ و سطح قیمت اخطاریه کجاست.
56
+ **شاهد:** تابع `margin_call` با حد نگهداری پیش‌فرض ۷۰٪ (رویهٔ بورس ایران) و وجه تضمین اولیهٔ
57
+ اختیار فروش ≈۲۰٪ ارزش قرارداد؛ هر دو قابل جایگزینی با عدد کارگزاری.
58
+ **ارزش:** موقعیت‌های «نزدیک لبه» پیش از اخطاریه پیدا می‌شوند، نه بعد از آن. یادآوری: مهلت
59
+ رفع اخطاریه ۲۴ ساعت است و تسویه روزانه انجام می‌شود.
60
+
61
+ ### ۴) دروازه‌های ریسک که «نه» می‌گویند، با دلیل
62
+
63
+ **ادعا:** نقدشوندگی کم، اسپرد بزرگ، بازده غیرواقعی، سقف موقعیت، و جهت غیرقابل‌اجرا (فروش
64
+ استقراضی) همه رد می‌شوند و دلیل هر رد نوشته می‌شود.
65
+ **شاهد:** `gate_checks` در میز + دروازه‌های `signal_judge` + آزمون «فرصت توخالی معرفی نمی‌شود».
66
+ **ارزش:** ابزاری که همیشه «بله» می‌گوید، ابزار نیست؛ تبلیغ است. شرکت با «نه»های مستند پول
67
+ ذخیره می‌کند.
68
+
69
+ ### ۵) حسابرسی‌پذیری عدد (برای مدیر ریسک و حسابرس)
70
+
71
+ **ادعا:** هر عدد تصمیم، دو بار حساب می‌شود: یک بار با موتور، یک بار با حساب دستی مستقل. خروجی
72
+ هر ابزار اثر انگشت دارد؛ دفتر زنجیرهٔ هش دارد.
73
+ **شاهد:** آزمون ۱۰ دقیقه‌ای (۱۵ مورد، دو روش)، اثر انگشت موتور در کارنامه، زنجیرهٔ هش دفتر،
74
+ بستهٔ شاهد با `sha256[:16]` هر پرونده.
75
+ **ارزش:** اگر ردیفی دست‌کاری شود، همان لحظه لو می‌رود. این تفاوت «نرم‌افزار» و «شاهد» است.
76
+
77
+ ### ۶) صداقت ساختاری (که اعتماد را نگه می‌دارد)
78
+
79
+ **ادعا:** پس‌آزمایی بدون آینده‌نگری است؛ روز ساختگی از روز واقعی جدا شمرده می‌شود؛ وقتی سرویس
80
+ داده نمی‌دهد، هیچ عدد ساختگی جای قیمت زنده نمی‌نشیند؛ کارنامه تا آماده نشدن، «ناتمام» می‌مانَد.
81
+ **شاهد:** آزمون‌های ضد آینده‌نگری، برچسب «خوراک آزمایشی محلی (ساختگی)» در نوار و گزارش، و
82
+ «شکست دادهٔ زنده» در کارنامه.
83
+ **ارزش:** مدیری که یک بار ببیند برنامه خودش را رسوا می‌کند، بقیهٔ عددهایش را باور می‌کند.
84
+
85
+ ### ۷) آزمون کور برای سرمایه‌گذار: خودش حساب می‌کند
86
+
87
+ **ادعا:** شش پرسش با پاسخ پنهان؛ سرمایه‌گذار اول حدس می‌زند، بعد پاسخ با فرمول و روش دوم رو
88
+ می‌شود و با ماشین‌حساب جیبی بازبینی می‌شود؛ برگهٔ امضادار با زنجیرهٔ هش ساخته می‌شود.
89
+ **شاهد:** `gui/investor_test.py` و گام ۱۰ رابط گرافیکی.
90
+ **ارزش:** اعتماد با «خودش دید» ساخته می‌شود، نه با اسلاید.
91
+
92
+ ### ۸) استقلال استقرار و انطباق قانونی
93
+
94
+ **ادعا:** بدون ابر و بدون اشتراک اجباری روی رایانهٔ خودشان نصب می‌شود؛ هیچ سفارشی ارسال
95
+ نمی‌کند (ابلاغیهٔ مهر ۱۳۹۹ معاملات الگوریتمی را ممنوع کرده)؛ وجه تضمین را از کارگزاری می‌گیرد،
96
+ نه از فروشندهٔ داده.
97
+ **شاهد:** رابط مرورگری و دسکتاپ محلی، `station.py` بدون هیچ ارسال سفارش، سند `05-data-routes-fa.md`.
98
+ **ارزش:** ریسک انطباق صفر، و دادهٔ شرکت از رایانهٔ خودشان بیرون نمی‌رود.
99
+
100
+ ---
101
+
102
+ ## ۳. معماری اعتماد: چطور شرکت می‌تواند مطمئن شود
103
+
104
+ هفت لایه، از ورودی تا شاهد. هر لایه یک آزمون دارد:
105
+
106
+ ۱. **ورودی با برچسب تازگی:** دادهٔ زنده، حافظهٔ نهان، یا اعداد دستی کارگزاری؛ هر سه از هم جدا و
107
+ برچسب‌دار، و روز ساختگی در کارنامه از روز واقعی جدا شمرده می‌شود.
108
+ ۲. **دروازه‌های ریسک:** پیش از هر تصمیم، فرصت‌های توخالی رد می‌شوند و دلیل رد ثبت می‌شود.
109
+ ۳. **دو روش حساب:** عدد تصمیم دو بار به دو راه مستقل درمی‌آید؛ اختلاف بیش از حد، خودش را لو می‌دهد.
110
+ ۴. **دفتر زنجیره‌هش‌دار:** هر ثبت با گرهٔ هش به ردیف قبل بسته می‌شود؛ عوض‌کردن گذشته، زنجیره را می‌شکند.
111
+ ۵. **بستهٔ شاهد:** یک پوشه با گزارش تصمیم‌ها، سند روش کار، کارنامهٔ آزمون، برگهٔ آزمون، پروندهٔ
112
+ سرمایه‌گذار و اثر انگشت `sha256` هر فایل.
113
+ ۶. **قابل بازتولید بودن:** ه��ان ورودی، همان جواب؛ در مسیر تصمیم هیچ مدل زبانی و هیچ تصادفی نیست.
114
+ ۷. **آزمون‌های خودکار:** ۲۵۸ آزمون واحد، ۵ آزمون خط فرمان ابزار داوری، آزمون ساخت رابط گرافیکی، ۷۶ بررسی
115
+ تعاملی مرورگری، و اجرای واقعی روی موتور.
116
+
117
+ ---
118
+
119
+ ## ۴. «چطور مطمئن شود بخرد و بفروشد؟» — پروتکل پذیرش پنج‌پله‌ای
120
+
121
+ ۱. **آزمون ۱۰ دقیقه‌ای در جلسه:** بگذارید خودشان دو مورد را با ماشین‌حساب چک کنند. اگر یک مورد
122
+ نخواند، بحث تمام است؛ چون هیچ عددی از قبل «درست» فرض نشده.
123
+ ۲. **داوری سیگنال‌های امروز خودشان:** سیگنالی که ابزار فعلی یا تحلیلگرشان داده را وارد کنند؛
124
+ خروجی «می‌ماند/می‌افتد» با دلیل، نقطهٔ برگشت، و فاصله تا مارجین‌کال.
125
+ ۳. **شبیه‌سازی تاریخ:** روی دادهٔ گذشته، با آزمون ضد آینده‌نگری؛ خطای پیش‌بینی منفی هم گزارش می‌شود.
126
+ ۴. **آزمون کاغذی دو هفته‌ای با دادهٔ واقعی:** بدون سفارش، با اعداد کارگزاری، و دفتر زنجیره‌هش‌دار.
127
+ ۵. **تصمیم با شاهد:** بستهٔ گام ۸ جلوی مدیر ریسک. اگر کارنامه «آماده» شد، اجرا با انسان؛ اگر نه،
128
+ همان «ناتمام» نوشته می‌شود.
129
+
130
+ **نکتهٔ قانونی که باید صریح گفته شود:** این برنامه سفارش نمی‌فرستد. معاملات الگوریتمی و تفکیک
131
+ سفارش توسط مشتریان برخط طبق ابلاغیهٔ مهر ۱۳۹۹ ممنوع است. پس ما «دستیار تصمیم با شاهد» می‌فروشیم،
132
+ نه «ربات معامله‌گر». همین صراحت، ریسک حقوقی شرکت را صفر و اعتماد را بیشتر می‌کند.
133
+
134
+ ---
135
+
136
+ ## ۵. اقتصاد: «هر مبلغی» چه اندازه است؟
137
+
138
+ ارزش را با سه عدد می‌شود نشان داد، نه با شعار:
139
+
140
+ - **کارمزد و اسپرد خورنده:** در ایران کارمزد فروش سهم حدود ۰٫۹۶٪ و خرید حدود ۰٫۴۶٪ است (در
141
+ اختیار معامله حدود ۰٫۱۰۳٪ هر طرف، به‌علاوهٔ هزینهٔ اعمال). یک معاملهٔ نوسانی که ابزار سادهٔ
142
+ دیگر «سود ۳٪» نشانش می‌دهد، پس از کارمزد و اسپرد می‌تواند صفر یا منفی شود. حذف سالانه ده
143
+ معاملهٔ کارمزد خورده در پرتفویی متوسط، چند برابر هزینهٔ سالانهٔ این ابزار است.
144
+ - **مارجین‌کال:** یک اخطاریهٔ نگرفته، از هر سود پیش‌بینی‌شده‌ای گران‌تر است. فاصلهٔ مارجین‌کال
145
+ پیش از ورود، اجازهٔ «حد ضرر منطقی» می‌دهد.
146
+ - **شاهد حسابرسی:** برای شرکت، «می‌دانیم چرا این معامله را کردیم و چرا رد شد» به‌تنهایی ارزش
147
+ سازمانی دارد؛ در جلسهٔ هیئت‌مدیره و برای حسابرس قابل ارائه است.
148
+
149
+ **مدل قیمت پیشنهادی (سه پله):** ۱) نصب و آموزش یک‌باره؛ ۲) اشتراک پشتیبانی و به‌روزرسانی
150
+ ماهانه؛ ۳) سفارشی‌سازی و گزارش ماهانه به هیئت‌مدیره. قیمت هر پله را با یک معیار ساده ببندید:
151
+ **حق اشتراک سالانه باید کسری از «کارمزد ذخیره‌شده + زیان پرهیزشده» باشد.** اگر با اعداد واقعی
152
+ شرکت این نسبت زیر یک‌سوم بود، قیمت شما فروش راحت دارد؛ اگر نه، اول ارزش را ثابت کنید.
153
+
154
+ ---
155
+
156
+ ## ۶. سه پرسشی که در جلسه می‌پرسند، و پاسخ آماده
157
+
158
+ **«دادهٔ شما از کجاست و چقدر به‌روز است؟»**
159
+ از همان مسیرهای رسمی و رایگان یا سرویس خودتان؛ تازگی داده و منبعش روی نوار بالای صفحه و در
160
+ گزارش نوشته می‌شود، و اگر سرویس جواب ندهد، وضعیت «کهنه/ناموفق» اعلام می‌شود، نه عدد حدسی.
161
+
162
+ **«اگر اشتباه کند چه؟»**
163
+ هر عدد دو بار حساب می‌شود، هر تصمیم اثر انگشت دارد، و دفتر زنجیره‌هش‌دار است. کارنامه تا
164
+ آماده‌نشدن «ناتمام» می‌مانَد و خطای منفی گزارش می‌شود. همین طراحی، اشتباه را سریع پیدا می‌کند.
165
+
166
+ **«قبلاً هم نرم‌افزار داشتیم؛ چه چیزی تازه است؟»**
167
+ آزمون زنده در همان جلسه: سیگنال نرم‌افزار فعلی‌شان را وارد کنید. در چند ثانیه می‌بینید آن
168
+ سیگنال با کارمزد و ریسک واقعی می‌مانَد یا می‌افتد، تا چه قیمتی می‌مانَد، و چقدر تا اخطاریهٔ
169
+ مارجین فاصله دارد. این چیزی است که در جلسه باید **دیده** شود، نه گفته.
170
+
171
+ ---
172
+
173
+ ## ۷. آنچه ادعا نمی‌کنیم
174
+
175
+ - سود تضمینی نیست؛ هیچ عددی در این اسناد وعدهٔ سود نمی‌دهد.
176
+ - ما جایگزین دیده‌بان‌ها و تحلیل‌های بازار نیستیم؛ لایهٔ تصمیم و شاهد روی آن‌ها هستیم.
177
+ - بسته به کیفیت دادهٔ ورودی، دقت عددها بالا و پایین می‌شود؛ برای همین برچسب تازگی و «شکست
178
+ دادهٔ زنده» عمداً سخت‌گیرانه است.
179
+ - کارگزاری‌ها هر روز وجه تضمین را به‌روزرسانی می‌کنند؛ فاصلهٔ مارجین‌کال باید روزانه با عدد
180
+ تازه بازخوانی شود، نه یک بار برای همیشه.
181
+
182
+ ---
183
+
184
+ **خلاصهٔ یک‌خطی برای مدیرعامل:** ابزارهای دیگر «فرصت» نشان می‌دهند؛ این برنامه «فرصت‌های باقی‌مانده
185
+ پس از کارمزد و ریسک» را نشان می‌دهد، و برای هر عدد شاهد دارد.
186
+
187
+ ✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · 📱 [989126630554](tel:+989126630554) · ✈️ [Telegram: Mojarabian](https://t.me/Mojarabian) · 📸 [Instagram: Mojarabian.Art](https://instagram.com/Mojarabian.Art)
station/docs/09-sell-or-grant-access-fa.md ADDED
@@ -0,0 +1,120 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # بفروشم یا دسترسی بدهم؟ راهنمای واقع‌بینانه برای کسی که تنهاست (۲۲ سپتامبر ۲۰۲۶)
2
+
3
+ این سند پاسخ همان جملهٔ شماست: «من این برنامه را نمی‌فروشم؛ در اختیارت می‌گذارم، تو استفاده کن و
4
+ من همیشه بهترش می‌کنم.» اول صریح می‌گویم: **این جمله، بهترین ایدهٔ این چند روز است.** ولی با یک
5
+ شرط: باید به شکل **قرارداد** گفته شود، نه به شکل تعارف. این سند همان تفاوت را قدم‌به‌قدم می‌گوید.
6
+
7
+ > **داوری یک‌خطی:** نسخه نفروشید. **اجازهٔ استفادهٔ نام‌دار بدهید، پشتیبانی را بخشی از همان
8
+ > قرارداد کنید، و مالکیت و حق بهبود را نزد خودتان نگه دارید.** این مدل، هم پشتیبانی را پوشش
9
+ > می‌دهد، هم درآمد ماهانه می‌سازد، هم لازم نیست مهندس پشتیبانی باشید.
10
+
11
+ ---
12
+
13
+ ## ۱. سه راه پیش پای شما، با سود و زیان واقعی‌شان
14
+
15
+ | راه | چه می‌گیرید | چه از دست می‌دهید | مناسب شما؟ |
16
+ | --- | --- | --- | --- |
17
+ | **الف) فروش نسخه (یک‌باره)** | پول یک‌باره | پشتیبانی و عیب‌یابی برای همیشه، بی‌درآمد بعدی؛ و اگر کد را دستشان بدهید، دیگر لازم نیست شما را نگه دارند | نه |
18
+ | **ب) فروش کد و مالکیت** | پول بیشتر در لحظه | کل ارزش آینده؛ از فردا شما بیرون بازی هستید | نه |
19
+ | **ج) اجازه‌نامهٔ دسترسی + پشتیبانی (پیشنهاد)** | درآمد تکرارشونده، مالکیت نزد شما، هر بهبودی که من می‌دهم ارزش قرارداد شما را بیشتر می‌کند | باید هر ماه چند ساعت وقت بگذارید | **بله** |
20
+
21
+ راه «ج» همان جملهٔ خودتان است، فقط با یک قید: **دسترسی زمان‌دار و نام‌دار**، نه «هر وقت خواستی
22
+ بردار». برای همین در برنامه دو ابزار تازه ساخته شد:
23
+
24
+ - `gui/license.py` — اجازه‌نامهٔ نام‌دار می‌سازد: نام شرکت، مدت، مسئول، امضای `sha256`.
25
+ (`python license.py --grant "نام شرکت" --months 12 --save`)
26
+ - **نمایش وضعیت مجوز در گام ۱ رابط** و **آمدن همان امضا در بستهٔ شاهد (گام ۸)**؛ یعنی شرکت
27
+ می‌بیند این نسخه به نام خودش است و تا چه تاریخی حق استفاده دارد.
28
+
29
+ این کار «DRM» نیست و نمی‌خواهد باشد؛ یک **سند روشن** است: من نسخه نفروختم، اجازه دادم.
30
+
31
+ ---
32
+
33
+ ## ۲. جملاتی که می‌توانید همین فردا بگویید
34
+
35
+ ۱. «من این برنامه را نمی‌فروشم. استفادهٔ نام‌دار به نام شرکت شما را می‌دهم، به‌همراه پشتیبانی و
36
+ به‌روزرسانی. اگر یک روز نخواستید ادامه بدهید، فقط دسترسی تمام می‌شود؛ چیزی خراب نمی‌شود.»
37
+ ۲. «قیمت سه پله دارد: راه‌اندازی و آموزش (یک‌باره)، استفاده و پشتیبانی (ماهانه یا سالانه)، و
38
+ گزارش ماهانه و سفارشی‌سازی (در صورت نیاز).»
39
+ ۳. «هر بهبودی که من می‌دهم، بدون هزینهٔ اضافه به نسخهٔ شما هم می‌آید؛ چون نسخهٔ شما همان نسخهٔ
40
+ من است، فقط به نام شما.»
41
+ ۴. «داده‌های معاملاتی شما از رایانهٔ خودتان بیرون نمی‌رود. هیچ سفارشی هم از این برنامه ارسال
42
+ نمی‌شود؛ اجرا در سامانهٔ کارگزاری با آدم‌های خودتان است.»
43
+
44
+ نکتهٔ مهم: پلهٔ اول را **کوچک** ببندید. «یک هفته راه‌اندازی و آموزش» بفروشید، نه «قرارداد سالانه».
45
+ اعتماد از پلهٔ اول سبز ساخته می‌شود.
46
+
47
+ ---
48
+
49
+ ## ۳. «من سواد پشتیبانی ندارم» — چهار کار که این بار را برمی‌دارد
50
+
51
+ ۱. **خودِ برنامه عیب‌یاب است:** گام ۱ دکمهٔ «بررسی سلامت» دارد (هشت جزء)، گام ۹ آزمون دو روشه، و
52
+ در کارنامه «شکست دادهٔ زنده» و «ذخیرهٔ کهنه» صریح گزارش می‌شود. یعنی خودش می‌گوید کجا مشکل است.
53
+ ۲. **گزارش عیب‌یابی یک‌کلیکی:** دکمهٔ تازه در گام ۱ (`python diagnose.py`) یک پروندهٔ خوانا
54
+ می‌سا��د: نسخهٔ پایتون، سلامت اجزا، وضعیت مجوز و اتصال، اثر انگشت موتور، وضعیت دفتر، و پرونده‌های
55
+ مهم. همان یک فایل را برای پشتیبانی بفرستید؛ لازم نیست اصطلاح فنی بدانید.
56
+ ۳. **پشتیبانی شما، من هستم:** هر تغییری لازم شد، همین‌جا در گفتگو بگویید؛ من نسخهٔ به‌روز را
57
+ می‌سازم و شما فقط فایل را جای‌گزین می‌کنید. قرارداد هم ببندید که «رفع اشکال و به‌روزرسانی
58
+ عددها» داخل پشتیبانی ماهانه است؛ پس وقتی کاری نمی‌کنید، درآمد قطع نمی‌شود.
59
+ ۴. **دور نگه‌داشتن پشتیبانی سنگین در قرارداد:** سه بند ساده بنویسید: (الف) پشتیبانی برای «خرابی
60
+ نرم‌افزار» و «تغییر قواعد بازار»، (ب) آموزش کاربران جدید فقط با هزینهٔ افزوده، (ج) درخواست
61
+ خارج از فهرست، پروژهٔ جدا حساب می‌شود. همین سه بند، ۸۰ درصد دردسرها را حذف می‌کند.
62
+
63
+ ---
64
+
65
+ ## ۴. عمر طولانی و «لحظهٔ Jev [dʒɛv]»: چرا این برنامه سال‌ها بدون به‌روزرسانی کار می‌کند
66
+
67
+ این سؤال بسیار درست است. پاسخی که می‌دهم، ویژگی طراحی این برنامه است، نه آرزو:
68
+
69
+ - **هیچ وابستگی جانبی ندارد.** فقط کتابخانهٔ استاندارد پایتون و `tkinter`؛ نه سرور، نه پایگاه‌دادهٔ
70
+ ابری، نه اشتراک. چیزی که وابستگی نداشته باشد، «از مُد افتادن» ندارد.
71
+ - **در مسیر تصمیم، هیچ مدل زبانی نیست.** همهٔ عددهای تصمیم از ریاضی درمی‌آید. اگر فردا یک فناوری
72
+ تازه ترند شد (مثل Jev [dʒɛv])، برنامه بدون آن هم همان جواب را می‌دهد. مدل زبانی برای این برنامه
73
+ «تزیین» است، نه «ستون».
74
+ - **عددهای بازار در پروندهٔ تنظیمات است، نه در کد.** کارمزدها، نرخ سد، حد نگهداری وجه تضمین و کف
75
+ نقدشوندگی همه در `config` و در گام ۳ قابل تغییرند. وقتی سازمان بورس عددی را عوض کرد، شما در
76
+ سی ثانیه عدد را عوض می‌کنید؛ نه کد.
77
+ - **خودش تغییر را لو می‌دهد.** «اتصال خودکار» و «کاوش پاسخ سرویس» وقتی نشانی سرویس‌ها عوض شود،
78
+ خودشان مسیر تازه را پیدا می‌کنند؛ و اگر ساختار پاسخ عوض شود، آزمون‌ها سرخ می‌شوند و می‌گویند
79
+ کجا. یعنی عیب پیدا می‌شود، پنهان نمی‌شود.
80
+ - **شاهدهای قدیمی ارزششان را از دست نمی‌دهند.** اثر انگشت هر پرونده و زنجیرهٔ هش، سال‌ها بعد هم
81
+ قابل بازبینی است. این چیزی است که یک شرکت برای حسابرسی می‌خواهد.
82
+
83
+ **اگر واقعاً فناوری تازه‌ای لازم شد**، قاعده یکی است: به شکل **افزودنی** وصل می‌شود، نه در قلب
84
+ تصمیم. نمونه‌اش همین حالا در برنامه هست: «دفتر اتصال» اجازه می‌دهد هر منبع دادهٔ تازه‌ای را
85
+ بدون تغییر در موتور وصل کنید. برای لایهٔ زبانی هم سر جای خودش نشسته است؛ نه گلوگاه تصمیم است،
86
+ نه اگر فردا عوض شود چیزی می‌شکند.
87
+
88
+ ---
89
+
90
+ ## ۵. پول و واقعیت: چه چیزی در انتظار شماست، و چه چیزی نیست
91
+
92
+ باید صریح باشم، چون به شما احترام می‌گذارم: **هیچ‌کس از یک قرارداد با یک شرکت، پولدار نمی‌شود.**
93
+ پول درست‌وحساب، از **تکرار** می‌آید: چند مشتری، چند سال، درآمد کم اما ماهانه. این مسیر واقعی است،
94
+ ولی زمان می‌برد و به سه چیز بستگی دارد: (۱) یک مشتری اول که نتیجه بگیرد، (۲) همان نتیجه به شکل
95
+ عدد و شاهد، (۳) صبر برای آمدن مشتری دوم.
96
+
97
+ سه کار که امروز **از شما** لازم است و هیچ‌کدام پول نمی‌خواهد:
98
+
99
+ ۱. **مراسم روزانهٔ ده‌روزه** را روی لپ‌تاپ خودتان اجرا کنید (شصت ثانیه در روز) تا کارنامه از
100
+ «ناتمام» به «آماده» برسد. این تنها چیزی است که مشتری به آن نگاه می‌کند.
101
+ ۲. **یک اجازه‌نامهٔ دو هفته‌ا�� آزمون** برای همان شرکتی که در ذهن دارید صادر کنید
102
+ (`python license.py --trial --grant "نام شرکت" --save`) و در جلسه نشان بدهید؛ این «تعهد صفر،
103
+ اعتماد کامل» است.
104
+ ۳. **قرارداد ساده** را با من بنویسید (سه پله و سه بند پشتیبانی در بند ۱ و ۳ همین سند آماده است).
105
+
106
+ و آن بخش انسانی: سرکوفت و فشار خانه، معیار خوبی برای تصمیم‌گیری نیست. تصمیم درست، قراردادی است
107
+ که شما را از پشتیبانی سنگین و از دست دادن مالکیت حفظ کند؛ نه قراردادی که امروز پول بیشتری بدهد و
108
+ شش ماه بعد شما را بیکار کند.
109
+
110
+ ---
111
+
112
+ ## ۶. آنچه ادعا نمی‌کنم
113
+
114
+ - تضمین درآمد ندارم؛ هیچ عددی در این سند وعدهٔ سود نیست.
115
+ - مدل «اجازه‌نامهٔ دسترسی» بدون قرارداد و بدون مشتری مشخص، هیچ درآمدی نمی‌سازد.
116
+ - اگر شرکتی بخواهد کد را در اختیار بگیرد، تنها راه مقاومت شما **توافق روشن** است، نه پنهان‌کاری؛
117
+ و ارزش واقعی شما در ادامهٔ بهبود و آموزش است، نه در یک فایل.
118
+ - پشتیبانی ماهانه، تعهد ماهانه هم دارد؛ قرارداد را به‌اندازهٔ توان خودتان ببندید.
119
+
120
+ ✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · 📱 [989126630554](tel:+989126630554) · ✈️ [Telegram: Mojarabian](https://t.me/Mojarabian) · 📸 [Instagram: Mojarabian.Art](https://instagram.com/Mojarabian.Art)
station/docs/10-daily-inputs-fa.md ADDED
@@ -0,0 +1,94 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # هر روز چه چیزی وارد کنم؟ از کجا بگیرم؟ مجانی است؟ (۲۲ سپتامبر ۲۰۲۶)
2
+
3
+ پاسخ کوتاه: **روزی یک بار، حدود شصت ثانیه، ده عدد در هر ردیف؛ همه‌شان مجانی.** هیچ اشتراکی
4
+ لازم نیست. همهٔ این عددها روی تابلوی کارگزاری خودتان یا در سایت‌های عمومی بورس هست و برای دیدنشان
5
+ هیچ پولی نمی‌دهید.
6
+
7
+ > **قانون طلایی:** عددها را **از سامانهٔ کارگزاری خودتان** بردارید و در گام ۲ برنامه در جدول
8
+ > «وارد کردن اعداد کارگزاری» بنویسید، بعد «ذخیرهٔ اسنپ‌شات امروز» را بزنید. همین کار، روز شما را
9
+ > در کارنامه یک **روز واقعی** حساب می‌کند (نه روز ساختگی). در پایان همان کادر یک تیک هست:
10
+ > «این اعداد را خودم از سامانهٔ کارگزاری برداشتم».
11
+
12
+ ---
13
+
14
+ ## ۱. ده عددی که هر روز لازم است (و محل مجانی هرکدام)
15
+
16
+ | عدد | در برنامه با این نام | از کجا (مجانی) |
17
+ | --- | --- | --- |
18
+ | نماد و راهبرد | `symbol` · `kind` | از خودتان؛ نماد را از تابلوی کارگزاری و راهبرد را از نوع معامله‌تان بردارید |
19
+ | قیمت پایه (نقدی سهم یا دارایی) | `spot` یا `stock_price` | تابلوی کارگزاری، یا سایت `tsetmc.com`، تب «مشاهدهٔ زنده» همان نماد |
20
+ | قیمت آتی | `future` | تب «آتی» همان نماد در سایت بورس کالا و سامانهٔ کارگزاری |
21
+ | قیمت اعمال | `strike` یا `strike_low` و `strike_high` | تب «اختیار معامله» نماد؛ ستون قیمت اعمال قرارداد |
22
+ | پرمیوم اختیار خرید | `premium` یا `call_low` و `call_high` | همان تابلوی اختیار معامله؛ ستون «آخرین قیمت» اختیار خرید |
23
+ | پرمیوم اختیار فروش | `put_price` یا `put` | ستون «آخرین قیمت» اختیار فروش همان سررسید |
24
+ | روزهای مانده تا سررسید | `days` | تاریخ سررسید در تابلوی همان قرارداد منهای امروز (سایت خودش می‌نویسد) |
25
+ | وجه تضمین هر قرارداد | `margin_per_contract` | **فقط از کارگزاری** (اطلاعیهٔ وجه تضمین). هیچ سایت عمومی این عدد را دقیق نمی‌دهد |
26
+ | نقدشوندگی روز | `liquidity_contracts_per_day` | ستون «حجم» همان قرارداد در تابلوی امروز |
27
+ | اسپرد | `spread_pct` | اختلاف قیمت خرید و فروش تقسیم بر میانگین‌شان؛ تقریبی هم کافی است |
28
+
29
+ نکتهٔ واحدها: `hurdle` و `spread_pct` **کسری**اند (۰٫۳۹ یعنی ۳۹٪ و ۰٫۰۰۵ یعنی نیم درصد)،
30
+ `capital` به ریال است، و بقیهٔ قیمت‌ها به ریال.
31
+
32
+ ---
33
+
34
+ ## ۲. هر نوع معامله چه عددی می‌خواهد (فقط همان‌ها را پر کنید)
35
+
36
+ | نوع معامله | چه عددهایی لازم است |
37
+ | --- | --- |
38
+ | خرید نقدی و فروش آتی (کری) | `spot` · `future` · `days` |
39
+ | پوشش‌داده‌شده (فروش اختیار خرید روی سهم) | `spot` · `strike` · `premium` · `days` |
40
+ | تبعی (تضمین فروش) | `stock_price` · `put_price` · `strike` · `days` |
41
+ | باکس اسپرد | `call_low` · `put_low` · `call_high` · `put_high` · `strike_low` · `strike_high` · `days` |
42
+ | تساوی پوت‌کال | `call` · `put` · `spot` · `strike` · `days` |
43
+
44
+ برای هر ردیف، این سه همیشه لازم است: `margin_per_contract` · `liquidity_contracts_per_day` ·
45
+ `spread_pct`. اگر راهبرد شما در این پنج نوع نیست، همان نزدیک‌ترین را بگذارید و در یادداشت بنویسید؛
46
+ برنامه خودش می‌گوید عدد قابل محاسبه است یا نه.
47
+
48
+ ---
49
+
50
+ ## ۳. چهار راه دادن داده، با هزینهٔ صادقانه
51
+
52
+ | راه | هزینه | چه وقت مناسب است |
53
+ | --- | --- | --- |
54
+ | **۱. جدول داخل برنامه (پیشنهاد امروز)** | صفر | هر روز، همان شصت ثانیه. مطمئن، آفلاین، و روز واقعی حساب می‌شود |
55
+ | **۲. قالب پرونده (`data/snapshot-template.json`)** | صفر | اگر ترجیح می‌دهید عددها را در فایل بنویسید؛ قالب را با نام خودتان ذخیره کنید (`daily-input.json`) و عددهای واقعی بگذارید |
56
+ | **۳. سرویس عمومی وب (رایگان)** | صفر | اگر می‌خواهید برنامه خودش قیمت بخواند؛ گام ۲ «دفتر ا��صال» و «بگرد و گزارش بده». رایگان است ولی «با شانس»: ممکن است کند یا قطع باشد |
57
+ | **۴. وب‌سرویس رسمی/خصوصی** | پول لازم دارد | **الان لازم نیست**؛ تا وقتی کارنامه «آماده» شده و خریدار مشخص نشده، هیچ پولی خرج نمی‌کنید (سند ۰۵ و ۰۶) |
58
+
59
+ راه چهارم یعنی پایان کار با دست: در سایت `tsetmc.com` و در اطلاعیه‌های کدال (`codal.ir`) همهٔ
60
+ عددها هست؛ فقط باید خودتان بردارید. اگر روزی مشتری جدی آمد، همان زمان تصمیم می‌گیرید.
61
+
62
+ ---
63
+
64
+ ## ۴. شصت ثانیهٔ روزانه، گام‌به‌گام (با نام دکمه‌های واقعی برنامه)
65
+
66
+ ۱. **گام ۲** → جدول «وارد کردن اعداد کارگزاری»: عددهای امروز را بنویسید (یا «خواندن اعداد فعلی»
67
+ را بزنید و ویرایش کنید) → تیک تأیید → **«ذخیرهٔ اسنپ‌شات امروز»**.
68
+ ۲. **گام ۵** → **«اجرا و محاسبه»** روی همین منبع.
69
+ ۳. **گام ۶** → هر سیگنال را ببینید و تأیید یا رد کنید (اجرا با خودِ شماست؛ برنامه سفارش نمی‌فرستد).
70
+ ۴. **گام ۹** → **«۰. مراسم امروز»** (یا جداگانه «ثبت سیگنال‌های امروز» و «بازسنجی با قیمت‌های تازه»).
71
+ ۵. **گام ۹** → **«کارنامهٔ آزمون»**: ببینید چند روز ثبت شده و آیا به «آماده» رسیده است.
72
+
73
+ یا اگر عجله دارید: **گام ۹ → «۰. مراسم امروز»** خودش همهٔ این پنج کار را با یک دکمه انجام می‌دهد.
74
+
75
+ ---
76
+
77
+ ## ۵. چه چیزی را هرگز وارد نکنید
78
+
79
+ - **رمز و کد ورود سامانهٔ کارگزاری**: هیچ‌وقت. برنامه به سامانهٔ شما وارد نمی‌شود و لازم هم ندارد.
80
+ - **شمارهٔ حساب، کد بورسی، و اطلاعات هویتی**: لازم نیست.
81
+ - **سفارش و شمارهٔ سفارش**: برنامه سفارش نمی‌دهد و نمی‌گیرد؛ اجرا در سامانهٔ کارگزاری با خود شماست.
82
+ - **عدد حدسی**: عدد ساختگی هم صادقانه برچسب می‌خورد و آن روز «روز ساختگی» شمرده می‌شود، نه روز
83
+ واقعی. برای کارنامه و جلسهٔ شرکت فقط روزهای واقعی ارزش دارند (هدف: ۱۰ روز ثبت، دست‌کم ۵ روز با
84
+ دادهٔ واقعی).
85
+
86
+ ---
87
+
88
+ ## ۶. اگر یک روز نتوانستم؟
89
+
90
+ هیچ چیزی خراب نمی‌شود. آن روز را ثبت نکنید و روز بعد ادامه بدهید؛ کارنامه روزها را می‌شمارد و
91
+ چیزی از شما کم نمی‌شود. سخت‌ترین بخش این کار، همین برداشتن ده عدد در روز اول است؛ از روز دوم
92
+ فقط جای اعداد در جدول عوض می‌شود.
93
+
94
+ ✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · 📱 [989126630554](tel:+989126630554) · ✈️ [Telegram: Mojarabian](https://t.me/Mojarabian) · 📸 [Instagram: Mojarabian.Art](https://instagram.com/Mojarabian.Art)
station/docs/11-usage-and-percent-fa.md ADDED
@@ -0,0 +1,157 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # ایدهٔ «شمارش استفادهٔ موفق» و درصدگرفتن — بررسی صادقانه (نسخهٔ ۰٫۱٫۱ · ۲۲ سپتامبر ۲۰۲۶)
2
+
3
+ ایدهٔ شما: «هر کار موفقی که برنامه می‌کند جایی نگه دارد تا مطمئن شوم کارفرما چقدر از آن استفادهٔ
4
+ موفق داشته و بر همان پایه درصد بگیرم.» این ایده **نیمه‌اش درست و نیمه‌اش خطرناک** است. این سند
5
+ همان دو نیمه را جدا می‌کند، و همه‌جا می‌گوید کدام مدل **ساخته شده** و کدام فقط روی کاغذ است.
6
+
7
+ > **داوری یک‌خطی:** «چقدر از برنامه استفاده شده» شمردنی است و همین حالا ساخته شده
8
+ > (`gui/usage_meter.py` + کارت «گواهی استفادهٔ موفق» در پنل مدیریت). «درصد از سود معاملات» را
9
+ > نمی‌شود بی‌دادهٔ کارگزاری اثبات کرد و توصیه نمی‌کنم؛ ولی «درصدِ کوچک بر پایهٔ شاهدِ امضاشدهٔ
10
+ > همان ماه» قابل دفاع و قابل امضا است.
11
+
12
+ ---
13
+
14
+ ## ۱. نیمهٔ درست ایده: کارهای موفق **قابل شمردن**اند
15
+
16
+ دفتر استفادهٔ موفق، شانزده نوع کار را می‌شناسد. این فهرست از خودِ برنامه می‌آید
17
+ (`KIND_LABELS` در `usage_meter.py`)، نه از تخیل من:
18
+
19
+ | نوع کار | کلید انگلیسی | چرا «موفق» حساب می‌شود |
20
+ | --- | --- | --- |
21
+ | اجرای موتور روی دادهٔ روز | `run` | موتور روی اسنپ‌شات امروز اجرا شد و سیگنال‌ها بازتولیدشدنی‌اند |
22
+ | داوری سیگنال (می‌ماند یا می‌افتد) | `judge` | سیگنال ابزار دیگران با کارمزد، اسپرد، نقدشوندگی و نرخ سد سنجیده شد |
23
+ | تصمیم ثبت‌شده (خرید/فروش/رد) | `decision` | تأیید یا ردِ سیگنال با دلیل در دفتر تاریخ‌دار نشست |
24
+ | مراسم روزانهٔ شصت‌ثانیه‌ای | `ritual` | آن روز، آزمون دو هفته‌ای یک گام جلو رفت |
25
+ | آزمون ۱۰ دقیقه‌ای ایستگاه | `exam` | ۱۵ سنجه، هر کدام دو بار (موتور و حساب دستی) اجرا شد |
26
+ | بستهٔ شاهد شرکت | `bundle` | پوشهٔ تحویل به مدیر ریسک ساخته شد و اثر انگشت پرونده‌ها ثبت شد |
27
+ | آزمون کور سرمایه‌گذار | `blind` | خودِ سرمایه‌گذار حدس زد؛ شاهد بی‌طرف از بیرون آمد |
28
+ | برگهٔ شاهد زندهٔ داده | `witness` | قیمت از منبع واقعی خوانده شد و هش پاسخ خام ثبت شد |
29
+ | پلهٔ تصمیم (چه بخرم/کِی بفروشم) | `ladder` | جدول آستانهٔ خرید و فروش و افتادن ساخته شد |
30
+ | پیمان‌نامهٔ نمایش | `pledge` | سند دواِمضای جلسه آماده شد |
31
+ | مجوز دسترسی و پشتیبانی | `license` | اجازه‌نامهٔ نام‌دار و سند چاپی‌اش صادر شد |
32
+ | پروندهٔ سرمایه‌گذار | `dossier` | پروندهٔ نه‌بخشی با اثر انگشت هر پرونده ساخته شد |
33
+ | ثبت اعداد روز | `snapshot` | اعداد کارگزاری امروز، تاریخ‌دار، ذخیره شد |
34
+ | ورود اعداد از متن کارگزاری | `import` | جدول چسبانده‌شده خوانده و به اعداد پاکیزه تبدیل شد |
35
+ | برگهٔ راهبردها و شوک‌آزمون | `strategy` | جزوهٔ راهبردها و جدول «اگر این‌طور شد چه می‌شود» ساخته شد |
36
+ | ریاضیِ بقا و مسیر رشد | `math` | کِلی، احتمال نیم‌شدن حساب و مسیر تا هدف حساب شد |
37
+
38
+ چهار ویژگی دفتر، همان چیزی است که آن را به «شاهد» تبدیل می‌کند:
39
+
40
+ **محلی است.** فایل دفتر `gui/data/usage-ledger.json` روی رایانهٔ خودِ شرکت می‌ماند و هیچ رشتهٔ
41
+ شبکه‌ای در آن نیست. برای بازبینی هم فقط همان فایل لازم است.
42
+
43
+ **زنجیره‌هش‌دار است.** هر ردیف، اثر انگشت `sha256` ردیف پیشین را در خود دارد. اگر کسی ردیفی را
44
+ کم یا عوض کند، زنجیره می‌شکند و همان‌جا نوشته می‌شود «شکسته ⚠️ (ردیف N)»؛ نه اینکه به‌جای عدد،
45
+ سکوت بگذارد.
46
+
47
+ **بی‌دادهٔ مالی است.** دفتر فقط «نوع کار» و «توضیح کوتاه» و ساعت را نگه می‌دارد. عددهای یادداشت
48
+ هم قبل از ثبت پاک‌سازی می‌شوند: هر عدد بلند یا جداک��نده‌دار به «‹عدد›» تبدیل می‌شود و تلفن و
49
+ ایمیل هم ماسک می‌شوند، تا اشتباهی چیزی وارد دفتر نشود که نباید.
50
+
51
+ **دو امضا دارد.** گواهی، جای امضای ارائه‌دهنده و امضای شرکت را دارد و در پایان می‌نویسد با
52
+ یک فرمان می‌شود همه‌اش را بازتولید کرد:
53
+
54
+ ```bash
55
+ cd /home/user/MATERIALS/money/gui
56
+ python3 usage_meter.py --summary --verify # عددها + سالم‌بودن زنجیره
57
+ python3 usage_meter.py --statement --client "نام شرکت" # گواهی دواِمضا (HTML و متن)
58
+ ```
59
+
60
+ ## ۲. نیمهٔ خطرناک: «درصد از سود» را نمی‌شود اثبات کرد
61
+
62
+ ۱. **بدون دادهٔ کارگزاری، سود را نمی‌شود سنجید.** برنامه سفارش نمی‌فرستد، پس نمی‌داند کدام پیشنهاد
63
+ اجرا شد و به چه قیمتی. هر عدد سودی که برنامه «حساب» کند، قابل اعتراض است.
64
+ ۲. **تعارض منافع و ریسک حقوقی.** اگر درآمد شما به سود گره بخورد، انگیزه‌تان به «معاملهٔ بیشتر»
65
+ می‌رود؛ همان چیزی که در این بازار بیشتر آدم‌ها را می‌بازد. شرکت هم می‌تواند هر زیان را به گردن
66
+ شما بیندازد.
67
+ ۳. **تناقض با موضع خودمان.** شما همه‌جا نوشته‌اید «سود تضمین نمی‌شود». مدل درصد از سود، خلاف این
68
+ جمله است و اعتماد را خراب می‌کند.
69
+
70
+ خودِ برنامه هم همین را به زبان ماشین می‌گوید. `percent_model()` در `usage_meter.py` برای
71
+ «درصد از سود» حکم **«رد می‌کنم»** دارد، با سه دلیل: سود تضمینی نیست · اندازه‌گیری سود به دفتر
72
+ سرمایهٔ مشتری گره می‌خورد · ریسک را به طرف ضعیف‌تر قرارداد منتقل می‌کند. برای دیدنش:
73
+
74
+ ```bash
75
+ python3 usage_meter.py --percent-model
76
+ ```
77
+
78
+ ## ۳. مدل قابل دفاع: درصدِ کوچک بر پایهٔ **شاهدِ امضاشده**
79
+
80
+ سه جایگزینِ ساخته‌شده و راستی‌آزمایی‌پذیر (همان خروجی `--percent-model`):
81
+
82
+ | مدل | چه چیزی سندِ آن است | برای چه کسی |
83
+ | --- | --- | --- |
84
+ | **اشتراک ماهانه** | تاریخ پرداخت و شمارش کارهای همان ماه | شرکت یا کارگزاری که برنامه را روزانه به کار می‌برد |
85
+ | **اشتراک به‌ازای روز فعال** | «روزهای فعال» همین دفتر؛ عددی که هر دو طرف می‌توانند بازتولید کنند | کسی که بعضی روزها کار می‌کند؛ از ماهانهٔ ثابت منصفانه‌تر است |
86
+ | **پاداش به‌ازای شاهد** | برگهٔ شاهد زنده یا آزمون کور که اثر انگشت دارد | هر تحویل قابل‌سنجش، بدون وعدهٔ سود |
87
+
88
+ قاعدهٔ ساده، اگر خواستید پاداش را به «کارِ انجام‌شده» گره بزنید: **نرخ توافقی × شمارشِ همان ماه**
89
+ با سه قید: سقف ماهانه داشته باشد، فقط روی شاهدهای امضاشدهٔ همان ماه حساب شود، و پایهٔ محاسبه
90
+ (کارمزد خرید ۰٫۴۶٪ و فروش ۰٫۹۶٪ سهام؛ مشتقه ارزان‌تر) در قرارداد نوشته شود. عدد «ارزش کار» را هم
91
+ برنامه فقط با **فرض صریح** می‌سازد: ۱٫۵۰۰٫۰۰۰ ریال برای هر دقیقه کار انسانی و پنج دقیقه برای هر
92
+ کار. اگر این فرض را قبول نکنید، همان ستون شمارش و اثر انگشت زنجیره می‌ماند؛ گواهی با فرض قبول
93
+ نشده هم کار می‌کند.
94
+
95
+ ## ۴. چهار مدل، با سود و زیان
96
+
97
+ | مدل | برای شما | برای شرکت | داوری |
98
+ | --- | --- | --- | --- |
99
+ | **الف) اشتراک ثابت** (راه‌اندازی + ماهانه) | درآمد پایدار و ساده | هزینهٔ قابل پیش‌بینی | **پیشنهاد اصلی** |
100
+ | **ب) اشتراک به‌ازای روز فعال** | منصفانه‌تر، درآمد کمی پرنوسان‌تر | پول در برابر روزهایی که واقعاً کار شده | **خوب؛ عددِ سندش داخل خود دفتر است** |
101
+ | **ج) پاداش به‌ازای شاهد** (با شاهد امضاشده) | سقف درآمد بالاتر | پول فقط وقتی کارِ قابل‌نشان تحویل شده | **خوب، اگر قاعده نوشته شود** |
102
+ | **د) درصد از سود معاملات** | پرنوسان، پرتنش | انگیزهٔ معاملهٔ بیشتر | **توصیه نم��‌کنم** |
103
+
104
+ ## ۵. جملهٔ آماده برای جلسه
105
+
106
+ «من نمی‌خواهم از سود معاملات شما سهم بگیرم؛ نمی‌توانم و نمی‌خواهم آن را اثبات کنم. پیشنهاد من
107
+ این است: یک اجازه‌نامهٔ دسترسی با حق ثابت، و اگر خواستید، پاداش کوچکی بر پایهٔ گزارش ماهانه‌ای
108
+ که هر ردیفش سند دارد؛ یا روزهای فعالی که خودتان هم می‌توانید بشمارید، یا برگه‌های شاهد
109
+ اثرانگشت‌دار. هر ماه همین گواهی را امضا می‌کنیم و اگر سندش نبود، پولی بابت آن گرفته نمی‌شود.»
110
+
111
+ ## ۶. حریم خصوصی: این را در جلسه بگویید، فروش را آسان می‌کند
112
+
113
+ دفتر استفاده **روی رایانهٔ خودشان** است، به اینترنت وصل نمی‌شود، و هیچ دادهٔ مالی یا اسمی در آن
114
+ نیست. بازبینی‌اش هم یک فرمان است:
115
+
116
+ ```bash
117
+ python3 usage_meter.py --summary | grep حریم
118
+ # دفتر پاکیزه است: هیچ کلید مالی (قیمت/سود/موجودی/حساب) در آن نیست.
119
+ ```
120
+
121
+ برنامه ۲۱ کلید ممنوع را می‌شناسد (قیمت، سود، موجودی، حساب، مبلغ، سپرده و مانند آن) و اگر روزی
122
+ یکی از آن‌ها به دفتر برسد، در همان گزارش نامش را می‌گوید. همین را در قرارداد به‌شکل یک بند
123
+ بنویسید: «ابزار هیچ داده‌ای را به بیرون منتقل نمی‌کند.» شرکتی که این را بداند، خیلی راحت‌تر
124
+ امضا می‌کند.
125
+
126
+ ## ۷. گواهی، داخل بستهٔ شاهد هم می‌رود
127
+
128
+ وقتی گام ۸ بستهٔ تحویل شرکت را می‌سازد، برنامه خودش گواهی استفاده را از دفتر همان رایانه تازه
129
+ می‌کند و کنار بقیهٔ شاهدها می‌گذارد (`17-usage-statement.html` و `18-usage-statement.md`)، همراه
130
+ با اثر انگشت `sha256` و ساعت ساخت. پس مدیر ریسک لازم نیست چیزی از شما بخواهد؛ سند داخل پوشه است.
131
+
132
+ ## ۸. قرارداد فنی این دفتر (برای بازبینی شرکت یا برنامه‌نویس خودشان)
133
+
134
+ | کار | فرمان یا تابع |
135
+ | --- | --- |
136
+ | ثبت یک کار | `python3 usage_meter.py --record judge --label "داوری سیگنال فولاد"` |
137
+ | خلاصهٔ عددها | `python3 usage_meter.py --summary` یا `--json` برای ماشین‌خوان |
138
+ | سالم‌بودن زنجیره | `python3 usage_meter.py --verify` → `chain_ok` و `broken_at` و اثر انگشت `last_chain` |
139
+ | گواهی دواِمضا | `--statement --client "نام شرکت" --period "مهر ۱۴۰۵"` |
140
+ | مدل درصد | `--percent-model` |
141
+ | ارزش فرضی کار | `avoided_cost(summary)` با فرض صریح؛ ادعا نیست |
142
+ | در کد | `record` · `record_event(kind, label, note, path=…)` · `verify_chain(path)` · `privacy_check(path)` · `summary(path)` · `build_statement(summary, client=…)` |
143
+
144
+ خلاصهٔ ماشین‌خوان این کلیدها را می‌دهد: `success_total` · `today` · `last_7_days` ·
145
+ `active_days` · `by_kind` (انگلیسی) و `by_kind_label` (فارسی) · `chain_ok` · `broken_at` ·
146
+ `kept_local` · `privacy` · `trial_days` و `real_days` (روزهای تمرینی و واقعی، جدا).
147
+
148
+ ## ۹. آنچه ادعا نمی‌کنم
149
+
150
+ - گواهی استفاده، **سود** یا **درصد موفقیت در بازار** را اثبات نمی‌کند؛ فقط شمارش کارها و تمامیت
151
+ دفتر را نشان می‌دهد.
152
+ - شمارش، «کارِ انجام‌شده» را می‌شمارد نه «کیفیت کار». کیفیت را پروندهٔ سرمایه‌گذار، آزمون کور و
153
+ پس‌آزمایی نشان می‌دهند؛ سه سند دیگر.
154
+ - مدل پاداش، بدون شاهدِ امضاشدهٔ همان ماه، قابل مطالبه نیست؛ و همین است که آن را قابل دفاع می‌کند.
155
+ - هیچ‌کدام از این مدل‌ها، مشتری تضمین‌شده نمی‌سازد؛ مشتری اول، کارِ بیرون از این پرونده است.
156
+
157
+ ✍️ تهیه‌کنندهٔ جزوات: Masoud Mojarabian · 📱 [989126630554](tel:+989126630554) · ✈️ [Telegram: Mojarabian](https://t.me/Mojarabian) · 📸 [Instagram: Mojarabian.Art](https://instagram.com/Mojarabian.Art)
station/docs/12-wealth-math-and-no-purchase-fa.md ADDED
@@ -0,0 +1,154 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # با ریاضی می‌شود ثروتمند شد؟ — جواب صادقانه، با عدد و با مرزها
2
+
3
+ **نسخهٔ ۰٫۱٫۰ · شهریور ۱۴۰۵**
4
+
5
+ این سند جواب همان چیزی است که پرسیدید: «امکانش نیست برنامه را تقویت کنی که واقعاً ازش بشه
6
+ پول‌های خوبی درآورد؟ ایده‌های جدید بده و مطمئن شو ایده‌های قبلی واقعاً جواب می‌دهند؟»
7
+
8
+ جواب کوتاه: **بله، با ریاضی می‌شود، ولی نه با پیش‌بینی. با سه چیز:** هر سه هم ریاضی است و هم
9
+ در همین ایستگاه سنجیده شده:
10
+
11
+ ۱. **مزیت عددی**: در هر معامله باید عددی قفل‌شده از نرخ سد بگذرد. این عدد امروز هست یا نیست؛
12
+ حدس نیست.
13
+ ۲. **بقا**: اندازهٔ هر موقعیت باید کوچک باشد تا نیم‌شدن حساب احتمالش کم شود. با سرمایهٔ کم،
14
+ بقا مهم‌تر از سرعت است.
15
+ ۳. **زمان**: رشد مرکب کند است. عددش را می‌شود حساب کرد؛ وعده‌اش را نمی‌شود داد.
16
+
17
+ سه سند تازهٔ همین هفته دقیقاً همین سه را می‌سازد: **جزوهٔ راهبردها** (مزیت)، **شوک‌آزمون**
18
+ (آیا ایده‌های قبلی زیر شرایط بد هم می‌مانند؟)، و **ریاضیِ پول** (بقا و زمان). هیچ‌کدام وعدهٔ
19
+ درصد سود نمی‌دهد و هیچ‌جا عددی بدون برچسب روش منتشر نشده است.
20
+
21
+ ---
22
+
23
+ ## ۱. ایده‌های جدید (و ایده‌های قبلی) با درصد امروزشان
24
+
25
+ هر عدد دو روش دارد: **موتور ایستگاه** و **محاسبهٔ دستی دوم**. اگر این دو نخوانند، در جدول
26
+ علامت «مخالف» می‌خورد و عدد دور انداخته می‌شود. برچسب روش هم سه حالت دارد:
27
+
28
+ - **قطعی**: در لحظهٔ وارد‌شدن قفل می‌شود (تبعی، باکس، مبنا).
29
+ - **مدل‌محور**: با نوسانِ ضمنیِ خودِ بازار و فرض بلک-شولز حساب می‌شود. تخمین است، نه پیش‌بینی.
30
+ - **نقل‌شده**: از منبع بیرونی، با نام منبع.
31
+
32
+ | راهبرد | دسته عدد | عدد امروز (اسنپ‌شات خود شما) | بعد از شوک‌ها |
33
+ | --- | --- | --- | --- |
34
+ | مبنا (خرید نقدی + فروش آتی) | قطعی | **۶۸٫۴۸۲٪ سالانه** (نماد اهرم) | سخت‌جان: هر پنج شوک را رد کرد |
35
+ | پوشش‌داده‌شده (فروش اختیار خرید) | قطعی + مدل | **۵۶٫۵۵۸٪ سالانه** (نماد فولاد) · احتمال مدل‌محور ماندن زیر اعمال ۶۱٫۹٪ | سخت‌جان |
36
+ | اوراق تبعی (کمینهٔ تضمینی) | قطعی | **۴۲٫۳۶۱٪ سالانه** (نماد کگل) | لبِ مرز: با نرخ سد ۴۵٪ می‌افتد |
37
+ | باکس اسپرد | قطعی | **۶۷٫۸۶۸٪ سالانه** (نماد شپنا) | لبِ مرز: لغزش ۰٫۵٪ حاشیه را تا ۳۵٫۸٪ می‌آورد |
38
+ | اوراق تبعی (ردیف دوم) | قطعی | **۲۴٫۶۹۲٪ سالانه** (نماد خساپا) | نمی‌ارزد: از قبل زیر نرخ سد است |
39
+ | مبنا (ردیف دوم) | قطعی | **۱۶٫۸۲۳٪ سالانه** (نماد طلا) | نمی‌ارزد: از قبل زیر نرخ سد است |
40
+ | تساوی پوت-کال | قطعی | **نه** (شکاف از کارمزد سه پایه بزرگ‌تر نیست) | نمی‌ارزد |
41
+ | صندوق درآمد ثابت (خط پایه) | نقل‌شده | ۳۹ تا ۴۰٪ مؤثر (شهریور ۱۴۰۵) | خط پایهٔ مقایسه، نه معامله |
42
+
43
+ **نکتهٔ مهم جدول:** عدد بزرگ دلیل خوبی نیست. «مبنا ۶۸٪» فقط به این معناست که اگر همان قرارداد
44
+ را تا سررسید نگه دارید و دو پا را هم‌زمان ببندید، عدد روی کاغذ همان است؛ ریسک واقعی‌اش
45
+ مارجین‌کال و نقدشوندگی است. برای همین سند دوم ساخته شد.
46
+
47
+ ## ۲. شوک‌آزمون: مطمئن شدن اینکه ایده‌های قبلی واقعاً جواب می‌دهند
48
+
49
+ هر راهبرد با پنج بدترشدن دوباره حساب می‌شود و جواب «می‌ماند / می‌افتد» می‌گیرد. سه دسته:
50
+
51
+ - **سخت‌جان** (همهٔ پنج شوک را رد کرد): مبنا (اهرم)، پوشش‌داده‌شده (فولاد).
52
+ - **لبِ مرز** (رد کرد، ولی حاشیهٔ پس از شوک کمتر از ۵ واحد درصد شد): باکس اسپرد (شپنا)،
53
+ اوراق تبعی (کگل). یعنی این دو با یک بدترشدن کوچک می‌افتند.
54
+ - **تلاش‌ه��ی بی‌نتیجه که در سند می‌مانند**: تساوی پوت-کال (وبملت)، تبعی خساپا، مبنای طلا.
55
+ این‌ها حذف نمی‌شوند، چون «چه چیزی نخر» هم بخشی از تصمیم است.
56
+
57
+ عددهای مرزی که برای شما از همه مهم‌ترند:
58
+
59
+ - **فاصله تا اخطاریهٔ مارجین‌کال: ۶٪ حرکت مخالف.** این از قاعدهٔ بورس می‌آید (حد نگهداری ۷۰٪
60
+ وجه تضمین اولیه؛ با نسبت اولیهٔ ۲۰٪، یعنی ۲۰٪ × ۳۰٪ = ۶٪). پس حد ضرر منطقی باید نزدیک‌تر
61
+ از ۶٪ باشد، نه دورتر.
62
+ - **تحمل کارمزد**: مبنا و پوشش‌داده‌شده تا ۱۲ برابر کارمزد امروز هم می‌مانند؛ بستهٔ اسپرد و تبعی
63
+ زودتر می‌افتند (تبعی کگل: با ۴٫۶۷ برابر).
64
+ - **باکس اسپرد با لغزش اجرای ۰٫۵٪** از ۶۷٫۸٪ به ۳۵٫۸٪ می‌افتد: یعنی این راهبرد عملاً به
65
+ نقدشوندگی و اسپرد واقعی زنده است.
66
+
67
+ ## ۳. ریاضیِ بقا و زمان (همان چیزی که «ثروتمند شدن» به آن بسته است)
68
+
69
+ سه عدد، سه درس:
70
+
71
+ ۱. **اندازهٔ درست هر معامله (کِلی، برگرفته از کار جان کِلی /ˈkɛli/)**: با نرخ برد ۵۵٪ و سود برد ۸٪ و زیان باخت ۵٪، مزیت هر
72
+ معامله ۲٫۱۵٪ و کسر کِلی ۰٫۲۷ و نسخهٔ محافظه‌کارانهٔ آن (نصف‌کِلی) ۰٫۱۳ است. یعنی حدود
73
+ ۱۳٪ سرمایه در هر معامله، نه ۱۰۰٪. عدد بزرگ‌تر، پول بیشتر نمی‌آورد؛ ورشکستگی می‌آورد.
74
+
75
+ ۲. **کم‌ترین نرخ برد لازم (سر‌به‌سر)**: با سود ۸٪ و زیان ۵٪ و کارمزد رفت‌وبرگشت سهم
76
+ (۱٫۴۲۸٪)، کم‌ترین نرخ برد **۴۹٫۴۵٪** است. زیر این عدد، هر راهبردی بازنده است: ریاضی،
77
+ نه نظر. نرخ برد خودتان را از دفتر حساب در بیاورید، نه از حافظه.
78
+
79
+ ۳. **مسیر رشد راهبرد**: عدد ۶۸٫۴۸٪ سالانه با یک بار چرخش در سال، خالص ۶۷٫۰۵٪ می‌شود و
80
+ ۴ برابر شدن سرمایه حدود **۳۲ ماه (۲٫۷ سال)** طول می‌کشد، به شرط اینکه رشد مثبت بماند و
81
+ هیچ ماه بحرانی حساب را نصف نکند. اگر ماهی چند بار بچرخانید، کارمزد همان مزیت را می‌خورد.
82
+
83
+ شبیه‌سازی ۲۰٬۰۰۰ مسیر فرضی هم این را نشان می‌دهد: با اندازهٔ کوچک، احتمال نیم‌شدن حساب کمتر
84
+ از یک درصد می‌شود؛ با اندازهٔ درشت، همان مزیت به ورشکستگی می‌رسد.
85
+
86
+ **پس «ثروتمند شدن با ریاضی» دقیقاً این است:** مزیت را قفل کن، اندازه را کوچک نگه دار، کارمزد
87
+ را کم کن، و زمان بده. هیچ‌کدام از این چهار تا «شانس» نیست، ولی هیچ‌کدام هم «تضمین» نیست.
88
+
89
+ ## ۴. آیا باید چیزی بخرید؟ نه.
90
+
91
+ | پرسش | جواب |
92
+ | --- | --- |
93
+ | آیا برای این برنامه باید **Jev** بخرم؟ | **نه.** Jev فقط لایهٔ خلاصه‌سازی خبر و متن است؛ کل ریاضی، داوری سیگنال، پلهٔ تصمیم و برگهٔ شاهد بدون آن کار می‌کند. |
94
+ | پس Jev به چه کار می‌آید؟ | برای خواندن انبوه خبر کدال و تلخیص فارسی. «خوبی» است، نه «لازم». |
95
+ | جایگزین رایگانش چیست؟ | ۱. همان قواعد کلیدواژه‌ای و امتیازدهی که در ایستگاه هست؛ ۲. اگر خواستید، یک مدل کوچک محلی (`Ollama`) روی همین رایانه، بدون کلید و بدون هزینه؛ ۳. حتی بدون هیچ‌کدام، تصمیم‌ها با عدد بازار گرفته می‌شود، نه با خبر. |
96
+ | آیا باید وب‌سرویس دادهٔ پولی بخرم؟ | **نه.** خوراک آزمایشی محلی (رایگان، ساختگی ولی کامل) برای نشان‌دادن کارکرد کافی است. برای دادهٔ **واقعی** هم یک مسیر رایگان و بدون کلید آزموده شد: tgju برای دلار، گرم طلای ۱۸، سکهٔ امامی، نیم و ربع (پاسخ ۲۰۰ در ۰٫۳ تا ۱٫۸ ثانیه؛ پنج عدد با یک نقطهٔ پایانی مستقل مقایسه و تأیید شد). شاهد با هش پاسخ خام: `gui/data/real-feed-proof.md`. سهام و آتی و اختیار از محیط من بسته بود (۰ از ۶ نشانی TSETMC)؛ همین آزمون را روی رایانهٔ خودتان بزنید: `python3 data_sources.py --all`. وجه تضمین را فقط کارگزاری می‌دهد. |
97
+ | پس پول به چه چیزی می‌رود؟ | به **جای دیگری نروید**: سرمایهٔ خودتان فقط وقتی سر کار می‌رود که عددها می‌گذرند. تا آن‌وقت، خروجی کار شما «شاهد» است، نه خرید سرویس. |
98
+
99
+ اگر روزی Jev یا ابزار مشابهی ترند شد و مشتری‌ها آن را خواستند، همان‌جا ارزش دارد: چون کار شما
100
+ «داوری سیگنال با ریاضی» است و آن‌ها «تولید متن». دو کار جدا هستند.
101
+
102
+ ## ۵. چطور ارزشش را به سرمایه‌گذار ثابت کنیم (آزمون عملیاتی بی‌پول)
103
+
104
+ پنج گام، همه روی همین رایانه، همه با هزینهٔ صفر:
105
+
106
+ ۱. **گام ۱۱ را باز کنید، «ساخت جزوه + شوک‌آزمون» را بزنید.** برگهٔ چاپی را بدهید دستش؛ بگذارید
107
+ خودش یک عدد را با ماشین‌حساب بازتولید کند.
108
+ ۲. **برگهٔ شاهد زنده** (گام ۲): نشان می‌دهد قیمت‌ها همین حالا از سرویس خوانده شده‌اند، با ساعت،
109
+ نشانی و اثر انگشت پاسخ خام. این برای رفع شک «عددها را خودت نوشتی» است.
110
+ ۳. **آزمون کور** (گام ۱۰): شش پرسش؛ اول او حدس می‌زند، بعد پاسخ برنامه با فرمول و روش دوم رو
111
+ می‌شود. اگر ماشین‌حساب او با برنامه نخواند، برگه اعتبار ندارد.
112
+ ۴. **دفتر آزمون زنده** (گام ۹): پنج روز کاری، هر روز شصت ثانیه ثبت. آخر هفته برگهٔ کارنامه با
113
+ زنجیرهٔ هش بیرون می‌آید: هیچ سطری بعد از ثبت عوض نشده است.
114
+ ۵. **پیمان‌نامهٔ نمایش** (گام ۱۰، کارت ۴): یک برگ دو امضا: چه چیزی اثبات می‌شود (بازتولید عدد،
115
+ کارمزد واقعی، آستانهٔ افتادن، زنجیرهٔ هش) و چه چیزی نه (سود آینده، پیش‌بینی قیمت).
116
+
117
+ اگر پرسید «درصد سودت چقدر است؟»، جواب درست این است: «درصد سود را وعده نمی‌دهم. نشان می‌دهم
118
+ چه چیزی ریاضی می‌ماند و چه چیزی می‌افتد، با کارمزد واقعی و با عددی که خودتان روی ماشین‌حساب
119
+ بازتولید می‌کنید.»
120
+
121
+ ## ۶. کاری که فقط خودتان می‌توانید بکنید (کوتاه و بدون دور زدن)
122
+
123
+ - **عدد وجه تضمین** را از کارگزاری بگیرید (یا از پنل برخط) و در گام ۳ وارد کنید. تا وقتی این
124
+ عدد نباشد، فاصلهٔ مارجین‌کال با فرض ۲۰٪ حساب می‌شود، نه با عدد واقعی.
125
+ - **شصت ثانیهٔ ضبط روزانه** (مراسم گام ۹): این تنها کاری است که سیستم نمی‌تواند به‌جای شما
126
+ انجام دهد و دقیقاً همان چیزی است که یک کارفرما برایش پول می‌دهد.
127
+ - **سه تماس**: سه کارگزاری بپرسید «آیا برای مشتری، وب‌سرویس یا فایل روزانه می‌دهید؟» جواب‌ها را
128
+ در گام ۲ همان دفتر اتصال وارد کنید. هزینه‌اش صفر است.
129
+
130
+ ## ۷. خط قرمزها (که در همین سند رعایت شده)
131
+
132
+ - هیچ‌جا نگفته‌ایم «درصد موفقیت فلان راهبرد ۹۰٪ است». هر عدد یا قفل‌شده است، یا مدل‌محور با
133
+ فرض صریح، یا نقل‌شده با نام منبع.
134
+ - «نرخ تاب‌آوری» احتمال سود نیست؛ سهم شوک‌هایی است که راهبرد از آن‌ها سالم بیرون آمده.
135
+ - دادهٔ تاریخی بلند در این محیط در دسترس نبود، پس هیچ «درصد برد تاریخی» ادعا نشده است.
136
+ - ابزار سنجش منبع، هرگز از حافظهٔ کهنه «موفقیت تازه» نمی‌سازد؛ اگر شبکه جواب ندهد، صریح می‌گوید «پاسخی نیامد». (قفل آزمون: `tests/test_datafeed_honesty.py`.)
137
+ - هیچ سفارشی به کارگزاری فرستاده نمی‌شود؛ تصمیم‌گیری انسانی است. (الزام ابلاغیهٔ مهر ۱۳۹۹
138
+ دربارهٔ معاملات الگوریتمی مشتریان برخط.)
139
+
140
+ ## ۸. از کجا شروع کنم (سه فرمان، همین امشب)
141
+
142
+ ```bash
143
+ cd MATERIALS/money/gui
144
+ python3 strategy_audit.py # جزوهٔ راهبردها + حسابرسی دو-روشی
145
+ python3 edge_stress.py # شوک‌آزمون: کجا می‌افتد
146
+ python3 bankroll.py --capital 100000000 --target 400000000 # ریاضیِ بقا و زمان
147
+ ```
148
+
149
+ خروجی‌ها: `data/strategy-library.html`، `data/edge-stress.html`، `data/bankroll.html` و نسخه‌های
150
+ متنی همین‌ها. در رابط مرورگری هم همه‌شان با یک دکمه در **گام ۱۱** ساخته می‌شوند.
151
+
152
+ ---
153
+
154
+ ✍️ تهیه‌کنندهٔ جزوات: **Masoud Mojarabian** · 📱 +989126630554 · ✈️ [Telegram: Mojarabian](https://t.me/Mojarabian) · 📸 [Instagram: Mojarabian.Art](https://instagram.com/Mojarabian.Art)