diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 808daa4..25c8187 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -13,8 +13,8 @@ export default defineConfig({ { text: 'Техническое задание', items: [ - { text: '1. Общие положения', link: '/' }, { text: 'Единый документ ТЗ', link: '/' }, + { text: 'Содержание разделов', link: '/tz/' }, ], }, ], diff --git a/docs/index.md b/docs/index.md index 819cfbc..5337977 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,6 +2,10 @@ + + + + @@ -12,6 +16,14 @@ - + - + + + + + + + + + diff --git a/docs/tz/acceptance.md b/docs/tz/acceptance.md index d397d6a..10dd98b 100644 --- a/docs/tz/acceptance.md +++ b/docs/tz/acceptance.md @@ -1,6 +1,6 @@ -# 11. Порядок приемки и состав передаваемых материалов +# 14. Порядок контроля, приемки и гарантийного сопровождения -## 11.1 Общие положения приемки +## 14.1 Общие положения приемки Приемка результата работ должна подтверждать соответствие программного продукта требованиям настоящего технического задания, условиям договора и согласованным требованиям заказчика. @@ -14,9 +14,22 @@ - сопровождение заказов - уведомления - бонусный и реферальный контур -- интеграционный обмен в согласованном объеме +- интеграционный обмен с 1С в согласованном объеме +- пользовательская и эксплуатационная документация в согласованном объеме -## 11.2 Критерии приемки +## 14.2 Виды проверок + +Для контроля результата работ используются следующие виды проверок: + +- функциональная проверка основных пользовательских сценариев +- проверка разграничения ролей и прав доступа +- проверка корректности данных, статусов и истории изменений +- проверка интерфейсов на desktop и mobile +- проверка уведомлений по согласованным каналам +- проверка интеграционного обмена с 1С +- проверка запуска и работы сервисов в согласованном эксплуатационном контуре + +## 14.3 Критерии приемки Программный продукт считается соответствующим требованиям, если: @@ -27,29 +40,25 @@ - цена не отображается клиенту до публикации условий менеджером - менеджер имеет возможность обработать заявку и опубликовать условия - история изменений сохраняется и доступна в предусмотренных сценариях +- сведения из 1С отображаются в согласованном объеме +- текущая задолженность клиента и дата актуальности данных отображаются при наличии этих сведений из 1С +- критичные дефекты, препятствующие выполнению основных сценариев, устранены до передачи результата -## 11.3 Состав передаваемых материалов +## 14.4 Передаваемые материалы -В состав передаваемых заказчику материалов должны входить: +В состав передаваемых заказчику материалов входят: -- исходный код программного продукта -- техническое задание в согласованной редакции -- сведения об используемых сторонних компонентах и их версиях -- описание реализованных интеграций и используемых внешних интерфейсов -- схемы взаимодействия модулей и движения данных -- описание состава пользовательских ролей и прав доступа -- материалы, необходимые для сопровождения и эксплуатации продукта +- программный продукт, размещенный в согласованном эксплуатационном контуре +- исходный код разработанных компонентов в репозитории проекта +- согласованная редакция настоящего технического задания +- пользовательская документация в согласованном объеме +- эксплуатационная документация в согласованном объеме +- интеграционная спецификация 1С, если точные форматы обмена фиксируются отдельно от настоящего технического задания +- перечень ключевых сторонних компонентов, сформированный на основании фактических файлов проекта -## 11.4 Требования к документации +Технические схемы, модель данных, роли, архитектура, стек, состав сервисов и требования к интеграциям являются частью настоящего технического задания и не дублируются в отдельных документах без отдельного согласования сторон. -Передаваемая документация должна позволять: - -- идентифицировать состав реализованных функций -- понять структуру данных и интеграций -- сопровождать клиентский и менеджерский контуры -- использовать систему в рамках согласованных ролей и сценариев - -## 11.5 Порядок фиксации замечаний +## 14.5 Порядок фиксации замечаний Каждое замечание, выявленное при приемке, должно содержать: @@ -59,3 +68,42 @@ - фактический результат - уровень критичности - статус устранения + +Замечания, не препятствующие выполнению основных пользовательских и интеграционных сценариев, могут быть зафиксированы сторонами для последующего устранения в согласованном порядке. + +## 14.6 Гарантийный срок + +Гарантийный срок на разработанные модули, сервисы и дополнительный функционал составляет 6 месяцев с даты подписания акта приемки выполненных работ, если иной порядок не согласован сторонами. + +Гарантия распространяется на дефекты разработанного программного продукта, проявившиеся при штатной эксплуатации и относящиеся к функционалу, реализованному исполнителем. + +## 14.7 Порядок гарантийного обращения + +Гарантийное обращение должно быть передано исполнителю в письменной форме или иным согласованным сторонами способом. + +В обращении должны быть указаны: + +- описание дефекта +- пользовательская роль или контур, в котором проявляется дефект +- шаги воспроизведения +- ожидаемый результат +- фактический результат +- дата и время обнаружения +- дополнительные материалы, если они нужны для диагностики + +Исполнитель выполняет диагностику дефекта и, если дефект относится к гарантийной зоне ответственности, устраняет его без дополнительной оплаты. + +Срок устранения гарантийного дефекта составляет не более 3 дней с даты получения обращения либо иной срок, согласованный сторонами с учетом критичности и характера дефекта. + +## 14.8 Ограничения гарантийного сопровождения + +Гарантийное сопровождение не распространяется на случаи, когда некорректная работа вызвана: + +- самостоятельным изменением программного продукта заказчиком или третьими лицами без согласования с исполнителем +- ошибками сервера, хостинга, инфраструктуры или базы данных, не связанными с разработанным функционалом +- атакой, компрометацией доступа или нарушением требований информационной безопасности со стороны заказчика +- некорректной работой стороннего программного обеспечения +- недоступностью или некорректной работой внешних систем, включая 1С, Telegram, Max, почтовые сервисы и иные внешние API +- изменением форматов или правил работы внешних систем без предварительного согласования и обновления интеграционной спецификации + +Если дефект связан с внешней системой или инфраструктурой, исполнитель фиксирует результат диагностики и передает заказчику сведения, достаточные для дальнейшего устранения причины на стороне соответствующей системы или поставщика. diff --git a/docs/tz/components-libraries.md b/docs/tz/components-libraries.md deleted file mode 100644 index 13088d1..0000000 --- a/docs/tz/components-libraries.md +++ /dev/null @@ -1,125 +0,0 @@ -# 7. Требования к компонентам и библиотекам - -## 7.1 Общая компонентная схема - -Программный продукт реализуется по клиент-серверной модели и включает веб-клиент, сервер бизнес-логики, базу данных, модуль интеграции и вспомогательные сервисы уведомлений. - -![Общая архитектурная схема](/diagrams/architecture-overview.svg) - -## 7.2 Компоненты клиентской части - -Клиентская часть должна быть организована по следующим слоям: - -- страницы `app/pages` -- компоненты `app/components` -- composables `app/composables` -- GraphQL-документы `graphql/operations` -- сгенерированная типизированная схема `app/composables/graphql/generated.ts` -- серверные proxy и интеграционные обработчики `server/api` - -Ключевые экранные маршруты текущей реализации: - -- `/products` и `/products/[slug]` -- `/cart` -- `/client-orders` и `/client-orders/[id]` -- `/clients` и `/clients/[id]` -- `/orders` и `/orders/[id]` -- `/catalog-settings` -- `/bonus-program`, `/bonus-system/*` - -## 7.3 Компоненты серверной части - -Серверная часть должна быть организована по следующим основным модулям: - -- `src/server.js` — инициализация HTTP-сервера и GraphQL-сервера -- `src/schema.graphql` — контракт GraphQL API -- `src/resolvers.js` — реализация GraphQL-операций -- `src/context.js` — построение контекста запроса -- `src/auth.js` — аутентификация и токены доступа -- `src/access.js` — правила авторизации и проверки ролей -- `src/prisma-client.js` — точка подключения Prisma -- `src/messenger*.js`, `src/telegram*.js`, `src/max-mini-app.js` — мессенджерный контур и мини-приложения - -## 7.4 Карта слоев и компонентов - -![Карта слоев и компонентов](/diagrams/component-map.svg) - -## 7.5 Требования к компонентной реализации - -Архитектура программного продукта должна сохранять следующие правила: - -- экранная логика должна находиться на уровне страниц и composables -- переиспользуемые элементы интерфейса должны быть вынесены в отдельные компоненты -- каждый GraphQL-документ должен храниться в отдельном `.graphql` файле -- клиентский код должен использовать сгенерированные типизированные документы -- серверная логика доступа к данным должна проходить через Prisma -- бизнес-правила доступа должны контролироваться серверной частью, а не только интерфейсом - -## 7.6 Требования к библиотекам и стеку - -Клиентская часть реализуется на следующих библиотеках и платформах: - -- `Nuxt 4` -- `Vue 3` -- `@nuxtjs/apollo` -- `@vue/apollo-composable` -- `GraphQL Code Generator` -- `Tailwind CSS` -- `daisyUI` -- `Storybook` -- `VitePress` - -Серверная часть реализуется на следующих библиотеках и платформах: - -- `Node.js` -- `Express 5` -- `Apollo Server 5` -- `Prisma 7` -- `PostgreSQL` -- `Zod` -- `Nodemailer` - -## 7.7 Зафиксированные версии ключевых зависимостей - -### Базовые runtime и контейнерные образы - -| Компонент | Текущая версия | -| --- | --- | -| Node base image для web/backend/bots | `node:22-bookworm-slim` | -| Vault image | `hashicorp/vault:1.21.3` | -| Hatchet Postgres | `postgres:15.6` | -| Nuxt | `4.4.2` | -| Vue | `3.5.30` | -| Apollo Server | `5.5.0` | -| Prisma / Prisma Client | `7.6.0` | -| Mermaid | `11.14.0` | -| VitePress | `1.6.4` | - -### Основные зависимости фронтенда - -| Библиотека | Версия | Назначение | -| --- | --- | --- | -| `@nuxtjs/apollo` | `5.0.0-alpha.16` | GraphQL-клиентский слой | -| `@vue/apollo-composable` | `4.2.2` | composable API для GraphQL | -| `@apollo/client` | `3.14.1` | Apollo client runtime | -| `@nuxt/eslint` | `1.15.2` | linting Nuxt-проекта | -| `@nuxtjs/tailwindcss` | `6.14.0` | Tailwind integration | -| `daisyui` | `5.5.19` | UI primitives | -| `graphql` | `16.13.2` | GraphQL runtime | -| `@sentry/vue` | `10.46.0` | error tracking | -| `storybook` | `8.6.14` | UI component review | - -### Основные зависимости backend - -| Библиотека | Версия | Назначение | -| --- | --- | --- | -| `@apollo/server` | `5.5.0` | GraphQL server | -| `@as-integrations/express5` | `1.1.2` | Apollo + Express integration | -| `express` | `5.2.1` | HTTP server | -| `@prisma/client` | `7.6.0` | data access | -| `@prisma/adapter-pg` | `7.6.0` | Prisma adapter | -| `pg` | `8.20.0` | PostgreSQL driver | -| `graphql` | `16.13.2` | GraphQL runtime | -| `zod` | `4.3.6` | validation | -| `nodemailer` | `8.0.4` | email notifications | -| `dotenv` | `17.3.1` | env bootstrap in local/runtime layers | diff --git a/docs/tz/data-entities.md b/docs/tz/data-entities.md index 49d0914..174f738 100644 --- a/docs/tz/data-entities.md +++ b/docs/tz/data-entities.md @@ -1,6 +1,6 @@ -# 4. Требования к данным и сущностям +# 6. Требования к данным и сущностям -## 4.1 Общие требования к данным +## 6.1 Общие требования к данным Основное хранилище данных программного продукта реализуется на `PostgreSQL`. Прикладной доступ к данным осуществляется через `Prisma ORM`. @@ -18,7 +18,7 @@ В прикладной реализации должны использоваться фактические сущности базы данных, определенные в `schema.prisma`. Наименование сущностей в документации и в базе данных должно сопоставляться однозначно. -## 4.2 Справочник сущностей базы данных +## 6.2 Справочник сущностей базы данных | Модель в базе данных | Русское наименование | Назначение | | --- | --- | --- | @@ -42,7 +42,7 @@ | `BonusTransaction` | Бонусная транзакция | Начисление или списание бонусов | | `RewardWithdrawalRequest` | Заявка на вывод бонусов | Заявка клиента на использование или вывод бонусов | -## 4.3 Служебные перечисления и статусы +## 6.3 Служебные перечисления и статусы В модели данных используются следующие перечисления: @@ -53,9 +53,9 @@ - `OrderStatus`: `NEW`, `MANAGER_PROCESSING`, `WAITING_DOUBLE_CONFIRM`, `CLIENT_REJECTED`, `MANAGER_REJECTED`, `MANAGER_BLOCKED`, `CONFIRMED`, `IN_PROGRESS`, `COMPLETED` - `WithdrawalStatus`: `PENDING`, `APPROVED`, `REJECTED` -## 4.4 Пользователи и компании +## 6.4 Пользователи и компании -### 4.4.1 Company +### 6.4.1 Company Русское наименование: `Компания` @@ -76,7 +76,7 @@ - одна компания связана со многими пользователями -### 4.4.2 User +### 6.4.2 User Русское наименование: `Пользователь` @@ -105,7 +105,7 @@ - пользователь может выступать клиентом или менеджером в заказах - пользователь может иметь бонусные операции и заявки на вывод -### 4.4.3 DeliveryAddress +### 6.4.3 DeliveryAddress Русское наименование: `Адрес доставки` @@ -125,7 +125,7 @@ - `createdAt` - `updatedAt` -### 4.4.4 CounterpartyProfile +### 6.4.4 CounterpartyProfile Русское наименование: `Профиль контрагента` @@ -153,7 +153,7 @@ - `createdAt` - `updatedAt` -### 4.4.5 RegistrationRequest +### 6.4.5 RegistrationRequest Русское наименование: `Заявка на подключение` @@ -175,7 +175,7 @@ - `createdAt` - `updatedAt` -### 4.4.6 Invitation +### 6.4.6 Invitation Русское наименование: `Приглашение` @@ -195,7 +195,7 @@ - `acceptedAt` - `createdAt` -### 4.4.7 MessengerConnection +### 6.4.7 MessengerConnection Русское наименование: `Подключение мессенджера` @@ -216,9 +216,9 @@ - `isActive` - `createdAt` -## 4.5 Каталог и складской контур +## 6.5 Каталог и складской контур -### 4.5.1 Product +### 6.5.1 Product Русское наименование: `Товар` @@ -245,7 +245,7 @@ - `createdAt` - `updatedAt` -### 4.5.2 CatalogProductTypeSetting +### 6.5.2 CatalogProductTypeSetting Русское наименование: `Настройки типа товара` @@ -274,7 +274,7 @@ - `createdAt` - `updatedAt` -### 4.5.3 Warehouse +### 6.5.3 Warehouse Русское наименование: `Склад` @@ -290,7 +290,7 @@ - `createdAt` - `updatedAt` -### 4.5.4 ProductStock +### 6.5.4 ProductStock Русское наименование: `Складской остаток` @@ -306,9 +306,9 @@ - `availableQty` - `updatedAt` -## 4.6 Корзина, заявки и заказы +## 6.6 Корзина, заявки и заказы -### 4.6.1 Cart +### 6.6.1 Cart Русское наименование: `Корзина` @@ -324,7 +324,7 @@ - `createdAt` - `updatedAt` -### 4.6.2 CartItem +### 6.6.2 CartItem Русское наименование: `Позиция корзины` @@ -345,7 +345,7 @@ - `createdAt` - `updatedAt` -### 4.6.3 Order +### 6.6.3 Order Русское наименование: `Заказ / заявка` @@ -380,7 +380,7 @@ - `kind = CALCULATION` означает сценарий расчета индивидуальной продукции - поле `calculationPayload` хранит параметры расчетной заявки -### 4.6.4 OrderItem +### 6.6.4 OrderItem Русское наименование: `Позиция заказа` @@ -398,7 +398,7 @@ - `unitPrice` - `createdAt` -### 4.6.5 OrderStatusEvent +### 6.6.5 OrderStatusEvent Русское наименование: `Событие статуса заказа` @@ -415,9 +415,9 @@ - `note` - `createdAt` -## 4.7 Бонусный и реферальный контур +## 6.7 Бонусный и реферальный контур -### 4.7.1 ReferralLink +### 6.7.1 ReferralLink Русское наименование: `Реферальная связь` @@ -434,7 +434,7 @@ - `bonusPercent` - `createdAt` -### 4.7.2 BonusTransaction +### 6.7.2 BonusTransaction Русское наименование: `Бонусная транзакция` @@ -452,7 +452,7 @@ - `referralLinkId` - `createdAt` -### 4.7.3 RewardWithdrawalRequest +### 6.7.3 RewardWithdrawalRequest Русское наименование: `Заявка на вывод бонусов` @@ -471,7 +471,7 @@ - `createdAt` - `updatedAt` -## 4.8 Основные связи между сущностями +## 6.8 Основные связи между сущностями Укрупненная структура связей определяется следующими правилами: @@ -483,7 +483,7 @@ - настройки параметров по товарному направлению хранятся в `CatalogProductTypeSetting` - реферальные связи реализуются через `ReferralLink`, связывающий одного пользователя с другим пользователем -## 4.9 Структура хранения и модель базы данных +## 6.9 Структура хранения и модель базы данных ![Укрупненная модель базы данных](/diagrams/database-model.svg) diff --git a/docs/tz/data-integrations.md b/docs/tz/data-integrations.md deleted file mode 100644 index f7a6e12..0000000 --- a/docs/tz/data-integrations.md +++ /dev/null @@ -1,175 +0,0 @@ -# 6. Требования к данным и интеграциям - -## 6.1 Основные сущности данных - -Система должна оперировать следующими основными сущностями: - -- пользователь -- роль -- контрагент -- заявка на подключение -- товар -- складской остаток -- корзина -- заявка на заказ -- заявка на расчет -- заказ -- событие изменения статуса -- уведомление -- бонусная связь -- бонусная операция -- заявка на использование либо вывод бонусов - -## 6.2 Обязательные данные по сущностям - -### 6.2.1 Пользователь - -Обязательные данные: - -- идентификатор -- имя -- адрес электронной почты -- телефон -- роль -- статус учетной записи -- связанный контрагент -- подключенные каналы уведомлений - -### 6.2.2 Контрагент - -Обязательные данные: - -- идентификатор -- наименование компании -- ИНН -- КПП -- юридический адрес -- контактные лица -- закрепленный менеджер - -### 6.2.3 Товар - -Обязательные данные: - -- идентификатор -- SKU -- наименование -- тип продукции -- набор параметров -- доступные варианты -- остатки по складам -- признаки доступности и кастомизации - -### 6.2.4 Заявка на заказ - -Обязательные данные: - -- идентификатор -- инициатор -- дата и время создания -- состав позиций -- параметры позиций -- количество -- комментарий клиента -- статус -- закрепленный менеджер -- стоимость после обработки -- условия поставки после обработки - -### 6.2.5 Заявка на расчет - -Обязательные данные: - -- идентификатор -- инициатор -- дата и время создания -- параметры изделия -- комментарий клиента -- статус -- закрепленный менеджер -- стоимость после обработки -- условия поставки после обработки - -### 6.2.6 Заказ - -Обязательные данные: - -- внутренний идентификатор -- внешний идентификатор учетной системы -- статус -- даты изменения -- состав заказа -- стоимость -- условия поставки -- ссылка на исходную клиентскую заявку - -### 6.2.7 Бонусная операция - -Обязательные данные: - -- идентификатор операции -- связанный клиент -- тип операции -- сумма или объем операции -- основание операции -- дата и время операции -- текущий статус операции - -## 6.3 Требования к данным каталога - -Для каждой позиции и для каждого товарного направления система должна хранить и отображать: - -- тип продукции -- доступные параметры выбора -- стандартные значения параметров -- описания параметров -- признаки доступности индивидуальной длины, втулки с логотипом и нанесения надписи -- доступные варианты товара -- остатки по складам -- сведения об актуальности данных - -## 6.4 Требования к интеграции с 1С - -Интеграция с 1С должна обеспечивать обмен данными, необходимыми для сопровождения каталога и заказов. - -Система должна обеспечивать получение из 1С следующих данных: - -- каталог товаров -- характеристики товаров -- складские остатки -- сведения о заказах -- статусы заказов -- изменения состава, стоимости, доставки и иных существенных параметров заказа - -## 6.5 Требования к интеграционному обмену - -Интеграционный слой должен обеспечивать: - -- сопоставление внутренних идентификаторов и идентификаторов 1С -- защиту от дублирования событий -- регистрацию входящих и исходящих операций обмена -- повторную обработку неуспешных сообщений -- хранение истории обновлений по интеграционным операциям - -## 6.6 Требования к журналированию данных - -Для ключевых действий и изменений система должна сохранять: - -- тип объекта -- идентификатор объекта -- предыдущее состояние объекта -- новое состояние объекта -- дату и время изменения -- пользователя либо источник, выполнивший изменение - -## 6.7 Требования к данным бонусного контура - -Для бонусной и реферальной программы система должна хранить: - -- текущий бонусный баланс клиента -- историю начислений -- историю списаний -- историю использования бонусов -- реферальные связи -- заявки на использование либо вывод бонусов -- статусы обработки таких заявок diff --git a/docs/tz/database-model.md b/docs/tz/database-model.md deleted file mode 100644 index 716f43f..0000000 --- a/docs/tz/database-model.md +++ /dev/null @@ -1,167 +0,0 @@ -# 8. Структура данных и модель базы данных - -## 8.1 Общие положения - -Основное хранилище данных программного продукта реализуется на `PostgreSQL`. Прикладной доступ к данным осуществляется через `Prisma ORM`. - -![Укрупненная модель базы данных](/diagrams/database-model.svg) - -Модель данных должна обеспечивать хранение: - -- пользователей и ролей -- компаний и профилей контрагентов -- адресов доставки -- каталога и складских остатков -- корзины и ее позиций -- заявок и заказов -- событий изменения статусов -- уведомлений и мессенджерных подключений -- бонусных и реферальных сущностей - -## 8.2 Логические группы сущностей - -В модели базы данных выделяются следующие логические группы: - -- справочник пользователей и компаний -- каталог и складской контур -- заказный контур -- контур уведомлений и мессенджеров -- бонусный и реферальный контур -- административные настройки каталога - -## 8.3 Справочник пользователей и компаний - -Базовые сущности группы: - -- `User` -- `Company` -- `CounterpartyProfile` -- `DeliveryAddress` -- `RegistrationRequest` -- `Invitation` -- `MessengerConnection` - -Назначение группы: - -- хранение учетных записей пользователей -- хранение принадлежности пользователя к компании -- хранение полного профиля контрагента -- хранение адресов доставки -- хранение заявок на подключение и приглашений -- хранение подключений Telegram и MAX - -Связи группы: - -- одна компания может иметь нескольких пользователей -- один пользователь может иметь один профиль контрагента -- один пользователь может иметь несколько адресов доставки -- один пользователь может иметь несколько подключенных мессенджеров - -## 8.4 Каталог и складской контур - -Базовые сущности группы: - -- `Product` -- `Warehouse` -- `ProductStock` -- `CatalogProductTypeSetting` - -Назначение группы: - -- хранение товарных позиций и SKU -- хранение параметров товара -- хранение остатков по складам -- хранение правил отображения и кастомизации по типам товара - -Основные поля сущности `Product`: - -- `sku` -- `name` -- `productType` -- `widthMm` -- `lengthM` -- `thicknessMicron` -- `sleeveBrand` -- `quantityPerBox` -- `tags` -- `description` -- `isCustomizable` -- `isActive` - -Основные поля сущности `CatalogProductTypeSetting`: - -- признак показа транспортных и упаковочных параметров -- разрешение на индивидуальную длину -- минимальная, максимальная длина и шаг -- разрешение на индивидуальную втулку -- разрешение на индивидуальную надпись -- списки стандартных значений ширины, длины, толщины, втулки, цвета и надписи - -## 8.5 Корзина и заказный контур - -Базовые сущности группы: - -- `Cart` -- `CartItem` -- `Order` -- `OrderItem` -- `OrderStatusEvent` - -Назначение группы: - -- хранение состава клиентской корзины -- фиксация параметров выбранного товара -- хранение заявки и заказа -- хранение истории изменения статусов - -Ключевые особенности: - -- корзина привязана к конкретному пользователю -- позиции корзины хранят снимок SKU, имени товара и параметров -- заказ хранит состав позиций, статус, стоимость, условия поставки и историю изменений -- события статуса обеспечивают аудит переходов между состояниями - -## 8.6 Бонусный и реферальный контур - -Базовые сущности группы: - -- `ReferralLink` -- `BonusTransaction` -- `RewardWithdrawalRequest` - -Назначение группы: - -- хранение реферальных связей между клиентами -- хранение бонусных начислений и списаний -- хранение заявок на использование либо вывод бонусов - -## 8.7 Основные связи между сущностями - -Укрупненная структура связей определяется следующими правилами: - -- `Company` объединяет пользователей одной клиентской организации -- `User` связан с `CounterpartyProfile`, `DeliveryAddress`, `MessengerConnection`, `Cart`, `Order`, `BonusTransaction` и `RewardWithdrawalRequest` -- `Cart` содержит набор `CartItem`, привязанных к конкретным `Product` -- `Order` содержит набор `OrderItem` и историю `OrderStatusEvent` -- `Product` связан с остатками `ProductStock`, распределенными по сущностям `Warehouse` -- настройки параметров по товарному направлению хранятся в `CatalogProductTypeSetting` -- реферальные связи реализуются через `ReferralLink`, связывающий одного пользователя с другим пользователем - -## 8.8 Требования к хранению прикладных данных - -Модель базы данных должна обеспечивать: - -- уникальность ключевых идентификаторов -- хранение дат создания и изменения сущностей -- хранение параметров товарных позиций в структурированном виде -- хранение истории статусов и действий -- хранение интеграционных идентификаторов для связи с внешними системами - -## 8.9 Требования к расширяемости модели - -Структура базы данных должна позволять: - -- добавлять новые типы продукции без изменения базовой логики ролей и заказов -- расширять набор параметров каталога -- развивать бонусный контур без нарушения заказного контура -- расширять интеграции с 1С и иными внешними системами diff --git a/docs/tz/development-stages.md b/docs/tz/development-stages.md new file mode 100644 index 0000000..ac4042d --- /dev/null +++ b/docs/tz/development-stages.md @@ -0,0 +1,99 @@ +# 13. Стадии и этапы разработки + +## 13.1 Общий порядок выполнения работ + +Работы выполняются поэтапно, чтобы согласовывать ключевые решения до перехода к следующей части реализации. + +Переход к следующему этапу выполняется после согласования сторонами результата предыдущего этапа либо после фиксации замечаний, не препятствующих продолжению работ. + +## 13.2 Этап 1. Разработка и согласование технического задания + +На этапе разрабатывается и согласуется настоящее техническое задание. + +Результат этапа: + +- согласованная редакция технического задания +- зафиксированные границы продукта +- зафиксированный состав пользовательских ролей +- зафиксированные функциональные, интеграционные, технические и эксплуатационные требования + +Критерий завершения этапа: утверждение технического задания сторонами. + +## 13.3 Этап 2. UX/UI и согласование визуального подхода + +На этапе подготавливаются 2-3 сверстанные страницы личного кабинета с основными элементами интерфейса. + +В состав страниц для согласования могут входить: + +- страница входа или регистрации +- каталог либо карточка товара +- корзина либо карточка заявки +- менеджерская карточка клиента или заказа + +Результат этапа: + +- согласованный визуальный подход +- согласованные базовые интерфейсные элементы +- подтверждение применимости выбранного подхода для клиентского и менеджерского контуров + +Критерий завершения этапа: согласование визуального подхода сторонами. + +## 13.4 Этап 3. Функциональная реализация без интеграции с 1С + +На этапе реализуются основные пользовательские и менеджерские сценарии без подключения обмена с 1С. + +В состав этапа входят: + +- регистрация и подключение клиентов +- роли и разграничение доступа +- каталог готовой продукции +- корзина и заявки на заказ +- заявки на расчет индивидуальной продукции +- обработка заявок менеджером +- статусы и история изменений +- уведомления в согласованном объеме +- бонусный и реферальный контур +- административные настройки, необходимые для работы продукта + +Результат этапа: + +- работоспособный программный продукт с основным функционалом +- возможность проверки клиентских, менеджерских и бонусных сценариев без обмена с 1С + +Критерий завершения этапа: готовность и приемка основного функционала без интеграции с 1С. + +## 13.5 Этап 4. Интеграция с 1С и отладка обмена + +На этапе выполняются подключение, настройка и отладка интеграции с 1С. + +В состав этапа входят: + +- согласование или уточнение интеграционной спецификации +- настройка приема webhook-событий от 1С +- настройка получения данных из 1С через согласованные методы +- сопоставление внутренних идентификаторов и идентификаторов 1С +- проверка получения каталога, остатков, заказов, статусов и задолженности +- проверка обработки дублей и ошибок обмена +- проверка отображения даты актуальности данных + +Результат этапа: + +- работоспособный интеграционный обмен с 1С в согласованном объеме +- журналирование ключевых интеграционных событий +- подтвержденная работоспособность сценариев, зависящих от данных 1С + +Критерий завершения этапа: подтвержденная сторонами работоспособность сценариев с 1С в согласованном объеме. + +## 13.6 Этап 5. Передача результата и приемка + +На этапе выполняются итоговая проверка, устранение критичных замечаний и передача результата работ. + +Результат этапа: + +- размещенный программный продукт в согласованном эксплуатационном контуре +- согласованная редакция технического задания +- пользовательская и эксплуатационная документация в согласованном объеме +- перечень ключевых сторонних компонентов +- акт приемки выполненных работ + +Критерий завершения этапа: подписание акта приемки либо наступление условий приемки, предусмотренных договором. diff --git a/docs/tz/documentation-requirements.md b/docs/tz/documentation-requirements.md new file mode 100644 index 0000000..371a51a --- /dev/null +++ b/docs/tz/documentation-requirements.md @@ -0,0 +1,89 @@ +# 11. Требования к программной документации + +## 11.1 Общий подход + +Настоящее техническое задание является основным техническим документом программного продукта. + +В составе настоящего технического задания фиксируются: + +- назначение и границы продукта +- функциональные требования +- роли пользователей и права доступа +- требования к данным, сущностям и модели базы данных +- требования к интерфейсам +- требования к интеграциям +- архитектура, стек, компоненты и эксплуатационный контур +- нефункциональные требования +- порядок контроля, приемки и гарантийного сопровождения + +Отдельные документы не должны дублировать техническое задание. Дополнительная документация должна описывать только то, что необходимо для использования, эксплуатации или интеграции программного продукта и не раскрыто в настоящем документе в достаточном объеме. + +## 11.2 Пользовательская документация + +Пользовательская документация должна быть подготовлена в объеме, достаточном для работы пользователей в предусмотренных ролях: + +- клиент +- менеджер +- суперменеджер + +Пользовательская документация должна описывать: + +- вход в личный кабинет и завершение регистрации +- работу с профилем и каналами уведомлений +- просмотр каталога готовой продукции +- добавление товаров в корзину и отправку заявки +- создание заявки на расчет индивидуальной продукции +- просмотр заказов, статусов, условий и истории изменений +- работу с бонусным кабинетом, бонусным балансом и заявками на вывод +- действия менеджера по обработке клиентов, заявок, заказов и бонусных операций +- действия суперменеджера в административных разделах, если они отличаются от действий менеджера + +Документация должна быть написана прикладным языком и ориентирована на выполнение пользовательских сценариев, а не на описание внутренней реализации. + +## 11.3 Эксплуатационная документация + +Эксплуатационная документация должна быть подготовлена в объеме, достаточном для сопровождения программного продукта после передачи результата работ. + +Эксплуатационная документация должна описывать: + +- состав сервисов и их назначение +- порядок запуска и перезапуска сервисов через согласованный контур деплоя +- используемые окружения и общие принципы конфигурации +- порядок загрузки секретов из Vault +- порядок просмотра логов и диагностики типовых сбоев +- порядок проверки работоспособности клиентского, менеджерского и интеграционного контуров +- порядок обновления приложения через Git и Dokploy +- перечень технических контактов или зон ответственности, если они согласованы сторонами + +Эксплуатационная документация не должна содержать бизнес-секреты, токены, пароли и иные чувствительные значения. Для секретов указываются только имена переменных, назначение и источник получения. + +## 11.4 Интеграционная документация + +Для интеграции с 1С должна быть подготовлена интеграционная спецификация либо отдельный раздел настоящего технического задания, если к моменту согласования ТЗ формат обмена уже определен. + +Интеграционная документация должна описывать: + +- состав событий, передаваемых из 1С +- состав методов получения данных из 1С +- структуру payload для каждого события и метода +- обязательные и необязательные поля +- правила сопоставления идентификаторов +- требования к авторизации, подписи или иному механизму защиты запросов +- порядок обработки дублей +- порядок фиксации ошибок и повторной обработки сообщений +- критерии приемки интеграционного обмена + +Если точный формат обмена с 1С не определен на момент утверждения ТЗ, он фиксируется отдельной согласованной интеграционной спецификацией до начала завершающего этапа интеграции. + +## 11.5 Перечень сторонних компонентов + +Перечень сторонних компонентов формируется на основании фактических файлов проекта, включая `package.json`, lock-файлы, Dockerfile и конфигурационные файлы сервисов. + +Перечень должен содержать: + +- наименование компонента +- версию или диапазон версий +- назначение компонента в продукте +- источник установки или репозиторий, если он отличается от стандартного пакетного менеджера + +Ключевые сторонние компоненты, используемые в текущей реализации, перечислены в разделе технической архитектуры настоящего технического задания. diff --git a/docs/tz/economic-indicators.md b/docs/tz/economic-indicators.md new file mode 100644 index 0000000..6045bd7 --- /dev/null +++ b/docs/tz/economic-indicators.md @@ -0,0 +1,25 @@ +# 12. Технико-экономические показатели + +## 12.1 Назначение показателей + +Технико-экономические показатели используются для фиксации ожидаемого прикладного эффекта от разработки программного продукта. + +Расчет финансовой эффективности, окупаемости или экономического эффекта в денежном выражении не входит в состав настоящего технического задания, если стороны не согласуют такой расчет отдельно. + +## 12.2 Ожидаемый прикладной эффект + +Разработка программного продукта должна обеспечить: + +- снижение объема ручной коммуникации при приеме и сопровождении заказов +- единый интерфейс для клиента, менеджера и суперменеджера +- ускорение обработки заявок за счет фиксации состава, параметров и статусов в системе +- снижение риска потери информации по заказам, заявкам и бонусным операциям +- повышение прозрачности статусов заказов и актуальности данных для клиента +- централизованное хранение истории изменений +- возможность дальнейшего развития клиентского, менеджерского, бонусного и интеграционного контуров + +## 12.3 Ограничения + +Программный продукт не заменяет учетную систему 1С и не является первичным источником бухгалтерских, складских или финансовых данных. + +Экономический эффект зависит от полноты внедрения продукта в рабочие процессы заказчика, качества данных 1С, доступности внешних каналов уведомлений и соблюдения эксплуатационных требований. diff --git a/docs/tz/functional-requirements.md b/docs/tz/functional-requirements.md index 471b84b..7d57c13 100644 --- a/docs/tz/functional-requirements.md +++ b/docs/tz/functional-requirements.md @@ -1,6 +1,6 @@ -# 2. Функциональные требования +# 4. Функциональные требования -## 2.1 Требования к регистрации и подключению клиентов +## 4.1 Требования к регистрации и подключению клиентов Система должна поддерживать два базовых сценария подключения клиента: @@ -18,7 +18,7 @@ 7. После завершения регистрации клиент должен получить доступ к личному кабинету. 8. Система должна поддерживать подключение доступных каналов уведомлений для клиентской учетной записи. -## 2.2 Требования к каталогу готовой продукции +## 4.2 Требования к каталогу готовой продукции Система должна предоставлять клиенту каталог готовой продукции без отображения цены до обработки менеджером. @@ -33,7 +33,7 @@ 7. Система должна исключать отображение стоимости до момента публикации условий менеджером. 8. Для параметров товара система должна отображать пояснения, помогающие клиенту понять назначение параметра и ограничения выбора. -## 2.3 Требования к параметрам каталога и кастомизации +## 4.3 Требования к параметрам каталога и кастомизации Система должна поддерживать настройку параметров по каждому товарному направлению. @@ -47,7 +47,7 @@ 6. Наборы стандартных параметров должны редактироваться в административном контуре. 7. Изменение набора стандартных параметров не должно приводить к потере уже сохраненных заказных данных. -## 2.4 Требования к корзине и заявке на заказ +## 4.4 Требования к корзине и заявке на заказ Система должна позволять клиенту собрать корзину и направить заявку на заказ. @@ -61,7 +61,7 @@ 6. Для заявки должны сохраняться дата создания, инициатор и закрепленный менеджер. 7. До обработки менеджером стоимость в заявке не должна отображаться клиенту. -## 2.5 Требования к обработке заявки менеджером +## 4.5 Требования к обработке заявки менеджером Менеджер должен иметь возможность обработать клиентскую заявку вручную. @@ -77,7 +77,7 @@ 8. Менеджер должен иметь возможность перевести заявку в работу. 9. Менеджер должен иметь возможность отменить заявку с фиксацией основания отмены. -## 2.6 Требования к заявке на расчет индивидуальной продукции +## 4.6 Требования к заявке на расчет индивидуальной продукции Система должна поддерживать отдельный сценарий расчета продукции с индивидуальными параметрами. @@ -101,7 +101,7 @@ - иные параметры в зависимости от вида продукции - текстовый комментарий клиента -## 2.7 Требования к статусам заявок +## 4.7 Требования к статусам заявок Система должна обеспечивать сквозное сопровождение заявок по статусам. @@ -122,9 +122,9 @@ - пользователя или источник, выполнивший изменение - комментарий, если он предусмотрен сценарием -## 2.8 Требования к заказам и их сопровождению +## 4.8 Требования к заказам и их сопровождению -Система должна предоставлять клиенту и менеджеру доступ к списку заказов и карточке каждого заказа. +Система должна предоставлять клиенту и менеджеру доступ к списку заказов, карточке каждого заказа и актуальным учетным сведениям, полученным из 1С. Функциональные требования: @@ -134,8 +134,10 @@ 4. В карточке заказа должны отображаться состав, статус, стоимость, условия поставки и история изменений. 5. В карточке заказа должна отображаться дата актуальности данных. 6. При наличии обновлений из внешней системы сведения по заказу должны синхронизироваться и отображаться пользователю. +7. Система должна отображать текущую задолженность клиента, если такие сведения получены из 1С. +8. Для задолженности должна отображаться дата актуальности данных. -## 2.9 Требования к уведомлениям +## 4.9 Требования к уведомлениям Система должна поддерживать уведомления по нескольким каналам связи. @@ -154,9 +156,9 @@ - изменение бонусного баланса - обработка заявки на использование либо вывод бонусов -## 2.10 Требования к бонусной и реферальной программе +## 4.10 Требования к бонусной и реферальной программе -Система должна включать бонусный контур как самостоятельную функциональную область. +Система должна включать бонусный контур как самостоятельную функциональную область с отдельным пользовательским интерфейсом. Функциональные требования: @@ -170,7 +172,7 @@ 8. Менеджер должен иметь возможность обрабатывать операции бонусного контура. 9. Система должна уведомлять клиента об изменениях бонусного состояния. -## 2.11 Требования к административным настройкам +## 4.11 Требования к административным настройкам Система должна содержать административные разделы для управления следующими объектами: diff --git a/docs/tz/index.md b/docs/tz/index.md index e458efe..bcdcaba 100644 --- a/docs/tz/index.md +++ b/docs/tz/index.md @@ -4,17 +4,23 @@ ## Содержание +1. [Введение, основание, цель и состав проекта](/tz/project-overview) 2. [Основания для разработки и нормативные материалы](/tz/normative-base) 3. [Назначение и границы программного продукта](/tz/product-scope) -4. [Роли пользователей и права доступа](/tz/roles-access) -5. [Функциональные требования](/tz/functional-requirements) -6. [Требования к данным и интеграциям](/tz/data-integrations) -7. [Техническая архитектура, стек и состав компонентов](/tz/technical-architecture) -8. [Структура данных и модель базы данных](/tz/database-model) -9. [Нефункциональные требования](/tz/non-functional-requirements) -10. [Экранные формы и прототипы интерфейсов](/tz/stage-1/) -11. [Порядок приемки и состав передаваемых материалов](/tz/acceptance) +4. [Функциональные требования](/tz/functional-requirements) +5. [Роли пользователей и права доступа](/tz/roles-access) +6. [Требования к данным, сущностям и модели базы данных](/tz/data-entities) +7. [Требования к интерфейсу и прототипам](/tz/stage-1/) +8. [Требования к интеграции с 1С и внешним интерфейсам](/tz/integrations) +9. [Техническая архитектура, стек и эксплуатационный контур](/tz/technical-architecture) +10. [Нефункциональные требования](/tz/non-functional-requirements) +11. [Требования к программной документации](/tz/documentation-requirements) +12. [Технико-экономические показатели](/tz/economic-indicators) +13. [Стадии и этапы разработки](/tz/development-stages) +14. [Порядок контроля, приемки и гарантийного сопровождения](/tz/acceptance) ## Назначение раздела Материалы раздела используются для согласования требований к программному продукту, его функциям, данным, интерфейсам, интеграциям и условиям приемки. + +Структура технического задания подготовлена с учетом ГОСТ 19.201-78 и адаптирована под разработку современного веб-программного продукта. Технические схемы, модель данных, архитектура, роли и интеграции являются частью настоящего технического задания и не требуют дублирования в отдельных документах, если иное не согласовано сторонами. diff --git a/docs/tz/infrastructure-operations.md b/docs/tz/infrastructure-operations.md deleted file mode 100644 index 4c1c7ee..0000000 --- a/docs/tz/infrastructure-operations.md +++ /dev/null @@ -1,79 +0,0 @@ -# 8. Требования к инфраструктуре и эксплуатации - -## 8.1 Инфраструктурная схема - -Текущая инфраструктурная схема проекта включает прикладные сервисы, сервис секретов, мессенджерные сервисы и вспомогательный worker-контур. - -![Инфраструктура, деплой и эксплуатационный контур](/diagrams/infrastructure-topology.svg) - -## 8.2 Сервисы и окружение - -Сервисы проекта и способ их развёртывания: - -| Сервис | Путь в репозитории | Роль | Deploy mode | Сервер | -| --- | --- | --- | --- | --- | -| web-frontend | `web-frontend` | клиентский и менеджерский веб-интерфейс | `dokploy_webhook` | `main` | -| apollo-backend | `apollo-backend` | GraphQL API и бизнес-логика | `dokploy_webhook` | `main` | -| hatchet-worker | `hatchet-worker` | фоновый worker-контур | `dokploy_webhook` | `main` | -| tg-bot | `tg-bot` | Telegram-контур | `dokploy_webhook` | `main` | -| max-bot | `max-bot` | MAX-контур | `dokploy_webhook` | `main` | -| bonus-bot | `bonus-bot` | бонусный сервис | `dokploy_webhook` | `main` | -| vault | `vault` | сервис секретов | `dokploy_webhook` | `main` | - -## 8.3 Требования к деплою и запуску - -Для основных сервисов проекта используется режим `dokploy_webhook`. - -Цепочка развёртывания должна быть следующей: - -1. изменения фиксируются в Git-репозитории -2. изменения публикуются в `main` -3. Dokploy получает webhook-событие -4. Dokploy выполняет сборку соответствующего сервиса -5. сервис перезапускается с загрузкой секретов из Vault -6. после старта выполняются bootstrap-действия, предусмотренные образом и entrypoint-командой - -Текущие особенности прикладных сервисов: - -- `web-frontend` стартует через загрузку Vault env и запуск `.output/server/index.mjs` -- `apollo-backend` стартует через загрузку Vault env, `prisma migrate deploy` и запуск `src/server.js` -- bot-сервисы стартуют через общий паттерн загрузки Vault env и запуск `node src/server.js` - -## 8.4 Требования к секретам и конфигурации - -Сервисы программного продукта должны получать прикладные секреты из `Vault`. - -В конфигурации сервисов допускается хранение только bootstrap-параметров для подключения к Vault. Бизнес-секреты, ключи интеграций и иные чувствительные данные должны загружаться из Vault при старте приложения. - -Сервис `vault` развернут как отдельное приложение на базе образа `hashicorp/vault:1.21.3`. - -Прикладные сервисы используют общий shell-bootstrap `load-vault-env.sh`, который: - -- ожидает доступность Vault по health endpoint -- загружает shared secrets -- загружает project secrets -- экспортирует секреты в runtime environment процесса - -## 8.5 Требования к эксплуатации и надежности - -Система должна обеспечивать: - -- корректную работу в десктопных и мобильных браузерах -- приемлемое время открытия основных экранов и выполнения действий -- сохранность пользовательских данных -- сохранность истории изменений по заявкам, заказам и бонусным операциям -- фиксацию ошибок интеграционного обмена -- журналирование значимых системных и пользовательских событий -- возможность сопровождения и развития клиентского и менеджерского контуров - -## 8.6 Требования к передаче результата и эксплуатации - -По результатам выполнения работ заказчику должны быть переданы: - -- исходный код программного продукта -- техническое задание в согласованной редакции -- сведения об используемых компонентах и их версиях -- описание реализованных интеграций и используемых внешних интерфейсов -- схемы взаимодействия модулей и движения данных -- описание пользовательских ролей и прав доступа -- материалы, необходимые для сопровождения и эксплуатации продукта diff --git a/docs/tz/integrations.md b/docs/tz/integrations.md index 267f25a..dc2745e 100644 --- a/docs/tz/integrations.md +++ b/docs/tz/integrations.md @@ -1,21 +1,22 @@ -# 6. Требования к интеграциям +# 8. Требования к интеграции с 1С и внешним интерфейсам -## 6.1 Общие требования к интеграционному контуру +## 8.1 Общие требования к интеграционному контуру Интеграционный слой должен обеспечивать обмен данными между личным кабинетом и внешними системами без потери целостности внутренних сущностей и статусов. Интеграционный контур должен обеспечивать: - получение данных из 1С -- передачу во внешние системы данных, необходимых для сопровождения заказов и клиентов +- прием событий от 1С +- передачу во внешние системы данных, необходимых для сопровождения заказов и клиентов, если такой обмен согласован сторонами - сопоставление внутренних идентификаторов и идентификаторов внешних систем - регистрацию входящих и исходящих операций обмена - повторную обработку неуспешных сообщений - хранение истории обновлений по интеграционным операциям -## 6.2 Интеграция с 1С +## 8.2 Интеграция с 1С -Интеграция с 1С должна обеспечивать обмен данными, необходимыми для сопровождения каталога и заказов. +Интеграция с 1С должна обеспечивать обмен данными, необходимыми для сопровождения каталога, заказов, статусов, остатков и сведений о задолженности клиента. Система должна обеспечивать получение из 1С следующих данных: @@ -25,8 +26,52 @@ - сведения о заказах - статусы заказов - изменения состава, стоимости, доставки и иных существенных параметров заказа +- текущая задолженность клиента +- дата актуальности сведений, полученных из 1С -## 6.3 Требования к структурам обмена +1С рассматривается как первичный источник учетных данных по заказам, складам, статусам, стоимости, доставке и задолженности. Личный кабинет отображает эти сведения и фиксирует дату их актуальности. + +## 8.3 События от 1С + +Система должна поддерживать прием webhook-событий от 1С в согласованном формате. + +Минимальный состав событий: + +- создание нового заказа +- изменение информации по заказу +- изменение статуса заказа +- изменение сроков, условий или параметров доставки +- изменение состава заказа +- изменение сведений о задолженности клиента, если такие данные передаются событийно + +Для каждого события должны фиксироваться: + +- тип события +- внешний идентификатор объекта 1С +- внутренний идентификатор объекта, если сопоставление выполнено +- дата и время события +- источник события +- статус обработки +- текст ошибки при неуспешной обработке + +Система должна защищаться от повторной обработки дублей webhook-событий. + +## 8.4 Методы получения данных из 1С + +Система должна поддерживать получение данных из 1С через согласованные методы. + +Минимальный состав методов: + +- получение заказов клиента +- получение товарного каталога +- получение характеристик товаров +- получение доступных остатков по складам +- получение статусов и изменений по заказам +- получение текущей задолженности клиента и даты актуальности этих сведений + +Точный набор методов, параметры запросов, формат ответов и ограничения по частоте вызовов фиксируются в интеграционной спецификации. + +## 8.5 Требования к структурам обмена Входные и выходные данные интеграционного слоя должны описываться в структурированном виде и позволять однозначно восстанавливать: @@ -39,7 +84,9 @@ Для обмена должны использоваться структурированные payload-форматы, пригодные для сериализации в `JSON`. -## 6.4 Интеграционные поля и служебные атрибуты +Точная структура payload, схема подписи запросов и набор обязательных полей согласуются сторонами до начала этапа интеграции с 1С. + +## 8.6 Интеграционные поля и служебные атрибуты Для сущностей, участвующих в обмене, должны поддерживаться: @@ -48,8 +95,9 @@ - источник последнего обновления - признак успешной или неуспешной обработки - журнал интеграционных ошибок при наличии +- технический идентификатор последнего обработанного события, если он передается 1С -## 6.5 Журналирование интеграционных операций +## 8.7 Журналирование интеграционных операций Для ключевых операций обмена система должна сохранять: @@ -61,3 +109,29 @@ - пользователя либо внешний источник, выполнивший изменение - статус обработки сообщения - текст ошибки при наличии + +## 8.8 Требования к защите интеграционного обмена + +Интеграционные запросы должны выполняться с использованием согласованного механизма авторизации или подписи. + +Система должна отклонять интеграционные запросы, если: + +- отсутствуют обязательные параметры авторизации +- подпись или токен не прошли проверку +- payload не соответствует согласованной структуре +- невозможно определить тип события или объект обработки + +Секреты, используемые для интеграции с 1С, должны храниться только в Vault и передаваться сервисам через runtime-конфигурацию. + +## 8.9 Критерии приемки интеграции с 1С + +Интеграция с 1С считается готовой в согласованном объеме, если: + +- каталог и характеристики товаров получаются и отображаются в личном кабинете +- остатки по складам отображаются в карточках товаров +- заказы клиента получаются и отображаются с актуальными статусами +- изменения заказа из 1С отображаются в карточке заказа +- текущая задолженность клиента и дата актуальности данных отображаются в предусмотренных интерфейсах +- webhook-события не обрабатываются повторно при дублях +- ошибки интеграционного обмена фиксируются в журнале +- неуспешные сообщения могут быть проанализированы и повторно обработаны в согласованном порядке diff --git a/docs/tz/non-functional-requirements.md b/docs/tz/non-functional-requirements.md index 9f88d55..cdcdf75 100644 --- a/docs/tz/non-functional-requirements.md +++ b/docs/tz/non-functional-requirements.md @@ -1,10 +1,10 @@ -# 9. Нефункциональные требования +# 10. Нефункциональные требования -## 9.1 Общие требования к архитектуре +## 10.1 Общие требования к архитектуре Программный продукт должен быть реализован как веб-система с разделением клиентского и менеджерского контуров, серверной бизнес-логикой, постоянным хранением данных и возможностью интеграционного обмена с внешними системами. -## 9.2 Требования к доступности интерфейсов +## 10.2 Требования к доступности интерфейсов Система должна обеспечивать корректную работу: @@ -14,7 +14,7 @@ Интерфейсы должны сохранять работоспособность и читаемость при адаптивном отображении. -## 9.3 Требования к производительности +## 10.3 Требования к производительности При штатной эксплуатации система должна обеспечивать: @@ -24,7 +24,7 @@ Точные количественные показатели производительности подлежат фиксации в рабочей документации по инфраструктуре и тестированию. -## 9.4 Требования к безопасности +## 10.4 Требования к безопасности Система должна обеспечивать: @@ -34,7 +34,7 @@ - хранение и передачу чувствительных данных с использованием защищенных механизмов - исключение несанкционированного доступа к административным функциям -## 9.5 Требования к надежности и журналированию +## 10.5 Требования к надежности и журналированию Система должна обеспечивать: @@ -43,7 +43,7 @@ - фиксацию ошибок интеграционного обмена - фиксацию значимых системных и пользовательских событий -## 9.6 Требования к сопровождаемости +## 10.6 Требования к сопровождаемости Реализация должна обеспечивать возможность: @@ -52,7 +52,7 @@ - изменения параметров каталога и уведомлений без переработки базовой структуры системы - расширения интеграционного обмена с 1С и иными внешними системами -## 9.7 Требования к данным и актуальности сведений +## 10.7 Требования к данным и актуальности сведений Система должна обеспечивать: @@ -60,7 +60,7 @@ - отображение даты актуальности сведений, полученных из внешних систем, когда это применимо - защиту от потери данных при обновлении параметров каталога и заказных сущностей -## 9.8 Требования к документации +## 10.8 Требования к документации По результатам выполнения работ должна быть сформирована документация, достаточная для: diff --git a/docs/tz/project-overview.md b/docs/tz/project-overview.md index ca8a1b3..c386d44 100644 --- a/docs/tz/project-overview.md +++ b/docs/tz/project-overview.md @@ -1,4 +1,8 @@ -# 1. Основание, цель и состав проекта +# 1. Введение, основание, цель и состав проекта + +Настоящее техническое задание описывает разработку программного продукта `Личный кабинет Фрегат` для поддержки клиентских, менеджерских, заказных, бонусных и интеграционных сценариев в едином веб-интерфейсе. + +Документ используется для согласования состава работ, функциональных и технических требований, этапов разработки, требований к программной документации, порядка приемки и гарантийного сопровождения. ## 1.1 Основание для разработки diff --git a/docs/tz/roles-access.md b/docs/tz/roles-access.md index 4f9ae09..f063701 100644 --- a/docs/tz/roles-access.md +++ b/docs/tz/roles-access.md @@ -1,6 +1,6 @@ -# 3. Требования к ролям и правам доступа +# 5. Требования к ролям и правам доступа -## 3.1 Состав ролей +## 5.1 Состав ролей В системе должны быть предусмотрены следующие роли пользователей: @@ -8,7 +8,7 @@ - менеджер - суперменеджер -## 3.2 Роль клиента +## 5.2 Роль клиента Пользователь с ролью `Клиент` представляет организацию-контрагента и работает только с данными своей компании. @@ -29,7 +29,7 @@ - просмотр бонусного баланса и истории бонусных операций - подача заявки на использование либо вывод бонусов при наличии соответствующих правил -## 3.3 Роль менеджера +## 5.3 Роль менеджера Пользователь с ролью `Менеджер` представляет сотрудника компании, закрепленного за клиентами. @@ -47,7 +47,7 @@ - просмотр карточек клиентов, заявок и заказов - выполнение операций в бонусном контуре в пределах полномочий -## 3.4 Роль суперменеджера +## 5.4 Роль суперменеджера Пользователь с ролью `Суперменеджер` обладает всеми правами менеджера и дополнительными административными полномочиями. @@ -60,7 +60,7 @@ - управление параметрами интеграции и синхронизации - расширенное управление бонусным и реферальным контуром -## 3.5 Матрица доступа +## 5.5 Матрица доступа | Действие | Клиент | Менеджер | Суперменеджер | | --- | --- | --- | --- | @@ -79,7 +79,7 @@ | Управление параметрами синхронизации | Нет | Нет | Да | | Управление бонусными правилами | Нет | Да | Да | -## 3.6 Ограничения доступа и требования к безопасности +## 5.6 Ограничения доступа и требования к безопасности Система должна обеспечивать: diff --git a/docs/tz/stage-1/index.md b/docs/tz/stage-1/index.md index d1156d3..657d197 100644 --- a/docs/tz/stage-1/index.md +++ b/docs/tz/stage-1/index.md @@ -1,6 +1,6 @@ -# 5. Требования к интерфейсу и прототипам +# 7. Требования к интерфейсу и прототипам -## 5.1 Карта экранов +## 7.1 Карта экранов Ниже приведен базовый состав экранов, подлежащих реализации и сопровождению в рамках программного продукта. @@ -26,11 +26,11 @@ | Настройки синхронизации | `/settings-sync` | суперменеджер | мониторинг и управление обменом | | Бонусная система | `/bonus-system/*` | менеджер/суперменеджер | рефералы, транзакции, выводы | -## 5.2 Маршруты и экранные формы +## 7.2 Маршруты и экранные формы Ниже приведен перечень экранных форм, предусмотренных в составе frontend-контура программного продукта. -### 5.2.1 Публичные и клиентские страницы +### 7.2.1 Публичные и клиентские страницы | Маршрут | Экран | Назначение | | --- | --- | --- | @@ -44,7 +44,7 @@ | `/notifications` | Уведомления | Список системных уведомлений | | `/bonus-program` | Бонусный кабинет | Бонусный баланс, подарочные карты и бонусные действия | -### 5.2.2 Профиль клиента +### 7.2.2 Профиль клиента | Маршрут | Экран | Назначение | | --- | --- | --- | @@ -55,7 +55,7 @@ | `/profile/notifications` | Настройки уведомлений | Подключение и настройка каналов уведомлений | | `/profile/notifications/success` | Успешное подключение уведомлений | Финальный экран сценария подключения канала | -### 5.2.3 Менеджерские и административные страницы +### 7.2.3 Менеджерские и административные страницы | Маршрут | Экран | Назначение | | --- | --- | --- | @@ -68,7 +68,7 @@ | `/settings-sync` | 1С / синхронизация | Управление и мониторинг синхронизации | | `/messages` | Сообщения | Шаблоны и тексты менеджерских сообщений | -### 5.2.4 Бонусный менеджерский контур +### 7.2.4 Бонусный менеджерский контур | Маршрут | Экран | Назначение | | --- | --- | --- | @@ -78,7 +78,7 @@ | `/bonus-system/transactions/new` | Добавить бонусную транзакцию | Ручное начисление или списание | | `/bonus-system/withdrawals/[id]` | Проверка заявки на вывод | Рассмотрение заявки клиента на вывод бонусов | -## 5.3 Общие требования к экранным формам +## 7.3 Общие требования к экранным формам Экранные формы должны обеспечивать: @@ -96,9 +96,9 @@ Ниже приведены низкодетализированные wireframe-прототипы. Они используются как визуальная фиксация состава страниц, ключевых блоков и пользовательских действий. -## 5.4 Клиентские экранные формы +## 7.4 Клиентские экранные формы -### 5.4.1 Главная страница клиента +### 7.4.1 Главная страница клиента Назначение страницы: @@ -118,7 +118,7 @@ Wireframe-прототип: ![Прототип главной страницы клиента](/prototypes/dashboard.svg) -### 5.4.2 Каталог продукции +### 7.4.2 Каталог продукции Назначение страницы: @@ -137,7 +137,7 @@ Wireframe-прототип: ![Прототип каталога продукции](/prototypes/catalog-grid.svg) -### 5.4.3 Карточка товара +### 7.4.3 Карточка товара Назначение страницы: @@ -182,7 +182,7 @@ Wireframe-прототип: - правила по втулке с логотипом - правила по нанесению индивидуальной надписи -### 5.4.4 Корзина +### 7.4.4 Корзина Назначение страницы: @@ -204,7 +204,7 @@ Wireframe-прототип: ![Прототип корзины](/prototypes/cart.svg) -### 5.4.5 Карточка заявки или заказа +### 7.4.5 Карточка заявки или заказа Назначение страницы: @@ -227,7 +227,7 @@ Wireframe-прототип: - история статусов - системные комментарии -### 5.4.6 Страница логина и регистрации +### 7.4.6 Страница логина и регистрации Назначение страницы: @@ -246,7 +246,7 @@ Wireframe-прототип: ![Прототип страницы логина и подключения](/prototypes/login.svg) -### 5.4.7 Список заказов +### 7.4.7 Список заказов Назначение страницы: @@ -259,13 +259,13 @@ Wireframe-прототип: - таблица заказов - переход в карточку конкретного заказа -### 5.4.8 Уведомления +### 7.4.8 Уведомления Назначение страницы: - просмотр истории уведомлений по заказам, заявкам и бонусным операциям -### 5.4.9 Бонусный кабинет +### 7.4.9 Бонусный кабинет Назначение страницы: @@ -285,9 +285,9 @@ Wireframe-прототип: ![Прототип бонусного кабинета](/prototypes/bonus-cabinet.svg) -## 5.5 Менеджерские экранные формы +## 7.5 Менеджерские экранные формы -### 5.5.1 Список клиентов +### 7.5.1 Список клиентов Назначение страницы: @@ -305,7 +305,7 @@ Wireframe-прототип: ![Прототип списка клиентов](/prototypes/client-list.svg) -### 5.5.2 Карточка клиента +### 7.5.2 Карточка клиента Назначение страницы: @@ -325,7 +325,7 @@ Wireframe-прототип: ![Прототип карточки клиента](/prototypes/client-card.svg) -### 5.5.3 Карточка обработки заявки +### 7.5.3 Карточка обработки заявки Назначение страницы: @@ -348,7 +348,7 @@ Wireframe-прототип: - история изменений - блок действий со статусом -### 5.5.4 Список заказов менеджера +### 7.5.4 Список заказов менеджера Назначение страницы: @@ -360,7 +360,7 @@ Wireframe-прототип: ![Прототип списка заказов менеджера](/prototypes/manager-orders.svg) -### 5.5.5 Настройки каталога +### 7.5.5 Настройки каталога Назначение страницы: @@ -381,7 +381,7 @@ Wireframe-прототип: ![Прототип настроек каталога](/prototypes/catalog-settings.svg) -### 5.5.6 Настройки синхронизации и уведомлений +### 7.5.6 Настройки синхронизации и уведомлений Назначение страницы: @@ -399,7 +399,7 @@ Wireframe-прототип: ![Прототип настроек синхронизации](/prototypes/sync-settings.svg) -## 5.6 Дополнительные профильные и сервисные страницы +## 7.6 Дополнительные профильные и сервисные страницы Помимо основных клиентских и менеджерских экранов, программный продукт включает дополнительные экранные формы: diff --git a/docs/tz/technical-architecture.md b/docs/tz/technical-architecture.md index a38ba71..2134051 100644 --- a/docs/tz/technical-architecture.md +++ b/docs/tz/technical-architecture.md @@ -1,12 +1,12 @@ -# 7. Техническая архитектура, стек и состав компонентов +# 9. Техническая архитектура, стек, компоненты и эксплуатационный контур -## 7.1 Общая архитектурная схема +## 9.1 Общая архитектурная схема Программный продукт реализуется по клиент-серверной модели и включает веб-клиент, сервер бизнес-логики, базу данных, модуль интеграции и вспомогательные сервисы уведомлений. ![Общая архитектурная схема](/diagrams/architecture-overview.svg) -## 7.2 Состав прикладных сервисов +## 9.2 Состав прикладных сервисов Согласно действующей карте деплоя в составе проекта используются следующие сервисы: @@ -19,7 +19,7 @@ Основные прикладные сервисы `web-frontend` и `apollo-backend` разворачиваются через `dokploy_webhook` на сервере `main`. -## 7.3 Технологический стек фронтенда +## 9.3 Технологический стек фронтенда Клиентская часть программного продукта реализуется на следующих технологиях: @@ -31,7 +31,7 @@ - `Storybook` — контур изоляционного просмотра компонентов - `VitePress` — подготовка проектной документации -## 7.4 Технологический стек серверной части +## 9.4 Технологический стек серверной части Серверная часть программного продукта реализуется на следующих технологиях: @@ -43,7 +43,7 @@ - `Zod` — валидация структур данных в прикладных сценариях - `Nodemailer` — отправка уведомлений по электронной почте -## 7.5 Архитектура клиентской части +## 9.5 Архитектура клиентской части Клиентская часть организована по следующим слоям: @@ -64,11 +64,11 @@ - `/catalog-settings` — административные настройки каталога - `/bonus-program`, `/bonus-system/*` — бонусный контур -## 7.6 Карта слоев и компонентов +## 9.6 Карта слоев и компонентов ![Карта слоев и компонентов](/diagrams/component-map.svg) -## 7.7 Архитектура серверной части +## 9.7 Архитектура серверной части Серверная часть организована по следующим основным модулям: @@ -81,7 +81,7 @@ - `src/prisma-client.js` — точка подключения Prisma - `src/messenger*.js`, `src/telegram*.js`, `src/max-mini-app.js` — мессенджерный контур и мини-приложения -## 7.8 Взаимодействие фронтенда и backend +## 9.8 Взаимодействие фронтенда и backend Взаимодействие клиентской и серверной части строится через GraphQL API. @@ -98,7 +98,7 @@ - централизованно передавать авторизационные данные - поддерживать единый клиентский GraphQL endpoint -## 7.9 Интеграционные и вспомогательные HTTP-точки +## 9.9 Интеграционные и вспомогательные HTTP-точки Помимо GraphQL API, во фронтенд-контуре реализованы вспомогательные серверные маршруты: @@ -109,7 +109,7 @@ - `/api/dadata/party` — подсказки контрагентов - `/api/messenger-avatar/[connectionId]` — выдача изображений, связанных с мессенджерными подключениями -## 7.10 Компонентные требования к реализации +## 9.10 Компонентные требования к реализации Архитектура программного продукта должна сохранять следующие правила: @@ -120,13 +120,13 @@ - серверная логика доступа к данным должна проходить через Prisma - бизнес-правила доступа должны контролироваться серверной частью, а не только интерфейсом -## 7.11 Требования к конфигурации и секретам +## 9.11 Требования к конфигурации и секретам Сервисы программного продукта должны получать прикладные секреты из `Vault`. В конфигурации сервисов допускается хранение только bootstrap-параметров для подключения к Vault. Бизнес-секреты, ключи интеграций и иные чувствительные данные должны загружаться из Vault при старте приложения. -## 7.12 Инфраструктура, деплой и эксплуатационный контур +## 9.12 Инфраструктура, деплой и эксплуатационный контур Текущая инфраструктурная схема проекта включает прикладные сервисы, сервис секретов, мессенджерные сервисы и вспомогательный worker-контур. @@ -152,7 +152,7 @@ Эксплуатационные операции доступа и диагностики выполняются через Tailscale SSH. -## 7.13 Dokploy и цепочка развёртывания +## 9.13 Dokploy и цепочка развёртывания Для основных сервисов проекта используется режим `dokploy_webhook`. @@ -171,7 +171,7 @@ - `apollo-backend` стартует через загрузку Vault env, `prisma migrate deploy` и запуск `src/server.js` - bot-сервисы стартуют через общий паттерн загрузки Vault env и запуск `node src/server.js` -## 7.14 Vault и хранение секретов +## 9.14 Vault и хранение секретов Сервис `vault` развернут как отдельное приложение на базе образа `hashicorp/vault:1.21.3`. @@ -190,7 +190,7 @@ - загружает project secrets - экспортирует секреты в runtime environment процесса -## 7.15 Структура сервисных каталогов +## 9.15 Структура сервисных каталогов Текущая сервисная структура репозитория: @@ -203,7 +203,7 @@ - `vault` — Dockerfile, конфигурация и entrypoint Vault - `hatchet` — docker-compose инфраструктурного контура Hatchet -## 7.16 Контур фоновых процессов +## 9.16 Контур фоновых процессов В проекте присутствует отдельный контур фонового исполнения задач: @@ -214,7 +214,7 @@ Конфигурация этого контура находится в `hatchet/docker-compose.yml`. -## 7.17 Зафиксированные runtime-версии и технологические зависимости +## 9.17 Зафиксированные runtime-версии и технологические зависимости ### Базовые runtime и контейнерные образы @@ -237,12 +237,17 @@ | `@nuxtjs/apollo` | `5.0.0-alpha.16` | GraphQL-клиентский слой | | `@vue/apollo-composable` | `4.2.2` | composable API для GraphQL | | `@apollo/client` | `3.14.1` | Apollo client runtime | +| `@fullcalendar/core` | `6.1.20` | calendar runtime | +| `@fullcalendar/daygrid` | `6.1.20` | calendar day grid | +| `@fullcalendar/vue3` | `6.1.20` | Vue integration for calendar | | `@nuxt/eslint` | `1.15.2` | linting Nuxt-проекта | | `@nuxtjs/tailwindcss` | `6.14.0` | Tailwind integration | | `daisyui` | `5.5.19` | UI primitives | | `graphql` | `16.13.2` | GraphQL runtime | +| `mermaid` | `11.14.0` | diagrams in documentation | | `@sentry/vue` | `10.46.0` | error tracking | | `storybook` | `8.6.14` | UI component review | +| `vue-router` | `5.0.4` | Vue routing runtime | ### Основные зависимости backend @@ -259,7 +264,14 @@ | `nodemailer` | `8.0.4` | email notifications | | `dotenv` | `17.3.1` | env bootstrap in local/runtime layers | -## 7.18 Технические конфигурационные файлы +### Основные зависимости worker-контура + +| Библиотека | Версия | Назначение | +| --- | --- | --- | +| `@hatchet-dev/typescript-sdk` | `1.19.0` | worker runtime | +| `dotenv` | `17.3.1` | env bootstrap in local/runtime layers | + +## 9.18 Технические конфигурационные файлы Ключевые технические файлы текущей реализации: