# Local Auth

本地登录代理用于开发态缓存一份后端登录 token，并在页面打开时同步到浏览器 `localStorage` 和 `window.__LOCAL_ACCESS_TOKEN__`。当多个本地开发实例同时运行时，代理会自动选择空闲端口，前端按本次启动实例自动发现对应端口。

## 目录

- 代理脚本：`scripts/local-auth-proxy.mjs`
- Vite 启动脚本：`scripts/dev-vite.mjs`
- 开发联合启动脚本：`scripts/dev-with-local-auth.mjs`
- 前端启动入口：`src/bootstrap/setupLocalAccessToken.ts`
- 默认本地配置：`dev-tools/local-auth/config.local.json`
- 示例配置：`dev-tools/local-auth/config.example.json`

## 快速开始

1. 复制 `dev-tools/local-auth/config.example.json` 为 `dev-tools/local-auth/config.local.json`
2. 在 `config.local.json` 中配置自己的账号
3. 启动 `pnpm dev`、`pnpm dev:qa`、`pnpm dev:pet` 等命令，代理会先登录默认账号并缓存 token

补充：

- `package.json` 里的开发命令已改成脚本参数传 mode，兼容 macOS 与 Windows
- 统一使用 `--mode <mode>` 传环境参数，和 Vite 保持一致
- 如需单独启动，可用 `pnpm run dev:vite --mode qa` 或 `pnpm run dev:auth --mode qa`

```json
{
  "defaultProfile": "dev-main",
  "profiles": {
    "dev-main": {
      "userCode": "your-user-code",
      "password": "your-encrypted-password"
    },
    "qa-backup": {
      "userCode": "another-user-code",
      "password": "another-encrypted-password"
    }
  }
}
```

## 多账号与切换

- `defaultProfile` 表示默认登录账号
- `profiles` 下可以配置多个账号
- 启动时可通过 `LOCAL_AUTH_PROFILE=<profileName>` 指定默认账号
- 开发服务启动时，Node 代理会先登录当前默认 profile，并缓存该 token
- 如果默认端口 `9530` 被占用，代理会自动顺延到下一个空闲端口
- 同一次 `pnpm dev*` 启动会生成唯一实例标识，前端会按该实例自动连接对应代理，避免多个开发实例串号
- 页面打开时可通过 URL 参数 `?localAuthProfile=qa-backup` 切换账号
- 页面加载时，前端会读取代理缓存 token；若本次没拿到 token，则保留浏览器原有 `localStorage.accessToken`
- 页面加载后可在控制台执行 `window.__LOCAL_AUTH__.getState()` 查看状态
- 页面加载后可在控制台执行 `await window.__LOCAL_AUTH__.getToken()` 读取当前缓存 token 并同步到本地
- 页面加载后可在控制台执行 `await window.__LOCAL_AUTH__.refresh()` 强制重新获取当前 profile 的 token，并更新代理缓存
- 页面加载后可在控制台执行 `await window.__LOCAL_AUTH__.switchProfile('qa-backup')` 切换账号并更新代理缓存

## 配置文件说明

- `dev-tools/local-auth/config.local.json` 建议只保存在本地，已被 git ignore
- 支持额外本地文件，例如 `config.local1.json`、`config.local-work.json`
- 可通过 `LOCAL_AUTH_CONFIG_PATH=dev-tools/local-auth/config.local1.json` 指定使用哪个本地配置文件

## 启动日志

前端开发态启动后会在控制台打印当前本地登录功能状态，包括：

- 是否启用
- 当前环境和代理地址
- 当前实例标识
- 当前 profile 与可选 profile
- 当前代理缓存 token 是否已就绪
- 当前实际使用的本地配置文件路径
- 控制台可直接调用的调试 helper