# فصل ۰۹ — پروژه: یک مسیرِ دادهٔ بازتولیدپذیر

<div dir="rtl">

# فصل ۰۹ — پروژه: یک مسیرِ دادهٔ بازتولیدپذیر

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

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

و آزمونِ نهایی‌اش یک خط است: **کلِ مسیر را از صفر دوباره اجرا می‌کنیم و اثرِ انگشتِ جدولِ نهایی دقیقاً همان `ac361ab48b4f` درمی‌آید.**

![چند ایستگاهِ به‌هم‌پیوسته که در انتها یک مهرِ یکسان روی خروجی می‌زنند](/lesson-assets/t2-s09-project-pipeline/prompt/01-image-sealed-line.png)

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

- هر هشت تکهٔ ترم را در یک مسیرِ واحد سرِ هم کنی
- بازتولیدپذیری را **ثابت** کنی، نه ادعا
- سیاههٔ تحویل بنویسی که خودش خودش را می‌سنجد
- یک مسیرِ داده را طوری تحویل بدهی که کسی که آنجا نبوده بتواند اجرایش کند

## قبل از شروع

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

**اگر جایی گیر کردی:** مرحله و راه‌انداز از فصلِ ۱، اسکیما از فصلِ ۳، اثرِ انگشت و فهرست از فصلِ ۴، نرمال‌ساز از فصلِ ۶، تقسیمِ گروهی و فرانمونه از فصلِ ۷، و پاک‌سازی و نام‌مستعار از فصلِ ۸.

> 📓 **نوت‌بوک:** [نوت‌بوک این فصل را در Colab باز کن](/notebooks/darbast/term-2-data-as-infrastructure/session-09-project-pipeline.ipynb) — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

</div>

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

<div dir="rtl">

## ۱. راه‌انداز

اول همان راه‌اندازِ فصلِ ۱، با یک اضافه: **هر رکوردِ منشأ حالا اثرِ انگشتِ خروجی را هم نگه می‌دارد.** همین یک فیلد است که بازتولیدپذیری را قابلِ اثبات می‌کند.

</div>

```python
import csv
import hashlib
import inspect
import json
import re
import time

OUT = WORK / "pipeline"
OUT.mkdir(exist_ok=True)
STATE = OUT / "state.json"
LOG = OUT / "provenance.jsonl"
RAW = WORK / "raw" / "tickets.csv"


def read_csv(path):
    with open(path, encoding="utf-8") as fh:
        return list(csv.DictReader(fh))


def write_csv(path, rows):
    with open(path, "w", encoding="utf-8", newline="") as fh:
        w = csv.DictWriter(fh, fieldnames=list(rows[0]))
        w.writeheader()
        w.writerows(rows)


def fingerprint(rows):
    lines = sorted(repr([r[k] for k in sorted(rows[0])]) for r in rows)
    return hashlib.sha256("\n".join(lines).encode("utf-8")).hexdigest()[:12]


def file_hash(path):
    return hashlib.sha256(path.read_bytes()).hexdigest()[:12]


class Stage:
    def __init__(self, name, inputs, outputs, fn):
        self.name, self.inputs, self.outputs, self.fn = name, inputs, outputs, fn

    def key(self):
        parts = [file_hash(p) for p in self.inputs] + [inspect.getsource(self.fn)]
        return hashlib.sha256("|".join(parts).encode("utf-8")).hexdigest()[:12]


def order(stages):
    made_by = {o: s.name for s in stages for o in s.outputs}
    done, out, todo = set(), [], list(stages)
    while todo:
        ready = [s for s in todo
                 if all(i not in made_by or made_by[i] in done for i in s.inputs)]
        if not ready:
            raise ValueError("حلقه در وابستگی‌ها")
        ready.sort(key=lambda s: s.name)
        for s in ready:
            out.append(s)
            done.add(s.name)
            todo.remove(s)
    return out


def run(stages):
    state = json.loads(STATE.read_text(encoding="utf-8")) if STATE.exists() else {}
    ran, skipped = [], []
    for s in order(stages):
        if state.get(s.name) == s.key() and all(p.exists() for p in s.outputs):
            skipped.append(s.name)
            continue
        t0 = time.perf_counter()
        n_in, n_out = s.fn(s.inputs, s.outputs)
        rec = {"stage": s.name, "key": s.key(),
               "inputs": [p.name for p in s.inputs],
               "outputs": [p.name for p in s.outputs],
               "rows_in": n_in, "rows_out": n_out,
               "out_fingerprint": fingerprint(read_csv(s.outputs[0])),
               "seconds": round(time.perf_counter() - t0, 3)}
        with open(LOG, "a", encoding="utf-8") as fh:
            fh.write(json.dumps(rec, ensure_ascii=False) + "\n")
        state[s.name] = s.key()
        ran.append(s.name)
    STATE.write_text(json.dumps(state, ensure_ascii=False), encoding="utf-8")
    return ran, skipped


print("راه‌انداز آماده است.")
```

