ShariX Open Docs

Эта страница только для чтения. Вы можете посмотреть её исходный текст, но не можете его изменить. Сообщите администратору, если считаете, что это неправильно.
<sharix-knowledge-meta>
{
    "id": "ShariXKnowledgeOpenKnowledgePublishingPackageformats",
    "page": "sharixopen:knowledge:publishing:package_formats",
    "area": "open",
    "type": "reference",
    "title": "Формат пакета и публикация ShariX Knowledge",
    "status": "review",
    "schema_version": 1,
    "relations": {
        "related_to": [
            "ShariXKnowledgeHub",
            "ShariXKnowledgeOpenKnowledgePublishingRoutingandreview",
            "ShariXKnowledgeOpenKnowledgeArchitectureSecurityboundaries",
            "ShariXKnowledgeStandards"
        ]
    },
    "extensions": {
        "taxonomy": {
            "domain": "reference",
            "lifecycle": "unspecified",
            "parents": [
                "ShariXKnowledgeOpenKnowledgeStart"
            ],
            "terms": []
        },
        "glossary": []
    },
    "content_sha256": "e2aed994a97ea595317c9a07d2a166f032b5dc407a59b0295dfe0aa88a3e8d20",
    "schema": 1
}
</sharix-knowledge-meta>
====== Формат ZIP и обновление ShariX Knowledge ======
~~NOCACHE~~

**Родительский раздел:** [[sharixopen:knowledge:start|База знаний ShariX Open]]. Эта статья — каноническая инструкция для генераторов архивов публикации.

===== Структура публикационного ZIP =====
Единый канонический формат для ''previewPackage'' / ''publishPackage'' — ''sharix.knowledge.bundle'' версии 1. В корне ZIP **только** файл манифеста и перечисленные в нём документы:

<code>
manifest.json
documents/ShariXKnowledgeZipContractExample.txt
</code>

Не класть в архив README, вложенные ZIP, папку с именем выпуска, файлы ОС или запись каталога ''documents/''. ''documents/<id>.txt'' — текст в UTF-8, имя файла точно совпадает с ''path'' и ''id'' в манифесте. ''sha256'' вычисляется по байтам текста. Это **проверка целостности при передаче**, не контроль существующей редакции Wiki.

Пример ''manifest.json'' для примера страницы ниже:
<code json>
{
  "format": "sharix.knowledge.bundle",
  "version": 1,
  "documents": [
    {
      "id": "ShariXKnowledgeZipContractExample",
      "page": "sharixopen:knowledge:examples:zip_contract_example",
      "area": "open",
      "type": "verification",
      "title": "Проверка пакета ShariX Knowledge",
      "status": "review",
      "schema_version": 1,
      "relations": {},
      "extensions": {},
      "path": "documents/ShariXKnowledgeZipContractExample.txt",
      "sha256": "987a979e8e2a0c5655cbf44b25c64c688eb49cb3d82e60112a5824d207104547"
    }
  ]
}
</code>

Содержимое ''documents/ShariXKnowledgeZipContractExample.txt'':
<code>
====== Проверка пакета ShariX Knowledge ======
~~NOCACHE~~

Статья для проверки структуры публикационного ZIP.
</code>

Значения: ''page'' — постоянный адрес DokuWiki; ''area'' — ''open'', ''platform'' либо ''joint''; ''id'' — синтаксически корректный ID входного пакета, который плагин согласует с существующим ID страницы; ''type'' — ''policy'', ''architecture'', ''decision'', ''contract'', ''component'', ''procedure'', ''requirement'', ''verification'' либо ''reference''; ''status'' — ''draft'', ''review'', ''approved'', ''deprecated''; ''schema_version'' равен 1. Связи ''relations'' — массивы ID документов, ''extensions.taxonomy.parents'' — ID родительских документов. Не придумывать несуществующие ID связанных страниц.

Для обычного создания или обновления ''base_sha256'' **не требуется**. Плагин определяет существование страницы по ''page'' независимо от старых JSON-файлов, сохраняет её собственный ID, перезаписывает через штатный API DokuWiki и ведёт историю редакций.

