gmTouringMiniApp/server/README.md

# Travel recommendation backend

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:

```json
{
  "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

```bash
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:

```bash
corepack pnpm server:test
```