2026-07-20 17:00:13 +08:00
|
|
|
# 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`.
|
2026-07-20 17:03:11 +08:00
|
|
|
|
|
|
|
|
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.
|