===== Метаданные в исходнике страницы =====
Плагин сам добавляет в начало DokuWiki-страницы скрытый блок. Генератор ZIP не должен дублировать его вручную в тексте статьи. Пример структуры блока, которую можно увидеть в исходнике страницы:
<code>
<sharix-knowledge-meta>
{
  "schema": 1,
  "id": "ShariXKnowledgeOpenArchitectureStart",
  "page": "sharixopen:knowledge:architecture:start",
  "area": "open",
  "type": "architecture",
  "title": "Архитектура ShariX Open",
  "status": "approved",
  "schema_version": 1,
  "relations": {"related_to": ["ShariXKnowledgeOpenKnowledgeModulesStart"]},
  "extensions": {"taxonomy": {"domain": "architecture", "parents": [], "terms": []}}
}
</sharix-knowledge-meta>
</code>
Блок должен находиться **самым первым** в DokuWiki-источнике. Плагин не отображает его читателю; он является частью сохраняемых версий страницы. При экспорте сведения о страницах без блока выводятся из содержимого и адреса, после следующей публикации блок появляется автоматически.

===== Два входных варианта для Platform =====
Django-модуль ShariX Knowledge принимает описанный канонический ZIP и может принимать упрощённый архив с путями ''open/...txt'', ''platform/...txt'', ''joint/...txt''. Папочный формат — только входной вариант Django: перед запросом DokuWiki он преобразуется в канонический ''manifest.json'' + ''documents/''. Не отправлять папочный формат непосредственно в API DokuWiki.

Через маршрутизатор Platform допустимо объединять области ''open'', ''platform'' и ''joint'' в одном **каноническом** ZIP: Platform разделяет его по целевой wiki. Если пакет отправляется напрямую в DokuWiki, допускаются только области соответствующей установки: ''open'' — публичная, ''platform'' и ''joint'' — внутренняя.

По умолчанию максимум **100 документов на ZIP**. Допускаются последовательные ZIP для одной Wiki (например, 100 + 13), без переименования адресов. Проверка архивов должна учитывать ограничение в 100 и точные контрольные суммы.

===== Правила обновления =====
Документацию составлять и обновлять **по актуальным изменениям исходного кода**, а не по выгрузке старого текста Wiki. Сохранять полезные факты, дополнять и корректировать существующие статьи, не создавать дубли ради номеров версий. Авторы и генераторы не обязаны получать SHA текущих страниц из DokuWiki.

Обычная замена существующей страницы публикуется после общего просмотра изменений; DokuWiki хранит историю. Сходство с другой страницей **по иному адресу** должно быть показано как выбор: объединить, перенести или создать отдельно. Удаление — отдельная явная операция ''operation=delete'' с ''delete_confirmation'' и проверкой ''AUTH_DELETE''; отсутствие файла в новом ZIP не удаляет страницу. Конфликтные страницы можно пропустить и опубликовать остальные. При просмотре различий показывать цветной построчный diff.

Каждая содержательная страница должна иметь ''~~NOCACHE~~'', понятную структуру, wiki-ссылку к родительской странице и ''~~SHARIX_KNOWLEDGE_RELATED~~''. Стартовые страницы разделов дополнительно содержат явное меню ссылок, ''~~SHARIX_KNOWLEDGE_GRAPH~~'' и ''~~SHARIX_KNOWLEDGE_CATALOG~~''. Ссылки на страницы должны соответствовать реально существующим адресам и типизированным связям.

===== Смежные правила =====
  * [[sharixopen:knowledge:publishing:bundle_v1|Пакет v1 и проверка содержимого]]
  * [[sharixopen:knowledge:publishing:routing_and_review|Open / Platform / Joint: маршруты и проверка]]
  * [[sharixopen:knowledge:standards:bundles|Состав пакета и приёмка]]

~~SHARIX_KNOWLEDGE_RELATED~~