```text
راه‌انداز آماده است.
```

<div dir="rtl">

## ۲. قرارداد و ابزارها

</div>

```python
CHANNELS = ["تلفن", "ایمیل", "چت", "حضوری"]
CATEGORIES = ["پرداخت", "ارسال", "حساب کاربری", "اپلیکیشن"]
SCHEMA = {
    "ticket_id":        [("required", None, "error"), ("unique", None, "error")],
    "customer_id":      [("required", None, "error")],
    "created_at":       [("required", None, "error"),
                         ("between", ("2031-01-01", "2031-12-31"), "warn")],
    "channel":          [("allowed", CHANNELS, "warn")],
    "text":             [("required", None, "warn")],
    "category":         [("allowed", CATEGORIES, "error")],
    "escalated":        [("allowed", ["0", "1"], "error")],
    "rating":           [("range", (1, 5), "warn")],
    "handling_minutes": [("range", (0, 1440), "warn")],
}


def check_value(kind, arg, value):
    if kind == "required":
        return value.strip() != ""
    if value.strip() == "":
        return True
    if kind == "allowed":
        return value in arg
    if kind == "range":
        return value.lstrip("-").isdigit() and arg[0] <= int(value) <= arg[1]
    if kind == "between":
        return arg[0] <= value <= arg[1]
    raise ValueError("قاعدهٔ ناشناخته: " + kind)


def validate(rows, schema):
    missing = [c for c in schema if c not in rows[0]]
    if missing:
        raise ValueError("ستونِ اعلام‌شده در فایل نیست: " + ", ".join(missing))
    findings = []
    for column, checks in schema.items():
        for kind, arg, sev in checks:
            if kind == "unique":
                seen, bad = set(), []
                for r in rows:
                    if r[column] in seen:
                        bad.append(r[column])
                    seen.add(r[column])
            else:
                bad = [r[column] for r in rows if not check_value(kind, arg, r[column])]
            if bad:
                findings.append({"column": column, "rule": kind,
                                 "severity": sev, "count": len(bad)})
    return findings


ARABIC = {"ي": "ی", "ك": "ک", "ة": "ه", "أ": "ا", "إ": "ا", "ؤ": "و"}
DIGITS = str.maketrans("۰۱۲۳۴۵۶۷۸۹٠١٢٣٤٥٦٧٨٩", "01234567890123456789")
HARAKAT = re.compile("[ً-ْٰ]")
PREFIX = re.compile(r"(?<![؀-ۿ])(ن?می) +(?=[؀-ۿ])")
SUFFIX = re.compile(r"(?<=[؀-ۿ]) +(ها|های|هایی|تر|تری|ترین|ام|ات|اش)(?![؀-ۿ])")
PII = {
    "phone": re.compile(r"09[0-9]{9}"),
    "melli": re.compile(r"(?<![0-9])[0-9]{10}(?![0-9])"),
    "email": re.compile(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}"),
}
SALT = "darbast-t2-salt"


def normalize(t):
    for a, b in ARABIC.items():
        t = t.replace(a, b)
    t = HARAKAT.sub("", t.translate(DIGITS))
    t = " ".join(t.split())
    t = PREFIX.sub(r"\1‌", t)
    return SUFFIX.sub("‌" + r"\1", t)


def scrub(t):
    for kind, rx in PII.items():
        t = rx.sub(f"<{kind}>", t)
    return t


def pseudonym(v):
    return "id_" + hashlib.sha256((SALT + v).encode("utf-8")).hexdigest()[:10]


print("قاعده‌های اسکیما:", sum(len(v) for v in SCHEMA.values()),
      "· الگوهای دادهٔ حساس:", len(PII))
```

