Структура документации по проектам — спецификация (для команды Wiki)¶

Проект common_docs (gitlab.com/gsmsoft1/common_docs). Это предложение структуры (последний шанс зафиксировать до наполнения). Дизайн: СА + Техлид. Дальнейшее наполнение/сортировку ведёт команда Wiki силами агентов (.claude/agents/: doc-sa/doc-ba/doc-architect/doc-cto).

Принцип трёх уровней¶

docs/projects/<project>/<category>/<domain>/<артефакты>.md
        L1            L2          L3

L1 — проект¶

Слаг проекта как в админ-панели (латиница, kebab-case): teslapay, trientes, bitbeon, meinbit, gexpay, … Правило: при создании проекта в админке создаётся одноимённая папка документации (см. «Автоматизация»).

L2 — категории (фиксированные слаги)¶

Слаг	Категория
`business-analytics`	Бизнес-аналитика (БА)
`system-analytics`	Системная аналитика (СА)
`tech-info`	Техническая информация (БД, схемы данных, API, интеграции)
`scenarios`	Бизнес-сценарии

L3 — единый доменный словарь (внутри каждой категории)¶

Деление по бизнес-доменам (не по типу артефакта; тип — в префиксе имени файла). Создаются только релевантные проекту домены.

auth, accounts, payments, cards, kyc-aml, exchange, crypto, acquiring, b2b, support, notifications, integrations, limits-fees, common.

Префиксы артефактов (тип кодируется именем файла): - БА: brd- (бизнес-требования), flow- (бизнес-процесс), rules- (правила), tariffs/glossary. - СА: spec- (спецификация), seq- (sequence), states- (состояния), er- (логическая модель). - tech: по типу артефакта (database/, data-model/, api/, integrations/). - scenarios: sc-NNN-<slug>.md (трёхзначный номер, уникален в проекте).

Общий технический раздел (teslapay + trientes)¶

database, scheme, techanaliz, techdoc — контент общий для teslapay и trientes. Хранится один раз в docs/_shared/ (сейчас: _shared/{database,scheme,techanaliz,techdoc}), проекты на него ссылаются (не дублируют). Целевая раскладка tech-info (зона doc-sa/doc-architect): tech-info/database ← _shared/database, tech-info/data-model ← _shared/scheme, tech-info/api ← _shared/techanaliz, tech-info/integrations ← _shared/techdoc. Механизм без дублей: include (mkdocs-include-markdown-plugin) или сборочный rsync из _shared в CI.

Бизнес-сценарии по проектам¶

teslapay/scenarios/ — сценарии TeslaPay (из вики main/TeslaPay/*): user/, payment/, finance/, support/(aml_1..aml_12), card/, B2B/.
trientes/scenarios/ — собственные сценарии Trientes + копия сценариев TeslaPay (по требованию: контент схож). Копии помечать во front-matter: source: teslapay/... + sync: copy (синхронны) / sync: fork (намеренно разошлись).
Целевая доменная раскладка (scenarios/auth|payments|cards|kyc-aml|...) — зона doc-sa; текущая раскладка по исходным разделам вики (user/payment/finance/support/...) сохранена как стартовая.

Маппинг «старый путь (вики) → новый»¶

Вики	Новый путь
`database/*`	`_shared/database/*` → `<proj>/tech-info/database`
`scheme/*`	`_shared/scheme/*` → `<proj>/tech-info/data-model`
`techanaliz/*`	`_shared/techanaliz/*` → `<proj>/tech-info/api`
`techdoc/*`	`_shared/techdoc/*` → `<proj>/tech-info/integrations`
`main/TeslaPay/*`	`teslapay/scenarios/` (+ копия `trientes/scenarios/`)
`main/Trientes/*`	`trientes/scenarios/*`
`main/CryptoGateway,MANEX,Acquiring,admin-panel`	`_platform/*` (платформенные модули — общие; не дублировать по проектам)
`main/gexpay, Taler, acq`	соответствующие проекты `gexpay/`, … (разнести командой)
прочее в `docs/wiki/`	сырьё — разнести по структуре или удалить

Соглашения¶

Пути — латиница kebab-case, без пробелов/кириллицы (URL MkDocs, кроссплатформенный git).
В каждой папке — index.md (не _index.md). Русские заголовки — во front-matter title: / # H1.
Шаблон нового проекта — docs/projects/_TEMPLATE/ (копируется в <project>/).
Источник истины контента: код сервисов (CREL/*, services/*) → admin_panel/docs/ → выгрузка docs/wiki/.

Машинный доступ из админ-панели (раздел «Документация»)¶

На сборке генерируется manifest.json на проект (дерево {title,path,category,children}) + manifest.index.json (реестр проектов). Генератор: MkDocs-hook material/overrides/hooks/manifests.py → пишет в site/projects/<slug>/manifest.json и site/projects/manifest.index.json. Админка строит навигацию из манифеста (нативно, без внешних CDN), тело документа — встраивает с приватного wiki-домена (origin-проверка, как DrawioEditor) либо проксирует через admin-api.
Базовый URL/слаг/путь манифеста — в service_connect.data.docs per-project (платформенное правило: не env/не хардкод):
```
"docs": { "base_url": "https://wiki.gsmsoft.eu", "project_slug": "teslapay", "manifest_path": "/projects/teslapay/manifest.json" }
```
Гейт правом (новое projectDocsView). Полный контракт для команды админки — docs/team/admin-integration.md.

Автоматизация «новый проект → папка документации»¶

Админка при POST /project/v1 дополняет service_connect.data.docs (slug/manifest_path) — обязательный шаг.
Скелет папки: CI-джоба scaffold в common_docs копирует _TEMPLATE → <slug>/, подставляет название, добавляет в manifest.index.json, открывает MR (запуск вручную командой Wiki или GitLab pipeline-trigger из admin-api). Рантайм-запись сервиса в git не делаем.

Границы (финтех)¶

Приватность wiki: закрыть авторизацией (reverse-proxy/forward-auth) перед публикацией для встраивания; для прод-сборки убрать Google Analytics и внешние шрифты из mkdocs.yml (нарушают «без внешних CDN»).
CSP: узкий frame-src на один доверенный wiki-origin (или проксирование HTML через admin-api без расширения CSP).
PII/код/секреты — не в LLM, не в документацию/тест-данные (только синтетика).

Текущее состояние (на момент спецификации)¶

Создано: _shared/{database,scheme,techanaliz,techdoc}, projects/teslapay/scenarios, projects/trientes/scenarios (+копия TeslaPay), _TEMPLATE.
Осталось команде Wiki: доменная раскладка L3, наполнение business-analytics/system-analytics/tech-info (из кода+admin_panel/docs), разнесение _platform и прочих проектов из docs/wiki/, манифесты, scaffold-джоба, чистка docs/wiki/ после переноса.