feat: align tenant site builder with real api

README.md

@@ -24,11 +24,11 @@ npm run check:production
 
 ```dotenv
 VITE_DATA_MODE=mock
-VITE_API_BASE_URL=
+VITE_DEV_API_TARGET=http://localhost:5090
 ```
 
 - `mock`：仅 Development 动态加载 MSW；生产构建不会包含 Worker、启动器、示例 Token 或 Mock 状态。
-- `api`：使用同源 `/api`，也可在开发期通过 `VITE_API_BASE_URL` 代理到 .NET API。
+- `api`：浏览器固定使用同源 `/api`；Development 的 Vite 服务通过 `VITE_DEV_API_TARGET` 代理到 .NET API，并保留浏览器原始 Host。
 
 页面只能调用 `src/api` 下的领域 Client，不能直接调用 `fetch`。前端请求不携带任意 `tenantId`；真实租户由 Host 与受保护 Session 决定。
 
@@ -42,7 +42,7 @@ VITE_API_BASE_URL=
 | `/manage/*` | 必须通过租户 Backoffice Bootstrap；无 Permission 的账号统一显示 404 |
 | `/__demo` | 仅开发环境存在的生命周期启动器 |
 
-后台菜单来自 `GET /api/backoffice/tenant/bootstrap`。进入站点设计还必须包含 `tenant:settings:manage`，前端隐藏菜单不能替代后端 401/403。
+后台菜单来自 `GET /api/backoffice/tenant/ui-bootstrap`。进入站点设计还必须包含 `tenant:settings:manage`，前端隐藏菜单不能替代后端 401/403。
 
 ## 前后端契约
 
@@ -51,11 +51,41 @@ VITE_API_BASE_URL=
 - `GET /api/runtime/bootstrap`
 - `POST /api/browser-auth/activation/complete`
 - `POST /api/browser-auth/login/password`
-- `GET /api/backoffice/tenant/bootstrap`
+- `GET /api/backoffice/tenant/ui-bootstrap`
 - `GET /api/tenant-onboarding/status`
 - `GET|PUT|POST /api/tenant-admin/frontend-config/**`
 
-后端目前已有 `/api/auth/activation/complete`，但只返回 204。目标 Browser Auth 激活接口需要在完成密码设置后签发 HttpOnly Session Cookie，并返回当前用户摘要，前端才能安全地自动进入建站向导。
+Browser Auth 激活接口会在完成密码设置后签发 HttpOnly Session Cookie；后续写请求从 `__Host-tiku-csrf` Cookie 读取双提交 Token，并发送 `X-CSRF-Token`。
+
+## 真实后端建站流程
+
+先按后端 `docs/quickstart.md` 初始化空数据库，在平台端创建 `school.localhost` 租户并领取 Owner 激活链接。然后启动本项目：
+
+```bash
+VITE_DATA_MODE=api \
+VITE_DEV_API_TARGET='http://localhost:5090' \
+npm run dev -- --host 0.0.0.0 --port 5180
+```
+
+真实流程如下：
+
+1. 打开平台签发的完整 `/activate/:activationId#token=...` 链接；
+2. Token 读入后立即从地址栏清除；
+3. Owner 设置密码，后端签发 Secure/HttpOnly Session Cookie；
+4. 自动进入 `/manage/onboarding`；
+5. 完成品牌、模板、主题、模块、桌面/移动预览并发布；
+6. 刷新 `/`，学生端读取已发布版本；
+7. 退出后在 `/manage/login` 使用 Owner 账号重新登录。
+
+平台管理员无需确认 Owner 密码或网站发布。站点未发布时的“管理员确认发布”指租户后台拥有站点配置权限的用户执行发布，不是平台二次审批。
+
+## 常见问题
+
+- 激活请求只有 OPTIONS、没有 POST：不要设置旧的 `VITE_API_BASE_URL`；使用 `VITE_DEV_API_TARGET` 并重启 Vite，浏览器请求必须保持同源 `/api`。
+- 激活失败后 Fragment 已清除：未消费时重新打开原始完整链接；已消费、过期或丢失时由平台撤销重签。
+- 发布后旧标签仍显示筹备页：刷新学生端，让 Runtime Bootstrap 重新读取已发布版本。
+- `school.localhost` 串租户或无法登录：确认代理为 `changeOrigin: false`，不要改用 `localhost:5180`，也不要在请求中发送 `tenantId`。
+- 后台没有菜单：菜单只映射后端 Bootstrap 已返回且当前前端已实现的 `tenant.dashboard` 和 `tenant.site-content`；站点配置还要求 `tenant:settings:manage`。
 
 ## 与旧系统的边界