diff --git a/docs/API_INTEGRATION.md b/docs/API_INTEGRATION.md
index 5283217a..35fa03cd 100644
--- a/docs/API_INTEGRATION.md
+++ b/docs/API_INTEGRATION.md
@@ -102,12 +102,13 @@ Qdrant 本地默认值可不配；需要覆盖时用 JVM property 或环境变
 
 ```bash
 TOKEN=<登录后 access_token>
-curl -fsS http://127.0.0.1:8080/api/aihr/org/sync \
+API_BASE=${API_BASE:-https://wygj-api.localhost}
+curl -fsS "$API_BASE/api/aihr/org/sync" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"dryRun":true}'
 
-curl -fsS http://127.0.0.1:8080/api/aihr/org/sync \
+curl -fsS "$API_BASE/api/aihr/org/sync" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"replaceExisting":true}'
@@ -138,7 +139,8 @@ curl -fsS http://127.0.0.1:8080/api/aihr/org/sync \
 ```bash
 ./scripts/demo-check.sh
 npm --prefix mobile-uni run build:h5
-curl -fsS http://127.0.0.1:8080/api/aihr/mobile/home/user
+API_BASE=${API_BASE:-https://wygj-api.localhost}
+curl -fsS "$API_BASE/api/aihr/mobile/home/user"
 npm --prefix frontend run lint:eslint -- src/api/aihr/interview.ts src/views/recruit/interview.vue src/api/aihr/practice.ts src/views/train/practice.vue src/api/aihr/case.ts src/views/knowledge/cases.vue src/api/aihr/sop.ts src/views/knowledge/sop.vue
 mvn -f backend/pom.xml -pl ruoyi-admin -am -DskipTests package
 ```
@@ -147,9 +149,10 @@ mvn -f backend/pom.xml -pl ruoyi-admin -am -DskipTests package
 
 ```bash
 TOKEN=<登录后 access_token>
-curl -fsS http://127.0.0.1:8080/api/aihr/model/providers -H "Authorization: Bearer $TOKEN"
-curl -fsS http://127.0.0.1:8080/api/aihr/model/configs -H "Authorization: Bearer $TOKEN"
-curl -fsS -X POST http://127.0.0.1:8080/api/aihr/model/chat \
+API_BASE=${API_BASE:-https://wygj-api.localhost}
+curl -fsS "$API_BASE/api/aihr/model/providers" -H "Authorization: Bearer $TOKEN"
+curl -fsS "$API_BASE/api/aihr/model/configs" -H "Authorization: Bearer $TOKEN"
+curl -fsS -X POST "$API_BASE/api/aihr/model/chat" \
   -H "Authorization: Bearer $TOKEN" \
   -H 'Content-Type: application/json' \
   -d '{"prompt":"物业管家处理漏水投诉第一步是什么？"}'
@@ -159,9 +162,10 @@ Qdrant 和向量索引可单独 smoke；重建接口会清空旧 embedding 并
 
 ```bash
 TOKEN=<登录后 access_token>
+API_BASE=${API_BASE:-https://wygj-api.localhost}
 curl -fsS http://127.0.0.1:6333/
-curl -fsS http://127.0.0.1:8080/api/knowledge/doc/vector-index-status -H "Authorization: Bearer $TOKEN"
-curl -fsS -X POST http://127.0.0.1:8080/api/knowledge/doc/rebuild-vector-index -H "Authorization: Bearer $TOKEN"
+curl -fsS "$API_BASE/api/knowledge/doc/vector-index-status" -H "Authorization: Bearer $TOKEN"
+curl -fsS -X POST "$API_BASE/api/knowledge/doc/rebuild-vector-index" -H "Authorization: Bearer $TOKEN"
 ```
 
 浏览器验收仍按 [DEMO_ACCEPTANCE.md](DEMO_ACCEPTANCE.md) 的四条关键路径执行。
diff --git a/docs/DEV_SETUP.md b/docs/DEV_SETUP.md
index 1d8f505f..9bc031b5 100644
--- a/docs/DEV_SETUP.md
+++ b/docs/DEV_SETUP.md
@@ -6,12 +6,12 @@
 - 管理端前端：`frontend`，来自 `CrazyLionCat/plus-ui` 的 `5.X` 分支
 - 用户侧前端：`mobile-uni`，uni-app Vue3 H5 工程；旧 `mobile` 仅保留为 MVP 演示兜底
 
-## 本地端口
+## 本地入口与依赖端口
 
 - 管理端前端：`https://wygj-admin.localhost/`
-- 旧移动端前端：`http://127.0.0.1:5174/h5/user`
 - uni-app 用户侧：`https://wygj-mobile-uni.localhost/h5/`
-- 后端：`https://wygj-api.localhost/`，显式 `PORTLESS=0` 时回退 `http://127.0.0.1:8080/`
+- 后端：`https://wygj-api.localhost/`
+- 固定端口仅用于显式 fallback：`PORTLESS=0 ./scripts/dev.sh` 时后端回退 `http://127.0.0.1:8080/`，旧移动端回退 `http://127.0.0.1:5174/h5/user`
 - MySQL：`127.0.0.1:13306`，数据库 `ry-vue`，账号 `root/root`
 - Redis：`127.0.0.1:16379`，密码 `ruoyi123`
 - MinIO API：`http://127.0.0.1:9000`，Console：`http://127.0.0.1:9001`，账号 `ruoyi / ruoyi123`，默认 bucket `ruoyi`