diff --git a/docs/design/appcenter.md b/docs/design/appcenter.md new file mode 100644 index 0000000000000000000000000000000000000000..c18e8d3f43a6bde2585dc9a4f7a1d600d42c7d10 --- /dev/null +++ b/docs/design/appcenter.md @@ -0,0 +1,100 @@ +# openEuler Copilot Framework AppCenter 设计文档 + +## 1. 整体设计 + +AppCenter 是 openEuler Copilot Framework 的应用中心模块, 主要提供以下功能: + +- 应用的 CRUD 操作 (创建、读取、更新、删除) +- 应用收藏管理 +- 最近使用应用记录 +- 应用搜索与过滤 +- 应用发布管理 + +### 1.1 核心组件 + +- AppCenter Manager: 应用中心管理器, 提供应用相关的核心业务逻辑 +- AppCenter Router: 提供 HTTP API 接口 +- MongoDB: 存储应用数据 + +## 2. 数据结构 + +### 2.1 App 数据模型 + +![App 数据模型](./uml/appcenter/DB%20AppPool%20数据模型.png) + +### 2.2 User 数据模型 + +![User 数据模型](./uml/appcenter/DB%20User%20数据模型.png) + +## 3. 接口设计 + +### 3.1 HTTP API + +| 路径 | 方法 | 描述 | +|------|------|------| +| `/api/app` | `GET` | 获取应用列表 | +| `/api/app` | `POST` | 创建/更新应用 | +| `/api/app/recent` | `GET` | 获取最近使用应用 | +| `/api/app/{appId}` | `GET` | 获取应用详情 | +| `/api/app/{appId}` | `DELETE` | 删除应用 | +| `/api/app/{appId}` | `POST` | 发布应用 | +| `/api/app/{appId}` | `PUT` | 修改应用收藏状态 | + +## 4. 核心流程 + +### 4.1 创建应用流程 + +![创建应用流程](./uml/appcenter/API%20创建应用.png) + +### 4.2 应用搜索流程 + +![应用搜索流程](./uml/appcenter/API%20搜索应用.png) + +### 4.3 获取最近使用的应用流程 + +![获取最近使用的应用流程](./uml/appcenter/API%20获取最近使用的应用.png) + +### 4.4 获取应用详情流程 + +![获取应用详情流程](./uml/appcenter/API%20获取应用详情.png) + +### 4.5 删除应用流程 + +![删除应用流程](./uml/appcenter/API%20删除应用.png) + +### 4.6 发布应用流程 + +![发布应用流程](./uml/appcenter/API%20发布应用.png) + +### 4.7 更改应用收藏状态流程 + +![更改应用收藏状态流程](./uml/appcenter/API%20收藏应用.png) + +## 5. 主要功能实现 + +### 5.1 应用搜索与过滤 + +支持以下搜索类型: + +- 全文搜索 (名称、描述、作者) +- 按名称搜索 +- 按描述搜索 +- 按作者搜索 + +### 5.2 应用收藏管理 + +- 支持收藏/取消收藏应用 +- 记录用户收藏列表 +- 支持获取收藏应用列表 + +### 5.3 最近使用记录 + +- 记录应用使用次数和最后使用时间 +- 支持获取最近使用应用列表 +- 按最后使用时间排序 + +## 6. 安全性设计 + +- 接口鉴权: 依赖 `verify_user` 中间件进行用户认证 +- CSRF 防护: 使用 `verify_csrf_token` 中间件 +- 权限控制: 应用删除、发布等操作需验证用户身份 diff --git "a/docs/design/uml/appcenter/API \345\210\233\345\273\272\345\272\224\347\224\250.png" "b/docs/design/uml/appcenter/API \345\210\233\345\273\272\345\272\224\347\224\250.png" new file mode 100644 index 0000000000000000000000000000000000000000..0f2bc13dd63a57ffc118b2dc5c894bc080303202 Binary files /dev/null and "b/docs/design/uml/appcenter/API \345\210\233\345\273\272\345\272\224\347\224\250.png" differ diff --git "a/docs/design/uml/appcenter/API \345\210\240\351\231\244\345\272\224\347\224\250.png" "b/docs/design/uml/appcenter/API \345\210\240\351\231\244\345\272\224\347\224\250.png" new file mode 100644 index 0000000000000000000000000000000000000000..a813a87b989b3bec2f2ebcdc94d118c691506ae4 Binary files /dev/null and "b/docs/design/uml/appcenter/API \345\210\240\351\231\244\345\272\224\347\224\250.png" differ diff --git "a/docs/design/uml/appcenter/API \345\217\221\345\270\203\345\272\224\347\224\250.png" "b/docs/design/uml/appcenter/API \345\217\221\345\270\203\345\272\224\347\224\250.png" new file mode 100644 index 0000000000000000000000000000000000000000..f59eec536921dda7b6509db887d0855bc0eb67ed Binary files /dev/null and "b/docs/design/uml/appcenter/API \345\217\221\345\270\203\345\272\224\347\224\250.png" differ diff --git "a/docs/design/uml/appcenter/API \346\220\234\347\264\242\345\272\224\347\224\250.png" "b/docs/design/uml/appcenter/API \346\220\234\347\264\242\345\272\224\347\224\250.png" new file mode 100644 index 0000000000000000000000000000000000000000..f69ddbdece13fac13547f68bf224b522390b2eea Binary files /dev/null and "b/docs/design/uml/appcenter/API \346\220\234\347\264\242\345\272\224\347\224\250.png" differ diff --git "a/docs/design/uml/appcenter/API \346\224\266\350\227\217\345\272\224\347\224\250.png" "b/docs/design/uml/appcenter/API \346\224\266\350\227\217\345\272\224\347\224\250.png" new file mode 100644 index 0000000000000000000000000000000000000000..143d0f43d8ee8e95e9a3f7d89c4e87468372aee5 Binary files /dev/null and "b/docs/design/uml/appcenter/API \346\224\266\350\227\217\345\272\224\347\224\250.png" differ diff --git "a/docs/design/uml/appcenter/API \350\216\267\345\217\226\345\272\224\347\224\250\350\257\246\346\203\205.png" "b/docs/design/uml/appcenter/API \350\216\267\345\217\226\345\272\224\347\224\250\350\257\246\346\203\205.png" new file mode 100644 index 0000000000000000000000000000000000000000..f6c9ab68c1d3fa4493ec1aea1ea6eaf05a655e1a Binary files /dev/null and "b/docs/design/uml/appcenter/API \350\216\267\345\217\226\345\272\224\347\224\250\350\257\246\346\203\205.png" differ diff --git "a/docs/design/uml/appcenter/API \350\216\267\345\217\226\346\234\200\350\277\221\344\275\277\347\224\250\347\232\204\345\272\224\347\224\250.png" "b/docs/design/uml/appcenter/API \350\216\267\345\217\226\346\234\200\350\277\221\344\275\277\347\224\250\347\232\204\345\272\224\347\224\250.png" new file mode 100644 index 0000000000000000000000000000000000000000..9bb87e59b66bedc4aa03cde4ccb83d65143f3a1f Binary files /dev/null and "b/docs/design/uml/appcenter/API \350\216\267\345\217\226\346\234\200\350\277\221\344\275\277\347\224\250\347\232\204\345\272\224\347\224\250.png" differ diff --git "a/docs/design/uml/appcenter/DB AppPool \346\225\260\346\215\256\346\250\241\345\236\213.png" "b/docs/design/uml/appcenter/DB AppPool \346\225\260\346\215\256\346\250\241\345\236\213.png" new file mode 100644 index 0000000000000000000000000000000000000000..02a4abcc583c4068bb03089bfc6113e153671115 Binary files /dev/null and "b/docs/design/uml/appcenter/DB AppPool \346\225\260\346\215\256\346\250\241\345\236\213.png" differ diff --git "a/docs/design/uml/appcenter/DB User \346\225\260\346\215\256\346\250\241\345\236\213.png" "b/docs/design/uml/appcenter/DB User \346\225\260\346\215\256\346\250\241\345\236\213.png" new file mode 100644 index 0000000000000000000000000000000000000000..ee3000ed1734cf56c98805ebe3f93c0cdb018a49 Binary files /dev/null and "b/docs/design/uml/appcenter/DB User \346\225\260\346\215\256\346\250\241\345\236\213.png" differ diff --git a/docs/design/uml/appcenter/api_create_app.puml b/docs/design/uml/appcenter/api_create_app.puml new file mode 100644 index 0000000000000000000000000000000000000000..1d973a2c80fff7115c5095a5de57735df89ebc6b --- /dev/null +++ b/docs/design/uml/appcenter/api_create_app.puml @@ -0,0 +1,13 @@ +@startuml API 创建应用 +actor User +participant "AppCenter Router" as Router +participant "AppCenter Manager" as Manager +database MongoDB + +User -> Router: POST /api/app +Router -> Manager: create_app() +Manager -> MongoDB: insert app data +MongoDB --> Manager: return app_id +Manager --> Router: return app_id +Router --> User: return success response +@enduml \ No newline at end of file diff --git a/docs/design/uml/appcenter/api_delete_app.puml b/docs/design/uml/appcenter/api_delete_app.puml new file mode 100644 index 0000000000000000000000000000000000000000..2f5ef442fbc2ddd884305d29acdc2d165bb7e20b --- /dev/null +++ b/docs/design/uml/appcenter/api_delete_app.puml @@ -0,0 +1,21 @@ +@startuml API 删除应用 +actor User +participant "AppCenter Router" as Router +participant "AppCenter Manager" as Manager +participant "FlowManager" as FlowManager +database MongoDB + +User -> Router: DELETE /api/app/{appId} +Router -> Manager: fetch_app_data_by_id() +MongoDB --> Manager: return app data +Router -> Router: verify author +Router -> FlowManager: delete_flow_by_app_and_flow_id() +FlowManager -> MongoDB: delete flows +Router -> Manager: delete_app() +Manager -> MongoDB: start transaction +Manager -> MongoDB: delete app +Manager -> MongoDB: update user app_usage +MongoDB -> MongoDB: commit transaction +Manager --> Router: return result +Router --> User: return response +@enduml \ No newline at end of file diff --git a/docs/design/uml/appcenter/api_fav_app.puml b/docs/design/uml/appcenter/api_fav_app.puml new file mode 100644 index 0000000000000000000000000000000000000000..f526c6821a0b42d3c69271f79a005a645b7a3be6 --- /dev/null +++ b/docs/design/uml/appcenter/api_fav_app.puml @@ -0,0 +1,15 @@ +@startuml API 收藏应用 +actor User +participant "AppCenter Router" as Router +participant "AppCenter Manager" as Manager +database MongoDB + +User -> Router: PUT /api/app/{appId} +Router -> Manager: modify_favorite_app() +Manager -> MongoDB: find app +MongoDB --> Manager: return app data +Manager -> Manager: verify favorite status +Manager -> MongoDB: update favorites array +Manager --> Router: return ModFavAppFlag +Router --> User: return response +@enduml \ No newline at end of file diff --git a/docs/design/uml/appcenter/api_fetch_app_data.puml b/docs/design/uml/appcenter/api_fetch_app_data.puml new file mode 100644 index 0000000000000000000000000000000000000000..5169aaeafff11f0b2b4eb48b59ed09106e86a7e8 --- /dev/null +++ b/docs/design/uml/appcenter/api_fetch_app_data.puml @@ -0,0 +1,14 @@ +@startuml API 获取应用详情 +actor User +participant "AppCenter Router" as Router +participant "AppCenter Manager" as Manager +database MongoDB + +User -> Router: GET /api/app/{appId} +Router -> Manager: fetch_app_data_by_id() +Manager -> MongoDB: find_one app +MongoDB --> Manager: return app data +Manager -> Manager: build app property +Manager --> Router: return app details +Router --> User: return response +@enduml \ No newline at end of file diff --git a/docs/design/uml/appcenter/api_fetch_recent_app.puml b/docs/design/uml/appcenter/api_fetch_recent_app.puml new file mode 100644 index 0000000000000000000000000000000000000000..da7a0628648f24ebf29b42fce895bd3e4120c227 --- /dev/null +++ b/docs/design/uml/appcenter/api_fetch_recent_app.puml @@ -0,0 +1,16 @@ +@startuml API 获取最近使用的应用 +actor User +participant "AppCenter Router" as Router +participant "AppCenter Manager" as Manager +database MongoDB + +User -> Router: GET /api/app/recent +Router -> Manager: get_recently_used_apps() +Manager -> MongoDB: find user data +MongoDB --> Manager: return user data +Manager -> MongoDB: find app data +MongoDB --> Manager: return app data +Manager -> Manager: sort by last_used time +Manager --> Router: return recent apps +Router --> User: return response +@enduml \ No newline at end of file diff --git a/docs/design/uml/appcenter/api_publish_app.puml b/docs/design/uml/appcenter/api_publish_app.puml new file mode 100644 index 0000000000000000000000000000000000000000..6f2dace22de4a624a9f678353d4878e460972635 --- /dev/null +++ b/docs/design/uml/appcenter/api_publish_app.puml @@ -0,0 +1,15 @@ +@startuml API 发布应用 +actor User +participant "AppCenter Router" as Router +participant "AppCenter Manager" as Manager +database MongoDB + +User -> Router: POST /api/app/{appId} +Router -> Manager: fetch_app_data_by_id() +MongoDB --> Manager: return app data +Router -> Router: verify author +Router -> Manager: publish_app() +Manager -> MongoDB: update published status +Manager --> Router: return result +Router --> User: return response +@enduml \ No newline at end of file diff --git a/docs/design/uml/appcenter/api_serach_app.puml b/docs/design/uml/appcenter/api_serach_app.puml new file mode 100644 index 0000000000000000000000000000000000000000..2e6f3e0f0676cbb2ce2bea5f5010e2fb78958e8d --- /dev/null +++ b/docs/design/uml/appcenter/api_serach_app.puml @@ -0,0 +1,15 @@ +@startuml API 搜索应用 +actor User +participant "AppCenter Router" as Router +participant "AppCenter Manager" as Manager +database MongoDB + +User -> Router: GET /api/app with filters +Router -> Manager: fetch_all_apps() +Manager -> Manager: build search filters +Manager -> MongoDB: find with filters +MongoDB --> Manager: return apps +Manager -> Manager: build response items +Manager --> Router: return app list +Router --> User: return apps response +@enduml \ No newline at end of file diff --git a/docs/design/uml/appcenter/db_app_pool.puml b/docs/design/uml/appcenter/db_app_pool.puml new file mode 100644 index 0000000000000000000000000000000000000000..9000bfbcc40cf8e936005a0f28ac1b6c2180cad8 --- /dev/null +++ b/docs/design/uml/appcenter/db_app_pool.puml @@ -0,0 +1,47 @@ +@startuml DB AppPool 数据模型 +class AppPool { + - id: str + - name: str + - description: str + - author: str + - icon: str + - links: List[str] + - first_questions: List[str] + - history_len: int + - permission: Permission + - flows: List[Flow] + - favorites: List[str] + - published: bool + - created_at: datetime +} + +class Permission { + - type: str + - users: List[str] +} + +class AppData { + - app_id: str + - name: str + - description: str + - icon: str + - links: List[str] + - first_questions: List[str] + - history_len: int + - permission: Permission + - workflows: List[str] +} + +class AppCenterCardItem { + - appId: str + - icon: str + - name: str + - description: str + - author: str + - favorited: bool + - published: bool +} + +AppPool --> Permission +AppData --> Permission +@enduml \ No newline at end of file diff --git a/docs/design/uml/appcenter/db_user.puml b/docs/design/uml/appcenter/db_user.puml new file mode 100644 index 0000000000000000000000000000000000000000..f2e5b15881f66175846a2f3fb40ecd2090319e9e --- /dev/null +++ b/docs/design/uml/appcenter/db_user.puml @@ -0,0 +1,27 @@ +@startuml DB User 数据模型 +class User { + _id: str + last_login: float + is_active: bool + is_whitelisted: bool + credit: int + api_key: Optional[str] + kb_id: Optional[str] + conversations: List[str] + domains: List[UserDomainData] + app_usage: Dict[str, AppUsageData] +} + +class AppUsageData { + count: int + last_used: float +} + +class UserDomainData { + name: str + count: int +} + +User --> AppUsageData +User --> UserDomainData +@enduml \ No newline at end of file