```text
قاعده‌های اسکیما: 11 · الگوهای دادهٔ حساس: 3
```

<div dir="rtl">

**به ترتیبِ `normalize` دقت کن: نرمال‌سازی قبل از `scrub` می‌آید.** فصلِ ۸ نشان داد که برعکسش بازیافتِ آشکارساز را از ۹۹٪ به ۵۱٪ می‌اندازد. **این یک جزئیاتِ پیاده‌سازی نیست؛ یک تصمیمِ امنیتی است که در ترتیبِ دو خط کد نشسته.**

## ۳. پنج مرحله

</div>

```python
REPORT = OUT / "quality.json"


def stage_ingest(inputs, outputs):
    rows, seen, out = read_csv(inputs[0]), set(), []
    for r in rows:
        key = tuple(r.values())
        if key not in seen:
            seen.add(key)
            out.append(r)
    write_csv(outputs[0], out)
    return len(rows), len(out)


def stage_validate(inputs, outputs):
    rows = read_csv(inputs[0])
    findings = validate(rows, SCHEMA)
    REPORT.write_text(json.dumps(findings, ensure_ascii=False, indent=1), encoding="utf-8")
    fatal = [f for f in findings if f["severity"] == "error"]
    if fatal:
        raise ValueError("تخلفِ بازدارنده: " + str(fatal))
    keep = [r for r in rows
            if r["text"].strip()
            and 0 <= int(r["handling_minutes"]) <= 1440
            and "2031-01-01" <= r["created_at"] <= "2031-12-31"]
    for r in keep:
        if r["rating"] and not (1 <= int(r["rating"]) <= 5):
            r["rating"] = ""
    write_csv(outputs[0], keep)
    return len(rows), len(keep)


def stage_text(inputs, outputs):
    rows = read_csv(inputs[0])
    for r in rows:
        r["text"] = scrub(normalize(r["text"]))
    write_csv(outputs[0], rows)
    return len(rows), len(rows)


def stage_minimize(inputs, outputs):
    rows = read_csv(inputs[0])
    out = [{"ticket_id": r["ticket_id"], "customer_ref": pseudonym(r["customer_id"]),
            "created_at": r["created_at"], "channel": r["channel"],
            "text": r["text"], "category": r["category"],
            "escalated": r["escalated"], "rating": r["rating"],
            "handling_minutes": r["handling_minutes"]}
           for r in rows]
    write_csv(outputs[0], out)
    return len(rows), len(out)


def stage_features(inputs, outputs):
    rows = read_csv(inputs[0])
    out = [{"ticket_id": r["ticket_id"], "customer_ref": r["customer_ref"],
            "words": str(len(r["text"].split())),
            "has_pii_mark": str(int("<" in r["text"])),
            "channel": r["channel"], "category": r["category"],
            "escalated": r["escalated"]}
           for r in rows]
    write_csv(outputs[0], out)
    return len(rows), len(out)


P = OUT
PIPELINE = [
    Stage("ingest", [RAW], [P / "01-ingested.csv"], stage_ingest),
    Stage("validate", [P / "01-ingested.csv"], [P / "02-valid.csv"], stage_validate),
    Stage("text", [P / "02-valid.csv"], [P / "03-text.csv"], stage_text),
    Stage("minimize", [P / "03-text.csv"], [P / "04-minimal.csv"], stage_minimize),
    Stage("features", [P / "04-minimal.csv"], [P / "05-features.csv"], stage_features),
]
ran, skipped = run(PIPELINE)
print("اجرای اول — اجرا:", len(ran), "· رد:", len(skipped))
ran2, skipped2 = run(PIPELINE)
print("اجرای دوم — اجرا:", len(ran2), "· رد:", len(skipped2))
```

