Управление различными документами на сайте

Допустим, нам необходимо разместить на сайте и/или в мобильном приложении Пользовательское соглашение и Политику обработки персональных данных. Их содержимое определяется юристами, согласовывается с руководством, и попадает на сайт с помощью технических специалистов. Зачастую, работа над такими документами ведётся в ручном режиме: сами документы формируются в .doc или .odt файлах, хранятся на сетевом или облачном диске, пересылаются друг-другу по электронной почте, либо работа ведётся в онлайн редакторе. После согласования финальная версия передаётся технической команде, которая конвертирует документ в PDF, HTML или сохраняет контент в БД, для обработки бэк-эндом системы. Проблемы, которые возникают при подобном процессе:

Решением этих проблем является система, которая позволяет редактировать документы, вести контроль версий, согласовывать их, публиковать, обеспечивает выкладку на различные экземпляры системы (тест/прод), позволяет откатываться.

Рассмотрим, как организовать такой процесс с помощью системы Az Doc.

  1. Для начала необходимо зарегистрировать аккаунт организации на главной странице https://azdoc.online/
    Теперь у нас есть аккаунт организации, в котором будут храниться необходимые документы. Пользователь данного аккаунта имеет роль admin. После создания аккаунта Вам на почту придёт письмо со ссылкой для подтверждения адреса e-mail, не забудьте перейти по ссылке, иначе, через 24 часа аккаунт будет заблокирован.
  2. Добавим пользователей, которые будут иметь возможность редактировать, согласовывать и публиковать эти документы. Предположим, что мы добавляем следующих пользователей:
    - Фёдор Плевако (юрист) - права уровня "Создание и редактирование документов"
    - Софья Ковалевская (руководитель юридической службы) - права уровня "Создание и редактирование документов"
    - Семён Дежнёв (инженер по тестированию) - права уровня "Чтение документов"
    - Иван Павлов (руководитель проекта) - права уровня "Чтение документов"
    - Дмитрий Менделеев (операционный директор) - права уровня "Чтение документов"
  3. В Настройках создадим стадии публикации. Предполагаем, что наша инфраструктура включает три среды: тестовую, пред-прод и прод.
    • Название "Test", Порядок "1", Разрешить автоматическую публикацию "Да". В качестве согласующего укажем Софью Ковалевскую. Публикующих не указываем.
    • Название "Pred-prod", Порядок "2", Разрешить автоматическую публикацию "Нет". В качестве согласующего укажем Семёна Дежнёва, в качестве публикующего - Ивана Павлова.
    • Название "Prod", Порядок "3", Разрешить автоматическую публикацию "Да". В качестве согласующих укажем Софью Ковалевскую и Ивана Павлова, в качестве публикующего - Дмитрия Менделеева.
    В вашем реальном проекте список и названия стадий могут отличаться, например, можно создать две стадии Dev и Prod. Единственное ограничение - названия должны быть на латинице, т.к. они используются для формирования ссылок.
  4. В Az Doc все документы хранятся в папках, поэтому, прежде чем создать документы, нужно создать папку, назовём её, например, "Соглашения". Папки, так же как и документы, создаются в разделе Документы
  5. Создадим необходимые документы: "Пользовательское соглашение" и "Политика обработки персональных данных". При создании укажем тип документа HTML, т.к. предполагаем отображать его на сайте.
  6. Внесём какие-нибудь правки в документ и сохраним его, чтобы у нас была история версий для наглядности.
  7. Перейдём на страницу "Версии", в списке версий выберем ту, которую нужно опубликовать и нажмём кнопку "Отправить на публикацию". При этом должен смениться статус версии на Публикуется. И в списке стадий публикации стадия Test должна стать активной.
  8. Авторизуемся под Софьей Ковалевской (руководитель юридической службы), которая указана в качестве согласующего для стадии Test. Откроем документ, перейдём в список версий и согласуем публикацию нужной версии.
  9. Т.к. в настройках была указана автоматическая публикация, то сразу после согласования данная версия документа будет опубликована на стадии Test и доступна по ссылке https://azdoc.online/doc/{id}/content/stage/{stageName}
  10. В конфигурационном файле вашего приложения необходимо настроить значение {stageName}, если вы планируете конструировать ссылки динамически, либо настроить полную ссылку на конкретный документ. Например: https://azdoc.online/doc/cabeecb1-0e04-47f3-9eeb-cc84f44985dd/content/stage/Test
  11. Теперь авторизуемся под Семёном Дежнёвым (инженером по тестированию), предполагаем, что он протестировал на тестовом сервере весь функционал, связанный с документом, и теперь документ может быть допущен к публикации на следдующем этапе, в нашем случае, на Pred-prod. Для Семёну нужно перейти в список версий, выбрать нужную версию, выбрать стадию и согласовать.
  12. Теперь авторизуемся под Семёном Дежнёвым (инженером по тестированию), предполагаем, что он протестировал на тестовом сервере весь функционал, связанный с документом, и теперь документ может быть допущен к публикации на следдующем этапе, в нашем случае, на Pred-prod. Для Семёну нужно перейти в список версий, выбрать нужную версию, выбрать стадию и согласовать.
  13. По окончании тестирования (и, возможно других работ на проекте), руководитель проекта Иван Павлов принимает решение, что ноавя версия продукта готова к релизу и запускает процесс выкладки на Pred-prod сервере. В т.ч. ему необходимо выложить документ. Для этого ему нужно авторизоваться в нашей системе, перейти в список версий, выбрать нужную версию, выбрать стадию и опубликовать. Теперь документ доступен на pred-prod сервере.
  14. На pred-prod сервере руководитель проекта Иван Павлов и руководитель юридической службы Софья Ковалевская, проверяют доукумент ещё раз, и согласовывают на публикацию на Prod.
  15. Предполагаем, что в нашей организации за публикацию юридически значимых документов на сайте организации отвечает операционный директор Дмитрий Менделеев. Получив все согласования (и не ранее), он может войти в систему и опубликовать нужную версию на Prod сервере.

