wangshaoqing/star-chart-search-enhancer

Fork 0

admin123 c7ae2fbfcb feat: add logto auth and backend metrics integration

2026-04-22 15:52:12 +08:00

12 KiB

Raw Blame History

Logto 登录集成设计

日期：2026-04-21

1. 背景

当前项目是一个 Chrome MV3 扩展，主要运行在星图市场页面，通过内容脚本注入页面并提供筛选、排序、导出等增强能力。

下一阶段需要为插件补齐登录能力，接入 Logto，目标是：

让插件具备统一的登录态
登录后可为未来的业务后端 API 获取 access token
未登录时禁止使用当前插件能力
这一版先打通登录、登出、会话持久化和 token 获取链路，不接真实业务后端

2. 已确认的产品决策

登录入口放在扩展 popup
目标范围是“插件登录态 + 为未来后端 API 预留 access token 获取能力”
当前版本暂不接真实后端 API
未登录时，插件功能整体禁用
仅允许内部已有 Logto 账号成员登录，不开放注册
popup 默认显示简洁账号信息，开发模式下显示调试信息
未登录时，市场页禁用面板需要提供“去登录”引导
配置项先使用占位值，不在设计文档里写死真实 tenant / appId / resource
设计文档明确建议新增目录结构，而不是只写抽象功能

3. 官方文档约束

本设计基于以下 Logto 官方文档：

Chrome 扩展快速开始：https://docs.logto.io/quick-starts/chrome-extension
Global API resources：https://docs.logto.io/zh-CN/authorization/global-api-resources

从官方文档抽取的关键约束如下：

Chrome 扩展应使用适配扩展场景的登录流程，重定向 URI 基于 chrome.identity.getRedirectURL()
Manifest 需要增加 identity、storage 等权限
登录流程更适合由后台脚本统一承接，而不是由内容脚本直接执行
access token 应面向一个明确的 API resource，而不是把“登录成功”与“可访问后端 API”混为一谈

这些约束直接决定了当前项目不能把认证逻辑塞进现有内容脚本入口。

4. 目标与非目标

4.1 目标

在扩展 popup 中提供登录和登出入口
在 background service worker 中统一处理 Logto 认证
在内容脚本中基于登录态控制插件可用性
登录成功后可读取基础用户信息
为未来业务后端 API 预留 getAccessToken(resource, scopes) 能力
通过 TDD 落地实现，保证认证状态切换和权限门控可回归测试

4.2 非目标

当前版本不接真实业务后端 API
当前版本不支持开放注册
当前版本不做复杂账号中心页面
当前版本不要求多标签页实时广播登录态变化
当前版本不默认展示完整 token 明文

5. 推荐架构

采用方案：Background 认证中枢 + Popup 展示 + Content 只消费状态

5.1 模块边界

`src/background/auth/*`

职责：

初始化 Logto 客户端
执行 signIn
执行 signOut
执行 getAuthState
执行 getAccessToken
统一收敛认证错误

约束：

它是唯一直接接触 Logto SDK 和登录流程的层
内容脚本和 popup 都不直接复制认证流程

`src/popup/*`

职责：

作为唯一登录入口
展示未登录态、已登录态、错误态
在开发模式下显示调试信息
向 background 发送认证消息

`src/content/*`

职责：

页面启动时查询认证状态
未登录时渲染禁用态工具栏
已登录后再初始化现有筛选、排序、导出能力

约束：

不直接依赖 Logto SDK
不自己发起登录
不长期缓存 access token

`src/shared/auth-messages.ts`

职责：

定义 popup / content / background 之间的消息协议
避免认证消息散落在多个文件中

5.2 为什么这样分层

符合 Logto 官方 Chrome 扩展接法
符合 MV3 生命周期特征，避免把认证流程绑死在不稳定的内容脚本生命周期上
后续接业务后端时只需要扩展 background 的 token 获取逻辑
权限边界清晰，未登录时不会出现“部分功能还能偷偷使用”的行为

6. 推荐目录结构

建议在当前项目中新增以下结构：

src/
  background/
    auth/
      client.ts
      controller.ts
      state.ts
      types.ts
    index.ts
  popup/
    index.html
    index.ts
    view.ts
    types.ts
  shared/
    auth-messages.ts
    auth-config.ts
  content/
    market/
      auth-gate.ts
      ...