```text
اجرای اول — اجرا: 5 · رد: 0
اجرای دوم — اجرا: 0 · رد: 5
```

<div dir="rtl">

**`stage_validate` تنها مرحله‌ای است که می‌تواند مسیر را متوقف کند** — و فقط برای تخلفِ `error`. تخلفِ `warn` در `quality.json` ثبت می‌شود و مسیر ادامه می‌دهد؛ همان تفکیکی که فصلِ ۳ ساخت.

## ۴. داده در مسیر چه کشید

</div>

```python
last = {}
for line in LOG.read_text(encoding="utf-8").strip().split("\n"):
    r = json.loads(line)
    last[r["stage"]] = r
print(f"{'مرحله':<12}{'ورودی':>7}{'خروجی':>7}{'افت':>6}  اثرِ انگشتِ خروجی")
for s in order(PIPELINE):
    r = last[s.name]
    print(f"{s.name:<12}{r['rows_in']:>7}{r['rows_out']:>7}"
          f"{r['rows_in'] - r['rows_out']:>6}  {r['out_fingerprint']}")
```

```text
مرحله         ورودی  خروجی   افت  اثرِ انگشتِ خروجی
ingest         1240   1200    40  e9410946a0dd
validate       1200   1160    40  48ad1bb28c93
text           1160   1160     0  2668df5b6894
minimize       1160   1160     0  77812a7e98f4
features       1160   1160     0  ac361ab48b4f
```

<div dir="rtl">

**۱۲۴۰ ردیف وارد شد، ۱۱۶۰ بیرون آمد — و برای هر ردیفی که گم شد، یک مرحلهٔ مشخص مسئول است.**

و به سه ردیفِ آخر نگاه کن: **افتِ صفر، ولی اثرِ انگشت هر بار عوض شده.** یعنی این مرحله‌ها ردیف حذف نکردند ولی محتوا را تغییر دادند. **جدولی که فقط شمارِ ردیف را نشان بدهد، این را کاملاً پنهان می‌کند.**

## ۵. آزمونِ بازتولیدپذیری

</div>

```python
STATE.unlink()                       # فراموش کن چه چیزی تازه است
ran3, _ = run(PIPELINE)
lines = LOG.read_text(encoding="utf-8").strip().split(chr(10))
again = json.loads(lines[-1])["out_fingerprint"]
print("اجرای کاملِ دوباره:", len(ran3), "مرحله")
print("اثرِ انگشتِ نهایی — بارِ اول:", last["features"]["out_fingerprint"],
      "· بارِ دوم:", again)
print("یکی هستند؟", again == last["features"]["out_fingerprint"])
```

```text
اجرای کاملِ دوباره: 5 مرحله
اثرِ انگشتِ نهایی — بارِ اول: ac361ab48b4f · بارِ دوم: ac361ab48b4f
یکی هستند؟ True
```

<div dir="rtl">

**این خط، آزمونِ صداقتِ کلِ مسیر است.**

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

> ✅ **چک کن:** اگر این عدد در اجرای دوم فرق کرد، **دنبالِ سه چیز بگرد**: ساعتِ واقعی که جایی وارد داده شده، یک `set` یا `dict` که ترتیبش را به داخلِ خروجی برده، و هر تصادفی که `seed` ندارد. **هر سه‌شان همیشه همین یک نشانه را می‌دهند.**

## ۶. گزارشِ کیفیت

</div>

```python
findings = json.loads(REPORT.read_text(encoding="utf-8"))
print("گزارشِ کیفیت — قاعده‌های شکسته:", len(findings))
for f in sorted(findings, key=lambda f: -f["count"]):
    print(f"   {f['column']:<18}{f['rule']:<9}{f['severity']:<7}{f['count']:>5}")
after = validate(read_csv(P / "05-features.csv"),
                 {k: v for k, v in SCHEMA.items() if k in ("ticket_id", "category",
                                                           "escalated", "channel")})
print("تخلف در چهار ستونِ کلیدیِ جدولِ نهایی:", len(after))
```

