# wyc2026 实施清单

本文可以直接交给网云穿仓库的开发者或代码助手。平台仓库不替网云穿修改官网、业务 API、桌面客户端、商品、订单或权益。

## 本轮接入范围

可以开始官网 OIDC、服务端平台 API 适配、Webhook、映射与测试。**本版已补齐桌面第一方原生认证接口，客户端可保留扫码、短信验证码、手机号密码 UI，不必打开系统浏览器。** 先部署平台新包，在 OIDC 客户端中为 `wyc-desktop` 显式开启原生登录，再按 [原生认证契约](NATIVE.md) 联调。此仓库未修改 WYC 客户端，不能把平台支持等同于 WYC 已完成接入。

## 配置与职责

| 模块 | 网云穿实施内容 |
| --- | --- |
| 配置 | 固定 Issuer `https://platform.too1.net`、产品代码 `wyc`；按环境分离客户端 |
| 官网登录 | 登录发起、回调、state/nonce/PKCE、JWKS 验签和本地 Session |
| 桌面 | 独立 Native Client；保留现有登录 UI，认证后端抽象为可替换适配层 |
| 用户映射 | 保留原业务用户 ID，以已验证的 sub 与迁移声明建立唯一映射 |
| 服务调用 | 5 分钟 Service Token 缓存、并发合并刷新、最小 Scope、超时 |
| 短信 | 使用平台模板代码；业务验证码仍由所属认证流程验证，不重复实现 SSO 登录 |
| 支付 | 服务端按业务订单定价，创建支付会话、查询、关闭和退款 |
| 事件 | 验签、数据库幂等、权益事务、安全事件撤销本地会话 |
| 运维 | 接入开关、请求编号、错误指标、旧入口回退 |

## 推荐交付顺序

### 第一步：只跑通测试账号官网登录

创建 `wyc-web`，实现 `/auth/tuyi/callback`，验证正确/错误 state、nonce、PKCE，授权码重放及用户取消。平台登录后在网云穿显示当前业务用户，刷新网页仍保持网云穿自己的会话。

暂时不迁移全量用户、不改原密码、不下线旧登录。断开平台后，已存在的网云穿会话按自身有效期继续使用。

### 第二步：映射和安全事件

准备合成的旧用户样本（含前导零 ID、同手机号多账号、已存在 SSO 用户）。用导入报告和 claims 核查老资源不丢失，验证并发首次登录、无映射时拒绝误建账号、禁用/撤销后的本地会话处理。

### 第三步：服务 API

创建 `wyc-service`；只授权实际需要的 Scope。统一封装基础 URL、Token 获取与缓存、JSON 解析、Idempotency-Key、超时和安全错误处理。请求编号关联日志，不能记录 Authorization 或包含验证码的请求正文。

外部短信 API 只用于产品授权的事务消息；用户登录验证码由平台登录流程处理。客户端不能拿服务密钥直接调发送接口。

### 第四步：支付与 Webhook

保留网云穿的商品和订单，金额由服务端计算。保存平台 payment_id 与原 external_order_id。通过签名事件 + 查询补偿更新订单，在一次业务事务中只发一次权益。验收重复事件、回跳伪造、金额篡改、退款并发和渠道结果未知。

没有真实支付退款闭环前，不替换已有生产支付入口。

### 第五步：桌面体验决策与灰度

桌面通过 [Native 契约](NATIVE.md) 创建登录事务、在原生界面完成扫码/短信/手机号密码验证并领取一次性授权码，最后用 PKCE 换现有 OIDC Token。旧用户名/旧密码不是平台凭据；新身份必须验证手机号、确认当前协议。客户端保留可切回旧入口的发布开关，逐阶段放量。不要爬平台 HTML、共享 Cookie 或在客户端携带 Service Client Secret。

## 提交验收证据

- 测试环境和平台版本；实际登记的客户端类型及回调（不含密钥）。
- Web OIDC 正/反例测试和产品 Session 测试结果。
- 旧业务用户 ID ↔ 平台 sub 核查结果及冲突隔离报告。
- 服务 Scope 越权、客户端不含 Secret 的打包扫描。
- Webhook 重复/乱序/重启恢复与事务回滚测试。
- 真实短信及支付退款验收记录；未具备的渠道明确关闭。
- 桌面原生三种方式、扫码绑手机、协议更新、取消/过期、Token 校验及刷新均完成真实联调；没有客户端验收就不能声称“全部接入完成”。
- 灰度开关和恢复旧登录/支付入口的演练记录。

## 阅读与调试入口

- 公开文档：`https://platform.too1.net/docs`。
- [Web 登录](OIDC.md)、[桌面登录](NATIVE.md)、[账号映射](MIGRATION.md)。
- [服务凭证/短信](PLATFORM_API.md)、[产品成员与代理边界](MANAGED_USERS.md)、[支付退款](PAYMENTS.md)、[签名事件](WEBHOOKS.md)。
- [验收与错误排查](TROUBLESHOOTING.md)。

线上文档需部署对应新版二进制后才公开；在此之前可直接阅读仓库同名 Markdown 文件。