02-Architecture / 02.07.Rollback-Reporting-Refactor

02.07.Rollback Reporting Refactor

02.07. Rollback Reporting Refactor

Purpose

This document defines the rollback path for the March 13, 2026 reporting-core refactor work across:

• bnc-cpt-api
• bnc-cpt-wui
• bnc-cpt-utl

Use this plan if the reporting refactor causes regressions in:

• Tesla report generation
• session ownership or session resume
• async/sync PDF generation
• Docker build or API runtime startup
• WUI report retrieval or rendering

This is the source of truth for backout order, target SHAs, and file groups.

Rollback Principle

Rollback must restore the last known remote state first.

Do not attempt ad hoc file edits during an incident. Do not mix old and new logic during rollback. Either:

• reset fully to the last remote state if nothing has been pushed, or
• revert the pushed commits in controlled order if the changes have already been shared

Last Known Safe Remote Targets

These are the rollback targets for the refactor work described in this document.

• bnc-cpt-api -> 4d0e5c7
• bnc-cpt-wui -> 114ac0f
• bnc-cpt-utl -> b5bd4b4

Local-Only Refactor Commits

If these commits exist only locally, do not revert them. Reset to the remote target instead.

• bnc-cpt-api -> 445cdf5 refactor reporting core and document security architecture
• bnc-cpt-wui -> 781725b handle partial report generation results
• bnc-cpt-utl -> 1dbd362 package API locales in Docker images

What Changed

bnc-cpt-api

Commit 445cdf5 introduced:

• new architecture docs
• PDF localization packaging fix support
• async PDF API path and task handling changes
• session-bound PDF/report access tightening
• reporting-core refactor in tesla_fleet.py
• new Tesla auth and acquisition services

Additional local-only, uncommitted API work introduced:

• src/python/cpt-api/app/models/tesla_acquisition.py
• src/python/cpt-api/app/services/tesla_provider_normalization.py
• src/python/cpt-api/tests/test_tesla_normalization.py
• further changes in:
• src/python/cpt-api/app/api/v1/routers/tesla.py
• src/python/cpt-api/app/services/tesla_fleet.py

bnc-cpt-wui

Commit 781725b introduced:

• partial report-generation result handling
• outcome metadata plumbing in the store and API layer

Additional local-only, uncommitted WUI work introduced:

• src/vue/app/src/components/ReportDashboard.vue
• src/vue/app/src/services/api.ts
• src/vue/app/src/stores/app.ts
• further changes in src/vue/app/src/components/GeneratingStep.vue

bnc-cpt-utl

Commit 1dbd362 introduced:

• Dockerfile changes for locale packaging

Additional local-only, uncommitted UTL work introduced:

• further changes in:
• src/docker/cpt-api/Dockerfile.arm-mac
• src/docker/cpt-api/Dockerfile.x86_64

Incident Types And Rollback Scope

1. API report generation broken

Symptoms:

• reports fail to generate
• vehicle_data or module handling regresses
• session reports return errors or malformed data

Rollback scope:

• bnc-cpt-api
• possibly bnc-cpt-wui if the WUI has already been updated to depend on outcomes

2. PDF generation or PDF polling broken

Symptoms:

• sync PDF endpoint fails
• async PDF task polling fails
• session-bound report retrieval blocks valid requests

Rollback scope:

• bnc-cpt-api
• bnc-cpt-wui
• bnc-cpt-utl if Docker/runtime packaging is involved

3. API container build or startup broken

Symptoms:

• Docker build fails
• API container exits on startup
• /health fails

Rollback scope:

• bnc-cpt-utl
• bnc-cpt-api

4. WUI report rendering or session resume broken

Symptoms:

• report page does not resume
• report dashboard behaves incorrectly
• partial-data handling breaks report display

Rollback scope:

• bnc-cpt-wui
• possibly bnc-cpt-api if the response shape mismatch is the real cause

Backout Order

If changes have been pushed and must be reverted, use this order:

1. bnc-cpt-wui
2. bnc-cpt-api
3. bnc-cpt-utl

Reason:

• WUI is the edge consumer and can be reverted first to reduce contract mismatch
• API is the main reporting-core change
• UTL should be reverted when build/runtime packaging is part of the failure

If the failure is purely Docker build/startup, use:

1. bnc-cpt-utl
2. bnc-cpt-api

Fastest Full Local Rollback

Use this only if nothing has been pushed and the goal is to get back to the last remote state immediately.

bnc-cpt-api

git -C /opt/bnc/bnc-cpt/bnc-cpt-api reset --hard origin/master
git -C /opt/bnc/bnc-cpt/bnc-cpt-api clean -fd

bnc-cpt-wui

git -C /opt/bnc/bnc-cpt/bnc-cpt-wui reset --hard origin/master

