fix

docs/frontend-integration.md

@@ -1,378 +0,0 @@
-# 前端对接文档
-
-> 适用平台：有声合成平台 / 掌维 AI 短剧
-> 后端：Laravel，接口统一前缀 `/api`
-> 本文档覆盖前端需要改造对接的两块内容：**接口签名**与**登录图片验证码**，以及通用约定与错误码。
-
----
-
-## 一、通用约定
-
-### 1.1 接口地址与鉴权
-
-- 所有业务接口以 `/api` 开头，例如 `POST /api/anime/detail`。
-- 登录后，除少量免登录接口外，均需在请求头携带登录令牌：
-
-  ```
-  d-token: <登录接口返回的 token>
-  ```
-- 少数导出类接口服务端也兼容从参数 `d_token` 读取令牌，**新代码请统一使用请求头**。
-- 免登录接口（不需要 `d-token`）：`GET /api/login`、`GET /api/captcha`、`ANY /api/video/seedanceCallback`。
-
-### 1.2 响应格式
-
-成功：
-
-```json
-{ "msg": "", "code": 0, "data": { } }
-```
-
-失败（业务异常）：
-
-```json
-{ "code": 1002, "msg": "签名异常", "data": { } }
-```
-
-> 约定：`code === 0` 表示成功，其余为业务错误码，前端按 `code` 判断并提示 `msg`。
-> 业务异常统一返回 HTTP 200；个别接口由框架做参数校验时可能返回 HTTP 422，建议在响应拦截器里一并处理。
-
-### 1.3 常用错误码
-
-| code  | msg                  | 说明                                      |
-| ----- | -------------------- | ----------------------------------------- |
-| 0     | -                    | 成功                                      |
-| 1002  | 签名异常             | 签名不正确 / 过期 / 缺少签名头 / 请求重复 |
-| 1003  | 请确认填写的数据无误 | 参数错误                                  |
-| 1005  | 没有权限             | 无权限访问该资源（含跨公司访问）          |
-| 1008  | 请先登录             | 未登录或 token 失效                       |
-| 10021 | 验证码错误           | 图片验证码错误或已过期                    |
-
----
-
-## 二、接口签名
-
-### 2.1 适用范围
-
-服务端在以下接口组启用了验签：
-
-- 剧本管理：`/api/deepseek/*`（`scriptList`、`scriptInfo`、`saveEpisodeContent` 等）
-- AI 生成：`/api/AIGeneration/*`
-- 动漫管理：`/api/anime/*`
-- 画布模式：`/api/canvas/*`
-- 音频素材上传：`/api/book/uploadAudioEffect`、`/api/book/uploadBgm`
-
-**推荐做法：前端统一给所有请求加签名头，不必区分接口。** 服务端对未开启验签的接口不会校验，多传请求头没有任何副作用，这样可以避免后续接口调整归属时前端漏改。
-
-> 注意：服务端有开关，未开启验签时签名头会被忽略，接口照常返回。因此前端上线后如果发现一切正常，不代表签名已经生效，需要和后端确认开关状态。
-
-### 2.2 签名规则
-
-三个请求头：
-
-| 请求头      | 内容                                         |
-| ----------- | -------------------------------------------- |
-| `X-Time`  | 当前时间戳（**秒**，10 位）            |
-| `X-Nonce` | 前端生成的随机串，同一账号在时间窗内不可重复 |
-| `X-Sign`  | 签名结果，**小写十六进制**（64 位）    |
-
-签名串按固定顺序拼接，字段间用 `|` 分隔：
-
-```
-{请求方法大写}|{接口路径}|{X-Time}|{X-Nonce}|d-token={d-token}
-```
-
-签名算法：
-
-```
-X-Sign = HMAC-SHA256(签名串, SIGN_SALT)    // 结果转小写 hex
-```
-
-其中 `SIGN_SALT` 由后端提供，需在打包时注入前端配置。
-
-**接口路径（PATH）的规则**，这是最容易算错的地方：
-
-- 以 `/` 开头
-- 不含协议和域名
-- **不含 query string**（`?a=1&b=2` 要丢掉）
-- 与后端路由注册的路径一致，例如 `/api/anime/detail`
-
-示例：
-
-```
-请求：POST /api/anime/detail?anime_id=123
-X-Time  = 1737280000
-X-Nonce = abc123
-d-token = 0123456789abcdef0123456789abcdef
-
-签名串 = POST|/api/anime/detail|1737280000|abc123|d-token=0123456789abcdef0123456789abcdef
-X-Sign = HMAC-SHA256(签名串, SIGN_SALT)
-```
-
-**有效期与重放保护**：
-
-- `X-Time` 与本机时间偏差超过 **120 秒**（可由后端配置）判定为过期；
-- 同一 `X-Nonce` 在时间窗内只能使用一次，重复请求会返回 1002。
-
-### 2.3 自检用例（用于验证前端实现是否正确）
-
-用下面的固定输入自测，输出的 `X-Sign` 必须与表中一致，否则说明拼接规则或编码有误。
-
-> 注意：用例中的时间戳是固定值（已过期），**仅用于校验算法实现，不能用于真实请求**。真实请求必须使用当前时间。
-
-| 项               | 用例一                                                               | 用例二                                                               |
-| ---------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| 请求方法         | `POST`                                                             | `GET`                                                              |
-| 接口路径         | `/api/anime/detail`                                                | `/api/canvas/list`                                                 |
-| X-Time           | `1737280000`                                                       | `1737280000`                                                       |
-| X-Nonce          | `abc123`                                                           | `nonce9876`                                                        |
-| d-token          | `0123456789abcdef0123456789abcdef`                                 | `fedcba9876543210fedcba9876543210`                                 |
-| SIGN_SALT        | `example_salt`                                                     | `example_salt`                                                     |
-| **X-Sign** | `f9a6c3cc7cf1b7f4b390fc08d91c5070445d60aadeba4b823509ea3092d7ae4b` | `3bc9b788a618dc44f06dba1aa2b0e5ebb703166b7f2b496eef49233a6461c4eb` |
-
-可以直接用 Node 跑一遍验证：
-
-```js
-// node sign-selfcheck.js
-const crypto = require('crypto')
-
-function sign(method, path, time, nonce, token, salt) {
-  const str = `${method}|${path}|${time}|${nonce}|d-token=${token}`
-  return crypto.createHmac('sha256', salt).update(str).digest('hex')
-}
-
-console.log(sign('POST', '/api/anime/detail', '1737280000', 'abc123',
-  '0123456789abcdef0123456789abcdef', 'example_salt'))
-// 期望：f9a6c3cc7cf1b7f4b390fc08d91c5070445d60aadeba4b823509ea3092d7ae4b
-
-console.log(sign('GET', '/api/canvas/list', '1737280000', 'nonce9876',
-  'fedcba9876543210fedcba9876543210', 'example_salt'))
-// 期望：3bc9b788a618dc44f06dba1aa2b0e5ebb703166b7f2b496eef49233a6461c4eb
-```
-
-两条都输出一致，说明签名算法实现正确；剩下只需要保证 `path`、`token` 与真实请求对齐。
-
-### 2.4 前端实现
-
-#### 方案 A：使用 crypto-js（推荐，改动最小）
-
-```bash
-npm install crypto-js
-```
-
-```js
-// src/utils/sign.js
-import HmacSHA256 from 'crypto-js/hmac-sha256'
-import Hex from 'crypto-js/enc-hex'
-
-const SIGN_SALT = process.env.VUE_APP_SIGN_SALT
-
-/**
- * 生成接口签名头
- * @param {string} method  请求方法
- * @param {string} path    接口路径（以 / 开头，不含域名与 query）
- * @param {string} token   登录令牌
- */
-export function buildSignHeaders(method, path, token) {
-  const time  = Math.floor(Date.now() / 1000).toString()
-  const nonce = `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`
-  const str   = `${method.toUpperCase()}|${path}|${time}|${nonce}|d-token=${token}`
-
-  return {
-    'X-Time':  time,
-    'X-Nonce': nonce,
-    'X-Sign':  HmacSHA256(str, SIGN_SALT).toString(Hex)
-  }
-}
-```
-
-#### 方案 B：使用浏览器原生 Web Crypto（不新增依赖）
-
-```js
-// src/utils/sign.js
-const SIGN_SALT = process.env.VUE_APP_SIGN_SALT
-
-const enc = new TextEncoder()
-let cachedKey = null
-
-async function getKey() {
-  if (!cachedKey) {
-    cachedKey = crypto.subtle.importKey(
-      'raw', enc.encode(SIGN_SALT), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']
-    )
-  }
-  return cachedKey
-}
-
-export async function buildSignHeaders(method, path, token) {
-  const time  = Math.floor(Date.now() / 1000).toString()
-  const nonce = `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`
-  const str   = `${method.toUpperCase()}|${path}|${time}|${nonce}|d-token=${token}`
-
-  const sig = await crypto.subtle.sign('HMAC', await getKey(), enc.encode(str))
-  const hex = Array.from(new Uint8Array(sig)).map(b => b.toString(16).padStart(2, '0')).join('')
-
-  return { 'X-Time': time, 'X-Nonce': nonce, 'X-Sign': hex }
-}
-```
-
-> Web Crypto 的 `crypto.subtle` 只在 HTTPS 或 localhost 下可用，若前端部署在 http 环境请使用方案 A。
-
-#### 挂到 axios 拦截器
-
-```js
-import { buildSignHeaders } from '@/utils/sign'
-import store from '@/store'
-
-service.interceptors.request.use(async (config) => {
-  if (config.skipSign) return config          // 个别请求可跳过
-
-  const token = store.getters.token || ''
-  // 关键：path 必须是含 /api 前缀的真实路径，且不含 query
-  const rawUrl = String(config.url || '')
-  const path   = '/' + rawUrl.split('?')[0].replace(/^\/+/, '')
-  const method = (config.method || 'get').toUpperCase()
-
-  const headers = await buildSignHeaders(method, path, token)
-  Object.assign(config.headers, headers)
-
-  return config
-}, (error) => Promise.reject(error))
-```
-
-### 2.5 签名相关常见错误
-
-| 现象                   | 排查方向                                                                                                                          |
-| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| 一直 1002              | 先跑第 2.3 节自检用例；再打印前端实际拼出的`path`，与后端 `$request->path()` 对比                                             |
-| 偶发 1002              | 服务器与客户端时钟偏差超过 120 秒，检查服务器 NTP                                                                                 |
-| 1002 且提示 nonce 重复 | 同一个`X-Nonce` 被复用（例如请求重试时复用了旧头），重试需重新生成                                                              |
-| `path` 对不上        | 注意`axios` 的 `baseURL`：若 `/api` 写在 `baseURL` 里、`url` 只写了 `/anime/detail`，需手动补成 `/api/anime/detail` |
-| token 对不上           | 签名里的`d-token` 必须与请求头 `d-token` 完全一致（含大小写），若 token 做过 trim 或转换需保持一致                            |
-
----
-
-## 三、登录图片验证码
-
-### 3.1 获取验证码
-
-```
-GET /api/captcha
-```
-
-免登录，无需签名。返回：
-
-```json
-{
-  "msg": "",
-  "code": 0,
-  "data": {
-    "captcha_key": "8f14e45fceea167a5a36dedd4bea2543",
-    "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
-  }
-}
-```
-
-- captcha_key：本次验证码的唯一标识，登录时回传；
-- `image`：完整的 data URI，可直接作为 `<img>` 的 `src`，无需额外处理。
-
-服务端对该接口有 **20 次/分钟/IP** 的限流。
-
-### 3.2 登录
-
-```
-GET /api/login?account=<账号>&passwd=<密码>&captcha_key=<key>&captcha_code=<用户输入>
-```
-
-| 参数             | 必填                 | 说明                           |
-| ---------------- | -------------------- | ------------------------------ |
-| `account`      | 是                   | 账号                           |
-| `passwd`       | 是                   | 密码                           |
-| `captcha_key`  | 后端开启验证码时必填 | 获取验证码接口返回的`key`    |
-| `captcha_code` | 后端开启验证码时必填 | 用户输入的验证码，大小写不敏感 |
-
-成功返回：
-
-```json
-{
-  "msg": "",
-  "code": 0,
-  "data": {
-    "uid": 12,
-    "nickname": "张三",
-    "token": "f3a8c1e0b7d94a2f8e6c5b1d0a9f3e72",
-    "role": "admin"
-  }
-}
-```
-
-`role` 取值：`superadmin`（平台）、`admin`（公司管理员）、`user`（组员）。
-
-### 3.3 验证码的关键行为
-
-- **有效期 5 分钟**，过期后需重新获取；
-- **一次性消费**：无论校验成功还是失败，`key` 立即失效，所以用户输错后必须自动刷新一张新验证码；
-- 大小写不敏感；
-- 错误返回 `code = 10021`。
-
-> 服务端有总开关。开关未开启时，不传 `captcha_key` / `captcha_code` 也能正常登录，因此前端可以先上线，等后端开启后再生效。
-
-### 3.4 前端实现要点
-
-登录页：
-
-1. 进入页面时调用 `GET /api/captcha`，把 `data.image` 绑到 `<img :src="captcha.image">`；
-2. 点击图片重新获取（同时清空输入框）；
-3. 提交登录时带上 `captcha_key` 与 `captcha_code`；
-4. **登录返回 `code === 10021` 时，自动重新拉取验证码并提示用户重新输入**；
-5. 其它失败（如密码错误）也建议刷新验证码，避免用户拿到已消费的 `key` 反复提交。
-
----
-
-## 四、其它常用接口
-
-### 4.1 获取当前用户信息
-
-```
-GET /api/userInfo
-```
-
-需登录。返回 `uid`、`nickname`、`token`、`role`、`points` 等字段。
-
-### 4.2 退出登录
-
-```
-GET /api/logout
-```
-
----
-
-## 五、灰度与上线说明
-
-本文档涉及的两项能力都由后端开关控制，前端可以先行上线，行为与现在完全一致：
-
-| 能力       | 后端开关            | 未开启时的表现             |
-| ---------- | ------------------- | -------------------------- |
-| 接口签名   | `CHECK_SIGN`      | 签名头被忽略，按原逻辑放行 |
-| 登录验证码 | `CAPTCHA_ENABLED` | 登录不校验验证码           |
-
-**建议的上线顺序**
-
-1. 后端部署（两个开关均为关闭状态，线上零影响）；
-2. 前端发布带签名与验证码的版本；此时功能表现不变，可确认页面无异常；
-3. 后端依次开启开关并清理配置缓存（`php artisan config:clear`）：
-   - 先开 `CHECK_SIGN`，观察日志是否出现验签失败；
-   - 再开 `CAPTCHA_ENABLED`，确认登录流程正常。
-
-**需要向后端确认的信息**
-
-- `SIGN_SALT` 的正式值（需与前端打包配置一致，改动需两端同步）；
-- `CHECK_SIGN` 与 `CAPTCHA_ENABLED` 的开启时间点；
-- 是否存在验签白名单账号（白名单账号不校验签名，表现为"签名错误也能调用成功"，属正常现象，不要据此判断前端实现有误）。
-
----
-
-## 六、变更记录
-
-| 日期       | 内容                                                         |
-| ---------- | ------------------------------------------------------------ |
-| 2026-09-21 | 初版：接口签名（HMAC-SHA256 + nonce 防重放）、登录图片验证码 |