Add the course materials

Author: arttet

omp-docs/images/grpc.png

@@ -0,0 +1,92 @@
+# Ozon Marketplace Project
+
+![schema](images/schema.png)
+
+Дальше везде используются **placeholder**-ы:
+- `{domain}`,`{Domain}`
+- `{subdomain}`,`{Subdomain}`
+
+Например, для поддомена `package` из домена `logistic` значение **placeholder**-ов будет:
+- `{domain}`,`{Domain}` = `logistic`,`Logistic`
+- `{subdomain}`,`{Subdomain}` = `package`,`Package`
+- `{domain}`/`{subdomain}` = `logistic`/`package`
+---
+
+
+### Задание 1
+
+1. Сделать форк **ozonmp/omp-bot** репозитория в свой профиль
+2. Запросить у своего тьютора свой домен/поддомен: **{domain}/{subdomain}**
+3. Добавить в ветку `feature/task-1` своего форка поддержку следующих команд:
+```
+/help__{domain}__{subdomain} — print list of commands
+/get__{domain}__{subdomain} — get a entity
+/list__{domain}__{subdomain} — get a list of your entity (💎: with pagination via telegram keyboard)
+/delete__{domain}__{subdomain} — delete an existing entity
+
+/new__{domain}__{subdomain} — create a new entity // not implemented (💎: implement list fields via arguments)
+/edit__{domain}__{subdomain} — edit a entity      // not implemented
+```
+4. Сделать PR из ветки `feature/task-1` своего форка в ветку `master` своего форка
+5. Отправить ссылку на PR личным сообщением своему тьютору до конда дедлайна сдачи (см. таблицу прогресса)
+
+#### Рецепт
+
+Для добавления поддержки команд в рамках своего поддомена:
+
+1. Написать структуру `{Subdomain}` с методом `String()`
+2. Написать интерфейс `{Subdomain}Service` и **dummy** имплементацию
+3. Написать интерфейс `{Subdomain}Commander` по обработке команд
+
+---
+
+2. Реализовать `{Subdomain}Service` в **internal/service/{domain}/{subdomain}/**
+
+```go
+package {subdomain}
+
+import "github.com/ozonmp/omp-bot/internal/model/{domain}"
+
+type {Subdomain}Service interface {
+  Describe({subdomain}ID uint64) (*{domain}.{Subdomain}, error)
+  List(cursor uint64, limit uint64) ([]{domain}.{Subdomain}, error)
+  Create({domain}.{Subdomain}) (uint64, error)
+  Update({subdomain}ID uint64, {subdomain} {domain}.{Subdomain}) error
+  Remove({subdomain}ID uint64) (bool, error)
+}
+
+type Dummy{Subdomain}Service struct {}
+
+func NewDummy{Subdomain}Service() *Dummy{Subdomain}Service {
+  return &Dummy{Subdomain}Service{}
+}
+
+// ...
+```
+
+---
+
+3. Реализовать `{Subdomain}Commander` по обработке команд в **internal/app/commands/{domain}/{subdomain}/**
+
+```go
+package {subdomain}
+
+import (
+  model "github.com/ozonmp/omp-bot/internal/model/{domain}"
+  service "github.com/ozonmp/omp-bot/internal/service/{domain}/{subdomain}"
+)
+
+type {Subdomain}Commander interface {
+  Help(inputMsg *tgbotapi.Message)
+  Get(inputMsg *tgbotapi.Message)
+  List(inputMsg *tgbotapi.Message)
+  Delete(inputMsg *tgbotapi.Message)
+
+  New(inputMsg *tgbotapi.Message)    // return error not implemented
+  Edit(inputMsg *tgbotapi.Message)   // return error not implemented
+}
+
+func New{Subdomain}Commander(bot *tgbotapi.BotAPI, service service.{Subdomain}Service) {Subdomain}Commander {
+  // ...
+}
+```

omp-docs/images/kafka.png

@@ -0,0 +1,40 @@
+# Ozon Marketplace Project
+
+![schema](images/retranslator.png)
+
+Дальше везде используются **placeholder**-ы:
+- `{domain}`,`{Domain}`
+- `{subdomain}`,`{Subdomain}`
+
+Например, для поддомена `package` из домена `logistic` значение **placeholder**-ов будет:
+- `{domain}`,`{Domain}` = `logistic`,`Logistic`
+- `{subdomain}`,`{Subdomain}` = `package`,`Package`
+- `{domain}`/`{subdomain}` = `logistic`/`package`
+---
+
+### Задание 2
+
+1. Создать репозиторий в формате `{domain-kw}-{subdomain}-api`
+
+2. Описать сущность `{domain}.{Subdomain}` и `{domain}.{Subdomain}Event` в **internal/model/{subdomain}.go**
+
+3. Реализовать паттерн consumer-producer из **db** в **kafka** на основе интерфейсов [EventRepo](https://github.com/ozonmp/omp-demo-api/blob/b847b3ae4a3c9e1d25e31e077c847a22f8b7aa99/internal/app/repo/event.go#L7) и [EventSender](https://github.com/ozonmp/omp-demo-api/blob/b847b3ae4a3c9e1d25e31e077c847a22f8b7aa99/internal/app/sender/event.go#L7) для одного типа события **Created**
+
+4. Написать тесты
+
+5. Синхронизацию работы потоков сделать через `context` 💎
+
+6. Создавать задачи у **workerpool** по обработке батчевых идентификаторов записей событий 💎
+
+7. Поддержать несколько типов событий учитывая корректный порядок 💎
+
+8. Реализовать гарантию доставки **At-least-once** 💎
+
+9. Найти скрытые ошибки в коде 💎
+
+**Рецепт**
+
+[omp-demo-api](https://github.com/ozonmp/omp-demo-api)
+
+P.S. Обратите внимание используется зеркальная (внешняя) точка зрения на вопрос, кто является потребителем, а кто является производителем.
+Поэтому паттерн назвали **consumer-producer** и классы переименовали.

omp-docs/images/observability.png

@@ -0,0 +1,107 @@
+# Ozon Marketplace Project
+
+![schema](images/grpc.png)
+
+Дальше везде используются **placeholder**-ы:
+
+- `{domain}`,`{Domain}`
+- `{subdomain}`,`{Subdomain}`
+
+Например, для поддомена `package` из домена `logistic` значение **placeholder**-ов будет:
+
+- `{domain}`,`{Domain}` = `logistic`,`Logistic`
+- `{subdomain}`,`{Subdomain}` = `package`,`Package`
+- `{domain}`/`{subdomain}` = `logistic`/`package`
+- `{subdomains}`,`{Subdomains}` = `packages`,`Packages`
+
+---
+
+### Задание 3
+
+1. Сделать **rebase** своего репозитория `{kw-domain}-{subdomain}-api` на [omp-template-api](https://github.com/ozonmp/omp-template-api)
+2. Добавить в **proto** следующие **handler**-ы (пример [template](https://github.com/ozonmp/omp-template-api/blob/be1223fb1d1c9751b0d9db1d6e2dfff6ba4c9316/protos/ozonmp/omp_template_api/v1/omp_template_api.proto)):
+   1. `Create{Subdomain}`
+   2. `Describe{Subdomain}`
+   3. `List{Subdomains}`
+   4. `Remove{Subdomain}`
+3. Добавить теги валидации в поля сообщений (пример [template](https://github.com/ozonmp/omp-template-api/blob/be1223fb1d1c9751b0d9db1d6e2dfff6ba4c9316/protos/ozonmp/omp_template_api/v1/omp_template_api.proto#L28))
+4. Сделать рефакторинг: заменить `template` на `{subomain}` (см. рецепт)
+5. Сгенерировать **gRPC** код клиента и сервера (make generate)
+6. Имплементировать код новых ручек в **internal/api/api.go** (пример [template](https://github.com/ozonmp/omp-template-api/blob/be1223fb1d1c9751b0d9db1d6e2dfff6ba4c9316/internal/api/api.go#L34))
+   1. Код ручек должен просто логгировать вызовы (с уровнем `debug`)
+   2. Возвращать пустой ответ или внутреннюю ошибку (`not implemented`)
+   3. При желание разделить по разным файлам имплементацию ручек
+7. Протестировать через **grpc_cli** (или **grpcurl**) написанные ручки (пример [template](https://github.com/ozonmp/omp-template-api/blob/main/DOCS.md#grpc))
+8. Написать тесты по обработке не валидных запросов :gem:
+9. Настроить маршрутизацию при запуске контейнеров: :gem: (можно сделать через [dist](https://github.com/ozonmp/omp-grpc-template/tree/master/swagger/dist) директорию)
+   - с `0.0.0.0:8080/swagger` на контейнер **swagger**
+   - c `0.0.0.0:8080/api` на контейнер сервиса на порт **gateway**-a
+10. Сгенерировать **Python** код клиента и задеплоить его в **PyPi** :gem: (пример [template](https://github.com/ozonmp/omp-template-api/blob/main/DOCS.md#python-client))
+
+
+**Рецепт**
+
+Переезд проекта на рельсы шаблона
+```sh
+export domain_kw=omp
+export subdomain=demo
+
+git remote add template https://github.com/ozonmp/omp-template-api
+git fetch template main
+git rebase template/main
+git checkout template/main -- Makefile go.mod go.sum
+git rebase --continue
+rm -rf pkg/omp-template-api
+mkdir pkg/${domain_kw}-${subdomain}-api
+mv api/ozonmp/omp_template_api/v1/omp_template_api.proto \
+   api/ozonmp/omp_template_api/v1/${domain_kw}_${subdomain}_api.proto
+mv api/ozonmp/omp_template_api api/ozonmp/${domain_kw}_${subdomain}_api
+mv pypkg/omp-template-api pypkg/${domain_kw}-${subdomain}-api
+// grep (exclude 'api/google' dir)
+// - template -> ${subdomain}
+// - grep omp -> ${domain_kw}
+make generate
+go mod tidy
+make build
+# перенесли в шаблонном репозитории README.md в DOCS.md, чтобы было меньше коонфликтов при rebase
+mv DOCS.md README.md
+git add .
+git commit -m"refactored"
+```
+
+Описание сообщений
+```proto
+// ...
+
+message {Subdomain} {
+  uint64 id = 1;
+  string foo = 2;
+}
+
+message Create{Subdomain}V1Request {
+  string foo = 1;
+}
+
+message Create{Subdomain}V1Response {
+  uint64 {subdomain}_id = 1;
+}
+
+message Describe{Subdomain}V1Request {
+  uint64 {subdomain}_id = 1;
+}
+
+message List{Subdomains}V1Request {
+}
+
+message List{Subdomains}V1Response {
+  repeated {Subdomain} items = 1;
+}
+
+message Remove{Subdomain}V1Request {
+  uint64 {subdomain}_id = 1;
+}
+
+message Remove{Subdomain}V1Response {
+  bool found = 1;
+}
+```

omp-docs/images/postgres.png

@@ -0,0 +1,91 @@
+# Ozon Marketplace Project
+
+![schema](images/postgres.png)
+
+Дальше везде используются **placeholder**-ы:
+
+- `{domain}`,`{Domain}`
+- `{subdomain}`,`{Subdomain}`
+
+Например, для поддомена `package` из домена `logistic` значение **placeholder**-ов будет:
+
+- `{domain}`,`{Domain}` = `logistic`,`Logistic`
+- `{subdomain}`,`{Subdomain}` = `package`,`Package`
+- `{domain}`/`{subdomain}` = `logistic`/`package`
+- `{subdomains}`,`{Subdomains}` = `packages`,`Packages`
+
+---
+
+**Задание IV**
+
+1. Реализовать методы для интерфейса `Repo`
+2. Написать миграции для создания таблиц и создания индексов
+3. Реализовать методы для интерфейса `RepoEvent` (сообщения в **proto**)
+4. Подготовить **dataset** для таблиц `subdomains` и `subdomains_events` :gem:
+5. Реализовать поддержку вариаций типов событий на обновление сущности `subdomain` :gem:
+6. Обеспечить защиту от **sql**-инъекции :gem:
+7. Настроить партиципирование таблицы на **N** частей :gem:
+8. Написать тесты :gem:
+
+---
+
+**Рецепт**
+
+Используя паттерн [Transactional Outbox Pattern](https://microservices.io/patterns/data/transactional-outbox.html)
+
+1. Создать таблицы следующих форматов:
+
+`{subdomains}` таблица
+
+| id **bigint** | ...  | removed **bool** | created **timestamp** | updated **timestamp** |
+| :-----------: | :--: | :--------------: | :-------------------: | :-------------------: |
+|               |      |                  |                       |                       |
+
+
+
+`{subdomains}_events` 📤 таблица
+
+| id **bigint** | {subdomain}_id **bigint** | type **text** | status | payload **jsonb**  | updated **timestamp** |
+| :-----------: | :-----------------------: | :-----------: | ------ | :----------------: | ------- |
+|               |                           |    Created    | lock   | `SubdomainCreated` |         |
+|               |                           |    Updated    | lock   | `SubdomainUpdated` |         |
+|               |                           |    Removed    |        | `SubdomainRemoved` |         |
+
+
+2. Составить список sql запросов для таблицы `{subdomains}`, потом для `{subdomains}_events`
+
+```sql
+-- Lock n events 🐘 🏆
+```
+
+3. Имплементировать методы интерфейсов с помощью [squirell](https://github.com/Masterminds/squirrel)
+
+```go
+type Repo interface {
+	Add(*model.Subdomain) (uint64, error)
+	Get(subdomainID uint64) (*model.Subdomain, error)
+	List(limit uint64, cursor uint64) ([]model.Subdomain, error)
+	Remove(subdomainID uint64) (bool, error)
+}
+```
+
+
+```go
+type EventRepo interface {
+	Lock(n uint64) ([]model.SubdomainEvent, error)
+	Unlock(eventIDs []uint64) error
+	Remove(eventIDs []uint64) (bool, error)
+}
+```
+
+4. Написать и накатить миграции
+```sh
+$ cd migrations
+$ cat .env
+PGPASSWORD=docker
+PGUSER=docker
+$ set -o allexport; source .env; set +o allexport
+$ goose postgres "host=localhost sslmode=disable dbname={domain-kw}_{subdomain}_api port=5432" up
+$ goose postgres "host=localhost sslmode=disable dbname={domain-kw}_{subdomain}_api port=5432" status
+```
+5. Поднять сервис и пострелять в него разными запросами [пример](https://github.com/ozonmp/omp-template-api/blob/main/DOCS.md#gateway)

omp-docs/images/retranslator.png

@@ -0,0 +1,40 @@
+# Ozon Marketplace Project
+
+![schema](images/observability.png)
+
+Дальше везде используются **placeholder**-ы:
+
+- `{domain}`,`{Domain}`
+- `{subdomain}`,`{Subdomain}`
+
+Например, для поддомена `package` из домена `logistic` значение **placeholder**-ов будет:
+
+- `{domain}`,`{Domain}` = `logistic`,`Logistic`
+- `{subdomain}`,`{Subdomain}` = `package`,`Package`
+- `{domain}`/`{subdomain}` = `logistic`/`package`
+- `{subdomains}`,`{Subdomains}` = `packages`,`Packages`
+
+---
+
+**Задание V**
+
+_Логирование_
+
+1. Покрыть логированием код обработки ручек со всем уровнем вложенности
+2. Добавить поддержку изменения уровня логирования через заголовок запроса
+3. Добавить поддержку детализированного вывода запроса и ответа через **middleware** :gem:
+4. Добавить отображение в **swagger** отладочных заголовков :gem:
+
+_Трассировка_
+
+1. Добавить создание спанов для ручек
+2. Добавить заполнение необходимых полей и ошибок
+3. Пострелять с помощью **hey**
+
+_Метрики_
+
+1. Добавить метрики на
+   1. Кол-во **NotFound** событий 🔍
+   2. Кол-во создаваемых **CUD** событий 🔍
+   3. Кол-во обрабатываемых событий в ретрансляторе 🔍
+2. Добавить **dashboard** на отображение метрик :gem: