# فصل ۰۷ — پروژهٔ نهایی: یک سامانهٔ کاملِ نگه‌داشتنی

<div dir="rtl">

# فصل ۰۷ — پروژهٔ نهایی: یک سامانهٔ کاملِ نگه‌داشتنی

## در این فصل چه یاد می‌گیری

**فصلِ آخرِ داربست، و هیچ مفهومِ تازه‌ای ندارد.** هر چه لازم داری در شش ترمِ قبل ساخته‌ای.

اینجا یک چیز می‌سازیم: **سیاههٔ تحویلی که خودش را اجرا می‌کند.** نه فهرستی که آدم تیک بزند — هجده بندِ اجراشدنی که به پوشهٔ پروژه نگاه می‌کنند، دستورهایش را در یک نسخهٔ تازه می‌زنند، دروازه‌اش را بالا می‌آورند و ردِ ممیزی‌اش را می‌خوانند.

بعد آن را روی دو پروژه اجرا می‌کنیم. **پروژهٔ معمول — همان که همه‌جا هست — ۱ از ۱۸ می‌گیرد.** پروژه‌ای که همهٔ قطعه‌های این ترم را دارد **۱۵ از ۱۸** می‌گیرد؛ سه بندِ قرمزش **یک ریشه** دارند و ریشه‌اش دقیقاً همان درسِ اولِ کلِ دوره است: **مدل از خطِ پایه بهتر نیست — ۰٫۷۹۳۳ در برابرِ ۰٫۷۸۵۰.**

آن یک ریشه را می‌بندیم و **۱۸ از ۱۸** می‌شود.

![یک دستگاهِ کامل با کارتِ بازرسی که خودش پرش کرده](/lesson-assets/t6-s07-capstone/prompt/01-image-self-inspecting-machine.png)

آخر این فصل می‌توانی:

- سیاههٔ تحویلی بنویسی که به‌جای پرسیدن، **بررسی می‌کند**
- پروژه‌ات را با آن بسنجی و بدانی دقیقاً کجا ناتمام است
- بگویی هر بندِ سیاهه به کدام قانونِ ثابتِ این دوره خدمت می‌کند
- کاری تحویل بدهی که کسِ دیگری بتواند نگهش دارد

## قبل از شروع

**هر شش فصلِ این ترم، و هر پنج ترمِ قبلش.** هیچ چیزِ تازه‌ای اینجا نیست جز چیدنشان کنارِ هم.

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

> 📓 **نوت‌بوک:** [نوت‌بوک این فصل را در Colab باز کن](/notebooks/darbast/term-6-team-and-delivery/session-07-capstone.ipynb) — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

</div>

| اجرا | زمانِ تقریبی |
|---|---|
| کلِ نوت‌بوک روی CPU | حدودِ یک دقیقه |
| GPU | لازم نیست |

<div dir="rtl">

## ۱. دو پروژه

**پروژهٔ معمول سه فایل دارد:** داده، یک ماژولِ مدل، و یک `README` که می‌گوید «نوت‌بوک را باز کن». **این کاریکاتور نیست؛ اکثریتِ پروژه‌های واقعی دقیقاً همین‌اند** و اغلب حتی همان ماژول را هم ندارند.

**پروژهٔ کامل دوازده فایل دارد** و هر فایلش از یکی از فصل‌های این ترم آمده: مجموعهٔ تست و دروازه از فصلِ ۲، `README`ی که اجرا می‌شود و تصمیم‌نامه از فصلِ ۳، سیاههٔ ریسک و ردِ ممیزی از فصلِ ۴، و طرحِ انتشار و برگشت از ترمِ ۴.

</div>

```python
import json
import re
import shlex
import sqlite3

TICKS = "`" * 3
COMMON = ('"""model.py — پاک‌سازی، قرارداد، تقسیم، ویژگی، مدل."""\n'
          'CATEGORIES = ("پرداخت", "ارسال", "حساب کاربری", "اپلیکیشن")\n'
          'REQUIRED = ("ticket_id", "week", "category", "text", "escalated")\n'
          "THRESHOLD = 0.5\n\n\n"
          "def normalise(text):\n"
          '    return " ".join(text.replace("ي", "ی").replace("ك", "ک").split())\n\n\n'
          "def features(rows):\n"
          '    return [normalise(r["text"]) for r in rows]\n\n\n'
          "def split(rows, upto=18):\n"
          '    return ([r for r in rows if r["week"] < upto],\n'
          '            [r for r in rows if r["week"] >= upto])\n\n\n')
MODEL_COUNT = COMMON + (
    "import json\n\n\n"
    "def fit(rows):\n"
    "    score = {}\n"
    "    for row, text in zip(rows, features(rows)):\n"
    "        for word in set(text.split()):\n"
    '            score[word] = score.get(word, 0) + (1 if row["escalated"] else -1)\n'
    "    return score\n\n\n"
    "def predict(fitted, text):\n"
    "    return int(sum(fitted.get(w, 0) for w in normalise(text).split()) > 0)\n\n\n"
    "def save(fitted, path):\n"
    '    json.dump(fitted, open(path, "w", encoding="utf-8"), ensure_ascii=False)\n\n\n'
    "def load(path):\n"
    '    return json.load(open(path, encoding="utf-8"))\n')
