Merge branch 'goplus:dev' into enhance-stageviewer

docs/architecture/01_architecture.md

@@ -1,36 +1,80 @@
 # STEM Education Architecture
 
-## Architecture Overview
+## **Architecture Overview**
 
 STEM EDU is a comprehensive online platform dedicated to enhancing children's programming education through interactive and engaging tools. The architecture encompasses a variety of modules, each designed to contribute to a holistic educational experience. These modules integrate to form a cohesive system that facilitates the creation, modification, and deployment of programming projects within an educational context.
 
-## Module Boundaries
+## **Module Boundaries**
 
-- **Asset List**: Handles the display and management of assets (Sprites, Backdrops, Sounds), allowing for addition and deletion, as well as importing assets from local storage.
-- **Asset Library**: Serves as the repository for assets, from which users can import assets into their projects.
-- **Sprite PropEdit**: Enables editing of SPX sprite properties, allowing for customization and configuration.
-- **Stage Editor**: A visual editing tool for real-time modification and rendering of sprites within a stage-like environment.
-- **Code Editor**: Provides an environment for writing and editing SPX code, with syntax highlighting and error detection.
-- **Code Toolbox**: Offers a collection of code snippets and shortcuts for quick insertion and manipulation of SPX code.
-- **FileManage**: Manages project files, allowing for organization, import, and export of project elements.
-- **Account**: Manages user authentication, including login and logout functionalities.
-- **Sounds Edit**: Facilitates the editing of sound assets, providing tools for audio manipulation.
-- **Project Runner**: Utilizes WebAssembly (WASM) to compile SPX projects, enabling online execution and testing of student code.
-- **I/O**: Manages input/output operations for projects, including loading, saving, and exporting project data.
-- **Global**: Implements internationalization features for language support, catering to a global user base.
+1. **Asset List:**
 
-## Module Interaction
+   - Description:  Handles the display and management of assets (Sprites, Backdrops, Sounds), allowing for addition and deletion, as well as importing assets from local storage.
+   - Interfaces: Input type and show, output handleAssetAddition function with  params(name: string, file: File[])
+   - Behavior: User can interact with the Asset List, they can add assets from local or Asset Library into project, and also delete it.
+2. **Asset Library**:
+
+   - Description:  Serves as the repository for assets, from which users can import assets into their projects.
+   - Interfaces: Input type and show, output handleAssetAddition function with  params(name: string, file: File[])
+   - Behavior: When a user interacts with the Asset Library, they can add selected assets to their respective asset lists.
+3. **Stage Viewer**:
+
+   - Description: render sprites  and backdrop  of  different spx project，Mainly include sprite's location,size,heading and soon.
+   - Interfaces: input size of container, size of stage in spx, sprites and backdrop, output onSpritesDragEnd function with params(targets: SpriteDragEndTarget[])
+   - Behavior: When in use, users can view backgrounds and sprites in the spx project, and drag sprites
+4. **Code Editor**:
+
+   - Description: Provide an editor for writing and editing SPX code, with syntax highlighting, error detection, formatting, and other features; Provides a toolbox that allows users to easily insert code blocks.
+   - Interfaces: Inputs _modelValue,height,width and editorOptions, outputs __change function with params(code:string),insertSnippet,format,snippets_
+   - Behavior: When users interact with the editor, they can edit the project's code
+5. **Project Management**:
+
+   - Description: Managing projects, allowing the usage of the project instance, and methods for project.
+   - Interfaces: Export project instances, getProjects, load, save, download, etc. methods.
+   - Behavior: When the user gets a project instance, he can display and change the contents of the project to the UI level.
+6. **Sounds Edit**: 
+
+   - Description: Allows users to perform editing operations on audio files, with the capability to save the edits.
+   - Interfaces: Inputs a list of audio files.
+   - Behavior: When in use, users can carry out editing actions on audio files.
+7. **Project Runner**:
+
+   - Description: Online compilation of spx projects using wasm
+   - Interfaces: None
+   - Behavior: The use of indexedDB to achieve the spx project file reading, the use of iframe to achieve the project online running
+8. **Backend**: 
+
+   - Description:  It is used to manage projects and asset files.
+   - Interfaces: Add, delete, modify, search for project and asset files, search for resource files, and format code.
+   - Behavior: When users interact with project files and resource files, they can upload, modify, search, and format code when editing.
+
+## **Module Interaction**
 
 Each module within the STEM EDU architecture is designed to interact seamlessly with one another, establishing a network of functionality that supports the platform's educational objectives.
 
