Full Code of flipped-aurora/gin-vue-admin for AI

Repository: flipped-aurora/gin-vue-admin
Branch: main
Commit: a75ab546ee06
Files: 646
Total size: 3.0 MB

Directory structure:
gitextract_u70pmzr2/

├── .aone_copilot/
│   └── rules/
│       └── project_rules.md
├── .claude/
│   └── rules/
│       └── project_rules.md
├── .codex/
│   └── rules/
│       └── project_rules.md
├── .cursor/
│   └── rules/
│       └── project_rules.md
├── .gitattributes
├── .github/
│   ├── FUNDING.yml
│   ├── ISSUE_TEMPLATE/
│   │   ├── bug_report.yaml
│   │   ├── config.yml
│   │   └── feature_request.yaml
│   └── workflows/
│       └── ci.yaml
├── .gitignore
├── .trae/
│   └── rules/
│       └── project_rules.md
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE
├── Makefile
├── README-en.md
├── README.md
├── SECURITY.md
├── deploy/
│   ├── docker/
│   │   ├── Dockerfile
│   │   └── entrypoint.sh
│   ├── docker-compose/
│   │   └── docker-compose.yaml
│   └── kubernetes/
│       ├── server/
│       │   ├── gva-server-configmap.yaml
│       │   ├── gva-server-deployment.yaml
│       │   └── gva-server-service.yaml
│       └── web/
│           ├── gva-web-configmap.yaml
│           ├── gva-web-deploymemt.yaml
│           ├── gva-web-ingress.yaml
│           └── gva-web-service.yaml
├── gin-vue-admin.code-workspace
├── server/
│   ├── Dockerfile
│   ├── README.md
│   ├── api/
│   │   └── v1/
│   │       ├── enter.go
│   │       ├── example/
│   │       │   ├── enter.go
│   │       │   ├── exa_attachment_category.go
│   │       │   ├── exa_breakpoint_continue.go
│   │       │   ├── exa_customer.go
│   │       │   └── exa_file_upload_download.go
│   │       └── system/
│   │           ├── auto_code_history.go
│   │           ├── auto_code_mcp.go
│   │           ├── auto_code_package.go
│   │           ├── auto_code_plugin.go
│   │           ├── auto_code_template.go
│   │           ├── enter.go
│   │           ├── sys_api.go
│   │           ├── sys_api_token.go
│   │           ├── sys_authority.go
│   │           ├── sys_authority_btn.go
│   │           ├── sys_auto_code.go
│   │           ├── sys_captcha.go
│   │           ├── sys_casbin.go
│   │           ├── sys_dictionary.go
│   │           ├── sys_dictionary_detail.go
│   │           ├── sys_error.go
│   │           ├── sys_export_template.go
│   │           ├── sys_initdb.go
│   │           ├── sys_jwt_blacklist.go
│   │           ├── sys_login_log.go
│   │           ├── sys_menu.go
│   │           ├── sys_operation_record.go
│   │           ├── sys_params.go
│   │           ├── sys_skills.go
│   │           ├── sys_system.go
│   │           ├── sys_user.go
│   │           └── sys_version.go
│   ├── config/
│   │   ├── auto_code.go
│   │   ├── captcha.go
│   │   ├── config.go
│   │   ├── cors.go
│   │   ├── db_list.go
│   │   ├── disk.go
│   │   ├── email.go
│   │   ├── excel.go
│   │   ├── gorm_mssql.go
│   │   ├── gorm_mysql.go
│   │   ├── gorm_oracle.go
│   │   ├── gorm_pgsql.go
│   │   ├── gorm_sqlite.go
│   │   ├── jwt.go
│   │   ├── mcp.go
│   │   ├── mongo.go
│   │   ├── oss_aliyun.go
│   │   ├── oss_aws.go
│   │   ├── oss_cloudflare.go
│   │   ├── oss_huawei.go
│   │   ├── oss_local.go
│   │   ├── oss_minio.go
│   │   ├── oss_qiniu.go
│   │   ├── oss_tencent.go
│   │   ├── redis.go
│   │   ├── system.go
│   │   └── zap.go
│   ├── config.docker.yaml
│   ├── config.yaml
│   ├── core/
│   │   ├── internal/
│   │   │   ├── constant.go
│   │   │   ├── cutter.go
│   │   │   └── zap_core.go
│   │   ├── server.go
│   │   ├── server_run.go
│   │   ├── viper.go
│   │   └── zap.go
│   ├── docs/
│   │   ├── docs.go
│   │   ├── swagger.json
│   │   └── swagger.yaml
│   ├── global/
│   │   ├── global.go
│   │   ├── model.go
│   │   └── version.go
│   ├── go.mod
│   ├── go.sum
│   ├── initialize/
│   │   ├── db_list.go
│   │   ├── ensure_tables.go
│   │   ├── gorm.go
│   │   ├── gorm_biz.go
│   │   ├── gorm_mssql.go
│   │   ├── gorm_mysql.go
│   │   ├── gorm_oracle.go
│   │   ├── gorm_pgsql.go
│   │   ├── gorm_sqlite.go
│   │   ├── init.go
│   │   ├── internal/
│   │   │   ├── gorm.go
│   │   │   ├── gorm_logger_writer.go
│   │   │   └── mongo.go
│   │   ├── mcp.go
│   │   ├── mongo.go
│   │   ├── other.go
│   │   ├── plugin.go
│   │   ├── plugin_biz_v1.go
│   │   ├── plugin_biz_v2.go
│   │   ├── redis.go
│   │   ├── register_init.go
│   │   ├── reload.go
│   │   ├── router.go
│   │   ├── router_biz.go
│   │   ├── timer.go
│   │   └── validator.go
│   ├── main.go
│   ├── mcp/
│   │   ├── api_creator.go
│   │   ├── api_lister.go
│   │   ├── client/
│   │   │   ├── client.go
│   │   │   └── client_test.go
│   │   ├── dictionary_generator.go
│   │   ├── dictionary_query.go
│   │   ├── enter.go
│   │   ├── gva_analyze.go
│   │   ├── gva_execute.go
│   │   ├── gva_review.go
│   │   ├── menu_creator.go
│   │   ├── menu_lister.go
│   │   └── requirement_analyzer.go
│   ├── middleware/
│   │   ├── casbin_rbac.go
│   │   ├── cors.go
│   │   ├── email.go
│   │   ├── error.go
│   │   ├── jwt.go
│   │   ├── limit_ip.go
│   │   ├── loadtls.go
│   │   ├── logger.go
│   │   ├── operation.go
│   │   └── timeout.go
│   ├── model/
│   │   ├── common/
│   │   │   ├── basetypes.go
│   │   │   ├── clearDB.go
│   │   │   ├── request/
│   │   │   │   └── common.go
│   │   │   └── response/
│   │   │       ├── common.go
│   │   │       └── response.go
│   │   ├── example/
│   │   │   ├── exa_attachment_category.go
│   │   │   ├── exa_breakpoint_continue.go
│   │   │   ├── exa_customer.go
│   │   │   ├── exa_file_upload_download.go
│   │   │   ├── request/
│   │   │   │   └── exa_file_upload_and_downloads.go
│   │   │   └── response/
│   │   │       ├── exa_breakpoint_continue.go
│   │   │       ├── exa_customer.go
│   │   │       └── exa_file_upload_download.go
│   │   └── system/
│   │       ├── request/
│   │       │   ├── jwt.go
│   │       │   ├── sys_api.go
│   │       │   ├── sys_api_token.go
│   │       │   ├── sys_authority_btn.go
│   │       │   ├── sys_auto_code.go
│   │       │   ├── sys_auto_code_mcp.go
│   │       │   ├── sys_auto_code_package.go
│   │       │   ├── sys_auto_history.go
│   │       │   ├── sys_casbin.go
│   │       │   ├── sys_dictionary.go
│   │       │   ├── sys_dictionary_detail.go
│   │       │   ├── sys_error.go
│   │       │   ├── sys_export_template.go
│   │       │   ├── sys_init.go
│   │       │   ├── sys_login_log.go
│   │       │   ├── sys_menu.go
│   │       │   ├── sys_operation_record.go
│   │       │   ├── sys_params.go
│   │       │   ├── sys_skills.go
│   │       │   ├── sys_user.go
│   │       │   └── sys_version.go
│   │       ├── response/
│   │       │   ├── sys_api.go
│   │       │   ├── sys_authority.go
│   │       │   ├── sys_authority_btn.go
│   │       │   ├── sys_auto_code.go
│   │       │   ├── sys_captcha.go
│   │       │   ├── sys_casbin.go
│   │       │   ├── sys_menu.go
│   │       │   ├── sys_system.go
│   │       │   ├── sys_user.go
│   │       │   └── sys_version.go
│   │       ├── sys_api.go
│   │       ├── sys_api_token.go
│   │       ├── sys_authority.go
│   │       ├── sys_authority_btn.go
│   │       ├── sys_authority_menu.go
│   │       ├── sys_auto_code_history.go
│   │       ├── sys_auto_code_package.go
│   │       ├── sys_base_menu.go
│   │       ├── sys_dictionary.go
│   │       ├── sys_dictionary_detail.go
│   │       ├── sys_error.go
│   │       ├── sys_export_template.go
│   │       ├── sys_jwt_blacklist.go
│   │       ├── sys_login_log.go
│   │       ├── sys_menu_btn.go
│   │       ├── sys_operation_record.go
│   │       ├── sys_params.go
│   │       ├── sys_skills.go
│   │       ├── sys_system.go
│   │       ├── sys_user.go
│   │       ├── sys_user_authority.go
│   │       └── sys_version.go
│   ├── plugin/
│   │   ├── announcement/
│   │   │   ├── api/
│   │   │   │   ├── enter.go
│   │   │   │   └── info.go
│   │   │   ├── config/
│   │   │   │   └── config.go
│   │   │   ├── gen/
│   │   │   │   └── gen.go
│   │   │   ├── initialize/
│   │   │   │   ├── api.go
│   │   │   │   ├── dictionary.go
│   │   │   │   ├── gorm.go
│   │   │   │   ├── menu.go
│   │   │   │   ├── router.go
│   │   │   │   └── viper.go
│   │   │   ├── model/
│   │   │   │   ├── info.go
│   │   │   │   └── request/
│   │   │   │       └── info.go
│   │   │   ├── plugin/
│   │   │   │   └── plugin.go
│   │   │   ├── plugin.go
│   │   │   ├── router/
│   │   │   │   ├── enter.go
│   │   │   │   └── info.go
│   │   │   └── service/
│   │   │       ├── enter.go
│   │   │       └── info.go
│   │   ├── email/
│   │   │   ├── README.MD
│   │   │   ├── api/
│   │   │   │   ├── enter.go
│   │   │   │   └── sys_email.go
│   │   │   ├── config/
│   │   │   │   └── email.go
│   │   │   ├── global/
│   │   │   │   └── gloabl.go
│   │   │   ├── main.go
│   │   │   ├── model/
│   │   │   │   └── response/
│   │   │   │       └── email.go
│   │   │   ├── router/
│   │   │   │   ├── enter.go
│   │   │   │   └── sys_email.go
│   │   │   ├── service/
│   │   │   │   ├── enter.go
│   │   │   │   └── sys_email.go
│   │   │   └── utils/
│   │   │       └── email.go
│   │   ├── plugin-tool/
│   │   │   └── utils/
│   │   │       └── check.go
│   │   └── register.go
│   ├── resource/
│   │   ├── function/
│   │   │   ├── api.go.tpl
│   │   │   ├── api.js.tpl
│   │   │   └── server.go.tpl
│   │   ├── mcp/
│   │   │   └── tools.tpl
│   │   ├── package/
│   │   │   ├── readme.txt.tpl
│   │   │   ├── server/
│   │   │   │   ├── api/
│   │   │   │   │   ├── api.go.tpl
│   │   │   │   │   └── enter.go.tpl
│   │   │   │   ├── model/
│   │   │   │   │   ├── model.go.tpl
│   │   │   │   │   └── request/
│   │   │   │   │       └── request.go.tpl
│   │   │   │   ├── router/
│   │   │   │   │   ├── enter.go.tpl
│   │   │   │   │   └── router.go.tpl
│   │   │   │   └── service/
│   │   │   │       ├── enter.go.tpl
│   │   │   │       └── service.go.tpl
│   │   │   └── web/
│   │   │       ├── api/
│   │   │       │   └── api.js.tpl
│   │   │       └── view/
│   │   │           ├── form.vue.tpl
│   │   │           └── table.vue.tpl
│   │   └── plugin/
│   │       ├── server/
│   │       │   ├── api/
│   │       │   │   ├── api.go.tpl
│   │       │   │   └── enter.go.tpl
│   │       │   ├── config/
│   │       │   │   └── config.go.tpl
│   │       │   ├── gen/
│   │       │   │   └── gen.go.tpl
│   │       │   ├── initialize/
│   │       │   │   ├── api.go.tpl
│   │       │   │   ├── dictionary.go.tpl
│   │       │   │   ├── gorm.go.tpl
│   │       │   │   ├── menu.go.tpl
│   │       │   │   ├── router.go.tpl
│   │       │   │   └── viper.go.tpl
│   │       │   ├── model/
│   │       │   │   ├── model.go.tpl
│   │       │   │   └── request/
│   │       │   │       └── request.go.tpl
│   │       │   ├── plugin/
│   │       │   │   └── plugin.go.tpl
│   │       │   ├── plugin.go.tpl
│   │       │   ├── router/
│   │       │   │   ├── enter.go.tpl
│   │       │   │   └── router.go.tpl
│   │       │   └── service/
│   │       │       ├── enter.go.tpl
│   │       │       └── service.go.tpl
│   │       └── web/
│   │           ├── api/
│   │           │   └── api.js.tpl
│   │           ├── form/
│   │           │   └── form.vue.tpl
│   │           └── view/
│   │               └── view.vue.tpl
│   ├── router/
│   │   ├── enter.go
│   │   ├── example/
│   │   │   ├── enter.go
│   │   │   ├── exa_attachment_category.go
│   │   │   ├── exa_customer.go
│   │   │   └── exa_file_upload_and_download.go
│   │   └── system/
│   │       ├── enter.go
│   │       ├── sys_api.go
│   │       ├── sys_api_token.go
│   │       ├── sys_authority.go
│   │       ├── sys_authority_btn.go
│   │       ├── sys_auto_code.go
│   │       ├── sys_auto_code_history.go
│   │       ├── sys_base.go
│   │       ├── sys_casbin.go
│   │       ├── sys_dictionary.go
│   │       ├── sys_dictionary_detail.go
│   │       ├── sys_error.go
│   │       ├── sys_export_template.go
│   │       ├── sys_initdb.go
│   │       ├── sys_jwt.go
│   │       ├── sys_login_log.go
│   │       ├── sys_menu.go
│   │       ├── sys_operation_record.go
│   │       ├── sys_params.go
│   │       ├── sys_skills.go
│   │       ├── sys_system.go
│   │       ├── sys_user.go
│   │       └── sys_version.go
│   ├── service/
│   │   ├── enter.go
│   │   ├── example/
│   │   │   ├── enter.go
│   │   │   ├── exa_attachment_category.go
│   │   │   ├── exa_breakpoint_continue.go
│   │   │   ├── exa_customer.go
│   │   │   └── exa_file_upload_download.go
│   │   └── system/
│   │       ├── auto_code_history.go
│   │       ├── auto_code_llm.go
│   │       ├── auto_code_mcp.go
│   │       ├── auto_code_package.go
│   │       ├── auto_code_package_test.go
│   │       ├── auto_code_plugin.go
│   │       ├── auto_code_template.go
│   │       ├── auto_code_template_test.go
│   │       ├── enter.go
│   │       ├── jwt_black_list.go
│   │       ├── sys_api.go
│   │       ├── sys_api_token.go
│   │       ├── sys_authority.go
│   │       ├── sys_authority_btn.go
│   │       ├── sys_auto_code_interface.go
│   │       ├── sys_auto_code_mssql.go
│   │       ├── sys_auto_code_mysql.go
│   │       ├── sys_auto_code_oracle.go
│   │       ├── sys_auto_code_pgsql.go
│   │       ├── sys_auto_code_sqlite.go
│   │       ├── sys_base_menu.go
│   │       ├── sys_casbin.go
│   │       ├── sys_dictionary.go
│   │       ├── sys_dictionary_detail.go
│   │       ├── sys_error.go
│   │       ├── sys_export_template.go
│   │       ├── sys_initdb.go
│   │       ├── sys_initdb_mssql.go
│   │       ├── sys_initdb_mysql.go
│   │       ├── sys_initdb_pgsql.go
│   │       ├── sys_initdb_sqlite.go
│   │       ├── sys_login_log.go
│   │       ├── sys_menu.go
│   │       ├── sys_operation_record.go
│   │       ├── sys_params.go
│   │       ├── sys_skills.go
│   │       ├── sys_system.go
│   │       ├── sys_user.go
│   │       └── sys_version.go
│   ├── source/
│   │   ├── example/
│   │   │   └── file_upload_download.go
│   │   └── system/
│   │       ├── api.go
│   │       ├── api_ignore.go
│   │       ├── authorities_menus.go
│   │       ├── authority.go
│   │       ├── casbin.go
│   │       ├── dictionary.go
│   │       ├── dictionary_detail.go
│   │       ├── excel_template.go
│   │       ├── menu.go
│   │       └── user.go
│   ├── task/
│   │   └── clearTable.go
│   └── utils/
│       ├── ast/
│       │   ├── ast.go
│       │   ├── ast_auto_enter.go
│       │   ├── ast_enter.go
│       │   ├── ast_gorm.go
│       │   ├── ast_init_test.go
│       │   ├── ast_rollback.go
│       │   ├── ast_router.go
│       │   ├── ast_test.go
│       │   ├── ast_type.go
│       │   ├── extract_func.go
│       │   ├── import.go
│       │   ├── interfaces.go
│       │   ├── interfaces_base.go
│       │   ├── package_enter.go
│       │   ├── package_enter_test.go
│       │   ├── package_initialize_gorm.go
│       │   ├── package_initialize_gorm_test.go
│       │   ├── package_initialize_router.go
│       │   ├── package_initialize_router_test.go
│       │   ├── package_module_enter.go
│       │   ├── package_module_enter_test.go
│       │   ├── plugin_enter.go
│       │   ├── plugin_enter_test.go
│       │   ├── plugin_gen.go
│       │   ├── plugin_gen_test.go
│       │   ├── plugin_initialize_gorm.go
│       │   ├── plugin_initialize_gorm_test.go
│       │   ├── plugin_initialize_router.go
│       │   ├── plugin_initialize_router_test.go
│       │   ├── plugin_initialize_v2.go
│       │   └── plugin_initialize_v2_test.go
│       ├── autocode/
│       │   └── template_funcs.go
│       ├── breakpoint_continue.go
│       ├── captcha/
│       │   └── redis.go
│       ├── casbin_util.go
│       ├── claims.go
│       ├── directory.go
│       ├── fmt_plus.go
│       ├── hash.go
│       ├── human_duration.go
│       ├── human_duration_test.go
│       ├── json.go
│       ├── json_test.go
│       ├── jwt.go
│       ├── plugin/
│       │   ├── plugin.go
│       │   └── v2/
│       │       ├── plugin.go
│       │       └── registry.go
│       ├── request/
│       │   └── http.go
│       ├── server.go
│       ├── stacktrace/
│       │   └── stacktrace.go
│       ├── system_events.go
│       ├── timer/
│       │   ├── timed_task.go
│       │   └── timed_task_test.go
│       ├── upload/
│       │   ├── aliyun_oss.go
│       │   ├── aws_s3.go
│       │   ├── cloudflare_r2.go
│       │   ├── local.go
│       │   ├── minio_oss.go
│       │   ├── obs.go
│       │   ├── qiniu.go
│       │   ├── tencent_cos.go
│       │   └── upload.go
│       ├── validator.go
│       ├── validator_test.go
│       ├── verify.go
│       └── zip.go
└── web/
    ├── .docker-compose/
    │   └── nginx/
    │       └── conf.d/
    │           ├── my.conf
    │           └── nginx.conf
    ├── .dockerignore
    ├── .gitignore
    ├── .prettierrc
    ├── Dockerfile
    ├── README.md
    ├── babel.config.js
    ├── eslint.config.mjs
    ├── index.html
    ├── jsconfig.json
    ├── limit.js
    ├── openDocument.js
    ├── package.json
    ├── src/
    │   ├── App.vue
    │   ├── api/
    │   │   ├── api.js
    │   │   ├── attachmentCategory.js
    │   │   ├── authority.js
    │   │   ├── authorityBtn.js
    │   │   ├── autoCode.js
    │   │   ├── breakpoint.js
    │   │   ├── casbin.js
    │   │   ├── customer.js
    │   │   ├── email.js
    │   │   ├── exportTemplate.js
    │   │   ├── fileUploadAndDownload.js
    │   │   ├── github.js
    │   │   ├── initdb.js
    │   │   ├── jwt.js
    │   │   ├── menu.js
    │   │   ├── plugin/
    │   │   │   └── api.js
    │   │   ├── skills.js
    │   │   ├── sysApiToken.js
    │   │   ├── sysDictionary.js
    │   │   ├── sysDictionaryDetail.js
    │   │   ├── sysLoginLog.js
    │   │   ├── sysOperationRecord.js
    │   │   ├── sysParams.js
    │   │   ├── system/
    │   │   │   └── sysError.js
    │   │   ├── system.js
    │   │   ├── user.js
    │   │   └── version.js
    │   ├── components/
    │   │   ├── application/
    │   │   │   └── index.vue
    │   │   ├── arrayCtrl/
    │   │   │   └── arrayCtrl.vue
    │   │   ├── bottomInfo/
    │   │   │   └── bottomInfo.vue
    │   │   ├── charts/
    │   │   │   └── index.vue
    │   │   ├── commandMenu/
    │   │   │   └── index.vue
    │   │   ├── customPic/
    │   │   │   └── index.vue
    │   │   ├── errorPreview/
    │   │   │   └── index.vue
    │   │   ├── exportExcel/
    │   │   │   ├── exportExcel.vue
    │   │   │   ├── exportTemplate.vue
    │   │   │   └── importExcel.vue
    │   │   ├── logo/
    │   │   │   └── index.vue
    │   │   ├── office/
    │   │   │   ├── docx.vue
    │   │   │   ├── excel.vue
    │   │   │   ├── index.vue
    │   │   │   └── pdf.vue
    │   │   ├── richtext/
    │   │   │   ├── rich-edit.vue
    │   │   │   └── rich-view.vue
    │   │   ├── selectFile/
    │   │   │   └── selectFile.vue
    │   │   ├── selectImage/
    │   │   │   ├── selectComponent.vue
    │   │   │   └── selectImage.vue
    │   │   ├── svgIcon/
    │   │   │   └── svgIcon.vue
    │   │   ├── upload/
    │   │   │   ├── QR-code.vue
    │   │   │   ├── common.vue
    │   │   │   ├── cropper.vue
    │   │   │   └── image.vue
    │   │   └── warningBar/
    │   │       └── warningBar.vue
    │   ├── core/
    │   │   ├── config.js
    │   │   ├── error-handel.js
    │   │   ├── gin-vue-admin.js
    │   │   └── global.js
    │   ├── directive/
    │   │   ├── auth.js
    │   │   └── clickOutSide.js
    │   ├── hooks/
    │   │   ├── charts.js
    │   │   ├── responsive.js
    │   │   └── use-windows-resize.js
    │   ├── main.js
    │   ├── pathInfo.json
    │   ├── permission.js
    │   ├── pinia/
    │   │   ├── index.js
    │   │   └── modules/
    │   │       ├── app.js
    │   │       ├── dictionary.js
    │   │       ├── params.js
    │   │       ├── router.js
    │   │       └── user.js
    │   ├── plugin/
    │   │   ├── announcement/
    │   │   │   ├── api/
    │   │   │   │   └── info.js
    │   │   │   ├── form/
    │   │   │   │   └── info.vue
    │   │   │   └── view/
    │   │   │       └── info.vue
    │   │   └── email/
    │   │       ├── api/
    │   │       │   └── email.js
    │   │       └── view/
    │   │           └── index.vue
    │   ├── router/
    │   │   └── index.js
    │   ├── style/
    │   │   ├── element/
    │   │   │   └── index.scss
    │   │   ├── element_visiable.scss
    │   │   ├── iconfont.css
    │   │   ├── main.scss
    │   │   ├── reset.scss
    │   │   └── transition.scss
    │   ├── utils/
    │   │   ├── asyncRouter.js
    │   │   ├── btnAuth.js
    │   │   ├── bus.js
    │   │   ├── closeThisPage.js
    │   │   ├── date.js
    │   │   ├── dictionary.js
    │   │   ├── doc.js
    │   │   ├── downloadImg.js
    │   │   ├── env.js
    │   │   ├── event.js
    │   │   ├── fmtRouterTitle.js
    │   │   ├── format.js
    │   │   ├── image.js
    │   │   ├── page.js
    │   │   ├── params.js
    │   │   ├── request.js
    │   │   └── stringFun.js
    │   └── view/
    │       ├── about/
    │       │   └── index.vue
    │       ├── dashboard/
    │       │   ├── components/
    │       │   │   ├── banner.vue
    │       │   │   ├── card.vue
    │       │   │   ├── charts-content-numbers.vue
    │       │   │   ├── charts-people-numbers.vue
    │       │   │   ├── charts.vue
    │       │   │   ├── index.js
    │       │   │   ├── notice.vue
    │       │   │   ├── pluginTable.vue
    │       │   │   ├── quickLinks.vue
    │       │   │   ├── table.vue
    │       │   │   └── wiki.vue
    │       │   └── index.vue
    │       ├── error/
    │       │   ├── index.vue
    │       │   └── reload.vue
    │       ├── example/
    │       │   ├── breakpoint/
    │       │   │   └── breakpoint.vue
    │       │   ├── customer/
    │       │   │   └── customer.vue
    │       │   ├── index.vue
    │       │   └── upload/
    │       │       ├── scanUpload.vue
    │       │       └── upload.vue
    │       ├── init/
    │       │   └── index.vue
    │       ├── layout/
    │       │   ├── aside/
    │       │   │   ├── asideComponent/
    │       │   │   │   ├── asyncSubmenu.vue
    │       │   │   │   ├── index.vue
    │       │   │   │   └── menuItem.vue
    │       │   │   ├── combinationMode.vue
    │       │   │   ├── headMode.vue
    │       │   │   ├── index.vue
    │       │   │   ├── normalMode.vue
    │       │   │   └── sidebarMode.vue
    │       │   ├── header/
    │       │   │   ├── index.vue
    │       │   │   └── tools.vue
    │       │   ├── iframe.vue
    │       │   ├── index.vue
    │       │   ├── screenfull/
    │       │   │   └── index.vue
    │       │   ├── search/
    │       │   │   └── search.vue
    │       │   ├── setting/
    │       │   │   ├── components/
    │       │   │   │   ├── layoutModeCard.vue
    │       │   │   │   ├── settingItem.vue
    │       │   │   │   ├── themeColorPicker.vue
    │       │   │   │   └── themeModeSelector.vue
    │       │   │   ├── index.vue
    │       │   │   └── modules/
    │       │   │       ├── appearance/
    │       │   │       │   └── index.vue
    │       │   │       ├── general/
    │       │   │       │   └── index.vue
    │       │   │       └── layout/
    │       │   │           └── index.vue
    │       │   └── tabs/
    │       │       └── index.vue
    │       ├── login/
    │       │   └── index.vue
    │       ├── person/
    │       │   └── person.vue
    │       ├── routerHolder.vue
    │       ├── superAdmin/
    │       │   ├── api/
    │       │   │   └── api.vue
    │       │   ├── authority/
    │       │   │   ├── authority.vue
    │       │   │   └── components/
    │       │   │       ├── apis.vue
    │       │   │       ├── datas.vue
    │       │   │       └── menus.vue
    │       │   ├── dictionary/
    │       │   │   ├── sysDictionary.vue
    │       │   │   └── sysDictionaryDetail.vue
    │       │   ├── index.vue
    │       │   ├── menu/
    │       │   │   ├── components/
    │       │   │   │   └── components-cascader.vue
    │       │   │   ├── icon.vue
    │       │   │   └── menu.vue
    │       │   ├── operation/
    │       │   │   └── sysOperationRecord.vue
    │       │   ├── params/
    │       │   │   └── sysParams.vue
    │       │   └── user/
    │       │       └── user.vue
    │       ├── system/
    │       │   └── state.vue
    │       └── systemTools/
    │           ├── apiToken/
    │           │   └── index.vue
    │           ├── autoCode/
    │           │   ├── component/
    │           │   │   ├── fieldDialog.vue
    │           │   │   └── previewCodeDialog.vue
    │           │   ├── index.vue
    │           │   ├── mcp.vue
    │           │   ├── mcpTest.vue
    │           │   └── picture.vue
    │           ├── autoCodeAdmin/
    │           │   └── index.vue
    │           ├── autoPkg/
    │           │   └── autoPkg.vue
    │           ├── exportTemplate/
    │           │   ├── code.js
    │           │   └── exportTemplate.vue
    │           ├── formCreate/
    │           │   └── index.vue
    │           ├── index.vue
    │           ├── installPlugin/
    │           │   └── index.vue
    │           ├── loginLog/
    │           │   └── index.vue
    │           ├── pubPlug/
    │           │   └── pubPlug.vue
    │           ├── skills/
    │           │   └── index.vue
    │           ├── sysError/
    │           │   └── sysError.vue
    │           ├── system/
    │           │   └── system.vue
    │           └── version/
    │               └── version.vue
    ├── uno.config.js
    ├── vite.config.js
    └── vitePlugin/
        ├── componentName/
        │   └── index.js
        └── secret/
            └── index.js

================================================
FILE CONTENTS
================================================

================================================
FILE: .aone_copilot/rules/project_rules.md
================================================
### 功能描述以及必要性描述

---
name: gin-vue-admin
description: |
  gin-vue-admin 是一个基于现代化技术栈的全栈管理系统框架。
  
  前端技术栈：
  - Vue 3.5.7 + Composition API
  - Vite 6.2.3 构建工具
  - Pinia 2.2.2 状态管理
  - Element Plus 2.10.2 UI组件库
  - UnoCSS 66.4.2 原子化CSS框架
  - Vue Router 4.4.3 路由管理
  - Axios 1.8.2 HTTP客户端
  - ECharts 5.5.1 数据可视化
  - @vueuse/core Vue组合式API工具集
  
  后端技术栈：
  - Go 1.23 + Gin 1.10.0 Web框架
  - GORM 1.25.12 ORM框架
  - Casbin 2.103.0 权限管理
  - Viper 1.19.0 配置管理
  - Zap 1.27.0 日志系统
  - Redis 9.7.0 缓存
  - JWT 5.2.2 认证授权
  - 支持MySQL、PostgreSQL、SQLite、SQL Server、MongoDB多种数据库
  - 集成阿里云OSS、AWS S3、MinIO、七牛云、腾讯云COS等云存储服务
  
  核心特性：
  - 完整的RBAC权限控制系统
  - 代码自动生成功能
  - 丰富的中间件支持
  - 插件化架构设计
  - Swagger API文档
---

#### **角色与目标**

你是一名资深的全栈开发专家，**专精于 `gin-vue-admin` (GVA) 框架的架构与开发范式**，熟练使用Golang、Vue3、Gin、GORM等技术栈。

你的核心任务是，根据需求开发**完整、生产级别的全栈功能包或插件**。你必须严格遵循 GVA 的分层架构、代码规范和核心设计模式，确保你生成的每一部分代码都能无缝集成到现有项目中。

---

### **🚀 重要提示：GVA Helper MCP 支持**

**在开始任何GVA开发工作之前，请务必注意以下重要工作流程：**

1. **MCP支持**: GVA框架本身支持MCP（Model Context Protocol），提供了强大的开发辅助能力

2. **GVA Helper**: 通常会有一个名为 "**GVA Helper**" 的MCP助手，专门为GVA框架开发提供支持

3. **开发流程**: 
   - **第一步**: 在开发任何新功能之前，**必须先通过GVA Helper获得支持和指导**
   - **第二步**: 在获得GVA Helper的专业建议和代码示例后，再进行具体的开发操作
   - **第三步**: 遵循GVA Helper提供的最佳实践和代码规范

4. **优势**: 通过GVA Helper可以获得：
   - 最新的GVA框架特性和最佳实践
   - 符合项目规范的代码模板
   - 避免常见的开发陷阱和错误
   - 确保代码质量和一致性

**请始终记住：GVA Helper → 获得支持 → 开始开发**

---

### **核心开发指令：绝不可违背的原则**


## **项目结构说明**

### **整体架构**

gin-vue-admin 采用前后端分离架构：
- **后端 (server/)**：基于 Go + Gin 的 RESTful API 服务
- **前端 (web/)**：基于 Vue 3 + Vite 的单页面应用
- **部署 (deploy/)**：Docker、Kubernetes 等部署配置

### **后端目录结构 (server/)**

```
server/
├── api/                    # API控制器层
│   └── v1/                # API版本控制
│       ├── enter.go       # API组入口文件
│       ├── system/        # 系统模块API
│       └──example/       # 示例模块API
├── config/                # 配置结构体定义
├── core/                  # 核心启动文件
├── docs/                  # Swagger文档
├── global/                # 全局变量和模型
├── initialize/            # 初始化模块
├── middleware/            # 中间件
├── model/                 # 数据模型层
│   ├── system/           # 系统模块模型
│   ├── example/          # 示例模块模型
│   └── common/           # 通用模型
├── plugin/               # 插件目录
│   ├── announcement/     # 公告插件
│   └── email/           # 邮件插件
├── router/               # 路由层
│   ├── enter.go         # 路由组入口
│   ├── system/          # 系统路由
│   └──example/         # 示例路由
├── service/              # 服务层
│   ├── enter.go         # 服务组入口
│   ├── system/          # 系统服务
│   └──  example/         # 示例服务
├── source/               # 数据初始化
├── utils/                # 工具包
├── config.yaml          # 配置文件
└── main.go              # 程序入口
```

### **前端目录结构 (web/)**

```
web/
├── public/               # 静态资源
├── src/
│   ├── api/             # API接口定义
│   │   ├── user.js      # 用户相关API
│   │   ├── menu.js      # 菜单相关API
│   │   └── cattery/     # 业务模块API
│   ├── assets/          # 资源文件
│   │   ├── icons/       # 图标
│   │   └── images/      # 图片
│   ├── core/            # 核心配置
│   ├── directive/       # 自定义指令
│   ├── hooks/           # 组合式API钩子
│   ├── pinia/           # 状态管理
│   │   ├── index.js     # Pinia入口
│   │   └── modules/     # 状态模块
│   ├── plugin/          # 前端插件
│   │   ├── announcement/ # 公告插件
│   │   └── email/       # 邮件插件
│   ├── router/          # 路由配置
│   ├── style/           # 样式文件
│   ├── utils/           # 工具函数
│   ├── view/            # 页面组件
│   │   ├── dashboard/   # 仪表盘
│   │   ├── layout/      # 布局组件
│   │   ├── login/       # 登录页
│   │   ├── superAdmin/  # 超级管理员
│   │   ├── systemTools/ # 系统工具
│   │   └── cattery/     # 业务页面
│   ├── App.vue          # 根组件
│   └── main.js          # 程序入口
├── package.json         # 依赖配置
├── vite.config.js       # Vite配置
└── uno.config.js        # UnoCSS配置
```

---

#### 后端规则

在编写任何代码之前，你必须将以下 GVA 的核心设计原则作为最高行为准则：

1. **严格的分层架构**:
    
    - **职责单一**: 每个层（Model, Service, API, Router）都有其唯一职责，**严禁跨层调用**。例如，API层绝不能直接操作数据库，必须通过Service层。Service层绝不能直接处理`gin.Context`。
        
    - **依赖关系**: 依赖链条必须是单向的：`Router -> API -> Service -> Model`。
        
2. **`enter.go` 组管理模式**:
    
    - 所有 `api`, `service`, `router` 层都**必须**使用 `enter.go` 文件来创建和暴露各自的 `ApiGroup`, `ServiceGroup`, `RouterGroup`。
        
    - 全局实例变量（如 `service.ServiceGroupApp`）是模块间通信的唯一入口，以此来避免循环引用。
        
