From a31994dc980facc01f621ee79661267f9195c022 Mon Sep 17 00:00:00 2001 From: xlsea Date: Mon, 30 Jun 2025 11:44:32 +0800 Subject: [PATCH] =?UTF-8?q?docs(projects):=20=E4=BC=98=E5=8C=96=20cursor?= =?UTF-8?q?=20=E8=A7=84=E5=88=99=E5=8F=8A=20mcp?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .codelf/attention.md | 106 ---- .codelf/changelog.md | 36 -- .codelf/project.md | 1004 ------------------------------------- .cursor/mcp.json | 39 ++ .cursor/rules/riper-5.mdc | 171 +++++++ 5 files changed, 210 insertions(+), 1146 deletions(-) delete mode 100644 .codelf/attention.md delete mode 100644 .codelf/changelog.md delete mode 100644 .codelf/project.md create mode 100644 .cursor/mcp.json create mode 100644 .cursor/rules/riper-5.mdc diff --git a/.codelf/attention.md b/.codelf/attention.md deleted file mode 100644 index 1834c151..00000000 --- a/.codelf/attention.md +++ /dev/null @@ -1,106 +0,0 @@ -## Development Guidelines - -### Framework and Language -> This project uses Vue 3 with TypeScript, focusing on modern development practices and type safety. - -**Framework Considerations:** -- Version Compatibility: Ensure all dependencies are compatible with Vue 3.4+ and TypeScript 5.3+ -- Feature Usage: Leverage Vue 3 Composition API and TypeScript features -- Performance Patterns: Follow Vue 3 best practices for optimal performance -- Upgrade Strategy: Keep dependencies up to date while maintaining compatibility -- Importance Notes for Framework: - * Use Composition API for better code organization and reusability - * Implement proper TypeScript types for better development experience - * Follow Vue 3's reactivity system best practices - -**Language Best Practices:** -- Type Safety: Use TypeScript's type system to prevent runtime errors -- Modern Features: Utilize TypeScript's latest features while maintaining compatibility -- Consistency: Apply consistent coding patterns throughout the codebase -- Documentation: Document complex TypeScript implementations and workarounds - -### Code Abstraction and Reusability -> The project follows a modular architecture with clear separation of concerns. Key reusable components and utilities are organized in specific directories. - -**Modular Design Principles:** -- Single Responsibility: Each module is responsible for only one functionality -- High Cohesion, Low Coupling: Related functions are centralized, reducing dependencies between modules -- Stable Interfaces: Expose stable interfaces externally while internal implementations can vary - -**Reusable Component Library:** -``` -root -- src - - components // Reusable Vue components - - advanced // Advanced UI components - - common // Common UI components - - custom // Custom business components - - hooks // Reusable Vue composition functions - - business // Business-specific hooks - - common // Common utility hooks - - utils // Utility functions - - common.ts // Common utility functions - - crypto.ts // Cryptographic utilities - - format.ts // Formatting utilities - - storage.ts // Storage utilities -``` - -### Coding Standards and Tools -**Code Formatting Tools:** -- ESLint: JavaScript/TypeScript code checking -- Prettier: Code formatting -- StyleLint: CSS/SCSS code checking - -**Naming and Structure Conventions:** -- Semantic Naming: Variable/function names should clearly express their purpose -- Consistent Naming Style: - * Vue components: PascalCase (e.g., UserProfile.vue) - * TypeScript files: camelCase (e.g., userService.ts) - * CSS/SCSS: kebab-case (e.g., user-profile.scss) -- Directory Structure follows functional responsibility division - -### Frontend-Backend Collaboration Standards -**API Design and Documentation:** -- RESTful design principles - * Use HTTP methods (GET, POST, PUT, DELETE) to represent operations - * Follow RESTful resource naming conventions -- Timely interface documentation updates - * Document API endpoints, parameters, and responses - * Keep API documentation in sync with implementation -- Unified error handling specifications - * Implement consistent error handling across the application - * Use appropriate HTTP status codes - -**Data Flow:** -- Clear frontend state management - * Use Pinia for state management - * Implement proper state persistence strategies -- Data validation on both frontend and backend - * Validate data types and constraints - * Implement proper error handling -- Standardized asynchronous operation handling - * Use consistent API call patterns - * Implement proper loading and error states - -### Performance and Security -**Performance Optimization Focus:** -- Resource loading optimization - * Use code splitting and lazy loading - * Implement proper caching strategies -- Rendering performance optimization - * Use virtualization for large lists - * Implement proper pagination -- Appropriate use of caching - * Implement caching strategies for API responses - * Use browser storage effectively - -**Security Measures:** -- Input validation and filtering - * Validate user inputs and sanitize data - * Implement proper XSS protection -- Protection of sensitive information - * Use secure authentication and authorization mechanisms - * Implement proper token management -- Access control mechanisms - * Implement role-based access control - * Use proper permission checking diff --git a/.codelf/changelog.md b/.codelf/changelog.md deleted file mode 100644 index 3b5abd44..00000000 --- a/.codelf/changelog.md +++ /dev/null @@ -1,36 +0,0 @@ -# Changelog - -## [Unreleased] - -### Added -- Added UnoCSS usage guidelines -- Added API request pattern documentation -- Added hooks usage guidelines for boolean and loading states -- Added table component guidelines with implementation examples -- Added code cleanliness guidelines for unused imports and variables -- Added comprehensive README.md file with project overview, installation instructions, development guidelines, and feature descriptions - -### Changed -- Updated development guidelines with new sections -- Enhanced code documentation with specific usage patterns -- Updated UnoCSS documentation to emphasize its priority over custom CSS/SCSS -- Added guidance on choosing between useBoolean and useLoading based on business requirements - -## [1.0.1] - 2024-06-28 - -### Added -- Enhanced project documentation with detailed component descriptions -- Added key project components section to documentation -- Added detailed descriptions of build system, monorepo structure, frontend architecture, API integration, and theming system - -### Changed -- Improved project structure documentation with more detailed explanations -- Reorganized documentation to better highlight important architecture components - -## [1.0.0] - 2024-03-20 - -### Added -- Initial project setup -- Basic project structure -- Core functionality implementation -- Documentation framework diff --git a/.codelf/project.md b/.codelf/project.md deleted file mode 100644 index b12aceee..00000000 --- a/.codelf/project.md +++ /dev/null @@ -1,1004 +0,0 @@ -## RuoYi-Plus-Soybean - -> A modern admin system based on RuoYi-Vue-Plus, enhanced with Soybean Admin features - -> This project combines the robust backend capabilities of RuoYi-Vue-Plus with the modern frontend features of Soybean Admin, providing a comprehensive enterprise-level admin system. - -> Active Development - -> Open Source Project - -> Framework: Vue 3 + TypeScript + Vite + Naive UI -> Language: TypeScript -> State Management: Pinia -> HTTP Client: Axios/Alova -> UI Framework: Naive UI -> Build Tool: Vite -> Package Manager: pnpm - -## Dependencies - -* vue (^3.4.0): Progressive JavaScript framework -* typescript (^5.3.0): JavaScript with syntax for types -* vite (^5.0.0): Next generation frontend tooling -* naive-ui (^2.37.0): A Vue 3 Component Library -* pinia (^2.1.0): Intuitive, type safe store for Vue -* axios (^1.6.0): Promise based HTTP client -* alova (^2.0.0): Lightweight request strategy library -* dayjs (^1.11.0): Fast 2kB alternative to Moment.js -* colord (^2.9.0): Color manipulation library -* crypto-js (^4.2.0): JavaScript library of crypto standards - -## Development Environment - -> Node.js >= 18.0.0 -> pnpm >= 8.0.0 -> Git - -> The project uses pnpm workspaces for monorepo management, with multiple packages in the packages directory. - -## Structure - -> The project follows a modular architecture with clear separation of concerns. Key directories and their purposes are explained below. - -``` -root -- build // Build configuration and plugins - - config // Build configuration files - - plugins // Vite plugins -- docs // Documentation and templates - - java // Java backend documentation - - template // Code generation templates -- packages // Monorepo packages - - alova // HTTP client implementation using Alova - - axios // HTTP client implementation using Axios - - color // Color management utilities - - hooks // Reusable Vue composition functions - - materials // UI components and materials - - ofetch // HTTP client implementation using ofetch - - scripts // Build and development scripts - - uno-preset // UnoCSS preset configuration - - utils // Common utility functions -- public // Static assets -- src // Main application source code - - assets // Static assets (images, icons) - - components // Reusable Vue components - - constants // Application constants - - enum // TypeScript enums - - hooks // Vue composition functions - - layouts // Page layouts - - locales // Internationalization - - plugins // Vue plugins - - router // Vue Router configuration - - service // API services - - store // Pinia store modules - - styles // Global styles - - theme // Theme configuration - - typings // TypeScript type definitions - - utils // Utility functions - - views // Page components -``` - -### Key Project Components - -#### Build System -The build system is based on Vite with custom configurations for different environments. The `build/plugins` directory contains custom Vite plugins for optimizing the build process, including router auto-generation and UnoCSS integration. - -#### Monorepo Packages -The project uses a monorepo structure with multiple packages in the `packages` directory: -- `alova` & `axios`: Two HTTP client implementations allowing flexible API interaction strategies -- `hooks`: Custom Vue composition API hooks for common functionalities like loading states, boolean toggles, and table operations -- `materials`: Reusable UI components like admin layouts and tabbed interfaces -- `color`: Advanced color management system for theme customization - -#### Frontend Architecture -- The application follows a modern Vue 3 + TypeScript architecture -- Uses Pinia for state management with modular stores -- Implements router-based code splitting for performance optimization -- Leverages NaiveUI as the primary UI component library -- Utilizes UnoCSS for atomic CSS utility classes - -#### API Integration -- Supports multiple HTTP clients (Axios, Alova) through adapter pattern -- Implements request interceptors for authentication and error handling -- Uses TypeScript for full API type safety - -#### Theming System -- Comprehensive theme customization through CSS variables -- Support for light/dark modes and custom color palettes -- Integration with NaiveUI theming system - -## Dependencies (init from programming language specification like package.json, requirements.txt, etc.) - -* package1 (version): simple description -* package2 (version): simple description - - -## Development Environment - -> include all the tools and environments needed to run the project -> makefile introduction (if exists) - - -## Structrue (init from project tree) - -> It is essential to consistently refine the analysis down to the file level — this level of granularity is of utmost importance. - -> If the number of files is too large, you should at least list all the directories, and provide comments for the parts you consider particularly important. - -> In the code block below, add comments to the directories/files to explain their functionality and usage scenarios. - -> if you think the directory/file is not important, you can not skip it, just add a simple comment to it. - -> but if you think the directory/file is important, you should read the files and add more detail comments on it (e.g. add comments on the functions, classes, and variables. explain the functionality and usage scenarios. write the importance of the directory/file). -``` -root -- .editorconfig -- .env -- .env.dev -- .env.prod -- .env.test -- .gitattributes -- .gitignore -- .npmrc -- LICENSE -- build - - config - - index.ts - - proxy.ts - - time.ts - - plugins - - devtools.ts - - html.ts - - index.ts - - monaco-editor.ts - - router.ts - - unocss.ts - - unplugin.ts -- docs - - README.md - - java - - SysMenuServiceImpl.java - - VelocityUtils.java - - template - - api - - soy.api.ts.vm - - modules - - soy.operate-drawer.vue.vm - - soy.search.vue.vm - - soy.index.vue.vm - - typings - - soy.api.d.ts.vm -- eslint.config.js -- index.html -- package.json -- packages - - alova - - node_modules - - @alova - - mock - - @sa - - utils - - alova - - package.json - - src - - client.ts - - constant.ts - - fetch.ts - - index.ts - - mock.ts - - type.ts - - tsconfig.json - - axios - - node_modules - - @sa - - utils - - @types - - qs - - axios - - axios-retry - - qs - - package.json - - src - - constant.ts - - index.ts - - options.ts - - shared.ts - - type.ts - - tsconfig.json - - color - - node_modules - - @sa - - utils - - colord - - package.json - - src - - constant - - index.ts - - name.ts - - palette.ts - - index.ts - - palette - - antd.ts - - index.ts - - recommend.ts - - shared - - colord.ts - - index.ts - - name.ts - - types - - index.ts - - tsconfig.json - - hooks - - node_modules - - @sa - - axios - - utils - - package.json - - src - - index.ts - - use-boolean.ts - - use-context.ts - - use-count-down.ts - - use-loading.ts - - use-request.ts - - use-signal.ts - - use-svg-icon-render.ts - - use-table.ts - - tsconfig.json - - materials - - node_modules - - .bin - - tcm - - @sa - - utils - - simplebar-vue - - typed-css-modules - - package.json - - src - - index.ts - - libs - - admin-layout - - index.module.css - - index.module.css.d.ts - - index.ts - - index.vue - - shared.ts - - page-tab - - button-tab.vue - - chrome-tab-bg.vue - - chrome-tab.vue - - index.module.css - - index.module.css.d.ts - - index.ts - - index.vue - - shared.ts - - svg-close.vue - - simple-scrollbar - - index.ts - - index.vue - - types - - index.ts - - tsconfig.json - - ofetch - - node_modules - - ofetch - - package.json - - src - - index.ts - - tsconfig.json - - scripts - - bin.ts - - node_modules - - .bin - - bumpp - - ncu - - npm-check-updates - - rimraf - - @soybeanjs - - changelog - - bumpp - - c12 - - cac - - consola - - enquirer - - execa - - kolorist - - npm-check-updates - - rimraf - - package.json - - src - - commands - - changelog.ts - - cleanup.ts - - git-commit.ts - - index.ts - - release.ts - - router.ts - - update-pkg.ts - - config - - index.ts - - index.ts - - locales - - index.ts - - shared - - index.ts - - types - - index.ts - - tsconfig.json - - uno-preset - - package.json - - src - - index.ts - - tsconfig.json - - utils - - node_modules - - .bin - - nanoid - - @types - - crypto-js - - colord - - crypto-js - - klona - - localforage - - nanoid - - package.json - - src - - crypto.ts - - index.ts - - klona.ts - - nanoid.ts - - storage.ts - - tsconfig.json -- pnpm-lock.yaml -- pnpm-workspace.yaml -- public - - favicon.png -- src - - App.vue - - assets - - imgs - - logo.png - - soybean.jpg - - svg-icon - - activity.svg - - at-sign.svg - - avatar.svg - - banner.svg - - cast.svg - - chrome.svg - - copy.svg - - custom-icon.svg - - empty-data.svg - - expectation.svg - - heart.svg - - maxkey.svg - - menu - - 404.svg - - bug.svg - - build.svg - - button.svg - - caret-back.svg - - caret-forward.svg - - cascader.svg - - category.svg - - chart.svg - - checkbox.svg - - clipboard.svg - - code.svg - - color.svg - - company.svg - - component.svg - - dashboard.svg - - date-range.svg - - date.svg - - dict.svg - - documentation.svg - - download.svg - - drag.svg - - druid.svg - - edit.svg - - education.svg - - email.svg - - example.svg - - excel.svg - - exit-fullscreen.svg - - eye-open.svg - - eye.svg - - finish.svg - - form.svg - - fullscreen.svg - - gitee.svg - - github.svg - - guide.svg - - icon.svg - - input.svg - - international.svg - - job.svg - - language.svg - - link.svg - - list.svg - - lock.svg - - log.svg - - logininfor.svg - - message.svg - - model.svg - - money.svg - - monitor.svg - - my-copy.svg - - my-task.svg - - nested.svg - - number.svg - - online.svg - - password.svg - - pdf.svg - - people.svg - - peoples.svg - - phone.svg - - post.svg - - process-definition.svg - - qq.svg - - question.svg - - radio.svg - - rate.svg - - redis-list.svg - - redis.svg - - row.svg - - search.svg - - select.svg - - server.svg - - shopping.svg - - size.svg - - skill.svg - - slider.svg - - star.svg - - swagger.svg - - switch.svg - - system.svg - - tab.svg - - table.svg - - textarea.svg - - theme.svg - - time-range.svg - - time.svg - - tool.svg - - tree-table.svg - - tree.svg - - upload.svg - - user.svg - - validCode.svg - - waiting.svg - - wechat.svg - - workflow.svg - - zip.svg - - network-error.svg - - no-icon.svg - - no-permission.svg - - not-found.svg - - service-error.svg - - topiam.svg - - wind.svg - - components - - advanced - - table-column-setting.vue - - table-header-operation.vue - - table-row-check-alert.vue - - table-sider-layout.vue - - common - - app-provider.vue - - dark-mode-container.vue - - exception-base.vue - - full-screen.vue - - lang-switch.vue - - menu-toggler.vue - - monaco-editor.vue - - pin-toggler.vue - - reload-button.vue - - system-logo.vue - - theme-schema-switch.vue - - custom - - better-scroll.vue - - boolean-tag.vue - - button-icon.vue - - count-to.vue - - dict-radio.vue - - dict-select.vue - - dict-tag.vue - - file-upload.vue - - form-tip.vue - - json-preview.vue - - look-forward.vue - - menu-tree-select.vue - - post-select.vue - - role-select.vue - - soybean-avatar.vue - - status-switch.vue - - svg-icon.vue - - tenant-select.vue - - wave-bg.vue - - constants - - app.ts - - business.ts - - common.ts - - reg.ts - - enum - - index.ts - - hooks - - business - - auth.ts - - captcha.ts - - dict.ts - - download.ts - - common - - echarts.ts - - form.ts - - icon.ts - - loading.ts - - router.ts - - table.ts - - tree-table.ts - - layouts - - base-layout - - index.vue - - blank-layout - - index.vue - - context - - index.ts - - modules - - global-breadcrumb - - index.vue - - global-content - - index.vue - - global-footer - - index.vue - - global-header - - components - - theme-button.vue - - user-avatar.vue - - index.vue - - global-logo - - index.vue - - global-menu - - components - - first-level-menu.vue - - index.vue - - modules - - horizontal-menu.vue - - horizontal-mix-menu.vue - - reversed-horizontal-mix-menu.vue - - vertical-menu.vue - - vertical-mix-menu.vue - - global-search - - components - - search-footer.vue - - search-modal.vue - - search-result.vue - - index.vue - - global-sider - - index.vue - - global-tab - - context-menu.vue - - index.vue - - theme-drawer - - components - - layout-mode-card.vue - - setting-item.vue - - index.vue - - modules - - config-operation.vue - - dark-mode.vue - - layout-mode.vue - - page-fun.vue - - theme-color.vue - - locales - - dayjs.ts - - index.ts - - langs - - en-us.ts - - zh-cn.ts - - locale.ts - - naive.ts - - main.ts - - plugins - - app.ts - - assets.ts - - dayjs.ts - - iconify.ts - - index.ts - - loading.ts - - nprogress.ts - - router - - elegant - - imports.ts - - routes.ts - - transform.ts - - guard - - index.ts - - progress.ts - - route.ts - - title.ts - - index.ts - - routes - - builtin.ts - - index.ts - - service - - api - - auth.ts - - index.ts - - monitor - - cache.ts - - index.ts - - login-infor.ts - - online.ts - - oper-log.ts - - route.ts - - system - - client.ts - - config.ts - - dept.ts - - dict-data.ts - - dict.ts - - index.ts - - menu.ts - - notice.ts - - oss-config.ts - - oss.ts - - post.ts - - role.ts - - social.ts - - tenant-package.ts - - tenant.ts - - user.ts - - tool - - gen.ts - - index.ts - - request - - index.ts - - shared.ts - - type.ts - - store - - index.ts - - modules - - app - - index.ts - - auth - - index.ts - - shared.ts - - dict - - index.ts - - notice - - index.ts - - route - - index.ts - - shared.ts - - tab - - index.ts - - shared.ts - - theme - - index.ts - - shared.ts - - plugins - - index.ts - - styles - - css - - global.css - - nprogress.css - - reset.css - - transition.css - - scss - - custom.scss - - global.scss - - scrollbar.scss - - theme - - settings.ts - - vars.ts - - typings - - api - - api.d.ts - - monitor.api.d.ts - - system.api.d.ts - - tool.api.d.ts - - app.d.ts - - common.d.ts - - components.d.ts - - elegant-router.d.ts - - global.d.ts - - naive-ui.d.ts - - router.d.ts - - storage.d.ts - - union-key.d.ts - - vite-env.d.ts - - utils - - agent.ts - - common.ts - - copy.ts - - crypto.ts - - format.ts - - icon.ts - - jsencrypt.ts - - service.ts - - sse.ts - - storage.ts - - websocket.ts - - views - - _builtin - - 403 - - index.vue - - 404 - - index.vue - - 500 - - index.vue - - iframe-page - - [url].vue - - login - - index.vue - - modules - - bind-wechat.vue - - code-login.vue - - pwd-login.vue - - register.vue - - reset-pwd.vue - - social-callback - - index.vue - - user-center - - index.vue - - home - - index.vue - - modules - - card-data.vue - - creativity-banner.vue - - header-banner.vue - - line-chart.vue - - pie-chart.vue - - project-news.vue - - monitor - - cache - - index.vue - - login-infor - - index.vue - - modules - - login-infor-search.vue - - login-infor-view-drawer.vue - - online - - index.vue - - modules - - online-search.vue - - oper-log - - index.vue - - modules - - oper-log-search.vue - - oper-log-view-drawer.vue - - system - - client - - index.vue - - modules - - client-operate-drawer.vue - - client-search.vue - - config - - index.vue - - modules - - config-operate-drawer.vue - - config-search.vue - - dept - - index.vue - - modules - - dept-operate-drawer.vue - - dept-search.vue - - dict - - data - - index.vue - - modules - - dict-data-operate-drawer.vue - - dict-data-search.vue - - index.vue - - mitt.ts - - type - - index.vue - - modules - - dict-type-operate-drawer.vue - - dict-type-search.vue - - menu - - index.vue - - modules - - menu-operate-drawer.vue - - notice - - index.vue - - modules - - notice-operate-drawer.vue - - notice-search.vue - - oss - - index.vue - - modules - - oss-search.vue - - oss-upload-modal.vue - - oss-config - - index.vue - - modules - - oss-config-operate-drawer.vue - - oss-config-search.vue - - post - - index.vue - - modules - - post-operate-drawer.vue - - post-search.vue - - tenant - - index.vue - - modules - - tenant-operate-drawer.vue - - tenant-search.vue - - user - - index.vue - - modules - - user-operate-drawer.vue - - user-search.vue - - tool - - gen - - index.vue - - modules - - gen-table-db-search.vue - - gen-table-import-drawer.vue - - gen-table-operate-drawer.vue - - gen-table-preview-drawer.vue - - gen-table-search.vue -- tsconfig.json -- uno.config.ts -- vite.config.ts -``` - -## Development Guidelines - -### Framework and Language -> This project uses Vue 3 with TypeScript, focusing on modern development practices and type safety. - -**Framework Considerations:** -- Version Compatibility: Ensure all dependencies are compatible with Vue 3.4+ and TypeScript 5.3+ -- Feature Usage: Leverage Vue 3 Composition API and TypeScript features -- Performance Patterns: Follow Vue 3 best practices for optimal performance -- Upgrade Strategy: Keep dependencies up to date while maintaining compatibility -- Importance Notes for Framework: - * Use Composition API for better code organization and reusability - * Implement proper TypeScript types for better development experience - * Follow Vue 3's reactivity system best practices - -**Language Best Practices:** -- Type Safety: Use TypeScript's type system to prevent runtime errors -- Modern Features: Utilize TypeScript's latest features while maintaining compatibility -- Consistency: Apply consistent coding patterns throughout the codebase -- Documentation: Document complex TypeScript implementations and workarounds - -### Code Abstraction and Reusability -> The project follows a modular architecture with clear separation of concerns. Key reusable components and utilities are organized in specific directories. - -**Modular Design Principles:** -- Single Responsibility: Each module is responsible for only one functionality -- High Cohesion, Low Coupling: Related functions are centralized, reducing dependencies between modules -- Stable Interfaces: Expose stable interfaces externally while internal implementations can vary - -**Reusable Component Library:** -``` -root -- src - - components // Reusable Vue components - - advanced // Advanced UI components - - common // Common UI components - - custom // Custom business components - - hooks // Reusable Vue composition functions - - business // Business-specific hooks - - common // Common utility hooks - - utils // Utility functions - - common.ts // Common utility functions - - crypto.ts // Cryptographic utilities - - format.ts // Formatting utilities - - storage.ts // Storage utilities -``` - -### Coding Standards and Tools -**Code Formatting Tools:** -- ESLint: JavaScript/TypeScript code checking -- Prettier: Code formatting -- StyleLint: CSS/SCSS code checking - -**Naming and Structure Conventions:** -- Semantic Naming: Variable/function names should clearly express their purpose -- Consistent Naming Style: - * Vue components: PascalCase (e.g., UserProfile.vue) - * TypeScript files: camelCase (e.g., userService.ts) - * CSS/SCSS: kebab-case (e.g., user-profile.scss) -- Directory Structure follows functional responsibility division - -### Frontend-Backend Collaboration Standards -**API Design and Documentation:** -- RESTful design principles - * Use HTTP methods (GET, POST, PUT, DELETE) to represent operations - * Follow RESTful resource naming conventions -- Timely interface documentation updates - * Document API endpoints, parameters, and responses - * Keep API documentation in sync with implementation -- Unified error handling specifications - * Implement consistent error handling across the application - * Use appropriate HTTP status codes - -**Data Flow:** -- Clear frontend state management - * Use Pinia for state management - * Implement proper state persistence strategies -- Data validation on both frontend and backend - * Validate data types and constraints - * Implement proper error handling -- Standardized asynchronous operation handling - * Use consistent API call patterns - * Implement proper loading and error states - -### Performance and Security -**Performance Optimization Focus:** -- Resource loading optimization - * Use code splitting and lazy loading - * Implement proper caching strategies -- Rendering performance optimization - * Use virtualization for large lists - * Implement proper pagination -- Appropriate use of caching - * Implement caching strategies for API responses - * Use browser storage effectively - -**Security Measures:** -- Input validation and filtering - * Validate user inputs and sanitize data - * Implement proper XSS protection -- Protection of sensitive information - * Use secure authentication and authorization mechanisms - * Implement proper token management -- Access control mechanisms - * Implement role-based access control - * Use proper permission checking - -### Style and UI Guidelines -**UnoCSS Usage:** -- Priority: UnoCSS should be the primary styling solution -- Usage Guidelines: - * Use UnoCSS utility classes for common styling needs - * Follow the project's UnoCSS preset configuration - * Maintain consistency in class naming and usage - * Document custom UnoCSS utilities when created - * Prefer UnoCSS over custom SCSS/CSS when possible - -### API and Data Handling -**API Request Pattern:** -- Standardized API Response Handling: - * Use the pattern: `const { data, error } = fetchApi();` - * `data` represents the successful response data - * `error` represents any error information -- Error Handling: - * Implement proper error handling for API responses - * Use consistent error message formatting - * Handle network errors appropriately - -### Hooks Usage Guidelines -**Boolean and Loading State Management:** -- Use the provided hooks from '@sa/hooks': - * Boolean state: `import { useBoolean } from '@sa/hooks';` - * Usage: `const { bool, setTrue, setFalse } = useBoolean();` -- Loading state management: - * Use: `import { useLoading } from '@sa/hooks';` - * Usage: `const { loading, startLoading, endLoading } = useLoading();` -- Choose between `useBoolean` and `useLoading` based on actual business requirements - -**Table Component Guidelines:** -- Use the provided table hooks: - * Regular tables: `import { useTable } from '@/hooks/common/table';` - * Tree tables: `import { useTreeTable } from '@/hooks/common/tree-table';` -- Implementation examples available in: - * Regular tables: `src/views/system/user/index.vue` - * Tree tables: `src/views/system/dept/index.vue` -- Follow the established patterns for: - * Table data management - * Column configuration - * Search functionality - * CRUD operations - -**Code Cleanliness:** -- Ensure unused imports and variables are removed -- Use IDE tools or linters to automatically detect and remove unused code -- Apply proper naming conventions for variables that are intentionally unused - * Prefix with underscore (e.g., `_unusedVar`) to indicate deliberate non-usage -- Keep components clean and optimized by removing any code that doesn't contribute to functionality diff --git a/.cursor/mcp.json b/.cursor/mcp.json new file mode 100644 index 00000000..5c4d03bb --- /dev/null +++ b/.cursor/mcp.json @@ -0,0 +1,39 @@ +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + }, + "sequential-thinking": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"] + }, + "mcp-feedback-enhanced": { + "command": "uvx", + "args": ["mcp-feedback-enhanced@latest"], + "timeout": 600, + "autoApprove": ["interactive_feedback"] + }, + "playwright": { + "command": "npx", + "args": ["@playwright/mcp@latest"] + }, + "mcp-server-time": { + "command": "uvx", + "args": ["mcp-server-time", "--local-timezone=Asia/Shanghai"] + }, + "shrimp-task-manager": { + "command": "npx", + "args": ["-y", "mcp-shrimp-task-manager"], + "env": { + "DATA_DIR": "D:/workspace/Aother/mcp-shrimp-task-manager/data", + "TEMPLATES_USE": "en", + "ENABLE_GUI": "false" + } + }, + "mcp-deepwiki": { + "command": "npx", + "args": ["-y", "mcp-deepwiki@latest"] + } + } +} diff --git a/.cursor/rules/riper-5.mdc b/.cursor/rules/riper-5.mdc new file mode 100644 index 00000000..6b7578f1 --- /dev/null +++ b/.cursor/rules/riper-5.mdc @@ -0,0 +1,171 @@ +--- +description: +globs: +alwaysApply: false +--- + +**# RIPER-5 + 多维度思维 + 代理执行协议 (v4.9.1 - MCP工具驱动版)** + +**元指令：** 此协议旨在最大化你的战略规划与执行效率。你的核心任务是**指挥和利用MCP工具集**来驱动项目进展。严格遵守核心原则，利用 `mcp-shrimp-task-manager` 进行项目规划与追踪，使用 `deepwiki-mcp` 进行深度研究。主动管理 `/project_document` 作为知识库。**每轮主要响应后，调用 `mcp.feedback_enhanced` 进行交互或通知。** + +**目录** +* 核心理念与角色 +* MCP工具集详解 +* RIPER-5 模式：工具驱动的工作流 +* 关键执行指南 +* 产出核心要求 (文档与代码) +* 任务文件模板 (精简) +* 性能与自动化期望 + +## 1. 核心理念与角色 + +**1.1. AI设定与理念：** +你是超智能AI项目指挥官（代号：齐天大圣），你的职责不是手动完成每一步，而是**高效地指挥MCP工具集**来自动化和管理整个项目生命周期。所有产出和关键文档存储在 `/project_document` 中。你将整合以下专家视角进行决策： +* **PM (项目经理):** 定义总体目标和风险，监控由 `mcp-shrimp-task-manager` 报告的进度。 +* **PDM (产品经理):** 提供用户价值和需求，作为 `mcp-shrimp-task-manager` 规划任务的输入。 +* **AR (架构师):** 负责系统和安全设计，其产出的架构将作为 `mcp-shrimp-task-manager` 任务分解的依据。 +* **LD (首席开发):** 作为主要的**任务执行者**，从 `mcp-shrimp-task-manager` 接收任务，进行编码和测试（包括 `mcp.playwright`）。 +* **DW (文档编写者):** 审计所有由AI或MCP工具生成的文档，确保存储在 `/project_document` 的信息符合规范。 + +**1.2. `/project_document` 与文档管理：** +* `/project_document` 是项目的**最终知识库和产出存档**。 +* `mcp-shrimp-task-manager` 负责过程中的任务记忆和状态追踪。 +* AI负责将关键的、总结性的信息（如最终架构、审查报告、自动生成的任务摘要等）从MCP同步归档至 `/project_document`。 +* **文档原则：** 最新内容优先、保留完整历史、精确时间戳（通过 `mcp.server_time`）、更新原因明确。 + +**1.3. 核心思维与编码原则 (AI内化执行)：** +* **思维原则：** 系统思维、风险防范、工程卓越。AI应利用 `mcp.sequential_thinking` 进行深度思考，但将常规规划交给 `mcp-shrimp-task-manager`。 +* **编码原则：** KISS, YAGNI, SOLID, DRY, 高内聚低耦合, 可读性, 可测试性, 安全编码。 + +## 2. MCP工具集详解 + +* **`mcp.feedback_enhanced` (用户交互核心):** + * 在每轮主要响应后**必须调用**，用于反馈、确认和流程控制。 + * **AUTO模式自动化:** 若用户短时无交互，AI自动按 `mcp-shrimp-task-manager` 的计划推进。 +* **`mcp-shrimp-task-manager` (核心任务管理器):** + * **功能：** 项目规划、任务分解、依赖管理、状态追踪、复杂度评估、自动摘要、历史记忆。 + * **AI交互：** AI通过此MCP初始化项目、输入需求/架构、审查生成的计划、获取任务、报告结果。 + * **激活声明：** `[INTERNAL_ACTION: Initializing/Interacting with mcp-shrimp-task-manager for X.]` (AI指明X的具体操作) +* **`deepwiki-mcp` (深度知识库):** + * **功能：** 抓取 `deepwiki.com` 的页面，转换为干净的Markdown。 + * **AI交互：** 在研究阶段使用，以获取特定主题或库的深度信息。 + * **激活声明：** `[INTERNAL_ACTION: Researching 'X' via deepwiki-mcp.]` +* **`mcp.context7` & `mcp.sequential_thinking` (AI认知增强):** + * 在需要超越标准流程的深度分析或复杂上下文理解时激活。 +* **`mcp.playwright` & `mcp.server_time` (基础执行与服务):** + * `playwright` 由LD在执行E2E测试任务时使用。 + * `server_time` 为所有记录提供标准时间戳。 + +## 3. RIPER-5 模式：工具驱动的工作流 + +**通用指令：** AI的核心工作是为每个阶段选择合适的MCP工具并有效指挥它。 + +### 模式1: 研究 (RESEARCH) +* **目的：** 快速形成对任务的全面理解。 +* **核心工具与活动：** + 1. 使用 `deepwiki-mcp` 抓取特定技术文档。 + 2. 对于系统性的技术研究，激活 `mcp-shrimp-task-manager` 的**研究模式**，它将提供引导式流程来探索和比较解决方案。 + 3. 分析现有项目文件（若有）。 +* **产出：** 形成研究报告，存入 `/project_document/research/`，并在主任务文件 `任务文件名.md` 中进行摘要。 + +### 模式2: 创新 (INNOVATE) +* **目的：** 提出高层次的解决方案。此阶段侧重于人类与AI的创造性思维，较少依赖自动化工具。 +* **核心活动：** 基于研究成果，进行头脑风暴，提出2-3个候选方案。AR主导架构草图设计。 +* **产出：** 形成包含各方案优劣对比的文档，存入 `/project_document/proposals/`。主任务文件中记录最终选择的方案方向。 + +### 模式3: 计划 (PLAN) +* **目的：** 将选定的方案转化为一个完整的、结构化的、可追踪的执行计划。 +* **核心工具与活动：** + 1. **激活 `mcp-shrimp-task-manager`**。 + 2. 向其输入选定的解决方案、架构设计（来自AR）、关键需求（来自PDM）。 + 3. 指挥任务管理器进行**智能任务拆分、依赖关系管理和复杂度评估**。 + 4. PM和AR审查并批准由任务管理器生成的计划。 +* **产出：** + * 一个由 `mcp-shrimp-task-manager` 管理的完整项目计划。 + * 在主任务文件中记录**计划已生成**，并附上访问计划的Web GUI链接（如果启用）或高级别计划摘要。**不再手动罗列详细清单。** + +### 模式4: 执行 (EXECUTE) +* **目的：** 高效、准确地完成由任务管理器分派的任务。 +* **核心工具与活动 (执行循环)：** + 1. LD向 `mcp-shrimp-task-manager` **请求下一个可执行任务**。 + 2. AI对当前任务进行必要的**预执行分析 (`EXECUTE-PREP`)**。 + 3. LD执行任务（编码、使用`mcp.playwright`进行测试等）。 + 4. 完成后，向 `mcp-shrimp-task-manager` **报告任务完成状态和结果**。 + 5. 任务管理器**自动更新状态、处理依赖关系并生成任务摘要**。 +* **产出：** + * 所有代码和测试产出按规范提交。 + * 主任务文件的“任务进度”部分，通过引用 `mcp-shrimp-task-manager` 自动生成的摘要来**动态更新**，而非手动填写长篇报告。 + +### 模式5: 审查 (REVIEW) +* **目的：** 验证整个项目的成果是否符合预期。 +* **核心工具与活动：** + 1. 使用 `mcp-shrimp-task-manager` 的**任务完整性验证**功能，检查所有任务是否已关闭且符合其定义的完成标准。 + 2. 审查 `/project_document` 中归档的所有关键产出（最终架构、代码、测试报告摘要等）。 + 3. AR和LD进行代码和架构的最终审查。 +* **产出：** 在主任务文件中撰写最终的审查报告，包括与 `mcp-shrimp-task-manager` 记录的对比、综合结论和改进建议。 + +## 4. 关键执行指南 + +* **指挥官角色：** 你的主要价值在于正确地使用和指挥MCP工具，而不是手动执行本可自动化的任务。 +* **信任工具：** 信任 `mcp-shrimp-task-manager` 进行详细的计划和追踪。你的任务是提供高质量的输入，并审查其输出。 +* **自动化反馈环：** 利用 `mcp.feedback_enhanced` 和 `mcp-shrimp-task-manager` 的状态更新，与用户保持高效同步。 +* **文档归档：** AI负责在项目关键节点（如模式结束）将 `mcp-shrimp-task-manager` 中的重要信息（如阶段性摘要、最终计划概览）固化并归档到 `/project_document`。 + +## 5. 产出核心要求 (文档与代码) + +* **代码块结构 (`{{CHENGQI:...}}`):** 保持简洁，核心是 `Action`, `Timestamp`, `Reason`。 + ```language + // [INTERNAL_ACTION: Fetching current time via mcp.server_time.] + // {{CHENGQI: + // Action: [Added/Modified/Removed]; Timestamp: [...]; Reason: [Shrimp Task ID: #123, brief why]; + // }} + // {{START MODIFICATIONS}} ... {{END MODIFICATIONS}} + ``` +* **文档质量 (DW审计):** 归档到 `/project_document` 的文档必须清晰、准确、完整。 + +## 6. 任务文件模板 (`任务文件名.md` - 精简) + +# 上下文 +项目ID: [...] 任务文件名：[...] 创建于：(`mcp.server_time`) [YYYY-MM-DD HH:MM:SS +08:00] +关联协议：RIPER-5 v5.0 + +# 任务描述 +[...] + +# 1. 研究成果摘要 (RESEARCH) +* (如有) Deepwiki研究报告链接: /project_document/research/deepwiki_summary.md +* (如有) `mcp-shrimp-task-manager` 研究模式产出链接: /project_document/research/tech_comparison.md + +# 2. 选定方案 (INNOVATE) +* **最终方案方向:** [方案描述，例如：采用微服务架构，使用React前端...] +* **高层架构图链接:** /project_document/proposals/solution_arch_sketch.png + +# 3. 项目计划 (PLAN) +* **状态:** 项目计划已通过 `mcp-shrimp-task-manager` 生成并最终确定。 +* **计划访问:** [可选的Web GUI链接] 或 [高级别里程碑列表] +* **DW确认:** 计划生成过程已记录，符合规范。 + +# 4. 任务进度 (EXECUTE) +> 本部分由 `mcp-shrimp-task-manager` 的自动摘要驱动。将定期更新。 +--- +* **最近更新:** (`mcp.server_time`) [YYYY-MM-DD HH:MM:SS +08:00] +* **已完成任务摘要:** + * **[#123] 实现用户登录API:** 完成于 [...], 链接到代码提交和测试报告。 + * **[#124] 创建登录页面UI:** 完成于 [...], 链接到代码提交和Playwright测试结果。 + * ... +* **当前进行中任务:** [#125] 用户个人资料页面后端逻辑 +--- + +# 5. 最终审查 (REVIEW) +* **符合性评估:** 项目成果已对照 `mcp-shrimp-task-manager` 的计划进行验证，所有任务均已关闭。 +* **(AR)架构与安全评估:** 最终架构与设计一致，未发现重大安全疏漏。 +* **(LD)测试与质量总结:** 单元测试覆盖率达到[X%]，所有关键路径的E2E测试已通过。 +* **综合结论:** 项目成功完成/有以下偏差... +* **改进建议:** [...] + +## 7. 性能与自动化期望 + +* **极致效率：** AI应最大限度地减少手动干预，让MCP工具处理所有可以自动化的工作。 +* **战略聚焦：** 将AI的“思考”集中在无法被工具替代的领域：战略决策、创新构想、复杂问题诊断 (`mcp.sequential_thinking`) 和最终质量把关。 + +* **无缝集成：** 期望AI能流畅地在不同MCP工具之间传递信息，形成一个高度整合的自动化工作流。