Medical Face Auth (医疗实人认证 SDK)

这是一个针对阿里云金融级实人认证（CloudAuth）的辅助库，专为医疗场景（或任何需要身份验证的场景）设计。

安装

npm install @treecko/medical-face-auth
# 或
pnpm add @treecko/medical-face-auth

使用说明

服务端 (Node.js)

1. 初始化客户端

import { MedicalFaceAuthClient } from '@treecko/medical-face-auth';

const client = new MedicalFaceAuthClient({
  accessKeyId: process.env.ALIBABA_CLOUD_ACCESS_KEY_ID, // 阿里云 AccessKey ID
  accessKeySecret: process.env.ALIBABA_CLOUD_ACCESS_KEY_SECRET, // 阿里云 AccessKey Secret
  // endpoint: 'cloudauth.aliyuncs.com', // 可选，默认为杭州节点
});

2. 发起认证 (获取认证链接)

当你的前端需要开始认证流程时，调用此接口。必须传入前端收集到的 metaInfo。

// 从前端请求中获取
const metaInfo = JSON.stringify({ ... }); 

try {
  const result = await client.initFaceVerify({
    sceneId: "YOUR_SCENE_ID", // 在阿里云控制台创建
    outerOrderNo: "YOUR_UNIQUE_ORDER_NO", // 你的业务订单号
    metaInfo: metaInfo,
    certName: "真实姓名", // 可选: 如果你已知用户姓名
    certNo: "身份证号", // 可选: 如果你已知用户身份证号
    model: "Sales", // 或 "PC"，根据你的业务模式选择，参考阿里文档
  });

  console.log(result.certifyUrl); // 认证跳转链接
  console.log(result.certifyId);  // 认证唯一ID (需要保存用于后续查询结果)
  // 将 result.certifyUrl 返回给前端进行跳转
} catch (error) {
  console.error('认证初始化失败:', error);
}

3. 查询结果

用户在 certifyUrl 完成认证后，会跳转回你设置的 returnUrl。此时调用此接口查询最终结果。

const certifyId = "RECEIVED_CERTIFY_ID"; // 从初始化步骤或回调中获取

const verification = await client.describeFaceVerify(certifyId);

if (verification.resultObject?.passed === 'T') {
  console.log('认证成功!');
  // verification.resultObject.materialInfo 包含人脸照片等素材
} else {
  console.log('认证失败');
}

客户端 (前端 / React / Vue)

现在您可以直接从包中导入前端工具，无需手动在 HTML 中添加 script 标签（工具会自动处理）。

import { loadAuthScript, getMetaInfo } from '@treecko/medical-face-auth/client';

// 在你的组件或业务逻辑中
async function startVerification() {
  try {
    // 1. 确保阿里云脚本已加载
    await loadAuthScript();

    // 2. 获取 MetaInfo
    const metaInfo = getMetaInfo();

    // 3. 发送给后端
    const response = await fetch('/api/auth/init', {
        method: 'POST',
        body: JSON.stringify({ metaInfo: JSON.stringify(metaInfo) }), // 注意：metaInfo 通常是一个对象，部分接口可能需要 JSON 字符串
        headers: { 'Content-Type': 'application/json' }
    });
    
    const data = await response.json();
    
    // 4. 跳转认证
    if (data.certifyUrl) {
      window.location.href = data.certifyUrl;
    }
    
  } catch (err) {
    console.error('认证启动失败', err);
  }
}

完整集成示例 (Express)

import express from 'express';
import { MedicalFaceAuthClient } from '@treecko/medical-face-auth';

const app = express();
app.use(express.json());

const authClient = new MedicalFaceAuthClient({
  accessKeyId: "YOUR_AK",
  accessKeySecret: "YOUR_SK"
});

// 1. 发起认证接口
app.post('/api/auth/init', async (req, res) => {
  const { metaInfo, userId } = req.body;
  
  try {
    const result = await authClient.initFaceVerify({
      sceneId: "12345678", 
      outerOrderNo: `ORDER_${Date.now()}`,
      metaInfo: JSON.stringify(metaInfo),
      model: "Sales",
      returnUrl: "https://your-site.com/auth/callback" // 认证完成后跳回地址
    });

    // 建议：在此处将 result.certifyId 与 userId 关联存入数据库

    res.json({ success: true, certifyUrl: result.certifyUrl });
  } catch (error) {
    res.status(500).json({ success: false, error: error.message });
  }
});

// 2. 认证回调页面 (或接口)
// 假设这是 returnUrl 指向的路径
app.get('/auth/callback', async (req, res) => {
  // 阿里云会在 returnUrl 后通过 query 参数传递一些非敏感状态，但为了安全，
  // 应该使用之前保存的 certifyId 去服务端查询准确结果。
  // 假设我们通过某种方式（如 session 或 query 参数）找回了 certifyId
  // 注: 实际业务中通常不在 returnUrl 直接透传 certifyId，而是通过 session 查找
  
  // 这里仅做演示，假设我们知道 certifyId
  const certifyId = "YOUR_SAVED_CERTIFY_ID"; 

  try {
    const verifyResult = await authClient.describeFaceVerify(certifyId);
    
    if (verifyResult.resultObject?.passed === 'T') {
      res.send("<h1>认证成功</h1>");
    } else {
      res.send("<h1>认证失败</h1>");
    }
  } catch (error) {
    res.send("查询失败");
  }
});

app.listen(3000, () => console.log('Server running on port 3000'));