MiniProgramAuth 接口联调指南

📋 配置完成情况

✅ 已完成的配置

1. 域名配置

   • 开发环境：https://oa-dev.onwall.cn
   • 生产环境：https://manulife.onwall.cn

2. 接口路径统一

   • 统一使用 a=openid 参数
   • 完整接口：https://oa-dev.onwall.cn/srv/?a=openid&f=manulife

3. 授权模式

   • 已启用：ENABLE_AUTH_MODE = true

4. 请求参数

   • 移除了 client_name 参数
   • 保留 f=manulife 业务模块标识

🧪 测试步骤

步骤 1: 启动项目

# 开发环境（默认使用 oa-dev.onwall.cn）
pnpm dev:weapp

步骤 2: 微信开发者工具配置

1. 打开微信开发者工具
2. 导入项目（选择项目根目录）
3. 不勾选"不校验合法域名"（测试真实接口）
4. 确保已登录微信开发者账号

步骤 3: 测试授权流程

测试点 1: 首次授权（无 sessionid）

操作：

1. 清除小程序缓存（微信开发者工具 → 清除缓存 → 清除全部）
2. 刷新小程序
3. 观察控制台日志

预期结果：

✅ 应该看到以下流程：
1. app.js 启动时调用 silentAuth()
2. Taro.login() 获取微信 code
3. 调用接口: POST https://oa-dev.onwall.cn/srv/?a=openid&f=manulife
4. 请求体: { code: "xxx" }
5. 接口返回: { code: 1, data: { user: {...} } }
6. 提取 cookie 并写入 localStorage.sessionid

检查点：

• 控制台无错误
• localStorage.sessionid 有值
• 接口返回 code: 1

测试点 2: 已授权用户（有 sessionid）

操作：

1. 关闭小程序
2. 重新打开（不清除缓存）
3. 观察控制台日志

预期结果：

✅ 应该看到以下流程：
1. hasAuth() 返回 true（检测到 sessionid）
2. 跳过授权流程
3. 直接进入首页

检查点：

• 不会重复调用授权接口
• 直接显示首页内容

测试点 3: 401 自动刷新

操作：

1. 手动删除 localStorage.sessionid
2. 访问任何需要登录的接口
3. 观察自动刷新流程

预期结果：

✅ 应该看到以下流程：
1. 接口返回 401
2. request.js 拦截器捕获 401
3. 调用 refreshSession()
4. Taro.login() 获取新 code
5. 重新调用授权接口
6. 重放原始请求

检查点：

• 用户无感知（静默刷新）
• 原始请求自动重放成功
• 新的 sessionid 已保存

测试点 4: 授权页跳转（降级方案）

操作：

1. 模拟授权失败（修改接口返回错误）
2. 观察是否跳转到授权页

预期结果：

✅ 应该看到以下流程：
1. 授权失败
2. 保存当前页面路径
3. 跳转到 /pages/auth/index
4. 授权成功后回跳原页面

检查点：

• 正确跳转到授权页
• 授权成功后回跳正确
• 路径参数不丢失

📊 接口说明

请求格式

POST https://oa-dev.onwall.cn/srv/?a=openid&f=manulife
Content-Type: application/json

{
  "code": "微信登录code"
}

响应格式

成功响应：

{
  "code": 1,
  "msg": "success",
  "data": {
    "user": {
      "id": 123,
      "avatar_url": "https://...",
      "name": "用户姓名"
    }
  }
}

Cookie 处理：

• 后端通过 Set-Cookie 头返回 sessionid
• 小程序端从 response.cookies[0] 读取
• H5 端从 response.header['set-cookie'] 读取

🐛 常见问题排查

问题 1: 接口返回 404

原因：接口路径错误

检查：

// 确认 buildApiUrl 构建的 URL
console.log(buildApiUrl('openid'))
// 应该输出: https://oa-dev.onwall.cn/srv/?a=openid&f=manulife

解决：确认后端接口参数为 a=openid

问题 2: 接口返回 403

原因：域名未白名单

检查：

• 微信开发者工具 → 详情 → 本地设置
• 确认是否勾选了"不校验合法域名"

解决：

1. 开发阶段：勾选"不校验合法域名"
2. 生产环境：在微信公众平台配置服务器域名白名单

问题 3: Cookie 未保存

原因：后端未返回 Set-Cookie

检查：

// 在 refreshSession 中添加日志
const response = await Taro.request({...})
console.log('响应头:', response.header)
console.log('Cookie:', response.cookies)

解决：

• 确认后端返回了 Set-Cookie 头
• 小程序端确保返回格式正确

问题 4: 授权后仍然跳转登录页

原因：sessionid 未正确保存

检查：

// 在控制台执行
console.log(Taro.getStorageSync('sessionid'))

解决：

• 确认 extractCookie() 函数正确提取了 cookie
• 确认 Taro.setStorageSync('sessionid', cookie) 成功执行

🔍 调试技巧

1. 开启详细日志

在 src/utils/request.js 拦截器中添加日志：

// 请求拦截器
config => {
  console.log('🔵 请求:', config.url, config.data)
  return config
}

// 响应拦截器
response => {
  console.log('🟢 响应:', response.config.url, response.data)
  return response
}

// 错误拦截器
error => {
  console.error('🔴 错误:', error.config?.url, error.response?.status)
  return Promise.reject(error)
}

2. 监控网络请求

微信开发者工具 → Network 面板：

• 查看 openid 接口请求
• 确认请求参数和响应格式
• 检查 Cookie 是否正确返回

3. 查看 Storage

微信开发者工具 → Storage 面板：

• 确认 sessionid 存在
• 查看值是否正确

✅ 验收标准

联调通过的标准：

• 首次授权能成功获取 sessionid
• 已授权用户能直接进入首页
• 401 时能自动刷新 sessionid
• 授权失败时能跳转到授权页
• 授权成功后能正确回跳
• 所有接口请求都能带上 sessionid

📝 后续优化建议

1. 添加加载提示：授权时显示 loading
2. 错误提示优化：友好的错误文案
3. 重试机制：授权失败时的重试策略
4. 埋点统计：授权成功率统计

📞 联系方式

如有问题，请联系开发团队。