MODEL_REAL = COMMON + (
    "import pickle\n\n"
    "from sklearn.feature_extraction.text import CountVectorizer\n"
    "from sklearn.linear_model import LogisticRegression\n"
    "from sklearn.pipeline import make_pipeline\n\n\n"
    "def fit(rows):\n"
    "    pipe = make_pipeline(CountVectorizer(), LogisticRegression(max_iter=1000))\n"
    '    pipe.fit(features(rows), [r["escalated"] for r in rows])\n'
    "    return pipe\n\n\n"
    "def predict(fitted, text):\n"
    "    return int(fitted.predict_proba([normalise(text)])[0][1] >= THRESHOLD)\n\n\n"
    "def save(fitted, path):\n"
    '    pickle.dump(fitted, open(path, "wb"))\n\n\n'
    "def load(path):\n"
    '    return pickle.load(open(path, "rb"))\n')

FULL = {
    "data.json": json.dumps(TICKETS, ensure_ascii=False),
    "model.py": MODEL_COUNT,
    "tests.py": '"""tests.py — مجموعهٔ تستِ پروژه، با ردهٔ سرعت."""\n'
                "import json\n\nimport model\n\n"
                'ROWS = json.load(open("data.json", encoding="utf-8"))\n\n\n'
                "def test_normalise_arabic():\n"
                '    assert model.normalise("كارت") == "کارت", model.normalise("كارت")\n\n\n'
                "def test_schema_categories():\n"
                '    unknown = sorted({r["category"] for r in ROWS} - set(model.CATEGORIES))\n'
                '    assert not unknown, f"دستهٔ ناشناخته: {unknown}"\n\n\n'
                "def test_split_shares_no_row():\n"
                "    train, test = model.split(ROWS)\n"
                '    shared = {r["ticket_id"] for r in train} & {r["ticket_id"] for r in test}\n'
                '    assert not shared, f"{len(shared)} تیکت در هر دو طرف"\n\n\n'
                "def test_split_is_chronological():\n"
                "    train, test = model.split(ROWS)\n"
                '    assert max(r["week"] for r in train) < min(r["week"] for r in test)\n\n\n'
                "def test_features_ignore_the_label():\n"
                "    row = dict(ROWS[0])\n"
                "    before = model.features([row])\n"
                '    row["escalated"] = 1 - row["escalated"]\n'
                '    assert model.features([row]) == before, "ویژگی به برچسب نگاه می‌کند"\n\n\n'
                "def test_model_beats_baseline():\n"
                "    train, test = model.split(ROWS)\n"
                "    fitted = model.fit(train)\n"
                '    hit = sum(model.predict(fitted, r["text"]) == r["escalated"]'
                " for r in test) / len(test)\n"
                '    share = sum(r["escalated"] for r in test) / len(test)\n'
                "    base = max(share, 1 - share)\n"
                '    assert hit > base + 0.02, f"مدل {hit:.4f} · خطِ پایه {base:.4f}"\n\n\n'
                "SUITE = [\n"
                '    ("normalise_arabic", "fast", test_normalise_arabic),\n'
                '    ("schema_categories", "fast", test_schema_categories),\n'
                '    ("split_shares_no_row", "fast", test_split_shares_no_row),\n'
                '    ("split_is_chronological", "fast", test_split_is_chronological),\n'
                '    ("features_ignore_the_label", "fast", test_features_ignore_the_label),\n'
                '    ("model_beats_baseline", "slow", test_model_beats_baseline),\n'
                "]\n",
    "ci.py": '"""ci.py — دروازهٔ خودکار: سریع اول، بعد کند."""\n'
             "import sys\n\nimport tests\n\n"
             "failures = []\n"
             'for kind in ("fast", "slow"):\n'
             "    for name, group, check in tests.SUITE:\n"
             "        if group != kind:\n            continue\n"
             "        try:\n            check()\n"
             "        except Exception as error:\n"
             '            failures.append(f"{name} — {type(error).__name__}: {error}")\n'
             "            break\n"
             "    if failures:\n        break\n"
             'print("قرمز: " + failures[0] if failures else "سبز")\n'
             "sys.exit(1 if failures else 0)\n",
    "prepare.py": '"""prepare.py — پاک‌سازی و ذخیره."""\n'
                  "import json\n\nimport model\n\n"
                  'rows = json.load(open("data.json", encoding="utf-8"))\n'
                  "for row in rows:\n"
                  '    row["text"] = model.normalise(row["text"])\n'
                  'json.dump(rows, open("clean.json", "w", encoding="utf-8"),'
                  " ensure_ascii=False)\n"
                  'print("clean.json ساخته شد:", len(rows), "ردیف")\n',
    "train.py": '"""train.py — آموزش روی برشِ زمانی و ذخیرهٔ مدل."""\n'
                "import json\n\nimport model\n\n"
                'rows = json.load(open("clean.json", encoding="utf-8"))\n'
                "train, _ = model.split(rows)\n"
                'model.save(model.fit(train), "model.bin")\n'
                'print("model.bin ساخته شد از", len(train), "ردیف")\n',
    "evaluate.py": '"""evaluate.py — دقت روی هفته‌های بعدی، کنارِ خطِ پایه."""\n'
                   "import json\n\nimport model\n\n"
                   'fitted = model.load("model.bin")\n'
                   'rows = json.load(open("clean.json", encoding="utf-8"))\n'
                   "_, test = model.split(rows)\n"
                   'hit = sum(model.predict(fitted, r["text"]) == r["escalated"]'
                   " for r in test) / len(test)\n"
                   'share = sum(r["escalated"] for r in test) / len(test)\n'
                   'print(f"دقت {hit:.4f} · خطِ پایه {max(share, 1 - share):.4f}"\n'
                   '      f" · روی {len(test)} ردیفِ آینده")\n',
    "deploy.py": '"""deploy.py — انتشارِ تدریجی با طرحِ برگشت."""\n'
                 'STAGES = ["shadow", "canary", "full"]\n'
                 'ROLLBACK = "نسخهٔ قبلی از رجیستری، با یک فرمان"\n'
                 'print("مرحله‌ها:", STAGES, "· برگشت:", ROLLBACK)\n',
    "record.py": '"""record.py — ردِ ممیزی: نسخهٔ داده، نسخهٔ مدل، و هر پیش‌بینی."""\n'
                 "import hashlib\nimport json\nimport os\nimport sqlite3\n\nimport model\n\n"
                 'if os.path.exists("audit.db"):\n    os.remove("audit.db")\n'
                 'db = sqlite3.connect("audit.db")\n'
                 'db.execute("PRAGMA foreign_keys = ON")\n'
                 'db.executescript("""\n'
                 "CREATE TABLE data_versions (id TEXT PRIMARY KEY, rows INTEGER);\n"
                 "CREATE TABLE model_versions (id TEXT PRIMARY KEY,\n"
                 "    data_id TEXT NOT NULL REFERENCES data_versions(id));\n"
                 "CREATE TABLE predictions (id INTEGER PRIMARY KEY, ticket_id TEXT,\n"
                 "    answer INTEGER, model_id TEXT NOT NULL REFERENCES model_versions(id));\n"
                 '""")\n'
                 'rows = json.load(open("clean.json", encoding="utf-8"))\n'
                 "train, test = model.split(rows)\n"
                 'data_id = hashlib.sha256(json.dumps([r["ticket_id"] for r in train])'
                 ".encode()).hexdigest()[:12]\n"
                 'model_id = "m-" + data_id\n'
                 'fitted = model.load("model.bin")\n'
                 'db.execute("INSERT INTO data_versions VALUES (?, ?)", (data_id, len(train)))\n'
                 'db.execute("INSERT INTO model_versions VALUES (?, ?)", (model_id, data_id))\n'
                 'db.executemany("INSERT INTO predictions (ticket_id, answer, model_id)'
                 ' VALUES (?, ?, ?)",\n'
                 '               [(r["ticket_id"], model.predict(fitted, r["text"]), model_id)\n'
                 "                for r in test])\n"
                 "db.commit()\n"
                 'print("ردِ ممیزی ثبت شد:",\n'
                 '      db.execute("SELECT COUNT(*) FROM predictions").fetchone()[0],'
                 ' "پیش‌بینی")\n',
    "README.md": "# خطِ تشدید\n\n## اجرا\n\n"
                 + "\n\n".join(f"{TICKS}bash\n{step}\n{TICKS}" for step in
                               ("python prepare.py", "python train.py",
                                "python evaluate.py", "python ci.py", "python record.py"))
                 + "\n",
    "docs/adr/0001-time-split.md": "# ۰۰۰۱ — تقسیمِ زمانی به‌جای تصادفی\n\n"
                                   "وضعیت: پذیرفته‌شده\n"
                                   "زمینه: با تقسیمِ تصادفی رتبه‌بندیِ مدل‌ها وارونه می‌شد.\n"
                                   "تصمیم: ارزیابی فقط روی برشِ زمانیِ بعدی.\n"
                                   "پیامد: عددها پایین‌تر و قابلِ اتکا شدند.\n"
                                   "بدیلِ ردشده: تقسیمِ تصادفی با چند seed.\n"
                                   "نگهبان: python ci.py\n",
    "risks.md": "# سیاههٔ ریسک\n\n"
                "| ریسک | احتمال | اثر | نگهبان |\n|---|---|---|---|\n"
                "| نشتیِ ردیفِ تکراری | ۴ | ۵ | split_shares_no_row |\n"
                "| ارزیابیِ آفلاین وارونه | ۴ | ۵ | split_is_chronological |\n"
                "| برچسب در ویژگی‌ها | ۲ | ۵ | features_ignore_the_label |\n"
                "| قراردادِ داده می‌شکند | ۴ | ۳ | schema_categories |\n"
                "| مدل از خطِ پایه بدتر شود | ۳ | ۴ | model_beats_baseline |\n"
                "| مستند از کد عقب بماند | ۵ | ۲ | README در دروازه |\n",
}
TYPICAL = {"data.json": FULL["data.json"], "model.py": FULL["model.py"],
           "README.md": "# خطِ تشدید\n\nنوت‌بوک را باز کن و سلول‌ها را به‌ترتیب بزن.\n"}


