图奕科技 开发文档
平台登录 图奕统一认证接入指南
面向图奕自有产品的服务端、Web 和桌面客户端开发者。文档可以公开阅读，不代表平台开放第三方注册；创建产品、分配权限及管理配置仍需管理员授权。
本文描述仓库当前已实现的接口，不表示线上已部署最新版本，也不代替真实产品联调。未标记为已支持的登录方式不要自行拼装内部接口。
接入前先分清三种身份
| 身份 | 用途 | 凭据放在哪里 | 能否调用短信、支付 API |
|---|---|---|---|
| Web OIDC Client | 官网用户登录 | Client Secret 仅服务端 | 不能 |
| Native OIDC Client | 桌面用户登录 | 无 Client Secret；刷新令牌存系统凭据库 | 不能 |
| Service Client | 产品服务调用 | Client Secret 仅产品服务端 | 依已授权 Scope |
平台负责认证、事务短信发送和支付处理。产品负责商品、定价、业务订单、权益，以及自己的业务用户和业务会话。平台登录成功不等于已经登录产品，需要产品完成回调验证和本地会话建立。
当前可以接到哪一步
| 能力 | 当前接口 | 注意事项 |
|---|---|---|
| Web 登录 | OIDC 授权码 + S256 PKCE | 验签后建立本地业务会话 |
| 官网自定义登录 | 浏览器直连 + 后端换码，不跳页 | Web Client 显式授权、精确 Origin；见 自定义网页登录 |
| 直接找回 / 设置密码 | Web / Native 独立密码事务 | 默认关闭；短信验证后统一撤销，见 密码管理 |
| 桌面登录 | 系统浏览器 + OIDC + 回调 | 支持 Public Native Client |
| 桌面原生扫码、短信、密码直连 | 本版新增第一方原生认证扩展 | 部署新版本并显式开启 Native Client，见桌面章节 |
| Device Authorization Grant | 未支持 | 不要调用 /device_authorization |
| 事务短信 | 服务 Token + 模板 API | 首期仅大陆 +86；并非身份验证 API |
| 支付与退款 | 服务 Token + 收银台 + 签名事件 | 真实渠道闭环验收前保持关闭 |
| 存量账号映射 | CLI 预导入 + OIDC 自定义声明 | 不迁移密码，不自动合并冲突账号 |
创建产品与领取配置
管理员在平台后台“产品 → 创建产品”中填写名称、产品代码、官网地址和需要的能力。网云穿使用 product_code=wyc，不要因为仓库叫 wyc2026 就换一个产品代码。
以 https://www.example.com 为官网、https://api.example.com 为产品 API 地址时，向导默认生成：
| 配置项 | 示例值 | 谁来实现 |
|---|---|---|
| Web Client ID | wyc-web |
平台创建 |
| Web 回调 | https://www.example.com/auth/tuyi/callback |
网云穿服务端 |
| Native Client ID | wyc-desktop |
平台创建 |
| Native 回调 | tuyi-wyc://oauth/callback |
网云穿桌面安装程序注册，客户端处理 |
| Service Client ID | wyc-service |
平台创建，仅服务端使用 |
| Webhook | https://api.example.com/api/tuyi/events |
网云穿服务端 |
| 收银台返回 | https://www.example.com/payment/result |
网云穿网页，仅展示结果 |
这些地址是默认建议和平台注册记录，不会自动在产品仓库生成接口。创建前可以改为产品实际拥有的地址；回调、返回地址不允许通配符。勾选短信/支付不会自动完成短信模板授权、商户绑定和真实验收，仍需分别配置。
产品向导和“产品 → 编辑产品”提供“强制绑定微信”开关，默认关闭。开启后，平台只允许已验证微信身份的账号完成该产品的新授权：已经绑定微信的用户仍可选择短信或密码登录；尚未绑定的用户须改用微信扫码，并用原手机号验证码把微信绑定到同一个平台账号。该策略按 product_code 隔离，不影响其他产品，也不能被中央登录 Cookie、prompt=none、Native 或自定义网页登录绕过。
开关不会回收产品已经建立的本地业务 Session；新授权和 Refresh Token 轮换会执行策略检查。产品仍须消费安全事件并维护自己的会话。启用前应确认公众号登录渠道可用，否则未绑定用户无法完成登录。
创建成功的一次性配置包包含 Web Secret、Service Secret、Webhook Secret（按所选能力）。保存到产品服务端的受限配置或 Secret 管理中，不要贴进工单、前端代码、Git 或日志。关闭一次性回执后不能再次查看原文；丢失应按密钥轮换流程处理。
环境配置
以下是产品侧建议变量名，不是平台 config.env 新增配置。域名以本页顶部的本实例 Issuer 为准；正文默认正式域名。
TUYI_ISSUER=https://platform.too1.net
TUYI_PRODUCT_CODE=wyc
TUYI_WEB_CLIENT_ID=wyc-web
TUYI_WEB_CLIENT_SECRET=REPLACE_WITH_SERVER_ONLY_SECRET
TUYI_WEB_REDIRECT_URI=https://www.example.com/auth/tuyi/callback
TUYI_NATIVE_CLIENT_ID=wyc-desktop
TUYI_NATIVE_REDIRECT_URI=tuyi-wyc://oauth/callback
TUYI_SERVICE_CLIENT_ID=wyc-service
TUYI_SERVICE_CLIENT_SECRET=REPLACE_WITH_SERVER_ONLY_SECRET
TUYI_WEBHOOK_SECRET=REPLACE_WITH_SERVER_ONLY_SECRET
桌面包只包含 Issuer、Native Client ID 和 Native 回调；不能打包上述任何 Secret。开发、staging、正式环境使用不同客户端和回调配置，不要让本地调试端接收生产授权。
标准端点
| 方法 | 地址 | 用途 |
|---|---|---|
| GET | /.well-known/openid-configuration |
发现文档 |
| GET | /.well-known/jwks.json |
ID Token 签名公钥 |
| GET | /oauth2/authorize |
浏览器授权 |
| POST | /oauth2/token |
换取/刷新用户 Token，或获取服务 Token |
| GET | /oauth2/userinfo |
获取当前用户信息 |
| POST | /oauth2/revoke |
撤销令牌 |
| GET | /oauth2/logout |
中央登出 |
不要用旧 sso.too1.net 作为新接入的 Issuer，不要通过 HTTP 跳转来发现 Token 端点。Issuer 必须完全匹配，包括协议和路径。
建议阅读顺序
- Web 登录：所有产品先理解这份认证契约。
- 桌面客户端：原生扫码/短信/手机号密码 API、事务、PKCE、错误恢复，以及保留的标准浏览器模式。
- 网云穿实施清单与旧账号映射：保留老用户、资源和权限。
- 服务凭证及短信、产品成员、支付退款、Webhook。
- 联调验收与排障：通过后再灰度。
所有章节支持 Markdown 下载，便于交给另一仓库的开发者或代码助手；下载的是文档，不包含实际产品配置和密钥。