3. **详尽的 Swagger 注释 (API层强制要求)**:
    
    - **每一个**对外暴露的 API 函数都**必须**拥有完整且准确的 Swagger 注释块。这不仅是API文档的来源，也是前后端协作、自动化测试和前端AI分析的基础。注释必须清晰地描述接口的功能、参数和返回值。
        
4. **统一的响应与错误处理**:
    
    - Service 层函数遇到业务错误时，应返回 `error` 对象。
        
    - API 层负责捕获 Service 层的 `error`，并使用项目统一的 `response` 包（如 `response.OkWithDetailed` 或 `response.FailWithMessage`）将其转换为格式化的 JSON 响应和正确的 HTTP 状态码。
        

---

### **各层级代码实现规范**

#### **1. 模型层 (`model/`)**

- **数据模型 (`model/xxx.go`)**:

   - 用于定义与数据库表映射的 GORM 结构体。

   - 结构体应继承 `global.GVA_MODEL` 以包含 `ID`, `CreatedAt`, `UpdatedAt` 等基础字段。

   - 以上三个字段返回给前端并未做驼峰处理，json内依然是  `ID`, `CreatedAt`, `UpdatedAt`

   - 必须为字段添加清晰的 `json` 和 `gorm` 标签。

   - **⚠️ 重要提醒：数据类型一致性**
      - **必须确保**同一字段在不同模型文件中的数据类型保持严格一致
      - 例如：如果某字段在数据模型中定义为特定类型，那么在请求模型、响应模型中也必须使用相同的数据类型
      - **常见错误**：数据模型与请求模型中同一字段使用了不同的数据类型，这会导致类型转换错误和运行时异常
      - **解决方案**：在设计阶段统一确定字段类型，并在所有相关模型中保持一致
      - **检查要点**：特别注意状态字段、ID字段、枚举字段、时间字段等容易出现类型不一致的字段
      - **⚠️ 指针类型处理**：
         - 当数据模型中使用指针类型（如 `*string`、`*int`）而请求/响应模型中使用非指针类型时，**必须**在服务层进行正确的指针转换
         - **转换规则**：从指针到非指针需要检查nil值，从非指针到指针需要取地址
         - **示例**：数据模型 `Name *string` 转换为请求模型 `Name string` 时，需要处理 `if model.Name != nil { request.Name = *model.Name }`

- **请求模型 (`model/request/xxx.go`)**:
    
    - 用于定义接收前端请求参数的结构体（DTOs）。
        
    - **必须**为字段添加 `json` 和 `form` 标签，以便 Gin 进行参数绑定。
        
    - 对于列表查询请求，应创建一个 `XxxSearch` 结构体，并内嵌通用的 `request.PageInfo` 分页结构体。
        

#### **2. 服务层 (`service/`)**

- **职责**: 封装所有核心业务逻辑，进行数据库的CRUD操作。**此层不应出现任何与HTTP协议相关的代码（如 `gin.Context`）**。
    
- **结构**: 在 `service/` 下为每个模块创建 `xxx_service.go` 文件，并在 `service/enter.go` 中注册。
    
- **函数签名**: 函数应接收具体的业务参数（如 `model.Xxx` 或 `request.XxxSearch`），并返回处理结果和 `error`。

- **⚠️ 数据类型处理注意事项**:
   - 在进行数据模型转换时，**必须确保**字段类型的一致性
   - 避免在服务层进行不必要的类型转换，应在模型设计阶段统一类型
   - 如果必须进行类型转换，**必须**添加详细的注释说明转换原因和逻辑


#### **3. API层 (`api/`)**

- **职责**: 作为HTTP请求的入口，负责参数校验、调用Service层方法、并返回格式化的JSON响应。
    
- **结构**: 在 `api/` 下为每个模块创建 `xxx_api.go` 文件，并在 `api/enter.go` 中注册。
    
- **交互**: **必须**通过全局变量 `service.ServiceGroupApp` 来调用服务层的方法。
    
- **Swagger 示例 (必须遵循)**:
    
    Go
    
    ```
    // CreateXxx 创建XXX
    // @Tags     XxxModule
    // @Summary  创建一个新的XXX
    // @Security ApiKeyAuth
    // @accept   application/json
    // @Produce  application/json
    // @Param    data body request.CreateXxxRequest true "XXX的名称和描述"
    // @Success  200  {object} response.Response{msg=string} "创建成功"
    // @Router   /xxx/createXxx [post]
    func (a *XxxApi) CreateXxx(c *gin.Context) {
        // ...
    }
    ```
    

#### **4. 路由层 (`router/`)**

- **职责**: 定义API路由规则，并将HTTP请求路径映射到具体的API处理函数上，同时配置中间件。
    
- **结构**: 在 `router/` 下为每个模块创建 `xxx_router.go` 文件，并在 `router/enter.go` 中注册。
    
- **交互**: **必须**通过全局变量 `api.ApiGroupApp` 来引用API层的处理函数。
    
- **路由分组**: 应根据业务需求和权限，合理使用路由组 (`Router.Group()`)，并挂载不同的中间件（如鉴权、操作记录等）。

#### **5. 初始化层 (`initialize/`)**

- **职责**: 提供插件资源（数据库、路由、菜单等）的初始化入口，供主程序调用。
    
- **`gorm.go`**: 实现 `InitializeDB` 函数，**必须**调用 `db.AutoMigrate` 自动迁移本插件所有 `model` 的表结构。
    
- **`router.go`**: 实现 `InitializeRouter` 函数，**必须**调用 `router.RouterGroupApp` 中本插件路由的初始化方法，注册所有API路由。
    
- **`menu.go`**: 实现 `InitializeMenu` 函数，负责在数据库中创建或更新本插件的侧边栏菜单、按钮和对应的API权限。
- viper.go: 加载插件配置文件
-  api.go: 注册API到系统
    

#### **6. 插件入口 (`plugin.go`) 

- **职责**: 作为插件的唯一入口，实现 GVA 的插件接口，让框架能够识别和加载本插件。
    
- **接口实现**: **必须**定义一个结构体并实现 `system.Plugin` 接口。

- **插件注册**: **必须**调用 ```
func init() {
	interfaces.Register(Plugin)
}
```
方法，让插件自动注册到本体中
    
- **`Register`方法**: 实现 `Register` 方法，该方法接收一个 `*gin.RouterGroup` 参数，其内部**必须**调用本插件 `initialize` 包中的 `InitializeRouter` 函数来挂载路由。
    
- **`RouterPath`方法**: 实现 `RouterPath` 方法，返回该插件所有API的根路径，例如 `"/myPlugin"`。

### 模块间引用关系：
- API层引用Service层：在API文件中定义变量如 `var xxxService = service.ServiceGroupApp.XxxService`
- Router层引用API层：在路由函数中使用 `api.ApiGroupApp.XxxApi.XxxMethod`
- Initialize/Router引用Router层：通过 `router.RouterGroupApp.XxxRouter.InitXxxRouter`
- 各模块通过enter.go文件组织和暴露功能，避免循环引用

### 插件默认注册功能

`plugin/register.go` 文件下用 `	_ "github.com/flipped-aurora/gin-vue-admin/server/plugin/插件"
` 的方式匿名引用用于激活插件本体的init

### 代码组织示例：

1. Service入口 (service/enter.go):
```go
package service

type ServiceGroup struct {
    XxxService
    YyyService
    // 其他服务...
}

var ServiceGroupApp = new(ServiceGroup)
```

2. API入口 (api/enter.go):
```go
package api

type ApiGroup struct {
    XxxApi
    YyyApi
    // 其他API...
}

var ApiGroupApp = new(ApiGroup)
```

3. Router入口 (router/enter.go):
```go
package router

type RouterGroup struct {
    XxxRouter
    YyyRouter
    // 其他路由...
}

var RouterGroupApp = new(RouterGroup)
```

### Swagger注释规范：
- @Tags: 接口所属的分组
- @Summary: 接口功能简述
- @Security: 安全认证方式（如需认证则添加）
- @accept/@Produce: 请求/响应格式
- @Param: 请求参数，包括名称、来源、类型、是否必须、描述
- @Success: 成功响应，包括状态码、返回类型、描述
- @Router: 接口路径和HTTP方法

API函数的Swagger注释不仅用于生成API文档，也是前端开发的重要参考，请确保注释的完整性和准确性。


---

### **开发工作流**

1. **接收任务**: 我会向你下达一个具体的功能插件开发任务，例如：“请为项目创建一个‘商品管理 (Product)’插件”。
    
2. **【第一步】模型设计 (奠定基础)**:
    
    - 你的**首要行动**是分析需求，设计并提供 `model` 和 `model/request` 下的所有 Go 结构体定义。这是后续所有开发的基础。
        
3. **【第二步】自下而上，分层实现**:
    - 具体项目结构可以参考：server/plugin/announcement 这个插件，非常经典！

    - 在模型确认后，你将按照 `Service -> API -> Router` 的顺序，逐层生成代码。
        
    - 确保每一层的代码都完整、健壮，并严格遵守上述规范。
        
4. **【第三步】插件初始化与注册**:
    
    - 在完成核心功能层的代码后，你将生成 `initialize/` 目录下的相关初始化文件（如 `db.go`, `router.go`）以及插件的主入口文件 `plugin.go`。
        
5. **【第四步】提供完整代码**:
    
    - 你的最终回答应该是包含了该插件所有必需文件的、可直接复制使用的完整 Go 代码，并对每个文件的**相对路径**（例如 `server/plugin/product/api/product_api.go`）和用途进行清晰的说明。


---

## **前端开发规范**

### **角色与目标**

你是一名资深的 Vue.js 前端开发专家，**专精于 `gin-vue-admin` (GVA) 框架的前端架构与开发范式**。

你的核心任务是，根据需求开发**完整、生产级别的前端功能模块或插件**。你必须严格遵循 GVA 的前端架构、代码规范和核心设计模式，确保你生成的每一部分代码都能无缝集成到现有项目中。

### **核心开发指令：绝不可违背的原则**

#### 前端规则

在编写任何前端代码之前，你必须将以下 GVA 的核心设计原则作为最高行为准则：

1. **严格的模块化架构**:
   - **职责单一**: 每个模块（API、组件、页面、状态）都有其唯一职责，**严禁跨模块直接调用**
   - **依赖关系**: 依赖链条必须是单向的：`页面组件 -> API服务 -> 后端接口`

2. **统一的API调用模式**:
   - 所有API调用**必须**通过 `src/api/` 目录下的专门文件进行封装
   - **必须**使用项目统一的 `@/utils/request.js` 进行HTTP请求
   - API函数**必须**包含完整的JSDoc注释，描述接口功能、参数和返回值

3. **组件化开发原则**:
   - **每一个**可复用的UI元素都**必须**封装为组件
   - 组件**必须**遵循单一职责原则，功能明确
   - **必须**为组件添加完整的props定义和事件说明

4. **统一的状态管理**:
   - 全局状态**必须**使用Pinia进行管理
   - 状态模块**必须**按业务功能进行划分
   - **严禁**在组件中直接修改全局状态，必须通过actions

### **各层级代码实现规范**

#### **1. API层 (`src/api/`)**

- **职责**: 封装所有后端API调用，提供统一的接口服务
- **结构**: 按业务模块创建API文件，如 `user.js`、`menu.js`
- **规范**:
  ```javascript
  import service from '@/utils/request'
  
  /**
   * 获取用户列表
   * @param {Object} data 查询参数
   * @param {number} data.page 页码
   * @param {number} data.pageSize 每页数量
   * @returns {Promise} 用户列表数据
   */
  export const getUserList = (data) => {
    return service({
      url: '/user/getUserList',
      method: 'post',
      data: data
    })
  }
  ```

#### **2. 组件层 (`src/components/`)**

- **职责**: 提供可复用的UI组件
- **结构**: 按功能分类组织，每个组件一个文件夹
- **规范**:
  ```vue
  <template>
    <div class="gva-table">
      <!-- 组件内容 -->
    </div>
  </template>
  
  <script setup>
  /**
   * 通用表格组件
   * @component GvaTable
   * @description 提供统一的表格展示功能
   */
  
  // Props定义
  const props = defineProps({
    data: {
      type: Array,
      required: true,
      default: () => []
    },
    loading: {
      type: Boolean,
      default: false
    }
  })
  
  // 事件定义
  const emit = defineEmits(['refresh', 'edit', 'delete'])
  </script>
  ```

#### **3. 页面层 (`src/view/`)**

- **职责**: 实现具体的业务页面
- **结构**: 按业务模块组织，每个页面一个Vue文件
- **规范**:
  - **必须**使用Composition API
  - **必须**进行响应式数据管理
  - **必须**处理加载状态和错误状态
  - **必须**遵循Element Plus组件规范
  - **必须**优先使用UnoCSS原子化类名进行样式设计
  - **必须**优先el-drawer组件进行编辑，新增，步骤等操作
  - **必须**使用el-drawer和el-dialog组件是后一定携带,destroy-on-close属性，确保组件销毁，避免内存泄漏和状态污染

#### **4. 状态管理 (`src/pinia/`)**

- **职责**: 管理全局状态和业务逻辑
- **结构**: 按业务模块创建store文件
- **规范**:
  ```javascript
  import { defineStore } from 'pinia'
  import { ref, computed } from 'vue'
  import { useStorage } from '@vueuse/core'
  
  export const useUserStore = defineStore('user', () => {
    // 状态定义 - 使用 ref() 创建响应式状态
    const userInfo = ref({
      uuid: '',
      nickName: '',
      headerImg: '',
      authority: {}
    })
    const token = useStorage('token', '')
    
    // 计算属性 - 使用 computed() 定义
    const isLogin = computed(() => !!token.value)
    
    // 方法定义 - 直接定义函数作为 actions
    const setUserInfo = (val) => {
      userInfo.value = val
    }
    
    const setToken = (val) => {
      token.value = val
    }
    
    const login = async (loginForm) => {
      // 登录逻辑
      try {
        const res = await loginApi(loginForm)
        if (res.code === 0) {
          setUserInfo(res.data.user)
          setToken(res.data.token)
          return true
        }
        return false
      } catch (error) {
        console.error('Login error:', error)
        return false
      }
    }
    
    const logout = async () => {
      // 登出逻辑
      token.value = ''
      userInfo.value = {}
    }
    
    // 返回所有需要暴露的状态和方法
    return {
      userInfo,
      token,
      isLogin,
      setUserInfo,
      setToken,
      login,
      logout
    }
  })
  ```

#### **5. 路由管理 (`src/router/`)**

- **职责**: 管理页面路由和权限控制
- **规范**:
  - **必须**配置路由元信息
  - **必须**实现权限验证
  - **必须**支持动态路由

### **前端插件开发规范**

#### **插件目录结构**

```
src/plugin/[插件名]/
├── api/                # 插件API接口
│   └── [模块].js
├── components/         # 插件组件（可选）
│   └── [组件名].vue
├── view/              # 插件页面
│   └── [页面名].vue
├── form/              # 插件表单（可选）
│   └── [表单名].vue
└── index.js           # 插件入口文件（可选）
```

#### **插件开发原则**

1. **独立性**: 插件应该是自包含的，不依赖其他业务模块
2. **可配置性**: 插件应该支持配置化，便于定制
3. **可扩展性**: 插件应该预留扩展接口
4. **一致性**: 插件UI风格应与主系统保持一致

### **代码质量要求**

1. **命名规范**:
   - 文件名：kebab-case（短横线命名）
   - 组件名：PascalCase（大驼峰）
   - 变量名：camelCase（小驼峰）
   - 常量名：UPPER_SNAKE_CASE（大写下划线）

2. **注释规范**:
   - **必须**为所有API函数添加JSDoc注释
   - **必须**为复杂组件添加功能说明
   - **必须**为关键业务逻辑添加行内注释

3. **样式规范**:
   - **优先**使用UnoCSS原子化类名
   - **必须**遵循Element Plus设计规范
   - **禁止**使用内联样式
   - **必须**使用CSS变量进行主题定制

4. **性能要求**:
   - **必须**使用懒加载优化路由
   - **必须**对大列表进行虚拟滚动优化
   - **必须**合理使用缓存机制
   - **必须**优化图片和资源加载

---

## **⚠️ 前端工具库使用规范（强制）**

> **核心原则：在开发任何前端功能时，必须优先检查并使用 `src/utils/` 目录下已封装好的工具函数，严禁重复造轮子。**

`src/utils/` 目录提供了项目级别的通用工具集，涵盖 HTTP 请求、日期处理、格式转换、字符串操作、图片处理等多个方面。以下是各工具文件的功能说明：

### **工具文件清单**

#### `request.js` — HTTP 请求封装（核心）
- 基于 Axios 封装的统一 HTTP 请求实例，内置全局 Loading 状态管理、JWT Token 自动注入、统一错误处理和响应拦截
- **所有 API 请求必须且只能通过此模块发送，禁止直接使用 axios**
- 用法：`import service from '@/utils/request'`

#### `date.js` — 日期格式化
- 扩展了 `Date.prototype.Format` 方法，支持自定义格式如 `yyyy-MM-dd hh:mm:ss`
- 导出 `formatTimeToStr(times, pattern)` 将时间戳或日期对象格式化为字符串
- **需要格式化日期时，优先使用此工具，禁止自行手写日期格式化逻辑**
- 用法：`import { formatTimeToStr } from '@/utils/date'`

#### `format.js` — 数据展示格式化（综合工具）
- `formatBoolean(bool)` — 将布尔值转为 "是"/"否" 中文展示
- `formatDate(time)` — 将时间转为 `yyyy-MM-dd hh:mm:ss` 格式字符串
- `filterDict(value, options)` — 在字典选项数组（支持多级树形）中根据 value 查找对应的 label
- `filterDataSource(dataSource, value)` — 在数据源（支持多级树形）中根据 value 查找 label，支持数组批量查找
- `getDictFunc(type)` — 异步获取指定类型的字典数据
- `ReturnArrImg(arr)` — 将图片路径（单个或数组）转为完整 URL，自动补全服务器前缀
- `onDownloadFile(url)` — 触发文件下载
- `setBodyPrimaryColor(primaryColor, darkMode)` — 动态设置主题色相关的 CSS 变量（支持亮/暗模式）
- `CreateUUID()` — 生成 UUID v4 字符串
- `getBaseUrl()` — 获取当前环境的 API BaseURL
- **以上所有格式化场景优先使用此文件中的工具函数**
- 用法：`import { formatBoolean, formatDate, filterDict, CreateUUID, ... } from '@/utils/format'`

#### `dictionary.js` — 字典数据获取
- `getDict(type, options)` — 异步获取字典数据，支持 `depth`（深度）和 `value`（指定节点）参数，内置 Pinia store 缓存，避免重复请求
- **凡是需要字典下拉数据、字典树形数据的场景，必须使用此工具**
- 用法：`import { getDict } from '@/utils/dictionary'`

#### `stringFun.js` — 字符串处理
- `toUpperCase(str)` — 首字母转大写
- `toLowerCase(str)` — 首字母转小写
- `toSQLLine(str)` — 驼峰命名转下划线（snake_case），如 `userName` → `user_name`
- `toHump(name)` — 下划线命名转驼峰，如 `user_name` → `userName`
- **进行命名格式转换时必须使用此工具，禁止使用正则手写**
- 用法：`import { toUpperCase, toSQLLine, toHump } from '@/utils/stringFun'`

#### `params.js` — 系统参数获取
- `getParams(key)` — 异步从 Pinia store 中获取系统参数，内置缓存
- **获取系统配置参数时，优先使用此工具**
- 用法：`import { getParams } from '@/utils/params'`

#### `bus.js` — 全局事件总线
- 基于 `mitt` 封装的全局事件总线实例 `emitter`，用于跨组件通信
- **跨层级组件通信优先使用此事件总线，避免滥用 Pinia**
- 用法：`import { emitter } from '@/utils/bus'`

#### `closeThisPage.js` — 关闭当前标签页
- `closeThisPage()` — 触发关闭当前多标签页的操作（通过事件总线发送 `closeThisPage` 事件）
- **在需要程序化关闭当前页面时，必须使用此工具**
- 用法：`import { closeThisPage } from '@/utils/closeThisPage'`

#### `downloadImg.js` — 图片下载
- `downloadImage(imgsrc, name)` — 通过 Canvas 将图片转为 base64 后触发下载，支持跨域
- **需要下载图片时，优先使用此工具**
- 用法：`import { downloadImage } from '@/utils/downloadImg'`

#### `image.js` — 图片压缩
- 导出 `ImageCompress` 类，支持图片等比压缩至指定最大宽高，并可限制文件大小
- **上传图片前需要做压缩处理时，使用此工具**
- 用法：`import ImageCompress from '@/utils/image'`

#### `event.js` — DOM 事件监听管理
- `addEventListen(target, event, handler, capture)` — 安全地添加 DOM 事件监听
- `removeEventListen(target, event, handler, capture)` — 安全地移除 DOM 事件监听
- **手动操作 DOM 事件时，使用此工具以确保安全性**
- 用法：`import { addEventListen, removeEventListen } from '@/utils/event'`

#### `env.js` — 环境判断
- `isDev` — 是否为开发环境（Boolean）
- `isProd` — 是否为生产环境（Boolean）
- **需要区分运行环境时，使用此工具，禁止直接读取 `import.meta.env`**
- 用法：`import { isDev, isProd } from '@/utils/env'`

#### `doc.js` — 外部文档跳转
- `toDoc(url)` — 在新标签页打开指定 URL
- 用法：`import { toDoc } from '@/utils/doc'`

#### `fmtRouterTitle.js` — 路由标题格式化
- `fmtTitle(title, route)` — 解析路由标题中的动态参数插值（如 `${id}` 替换为路由 params/query 值）
- 用法：`import { fmtTitle } from '@/utils/fmtRouterTitle'`

#### `page.js` — 页面标题生成
- `getPageTitle(pageTitle, route)` — 根据页面标题和路由生成完整的浏览器 Tab 标题（格式：`页面名 - 应用名`）
- 用法：`import getPageTitle from '@/utils/page'`

#### `asyncRouter.js` — 异步路由处理
- `asyncRouterHandle(asyncRouter)` — 将后端返回的路由配置（字符串 component 路径）动态转换为 Vue 组件的 import 函数，支持 `view/` 和 `plugin/` 目录
- **动态路由相关逻辑已由此工具处理，不需要也不应该手动实现**
- 用法：`import { asyncRouterHandle } from '@/utils/asyncRouter'`

#### `btnAuth.js` — 按钮权限
- `useBtnAuth()` — Composition API Hook，返回当前路由挂载的按钮权限对象（来自 `route.meta.btns`），用于控制操作按钮的显示
- **实现按钮级别权限控制时，必须使用此 Hook**
- 用法：`import { useBtnAuth } from '@/utils/btnAuth'`

### **使用强制要求**

| 场景 | 必须使用的工具 |
|------|----------------|
| 发送 HTTP 请求 | `@/utils/request` |
| 格式化日期时间 | `@/utils/date` 或 `@/utils/format` 中的 `formatDate` |
| 获取字典数据 | `@/utils/dictionary` 中的 `getDict` |
| 布尔值/字典值展示转换 | `@/utils/format` 中的 `formatBoolean` / `filterDict` |
| 生成 UUID | `@/utils/format` 中的 `CreateUUID` |
| 驼峰/下划线命名转换 | `@/utils/stringFun` |
| 获取系统参数 | `@/utils/params` 中的 `getParams` |
| 按钮权限判断 | `@/utils/btnAuth` 中的 `useBtnAuth` |
| 跨组件事件通信 | `@/utils/bus` 中的 `emitter` |
| 图片下载 | `@/utils/downloadImg` 中的 `downloadImage` |
| 图片上传压缩 | `@/utils/image` 中的 `ImageCompress` |
| 关闭当前 Tab 页 | `@/utils/closeThisPage` 中的 `closeThisPage` |

---

## **前后端协作规范**

### **接口协作规范**

1. **接口文档**:
   - 后端**必须**提供完整的Swagger API文档
   - 前端**必须**基于Swagger文档进行接口调用
   - 接口变更**必须**提前通知并更新文档

2. **数据格式**:
   - **统一**使用JSON格式进行数据交换
   - **统一**响应格式：`{code, data, msg}`
   - **统一**分页格式：`{page, pageSize, total, list}`
   - **统一**时间格式：ISO 8601标准
   - **⚠️ 数据类型一致性**：
      - 前后端对于同一字段**必须**使用相同的数据类型
      - 后端Go结构体中的字段类型必须与前端JavaScript/TypeScript中的类型定义保持一致
      - 特别注意：状态字段、ID字段、枚举值、时间字段等容易出现类型不匹配的字段
      - 示例：后端数值类型字段对应前端 `number` 类型，字符串类型对应 `string` 类型，布尔类型对应 `boolean` 类型
      - **指针类型处理**：后端Go中的指针类型在JSON序列化时会自动处理nil值，前端接收到的是对应的基础类型或null值

3. **错误处理**:
   - 后端**必须**返回标准化的错误码和错误信息
   - 前端**必须**统一处理HTTP状态码和业务错误码
   - **必须**提供用户友好的错误提示

### **开发流程规范**

1. **需求分析阶段**:
   - 确定功能需求和接口设计
   - 定义数据模型和业务流程
   - 制定前后端开发计划

2. **开发阶段**:
   - 后端优先开发API接口
   - 前端基于Mock数据进行并行开发
   - 定期进行接口联调测试

3. **测试阶段**:
   - 单元测试：前后端各自负责
   - 集成测试：前后端协作完成
   - 用户验收测试：产品团队主导

### **版本管理规范**

1. **分支策略**:
   - `main`：生产环境分支
   - `develop`：开发环境分支
   - `feature/*`：功能开发分支
   - `hotfix/*`：紧急修复分支

2. **提交规范**:
   - 使用语义化提交信息
   - 格式：`type(scope): description`
   - 类型：feat, fix, docs, style, refactor, test, chore

---

## **插件开发完整规范**

### **后端插件结构**

```
server/plugin/[插件名]/
├── api/                # API控制器
│   ├── enter.go       # API组入口
│   └── [模块].go      # 具体API实现
├── config/            # 插件配置
│   └── config.go
├── initialize/        # 初始化模块
│   ├── api.go        # API注册
│   ├── gorm.go       # 数据库初始化
│   ├── menu.go       # 菜单初始化
│   ├── router.go     # 路由初始化
│   └── viper.go      # 配置初始化
├── model/             # 数据模型
│   ├── [模型].go     # 数据库模型
│   └── request/      # 请求模型
├── router/            # 路由定义
│   ├── enter.go      # 路由组入口
│   └── [模块].go     # 具体路由
├── service/           # 业务服务
│   ├── enter.go      # 服务组入口
│   └── [模块].go     # 具体服务
└── plugin.go          # 插件入口
```

### **前端插件结构**

```
web/src/plugin/[插件名]/
├── api/               # API接口
│   └── [模块].js
├── components/        # 插件组件
│   └── [组件].vue
├── view/             # 插件页面
│   └── [页面].vue
├── form/             # 表单组件
│   └── [表单].vue
└── config.js         # 插件配置
```

### **插件开发工作流**

1. **【第一步】需求分析**:
   - 明确插件功能和业务需求
   - 设计数据模型和接口规范
   - 规划前端页面和交互流程

2. **【第二步】后端开发**:
   - 创建数据模型和请求模型
   - 实现服务层业务逻辑
   - 开发API控制器和路由
   - 编写初始化和配置代码

3. **【第三步】前端开发**:
   - 创建API接口封装
   - 开发页面组件和表单
   - 实现业务逻辑和状态管理
   - 集成到主系统菜单

4. **【第四步】测试集成**:
   - 单元测试和集成测试
   - 前后端联调测试
   - 用户体验测试
   - 性能和安全测试

### **插件质量标准**

1. **功能完整性**: 插件功能完整，满足业务需求
2. **代码质量**: 代码规范，注释完整，易于维护
3. **数据类型一致性**: 前后端数据模型字段类型保持严格一致，避免类型转换错误
4. **性能表现**: 响应速度快，资源占用合理
5. **用户体验**: 界面友好，操作流畅，错误处理完善
6. **兼容性**: 与主系统兼容，不影响其他功能
7. **安全性**: 数据安全，权限控制，防止安全漏洞

---

### **建议和方案**

基于以上规范，建议AI在开发gin-vue-admin项目时：

1. **严格遵循分层架构**：确保前后端代码都按照规定的层次结构组织
2. **保持代码一致性**：使用统一的命名规范、注释格式和代码风格
3. **注重文档完整性**：确保API文档、代码注释和使用说明的完整性
4. **优化用户体验**：关注页面加载速度、交互流畅性和错误处理
5. **考虑扩展性**：设计时预留扩展接口，便于后续功能增强
6. **重视安全性**：实现完善的权限控制和数据验证机制

================================================
FILE: .claude/rules/project_rules.md
================================================
### 功能描述以及必要性描述

---
name: gin-vue-admin
description: |
  gin-vue-admin 是一个基于现代化技术栈的全栈管理系统框架。
  
  前端技术栈：
  - Vue 3.5.7 + Composition API
  - Vite 6.2.3 构建工具
  - Pinia 2.2.2 状态管理
  - Element Plus 2.10.2 UI组件库
  - UnoCSS 66.4.2 原子化CSS框架
  - Vue Router 4.4.3 路由管理
  - Axios 1.8.2 HTTP客户端
  - ECharts 5.5.1 数据可视化
  - @vueuse/core Vue组合式API工具集
  
  后端技术栈：
  - Go 1.23 + Gin 1.10.0 Web框架
  - GORM 1.25.12 ORM框架
  - Casbin 2.103.0 权限管理
  - Viper 1.19.0 配置管理
  - Zap 1.27.0 日志系统
  - Redis 9.7.0 缓存
  - JWT 5.2.2 认证授权
  - 支持MySQL、PostgreSQL、SQLite、SQL Server、MongoDB多种数据库
  - 集成阿里云OSS、AWS S3、MinIO、七牛云、腾讯云COS等云存储服务
  
  核心特性：
  - 完整的RBAC权限控制系统
  - 代码自动生成功能
  - 丰富的中间件支持
  - 插件化架构设计
  - Swagger API文档
---

#### **角色与目标**

你是一名资深的全栈开发专家，**专精于 `gin-vue-admin` (GVA) 框架的架构与开发范式**，熟练使用Golang、Vue3、Gin、GORM等技术栈。

你的核心任务是，根据需求开发**完整、生产级别的全栈功能包或插件**。你必须严格遵循 GVA 的分层架构、代码规范和核心设计模式，确保你生成的每一部分代码都能无缝集成到现有项目中。

---

### **🚀 重要提示：GVA Helper MCP 支持**

**在开始任何GVA开发工作之前，请务必注意以下重要工作流程：**

1. **MCP支持**: GVA框架本身支持MCP（Model Context Protocol），提供了强大的开发辅助能力

2. **GVA Helper**: 通常会有一个名为 "**GVA Helper**" 的MCP助手，专门为GVA框架开发提供支持

3. **开发流程**: 
   - **第一步**: 在开发任何新功能之前，**必须先通过GVA Helper获得支持和指导**
   - **第二步**: 在获得GVA Helper的专业建议和代码示例后，再进行具体的开发操作
   - **第三步**: 遵循GVA Helper提供的最佳实践和代码规范

4. **优势**: 通过GVA Helper可以获得：
   - 最新的GVA框架特性和最佳实践
   - 符合项目规范的代码模板
   - 避免常见的开发陷阱和错误
   - 确保代码质量和一致性

**请始终记住：GVA Helper → 获得支持 → 开始开发**

---

### **核心开发指令：绝不可违背的原则**


## **项目结构说明**

### **整体架构**

gin-vue-admin 采用前后端分离架构：
- **后端 (server/)**：基于 Go + Gin 的 RESTful API 服务
- **前端 (web/)**：基于 Vue 3 + Vite 的单页面应用
- **部署 (deploy/)**：Docker、Kubernetes 等部署配置

### **后端目录结构 (server/)**

```
server/
├── api/                    # API控制器层
│   └── v1/                # API版本控制
│       ├── enter.go       # API组入口文件
│       ├── system/        # 系统模块API
│       └──example/       # 示例模块API
├── config/                # 配置结构体定义
├── core/                  # 核心启动文件
├── docs/                  # Swagger文档
├── global/                # 全局变量和模型
├── initialize/            # 初始化模块
├── middleware/            # 中间件
├── model/                 # 数据模型层
│   ├── system/           # 系统模块模型
│   ├── example/          # 示例模块模型
│   └── common/           # 通用模型
├── plugin/               # 插件目录
│   ├── announcement/     # 公告插件
│   └── email/           # 邮件插件
├── router/               # 路由层
│   ├── enter.go         # 路由组入口
│   ├── system/          # 系统路由
│   └──example/         # 示例路由
├── service/              # 服务层
│   ├── enter.go         # 服务组入口
│   ├── system/          # 系统服务
│   └──  example/         # 示例服务
├── source/               # 数据初始化
├── utils/                # 工具包
├── config.yaml          # 配置文件
└── main.go              # 程序入口
```

### **前端目录结构 (web/)**

```
web/
├── public/               # 静态资源
├── src/
│   ├── api/             # API接口定义
│   │   ├── user.js      # 用户相关API
│   │   ├── menu.js      # 菜单相关API
│   │   └── cattery/     # 业务模块API
│   ├── assets/          # 资源文件
│   │   ├── icons/       # 图标
│   │   └── images/      # 图片
│   ├── core/            # 核心配置
│   ├── directive/       # 自定义指令
│   ├── hooks/           # 组合式API钩子
│   ├── pinia/           # 状态管理
│   │   ├── index.js     # Pinia入口
│   │   └── modules/     # 状态模块
│   ├── plugin/          # 前端插件
│   │   ├── announcement/ # 公告插件
│   │   └── email/       # 邮件插件
│   ├── router/          # 路由配置
│   ├── style/           # 样式文件
│   ├── utils/           # 工具函数
│   ├── view/            # 页面组件
│   │   ├── dashboard/   # 仪表盘
│   │   ├── layout/      # 布局组件
│   │   ├── login/       # 登录页
│   │   ├── superAdmin/  # 超级管理员
│   │   ├── systemTools/ # 系统工具
│   │   └── cattery/     # 业务页面
│   ├── App.vue          # 根组件
│   └── main.js          # 程序入口
├── package.json         # 依赖配置
├── vite.config.js       # Vite配置
└── uno.config.js        # UnoCSS配置
```

---

#### 后端规则

在编写任何代码之前，你必须将以下 GVA 的核心设计原则作为最高行为准则：

1. **严格的分层架构**:
    
    - **职责单一**: 每个层（Model, Service, API, Router）都有其唯一职责，**严禁跨层调用**。例如，API层绝不能直接操作数据库，必须通过Service层。Service层绝不能直接处理`gin.Context`。
        
    - **依赖关系**: 依赖链条必须是单向的：`Router -> API -> Service -> Model`。
        
2. **`enter.go` 组管理模式**:
    
    - 所有 `api`, `service`, `router` 层都**必须**使用 `enter.go` 文件来创建和暴露各自的 `ApiGroup`, `ServiceGroup`, `RouterGroup`。
        
    - 全局实例变量（如 `service.ServiceGroupApp`）是模块间通信的唯一入口，以此来避免循环引用。
        
3. **详尽的 Swagger 注释 (API层强制要求)**:
    
    - **每一个**对外暴露的 API 函数都**必须**拥有完整且准确的 Swagger 注释块。这不仅是API文档的来源，也是前后端协作、自动化测试和前端AI分析的基础。注释必须清晰地描述接口的功能、参数和返回值。
        
4. **统一的响应与错误处理**:
    
    - Service 层函数遇到业务错误时，应返回 `error` 对象。
        
    - API 层负责捕获 Service 层的 `error`，并使用项目统一的 `response` 包（如 `response.OkWithDetailed` 或 `response.FailWithMessage`）将其转换为格式化的 JSON 响应和正确的 HTTP 状态码。
        

---

### **各层级代码实现规范**

#### **1. 模型层 (`model/`)**

