feat: add FastAPI manager API compatibility baseline

2026-07-23 23:53:55 +08:00 · 2026-07-20 17:00:13 +08:00
parent 7c58fa37b2
commit 804ddb51f2
140 changed files with 47169 additions and 1 deletions
@@ -0,0 +1,38 @@
+# manager-api-fastapi
+
+`manager-api-fastapi` is the Python/FastAPI implementation of the existing Spring Boot
+`main/manager-api`. The Java service remains in the repository as the contract baseline,
+Liquibase migration owner, and rollback implementation.
+
+## Local development
+
+The service requires Python 3.10, MySQL 8, and Redis 5 or newer. Never point tests at a
+development database: the integration harness creates a dedicated database and Redis
+namespace/instance.
+
+```bash
+cd main/manager-api-fastapi
+cp .env.example .env
+uv sync --locked
+uv run python -m app
+```
+
+The compatible base URL is `http://127.0.0.1:8002/xiaozhi`. OpenAPI is exposed at
+`/xiaozhi/v3/api-docs` and the Swagger UI at `/xiaozhi/doc.html`.
+
+Production must set `APP_DATABASE_URL`, `APP_REDIS_URL`, `APP_UPLOAD_DIR`, and
+`APP_JAVA_RESOURCES_DIR`. The last path must contain the original Java i18n resources and
+Liquibase changelog. `APP_SERVER_SECRET_OVERRIDE` is reserved for isolated tests; leaving it
+set in a deployment bypasses the database-backed `server.secret` lookup and is unsupported.
+
+## Commands
+
+```bash
+uv run pytest
+uv run ruff check app tests scripts
+uv run mypy app
+uv run python scripts/extract_java_routes.py --output compatibility/java-routes.json
+```
+
+Migration, container, differential-contract, and cutover instructions are maintained in the
+repository-level migration documents under `docs/manager-api-fastapi-*.md`.