docs: add mobile-h5 password login API implementation plan

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-10 15:52:29 +08:00
1 parent 5e0a1ce0a1
commit 6dd7a95ce8
@@ -0,0 +1,570 @@
+# mobile-h5 账号密码登录对接真实 API Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 将 `mobile-h5` 登录页账号密码从 mock 改为调用 backend `/api/web/auth/login`（RSA），微信按钮置灰不可点。
+
+**Architecture:** 新增 `config` / `request` / `login-rsa` / `auth`；登录页调 `passwordLogin`；会话写入 `token` + `refreshToken` + `userInfo`；不改后端；不做微信登录与自动 refresh。
+
+**Tech Stack:** uni-app Vue3（HBuilderX）、`jsencrypt`、`uni.request`、现有 backend Web 登录 API
+
+**Spec:** `docs/superpowers/specs/2026-08-10-mobile-h5-password-login-api-design.md`
+
+---
+
+## File map
+
+| 路径 | 职责 |
+|------|------|
+| `mobile-h5/utils/config.js` | `API_BASE_URL` |
+| `mobile-h5/utils/request.js` | `get` / `post`，解析 `{ code, message, data }` |
+| `mobile-h5/utils/request.test.mjs` | 纯函数响应解析单测 |
+| `mobile-h5/utils/login-rsa.js` | 拉公钥 + JSEncrypt 加密 |
+| `mobile-h5/utils/auth.js` | 会话存取 + `passwordLogin`（替换 `auth-mock.js`） |
+| `mobile-h5/package.json` | 增加 `jsencrypt` |
+| `mobile-h5/pages/login/index.vue` | 真实登录；微信置灰 |
+| `mobile-h5/pages/index/index.vue` | import 改为 `auth.js` |
+| `mobile-h5/styles/components/login.scss` | `.login-wechat.is-disabled` |
+| `mobile-h5/utils/auth-mock.js` | 删除（调用方改完后） |
+
+**不修改：** `backend/**`、协议页、微信换票 API。
+
+---
+
+### Task 1: `config.js`
+
+**Files:**
+- Create: `mobile-h5/utils/config.js`
+
+- [ ] **Step 1: 写入配置**
+
+```js
+/**
+ * 后端 API 根路径（含 /api，不含末尾斜杠）。
+ * 本地默认；真机 / 体验版请改为可达地址，例如 http://192.168.x.x:8000/api
+ */
+export const API_BASE_URL = 'http://127.0.0.1:8000/api'
+
+export const REQUEST_TIMEOUT_MS = 15000
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+cd /Users/wuzilong/work/00code/zkxw
+git add mobile-h5/utils/config.js
+git commit -m "$(cat <<'EOF'
+chore(mobile-h5): add API_BASE_URL config for login
+
+EOF
+)"
+```
+
+---
+
+### Task 2: `request.js` + 响应解析单测
+
+**Files:**
+- Create: `mobile-h5/utils/request.js`
+- Create: `mobile-h5/utils/request.test.mjs`
+
+- [ ] **Step 1: 写入可测的解析函数与 request 封装**
+
+`mobile-h5/utils/request.js`:
+
+```js
+import { API_BASE_URL, REQUEST_TIMEOUT_MS } from './config.js'
+
+/**
+ * 解析后端统一响应。成功返回 data；失败抛 Error（message 为业务文案）。
+ * @param {{ code?: number, message?: string, data?: any }} body
+ * @param {number} [httpStatus]
+ */
+export function unwrapResponse(body, httpStatus) {
+  if (body == null || typeof body !== 'object') {
+    const err = new Error('网络异常，请稍后重试')
+    err.code = 'BAD_RESPONSE'
+    throw err
+  }
+  const code = body.code
+  if (code === 200) {
+    return body.data
+  }
+  const msg =
+    (typeof body.message === 'string' && body.message.trim()) ||
+    '请求失败'
+  const err = new Error(msg)
+  err.code = code
+  err.httpStatus = httpStatus
+  throw err
+}
+
+function joinUrl(path) {
+  const base = (API_BASE_URL || '').replace(/\/$/, '')
+  const p = path.startsWith('/') ? path : `/${path}`
+  return `${base}${p}`
+}
+
+/**
+ * @param {{ url: string, method?: string, data?: any, header?: Record<string, string> }} options
+ * @returns {Promise<any>} data 字段
+ */
+export function request(options) {
+  const method = (options.method || 'GET').toUpperCase()
+  const url = joinUrl(options.url)
+  const header = Object.assign(
+    { 'Content-Type': 'application/json' },
+    options.header || {}
+  )
+
+  return new Promise((resolve, reject) => {
+    uni.request({
+      url,
+      method,
+      data: options.data,
+      header,
+      timeout: REQUEST_TIMEOUT_MS,
+      success(res) {
+        try {
+          if (res.statusCode >= 200 && res.statusCode < 300) {
+            resolve(unwrapResponse(res.data, res.statusCode))
+            return
+          }
+          // HTTP 非 2xx：若 body 仍是业务包，优先展示 message
+          try {
+            resolve(unwrapResponse(res.data, res.statusCode))
+          } catch (bizErr) {
+            reject(bizErr)
+          }
+        } catch (e) {
+          reject(e)
+        }
+      },
+      fail() {
+        const err = new Error('网络异常，请稍后重试')
+        err.code = 'NETWORK'
+        reject(err)
+      }
+    })
+  })
+}
+
+export function get(url, header) {
+  return request({ url, method: 'GET', header })
+}
+
+export function post(url, data, header) {
+  return request({ url, method: 'POST', data, header })
+}
+```
+
+- [ ] **Step 2: 写入单测**
+
+`mobile-h5/utils/request.test.mjs`:
+
+```js
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { unwrapResponse } from './request.js'
+
+test('unwrapResponse returns data when code is 200', () => {
+  const data = unwrapResponse({ code: 200, message: 'success', data: { token: 't' } })
+  assert.deepEqual(data, { token: 't' })
+})
+
+test('unwrapResponse throws with backend message when code is not 200', () => {
+  assert.throws(
+    () => unwrapResponse({ code: 401, message: '用户名或密码错误', data: null }),
+    (e) => e instanceof Error && e.message === '用户名或密码错误' && e.code === 401
+  )
+})
+
+test('unwrapResponse throws network message on null body', () => {
+  assert.throws(
+    () => unwrapResponse(null),
+    (e) => e instanceof Error && e.message === '网络异常，请稍后重试'
+  )
+})
+```
+
+- [ ] **Step 3: 跑单测**
+
+```bash
+cd /Users/wuzilong/work/00code/zkxw/mobile-h5
+node --test utils/request.test.mjs
+```
+
+Expected: 3 passed。若因 `uni` 未定义导致 `request.js` 加载失败：把 `unwrapResponse` 抽到 `utils/unwrap-response.js` 再测该文件（保持行为不变）。优先保持单文件；仅在加载失败时拆分。
+
+- [ ] **Step 4: Commit**
+
+```bash
+cd /Users/wuzilong/work/00code/zkxw
+git add mobile-h5/utils/request.js mobile-h5/utils/request.test.mjs
+git commit -m "$(cat <<'EOF'
+feat(mobile-h5): add thin uni.request wrapper for API calls
+
+EOF
+)"
+```
+
+---
+
+### Task 3: 安装 `jsencrypt` + `login-rsa.js`
+
+**Files:**
+- Modify: `mobile-h5/package.json`
+- Create: `mobile-h5/utils/login-rsa.js`
+
+- [ ] **Step 1: 安装依赖**
+
+```bash
+cd /Users/wuzilong/work/00code/zkxw/mobile-h5
+npm install jsencrypt@^3.3.2 --save
+```
+
+Expected: `package.json` / `package-lock.json` 含 `jsencrypt`；`node_modules/jsencrypt` 存在。
+
+HBuilderX：若项目需「工具 → 插件安装 / 使用 npm 模块」，按既有流程执行一次 npm 构建，确保小程序能 resolve `jsencrypt`。
+
+- [ ] **Step 2: 写入 `login-rsa.js`**
+
+```js
+import JSEncrypt from 'jsencrypt'
+import { get } from './request.js'
+
+/**
+ * 对齐 web-admin `buildWebEncryptedLoginBody`：
+ * 拉公钥后加密 { username, password, ts }。
+ * @returns {Promise<{ encryptedLogin: string }>}
+ */
+export async function buildEncryptedLoginBody(username, password) {
+  const data = await get('/web/auth/login-rsa-public-key')
+  const publicKeyPem = data && data.publicKeyPem
+  if (!publicKeyPem) {
+    throw new Error('获取登录公钥失败')
+  }
+  const crypt = new JSEncrypt()
+  crypt.setPublicKey(publicKeyPem)
+  const payload = JSON.stringify({
+    username,
+    password,
+    ts: Date.now()
+  })
+  const encryptedLogin = crypt.encrypt(payload)
+  if (!encryptedLogin) {
+    throw new Error('登录加密失败，请重试')
+  }
+  return { encryptedLogin }
+}
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+cd /Users/wuzilong/work/00code/zkxw
+git add mobile-h5/package.json mobile-h5/package-lock.json mobile-h5/utils/login-rsa.js
+git commit -m "$(cat <<'EOF'
+feat(mobile-h5): add RSA login body builder with jsencrypt
+
+EOF
+)"
+```
+
+---
+
+### Task 4: `auth.js` 替换 `auth-mock.js`
+
+**Files:**
+- Create: `mobile-h5/utils/auth.js`
+- Modify: `mobile-h5/pages/login/index.vue`（仅改 import 与 `onPasswordLogin` 调用名，微信改动放 Task 5）
+- Modify: `mobile-h5/pages/index/index.vue`（import 路径）
+- Delete: `mobile-h5/utils/auth-mock.js`
+
+- [ ] **Step 1: 写入 `auth.js`**
+
+```js
+import { validateCredentials } from './validate-credentials.js'
+import { buildEncryptedLoginBody } from './login-rsa.js'
+import { post } from './request.js'
+
+export { validateCredentials }
+
+const TOKEN_KEY = 'zkxw_mobile_token'
+const REFRESH_TOKEN_KEY = 'zkxw_mobile_refresh_token'
+const USER_KEY = 'zkxw_mobile_user'
+
+export function getToken() {
+  try {
+    return uni.getStorageSync(TOKEN_KEY) || ''
+  } catch (e) {
+    return ''
+  }
+}
+
+export function getRefreshToken() {
+  try {
+    return uni.getStorageSync(REFRESH_TOKEN_KEY) || ''
+  } catch (e) {
+    return ''
+  }
+}
+
+export function isLoggedIn() {
+  return !!getToken()
+}
+
+export function getUser() {
+  try {
+    const raw = uni.getStorageSync(USER_KEY)
+    return raw ? JSON.parse(raw) : null
+  } catch (e) {
+    return null
+  }
+}
+
+export function clearSession() {
+  try {
+    uni.removeStorageSync(TOKEN_KEY)
+    uni.removeStorageSync(REFRESH_TOKEN_KEY)
+    uni.removeStorageSync(USER_KEY)
+  } catch (e) {
+    /* ignore */
+  }
+}
+
+function saveSession({ token, refreshToken, userInfo }) {
+  uni.setStorageSync(TOKEN_KEY, token || '')
+  uni.setStorageSync(REFRESH_TOKEN_KEY, refreshToken || '')
+  uni.setStorageSync(USER_KEY, JSON.stringify(userInfo || null))
+}
+
+/**
+ * 可选：清除历史 mock_ 前缀假会话，避免误判已登录。
+ */
+export function clearLegacyMockSessionIfNeeded() {
+  const token = getToken()
+  if (typeof token === 'string' && token.indexOf('mock_') === 0) {
+    clearSession()
+  }
+}
+
+/**
+ * 真实账号密码登录。
+ * @param {{ username: string, password: string }} params
+ */
+export async function passwordLogin({ username, password }) {
+  const v = validateCredentials(username, password)
+  if (!v.ok) {
+    const err = new Error(v.message)
+    err.code = v.code
+    throw err
+  }
+  const body = await buildEncryptedLoginBody(
+    (username || '').trim(),
+    password || ''
+  )
+  const data = await post('/web/auth/login', body)
+  if (!data || !data.token) {
+    throw new Error('登录失败')
+  }
+  saveSession({
+    token: data.token,
+    refreshToken: data.refreshToken,
+    userInfo: data.userInfo
+  })
+  return data
+}
+```
+
+- [ ] **Step 2: 更新 `pages/index/index.vue` import**
+
+将：
+
+```js
+import { clearSession, getUser } from '../../utils/auth-mock.js'
+```
+
+改为：
+
+```js
+import { clearSession, getUser } from '../../utils/auth.js'
+```
+
+- [ ] **Step 3: 更新 `pages/login/index.vue` 的 script import 与登录调用**
+
+将 import：
+
+```js
+import {
+  isLoggedIn,
+  mockPasswordLogin,
+  mockWechatLogin
+} from '../../utils/auth-mock.js'
+```
+
+改为：
+
+```js
+import {
+  isLoggedIn,
+  passwordLogin,
+  clearLegacyMockSessionIfNeeded
+} from '../../utils/auth.js'
+```
+
+在 `onShow` 开头增加：
+
+```js
+clearLegacyMockSessionIfNeeded()
+```
+
+将 `onPasswordLogin` 内：
+
+```js
+mockPasswordLogin({
+  username: this.username,
+  password: this.password
+})
+```
+
+改为：
+
+```js
+await passwordLogin({
+  username: this.username,
+  password: this.password
+})
+```
+
+（本 Task 暂保留 `onWechatLogin` 方法体；Task 5 再置灰并移除。）
+
+- [ ] **Step 4: 删除 `auth-mock.js`**
+
+```bash
+rm /Users/wuzilong/work/00code/zkxw/mobile-h5/utils/auth-mock.js
+```
+
+确认无残留引用：
+
+```bash
+rg "auth-mock" /Users/wuzilong/work/00code/zkxw/mobile-h5
+```
+
+Expected: 无匹配。
+
+- [ ] **Step 5: Commit**
+
+```bash
+cd /Users/wuzilong/work/00code/zkxw
+git add mobile-h5/utils/auth.js mobile-h5/pages/login/index.vue mobile-h5/pages/index/index.vue
+git add -u mobile-h5/utils/auth-mock.js
+git commit -m "$(cat <<'EOF'
+feat(mobile-h5): replace mock auth with real password login API
+
+EOF
+)"
+```
+
+---
+
+### Task 5: 微信按钮置灰 + 登录页收尾
+
+**Files:**
+- Modify: `mobile-h5/styles/components/login.scss`
+- Modify: `mobile-h5/pages/login/index.vue`
+
+- [ ] **Step 1: 增加禁用样式**
+
+在 `login.scss` 的 `.login-wechat` 块后追加：
+
+```scss
+.login-wechat.is-disabled {
+  opacity: 0.45;
+  pointer-events: none;
+}
+```
+
+- [ ] **Step 2: 模板置灰并去掉点击**
+
+将：
+
+```html
+    <view class="login-wechat" @click="onWechatLogin">
+      <image class="login-wechat__icon" src="/static/wechat-logo.png" mode="aspectFit" />
+      <text>微信授权登录</text>
+    </view>
+```
+
+改为：
+
+```html
+    <view class="login-wechat is-disabled">
+      <image class="login-wechat__icon" src="/static/wechat-logo.png" mode="aspectFit" />
+      <text>微信授权登录</text>
+    </view>
+```
+
+删除 `methods` 中的 `onWechatLogin` 整段方法。
+
+- [ ] **Step 3: Commit**
+
+```bash
+cd /Users/wuzilong/work/00code/zkxw
+git add mobile-h5/styles/components/login.scss mobile-h5/pages/login/index.vue
+git commit -m "$(cat <<'EOF'
+feat(mobile-h5): disable WeChat login button until API is ready
+
+EOF
+)"
+```
+
+---
+
+### Task 6: 联调验收
+
+**前置：** 本地 backend 已启动（如 `./start-local.sh`），`API_BASE_URL` 指向该实例。
+
+- [ ] **Step 1: 公钥接口可达**
+
+```bash
+curl -sS http://127.0.0.1:8000/api/web/auth/login-rsa-public-key | head -c 200
+```
+
+Expected: JSON 含 `"code":200` 与 `publicKeyPem`。
+
+- [ ] **Step 2: 微信开发者工具 / HBuilderX 运行 `mobile-h5`**
+
+1. 开发设置关闭「校验合法域名」（或已配置 request 合法域名）。
+2. 使用后台已有启用且有角色的账号登录 → 应进首页；Storage 中 `zkxw_mobile_token` 为 JWT（非 `mock_` 前缀）。
+3. 错误密码 → Toast「用户名或密码错误」（或后端原文）。
+4. 微信按钮置灰、点击无反应。
+5. 退出登录（若首页有出口）后会话清除，回到登录页。
+
+- [ ] **Step 3: 若联调失败，按清单排查**
+
+| 现象 | 检查 |
+|------|------|
+| 网络异常 | `API_BASE_URL`、后端是否启动、真机是否应用局域网 IP |
+| 登录加密失败 / 凭证过期 | 设备时间、后端 RSA 是否正常 |
+| jsencrypt 找不到模块 | HBuilderX npm 构建；必要时 vendor `jsencrypt.min.js` 到 `utils/vendor/` 并改 import |
+| CORS（仅 H5） | 后端 CORS；小程序端一般无 CORS 问题 |
+
+- [ ] **Step 4:（可选）文档交叉引用**
+
+若方便，在 `docs/superpowers/specs/2026-08-10-miniprogram-login-ui-design.md` 的非目标中注明「账号密码已对接真实 API，见 `2026-08-10-mobile-h5-password-login-api-design.md`」；无则跳过。
+
+---
+
+## Spec coverage checklist
+
+| Spec 项 | Task |
+|---------|------|
+| 复用 login + RSA | 3、4 |
+| `API_BASE_URL` 可改 | 1 |
+| 存 token / refreshToken / userInfo | 4 |
+| 微信置灰不可点 | 5 |
+| 不做 refresh / 微信接口 / 后端改动 | 全计划遵守 |
+| 错误 Toast / 网络文案 | 2、4 |
+| 清除 mock_ 假会话 | 4 `clearLegacyMockSessionIfNeeded` |
+| 验收标准 | 6 |