Merge pull request #86 from palp1tate/patch-1

Create load-save.md

docs/load-save.md

@@ -0,0 +1,96 @@
+### Background
+
+#### Project Background
+
+In current software development practices, project management and file version control are core components. Projects involve a variety of file types, including code, images, audio, etc., requiring effective management of these files to support the development and maintenance of the project.
+
+#### Requirement Background
+
+Users need a convenient and efficient way to create, edit, save, and manage project files. Especially during file editing, the ability to perform incremental updates rather than just full updates is needed to improve efficiency and save resources. Additionally, the uniqueness and non-redundancy of project files need to be ensured.
+
+### Solution Overview
+
+**Project files are no longer stored in object storage on a project-by-project basis, but rather on a file-by-file basis**.
+
+#### Roles and Their Responsibilities
+
+- **Frontend Role**: Responsible for the design and implementation of the user interface, including the creation, editing, and display of project files. The frontend also needs to handle communication with the backend and interact directly with the object storage service to upload and delete files.
+- **Backend Role**: Responsible for handling requests from the frontend, including providing complete project information and updating project information. Project information mainly includes the project's file structure, version number, `id`, `uid`, update time, etc. The backend does not directly deal with object storage.
+- **Object Storage Service**: Provides storage capabilities for project files. Each file is accessed through a unique URL generated by a hash algorithm, ensuring the file's uniqueness and non-redundancy.
+
+#### How It Works
+
+1. **Project Loading**: The frontend makes an HTTP request to the backend, which retrieves the complete project information from the database and returns it to the frontend. The frontend parses and displays the project content.
+
+ An example of the file structure is as follows (using MySQL database, which cannot store arrays, so JSON is serialized into a string for easy storage in the database):
+
+ ```json
+ {
+ "index.json": "https://xxx.com/d2a6802666d0d9248393d0b02abc93ae.json",
+ "assets/demo.png":"https://xxx.com/f535a73a3dfe15ca7c623512f09d5ed4.png"
+ }
+ ```
+
+ The key corresponds to the file's relative path in the project, and the value corresponds to the file's online address (using object storage). The backend needs to deserialize the project file structure for the frontend, thus loading the entire project.
+
+ After loading the entire project, the browser might have a data structure like this:
+
+ ```json
+ const projectFiles = {
+ "index.json": {
+ onlineUrl: "https://xxx.com/123.json",
+ content: '...'
+ }, 
+ // ...
+ }
+
+ ```
+
+ The key corresponds to the file's relative path, and the value includes the online address, file content, etc.
+
+
+
+2. **Project Editing and Saving**: After the user edits a project file, the frontend interacts directly with the object storage service for file upload and deletion. After editing, the frontend sends the updated project file structure to the backend, which updates the database.
+
+ ### Core Logic Detail Explanation
+
+ #### Loading Project Files
+
+ - **Frontend Request**: Carries the project ID to initiate a project loading request to the backend.
+ - **Backend Processing**: Queries the project file structure in the database based on the project ID, and returns the serialized JSON string to the frontend.
+ - **Frontend Parsing**: Converts the JSON string into a data structure of project files for editing and browsing by the user.
+
+ #### Saving Edited Projects
+
+ - **File Processing**: After editing a file, the frontend removes the file's `onlineUrl` and interacts with the object storage service to delete the old file, upload the new file, and obtain a new `url`.
+ - **Project File Structure Update**: The frontend collects all new `urls` of the files, forming an updated project file structure.
+ - **Backend Database Update**: The frontend sends the updated project file structure to the backend, which serializes it and updates the database, with the version number changing accordingly.
+
+ ### Points to Note
+
+ - Using a hash algorithm (e.g., MD5) to generate the file name for a file maintains the original file extension. This ensures the file's online address uniquely identifies the file, avoiding duplicate files and saving resources, as duplicate files will have the same `url`. If a file is changed, its `url` will change, providing a basis for a variant of incremental update between the client and server.
+
+ - Users may need to download the entire project. This can be quickly accomplished directly with the object storage's packaging feature, meaning the frontend can directly interact with object storage without going through the backend.
+
+ - Upon clicking the edit button in the UI, the frontend deletes the online address of the file, which is the `onlineUrl`. This is because once a file is edited, it is considered changed, and without a new online address, the file's old online address is removed. This approach allows for a kind of incremental update based on the presence or absence of each project file's online address in the browser.
+
+ A possible logic for frontend project update:
+
+ ```javascript
+ function saveProject() {
+ var fileTree = {}
+ for (const path of projectFiles) {
+ var url = projectFiles[path].onlineUrl
+ if (url == null) {
+ url = uploadFile(path, projectFiles[path].content)
+ }
+ fileTree[path] = url
+ }
+ postToServer(fileTree)
+ }
+ ```
+
+ - For a new project, since every file edited by the user does not have an online address, files without `urls` can be uploaded in the manner described above, and the new file structure can be sent to the backend.
+ - The initial version of the project is set to 1. When the user saves the project, the backend increases the version number as it updates the database.
+ - Throughout the process of loading and saving project files, the interaction between the frontend and backend only involves loading project file structures from the backend and updating the database by the backend, without the backend dealing with object storage. The frontend interacts directly with object storage.
+