def make(name, files):
    root = WORK / name
    shutil.rmtree(root, ignore_errors=True)
    for path, text in files.items():
        write(root / path, text)
    return root


complete = make("project-complete", FULL)
typical = make("project-typical", TYPICAL)
print("پروژهٔ کامل:", len(FULL), "فایل · پروژهٔ معمول:", len(TYPICAL), "فایل")
```

```text
پروژهٔ کامل: 12 فایل · پروژهٔ معمول: 3 فایل
```

<div dir="rtl">

## ۲. سیاهه‌ای که خودش را اجرا می‌کند

**هجده بند. هیچ‌کدام سؤال نیستند.** هر بند یا به فایل نگاه می‌کند، یا برنامه‌ای را واقعاً اجرا می‌کند و کدِ خروجش را می‌خواند.

</div>

```python
BASH_BLOCK = re.compile(TICKS + r"bash\n(.*?)" + TICKS, re.S)


def read(root, name):
    path = root / name
    return path.read_text(encoding="utf-8") if path.exists() else ""


def run_readme(root):
    """هر دستورِ مستندشده، در یک نسخهٔ تازه (فصلِ ۳)."""
    fresh = WORK / "fresh"
    shutil.rmtree(fresh, ignore_errors=True)
    shutil.copytree(root, fresh)
    steps = [line.strip() for block in BASH_BLOCK.findall(read(root, "README.md"))
             for line in block.split("\n") if line.strip().startswith("python ")]
    return fresh, [(step, run_py(*shlex.split(step)[1:], cwd=fresh)) for step in steps]


