العمليات ووثائق إدارة → للعمليات بوصفها مدونة

وثائق المعاملات كمدونة

1) جوهر النهج

الوثائق كمدونة هي ممارسة يتم فيها تخزين المعارف والتعليمات والعمليات التشغيلية وتحريرها والتحقق من صحتها بنفس طريقة الرمز: من خلال Git وطلبات السحب والاستعراض والتحقق من صحة CI.
في الحلقة التشغيلية، يشكل هذا الأساس للموثوقية والشفافية وتوافق القيادة.

• إنشاء نظام معرفي حي وقابل للتكرار ومتحرر، حيث تكون كل تعليمات قطعة أثرية للبنية التحتية، وليست PDF قديمة.

2) لماذا تحتاجها

الشفافية: يمكنك معرفة من ومتى ولماذا غيرت الإجراء.
الاتساق: تعمل جميع الفرق على الإصدارات الحالية.
التكامل مع CI/CD: التصديق التلقائي على التعليمات.
قابلية التكرار - البنية التحتية والوثائق متزامنة.
الأمن: مراقبة الدخول والتدقيق عبر Git.
التسارع على متن الطائرة: يرى المشغلون الجدد سيناريوهات دقيقة مرتبطة بالرمز.

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 وعمليات التغيير

طلب السحب = تغييرات وثائق RFC.
مراجعة: يجب أن يوافق مالك المجال ورئيس العمليات.
التحقق من صحة CI: فحص الهيكل، الحقول الإلزامية، خط Markdown/YAML.
النشر التلقائي: بعد الدمج - توليد HTML/wiki/لوحات القيادة.
سجل التغيير: التاريخ التلقائي للتغييرات مع التواريخ والمؤلفين.
التذكير بالتنبيه: تنقيح الوثائق كل يوم شمالي (بواسطة جيش تحرير السودان).

7) دمج CI/CD

فحص الوبر: بناء ماركداون، صلاحية YAML، حقول المالك/الإصدار.
التحقق من الرابط: التحقق من عناوين URL والروابط الداخلية.
بناء المستندات: التحويل إلى HTML/Confluence/portal.
تحليل Diff: ما الذي تغير منذ الإصدار الأخير للوثائق.
المزامنة التلقائية: تحديث الروابط في لوحات القيادة Grafana و Ops UI و Slack.
روبوتات المراجعة: نصائح للأقسام القديمة أو المالكين المفقودين.

8) التكامل مع الأدوات التشغيلية

Grafana/Kibana: شروح ووصلات لدليل التشغيل المقابل مباشرة من الفريق.
مدير الحادث: زر «Open Runbook» عند إنشاء تذكرة.
بوابة تحت الطلب: إصدار SOPs وكتب اللعب الحالية حسب فئة الحوادث.
مساعدو الذكاء الاصطناعي: البحث في المستودعات، توليد TL ؛ DR ونصائح العمل.
لوحات BCP - تقوم تلقائيًا بتحميل تعليمات DR عند تنشيط النص.

9) إدارة دورة حياة المستندات

10) الأتمتة والتزامن

روبوت المستندات: التحقق من المستندات القديمة.
شارة الإصدار: '! [آخر مراجعة: 2025-05] 'حق في الحد الأقصى.
مكتشف Runbook: بالتنبيه يفتح المستند المطلوب بالعلامة.
مولد القوالب: ينشئ SOPs جديدة بواسطة قالب ("make new-sop" Position ").
مزامنة التدقيق: يربط إصدار SOP بإصدار النظام ومعرف الالتزام.

11) الأمن والخصوصية

RBAC لكل مستودع: يمكن لمالكي النطاق فقط التعديل.
الأسرار و PII: لا يمكن الاحتفاظ بها في وثائق مفتوحة ؛ فقط الروابط إلى الأقبية المحمية.
مراجعة الحسابات: سجل بجميع التغييرات والاستعراضات والمنشورات.
تحديث السياسة: مراجعة SOPs كل 6 أشهر.
النسخ الاحتياطية: لقطات مستودع منتظمة ومخابئ البوابة في منطقة DR.

12) مقاييس النضج

13) الأنماط المضادة

يتم تخزين الوثائق في مستندات Google بدون إصدارات ومالكين.
لا يتم تحديث Runbook بعد الإصدارات.
يشير SOP إلى الأوامر/الأدوات القديمة.
لا يوجد التحقق من صحة CI: التخفيض بالأخطاء والروابط المكسورة.
تكرار نفس التعليمات في مواقع مختلفة.
نقص المالكين وعملية المراجعة.

14) قائمة التنفيذ المرجعية

• تحديد مالكي النطاقات وأصحاب المستندات.
• إنشاء مستودع Git 'ops-docs/' ونماذج SOP/runbook/playbook.
• ضبط CI checks and linters (Markdown/YAML).
• ضبط Auto-Publish to Portal or Wiki.
• الاندماج مع Grafana/مدير الحوادث.
• أضف روبوت عمليات للتذكيرات وتنقيحات جيش تحرير السودان.
• تدريب أوامر سير العمل بالوثائق كرمز.

15) 30/60/90 - خطة التنفيذ

• إنشاء هيكل مستودع، نماذج، بطانة CI وعملية استعراض العلاقات العامة.
• هاجر SOPs الرئيسية و 5-10 دفاتر تشغيل مهمة.
• إعداد بناء تلقائي في البوابة.

• تنفيذ عمليات التكامل مع مدير الحوادث و Grafana.
• قم بتوصيل روبوت العمليات لعمليات التدقيق والإبلاغ.
• قم بتحديث نموذج تشريح الجثة والربط بحادث لوحة القيادة.

• التغطية الكاملة لـ SOP/runbook (≥90٪).
• أدخل KPI: التغطية، مراجعة SLA، الاستخدام.
• Retro على راحة وجودة عملية «المستندات كرمز».

16) مثال على نموذج SOP (Markdown)

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) التكامل مع العمليات الأخرى

التحليلات التشغيلية: التغطية وتقارير مراجعة حسابات جيش تحرير السودان.
تدريب المشغلين: التدريب على أساس دفاتر التشغيل الحقيقية.
بعد الوفاة: الإدخال التلقائي للوصلات إلى SOP وكتاب اللعب.
أخلاقيات الحكم: شفافية التغيير والتأليف.
مساعدو الذكاء الاصطناعي: البحث عن السياق و TL ؛ DR من المستودع.

18) الأسئلة الشائعة

س: لماذا Git إذا كان هناك التقاء ؟

ج: تقدم Git إصدارات ومراجعة وأتمتة وقابلية للتكرار. قد يكون الالتقاء هو العرض النهائي، ولكن ليس مصدر الحقيقة.

س: كيف تتجنب التعليمات القديمة ؟

ج: SLA للمراجعة (180 يومًا) + روبوتات تذكير العمليات + الشارة التلقائية للفحص الأخير.

س: هل يمكن ربط CI بالوثائق ؟

ج: نعم. يتم فحص التركيب والحقول المطلوبة والمراجع المكسورة كخط أنابيب قياسي، على غرار اختبارات الكود.