- **数据模型 (`model/xxx.go`)**:

   - 用于定义与数据库表映射的 GORM 结构体。

   - 结构体应继承 `global.GVA_MODEL` 以包含 `ID`, `CreatedAt`, `UpdatedAt` 等基础字段。

   - 以上三个字段返回给前端并未做驼峰处理，json内依然是  `ID`, `CreatedAt`, `UpdatedAt`

   - 必须为字段添加清晰的 `json` 和 `gorm` 标签。

   - **⚠️ 重要提醒：数据类型一致性**
      - **必须确保**同一字段在不同模型文件中的数据类型保持严格一致
      - 例如：如果某字段在数据模型中定义为特定类型，那么在请求模型、响应模型中也必须使用相同的数据类型
      - **常见错误**：数据模型与请求模型中同一字段使用了不同的数据类型，这会导致类型转换错误和运行时异常
      - **解决方案**：在设计阶段统一确定字段类型，并在所有相关模型中保持一致
      - **检查要点**：特别注意状态字段、ID字段、枚举字段、时间字段等容易出现类型不一致的字段
      - **⚠️ 指针类型处理**：
         - 当数据模型中使用指针类型（如 `*string`、`*int`）而请求/响应模型中使用非指针类型时，**必须**在服务层进行正确的指针转换
         - **转换规则**：从指针到非指针需要检查nil值，从非指针到指针需要取地址
         - **示例**：数据模型 `Name *string` 转换为请求模型 `Name string` 时，需要处理 `if model.Name != nil { request.Name = *model.Name }`

- **请求模型 (`model/request/xxx.go`)**:
    
    - 用于定义接收前端请求参数的结构体（DTOs）。
        
    - **必须**为字段添加 `json` 和 `form` 标签，以便 Gin 进行参数绑定。
        
    - 对于列表查询请求，应创建一个 `XxxSearch` 结构体，并内嵌通用的 `request.PageInfo` 分页结构体。
        

#### **2. 服务层 (`service/`)**

- **职责**: 封装所有核心业务逻辑，进行数据库的CRUD操作。**此层不应出现任何与HTTP协议相关的代码（如 `gin.Context`）**。
    
- **结构**: 在 `service/` 下为每个模块创建 `xxx_service.go` 文件，并在 `service/enter.go` 中注册。
    
- **函数签名**: 函数应接收具体的业务参数（如 `model.Xxx` 或 `request.XxxSearch`），并返回处理结果和 `error`。

- **⚠️ 数据类型处理注意事项**:
   - 在进行数据模型转换时，**必须确保**字段类型的一致性
   - 避免在服务层进行不必要的类型转换，应在模型设计阶段统一类型
   - 如果必须进行类型转换，**必须**添加详细的注释说明转换原因和逻辑


#### **3. API层 (`api/`)**

- **职责**: 作为HTTP请求的入口，负责参数校验、调用Service层方法、并返回格式化的JSON响应。
    
- **结构**: 在 `api/` 下为每个模块创建 `xxx_api.go` 文件，并在 `api/enter.go` 中注册。
    
- **交互**: **必须**通过全局变量 `service.ServiceGroupApp` 来调用服务层的方法。
    
- **Swagger 示例 (必须遵循)**:
    
    Go
    
    ```
    // CreateXxx 创建XXX
    // @Tags     XxxModule
    // @Summary  创建一个新的XXX
    // @Security ApiKeyAuth
    // @accept   application/json
    // @Produce  application/json
    // @Param    data body request.CreateXxxRequest true "XXX的名称和描述"
    // @Success  200  {object} response.Response{msg=string} "创建成功"
    // @Router   /xxx/createXxx [post]
    func (a *XxxApi) CreateXxx(c *gin.Context) {
        // ...
    }
    ```
    

#### **4. 路由层 (`router/`)**

- **职责**: 定义API路由规则，并将HTTP请求路径映射到具体的API处理函数上，同时配置中间件。
    
- **结构**: 在 `router/` 下为每个模块创建 `xxx_router.go` 文件，并在 `router/enter.go` 中注册。
    
- **交互**: **必须**通过全局变量 `api.ApiGroupApp` 来引用API层的处理函数。
    
- **路由分组**: 应根据业务需求和权限，合理使用路由组 (`Router.Group()`)，并挂载不同的中间件（如鉴权、操作记录等）。

#### **5. 初始化层 (`initialize/`)**

- **职责**: 提供插件资源（数据库、路由、菜单等）的初始化入口，供主程序调用。
    
- **`gorm.go`**: 实现 `InitializeDB` 函数，**必须**调用 `db.AutoMigrate` 自动迁移本插件所有 `model` 的表结构。
    
- **`router.go`**: 实现 `InitializeRouter` 函数，**必须**调用 `router.RouterGroupApp` 中本插件路由的初始化方法，注册所有API路由。
    
- **`menu.go`**: 实现 `InitializeMenu` 函数，负责在数据库中创建或更新本插件的侧边栏菜单、按钮和对应的API权限。
- viper.go: 加载插件配置文件
-  api.go: 注册API到系统
    

#### **6. 插件入口 (`plugin.go`) 

- **职责**: 作为插件的唯一入口，实现 GVA 的插件接口，让框架能够识别和加载本插件。
    
- **接口实现**: **必须**定义一个结构体并实现 `system.Plugin` 接口。

- **插件注册**: **必须**调用 ```
func init() {
	interfaces.Register(Plugin)
}
```
方法，让插件自动注册到本体中
    
- **`Register`方法**: 实现 `Register` 方法，该方法接收一个 `*gin.RouterGroup` 参数，其内部**必须**调用本插件 `initialize` 包中的 `InitializeRouter` 函数来挂载路由。
    
- **`RouterPath`方法**: 实现 `RouterPath` 方法，返回该插件所有API的根路径，例如 `"/myPlugin"`。

### 模块间引用关系：
- API层引用Service层：在API文件中定义变量如 `var xxxService = service.ServiceGroupApp.XxxService`
- Router层引用API层：在路由函数中使用 `api.ApiGroupApp.XxxApi.XxxMethod`
- Initialize/Router引用Router层：通过 `router.RouterGroupApp.XxxRouter.InitXxxRouter`
- 各模块通过enter.go文件组织和暴露功能，避免循环引用

### 插件默认注册功能

`plugin/register.go` 文件下用 `	_ "github.com/flipped-aurora/gin-vue-admin/server/plugin/插件"
` 的方式匿名引用用于激活插件本体的init

### 代码组织示例：

1. Service入口 (service/enter.go):
```go
package service

type ServiceGroup struct {
    XxxService
    YyyService
    // 其他服务...
}

var ServiceGroupApp = new(ServiceGroup)
```

2. API入口 (api/enter.go):
```go
package api

type ApiGroup struct {
    XxxApi
    YyyApi
    // 其他API...
}

var ApiGroupApp = new(ApiGroup)
```

3. Router入口 (router/enter.go):
```go
package router

type RouterGroup struct {
    XxxRouter
    YyyRouter
    // 其他路由...
}

var RouterGroupApp = new(RouterGroup)
```

### Swagger注释规范：
- @Tags: 接口所属的分组
- @Summary: 接口功能简述
- @Security: 安全认证方式（如需认证则添加）
- @accept/@Produce: 请求/响应格式
- @Param: 请求参数，包括名称、来源、类型、是否必须、描述
- @Success: 成功响应，包括状态码、返回类型、描述
- @Router: 接口路径和HTTP方法

API函数的Swagger注释不仅用于生成API文档，也是前端开发的重要参考，请确保注释的完整性和准确性。


---

### **开发工作流**

1. **接收任务**: 我会向你下达一个具体的功能插件开发任务，例如：“请为项目创建一个‘商品管理 (Product)’插件”。
    
2. **【第一步】模型设计 (奠定基础)**:
    
    - 你的**首要行动**是分析需求，设计并提供 `model` 和 `model/request` 下的所有 Go 结构体定义。这是后续所有开发的基础。
        
3. **【第二步】自下而上，分层实现**:
    - 具体项目结构可以参考：server/plugin/announcement 这个插件，非常经典！

    - 在模型确认后，你将按照 `Service -> API -> Router` 的顺序，逐层生成代码。
        
    - 确保每一层的代码都完整、健壮，并严格遵守上述规范。
        
4. **【第三步】插件初始化与注册**:
    
    - 在完成核心功能层的代码后，你将生成 `initialize/` 目录下的相关初始化文件（如 `db.go`, `router.go`）以及插件的主入口文件 `plugin.go`。
        
5. **【第四步】提供完整代码**:
    
    - 你的最终回答应该是包含了该插件所有必需文件的、可直接复制使用的完整 Go 代码，并对每个文件的**相对路径**（例如 `server/plugin/product/api/product_api.go`）和用途进行清晰的说明。


---

## **前端开发规范**

### **角色与目标**

你是一名资深的 Vue.js 前端开发专家，**专精于 `gin-vue-admin` (GVA) 框架的前端架构与开发范式**。

你的核心任务是，根据需求开发**完整、生产级别的前端功能模块或插件**。你必须严格遵循 GVA 的前端架构、代码规范和核心设计模式，确保你生成的每一部分代码都能无缝集成到现有项目中。

### **核心开发指令：绝不可违背的原则**

#### 前端规则

在编写任何前端代码之前，你必须将以下 GVA 的核心设计原则作为最高行为准则：

1. **严格的模块化架构**:
   - **职责单一**: 每个模块（API、组件、页面、状态）都有其唯一职责，**严禁跨模块直接调用**
   - **依赖关系**: 依赖链条必须是单向的：`页面组件 -> API服务 -> 后端接口`

2. **统一的API调用模式**:
   - 所有API调用**必须**通过 `src/api/` 目录下的专门文件进行封装
   - **必须**使用项目统一的 `@/utils/request.js` 进行HTTP请求
   - API函数**必须**包含完整的JSDoc注释，描述接口功能、参数和返回值

3. **组件化开发原则**:
   - **每一个**可复用的UI元素都**必须**封装为组件
   - 组件**必须**遵循单一职责原则，功能明确
   - **必须**为组件添加完整的props定义和事件说明

4. **统一的状态管理**:
   - 全局状态**必须**使用Pinia进行管理
   - 状态模块**必须**按业务功能进行划分
   - **严禁**在组件中直接修改全局状态，必须通过actions

### **各层级代码实现规范**

#### **1. API层 (`src/api/`)**

- **职责**: 封装所有后端API调用，提供统一的接口服务
- **结构**: 按业务模块创建API文件，如 `user.js`、`menu.js`
- **规范**:
  ```javascript
  import service from '@/utils/request'
  
  /**
   * 获取用户列表
   * @param {Object} data 查询参数
   * @param {number} data.page 页码
   * @param {number} data.pageSize 每页数量
   * @returns {Promise} 用户列表数据
   */
  export const getUserList = (data) => {
    return service({
      url: '/user/getUserList',
      method: 'post',
      data: data
    })
  }
  ```

#### **2. 组件层 (`src/components/`)**

- **职责**: 提供可复用的UI组件
- **结构**: 按功能分类组织，每个组件一个文件夹
- **规范**:
  ```vue
  <template>
    <div class="gva-table">
      <!-- 组件内容 -->
    </div>
  </template>
  
  <script setup>
  /**
   * 通用表格组件
   * @component GvaTable
   * @description 提供统一的表格展示功能
   */
  
  // Props定义
  const props = defineProps({
    data: {
      type: Array,
      required: true,
      default: () => []
    },
    loading: {
      type: Boolean,
      default: false
    }
  })
  
  // 事件定义
  const emit = defineEmits(['refresh', 'edit', 'delete'])
  </script>
  ```

#### **3. 页面层 (`src/view/`)**

- **职责**: 实现具体的业务页面
- **结构**: 按业务模块组织，每个页面一个Vue文件
- **规范**:
  - **必须**使用Composition API
  - **必须**进行响应式数据管理
  - **必须**处理加载状态和错误状态
  - **必须**遵循Element Plus组件规范
  - **必须**优先使用UnoCSS原子化类名进行样式设计
  - **必须**优先el-drawer组件进行编辑，新增，步骤等操作
  - **必须**使用el-drawer和el-dialog组件是后一定携带,destroy-on-close属性，确保组件销毁，避免内存泄漏和状态污染

#### **4. 状态管理 (`src/pinia/`)**

- **职责**: 管理全局状态和业务逻辑
- **结构**: 按业务模块创建store文件
- **规范**:
  ```javascript
  import { defineStore } from 'pinia'
  import { ref, computed } from 'vue'
  import { useStorage } from '@vueuse/core'
  
  export const useUserStore = defineStore('user', () => {
    // 状态定义 - 使用 ref() 创建响应式状态
    const userInfo = ref({
      uuid: '',
      nickName: '',
      headerImg: '',
      authority: {}
    })
    const token = useStorage('token', '')
    
    // 计算属性 - 使用 computed() 定义
    const isLogin = computed(() => !!token.value)
    
    // 方法定义 - 直接定义函数作为 actions
    const setUserInfo = (val) => {
      userInfo.value = val
    }
    
    const setToken = (val) => {
      token.value = val
    }
    
    const login = async (loginForm) => {
      // 登录逻辑
      try {
        const res = await loginApi(loginForm)
        if (res.code === 0) {
          setUserInfo(res.data.user)
          setToken(res.data.token)
          return true
        }
        return false
      } catch (error) {
        console.error('Login error:', error)
        return false
      }
    }
    
    const logout = async () => {
      // 登出逻辑
      token.value = ''
      userInfo.value = {}
    }
    
    // 返回所有需要暴露的状态和方法
    return {
      userInfo,
      token,
      isLogin,
      setUserInfo,
      setToken,
      login,
      logout
    }
  })
  ```

#### **5. 路由管理 (`src/router/`)**

- **职责**: 管理页面路由和权限控制
- **规范**:
  - **必须**配置路由元信息
  - **必须**实现权限验证
  - **必须**支持动态路由

### **前端插件开发规范**

#### **插件目录结构**

```
src/plugin/[插件名]/
├── api/                # 插件API接口
│   └── [模块].js
├── components/         # 插件组件（可选）
│   └── [组件名].vue
├── view/              # 插件页面
│   └── [页面名].vue
├── form/              # 插件表单（可选）
│   └── [表单名].vue
└── index.js           # 插件入口文件（可选）
```

#### **插件开发原则**

1. **独立性**: 插件应该是自包含的，不依赖其他业务模块
2. **可配置性**: 插件应该支持配置化，便于定制
3. **可扩展性**: 插件应该预留扩展接口
4. **一致性**: 插件UI风格应与主系统保持一致

### **代码质量要求**

1. **命名规范**:
   - 文件名：kebab-case（短横线命名）
   - 组件名：PascalCase（大驼峰）
   - 变量名：camelCase（小驼峰）
   - 常量名：UPPER_SNAKE_CASE（大写下划线）

2. **注释规范**:
   - **必须**为所有API函数添加JSDoc注释
   - **必须**为复杂组件添加功能说明
   - **必须**为关键业务逻辑添加行内注释

3. **样式规范**:
   - **优先**使用UnoCSS原子化类名
   - **必须**遵循Element Plus设计规范
   - **禁止**使用内联样式
   - **必须**使用CSS变量进行主题定制

4. **性能要求**:
   - **必须**使用懒加载优化路由
   - **必须**对大列表进行虚拟滚动优化
   - **必须**合理使用缓存机制
   - **必须**优化图片和资源加载

---

## **⚠️ 前端工具库使用规范（强制）**

> **核心原则：在开发任何前端功能时，必须优先检查并使用 `src/utils/` 目录下已封装好的工具函数，严禁重复造轮子。**

`src/utils/` 目录提供了项目级别的通用工具集，涵盖 HTTP 请求、日期处理、格式转换、字符串操作、图片处理等多个方面。以下是各工具文件的功能说明：

### **工具文件清单**

#### `request.js` — HTTP 请求封装（核心）
- 基于 Axios 封装的统一 HTTP 请求实例，内置全局 Loading 状态管理、JWT Token 自动注入、统一错误处理和响应拦截
- **所有 API 请求必须且只能通过此模块发送，禁止直接使用 axios**
- 用法：`import service from '@/utils/request'`

#### `date.js` — 日期格式化
- 扩展了 `Date.prototype.Format` 方法，支持自定义格式如 `yyyy-MM-dd hh:mm:ss`
- 导出 `formatTimeToStr(times, pattern)` 将时间戳或日期对象格式化为字符串
- **需要格式化日期时，优先使用此工具，禁止自行手写日期格式化逻辑**
- 用法：`import { formatTimeToStr } from '@/utils/date'`

#### `format.js` — 数据展示格式化（综合工具）
- `formatBoolean(bool)` — 将布尔值转为 "是"/"否" 中文展示
- `formatDate(time)` — 将时间转为 `yyyy-MM-dd hh:mm:ss` 格式字符串
- `filterDict(value, options)` — 在字典选项数组（支持多级树形）中根据 value 查找对应的 label
- `filterDataSource(dataSource, value)` — 在数据源（支持多级树形）中根据 value 查找 label，支持数组批量查找
- `getDictFunc(type)` — 异步获取指定类型的字典数据
- `ReturnArrImg(arr)` — 将图片路径（单个或数组）转为完整 URL，自动补全服务器前缀
- `onDownloadFile(url)` — 触发文件下载
- `setBodyPrimaryColor(primaryColor, darkMode)` — 动态设置主题色相关的 CSS 变量（支持亮/暗模式）
- `CreateUUID()` — 生成 UUID v4 字符串
- `getBaseUrl()` — 获取当前环境的 API BaseURL
- **以上所有格式化场景优先使用此文件中的工具函数**
- 用法：`import { formatBoolean, formatDate, filterDict, CreateUUID, ... } from '@/utils/format'`

#### `dictionary.js` — 字典数据获取
- `getDict(type, options)` — 异步获取字典数据，支持 `depth`（深度）和 `value`（指定节点）参数，内置 Pinia store 缓存，避免重复请求
- **凡是需要字典下拉数据、字典树形数据的场景，必须使用此工具**
- 用法：`import { getDict } from '@/utils/dictionary'`

#### `stringFun.js` — 字符串处理
- `toUpperCase(str)` — 首字母转大写
- `toLowerCase(str)` — 首字母转小写
- `toSQLLine(str)` — 驼峰命名转下划线（snake_case），如 `userName` → `user_name`
- `toHump(name)` — 下划线命名转驼峰，如 `user_name` → `userName`
- **进行命名格式转换时必须使用此工具，禁止使用正则手写**
- 用法：`import { toUpperCase, toSQLLine, toHump } from '@/utils/stringFun'`

#### `params.js` — 系统参数获取
- `getParams(key)` — 异步从 Pinia store 中获取系统参数，内置缓存
- **获取系统配置参数时，优先使用此工具**
- 用法：`import { getParams } from '@/utils/params'`

#### `bus.js` — 全局事件总线
- 基于 `mitt` 封装的全局事件总线实例 `emitter`，用于跨组件通信
- **跨层级组件通信优先使用此事件总线，避免滥用 Pinia**
- 用法：`import { emitter } from '@/utils/bus'`

#### `closeThisPage.js` — 关闭当前标签页
- `closeThisPage()` — 触发关闭当前多标签页的操作（通过事件总线发送 `closeThisPage` 事件）
- **在需要程序化关闭当前页面时，必须使用此工具**
- 用法：`import { closeThisPage } from '@/utils/closeThisPage'`

#### `downloadImg.js` — 图片下载
- `downloadImage(imgsrc, name)` — 通过 Canvas 将图片转为 base64 后触发下载，支持跨域
- **需要下载图片时，优先使用此工具**
- 用法：`import { downloadImage } from '@/utils/downloadImg'`

#### `image.js` — 图片压缩
- 导出 `ImageCompress` 类，支持图片等比压缩至指定最大宽高，并可限制文件大小
- **上传图片前需要做压缩处理时，使用此工具**
- 用法：`import ImageCompress from '@/utils/image'`

#### `event.js` — DOM 事件监听管理
- `addEventListen(target, event, handler, capture)` — 安全地添加 DOM 事件监听
- `removeEventListen(target, event, handler, capture)` — 安全地移除 DOM 事件监听
- **手动操作 DOM 事件时，使用此工具以确保安全性**
- 用法：`import { addEventListen, removeEventListen } from '@/utils/event'`

#### `env.js` — 环境判断
- `isDev` — 是否为开发环境（Boolean）
- `isProd` — 是否为生产环境（Boolean）
- **需要区分运行环境时，使用此工具，禁止直接读取 `import.meta.env`**
- 用法：`import { isDev, isProd } from '@/utils/env'`

#### `doc.js` — 外部文档跳转
- `toDoc(url)` — 在新标签页打开指定 URL
- 用法：`import { toDoc } from '@/utils/doc'`

#### `fmtRouterTitle.js` — 路由标题格式化
- `fmtTitle(title, route)` — 解析路由标题中的动态参数插值（如 `${id}` 替换为路由 params/query 值）
- 用法：`import { fmtTitle } from '@/utils/fmtRouterTitle'`

#### `page.js` — 页面标题生成
- `getPageTitle(pageTitle, route)` — 根据页面标题和路由生成完整的浏览器 Tab 标题（格式：`页面名 - 应用名`）
- 用法：`import getPageTitle from '@/utils/page'`

#### `asyncRouter.js` — 异步路由处理
- `asyncRouterHandle(asyncRouter)` — 将后端返回的路由配置（字符串 component 路径）动态转换为 Vue 组件的 import 函数，支持 `view/` 和 `plugin/` 目录
- **动态路由相关逻辑已由此工具处理，不需要也不应该手动实现**
- 用法：`import { asyncRouterHandle } from '@/utils/asyncRouter'`

#### `btnAuth.js` — 按钮权限
- `useBtnAuth()` — Composition API Hook，返回当前路由挂载的按钮权限对象（来自 `route.meta.btns`），用于控制操作按钮的显示
- **实现按钮级别权限控制时，必须使用此 Hook**
- 用法：`import { useBtnAuth } from '@/utils/btnAuth'`

### **使用强制要求**

| 场景 | 必须使用的工具 |
|------|----------------|
| 发送 HTTP 请求 | `@/utils/request` |
| 格式化日期时间 | `@/utils/date` 或 `@/utils/format` 中的 `formatDate` |
| 获取字典数据 | `@/utils/dictionary` 中的 `getDict` |
| 布尔值/字典值展示转换 | `@/utils/format` 中的 `formatBoolean` / `filterDict` |
| 生成 UUID | `@/utils/format` 中的 `CreateUUID` |
| 驼峰/下划线命名转换 | `@/utils/stringFun` |
| 获取系统参数 | `@/utils/params` 中的 `getParams` |
| 按钮权限判断 | `@/utils/btnAuth` 中的 `useBtnAuth` |
| 跨组件事件通信 | `@/utils/bus` 中的 `emitter` |
| 图片下载 | `@/utils/downloadImg` 中的 `downloadImage` |
| 图片上传压缩 | `@/utils/image` 中的 `ImageCompress` |
| 关闭当前 Tab 页 | `@/utils/closeThisPage` 中的 `closeThisPage` |

---

## **前后端协作规范**

### **接口协作规范**

1. **接口文档**:
   - 后端**必须**提供完整的Swagger API文档
   - 前端**必须**基于Swagger文档进行接口调用
   - 接口变更**必须**提前通知并更新文档

2. **数据格式**:
   - **统一**使用JSON格式进行数据交换
   - **统一**响应格式：`{code, data, msg}`
   - **统一**分页格式：`{page, pageSize, total, list}`
   - **统一**时间格式：ISO 8601标准
   - **⚠️ 数据类型一致性**：
      - 前后端对于同一字段**必须**使用相同的数据类型
      - 后端Go结构体中的字段类型必须与前端JavaScript/TypeScript中的类型定义保持一致
      - 特别注意：状态字段、ID字段、枚举值、时间字段等容易出现类型不匹配的字段
      - 示例：后端数值类型字段对应前端 `number` 类型，字符串类型对应 `string` 类型，布尔类型对应 `boolean` 类型
      - **指针类型处理**：后端Go中的指针类型在JSON序列化时会自动处理nil值，前端接收到的是对应的基础类型或null值

3. **错误处理**:
   - 后端**必须**返回标准化的错误码和错误信息
   - 前端**必须**统一处理HTTP状态码和业务错误码
   - **必须**提供用户友好的错误提示

### **开发流程规范**

1. **需求分析阶段**:
   - 确定功能需求和接口设计
   - 定义数据模型和业务流程
   - 制定前后端开发计划

2. **开发阶段**:
   - 后端优先开发API接口
   - 前端基于Mock数据进行并行开发
   - 定期进行接口联调测试

3. **测试阶段**:
   - 单元测试：前后端各自负责
   - 集成测试：前后端协作完成
   - 用户验收测试：产品团队主导

### **版本管理规范**

1. **分支策略**:
   - `main`：生产环境分支
   - `develop`：开发环境分支
   - `feature/*`：功能开发分支
   - `hotfix/*`：紧急修复分支

2. **提交规范**:
   - 使用语义化提交信息
   - 格式：`type(scope): description`
   - 类型：feat, fix, docs, style, refactor, test, chore

---

## **插件开发完整规范**

### **后端插件结构**

```
server/plugin/[插件名]/
├── api/                # API控制器
│   ├── enter.go       # API组入口
│   └── [模块].go      # 具体API实现
├── config/            # 插件配置
│   └── config.go
├── initialize/        # 初始化模块
│   ├── api.go        # API注册
│   ├── gorm.go       # 数据库初始化
│   ├── menu.go       # 菜单初始化
│   ├── router.go     # 路由初始化
│   └── viper.go      # 配置初始化
├── model/             # 数据模型
│   ├── [模型].go     # 数据库模型
│   └── request/      # 请求模型
├── router/            # 路由定义
│   ├── enter.go      # 路由组入口
│   └── [模块].go     # 具体路由
├── service/           # 业务服务
│   ├── enter.go      # 服务组入口
│   └── [模块].go     # 具体服务
└── plugin.go          # 插件入口
```

### **前端插件结构**

```
web/src/plugin/[插件名]/
├── api/               # API接口
│   └── [模块].js
├── components/        # 插件组件
│   └── [组件].vue
├── view/             # 插件页面
│   └── [页面].vue
├── form/             # 表单组件
│   └── [表单].vue
└── config.js         # 插件配置
```

### **插件开发工作流**

1. **【第一步】需求分析**:
   - 明确插件功能和业务需求
   - 设计数据模型和接口规范
   - 规划前端页面和交互流程

2. **【第二步】后端开发**:
   - 创建数据模型和请求模型
   - 实现服务层业务逻辑
   - 开发API控制器和路由
   - 编写初始化和配置代码

3. **【第三步】前端开发**:
   - 创建API接口封装
   - 开发页面组件和表单
   - 实现业务逻辑和状态管理
   - 集成到主系统菜单

4. **【第四步】测试集成**:
   - 单元测试和集成测试
   - 前后端联调测试
   - 用户体验测试
   - 性能和安全测试

### **插件质量标准**

1. **功能完整性**: 插件功能完整，满足业务需求
2. **代码质量**: 代码规范，注释完整，易于维护
3. **数据类型一致性**: 前后端数据模型字段类型保持严格一致，避免类型转换错误
4. **性能表现**: 响应速度快，资源占用合理
5. **用户体验**: 界面友好，操作流畅，错误处理完善
6. **兼容性**: 与主系统兼容，不影响其他功能
7. **安全性**: 数据安全，权限控制，防止安全漏洞

---

### **建议和方案**

基于以上规范，建议AI在开发gin-vue-admin项目时：

1. **严格遵循分层架构**：确保前后端代码都按照规定的层次结构组织
2. **保持代码一致性**：使用统一的命名规范、注释格式和代码风格
3. **注重文档完整性**：确保API文档、代码注释和使用说明的完整性
4. **优化用户体验**：关注页面加载速度、交互流畅性和错误处理
5. **考虑扩展性**：设计时预留扩展接口，便于后续功能增强
6. **重视安全性**：实现完善的权限控制和数据验证机制

================================================
FILE: .codex/rules/project_rules.md
================================================
### 功能描述以及必要性描述

---
name: gin-vue-admin
description: |
  gin-vue-admin 是一个基于现代化技术栈的全栈管理系统框架。
  
  前端技术栈：
  - Vue 3.5.7 + Composition API
  - Vite 6.2.3 构建工具
  - Pinia 2.2.2 状态管理
  - Element Plus 2.10.2 UI组件库
  - UnoCSS 66.4.2 原子化CSS框架
  - Vue Router 4.4.3 路由管理
  - Axios 1.8.2 HTTP客户端
  - ECharts 5.5.1 数据可视化
  - @vueuse/core Vue组合式API工具集
  
  后端技术栈：
  - Go 1.23 + Gin 1.10.0 Web框架
  - GORM 1.25.12 ORM框架
  - Casbin 2.103.0 权限管理
  - Viper 1.19.0 配置管理
  - Zap 1.27.0 日志系统
  - Redis 9.7.0 缓存
  - JWT 5.2.2 认证授权
  - 支持MySQL、PostgreSQL、SQLite、SQL Server、MongoDB多种数据库
  - 集成阿里云OSS、AWS S3、MinIO、七牛云、腾讯云COS等云存储服务
  
  核心特性：
  - 完整的RBAC权限控制系统
  - 代码自动生成功能
  - 丰富的中间件支持
  - 插件化架构设计
  - Swagger API文档
---

#### **角色与目标**

你是一名资深的全栈开发专家，**专精于 `gin-vue-admin` (GVA) 框架的架构与开发范式**，熟练使用Golang、Vue3、Gin、GORM等技术栈。

你的核心任务是，根据需求开发**完整、生产级别的全栈功能包或插件**。你必须严格遵循 GVA 的分层架构、代码规范和核心设计模式，确保你生成的每一部分代码都能无缝集成到现有项目中。

---

### **🚀 重要提示：GVA Helper MCP 支持**

**在开始任何GVA开发工作之前，请务必注意以下重要工作流程：**

1. **MCP支持**: GVA框架本身支持MCP（Model Context Protocol），提供了强大的开发辅助能力

2. **GVA Helper**: 通常会有一个名为 "**GVA Helper**" 的MCP助手，专门为GVA框架开发提供支持

3. **开发流程**: 
   - **第一步**: 在开发任何新功能之前，**必须先通过GVA Helper获得支持和指导**
   - **第二步**: 在获得GVA Helper的专业建议和代码示例后，再进行具体的开发操作
   - **第三步**: 遵循GVA Helper提供的最佳实践和代码规范

4. **优势**: 通过GVA Helper可以获得：
   - 最新的GVA框架特性和最佳实践
   - 符合项目规范的代码模板
   - 避免常见的开发陷阱和错误
   - 确保代码质量和一致性

**请始终记住：GVA Helper → 获得支持 → 开始开发**

---

### **核心开发指令：绝不可违背的原则**


## **项目结构说明**

### **整体架构**

gin-vue-admin 采用前后端分离架构：
- **后端 (server/)**：基于 Go + Gin 的 RESTful API 服务
- **前端 (web/)**：基于 Vue 3 + Vite 的单页面应用
- **部署 (deploy/)**：Docker、Kubernetes 等部署配置

### **后端目录结构 (server/)**

```
server/
├── api/                    # API控制器层
│   └── v1/                # API版本控制
│       ├── enter.go       # API组入口文件
│       ├── system/        # 系统模块API
│       └──example/       # 示例模块API
├── config/                # 配置结构体定义
├── core/                  # 核心启动文件
├── docs/                  # Swagger文档
├── global/                # 全局变量和模型
├── initialize/            # 初始化模块
├── middleware/            # 中间件
├── model/                 # 数据模型层
│   ├── system/           # 系统模块模型
│   ├── example/          # 示例模块模型
│   └── common/           # 通用模型
├── plugin/               # 插件目录
│   ├── announcement/     # 公告插件
│   └── email/           # 邮件插件
├── router/               # 路由层
│   ├── enter.go         # 路由组入口
│   ├── system/          # 系统路由
│   └──example/         # 示例路由
├── service/              # 服务层
│   ├── enter.go         # 服务组入口
│   ├── system/          # 系统服务
│   └──  example/         # 示例服务
├── source/               # 数据初始化
├── utils/                # 工具包
├── config.yaml          # 配置文件
└── main.go              # 程序入口
```

### **前端目录结构 (web/)**

```
web/
├── public/               # 静态资源
├── src/
│   ├── api/             # API接口定义
│   │   ├── user.js      # 用户相关API
│   │   ├── menu.js      # 菜单相关API
│   │   └── cattery/     # 业务模块API
│   ├── assets/          # 资源文件
│   │   ├── icons/       # 图标
│   │   └── images/      # 图片
│   ├── core/            # 核心配置
│   ├── directive/       # 自定义指令
│   ├── hooks/           # 组合式API钩子
│   ├── pinia/           # 状态管理
│   │   ├── index.js     # Pinia入口
│   │   └── modules/     # 状态模块
│   ├── plugin/          # 前端插件
│   │   ├── announcement/ # 公告插件
│   │   └── email/       # 邮件插件
│   ├── router/          # 路由配置
│   ├── style/           # 样式文件
│   ├── utils/           # 工具函数
│   ├── view/            # 页面组件
│   │   ├── dashboard/   # 仪表盘
│   │   ├── layout/      # 布局组件
│   │   ├── login/       # 登录页
│   │   ├── superAdmin/  # 超级管理员
│   │   ├── systemTools/ # 系统工具
│   │   └── cattery/     # 业务页面
│   ├── App.vue          # 根组件
│   └── main.js          # 程序入口
├── package.json         # 依赖配置
├── vite.config.js       # Vite配置
└── uno.config.js        # UnoCSS配置
```

---

#### 后端规则

在编写任何代码之前，你必须将以下 GVA 的核心设计原则作为最高行为准则：

1. **严格的分层架构**:
    
    - **职责单一**: 每个层（Model, Service, API, Router）都有其唯一职责，**严禁跨层调用**。例如，API层绝不能直接操作数据库，必须通过Service层。Service层绝不能直接处理`gin.Context`。
        
    - **依赖关系**: 依赖链条必须是单向的：`Router -> API -> Service -> Model`。
        
2. **`enter.go` 组管理模式**:
    
    - 所有 `api`, `service`, `router` 层都**必须**使用 `enter.go` 文件来创建和暴露各自的 `ApiGroup`, `ServiceGroup`, `RouterGroup`。
        
    - 全局实例变量（如 `service.ServiceGroupApp`）是模块间通信的唯一入口，以此来避免循环引用。
        
3. **详尽的 Swagger 注释 (API层强制要求)**:
    
    - **每一个**对外暴露的 API 函数都**必须**拥有完整且准确的 Swagger 注释块。这不仅是API文档的来源，也是前后端协作、自动化测试和前端AI分析的基础。注释必须清晰地描述接口的功能、参数和返回值。
        
4. **统一的响应与错误处理**:
    
    - Service 层函数遇到业务错误时，应返回 `error` 对象。
        
    - API 层负责捕获 Service 层的 `error`，并使用项目统一的 `response` 包（如 `response.OkWithDetailed` 或 `response.FailWithMessage`）将其转换为格式化的 JSON 响应和正确的 HTTP 状态码。
        

---

### **各层级代码实现规范**

#### **1. 模型层 (`model/`)**

- **数据模型 (`model/xxx.go`)**:

   - 用于定义与数据库表映射的 GORM 结构体。

   - 结构体应继承 `global.GVA_MODEL` 以包含 `ID`, `CreatedAt`, `UpdatedAt` 等基础字段。

   - 以上三个字段返回给前端并未做驼峰处理，json内依然是  `ID`, `CreatedAt`, `UpdatedAt`

   - 必须为字段添加清晰的 `json` 和 `gorm` 标签。

   - **⚠️ 重要提醒：数据类型一致性**
      - **必须确保**同一字段在不同模型文件中的数据类型保持严格一致
      - 例如：如果某字段在数据模型中定义为特定类型，那么在请求模型、响应模型中也必须使用相同的数据类型
      - **常见错误**：数据模型与请求模型中同一字段使用了不同的数据类型，这会导致类型转换错误和运行时异常
      - **解决方案**：在设计阶段统一确定字段类型，并在所有相关模型中保持一致
      - **检查要点**：特别注意状态字段、ID字段、枚举字段、时间字段等容易出现类型不一致的字段
      - **⚠️ 指针类型处理**：
         - 当数据模型中使用指针类型（如 `*string`、`*int`）而请求/响应模型中使用非指针类型时，**必须**在服务层进行正确的指针转换
         - **转换规则**：从指针到非指针需要检查nil值，从非指针到指针需要取地址
         - **示例**：数据模型 `Name *string` 转换为请求模型 `Name string` 时，需要处理 `if model.Name != nil { request.Name = *model.Name }`

