crm-backend-matt/.scratch/token-service-split/spec.md

拆分 TokenService：JwtCodec + SessionStore + PreLoginTicketStore Spec

Status: ready-for-agent

把承载三个概念的宽接口 TokenService（12 方法级、JWT 密码学 + 单端在线会话索引 + 预登录票 + 被顶下线标记同居一类）拆成三个按概念划分的深模块：无状态的 JwtCodec（签发/验签）、独占「单端在线」不变量的 SessionStore（会话生命周期 + 真相/线索索引 + 被顶下线标记）、以及独立的 PreLoginTicketStore（短命预登录票）。纯重构，不改任何对外 HTTP 行为、错误码、Redis 数据结构。

域：crm-auth。前置功能已由 single-device-login/spec.md 落地（本 spec 只重构其内部实现，不新增业务）。

---

Problem Statement

作为维护 crm-auth 的开发者，TokenService 一个 @Component 里塞了三件互不相干的事：JWT 签发/验签（纯密码学）、单端在线会话索引（token:{jti} 真相 + session:{userId}:{clientType} 线索 + 滑动续期 + 脏索引自愈 + CAS 删索引）、预登录票（GETDEL 即烧）、被顶下线标记。这是一个宽接口：接口方法数 ≈ 实现复杂度，没有一个模块专门为「每个 (userId, clientType) 至多一个活会话」这条核心不变量负责。后果：

• 想给「单端在线」不变量写专属测试，只能对着一个什么都做的类，测试意图被稀释。
• 每请求认证热路径（JwtAuthenticationFilter.verifyToken）把「验签」和「查 Redis 会话 + 续期」焊死在一个方法里，filter 无法只依赖它真正需要的那一小片。
• 登录/校验的上层编排测试必须 mock 一个 12 方法的门面，牵一发动全身。

Solution

作为开发者，我希望 TokenService 按概念拆成三个深模块（小接口、大实现），使：

• JwtCodec 无状态、不碰 Redis，只做「签一个带 jti 的 JWT」和「验签并取出 jti」，可用纯密码学单测覆盖。
• SessionStore 独占所有会话 Redis key（token 真相键、反向索引线索键、被顶下线标记）与「单端在线」不变量、真相/线索一致性关系、滑动续期、脏索引自愈、CAS 删索引——这些实现细节全部落在它内部，不再横跨两个类。
• PreLoginTicketStore 独立承载短命预登录票的签发与 GETDEL 消费。

登录/登出/校验的编排（先建会话拿 jti、再签 token；先验签取 jti、再解析会话）上移到本就该知道顺序的调用方（AuthServiceImpl / JwtAuthenticationFilter / DebugTokenController）。对外 HTTP 契约、错误码、Redis 数据结构、JWT payload 结构全部保持不变——存量 token 不失效。

分两步落地，先摘风险最低的预登录票，再做会话拆分，各步独立编译、测试、评审。

User Stories

