[*](docs/gui): fix provider-switch add some comments and docs

docs/source/index.rst

@@ -30,8 +30,7 @@ FeelUOwn 是一个用户友好、可玩性强的播放器
    dev_quickstart
    arch
    api
-   media_assets_management_v1
-   media_assets_management/index_v2
+   media_assets_management/index
    protocol
    glossary
    research

docs/source/media_assets_management/index.rst

@@ -0,0 +1,41 @@
+媒体资源管理
+===================
+
+feeluown 一个设计目标是让用户能够高效使用各个音乐平台的合法资源。
+媒体资源管理定义、规范并统一了各个音乐平台资源的访问接口。
+
+音乐库是媒体资源管理子系统的入口。音乐库部分负责管理 feeluown 的音乐资源，
+包括歌曲、歌手、专辑详情获取，专辑、歌单封面获取等。它主要由几个部分组成：
+音乐对象模型(*Model*)、音乐提供方(*Provider*)、提供方管理(*Library*)。
+
+.. code::
+
+    +---------------------------------------------------------------------------+
+    |  +---------+                                                              |
+    |  | Library |                                                              |
+    |  +---------+                +-------------+                               |
+    |   |                         | song_get    |                               |
+    |   |  +-------------------+  | ...         |                               |
+    |   |--| provider(netease) |--| aritst_get  |-----+                         |
+    |   |  +-------------------+  | search      |     |     +----------------+  |
+    |   |                         | ...         |     |     | BriefSongModel |  |
+    |   |                         +-------------+     |     | ...            |  |
+    |   |                       +-------------+       +-----|                |  |
+    |   |                       | song_get_mv |       |     | SongModel      |  |
+    |   |  +-----------------+  | ...         |       |     | ArtistModel    |  |
+    |   |--| provider(xiami) |--| album_get   |-------+     | ...            |  |
+    |   |  +-----------------+  | search      |             +----------------+  |
+    |   |                       | ...         |                                 |
+    |   |                       +-------------+                                 |
+    |   |--...                                                                  |
+    |                                                                           |
+    +---------------------------------------------------------------------------+
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: 目录
+
+   library
+   provider
+   model

docs/source/media_assets_management/library.rst

@@ -0,0 +1,23 @@
+音乐库
+=====================
+
+.. _library:
+
+音乐库模块管理资源提供方(*Provider*)。音乐库还提供了一些通用接口，简化了对资源提供方的访问。
+
+.. code::
+
+    # 注册一个资源提供方
+    library.register(provider)
+
+    # 获取资源提供方实例
+    provider = library.get(provider.identifier)
+
+    # 列出所有资源提供方
+    library.list()
+
+    # 在音乐库中搜索关键词
+    library.search('linkin park')
+
+.. autoclass:: feeluown.library.Library
+   :members:

docs/source/media_assets_management/model.rst

@@ -0,0 +1,8 @@
+数据模型
+=====================
+
+feeluown 定义了常见音乐资源的数据模型，包括歌曲、歌手、专辑、视频、MV、歌单等。
+这样，上层模块就能以统一的方式访问这些资源。
+
+.. automodule:: feeluown.library.models
+   :members:

docs/source/media_assets_management/provider.rst

@@ -0,0 +1,31 @@
+资源提供方
+=====================
+
+歌曲等音乐资源都来自于某一个提供方。比如，我们认为本地音乐的提供方是本地，
+网易云音乐资源的提供方是网易，等等。对应到程序设计上，每个提供方都对应一个 provider 实例。
+provider 是我们访问具体一个音乐平台资源音乐的入口。
+
+在 feeluown 生态中，每个音乐资源提供方都对应着一个插件，我们现在有 feeluown-local/feeluown-netease
+等许多插件，这些插件在启动时，会注册一个 provider 实例到 feeluown 的音乐库模块上。
+注册完成之后，音乐库和 feeluown 其它模块就能访问到这个提供方的资源
+
+举个栗子，feeluown-local 插件在启动时就创建了一个 *identifier* 为 ``local`` 的 provider 实例，
+并将它注册到音乐库中，这样，当我们访问音乐库资源时，就能访问到本地音乐资源。
+
+详细信息请参考 :doc:`provider`。
+
+定义一个资源提供方
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: feeluown.library.AbstractProvider
+   :members:
+
+.. autoclass:: feeluown.library.Provider
+   :members:
+
+协议
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: feeluown.library.provider_protocol
+   :members:
+

feeluown/gui/components/avatar.py

@@ -82,6 +82,9 @@ def contextMenuEvent(self, e) -> None:
         menu.exec_(e.globalPos())
 
     def on_provider_ui_login_event(self, provider_ui, event):
+        current_pvd_ui = self._app.current_pvd_ui_mgr.get()
+        if current_pvd_ui == provider_ui and event == 2:
+            return
         if event in (1, 2):
             run_afn(self.show_pvd_ui_current_user)
             run_afn(
@@ -90,12 +93,13 @@ def on_provider_ui_login_event(self, provider_ui, event):
             )
 
     def on_pvd_ui_selected(self, pvd_ui):
-        self._app.current_pvd_ui_mgr.set(pvd_ui)
         if isinstance(pvd_ui, UISupportsLoginEvent):
             pvd_ui.login_event.connect(self.on_provider_ui_login_event)
         if isinstance(pvd_ui, UISupportsLoginOrGoHome):
             pvd_ui.login_or_go_home()
-        run_afn(self.show_pvd_ui_current_user)
+        # Set current provider ui at the very last.
+        # Must not set it before handling login event.
+        self._app.current_pvd_ui_mgr.set(pvd_ui)
 
     def on_provider_selected(self, provider: ProviderUiItem):
         self._app.current_pvd_ui_mgr.set_item(provider)

feeluown/gui/provider_ui.py

@@ -23,14 +23,24 @@ class NavBtn:
 
 @runtime_checkable
 class UISupportsLoginOrGoHome(Protocol):
-
     @abstractmethod
     def login_or_go_home(self):
-        ...
+        """This method is called when the avatar is clicked.
+
+        Typically, ProviderUI can implement this method as follows:
+        - When no user is logged in, ProviderUI MAY show a login dialog.
+        - When a user is logged in, ProviderUI MAY show the homepage.
+          At the same time, ProviderUI MAY emit a login success event.
+        """
 
 
 @runtime_checkable
 class UISupportsLoginEvent(Protocol):
+    """
+    When the user is logged in, ProviderUI MAY emit a login success event.
+    This allows FeelUOwn to perform certain actions based on this event,
+    for example, fetching and show the user's playlist.
+    """
 
     @property
     @abstractmethod