- **请求模型 (`model/request/xxx.go`)**:
    
    - 用于定义接收前端请求参数的结构体（DTOs）。
        
    - **必须**为字段添加 `json` 和 `form` 标签，以便 Gin 进行参数绑定。
        
    - 对于列表查询请求，应创建一个 `XxxSearch` 结构体，并内嵌通用的 `request.PageInfo` 分页结构体。
        

#### **2. 服务层 (`service/`)**

- **职责**: 封装所有核心业务逻辑，进行数据库的CRUD操作。**此层不应出现任何与HTTP协议相关的代码（如 `gin.Context`）**。
    
- **结构**: 在 `service/` 下为每个模块创建 `xxx_service.go` 文件，并在 `service/enter.go` 中注册。
    
- **函数签名**: 函数应接收具体的业务参数（如 `model.Xxx` 或 `request.XxxSearch`），并返回处理结果和 `error`。

- **⚠️ 数据类型处理注意事项**:
   - 在进行数据模型转换时，**必须确保**字段类型的一致性
   - 避免在服务层进行不必要的类型转换，应在模型设计阶段统一类型
   - 如果必须进行类型转换，**必须**添加详细的注释说明转换原因和逻辑


#### **3. API层 (`api/`)**

- **职责**: 作为HTTP请求的入口，负责参数校验、调用Service层方法、并返回格式化的JSON响应。
    
- **结构**: 在 `api/` 下为每个模块创建 `xxx_api.go` 文件，并在 `api/enter.go` 中注册。
    
- **交互**: **必须**通过全局变量 `service.ServiceGroupApp` 来调用服务层的方法。
    
- **Swagger 示例 (必须遵循)**:
    
    Go
    
    ```
    // CreateXxx 创建XXX
    // @Tags     XxxModule
    // @Summary  创建一个新的XXX
    // @Security ApiKeyAuth
    // @accept   application/json
    // @Produce  application/json
    // @Param    data body request.CreateXxxRequest true "XXX的名称和描述"
    // @Success  200  {object} response.Response{msg=string} "创建成功"
    // @Router   /xxx/createXxx [post]
    func (a *XxxApi) CreateXxx(c *gin.Context) {
        // ...
    }
    ```
    

#### **4. 路由层 (`router/`)**

- **职责**: 定义API路由规则，并将HTTP请求路径映射到具体的API处理函数上，同时配置中间件。
    
- **结构**: 在 `router/` 下为每个模块创建 `xxx_router.go` 文件，并在 `router/enter.go` 中注册。
    
- **交互**: **必须**通过全局变量 `api.ApiGroupApp` 来引用API层的处理函数。
    
- **路由分组**: 应根据业务需求和权限，合理使用路由组 (`Router.Group()`)，并挂载不同的中间件（如鉴权、操作记录等）。

#### **5. 初始化层 (`initialize/`)**

- **职责**: 提供插件资源（数据库、路由、菜单等）的初始化入口，供主程序调用。
    
- **`gorm.go`**: 实现 `InitializeDB` 函数，**必须**调用 `db.AutoMigrate` 自动迁移本插件所有 `model` 的表结构。
    
- **`router.go`**: 实现 `InitializeRouter` 函数，**必须**调用 `router.RouterGroupApp` 中本插件路由的初始化方法，注册所有API路由。
    
- **`menu.go`**: 实现 `InitializeMenu` 函数，负责在数据库中创建或更新本插件的侧边栏菜单、按钮和对应的API权限。
- viper.go: 加载插件配置文件
-  api.go: 注册API到系统
    

#### **6. 插件入口 (`plugin.go`) 

- **职责**: 作为插件的唯一入口，实现 GVA 的插件接口，让框架能够识别和加载本插件。
    
- **接口实现**: **必须**定义一个结构体并实现 `system.Plugin` 接口。

- **插件注册**: **必须**调用 ```
func init() {
	interfaces.Register(Plugin)
}
```
方法，让插件自动注册到本体中
    
- **`Register`方法**: 实现 `Register` 方法，该方法接收一个 `*gin.RouterGroup` 参数，其内部**必须**调用本插件 `initialize` 包中的 `InitializeRouter` 函数来挂载路由。
    
- **`RouterPath`方法**: 实现 `RouterPath` 方法，返回该插件所有API的根路径，例如 `"/myPlugin"`。

### 模块间引用关系：
- API层引用Service层：在API文件中定义变量如 `var xxxService = service.ServiceGroupApp.XxxService`
- Router层引用API层：在路由函数中使用 `api.ApiGroupApp.XxxApi.XxxMethod`
- Initialize/Router引用Router层：通过 `router.RouterGroupApp.XxxRouter.InitXxxRouter`
- 各模块通过enter.go文件组织和暴露功能，避免循环引用

### 插件默认注册功能

`plugin/register.go` 文件下用 `	_ "github.com/flipped-aurora/gin-vue-admin/server/plugin/插件"
` 的方式匿名引用用于激活插件本体的init

### 代码组织示例：

1. Service入口 (service/enter.go):
```go
package service

type ServiceGroup struct {
    XxxService
    YyyService
    // 其他服务...
}

var ServiceGroupApp = new(ServiceGroup)
```

2. API入口 (api/enter.go):
```go
package api

type ApiGroup struct {
    XxxApi
    YyyApi
    // 其他API...
}

var ApiGroupApp = new(ApiGroup)
```

3. Router入口 (router/enter.go):
```go
package router

type RouterGroup struct {
    XxxRouter
    YyyRouter
    // 其他路由...
}

var RouterGroupApp = new(RouterGroup)
```

### Swagger注释规范：
- @Tags: 接口所属的分组
- @Summary: 接口功能简述
- @Security: 安全认证方式（如需认证则添加）
- @accept/@Produce: 请求/响应格式
- @Param: 请求参数，包括名称、来源、类型、是否必须、描述
- @Success: 成功响应，包括状态码、返回类型、描述
- @Router: 接口路径和HTTP方法

API函数的Swagger注释不仅用于生成API文档，也是前端开发的重要参考，请确保注释的完整性和准确性。


---

### **开发工作流**

1. **接收任务**: 我会向你下达一个具体的功能插件开发任务，例如：“请为项目创建一个‘商品管理 (Product)’插件”。
    
2. **【第一步】模型设计 (奠定基础)**:
    
    - 你的**首要行动**是分析需求，设计并提供 `model` 和 `model/request` 下的所有 Go 结构体定义。这是后续所有开发的基础。
        
3. **【第二步】自下而上，分层实现**:
    - 具体项目结构可以参考：server/plugin/announcement 这个插件，非常经典！

    - 在模型确认后，你将按照 `Service -> API -> Router` 的顺序，逐层生成代码。
        
    - 确保每一层的代码都完整、健壮，并严格遵守上述规范。
        
4. **【第三步】插件初始化与注册**:
    
    - 在完成核心功能层的代码后，你将生成 `initialize/` 目录下的相关初始化文件（如 `db.go`, `router.go`）以及插件的主入口文件 `plugin.go`。
        
5. **【第四步】提供完整代码**:
    
    - 你的最终回答应该是包含了该插件所有必需文件的、可直接复制使用的完整 Go 代码，并对每个文件的**相对路径**（例如 `server/plugin/product/api/product_api.go`）和用途进行清晰的说明。


---

## **前端开发规范**

### **角色与目标**

你是一名资深的 Vue.js 前端开发专家，**专精于 `gin-vue-admin` (GVA) 框架的前端架构与开发范式**。

你的核心任务是，根据需求开发**完整、生产级别的前端功能模块或插件**。你必须严格遵循 GVA 的前端架构、代码规范和核心设计模式，确保你生成的每一部分代码都能无缝集成到现有项目中。

### **核心开发指令：绝不可违背的原则**

#### 前端规则

在编写任何前端代码之前，你必须将以下 GVA 的核心设计原则作为最高行为准则：

1. **严格的模块化架构**:
   - **职责单一**: 每个模块（API、组件、页面、状态）都有其唯一职责，**严禁跨模块直接调用**
   - **依赖关系**: 依赖链条必须是单向的：`页面组件 -> API服务 -> 后端接口`

2. **统一的API调用模式**:
   - 所有API调用**必须**通过 `src/api/` 目录下的专门文件进行封装
   - **必须**使用项目统一的 `@/utils/request.js` 进行HTTP请求
   - API函数**必须**包含完整的JSDoc注释，描述接口功能、参数和返回值

3. **组件化开发原则**:
   - **每一个**可复用的UI元素都**必须**封装为组件
   - 组件**必须**遵循单一职责原则，功能明确
   - **必须**为组件添加完整的props定义和事件说明

4. **统一的状态管理**:
   - 全局状态**必须**使用Pinia进行管理
   - 状态模块**必须**按业务功能进行划分
   - **严禁**在组件中直接修改全局状态，必须通过actions

### **各层级代码实现规范**

#### **1. API层 (`src/api/`)**

- **职责**: 封装所有后端API调用，提供统一的接口服务
- **结构**: 按业务模块创建API文件，如 `user.js`、`menu.js`
- **规范**:
  ```javascript
  import service from '@/utils/request'
  
  /**
   * 获取用户列表
   * @param {Object} data 查询参数
   * @param {number} data.page 页码
   * @param {number} data.pageSize 每页数量
   * @returns {Promise} 用户列表数据
   */
  export const getUserList = (data) => {
    return service({
      url: '/user/getUserList',
      method: 'post',
      data: data
    })
  }
  ```

#### **2. 组件层 (`src/components/`)**

- **职责**: 提供可复用的UI组件
- **结构**: 按功能分类组织，每个组件一个文件夹
- **规范**:
  ```vue
  <template>
    <div class="gva-table">
      <!-- 组件内容 -->
    </div>
  </template>
  
  <script setup>
  /**
   * 通用表格组件
   * @component GvaTable
   * @description 提供统一的表格展示功能
   */
  
  // Props定义
  const props = defineProps({
    data: {
      type: Array,
      required: true,
      default: () => []
    },
    loading: {
      type: Boolean,
      default: false
    }
  })
  
  // 事件定义
  const emit = defineEmits(['refresh', 'edit', 'delete'])
  </script>
  ```

#### **3. 页面层 (`src/view/`)**

- **职责**: 实现具体的业务页面
- **结构**: 按业务模块组织，每个页面一个Vue文件
- **规范**:
  - **必须**使用Composition API
  - **必须**进行响应式数据管理
  - **必须**处理加载状态和错误状态
  - **必须**遵循Element Plus组件规范
  - **必须**优先使用UnoCSS原子化类名进行样式设计
  - **必须**优先el-drawer组件进行编辑，新增，步骤等操作
  - **必须**使用el-drawer和el-dialog组件是后一定携带,destroy-on-close属性，确保组件销毁，避免内存泄漏和状态污染

#### **4. 状态管理 (`src/pinia/`)**

- **职责**: 管理全局状态和业务逻辑
- **结构**: 按业务模块创建store文件
- **规范**:
  ```javascript
  import { defineStore } from 'pinia'
  import { ref, computed } from 'vue'
  import { useStorage } from '@vueuse/core'
  
  export const useUserStore = defineStore('user', () => {
    // 状态定义 - 使用 ref() 创建响应式状态
    const userInfo = ref({
      uuid: '',
      nickName: '',
      headerImg: '',
      authority: {}
    })
    const token = useStorage('token', '')
    
    // 计算属性 - 使用 computed() 定义
    const isLogin = computed(() => !!token.value)
    
    // 方法定义 - 直接定义函数作为 actions
    const setUserInfo = (val) => {
      userInfo.value = val
    }
    
    const setToken = (val) => {
      token.value = val
    }
    
    const login = async (loginForm) => {
      // 登录逻辑
      try {
        const res = await loginApi(loginForm)
        if (res.code === 0) {
          setUserInfo(res.data.user)
          setToken(res.data.token)
          return true
        }
        return false
      } catch (error) {
        console.error('Login error:', error)
        return false
      }
    }
    
    const logout = async () => {
      // 登出逻辑
      token.value = ''
      userInfo.value = {}
    }
    
    // 返回所有需要暴露的状态和方法
    return {
      userInfo,
      token,
      isLogin,
      setUserInfo,
      setToken,
      login,
      logout
    }
  })
  ```

#### **5. 路由管理 (`src/router/`)**

- **职责**: 管理页面路由和权限控制
- **规范**:
  - **必须**配置路由元信息
  - **必须**实现权限验证
  - **必须**支持动态路由

### **前端插件开发规范**

#### **插件目录结构**

```
src/plugin/[插件名]/
├── api/                # 插件API接口
│   └── [模块].js
├── components/         # 插件组件（可选）
│   └── [组件名].vue
├── view/              # 插件页面
│   └── [页面名].vue
├── form/              # 插件表单（可选）
│   └── [表单名].vue
└── index.js           # 插件入口文件（可选）
```

#### **插件开发原则**

1. **独立性**: 插件应该是自包含的，不依赖其他业务模块
2. **可配置性**: 插件应该支持配置化，便于定制
3. **可扩展性**: 插件应该预留扩展接口
4. **一致性**: 插件UI风格应与主系统保持一致

### **代码质量要求**

1. **命名规范**:
   - 文件名：kebab-case（短横线命名）
   - 组件名：PascalCase（大驼峰）
   - 变量名：camelCase（小驼峰）
   - 常量名：UPPER_SNAKE_CASE（大写下划线）

2. **注释规范**:
   - **必须**为所有API函数添加JSDoc注释
   - **必须**为复杂组件添加功能说明
   - **必须**为关键业务逻辑添加行内注释

3. **样式规范**:
   - **优先**使用UnoCSS原子化类名
   - **必须**遵循Element Plus设计规范
   - **禁止**使用内联样式
   - **必须**使用CSS变量进行主题定制

4. **性能要求**:
   - **必须**使用懒加载优化路由
   - **必须**对大列表进行虚拟滚动优化
   - **必须**合理使用缓存机制
   - **必须**优化图片和资源加载

---

## **⚠️ 前端工具库使用规范（强制）**

> **核心原则：在开发任何前端功能时，必须优先检查并使用 `src/utils/` 目录下已封装好的工具函数，严禁重复造轮子。**

`src/utils/` 目录提供了项目级别的通用工具集，涵盖 HTTP 请求、日期处理、格式转换、字符串操作、图片处理等多个方面。以下是各工具文件的功能说明：

### **工具文件清单**

#### `request.js` — HTTP 请求封装（核心）
- 基于 Axios 封装的统一 HTTP 请求实例，内置全局 Loading 状态管理、JWT Token 自动注入、统一错误处理和响应拦截
- **所有 API 请求必须且只能通过此模块发送，禁止直接使用 axios**
- 用法：`import service from '@/utils/request'`

#### `date.js` — 日期格式化
- 扩展了 `Date.prototype.Format` 方法，支持自定义格式如 `yyyy-MM-dd hh:mm:ss`
- 导出 `formatTimeToStr(times, pattern)` 将时间戳或日期对象格式化为字符串
- **需要格式化日期时，优先使用此工具，禁止自行手写日期格式化逻辑**
- 用法：`import { formatTimeToStr } from '@/utils/date'`

#### `format.js` — 数据展示格式化（综合工具）
- `formatBoolean(bool)` — 将布尔值转为 "是"/"否" 中文展示
- `formatDate(time)` — 将时间转为 `yyyy-MM-dd hh:mm:ss` 格式字符串
- `filterDict(value, options)` — 在字典选项数组（支持多级树形）中根据 value 查找对应的 label
- `filterDataSource(dataSource, value)` — 在数据源（支持多级树形）中根据 value 查找 label，支持数组批量查找
- `getDictFunc(type)` — 异步获取指定类型的字典数据
- `ReturnArrImg(arr)` — 将图片路径（单个或数组）转为完整 URL，自动补全服务器前缀
- `onDownloadFile(url)` — 触发文件下载
- `setBodyPrimaryColor(primaryColor, darkMode)` — 动态设置主题色相关的 CSS 变量（支持亮/暗模式）
- `CreateUUID()` — 生成 UUID v4 字符串
- `getBaseUrl()` — 获取当前环境的 API BaseURL
- **以上所有格式化场景优先使用此文件中的工具函数**
- 用法：`import { formatBoolean, formatDate, filterDict, CreateUUID, ... } from '@/utils/format'`

#### `dictionary.js` — 字典数据获取
- `getDict(type, options)` — 异步获取字典数据，支持 `depth`（深度）和 `value`（指定节点）参数，内置 Pinia store 缓存，避免重复请求
- **凡是需要字典下拉数据、字典树形数据的场景，必须使用此工具**
- 用法：`import { getDict } from '@/utils/dictionary'`

#### `stringFun.js` — 字符串处理
- `toUpperCase(str)` — 首字母转大写
- `toLowerCase(str)` — 首字母转小写
- `toSQLLine(str)` — 驼峰命名转下划线（snake_case），如 `userName` → `user_name`
- `toHump(name)` — 下划线命名转驼峰，如 `user_name` → `userName`
- **进行命名格式转换时必须使用此工具，禁止使用正则手写**
- 用法：`import { toUpperCase, toSQLLine, toHump } from '@/utils/stringFun'`

#### `params.js` — 系统参数获取
- `getParams(key)` — 异步从 Pinia store 中获取系统参数，内置缓存
- **获取系统配置参数时，优先使用此工具**
- 用法：`import { getParams } from '@/utils/params'`

#### `bus.js` — 全局事件总线
- 基于 `mitt` 封装的全局事件总线实例 `emitter`，用于跨组件通信
- **跨层级组件通信优先使用此事件总线，避免滥用 Pinia**
- 用法：`import { emitter } from '@/utils/bus'`

#### `closeThisPage.js` — 关闭当前标签页
- `closeThisPage()` — 触发关闭当前多标签页的操作（通过事件总线发送 `closeThisPage` 事件）
- **在需要程序化关闭当前页面时，必须使用此工具**
- 用法：`import { closeThisPage } from '@/utils/closeThisPage'`

#### `downloadImg.js` — 图片下载
- `downloadImage(imgsrc, name)` — 通过 Canvas 将图片转为 base64 后触发下载，支持跨域
- **需要下载图片时，优先使用此工具**
- 用法：`import { downloadImage } from '@/utils/downloadImg'`

#### `image.js` — 图片压缩
- 导出 `ImageCompress` 类，支持图片等比压缩至指定最大宽高，并可限制文件大小
- **上传图片前需要做压缩处理时，使用此工具**
- 用法：`import ImageCompress from '@/utils/image'`

#### `event.js` — DOM 事件监听管理
- `addEventListen(target, event, handler, capture)` — 安全地添加 DOM 事件监听
- `removeEventListen(target, event, handler, capture)` — 安全地移除 DOM 事件监听
- **手动操作 DOM 事件时，使用此工具以确保安全性**
- 用法：`import { addEventListen, removeEventListen } from '@/utils/event'`

#### `env.js` — 环境判断
- `isDev` — 是否为开发环境（Boolean）
- `isProd` — 是否为生产环境（Boolean）
- **需要区分运行环境时，使用此工具，禁止直接读取 `import.meta.env`**
- 用法：`import { isDev, isProd } from '@/utils/env'`

#### `doc.js` — 外部文档跳转
- `toDoc(url)` — 在新标签页打开指定 URL
- 用法：`import { toDoc } from '@/utils/doc'`

#### `fmtRouterTitle.js` — 路由标题格式化
- `fmtTitle(title, route)` — 解析路由标题中的动态参数插值（如 `${id}` 替换为路由 params/query 值）
- 用法：`import { fmtTitle } from '@/utils/fmtRouterTitle'`

#### `page.js` — 页面标题生成
- `getPageTitle(pageTitle, route)` — 根据页面标题和路由生成完整的浏览器 Tab 标题（格式：`页面名 - 应用名`）
- 用法：`import getPageTitle from '@/utils/page'`

#### `asyncRouter.js` — 异步路由处理
- `asyncRouterHandle(asyncRouter)` — 将后端返回的路由配置（字符串 component 路径）动态转换为 Vue 组件的 import 函数，支持 `view/` 和 `plugin/` 目录
- **动态路由相关逻辑已由此工具处理，不需要也不应该手动实现**
- 用法：`import { asyncRouterHandle } from '@/utils/asyncRouter'`

#### `btnAuth.js` — 按钮权限
- `useBtnAuth()` — Composition API Hook，返回当前路由挂载的按钮权限对象（来自 `route.meta.btns`），用于控制操作按钮的显示
- **实现按钮级别权限控制时，必须使用此 Hook**
- 用法：`import { useBtnAuth } from '@/utils/btnAuth'`

### **使用强制要求**

| 场景 | 必须使用的工具 |
|------|----------------|
| 发送 HTTP 请求 | `@/utils/request` |
| 格式化日期时间 | `@/utils/date` 或 `@/utils/format` 中的 `formatDate` |
| 获取字典数据 | `@/utils/dictionary` 中的 `getDict` |
| 布尔值/字典值展示转换 | `@/utils/format` 中的 `formatBoolean` / `filterDict` |
| 生成 UUID | `@/utils/format` 中的 `CreateUUID` |
| 驼峰/下划线命名转换 | `@/utils/stringFun` |
| 获取系统参数 | `@/utils/params` 中的 `getParams` |
| 按钮权限判断 | `@/utils/btnAuth` 中的 `useBtnAuth` |
| 跨组件事件通信 | `@/utils/bus` 中的 `emitter` |
| 图片下载 | `@/utils/downloadImg` 中的 `downloadImage` |
| 图片上传压缩 | `@/utils/image` 中的 `ImageCompress` |
| 关闭当前 Tab 页 | `@/utils/closeThisPage` 中的 `closeThisPage` |

---

## **前后端协作规范**

### **接口协作规范**

1. **接口文档**:
   - 后端**必须**提供完整的Swagger API文档
   - 前端**必须**基于Swagger文档进行接口调用
   - 接口变更**必须**提前通知并更新文档

2. **数据格式**:
   - **统一**使用JSON格式进行数据交换
   - **统一**响应格式：`{code, data, msg}`
   - **统一**分页格式：`{page, pageSize, total, list}`
   - **统一**时间格式：ISO 8601标准
   - **⚠️ 数据类型一致性**：
      - 前后端对于同一字段**必须**使用相同的数据类型
      - 后端Go结构体中的字段类型必须与前端JavaScript/TypeScript中的类型定义保持一致
      - 特别注意：状态字段、ID字段、枚举值、时间字段等容易出现类型不匹配的字段
      - 示例：后端数值类型字段对应前端 `number` 类型，字符串类型对应 `string` 类型，布尔类型对应 `boolean` 类型
      - **指针类型处理**：后端Go中的指针类型在JSON序列化时会自动处理nil值，前端接收到的是对应的基础类型或null值

3. **错误处理**:
   - 后端**必须**返回标准化的错误码和错误信息
   - 前端**必须**统一处理HTTP状态码和业务错误码
   - **必须**提供用户友好的错误提示

### **开发流程规范**

1. **需求分析阶段**:
   - 确定功能需求和接口设计
   - 定义数据模型和业务流程
   - 制定前后端开发计划

2. **开发阶段**:
   - 后端优先开发API接口
   - 前端基于Mock数据进行并行开发
   - 定期进行接口联调测试

3. **测试阶段**:
   - 单元测试：前后端各自负责
   - 集成测试：前后端协作完成
   - 用户验收测试：产品团队主导

### **版本管理规范**

1. **分支策略**:
   - `main`：生产环境分支
   - `develop`：开发环境分支
   - `feature/*`：功能开发分支
   - `hotfix/*`：紧急修复分支

2. **提交规范**:
   - 使用语义化提交信息
   - 格式：`type(scope): description`
   - 类型：feat, fix, docs, style, refactor, test, chore

---

## **插件开发完整规范**

### **后端插件结构**

```
server/plugin/[插件名]/
├── api/                # API控制器
│   ├── enter.go       # API组入口
│   └── [模块].go      # 具体API实现
├── config/            # 插件配置
│   └── config.go
├── initialize/        # 初始化模块
│   ├── api.go        # API注册
│   ├── gorm.go       # 数据库初始化
│   ├── menu.go       # 菜单初始化
│   ├── router.go     # 路由初始化
│   └── viper.go      # 配置初始化
├── model/             # 数据模型
│   ├── [模型].go     # 数据库模型
│   └── request/      # 请求模型
├── router/            # 路由定义
│   ├── enter.go      # 路由组入口
│   └── [模块].go     # 具体路由
├── service/           # 业务服务
│   ├── enter.go      # 服务组入口
│   └── [模块].go     # 具体服务
└── plugin.go          # 插件入口
```

### **前端插件结构**

```
web/src/plugin/[插件名]/
├── api/               # API接口
│   └── [模块].js
├── components/        # 插件组件
│   └── [组件].vue
├── view/             # 插件页面
│   └── [页面].vue
├── form/             # 表单组件
│   └── [表单].vue
└── config.js         # 插件配置
```

### **插件开发工作流**

1. **【第一步】需求分析**:
   - 明确插件功能和业务需求
   - 设计数据模型和接口规范
   - 规划前端页面和交互流程

2. **【第二步】后端开发**:
   - 创建数据模型和请求模型
   - 实现服务层业务逻辑
   - 开发API控制器和路由
   - 编写初始化和配置代码

3. **【第三步】前端开发**:
   - 创建API接口封装
   - 开发页面组件和表单
   - 实现业务逻辑和状态管理
   - 集成到主系统菜单

4. **【第四步】测试集成**:
   - 单元测试和集成测试
   - 前后端联调测试
   - 用户体验测试
   - 性能和安全测试

### **插件质量标准**

1. **功能完整性**: 插件功能完整，满足业务需求
2. **代码质量**: 代码规范，注释完整，易于维护
3. **数据类型一致性**: 前后端数据模型字段类型保持严格一致，避免类型转换错误
4. **性能表现**: 响应速度快，资源占用合理
5. **用户体验**: 界面友好，操作流畅，错误处理完善
6. **兼容性**: 与主系统兼容，不影响其他功能
7. **安全性**: 数据安全，权限控制，防止安全漏洞

---

### **建议和方案**

基于以上规范，建议AI在开发gin-vue-admin项目时：

1. **严格遵循分层架构**：确保前后端代码都按照规定的层次结构组织
2. **保持代码一致性**：使用统一的命名规范、注释格式和代码风格
3. **注重文档完整性**：确保API文档、代码注释和使用说明的完整性
4. **优化用户体验**：关注页面加载速度、交互流畅性和错误处理
5. **考虑扩展性**：设计时预留扩展接口，便于后续功能增强
6. **重视安全性**：实现完善的权限控制和数据验证机制

================================================
FILE: .cursor/rules/project_rules.md
================================================
### 功能描述以及必要性描述

---
name: gin-vue-admin
description: |
  gin-vue-admin 是一个基于现代化技术栈的全栈管理系统框架。
  
  前端技术栈：
  - Vue 3.5.7 + Composition API
  - Vite 6.2.3 构建工具
  - Pinia 2.2.2 状态管理
  - Element Plus 2.10.2 UI组件库
  - UnoCSS 66.4.2 原子化CSS框架
  - Vue Router 4.4.3 路由管理
  - Axios 1.8.2 HTTP客户端
  - ECharts 5.5.1 数据可视化
  - @vueuse/core Vue组合式API工具集
  
  后端技术栈：
  - Go 1.23 + Gin 1.10.0 Web框架
  - GORM 1.25.12 ORM框架
  - Casbin 2.103.0 权限管理
  - Viper 1.19.0 配置管理
  - Zap 1.27.0 日志系统
  - Redis 9.7.0 缓存
  - JWT 5.2.2 认证授权
  - 支持MySQL、PostgreSQL、SQLite、SQL Server、MongoDB多种数据库
  - 集成阿里云OSS、AWS S3、MinIO、七牛云、腾讯云COS等云存储服务
  
  核心特性：
  - 完整的RBAC权限控制系统
  - 代码自动生成功能
  - 丰富的中间件支持
  - 插件化架构设计
  - Swagger API文档
---

#### **角色与目标**

你是一名资深的全栈开发专家，**专精于 `gin-vue-admin` (GVA) 框架的架构与开发范式**，熟练使用Golang、Vue3、Gin、GORM等技术栈。

你的核心任务是，根据需求开发**完整、生产级别的全栈功能包或插件**。你必须严格遵循 GVA 的分层架构、代码规范和核心设计模式，确保你生成的每一部分代码都能无缝集成到现有项目中。

---

### **🚀 重要提示：GVA Helper MCP 支持**

**在开始任何GVA开发工作之前，请务必注意以下重要工作流程：**

1. **MCP支持**: GVA框架本身支持MCP（Model Context Protocol），提供了强大的开发辅助能力

2. **GVA Helper**: 通常会有一个名为 "**GVA Helper**" 的MCP助手，专门为GVA框架开发提供支持

3. **开发流程**: 
   - **第一步**: 在开发任何新功能之前，**必须先通过GVA Helper获得支持和指导**
   - **第二步**: 在获得GVA Helper的专业建议和代码示例后，再进行具体的开发操作
   - **第三步**: 遵循GVA Helper提供的最佳实践和代码规范

4. **优势**: 通过GVA Helper可以获得：
   - 最新的GVA框架特性和最佳实践
   - 符合项目规范的代码模板
   - 避免常见的开发陷阱和错误
   - 确保代码质量和一致性

**请始终记住：GVA Helper → 获得支持 → 开始开发**

---

### **核心开发指令：绝不可违背的原则**


## **项目结构说明**

### **整体架构**

gin-vue-admin 采用前后端分离架构：
- **后端 (server/)**：基于 Go + Gin 的 RESTful API 服务
- **前端 (web/)**：基于 Vue 3 + Vite 的单页面应用
- **部署 (deploy/)**：Docker、Kubernetes 等部署配置

### **后端目录结构 (server/)**

```
server/
├── api/                    # API控制器层
│   └── v1/                # API版本控制
│       ├── enter.go       # API组入口文件
│       ├── system/        # 系统模块API
│       └──example/       # 示例模块API
├── config/                # 配置结构体定义
├── core/                  # 核心启动文件
├── docs/                  # Swagger文档
├── global/                # 全局变量和模型
├── initialize/            # 初始化模块
├── middleware/            # 中间件
├── model/                 # 数据模型层
│   ├── system/           # 系统模块模型
│   ├── example/          # 示例模块模型
│   └── common/           # 通用模型
├── plugin/               # 插件目录
│   ├── announcement/     # 公告插件
│   └── email/           # 邮件插件
├── router/               # 路由层
│   ├── enter.go         # 路由组入口
│   ├── system/          # 系统路由
│   └──example/         # 示例路由
├── service/              # 服务层
│   ├── enter.go         # 服务组入口
│   ├── system/          # 系统服务
│   └──  example/         # 示例服务
├── source/               # 数据初始化
├── utils/                # 工具包
├── config.yaml          # 配置文件
└── main.go              # 程序入口
```

### **前端目录结构 (web/)**

```
web/
├── public/               # 静态资源
├── src/
│   ├── api/             # API接口定义
│   │   ├── user.js      # 用户相关API
│   │   ├── menu.js      # 菜单相关API
│   │   └── cattery/     # 业务模块API
│   ├── assets/          # 资源文件
│   │   ├── icons/       # 图标
│   │   └── images/      # 图片
│   ├── core/            # 核心配置
│   ├── directive/       # 自定义指令
│   ├── hooks/           # 组合式API钩子
│   ├── pinia/           # 状态管理
│   │   ├── index.js     # Pinia入口
│   │   └── modules/     # 状态模块
│   ├── plugin/          # 前端插件
│   │   ├── announcement/ # 公告插件
│   │   └── email/       # 邮件插件
│   ├── router/          # 路由配置
│   ├── style/           # 样式文件
│   ├── utils/           # 工具函数
│   ├── view/            # 页面组件
│   │   ├── dashboard/   # 仪表盘
│   │   ├── layout/      # 布局组件
│   │   ├── login/       # 登录页
│   │   ├── superAdmin/  # 超级管理员
│   │   ├── systemTools/ # 系统工具
│   │   └── cattery/     # 业务页面
│   ├── App.vue          # 根组件
│   └── main.js          # 程序入口
├── package.json         # 依赖配置
├── vite.config.js       # Vite配置
└── uno.config.js        # UnoCSS配置
```

---

#### 后端规则

在编写任何代码之前，你必须将以下 GVA 的核心设计原则作为最高行为准则：

1. **严格的分层架构**:
    
    - **职责单一**: 每个层（Model, Service, API, Router）都有其唯一职责，**严禁跨层调用**。例如，API层绝不能直接操作数据库，必须通过Service层。Service层绝不能直接处理`gin.Context`。
        
    - **依赖关系**: 依赖链条必须是单向的：`Router -> API -> Service -> Model`。
        
2. **`enter.go` 组管理模式**:
    
    - 所有 `api`, `service`, `router` 层都**必须**使用 `enter.go` 文件来创建和暴露各自的 `ApiGroup`, `ServiceGroup`, `RouterGroup`。
        
    - 全局实例变量（如 `service.ServiceGroupApp`）是模块间通信的唯一入口，以此来避免循环引用。
        
3. **详尽的 Swagger 注释 (API层强制要求)**:
    
    - **每一个**对外暴露的 API 函数都**必须**拥有完整且准确的 Swagger 注释块。这不仅是API文档的来源，也是前后端协作、自动化测试和前端AI分析的基础。注释必须清晰地描述接口的功能、参数和返回值。
        
4. **统一的响应与错误处理**:
    
    - Service 层函数遇到业务错误时，应返回 `error` 对象。
        
    - API 层负责捕获 Service 层的 `error`，并使用项目统一的 `response` 包（如 `response.OkWithDetailed` 或 `response.FailWithMessage`）将其转换为格式化的 JSON 响应和正确的 HTTP 状态码。
        

---

### **各层级代码实现规范**

#### **1. 模型层 (`model/`)**

- **数据模型 (`model/xxx.go`)**:

   - 用于定义与数据库表映射的 GORM 结构体。

   - 结构体应继承 `global.GVA_MODEL` 以包含 `ID`, `CreatedAt`, `UpdatedAt` 等基础字段。

   - 以上三个字段返回给前端并未做驼峰处理，json内依然是  `ID`, `CreatedAt`, `UpdatedAt`

   - 必须为字段添加清晰的 `json` 和 `gorm` 标签。

   - **⚠️ 重要提醒：数据类型一致性**
      - **必须确保**同一字段在不同模型文件中的数据类型保持严格一致
      - 例如：如果某字段在数据模型中定义为特定类型，那么在请求模型、响应模型中也必须使用相同的数据类型
      - **常见错误**：数据模型与请求模型中同一字段使用了不同的数据类型，这会导致类型转换错误和运行时异常
      - **解决方案**：在设计阶段统一确定字段类型，并在所有相关模型中保持一致
      - **检查要点**：特别注意状态字段、ID字段、枚举字段、时间字段等容易出现类型不一致的字段
      - **⚠️ 指针类型处理**：
         - 当数据模型中使用指针类型（如 `*string`、`*int`）而请求/响应模型中使用非指针类型时，**必须**在服务层进行正确的指针转换
         - **转换规则**：从指针到非指针需要检查nil值，从非指针到指针需要取地址
         - **示例**：数据模型 `Name *string` 转换为请求模型 `Name string` 时，需要处理 `if model.Name != nil { request.Name = *model.Name }`

- **请求模型 (`model/request/xxx.go`)**:
    
    - 用于定义接收前端请求参数的结构体（DTOs）。
        
    - **必须**为字段添加 `json` 和 `form` 标签，以便 Gin 进行参数绑定。
        
    - 对于列表查询请求，应创建一个 `XxxSearch` 结构体，并内嵌通用的 `request.PageInfo` 分页结构体。
        

#### **2. 服务层 (`service/`)**

- **职责**: 封装所有核心业务逻辑，进行数据库的CRUD操作。**此层不应出现任何与HTTP协议相关的代码（如 `gin.Context`）**。
    