1. 作为 crm-auth 维护者，我希望「签发/验签 JWT」独立成 JwtCodec，以便用不依赖 Redis 的纯单测覆盖密码学行为。
2. 作为维护者，我希望 JwtCodec.sign(jti, userId) 只接收调用方给定的 jti，以便会话身份的生成权归 SessionStore，密码学模块保持无状态。
3. 作为维护者，我希望 JwtCodec.parseJti(token) 对非法/过期签名的 token 统一返回 null（保留现有限频告警），以便调用方用单一 null 判定处理所有验签失败。
4. 作为维护者，我希望「单端在线」不变量（每个 (userId, clientType) 至多一个活会话）由 SessionStore 独家负责，以便这条核心安全不变量有一个明确的家和专属测试。
5. 作为维护者，我希望 SessionStore.openSession(loginUser) 生成 jti、写 token 真相键 + 反向索引线索键（TTL 对齐 ttlDays），返回 jti，以便登录编排拿 jti 去签 token。
6. 作为维护者，我希望存量登录态（loginUser 无 clientType）在 openSession 时只写 token 键、不建索引，以便老会话行为与现状一致。
7. 作为维护者，我希望 SessionStore.resolveSession(jti) 查 token 真相键返回 AuthLoginUser，token 键不存在时返回 null，以便每请求热路径用 null 判定区分「活会话 / 已下线过期被顶」。
8. 作为维护者，我希望 resolveSession 读时顺带滑动续期（剩余 TTL 不足一半时 token 键 + 索引键一并续满，存量无 clientType 会话只续 token 键），且这一副作用对调用方透明，以便续期这项 SessionStore 内政不泄漏成 filter 的显式步骤。
9. 作为维护者，我希望 SessionStore.isOnline(userId, clientType) 以索引为线索命中后回查 token 真相键确认活着才算在线，token 已死时顺手删脏索引自愈，以便在线检测遵循「真相/线索」一致性风格。
10. 作为维护者，我希望 SessionStore.kick(userId, clientType) 埋被顶下线标记（TTL 对齐 ttlDays）+ 删旧 token 键，索引留待随后 openSession 覆写，以便顶号踢旧的语义原样保留。
11. 作为维护者，我希望 SessionStore.isKicked(jti) 报告被顶下线标记是否仍在，以便 filter 在 resolveSession 返回 null 时区分「被顶下线」与「普通过期」。
12. 作为维护者，我希望 SessionStore.closeSession(jti) 删 token 键 + 用 CAS 删索引（仅当索引仍指向本次 jti），以便登出不误删已被顶号覆写指向新会话的索引。
13. 作为维护者，我希望预登录票的签发/消费独立成 PreLoginTicketStore（issue / consume），以便它与 JWT、会话索引解耦（独立 key、独立生命周期）。
14. 作为维护者，我希望 PreLoginTicketStore.consume(ticket) 用 GETDEL 原子读删（拿到即烧），对空白入参不碰 Redis 直接返回 null，以便防并发双签/重放的语义原样保留。
15. 作为登录编排的调用方（AuthServiceImpl），我希望登录成功路径先 openSession 拿 jti、再 jwtCodec.sign(jti, userId) 拿 token，以便会话与 token 的连体生成显式且有序。
16. 作为调用方，我希望冲突路径改用 preLoginTicketStore.issue(...) 签发预登录票、isOnline 检测在线，以便顶号决策链路行为不变。
17. 作为调用方，我希望确认顶号路径用 preLoginTicketStore.consume(...) 读取、sessionStore.kick(...) 踢旧、再 openSession + sign 签新，以便顶号踢旧签新的顺序与现状一致。
18. 作为调用方，我希望登出路径 jwtCodec.parseJti(token) 取 jti 后 sessionStore.closeSession(jti)，以便注销的索引 CAS 删除语义原样保留。
19. 作为每请求认证热路径（JwtAuthenticationFilter），我希望 jwtCodec.parseJti(token) → sessionStore.resolveSession(jti)，为 null 时 sessionStore.isKicked(jti) 区分被顶下线，以便被顶设备下次请求仍得到专门的错误码。
20. 作为调试端点（DebugTokenController），我希望复用与正式登录一致的 openSession + sign 编排，以便调试 token 行为与真登录完全一致。
21. 作为维护者，我希望重构后 TokenService 类被完全移除（其职责由三个新模块承接），以便不留下宽接口门面造成的复杂度残留。
22. 作为维护者，我希望对外 HTTP 契约、错误码（61013–61016）、Redis 数据结构、JWT payload（仍只 jti + userId）全部不变，以便存量 token 不失效、老前端不受影响。

Implementation Decisions

• 拆分维度按概念，不按方法数。三个概念各成一个深模块，接口小、实现深。
• 新增模块与接口：
  • JwtCodec（接口 + impl）：String sign(Long userId /* 或 String */, String jti) 语义上「用给定 jti 签一枚带 userId 的 JWT」；String parseJti(String token) 验签成功返回 jti，失败返回 null。无状态、不注入 Redis，仅依赖 AuthProperties（密钥、限频告警计数器留在 impl）。
  • SessionStore（接口 + impl）：String openSession(AuthLoginUser)、AuthLoginUser resolveSession(String jti)（读时滑动续期）、void closeSession(String jti)、boolean isOnline(String userId, ClientTypeEnum)、void kick(String userId, ClientTypeEnum)、boolean isKicked(String jti)。注入 StringRedisTemplate + AuthProperties。独占 token 真相键、反向索引线索键、被顶下线标记三类 key 及其一致性关系。CAS 删索引的 Lua 脚本随 impl 迁移。
  • PreLoginTicketStore（接口 + impl）：String issue(String userId, ClientTypeEnum)、PreLoginSession consume(String ticket)。注入 StringRedisTemplate + AuthProperties。
