HSE/tgit
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: ТЗ v2, архитектура, ADR, переезд в Gitea #23

Merged
Eleboba merged 5 commits from docs/2-spec-architecture into dev 2026-10-13 22:59:15 +03:00
Conversation 0 Commits 5 Files Changed 9
+117 -11
8 changed files with 117 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit af1585c634 - Show all commits
CLAUDE.md
+13 -6
View File
@@ -6,8 +6,14 @@
set -a; . ./.env 2>/dev/null; set +a
```
`SOURCECRAFT_TOKEN` — токен SourceCraft API (секрет — **в чат не печатать**). Репозиторий:
[`rogachevegorushka/tgit`](https://sourcecraft.dev/rogachevegorushka/tgit). API → [`docs/dev/SOURCECRAFT_API.md`](docs/dev/SOURCECRAFT_API.md).
Переменные: `GITEA_URL`, `GITEA_TOKEN`, `GITEA_USER`, `GITEA_REPO`, `SOURCECRAFT_TOKEN` (токены — секрет, **в чат не печатать**).
| Где | Что | Remote |
|---|---|---|
| [Gitea `HSE/tgit`](https://gitea.24studbank.ru/HSE/tgit) | **основной:** код, issues, PR, ревью | `origin` |
| [SourceCraft `rogachevegorushka/tgit`](https://sourcecraft.dev/rogachevegorushka/tgit) | зеркало (push-mirror из Gitea) + CI/CD | `sourcecraft` (только чтение) |
⛔ В SourceCraft ничего не пушим и не мержим — зеркало перезапишет (ADR-010).
---
@@ -31,7 +37,7 @@ Telegram-бот (учебный проект НИУ ВШЭ, курс Python): п
## Карта документации
> Задачи — в Issues на SourceCraft, не в файлах.
> Задачи — в [Gitea Issues](https://gitea.24studbank.ru/HSE/tgit/issues), не в файлах.
| Файл | О чём |
|------|-------|
@@ -41,14 +47,15 @@ Telegram-бот (учебный проект НИУ ВШЭ, курс Python): п
| [`docs/QUESTIONS_IDEAS.md`](docs/QUESTIONS_IDEAS.md) | Открытые вопросы, бэклог идей |
| [`docs/dev/WORKFLOW.md`](docs/dev/WORKFLOW.md) | Регламент: ветки, коммиты, PR, жизненный цикл задачи |
| [`docs/dev/ISSUE_TEMPLATE.md`](docs/dev/ISSUE_TEMPLATE.md) | Шаблон тела issue |
| [`docs/dev/SOURCECRAFT_API.md`](docs/dev/SOURCECRAFT_API.md) | SourceCraft API: curl-шпаргалка (issue, метки, PR) |
| [`docs/dev/GITEA_API.md`](docs/dev/GITEA_API.md) | Gitea API: issue, PR, зависимости, зеркало |
| [`docs/dev/SOURCECRAFT_API.md`](docs/dev/SOURCECRAFT_API.md) | SourceCraft API: CI-прогоны, логи, секреты |
---
## TL;DR — работа
1. **Задача = Issue.** Нет issue — нет кода.
2. **Ветка от `dev`:** `<type>/<issue#>-<slug>`. PR в `dev`; `dev → main` — только человек.
1. **Задача = Issue в Gitea.** Нет issue — нет кода.
2. **Ветка от `dev`:** `<type>/<issue#>-<slug>`. PR в `dev` (в Gitea); `dev → main` — только человек.
3. **Гейт зелёный:** lint + тесты перед PR.
4. **Завершил → push + PR** сразу.
5. **Лог выполнения** — в issue (`### YYYY-MM-DD`), архитектурные решения — в `DECISIONS.md`.
README.md
+2
View File
@@ -10,3 +10,5 @@
- ТЗ: [`docs/SPEC.md`](docs/SPEC.md)
- Архитектура: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
- Как работаем: [`docs/dev/WORKFLOW.md`](docs/dev/WORKFLOW.md)
Основной репозиторий и задачи — [Gitea `HSE/tgit`](https://gitea.24studbank.ru/HSE/tgit); [SourceCraft](https://sourcecraft.dev/rogachevegorushka/tgit) — зеркало с CI/CD.
docs/ARCHITECTURE.md
+5 -2
View File
@@ -33,7 +33,7 @@
| Репозиторий | Что внутри | CI/CD |
|---|---|---|
| `tgit` | код бота | PR/push `dev`: lint + types + tests; push `main`: + деплой бота на хост |
| `tgit` (Gitea → зеркало в SourceCraft) | код бота | push в любую ветку: lint + types + tests; push `main`: + деплой бота на хост |
| `tgit-uploads` | `projects/<name>/…` от пользователей | push `main`: проверки проекта; успех → `ssh tgit-runner deploy <project> <sha>` |
## 2. Компоненты
@@ -142,9 +142,12 @@ docker run -d --name tgit-app-<project> --label tgit.project=<project> --label t
## 5. CI/CD
### 5.1 Репозиторий бота (`tgit/.sourcecraft/ci.yaml`)
Код живёт в Gitea, SourceCraft получает его push-зеркалом и запускает CI/CD (ADR-010).
| Триггер | Workflow | Шаги |
|---|---|---|
| PR в `dev`/`main`, push в `dev` | `check` | `uv sync --frozen` → `ruff check` + `ruff format --check` → `mypy app` → `pytest --cov=app --cov-fail-under=70` |
| push в любую ветку (через зеркало Gitea; PR живут в Gitea — ADR-010) | `check` | `uv sync --frozen` → `ruff check` + `ruff format --check` → `mypy app` → `pytest --cov=app --cov-fail-under=70` |
| push в `main` | `check` + `deploy` | → `infra/deploy/deploy.sh` по SSH (секреты `DEPLOY_SSH_KEY`, `DEPLOY_HOST`) → smoke: healthcheck контейнера |
### 5.2 Репозиторий загрузок (`tgit-uploads/.sourcecraft/ci.yaml`)
docs/DECISIONS.md
+13 -1
View File
@@ -15,7 +15,7 @@
---
## ADR-001: Хостинг кода и задач — SourceCraft
**Дата:** 2026-10-12 · **Статус:** принято
**Дата:** 2026-10-12 · **Статус:** заменено ADR-010
**Контекст:** нужен репозиторий проекта, трекер задач и CI.
**Решение:** код бота, issues и CI — на SourceCraft. Загрузки пользователей — в отдельный репозиторий там же.
@@ -84,3 +84,15 @@
**Решение:** Python 3.12, uv, aiogram 3, httpx, pydantic-settings, SQLAlchemy 2 async + Alembic, PostgreSQL 16, `regex`, pytest (+ pytest-asyncio, respx), ruff, mypy. Контейнеризация — Docker Compose.
**Альтернативы:** python-telegram-bot — синхронное наследие в API; SQLite в проде — проще, но Postgres ближе к реальным сервисам и уже привычен по Vobot/meditron.
**Последствия:** тесты на SQLite через тот же SQLAlchemy.
## ADR-010: Gitea — основной репозиторий и трекер, SourceCraft — зеркало + CI/CD
**Дата:** 2026-10-12 · **Статус:** принято (заменяет ADR-001)
**Контекст:** веб-интерфейс SourceCraft работает нестабильно и часть функций отображает плохо; API периодически рвёт соединения. При этом CI/CD на SourceCraft — часть постановки преподавателя.
**Решение:** код, issues, PR и ревью — в Gitea [`HSE/tgit`](https://gitea.24studbank.ru/HSE/tgit) (как Vobot/meditron). Встроенный push-mirror Gitea синхронизирует репозиторий в SourceCraft на каждый push (+ раз в 8 ч); CI/CD бота и репозиторий загрузок `tgit-uploads` остаются в SourceCraft.
**Альтернативы:** только SourceCraft — неудобно работать; только Gitea (Gitea Actions) — уходим от постановки; зеркало по SSH — на этом Gitea SSH-зеркала отключены, поэтому HTTPS + токен SourceCraft.
**Последствия:**
- В SourceCraft ничего не пушим и не мержим — зеркало перезаписывает его целиком.
- Триггер `pull_request` в SourceCraft не срабатывает (PR живут в Gitea) → CI бота запускается на `push` во все ветки.
- Токен SourceCraft хранится в настройках зеркала Gitea → нужен отдельный токен с доступом только к `tgit`.
- Issues #1–#21 перенесены из SourceCraft с теми же номерами; в SourceCraft закрыты со ссылкой.
docs/SPEC.md
+1 -1
View File
@@ -26,7 +26,7 @@
| Термин | Значение |
|---|---|
| **Репозиторий бота** | [`rogachevegorushka/tgit`](https://sourcecraft.dev/rogachevegorushka/tgit) — код самого бота |
| **Репозиторий бота** | Gitea [`HSE/tgit`](https://gitea.24studbank.ru/HSE/tgit) (основной) → зеркало [`rogachevegorushka/tgit`](https://sourcecraft.dev/rogachevegorushka/tgit) в SourceCraft, где работает CI/CD |
| **Репозиторий загрузок** | `rogachevegorushka/tgit-uploads` — сюда бот коммитит файлы пользователей |
| **Проект** | Папка `projects/<name>/` в репозитории загрузок; единица запуска и мониторинга |
| **Загрузка** | Один отправленный файл → один коммит |
docs/dev/GITEA_API.md
+67
View File
@@ -0,0 +1,67 @@
# Gitea API — шпаргалка
Gitea — основной репозиторий и трекер: [`HSE/tgit`](https://gitea.24studbank.ru/HSE/tgit). SourceCraft — зеркало (ADR-010).
> **Кириллица в JSON:** не собирать тело в `curl -d '{...}'` руками — ломается кодировка и экранирование.
> Тело собираем в Python (`json.dumps(..., ensure_ascii=False)`) в файл и отправляем `--data @file.json`.
```bash
set -a; . ./.env; set +a # GITEA_URL, GITEA_TOKEN, GITEA_USER, GITEA_REPO
G="$GITEA_URL/api/v1/repos/$GITEA_REPO"
A="Authorization: token $GITEA_TOKEN"
J="Content-Type: application/json; charset=utf-8"
alias curl='curl --retry 4 --retry-all-errors --retry-delay 2'
```
> Сервер иногда рвёт SSH (`Connection closed … port 2222`) и медленно отвечает на запись — повторять, перед повторным
> POST проверять, не создалась ли сущность.
## Issues
```bash
# мои открытые
curl -s -H "$A" "$G/issues?state=open&type=issues&assigned_by=$GITEA_USER"
# создать: {"title","body","labels":[id…],"milestone":id,"assignees":["$GITEA_USER"]}
curl -s -X POST -H "$A" -H "$J" "$G/issues" --data @issue.json
# обновить тело / закрыть
curl -s -X PATCH -H "$A" -H "$J" "$G/issues/NN" --data @body.json # {"body": "..."}
curl -s -X PATCH -H "$A" -H "$J" "$G/issues/NN" -d '{"state":"closed"}'
# комментарий
curl -s -X POST -H "$A" -H "$J" "$G/issues/NN/comments" --data @comment.json # {"body": "..."}
# метки и вехи — по id
curl -s -H "$A" "$G/labels"
curl -s -H "$A" "$G/milestones?state=all"
```
## Зависимости (только через API, не текстом в теле)
```bash
# #NN зависит от #MM (MM блокирует NN)
curl -s -X POST -H "$A" -H "$J" "$G/issues/NN/dependencies" -d "{\"owner\":\"${GITEA_REPO%%/*}\",\"repo\":\"${GITEA_REPO##*/}\",\"index\":MM}"
curl -s -H "$A" "$G/issues/NN/dependencies"
```
## Pull requests
```bash
# PR в dev (не в main!); тело — с "Closes #NN"
curl -s -X POST -H "$A" -H "$J" "$G/pulls" --data @pr.json # {"head":"feat/NN-slug","base":"dev","title":"…","body":"…"}
# ветка ещё есть? пусто → PR смержен, не пушить
git ls-remote --heads origin <ветка>
```
## Зеркало в SourceCraft
```bash
curl -s -H "$A" "$G/push_mirrors" # статус: last_update, last_error
curl -s -X POST -H "$A" "$G/push_mirrors-sync" # синхронизировать сейчас
```
Зеркало — HTTPS (`git.sourcecraft.dev`) с токеном SourceCraft: SSH-зеркала на этом Gitea отключены.
Синхронизация — на каждый push + раз в 8 часов. Зеркало перезаписывает SourceCraft целиком (`--mirror`):
**в SourceCraft ничего не пушим и не мержим** — изменения пропадут.
docs/dev/SOURCECRAFT_API.md
+3
View File
@@ -1,5 +1,8 @@
# SourceCraft API — шпаргалка
> Issues и PR ведём в Gitea ([`GITEA_API.md`](GITEA_API.md), ADR-010). Здесь нужны в основном CI-прогоны, логи и секреты;
> разделы про issues/метки/PR — справочно (бот и скрипты могут работать с `tgit-uploads`).
Справочник: [методы](https://sourcecraft.dev/portal/docs/en/api-ref/index.md) ·
[интерактивный](https://api.sourcecraft.tech/docs/index.html) ·
[swagger.json](https://api.sourcecraft.tech/sourcecraft.swagger.json)
docs/dev/WORKFLOW.md
+13 -1
View File
@@ -2,7 +2,8 @@
## Откуда задачи
- Только из Issues на SourceCraft. Нет issue → завести → потом код. API: [`SOURCECRAFT_API.md`](SOURCECRAFT_API.md).
- Только из [Gitea Issues](https://gitea.24studbank.ru/HSE/tgit/issues). Нет issue → завести → потом код. API: [`GITEA_API.md`](GITEA_API.md).
- Зависимости между issue — через API Gitea, не текстом в теле.
- Атрибуты issue: исполнитель, метка зоны (`bot` / `ci` / `infra` / `llm` / `docs`),
тип (`feature` / `fix` / `refactor` / `docs`), размер (`size/0.5` ≈ 2ч · `size/1` ≈ 4ч · `size/2` ≈ 1д).
- Тело — по [`ISSUE_TEMPLATE.md`](ISSUE_TEMPLATE.md).
@@ -20,6 +21,17 @@
8. Мерж → ветку удалить
```
## Репозитории
```
Gitea HSE/tgit (origin) ──push-mirror (на каждый push)──► SourceCraft rogachevegorushka/tgit
код · issues · PR · ревью CI/CD (.sourcecraft/ci.yaml)
```
- Работаем только с `origin` (Gitea). Remote `sourcecraft` — для чтения/сверки.
- ⛔ В SourceCraft не пушим, не мержим, PR не открываем: зеркало перезаписывает его целиком.
- CI SourceCraft запускается пушем зеркала; результат смотрим там же (ссылка — в PR вручную или через бота, когда будет).
## Ветки
```