Амалиётҳо ва → Ҳуҷҷатҳои идоракунии амалиёт ҳамчун Кодекс

Ҳуҷҷатҳои муомилот ҳамчун рамз

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 ё submodule мебошад, то гурӯҳҳои гуногун мустақилона мундариҷаро идора кунанд.

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) Равандҳои GIT ва тағирот

Дархости Pull = Тағироти ҳуҷҷатгузории RFC.
Шарҳ: Соҳиби домейн ва роҳбари Ops бояд тасдиқ кунанд.
Санҷиши CI: санҷиши сохтор, майдонҳои ҳатмӣ, linter Markdown/YAML.
Нашри худкор: баъд аз якҷояшавӣ - тавлиди HTML/wiki/dashboard.
Рӯйхати тағирот: таърихи худкори тағирот бо сана ва муаллифон.
Ёдраскуниҳои ҳушдор: таҷдиди ҳуҷҷат ҳар рӯз N (аз ҷониби SLA).

7) Ҳамгироии CI/CD

Санҷишҳои Lint: Синтаксиси Markdown, дурустии YAML, майдонҳои соҳиб/версия.
Санҷиши пайванд: санҷиши URL ва пайвандҳои дохилӣ.
Сохтани ҳуҷҷатҳо: табдил ба HTML/Confluence/portal.
Таҳлили Diff: пас аз нашри охирини ҳуҷҷатҳо чӣ тағйир ёфт.
Auto-sync: навсозии пайвандҳо дар панели панели Grafana, Ops UI, Slack.
Ботҳои баррасии: маслиҳатҳо барои қисматҳои кӯҳна ё соҳибони гумшуда.

8) Ҳамгироӣ бо воситаҳои амалиётӣ

Графана/Кибана: эзоҳҳо ва пайвандҳо ба дафтарчаи мувофиқ бевосита аз панел.
Менеҷери ҳодисаҳо: тугмаи "Runbook Open" ҳангоми сохтани чипта.
Портали занг: додани китобҳои ҷории SOP ва дафтарҳо аз рӯи категорияи ҳодисаҳо.
Ёрдамчиёни AI: ҷустуҷӯи анбор, насли TL; Маслиҳатҳои DR ва амал.
Панелҳои BCP - Ҳангоми фаъол кардани скрипт ба таври худкор дастурҳои DR-ро бор мекунад.

9) Идоракунии даврии ҳуҷҷатҳо

10) Автоматизатсия ва ҳамоҳангсозӣ

Ҳуҷҷатҳо бот: тафтиш мекунад, ки кадом ҳуҷҷатҳо кӯҳна шудаанд.
Нишони версия: '! [баррасии охирин: 2025-05] 'ҳуқуқ дар ҳадди аққал.
Дарёфткунандаи китоб: бо ҳушдор ҳуҷҷати дилхоҳро бо барчасп мекушояд.
Шаблонҳо-генераторҳо: SOP-ҳои навро аз рӯи қолаб эҷод мекунанд ('нав-sop "Deposment" -ро созед).
Аудит-синхронизатсия: версияи SOP-ро бо барориши система ва вогузории ID пайваст мекунад.

11) Амният ва махфият

RBAC дар як анбор: танҳо соҳибони домейн метавонанд таҳрир кунанд.
Асрҳо ва PII: Дар ҳуҷҷатҳои кушода нигоҳ дошта намешавад; танҳо пайвандҳо ба таҳхонаҳои муҳофизатшаванда.
Аудит: сабти ҳама дигаргуниҳо, баррасиҳо ва нашрияҳо.
Сиёсати навсозӣ: Шарҳи SOP-ҳо ҳар 6 моҳ.
Нусхабардорӣ: аксҳои анбори репозиторӣ ва кэшҳои порталӣ дар минтақаи DR.

12) Нишондиҳандаҳои камолот

13) Анти-намунаҳо

Ҳуҷҷатгузорӣ дар Google Docs бидуни версия ва соҳибон нигоҳ дошта мешавад.
Runbook пас аз интишор нав карда намешавад.
SOP ба фармонҳо/абзорҳои меросӣ дахл дорад.
Тасдиқи CI нест: Маркет бо хатогиҳо ва пайвандҳои шикаста.
Дастурҳои якхеларо дар ҷойҳои гуногун нусхабардорӣ кунед.
Набудани соҳибон ва раванди бознигарӣ.

14) Рӯйхати назорати амалисозӣ

• Муайян кардани соҳибони домейнҳо ва соҳибони ҳуҷҷатҳо.
• Эҷоди анбори анбори Git 'ops-docs/' ва қолабҳои SOP/runbook/playbook.
• Танзими санҷишҳо ва линтерҳо (Markdown/YAML).
• Ба таври худкор нашр кунед ба портал ё Wiki.
• Ҳамгироӣ бо Grafana/Менеҷери ҳодисаҳо.
• Иловаи Ops bot барои ёдраскуниҳо ва нусхаҳои SLA.
• Фармонҳои ҷараёни кории docs-as-code.

15) 30/60/90 - нақшаи амалисозӣ

• Сохтани сохтори анборҳо, қолибҳо, линтер CI ва раванди баррасии PR.
• SOP-ҳои калидӣ ва 5-10 китобҳои интиқодӣ интиқол диҳед.
• Сохтани худкор дар портал.

• Амалисозии ҳамгироӣ бо Менеҷери Ҳодисаҳо ва Графана.
• Ops botро барои аудит ва ҳисобот пайваст кунед.
• Қолаби постмортемаро навсозӣ кунед ва ба ҳодисаи панели панел пайваст кунед.

• Фарогирии пурраи SOP/runbook (≥ 90%).
• KPI-ро ворид кунед: Фарогирӣ, Шарҳи SLA, Истифода.
• Ретро дар бораи роҳат ва сифати раванди "docs-as-code".

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) Ҳамгироӣ бо дигар равандҳо

Таҳлили амалиётӣ: Ҳисоботҳои аудити фарогирӣ ва SLA.
Тренинги оператор: омӯзиш дар асоси китобҳои воқеӣ.
Постмортемҳо: воридкунии худкори пайвандҳо ба SOP ва дафтарчаи бозӣ.
Этикаи идоракунӣ: шаффофияти тағирот ва муаллифӣ.
Ёрдамчиёни AI: ҷустуҷӯи контекст ва TL; DR аз репозитория.

18) FAQ

Савол: Чаро Git, агар омезиш вуҷуд дошта бошад?
A: Git версияҳо, барраси, автоматизатсия ва такрористеҳсолкуниро медиҳад. Омезиш метавонад намоиши ниҳоӣ бошад, аммо манбаи ҳақиқат нест.

Савол: Чӣ гуна бояд аз дастурҳои кӯҳна канорагирӣ кард?
A: SLA барои таҷдиди назар (180 рӯз) + Ботҳои ёдраскунӣ + нишони автоматии чеки охирин.

Савол: Оё CI метавонад ба ҳуҷҷатгузорӣ пайваст карда шавад?
A: Бале. Синтаксис, майдонҳои зарурӣ ва истинодҳои шикаста ҳамчун лӯлаи стандартӣ, ки ба санҷишҳои код монанданд, тафтиш карда мешаванд.