# 插件市场 Server 后端设计稿

本文档面向平台后端与基础设施团队，定义中心服务器的职责边界、对象模型、接口范围、状态流转与安全治理要求。

## 一、定位

中心服务器是插件市场的索引与治理中枢，不是插件包托管服务。

其核心职责是维护可信元数据、版本索引、审核状态和可查询能力，并对外提供统一的搜索与下载决策入口。

## 二、后端目标

1. 建立插件、版本、作者、审核记录的标准对象模型。
2. 提供面向客户端的检索与详情 API。
3. 提供面向 CLI 的注册、发布、同步 API。
4. 提供面向管理端的审核、下架、封禁、统计 API。
5. 维持 GitHub Release 元数据与中心索引的一致性。

## 三、后端不负责的事情

1. 不保存插件包二进制。
2. 不代理所有下载流量。
3. 不代替 GitHub 完成源码协作与版本管理。
4. 不在第一阶段承担复杂内容推荐与评论系统。

## 四、核心对象模型

### 1. Plugin

表示市场中的逻辑插件实体。

建议字段：

1. `plugin_id`
2. `display_name`
3. `summary`
4. `description`
5. `icon_url`
6. `homepage`
7. `repository_url`
8. `license`
9. `categories`
10. `tags`
11. `status`
12. `owner_id`
13. `maintainers`
14. `trust_level`
15. `created_at`
16. `updated_at`

### 2. PluginVersion

表示插件某个可安装版本。

建议字段：

1. `plugin_id`
2. `version`
3. `release_tag`
4. `release_title`
5. `release_url`
6. `asset_name`
7. `asset_download_url`
8. `checksum_sha256`
9. `file_size`
10. `published_at`
11. `is_prerelease`
12. `is_yanked`
13. `plugin_api_version`
14. `min_host_version`
15. `max_host_version`
16. `supported_platforms`

### 3. Author

表示与 GitHub 身份绑定的发布主体。

建议字段：

1. `author_id`
2. `github_user_id`
3. `github_login`
4. `display_name`
5. `avatar_url`
6. `author_type`
7. `verified_at`

### 4. ReviewRecord

表示审核与治理历史。

建议字段：

1. `target_type`
2. `target_id`
3. `action`
4. `status_before`
5. `status_after`
6. `reason`
7. `operator_id`
8. `created_at`

## 五、状态机建议

### 插件状态

1. `draft`
2. `pending_review`
3. `published`
4. `deprecated`
5. `blocked`
6. `archived`

### 版本状态

1. `submitted`
2. `pending_review`
3. `published`
4. `yanked`
5. `blocked`

### 核心原则

1. 首次上架建议进入 `pending_review`。
2. 已发布版本允许转为 `yanked`，但不能物理删除审计记录。
3. `blocked` 状态必须能够阻止新安装与版本推荐。

## 六、API 分层建议

### 1. 公共查询 API

用于客户端和公开页面。

建议包含：

1. 插件搜索。
2. 插件详情。
3. 版本列表。
4. 版本详情。
5. 分类与标签列表。
6. 官方插件与推荐插件列表。

### 2. 作者侧 API

用于 CLI 或作者控制台。

建议包含：

1. 插件注册。
2. 插件信息更新。
3. 新版本提交。
4. 版本重新同步。
5. 版本撤回申请。
6. 审核状态查询。

### 3. 管理侧 API

用于管理后台。

建议包含：

1. 审核通过或拒绝。
2. 插件下架。
3. 版本封禁。
4. 风险标记。
5. 维护者迁移。
6. 审计日志与统计查询。

### 4. 同步与校验 API

建议包含：

1. GitHub 身份验证回调。
2. GitHub webhook 验签与事件接收。
3. Release 状态复核。
4. 仓库归档、删除、转移监测。

## 七、鉴权与权限模型

建议以后端为中心建立最小权限体系。

### 角色

1. 平台管理员。
2. 插件所有者。
3. 插件维护者。
4. 普通用户。

### 核心规则

1. 身份绑定应基于 GitHub 用户 ID，而不是仅使用用户名。
2. 插件归属可绑定个人或 GitHub 组织。
3. 只有拥有写权限的作者或维护者才能提交新版本。
4. 仓库转移所有权后应要求重新验证归属。

## 八、与 GitHub 的同步策略

建议采用“CLI 主动推送为主，GitHub webhook 被动校验为辅”的组合策略。

### 主动推送

由 CLI 在发布完成后立即同步元数据，优点是时效性高、链路清晰。

### 被动校验

由 GitHub webhook 或定时任务校验以下场景：

1. Release 被删除。
2. 仓库被归档或删除。
3. tag 与中心收录版本不一致。
4. 仓库转移所有权。

## 九、兼容性决策逻辑

后端应支持基于以下维度筛选版本：

1. 宿主版本。
2. 插件 API 版本。
3. 平台信息。
4. 是否预发布。
5. 版本是否已撤回或封禁。

客户端默认应得到“最新兼容稳定版”，而不是单纯的最高版本号。

## 十、安全与治理要求

### 供应链安全

1. 强制记录每个资产的 sha256。
2. 客户端安装前必须校验。
3. 中心服务器需保留可扩展字段，为后续签名校验预留空间。

### 平台治理

1. 首次上架建议人工审核。
2. 高风险插件支持紧急封禁。
3. 已知风险插件需要对外展示风险提示。
4. 支持弃用声明与替代插件推荐。

### 审计与追踪

1. 保存插件与版本元数据的变更历史。
2. 保存审核动作与操作者记录。
3. 保存同步失败原因与最近一次成功同步时间。

## 十一、可观测性与运维建议

1. 对 GitHub API 调用增加缓存与限流保护。
2. 对外 API 增加分页、过滤、限流与基础风控。
3. 为同步任务建立告警，例如 Release 丢失、仓库不可达、校验值缺失。
4. 即使只存元数据，也需要数据库备份与恢复机制。

## 十二、MVP 建议

第一版后端建议优先交付以下能力：

1. 插件与版本元数据模型。
2. 面向客户端的搜索与详情 API。
3. 面向 CLI 的注册、版本提交、同步状态 API。
4. 审核、下架、撤回的管理能力。
5. GitHub 身份绑定与最小 webhook 校验。

以下可放入第二阶段：

1. 自动化安全扫描。
2. 下载统计与热度排序优化。
3. 官方插件认证体系增强。
4. 多代码托管平台接入。