93 lines
4.4 KiB
Markdown
93 lines
4.4 KiB
Markdown
# Tiku SaaS Web
|
||
|
||
租户建站与学生端前端。项目是单应用双 Shell：学生端使用 Tailwind CSS，租户后台使用 Ant Design。当前版本优先完成一次性 Owner 激活、建站引导、主题和首页模块配置、预览与发布闭环。
|
||
|
||
## 开发
|
||
|
||
要求 Node.js 24+ 与 npm 11+。
|
||
|
||
```bash
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
默认访问 `http://localhost:5180/__demo`，创建或重置租户并复制一次性激活链接。Mock 数据按开发模拟 Host 保存在浏览器 `localStorage`，刷新页面不会丢失。
|
||
|
||
```bash
|
||
npm test
|
||
npm run check:production
|
||
```
|
||
|
||
## 数据模式
|
||
|
||
复制 `.env.example` 为 `.env.local`：
|
||
|
||
```dotenv
|
||
VITE_DATA_MODE=mock
|
||
VITE_DEV_API_TARGET=http://localhost:5090
|
||
```
|
||
|
||
- `mock`：仅 Development 动态加载 MSW；生产构建不会包含 Worker、启动器、示例 Token 或 Mock 状态。
|
||
- `api`：浏览器固定使用同源 `/api`；Development 的 Vite 服务通过 `VITE_DEV_API_TARGET` 代理到 .NET API，并保留浏览器原始 Host。
|
||
|
||
页面只能调用 `src/api` 下的领域 Client，不能直接调用 `fetch`。前端请求不携带任意 `tenantId`；真实租户由 Host 与受保护 Session 决定。
|
||
|
||
## 路由和权限
|
||
|
||
| 路由 | 行为 |
|
||
| --- | --- |
|
||
| `/` | 学生端；根据 Runtime 的站点状态显示内容、筹备、暂停或域名接入页面 |
|
||
| `/activate/:activationId#token=...` | 一次性 Owner 激活；Token 读入后立即从地址栏移除 |
|
||
| `/manage/login` | 租户后台登录 |
|
||
| `/manage/*` | 必须通过租户 Backoffice Bootstrap；无 Permission 的账号统一显示 404 |
|
||
| `/__demo` | 仅开发环境存在的生命周期启动器 |
|
||
|
||
后台菜单来自 `GET /api/tenant/access/ui-bootstrap`。进入站点设计还必须包含 `tenant:settings:manage`，前端隐藏菜单不能替代后端 401/403。
|
||
|
||
## 前后端契约
|
||
|
||
当前前端 Facade 对齐以下接口：
|
||
|
||
- `GET /api/public/runtime/bootstrap`
|
||
- `POST /api/tenant/auth/browser/activation/complete`
|
||
- `POST /api/tenant/auth/browser/login/password`
|
||
- `GET /api/tenant/access/ui-bootstrap`
|
||
- `GET /api/tenant/onboarding/status`
|
||
- `GET|PUT|POST /api/tenant/frontend-config/**`
|
||
|
||
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`。
|
||
|
||
## 与旧系统的边界
|
||
|
||
旧 `tiki-web` 仅作为学生业务页面、响应式布局和交互体验的功能参考。本仓库不得引入 PocketBase、`MockBackend`、`tenant.config.ts`，也不得在浏览器保存支付、短信或对象存储 Secret。Logo 的本地 Data URL 仅用于当前前端原型；真实接入时改为后端签发的上传凭证或预签名 URL。
|