-- **Asset List and Asset Library**: The Asset List module communicates with the Asset Library to retrieve and display assets, while also handling the addition of new assets imported by the user.
-- **Stage Editor and Sprite PropEdit**: The Stage Editor collaborates with Sprite PropEdit to reflect changes in sprite properties within the visual stage.
-- **Code Editor and Code Toolbox**: The Code Editor module utilizes the Code Toolbox to enhance the code writing experience with easily accessible coding constructs.
-- **FileManage and I/O**: FileManage works closely with the I/O module to handle file operations, ensuring that project data is accurately loaded, saved, and exported.
-- **Account and Global**: The Account module integrates with Global to provide a localized authentication experience for users from different linguistic backgrounds.
+- **Asset List & Asset Library:** The Asset List (comprising BackdropList.vue and SpriteList.vue) interacts with the Asset Library (LibraryModal.vue) to handle the addition, deletion, and importing of assets. When users choose assets from the Asset Library, these assets are inserted into the Asset List and become part of the project.
+- **Stage Viewer & Project Management:** The Stage Viewer module displays the visual elements of the SPX project, such as sprites and backdrops. It is closely linked with Project Management, such that any changes made in the project (like sprite position or backdrop selection) are immediately reflected within the Stage Viewer, providing real-time feedback as users adjust different aspects of their project.
+- **Code Editor, Sounds Editor, & Project Runner:** These three modules represent the creative triad of the system. The Code Editor allows users to write and modify SPX code, which is then used by the Project Runner to compile and run the project using WebAssembly (wasm). Both the code and sound modifications are managed and saved via the Project Management module.
+- **Project Management & Backend:** The Project Management module serves as the bridge between the user interface and the backend. It manages project instances, including the import, save, and publish functionalities. When users save or publish their projects, these actions are processed through the backend, which handles file storage, authentication, and other cloud-based operations.
+- **User Interaction with Account & Auth:** Users must log in to access cloud-based functionalities like importing, saving, and publishing projects. The Account module ensures that user credentials are securely managed, while the Auth interface within the backend validates these credentials, allowing users to interact with their projects and assets.
+
+## **Architecture Design**
+
+The interaction of each module is as follows:
+
+- Users can import projects, save them in Project Manage, and display them on the page.
+
+- Users can modify the code in the Code Editor module, modify the project's sound in the Sounds Editor, compile the spx project online using wasm in the Project Runner, and view the project's running effects in the Stage Viewer. Resources can be inserted from the Asset Library into the Asset List. These changes are saved through the Project Manage module, which also saves the project to the backend and publishes the project when necessary.
+
+- Users need to log in to perform cloud-based functions such as importing projects, saving projects, and publishing projects.
+
+<img src="../static/architectureImg.png" width=400>
 
-## Module List
+## **Module List**
 
-updating...
-- assetList
-- assetLibrary
+- AssetList
+- AssetLibrary
+- StageViewer
+- CodeEditor
+- ProjectManagement
+- SoundsEditor
+- Backend

docs/architecture/03_assetLibrary.md → docs/architecture/02_assetLibrary.md

@@ -29,7 +29,7 @@ Emits a function `handleAssetAddition(name: string, file: File[])` with the asse
 
 ## User Stories
 
-When a user interacts with the Asset Library, they can add selected assets to their respective store lists. Depending on the asset type, different actions are performed to update the state in the store.
+When a user interacts with the Asset Library, they can add selected assets to their respective store lists. 
 
 ## Example Usage
 
@@ -51,13 +51,17 @@ import Sprite from "@/class/sprite";
 const spriteStore = useSpriteStore();
 const backdropStore = useBackdropStore();
 
