From b1906c8e3ca242a0e30bd63519504c0c070f0354 Mon Sep 17 00:00:00 2001 From: Sergey Krylov Date: Sat, 12 Sep 2026 14:45:47 +0300 Subject: [PATCH] docs: update routes to system documentation --- .ai/SOURCES.md | 12 ++++++------ .ai/conventions/backend-data.md | 4 ++-- .ai/conventions/backend-integrations.md | 6 +++--- .ai/conventions/backend-testing.md | 2 +- .ai/conventions/security-auth.md | 4 ++-- README.md | 6 +++--- 6 files changed, 17 insertions(+), 17 deletions(-) diff --git a/.ai/SOURCES.md b/.ai/SOURCES.md index 35b74d0..8a78838 100644 --- a/.ai/SOURCES.md +++ b/.ai/SOURCES.md @@ -3,12 +3,12 @@ | Что нужно установить | Владелец | | --- | --- | | Implementation decision и безопасный pattern | [CONVENTIONS](CONVENTIONS.md) | -| HTTP errors, DTO semantics, public wire shape | [docs: HTTP API](../../docs/AI_INDEX.md#http-api); runtime OpenAPI из Nest — единственный editable source | -| Auth/session, account access, token encryption | [docs: Security](../../docs/AI_INDEX.md#security) | -| Prisma schema/data ownership и migration context | [docs: Data](../../docs/AI_INDEX.md#data) | -| T-Bank/gRPC/cache, logging | [docs: Integrations](../../docs/AI_INDEX.md#integrations) | -| Money, account/position/income/cache meanings | [docs: Domain](../../docs/AI_INDEX.md#domain) | -| Поведение конкретной feature | [docs: Features](../../docs/AI_INDEX.md#features) | +| HTTP errors, DTO semantics, public wire shape | [docs: HTTP API](../../docs/architecture/http-api.md); runtime OpenAPI из Nest — единственный editable source | +| Auth/session, account access, token encryption | [Аутентификация](../../docs/domains/authentication/overview.md), [доступ к данным](../../docs/architecture/containers.md#хранимые-данные-и-границы-доступа), [подключение брокера](../../docs/integrations/tbank.md) | +| Prisma schema/data ownership и migration context | [docs: Data](../../docs/architecture/containers.md#хранимые-данные-и-границы-доступа) | +| T-Bank/gRPC/cache, logging | [T-Bank](../../docs/integrations/tbank.md), [свежесть данных](../../docs/architecture/cross-cutting/data-freshness.md), [наблюдаемость](../../docs/architecture/http-api.md#наблюдаемость) | +| Money, account/position/income/cache meanings | [docs: Domain](../../docs/glossary.md) | +| Поведение конкретной feature | [docs: Features](../../docs/README.md#предметные-области) | | Существующие behavioral requirements при необходимости | [specs index](../../specs/AI_INDEX.md) | | Versions/scripts и scope автоматических checks | package.json/lockfile, ESLint/TypeScript/Jest/Prisma configs | diff --git a/.ai/conventions/backend-data.md b/.ai/conventions/backend-data.md index d446ae0..fb66c33 100644 --- a/.ai/conventions/backend-data.md +++ b/.ai/conventions/backend-data.md @@ -23,14 +23,14 @@ application checks. Предварительный lookup не заменяет Transaction не охватывает сетевой T-Bank вызов как будто это одна atomic DB операция. Планируй порядок и compensation по текущей задаче; не удерживай DB lock во время retry внешней сети. Access/cache generation semantics — у -[T-Bank source](../../../docs/features/tbank-connection.md#граница-финансового-кэша). +[T-Bank source](../../../docs/integrations/tbank.md#граница-финансового-кэша). ## Деньги и точность Для денежных значений используй existing decimal helpers и строковый wire value, не JS floating-point арифметику для сумм. Currency — отдельная часть Money; разные валюты не складываются без явно заданного conversion contract. -Источник: [Money](../../../docs/architecture/domain-glossary.md#money), +Источник: [Money](../../../docs/glossary.md#money), пример: [decimal.ts](../../src/tbank/decimal.ts). UI formatting не меняет backend ownership расчётов и доменную семантику. diff --git a/.ai/conventions/backend-integrations.md b/.ai/conventions/backend-integrations.md index 5b3665e..f41eac9 100644 --- a/.ai/conventions/backend-integrations.md +++ b/.ai/conventions/backend-integrations.md @@ -6,7 +6,7 @@ T-Bank gRPC принадлежит TbankClient; MOEX metadata — MoexClient. С получают нормализованный результат через эти clients. Frontend не вызывает T-Bank и не получает credentials/proto client. Reference source — [ADR 003](../../../docs/adr/003-tbank-server-side-grpc-boundary.md) и -[connection behavior](../../../docs/features/tbank-connection.md). +[connection behavior](../../../docs/integrations/tbank.md). Для нового account use case сначала используй TbankAccessService: access, connection generation и invalid-token translation не дублируются в callers. @@ -18,13 +18,13 @@ Existing client уже владеет bounded FIFO queue, rate limit, deadline классификацией. Новый RPC проходит тот же путь; не добавляй вложенный retry loop в service. Не отключай TLS verification ради окружения: используй документированный CA mechanism. Точные параметры и ограничения принадлежат -[connection configuration](../../../docs/features/tbank-connection.md#конфигурация-и-ограничения). +[connection configuration](../../../docs/integrations/tbank.md#конфигурация-и-ограничения). При query/cache change установи key, user/account/generation ownership, freshness и поведение late response. Старый результат не может обслужить новую connection generation. Client Cached Snapshot frontend отличается от backend cache/stale policy; semantics конкретного use case читай через -[feature index](../../../docs/AI_INDEX.md#features). +[feature index](../../../docs/README.md#предметные-области). Внешний auth failure и временная недоступность имеют разные public codes; raw gRPC exception не уходит клиенту. Existing translation — в TbankTokenService diff --git a/.ai/conventions/backend-testing.md b/.ai/conventions/backend-testing.md index 714257d..6a083af 100644 --- a/.ai/conventions/backend-testing.md +++ b/.ai/conventions/backend-testing.md @@ -37,7 +37,7 @@ Unit specs colocated в `src/**/*.spec.ts`; HTTP/integration — `test/`. `npm run test:openapi-contract` — отдельный required check при wire contract change. `npm run test:e2e` существует, но известный Prisma migration blocker описан в -[backend workflow](../../../docs/development/backend-workflow.md) и WL-P2-05 +[ограничении сквозной проверки](../../../docs/development/verification.md#известное-ограничение-сквозной-проверки) и WL-P2-05 [registry](../../../docs/development/audit-remediation.md). Скрипт использует фиксированную `/tmp/wealth-ledger-e2e.db`; не запускай его конкурентно как независимые DB tests. Для isolation выбери отдельную test DB и runner configuration. diff --git a/.ai/conventions/security-auth.md b/.ai/conventions/security-auth.md index d7a9012..9bb0798 100644 --- a/.ai/conventions/security-auth.md +++ b/.ai/conventions/security-auth.md @@ -10,7 +10,7 @@ account access/connection generation — TbankAccessService; token crypto — TbankTokenService/TbankCrypto. Расширяй существующую boundary, не добавляй второй JWT middleware, decrypt helper или refresh coordinator. -[Authentication](../../../docs/features/authentication.md) и +[Authentication](../../../docs/domains/authentication/overview.md) и [ADR 006](../../../docs/adr/006-auth-session-policy.md)/[009](../../../docs/adr/009-concurrent-refresh-rotation-policy.md) задают session semantics. Access хранится только в памяти frontend; refresh передаётся httpOnly cookie. Source code конфигурации cookie — @@ -32,7 +32,7 @@ cases для соответствующего изменения. T-Bank credentials остаются server-side и хранятся encrypted. Используй existing AES-256-GCM boundary с validated 32-byte key; не печатай plaintext, шифротекст, cookie, Authorization или connection generation в logs/errors/API. -[Connection source](../../../docs/features/tbank-connection.md) определяет +[Connection source](../../../docs/integrations/tbank.md) определяет cache invalidation при замене/deletion и ограничение key rotation. Не передавай Prisma User/Session целиком наружу; выбирай public DTO. Пароль diff --git a/README.md b/README.md index b805faa..24b1e62 100644 --- a/README.md +++ b/README.md @@ -42,11 +42,11 @@ engine останавливает migration до запуска Jest. Точны - [HTTP API](.ai/conventions/backend-http-api.md), [data](.ai/conventions/backend-data.md) и [testing](.ai/conventions/backend-testing.md) - [Security/auth](.ai/conventions/security-auth.md) и [integrations](.ai/conventions/backend-integrations.md) -- [Backend workflow](../docs/development/backend-workflow.md) +- [Границы проверки API и данных](../docs/development/verification.md#api-и-хранение-данных) - [Engineering governance и risk-based testing](../docs/development/engineering-governance.md) -- [Карта проектных фактов](../docs/AI_INDEX.md) +- [Карта проектных фактов](../docs/README.md) - [API contract и runtime OpenAPI](../docs/development/runtime-openapi-verification.md) -- [Обзор поставленной системы](../docs/architecture/system-overview.md) +- [Обзор поставленной системы](../docs/overview.md) - [Архитектурные решения](../docs/adr/README.md) - [Remediation registry](../docs/development/audit-remediation.md)