عملیات و → مستندات مدیریت عملیات به عنوان کد

مستندات تراکنش به عنوان کد

1) ماهیت رویکرد

مستندسازی به عنوان کد عملی است که در آن دانش عملیاتی، دستورالعمل ها و فرایندها به همان روش کد ذخیره، ویرایش و تأیید می شوند: از طریق Git، pull-requests، بازبینی و اعتبارسنجی CI.
در یک حلقه عملیاتی، این پایه ای برای قابلیت اطمینان، شفافیت و سازگاری فرمان است.

• یک سیستم دانش زنده، تجدید پذیر و نسخه سازی شده ایجاد کنید، جایی که هر دستورالعمل مصنوع زیرساخت است و نه یک PDF قدیمی.

2) چرا شما به آن نیاز دارید

شفافیت: شما می توانید ببینید که چه کسی، چه زمانی و چرا روش را تغییر داده است.
سازگاری: همه تیم ها بر روی نسخه های فعلی کار می کنند.
ادغام با CI/CD: اعتبار خودکار دستورالعمل ها.
تکرارپذیری - زیرساخت ها و مستندات هماهنگ می شوند.
امنیت: کنترل دسترسی و حسابرسی از طریق Git.
شتاب Onboarding: اپراتورهای جدید سناریوهای دقیق مربوط به کد را مشاهده می کنند.

3) امکانات اصلی

4) معماری مخزن

ops-docs/
├── README.md        # описание структуры
├── standards/
│  ├── sop-deploy.md
│  ├── sop-oncall.md
│  └── sop-release.md
├── runbooks/
│  ├── payments-latency.md
│  ├── games-cache.md
│  └── kyc-verification.md
├── playbooks/
│  ├── dr-failover.yaml
│  ├── psp-switch.yaml
│  └── safe-mode.yaml
├── postmortems/
│  └── 2025-03-17-bets-lag.md
├── policies/
│  ├── alerting.yaml
│  ├── communication.yaml
│  └── security.yaml
└── templates/
├── postmortem-template.md
├── sop-template.md
└── playbook-template.yaml

نکته: هر پوشه دارای مخزن یا زیر مجموعه Git خاص خود است تا تیم های مختلف بتوانند محتوا را به طور مستقل مدیریت کنند.

5) قالب و استانداردها

yaml id: sop-deploy owner: platform-team version: 3.2 last_review: 2025-10-15 tags: [deployment, ci-cd, rollback]
sla: review-180d

Цель
Контекст
Последовательность шагов
Проверка результата
Риски и откат
Контакты и каналы

yaml name: failover-psp triggers:
- alert: PSP downtime steps:
- action: check quota PSP-X
- action: switch PSP-Y
- action: verify payments latency < 200ms rollback:
- action: revert PSP-X

6) GitOps و تغییر فرایندها

Pull Request = تغییرات مستندات RFC

بررسی: صاحب دامنه و رئیس Ops باید تأیید کنند.
اعتبار سنجی CI: بررسی ساختار، زمینه های اجباری، Markdown/YAML linter.
انتشار خودکار: پس از ادغام - تولید HTML/ویکی/داشبورد.
ورود به سیستم تغییر: خودکار تاریخ تغییرات با تاریخ و نویسندگان.
یادآوری هشدار: بازبینی سند هر N روز (توسط SLA).

7) ادغام CI/CD

بررسی Lint: نحو Markdown، اعتبار YAML، فیلدهای مالک/نسخه.
بررسی لینک: بررسی URL ها و لینک های داخلی.
Docs-build: تبدیل به HTML/Confluence/portal.
تجزیه و تحلیل تفاوت: چه چیزی از آخرین انتشار اسناد تغییر کرده است.
خودکار همگام سازی: به روز رسانی لینک ها در داشبورد Grafana، UI Ops، Slack.
بررسی رباتها: راهنمایی برای بخش های قدیمی و یا از دست رفته صاحبان.

8) ادغام با ابزارهای عملیاتی

Grafana/Kibana: حاشیه نویسی و لینک به runbook مربوطه به طور مستقیم از پانل.
مدیر رویداد: هنگام ایجاد یک بلیط، دکمه «Runbook Open» را فشار دهید.
پورتال در تماس: صدور SOP ها و playbooks فعلی بر اساس طبقه بندی حادثه.

دستیاران AI: جستجوی مخزن، تولید TL ؛ DR و راهنمایی های عملی

پانل های BCP - هنگامی که یک اسکریپت فعال می شود، به طور خودکار دستورالعمل های DR را بارگذاری می کند.

9) مدیریت چرخه عمر سند

10) اتوماسیون و هماهنگ سازی

