Initial commit: gmTouringMiniApp project

2026-07-30 16:04:34 +08:00
commit ebcae02d35
201 changed files with 49545 additions and 0 deletions
@@ -0,0 +1,66 @@
+# 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
+```