-const handleAssetAddition = (name: string, file?: File[]) => {
-    //if （type === 'sprite'）
-    const sprite = new Sprite(name, file);
+const handleAssetAddition = async (name: string, address: string) => {
+  if (props.type === 'sprite') {
+    const file = await urlToFile(address, name);
+    const sprite = new Sprite(name, [file]);
     spriteStore.addItem(sprite);
-    //if (type === 'backdrop')
-    backdropStore.backdrop.removeFile(file);
-    
+    message.success(`add ${name} successfully!`)
+  } else if (props.type === 'backdrop') {
+    const file = await urlToFile(address, name);
+    backdropStore.backdrop.addFile(file);
+    message.success(`add ${name} successfully!`)
+  }
 };
 </script>
 ```

docs/architecture/03_assetList.md

@@ -0,0 +1,39 @@
+# Asset List Module
+
+## Module Purpose
+
+The Asset List module is responsible for managing the display of assets, including uploading new assets, deleting existing ones, and presenting a list of assets. It includes separate components for handling sprites (`SpriteList.vue`) and backdrops (`BackdropList.vue`).
+
+## Module Scope
+
+The module provides the ability to upload and delete assets, as well as to display a list of current assets. It takes specific information about sprites and backdrops as input and provides functions for deleting them as output.
+
+## Module Structure
+
+Components:
+
+- `BackdropList.vue` - Manages the display and deletion of backdrop.
+- `SpriteList.vue` - Manages the display and deletion of sprite.
+
+## Module Interface
+
+### Inputs
+
+None.
+
+### Outputs
+
+None.
+
+## User Stories
+
+Users can interact with the asset list components to upload new assets, remove existing ones, and view the list of assets. When an asset is selected for deletion, the corresponding deletion function is triggered, which updates the state in the respective store.
+
+## Example Usage
+
+```vue
+<template>
+	<BackdropList/>
+	<SpriteList/>
+</template>
+```

docs/architecture/project-manage.md

@@ -16,10 +16,6 @@ class:
 
 - `Project` - Project class, used to create project instance and organise project.
 
-store:
-
-- `ProjectStore` - Project management, for sharing project status and providing functions.
-
 ## Module Interface
 
 Project Management.
@@ -41,7 +37,7 @@ interface ProjectSummary {
     source: ProjectSource
 }
 
-interface ProjectData {
+interface ProjectDetail {
     // Sprite list
     sprite: SpriteList
     // Sound list
@@ -51,33 +47,27 @@ interface ProjectData {
     // Entry code of the project
     entryCode: string
     // Documents not identified
-    unidentifiedFile: rawDir
+    unidentifiedFile: RawDir
 }
 
-class Project implements ProjectSummary, ProjectData {
+class Project implements ProjectSummary, ProjectDetail {
+    constructor();
     // Save project to Cloud.
     save(): Promise<void>;
+    // Load project.
+    load(id: string, source: ProjectSource = ProjectSource.cloud): Promise<void>;
+    // Load project from zip file.
+    loadFromZip(file: File, title?: string);
     // Download project to computer.
     download(): Promise<void>;
-}
-
-type ProjectStoreExports = {
-    // Instance of project.
-    project: Project
     // Get local and cloud projects.
-    getProjects(): Promise<ProjectSummary[]>
-    // Load the item with the id.
-    load(id: string, source: ProjectSource = ProjectSource.local): Promise<void>;
-    // Load zip file.
-    loadFromZip(file: File): Promise<void>;
+    static getProjects(): Promise<ProjectSummary[]>
 }
-
-function useProjectStore(): ProjectStoreExports;
 ```
 
 ## User Stories
 
-Users can access project-related information through project management. If you need to modify the contents of a project, you can do so directly, and all changes will be responsively updated to other uses of the project. Users can use the `getProjects` function to get a list of all cloud or local projects and then load this project via `loadProject`. If the user already has a project zip locally, it can load this zip into the project using `loadFromZip`. If the user needs to save the project to the cloud, just call the `save` function, and to save it locally call the `download` function.
+Users can access project-related information through project management. If you need to modify the contents of a project, you can do so directly, and all changes will be responsively updated to other uses of the project. Users can use the `getProjects` function to get a list of all cloud or local projects and then load this project via `load`. If the user needs to save the project to the cloud, just call the `save` function, and to save it locally call the `download` function.
 
 ## Example Usage
 
@@ -89,23 +79,21 @@ Here is the basic usage of Project Management.
 </template>
 
 <script setup lang="ts">
-import { useProjectStore } from "@/store/modules/project";
+import { Project } from "@/class/project";
     
-const projectStore = useProjectStore();
+const project = new Project();
 
 const loadFile = async (e: any) => {
-    await projectStore.loadFromZip(e.target.files[0]);  // load project by zip file
+    await project.loadFromZip(e.target.files[0]);  // load project by zip file
 }
 
-const loadProjects = async () => {
-    const projects = await projectStore.getProjects();  // [ProjectSummary{}, ProjectSummary{}]
-    const id = projects[0].id;
-    const source = projects[0].source;
-    await projectStore.load(id, source);  // load the first project
+const loadProject = async () => {
+    const projects = await Project.getProjects();  // [ProjectSummary{}, ProjectSummary{}]
+    await project.load(projects[0].id, projects[0].source);  // load the first project
 }
 
 const download = () => {
-    projectStore.project.value.download();  // save project to computer
+    project.download();  // save project to computer
 }
 </script>
-```
+```

spx-gui/.eslintrc.cjs

@@ -16,4 +16,4 @@ module.exports = {
     'no-useless-escape': 'warn',
     '@typescript-eslint/naming-convention': 'warn'
   }
-}
+}

spx-gui/.gitignore

@@ -39,3 +39,5 @@ tsconfig.tsbuildinfo
 !.yarn/releases
 !.yarn/sdks
 !.yarn/versions
+
+.env.local

spx-gui/README.md

@@ -228,4 +228,4 @@ export const initI18n = async (app: App) => {
 
 ```html
 <div class="sounds-hint">{{ $t('sounds.hint') }}</div>
-```
+```

spx-gui/env.d.ts

@@ -1 +1,14 @@
+/* eslint-disable @typescript-eslint/naming-convention */
 /// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  readonly VITE_API_BASE: string
+  readonly VITE_CASDOOR_ENDPOINT: string
+  readonly VITE_CASDOOR_CLIENT_ID: string
+  readonly VITE_CASDOOR_ORGANIZATION_NAME: string
+  readonly VITE_CASDOOR_APP_NAME: string
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}