ربات Docs: بررسی میکند که کدام اسناد قدیمی هستند.
نسخه نشان: '! [آخرین بررسی: 2025-05] "درست در کلاه.
Runbook-finder: با هشدار سند مورد نظر را با برچسب باز می کند.
Templates-generator: SOP های جدید را با قالب ایجاد می کند ("ایجاد جدید sop" استقرار ").
Audit-sync: نسخه SOP را با انتشار سیستم و commit-ID مرتبط می کند.

11) امنیت و حریم خصوصی

RBAC در هر مخزن: فقط صاحبان دامنه می توانند ویرایش کنند.
اسرار و PII: نمی تواند در اسناد باز نگه داشته شود ؛ فقط به طاقهای محافظت شده متصل است.
حسابرسی: ورود به سیستم از تمام تغییرات، بررسی ها و نشریات.
سیاست به روز رسانی: بررسی SOP ها هر 6 ماه.
پشتیبان گیری: تصاویر فوری مخزن به طور منظم و کش پورتال در منطقه DR.

12) معیارهای بلوغ

13) ضد الگوهای

مستندات در Google Docs بدون نسخه و مالک ذخیره می شود.
Runbook پس از انتشار به روز نمی شود.
SOP به دستورات/ابزارهای میراث اشاره دارد.
بدون اعتبار CI: نشانه گذاری با خطاها و لینک های شکسته.
دستورالعمل های مشابه را در مکان های مختلف تکرار کنید.

عدم وجود مالک و روند بررسی

14) چک لیست پیاده سازی

• شناسایی صاحبان دامنه و صاحبان سند.
• ایجاد مخزن گیت 'ops-docs/' و SOP/runbook/playbook templates.
• پیکربندی چک CI و linters (Markdown/YAML).
• پیکربندی خودکار انتشار به پورتال یا ویکی.
• ادغام با گرافانا/مدیر حادثه.
• اضافه کردن یک ربات Ops برای یادآوری و تجدید نظر SLA.
• آموزش دستورات گردش کار docs-as-code.

15) 30/60/90 - برنامه اجرا

• ساختار مخزن، قالب ها، فرآیند بررسی CI linter و PR را ایجاد کنید.
• مهاجرت SOP های کلیدی و 5-10 runbooks بحرانی.
• تنظیم خودکار ساخت در پورتال.

• پیاده سازی ادغام با مدیر حادثه و Grafana.
• اتصال Ops ربات برای ممیزی و گزارش.
• قالب پس از مرگ را به روز کنید و به حادثه داشبورد پیوند دهید.

• پوشش کامل SOP/runbook (≥90٪).
• KPI را وارد کنید: پوشش، بررسی SLA، استفاده.
• Retro در راحتی و کیفیت فرآیند «docs-as-code».

16) نمونه ای از قالب SOP (نشانه گذاری)

SOP: Deployment через ArgoCD id: sop-deploy owner: platform-team last_review: 2025-10-15 tags: [deployment, rollback, argo]

Цель
Обеспечить безопасное и управляемое развертывание сервисов через ArgoCD.

Контекст
Используется для всех микросервисов с шаблоном Helm v2+.
Требует активного GitOps-контура и включенных health-checks.

Последовательность шагов
1. Проверить статус `argocd app list`
2. Выполнить `argocd app sync payments-api`
3. Убедиться, что `status: Healthy`
4. В случае проблем — `argocd app rollback payments-api --to-rev <rev>`

Проверка результата
SLO API доступность ≥ 99.95%, алертов нет.

Риски и откат
- Ошибка синхронизации — rollback.
- При повторных ошибках — эскалация Head of Ops.

Контакты
@platform-team / #ops-deploy

17) ادغام با فرآیندهای دیگر

تجزیه و تحلیل عملیاتی: گزارش های حسابرسی پوشش و SLA.
آموزش اپراتور: آموزش بر اساس runbooks واقعی است.
Postmortems: درج خودکار پیوندها به SOP و playbook.

اخلاق حکومتی: شفافیت تغییر و نویسندگی

دستیاران AI: جستجوی زمینه و TL ؛ DR از مخزن.

18) سوالات متداول

س: چرا Git اگر تلاقی وجود دارد ؟

A: Git نسخه ها، بررسی، اتوماسیون و قابلیت تکرار را می دهد. تلاقی ممکن است ویترین نهایی باشد، اما منبع حقیقت نیست.

س: چگونه از دستورالعمل های قدیمی جلوگیری کنیم ؟

A: SLA برای تجدید نظر (180 روز) + عملیات یادآوری رباتها + نشان خودکار از آخرین چک.

س: آیا CI می تواند به اسناد متصل شود ؟

پاسخ: بله. نحو، فیلدهای مورد نیاز و مراجع شکسته به عنوان خط لوله استاندارد، شبیه به تست های کد بررسی می شوند.