docs: add phase 2 Bitrix24 implementation plan

This commit is contained in:
Ilgiz Kamelyev 2026-05-29 19:12:49 +05:00
parent 84c6287ecd
commit 99cddf8b9a
1 changed files with 61 additions and 0 deletions

View File

@ -0,0 +1,61 @@
# Phase 2: Bitrix24 API Integration
## Summary
- Implement Bitrix24 as a first-class `SourceAdapter`.
- Use `tmp/get_calls_via_Bitrix24_REST_v1.py` as the working prototype for REST calls, pagination, rate limiting, recording downloads, and diagnostics.
- Target CLI: `b24calls discover --source bitrix24`.
- Download call recordings during discovery so the existing validation, spool, transcription, and export pipeline continues to operate on local audio files.
## Commit Plan
1. `docs: add phase 2 Bitrix24 implementation plan`
- Add this plan.
- Document required webhook scopes: `telephony` and `disk`; `user` is only needed for optional user enrichment.
2. `config: expand Bitrix24 settings`
- Extend `Bitrix24Config` with `recordings_dir`, `download_recordings`, `enrich_users`, and `timeout_seconds`.
- Add `B24CALLS_BITRIX24_*` environment overrides.
- Update `configs/example.toml`.
3. `bitrix24: add REST client`
- Add a standard-library REST client.
- Support `voximplant.statistic.get`, `disk.file.get`, optional `user.get`, form-encoded POST, pagination, rate limiting, timeouts, and clear diagnostics.
4. `bitrix24: implement source adapter and recording download`
- Add `Bitrix24Source`.
- Download by `CALL_RECORD_URL`, or by `RECORD_FILE_ID -> disk.file.get -> DOWNLOAD_URL`.
- Store recordings in `bitrix24.recordings_dir`.
- Skip existing non-empty local files.
- Use Bitrix24 call `ID` as `source_id` and store raw call metadata.
5. `discovery: route discover by source`
- Add `b24calls discover --source local|bitrix24`, default `local`.
- Register downloaded Bitrix24 recordings through the existing SQLite discovery flow.
- Print `download_failed` in discovery summaries.
6. `tests: cover Bitrix24 discovery`
- Cover REST pagination and errors with fake HTTP transport.
- Cover direct URL download, `RECORD_FILE_ID` download, missing recordings, repeat discovery, config overrides, and CLI source routing.
- Keep local discovery tests unchanged.
7. `docs: document Bitrix24 workflow`
- Update README with command examples and webhook scope requirements.
- Mark `tmp/get_calls_via_Bitrix24_REST_v1.py` as a diagnostic prototype, not the runtime path.
## Verification
- `python -m compileall src tests`
- `python -m unittest discover -s tests`
- Manual smoke test with a real webhook:
- `b24calls discover --source bitrix24 --start YYYY-MM-DD --end YYYY-MM-DD`
- `b24calls validate`
- `b24calls spool`
- `b24calls transcribe --limit 1`
## Assumptions
- Recording download happens in `discover`.
- `telephony` scope is required for call statistics.
- `disk` scope is required for `RECORD_FILE_ID` downloads.
- `user` scope is optional and only needed when user enrichment is enabled.