راهنمای متغیرها¶

مقدمه¶

تمامی مستندات از متغیرهای جایگزین برای آدرس‌های پایه استفاده می‌کنند. این به شما اجازه می‌دهد به راحتی آدرس‌ها را تغییر دهید بدون نیاز به ویرایش تمام فایل‌ها.

متغیرهای تعریف شده¶

1. `{{ USSO_BASE_URL }}`¶

توضیحات: آدرس پایه سرویس احراز هویت USSO

مقدار پیش‌فرض:

https://usso.example.com

مثال‌های استفاده:

# Login
curl -X POST "{{ USSO_BASE_URL }}/auth/login"

# Refresh
curl -X POST "{{ USSO_BASE_URL }}/auth/refresh"

2. `{{ API_BASE_URL }}`¶

توضیحات: آدرس پایه API اصلی

مقدار پیش‌فرض:

https://api.example.com

مثال‌های استفاده:

# Get symbols
curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/symbols"

# Get ticker
curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/tickers/BTC-IRR"

# Create order
curl -X POST "{{ API_BASE_URL }}/api/exchange/v1/orders"

چگونه متغیرها را جایگزین کنیم؟¶

روش 1: استفاده از sed (Linux/Mac)¶

# تعریف مقادیر جدید
export NEW_USSO_BASE_URL="https://auth.mycompany.com"
export NEW_API_BASE_URL="https://api.mycompany.com"

# جایگزینی در تمام فایل‌ها
find docs -name "*.md" -exec sed -i \
  -e "s|{{ USSO_BASE_URL }}|$NEW_USSO_BASE_URL|g" \
  -e "s|{{ API_BASE_URL }}|$NEW_API_BASE_URL|g" \
  {} \;

روش 2: استفاده از Python¶

import os
import re

# مقادیر جدید
variables = {
    "{{ USSO_BASE_URL }}": "https://auth.mycompany.com",
    "{{ API_BASE_URL }}": "https://api.mycompany.com"
}

# جایگزینی در تمام فایل‌ها
for root, dirs, files in os.walk("docs"):
    for file in files:
        if file.endswith(".md"):
            filepath = os.path.join(root, file)
            with open(filepath, "r", encoding="utf-8") as f:
                content = f.read()

            for old, new in variables.items():
                content = content.replace(old, new)

            with open(filepath, "w", encoding="utf-8") as f:
                f.write(content)

print("جایگزینی کامل شد!")

روش 3: استفاده از mkdocs با plugin¶

# mkdocs.yml
plugins:
  - replace:
      replacements:
        - from: "{{ USSO_BASE_URL }}"
          to: "https://auth.mycompany.com"
        - from: "{{ API_BASE_URL }}"
          to: "https://api.mycompany.com"

روش 4: ویرایش دستی¶

می‌توانید هر فایل را به صورت دستی ویرایش کنید:

# مثال: ویرایش README.md
sed -i 's|{{ USSO_BASE_URL }}|https://auth.mycompany.com|g' docs/README.md
sed -i 's|{{ API_BASE_URL }}|https://api.mycompany.com|g' docs/README.md

محیط‌های مختلف¶

محیط توسعه (Development)¶

export USSO_BASE_URL="http://localhost:8000"
export API_BASE_URL="http://localhost:8000"

محیط تست (Staging)¶

export USSO_BASE_URL="https://staging-auth.example.com"
export API_BASE_URL="https://staging-api.example.com"

محیط تولید (Production)¶

export USSO_BASE_URL="https://auth.example.com"
export API_BASE_URL="https://api.example.com"

لیست فایل‌های شامل متغیرها¶

فایل‌های اصلی¶

[x] docs/README.md
[x] docs/01-api-basics/authentication.md
[x] docs/01-api-basics/conventions.md
[x] docs/01-api-basics/pagination-filtering.md
[x] docs/01-api-basics/errors.md
[x] docs/02-domain/market-logic.md
[x] docs/02-domain/order-lifecycle.md