def reconstructable(fresh):
    """یک پیش‌بینی: می‌شود به نسخهٔ مدل و دادهٔ سازنده‌اش برگرداندش؟ (فصلِ ۴)"""
    if not (fresh / "audit.db").exists():
        return False
    db = sqlite3.connect(fresh / "audit.db")
    row = db.execute("SELECT p.ticket_id, m.id, d.rows FROM predictions p"
                     " JOIN model_versions m ON m.id = p.model_id"
                     " JOIN data_versions d ON d.id = m.data_id LIMIT 1").fetchone()
    db.close()
    return bool(row)


def audit(root):
    """سیاههٔ تحویل — هر بند یک بررسیِ اجراشدنی است، نه یک سؤال."""
    fresh, steps = run_readme(root)
    tests_src = read(root, "tests.py")
    risks = read(root, "risks.md")
    adr = read(root, "docs/adr/0001-time-split.md")
    guard = re.search(r"نگهبان: (.+)", adr)
    guard_ok = bool(guard) and run_py(*shlex.split(guard.group(1))[1:], cwd=fresh)[0] == 0
    rows = [ln for ln in risks.split("\n") if ln.startswith("| ") and "---" not in ln][1:]
    return [
        ("کدِ اصلی در فایل است، نه در نوت‌بوک", bool(read(root, "model.py"))),
        ("مجموعهٔ تست دارد", tests_src.count("def test_") >= 5),
        ("تستِ سریع و کند از هم جدا شده‌اند",
         '"fast"' in tests_src and '"slow"' in tests_src),
        ("دروازه با کدِ خروج جواب می‌دهد", (root / "ci.py").exists()),
        ("دروازه همین حالا سبز است",
         (root / "ci.py").exists() and run_py("ci.py", cwd=fresh)[0] == 0),
        ("تستِ نشتی دارد", "shares_no_row" in tests_src),
        ("تستِ ناوردایی روی برچسب دارد", "features_ignore_the_label" in tests_src),
        ("قراردادِ داده دارد", "schema" in tests_src),
        ("خطِ پایه داخلِ تست است", "beats_baseline" in tests_src),
        ("README دستورِ اجرا دارد", len(steps) > 0),
        ("همهٔ دستورهای README در نسخهٔ تازه اجرا می‌شوند",
         bool(steps) and all(code == 0 for _, (code, _) in steps)),
        ("تصمیم‌نامه دارد", bool(adr)),
        ("تصمیم‌نامه نگهبانِ سبز دارد", guard_ok),
        ("سیاههٔ ریسک با حداقل پنج ردیف", len(rows) >= 5),
        ("هر ریسک ستونِ نگهبان دارد",
         bool(rows) and all(len(ln.split("|")) >= 6 and ln.split("|")[4].strip()
                            for ln in rows)),
        ("نسخهٔ داده و مدل ثبت می‌شود", "data_versions" in read(root, "record.py")),
        ("یک پیش‌بینی به نسخهٔ مدلش برمی‌گردد", reconstructable(fresh)),
        ("طرحِ انتشار و برگشت دارد",
         "shadow" in read(root, "deploy.py") and "ROLLBACK" in read(root, "deploy.py")),
    ]


