MH BankStatement Docs

English

Русский
Bahasa Indonesia

English

Русский
Bahasa Indonesia

Appearance

Git / Plane Traceability (Direct Main Commits) ​

Process doc для AI-агентов и разработчиков MyHoreca Pay: как связывать изменения в Git с Plane issues при direct commits to main.

См. также: Plane Task Execution Rules, AI Agents Rules, корневой AGENTS.md.

Workflow decision ​

Для MVP выбран workflow direct commits to main:

  • изменения коммитятся напрямую в ветку main;
  • pull request не обязателен и не является обязательным gate перед merge;
  • traceability обеспечивается через Plane issue id в commit message и handoff в Plane после завершения задачи.

PR допустим по желанию команды для крупных или рискованных изменений, но не требуется процессом по умолчанию.

Commit message format ​

Каждый коммит, выполненный в рамках Plane-задачи, должен содержать id issue в начале subject line:

text
[MHPAY-123] Implement feature

Правила:

RuleDetail
Prefix[MHPAY-XXX] — id активной Plane issue
SubjectКраткое описание сути изменения на английском (как в истории репозитория)
BodyОпционально: детали, breaking changes, ссылки на ADR
One issue per commitПредпочтительно один issue id на коммит; при смешении — явно указать primary issue

Примеры:

text
[MHPAY-99] Document Git Plane direct-main traceability

[MHPAY-42] Fix counterparty matching for BCA CSV adapter

Issue id in code comments ​

Plane issue id не добавлять в комментарии к коду по умолчанию.

Допустимо только при долговременной архитектурной или операционной причине, например:

  • ссылка на ADR или известный tech debt, который переживёт закрытие issue;
  • временный workaround с явным сроком снятия (лучше — отдельная follow-up задача в Plane).

Обычная traceability: commit message + Plane comment + current-implementation-state.md.

Agent Definition of Done (before handoff) ​

Перед финальным handoff агент обязан проверить:

Scope and quality ​

  • [ ] Scope и Acceptance Criteria активной Plane-задачи выполнены
  • [ ] Diff минимален и не содержит unrelated-изменений
  • [ ] Нет secrets, tokens, credentials, raw bank files/lines, полных номеров счетов

Verification ​

  • [ ] Запущены targeted verification commands по затронутой области
  • [ ] В handoff указаны точные команды и фактический результат (pass / fail / not run + причина)
  • [ ] Не заявлено «тесты прошли», если команды не запускались

Tests (if affected area changed) ​

  • [ ] Unit/integration tests добавлены или обновлены для изменённого поведения
  • [ ] Существующие regression tests не удалены без причины

Documentation (if corresponding area touched) ​

  • [ ] docs/docs/ai-agents/current-implementation-state.md обновлён
  • [ ] docs/docs/backend/api.md — при изменении API
  • [ ] Permission matrix — при изменении RBAC/permissions
  • [ ] codegraph/manifest.yaml — при изменении architecture/API/routes/hooks/contracts boundaries
  • [ ] docs/docs/.vitepress/config.ts — при новой странице в sidebar
  • [ ] UI screenshots в docs/public/screenshots — при значимых UI-изменениях (Playwright)
  • [ ] ADR — при новом архитектурном решении

Git and Plane ​

  • [ ] Commit message содержит [MHPAY-XXX]
  • [ ] Plane issue: комментарий с кратким отчётом, verification summary и commit hash
  • [ ] Plane issue: state → Done (или явная причина, почему нет)
  • [ ] current-plane-task.md переключён на следующую задачу (если применимо)

Plane comment after completion ​

После завершения задачи добавьте комментарий в Plane issue:

text
## Summary
<1–3 предложения: что сделано>

## Changed files
<ключевые пути или «docs-only: …»>

## Verification
<команды и результаты>

## Commit
<full commit hash, например abc1234…>

Не включайте secrets, raw bank data, полные номера счетов.

Risk warning: direct-main workflow ​

Direct commits to main ускоряют MVP, но повышают риск попадания непроверенных или неконсистентных изменений в основную ветку.

Обязательные меры снижения риска:

  1. Targeted verification — узкий набор тестов/build по затронутой области перед коммитом
  2. Clean diff — только изменения в scope задачи; без drive-by refactor
  3. Docs and state update — current-implementation-state.md и релевантные docs синхронизированы с кодом
  4. No secrets / no raw bank data — в коммитах, логах, fixtures и Plane-комментариях
  5. Commit traceability — каждый task commit с [MHPAY-XXX] для аудита и bisect

При сомнении в impact — расширить verification или обсудить optional PR; mandatory PR gate не вводится без отдельного ADR/решения.