[
{
"path": ".air.toml",
"content": "root = \".\"\ntestdata_dir = \"testdata\"\ntmp_dir = \"tmp\"\n\n[build]\n args_bin = []\n # 使用相对路径，或者不指定配置文件让程序自动查找\n bin = \"./tmp/main service\"\n cmd = \"go build -o ./tmp/main\"\n # 设置环境变量\n env = [\"GO_ENV=development\"]\n delay = 0\n exclude_dir = [\"assets\", \"tmp\", \"vendor\", \"testdata\", \"logs\", \"tests\"]\n exclude_file = []\n exclude_regex = [\"_test.go\"]\n exclude_unchanged = false\n follow_symlink = false\n full_bin = \"\"\n include_dir = []\n include_ext = [\"go\", \"tpl\", \"tmpl\", \"html\"]\n include_file = []\n kill_delay = \"0s\"\n log = \"./logs/build-errors.log\"\n poll = false\n poll_interval = 0\n rerun = false\n rerun_delay = 500\n send_interrupt = false\n stop_on_error = false\n\n[color]\n app = \"\"\n build = \"yellow\"\n main = \"magenta\"\n runner = \"green\"\n watcher = \"cyan\"\n\n[log]\n main_only = false\n time = false\n\n[misc]\n clean_on_exit = false\n\n[screen]\n clear_on_rebuild = false\n keep_scroll = true\n"
},
{
"path": ".github/pull_request_template.md",
"content": "## 变更说明\n\n- 主要目标：\n- 影响模块：\n- 风险等级：低 / 中 / 高\n\n## 自查清单\n\n- [ ] 已确认本次改动解决的是主要问题，而不是无关重构\n- [ ] 已调研相关代码并复用现有实现（未重复造轮子）\n- [ ] 已评估影响范围与兼容性（必要时给出回滚方案）\n- [ ] 已补充或更新测试（至少覆盖一个新增/修改分支）\n\n## 可读性专项检查（必填）\n\n- [ ] 未引入“仅一层转发且无语义增量”的新方法\n- [ ] 如果新增拆分，已说明拆分理由（事务边界 / 复用 / 测试隔离）\n- [ ] 方法职责保持单一，命名表达清晰\n- [ ] 跨文件跳转成本可接受（阅读主流程不需要反复来回定位）\n\n## 验证记录\n\n- 本地执行命令：\n - `go test ./...`\n- 关键结果：\n\n## 关联信息\n\n- 关联 Issue / 任务：\n- 额外说明：\n"
},
{
"path": ".github/workflows/codeql.yml",
"content": "# For most projects, this workflow file will not need changing; you simply need\n# to commit it to your repository.\n#\n# You may wish to alter this file to override the set of languages analyzed,\n# or to provide custom queries or build logic.\n#\n# ******** NOTE ********\n# We have attempted to detect the languages in your repository. Please check\n# the `language` matrix defined below to confirm you have the correct set of\n# supported CodeQL languages.\n#\nname: \"CodeQL\"\n\non:\n push:\n branches: [ master, x_l_admin ]\n pull_request:\n # The branches below must be a subset of the branches above\n branches: [ master, x_l_admin ]\n schedule:\n - cron: '27 0 * * 6'\n\njobs:\n analyze:\n name: Analyze\n runs-on: ubuntu-latest\n permissions:\n actions: read\n contents: read\n security-events: write\n\n strategy:\n fail-fast: false\n matrix:\n language: [ 'go' ]\n # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby' ]\n # Learn more about CodeQL language support at https://aka.ms/codeql-docs/language-support\n\n steps:\n - name: Checkout repository\n uses: actions/checkout@v3\n\n # Initializes the CodeQL tools for scanning.\n - name: Initialize CodeQL\n uses: github/codeql-action/init@v2\n with:\n languages: ${{ matrix.language }}\n # If you wish to specify custom queries, you can do so here or in a config file.\n # By default, queries listed here will override any specified in a config file.\n # Prefix the list here with \"+\" to use these queries and those in the config file.\n\n # Details on CodeQL's query packs refer to : https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs\n # queries: security-extended,security-and-quality\n\n\n # Autobuild attempts to build any compiled languages (C/C++, C#, or Java).\n # If this step fails, then you should remove it and run the build manually (see below)\n - name: Autobuild\n uses: github/codeql-action/autobuild@v2\n\n # ℹ️ Command-line programs to run using the OS shell.\n # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun\n\n # If the Autobuild fails above, remove it and uncomment the following three lines.\n # modify them (or add more) to build your code if your project, please refer to the EXAMPLE below for guidance.\n\n # - run: |\n # echo \"Run, Build Application using script\"\n # ./location_of_script_within_repo/buildscript.sh\n\n - name: Perform CodeQL Analysis\n uses: github/codeql-action/analyze@v2"
},
{
"path": ".github/workflows/go.yml",
"content": "name: Go\n\non:\n push:\n branches: [ master, x_l_admin ]\n pull_request:\n branches: [ master, x_l_admin ]\n\njobs:\n\n build:\n runs-on: ubuntu-latest\n strategy:\n matrix:\n go-version: [ '1.26.x' ]\n steps:\n - uses: actions/checkout@v3\n\n - name: Setup Go ${{ matrix.go-version }}\n uses: actions/setup-go@v4\n with:\n go-version: ${{ matrix.go-version }}\n\n - name: Display Go version\n run: go version\n\n - name: Build\n run: go build -v ./...\n\n - name: Test\n run: go test $(go list ./... | grep -v /tests/)"
},
{
"path": ".gitignore",
"content": "# Binaries for programs and plugins\n*.exe\n*.exe~\n*.dll\n*.so\n*.dylib\n\n# Test binary, built with `go test -c`\n*.test\n\n# Output of the go coverage tool, specifically when used with LiteIDE\n*.out\n\n# Dependency directories (remove the comment below to include it)\n# vendor/\n\n# IDE and editor files\n.idea\n.vscode\n*.DS_Store\n\n# Runtime directories\nstorage\nlogs/\ntmp\nbuild/\n\n# Local config and environment files\n*.yaml\n*.ini\n.env\n.env.local\n.env.*.local\n\n# Claude Code local settings (keep memory but ignore local configs)\n.claude\n\n# Application binaries\ngin-layout\ngin-layout/\ngo-layout\n/migrate\n\n# Documentation (project-specific, not for version control)\nPROJECT_ARCHITECTURE.md\nCODE_OPTIMIZATION_REPORT.md\n\n# Go cache\n.gocache\n.go-test-cache\n\n# Memory (if you want to keep it local only)\n# memory/\n.aitasks\n"
},
{
"path": ".golangci.yml",
"content": "# golangci-lint 配置文件\n# 参考: https://golangci-lint.run/usage/configuration/\n\nrun:\n # 超时时间\n timeout: 5m\n # 并发数\n concurrency: 4\n # 包含的测试文件\n tests: true\n # 跳过目录\n skip-dirs:\n - vendor\n - build\n - dist\n - logs\n - storage\n - tmp\n # 跳过文件\n skip-files:\n - \".*\\\\.pb\\\\.go$\"\n - \".*\\\\.gen\\\\.go$\"\n\n# 输出配置\noutput:\n # 输出格式: colored-line-number, line-number, json, tab, checkstyle, code-climate, html, junit-xml, github-actions\n format: colored-line-number\n # 打印问题数量\n print-issued-lines: true\n # 打印 linter 名称\n print-linter-name: true\n # 不打印欢迎信息\n uniq-by-line: false\n # 打印源代码行\n print-welcome: false\n\n# 启用的 linter\nlinters:\n enable:\n # 代码质量\n - errcheck # 检查错误处理\n - gosimple # 简化代码建议\n - govet # go vet 检查\n - ineffassign # 检查未使用的赋值\n - staticcheck # 静态分析\n - unused # 检查未使用的代码\n \n # 代码风格\n - gofmt # 代码格式检查\n - goimports # import 语句检查\n - misspell # 拼写检查\n - revive # Go 代码检查工具（替代 golint）\n - stylecheck # 风格检查\n \n # 性能\n - prealloc # 预分配切片检查\n \n # 复杂度\n - gocyclo # 圈复杂度检查\n - gocognit # 认知复杂度检查\n \n # 其他\n - exportloopref # 循环变量引用检查\n - gocritic # 代码审查建议\n - gosec # 安全检查\n - nakedret # 检查裸返回\n - noctx # 检查 context 传递\n - rowserrcheck # 检查 rows.Err()\n - sqlclosecheck # 检查 SQL 连接关闭\n\nlinters-settings:\n # errcheck 配置\n errcheck:\n check-type-assertions: true\n check-blank: true\n \n # gocyclo 配置 - 圈复杂度阈值\n gocyclo:\n min-complexity: 15\n \n # gocognit 配置 - 认知复杂度阈值\n gocognit:\n min-complexity: 15\n \n # revive 配置\n revive:\n rules:\n - name: exported\n severity: warning\n - name: var-naming\n severity: warning\n - name: package-comments\n severity: warning\n - name: range\n severity: warning\n - name: increment-decrement\n severity: warning\n - name: error-return\n severity: warning\n - name: error-strings\n severity: warning\n - name: error-naming\n severity: warning\n - name: receiver-naming\n severity: warning\n - name: unexported-return\n severity: warning\n - name: time-equal\n severity: warning\n - name: banned-characters\n severity: warning\n - name: context-keys-type\n severity: warning\n - name: context-as-argument\n severity: warning\n - name: if-return\n severity: warning\n - name: increment-decrement\n severity: warning\n - name: var-declaration\n severity: warning\n - name: range-val-in-closure\n severity: warning\n - name: range-val-address\n severity: warning\n - name: waitgroup-by-value\n severity: warning\n - name: atomic\n severity: warning\n - name: empty-lines\n severity: warning\n - name: line-length-limit\n severity: warning\n arguments:\n - 120\n \n # gocritic 配置\n gocritic:\n enabled-tags:\n - diagnostic\n - experimental\n - opinionated\n - performance\n - style\n disabled-checks:\n - dupImport # 允许重复导入（某些情况下需要）\n - ifElseChain # 允许 if-else 链\n - octalLiteral # 允许八进制字面量\n \n # gosec 配置\n gosec:\n # 严重程度: low, medium, high\n severity: medium\n # 置信度: low, medium, high\n confidence: medium\n # 排除的规则\n excludes:\n - G104 # 审计错误未检查（某些情况下可以接受）\n - G401 # 弱随机数生成（某些场景可以接受）\n - G501 # 导入黑名单（某些依赖是必需的）\n\nissues:\n # 排除的问题\n exclude-rules:\n # 排除测试文件中的某些检查\n - path: _test\\.go\n linters:\n - errcheck\n - gosec\n - gocritic\n - gocyclo\n - gocognit\n \n # 最大问题数（0 表示不限制）\n max-issues-per-linter: 0\n max-same-issues: 0\n \n # 排除的问题模式\n exclude:\n # 排除 \"Error return value of .((os\\.)?std(out|err)\\..*|.*Close|.*Flush|os\\.Remove(All)?|.*printf?|os\\.(Un)?Setenv). is not checked\"\n - 'Error return value of .((os\\.)?std(out|err)\\..*|.*Close|.*Flush|os\\.Remove(All)?|.*printf?|os\\.(Un)?Setenv). is not checked'\n # 排除 \"exported function .* should have comment\"\n - 'exported function .* should have comment'\n # 排除 \"comment on exported .* should be of the form\"\n - 'comment on exported .* should be of the form'\n\n"
},
{
"path": "LICENSE",
"content": "MIT License\n\nCopyright (c) 2022 wannanbigpig\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n"
},
{
"path": "MEMORY.md",
"content": "# MEMORY\n\n这份文档写给接手 `gin-layout` 的 AI Agent。它不是项目营销介绍，而是为了让下一位 AI 尽快知道：\n\n- 项目当前真实状态是什么\n- 主要入口、核心链路和高风险区域在哪\n- 关键约束和禁止事项是什么\n- 写代码时如何保持当前项目风格\n\n## 0. 快速结论\n\n先记住这些，不确定时再往下查细节：\n\n- 代码是真相，文档只是辅助；文档和代码冲突时，以代码为准并顺手修正文档。\n- 新功能优先沿用现有 `service / model / resources / validator` 分层。\n- 保持现有工程范式，不引入重框架化、函数式大重写、新 DI 容器或 repository 全量替换。\n- Casbin 使用 `github.com/casbin/casbin/v3`。\n- 鉴权链路采用 claims-first：请求上下文保存 `AuthPrincipal`，不是完整数据库 `AdminUser`。\n- 错误文案按请求语言国际化返回；需要自定义错误文案时优先使用错误码或 message key，而不是在 controller 里硬编码中文。\n- 请求审计是“审计快照 + 队列优先”：队列开启时异步落库，队列关闭时才同步落库审计日志。\n- CORS 使用常规 `[\"*\"]` 语义。\n- 菜单列表/树只返回当前语言 `title`；菜单详情返回 `title_i18n`，不返回 `title`。\n- 继续改代码时保持小步修改、局部重组、命名稳定。\n- 改完代码必须自己验证；新增或修改 HTTP 行为默认要补 `tests/` 接口级测试。\n\n## 1. 禁止事项\n\n当前代码库禁止这样做：\n\n- 引入 `casbin/v2` 或混用不同主版本的 Casbin adapter。\n- 在认证中间件里每个请求都回表查询完整 `AdminUser`；账号状态变更应通过服务层撤销 token 或更新会话状态生效。\n- 把 `AuthPrincipal.AdminUser()` 当成数据库实时状态。\n- 在队列开启时同步落库请求审计日志。\n- 把请求日志设计成“每个请求同步写文件 + 异步审计”的双写链路。\n- 把 CORS 空数组当成全放开；显式全放开使用 `[\"*\"]`。\n- 让菜单列表或用户菜单树返回 `title_i18n`。\n- 让菜单详情返回 `title`。\n- 让菜单写接口接收 `title`；写接口使用 `title_i18n`。\n- 把业务逻辑、事务或批量数据修复塞进 controller。\n- 把所有逻辑塞回单个超大 service 文件。\n- 绕过 `PermissionSyncCoordinator` 分散写入 Casbin 权限。\n- 只改代码不跑测试，或把验证责任留给用户或下一个 AI。\n\n## 2. 当前定位\n\n项目名：`gin-layout`\n\n这是一个偏后台管理场景的 Go 后端骨架，内置：\n\n- JWT 登录、校验、刷新、登出\n- Casbin RBAC 接口权限控制\n- 管理员、角色、部门、菜单、API 权限体系\n- 请求日志、登录日志、审计日志\n- 文件上传与本地文件访问\n- CLI 命令、定时任务、异步队列 worker\n\n运行形态包含三类进程：\n\n1. `service`\n - 提供 HTTP API\n - 构建请求审计日志快照\n - 队列开启时把审计快照投递到异步队列\n - 队列关闭时在当前请求链路同步落库审计日志\n\n2. `worker`\n - 消费异步任务\n - 主要消费请求审计日志异步落库\n\n3. `cron`\n - 负责周期任务\n\n## 3. 当前事实\n\n这些是当前实现与开发规范。\n\n### 3.1 Casbin v3\n\n权限引擎是：\n\n- `github.com/casbin/casbin/v3`\n- `github.com/casbin/gorm-adapter/v3`\n\n相关入口：\n\n- [internal/access/casbin/casbin.go](/Users/liuml/data/go/src/go-layout/internal/access/casbin/casbin.go:1)\n- [internal/access/casbin/adapter.go](/Users/liuml/data/go/src/go-layout/internal/access/casbin/adapter.go:1)\n\n### 3.2 Claims-First 鉴权\n\n请求上下文保存 claims 快照，不保存完整数据库 `AdminUser` 模型：\n\n- [internal/service/auth/principal.go](/Users/liuml/data/go/src/go-layout/internal/service/auth/principal.go:1)\n- [internal/middleware/parse_token.go](/Users/liuml/data/go/src/go-layout/internal/middleware/parse_token.go:1)\n- [internal/middleware/admin_auth.go](/Users/liuml/data/go/src/go-layout/internal/middleware/admin_auth.go:1)\n\n这意味着：\n\n- 中间件不应为每个请求回表查用户。\n- 需要用户实时数据库状态的地方，由具体业务接口显式查库。\n- `AuthPrincipal.AdminUser()` 是轻量投影，不代表数据库最新状态。\n\n### 3.3 请求日志\n\n请求日志链路以审计日志为核心：\n\n- 请求链路：缓存请求体、录制响应体，构建审计快照。\n- 队列开启：把审计快照投给队列，由 worker 异步落库。\n- 队列关闭：在当前请求链路同步落库审计日志。\n\n全局 zap 文件日志用于系统日志、错误日志和 panic 日志；每个请求日志按审计快照链路处理。\n\n关键文件：\n\n- [internal/middleware/logger.go](/Users/liuml/data/go/src/go-layout/internal/middleware/logger.go:1)\n- [internal/middleware/audit_queue.go](/Users/liuml/data/go/src/go-layout/internal/middleware/audit_queue.go:1)\n- [internal/jobs/audit_log.go](/Users/liuml/data/go/src/go-layout/internal/jobs/audit_log.go:1)\n- [cmd/worker/worker.go](/Users/liuml/data/go/src/go-layout/cmd/worker/worker.go:1)\n\n### 3.4 CORS\n\n支持常规 `*` 语义：\n\n- `cors_origins: [\"*\"]`\n- `cors_methods: [\"*\"]`\n- `cors_headers: [\"*\"]`\n- `cors_expose_headers: [\"*\"]`\n\n实现位置：\n\n- [internal/middleware/cors.go](/Users/liuml/data/go/src/go-layout/internal/middleware/cors.go:1)\n- [config/config.yaml.example](/Users/liuml/data/go/src/go-layout/config/config.yaml.example:17)\n\n### 3.5 错误国际化\n\n错误文案由请求语言驱动：\n\n- `RequestLocaleHandler` 从 `Accept-Language` 解析语言并写入请求上下文。\n- 响应层根据上下文语言选择错误文案语言。\n- 通用业务错误默认走错误码文案表。\n- 需要细粒度错误文案时，优先使用 `message key`，由响应层统一国际化。\n- 参数校验错误由 validator translator 输出多语言文案，字段名优先使用 `label/json/form` 标签。\n\n关键文件：\n\n- [internal/middleware/request_locale.go](/Users/liuml/data/go/src/go-layout/internal/middleware/request_locale.go:1)\n- [internal/pkg/i18n/locale.go](/Users/liuml/data/go/src/go-layout/internal/pkg/i18n/locale.go:1)\n- [internal/pkg/errors/error.go](/Users/liuml/data/go/src/go-layout/internal/pkg/errors/error.go:1)\n- [internal/pkg/errors/zh-cn.go](/Users/liuml/data/go/src/go-layout/internal/pkg/errors/zh-cn.go:1)\n- [internal/pkg/errors/en-us.go](/Users/liuml/data/go/src/go-layout/internal/pkg/errors/en-us.go:1)\n- [internal/pkg/response/response.go](/Users/liuml/data/go/src/go-layout/internal/pkg/response/response.go:1)\n- [internal/validator/runtime.go](/Users/liuml/data/go/src/go-layout/internal/validator/runtime.go:1)\n- [internal/validator/translation.go](/Users/liuml/data/go/src/go-layout/internal/validator/translation.go:1)\n- [internal/validator/binding.go](/Users/liuml/data/go/src/go-layout/internal/validator/binding.go:1)\n\n### 3.6 菜单 I18n\n\n菜单标题由请求语言驱动：\n\n- 列表/树：只返回当前语言 `title`，不返回 `title_i18n`。\n- 详情：返回 `title_i18n` 供编辑回填，不返回 `title`。\n- 写接口：使用 `title_i18n`，支持 `zh-CN` 与 `en-US`，至少一种非空。\n\n关键文件：\n\n- [internal/controller/admin_v1/auth_menu.go](/Users/liuml/data/go/src/go-layout/internal/controller/admin_v1/auth_menu.go:1)\n- [internal/service/menu/menu_query.go](/Users/liuml/data/go/src/go-layout/internal/service/menu/menu_query.go:1)\n- [internal/service/menu/menu_edit.go](/Users/liuml/data/go/src/go-layout/internal/service/menu/menu_edit.go:1)\n- [internal/resources/menu.go](/Users/liuml/data/go/src/go-layout/internal/resources/menu.go:1)\n- [tests/admin_test/menu_test.go](/Users/liuml/data/go/src/go-layout/tests/admin_test/menu_test.go:1)\n\n### 3.7 文件组织\n\n典型职责包：\n\n- `internal/service/admin/`\n- `internal/service/role/`\n- `internal/service/dept/`\n- `internal/service/access/`\n- `internal/validator/`\n- `internal/model/`\n\n继续改时，优先往对应职责文件里放；可以同包拆文件，保持文件职责清晰。\n\n## 4. 任务阅读索引\n\n新会话建议先看：\n\n1. [README.md](/Users/liuml/data/go/src/go-layout/README.md:1)\n2. [docs/COMMANDS_AND_TASKS.md](/Users/liuml/data/go/src/go-layout/docs/COMMANDS_AND_TASKS.md:1)\n3. [cmd/root.go](/Users/liuml/data/go/src/go-layout/cmd/root.go:1)\n4. [cmd/service/service.go](/Users/liuml/data/go/src/go-layout/cmd/service/service.go:1)\n5. [internal/routers](/Users/liuml/data/go/src/go-layout/internal/routers)\n\n按任务追加阅读：\n\n- 新增或修改后台接口：\n - [internal/routers](/Users/liuml/data/go/src/go-layout/internal/routers)\n - [internal/controller/admin_v1](/Users/liuml/data/go/src/go-layout/internal/controller/admin_v1)\n - [internal/validator/form](/Users/liuml/data/go/src/go-layout/internal/validator/form)\n - [internal/service](/Users/liuml/data/go/src/go-layout/internal/service)\n - [internal/resources](/Users/liuml/data/go/src/go-layout/internal/resources)\n - [tests/admin_test](/Users/liuml/data/go/src/go-layout/tests/admin_test)\n\n- 权限 / Casbin / 菜单可见性：\n - [internal/access/casbin](/Users/liuml/data/go/src/go-layout/internal/access/casbin)\n - [internal/service/access](/Users/liuml/data/go/src/go-layout/internal/service/access)\n - [rbac_model.conf](/Users/liuml/data/go/src/go-layout/rbac_model.conf:1)\n\n- 鉴权 / token / 当前用户：\n - [internal/middleware/parse_token.go](/Users/liuml/data/go/src/go-layout/internal/middleware/parse_token.go:1)\n - [internal/middleware/admin_auth.go](/Users/liuml/data/go/src/go-layout/internal/middleware/admin_auth.go:1)\n - [internal/service/auth](/Users/liuml/data/go/src/go-layout/internal/service/auth)\n\n- 请求日志 / 审计 / 队列：\n - [internal/middleware/logger.go](/Users/liuml/data/go/src/go-layout/internal/middleware/logger.go:1)\n - [internal/middleware/audit_queue.go](/Users/liuml/data/go/src/go-layout/internal/middleware/audit_queue.go:1)\n - [internal/jobs/audit_log.go](/Users/liuml/data/go/src/go-layout/internal/jobs/audit_log.go:1)\n - [internal/service/audit](/Users/liuml/data/go/src/go-layout/internal/service/audit)\n - [cmd/worker/worker.go](/Users/liuml/data/go/src/go-layout/cmd/worker/worker.go:1)\n\n- 菜单标题国际化：\n - [internal/service/menu](/Users/liuml/data/go/src/go-layout/internal/service/menu)\n - [internal/model/menu_i18n.go](/Users/liuml/data/go/src/go-layout/internal/model/menu_i18n.go:1)\n - [internal/resources/menu.go](/Users/liuml/data/go/src/go-layout/internal/resources/menu.go:1)\n - [tests/admin_test/menu_test.go](/Users/liuml/data/go/src/go-layout/tests/admin_test/menu_test.go:1)\n\n- 模型基础能力 / 列表分页 / 删除：\n - [internal/model/base.go](/Users/liuml/data/go/src/go-layout/internal/model/base.go:1)\n - [internal/model/base_crud.go](/Users/liuml/data/go/src/go-layout/internal/model/base_crud.go:1)\n - [internal/model/base_list.go](/Users/liuml/data/go/src/go-layout/internal/model/base_list.go:1)\n - [internal/model/base_tree.go](/Users/liuml/data/go/src/go-layout/internal/model/base_tree.go:1)\n\n## 5. 目录边界\n\n目录需要按职责边界理解，而不只是物理位置。\n\n### 5.1 `cmd/`\n\n负责程序入口和启动编排，不负责业务逻辑。\n\n关键命令：\n\n- `service`\n- `worker`\n- `cron`\n- `command`\n\n### 5.2 `internal/controller/`\n\nHTTP 控制器层。\n\n职责：\n\n- 收参\n- 调 validator/form\n- 调 service\n- 返回 response\n\n不应该在 controller 里写复杂业务判断、事务或批量数据修复逻辑。\n\n### 5.3 `internal/service/`\n\n业务层核心。\n\n职责：\n\n- 业务规则\n- 事务编排\n- 模型组合查询\n- 触发权限同步\n- 触发 token 撤销\n\n这个项目的大部分改动都应该优先落在 service 层。\n\n### 5.4 `internal/model/`\n\nGORM 模型层和基础数据访问层。\n\n职责：\n\n- 表结构\n- 通用 CRUD\n- 列表分页\n- 树形节点辅助\n\n复杂业务判断放在 service 层，model 保持数据模型与通用数据访问职责。\n\n### 5.5 `internal/resources/`\n\n响应整形层。\n\n职责：\n\n- 把 model / service 结果转换成前端要的结构。\n\n响应整形采用显式 transformer，不直接把 model 原样 JSON 输出。\n\n### 5.6 `internal/validator/` 与 `internal/validator/form/`\n\n参数对象和校验规则层。\n\n职责：\n\n- 定义请求参数 struct。\n- 定义 tag 校验规则。\n- 统一错误翻译和绑定错误处理。\n\n### 5.7 `internal/service/access/`\n\n权限同步协调层。\n\n职责拆分为：\n\n- `api_cache`\n- `scope_resolver`\n- `graph_loader`\n- `coordinator`\n- `menu_api_defaults`\n- `system_defaults`\n- `user_permission_sync`\n\n外层统一从 `PermissionSyncCoordinator` 进入，业务层通过协调器触发 Casbin 权限同步。\n\n## 6. 开发风格\n\n### 6.1 命名\n\n- service 名称以业务对象命名，如 `AdminUserService`、`RoleService`。\n- constructor 用 `NewXxxService()`。\n- 业务入口方法名直接用动词：`List`、`Create`、`Update`、`Delete`、`BindRole`。\n- 内部辅助方法用小写，尽量语义直接：`buildListCondition`、`updateDeptRole`。\n\n避免引入抽象但缺少项目语境的命名，例如：\n\n- `Processor`\n- `Manager`\n- `Facade`\n- `RepositoryFactory`\n\n只有代码里存在明确同类模式时，才沿用同类命名。\n\n### 6.2 结构\n\n优先做“同包拆文件”，新增 package 前先确认职责边界确实独立。\n\n结构整理方式：\n\n- 保留 `package` 不变。\n- 保留原 service 名称不变。\n- 把一个大文件拆成多个职责文件。\n\n### 6.3 错误处理\n\n业务错误优先使用：\n\n- `internal/pkg/errors`\n\n典型方式：\n\n- `e.NewBusinessError(...)`\n\n业务错误码优先复用，保持现有错误码风格。\n\n### 6.4 事务与权限刷新\n\n事务与权限刷新规范：\n\n- service 层显式事务。\n- 事务工具统一复用。\n- 权限刷新或缓存刷新在事务提交后处理。\n\n“事务 + 后置刷新”保持在 service 层编排。\n\n### 6.5 响应\n\n接口响应走统一响应封装，不直接返回裸对象。\n\n所以：\n\n- controller 保持现有 response 风格。\n- 列表接口尽量返回 collection。\n- detail 接口尽量走 transformer。\n\n### 6.6 注释\n\n注释使用少量中文，说明职责和意图；除非必要复杂需求才写长注释。\n\n可以写：\n\n- `// BindRole 绑定角色。`\n- `// ReloadPolicyCache 在事务提交后刷新共享 Casbin Enforcer 的内存策略。`\n\n注释保持高信息密度，只解释职责、意图和复杂逻辑。\n\n## 7. 写代码硬规则\n\n### 7.1 先复用，再新增\n\n做任何功能前，先查：\n\n- service 是否存在类似逻辑。\n- model 是否存在通用方法。\n- validator 是否存在相同校验模式。\n- resources 是否存在类似 transformer。\n\n优先复用现有能力。\n\n### 7.2 小步修改\n\n这个项目是工程型仓库，不是实验仓库。\n\n可以：\n\n- 局部重构。\n- 同包拆文件。\n- 补测试。\n\n保持现有范式，尤其避免突然引入：\n\n- repository 模式全量替换。\n- 泛型 service 框架大改。\n- 新 DI 容器。\n- 新 HTTP 框架。\n\n### 7.3 保持接口签名稳定\n\n如果只是做结构优化或内部修复：\n\n- controller 签名不改。\n- service 对外方法名尽量不改。\n- HTTP API 不改。\n- CLI 命令名不改。\n\n### 7.4 新增行为要配测试\n\n尤其是下面几类：\n\n- 鉴权\n- 权限同步\n- CORS\n- 日志截断\n- token 撤销\n- 默认值生成\n- 事务提交后刷新\n\n如果是新增接口，不仅要补直接相关的测试，还要默认在 `tests/` 目录下补接口级测试用例。\n\n原因：\n\n- 项目有明确的 `tests/admin_test` 集成测试入口。\n- 只补 service 或 middleware 级测试，不足以证明接口链路真实可用。\n- 新接口至少要验证路由、鉴权、请求参数、响应结构中的关键路径。\n\n默认要求：\n\n- 新增 HTTP 接口：补 `tests/` 目录下的接口测试。\n- 修改现有 HTTP 接口行为：补或更新 `tests/` 目录下对应测试。\n- 只改内部实现且对外行为不变：可以只补包内测试，但要能说明为什么不需要接口测试。\n\n### 7.5 改完先验证\n\n改完代码后，先自己跑测试，再决定是否结束本轮工作。\n\n最小要求：\n\n- 小改动：跑直接受影响包测试。\n- 中等改动：跑相关子系统测试。\n- 公共层或高风险改动：优先跑 `go test ./...`。\n\n以下结束方式不符合项目要求：\n\n- 只改代码，不跑测试。\n- 只说“理论上没问题”。\n- 只让用户自己去验证。\n\n如果因为环境限制无法完成某项测试，结果里必须明确：\n\n- 哪些测试跑了。\n- 哪些测试没跑。\n- 没跑的原因是什么。\n\n推荐基线：\n\n```bash\ngo test ./internal/...\ngo test ./...\ngo test ./internal/middleware ./internal/service/access ./internal/service/auth\n```\n\n## 8. 新增后台接口路径\n\n建议按这个顺序：\n\n1. 在 `internal/validator/form/` 定义参数 struct。\n2. 在 `internal/model/` 复用或补充数据访问方法。\n3. 在 `internal/service/` 写业务逻辑。\n4. 在 `internal/resources/` 补返回结构。\n5. 在 `internal/controller/admin_v1/` 加控制器方法。\n6. 在 `internal/routers/` 的声明式路由树里注册。\n7. 如涉及权限元数据，同步执行 `command api-route`。\n8. 如涉及角色/菜单/API 关系变化，确认权限重建链路是否需要触发。\n9. 在 `tests/` 目录下补接口级测试。\n\n## 9. 高风险区域\n\n### 9.1 `internal/service/access`\n\n会影响：\n\n- 菜单可见性\n- API 权限\n- Casbin 最终策略\n\n### 9.2 `internal/service/auth`\n\n风险点：\n\n- 鉴权链路采用 claims-first。\n- token 黑名单 / 撤销逻辑集中在认证服务内。\n- 改不好会影响所有登录态请求。\n\n### 9.3 `internal/middleware/logger*`\n\n风险点：\n\n- 请求体截断。\n- 响应体捕获。\n- 队列异步投递。\n- 队列关闭时的同步审计落库。\n- 性能与日志正确性平衡。\n\n### 9.4 `internal/model/base_*`\n\n风险点：\n\n- 很多 model 共用。\n- 一旦改坏，会影响列表、分页、删除、防误删逻辑。\n\n## 10. 接手检查命令\n\n先看工作树状态：\n\n```bash\ngit status --short\n```\n\n再看测试基线：\n\n```bash\ngo test ./...\n```\n\n如果只改中间件 / 权限 / 鉴权，优先跑对应子集：\n\n```bash\ngo test ./internal/middleware ./internal/service/access ./internal/service/auth\n```\n\n## 11. 文档关系\n\n根目录文档建议这样理解：\n\n- [README.md](/Users/liuml/data/go/src/go-layout/README.md:1)\n - 对外项目介绍、基础使用说明。\n\n- [docs/COMMANDS_AND_TASKS.md](/Users/liuml/data/go/src/go-layout/docs/COMMANDS_AND_TASKS.md:1)\n - 命令说明、定时任务与操作约束。\n\n- 本文档\n - 给下一位 AI 的“当前状态 + 接手约束 + 写码风格”说明。\n\n如果文档和代码冲突：\n\n- 以代码为准。\n- 再顺手修正文档。\n\n## 12. 一句话接手策略\n\n先读入口和当前链路，再读与你任务相关的 service；优先复用现有结构，保持命名和接口稳定，用小步修改把需求做完，维持项目既有风格。\n"
},
{
"path": "README.en.md",
"content": "# gin-layout
\n\n\n\n
\n\n\n A Gin-based admin backend scaffold\n
\n\n\n Built with JWT auth, RBAC, request/login logging, file upload, readiness probes, validation, request-locale i18n, declarative routing, and CLI initialization commands.\n
\n\n
\n\n\n\n
\n\n## Why This Exists\n\nMost admin projects start with the same goal: get login, permissions, menus, uploads, and logs working quickly. In practice, the same engineering problems show up again and again:\n\n- Auth, permissions, logging, and file handling are split across too many places\n- Route declarations, menus, and API permissions drift apart over time\n- The same admin infrastructure is rewritten repeatedly across projects\n- Config, command, migration, and deployment workflows lack a clear baseline\n\n`gin-layout` is built to turn these repeated backend concerns into a reusable, production-oriented foundation for admin systems.\n\n## Highlights\n\n| Capability | Description |\n| --- | --- |\n| Auth | JWT login, token verification, auto refresh, and blacklist support |\n| RBAC | Admin, role, department, menu, and API permission management |\n| Route Metadata | Declarative route tree generates both Gin routes and API metadata |\n| Logs | Built-in login logs, request logs, and unified response structure |\n| File Access | File upload and public / private file access |\n| I18n | Error messages and menu titles are resolved by `Accept-Language` (`zh-CN` / `en-US`) |\n| Health Probes | Built-in `/ping` and `/health/readiness` for liveness and dependency-readiness checks |\n| Tooling | CLI commands for initialization, route sync, permission rebuild, and migrations |\n| Hot Reload | Partial config hot reload with fallback to previous live instances on failure |\n\n## Related Resources\n\n- Frontend project: [go-admin-ui](https://github.com/wannanbigpig/go-admin-ui)\n- Online docs: [Apifox](https://wannanbigpig.apifox.cn/)\n- Demo: [Live Demo](https://x-l-admin.wannanbigpig.com/)\n- Commands and jobs guide: [docs/COMMANDS_AND_TASKS.en.md](./docs/COMMANDS_AND_TASKS.en.md)\n- Migration command guide: [docs/MIGRATE_COMMANDS.en.md](./docs/MIGRATE_COMMANDS.en.md)\n\n## Quick Start\n\n### 1. Requirements\n\n- `Go >= 1.23`\n- `MySQL >= 5.7`\n- `Redis >= 5.0` (optional)\n\n### 2. Install\n\n```bash\ngit clone https://github.com/wannanbigpig/gin-layout.git\ncd gin-layout\ngo mod download\n```\n\n### 3. Run Migrations\n\nRecommended project commands:\n\n```bash\ngo run main.go command migrate # defaults to migrate up\ngo run main.go command migrate check\n```\n\nAfter migrations finish, a default baseline dataset is inserted, including the super admin account `super_admin / 123456`. It is only recommended for local initialization. Change the password immediately after the first login.\n\nFor migration file creation, timestamp naming rules, and full `down/goto/force/version` usage, see [docs/MIGRATE_COMMANDS.en.md](./docs/MIGRATE_COMMANDS.en.md).\n\n### 4. Configure\n\nFor source runs, `GO_ENV=development` is recommended. Without `-c`:\n\n- development mode uses `config.yaml` in the current working directory\n- if missing, it copies from `config/config.yaml.example` in the current working directory\n- non-development mode resolves `config.yaml` next to the executable and copies from sibling `config.yaml.example` when needed\n\nYou can also copy and edit the config file manually.\n\nMinimal example:\n\n```yaml\napp:\n app_env: local\n debug: true\n language: zh_CN\n trusted_proxies:\n - 127.0.0.1\n watch_config: true\n # allow_degraded_startup: false\n\njwt:\n ttl: 7200\n refresh_ttl: 3600\n secret_key: change-me-to-a-random-secret\n\nmysql:\n enable: true\n host: 127.0.0.1\n port: 3306\n database: go_layout\n username: root\n password: your_password\n\nredis:\n enable: true\n host: 127.0.0.1\n port: 6379\n password: \"\"\n database: 0\n\nqueue:\n enable: true\n use_default_redis: true\n namespace: go_layout\n concurrency: 8\n strict_priority: false\n queues:\n critical: 4\n default: 2\n audit: 2\n low: 1\n audit_max_retry: 3\n audit_timeout_seconds: 10\n```\n\nNotes:\n\n- `jwt.secret_key` is required and cannot be empty\n- If you only run the API and do not need async jobs, set `queue.enable` to `false`\n- If `queue.enable=true` but you do not want to reuse `redis.*`, set `queue.use_default_redis` to `false` and fill in `queue.redis.*`\n\n### 5. Start Service\n\n```bash\nGO_ENV=development go run main.go service\n```\n\nTo explicitly set the listen host or port:\n\n```bash\nGO_ENV=development go run main.go service -H 127.0.0.1 -P 9001\n```\n\nIf `queue.enable=true`, start the worker in a separate process as well:\n\n```bash\nGO_ENV=development go run main.go worker\n```\n\n### 6. Verify\n\n```bash\ncurl http://127.0.0.1:9001/ping\ncurl http://127.0.0.1:9001/health/readiness\n```\n\n- `/ping` returns `pong` when the HTTP process is alive.\n- `/health/readiness` returns `ready=true` when required dependencies are ready for the current runtime mode.\n\n## Core Ideas\n\n### Prefer Declarative Routing\n\nAdmin routes are maintained in a single declarative route tree. The current entry is `AdminRouteTree()` in `internal/routers/admin_router.go`. Gin route registration and API metadata initialization are both generated from that tree so route code and permission metadata do not drift apart.\n\n### Database Relations Are The Source Of Truth\n\nThe current permission model treats database relations as the source of truth, while Casbin performs final API authorization checks. The `rebuild-user-permissions` command rebuilds each user's final API permissions from user, department, role, menu, and API relationships stored in the database.\n\n### Hot Reload Is Tiered\n\nThe project supports config hot reload, but not every setting can be applied live. Supported resources are rebuilt when possible. If a rebuild fails, the previous live instance is kept so the service can continue running.\n\n### Request-Locale Driven Texts\n\nThe request pipeline parses `Accept-Language` (currently `zh-CN` / `en-US`) and applies normalized fallback behavior:\n\n- Error messages are resolved by request locale, with fallback to default locale (`zh-CN`).\n- Menu list / user menu tree returns localized `title` only.\n- Menu detail returns `title_i18n` for edit backfill, not `title`.\n- Menu create/update writes `title_i18n`; at least one of `zh-CN` / `en-US` must be non-empty.\n\n## Commands\n\nHelp:\n\n```bash\ngo run main.go -h\ngo run main.go command -h\ngo run main.go service --help\n```\n\nCommon commands:\n\n| Command | Description |\n| --- | --- |\n| `go run main.go version` | Print the current version |\n| `go run main.go service` | Start the API service |\n| `go run main.go service -H 0.0.0.0 -P 9001` | Explicitly set the listen host and port |\n| `go run main.go worker` | Start the Asynq async worker |\n| `go run main.go cron` | Start scheduled jobs |\n| `go run main.go command demo` | Run the demo command |\n| `go run main.go command api-route` | Scan the declarative route tree and rebuild the `api` route table |\n| `go run main.go command rebuild-user-permissions` | Rebuild final user API permissions from database relationships |\n| `go run main.go command init-system` | Roll back and rerun migrations, rebuild API routes, and rebuild user permissions |\n| `go run main.go -c ./config.yaml command task scan-async` | Scan async task registration against the task-definition mirror |\n| `go run main.go -c ./config.yaml command task scan-cron` | Scan cron task definitions against the task-definition mirror |\n| `go run main.go -c ./config.yaml command migrate check` | Validate migration naming and up/down pairing |\n| `go run main.go -c ./config.yaml command migrate up` | Apply all pending migrations |\n| `go run main.go -c ./config.yaml command migrate down 1` | Roll back one migration version |\n\nIf the config file is not in the default location:\n\n```bash\ngo run main.go -c /path/to/config.yaml service\ngo run main.go -c /path/to/config.yaml command init-system\n```\n\nSee [docs/MIGRATE_COMMANDS.en.md](./docs/MIGRATE_COMMANDS.en.md) for full migration command details.\n\n## Configuration\n\n### Config Resolution\n\nConfig lookup order:\n\n1. Explicit `-c` / `--config`\n2. `config.yaml` in the current working directory for development mode\n3. if missing, copy from `config/config.yaml.example` in the current working directory\n4. `config.yaml` next to the executable for non-development mode\n5. if missing, copy from sibling `config.yaml.example`\n\n### Key Settings\n\n| Key | Description |\n| --- | --- |\n| `app.base_path` | Base directory for logs, uploaded files, and other local paths; when not set it follows `GO_ENV` (development=current working directory, otherwise executable directory) |\n| `app.allow_degraded_startup` | Only applies to the `service` command; allows the HTTP service to start when dependency initialization fails, exposing the not-ready state through readiness and route guards |\n| `app.base_url` | URL prefix used to generate public file access URLs |\n| `app.trusted_proxies` | Trusted proxy addresses or CIDRs that affect `ClientIP()` and log IPs |\n| `jwt.secret_key` | Required; do not use weak placeholder values in production |\n| `jwt.ttl` / `jwt.refresh_ttl` | Token expiration and auto-refresh threshold |\n| `mysql` | Database enable flag and connection settings |\n| `redis` | Cache, blacklist, and distributed lock settings |\n| `queue.use_default_redis` | `true` reuses `redis.*`; `false` uses the independent `queue.redis.*` connection |\n| `queue` | Asynq enable flag, queue concurrency, priorities, and audit-log retry settings |\n| `logger` | Log output, rotation, and retention strategy |\n\nIf requests pass through Nginx, Ingress, or a load balancer, keep `app.trusted_proxies` aligned or client IP logging may be inaccurate.\n\n### Worker And Cron\n\n- `service` serves the HTTP API.\n- `worker` consumes Asynq jobs. The current first phase only moves request audit-log persistence to Asynq.\n- When `queue.enable=false`, you do not need to start `worker`; request audit logs are persisted synchronously in the current request flow.\n- `cron` owns scheduled jobs. The demo cron task is controlled by the system config `task.cron_demo_enabled` and is disabled by default after initialization.\n- `reset-system-data` is only registered when `app.enable_reset_system_cron=true` is explicitly configured, and startup logs a high-risk warning.\n- Do not register the same recurring business task in both `cron` and the async worker flow, or it will run twice.\n\nNote: `reset-system-data` currently calls `system.ReinitializeSystemData()`, which rolls back migrations and rebuilds system data. Keep `app.enable_reset_system_cron=false` in production, and only enable it temporarily when you explicitly need to rebuild system data.\n\n### Hot Reload\n\nEnable it with:\n\n```yaml\napp:\n watch_config: true\n```\n\nHot-reload supported:\n\n- `logger.*`\n- `mysql.*`\n- `redis.*`\n- `app.base_url`\n- `app.cors_*`\n- `jwt.ttl`\n- `jwt.refresh_ttl`\n\nDetected but requires restart:\n\n- `app.trusted_proxies`\n- `app.language`\n- `app.allow_degraded_startup`\n- `jwt.secret_key`\n- service listen address and port\n- route structure\n\nNotes:\n\n- `watch_config=true` only enables file watching; it does not mean every setting is safely swappable\n- MySQL, Redis, and Casbin instances are rebuilt from the new config and the old instance is kept on failure\n- JWT secret hot reload is not currently supported; changes are logged and only take effect after restart\n\n## Development\n\n### Add A New Endpoint\n\n1. Write the controller in `internal/controller/`\n2. Write the business logic in `internal/service/`\n3. Define request params in `internal/validator/form/`\n4. Declare the route in `AdminRouteTree()`\n5. Run `go run main.go command api-route` if the API route table needs to be refreshed\n\n### Validation Conventions\n\n- For enum-like fields (for example `status`, `is_auth`, `method`), prefer explicit `oneof` constraints.\n- For ID arrays (for example `role_ids`, `menu_list`, `api_list`), prefer `dive,gt=0` so invalid IDs such as `0` are rejected at validation stage.\n- When adding/changing validation rules, add both positive and negative tests to prevent regressions.\n\n### Test\n\n```bash\ngo test ./...\ngo test ./tests/admin_test\n```\n\nTests prefer the root `config.yaml`. If MySQL or Redis is unavailable in the current environment, the test setup falls back to example config paths for cases that can run without those external services.\n\n## Deployment\n\n### Build\n\n```bash\ngo build -o go-layout main.go\n./go-layout service\n```\n\nIf `-c` is not provided, use `GO_ENV=development` in development and ensure `config/config.yaml.example` exists in the current working directory or `config.yaml` has already been generated. For binary deployment, keep the config file next to the executable.\n\n### Supervisor\n\n```ini\n[program:go-layout]\ncommand=/path/to/go-layout -c /path/to/config.yaml service\ndirectory=/path/to/go-layout\nautostart=true\nautorestart=true\nstartsecs=5\nuser=www-data\nredirect_stderr=true\nstdout_logfile=/path/to/go-layout/supervisord.log\n```\n\n### Nginx\n\n```nginx\nserver {\n listen 80;\n server_name api.example.com;\n\n location / {\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_pass http://127.0.0.1:9001;\n }\n}\n```\n\nIf you are behind a reverse proxy, add the proxy address or CIDR to `app.trusted_proxies`.\n\n## Project Layout\n\n```text\ngin-layout/\n├── cmd/ # CLI entrypoints\n├── config/ # Config structs and example config\n├── data/ # MySQL / Redis and migrations\n├── docs/ # Supplementary docs and resources\n├── internal/\n│ ├── access/ # Access and permission infrastructure\n│ ├── controller/ # Controllers\n│ ├── middleware/ # Middlewares\n│ ├── model/ # Data models\n│ ├── resources/ # Resource transformers\n│ ├── routers/ # Declarative routing\n│ ├── service/ # Business services\n│ └── validator/ # Request validation\n├── pkg/ # Shared utilities\n├── storage/ # File storage\n├── tests/ # Route and integration tests\n└── README.md\n```\n\n## 💝 Support This Project\n\nThanks for using `gin-layout`.\n\nIf this project helps you, you can support its ongoing development and maintenance.\n\n\n ![\"Support](\"https://img.shields.io/badge/BUY_ME_A_COFFEE-SUPPORT_AUTHOR-f08a24?style=for-the-badge&logo=buymeacoffee&logoColor=ffdd00&labelColor=4a4a4a\")
\n\n\n## License\n\nThis project is released under the MIT License. See [LICENSE](LICENSE).\n\n## Contributing\n\nIssues and pull requests are welcome.\n\n## Disclaimer\n\nThis project is provided **“as is”**, without any express or implied warranty. It may contain defects, security vulnerabilities, or implementations that do not fit a specific business scenario. Before using it in production, you should perform your own code review, security hardening, configuration review, permission validation, and data backup. Any issues caused by using, relying on, deploying, modifying, or operating this project are the responsibility of the user.\n"
},
{
"path": "README.md",
"content": "# gin-layout
\n\n\n\n
\n\n\n 基于 Gin 的后台管理系统脚手架\n
\n\n\n 内置 JWT 认证、RBAC 权限、请求/登录日志、文件上传、readiness 探针、参数校验、请求语言国际化、声明式路由和 CLI 初始化命令。\n
\n\n
\n\n\n\n
\n\n## 项目定位\n\n很多后台项目一开始都只是想“先把登录、权限、菜单、上传和日志跑起来”，但真正进入开发后，通常会很快碰到这些重复问题：\n\n- 认证、权限、日志和文件能力分散，初始化成本高\n- 路由、菜单、API 权限关系容易逐步失控\n- 不同项目里同一套后台基础设施被反复重写\n- 配置、命令、迁移和部署流程缺少统一约定\n\n`gin-layout` 的目标很明确：把后台管理场景里高频、重复、工程化要求高的基础能力沉淀成一套可以直接落地的后端骨架。\n\n## 核心特性\n\n| 能力 | 说明 |\n| --- | --- |\n| Auth | 内置 JWT 登录、Token 校验、自动刷新、黑名单 |\n| RBAC | 管理员、角色、部门、菜单、API 权限管理 |\n| Route Metadata | 声明式路由树统一生成 Gin 路由和 API 元数据 |\n| Logs | 内置登录日志、请求日志、统一响应结构 |\n| File Access | 文件上传与公开 / 私有文件访问 |\n| I18n | 基于 `Accept-Language` 返回错误文案与菜单标题（支持 `zh-CN` / `en-US`） |\n| Health Probes | 提供 `/ping` 与 `/health/readiness`，便于存活检测与依赖就绪检查 |\n| Tooling | 提供 CLI 初始化、路由同步、权限重建、迁移配套能力 |\n| Hot Reload | 支持部分配置热更新，失败时保留旧实例继续运行 |\n\n## 相关资源\n\n- 前端项目：[go-admin-ui](https://github.com/wannanbigpig/go-admin-ui)\n- 在线文档：[Apifox](https://wannanbigpig.apifox.cn/)\n- 演示地址：[在线演示](https://x-l-admin.wannanbigpig.com/)\n- 命令与任务文档：[docs/COMMANDS_AND_TASKS.md](./docs/COMMANDS_AND_TASKS.md)\n- 迁移命令详解：[docs/MIGRATE_COMMANDS.md](./docs/MIGRATE_COMMANDS.md)\n\n## 快速开始\n\n### 1. 环境要求\n\n- `Go >= 1.23`\n- `MySQL >= 5.7`\n- `Redis >= 5.0`（可选）\n\n### 2. 安装项目\n\n```bash\ngit clone https://github.com/wannanbigpig/gin-layout.git\ncd gin-layout\ngo mod download\n```\n\n### 3. 执行迁移\n\n推荐使用项目命令：\n\n```bash\ngo run main.go command migrate # 默认等价于 migrate up\ngo run main.go command migrate check\n```\n\n迁移执行完成后会写入一套默认基础数据，其中包含超级管理员账号 `super_admin / 123456`。仅建议用于本地初始化，首次登录后请立即修改密码。\n\n迁移文件创建、时间戳命名规范、`down/goto/force/version` 等详细说明见：[docs/MIGRATE_COMMANDS.md](./docs/MIGRATE_COMMANDS.md)。\n\n### 4. 配置项目\n\n源码运行时建议带上 `GO_ENV=development`。未显式传入 `-c` 时：\n\n- 开发模式会把当前工作目录下的 `config/config.yaml.example` 自动复制为项目根目录 `config.yaml`\n- 非开发模式会在可执行文件同级查找 `config.yaml`，若不存在则尝试从同目录 `config.yaml.example` 复制\n\n也可以手动复制配置文件后再修改。\n\n最小配置示例：\n\n```yaml\napp:\n app_env: local\n debug: true\n language: zh_CN\n trusted_proxies:\n - 127.0.0.1\n watch_config: true\n # allow_degraded_startup: false\n\njwt:\n ttl: 7200\n refresh_ttl: 3600\n secret_key: change-me-to-a-random-secret\n\nmysql:\n enable: true\n host: 127.0.0.1\n port: 3306\n database: go_layout\n username: root\n password: your_password\n\nredis:\n enable: true\n host: 127.0.0.1\n port: 6379\n password: \"\"\n database: 0\n\nqueue:\n enable: true\n use_default_redis: true\n namespace: go_layout\n concurrency: 8\n strict_priority: false\n queues:\n critical: 4\n default: 2\n audit: 2\n low: 1\n audit_max_retry: 3\n audit_timeout_seconds: 10\n```\n\n注意：\n\n- `jwt.secret_key` 为必填项，不能为空\n- 如果只启动 API、不启用异步任务，可以把 `queue.enable` 设为 `false`\n- 如果 `queue.enable=true` 但不想复用 `redis.*`，请把 `queue.use_default_redis` 设为 `false`，并补齐 `queue.redis.*`\n\n### 5. 启动服务\n\n```bash\nGO_ENV=development go run main.go service\n```\n\n需要显式指定监听地址或端口时：\n\n```bash\nGO_ENV=development go run main.go service -H 127.0.0.1 -P 9001\n```\n\n如果启用了 `queue.enable=true`，还需要单独启动 worker：\n\n```bash\nGO_ENV=development go run main.go worker\n```\n\n### 6. 验证服务\n\n```bash\ncurl http://127.0.0.1:9001/ping\ncurl http://127.0.0.1:9001/health/readiness\n```\n\n- `/ping` 返回 `pong`，说明 HTTP 进程已正常启动\n- `/health/readiness` 返回 `ready=true`，说明当前配置下需要的依赖已经就绪\n\n## 设计思路\n\n### 声明式路由优先\n\n后台路由维护在一棵声明式路由树中，目前入口位于 `internal/routers/admin_router.go` 的 `AdminRouteTree()`。Gin 路由注册和 API 元数据初始化都从这棵树生成，避免“代码路由”和“权限路由”长期分叉。\n\n### 数据库关系是权限真相\n\n当前权限模型采用“数据库关系为真相，Casbin 负责最终接口判定”的方式。角色、部门、菜单和 API 的业务关系以数据库为准，`rebuild-user-permissions` 命令会按这些关系重建用户最终 API 权限。\n\n### 配置热更新是分级的\n\n项目支持配置热更新，但不是所有配置都会在运行中立即生效。支持热更新的资源会尝试重建；如果重建失败，会继续保留旧实例运行，避免把服务直接打挂。\n\n### 请求语言驱动文案\n\n项目会在请求链路读取 `Accept-Language`（当前支持 `zh-CN` / `en-US`），并做归一化与降级处理：\n\n- 错误码文案：按请求语言返回；无法识别时降级到默认语言（`zh-CN`）。\n- 菜单列表/用户菜单树：仅返回 `title`，由后端按请求语言解析后返回。\n- 菜单详情：返回 `title_i18n`（用于前端编辑回填），不返回 `title`。\n- 菜单新增/编辑：写接口使用 `title_i18n`，目前支持 `zh-CN` 与 `en-US`，两者至少一种非空。\n\n## 常用命令\n\n查看帮助：\n\n```bash\ngo run main.go -h\ngo run main.go command -h\ngo run main.go service --help\n```\n\n常用命令：\n\n| 命令 | 说明 |\n| --- | --- |\n| `go run main.go version` | 输出当前版本号 |\n| `go run main.go service` | 启动 API 服务 |\n| `go run main.go service -H 0.0.0.0 -P 9001` | 显式指定监听地址与端口 |\n| `go run main.go worker` | 启动 Asynq 异步任务消费进程 |\n| `go run main.go cron` | 启动定时任务 |\n| `go run main.go command demo` | 运行示例命令 |\n| `go run main.go command api-route -y` | 扫描声明式路由树并重建 `api` 路由表 |\n| `go run main.go command rebuild-user-permissions -y` | 按数据库关系重建用户最终 API 权限 |\n| `go run main.go command init-system -y` | 回滚并重新执行迁移、重建 API 路由、重建用户权限 |\n| `go run main.go -c ./config.yaml command task scan-async` | 扫描异步任务注册与任务定义镜像 |\n| `go run main.go -c ./config.yaml command task scan-cron` | 扫描定时任务定义与任务定义镜像 |\n| `go run main.go -c ./config.yaml command migrate check` | 校验迁移文件命名与 up/down 配对 |\n| `go run main.go -c ./config.yaml command migrate up` | 执行全部未应用迁移 |\n| `go run main.go -c ./config.yaml command migrate down 1` | 回滚 1 个迁移版本 |\n\n如果配置文件不在默认位置，可以显式指定：\n\n```bash\ngo run main.go -c /path/to/config.yaml service\ngo run main.go -c /path/to/config.yaml command init-system\n```\n\n迁移命令完整参数见：[docs/MIGRATE_COMMANDS.md](./docs/MIGRATE_COMMANDS.md)。\n\n补充说明：\n\n- `api-route`、`rebuild-user-permissions`、`init-system` 默认会二次确认；自动化场景建议显式加 `-y`\n- `init-system` 会清空并重建系统数据，只适合本地初始化或明确允许重置的环境\n\n## 配置说明\n\n### 配置查找顺序\n\n配置文件查找顺序：\n\n1. 显式传入 `-c` / `--config`\n2. `GO_ENV=development` 时，使用当前工作目录的 `config.yaml`\n3. 若第 2 步缺失，则尝试从当前工作目录的 `config/config.yaml.example` 复制生成\n4. 非开发模式下，使用可执行文件所在目录的 `config.yaml`\n5. 若第 4 步缺失，则尝试从可执行文件同级的 `config.yaml.example` 复制生成\n\n### 主要配置项\n\n| 配置项 | 说明 |\n| --- | --- |\n| `app.base_path` | 日志、上传文件等本地路径的基础目录；未配置时默认按 `GO_ENV` 选择（development=当前工作目录，其他=可执行文件目录） |\n| `app.allow_degraded_startup` | 仅 `service` 命令生效；依赖初始化失败时允许 HTTP 服务先启动，并通过 readiness / 路由守卫暴露未就绪状态 |\n| `app.base_url` | 文件访问 URL 前缀，用于生成公开文件地址 |\n| `app.trusted_proxies` | 受信任代理地址或网段，影响 `ClientIP()` 与日志 IP |\n| `jwt.secret_key` | 必填；生产环境不能使用弱占位值 |\n| `jwt.ttl` / `jwt.refresh_ttl` | Token 过期时间与自动刷新阈值 |\n| `mysql` | 数据库开关与连接信息 |\n| `redis` | 缓存、黑名单和分布式锁配置 |\n| `queue.use_default_redis` | `true` 复用 `redis.*`；`false` 时改用 `queue.redis.*` 独立连接 |\n| `queue` | Asynq 异步任务开关、队列命名空间、并发度、优先级和审计日志重试策略 |\n| `logger` | 日志输出、切割和保留策略 |\n\n如果通过 Nginx、Ingress 或负载均衡转发请求，需要同步配置 `app.trusted_proxies`，否则客户端 IP 可能记录不准确。\n\n### Worker 与 Cron\n\n- `service` 负责提供 HTTP API。\n- `worker` 负责消费 Asynq 异步任务。当前首版只接入请求审计日志异步落库。\n- `queue.enable=false` 时，不需要启动 `worker`，请求审计日志会在当前请求链路同步落库。\n- `cron` 负责定时任务调度；演示定时任务由系统配置 `task.cron_demo_enabled` 控制，初始化默认关闭。\n- `reset-system-data` 需要显式配置 `app.enable_reset_system_cron=true` 才会注册，并在启动时输出高风险告警。\n- 不要把同一个周期任务同时注册到 `cron` 和 `worker` 体系里，否则会重复执行。\n\n注意：`reset-system-data` 当前调用的是 `system.ReinitializeSystemData()`，会回滚迁移并重建系统数据。生产环境建议保持 `app.enable_reset_system_cron=false`，只有在明确需要重建系统数据时才临时开启。\n\n### 热更新\n\n启用方式：\n\n```yaml\napp:\n watch_config: true\n```\n\n支持热更新：\n\n- `logger.*`\n- `mysql.*`\n- `redis.*`\n- `app.base_url`\n- `app.cors_*`\n- `jwt.ttl`\n- `jwt.refresh_ttl`\n\n仅检测并提示“需要重启”：\n\n- `app.trusted_proxies`\n- `app.language`\n- `app.allow_degraded_startup`\n- `jwt.secret_key`\n- 服务监听地址与端口\n- 路由结构\n\n说明：\n\n- `watch_config=true` 只表示启用监听，不代表所有配置都能无损切换\n- MySQL、Redis、Casbin 会按新配置重建实例，失败时保留旧实例\n- JWT 密钥当前不支持热更新，修改后会记录告警并继续使用旧密钥，直到进程重启\n\n## 开发指南\n\n### 新增接口流程\n\n1. 在 `internal/controller/` 编写控制器\n2. 在 `internal/service/` 编写业务逻辑\n3. 在 `internal/validator/form/` 定义请求参数\n4. 在 `AdminRouteTree()` 中声明路由\n5. 需要更新 API 路由表时执行 `go run main.go command api-route`\n\n### 参数校验约定\n\n- 枚举字段（如 `status`、`is_auth`、`method`）建议使用 `oneof` 显式约束。\n- ID 数组字段（如 `role_ids`、`menu_list`、`api_list`）建议统一使用 `dive,gt=0`，避免无效 ID（如 `0`）进入业务层。\n- 新增/修改校验规则时，建议同时补充正反例单测，避免后续回归。\n\n### 测试\n\n```bash\ngo test ./...\ngo test ./tests/admin_test\n```\n\n测试会优先使用项目根目录 `config.yaml`。如果当前环境的 MySQL 或 Redis 不可用，会自动回退到示例配置运行可脱离外部依赖的测试。\n\n## 部署说明\n\n### 构建\n\n```bash\ngo build -o go-layout main.go\n./go-layout service\n```\n\n如果没有显式传 `-c`，请在开发环境使用 `GO_ENV=development`，并确保当前工作目录存在 `config/config.yaml.example`（或已生成 `config.yaml`）；部署二进制时请保证可执行文件同级存在配置文件。\n\n### Supervisor\n\n```ini\n[program:go-layout]\ncommand=/path/to/go-layout -c /path/to/config.yaml service\ndirectory=/path/to/go-layout\nautostart=true\nautorestart=true\nstartsecs=5\nuser=www-data\nredirect_stderr=true\nstdout_logfile=/path/to/go-layout/supervisord.log\n```\n\n### Nginx\n\n```nginx\nserver {\n listen 80;\n server_name api.example.com;\n\n location / {\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_pass http://127.0.0.1:9001;\n }\n}\n```\n\n如果前面有反向代理，请把代理地址或网段加入 `app.trusted_proxies`。\n\n## 目录结构\n\n```text\ngin-layout/\n├── cmd/ # 命令行入口\n├── config/ # 配置结构与示例配置\n├── data/ # MySQL / Redis 与迁移\n├── docs/ # 补充文档与资源\n├── internal/\n│ ├── access/ # 权限基础设施\n│ ├── controller/ # 控制器\n│ ├── middleware/ # 中间件\n│ ├── model/ # 数据模型\n│ ├── resources/ # 资源转换\n│ ├── routers/ # 声明式路由\n│ ├── service/ # 业务逻辑\n│ └── validator/ # 参数验证\n├── pkg/ # 通用工具\n├── storage/ # 文件存储\n├── tests/ # 路由与集成测试\n└── README.md\n```\n\n## 💝 赞助项目\n\n感谢你使用 `gin-layout`。\n\n如果这个项目对你有帮助，欢迎支持项目的持续开发与维护。\n\n\n ![\"支持作者\"](\"https://img.shields.io/badge/BUY_ME_A_COFFEE-%E6%94%AF%E6%8C%81%E4%BD%9C%E8%80%85-f08a24?style=for-the-badge&logo=buymeacoffee&logoColor=ffdd00&labelColor=4a4a4a\")
\n\n\n## 许可证\n\n本项目采用 MIT 许可证，详见 [LICENSE](LICENSE)。\n\n## 贡献\n\n欢迎提交 Issue 和 Pull Request。\n\n## 免责声明\n\n本项目按 **“现状”提供**，不附带任何明示或默示担保。项目可能存在缺陷、安全漏洞或与特定业务场景不匹配的实现；上线前请自行完成代码审查、安全加固、配置审查、权限验收和数据备份。因使用、依赖、部署、改造或运维本项目导致的问题，由使用者自行承担。\n"
},
{
"path": "build.sh",
"content": "#!/bin/bash\n\nset -e # 遇到错误立即退出\n\n# ==================== 配置区域 ====================\nPROJECT_NAME=\"go-layout\"\nBUILD_DIR=\"build\"\nDIST_DIR=\"${BUILD_DIR}/dist\"\nKEEP_VERSIONS=3\n\n# 默认平台（单平台构建时使用）\nDEFAULT_OS=\"linux\"\nDEFAULT_ARCH=\"amd64\"\n\n# 多平台构建列表\nPLATFORMS=(\n \"linux/amd64\"\n \"linux/arm64\"\n \"darwin/amd64\"\n \"darwin/arm64\"\n \"windows/amd64\"\n)\n\n# 颜色输出\nRED='\\033[0;31m'\nGREEN='\\033[0;32m'\nYELLOW='\\033[1;33m'\nBLUE='\\033[0;34m'\nNC='\\033[0m'\n\n# 生成版本号\nVERSION=$(date +\"%Y%m%d_%H%M%S\")\n\n# ==================== 工具函数 ====================\n\nusage() {\n cat << EOF\n用法：$0 [选项]\n\n选项:\n -o, --os 目标操作系统 (linux, darwin, windows)\n -a, --arch 目标架构 (amd64, arm64, 386)\n -p, --platform 指定平台 (格式：os/arch，如 linux/amd64)\n -a, --all 构建所有支持的平台\n -n, --no-compress 不使用 UPX 压缩\n -k, --keep 保留的历史版本数量 (默认：3，0=全部清理)\n -h, --help 显示帮助信息\n\n示例:\n $0 # 使用默认平台 linux/amd64\n $0 -o linux -a arm64 # 构建 linux/arm64\n $0 -p darwin/amd64 # 构建 darwin/amd64\n $0 --all # 构建所有平台\n $0 --all -n # 构建所有平台，不压缩\n $0 --all -k 5 # 构建所有平台，保留 5 个历史版本\n $0 --clean-only -k 0 # 仅清理，删除所有历史版本\nEOF\n exit 0\n}\n\n# 清理 macOS 资源分叉文件\nclean_macos_artifacts() {\n local target_dir=\"$1\"\n if command -v dot_clean &> /dev/null; then\n dot_clean \"${target_dir}\" 2>/dev/null || true\n fi\n find \"${target_dir}\" -type f \\( -name \"._*\" -o -name \".DS_Store\" \\) -delete 2>/dev/null || true\n}\n\n# 获取文件大小（字节）\nget_file_size() {\n stat -f%z \"$1\" 2>/dev/null || stat -c%s \"$1\" 2>/dev/null\n}\n\n# 获取人类可读的文件大小\nget_human_size() {\n local bytes=$1\n if [ \"$bytes\" -lt 1024 ]; then\n echo \"${bytes}B\"\n elif [ \"$bytes\" -lt 1048576 ]; then\n awk \"BEGIN {printf \\\"%.1fK\\\", $bytes/1024}\"\n else\n awk \"BEGIN {printf \\\"%.1fM\\\", $bytes/1048576}\"\n fi\n}\n\n# ==================== 构建流程 ====================\n\nprint_header() {\n local os=\"$1\"\n local arch=\"$2\"\n echo -e \"${BLUE}==========================================\"\n echo \"构建：${os}/${arch}\"\n echo \"版本：${VERSION}\"\n echo \"==========================================${NC}\"\n}\n\n# 编译 Go 二进制文件\nbuild_binary() {\n local os=\"$1\"\n local arch=\"$2\"\n local dist_dir=\"$3\"\n local binary_name=\"$4\"\n\n echo \"正在编译...\"\n\n local binary_file=\"${dist_dir}/${binary_name}\"\n # Windows 平台添加.exe 后缀\n if [ \"$os\" = \"windows\" ]; then\n binary_file=\"${dist_dir}/${binary_name}.exe\"\n fi\n\n if ! CGO_ENABLED=0 GOOS=\"${os}\" GOARCH=\"${arch}\" go build \\\n -ldflags=\"-w -s\" -trimpath -o \"${binary_file}\" .; then\n echo -e \"${RED}编译失败：${os}/${arch}${NC}\"\n return 1\n fi\n\n local size=$(get_file_size \"${binary_file}\")\n echo \"编译完成：$(get_human_size ${size})\"\n return 0\n}\n\n# 使用 UPX 压缩二进制文件\ncompress_with_upx() {\n local os=\"$1\"\n local dist_dir=\"$2\"\n local binary_name=\"$3\"\n local use_compress=\"$4\"\n\n if [ \"$use_compress\" = \"false\" ]; then\n echo \"跳过 UPX 压缩\"\n return 0\n fi\n\n if ! command -v upx &> /dev/null; then\n echo \"提示：安装 UPX 可减小二进制大小 (brew install upx)\"\n return 0\n fi\n\n local binary_file=\"${dist_dir}/${binary_name}\"\n [ \"$os\" = \"windows\" ] && binary_file=\"${dist_dir}/${binary_name}.exe\"\n\n echo \"正在使用 UPX 压缩...\"\n local original_size=$(get_file_size \"${binary_file}\")\n\n if upx --best --lzma \"${binary_file}\" > /dev/null 2>&1; then\n local compressed_size=$(get_file_size \"${binary_file}\")\n local ratio=$(awk \"BEGIN {printf \\\"%.1f\\\", (1 - ${compressed_size}/${original_size}) * 100}\")\n echo -e \"${GREEN}压缩完成：$(get_human_size ${compressed_size}) (压缩率：${ratio}%)${NC}\"\n else\n echo -e \"${YELLOW}UPX 压缩失败，使用原始二进制${NC}\"\n fi\n}\n\n# 复制必要的资源文件\ncopy_resources() {\n local dist_dir=\"$1\"\n\n echo \"复制资源文件...\"\n\n # 配置文件示例\n [ -f \"config/config.yaml.example\" ] && cp \"config/config.yaml.example\" \"${dist_dir}/\"\n [ -f \"AI_DEPLOYMENT.md\" ] && cp \"AI_DEPLOYMENT.md\" \"${dist_dir}/\"\n\n # 数据库迁移文件\n if [ -d \"data/migrations\" ]; then\n mkdir -p \"${dist_dir}/data/migrations\"\n rsync -av --exclude='._*' --exclude='.DS_Store' \\\n data/migrations/ \"${dist_dir}/data/migrations/\" 2>/dev/null \\\n || cp -r data/migrations/* \"${dist_dir}/data/migrations/\" 2>/dev/null || true\n fi\n\n # 权限相关文件\n [ -f \"policy.csv\" ] && cp \"policy.csv\" \"${dist_dir}/\"\n [ -f \"rbac_model.conf\" ] && cp \"rbac_model.conf\" \"${dist_dir}/\"\n}\n\n# 创建压缩包\ncreate_tarball() {\n local os=\"$1\"\n local arch=\"$2\"\n local dist_dir=\"$3\"\n\n local tarball_name=\"${PROJECT_NAME}_${os}_${arch}_${VERSION}.tar.gz\"\n\n # 输出到 stderr（不污染返回值）\n echo \"创建压缩包...\" >&2\n cd \"${BUILD_DIR}\"\n\n # Windows 平台使用 zip 格式\n if [ \"$os\" = \"windows\" ]; then\n tarball_name=\"${PROJECT_NAME}_${os}_${arch}_${VERSION}.zip\"\n if command -v zip &> /dev/null; then\n zip -rq \"${tarball_name}\" dist\n else\n echo -e \"${YELLOW}警告：zip 命令不可用，使用 tar.gz 格式${NC}\" >&2\n tar -czf \"${tarball_name%.zip}.tar.gz\" -C dist .\n tarball_name=\"${tarball_name%.zip}.tar.gz\"\n fi\n else\n tar -czf \"${tarball_name}\" -C dist .\n fi\n\n cd ..\n # 只输出文件名（用于返回值）\n echo \"TARBALL:${tarball_name}\"\n}\n\n# 验证压缩包\nverify_tarball() {\n local tarball=\"$1\"\n\n echo \"验证压缩包...\"\n\n # Windows zip 文件验证\n if [[ \"$tarball\" == *.zip ]]; then\n if command -v unzip &> /dev/null; then\n unzip -l \"${tarball}\" | grep -q \"\\._\" && {\n echo -e \"${RED}错误：压缩包中包含 macOS 资源分叉文件！${NC}\"\n return 1\n }\n fi\n else\n if tar -tzf \"${tarball}\" | grep -q \"\\._\"; then\n echo -e \"${RED}错误：压缩包中包含 macOS 资源分叉文件！${NC}\"\n return 1\n fi\n fi\n\n local file_count\n if [[ \"$tarball\" == *.zip ]]; then\n file_count=$(unzip -l \"${tarball}\" | tail -1 | awk '{print $2}')\n else\n file_count=$(tar -tzf \"${tarball}\" | wc -l | tr -d ' ')\n fi\n echo \"验证通过：共 ${file_count} 个文件\"\n return 0\n}\n\n# 构建单个平台\nbuild_platform() {\n local os=\"$1\"\n local arch=\"$2\"\n local use_compress=\"$3\"\n\n local platform_dist=\"${DIST_DIR}/${os}_${arch}\"\n mkdir -p \"${platform_dist}\"\n\n print_header \"${os}\" \"${arch}\"\n\n if ! build_binary \"${os}\" \"${arch}\" \"${platform_dist}\" \"${PROJECT_NAME}\"; then\n return 1\n fi\n\n compress_with_upx \"${os}\" \"${platform_dist}\" \"${PROJECT_NAME}\" \"${use_compress}\"\n copy_resources \"${platform_dist}\"\n\n echo \"清理 macOS 资源分叉文件...\"\n clean_macos_artifacts \"${platform_dist}\"\n\n local tarball\n tarball=$(create_tarball \"${os}\" \"${arch}\" \"${platform_dist}\")\n tarball=\"${tarball#TARBALL:}\"\n\n # 压缩包已在 BUILD_DIR 目录下，无需移动\n # 清理平台临时目录\n rm -rf \"${platform_dist}\"\n\n if ! verify_tarball \"${BUILD_DIR}/${tarball}\"; then\n return 1\n fi\n\n echo -e \"${GREEN}构建完成：${tarball}${NC}\"\n echo \"\"\n return 0\n}\n\n# 清理旧版本\ncleanup_old_versions() {\n local keep_count=\"${1:-$KEEP_VERSIONS}\"\n\n if [ \"$keep_count\" -eq 0 ]; then\n echo \"清理所有历史版本...\"\n rm -f \"${BUILD_DIR}\"/${PROJECT_NAME}_*_*.tar.gz \"${BUILD_DIR}\"/${PROJECT_NAME}_*_*.zip 2>/dev/null || true\n echo \"已删除所有历史版本\"\n return\n fi\n\n echo \"清理旧版本（保留最新${keep_count}个）...\"\n\n for platform in \"${PLATFORMS[@]}\"; do\n local os=\"${platform%/*}\"\n local arch=\"${platform#*/}\"\n local pattern=\"${PROJECT_NAME}_${os}_${arch}_*\"\n\n local all_versions=($(ls -t \"${BUILD_DIR}\"/${pattern}.tar.gz \"${BUILD_DIR}\"/${pattern}.zip 2>/dev/null || true))\n local count=${#all_versions[@]}\n\n if [ \"${count}\" -le \"${keep_count}\" ]; then\n continue\n fi\n\n local delete_count=$((count - keep_count))\n for ((i=keep_count; i/dev/null || echo \"无构建文件\"\n return\n fi\n\n echo \"==========================================\"\n echo \"Go 项目构建脚本\"\n echo \"版本：${VERSION}\"\n echo \"==========================================\"\n\n # 准备构建目录\n echo \"清理旧的构建文件...\"\n rm -rf \"${DIST_DIR}\"\n mkdir -p \"${DIST_DIR}\"\n\n if [ \"$BUILD_ALL\" = true ]; then\n # 多平台构建\n echo -e \"${BLUE}开始多平台构建...${NC}\"\n\n for platform in \"${PLATFORMS[@]}\"; do\n local os=\"${platform%/*}\"\n local arch=\"${platform#*/}\"\n\n if ! build_platform \"${os}\" \"${arch}\" \"${USE_COMPRESS}\"; then\n echo -e \"${YELLOW}跳过失败的平台：${platform}${NC}\"\n fi\n done\n\n cleanup_old_versions \"${KEEP_COUNT}\"\n\n echo \"==========================================\"\n echo -e \"${GREEN}所有平台构建完成！${NC}\"\n echo \"输出目录：${BUILD_DIR}/\"\n ls -lh \"${BUILD_DIR}\"/*.tar.gz \"${BUILD_DIR}\"/*.zip 2>/dev/null || true\n echo \"==========================================\"\n\n elif [ -n \"$PLATFORM\" ]; then\n # 指定平台构建\n if [[ ! \"$PLATFORM\" =~ ^[a-z0-9]+/[a-z0-9]+$ ]]; then\n echo -e \"${RED}错误：平台格式不正确，应为 os/arch 格式${NC}\"\n exit 1\n fi\n\n local os=\"${PLATFORM%/*}\"\n local arch=\"${PLATFORM#*/}\"\n build_platform \"${os}\" \"${arch}\" \"${USE_COMPRESS}\"\n\n echo \"==========================================\"\n echo -e \"${GREEN}构建完成！${NC}\"\n ls -lh \"${BUILD_DIR}\"/*.tar.gz \"${BUILD_DIR}\"/*.zip 2>/dev/null || true\n echo \"==========================================\"\n\n else\n # 单平台构建（使用默认或命令行指定）\n local os=\"${TARGET_OS:-$DEFAULT_OS}\"\n local arch=\"${TARGET_ARCH:-$DEFAULT_ARCH}\"\n build_platform \"${os}\" \"${arch}\" \"${USE_COMPRESS}\"\n\n echo \"==========================================\"\n echo -e \"${GREEN}构建完成！${NC}\"\n ls -lh \"${BUILD_DIR}\"/*.tar.gz \"${BUILD_DIR}\"/*.zip 2>/dev/null || true\n echo \"==========================================\"\n fi\n}\n\nmain \"$@\"\n"
},
{
"path": "cmd/.gitignore",
"content": "!.gitignore\ngo-layout"
},
{
"path": "cmd/bootstrapx/bootstrap.go",
"content": "package bootstrapx\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"time\"\n\n\t\"github.com/spf13/cobra\"\n\t\"github.com/wannanbigpig/gin-layout/config\"\n\t\"github.com/wannanbigpig/gin-layout/data\"\n\ttaskcron \"github.com/wannanbigpig/gin-layout/internal/cron\"\n\tlog \"github.com/wannanbigpig/gin-layout/internal/pkg/logger\"\n\t\"github.com/wannanbigpig/gin-layout/internal/queue\"\n\t\"github.com/wannanbigpig/gin-layout/internal/service/sys_config\"\n\t\"github.com/wannanbigpig/gin-layout/internal/service/system\"\n\t\"github.com/wannanbigpig/gin-layout/internal/validator\"\n\t\"go.uber.org/zap\"\n)\n\nconst errorLoadingLocation = \"Error loading location: %v\"\n\n// Requirements 描述命令运行前需要初始化的依赖。\ntype Requirements struct {\n\tData bool\n\tValidator bool\n\tQueue bool\n\tAllowDegradedStartup bool\n}\n\nvar (\n\tinitializeDataFunc = InitializeData\n\tinitializeValidatorFunc = InitializeValidator\n\tinitializeQueueFunc = InitializeQueue\n)\n\n// InitializeConfig 初始化配置。\nfunc InitializeConfig(configPath string) error {\n\treturn config.InitConfig(configPath)\n}\n\n// InitializeTimezone 根据配置设置进程时区。\nfunc InitializeTimezone() {\n\tcfg := config.GetConfig()\n\tif cfg.Timezone == nil {\n\t\treturn\n\t}\n\n\tlocation, err := time.LoadLocation(*cfg.Timezone)\n\tif err != nil {\n\t\tif log.Logger != nil {\n\t\t\tlog.Logger.Error(fmt.Sprintf(errorLoadingLocation, err), zap.Error(err))\n\t\t}\n\t\tfmt.Printf(errorLoadingLocation+\"\\n\", err)\n\t\treturn\n\t}\n\ttime.Local = location\n}\n\n// InitializeLogger 初始化全局日志组件。\nfunc InitializeLogger() error {\n\treturn log.InitLogger()\n}\n\n// InitializeData 初始化数据源依赖。\nfunc InitializeData() error {\n\tif err := data.InitData(); err != nil {\n\t\treturn err\n\t}\n\ttaskcron.RegisterHandler(taskcron.HandlerCronResetSystemData, func(ctx context.Context, payload map[string]any) error {\n\t\t_ = ctx\n\t\t_ = payload\n\t\treturn system.ReinitializeSystemData()\n\t})\n\tif err := sys_config.NewSysConfigService().WarmupRuntimeConfigIfAvailable(); err != nil {\n\t\treturn err\n\t}\n\treturn taskcron.SyncBuiltinDefinitionsIfAvailable(config.GetConfig())\n}\n\n// InitializeValidator 初始化参数校验器。\nfunc InitializeValidator() error {\n\treturn validator.InitValidatorTrans(\"zh\")\n}\n\n// WrapCommand 为命令注入统一的初始化逻辑，并保留原有 PreRunE/RunE。\nfunc WrapCommand(cmd *cobra.Command, req Requirements) *cobra.Command {\n\tif cmd == nil {\n\t\treturn cmd\n\t}\n\n\toriginalPreRunE := cmd.PreRunE\n\tcmd.PreRunE = func(c *cobra.Command, args []string) error {\n\t\tif req.Data {\n\t\t\tif err := initializeDataFunc(); err != nil {\n\t\t\t\tif shouldAllowDegradedStartup(req) {\n\t\t\t\t\tlogDependencyInitWarning(c, \"data\", err)\n\t\t\t\t} else {\n\t\t\t\t\treturn err\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tif req.Validator {\n\t\t\tif err := initializeValidatorFunc(); err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\t\t}\n\t\tif req.Queue {\n\t\t\tif err := initializeQueueFunc(); err != nil {\n\t\t\t\tif shouldAllowDegradedStartup(req) {\n\t\t\t\t\tlogDependencyInitWarning(c, \"queue\", err)\n\t\t\t\t} else {\n\t\t\t\t\treturn err\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\tif originalPreRunE != nil {\n\t\t\treturn originalPreRunE(c, args)\n\t\t}\n\t\treturn nil\n\t}\n\n\treturn cmd\n}\n\n// InitializeQueue 初始化队列发布者。\nfunc InitializeQueue() error {\n\tcfg := config.GetConfig()\n\tif !cfg.Queue.Enable {\n\t\treturn nil\n\t}\n\tif err := queue.InitPublisher(cfg); err != nil {\n\t\treturn err\n\t}\n\treturn queue.InitInspector(cfg)\n}\n\nfunc shouldAllowDegradedStartup(req Requirements) bool {\n\tif !req.AllowDegradedStartup {\n\t\treturn false\n\t}\n\tcfg := config.GetConfig()\n\treturn cfg != nil && cfg.AllowDegradedStartup\n}\n\nfunc logDependencyInitWarning(cmd *cobra.Command, dependency string, err error) {\n\tif err == nil {\n\t\treturn\n\t}\n\tcommandPath := \"\"\n\tif cmd != nil {\n\t\tcommandPath = cmd.CommandPath()\n\t}\n\tif log.Logger != nil {\n\t\tlog.Logger.Warn(\"Dependency initialization failed, continue with degraded startup\",\n\t\t\tzap.String(\"command\", commandPath),\n\t\t\tzap.String(\"dependency\", dependency),\n\t\t\tzap.Error(err))\n\t\treturn\n\t}\n\tfmt.Printf(\"warning: dependency initialization failed, continue with degraded startup; command=%s dependency=%s err=%v\\n\", commandPath, dependency, err)\n}\n"
},
{
"path": "cmd/bootstrapx/bootstrap_test.go",
"content": "package bootstrapx\n\nimport (\n\t\"errors\"\n\t\"testing\"\n\n\t\"github.com/spf13/cobra\"\n\t\"go.uber.org/zap\"\n\n\t\"github.com/wannanbigpig/gin-layout/config\"\n\tlog \"github.com/wannanbigpig/gin-layout/internal/pkg/logger\"\n)\n\nfunc TestWrapCommandReturnsDataErrorWhenDegradedStartupDisabled(t *testing.T) {\n\trestoreInit := stubBootstrapInitializers(\n\t\tfunc() error { return errTestDataInit },\n\t\tfunc() error { return nil },\n\t\tfunc() error { return nil },\n\t)\n\tdefer restoreInit()\n\n\trestoreConfig := setAllowDegradedStartup(t, false)\n\tdefer restoreConfig()\n\n\tcmd := WrapCommand(&cobra.Command{Use: \"service\"}, Requirements{\n\t\tData: true,\n\t\tAllowDegradedStartup: true,\n\t})\n\n\terr := cmd.PreRunE(cmd, nil)\n\tif !errors.Is(err, errTestDataInit) {\n\t\tt.Fatalf(\"expected data init error, got %v\", err)\n\t}\n}\n\nfunc TestWrapCommandAllowsDataAndQueueErrorsWhenEnabled(t *testing.T) {\n\tdataCalled := false\n\tvalidatorCalled := false\n\tqueueCalled := false\n\toriginalCalled := false\n\n\trestoreInit := stubBootstrapInitializers(\n\t\tfunc() error {\n\t\t\tdataCalled = true\n\t\t\treturn errTestDataInit\n\t\t},\n\t\tfunc() error {\n\t\t\tvalidatorCalled = true\n\t\t\treturn nil\n\t\t},\n\t\tfunc() error {\n\t\t\tqueueCalled = true\n\t\t\treturn errTestQueueInit\n\t\t},\n\t)\n\tdefer restoreInit()\n\n\trestoreConfig := setAllowDegradedStartup(t, true)\n\tdefer restoreConfig()\n\n\tcmd := WrapCommand(&cobra.Command{\n\t\tUse: \"service\",\n\t\tPreRunE: func(cmd *cobra.Command, args []string) error {\n\t\t\toriginalCalled = true\n\t\t\treturn nil\n\t\t},\n\t}, Requirements{\n\t\tData: true,\n\t\tValidator: true,\n\t\tQueue: true,\n\t\tAllowDegradedStartup: true,\n\t})\n\n\tif err := cmd.PreRunE(cmd, nil); err != nil {\n\t\tt.Fatalf(\"expected degraded startup to continue, got %v\", err)\n\t}\n\tif !dataCalled || !validatorCalled || !queueCalled {\n\t\tt.Fatalf(\"expected all initializers to run, got data=%v validator=%v queue=%v\", dataCalled, validatorCalled, queueCalled)\n\t}\n\tif !originalCalled {\n\t\tt.Fatal(\"expected original PreRunE to be called\")\n\t}\n}\n\nfunc TestWrapCommandKeepsStrictModeForCommandsWithoutOptIn(t *testing.T) {\n\trestoreInit := stubBootstrapInitializers(\n\t\tfunc() error { return errTestDataInit },\n\t\tfunc() error { return nil },\n\t\tfunc() error { return nil },\n\t)\n\tdefer restoreInit()\n\n\trestoreConfig := setAllowDegradedStartup(t, true)\n\tdefer restoreConfig()\n\n\tcmd := WrapCommand(&cobra.Command{Use: \"cron\"}, Requirements{\n\t\tData: true,\n\t})\n\n\terr := cmd.PreRunE(cmd, nil)\n\tif !errors.Is(err, errTestDataInit) {\n\t\tt.Fatalf(\"expected strict command to return data init error, got %v\", err)\n\t}\n}\n\nfunc TestWrapCommandKeepsValidatorStrictEvenWhenDegradedStartupEnabled(t *testing.T) {\n\trestoreInit := stubBootstrapInitializers(\n\t\tfunc() error { return errTestDataInit },\n\t\tfunc() error { return errTestValidatorInit },\n\t\tfunc() error { return nil },\n\t)\n\tdefer restoreInit()\n\n\trestoreConfig := setAllowDegradedStartup(t, true)\n\tdefer restoreConfig()\n\n\tcmd := WrapCommand(&cobra.Command{Use: \"service\"}, Requirements{\n\t\tData: true,\n\t\tValidator: true,\n\t\tAllowDegradedStartup: true,\n\t})\n\n\terr := cmd.PreRunE(cmd, nil)\n\tif !errors.Is(err, errTestValidatorInit) {\n\t\tt.Fatalf(\"expected validator init error, got %v\", err)\n\t}\n}\n\nvar (\n\terrTestDataInit = errors.New(\"data init failed\")\n\terrTestQueueInit = errors.New(\"queue init failed\")\n\terrTestValidatorInit = errors.New(\"validator init failed\")\n)\n\nfunc stubBootstrapInitializers(dataFn, validatorFn, queueFn func() error) func() {\n\tpreviousData := initializeDataFunc\n\tpreviousValidator := initializeValidatorFunc\n\tpreviousQueue := initializeQueueFunc\n\tinitializeDataFunc = dataFn\n\tinitializeValidatorFunc = validatorFn\n\tinitializeQueueFunc = queueFn\n\n\treturn func() {\n\t\tinitializeDataFunc = previousData\n\t\tinitializeValidatorFunc = previousValidator\n\t\tinitializeQueueFunc = previousQueue\n\t}\n}\n\nfunc setAllowDegradedStartup(t *testing.T, enabled bool) func() {\n\tt.Helper()\n\n\toriginalLogger := log.Logger\n\trestoreConfig := config.UpdateConfigForTesting(func(cfg *config.Conf) {\n\t\tcfg.AllowDegradedStartup = enabled\n\t})\n\tlog.Logger = zap.NewNop()\n\n\treturn func() {\n\t\trestoreConfig()\n\t\tlog.Logger = originalLogger\n\t}\n}\n"
},
{
"path": "cmd/command/command.go",
"content": "package command\n\nimport (\n\t\"github.com/spf13/cobra\"\n\n\t\"github.com/wannanbigpig/gin-layout/cmd/bootstrapx\"\n\t\"github.com/wannanbigpig/gin-layout/internal/console/demo\"\n\tinitconsole \"github.com/wannanbigpig/gin-layout/internal/console/init\"\n\tmigrateconsole \"github.com/wannanbigpig/gin-layout/internal/console/migrate\"\n\t\"github.com/wannanbigpig/gin-layout/internal/console/system_init\"\n\ttaskconsole \"github.com/wannanbigpig/gin-layout/internal/console/task\"\n)\n\nvar (\n\tCmd = &cobra.Command{\n\t\tUse: \"command\",\n\t\tShort: \"The control head runs the command\",\n\t\tExample: \"go-layout command demo\",\n\t}\n)\n\nfunc init() {\n\tregisterSubCommands()\n}\n\n// registerSubCommands 注册子命令\nfunc registerSubCommands() {\n\t// 一次性运行脚本\n\tCmd.AddCommand(demo.Cmd)\n\tCmd.AddCommand(bootstrapx.WrapCommand(initconsole.ApiRouteCmd, bootstrapx.Requirements{Data: true})) // 初始化API路由表: go-layout command api-route\n\tCmd.AddCommand(bootstrapx.WrapCommand(initconsole.RebuildUserPermissionsCmd, bootstrapx.Requirements{Data: true})) // 重建用户最终 API 权限: go-layout command rebuild-user-permissions\n\tCmd.AddCommand(bootstrapx.WrapCommand(system_init.InitSystemCmd, bootstrapx.Requirements{Data: true})) // 初始化系统: go-layout command init-system\n\tCmd.AddCommand(migrateconsole.Cmd) // 迁移管理: go-layout command migrate up / down / create / check\n\tCmd.AddCommand(bootstrapx.WrapCommand(taskconsole.Cmd, bootstrapx.Requirements{Data: true})) // 任务扫描: go-layout command task scan-async\n}\n"
},
{
"path": "cmd/completion.go",
"content": "package cmd\n\nimport (\n\t\"fmt\"\n\t\"os\"\n\n\t\"github.com/spf13/cobra\"\n)\n\nvar completionNoDesc bool\n\nvar completionCmd = &cobra.Command{\n\tUse: \"completion [bash|zsh|fish|powershell]\",\n\tShort: \"Generate shell completion scripts\",\n\tLong: `Generate shell completion scripts for go-layout.\n\nLoad examples:\n bash: source <(go-layout completion bash)\n zsh: source <(go-layout completion zsh)\n fish: go-layout completion fish | source\n powershell: go-layout completion powershell | Out-String | Invoke-Expression`,\n\tArgs: cobra.ExactArgs(1),\n\tRunE: func(cmd *cobra.Command, args []string) error {\n\t\tswitch args[0] {\n\t\tcase \"bash\":\n\t\t\treturn rootCmd.GenBashCompletionV2(os.Stdout, !completionNoDesc)\n\t\tcase \"zsh\":\n\t\t\treturn rootCmd.GenZshCompletion(os.Stdout)\n\t\tcase \"fish\":\n\t\t\treturn rootCmd.GenFishCompletion(os.Stdout, !completionNoDesc)\n\t\tcase \"powershell\":\n\t\t\treturn rootCmd.GenPowerShellCompletionWithDesc(os.Stdout)\n\t\tdefault:\n\t\t\treturn fmt.Errorf(\"unsupported shell type %q\", args[0])\n\t\t}\n\t},\n}\n\nfunc init() {\n\tcompletionCmd.Flags().BoolVar(&completionNoDesc, \"no-descriptions\", false, \"Disable completion descriptions where supported\")\n}\n"
},
{
"path": "cmd/cron/cron.go",
"content": "package cron\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"os\"\n\t\"os/signal\"\n\t\"syscall\"\n\n\t\"github.com/robfig/cron/v3\"\n\t\"github.com/spf13/cobra\"\n\t\"go.uber.org/zap\"\n\n\t\"github.com/wannanbigpig/gin-layout/cmd/bootstrapx\"\n\t\"github.com/wannanbigpig/gin-layout/data\"\n\tlog \"github.com/wannanbigpig/gin-layout/internal/pkg/logger\"\n)\n\nvar (\n\tCmd = bootstrapx.WrapCommand(&cobra.Command{\n\t\tUse: \"cron\",\n\t\tShort: \"Starting a scheduled task\",\n\t\tExample: \"go-layout cron\",\n\t\tRunE: func(cmd *cobra.Command, args []string) error {\n\t\t\treturn Start()\n\t\t},\n\t}, bootstrapx.Requirements{Data: true})\n)\n\n// Start 启动定时任务服务\nfunc Start() error {\n\tcrontab, err := newScheduler()\n\tif err != nil {\n\t\treturn err\n\t}\n\tif err := registerTasks(crontab); err != nil {\n\t\tlog.Logger.Error(\"定时任务启动失败\", zap.Error(err))\n\t\treturn fmt.Errorf(\"定时任务启动失败: %w\", err)\n\t}\n\n\t// 启动定时器\n\tcrontab.Start()\n\n\tlog.Logger.Info(\"Cron service started successfully\")\n\n\t// 优雅关闭\n\twaitForShutdown()\n\tstopCtx := crontab.Stop()\n\t<-stopCtx.Done()\n\tif err := data.Shutdown(); err != nil {\n\t\treturn fmt.Errorf(\"shutdown data resources failed: %w\", err)\n\t}\n\tlog.Logger.Info(\"Cron service stopped gracefully\")\n\treturn nil\n}\n\nfunc newScheduler() (*cron.Cron, error) {\n\tlogger := &cronLogger{}\n\tscheduler := cron.New(\n\t\tcron.WithSeconds(),\n\t\tcron.WithChain(cron.Recover(logger)),\n\t)\n\tif scheduler == nil {\n\t\treturn nil, fmt.Errorf(\"创建定时任务调度器失败\")\n\t}\n\treturn scheduler, nil\n}\n\n// waitForShutdown 等待关闭信号，实现优雅关闭\nfunc waitForShutdown() {\n\tctx, cancel := context.WithCancel(context.Background())\n\tdefer cancel()\n\n\tgo handleSignals(cancel)\n\t<-ctx.Done()\n}\n\n// handleSignals 处理系统信号（SIGINT、SIGTERM）\nfunc handleSignals(cancel context.CancelFunc) {\n\tsigChan := make(chan os.Signal, 1)\n\tsignal.Notify(sigChan, syscall.SIGINT, syscall.SIGTERM)\n\n\tsig := <-sigChan\n\tlog.Logger.Warn(\"Received shutdown signal\", zap.String(\"signal\", sig.String()))\n\tcancel()\n}\n\n// cronLogger 定时任务日志记录器\ntype cronLogger struct{}\n\n// Info 记录信息日志\nfunc (cl *cronLogger) Info(msg string, keysAndValues ...interface{}) {\n\tif len(keysAndValues) > 0 {\n\t\tlog.Logger.Info(fmt.Sprintf(msg, keysAndValues...))\n\t} else {\n\t\tlog.Logger.Info(msg)\n\t}\n}\n\n// Error 记录错误日志\nfunc (cl *cronLogger) Error(err error, msg string, keysAndValues ...interface{}) {\n\terrorMsg := err.Error()\n\tif len(keysAndValues) > 0 {\n\t\terrorMsg += \" \" + fmt.Sprintf(msg, keysAndValues...)\n\t} else if msg != \"\" {\n\t\terrorMsg += \" \" + msg\n\t}\n\tlog.Logger.Error(errorMsg, zap.Error(err))\n}\n"
},
{
"path": "cmd/cron/schedule.go",
"content": "package cron\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"strconv\"\n\t\"strings\"\n\t\"time\"\n\n\t\"github.com/robfig/cron/v3\"\n\t\"go.uber.org/zap\"\n\n\t\"github.com/wannanbigpig/gin-layout/internal/model\"\n\tlog \"github.com/wannanbigpig/gin-layout/internal/pkg/logger\"\n\t\"github.com/wannanbigpig/gin-layout/internal/service/taskcenter\"\n)\n\n// Scheduler 提供链式的任务注册方式。\ntype Scheduler struct {\n\tlogger *cronLogger\n\ttasks []*scheduledTask\n}\n\ntype scheduledTask struct {\n\tname string\n\tspec string\n\tspecErr error\n\trun func() error\n\tskipIfRun bool\n}\n\n// TaskBuilder 用于链式声明任务调度规则。\ntype TaskBuilder struct {\n\ttask *scheduledTask\n}\n\nvar cronSpecParser = cron.NewParser(\n\tcron.Second |\n\t\tcron.Minute |\n\t\tcron.Hour |\n\t\tcron.Dom |\n\t\tcron.Month |\n\t\tcron.Dow |\n\t\tcron.Descriptor,\n)\n\nfunc registerTasks(crontab *cron.Cron) error {\n\tlogger := &cronLogger{}\n\tschedule := NewSchedule(logger)\n\tdefineSchedule(schedule)\n\treturn schedule.Register(crontab)\n}\n\n// NewSchedule 创建任务声明器。\nfunc NewSchedule(logger *cronLogger) *Scheduler {\n\treturn &Scheduler{\n\t\tlogger: logger,\n\t\ttasks: make([]*scheduledTask, 0, 4),\n\t}\n}\n\n// Call 注册一个函数任务，默认启用防重入。\nfunc (s *Scheduler) Call(name string, fn func()) *TaskBuilder {\n\ttask := &scheduledTask{\n\t\tname: name,\n\t\trun: func() error { fn(); return nil },\n\t\tskipIfRun: true,\n\t}\n\ts.tasks = append(s.tasks, task)\n\treturn &TaskBuilder{task: task}\n}\n\n// CallE 注册一个返回 error 的函数任务。\nfunc (s *Scheduler) CallE(name string, fn func() error) *TaskBuilder {\n\ttask := &scheduledTask{\n\t\tname: name,\n\t\trun: fn,\n\t\tskipIfRun: true,\n\t}\n\ts.tasks = append(s.tasks, task)\n\treturn &TaskBuilder{task: task}\n}\n\n// Cron 直接使用 cron 表达式。\nfunc (b *TaskBuilder) Cron(spec string) *TaskBuilder {\n\tb.task.spec = spec\n\treturn b\n}\n\n// EveryFiveSeconds 每 5 秒执行一次，适合本地测试任务。\nfunc (b *TaskBuilder) EveryFiveSeconds() *TaskBuilder {\n\treturn b.Cron(\"0/5 * * * * *\")\n}\n\n// DailyAt 每天固定时间执行，支持 HH:MM 或 HH:MM:SS。\nfunc (b *TaskBuilder) DailyAt(value string) *TaskBuilder {\n\tspec, err := dailyAtSpec(value)\n\tif err != nil {\n\t\tb.task.specErr = err\n\t\treturn b\n\t}\n\tb.task.spec = spec\n\treturn b\n}\n\n// WithoutOverlapping 表示任务执行期间跳过重入。\nfunc (b *TaskBuilder) WithoutOverlapping() *TaskBuilder {\n\tb.task.skipIfRun = true\n\treturn b\n}\n\n// AllowOverlap 允许任务重入。\nfunc (b *TaskBuilder) AllowOverlap() *TaskBuilder {\n\tb.task.skipIfRun = false\n\treturn b\n}\n\n// Register 把声明过的任务统一注册到 cron 实例中。\nfunc (s *Scheduler) Register(crontab *cron.Cron) error {\n\tfor _, task := range s.tasks {\n\t\tif err := s.registerTask(crontab, task); err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\treturn nil\n}\n\nfunc (s *Scheduler) registerTask(crontab *cron.Cron, task *scheduledTask) error {\n\tif task.specErr != nil {\n\t\treturn fmt.Errorf(\"定时任务 %s 调度表达式无效: %w\", task.name, task.specErr)\n\t}\n\tif task.spec == \"\" {\n\t\treturn fmt.Errorf(\"定时任务 %s 缺少调度表达式\", task.name)\n\t}\n\n\tchain := cron.NewChain(cron.Recover(s.logger))\n\tif task.skipIfRun {\n\t\tchain = cron.NewChain(\n\t\t\tcron.SkipIfStillRunning(s.logger),\n\t\t\tcron.Recover(s.logger),\n\t\t)\n\t}\n\n\tif _, err := crontab.AddJob(task.spec, chain.Then(s.recordedJob(task))); err != nil {\n\t\treturn fmt.Errorf(\"添加定时任务失败 [%s] (schedule: %s): %w\", task.name, task.spec, err)\n\t}\n\n\tlog.Logger.Info(\"定时任务添加成功\",\n\t\tzap.String(\"name\", task.name),\n\t\tzap.String(\"schedule\", task.spec),\n\t\tzap.Bool(\"skip_if_still_running\", task.skipIfRun),\n\t)\n\treturn nil\n}\n\nfunc (s *Scheduler) recordedJob(task *scheduledTask) cron.Job {\n\treturn cron.FuncJob(func() {\n\t\tif task == nil || task.run == nil {\n\t\t\treturn\n\t\t}\n\n\t\tctx := context.Background()\n\t\ttaskCode := \"cron:\" + task.name\n\t\trun, recordErr := taskcenter.NewRunRecorder().Start(ctx, taskcenter.RunStart{\n\t\t\tTaskCode: taskCode,\n\t\t\tKind: model.TaskKindCron,\n\t\t\tSource: model.TaskSourceCron,\n\t\t\tSourceID: task.name,\n\t\t\tCronSpec: task.spec,\n\t\t})\n\t\tif recordErr != nil {\n\t\t\tlog.Logger.Warn(\"记录定时任务开始失败\",\n\t\t\t\tzap.String(\"name\", task.name),\n\t\t\t\tzap.Error(recordErr))\n\t\t}\n\n\t\terr := task.run()\n\t\tif err != nil {\n\t\t\tlog.Logger.Error(\"定时任务执行失败\",\n\t\t\t\tzap.String(\"name\", task.name),\n\t\t\t\tzap.Error(err))\n\t\t}\n\n\t\tif run == nil {\n\t\t\treturn\n\t\t}\n\t\tfinishInput := taskcenter.RunFinish{Error: err}\n\t\tnextRunAt, nextRunErr := calculateNextRunAt(task.spec, time.Now())\n\t\tif nextRunErr != nil {\n\t\t\tlog.Logger.Warn(\"计算定时任务下次执行时间失败\",\n\t\t\t\tzap.String(\"name\", task.name),\n\t\t\t\tzap.String(\"schedule\", task.spec),\n\t\t\t\tzap.Error(nextRunErr))\n\t\t}\n\t\tfinishInput.NextRunAt = nextRunAt\n\t\tif recordErr := taskcenter.NewRunRecorder().Finish(ctx, run, finishInput); recordErr != nil {\n\t\t\tlog.Logger.Warn(\"记录定时任务结束失败\",\n\t\t\t\tzap.String(\"name\", task.name),\n\t\t\t\tzap.Error(recordErr))\n\t\t}\n\t})\n}\n\nfunc calculateNextRunAt(spec string, base time.Time) (*time.Time, error) {\n\tspec = strings.TrimSpace(spec)\n\tif spec == \"\" {\n\t\treturn nil, nil\n\t}\n\n\tschedule, err := cronSpecParser.Parse(spec)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tnextRunAt := schedule.Next(base)\n\tif nextRunAt.IsZero() {\n\t\treturn nil, nil\n\t}\n\treturn &nextRunAt, nil\n}\n\nfunc dailyAtSpec(value string) (string, error) {\n\tparts := strings.Split(value, \":\")\n\tswitch len(parts) {\n\tcase 2:\n\t\thour, err := parseTimePart(\"hour\", parts[0], 0, 23)\n\t\tif err != nil {\n\t\t\treturn \"\", err\n\t\t}\n\t\tminute, err := parseTimePart(\"minute\", parts[1], 0, 59)\n\t\tif err != nil {\n\t\t\treturn \"\", err\n\t\t}\n\t\treturn fmt.Sprintf(\"0 %d %d * * *\", minute, hour), nil\n\tcase 3:\n\t\thour, err := parseTimePart(\"hour\", parts[0], 0, 23)\n\t\tif err != nil {\n\t\t\treturn \"\", err\n\t\t}\n\t\tminute, err := parseTimePart(\"minute\", parts[1], 0, 59)\n\t\tif err != nil {\n\t\t\treturn \"\", err\n\t\t}\n\t\tsecond, err := parseTimePart(\"second\", parts[2], 0, 59)\n\t\tif err != nil {\n\t\t\treturn \"\", err\n\t\t}\n\t\treturn fmt.Sprintf(\"%d %d %d * * *\", second, minute, hour), nil\n\tdefault:\n\t\treturn \"\", fmt.Errorf(\"invalid daily time format: %s\", value)\n\t}\n}\n\nfunc parseTimePart(name, raw string, min, max int) (int, error) {\n\traw = strings.TrimSpace(raw)\n\tvalue, err := strconv.Atoi(raw)\n\tif err != nil {\n\t\treturn 0, fmt.Errorf(\"invalid %s value %q\", name, raw)\n\t}\n\tif value < min || value > max {\n\t\treturn 0, fmt.Errorf(\"%s value out of range [%d,%d]: %d\", name, min, max, value)\n\t}\n\treturn value, nil\n}\n"
},
{
"path": "cmd/cron/schedule_test.go",
"content": "package cron\n\nimport (\n\t\"strings\"\n\t\"testing\"\n\n\t\"github.com/robfig/cron/v3\"\n)\n\nfunc TestDailyAtSpecWithHHMM(t *testing.T) {\n\tspec, err := dailyAtSpec(\"02:30\")\n\tif err != nil {\n\t\tt.Fatalf(\"expected no error, got %v\", err)\n\t}\n\tif spec != \"0 30 2 * * *\" {\n\t\tt.Fatalf(\"unexpected cron spec: %s\", spec)\n\t}\n}\n\nfunc TestDailyAtSpecWithHHMMSS(t *testing.T) {\n\tspec, err := dailyAtSpec(\"03:04:05\")\n\tif err != nil {\n\t\tt.Fatalf(\"expected no error, got %v\", err)\n\t}\n\tif spec != \"5 4 3 * * *\" {\n\t\tt.Fatalf(\"unexpected cron spec: %s\", spec)\n\t}\n}\n\nfunc TestDailyAtSpecRejectsInvalidInput(t *testing.T) {\n\t_, err := dailyAtSpec(\"invalid\")\n\tif err == nil {\n\t\tt.Fatal(\"expected invalid input to return error\")\n\t}\n}\n\nfunc TestDailyAtSpecRejectsOutOfRange(t *testing.T) {\n\t_, err := dailyAtSpec(\"25:00\")\n\tif err == nil {\n\t\tt.Fatal(\"expected out of range input to return error\")\n\t}\n}\n\nfunc TestSchedulerRegisterReturnsDailyAtError(t *testing.T) {\n\tschedule := NewSchedule(&cronLogger{})\n\tschedule.Call(\"bad-task\", func() {}).DailyAt(\"bad-time\")\n\n\tc := cron.New(cron.WithSeconds())\n\terr := schedule.Register(c)\n\tif err == nil {\n\t\tt.Fatal(\"expected register to return error for invalid daily time\")\n\t}\n\tif !strings.Contains(err.Error(), \"调度表达式无效\") {\n\t\tt.Fatalf(\"unexpected error: %v\", err)\n\t}\n}\n"
},
{
"path": "cmd/cron/task_record_test.go",
"content": "package cron\n\nimport (\n\t\"context\"\n\t\"errors\"\n\t\"testing\"\n\t\"time\"\n\n\t\"github.com/wannanbigpig/gin-layout/internal/model\"\n\t\"github.com/wannanbigpig/gin-layout/internal/service/taskcenter\"\n)\n\nfunc TestRecordedJobRecordsCallEFailure(t *testing.T) {\n\tfake := &fakeCronRunRecorder{}\n\trestore := taskcenter.SetRecorderForTesting(fake)\n\tdefer restore()\n\n\texpectedErr := errors.New(\"cron failed\")\n\tschedule := NewSchedule(&cronLogger{})\n\tbuilder := schedule.CallE(\"demo\", func() error {\n\t\treturn expectedErr\n\t}).EveryFiveSeconds()\n\n\tstartAt := time.Now()\n\tschedule.recordedJob(builder.task).Run()\n\n\tif len(fake.starts) != 1 {\n\t\tt.Fatalf(\"expected 1 start call, got %d\", len(fake.starts))\n\t}\n\tstart := fake.starts[0]\n\tif start.TaskCode != \"cron:demo\" || start.Kind != model.TaskKindCron || start.Source != model.TaskSourceCron {\n\t\tt.Fatalf(\"unexpected start input: %#v\", start)\n\t}\n\tif start.CronSpec != \"0/5 * * * * *\" {\n\t\tt.Fatalf(\"unexpected cron spec: %s\", start.CronSpec)\n\t}\n\tif len(fake.finishes) != 1 {\n\t\tt.Fatalf(\"expected 1 finish call, got %d\", len(fake.finishes))\n\t}\n\tif !errors.Is(fake.finishes[0].Error, expectedErr) {\n\t\tt.Fatalf(\"unexpected finish error: %v\", fake.finishes[0].Error)\n\t}\n\tif fake.finishes[0].NextRunAt == nil {\n\t\tt.Fatal(\"expected finish next run at to be set\")\n\t}\n\tif !fake.finishes[0].NextRunAt.After(startAt) {\n\t\tt.Fatalf(\"expected next run at after start time, got %s\", fake.finishes[0].NextRunAt.Format(time.DateTime))\n\t}\n}\n\nfunc TestCalculateNextRunAtInvalidSpec(t *testing.T) {\n\tnextRunAt, err := calculateNextRunAt(\"bad spec\", time.Now())\n\tif err == nil {\n\t\tt.Fatal(\"expected parse error for invalid cron spec\")\n\t}\n\tif nextRunAt != nil {\n\t\tt.Fatalf(\"expected nil next run at on parse error, got %v\", nextRunAt)\n\t}\n}\n\ntype fakeCronRunRecorder struct {\n\tstarts []taskcenter.RunStart\n\tfinishes []taskcenter.RunFinish\n}\n\nfunc (f *fakeCronRunRecorder) Enqueue(ctx context.Context, input taskcenter.RunStart) (*model.TaskRun, error) {\n\t_ = ctx\n\tf.starts = append(f.starts, input)\n\treturn &model.TaskRun{BaseModel: model.BaseModel{ID: uint(len(f.starts))}, TaskCode: input.TaskCode, Source: input.Source}, nil\n}\n\nfunc (f *fakeCronRunRecorder) Start(ctx context.Context, input taskcenter.RunStart) (*model.TaskRun, error) {\n\t_ = ctx\n\tf.starts = append(f.starts, input)\n\treturn &model.TaskRun{BaseModel: model.BaseModel{ID: uint(len(f.starts))}, TaskCode: input.TaskCode, Source: input.Source}, nil\n}\n\nfunc (f *fakeCronRunRecorder) Finish(ctx context.Context, run *model.TaskRun, input taskcenter.RunFinish) error {\n\t_ = ctx\n\t_ = run\n\tf.finishes = append(f.finishes, input)\n\treturn nil\n}\n"
},
{
"path": "cmd/cron/tasks.go",
"content": "package cron\n\nimport (\n\t\"context\"\n\t\"strings\"\n\n\t\"go.uber.org/zap\"\n\n\t\"github.com/wannanbigpig/gin-layout/config\"\n\ttaskcron \"github.com/wannanbigpig/gin-layout/internal/cron\"\n\t\"github.com/wannanbigpig/gin-layout/internal/model\"\n\tlog \"github.com/wannanbigpig/gin-layout/internal/pkg/logger\"\n)\n\nfunc defineSchedule(schedule *Scheduler) {\n\tcfg := config.GetConfig()\n\tfor _, definition := range taskcron.BuiltinTaskDefinitions(cfg) {\n\t\tif definition.Kind != model.TaskKindCron || definition.Status != model.TaskStatusEnabled {\n\t\t\tcontinue\n\t\t}\n\t\tif strings.TrimSpace(definition.Code) == \"\" || strings.TrimSpace(definition.CronSpec) == \"\" {\n\t\t\tcontinue\n\t\t}\n\n\t\ttaskName := taskNameFromCode(definition.Code)\n\t\thandler := definition.Handler\n\t\tif definition.IsHighRisk == model.TaskHighRisk {\n\t\t\tlog.Logger.Warn(\"高风险定时任务已启用\",\n\t\t\t\tzap.String(\"name\", taskName),\n\t\t\t\tzap.String(\"schedule\", definition.CronSpec),\n\t\t\t)\n\t\t}\n\t\tschedule.CallE(taskName, func() error {\n\t\t\treturn taskcron.ExecuteHandler(context.Background(), handler, nil)\n\t\t}).\n\t\t\tCron(definition.CronSpec).\n\t\t\tWithoutOverlapping()\n\t}\n}\n\nfunc taskNameFromCode(code string) string {\n\tcode = strings.TrimSpace(code)\n\tif strings.HasPrefix(code, \"cron:\") {\n\t\ttrimmed := strings.TrimPrefix(code, \"cron:\")\n\t\tif trimmed != \"\" {\n\t\t\treturn trimmed\n\t\t}\n\t}\n\treturn code\n}\n"
},
{
"path": "cmd/cron/tasks_test.go",
"content": "package cron\n\nimport (\n\t\"testing\"\n\n\t\"github.com/wannanbigpig/gin-layout/config\"\n)\n\nfunc TestDefineScheduleSkipsResetTaskByDefault(t *testing.T) {\n\trestoreConfig := config.UpdateConfigForTesting(func(cfg *config.Conf) {\n\t\tcfg.EnableResetSystemCron = false\n\t})\n\tdefer restoreConfig()\n\n\tschedule := NewSchedule(&cronLogger{})\n\tdefineSchedule(schedule)\n\n\tif hasScheduledTask(schedule, \"reset-system-data\") {\n\t\tt.Fatal(\"expected reset-system-data task to be skipped by default\")\n\t}\n\tif hasScheduledTask(schedule, \"demo\") {\n\t\tt.Fatal(\"expected demo task to be skipped by default\")\n\t}\n}\n\nfunc TestDefineScheduleRegistersResetTaskWhenEnabled(t *testing.T) {\n\trestoreConfig := config.UpdateConfigForTesting(func(cfg *config.Conf) {\n\t\tcfg.EnableResetSystemCron = true\n\t})\n\tdefer restoreConfig()\n\n\tschedule := NewSchedule(&cronLogger{})\n\tdefineSchedule(schedule)\n\n\tif !hasScheduledTask(schedule, \"reset-system-data\") {\n\t\tt.Fatal(\"expected reset-system-data task to be registered when enabled\")\n\t}\n}\n\nfunc hasScheduledTask(schedule *Scheduler, name string) bool {\n\tfor _, task := range schedule.tasks {\n\t\tif task.name == name {\n\t\t\treturn true\n\t\t}\n\t}\n\treturn false\n}\n"
},
{
"path": "cmd/root.go",
"content": "package cmd\n\nimport (\n\t\"fmt\"\n\t\"os\"\n\t\"strings\"\n\n\t\"github.com/spf13/cobra\"\n\t\"go.uber.org/zap\"\n\n\t\"github.com/wannanbigpig/gin-layout/cmd/bootstrapx\"\n\t\"github.com/wannanbigpig/gin-layout/cmd/command\"\n\t\"github.com/wannanbigpig/gin-layout/cmd/cron\"\n\t\"github.com/wannanbigpig/gin-layout/cmd/service\"\n\t\"github.com/wannanbigpig/gin-layout/cmd/version\"\n\t\"github.com/wannanbigpig/gin-layout/cmd/worker\"\n\tlog \"github.com/wannanbigpig/gin-layout/internal/pkg/logger\"\n\t\"github.com/wannanbigpig/gin-layout/internal/runtime\"\n)\n\nconst (\n\twelcomeMessage = \"Welcome to go-layout. Use -h to see more commands\"\n)\n\nvar (\n\trootCmd = &cobra.Command{\n\t\tUse: \"go-layout\",\n\t\tShort: \"go-layout\",\n\t\tSilenceUsage: true,\n\t\tSilenceErrors: true,\n\t\tLong: `Gin framework is used as the core of this project to build a scaffold,\nbased on the project can be quickly completed business development, out of the box 📦`,\n\t\tPersistentPreRunE: func(cmd *cobra.Command, args []string) error {\n\t\t\tif shouldSkipBootstrap(cmd) {\n\t\t\t\treturn nil\n\t\t\t}\n\t\t\tif err := bootstrapx.InitializeConfig(configPath); err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\t\t\tbootstrapx.InitializeTimezone()\n\t\t\tif err := bootstrapx.InitializeLogger(); err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\t\t\treturn nil\n\t\t},\n\t\tRun: func(cmd *cobra.Command, args []string) {\n\t\t\tfmt.Printf(\"%s\\n\", welcomeMessage)\n\t\t},\n\t}\n\tconfigPath string\n)\n\nfunc init() {\n\truntime.RegisterConfigReloadHandlers()\n\tregisterFlags()\n\tregisterCommands()\n}\n\n// registerFlags 注册命令行标志\nfunc registerFlags() {\n\trootCmd.PersistentFlags().StringVarP(&configPath, \"config\", \"c\", \"\", \"The absolute path of the configuration file\")\n}\n\nfunc shouldSkipBootstrap(cmd *cobra.Command) bool {\n\tif cmd == nil {\n\t\treturn false\n\t}\n\tif cmd.Name() == \"help\" {\n\t\treturn true\n\t}\n\tcommandPath := cmd.CommandPath()\n\tswitch commandPath {\n\tcase \"go-layout\", \"go-layout version\", \"go-layout help\":\n\t\treturn true\n\tdefault:\n\t\treturn strings.HasPrefix(commandPath, \"go-layout completion\") ||\n\t\t\tstrings.HasPrefix(commandPath, \"go-layout __complete\")\n\t}\n}\n\n// registerCommands 注册子命令\nfunc registerCommands() {\n\trootCmd.AddCommand(version.Cmd) // 查看版本: go-layout version\n\trootCmd.AddCommand(completionCmd)\n\trootCmd.AddCommand(service.Cmd) // 启动服务: go-layout service\n\trootCmd.AddCommand(command.Cmd) // 运行命令: go-layout command demo / go-layout command init api-route\n\trootCmd.AddCommand(cron.Cmd) // 启动计划任务: go-layout cron\n\trootCmd.AddCommand(worker.Cmd) // 启动异步任务 worker: go-layout worker\n}\n\n// Execute 执行命令\nfunc Execute() {\n\tif err := rootCmd.Execute(); err != nil {\n\t\tif log.Logger != nil {\n\t\t\tlog.Logger.Error(\"Command execution failed\", zap.Error(err))\n\t\t}\n\t\tfmt.Fprintf(os.Stderr, \"Error: %v\\n\", err)\n\t\tos.Exit(1)\n\t}\n}\n"
},
{
"path": "cmd/service/service.go",
"content": "package service\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\t\"net/http\"\n\t\"os\"\n\t\"os/signal\"\n\t\"syscall\"\n\t\"time\"\n\n\t\"github.com/spf13/cobra\"\n\t\"go.uber.org/zap\"\n\n\t\"github.com/wannanbigpig/gin-layout/cmd/bootstrapx\"\n\t\"github.com/wannanbigpig/gin-layout/data\"\n\tlog \"github.com/wannanbigpig/gin-layout/internal/pkg/logger\"\n\t_ \"github.com/wannanbigpig/gin-layout/internal/queue/asynqx\"\n\t\"github.com/wannanbigpig/gin-layout/internal/routers\"\n)\n\nconst (\n\tdefaultHost = \"0.0.0.0\"\n\tdefaultPort = 9001\n\tgracefulShutdownTimout = 10 * time.Second\n)\n\nvar (\n\tCmd = bootstrapx.WrapCommand(&cobra.Command{\n\t\tUse: \"service\",\n\t\tShort: \"Start API service\",\n\t\tExample: \"go-layout service -c config.yml\",\n\t\tRunE: func(cmd *cobra.Command, args []string) error {\n\t\t\treturn run()\n\t\t},\n\t}, bootstrapx.Requirements{Data: true, Validator: true, Queue: true, AllowDegradedStartup: true})\n\thost string\n\tport int\n)\n\nfunc init() {\n\tregisterFlags()\n}\n\n// registerFlags 注册命令行标志\nfunc registerFlags() {\n\tCmd.Flags().StringVarP(&host, \"host\", \"H\", defaultHost, \"监听服务器地址\")\n\tCmd.Flags().IntVarP(&port, \"port\", \"P\", defaultPort, \"监听服务器端口\")\n}\n\n// run 运行服务器\nfunc run() error {\n\tengine, err := routers.SetRouters()\n\tif err != nil {\n\t\treturn fmt.Errorf(\"build router failed: %w\", err)\n\t}\n\taddress := fmt.Sprintf(\"%s:%d\", host, port)\n\tserver := &http.Server{\n\t\tAddr: address,\n\t\tHandler: engine,\n\t}\n\n\terrChan := make(chan error, 1)\n\tgo func() {\n\t\tlog.Logger.Info(\"API service starting\", zap.String(\"address\", address))\n\t\tif err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {\n\t\t\terrChan <- err\n\t\t}\n\t\tclose(errChan)\n\t}()\n\n\treturn waitForShutdown(server, errChan)\n}\n\nfunc waitForShutdown(server *http.Server, errChan <-chan error) error {\n\tsigChan := make(chan os.Signal, 1)\n\tsignal.Notify(sigChan, syscall.SIGINT, syscall.SIGTERM)\n\tdefer signal.Stop(sigChan)\n\n\tselect {\n\tcase err, ok := <-errChan:\n\t\tif ok && err != nil {\n\t\t\treturn err\n\t\t}\n\t\treturn nil\n\tcase sig := <-sigChan:\n\t\tlog.Logger.Warn(\"Received API shutdown signal\", zap.String(\"signal\", sig.String()))\n\t}\n\n\tctx, cancel := context.WithTimeout(context.Background(), gracefulShutdownTimout)\n\tdefer cancel()\n\n\tif err := server.Shutdown(ctx); err != nil {\n\t\treturn fmt.Errorf(\"shutdown http server failed: %w\", err)\n\t}\n\tif err := data.Shutdown(); err != nil {\n\t\treturn fmt.Errorf(\"shutdown data resources failed: %w\", err)\n\t}\n\n\tlog.Logger.Info(\"API service stopped gracefully\")\n\treturn nil\n}\n"
},
{
"path": "cmd/version/version.go",
"content": "package version\n\nimport (\n\t\"fmt\"\n\n\t\"github.com/spf13/cobra\"\n\n\t\"github.com/wannanbigpig/gin-layout/internal/global\"\n)\n\nvar (\n\t// Cmd 版本信息命令\n\tCmd = &cobra.Command{\n\t\tUse: \"version\",\n\t\tShort: \"Get version info\",\n\t\tExample: \"go-layout version\",\n\t\tRunE: func(cmd *cobra.Command, args []string) error {\n\t\t\tfmt.Println(global.Version)\n\t\t\treturn nil\n\t\t},\n\t}\n)\n"
},
{
"path": "cmd/worker/worker.go",
"content": "package worker\n\nimport (\n\t\"fmt\"\n\n\t\"github.com/spf13/cobra\"\n\t\"go.uber.org/zap\"\n\n\t\"github.com/wannanbigpig/gin-layout/cmd/bootstrapx\"\n\t\"github.com/wannanbigpig/gin-layout/config\"\n\t\"github.com/wannanbigpig/gin-layout/data\"\n\ttaskcron \"github.com/wannanbigpig/gin-layout/internal/cron\"\n\t\"github.com/wannanbigpig/gin-layout/internal/jobs\"\n\tlog \"github.com/wannanbigpig/gin-layout/internal/pkg/logger\"\n\t\"github.com/wannanbigpig/gin-layout/internal/queue/asynqx\"\n)\n\nvar Cmd = bootstrapx.WrapCommand(&cobra.Command{\n\tUse: \"worker\",\n\tShort: \"Start async worker\",\n\tExample: \"go-layout worker -c config.yml\",\n\tRunE: func(cmd *cobra.Command, args []string) error {\n\t\treturn run()\n\t},\n}, bootstrapx.Requirements{Data: true})\n\nfunc run() error {\n\tcfg := config.GetConfig()\n\tif cfg == nil {\n\t\treturn fmt.Errorf(\"queue config is not initialized\")\n\t}\n\tif !cfg.Queue.Enable {\n\t\treturn fmt.Errorf(\"queue.enable is false\")\n\t}\n\tif cfg.Queue.UseDefaultRedis {\n\t\tif !cfg.Redis.Enable {\n\t\t\treturn fmt.Errorf(\"queue uses default redis, but redis.enable is false\")\n\t\t}\n\t\tif err := data.GetRedisInitError(); err != nil {\n\t\t\treturn fmt.Errorf(\"redis initialization failed: %w\", err)\n\t\t}\n\t\tif data.RedisClient() == nil {\n\t\t\treturn fmt.Errorf(\"redis client is unavailable\")\n\t\t}\n\t}\n\n\tregistry := jobs.NewRegistry()\n\tcronFallbackHandlers := 0\n\tif cfg.Queue.ConsumeCronFallback {\n\t\tcronFallbackHandlers = taskcron.RegisterQueueFallbackHandlers(registry, cfg)\n\t}\n\n\tserver, mux, err := asynqx.NewServer(cfg, registry)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tlog.Logger.Info(\"Async worker starting\",\n\t\tzap.Int(\"concurrency\", cfg.Queue.Concurrency),\n\t\tzap.Bool(\"strict_priority\", cfg.Queue.StrictPriority),\n\t\tzap.Bool(\"consume_cron_fallback\", cfg.Queue.ConsumeCronFallback),\n\t\tzap.Int(\"cron_fallback_handlers\", cronFallbackHandlers),\n\t\tzap.Any(\"queues\", cfg.Queue.Queues))\n\n\tif err := server.Run(mux); err != nil {\n\t\treturn err\n\t}\n\tif err := data.Shutdown(); err != nil {\n\t\treturn fmt.Errorf(\"shutdown data resources failed: %w\", err)\n\t}\n\n\tlog.Logger.Info(\"Async worker stopped gracefully\")\n\treturn nil\n}\n"
},
{
"path": "config/.gitignore",
"content": "*.yaml\n*.ini"
},
{
"path": "config/autoload/app.go",
"content": "package autoload\n\nimport (\n\t\"github.com/wannanbigpig/gin-layout/pkg/utils\"\n)\n\n// AppConfig 定义应用运行时基础配置。\ntype AppConfig struct {\n\t// AppEnv 应用环境标识，如：local（本地）、dev（开发）、prod（生产）\n\tAppEnv string `mapstructure:\"app_env\"`\n\t// Debug 是否开启调试模式，true 时输出详细调试信息\n\tDebug bool `mapstructure:\"debug\"`\n\t// Language 国际化语言，如：zh_CN（中文）、en_US（英文）\n\tLanguage string `mapstructure:\"language\"`\n\t// WatchConfig 是否开启配置热更新，true 时配置变更自动重载\n\tWatchConfig bool `mapstructure:\"watch_config\"`\n\t// BasePath 应用基础路径，用于拼接文件存储路径。\n\t// 未在配置文件显式设置时，会在配置加载阶段优先回填为当前工作目录。\n\tBasePath string `mapstructure:\"base_path\"`\n\t// BaseURL 文件访问的基础 URL（如：https://example.com），用于拼接文件访问地址\n\tBaseURL string `mapstructure:\"base_url\"`\n\t// Timezone 时区设置，nil 时使用系统默认时区\n\tTimezone *string `mapstructure:\"timezone\"`\n\t// TrustedProxies 受信任代理列表，仅这些代理转发的 X-Forwarded-For/X-Real-IP 会被信任\n\t// 生产环境应配置为负载均衡或反向代理的 IP/网段\n\tTrustedProxies []string `mapstructure:\"trusted_proxies\"`\n\t// CorsOrigins CORS 允许的源列表，如：[\"http://localhost:3000\", \"https://example.com\"]\n\t// 使用 [\"*\"] 表示允许所有源（生产环境慎用）\n\tCorsOrigins []string `mapstructure:\"cors_origins\"`\n\t// CorsMethods 允许的 HTTP 方法，如：[\"GET\", \"POST\", \"PUT\", \"DELETE\"]\n\t// 使用 [\"*\"] 表示允许全部已支持方法，空数组使用默认值\n\tCorsMethods []string `mapstructure:\"cors_methods\"`\n\t// CorsHeaders 允许的请求头，如：[\"Content-Type\", \"Authorization\"]\n\t// 使用 [\"*\"] 表示允许全部请求头\n\tCorsHeaders []string `mapstructure:\"cors_headers\"`\n\t// CorsExposeHeaders 暴露的响应头，如：[\"Content-Length\", \"X-Request-Id\"]\n\t// 使用 [\"*\"] 表示暴露全部响应头\n\tCorsExposeHeaders []string `mapstructure:\"cors_expose_headers\"`\n\t// CorsMaxAge 预检请求（OPTIONS）缓存时间（秒），默认 43200（12 小时）\n\tCorsMaxAge int `mapstructure:\"cors_max_age\"`\n\t// CorsCredentials 是否允许携带凭证（cookies、Authorization 头等），默认 false\n\tCorsCredentials bool `mapstructure:\"cors_credentials\"`\n\t// AllowDegradedStartup 是否允许 service 在依赖初始化失败时降级启动。\n\t// true 时仅 HTTP 服务会继续启动，由 readiness 与路由守卫体现未就绪状态。\n\tAllowDegradedStartup bool `mapstructure:\"allow_degraded_startup\"`\n\t// EnableResetSystemCron 是否启用高风险的系统重建定时任务。\n\t// 默认 false，避免在非预期环境触发系统数据重建。\n\tEnableResetSystemCron bool `mapstructure:\"enable_reset_system_cron\"`\n}\n\nvar App = AppConfig{\n\tAppEnv: \"local\", // 默认本地环境\n\tDebug: true, // 默认开启调试模式\n\tLanguage: \"zh_CN\", // 默认中文\n\tWatchConfig: false, // 默认关闭配置热更新\n\tBasePath: getDefaultPath(),\n\tBaseURL: \"\", // 默认空，需要配置\n\tTimezone: nil, // 默认使用系统时区\n\tTrustedProxies: []string{\"127.0.0.1\"}, // 默认只信任本地\n\tCorsOrigins: []string{}, // 默认空数组，不放行跨域来源；使用 [\"*\"] 表示允许所有源\n\tCorsMethods: []string{}, // 默认空数组，使用默认方法列表；使用 [\"*\"] 表示允许全部已支持方法\n\tCorsHeaders: []string{}, // 默认空数组，按请求头自动放行预检头；使用 [\"*\"] 表示允许全部请求头\n\tCorsExposeHeaders: []string{}, // 默认空数组，默认暴露全部响应头；使用 [\"*\"] 明确表示暴露全部响应头\n\tCorsMaxAge: 43200, // 默认 12 小时（43200 秒）\n\tCorsCredentials: false, // 默认不允许携带凭证\n\tAllowDegradedStartup: false, // 默认关闭降级启动，依赖初始化失败时直接退出\n\tEnableResetSystemCron: false, // 默认关闭高风险系统重建定时任务\n}\n\nfunc getDefaultPath() (path string) {\n\t// 初始化时优先按 GO_ENV 处理：\n\t// - development: 当前工作目录\n\t// - 其他环境: 可执行文件所在目录\n\t// 配置加载阶段会按 app.base_path 是否显式配置进一步修正。\n\tpath, err := utils.GetDefaultPath()\n\tif err != nil || path == \"\" {\n\t\tpath = \".\"\n\t}\n\treturn\n}\n"
},
{
"path": "config/autoload/jwt.go",
"content": "package autoload\n\nimport \"time\"\n\n// JwtConfig 定义 JWT 相关配置。\ntype JwtConfig struct {\n\t// TTL Token 有效期（秒），默认 7200 秒（2 小时）\n\tTTL time.Duration `mapstructure:\"ttl\"`\n\t// RefreshTTL Token 刷新阈值（秒）。\n\t// 默认 0：不主动刷新 Token\n\t// 大于 0 时：当 Token 剩余有效期小于该值时，自动刷新 Token 并在 Response Header 中返回新 Token\n\t// 推荐设置为 TTL/2，例如 TTL=7200 时，RefreshTTL=3600\n\tRefreshTTL time.Duration `mapstructure:\"refresh_ttl\"`\n\t// SecretKey JWT 签名密钥，用于生成和验证 Token\n\t// 启动时会校验非空；生产环境还会拒绝弱占位值和长度不足的密钥\n\t// 建议使用随机密钥，例如：openssl rand -hex 32\n\tSecretKey string `mapstructure:\"secret_key\"`\n}\n\nvar Jwt = JwtConfig{\n\tTTL: 7200, // Token 有效期 2 小时\n\tRefreshTTL: 0, // 0 表示不主动刷新 Token\n\tSecretKey: \"\", // 默认空，启动时必须由配置提供有效密钥\n}\n"
},
{
"path": "config/autoload/logger.go",
"content": "package autoload\n\n// DivisionTime 定义按时间切割日志时的参数。\ntype DivisionTime struct {\n\t// MaxAge 日志文件保留的最大天数，过期会被删除\n\tMaxAge int `mapstructure:\"max_age\"`\n\t// RotationTime 多长时间切割一次日志文件，单位小时（24 表示每天切割）\n\tRotationTime int `mapstructure:\"rotation_time\"`\n}\n\n// DivisionSize 定义按大小切割日志时的参数。\ntype DivisionSize struct {\n\t// MaxSize 日志文件的最大大小（以 MB 为单位），超过该值会触发切割\n\tMaxSize int `mapstructure:\"max_size\"`\n\t// MaxBackups 保留的旧日志文件最大个数，超过会被删除\n\tMaxBackups int `mapstructure:\"max_backups\"`\n\t// MaxAge 旧日志文件保留的最大天数，过期会被删除\n\tMaxAge int `mapstructure:\"max_age\"`\n\t// Compress 是否压缩/归档旧日志文件（gzip 格式）\n\tCompress bool `mapstructure:\"compress\"`\n}\n\n// LoggerConfig 定义日志输出与切割策略。\ntype LoggerConfig struct {\n\t// Output 日志输出方式：file（输出到文件）、stderr（输出到标准错误）\n\tOutput string `mapstructure:\"output\"`\n\t// DefaultDivision 默认切割方式：time（按时间）、size（按大小）\n\tDefaultDivision string `mapstructure:\"default_division\"`\n\t// Filename 日志文件名\n\tFilename string `mapstructure:\"file_name\"`\n\t// DivisionTime 按时间切割的参数配置\n\tDivisionTime DivisionTime `mapstructure:\"division_time\"`\n\t// DivisionSize 按大小切割的参数配置\n\tDivisionSize DivisionSize `mapstructure:\"division_size\"`\n}\n\nvar Logger = LoggerConfig{\n\tOutput: \"file\", // 默认输出到文件\n\tDefaultDivision: \"time\", // 默认按时间切割\n\tFilename: \"gin-layout.sys.log\",\n\tDivisionTime: DivisionTime{\n\t\tMaxAge: 15, // 日志保留 15 天\n\t\tRotationTime: 24, // 每 24 小时切割一次\n\t},\n\tDivisionSize: DivisionSize{\n\t\tMaxSize: 20, // 日志文件最大 20MB\n\t\tMaxBackups: 15, // 最多保留 15 个备份\n\t\tMaxAge: 15, // 日志保留 15 天\n\t\tCompress: false, // 默认不压缩\n\t},\n}\n"
},
{
"path": "config/autoload/mysql.go",
"content": "package autoload\n\nimport \"time\"\n\n// MysqlConfig 定义 MySQL 连接与连接池配置。\ntype MysqlConfig struct {\n\t// Enable 是否启用 MySQL 连接\n\tEnable bool `mapstructure:\"enable\"`\n\t// Host 数据库服务器地址\n\tHost string `mapstructure:\"host\"`\n\t// Username 数据库用户名\n\tUsername string `mapstructure:\"username\"`\n\t// Password 数据库密码\n\tPassword string `mapstructure:\"password\"`\n\t// Port 数据库端口\n\tPort uint16 `mapstructure:\"port\"`\n\t// Database 数据库名称\n\tDatabase string `mapstructure:\"database\"`\n\t// Charset 字符集，推荐 utf8mb4\n\tCharset string `mapstructure:\"charset\"`\n\t// TablePrefix 表名前缀，用于区分不同应用的表\n\tTablePrefix string `mapstructure:\"table_prefix\"`\n\t// MaxIdleConns 最大空闲连接数\n\tMaxIdleConns int `mapstructure:\"max_idle_conns\"`\n\t// MaxOpenConns 最大打开连接数（并发连接数上限）\n\tMaxOpenConns int `mapstructure:\"max_open_conns\"`\n\t// MaxLifetime 连接最大存活时间，超时会被复用前重新创建\n\tMaxLifetime time.Duration `mapstructure:\"max_lifetime\"`\n\t// LogLevel GORM 日志级别：1=silent, 2=error, 3=warn, 4=info\n\tLogLevel int `mapstructure:\"log_level\"`\n\t// PrintSql 是否打印 SQL 到控制台，调试时使用\n\tPrintSql bool `mapstructure:\"print_sql\"`\n}\n\n// Mysql 数据库默认配置。\nvar Mysql = MysqlConfig{\n\tEnable: false, // 默认关闭，需要时开启\n\tHost: \"127.0.0.1\",\n\tUsername: \"root\",\n\tPassword: \"root1234\",\n\tPort: 3306,\n\tDatabase: \"test\",\n\tCharset: \"utf8mb4\",\n\tTablePrefix: \"\",\n\tMaxIdleConns: 10,\n\tMaxOpenConns: 100,\n\tMaxLifetime: time.Hour, // 连接存活 1 小时\n\tLogLevel: 4, // info 级别\n\tPrintSql: false, // 默认不打印 SQL\n}\n"
},
{
"path": "config/autoload/queue.go",
"content": "package autoload\n\n// QueueRedisConfig 队列使用的 Redis 连接配置。\ntype QueueRedisConfig struct {\n\t// Host Redis 服务器地址\n\tHost string `mapstructure:\"host\" yaml:\"host\"`\n\t// Port Redis 服务器端口\n\tPort string `mapstructure:\"port\" yaml:\"port\"`\n\t// Password Redis 密码，空字符串表示无密码\n\tPassword string `mapstructure:\"password\" yaml:\"password\"`\n\t// Database 数据库编号\n\tDatabase int `mapstructure:\"database\" yaml:\"database\"`\n}\n\n// QueueConfig 异步任务队列配置。\ntype QueueConfig struct {\n\t// Enable 是否启用异步队列。false 时同步执行任务（如审计日志直接写库）\n\tEnable bool `mapstructure:\"enable\" yaml:\"enable\"`\n\t// UseDefaultRedis 是否复用全局 redis 配置。\n\t// true: 使用 redis.* 作为队列连接（默认）\n\t// false: 使用 queue.redis.* 作为队列独立连接\n\tUseDefaultRedis bool `mapstructure:\"use_default_redis\" yaml:\"use_default_redis\"`\n\t// Redis 队列独立 Redis 配置，仅当 UseDefaultRedis=false 时生效\n\tRedis QueueRedisConfig `mapstructure:\"redis\" yaml:\"redis\"`\n\t// Namespace 队列命名空间前缀，用于隔离不同应用的队列\n\tNamespace string `mapstructure:\"namespace\" yaml:\"namespace\"`\n\t// Concurrency Worker Server 的最大并发协程数（全局上限）\n\t// 建议值：开发环境 2-4，小流量生产 8-16，中等流量 16-32\n\t// 注意：并发过高会增加数据库压力，审计日志类任务建议 8-16\n\tConcurrency int `mapstructure:\"concurrency\" yaml:\"concurrency\"`\n\t// StrictPriority 是否严格优先级模式。\n\t// true: 必须处理完高优先级队列的所有任务后，才处理低优先级队列\n\t// false: 按权重比例调度，高优先级队列的任务被调度的概率更大（推荐）\n\tStrictPriority bool `mapstructure:\"strict_priority\" yaml:\"strict_priority\"`\n\t// ConsumeCronFallback 是否允许 worker 消费历史误入 Asynq 的非高风险 cron 任务。\n\t// 仅用于清理旧队列残留，不影响 cron 调度开关。\n\tConsumeCronFallback bool `mapstructure:\"consume_cron_fallback\" yaml:\"consume_cron_fallback\"`\n\t// Queues 各队列的权重配置，key 为队列名，value 为权重值\n\t// 新增队列必须在此配置，否则 Worker 不会消费该队列的任务！\n\t// 权重决定任务被调度的概率，不是分配的协程数量！\n\t// 所有队列共享 Concurrency 个协程，权重越高越容易被优先调度\n\t// 调度概率 = 该队列权重 / 所有队列权重之和\n\t// 示例（总权重=4+2+2+1=9）：\n\t// critical: 权重 4 → 4/9≈44% 概率被调度（支付回调、短信发送）\n\t// default: 权重 2 → 2/9≈22% 概率被调度（普通异步任务）\n\t// audit: 权重 2 → 2/9≈22% 概率被调度（请求日志、登录日志）\n\t// low: 权重 1 → 1/9≈11% 概率被调度（批量通知、数据导出）\n\tQueues map[string]int `mapstructure:\"queues\" yaml:\"queues\"`\n\t// AuditMaxRetry 审计日志队列的最大重试次数\n\tAuditMaxRetry int `mapstructure:\"audit_max_retry\" yaml:\"audit_max_retry\"`\n\t// AuditTimeoutSeconds 审计日志任务的超时时间（秒）\n\tAuditTimeoutSeconds int `mapstructure:\"audit_timeout_seconds\" yaml:\"audit_timeout_seconds\"`\n}\n\n// Queue 队列默认配置。\nvar Queue = QueueConfig{\n\tEnable: false, // 默认关闭队列，同步执行\n\tUseDefaultRedis: true, // 默认复用全局 redis 配置\n\tRedis: QueueRedisConfig{\n\t\tHost: \"127.0.0.1\",\n\t\tPort: \"6379\",\n\t\tPassword: \"\",\n\t\tDatabase: 0,\n\t},\n\tNamespace: \"go_layout\",\n\tConcurrency: 8, // 整个 worker 最多同时处理 8 个任务（全局上限）\n\tStrictPriority: false, // 按权重比例调度，非严格优先级\n\t// 默认不让 worker 消费 cron 类型任务；需要清理历史残留时再显式开启。\n\tConsumeCronFallback: false,\n\tQueues: map[string]int{\n\t\t// 权重值表示调度概率，不是协程数量！\n\t\t// 所有队列共享 8 个协程，权重越高越容易被优先调度\n\t\t// 总权重 = 4+2+2+1 = 9\n\t\t// critical 被选中的概率 ≈ 4/9 ≈ 44%\n\t\t\"critical\": 4, // 权重 4，约 44% 概率被调度（如支付回调）\n\t\t\"default\": 2, // 权重 2，约 22% 概率被调度（普通任务）\n\t\t\"audit\": 2, // 权重 2，约 22% 概率被调度（审计日志）\n\t\t\"low\": 1, // 权重 1，约 11% 概率被调度（批量通知）\n\t},\n\tAuditMaxRetry: 3, // 审计日志失败最多重试 3 次\n\tAuditTimeoutSeconds: 10, // 审计日志任务超时 10 秒\n}\n"
},
{
"path": "config/autoload/redis.go",
"content": "package autoload\n\nimport \"time\"\n\n// RedisConfig 定义 Redis 连接配置。\ntype RedisConfig struct {\n\t// Enable 是否启用 Redis 连接\n\tEnable bool `mapstructure:\"enable\"`\n\t// Host Redis 服务器地址\n\tHost string `mapstructure:\"host\"`\n\t// Port Redis 服务器端口\n\tPort string `mapstructure:\"port\"`\n\t// Password Redis 密码，空字符串表示无密码\n\tPassword string `mapstructure:\"password\"`\n\t// Database 数据库编号，默认 0\n\tDatabase int `mapstructure:\"database\"`\n\t// PoolSize 连接池大小（最大连接数）\n\tPoolSize int `mapstructure:\"pool_size\"`\n\t// MinIdleConns 最小空闲连接数\n\tMinIdleConns int `mapstructure:\"min_idle_conns\"`\n\t// ConnMaxIdleTime 连接最大空闲时间，超时会被回收\n\tConnMaxIdle time.Duration `mapstructure:\"conn_max_idle_time\"`\n\t// ConnMaxLifetime 连接最大存活时间，超时会被重新创建\n\tConnMaxLifetime time.Duration `mapstructure:\"conn_max_lifetime\"`\n\t// ReadTimeout 读取超时时间\n\tReadTimeout time.Duration `mapstructure:\"read_timeout\"`\n\t// WriteTimeout 写入超时时间\n\tWriteTimeout time.Duration `mapstructure:\"write_timeout\"`\n}\n\n// Redis 默认配置。\nvar Redis = RedisConfig{\n\tEnable: false, // 默认关闭，需要时开启\n\tHost: \"127.0.0.1\",\n\tPassword: \"\",\n\tPort: \"6379\",\n\tDatabase: 0,\n\tPoolSize: 10,\n\tMinIdleConns: 5,\n\tConnMaxIdle: 5 * time.Minute, // 空闲 5 分钟回收\n\tConnMaxLifetime: 30 * time.Minute, // 连接存活 30 分钟\n\tReadTimeout: 3 * time.Second, // 读取超时 3 秒\n\tWriteTimeout: 3 * time.Second, // 写入超时 3 秒\n}\n"
},
{
"path": "config/config.go",
"content": "package config\n\nimport (\n\t\"sort\"\n\t\"sync\"\n\t\"sync/atomic\"\n\n\t\"github.com/spf13/viper\"\n\t\"github.com/wannanbigpig/gin-layout/config/autoload\"\n)\n\n// Conf 配置项主结构体\ntype Conf struct {\n\tautoload.AppConfig `mapstructure:\"app\"`\n\tMysql autoload.MysqlConfig `mapstructure:\"mysql\"`\n\tRedis autoload.RedisConfig `mapstructure:\"redis\"`\n\tLogger autoload.LoggerConfig `mapstructure:\"logger\"`\n\tJwt autoload.JwtConfig `mapstructure:\"jwt\"`\n\tQueue autoload.QueueConfig `mapstructure:\"queue\"`\n}\n\nvar (\n\tConfig = &Conf{\n\t\tAppConfig: cloneAppConfig(autoload.App),\n\t\tMysql: autoload.Mysql,\n\t\tRedis: autoload.Redis,\n\t\tLogger: autoload.Logger,\n\t\tJwt: autoload.Jwt,\n\t\tQueue: cloneQueueConfig(autoload.Queue),\n\t}\n\tonce sync.Once\n\tinitErr error\n\tV *viper.Viper\n\tconfigValue atomic.Value\n\n\treloadHandlersMu sync.RWMutex\n\treloadHandlers []ConfigReloadHandler\n)\n\n// ConfigReloadHandler 在配置热更新时被调用。\ntype ConfigReloadHandler struct {\n\tName string\n\tPriority int\n\tHandle func(oldConfig, newConfig *Conf, diff ConfigDiff) error\n}\n\n// ConfigDiff 描述配置变更摘要。\ntype ConfigDiff struct {\n\tLoggerChanged bool\n\tMysqlChanged bool\n\tRedisChanged bool\n\tJWTChanged bool\n\tJWTSecretChanged bool\n\tBaseURLChanged bool\n\tCORSChanged bool\n\tTrustedProxiesChanged bool\n\tLightAppChanged bool\n\tRestartRequiredFields []string\n\tChangedFields []string\n}\n\n// GetConfig 返回当前生效的配置快照。\nfunc GetConfig() *Conf {\n\tif cfg, ok := configValue.Load().(*Conf); ok && cfg != nil {\n\t\treturn cfg\n\t}\n\treturn Config\n}\n\n// RegisterConfigReloadHandler 注册配置热更新回调。\nfunc RegisterConfigReloadHandler(handler ConfigReloadHandler) {\n\tif handler.Name == \"\" {\n\t\treturn\n\t}\n\n\treloadHandlersMu.Lock()\n\tdefer reloadHandlersMu.Unlock()\n\n\tfor i := range reloadHandlers {\n\t\tif reloadHandlers[i].Name == handler.Name {\n\t\t\treloadHandlers[i] = handler\n\t\t\tsortConfigReloadHandlersLocked()\n\t\t\treturn\n\t\t}\n\t}\n\n\treloadHandlers = append(reloadHandlers, handler)\n\tsortConfigReloadHandlersLocked()\n}\n\nfunc sortConfigReloadHandlersLocked() {\n\tsort.SliceStable(reloadHandlers, func(i, j int) bool {\n\t\tif reloadHandlers[i].Priority == reloadHandlers[j].Priority {\n\t\t\treturn reloadHandlers[i].Name < reloadHandlers[j].Name\n\t\t}\n\t\treturn reloadHandlers[i].Priority < reloadHandlers[j].Priority\n\t})\n}\n"
},
{
"path": "config/config.yaml.example",
"content": "# 该文件为配置示例文件，请复制该文件改名为 config.yaml, 不要直接修改该文件，修改无意义\napp:\n app_env: local\n debug: true\n language: zh_CN\n# allow_degraded_startup: false # service 启动时依赖初始化失败是否继续启动；仅建议在需要“先起服务再排障”场景开启\n# enable_reset_system_cron: false # 高风险：是否启用 reset-system-data 定时任务；默认关闭，避免误重建系统数据\n# watch_config: false\n# base_path: \"\"\n# base_url: \"https://example.com\" # 文件访问的基础URL，用于拼接本地文件访问地址\n# trusted_proxies: # 受信任代理列表，仅这些代理转发的 X-Forwarded-For / X-Real-IP 会被信任\n# - \"127.0.0.1\"\n# # 生产环境可按实际代理网段配置，例如：\n# # - \"10.0.0.0/8\"\n# # - \"172.16.0.0/12\"\n# # - \"192.168.0.0/16\"\n# # CORS 跨域配置\n# cors_origins: # CORS允许的源列表，使用 [\"*\"] 表示允许所有源\n# - \"http://localhost:3000\"\n# - \"http://localhost:8080\"\n# - \"https://example.com\"\n# # 支持通配符匹配，例如：\n# - \"https://*.wannanbigpig.com\" # 匹配所有 wannanbigpig.com 的子域名（如 https://x-l-admin.wannanbigpig.com）\n# # 或者明确指定：\n# - \"https://x-l-admin.wannanbigpig.com\"\n# cors_methods: # 允许的HTTP方法，使用 [\"*\"] 表示允许全部已支持方法，空数组使用默认值\n# - \"GET\"\n# - \"POST\"\n# - \"PUT\"\n# - \"PATCH\"\n# - \"DELETE\"\n# - \"HEAD\"\n# - \"OPTIONS\"\n# cors_headers: # 允许的请求头，使用 [\"*\"] 表示允许所有请求头\n# - \"Content-Type\"\n# - \"Authorization\"\n# - \"X-Requested-With\"\n# cors_expose_headers: # 暴露的响应头，使用 [\"*\"] 表示暴露所有响应头\n# - \"Content-Length\"\n# - \"X-Request-Id\"\n# cors_max_age: 43200 # 预检请求缓存时间（秒），默认 43200（12小时）\n# cors_credentials: false # 是否允许携带凭证（cookies等），默认 false\njwt:\n ttl: 7200\n refresh_ttl: 3600\n secret_key: # 请替换为随机密钥；启动时会校验非空，生产环境还会拒绝弱占位值和短密钥\nmysql:\n enable: false\n host: 127.0.0.1\n port: 3306\n database: test\n username: root\n password: root1234\n charset: utf8mb4\n table_prefix: \"\"\n max_idle_conns: 10\n max_open_conns: 100\n max_lifetime: 3600s\nredis:\n enable: false\n host: 127.0.0.1\n port: 6379\n password:\n database: 0\nqueue:\n enable: false\n use_default_redis: true # true=复用 redis.*；false=使用 queue.redis.* 独立连接\n redis:\n host: 127.0.0.1\n port: 6379\n password:\n database: 0\n namespace: go_layout\n concurrency: 8\n strict_priority: false\n consume_cron_fallback: false # true=worker 兜底消费历史误入 Asynq 的非高风险 cron 任务\n queues:\n critical: 4\n default: 2\n audit: 2\n low: 1\n audit_max_retry: 3\n audit_timeout_seconds: 10\nlogger:\n # 日志输出默认为文件，stderr 可选\n output: file\n default_division: time\n file_name: gin-layout.sys.log\n division_time:\n max_age: 15\n rotation_time: 24\n division_size:\n max_size: 20\n max_backups: 15\n max_age: 15\n compress: false\n"
},
{
"path": "config/config_clone.go",
"content": "package config\n\nimport (\n\t\"fmt\"\n\t\"io\"\n\t\"os\"\n\n\t\"github.com/wannanbigpig/gin-layout/config/autoload\"\n)\n\nfunc setActiveConfig(cfg *Conf) {\n\tConfig = cfg\n\tconfigValue.Store(cfg)\n}\n\nfunc cloneDefaultConfig() *Conf {\n\treturn &Conf{\n\t\tAppConfig: cloneAppConfig(autoload.App),\n\t\tMysql: autoload.Mysql,\n\t\tRedis: autoload.Redis,\n\t\tLogger: autoload.Logger,\n\t\tJwt: autoload.Jwt,\n\t\tQueue: cloneQueueConfig(autoload.Queue),\n\t}\n}\n\nfunc cloneAppConfig(src autoload.AppConfig) autoload.AppConfig {\n\tcloned := src\n\tcloned.TrustedProxies = cloneStringSlice(src.TrustedProxies)\n\tcloned.CorsOrigins = cloneStringSlice(src.CorsOrigins)\n\tcloned.CorsMethods = cloneStringSlice(src.CorsMethods)\n\tcloned.CorsHeaders = cloneStringSlice(src.CorsHeaders)\n\tcloned.CorsExposeHeaders = cloneStringSlice(src.CorsExposeHeaders)\n\tif src.Timezone != nil {\n\t\ttz := *src.Timezone\n\t\tcloned.Timezone = &tz\n\t}\n\treturn cloned\n}\n\nfunc cloneQueueConfig(src autoload.QueueConfig) autoload.QueueConfig {\n\tcloned := src\n\tif src.Queues != nil {\n\t\tcloned.Queues = make(map[string]int, len(src.Queues))\n\t\tfor key, value := range src.Queues {\n\t\t\tcloned.Queues[key] = value\n\t\t}\n\t}\n\treturn cloned\n}\n\nfunc cloneStringSlice(src []string) []string {\n\tif src == nil {\n\t\treturn nil\n\t}\n\treturn append([]string(nil), src...)\n}\n\n// copyConf 复制配置示例文件\nfunc copyConf(exampleConfig, config string) error {\n\tfileInfo, err := os.Stat(config)\n\tif err == nil {\n\t\tif !fileInfo.IsDir() {\n\t\t\treturn nil\n\t\t}\n\t\treturn fmt.Errorf(\"配置文件目录存在同名的文件夹，无法创建配置文件\")\n\t}\n\tif !os.IsNotExist(err) {\n\t\treturn fmt.Errorf(\"初始化失败: %w\", err)\n\t}\n\n\tsource, err := os.Open(exampleConfig)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"创建配置文件失败，配置示例文件不存在: %w\", err)\n\t}\n\tdefer func(source *os.File) {\n\t\t_ = source.Close()\n\t}(source)\n\n\tdst, err := os.Create(config)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"生成配置文件失败: %w\", err)\n\t}\n\tdefer func(dst *os.File) {\n\t\t_ = dst.Close()\n\t}(dst)\n\n\tif _, err := io.Copy(dst, source); err != nil {\n\t\treturn fmt.Errorf(\"写入配置文件失败: %w\", err)\n\t}\n\treturn nil\n}\n"
},
{
"path": "config/config_load.go",
"content": "package config\n\nimport (\n\t\"fmt\"\n\t\"os\"\n\t\"path/filepath\"\n\t\"strings\"\n\n\t\"github.com/fsnotify/fsnotify\"\n\t\"github.com/spf13/viper\"\n\n\t\"github.com/wannanbigpig/gin-layout/pkg/utils\"\n)\n\n// InitConfig 初始化配置系统并加载首个生效快照。\nfunc InitConfig(configPath string) error {\n\tonce.Do(func() {\n\t\tvar loaded *Conf\n\t\tloaded, initErr = load(configPath)\n\t\tif initErr != nil {\n\t\t\treturn\n\t\t}\n\t\tinitErr = validateJWTSecretKey(loaded)\n\t\tif initErr != nil {\n\t\t\treturn\n\t\t}\n\t\tsetActiveConfig(loaded)\n\t})\n\treturn initErr\n}\n\nfunc checkJwtSecretKey() error {\n\treturn validateJWTSecretKey(GetConfig())\n}\n\nfunc validateJWTSecretKey(cfg *Conf) error {\n\tif cfg == nil {\n\t\treturn fmt.Errorf(\"config is nil\")\n\t}\n\tsecret := strings.TrimSpace(cfg.Jwt.SecretKey)\n\tif secret == \"\" {\n\t\treturn fmt.Errorf(\"jwt.secret_key is empty, please set a non-empty secret key\")\n\t}\n\n\tisProd := strings.EqualFold(cfg.AppEnv, \"prod\") || strings.EqualFold(cfg.AppEnv, \"production\")\n\tif !isProd {\n\t\treturn nil\n\t}\n\n\tweakSecrets := map[string]struct{}{\n\t\t\"\": {},\n\t\t\"your-secret-key-here\": {},\n\t\t\"default-secret-key\": {},\n\t\t\"change-me\": {},\n\t\t\"changeme\": {},\n\t\t\"secret\": {},\n\t\t\"123456\": {},\n\t}\n\tif _, ok := weakSecrets[strings.ToLower(secret)]; ok {\n\t\treturn fmt.Errorf(\"jwt.secret_key uses a weak placeholder value in production\")\n\t}\n\tif len(secret) < 16 {\n\t\treturn fmt.Errorf(\"jwt.secret_key is too short in production, require at least 16 characters\")\n\t}\n\n\treturn nil\n}\n\nfunc load(configPath string) (*Conf, error) {\n\tfilePath, err := resolveConfigPath(configPath)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tV = viper.New()\n\tV.SetConfigFile(filePath)\n\tif err := V.ReadInConfig(); err != nil {\n\t\tif _, ok := err.(viper.ConfigFileNotFoundError); ok {\n\t\t\treturn nil, fmt.Errorf(\"未找到配置: %w\", err)\n\t\t}\n\t\treturn nil, fmt.Errorf(\"读取配置出错: %w\", err)\n\t}\n\n\tloaded := cloneDefaultConfig()\n\tif err := V.Unmarshal(loaded); err != nil {\n\t\treturn nil, fmt.Errorf(\"映射配置出错: %w\", err)\n\t}\n\n\tresolveEnvVars(loaded)\n\tensureBasePathDefault(loaded, V.IsSet(\"app.base_path\"))\n\n\tensureCorsDefaults(loaded)\n\tregisterConfigWatcherIfNeeded(loaded)\n\treturn loaded, nil\n}\n\nfunc resolveConfigPath(configPath string) (string, error) {\n\tif configPath != \"\" {\n\t\treturn configPath, nil\n\t}\n\n\texampleConfig, targetConfig, err := resolveDefaultConfigFiles()\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\tif err := copyConf(exampleConfig, targetConfig); err != nil {\n\t\treturn \"\", err\n\t}\n\treturn targetConfig, nil\n}\n\nfunc resolveDefaultConfigFiles() (string, string, error) {\n\tif os.Getenv(\"GO_ENV\") == \"development\" {\n\t\treturn resolveDevelopmentConfigFiles()\n\t}\n\n\trunDirectory, err := utils.GetCurrentPath()\n\tif err != nil {\n\t\treturn \"\", \"\", fmt.Errorf(\"获取执行文件目录失败: %w\", err)\n\t}\n\treturn filepath.Join(runDirectory, \"config.yaml.example\"), filepath.Join(runDirectory, \"config.yaml\"), nil\n}\n\nfunc resolveDevelopmentConfigFiles() (string, string, error) {\n\tworkDir, err := os.Getwd()\n\tif err != nil {\n\t\treturn \"\", \"\", fmt.Errorf(\"获取工作目录失败: %w\", err)\n\t}\n\n\texampleConfig := filepath.Join(workDir, \"config\", \"config.yaml.example\")\n\tif !fileExists(exampleConfig) {\n\t\texampleConfig = filepath.Join(workDir, \"config.yaml.example\")\n\t}\n\treturn exampleConfig, filepath.Join(workDir, \"config.yaml\"), nil\n}\n\nfunc fileExists(path string) bool {\n\tif strings.TrimSpace(path) == \"\" {\n\t\treturn false\n\t}\n\tinfo, err := os.Stat(path)\n\tif err != nil {\n\t\treturn false\n\t}\n\treturn !info.IsDir()\n}\n\nfunc ensureBasePathDefault(cfg *Conf, basePathConfigured bool) {\n\tif cfg == nil {\n\t\treturn\n\t}\n\tif basePathConfigured && strings.TrimSpace(cfg.BasePath) != \"\" {\n\t\treturn\n\t}\n\n\tif os.Getenv(\"GO_ENV\") == \"development\" {\n\t\tworkDir, err := os.Getwd()\n\t\tif err == nil && strings.TrimSpace(workDir) != \"\" {\n\t\t\tcfg.BasePath = workDir\n\t\t\treturn\n\t\t}\n\t}\n\n\trunDir, err := utils.GetCurrentPath()\n\tif err == nil && strings.TrimSpace(runDir) != \"\" {\n\t\tcfg.BasePath = runDir\n\t\treturn\n\t}\n\n\tworkDir, err := os.Getwd()\n\tif err == nil && strings.TrimSpace(workDir) != \"\" {\n\t\tcfg.BasePath = workDir\n\t\treturn\n\t}\n\tcfg.BasePath = strings.TrimSpace(cfg.BasePath)\n\tif cfg.BasePath == \"\" {\n\t\tcfg.BasePath = \".\"\n\t}\n}\n\nfunc registerConfigWatcherIfNeeded(cfg *Conf) {\n\tif !cfg.WatchConfig {\n\t\treturn\n\t}\n\n\tV.WatchConfig()\n\tV.OnConfigChange(func(in fsnotify.Event) {\n\t\tinitErr = reloadConfigFromWatcher()\n\t})\n}\n\nfunc ensureCorsDefaults(cfg *Conf) {\n\tif cfg.CorsOrigins == nil {\n\t\tcfg.CorsOrigins = []string{}\n\t}\n\tif cfg.CorsMethods == nil {\n\t\tcfg.CorsMethods = []string{}\n\t}\n\tif cfg.CorsHeaders == nil {\n\t\tcfg.CorsHeaders = []string{}\n\t}\n\tif cfg.CorsExposeHeaders == nil {\n\t\tcfg.CorsExposeHeaders = []string{}\n\t}\n\tif cfg.TrustedProxies == nil {\n\t\tcfg.TrustedProxies = []string{\"127.0.0.1\"}\n\t}\n\tif cfg.CorsMaxAge == 0 {\n\t\tcfg.CorsMaxAge = 43200\n\t}\n}\n\nfunc reloadConfigFromWatcher() error {\n\tif err := V.ReadInConfig(); err != nil {\n\t\treturn fmt.Errorf(\"重新读取配置出错: %w\", err)\n\t}\n\n\tnext := cloneDefaultConfig()\n\tif err := V.Unmarshal(next); err != nil {\n\t\treturn fmt.Errorf(\"重新映射配置出错: %w\", err)\n\t}\n\tresolveEnvVars(next)\n\tensureBasePathDefault(next, V.IsSet(\"app.base_path\"))\n\tensureCorsDefaults(next)\n\tif err := validateJWTSecretKey(next); err != nil {\n\t\treturn fmt.Errorf(\"JWT 配置校验失败: %w\", err)\n\t}\n\n\tcurrent := GetConfig()\n\tdiff := BuildConfigDiff(current, next)\n\tapplied := BuildAppliedConfig(current, next, diff)\n\n\treloadHandlersMu.RLock()\n\thandlers := append([]ConfigReloadHandler(nil), reloadHandlers...)\n\treloadHandlersMu.RUnlock()\n\n\tfor _, handler := range handlers {\n\t\tif handler.Handle == nil {\n\t\t\tcontinue\n\t\t}\n\t\tif err := handler.Handle(current, applied, diff); err != nil {\n\t\t\treturn fmt.Errorf(\"配置热更新失败[%s]: %w\", handler.Name, err)\n\t\t}\n\t}\n\n\tsetActiveConfig(applied)\n\treturn nil\n}\n\nfunc resolveEnvVars(cfg *Conf) {\n\tcfg.Mysql.Username = resolveEnvVar(cfg.Mysql.Username)\n\tcfg.Mysql.Password = resolveEnvVar(cfg.Mysql.Password)\n\tcfg.Mysql.Host = resolveEnvVar(cfg.Mysql.Host)\n\tcfg.Redis.Password = resolveEnvVar(cfg.Redis.Password)\n\tcfg.Redis.Host = resolveEnvVar(cfg.Redis.Host)\n\tcfg.Queue.Redis.Password = resolveEnvVar(cfg.Queue.Redis.Password)\n\tcfg.Queue.Redis.Host = resolveEnvVar(cfg.Queue.Redis.Host)\n\tcfg.Jwt.SecretKey = resolveEnvVar(cfg.Jwt.SecretKey)\n}\n\nfunc resolveEnvVar(val string) string {\n\tif !strings.HasPrefix(val, \"${\") || !strings.HasSuffix(val, \"}\") {\n\t\treturn val\n\t}\n\tenvKey := val[2 : len(val)-1]\n\tif envVal := os.Getenv(envKey); envVal != \"\" {\n\t\treturn envVal\n\t}\n\treturn val\n}\n"
},
{
"path": "config/config_load_test.go",
"content": "package config\n\nimport (\n\t\"os\"\n\t\"path/filepath\"\n\t\"testing\"\n)\n\nfunc assertSamePath(t *testing.T, expected string, actual string) {\n\tt.Helper()\n\texpectedResolved, err := filepath.EvalSymlinks(expected)\n\tif err != nil {\n\t\texpectedResolved = filepath.Clean(expected)\n\t}\n\tactualResolved, err := filepath.EvalSymlinks(actual)\n\tif err != nil {\n\t\tactualResolved = filepath.Clean(actual)\n\t}\n\tif expectedResolved != actualResolved {\n\t\tt.Fatalf(\"expected %s, got %s\", expectedResolved, actualResolved)\n\t}\n}\n\nfunc TestResolveConfigPathPrefersWorkingDirectoryConfig(t *testing.T) {\n\tt.Setenv(\"GO_ENV\", \"development\")\n\n\tworkDir := t.TempDir()\n\tconfigPath := filepath.Join(workDir, \"config.yaml\")\n\tif err := os.WriteFile(configPath, []byte(\"app:\\n port: 8080\\n\"), 0o644); err != nil {\n\t\tt.Fatalf(\"write config file failed: %v\", err)\n\t}\n\n\toriginWD, err := os.Getwd()\n\tif err != nil {\n\t\tt.Fatalf(\"getwd failed: %v\", err)\n\t}\n\tif err := os.Chdir(workDir); err != nil {\n\t\tt.Fatalf(\"chdir failed: %v\", err)\n\t}\n\tt.Cleanup(func() {\n\t\t_ = os.Chdir(originWD)\n\t})\n\n\tresolved, err := resolveConfigPath(\"\")\n\tif err != nil {\n\t\tt.Fatalf(\"resolveConfigPath failed: %v\", err)\n\t}\n\tassertSamePath(t, configPath, resolved)\n}\n\nfunc TestResolveDefaultConfigFilesUsesWorkingDirectoryExample(t *testing.T) {\n\tt.Setenv(\"GO_ENV\", \"development\")\n\n\tworkDir := t.TempDir()\n\tconfigDir := filepath.Join(workDir, \"config\")\n\tif err := os.MkdirAll(configDir, 0o755); err != nil {\n\t\tt.Fatalf(\"mkdir config dir failed: %v\", err)\n\t}\n\n\texamplePath := filepath.Join(configDir, \"config.yaml.example\")\n\tif err := os.WriteFile(examplePath, []byte(\"app:\\n port: 8080\\n\"), 0o644); err != nil {\n\t\tt.Fatalf(\"write example file failed: %v\", err)\n\t}\n\n\toriginWD, err := os.Getwd()\n\tif err != nil {\n\t\tt.Fatalf(\"getwd failed: %v\", err)\n\t}\n\tif err := os.Chdir(workDir); err != nil {\n\t\tt.Fatalf(\"chdir failed: %v\", err)\n\t}\n\tt.Cleanup(func() {\n\t\t_ = os.Chdir(originWD)\n\t})\n\n\tgotExample, gotTarget, err := resolveDefaultConfigFiles()\n\tif err != nil {\n\t\tt.Fatalf(\"resolveDefaultConfigFiles failed: %v\", err)\n\t}\n\tassertSamePath(t, examplePath, gotExample)\n\texpectedTarget := filepath.Join(filepath.Dir(filepath.Dir(gotExample)), \"config.yaml\")\n\tif gotTarget != expectedTarget {\n\t\tt.Fatalf(\"expected target %s, got %s\", expectedTarget, gotTarget)\n\t}\n}\n\nfunc TestEnsureBasePathDefaultUsesWorkingDirectoryWhenNotConfigured(t *testing.T) {\n\tt.Setenv(\"GO_ENV\", \"development\")\n\n\tworkDir := t.TempDir()\n\toriginWD, err := os.Getwd()\n\tif err != nil {\n\t\tt.Fatalf(\"getwd failed: %v\", err)\n\t}\n\tif err := os.Chdir(workDir); err != nil {\n\t\tt.Fatalf(\"chdir failed: %v\", err)\n\t}\n\tt.Cleanup(func() {\n\t\t_ = os.Chdir(originWD)\n\t})\n\n\tcfg := cloneDefaultConfig()\n\tcfg.BasePath = \"/tmp/legacy-base-path\"\n\tensureBasePathDefault(cfg, false)\n\tassertSamePath(t, workDir, cfg.BasePath)\n}\n\nfunc TestEnsureBasePathDefaultKeepsExplicitConfiguredValue(t *testing.T) {\n\tcfg := cloneDefaultConfig()\n\tcfg.BasePath = \"/tmp/custom-base-path\"\n\tensureBasePathDefault(cfg, true)\n\tif cfg.BasePath != \"/tmp/custom-base-path\" {\n\t\tt.Fatalf(\"expected explicit base_path to be kept, got %s\", cfg.BasePath)\n\t}\n}\n\nfunc TestValidateJWTSecretKeyRejectsNilConfig(t *testing.T) {\n\tif err := validateJWTSecretKey(nil); err == nil {\n\t\tt.Fatal(\"expected nil config to return error\")\n\t}\n}\n\nfunc TestCheckJwtSecretKeyRejectsEmptySecret(t *testing.T) {\n\toriginal := GetConfig()\n\ttestCfg := cloneDefaultConfig()\n\ttestCfg.Jwt.SecretKey = \"\"\n\tsetActiveConfig(testCfg)\n\tt.Cleanup(func() { setActiveConfig(original) })\n\n\tif err := checkJwtSecretKey(); err == nil {\n\t\tt.Fatal(\"expected empty jwt secret key to return error\")\n\t}\n}\n\nfunc TestCheckJwtSecretKeyRejectsWeakProdSecret(t *testing.T) {\n\toriginal := GetConfig()\n\ttestCfg := cloneDefaultConfig()\n\ttestCfg.AppEnv = \"prod\"\n\ttestCfg.Jwt.SecretKey = \"default-secret-key\"\n\tsetActiveConfig(testCfg)\n\tt.Cleanup(func() { setActiveConfig(original) })\n\n\tif err := checkJwtSecretKey(); err == nil {\n\t\tt.Fatal(\"expected weak prod jwt secret key to return error\")\n\t}\n}\n\nfunc TestCheckJwtSecretKeyAllowsLocalWeakSecret(t *testing.T) {\n\toriginal := GetConfig()\n\ttestCfg := cloneDefaultConfig()\n\ttestCfg.AppEnv = \"local\"\n\ttestCfg.Jwt.SecretKey = \"default-secret-key\"\n\tsetActiveConfig(testCfg)\n\tt.Cleanup(func() { setActiveConfig(original) })\n\n\tif err := checkJwtSecretKey(); err != nil {\n\t\tt.Fatalf(\"expected local weak secret key to pass, got %v\", err)\n\t}\n}\n"
},
{
"path": "config/config_test.go",
"content": "package config\n\nimport \"testing\"\n\nfunc resetConfigReloadHandlersForTest(t *testing.T) {\n\tt.Helper()\n\treloadHandlersMu.Lock()\n\tdefer reloadHandlersMu.Unlock()\n\treloadHandlers = nil\n}\n\nfunc TestRegisterConfigReloadHandlerDeduplicatesByName(t *testing.T) {\n\tresetConfigReloadHandlersForTest(t)\n\n\tRegisterConfigReloadHandler(ConfigReloadHandler{Name: \"data\", Priority: 20})\n\tRegisterConfigReloadHandler(ConfigReloadHandler{Name: \"data\", Priority: 10})\n\n\treloadHandlersMu.RLock()\n\tdefer reloadHandlersMu.RUnlock()\n\n\tif len(reloadHandlers) != 1 {\n\t\tt.Fatalf(\"expected 1 handler, got %d\", len(reloadHandlers))\n\t}\n\tif reloadHandlers[0].Priority != 10 {\n\t\tt.Fatalf(\"expected overwritten priority 10, got %d\", reloadHandlers[0].Priority)\n\t}\n}\n\nfunc TestRegisterConfigReloadHandlerKeepsStablePriorityOrder(t *testing.T) {\n\tresetConfigReloadHandlersForTest(t)\n\n\tRegisterConfigReloadHandler(ConfigReloadHandler{Name: \"warnings\", Priority: 100})\n\tRegisterConfigReloadHandler(ConfigReloadHandler{Name: \"logger\", Priority: 10})\n\tRegisterConfigReloadHandler(ConfigReloadHandler{Name: \"data\", Priority: 20})\n\n\treloadHandlersMu.RLock()\n\tdefer reloadHandlersMu.RUnlock()\n\n\tif len(reloadHandlers) != 3 {\n\t\tt.Fatalf(\"expected 3 handlers, got %d\", len(reloadHandlers))\n\t}\n\n\tgot := []string{reloadHandlers[0].Name, reloadHandlers[1].Name, reloadHandlers[2].Name}\n\twant := []string{\"logger\", \"data\", \"warnings\"}\n\tfor i := range want {\n\t\tif got[i] != want[i] {\n\t\t\tt.Fatalf(\"unexpected order: got %v want %v\", got, want)\n\t\t}\n\t}\n}\n\nfunc TestRegisterConfigReloadHandlerIgnoresEmptyName(t *testing.T) {\n\tresetConfigReloadHandlersForTest(t)\n\n\tRegisterConfigReloadHandler(ConfigReloadHandler{Priority: 1})\n\n\treloadHandlersMu.RLock()\n\tdefer reloadHandlersMu.RUnlock()\n\n\tif len(reloadHandlers) != 0 {\n\t\tt.Fatalf(\"expected empty-name handler to be ignored, got %d handlers\", len(reloadHandlers))\n\t}\n}\n"
},
{
"path": "config/provider.go",
"content": "package config\n\n// GetConfigFrom 通过指定 provider 获取配置，并保证返回值非 nil。\nfunc GetConfigFrom(provider func() *Conf) *Conf {\n\tif provider == nil {\n\t\treturn &Conf{}\n\t}\n\n\tcfg := provider()\n\tif cfg == nil {\n\t\treturn &Conf{}\n\t}\n\treturn cfg\n}\n"
},
{
"path": "config/runtime.go",
"content": "package config\n\nimport \"reflect\"\n\n// BuildConfigDiff 生成配置差异摘要。\nfunc BuildConfigDiff(oldConfig, newConfig *Conf) ConfigDiff {\n\tdiff := ConfigDiff{}\n\tif oldConfig == nil || newConfig == nil {\n\t\treturn diff\n\t}\n\n\tdiff.LoggerChanged = !reflect.DeepEqual(oldConfig.Logger, newConfig.Logger)\n\tdiff.MysqlChanged = !reflect.DeepEqual(oldConfig.Mysql, newConfig.Mysql)\n\tdiff.RedisChanged = !reflect.DeepEqual(oldConfig.Redis, newConfig.Redis)\n\tdiff.JWTChanged = oldConfig.Jwt.TTL != newConfig.Jwt.TTL || oldConfig.Jwt.RefreshTTL != newConfig.Jwt.RefreshTTL\n\tdiff.JWTSecretChanged = oldConfig.Jwt.SecretKey != newConfig.Jwt.SecretKey\n\tdiff.BaseURLChanged = oldConfig.BaseURL != newConfig.BaseURL\n\tdiff.CORSChanged = !reflect.DeepEqual(oldConfig.CorsOrigins, newConfig.CorsOrigins) ||\n\t\t!reflect.DeepEqual(oldConfig.CorsMethods, newConfig.CorsMethods) ||\n\t\t!reflect.DeepEqual(oldConfig.CorsHeaders, newConfig.CorsHeaders) ||\n\t\t!reflect.DeepEqual(oldConfig.CorsExposeHeaders, newConfig.CorsExposeHeaders) ||\n\t\toldConfig.CorsMaxAge != newConfig.CorsMaxAge ||\n\t\toldConfig.CorsCredentials != newConfig.CorsCredentials\n\tdiff.TrustedProxiesChanged = !reflect.DeepEqual(oldConfig.TrustedProxies, newConfig.TrustedProxies)\n\tdiff.LightAppChanged = oldConfig.BasePath != newConfig.BasePath ||\n\t\toldConfig.AppEnv != newConfig.AppEnv ||\n\t\toldConfig.Debug != newConfig.Debug ||\n\t\toldConfig.WatchConfig != newConfig.WatchConfig ||\n\t\toldConfig.Language != newConfig.Language ||\n\t\toldConfig.AllowDegradedStartup != newConfig.AllowDegradedStartup\n\n\tif diff.LoggerChanged {\n\t\tdiff.ChangedFields = append(diff.ChangedFields, \"logger.*\")\n\t}\n\tif diff.MysqlChanged {\n\t\tdiff.ChangedFields = append(diff.ChangedFields, \"mysql.*\")\n\t}\n\tif diff.RedisChanged {\n\t\tdiff.ChangedFields = append(diff.ChangedFields, \"redis.*\")\n\t}\n\tif diff.JWTChanged {\n\t\tdiff.ChangedFields = append(diff.ChangedFields, \"jwt.ttl\", \"jwt.refresh_ttl\")\n\t}\n\tif diff.JWTSecretChanged {\n\t\tdiff.ChangedFields = append(diff.ChangedFields, \"jwt.secret_key\")\n\t\tdiff.RestartRequiredFields = append(diff.RestartRequiredFields, \"jwt.secret_key\")\n\t}\n\tif diff.BaseURLChanged {\n\t\tdiff.ChangedFields = append(diff.ChangedFields, \"app.base_url\")\n\t}\n\tif diff.CORSChanged {\n\t\tdiff.ChangedFields = append(diff.ChangedFields, \"app.cors_*\")\n\t}\n\tif diff.TrustedProxiesChanged {\n\t\tdiff.ChangedFields = append(diff.ChangedFields, \"app.trusted_proxies\")\n\t\tdiff.RestartRequiredFields = append(diff.RestartRequiredFields, \"app.trusted_proxies\")\n\t}\n\tif oldConfig.Language != newConfig.Language {\n\t\tdiff.RestartRequiredFields = append(diff.RestartRequiredFields, \"app.language\")\n\t}\n\tif oldConfig.AllowDegradedStartup != newConfig.AllowDegradedStartup {\n\t\tdiff.ChangedFields = append(diff.ChangedFields, \"app.allow_degraded_startup\")\n\t\tdiff.RestartRequiredFields = append(diff.RestartRequiredFields, \"app.allow_degraded_startup\")\n\t}\n\n\treturn diff\n}\n\n// BuildAppliedConfig 返回当前进程应采用的配置快照。\n// 对不支持热更新的字段保持旧值，避免配置快照与实际运行状态不一致。\nfunc BuildAppliedConfig(oldConfig, newConfig *Conf, diff ConfigDiff) *Conf {\n\tif oldConfig == nil {\n\t\treturn newConfig\n\t}\n\tapplied := *newConfig\n\tapplied.AppConfig = cloneAppConfig(newConfig.AppConfig)\n\tapplied.Queue = cloneQueueConfig(newConfig.Queue)\n\n\tif diff.JWTSecretChanged {\n\t\tapplied.Jwt.SecretKey = oldConfig.Jwt.SecretKey\n\t}\n\tif diff.TrustedProxiesChanged {\n\t\tapplied.TrustedProxies = cloneStringSlice(oldConfig.TrustedProxies)\n\t}\n\tif oldConfig.Language != newConfig.Language {\n\t\tapplied.Language = oldConfig.Language\n\t}\n\tif oldConfig.AllowDegradedStartup != newConfig.AllowDegradedStartup {\n\t\tapplied.AllowDegradedStartup = oldConfig.AllowDegradedStartup\n\t}\n\n\treturn &applied\n}\n"
},
{
"path": "config/runtime_test.go",
"content": "package config\n\nimport (\n\t\"testing\"\n\n\t. \"github.com/wannanbigpig/gin-layout/config/autoload\"\n)\n\nfunc TestBuildConfigDiff(t *testing.T) {\n\toldCfg := &Conf{\n\t\tAppConfig: App,\n\t\tMysql: Mysql,\n\t\tRedis: Redis,\n\t\tLogger: Logger,\n\t\tJwt: Jwt,\n\t}\n\tnewCfg := &Conf{\n\t\tAppConfig: App,\n\t\tMysql: Mysql,\n\t\tRedis: Redis,\n\t\tLogger: Logger,\n\t\tJwt: Jwt,\n\t}\n\n\tnewCfg.Logger.Output = \"stderr\"\n\tnewCfg.Redis.Enable = true\n\tnewCfg.BaseURL = \"https://example.com\"\n\tnewCfg.CorsOrigins = []string{\"https://ui.example.com\"}\n\tnewCfg.TrustedProxies = []string{\"10.0.0.0/8\"}\n\tnewCfg.Jwt.TTL = 999\n\tnewCfg.Jwt.SecretKey = \"new-secret\"\n\tnewCfg.Language = \"en\"\n\n\tdiff := BuildConfigDiff(oldCfg, newCfg)\n\tif !diff.LoggerChanged {\n\t\tt.Fatalf(\"expected logger change\")\n\t}\n\tif !diff.RedisChanged {\n\t\tt.Fatalf(\"expected redis change\")\n\t}\n\tif !diff.JWTChanged {\n\t\tt.Fatalf(\"expected jwt ttl change\")\n\t}\n\tif !diff.JWTSecretChanged {\n\t\tt.Fatalf(\"expected jwt secret change\")\n\t}\n\tif !diff.BaseURLChanged {\n\t\tt.Fatalf(\"expected base_url change\")\n\t}\n\tif !diff.CORSChanged {\n\t\tt.Fatalf(\"expected cors change\")\n\t}\n\tif !diff.TrustedProxiesChanged {\n\t\tt.Fatalf(\"expected trusted proxies change\")\n\t}\n\tif len(diff.RestartRequiredFields) == 0 {\n\t\tt.Fatalf(\"expected restart-required fields\")\n\t}\n}\n\nfunc TestBuildAppliedConfigKeepsUnsupportedFields(t *testing.T) {\n\toldCfg := &Conf{\n\t\tAppConfig: App,\n\t\tMysql: Mysql,\n\t\tRedis: Redis,\n\t\tLogger: Logger,\n\t\tJwt: JwtConfig{\n\t\t\tTTL: 100,\n\t\t\tRefreshTTL: 10,\n\t\t\tSecretKey: \"old-secret\",\n\t\t},\n\t}\n\toldCfg.TrustedProxies = []string{\"127.0.0.1\"}\n\toldCfg.Language = \"zh_CN\"\n\n\tnewCfg := &Conf{\n\t\tAppConfig: App,\n\t\tMysql: Mysql,\n\t\tRedis: Redis,\n\t\tLogger: Logger,\n\t\tJwt: JwtConfig{\n\t\t\tTTL: 200,\n\t\t\tRefreshTTL: 20,\n\t\t\tSecretKey: \"new-secret\",\n\t\t},\n\t}\n\tnewCfg.TrustedProxies = []string{\"10.0.0.0/8\"}\n\tnewCfg.Language = \"en\"\n\tnewCfg.BaseURL = \"https://cdn.example.com\"\n\n\tdiff := BuildConfigDiff(oldCfg, newCfg)\n\tapplied := BuildAppliedConfig(oldCfg, newCfg, diff)\n\n\tif applied.Jwt.SecretKey != \"old-secret\" {\n\t\tt.Fatalf(\"expected jwt secret to remain old, got %q\", applied.Jwt.SecretKey)\n\t}\n\tif applied.Language != \"zh_CN\" {\n\t\tt.Fatalf(\"expected language to remain old, got %q\", applied.Language)\n\t}\n\tif len(applied.TrustedProxies) != 1 || applied.TrustedProxies[0] != \"127.0.0.1\" {\n\t\tt.Fatalf(\"expected trusted proxies to remain old, got %#v\", applied.TrustedProxies)\n\t}\n\tif applied.BaseURL != \"https://cdn.example.com\" {\n\t\tt.Fatalf(\"expected supported field base_url to update, got %q\", applied.BaseURL)\n\t}\n\tif applied.Jwt.TTL != 200 {\n\t\tt.Fatalf(\"expected supported jwt ttl to update, got %v\", applied.Jwt.TTL)\n\t}\n}\n"
},
{
"path": "config/testing_helper.go",
"content": "package config\n\n// CloneConf 返回配置的深拷贝，避免测试场景下共享可变引用。\nfunc CloneConf(src *Conf) *Conf {\n\tif src == nil {\n\t\treturn &Conf{}\n\t}\n\n\tcloned := *src\n\tcloned.AppConfig = cloneAppConfig(src.AppConfig)\n\tcloned.Queue = cloneQueueConfig(src.Queue)\n\treturn &cloned\n}\n\n// ReplaceConfigForTesting 替换当前配置并返回恢复函数。\nfunc ReplaceConfigForTesting(cfg *Conf) func() {\n\tprevious := CloneConf(GetConfig())\n\n\tif cfg == nil {\n\t\tsetActiveConfig(&Conf{})\n\t} else {\n\t\tsetActiveConfig(CloneConf(cfg))\n\t}\n\n\treturn func() {\n\t\tsetActiveConfig(previous)\n\t}\n}\n\n// UpdateConfigForTesting 在当前配置副本上应用变更并返回恢复函数。\nfunc UpdateConfigForTesting(mutator func(cfg *Conf)) func() {\n\tnext := CloneConf(GetConfig())\n\tif mutator != nil {\n\t\tmutator(next)\n\t}\n\treturn ReplaceConfigForTesting(next)\n}\n"
},
{
"path": "data/data.go",
"content": "package data\n\nimport (\n\t\"errors\"\n\t\"fmt\"\n\t\"sync\"\n\n\tc \"github.com/wannanbigpig/gin-layout/config\"\n)\n\nvar once sync.Once\nvar initErr error\n\n// InitData 按配置初始化 MySQL 和 Redis 数据源。\nfunc InitData() error {\n\tonce.Do(func() {\n\t\tcfg := c.GetConfig()\n\t\tvar errs []error\n\n\t\tif cfg.Mysql.Enable {\n\t\t\tif err := initMysql(); err != nil {\n\t\t\t\terrs = append(errs, fmt.Errorf(\"mysql init error: %w\", err))\n\t\t\t}\n\t\t}\n\n\t\tif cfg.Redis.Enable {\n\t\t\tif err := initRedis(); err != nil {\n\t\t\t\terrs = append(errs, fmt.Errorf(\"redis init error: %w\", err))\n\t\t\t}\n\t\t}\n\n\t\tif len(errs) > 0 {\n\t\t\tinitErr = errors.Join(errs...)\n\t\t}\n\t})\n\n\treturn initErr\n}\n\n// Shutdown 关闭当前已初始化的数据源。\nfunc Shutdown() error {\n\tvar firstErr error\n\n\tif err := CloseRedis(); err != nil && firstErr == nil {\n\t\tfirstErr = err\n\t}\n\tif err := CloseMysql(); err != nil && firstErr == nil {\n\t\tfirstErr = err\n\t}\n\n\treturn firstErr\n}\n"
},
{
"path": "data/data_test.go",
"content": "package data\n\nimport \"testing\"\n\nfunc TestShutdownWithoutInitializedResources(t *testing.T) {\n\tif err := Shutdown(); err != nil {\n\t\tt.Fatalf(\"shutdown should be safe without initialized resources: %v\", err)\n\t}\n\tif err := Shutdown(); err != nil {\n\t\tt.Fatalf(\"shutdown should be idempotent: %v\", err)\n\t}\n}\n"
},
{
"path": "data/migrations/20260425000001_init_table.down.sql",
"content": "BEGIN;\n\n-- 删除系统参数与字典相关表\nDROP TABLE IF EXISTS `sys_dict_item_i18n`;\nDROP TABLE IF EXISTS `sys_dict_type_i18n`;\nDROP TABLE IF EXISTS `sys_config_i18n`;\nDROP TABLE IF EXISTS `sys_dict_item`;\nDROP TABLE IF EXISTS `sys_dict_type`;\nDROP TABLE IF EXISTS `sys_config`;\n-- 删除任务中心相关表\nDROP TABLE IF EXISTS `cron_task_states`;\nDROP TABLE IF EXISTS `task_run_events`;\nDROP TABLE IF EXISTS `task_runs`;\nDROP TABLE IF EXISTS `task_definitions`;\n-- 删除管理员表\nDROP TABLE IF EXISTS `admin_user`;\n-- 删除路由表\nDROP TABLE IF EXISTS `api`;\n-- 删除路由分组表\nDROP TABLE IF EXISTS `api_group`;\n-- 删除菜单多语言标题表\nDROP TABLE IF EXISTS `menu_i18n`;\n-- 删除菜单表\nDROP TABLE IF EXISTS `menu`;\n-- 删除部门表\nDROP TABLE IF EXISTS `department`;\n-- 删除角色表\nDROP TABLE IF EXISTS `role`;\n-- 删除用户部门映射表\nDROP TABLE IF EXISTS `admin_user_department_map`;\n-- 删除部门角色映射表\nDROP TABLE IF EXISTS `department_role_map`;\n-- 删除用户菜单映射表\nDROP TABLE IF EXISTS `admin_user_menu_map`;\n-- 删除菜单权限映射表\nDROP TABLE IF EXISTS `menu_api_map`;\n-- 删除角色菜单映射表\nDROP TABLE IF EXISTS `role_menu_map`;\n-- 删除用户角色映射表\nDROP TABLE IF EXISTS `admin_user_role_map`;\n-- 删除请求日志表\nDROP TABLE IF EXISTS `request_logs`;\n-- 删除登录安全状态表\nDROP TABLE IF EXISTS `login_security_state`;\n-- 删除管理员登录日志表\nDROP TABLE IF EXISTS `admin_login_logs`;\n-- 删除casbin规则表\nDROP TABLE IF EXISTS `casbin_rule`;\n-- 删除文件上传表\nDROP TABLE IF EXISTS `upload_file_references`;\nDROP TABLE IF EXISTS `upload_file_folders`;\nDROP TABLE IF EXISTS `upload_files`;\n\nCOMMIT;\n"
},
{
"path": "data/migrations/20260425000001_init_table.up.sql",
"content": "BEGIN;\n\n-- 创建管理员表\nCREATE TABLE IF NOT EXISTS `admin_user`\n(\n `id` int unsigned NOT NULL AUTO_INCREMENT,\n `nickname` varchar(30) NOT NULL DEFAULT '' COMMENT '昵称',\n `username` varchar(30) NOT NULL DEFAULT '' COMMENT '用户名',\n `password` varchar(255) NOT NULL DEFAULT '' COMMENT '密码',\n `phone_number` varchar(15) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL DEFAULT '' COMMENT '手机号',\n `full_phone_number` varchar(20) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL DEFAULT '' COMMENT '带区号的手机号',\n `country_code` varchar(10) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL DEFAULT '' COMMENT '国际区号',\n `email` varchar(120) NOT NULL DEFAULT '' COMMENT '邮箱',\n `avatar` varchar(255) NOT NULL DEFAULT '' COMMENT '头像',\n `status` tinyint(1) NOT NULL DEFAULT '1' COMMENT '状态 1启用 0禁用',\n `is_super_admin` tinyint(1) NOT NULL DEFAULT '1' COMMENT '是否超级管理员（拥有所有权限） 1是 0不是',\n `last_login` datetime DEFAULT NULL COMMENT '最后登录时间',\n `last_ip` varchar(45) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NOT NULL DEFAULT '' COMMENT '最后登录IP',\n `created_at` datetime DEFAULT NULL,\n `updated_at` datetime DEFAULT NULL,\n `deleted_at` int NOT NULL DEFAULT '0' COMMENT '删除时间',\n PRIMARY KEY (`id`),\n UNIQUE KEY `adu_u_d` (`username`, `deleted_at`),\n KEY `idx_status_deleted_at` (`status`, `deleted_at`),\n KEY `idx_full_phone_number_deleted_at` (`full_phone_number`, `deleted_at`),\n KEY `idx_email_deleted_at` (`email`, `deleted_at`),\n KEY `idx_created_at_deleted_at` (`created_at`, `deleted_at`)\n) ENGINE = InnoDB\n AUTO_INCREMENT = 10000\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_0900_ai_ci COMMENT ='后台管理用户表';\n\n-- 创建权限分组表\nCREATE TABLE IF NOT EXISTS `api_group`\n(\n `id` int unsigned NOT NULL AUTO_INCREMENT,\n `pid` int unsigned NOT NULL DEFAULT '0' COMMENT '上级组织id',\n `code` varchar(30) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT 'code',\n `name` varchar(60) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '分组名称',\n `created_at` datetime DEFAULT NULL,\n `updated_at` datetime DEFAULT NULL,\n PRIMARY KEY (`id`) USING BTREE,\n UNIQUE KEY `ag_code` (`code`)\n) ENGINE = InnoDB\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_bin\n ROW_FORMAT = DYNAMIC COMMENT ='权限分组表';\n\n-- 创建权限表\nCREATE TABLE IF NOT EXISTS `api`\n(\n `id` int unsigned NOT NULL AUTO_INCREMENT,\n `code` varchar(32) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '权限唯一code码',\n `group_code` varchar(36) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '分组唯一code码',\n `name` varchar(60) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '权限名称',\n `description` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '描述',\n `method` varchar(10) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '接口请求方法',\n `route` varchar(160) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '接口路由',\n `func` varchar(80) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '接口方法',\n `func_path` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '接口方法路径',\n `is_auth` tinyint unsigned NOT NULL DEFAULT '1' COMMENT '接口鉴权模式 0无需登录 1需要登录 2需要登录且需要API权限',\n `is_effective` tinyint unsigned NOT NULL DEFAULT '1' COMMENT '接口是否可用 1是 0否',\n `sort` int unsigned NOT NULL DEFAULT '0' COMMENT '排序',\n `created_at` datetime DEFAULT NULL,\n `updated_at` datetime DEFAULT NULL,\n `deleted_at` int NOT NULL DEFAULT '0' COMMENT '删除时间戳',\n PRIMARY KEY (`id`) USING BTREE,\n UNIQUE KEY `api_uniq_code_del` (`code`, `deleted_at`) USING BTREE,\n KEY `api_idx_route_method_deleted_at` (`route`, `method`, `deleted_at`) USING BTREE,\n KEY `idx_group_code_deleted_at_sort` (`group_code`, `deleted_at`, `sort`) USING BTREE,\n KEY `idx_is_auth_deleted_at` (`is_auth`, `deleted_at`) USING BTREE,\n KEY `idx_updated_at` (`updated_at`) USING BTREE\n) ENGINE = InnoDB\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_bin\n ROW_FORMAT = DYNAMIC COMMENT ='权限表';\n\n-- 创建菜单表\nCREATE TABLE IF NOT EXISTS `menu`\n(\n `id` int NOT NULL AUTO_INCREMENT,\n `icon` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '图标',\n `code` varchar(120) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '前端权限标识',\n `path` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '前端路由路径',\n `full_path` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '完整前端路由路径',\n `redirect` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '重定向路由名称',\n `name` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '前端路由名称',\n `component` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '前端组件路径',\n `animate_enter` varchar(60) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '进入动画，动画类参考https://animate.style/',\n `animate_leave` varchar(60) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '离开动画，动画类参考https://animate.style/',\n `animate_duration` float(2, 2) NOT NULL DEFAULT '0.00' COMMENT '动画持续时间',\n `is_show` tinyint NOT NULL DEFAULT '0' COMMENT '是否显示，1是 0否',\n `status` tinyint NOT NULL DEFAULT '0' COMMENT '状态，1正常 0禁用',\n `is_auth` tinyint NOT NULL DEFAULT '0' COMMENT '是否需要授权，1是 0否 ',\n `is_external_links` tinyint NOT NULL DEFAULT '0' COMMENT '是否外链，1是 0否 ',\n `is_new_window` tinyint NOT NULL DEFAULT '0' COMMENT '是否新窗口打开, 1是 0否',\n `sort` int NOT NULL DEFAULT '0' COMMENT '排序，数字越大，排名越靠前',\n `type` tinyint NOT NULL DEFAULT '1' COMMENT '菜单类型，1目录，2菜单，3按钮',\n `pid` int NOT NULL DEFAULT '0' COMMENT '上级菜单id',\n `level` tinyint NOT NULL DEFAULT '0' COMMENT '层级',\n `pids` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '层级序列，多个用英文逗号隔开',\n `children_num` int NOT NULL DEFAULT '0' COMMENT '子集数量',\n `description` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '描述',\n `created_at` datetime DEFAULT NULL COMMENT '创建时间',\n `updated_at` datetime DEFAULT NULL COMMENT '更新时间',\n `deleted_at` int NOT NULL DEFAULT '0' COMMENT '删除时间戳',\n PRIMARY KEY (`id`) USING BTREE,\n KEY `uniq_code_del` (`code`, `deleted_at`) USING BTREE,\n KEY `idx_name_del` (`name`, `deleted_at`) USING BTREE,\n KEY `idx_path_del` (`path`, `deleted_at`) USING BTREE,\n KEY `idx_is_auth_del` (`is_auth`, `deleted_at`) USING BTREE,\n KEY `idx_status_del` (`status`, `deleted_at`) USING BTREE,\n KEY `idx_pid_deleted_at_sort_id` (`pid`, `deleted_at`, `sort`, `id`) USING BTREE,\n KEY `idx_pids_deleted_at` (`pids`, `deleted_at`) USING BTREE\n) ENGINE = InnoDB\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_bin\n ROW_FORMAT = DYNAMIC COMMENT ='菜单表';\n\n-- 创建菜单多语言标题表\nCREATE TABLE IF NOT EXISTS `menu_i18n`\n(\n `id` int unsigned NOT NULL AUTO_INCREMENT,\n `menu_id` int unsigned NOT NULL DEFAULT '0' COMMENT '菜单ID',\n `locale` varchar(10) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '语言代码，如 zh-CN、en-US',\n `title` varchar(60) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '菜单标题',\n `created_at` datetime DEFAULT NULL,\n `updated_at` datetime DEFAULT NULL,\n PRIMARY KEY (`id`) USING BTREE,\n UNIQUE KEY `uniq_menu_id_locale` (`menu_id`, `locale`) USING BTREE,\n KEY `idx_locale_menu_id` (`locale`, `menu_id`) USING BTREE\n) ENGINE = InnoDB\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_bin\n ROW_FORMAT = DYNAMIC COMMENT ='菜单多语言标题表';\n\n-- 创建组织表\nCREATE TABLE IF NOT EXISTS `department`\n(\n `id` int unsigned NOT NULL AUTO_INCREMENT,\n `code` varchar(60) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '部门业务编码',\n `is_system` tinyint NOT NULL DEFAULT '0' COMMENT '是否系统保留对象,1是 0否',\n `pid` int unsigned NOT NULL DEFAULT '0' COMMENT '上级部门id',\n `pids` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '',\n `name` varchar(60) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '部门名称',\n `description` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '描述',\n `level` tinyint NOT NULL DEFAULT '1' COMMENT '层级',\n `sort` int NOT NULL DEFAULT '0' COMMENT '排序',\n `children_num` int NOT NULL DEFAULT '0' COMMENT '子集数量',\n `user_number` int NOT NULL DEFAULT '0' COMMENT '部门用户数量',\n `created_at` datetime DEFAULT NULL,\n `updated_at` datetime DEFAULT NULL,\n `deleted_at` int NOT NULL DEFAULT '0' COMMENT '删除时间戳',\n PRIMARY KEY (`id`) USING BTREE,\n UNIQUE KEY `uniq_code_deleted_at` (`code`, `deleted_at`),\n KEY `idx_name_deleted_at` (`name`, `deleted_at`),\n KEY `idx_is_system_deleted_at` (`is_system`, `deleted_at`),\n KEY `idx_pid_deleted_at_sort_id` (`pid`, `deleted_at`, `sort`, `id`),\n KEY `idx_pids_deleted_at` (`pids`, `deleted_at`)\n) ENGINE = InnoDB\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_bin\n ROW_FORMAT = DYNAMIC COMMENT ='部门表';\n\n-- 创建角色表\nCREATE TABLE IF NOT EXISTS `role`\n(\n `id` int unsigned NOT NULL AUTO_INCREMENT,\n `code` varchar(60) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '角色业务编码',\n `is_system` tinyint NOT NULL DEFAULT '0' COMMENT '是否系统保留对象,1是 0否',\n `pid` int unsigned NOT NULL DEFAULT '0' COMMENT '上级id',\n `pids` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '上级id路径链',\n `name` varchar(60) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '角色名称',\n `description` varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '描述',\n `level` tinyint NOT NULL DEFAULT '1' COMMENT '层级',\n `sort` mediumint NOT NULL DEFAULT '0' COMMENT '排序',\n `children_num` int unsigned NOT NULL DEFAULT '0' COMMENT '子集数量',\n `status` tinyint NOT NULL DEFAULT '0' COMMENT '是否启用状态,1是，0否',\n `created_at` datetime DEFAULT NULL,\n `updated_at` datetime DEFAULT NULL,\n `deleted_at` int NOT NULL DEFAULT '0' COMMENT '删除时间戳',\n PRIMARY KEY (`id`) USING BTREE,\n UNIQUE KEY `uniq_code_deleted_at` (`code`, `deleted_at`),\n KEY `idx_name_deleted_at` (`name`, `deleted_at`),\n KEY `idx_is_system_deleted_at` (`is_system`, `deleted_at`),\n KEY `idx_pid_deleted_at_sort_id` (`pid`, `deleted_at`, `sort`, `id`),\n KEY `idx_status_deleted_at` (`status`, `deleted_at`),\n KEY `idx_pids_deleted_at` (`pids`, `deleted_at`)\n) ENGINE = InnoDB\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_bin\n ROW_FORMAT = DYNAMIC COMMENT ='角色表';\n\n-- 创建用户部门映射表\nCREATE TABLE IF NOT EXISTS `admin_user_department_map`\n(\n `id` int unsigned NOT NULL AUTO_INCREMENT,\n `uid` int unsigned NOT NULL DEFAULT '0' COMMENT 'admin_users表id',\n `dept_id` int unsigned NOT NULL DEFAULT '0' COMMENT '部门id，department表id',\n `is_admin` tinyint NOT NULL DEFAULT '0' COMMENT '是否管理员，1是，0否',\n `created_at` datetime DEFAULT NULL,\n `updated_at` datetime DEFAULT NULL,\n PRIMARY KEY (`id`) USING BTREE,\n UNIQUE KEY `idx_uid_dept_id` (`uid`, `dept_id`),\n KEY `idx_dept_id_uid` (`dept_id`, `uid`)\n) ENGINE = InnoDB\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_bin\n ROW_FORMAT = DYNAMIC COMMENT ='用户部门映射表';\n\n-- 创建菜单权限映射表\nCREATE TABLE IF NOT EXISTS `menu_api_map`\n(\n `id` int unsigned NOT NULL AUTO_INCREMENT,\n `menu_id` int unsigned NOT NULL DEFAULT '0' COMMENT '菜单id,对应menu表id',\n `api_id` int unsigned NOT NULL DEFAULT '0' COMMENT '接口id,对应api表id',\n `created_at` datetime DEFAULT NULL,\n `updated_at` datetime DEFAULT NULL,\n PRIMARY KEY (`id`) USING BTREE,\n UNIQUE KEY `idx_menu_id_api_id` (`menu_id`, `api_id`),\n KEY `idx_api_id_menu_id` (`api_id`, `menu_id`)\n) ENGINE = InnoDB\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_bin\n ROW_FORMAT = DYNAMIC COMMENT ='菜单权限映射表';\n\n-- menu_api_map 维护菜单与 API 的静态关系。\n-- api 表由 `go-layout command api-route` 或 `init-system` 写入后，\n-- 默认菜单与 API 的初始绑定由 Go 初始化逻辑幂等补齐。\n\n-- 创建角色菜单映射表\nCREATE TABLE IF NOT EXISTS `role_menu_map`\n(\n `id` int unsigned NOT NULL AUTO_INCREMENT,\n `role_id` int unsigned NOT NULL DEFAULT '0' COMMENT '角色id,对应roles表id',\n `menu_id` int unsigned NOT NULL DEFAULT '0' COMMENT '菜单id,对应menu表id',\n `created_at` datetime DEFAULT NULL,\n `updated_at` datetime DEFAULT NULL,\n PRIMARY KEY (`id`) USING BTREE,\n UNIQUE KEY `idx_role_id_menu_id` (`role_id`, `menu_id`),\n KEY `idx_menu_id_role_id` (`menu_id`, `role_id`)\n) ENGINE = InnoDB\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_bin\n ROW_FORMAT = DYNAMIC COMMENT ='角色菜单映射表';\n\n-- 创建用户菜单映射表\nCREATE TABLE IF NOT EXISTS `admin_user_menu_map`\n(\n `id` int unsigned NOT NULL AUTO_INCREMENT,\n `uid` int unsigned NOT NULL DEFAULT '0' COMMENT 'uid,admin_users表id',\n `menu_id` int unsigned NOT NULL DEFAULT '0' COMMENT '菜单id',\n `created_at` datetime DEFAULT NULL,\n `updated_at` datetime DEFAULT NULL,\n PRIMARY KEY (`id`) USING BTREE,\n UNIQUE KEY `idx_uid_menu_id` (`uid`, `menu_id`),\n KEY `idx_menu_id_uid` (`menu_id`, `uid`)\n) ENGINE = InnoDB\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_bin\n ROW_FORMAT = DYNAMIC COMMENT ='用户菜单映射表';\n\n-- 创建部门角色映射表\nCREATE TABLE IF NOT EXISTS `department_role_map`\n(\n `id` int unsigned NOT NULL AUTO_INCREMENT,\n `dept_id` int unsigned NOT NULL DEFAULT '0' COMMENT '部门id,对应department表id',\n `role_id` int unsigned NOT NULL DEFAULT '0' COMMENT '角色id,对应roles表id',\n `created_at` datetime DEFAULT NULL,\n `updated_at` datetime DEFAULT NULL,\n PRIMARY KEY (`id`) USING BTREE,\n UNIQUE KEY `idx_dept_id_role_id` (`dept_id`, `role_id`),\n KEY `idx_role_id_dept_id` (`role_id`, `dept_id`)\n) ENGINE = InnoDB\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_bin\n ROW_FORMAT = DYNAMIC COMMENT ='部门角色映射表';\n\n-- 创建用户角色映射表\nCREATE TABLE IF NOT EXISTS `admin_user_role_map`\n(\n `id` int unsigned NOT NULL AUTO_INCREMENT,\n `uid` int unsigned NOT NULL DEFAULT '0' COMMENT 'uid,admin_users表id',\n `role_id` int unsigned NOT NULL DEFAULT '0' COMMENT '角色id',\n `created_at` datetime DEFAULT NULL,\n `updated_at` datetime DEFAULT NULL,\n PRIMARY KEY (`id`) USING BTREE,\n UNIQUE KEY `idx_uid_role_id` (`uid`, `role_id`),\n KEY `idx_role_id_uid` (`role_id`, `uid`)\n) ENGINE = InnoDB\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_bin\n ROW_FORMAT = DYNAMIC COMMENT ='用户角色映射表';\n\n-- 创建管理员登录日志表\nCREATE TABLE IF NOT EXISTS `admin_login_logs`\n(\n `id` bigint unsigned NOT NULL AUTO_INCREMENT,\n `uid` int unsigned NOT NULL DEFAULT '0' COMMENT '用户ID（登录失败时为0）',\n `username` varchar(50) NOT NULL DEFAULT '' COMMENT '登录账号',\n `jwt_id` char(36) NOT NULL DEFAULT '' COMMENT 'JWT唯一标识(jti claim)',\n `access_token` text DEFAULT NULL COMMENT '访问令牌（加密保存）',\n `refresh_token` text DEFAULT NULL COMMENT '刷新令牌（加密保存）',\n `token_hash` char(64) NOT NULL DEFAULT '' COMMENT 'Token的SHA256哈希值',\n `refresh_token_hash` char(64) NOT NULL DEFAULT '' COMMENT 'Refresh Token的哈希值',\n `ip` varchar(45) NOT NULL DEFAULT '' COMMENT '登录IP(支持IPv6)',\n `user_agent` varchar(1024) NOT NULL DEFAULT '' COMMENT '用户代理（浏览器/设备信息）',\n `os` varchar(50) NOT NULL DEFAULT '' COMMENT '操作系统',\n `browser` varchar(50) NOT NULL DEFAULT '' COMMENT '浏览器',\n `execution_time` int(11) NOT NULL DEFAULT '0' COMMENT '登录耗时（毫秒）',\n `login_status` tinyint(1) NOT NULL DEFAULT '1' COMMENT '登录状态：1=成功, 0=失败',\n `login_fail_reason` varchar(255) NOT NULL DEFAULT '' COMMENT '登录失败原因',\n `type` tinyint(1) NOT NULL DEFAULT '1' COMMENT '操作类型：1=登录操作, 2=刷新token',\n `is_revoked` tinyint(1) NOT NULL DEFAULT '0' COMMENT '是否被撤销：0=否, 1=是',\n `revoked_code` tinyint(1) NOT NULL DEFAULT '0' COMMENT '撤销原因码：1=用户主动登出（退出登录）, 2=系统强制登出（账号被封）, 3=系统刷新token, 4=用户禁用（针对某个设备下线操作）, 5=其他原因, 6=用户自己修改密码, 7=管理员修改用户密码',\n `revoked_reason` varchar(255) NOT NULL DEFAULT '' COMMENT '撤销原因',\n `revoked_at` datetime DEFAULT NULL COMMENT '撤销时间',\n `token_expires` datetime DEFAULT NULL COMMENT 'Token过期时间',\n `refresh_expires` datetime DEFAULT NULL COMMENT 'Refresh Token过期时间',\n `created_at` datetime DEFAULT NULL,\n `updated_at` datetime DEFAULT NULL,\n `deleted_at` int NOT NULL DEFAULT '0' COMMENT '删除时间戳',\n PRIMARY KEY (`id`),\n KEY `aall_deleted_at_created_at` (`deleted_at`, `created_at`),\n KEY `aall_login_status_deleted_at_created_at` (`login_status`, `deleted_at`, `created_at`),\n KEY `aall_is_revoked_deleted_at_revoked_at` (`is_revoked`, `deleted_at`, `revoked_at`),\n KEY `aall_uid_deleted_at_is_revoked_login_status_token_expires` (`uid`, `deleted_at`, `is_revoked`, `login_status`, `token_expires`),\n KEY `aall_jwt_id_deleted_at_is_revoked` (`jwt_id`, `deleted_at`, `is_revoked`)\n) ENGINE = InnoDB\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_unicode_ci COMMENT ='管理员登录日志表';\n\n-- 创建登录安全状态表\nCREATE TABLE IF NOT EXISTS `login_security_state`\n(\n `id` int unsigned NOT NULL AUTO_INCREMENT,\n `username` varchar(50) NOT NULL DEFAULT '' COMMENT '登录账号',\n `fail_count` int unsigned NOT NULL DEFAULT '0' COMMENT '连续失败次数',\n `lock_until` datetime DEFAULT NULL COMMENT '锁定截止时间',\n `last_failed_at` datetime DEFAULT NULL COMMENT '最近失败时间',\n `created_at` datetime DEFAULT NULL,\n `updated_at` datetime DEFAULT NULL,\n PRIMARY KEY (`id`),\n UNIQUE KEY `lss_username` (`username`),\n KEY `lss_lock_until` (`lock_until`)\n) ENGINE = InnoDB\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_unicode_ci COMMENT ='登录安全状态表';\n\n-- 创建请求日志表\nCREATE TABLE IF NOT EXISTS `request_logs`\n(\n `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '日志ID',\n `request_id` varchar(64) NOT NULL DEFAULT '' COMMENT '请求唯一标识',\n `jwt_id` varchar(36) NOT NULL DEFAULT '' COMMENT '请求授权的jwtId',\n `operator_id` bigint(20) unsigned NOT NULL DEFAULT '0' COMMENT '操作ID（用户ID）',\n `ip` varchar(45) NOT NULL DEFAULT '' COMMENT '客户端IP地址',\n `user_agent` varchar(1024) NOT NULL DEFAULT '' COMMENT '用户代理（浏览器/设备信息）',\n `os` varchar(50) NOT NULL DEFAULT '' COMMENT '操作系统',\n `browser` varchar(50) NOT NULL DEFAULT '' COMMENT '浏览器',\n `method` varchar(10) NOT NULL DEFAULT '' COMMENT 'HTTP请求方法（GET/POST等）',\n `base_url` varchar(160) NOT NULL DEFAULT '' COMMENT '请求基础URL',\n `operation_name` varchar(255) NOT NULL DEFAULT '' COMMENT '操作名称',\n `operation_status` int(11) NOT NULL DEFAULT '0' COMMENT '操作状态码（响应返回的code，0=成功，其他=失败）',\n `is_high_risk` tinyint(1) NOT NULL DEFAULT '0' COMMENT '是否高危操作 1是 0否',\n `operator_account` varchar(50) NOT NULL DEFAULT '' COMMENT '操作账号',\n `operator_name` varchar(50) NOT NULL DEFAULT '' COMMENT '操作人员',\n `request_headers` text DEFAULT NULL COMMENT '请求头（JSON格式）',\n `request_query` text DEFAULT NULL COMMENT '请求参数',\n `request_body` text DEFAULT NULL COMMENT '请求体',\n `change_diff` longtext DEFAULT NULL COMMENT '关键变更前后差异（JSON）',\n `response_status` int(11) NOT NULL DEFAULT '0' COMMENT '响应状态码',\n `response_body` text DEFAULT NULL COMMENT '响应体',\n `response_header` text DEFAULT NULL COMMENT '响应头',\n `execution_time` DECIMAL(10,4) NOT NULL DEFAULT '0.0000' COMMENT '执行时间（毫秒，支持小数，最多4位）',\n `created_at` datetime DEFAULT NULL COMMENT '创建时间',\n `updated_at` datetime DEFAULT NULL COMMENT '更新时间',\n PRIMARY KEY (`id`),\n KEY `rl_request_id` (`request_id`),\n KEY `rl_operator_id_created_at` (`operator_id`, `created_at`),\n KEY `rl_base_url_method_created_at` (`base_url`, `method`, `created_at`),\n KEY `rl_operation_status_created_at` (`operation_status`, `created_at`),\n KEY `rl_response_status_operator_id_created_at` (`response_status`, `operator_id`, `created_at`),\n KEY `rl_operator_account_created_at` (`operator_account`, `created_at`),\n KEY `rl_created_at` (`created_at`),\n KEY `rl_jwt_id` (`jwt_id`),\n KEY `rl_is_high_risk_created_at` (`is_high_risk`, `created_at`)\n) ENGINE = InnoDB\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_unicode_ci COMMENT ='请求日志表';\n\n\nCREATE TABLE IF NOT EXISTS `casbin_rule`\n(\n `id` bigint unsigned NOT NULL AUTO_INCREMENT,\n `ptype` varchar(100) DEFAULT NULL,\n `v0` varchar(100) DEFAULT NULL,\n `v1` varchar(100) DEFAULT NULL,\n `v2` varchar(100) DEFAULT NULL,\n `v3` varchar(100) DEFAULT NULL,\n `v4` varchar(100) DEFAULT NULL,\n `v5` varchar(100) DEFAULT NULL,\n PRIMARY KEY (`id`),\n UNIQUE KEY `idx_casbin_rule` (`ptype`, `v0`, `v1`, `v2`, `v3`, `v4`, `v5`)\n) ENGINE = InnoDB\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_0900_ai_ci COMMENT ='casbin_rule表';\n\nCREATE TABLE IF NOT EXISTS `upload_files`\n(\n `id` int unsigned NOT NULL AUTO_INCREMENT,\n `uid` int unsigned NOT NULL DEFAULT '0' COMMENT '用户ID',\n `folder_id` int unsigned NOT NULL DEFAULT '0' COMMENT '逻辑目录ID',\n `logical_path` varchar(1024) NOT NULL DEFAULT '/' COMMENT '逻辑路径快照',\n `display_name` varchar(255) NOT NULL DEFAULT '' COMMENT '展示名称',\n `origin_name` varchar(255) NOT NULL DEFAULT '' COMMENT '文件源名称',\n `name` varchar(255) NOT NULL DEFAULT '' COMMENT '文件名称（UUID+扩展名）',\n `path` varchar(255) NOT NULL DEFAULT '' COMMENT '文件相对路径（相对于storage/public或storage/private）',\n `size` int unsigned NOT NULL DEFAULT '0' COMMENT '文件大小（字节）',\n `ext` varchar(20) NOT NULL DEFAULT '' COMMENT '文件扩展名',\n `hash` varchar(64) NOT NULL DEFAULT '' COMMENT '文件SHA256哈希值（用于去重）',\n `uuid` varchar(32) NOT NULL DEFAULT '' COMMENT '文件UUID（用于URL访问，32位十六进制字符串，不带连字符）',\n `mime_type` varchar(100) NOT NULL DEFAULT '' COMMENT 'MIME类型（如：image/jpeg, application/pdf）',\n `file_type` varchar(20) NOT NULL DEFAULT '' COMMENT '文件类型:image,pdf,word,excel,ppt,archive,text,audio,video,other',\n `is_public` tinyint NOT NULL DEFAULT '0' COMMENT '是否公开访问: 0否 1是',\n `storage_driver` varchar(20) NOT NULL DEFAULT 'local' COMMENT '存储驱动:local,aliyun_oss,s3',\n `storage_base` varchar(512) NOT NULL DEFAULT '' COMMENT '存储基础位置',\n `bucket` varchar(128) NOT NULL DEFAULT '' COMMENT '存储桶',\n `storage_path` varchar(512) NOT NULL DEFAULT '' COMMENT '实际存储路径',\n `object_key` varchar(512) NOT NULL DEFAULT '' COMMENT '对象key',\n `etag` varchar(128) NOT NULL DEFAULT '' COMMENT '对象ETag',\n `storage_status` varchar(32) NOT NULL DEFAULT 'stored' COMMENT '存储状态:stored,delete_failed',\n `upload_source` varchar(20) NOT NULL DEFAULT 'backend' COMMENT '上传来源:backend,direct,system',\n `upload_scene` varchar(60) NOT NULL DEFAULT '' COMMENT '上传场景',\n `upload_status` varchar(20) NOT NULL DEFAULT 'uploaded' COMMENT '上传状态:pending,uploaded,failed',\n `last_accessed_at` datetime DEFAULT NULL COMMENT '最后访问时间',\n `deleted_by` int unsigned NOT NULL DEFAULT '0' COMMENT '删除人',\n `deleted_reason` varchar(255) NOT NULL DEFAULT '' COMMENT '删除原因',\n `created_at` datetime DEFAULT NULL COMMENT '创建时间',\n `updated_at` datetime DEFAULT NULL COMMENT '更新时间',\n `deleted_at` int unsigned NOT NULL DEFAULT '0' COMMENT '删除时间戳',\n PRIMARY KEY (`id`),\n KEY `idx_uid_created_at` (`uid`, `created_at`),\n KEY `idx_folder_created_at` (`folder_id`, `created_at`),\n KEY `idx_hash_is_public` (`hash`, `is_public`),\n KEY `idx_file_type_created_at` (`file_type`, `created_at`),\n KEY `idx_storage_driver_status` (`storage_driver`, `storage_status`),\n KEY `idx_deleted_at_created_at` (`deleted_at`, `created_at`),\n UNIQUE KEY `idx_uuid` (`uuid`),\n KEY `idx_is_public_uuid` (`is_public`, `uuid`)\n) ENGINE = InnoDB\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_unicode_ci COMMENT ='上传文件表';\n\nCREATE TABLE IF NOT EXISTS `upload_file_folders`\n(\n `id` int unsigned NOT NULL AUTO_INCREMENT,\n `parent_id` int unsigned NOT NULL DEFAULT '0' COMMENT '父目录ID',\n `name` varchar(120) NOT NULL DEFAULT '' COMMENT '目录名称',\n `logical_path` varchar(1024) NOT NULL DEFAULT '/' COMMENT '逻辑路径',\n `sort` int NOT NULL DEFAULT '0' COMMENT '排序',\n `created_by` int unsigned NOT NULL DEFAULT '0' COMMENT '创建人',\n `updated_by` int unsigned NOT NULL DEFAULT '0' COMMENT '更新人',\n `created_at` datetime DEFAULT NULL COMMENT '创建时间',\n `updated_at` datetime DEFAULT NULL COMMENT '更新时间',\n `deleted_at` int unsigned NOT NULL DEFAULT '0' COMMENT '删除时间戳',\n PRIMARY KEY (`id`),\n UNIQUE KEY `uniq_parent_name_deleted` (`parent_id`, `name`, `deleted_at`),\n KEY `idx_parent_sort` (`parent_id`, `sort`, `id`),\n KEY `idx_logical_path` (`logical_path`(191))\n) ENGINE = InnoDB\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_unicode_ci COMMENT ='上传文件逻辑目录表';\n\nCREATE TABLE IF NOT EXISTS `upload_file_references`\n(\n `id` int unsigned NOT NULL AUTO_INCREMENT,\n `file_id` int unsigned NOT NULL DEFAULT '0' COMMENT 'upload_files.id',\n `uuid` varchar(32) NOT NULL DEFAULT '' COMMENT '文件UUID',\n `owner_type` varchar(60) NOT NULL DEFAULT '' COMMENT '引用对象类型',\n `owner_id` int unsigned NOT NULL DEFAULT '0' COMMENT '引用对象ID',\n `owner_field` varchar(60) NOT NULL DEFAULT '' COMMENT '引用字段',\n `created_at` datetime DEFAULT NULL COMMENT '创建时间',\n `updated_at` datetime DEFAULT NULL COMMENT '更新时间',\n PRIMARY KEY (`id`),\n UNIQUE KEY `uniq_owner_file_field` (`owner_type`, `owner_id`, `owner_field`, `file_id`),\n KEY `idx_file_id` (`file_id`),\n KEY `idx_uuid` (`uuid`),\n KEY `idx_owner` (`owner_type`, `owner_id`, `owner_field`)\n) ENGINE = InnoDB\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_unicode_ci COMMENT ='上传文件引用关系表';\n\nCREATE TABLE IF NOT EXISTS `sys_config`\n(\n `id` int unsigned NOT NULL AUTO_INCREMENT,\n `config_key` varchar(100) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '参数键名',\n `config_value` text DEFAULT NULL COMMENT '参数值',\n `value_type` varchar(20) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT 'string' COMMENT '值类型:string,number,bool,json',\n `group_code` varchar(60) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT 'default' COMMENT '参数分组',\n `is_system` tinyint unsigned NOT NULL DEFAULT '0' COMMENT '是否系统内置:0否,1是',\n `is_sensitive` tinyint unsigned NOT NULL DEFAULT '0' COMMENT '是否敏感配置:0否,1是',\n `is_visible` tinyint unsigned NOT NULL DEFAULT '1' COMMENT '是否在系统参数页展示:0否,1是',\n `manage_tab` varchar(60) NOT NULL DEFAULT '' COMMENT '专属配置Tab',\n `status` tinyint unsigned NOT NULL DEFAULT '1' COMMENT '状态:0禁用,1启用',\n `sort` int unsigned NOT NULL DEFAULT '0' COMMENT '排序',\n `remark` varchar(255) NOT NULL DEFAULT '' COMMENT '备注',\n `created_at` datetime DEFAULT NULL,\n `updated_at` datetime DEFAULT NULL,\n `deleted_at` int unsigned NOT NULL DEFAULT '0' COMMENT '删除时间戳',\n PRIMARY KEY (`id`) USING BTREE,\n UNIQUE KEY `uniq_config_key_deleted_at` (`config_key`, `deleted_at`) USING BTREE,\n KEY `idx_group_status_deleted_at_sort` (`group_code`, `status`, `deleted_at`, `sort`) USING BTREE,\n KEY `idx_visible_deleted_at_sort` (`is_visible`, `deleted_at`, `sort`) USING BTREE,\n KEY `idx_status_deleted_at` (`status`, `deleted_at`) USING BTREE\n) ENGINE = InnoDB\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_unicode_ci COMMENT ='系统参数表';\n\nCREATE TABLE IF NOT EXISTS `sys_dict_type`\n(\n `id` int unsigned NOT NULL AUTO_INCREMENT,\n `type_code` varchar(100) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '字典类型编码',\n `is_system` tinyint unsigned NOT NULL DEFAULT '0' COMMENT '是否系统内置:0否,1是',\n `status` tinyint unsigned NOT NULL DEFAULT '1' COMMENT '状态:0禁用,1启用',\n `sort` int unsigned NOT NULL DEFAULT '0' COMMENT '排序',\n `remark` varchar(255) NOT NULL DEFAULT '' COMMENT '备注',\n `created_at` datetime DEFAULT NULL,\n `updated_at` datetime DEFAULT NULL,\n `deleted_at` int unsigned NOT NULL DEFAULT '0' COMMENT '删除时间戳',\n PRIMARY KEY (`id`) USING BTREE,\n UNIQUE KEY `uniq_type_code_deleted_at` (`type_code`, `deleted_at`) USING BTREE,\n KEY `idx_status_deleted_at_sort` (`status`, `deleted_at`, `sort`) USING BTREE\n) ENGINE = InnoDB\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_unicode_ci COMMENT ='系统字典类型表';\n\nCREATE TABLE IF NOT EXISTS `sys_dict_item`\n(\n `id` int unsigned NOT NULL AUTO_INCREMENT,\n `type_code` varchar(100) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '字典类型编码',\n `value` varchar(100) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '字典值',\n `color` varchar(30) NOT NULL DEFAULT '' COMMENT '展示颜色',\n `tag_type` varchar(30) NOT NULL DEFAULT '' COMMENT '前端标签类型',\n `is_default` tinyint unsigned NOT NULL DEFAULT '0' COMMENT '是否默认项:0否,1是',\n `is_system` tinyint unsigned NOT NULL DEFAULT '0' COMMENT '是否系统内置:0否,1是',\n `status` tinyint unsigned NOT NULL DEFAULT '1' COMMENT '状态:0禁用,1启用',\n `sort` int unsigned NOT NULL DEFAULT '0' COMMENT '排序',\n `remark` varchar(255) NOT NULL DEFAULT '' COMMENT '备注',\n `created_at` datetime DEFAULT NULL,\n `updated_at` datetime DEFAULT NULL,\n `deleted_at` int unsigned NOT NULL DEFAULT '0' COMMENT '删除时间戳',\n PRIMARY KEY (`id`) USING BTREE,\n UNIQUE KEY `uniq_type_value_deleted_at` (`type_code`, `value`, `deleted_at`) USING BTREE,\n KEY `idx_type_status_deleted_at_sort` (`type_code`, `status`, `deleted_at`, `sort`) USING BTREE,\n KEY `idx_status_deleted_at` (`status`, `deleted_at`) USING BTREE\n) ENGINE = InnoDB\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_unicode_ci COMMENT ='系统字典项表';\n\nCREATE TABLE IF NOT EXISTS `sys_config_i18n`\n(\n `id` int unsigned NOT NULL AUTO_INCREMENT,\n `config_id` int unsigned NOT NULL DEFAULT '0' COMMENT '系统参数ID',\n `locale` varchar(20) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '语言编码',\n `config_name` varchar(100) NOT NULL DEFAULT '' COMMENT '参数名称',\n `created_at` datetime DEFAULT NULL,\n `updated_at` datetime DEFAULT NULL,\n PRIMARY KEY (`id`) USING BTREE,\n UNIQUE KEY `uniq_config_id_locale` (`config_id`, `locale`) USING BTREE,\n KEY `idx_locale_config_name` (`locale`, `config_name`) USING BTREE\n) ENGINE = InnoDB\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_unicode_ci COMMENT ='系统参数多语言表';\n\nCREATE TABLE IF NOT EXISTS `sys_dict_type_i18n`\n(\n `id` int unsigned NOT NULL AUTO_INCREMENT,\n `dict_type_id` int unsigned NOT NULL DEFAULT '0' COMMENT '字典类型ID',\n `locale` varchar(20) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '语言编码',\n `type_name` varchar(100) NOT NULL DEFAULT '' COMMENT '字典类型名称',\n `created_at` datetime DEFAULT NULL,\n `updated_at` datetime DEFAULT NULL,\n PRIMARY KEY (`id`) USING BTREE,\n UNIQUE KEY `uniq_dict_type_id_locale` (`dict_type_id`, `locale`) USING BTREE,\n KEY `idx_locale_type_name` (`locale`, `type_name`) USING BTREE\n) ENGINE = InnoDB\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_unicode_ci COMMENT ='系统字典类型多语言表';\n\nCREATE TABLE IF NOT EXISTS `sys_dict_item_i18n`\n(\n `id` int unsigned NOT NULL AUTO_INCREMENT,\n `dict_item_id` int unsigned NOT NULL DEFAULT '0' COMMENT '字典项ID',\n `locale` varchar(20) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT '语言编码',\n `label` varchar(100) NOT NULL DEFAULT '' COMMENT '字典标签',\n `created_at` datetime DEFAULT NULL,\n `updated_at` datetime DEFAULT NULL,\n PRIMARY KEY (`id`) USING BTREE,\n UNIQUE KEY `uniq_dict_item_id_locale` (`dict_item_id`, `locale`) USING BTREE,\n KEY `idx_locale_label` (`locale`, `label`) USING BTREE\n) ENGINE = InnoDB\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_unicode_ci COMMENT ='系统字典项多语言表';\n\nCREATE TABLE IF NOT EXISTS `task_definitions`\n(\n `id` int unsigned NOT NULL AUTO_INCREMENT,\n `code` varchar(120) NOT NULL DEFAULT '' COMMENT '任务唯一编码',\n `name` varchar(120) NOT NULL DEFAULT '' COMMENT '任务名称',\n `kind` varchar(20) NOT NULL DEFAULT '' COMMENT '任务类型 async/cron/manual',\n `queue` varchar(60) NOT NULL DEFAULT '' COMMENT '队列名称',\n `cron_spec` varchar(120) NOT NULL DEFAULT '' COMMENT 'Cron 表达式',\n `handler` varchar(255) NOT NULL DEFAULT '' COMMENT '处理器标识',\n `status` tinyint(1) NOT NULL DEFAULT '1' COMMENT '状态 1启用 0停用',\n `allow_manual` tinyint(1) NOT NULL DEFAULT '0' COMMENT '是否允许手动触发 1是 0否',\n `allow_retry` tinyint(1) NOT NULL DEFAULT '1' COMMENT '是否允许手动重试 1是 0否',\n `is_high_risk` tinyint(1) NOT NULL DEFAULT '0' COMMENT '是否高危任务 1是 0否',\n `remark` varchar(255) NOT NULL DEFAULT '' COMMENT '备注',\n `created_at` datetime DEFAULT NULL,\n `updated_at` datetime DEFAULT NULL,\n `deleted_at` int NOT NULL DEFAULT '0' COMMENT '删除时间戳',\n PRIMARY KEY (`id`),\n UNIQUE KEY `td_code_deleted_at` (`code`, `deleted_at`),\n KEY `td_kind_status_deleted_at` (`kind`, `status`, `deleted_at`)\n) ENGINE = InnoDB\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_unicode_ci COMMENT ='任务定义表';\n\nCREATE TABLE IF NOT EXISTS `task_runs`\n(\n `id` bigint unsigned NOT NULL AUTO_INCREMENT,\n `task_code` varchar(120) NOT NULL DEFAULT '' COMMENT '任务唯一编码',\n `kind` varchar(20) NOT NULL DEFAULT '' COMMENT '任务类型 async/cron/manual',\n `source` varchar(20) NOT NULL DEFAULT '' COMMENT '来源 queue/cron/manual',\n `source_id` varchar(120) NOT NULL DEFAULT '' COMMENT '来源任务ID，如 Asynq task id',\n `queue` varchar(60) NOT NULL DEFAULT '' COMMENT '队列名称',\n `trigger_user_id` bigint unsigned NOT NULL DEFAULT '0' COMMENT '触发人ID',\n `trigger_account` varchar(60) NOT NULL DEFAULT '' COMMENT '触发人账号',\n `status` varchar(20) NOT NULL DEFAULT '' COMMENT '执行状态 pending/running/success/failed/canceled/retrying',\n `attempt` int NOT NULL DEFAULT '0' COMMENT '当前尝试次数',\n `max_retry` int NOT NULL DEFAULT '0' COMMENT '最大重试次数',\n `payload` mediumtext DEFAULT NULL COMMENT '任务 payload',\n `error_message` text DEFAULT NULL COMMENT '失败原因',\n `started_at` datetime DEFAULT NULL COMMENT '开始时间',\n `finished_at` datetime DEFAULT NULL COMMENT '结束时间',\n `duration_ms` decimal(10, 4) NOT NULL DEFAULT '0.0000' COMMENT '执行耗时毫秒',\n `created_at` datetime DEFAULT NULL,\n `updated_at` datetime DEFAULT NULL,\n PRIMARY KEY (`id`),\n KEY `tr_task_code_created_at` (`task_code`, `created_at`),\n KEY `tr_status_created_at` (`status`, `created_at`),\n KEY `tr_source_source_id` (`source`, `source_id`),\n KEY `tr_kind_created_at` (`kind`, `created_at`)\n) ENGINE = InnoDB\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_unicode_ci COMMENT ='任务执行记录表';\n\nCREATE TABLE IF NOT EXISTS `task_run_events`\n(\n `id` bigint unsigned NOT NULL AUTO_INCREMENT,\n `run_id` bigint unsigned NOT NULL DEFAULT '0' COMMENT '任务执行记录ID',\n `event_type` varchar(30) NOT NULL DEFAULT '' COMMENT '事件类型 enqueue/start/retry/fail/success/cancel',\n `message` text DEFAULT NULL COMMENT '事件说明',\n `meta` text DEFAULT NULL COMMENT '事件元数据 JSON',\n `created_at` datetime DEFAULT NULL,\n `updated_at` datetime DEFAULT NULL,\n PRIMARY KEY (`id`),\n KEY `tre_run_id_created_at` (`run_id`, `created_at`),\n KEY `tre_event_type_created_at` (`event_type`, `created_at`)\n) ENGINE = InnoDB\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_unicode_ci COMMENT ='任务执行事件表';\n\nCREATE TABLE IF NOT EXISTS `cron_task_states`\n(\n `id` bigint unsigned NOT NULL AUTO_INCREMENT,\n `task_code` varchar(120) NOT NULL DEFAULT '' COMMENT '任务唯一编码',\n `cron_spec` varchar(120) NOT NULL DEFAULT '' COMMENT 'Cron 表达式',\n `last_run_id` bigint unsigned NOT NULL DEFAULT '0' COMMENT '最近执行记录ID',\n `last_status` varchar(20) NOT NULL DEFAULT '' COMMENT '最近执行状态',\n `last_started_at` datetime DEFAULT NULL COMMENT '最近开始时间',\n `last_finished_at` datetime DEFAULT NULL COMMENT '最近结束时间',\n `next_run_at` datetime DEFAULT NULL COMMENT '下次执行时间',\n `last_error` text DEFAULT NULL COMMENT '最近失败原因',\n `created_at` datetime DEFAULT NULL,\n `updated_at` datetime DEFAULT NULL,\n PRIMARY KEY (`id`),\n UNIQUE KEY `cts_task_code` (`task_code`)\n) ENGINE = InnoDB\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_unicode_ci COMMENT ='定时任务最近状态表';\n\nCOMMIT;\n"
},
{
"path": "data/migrations/20260425000002_init_data.down.sql",
"content": "BEGIN;\n\n-- 回滚系统数据\n\n-- 删除任务中心/系统管理新增菜单与映射\nDELETE FROM `role_menu_map` WHERE `menu_id` BETWEEN 42 AND 76;\nDELETE FROM `menu_i18n` WHERE `menu_id` BETWEEN 42 AND 76;\nDELETE FROM `menu` WHERE `id` BETWEEN 42 AND 76;\nDELETE FROM `api_group` WHERE `code` IN ('system', 'sysConfig', 'sysDict', 'task', 'file', 'session');\n\n-- 删除系统参数/字典初始化数据\nDELETE FROM `sys_dict_item_i18n`\nWHERE `dict_item_id` IN (\n SELECT `id`\n FROM `sys_dict_item`\n WHERE `type_code` IN ('common_status', 'yes_no', 'menu_type', 'api_auth_mode', 'http_method', 'task_kind', 'task_source', 'task_run_status')\n AND `deleted_at` = 0\n);\nDELETE FROM `sys_dict_type_i18n`\nWHERE `dict_type_id` IN (\n SELECT `id`\n FROM `sys_dict_type`\n WHERE `type_code` IN ('common_status', 'yes_no', 'menu_type', 'api_auth_mode', 'http_method', 'task_kind', 'task_source', 'task_run_status')\n AND `deleted_at` = 0\n);\nDELETE FROM `sys_config_i18n`\nWHERE `config_id` IN (\n SELECT `id`\n FROM `sys_config`\n WHERE `config_key` IN ('auth.login_lock_enabled', 'auth.login_max_failures', 'auth.login_lock_minutes', 'task.cron_demo_enabled', 'audit.sensitive_fields', 'storage.active_driver', 'storage.config')\n AND `deleted_at` = 0\n);\nDELETE FROM `sys_dict_item`\nWHERE `type_code` IN ('common_status', 'yes_no', 'menu_type', 'api_auth_mode', 'http_method', 'task_kind', 'task_source', 'task_run_status')\n AND `deleted_at` = 0;\nDELETE FROM `sys_dict_type`\nWHERE `type_code` IN ('common_status', 'yes_no', 'menu_type', 'api_auth_mode', 'http_method', 'task_kind', 'task_source', 'task_run_status')\n AND `deleted_at` = 0;\nDELETE FROM `sys_config`\nWHERE `config_key` IN ('auth.login_lock_enabled', 'auth.login_max_failures', 'auth.login_lock_minutes', 'task.cron_demo_enabled', 'audit.sensitive_fields', 'storage.active_driver', 'storage.config')\n AND `deleted_at` = 0;\n\n-- 删除角色菜单映射\nDELETE FROM `role_menu_map` WHERE `role_id` = 1;\n\n-- 删除菜单翻译数据\nDELETE FROM `menu_i18n` WHERE `menu_id` BETWEEN 1 AND 41;\n\n-- 删除菜单数据\nDELETE FROM `menu` WHERE `id` BETWEEN 1 AND 41;\n\n-- 删除权限分组数据\nDELETE FROM `api_group` WHERE `id` BETWEEN 1 AND 9;\n\n-- 删除管理员用户部门/角色映射\nDELETE FROM `admin_user_role_map` WHERE `uid` = 1 AND `role_id` = 1;\nDELETE FROM `admin_user_department_map` WHERE `uid` = 1 AND `dept_id` = 1;\n\n-- 删除默认角色和部门\nDELETE FROM `role` WHERE `id` = 1;\nDELETE FROM `department` WHERE `id` = 1;\n\n-- 删除管理员用户数据\nDELETE FROM `admin_user` WHERE `id` = 1;\n\nCOMMIT;\n"
},
{
"path": "data/migrations/20260425000002_init_data.up.sql",
"content": "BEGIN;\n\n-- 初始化系统数据\n\n-- 初始密码 123456\nINSERT INTO `admin_user` (`id`, `nickname`, `username`, `password`, `phone_number`, `full_phone_number`,\n `country_code`, `email`, `avatar`, `status`,\n `is_super_admin`,\n `created_at`, `updated_at`, `deleted_at`)\nVALUES (1, '超级管理员', 'super_admin', '$2a$10$OuKQoJGH7xkCgwFISmDve.euBDbOCnYEJX6R22QMeLxCLwdoJ4iyi', '18888888888',\n '8618888888888', '86', 'admin@go-layout.com', 'https://avatars.githubusercontent.com/u/48752601?v=4', 1, 1,\n '2023-05-01 00:00:00', '2023-05-01 00:00:00', 0);\n\nINSERT INTO `department` (`id`, `code`, `is_system`, `pid`, `pids`, `name`, `description`, `level`, `sort`,\n `children_num`, `user_number`, `created_at`, `updated_at`, `deleted_at`)\nVALUES (1, 'default_department', 1, 0, '0', '默认部门', '系统默认部门', 1, 100, 0, 1,\n '2023-05-01 00:00:00', '2023-05-01 00:00:00', 0);\n\nINSERT INTO `role` (`id`, `code`, `is_system`, `pid`, `pids`, `name`, `description`, `level`, `sort`, `children_num`,\n `status`, `created_at`, `updated_at`, `deleted_at`)\nVALUES (1, 'super_admin', 1, 0, '0', '超级管理员', '系统默认超级管理员角色', 1, 100, 0, 1,\n '2023-05-01 00:00:00', '2023-05-01 00:00:00', 0);\n\nINSERT INTO `admin_user_department_map` (`uid`, `dept_id`, `is_admin`, `created_at`, `updated_at`)\nVALUES (1, 1, 1, '2023-05-01 00:00:00', '2023-05-01 00:00:00');\n\nINSERT INTO `admin_user_role_map` (`uid`, `role_id`, `created_at`, `updated_at`)\nVALUES (1, 1, '2023-05-01 00:00:00', '2023-05-01 00:00:00');\n\n-- 初始化权限分组数据\nINSERT INTO `api_group` (`id`, `pid`, `code`, `name`, `created_at`, `updated_at`)\nVALUES (1, 0, 'other', '其他', '2025-04-26 18:00:00', '2025-04-26 18:00:00'),\n (2, 0, 'login', '登录模块', '2025-04-26 18:00:00', '2025-04-26 18:00:00'),\n (3, 0, 'auth', '权限模块', '2025-04-26 18:00:00', '2025-04-26 18:00:00'),\n (4, 3, 'adminUser', '管理员模块', '2025-04-26 18:00:00', '2025-04-26 18:00:00'),\n (5, 3, 'api', 'API模块', '2025-04-26 18:00:00', '2025-04-26 18:00:00'),\n (6, 3, 'role', '角色模块', '2025-04-26 18:00:00', '2025-04-26 18:00:00'),\n (7, 3, 'menu', '菜单模块', '2025-04-26 18:00:00', '2025-04-26 18:00:00'),\n (8, 0, 'common', '公共模块', '2025-04-26 18:00:00', '2025-04-26 18:00:00'),\n (9, 0, 'log', '日志模块', '2025-04-26 18:00:00', '2025-04-26 18:00:00');\n\n-- 初始化菜单数据\nINSERT INTO `menu` (`id`, `icon`, `code`, `path`, `full_path`, `redirect`, `name`, `component`, `animate_enter`, `animate_leave`, `animate_duration`, `is_show`, `status`, `is_auth`, `is_external_links`, `is_new_window`, `sort`, `type`, `pid`, `level`, `pids`, `children_num`, `description`, `created_at`, `updated_at`, `deleted_at`) VALUES\n(1, 'ep:menu', '', '', '/', '', 'Home', 'home/index.vue', '', '', 0.00, 1, 1, 0, 0, 0, 100, 2, 0, 1, '0', 0, '', '2024-09-27 13:36:50', '2025-11-15 14:36:40', 0),\n(2, 'ant-design:lock-outlined', '', 'permission', '/permission', 'AdminUserList', 'Permission', '', '', '', 0.00, 1, 1, 1, 0, 0, 99, 1, 0, 1, '0', 0, '', '2025-04-16 15:36:33', '2025-04-22 18:16:25', 0),\n(3, 'ant-design:api-outlined', '', 'list', '/permission/list', '', 'PermissionList', 'permission/api.vue', '', '', 0.00, 1, 1, 1, 0, 0, 100, 2, 2, 2, '0,2', 2, '', '2025-04-16 15:41:54', '2025-11-25 17:23:53', 0),\n(4, 'ant-design:menu-outlined', '', 'menu-list', '/permission/menu-list', '', 'MenuList', 'permission/menuList.vue', '', '', 0.00, 1, 1, 1, 0, 0, 105, 2, 2, 2, '0,2', 5, '', '2025-04-16 15:45:31', '2025-11-25 17:23:44', 0),\n(5, 'lucide:info', '', '/about', '/about', '', 'About', 'about/index.vue', '', '', 0.00, 1, 1, 1, 0, 0, 78, 2, 0, 1, '0', 0, '', '2025-04-16 16:47:58', '2025-04-23 15:01:05', 0),\n(7, 'ep:user', '', 'admin-user-list', '/permission/admin-user-list', '', 'AdminUserList', 'permission/adminUser.vue', '', '', 0.00, 1, 1, 1, 0, 0, 120, 2, 2, 2, '0,2', 5, '', '2025-04-19 11:19:36', '2025-11-25 17:20:23', 0),\n(8, 'ant-design:usergroup-add-outlined', '', 'role-list', '/permission/role-list', '', 'RoleList', 'permission/role.vue', '', '', 0.00, 1, 1, 1, 0, 0, 115, 2, 2, 2, '0,2', 5, '', '2025-04-21 16:51:22', '2025-11-25 17:22:21', 0),\n(9, 'tdesign:tree-square-dot', '', 'department-list', '/permission/department-list', '', 'DepartmentList', 'permission/department.vue', '', '', 0.00, 1, 1, 1, 0, 0, 115, 2, 2, 2, '0,2', 6, '', '2025-04-21 16:51:22', '2025-11-25 17:21:30', 0),\n(10, 'ant-design:edit-filled', 'adminUser:update', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 7, 3, '0,2,7', 0, '', '2025-11-13 16:45:19', '2025-11-18 17:14:25', 0),\n(11, 'ant-design:plus-outlined', 'adminUser:add', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 7, 3, '0,2,7', 0, '', '2025-11-15 10:06:52', '2025-11-18 17:22:41', 0),\n(12, 'ant-design:user-switch-outlined', 'adminUser:bindRole', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 7, 3, '0,2,7', 0, '', '2025-11-15 10:06:52', '2025-11-18 17:20:53', 0),\n(13, 'ant-design:delete-outlined', 'adminUser:delete', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 7, 3, '0,2,7', 0, '', '2025-11-15 10:06:52', '2025-11-18 17:24:34', 0),\n(14, 'ant-design:plus-outlined', 'menu:add', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 4, 3, '0,2,4', 0, '', '2025-11-15 10:06:52', '2025-11-18 17:39:20', 0),\n(15, 'ant-design:plus-circle-outlined', 'menu:addChild', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 4, 3, '0,2,4', 0, '', '2025-11-15 10:06:52', '2025-11-18 17:39:03', 0),\n(16, 'ant-design:edit-filled', 'menu:update', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 4, 3, '0,2,4', 0, '', '2025-11-15 10:06:52', '2025-11-18 17:38:12', 0),\n(17, 'ant-design:delete-outlined', 'menu:delete', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 4, 3, '0,2,4', 0, '', '2025-11-15 10:06:52', '2025-11-18 17:37:02', 0),\n(18, 'ant-design:plus-outlined', 'role:add', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 8, 3, '0,2,8', 0, '', '2025-11-15 10:06:52', '2025-11-18 17:36:08', 0),\n(19, 'ant-design:edit-filled', 'role:update', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 8, 3, '0,2,8', 0, '', '2025-11-15 10:06:52', '2025-11-18 17:36:22', 0),\n(20, 'ant-design:delete-outlined', 'role:delete', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 8, 3, '0,2,8', 0, '', '2025-11-15 10:06:52', '2025-11-18 17:32:12', 0),\n(21, 'ant-design:plus-outlined', 'department:add', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 9, 3, '0,2,9', 0, '', '2025-11-15 10:06:52', '2025-11-18 17:29:43', 0),\n(22, 'ant-design:plus-circle-outlined', 'department:addChild', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 9, 3, '0,2,9', 0, '', '2025-11-15 10:06:52', '2025-11-18 17:29:07', 0),\n(23, 'ant-design:edit-filled', 'department:update', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 9, 3, '0,2,9', 0, '', '2025-11-15 10:06:52', '2025-11-18 17:33:40', 0),\n(24, 'ant-design:user-switch-outlined', 'department:bindRole', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 9, 3, '0,2,9', 0, '', '2025-11-15 10:06:52', '2025-11-18 17:27:57', 0),\n(25, 'ant-design:delete-outlined', 'department:delete', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 9, 3, '0,2,9', 0, '', '2025-11-15 10:06:52', '2025-11-18 17:26:52', 0),\n(26, 'ant-design:edit-filled', 'api:update', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 3, 3, '0,2,3', 0, '', '2025-11-15 10:06:52', '2025-11-18 17:39:39', 0),\n(28, 'ant-design:plus-circle-outlined', 'role:addChild', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 8, 3, '0,2,8', 0, '', '2025-11-17 17:46:21', '2025-11-18 17:41:45', 0),\n(29, 'ep:tickets', '', 'log', '/log', 'RequestLog', 'Log', '', '', '', 0.00, 1, 1, 1, 0, 0, 98, 1, 0, 1, '0', 3, '', '2025-11-20 16:16:47', '2025-11-20 16:17:04', 0),\n(30, 'ep:document', '', 'request-log', '/log/request-log', '', 'RequestLog', 'log/request.vue', '', '', 0.00, 1, 1, 1, 0, 0, 100, 2, 29, 2, '0,29', 4, '', '2025-11-20 16:14:39', '2025-11-25 17:25:13', 0),\n(31, 'ep:document', '', 'admin-login-log', '/log/admin-login-log', '', 'AdminLoginLog', 'log/adminLogin.vue', '', '', 0.00, 1, 1, 1, 0, 0, 100, 2, 29, 2, '0,29', 2, '', '2025-11-20 16:16:47', '2025-11-25 17:24:30', 0),\n(32, 'ep:document', 'adminLoginLog:detail', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 31, 3, '0,29,31', 0, '', '2025-11-22 11:48:10', '2025-11-22 11:48:10', 0),\n(33, 'ep:document', 'requestLog:detail', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 30, 3, '0,29,30', 0, '', '2025-11-22 11:48:44', '2025-11-22 11:48:44', 0),\n(34, 'ant-design:search-outlined', 'adminUser:list', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 7, 3, '0,2,7', 0, '', '2025-11-25 17:20:23', '2025-11-25 17:20:23', 0),\n(35, 'ant-design:search-outlined', 'department:list', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 9, 3, '0,2,9', 0, '', '2025-11-25 17:21:22', '2025-11-25 17:21:22', 0),\n(36, 'ant-design:search-outlined', 'role:list', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 8, 3, '0,2,8', 0, '', '2025-11-25 17:22:13', '2025-11-25 17:22:13', 0),\n(37, 'ant-design:search-outlined', 'menu:list', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 4, 3, '0,2,4', 0, '', '2025-11-25 17:23:02', '2025-11-25 17:23:02', 0),\n(38, 'ant-design:search-outlined', 'api:list', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 3, 3, '0,2,3', 0, '', '2025-11-25 17:23:35', '2025-11-25 17:23:35', 0),\n(39, 'ant-design:search-outlined', 'adminLoginLog:list', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 31, 3, '0,29,31', 0, '', '2025-11-25 17:24:20', '2025-11-25 17:24:20', 0),\n(40, 'ant-design:search-outlined', 'requestLog:list', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 30, 3, '0,29,30', 0, '', '2025-11-25 17:25:04', '2025-11-25 17:25:04', 0),\n(42, 'ep:setting', '', 'system', '/system', 'SysConfig', 'System', '', '', '', 0.00, 1, 1, 1, 0, 0, 96, 1, 0, 1, '0', 3, '', NOW(), NOW(), 0),\n(43, 'ep:operation', '', 'config', '/system/config', '', 'SysConfig', 'system/config.vue', '', '', 0.00, 1, 1, 1, 0, 0, 100, 2, 42, 2, '0,42', 8, '', NOW(), NOW(), 0),\n(44, 'ep:collection-tag', '', 'dict', '/system/dict', '', 'SysDict', 'system/dict.vue', '', '', 0.00, 1, 1, 1, 0, 0, 90, 2, 42, 2, '0,42', 4, '', NOW(), NOW(), 0),\n(45, 'ant-design:search-outlined', 'sysConfig:list', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 43, 3, '0,42,43', 0, '', NOW(), NOW(), 0),\n(46, 'ant-design:plus-outlined', 'sysConfig:add', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 90, 3, 43, 3, '0,42,43', 0, '', NOW(), NOW(), 0),\n(47, 'ant-design:edit-filled', 'sysConfig:update', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 80, 3, 43, 3, '0,42,43', 0, '', NOW(), NOW(), 0),\n(48, 'ant-design:delete-outlined', 'sysConfig:delete', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 70, 3, 43, 3, '0,42,43', 0, '', NOW(), NOW(), 0),\n(49, 'ep:refresh', 'sysConfig:refresh', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 60, 3, 43, 3, '0,42,43', 0, '', NOW(), NOW(), 0),\n(50, 'ant-design:search-outlined', 'sysDict:list', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 44, 3, '0,42,44', 0, '', NOW(), NOW(), 0),\n(51, 'ant-design:plus-outlined', 'sysDict:add', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 90, 3, 44, 3, '0,42,44', 0, '', NOW(), NOW(), 0),\n(52, 'ant-design:edit-filled', 'sysDict:update', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 80, 3, 44, 3, '0,42,44', 0, '', NOW(), NOW(), 0),\n(53, 'ant-design:delete-outlined', 'sysDict:delete', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 70, 3, 44, 3, '0,42,44', 0, '', NOW(), NOW(), 0),\n(54, 'ri:task-line', '', 'task', '/task', 'TaskCenter', 'Task', '', '', '', 0.00, 1, 1, 1, 0, 0, 97, 1, 0, 1, '0', 1, '', NOW(), NOW(), 0),\n(55, 'ri:task-line', '', 'center', '/task/center', '', 'TaskCenter', 'system/task.vue', '', '', 0.00, 1, 1, 1, 0, 0, 100, 2, 54, 2, '0,54', 7, '', NOW(), NOW(), 0),\n(56, 'ant-design:search-outlined', 'task:list', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 55, 3, '0,54,55', 0, '', NOW(), NOW(), 0),\n(57, 'ep:video-play', 'task:trigger', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 90, 3, 55, 3, '0,54,55', 0, '', NOW(), NOW(), 0),\n(58, 'ep:refresh-right', 'task:retry', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 80, 3, 55, 3, '0,54,55', 0, '', NOW(), NOW(), 0),\n(59, 'ep:circle-close', 'task:cancel', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 70, 3, 55, 3, '0,54,55', 0, '', NOW(), NOW(), 0),\n(60, 'ep:view', 'task:detail', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 60, 3, 55, 3, '0,54,55', 0, '', NOW(), NOW(), 0),\n(61, 'ant-design:search-outlined', 'requestLog:export', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 80, 3, 30, 3, '0,29,30', 0, '', NOW(), NOW(), 0),\n(62, 'ep:setting', 'requestLog:maskConfig', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 70, 3, 30, 3, '0,29,30', 0, '', NOW(), NOW(), 0),\n(63, 'ep:folder-opened', '', 'file', '/system/file', '', 'FileResource', 'system/file.vue', '', '', 0.00, 1, 1, 1, 0, 0, 80, 2, 42, 2, '0,42', 2, '', NOW(), NOW(), 0),\n(64, 'ant-design:search-outlined', 'file:list', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 63, 3, '0,42,63', 0, '', NOW(), NOW(), 0),\n(65, 'ant-design:delete-outlined', 'file:delete', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 90, 3, 63, 3, '0,42,63', 0, '', NOW(), NOW(), 0),\n(66, 'ep:monitor', '', 'session', '/log/session', '', 'OnlineSession', 'log/session.vue', '', '', 0.00, 1, 1, 1, 0, 0, 90, 2, 29, 2, '0,29', 2, '', NOW(), NOW(), 0),\n(67, 'ant-design:search-outlined', 'session:list', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 66, 3, '0,29,66', 0, '', NOW(), NOW(), 0),\n(68, 'ep:circle-close', 'session:revoke', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 90, 3, 66, 3, '0,29,66', 0, '', NOW(), NOW(), 0),\n(70, 'ant-design:search-outlined', 'storage:config', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 100, 3, 43, 3, '0,42,43', 0, '', NOW(), NOW(), 0),\n(71, 'ant-design:edit-filled', 'storage:update', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 90, 3, 43, 3, '0,42,43', 0, '', NOW(), NOW(), 0),\n(72, 'ep:connection', 'storage:test', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 80, 3, 43, 3, '0,42,43', 0, '', NOW(), NOW(), 0),\n(73, 'ep:refresh-left', 'file:restore', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 80, 3, 63, 3, '0,42,63', 0, '', NOW(), NOW(), 0),\n(74, 'ant-design:delete-filled', 'file:destroy', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 70, 3, 63, 3, '0,42,63', 0, '', NOW(), NOW(), 0),\n(75, 'ant-design:edit-filled', 'file:update', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 85, 3, 63, 3, '0,42,63', 0, '', NOW(), NOW(), 0),\n(76, 'ant-design:plus-outlined', 'file:create', '', '', '', '', '', '', '', 0.00, 1, 1, 1, 0, 0, 95, 3, 63, 3, '0,42,63', 0, '', NOW(), NOW(), 0);\n\nINSERT INTO `menu_i18n` (`menu_id`, `locale`, `title`, `created_at`, `updated_at`)\nSELECT `id`,\n 'zh-CN',\n CASE `id`\n WHEN 1 THEN '首页'\n WHEN 2 THEN '权限管理'\n WHEN 3 THEN '接口'\n WHEN 4 THEN '菜单'\n WHEN 5 THEN '关于'\n WHEN 7 THEN '管理员'\n WHEN 8 THEN '角色'\n WHEN 9 THEN '部门'\n WHEN 10 THEN '编辑'\n WHEN 11 THEN '新增管理员'\n WHEN 12 THEN '绑定角色'\n WHEN 13 THEN '删除'\n WHEN 14 THEN '新增菜单'\n WHEN 15 THEN '新增下级'\n WHEN 16 THEN '编辑'\n WHEN 17 THEN '删除'\n WHEN 18 THEN '新增角色'\n WHEN 19 THEN '编辑'\n WHEN 20 THEN '删除'\n WHEN 21 THEN '新增部门'\n WHEN 22 THEN '新增'\n WHEN 23 THEN '编辑'\n WHEN 24 THEN '绑定角色'\n WHEN 25 THEN '删除'\n WHEN 26 THEN '编辑'\n WHEN 28 THEN '新增'\n WHEN 29 THEN '日志管理'\n WHEN 30 THEN '请求日志'\n WHEN 31 THEN '管理员登录日志'\n WHEN 32 THEN '详情'\n WHEN 33 THEN '详情'\n WHEN 34 THEN '列表'\n WHEN 35 THEN '列表'\n WHEN 36 THEN '列表'\n WHEN 37 THEN '列表'\n WHEN 38 THEN '列表'\n WHEN 39 THEN '列表'\n WHEN 40 THEN '列表'\n WHEN 42 THEN '系统管理'\n WHEN 43 THEN '系统参数'\n WHEN 44 THEN '字典管理'\n WHEN 45 THEN '列表'\n WHEN 46 THEN '新增'\n WHEN 47 THEN '编辑'\n WHEN 48 THEN '删除'\n WHEN 49 THEN '刷新缓存'\n WHEN 50 THEN '列表'\n WHEN 51 THEN '新增'\n WHEN 52 THEN '编辑'\n WHEN 53 THEN '删除'\n WHEN 54 THEN '任务中心'\n WHEN 55 THEN '任务管理'\n WHEN 56 THEN '列表'\n WHEN 57 THEN '触发任务'\n WHEN 58 THEN '重试任务'\n WHEN 59 THEN '取消任务'\n WHEN 60 THEN '详情'\n WHEN 61 THEN '导出'\n WHEN 62 THEN '脱敏配置'\n WHEN 63 THEN '文件资源'\n WHEN 64 THEN '列表'\n WHEN 65 THEN '删除'\n WHEN 66 THEN '在线会话'\n WHEN 67 THEN '列表'\n WHEN 68 THEN '撤销'\n WHEN 70 THEN '配置'\n WHEN 71 THEN '更新'\n WHEN 72 THEN '测试'\n WHEN 73 THEN '恢复'\n WHEN 74 THEN '硬删除'\n WHEN 75 THEN '编辑'\n WHEN 76 THEN '新增'\n ELSE ''\n END,\n `created_at`,\n `updated_at`\nFROM `menu`\nWHERE `deleted_at` = 0;\n\nINSERT INTO `menu_i18n` (`menu_id`, `locale`, `title`, `created_at`, `updated_at`)\nSELECT `id`,\n 'en-US',\n CASE `id`\n WHEN 1 THEN 'Home'\n WHEN 2 THEN 'Permission'\n WHEN 3 THEN 'API'\n WHEN 4 THEN 'Menu'\n WHEN 5 THEN 'About'\n WHEN 7 THEN 'Administrators'\n WHEN 8 THEN 'Roles'\n WHEN 9 THEN 'Departments'\n WHEN 10 THEN 'Edit'\n WHEN 11 THEN 'Add Administrator'\n WHEN 12 THEN 'Bind Roles'\n WHEN 13 THEN 'Delete'\n WHEN 14 THEN 'Add Menu'\n WHEN 15 THEN 'Add Child'\n WHEN 16 THEN 'Edit'\n WHEN 17 THEN 'Delete'\n WHEN 18 THEN 'Add Role'\n WHEN 19 THEN 'Edit'\n WHEN 20 THEN 'Delete'\n WHEN 21 THEN 'Add Department'\n WHEN 22 THEN 'Add'\n WHEN 23 THEN 'Edit'\n WHEN 24 THEN 'Bind Roles'\n WHEN 25 THEN 'Delete'\n WHEN 26 THEN 'Edit'\n WHEN 28 THEN 'Add'\n WHEN 29 THEN 'Log Management'\n WHEN 30 THEN 'Request Logs'\n WHEN 31 THEN 'Admin Login Logs'\n WHEN 32 THEN 'Detail'\n WHEN 33 THEN 'Detail'\n WHEN 34 THEN 'List'\n WHEN 35 THEN 'List'\n WHEN 36 THEN 'List'\n WHEN 37 THEN 'List'\n WHEN 38 THEN 'List'\n WHEN 39 THEN 'List'\n WHEN 40 THEN 'List'\n WHEN 42 THEN 'System'\n WHEN 43 THEN 'System Config'\n WHEN 44 THEN 'Dictionary'\n WHEN 45 THEN 'List'\n WHEN 46 THEN 'Add'\n WHEN 47 THEN 'Edit'\n WHEN 48 THEN 'Delete'\n WHEN 49 THEN 'Refresh Cache'\n WHEN 50 THEN 'List'\n WHEN 51 THEN 'Add'\n WHEN 52 THEN 'Edit'\n WHEN 53 THEN 'Delete'\n WHEN 54 THEN 'Task Center'\n WHEN 55 THEN 'Task Management'\n WHEN 56 THEN 'List'\n WHEN 57 THEN 'Trigger Task'\n WHEN 58 THEN 'Retry Task'\n WHEN 59 THEN 'Cancel Task'\n WHEN 60 THEN 'Detail'\n WHEN 61 THEN 'Export'\n WHEN 62 THEN 'Mask Config'\n WHEN 63 THEN 'File Resources'\n WHEN 64 THEN 'List'\n WHEN 65 THEN 'Delete'\n WHEN 66 THEN 'Online Sessions'\n WHEN 67 THEN 'List'\n WHEN 68 THEN 'Revoke'\n WHEN 70 THEN 'Config'\n WHEN 71 THEN 'Update'\n WHEN 72 THEN 'Test'\n WHEN 73 THEN 'Restore'\n WHEN 74 THEN 'Destroy'\n WHEN 75 THEN 'Edit'\n WHEN 76 THEN 'Create'\n ELSE ''\n END,\n `created_at`,\n `updated_at`\nFROM `menu`\nWHERE `deleted_at` = 0;\n\nINSERT INTO `role_menu_map` (`role_id`, `menu_id`, `created_at`, `updated_at`)\nSELECT 1, `id`, '2023-05-01 00:00:00', '2023-05-01 00:00:00'\nFROM `menu`\nWHERE `deleted_at` = 0;\n\nINSERT INTO `sys_config` (`config_key`, `config_value`, `value_type`, `group_code`, `is_system`,\n `is_sensitive`, `is_visible`, `manage_tab`, `status`, `sort`, `remark`, `created_at`, `updated_at`, `deleted_at`)\nVALUES ('auth.login_lock_enabled', 'true', 'bool', 'auth', 1, 0, 1, '', 1, 89, '是否开启登录失败锁定', NOW(), NOW(), 0),\n ('auth.login_max_failures', '5', 'number', 'auth', 1, 0, 1, '', 1, 88, '登录连续失败阈值', NOW(), NOW(), 0),\n ('auth.login_lock_minutes', '15', 'number', 'auth', 1, 0, 1, '', 1, 87, '登录锁定时长（分钟）', NOW(), NOW(), 0),\n ('task.cron_demo_enabled', 'false', 'bool', 'task', 1, 0, 1, '', 1, 80, '是否启用演示定时任务，默认关闭', NOW(), NOW(), 0),\n ('audit.sensitive_fields', '{\"common\":[\"password\",\"pwd\",\"passwd\",\"pass\",\"secret\",\"token\",\"access_token\",\"refresh_token\",\"api_key\",\"apikey\",\"apiKey\",\"pin\",\"cvv\",\"cvc\",\"cvv2\",\"security_code\"],\"request_header\":[\"authorization\",\"auth\",\"cookie\",\"x-api-key\",\"x-access-token\",\"x-auth-token\",\"x-token\"],\"request_body\":[\"password\",\"pwd\",\"passwd\",\"pass\",\"secret\",\"token\",\"access_token\",\"refresh_token\",\"api_key\",\"apikey\",\"apiKey\",\"phone\",\"mobile\",\"tel\",\"telephone\",\"phone_number\",\"mobile_number\",\"email\",\"mail\",\"id_card\",\"idcard\",\"identity\",\"id_number\",\"bank_card\",\"bankcard\",\"card_number\",\"card_no\",\"cvv\",\"cvc\",\"cvv2\",\"security_code\",\"pin\",\"ssn\",\"social_security\",\"real_name\",\"realname\",\"name\"],\"response_header\":[\"set-cookie\",\"authorization\",\"auth\",\"x-api-key\",\"x-access-token\",\"x-auth-token\",\"x-token\",\"x-refresh-token\",\"refresh-access-token\",\"refresh-exp\",\"cookie\"],\"response_body\":[\"password\",\"pwd\",\"passwd\",\"pass\",\"secret\",\"token\",\"access_token\",\"refresh_token\",\"api_key\",\"apikey\",\"apiKey\",\"phone\",\"mobile\",\"tel\",\"telephone\",\"phone_number\",\"mobile_number\",\"email\",\"mail\",\"id_card\",\"idcard\",\"identity\",\"id_number\",\"bank_card\",\"bankcard\",\"card_number\",\"card_no\",\"cvv\",\"cvc\",\"cvv2\",\"security_code\",\"pin\",\"ssn\",\"social_security\"]}', 'json', 'audit', 1, 1, 0, 'audit_mask', 1, 95, '请求日志脱敏字段配置', NOW(), NOW(), 0),\n ('storage.active_driver', 'local', 'string', 'storage', 1, 0, 0, 'storage', 1, 90, '当前启用的文件存储驱动', NOW(), NOW(), 0),\n ('storage.config', '{\"local\":{},\"aliyun_oss\":{},\"s3\":{},\"signed_url_ttl_seconds\":300,\"max_file_size_mb\":10,\"allowed_mime_types\":[]}', 'json', 'storage', 1, 1, 0, 'storage', 1, 80, '文件存储配置', NOW(), NOW(), 0)\nON DUPLICATE KEY UPDATE `updated_at` = VALUES(`updated_at`);\n\nINSERT INTO `sys_dict_type` (`type_code`, `is_system`, `status`, `sort`, `remark`, `created_at`,\n `updated_at`, `deleted_at`)\nVALUES ('common_status', 1, 1, 100, '0=禁用,1=启用', NOW(), NOW(), 0),\n ('yes_no', 1, 1, 90, '0=否,1=是', NOW(), NOW(), 0),\n ('menu_type', 1, 1, 80, '1=目录,2=菜单,3=按钮', NOW(), NOW(), 0),\n ('api_auth_mode', 1, 1, 70, '0=无需登录,1=需要登录,2=需要接口权限', NOW(), NOW(), 0),\n ('http_method', 1, 1, 60, '常用 HTTP 方法', NOW(), NOW(), 0),\n ('task_kind', 1, 1, 50, '任务类型', NOW(), NOW(), 0),\n ('task_source', 1, 1, 40, '任务来源', NOW(), NOW(), 0),\n ('task_run_status', 1, 1, 30, '任务执行状态', NOW(), NOW(), 0)\nON DUPLICATE KEY UPDATE `updated_at` = VALUES(`updated_at`);\n\nINSERT INTO `sys_dict_item` (`type_code`, `value`, `color`, `tag_type`, `is_default`, `is_system`, `status`,\n `sort`, `remark`, `created_at`, `updated_at`, `deleted_at`)\nVALUES ('common_status', '0', '#909399', 'info', 0, 1, 1, 10, '', NOW(), NOW(), 0),\n ('common_status', '1', '#67c23a', 'success', 1, 1, 1, 20, '', NOW(), NOW(), 0),\n ('yes_no', '0', '#909399', 'info', 1, 1, 1, 10, '', NOW(), NOW(), 0),\n ('yes_no', '1', '#67c23a', 'success', 0, 1, 1, 20, '', NOW(), NOW(), 0),\n ('menu_type', '1', '#409eff', 'primary', 0, 1, 1, 30, '', NOW(), NOW(), 0),\n ('menu_type', '2', '#67c23a', 'success', 1, 1, 1, 20, '', NOW(), NOW(), 0),\n ('menu_type', '3', '#e6a23c', 'warning', 0, 1, 1, 10, '', NOW(), NOW(), 0),\n ('api_auth_mode', '0', '#909399', 'info', 0, 1, 1, 30, '', NOW(), NOW(), 0),\n ('api_auth_mode', '1', '#409eff', 'primary', 1, 1, 1, 20, '', NOW(), NOW(), 0),\n ('api_auth_mode', '2', '#f56c6c', 'danger', 0, 1, 1, 10, '', NOW(), NOW(), 0),\n ('http_method', 'GET', '#67c23a', 'success', 1, 1, 1, 70, '', NOW(), NOW(), 0),\n ('http_method', 'POST', '#409eff', 'primary', 0, 1, 1, 60, '', NOW(), NOW(), 0),\n ('http_method', 'PUT', '#e6a23c', 'warning', 0, 1, 1, 50, '', NOW(), NOW(), 0),\n ('http_method', 'DELETE', '#f56c6c', 'danger', 0, 1, 1, 40, '', NOW(), NOW(), 0),\n ('http_method', 'PATCH', '#909399', 'info', 0, 1, 1, 30, '', NOW(), NOW(), 0),\n ('http_method', 'OPTIONS', '#909399', 'info', 0, 1, 1, 20, '', NOW(), NOW(), 0),\n ('http_method', 'HEAD', '#909399', 'info', 0, 1, 1, 10, '', NOW(), NOW(), 0),\n ('task_kind', 'async', '#909399', 'info', 1, 1, 1, 20, '', NOW(), NOW(), 0),\n ('task_kind', 'cron', '#e6a23c', 'warning', 0, 1, 1, 10, '', NOW(), NOW(), 0),\n ('task_source', 'queue', '#409eff', 'primary', 1, 1, 1, 30, '', NOW(), NOW(), 0),\n ('task_source', 'cron', '#e6a23c', 'warning', 0, 1, 1, 20, '', NOW(), NOW(), 0),\n ('task_source', 'manual', '#67c23a', 'success', 0, 1, 1, 10, '', NOW(), NOW(), 0),\n ('task_run_status', 'pending', '#909399', 'info', 1, 1, 1, 60, '', NOW(), NOW(), 0),\n ('task_run_status', 'running', '#e6a23c', 'warning', 0, 1, 1, 50, '', NOW(), NOW(), 0),\n ('task_run_status', 'success', '#67c23a', 'success', 0, 1, 1, 40, '', NOW(), NOW(), 0),\n ('task_run_status', 'failed', '#f56c6c', 'danger', 0, 1, 1, 30, '', NOW(), NOW(), 0),\n ('task_run_status', 'canceled', '#909399', 'info', 0, 1, 1, 20, '', NOW(), NOW(), 0),\n ('task_run_status', 'retrying', '#e6a23c', 'warning', 0, 1, 1, 10, '', NOW(), NOW(), 0)\nON DUPLICATE KEY UPDATE `updated_at` = VALUES(`updated_at`);\n\nINSERT INTO `sys_config_i18n` (`config_id`, `locale`, `config_name`, `created_at`, `updated_at`)\nSELECT `id`,\n 'zh-CN',\n CASE\n WHEN `config_key` = 'auth.login_lock_enabled' THEN '登录失败锁定开关'\n WHEN `config_key` = 'auth.login_max_failures' THEN '登录失败锁定阈值'\n WHEN `config_key` = 'auth.login_lock_minutes' THEN '登录失败锁定时长（分钟）'\n WHEN `config_key` = 'task.cron_demo_enabled' THEN '演示定时任务开关'\n WHEN `config_key` = 'audit.sensitive_fields' THEN '请求日志脱敏配置'\n WHEN `config_key` = 'storage.active_driver' THEN '当前存储驱动'\n WHEN `config_key` = 'storage.config' THEN '文件存储配置'\n ELSE ''\n END,\n NOW(),\n NOW()\nFROM `sys_config`\nWHERE `deleted_at` = 0\n AND `config_key` IN ('auth.login_lock_enabled', 'auth.login_max_failures', 'auth.login_lock_minutes', 'task.cron_demo_enabled', 'audit.sensitive_fields', 'storage.active_driver', 'storage.config')\nON DUPLICATE KEY UPDATE `config_name` = VALUES(`config_name`), `updated_at` = VALUES(`updated_at`);\n\nINSERT INTO `sys_config_i18n` (`config_id`, `locale`, `config_name`, `created_at`, `updated_at`)\nSELECT `id`,\n 'en-US',\n CASE\n WHEN `config_key` = 'auth.login_lock_enabled' THEN 'Login Lock Enabled'\n WHEN `config_key` = 'auth.login_max_failures' THEN 'Login Lock Max Failures'\n WHEN `config_key` = 'auth.login_lock_minutes' THEN 'Login Lock Minutes'\n WHEN `config_key` = 'task.cron_demo_enabled' THEN 'Cron Demo Enabled'\n WHEN `config_key` = 'audit.sensitive_fields' THEN 'Request Log Mask Config'\n WHEN `config_key` = 'storage.active_driver' THEN 'Active Storage Driver'\n WHEN `config_key` = 'storage.config' THEN 'File Storage Config'\n ELSE ''\n END,\n NOW(),\n NOW()\nFROM `sys_config`\nWHERE `deleted_at` = 0\n AND `config_key` IN ('auth.login_lock_enabled', 'auth.login_max_failures', 'auth.login_lock_minutes', 'task.cron_demo_enabled', 'audit.sensitive_fields', 'storage.active_driver', 'storage.config')\nON DUPLICATE KEY UPDATE `config_name` = VALUES(`config_name`), `updated_at` = VALUES(`updated_at`);\n\nINSERT INTO `sys_dict_type_i18n` (`dict_type_id`, `locale`, `type_name`, `created_at`, `updated_at`)\nSELECT `id`,\n 'zh-CN',\n CASE\n WHEN `type_code` = 'common_status' THEN '通用状态'\n WHEN `type_code` = 'yes_no' THEN '是否选项'\n WHEN `type_code` = 'menu_type' THEN '菜单类型'\n WHEN `type_code` = 'api_auth_mode' THEN '接口鉴权模式'\n WHEN `type_code` = 'http_method' THEN 'HTTP 方法'\n WHEN `type_code` = 'task_kind' THEN '任务类型'\n WHEN `type_code` = 'task_source' THEN '任务来源'\n WHEN `type_code` = 'task_run_status' THEN '任务执行状态'\n ELSE ''\n END,\n NOW(),\n NOW()\nFROM `sys_dict_type`\nWHERE `deleted_at` = 0\n AND `type_code` IN ('common_status', 'yes_no', 'menu_type', 'api_auth_mode', 'http_method', 'task_kind', 'task_source', 'task_run_status')\nON DUPLICATE KEY UPDATE `type_name` = VALUES(`type_name`), `updated_at` = VALUES(`updated_at`);\n\nINSERT INTO `sys_dict_type_i18n` (`dict_type_id`, `locale`, `type_name`, `created_at`, `updated_at`)\nSELECT `id`,\n 'en-US',\n CASE\n WHEN `type_code` = 'common_status' THEN 'Common Status'\n WHEN `type_code` = 'yes_no' THEN 'Yes/No'\n WHEN `type_code` = 'menu_type' THEN 'Menu Type'\n WHEN `type_code` = 'api_auth_mode' THEN 'API Auth Mode'\n WHEN `type_code` = 'http_method' THEN 'HTTP Method'\n WHEN `type_code` = 'task_kind' THEN 'Task Kind'\n WHEN `type_code` = 'task_source' THEN 'Task Source'\n WHEN `type_code` = 'task_run_status' THEN 'Task Run Status'\n ELSE ''\n END,\n NOW(),\n NOW()\nFROM `sys_dict_type`\nWHERE `deleted_at` = 0\n AND `type_code` IN ('common_status', 'yes_no', 'menu_type', 'api_auth_mode', 'http_method', 'task_kind', 'task_source', 'task_run_status')\nON DUPLICATE KEY UPDATE `type_name` = VALUES(`type_name`), `updated_at` = VALUES(`updated_at`);\n\nINSERT INTO `sys_dict_item_i18n` (`dict_item_id`, `locale`, `label`, `created_at`, `updated_at`)\nSELECT `id`,\n 'zh-CN',\n CASE\n WHEN `type_code` = 'common_status' AND `value` = '0' THEN '禁用'\n WHEN `type_code` = 'common_status' AND `value` = '1' THEN '启用'\n WHEN `type_code` = 'yes_no' AND `value` = '0' THEN '否'\n WHEN `type_code` = 'yes_no' AND `value` = '1' THEN '是'\n WHEN `type_code` = 'menu_type' AND `value` = '1' THEN '目录'\n WHEN `type_code` = 'menu_type' AND `value` = '2' THEN '菜单'\n WHEN `type_code` = 'menu_type' AND `value` = '3' THEN '按钮'\n WHEN `type_code` = 'api_auth_mode' AND `value` = '0' THEN '无需登录'\n WHEN `type_code` = 'api_auth_mode' AND `value` = '1' THEN '需要登录'\n WHEN `type_code` = 'api_auth_mode' AND `value` = '2' THEN '需要接口权限'\n WHEN `type_code` = 'http_method' THEN `value`\n WHEN `type_code` = 'task_kind' AND `value` = 'async' THEN '异步'\n WHEN `type_code` = 'task_kind' AND `value` = 'cron' THEN '定时'\n WHEN `type_code` = 'task_source' AND `value` = 'queue' THEN '队列'\n WHEN `type_code` = 'task_source' AND `value` = 'cron' THEN '定时'\n WHEN `type_code` = 'task_source' AND `value` = 'manual' THEN '手动'\n WHEN `type_code` = 'task_run_status' AND `value` = 'pending' THEN '等待中'\n WHEN `type_code` = 'task_run_status' AND `value` = 'running' THEN '执行中'\n WHEN `type_code` = 'task_run_status' AND `value` = 'success' THEN '成功'\n WHEN `type_code` = 'task_run_status' AND `value` = 'failed' THEN '失败'\n WHEN `type_code` = 'task_run_status' AND `value` = 'canceled' THEN '已取消'\n WHEN `type_code` = 'task_run_status' AND `value` = 'retrying' THEN '重试中'\n ELSE ''\n END,\n NOW(),\n NOW()\nFROM `sys_dict_item`\nWHERE `deleted_at` = 0\n AND (\n (`type_code` = 'common_status' AND `value` IN ('0', '1')) OR\n (`type_code` = 'yes_no' AND `value` IN ('0', '1')) OR\n (`type_code` = 'menu_type' AND `value` IN ('1', '2', '3')) OR\n (`type_code` = 'api_auth_mode' AND `value` IN ('0', '1', '2')) OR\n (`type_code` = 'http_method' AND `value` IN ('GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS', 'HEAD')) OR\n (`type_code` = 'task_kind' AND `value` IN ('async', 'cron')) OR\n (`type_code` = 'task_source' AND `value` IN ('queue', 'cron', 'manual')) OR\n (`type_code` = 'task_run_status' AND `value` IN ('pending', 'running', 'success', 'failed', 'canceled', 'retrying'))\n )\nON DUPLICATE KEY UPDATE `label` = VALUES(`label`), `updated_at` = VALUES(`updated_at`);\n\nINSERT INTO `sys_dict_item_i18n` (`dict_item_id`, `locale`, `label`, `created_at`, `updated_at`)\nSELECT `id`,\n 'en-US',\n CASE\n WHEN `type_code` = 'common_status' AND `value` = '0' THEN 'Disabled'\n WHEN `type_code` = 'common_status' AND `value` = '1' THEN 'Enabled'\n WHEN `type_code` = 'yes_no' AND `value` = '0' THEN 'No'\n WHEN `type_code` = 'yes_no' AND `value` = '1' THEN 'Yes'\n WHEN `type_code` = 'menu_type' AND `value` = '1' THEN 'Directory'\n WHEN `type_code` = 'menu_type' AND `value` = '2' THEN 'Menu'\n WHEN `type_code` = 'menu_type' AND `value` = '3' THEN 'Button'\n WHEN `type_code` = 'api_auth_mode' AND `value` = '0' THEN 'No Auth'\n WHEN `type_code` = 'api_auth_mode' AND `value` = '1' THEN 'Login Required'\n WHEN `type_code` = 'api_auth_mode' AND `value` = '2' THEN 'Permission Required'\n WHEN `type_code` = 'http_method' THEN `value`\n WHEN `type_code` = 'task_kind' AND `value` = 'async' THEN 'Async'\n WHEN `type_code` = 'task_kind' AND `value` = 'cron' THEN 'Cron'\n WHEN `type_code` = 'task_source' AND `value` = 'queue' THEN 'Queue'\n WHEN `type_code` = 'task_source' AND `value` = 'cron' THEN 'Cron'\n WHEN `type_code` = 'task_source' AND `value` = 'manual' THEN 'Manual'\n WHEN `type_code` = 'task_run_status' AND `value` = 'pending' THEN 'Pending'\n WHEN `type_code` = 'task_run_status' AND `value` = 'running' THEN 'Running'\n WHEN `type_code` = 'task_run_status' AND `value` = 'success' THEN 'Success'\n WHEN `type_code` = 'task_run_status' AND `value` = 'failed' THEN 'Failed'\n WHEN `type_code` = 'task_run_status' AND `value` = 'canceled' THEN 'Canceled'\n WHEN `type_code` = 'task_run_status' AND `value` = 'retrying' THEN 'Retrying'\n ELSE ''\n END,\n NOW(),\n NOW()\nFROM `sys_dict_item`\nWHERE `deleted_at` = 0\n AND (\n (`type_code` = 'common_status' AND `value` IN ('0', '1')) OR\n (`type_code` = 'yes_no' AND `value` IN ('0', '1')) OR\n (`type_code` = 'menu_type' AND `value` IN ('1', '2', '3')) OR\n (`type_code` = 'api_auth_mode' AND `value` IN ('0', '1', '2')) OR\n (`type_code` = 'http_method' AND `value` IN ('GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS', 'HEAD')) OR\n (`type_code` = 'task_kind' AND `value` IN ('async', 'cron')) OR\n (`type_code` = 'task_source' AND `value` IN ('queue', 'cron', 'manual')) OR\n (`type_code` = 'task_run_status' AND `value` IN ('pending', 'running', 'success', 'failed', 'canceled', 'retrying'))\n )\nON DUPLICATE KEY UPDATE `label` = VALUES(`label`), `updated_at` = VALUES(`updated_at`);\n\nINSERT INTO `api_group` (`id`, `pid`, `code`, `name`, `created_at`, `updated_at`)\nVALUES (10, 0, 'system', '系统管理模块', NOW(), NOW()),\n (11, 10, 'sysConfig', '系统参数模块', NOW(), NOW()),\n (12, 10, 'sysDict', '系统字典模块', NOW(), NOW()),\n (13, 0, 'task', '任务中心模块', NOW(), NOW()),\n (14, 10, 'file', '文件资源模块', NOW(), NOW()),\n (15, 3, 'session', '在线会话模块', NOW(), NOW())\nON DUPLICATE KEY UPDATE `name` = VALUES(`name`), `updated_at` = VALUES(`updated_at`);\n\nCOMMIT;\n"
},
{
"path": "data/migrations/20260515010000_upload_file_objects.down.sql",
"content": "ALTER TABLE `upload_files`\n DROP KEY `idx_file_object_id`,\n DROP COLUMN `file_object_id`;\n\nDROP TABLE IF EXISTS `upload_file_objects`;\n"
},
{
"path": "data/migrations/20260515010000_upload_file_objects.up.sql",
"content": "CREATE TABLE IF NOT EXISTS `upload_file_objects`\n(\n `id` int unsigned NOT NULL AUTO_INCREMENT,\n `storage_driver` varchar(20) NOT NULL DEFAULT 'local' COMMENT '存储驱动:local,aliyun_oss,s3',\n `storage_base` varchar(512) NOT NULL DEFAULT '' COMMENT '存储基础位置',\n `bucket` varchar(128) NOT NULL DEFAULT '' COMMENT '存储桶',\n `storage_path` varchar(512) NOT NULL DEFAULT '' COMMENT '实际存储路径',\n `object_key` varchar(512) NOT NULL DEFAULT '' COMMENT '对象key',\n `size` int unsigned NOT NULL DEFAULT '0' COMMENT '文件大小（字节）',\n `hash` varchar(64) NOT NULL DEFAULT '' COMMENT '文件SHA256哈希值',\n `mime_type` varchar(100) NOT NULL DEFAULT '' COMMENT 'MIME类型',\n `etag` varchar(128) NOT NULL DEFAULT '' COMMENT '对象ETag',\n `status` varchar(32) NOT NULL DEFAULT 'stored' COMMENT '物理对象状态:stored,delete_failed',\n `created_at` datetime DEFAULT NULL COMMENT '创建时间',\n `updated_at` datetime DEFAULT NULL COMMENT '更新时间',\n PRIMARY KEY (`id`),\n UNIQUE KEY `uniq_driver_bucket_hash` (`storage_driver`, `bucket`, `hash`),\n KEY `idx_local_hash` (`storage_driver`, `hash`),\n KEY `idx_remote_bucket_hash` (`storage_driver`, `bucket`, `hash`),\n KEY `idx_status` (`status`)\n) ENGINE = InnoDB\n DEFAULT CHARSET = utf8mb4\n COLLATE = utf8mb4_unicode_ci COMMENT ='上传文件物理对象表';\n\nALTER TABLE `upload_files`\n ADD COLUMN `file_object_id` int unsigned NOT NULL DEFAULT '0' COMMENT '物理对象ID' AFTER `id`,\n ADD KEY `idx_file_object_id` (`file_object_id`);\n"
},
{
"path": "data/mysql.go",
"content": "package data\n\nimport (\n\t\"context\"\n\t\"database/sql\"\n\t\"errors\"\n\t\"fmt\"\n\t\"net/url\"\n\t\"strings\"\n\t\"sync\"\n\t\"sync/atomic\"\n\t\"time\"\n\n\t\"gorm.io/driver/mysql\"\n\t\"gorm.io/gorm\"\n\t\"gorm.io/gorm/logger\"\n\t\"gorm.io/gorm/schema\"\n\n\tc \"github.com/wannanbigpig/gin-layout/config\"\n\tlog \"github.com/wannanbigpig/gin-layout/internal/pkg/logger\"\n\t\"go.uber.org/zap\"\n)\n\nvar (\n\tmysqlDB *gorm.DB\n\tmysqlOnce sync.Once\n\tmysqlInitError error\n\tmysqlValue atomic.Value\n\tmysqlMu sync.Mutex\n\tmysqlHealth = newRuntimeHealthCache(defaultRuntimeHealthTTL)\n)\n\ntype mysqlSlot struct {\n\tdb *gorm.DB\n}\n\nconst mysqlProbeTimeout = 2 * time.Second\n\nvar mysqlRuntimeProbe = func(db *gorm.DB) error {\n\tsqlDB := getSQLDB(db)\n\tif sqlDB == nil {\n\t\treturn errors.New(\"mysql sql.DB is unavailable\")\n\t}\n\tctx, cancel := context.WithTimeout(context.Background(), mysqlProbeTimeout)\n\tdefer cancel()\n\treturn sqlDB.PingContext(ctx)\n}\n\n// Writer 定义 GORM 自定义日志写入接口。\ntype Writer interface {\n\tPrintf(string, ...interface{})\n}\n\n// WriterLog 将 GORM SQL 日志转发到项目日志组件。\ntype WriterLog struct{}\n\n// Printf 实现 GORM logger.Writer 接口。\nfunc (w WriterLog) Printf(format string, args ...interface{}) {\n\tif c.GetConfig().Mysql.PrintSql {\n\t\tlog.Logger.Sugar().Infof(format, args...)\n\t}\n}\n\n// GenerateDSN 生成带固定连接参数的 MySQL DSN。\nfunc GenerateDSN(cfg *c.Conf) string {\n\t// 防御性编码\n\tif cfg == nil || cfg.Mysql.Host == \"\" || cfg.Mysql.Database == \"\" {\n\t\treturn \"\"\n\t}\n\n\t// 特殊字符处理\n\tusername := strings.Replace(url.QueryEscape(cfg.Mysql.Username), \"%\", \"%25\", -1)\n\tpassword := strings.Replace(url.QueryEscape(cfg.Mysql.Password), \"%\", \"%25\", -1)\n\n\t// IPv6处理\n\thost := cfg.Mysql.Host\n\tif strings.Contains(host, \":\") && !strings.HasPrefix(host, \"[\") {\n\t\thost = \"[\" + host + \"]\"\n\t}\n\n\t// 强制关键参数\n\tcharset := \"utf8mb4\"\n\tdsn := fmt.Sprintf(\"%s:%s@tcp(%s:%d)/%s\",\n\t\tusername,\n\t\tpassword,\n\t\thost,\n\t\tcfg.Mysql.Port,\n\t\tcfg.Mysql.Database,\n\t)\n\n\t// 参数显式排序\n\tparams := url.Values{\n\t\t\"charset\": []string{charset},\n\t\t\"parseTime\": []string{\"true\"},\n\t\t\"loc\": []string{\"Local\"},\n\t\t\"timeout\": []string{\"5s\"},\n\t\t\"readTimeout\": []string{\"30s\"},\n\t\t\"writeTimeout\": []string{\"60s\"},\n\t}\n\n\treturn dsn + \"?\" + params.Encode()\n}\n\n// initMysql 初始化当前配置下的 MySQL 连接。\nfunc initMysql() error {\n\treturn reloadMysql(c.GetConfig())\n}\n\nfunc reloadMysql(cfg *c.Conf) error {\n\tmysqlMu.Lock()\n\tdefer mysqlMu.Unlock()\n\n\tnext, err := openMysql(cfg)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\told := currentMysql()\n\toldSQLDB := getSQLDB(old)\n\tmysqlDB = next\n\tmysqlValue.Store(mysqlSlot{db: next})\n\tmysqlInitError = nil\n\tif next != nil {\n\t\tmysqlHealth.SeedReady()\n\t} else {\n\t\tmysqlHealth.Reset()\n\t}\n\tif oldSQLDB != nil {\n\t\tif err := oldSQLDB.Close(); err != nil {\n\t\t\tlog.Logger.Warn(\"关闭旧 MySQL 连接池失败\", zap.Error(err))\n\t\t}\n\t}\n\treturn nil\n}\n\nfunc openMysql(cfg *c.Conf) (*gorm.DB, error) {\n\tif cfg == nil || !cfg.Mysql.Enable {\n\t\treturn nil, nil\n\t}\n\t// Validate configuration parameters\n\tif cfg.Mysql.MaxIdleConns < 0 || cfg.Mysql.MaxOpenConns < 0 || cfg.Mysql.MaxLifetime < 0 {\n\t\treturn nil, fmt.Errorf(\"invalid MySQL configuration: MaxIdleConns, MaxOpenConns, and MaxLifetime must be non-negative\")\n\t}\n\n\t// Initialize logger\n\tlogConfig := logger.New(\n\t\tWriterLog{},\n\t\tlogger.Config{\n\t\t\tSlowThreshold: 0,\n\t\t\tLogLevel: logger.LogLevel(cfg.Mysql.LogLevel),\n\t\t\tIgnoreRecordNotFoundError: false,\n\t\t\tColorful: false,\n\t\t},\n\t)\n\n\t// Configure GORM settings\n\tconfigs := &gorm.Config{\n\t\tNamingStrategy: schema.NamingStrategy{\n\t\t\tTablePrefix: cfg.Mysql.TablePrefix,\n\t\t},\n\t\tLogger: logConfig,\n\t\tSkipDefaultTransaction: true,\n\t}\n\n\t// Open database connection\n\tdsn := GenerateDSN(cfg)\n\tdb, err := gorm.Open(mysql.Open(dsn), configs)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to connect to MySQL: %s\", err.Error())\n\t}\n\n\t// Get underlying sql.DB and configure connection pool\n\tsqlDB, err := db.DB()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to get sql.DB: %s\", err.Error())\n\t}\n\n\tsqlDB.SetMaxIdleConns(cfg.Mysql.MaxIdleConns)\n\tsqlDB.SetMaxOpenConns(cfg.Mysql.MaxOpenConns)\n\tsqlDB.SetConnMaxLifetime(cfg.Mysql.MaxLifetime)\n\tif err := sqlDB.Ping(); err != nil {\n\t\t_ = sqlDB.Close()\n\t\treturn nil, fmt.Errorf(\"failed to ping MySQL: %s\", err.Error())\n\t}\n\n\treturn db, nil\n}\n\n// MysqlDB 返回当前生效的 MySQL 连接实例。\nfunc MysqlDB() *gorm.DB {\n\tif db := currentMysql(); db != nil {\n\t\treturn db\n\t}\n\tif mysqlDB == nil {\n\t\tmysqlOnce.Do(func() {\n\t\t\tmysqlInitError = initMysql()\n\t\t})\n\t}\n\treturn currentMysql()\n}\n\n// MysqlInitError 返回 MySQL 初始化阶段记录的错误。\nfunc MysqlInitError() error {\n\treturn mysqlInitError\n}\n\n// MysqlRuntimeStatus 返回带缓存的 MySQL 运行时健康探测结果。\nfunc MysqlRuntimeStatus() RuntimeHealthStatus {\n\tdb := MysqlDB()\n\tif db == nil {\n\t\tmysqlHealth.Reset()\n\t\treturn RuntimeHealthStatus{\n\t\t\tReady: false,\n\t\t\tError: mysqlUnavailableError(),\n\t\t\tCheckedAt: time.Now(),\n\t\t}\n\t}\n\tstatus := mysqlHealth.Check(func() error {\n\t\treturn mysqlRuntimeProbe(db)\n\t})\n\tif !status.Ready && status.Error == nil {\n\t\tstatus.Error = mysqlUnavailableError()\n\t}\n\treturn status\n}\n\n// MysqlReady 判断 MySQL 当前是否可用。\nfunc MysqlReady() bool {\n\treturn MysqlRuntimeStatus().Ready\n}\n\n// ReloadMysql 重新加载 MySQL 连接。\nfunc ReloadMysql(cfg *c.Conf) error {\n\treturn reloadMysql(cfg)\n}\n\n// CloseMysql 关闭当前 MySQL 连接池。\nfunc CloseMysql() error {\n\tmysqlMu.Lock()\n\tdefer mysqlMu.Unlock()\n\n\tcurrent := currentMysql()\n\tmysqlDB = nil\n\tmysqlValue.Store(mysqlSlot{})\n\tmysqlInitError = nil\n\tmysqlHealth.Reset()\n\tif current == nil {\n\t\treturn nil\n\t}\n\n\tsqlDB := getSQLDB(current)\n\tif sqlDB == nil {\n\t\treturn nil\n\t}\n\treturn sqlDB.Close()\n}\n\nfunc currentMysql() *gorm.DB {\n\tif slot, ok := mysqlValue.Load().(mysqlSlot); ok {\n\t\treturn slot.db\n\t}\n\treturn mysqlDB\n}\n\nfunc getSQLDB(db *gorm.DB) *sql.DB {\n\tif db == nil {\n\t\treturn nil\n\t}\n\tsqlDB, err := db.DB()\n\tif err != nil {\n\t\treturn nil\n\t}\n\treturn sqlDB\n}\n\nfunc mysqlUnavailableError() error {\n\tif mysqlInitError != nil {\n\t\treturn mysqlInitError\n\t}\n\treturn ErrDBUnavailable\n}\n\n// ErrDBUnavailable 表示 MySQL 连接当前不可用。\nvar ErrDBUnavailable = errors.New(\"mysql connection is unavailable\")\n"
},
{
"path": "data/redis.go",
"content": "package data\n\nimport (\n\t\"context\"\n\t\"errors\"\n\t\"sync\"\n\t\"sync/atomic\"\n\t\"time\"\n\n\t\"github.com/redis/go-redis/v9\"\n\n\tc \"github.com/wannanbigpig/gin-layout/config\"\n)\n\nvar (\n\tredisDb *redis.Client\n\tredisOnce sync.Once\n\tredisInitError error\n\tredisValue atomic.Value\n\tredisMu sync.Mutex\n\tredisHealth = newRuntimeHealthCache(defaultRuntimeHealthTTL)\n)\n\ntype redisSlot struct {\n\tclient *redis.Client\n}\n\nconst redisProbeTimeout = 2 * time.Second\n\nvar redisRuntimeProbe = func(client *redis.Client) error {\n\tctx, cancel := context.WithTimeout(context.Background(), redisProbeTimeout)\n\tdefer cancel()\n\treturn client.Ping(ctx).Err()\n}\n\nfunc initRedis() error {\n\treturn reloadRedis(c.GetConfig())\n}\n\nfunc reloadRedis(cfg *c.Conf) error {\n\tredisMu.Lock()\n\tdefer redisMu.Unlock()\n\n\tnext, err := openRedis(cfg)\n\tif err != nil {\n\t\treturn err\n\t}\n\told := currentRedis()\n\tredisDb = next\n\tredisValue.Store(redisSlot{client: next})\n\tredisInitError = nil\n\tif next != nil {\n\t\tredisHealth.SeedReady()\n\t} else {\n\t\tredisHealth.Reset()\n\t}\n\tif old != nil {\n\t\t_ = old.Close()\n\t}\n\treturn nil\n}\n\nfunc openRedis(cfg *c.Conf) (*redis.Client, error) {\n\tif cfg == nil || !cfg.Redis.Enable {\n\t\treturn nil, nil\n\t}\n\tctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)\n\tdefer cancel()\n\n\topts := &redis.Options{\n\t\tAddr: cfg.Redis.Host + \":\" + cfg.Redis.Port,\n\t\tPassword: cfg.Redis.Password,\n\t\tDB: cfg.Redis.Database,\n\t\tPoolSize: cfg.Redis.PoolSize,\n\t\tMinIdleConns: cfg.Redis.MinIdleConns,\n\t\tConnMaxLifetime: cfg.Redis.ConnMaxLifetime,\n\t\tConnMaxIdleTime: cfg.Redis.ConnMaxIdle,\n\t\tReadTimeout: cfg.Redis.ReadTimeout,\n\t\tWriteTimeout: cfg.Redis.WriteTimeout,\n\t}\n\n\tclient := redis.NewClient(opts)\n\n\t_, err := client.Ping(ctx).Result()\n\tif err != nil {\n\t\t_ = client.Close()\n\t\treturn nil, err\n\t}\n\treturn client, nil\n}\n\n// RedisClient 返回 Redis 客户端和初始化错误\nfunc RedisClient() *redis.Client {\n\tif client := currentRedis(); client != nil {\n\t\treturn client\n\t}\n\tif redisDb == nil {\n\t\tredisOnce.Do(func() {\n\t\t\tredisInitError = initRedis()\n\t\t})\n\t}\n\treturn currentRedis()\n}\n\n// GetRedisInitError 返回 Redis 初始化错误，供外部检查\nfunc GetRedisInitError() error {\n\treturn redisInitError\n}\n\n// RedisRuntimeStatus 返回带缓存的 Redis 运行时健康探测结果。\nfunc RedisRuntimeStatus() RuntimeHealthStatus {\n\tclient := RedisClient()\n\tif client == nil {\n\t\tredisHealth.Reset()\n\t\treturn RuntimeHealthStatus{\n\t\t\tReady: false,\n\t\t\tError: redisUnavailableError(),\n\t\t\tCheckedAt: time.Now(),\n\t\t}\n\t}\n\tstatus := redisHealth.Check(func() error {\n\t\treturn redisRuntimeProbe(client)\n\t})\n\tif !status.Ready && status.Error == nil {\n\t\tstatus.Error = redisUnavailableError()\n\t}\n\treturn status\n}\n\n// RedisReady 判断 Redis 当前是否可用。\nfunc RedisReady() bool {\n\treturn RedisRuntimeStatus().Ready\n}\n\n// ReloadRedis 重新加载 Redis 客户端。\nfunc ReloadRedis(cfg *c.Conf) error {\n\treturn reloadRedis(cfg)\n}\n\n// CloseRedis 关闭当前 Redis 客户端。\nfunc CloseRedis() error {\n\tredisMu.Lock()\n\tdefer redisMu.Unlock()\n\n\tcurrent := currentRedis()\n\tredisDb = nil\n\tredisValue.Store(redisSlot{})\n\tredisInitError = nil\n\tredisHealth.Reset()\n\tif current == nil {\n\t\treturn nil\n\t}\n\treturn current.Close()\n}\n\nfunc currentRedis() *redis.Client {\n\tif slot, ok := redisValue.Load().(redisSlot); ok {\n\t\treturn slot.client\n\t}\n\treturn redisDb\n}\n\nfunc redisUnavailableError() error {\n\tif redisInitError != nil {\n\t\treturn redisInitError\n\t}\n\treturn ErrRedisUnavailable\n}\n\n// ErrRedisUnavailable 表示 Redis 客户端当前不可用。\nvar ErrRedisUnavailable = errors.New(\"redis client is unavailable\")\n"
},
{
"path": "data/runtime_health.go",
"content": "package data\n\nimport (\n\t\"sync\"\n\t\"time\"\n)\n\nconst defaultRuntimeHealthTTL = 3 * time.Second\n\n// RuntimeHealthStatus 表示依赖最近一次运行时探测结果。\ntype RuntimeHealthStatus struct {\n\tReady bool\n\tError error\n\tCheckedAt time.Time\n}\n\ntype runtimeHealthCache struct {\n\tttl time.Duration\n\tmu sync.Mutex\n\tstatus RuntimeHealthStatus\n}\n\nfunc newRuntimeHealthCache(ttl time.Duration) *runtimeHealthCache {\n\tif ttl <= 0 {\n\t\tttl = defaultRuntimeHealthTTL\n\t}\n\treturn &runtimeHealthCache{ttl: ttl}\n}\n\nfunc (c *runtimeHealthCache) Check(probe func() error) RuntimeHealthStatus {\n\tnow := time.Now()\n\n\tc.mu.Lock()\n\tdefer c.mu.Unlock()\n\n\tif !c.status.CheckedAt.IsZero() && now.Sub(c.status.CheckedAt) < c.ttl {\n\t\treturn c.status\n\t}\n\n\terr := probe()\n\tc.status = RuntimeHealthStatus{\n\t\tReady: err == nil,\n\t\tError: err,\n\t\tCheckedAt: now,\n\t}\n\treturn c.status\n}\n\nfunc (c *runtimeHealthCache) SeedReady() {\n\tc.mu.Lock()\n\tdefer c.mu.Unlock()\n\tc.status = RuntimeHealthStatus{\n\t\tReady: true,\n\t\tCheckedAt: time.Now(),\n\t}\n}\n\nfunc (c *runtimeHealthCache) Reset() {\n\tc.mu.Lock()\n\tdefer c.mu.Unlock()\n\tc.status = RuntimeHealthStatus{}\n}\n"
},
{
"path": "data/runtime_health_test.go",
"content": "package data\n\nimport (\n\t\"errors\"\n\t\"testing\"\n\t\"time\"\n\n\t\"github.com/redis/go-redis/v9\"\n\t\"gorm.io/driver/sqlite\"\n\t\"gorm.io/gorm\"\n)\n\nfunc TestMysqlRuntimeStatusCachesProbeResult(t *testing.T) {\n\tdb, err := gorm.Open(sqlite.Open(\"file::memory:?cache=shared\"), &gorm.Config{})\n\tif err != nil {\n\t\tt.Fatalf(\"open sqlite failed: %v\", err)\n\t}\n\n\trestore := backupMysqlState()\n\tdefer restore()\n\n\tmysqlDB = db\n\tmysqlValue.Store(mysqlSlot{db: db})\n\tmysqlInitError = nil\n\tmysqlHealth = newRuntimeHealthCache(time.Hour)\n\n\tprobeCount := 0\n\toriginalProbe := mysqlRuntimeProbe\n\tmysqlRuntimeProbe = func(current *gorm.DB) error {\n\t\tif current != db {\n\t\t\tt.Fatalf(\"unexpected db pointer\")\n\t\t}\n\t\tprobeCount++\n\t\treturn nil\n\t}\n\tdefer func() {\n\t\tmysqlRuntimeProbe = originalProbe\n\t}()\n\n\tstatus1 := MysqlRuntimeStatus()\n\tstatus2 := MysqlRuntimeStatus()\n\n\tif !status1.Ready || !status2.Ready {\n\t\tt.Fatalf(\"expected mysql runtime status to stay ready, got %+v %+v\", status1, status2)\n\t}\n\tif probeCount != 1 {\n\t\tt.Fatalf(\"expected mysql probe to run once, got %d\", probeCount)\n\t}\n}\n\nfunc TestMysqlRuntimeStatusReturnsProbeFailure(t *testing.T) {\n\tdb, err := gorm.Open(sqlite.Open(\"file::memory:?cache=shared\"), &gorm.Config{})\n\tif err != nil {\n\t\tt.Fatalf(\"open sqlite failed: %v\", err)\n\t}\n\n\trestore := backupMysqlState()\n\tdefer restore()\n\n\tmysqlDB = db\n\tmysqlValue.Store(mysqlSlot{db: db})\n\tmysqlInitError = nil\n\tmysqlHealth = newRuntimeHealthCache(time.Hour)\n\n\twantErr := errors.New(\"mysql down\")\n\toriginalProbe := mysqlRuntimeProbe\n\tmysqlRuntimeProbe = func(*gorm.DB) error { return wantErr }\n\tdefer func() {\n\t\tmysqlRuntimeProbe = originalProbe\n\t}()\n\n\tstatus := MysqlRuntimeStatus()\n\tif status.Ready {\n\t\tt.Fatal(\"expected mysql runtime status to be not ready\")\n\t}\n\tif !errors.Is(status.Error, wantErr) {\n\t\tt.Fatalf(\"expected error %v, got %v\", wantErr, status.Error)\n\t}\n\tif MysqlReady() {\n\t\tt.Fatal(\"expected MysqlReady to be false\")\n\t}\n}\n\nfunc TestRedisRuntimeStatusCachesProbeResult(t *testing.T) {\n\tclient := redis.NewClient(&redis.Options{Addr: \"127.0.0.1:0\"})\n\tdefer client.Close()\n\n\trestore := backupRedisState()\n\tdefer restore()\n\n\tredisDb = client\n\tredisValue.Store(redisSlot{client: client})\n\tredisInitError = nil\n\tredisHealth = newRuntimeHealthCache(time.Hour)\n\n\tprobeCount := 0\n\toriginalProbe := redisRuntimeProbe\n\tredisRuntimeProbe = func(current *redis.Client) error {\n\t\tif current != client {\n\t\t\tt.Fatalf(\"unexpected redis client pointer\")\n\t\t}\n\t\tprobeCount++\n\t\treturn nil\n\t}\n\tdefer func() {\n\t\tredisRuntimeProbe = originalProbe\n\t}()\n\n\tstatus1 := RedisRuntimeStatus()\n\tstatus2 := RedisRuntimeStatus()\n\n\tif !status1.Ready || !status2.Ready {\n\t\tt.Fatalf(\"expected redis runtime status to stay ready, got %+v %+v\", status1, status2)\n\t}\n\tif probeCount != 1 {\n\t\tt.Fatalf(\"expected redis probe to run once, got %d\", probeCount)\n\t}\n}\n\nfunc TestRedisRuntimeStatusReturnsProbeFailure(t *testing.T) {\n\tclient := redis.NewClient(&redis.Options{Addr: \"127.0.0.1:0\"})\n\tdefer client.Close()\n\n\trestore := backupRedisState()\n\tdefer restore()\n\n\tredisDb = client\n\tredisValue.Store(redisSlot{client: client})\n\tredisInitError = nil\n\tredisHealth = newRuntimeHealthCache(time.Hour)\n\n\twantErr := errors.New(\"redis down\")\n\toriginalProbe := redisRuntimeProbe\n\tredisRuntimeProbe = func(*redis.Client) error { return wantErr }\n\tdefer func() {\n\t\tredisRuntimeProbe = originalProbe\n\t}()\n\n\tstatus := RedisRuntimeStatus()\n\tif status.Ready {\n\t\tt.Fatal(\"expected redis runtime status to be not ready\")\n\t}\n\tif !errors.Is(status.Error, wantErr) {\n\t\tt.Fatalf(\"expected error %v, got %v\", wantErr, status.Error)\n\t}\n\tif RedisReady() {\n\t\tt.Fatal(\"expected RedisReady to be false\")\n\t}\n}\n\nfunc backupMysqlState() func() {\n\tpreviousDB := mysqlDB\n\tpreviousInitErr := mysqlInitError\n\tpreviousHealth := mysqlHealth\n\tvar previousSlot mysqlSlot\n\tif slot, ok := mysqlValue.Load().(mysqlSlot); ok {\n\t\tpreviousSlot = slot\n\t}\n\treturn func() {\n\t\tmysqlDB = previousDB\n\t\tmysqlInitError = previousInitErr\n\t\tmysqlHealth = previousHealth\n\t\tmysqlValue.Store(previousSlot)\n\t}\n}\n\nfunc backupRedisState() func() {\n\tpreviousClient := redisDb\n\tpreviousInitErr := redisInitError\n\tpreviousHealth := redisHealth\n\tvar previousSlot redisSlot\n\tif slot, ok := redisValue.Load().(redisSlot); ok {\n\t\tpreviousSlot = slot\n\t}\n\treturn func() {\n\t\tredisDb = previousClient\n\t\tredisInitError = previousInitErr\n\t\tredisHealth = previousHealth\n\t\tredisValue.Store(previousSlot)\n\t}\n}\n"
},
{
"path": "docs/COMMANDS_AND_TASKS.en.md",
"content": "# Commands, Scheduled Jobs, and Queue Usage\n\nThis document covers:\n\n- Available project commands and what they do\n- How to start `service`, `worker`, and `cron`\n- How to add scheduled jobs\n- How to create, publish, and consume async queue jobs\n- How to send jobs to a specific queue and configure multiple queues\n\nFor system config and dictionary boundaries, see [docs/SYSTEM_CONFIG_AND_DICT_GUIDELINES.en.md](/Users/liuml/data/go/src/go-layout/docs/SYSTEM_CONFIG_AND_DICT_GUIDELINES.en.md).\n\nIf you are new to the project, start with \"Runtime Model\" and \"Commands\", then move to \"Scheduled Jobs\" and \"Queue Usage\".\n\n## Runtime Model\n\nThe project currently splits runtime responsibilities into 3 process types:\n\n- `service`\n - serves the HTTP API\n - handles login, permissions, menus, uploads, logs, and business requests\n - can publish async jobs in some flows\n\n- `worker`\n - consumes async jobs\n - currently handles async request-audit persistence\n\n- `cron`\n - handles recurring schedules\n - currently uses `robfig/cron`\n - fits fixed-time tasks such as \"run every day at 2 AM\"\n\nIn short:\n\n- `service` serves requests\n- `worker` consumes jobs\n- `cron` triggers recurring tasks\n\n## Commands\n\nThe root command entry is in [cmd/root.go](/Users/liuml/data/go/src/go-layout/cmd/root.go).\n\n### 0. Migration Commands\n\nCommon entry points:\n\n```bash\ngo run main.go -c ./config.yaml command migrate check\ngo run main.go -c ./config.yaml command migrate up\n```\n\nSee [docs/MIGRATE_COMMANDS.en.md](/Users/liuml/data/go/src/go-layout/docs/MIGRATE_COMMANDS.en.md) for full details.\n\n### 1. Show Help\n\n```bash\ngo run main.go -h\ngo run main.go command -h\n```\n\n### 2. Start the API Service\n\n```bash\ngo run main.go service\n```\n\nUsed for:\n\n- starting the Gin HTTP server\n- loading config, logger, database, and other base resources\n- serving business APIs\n\nCommon scenarios:\n\n- local development\n- single-node API deployment\n- main application process in a container\n\n### 3. Start the Async Worker\n\n```bash\ngo run main.go worker\n```\n\nEntry file:\n\n- [cmd/worker/worker.go](/Users/liuml/data/go/src/go-layout/cmd/worker/worker.go)\n\nUsed for:\n\n- connecting to Redis\n- registering all async job handlers\n- starting the Asynq worker and consuming jobs\n\nCurrently registered:\n\n- `audit:request_log.write`\n\n### 4. Start the Scheduler\n\n```bash\ngo run main.go cron\n```\n\nEntry file:\n\n- [cmd/cron/cron.go](/Users/liuml/data/go/src/go-layout/cmd/cron/cron.go)\n\nUsed for:\n\n- starting the scheduler\n- registering the current recurring jobs\n- shutting down gracefully on process signals\n\nTask definition boundary:\n\n- `task_definitions` is currently a read-only mirror of built-in task definitions for the task center UI, manual trigger checks, and retry checks.\n- The `cron` scheduler still uses `BuiltinTaskDefinitions(cfg)` as its source of truth and does not read manually edited `task_definitions` rows from DB.\n- If the admin UI should become the scheduler configuration source, update the scheduler to read DB first and change built-in sync from overwrite to missing-record initialization.\n\n### 5. Run One-Off Commands\n\n```bash\ngo run main.go command api-route\ngo run main.go command rebuild-user-permissions\ngo run main.go command init-system\ngo run main.go -c ./config.yaml command migrate up\n```\n\nEntry file:\n\n- [cmd/command/command.go](/Users/liuml/data/go/src/go-layout/cmd/command/command.go)\n\nSupported subcommands:\n\n- `api-route`\n - scans the declarative route tree and rebuilds the `api` route table\n- `rebuild-user-permissions`\n - rebuilds final user API permissions from database relationships\n- `init-system`\n - rolls back migrations, reruns migrations, initializes API routes, and rebuilds user permissions\n- `demo`\n - example command\n- `migrate`\n - migration management subcommands: `create/check/up/down/goto/force/version`\n - full guide: [docs/MIGRATE_COMMANDS.en.md](/Users/liuml/data/go/src/go-layout/docs/MIGRATE_COMMANDS.en.md)\n- `task scan-async`\n - scans async queue tasks registered in code and compares them with the `task_definitions` mirror\n- `task scan-cron`\n - scans built-in cron task definitions and compares them with the `task_definitions` mirror\n\n### 6. Show Version\n\n```bash\ngo run main.go version\n```\n\n## Common Startup Combinations\n\n### 1. API Only\n\nUseful when:\n\n- you only need to debug HTTP APIs locally\n- your scenario does not depend on async jobs\n\n```bash\ngo run main.go service\n```\n\n### 2. API + Worker\n\nUseful when:\n\n- async jobs need to be consumed\n- Redis is enabled\n\n```bash\ngo run main.go service\ngo run main.go worker\n```\n\n### 3. API + Worker + Cron\n\nUseful when:\n\n- you need the API, async jobs, and recurring tasks at the same time\n\n```bash\ngo run main.go service\ngo run main.go worker\ngo run main.go cron\n```\n\n## Scheduled Jobs\n\nThe current scheduling code is split into 3 files:\n\n- [cmd/cron/cron.go](/Users/liuml/data/go/src/go-layout/cmd/cron/cron.go)\n - startup and shutdown only\n- [cmd/cron/schedule.go](/Users/liuml/data/go/src/go-layout/cmd/cron/schedule.go)\n - scheduling DSL\n- [cmd/cron/tasks.go](/Users/liuml/data/go/src/go-layout/cmd/cron/tasks.go)\n - filters enabled cron definitions and registers them into the scheduler\n- [internal/cron/registry.go](/Users/liuml/data/go/src/go-layout/internal/cron/registry.go)\n - owns built-in task definitions, cron handler registration, and task-center mirror sync\n\n### Current Style\n\nThe project now recommends declaring built-in task definitions in `internal/cron/registry.go`, while `cmd/cron/tasks.go` registers enabled cron definitions into the scheduler:\n\n```go\nfunc BuiltinTaskDefinitions(cfg *config.Conf) []model.TaskDefinition {\n\treturn []model.TaskDefinition{\n\t\t{\n\t\t\tCode: \"cron:cleanup-cache\",\n\t\t\tKind: model.TaskKindCron,\n\t\t\tCronSpec: \"0 */10 * * * *\",\n\t\t\tHandler: \"cron.cleanup-cache\",\n\t\t\tStatus: model.TaskStatusEnabled,\n\t\t},\n\t}\n}\n```\n\nWhy this is simpler:\n\n- task-center display, manual trigger checks, retry checks, and cron registration share the same built-in code definition\n- name, schedule, handler, status, and high-risk flags are visible at a glance\n- risky jobs can be explicitly enabled instead of being registered into cron by default\n- no need to repeat `AddJob`, `Chain`, and `Recover` manually\n\n### Available Methods\n\nCurrently supported:\n\n- `Call(name, func())`\n - register a function with no return value\n- `CallE(name, func() error)`\n - register a function returning `error`\n- `Cron(spec)`\n - use a raw cron expression\n- `EveryFiveSeconds()`\n - run every 5 seconds\n- `DailyAt(\"02:00:00\")`\n - run at a fixed time every day\n- `WithoutOverlapping()`\n - skip the next run if the current run is still active\n- `AllowOverlap()`\n - allow overlapping executions\n\n### Example 1: Run Every 10 Minutes\n\n```go\nschedule.Call(\"cleanup-cache\", cleanupCache).\n\tCron(\"0 */10 * * * *\").\n\tWithoutOverlapping()\n```\n\n### Example 2: Run Every Day At 3 AM\n\n```go\nschedule.CallE(\"sync-report\", reportService.SyncDailyReport).\n\tDailyAt(\"03:00:00\").\n\tWithoutOverlapping()\n```\n\n### Example 3: Allow Overlap\n\n```go\nschedule.Call(\"heartbeat\", heartbeat).\n\tCron(\"0/30 * * * * *\").\n\tAllowOverlap()\n```\n\n### Steps To Add A Scheduled Job\n\n1. Prepare the task function in the business layer.\n2. Register its handler in [registry.go](/Users/liuml/data/go/src/go-layout/internal/cron/registry.go).\n3. Add a `kind=cron` task definition to `BuiltinTaskDefinitions`.\n4. Run `go run main.go -c ./config.yaml command task scan-cron` to compare built-in definitions with the DB mirror.\n5. Restart the `cron` process.\n\n## Queue Usage\n\nThe queue system is built on top of `Asynq`, but business code does not talk to `asynq.Client` directly. It uses the project-level queue API instead.\n\nCore files:\n\n- [internal/queue/queue.go](/Users/liuml/data/go/src/go-layout/internal/queue/queue.go)\n- [internal/queue/asynqx/asynq.go](/Users/liuml/data/go/src/go-layout/internal/queue/asynqx/asynq.go)\n- [internal/jobs/registry.go](/Users/liuml/data/go/src/go-layout/internal/jobs/registry.go)\n\n### Queue Flow\n\nA typical async job flows like this:\n\n1. business code builds a payload\n2. it calls `queue.PublishJSON(...)`\n3. the job enters the target Redis queue\n4. `worker` starts and registers handlers\n5. Asynq pulls the job from Redis\n6. the corresponding handler runs the business logic\n\n### Recommended API\n\nPublish a job:\n\n```go\n_, err := queue.PublishJSON(ctx, taskType, queueName, payload, opts...)\n```\n\nRegister a consumer:\n\n```go\nqueue.RegisterJSON(registry, taskType, func(ctx context.Context, payload PayloadType) error {\n\treturn handle(payload)\n})\n```\n\nCompared to the older pattern, this is easier because:\n\n- you do not need to implement a full custom `Job` type\n- you do not need to manually `json.Marshal` and `json.Unmarshal`\n- payloads are easier to read and reuse\n- new jobs are easier to add by copying a small template\n\n## How To Add A New Queue Job\n\nThe example below uses \"send email\".\n\n### 1. Define The Payload\n\n```go\ntype EmailPayload struct {\n\tTo string `json:\"to\"`\n\tSubject string `json:\"subject\"`\n\tBody string `json:\"body\"`\n}\n\nfunc (p EmailPayload) Validate() error {\n\tif p.To == \"\" {\n\t\treturn errors.New(\"to is required\")\n\t}\n\treturn nil\n}\n```\n\nIf the payload implements `Validate() error`, it will be validated automatically before the handler runs. Validation failures are treated as non-retryable.\n\n### 2. Publish The Job\n\n```go\nfunc EnqueueEmail(ctx context.Context, payload EmailPayload) error {\n\t_, err := queue.PublishJSON(\n\t\tctx,\n\t\t\"notify:email.send\",\n\t\t\"default\",\n\t\tpayload,\n\t\tqueue.WithMaxRetry(5),\n\t\tqueue.WithTimeout(30*time.Second),\n\t)\n\treturn err\n}\n```\n\nThe parameters mean:\n\n- `\"notify:email.send\"`\n - task type\n- `\"default\"`\n - queue name\n- `payload`\n - task data\n- `WithMaxRetry`\n - maximum retry count\n- `WithTimeout`\n - execution timeout\n\n### 3. Register The Consumer\n\n```go\nfunc registerEmail(registry queue.Registry) {\n\tqueue.RegisterJSON(registry, \"notify:email.send\", func(ctx context.Context, payload EmailPayload) error {\n\t\treturn sendEmail(payload)\n\t})\n}\n```\n\n### 4. Register It In The Unified Entry\n\nCurrent recommended pattern:\n\n```go\nfunc RegisterAll(registry queue.Registry) {\n\tqueue.RegisterJSON(registry, AuditLogTaskType, handleAuditLog)\n\tregisterEmail(registry)\n}\n```\n\n### 5. Worker Consumes It Automatically\n\nWhen the worker starts, it does this:\n\n```go\nregistry := jobs.NewRegistry()\nserver, mux, err := asynqx.NewServer(cfg, registry)\n```\n\nSo if your handler is already registered in `RegisterAll`, the worker will consume it automatically.\n\n## How To Send A Job To A Specific Queue\n\nThe queue name is the third argument of `PublishJSON`:\n\n```go\nqueue.PublishJSON(ctx, \"notify:email.send\", \"critical\", payload)\n```\n\nHere `\"critical\"` is the queue name.\n\nTypical usage:\n\n- audit logs go to `audit`\n- normal jobs go to `default`\n- high-priority jobs go to `critical`\n- cleanup and low-priority jobs go to `low`\n\n## How To Configure Multiple Queues\n\nExample config:\n\n```yaml\nqueue:\n enable: true\n namespace: go_layout\n concurrency: 8\n strict_priority: false\n queues:\n critical: 4\n default: 2\n audit: 2\n low: 1\n audit_max_retry: 3\n audit_timeout_seconds: 10\n```\n\nMeaning:\n\n- `queues`\n - which queues the worker should listen to\n- numbers\n - relative weights for queue scheduling\n- `concurrency`\n - worker concurrency\n- `strict_priority`\n - whether to strictly prefer higher-priority queues\n\n### Multi-Queue Example\n\n```yaml\nqueue:\n queues:\n critical: 5\n default: 3\n audit: 2\n low: 1\n```\n\nOne possible split:\n\n- `critical`\n - permission repair, account-state sync\n- `default`\n - normal async business jobs\n- `audit`\n - request audit logs\n- `low`\n - cleanup, reporting, compensation jobs\n\n## Real Example In This Project\n\nThe currently integrated job is the audit log job:\n\n- task type: `audit:request_log.write`\n- queue: `audit`\n\nFile:\n\n- [internal/jobs/audit_log.go](/Users/liuml/data/go/src/go-layout/internal/jobs/audit_log.go)\n\nProducer:\n\n```go\nfunc EnqueueAuditLog(ctx context.Context, kind string, snapshot *auditsvc.AuditLogSnapshot) error {\n\tpayload, err := NewAuditLogPayload(kind, snapshot)\n\tif err != nil {\n\t\treturn err\n\t}\n\t_, err = queue.PublishJSON(ctx, AuditLogTaskType, AuditQueueName, payload, auditLogOptions()...)\n\treturn err\n}\n```\n\nConsumer registration:\n\n```go\nfunc RegisterAll(registry queue.Registry) {\n\tqueue.RegisterJSON(registry, AuditLogTaskType, handleAuditLog)\n}\n```\n\nWorker startup:\n\n```go\nregistry := jobs.NewRegistry()\nserver, mux, err := asynqx.NewServer(cfg, registry)\n```\n\n## When To Use Cron vs Queue\n\nRecommended split by responsibility:\n\n- `cron`\n - decides when something should run\n - good for recurring schedules\n- `queue`\n - decides how something runs asynchronously\n - good for retries, decoupling, and background consumption\n\n### Typical Cases\n\nUse `cron` for:\n\n- resetting system data every day\n- clearing cache every hour\n- syncing statistics every 5 minutes\n\nUse `queue` for:\n\n- audit-log persistence\n- email sending\n- webhook delivery\n- incremental permission sync\n\nUse both together when needed:\n\n- `cron` triggers on schedule\n- `cron` publishes a queue job\n- `worker` performs the actual work\n\n## FAQ\n\n### 1. Why Was The Job Published But Not Consumed?\n\nCheck these first:\n\n- Redis is available\n- `queue.enable` is enabled\n- `worker` is running\n- the task is registered in `RegisterAll`\n\n### 2. Why Do Invalid Payloads Not Retry?\n\nBecause `RegisterJSON` treats JSON decode failures and `Validate()` failures as invalid input. Retrying those usually does not help.\n\n### 3. Why Does The Physical Queue Name Include A Prefix?\n\nBecause the current implementation supports `namespace`, for example:\n\n- configured queue name: `audit`\n- actual Redis queue name: `go_layout:audit`\n\nBusiness code should keep using the logical queue name.\n\n### 4. When Should I Implement `queue.Job` Myself?\n\nMost business scenarios do not need it.\n\nOnly consider it when you need:\n\n- a custom non-JSON payload flow\n- a special payload generation path\n- unusual job object behavior\n\nBy default, prefer:\n\n- `queue.PublishJSON`\n- `queue.RegisterJSON`\n\n## Recommended Practices\n\n- keep scheduled jobs in [tasks.go](/Users/liuml/data/go/src/go-layout/cmd/cron/tasks.go)\n- keep async jobs under `internal/jobs`\n- keep one clear payload per task type\n- keep payloads small and stable\n- separate high-priority and low-priority jobs by queue\n- avoid calling Asynq APIs directly from business code\n- prefer the project-level helpers: `PublishJSON` and `RegisterJSON`\n"
},
{
"path": "docs/COMMANDS_AND_TASKS.md",
"content": "# 命令、定时任务与队列使用说明\n\n本文档集中说明以下内容：\n\n- 项目支持的命令及用途\n- 如何启动 `service`、`worker`、`cron`\n- 如何新增定时任务\n- 如何创建、发布、消费异步队列任务\n- 如何把任务放入指定队列，以及如何配置多队列\n\n系统配置与系统字典的接入边界见：[docs/SYSTEM_CONFIG_AND_DICT_GUIDELINES.md](/Users/liuml/data/go/src/go-layout/docs/SYSTEM_CONFIG_AND_DICT_GUIDELINES.md)。\n\n如果你刚接手项目，建议先看“运行模型”和“命令说明”，再看“定时任务”和“队列”两节。\n\n## 运行模型\n\n当前项目把后台运行能力拆成了 3 类进程：\n\n- `service`\n - 提供 HTTP API\n - 处理登录、权限、菜单、上传、日志等业务\n - 某些场景下会往队列里发布异步任务\n\n- `worker`\n - 消费异步任务\n - 当前已经接入请求审计日志异步落库\n\n- `cron`\n - 负责周期性调度\n - 当前使用 `robfig/cron`\n - 适合“每天凌晨 2 点执行一次”这类固定时间任务\n\n可以把它理解成：\n\n- `service` 负责对外服务\n- `worker` 负责后台消费\n- `cron` 负责按时间触发\n\n## 命令说明\n\n项目根命令入口在 [cmd/root.go](/Users/liuml/data/go/src/go-layout/cmd/root.go)。\n\n### 0. 迁移命令\n\n常用入口：\n\n```bash\ngo run main.go -c ./config.yaml command migrate check\ngo run main.go -c ./config.yaml command migrate up\n```\n\n详细说明见：[docs/MIGRATE_COMMANDS.md](/Users/liuml/data/go/src/go-layout/docs/MIGRATE_COMMANDS.md)。\n\n### 1. 查看帮助\n\n```bash\ngo run main.go -h\ngo run main.go command -h\n```\n\n### 2. 启动 API 服务\n\n```bash\ngo run main.go service\n```\n\n用途：\n\n- 启动 Gin HTTP 服务\n- 加载配置、日志、数据库等基础资源\n- 提供业务 API\n\n常见场景：\n\n- 本地开发\n- 单机部署 API 服务\n- 容器内主应用进程\n\n### 3. 启动异步任务消费进程\n\n```bash\ngo run main.go worker\n```\n\n入口文件：\n\n- [cmd/worker/worker.go](/Users/liuml/data/go/src/go-layout/cmd/worker/worker.go)\n\n用途：\n\n- 连接 Redis\n- 注册所有异步任务处理器\n- 启动 Asynq worker，消费队列中的任务\n\n当前已接入任务：\n\n- `audit:request_log.write`\n\n### 4. 启动定时任务调度器\n\n```bash\ngo run main.go cron\n```\n\n入口文件：\n\n- [cmd/cron/cron.go](/Users/liuml/data/go/src/go-layout/cmd/cron/cron.go)\n\n用途：\n\n- 启动周期调度器\n- 注册当前定义的周期任务\n- 收到退出信号后优雅关闭\n\n任务定义边界：\n\n- `task_definitions` 当前是代码内置任务定义的只读镜像，用于任务中心展示、手动触发与重试校验。\n- `cron` 调度器的真实来源仍是 `BuiltinTaskDefinitions(cfg)`，不会读取 DB 中被人工修改的 `task_definitions`。\n- 如需让后台成为调度配置入口，必须先调整 scheduler 读取 DB，并把内置同步策略从覆盖改为初始化缺失记录。\n\n### 5. 运行一次性命令\n\n```bash\ngo run main.go command api-route\ngo run main.go command rebuild-user-permissions\ngo run main.go command init-system\ngo run main.go -c ./config.yaml command migrate up\n```\n\n入口文件：\n\n- [cmd/command/command.go](/Users/liuml/data/go/src/go-layout/cmd/command/command.go)\n\n支持的子命令：\n\n- `api-route`\n - 扫描声明式路由树并重建 `api` 路由表\n- `rebuild-user-permissions`\n - 按数据库关系重建用户最终 API 权限\n- `init-system`\n - 回滚迁移、重新执行迁移、初始化 API 路由、重建用户权限\n- `demo`\n - 示例命令\n- `migrate`\n - 迁移管理子命令，支持 `create/check/up/down/goto/force/version`\n - 详细说明见 [docs/MIGRATE_COMMANDS.md](/Users/liuml/data/go/src/go-layout/docs/MIGRATE_COMMANDS.md)\n- `task scan-async`\n - 扫描代码注册的异步队列任务，并与 `task_definitions` 镜像做对比\n- `task scan-cron`\n - 扫描代码内置的 cron 任务定义，并与 `task_definitions` 镜像做对比\n\n### 6. 查看版本\n\n```bash\ngo run main.go version\n```\n\n## 常见启动组合\n\n### 1. 只启动 API\n\n适合：\n\n- 本地只调接口\n- 不依赖异步任务的场景\n\n```bash\ngo run main.go service\n```\n\n### 2. 启动 API + Worker\n\n适合：\n\n- 需要消费异步任务\n- 已启用 Redis\n\n```bash\ngo run main.go service\ngo run main.go worker\n```\n\n### 3. 启动 API + Worker + Cron\n\n适合：\n\n- 同时需要接口服务、异步消费和定时调度\n\n```bash\ngo run main.go service\ngo run main.go worker\ngo run main.go cron\n```\n\n## 定时任务使用方式\n\n当前定时任务代码分成 3 个文件：\n\n- [cmd/cron/cron.go](/Users/liuml/data/go/src/go-layout/cmd/cron/cron.go)\n - 只负责启动与关闭\n- [cmd/cron/schedule.go](/Users/liuml/data/go/src/go-layout/cmd/cron/schedule.go)\n - 提供任务声明 DSL\n- [cmd/cron/tasks.go](/Users/liuml/data/go/src/go-layout/cmd/cron/tasks.go)\n - 从内置任务定义中筛选启用的 cron 任务并注册到调度器\n- [internal/cron/registry.go](/Users/liuml/data/go/src/go-layout/internal/cron/registry.go)\n - 维护内置任务定义、cron handler 注册表和任务中心镜像同步\n\n### 当前写法\n\n当前项目推荐先在 `internal/cron/registry.go` 声明内置任务定义，再由 `cmd/cron/tasks.go` 统一注册启用的 cron 任务：\n\n```go\nfunc BuiltinTaskDefinitions(cfg *config.Conf) []model.TaskDefinition {\n\treturn []model.TaskDefinition{\n\t\t{\n\t\t\tCode: \"cron:cleanup-cache\",\n\t\t\tKind: model.TaskKindCron,\n\t\t\tCronSpec: \"0 */10 * * * *\",\n\t\t\tHandler: \"cron.cleanup-cache\",\n\t\t\tStatus: model.TaskStatusEnabled,\n\t\t},\n\t}\n}\n```\n\n这样做的好处是：\n\n- 任务中心展示、手动触发、重试校验和 cron 注册共用一份代码内置定义\n- 名称、时间规则、handler、状态和高风险标记一眼能看出来\n- 高风险任务可以显式配置启用，默认不参与 cron 注册\n- 不需要每次手写 `AddJob`、`Chain`、`Recover`\n\n### 可用方法\n\n目前已经支持：\n\n- `Call(name, func())`\n - 注册无返回值任务\n- `CallE(name, func() error)`\n - 注册返回 `error` 的任务\n- `Cron(spec)`\n - 直接使用 cron 表达式\n- `EveryFiveSeconds()`\n - 每 5 秒执行一次\n- `DailyAt(\"02:00:00\")`\n - 每天固定时间执行\n- `WithoutOverlapping()`\n - 任务运行期间不允许重入\n- `AllowOverlap()`\n - 允许重入\n\n### 示例 1：每 10 分钟执行一次\n\n```go\nschedule.Call(\"cleanup-cache\", cleanupCache).\n\tCron(\"0 */10 * * * *\").\n\tWithoutOverlapping()\n```\n\n### 示例 2：每天凌晨 3 点执行\n\n```go\nschedule.CallE(\"sync-report\", reportService.SyncDailyReport).\n\tDailyAt(\"03:00:00\").\n\tWithoutOverlapping()\n```\n\n### 示例 3：允许重入\n\n```go\nschedule.Call(\"heartbeat\", heartbeat).\n\tCron(\"0/30 * * * * *\").\n\tAllowOverlap()\n```\n\n### 新增定时任务步骤\n\n1. 在业务层准备好任务函数。\n2. 在 [registry.go](/Users/liuml/data/go/src/go-layout/internal/cron/registry.go) 注册 handler。\n3. 在 `BuiltinTaskDefinitions` 中新增 `kind=cron` 的任务定义。\n4. 运行 `go run main.go -c ./config.yaml command task scan-cron` 检查内置定义与 DB 镜像。\n5. 重启 `cron` 进程。\n\n## 队列使用说明\n\n当前队列基于 `Asynq`，但业务层不直接依赖 `asynq.Client`，而是使用项目自己的统一接口。\n\n核心代码：\n\n- [internal/queue/queue.go](/Users/liuml/data/go/src/go-layout/internal/queue/queue.go)\n- [internal/queue/asynqx/asynq.go](/Users/liuml/data/go/src/go-layout/internal/queue/asynqx/asynq.go)\n- [internal/jobs/registry.go](/Users/liuml/data/go/src/go-layout/internal/jobs/registry.go)\n\n### 队列完整链路\n\n一条异步任务的执行链路如下：\n\n1. 业务代码构造 payload\n2. 调用 `queue.PublishJSON(...)` 发布任务\n3. 任务进入 Redis 对应队列\n4. `worker` 启动后注册任务处理器\n5. Asynq 从 Redis 拉取任务\n6. 调用对应 handler 执行业务逻辑\n\n### 当前推荐 API\n\n发布任务：\n\n```go\n_, err := queue.PublishJSON(ctx, taskType, queueName, payload, opts...)\n```\n\n注册消费：\n\n```go\nqueue.RegisterJSON(registry, taskType, func(ctx context.Context, payload PayloadType) error {\n\treturn handle(payload)\n})\n```\n\n相比旧写法，这样有几个好处：\n\n- 不需要单独实现一个 `Job` 结构体\n- 不需要手动做 `json.Marshal` / `json.Unmarshal`\n- payload 结构更直观\n- 新任务更容易复制模板\n\n## 如何创建一个新队列任务\n\n下面用“发送邮件”举例。\n\n### 1. 定义 payload\n\n```go\ntype EmailPayload struct {\n\tTo string `json:\"to\"`\n\tSubject string `json:\"subject\"`\n\tBody string `json:\"body\"`\n}\n\nfunc (p EmailPayload) Validate() error {\n\tif p.To == \"\" {\n\t\treturn errors.New(\"to is required\")\n\t}\n\treturn nil\n}\n```\n\n如果 payload 实现了 `Validate() error`，消费前会自动校验。校验失败会按“不重试”处理。\n\n### 2. 发布任务\n\n```go\nfunc EnqueueEmail(ctx context.Context, payload EmailPayload) error {\n\t_, err := queue.PublishJSON(\n\t\tctx,\n\t\t\"notify:email.send\",\n\t\t\"default\",\n\t\tpayload,\n\t\tqueue.WithMaxRetry(5),\n\t\tqueue.WithTimeout(30*time.Second),\n\t)\n\treturn err\n}\n```\n\n这里的参数分别表示：\n\n- `\"notify:email.send\"`\n - 任务类型\n- `\"default\"`\n - 队列名\n- `payload`\n - 任务数据\n- `WithMaxRetry`\n - 最大重试次数\n- `WithTimeout`\n - 执行超时时间\n\n### 3. 注册消费处理器\n\n```go\nfunc registerEmail(registry queue.Registry) {\n\tqueue.RegisterJSON(registry, \"notify:email.send\", func(ctx context.Context, payload EmailPayload) error {\n\t\treturn sendEmail(payload)\n\t})\n}\n```\n\n### 4. 注册到统一入口\n\n当前推荐把所有任务注册放在一个地方，例如：\n\n```go\nfunc RegisterAll(registry queue.Registry) {\n\tqueue.RegisterJSON(registry, AuditLogTaskType, handleAuditLog)\n\tregisterEmail(registry)\n}\n```\n\n### 5. Worker 自动消费\n\n`worker` 启动时会调用：\n\n```go\nregistry := jobs.NewRegistry()\nserver, mux, err := asynqx.NewServer(cfg, registry)\n```\n\n所以只要你的任务已经注册进 `RegisterAll`，worker 就会自动消费。\n\n## 如何把任务放到指定队列\n\n看 `PublishJSON` 的第三个参数：\n\n```go\nqueue.PublishJSON(ctx, \"notify:email.send\", \"critical\", payload)\n```\n\n这里的 `\"critical\"` 就是队列名。\n\n常见用法：\n\n- 审计日志放 `audit`\n- 普通任务放 `default`\n- 高优先级任务放 `critical`\n- 低优先级清理任务放 `low`\n\n## 如何配置多队列\n\n配置文件示例：\n\n```yaml\nqueue:\n enable: true\n namespace: go_layout\n concurrency: 8\n strict_priority: false\n queues:\n critical: 4\n default: 2\n audit: 2\n low: 1\n audit_max_retry: 3\n audit_timeout_seconds: 10\n```\n\n含义：\n\n- `queues`\n - 声明 worker 需要监听哪些队列\n- 数字\n - 表示各队列的权重\n- `concurrency`\n - worker 并发度\n- `strict_priority`\n - 是否严格优先消费高优先级队列\n\n### 多队列示例\n\n```yaml\nqueue:\n queues:\n critical: 5\n default: 3\n audit: 2\n low: 1\n```\n\n你可以这样分配：\n\n- `critical`\n - 权限修复、账号状态同步\n- `default`\n - 普通异步业务\n- `audit`\n - 请求审计日志\n- `low`\n - 清理、统计、补偿任务\n\n## 当前项目中的真实示例\n\n当前已经接入的任务是审计日志任务：\n\n- 任务类型：`audit:request_log.write`\n- 队列：`audit`\n\n对应文件：\n\n- [internal/jobs/audit_log.go](/Users/liuml/data/go/src/go-layout/internal/jobs/audit_log.go)\n\n发布端：\n\n```go\nfunc EnqueueAuditLog(ctx context.Context, kind string, snapshot *auditsvc.AuditLogSnapshot) error {\n\tpayload, err := NewAuditLogPayload(kind, snapshot)\n\tif err != nil {\n\t\treturn err\n\t}\n\t_, err = queue.PublishJSON(ctx, AuditLogTaskType, AuditQueueName, payload, auditLogOptions()...)\n\treturn err\n}\n```\n\n消费端：\n\n```go\nfunc RegisterAll(registry queue.Registry) {\n\tqueue.RegisterJSON(registry, AuditLogTaskType, handleAuditLog)\n}\n```\n\nworker 启动：\n\n```go\nregistry := jobs.NewRegistry()\nserver, mux, err := asynqx.NewServer(cfg, registry)\n```\n\n## 何时使用 Cron，何时使用 Queue\n\n建议按职责区分：\n\n- `cron`\n - 负责“什么时候触发”\n - 适合固定时间周期任务\n- `queue`\n - 负责“任务如何异步执行”\n - 适合削峰、重试、异步消费\n\n### 典型场景\n\n用 `cron`：\n\n- 每天凌晨重置系统数据\n- 每小时清理缓存\n- 每 5 分钟同步统计\n\n用 `queue`：\n\n- 审计日志落库\n- 邮件发送\n- Webhook 投递\n- 权限增量同步\n\n组合使用：\n\n- `cron` 到点触发\n- `cron` 内部把任务投递到 `queue`\n- `worker` 真正执行任务\n\n## 常见问题\n\n### 1. 为什么发布了任务，但没有被消费？\n\n先检查：\n\n- Redis 是否可用\n- `queue.enable` 是否开启\n- `worker` 是否已启动\n- 任务是否已经注册到 `RegisterAll`\n\n### 2. 为什么任务校验失败后不重试？\n\n因为 `RegisterJSON` 会把 payload 反序列化失败或 `Validate()` 失败视为“无效任务”，这类问题通常重试没有意义。\n\n### 3. 为什么任务进了带前缀的物理队列？\n\n因为当前实现支持 `namespace`，例如：\n\n- 配置队列名：`audit`\n- 实际 Redis 队列名：`go_layout:audit`\n\n业务代码里仍然使用逻辑队列名即可。\n\n### 4. 什么时候需要自己实现 `queue.Job`？\n\n大多数业务场景都不需要。\n\n只有当你需要：\n\n- 自定义更复杂的 payload 生成过程\n- 不想走 JSON\n- 需要对任务对象做特殊封装\n\n才建议自己实现 `queue.Job`。\n\n默认情况下，优先使用：\n\n- `queue.PublishJSON`\n- `queue.RegisterJSON`\n\n## 推荐实践\n\n- 定时任务统一写在 [tasks.go](/Users/liuml/data/go/src/go-layout/cmd/cron/tasks.go)\n- 异步任务统一写在 `internal/jobs`\n- 一个任务类型只对应一个清晰的 payload\n- payload 尽量保持小而稳定\n- 高优先级任务和低优先级任务分队列\n- 不要在业务代码里直接使用 Asynq 的底层 API\n- 优先使用项目封装好的 `PublishJSON` / `RegisterJSON`\n"
},
{
"path": "docs/DONATE.en.md",
"content": "# Support gin-layout
\n\n\n\n
\n\nThank you for using `gin-layout`.\n\nIf this project helps you, you are welcome to support its ongoing development and maintenance through any of the options below.\n\n## Alipay\n\n\n
![\"Alipay](\"./images/alipay.jpg\")
\n
\n
![\"WeChat](\"./images/wechat_pay.jpg\")
\n
\n
![\"ETH](\"./images/eth.jpg\")
\n
赞助 gin-layout
\n\n\n\n
\n\n感谢你使用 `gin-layout`。\n\n如果这个项目对你有帮助，欢迎通过下面的方式支持项目的持续开发与维护。\n\n## 支付宝\n\n\n
\n
\n
\n
\n
\n
![\"go\"](\"https://github.com/wannanbigpig/gin-layout/actions/workflows/go.yml/badge.svg\"){kind=icon}
\n ![\"codeql\"](\"https://github.com/wannanbigpig/gin-layout/actions/workflows/codeql.yml/badge.svg\"){kind=icon}
\n ![\"license\"](\"https://img.shields.io/github/license/wannanbigpig/gin-layout\")
\n ![\"go](\"https://img.shields.io/badge/Go-%3E%3D1.23-blue.svg\"){kind=icon}
\n