```text
گزارشِ کیفیت — قاعده‌های شکسته: 4
   rating            range    warn     235
   handling_minutes  range    warn      34
   text              required warn       5
   created_at        between  warn       3
تخلف در چهار ستونِ کلیدیِ جدولِ نهایی: 0
```

<div dir="rtl">

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

## ۷. فهرستِ نسخه، و مدلی که به آن وصل است

</div>

```python
import sqlite3

DB = OUT / "registry.db"
if DB.exists():
    DB.unlink()
db = sqlite3.connect(DB)
db.executescript("""
CREATE TABLE versions (fingerprint TEXT PRIMARY KEY, stage TEXT NOT NULL,
                       n_rows INTEGER NOT NULL, parent TEXT);
CREATE TABLE models (name TEXT PRIMARY KEY, data_fp TEXT NOT NULL,
                     f1 REAL NOT NULL, f1_low REAL NOT NULL, f1_high REAL NOT NULL);
""")
parent = None
for s in order(PIPELINE):
    r = last[s.name]
    db.execute("INSERT INTO versions VALUES (?,?,?,?)",
               (r["out_fingerprint"], s.name, r["rows_out"], parent))
    parent = r["out_fingerprint"]
db.commit()
final_fp = parent
print("نسخه‌های ثبت‌شده:", db.execute("SELECT count(*) FROM versions").fetchone()[0])
print("اثرِ انگشتِ جدولِ نهایی:", final_fp)
```

```text
نسخه‌های ثبت‌شده: 5
اثرِ انگشتِ جدولِ نهایی: ac361ab48b4f
```

<div dir="rtl">

</div>

```python
import random

from sklearn.feature_extraction.text import CountVectorizer
from sklearn.linear_model import LogisticRegression
from sklearn.metrics import f1_score

final = read_csv(P / "04-minimal.csv")
X = [r["text"] for r in final]
Y = [int(r["escalated"]) for r in final]
G = [r["customer_ref"] for r in final]


def group_split(groups, seed, frac=0.25):
    names = sorted(set(groups))
    random.Random(seed).shuffle(names)
    held, held_rows, target = set(), 0, frac * len(groups)
    for g in names:
        if held_rows >= target:
            break
        held.add(g)
        held_rows += sum(1 for x in groups if x == g)
    te = [i for i, g in enumerate(groups) if g in held]
    tr = [i for i, g in enumerate(groups) if g not in held]
    return tr, te


def oversample(xs, ys, seed):
    rng = random.Random(seed)
    minor = [i for i, y in enumerate(ys) if y == 1]
    major = [i for i, y in enumerate(ys) if y == 0]
    idx = list(range(len(ys))) + [rng.choice(minor) for _ in range(len(major) - len(minor))]
    rng.shuffle(idx)
    return [xs[i] for i in idx], [ys[i] for i in idx]


def score(seed):
    tr, te = group_split(G, seed)
    xtr, ytr = oversample([X[i] for i in tr], [Y[i] for i in tr], seed)
    vec = CountVectorizer(min_df=1)
    model = LogisticRegression(max_iter=2000, random_state=seed).fit(vec.fit_transform(xtr), ytr)
    pred = model.predict(vec.transform([X[i] for i in te]))
    return f1_score([Y[i] for i in te], pred, zero_division=0)


f1s = [score(s) for s in range(5)]
db.execute("INSERT INTO models VALUES (?,?,?,?,?)",
           ("escalation-v1", final_fp, sum(f1s) / 5, min(f1s), max(f1s)))
db.commit()
name, fp, m, lo, hi = db.execute("SELECT * FROM models").fetchone()
print(f"{name}: F1 {m:.4f}  [{lo:.3f}–{hi:.3f}]  · روی دادهٔ {fp}")
print("خطِ پایهٔ «همیشه نه» — دقت:", round(1 - sum(Y) / len(Y), 4))
```

