aenvs/.docs/00-initial-qa-session/q-002.md

Follow-up Questions (q-002)

Typos / Bugs in Types Definition

В типах есть ошибки, которые нужно исправить:

// Текущий код с ошибками:
type Project struct {
    Id uuid.UUID `json:"id"`
    Name string `json:"string"`  // ❌ должно быть json:"name"
}

const {  // ❌ должно быть const (
    ACTIVE State = 1
    INACTIVE State = -1
}

type Version struct {
    Ts int64 `json:"td"` // ❌ опечатка, должно быть json:"ts"
    // ...
}

type Envs struct {  // ❌ должно быть Env (singular), т.к. используется как []Env
    Name string `json:"name"`
    Path string `json"path"`  // ❌ пропущено двоеточие, json:"path"
}

Подтверди исправления или укажи правильные значения.

---

Уточнения по командам

1. aevs project remove --id {uuid} имеет комментарий (or --remove):

   • --remove не эквивалентен --id
   • Имелось в виду -r как короткий флаг для remove? Или это описка?

2. aevs project read — нет флага для вывода конкретной версии:

   • Сейчас показывает все версии проекта
   • Нужен ли флаг --version {timestamp} для просмотра конкретной версии? Answer: не нужен;

---

Уточнения по sync

3. "if version is inactive, server responds w/ latest version data":

   • "Latest" означает:
     • (a) последнюю по timestamp активную версию?
     • (b) последнюю созданную версию (независимо от state)? Answer: (a)

4. При sync создаётся новая версия — откуда берётся version_name?

   • Автоматически (timestamp)?
   • Интерактивный prompt пользователю?
   • Из конфига? Answer: интерактивный промпт

5. Version.Creator — откуда берётся значение?

   • Из api_key?
   • Из git config user.name?
   • Интерактивный ввод? Answer: api_key подразумевает конкретного пользователя с набором пермишнов и username, так вот Version.Creator = username, на данный момент можно захардкодить root с пометкой // TODO

---

Уточнение по "no active version"

6. В q-001 ответ "provide some variants" не ясен. Варианты поведения при sync, если нет активной версии:

   • (a) Создать новую версию из локальных файлов
   • (b) Показать ошибку "no active version found"
   • (c) Показать список всех версий и предложить выбрать

   Какой вариант предпочтителен? Answer: Если локальные файлы есть, то нужно сформировать новую версию с вопросом о её имени; если нет и локальных файлов окружения нужно вывести ошибку, что нет активных версий и локальных версий тоже. Ситуация кажется невозможной, т.к. версии можно сделать неактивными только в результате мерджа, при этом операция подразумевает создание новой активной версии;

---

Server Interface

7. Какой протокол для сервера?

   • REST API (HTTP/JSON)?
   • gRPC?
   • Другое? Answer: рассмотри другие cli tool такого рода, например wrangler для cloudflare

8. Нужно ли описать endpoints сервера для мока? Например:

   GET    /projects
   POST   /projects
   DELETE /projects/{id}
   GET    /projects/{id}/versions
   POST   /projects/{id}/versions
   PATCH  /projects/{id}/versions/{ts}
   

   Answwer: нам нужен мок веб. сервера, но не сам вебсервер, нужно сделать для этого всё необходимое;

---

parseLocals vs Config.environments

9. Как соотносятся parseLocals и environments из конфига?

   • parseLocals сканирует все *.env.* файлы в директории
   • Config.environments содержит маппинг name → path

   Вопрос: При sync используем только environments из конфига, или parseLocals тоже участвует? Если оба — как разрешаются конфликты имён? Answer: имена могут быть не уникальными, конфиг заполняется из parseLocals, для добавления новых locals в конфиг нужно сделать это явно, т.е. если конфиг существет, то мы больше не ищем файлы в директориях проекта

---

Пояснение по "config inheritance"

10. Что я имел в виду под "inherit from parent directories":

    Пример структуры:

    ~/projects/
        aevs.yaml           ← глобальный конфиг (api_key)
        my-app/
            aevs.yaml       ← проектный конфиг (project, version, environments)
    

    При запуске aevs sync в ~/projects/my-app/:

    • Читается my-app/aevs.yaml
    • Если api_key не указан, ищется в ../aevs.yaml

    Нужна ли такая иерархия? Или api_key всегда должен быть в проектном конфиге? Answer: конфиг только один, путь до него либо указан флагом, либо он в директории из которой вызывается утилита, наследование не нужно