This FastAPI service is the server-only AI boundary for the Guangming travel POC. It defaults to deterministic mock mode. Model credentials belong only in server/.env or the deployment environment and must never be added to the mini-program build.

This service is reserved for a later AI integration phase. The current mini-program createPlan entry point is hard-wired to the local planner and does not call this service.

Contract

POST /api/v1/plans accepts a planning request and a coordinate-free POI whitelist:

{
  "mode": "custom",
  "preferences": {
    "destination": "深圳市光明区",
    "themes": ["亲子"],
    "pace": "moderate",
    "interests": ["自然风光"],
    "transport": "public_transport"
  },
  "durationMinutes": 240,
  "selectedPoiIds": ["poi_a", "poi_b"],
  "candidates": [
    {
      "id": "poi_a",
      "name": "Example A",
      "categoryCode": "urban_park",
      "tagCodes": ["family_friendly"],
      "summary": "Coordinate-free summary",
      "recommendationIndex": 4
    },
    {
      "id": "poi_b",
      "name": "Example B",
      "categoryCode": "cultural_venue",
      "tagCodes": ["indoor_venue"],
      "summary": "Coordinate-free summary",
      "recommendationIndex": 5
    }
  ]
}

The response contains only POI IDs, reasons, and suggested order. In custom mode all 2-8 user-selected IDs are retained. The model never receives origin, and never owns coordinates, route geometry, transfer estimates, or final itinerary time; those remain deterministic client responsibilities.

GET /api/v1/health reports mode (mock or real), whether real-model credentials are configured, and whether the selected mode is ready.

Run locally

cd server
python3 -m venv .venv
.venv/bin/python -m pip install -e '.[test]'
cd ..
corepack pnpm server:dev

Run tests from the repository root:

corepack pnpm server:test