目录约束：

background/auth/* 只做认证中枢，不掺杂市场业务逻辑
popup/* 只处理展示和用户交互
shared/* 放跨入口共享的数据结构和配置解析
content/market/auth-gate.ts 只做登录态门控，不直接写登录流程

7. 配置设计

当前版本只定义占位配置，不写死真实值。

建议新增 src/shared/auth-config.ts，集中管理以下配置：

export interface AuthConfig {
  logtoEndpoint: string;
  appId: string;
  apiResource: string;
  scopes: string[];
  enableDevAuthPanel: boolean;
}

建议占位字段：

logtoEndpoint: https://<your-tenant>.logto.app
appId: <chrome-extension-app-id>
apiResource: <your-global-api-resource-indicator>
scopes: ["openid", "profile", "offline_access"]
enableDevAuthPanel: false

配置要求：

缺失配置时必须明确报错
不允许 silent fail
后续真实接入时应能通过单点改动切换环境

8. Manifest 变更要求

现有 manifest 仅覆盖下载和内容脚本注入，接入 Logto 后至少需要补充：

permissions 增加 identity
permissions 保留或补充 storage
新增 action.default_popup
根据实际请求域名增加必要的 host_permissions

示意要求：

{
  "permissions": ["downloads", "identity", "storage"],
  "action": {
    "default_popup": "popup/index.html"
  }
}

实际值需要结合构建输出路径调整，但规范上必须支持 popup 与 identity 登录流程。

9. 认证与会话数据流

9.1 登录流程

用户点击扩展图标，打开 popup
popup 读取 background 返回的 auth state
如果未登录，点击“登录 Logto”
popup 发送 auth:sign-in 给 background
background 发起 Logto 登录流程
登录成功后，background 更新本地认证摘要状态
popup 重新读取状态并渲染已登录信息

9.2 内容脚本门控流程

内容脚本进入星图市场页
插件初始化前先发送 auth:get-state
如果未登录，渲染禁用态，不执行当前业务能力初始化
如果已登录，继续执行现有注入逻辑

9.3 登出流程

用户在 popup 点击退出登录
popup 发送 auth:sign-out
background 清理会话
popup 回到未登录态
已打开的市场页在刷新后进入禁用态

9.4 token 策略

当前版本采用：

Authorization Code Flow + PKCE
基础 scopes：openid profile offline_access
resource 对应未来业务后端 API 的 global API resource

约束：

ID token 仅用于身份展示
Access token 仅用于未来业务后端 API 调用
内容脚本只按需向 background 请求 token，不本地长期存储

10. 消息协议建议

建议新增一组显式消息类型：

type AuthMessage =
  | { type: "auth:get-state" }
  | { type: "auth:sign-in" }
  | { type: "auth:sign-out" }
  | { type: "auth:get-access-token" };

建议的状态结构：

interface AuthState {
  isAuthenticated: boolean;
  userInfo: {
    sub: string;
    name?: string;
    username?: string;
    email?: string;
  } | null;
  scopes: string[];
  resource: string | null;
  accessTokenExpiresAt: number | null;
  lastError: string | null;
}

设计要求：

状态必须可序列化
消息响应必须有稳定结构
失败时返回明确错误码或错误文案

11.1 未登录态

显示内容：

插件名称
说明文案：“登录后才能使用星图增强功能”
主按钮：“登录 Logto”
最近一次登录失败摘要（如果存在）

11.2 已登录态

默认展示：

已登录状态
用户名
邮箱
退出登录 按钮

11.3 开发调试态

仅在 enableDevAuthPanel 开启时显示：

isAuthenticated
sub
scopes
resource
token 是否可获取
access token 预计过期时间
最近一次认证错误
手动“刷新状态”按钮

默认不显示完整 token 字符串。

12. 内容脚本权限门控设计

12.1 未登录态

插件工具栏应替换为禁用面板，显示：

主提示：“请先登录插件”
次提示：“打开扩展弹窗完成登录后刷新本页”
引导按钮：“去登录”

“去登录”按钮行为：

不直接尝试从内容脚本打开 popup
仅提示用户点击浏览器工具栏中的扩展图标完成登录

未登录时：

不初始化筛选
不初始化排序
不初始化导出
不发起后续业务请求

12.2 已登录态

保持当前市场增强行为不变。

12.3 登录失效态

如果内容脚本运行过程中发现 background 返回未登录或 token 不可用：

立即切回禁用态
提示“登录已失效，请重新登录”

13. 错误处理设计

至少覆盖以下错误：

Logto 配置缺失
登录取消
登录回调失败
token 获取失败
popup 无法读取 background 状态
内容脚本无法获取登录态

设计要求：

popup 中展示用户可理解的错误摘要
background 中保留标准化错误结构
内容脚本遇到认证错误时优先进入禁用态，而不是继续执行业务逻辑

14. TDD 实施要求

实现必须采用 TDD，遵循：

先写失败测试
明确验证测试因缺失功能而失败
再写最小实现让测试通过
最后做必要重构

不允许先写生产代码再补测试。

15. 测试分层建议

15.1 单元测试：消息协议与状态结构

建议文件：

tests/auth-messages.test.ts
tests/auth-state-store.test.ts

覆盖点：

消息类型收发正确
状态序列化结构稳定
配置缺失时能返回明确错误

15.2 单元测试：background 认证协调器

建议文件：

tests/background-auth-controller.test.ts

覆盖点：

signIn 调用认证入口
signOut 清理会话
getAuthState 返回认证摘要
getAccessToken 在未登录或配置无效时失败明确

15.3 单元测试：popup UI

建议文件：

tests/popup-entry.test.ts

覆盖点：

未登录显示登录按钮
已登录显示用户信息和退出按钮
开发模式显示调试区
错误态显示错误摘要

15.4 集成测试：内容脚本门控

建议文件：

tests/market-auth-gating.test.ts

覆盖点：

未登录时市场页工具栏进入禁用态
已登录后才初始化现有筛选、排序、导出
运行中登录失效时切回禁用态

16. 验收标准

扩展加载后存在可用的 popup
未登录时 popup 显示登录入口
登录成功后 popup 显示基础用户信息
开发模式下 popup 能显示认证调试信息
未登录时市场页插件整体禁用
登录后刷新市场页，现有插件能力恢复
登出后刷新市场页，插件重新禁用
配置缺失时，popup / background / content 都能给出明确错误，而不是静默失败

17. 后续实现顺序建议

建议实施顺序：

补 manifest 与构建入口，先让 popup 可以独立加载
写 auth-messages 与 auth-config 的失败测试
写 background auth controller 的失败测试并落最小实现
写 popup 状态渲染测试并接上 background
写内容脚本门控测试，再把市场页逻辑接入认证态
最后补开发调试面板

18. 当前仍保留为占位的实施参数

这些值在真正开始编码前仍需由你提供：

Logto tenant endpoint
Logto Chrome extension appId
Global API resource 标识
是否存在额外自定义 scopes
调试面板是否区分开发包与生产包

在这些真实值到位前，可以先完成目录搭建、消息协议、状态门控和测试骨架。

12 KiB Raw Blame History Unescape Escape

Logto 登录集成设计

1. 背景

2. 已确认的产品决策

3. 官方文档约束

4. 目标与非目标

4.1 目标

4.2 非目标

5. 推荐架构

5.1 模块边界

src/background/auth/*

src/popup/*

src/content/*

src/shared/auth-messages.ts

5.2 为什么这样分层

6. 推荐目录结构

7. 配置设计

8. Manifest 变更要求

9. 认证与会话数据流

9.1 登录流程

9.2 内容脚本门控流程

9.3 登出流程

9.4 token 策略

10. 消息协议建议

11. Popup 交互设计

11.1 未登录态

11.2 已登录态

11.3 开发调试态

12. 内容脚本权限门控设计

12.1 未登录态

12.2 已登录态

12.3 登录失效态

13. 错误处理设计

14. TDD 实施要求

15. 测试分层建议

15.1 单元测试：消息协议与状态结构

15.2 单元测试：background 认证协调器

15.3 单元测试：popup UI

15.4 集成测试：内容脚本门控

16. 验收标准

17. 后续实现顺序建议

18. 当前仍保留为占位的实施参数

12 KiB

Raw Blame History

`src/background/auth/*`

`src/popup/*`

`src/content/*`

`src/shared/auth-messages.ts`