smart-org/docs/current-infra-notes.md

# زیرساخت فعلی — یادداشت مرجع

> این سند خلاصهٔ بررسی کد فعلی ربات تلگرام است، فقط برای درک زیرساخت موجود.
> **نسخهٔ وب جدید هیچ‌کدام از این فایل‌ها را import نمی‌کند.** هر قابلیت با یک
> adapter مستقل داخل `web/` بازنویسی می‌شود. این سند صرفاً قراردادها و محدودیت‌هایی
> را ثبت می‌کند که باید در adapterهای جدید حفظ شوند.

---

## ۱. Domain Routing و Preview Domain

منابع بررسی‌شده: `caddy_manager.py` (۲۵۹ خط)، `port_registry.py` (۵۳۱ خط).

### ۱.۱ Caddy

- مسیر فایل: `CADDYFILE_PATH = /etc/caddy/Caddyfile` (یک فایل مشترک سیستمی).
- دامنهٔ wildcard: `WILDCARD_DOMAIN = msa.artacloud.ir`.
- **allowlist سخت‌گیرانهٔ host:** فقط hostهای تک‌label زیر دامنهٔ wildcard مجازند.
  الگوی فعلی: `[a-z0-9\-]{1,63}\.msa\.artacloud\.ir`. هر کاراکتری که بتواند از بلوک
  سایت خارج شود (آکولاد، کوتیشن، فاصله، newline) رد می‌شود.
- **target فقط local:** الگوی فعلی `(https?://)?(localhost|127\.0\.0\.1):\d{1,5}`.
  این برای جلوگیری از SSRF است — نباید هیچ‌وقت به host دیگر proxy شود.
- **چرخهٔ امن نوشتن:** خواندن فایل → ساخت/جایگزینی بلوک → نوشتن → `caddy validate`
  → در صورت خطا **بازگردانی به نسخهٔ قبلی** → `systemctl reload caddy` و در صورت
  شکست `caddy reload --config ...`.
- پیدا کردن بلوک سایت با شمارش عمق آکولاد انجام می‌شود (نه regex)، چون بلوک‌ها
  تودرتو هستند (`handle`, `route`, `tls`, `header`).

### ۱.۲ Port Registry

دو جدول در SQLite (`data/memory.db`):

| جدول | نقش |
|---|---|
| `port_registry` | `port` (PK)، `user_id`، `project_name`، `service_name`، `subdomain`، `description`، `created_at` — یکتا روی `(user_id, project_name, service_name)` |
| `subdomain_registry` | `host` (PK)، `user_id`، `project_name`، `port`، `protected`، `created_at` — ledger مالکیت دامنه |

قواعد کلیدی که باید در `DomainRouterPort` جدید حفظ شوند:

- محدودهٔ تخصیص port: `8080-8999`.
- `SYSTEM_RESERVED_PORTS = {22, 53, 80, 443, 2019, 3000, 5432, 6379, 8008}`.
- `SYSTEM_PROTECTED_PORTS = {3000, 35555, 35556, 35557} ∪ reserved` — یک پروژهٔ
  کاربر هرگز نباید به این‌ها proxy کند، وگرنه سرویس tenant دیگر عمومی می‌شود.
- `MAX_SUBDOMAINS_PER_PROJECT = 5`.
- `SYSTEM_OWNER_PROJECT = "__system__"` برای hostهای بدون مالک شناخته‌شده.
- snapshot پورت‌های listening با `ss -tlnH` گرفته می‌شود. اگر snapshot ممکن نبود
  (`None`)، تخصیص **رد می‌شود** — تفاوت «چیزی گوش نمی‌دهد» با «نمی‌دانیم» حفظ می‌شود.
- در تخصیص هم‌زمان، `IntegrityError` گرفته و تا ۵ بار rescan/retry می‌شود.
- هر host دقیقاً یک مالک دارد؛ بدون این ledger هر پروژه می‌توانست دامنهٔ پروژهٔ دیگر را
  حذف یا hijack کند.
- hostهایی که قابل انتساب به پروژه نیستند `protected = 1` می‌شوند (فقط admin).

### ۱.۳ تصمیم برای نسخهٔ وب

- `DomainRouterPort` با متدهای `allocate_port` / `claim_preview_domain` /
  `configure_reverse_proxy` / `remove_preview_domain` / `list_project_domains`.
- دو adapter: `ManagedDomainRouterAdapter` (mock، بدون لمس Caddy) و
  `CaddyDomainRouterAdapter` (واقعی، پشت env flag `DOMAIN_ROUTER=caddy`).