for label, root in (("پروژهٔ معمول", typical), ("پروژهٔ کامل", complete)):
    result = audit(root)
    print(f"— {label} —")
    for item, ok in result:
        print(f"  {'✓' if ok else '✗'} {item}")
    print(f"  {sum(ok for _, ok in result)} از {len(result)}")
```

```text
— پروژهٔ معمول —
  ✓ کدِ اصلی در فایل است، نه در نوت‌بوک
  ✗ مجموعهٔ تست دارد
  ✗ تستِ سریع و کند از هم جدا شده‌اند
  ✗ دروازه با کدِ خروج جواب می‌دهد
  ✗ دروازه همین حالا سبز است
  ✗ تستِ نشتی دارد
  ✗ تستِ ناوردایی روی برچسب دارد
  ✗ قراردادِ داده دارد
  ✗ خطِ پایه داخلِ تست است
  ✗ README دستورِ اجرا دارد
  ✗ همهٔ دستورهای README در نسخهٔ تازه اجرا می‌شوند
  ✗ تصمیم‌نامه دارد
  ✗ تصمیم‌نامه نگهبانِ سبز دارد
  ✗ سیاههٔ ریسک با حداقل پنج ردیف
  ✗ هر ریسک ستونِ نگهبان دارد
  ✗ نسخهٔ داده و مدل ثبت می‌شود
  ✗ یک پیش‌بینی به نسخهٔ مدلش برمی‌گردد
  ✗ طرحِ انتشار و برگشت دارد
  1 از 18
— پروژهٔ کامل —
  ✓ کدِ اصلی در فایل است، نه در نوت‌بوک
  ✓ مجموعهٔ تست دارد
  ✓ تستِ سریع و کند از هم جدا شده‌اند
  ✓ دروازه با کدِ خروج جواب می‌دهد
  ✗ دروازه همین حالا سبز است
  ✓ تستِ نشتی دارد
  ✓ تستِ ناوردایی روی برچسب دارد
  ✓ قراردادِ داده دارد
  ✓ خطِ پایه داخلِ تست است
  ✓ README دستورِ اجرا دارد
  ✗ همهٔ دستورهای README در نسخهٔ تازه اجرا می‌شوند
  ✓ تصمیم‌نامه دارد
  ✗ تصمیم‌نامه نگهبانِ سبز دارد
  ✓ سیاههٔ ریسک با حداقل پنج ردیف
  ✓ هر ریسک ستونِ نگهبان دارد
  ✓ نسخهٔ داده و مدل ثبت می‌شود
  ✓ یک پیش‌بینی به نسخهٔ مدلش برمی‌گردد
  ✓ طرحِ انتشار و برگشت دارد
  15 از 18
```

<div dir="rtl">

**۱ از ۱۸، و ۱۵ از ۱۸.**

پروژهٔ معمول تنها بندی را می‌گیرد که رایگان است: کدش در یک فایل است. **همهٔ هفده بندِ دیگر چیزی می‌خواهند که کسی وقتش را نگذاشته** — و هیچ‌کدامشان از خودِ مدل سخت‌تر نبودند.

**و سه بندِ قرمزِ پروژهٔ کامل، هدیهٔ این فصل‌اند.** من این پروژه را ساختم تا کامل باشد، و سیاهه سه چیز پیدا کرد که ندیده بودم.

## ۳. سه قرمز، یک ریشه

</div>

```python
fresh, steps = run_readme(complete)
print("دروازه چه گفت؟", run_py("ci.py", cwd=fresh)[1].splitlines()[-1])
for step, (code, out) in steps:
    if code:
        print(f"{step} → {out.splitlines()[-1]}")