```text
escalation-v1: F1 0.2988  [0.208–0.361]  · روی دادهٔ ac361ab48b4f
خطِ پایهٔ «همیشه نه» — دقت: 0.9078
```

<div dir="rtl">

**`F1` برابرِ ۰٫۲۹۹ با دامنهٔ ۰٫۲۰۸ تا ۰٫۳۶۱ — و این عددِ نهاییِ ماست.**

از ۰٫۸۴۰ فصلِ ۷ خیلی کمتر است، و **این نشانهٔ سلامتِ کار است، نه شکستش.** آن ۰٫۸۴۰ حفظ کردنِ کپی‌ها بود؛ این عدد پیش‌بینی برای **مشتریِ ندیده** است، روی داده‌ای که شمارهٔ تلفن و کدِ ملی‌اش هم پاک شده.

**و کمی با فصلِ ۸ فرق دارد (۰٫۲۶۵)**، چون آنجا روی ۱۱۹۵ ردیف بودیم و اینجا ۳۵ ردیفِ نامعتبر هم کنار رفته‌اند، پس تقسیمِ گروهی جورِ دیگری افتاده است. نیم‌فاصله علتش نیست: روی همین ۱۱۶۰ ردیف، بردنِ نیم‌فاصله به فاصله عدد را دقیقاً ۰٫۲۹۸۸ نگه می‌دارد. **همین تغییرِ کوچک در یک مرحله، عدد را جابه‌جا می‌کند** — و دقیقاً به همین دلیل است که ستونِ `داده` در جدولِ `models` وجود دارد.

## ۸. سیاههٔ تحویل

آخرین تکه: **مسیری که خودش می‌گوید سالم است یا نه.**

</div>

```python
def checklist():
    checks = []
    checks.append(("هر مرحله سیاههٔ منشأ دارد",
                   set(last) == {s.name for s in PIPELINE}))
    checks.append(("اجرای دوباره هیچ مرحله‌ای اجرا نکرد", len(ran2) == 0))
    checks.append(("جدولِ نهایی از اسکیما رد می‌شود", len(after) == 0))
    text_now = " ".join(r["text"] for r in read_csv(P / "03-text.csv"))
    checks.append(("هیچ الگوی دادهٔ حساسی در متن نمانده",
                   not any(rx.search(text_now) for rx in PII.values())))
    checks.append(("شناسهٔ خامِ مشتری در خروجی نیست",
                   "customer_id" not in read_csv(P / "04-minimal.csv")[0]))
    tr, te = group_split(G, 0)
    checks.append(("آموزش و آزمون هیچ مشتریِ مشترکی ندارند",
                   not ({G[i] for i in tr} & {G[i] for i in te})))
    checks.append(("مدل به یک نسخهٔ مشخص از داده وصل است",
                   db.execute("SELECT count(*) FROM models m JOIN versions v"
                              " ON m.data_fp = v.fingerprint").fetchone()[0] == 1))
    for label, ok in checks:
        print(("  [درست] " if ok else "  [غلط ] ") + label)
    return all(ok for _l, ok in checks)


print("سیاههٔ تحویل کامل است:", checklist())
```

```text
  [درست] هر مرحله سیاههٔ منشأ دارد
  [درست] اجرای دوباره هیچ مرحله‌ای اجرا نکرد
  [درست] جدولِ نهایی از اسکیما رد می‌شود
  [درست] هیچ الگوی دادهٔ حساسی در متن نمانده
  [درست] شناسهٔ خامِ مشتری در خروجی نیست
  [درست] آموزش و آزمون هیچ مشتریِ مشترکی ندارند
  [درست] مدل به یک نسخهٔ مشخص از داده وصل است
سیاههٔ تحویل کامل است: True
```

<div dir="rtl">

**هفت ادعا، هفت‌تا اجراشدنی.**

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

**و دقت کن که هر بند مستقیماً از یک فصل آمده** — بندِ چهارم فصلِ ۸، بندِ ششم فصلِ ۷، بندِ هفتم فصلِ ۴. **یک ترمِ کامل، در هفت بررسی.**

