|
1 | 1 | # FileClassificationSolutions |
2 | 2 |
|
3 | | -## Project Overview |
| 3 | +This repository contains documentation files in the [docs](./docs) directory. |
4 | 4 |
|
5 | | -FileClassificationSolutions is an innovative file classification and storage system developed in the Rust programming language. It aims to provide users with an efficient and convenient way to manage and retrieve various types of file data, such as memes, text files, or other abstract data types. The system establishes a non-file-system-like database architecture that allows files to be categorized and quickly retrieved based on their content and attributes (such as tags and groups). |
6 | | - |
7 | | -## Core Features |
8 | | - |
9 | | -- **Multi-dimensional Classification**: Achieve multi-dimensional file management through groups (`groups`) and tags (`tags`) |
10 | | -- **Reference Counting Mechanism**: Automatically track associations between files, groups, and tags to ensure data consistency |
11 | | -- **Flexible Querying**: Support complex queries based on multiple conditions including equals, greater than, less than, LIKE pattern matching, etc. |
12 | | -- **Batch Operations**: Support batch updates and deletions based on conditions |
13 | | -- **Primary Group Concept**: Distinguish between primary groups and ordinary groups, where primary groups have a one-to-one relationship with files |
14 | | -- **Multiple Access Methods**: Provide both Command Line Interface (CLI) and Web API access methods |
15 | | - |
16 | | -## System Architecture |
17 | | - |
18 | | -The project adopts a modular architecture design, including the following core components: |
19 | | - |
20 | | -### Core Library (file_classification_core) |
21 | | - |
22 | | -This is the business logic core of the entire project, containing data models, database access layer, and business services. |
23 | | - |
24 | | -### Command Line Interface (file_classification_cli) |
25 | | - |
26 | | -Provides an interactive command-line tool for operating the file classification system, including complete CRUD functionality. |
27 | | - |
28 | | -### Web API (file_classification_webapi) |
29 | | - |
30 | | -A RESTful API service built on the Actix-web framework that provides HTTP interfaces for data operations. |
31 | | - |
32 | | -## Database Design |
33 | | - |
34 | | -### Core Table Structure |
35 | | - |
36 | | -The system uses the following 6 core tables to store data: |
37 | | - |
38 | | -1. `files` table: Stores basic file information |
39 | | -2. `groups` table: Stores file group information |
40 | | -3. `file_groups` table: Stores many-to-many relationships between files and groups |
41 | | -4. `tags` table: Stores tag information |
42 | | -5. `group_tags` table: Stores many-to-many relationships between groups and tags |
43 | | -6. `group_relations` table: Stores hierarchical relationships between groups |
44 | | - |
45 | | -### Table Structure Details |
46 | | - |
47 | | -``` |
48 | | -CREATE TABLE IF NOT EXISTS files ( |
49 | | - id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT, |
50 | | - type TEXT NOT NULL, -- File type |
51 | | - path TEXT NOT NULL, -- File storage location |
52 | | - reference_count INTEGER NOT NULL DEFAULT 0, -- Reference count |
53 | | - group_id INTEGER NOT NULL, -- Default file group ID |
54 | | - FOREIGN KEY (group_id) REFERENCES groups(id) |
55 | | -); |
56 | | -
|
57 | | -CREATE TABLE IF NOT EXISTS groups ( |
58 | | - id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT, |
59 | | - name TEXT NOT NULL UNIQUE, -- Group name |
60 | | - reference_count INTEGER NOT NULL DEFAULT 0, -- Reference count |
61 | | - is_primary BOOLEAN NOT NULL DEFAULT false, -- Whether it's a primary group, false for no, true for yes |
62 | | - click_count INTEGER NOT NULL DEFAULT 0, -- Click count |
63 | | - share_count INTEGER NOT NULL DEFAULT 0, -- Share count |
64 | | - create_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, -- Creation time |
65 | | - modify_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, -- Modification time |
66 | | - parent_id INTEGER REFERENCES groups(id) -- Parent group ID for hierarchical structure |
67 | | -); |
68 | | -
|
69 | | -CREATE TABLE IF NOT EXISTS file_groups ( |
70 | | - file_id INTEGER NOT NULL, |
71 | | - group_id INTEGER NOT NULL, |
72 | | - relation_type INTEGER NOT NULL DEFAULT 1, -- Relationship type: 1 for primary group relationship |
73 | | - PRIMARY KEY (file_id, group_id), |
74 | | - FOREIGN KEY (file_id) REFERENCES files(id), |
75 | | - FOREIGN KEY (group_id) REFERENCES groups(id) |
76 | | -); |
77 | | -
|
78 | | -CREATE TABLE IF NOT EXISTS tags ( |
79 | | - id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT, |
80 | | - reference_count INTEGER NOT NULL DEFAULT 0, -- Reference count |
81 | | - name TEXT NOT NULL UNIQUE -- Tag name, unique |
82 | | -); |
83 | | -
|
84 | | -CREATE TABLE IF NOT EXISTS group_tags ( |
85 | | - group_id INTEGER NOT NULL, |
86 | | - tag_id INTEGER NOT NULL, |
87 | | - PRIMARY KEY (group_id, tag_id), |
88 | | - FOREIGN KEY (group_id) REFERENCES groups(id), |
89 | | - FOREIGN KEY (tag_id) REFERENCES tags(id) |
90 | | -); |
91 | | -
|
92 | | -CREATE TABLE IF NOT EXISTS group_relations ( |
93 | | - first_group_id INTEGER NOT NULL, |
94 | | - second_group_id INTEGER NOT NULL, |
95 | | - relation_type INTEGER NOT NULL DEFAULT 1, -- Relationship type: 1 for parent-child relationship |
96 | | - PRIMARY KEY (first_group_id, second_group_id, relation_type), |
97 | | - FOREIGN KEY (first_group_id) REFERENCES groups(id), |
98 | | - FOREIGN KEY (second_group_id) REFERENCES groups(id) |
99 | | -); |
100 | | -``` |
101 | | - |
102 | | - |
103 | | -## Function Details |
104 | | - |
105 | | -### File Management |
106 | | - |
107 | | -- Files are stored with unique identifiers (ID) |
108 | | -- Records file type (`type`) and storage path (`path`) |
109 | | -- Automatically maintains reference count (`reference_count`) |
110 | | -- Establishes association relationships with groups |
111 | | - |
112 | | -### Group System |
113 | | - |
114 | | -- Supports creating file groups with unique names |
115 | | -- Distinguishes between primary groups (`is_primary`) and ordinary groups |
116 | | -- Each file has a primary file group that records detailed information |
117 | | -- Tracks group usage statistics (click count, share count) |
118 | | -- Automatically maintains reference count |
119 | | -- Records creation and modification times |
120 | | - |
121 | | -### Tag System |
122 | | - |
123 | | -- Supports creating tags with unique names |
124 | | -- Organizes and classifies file groups through tags |
125 | | -- Automatically maintains reference count |
126 | | - |
127 | | -### Query Functionality |
128 | | - |
129 | | -#### Basic Queries |
130 | | - |
131 | | -Supports precise queries based on various fields: |
132 | | -- Files: ID, type, path, reference count, group ID |
133 | | -- Groups: ID, name, reference count, whether it's a primary group, click count, share count, creation time, modification time |
134 | | -- Tags: ID, name, reference count |
135 | | - |
136 | | -#### Advanced Queries |
137 | | - |
138 | | -Supports complex conditional queries: |
139 | | -- Range queries: greater than, less than |
140 | | -- Pattern matching: LIKE queries |
141 | | -- Combined conditions: AND, OR, NOT logical combinations |
142 | | -- Batch queries: IN conditions |
143 | | - |
144 | | -#### Association Queries |
145 | | - |
146 | | -- Query related file groups by tag |
147 | | -- Query groups that files belong to |
148 | | -- Query associated tags by group |
149 | | - |
150 | | -### Update Functionality |
151 | | - |
152 | | -Supports batch updates based on conditions: |
153 | | -- Files: path, type, reference count, group ID |
154 | | -- Groups: name, reference count, whether it's a primary group, click count, share count, timestamps |
155 | | -- Tags: name, reference count |
156 | | - |
157 | | -### Delete Functionality |
158 | | - |
159 | | -Supports safe data deletion: |
160 | | -- Automatically handles reduction of reference counts |
161 | | -- Cascading deletion of associated data |
162 | | -- Automatic cleanup of associated files when deleting primary groups |
163 | | - |
164 | | -## Usage |
165 | | - |
166 | | -### Command Line Interface |
167 | | - |
168 | | -Provides multiple independent command-line tools: |
169 | | - |
170 | | -```bash |
171 | | -# File operations |
172 | | -list_files # List files |
173 | | -list_files_by_conditions # Query files by conditions |
174 | | -create_file # Create file |
175 | | -delete_file # Delete file |
176 | | -update_files_by_conditions # Update files by conditions |
177 | | - |
178 | | -# Group operations |
179 | | -list_groups # List groups |
180 | | -list_groups_by_conditions # Query groups by conditions |
181 | | -create_group # Create group |
182 | | -delete_group # Delete group |
183 | | -update_groups_by_conditions # Update groups by conditions |
184 | | - |
185 | | -# Tag operations |
186 | | -list_tags # List tags |
187 | | -list_tags_by_conditions # Query tags by conditions |
188 | | -create_tag # Create tag |
189 | | -delete_tag # Delete tag |
190 | | -update_tags_by_conditions # Update tags by conditions |
191 | | - |
192 | | -# Association operations |
193 | | -list_file_groups_by_conditions # Query file-group associations by conditions |
194 | | -create_file_group # Create file-group association |
195 | | -delete_file_group # Delete file-group association |
196 | | -list_group_tags_by_conditions # Query group-tag associations by conditions |
197 | | -create_group_tag # Create group-tag association |
198 | | -delete_group_tag # Delete group-tag association |
199 | | -``` |
200 | | - |
201 | | - |
202 | | -### Web API |
203 | | - |
204 | | -Provides RESTful API interfaces: |
205 | | - |
206 | | -``` |
207 | | -# File related |
208 | | -GET /api/files # Query files |
209 | | -POST /api/files/search # Query files by conditions |
210 | | -PUT /api/files # Update files by conditions |
211 | | -DELETE /api/files/{id} # Delete file |
212 | | -
|
213 | | -# Group related |
214 | | -GET /api/groups # Query groups |
215 | | -POST /api/groups/search # Query groups by conditions |
216 | | -POST /api/groups # Create group |
217 | | -PUT /api/groups # Update groups by conditions |
218 | | -DELETE /api/groups/{id} # Delete group |
219 | | -
|
220 | | -# Tag related |
221 | | -GET /api/tags # Query tags |
222 | | -POST /api/tags/search # Query tags by conditions |
223 | | -POST /api/tags # Create tag |
224 | | -PUT /api/tags # Update tags by conditions |
225 | | -DELETE /api/tags/{id} # Delete tag |
226 | | -
|
227 | | -# File-group association related |
228 | | -GET /api/file-groups # Query file-group associations by conditions |
229 | | -POST /api/file-groups # Create file-group association |
230 | | -DELETE /api/file-groups # Delete file-group association |
231 | | -
|
232 | | -# Group-tag association related |
233 | | -GET /api/group-tags # Query group-tag associations by conditions |
234 | | -POST /api/group-tags # Create group-tag association |
235 | | -DELETE /api/group-tags # Delete group-tag association |
236 | | -``` |
237 | | - |
238 | | - |
239 | | -## Technical Features |
240 | | - |
241 | | -### Architectural Advantages |
242 | | - |
243 | | -1. **Layered Architecture**: Clear separation of data access layer, business logic layer, and presentation layer |
244 | | -2. **Modular Design**: Different functional modules organized in independent crates |
245 | | -3. **Strong Type Safety**: Utilizes Rust's type system to ensure code safety |
246 | | -4. **Error Handling**: Unified error handling mechanism |
247 | | -5. **Database Abstraction**: Uses Diesel ORM for database operations |
248 | | -6. **Scalability**: Easy to add new functional modules and access interfaces |
249 | | - |
250 | | -### Data Consistency |
251 | | - |
252 | | -1. **Transaction Processing**: Critical operations use database transactions to ensure consistency |
253 | | -2. **Reference Counting**: Automatically maintains references between entities |
254 | | -3. **Cascading Operations**: Automatically cleans up associated data during deletion operations |
255 | | - |
256 | | -### Performance Optimization |
257 | | - |
258 | | -1. **Query Optimization**: Supports complex conditional queries and sorting |
259 | | -2. **Batch Operations**: Supports batch updates and deletions |
260 | | -3. **Connection Pooling**: Web API uses database connection pooling to improve performance |
261 | | - |
262 | | -## Future Plans |
263 | | - |
264 | | -1. **Multiple File Type Support**: Extend support for more file types |
265 | | -2. **Data Index Optimization**: Create indexes on frequently queried fields |
266 | | -3. **Data Backup and Recovery**: Implement data backup and recovery mechanisms |
267 | | -4. **User Permission Management**: Support multi-user and permission control |
268 | | -5. **File Version Control**: Add file version management functionality |
269 | | -6. **Full-text Search**: Implement full-text search based on file content |
270 | | -7. **Multiple Database Compatibility**: Support more database types |
271 | | -8. **Enhanced Batch Operations**: Provide richer batch operation functionality |
272 | | - |
273 | | -## Application Scenarios |
274 | | - |
275 | | -- Meme management |
276 | | -- Document classification storage |
277 | | -- Image asset management |
278 | | -- Code snippet organization |
279 | | -- General file management systems |
280 | | - |
281 | | -This system is not only suitable for specific types of file management but can also be extended as a general file management and search solution. |
| 5 | +Please refer to the following documents for detailed information: |
| 6 | +- [Project Overview / 项目概述](./docs/README.md) - Available in both [English](./docs/README.md) and [Chinese](./docs/README_cn.md) |
| 7 | +- [Project Structure / 项目结构](./docs/project_structure.md) - Available in both [English](./docs/project_structure.md) and [Chinese](./docs/project_structure_cn.md) |
0 commit comments