```

```text
دروازه چه گفت؟ قرمز: model_beats_baseline — AssertionError: مدل 0.7933 · خطِ پایه 0.7850
python ci.py → قرمز: model_beats_baseline — AssertionError: مدل 0.7933 · خطِ پایه 0.7850
```

<div dir="rtl">

**۰٫۷۹۳۳ در برابرِ ۰٫۷۸۵۰.**

سه بندِ قرمز — «دروازه سبز است»، «دستورهای `README` اجرا می‌شوند»، «تصمیم‌نامه نگهبانِ سبز دارد» — **هر سه یک چیز می‌گویند**، چون هر سه در نهایت همان `ci.py` را اجرا می‌کنند. **و آن یک چیز، درسِ اولِ کلِ این دوره است: مدل از خطِ پایه بهتر نیست.**

هشت هزارمِ بهبود. **مدلِ شمارشی به‌اندازهٔ «همیشه بگو تشدید نمی‌شود» خوب است**، و اگر خطِ پایه داخلِ تست نبود، عددِ ۰٫۷۹ روی هر اسلایدی قابلِ قبول به نظر می‌رسید.

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

## ۴. بستنِ ریشه

**اصلاح، عوض کردنِ یک فایل است: مدلِ شمارشی می‌رود و همان `LogisticRegression` ترمِ ۱ می‌آید.** بقیهٔ پروژه یک بایت هم عوض نمی‌شود، چون `train.py` و `evaluate.py` و `record.py` همه از پشتِ `model.fit` و `model.predict` کار می‌کنند — **همان مرزِ ماژولِ ترمِ ۱ فصلِ ۴.**

</div>

```python
write(complete / "model.py", MODEL_REAL)
after = audit(complete)
for item, ok in after:
    if not ok:
        print("✗", item)
print("پس از عوض کردنِ مدل:", sum(ok for _, ok in after), "از", len(after))
fresh, steps = run_readme(complete)
for step, (code, out) in steps:
    print(f"  {step:<22}{out.splitlines()[-1]}")
```

```text
پس از عوض کردنِ مدل: 18 از 18
  python prepare.py     clean.json ساخته شد: 2400 ردیف
  python train.py       model.bin ساخته شد از 1800 ردیف
  python evaluate.py    دقت 0.8283 · خطِ پایه 0.7850 · روی 600 ردیفِ آینده
  python ci.py          سبز
  python record.py      ردِ ممیزی ثبت شد: 600 پیش‌بینی
```

<div dir="rtl">

**۱۸ از ۱۸.**

و پنج خطِ آخر، تحویلِ نهایی‌اند: **هر خط یک دستورِ مستندشده است که در یک نسخهٔ تازهٔ پروژه اجرا شد و عددش را چاپ کرد.** کسی که فردا این مخزن را می‌گیرد، همین پنج خط را می‌زند و همین پنج عدد را می‌بیند — **و این تعریفِ کاملِ «تحویل داده شد» است.**

> ✅ **چک کن:** به سطرِ `evaluate.py` نگاه کن: **دقت و خطِ پایه کنارِ هم چاپ می‌شوند.** این یک تزئین نیست. اگر `evaluate.py` فقط `0.8283` را چاپ می‌کرد، همان مدلِ شمارشیِ ۰٫۷۹۳۳ هم قابلِ قبول به نظر می‌رسید. **هر عددی که تنها چاپ شود، بی‌معناست؛ کنارش همیشه باید چیزی باشد که با آن مقایسه می‌شود.**

## ۵. هجده بند، سه قانون

هر بندِ این سیاهه از یکی از سه قانونِ ثابتِ داربست می‌آید.

</div>

```python
RULE = {
    "اگر خودکار نیست، انجام نمی‌شود": (1, 2, 3, 4, 9, 10, 12, 13),
    "هر چیزی که عوض می‌شود نسخه دارد": (0, 11, 15, 16, 17),
    "سامانهٔ پایش‌نشده خراب است و تو نمی‌دانی": (5, 6, 7, 8, 14),
}
BEFORE = dict(audit(typical))
AFTER = dict(after)
ITEMS = [item for item, _ in after]
print(f"{'قانونِ ثابتِ دوره':<44}{'پروژهٔ معمول':>16}{'پروژهٔ کامل':>16}")
for rule, idx in RULE.items():
    a = sum(BEFORE[ITEMS[i]] for i in idx)
    b = sum(AFTER[ITEMS[i]] for i in idx)
    print(f"{rule:<44}{f'{a}/{len(idx)}':>16}{f'{b}/{len(idx)}':>16}")
