---

🎯 Позиционирование

Wiki — self-hosted knowledge base платформы PDLC для FerrPOINT: spaces, documents, revisions, task dossiers, workflow phases, evidence, attachments, search и audit.

Репозиторий сокращён до Wiki MVP runtime: public API/OpenAPI, CLI surface, frontend shell и SQLx/PostgreSQL persistence. Скопированные task-tracker backend-модули и старые зависимости удалены из активного workspace.

📌 Snapshot

Поле	Значение
Статус	MVP baseline: Wiki API/OpenAPI, CLI surface, frontend shell и SQLx persistence на месте
Backend	Rust 2024, Axum, SQLx runtime persistence
Data	PostgreSQL 17 и filesystem attachment storage
Frontend	React 19, Vite, Tailwind CSS
API	Canonical Wiki MVP contract: openapi/openapi.json
Порты	repository-local: frontend 19877, backend 3456, PostgreSQL 3457; Base umbrella: frontend 7732, API 7731, PostgreSQL loopback 7733
License	FerrPOINT Proprietary Source-Available Evaluation License v1.0

✨ Возможности

Feature	Описание
Spaces and documents	Spaces и document tree для requirements, architecture notes, decisions и release materials.
Document lifecycle	Create/view/edit/publish/archive/move flows, revision-aware backend endpoints и generated frontend API types.
Base dossiers	Task и phase dossiers, связанные с evidence и workflow context.
Evidence registry	External links и uploaded files, прикреплённые к documents, tasks или phases.
Operations	Templates, audit log, users/settings/admin pages, global search и API health/readiness probes.
CLI	HTTP-only wiki binary для тех же public API операций, что и UI.
Documentation	Architecture, operations, threat model, traceability и visual screenshot evidence.

🔧 Стек

Zone	Tech	Роль
API	Rust + Axum	Wiki MVP routes и public API
Persistence	SQLx + PostgreSQL	runtime data и migrations
Attachment storage	local filesystem	uploaded evidence files
Frontend	React + Vite + Tailwind	Wiki shell и API-backed MVP pages
Contract	OpenAPI	generated frontend types
Docs	contracts, security, traceability	source of truth для scope

⚡ Быстрый старт

cp .env.example .env
# Заменить [CHANGE_ME] значения и задать WIKI_BOOTSTRAP__ADMIN_EMAIL/PASSWORD
docker compose up --build -d
curl -fsS http://127.0.0.1:3456/api/v1/health
curl -fsS http://127.0.0.1:3456/api/v1/health/ready

Frontend dev:

Workspace helper задаёт собственные VITE_AUTH_ISSUER, VITE_AUTH_CLIENT_ID и VITE_API_BASE_URL. Callback клиента Auth должен соответствовать Dev origin; без настройки client ID сохраняется wiki. См. Local Setup.

cd frontend
pnpm install
pnpm dev

PostgreSQL API smoke (disposable test DB + env-gated wiki_postgres_ API tests, включая persistence, membership revocation и FTS index-plan evidence):

pwsh -File scripts/postgres-smoke.ps1

Если Docker Desktop недоступен, но в WSL есть локальный PostgreSQL — тот же smoke против изолированной временной БД:

pwsh -File scripts/postgres-smoke-wsl.ps1

Backup/restore drill на том же Windows/WSL fallback-пути:

pwsh -File scripts/backup-restore-smoke-wsl.ps1

🧭 Фронтенд-роуты

Route	Назначение
/login, /register	Auth
/	Dashboard
/spaces, /documents/new, /documents/:documentId	Spaces и documents
/tasks, /tasks/:taskKey	Task dossiers
/phases, /phases/:phaseId	Workflow phase dossiers
/evidence, /templates, /audit-log	Evidence и operations
/users, /settings, /admin	Administration
/search	Global search

Операционные probe /api/v1/health и /api/v1/health/ready — API-only, без frontend-скриншотов.

🖼️ Визуальные доказательства

Скриншоты — реальные страницы продукта при 1920x1080 в default theme. Полный реестр маршрутов и параметры responsive QA, включая 375px, хранятся в manifest.

Общий Header принят отдельным live-прогоном 2026-10-01. Текущий пример при 1920 px и default dark theme:

Параметры образа, проверки и mobile/wide evidence находятся в Header evidence. Три примера ниже - предыдущий snapshot страниц до интеграции общего Header; они не являются доказательством его текущей геометрии.

Дашборд (wide)

Создание документа (reading/form)

Карточка task-досье (detail-with-aside)

Остальные маршруты и снимки адаптивной проверки перечислены в визуальном manifest.

🖥️ CLI

cd backend
cargo build --bin wiki

export WIKI_API_URL=http://localhost:3456/api/v1
export WIKI_TOKEN=<jwt_token>

./target/debug/wiki space list
./target/debug/wiki user list
./target/debug/wiki doc create --space BASE --title "Requirements" --from-file requirements.md
./target/debug/wiki space member-set BASE --user <user-id> --role editor
./target/debug/wiki attachment download <attachment-id> --out artifact.bin
./target/debug/wiki audit list --limit 25
./target/debug/wiki settings get

🏗️ Архитектура

flowchart TD
    UI[React Wiki shell] --> API[Axum Wiki API]
    CLI[wiki CLI] --> API
    API --> Services[Wiki application services]
    Services --> Store[SQLx persistence]
    Store --> DB[(PostgreSQL)]
    Services --> Evidence[Evidence + audit]
    OpenAPI[OpenAPI contract] --> Gen[Generated frontend types]
    API --> OpenAPI

Loading

