07 实名认证

驱动列表

驱动 key	来源	说明
zhima	内置	支付宝芝麻信用
plugin:http_api	插件	HTTP 第三方 API 模板
plugin:idcard_meta	插件	身份证二要素
plugin:tencent_face	插件	腾讯云人脸核身
plugin:alipay_face	插件	支付宝人脸

调度：RealnameProviderService / RealnameService

---

接口 RealnameProviderInterface

public function name(): string;
public function title(): string;
public function configFields(): array;

public function initVerify(
    string $realName,
    string $idCard,
    array $config,
    array $context = [],  // user_id, return_url, client_ip
): RealnameInitResult;

public function queryStatus(
    string $bizNo,
    array $config,
    array $context = [],
): RealnameQueryResult;

同步 vs 异步

• 同步：initVerify 直接返回 status: approved（如二要素）
• 异步：返回 pending + certifyUrl + bizNo，前台跳转后轮询 queryStatus

---

开发 certification 插件

namespace certification\my_verify;

use app\common\lib\CertificationPlugin;
use app\common\realname\RealnameInitResult;
use app\common\realname\RealnameQueryResult;

class MyVerify extends CertificationPlugin
{
    public $info = [ /* ... */ ];

    public function name(): string { return 'my_verify'; }
    public function title(): string { return '我的实名'; }

    public function configFields(): array { /* 后台表单字段 */ }

    public function initVerify(...): RealnameInitResult { /* ... */ }
    public function queryStatus(...): RealnameQueryResult { /* ... */ }
}

---

后台启用

1. 插件市场安装 certification 类插件
2. 系统设置 → 实名认证 → 驱动选 plugin:插件名
3. 在插件配置或实名分组填写 API 密钥

内置 zhima 配置存在 realname 分组；插件配置在 kd_addons.config。

---

前台 / 回调 API

方法	路径	说明
POST	/home/auth/realname	body：real_name · id_card · return_url?
GET	/home/auth/realnameQuery	query：biz_no
GET|POST	/api/notify/realname	第三方异步回调（验参后跳转前台）
GET	/home/content/siteConfig	data.realname 公开设置

完整对接表（含后台 saveRealname、驱动键约定）见 04b §8。

---

下一章：08-notify