# 本地开发（test.*.tkmind.cn）

本地开发统一使用 **test 子域**，不再用 `127.0.0.1` / `localhost` 访问。结构与生产一致，`.tkmind.cn` Cookie 可跨子域共享登录态。

## 域名映射

| 域名 | 服务 | 内部端口 |
|------|------|----------|
| **test.tkmind.cn** | MindSpace H5（Vite 热更新） | 5173 |
| **testadm.tkmind.cn** | memind_adm 后台 API | 8082 |
| **testpla.tkmind.cn** | Plaza 发现广场 | 3001 |
| **testops.tkmind.cn** | Ops 审核 / 超管 SPA | 3002 |

Portal（用户 API、登录、`/auth`）仍跑在 **8081**，由 Vite / Plaza 内部代理，**无需单独域名**。

```
浏览器
  ↓  HTTPS :443（local-test-proxy，按 Host 分流）
  ├─ test.tkmind.cn      → :5173  Vite（/api、/auth → :8081）
  ├─ testadm.tkmind.cn   → :8082  memind_adm
  ├─ testpla.tkmind.cn   → :3001  Plaza Next.js
  └─ testops.tkmind.cn   → :3002  Ops SPA
```

## 首次配置（一次性）

```bash
# 1. 安装依赖
pnpm install
cd ops && npm install && cd ..

# 2. 环境变量（按需）
cp .env.example .env

# 3. 本地 DNS（覆盖 Tailscale / Clash fake-ip）
sudo pnpm setup:local-test

# 或分步：
# sudo pnpm setup:local-dns
# sudo pnpm setup:local-tls
```

`.env` 建议至少设置：

```bash
H5_PUBLIC_BASE_URL=https://test.tkmind.cn
H5_COOKIE_DOMAIN=.tkmind.cn
PLAZA_LOCAL_HOST=testpla.tkmind.cn
PLAZA_PUBLIC_BASE=https://testpla.tkmind.cn
ADMIN_PUBLIC_HOST=testadm.tkmind.cn
PLAZA_APP_DIR=/Users/john/PycharmProjects/goose/ui/plaza   # Plaza 源码路径
```

## 日常启动

**终端 1 — 全栈开发：**

```bash
PLAZA_APP_DIR=/Users/john/PycharmProjects/goose/ui/plaza pnpm dev
```

**终端 2 — HTTPS 统一入口（需 root）：**

```bash
sudo pnpm dev:local-proxy
```

## 访问地址

| 场景 | 地址 |
|------|------|
| MindSpace | https://test.tkmind.cn/?preview=mindspace |
| Plaza | https://testpla.tkmind.cn/plaza |
| Ops 审核后台 | https://testops.tkmind.cn/ops/ |
| memind_adm 健康检查 | https://testadm.tkmind.cn/healthz |
| 一键打开 H5 | `pnpm open:local-test` |

## 诊断

```bash
pnpm check:local-test
```

## Ops 首次授权

先在 MindSpace 登录，再执行：

```bash
node scripts/grant-ops-role.mjs admin ops_admin
```

## 浏览器「连接不是私密连接」？

本地 HTTPS 使用自签证书（`.local/local-test-tls/`）。首次访问各 test 域名时，在浏览器中信任证书即可。

若 Chrome 仍走 Secure DNS 绕过 `/etc/hosts`：

1. 关闭「使用安全 DNS」
2. 或执行 `pnpm open:local-test`

## 移除本地劫持

```bash
sudo pnpm setup:local-dns:remove
```

## 与 plaza.tkmind.cn 的关系

- **testpla.tkmind.cn**：纯本地开发，不与公网冲突
- **plaza.tkmind.cn**：公网 Tunnel 回源，见 [plaza-local.md](./plaza-local.md)

两套域名可并存；日常 Memind 全栈开发优先用 `test.*`。

## 环境变量

| 变量 | 默认 | 说明 |
|------|------|------|
| `H5_LOCAL_HOST` | test.tkmind.cn | H5 测试域 |
| `ADMIN_LOCAL_HOST` | testadm.tkmind.cn | 后台 API 测试域 |
| `PLAZA_LOCAL_HOST` | testpla.tkmind.cn | Plaza 测试域 |
| `OPS_LOCAL_HOST` | testops.tkmind.cn | Ops 测试域 |
| `H5_PUBLIC_BASE_URL` | https://test.tkmind.cn | 公开链接 / OAuth 回调基址 |
| `H5_COOKIE_DOMAIN` | （建议 `.tkmind.cn`） | 跨子域共享登录 |
| `LOCAL_TEST_DNS_PORT` | 5533 | 本地 DNS 监听端口 |
| `LOCAL_TEST_PUBLIC_PORT` | 443 | HTTPS 代理端口 |
| `LOCAL_TEST_HTTPS` | 1 | 设为 `0` 时用 HTTP :80 |