Управление различными документами на сайте (АПИ)

Допустим, нам необходимо разместить на сайте и/или в приложении Оферту для пользователей. Зачастую проблема с подобными документами в том, что их содержимое определяется руководством компании или юристами, и не всегда оперативно и последовательно эти изменения попадают на сайт. Процесс ещё более осложняется, если эти изменения должны согласовываться внутри компании.

Всё взаимодействие с AZ doc осуществляется посредством АПИ. Ниже описан процесс взаимодействия.

  1. Создаём аккаунт нашей организации:
    POST https://azdoc.online/api/register
    Content-Type: application/json

    {"username":"company@company.ru", "password":"abc123", "password2":"abc123"}

    Ответ:
    {
        "status": "Sucess", 
        "message": "Registered sucessfully."
    }

    Теперь у нас есть аккаунт организации, в котором будут храниться необходимые документы. Пользователь данного аккаунта имеет роль admin. После создания аккаунта Вам на почту придёт письмо со ссылкой для подтверждения адреса e-mail, не забудьте перейти по ссылке, иначе, через 24 часа аккаунт будет заблокирован.
  2. Авторизуемся:
    POST https://azdoc.online/api/login
    Content-Type: application/json

    {"username":"company@company.ru", "password":"abc123"}

    Ответ:
    {
        "access_token": "sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C",
        "expires_on": 1621318069333,
        "refresh_token": "pNtxHZ3lUvhwPkKqjw4RlkotPyhtiE4kdCMzBENf6YjnDfPlXk"
    }

    В ответе мы получили access token и refresh token, которые будем использовать для аутентификации запросов. Время жизни access токена 30 минут, после этого его нужно обновлять.
  3. Добавляем пользователей, которые будут редактировать документ (обратите внимание на заголовок Authorization, в котором указан access token, полученный ранее):
    POST https://azdoc.online/api/user/add
    Content-Type: application/json
    Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

    {"username":"manager@company.ru", "group":"author"}

    Ответ:
    {
        "status": "Success",
        "message": "Created sucessfully.",
        "id": "ffe8df10-06cd-43b1-95da-739fa806a9d4"
    }

    В ответе мы получили id нового пользователя.
  4. Авторизованные пользователи с ролью admin или author могут добавлять и редактировать документы. Все документы хранятся в папках. Необходимо создать минимум одну корневую папку: POST https://azdoc.online/api/folder/add
    Content-Type: application/json
    Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

    {"name":"Все документы"}

    Ответ:
    {
        "status": "Success",
        "message": "Created sucessfully.",
        "id": "f3386450-ed39-47fe-a0ea-05f876dc817b"
    }

    В ответе мы получили id новой папки.
  5. Добавим документ в эту папку:
    POST https://azdoc.online/api/doc/add
    Content-Type: application/json
    Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

    { "title": "Оферта", "status": 0, "type": "html", "body": "текст оферты в html формате", "folderId":"f3386450-ed39-47fe-a0ea-05f876dc817b" }
    где:
    status - 0 или 1. 0 - черновик (значение по умолчанию), 1 - опубликованный документ;
    type - тип документа, может быть любой;
    body - тело документа в любом формате (plain text, json, markdown, html).

    Ответ:
    {
        "status": "Success",
        "message": "Created sucessfully.",
        "id": "f7a817af-2b50-404e-a63f-771ee31be27a"
    }
    

    В ответе мы получили id нового документа.
  6. Пока документ находится в статусе 0 (черновик), он не будет доступен неавторизованным пользователям. Для изменения статуса используется АПИ doc/edit:
    POST https://azdoc.online/api/user/edit
    Content-Type: application/json
    Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

    {"id":"f7a817af-2b50-404e-a63f-771ee31be27a", "status": 1}

    Ответ:
    {
        "status": "Sucess",
        "message": "Updated sucessfully."
    }
    

    При обновлении документа старая версия будет сохранена в БД, и её всегда можно будет получить по АПИ (см. ниже).
  7. Теперь этот документ доступен по ссылке, которую можно использовать на сайте:
    GET https://azdoc.online/api/public/doc/{id}
  8. АПИ doc/edit также используется для редактирвания документа:
    POST https://azdoc.online/api/doc/edit
    Content-Type: application/json
    Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

    {"id":"f7a817af-2b50-404e-a63f-771ee31be27a", "title": "Оферта для пользователей", "type": "html", "body": "текст №2 оферты в html формате"}

    Ответ:
    {
        "status": "Sucess",
        "message": "Updated sucessfully."
    }
    

    Т.к. поле "status" в вызове АПИ отсутствует, то по умолчанию оно равно "0", т.е. новая версия будет сохранена в статусе "черновик", и по публичной ссылке /api/public/doc/{id} будет доступна предыдущая, наиболее высокая версия со статусом "опубликовано". Чтобы новая версия стала доступна по публичной ссылке, необходимо изменить status на 1, как показано в примере выше, либо при редактировании документа сразу указывать "status":1.
  9. Вы можете получить список версий документа и откатиться к старой версии. Для отката необходимо: получить список версий (doc/{id}/versions), получить контент нужной версии (doc/{id}/version/{number}), сохранить документ (doc/edit), заполнив нужные поля (как правило, title и body) значениями, взятыми из той версии, на которую откатываетесь. Подробное описание АПИ можно посмотреть в документации.