```

```text
قانونِ ثابتِ دوره                               پروژهٔ معمول     پروژهٔ کامل
اگر خودکار نیست، انجام نمی‌شود                           0/8             8/8
هر چیزی که عوض می‌شود نسخه دارد                          1/5             5/5
سامانهٔ پایش‌نشده خراب است و تو نمی‌دانی                 0/5             5/5
```

<div dir="rtl">

**صفر از هشت.** پروژهٔ معمول در قانونی صفر می‌گیرد که ارزان‌ترین است. نوشتنِ یک دروازهٔ خودکار چند ساعت کار دارد؛ **نداشتنش سال‌ها هزینه می‌دهد** — و ما هزینه‌اش را در همین ترم شمردیم: ۱ از ۶ دستورِ مستند، ۴۳۱ تیکت در هر دو طرفِ تقسیم، و مدلی که به‌اندازهٔ خطِ پایه خوب بود و کسی نفهمید.

## ۶. پروژهٔ خودت

**همین سیاهه را روی کارِ خودت ببر.** نه به‌عنوان یک تمرین — به‌عنوان تعریفِ تمام شدن.

</div>

| اگر این بند قرمز است | اولین کاری که باید بکنی |
|---|---|
| کد در نوت‌بوک است | یک ماژول بساز و نوت‌بوک را نازک کن (ترمِ ۱ فصلِ ۱) |
| تست ندارد | با دو تست شروع کن: نشتی و خطِ پایه (ترمِ ۱ فصلِ ۳) |
| دروازه ندارد | یک `ci.py` بیست‌خطی که کدِ خروج بدهد (فصلِ ۲) |
| دستورهای `README` اجرا نمی‌شوند | همان‌ها را در نسخهٔ تازه بزن و بشمار (فصلِ ۳) |
| تصمیم‌نامه ندارد | سه تصمیمِ بزرگت را بنویس، با نگهبان (فصلِ ۳) |
| ریسک نگهبان ندارد | فقط برای دو ریسکِ اولِ فهرست بساز (فصلِ ۴) |
| پیش‌بینی به مدلش برنمی‌گردد | چهار جدول و یک کلیدِ خارجی (فصلِ ۴) |
| طرحِ برگشت ندارد | سایه، بعد قناری، بعد دکمهٔ برگشت (ترمِ ۴) |

<div dir="rtl">

**و یک قاعده که از همهٔ جدول مهم‌تر است: از بندی شروع کن که ارزان‌ترین است و بیشترین ریسک را می‌بندد.** جدولِ ریسکِ فصلِ ۴ همین را می‌گوید، و برای اکثرِ پروژه‌ها جوابش یکی است: **تستِ نشتی و خطِ پایه، در یک بعدازظهر.**

> 📏 **اندازه بگیر:** **با چه چیزی مقایسه شد؟** دو پروژه با **یک سیاهه** و یک تعریف از هر بند — و بندها همه اجراشدنی‌اند، پس هیچ‌کدام به قضاوتِ من وابسته نیستند. **روی کدام داده؟** روی همان ۲۴۰۰ تیکتِ ترم، و هر بار در یک **نسخهٔ تازه** از پوشهٔ پروژه. **با چند `seed`؟** اینجا تصادفی نیست؛ ولی همان صداقتِ فصلِ ۴ لازم است: **هجده بند و وزنِ برابرشان، انتخابِ من است.** اگر بندی را حذف یا اضافه کنی، نمره‌ها عوض می‌شوند. **چیزی که عوض نمی‌شود، ۱ در برابرِ ۱۸ است** — و آن فاصله آن‌قدر بزرگ است که به وزن‌ها حساس نباشد.

> 🔧 **اگر کار نکرد:** اگر سیاهه روی پروژهٔ خودت با `FileNotFoundError` ایستاد، `run_readme` را نگاه کن: دستورها با `cwd` برابرِ نسخهٔ تازه اجرا می‌شوند، پس هر مسیرِ مطلقی در `README` تو همان‌جا می‌شکند — **و همان یک یافته است، نه یک باگ**. اگر `shutil.copytree` با `FileExistsError` ایستاد، پوشهٔ `fresh` از اجرای قبلی مانده. و اگر بندِ «یک پیش‌بینی به نسخهٔ مدلش برمی‌گردد» بی‌صدا `False` داد در حالی که `audit.db` وجود دارد، `JOIN` جوابِ خالی داده — یعنی جدول‌ها پر شده‌اند ولی به هم وصل نیستند، **که دقیقاً همان چیزی است که این بند برای گرفتنش نوشته شده.**

> 🤖 **از دستیارت بپرس:** «این هجده بند را ببین [فهرست را بده]. برای پروژهٔ من چه بندِ نوزدهمی لازم است که اینجا نیست؟» بعد این را بپرس: **«برای همان بند، یک بررسیِ اجراشدنی بنویس که کدِ خروج بدهد.»** — اگر نتوانست، آن بند هنوز به‌اندازهٔ کافی مشخص نشده.

## ۷. و آخر

**در ابتدای این دوره یک نوت‌بوک داشتی که کار می‌کرد.**

حالا چیزی داری که **کسِ دیگری می‌تواند اجرایش کند، و شش ماهِ دیگر هم کار می‌کند.** فاصلهٔ این دو، همان درّه‌ای بود که این دوره دربارهٔ آن نوشته شد.

**و بیشترِ آنچه در این شش ترم یاد گرفتی، ابزار نبود.** ابزارها عوض می‌شوند؛ هر کدام از سازوکارهایی که ساختی امروز یک ابزارِ آماده هم دارد، و فردا ابزارِ دیگری خواهد داشت. **چیزی که عوض نمی‌شود، سه جمله است:**

- **اگر خودکار نیست، انجام نمی‌شود.** نه چون آدم‌ها تنبل‌اند — چون کار زیاد است و آنچه یادآور ندارد، فراموش می‌شود.
- **هر چیزی که عوض می‌شود باید نسخه داشته باشد.** داده، کد، مدل، پیکربندی، و تصمیم. چیزی که نسخه ندارد، روزی که لازمش داشته باشی وجود ندارد.
- **سامانه‌ای که پایش نمی‌شود، خراب است و تو نمی‌دانی.** این بدبینی نیست؛ در پنج ترمِ گذشته هر بار که چیزی را برای اولین بار اندازه گرفتیم، چیزی پیدا شد.

**و یک جملهٔ چهارم که از ژرفا آمد و اینجا هم برقرار است: وقتی کار کرد، اول شک کن.** `F1` که به ۰٫۸۴۰ پرید نشتی بود. مدلی که آفلاین برنده بود، روی آینده بازنده شد. مدلی که دقتش هشت واحد بالاتر بود، هفته‌ای چهار و نیم پروندهٔ واقعی را از دست می‌داد. **هر بار، عددِ خوب علامتِ خطر بود.**

**چیزی که از اینجا به بعد می‌سازی، دیگر تمرین نیست — و کسی هم آن را برایت تصحیح نمی‌کند.** تنها چیزی که داری، همان سیاهه‌ای است که خودت می‌نویسی و خودت اجرایش می‌کنی.

## واژه‌های تازهٔ این فصل

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| definition of done | دفینیشن آف دان | فهرستِ روشنِ اینکه «تمام شد» یعنی چه |
| delivery checklist | دلیوری چک‌لیست | سیاهه‌ای که پیش از تحویل، خودش پروژه را می‌سنجد |
| handover | هندآور | تحویل دادنِ کار به کسی که آنجا نبوده |
| root cause | روت کاز | خرابیِ واحدی که چند علامتِ متفاوت از آن می‌آید |

<div dir="rtl">

## تمرین‌ها

قبل از تمرین، بدونِ نگاه به بالا جواب بده: چرا سه بندِ قرمز لزوماً سه مشکل نیستند؟

**تمرینِ اجباری:** سیاهه را روی **پروژهٔ خودت** اجرا کن — هر چیزی که کد دارد. **نمره‌ات را بنویس، و برای هر بندِ قرمز یک جمله: چرا هنوز قرمز است.** بعد **دو** بند را ببند، نه هجده‌تا، و دوباره اجرا کن. **و جوابِ اصلی را بنویس: کدام دو بند را انتخاب کردی و چرا آن دوتا؟** جوابت باید به سیاههٔ ریسکِ فصلِ ۴ وصل شود، نه به اینکه کدام آسان‌تر بود.

**تمرینِ ستاره‌دار ⭐ — و این پروژهٔ پایانیِ توست:** یک مسئلهٔ واقعیِ خودت را از صفر تا **۱۸ از ۱۸** ببر. داده‌اش را خودت پیدا کن، مدلش هرچه می‌خواهد باشد، ولی هر هجده بند باید **اجراشدنی** سبز شود. **بعد آن را به یک نفرِ دیگر بده و بخواه بدونِ هیچ کمکی فقط دستورهای `README` را بزند.** هر جا گیر کرد، یک بند دروغ گفته بود. **و سؤالِ آخر: اگر کسی سه ماهِ دیگر یک نسخهٔ تازه از مدلت بسازد، کدام‌یک از این هجده بند جلوی انتشارِ یک نسخهٔ بد را می‌گیرد؟** اگر جوابت کمتر از سه بند بود، سامانه‌ات هنوز به تو وابسته است، نه به خودش.

## در فصل بعد

**فصلِ بعدی وجود ندارد. داربست اینجا تمام می‌شود، و با آن این مسیر.**

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

**و یک جملهٔ آخر که این دوره حق ندارد نگوید: هیچ‌کدام از این هجده بند سامانه‌ات را مستقر نکرده است.** هر شش ترم داخلِ یک runtimeِ Colab اجرا شدند و با بستنِ صفحه پاک می‌شوند — ترمِ ۴ فصلِ ۹ بخشِ ۸ ستون‌به‌ستون گفت کدام قطعه شبیه‌سازی بود. **چیزی که یاد گرفتی تصمیم‌های مهندسی است؛ چیزی که هنوز نکرده‌ای رساندنِ آن‌ها به ماشینی است که با بستنِ مرورگر خاموش نمی‌شود.**

آن قدمِ آخر سه چیز می‌خواهد و هر سه بیرونِ این دوره‌اند: **جایی که فرآیندت همیشه روشن بماند**، **یک نام و یک اتصالِ رمزنگاری‌شده** تا کسی جز تو وسطِ راه ننشیند، و **مرزِ سرویس** — کلید، سهمیه و محدودیتِ نرخ — که ترمِ ۴ فصلِ ۳ ساختنش را نشان داد. **ترتیبش هم همین است:** اول `artifact` ترمِ ۴ را روی ماشینِ خودت اجرا کن و ببین چه چیزی می‌شکند، بعد ببرش روی ماشینی که همیشه روشن است، و **تنها بعد از آن** آدرسش را به کسی بده.

**آن روز است که می‌فهمی کدام یکی از این هجده بند را واقعاً لازم داشتی.**

</div>

---
Source: https://yaadestan.com/courses/darbast/lessons/t6/s07-capstone (یادستان, Yaadestan)
