1.7 KiB
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.
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
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.
The cross-module plan for integrating manager-web and the xiaozhi-server realtime runtime is
maintained in docs/unified-fastapi-platform/README.md. It defines the staged PR queue, agent
ownership, automated quality gates, and the boundary where real hardware and external service
validation become mandatory.