# 门户前端 token 同步方案（阶段 1 收尾 BUG-C）

> 范围：`txw-mhzc-web` 门户前端与 `txw-cloud` 网关的鉴权头协商。
> 基线：本地三后端在跑（auth 9200 / system 9201 / gateway 8080），UUID + JWT 双 Token 模式可工作。
> 日期：2026-06-07

## 1. 问题

- `txw-auth` 的 `AuthController.loginByPassword` 把 token 写入 `Cookie: token`（`HttpOnly; Secure`）。
- 网关 `AuthFilter` 只读 `Authorization: Bearer <token>` Header，**不读 Cookie**。
- 后果：门户前端若只依赖 Cookie 携带 token，业务接口经网关会 401。

## 2. 决策

不改后端（影响网关所有受保护接口），由门户前端在 axios 拦截器把 **响应体中的 token** 同步到 `Authorization` Header。

## 3. 实现要点

| 点 | 说明 |
|----|------|
| token 来源 | 登录/刷新响应体 `data.accessToken`（不是 Cookie，Cookie 是 HttpOnly，JS 读不到） |
| token 持久化 | `localStorage`（多 tab 共享、刷新不丢） |
| 请求拦截器 | 自动在 `headers.Authorization` 写入 `Bearer <accessToken>` |
| 响应拦截器 | 登录/刷新成功后 `setTokensFromResponse(data)`；401 失败时 `clearTokens()` |
| 登出 | 不需要前端手动清 Header（后端 expire Cookie 即可，本地 token 由 `clearTokens` 清） |
| 关键文件 | `src/utils/auth-token-store.js`（存取）、`src/core/request.js`（拦截器） |

## 4. 为什么不用 Cookie 读

`HttpOnly` Cookie 是浏览器安全机制，JS 读取会得到空串。若团队坚持用 Cookie，需要：
1. 去掉 `HttpOnly`（安全降级），或
2. 改后端让网关优先读 Cookie（影响所有受保护接口）。

都不采纳。详情见 `refactor-docs/重构方案/阶段1-收尾-问题清单.md` 第 4 节备选。

## 5. 联调验收

- [ ] 门户登录成功后 `localStorage` 有 `txw_access_token`
- [ ] `Authorization: Bearer ...` 出现在 devtools Network 请求头
- [ ] 调 `/mhzc/sy/ptgg/list` 等需鉴权接口返回 200
- [ ] 登出后 `localStorage` 中 `txw_access_token` 被清
- [ ] 401 时自动清 token 并触发 `showLoginGuide`

## 6. 不要做的事

- 不要在前端代码里直接 `document.cookie` 读 token（HttpOnly 读不到）
- 不要把 token 存到 `sessionStorage`（刷新即丢）
- 不要在 `vuex` 全局状态里存（多 tab 不共享）