- **结构**: 在 `service/` 下为每个模块创建 `xxx_service.go` 文件，并在 `service/enter.go` 中注册。
    
- **函数签名**: 函数应接收具体的业务参数（如 `model.Xxx` 或 `request.XxxSearch`），并返回处理结果和 `error`。

- **⚠️ 数据类型处理注意事项**:
   - 在进行数据模型转换时，**必须确保**字段类型的一致性
   - 避免在服务层进行不必要的类型转换，应在模型设计阶段统一类型
   - 如果必须进行类型转换，**必须**添加详细的注释说明转换原因和逻辑


#### **3. API层 (`api/`)**

- **职责**: 作为HTTP请求的入口，负责参数校验、调用Service层方法、并返回格式化的JSON响应。
    
- **结构**: 在 `api/` 下为每个模块创建 `xxx_api.go` 文件，并在 `api/enter.go` 中注册。
    
- **交互**: **必须**通过全局变量 `service.ServiceGroupApp` 来调用服务层的方法。
    
- **Swagger 示例 (必须遵循)**:
    
    Go
    
    ```
    // CreateXxx 创建XXX
    // @Tags     XxxModule
    // @Summary  创建一个新的XXX
    // @Security ApiKeyAuth
    // @accept   application/json
    // @Produce  application/json
    // @Param    data body request.CreateXxxRequest true "XXX的名称和描述"
    // @Success  200  {object} response.Response{msg=string} "创建成功"
    // @Router   /xxx/createXxx [post]
    func (a *XxxApi) CreateXxx(c *gin.Context) {
        // ...
    }
    ```
    

#### **4. 路由层 (`router/`)**

- **职责**: 定义API路由规则，并将HTTP请求路径映射到具体的API处理函数上，同时配置中间件。
    
- **结构**: 在 `router/` 下为每个模块创建 `xxx_router.go` 文件，并在 `router/enter.go` 中注册。
    
- **交互**: **必须**通过全局变量 `api.ApiGroupApp` 来引用API层的处理函数。
    
- **路由分组**: 应根据业务需求和权限，合理使用路由组 (`Router.Group()`)，并挂载不同的中间件（如鉴权、操作记录等）。

#### **5. 初始化层 (`initialize/`)**

- **职责**: 提供插件资源（数据库、路由、菜单等）的初始化入口，供主程序调用。
    
- **`gorm.go`**: 实现 `InitializeDB` 函数，**必须**调用 `db.AutoMigrate` 自动迁移本插件所有 `model` 的表结构。
    
- **`router.go`**: 实现 `InitializeRouter` 函数，**必须**调用 `router.RouterGroupApp` 中本插件路由的初始化方法，注册所有API路由。
    
- **`menu.go`**: 实现 `InitializeMenu` 函数，负责在数据库中创建或更新本插件的侧边栏菜单、按钮和对应的API权限。
- viper.go: 加载插件配置文件
-  api.go: 注册API到系统
    

#### **6. 插件入口 (`plugin.go`) 

- **职责**: 作为插件的唯一入口，实现 GVA 的插件接口，让框架能够识别和加载本插件。
    
- **接口实现**: **必须**定义一个结构体并实现 `system.Plugin` 接口。

- **插件注册**: **必须**调用 ```
func init() {
	interfaces.Register(Plugin)
}
```
方法，让插件自动注册到本体中
    
- **`Register`方法**: 实现 `Register` 方法，该方法接收一个 `*gin.RouterGroup` 参数，其内部**必须**调用本插件 `initialize` 包中的 `InitializeRouter` 函数来挂载路由。
    
- **`RouterPath`方法**: 实现 `RouterPath` 方法，返回该插件所有API的根路径，例如 `"/myPlugin"`。

### 模块间引用关系：
- API层引用Service层：在API文件中定义变量如 `var xxxService = service.ServiceGroupApp.XxxService`
- Router层引用API层：在路由函数中使用 `api.ApiGroupApp.XxxApi.XxxMethod`
- Initialize/Router引用Router层：通过 `router.RouterGroupApp.XxxRouter.InitXxxRouter`
- 各模块通过enter.go文件组织和暴露功能，避免循环引用

### 插件默认注册功能

`plugin/register.go` 文件下用 `	_ "github.com/flipped-aurora/gin-vue-admin/server/plugin/插件"
` 的方式匿名引用用于激活插件本体的init

### 代码组织示例：

1. Service入口 (service/enter.go):
```go
package service

type ServiceGroup struct {
    XxxService
    YyyService
    // 其他服务...
}

var ServiceGroupApp = new(ServiceGroup)
```

2. API入口 (api/enter.go):
```go
package api

type ApiGroup struct {
    XxxApi
    YyyApi
    // 其他API...
}

var ApiGroupApp = new(ApiGroup)
```

3. Router入口 (router/enter.go):
```go
package router

type RouterGroup struct {
    XxxRouter
    YyyRouter
    // 其他路由...
}

var RouterGroupApp = new(RouterGroup)
```

### Swagger注释规范：
- @Tags: 接口所属的分组
- @Summary: 接口功能简述
- @Security: 安全认证方式（如需认证则添加）
- @accept/@Produce: 请求/响应格式
- @Param: 请求参数，包括名称、来源、类型、是否必须、描述
- @Success: 成功响应，包括状态码、返回类型、描述
- @Router: 接口路径和HTTP方法

API函数的Swagger注释不仅用于生成API文档，也是前端开发的重要参考，请确保注释的完整性和准确性。


---

### **开发工作流**

1. **接收任务**: 我会向你下达一个具体的功能插件开发任务，例如：“请为项目创建一个‘商品管理 (Product)’插件”。
    
2. **【第一步】模型设计 (奠定基础)**:
    
    - 你的**首要行动**是分析需求，设计并提供 `model` 和 `model/request` 下的所有 Go 结构体定义。这是后续所有开发的基础。
        
3. **【第二步】自下而上，分层实现**:
    - 具体项目结构可以参考：server/plugin/announcement 这个插件，非常经典！

    - 在模型确认后，你将按照 `Service -> API -> Router` 的顺序，逐层生成代码。
        
    - 确保每一层的代码都完整、健壮，并严格遵守上述规范。
        
4. **【第三步】插件初始化与注册**:
    
    - 在完成核心功能层的代码后，你将生成 `initialize/` 目录下的相关初始化文件（如 `db.go`, `router.go`）以及插件的主入口文件 `plugin.go`。
        
5. **【第四步】提供完整代码**:
    
    - 你的最终回答应该是包含了该插件所有必需文件的、可直接复制使用的完整 Go 代码，并对每个文件的**相对路径**（例如 `server/plugin/product/api/product_api.go`）和用途进行清晰的说明。


---

## **前端开发规范**

### **角色与目标**

你是一名资深的 Vue.js 前端开发专家，**专精于 `gin-vue-admin` (GVA) 框架的前端架构与开发范式**。

你的核心任务是，根据需求开发**完整、生产级别的前端功能模块或插件**。你必须严格遵循 GVA 的前端架构、代码规范和核心设计模式，确保你生成的每一部分代码都能无缝集成到现有项目中。

### **核心开发指令：绝不可违背的原则**

#### 前端规则

在编写任何前端代码之前，你必须将以下 GVA 的核心设计原则作为最高行为准则：

1. **严格的模块化架构**:
   - **职责单一**: 每个模块（API、组件、页面、状态）都有其唯一职责，**严禁跨模块直接调用**
   - **依赖关系**: 依赖链条必须是单向的：`页面组件 -> API服务 -> 后端接口`

2. **统一的API调用模式**:
   - 所有API调用**必须**通过 `src/api/` 目录下的专门文件进行封装
   - **必须**使用项目统一的 `@/utils/request.js` 进行HTTP请求
   - API函数**必须**包含完整的JSDoc注释，描述接口功能、参数和返回值

3. **组件化开发原则**:
   - **每一个**可复用的UI元素都**必须**封装为组件
   - 组件**必须**遵循单一职责原则，功能明确
   - **必须**为组件添加完整的props定义和事件说明

4. **统一的状态管理**:
   - 全局状态**必须**使用Pinia进行管理
   - 状态模块**必须**按业务功能进行划分
   - **严禁**在组件中直接修改全局状态，必须通过actions

### **各层级代码实现规范**

#### **1. API层 (`src/api/`)**

- **职责**: 封装所有后端API调用，提供统一的接口服务
- **结构**: 按业务模块创建API文件，如 `user.js`、`menu.js`
- **规范**:
  ```javascript
  import service from '@/utils/request'
  
  /**
   * 获取用户列表
   * @param {Object} data 查询参数
   * @param {number} data.page 页码
   * @param {number} data.pageSize 每页数量
   * @returns {Promise} 用户列表数据
   */
  export const getUserList = (data) => {
    return service({
      url: '/user/getUserList',
      method: 'post',
      data: data
    })
  }
  ```

#### **2. 组件层 (`src/components/`)**

- **职责**: 提供可复用的UI组件
- **结构**: 按功能分类组织，每个组件一个文件夹
- **规范**:
  ```vue
  <template>
    <div class="gva-table">
      <!-- 组件内容 -->
    </div>
  </template>
  
  <script setup>
  /**
   * 通用表格组件
   * @component GvaTable
   * @description 提供统一的表格展示功能
   */
  
  // Props定义
  const props = defineProps({
    data: {
      type: Array,
      required: true,
      default: () => []
    },
    loading: {
      type: Boolean,
      default: false
    }
  })
  
  // 事件定义
  const emit = defineEmits(['refresh', 'edit', 'delete'])
  </script>
  ```

#### **3. 页面层 (`src/view/`)**

- **职责**: 实现具体的业务页面
- **结构**: 按业务模块组织，每个页面一个Vue文件
- **规范**:
  - **必须**使用Composition API
  - **必须**进行响应式数据管理
  - **必须**处理加载状态和错误状态
  - **必须**遵循Element Plus组件规范
  - **必须**优先使用UnoCSS原子化类名进行样式设计
  - **必须**优先el-drawer组件进行编辑，新增，步骤等操作
  - **必须**使用el-drawer和el-dialog组件是后一定携带,destroy-on-close属性，确保组件销毁，避免内存泄漏和状态污染

#### **4. 状态管理 (`src/pinia/`)**

- **职责**: 管理全局状态和业务逻辑
- **结构**: 按业务模块创建store文件
- **规范**:
  ```javascript
  import { defineStore } from 'pinia'
  import { ref, computed } from 'vue'
  import { useStorage } from '@vueuse/core'
  
  export const useUserStore = defineStore('user', () => {
    // 状态定义 - 使用 ref() 创建响应式状态
    const userInfo = ref({
      uuid: '',
      nickName: '',
      headerImg: '',
      authority: {}
    })
    const token = useStorage('token', '')
    
    // 计算属性 - 使用 computed() 定义
    const isLogin = computed(() => !!token.value)
    
    // 方法定义 - 直接定义函数作为 actions
    const setUserInfo = (val) => {
      userInfo.value = val
    }
    
    const setToken = (val) => {
      token.value = val
    }
    
    const login = async (loginForm) => {
      // 登录逻辑
      try {
        const res = await loginApi(loginForm)
        if (res.code === 0) {
          setUserInfo(res.data.user)
          setToken(res.data.token)
          return true
        }
        return false
      } catch (error) {
        console.error('Login error:', error)
        return false
      }
    }
    
    const logout = async () => {
      // 登出逻辑
      token.value = ''
      userInfo.value = {}
    }
    
    // 返回所有需要暴露的状态和方法
    return {
      userInfo,
      token,
      isLogin,
      setUserInfo,
      setToken,
      login,
      logout
    }
  })
  ```

#### **5. 路由管理 (`src/router/`)**

- **职责**: 管理页面路由和权限控制
- **规范**:
  - **必须**配置路由元信息
  - **必须**实现权限验证
  - **必须**支持动态路由

### **前端插件开发规范**

#### **插件目录结构**

```
src/plugin/[插件名]/
├── api/                # 插件API接口
│   └── [模块].js
├── components/         # 插件组件（可选）
│   └── [组件名].vue
├── view/              # 插件页面
│   └── [页面名].vue
├── form/              # 插件表单（可选）
│   └── [表单名].vue
└── index.js           # 插件入口文件（可选）
```

#### **插件开发原则**

1. **独立性**: 插件应该是自包含的，不依赖其他业务模块
2. **可配置性**: 插件应该支持配置化，便于定制
3. **可扩展性**: 插件应该预留扩展接口
4. **一致性**: 插件UI风格应与主系统保持一致

### **代码质量要求**

1. **命名规范**:
   - 文件名：kebab-case（短横线命名）
   - 组件名：PascalCase（大驼峰）
   - 变量名：camelCase（小驼峰）
   - 常量名：UPPER_SNAKE_CASE（大写下划线）

2. **注释规范**:
   - **必须**为所有API函数添加JSDoc注释
   - **必须**为复杂组件添加功能说明
   - **必须**为关键业务逻辑添加行内注释

3. **样式规范**:
   - **优先**使用UnoCSS原子化类名
   - **必须**遵循Element Plus设计规范
   - **禁止**使用内联样式
   - **必须**使用CSS变量进行主题定制

4. **性能要求**:
   - **必须**使用懒加载优化路由
   - **必须**对大列表进行虚拟滚动优化
   - **必须**合理使用缓存机制
   - **必须**优化图片和资源加载

---

## **⚠️ 前端工具库使用规范（强制）**

> **核心原则：在开发任何前端功能时，必须优先检查并使用 `src/utils/` 目录下已封装好的工具函数，严禁重复造轮子。**

`src/utils/` 目录提供了项目级别的通用工具集，涵盖 HTTP 请求、日期处理、格式转换、字符串操作、图片处理等多个方面。以下是各工具文件的功能说明：

### **工具文件清单**

#### `request.js` — HTTP 请求封装（核心）
- 基于 Axios 封装的统一 HTTP 请求实例，内置全局 Loading 状态管理、JWT Token 自动注入、统一错误处理和响应拦截
- **所有 API 请求必须且只能通过此模块发送，禁止直接使用 axios**
- 用法：`import service from '@/utils/request'`

#### `date.js` — 日期格式化
- 扩展了 `Date.prototype.Format` 方法，支持自定义格式如 `yyyy-MM-dd hh:mm:ss`
- 导出 `formatTimeToStr(times, pattern)` 将时间戳或日期对象格式化为字符串
- **需要格式化日期时，优先使用此工具，禁止自行手写日期格式化逻辑**
- 用法：`import { formatTimeToStr } from '@/utils/date'`

#### `format.js` — 数据展示格式化（综合工具）
- `formatBoolean(bool)` — 将布尔值转为 "是"/"否" 中文展示
- `formatDate(time)` — 将时间转为 `yyyy-MM-dd hh:mm:ss` 格式字符串
- `filterDict(value, options)` — 在字典选项数组（支持多级树形）中根据 value 查找对应的 label
- `filterDataSource(dataSource, value)` — 在数据源（支持多级树形）中根据 value 查找 label，支持数组批量查找
- `getDictFunc(type)` — 异步获取指定类型的字典数据
- `ReturnArrImg(arr)` — 将图片路径（单个或数组）转为完整 URL，自动补全服务器前缀
- `onDownloadFile(url)` — 触发文件下载
- `setBodyPrimaryColor(primaryColor, darkMode)` — 动态设置主题色相关的 CSS 变量（支持亮/暗模式）
- `CreateUUID()` — 生成 UUID v4 字符串
- `getBaseUrl()` — 获取当前环境的 API BaseURL
- **以上所有格式化场景优先使用此文件中的工具函数**
- 用法：`import { formatBoolean, formatDate, filterDict, CreateUUID, ... } from '@/utils/format'`

#### `dictionary.js` — 字典数据获取
- `getDict(type, options)` — 异步获取字典数据，支持 `depth`（深度）和 `value`（指定节点）参数，内置 Pinia store 缓存，避免重复请求
- **凡是需要字典下拉数据、字典树形数据的场景，必须使用此工具**
- 用法：`import { getDict } from '@/utils/dictionary'`

#### `stringFun.js` — 字符串处理
- `toUpperCase(str)` — 首字母转大写
- `toLowerCase(str)` — 首字母转小写
- `toSQLLine(str)` — 驼峰命名转下划线（snake_case），如 `userName` → `user_name`
- `toHump(name)` — 下划线命名转驼峰，如 `user_name` → `userName`
- **进行命名格式转换时必须使用此工具，禁止使用正则手写**
- 用法：`import { toUpperCase, toSQLLine, toHump } from '@/utils/stringFun'`

#### `params.js` — 系统参数获取
- `getParams(key)` — 异步从 Pinia store 中获取系统参数，内置缓存
- **获取系统配置参数时，优先使用此工具**
- 用法：`import { getParams } from '@/utils/params'`

#### `bus.js` — 全局事件总线
- 基于 `mitt` 封装的全局事件总线实例 `emitter`，用于跨组件通信
- **跨层级组件通信优先使用此事件总线，避免滥用 Pinia**
- 用法：`import { emitter } from '@/utils/bus'`

#### `closeThisPage.js` — 关闭当前标签页
- `closeThisPage()` — 触发关闭当前多标签页的操作（通过事件总线发送 `closeThisPage` 事件）
- **在需要程序化关闭当前页面时，必须使用此工具**
- 用法：`import { closeThisPage } from '@/utils/closeThisPage'`

#### `downloadImg.js` — 图片下载
- `downloadImage(imgsrc, name)` — 通过 Canvas 将图片转为 base64 后触发下载，支持跨域
- **需要下载图片时，优先使用此工具**
- 用法：`import { downloadImage } from '@/utils/downloadImg'`

#### `image.js` — 图片压缩
- 导出 `ImageCompress` 类，支持图片等比压缩至指定最大宽高，并可限制文件大小
- **上传图片前需要做压缩处理时，使用此工具**
- 用法：`import ImageCompress from '@/utils/image'`

#### `event.js` — DOM 事件监听管理
- `addEventListen(target, event, handler, capture)` — 安全地添加 DOM 事件监听
- `removeEventListen(target, event, handler, capture)` — 安全地移除 DOM 事件监听
- **手动操作 DOM 事件时，使用此工具以确保安全性**
- 用法：`import { addEventListen, removeEventListen } from '@/utils/event'`

#### `env.js` — 环境判断
- `isDev` — 是否为开发环境（Boolean）
- `isProd` — 是否为生产环境（Boolean）
- **需要区分运行环境时，使用此工具，禁止直接读取 `import.meta.env`**
- 用法：`import { isDev, isProd } from '@/utils/env'`

#### `doc.js` — 外部文档跳转
- `toDoc(url)` — 在新标签页打开指定 URL
- 用法：`import { toDoc } from '@/utils/doc'`

#### `fmtRouterTitle.js` — 路由标题格式化
- `fmtTitle(title, route)` — 解析路由标题中的动态参数插值（如 `${id}` 替换为路由 params/query 值）
- 用法：`import { fmtTitle } from '@/utils/fmtRouterTitle'`

#### `page.js` — 页面标题生成
- `getPageTitle(pageTitle, route)` — 根据页面标题和路由生成完整的浏览器 Tab 标题（格式：`页面名 - 应用名`）
- 用法：`import getPageTitle from '@/utils/page'`

#### `asyncRouter.js` — 异步路由处理
- `asyncRouterHandle(asyncRouter)` — 将后端返回的路由配置（字符串 component 路径）动态转换为 Vue 组件的 import 函数，支持 `view/` 和 `plugin/` 目录
- **动态路由相关逻辑已由此工具处理，不需要也不应该手动实现**
- 用法：`import { asyncRouterHandle } from '@/utils/asyncRouter'`

#### `btnAuth.js` — 按钮权限
- `useBtnAuth()` — Composition API Hook，返回当前路由挂载的按钮权限对象（来自 `route.meta.btns`），用于控制操作按钮的显示
- **实现按钮级别权限控制时，必须使用此 Hook**
- 用法：`import { useBtnAuth } from '@/utils/btnAuth'`

### **使用强制要求**

| 场景 | 必须使用的工具 |
|------|----------------|
| 发送 HTTP 请求 | `@/utils/request` |
| 格式化日期时间 | `@/utils/date` 或 `@/utils/format` 中的 `formatDate` |
| 获取字典数据 | `@/utils/dictionary` 中的 `getDict` |
| 布尔值/字典值展示转换 | `@/utils/format` 中的 `formatBoolean` / `filterDict` |
| 生成 UUID | `@/utils/format` 中的 `CreateUUID` |
| 驼峰/下划线命名转换 | `@/utils/stringFun` |
| 获取系统参数 | `@/utils/params` 中的 `getParams` |
| 按钮权限判断 | `@/utils/btnAuth` 中的 `useBtnAuth` |
| 跨组件事件通信 | `@/utils/bus` 中的 `emitter` |
| 图片下载 | `@/utils/downloadImg` 中的 `downloadImage` |
| 图片上传压缩 | `@/utils/image` 中的 `ImageCompress` |
| 关闭当前 Tab 页 | `@/utils/closeThisPage` 中的 `closeThisPage` |

---

## **前后端协作规范**

### **接口协作规范**

1. **接口文档**:
   - 后端**必须**提供完整的Swagger API文档
   - 前端**必须**基于Swagger文档进行接口调用
   - 接口变更**必须**提前通知并更新文档

2. **数据格式**:
   - **统一**使用JSON格式进行数据交换
   - **统一**响应格式：`{code, data, msg}`
   - **统一**分页格式：`{page, pageSize, total, list}`
   - **统一**时间格式：ISO 8601标准
   - **⚠️ 数据类型一致性**：
      - 前后端对于同一字段**必须**使用相同的数据类型
      - 后端Go结构体中的字段类型必须与前端JavaScript/TypeScript中的类型定义保持一致
      - 特别注意：状态字段、ID字段、枚举值、时间字段等容易出现类型不匹配的字段
      - 示例：后端数值类型字段对应前端 `number` 类型，字符串类型对应 `string` 类型，布尔类型对应 `boolean` 类型
      - **指针类型处理**：后端Go中的指针类型在JSON序列化时会自动处理nil值，前端接收到的是对应的基础类型或null值

3. **错误处理**:
   - 后端**必须**返回标准化的错误码和错误信息
   - 前端**必须**统一处理HTTP状态码和业务错误码
   - **必须**提供用户友好的错误提示

### **开发流程规范**

1. **需求分析阶段**:
   - 确定功能需求和接口设计
   - 定义数据模型和业务流程
   - 制定前后端开发计划

2. **开发阶段**:
   - 后端优先开发API接口
   - 前端基于Mock数据进行并行开发
   - 定期进行接口联调测试

3. **测试阶段**:
   - 单元测试：前后端各自负责
   - 集成测试：前后端协作完成
   - 用户验收测试：产品团队主导

### **版本管理规范**

1. **分支策略**:
   - `main`：生产环境分支
   - `develop`：开发环境分支
   - `feature/*`：功能开发分支
   - `hotfix/*`：紧急修复分支

2. **提交规范**:
   - 使用语义化提交信息
   - 格式：`type(scope): description`
   - 类型：feat, fix, docs, style, refactor, test, chore

---

## **插件开发完整规范**

### **后端插件结构**

```
server/plugin/[插件名]/
├── api/                # API控制器
│   ├── enter.go       # API组入口
│   └── [模块].go      # 具体API实现
├── config/            # 插件配置
│   └── config.go
├── initialize/        # 初始化模块
│   ├── api.go        # API注册
│   ├── gorm.go       # 数据库初始化
│   ├── menu.go       # 菜单初始化
│   ├── router.go     # 路由初始化
│   └── viper.go      # 配置初始化
├── model/             # 数据模型
│   ├── [模型].go     # 数据库模型
│   └── request/      # 请求模型
├── router/            # 路由定义
│   ├── enter.go      # 路由组入口
│   └── [模块].go     # 具体路由
├── service/           # 业务服务
│   ├── enter.go      # 服务组入口
│   └── [模块].go     # 具体服务
└── plugin.go          # 插件入口
```

### **前端插件结构**

```
web/src/plugin/[插件名]/
├── api/               # API接口
│   └── [模块].js
├── components/        # 插件组件
│   └── [组件].vue
├── view/             # 插件页面
│   └── [页面].vue
├── form/             # 表单组件
│   └── [表单].vue
└── config.js         # 插件配置
```

### **插件开发工作流**

1. **【第一步】需求分析**:
   - 明确插件功能和业务需求
   - 设计数据模型和接口规范
   - 规划前端页面和交互流程

2. **【第二步】后端开发**:
   - 创建数据模型和请求模型
   - 实现服务层业务逻辑
   - 开发API控制器和路由
   - 编写初始化和配置代码

3. **【第三步】前端开发**:
   - 创建API接口封装
   - 开发页面组件和表单
   - 实现业务逻辑和状态管理
   - 集成到主系统菜单

4. **【第四步】测试集成**:
   - 单元测试和集成测试
   - 前后端联调测试
   - 用户体验测试
   - 性能和安全测试

### **插件质量标准**

1. **功能完整性**: 插件功能完整，满足业务需求
2. **代码质量**: 代码规范，注释完整，易于维护
3. **数据类型一致性**: 前后端数据模型字段类型保持严格一致，避免类型转换错误
4. **性能表现**: 响应速度快，资源占用合理
5. **用户体验**: 界面友好，操作流畅，错误处理完善
6. **兼容性**: 与主系统兼容，不影响其他功能
7. **安全性**: 数据安全，权限控制，防止安全漏洞

---

### **建议和方案**

基于以上规范，建议AI在开发gin-vue-admin项目时：

1. **严格遵循分层架构**：确保前后端代码都按照规定的层次结构组织
2. **保持代码一致性**：使用统一的命名规范、注释格式和代码风格
3. **注重文档完整性**：确保API文档、代码注释和使用说明的完整性
4. **优化用户体验**：关注页面加载速度、交互流畅性和错误处理
5. **考虑扩展性**：设计时预留扩展接口，便于后续功能增强
6. **重视安全性**：实现完善的权限控制和数据验证机制

================================================
FILE: .gitattributes
================================================
*.sql linguist-language=GO
*.html linguist-language=GO


================================================
FILE: .github/FUNDING.yml
================================================
# These are supported funding model platforms

github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
patreon: # Replace with a single Patreon username
open_collective: gin-vue-admin
ko_fi: # Replace with a single Ko-fi username
tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
liberapay: # Replace with a single Liberapay username
issuehunt: # Replace with a single IssueHunt username
otechie: # Replace with a single Otechie username
custom: https://www.gin-vue-admin.com/docs/coffee


================================================
FILE: .github/ISSUE_TEMPLATE/bug_report.yaml
================================================
name: 🐛 Bug report
description: Report a bug to help us improve Gin-Vue-Admin
title: "[Bug]: "
labels: [bug]
assignees:
  - pixelmaxQm
  - songzhibin97
  - SliverHorn
  - bypanghu
body:
  - type: input
    id: gva
    attributes:
      label: gin-vue-admin 版本
      description: 请输入您当前使用的项目版本?
      placeholder: 2.4.5Beta
    validations:
      required: true
  - type: input
    id: node
    attributes:
      label: Node 版本
      description: 请输入您当前使用的NODE版本?
      placeholder: v14.16.0
    validations:
      required: true
  - type: input
    id: golang
    attributes:
      label: Golang 版本
      description: 请输入您当前使用的GOLANG版本?
      placeholder: go 1.16
    validations:
      required: true
  - type: dropdown
    id: reappearance
    attributes:
      label: 是否依旧存在
      description: 是否可以在master分支复现此bug?
      options:
        - 可以
        - 不可以
        - 未测试
    validations:
      required: true
  - type: textarea
    id: desc
    attributes:
      label: bug描述
      description: 请简要描述bug以及复现过程.
      placeholder: |
        1. 首先...
        2. 然后...
    validations:
      required: true
  - type: textarea
    id: advise
    attributes:
      label: 修改建议
      description: 您有好的建议或者修改方案可以提供给我们。


================================================
FILE: .github/ISSUE_TEMPLATE/config.yml
================================================
blank_issues_enabled: false
contact_links:
  - name: Document
    url: https://www.gin-vue-admin.com
    about: If you have any questions about the use, you can check our official documents first


================================================
FILE: .github/ISSUE_TEMPLATE/feature_request.yaml
================================================
name: 🚀 Feature request
description: Suggest an idea for Gin-Vue-Admin
title: "[Feature]: "
labels: [feature]
assignees:
  - pixelmaxQm
body:
  - type: textarea
    id: desc
    attributes:
      label: 功能描述以及必要性描述
      description: 您觉得此新功能会为框架带来什么便利.
      placeholder: |
        1. 首先...
        2. 然后...
    validations:
      required: true
  - type: textarea
    id: advise
    attributes:
      label: 建议和方案
      description: 您有好的建议或者修改方案可以提供给我们。


================================================
FILE: .github/workflows/ci.yaml
================================================
name: CI

on:
  push:
    branches: [ '*' ]
  pull_request:
  release:
    types: [ created, edited ]
  workflow_dispatch:
    inputs:
      gva_version:
        required: true
        type: string

