Как устроена навигация
Индекс объясняет, что и когда читать
FISS/INDEX.md — основная точка входа. Индексы отдельных областей также называются INDEX.md и находятся внутри соответствующих каталогов.
Каждая ссылка на материал или область в индексном файле должна сопровождаться условием чтения: пояснением, в какой ситуации нужен связанный контекст. В исходной терминологии стандарта это правило называется Read when; в русскоязычных индексах можно писать «Читать…».
Пример корневого индекса для проекта с несколькими областями:
# Интеллектуальное пространство проекта
- [Базовый контекст](BOOTSTRAP.md) — Читать всегда перед началом работы с проектом.
- [Предметная область](knowledge/subject/INDEX.md) — Читать при изменении бизнес-правил и работе с предметными понятиями.
- [Устройство проекта](knowledge/project/architecture.md) — Читать при изменении компонентов системы или настройке окружения.
- [Текущее состояние](state/INDEX.md) — Читать, когда риски, открытые вопросы или временные ограничения могут повлиять на задачу.Подпись «Предметная область проекта» только описывает содержание. Условие «Читать при изменении бизнес-правил» помогает решить, нужен ли материал сейчас — это реализует принцип «Делайте применимость видимой».
Следуя принципу «Отделяйте навигацию от содержания», индекс должен оставаться кратким: ссылки, условия чтения и необходимые пояснения для навигации. Подробное содержание размещается в документах, на которые он ссылается. Это позволяет переходить от общего контекста к подробностям по мере необходимости.
Область может быть файлом или каталогом
Область — тематически связанная часть интеллектуального пространства, например проектные знания или открытые вопросы.
| Форма | Когда использовать | Правило оформления |
|---|---|---|
| Один файл | Тема помещается в одном документе | Имя определяется проектом |
Каталог с INDEX.md — составная область | Тема разделена на несколько материалов | INDEX.md служит точкой входа в область |
Каталог без INDEX.md — контейнер | Нужно только сгруппировать области | Ссылки на дочерние области находятся в индексе охватывающей области |
Например, FISS/knowledge/ может быть контейнером:
FISS/
├── INDEX.md
├── BOOTSTRAP.md
└── knowledge/
├── project/
│ └── architecture.md
└── subject/
├── INDEX.md
├── access.md
└── notifications.mdВ этом примере корневой индекс ссылается на FISS/knowledge/project/architecture.md и FISS/knowledge/subject/INDEX.md. Индекс FISS/knowledge/subject/INDEX.md ведёт к материалам своей области. Отдельный FISS/knowledge/INDEX.md не нужен.
Имена областей, представленных одним файлом, и других содержательных документов, таких как access.md, определяет проект. Стандарт закрепляет имена INDEX.md для навигационных точек и BOOTSTRAP.md для обязательного базового контекста.
Все используемые области должны быть доступны через навигацию от FISS/INDEX.md. Индекс составной области должен вести к её материалам и дочерним областям; при переходе через контейнер ссылки ведут непосредственно к вложенным областям. Для всех индексных ссылок действует правило условия чтения.
Как расширять область
Когда одному файлу становится тесно, его можно заменить каталогом с индексом:
До: После:
FISS/state/ FISS/state/
└── open-questions.md └── open-questions/
├── INDEX.md
├── payment-model.md
└── access-policy.mdПри таком переходе необходимо обновить входящие ссылки. К новому INDEX.md применяются те же правила навигации, что и к корневому.
Закладывайте структуру для разделения
В областях, представленных одним файлом, рекомендуется изначально закладывать структуру, которую легко будет разделить по отдельным файлам, когда документ разрастётся. Это помогает следовать принципу «Начинайте с малого»: начинать с простого единого файла, но заранее исключать трудности при будущем разделении.
Если материал внутри файла с самого начала организован по логически цельным разделам и подразделам, то при росте проекта каждый такой раздел становится естественным кандидатом на вынесение в отдельный файл или подкаталог без необходимости распутывать и переписывать связанный текст.
Например, начальный документ FISS/knowledge/project/architecture.md может содержать:
# Frontend
## Общие правила
- В `admin` и `front` использовать TypeScript, не JavaScript.
- В TypeScript не ставить `;` в конце строк.
- Не дублировать типы между страницами.
- Для взаимодействия с backend предпочитать composable-first подход.
## Admin
- `admin` — Nuxt 4 SPA + `naive-ui`; SSR выключен.
- `admin` SPA обслуживает два host-а: admin host для `/admin` и business host для `/business`; не добавлять cross-host редиректы, раскрывающие admin host бизнес-пользователям.
- Для backend-запросов использовать `admin/app/utils/apiFetch.ts`, не прямой `fetch`.
# Cache
## Redis clients и разделение DB
- Redis разделён по ответственности:
- DB0 / `snc_redis.token_store` / prefix `token:` — только refresh-token whitelist и auth/token storage.
- DB1 / `snc_redis.app_cache` / prefix `cache:` — только application cache.
- Application cache не хранить в DB0.
- Auth/session/token data не хранить в DB1.
- Cache не является source of truth. Источником истины остаются PostgreSQL и доменные сервисы.
## Правила application cache
- У каждой application cache entry должен быть конечный TTL.
- Cache key должен учитывать все request parameters и context values, которые могут изменить response.
- Cache key должен быть детерминированным и стабильным для эквивалентных запросов.
- В cache key нельзя писать raw user input, токены, cookies, секреты, raw ПДн, полный URL с query string или request body.
- Если в будущем для cache key неизбежно нужен пользовательский ввод, сначала нормализовать его и предпочитать safe hash/fingerprint вместо raw value.
- При добавлении или изменении кеша в той же задаче фиксировать invalidation strategy.
- Если invalidation coarse-grained, явно фиксировать это и держать TTL консервативным.Когда этот файл разрастётся, чёткая структура позволит естественным образом разделить его, например, на:
FISS/knowledge/project/frontend/common-rules.mdFISS/knowledge/project/frontend/admin.mdFISS/knowledge/project/cache.md(илиFISS/knowledge/project/cache/INDEX.md)