sub2api-cn-relay-manager/docs/KNOWN_LIMITATIONS.md

# Known Limitations & Production Gaps (V0.1)

This document covers known limitations that operators should be aware of before deploying `sub2api-cn-relay-manager` v0.1 to production.

## Core Limitations

### 1. Automated Reconcile Is Available, but Disabled by Default (P2)
- A built-in background reconcile worker is now available in the control plane server.
- It is gated by `SUB2API_CRM_RECONCILE_WORKER_ENABLED=true` and uses `SUB2API_CRM_RECONCILE_POLL_INTERVAL` for cadence.
- The current scheduler model is still a simple polling runner rather than a full generic jobs platform.
- Manual `POST /api/providers/{providerID}/reconcile` and CLI reconcile remain supported.

### 2. Real sub2api Compatibility Is Verified on a Fresh Host, but Requires Explicit Operator Preparation
- Real-host validation has now been executed against a fresh redeployed sub2api host.
- Evidence: `artifacts/real-host-acceptance/20260518_redeploy_matrix`.
- Both `self_service` and `subscription` ordinary-user access paths reached `/v1/models -> 200`.
- However, host initialization alone is not enough: operators must explicitly create ordinary users, keep reusable credentials, bind keys to the correct group, and satisfy the billing/subscription prerequisites documented in `docs/REAL_HOST_ACCEPTANCE_RUNBOOK.md`.
- This is therefore no longer a code-compatibility blocker; it is an explicit operational prerequisite.

### 3. Standard Multi-stage Docker Build Still Depends on Outbound Module Download
- `Dockerfile.local` has been validated as the recommended proxy-safe build path.
- `scripts/deploy/build_local_image.sh` now prebuilds the Linux binary on the host and produces `sub2api-cn-relay-manager:local` reliably in this environment.
- The standard multi-stage `Dockerfile` still requires outbound Go module download from inside the container build context; in restricted networks, prefer the local-image path.

## Accepted Design Trade-offs

### 4. CLI Run Functions Not Unit-Tested
- `runInstallPack`, `runImportProvider`, `runPreviewProvider`, `runRollbackProvider`, `runReconcileProvider`, `findProvider` connect to real SQLite/sub2api — these are 0% covered in unit tests.
- The `execute()` dispatch and all `parse*` functions are fully tested.
- In an integration/E2E context these functions are exercised through the host stub.

### 5. No Web UI
- Administration is through CLI and HTTP API only.
- Consistent with MVP scope defined in PRD.

## Operational Notes

### Token Security
- `SUB2API_CRM_ADMIN_TOKEN` must be at least 20 characters, rotated outside source control.
- To support continuous background reconcile, the latest access closure now persists probe metadata in control-plane state:
  `self_service` stores the probe API key, and `subscription` stores the subscription user selector metadata.
- Operators should therefore treat the SQLite database as secret-bearing state and protect it accordingly.

### Database
- SQLite is the only supported database backend for v0.1.
- SQLite WAL mode is handled automatically by the driver.
- For high availability, mount the SQLite file on persistent storage (host volume or NFS).
- No external DB migration tool is needed — Flyway-style migrations are embedded in the binary.

### Monitoring
- Only `/healthz` endpoint is available for container orchestration liveness checks.
- No metrics, structured logging, or APM integration in v0.1.
- Use standard log collection (stdout/json) for observability.