speckit: внедрение Spec Kit и фиксация архитектуры в конституции JT4D v1.0.0
- Интеграция Spec Kit для pi: команды `/speckit.*`, bash-скрипты и шаблоны в `.specify` - Конституция JT4D v1.0.0 вместо шаблона: принципы WELD для слоёв web и api, публичный API директории - Слои web описаны по методологии WELD и проверяются `eslint-plugin-weld` - Vitest в api запускает `*.test.ts` рядом с `*.spec.ts`, тесты исключены из сборки приложения - `yarn.lock` пересобран через `yarn deduplicate` ## Мотивация Нужно зафиксировать архитектуру проекта в конституции JT4D v1.0.0 и подключить Spec Kit, чтобы планировать фичи до написания кода. ## Ключевые моменты реализации - `eslint-plugin-weld` настроен только в `apps/web`: схема слоёв API описана конституцией и документацией, но линтером пока не проверяется Reviewed-on: jt4d/jt4d#4 Co-authored-by: Arswarog <arswarog@yandex.ru>
This commit is contained in:
1 parent
1d80630fb2
commit
7c60482467
55 files changed
+6070
-415
No files matched your search
@@ -4,16 +4,32 @@
|
||||
одну сторону:
|
||||
|
||||
```
|
||||
app → pages → widgets → entities → shared
|
||||
app → pages → @modules → common
|
||||
```
|
||||
|
||||
Слой слева знает о слоях справа и пользуется ими. Обратное запрещено: `shared` не знает, где
|
||||
применён и по чьей воле вызван, а `entities` не знает о `widgets`.
|
||||
Слой слева знает о слоях справа и пользуется ими. Обратное запрещено: `common` не знает, где
|
||||
применён и по чьей воле вызван, а `pages` не знает о `app`.
|
||||
|
||||
Слой — это директория: имя слоя и есть имя директории. Одни слои существуют в проекте в одном
|
||||
экземпляре, других — столько, сколько модулей.
|
||||
|
||||
**Модуль** — не слой, а рамка. `modules/<домен>` собирает свои `entities` и `widgets` и определяет,
|
||||
```
|
||||
src/
|
||||
├── app/
|
||||
├── pages/
|
||||
├── modules/
|
||||
│ └── <домен>/
|
||||
│ ├── widgets/
|
||||
│ ├── entities/
|
||||
│ └── modules/
|
||||
└── common/
|
||||
```
|
||||
|
||||
`@modules` — служебная метка места слоёв модулей в общей схеме, а не имя директории. Слои модулей
|
||||
(`widgets`, `entities`) повторяются в каждом модуле на любой глубине; принадлежность к слою модуля
|
||||
задаёт первое имя на пути от корня модуля.
|
||||
|
||||
**Модуль** — не слой, а рамка. `modules/<домен>` собирает свои `widgets` и `entities` и определяет,
|
||||
что из них видно снаружи, — тем же способом, каким это делает модуль в
|
||||
[слоях API](01-api-layers.md). Поддомен — такая же рамка, вложенная внутрь модуля.
|
||||
|
||||
@@ -54,9 +70,6 @@ app → pages → widgets → entities → shared
|
||||
между собой. Виджеты друг о друге не знают, поэтому место их встречи — страница. Всё, что является
|
||||
бизнес-логикой или передачей сообщений между виджетами, странице не принадлежит.
|
||||
|
||||
Как и модуль, страница бывает вложенной: лейаут с вкладками — это тоже `pages`, и он объявляет
|
||||
крошки за все свои вкладки, потому что только у него есть нужные для этого данные.
|
||||
|
||||
**Входит:**
|
||||
|
||||
- Композиция виджетов и их расположение на странице
|
||||
@@ -71,26 +84,26 @@ app → pages → widgets → entities → shared
|
||||
- Передача сообщений между виджетами
|
||||
- Работа с API
|
||||
|
||||
## widgets
|
||||
## @modules: widgets
|
||||
|
||||
**Самостоятельный блок интерфейса.**
|
||||
|
||||
Виджет сам добывает свои данные и сам держит своё состояние: открытие модалок, активную вкладку,
|
||||
раскрытые строки. Наружу он поставляет готовый блок, а внутрь принимает только параметры —
|
||||
идентификаторы и начальные значения, — поэтому страница может поставить виджет, ничего не зная о
|
||||
том, что внутри.
|
||||
раскрытые строки, значения полей формы. Наружу он поставляет готовый блок, а внутрь принимает только
|
||||
параметры — идентификаторы и начальные значения, — поэтому страница может поставить виджет, ничего
|
||||
не зная о том, что внутри.
|
||||
|
||||
Один виджет — один законченный участок работы: `AdminCreditsSummary` рисует карточку баланса
|
||||
платёжного аккаунта и держит диалоги лотов, броней и ручного начисления.
|
||||
Один виджет — один законченный участок работы: форма входа модуля `auth` проверяет поле, держит
|
||||
ошибку и статус отправки, а страница передаёт ей только различающиеся тексты.
|
||||
|
||||
Виджет собирается из `entities` и `shared` и о других виджетах на странице не знает: связать два
|
||||
виджета — задача `pages`.
|
||||
Виджет собирается из `entities` и `common` и о других виджетах на странице не знает: связать два
|
||||
виджета — задача `pages`. Слои выше модуля — `pages` и `app` — виджету недоступны.
|
||||
|
||||
**Входит:**
|
||||
|
||||
- Загрузка своих данных
|
||||
- Своё состояние: модалки, вкладки, раскрытия, промежуточные значения форм
|
||||
- Композиция `entities` и `shared`
|
||||
- Композиция `entities` и `common`
|
||||
- Действия пользователя в границах блока
|
||||
|
||||
**Не входит:**
|
||||
@@ -99,7 +112,7 @@ app → pages → widgets → entities → shared
|
||||
- Знание о других виджетах
|
||||
- Доменные правила
|
||||
|
||||
## entities
|
||||
## @modules: entities
|
||||
|
||||
**Показ доменной сущности.**
|
||||
|
||||
@@ -121,19 +134,18 @@ Entity отвечает за то, как выглядит одна доменн
|
||||
- Композиция нескольких сущностей
|
||||
- Знание о странице и о том, где entity показана
|
||||
|
||||
## shared
|
||||
## common
|
||||
|
||||
**Общий слой.**
|
||||
|
||||
`shared` — фундамент: UI-примитивы (кнопка, диалог, таблица), вызовы API (`shared/api`), типы,
|
||||
утилиты форматирования, переводы. Всё это переиспользуется слоями выше и не принадлежит ни одному
|
||||
сценарию.
|
||||
`common` — фундамент: UI-примитивы (кнопка, диалог, таблица), вызовы API, типы, утилиты
|
||||
форматирования, переводы. Всё это переиспользуется слоями выше и не принадлежит ни одному сценарию.
|
||||
|
||||
Слой ничего не знает о том, где и для чего его применили. Примитив интерфейса не подписывается на
|
||||
домен, а модуль API не решает, что показать пользователю при ошибке: решение принимает тот, кто его
|
||||
вызвал.
|
||||
|
||||
`shared` — нижний слой: его берут все, он не берёт никого.
|
||||
`common` — нижний слой: его берут все, он не берёт никого.
|
||||
|
||||
**Входит:**
|
||||
|
||||
@@ -148,3 +160,65 @@ Entity отвечает за то, как выглядит одна доменн
|
||||
- Знание о том, где и в каком сценарии он применён
|
||||
- Композиция доменного интерфейса
|
||||
- Решения о том, что показать и что сделать при ошибке
|
||||
|
||||
## Баррели: публичный API границы
|
||||
|
||||
Граница — модуль, слой, сложный компонент из нескольких файлов — объявляет публичный API через
|
||||
`index.ts` и только через него отдаёт содержимое наружу. Импорт внутреннего файла в обход барреля
|
||||
запрещён.
|
||||
|
||||
```ts
|
||||
// apps/web/src/common/index.ts
|
||||
export * from './lib';
|
||||
export * from './ui';
|
||||
|
||||
// apps/web/src/common/lib/index.ts
|
||||
export { applyTheme, getTheme, subscribeToTheme, toggleTheme, type Theme } from './theme';
|
||||
export { cn } from './utils';
|
||||
```
|
||||
|
||||
Правила барреля:
|
||||
|
||||
- Только явный список именованных реэкспортов. `export *` допустим лишь от вложенной директории, у
|
||||
которой уже есть собственный `index.ts`.
|
||||
- Никакого исполняемого кода: ни импортов стилей, ни инициализации, ни оборачивания компонентов.
|
||||
- Импорт из своего или вышестоящего барреля запрещён; внутри директории файлы импортируют друг друга
|
||||
относительными путями.
|
||||
|
||||
Межграничный импорт идёт через алиас `@jt4d-platform/web/*`, который объявлен в `tsconfig.base.json`
|
||||
и разрешается в `vite.config.ts` через `resolve.alias`:
|
||||
|
||||
```ts
|
||||
import { Button, usePageBreadcrumbs } from '@jt4d-platform/web/common';
|
||||
import { AuthForm } from '@jt4d-platform/web/modules/auth';
|
||||
import { HealthPage } from '@jt4d-platform/web/pages';
|
||||
```
|
||||
|
||||
Обход барреля ловится линтером правилом `weld/no-barrel-bypass` из `eslint-plugin-weld`; оно
|
||||
включено в `apps/web/eslint.config.mjs`.
|
||||
|
||||
## Приватность частей директории
|
||||
|
||||
Часть директории объявляется приватной явно, а не договорённостью на словах:
|
||||
|
||||
- публичный API директории — её баррель: файл, который баррель не реэкспортирует, наружу не
|
||||
отдаётся;
|
||||
- приватная группа файлов лежит в каталоге с точным именем `internal` вместе со всем содержимым;
|
||||
- приватное доступно только содержимому непосредственного родителя;
|
||||
- владелец может опубликовать часть реализации через свой баррель, но путь приватной директории от
|
||||
этого не открывается.
|
||||
|
||||
Пример — хук формы входа: `modules/auth/widgets/auth-form/useAuthForm.ts`. Он используется
|
||||
компонентом `AuthForm.tsx` из той же директории и не попадает в баррель виджета.
|
||||
|
||||
## Модули и видимость
|
||||
|
||||
Модули верхнего уровня лежат в `src/modules/<домен>`, вложенные — в контейнере `modules/` внутри
|
||||
родительского модуля. Контейнер слоем не является и собственного публичного API не имеет.
|
||||
|
||||
Видимость определяется положением в дереве: модулю доступны его предки, братья, братья предков и
|
||||
непосредственные дочерние модули. Доступ к «племянникам» запрещён: он раскрывает внутреннюю
|
||||
структуру ветки. Дублирование логики между модулями не допускается — общая часть переносится в
|
||||
`common` или в модуль, доступный по дереву.
|
||||
|
||||
Пример: `modules/auth` отдаёт наружу только `AuthForm`, страницы берут его из барреля модуля.
|
||||
@@ -200,7 +200,7 @@ staging-db-postgres create <org/project> <branch>
|
||||
## Применение на проде
|
||||
|
||||
Job `deploy-production` в `.gitea/workflows/production.yaml`, шаг `Deploy via SSH` — тот же
|
||||
`jt4d-lab/ssh-action`, что и на стейджинге, плюс `workdir: /srv/geo-platform` и
|
||||
`jt4d-lab/ssh-action`, что и на стейджинге, плюс `workdir: /srv/jt4d` и
|
||||
`files: docker-compose.production.yml`: компоуз-файл приезжает тем же шагом, отдельного `scp` нет.
|
||||
Порядок:
|
||||
|
||||
@@ -219,7 +219,7 @@ Job `deploy-production` в `.gitea/workflows/production.yaml`, шаг `Deploy vi
|
||||
поднимает HTTP-слой NestJS, а `migration:run` идёт отдельным процессом со своим соединением через
|
||||
`data-source.js`.
|
||||
|
||||
Логи приложения при провале смотрятся на хосте: `docker logs geo-platform_api --tail 50`.
|
||||
Логи приложения при провале смотрятся на хосте: `docker logs jt4d_api --tail 50`.
|
||||
|
||||
⚠️ `migration:show` — не безобидная команда «только посмотреть»:
|
||||
|
||||
@@ -280,7 +280,7 @@ runbook отката.
|
||||
|
||||
```bash
|
||||
ssh <prod>
|
||||
docker exec geo-platform_api node_modules/.bin/typeorm migration:show -d data-source.js
|
||||
docker exec jt4d_api node_modules/.bin/typeorm migration:show -d data-source.js
|
||||
```
|
||||
|
||||
`[X]` — применена, `[ ]` — нет. Этот вывод — источник истины, а не лог job.
|
||||
@@ -296,7 +296,7 @@ runbook отката.
|
||||
`docker images git.jt4d.ru/jt4d/jt4d/api`:
|
||||
|
||||
```bash
|
||||
cd /srv/geo-platform
|
||||
cd /srv/jt4d
|
||||
VERSION=<prev> docker-compose up -d
|
||||
```
|
||||
|
||||
@@ -308,7 +308,7 @@ runbook отката.
|
||||
старый код несовместим с новой схемой, откатывать схему придётся отдельно (`migration:revert`,
|
||||
по одной миграции за вызов) или восстанавливать из ручного дампа.
|
||||
|
||||
5. **Проверить результат:** `/api/health` и `docker logs geo-platform_api --tail 100`.
|
||||
5. **Проверить результат:** `/api/health` и `docker logs jt4d_api --tail 100`.
|
||||
|
||||
## Ручной запуск миграций на проде
|
||||
|
||||
@@ -320,13 +320,13 @@ runbook отката.
|
||||
ssh <prod>
|
||||
|
||||
# посмотреть, что применится
|
||||
docker exec geo-platform_api node_modules/.bin/typeorm migration:show -d data-source.js
|
||||
docker exec jt4d_api node_modules/.bin/typeorm migration:show -d data-source.js
|
||||
|
||||
# применить
|
||||
docker exec geo-platform_api node_modules/.bin/typeorm migration:run -t each -d data-source.js
|
||||
docker exec jt4d_api node_modules/.bin/typeorm migration:run -t each -d data-source.js
|
||||
|
||||
# откатить последнюю применённую (по одной за вызов)
|
||||
docker exec geo-platform_api node_modules/.bin/typeorm migration:revert -d data-source.js
|
||||
docker exec jt4d_api node_modules/.bin/typeorm migration:revert -d data-source.js
|
||||
```
|
||||
|
||||
Перед запуском учтите, что автоматического бэкапа нет (см. выше).
|
||||
@@ -345,8 +345,8 @@ Api ходит в прод-БД под `aigeo_app` — это не владел
|
||||
TypeORM `--fake` / `-f` (`MigrationRunCommand`, `MigrationExecutor`):
|
||||
|
||||
```bash
|
||||
docker exec geo-platform_api node_modules/.bin/typeorm migration:show -d data-source.js # сначала посмотреть список
|
||||
docker exec geo-platform_api node_modules/.bin/typeorm migration:run --fake -d data-source.js
|
||||
docker exec jt4d_api node_modules/.bin/typeorm migration:show -d data-source.js # сначала посмотреть список
|
||||
docker exec jt4d_api node_modules/.bin/typeorm migration:run --fake -d data-source.js
|
||||
```
|
||||
|
||||
`--fake` вставляет записи в таблицу `migrations`, не выполняя `up()`. Он применяется ко **всему**
|
||||
|
||||
Reference in new issue
Block a user