• 编排上移：登录/登出/校验的「先建会话再签 / 先验签再解析」顺序移到 AuthServiceImpl、JwtAuthenticationFilter、DebugTokenController。AuthServiceImpl 现已在编排 isOnline → kick → createToken，顺理成章。
• 滑动续期归属：埋进 SessionStore.resolveSession，作为读的副作用，对调用方透明（deep module：简单接口藏「查 + 判 TTL + 续两个 key」）。不设独立的 renew 公开方法。
• replace, don't layer：JwtCodec 不是 TokenService 的门面转发层；TokenService 类整体删除，职责真正迁移到三个模块，不保留宽接口。
• 不变项：Redis key 前缀（crm:auth:token/session/prelogin/kicked）、TTL 策略、JWT payload、AuthConstants、错误码、LoginResultDTO/AuthLoginUser 结构、HTTP 契约。
• 分两步交付：
  • 第一步：抽 PreLoginTicketStore，从 TokenService 删除 prelogin 相关方法与 helper，AuthServiceImpl 改用新模块。独立编译 + 测试 + BOM 扫描。
  • 第二步：抽 JwtCodec + SessionStore，删除 TokenService，上移编排，改 AuthServiceImpl/JwtAuthenticationFilter/DebugTokenController。独立编译 + 全量 crm-auth 测试 + BOM 扫描。
• 尊重既有 ADR / spec：single-device-login/spec.md 的一致性风格 B（真相/线索）、CAS 删索引、GETDEL 即烧、滑动续期对齐等语义在重构后逐条保留，不引入新业务决策。

Testing Decisions

• 好测试只验外部行为：验各模块通过接口可观察的效果（返回值、对 StringRedisTemplate 的交互契约），不验私有 helper。
• 测试基建复用现状：现有 TokenServiceTest 用 mock StringRedisTemplate + ValueOperations、以真密钥 mintToken 铸合法 JWT，不用嵌入式 Redis。新模块单测沿用这套 mock-Redis 基建。
• 分层测试：
  • JwtCodecImplTest：纯单测，签→解 jti 往返、验签失败/垃圾 token 返回 null、限频告警不刷屏。无 Redis。
  • SessionStoreImplTest：承接 TokenServiceTest 中会话相关用例——openSession 写 token 键 + 索引（含无 clientType 只写 token 键）、resolveSession 滑动续期（不足一半续、超过一半不续、存量只续 token 键）、isOnline 索引命中/未命中/脏索引自愈、kick 埋标记 + 删旧 token、closeSession CAS 删索引（含无 clientType 只删 token 键）、isKicked。锁住「单端在线」不变量与真相/线索一致性。
  • PreLoginTicketStoreImplTest：承接 TokenServiceTest 中 prelogin 相关用例——issue 写 payload（TTL 取配置）、consume GETDEL 读删并解析、缺失返回 null、空白入参不碰 Redis。
• 上层编排测试：AuthServiceImplTest、JwtAuthenticationFilterTest 现 mock TokenService；改为 mock JwtCodec + SessionStore（+ PreLoginTicketStore），重写编排桩（登录：openSession→sign；校验：parseJti→resolveSession→isKicked；顶号：consume→kick→openSession→sign）。塞内存/mock 假实现，不碰真 Redis。
• prior art：TokenServiceTest（mock-Redis 契约测试）、候选 1 的 OwnerSnapshotResolverImplTest（接口 + impl 深模块的分层单测与「假实现替换整模块」模式）。
• 删除：TokenServiceTest 随 TokenService 类一并删除，其用例已按概念分流到三个新单测。

Out of Scope

• 任何对外 HTTP 契约、错误码、返回结构、Redis 数据结构、JWT payload 的改动。
• 单端在线业务逻辑本身的变更（顶号决策、被顶下线码等由 single-device-login/spec.md 定义，不动）。
• 引入嵌入式 Redis 或集成测试基建（继续用 mock-Redis 单测）。
• 把 SessionStore / JwtCodec 跨模块下沉到 crm-base 之类的共享层。
• 候选清单中的其他架构改进（owner 快照已单独完成；display 名称回显、opportunity port 收敛等属另案）。

Further Notes

• 风险集中在第二步：它触及每请求认证热路径与「单端在线」安全不变量。分两步正是为了先把零风险的预登录票落袋，再单独面对会话拆分。
• 领域词沿用 single-device-login/spec.md：端类型 clientType、在线会话、真相/线索、被顶下线、预登录票、单端在线不变量。
• 收尾统一：BOM 扫描（所有 *.java）→ mvn compile → 跑 crm-auth 测试。
• AuthLoginUser / PreLoginSession 的包位置本次不迁移，避免扩大改动面。