> 🔧 **اگر کار نکرد:** اگر بندِ دوم `[غلط]` شد، یعنی چیزی در مسیر هر بار عوض می‌شود؛ سراغِ همان سه مظنونِ بخشِ ۵ برو. اگر بندِ چهارم `[غلط]` شد، احتمالاً در `stage_text` ترتیبِ `scrub` و `normalize` را جابه‌جا کرده‌ای — همان دامِ بخشِ ۲.

> 📏 **اندازه بگیر:** **با چه چیزی مقایسه شد؟** با خطِ پایهٔ «همیشه نه»، و با عددهای فصلِ ۷ و ۸ که همه‌شان روی همان پیکره گرفته شده‌اند. **روی کدام داده؟** روی جدولی با اثرِ انگشتِ `ac361ab48b4f` — و همین است که این عدد را ماه‌ها بعد هم قابلِ بازتولید می‌کند. **با چند `seed`؟** پنج‌تا، با دامنهٔ گزارش‌شده.

> 🤖 **از دستیارت بپرس:** «برای مسیرِ داده‌ای که یک `csv` را به جدولِ ویژگی تبدیل می‌کند، چه تست‌هایی باید نوشت؟» بعد این را هم بپرس: **«کدام‌هایشان باید در هر اجرا اجرا شوند و کدام فقط قبل از انتشار؟»** — و جوابش را با سیاههٔ بالا مقایسه کن: چه چیزی را جا انداخته‌ایم؟

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

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| delivery checklist | دلیوری چک‌لیست | فهرستِ ادعاهایی که خودشان اجرا و سنجیده می‌شوند |
| reproducibility test | ریپروداسیبیلیتی تست | مقایسهٔ اثرِ انگشتِ خروجی در دو اجرای مستقل |
| end-to-end pipeline | اند-تو-اند پایپ‌لاین | مسیرِ کامل از فایلِ خام تا جدولِ ویژگی |

<div dir="rtl">

## تمرین‌ها

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

**تمرینِ اجباری:** یک مرحلهٔ ششم به اسمِ `report` اضافه کن که از `05-features.csv` یک خلاصهٔ `json` بسازد: شمارِ تیکت به تفکیکِ `category`، نرخِ تشدید در هر `channel`، و میانگینِ `words`. بعد آن را به سیاههٔ تحویل وصل کن با یک بندِ تازه: **«خلاصه با جدولِ نهایی هم‌خوان است»** — یعنی جمعِ شمارش‌های خلاصه باید با شمارِ ردیف‌های جدول برابر باشد. **بعد عمداً خرابش کن** (مثلاً یک فیلتر در `report` بگذار) و ببین سیاهه قرمز می‌شود.

**تمرینِ ستاره‌دار ⭐:** مسیر را برای کسی که آنجا نبوده تحویل بده: یک `README` بنویس که **فقط** با اجرای دستورهایش، یک نفرِ دیگر بتواند به همان اثرِ انگشتِ `ac361ab48b4f` برسد. بعد سخت‌ترین قسمتش: **از یک نفرِ دیگر بخواه واقعاً امتحانش کند** و هر جای گیرکردنش را یادداشت کن. **چند قدم را فرض کرده بودی که او می‌داند؟** جوابت به این می‌رسد که «مستند» و «مستندی که کار می‌کند» دو چیزند — و ترمِ ۶ کاملاً دربارهٔ همین است.

## در فصل بعد

مسیرِ داده‌ات بازتولیدپذیر است، ولی هنوز فقط **یک** بار اجرا شده. **ترمِ بعد از این می‌پرسد: وقتی بیست آزمایشِ متفاوت روی همین داده زدی، چطور می‌فهمی کدام بهتر بود؟** ردیابِ آزمایش را از صفر می‌سازیم، محیط را ثبت می‌کنیم، و نشان می‌دهیم **کجا قطعیت اصلاً ممکن نیست** — و آنجا چه باید کرد.

</div>

---
Source: https://yaadestan.com/courses/darbast/lessons/t2/s09-project-pipeline (یادستان, Yaadestan)
