端点

加依赖后，SDK 会在业务应用里自动挂载一批端点——集成方无需实现，但应知道这些路径已被占用；另有几条由集成方挂载（SDK 只提供门面类）。

SDK 自动挂载的端点全部在 /atkonoffice/ 这一个前缀下，反向代理只需为它配一条转发规则（WebSocket 端点因须放行升级头再单列一条），见反向代理转发。

SDK 自动挂载

端点	作用
POST /atkonoffice/rpc/launch	浏览器端 SDK open() 调用，签发 atkonoffice:// 拉起链。
POST /atkonoffice/rpc/ws-ticket	事件通道重连 / 续订用的票据。
POST /atkonoffice/rpc/session/open	控制面会话握手。
GET /atkonoffice/doc/download	黑盒下载端点，经集成方解析器定位字节；带一次性下载 token。
GET /atkonoffice/doc/blank	新建空白文档的模板字节端点（webCreate 使用）。
POST /atkonoffice/license/activate	提交授权码激活。
GET /atkonoffice/license/fingerprint	查询本机机器码与授权状态。
/atkonoffice/ws（WebSocket）	实时事件通道：业务页经它接收文档生命周期事件回推。反代转发要求见部署要求。

集成方挂载

端点	挂载门面类	说明
host-page 路由（如 GET /atkonoffice/host-page）	AtkonofficeCtrl.getHostPage()	见服务端 SDK 参考
比对页路由（如 GET /atkonoffice/compare-page）	AtkonofficeCtrl.getComparePage()	Word 比对，见 Word
save 路由（如 POST /atkonoffice/doc/save）	AtkonofficeFileSaver	见服务端 SDK 参考

host-page 路由可按业务功能拆多条（普通编辑 / 只读 / Excel / PPT / 新建 / 按业务参数分流），每条各自挑打开模式；前端用 open({ pageApi }) 指到对应路由。这是推荐的分流方式，见通用控制 · 业务参数透传与分流。

---

谁在调用、怎么鉴权

这些端点分别由浏览器业务页和终端用户机器上的客户端调用，两类调用方携带的凭据在结构上不同——把全站登录拦截无差别套上去，会精确打断闭环的不同环节。按下表处理：

端点	调用方	鉴权处理
POST /atkonoffice/rpc/launch	浏览器业务页（代表已登录用户）	必须用你的登录态保护。⚠️ 不能放行（permitAll）——放开等于任何人 POST 一个 docId 就能换到一条可下载该文档的链接
POST /atkonoffice/rpc/ws-ticket	浏览器业务页	同上，用你的登录态保护
POST /atkonoffice/rpc/session/open	客户端进程	必须放行。结构上不可能携带浏览器的 cookie / token；用登录态拦它 → 点「编辑」后干等、编辑器窗口起不来
/atkonoffice/ws（WebSocket）	客户端与业务页，自带 SDK 签发的一次性凭据	必须放行。拦它 → 业务页收不到任何事件回推
GET /atkonoffice/doc/download	客户端，自带 SDK 签发的一次性下载凭据	必须放行。拦它 → 文档打不开
host-page / 比对页路由（集成方挂载）	客户端	用你的登录态保护 + 凭据经 open({ headers }) 透传（见下）
save 路由（集成方挂载）	客户端	同上

其余自动挂载端点（空白模板、授权激活 / 查询）同样由客户端直接访问或用于部署排障，不应套浏览器登录态。

open({ headers }) 是客户端这条腿唯一的凭据入口：host-page / save 路由用你自己的登录态保护时，凭据必须在前端 open() 里经 headers（或 cookie / storage，见类型 · AtkonofficeOpenRequest）传入，客户端会把它应用到这些请求上。不传的症状：浏览器侧明明已登录，客户端却空手请求受保护的 host-page → 401/403 → 编辑器窗口显示失败提示——而你合理地以为鉴权已经配好了。

---

这些端点不经过 Spring MVC

SDK 自动挂载的端点是直接注册到 Servlet 容器的原生 servlet，由容器按路径直接命中、不经过 DispatcherServlet。于是 Spring MVC 层的机制对它们一概无效——这是集成期最容易踩、且症状最有迷惑性的一格：

对这些端点有效	对这些端点无效
Servlet 容器层机制：Filter / FilterRegistrationBean / Spring Security 过滤器链	Spring MVC 层机制：HandlerInterceptor / WebMvcConfigurer.addCorsMappings / @ControllerAdvice / HandlerMethodArgumentResolver

三个典型症状：

1. addCorsMappings 配了 CORS 却不生效，浏览器报预检失败——SDK 端点根本走不到 MVC 的 CORS 处理，怎么调都无效。
2. 写在 HandlerInterceptor 里的校验对 SDK 端点从未执行过。⚠️ 这是安全面：若你的鉴权逻辑只写在 interceptor 里，上表要求「保护」的端点一直是裸的。请把鉴权放到 Filter / Spring Security 过滤器链层。
3. 一个会把人带偏的假象：SDK 端点的 4xx 错误响应经容器错误分发转到 /error（那是 MVC 端点），MVC 层的 CORS 在那里生效——于是错误响应「看起来」有 CORS 头，而成功响应和预检没有。据此判断「CORS 已配好、问题在别处」，方向就错了。

跨域部署时给 SDK 端点配 CORS，用 servlet 级 CorsFilter（注释标出的两处细节是踩出来的，不能省）：

@Bean
public FilterRegistrationBean<CorsFilter> atkonofficeRpcCorsFilter() {
    CorsConfiguration cors = new CorsConfiguration();
    cors.setAllowedOrigins(Arrays.asList("https://your-frontend.example"));  // ← 换成你的业务前端源
    cors.setAllowedMethods(Arrays.asList("POST", "OPTIONS"));
    cors.setAllowedHeaders(Arrays.asList("*"));

    // ① source 必须注册 "/**"：filter 已限域，对其所见路径全匹配即可；
    //    注册具体 pattern 反而匹配不上、每个预检都会被判 403
    UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
    source.registerCorsConfiguration("/**", cors);

    FilterRegistrationBean<CorsFilter> registration = new FilterRegistrationBean<>(new CorsFilter(source));
    // ② filter 必须显式限域到 SDK 端点：不设默认拦全站 /*，会抢掉你自己 MVC 端点的预检
    registration.addUrlPatterns("/atkonoffice/rpc/*");
    registration.setOrder(Ordered.HIGHEST_PRECEDENCE);
    return registration;
}

同源部署（业务页与后端同一个源，含「同域名 + 网关路径前缀」形态）不涉及 CORS，无需以上配置。