🧱 Границы

• Текущий baseline — API-backed MVP, не готовая enterprise knowledge platform.
• Reports, notifications, webhooks, import/export bundles, OCR и real-time collaboration отложены.
• Перед shared deployments замените все [CHANGE_ME], задайте WIKI_ENVIRONMENT=production, WIKI_JWT_SECRET, bootstrap-admin credentials и проверьте CORS/cookie/TLS.
• Опубликованный Markdown рендерится в sanitized HTML; имена и storage-ключи вложений валидируются.
• Production startup отклоняет слабую auth-конфигурацию, wildcard/non-HTTPS CORS, insecure refresh cookies и пустой database URL.

Полный current-state срез: docs/CURRENT_STATE.md.

🛡️ Качество и проверки

Проверка	Команда
README contract tests	python3 -m unittest scripts.tests.test_verify_readme -v
README assets и anchors	python3 scripts/verify_readme.py
Backend	cd backend && cargo fmt --all -- --check && cargo clippy --workspace --all-targets -- -D warnings && cargo test --workspace -- --test-threads=1
Frontend	cd frontend && pnpm openapi:check && pnpm typecheck && pnpm test -- --run && pnpm lint && pnpm build
Browser route smoke	cd frontend && pnpm test:e2e -- --project=chromium
Compose contract	docker compose config -q
Runtime probes	curl -fsS http://127.0.0.1:3456/api/v1/health и .../health/ready

GitHub Actions прогоняет docs-гейт, backend fmt/clippy/tests, OpenAPI drift и frontend gates; тяжёлые проверки (coverage, dependency-audit, browser E2E) выполняются локально по необходимости.

Архивирование сохраняет клавиатурный контекст: после успеха фокус возвращается на строку пространства или заголовок документа, после отмены — на кнопку действия. Решение и регрессии описаны в плане проверки.

🗂️ Карта проекта

wiki/
├── backend/     # Rust workspace: public Wiki API, SQLx persistence, CLI
├── frontend/    # React/Vite Wiki shell и API-backed MVP pages
├── cli/         # helper skill notes
├── docs/        # requirements, architecture, contracts, operations, quality
├── openapi/     # Wiki MVP API artifact
├── scripts/     # helper scripts
└── docker-compose.yml

📚 Документы

Общий UI и управляемый брендинг Base.

• docs/USER_GUIDE.md — пользовательские сценарии.
• docs/MVP_READINESS.md — 100% readiness gate перед main development.
• docs/DEVELOPMENT_GUIDE.md — разработка.
• docs/OPERATIONS.md, docs/TROUBLESHOOTING.md — эксплуатация.
• docs/SECURITY.md, docs/THREAT_MODEL.md — безопасность.
• docs/ARCHITECTURE_INDEX.md, docs/ARCHITECTURE.md, docs/contracts — архитектура и контракты.
• docs/API.md, docs/DATA_MODEL.md, docs/ENV.md, docs/CLI.md — справочники.
• Служебное чтение аналитиком — reader, проектные права, версии, вложения и отдельная приёмка без Workflow/Fleet.
• docs/TEST_PLAN.md, docs/TRACEABILITY.md, docs/RISK_REGISTER.md — качество.

Скриншоты и параметры пересъёмки: docs/assets/screens/manifest.md.

🔒 Лицензия

Proprietary source-available. Not open source. Viewing/evaluation only.

Commercial, production, resale, redistribution, SaaS/hosting use require written license from FerrPOINT. См. LICENSE, NOTICE и THIRD_PARTY_NOTICES.md.

Нормативные термины и зависимости: PDLC и интеграция с Base.

Разработка UI со справочником Base

Порядок для разработчика и ИИ: версия UI → check → поиск/карточка → один пример → интеграция → проверка поведения. Из корня подготовленного React-продукта: pnpm --dir frontend exec pdlc-ui. Полный каталог и запуск Storybook/API для offline-поиска не нужны. Общие компоненты и брендинг исправляются в Base, данные и правила остаются у продукта.

Единое пространство PDLC

Согласованная M:N-модель и план: реализация в работе. Source, tests, миграция, образы и live dev acceptance учитываются раздельно; документация цели не подтверждает установленную политику.

Ручные долгие проверки

Долгие opt-in PostgreSQL/integration и браузерные E2E запускаются только через явный workflow_dispatch существующего CI. В Actions выберите CI, ветку и «Run workflow»; сохранены прежние адресные inputs, если они предусмотрены. Обычные PR/push не запускают эти шаги. Быстрые unit, format, typecheck, lint и build-проверки сохраняют прежние условия. Команды, assertions, зависимости и timeouts долгих сценариев не меняются.

Долгий набор также можно запускать вручную штатными командами проекта. Успешный автоматический CI подтверждает быстрый набор; он не подтверждает пропущенную integration/live/E2E приёмку. Перед относящейся к данным или безопасности поставкой необходимый адресный manual gate остаётся обязательным.

Полный workspace-набор тоже ручной: автоматический backend выполняет короткие SDK/domain unit tests; прежний полный набор сохранён с manual predicate.

Владелец identity references

Private check/freeze/release удерживает durable fences и прежнюю identity-историю; неизвестные bindings не считаются отсутствием ссылок. Настройки WIKI_IDENTITY_DELETION_LEGACY_ISSUER и WIKI_IDENTITY_DELETION_COORDINATOR_SUBJECTS задаются только после операторской проверки deployment; примеры закомментированы в .env.example. См. настройки deployment и контракт. Проверенный отдельный owner не означает приёмку восьми owners, Kubernetes или установленного rollout.