Хранение документов для корпоративной системы управления знаниями

Допустим, нам необходимо создать систему для накопления знаниями в компании. Привычным способом хранения документов является структура вложенных папок, при этом, желательно, чтобы можно было определять порядок следования (сортировку) подпапок и документов. Именно этот подход и реализует AZ doc.

Всё взаимодействие с AZ doc осуществляется посредством АПИ. Процесс взаимодействия по большей части идентичен процессу описанному выше в разделе "Управление различными документами на сайте". Сейчас мы рассмотрим работу со структурой папок и документов.

  1. Все документы хранятся в папках, т.е. в каждой учётной записи необходимо иметь как минимум одну корневую папку. Максимальное количество корневых папок не ограничено. Создадим корневую папку:
    POST https://azdoc.online/api/folder/add
    Content-Type: application/json
    Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

    {"name":"Отдел маркетинга"}

    Ответ:
    {
        "status": "Success",
        "message": "Created sucessfully.",
        "id": "f3386450-ed39-47fe-a0ea-05f876dc817b"
    }

    В ответе мы получили id новой папки.
  2. При создании последующих корневых папок, при необходимости мы можем указывать порядок сортировки папок. Для этого при созднии используется параметр order:
    POST https://azdoc.online/api/folder/add
    Content-Type: application/json
    Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

    {"name":"Отдел ИТ", "order":"0"}

    Ответ:
    {
        "status": "Success",
        "message": "Created sucessfully.",
        "id": "df8f5f89-b93a-4b71-a5ee-2340ecc387e5"
    }

    В ответе мы получили id новой папки. Поскольку order был указан равным 0, то система пересчитала порядок сортировки для остальных папок.
  3. Попробуем получить список папок:
    GET https://azdoc.online/api/folder/list
    Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

    Ответ:
    [
        {
            "id": "df8f5f89-b93a-4b71-a5ee-2340ecc387e5",
            "name": "Отдел ИТ",
            "order": 0,
            "parentId": null
        },
        {
            "id": "f3386450-ed39-47fe-a0ea-05f876dc817b",
            "name": "Отдел маркетинга",
            "order": 1,
            "parentId": null
        }
    ]

    В ответе мы получили список папок. Обратите внимание на порядок папок в списке.
  4. Создадим вложенные папки внутри раздела "Отдел ИТ":
    POST https://azdoc.online/api/folder/add
    Content-Type: application/json
    Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

    {"name":"Документация", "parentId": "df8f5f89-b93a-4b71-a5ee-2340ecc387e5", "order":"0"}

    И ещё одну:
    POST https://azdoc.online/api/folder/add
    Content-Type: application/json
    Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

    {"name":"Список сотрудников", "parentId": "df8f5f89-b93a-4b71-a5ee-2340ecc387e5", "order":"1"}

    Посмотрим на список папок теперь:
    GET https://azdoc.online/api/folder/list
    Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

    Ответ:
    [
        {
            "id": "df8f5f89-b93a-4b71-a5ee-2340ecc387e5",
            "name": "Отдел ИТ",
            "order": 0,
            "parentId": null,
            "children": [
                {
                    "id": "347b7fe2-0eab-40c5-b1c1-06f73fdeccad",
                    "name": "Документация",
                    "order": 0,
                    "parentId": "df8f5f89-b93a-4b71-a5ee-2340ecc387e5"
                },
                {
                    "id": "d8f614ac-b74c-4da9-9be3-a0facbd23a6f",
                    "name": "Список сотрудников",
                    "order": 1,
                    "parentId": "df8f5f89-b93a-4b71-a5ee-2340ecc387e5"
                }
            ]
        },
        {
            "id": "f3386450-ed39-47fe-a0ea-05f876dc817b",
            "name": "Отдел маркетинга",
            "order": 1,
            "parentId": null
        }
    ]

    Аналогично можно создавать вложенные папки внутри подпапок, количество уровней вложенности неограничено. Чтобы изменить порядок сортировки папок достаточно изменить order у одной папки, указав ей желаемую позицию, для остальных папок order будет пересчитал автоматически.
  5. Добавим документ в корневую папку "Отдел ИТ" и ещё один в под-папку "Документация". Пример добавления в корневую папку:
    POST https://azdoc.online/api/doc/add
    Content-Type: application/json
    Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

    {"folderId":"df8f5f89-b93a-4b71-a5ee-2340ecc387e5", "title":"Описание структуры отдела", "status":0, "type": "Markdown", "body": "текст оферты в markdown формате", "order":0}

    Ответ:
    {
        "status": "Success",
        "message": "Created sucessfully.",
        "id": "a9506e6f-b519-4768-a1c1-4ed01f5c3282"
    }

    В ответе мы получили id нового документа. Документ в подпапке создаётся аналогично, нужно просто указать соответствующий id подпапки.
  6. Посмотрим на список документов:
    GET https://azdoc.online/api/doc/list
    Authorization: Bearer sTw8eMjmsotUTVsqmnq2beU818eOzQcEkSvlca3dHKDVxtXH4C

    Ответ:
    [
        {
            "id": "a9506e6f-b519-4768-a1c1-4ed01f5c3282",
            "title": "Описание структуры отдела",
            "order": 1,
            "active": true,
            "FolderId": "df8f5f89-b93a-4b71-a5ee-2340ecc387e5"
        },
        {
            "id": "9ebd51b0-d05b-44d9-bbae-8d9c9333218b",
            "title": "Протокол интеграции",
            "order": 0,
            "active": true,
            "FolderId": "347b7fe2-0eab-40c5-b1c1-06f73fdeccad"
        }
    ]

    Как было показано в пирмере выше, есть АПИ для получения документа по его id. Каждый документ может быть, как в статусе черновика, так и опубликован.