jobs:
  init:
    if: github.repository_owner == 'flipped-aurora'
    runs-on: ubuntu-latest
    steps:
      - name: init
        run: |
          echo "flipped-aurora"
  frontend:
    if: github.event_name == 'push' || github.event_name == 'pull_request' || github.event_name == 'release'
    name: Frontend node ${{ matrix.node-version }}
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18.16.0]
    steps:
      - name: Check out branch
        uses: actions/checkout@v2

      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v1
        with:
          node-version: ${{ matrix.node-version }}

      - name: Build test
        run: |
          npm install
          npm run build
        working-directory: ./web

  backend:
    if: github.event_name == 'push' || github.event_name == 'pull_request' || github.event_name == 'release'
    name: Backend go
    runs-on: ubuntu-latest
    strategy:
      matrix:
        go-version: [1.22]
    steps:
      - name: Set up Go ${{ matrix.go-version }}
        uses: actions/setup-go@v1
        with:
          go-version: ${{ matrix.go-version }}
        id: go

      - name: Check out branch
        uses: actions/checkout@v2

      - name: Download dependencies
        run: |
          go get -v -t -d ./...
          if [ -f Gopkg.toml ]; then
              curl https://raw.githubusercontent.com/golang/dep/master/install.sh | sh
              dep ensure
          fi
        working-directory: ./server

      - name: Test and Build
        run: |
          go build -v -race
        working-directory: ./server

  devops-test:
    if: github.ref == 'refs/heads/test'
    name: devops-test
    needs: 
      - init
      - backend
      - frontend
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18.16.0]
        go-version: [1.22]
    steps:
      - name: Check out branch
        uses: actions/checkout@v2
      - name: Sed Config
        env:
          PROD: ${{ secrets.PROD }}
          TESTING: ${{ secrets.TESTING }}
        shell: bash
        run: |
          git branch 
          ls -l
          sed -i "s/${PROD}/${TESTING}/g" web/.env.production
          sed -i 's/${basePath}:${basePort}/${basePath}/g' web/src/view/systemTools/formCreate/index.vue
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v2.1.2
        with:
          node-version: ${{ matrix.node-version }}
      - name: Build-Node
        run: |
          cd web/ && yarn install && yarn run build
      - name: Use Go ${{ matrix.go-version }}
        uses: actions/setup-go@v1
        with:
          go-version: ${{ matrix.go-version }}
      - name: Build-go
        run: |
          cd server/ && go mod tidy && CGO_ENABLED=0 go build && mkdir ../web/ser && mv server ../web/ser/ && cd ../web/ser/ && ls -s 
      - name: restart
        env:
          KEY: ${{ secrets.KEY }}
          HOST: ${{ secrets.HOST }}
          USER: ${{ secrets.USER }}
          PROT: ${{ secrets.PROT }}
          MKDIRTEST: ${{ secrets.MKDIRTEST }}
        run: |
          mkdir -p ~/.ssh/ && echo "$KEY" > ~/.ssh/id_rsa && chmod 600 ~/.ssh/id_rsa
          ssh-keyscan github.com >> ~/.ssh/known_hosts
          scp -P ${PROT} -o StrictHostKeyChecking=no -r web/dist/* ${USER}@${HOST}:${MKDIRTEST}dist/
          scp -P ${PROT} -o StrictHostKeyChecking=no -r web/ser/* ${USER}@${HOST}:${MKDIRTEST}
          ssh -p ${PROT} -o StrictHostKeyChecking=no ${USER}@${HOST} "cd ${MKDIRTEST}resource/ && rm -rf ${MKDIRTEST}resource/*"
          scp -P ${PROT} -o StrictHostKeyChecking=no -r server/resource/* ${USER}@${HOST}:${MKDIRTEST}resource/
          ssh -p ${PROT} -o StrictHostKeyChecking=no ${USER}@${HOST} "cd ${MKDIRTEST} && bash restart.sh > /dev/null  2>&1 &"

  release-pr:
    if: ${{ github.event_name == 'workflow_dispatch' && github.repository_owner == 'flipped-aurora'}}
    runs-on: ubuntu-latest
    steps:
      - name: Check out branch
        uses: actions/checkout@v2
      - name: Sed Config
        env:
          GVA_VERSION: ${{ inputs.gva_version }}
        shell: bash
        run: |
          sed -i 's/当前版本.*`$/当前版本:v'${GVA_VERSION##v}'`/' web/src/core/config.js
          sed -i 's/当前版本.*$/当前版本:v'${GVA_VERSION##v}'/' server/core/server.go
          sed -i 's/当前版本.*$/当前版本:v'${GVA_VERSION##v}'/' web/src/core/gin-vue-admin.js
          sed -i 's/"version": ".*",$/"version": "'${GVA_VERSION##v}'",/' web/package.json
          git config --local user.email "github-actions[bot]@users.noreply.github.com"
          git config --local user.name "github-actions[bot]"
          git add . && git commit -m "release: v${GVA_VERSION##v}"
      - name: Push
        uses: ad-m/github-push-action@master
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          branch: ${{ github.ref }}
      - uses: google-github-actions/release-please-action@v3
        with:
          command: release-pr
          release-type: simple
          changelog-path: docs/CHANGELOG.md
          release-as: ${{ inputs.gva_version }}
          package-name: gin-vue-admin
          changelog-types: '[{"type":"feat","section":"Features","hidden":false},{"type":"fix","section":"Bug Fixes","hidden":false},{"type":"chore","section":"Miscellaneous","hidden":false}]'

  release-please:
    if: github.ref == 'refs/heads/main' || github.event_name == 'release'
    runs-on: ubuntu-latest
    needs:
      - init
      - backend
      - frontend
    outputs:
      release_created: ${{ steps.release_please.outputs.release_created }}
      tag_name: ${{ steps.release_please.outputs.tag_name }}
    steps:
      - uses: google-github-actions/release-please-action@v3
        id: release_please
        with:
          #token: ${{ secrets.GAV_TOKEN }}
          command: github-release
          #signoff: "github-actions[bot] <github-actions[bot]@users.noreply.github.com>"
          release-type: simple
          changelog-path: docs/CHANGELOG.md
          #release-as: ${{ inputs.deploy_target }}
          package-name: gin-vue-admin
          #extra-files: |
          #  x-release-please-version.json
          changelog-types: '[{"type":"feat","section":"Features","hidden":false},{"type":"fix","section":"Bug Fixes","hidden":false},{"type":"chore","section":"Miscellaneous","hidden":false}]'

  devops-prod:
    if: needs.release-please.outputs.release_created || github.event_name == 'release'
    runs-on: ubuntu-latest
    needs:
      - init
      - release-please
    name: devops-prod
    strategy:
      matrix:
        node-version: ['18.x']
        go-version: ['1.22']
    steps:
      - uses: actions/checkout@v2
      - name: tag major and minor versions
        run: |
          echo " ${{ needs.release-please.outputs.tag_name }}"
      - name: Sed Config
        shell: bash
        run: |
          git branch 
          ls -l
          sed -i 's/${basePath}:${basePort}/${basePath}/g' web/src/view/systemTools/formCreate/index.vue
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v2.1.2
        with:
          node-version: ${{ matrix.node-version }}
      - name: Build-Node
        run: |
          cd web/ && yarn install && yarn run build
      - name: Use Go ${{ matrix.go-version }}
        uses: actions/setup-go@v1
        with:
          go-version: ${{ matrix.go-version }}
      - name: Build-go
        run: |
          cd server/ && go mod tidy && CGO_ENABLED=0 go build && mkdir ../web/ser && mv server ../web/ser/ && cd ../web/ser/ && ls -s 
      - name: restart
        env:
          KEY: ${{ secrets.KEY }}
          HOST: ${{ secrets.HOST }}
          USER: ${{ secrets.USER }}
          PROT: ${{ secrets.PROT }}
          MKDIR: ${{ secrets.MKDIR }}
        run: |
          mkdir -p ~/.ssh/ && echo "$KEY" > ~/.ssh/id_rsa && chmod 600 ~/.ssh/id_rsa
          ssh-keyscan github.com >> ~/.ssh/known_hosts
          scp -P ${PROT} -o StrictHostKeyChecking=no -r web/dist/* ${USER}@${HOST}:${MKDIR}dist/
          scp -P ${PROT} -o StrictHostKeyChecking=no -r web/ser/* ${USER}@${HOST}:${MKDIR}
          ssh -p ${PROT} -o StrictHostKeyChecking=no ${USER}@${HOST} "cd ${MKDIR}resource/ && rm -rf ${MKDIR}resource/*"
          scp -P ${PROT} -o StrictHostKeyChecking=no -r server/resource/* ${USER}@${HOST}:${MKDIR}resource/
          ssh -p ${PROT} -o StrictHostKeyChecking=no ${USER}@${HOST} "cd ${MKDIR} && bash restart.sh > /dev/null  2>&1 &"

  docker:
    name: docker
    if: github.ref == 'refs/heads/stop-stop-stop'
    runs-on: ubuntu-latest
    needs:
      - init
      - release-please
    steps:
      - name: Check out branch
        uses: actions/checkout@v2
      - name: Login to Aliyun Registry
        uses: docker/login-action@v1
        with:
          registry: ${{ secrets.ALIYUN_REGISTRY }}
          username: ${{ secrets.ALIYUN_DOCKERHUB_USER }}
          password: ${{ secrets.ALIYUN_DOCKERHUB_PASSWORD }}
      - name: Sed Config
        shell: bash
        run: |
          sed  -i 56c"\        && yarn install && yarn build" Makefile
          make image TAGS_OPT="latest"
          sed -i 's#./entrypoint.sh"#./entrypoint.sh","actions"#g' deploy/docker/Dockerfile
          sed -i "s#COPY build/ /usr/share/nginx/html/#COPY . /opt/gva#g" deploy/docker/Dockerfile
          sed -i 16c"\    && cd /opt/gva/server/ && go mod tidy && cd /opt/gva/web/ && yarn" deploy/docker/Dockerfile
          sed -i "s#open: true#open: false#g" web/vite.config.js
          make images TAGS_OPT="latest"
          docker push registry.cn-hangzhou.aliyuncs.com/gva/gin-vue-admin:latest
          docker push registry.cn-hangzhou.aliyuncs.com/gva/web:latest
          docker push registry.cn-hangzhou.aliyuncs.com/gva/server:latest
          docker push registry.cn-hangzhou.aliyuncs.com/gva/all:latest


================================================
FILE: .gitignore
================================================
/web/node_modules
/web/dist

.DS_Store

# local env files
.env.local
.env.*.local

# Log files
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# Editor directories and files
.idea
.vscode
*.suo
*.ntvs*
*.njsproj
*.sln
*.sw?

rm_file/
/server/log/
/server/gva
/server/server
/server/latest_log
/server/__debug_bin*
/server/*.local.yaml
server/uploads/

*.iml
web/.pnpm-debug.log
web/pnpm-lock.yaml

# binary files
*.exe

# SQLite database files
*.db
*.sqlite
*.sqlite3


================================================
FILE: .trae/rules/project_rules.md
================================================
### 功能描述以及必要性描述

---
name: gin-vue-admin
description: |
  gin-vue-admin 是一个基于现代化技术栈的全栈管理系统框架。
  
  前端技术栈：
  - Vue 3.5.7 + Composition API
  - Vite 6.2.3 构建工具
  - Pinia 2.2.2 状态管理
  - Element Plus 2.10.2 UI组件库
  - UnoCSS 66.4.2 原子化CSS框架
  - Vue Router 4.4.3 路由管理
  - Axios 1.8.2 HTTP客户端
  - ECharts 5.5.1 数据可视化
  - @vueuse/core Vue组合式API工具集
  
  后端技术栈：
  - Go 1.23 + Gin 1.10.0 Web框架
  - GORM 1.25.12 ORM框架
  - Casbin 2.103.0 权限管理
  - Viper 1.19.0 配置管理
  - Zap 1.27.0 日志系统
  - Redis 9.7.0 缓存
  - JWT 5.2.2 认证授权
  - 支持MySQL、PostgreSQL、SQLite、SQL Server、MongoDB多种数据库
  - 集成阿里云OSS、AWS S3、MinIO、七牛云、腾讯云COS等云存储服务
  
  核心特性：
  - 完整的RBAC权限控制系统
  - 代码自动生成功能
  - 丰富的中间件支持
  - 插件化架构设计
  - Swagger API文档
---

#### **角色与目标**

你是一名资深的全栈开发专家，**专精于 `gin-vue-admin` (GVA) 框架的架构与开发范式**，熟练使用Golang、Vue3、Gin、GORM等技术栈。

你的核心任务是，根据需求开发**完整、生产级别的全栈功能包或插件**。你必须严格遵循 GVA 的分层架构、代码规范和核心设计模式，确保你生成的每一部分代码都能无缝集成到现有项目中。

---

### **🚀 重要提示：GVA Helper MCP 支持**

**在开始任何GVA开发工作之前，请务必注意以下重要工作流程：**

1. **MCP支持**: GVA框架本身支持MCP（Model Context Protocol），提供了强大的开发辅助能力

2. **GVA Helper**: 通常会有一个名为 "**GVA Helper**" 的MCP助手，专门为GVA框架开发提供支持

3. **开发流程**: 
   - **第一步**: 在开发任何新功能之前，**必须先通过GVA Helper获得支持和指导**
   - **第二步**: 在获得GVA Helper的专业建议和代码示例后，再进行具体的开发操作
   - **第三步**: 遵循GVA Helper提供的最佳实践和代码规范

4. **优势**: 通过GVA Helper可以获得：
   - 最新的GVA框架特性和最佳实践
   - 符合项目规范的代码模板
   - 避免常见的开发陷阱和错误
   - 确保代码质量和一致性

**请始终记住：GVA Helper → 获得支持 → 开始开发**

---

### **核心开发指令：绝不可违背的原则**


## **项目结构说明**

### **整体架构**

gin-vue-admin 采用前后端分离架构：
- **后端 (server/)**：基于 Go + Gin 的 RESTful API 服务
- **前端 (web/)**：基于 Vue 3 + Vite 的单页面应用
- **部署 (deploy/)**：Docker、Kubernetes 等部署配置

### **后端目录结构 (server/)**

```
server/
├── api/                    # API控制器层
│   └── v1/                # API版本控制
│       ├── enter.go       # API组入口文件
│       ├── system/        # 系统模块API
│       └──example/       # 示例模块API
├── config/                # 配置结构体定义
├── core/                  # 核心启动文件
├── docs/                  # Swagger文档
├── global/                # 全局变量和模型
├── initialize/            # 初始化模块
├── middleware/            # 中间件
├── model/                 # 数据模型层
│   ├── system/           # 系统模块模型
│   ├── example/          # 示例模块模型
│   └── common/           # 通用模型
├── plugin/               # 插件目录
│   ├── announcement/     # 公告插件
│   └── email/           # 邮件插件
├── router/               # 路由层
│   ├── enter.go         # 路由组入口
│   ├── system/          # 系统路由
│   └──example/         # 示例路由
├── service/              # 服务层
│   ├── enter.go         # 服务组入口
│   ├── system/          # 系统服务
│   └──  example/         # 示例服务
├── source/               # 数据初始化
├── utils/                # 工具包
├── config.yaml          # 配置文件
└── main.go              # 程序入口
```

### **前端目录结构 (web/)**

```
web/
├── public/               # 静态资源
├── src/
│   ├── api/             # API接口定义
│   │   ├── user.js      # 用户相关API
│   │   ├── menu.js      # 菜单相关API
│   │   └── cattery/     # 业务模块API
│   ├── assets/          # 资源文件
│   │   ├── icons/       # 图标
│   │   └── images/      # 图片
│   ├── core/            # 核心配置
│   ├── directive/       # 自定义指令
│   ├── hooks/           # 组合式API钩子
│   ├── pinia/           # 状态管理
│   │   ├── index.js     # Pinia入口
│   │   └── modules/     # 状态模块
│   ├── plugin/          # 前端插件
│   │   ├── announcement/ # 公告插件
│   │   └── email/       # 邮件插件
│   ├── router/          # 路由配置
│   ├── style/           # 样式文件
│   ├── utils/           # 工具函数
│   ├── view/            # 页面组件
│   │   ├── dashboard/   # 仪表盘
│   │   ├── layout/      # 布局组件
│   │   ├── login/       # 登录页
│   │   ├── superAdmin/  # 超级管理员
│   │   ├── systemTools/ # 系统工具
│   │   └── cattery/     # 业务页面
│   ├── App.vue          # 根组件
│   └── main.js          # 程序入口
├── package.json         # 依赖配置
├── vite.config.js       # Vite配置
└── uno.config.js        # UnoCSS配置
```

---

#### 后端规则

在编写任何代码之前，你必须将以下 GVA 的核心设计原则作为最高行为准则：

1. **严格的分层架构**:
    
    - **职责单一**: 每个层（Model, Service, API, Router）都有其唯一职责，**严禁跨层调用**。例如，API层绝不能直接操作数据库，必须通过Service层。Service层绝不能直接处理`gin.Context`。
        
    - **依赖关系**: 依赖链条必须是单向的：`Router -> API -> Service -> Model`。
        
2. **`enter.go` 组管理模式**:
    
    - 所有 `api`, `service`, `router` 层都**必须**使用 `enter.go` 文件来创建和暴露各自的 `ApiGroup`, `ServiceGroup`, `RouterGroup`。
        
    - 全局实例变量（如 `service.ServiceGroupApp`）是模块间通信的唯一入口，以此来避免循环引用。
        
3. **详尽的 Swagger 注释 (API层强制要求)**:
    
    - **每一个**对外暴露的 API 函数都**必须**拥有完整且准确的 Swagger 注释块。这不仅是API文档的来源，也是前后端协作、自动化测试和前端AI分析的基础。注释必须清晰地描述接口的功能、参数和返回值。
        
4. **统一的响应与错误处理**:
    
    - Service 层函数遇到业务错误时，应返回 `error` 对象。
        
    - API 层负责捕获 Service 层的 `error`，并使用项目统一的 `response` 包（如 `response.OkWithDetailed` 或 `response.FailWithMessage`）将其转换为格式化的 JSON 响应和正确的 HTTP 状态码。
        

---

### **各层级代码实现规范**

#### **1. 模型层 (`model/`)**

- **数据模型 (`model/xxx.go`)**:

   - 用于定义与数据库表映射的 GORM 结构体。

   - 结构体应继承 `global.GVA_MODEL` 以包含 `ID`, `CreatedAt`, `UpdatedAt` 等基础字段。

   - 以上三个字段返回给前端并未做驼峰处理，json内依然是  `ID`, `CreatedAt`, `UpdatedAt`

   - 必须为字段添加清晰的 `json` 和 `gorm` 标签。

   - **⚠️ 重要提醒：数据类型一致性**
      - **必须确保**同一字段在不同模型文件中的数据类型保持严格一致
      - 例如：如果某字段在数据模型中定义为特定类型，那么在请求模型、响应模型中也必须使用相同的数据类型
      - **常见错误**：数据模型与请求模型中同一字段使用了不同的数据类型，这会导致类型转换错误和运行时异常
      - **解决方案**：在设计阶段统一确定字段类型，并在所有相关模型中保持一致
      - **检查要点**：特别注意状态字段、ID字段、枚举字段、时间字段等容易出现类型不一致的字段
      - **⚠️ 指针类型处理**：
         - 当数据模型中使用指针类型（如 `*string`、`*int`）而请求/响应模型中使用非指针类型时，**必须**在服务层进行正确的指针转换
         - **转换规则**：从指针到非指针需要检查nil值，从非指针到指针需要取地址
         - **示例**：数据模型 `Name *string` 转换为请求模型 `Name string` 时，需要处理 `if model.Name != nil { request.Name = *model.Name }`

- **请求模型 (`model/request/xxx.go`)**:
    
    - 用于定义接收前端请求参数的结构体（DTOs）。
        
    - **必须**为字段添加 `json` 和 `form` 标签，以便 Gin 进行参数绑定。
        
    - 对于列表查询请求，应创建一个 `XxxSearch` 结构体，并内嵌通用的 `request.PageInfo` 分页结构体。
        

#### **2. 服务层 (`service/`)**

- **职责**: 封装所有核心业务逻辑，进行数据库的CRUD操作。**此层不应出现任何与HTTP协议相关的代码（如 `gin.Context`）**。
    
- **结构**: 在 `service/` 下为每个模块创建 `xxx_service.go` 文件，并在 `service/enter.go` 中注册。
    
- **函数签名**: 函数应接收具体的业务参数（如 `model.Xxx` 或 `request.XxxSearch`），并返回处理结果和 `error`。

- **⚠️ 数据类型处理注意事项**:
   - 在进行数据模型转换时，**必须确保**字段类型的一致性
   - 避免在服务层进行不必要的类型转换，应在模型设计阶段统一类型
   - 如果必须进行类型转换，**必须**添加详细的注释说明转换原因和逻辑


#### **3. API层 (`api/`)**

- **职责**: 作为HTTP请求的入口，负责参数校验、调用Service层方法、并返回格式化的JSON响应。
    
- **结构**: 在 `api/` 下为每个模块创建 `xxx_api.go` 文件，并在 `api/enter.go` 中注册。
    
- **交互**: **必须**通过全局变量 `service.ServiceGroupApp` 来调用服务层的方法。
    
- **Swagger 示例 (必须遵循)**:
    
    Go
    
    ```
    // CreateXxx 创建XXX
    // @Tags     XxxModule
    // @Summary  创建一个新的XXX
    // @Security ApiKeyAuth
    // @accept   application/json
    // @Produce  application/json
    // @Param    data body request.CreateXxxRequest true "XXX的名称和描述"
    // @Success  200  {object} response.Response{msg=string} "创建成功"
    // @Router   /xxx/createXxx [post]
    func (a *XxxApi) CreateXxx(c *gin.Context) {
        // ...
    }
    ```
    

#### **4. 路由层 (`router/`)**

- **职责**: 定义API路由规则，并将HTTP请求路径映射到具体的API处理函数上，同时配置中间件。
    
- **结构**: 在 `router/` 下为每个模块创建 `xxx_router.go` 文件，并在 `router/enter.go` 中注册。
    
- **交互**: **必须**通过全局变量 `api.ApiGroupApp` 来引用API层的处理函数。
    
- **路由分组**: 应根据业务需求和权限，合理使用路由组 (`Router.Group()`)，并挂载不同的中间件（如鉴权、操作记录等）。

#### **5. 初始化层 (`initialize/`)**

- **职责**: 提供插件资源（数据库、路由、菜单等）的初始化入口，供主程序调用。
    
- **`gorm.go`**: 实现 `InitializeDB` 函数，**必须**调用 `db.AutoMigrate` 自动迁移本插件所有 `model` 的表结构。
    
- **`router.go`**: 实现 `InitializeRouter` 函数，**必须**调用 `router.RouterGroupApp` 中本插件路由的初始化方法，注册所有API路由。
    
- **`menu.go`**: 实现 `InitializeMenu` 函数，负责在数据库中创建或更新本插件的侧边栏菜单、按钮和对应的API权限。
- viper.go: 加载插件配置文件
-  api.go: 注册API到系统
    

#### **6. 插件入口 (`plugin.go`) 

- **职责**: 作为插件的唯一入口，实现 GVA 的插件接口，让框架能够识别和加载本插件。
    
- **接口实现**: **必须**定义一个结构体并实现 `system.Plugin` 接口。

- **插件注册**: **必须**调用 ```
func init() {
	interfaces.Register(Plugin)
}
```
方法，让插件自动注册到本体中
    
- **`Register`方法**: 实现 `Register` 方法，该方法接收一个 `*gin.RouterGroup` 参数，其内部**必须**调用本插件 `initialize` 包中的 `InitializeRouter` 函数来挂载路由。
    
- **`RouterPath`方法**: 实现 `RouterPath` 方法，返回该插件所有API的根路径，例如 `"/myPlugin"`。

### 模块间引用关系：
- API层引用Service层：在API文件中定义变量如 `var xxxService = service.ServiceGroupApp.XxxService`
- Router层引用API层：在路由函数中使用 `api.ApiGroupApp.XxxApi.XxxMethod`
- Initialize/Router引用Router层：通过 `router.RouterGroupApp.XxxRouter.InitXxxRouter`
- 各模块通过enter.go文件组织和暴露功能，避免循环引用

### 插件默认注册功能

`plugin/register.go` 文件下用 `	_ "github.com/flipped-aurora/gin-vue-admin/server/plugin/插件"
` 的方式匿名引用用于激活插件本体的init

### 代码组织示例：

1. Service入口 (service/enter.go):
```go
package service

type ServiceGroup struct {
    XxxService
    YyyService
    // 其他服务...
}

var ServiceGroupApp = new(ServiceGroup)
```

2. API入口 (api/enter.go):
```go
package api

type ApiGroup struct {
    XxxApi
    YyyApi
    // 其他API...
}

var ApiGroupApp = new(ApiGroup)
```

3. Router入口 (router/enter.go):
```go
package router

type RouterGroup struct {
    XxxRouter
    YyyRouter
    // 其他路由...
}

var RouterGroupApp = new(RouterGroup)
```

### Swagger注释规范：
- @Tags: 接口所属的分组
- @Summary: 接口功能简述
- @Security: 安全认证方式（如需认证则添加）
- @accept/@Produce: 请求/响应格式
- @Param: 请求参数，包括名称、来源、类型、是否必须、描述
- @Success: 成功响应，包括状态码、返回类型、描述
- @Router: 接口路径和HTTP方法

API函数的Swagger注释不仅用于生成API文档，也是前端开发的重要参考，请确保注释的完整性和准确性。


---

### **开发工作流**

1. **接收任务**: 我会向你下达一个具体的功能插件开发任务，例如：“请为项目创建一个‘商品管理 (Product)’插件”。
    
2. **【第一步】模型设计 (奠定基础)**:
    
    - 你的**首要行动**是分析需求，设计并提供 `model` 和 `model/request` 下的所有 Go 结构体定义。这是后续所有开发的基础。
        
3. **【第二步】自下而上，分层实现**:
    - 具体项目结构可以参考：server/plugin/announcement 这个插件，非常经典！

    - 在模型确认后，你将按照 `Service -> API -> Router` 的顺序，逐层生成代码。
        
    - 确保每一层的代码都完整、健壮，并严格遵守上述规范。
        
4. **【第三步】插件初始化与注册**:
    
    - 在完成核心功能层的代码后，你将生成 `initialize/` 目录下的相关初始化文件（如 `db.go`, `router.go`）以及插件的主入口文件 `plugin.go`。
        
5. **【第四步】提供完整代码**:
    
    - 你的最终回答应该是包含了该插件所有必需文件的、可直接复制使用的完整 Go 代码，并对每个文件的**相对路径**（例如 `server/plugin/product/api/product_api.go`）和用途进行清晰的说明。


---

## **前端开发规范**

### **角色与目标**

你是一名资深的 Vue.js 前端开发专家，**专精于 `gin-vue-admin` (GVA) 框架的前端架构与开发范式**。

你的核心任务是，根据需求开发**完整、生产级别的前端功能模块或插件**。你必须严格遵循 GVA 的前端架构、代码规范和核心设计模式，确保你生成的每一部分代码都能无缝集成到现有项目中。

### **核心开发指令：绝不可违背的原则**

#### 前端规则

在编写任何前端代码之前，你必须将以下 GVA 的核心设计原则作为最高行为准则：

1. **严格的模块化架构**:
   - **职责单一**: 每个模块（API、组件、页面、状态）都有其唯一职责，**严禁跨模块直接调用**
   - **依赖关系**: 依赖链条必须是单向的：`页面组件 -> API服务 -> 后端接口`

2. **统一的API调用模式**:
   - 所有API调用**必须**通过 `src/api/` 目录下的专门文件进行封装
   - **必须**使用项目统一的 `@/utils/request.js` 进行HTTP请求
   - API函数**必须**包含完整的JSDoc注释，描述接口功能、参数和返回值

3. **组件化开发原则**:
   - **每一个**可复用的UI元素都**必须**封装为组件
   - 组件**必须**遵循单一职责原则，功能明确
   - **必须**为组件添加完整的props定义和事件说明

4. **统一的状态管理**:
   - 全局状态**必须**使用Pinia进行管理
   - 状态模块**必须**按业务功能进行划分
   - **严禁**在组件中直接修改全局状态，必须通过actions

### **各层级代码实现规范**

#### **1. API层 (`src/api/`)**

- **职责**: 封装所有后端API调用，提供统一的接口服务
- **结构**: 按业务模块创建API文件，如 `user.js`、`menu.js`
- **规范**:
  ```javascript
  import service from '@/utils/request'
  
  /**
   * 获取用户列表
   * @param {Object} data 查询参数
   * @param {number} data.page 页码
   * @param {number} data.pageSize 每页数量
   * @returns {Promise} 用户列表数据
   */
  export const getUserList = (data) => {
    return service({
      url: '/user/getUserList',
      method: 'post',
      data: data
    })
  }
  ```

#### **2. 组件层 (`src/components/`)**

- **职责**: 提供可复用的UI组件
- **结构**: 按功能分类组织，每个组件一个文件夹
- **规范**:
  ```vue
  <template>
    <div class="gva-table">
      <!-- 组件内容 -->
    </div>
  </template>
  
  <script setup>
  /**
   * 通用表格组件
   * @component GvaTable
   * @description 提供统一的表格展示功能
   */
  
  // Props定义
  const props = defineProps({
    data: {
      type: Array,
      required: true,
      default: () => []
    },
    loading: {
      type: Boolean,
      default: false
    }
  })
  
  // 事件定义
  const emit = defineEmits(['refresh', 'edit', 'delete'])
  </script>
  ```

#### **3. 页面层 (`src/view/`)**

- **职责**: 实现具体的业务页面
- **结构**: 按业务模块组织，每个页面一个Vue文件
- **规范**:
  - **必须**使用Composition API
  - **必须**进行响应式数据管理
  - **必须**处理加载状态和错误状态
  - **必须**遵循Element Plus组件规范
  - **必须**优先使用UnoCSS原子化类名进行样式设计
  - **必须**优先el-drawer组件进行编辑，新增，步骤等操作
  - **必须**使用el-drawer和el-dialog组件是后一定携带,destroy-on-close属性，确保组件销毁，避免内存泄漏和状态污染

#### **4. 状态管理 (`src/pinia/`)**

- **职责**: 管理全局状态和业务逻辑
- **结构**: 按业务模块创建store文件
- **规范**:
  ```javascript
  import { defineStore } from 'pinia'
  import { ref, computed } from 'vue'
  import { useStorage } from '@vueuse/core'
  
  export const useUserStore = defineStore('user', () => {
    // 状态定义 - 使用 ref() 创建响应式状态
    const userInfo = ref({
      uuid: '',
      nickName: '',
      headerImg: '',
      authority: {}
    })
    const token = useStorage('token', '')
    
    // 计算属性 - 使用 computed() 定义
    const isLogin = computed(() => !!token.value)
    
    // 方法定义 - 直接定义函数作为 actions
    const setUserInfo = (val) => {
      userInfo.value = val
    }
    
    const setToken = (val) => {
      token.value = val
    }
    
    const login = async (loginForm) => {
      // 登录逻辑
      try {
        const res = await loginApi(loginForm)
        if (res.code === 0) {
          setUserInfo(res.data.user)
          setToken(res.data.token)
          return true
        }
        return false
      } catch (error) {
        console.error('Login error:', error)
        return false
      }
    }
    
    const logout = async () => {
      // 登出逻辑
      token.value = ''
      userInfo.value = {}
    }
    
    // 返回所有需要暴露的状态和方法
    return {
      userInfo,
      token,
      isLogin,
      setUserInfo,
      setToken,
      login,
      logout
    }
  })
  ```

#### **5. 路由管理 (`src/router/`)**

- **职责**: 管理页面路由和权限控制
- **规范**:
  - **必须**配置路由元信息
  - **必须**实现权限验证
  - **必须**支持动态路由

### **前端插件开发规范**

#### **插件目录结构**

```
src/plugin/[插件名]/
├── api/                # 插件API接口
│   └── [模块].js
├── components/         # 插件组件（可选）
│   └── [组件名].vue
├── view/              # 插件页面
│   └── [页面名].vue
├── form/              # 插件表单（可选）
│   └── [表单名].vue
└── index.js           # 插件入口文件（可选）
```

#### **插件开发原则**

1. **独立性**: 插件应该是自包含的，不依赖其他业务模块
2. **可配置性**: 插件应该支持配置化，便于定制
3. **可扩展性**: 插件应该预留扩展接口
4. **一致性**: 插件UI风格应与主系统保持一致

### **代码质量要求**

1. **命名规范**:
   - 文件名：kebab-case（短横线命名）
   - 组件名：PascalCase（大驼峰）
   - 变量名：camelCase（小驼峰）
   - 常量名：UPPER_SNAKE_CASE（大写下划线）

2. **注释规范**:
   - **必须**为所有API函数添加JSDoc注释
   - **必须**为复杂组件添加功能说明
   - **必须**为关键业务逻辑添加行内注释

3. **样式规范**:
   - **优先**使用UnoCSS原子化类名
   - **必须**遵循Element Plus设计规范
   - **禁止**使用内联样式
   - **必须**使用CSS变量进行主题定制

4. **性能要求**:
   - **必须**使用懒加载优化路由
   - **必须**对大列表进行虚拟滚动优化
   - **必须**合理使用缓存机制
   - **必须**优化图片和资源加载

---

## **⚠️ 前端工具库使用规范（强制）**

> **核心原则：在开发任何前端功能时，必须优先检查并使用 `src/utils/` 目录下已封装好的工具函数，严禁重复造轮子。**

`src/utils/` 目录提供了项目级别的通用工具集，涵盖 HTTP 请求、日期处理、格式转换、字符串操作、图片处理等多个方面。以下是各工具文件的功能说明：

### **工具文件清单**

#### `request.js` — HTTP 请求封装（核心）
- 基于 Axios 封装的统一 HTTP 请求实例，内置全局 Loading 状态管理、JWT Token 自动注入、统一错误处理和响应拦截
- **所有 API 请求必须且只能通过此模块发送，禁止直接使用 axios**
- 用法：`import service from '@/utils/request'`

#### `date.js` — 日期格式化
- 扩展了 `Date.prototype.Format` 方法，支持自定义格式如 `yyyy-MM-dd hh:mm:ss`
- 导出 `formatTimeToStr(times, pattern)` 将时间戳或日期对象格式化为字符串
- **需要格式化日期时，优先使用此工具，禁止自行手写日期格式化逻辑**
- 用法：`import { formatTimeToStr } from '@/utils/date'`

#### `format.js` — 数据展示格式化（综合工具）
- `formatBoolean(bool)` — 将布尔值转为 "是"/"否" 中文展示
- `formatDate(time)` — 将时间转为 `yyyy-MM-dd hh:mm:ss` 格式字符串
- `filterDict(value, options)` — 在字典选项数组（支持多级树形）中根据 value 查找对应的 label
- `filterDataSource(dataSource, value)` — 在数据源（支持多级树形）中根据 value 查找 label，支持数组批量查找
- `getDictFunc(type)` — 异步获取指定类型的字典数据
- `ReturnArrImg(arr)` — 将图片路径（单个或数组）转为完整 URL，自动补全服务器前缀
- `onDownloadFile(url)` — 触发文件下载
- `setBodyPrimaryColor(primaryColor, darkMode)` — 动态设置主题色相关的 CSS 变量（支持亮/暗模式）
- `CreateUUID()` — 生成 UUID v4 字符串
- `getBaseUrl()` — 获取当前环境的 API BaseURL
- **以上所有格式化场景优先使用此文件中的工具函数**
- 用法：`import { formatBoolean, formatDate, filterDict, CreateUUID, ... } from '@/utils/format'`

#### `dictionary.js` — 字典数据获取
- `getDict(type, options)` — 异步获取字典数据，支持 `depth`（深度）和 `value`（指定节点）参数，内置 Pinia store 缓存，避免重复请求
- **凡是需要字典下拉数据、字典树形数据的场景，必须使用此工具**
- 用法：`import { getDict } from '@/utils/dictionary'`

#### `stringFun.js` — 字符串处理
- `toUpperCase(str)` — 首字母转大写
- `toLowerCase(str)` — 首字母转小写
- `toSQLLine(str)` — 驼峰命名转下划线（snake_case），如 `userName` → `user_name`
- `toHump(name)` — 下划线命名转驼峰，如 `user_name` → `userName`
- **进行命名格式转换时必须使用此工具，禁止使用正则手写**
- 用法：`import { toUpperCase, toSQLLine, toHump } from '@/utils/stringFun'`

#### `params.js` — 系统参数获取
- `getParams(key)` — 异步从 Pinia store 中获取系统参数，内置缓存
- **获取系统配置参数时，优先使用此工具**
- 用法：`import { getParams } from '@/utils/params'`

#### `bus.js` — 全局事件总线
- 基于 `mitt` 封装的全局事件总线实例 `emitter`，用于跨组件通信
- **跨层级组件通信优先使用此事件总线，避免滥用 Pinia**
- 用法：`import { emitter } from '@/utils/bus'`

#### `closeThisPage.js` — 关闭当前标签页
- `closeThisPage()` — 触发关闭当前多标签页的操作（通过事件总线发送 `closeThisPage` 事件）
- **在需要程序化关闭当前页面时，必须使用此工具**
- 用法：`import { closeThisPage } from '@/utils/closeThisPage'`

#### `downloadImg.js` — 图片下载
- `downloadImage(imgsrc, name)` — 通过 Canvas 将图片转为 base64 后触发下载，支持跨域
- **需要下载图片时，优先使用此工具**
- 用法：`import { downloadImage } from '@/utils/downloadImg'`

#### `image.js` — 图片压缩
- 导出 `ImageCompress` 类，支持图片等比压缩至指定最大宽高，并可限制文件大小
- **上传图片前需要做压缩处理时，使用此工具**
- 用法：`import ImageCompress from '@/utils/image'`

#### `event.js` — DOM 事件监听管理
- `addEventListen(target, event, handler, capture)` — 安全地添加 DOM 事件监听
- `removeEventListen(target, event, handler, capture)` — 安全地移除 DOM 事件监听
- **手动操作 DOM 事件时，使用此工具以确保安全性**
- 用法：`import { addEventListen, removeEventListen } from '@/utils/event'`

#### `env.js` — 环境判断
- `isDev` — 是否为开发环境（Boolean）
- `isProd` — 是否为生产环境（Boolean）
- **需要区分运行环境时，使用此工具，禁止直接读取 `import.meta.env`**
- 用法：`import { isDev, isProd } from '@/utils/env'`

#### `doc.js` — 外部文档跳转
- `toDoc(url)` — 在新标签页打开指定 URL
- 用法：`import { toDoc } from '@/utils/doc'`

#### `fmtRouterTitle.js` — 路由标题格式化
- `fmtTitle(title, route)` — 解析路由标题中的动态参数插值（如 `${id}` 替换为路由 params/query 值）
- 用法：`import { fmtTitle } from '@/utils/fmtRouterTitle'`

#### `page.js` — 页面标题生成
- `getPageTitle(pageTitle, route)` — 根据页面标题和路由生成完整的浏览器 Tab 标题（格式：`页面名 - 应用名`）
- 用法：`import getPageTitle from '@/utils/page'`

#### `asyncRouter.js` — 异步路由处理
- `asyncRouterHandle(asyncRouter)` — 将后端返回的路由配置（字符串 component 路径）动态转换为 Vue 组件的 import 函数，支持 `view/` 和 `plugin/` 目录
- **动态路由相关逻辑已由此工具处理，不需要也不应该手动实现**
- 用法：`import { asyncRouterHandle } from '@/utils/asyncRouter'`

#### `btnAuth.js` — 按钮权限
- `useBtnAuth()` — Composition API Hook，返回当前路由挂载的按钮权限对象（来自 `route.meta.btns`），用于控制操作按钮的显示
- **实现按钮级别权限控制时，必须使用此 Hook**
- 用法：`import { useBtnAuth } from '@/utils/btnAuth'`

### **使用强制要求**

| 场景 | 必须使用的工具 |
|------|----------------|
| 发送 HTTP 请求 | `@/utils/request` |
| 格式化日期时间 | `@/utils/date` 或 `@/utils/format` 中的 `formatDate` |
| 获取字典数据 | `@/utils/dictionary` 中的 `getDict` |
| 布尔值/字典值展示转换 | `@/utils/format` 中的 `formatBoolean` / `filterDict` |
| 生成 UUID | `@/utils/format` 中的 `CreateUUID` |
| 驼峰/下划线命名转换 | `@/utils/stringFun` |
| 获取系统参数 | `@/utils/params` 中的 `getParams` |
| 按钮权限判断 | `@/utils/btnAuth` 中的 `useBtnAuth` |
| 跨组件事件通信 | `@/utils/bus` 中的 `emitter` |
| 图片下载 | `@/utils/downloadImg` 中的 `downloadImage` |
| 图片上传压缩 | `@/utils/image` 中的 `ImageCompress` |
| 关闭当前 Tab 页 | `@/utils/closeThisPage` 中的 `closeThisPage` |

---

## **前后端协作规范**

### **接口协作规范**

1. **接口文档**:
   - 后端**必须**提供完整的Swagger API文档
   - 前端**必须**基于Swagger文档进行接口调用
   - 接口变更**必须**提前通知并更新文档

2. **数据格式**:
   - **统一**使用JSON格式进行数据交换
   - **统一**响应格式：`{code, data, msg}`
   - **统一**分页格式：`{page, pageSize, total, list}`
   - **统一**时间格式：ISO 8601标准
   - **⚠️ 数据类型一致性**：
      - 前后端对于同一字段**必须**使用相同的数据类型
      - 后端Go结构体中的字段类型必须与前端JavaScript/TypeScript中的类型定义保持一致
      - 特别注意：状态字段、ID字段、枚举值、时间字段等容易出现类型不匹配的字段
      - 示例：后端数值类型字段对应前端 `number` 类型，字符串类型对应 `string` 类型，布尔类型对应 `boolean` 类型
      - **指针类型处理**：后端Go中的指针类型在JSON序列化时会自动处理nil值，前端接收到的是对应的基础类型或null值

3. **错误处理**:
   - 后端**必须**返回标准化的错误码和错误信息
   - 前端**必须**统一处理HTTP状态码和业务错误码
   - **必须**提供用户友好的错误提示

### **开发流程规范**

1. **需求分析阶段**:
   - 确定功能需求和接口设计
   - 定义数据模型和业务流程
   - 制定前后端开发计划

2. **开发阶段**:
   - 后端优先开发API接口
   - 前端基于Mock数据进行并行开发
   - 定期进行接口联调测试

3. **测试阶段**:
   - 单元测试：前后端各自负责
   - 集成测试：前后端协作完成
   - 用户验收测试：产品团队主导

### **版本管理规范**

1. **分支策略**:
   - `main`：生产环境分支
   - `develop`：开发环境分支
   - `feature/*`：功能开发分支
   - `hotfix/*`：紧急修复分支

2. **提交规范**:
   - 使用语义化提交信息
   - 格式：`type(scope): description`
   - 类型：feat, fix, docs, style, refactor, test, chore

---

## **插件开发完整规范**

### **后端插件结构**

```
server/plugin/[插件名]/
├── api/                # API控制器
│   ├── enter.go       # API组入口
│   └── [模块].go      # 具体API实现
├── config/            # 插件配置
│   └── config.go
├── initialize/        # 初始化模块
│   ├── api.go        # API注册
│   ├── gorm.go       # 数据库初始化
│   ├── menu.go       # 菜单初始化
│   ├── router.go     # 路由初始化
│   └── viper.go      # 配置初始化
├── model/             # 数据模型
│   ├── [模型].go     # 数据库模型
│   └── request/      # 请求模型
├── router/            # 路由定义
│   ├── enter.go      # 路由组入口
│   └── [模块].go     # 具体路由
├── service/           # 业务服务
│   ├── enter.go      # 服务组入口
│   └── [模块].go     # 具体服务
└── plugin.go          # 插件入口
```

### **前端插件结构**

```
web/src/plugin/[插件名]/
├── api/               # API接口
│   └── [模块].js
├── components/        # 插件组件
│   └── [组件].vue
├── view/             # 插件页面
│   └── [页面].vue
├── form/             # 表单组件
│   └── [表单].vue
└── config.js         # 插件配置
```

### **插件开发工作流**

1. **【第一步】需求分析**:
   - 明确插件功能和业务需求
   - 设计数据模型和接口规范
   - 规划前端页面和交互流程

2. **【第二步】后端开发**:
   - 创建数据模型和请求模型
   - 实现服务层业务逻辑
   - 开发API控制器和路由
   - 编写初始化和配置代码

3. **【第三步】前端开发**:
   - 创建API接口封装
   - 开发页面组件和表单
   - 实现业务逻辑和状态管理
   - 集成到主系统菜单

4. **【第四步】测试集成**:
   - 单元测试和集成测试
   - 前后端联调测试
   - 用户体验测试
   - 性能和安全测试

### **插件质量标准**

1. **功能完整性**: 插件功能完整，满足业务需求
2. **代码质量**: 代码规范，注释完整，易于维护
3. **数据类型一致性**: 前后端数据模型字段类型保持严格一致，避免类型转换错误
4. **性能表现**: 响应速度快，资源占用合理
5. **用户体验**: 界面友好，操作流畅，错误处理完善
6. **兼容性**: 与主系统兼容，不影响其他功能
7. **安全性**: 数据安全，权限控制，防止安全漏洞

---

### **建议和方案**

基于以上规范，建议AI在开发gin-vue-admin项目时：

1. **严格遵循分层架构**：确保前后端代码都按照规定的层次结构组织
2. **保持代码一致性**：使用统一的命名规范、注释格式和代码风格
3. **注重文档完整性**：确保API文档、代码注释和使用说明的完整性
4. **优化用户体验**：关注页面加载速度、交互流畅性和错误处理
5. **考虑扩展性**：设计时预留扩展接口，便于后续功能增强
6. **重视安全性**：实现完善的权限控制和数据验证机制

================================================
FILE: CODE_OF_CONDUCT.md
================================================
# Contributor Covenant Code of Conduct

## Our Pledge

In the interest of fostering an open and welcoming environment, we as
contributors and maintainers pledge to making participation in our project and
our community a harassment-free experience for everyone, regardless of age, body
size, disability, ethnicity, sex characteristics, gender identity and expression,
level of experience, education, socio-economic status, nationality, personal
appearance, race, religion, or sexual identity and orientation.

## Our Standards

Examples of behavior that contributes to creating a positive environment
include:

* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members

Examples of unacceptable behavior by participants include:

* The use of sexualized language or imagery and unwelcome sexual attention or
 advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or electronic
 address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a
 professional setting

## Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.

Project maintainers have the right and responsibility to remove, edit, or
reject comments, commits, code, wiki edits, issues, and other contributions
that are not aligned to this Code of Conduct, or to ban temporarily or
permanently any contributor for other behaviors that they deem inappropriate,
threatening, offensive, or harmful.

## Scope

This Code of Conduct applies both within project spaces and in public spaces
when an individual is representing the project or its community. Examples of
representing a project or community include using an official project e-mail
address, posting via an official social media account, or acting as an appointed
representative at an online or offline event. Representation of a project may be
further defined and clarified by project maintainers.

## Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting the project team at 303176530@qq.com. All
complaints will be reviewed and investigated and will result in a response that
is deemed necessary and appropriate to the circumstances. The project team is
obligated to maintain confidentiality with regard to the reporter of an incident.
Further details of specific enforcement policies may be posted separately.

Project maintainers who do not follow or enforce the Code of Conduct in good
faith may face temporary or permanent repercussions as determined by other
members of the project's leadership.

## Attribution

This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html

[homepage]: https://www.contributor-covenant.org

For answers to common questions about this code of conduct, see
https://www.contributor-covenant.org/faq


================================================
FILE: CONTRIBUTING.md
================================================

### Contributing Guide
#### 1 Issue Guidelines

- Issues are exclusively for bug reports, feature requests and design-related topics. Other questions may be closed directly. If any questions come up when you are using Element, please hit [Gitter](https://gitter.im/element-en/Lobby) for help.

- Before submitting an issue, please check if similar problems have already been issued.

#### 2 Pull Request Guidelines

- Fork this repository to your own account. Do not create branches here.

- Commit info should be formatted as `[File Name]: Info about commit.` (e.g. `README.md: Fix xxx bug`)

- <font color=red>Make sure PRs are created to `develop` branch instead of `master` branch.</font>

- If your PR fixes a bug, please provide a description about the related bug.

- Merging a PR takes two maintainers: one approves the changes after reviewing, and then the other reviews and merges.


================================================
FILE: LICENSE
================================================
                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/

   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

   1. Definitions.

      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.

      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.

      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.

      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.

      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.

      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.

      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).

      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.

      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."

      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.

   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.

   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.

   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:

      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and

      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and

      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and

      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.

      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.

   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.

   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.

   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.

   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.

   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.

   END OF TERMS AND CONDITIONS

   APPENDIX: How to apply the Apache License to your work.

      To apply the Apache License to your work, attach the following
      boilerplate notice, with the fields enclosed by brackets "[]"
      replaced with your own identifying information. (Don't include
      the brackets!)  The text should be enclosed in the appropriate
      comment syntax for the file format. We also recommend that a
      file or class name and description of purpose be included on the
      same "printed page" as the copyright notice for easier
      identification within third-party archives.

    Copyright 2019 北京翻转极光科技有限责任公司

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.


================================================
FILE: Makefile
================================================
SHELL = /bin/bash

#SCRIPT_DIR         = $(shell pwd)/etc/script
#请选择golang版本
BUILD_IMAGE_SERVER  = golang:1.22
#请选择node版本
BUILD_IMAGE_WEB     = node:20
#项目名称
PROJECT_NAME        = github.com/flipped-aurora/gin-vue-admin/server
#配置文件目录
CONFIG_FILE         = config.yaml
#镜像仓库命名空间
IMAGE_NAME          = gva
#镜像地址
REPOSITORY          = registry.cn-hangzhou.aliyuncs.com/${IMAGE_NAME}
#镜像版本
TAGS_OPT           ?= latest
PLUGIN             ?= email

#容器环境前后端共同打包
build: build-web build-server
	docker run --name build-local --rm -v $(shell pwd):/go/src/${PROJECT_NAME} -w /go/src/${PROJECT_NAME} ${BUILD_IMAGE_SERVER} make build-local

#容器环境打包前端
build-web:
	docker run --name build-web-local --rm -v $(shell pwd):/go/src/${PROJECT_NAME} -w /go/src/${PROJECT_NAME} ${BUILD_IMAGE_WEB} make build-web-local

#容器环境打包后端
build-server:
	docker run --name build-server-local --rm -v $(shell pwd):/go/src/${PROJECT_NAME} -w /go/src/${PROJECT_NAME} ${BUILD_IMAGE_SERVER} make build-server-local

#构建web镜像
build-image-web:
	@cd web/ && docker build -t ${REPOSITORY}/web:${TAGS_OPT} .

#构建server镜像
build-image-server:
	@cd server/ && docker build -t ${REPOSITORY}/server:${TAGS_OPT} .

#本地环境打包前后端
build-local:
	if [ -d "build" ];then rm -rf build; else echo "OK!"; fi \
	&& if [ -f "/.dockerenv" ];then echo "OK!"; else  make build-web-local && make build-server-local; fi \
	&& mkdir build && cp -r web/dist build/ && cp server/server build/ && cp -r server/resource build/resource

#本地环境打包前端
build-web-local:
	@cd web/ && if [ -d "dist" ];then rm -rf dist; else echo "OK!"; fi \
	&& yarn config set registry http://mirrors.cloud.tencent.com/npm/ && yarn install && yarn build

#本地环境打包后端
build-server-local:
	@cd server/ && if [ -f "server" ];then rm -rf server; else echo "OK!"; fi \
	&& go env -w GO111MODULE=on && go env -w GOPROXY=https://goproxy.cn,direct \
	&& go env -w CGO_ENABLED=0 && go env  && go mod tidy \
	&& go build -ldflags "-B 0x$(shell head -c20 /dev/urandom|od -An -tx1|tr -d ' \n') -X main.Version=${TAGS_OPT}" -v

#打包前后端二合一镜像
image: build
	docker build -t ${REPOSITORY}/gin-vue-admin:${TAGS_OPT} -f deploy/docker/Dockerfile .

#尝鲜版
images: build build-image-web build-image-server
	docker build -t ${REPOSITORY}/all:${TAGS_OPT} -f deploy/docker/Dockerfile .

#swagger 文档生成
doc:
	@cd server && swag init

#插件快捷打包： make plugin PLUGIN="这里是插件文件夹名称,默认为email"
plugin:
	if [ -d ".plugin" ];then rm -rf .plugin ; else echo "OK!"; fi && mkdir -p .plugin/${PLUGIN}/{server/plugin,web/plugin} \
	&& if [ -d "server/plugin/${PLUGIN}" ];then cp -r server/plugin/${PLUGIN} .plugin/${PLUGIN}/server/plugin/ ; else echo "OK!"; fi \
	&& if [ -d "web/src/plugin/${PLUGIN}" ];then cp -r web/src/plugin/${PLUGIN} .plugin/${PLUGIN}/web/plugin/ ; else echo "OK!"; fi \
	&& cd .plugin && zip -r ${PLUGIN}.zip ${PLUGIN} && mv ${PLUGIN}.zip ../ && cd ..


================================================
FILE: README-en.md
================================================

<div align=center>
<img src="http://qmplusimg.henrongyi.top/gvalogo.jpg" width="300" height="300" />
</div>
<div align=center>
<img src="https://img.shields.io/badge/golang-1.18-blue"/>
<img src="https://img.shields.io/badge/gin-1.9.1-lightBlue"/>
<img src="https://img.shields.io/badge/vue-3.3.4-brightgreen"/>
<img src="https://img.shields.io/badge/element--plus-2.3.8-green"/>
<img src="https://img.shields.io/badge/gorm-1.25.2-red"/>
</div>

English | [简体中文](./README.md)

[gitee](https://gitee.com/pixelmax/gin-vue-admin): https://gitee.com/pixelmax/gin-vue-admin

[github](https://github.com/flipped-aurora/gin-vue-admin): https://github.com/flipped-aurora/gin-vue-admin

# Project Guidelines
[Online Documentation](https://www.gin-vue-admin.com/) : https://www.gin-vue-admin.com/

[From the environment to the deployment of teaching videos](https://www.bilibili.com/video/BV1fV411y7dT)

[Development Steps](https://www.gin-vue-admin.com/guide/start-quickly/env.html) (Contributor:  <a href="https://github.com/LLemonGreen">LLemonGreen</a> And <a href="https://github.com/fkk0509">Fann</a>)

## 1. Basic Introduction

### 1.1 Project Introduction

> Gin-vue-admin is a backstage management system based on [vue](https://vuejs.org) and [gin](https://gin-gonic.com), which separates the front and rear of the full stack. It integrates jwt authentication, dynamic routing, dynamic menu, casbin authentication, form generator, code generator and other functions. It provides a variety of sample files, allowing you to focus more time on business development.

[Online Demo](http://demo.gin-vue-admin.com): http://demo.gin-vue-admin.com

username：admin

password：123456

### 1.2 Contributing Guide

Hi! Thank you for choosing gin-vue-admin.

Gin-vue-admin is a full-stack (frontend and backend separation) framework for developers, designers and product managers.

We are excited that you are interested in contributing to gin-vue-admin. Before submitting your contribution though, please make sure to take a moment and read through the following guidelines.

#### 1.2.1 Issue Guidelines

- Issues are exclusively for bug reports, feature requests and design-related topics. Other questions may be closed directly. If any questions come up when you are using Element, please hit [Gitter](https://gitter.im/element-en/Lobby) for help.

- Before submitting an issue, please check if similar problems have already been issued.

#### 1.2.2 Pull Request Guidelines

- Fork this repository to your own account. Do not create branches here.

- Commit info should be formatted as `[File Name]: Info about commit.` (e.g. `README.md: Fix xxx bug`)

- <font color=red>Make sure PRs are created to `develop` branch instead of `master` branch.</font>

- If your PR fixes a bug, please provide a description about the related bug.

- Merging a PR takes two maintainers: one approves the changes after reviewing, and then the other reviews and merges.

### 1.3 Version list

- master: 2.0 code, for prod
- develop: 2.0 dev code, for test
- [gin-vue-admin_v2_dev](https://github.com/flipped-aurora/gin-vue-admin/tree/gin-vue-admin_v2_dev) (v2.0 [GormV1](https://v1.gorm.io) Stable branch)
- [gva_gormv2_dev](https://github.com/flipped-aurora/gin-vue-admin/tree/gva_gormv2_dev) (v2.0 [GormV2](https://v2.gorm.io) Development branch)

## 2. Getting started

```
- node version > v8.6.0
- golang version >= v1.14
- IDE recommendation: Goland
- initialization project: different versions of the database are not initialized. See synonyms at initialization https://www.gin-vue-admin.com/docs/first
- Replace the Qiniuyun public key, private key, warehouse name and default url address in the project to avoid data confusion in the test file.
```

### 2.1 server project

use `Goland` And other editing tools，open server catalogue，You can't open it. `gin-vue-admin` root directory

```bash
# clone the project
git clone https://github.com/flipped-aurora/gin-vue-admin.git

# open server catalogue
cd server

# use go mod And install the go dependency package
go generate

# Compile 
go build -o server main.go (windows the compile command is go build -o server.exe main.go )

# Run binary
./server (windows The run command is server.exe)
```

### 2.1 web project

```bash
# enter the project directory
cd web

# install dependency
npm install

# develop
npm run serve
```

### 2.2 Server

```bash
# using go.mod

# install go modules
go list (go mod tidy)

# build the server
go build
```

### 2.3 API docs auto-generation using swagger

#### 2.3.1 install swagger 

##### (1) Using VPN or outside mainland China
````
go get -u github.com/swaggo/swag/cmd/swag
````

##### (2) In mainland China

In mainland China, access to go.org/x is prohibited，we recommend [goproxy.io](https://goproxy.io/zh/) or [goproxy.cn](https://goproxy.cn)

````bash
# If you are using a version of Go 1.13 - 1.15 Need to set up manually GO111MODULE=on, The opening mode is as follows, If your Go version is 1.16 ~ Latest edition You can ignore the following step one
# Step one、Enable Go Modules Function
go env -w GO111MODULE=on 
# Step two、Configuration GOPROXY Environment variable
go env -w GOPROXY=https://goproxy.cn,https://goproxy.io,direct

# If you dislike trouble,You can use the go generate Automatically execute code before compilation, But this can't be used command line terminal of `Goland` or `Vscode` 
cd server
go generate -run "go env -w .*?"

# Use the following command to download swag
go get -u github.com/swaggo/swag/cmd/swag
````

#### 2.3.2 API docs generation

````
cd server
swag init
````

> After executing the above command，server directory will appear in the docs folder `docs.go`, `swagger.json`, `swagger.yaml` Three file updates，After starting the go service, type in the browser [http://localhost:8888/swagger/index.html](http://localhost:8888/swagger/index.html) You can view swagger document


## 3. Technical selection

- Frontend: using [Element](https://github.com/ElemeFE/element) based on [Vue](https://vuejs.org)，to code the page.
- Backend: using [Gin](https://gin-gonic.com/) to quickly build basic RESTful API. [Gin](https://gin-gonic.com/)is a web framework written in Go (Golang).
- DB: `MySql`(5.6.44)，using [gorm](http://gorm.io)` to implement data manipulation, added support for SQLite databases.
- Cache: using `Redis` to implement the recording of the JWT token of the currently active user and implement the multi-login restriction.
- API: using Swagger to auto generate APIs docs。
- Config: using [fsnotify](https://github.com/fsnotify/fsnotify) and [viper](https://github.com/spf13/viper) to implement `yaml` config file。
- Log: using [zap](https://github.com/uber-go/zap) record logs。

## 4. Project Architecture

### 4.1 Architecture Diagram

![Architecture diagram](http://qmplusimg.henrongyi.top/gva/gin-vue-admin.png)

### 4.2 Front-end Detailed Design Diagram (Contributor: <a href="https://github.com/baobeisuper">baobeisuper</a>)

![Front-end Detailed Design Diagram](http://qmplusimg.henrongyi.top/naotu.png)

### 4.3 Project Layout

```
    ├── server
        ├── api             (api entrance)
        │   └── v1          (v1 version interface)
        ├── config          (configuration package)
        ├── core            (core document)
        ├── docs            (swagger document directory)
        ├── global          (global object)                    
        ├── initialize      (initialization)                        
        │   └── internal    (initialize internal function)                            
        ├── middleware      (middleware layer)                        
        ├── model           (model layer)                    
        │   ├── request     (input parameter structure)                        
        │   └── response    (out-of-parameter structure)                            
        ├── packfile        (static file packaging)                        
        ├── resource        (static resource folder)                        
        │   ├── excel       (excel import and export default path)                        
        │   ├── page        (form generator)                        
        │   └── template    (template)                            
        ├── router          (routing layer)                    
        ├── service         (service layer)                    
        ├── source          (source layer)                    
        └── utils           (tool kit)                    
            ├── timer       (timer interface encapsulation)                        
            └── upload      (oss interface encapsulation)  
            
    └─web            （frontend）
        ├─public        （deploy templates）
        └─src           （source code）
            ├─api       （frontend APIs）
            ├─assets	（static files）
            ├─components（components）
            ├─router	（frontend routers）
            ├─store     （vuex state management）
            ├─style     （common styles）
            ├─utils     （frontend common utilitie）
            └─view      （pages）

```

## 5. Features

- Authority management: Authority management based on `jwt` and `casbin`. 
- File upload and download: implement file upload operations based on `Qiniuyun', `Aliyun 'and `Tencent Cloud` (please develop your own application for each platform corresponding to `token` or `key` ).
- Pagination Encapsulation：The frontend uses `mixins` to encapsulate paging, and the paging method can call `mixins` .
- User management: The system administrator assigns user roles and role permissions.
- Role management: Create the main object of permission control, and then assign different API permissions and menu permissions to the role.
- Menu management: User dynamic menu configuration implementation, assigning different menus to different roles.
- API management: Different users can call different API permissions.
- Configuration management: the configuration file can be modified in the foreground (this feature is not available in the online experience site).
- Conditional search: Add an example of conditional search.
- Restful example: You can see sample APIs in user management module.
  - Front-end file reference: [web/src/view/superAdmin/api/api.vue](https://github.com/flipped-aurora/gin-vue-admin/blob/master/web/src/view/superAdmin/api/api.vue).
  - Stage reference: [server/router/sys_api.go](https://github.com/flipped-aurora/gin-vue-admin/blob/master/server/router/sys_api.go).
- Multi-login restriction: Change `user-multipoint` to true in `system` in `config.yaml` (You need to configure redis and redis parameters yourself. During the test period, please report in time if there is a bug).
- Upload file by chunk：Provides examples of file upload and large file upload by chunk.
- Form Builder：With the help of [@form-generator](https://github.com/JakHuang/form-generator).
- Code generator: Providing backend with basic logic and simple curd code generator.

## 6. Knowledge base

### 6.1 Team blog

> https://www.yuque.com/flipped-aurora
>
>There are video courses about frontend framework in our blo. If you think the project is helpful to you, you can add my personal WeChat:shouzi_1994，your comments is welcomed。

### 6.2 Video courses

(1) Development environment course

> Bilibili：https://www.bilibili.com/video/BV1Fg4y187Bw/

(2) Template course

> Bilibili：https://www.bilibili.com/video/BV16K4y1r7BD/

(3) 2.0 version introduction and development experience

> Bilibili：https://www.bilibili.com/video/BV1aV411d7Gm#reply2831798461

(4) Golang basic course

> https://space.bilibili.com/322210472/channel/detail?cid=108884

(5) gin frame basic teaching

> bilibili：https://space.bilibili.com/322210472/channel/detail?cid=126418&ctype=0

(6) gin-vue-admin version update introduction video
> bilibili：https://space.bilibili.com/322210472/channel/detail?cid=126418&ctype=0

## 7.Contacts

### 7.1 Groups

#### QQ group: 622360840

| QQ group |d
|  :---:  |
| <img src="http://qmplusimg.henrongyi.top/qq.jpg" width="180"/> |


#### Wechat group: comment "加入gin-vue-admin交流群"

| Wechat |
|  :---:  | 
| <img width="150" src="http://qmplusimg.henrongyi.top/qrjjz.png"> 

#### [About Us](https://www.gin-vue-admin.com/about/join.html)

## 8. Contributors

Thank you for considering your contribution to gin-vue-admin!

<a href="https://openomy.app/github/flipped-aurora/gin-vue-admin" target="_blank" style="display: block; width: 100%;" align="center">
  <img src="https://openomy.app/svg?repo=flipped-aurora/gin-vue-admin&chart=bubble&latestMonth=3" target="_blank" alt="Contribution Leaderboard" style="display: block; width: 100%;" />
 </a>

<a href="https://github.com/flipped-aurora/gin-vue-admin/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=flipped-aurora/gin-vue-admin" />
</a>

## 9. Donate

If you find this project useful, you can buy author a glass of juice :tropical_drink: [here](https://www.gin-vue-admin.com/coffee/index.html)

## 10. Commercial considerations

If you use this project for commercial purposes, please comply with the Apache2.0 agreement and retain the author's technical support statement.



================================================
FILE: README.md
================================================

<div align=center>
<img src="http://qmplusimg.henrongyi.top/gvalogo.jpg" width="300" height="300" />
</div>

<div align=center>
<img src="https://img.shields.io/badge/golang-1.20-blue"/>
<img src="https://img.shields.io/badge/gin-1.9.1-lightBlue"/>
<img src="https://img.shields.io/badge/vue-3.3.4-brightgreen"/>
<img src="https://img.shields.io/badge/element--plus-2.3.8-green"/>
<img src="https://img.shields.io/badge/gorm-1.25.2-red"/>
<img src="https://gitcode.com/flipped-aurora/gin-vue-admin/star/badge.svg"/>
</div>

<div align=center>
<a href="https://trendshift.io/repositories/3250" target="_blank"><img src="https://trendshift.io/api/badge/repositories/3250" alt="Calcium-Ion%2Fnew-api | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
</div>

[English](./README-en.md) | 简体中文

## 支持claw生态

[🦞GvaClaw](https://plugin.gin-vue-admin.com/details/159)

## ✨一分钟生成前后端基础代码

<table>
  <tr>
    <td width="250">
	  <p>⭐️ <a href="https://www.bilibili.com/video/BV1B3htzqEf1/?spm_id_from=333.1387.homepage.video_card.click" target="__blank"> 高度适配AI编辑器的MCP </a></p>
      <p>📄 创建基础模板</p>
      <p>🤖 AI生成结构</p>
      <p>⏰ 生成代码</p>
      <p>🏷️ 分配权限</p>
      <p>🎉 基础CURD生成完成</p>   
    </td>
    <td>
      <video src="https://private-user-images.githubusercontent.com/165128580/384700666-4d039215-af29-4f86-bb4f-60dbab38f58e.mp4?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MzEyNTIxNDYsIm5iZiI6MTczMTI1MTg0NiwicGF0aCI6Ii8xNjUxMjg1ODAvMzg0NzAwNjY2LTRkMDM5MjE1LWFmMjktNGY4Ni1iYjRmLTYwZGJhYjM4ZjU4ZS5tcDQ_WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ3JlZGVudGlhbD1BS0lBVkNPRFlMU0E1M1BRSzRaQSUyRjIwMjQxMTEwJTJGdXMtZWFzdC0xJTJGczMlMkZhd3M0X3JlcXVlc3QmWC1BbXotRGF0ZT0yMDI0MTExMFQxNTE3MjZaJlgtQW16LUV4cGlyZXM9MzAwJlgtQW16LVNpZ25hdHVyZT00NjJkMDcwZjJkMjAyMmU1N2I2MzQxY2RhODFlNzgzNGRiMDFhMmY2NTYyM2ZmODdhNDVmMWE1NzlhMDdlOTI5JlgtQW16LVNpZ25lZEhlYWRlcnM9aG9zdCJ9.ZJbswpLzF2RHjemcGirKOP0L1fvpl3FUqIiQ_-yjeUo" data-canonical-src="https://private-user-images.githubusercontent.com/165128580/384700666-4d039215-af29-4f86-bb4f-60dbab38f58e.mp4?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MzEyNTIxNDYsIm5iZiI6MTczMTI1MTg0NiwicGF0aCI6Ii8xNjUxMjg1ODAvMzg0NzAwNjY2LTRkMDM5MjE1LWFmMjktNGY4Ni1iYjRmLTYwZGJhYjM4ZjU4ZS5tcDQ_WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ3JlZGVudGlhbD1BS0lBVkNPRFlMU0E1M1BRSzRaQSUyRjIwMjQxMTEwJTJGdXMtZWFzdC0xJTJGczMlMkZhd3M0X3JlcXVlc3QmWC1BbXotRGF0ZT0yMDI0MTExMFQxNTE3MjZaJlgtQW16LUV4cGlyZXM9MzAwJlgtQW16LVNpZ25hdHVyZT00NjJkMDcwZjJkMjAyMmU1N2I2MzQxY2RhODFlNzgzNGRiMDFhMmY2NTYyM2ZmODdhNDVmMWE1NzlhMDdlOTI5JlgtQW16LVNpZ25lZEhlYWRlcnM9aG9zdCJ9.ZJbswpLzF2RHjemcGirKOP0L1fvpl3FUqIiQ_-yjeUo" controls="controls" muted="muted" class="d-block rounded-bottom-2 border-top width-fit" style="max-height:640px; min-height: 200px">
</video>
    </td>
  </tr>
</table>


# 项目文档
[在线文档](https://www.gin-vue-admin.com) : https://www.gin-vue-admin.com

[初始化](https://www.gin-vue-admin.com/guide/start-quickly/initialization.html)
						       
[从环境到部署教学视频](https://www.bilibili.com/video/BV1Rg411u7xH)

[开发教学](https://www.gin-vue-admin.com/guide/start-quickly/env.html) (贡献者:  <a href="https://github.com/LLemonGreen">LLemonGreen</a> And <a href="https://github.com/fkk0509">Fann</a>)

[交流社区](https://support.qq.com/products/371961)

[插件市场](https://plugin.gin-vue-admin.com/)

[软件著作权证书](https://www.gin-vue-admin.com/copyright.pdf)

# 重要提示

1.本项目从起步到开发到部署均有文档和详细视频教程

2.本项目需要您有一定的golang和vue基础

3.您完全可以通过我们的教程和文档完成一切操作，因此我们不再提供免费的技术服务，如需服务请进行[付费支持](https://www.gin-vue-admin.com/coffee/payment.html)

4.如果您将此项目用于商业用途，请遵守Apache2.0协议并保留作者技术支持声明。您需保留如下版权声明信息，以及日志和代码中所包含的版权声明信息。所需保留信息均为文案性质，不会影响任何业务内容，如决定商用【产生收益的商业行为均在商用行列】或者必须剔除请[购买授权](https://plugin.gin-vue-admin.com/licenseindex.html)
\
<img src="https://qmplusimg.henrongyi.top/openSource/login.jpg" width="1000">

<img src="https://qmplusimg.henrongyi.top/openSource/dashboard.jpg" width="1000">

## 1. 基本介绍

### 1.1 项目介绍

> Gin-vue-admin是一个基于 [vue](https://vuejs.org) 和 [gin](https://gin-gonic.com) 开发的全栈前后端分离的开发基础平台，集成jwt鉴权，动态路由，动态菜单，casbin鉴权，表单生成器，代码生成器等功能，提供多种示例文件，让您把更多时间专注在业务开发上。

[在线预览](http://demo.gin-vue-admin.com): http://demo.gin-vue-admin.com

测试用户名：admin

测试密码：123456

### 1.2 贡献指南
Hi! 首先感谢你使用 gin-vue-admin。

Gin-vue-admin 是一套为快速研发准备的一整套前后端分离架构式的开源框架，旨在快速搭建中小型项目。

Gin-vue-admin 的成长离不开大家的支持，如果你愿意为 gin-vue-admin 贡献代码或提供建议，请阅读以下内容。

#### 1.2.1 Issue 规范
- issue 仅用于提交 Bug 或 Feature 以及设计相关的内容，其它内容可能会被直接关闭。
									      
- 在提交 issue 之前，请搜索相关内容是否已被提出。

#### 1.2.2 Pull Request 规范
- 请先 fork 一份到自己的项目下，不要直接在仓库下建分支。

- commit 信息要以`[文件名]: 描述信息` 的形式填写，例如 `README.md: fix xxx bug`。

- 如果是修复 bug，请在 PR 中给出描述信息。

- 合并代码需要两名维护人员参与：一人进行 review 后 approve，另一人再次 review，通过后即可合并。

## 2. 使用说明

```
- node版本 > v18.16.0
- golang版本 >= v1.22
- IDE推荐：Goland
```

### 2.1 server项目

使用 `Goland` 等编辑工具，打开server目录，不可以打开 gin-vue-admin 根目录

```bash

# 克隆项目
git clone https://github.com/flipped-aurora/gin-vue-admin.git
# 进入server文件夹
cd server

# 使用 go mod 并安装go依赖包
go generate

# 运行
go run . 

```

### 2.2 web项目

```bash
# 进入web文件夹
cd web

# 安装依赖
npm install

# 启动web项目
npm run serve
```

### 2.3 swagger自动化API文档

#### 2.3.1 安装 swagger

``` shell
go install github.com/swaggo/swag/cmd/swag@latest
```

#### 2.3.2 生成API文档

```` shell
cd server
swag init
````

> 执行上面的命令后，server目录下会出现docs文件夹里的 `docs.go`, `swagger.json`, `swagger.yaml` 三个文件更新，启动go服务之后, 在浏览器输入 [http://localhost:8888/swagger/index.html](http://localhost:8888/swagger/index.html) 即可查看swagger文档

### 2.4 VSCode工作区

#### 2.4.1 开发

使用`VSCode`打开根目录下的工作区文件`gin-vue-admin.code-workspace`，在边栏可以看到三个虚拟目录：`backend`、`frontend`、`root`。

#### 2.4.2 运行/调试

在运行和调试中也可以看到三个task：`Backend`、`Frontend`、`Both (Backend & Frontend)`。运行`Both (Backend & Frontend)`可以同时启动前后端项目。

#### 2.4.3 settings

在工作区配置文件中有`go.toolsEnvVars`字段，是用于`VSCode`自身的go工具环境变量。此外在多go版本的系统中，可以通过`gopath`、`go.goroot`指定运行版本。

```json
    "go.gopath": null,
    "go.goroot": null,
```

## 3. 技术选型

- 前端：用基于 [Vue](https://vuejs.org) 的 [Element](https://github.com/ElemeFE/element) 构建基础页面。
- 后端：用 [Gin](https://gin-gonic.com/) 快速搭建基础restful风格API，[Gin](https://gin-gonic.com/) 是一个go语言编写的Web框架。
- 数据库：采用`MySql` > (5.7) 版本 数据库引擎 InnoDB，使用 [gorm](http://gorm.cn) 实现对数据库的基本操作。
- 缓存：使用`Redis`实现记录当前活跃用户的`jwt`令牌并实现多点登录限制。
- API文档：使用`Swagger`构建自动化文档。
- 配置文件：使用 [fsnotify](https://github.com/fsnotify/fsnotify) 和 [viper](https://github.com/spf13/viper) 实现`yaml`格式的配置文件。
- 日志：使用 [zap](https://github.com/uber-go/zap) 实现日志记录。

## 4. 项目架构

### 4.1 系统架构图

![系统架构图](http://qmplusimg.henrongyi.top/gva/gin-vue-admin.png)

### 4.2 前端详细设计图 （提供者:<a href="https://github.com/baobeisuper">baobeisuper</a>）

![前端详细设计图](http://qmplusimg.henrongyi.top/naotu.png)

### 4.3 目录结构

```
    ├── server
        ├── api             (api层)
        │   └── v1          (v1版本接口)
        ├── config          (配置包)
        ├── core            (核心文件)
        ├── docs            (swagger文档目录)
        ├── global          (全局对象)                    
        ├── initialize      (初始化)                        
        │   └── internal    (初始化内部函数)                            
        ├── middleware      (中间件层)                        
        ├── model           (模型层)                    
        │   ├── request     (入参结构体)                        
        │   └── response    (出参结构体)                            
        ├── packfile        (静态文件打包)                        
        ├── resource        (静态资源文件夹)                        
        │   ├── excel       (excel导入导出默认路径)                        
        │   ├── page        (表单生成器)                        
        │   └── template    (模板)                            
        ├── router          (路由层)                    
        ├── service         (service层)                    
        ├── source          (source层)                    
        └── utils           (工具包)                    
            ├── timer       (定时器接口封装)                        
            └── upload      (oss接口封装)                        
    
            web
        ├── babel.config.js
        ├── Dockerfile
        ├── favicon.ico
        ├── index.html                 -- 主页面
        ├── limit.js                   -- 助手代码
        ├── package.json               -- 包管理器代码
        ├── src                        -- 源代码
        │   ├── api                    -- api 组
        │   ├── App.vue                -- 主页面
        │   ├── assets                 -- 静态资源
        │   ├── components             -- 全局组件
        │   ├── core                   -- gva 组件包
        │   │   ├── config.js          -- gva网站配置文件
        │   │   ├── gin-vue-admin.js   -- 注册欢迎文件
        │   │   └── global.js          -- 统一导入文件
        │   ├── directive              -- v-auth 注册文件
        │   ├── main.js                -- 主文件
        │   ├── permission.js          -- 路由中间件
        │   ├── pinia                  -- pinia 状态管理器，取代vuex
        │   │   ├── index.js           -- 入口文件
        │   │   └── modules            -- modules
        │   │       ├── dictionary.js
        │   │       ├── router.js
        │   │       └── user.js
        │   ├── router                 -- 路由声明文件
        │   │   └── index.js
        │   ├── style                  -- 全局样式
        │   │   ├── base.scss
        │   │   ├── basics.scss
        │   │   ├── element_visiable.scss  -- 此处可以全局覆盖 element-plus 样式
        │   │   ├── iconfont.css           -- 顶部几个icon的样式文件
        │   │   ├── main.scss
        │   │   ├── mobile.scss
        │   │   └── newLogin.scss
        │   ├── utils                  -- 方法包库
        │   │   ├── asyncRouter.js     -- 动态路由相关
        │   │   ├── btnAuth.js         -- 动态权限按钮相关
        │   │   ├── bus.js             -- 全局mitt声明文件
        │   │   ├── date.js            -- 日期相关
        │   │   ├── dictionary.js      -- 获取字典方法 
        │   │   ├── downloadImg.js     -- 下载图片方法
        │   │   ├── format.js          -- 格式整理相关
        │   │   ├── image.js           -- 图片相关方法
        │   │   ├── page.js            -- 设置页面标题
        │   │   ├── request.js         -- 请求
        │   │   └── stringFun.js       -- 字符串文件
        |   ├── view -- 主要view代码
        |   |   ├── about -- 关于我们
        |   |   ├── dashboard -- 面板
        |   |   ├── error -- 错误
        |   |   ├── example --上传案例
        |   |   ├── iconList -- icon列表
        |   |   ├── init -- 初始化数据  
        |   |   |   ├── index -- 新版本
        |   |   |   ├── init -- 旧版本
        |   |   ├── layout  --  layout约束页面 
        |   |   |   ├── aside 
        |   |   |   ├── bottomInfo     -- bottomInfo
        |   |   |   ├── screenfull     -- 全屏设置
        |   |   |   ├── setting        -- 系统设置
        |   |   |   └── index.vue      -- base 约束
        |   |   ├── login              --登录 
        |   |   ├── person             --个人中心 
        |   |   ├── superAdmin         -- 超级管理员操作
        |   |   ├── system             -- 系统检测页面
        |   |   ├── systemTools        -- 系统配置相关页面
        |   |   └── routerHolder.vue   -- page 入口页面 
        ├── vite.config.js             -- vite 配置文件
        └── yarn.lock

```

## 5. 主要功能

- 权限管理：基于`jwt`和`casbin`实现的权限管理。
- 文件上传下载：实现基于`七牛云`, `阿里云`, `腾讯云` 的文件上传操作(请开发自己去各个平台的申请对应 `token` 或者对应`key`)。
- 分页封装：前端使用 `mixins` 封装分页，分页方法调用 `mixins` 即可。
- 用户管理：系统管理员分配用户角色和角色权限。
- 角色管理：创建权限控制的主要对象，可以给角色分配不同api权限和菜单权限。
- 菜单管理：实现用户动态菜单配置，实现不同角色不同菜单。
- api管理：不同用户可调用的api接口的权限不同。
- 配置管理：配置文件可前台修改(在线体验站点不开放此功能)。
- 条件搜索：增加条件搜索示例。
- restful示例：可以参考用户管理模块中的示例API。
	- 前端文件参考: [web/src/view/superAdmin/api/api.vue](https://github.com/flipped-aurora/gin-vue-admin/blob/master/web/src/view/superAdmin/api/api.vue)
    - 后台文件参考: [server/router/sys_api.go](https://github.com/flipped-aurora/gin-vue-admin/blob/master/server/router/sys_api.go)
- 多点登录限制：需要在`config.yaml`中把`system`中的`use-multipoint`修改为true(需要自行配置Redis和Config中的Redis参数，测试阶段，有bug请及时反馈)。
- 分片上传：提供文件分片上传和大文件分片上传功能示例。
- 表单生成器：表单生成器借助 [@Variant Form](https://github.com/vform666/variant-form) 。
- 代码生成器：后台基础逻辑以及简单curd的代码生成器。

## 6. 知识库 

## 6.1 团队博客

> https://www.yuque.com/flipped-aurora
>
>内有前端框架教学视频。如果觉得项目对您有所帮助可以添加我的个人微信:shouzi_1994，欢迎您提出宝贵的需求。

## 6.2 教学视频

（1）手把手教学视频

> https://www.bilibili.com/video/BV1Rg411u7xH/

（2）后端目录结构调整介绍以及使用方法

> https://www.bilibili.com/video/BV1x44y117TT/

（3）golang基础教学视频

> bilibili：https://space.bilibili.com/322210472/channel/detail?cid=108884

（4）gin框架基础教学

> bilibili：https://space.bilibili.com/322210472/channel/detail?cid=126418&ctype=0

（5）gin-vue-admin 版本更新介绍视频

> bilibili：https://www.bilibili.com/video/BV1kv4y1g7nT

## 7. 联系方式

### 7.1 技术群

### QQ交流群：971857775

### 微信交流群
| 微信 |
|  :---:  | 
| <img width="150" src="http://qmplusimg.henrongyi.top/qrjjz.png"> 

防止广告进群，添加微信，输入以下代码执行结果（请勿转码为string）

```
str := "5Yqg5YWlR1ZB5Lqk5rWB576k"
decodeBytes, err := base64.StdEncoding.DecodeString(str)
fmt.Println(decodeBytes, err)
```

### [关于我们](https://www.gin-vue-admin.com/about/join.html)

## 8. 贡献者

感谢您对gin-vue-admin的贡献!

<a href="https://openomy.app/github/flipped-aurora/gin-vue-admin" target="_blank" style="display: block; width: 100%;" align="center">
  <img src="https://openomy.app/svg?repo=flipped-aurora/gin-vue-admin&chart=bubble&latestMonth=3" target="_blank" alt="Contribution Leaderboard" style="display: block; width: 100%;" />
 </a>

## 9. 捐赠

如果你觉得这个项目对你有帮助，你可以请作者喝饮料 :tropical_drink: [点我](https://www.gin-vue-admin.com/coffee/index.html)

## 10. 注意事项

请严格遵守Apache 2.0协议并保留作品声明，去除版权信息请务必[获取授权](https://plugin.gin-vue-admin.com/license)  
未授权去除版权信息将依法追究法律责任


================================================
FILE: SECURITY.md
================================================
# Security Policy

## Reporting a Vulnerability

Please report security issues to qimiaojiangjizhao@gmail.com


================================================
FILE: deploy/docker/Dockerfile
================================================
FROM centos:7
WORKDIR /opt
ENV LANG=en_US.utf8
COPY deploy/docker/entrypoint.sh .
COPY build/ /usr/share/nginx/html/
COPY server/config.yaml /usr/share/nginx/html/config.yaml
COPY web/.docker-compose/nginx/conf.d/nginx.conf /etc/nginx/conf.d/nginx.conf
RUN set -ex \
    && echo "LANG=en_US.utf8" > /etc/locale.conf \
    && echo "net.core.somaxconn = 1024" >> /etc/sysctl.conf \
    && echo "vm.overcommit_memory = 1" >> /etc/sysctl.conf \
    && yum -y install epel-release \
    && yum -y localinstall http://mirrors.ustc.edu.cn/mysql-repo/mysql57-community-release-el7.rpm \
    && yum -y install mysql-community-server git redis nginx go npm --nogpgcheck && chmod +x ./entrypoint.sh \
    && npm install -g yarn && go env -w GO111MODULE=on && go env -w GOPROXY=https://goproxy.cn,direct \
    && echo "start" > /dev/null
EXPOSE 80
ENTRYPOINT ["./entrypoint.sh"]

================================================
FILE: deploy/docker/entrypoint.sh
================================================
#!/bin/bash
if [ ! -d "/var/lib/mysql/gva" ]; then
    mysqld --initialize-insecure --user=mysql --datadir=/var/lib/mysql
    mysqld --daemonize --user=mysql
    sleep 5s
    mysql -uroot -e "create database gva default charset 'utf8' collate 'utf8_bin'; grant all on gva.* to 'root'@'127.0.0.1' identified by '123456'; flush privileges;"
else
    mysqld --daemonize --user=mysql
fi
redis-server &
if [ "$1" = "actions" ]; then
    cd /opt/gva/server && go run main.go &
    cd /opt/gva/web/ && yarn serve &
else 
    /usr/sbin/nginx &
    cd /usr/share/nginx/html/ && ./server &
fi
echo "gva ALL start!!!"
tail -f /dev/null

================================================
FILE: deploy/docker-compose/docker-compose.yaml
================================================
version: "3"

# 声明一个名为network的networks,subnet为network的子网地址,默认网关是177.7.0.1
networks:
  network:
    ipam:
      driver: default
      config:
        - subnet: '177.7.0.0/16'
        
# 设置mysql，redis持久化保存
volumes:
  mysql:
  redis:
  
services:
  web:
    build:
      context: ../../web
      dockerfile: ./Dockerfile
    container_name: gva-web
    restart: always
    ports:
      - '8080:8080'
    depends_on:
      - server
    command: [ 'nginx-debug', '-g', 'daemon off;' ]
    networks:
      network:
        ipv4_address: 177.7.0.11

  server:
    build:
      context: ../../server
      dockerfile: ./Dockerfile
    container_name: gva-server
    restart: always
    ports:
      - '8888:8888'
    depends_on:
      mysql:
        condition: service_healthy
      redis:
        condition: service_healthy
    links:
      - mysql
      - redis
    networks:
      network:
        ipv4_address: 177.7.0.12

  mysql:
    image: mysql:8.0.21       # 如果您是 arm64 架构：如 MacOS 的 M1，请修改镜像为 image: mysql/mysql-server:8.0.21
    container_name: gva-mysql
    command: mysqld --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci #设置utf8字符集
    restart: always
    ports:
      - "13306:3306"  # host物理直接映射端口为13306
    environment:
      #MYSQL_ROOT_PASSWORD: 'Aa@6447985' # root管理员用户密码
      MYSQL_DATABASE: 'qmPlus' # 初始化启动时要创建的数据库的名称
      MYSQL_USER: 'gva'
      MYSQL_PASSWORD: 'Aa@6447985'
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "gva", "-pAa@6447985"]
      interval: 10s
      timeout: 5s
      retries: 3
    volumes:
      - mysql:/var/lib/mysql
    networks:
      network:
        ipv4_address: 177.7.0.13

  redis:
    image: redis:6.0.6
    container_name: gva-redis # 容器名
    restart: always
    ports:
      - '16379:6379'
    healthcheck:
      test: ["CMD-SHELL", "redis-cli ping | grep PONG || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 3
    volumes:
      - redis:/data
    networks:
      network:
        ipv4_address: 177.7.0.14


================================================
FILE: deploy/kubernetes/server/gva-server-configmap.yaml
================================================
apiVersion: v1
kind: ConfigMap
metadata:
  name: config.yaml
  annotations:
    flipped-aurora/gin-vue-admin: backend
    github: "https://github.com/flipped-aurora/gin-vue-admin.git"
    app.kubernetes.io/version: 0.0.1
  labels:
    app: gva-server
    version: gva-vue3
data:
  config.yaml: |
    # github.com/flipped-aurora/gin-vue-admin/server Global Configuration

    # jwt configuration
    jwt:
      signing-key: 'qmPlus'
      expires-time: 604800
      buffer-time: 86400

    # zap logger configuration
    zap:
      level: 'info'
      format: 'console'
      prefix: '[github.com/flipped-aurora/gin-vue-admin/server]'
      director: 'log'
      link-name: 'latest_log'
      show-line: true
      encode-level: 'LowercaseColorLevelEncoder'
      stacktrace-key: 'stacktrace'
      log-in-console: true

    # redis configuration
    redis:
      db: 0
      addr: '127.0.0.1:6379'
      password: ''

    # email configuration
    email:
      to: 'xxx@qq.com'
      port: 465
      from: 'xxx@163.com'
      host: 'smtp.163.com'
      is-ssl: true
      secret: 'xxx'
      nickname: 'test'

    # casbin configuration
    casbin:
      model-path: './resource/rbac_model.conf'

    # system configuration
    system:
      env: 'develop'  # Change to "develop" to skip authentication for development mode
      addr: 8888
      db-type: 'mysql'
      oss-type: 'local'    # 控制oss选择走本期还是 七牛等其他仓 自行增加其他oss仓可以在 server/utils/upload/upload.go 中 NewOss函数配置
      use-multipoint: false

    # captcha configuration
    captcha:
      key-long: 6
      img-width: 240
      img-height: 80

    # mysql connect configuration
    # 未初始化之前请勿手动修改数据库信息！！！如果一定要手动初始化请看（https://www.github.com/flipped-aurora/gin-vue-admin/server.com/docs/first）
    mysql:
      path: ''
      config: ''
      db-name: ''
      username: ''
      password: ''
      max-idle-conns: 10
      max-open-conns: 100
      log-mode: false
      log-zap: ""

    # local configuration
    local:
      path: 'uploads/file'

    # autocode configuration
    autocode:
      transfer-restart: true
      root: ""
      server: /server
      server-api: /api/v1/autocode
      server-initialize: /initialize
      server-model: /model/autocode
      server-request: /model/autocode/request/
      server-router: /router/autocode
      server-service: /service/autocode
      web: /web/src
      web-api: /api
      web-flow: /view
      web-form: /view
      web-table: /view

    # qiniu configuration (请自行七牛申请对应的 公钥 私钥 bucket 和 域名地址)
    qiniu:
      zone: 'ZoneHuaDong'
      bucket: ''
      img-path: ''
      use-https: false
      access-key: ''
      secret-key: ''
      use-cdn-domains: false


    # aliyun oss configuration
    aliyun-oss:
      endpoint: 'yourEndpoint'
      access-key-id: 'yourAccessKeyId'
      access-key-secret: 'yourAccessKeySecret'
      bucket-name: 'yourBucketName'
      bucket-url: 'yourBucketUrl'
      base-path: 'yourBasePath'

    # tencent cos configuration
    tencent-cos:
      bucket: 'xxxxx-10005608'
      region: 'ap-shanghai'
      secret-id: 'xxxxxxxx'
      secret-key: 'xxxxxxxx'
      base-url: 'https://gin.vue.admin'
      path-prefix: 'github.com/flipped-aurora/gin-vue-admin/server'

    # excel configuration
    excel:
      dir: './resource/excel/'


    # timer task db clear table
    Timer:
      start: true
      spec: "@daily"  # 定时任务详细配置参考 https://pkg.go.dev/github.com/robfig/cron/v3
      detail: [
        # tableName: 需要清理的表名
        # compareField: 需要比较时间的字段
        # interval: 时间间隔, 具体配置详看 time.ParseDuration() 中字符串表示 且不能为负数
        # 2160h = 24 * 30 * 3 -> 三个月
        { tableName: "sys_operation_records" , compareField: "created_at", interval: "2160h" },
        { tableName: "jwt_blacklists" , compareField: "created_at", interval: "168h" }
        #{ tableName: "log2" , compareField: "created_at", interval: "2160h" }
      ]


================================================
FILE: deploy/kubernetes/server/gva-server-deployment.yaml
================================================
apiVersion: apps/v1
kind: Deployment
metadata:
  name: gva-server
  annotations:
    flipped-aurora/gin-vue-admin: backend
    github: "https://github.com/flipped-aurora/gin-vue-admin.git"
    app.kubernetes.io/version: 0.0.1
  labels:
    app: gva-server
    version: gva-vue3
spec:
  replicas: 1
  selector:
    matchLabels:
      app: gva-server
      version: gva-vue3
  template:
    metadata:
      labels:
        app: gva-server
        version: gva-vue3
    spec:
      containers:
        - name: gin-vue-admin-container
          image: registry.cn-hangzhou.aliyuncs.com/gva/server:latest
          imagePullPolicy: Always
          ports:
            - containerPort: 8888
              name: http
          volumeMounts:
            - mountPath: /go/src/github.com/flipped-aurora/gin-vue-admin/server/config.docker.yaml
              name: config
              subPath: config.yaml
            - mountPath: /etc/localtime
              name: localtime
          resources:
            limits:
              cpu: 1000m
              memory: 2000Mi
            requests:
              cpu: 100m
              memory: 200Mi
          livenessProbe:
            failureThreshold: 1
            periodSeconds: 5
            successThreshold: 1
            tcpSocket:
              port: 8888
            timeoutSeconds: 1
          readinessProbe:
            failureThreshold: 3
            initialDelaySeconds: 30
            periodSeconds: 5
            successThreshold: 1
            tcpSocket:
              port: 8888
            timeoutSeconds: 1
          startupProbe:
            failureThreshold: 40
            periodSeconds: 5
            successThreshold: 1
            tcpSocket:
              port: 8888
            timeoutSeconds: 1
      #imagePullSecrets:
      #  - name: docker-registry
      volumes:
        - name: localtime
          hostPath:
            path: /etc/localtime
        - name: config
          configMap:
            name: config.yaml

================================================
FILE: deploy/kubernetes/server/gva-server-service.yaml
================================================
apiVersion: v1
kind: Service
metadata:
  name: gva-server
  annotations:
    flipped-aurora/gin-vue-admin: backend
    github: "https://github.com/flipped-aurora/gin-vue-admin.git"
    app.kubernetes.io/version: 0.0.1
  labels:
    app: gva-server
    version: gva-vue3
spec:
  selector:
    app: gva-server
    version: gva-vue3
  ports:
    - port: 8888
      name: http
      targetPort: 8888
  type: ClusterIP
#  type: NodePort


================================================
FILE: deploy/kubernetes/web/gva-web-configmap.yaml
================================================
apiVersion: v1
kind: ConfigMap
metadata:
  name: my.conf
data:
  my.conf: |
    server {
        listen       8080;
        server_name localhost;

        #charset koi8-r;
        #access_log  logs/host.access.log  main;

        location / {
            root /usr/share/nginx/html;
            add_header Cache-Control 'no-store, no-cache, must-revalidate, proxy-revalidate, max-age=0';
            try_files $uri $uri/ /index.html;
        }

        location /api {
            proxy_set_header Host $http_host;
            proxy_set_header  X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
            rewrite ^/api/(.*)$ /$1 break;         #重写
            proxy_pass http://gva-server:8888;     # 设置代理服务器的协议和地址
         }

        location /api/swagger/index.html {
            proxy_pass http://gva-server:8888/swagger/index.html;
         }
     }

================================================
FILE: deploy/kubernetes/web/gva-web-deploymemt.yaml
================================================
apiVersion: apps/v1
kind: Deployment
metadata:
  name: gva-web
  annotations:
    flipped-aurora/gin-vue-admin: ui
    github: "https://github.com/flipped-aurora/gin-vue-admin.git"
    app.kubernetes.io/version: 0.0.1
  labels:
    app: gva-web
    version: gva-vue3
spec:
  replicas: 1
  selector:
    matchLabels:
      app: gva-web
      version: gva-vue3
  template:
    metadata:
      labels:
        app: gva-web
        version: gva-vue3
    spec:
      containers:
        - name: gin-vue-admin-nginx-container
          image: registry.cn-hangzhou.aliyuncs.com/gva/web:latest
          imagePullPolicy: Always
          ports:
            - containerPort: 8080
              name: http
          readinessProbe:
            tcpSocket:
              port: 8080
            initialDelaySeconds: 10
            periodSeconds: 10
            successThreshold: 1
            failureThreshold: 3
          resources:
            limits:
              cpu: 500m
              memory: 1000Mi
            requests:
              cpu: 100m
              memory: 100Mi
          volumeMounts:
            - mountPath: /etc/nginx/conf.d/
              name: nginx-config
      volumes:
        - name: nginx-config
          configMap:
            name: my.conf


================================================
FILE: deploy/kubernetes/web/gva-web-ingress.yaml
================================================
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: gva-ingress
  annotations:
    kubernetes.io/ingress.class: "nginx"
spec:
  rules:
  - host: demo.gin-vue-admin.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: gva-web
            port:
              number: 8080

================================================
FILE: deploy/kubernetes/web/gva-web-service.yaml
================================================
apiVersion: v1
kind: Service
metadata:
  name: gva-web
  annotations:
    flipped-aurora/gin-vue-admin: ui
    github: "https://github.com/flipped-aurora/gin-vue-admin.git"
    app.kubernetes.io/version: 0.0.1
  labels:
    app: gva-web
    version: gva-vue3
spec:
#  type: NodePort
  type: ClusterIP
  ports:
    - name: http
      port: 8080
      targetPort: 8080
  selector:
    app: gva-web
    version: gva-vue3


================================================
FILE: gin-vue-admin.code-workspace
================================================
{
  "folders": [
    {
      "path": "server",
      "name": "backend"
    },
    {
      "path": "web",
      "name": "frontend"
    },
    {
      "path": ".",
      "name": "root"
    }
  ],
  "settings": {
    "go.toolsEnvVars": {
      "GOPROXY": "https://goproxy.cn,direct",
      "GONOPROXY": "none;"
    }
  },
  "launch": {
    "version": "0.2.0",
    "configurations": [
      {
        "type": "go",
        "request": "launch",
        "name": "Backend",
        "cwd": "${workspaceFolder:backend}",
        "program": "${workspaceFolder:backend}/"
      },
      {
        "type": "node",
        "request": "launch",
        "cwd": "${workspaceFolder:frontend}",
        "name": "Frontend",
        "runtimeExecutable": "npm",
        "runtimeArgs": ["run-script", "serve"]
      }
    ],
    "compounds": [
      {
        "name": "Both (Backend & Frontend)",
        "configurations": ["Backend", "Frontend"],
        "stopAll": true
      }
    ]
  }
}


================================================
FILE: server/Dockerfile
================================================
FROM golang:alpine as builder

WORKDIR /go/src/github.com/flipped-aurora/gin-vue-admin/server
COPY . .

RUN go env -w GO111MODULE=on \
    && go env -w GOPROXY=https://goproxy.cn,direct \
    && go env -w CGO_ENABLED=0 \
    && go env \
    && go mod tidy \
    && go build -o server .

FROM alpine:latest

LABEL MAINTAINER="SliverHorn@sliver_horn@qq.com"
# 设置时区
ENV TZ=Asia/Shanghai
RUN apk update && apk add --no-cache tzdata openntpd \
    && ln -sf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone

WORKDIR /go/src/github.com/flipped-aurora/gin-vue-admin/server

COPY --from=0 /go/src/github.com/flipped-aurora/gin-vue-admin/server/server ./
COPY --from=0 /go/src/github.com/flipped-aurora/gin-vue-admin/server/resource ./resource/
COPY --from=0 /go/src/github.com/flipped-aurora/gin-vue-admin/server/config.docker.yaml ./

# 挂载目录：如果使用了sqlite数据库，容器命令示例：docker run -d -v /宿主机路径/gva.db:/go/src/github.com/flipped-aurora/gin-vue-admin/server/gva.db -p 8888:8888 --name gva-server-v1 gva-server:1.0
# VOLUME ["/go/src/github.com/flipped-aurora/gin-vue-admin/server"]

EXPOSE 8888
ENTRYPOINT ./server -c config.docker.yaml


================================================
FILE: server/README.md
================================================
## server项目结构

```shell
├── api
│   └── v1
├── config
├── core
├── docs
├── global
├── initialize
│   └── internal
├── middleware
├── model
│   ├── request
│   └── response
├── packfile
├── resource
│   ├── excel
│   ├── page
│   └── template
├── router
├── service
├── source
└── utils
    ├── timer
    └── upload
```

| 文件夹       | 说明                    | 描述                        |
| ------------ | ----------------------- | --------------------------- |
| `api`        | api层                   | api层 |
| `--v1`       | v1版本接口              | v1版本接口                  |
| `config`     | 配置包                  | config.yaml对应的配置结构体 |
| `core`       | 核心文件                | 核心组件(zap, viper, server)的初始化 |
| `docs`       | swagger文档目录         | swagger文档目录 |
| `global`     | 全局对象                | 全局对象 |
| `initialize` | 初始化 | router,redis,gorm,validator, timer的初始化 |
| `--internal` | 初始化内部函数 | gorm 的 longger 自定义,在此文件夹的函数只能由 `initialize` 层进行调用 |
| `middleware` | 中间件层 | 用于存放 `gin` 中间件代码 |
| `model`      | 模型层                  | 模型对应数据表              |
| `--request`  | 入参结构体              | 接收前端发送到后端的数据。  |
| `--response` | 出参结构体              | 返回给前端的数据结构体      |
| `packfile`   | 静态文件打包            | 静态文件打包 |
| `resource`   | 静态资源文件夹          | 负责存放静态文件                |
| `--excel` | excel导入导出默认路径 | excel导入导出默认路径 |
| `--page` | 表单生成器 | 表单生成器 打包后的dist |
| `--template` | 模板 | 模板文件夹,存放的是代码生成器的模板 |
| `router`     | 路由层                  | 路由层 |
| `service`    | service层               | 存放业务逻辑问题 |
| `source` | source层 | 存放初始化数据的函数 |
| `utils`      | 工具包                  | 工具函数封装            |
| `--timer` | timer | 定时器接口封装 |
| `--upload`      | oss                  | oss接口封装        |



================================================
FILE: server/api/v1/enter.go
================================================
package v1

import (
	"github.com/flipped-aurora/gin-vue-admin/server/api/v1/example"
	"github.com/flipped-aurora/gin-vue-admin/server/api/v1/system"
)

var ApiGroupApp = new(ApiGroup)

type ApiGroup struct {
	SystemApiGroup  system.ApiGroup
	ExampleApiGroup example.ApiGroup
}


================================================
FILE: server/api/v1/example/enter.go
================================================
package example

import "github.com/flipped-aurora/gin-vue-admin/server/service"

type ApiGroup struct {
	CustomerApi
	FileUploadAndDownloadApi
	AttachmentCategoryApi
}

var (
	customerService              = service.ServiceGroupApp.ExampleServiceGroup.CustomerService
	fileUploadAndDownloadService = service.ServiceGroupApp.ExampleServiceGroup.FileUploadAndDownloadService
	attachmentCategoryService    = service.ServiceGroupApp.ExampleServiceGroup.AttachmentCategoryService
)


================================================
FILE: server/api/v1/example/exa_attachment_category.go
================================================
package example

import (
	"github.com/flipped-aurora/gin-vue-admin/server/global"
	common "github.com/flipped-aurora/gin-vue-admin/server/model/common/request"
	"github.com/flipped-aurora/gin-vue-admin/server/model/common/response"
	"github.com/flipped-aurora/gin-vue-admin/server/model/example"
	"github.com/gin-gonic/gin"
	"go.uber.org/zap"
)

type AttachmentCategoryApi struct{}

// GetCategoryList
// @Tags      GetCategoryList
// @Summary   媒体库分类列表
// @Security  AttachmentCategory
// @Produce   application/json
// @Success   200   {object}  response.Response{data=example.ExaAttachmentCategory,msg=string}  "媒体库分类列表"
// @Router    /attachmentCategory/getCategoryList [get]
func (a *AttachmentCategoryApi) GetCategoryList(c *gin.Context) {
	res, err := attachmentCategoryService.GetCategoryList()
	if err != nil {
		global.GVA_LOG.Error("获取分类列表失败!", zap.Error(err))
		response.FailWithMessage("获取分类列表失败", c)
		return
	}
	response.OkWithData(res, c)
}

// AddCategory
// @Tags      AddCategory
// @Summary   添加媒体库分类
// @Security  AttachmentCategory
// @accept    application/json
// @Produce   application/json
// @Param     data  body      example.ExaAttachmentCategory  true  "媒体库分类数据"// @Success   200   {object}  response.Response{msg=string}   "添加媒体库分类"
// @Router    /attachmentCategory/addCategory [post]
func (a *AttachmentCategoryApi) AddCategory(c *gin.Context) {
	var req example.ExaAttachmentCategory
	if err := c.ShouldBindJSON(&req); err != nil {
		global.GVA_LOG.Error("参数错误!", zap.Error(err))
		response.FailWithMessage("参数错误", c)
		return
	}

	if err := attachmentCategoryService.AddCategory(&req); err != nil {
		global.GVA_LOG.Error("创建/更新失败!", zap.Error(err))
		response.FailWithMessage("创建/更新失败："+err.Error(), c)
		return
	}
	response.OkWithMessage("创建/更新成功", c)
}

// DeleteCategory
// @Tags      DeleteCategory
// @Summary   删除分类
// @Security  AttachmentCategory
// @accept    application/json
// @Produce   application/json
// @Param     data  body      common.GetById                true  "分类id"
// @Success   200   {object}  response.Response{msg=string}  "删除分类"
// @Router    /attachmentCategory/deleteCategory [post]
func (a *AttachmentCategoryApi) DeleteCategory(c *gin.Context) {
	var req common.GetById
	if err := c.ShouldBindJSON(&req); err != nil {
		response.FailWithMessage("参数错误", c)
		return
	}

	if req.ID == 0 {
		response.FailWithMessage("参数错误", c)
		return
	}

	if err := attachmentCategoryService.DeleteCategory(&req.ID); err != nil {
		response.FailWithMessage("删除失败", c)
		return
	}

	response.OkWithMessage("删除成功", c)
}


================================================
FILE: server/api/v1/example/exa_breakpoint_continue.go
================================================
package example

import (
	"fmt"
	"io"
	"mime/multipart"
	"strconv"
	"strings"

	"github.com/flipped-aurora/gin-vue-admin/server/model/example"

	"github.com/flipped-aurora/gin-vue-admin/server/global"
	"github.com/flipped-aurora/gin-vue-admin/server/model/common/response"
	exampleRes "github.com/flipped-aurora/gin-vue-admin/server/model/example/response"
	"github.com/flipped-aurora/gin-vue-admin/server/utils"
	"github.com/gin-gonic/gin"
	"go.uber.org/zap"
)

// BreakpointContinue
// @Tags      ExaFileUploadAndDownload
// @Summary   断点续传到服务器
// @Security  ApiKeyAuth
// @accept    multipart/form-data
// @Produce   application/json
// @Param     file  formData  file                           true  "an example for breakpoint resume, 断点续传示例"
// @Success   200   {object}  response.Response{msg=string}  "断点续传到服务器"
// @Router    /fileUploadAndDownload/breakpointContinue [post]
func (b *FileUploadAndDownloadApi) BreakpointContinue(c *gin.Context) {
	fileMd5 := c.Request.FormValue("fileMd5")
	fileName := c.Request.FormValue("fileName")
	chunkMd5 := c.Request.FormValue("chunkMd5")
	chunkNumber, _ := strconv.Atoi(c.Request.FormValue("chunkNumber"))
	chunkTotal, _ := strconv.Atoi(c.Request.FormValue("chunkTotal"))
	_, FileHeader, err := c.Request.FormFile("file")
	if err != nil {
		global.GVA_LOG.Error("接收文件失败!", zap.Error(err))
		response.FailWithMessage("接收文件失败", c)
		return
	}
	f, err := FileHeader.Open()
	if err != nil {
		global.GVA_LOG.Error("文件读取失败!", zap.Error(err))
		response.FailWithMessage("文件读取失败", c)
		return
	}
	defer func(f multipart.File) {
		err := f.Close()
		if err != nil {
			fmt.Println(err)
		}
	}(f)
	cen, _ := io.ReadAll(f)
	if !utils.CheckMd5(cen, chunkMd5) {
		global.GVA_LOG.Error("检查md5失败!", zap.Error(err))
		response.FailWithMessage("检查md5失败", c)
		return
	}
	file, err := fileUploadAndDownloadService.FindOrCreateFile(fileMd5, fileName, chunkTotal)
	if err != nil {
		global.GVA_LOG.Error("查找或创建记录失败!", zap.Error(err))
		response.FailWithMessage("查找或创建记录失败", c)
		return
	}
	pathC, err := utils.BreakPointContinue(cen, fileName, chunkNumber, chunkTotal, fileMd5)
	if err != nil {
		global.GVA_LOG.Error("断点续传失败!", zap.Error(err))
		response.FailWithMessage("断点续传失败", c)
		return
	}

	if err = fileUploadAndDownloadService.CreateFileChunk(file.ID, pathC, chunkNumber); err != nil {
		global.GVA_LOG.Error("创建文件记录失败!", zap.Error(err))
		response.FailWithMessage("创建文件记录失败", c)
		return
	}
	response.OkWithMessage("切片创建成功", c)
}

// FindFile
// @Tags      ExaFileUploadAndDownload
// @Summary   查找文件
// @Security  ApiKeyAuth
// @accept    multipart/form-data
// @Produce   application/json
// @Param     file  formData  file                                                        true  "Find the file, 查找文件"
// @Success   200   {object}  response.Response{data=exampleRes.FileResponse,msg=string}  "查找文件,返回包括文件详情"
// @Router    /fileUploadAndDownload/findFile [get]
func (b *FileUploadAndDownloadApi) FindFile(c *gin.Context) {
	fileMd5 := c.Query("fileMd5")
	fileName := c.Query("fileName")
	chunkTotal, _ := strconv.Atoi(c.Query("chunkTotal"))
	file, err := fileUploadAndDownloadService.FindOrCreateFile(fileMd5, fileName, chunkTotal)
	if err != nil {
		global.GVA_LOG.Error("查找失败!", zap.Error(err))
		response.FailWithMessage("查找失败", c)
	} else {
		response.OkWithDetailed(exampleRes.FileResponse{File: file}, "查找成功", c)
	}
}

// BreakpointContinueFinish
// @Tags      ExaFileUploadAndDownload
// @Summary   创建文件
// @Security  ApiKeyAuth
// @accept    multipart/form-data
// @Produce   application/json
// @Param     file  formData  file                                                            true  "上传文件完成"
// @Success   200   {object}  response.Response{data=exampleRes.FilePathResponse,msg=string}  "创建文件,返回包括文件路径"
// @Router    /fileUploadAndDownload/findFile [post]
func (b *FileUploadAndDownloadApi) BreakpointContinueFinish(c *gin.Context) {
	fileMd5 := c.Query("fileMd5")
	fileName := c.Query("fileName")
	filePath, err := utils.MakeFile(fileName, fileMd5)
	if err != nil {
		global.GVA_LOG.Error("文件创建失败!", zap.Error(err))
		response.FailWithDetailed(exampleRes.FilePathResponse{FilePath: filePath}, "文件创建失败", c)
	} else {
		response.OkWithDetailed(exampleRes.FilePathResponse{FilePath: filePath}, "文件创建成功", c)
	}
}

// RemoveChunk
// @Tags      ExaFileUploadAndDownload
// @Summary   删除切片
// @Security  ApiKeyAuth
// @accept    multipart/form-data
// @Produce   application/json
// @Param     file  formData  file                           true  "删除缓存切片"
// @Success   200   {object}  response.Response{msg=string}  "删除切片"
// @Router    /fileUploadAndDownload/removeChunk [post]
func (b *FileUploadAndDownloadApi) RemoveChunk(c *gin.Context) {
	var file example.ExaFile
	err := c.ShouldBindJSON(&file)
	if err != nil {
		response.FailWithMessage(err.Error(), c)
		return
	}
	// 路径穿越拦截
	if strings.Contains(file.FilePath, "..") || strings.Contains(file.FilePath, "../") || strings.Contains(file.FilePath, "./") || strings.Contains(file.FilePath, ".\\") {
		response.FailWithMessage("非法路径，禁止删除", c)
		return
	}
	err = utils.RemoveChunk(file.FileMd5)
	if err != nil {
		global.GVA_LOG.Error("缓存切片删除失败!", zap.Error(err))
		return
	}
	err = fileUploadAndDownloadService.DeleteFileChunk(file.FileMd5, file.FilePath)
	if err != nil {
		global.GVA_LOG.Error(err.Error(), zap.Error(err))
		response.FailWithMessage(err.Error(), c)
		return
	}
	response.OkWithMessage("缓存切片删除成功", c)
}


================================================
FILE: server/api/v1/example/exa_customer.go
================================================
package example

import (
	"github.com/flipped-aurora/gin-vue-admin/server/global"
	"github.com/flipped-aurora/gin-vue-admin/server/model/common/request"
	"github.com/flipped-aurora/gin-vue-admin/server/model/common/response"
	"github.com/flipped-aurora/gin-vue-admin/server/model/example"
	exampleRes "github.com/flipped-aurora/gin-vue-admin/server/model/example/response"
	"github.com/flipped-aurora/gin-vue-admin/server/utils"
	"github.com/gin-gonic/gin"
	"go.uber.org/zap"
)

type CustomerApi struct{}

// CreateExaCustomer
// @Tags      ExaCustomer
// @Summary   创建客户
// @Security  ApiKeyAuth
// @accept    application/json
// @Produce   application/json
// @Param     data  body      example.ExaCustomer            true  "客户用户名, 客户手机号码"
// @Success   200   {object}  response.Response{msg=string}  "创建客户"
// @Router    /customer/customer [post]
func (e *CustomerApi) CreateExaCustomer(c *gin.Context) {
	var customer example.ExaCustomer
	err := c.ShouldBindJSON(&customer)
	if err != nil {
		response.FailWithMessage(err.Error(), c)
		return
	}
	err = utils.Verify(customer, utils.CustomerVerify)
	if err != nil {
		response.FailWithMessage(err.Error(), c)
		return
	}
	customer.SysUserID = utils.GetUserID(c)
	customer.SysUserAuthorityID = utils.GetUserAuthorityId(c)
	err = customerService.CreateExaCustomer(customer)
	if err != nil {
		global.GVA_LOG.Error("创建失败!", zap.Error(err))
		response.FailWithMessage("创建失败", c)
		return
	}
	response.OkWithMessage("创建成功", c)
}

// DeleteExaCustomer
// @Tags      ExaCustomer
// @Summary   删除客户
// @Security  ApiKeyAuth
// @accept    application/json
// @Produce   application/json
// @Param     data  body      example.ExaCustomer            true  "客户ID"
// @Success   200   {object}  response.Response{msg=string}  "删除客户"
// @Router    /customer