- مالکیت دامنه به `organization_id` + `project_id` در PostgreSQL منتقل می‌شود،
  نه `user_id` تلگرام.

---

## ۲. Git / Gitea

منابع بررسی‌شده: `git_manager.py` (۱۰۶۴ خط)، `gitea_api.py` (۲۱۵ خط).

### ۲.۱ تنظیمات فعلی (از `config.py`)

| متغیر | مقدار پیش‌فرض |
|---|---|
| `GITEA_URL` | `https://git.msa.artacloud.ir` (عمومی، برای نمایش) |
| `GITEA_INTERNAL_URL` | `http://127.0.0.1:3000` (برای تماس API) |
| `GITEA_ADMIN_USER` | `root` |
| `GITEA_ADMIN_TOKEN` | خالی — بدون آن همهٔ قابلیت‌های Gitea غیرفعال است |

### ۲.۲ رفتار GitManager

- `ensure_gitea_repo(repo_name, owner, description, private=True)`: اگر repo نبود
  می‌سازد، اگر بود و private نبود آن را PATCH می‌کند به private. `auto_init=False`،
  `default_branch=main`.
- `generate_project_credentials(project_name, owner_id)`: نام کاربری به شکل
  `u{owner_id}_{clean_name[:room]}_{sha1(f"{owner_id}:{project_name}")[:8]}` و رمز
  `secrets.token_urlsafe(12)`. هش کوتاه برای جلوگیری از collision دو پروژه با نام
  سانیتایز یکسان ضروری است (وگرنه PATCH رمز کاربر مشترک، credential پروژهٔ اول را
  بی‌صدا خراب می‌کند). سقف ۳۶ کاراکتر Gitea رعایت می‌شود.
- قفل per-repo (`_RepoLock`) که برای همان asyncio task قابل re-enter است؛
  `git_publish`/`git_sync` داخل بخش بحرانی خودشان دوباره lock می‌گیرند، پس
  `asyncio.Lock` ساده deadlock می‌داد.
- پاک‌سازی `index.lock` فقط اگر قدیمی‌تر از `STALE_LOCK_AGE_SECONDS = 30` باشد
  (حذف lock جوان می‌تواند index را خراب کند).

### ۲.۳ GiteaApiClient

متدها: `create_pr`، `pr_status`، `merge_pr`، `list_open_prs`،
`list_labeled_issues(label="agybot")`، `comment_issue`، `close_issue`.
نکات:

- transport تزریق‌پذیر است (`request` callable) تا تست بدون شبکه اجرا شود.
- token هرگز در هیچ مقدار برگشتی یا prompt قرار نمی‌گیرد؛ `base_url` امن برای نمایش است.
- صفحه‌بندی با cursor `page` انجام می‌شود تا نتایج در یک صفحه بریده نشوند.
- خواندن پیام خطا از `message` / `error` / `errors` (نه فقط `error`).
- برچسب `agybot` روی issue آن را به task سازمانی تبدیل می‌کند.

### ۲.۴ تصمیم برای نسخهٔ وب

- `GitProviderPort` با متدهای `ensure_project_repo` / `create_branch` /
  `commit_files` / `open_pull_request` / `merge_pull_request` / `get_repo_status`.
- `GiteaGitAdapter` (واقعی) و `MockGitAdapter` (پیش‌فرض dev).
- نام repo در نسخهٔ وب: `orgslug-projectslug-shortid` (collision-free).
- credential هر پروژه **encrypted at rest** در `project_git_credentials` ذخیره می‌شود؛
  token/password هرگز خام به frontend برنمی‌گردد.
- admin token فقط سمت backend می‌ماند.

---

## ۳. جمع‌بندی

| قابلیت فعلی | منبع فعلی | جایگزین در نسخهٔ وب |
|---|---|---|
| Caddy subdomain routing | `caddy_manager.py` | `DomainRouterPort` + `CaddyDomainRouterAdapter` |
| Port/subdomain ledger | `port_registry.py` (SQLite) | جداول `preview_ports` / `preview_domains` (PostgreSQL) |
| Gitea repo + credentials | `git_manager.py` | `GitProviderPort` + `GiteaGitAdapter` |
| PR / issue workflow | `gitea_api.py` | همان port، متدهای PR/issue |

**هیچ‌کدام از این فایل‌ها در runtime نسخهٔ وب import نمی‌شوند.** فقط قراردادها،
الگوهای اعتبارسنجی و قواعد امنیتی بالا به عنوان مرجع استفاده شده‌اند.