bnc-cpt-utl

git -C /opt/bnc/bnc-cpt/bnc-cpt-utl reset --hard origin/master

Effect:

• removes all local refactor commits
• removes all unstaged changes
• removes all untracked new API files
• restores each repo to the last remote target SHA

Safe Shared-History Rollback

Use this if commits have already been pushed or deployed.

Do not reset --hard shared history. Use git revert.

bnc-cpt-wui

git -C /opt/bnc/bnc-cpt/bnc-cpt-wui revert 781725b

bnc-cpt-api

git -C /opt/bnc/bnc-cpt/bnc-cpt-api revert 445cdf5

bnc-cpt-utl

git -C /opt/bnc/bnc-cpt/bnc-cpt-utl revert 1dbd362

Notes:

• local uncommitted changes must be stashed, committed, or discarded first
• these revert commands do not include the still-uncommitted local changes listed in this document

File Groups To Remove First If The Refactor Must Be Unwound

Highest-risk API code

• src/python/cpt-api/app/services/tesla_fleet.py
• src/python/cpt-api/app/api/v1/routers/tesla.py
• src/python/cpt-api/app/models/tesla.py
• src/python/cpt-api/app/services/i18n.py
• src/python/cpt-api/app/services/tesla_provider_auth.py
• src/python/cpt-api/app/services/tesla_provider_acquisition.py
• src/python/cpt-api/app/models/tesla_acquisition.py
• src/python/cpt-api/app/services/tesla_provider_normalization.py

Highest-risk WUI code

• src/vue/app/src/components/GeneratingStep.vue
• src/vue/app/src/components/ReportDashboard.vue
• src/vue/app/src/services/api.ts
• src/vue/app/src/stores/app.ts

Highest-risk Docker/runtime files

• src/docker/cpt-api/Dockerfile.x86_64
• src/docker/cpt-api/Dockerfile.arm-mac

Targeted Partial Rollback

Use this only if documentation should be kept but risky code should be removed.

Recommended process:

1. create a rescue branch
2. restore risky code files from origin/master
3. delete newly added untracked files
4. keep documentation files if desired

Example: API targeted partial rollback

git -C /opt/bnc/bnc-cpt/bnc-cpt-api switch -c rescue/reporting-refactor
git -C /opt/bnc/bnc-cpt/bnc-cpt-api restore --source=origin/master src/python/cpt-api/app/api/v1/routers/tesla.py
git -C /opt/bnc/bnc-cpt/bnc-cpt-api restore --source=origin/master src/python/cpt-api/app/models/tesla.py
git -C /opt/bnc/bnc-cpt/bnc-cpt-api restore --source=origin/master src/python/cpt-api/app/services/i18n.py
git -C /opt/bnc/bnc-cpt/bnc-cpt-api restore --source=origin/master src/python/cpt-api/app/services/tesla_fleet.py
git -C /opt/bnc/bnc-cpt/bnc-cpt-api restore --source=origin/master src/python/cpt-api/app/__init__.py
git -C /opt/bnc/bnc-cpt/bnc-cpt-api restore --source=origin/master src/python/cpt-api/app/services/__init__.py
rm -f /opt/bnc/bnc-cpt/bnc-cpt-api/src/python/cpt-api/app/models/tesla_acquisition.py
rm -f /opt/bnc/bnc-cpt/bnc-cpt-api/src/python/cpt-api/app/services/tesla_provider_normalization.py
rm -f /opt/bnc/bnc-cpt/bnc-cpt-api/src/python/cpt-api/tests/test_tesla_normalization.py

Use the same pattern for WUI and UTL if only part of the refactor must be removed.

Pre-Push Safety Step

Before any push, create a backup branch in each touched repo.

git -C /opt/bnc/bnc-cpt/bnc-cpt-api switch -c backup/reporting-refactor-2026-03-13
git -C /opt/bnc/bnc-cpt/bnc-cpt-wui switch -c backup/reporting-refactor-2026-03-13
git -C /opt/bnc/bnc-cpt/bnc-cpt-utl switch -c backup/reporting-refactor-2026-03-13

This does not replace rollback, but it preserves the exact local state before any push or reset.

Validation After Rollback

After any rollback, verify:

1. API build or container startup works again
2. /health returns 200
3. session resume works
4. report generation works
5. PDF generation works
6. WUI report page loads correctly

If rollback restores build/startup but not reporting, rollback was incomplete.

Decision Rule

Use full rollback if:

• report generation is broken
• session ownership looks unsafe
• API startup or Docker build regresses
• the runtime state is unclear and time matters more than preserving refactor work

Use targeted partial rollback only if:

• documentation should remain
• the failure is isolated
• there is clear confidence about which file group caused the problem