فایل‌های API Reference¶

[x] docs/03-api-reference/users.md
[x] docs/03-api-reference/wallets.md
[x] docs/03-api-reference/market-symbols.md
[x] docs/03-api-reference/market-sessions.md
[x] docs/03-api-reference/orders.md
[x] docs/03-api-reference/trades.md
[x] docs/03-api-reference/market-data.md

فایل‌های مثال¶

[x] docs/04-examples/curl-snippets.md

مثال کامل¶

قبل از جایگزینی¶

# فایل: docs/README.md
curl -X POST "{{ USSO_BASE_URL }}/auth/login" ...
curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/symbols" ...

بعد از جایگزینی (برای محیط تولید)¶

# فایل: docs/README.md
curl -X POST "https://auth.example.com/auth/login" ...
curl -X GET "https://api.example.com/api/exchange/v1/symbols" ...

بعد از جایگزینی (برای محیط توسعه)¶

# فایل: docs/README.md
curl -X POST "http://localhost:8000/auth/login" ...
curl -X GET "http://localhost:8000/api/exchange/v1/symbols" ...

اسکریپت جایگزینی خودکار¶

#!/bin/bash

# اسکریپت جایگزینی متغیرها

if [ $# -ne 2 ]; then
    echo "استفاده: $0 <USSO_BASE_URL> <API_BASE_URL>"
    echo "مثال: $0 https://auth.example.com https://api.example.com"
    exit 1
fi

USSO_URL=$1
API_URL=$2

echo "جایگزینی متغیرها..."
echo "USSO: $USSO_URL"
echo "API: $API_URL"

# جایگزینی در تمام فایل‌های Markdown
find docs -name "*.md" -type f | while read file; do
    sed -i "s|{{ USSO_BASE_URL }}|$USSO_URL|g" "$file"
    sed -i "s|{{ API_BASE_URL }}|$API_URL|g" "$file"
    echo "✓ $file"
done

echo ""
echo "جایگزینی کامل شد!"
echo "برای مشاهده تغییرات:"
echo "  mkdocs serve --dev-addr 0.0.0.0:8000"

استفاده:

chmod +x replace_vars.sh
./replace_vars.sh https://auth.mycompany.com https://api.mycompany.com

نکات مهم¶

1. پشتیبان گیری¶

قبل از جایگزینی، پشتیبان بگیرید:

cp -r docs docs.backup

2. بررسی تغییرات¶

# بررسی فایل‌های تغییر کرده
git diff docs/

3. بازگردانی¶

# اگر مشکلی پیش آمد
rm -rf docs
cp -r docs.backup docs

4. Git¶

# اگر از Git استفاده می‌کنید
git add docs/
git commit -m "refactor: جایگزینی متغیرهای پایه"

بهترین روش‌ها¶

✅ انجام دهید¶

قبل از جایگزینی پشتیبان بگیرید
تغییرات را تست کنید
از Git استفاده کنید
مستندات را به‌روز نگه دارید

❌ انجام ندهید¶

بدون پشتیبان جایگزینی کنید
فایل‌های اصلی را دستکاری کنید
متغیرها را در کد قرار دهید

تست جایگزینی¶

بعد از جایگزینی، این دستور را اجرا کنید:

# بررسی باقی ماندن متغیرها
grep -r "{{ USSO_BASE_URL }}" docs/ && echo "❌ متغیر باقی مانده" || echo "✅ همه جایگزین شدند"
grep -r "{{ API_BASE_URL }}" docs/ && echo "❌ متغیر باقی مانده" || echo "✅ همه جایگزین شدند"

اگر خروجی نداشت، یعنی همه متغیرها جایگزین شده‌اند.

نکته: این فایل را در مستندات نگه دارید تا توسعه‌دهندگان بعدی بدانند چگونه متغیرها را مدیریت کنند.