67 lines
1.9 KiB
Markdown
67 lines
1.9 KiB
Markdown
|
# 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.
|
||
|
|
|
||
|
|
## Contract
|
||
|
|
|
||
|
|
`POST /api/v1/plans` accepts a planning request and a coordinate-free POI whitelist:
|
||
|
|
|
||
|
|
```json
|
||
|
|
{
|
||
|
|
"mode": "custom",
|
||
|
|
"preferences": {
|
||
|
|
"destination": "深圳市光明区",
|
||
|
|
"themes": ["亲子"],
|
||
|
|
"duration": "half_day",
|
||
|
|
"pace": "moderate",
|
||
|
|
"interests": ["自然风光"],
|
||
|
|
"adults": 2,
|
||
|
|
"children": 1,
|
||
|
|
"childAges": [6],
|
||
|
|
"transport": "public_transport",
|
||
|
|
"budgetLevel": "standard",
|
||
|
|
"extraRequirements": ""
|
||
|
|
},
|
||
|
|
"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
|
||
|
|
```
|