docs: контракт для агентов, архитектура и план фаз

AGENTS.md — индекс, команды и обязательные ограничения (Decimal для денег, не конвертировать валюту на записи, SDK T-Invest ровно в одном модуле, аналитика читает только confirmed). docs/ai/ — архитектура, соглашения, эксплуатация и полный план на шесть фаз с проверками для каждой.
2026-09-18 13:43:31 +03:00
parent 563308a08b
commit 220f027652
7 changed files with 836 additions and 0 deletions
@@ -0,0 +1,48 @@
+# Внешние API и референсы
+
+| Что | Ссылка | Заметки |
+|---|---|---|
+| ZenMoney API | https://github.com/zenmoney/ZenPlugins/wiki/ZenMoney-API | только `/v8/diff/` и `/v8/suggest/`; токен 24 ч + refresh |
+| T-Invest API | https://developer.tbank.ru/invest/api | gRPC; лимиты Operations/Instruments 200/мин, MarketData 600/мин |
+| T-Invest Python SDK | индекс `https://opensource.tbank.ru/api/v4/projects/238/packages/pypi/simple` | пакет `t-tech-investments` |
+| MOEX ISS | https://iss.moex.com/iss/reference/ | без ключа; history, dividends, bondization, индексы |
+| ЦБ РФ курсы | https://www.cbr.ru/scripts/XML_dynamic.asp | cp1251, делить на `Nominal` |
+| pyxirr | https://github.com/Anexen/pyxirr | XIRR/TWR |
+| investbook | https://github.com/spacious-team/investbook | референс форматов отчётов Сбер/ВТБ (Java) |
+| invest_toolkit | https://github.com/i-savelev/invest_toolkit | парсеры Сбер/ВТБ на Python |
+| Соседние проекты | `../fin-dashboard`, `../t_tech-gyro` | ZenMoney diff-цикл, CBR fx, T-Invest адаптер + CA-сертификаты |
+
+## Что выяснилось при реализации фазы 1 (источники)
+
+### ZenMoney `/v8/diff/`
+- Тело запроса: `{"currentClientTimestamp": <unix now>, "serverTimestamp": <курсор|0>,
+  "forceFetch": [типы]}`; `forceFetch` отправляем только при курсоре 0. Ответ — те же
+  массивы сущностей (только изменённые), `deletion: [{id, object, stamp, user}]` и новый
+  `serverTimestamp`.
+- Типы сущностей: `instrument, company, user, account, tag, merchant, budget, reminder,
+  reminderMarker, transaction`. `company`, `user`, `budget`, `reminder*` храним только в
+  raw — в core они пока не нужны.
+- `account.type = ccard` маппится в `AccountKind.zm_card` (в enum нет `zm_ccard`),
+  остальные типы — буквально `zm_<type>`.
+- Токен живёт 86400 с. Ротация: `POST https://api.zenmoney.ru/oauth2/token/`,
+  form-encoded `grant_type=refresh_token&refresh_token=…&client_id=…&client_secret=…`,
+  ответ `{access_token, refresh_token, expires_in, token_type}`. Пара лежит в
+  `source_credential(source='zenmoney')`, засеивается из `ZENMONEY_REFRESH_TOKEN`.
+- Статический токен (zerro.app/token) при 401 нечем обновить — источник падает с
+  явным требованием обновить `ZENMONEY_TOKEN`.
+
+### Прокси на хосте `ada-x1`
+- `ALL_PROXY=socks5h://…`, поэтому `httpx.AsyncClient(trust_env=True)` требует extra
+  `httpx[socks]` (пакет `socksio`) — он добавлен в зависимости, иначе клиент падает на
+  конструировании ещё до запроса.
+- api.zenmoney.ru доступен через прокси (`trust_env=True`, по умолчанию).
+  cbr.ru через этот прокси роняет TLS → CBR-клиент строится с `trust_env=False`.
+
+### ЦБ РФ
+- `XML_daily.asp?date_req=DD/MM/YYYY` нужен только ради карты `CharCode -> ID`
+  (`USD -> R01235`, `JPY -> R01820`); на 17.09.2026 отдаёт 54 валюты.
+- `XML_dynamic.asp?date_req1=…&date_req2=…&VAL_NM_RQ=<ID>` — `<Record Date="dd.mm.yyyy">`
+  с `<Nominal>` и `<Value>` (запятая как разделитель). Кодировка windows-1251.
+  В `raw_cbr_rate` кладём `value` и `nominal` как напечатано; деление на номинал —
+  в `pricing/fx.py`.
+- Крипта и металлы (XAU, BTC …) ЦБ не котирует — уходят в `warnings`, не в ошибку.