goNotes

Imported from Feverqwe/goNotes (AGENTS.md). Install upstream with npx skills add Feverqwe/goNotes. Copyright stays with the author.

Руководство для агентов

Назначение проекта

goNotes — self-hosted приложение для заметок. Backend написан на Go и хранит данные в SQLite; frontend находится в notes-ui и собирается в статические файлы, которые в production встраиваются в Go-бинарник.

Перед изменениями прочитай карту архитектуры и релевантные исходники. README.md описывает пользовательскую установку и запуск.

Где вносить изменения

• HTTP API-адаптеры: internal/api.go; общая бизнес-логика, SQL и транзакции заметок для HTTP/MCP: internal/notes_service.go; DTO ответа: internal/types.go.
• Схема новой БД: db.sql; совместимость существующей БД: internal/migrations.go.
• Конфигурация и расположение профиля: internal/cfg/config.go.
• Клиентский API-контракт: notes-ui/src/tools/api.ts и notes-ui/src/tools/types.ts; модель заметки: notes-ui/src/types.ts.
• Загрузка и кеш заметок/тегов: notes-ui/src/hooks/; экран, URL-фильтры и верхнеуровневое состояние: notes-ui/src/App.tsx.
• Поиск и переключение текущих/архивных заметок: NotesHeader; категории и их сортировка: TagsNavigation и TagsNavigationList; desktop/mobile drawer, корзина и тема: NavigationDrawer; вывод ленты: NotesFeed и NoteCard.
• Режимы массовых действий и ручной сортировки заметок координируются в App.tsx, а их панели находятся в NoteBulkActionsBar и NoteReorderBar.
• Создание и редактирование заметок координирует NoteEditor: на мобильных экранах он показывает CompactNoteEditor, на desktop — CompactNoteEditorDialog с переходом в AdvancedNoteEditor. Изменения сценария редактирования проверь в обеих ветках.
• Конфигурация frontend-сборки находится в notes-ui/rspack.config.cts.
• Конфигурация Storybook находится в notes-ui/.storybook; stories размещай рядом с компонентами в файлах *.stories.tsx. Общие провайдеры и стили подключай в notes-ui/.storybook/preview.tsx.

Основные команды

Запускай команды из корня репозитория, если не указано иное.

# Backend
gofmt -w <измененные-go-файлы>
go test ./...
go vet ./...
go build ./...

# Frontend
nvm use
cd notes-ui
npm ci
npm run tsc
npm run lint
npm run build

# Storybook
npm run storybook
npm run build-storybook

В проекте пока нет отдельных unit-тестов. Для каждого изменения обязательно выполняй подходящие статические проверки и сборку. npm run lint также запускает проверку Prettier. Не запускай npm install, если не требуется менять зависимости: для воспроизводимой установки используй npm ci. Версия Node.js закреплена в корневом .nvmrc; перед frontend-командами запускай nvm use из корня репозитория. Сейчас проект использует Node.js 24.

Для локальной разработки:

# Терминал 1: backend читает UI из notes-ui/dist
./scripts/run.sh dev

# Терминал 2: пересборка frontend при изменениях
cd notes-ui && npm run dev

# Изолированная разработка и просмотр компонентов на порту 6006
cd notes-ui && npm run storybook

По умолчанию приложение слушает порт 80 и пишет пользовательские данные вне репозитория. Для изолированного smoke-теста задай PROFILE_PLACE на временный каталог и укажи свободный непривилегированный порт в созданном config.json. Не коммить локальные базы, конфиги, загрузки и собранные артефакты.

Для production-проверки сначала выполни ./scripts/build.ui.sh, затем ./scripts/build.sh. Первый скрипт собирает frontend и обновляет игнорируемый assets/www, второй создает локальный игнорируемый бинарник goNotes.

Правила изменений

• Сохраняй текущую простую архитектуру; не добавляй фреймворк или новую зависимость без необходимости.
• Форматируй Go через gofmt, TypeScript/React — существующими ESLint и Prettier-конфигами.
• При добавлении или существенном изменении изолированного UI-компонента обновляй его story, если компонент уже представлен в Storybook. Не обращайся к реальному backend из stories: передавай данные через args или локальные моки.
• SQL всегда параметризуй. Изменения схемы делай обратно совместимыми: актуализируй db.sql для новых установок и добавляй миграцию в internal/migrations.go для существующих баз.
• При изменении API синхронно обновляй backend DTO/обработчик и типы/клиент в notes-ui/src/tools или notes-ui/src/types.ts. Все API-ответы имеют форму {"result": ...} либо {"error": "..."}; создание и обновление заметки принимают multipart/form-data, остальные мутации — JSON.
• При добавлении нового HTTP API или изменении доступных через API возможностей заметок синхронно обновляй MCP-контракт в internal/mcp.go: инструменты, входные и выходные DTO, описания и тесты. При появлении новой кастомной Markdown-разметки также добавляй правила ее использования и сохранения в инструкции MCP-сервера, чтобы агенты не теряли разметку при редактировании.
• Теги являются частью текста заметки: backend извлекает хештеги и синхронизирует tags/message_tags. Массовое добавление тегов также дописывает отсутствующие #теги в content, обновляет content_lower и updated_at; не превращай эту операцию в изменение только связующей таблицы.
• Удаление двухэтапное: первое действие перемещает заметку в корзину через is_deleted, повторное удаление из корзины физически удаляет запись и файлы вложений. Не ломай этот контракт в одиночных и пакетных операциях.
• Список заметок использует cursor pagination по sort_order; при изменении сортировки синхронно проверь internal/api.go и useNotes.ts.
• App.tsx синхронизирует id, q, tags, archived и deleted с URL. Глобальный архив и архив выбранной категории переключаются в NotesHeader; отдельного пункта архива в NavigationDrawer нет.
• Учитывай два режима раздачи UI: notes-ui/dist при DEBUG_UI=1 и встроенную файловую систему assets/www в production.
• Не редактируй вручную assets/www: это генерируемый и игнорируемый результат npm run release. Не коммить notes-ui/dist и бинарник goNotes.
• internal/cfg.Config.UploadsDir сейчас не используется обработчиками файлов: фактический путь — <PROFILE_PLACE>/uploads. Не полагайся на это поле без сквозного исправления чтения, записи, превью и удаления вложений.
• Не изменяй и не удаляй пользовательские данные (notes.db*, uploads/) ради тестов.
• Не исправляй попутно несвязанные проблемы и не перезаписывай чужие незакоммиченные изменения.

Критерии готовности

Перед завершением:

1. Проверь diff и отсутствие случайных/generated-файлов.
2. Выполни проверки затронутой части (go test ./... для backend; npm run tsc, npm run lint, npm run build для frontend; дополнительно npm run build-storybook при изменении Storybook или stories).
3. Для сквозных изменений собери обе части и проверь основной сценарий вручную.
4. В отчете перечисли измененные файлы, выполненные проверки и известные ограничения.