From e1ff172d27a15299a14c7298ef12a57563910afa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=B0=8F=E8=9A=82=E8=9A=81=E4=BA=91?= Date: Sun, 25 Oct 2026 22:36:33 +0800 Subject: [PATCH] =?UTF-8?q?=E7=AD=BE=E5=85=A5=E7=89=88=E6=9C=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../.vitepress/config/en.ts | 2 +- .../.vitepress/config/extract.d.mts | 5 + .../.vitepress/config/extract.mjs | 130 ++++++++ .../.vitepress/config/index.ts | 8 + .../.vitepress/config/seo.ts | 311 ++++++++++++++++++ .../.vitepress/config/shared.ts | 4 +- .../.vitepress/config/zh.ts | 2 +- DjangoAdmin_Django_AntdVue/404.md | 12 + DjangoAdmin_Django_AntdVue/package.json | 3 +- DjangoAdmin_Django_AntdVue/public/llms.txt | 165 ++++++++++ DjangoAdmin_Django_AntdVue/public/robots.txt | 33 ++ .../scripts/generate-llms-txt.mjs | 122 +++++++ DjangoAdmin_Django_AntdVue/zh/course.md | 2 + DjangoAdmin_Django_AntdVue/zh/introduction.md | 6 + .../zh/other/contributing.md | 2 +- .../zh/other/declare.md | 4 + DjangoAdmin_Django_AntdVue/zh/struct.md | 4 + .../zh/volume2/code-list.md | 4 + DjangoAdmin_Django_AntdVue/zh/volume2/faq.md | 4 + .../zh/volume2/fe-api.md | 4 + .../zh/volume2/fe-router.md | 4 + .../zh/volume2/fe-view.md | 4 + DjangoAdmin_Django_AntdVue/zh/volume2/form.md | 4 + .../zh/volume2/model.md | 4 + .../zh/volume2/overview.md | 4 + .../zh/volume2/permission.md | 4 + .../zh/volume2/service.md | 4 + DjangoAdmin_Django_AntdVue/zh/volume2/url.md | 4 + DjangoAdmin_Django_AntdVue/zh/volume2/view.md | 4 + .../zh/volume3/base-classes.md | 4 + .../zh/volume3/cache.md | 4 + .../zh/volume3/database-design.md | 4 + .../zh/volume3/directory.md | 4 + .../zh/volume3/extensibility.md | 4 + .../zh/volume3/layer-arch.md | 4 + .../zh/volume3/overview.md | 4 + .../zh/volume3/request-flow.md | 4 + .../zh/volume3/security.md | 4 + .../zh/volume3/tech-stack.md | 4 + .../zh/volume4/business/article.md | 2 + .../zh/volume4/business/category.md | 2 + .../zh/volume4/business/city.md | 2 + .../zh/volume4/business/content.md | 2 + .../zh/volume4/business/dept.md | 2 + .../zh/volume4/business/job.md | 2 + .../zh/volume4/business/menu.md | 2 + .../zh/volume4/business/param.md | 2 + .../zh/volume4/business/role.md | 2 + .../zh/volume4/business/user.md | 2 + .../zh/volume4/core/captcha.md | 2 + .../zh/volume4/core/config.md | 2 + .../zh/volume4/core/cors.md | 2 + .../zh/volume4/core/demo-mode.md | 2 + .../zh/volume4/core/dict.md | 2 + .../zh/volume4/core/exception.md | 2 + .../zh/volume4/core/idempotent.md | 2 + .../zh/volume4/core/jwt.md | 2 + .../zh/volume4/core/login-log.md | 2 + .../zh/volume4/core/operation-log.md | 2 + .../zh/volume4/core/rate-limit.md | 2 + .../zh/volume4/core/rbac.md | 2 + .../zh/volume4/core/validator.md | 2 + DjangoAdmin_Django_AntdVue/zh/why.md | 4 + .../.vitepress/config/en.ts | 2 +- .../.vitepress/config/extract.d.mts | 5 + .../.vitepress/config/extract.mjs | 130 ++++++++ .../.vitepress/config/index.ts | 8 + .../.vitepress/config/seo.ts | 311 ++++++++++++++++++ .../.vitepress/config/shared.ts | 4 +- .../.vitepress/config/zh.ts | 2 +- DjangoAdmin_Django_EleVue/404.md | 12 + DjangoAdmin_Django_EleVue/package.json | 3 +- DjangoAdmin_Django_EleVue/public/llms.txt | 165 ++++++++++ DjangoAdmin_Django_EleVue/public/robots.txt | 33 ++ .../scripts/generate-llms-txt.mjs | 122 +++++++ DjangoAdmin_Django_EleVue/zh/course.md | 2 + DjangoAdmin_Django_EleVue/zh/introduction.md | 6 + .../zh/other/contributing.md | 2 +- DjangoAdmin_Django_EleVue/zh/other/declare.md | 4 + DjangoAdmin_Django_EleVue/zh/struct.md | 4 + .../zh/volume2/code-list.md | 4 + DjangoAdmin_Django_EleVue/zh/volume2/faq.md | 4 + .../zh/volume2/fe-api.md | 4 + .../zh/volume2/fe-router.md | 4 + .../zh/volume2/fe-view.md | 4 + DjangoAdmin_Django_EleVue/zh/volume2/form.md | 4 + DjangoAdmin_Django_EleVue/zh/volume2/model.md | 4 + .../zh/volume2/overview.md | 4 + .../zh/volume2/permission.md | 4 + .../zh/volume2/service.md | 4 + DjangoAdmin_Django_EleVue/zh/volume2/url.md | 4 + DjangoAdmin_Django_EleVue/zh/volume2/view.md | 4 + .../zh/volume3/base-classes.md | 4 + DjangoAdmin_Django_EleVue/zh/volume3/cache.md | 4 + .../zh/volume3/database-design.md | 4 + .../zh/volume3/directory.md | 4 + .../zh/volume3/extensibility.md | 4 + .../zh/volume3/layer-arch.md | 4 + .../zh/volume3/overview.md | 4 + .../zh/volume3/request-flow.md | 4 + .../zh/volume3/security.md | 4 + .../zh/volume3/tech-stack.md | 4 + .../zh/volume4/business/article.md | 2 + .../zh/volume4/business/category.md | 2 + .../zh/volume4/business/city.md | 2 + .../zh/volume4/business/content.md | 2 + .../zh/volume4/business/dept.md | 2 + .../zh/volume4/business/job.md | 2 + .../zh/volume4/business/menu.md | 2 + .../zh/volume4/business/param.md | 2 + .../zh/volume4/business/role.md | 2 + .../zh/volume4/business/user.md | 2 + .../zh/volume4/core/captcha.md | 2 + .../zh/volume4/core/config.md | 2 + .../zh/volume4/core/cors.md | 2 + .../zh/volume4/core/demo-mode.md | 2 + .../zh/volume4/core/dict.md | 2 + .../zh/volume4/core/exception.md | 2 + .../zh/volume4/core/idempotent.md | 2 + .../zh/volume4/core/jwt.md | 2 + .../zh/volume4/core/login-log.md | 2 + .../zh/volume4/core/operation-log.md | 2 + .../zh/volume4/core/rate-limit.md | 2 + .../zh/volume4/core/rbac.md | 2 + .../zh/volume4/core/validator.md | 2 + DjangoAdmin_Django_EleVue/zh/why.md | 4 + .../.vitepress/config/en.ts | 2 +- .../.vitepress/config/extract.d.mts | 5 + .../.vitepress/config/extract.mjs | 130 ++++++++ .../.vitepress/config/index.ts | 8 + .../.vitepress/config/seo.ts | 311 ++++++++++++++++++ .../.vitepress/config/shared.ts | 4 +- .../.vitepress/config/zh.ts | 2 +- DjangoAdmin_Django_NaiveVue/404.md | 12 + DjangoAdmin_Django_NaiveVue/package.json | 3 +- DjangoAdmin_Django_NaiveVue/public/llms.txt | 165 ++++++++++ DjangoAdmin_Django_NaiveVue/public/robots.txt | 33 ++ .../scripts/generate-llms-txt.mjs | 122 +++++++ DjangoAdmin_Django_NaiveVue/zh/course.md | 2 + .../zh/introduction.md | 6 + .../zh/other/contributing.md | 2 +- .../zh/other/declare.md | 4 + DjangoAdmin_Django_NaiveVue/zh/struct.md | 4 + .../zh/volume2/code-list.md | 4 + DjangoAdmin_Django_NaiveVue/zh/volume2/faq.md | 4 + .../zh/volume2/fe-api.md | 4 + .../zh/volume2/fe-router.md | 4 + .../zh/volume2/fe-view.md | 4 + .../zh/volume2/form.md | 4 + .../zh/volume2/model.md | 4 + .../zh/volume2/overview.md | 4 + .../zh/volume2/permission.md | 4 + .../zh/volume2/service.md | 4 + DjangoAdmin_Django_NaiveVue/zh/volume2/url.md | 4 + .../zh/volume2/view.md | 4 + .../zh/volume3/base-classes.md | 4 + .../zh/volume3/cache.md | 4 + .../zh/volume3/database-design.md | 4 + .../zh/volume3/directory.md | 4 + .../zh/volume3/extensibility.md | 4 + .../zh/volume3/layer-arch.md | 4 + .../zh/volume3/overview.md | 4 + .../zh/volume3/request-flow.md | 4 + .../zh/volume3/security.md | 4 + .../zh/volume3/tech-stack.md | 4 + .../zh/volume4/business/article.md | 2 + .../zh/volume4/business/category.md | 2 + .../zh/volume4/business/city.md | 2 + .../zh/volume4/business/content.md | 2 + .../zh/volume4/business/dept.md | 2 + .../zh/volume4/business/job.md | 2 + .../zh/volume4/business/menu.md | 2 + .../zh/volume4/business/param.md | 2 + .../zh/volume4/business/role.md | 2 + .../zh/volume4/business/user.md | 2 + .../zh/volume4/core/captcha.md | 2 + .../zh/volume4/core/config.md | 2 + .../zh/volume4/core/cors.md | 2 + .../zh/volume4/core/demo-mode.md | 2 + .../zh/volume4/core/dict.md | 2 + .../zh/volume4/core/exception.md | 2 + .../zh/volume4/core/idempotent.md | 2 + .../zh/volume4/core/jwt.md | 2 + .../zh/volume4/core/login-log.md | 2 + .../zh/volume4/core/operation-log.md | 2 + .../zh/volume4/core/rate-limit.md | 2 + .../zh/volume4/core/rbac.md | 2 + .../zh/volume4/core/validator.md | 2 + DjangoAdmin_Django_NaiveVue/zh/why.md | 4 + .../.vitepress/config/en.ts | 2 +- .../.vitepress/config/extract.d.mts | 5 + .../.vitepress/config/extract.mjs | 130 ++++++++ .../.vitepress/config/index.ts | 8 + .../.vitepress/config/seo.ts | 311 ++++++++++++++++++ .../.vitepress/config/shared.ts | 4 +- .../.vitepress/config/zh.ts | 7 +- DjangoAdmin_FastAPI_AntdVue/404.md | 12 + DjangoAdmin_FastAPI_AntdVue/package.json | 3 +- DjangoAdmin_FastAPI_AntdVue/public/llms.txt | 159 +++++++++ DjangoAdmin_FastAPI_AntdVue/public/robots.txt | 33 ++ .../scripts/generate-llms-txt.mjs | 122 +++++++ DjangoAdmin_FastAPI_AntdVue/zh/course.md | 2 + .../zh/introduction.md | 14 +- .../zh/other/declare.md | 4 + DjangoAdmin_FastAPI_AntdVue/zh/struct.md | 6 + .../zh/volume2/code-list.md | 4 + .../zh/volume2/endpoint.md | 4 + DjangoAdmin_FastAPI_AntdVue/zh/volume2/faq.md | 4 + .../zh/volume2/fe-api.md | 4 + .../zh/volume2/fe-router.md | 4 + .../zh/volume2/fe-view.md | 4 + .../zh/volume2/repository.md | 4 + .../zh/volume2/router.md | 4 + .../zh/volume2/schema.md | 4 + .../zh/volume2/service.md | 4 + .../zh/volume4/business/article.md | 2 + .../zh/volume4/business/category.md | 2 + .../zh/volume4/business/content.md | 2 + .../zh/volume4/business/dept.md | 2 + .../zh/volume4/business/job.md | 2 + .../zh/volume4/business/menu.md | 2 + .../zh/volume4/business/param.md | 2 + .../zh/volume4/business/role.md | 2 + .../zh/volume4/business/user.md | 2 + .../zh/volume4/core/captcha.md | 2 + .../zh/volume4/core/config.md | 2 + .../zh/volume4/core/cors.md | 2 + .../zh/volume4/core/demo-mode.md | 2 + .../zh/volume4/core/dict.md | 2 + .../zh/volume4/core/exception.md | 2 + .../zh/volume4/core/idempotent.md | 2 + .../zh/volume4/core/jwt.md | 2 + .../zh/volume4/core/login-log.md | 2 + .../zh/volume4/core/operation-log.md | 2 + .../zh/volume4/core/rate-limit.md | 2 + .../zh/volume4/core/rbac.md | 2 + .../zh/volume4/core/validator.md | 2 + DjangoAdmin_FastAPI_AntdVue/zh/why.md | 2 +- .../.vitepress/config/en.ts | 2 +- .../.vitepress/config/extract.d.mts | 5 + .../.vitepress/config/extract.mjs | 130 ++++++++ .../.vitepress/config/index.ts | 8 + .../.vitepress/config/seo.ts | 311 ++++++++++++++++++ .../.vitepress/config/shared.ts | 4 +- .../.vitepress/config/zh.ts | 11 +- DjangoAdmin_FastAPI_EleVue/404.md | 12 + DjangoAdmin_FastAPI_EleVue/package.json | 3 +- DjangoAdmin_FastAPI_EleVue/public/llms.txt | 159 +++++++++ DjangoAdmin_FastAPI_EleVue/public/robots.txt | 33 ++ .../scripts/generate-llms-txt.mjs | 122 +++++++ DjangoAdmin_FastAPI_EleVue/zh/course.md | 2 + DjangoAdmin_FastAPI_EleVue/zh/introduction.md | 14 +- .../zh/other/declare.md | 4 + DjangoAdmin_FastAPI_EleVue/zh/struct.md | 6 + .../zh/volume2/code-list.md | 4 + .../zh/volume2/endpoint.md | 4 + DjangoAdmin_FastAPI_EleVue/zh/volume2/faq.md | 4 + .../zh/volume2/fe-api.md | 4 + .../zh/volume2/fe-router.md | 4 + .../zh/volume2/fe-view.md | 4 + .../zh/volume2/overview.md | 4 + .../zh/volume2/repository.md | 4 + .../zh/volume2/router.md | 4 + .../zh/volume2/schema.md | 4 + .../zh/volume2/service.md | 4 + .../zh/volume4/business/article.md | 2 + .../zh/volume4/business/category.md | 2 + .../zh/volume4/business/content.md | 2 + .../zh/volume4/business/dept.md | 2 + .../zh/volume4/business/job.md | 2 + .../zh/volume4/business/menu.md | 2 + .../zh/volume4/business/param.md | 2 + .../zh/volume4/business/role.md | 2 + .../zh/volume4/business/user.md | 2 + .../zh/volume4/core/captcha.md | 2 + .../zh/volume4/core/config.md | 2 + .../zh/volume4/core/cors.md | 2 + .../zh/volume4/core/demo-mode.md | 2 + .../zh/volume4/core/dict.md | 2 + .../zh/volume4/core/exception.md | 2 + .../zh/volume4/core/idempotent.md | 2 + .../zh/volume4/core/jwt.md | 2 + .../zh/volume4/core/login-log.md | 2 + .../zh/volume4/core/operation-log.md | 2 + .../zh/volume4/core/rate-limit.md | 2 + .../zh/volume4/core/rbac.md | 2 + .../zh/volume4/core/validator.md | 2 + DjangoAdmin_FastAPI_EleVue/zh/why.md | 2 +- .../.vitepress/config/extract.d.mts | 5 + .../.vitepress/config/extract.mjs | 130 ++++++++ .../.vitepress/config/index.ts | 8 + .../.vitepress/config/seo.ts | 311 ++++++++++++++++++ .../.vitepress/config/shared.ts | 6 +- .../.vitepress/config/zh.ts | 7 +- DjangoAdmin_FastAPI_NaiveVue/404.md | 12 + DjangoAdmin_FastAPI_NaiveVue/package.json | 3 +- DjangoAdmin_FastAPI_NaiveVue/public/llms.txt | 159 +++++++++ .../public/robots.txt | 33 ++ .../scripts/generate-llms-txt.mjs | 122 +++++++ DjangoAdmin_FastAPI_NaiveVue/zh/course.md | 2 + .../zh/introduction.md | 14 +- .../zh/other/declare.md | 4 + DjangoAdmin_FastAPI_NaiveVue/zh/struct.md | 6 + .../zh/volume2/code-list.md | 4 + .../zh/volume2/endpoint.md | 4 + .../zh/volume2/faq.md | 4 + .../zh/volume2/fe-api.md | 4 + .../zh/volume2/fe-router.md | 4 + .../zh/volume2/fe-view.md | 4 + .../zh/volume2/repository.md | 4 + .../zh/volume2/router.md | 4 + .../zh/volume2/schema.md | 4 + .../zh/volume2/service.md | 4 + .../zh/volume4/business/article.md | 2 + .../zh/volume4/business/category.md | 2 + .../zh/volume4/business/content.md | 2 + .../zh/volume4/business/dept.md | 2 + .../zh/volume4/business/job.md | 2 + .../zh/volume4/business/menu.md | 2 + .../zh/volume4/business/param.md | 2 + .../zh/volume4/business/role.md | 2 + .../zh/volume4/business/user.md | 2 + .../zh/volume4/core/captcha.md | 2 + .../zh/volume4/core/config.md | 2 + .../zh/volume4/core/cors.md | 2 + .../zh/volume4/core/demo-mode.md | 2 + .../zh/volume4/core/dict.md | 2 + .../zh/volume4/core/exception.md | 2 + .../zh/volume4/core/idempotent.md | 2 + .../zh/volume4/core/jwt.md | 2 + .../zh/volume4/core/login-log.md | 2 + .../zh/volume4/core/operation-log.md | 2 + .../zh/volume4/core/rate-limit.md | 2 + .../zh/volume4/core/rbac.md | 2 + .../zh/volume4/core/validator.md | 2 + DjangoAdmin_FastAPI_NaiveVue/zh/why.md | 2 +- .../.vitepress/config/en.ts | 2 +- .../.vitepress/config/extract.d.mts | 5 + .../.vitepress/config/extract.mjs | 130 ++++++++ .../.vitepress/config/index.ts | 8 + .../.vitepress/config/seo.ts | 311 ++++++++++++++++++ .../.vitepress/config/shared.ts | 4 +- .../.vitepress/config/zh.ts | 2 +- DjangoAdmin_Flask_AntdVue/404.md | 12 + DjangoAdmin_Flask_AntdVue/package.json | 3 +- DjangoAdmin_Flask_AntdVue/public/llms.txt | 169 ++++++++++ DjangoAdmin_Flask_AntdVue/public/robots.txt | 33 ++ .../scripts/generate-llms-txt.mjs | 122 +++++++ DjangoAdmin_Flask_AntdVue/zh/course.md | 2 + DjangoAdmin_Flask_AntdVue/zh/introduction.md | 6 + DjangoAdmin_Flask_AntdVue/zh/other/declare.md | 4 + DjangoAdmin_Flask_AntdVue/zh/struct.md | 2 + .../zh/volume2/blueprint.md | 4 + .../zh/volume2/code-list.md | 4 + .../zh/volume2/endpoint.md | 4 + DjangoAdmin_Flask_AntdVue/zh/volume2/faq.md | 4 + .../zh/volume2/fe-api.md | 4 + .../zh/volume2/fe-router.md | 4 + .../zh/volume2/fe-view.md | 4 + DjangoAdmin_Flask_AntdVue/zh/volume2/model.md | 4 + .../zh/volume2/repository.md | 4 + .../zh/volume2/router.md | 4 + .../zh/volume2/schema.md | 4 + .../zh/volume2/service.md | 4 + .../zh/volume4/business/article.md | 2 + .../zh/volume4/business/category.md | 2 + .../zh/volume4/business/city.md | 2 + .../zh/volume4/business/content.md | 2 + .../zh/volume4/business/dept.md | 2 + .../zh/volume4/business/example.md | 2 + .../zh/volume4/business/file-template.md | 2 + .../zh/volume4/business/job.md | 2 + .../zh/volume4/business/menu.md | 2 + .../zh/volume4/business/param.md | 2 + .../zh/volume4/business/role.md | 2 + .../zh/volume4/business/user.md | 2 + .../zh/volume4/core/captcha.md | 2 + .../zh/volume4/core/config.md | 2 + .../zh/volume4/core/demo-mode.md | 2 + .../zh/volume4/core/dict.md | 2 + .../zh/volume4/core/exception.md | 2 + .../zh/volume4/core/idempotent.md | 2 + .../zh/volume4/core/jwt.md | 2 + .../zh/volume4/core/login-log.md | 2 + .../zh/volume4/core/operation-log.md | 2 + .../zh/volume4/core/rbac.md | 2 + .../zh/volume4/core/transaction-decorator.md | 4 + .../zh/volume4/core/transaction.md | 4 + .../zh/volume4/core/validator.md | 2 + .../zh/volume4/tools/generator.md | 4 + DjangoAdmin_Flask_AntdVue/zh/why.md | 2 +- .../.vitepress/config/en.ts | 2 +- .../.vitepress/config/extract.d.mts | 5 + .../.vitepress/config/extract.mjs | 130 ++++++++ .../.vitepress/config/index.ts | 8 + .../.vitepress/config/seo.ts | 311 ++++++++++++++++++ .../.vitepress/config/shared.ts | 4 +- .../.vitepress/config/zh.ts | 2 +- DjangoAdmin_Flask_EleVue/404.md | 12 + DjangoAdmin_Flask_EleVue/package.json | 3 +- DjangoAdmin_Flask_EleVue/public/llms.txt | 169 ++++++++++ DjangoAdmin_Flask_EleVue/public/robots.txt | 33 ++ .../scripts/generate-llms-txt.mjs | 122 +++++++ DjangoAdmin_Flask_EleVue/zh/course.md | 2 + DjangoAdmin_Flask_EleVue/zh/introduction.md | 6 + DjangoAdmin_Flask_EleVue/zh/other/declare.md | 4 + DjangoAdmin_Flask_EleVue/zh/struct.md | 2 + .../zh/volume2/blueprint.md | 4 + .../zh/volume2/code-list.md | 4 + .../zh/volume2/endpoint.md | 4 + DjangoAdmin_Flask_EleVue/zh/volume2/faq.md | 4 + DjangoAdmin_Flask_EleVue/zh/volume2/fe-api.md | 4 + .../zh/volume2/fe-router.md | 4 + .../zh/volume2/fe-view.md | 4 + DjangoAdmin_Flask_EleVue/zh/volume2/model.md | 4 + .../zh/volume2/repository.md | 4 + DjangoAdmin_Flask_EleVue/zh/volume2/router.md | 4 + DjangoAdmin_Flask_EleVue/zh/volume2/schema.md | 4 + .../zh/volume2/service.md | 4 + .../zh/volume4/business/article.md | 2 + .../zh/volume4/business/category.md | 2 + .../zh/volume4/business/city.md | 2 + .../zh/volume4/business/content.md | 2 + .../zh/volume4/business/dept.md | 2 + .../zh/volume4/business/example.md | 2 + .../zh/volume4/business/file-template.md | 2 + .../zh/volume4/business/job.md | 2 + .../zh/volume4/business/menu.md | 2 + .../zh/volume4/business/param.md | 2 + .../zh/volume4/business/role.md | 2 + .../zh/volume4/business/user.md | 2 + .../zh/volume4/core/captcha.md | 2 + .../zh/volume4/core/config.md | 2 + .../zh/volume4/core/demo-mode.md | 2 + .../zh/volume4/core/dict.md | 2 + .../zh/volume4/core/exception.md | 2 + .../zh/volume4/core/idempotent.md | 2 + .../zh/volume4/core/jwt.md | 2 + .../zh/volume4/core/login-log.md | 2 + .../zh/volume4/core/operation-log.md | 2 + .../zh/volume4/core/rbac.md | 2 + .../zh/volume4/core/transaction-decorator.md | 4 + .../zh/volume4/core/transaction.md | 4 + .../zh/volume4/core/validator.md | 2 + .../zh/volume4/tools/generator.md | 4 + DjangoAdmin_Flask_EleVue/zh/why.md | 2 +- .../.vitepress/config/en.ts | 2 +- .../.vitepress/config/extract.d.mts | 5 + .../.vitepress/config/extract.mjs | 130 ++++++++ .../.vitepress/config/index.ts | 8 + .../.vitepress/config/seo.ts | 311 ++++++++++++++++++ .../.vitepress/config/shared.ts | 4 +- .../.vitepress/config/zh.ts | 2 +- DjangoAdmin_Flask_NaiveVue/404.md | 12 + DjangoAdmin_Flask_NaiveVue/package.json | 3 +- DjangoAdmin_Flask_NaiveVue/public/llms.txt | 169 ++++++++++ DjangoAdmin_Flask_NaiveVue/public/robots.txt | 33 ++ .../scripts/generate-llms-txt.mjs | 122 +++++++ DjangoAdmin_Flask_NaiveVue/zh/course.md | 2 + DjangoAdmin_Flask_NaiveVue/zh/introduction.md | 6 + .../zh/other/declare.md | 4 + DjangoAdmin_Flask_NaiveVue/zh/struct.md | 2 + .../zh/volume2/blueprint.md | 4 + .../zh/volume2/code-list.md | 4 + .../zh/volume2/endpoint.md | 4 + DjangoAdmin_Flask_NaiveVue/zh/volume2/faq.md | 4 + .../zh/volume2/fe-api.md | 4 + .../zh/volume2/fe-router.md | 4 + .../zh/volume2/fe-view.md | 4 + .../zh/volume2/model.md | 4 + .../zh/volume2/repository.md | 4 + .../zh/volume2/router.md | 4 + .../zh/volume2/schema.md | 4 + .../zh/volume2/service.md | 4 + .../zh/volume4/business/article.md | 2 + .../zh/volume4/business/category.md | 2 + .../zh/volume4/business/city.md | 2 + .../zh/volume4/business/content.md | 2 + .../zh/volume4/business/dept.md | 2 + .../zh/volume4/business/example.md | 2 + .../zh/volume4/business/file-template.md | 2 + .../zh/volume4/business/job.md | 2 + .../zh/volume4/business/menu.md | 2 + .../zh/volume4/business/param.md | 2 + .../zh/volume4/business/role.md | 2 + .../zh/volume4/business/user.md | 2 + .../zh/volume4/core/captcha.md | 2 + .../zh/volume4/core/config.md | 2 + .../zh/volume4/core/demo-mode.md | 2 + .../zh/volume4/core/dict.md | 2 + .../zh/volume4/core/exception.md | 2 + .../zh/volume4/core/idempotent.md | 2 + .../zh/volume4/core/jwt.md | 2 + .../zh/volume4/core/login-log.md | 2 + .../zh/volume4/core/operation-log.md | 2 + .../zh/volume4/core/rbac.md | 2 + .../zh/volume4/core/transaction-decorator.md | 4 + .../zh/volume4/core/transaction.md | 4 + .../zh/volume4/core/validator.md | 2 + .../zh/volume4/tools/generator.md | 4 + DjangoAdmin_Flask_NaiveVue/zh/why.md | 2 +- 501 files changed, 8295 insertions(+), 65 deletions(-) create mode 100644 DjangoAdmin_Django_AntdVue/.vitepress/config/extract.d.mts create mode 100644 DjangoAdmin_Django_AntdVue/.vitepress/config/extract.mjs create mode 100644 DjangoAdmin_Django_AntdVue/.vitepress/config/seo.ts create mode 100644 DjangoAdmin_Django_AntdVue/404.md create mode 100644 DjangoAdmin_Django_AntdVue/public/llms.txt create mode 100644 DjangoAdmin_Django_AntdVue/public/robots.txt create mode 100644 DjangoAdmin_Django_AntdVue/scripts/generate-llms-txt.mjs create mode 100644 DjangoAdmin_Django_EleVue/.vitepress/config/extract.d.mts create mode 100644 DjangoAdmin_Django_EleVue/.vitepress/config/extract.mjs create mode 100644 DjangoAdmin_Django_EleVue/.vitepress/config/seo.ts create mode 100644 DjangoAdmin_Django_EleVue/404.md create mode 100644 DjangoAdmin_Django_EleVue/public/llms.txt create mode 100644 DjangoAdmin_Django_EleVue/public/robots.txt create mode 100644 DjangoAdmin_Django_EleVue/scripts/generate-llms-txt.mjs create mode 100644 DjangoAdmin_Django_NaiveVue/.vitepress/config/extract.d.mts create mode 100644 DjangoAdmin_Django_NaiveVue/.vitepress/config/extract.mjs create mode 100644 DjangoAdmin_Django_NaiveVue/.vitepress/config/seo.ts create mode 100644 DjangoAdmin_Django_NaiveVue/404.md create mode 100644 DjangoAdmin_Django_NaiveVue/public/llms.txt create mode 100644 DjangoAdmin_Django_NaiveVue/public/robots.txt create mode 100644 DjangoAdmin_Django_NaiveVue/scripts/generate-llms-txt.mjs create mode 100644 DjangoAdmin_FastAPI_AntdVue/.vitepress/config/extract.d.mts create mode 100644 DjangoAdmin_FastAPI_AntdVue/.vitepress/config/extract.mjs create mode 100644 DjangoAdmin_FastAPI_AntdVue/.vitepress/config/seo.ts create mode 100644 DjangoAdmin_FastAPI_AntdVue/404.md create mode 100644 DjangoAdmin_FastAPI_AntdVue/public/llms.txt create mode 100644 DjangoAdmin_FastAPI_AntdVue/public/robots.txt create mode 100644 DjangoAdmin_FastAPI_AntdVue/scripts/generate-llms-txt.mjs create mode 100644 DjangoAdmin_FastAPI_EleVue/.vitepress/config/extract.d.mts create mode 100644 DjangoAdmin_FastAPI_EleVue/.vitepress/config/extract.mjs create mode 100644 DjangoAdmin_FastAPI_EleVue/.vitepress/config/seo.ts create mode 100644 DjangoAdmin_FastAPI_EleVue/404.md create mode 100644 DjangoAdmin_FastAPI_EleVue/public/llms.txt create mode 100644 DjangoAdmin_FastAPI_EleVue/public/robots.txt create mode 100644 DjangoAdmin_FastAPI_EleVue/scripts/generate-llms-txt.mjs create mode 100644 DjangoAdmin_FastAPI_NaiveVue/.vitepress/config/extract.d.mts create mode 100644 DjangoAdmin_FastAPI_NaiveVue/.vitepress/config/extract.mjs create mode 100644 DjangoAdmin_FastAPI_NaiveVue/.vitepress/config/seo.ts create mode 100644 DjangoAdmin_FastAPI_NaiveVue/404.md create mode 100644 DjangoAdmin_FastAPI_NaiveVue/public/llms.txt create mode 100644 DjangoAdmin_FastAPI_NaiveVue/public/robots.txt create mode 100644 DjangoAdmin_FastAPI_NaiveVue/scripts/generate-llms-txt.mjs create mode 100644 DjangoAdmin_Flask_AntdVue/.vitepress/config/extract.d.mts create mode 100644 DjangoAdmin_Flask_AntdVue/.vitepress/config/extract.mjs create mode 100644 DjangoAdmin_Flask_AntdVue/.vitepress/config/seo.ts create mode 100644 DjangoAdmin_Flask_AntdVue/404.md create mode 100644 DjangoAdmin_Flask_AntdVue/public/llms.txt create mode 100644 DjangoAdmin_Flask_AntdVue/public/robots.txt create mode 100644 DjangoAdmin_Flask_AntdVue/scripts/generate-llms-txt.mjs create mode 100644 DjangoAdmin_Flask_EleVue/.vitepress/config/extract.d.mts create mode 100644 DjangoAdmin_Flask_EleVue/.vitepress/config/extract.mjs create mode 100644 DjangoAdmin_Flask_EleVue/.vitepress/config/seo.ts create mode 100644 DjangoAdmin_Flask_EleVue/404.md create mode 100644 DjangoAdmin_Flask_EleVue/public/llms.txt create mode 100644 DjangoAdmin_Flask_EleVue/public/robots.txt create mode 100644 DjangoAdmin_Flask_EleVue/scripts/generate-llms-txt.mjs create mode 100644 DjangoAdmin_Flask_NaiveVue/.vitepress/config/extract.d.mts create mode 100644 DjangoAdmin_Flask_NaiveVue/.vitepress/config/extract.mjs create mode 100644 DjangoAdmin_Flask_NaiveVue/.vitepress/config/seo.ts create mode 100644 DjangoAdmin_Flask_NaiveVue/404.md create mode 100644 DjangoAdmin_Flask_NaiveVue/public/llms.txt create mode 100644 DjangoAdmin_Flask_NaiveVue/public/robots.txt create mode 100644 DjangoAdmin_Flask_NaiveVue/scripts/generate-llms-txt.mjs diff --git a/DjangoAdmin_Django_AntdVue/.vitepress/config/en.ts b/DjangoAdmin_Django_AntdVue/.vitepress/config/en.ts index a1a96ef..7c5fbe1 100644 --- a/DjangoAdmin_Django_AntdVue/.vitepress/config/en.ts +++ b/DjangoAdmin_Django_AntdVue/.vitepress/config/en.ts @@ -29,7 +29,7 @@ // // themeConfig: { // editLink: { -// pattern: "https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_EleVue", +// pattern: "https://gitee.com/djangoadmin/DjangoAdmin_Django_AntdVue", // text: "Suggest changes to this page", // }, // diff --git a/DjangoAdmin_Django_AntdVue/.vitepress/config/extract.d.mts b/DjangoAdmin_Django_AntdVue/.vitepress/config/extract.d.mts new file mode 100644 index 0000000..2a46233 --- /dev/null +++ b/DjangoAdmin_Django_AntdVue/.vitepress/config/extract.d.mts @@ -0,0 +1,5 @@ +export declare const SITE_URL: string; +export declare const SITE_DESCRIPTION: string; +export declare function stripNumberPrefix(title: string): string; +export declare function extractDescription(md: string): string; +export declare function extractFaqs(md: string): { q: string; a: string }[]; diff --git a/DjangoAdmin_Django_AntdVue/.vitepress/config/extract.mjs b/DjangoAdmin_Django_AntdVue/.vitepress/config/extract.mjs new file mode 100644 index 0000000..70e8db5 --- /dev/null +++ b/DjangoAdmin_Django_AntdVue/.vitepress/config/extract.mjs @@ -0,0 +1,130 @@ +/** + * SEO/GEO 共享工具（纯 ESM，零依赖）。 + * + * 同时被两类调用方 import： + * 1. VitePress 配置（.ts，esbuild 打包时内联本文件） + * 2. scripts/generate-llms-txt.mjs（Node 直接运行） + * + * 注意：SITE_URL 是全站唯一 URL 真相源。 + * docs 子域当前 TLS 证书为腾讯 CDN 默认证书（*.cdn.myqcloud.com，校验失败）， + * 故暂用 http；证书修复后只需改这里一处。 + */ + +export const SITE_URL = "http://docs.django.antdvue.djangoadmin.cn"; + +export const SITE_DESCRIPTION = + "DjangoAdmin 企业级中台解决方案 - Django + AntDesign 前后端分离版本"; + +/** + * 剥离 H1/标题中的章节编号前缀，用于 与 JSON-LD headline。 + * 例："5.10 字典模块" → "字典模块"；"K. 贡献指南" → "贡献指南"。 + * 页内 H1 与侧边栏编号保持不变，仅影响 SEO 输出。 + */ +export function stripNumberPrefix(title) { + return String(title) + .replace(/^(?:\d+(?:\.\d+)+|[A-Z]\.)\s+/, "") + .trim(); +} + +/** + * 从页面 Markdown 提取 meta description： + * 1. 首选 `:::tip xxx` 容器内的首句（141/143 页的标准 opener） + * 2. 回退到 H1 后的第一个普通段落 + * 输出压缩为单行、去除行内 Markdown，按中文句末标点截断（≤100 字符）。 + */ +export function extractDescription(md) { + const src = String(md); + const fm = src.match(/^---\r?\n([\s\S]*?)\r?\n---/); + const body = fm ? src.slice(fm[0].length) : src; + + let text = ""; + // frontmatter description 显式声明优先（无 H1 页面的补齐手段） + const fmDesc = fm && fm[1].match(/^description:\s*(.+)$/m); + if (fmDesc) { + text = fmDesc[1].trim().replace(/^["']|["']$/g, ""); + } + const tip = !text && body.match(/^:::\s*tip[^\n]*\n([\s\S]*?)\n:::/m); + if (tip) { + text = tip[1]; + } + if (!text) { + const afterH1 = body.match(/^# (?!#)(.+)$/m); + if (afterH1) { + const rest = body.slice((afterH1.index ?? 0) + afterH1[0].length); + const para = rest + .split(/\n{2,}/) + .find( + (p) => + p.trim() && + !/^\s*#/.test(p) && + !/^\s*:::/.test(p) && + !/^\s*```/.test(p) && + !/^\s*\|/.test(p), + ); + text = para || ""; + } + } + + text = text + .replace(/\s+/g, " ") + .replace(/`([^`]+)`/g, "$1") + .replace(/\*\*([^*]+)\*\*/g, "$1") + .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") + .trim(); + + if (!text) return ""; + + // 按中文句末标点截取首句，上限 100 字符；截断时避免切碎词 + const m = text.match(/^.{1,100}?(?:[。！？!?]|$)/); + let out = m ? m[0] : text.slice(0, 100); + if (out.length < text.length && !/[。！？!?]$/.test(out)) { + out = out.replace(/[^\s，、；：,;:]+$/, ""); + } + return out.trim() || text.slice(0, 100); +} + +function cleanText(s) { + return s + .replace(/^:::[^\n]*$/gm, "") + .replace(/^```[^\n]*$/gm, "") + .replace(/`([^`]+)`/g, "$1") + .replace(/\*\*([^*]+)\*\*/g, "$1") + .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") + .replace(/\s+/g, " ") + .trim(); +} + +/** + * 提取页面中的 Q/A 对（用于 FAQPage JSON-LD），支持两种站内格式： + * A. `### Q：问题` 标题式（如 zh/quickstart/faq.md） + * B. `**Q：问题**` 加粗式（如 zh/appendix/faq.md） + * 返回 [{ q, a }]；无匹配返回 []。 + */ +export function extractFaqs(md) { + const body = String(md).replace(/^---[\s\S]*?\n---\s*/, ""); + let faqs = []; + + // 格式 A：按 `### Q：` 切块，答案截断到下一个标题 + for (const part of body.split(/(?=^###\s*Q[：:])/m)) { + const m = part.match(/^###\s*Q[：:]\s*([^\n]+)\n+([\s\S]*)/); + if (!m) continue; + let a = m[2]; + const cut = a.search(/^#{1,4}\s/m); + if (cut >= 0) a = a.slice(0, cut); + faqs.push({ q: cleanText(m[1]), a: cleanText(a) }); + } + + // 格式 B：按 `**Q：` 切块 + if (!faqs.length) { + for (const part of body.split(/(?=^\*\*Q[：:])/m)) { + const m = part.match(/^\*\*Q[：:]\s*([^*]+)\*\*\s*\n+([\s\S]*)/); + if (!m) continue; + let a = m[2]; + const cut = a.search(/^(?:#{1,4}\s|\*\*Q)/m); + if (cut >= 0) a = a.slice(0, cut); + faqs.push({ q: cleanText(m[1]), a: cleanText(a) }); + } + } + + return faqs.filter((f) => f.q && f.a); +} diff --git a/DjangoAdmin_Django_AntdVue/.vitepress/config/index.ts b/DjangoAdmin_Django_AntdVue/.vitepress/config/index.ts index 2294856..6627a76 100644 --- a/DjangoAdmin_Django_AntdVue/.vitepress/config/index.ts +++ b/DjangoAdmin_Django_AntdVue/.vitepress/config/index.ts @@ -1,14 +1,22 @@ import { defineConfig } from "vitepress"; import { enConfig } from "./en"; +import { createSeoHooks } from "./seo"; import { sharedConfig } from "./shared"; import { zhConfig } from "./zh"; +const seo = createSeoHooks(zhConfig.themeConfig?.sidebar); + export default defineConfig({ ...sharedConfig, ignoreDeadLinks: [ (link) => link.includes('localhost'), ], + // SEO：页面级 title/description、canonical/OG/JSON-LD、sitemap+lastmod + transformPageData: seo.transformPageData, + transformHead: seo.transformHead, + sitemap: seo.sitemap, + locales: { root: { label: "简体中文", lang: "zh-CN", link: "/", ...zhConfig }, // root: { label: "English", lang: "en-US", link: "/", ...enConfig }, diff --git a/DjangoAdmin_Django_AntdVue/.vitepress/config/seo.ts b/DjangoAdmin_Django_AntdVue/.vitepress/config/seo.ts new file mode 100644 index 0000000..3176b6a --- /dev/null +++ b/DjangoAdmin_Django_AntdVue/.vitepress/config/seo.ts @@ -0,0 +1,311 @@ +/** + * SEO/GEO 构建期钩子（仅 Node 构建时运行，不进客户端 bundle）： + * - transformPageData：每页独立 title（去编号前缀）与 description（取 :::tip 首句） + * - transformHead：canonical / Open Graph / twitter 卡片 / JSON-LD 结构化数据 + * - sitemap.transformItems：注入 lastmod（git 最后提交时间）并过滤 404 + * + * 由 config/index.ts 通过 createSeoHooks(zhConfig.themeConfig?.sidebar) 挂载。 + * 依赖 extract.mjs（纯 ESM，同被 scripts/generate-llms-txt.mjs 复用）。 + */ +import fs from "node:fs"; +import path from "node:path"; +import { execSync } from "node:child_process"; +import { + SITE_URL, + extractDescription, + extractFaqs, + stripNumberPrefix, +} from "./extract.mjs"; + +/** 与 vitepress HeadConfig 同构：[tag, attrs, innerHTML?] */ +type HeadTuple = [string, Record<string, any>, string?]; + +interface SideItem { + text?: string; + link?: string; + items?: SideItem[]; +} + +interface PageDataLike { + relativePath?: string; + title?: string; + description?: string; + frontmatter?: Record<string, any>; + [k: string]: any; +} + +interface TransformCtx { + pageData?: PageDataLike; + title?: string; + description?: string; + content?: string; + siteConfig?: { root?: string; srcDir?: string }; +} + +const ORG = { + "@type": "Organization", + name: "DjangoAdmin", + url: "https://www.djangoadmin.cn", + logo: `${SITE_URL}/logo.png`, + sameAs: [ + "https://gitee.com/djangoadmin/DjangoAdmin_Django_AntdVue", + "https://www.djangoadmin.cn", + ], +}; + +/** 相对路径 → 站内路由（cleanUrls 关闭，正文页带 .html） */ +function routeOf(relativePath: string): string { + if (relativePath === "index.md") return "/"; + if (relativePath === "404.md") return "/404.html"; + return `/${relativePath.replace(/\.md$/, ".html")}`; +} + +/** 去掉侧边栏文案前导 emoji/符号，保留 "1.1 项目介绍" 这类编号文字 */ +function cleanLabel(s?: string): string { + return (s || "").replace(/^[^\p{L}\p{N}]+/u, "").trim(); +} + +/** 从侧边栏构建 route → 面包屑文案链（含分组小节） */ +function buildCrumbMap(sidebar: unknown): Map<string, string[]> { + const map = new Map<string, string[]>(); + const groups: SideItem[] = Array.isArray(sidebar) + ? sidebar + : ((sidebar as Record<string, SideItem[]>)?.["/zh/"] ?? []); + const walk = (items: SideItem[], trail: string[]) => { + for (const item of items) { + if (item.link && item.link.startsWith("/")) { + map.set(item.link, [...trail, cleanLabel(item.text)]); + } else if (item.items?.length) { + walk(item.items, [...trail, cleanLabel(item.text)]); + } + } + }; + for (const group of groups) { + walk(group.items ?? [], [cleanLabel(group.text)].filter(Boolean)); + } + return map; +} + +/** 从渲染后的 HTML 提取 H1 纯文本（JSON-LD headline 须与页面 H1 一致） */ +function h1OfHtml(html?: string): string { + const m = (html || "").match(/<h1[^>]*>([\s\S]*?)<\/h1>/i); + if (!m) return ""; + return m[1] + .replace(/<[^>]+>/g, "") + .replace(/&/g, "&") + .replace(/</g, "<") + .replace(/>/g, ">") + .replace(/"/g, '"') + .replace(/'/g, "'") + .trim(); +} + +/** 从 Markdown 源提取 H1 纯文本（去除行内 markdown 标记） */ +function h1OfMd(md: string): string { + // 围栏感知：跳过 ``` 代码块内的 # 注释，取真正的页面 H1 + let inFence = false; + for (const line of md.split("\n")) { + if (line.startsWith("```")) { inFence = !inFence; continue; } + if (!inFence && /^# (?!#)/.test(line)) { + return line + .replace(/^# /, "") + .replace(/`([^`]+)`/g, "$1") + .replace(/\*\*([^*]+)\*\*/g, "$1") + .trim(); + } + } + return ""; +} + +export function createSeoHooks(sidebar: unknown) { + const crumbs = buildCrumbMap(sidebar); + const projectDirs: string[] = []; + let gitDates: Map<string, string> | null = null; + + const readMd = (relativePath: string, srcDir?: string): string => { + try { + return fs.readFileSync( + path.resolve(srcDir || process.cwd(), relativePath), + "utf8", + ); + } catch { + return ""; + } + }; + + /** + * 项目内每个文件最后一次 git 提交的 ISO 时间。 + * 单次 git log 调用构建全量映射（key = 相对路径，与 pageData.relativePath 一致）； + * git 不可用时静默降级（sitemap 无 lastmod、JSON-LD 无 dateModified）。 + */ + const getGitDates = (root: string): Map<string, string> => { + if (gitDates) return gitDates; + gitDates = new Map<string, string>(); + try { + const out = execSync( + "git log --format=:::%cI --name-only --relative -n 500 -- .", + { + cwd: root, + encoding: "utf8", + maxBuffer: 64 * 1024 * 1024, + stdio: ["ignore", "pipe", "ignore"], + }, + ); + let current = ""; + for (const line of out.split(/\r?\n/)) { + if (line.startsWith(":::")) { + current = line.slice(3).trim(); + continue; + } + const file = line.trim(); + if (file && current && !gitDates.has(file)) { + gitDates.set(file, current); + } + } + } catch { + // 降级：无 lastmod / dateModified + } + return gitDates; + }; + + /** 每页独立 title（去 "5.10 " 编号前缀，关键词前置）与 description（:::tip 首句） */ + function transformPageData(pageData: PageDataLike, ctx?: any): Record<string, unknown> { + const srcDir: string | undefined = ctx?.siteConfig?.srcDir; + const root: string | undefined = ctx?.siteConfig?.root; + if (root && !projectDirs.includes(root)) projectDirs.push(root); + + const out: Record<string, unknown> = {}; + const rel = pageData.relativePath; + if (rel && !pageData.frontmatter?.description) { + const desc = extractDescription(readMd(rel, srcDir)); + if (desc) out.description = desc; + } + if (pageData.title) { + out.title = stripNumberPrefix(pageData.title); + } + return out; + } + + /** 构建期注入 canonical / OG / twitter / JSON-LD */ + function transformHead(ctx: TransformCtx): HeadTuple[] { + const rel = ctx?.pageData?.relativePath || ""; + if (!rel || rel === "404.md") return []; + + const route = routeOf(rel); + const url = `${SITE_URL}${route}`; + const title = ctx.pageData?.title || ctx.title || ""; + const desc = ctx.description || ""; + const isHome = rel === "index.md"; + const image = `${SITE_URL}/logo.png`; + + const heads: HeadTuple[] = [ + ["link", { rel: "canonical", href: url }], + ["meta", { property: "og:type", content: isHome ? "website" : "article" }], + ["meta", { property: "og:site_name", content: "DjangoAdmin" }], + ["meta", { property: "og:locale", content: "zh_CN" }], + ["meta", { property: "og:title", content: title }], + ["meta", { property: "og:description", content: desc }], + ["meta", { property: "og:url", content: url }], + ["meta", { property: "og:image", content: image }], + ["meta", { property: "twitter:title", content: title }], + ["meta", { property: "twitter:description", content: desc }], + ["meta", { property: "twitter:url", content: url }], + ["meta", { property: "twitter:image", content: image }], + ]; + + // ---- JSON-LD ---- + const root = ctx.siteConfig?.root || projectDirs[0] || process.cwd(); + const srcDir = ctx.siteConfig?.srcDir || root; + const lastMod = getGitDates(root).get(rel); + const blocks: Record<string, any>[] = []; + + if (isHome) { + blocks.push({ + "@context": "https://schema.org", + "@type": "WebSite", + name: "DjangoAdmin 开发文档", + url: `${SITE_URL}/`, + inLanguage: "zh-CN", + description: desc, + }); + blocks.push({ "@context": "https://schema.org", ...ORG }); + } else { + const md = readMd(rel, srcDir); + const article: Record<string, any> = { + "@context": "https://schema.org", + "@type": "TechArticle", + headline: h1OfMd(md) || h1OfHtml(ctx.content) || title, + description: desc, + url, + inLanguage: "zh-CN", + mainEntityOfPage: { "@type": "WebPage", "@id": url }, + publisher: ORG, + }; + if (lastMod) article.dateModified = lastMod; + blocks.push(article); + + const trail = crumbs.get(route); + if (trail?.length) { + const items: Record<string, any>[] = [ + { "@type": "ListItem", position: 1, name: "首页", item: `${SITE_URL}/` }, + ]; + trail.forEach((name, i) => { + const node: Record<string, any> = { + "@type": "ListItem", + position: i + 2, + name, + }; + if (i === trail.length - 1) node.item = url; + items.push(node); + }); + blocks.push({ + "@context": "https://schema.org", + "@type": "BreadcrumbList", + itemListElement: items, + }); + } + + const faqs = extractFaqs(md); + if (faqs.length) { + blocks.push({ + "@context": "https://schema.org", + "@type": "FAQPage", + mainEntity: faqs.map((f) => ({ + "@type": "Question", + name: f.q, + acceptedAnswer: { "@type": "Answer", text: f.a }, + })), + }); + } + } + + // 转义 "<"，防止内容中出现 </script> 破坏注入 + const json = JSON.stringify(blocks).replace(/</g, "\\u003c"); + heads.push(["script", { type: "application/ld+json" }, json]); + return heads; + } + + /** sitemap.xml：过滤 404/README，注入 git lastmod */ + const sitemap = { + hostname: SITE_URL, + transformItems(items: { url: string; lastmod?: string }[]) { + const root = projectDirs[0] || process.cwd(); + const dates = getGitDates(root); + const out: { url: string; lastmod?: string }[] = []; + for (const item of items) { + // ⚠ vitepress 传入的 item.url 是相对路径（"404.html"、"zh/x.html"、""）， + // 无前导斜杠也无域名——hostname 由 SitemapStream 事后拼接。 + if (/(^|\/)404\.html$/.test(item.url)) continue; // 404 页不收录 + if (/(^|\/)README\.html$/.test(item.url)) continue; // 仓库 README 非文档页 + const p = item.url.replace(/^\//, ""); + const rel = + p === "" || p === "index.html" ? "index.md" : p.replace(/\.html$/, ".md"); + const lastmod = dates.get(rel); + out.push(lastmod ? { ...item, lastmod } : item); + } + return out; + }, + }; + + return { transformPageData, transformHead, sitemap }; +} diff --git a/DjangoAdmin_Django_AntdVue/.vitepress/config/shared.ts b/DjangoAdmin_Django_AntdVue/.vitepress/config/shared.ts index 2dda640..6b826eb 100644 --- a/DjangoAdmin_Django_AntdVue/.vitepress/config/shared.ts +++ b/DjangoAdmin_Django_AntdVue/.vitepress/config/shared.ts @@ -1,6 +1,6 @@ import { defineConfig, HeadConfig } from "vitepress"; -export const META_IMAGE = "/social.png"; +export const META_IMAGE = "/logo.png"; const rControl = /[\u0000-\u001f]/g; const rSpecial = /[\s~`!@#$%^&*()\-_+=[\]{}|\\;:"'“”‘’<>,.?/]+/g; @@ -23,6 +23,8 @@ export const slugify = (str: string): string => export const sharedConfig = defineConfig({ title: "小蚂蚁云", + // 页面 <title> 后缀：「环境准备 | DjangoAdmin 开发文档」（index.md frontmatter 可覆盖） + titleTemplate: "DjangoAdmin 开发文档", appearance: "light", markdown: { diff --git a/DjangoAdmin_Django_AntdVue/.vitepress/config/zh.ts b/DjangoAdmin_Django_AntdVue/.vitepress/config/zh.ts index 333cd20..a3f8a5c 100644 --- a/DjangoAdmin_Django_AntdVue/.vitepress/config/zh.ts +++ b/DjangoAdmin_Django_AntdVue/.vitepress/config/zh.ts @@ -1,6 +1,6 @@ import type { DefaultTheme, LocaleSpecificConfig } from "vitepress"; -export const META_URL = "https://www.djangoadmin.cn"; +export const META_URL = "http://docs.django.antdvue.djangoadmin.cn"; export const META_TITLE = "DjangoAdmin 企业级中台解决方案"; export const META_DESCRIPTION = "DjangoAdmin 企业级中台解决方案 - Django + AntDesign 前后端分离版本"; diff --git a/DjangoAdmin_Django_AntdVue/404.md b/DjangoAdmin_Django_AntdVue/404.md new file mode 100644 index 0000000..c344b20 --- /dev/null +++ b/DjangoAdmin_Django_AntdVue/404.md @@ -0,0 +1,12 @@ +--- +head: + - - meta + - name: robots + content: noindex +--- + +# 页面不存在 + +抱歉，您访问的页面不存在或已被移动。 + +[返回首页](/) · [浏览文档](/zh/introduction) diff --git a/DjangoAdmin_Django_AntdVue/package.json b/DjangoAdmin_Django_AntdVue/package.json index 77bd941..b5517ed 100644 --- a/DjangoAdmin_Django_AntdVue/package.json +++ b/DjangoAdmin_Django_AntdVue/package.json @@ -5,7 +5,8 @@ "type": "module", "scripts": { "docs": "vitepress dev .", - "docs:build": "vitepress build .", + "docs:llms": "node scripts/generate-llms-txt.mjs", + "docs:build": "node scripts/generate-llms-txt.mjs && vitepress build .", "docs:preview": "vitepress preview ." }, "dependencies": { diff --git a/DjangoAdmin_Django_AntdVue/public/llms.txt b/DjangoAdmin_Django_AntdVue/public/llms.txt new file mode 100644 index 0000000..108bf0e --- /dev/null +++ b/DjangoAdmin_Django_AntdVue/public/llms.txt @@ -0,0 +1,165 @@ +# DjangoAdmin Django+AntDesign 开发文档 + +> DjangoAdmin 企业级中台解决方案 - Django + AntDesign 前后端分离版本。内置 RBAC 权限体系、代码生成器等开箱即用功能，支持五种数据库一键切换。本文档共 135 篇，按章节组织。 + +## 1. 了解项目 + +- [1.1 项目介绍](http://docs.django.antdvue.djangoadmin.cn/zh/introduction.html): DjangoAdmin 是企业级中台解决方案，后端基于 Django + Django ORM，前端基于 Vue3 + AntDesign，内置 RBAC 权限、代码生成器等开箱即用功能， +- [更新日志](http://docs.django.antdvue.djangoadmin.cn/zh/changelog.html): 更新日志是项目演进的完整记录，帮助开发者和企业了解每个版本的能力变化与技术演进方向。 +- [新手入门指南](http://docs.django.antdvue.djangoadmin.cn/zh/course.html): 详细的安装步骤请参考 环境准备 章节。 +- [项目目录结构](http://docs.django.antdvue.djangoadmin.cn/zh/struct.html): 本页说明项目前后端目录组织与各目录职责，二次开发定位文件或了解工程结构时对照查阅。 +- [为什么选择我们](http://docs.django.antdvue.djangoadmin.cn/zh/why.html): 本页从低代码生成能力、功能开箱即用与工程可持续性三个维度说明选择本项目的理由，技术选型对比时可作为评估依据。 + +## 2. 快速入门 + +- [后端启动](http://docs.django.antdvue.djangoadmin.cn/zh/volume1/backend.html): 启动后端前，请确保已完成 环境准备 章节中的所有软件安装。 +- [数据库初始化](http://docs.django.antdvue.djangoadmin.cn/zh/volume1/database.html): 数据库初始化前，请确保已完成以下准备工作： 1. 目标数据库服务已启动（如 MySQL 8.0+） 2. .env 文件中的 DATABASE_ENGINE 和数据库连接信息已正确配置 3. +- [Docker 一键启动](http://docs.django.antdvue.djangoadmin.cn/zh/volume1/docker.html): 使用 Docker 方式启动前，请确保已安装以下软件： 1. Docker Desktop（Windows / macOS）或 Docker Engine（Linux） 2. Docker +- [环境变量速查表](http://docs.django.antdvue.djangoadmin.cn/zh/volume1/env-vars.html): 1. .env 文件包含项目的敏感配置信息，已被 .gitignore 忽略，不会提交到版本控制。 +- [环境准备](http://docs.django.antdvue.djangoadmin.cn/zh/volume1/environment.html): 1. 部分软件安装后需要设置本地环境变量，便于在终端中使用命令。 +- [常见问题FAQ](http://docs.django.antdvue.djangoadmin.cn/zh/volume1/faq.html): 遇到问题时，建议先查看终端日志输出和浏览器控制台（F12）的错误信息，通常能快速定位问题原因。 +- [第一个接口调试](http://docs.django.antdvue.djangoadmin.cn/zh/volume1/first-api.html): 开始调试前，请确保已完成以下步骤： 1. 后端服务已启动（参见 后端启动） 2. 数据库已初始化（参见 数据库初始化） 3. Redis 服务已启动 +- [前端启动](http://docs.django.antdvue.djangoadmin.cn/zh/volume1/frontend.html): 启动前端前，请确保已完成 环境准备 章节中的 Node.js 和 pnpm 安装，并已启动后端服务（参见 后端启动）。 + +## 3. 模块开发实战 + +- [完整代码清单](http://docs.django.antdvue.djangoadmin.cn/zh/volume2/code-list.html): 本页汇总案例管理（Example）模块涉及的全部文件代码，开发时可快速查阅与复制对照。 +- [常见问题与排错](http://docs.django.antdvue.djangoadmin.cn/zh/volume2/faq.html): 本页汇总模块开发过程中的常见问题与排错方法，开发受阻时按症状索引即可定位。 +- [前端 API 层](http://docs.django.antdvue.djangoadmin.cn/zh/volume2/fe-api.html): 前端 API 层封装后端接口的 HTTP 请求，每个业务模块对应一个 API 文件，本页讲解基于 Axios 封装的编写规范。 +- [前端路由与菜单](http://docs.django.antdvue.djangoadmin.cn/zh/volume2/fe-router.html): 本页讲解前端路由与菜单机制——路由和菜单由后端动态返回，前端只需注册路由组件映射。 +- [前端页面视图](http://docs.django.antdvue.djangoadmin.cn/zh/volume2/fe-view.html): 前端页面视图是用户直接交互的界面，本页讲解 Vue3 + AntDesign 下一个完整 CRUD 页面的文件组成与编写方式。 +- [表单验证（Form）](http://docs.django.antdvue.djangoadmin.cn/zh/volume2/form.html): 表单验证是模块开发的第二步，讲解基于 Django ModelForm 的提交数据校验与错误信息约定。 +- [数据模型（Model）](http://docs.django.antdvue.djangoadmin.cn/zh/volume2/model.html): 数据模型是模块开发的第一步，讲解如何用 Django ORM 与 BaseModel 定义数据库表结构，新建模块时从本页开始。 +- [模块开发实战概述](http://docs.django.antdvue.djangoadmin.cn/zh/volume2/overview.html): 本章以案例管理（Example）模块为完整案例，手把手演示从零开发一个业务模块的全流程，学完即可掌握项目中任意模块的开发方式。 +- [权限节点配置](http://docs.django.antdvue.djangoadmin.cn/zh/volume2/permission.html): 本页讲解接口权限字符串的定义与菜单权限节点的配置方法，联调 403 问题时对照本页。 +- [业务逻辑层（Service）](http://docs.django.antdvue.djangoadmin.cn/zh/volume2/service.html): 业务逻辑层是模块开发的核心，CRUD 操作、业务规则与数据处理均封装在 Service 层函数，本页讲解其编写规范。 +- [URL 路由配置](http://docs.django.antdvue.djangoadmin.cn/zh/volume2/url.html): URL 路由是模块开发的最后一步，本页讲解用 Django path() 将路径映射到视图类的配置方法。 +- [视图层（View）](http://docs.django.antdvue.djangoadmin.cn/zh/volume2/view.html): 视图层负责处理 HTTP 请求并调用 Service 业务逻辑，本页讲解 Django 类视图的编写方式与响应约定。 + +## 4. 架构设计 + +- [第四章 架构设计 - 核心基类体系](http://docs.django.antdvue.djangoadmin.cn/zh/volume3/base-classes.html): 本页汇总项目核心基类体系的总览与用法，编写业务代码前先了解可复用的基座能力。 +- [第四章 架构设计 - 缓存架构](http://docs.django.antdvue.djangoadmin.cn/zh/volume3/cache.html): 本页说明系统缓存架构的设计与使用方式，涉及缓存一致性或性能问题时查阅。 +- [数据库设计指南](http://docs.django.antdvue.djangoadmin.cn/zh/volume3/database-design-guide.html): 本文介绍本项目的数据库设计规范，包括表命名、字段类型选择、索引策略、常见表模式等。 +- [第四章 架构设计 - 数据库设计](http://docs.django.antdvue.djangoadmin.cn/zh/volume3/database-design.html): 本页说明数据库设计原则与表结构组织方式，建表或数据迁移时对照本页。 +- [第四章 架构设计 - 目录结构设计](http://docs.django.antdvue.djangoadmin.cn/zh/volume3/directory.html): 本页说明项目根目录与各层目录的组织设计，二次开发定位文件时对照查阅。 +- [第四章 架构设计 - 扩展性设计](http://docs.django.antdvue.djangoadmin.cn/zh/volume3/extensibility.html): 本页说明系统的扩展性设计原则，二次开发新增能力或改造现有模块时参考。 +- [第四章 架构设计 - 分层架构详解](http://docs.django.antdvue.djangoadmin.cn/zh/volume3/layer-arch.html): 本页详解后端分层架构的职责划分与调用关系，编写代码前先理解各层边界。 +- [第四章 架构设计 - 系统架构总览](http://docs.django.antdvue.djangoadmin.cn/zh/volume3/overview.html): 本页给出系统整体架构总览，理解各层职责与模块关系时从本页开始。 +- [性能优化指南](http://docs.django.antdvue.djangoadmin.cn/zh/volume3/performance.html): 本文介绍本项目中常见的性能优化策略，涵盖后端 ORM 查询、缓存、分页、前端加载等方面。 +- [第四章 架构设计 - 请求处理流程](http://docs.django.antdvue.djangoadmin.cn/zh/volume3/request-flow.html): 本页给出请求从进入路由到返回响应的全链路处理流程，排查接口问题时对照追踪。 +- [第四章 架构设计 - 安全架构](http://docs.django.antdvue.djangoadmin.cn/zh/volume3/security.html): 本页说明系统安全架构设计，含认证、权限与数据安全等防护机制。 +- [第四章 架构设计 - 技术栈选型](http://docs.django.antdvue.djangoadmin.cn/zh/volume3/tech-stack.html): 本页列出项目后端与前端完整技术选型及版本要求，评估兼容性或升级影响时对照本表。 + +## 5. 开发指南 + +- [API 接口速查表](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/api-cheatsheet.html): API 接口速查表，按模块分组列出所有 RESTful 接口的请求方法、路径、说明和权限标识。 +- [文章管理](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/business/article.html): 文章管理模块支持富文本编辑、分类关联、封面图片上传、图集管理等功能。 +- [分类管理](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/business/category.html): 分类管理模块用于管理树形分类数据，如文章分类、产品分类等。 +- [行政区划管理](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/business/city.html): 城市管理模块用于管理行政区划数据，支持省/市/区/街道/社区五级行政区划。 +- [公告与链接管理](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/business/content.html): 公告和链接是两个简单 CRUD 内容模块，提供标准的增删改查接口。 +- [部门/职级/岗位管理](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/business/dept.html): 部门、职级、岗位是组织架构管理的三个核心模块。 +- [定时任务](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/business/job.html): 定时任务模块基于 APScheduler 实现，支持 Cron 表达式调度、任务执行日志、动态启停等功能。 +- [菜单管理](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/business/menu.html): 菜单管理是 RBAC 权限系统的基础，负责管理系统的导航菜单和权限节点。 +- [参数管理](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/business/param.html): 参数管理模块用于管理动态系统参数，支持按参数键查询、修改，无需重启服务即可生效。 +- [角色管理](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/business/role.html): 角色是 RBAC 权限模型的核心，连接用户和菜单（权限）。 +- [用户管理](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/business/user.html): 用户管理是系统的核心模块，属于复杂业务模块。 +- [认证流程实战](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/core/auth-flow.html): 登录 -> Token 获取 -> 权限校验 -> Token 刷新 -> 退出登录的完整认证链路实战说明。 +- [验证码机制](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/core/captcha.html): 验证码是防止自动化攻击的重要安全手段。 +- [系统配置管理](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/core/config.html): 系统配置模块用于管理动态的键值对配置项，与数据字典类似但更偏向系统级参数。 +- [跨域资源共享（CORS）](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/core/cors.html): CORS（Cross-Origin Resource Sharing）跨域资源共享是前后端分离架构必须处理的问题。 +- [演示模式](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/core/demo-mode.html): 演示模式用于在线体验环境，开启后所有写操作（新增、编辑、删除等）将被拦截，返回"演示环境，暂无操作权限"提示。 +- [数据字典使用指南](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/core/dict-guide.html): 数据字典的完整使用流程，从新增字典类型到在代码中使用字典数据的实操指南。 +- [字典模块](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/core/dict.html): 数据字典用于管理系统中的枚举值和配置项，如状态、类型、性别等。 +- [异常与响应处理](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/core/exception.html): 定义了统一的响应格式和全局异常处理机制。 +- [防重复提交](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/core/idempotent.html): 防重复提交是保障数据一致性的重要措施。 +- [用户认证（JWT）](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/core/jwt.html): JWT（JSON Web Token）是系统的核心认证机制。 +- [登录日志](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/core/login-log.html): 登录日志记录每次登录尝试（成功/失败），包含登录账号、IP地址、浏览器信息、登录时间等。 +- [操作日志](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/core/operation-log.html): 操作日志通过 @operation_log 装饰器标记需要记录日志的视图方法，自动记录请求参数、响应结果、耗时、操作类型等信息。 +- [请求限流](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/core/rate-limit.html): 请求限流可通过中间件实现 IP 级别的限流，防止恶意请求和 DoS 攻击。 +- [权限管理（RBAC）](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/core/rbac.html): 采用基于角色的访问控制（RBAC）模型，通过用户-角色-菜单三层关系实现细粒度的权限管理。 +- [参数验证（Form）](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/core/validator.html): 使用 Django ModelForm 进行请求参数验证。 +- [API 层开发](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/frontend/api.html): 前端 API 层位于 src/api/ 目录，封装所有与后端的 HTTP 请求。 +- [前端构建](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/frontend/build.html): 前端使用 Vite 构建，支持开发服务器和生产构建。 +- [公共组件库](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/frontend/components.html): 项目提供丰富的公共组件，位于 ui/src/components/ 目录，基于 Ant Design Vue 二次封装，覆盖表格、表单、弹窗、上传、富文本编辑等常见场景。 +- [BasicForm 表单](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/frontend/form.html): BasicForm 位于 src/components/Form/src/BasicForm.vue，基于 Ant Design Vue 的 a-form 二次封装，通过 schemas +- [Hooks 组合式函数](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/frontend/hooks.html): 项目封装了一系列组合式函数（Hooks），位于 src/hooks/ 和 src/utils/ 目录，提供权限检查、异步 loading、防重复提交、实时时钟、项目配置等可复用逻辑。 +- [国际化](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/frontend/i18n.html): 当前项目仅支持中文界面，Ant Design Vue 默认支持中文，所有界面文本直接硬编码在组件中。 +- [Modal 弹窗](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/frontend/modal.html): 项目提供 BasicModal 组件（src/components/Modal/src/basicModal.vue）和原生 a-modal 两种弹窗用法。 +- [权限指令 v-perm](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/frontend/perm-directive.html): v-perm 和 v-perms 是项目自定义的 Vue 指令，用于按钮级别的权限控制，无权限时自动从 DOM 中移除元素。 +- [路由与菜单](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/frontend/router.html): 前端路由基于 Vue Router 4 实现动态路由生成，菜单数据从后端获取，通过 generator-routers.ts 递归生成路由表，路由守卫控制登录状态和权限。 +- [前端环境与结构](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/frontend/setup.html): 前端基于 Vue3 + Ant Design Vue 构建，使用 pnpm 作为包管理工具，Vite 作为构建工具，TypeScript 作为开发语言。 +- [Store 状态管理](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/frontend/store.html): 前端使用 Pinia 进行状态管理，核心模块包括 user（用户信息与权限）、asyncRoute（动态路由与菜单）、projectSetting（项目配置）、designSetting（主题设计）等。 +- [样式与主题](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/frontend/style.html): 前端样式方案采用 Tailwind CSS + SCSS + Ant Design Vue 主题覆盖，支持深色模式切换。 +- [BasicTable 表格](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/frontend/table.html): BasicTable 位于 src/components/Table/src/Table.vue，基于 Ant Design Vue 的 a-table 二次封装，提供列定义、数据请求、分页、操作列、 +- [工具函数](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/frontend/utils.html): 前端工具函数位于 src/utils/ 目录，提供认证管理、本地存储、日期格式化、树结构操作、文件下载等通用能力。 +- [页面视图开发](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/frontend/view.html): 页面视图位于 src/views/ 目录，每个业务模块遵循 index.vue（列表页）+ edit.vue（编辑弹窗）+ detail.vue（详情弹窗）的标准模式，辅以 +- [接口响应规范](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/integration/api-contract.html): 后端所有接口统一返回 R.ok() / R.failed() 格式的 JSON 响应，前端通过 VAxios 的 transformRequestData 拦截器统一解包处理。 +- [字典数据联调](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/integration/dict-sync.html): 字典数据通过后端字典 API 获取，前端在下拉选择器中渲染选项。 +- [权限节点联动](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/integration/perm-sync.html): 前后端权限通过统一的权限节点字符串联动，后端 PermissionRequired 中间件校验权限，前端 v-perm 指令和 TableAction 的 auth 属性控制按钮显示。 +- [代理配置](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/integration/proxy.html): 开发环境通过 Vite 代理转发 API 请求到后端 Django 服务，生产环境通过 Nginx 代理。 +- [文件上传联调](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/integration/upload-sync.html): 文件上传涉及前端 Upload 组件、后端上传接口和 URL 拼接三个环节，需要前后端协同配置。 +- [数据库与 ORM](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/tools/db-session.html): 项目使用 Django ORM 作为数据库访问层，数据库连接配置位于 config/env.py 和 application/settings.py。 +- [导入导出](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/tools/excel.html): 基于 openpyxl 实现 Excel 导入导出功能，支持通过 file_template 模块管理导入模板配置。 +- [IP/UA 解析](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/tools/ip-ua.html): 提供客户端 IP 获取、IP 地理位置查询和 User-Agent 解析三大能力，位于 utils/common.py。 +- [日志系统](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/tools/logger.html): 通过 Python 标准库 logging 实现结构化日志，Django 框架内置日志配置，支持控制台 + 文件双输出。 +- [密码工具](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/tools/password.html): 密码加密使用 Django 内置的 make_password 和 check_password 函数，基于 PBKDF2 算法（默认工作因子 320000 次迭代）。 +- [权限缓存](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/tools/perm-cache.html): 通过 Redis 实现用户权限和菜单的缓存，采用用户级缓存 + 全局版本号双层策略。 +- [请求解析工具](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/tools/request-util.html): utils/common.py 提供请求数据解析相关的工具函数，核心函数 parse_request_body() 用于解析请求体 JSON 数据。 +- [富文本过滤](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/tools/rich-text.html): 富文本编辑器内容存在存储型 XSS 风险，通过 save_content() 函数实现 HTML 内容处理，在落盘前统一过滤危险内容并迁移嵌入图片。 +- [文件上传完整流程](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/tools/upload-guide.html): 富文本编辑器（如 WangEditor 等）的图片上传同样使用此接口。 +- [文件上传](http://docs.django.antdvue.djangoadmin.cn/zh/volume4/tools/upload.html): 提供本地文件上传功能，支持图片和通用文件上传，内置扩展名白名单校验。 + +## 6. 代码生成器 + +- [CLI 命令行使用](http://docs.django.antdvue.djangoadmin.cn/zh/volume5/cli.html): 代码生成器 CLI 模式的使用方法，包括单表生成、预览模式和配置导出。 +- [代码生成引擎](http://docs.django.antdvue.djangoadmin.cn/zh/volume5/code-engine.html): 代码生成引擎的工作原理，包括配置解析、模板渲染、文件写入和自动注册的完整流程。 +- [配置文件详解](http://docs.django.antdvue.djangoadmin.cn/zh/volume5/config.html): 代码生成器 JSON 配置文件的格式说明，包括模块名称、字段属性等配置项的详细解释。 +- [实战案例](http://docs.django.antdvue.djangoadmin.cn/zh/volume5/demo.html): 以 django_example 演示表为完整案例，演示从建表到生成到使用的全流程。 +- [常见问题](http://docs.django.antdvue.djangoadmin.cn/zh/volume5/faq.html): 代码生成器使用过程中常见问题的原因分析和解决方案。 +- [概述与架构](http://docs.django.antdvue.djangoadmin.cn/zh/volume5/overview.html): 代码生成器的整体架构、核心模块和生成流程概述。 +- [表结构解析引擎](http://docs.django.antdvue.djangoadmin.cn/zh/volume5/parser.html): 表结构解析引擎的工作原理，从数据库读取表元数据并智能推断字段用途的过程。 +- [自定义模板](http://docs.django.antdvue.djangoadmin.cn/zh/volume5/templates.html): 代码生成器模板的 Jinja2 语法说明，包括模板变量、字段属性和自定义模板的开发方法。 +- [Web 管理界面](http://docs.django.antdvue.djangoadmin.cn/zh/volume5/web-ui.html): 代码生成器 Web 管理界面的使用方法，通过可视化界面操作单表生成和批量生成。 + +## 7. 运维部署 + +- [备份与恢复](http://docs.django.antdvue.djangoadmin.cn/zh/volume6/backup.html): - 3 份数据副本（1 份生产 + 2 份备份） - 2 种不同存储介质（如本地磁盘 + 远程存储） - 1 份异地备份（防机房级灾难） +- [CI/CD 流水线配置](http://docs.django.antdvue.djangoadmin.cn/zh/volume6/ci-cd.html): CI/CD（持续集成/持续部署）是现代开发流程的基础设施。 +- [数据库迁移](http://docs.django.antdvue.djangoadmin.cn/zh/volume6/db-migrate.html): - 结构迁移：Django 内置迁移系统（makemigrations + migrate） - 字段注释：Django 4.1+ 通过 db_comment 参数自动添加数据库字段注释 +- [部署 Checklist](http://docs.django.antdvue.djangoadmin.cn/zh/volume6/deploy-checklist.html): 从服务器准备到应用上线的完整部署操作清单，适用于生产环境首次部署和后续版本更新。 +- [Docker容器化](http://docs.django.antdvue.djangoadmin.cn/zh/volume6/docker.html): - 环境一致性：消除"在我机器上能跑"的问题 - 快速部署：一条命令启动完整服务 - 资源隔离：应用与宿主机环境解耦 +- [环境规划](http://docs.django.antdvue.djangoadmin.cn/zh/volume6/env-plan.html): 各环境之间保持代码一致，仅通过环境变量（.env）区分配置。 +- [健康检查与监控](http://docs.django.antdvue.djangoadmin.cn/zh/volume6/monitoring.html): `` 1. 应用层：健康检查端点、业务指标 2. 系统层：CPU/内存/磁盘/网络 3. 中间件：MySQL/Redis 连接状态 4. 日志：集中式日志收集与分析 `` +- [Nginx 反向代理](http://docs.django.antdvue.djangoadmin.cn/zh/volume6/nginx.html): `` 客户端 -> Nginx（80/443） ├─ / -> 前端静态资源（dist/） ├─ /api/... -> Django 后端（8000） ├─ /static/ -> Django +- [性能调优](http://docs.django.antdvue.djangoadmin.cn/zh/volume6/performance.html): 1. 先测量，后优化：用数据说话，避免盲目调参 2. 瓶颈优先：找到最大瓶颈，集中优化 3. 渐进式：每次只调整一个参数，观察效果 +- [多实例与负载均衡](http://docs.django.antdvue.djangoadmin.cn/zh/volume6/scaling.html): 当单台服务器无法满足性能需求时，需要通过多实例部署和负载均衡来提升系统吞吐量。 +- [安全加固](http://docs.django.antdvue.djangoadmin.cn/zh/volume6/security-hardening.html): - 最小权限：只开放必要的端口和权限 - 纵深防御：多层安全措施叠加 - 默认安全：配置默认值应为安全选项 +- [Supervisor进程管理](http://docs.django.antdvue.djangoadmin.cn/zh/volume6/supervisor.html): - Linux 服务器直接部署（非 Docker） - 需要进程自动重启和日志轮转 - 管理多个相关进程 +- [故障排查手册](http://docs.django.antdvue.djangoadmin.cn/zh/volume6/troubleshooting.html): 1. 查看日志：tail -f logs/supervisor.out.log 或 docker-compose logs -f 2. 检查配置：.env 文件、数据库连接、Redis 连接 3. +- [版本升级流程](http://docs.django.antdvue.djangoadmin.cn/zh/volume6/upgrade.html): 1. 先备份，后升级 2. 先测试环境，后生产环境 3. 每次升级可回滚 4. 低峰期执行升级 + +## 8. 规范标准 + +- [API响应规范](http://docs.django.antdvue.djangoadmin.cn/zh/volume7/api-response.html): - 所有接口必须通过 R.ok() 或 R.failed() 返回，禁止直接返回 dict - 成功响应 code=0，失败响应 code=1 - 响应体始终包含 code、data、msg、ok +- [代码审查清单](http://docs.django.antdvue.djangoadmin.cn/zh/volume7/code-review.html): - 每次提交必须经过至少一人审查 - 审查关注点：正确性 > 安全性 > 可维护性 > 性能 - 审查意见应具体、可操作，避免主观评价 +- [代码风格与 Lint 规范](http://docs.django.antdvue.djangoadmin.cn/zh/volume7/code-style.html): 统一的代码风格是团队协作的基础。 +- [删除规范](http://docs.django.antdvue.djangoadmin.cn/zh/volume7/deletion.html): - is_delete = False（0）：正常记录（默认值） - is_delete = True（1）：已删除记录 - 所有查询方法自动过滤 is_delete=False，业务层无需关心 +- [文档规范](http://docs.django.antdvue.djangoadmin.cn/zh/volume7/doc-standard.html): - 文档与代码同步更新 - 使用中文编写（项目约定） - 示例代码可直接运行 +- [前端 API 规范](http://docs.django.antdvue.djangoadmin.cn/zh/volume7/fe-api.html): - 每个后端模块对应一个 API 文件 - 函数命名统一使用 名词 + 动词 格式（与后端保持一致） - 请求路径使用相对路径（/position/page），不含 /api/v1 前缀（由 +- [前端页面规范](http://docs.django.antdvue.djangoadmin.cn/zh/volume7/fe-component.html): - Vue3（Composition API + <script setup>） - Ant Design Vue 3.x - 自定义组件（BasicTable / BasicForm / +- [Form层规范](http://docs.django.antdvue.djangoadmin.cn/zh/volume7/form.html): - 继承 forms.ModelForm - 每个字段定义中文 error_messages - 使用 Meta.fields 指定验证字段 - 验证在 Service 层 ORM 操作之前执行 +- [Git提交规范](http://docs.django.antdvue.djangoadmin.cn/zh/volume7/git.html): `` <type>(<scope>): <subject> <body> <footer> `` +- [Model层规范](http://docs.django.antdvue.djangoadmin.cn/zh/volume7/model.html): - 所有模型继承 BaseModel - 字段命名使用 snake_case - 每个字段必须有 db_comment 注释 - 使用 get_table_name() 生成表名 +- [分页规范](http://docs.django.antdvue.djangoadmin.cn/zh/volume7/pagination.html): - 前端传递 pageNo（页码，从 1 开始）和 pageSize（每页条数） - 后端返回 {records, total, size, current, pages} 结构 - 默认每页 10 +- [Service层规范](http://docs.django.antdvue.djangoadmin.cn/zh/volume7/service.html): - 所有业务逻辑集中在 Service 层 - View 层只负责接收请求和返回响应 - Model 层只负责数据定义 - Form 层只负责数据验证 +- [测试最佳实践](http://docs.django.antdvue.djangoadmin.cn/zh/volume7/testing-best-practices.html): 本文在 测试规范 基础上，介绍更高级的测试技巧，包括 Mock、Fixture、API 测试、覆盖率实战等。 +- [测试规范](http://docs.django.antdvue.djangoadmin.cn/zh/volume7/testing.html): 1. 单元测试（Unit）：验证单个函数/方法的逻辑正确性 2. 集成测试（Integration）：验证模块间协作、真实数据库操作 +- [View层规范](http://docs.django.antdvue.djangoadmin.cn/zh/volume7/view.html): - 使用类视图（继承 View） - 通过 @method_decorator(check_login) 验证登录 - 通过 PermissionRequired mixin 检查权限 - 通过 + +## 附录 + +- [常见问题汇总](http://docs.django.antdvue.djangoadmin.cn/zh/faq.html): 本页汇总了项目各模块的常见问题及解决方案，按场景分类索引。 +- [贡献指南](http://docs.django.antdvue.djangoadmin.cn/zh/other/contributing.html): 本页介绍如何参与项目贡献，包括代码提交、Issue 反馈与 PR 流程，欢迎关注本项目的开发者参阅。 +- [免责声明](http://docs.django.antdvue.djangoadmin.cn/zh/other/declare.html): 使用本产品前必读的法律声明，明确产品性质、使用限制与责任划分，一旦使用本产品即视为接受本声明全部条款。 +- [广告赞助](http://docs.django.antdvue.djangoadmin.cn/zh/other/sponsor.html): 1. 投放广告不得与官方全系产品存在结构性冲突和竞争 2. 广告内容需符合国家法律法规，不得包含虚假、误导性信息 3. 广告素材需经官方审核通过后方可上线，审核周期 1-3 个工作日 4. diff --git a/DjangoAdmin_Django_AntdVue/public/robots.txt b/DjangoAdmin_Django_AntdVue/public/robots.txt new file mode 100644 index 0000000..136eebb --- /dev/null +++ b/DjangoAdmin_Django_AntdVue/public/robots.txt @@ -0,0 +1,33 @@ +# DjangoAdmin Django+AntDesign 开发文档 +User-agent: * +Allow: / + +# 显式放行生成式引擎 / AI 爬虫（GEO） +User-agent: GPTBot +Allow: / + +User-agent: ChatGPT-User +Allow: / + +User-agent: ClaudeBot +Allow: / + +User-agent: Claude-Web +Allow: / + +User-agent: anthropic-ai +Allow: / + +User-agent: PerplexityBot +Allow: / + +User-agent: Google-Extended +Allow: / + +User-agent: Bytespider +Allow: / + +User-agent: bingbot +Allow: / + +Sitemap: http://docs.django.antdvue.djangoadmin.cn/sitemap.xml diff --git a/DjangoAdmin_Django_AntdVue/scripts/generate-llms-txt.mjs b/DjangoAdmin_Django_AntdVue/scripts/generate-llms-txt.mjs new file mode 100644 index 0000000..bd84ff3 --- /dev/null +++ b/DjangoAdmin_Django_AntdVue/scripts/generate-llms-txt.mjs @@ -0,0 +1,122 @@ +#!/usr/bin/env node +/** + * 生成 public/llms.txt（llmstxt.org 标准）——AI 爬虫的站点摘要索引。 + * + * 数据源：zh 目录下全部 Markdown 的 H1 + :::tip 概述首句（与 meta + * description 同源，复用 .vitepress/config/extract.mjs）。按侧边栏章节分组。 + * + * 用法：node scripts/generate-llms-txt.mjs + * 已挂入 package.json 的 docs:build 前置步骤。 + */ +import fs from "node:fs"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; +import { + SITE_URL, + SITE_DESCRIPTION, + extractDescription, +} from "../.vitepress/config/extract.mjs"; + +const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."); +const ZH = path.join(ROOT, "zh"); + +/** 顶层目录 → 侧边栏章节名（与 .vitepress/config/zh.ts 保持一致） */ +const SECTIONS = [ + ["", "1. 了解项目"], + ["volume1", "2. 快速入门"], + ["volume2", "3. 模块开发实战"], + ["volume3", "4. 架构设计"], + ["volume4", "5. 开发指南"], + ["volume5", "6. 代码生成器"], + ["volume6", "7. 运维部署"], + ["volume7", "8. 规范标准"], + ["other", "附录"], +]; + +function walk(dir, out = []) { + for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { + const p = path.join(dir, entry.name); + if (entry.isDirectory()) walk(p, out); + else if (entry.name.endsWith(".md")) out.push(p); + } + return out; +} + +/** 提取首个 H1 文本 */ +function h1Of(md) { + // 围栏感知：跳过 ``` 代码块内的 # 注释，取真正的页面 H1 + let inFence = false; + for (const line of md.split("\n")) { + if (line.startsWith("```")) { inFence = !inFence; continue; } + if (!inFence && line.startsWith("# ") && !line.startsWith("## ")) { + return line.slice(2).trim(); + } + } + return ""; +} + +/** H1 编号排序键："5.10 x" → [5,10]；无编号排最后 */ +function sortKey(h1) { + const m = h1.match(/^(\d+(?:\.\d+)*)/); + if (m) return m[1].split(".").map(Number); + const letter = h1.match(/^([A-Z])\./); + if (letter) return [1000 + letter[1].charCodeAt(0)]; + return [9999]; +} + +function cmpKey(a, b) { + const len = Math.max(a.length, b.length); + for (let i = 0; i < len; i++) { + const x = a[i] ?? 0; + const y = b[i] ?? 0; + if (x !== y) return x - y; + } + return 0; +} + +const files = walk(ZH); +const groups = new Map(SECTIONS.map(([dir, label]) => [label, []])); + +for (const file of files) { + const rel = path.relative(ZH, file).replace(/\\/g, "/"); + const topDir = rel.includes("/") ? rel.split("/")[0] : ""; + const base = rel.split("/").pop(); + const label = (topDir === "" && base === "faq.md") ? "附录" + : SECTIONS.find(([dir]) => dir === topDir)?.[1] ?? "附录"; + + const md = fs.readFileSync(file, "utf8"); + const h1 = h1Of(md); + if (!h1) continue; + const desc = extractDescription(md); + const url = `${SITE_URL}/zh/${rel.replace(/\.md$/, ".html")}`; + groups.get(label).push({ h1, desc, url, key: sortKey(h1) }); +} + +const lines = [ + "# DjangoAdmin Django+AntDesign 开发文档", + "", + `> ${SITE_DESCRIPTION}。内置 RBAC 权限体系、代码生成器等开箱即用功能，支持五种数据库一键切换。本文档共 ${files.length} 篇，按章节组织。`, + "", +]; + +// 按章节顺序输出，合并重复 label（appendix/other 同为「附录」，只输出一次） +const printed = new Set(); +for (const [, label] of SECTIONS) { + if (printed.has(label)) continue; + const items = groups.get(label); + if (!items?.length) continue; + printed.add(label); + + lines.push(`## ${label}`, ""); + items.sort((a, b) => cmpKey(a.key, b.key)); + for (const { h1, desc, url } of items) { + lines.push(desc ? `- [${h1}](${url}): ${desc}` : `- [${h1}](${url})`); + } + lines.push(""); +} + +const out = path.join(ROOT, "public", "llms.txt"); +fs.writeFileSync(out, lines.join("\n"), "utf8"); +console.log( + `llms.txt: ${files.length} 页 → ${path.relative(ROOT, out)} (${printed.size} 个章节)`, +); diff --git a/DjangoAdmin_Django_AntdVue/zh/course.md b/DjangoAdmin_Django_AntdVue/zh/course.md index fff9470..1e482f6 100644 --- a/DjangoAdmin_Django_AntdVue/zh/course.md +++ b/DjangoAdmin_Django_AntdVue/zh/course.md @@ -1,3 +1,5 @@ +# 新手入门指南 + :::warning 特别提醒 官方精心制作本教程，目的在于方便用户快速掌握软件产品的使用和部署。通过此教程，刚入行的开发者也可以快速掌握并投入产品研发。本地部署时务必请耐心阅读文档操作。 ::: diff --git a/DjangoAdmin_Django_AntdVue/zh/introduction.md b/DjangoAdmin_Django_AntdVue/zh/introduction.md index a547261..8f6b76c 100644 --- a/DjangoAdmin_Django_AntdVue/zh/introduction.md +++ b/DjangoAdmin_Django_AntdVue/zh/introduction.md @@ -1,3 +1,9 @@ +# 1.1 项目介绍 + +:::tip 概述 +DjangoAdmin 是企业级中台解决方案，后端基于 Django + Django ORM，前端基于 Vue3 + AntDesign，内置 RBAC 权限、代码生成器等开箱即用功能，支持五种数据库一键切换。 +::: + <div align="center"> <p align="center"> <img src="/logo.png" height="150" alt="logo"/> diff --git a/DjangoAdmin_Django_AntdVue/zh/other/contributing.md b/DjangoAdmin_Django_AntdVue/zh/other/contributing.md index 2d327c8..d257faf 100644 --- a/DjangoAdmin_Django_AntdVue/zh/other/contributing.md +++ b/DjangoAdmin_Django_AntdVue/zh/other/contributing.md @@ -1,7 +1,7 @@ # 贡献指南 :::tip 说明 -感谢你对本项目的关注！本文档介绍如何参与项目贡献，包括代码提交、Issue 反馈、PR 流程等。 +本页介绍如何参与项目贡献，包括代码提交、Issue 反馈与 PR 流程，欢迎关注本项目的开发者参阅。 ::: ## 开发环境搭建 diff --git a/DjangoAdmin_Django_AntdVue/zh/other/declare.md b/DjangoAdmin_Django_AntdVue/zh/other/declare.md index 7737479..915692a 100644 --- a/DjangoAdmin_Django_AntdVue/zh/other/declare.md +++ b/DjangoAdmin_Django_AntdVue/zh/other/declare.md @@ -1,5 +1,9 @@ # 免责声明 +:::tip 概述 +使用本产品前必读的法律声明，明确产品性质、使用限制与责任划分，一旦使用本产品即视为接受本声明全部条款。 +::: + :::danger 重要提示 任何用户在使用本团队研发的系列软件产品（以下简称「本产品」）前，请仔细阅读并透彻理解本声明。选择不使用本产品，可随时停止使用；一旦使用本产品，即视为对本声明全部内容的认可和接受。 ::: diff --git a/DjangoAdmin_Django_AntdVue/zh/struct.md b/DjangoAdmin_Django_AntdVue/zh/struct.md index 5347f87..a58356a 100644 --- a/DjangoAdmin_Django_AntdVue/zh/struct.md +++ b/DjangoAdmin_Django_AntdVue/zh/struct.md @@ -1,5 +1,9 @@ # 项目目录结构 +:::tip 概述 +本页说明项目前后端目录组织与各目录职责，二次开发定位文件或了解工程结构时对照查阅。 +::: + ## 整体结构 ``` diff --git a/DjangoAdmin_Django_AntdVue/zh/volume2/code-list.md b/DjangoAdmin_Django_AntdVue/zh/volume2/code-list.md index a41990f..2a26172 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume2/code-list.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume2/code-list.md @@ -1,5 +1,9 @@ # 完整代码清单 +:::tip 概述 +本页汇总案例管理（Example）模块涉及的全部文件代码，开发时可快速查阅与复制对照。 +::: + 本章汇总 Example 案例模块涉及的全部文件，便于开发时快速查阅和复制。 ## 后端文件清单 diff --git a/DjangoAdmin_Django_AntdVue/zh/volume2/faq.md b/DjangoAdmin_Django_AntdVue/zh/volume2/faq.md index 4c244cb..bd6d1f1 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume2/faq.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume2/faq.md @@ -1,5 +1,9 @@ # 常见问题与排错 +:::tip 概述 +本页汇总模块开发过程中的常见问题与排错方法，开发受阻时按症状索引即可定位。 +::: + 本章汇总模块开发过程中的常见问题和解决方案。 ## 后端问题 diff --git a/DjangoAdmin_Django_AntdVue/zh/volume2/fe-api.md b/DjangoAdmin_Django_AntdVue/zh/volume2/fe-api.md index 8d52e68..7c1f64f 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume2/fe-api.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume2/fe-api.md @@ -1,5 +1,9 @@ # 前端 API 层 +:::tip 概述 +前端 API 层封装后端接口的 HTTP 请求，每个业务模块对应一个 API 文件，本页讲解基于 Axios 封装的编写规范。 +::: + 前端 API 层负责封装后端接口的 HTTP 请求。每个业务模块对应一个 API 文件，使用项目封装的 Axios 工具发送请求。 ## 文件位置 diff --git a/DjangoAdmin_Django_AntdVue/zh/volume2/fe-router.md b/DjangoAdmin_Django_AntdVue/zh/volume2/fe-router.md index 04bc70a..20e3913 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume2/fe-router.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume2/fe-router.md @@ -1,5 +1,9 @@ # 前端路由与菜单 +:::tip 概述 +本页讲解前端路由与菜单机制——路由和菜单由后端动态返回，前端只需注册路由组件映射。 +::: + 前端路由定义页面的访问路径，菜单是路由的可视化展示。项目的路由和菜单由后端动态返回，前端只需注册路由组件映射。 ## 动态路由机制 diff --git a/DjangoAdmin_Django_AntdVue/zh/volume2/fe-view.md b/DjangoAdmin_Django_AntdVue/zh/volume2/fe-view.md index cd3da3c..c7551b2 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume2/fe-view.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume2/fe-view.md @@ -1,5 +1,9 @@ # 前端页面视图 +:::tip 概述 +前端页面视图是用户直接交互的界面，本页讲解 Vue3 + AntDesign 下一个完整 CRUD 页面的文件组成与编写方式。 +::: + 前端页面视图是用户直接交互的界面。项目使用 Vue3 + Ant Design Vue + Vite 构建。一个完整的 CRUD 页面由 5 个文件组成： ``` diff --git a/DjangoAdmin_Django_AntdVue/zh/volume2/form.md b/DjangoAdmin_Django_AntdVue/zh/volume2/form.md index 884ad47..7b24bba 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume2/form.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume2/form.md @@ -1,5 +1,9 @@ # 表单验证（Form） +:::tip 概述 +表单验证是模块开发的第二步，讲解基于 Django ModelForm 的提交数据校验与错误信息约定。 +::: + 表单验证是模块开发的第二步，用于对前端提交的数据进行验证。项目使用 Django 的 `ModelForm` 实现表单验证，所有错误信息使用中文提示。 ## 文件位置 diff --git a/DjangoAdmin_Django_AntdVue/zh/volume2/model.md b/DjangoAdmin_Django_AntdVue/zh/volume2/model.md index 8c80c0f..e10cb25 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume2/model.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume2/model.md @@ -1,5 +1,9 @@ # 数据模型（Model） +:::tip 概述 +数据模型是模块开发的第一步，讲解如何用 Django ORM 与 BaseModel 定义数据库表结构，新建模块时从本页开始。 +::: + 数据模型是模块开发的第一步，用于定义数据库表结构。项目使用 Django ORM，模型类通过继承 `BaseModel` 自动获得通用字段。 ## 文件位置 diff --git a/DjangoAdmin_Django_AntdVue/zh/volume2/overview.md b/DjangoAdmin_Django_AntdVue/zh/volume2/overview.md index 4db86b4..f476f00 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume2/overview.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume2/overview.md @@ -1,5 +1,9 @@ # 模块开发实战概述 +:::tip 概述 +本章以案例管理（Example）模块为完整案例，手把手演示从零开发一个业务模块的全流程，学完即可掌握项目中任意模块的开发方式。 +::: + 本章以「案例管理（Example）」模块为完整案例，手把手演示从零开发一个业务模块的全流程。学完本章后，你将掌握项目中任意模块的开发方式。 ## 你将学到什么 diff --git a/DjangoAdmin_Django_AntdVue/zh/volume2/permission.md b/DjangoAdmin_Django_AntdVue/zh/volume2/permission.md index 54ff8bb..c463485 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume2/permission.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume2/permission.md @@ -1,5 +1,9 @@ # 权限节点配置 +:::tip 概述 +本页讲解接口权限字符串的定义与菜单权限节点的配置方法，联调 403 问题时对照本页。 +::: + 后端代码中的 `permission_required = ("sys:example:page",)` 定义了接口所需的权限字符串，但权限节点本身需要在数据库中配置，才能在「菜单管理」中分配给角色。 ## 权限字符串格式 diff --git a/DjangoAdmin_Django_AntdVue/zh/volume2/service.md b/DjangoAdmin_Django_AntdVue/zh/volume2/service.md index 0910d08..7937611 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume2/service.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume2/service.md @@ -1,5 +1,9 @@ # 业务逻辑层（Service） +:::tip 概述 +业务逻辑层是模块开发的核心，CRUD 操作、业务规则与数据处理均封装在 Service 层函数，本页讲解其编写规范。 +::: + 业务逻辑层是模块开发的第三步，也是最核心的部分。所有 CRUD 操作、业务规则、数据处理都封装在 Service 层的独立函数中。 ## 文件位置 diff --git a/DjangoAdmin_Django_AntdVue/zh/volume2/url.md b/DjangoAdmin_Django_AntdVue/zh/volume2/url.md index 024e2c7..9c8c74e 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume2/url.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume2/url.md @@ -1,5 +1,9 @@ # URL 路由配置 +:::tip 概述 +URL 路由是模块开发的最后一步，本页讲解用 Django path() 将路径映射到视图类的配置方法。 +::: + URL 路由是模块开发的最后一步，负责将 URL 路径映射到视图类。项目使用 Django 的 `path()` 函数定义路由，通过 `include()` 将模块路由注册到主路由。 ## 文件位置 diff --git a/DjangoAdmin_Django_AntdVue/zh/volume2/view.md b/DjangoAdmin_Django_AntdVue/zh/volume2/view.md index 5e3bafc..be37d10 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume2/view.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume2/view.md @@ -1,5 +1,9 @@ # 视图层（View） +:::tip 概述 +视图层负责处理 HTTP 请求并调用 Service 业务逻辑，本页讲解 Django 类视图的编写方式与响应约定。 +::: + 视图层是模块开发的第四步，负责处理 HTTP 请求并调用 Service 层的业务逻辑。项目使用 Django 的类视图（Class-Based Views），每个视图类对应一个 API 端点。 ## 文件位置 diff --git a/DjangoAdmin_Django_AntdVue/zh/volume3/base-classes.md b/DjangoAdmin_Django_AntdVue/zh/volume3/base-classes.md index 27817b6..c20ff00 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume3/base-classes.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume3/base-classes.md @@ -1,5 +1,9 @@ # 第四章 架构设计 - 核心基类体系 +:::tip 概述 +本页汇总项目核心基类体系的总览与用法，编写业务代码前先了解可复用的基座能力。 +::: + ## 4.1 基类总览 核心基类体系由四大基类组成，覆盖从数据模型到请求校验再到响应输出的完整链路。子类只需声明差异点，即可获得标准化的增删改查能力。 diff --git a/DjangoAdmin_Django_AntdVue/zh/volume3/cache.md b/DjangoAdmin_Django_AntdVue/zh/volume3/cache.md index 1e20ea1..028649d 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume3/cache.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume3/cache.md @@ -1,5 +1,9 @@ # 第四章 架构设计 - 缓存架构 +:::tip 概述 +本页说明系统缓存架构的设计与使用方式，涉及缓存一致性或性能问题时查阅。 +::: + ## 4.1 缓存架构概述 项目使用 Redis 作为缓存后端，通过 Django 的缓存框架实现统一的缓存管理。缓存主要用于以下场景： diff --git a/DjangoAdmin_Django_AntdVue/zh/volume3/database-design.md b/DjangoAdmin_Django_AntdVue/zh/volume3/database-design.md index 9654a0c..5ed7a5e 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume3/database-design.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume3/database-design.md @@ -1,5 +1,9 @@ # 第四章 架构设计 - 数据库设计 +:::tip 概述 +本页说明数据库设计原则与表结构组织方式，建表或数据迁移时对照本页。 +::: + ## 4.1 数据库设计概述 项目使用 MySQL 8.0 作为主数据库，通过 Django ORM 进行数据访问。所有业务表继承 BaseModel 抽象基类，自动获得 6 个通用字段。 diff --git a/DjangoAdmin_Django_AntdVue/zh/volume3/directory.md b/DjangoAdmin_Django_AntdVue/zh/volume3/directory.md index 4c456ff..315b4bc 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume3/directory.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume3/directory.md @@ -1,5 +1,9 @@ # 第四章 架构设计 - 目录结构设计 +:::tip 概述 +本页说明项目根目录与各层目录的组织设计，二次开发定位文件时对照查阅。 +::: + ## 4.1 项目根目录 ``` diff --git a/DjangoAdmin_Django_AntdVue/zh/volume3/extensibility.md b/DjangoAdmin_Django_AntdVue/zh/volume3/extensibility.md index 720e68a..5f6181c 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume3/extensibility.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume3/extensibility.md @@ -1,5 +1,9 @@ # 第四章 架构设计 - 扩展性设计 +:::tip 概述 +本页说明系统的扩展性设计原则，二次开发新增能力或改造现有模块时参考。 +::: + ## 4.1 扩展性设计原则 项目遵循开闭原则（OCP）：对扩展开放，对修改关闭。新功能通过添加新模块实现，而非修改现有代码。系统通过 Django App 机制、代码生成器、模板定制等方式提供扩展能力。 diff --git a/DjangoAdmin_Django_AntdVue/zh/volume3/layer-arch.md b/DjangoAdmin_Django_AntdVue/zh/volume3/layer-arch.md index cb1ae9b..3f5f2c6 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume3/layer-arch.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume3/layer-arch.md @@ -1,5 +1,9 @@ # 第四章 架构设计 - 分层架构详解 +:::tip 概述 +本页详解后端分层架构的职责划分与调用关系，编写代码前先理解各层边界。 +::: + ## 4.1 分层架构概述 项目采用经典的五层架构设计，各层职责明确，依赖关系清晰： diff --git a/DjangoAdmin_Django_AntdVue/zh/volume3/overview.md b/DjangoAdmin_Django_AntdVue/zh/volume3/overview.md index 8a64fa4..5116273 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume3/overview.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume3/overview.md @@ -1,5 +1,9 @@ # 第四章 架构设计 - 系统架构总览 +:::tip 概述 +本页给出系统整体架构总览，理解各层职责与模块关系时从本页开始。 +::: + ## 4.1 整体架构 项目采用前后端分离的 B/S 架构，后端基于 Django 6.0.3 提供 RESTful API，前端基于 Vue3 + Ant Design Vue 构建单页应用。系统通过 Nginx 反向代理统一入口，实现静态资源托管与 API 转发。 diff --git a/DjangoAdmin_Django_AntdVue/zh/volume3/request-flow.md b/DjangoAdmin_Django_AntdVue/zh/volume3/request-flow.md index b69d1e5..7887aae 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume3/request-flow.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume3/request-flow.md @@ -1,5 +1,9 @@ # 第四章 架构设计 - 请求处理流程 +:::tip 概述 +本页给出请求从进入路由到返回响应的全链路处理流程，排查接口问题时对照追踪。 +::: + ## 4.1 请求处理全链路 一个完整的 HTTP 请求在 系统中的处理流程如下： diff --git a/DjangoAdmin_Django_AntdVue/zh/volume3/security.md b/DjangoAdmin_Django_AntdVue/zh/volume3/security.md index cb653e1..d6c4dce 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume3/security.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume3/security.md @@ -1,5 +1,9 @@ # 第四章 架构设计 - 安全架构 +:::tip 概述 +本页说明系统安全架构设计，含认证、权限与数据安全等防护机制。 +::: + ## 4.1 安全架构概述 系统从认证、授权、防护三个维度构建安全体系： diff --git a/DjangoAdmin_Django_AntdVue/zh/volume3/tech-stack.md b/DjangoAdmin_Django_AntdVue/zh/volume3/tech-stack.md index 2ca7162..90a4ab4 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume3/tech-stack.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume3/tech-stack.md @@ -1,5 +1,9 @@ # 第四章 架构设计 - 技术栈选型 +:::tip 概述 +本页列出项目后端与前端完整技术选型及版本要求，评估兼容性或升级影响时对照本表。 +::: + ## 4.1 后端技术栈 ### Django 6.0.3 diff --git a/DjangoAdmin_Django_AntdVue/zh/volume4/business/article.md b/DjangoAdmin_Django_AntdVue/zh/volume4/business/article.md index a2811c7..0d28fd8 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume4/business/article.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume4/business/article.md @@ -1,3 +1,5 @@ +# 文章管理 + :::tip 文章管理 文章管理模块支持富文本编辑、分类关联、封面图片上传、图集管理等功能。适用于新闻、公告、帮助文档等内容管理场景。 ::: diff --git a/DjangoAdmin_Django_AntdVue/zh/volume4/business/category.md b/DjangoAdmin_Django_AntdVue/zh/volume4/business/category.md index 4e286e4..0bf243f 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume4/business/category.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume4/business/category.md @@ -1,3 +1,5 @@ +# 分类管理 + :::tip 分类管理 分类管理模块用于管理树形分类数据，如文章分类、产品分类等。通过 `parent_id` 字段实现无限级分类。 ::: diff --git a/DjangoAdmin_Django_AntdVue/zh/volume4/business/city.md b/DjangoAdmin_Django_AntdVue/zh/volume4/business/city.md index 89da3be..0ebc97d 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume4/business/city.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume4/business/city.md @@ -1,3 +1,5 @@ +# 行政区划管理 + :::tip 城市管理 城市管理模块用于管理行政区划数据，支持省/市/区/街道/社区五级行政区划。通过 `parent_code` 字段实现树形结构。 ::: diff --git a/DjangoAdmin_Django_AntdVue/zh/volume4/business/content.md b/DjangoAdmin_Django_AntdVue/zh/volume4/business/content.md index 76ad1b0..0d7e8df 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume4/business/content.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume4/business/content.md @@ -1,3 +1,5 @@ +# 公告与链接管理 + :::tip 公告/链接 公告和链接是两个简单 CRUD 内容模块，提供标准的增删改查接口。适用于系统公告、友情链接等场景。 ::: diff --git a/DjangoAdmin_Django_AntdVue/zh/volume4/business/dept.md b/DjangoAdmin_Django_AntdVue/zh/volume4/business/dept.md index 124bad8..ad7295f 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume4/business/dept.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume4/business/dept.md @@ -1,3 +1,5 @@ +# 部门/职级/岗位管理 + :::tip 部门/职级/岗位 部门、职级、岗位是组织架构管理的三个核心模块。部门采用树形结构，职级和岗位为简单 CRUD 模块。用户表通过 `dept_id`、`position_id`、`level_id` 三个外键关联这三个模块。 ::: diff --git a/DjangoAdmin_Django_AntdVue/zh/volume4/business/job.md b/DjangoAdmin_Django_AntdVue/zh/volume4/business/job.md index 8dc8f7d..ff7ff1f 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume4/business/job.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume4/business/job.md @@ -1,3 +1,5 @@ +# 定时任务 + :::tip 定时任务 定时任务模块基于 APScheduler 实现，支持 Cron 表达式调度、任务执行日志、动态启停等功能。包含 job（任务定义）、job_log（执行日志）两个子模块。 ::: diff --git a/DjangoAdmin_Django_AntdVue/zh/volume4/business/menu.md b/DjangoAdmin_Django_AntdVue/zh/volume4/business/menu.md index 305f665..ee73679 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume4/business/menu.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume4/business/menu.md @@ -1,3 +1,5 @@ +# 菜单管理 + :::tip 菜单管理 菜单管理是 RBAC 权限系统的基础，负责管理系统的导航菜单和权限节点。支持目录/菜单（type=0）和权限按钮节点（type=1）两种类型，通过树形结构组织。 ::: diff --git a/DjangoAdmin_Django_AntdVue/zh/volume4/business/param.md b/DjangoAdmin_Django_AntdVue/zh/volume4/business/param.md index e5eeaf4..58b68c9 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume4/business/param.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume4/business/param.md @@ -1,3 +1,5 @@ +# 参数管理 + :::tip 参数管理 参数管理模块用于管理动态系统参数，支持按参数键查询、修改，无需重启服务即可生效。 ::: diff --git a/DjangoAdmin_Django_AntdVue/zh/volume4/business/role.md b/DjangoAdmin_Django_AntdVue/zh/volume4/business/role.md index 0f13489..7f566e2 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume4/business/role.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume4/business/role.md @@ -1,3 +1,5 @@ +# 角色管理 + :::tip 角色管理 角色是 RBAC 权限模型的核心，连接用户和菜单（权限）。通过为角色分配菜单权限，再将角色分配给用户，实现灵活的权限管理。 ::: diff --git a/DjangoAdmin_Django_AntdVue/zh/volume4/business/user.md b/DjangoAdmin_Django_AntdVue/zh/volume4/business/user.md index 52def72..0dae730 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume4/business/user.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume4/business/user.md @@ -1,3 +1,5 @@ +# 用户管理 + :::tip 用户管理 用户管理是系统的核心模块，属于复杂业务模块。包含用户 CRUD、角色关联、密码加密、行政区划等功能。与简单 CRUD 模块不同，用户管理使用自定义 service 函数。 ::: diff --git a/DjangoAdmin_Django_AntdVue/zh/volume4/core/captcha.md b/DjangoAdmin_Django_AntdVue/zh/volume4/core/captcha.md index ad81dfc..bc8ea2b 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume4/core/captcha.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume4/core/captcha.md @@ -1,3 +1,5 @@ +# 验证码机制 + :::tip 验证码 验证码是防止自动化攻击的重要安全手段。项目使用 django-simple-captcha 库生成图片验证码，存储在数据库中，支持多种验证码格式。源码位于 `application/login/views.py`。 ::: diff --git a/DjangoAdmin_Django_AntdVue/zh/volume4/core/config.md b/DjangoAdmin_Django_AntdVue/zh/volume4/core/config.md index 1a23de0..877d4b6 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume4/core/config.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume4/core/config.md @@ -1,3 +1,5 @@ +# 系统配置管理 + :::tip 系统配置 系统配置模块用于管理动态的键值对配置项，与数据字典类似但更偏向系统级参数。支持分组管理，可通过接口动态修改，无需重启服务。模块位于 `application/config/`。 ::: diff --git a/DjangoAdmin_Django_AntdVue/zh/volume4/core/cors.md b/DjangoAdmin_Django_AntdVue/zh/volume4/core/cors.md index 99bb73d..25a90eb 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume4/core/cors.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume4/core/cors.md @@ -1,3 +1,5 @@ +# 跨域资源共享（CORS） + :::tip CORS跨域 CORS（Cross-Origin Resource Sharing）跨域资源共享是前后端分离架构必须处理的问题。项目使用 `django-cors-headers` 中间件处理跨域请求，通过 `.env` 配置允许的跨域源。 ::: diff --git a/DjangoAdmin_Django_AntdVue/zh/volume4/core/demo-mode.md b/DjangoAdmin_Django_AntdVue/zh/volume4/core/demo-mode.md index 806316f..fb8a2f3 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume4/core/demo-mode.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume4/core/demo-mode.md @@ -1,3 +1,5 @@ +# 演示模式 + :::tip 演示模式 演示模式用于在线体验环境，开启后所有写操作（新增、编辑、删除等）将被拦截，返回"演示环境，暂无操作权限"提示。通过 `DJANGO_DEMO` 环境变量控制。 ::: diff --git a/DjangoAdmin_Django_AntdVue/zh/volume4/core/dict.md b/DjangoAdmin_Django_AntdVue/zh/volume4/core/dict.md index 7e315fc..cf741e8 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume4/core/dict.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume4/core/dict.md @@ -1,3 +1,5 @@ +# 字典模块 + :::tip 数据字典 数据字典用于管理系统中的枚举值和配置项，如状态、类型、性别等。通过字典编码统一管理，前端可通过 `useDictStore` 获取字典选项，避免硬编码。模块位于 `application/dict/`。 ::: diff --git a/DjangoAdmin_Django_AntdVue/zh/volume4/core/exception.md b/DjangoAdmin_Django_AntdVue/zh/volume4/core/exception.md index 687a82e..a0e0a48 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume4/core/exception.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume4/core/exception.md @@ -1,3 +1,5 @@ +# 异常与响应处理 + :::tip 全局异常与响应 定义了统一的响应格式和全局异常处理机制。所有 API 返回 `{code, data, msg, ok}` 标准格式。响应函数位于 `utils/R.py`。 ::: diff --git a/DjangoAdmin_Django_AntdVue/zh/volume4/core/idempotent.md b/DjangoAdmin_Django_AntdVue/zh/volume4/core/idempotent.md index 04abfa1..91da95f 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume4/core/idempotent.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume4/core/idempotent.md @@ -1,3 +1,5 @@ +# 防重复提交 + :::tip 防重复提交 防重复提交是保障数据一致性的重要措施。通过前端防抖和后端唯一性校验双重保护，防止用户重复点击导致的数据重复提交。 ::: diff --git a/DjangoAdmin_Django_AntdVue/zh/volume4/core/jwt.md b/DjangoAdmin_Django_AntdVue/zh/volume4/core/jwt.md index 3ebe203..5374d5d 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume4/core/jwt.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume4/core/jwt.md @@ -1,3 +1,5 @@ +# 用户认证（JWT） + :::tip JWT认证 JWT（JSON Web Token）是系统的核心认证机制。用户登录成功后获取 Token，后续请求通过 `Authorization: Bearer <token>` 头携带 Token 进行身份验证。项目内置了 Token 生成、解析、刷新和黑名单管理功能，源码位于 `utils/jwt.py`。 ::: diff --git a/DjangoAdmin_Django_AntdVue/zh/volume4/core/login-log.md b/DjangoAdmin_Django_AntdVue/zh/volume4/core/login-log.md index c95dc0d..8320f45 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume4/core/login-log.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume4/core/login-log.md @@ -1,3 +1,5 @@ +# 登录日志 + :::tip 登录日志 登录日志记录每次登录尝试（成功/失败），包含登录账号、IP地址、浏览器信息、登录时间等。登录逻辑位于 `application/login/services.py`，日志记录位于 `application/login_log/` 模块。 ::: diff --git a/DjangoAdmin_Django_AntdVue/zh/volume4/core/operation-log.md b/DjangoAdmin_Django_AntdVue/zh/volume4/core/operation-log.md index 6cad27c..08ab4e9 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume4/core/operation-log.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume4/core/operation-log.md @@ -1,3 +1,5 @@ +# 操作日志 + :::tip 操作日志 操作日志通过 `@operation_log` 装饰器标记需要记录日志的视图方法，自动记录请求参数、响应结果、耗时、操作类型等信息。源码位于 `application/operation_log/decorators.py`。 ::: diff --git a/DjangoAdmin_Django_AntdVue/zh/volume4/core/rate-limit.md b/DjangoAdmin_Django_AntdVue/zh/volume4/core/rate-limit.md index 0d5e609..84513f4 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume4/core/rate-limit.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume4/core/rate-limit.md @@ -1,3 +1,5 @@ +# 请求限流 + :::tip 请求限流 请求限流可通过中间件实现 IP 级别的限流，防止恶意请求和 DoS 攻击。项目中限流可通过 Nginx 反向代理或自定义中间件实现。 ::: diff --git a/DjangoAdmin_Django_AntdVue/zh/volume4/core/rbac.md b/DjangoAdmin_Django_AntdVue/zh/volume4/core/rbac.md index 0e2b49d..9153738 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume4/core/rbac.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume4/core/rbac.md @@ -1,3 +1,5 @@ +# 权限管理（RBAC） + :::tip RBAC权限 采用基于角色的访问控制（RBAC）模型，通过用户-角色-菜单三层关系实现细粒度的权限管理。权限控制贯穿前后端：后端通过 `PermissionRequired` 混入类校验（`middleware/permission_middleware.py`），前端通过 `v-perm` 指令控制按钮显隐。 ::: diff --git a/DjangoAdmin_Django_AntdVue/zh/volume4/core/validator.md b/DjangoAdmin_Django_AntdVue/zh/volume4/core/validator.md index 5d679b6..7630021 100644 --- a/DjangoAdmin_Django_AntdVue/zh/volume4/core/validator.md +++ b/DjangoAdmin_Django_AntdVue/zh/volume4/core/validator.md @@ -1,3 +1,5 @@ +# 参数验证（Form） + :::tip 参数验证 使用 Django ModelForm 进行请求参数验证。所有请求体参数通过 Django Form 定义，视图中调用 `form.is_valid()` 自动验证，验证失败通过 `regular.get_err()` 提取错误信息返回前端。 ::: diff --git a/DjangoAdmin_Django_AntdVue/zh/why.md b/DjangoAdmin_Django_AntdVue/zh/why.md index 8b6eaaa..efcd393 100644 --- a/DjangoAdmin_Django_AntdVue/zh/why.md +++ b/DjangoAdmin_Django_AntdVue/zh/why.md @@ -1,5 +1,9 @@ # 为什么选择我们 +:::tip 概述 +本页从低代码生成能力、功能开箱即用与工程可持续性三个维度说明选择本项目的理由，技术选型对比时可作为评估依据。 +::: + ## 低代码生成，开发效率倍增 项目最大的特点是代码生成器。只需在数据库中建好表，一条命令即可生成完整的前后端 CRUD 模块： diff --git a/DjangoAdmin_Django_EleVue/.vitepress/config/en.ts b/DjangoAdmin_Django_EleVue/.vitepress/config/en.ts index a1a96ef..4e0d3f4 100644 --- a/DjangoAdmin_Django_EleVue/.vitepress/config/en.ts +++ b/DjangoAdmin_Django_EleVue/.vitepress/config/en.ts @@ -29,7 +29,7 @@ // // themeConfig: { // editLink: { -// pattern: "https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_EleVue", +// pattern: "https://gitee.com/djangoadmin/DjangoAdmin_Django_EleVue", // text: "Suggest changes to this page", // }, // diff --git a/DjangoAdmin_Django_EleVue/.vitepress/config/extract.d.mts b/DjangoAdmin_Django_EleVue/.vitepress/config/extract.d.mts new file mode 100644 index 0000000..2a46233 --- /dev/null +++ b/DjangoAdmin_Django_EleVue/.vitepress/config/extract.d.mts @@ -0,0 +1,5 @@ +export declare const SITE_URL: string; +export declare const SITE_DESCRIPTION: string; +export declare function stripNumberPrefix(title: string): string; +export declare function extractDescription(md: string): string; +export declare function extractFaqs(md: string): { q: string; a: string }[]; diff --git a/DjangoAdmin_Django_EleVue/.vitepress/config/extract.mjs b/DjangoAdmin_Django_EleVue/.vitepress/config/extract.mjs new file mode 100644 index 0000000..a5f216c --- /dev/null +++ b/DjangoAdmin_Django_EleVue/.vitepress/config/extract.mjs @@ -0,0 +1,130 @@ +/** + * SEO/GEO 共享工具（纯 ESM，零依赖）。 + * + * 同时被两类调用方 import： + * 1. VitePress 配置（.ts，esbuild 打包时内联本文件） + * 2. scripts/generate-llms-txt.mjs（Node 直接运行） + * + * 注意：SITE_URL 是全站唯一 URL 真相源。 + * docs 子域当前 TLS 证书为腾讯 CDN 默认证书（*.cdn.myqcloud.com，校验失败）， + * 故暂用 http；证书修复后只需改这里一处。 + */ + +export const SITE_URL = "http://docs.django.elevue.djangoadmin.cn"; + +export const SITE_DESCRIPTION = + "DjangoAdmin 企业级中台解决方案 - Django + ElementPlus 前后端分离版本"; + +/** + * 剥离 H1/标题中的章节编号前缀，用于 <title> 与 JSON-LD headline。 + * 例："5.10 字典模块" → "字典模块"；"K. 贡献指南" → "贡献指南"。 + * 页内 H1 与侧边栏编号保持不变，仅影响 SEO 输出。 + */ +export function stripNumberPrefix(title) { + return String(title) + .replace(/^(?:\d+(?:\.\d+)+|[A-Z]\.)\s+/, "") + .trim(); +} + +/** + * 从页面 Markdown 提取 meta description： + * 1. 首选 `:::tip xxx` 容器内的首句（141/143 页的标准 opener） + * 2. 回退到 H1 后的第一个普通段落 + * 输出压缩为单行、去除行内 Markdown，按中文句末标点截断（≤100 字符）。 + */ +export function extractDescription(md) { + const src = String(md); + const fm = src.match(/^---\r?\n([\s\S]*?)\r?\n---/); + const body = fm ? src.slice(fm[0].length) : src; + + let text = ""; + // frontmatter description 显式声明优先（无 H1 页面的补齐手段） + const fmDesc = fm && fm[1].match(/^description:\s*(.+)$/m); + if (fmDesc) { + text = fmDesc[1].trim().replace(/^["']|["']$/g, ""); + } + const tip = !text && body.match(/^:::\s*tip[^\n]*\n([\s\S]*?)\n:::/m); + if (tip) { + text = tip[1]; + } + if (!text) { + const afterH1 = body.match(/^# (?!#)(.+)$/m); + if (afterH1) { + const rest = body.slice((afterH1.index ?? 0) + afterH1[0].length); + const para = rest + .split(/\n{2,}/) + .find( + (p) => + p.trim() && + !/^\s*#/.test(p) && + !/^\s*:::/.test(p) && + !/^\s*```/.test(p) && + !/^\s*\|/.test(p), + ); + text = para || ""; + } + } + + text = text + .replace(/\s+/g, " ") + .replace(/`([^`]+)`/g, "$1") + .replace(/\*\*([^*]+)\*\*/g, "$1") + .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") + .trim(); + + if (!text) return ""; + + // 按中文句末标点截取首句，上限 100 字符；截断时避免切碎词 + const m = text.match(/^.{1,100}?(?:[。！？!?]|$)/); + let out = m ? m[0] : text.slice(0, 100); + if (out.length < text.length && !/[。！？!?]$/.test(out)) { + out = out.replace(/[^\s，、；：,;:]+$/, ""); + } + return out.trim() || text.slice(0, 100); +} + +function cleanText(s) { + return s + .replace(/^:::[^\n]*$/gm, "") + .replace(/^```[^\n]*$/gm, "") + .replace(/`([^`]+)`/g, "$1") + .replace(/\*\*([^*]+)\*\*/g, "$1") + .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") + .replace(/\s+/g, " ") + .trim(); +} + +/** + * 提取页面中的 Q/A 对（用于 FAQPage JSON-LD），支持两种站内格式： + * A. `### Q：问题` 标题式（如 zh/quickstart/faq.md） + * B. `**Q：问题**` 加粗式（如 zh/appendix/faq.md） + * 返回 [{ q, a }]；无匹配返回 []。 + */ +export function extractFaqs(md) { + const body = String(md).replace(/^---[\s\S]*?\n---\s*/, ""); + let faqs = []; + + // 格式 A：按 `### Q：` 切块，答案截断到下一个标题 + for (const part of body.split(/(?=^###\s*Q[：:])/m)) { + const m = part.match(/^###\s*Q[：:]\s*([^\n]+)\n+([\s\S]*)/); + if (!m) continue; + let a = m[2]; + const cut = a.search(/^#{1,4}\s/m); + if (cut >= 0) a = a.slice(0, cut); + faqs.push({ q: cleanText(m[1]), a: cleanText(a) }); + } + + // 格式 B：按 `**Q：` 切块 + if (!faqs.length) { + for (const part of body.split(/(?=^\*\*Q[：:])/m)) { + const m = part.match(/^\*\*Q[：:]\s*([^*]+)\*\*\s*\n+([\s\S]*)/); + if (!m) continue; + let a = m[2]; + const cut = a.search(/^(?:#{1,4}\s|\*\*Q)/m); + if (cut >= 0) a = a.slice(0, cut); + faqs.push({ q: cleanText(m[1]), a: cleanText(a) }); + } + } + + return faqs.filter((f) => f.q && f.a); +} diff --git a/DjangoAdmin_Django_EleVue/.vitepress/config/index.ts b/DjangoAdmin_Django_EleVue/.vitepress/config/index.ts index 2294856..6627a76 100644 --- a/DjangoAdmin_Django_EleVue/.vitepress/config/index.ts +++ b/DjangoAdmin_Django_EleVue/.vitepress/config/index.ts @@ -1,14 +1,22 @@ import { defineConfig } from "vitepress"; import { enConfig } from "./en"; +import { createSeoHooks } from "./seo"; import { sharedConfig } from "./shared"; import { zhConfig } from "./zh"; +const seo = createSeoHooks(zhConfig.themeConfig?.sidebar); + export default defineConfig({ ...sharedConfig, ignoreDeadLinks: [ (link) => link.includes('localhost'), ], + // SEO：页面级 title/description、canonical/OG/JSON-LD、sitemap+lastmod + transformPageData: seo.transformPageData, + transformHead: seo.transformHead, + sitemap: seo.sitemap, + locales: { root: { label: "简体中文", lang: "zh-CN", link: "/", ...zhConfig }, // root: { label: "English", lang: "en-US", link: "/", ...enConfig }, diff --git a/DjangoAdmin_Django_EleVue/.vitepress/config/seo.ts b/DjangoAdmin_Django_EleVue/.vitepress/config/seo.ts new file mode 100644 index 0000000..02b25fc --- /dev/null +++ b/DjangoAdmin_Django_EleVue/.vitepress/config/seo.ts @@ -0,0 +1,311 @@ +/** + * SEO/GEO 构建期钩子（仅 Node 构建时运行，不进客户端 bundle）： + * - transformPageData：每页独立 title（去编号前缀）与 description（取 :::tip 首句） + * - transformHead：canonical / Open Graph / twitter 卡片 / JSON-LD 结构化数据 + * - sitemap.transformItems：注入 lastmod（git 最后提交时间）并过滤 404 + * + * 由 config/index.ts 通过 createSeoHooks(zhConfig.themeConfig?.sidebar) 挂载。 + * 依赖 extract.mjs（纯 ESM，同被 scripts/generate-llms-txt.mjs 复用）。 + */ +import fs from "node:fs"; +import path from "node:path"; +import { execSync } from "node:child_process"; +import { + SITE_URL, + extractDescription, + extractFaqs, + stripNumberPrefix, +} from "./extract.mjs"; + +/** 与 vitepress HeadConfig 同构：[tag, attrs, innerHTML?] */ +type HeadTuple = [string, Record<string, any>, string?]; + +interface SideItem { + text?: string; + link?: string; + items?: SideItem[]; +} + +interface PageDataLike { + relativePath?: string; + title?: string; + description?: string; + frontmatter?: Record<string, any>; + [k: string]: any; +} + +interface TransformCtx { + pageData?: PageDataLike; + title?: string; + description?: string; + content?: string; + siteConfig?: { root?: string; srcDir?: string }; +} + +const ORG = { + "@type": "Organization", + name: "DjangoAdmin", + url: "https://www.djangoadmin.cn", + logo: `${SITE_URL}/logo.png`, + sameAs: [ + "https://gitee.com/djangoadmin/DjangoAdmin_Django_EleVue", + "https://www.djangoadmin.cn", + ], +}; + +/** 相对路径 → 站内路由（cleanUrls 关闭，正文页带 .html） */ +function routeOf(relativePath: string): string { + if (relativePath === "index.md") return "/"; + if (relativePath === "404.md") return "/404.html"; + return `/${relativePath.replace(/\.md$/, ".html")}`; +} + +/** 去掉侧边栏文案前导 emoji/符号，保留 "1.1 项目介绍" 这类编号文字 */ +function cleanLabel(s?: string): string { + return (s || "").replace(/^[^\p{L}\p{N}]+/u, "").trim(); +} + +/** 从侧边栏构建 route → 面包屑文案链（含分组小节） */ +function buildCrumbMap(sidebar: unknown): Map<string, string[]> { + const map = new Map<string, string[]>(); + const groups: SideItem[] = Array.isArray(sidebar) + ? sidebar + : ((sidebar as Record<string, SideItem[]>)?.["/zh/"] ?? []); + const walk = (items: SideItem[], trail: string[]) => { + for (const item of items) { + if (item.link && item.link.startsWith("/")) { + map.set(item.link, [...trail, cleanLabel(item.text)]); + } else if (item.items?.length) { + walk(item.items, [...trail, cleanLabel(item.text)]); + } + } + }; + for (const group of groups) { + walk(group.items ?? [], [cleanLabel(group.text)].filter(Boolean)); + } + return map; +} + +/** 从渲染后的 HTML 提取 H1 纯文本（JSON-LD headline 须与页面 H1 一致） */ +function h1OfHtml(html?: string): string { + const m = (html || "").match(/<h1[^>]*>([\s\S]*?)<\/h1>/i); + if (!m) return ""; + return m[1] + .replace(/<[^>]+>/g, "") + .replace(/&/g, "&") + .replace(/</g, "<") + .replace(/>/g, ">") + .replace(/"/g, '"') + .replace(/'/g, "'") + .trim(); +} + +/** 从 Markdown 源提取 H1 纯文本（去除行内 markdown 标记） */ +function h1OfMd(md: string): string { + // 围栏感知：跳过 ``` 代码块内的 # 注释，取真正的页面 H1 + let inFence = false; + for (const line of md.split("\n")) { + if (line.startsWith("```")) { inFence = !inFence; continue; } + if (!inFence && /^# (?!#)/.test(line)) { + return line + .replace(/^# /, "") + .replace(/`([^`]+)`/g, "$1") + .replace(/\*\*([^*]+)\*\*/g, "$1") + .trim(); + } + } + return ""; +} + +export function createSeoHooks(sidebar: unknown) { + const crumbs = buildCrumbMap(sidebar); + const projectDirs: string[] = []; + let gitDates: Map<string, string> | null = null; + + const readMd = (relativePath: string, srcDir?: string): string => { + try { + return fs.readFileSync( + path.resolve(srcDir || process.cwd(), relativePath), + "utf8", + ); + } catch { + return ""; + } + }; + + /** + * 项目内每个文件最后一次 git 提交的 ISO 时间。 + * 单次 git log 调用构建全量映射（key = 相对路径，与 pageData.relativePath 一致）； + * git 不可用时静默降级（sitemap 无 lastmod、JSON-LD 无 dateModified）。 + */ + const getGitDates = (root: string): Map<string, string> => { + if (gitDates) return gitDates; + gitDates = new Map<string, string>(); + try { + const out = execSync( + "git log --format=:::%cI --name-only --relative -n 500 -- .", + { + cwd: root, + encoding: "utf8", + maxBuffer: 64 * 1024 * 1024, + stdio: ["ignore", "pipe", "ignore"], + }, + ); + let current = ""; + for (const line of out.split(/\r?\n/)) { + if (line.startsWith(":::")) { + current = line.slice(3).trim(); + continue; + } + const file = line.trim(); + if (file && current && !gitDates.has(file)) { + gitDates.set(file, current); + } + } + } catch { + // 降级：无 lastmod / dateModified + } + return gitDates; + }; + + /** 每页独立 title（去 "5.10 " 编号前缀，关键词前置）与 description（:::tip 首句） */ + function transformPageData(pageData: PageDataLike, ctx?: any): Record<string, unknown> { + const srcDir: string | undefined = ctx?.siteConfig?.srcDir; + const root: string | undefined = ctx?.siteConfig?.root; + if (root && !projectDirs.includes(root)) projectDirs.push(root); + + const out: Record<string, unknown> = {}; + const rel = pageData.relativePath; + if (rel && !pageData.frontmatter?.description) { + const desc = extractDescription(readMd(rel, srcDir)); + if (desc) out.description = desc; + } + if (pageData.title) { + out.title = stripNumberPrefix(pageData.title); + } + return out; + } + + /** 构建期注入 canonical / OG / twitter / JSON-LD */ + function transformHead(ctx: TransformCtx): HeadTuple[] { + const rel = ctx?.pageData?.relativePath || ""; + if (!rel || rel === "404.md") return []; + + const route = routeOf(rel); + const url = `${SITE_URL}${route}`; + const title = ctx.pageData?.title || ctx.title || ""; + const desc = ctx.description || ""; + const isHome = rel === "index.md"; + const image = `${SITE_URL}/logo.png`; + + const heads: HeadTuple[] = [ + ["link", { rel: "canonical", href: url }], + ["meta", { property: "og:type", content: isHome ? "website" : "article" }], + ["meta", { property: "og:site_name", content: "DjangoAdmin" }], + ["meta", { property: "og:locale", content: "zh_CN" }], + ["meta", { property: "og:title", content: title }], + ["meta", { property: "og:description", content: desc }], + ["meta", { property: "og:url", content: url }], + ["meta", { property: "og:image", content: image }], + ["meta", { property: "twitter:title", content: title }], + ["meta", { property: "twitter:description", content: desc }], + ["meta", { property: "twitter:url", content: url }], + ["meta", { property: "twitter:image", content: image }], + ]; + + // ---- JSON-LD ---- + const root = ctx.siteConfig?.root || projectDirs[0] || process.cwd(); + const srcDir = ctx.siteConfig?.srcDir || root; + const lastMod = getGitDates(root).get(rel); + const blocks: Record<string, any>[] = []; + + if (isHome) { + blocks.push({ + "@context": "https://schema.org", + "@type": "WebSite", + name: "DjangoAdmin 开发文档", + url: `${SITE_URL}/`, + inLanguage: "zh-CN", + description: desc, + }); + blocks.push({ "@context": "https://schema.org", ...ORG }); + } else { + const md = readMd(rel, srcDir); + const article: Record<string, any> = { + "@context": "https://schema.org", + "@type": "TechArticle", + headline: h1OfMd(md) || h1OfHtml(ctx.content) || title, + description: desc, + url, + inLanguage: "zh-CN", + mainEntityOfPage: { "@type": "WebPage", "@id": url }, + publisher: ORG, + }; + if (lastMod) article.dateModified = lastMod; + blocks.push(article); + + const trail = crumbs.get(route); + if (trail?.length) { + const items: Record<string, any>[] = [ + { "@type": "ListItem", position: 1, name: "首页", item: `${SITE_URL}/` }, + ]; + trail.forEach((name, i) => { + const node: Record<string, any> = { + "@type": "ListItem", + position: i + 2, + name, + }; + if (i === trail.length - 1) node.item = url; + items.push(node); + }); + blocks.push({ + "@context": "https://schema.org", + "@type": "BreadcrumbList", + itemListElement: items, + }); + } + + const faqs = extractFaqs(md); + if (faqs.length) { + blocks.push({ + "@context": "https://schema.org", + "@type": "FAQPage", + mainEntity: faqs.map((f) => ({ + "@type": "Question", + name: f.q, + acceptedAnswer: { "@type": "Answer", text: f.a }, + })), + }); + } + } + + // 转义 "<"，防止内容中出现 </script> 破坏注入 + const json = JSON.stringify(blocks).replace(/</g, "\\u003c"); + heads.push(["script", { type: "application/ld+json" }, json]); + return heads; + } + + /** sitemap.xml：过滤 404/README，注入 git lastmod */ + const sitemap = { + hostname: SITE_URL, + transformItems(items: { url: string; lastmod?: string }[]) { + const root = projectDirs[0] || process.cwd(); + const dates = getGitDates(root); + const out: { url: string; lastmod?: string }[] = []; + for (const item of items) { + // ⚠ vitepress 传入的 item.url 是相对路径（"404.html"、"zh/x.html"、""）， + // 无前导斜杠也无域名——hostname 由 SitemapStream 事后拼接。 + if (/(^|\/)404\.html$/.test(item.url)) continue; // 404 页不收录 + if (/(^|\/)README\.html$/.test(item.url)) continue; // 仓库 README 非文档页 + const p = item.url.replace(/^\//, ""); + const rel = + p === "" || p === "index.html" ? "index.md" : p.replace(/\.html$/, ".md"); + const lastmod = dates.get(rel); + out.push(lastmod ? { ...item, lastmod } : item); + } + return out; + }, + }; + + return { transformPageData, transformHead, sitemap }; +} diff --git a/DjangoAdmin_Django_EleVue/.vitepress/config/shared.ts b/DjangoAdmin_Django_EleVue/.vitepress/config/shared.ts index 1a61689..5d75f49 100644 --- a/DjangoAdmin_Django_EleVue/.vitepress/config/shared.ts +++ b/DjangoAdmin_Django_EleVue/.vitepress/config/shared.ts @@ -1,6 +1,6 @@ import { defineConfig, HeadConfig } from "vitepress"; -export const META_IMAGE = "/social.png"; +export const META_IMAGE = "/logo.png"; const rControl = /[\u0000-\u001f]/g; const rSpecial = /[\s~`!@#$%^&*()\-_+=[\]{}|\\;:"'“”‘’<>,.?/]+/g; @@ -23,6 +23,8 @@ export const slugify = (str: string): string => export const sharedConfig = defineConfig({ title: "小蚂蚁云", + // 页面 <title> 后缀：「环境准备 | DjangoAdmin 开发文档」（index.md frontmatter 可覆盖） + titleTemplate: "DjangoAdmin 开发文档", appearance: "light", markdown: { diff --git a/DjangoAdmin_Django_EleVue/.vitepress/config/zh.ts b/DjangoAdmin_Django_EleVue/.vitepress/config/zh.ts index ff0144f..25a4cd2 100644 --- a/DjangoAdmin_Django_EleVue/.vitepress/config/zh.ts +++ b/DjangoAdmin_Django_EleVue/.vitepress/config/zh.ts @@ -1,6 +1,6 @@ import type { DefaultTheme, LocaleSpecificConfig } from "vitepress"; -export const META_URL = "https://www.djangoadmin.cn"; +export const META_URL = "http://docs.django.elevue.djangoadmin.cn"; export const META_TITLE = "DjangoAdmin 企业级中台解决方案"; export const META_DESCRIPTION = "DjangoAdmin 企业级中台解决方案 - Django + ElementPlus 前后端分离版本"; diff --git a/DjangoAdmin_Django_EleVue/404.md b/DjangoAdmin_Django_EleVue/404.md new file mode 100644 index 0000000..c344b20 --- /dev/null +++ b/DjangoAdmin_Django_EleVue/404.md @@ -0,0 +1,12 @@ +--- +head: + - - meta + - name: robots + content: noindex +--- + +# 页面不存在 + +抱歉，您访问的页面不存在或已被移动。 + +[返回首页](/) · [浏览文档](/zh/introduction) diff --git a/DjangoAdmin_Django_EleVue/package.json b/DjangoAdmin_Django_EleVue/package.json index 77bd941..b5517ed 100644 --- a/DjangoAdmin_Django_EleVue/package.json +++ b/DjangoAdmin_Django_EleVue/package.json @@ -5,7 +5,8 @@ "type": "module", "scripts": { "docs": "vitepress dev .", - "docs:build": "vitepress build .", + "docs:llms": "node scripts/generate-llms-txt.mjs", + "docs:build": "node scripts/generate-llms-txt.mjs && vitepress build .", "docs:preview": "vitepress preview ." }, "dependencies": { diff --git a/DjangoAdmin_Django_EleVue/public/llms.txt b/DjangoAdmin_Django_EleVue/public/llms.txt new file mode 100644 index 0000000..63368bd --- /dev/null +++ b/DjangoAdmin_Django_EleVue/public/llms.txt @@ -0,0 +1,165 @@ +# DjangoAdmin Django+ElementPlus 开发文档 + +> DjangoAdmin 企业级中台解决方案 - Django + ElementPlus 前后端分离版本。内置 RBAC 权限体系、代码生成器等开箱即用功能，支持五种数据库一键切换。本文档共 135 篇，按章节组织。 + +## 1. 了解项目 + +- [1.1 项目介绍](http://docs.django.elevue.djangoadmin.cn/zh/introduction.html): DjangoAdmin 是企业级中台解决方案，后端基于 Django + Django ORM，前端基于 Vue3 + ElementPlus，内置 RBAC 权限、代码生成器等开箱即用功能， +- [更新日志](http://docs.django.elevue.djangoadmin.cn/zh/changelog.html): 更新日志是项目演进的完整记录，帮助开发者和企业了解每个版本的能力变化与技术演进方向。 +- [新手入门指南](http://docs.django.elevue.djangoadmin.cn/zh/course.html): 详细的安装步骤请参考 环境准备 章节。 +- [项目目录结构](http://docs.django.elevue.djangoadmin.cn/zh/struct.html): 本页说明项目前后端目录组织与各目录职责，二次开发定位文件或了解工程结构时对照查阅。 +- [为什么选择我们](http://docs.django.elevue.djangoadmin.cn/zh/why.html): 本页从低代码生成能力、功能开箱即用与工程可持续性三个维度说明选择本项目的理由，技术选型对比时可作为评估依据。 + +## 2. 快速入门 + +- [后端启动](http://docs.django.elevue.djangoadmin.cn/zh/volume1/backend.html): 启动后端前，请确保已完成 环境准备 章节中的所有软件安装。 +- [数据库初始化](http://docs.django.elevue.djangoadmin.cn/zh/volume1/database.html): 数据库初始化前，请确保已完成以下准备工作： 1. 目标数据库服务已启动（如 MySQL 8.0+） 2. .env 文件中的 DATABASE_ENGINE 和数据库连接信息已正确配置 3. +- [Docker 一键启动](http://docs.django.elevue.djangoadmin.cn/zh/volume1/docker.html): 使用 Docker 方式启动前，请确保已安装以下软件： 1. Docker Desktop（Windows / macOS）或 Docker Engine（Linux） 2. Docker +- [环境变量速查表](http://docs.django.elevue.djangoadmin.cn/zh/volume1/env-vars.html): 1. .env 文件包含项目的敏感配置信息，已被 .gitignore 忽略，不会提交到版本控制。 +- [环境准备](http://docs.django.elevue.djangoadmin.cn/zh/volume1/environment.html): 1. 部分软件安装后需要设置本地环境变量，便于在终端中使用命令。 +- [常见问题FAQ](http://docs.django.elevue.djangoadmin.cn/zh/volume1/faq.html): 遇到问题时，建议先查看终端日志输出和浏览器控制台（F12）的错误信息，通常能快速定位问题原因。 +- [第一个接口调试](http://docs.django.elevue.djangoadmin.cn/zh/volume1/first-api.html): 开始调试前，请确保已完成以下步骤： 1. 后端服务已启动（参见 后端启动） 2. 数据库已初始化（参见 数据库初始化） 3. Redis 服务已启动 +- [前端启动](http://docs.django.elevue.djangoadmin.cn/zh/volume1/frontend.html): 启动前端前，请确保已完成 环境准备 章节中的 Node.js 和 pnpm 安装，并已启动后端服务（参见 后端启动）。 + +## 3. 模块开发实战 + +- [完整代码清单](http://docs.django.elevue.djangoadmin.cn/zh/volume2/code-list.html): 本页汇总案例管理（Example）模块涉及的全部文件代码，开发时可快速查阅与复制对照。 +- [常见问题与排错](http://docs.django.elevue.djangoadmin.cn/zh/volume2/faq.html): 本页汇总模块开发过程中的常见问题与排错方法，开发受阻时按症状索引即可定位。 +- [前端 API 层](http://docs.django.elevue.djangoadmin.cn/zh/volume2/fe-api.html): 前端 API 层封装后端接口的 HTTP 请求，每个业务模块对应一个 API 文件，本页讲解基于 Axios 封装的编写规范。 +- [前端路由与菜单](http://docs.django.elevue.djangoadmin.cn/zh/volume2/fe-router.html): 本页讲解前端路由与菜单机制——路由和菜单由后端动态返回，前端只需注册路由组件映射。 +- [前端页面视图](http://docs.django.elevue.djangoadmin.cn/zh/volume2/fe-view.html): 前端页面视图是用户直接交互的界面，本页讲解 Vue3 + ElementPlus 下一个完整 CRUD 页面的文件组成与编写方式。 +- [表单验证（Form）](http://docs.django.elevue.djangoadmin.cn/zh/volume2/form.html): 表单验证是模块开发的第二步，讲解基于 Django ModelForm 的提交数据校验与错误信息约定。 +- [数据模型（Model）](http://docs.django.elevue.djangoadmin.cn/zh/volume2/model.html): 数据模型是模块开发的第一步，讲解如何用 Django ORM 与 BaseModel 定义数据库表结构，新建模块时从本页开始。 +- [模块开发实战概述](http://docs.django.elevue.djangoadmin.cn/zh/volume2/overview.html): 本章以案例管理（Example）模块为完整案例，手把手演示从零开发一个业务模块的全流程，学完即可掌握项目中任意模块的开发方式。 +- [权限节点配置](http://docs.django.elevue.djangoadmin.cn/zh/volume2/permission.html): 本页讲解接口权限字符串的定义与菜单权限节点的配置方法，联调 403 问题时对照本页。 +- [业务逻辑层（Service）](http://docs.django.elevue.djangoadmin.cn/zh/volume2/service.html): 业务逻辑层是模块开发的核心，CRUD 操作、业务规则与数据处理均封装在 Service 层函数，本页讲解其编写规范。 +- [URL 路由配置](http://docs.django.elevue.djangoadmin.cn/zh/volume2/url.html): URL 路由是模块开发的最后一步，本页讲解用 Django path() 将路径映射到视图类的配置方法。 +- [视图层（View）](http://docs.django.elevue.djangoadmin.cn/zh/volume2/view.html): 视图层负责处理 HTTP 请求并调用 Service 业务逻辑，本页讲解 Django 类视图的编写方式与响应约定。 + +## 4. 架构设计 + +- [第四章 架构设计 - 核心基类体系](http://docs.django.elevue.djangoadmin.cn/zh/volume3/base-classes.html): 本页汇总项目核心基类体系的总览与用法，编写业务代码前先了解可复用的基座能力。 +- [第四章 架构设计 - 缓存架构](http://docs.django.elevue.djangoadmin.cn/zh/volume3/cache.html): 本页说明系统缓存架构的设计与使用方式，涉及缓存一致性或性能问题时查阅。 +- [数据库设计指南](http://docs.django.elevue.djangoadmin.cn/zh/volume3/database-design-guide.html): 本文介绍本项目的数据库设计规范，包括表命名、字段类型选择、索引策略、常见表模式等。 +- [第四章 架构设计 - 数据库设计](http://docs.django.elevue.djangoadmin.cn/zh/volume3/database-design.html): 本页说明数据库设计原则与表结构组织方式，建表或数据迁移时对照本页。 +- [第四章 架构设计 - 目录结构设计](http://docs.django.elevue.djangoadmin.cn/zh/volume3/directory.html): 本页说明项目根目录与各层目录的组织设计，二次开发定位文件时对照查阅。 +- [第四章 架构设计 - 扩展性设计](http://docs.django.elevue.djangoadmin.cn/zh/volume3/extensibility.html): 本页说明系统的扩展性设计原则，二次开发新增能力或改造现有模块时参考。 +- [第四章 架构设计 - 分层架构详解](http://docs.django.elevue.djangoadmin.cn/zh/volume3/layer-arch.html): 本页详解后端分层架构的职责划分与调用关系，编写代码前先理解各层边界。 +- [第四章 架构设计 - 系统架构总览](http://docs.django.elevue.djangoadmin.cn/zh/volume3/overview.html): 本页给出系统整体架构总览，理解各层职责与模块关系时从本页开始。 +- [性能优化指南](http://docs.django.elevue.djangoadmin.cn/zh/volume3/performance.html): 本文介绍本项目中常见的性能优化策略，涵盖后端 ORM 查询、缓存、分页、前端加载等方面。 +- [第四章 架构设计 - 请求处理流程](http://docs.django.elevue.djangoadmin.cn/zh/volume3/request-flow.html): 本页给出请求从进入路由到返回响应的全链路处理流程，排查接口问题时对照追踪。 +- [第四章 架构设计 - 安全架构](http://docs.django.elevue.djangoadmin.cn/zh/volume3/security.html): 本页说明系统安全架构设计，含认证、权限与数据安全等防护机制。 +- [第四章 架构设计 - 技术栈选型](http://docs.django.elevue.djangoadmin.cn/zh/volume3/tech-stack.html): 本页列出项目后端与前端完整技术选型及版本要求，评估兼容性或升级影响时对照本表。 + +## 5. 开发指南 + +- [API 接口速查表](http://docs.django.elevue.djangoadmin.cn/zh/volume4/api-cheatsheet.html): API 接口速查表，按模块分组列出所有 RESTful 接口的请求方法、路径、说明和权限标识。 +- [文章管理](http://docs.django.elevue.djangoadmin.cn/zh/volume4/business/article.html): 文章管理模块支持富文本编辑、分类关联、封面图片上传、图集管理等功能。 +- [分类管理](http://docs.django.elevue.djangoadmin.cn/zh/volume4/business/category.html): 分类管理模块用于管理树形分类数据，如文章分类、产品分类等。 +- [行政区划管理](http://docs.django.elevue.djangoadmin.cn/zh/volume4/business/city.html): 城市管理模块用于管理行政区划数据，支持省/市/区/街道/社区五级行政区划。 +- [公告与链接管理](http://docs.django.elevue.djangoadmin.cn/zh/volume4/business/content.html): 公告和链接是两个简单 CRUD 内容模块，提供标准的增删改查接口。 +- [部门/职级/岗位管理](http://docs.django.elevue.djangoadmin.cn/zh/volume4/business/dept.html): 部门、职级、岗位是组织架构管理的三个核心模块。 +- [定时任务](http://docs.django.elevue.djangoadmin.cn/zh/volume4/business/job.html): 定时任务模块基于 APScheduler 实现，支持 Cron 表达式调度、任务执行日志、动态启停等功能。 +- [菜单管理](http://docs.django.elevue.djangoadmin.cn/zh/volume4/business/menu.html): 菜单管理是 RBAC 权限系统的基础，负责管理系统的导航菜单和权限节点。 +- [参数管理](http://docs.django.elevue.djangoadmin.cn/zh/volume4/business/param.html): 参数管理模块用于管理动态系统参数，支持按参数键查询、修改，无需重启服务即可生效。 +- [角色管理](http://docs.django.elevue.djangoadmin.cn/zh/volume4/business/role.html): 角色是 RBAC 权限模型的核心，连接用户和菜单（权限）。 +- [用户管理](http://docs.django.elevue.djangoadmin.cn/zh/volume4/business/user.html): 用户管理是系统的核心模块，属于复杂业务模块。 +- [认证流程实战](http://docs.django.elevue.djangoadmin.cn/zh/volume4/core/auth-flow.html): 登录 -> Token 获取 -> 权限校验 -> Token 刷新 -> 退出登录的完整认证链路实战说明。 +- [验证码机制](http://docs.django.elevue.djangoadmin.cn/zh/volume4/core/captcha.html): 验证码是防止自动化攻击的重要安全手段。 +- [系统配置管理](http://docs.django.elevue.djangoadmin.cn/zh/volume4/core/config.html): 系统配置模块用于管理动态的键值对配置项，与数据字典类似但更偏向系统级参数。 +- [跨域资源共享（CORS）](http://docs.django.elevue.djangoadmin.cn/zh/volume4/core/cors.html): CORS（Cross-Origin Resource Sharing）跨域资源共享是前后端分离架构必须处理的问题。 +- [演示模式](http://docs.django.elevue.djangoadmin.cn/zh/volume4/core/demo-mode.html): 演示模式用于在线体验环境，开启后所有写操作（新增、编辑、删除等）将被拦截，返回"演示环境，暂无操作权限"提示。 +- [数据字典使用指南](http://docs.django.elevue.djangoadmin.cn/zh/volume4/core/dict-guide.html): 数据字典的完整使用流程，从新增字典类型到在代码中使用字典数据的实操指南。 +- [字典模块](http://docs.django.elevue.djangoadmin.cn/zh/volume4/core/dict.html): 数据字典用于管理系统中的枚举值和配置项，如状态、类型、性别等。 +- [异常与响应处理](http://docs.django.elevue.djangoadmin.cn/zh/volume4/core/exception.html): 定义了统一的响应格式和全局异常处理机制。 +- [防重复提交](http://docs.django.elevue.djangoadmin.cn/zh/volume4/core/idempotent.html): 防重复提交是保障数据一致性的重要措施。 +- [用户认证（JWT）](http://docs.django.elevue.djangoadmin.cn/zh/volume4/core/jwt.html): JWT（JSON Web Token）是系统的核心认证机制。 +- [登录日志](http://docs.django.elevue.djangoadmin.cn/zh/volume4/core/login-log.html): 登录日志记录每次登录尝试（成功/失败），包含登录账号、IP地址、浏览器信息、登录时间等。 +- [操作日志](http://docs.django.elevue.djangoadmin.cn/zh/volume4/core/operation-log.html): 操作日志通过 @operation_log 装饰器标记需要记录日志的视图方法，自动记录请求参数、响应结果、耗时、操作类型等信息。 +- [请求限流](http://docs.django.elevue.djangoadmin.cn/zh/volume4/core/rate-limit.html): 请求限流可通过中间件实现 IP 级别的限流，防止恶意请求和 DoS 攻击。 +- [权限管理（RBAC）](http://docs.django.elevue.djangoadmin.cn/zh/volume4/core/rbac.html): 采用基于角色的访问控制（RBAC）模型，通过用户-角色-菜单三层关系实现细粒度的权限管理。 +- [参数验证（Form）](http://docs.django.elevue.djangoadmin.cn/zh/volume4/core/validator.html): 使用 Django ModelForm 进行请求参数验证。 +- [API 层开发](http://docs.django.elevue.djangoadmin.cn/zh/volume4/frontend/api.html): 前端 API 层位于 src/api/ 目录，封装所有与后端的 HTTP 请求。 +- [前端构建](http://docs.django.elevue.djangoadmin.cn/zh/volume4/frontend/build.html): 前端使用 Vite 构建，支持开发服务器和生产构建。 +- [公共组件库](http://docs.django.elevue.djangoadmin.cn/zh/volume4/frontend/components.html): 项目提供丰富的公共组件，位于 ui/src/components/ 目录，基于 ElementPlus 二次封装，覆盖表格、表单、弹窗、上传、富文本编辑等常见场景。 +- [BasicForm 表单](http://docs.django.elevue.djangoadmin.cn/zh/volume4/frontend/form.html): BasicForm 位于 src/components/Form/src/BasicForm.vue，基于 ElementPlus 的 el-form 二次封装，通过 schemas +- [Hooks 组合式函数](http://docs.django.elevue.djangoadmin.cn/zh/volume4/frontend/hooks.html): 项目封装了一系列组合式函数（Hooks），位于 src/hooks/ 和 src/utils/ 目录，提供权限检查、异步 loading、防重复提交、实时时钟、项目配置等可复用逻辑。 +- [国际化](http://docs.django.elevue.djangoadmin.cn/zh/volume4/frontend/i18n.html): 当前项目仅支持中文界面，ElementPlus 使用中文语言包（zh-cn），所有界面文本直接硬编码在组件中。 +- [Modal 弹窗](http://docs.django.elevue.djangoadmin.cn/zh/volume4/frontend/modal.html): 项目提供 BasicModal 组件（src/components/Modal/src/BasicModal.vue）和原生 el-dialog 两种弹窗用法。 +- [权限指令 v-perm](http://docs.django.elevue.djangoadmin.cn/zh/volume4/frontend/perm-directive.html): v-perm 和 v-perms 是项目自定义的 Vue 指令，用于按钮级别的权限控制，无权限时自动从 DOM 中移除元素。 +- [路由与菜单](http://docs.django.elevue.djangoadmin.cn/zh/volume4/frontend/router.html): 前端路由基于 Vue Router 4 实现动态路由生成，菜单数据从后端获取，通过 generator-routers.ts 递归生成路由表，路由守卫控制登录状态和权限。 +- [前端环境与结构](http://docs.django.elevue.djangoadmin.cn/zh/volume4/frontend/setup.html): 前端基于 Vue3 + ElementPlus 构建，使用 pnpm 作为包管理工具，Vite 作为构建工具，TypeScript 作为开发语言。 +- [Store 状态管理](http://docs.django.elevue.djangoadmin.cn/zh/volume4/frontend/store.html): 前端使用 Pinia 进行状态管理，核心模块包括 user（用户信息与权限）、asyncRoute（动态路由与菜单）、projectSetting（项目配置）、designSetting（主题设计）等。 +- [样式与主题](http://docs.django.elevue.djangoadmin.cn/zh/volume4/frontend/style.html): 前端样式方案采用 Tailwind CSS + SCSS + ElementPlus 主题覆盖，支持深色模式切换。 +- [BasicTable 表格](http://docs.django.elevue.djangoadmin.cn/zh/volume4/frontend/table.html): BasicTable 位于 src/components/Table/src/Table.vue，基于 ElementPlus 的 el-table 二次封装，提供列定义、数据请求、分页、操作列、 +- [工具函数](http://docs.django.elevue.djangoadmin.cn/zh/volume4/frontend/utils.html): 前端工具函数位于 src/utils/ 目录，提供认证管理、本地存储、日期格式化、树结构操作、文件下载等通用能力。 +- [页面视图开发](http://docs.django.elevue.djangoadmin.cn/zh/volume4/frontend/view.html): 页面视图位于 src/views/ 目录，每个业务模块遵循 index.vue（列表页）+ edit.vue（编辑弹窗）+ detail.vue（详情弹窗）的标准模式，辅以 +- [接口响应规范](http://docs.django.elevue.djangoadmin.cn/zh/volume4/integration/api-contract.html): 后端所有接口统一返回 R.ok() / R.failed() 格式的 JSON 响应，前端通过 VAxios 的 transformRequestData 拦截器统一解包处理。 +- [字典数据联调](http://docs.django.elevue.djangoadmin.cn/zh/volume4/integration/dict-sync.html): 字典数据通过后端字典 API 获取，前端在下拉选择器中渲染选项。 +- [权限节点联动](http://docs.django.elevue.djangoadmin.cn/zh/volume4/integration/perm-sync.html): 前后端权限通过统一的权限节点字符串联动，后端 PermissionRequired 中间件校验权限，前端 v-perm 指令和 TableAction 的 auth 属性控制按钮显示。 +- [代理配置](http://docs.django.elevue.djangoadmin.cn/zh/volume4/integration/proxy.html): 开发环境通过 Vite 代理转发 API 请求到后端 Django 服务，生产环境通过 Nginx 代理。 +- [文件上传联调](http://docs.django.elevue.djangoadmin.cn/zh/volume4/integration/upload-sync.html): 文件上传涉及前端 Upload 组件、后端上传接口和 URL 拼接三个环节，需要前后端协同配置。 +- [数据库与 ORM](http://docs.django.elevue.djangoadmin.cn/zh/volume4/tools/db-session.html): 项目使用 Django ORM 作为数据库访问层，数据库连接配置位于 config/env.py 和 application/settings.py。 +- [导入导出](http://docs.django.elevue.djangoadmin.cn/zh/volume4/tools/excel.html): 基于 openpyxl 实现 Excel 导入导出功能，支持通过 file_template 模块管理导入模板配置。 +- [IP/UA 解析](http://docs.django.elevue.djangoadmin.cn/zh/volume4/tools/ip-ua.html): 提供客户端 IP 获取、IP 地理位置查询和 User-Agent 解析三大能力，位于 utils/common.py。 +- [日志系统](http://docs.django.elevue.djangoadmin.cn/zh/volume4/tools/logger.html): 通过 Python 标准库 logging 实现结构化日志，Django 框架内置日志配置，支持控制台 + 文件双输出。 +- [密码工具](http://docs.django.elevue.djangoadmin.cn/zh/volume4/tools/password.html): 密码加密使用 Django 内置的 make_password 和 check_password 函数，基于 PBKDF2 算法（默认工作因子 320000 次迭代）。 +- [权限缓存](http://docs.django.elevue.djangoadmin.cn/zh/volume4/tools/perm-cache.html): 通过 Redis 实现用户权限和菜单的缓存，采用用户级缓存 + 全局版本号双层策略。 +- [请求解析工具](http://docs.django.elevue.djangoadmin.cn/zh/volume4/tools/request-util.html): utils/common.py 提供请求数据解析相关的工具函数，核心函数 parse_request_body() 用于解析请求体 JSON 数据。 +- [富文本过滤](http://docs.django.elevue.djangoadmin.cn/zh/volume4/tools/rich-text.html): 富文本编辑器内容存在存储型 XSS 风险，通过 save_content() 函数实现 HTML 内容处理，在落盘前统一过滤危险内容并迁移嵌入图片。 +- [文件上传完整流程](http://docs.django.elevue.djangoadmin.cn/zh/volume4/tools/upload-guide.html): 富文本编辑器（如 WangEditor 等）的图片上传同样使用此接口。 +- [文件上传](http://docs.django.elevue.djangoadmin.cn/zh/volume4/tools/upload.html): 提供本地文件上传功能，支持图片和通用文件上传，内置扩展名白名单校验。 + +## 6. 代码生成器 + +- [CLI 命令行使用](http://docs.django.elevue.djangoadmin.cn/zh/volume5/cli.html): 代码生成器 CLI 模式的使用方法，包括单表生成、预览模式和配置导出。 +- [代码生成引擎](http://docs.django.elevue.djangoadmin.cn/zh/volume5/code-engine.html): 代码生成引擎的工作原理，包括配置解析、模板渲染、文件写入和自动注册的完整流程。 +- [配置文件详解](http://docs.django.elevue.djangoadmin.cn/zh/volume5/config.html): 代码生成器 JSON 配置文件的格式说明，包括模块名称、字段属性等配置项的详细解释。 +- [实战案例](http://docs.django.elevue.djangoadmin.cn/zh/volume5/demo.html): 以 django_example 演示表为完整案例，演示从建表到生成到使用的全流程。 +- [常见问题](http://docs.django.elevue.djangoadmin.cn/zh/volume5/faq.html): 代码生成器使用过程中常见问题的原因分析和解决方案。 +- [概述与架构](http://docs.django.elevue.djangoadmin.cn/zh/volume5/overview.html): 代码生成器的整体架构、核心模块和生成流程概述。 +- [表结构解析引擎](http://docs.django.elevue.djangoadmin.cn/zh/volume5/parser.html): 表结构解析引擎的工作原理，从数据库读取表元数据并智能推断字段用途的过程。 +- [自定义模板](http://docs.django.elevue.djangoadmin.cn/zh/volume5/templates.html): 代码生成器模板的 Jinja2 语法说明，包括模板变量、字段属性和自定义模板的开发方法。 +- [Web 管理界面](http://docs.django.elevue.djangoadmin.cn/zh/volume5/web-ui.html): 代码生成器 Web 管理界面的使用方法，通过可视化界面操作单表生成和批量生成。 + +## 7. 运维部署 + +- [备份与恢复](http://docs.django.elevue.djangoadmin.cn/zh/volume6/backup.html): - 3 份数据副本（1 份生产 + 2 份备份） - 2 种不同存储介质（如本地磁盘 + 远程存储） - 1 份异地备份（防机房级灾难） +- [CI/CD 流水线配置](http://docs.django.elevue.djangoadmin.cn/zh/volume6/ci-cd.html): CI/CD（持续集成/持续部署）是现代开发流程的基础设施。 +- [数据库迁移](http://docs.django.elevue.djangoadmin.cn/zh/volume6/db-migrate.html): - 结构迁移：Django 内置迁移系统（makemigrations + migrate） - 字段注释：Django 4.1+ 通过 db_comment 参数自动添加数据库字段注释 +- [部署 Checklist](http://docs.django.elevue.djangoadmin.cn/zh/volume6/deploy-checklist.html): 从服务器准备到应用上线的完整部署操作清单，适用于生产环境首次部署和后续版本更新。 +- [Docker容器化](http://docs.django.elevue.djangoadmin.cn/zh/volume6/docker.html): - 环境一致性：消除"在我机器上能跑"的问题 - 快速部署：一条命令启动完整服务 - 资源隔离：应用与宿主机环境解耦 +- [环境规划](http://docs.django.elevue.djangoadmin.cn/zh/volume6/env-plan.html): 各环境之间保持代码一致，仅通过环境变量（.env）区分配置。 +- [健康检查与监控](http://docs.django.elevue.djangoadmin.cn/zh/volume6/monitoring.html): `` 1. 应用层：健康检查端点、业务指标 2. 系统层：CPU/内存/磁盘/网络 3. 中间件：MySQL/Redis 连接状态 4. 日志：集中式日志收集与分析 `` +- [Nginx 反向代理](http://docs.django.elevue.djangoadmin.cn/zh/volume6/nginx.html): `` 客户端 -> Nginx（80/443） ├─ / -> 前端静态资源（dist/） ├─ /api/... -> Django 后端（8000） ├─ /static/ -> Django +- [性能调优](http://docs.django.elevue.djangoadmin.cn/zh/volume6/performance.html): 1. 先测量，后优化：用数据说话，避免盲目调参 2. 瓶颈优先：找到最大瓶颈，集中优化 3. 渐进式：每次只调整一个参数，观察效果 +- [多实例与负载均衡](http://docs.django.elevue.djangoadmin.cn/zh/volume6/scaling.html): 当单台服务器无法满足性能需求时，需要通过多实例部署和负载均衡来提升系统吞吐量。 +- [安全加固](http://docs.django.elevue.djangoadmin.cn/zh/volume6/security-hardening.html): - 最小权限：只开放必要的端口和权限 - 纵深防御：多层安全措施叠加 - 默认安全：配置默认值应为安全选项 +- [Supervisor进程管理](http://docs.django.elevue.djangoadmin.cn/zh/volume6/supervisor.html): - Linux 服务器直接部署（非 Docker） - 需要进程自动重启和日志轮转 - 管理多个相关进程 +- [故障排查手册](http://docs.django.elevue.djangoadmin.cn/zh/volume6/troubleshooting.html): 1. 查看日志：tail -f logs/supervisor.out.log 或 docker-compose logs -f 2. 检查配置：.env 文件、数据库连接、Redis 连接 3. +- [版本升级流程](http://docs.django.elevue.djangoadmin.cn/zh/volume6/upgrade.html): 1. 先备份，后升级 2. 先测试环境，后生产环境 3. 每次升级可回滚 4. 低峰期执行升级 + +## 8. 规范标准 + +- [API响应规范](http://docs.django.elevue.djangoadmin.cn/zh/volume7/api-response.html): - 所有接口必须通过 R.ok() 或 R.failed() 返回，禁止直接返回 dict - 成功响应 code=0，失败响应 code=1 - 响应体始终包含 code、data、msg、ok +- [代码审查清单](http://docs.django.elevue.djangoadmin.cn/zh/volume7/code-review.html): - 每次提交必须经过至少一人审查 - 审查关注点：正确性 > 安全性 > 可维护性 > 性能 - 审查意见应具体、可操作，避免主观评价 +- [代码风格与 Lint 规范](http://docs.django.elevue.djangoadmin.cn/zh/volume7/code-style.html): 统一的代码风格是团队协作的基础。 +- [删除规范](http://docs.django.elevue.djangoadmin.cn/zh/volume7/deletion.html): - is_delete = False（0）：正常记录（默认值） - is_delete = True（1）：已删除记录 - 所有查询方法自动过滤 is_delete=False，业务层无需关心 +- [文档规范](http://docs.django.elevue.djangoadmin.cn/zh/volume7/doc-standard.html): - 文档与代码同步更新 - 使用中文编写（项目约定） - 示例代码可直接运行 +- [前端 API 规范](http://docs.django.elevue.djangoadmin.cn/zh/volume7/fe-api.html): - 每个后端模块对应一个 API 文件 - 函数命名统一使用 名词 + 动词 格式（与后端保持一致） - 请求路径使用相对路径（/position/page），不含 /api/v1 前缀（由 +- [前端页面规范](http://docs.django.elevue.djangoadmin.cn/zh/volume7/fe-component.html): - Vue3（Composition API + <script setup>） - ElementPlus - 自定义组件（BasicTable / BasicForm / TableAction +- [Form层规范](http://docs.django.elevue.djangoadmin.cn/zh/volume7/form.html): - 继承 forms.ModelForm - 每个字段定义中文 error_messages - 使用 Meta.fields 指定验证字段 - 验证在 Service 层 ORM 操作之前执行 +- [Git提交规范](http://docs.django.elevue.djangoadmin.cn/zh/volume7/git.html): `` <type>(<scope>): <subject> <body> <footer> `` +- [Model层规范](http://docs.django.elevue.djangoadmin.cn/zh/volume7/model.html): - 所有模型继承 BaseModel - 字段命名使用 snake_case - 每个字段必须有 db_comment 注释 - 使用 get_table_name() 生成表名 +- [分页规范](http://docs.django.elevue.djangoadmin.cn/zh/volume7/pagination.html): - 前端传递 pageNo（页码，从 1 开始）和 pageSize（每页条数） - 后端返回 {records, total, size, current, pages} 结构 - 默认每页 10 +- [Service层规范](http://docs.django.elevue.djangoadmin.cn/zh/volume7/service.html): - 所有业务逻辑集中在 Service 层 - View 层只负责接收请求和返回响应 - Model 层只负责数据定义 - Form 层只负责数据验证 +- [测试最佳实践](http://docs.django.elevue.djangoadmin.cn/zh/volume7/testing-best-practices.html): 本文在 测试规范 基础上，介绍更高级的测试技巧，包括 Mock、Fixture、API 测试、覆盖率实战等。 +- [测试规范](http://docs.django.elevue.djangoadmin.cn/zh/volume7/testing.html): 1. 单元测试（Unit）：验证单个函数/方法的逻辑正确性 2. 集成测试（Integration）：验证模块间协作、真实数据库操作 +- [View层规范](http://docs.django.elevue.djangoadmin.cn/zh/volume7/view.html): - 使用类视图（继承 View） - 通过 @method_decorator(check_login) 验证登录 - 通过 PermissionRequired mixin 检查权限 - 通过 + +## 附录 + +- [常见问题汇总](http://docs.django.elevue.djangoadmin.cn/zh/faq.html): 本页汇总了项目各模块的常见问题及解决方案，按场景分类索引。 +- [贡献指南](http://docs.django.elevue.djangoadmin.cn/zh/other/contributing.html): 本页介绍如何参与项目贡献，包括代码提交、Issue 反馈与 PR 流程，欢迎关注本项目的开发者参阅。 +- [免责声明](http://docs.django.elevue.djangoadmin.cn/zh/other/declare.html): 使用本产品前必读的法律声明，明确产品性质、使用限制与责任划分，一旦使用本产品即视为接受本声明全部条款。 +- [广告赞助](http://docs.django.elevue.djangoadmin.cn/zh/other/sponsor.html): 1. 投放广告不得与官方全系产品存在结构性冲突和竞争 2. 广告内容需符合国家法律法规，不得包含虚假、误导性信息 3. 广告素材需经官方审核通过后方可上线，审核周期 1-3 个工作日 4. diff --git a/DjangoAdmin_Django_EleVue/public/robots.txt b/DjangoAdmin_Django_EleVue/public/robots.txt new file mode 100644 index 0000000..32cec47 --- /dev/null +++ b/DjangoAdmin_Django_EleVue/public/robots.txt @@ -0,0 +1,33 @@ +# DjangoAdmin Django+ElementPlus 开发文档 +User-agent: * +Allow: / + +# 显式放行生成式引擎 / AI 爬虫（GEO） +User-agent: GPTBot +Allow: / + +User-agent: ChatGPT-User +Allow: / + +User-agent: ClaudeBot +Allow: / + +User-agent: Claude-Web +Allow: / + +User-agent: anthropic-ai +Allow: / + +User-agent: PerplexityBot +Allow: / + +User-agent: Google-Extended +Allow: / + +User-agent: Bytespider +Allow: / + +User-agent: bingbot +Allow: / + +Sitemap: http://docs.django.elevue.djangoadmin.cn/sitemap.xml diff --git a/DjangoAdmin_Django_EleVue/scripts/generate-llms-txt.mjs b/DjangoAdmin_Django_EleVue/scripts/generate-llms-txt.mjs new file mode 100644 index 0000000..cb81e8d --- /dev/null +++ b/DjangoAdmin_Django_EleVue/scripts/generate-llms-txt.mjs @@ -0,0 +1,122 @@ +#!/usr/bin/env node +/** + * 生成 public/llms.txt（llmstxt.org 标准）——AI 爬虫的站点摘要索引。 + * + * 数据源：zh 目录下全部 Markdown 的 H1 + :::tip 概述首句（与 meta + * description 同源，复用 .vitepress/config/extract.mjs）。按侧边栏章节分组。 + * + * 用法：node scripts/generate-llms-txt.mjs + * 已挂入 package.json 的 docs:build 前置步骤。 + */ +import fs from "node:fs"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; +import { + SITE_URL, + SITE_DESCRIPTION, + extractDescription, +} from "../.vitepress/config/extract.mjs"; + +const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."); +const ZH = path.join(ROOT, "zh"); + +/** 顶层目录 → 侧边栏章节名（与 .vitepress/config/zh.ts 保持一致） */ +const SECTIONS = [ + ["", "1. 了解项目"], + ["volume1", "2. 快速入门"], + ["volume2", "3. 模块开发实战"], + ["volume3", "4. 架构设计"], + ["volume4", "5. 开发指南"], + ["volume5", "6. 代码生成器"], + ["volume6", "7. 运维部署"], + ["volume7", "8. 规范标准"], + ["other", "附录"], +]; + +function walk(dir, out = []) { + for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { + const p = path.join(dir, entry.name); + if (entry.isDirectory()) walk(p, out); + else if (entry.name.endsWith(".md")) out.push(p); + } + return out; +} + +/** 提取首个 H1 文本 */ +function h1Of(md) { + // 围栏感知：跳过 ``` 代码块内的 # 注释，取真正的页面 H1 + let inFence = false; + for (const line of md.split("\n")) { + if (line.startsWith("```")) { inFence = !inFence; continue; } + if (!inFence && line.startsWith("# ") && !line.startsWith("## ")) { + return line.slice(2).trim(); + } + } + return ""; +} + +/** H1 编号排序键："5.10 x" → [5,10]；无编号排最后 */ +function sortKey(h1) { + const m = h1.match(/^(\d+(?:\.\d+)*)/); + if (m) return m[1].split(".").map(Number); + const letter = h1.match(/^([A-Z])\./); + if (letter) return [1000 + letter[1].charCodeAt(0)]; + return [9999]; +} + +function cmpKey(a, b) { + const len = Math.max(a.length, b.length); + for (let i = 0; i < len; i++) { + const x = a[i] ?? 0; + const y = b[i] ?? 0; + if (x !== y) return x - y; + } + return 0; +} + +const files = walk(ZH); +const groups = new Map(SECTIONS.map(([dir, label]) => [label, []])); + +for (const file of files) { + const rel = path.relative(ZH, file).replace(/\\/g, "/"); + const topDir = rel.includes("/") ? rel.split("/")[0] : ""; + const base = rel.split("/").pop(); + const label = (topDir === "" && base === "faq.md") ? "附录" + : SECTIONS.find(([dir]) => dir === topDir)?.[1] ?? "附录"; + + const md = fs.readFileSync(file, "utf8"); + const h1 = h1Of(md); + if (!h1) continue; + const desc = extractDescription(md); + const url = `${SITE_URL}/zh/${rel.replace(/\.md$/, ".html")}`; + groups.get(label).push({ h1, desc, url, key: sortKey(h1) }); +} + +const lines = [ + "# DjangoAdmin Django+ElementPlus 开发文档", + "", + `> ${SITE_DESCRIPTION}。内置 RBAC 权限体系、代码生成器等开箱即用功能，支持五种数据库一键切换。本文档共 ${files.length} 篇，按章节组织。`, + "", +]; + +// 按章节顺序输出，合并重复 label（appendix/other 同为「附录」，只输出一次） +const printed = new Set(); +for (const [, label] of SECTIONS) { + if (printed.has(label)) continue; + const items = groups.get(label); + if (!items?.length) continue; + printed.add(label); + + lines.push(`## ${label}`, ""); + items.sort((a, b) => cmpKey(a.key, b.key)); + for (const { h1, desc, url } of items) { + lines.push(desc ? `- [${h1}](${url}): ${desc}` : `- [${h1}](${url})`); + } + lines.push(""); +} + +const out = path.join(ROOT, "public", "llms.txt"); +fs.writeFileSync(out, lines.join("\n"), "utf8"); +console.log( + `llms.txt: ${files.length} 页 → ${path.relative(ROOT, out)} (${printed.size} 个章节)`, +); diff --git a/DjangoAdmin_Django_EleVue/zh/course.md b/DjangoAdmin_Django_EleVue/zh/course.md index 0dcdcaa..6601fef 100644 --- a/DjangoAdmin_Django_EleVue/zh/course.md +++ b/DjangoAdmin_Django_EleVue/zh/course.md @@ -1,3 +1,5 @@ +# 新手入门指南 + :::warning 特别提醒 官方精心制作本教程，目的在于方便用户快速掌握软件产品的使用和部署。通过此教程，刚入行的开发者也可以快速掌握并投入产品研发。本地部署时务必请耐心阅读文档操作。 ::: diff --git a/DjangoAdmin_Django_EleVue/zh/introduction.md b/DjangoAdmin_Django_EleVue/zh/introduction.md index 7a0606d..15fe90c 100644 --- a/DjangoAdmin_Django_EleVue/zh/introduction.md +++ b/DjangoAdmin_Django_EleVue/zh/introduction.md @@ -1,3 +1,9 @@ +# 1.1 项目介绍 + +:::tip 概述 +DjangoAdmin 是企业级中台解决方案，后端基于 Django + Django ORM，前端基于 Vue3 + ElementPlus，内置 RBAC 权限、代码生成器等开箱即用功能，支持五种数据库一键切换。 +::: + <div align="center"> <p align="center"> <img src="/logo.png" height="150" alt="logo"/> diff --git a/DjangoAdmin_Django_EleVue/zh/other/contributing.md b/DjangoAdmin_Django_EleVue/zh/other/contributing.md index 68c9275..662dc17 100644 --- a/DjangoAdmin_Django_EleVue/zh/other/contributing.md +++ b/DjangoAdmin_Django_EleVue/zh/other/contributing.md @@ -1,7 +1,7 @@ # 贡献指南 :::tip 说明 -感谢你对本项目的关注！本文档介绍如何参与项目贡献，包括代码提交、Issue 反馈、PR 流程等。 +本页介绍如何参与项目贡献，包括代码提交、Issue 反馈与 PR 流程，欢迎关注本项目的开发者参阅。 ::: ## 开发环境搭建 diff --git a/DjangoAdmin_Django_EleVue/zh/other/declare.md b/DjangoAdmin_Django_EleVue/zh/other/declare.md index 7737479..915692a 100644 --- a/DjangoAdmin_Django_EleVue/zh/other/declare.md +++ b/DjangoAdmin_Django_EleVue/zh/other/declare.md @@ -1,5 +1,9 @@ # 免责声明 +:::tip 概述 +使用本产品前必读的法律声明，明确产品性质、使用限制与责任划分，一旦使用本产品即视为接受本声明全部条款。 +::: + :::danger 重要提示 任何用户在使用本团队研发的系列软件产品（以下简称「本产品」）前，请仔细阅读并透彻理解本声明。选择不使用本产品，可随时停止使用；一旦使用本产品，即视为对本声明全部内容的认可和接受。 ::: diff --git a/DjangoAdmin_Django_EleVue/zh/struct.md b/DjangoAdmin_Django_EleVue/zh/struct.md index 5347f87..a58356a 100644 --- a/DjangoAdmin_Django_EleVue/zh/struct.md +++ b/DjangoAdmin_Django_EleVue/zh/struct.md @@ -1,5 +1,9 @@ # 项目目录结构 +:::tip 概述 +本页说明项目前后端目录组织与各目录职责，二次开发定位文件或了解工程结构时对照查阅。 +::: + ## 整体结构 ``` diff --git a/DjangoAdmin_Django_EleVue/zh/volume2/code-list.md b/DjangoAdmin_Django_EleVue/zh/volume2/code-list.md index a41990f..2a26172 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume2/code-list.md +++ b/DjangoAdmin_Django_EleVue/zh/volume2/code-list.md @@ -1,5 +1,9 @@ # 完整代码清单 +:::tip 概述 +本页汇总案例管理（Example）模块涉及的全部文件代码，开发时可快速查阅与复制对照。 +::: + 本章汇总 Example 案例模块涉及的全部文件，便于开发时快速查阅和复制。 ## 后端文件清单 diff --git a/DjangoAdmin_Django_EleVue/zh/volume2/faq.md b/DjangoAdmin_Django_EleVue/zh/volume2/faq.md index 1eb4a98..e84a4c0 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume2/faq.md +++ b/DjangoAdmin_Django_EleVue/zh/volume2/faq.md @@ -1,5 +1,9 @@ # 常见问题与排错 +:::tip 概述 +本页汇总模块开发过程中的常见问题与排错方法，开发受阻时按症状索引即可定位。 +::: + 本章汇总模块开发过程中的常见问题和解决方案。 ## 后端问题 diff --git a/DjangoAdmin_Django_EleVue/zh/volume2/fe-api.md b/DjangoAdmin_Django_EleVue/zh/volume2/fe-api.md index 8d52e68..7c1f64f 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume2/fe-api.md +++ b/DjangoAdmin_Django_EleVue/zh/volume2/fe-api.md @@ -1,5 +1,9 @@ # 前端 API 层 +:::tip 概述 +前端 API 层封装后端接口的 HTTP 请求，每个业务模块对应一个 API 文件，本页讲解基于 Axios 封装的编写规范。 +::: + 前端 API 层负责封装后端接口的 HTTP 请求。每个业务模块对应一个 API 文件，使用项目封装的 Axios 工具发送请求。 ## 文件位置 diff --git a/DjangoAdmin_Django_EleVue/zh/volume2/fe-router.md b/DjangoAdmin_Django_EleVue/zh/volume2/fe-router.md index 04bc70a..20e3913 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume2/fe-router.md +++ b/DjangoAdmin_Django_EleVue/zh/volume2/fe-router.md @@ -1,5 +1,9 @@ # 前端路由与菜单 +:::tip 概述 +本页讲解前端路由与菜单机制——路由和菜单由后端动态返回，前端只需注册路由组件映射。 +::: + 前端路由定义页面的访问路径，菜单是路由的可视化展示。项目的路由和菜单由后端动态返回，前端只需注册路由组件映射。 ## 动态路由机制 diff --git a/DjangoAdmin_Django_EleVue/zh/volume2/fe-view.md b/DjangoAdmin_Django_EleVue/zh/volume2/fe-view.md index 37d8d3a..cca2df8 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume2/fe-view.md +++ b/DjangoAdmin_Django_EleVue/zh/volume2/fe-view.md @@ -1,5 +1,9 @@ # 前端页面视图 +:::tip 概述 +前端页面视图是用户直接交互的界面，本页讲解 Vue3 + ElementPlus 下一个完整 CRUD 页面的文件组成与编写方式。 +::: + 前端页面视图是用户直接交互的界面。项目使用 Vue3 + ElementPlus + Vite 构建。一个完整的 CRUD 页面由 5 个文件组成： ``` diff --git a/DjangoAdmin_Django_EleVue/zh/volume2/form.md b/DjangoAdmin_Django_EleVue/zh/volume2/form.md index 884ad47..7b24bba 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume2/form.md +++ b/DjangoAdmin_Django_EleVue/zh/volume2/form.md @@ -1,5 +1,9 @@ # 表单验证（Form） +:::tip 概述 +表单验证是模块开发的第二步，讲解基于 Django ModelForm 的提交数据校验与错误信息约定。 +::: + 表单验证是模块开发的第二步，用于对前端提交的数据进行验证。项目使用 Django 的 `ModelForm` 实现表单验证，所有错误信息使用中文提示。 ## 文件位置 diff --git a/DjangoAdmin_Django_EleVue/zh/volume2/model.md b/DjangoAdmin_Django_EleVue/zh/volume2/model.md index 8c80c0f..e10cb25 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume2/model.md +++ b/DjangoAdmin_Django_EleVue/zh/volume2/model.md @@ -1,5 +1,9 @@ # 数据模型（Model） +:::tip 概述 +数据模型是模块开发的第一步，讲解如何用 Django ORM 与 BaseModel 定义数据库表结构，新建模块时从本页开始。 +::: + 数据模型是模块开发的第一步，用于定义数据库表结构。项目使用 Django ORM，模型类通过继承 `BaseModel` 自动获得通用字段。 ## 文件位置 diff --git a/DjangoAdmin_Django_EleVue/zh/volume2/overview.md b/DjangoAdmin_Django_EleVue/zh/volume2/overview.md index 4db86b4..f476f00 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume2/overview.md +++ b/DjangoAdmin_Django_EleVue/zh/volume2/overview.md @@ -1,5 +1,9 @@ # 模块开发实战概述 +:::tip 概述 +本章以案例管理（Example）模块为完整案例，手把手演示从零开发一个业务模块的全流程，学完即可掌握项目中任意模块的开发方式。 +::: + 本章以「案例管理（Example）」模块为完整案例，手把手演示从零开发一个业务模块的全流程。学完本章后，你将掌握项目中任意模块的开发方式。 ## 你将学到什么 diff --git a/DjangoAdmin_Django_EleVue/zh/volume2/permission.md b/DjangoAdmin_Django_EleVue/zh/volume2/permission.md index 4199045..9210515 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume2/permission.md +++ b/DjangoAdmin_Django_EleVue/zh/volume2/permission.md @@ -1,5 +1,9 @@ # 权限节点配置 +:::tip 概述 +本页讲解接口权限字符串的定义与菜单权限节点的配置方法，联调 403 问题时对照本页。 +::: + 后端代码中的 `permission_required = ("sys:example:page",)` 定义了接口所需的权限字符串，但权限节点本身需要在数据库中配置，才能在「菜单管理」中分配给角色。 ## 权限字符串格式 diff --git a/DjangoAdmin_Django_EleVue/zh/volume2/service.md b/DjangoAdmin_Django_EleVue/zh/volume2/service.md index 0910d08..7937611 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume2/service.md +++ b/DjangoAdmin_Django_EleVue/zh/volume2/service.md @@ -1,5 +1,9 @@ # 业务逻辑层（Service） +:::tip 概述 +业务逻辑层是模块开发的核心，CRUD 操作、业务规则与数据处理均封装在 Service 层函数，本页讲解其编写规范。 +::: + 业务逻辑层是模块开发的第三步，也是最核心的部分。所有 CRUD 操作、业务规则、数据处理都封装在 Service 层的独立函数中。 ## 文件位置 diff --git a/DjangoAdmin_Django_EleVue/zh/volume2/url.md b/DjangoAdmin_Django_EleVue/zh/volume2/url.md index 024e2c7..9c8c74e 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume2/url.md +++ b/DjangoAdmin_Django_EleVue/zh/volume2/url.md @@ -1,5 +1,9 @@ # URL 路由配置 +:::tip 概述 +URL 路由是模块开发的最后一步，本页讲解用 Django path() 将路径映射到视图类的配置方法。 +::: + URL 路由是模块开发的最后一步，负责将 URL 路径映射到视图类。项目使用 Django 的 `path()` 函数定义路由，通过 `include()` 将模块路由注册到主路由。 ## 文件位置 diff --git a/DjangoAdmin_Django_EleVue/zh/volume2/view.md b/DjangoAdmin_Django_EleVue/zh/volume2/view.md index 5e3bafc..be37d10 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume2/view.md +++ b/DjangoAdmin_Django_EleVue/zh/volume2/view.md @@ -1,5 +1,9 @@ # 视图层（View） +:::tip 概述 +视图层负责处理 HTTP 请求并调用 Service 业务逻辑，本页讲解 Django 类视图的编写方式与响应约定。 +::: + 视图层是模块开发的第四步，负责处理 HTTP 请求并调用 Service 层的业务逻辑。项目使用 Django 的类视图（Class-Based Views），每个视图类对应一个 API 端点。 ## 文件位置 diff --git a/DjangoAdmin_Django_EleVue/zh/volume3/base-classes.md b/DjangoAdmin_Django_EleVue/zh/volume3/base-classes.md index 27817b6..c20ff00 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume3/base-classes.md +++ b/DjangoAdmin_Django_EleVue/zh/volume3/base-classes.md @@ -1,5 +1,9 @@ # 第四章 架构设计 - 核心基类体系 +:::tip 概述 +本页汇总项目核心基类体系的总览与用法，编写业务代码前先了解可复用的基座能力。 +::: + ## 4.1 基类总览 核心基类体系由四大基类组成，覆盖从数据模型到请求校验再到响应输出的完整链路。子类只需声明差异点，即可获得标准化的增删改查能力。 diff --git a/DjangoAdmin_Django_EleVue/zh/volume3/cache.md b/DjangoAdmin_Django_EleVue/zh/volume3/cache.md index 1e20ea1..028649d 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume3/cache.md +++ b/DjangoAdmin_Django_EleVue/zh/volume3/cache.md @@ -1,5 +1,9 @@ # 第四章 架构设计 - 缓存架构 +:::tip 概述 +本页说明系统缓存架构的设计与使用方式，涉及缓存一致性或性能问题时查阅。 +::: + ## 4.1 缓存架构概述 项目使用 Redis 作为缓存后端，通过 Django 的缓存框架实现统一的缓存管理。缓存主要用于以下场景： diff --git a/DjangoAdmin_Django_EleVue/zh/volume3/database-design.md b/DjangoAdmin_Django_EleVue/zh/volume3/database-design.md index 9654a0c..5ed7a5e 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume3/database-design.md +++ b/DjangoAdmin_Django_EleVue/zh/volume3/database-design.md @@ -1,5 +1,9 @@ # 第四章 架构设计 - 数据库设计 +:::tip 概述 +本页说明数据库设计原则与表结构组织方式，建表或数据迁移时对照本页。 +::: + ## 4.1 数据库设计概述 项目使用 MySQL 8.0 作为主数据库，通过 Django ORM 进行数据访问。所有业务表继承 BaseModel 抽象基类，自动获得 6 个通用字段。 diff --git a/DjangoAdmin_Django_EleVue/zh/volume3/directory.md b/DjangoAdmin_Django_EleVue/zh/volume3/directory.md index e52a2a7..7b531f3 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume3/directory.md +++ b/DjangoAdmin_Django_EleVue/zh/volume3/directory.md @@ -1,5 +1,9 @@ # 第四章 架构设计 - 目录结构设计 +:::tip 概述 +本页说明项目根目录与各层目录的组织设计，二次开发定位文件时对照查阅。 +::: + ## 4.1 项目根目录 ``` diff --git a/DjangoAdmin_Django_EleVue/zh/volume3/extensibility.md b/DjangoAdmin_Django_EleVue/zh/volume3/extensibility.md index cf0da67..80d123b 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume3/extensibility.md +++ b/DjangoAdmin_Django_EleVue/zh/volume3/extensibility.md @@ -1,5 +1,9 @@ # 第四章 架构设计 - 扩展性设计 +:::tip 概述 +本页说明系统的扩展性设计原则，二次开发新增能力或改造现有模块时参考。 +::: + ## 4.1 扩展性设计原则 项目遵循开闭原则（OCP）：对扩展开放，对修改关闭。新功能通过添加新模块实现，而非修改现有代码。系统通过 Django App 机制、代码生成器、模板定制等方式提供扩展能力。 diff --git a/DjangoAdmin_Django_EleVue/zh/volume3/layer-arch.md b/DjangoAdmin_Django_EleVue/zh/volume3/layer-arch.md index cb1ae9b..3f5f2c6 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume3/layer-arch.md +++ b/DjangoAdmin_Django_EleVue/zh/volume3/layer-arch.md @@ -1,5 +1,9 @@ # 第四章 架构设计 - 分层架构详解 +:::tip 概述 +本页详解后端分层架构的职责划分与调用关系，编写代码前先理解各层边界。 +::: + ## 4.1 分层架构概述 项目采用经典的五层架构设计，各层职责明确，依赖关系清晰： diff --git a/DjangoAdmin_Django_EleVue/zh/volume3/overview.md b/DjangoAdmin_Django_EleVue/zh/volume3/overview.md index 03a0a15..e79519d 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume3/overview.md +++ b/DjangoAdmin_Django_EleVue/zh/volume3/overview.md @@ -1,5 +1,9 @@ # 第四章 架构设计 - 系统架构总览 +:::tip 概述 +本页给出系统整体架构总览，理解各层职责与模块关系时从本页开始。 +::: + ## 4.1 整体架构 项目采用前后端分离的 B/S 架构，后端基于 Django 6.0.3 提供 RESTful API，前端基于 Vue3 + ElementPlus 构建单页应用。系统通过 Nginx 反向代理统一入口，实现静态资源托管与 API 转发。 diff --git a/DjangoAdmin_Django_EleVue/zh/volume3/request-flow.md b/DjangoAdmin_Django_EleVue/zh/volume3/request-flow.md index b69d1e5..7887aae 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume3/request-flow.md +++ b/DjangoAdmin_Django_EleVue/zh/volume3/request-flow.md @@ -1,5 +1,9 @@ # 第四章 架构设计 - 请求处理流程 +:::tip 概述 +本页给出请求从进入路由到返回响应的全链路处理流程，排查接口问题时对照追踪。 +::: + ## 4.1 请求处理全链路 一个完整的 HTTP 请求在 系统中的处理流程如下： diff --git a/DjangoAdmin_Django_EleVue/zh/volume3/security.md b/DjangoAdmin_Django_EleVue/zh/volume3/security.md index cb653e1..d6c4dce 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume3/security.md +++ b/DjangoAdmin_Django_EleVue/zh/volume3/security.md @@ -1,5 +1,9 @@ # 第四章 架构设计 - 安全架构 +:::tip 概述 +本页说明系统安全架构设计，含认证、权限与数据安全等防护机制。 +::: + ## 4.1 安全架构概述 系统从认证、授权、防护三个维度构建安全体系： diff --git a/DjangoAdmin_Django_EleVue/zh/volume3/tech-stack.md b/DjangoAdmin_Django_EleVue/zh/volume3/tech-stack.md index c5811d1..c09fbda 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume3/tech-stack.md +++ b/DjangoAdmin_Django_EleVue/zh/volume3/tech-stack.md @@ -1,5 +1,9 @@ # 第四章 架构设计 - 技术栈选型 +:::tip 概述 +本页列出项目后端与前端完整技术选型及版本要求，评估兼容性或升级影响时对照本表。 +::: + ## 4.1 后端技术栈 ### Django 6.0.3 diff --git a/DjangoAdmin_Django_EleVue/zh/volume4/business/article.md b/DjangoAdmin_Django_EleVue/zh/volume4/business/article.md index a2811c7..0d28fd8 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume4/business/article.md +++ b/DjangoAdmin_Django_EleVue/zh/volume4/business/article.md @@ -1,3 +1,5 @@ +# 文章管理 + :::tip 文章管理 文章管理模块支持富文本编辑、分类关联、封面图片上传、图集管理等功能。适用于新闻、公告、帮助文档等内容管理场景。 ::: diff --git a/DjangoAdmin_Django_EleVue/zh/volume4/business/category.md b/DjangoAdmin_Django_EleVue/zh/volume4/business/category.md index 55a09d0..f737ac7 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume4/business/category.md +++ b/DjangoAdmin_Django_EleVue/zh/volume4/business/category.md @@ -1,3 +1,5 @@ +# 分类管理 + :::tip 分类管理 分类管理模块用于管理树形分类数据，如文章分类、产品分类等。通过 `parent_id` 字段实现无限级分类。 ::: diff --git a/DjangoAdmin_Django_EleVue/zh/volume4/business/city.md b/DjangoAdmin_Django_EleVue/zh/volume4/business/city.md index 78d90c4..e0f9673 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume4/business/city.md +++ b/DjangoAdmin_Django_EleVue/zh/volume4/business/city.md @@ -1,3 +1,5 @@ +# 行政区划管理 + :::tip 城市管理 城市管理模块用于管理行政区划数据，支持省/市/区/街道/社区五级行政区划。通过 `parent_code` 字段实现树形结构。 ::: diff --git a/DjangoAdmin_Django_EleVue/zh/volume4/business/content.md b/DjangoAdmin_Django_EleVue/zh/volume4/business/content.md index a54fed7..6eecbec 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume4/business/content.md +++ b/DjangoAdmin_Django_EleVue/zh/volume4/business/content.md @@ -1,3 +1,5 @@ +# 公告与链接管理 + :::tip 公告/链接 公告和链接是两个简单 CRUD 内容模块，提供标准的增删改查接口。适用于系统公告、友情链接等场景。 ::: diff --git a/DjangoAdmin_Django_EleVue/zh/volume4/business/dept.md b/DjangoAdmin_Django_EleVue/zh/volume4/business/dept.md index 124bad8..ad7295f 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume4/business/dept.md +++ b/DjangoAdmin_Django_EleVue/zh/volume4/business/dept.md @@ -1,3 +1,5 @@ +# 部门/职级/岗位管理 + :::tip 部门/职级/岗位 部门、职级、岗位是组织架构管理的三个核心模块。部门采用树形结构，职级和岗位为简单 CRUD 模块。用户表通过 `dept_id`、`position_id`、`level_id` 三个外键关联这三个模块。 ::: diff --git a/DjangoAdmin_Django_EleVue/zh/volume4/business/job.md b/DjangoAdmin_Django_EleVue/zh/volume4/business/job.md index 8dc8f7d..ff7ff1f 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume4/business/job.md +++ b/DjangoAdmin_Django_EleVue/zh/volume4/business/job.md @@ -1,3 +1,5 @@ +# 定时任务 + :::tip 定时任务 定时任务模块基于 APScheduler 实现，支持 Cron 表达式调度、任务执行日志、动态启停等功能。包含 job（任务定义）、job_log（执行日志）两个子模块。 ::: diff --git a/DjangoAdmin_Django_EleVue/zh/volume4/business/menu.md b/DjangoAdmin_Django_EleVue/zh/volume4/business/menu.md index 305f665..ee73679 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume4/business/menu.md +++ b/DjangoAdmin_Django_EleVue/zh/volume4/business/menu.md @@ -1,3 +1,5 @@ +# 菜单管理 + :::tip 菜单管理 菜单管理是 RBAC 权限系统的基础，负责管理系统的导航菜单和权限节点。支持目录/菜单（type=0）和权限按钮节点（type=1）两种类型，通过树形结构组织。 ::: diff --git a/DjangoAdmin_Django_EleVue/zh/volume4/business/param.md b/DjangoAdmin_Django_EleVue/zh/volume4/business/param.md index e5eeaf4..58b68c9 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume4/business/param.md +++ b/DjangoAdmin_Django_EleVue/zh/volume4/business/param.md @@ -1,3 +1,5 @@ +# 参数管理 + :::tip 参数管理 参数管理模块用于管理动态系统参数，支持按参数键查询、修改，无需重启服务即可生效。 ::: diff --git a/DjangoAdmin_Django_EleVue/zh/volume4/business/role.md b/DjangoAdmin_Django_EleVue/zh/volume4/business/role.md index 0f13489..7f566e2 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume4/business/role.md +++ b/DjangoAdmin_Django_EleVue/zh/volume4/business/role.md @@ -1,3 +1,5 @@ +# 角色管理 + :::tip 角色管理 角色是 RBAC 权限模型的核心，连接用户和菜单（权限）。通过为角色分配菜单权限，再将角色分配给用户，实现灵活的权限管理。 ::: diff --git a/DjangoAdmin_Django_EleVue/zh/volume4/business/user.md b/DjangoAdmin_Django_EleVue/zh/volume4/business/user.md index 52def72..0dae730 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume4/business/user.md +++ b/DjangoAdmin_Django_EleVue/zh/volume4/business/user.md @@ -1,3 +1,5 @@ +# 用户管理 + :::tip 用户管理 用户管理是系统的核心模块，属于复杂业务模块。包含用户 CRUD、角色关联、密码加密、行政区划等功能。与简单 CRUD 模块不同，用户管理使用自定义 service 函数。 ::: diff --git a/DjangoAdmin_Django_EleVue/zh/volume4/core/captcha.md b/DjangoAdmin_Django_EleVue/zh/volume4/core/captcha.md index ad81dfc..bc8ea2b 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume4/core/captcha.md +++ b/DjangoAdmin_Django_EleVue/zh/volume4/core/captcha.md @@ -1,3 +1,5 @@ +# 验证码机制 + :::tip 验证码 验证码是防止自动化攻击的重要安全手段。项目使用 django-simple-captcha 库生成图片验证码，存储在数据库中，支持多种验证码格式。源码位于 `application/login/views.py`。 ::: diff --git a/DjangoAdmin_Django_EleVue/zh/volume4/core/config.md b/DjangoAdmin_Django_EleVue/zh/volume4/core/config.md index bec42e6..525e6ea 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume4/core/config.md +++ b/DjangoAdmin_Django_EleVue/zh/volume4/core/config.md @@ -1,3 +1,5 @@ +# 系统配置管理 + :::tip 系统配置 系统配置模块用于管理动态的键值对配置项，与数据字典类似但更偏向系统级参数。支持分组管理，可通过接口动态修改，无需重启服务。模块位于 `application/config/`。 ::: diff --git a/DjangoAdmin_Django_EleVue/zh/volume4/core/cors.md b/DjangoAdmin_Django_EleVue/zh/volume4/core/cors.md index 99bb73d..25a90eb 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume4/core/cors.md +++ b/DjangoAdmin_Django_EleVue/zh/volume4/core/cors.md @@ -1,3 +1,5 @@ +# 跨域资源共享（CORS） + :::tip CORS跨域 CORS（Cross-Origin Resource Sharing）跨域资源共享是前后端分离架构必须处理的问题。项目使用 `django-cors-headers` 中间件处理跨域请求，通过 `.env` 配置允许的跨域源。 ::: diff --git a/DjangoAdmin_Django_EleVue/zh/volume4/core/demo-mode.md b/DjangoAdmin_Django_EleVue/zh/volume4/core/demo-mode.md index b3e6a46..5ebc90d 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume4/core/demo-mode.md +++ b/DjangoAdmin_Django_EleVue/zh/volume4/core/demo-mode.md @@ -1,3 +1,5 @@ +# 演示模式 + :::tip 演示模式 演示模式用于在线体验环境，开启后所有写操作（新增、编辑、删除等）将被拦截，返回"演示环境，暂无操作权限"提示。通过 `DJANGO_DEMO` 环境变量控制。 ::: diff --git a/DjangoAdmin_Django_EleVue/zh/volume4/core/dict.md b/DjangoAdmin_Django_EleVue/zh/volume4/core/dict.md index 40d4920..8fd705a 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume4/core/dict.md +++ b/DjangoAdmin_Django_EleVue/zh/volume4/core/dict.md @@ -1,3 +1,5 @@ +# 字典模块 + :::tip 数据字典 数据字典用于管理系统中的枚举值和配置项，如状态、类型、性别等。通过字典编码统一管理，前端可通过 `useDictStore` 获取字典选项，避免硬编码。模块位于 `application/dict/`。 ::: diff --git a/DjangoAdmin_Django_EleVue/zh/volume4/core/exception.md b/DjangoAdmin_Django_EleVue/zh/volume4/core/exception.md index 687a82e..a0e0a48 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume4/core/exception.md +++ b/DjangoAdmin_Django_EleVue/zh/volume4/core/exception.md @@ -1,3 +1,5 @@ +# 异常与响应处理 + :::tip 全局异常与响应 定义了统一的响应格式和全局异常处理机制。所有 API 返回 `{code, data, msg, ok}` 标准格式。响应函数位于 `utils/R.py`。 ::: diff --git a/DjangoAdmin_Django_EleVue/zh/volume4/core/idempotent.md b/DjangoAdmin_Django_EleVue/zh/volume4/core/idempotent.md index cff1655..0ce74fa 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume4/core/idempotent.md +++ b/DjangoAdmin_Django_EleVue/zh/volume4/core/idempotent.md @@ -1,3 +1,5 @@ +# 防重复提交 + :::tip 防重复提交 防重复提交是保障数据一致性的重要措施。通过前端防抖和后端唯一性校验双重保护，防止用户重复点击导致的数据重复提交。 ::: diff --git a/DjangoAdmin_Django_EleVue/zh/volume4/core/jwt.md b/DjangoAdmin_Django_EleVue/zh/volume4/core/jwt.md index 3ebe203..5374d5d 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume4/core/jwt.md +++ b/DjangoAdmin_Django_EleVue/zh/volume4/core/jwt.md @@ -1,3 +1,5 @@ +# 用户认证（JWT） + :::tip JWT认证 JWT（JSON Web Token）是系统的核心认证机制。用户登录成功后获取 Token，后续请求通过 `Authorization: Bearer <token>` 头携带 Token 进行身份验证。项目内置了 Token 生成、解析、刷新和黑名单管理功能，源码位于 `utils/jwt.py`。 ::: diff --git a/DjangoAdmin_Django_EleVue/zh/volume4/core/login-log.md b/DjangoAdmin_Django_EleVue/zh/volume4/core/login-log.md index c95dc0d..8320f45 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume4/core/login-log.md +++ b/DjangoAdmin_Django_EleVue/zh/volume4/core/login-log.md @@ -1,3 +1,5 @@ +# 登录日志 + :::tip 登录日志 登录日志记录每次登录尝试（成功/失败），包含登录账号、IP地址、浏览器信息、登录时间等。登录逻辑位于 `application/login/services.py`，日志记录位于 `application/login_log/` 模块。 ::: diff --git a/DjangoAdmin_Django_EleVue/zh/volume4/core/operation-log.md b/DjangoAdmin_Django_EleVue/zh/volume4/core/operation-log.md index 6cad27c..08ab4e9 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume4/core/operation-log.md +++ b/DjangoAdmin_Django_EleVue/zh/volume4/core/operation-log.md @@ -1,3 +1,5 @@ +# 操作日志 + :::tip 操作日志 操作日志通过 `@operation_log` 装饰器标记需要记录日志的视图方法，自动记录请求参数、响应结果、耗时、操作类型等信息。源码位于 `application/operation_log/decorators.py`。 ::: diff --git a/DjangoAdmin_Django_EleVue/zh/volume4/core/rate-limit.md b/DjangoAdmin_Django_EleVue/zh/volume4/core/rate-limit.md index d464610..7ace523 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume4/core/rate-limit.md +++ b/DjangoAdmin_Django_EleVue/zh/volume4/core/rate-limit.md @@ -1,3 +1,5 @@ +# 请求限流 + :::tip 请求限流 请求限流可通过中间件实现 IP 级别的限流，防止恶意请求和 DoS 攻击。项目中限流可通过 Nginx 反向代理或自定义中间件实现。 ::: diff --git a/DjangoAdmin_Django_EleVue/zh/volume4/core/rbac.md b/DjangoAdmin_Django_EleVue/zh/volume4/core/rbac.md index d086ec4..6fc2716 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume4/core/rbac.md +++ b/DjangoAdmin_Django_EleVue/zh/volume4/core/rbac.md @@ -1,3 +1,5 @@ +# 权限管理（RBAC） + :::tip RBAC权限 采用基于角色的访问控制（RBAC）模型，通过用户-角色-菜单三层关系实现细粒度的权限管理。权限控制贯穿前后端：后端通过 `PermissionRequired` 混入类校验（`middleware/permission_middleware.py`），前端通过 `v-perm` 指令控制按钮显隐。 ::: diff --git a/DjangoAdmin_Django_EleVue/zh/volume4/core/validator.md b/DjangoAdmin_Django_EleVue/zh/volume4/core/validator.md index 5d679b6..7630021 100644 --- a/DjangoAdmin_Django_EleVue/zh/volume4/core/validator.md +++ b/DjangoAdmin_Django_EleVue/zh/volume4/core/validator.md @@ -1,3 +1,5 @@ +# 参数验证（Form） + :::tip 参数验证 使用 Django ModelForm 进行请求参数验证。所有请求体参数通过 Django Form 定义，视图中调用 `form.is_valid()` 自动验证，验证失败通过 `regular.get_err()` 提取错误信息返回前端。 ::: diff --git a/DjangoAdmin_Django_EleVue/zh/why.md b/DjangoAdmin_Django_EleVue/zh/why.md index d1dae2b..0f1fb85 100644 --- a/DjangoAdmin_Django_EleVue/zh/why.md +++ b/DjangoAdmin_Django_EleVue/zh/why.md @@ -1,5 +1,9 @@ # 为什么选择我们 +:::tip 概述 +本页从低代码生成能力、功能开箱即用与工程可持续性三个维度说明选择本项目的理由，技术选型对比时可作为评估依据。 +::: + ## 低代码生成，开发效率倍增 项目最大的特点是代码生成器。只需在数据库中建好表，一条命令即可生成完整的前后端 CRUD 模块： diff --git a/DjangoAdmin_Django_NaiveVue/.vitepress/config/en.ts b/DjangoAdmin_Django_NaiveVue/.vitepress/config/en.ts index a1a96ef..c5e4785 100644 --- a/DjangoAdmin_Django_NaiveVue/.vitepress/config/en.ts +++ b/DjangoAdmin_Django_NaiveVue/.vitepress/config/en.ts @@ -29,7 +29,7 @@ // // themeConfig: { // editLink: { -// pattern: "https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_EleVue", +// pattern: "https://gitee.com/djangoadmin/DjangoAdmin_Django_NaiveVue", // text: "Suggest changes to this page", // }, // diff --git a/DjangoAdmin_Django_NaiveVue/.vitepress/config/extract.d.mts b/DjangoAdmin_Django_NaiveVue/.vitepress/config/extract.d.mts new file mode 100644 index 0000000..2a46233 --- /dev/null +++ b/DjangoAdmin_Django_NaiveVue/.vitepress/config/extract.d.mts @@ -0,0 +1,5 @@ +export declare const SITE_URL: string; +export declare const SITE_DESCRIPTION: string; +export declare function stripNumberPrefix(title: string): string; +export declare function extractDescription(md: string): string; +export declare function extractFaqs(md: string): { q: string; a: string }[]; diff --git a/DjangoAdmin_Django_NaiveVue/.vitepress/config/extract.mjs b/DjangoAdmin_Django_NaiveVue/.vitepress/config/extract.mjs new file mode 100644 index 0000000..0e7ed86 --- /dev/null +++ b/DjangoAdmin_Django_NaiveVue/.vitepress/config/extract.mjs @@ -0,0 +1,130 @@ +/** + * SEO/GEO 共享工具（纯 ESM，零依赖）。 + * + * 同时被两类调用方 import： + * 1. VitePress 配置（.ts，esbuild 打包时内联本文件） + * 2. scripts/generate-llms-txt.mjs（Node 直接运行） + * + * 注意：SITE_URL 是全站唯一 URL 真相源。 + * docs 子域当前 TLS 证书为腾讯 CDN 默认证书（*.cdn.myqcloud.com，校验失败）， + * 故暂用 http；证书修复后只需改这里一处。 + */ + +export const SITE_URL = "http://docs.django.naivevue.djangoadmin.cn"; + +export const SITE_DESCRIPTION = + "DjangoAdmin 企业级中台解决方案 - Django + NaiveUI 前后端分离版本"; + +/** + * 剥离 H1/标题中的章节编号前缀，用于 <title> 与 JSON-LD headline。 + * 例："5.10 字典模块" → "字典模块"；"K. 贡献指南" → "贡献指南"。 + * 页内 H1 与侧边栏编号保持不变，仅影响 SEO 输出。 + */ +export function stripNumberPrefix(title) { + return String(title) + .replace(/^(?:\d+(?:\.\d+)+|[A-Z]\.)\s+/, "") + .trim(); +} + +/** + * 从页面 Markdown 提取 meta description： + * 1. 首选 `:::tip xxx` 容器内的首句（141/143 页的标准 opener） + * 2. 回退到 H1 后的第一个普通段落 + * 输出压缩为单行、去除行内 Markdown，按中文句末标点截断（≤100 字符）。 + */ +export function extractDescription(md) { + const src = String(md); + const fm = src.match(/^---\r?\n([\s\S]*?)\r?\n---/); + const body = fm ? src.slice(fm[0].length) : src; + + let text = ""; + // frontmatter description 显式声明优先（无 H1 页面的补齐手段） + const fmDesc = fm && fm[1].match(/^description:\s*(.+)$/m); + if (fmDesc) { + text = fmDesc[1].trim().replace(/^["']|["']$/g, ""); + } + const tip = !text && body.match(/^:::\s*tip[^\n]*\n([\s\S]*?)\n:::/m); + if (tip) { + text = tip[1]; + } + if (!text) { + const afterH1 = body.match(/^# (?!#)(.+)$/m); + if (afterH1) { + const rest = body.slice((afterH1.index ?? 0) + afterH1[0].length); + const para = rest + .split(/\n{2,}/) + .find( + (p) => + p.trim() && + !/^\s*#/.test(p) && + !/^\s*:::/.test(p) && + !/^\s*```/.test(p) && + !/^\s*\|/.test(p), + ); + text = para || ""; + } + } + + text = text + .replace(/\s+/g, " ") + .replace(/`([^`]+)`/g, "$1") + .replace(/\*\*([^*]+)\*\*/g, "$1") + .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") + .trim(); + + if (!text) return ""; + + // 按中文句末标点截取首句，上限 100 字符；截断时避免切碎词 + const m = text.match(/^.{1,100}?(?:[。！？!?]|$)/); + let out = m ? m[0] : text.slice(0, 100); + if (out.length < text.length && !/[。！？!?]$/.test(out)) { + out = out.replace(/[^\s，、；：,;:]+$/, ""); + } + return out.trim() || text.slice(0, 100); +} + +function cleanText(s) { + return s + .replace(/^:::[^\n]*$/gm, "") + .replace(/^```[^\n]*$/gm, "") + .replace(/`([^`]+)`/g, "$1") + .replace(/\*\*([^*]+)\*\*/g, "$1") + .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") + .replace(/\s+/g, " ") + .trim(); +} + +/** + * 提取页面中的 Q/A 对（用于 FAQPage JSON-LD），支持两种站内格式： + * A. `### Q：问题` 标题式（如 zh/quickstart/faq.md） + * B. `**Q：问题**` 加粗式（如 zh/appendix/faq.md） + * 返回 [{ q, a }]；无匹配返回 []。 + */ +export function extractFaqs(md) { + const body = String(md).replace(/^---[\s\S]*?\n---\s*/, ""); + let faqs = []; + + // 格式 A：按 `### Q：` 切块，答案截断到下一个标题 + for (const part of body.split(/(?=^###\s*Q[：:])/m)) { + const m = part.match(/^###\s*Q[：:]\s*([^\n]+)\n+([\s\S]*)/); + if (!m) continue; + let a = m[2]; + const cut = a.search(/^#{1,4}\s/m); + if (cut >= 0) a = a.slice(0, cut); + faqs.push({ q: cleanText(m[1]), a: cleanText(a) }); + } + + // 格式 B：按 `**Q：` 切块 + if (!faqs.length) { + for (const part of body.split(/(?=^\*\*Q[：:])/m)) { + const m = part.match(/^\*\*Q[：:]\s*([^*]+)\*\*\s*\n+([\s\S]*)/); + if (!m) continue; + let a = m[2]; + const cut = a.search(/^(?:#{1,4}\s|\*\*Q)/m); + if (cut >= 0) a = a.slice(0, cut); + faqs.push({ q: cleanText(m[1]), a: cleanText(a) }); + } + } + + return faqs.filter((f) => f.q && f.a); +} diff --git a/DjangoAdmin_Django_NaiveVue/.vitepress/config/index.ts b/DjangoAdmin_Django_NaiveVue/.vitepress/config/index.ts index 2294856..6627a76 100644 --- a/DjangoAdmin_Django_NaiveVue/.vitepress/config/index.ts +++ b/DjangoAdmin_Django_NaiveVue/.vitepress/config/index.ts @@ -1,14 +1,22 @@ import { defineConfig } from "vitepress"; import { enConfig } from "./en"; +import { createSeoHooks } from "./seo"; import { sharedConfig } from "./shared"; import { zhConfig } from "./zh"; +const seo = createSeoHooks(zhConfig.themeConfig?.sidebar); + export default defineConfig({ ...sharedConfig, ignoreDeadLinks: [ (link) => link.includes('localhost'), ], + // SEO：页面级 title/description、canonical/OG/JSON-LD、sitemap+lastmod + transformPageData: seo.transformPageData, + transformHead: seo.transformHead, + sitemap: seo.sitemap, + locales: { root: { label: "简体中文", lang: "zh-CN", link: "/", ...zhConfig }, // root: { label: "English", lang: "en-US", link: "/", ...enConfig }, diff --git a/DjangoAdmin_Django_NaiveVue/.vitepress/config/seo.ts b/DjangoAdmin_Django_NaiveVue/.vitepress/config/seo.ts new file mode 100644 index 0000000..a018197 --- /dev/null +++ b/DjangoAdmin_Django_NaiveVue/.vitepress/config/seo.ts @@ -0,0 +1,311 @@ +/** + * SEO/GEO 构建期钩子（仅 Node 构建时运行，不进客户端 bundle）： + * - transformPageData：每页独立 title（去编号前缀）与 description（取 :::tip 首句） + * - transformHead：canonical / Open Graph / twitter 卡片 / JSON-LD 结构化数据 + * - sitemap.transformItems：注入 lastmod（git 最后提交时间）并过滤 404 + * + * 由 config/index.ts 通过 createSeoHooks(zhConfig.themeConfig?.sidebar) 挂载。 + * 依赖 extract.mjs（纯 ESM，同被 scripts/generate-llms-txt.mjs 复用）。 + */ +import fs from "node:fs"; +import path from "node:path"; +import { execSync } from "node:child_process"; +import { + SITE_URL, + extractDescription, + extractFaqs, + stripNumberPrefix, +} from "./extract.mjs"; + +/** 与 vitepress HeadConfig 同构：[tag, attrs, innerHTML?] */ +type HeadTuple = [string, Record<string, any>, string?]; + +interface SideItem { + text?: string; + link?: string; + items?: SideItem[]; +} + +interface PageDataLike { + relativePath?: string; + title?: string; + description?: string; + frontmatter?: Record<string, any>; + [k: string]: any; +} + +interface TransformCtx { + pageData?: PageDataLike; + title?: string; + description?: string; + content?: string; + siteConfig?: { root?: string; srcDir?: string }; +} + +const ORG = { + "@type": "Organization", + name: "DjangoAdmin", + url: "https://www.djangoadmin.cn", + logo: `${SITE_URL}/logo.png`, + sameAs: [ + "https://gitee.com/djangoadmin/DjangoAdmin_Django_NaiveVue", + "https://www.djangoadmin.cn", + ], +}; + +/** 相对路径 → 站内路由（cleanUrls 关闭，正文页带 .html） */ +function routeOf(relativePath: string): string { + if (relativePath === "index.md") return "/"; + if (relativePath === "404.md") return "/404.html"; + return `/${relativePath.replace(/\.md$/, ".html")}`; +} + +/** 去掉侧边栏文案前导 emoji/符号，保留 "1.1 项目介绍" 这类编号文字 */ +function cleanLabel(s?: string): string { + return (s || "").replace(/^[^\p{L}\p{N}]+/u, "").trim(); +} + +/** 从侧边栏构建 route → 面包屑文案链（含分组小节） */ +function buildCrumbMap(sidebar: unknown): Map<string, string[]> { + const map = new Map<string, string[]>(); + const groups: SideItem[] = Array.isArray(sidebar) + ? sidebar + : ((sidebar as Record<string, SideItem[]>)?.["/zh/"] ?? []); + const walk = (items: SideItem[], trail: string[]) => { + for (const item of items) { + if (item.link && item.link.startsWith("/")) { + map.set(item.link, [...trail, cleanLabel(item.text)]); + } else if (item.items?.length) { + walk(item.items, [...trail, cleanLabel(item.text)]); + } + } + }; + for (const group of groups) { + walk(group.items ?? [], [cleanLabel(group.text)].filter(Boolean)); + } + return map; +} + +/** 从渲染后的 HTML 提取 H1 纯文本（JSON-LD headline 须与页面 H1 一致） */ +function h1OfHtml(html?: string): string { + const m = (html || "").match(/<h1[^>]*>([\s\S]*?)<\/h1>/i); + if (!m) return ""; + return m[1] + .replace(/<[^>]+>/g, "") + .replace(/&/g, "&") + .replace(/</g, "<") + .replace(/>/g, ">") + .replace(/"/g, '"') + .replace(/'/g, "'") + .trim(); +} + +/** 从 Markdown 源提取 H1 纯文本（去除行内 markdown 标记） */ +function h1OfMd(md: string): string { + // 围栏感知：跳过 ``` 代码块内的 # 注释，取真正的页面 H1 + let inFence = false; + for (const line of md.split("\n")) { + if (line.startsWith("```")) { inFence = !inFence; continue; } + if (!inFence && /^# (?!#)/.test(line)) { + return line + .replace(/^# /, "") + .replace(/`([^`]+)`/g, "$1") + .replace(/\*\*([^*]+)\*\*/g, "$1") + .trim(); + } + } + return ""; +} + +export function createSeoHooks(sidebar: unknown) { + const crumbs = buildCrumbMap(sidebar); + const projectDirs: string[] = []; + let gitDates: Map<string, string> | null = null; + + const readMd = (relativePath: string, srcDir?: string): string => { + try { + return fs.readFileSync( + path.resolve(srcDir || process.cwd(), relativePath), + "utf8", + ); + } catch { + return ""; + } + }; + + /** + * 项目内每个文件最后一次 git 提交的 ISO 时间。 + * 单次 git log 调用构建全量映射（key = 相对路径，与 pageData.relativePath 一致）； + * git 不可用时静默降级（sitemap 无 lastmod、JSON-LD 无 dateModified）。 + */ + const getGitDates = (root: string): Map<string, string> => { + if (gitDates) return gitDates; + gitDates = new Map<string, string>(); + try { + const out = execSync( + "git log --format=:::%cI --name-only --relative -n 500 -- .", + { + cwd: root, + encoding: "utf8", + maxBuffer: 64 * 1024 * 1024, + stdio: ["ignore", "pipe", "ignore"], + }, + ); + let current = ""; + for (const line of out.split(/\r?\n/)) { + if (line.startsWith(":::")) { + current = line.slice(3).trim(); + continue; + } + const file = line.trim(); + if (file && current && !gitDates.has(file)) { + gitDates.set(file, current); + } + } + } catch { + // 降级：无 lastmod / dateModified + } + return gitDates; + }; + + /** 每页独立 title（去 "5.10 " 编号前缀，关键词前置）与 description（:::tip 首句） */ + function transformPageData(pageData: PageDataLike, ctx?: any): Record<string, unknown> { + const srcDir: string | undefined = ctx?.siteConfig?.srcDir; + const root: string | undefined = ctx?.siteConfig?.root; + if (root && !projectDirs.includes(root)) projectDirs.push(root); + + const out: Record<string, unknown> = {}; + const rel = pageData.relativePath; + if (rel && !pageData.frontmatter?.description) { + const desc = extractDescription(readMd(rel, srcDir)); + if (desc) out.description = desc; + } + if (pageData.title) { + out.title = stripNumberPrefix(pageData.title); + } + return out; + } + + /** 构建期注入 canonical / OG / twitter / JSON-LD */ + function transformHead(ctx: TransformCtx): HeadTuple[] { + const rel = ctx?.pageData?.relativePath || ""; + if (!rel || rel === "404.md") return []; + + const route = routeOf(rel); + const url = `${SITE_URL}${route}`; + const title = ctx.pageData?.title || ctx.title || ""; + const desc = ctx.description || ""; + const isHome = rel === "index.md"; + const image = `${SITE_URL}/logo.png`; + + const heads: HeadTuple[] = [ + ["link", { rel: "canonical", href: url }], + ["meta", { property: "og:type", content: isHome ? "website" : "article" }], + ["meta", { property: "og:site_name", content: "DjangoAdmin" }], + ["meta", { property: "og:locale", content: "zh_CN" }], + ["meta", { property: "og:title", content: title }], + ["meta", { property: "og:description", content: desc }], + ["meta", { property: "og:url", content: url }], + ["meta", { property: "og:image", content: image }], + ["meta", { property: "twitter:title", content: title }], + ["meta", { property: "twitter:description", content: desc }], + ["meta", { property: "twitter:url", content: url }], + ["meta", { property: "twitter:image", content: image }], + ]; + + // ---- JSON-LD ---- + const root = ctx.siteConfig?.root || projectDirs[0] || process.cwd(); + const srcDir = ctx.siteConfig?.srcDir || root; + const lastMod = getGitDates(root).get(rel); + const blocks: Record<string, any>[] = []; + + if (isHome) { + blocks.push({ + "@context": "https://schema.org", + "@type": "WebSite", + name: "DjangoAdmin 开发文档", + url: `${SITE_URL}/`, + inLanguage: "zh-CN", + description: desc, + }); + blocks.push({ "@context": "https://schema.org", ...ORG }); + } else { + const md = readMd(rel, srcDir); + const article: Record<string, any> = { + "@context": "https://schema.org", + "@type": "TechArticle", + headline: h1OfMd(md) || h1OfHtml(ctx.content) || title, + description: desc, + url, + inLanguage: "zh-CN", + mainEntityOfPage: { "@type": "WebPage", "@id": url }, + publisher: ORG, + }; + if (lastMod) article.dateModified = lastMod; + blocks.push(article); + + const trail = crumbs.get(route); + if (trail?.length) { + const items: Record<string, any>[] = [ + { "@type": "ListItem", position: 1, name: "首页", item: `${SITE_URL}/` }, + ]; + trail.forEach((name, i) => { + const node: Record<string, any> = { + "@type": "ListItem", + position: i + 2, + name, + }; + if (i === trail.length - 1) node.item = url; + items.push(node); + }); + blocks.push({ + "@context": "https://schema.org", + "@type": "BreadcrumbList", + itemListElement: items, + }); + } + + const faqs = extractFaqs(md); + if (faqs.length) { + blocks.push({ + "@context": "https://schema.org", + "@type": "FAQPage", + mainEntity: faqs.map((f) => ({ + "@type": "Question", + name: f.q, + acceptedAnswer: { "@type": "Answer", text: f.a }, + })), + }); + } + } + + // 转义 "<"，防止内容中出现 </script> 破坏注入 + const json = JSON.stringify(blocks).replace(/</g, "\\u003c"); + heads.push(["script", { type: "application/ld+json" }, json]); + return heads; + } + + /** sitemap.xml：过滤 404/README，注入 git lastmod */ + const sitemap = { + hostname: SITE_URL, + transformItems(items: { url: string; lastmod?: string }[]) { + const root = projectDirs[0] || process.cwd(); + const dates = getGitDates(root); + const out: { url: string; lastmod?: string }[] = []; + for (const item of items) { + // ⚠ vitepress 传入的 item.url 是相对路径（"404.html"、"zh/x.html"、""）， + // 无前导斜杠也无域名——hostname 由 SitemapStream 事后拼接。 + if (/(^|\/)404\.html$/.test(item.url)) continue; // 404 页不收录 + if (/(^|\/)README\.html$/.test(item.url)) continue; // 仓库 README 非文档页 + const p = item.url.replace(/^\//, ""); + const rel = + p === "" || p === "index.html" ? "index.md" : p.replace(/\.html$/, ".md"); + const lastmod = dates.get(rel); + out.push(lastmod ? { ...item, lastmod } : item); + } + return out; + }, + }; + + return { transformPageData, transformHead, sitemap }; +} diff --git a/DjangoAdmin_Django_NaiveVue/.vitepress/config/shared.ts b/DjangoAdmin_Django_NaiveVue/.vitepress/config/shared.ts index 78988d5..a446021 100644 --- a/DjangoAdmin_Django_NaiveVue/.vitepress/config/shared.ts +++ b/DjangoAdmin_Django_NaiveVue/.vitepress/config/shared.ts @@ -1,6 +1,6 @@ import { defineConfig, HeadConfig } from "vitepress"; -export const META_IMAGE = "/social.png"; +export const META_IMAGE = "/logo.png"; const rControl = /[\u0000-\u001f]/g; const rSpecial = /[\s~`!@#$%^&*()\-_+=[\]{}|\\;:"'“”‘’<>,.?/]+/g; @@ -23,6 +23,8 @@ export const slugify = (str: string): string => export const sharedConfig = defineConfig({ title: "小蚂蚁云", + // 页面 <title> 后缀：「环境准备 | DjangoAdmin 开发文档」（index.md frontmatter 可覆盖） + titleTemplate: "DjangoAdmin 开发文档", appearance: "light", markdown: { diff --git a/DjangoAdmin_Django_NaiveVue/.vitepress/config/zh.ts b/DjangoAdmin_Django_NaiveVue/.vitepress/config/zh.ts index bd23e4c..47b0608 100644 --- a/DjangoAdmin_Django_NaiveVue/.vitepress/config/zh.ts +++ b/DjangoAdmin_Django_NaiveVue/.vitepress/config/zh.ts @@ -1,6 +1,6 @@ import type { DefaultTheme, LocaleSpecificConfig } from "vitepress"; -export const META_URL = "https://www.djangoadmin.cn"; +export const META_URL = "http://docs.django.naivevue.djangoadmin.cn"; export const META_TITLE = "DjangoAdmin 企业级中台解决方案"; export const META_DESCRIPTION = "DjangoAdmin 企业级中台解决方案 - Django + NaiveUI 前后端分离版本"; diff --git a/DjangoAdmin_Django_NaiveVue/404.md b/DjangoAdmin_Django_NaiveVue/404.md new file mode 100644 index 0000000..c344b20 --- /dev/null +++ b/DjangoAdmin_Django_NaiveVue/404.md @@ -0,0 +1,12 @@ +--- +head: + - - meta + - name: robots + content: noindex +--- + +# 页面不存在 + +抱歉，您访问的页面不存在或已被移动。 + +[返回首页](/) · [浏览文档](/zh/introduction) diff --git a/DjangoAdmin_Django_NaiveVue/package.json b/DjangoAdmin_Django_NaiveVue/package.json index 77bd941..b5517ed 100644 --- a/DjangoAdmin_Django_NaiveVue/package.json +++ b/DjangoAdmin_Django_NaiveVue/package.json @@ -5,7 +5,8 @@ "type": "module", "scripts": { "docs": "vitepress dev .", - "docs:build": "vitepress build .", + "docs:llms": "node scripts/generate-llms-txt.mjs", + "docs:build": "node scripts/generate-llms-txt.mjs && vitepress build .", "docs:preview": "vitepress preview ." }, "dependencies": { diff --git a/DjangoAdmin_Django_NaiveVue/public/llms.txt b/DjangoAdmin_Django_NaiveVue/public/llms.txt new file mode 100644 index 0000000..030efa5 --- /dev/null +++ b/DjangoAdmin_Django_NaiveVue/public/llms.txt @@ -0,0 +1,165 @@ +# DjangoAdmin Django+NaiveUI 开发文档 + +> DjangoAdmin 企业级中台解决方案 - Django + NaiveUI 前后端分离版本。内置 RBAC 权限体系、代码生成器等开箱即用功能，支持五种数据库一键切换。本文档共 135 篇，按章节组织。 + +## 1. 了解项目 + +- [1.1 项目介绍](http://docs.django.naivevue.djangoadmin.cn/zh/introduction.html): DjangoAdmin 是企业级中台解决方案，后端基于 Django + Django ORM，前端基于 Vue3 + NaiveUI，内置 RBAC 权限、代码生成器等开箱即用功能， +- [更新日志](http://docs.django.naivevue.djangoadmin.cn/zh/changelog.html): 更新日志是项目演进的完整记录，帮助开发者和企业了解每个版本的能力变化与技术演进方向。 +- [新手入门指南](http://docs.django.naivevue.djangoadmin.cn/zh/course.html): 详细的安装步骤请参考 环境准备 章节。 +- [项目目录结构](http://docs.django.naivevue.djangoadmin.cn/zh/struct.html): 本页说明项目前后端目录组织与各目录职责，二次开发定位文件或了解工程结构时对照查阅。 +- [为什么选择我们](http://docs.django.naivevue.djangoadmin.cn/zh/why.html): 本页从低代码生成能力、功能开箱即用与工程可持续性三个维度说明选择本项目的理由，技术选型对比时可作为评估依据。 + +## 2. 快速入门 + +- [后端启动](http://docs.django.naivevue.djangoadmin.cn/zh/volume1/backend.html): 启动后端前，请确保已完成 环境准备 章节中的所有软件安装。 +- [数据库初始化](http://docs.django.naivevue.djangoadmin.cn/zh/volume1/database.html): 数据库初始化前，请确保已完成以下准备工作： 1. 目标数据库服务已启动（如 MySQL 8.0+） 2. .env 文件中的 DATABASE_ENGINE 和数据库连接信息已正确配置 3. +- [Docker 一键启动](http://docs.django.naivevue.djangoadmin.cn/zh/volume1/docker.html): 使用 Docker 方式启动前，请确保已安装以下软件： 1. Docker Desktop（Windows / macOS）或 Docker Engine（Linux） 2. Docker +- [环境变量速查表](http://docs.django.naivevue.djangoadmin.cn/zh/volume1/env-vars.html): 1. .env 文件包含项目的敏感配置信息，已被 .gitignore 忽略，不会提交到版本控制。 +- [环境准备](http://docs.django.naivevue.djangoadmin.cn/zh/volume1/environment.html): 1. 部分软件安装后需要设置本地环境变量，便于在终端中使用命令。 +- [常见问题FAQ](http://docs.django.naivevue.djangoadmin.cn/zh/volume1/faq.html): 遇到问题时，建议先查看终端日志输出和浏览器控制台（F12）的错误信息，通常能快速定位问题原因。 +- [第一个接口调试](http://docs.django.naivevue.djangoadmin.cn/zh/volume1/first-api.html): 开始调试前，请确保已完成以下步骤： 1. 后端服务已启动（参见 后端启动） 2. 数据库已初始化（参见 数据库初始化） 3. Redis 服务已启动 +- [前端启动](http://docs.django.naivevue.djangoadmin.cn/zh/volume1/frontend.html): 启动前端前，请确保已完成 环境准备 章节中的 Node.js 和 pnpm 安装，并已启动后端服务（参见 后端启动）。 + +## 3. 模块开发实战 + +- [完整代码清单](http://docs.django.naivevue.djangoadmin.cn/zh/volume2/code-list.html): 本页汇总案例管理（Example）模块涉及的全部文件代码，开发时可快速查阅与复制对照。 +- [常见问题与排错](http://docs.django.naivevue.djangoadmin.cn/zh/volume2/faq.html): 本页汇总模块开发过程中的常见问题与排错方法，开发受阻时按症状索引即可定位。 +- [前端 API 层](http://docs.django.naivevue.djangoadmin.cn/zh/volume2/fe-api.html): 前端 API 层封装后端接口的 HTTP 请求，每个业务模块对应一个 API 文件，本页讲解基于 Axios 封装的编写规范。 +- [前端路由与菜单](http://docs.django.naivevue.djangoadmin.cn/zh/volume2/fe-router.html): 本页讲解前端路由与菜单机制——路由和菜单由后端动态返回，前端只需注册路由组件映射。 +- [前端页面视图](http://docs.django.naivevue.djangoadmin.cn/zh/volume2/fe-view.html): 前端页面视图是用户直接交互的界面，本页讲解 Vue3 + NaiveUI 下一个完整 CRUD 页面的文件组成与编写方式。 +- [表单验证（Form）](http://docs.django.naivevue.djangoadmin.cn/zh/volume2/form.html): 表单验证是模块开发的第二步，讲解基于 Django ModelForm 的提交数据校验与错误信息约定。 +- [数据模型（Model）](http://docs.django.naivevue.djangoadmin.cn/zh/volume2/model.html): 数据模型是模块开发的第一步，讲解如何用 Django ORM 与 BaseModel 定义数据库表结构，新建模块时从本页开始。 +- [模块开发实战概述](http://docs.django.naivevue.djangoadmin.cn/zh/volume2/overview.html): 本章以案例管理（Example）模块为完整案例，手把手演示从零开发一个业务模块的全流程，学完即可掌握项目中任意模块的开发方式。 +- [权限节点配置](http://docs.django.naivevue.djangoadmin.cn/zh/volume2/permission.html): 本页讲解接口权限字符串的定义与菜单权限节点的配置方法，联调 403 问题时对照本页。 +- [业务逻辑层（Service）](http://docs.django.naivevue.djangoadmin.cn/zh/volume2/service.html): 业务逻辑层是模块开发的核心，CRUD 操作、业务规则与数据处理均封装在 Service 层函数，本页讲解其编写规范。 +- [URL 路由配置](http://docs.django.naivevue.djangoadmin.cn/zh/volume2/url.html): URL 路由是模块开发的最后一步，本页讲解用 Django path() 将路径映射到视图类的配置方法。 +- [视图层（View）](http://docs.django.naivevue.djangoadmin.cn/zh/volume2/view.html): 视图层负责处理 HTTP 请求并调用 Service 业务逻辑，本页讲解 Django 类视图的编写方式与响应约定。 + +## 4. 架构设计 + +- [第四章 架构设计 - 核心基类体系](http://docs.django.naivevue.djangoadmin.cn/zh/volume3/base-classes.html): 本页汇总项目核心基类体系的总览与用法，编写业务代码前先了解可复用的基座能力。 +- [第四章 架构设计 - 缓存架构](http://docs.django.naivevue.djangoadmin.cn/zh/volume3/cache.html): 本页说明系统缓存架构的设计与使用方式，涉及缓存一致性或性能问题时查阅。 +- [数据库设计指南](http://docs.django.naivevue.djangoadmin.cn/zh/volume3/database-design-guide.html): 本文介绍本项目的数据库设计规范，包括表命名、字段类型选择、索引策略、常见表模式等。 +- [第四章 架构设计 - 数据库设计](http://docs.django.naivevue.djangoadmin.cn/zh/volume3/database-design.html): 本页说明数据库设计原则与表结构组织方式，建表或数据迁移时对照本页。 +- [第四章 架构设计 - 目录结构设计](http://docs.django.naivevue.djangoadmin.cn/zh/volume3/directory.html): 本页说明项目根目录与各层目录的组织设计，二次开发定位文件时对照查阅。 +- [第四章 架构设计 - 扩展性设计](http://docs.django.naivevue.djangoadmin.cn/zh/volume3/extensibility.html): 本页说明系统的扩展性设计原则，二次开发新增能力或改造现有模块时参考。 +- [第四章 架构设计 - 分层架构详解](http://docs.django.naivevue.djangoadmin.cn/zh/volume3/layer-arch.html): 本页详解后端分层架构的职责划分与调用关系，编写代码前先理解各层边界。 +- [第四章 架构设计 - 系统架构总览](http://docs.django.naivevue.djangoadmin.cn/zh/volume3/overview.html): 本页给出系统整体架构总览，理解各层职责与模块关系时从本页开始。 +- [性能优化指南](http://docs.django.naivevue.djangoadmin.cn/zh/volume3/performance.html): 本文介绍本项目中常见的性能优化策略，涵盖后端 ORM 查询、缓存、分页、前端加载等方面。 +- [第四章 架构设计 - 请求处理流程](http://docs.django.naivevue.djangoadmin.cn/zh/volume3/request-flow.html): 本页给出请求从进入路由到返回响应的全链路处理流程，排查接口问题时对照追踪。 +- [第四章 架构设计 - 安全架构](http://docs.django.naivevue.djangoadmin.cn/zh/volume3/security.html): 本页说明系统安全架构设计，含认证、权限与数据安全等防护机制。 +- [第四章 架构设计 - 技术栈选型](http://docs.django.naivevue.djangoadmin.cn/zh/volume3/tech-stack.html): 本页列出项目后端与前端完整技术选型及版本要求，评估兼容性或升级影响时对照本表。 + +## 5. 开发指南 + +- [API 接口速查表](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/api-cheatsheet.html): API 接口速查表，按模块分组列出所有 RESTful 接口的请求方法、路径、说明和权限标识。 +- [文章管理](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/business/article.html): 文章管理模块支持富文本编辑、分类关联、封面图片上传、图集管理等功能。 +- [分类管理](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/business/category.html): 分类管理模块用于管理树形分类数据，如文章分类、产品分类等。 +- [行政区划管理](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/business/city.html): 城市管理模块用于管理行政区划数据，支持省/市/区/街道/社区五级行政区划。 +- [公告与链接管理](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/business/content.html): 公告和链接是两个简单 CRUD 内容模块，提供标准的增删改查接口。 +- [部门/职级/岗位管理](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/business/dept.html): 部门、职级、岗位是组织架构管理的三个核心模块。 +- [定时任务](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/business/job.html): 定时任务模块基于 APScheduler 实现，支持 Cron 表达式调度、任务执行日志、动态启停等功能。 +- [菜单管理](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/business/menu.html): 菜单管理是 RBAC 权限系统的基础，负责管理系统的导航菜单和权限节点。 +- [参数管理](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/business/param.html): 参数管理模块用于管理动态系统参数，支持按参数键查询、修改，无需重启服务即可生效。 +- [角色管理](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/business/role.html): 角色是 RBAC 权限模型的核心，连接用户和菜单（权限）。 +- [用户管理](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/business/user.html): 用户管理是系统的核心模块，属于复杂业务模块。 +- [认证流程实战](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/core/auth-flow.html): 登录 -> Token 获取 -> 权限校验 -> Token 刷新 -> 退出登录的完整认证链路实战说明。 +- [验证码机制](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/core/captcha.html): 验证码是防止自动化攻击的重要安全手段。 +- [系统配置管理](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/core/config.html): 系统配置模块用于管理动态的键值对配置项，与数据字典类似但更偏向系统级参数。 +- [跨域资源共享（CORS）](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/core/cors.html): CORS（Cross-Origin Resource Sharing）跨域资源共享是前后端分离架构必须处理的问题。 +- [演示模式](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/core/demo-mode.html): 演示模式用于在线体验环境，开启后所有写操作（新增、编辑、删除等）将被拦截，返回"演示环境，暂无操作权限"提示。 +- [数据字典使用指南](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/core/dict-guide.html): 数据字典的完整使用流程，从新增字典类型到在代码中使用字典数据的实操指南。 +- [字典模块](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/core/dict.html): 数据字典用于管理系统中的枚举值和配置项，如状态、类型、性别等。 +- [异常与响应处理](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/core/exception.html): 定义了统一的响应格式和全局异常处理机制。 +- [防重复提交](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/core/idempotent.html): 防重复提交是保障数据一致性的重要措施。 +- [用户认证（JWT）](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/core/jwt.html): JWT（JSON Web Token）是系统的核心认证机制。 +- [登录日志](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/core/login-log.html): 登录日志记录每次登录尝试（成功/失败），包含登录账号、IP地址、浏览器信息、登录时间等。 +- [操作日志](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/core/operation-log.html): 操作日志通过 @operation_log 装饰器标记需要记录日志的视图方法，自动记录请求参数、响应结果、耗时、操作类型等信息。 +- [请求限流](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/core/rate-limit.html): 请求限流可通过中间件实现 IP 级别的限流，防止恶意请求和 DoS 攻击。 +- [权限管理（RBAC）](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/core/rbac.html): 采用基于角色的访问控制（RBAC）模型，通过用户-角色-菜单三层关系实现细粒度的权限管理。 +- [参数验证（Form）](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/core/validator.html): 使用 Django ModelForm 进行请求参数验证。 +- [API 层开发](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/frontend/api.html): 前端 API 层位于 src/api/ 目录，封装所有与后端的 HTTP 请求。 +- [前端构建](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/frontend/build.html): 前端使用 Vite 构建，支持开发服务器和生产构建。 +- [公共组件库](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/frontend/components.html): 项目提供丰富的公共组件，位于 ui/src/components/ 目录，基于 NaiveUI 二次封装，覆盖表格、表单、弹窗、上传、富文本编辑等常见场景。 +- [BasicForm 表单](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/frontend/form.html): BasicForm 位于 src/components/Form/src/BasicForm.vue，基于 NaiveUI 的 n-form 二次封装，通过 schemas 配置化定义表单字段， +- [Hooks 组合式函数](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/frontend/hooks.html): 项目封装了一系列组合式函数（Hooks），位于 src/hooks/ 和 src/utils/ 目录，提供权限检查、异步 loading、防重复提交、实时时钟、项目配置等可复用逻辑。 +- [国际化](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/frontend/i18n.html): 当前项目仅支持中文界面，NaiveUI 使用中文语言包（zhCN），所有界面文本直接硬编码在组件中。 +- [Modal 弹窗](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/frontend/modal.html): 项目使用 basicModal 组件（src/components/Modal/src/BasicModal.vue）配合 useModal hook 实现弹窗。 +- [权限指令 v-perm](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/frontend/perm-directive.html): v-perm 和 v-perms 是项目自定义的 Vue 指令，用于按钮级别的权限控制，无权限时自动从 DOM 中移除元素。 +- [路由与菜单](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/frontend/router.html): 前端路由基于 Vue Router 4 实现动态路由生成，菜单数据从后端获取，通过 generator-routers.ts 递归生成路由表，路由守卫控制登录状态和权限。 +- [前端环境与结构](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/frontend/setup.html): 前端基于 Vue3 + NaiveUI 构建，使用 pnpm 作为包管理工具，Vite 作为构建工具，TypeScript 作为开发语言。 +- [Store 状态管理](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/frontend/store.html): 前端使用 Pinia 进行状态管理，核心模块包括 user（用户信息与权限）、asyncRoute（动态路由与菜单）、projectSetting（项目配置）、designSetting（主题设计）等。 +- [样式与主题](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/frontend/style.html): 前端样式方案采用 Tailwind CSS + SCSS + NaiveUI 主题覆盖，支持深色模式切换。 +- [BasicTable 表格](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/frontend/table.html): BasicTable 位于 src/components/Table/src/Table.vue，基于 NaiveUI 的 n-data-table 二次封装，提供列定义、数据请求、分页、操作列、 +- [工具函数](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/frontend/utils.html): 前端工具函数位于 src/utils/ 目录，提供认证管理、本地存储、日期格式化、树结构操作、文件下载等通用能力。 +- [页面视图开发](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/frontend/view.html): 页面视图位于 src/views/ 目录，每个业务模块遵循 index.vue（列表页）+ edit.vue（编辑弹窗）+ detail.vue（详情弹窗）的标准模式，辅以 +- [接口响应规范](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/integration/api-contract.html): 后端所有接口统一返回 R.ok() / R.failed() 格式的 JSON 响应，前端通过 VAxios 的 transformRequestData 拦截器统一解包处理。 +- [字典数据联调](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/integration/dict-sync.html): 字典数据通过后端字典 API 获取，前端在下拉选择器中渲染选项。 +- [权限节点联动](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/integration/perm-sync.html): 前后端权限通过统一的权限节点字符串联动，后端 PermissionRequired 中间件校验权限，前端 v-perm 指令和 TableAction 的 auth 属性控制按钮显示。 +- [代理配置](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/integration/proxy.html): 开发环境通过 Vite 代理转发 API 请求到后端 Django 服务，生产环境通过 Nginx 代理。 +- [文件上传联调](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/integration/upload-sync.html): 文件上传涉及前端 Upload 组件、后端上传接口和 URL 拼接三个环节，需要前后端协同配置。 +- [数据库与 ORM](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/tools/db-session.html): 项目使用 Django ORM 作为数据库访问层，数据库连接配置位于 config/env.py 和 application/settings.py。 +- [导入导出](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/tools/excel.html): 基于 openpyxl 实现 Excel 导入导出功能，支持通过 file_template 模块管理导入模板配置。 +- [IP/UA 解析](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/tools/ip-ua.html): 提供客户端 IP 获取、IP 地理位置查询和 User-Agent 解析三大能力，位于 utils/common.py。 +- [日志系统](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/tools/logger.html): 通过 Python 标准库 logging 实现结构化日志，Django 框架内置日志配置，支持控制台 + 文件双输出。 +- [密码工具](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/tools/password.html): 密码加密使用 Django 内置的 make_password 和 check_password 函数，基于 PBKDF2 算法（默认工作因子 320000 次迭代）。 +- [权限缓存](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/tools/perm-cache.html): 通过 Redis 实现用户权限和菜单的缓存，采用用户级缓存 + 全局版本号双层策略。 +- [请求解析工具](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/tools/request-util.html): utils/common.py 提供请求数据解析相关的工具函数，核心函数 parse_request_body() 用于解析请求体 JSON 数据。 +- [富文本过滤](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/tools/rich-text.html): 富文本编辑器内容存在存储型 XSS 风险，通过 save_content() 函数实现 HTML 内容处理，在落盘前统一过滤危险内容并迁移嵌入图片。 +- [文件上传完整流程](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/tools/upload-guide.html): 富文本编辑器（如 WangEditor 等）的图片上传同样使用此接口。 +- [文件上传](http://docs.django.naivevue.djangoadmin.cn/zh/volume4/tools/upload.html): 提供本地文件上传功能，支持图片和通用文件上传，内置扩展名白名单校验。 + +## 6. 代码生成器 + +- [CLI 命令行使用](http://docs.django.naivevue.djangoadmin.cn/zh/volume5/cli.html): 代码生成器 CLI 模式的使用方法，包括单表生成、预览模式和配置导出。 +- [代码生成引擎](http://docs.django.naivevue.djangoadmin.cn/zh/volume5/code-engine.html): 代码生成引擎的工作原理，包括配置解析、模板渲染、文件写入和自动注册的完整流程。 +- [配置文件详解](http://docs.django.naivevue.djangoadmin.cn/zh/volume5/config.html): 代码生成器 JSON 配置文件的格式说明，包括模块名称、字段属性等配置项的详细解释。 +- [实战案例](http://docs.django.naivevue.djangoadmin.cn/zh/volume5/demo.html): 以 django_example 演示表为完整案例，演示从建表到生成到使用的全流程。 +- [常见问题](http://docs.django.naivevue.djangoadmin.cn/zh/volume5/faq.html): 代码生成器使用过程中常见问题的原因分析和解决方案。 +- [概述与架构](http://docs.django.naivevue.djangoadmin.cn/zh/volume5/overview.html): 代码生成器的整体架构、核心模块和生成流程概述。 +- [表结构解析引擎](http://docs.django.naivevue.djangoadmin.cn/zh/volume5/parser.html): 表结构解析引擎的工作原理，从数据库读取表元数据并智能推断字段用途的过程。 +- [自定义模板](http://docs.django.naivevue.djangoadmin.cn/zh/volume5/templates.html): 代码生成器模板的 Jinja2 语法说明，包括模板变量、字段属性和自定义模板的开发方法。 +- [Web 管理界面](http://docs.django.naivevue.djangoadmin.cn/zh/volume5/web-ui.html): 代码生成器 Web 管理界面的使用方法，通过可视化界面操作单表生成和批量生成。 + +## 7. 运维部署 + +- [备份与恢复](http://docs.django.naivevue.djangoadmin.cn/zh/volume6/backup.html): - 3 份数据副本（1 份生产 + 2 份备份） - 2 种不同存储介质（如本地磁盘 + 远程存储） - 1 份异地备份（防机房级灾难） +- [CI/CD 流水线配置](http://docs.django.naivevue.djangoadmin.cn/zh/volume6/ci-cd.html): CI/CD（持续集成/持续部署）是现代开发流程的基础设施。 +- [数据库迁移](http://docs.django.naivevue.djangoadmin.cn/zh/volume6/db-migrate.html): - 结构迁移：Django 内置迁移系统（makemigrations + migrate） - 字段注释：Django 4.1+ 通过 db_comment 参数自动添加数据库字段注释 +- [部署 Checklist](http://docs.django.naivevue.djangoadmin.cn/zh/volume6/deploy-checklist.html): 从服务器准备到应用上线的完整部署操作清单，适用于生产环境首次部署和后续版本更新。 +- [Docker容器化](http://docs.django.naivevue.djangoadmin.cn/zh/volume6/docker.html): - 环境一致性：消除"在我机器上能跑"的问题 - 快速部署：一条命令启动完整服务 - 资源隔离：应用与宿主机环境解耦 +- [环境规划](http://docs.django.naivevue.djangoadmin.cn/zh/volume6/env-plan.html): 各环境之间保持代码一致，仅通过环境变量（.env）区分配置。 +- [健康检查与监控](http://docs.django.naivevue.djangoadmin.cn/zh/volume6/monitoring.html): `` 1. 应用层：健康检查端点、业务指标 2. 系统层：CPU/内存/磁盘/网络 3. 中间件：MySQL/Redis 连接状态 4. 日志：集中式日志收集与分析 `` +- [Nginx 反向代理](http://docs.django.naivevue.djangoadmin.cn/zh/volume6/nginx.html): `` 客户端 -> Nginx（80/443） ├─ / -> 前端静态资源（dist/） ├─ /api/... -> Django 后端（8000） ├─ /static/ -> Django +- [性能调优](http://docs.django.naivevue.djangoadmin.cn/zh/volume6/performance.html): 1. 先测量，后优化：用数据说话，避免盲目调参 2. 瓶颈优先：找到最大瓶颈，集中优化 3. 渐进式：每次只调整一个参数，观察效果 +- [多实例与负载均衡](http://docs.django.naivevue.djangoadmin.cn/zh/volume6/scaling.html): 当单台服务器无法满足性能需求时，需要通过多实例部署和负载均衡来提升系统吞吐量。 +- [安全加固](http://docs.django.naivevue.djangoadmin.cn/zh/volume6/security-hardening.html): - 最小权限：只开放必要的端口和权限 - 纵深防御：多层安全措施叠加 - 默认安全：配置默认值应为安全选项 +- [Supervisor进程管理](http://docs.django.naivevue.djangoadmin.cn/zh/volume6/supervisor.html): - Linux 服务器直接部署（非 Docker） - 需要进程自动重启和日志轮转 - 管理多个相关进程 +- [故障排查手册](http://docs.django.naivevue.djangoadmin.cn/zh/volume6/troubleshooting.html): 1. 查看日志：tail -f logs/supervisor.out.log 或 docker-compose logs -f 2. 检查配置：.env 文件、数据库连接、Redis 连接 3. +- [版本升级流程](http://docs.django.naivevue.djangoadmin.cn/zh/volume6/upgrade.html): 1. 先备份，后升级 2. 先测试环境，后生产环境 3. 每次升级可回滚 4. 低峰期执行升级 + +## 8. 规范标准 + +- [API响应规范](http://docs.django.naivevue.djangoadmin.cn/zh/volume7/api-response.html): - 所有接口必须通过 R.ok() 或 R.failed() 返回，禁止直接返回 dict - 成功响应 code=0，失败响应 code=1 - 响应体始终包含 code、data、msg、ok +- [代码审查清单](http://docs.django.naivevue.djangoadmin.cn/zh/volume7/code-review.html): - 每次提交必须经过至少一人审查 - 审查关注点：正确性 > 安全性 > 可维护性 > 性能 - 审查意见应具体、可操作，避免主观评价 +- [代码风格与 Lint 规范](http://docs.django.naivevue.djangoadmin.cn/zh/volume7/code-style.html): 统一的代码风格是团队协作的基础。 +- [删除规范](http://docs.django.naivevue.djangoadmin.cn/zh/volume7/deletion.html): - is_delete = False（0）：正常记录（默认值） - is_delete = True（1）：已删除记录 - 所有查询方法自动过滤 is_delete=False，业务层无需关心 +- [文档规范](http://docs.django.naivevue.djangoadmin.cn/zh/volume7/doc-standard.html): - 文档与代码同步更新 - 使用中文编写（项目约定） - 示例代码可直接运行 +- [前端 API 规范](http://docs.django.naivevue.djangoadmin.cn/zh/volume7/fe-api.html): - 每个后端模块对应一个 API 文件 - 函数命名统一使用 名词 + 动词 格式（与后端保持一致） - 请求路径使用相对路径（/position/page），不含 /api/v1 前缀（由 +- [前端页面规范](http://docs.django.naivevue.djangoadmin.cn/zh/volume7/fe-component.html): - Vue3（Composition API + <script setup>） - NaiveUI - 自定义组件（BasicTable / BasicForm / TableAction / +- [Form层规范](http://docs.django.naivevue.djangoadmin.cn/zh/volume7/form.html): - 继承 forms.ModelForm - 每个字段定义中文 error_messages - 使用 Meta.fields 指定验证字段 - 验证在 Service 层 ORM 操作之前执行 +- [Git提交规范](http://docs.django.naivevue.djangoadmin.cn/zh/volume7/git.html): `` <type>(<scope>): <subject> <body> <footer> `` +- [Model层规范](http://docs.django.naivevue.djangoadmin.cn/zh/volume7/model.html): - 所有模型继承 BaseModel - 字段命名使用 snake_case - 每个字段必须有 db_comment 注释 - 使用 get_table_name() 生成表名 +- [分页规范](http://docs.django.naivevue.djangoadmin.cn/zh/volume7/pagination.html): - 前端传递 pageNo（页码，从 1 开始）和 pageSize（每页条数） - 后端返回 {records, total, size, current, pages} 结构 - 默认每页 10 +- [Service层规范](http://docs.django.naivevue.djangoadmin.cn/zh/volume7/service.html): - 所有业务逻辑集中在 Service 层 - View 层只负责接收请求和返回响应 - Model 层只负责数据定义 - Form 层只负责数据验证 +- [测试最佳实践](http://docs.django.naivevue.djangoadmin.cn/zh/volume7/testing-best-practices.html): 本文在 测试规范 基础上，介绍更高级的测试技巧，包括 Mock、Fixture、API 测试、覆盖率实战等。 +- [测试规范](http://docs.django.naivevue.djangoadmin.cn/zh/volume7/testing.html): 1. 单元测试（Unit）：验证单个函数/方法的逻辑正确性 2. 集成测试（Integration）：验证模块间协作、真实数据库操作 +- [View层规范](http://docs.django.naivevue.djangoadmin.cn/zh/volume7/view.html): - 使用类视图（继承 View） - 通过 @method_decorator(check_login) 验证登录 - 通过 PermissionRequired mixin 检查权限 - 通过 + +## 附录 + +- [常见问题汇总](http://docs.django.naivevue.djangoadmin.cn/zh/faq.html): 本页汇总了项目各模块的常见问题及解决方案，按场景分类索引。 +- [贡献指南](http://docs.django.naivevue.djangoadmin.cn/zh/other/contributing.html): 本页介绍如何参与项目贡献，包括代码提交、Issue 反馈与 PR 流程，欢迎关注本项目的开发者参阅。 +- [免责声明](http://docs.django.naivevue.djangoadmin.cn/zh/other/declare.html): 使用本产品前必读的法律声明，明确产品性质、使用限制与责任划分，一旦使用本产品即视为接受本声明全部条款。 +- [广告赞助](http://docs.django.naivevue.djangoadmin.cn/zh/other/sponsor.html): 1. 投放广告不得与官方全系产品存在结构性冲突和竞争 2. 广告内容需符合国家法律法规，不得包含虚假、误导性信息 3. 广告素材需经官方审核通过后方可上线，审核周期 1-3 个工作日 4. diff --git a/DjangoAdmin_Django_NaiveVue/public/robots.txt b/DjangoAdmin_Django_NaiveVue/public/robots.txt new file mode 100644 index 0000000..a5c5455 --- /dev/null +++ b/DjangoAdmin_Django_NaiveVue/public/robots.txt @@ -0,0 +1,33 @@ +# DjangoAdmin Django+NaiveUI 开发文档 +User-agent: * +Allow: / + +# 显式放行生成式引擎 / AI 爬虫（GEO） +User-agent: GPTBot +Allow: / + +User-agent: ChatGPT-User +Allow: / + +User-agent: ClaudeBot +Allow: / + +User-agent: Claude-Web +Allow: / + +User-agent: anthropic-ai +Allow: / + +User-agent: PerplexityBot +Allow: / + +User-agent: Google-Extended +Allow: / + +User-agent: Bytespider +Allow: / + +User-agent: bingbot +Allow: / + +Sitemap: http://docs.django.naivevue.djangoadmin.cn/sitemap.xml diff --git a/DjangoAdmin_Django_NaiveVue/scripts/generate-llms-txt.mjs b/DjangoAdmin_Django_NaiveVue/scripts/generate-llms-txt.mjs new file mode 100644 index 0000000..8e3385c --- /dev/null +++ b/DjangoAdmin_Django_NaiveVue/scripts/generate-llms-txt.mjs @@ -0,0 +1,122 @@ +#!/usr/bin/env node +/** + * 生成 public/llms.txt（llmstxt.org 标准）——AI 爬虫的站点摘要索引。 + * + * 数据源：zh 目录下全部 Markdown 的 H1 + :::tip 概述首句（与 meta + * description 同源，复用 .vitepress/config/extract.mjs）。按侧边栏章节分组。 + * + * 用法：node scripts/generate-llms-txt.mjs + * 已挂入 package.json 的 docs:build 前置步骤。 + */ +import fs from "node:fs"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; +import { + SITE_URL, + SITE_DESCRIPTION, + extractDescription, +} from "../.vitepress/config/extract.mjs"; + +const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."); +const ZH = path.join(ROOT, "zh"); + +/** 顶层目录 → 侧边栏章节名（与 .vitepress/config/zh.ts 保持一致） */ +const SECTIONS = [ + ["", "1. 了解项目"], + ["volume1", "2. 快速入门"], + ["volume2", "3. 模块开发实战"], + ["volume3", "4. 架构设计"], + ["volume4", "5. 开发指南"], + ["volume5", "6. 代码生成器"], + ["volume6", "7. 运维部署"], + ["volume7", "8. 规范标准"], + ["other", "附录"], +]; + +function walk(dir, out = []) { + for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { + const p = path.join(dir, entry.name); + if (entry.isDirectory()) walk(p, out); + else if (entry.name.endsWith(".md")) out.push(p); + } + return out; +} + +/** 提取首个 H1 文本 */ +function h1Of(md) { + // 围栏感知：跳过 ``` 代码块内的 # 注释，取真正的页面 H1 + let inFence = false; + for (const line of md.split("\n")) { + if (line.startsWith("```")) { inFence = !inFence; continue; } + if (!inFence && line.startsWith("# ") && !line.startsWith("## ")) { + return line.slice(2).trim(); + } + } + return ""; +} + +/** H1 编号排序键："5.10 x" → [5,10]；无编号排最后 */ +function sortKey(h1) { + const m = h1.match(/^(\d+(?:\.\d+)*)/); + if (m) return m[1].split(".").map(Number); + const letter = h1.match(/^([A-Z])\./); + if (letter) return [1000 + letter[1].charCodeAt(0)]; + return [9999]; +} + +function cmpKey(a, b) { + const len = Math.max(a.length, b.length); + for (let i = 0; i < len; i++) { + const x = a[i] ?? 0; + const y = b[i] ?? 0; + if (x !== y) return x - y; + } + return 0; +} + +const files = walk(ZH); +const groups = new Map(SECTIONS.map(([dir, label]) => [label, []])); + +for (const file of files) { + const rel = path.relative(ZH, file).replace(/\\/g, "/"); + const topDir = rel.includes("/") ? rel.split("/")[0] : ""; + const base = rel.split("/").pop(); + const label = (topDir === "" && base === "faq.md") ? "附录" + : SECTIONS.find(([dir]) => dir === topDir)?.[1] ?? "附录"; + + const md = fs.readFileSync(file, "utf8"); + const h1 = h1Of(md); + if (!h1) continue; + const desc = extractDescription(md); + const url = `${SITE_URL}/zh/${rel.replace(/\.md$/, ".html")}`; + groups.get(label).push({ h1, desc, url, key: sortKey(h1) }); +} + +const lines = [ + "# DjangoAdmin Django+NaiveUI 开发文档", + "", + `> ${SITE_DESCRIPTION}。内置 RBAC 权限体系、代码生成器等开箱即用功能，支持五种数据库一键切换。本文档共 ${files.length} 篇，按章节组织。`, + "", +]; + +// 按章节顺序输出，合并重复 label（appendix/other 同为「附录」，只输出一次） +const printed = new Set(); +for (const [, label] of SECTIONS) { + if (printed.has(label)) continue; + const items = groups.get(label); + if (!items?.length) continue; + printed.add(label); + + lines.push(`## ${label}`, ""); + items.sort((a, b) => cmpKey(a.key, b.key)); + for (const { h1, desc, url } of items) { + lines.push(desc ? `- [${h1}](${url}): ${desc}` : `- [${h1}](${url})`); + } + lines.push(""); +} + +const out = path.join(ROOT, "public", "llms.txt"); +fs.writeFileSync(out, lines.join("\n"), "utf8"); +console.log( + `llms.txt: ${files.length} 页 → ${path.relative(ROOT, out)} (${printed.size} 个章节)`, +); diff --git a/DjangoAdmin_Django_NaiveVue/zh/course.md b/DjangoAdmin_Django_NaiveVue/zh/course.md index 7ef2aa6..3074c77 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/course.md +++ b/DjangoAdmin_Django_NaiveVue/zh/course.md @@ -1,3 +1,5 @@ +# 新手入门指南 + :::warning 特别提醒 官方精心制作本教程，目的在于方便用户快速掌握软件产品的使用和部署。通过此教程，刚入行的开发者也可以快速掌握并投入产品研发。本地部署时务必请耐心阅读文档操作。 ::: diff --git a/DjangoAdmin_Django_NaiveVue/zh/introduction.md b/DjangoAdmin_Django_NaiveVue/zh/introduction.md index ebcbca8..c76d94b 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/introduction.md +++ b/DjangoAdmin_Django_NaiveVue/zh/introduction.md @@ -1,3 +1,9 @@ +# 1.1 项目介绍 + +:::tip 概述 +DjangoAdmin 是企业级中台解决方案，后端基于 Django + Django ORM，前端基于 Vue3 + NaiveUI，内置 RBAC 权限、代码生成器等开箱即用功能，支持五种数据库一键切换。 +::: + <div align="center"> <p align="center"> <img src="/logo.png" height="150" alt="logo"/> diff --git a/DjangoAdmin_Django_NaiveVue/zh/other/contributing.md b/DjangoAdmin_Django_NaiveVue/zh/other/contributing.md index 2708c82..189c655 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/other/contributing.md +++ b/DjangoAdmin_Django_NaiveVue/zh/other/contributing.md @@ -1,7 +1,7 @@ # 贡献指南 :::tip 说明 -感谢你对本项目的关注！本文档介绍如何参与项目贡献，包括代码提交、Issue 反馈、PR 流程等。 +本页介绍如何参与项目贡献，包括代码提交、Issue 反馈与 PR 流程，欢迎关注本项目的开发者参阅。 ::: ## 开发环境搭建 diff --git a/DjangoAdmin_Django_NaiveVue/zh/other/declare.md b/DjangoAdmin_Django_NaiveVue/zh/other/declare.md index 7737479..915692a 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/other/declare.md +++ b/DjangoAdmin_Django_NaiveVue/zh/other/declare.md @@ -1,5 +1,9 @@ # 免责声明 +:::tip 概述 +使用本产品前必读的法律声明，明确产品性质、使用限制与责任划分，一旦使用本产品即视为接受本声明全部条款。 +::: + :::danger 重要提示 任何用户在使用本团队研发的系列软件产品（以下简称「本产品」）前，请仔细阅读并透彻理解本声明。选择不使用本产品，可随时停止使用；一旦使用本产品，即视为对本声明全部内容的认可和接受。 ::: diff --git a/DjangoAdmin_Django_NaiveVue/zh/struct.md b/DjangoAdmin_Django_NaiveVue/zh/struct.md index 5347f87..a58356a 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/struct.md +++ b/DjangoAdmin_Django_NaiveVue/zh/struct.md @@ -1,5 +1,9 @@ # 项目目录结构 +:::tip 概述 +本页说明项目前后端目录组织与各目录职责，二次开发定位文件或了解工程结构时对照查阅。 +::: + ## 整体结构 ``` diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume2/code-list.md b/DjangoAdmin_Django_NaiveVue/zh/volume2/code-list.md index a41990f..2a26172 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume2/code-list.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume2/code-list.md @@ -1,5 +1,9 @@ # 完整代码清单 +:::tip 概述 +本页汇总案例管理（Example）模块涉及的全部文件代码，开发时可快速查阅与复制对照。 +::: + 本章汇总 Example 案例模块涉及的全部文件，便于开发时快速查阅和复制。 ## 后端文件清单 diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume2/faq.md b/DjangoAdmin_Django_NaiveVue/zh/volume2/faq.md index 0d3d4d3..d9d2e02 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume2/faq.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume2/faq.md @@ -1,5 +1,9 @@ # 常见问题与排错 +:::tip 概述 +本页汇总模块开发过程中的常见问题与排错方法，开发受阻时按症状索引即可定位。 +::: + 本章汇总模块开发过程中的常见问题和解决方案。 ## 后端问题 diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume2/fe-api.md b/DjangoAdmin_Django_NaiveVue/zh/volume2/fe-api.md index 8d52e68..7c1f64f 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume2/fe-api.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume2/fe-api.md @@ -1,5 +1,9 @@ # 前端 API 层 +:::tip 概述 +前端 API 层封装后端接口的 HTTP 请求，每个业务模块对应一个 API 文件，本页讲解基于 Axios 封装的编写规范。 +::: + 前端 API 层负责封装后端接口的 HTTP 请求。每个业务模块对应一个 API 文件，使用项目封装的 Axios 工具发送请求。 ## 文件位置 diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume2/fe-router.md b/DjangoAdmin_Django_NaiveVue/zh/volume2/fe-router.md index 04bc70a..20e3913 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume2/fe-router.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume2/fe-router.md @@ -1,5 +1,9 @@ # 前端路由与菜单 +:::tip 概述 +本页讲解前端路由与菜单机制——路由和菜单由后端动态返回，前端只需注册路由组件映射。 +::: + 前端路由定义页面的访问路径，菜单是路由的可视化展示。项目的路由和菜单由后端动态返回，前端只需注册路由组件映射。 ## 动态路由机制 diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume2/fe-view.md b/DjangoAdmin_Django_NaiveVue/zh/volume2/fe-view.md index 86c27d3..b82f10d 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume2/fe-view.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume2/fe-view.md @@ -1,5 +1,9 @@ # 前端页面视图 +:::tip 概述 +前端页面视图是用户直接交互的界面，本页讲解 Vue3 + NaiveUI 下一个完整 CRUD 页面的文件组成与编写方式。 +::: + 前端页面视图是用户直接交互的界面。项目使用 Vue3 + NaiveUI + Vite 构建。一个完整的 CRUD 页面由 5 个文件组成： ``` diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume2/form.md b/DjangoAdmin_Django_NaiveVue/zh/volume2/form.md index 884ad47..7b24bba 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume2/form.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume2/form.md @@ -1,5 +1,9 @@ # 表单验证（Form） +:::tip 概述 +表单验证是模块开发的第二步，讲解基于 Django ModelForm 的提交数据校验与错误信息约定。 +::: + 表单验证是模块开发的第二步，用于对前端提交的数据进行验证。项目使用 Django 的 `ModelForm` 实现表单验证，所有错误信息使用中文提示。 ## 文件位置 diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume2/model.md b/DjangoAdmin_Django_NaiveVue/zh/volume2/model.md index 8c80c0f..e10cb25 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume2/model.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume2/model.md @@ -1,5 +1,9 @@ # 数据模型（Model） +:::tip 概述 +数据模型是模块开发的第一步，讲解如何用 Django ORM 与 BaseModel 定义数据库表结构，新建模块时从本页开始。 +::: + 数据模型是模块开发的第一步，用于定义数据库表结构。项目使用 Django ORM，模型类通过继承 `BaseModel` 自动获得通用字段。 ## 文件位置 diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume2/overview.md b/DjangoAdmin_Django_NaiveVue/zh/volume2/overview.md index 4db86b4..f476f00 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume2/overview.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume2/overview.md @@ -1,5 +1,9 @@ # 模块开发实战概述 +:::tip 概述 +本章以案例管理（Example）模块为完整案例，手把手演示从零开发一个业务模块的全流程，学完即可掌握项目中任意模块的开发方式。 +::: + 本章以「案例管理（Example）」模块为完整案例，手把手演示从零开发一个业务模块的全流程。学完本章后，你将掌握项目中任意模块的开发方式。 ## 你将学到什么 diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume2/permission.md b/DjangoAdmin_Django_NaiveVue/zh/volume2/permission.md index c03d73b..d9fe07a 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume2/permission.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume2/permission.md @@ -1,5 +1,9 @@ # 权限节点配置 +:::tip 概述 +本页讲解接口权限字符串的定义与菜单权限节点的配置方法，联调 403 问题时对照本页。 +::: + 后端代码中的 `permission_required = ("sys:example:page",)` 定义了接口所需的权限字符串，但权限节点本身需要在数据库中配置，才能在「菜单管理」中分配给角色。 ## 权限字符串格式 diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume2/service.md b/DjangoAdmin_Django_NaiveVue/zh/volume2/service.md index 0910d08..7937611 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume2/service.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume2/service.md @@ -1,5 +1,9 @@ # 业务逻辑层（Service） +:::tip 概述 +业务逻辑层是模块开发的核心，CRUD 操作、业务规则与数据处理均封装在 Service 层函数，本页讲解其编写规范。 +::: + 业务逻辑层是模块开发的第三步，也是最核心的部分。所有 CRUD 操作、业务规则、数据处理都封装在 Service 层的独立函数中。 ## 文件位置 diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume2/url.md b/DjangoAdmin_Django_NaiveVue/zh/volume2/url.md index 024e2c7..9c8c74e 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume2/url.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume2/url.md @@ -1,5 +1,9 @@ # URL 路由配置 +:::tip 概述 +URL 路由是模块开发的最后一步，本页讲解用 Django path() 将路径映射到视图类的配置方法。 +::: + URL 路由是模块开发的最后一步，负责将 URL 路径映射到视图类。项目使用 Django 的 `path()` 函数定义路由，通过 `include()` 将模块路由注册到主路由。 ## 文件位置 diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume2/view.md b/DjangoAdmin_Django_NaiveVue/zh/volume2/view.md index 5e3bafc..be37d10 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume2/view.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume2/view.md @@ -1,5 +1,9 @@ # 视图层（View） +:::tip 概述 +视图层负责处理 HTTP 请求并调用 Service 业务逻辑，本页讲解 Django 类视图的编写方式与响应约定。 +::: + 视图层是模块开发的第四步，负责处理 HTTP 请求并调用 Service 层的业务逻辑。项目使用 Django 的类视图（Class-Based Views），每个视图类对应一个 API 端点。 ## 文件位置 diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume3/base-classes.md b/DjangoAdmin_Django_NaiveVue/zh/volume3/base-classes.md index 27817b6..c20ff00 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume3/base-classes.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume3/base-classes.md @@ -1,5 +1,9 @@ # 第四章 架构设计 - 核心基类体系 +:::tip 概述 +本页汇总项目核心基类体系的总览与用法，编写业务代码前先了解可复用的基座能力。 +::: + ## 4.1 基类总览 核心基类体系由四大基类组成，覆盖从数据模型到请求校验再到响应输出的完整链路。子类只需声明差异点，即可获得标准化的增删改查能力。 diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume3/cache.md b/DjangoAdmin_Django_NaiveVue/zh/volume3/cache.md index 1e20ea1..028649d 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume3/cache.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume3/cache.md @@ -1,5 +1,9 @@ # 第四章 架构设计 - 缓存架构 +:::tip 概述 +本页说明系统缓存架构的设计与使用方式，涉及缓存一致性或性能问题时查阅。 +::: + ## 4.1 缓存架构概述 项目使用 Redis 作为缓存后端，通过 Django 的缓存框架实现统一的缓存管理。缓存主要用于以下场景： diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume3/database-design.md b/DjangoAdmin_Django_NaiveVue/zh/volume3/database-design.md index 9654a0c..5ed7a5e 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume3/database-design.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume3/database-design.md @@ -1,5 +1,9 @@ # 第四章 架构设计 - 数据库设计 +:::tip 概述 +本页说明数据库设计原则与表结构组织方式，建表或数据迁移时对照本页。 +::: + ## 4.1 数据库设计概述 项目使用 MySQL 8.0 作为主数据库，通过 Django ORM 进行数据访问。所有业务表继承 BaseModel 抽象基类，自动获得 6 个通用字段。 diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume3/directory.md b/DjangoAdmin_Django_NaiveVue/zh/volume3/directory.md index 8a36f66..e434a51 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume3/directory.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume3/directory.md @@ -1,5 +1,9 @@ # 第四章 架构设计 - 目录结构设计 +:::tip 概述 +本页说明项目根目录与各层目录的组织设计，二次开发定位文件时对照查阅。 +::: + ## 4.1 项目根目录 ``` diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume3/extensibility.md b/DjangoAdmin_Django_NaiveVue/zh/volume3/extensibility.md index 339097c..1c908e3 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume3/extensibility.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume3/extensibility.md @@ -1,5 +1,9 @@ # 第四章 架构设计 - 扩展性设计 +:::tip 概述 +本页说明系统的扩展性设计原则，二次开发新增能力或改造现有模块时参考。 +::: + ## 4.1 扩展性设计原则 项目遵循开闭原则（OCP）：对扩展开放，对修改关闭。新功能通过添加新模块实现，而非修改现有代码。系统通过 Django App 机制、代码生成器、模板定制等方式提供扩展能力。 diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume3/layer-arch.md b/DjangoAdmin_Django_NaiveVue/zh/volume3/layer-arch.md index cb1ae9b..3f5f2c6 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume3/layer-arch.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume3/layer-arch.md @@ -1,5 +1,9 @@ # 第四章 架构设计 - 分层架构详解 +:::tip 概述 +本页详解后端分层架构的职责划分与调用关系，编写代码前先理解各层边界。 +::: + ## 4.1 分层架构概述 项目采用经典的五层架构设计，各层职责明确，依赖关系清晰： diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume3/overview.md b/DjangoAdmin_Django_NaiveVue/zh/volume3/overview.md index 5f826c3..354f3c9 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume3/overview.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume3/overview.md @@ -1,5 +1,9 @@ # 第四章 架构设计 - 系统架构总览 +:::tip 概述 +本页给出系统整体架构总览，理解各层职责与模块关系时从本页开始。 +::: + ## 4.1 整体架构 项目采用前后端分离的 B/S 架构，后端基于 Django 6.0.3 提供 RESTful API，前端基于 Vue3 + NaiveUI 构建单页应用。系统通过 Nginx 反向代理统一入口，实现静态资源托管与 API 转发。 diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume3/request-flow.md b/DjangoAdmin_Django_NaiveVue/zh/volume3/request-flow.md index b69d1e5..7887aae 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume3/request-flow.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume3/request-flow.md @@ -1,5 +1,9 @@ # 第四章 架构设计 - 请求处理流程 +:::tip 概述 +本页给出请求从进入路由到返回响应的全链路处理流程，排查接口问题时对照追踪。 +::: + ## 4.1 请求处理全链路 一个完整的 HTTP 请求在 系统中的处理流程如下： diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume3/security.md b/DjangoAdmin_Django_NaiveVue/zh/volume3/security.md index cb653e1..d6c4dce 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume3/security.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume3/security.md @@ -1,5 +1,9 @@ # 第四章 架构设计 - 安全架构 +:::tip 概述 +本页说明系统安全架构设计，含认证、权限与数据安全等防护机制。 +::: + ## 4.1 安全架构概述 系统从认证、授权、防护三个维度构建安全体系： diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume3/tech-stack.md b/DjangoAdmin_Django_NaiveVue/zh/volume3/tech-stack.md index ee00fdd..d6f7054 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume3/tech-stack.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume3/tech-stack.md @@ -1,5 +1,9 @@ # 第四章 架构设计 - 技术栈选型 +:::tip 概述 +本页列出项目后端与前端完整技术选型及版本要求，评估兼容性或升级影响时对照本表。 +::: + ## 4.1 后端技术栈 ### Django 6.0.3 diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume4/business/article.md b/DjangoAdmin_Django_NaiveVue/zh/volume4/business/article.md index a2811c7..0d28fd8 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume4/business/article.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume4/business/article.md @@ -1,3 +1,5 @@ +# 文章管理 + :::tip 文章管理 文章管理模块支持富文本编辑、分类关联、封面图片上传、图集管理等功能。适用于新闻、公告、帮助文档等内容管理场景。 ::: diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume4/business/category.md b/DjangoAdmin_Django_NaiveVue/zh/volume4/business/category.md index 22f9e98..6e1e54b 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume4/business/category.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume4/business/category.md @@ -1,3 +1,5 @@ +# 分类管理 + :::tip 分类管理 分类管理模块用于管理树形分类数据，如文章分类、产品分类等。通过 `parent_id` 字段实现无限级分类。 ::: diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume4/business/city.md b/DjangoAdmin_Django_NaiveVue/zh/volume4/business/city.md index 1e0fa73..6234529 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume4/business/city.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume4/business/city.md @@ -1,3 +1,5 @@ +# 行政区划管理 + :::tip 城市管理 城市管理模块用于管理行政区划数据，支持省/市/区/街道/社区五级行政区划。通过 `parent_code` 字段实现树形结构。 ::: diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume4/business/content.md b/DjangoAdmin_Django_NaiveVue/zh/volume4/business/content.md index 77af83f..849e344 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume4/business/content.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume4/business/content.md @@ -1,3 +1,5 @@ +# 公告与链接管理 + :::tip 公告/链接 公告和链接是两个简单 CRUD 内容模块，提供标准的增删改查接口。适用于系统公告、友情链接等场景。 ::: diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume4/business/dept.md b/DjangoAdmin_Django_NaiveVue/zh/volume4/business/dept.md index 124bad8..ad7295f 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume4/business/dept.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume4/business/dept.md @@ -1,3 +1,5 @@ +# 部门/职级/岗位管理 + :::tip 部门/职级/岗位 部门、职级、岗位是组织架构管理的三个核心模块。部门采用树形结构，职级和岗位为简单 CRUD 模块。用户表通过 `dept_id`、`position_id`、`level_id` 三个外键关联这三个模块。 ::: diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume4/business/job.md b/DjangoAdmin_Django_NaiveVue/zh/volume4/business/job.md index 8dc8f7d..ff7ff1f 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume4/business/job.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume4/business/job.md @@ -1,3 +1,5 @@ +# 定时任务 + :::tip 定时任务 定时任务模块基于 APScheduler 实现，支持 Cron 表达式调度、任务执行日志、动态启停等功能。包含 job（任务定义）、job_log（执行日志）两个子模块。 ::: diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume4/business/menu.md b/DjangoAdmin_Django_NaiveVue/zh/volume4/business/menu.md index 305f665..ee73679 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume4/business/menu.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume4/business/menu.md @@ -1,3 +1,5 @@ +# 菜单管理 + :::tip 菜单管理 菜单管理是 RBAC 权限系统的基础，负责管理系统的导航菜单和权限节点。支持目录/菜单（type=0）和权限按钮节点（type=1）两种类型，通过树形结构组织。 ::: diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume4/business/param.md b/DjangoAdmin_Django_NaiveVue/zh/volume4/business/param.md index e5eeaf4..58b68c9 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume4/business/param.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume4/business/param.md @@ -1,3 +1,5 @@ +# 参数管理 + :::tip 参数管理 参数管理模块用于管理动态系统参数，支持按参数键查询、修改，无需重启服务即可生效。 ::: diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume4/business/role.md b/DjangoAdmin_Django_NaiveVue/zh/volume4/business/role.md index 0f13489..7f566e2 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume4/business/role.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume4/business/role.md @@ -1,3 +1,5 @@ +# 角色管理 + :::tip 角色管理 角色是 RBAC 权限模型的核心，连接用户和菜单（权限）。通过为角色分配菜单权限，再将角色分配给用户，实现灵活的权限管理。 ::: diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume4/business/user.md b/DjangoAdmin_Django_NaiveVue/zh/volume4/business/user.md index 52def72..0dae730 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume4/business/user.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume4/business/user.md @@ -1,3 +1,5 @@ +# 用户管理 + :::tip 用户管理 用户管理是系统的核心模块，属于复杂业务模块。包含用户 CRUD、角色关联、密码加密、行政区划等功能。与简单 CRUD 模块不同，用户管理使用自定义 service 函数。 ::: diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume4/core/captcha.md b/DjangoAdmin_Django_NaiveVue/zh/volume4/core/captcha.md index ad81dfc..bc8ea2b 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume4/core/captcha.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume4/core/captcha.md @@ -1,3 +1,5 @@ +# 验证码机制 + :::tip 验证码 验证码是防止自动化攻击的重要安全手段。项目使用 django-simple-captcha 库生成图片验证码，存储在数据库中，支持多种验证码格式。源码位于 `application/login/views.py`。 ::: diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume4/core/config.md b/DjangoAdmin_Django_NaiveVue/zh/volume4/core/config.md index f82049c..404c302 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume4/core/config.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume4/core/config.md @@ -1,3 +1,5 @@ +# 系统配置管理 + :::tip 系统配置 系统配置模块用于管理动态的键值对配置项，与数据字典类似但更偏向系统级参数。支持分组管理，可通过接口动态修改，无需重启服务。模块位于 `application/config/`。 ::: diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume4/core/cors.md b/DjangoAdmin_Django_NaiveVue/zh/volume4/core/cors.md index 99bb73d..25a90eb 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume4/core/cors.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume4/core/cors.md @@ -1,3 +1,5 @@ +# 跨域资源共享（CORS） + :::tip CORS跨域 CORS（Cross-Origin Resource Sharing）跨域资源共享是前后端分离架构必须处理的问题。项目使用 `django-cors-headers` 中间件处理跨域请求，通过 `.env` 配置允许的跨域源。 ::: diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume4/core/demo-mode.md b/DjangoAdmin_Django_NaiveVue/zh/volume4/core/demo-mode.md index b3e6a46..5ebc90d 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume4/core/demo-mode.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume4/core/demo-mode.md @@ -1,3 +1,5 @@ +# 演示模式 + :::tip 演示模式 演示模式用于在线体验环境，开启后所有写操作（新增、编辑、删除等）将被拦截，返回"演示环境，暂无操作权限"提示。通过 `DJANGO_DEMO` 环境变量控制。 ::: diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume4/core/dict.md b/DjangoAdmin_Django_NaiveVue/zh/volume4/core/dict.md index 6d0ba27..9dbf470 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume4/core/dict.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume4/core/dict.md @@ -1,3 +1,5 @@ +# 字典模块 + :::tip 数据字典 数据字典用于管理系统中的枚举值和配置项，如状态、类型、性别等。通过字典编码统一管理，前端可通过 `useDictStore` 获取字典选项，避免硬编码。模块位于 `application/dict/`。 ::: diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume4/core/exception.md b/DjangoAdmin_Django_NaiveVue/zh/volume4/core/exception.md index 687a82e..a0e0a48 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume4/core/exception.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume4/core/exception.md @@ -1,3 +1,5 @@ +# 异常与响应处理 + :::tip 全局异常与响应 定义了统一的响应格式和全局异常处理机制。所有 API 返回 `{code, data, msg, ok}` 标准格式。响应函数位于 `utils/R.py`。 ::: diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume4/core/idempotent.md b/DjangoAdmin_Django_NaiveVue/zh/volume4/core/idempotent.md index 112729d..2fbf4f5 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume4/core/idempotent.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume4/core/idempotent.md @@ -1,3 +1,5 @@ +# 防重复提交 + :::tip 防重复提交 防重复提交是保障数据一致性的重要措施。通过前端防抖和后端唯一性校验双重保护，防止用户重复点击导致的数据重复提交。 ::: diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume4/core/jwt.md b/DjangoAdmin_Django_NaiveVue/zh/volume4/core/jwt.md index 3ebe203..5374d5d 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume4/core/jwt.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume4/core/jwt.md @@ -1,3 +1,5 @@ +# 用户认证（JWT） + :::tip JWT认证 JWT（JSON Web Token）是系统的核心认证机制。用户登录成功后获取 Token，后续请求通过 `Authorization: Bearer <token>` 头携带 Token 进行身份验证。项目内置了 Token 生成、解析、刷新和黑名单管理功能，源码位于 `utils/jwt.py`。 ::: diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume4/core/login-log.md b/DjangoAdmin_Django_NaiveVue/zh/volume4/core/login-log.md index c95dc0d..8320f45 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume4/core/login-log.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume4/core/login-log.md @@ -1,3 +1,5 @@ +# 登录日志 + :::tip 登录日志 登录日志记录每次登录尝试（成功/失败），包含登录账号、IP地址、浏览器信息、登录时间等。登录逻辑位于 `application/login/services.py`，日志记录位于 `application/login_log/` 模块。 ::: diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume4/core/operation-log.md b/DjangoAdmin_Django_NaiveVue/zh/volume4/core/operation-log.md index 6cad27c..08ab4e9 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume4/core/operation-log.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume4/core/operation-log.md @@ -1,3 +1,5 @@ +# 操作日志 + :::tip 操作日志 操作日志通过 `@operation_log` 装饰器标记需要记录日志的视图方法，自动记录请求参数、响应结果、耗时、操作类型等信息。源码位于 `application/operation_log/decorators.py`。 ::: diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume4/core/rate-limit.md b/DjangoAdmin_Django_NaiveVue/zh/volume4/core/rate-limit.md index d464610..7ace523 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume4/core/rate-limit.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume4/core/rate-limit.md @@ -1,3 +1,5 @@ +# 请求限流 + :::tip 请求限流 请求限流可通过中间件实现 IP 级别的限流，防止恶意请求和 DoS 攻击。项目中限流可通过 Nginx 反向代理或自定义中间件实现。 ::: diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume4/core/rbac.md b/DjangoAdmin_Django_NaiveVue/zh/volume4/core/rbac.md index 38bb8d8..b781f9e 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume4/core/rbac.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume4/core/rbac.md @@ -1,3 +1,5 @@ +# 权限管理（RBAC） + :::tip RBAC权限 采用基于角色的访问控制（RBAC）模型，通过用户-角色-菜单三层关系实现细粒度的权限管理。权限控制贯穿前后端：后端通过 `PermissionRequired` 混入类校验（`middleware/permission_middleware.py`），前端通过 `v-perm` 指令控制按钮显隐。 ::: diff --git a/DjangoAdmin_Django_NaiveVue/zh/volume4/core/validator.md b/DjangoAdmin_Django_NaiveVue/zh/volume4/core/validator.md index 5d679b6..7630021 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/volume4/core/validator.md +++ b/DjangoAdmin_Django_NaiveVue/zh/volume4/core/validator.md @@ -1,3 +1,5 @@ +# 参数验证（Form） + :::tip 参数验证 使用 Django ModelForm 进行请求参数验证。所有请求体参数通过 Django Form 定义，视图中调用 `form.is_valid()` 自动验证，验证失败通过 `regular.get_err()` 提取错误信息返回前端。 ::: diff --git a/DjangoAdmin_Django_NaiveVue/zh/why.md b/DjangoAdmin_Django_NaiveVue/zh/why.md index d4158f7..671b712 100644 --- a/DjangoAdmin_Django_NaiveVue/zh/why.md +++ b/DjangoAdmin_Django_NaiveVue/zh/why.md @@ -1,5 +1,9 @@ # 为什么选择我们 +:::tip 概述 +本页从低代码生成能力、功能开箱即用与工程可持续性三个维度说明选择本项目的理由，技术选型对比时可作为评估依据。 +::: + ## 低代码生成，开发效率倍增 项目最大的特点是代码生成器。只需在数据库中建好表，一条命令即可生成完整的前后端 CRUD 模块： diff --git a/DjangoAdmin_FastAPI_AntdVue/.vitepress/config/en.ts b/DjangoAdmin_FastAPI_AntdVue/.vitepress/config/en.ts index a1a96ef..b69ab60 100644 --- a/DjangoAdmin_FastAPI_AntdVue/.vitepress/config/en.ts +++ b/DjangoAdmin_FastAPI_AntdVue/.vitepress/config/en.ts @@ -29,7 +29,7 @@ // // themeConfig: { // editLink: { -// pattern: "https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_EleVue", +// pattern: "https://gitee.com/djangoadmin/DjangoAdmin_FastAPI_AntdVue", // text: "Suggest changes to this page", // }, // diff --git a/DjangoAdmin_FastAPI_AntdVue/.vitepress/config/extract.d.mts b/DjangoAdmin_FastAPI_AntdVue/.vitepress/config/extract.d.mts new file mode 100644 index 0000000..2a46233 --- /dev/null +++ b/DjangoAdmin_FastAPI_AntdVue/.vitepress/config/extract.d.mts @@ -0,0 +1,5 @@ +export declare const SITE_URL: string; +export declare const SITE_DESCRIPTION: string; +export declare function stripNumberPrefix(title: string): string; +export declare function extractDescription(md: string): string; +export declare function extractFaqs(md: string): { q: string; a: string }[]; diff --git a/DjangoAdmin_FastAPI_AntdVue/.vitepress/config/extract.mjs b/DjangoAdmin_FastAPI_AntdVue/.vitepress/config/extract.mjs new file mode 100644 index 0000000..7a3d926 --- /dev/null +++ b/DjangoAdmin_FastAPI_AntdVue/.vitepress/config/extract.mjs @@ -0,0 +1,130 @@ +/** + * SEO/GEO 共享工具（纯 ESM，零依赖）。 + * + * 同时被两类调用方 import： + * 1. VitePress 配置（.ts，esbuild 打包时内联本文件） + * 2. scripts/generate-llms-txt.mjs（Node 直接运行） + * + * 注意：SITE_URL 是全站唯一 URL 真相源。 + * docs 子域当前 TLS 证书为腾讯 CDN 默认证书（*.cdn.myqcloud.com，校验失败）， + * 故暂用 http；证书修复后只需改这里一处。 + */ + +export const SITE_URL = "http://docs.fastapi.antdvue.djangoadmin.cn"; + +export const SITE_DESCRIPTION = + "DjangoAdmin 企业级中台解决方案 - FastAPI + AntDesign 前后端分离版本"; + +/** + * 剥离 H1/标题中的章节编号前缀，用于 <title> 与 JSON-LD headline。 + * 例："5.10 字典模块" → "字典模块"；"K. 贡献指南" → "贡献指南"。 + * 页内 H1 与侧边栏编号保持不变，仅影响 SEO 输出。 + */ +export function stripNumberPrefix(title) { + return String(title) + .replace(/^(?:\d+(?:\.\d+)+|[A-Z]\.)\s+/, "") + .trim(); +} + +/** + * 从页面 Markdown 提取 meta description： + * 1. 首选 `:::tip xxx` 容器内的首句（141/143 页的标准 opener） + * 2. 回退到 H1 后的第一个普通段落 + * 输出压缩为单行、去除行内 Markdown，按中文句末标点截断（≤100 字符）。 + */ +export function extractDescription(md) { + const src = String(md); + const fm = src.match(/^---\r?\n([\s\S]*?)\r?\n---/); + const body = fm ? src.slice(fm[0].length) : src; + + let text = ""; + // frontmatter description 显式声明优先（无 H1 页面的补齐手段） + const fmDesc = fm && fm[1].match(/^description:\s*(.+)$/m); + if (fmDesc) { + text = fmDesc[1].trim().replace(/^["']|["']$/g, ""); + } + const tip = !text && body.match(/^:::\s*tip[^\n]*\n([\s\S]*?)\n:::/m); + if (tip) { + text = tip[1]; + } + if (!text) { + const afterH1 = body.match(/^# (?!#)(.+)$/m); + if (afterH1) { + const rest = body.slice((afterH1.index ?? 0) + afterH1[0].length); + const para = rest + .split(/\n{2,}/) + .find( + (p) => + p.trim() && + !/^\s*#/.test(p) && + !/^\s*:::/.test(p) && + !/^\s*```/.test(p) && + !/^\s*\|/.test(p), + ); + text = para || ""; + } + } + + text = text + .replace(/\s+/g, " ") + .replace(/`([^`]+)`/g, "$1") + .replace(/\*\*([^*]+)\*\*/g, "$1") + .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") + .trim(); + + if (!text) return ""; + + // 按中文句末标点截取首句，上限 100 字符；截断时避免切碎词 + const m = text.match(/^.{1,100}?(?:[。！？!?]|$)/); + let out = m ? m[0] : text.slice(0, 100); + if (out.length < text.length && !/[。！？!?]$/.test(out)) { + out = out.replace(/[^\s，、；：,;:]+$/, ""); + } + return out.trim() || text.slice(0, 100); +} + +function cleanText(s) { + return s + .replace(/^:::[^\n]*$/gm, "") + .replace(/^```[^\n]*$/gm, "") + .replace(/`([^`]+)`/g, "$1") + .replace(/\*\*([^*]+)\*\*/g, "$1") + .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") + .replace(/\s+/g, " ") + .trim(); +} + +/** + * 提取页面中的 Q/A 对（用于 FAQPage JSON-LD），支持两种站内格式： + * A. `### Q：问题` 标题式（如 zh/quickstart/faq.md） + * B. `**Q：问题**` 加粗式（如 zh/appendix/faq.md） + * 返回 [{ q, a }]；无匹配返回 []。 + */ +export function extractFaqs(md) { + const body = String(md).replace(/^---[\s\S]*?\n---\s*/, ""); + let faqs = []; + + // 格式 A：按 `### Q：` 切块，答案截断到下一个标题 + for (const part of body.split(/(?=^###\s*Q[：:])/m)) { + const m = part.match(/^###\s*Q[：:]\s*([^\n]+)\n+([\s\S]*)/); + if (!m) continue; + let a = m[2]; + const cut = a.search(/^#{1,4}\s/m); + if (cut >= 0) a = a.slice(0, cut); + faqs.push({ q: cleanText(m[1]), a: cleanText(a) }); + } + + // 格式 B：按 `**Q：` 切块 + if (!faqs.length) { + for (const part of body.split(/(?=^\*\*Q[：:])/m)) { + const m = part.match(/^\*\*Q[：:]\s*([^*]+)\*\*\s*\n+([\s\S]*)/); + if (!m) continue; + let a = m[2]; + const cut = a.search(/^(?:#{1,4}\s|\*\*Q)/m); + if (cut >= 0) a = a.slice(0, cut); + faqs.push({ q: cleanText(m[1]), a: cleanText(a) }); + } + } + + return faqs.filter((f) => f.q && f.a); +} diff --git a/DjangoAdmin_FastAPI_AntdVue/.vitepress/config/index.ts b/DjangoAdmin_FastAPI_AntdVue/.vitepress/config/index.ts index 2294856..6627a76 100644 --- a/DjangoAdmin_FastAPI_AntdVue/.vitepress/config/index.ts +++ b/DjangoAdmin_FastAPI_AntdVue/.vitepress/config/index.ts @@ -1,14 +1,22 @@ import { defineConfig } from "vitepress"; import { enConfig } from "./en"; +import { createSeoHooks } from "./seo"; import { sharedConfig } from "./shared"; import { zhConfig } from "./zh"; +const seo = createSeoHooks(zhConfig.themeConfig?.sidebar); + export default defineConfig({ ...sharedConfig, ignoreDeadLinks: [ (link) => link.includes('localhost'), ], + // SEO：页面级 title/description、canonical/OG/JSON-LD、sitemap+lastmod + transformPageData: seo.transformPageData, + transformHead: seo.transformHead, + sitemap: seo.sitemap, + locales: { root: { label: "简体中文", lang: "zh-CN", link: "/", ...zhConfig }, // root: { label: "English", lang: "en-US", link: "/", ...enConfig }, diff --git a/DjangoAdmin_FastAPI_AntdVue/.vitepress/config/seo.ts b/DjangoAdmin_FastAPI_AntdVue/.vitepress/config/seo.ts new file mode 100644 index 0000000..dbf5e64 --- /dev/null +++ b/DjangoAdmin_FastAPI_AntdVue/.vitepress/config/seo.ts @@ -0,0 +1,311 @@ +/** + * SEO/GEO 构建期钩子（仅 Node 构建时运行，不进客户端 bundle）： + * - transformPageData：每页独立 title（去编号前缀）与 description（取 :::tip 首句） + * - transformHead：canonical / Open Graph / twitter 卡片 / JSON-LD 结构化数据 + * - sitemap.transformItems：注入 lastmod（git 最后提交时间）并过滤 404 + * + * 由 config/index.ts 通过 createSeoHooks(zhConfig.themeConfig?.sidebar) 挂载。 + * 依赖 extract.mjs（纯 ESM，同被 scripts/generate-llms-txt.mjs 复用）。 + */ +import fs from "node:fs"; +import path from "node:path"; +import { execSync } from "node:child_process"; +import { + SITE_URL, + extractDescription, + extractFaqs, + stripNumberPrefix, +} from "./extract.mjs"; + +/** 与 vitepress HeadConfig 同构：[tag, attrs, innerHTML?] */ +type HeadTuple = [string, Record<string, any>, string?]; + +interface SideItem { + text?: string; + link?: string; + items?: SideItem[]; +} + +interface PageDataLike { + relativePath?: string; + title?: string; + description?: string; + frontmatter?: Record<string, any>; + [k: string]: any; +} + +interface TransformCtx { + pageData?: PageDataLike; + title?: string; + description?: string; + content?: string; + siteConfig?: { root?: string; srcDir?: string }; +} + +const ORG = { + "@type": "Organization", + name: "DjangoAdmin", + url: "https://www.djangoadmin.cn", + logo: `${SITE_URL}/logo.png`, + sameAs: [ + "https://gitee.com/djangoadmin/DjangoAdmin_FastAPI_AntdVue", + "https://www.djangoadmin.cn", + ], +}; + +/** 相对路径 → 站内路由（cleanUrls 关闭，正文页带 .html） */ +function routeOf(relativePath: string): string { + if (relativePath === "index.md") return "/"; + if (relativePath === "404.md") return "/404.html"; + return `/${relativePath.replace(/\.md$/, ".html")}`; +} + +/** 去掉侧边栏文案前导 emoji/符号，保留 "1.1 项目介绍" 这类编号文字 */ +function cleanLabel(s?: string): string { + return (s || "").replace(/^[^\p{L}\p{N}]+/u, "").trim(); +} + +/** 从侧边栏构建 route → 面包屑文案链（含分组小节） */ +function buildCrumbMap(sidebar: unknown): Map<string, string[]> { + const map = new Map<string, string[]>(); + const groups: SideItem[] = Array.isArray(sidebar) + ? sidebar + : ((sidebar as Record<string, SideItem[]>)?.["/zh/"] ?? []); + const walk = (items: SideItem[], trail: string[]) => { + for (const item of items) { + if (item.link && item.link.startsWith("/")) { + map.set(item.link, [...trail, cleanLabel(item.text)]); + } else if (item.items?.length) { + walk(item.items, [...trail, cleanLabel(item.text)]); + } + } + }; + for (const group of groups) { + walk(group.items ?? [], [cleanLabel(group.text)].filter(Boolean)); + } + return map; +} + +/** 从渲染后的 HTML 提取 H1 纯文本（JSON-LD headline 须与页面 H1 一致） */ +function h1OfHtml(html?: string): string { + const m = (html || "").match(/<h1[^>]*>([\s\S]*?)<\/h1>/i); + if (!m) return ""; + return m[1] + .replace(/<[^>]+>/g, "") + .replace(/&/g, "&") + .replace(/</g, "<") + .replace(/>/g, ">") + .replace(/"/g, '"') + .replace(/'/g, "'") + .trim(); +} + +/** 从 Markdown 源提取 H1 纯文本（去除行内 markdown 标记） */ +function h1OfMd(md: string): string { + // 围栏感知：跳过 ``` 代码块内的 # 注释，取真正的页面 H1 + let inFence = false; + for (const line of md.split("\n")) { + if (line.startsWith("```")) { inFence = !inFence; continue; } + if (!inFence && /^# (?!#)/.test(line)) { + return line + .replace(/^# /, "") + .replace(/`([^`]+)`/g, "$1") + .replace(/\*\*([^*]+)\*\*/g, "$1") + .trim(); + } + } + return ""; +} + +export function createSeoHooks(sidebar: unknown) { + const crumbs = buildCrumbMap(sidebar); + const projectDirs: string[] = []; + let gitDates: Map<string, string> | null = null; + + const readMd = (relativePath: string, srcDir?: string): string => { + try { + return fs.readFileSync( + path.resolve(srcDir || process.cwd(), relativePath), + "utf8", + ); + } catch { + return ""; + } + }; + + /** + * 项目内每个文件最后一次 git 提交的 ISO 时间。 + * 单次 git log 调用构建全量映射（key = 相对路径，与 pageData.relativePath 一致）； + * git 不可用时静默降级（sitemap 无 lastmod、JSON-LD 无 dateModified）。 + */ + const getGitDates = (root: string): Map<string, string> => { + if (gitDates) return gitDates; + gitDates = new Map<string, string>(); + try { + const out = execSync( + "git log --format=:::%cI --name-only --relative -n 500 -- .", + { + cwd: root, + encoding: "utf8", + maxBuffer: 64 * 1024 * 1024, + stdio: ["ignore", "pipe", "ignore"], + }, + ); + let current = ""; + for (const line of out.split(/\r?\n/)) { + if (line.startsWith(":::")) { + current = line.slice(3).trim(); + continue; + } + const file = line.trim(); + if (file && current && !gitDates.has(file)) { + gitDates.set(file, current); + } + } + } catch { + // 降级：无 lastmod / dateModified + } + return gitDates; + }; + + /** 每页独立 title（去 "5.10 " 编号前缀，关键词前置）与 description（:::tip 首句） */ + function transformPageData(pageData: PageDataLike, ctx?: any): Record<string, unknown> { + const srcDir: string | undefined = ctx?.siteConfig?.srcDir; + const root: string | undefined = ctx?.siteConfig?.root; + if (root && !projectDirs.includes(root)) projectDirs.push(root); + + const out: Record<string, unknown> = {}; + const rel = pageData.relativePath; + if (rel && !pageData.frontmatter?.description) { + const desc = extractDescription(readMd(rel, srcDir)); + if (desc) out.description = desc; + } + if (pageData.title) { + out.title = stripNumberPrefix(pageData.title); + } + return out; + } + + /** 构建期注入 canonical / OG / twitter / JSON-LD */ + function transformHead(ctx: TransformCtx): HeadTuple[] { + const rel = ctx?.pageData?.relativePath || ""; + if (!rel || rel === "404.md") return []; + + const route = routeOf(rel); + const url = `${SITE_URL}${route}`; + const title = ctx.pageData?.title || ctx.title || ""; + const desc = ctx.description || ""; + const isHome = rel === "index.md"; + const image = `${SITE_URL}/logo.png`; + + const heads: HeadTuple[] = [ + ["link", { rel: "canonical", href: url }], + ["meta", { property: "og:type", content: isHome ? "website" : "article" }], + ["meta", { property: "og:site_name", content: "DjangoAdmin" }], + ["meta", { property: "og:locale", content: "zh_CN" }], + ["meta", { property: "og:title", content: title }], + ["meta", { property: "og:description", content: desc }], + ["meta", { property: "og:url", content: url }], + ["meta", { property: "og:image", content: image }], + ["meta", { property: "twitter:title", content: title }], + ["meta", { property: "twitter:description", content: desc }], + ["meta", { property: "twitter:url", content: url }], + ["meta", { property: "twitter:image", content: image }], + ]; + + // ---- JSON-LD ---- + const root = ctx.siteConfig?.root || projectDirs[0] || process.cwd(); + const srcDir = ctx.siteConfig?.srcDir || root; + const lastMod = getGitDates(root).get(rel); + const blocks: Record<string, any>[] = []; + + if (isHome) { + blocks.push({ + "@context": "https://schema.org", + "@type": "WebSite", + name: "DjangoAdmin 开发文档", + url: `${SITE_URL}/`, + inLanguage: "zh-CN", + description: desc, + }); + blocks.push({ "@context": "https://schema.org", ...ORG }); + } else { + const md = readMd(rel, srcDir); + const article: Record<string, any> = { + "@context": "https://schema.org", + "@type": "TechArticle", + headline: h1OfMd(md) || h1OfHtml(ctx.content) || title, + description: desc, + url, + inLanguage: "zh-CN", + mainEntityOfPage: { "@type": "WebPage", "@id": url }, + publisher: ORG, + }; + if (lastMod) article.dateModified = lastMod; + blocks.push(article); + + const trail = crumbs.get(route); + if (trail?.length) { + const items: Record<string, any>[] = [ + { "@type": "ListItem", position: 1, name: "首页", item: `${SITE_URL}/` }, + ]; + trail.forEach((name, i) => { + const node: Record<string, any> = { + "@type": "ListItem", + position: i + 2, + name, + }; + if (i === trail.length - 1) node.item = url; + items.push(node); + }); + blocks.push({ + "@context": "https://schema.org", + "@type": "BreadcrumbList", + itemListElement: items, + }); + } + + const faqs = extractFaqs(md); + if (faqs.length) { + blocks.push({ + "@context": "https://schema.org", + "@type": "FAQPage", + mainEntity: faqs.map((f) => ({ + "@type": "Question", + name: f.q, + acceptedAnswer: { "@type": "Answer", text: f.a }, + })), + }); + } + } + + // 转义 "<"，防止内容中出现 </script> 破坏注入 + const json = JSON.stringify(blocks).replace(/</g, "\\u003c"); + heads.push(["script", { type: "application/ld+json" }, json]); + return heads; + } + + /** sitemap.xml：过滤 404/README，注入 git lastmod */ + const sitemap = { + hostname: SITE_URL, + transformItems(items: { url: string; lastmod?: string }[]) { + const root = projectDirs[0] || process.cwd(); + const dates = getGitDates(root); + const out: { url: string; lastmod?: string }[] = []; + for (const item of items) { + // ⚠ vitepress 传入的 item.url 是相对路径（"404.html"、"zh/x.html"、""）， + // 无前导斜杠也无域名——hostname 由 SitemapStream 事后拼接。 + if (/(^|\/)404\.html$/.test(item.url)) continue; // 404 页不收录 + if (/(^|\/)README\.html$/.test(item.url)) continue; // 仓库 README 非文档页 + const p = item.url.replace(/^\//, ""); + const rel = + p === "" || p === "index.html" ? "index.md" : p.replace(/\.html$/, ".md"); + const lastmod = dates.get(rel); + out.push(lastmod ? { ...item, lastmod } : item); + } + return out; + }, + }; + + return { transformPageData, transformHead, sitemap }; +} diff --git a/DjangoAdmin_FastAPI_AntdVue/.vitepress/config/shared.ts b/DjangoAdmin_FastAPI_AntdVue/.vitepress/config/shared.ts index 44fad76..1ef3d21 100644 --- a/DjangoAdmin_FastAPI_AntdVue/.vitepress/config/shared.ts +++ b/DjangoAdmin_FastAPI_AntdVue/.vitepress/config/shared.ts @@ -1,6 +1,6 @@ import { defineConfig, HeadConfig } from "vitepress"; -export const META_IMAGE = "/social.png"; +export const META_IMAGE = "/logo.png"; const rControl = /[\u0000-\u001f]/g; const rSpecial = /[\s~`!@#$%^&*()\-_+=[\]{}|\\;:"'“”‘’<>,.?/]+/g; @@ -23,6 +23,8 @@ export const slugify = (str: string): string => export const sharedConfig = defineConfig({ title: "小蚂蚁云", + // 页面 <title> 后缀：「环境准备 | DjangoAdmin 开发文档」（index.md frontmatter 可覆盖） + titleTemplate: "DjangoAdmin 开发文档", appearance: "light", markdown: { diff --git a/DjangoAdmin_FastAPI_AntdVue/.vitepress/config/zh.ts b/DjangoAdmin_FastAPI_AntdVue/.vitepress/config/zh.ts index 86b4209..e679e32 100644 --- a/DjangoAdmin_FastAPI_AntdVue/.vitepress/config/zh.ts +++ b/DjangoAdmin_FastAPI_AntdVue/.vitepress/config/zh.ts @@ -1,8 +1,9 @@ import type { DefaultTheme, LocaleSpecificConfig } from "vitepress"; -export const META_URL = "https://www.djangoadmin.cn"; -export const META_TITLE = "企业级中台解决方案"; -export const META_DESCRIPTION = "企业级中台解决方案"; +export const META_URL = "http://docs.fastapi.antdvue.djangoadmin.cn"; +export const META_TITLE = "DjangoAdmin FastAPI+AntDesign 开发文档"; +export const META_DESCRIPTION = + "DjangoAdmin 企业级中台解决方案 - FastAPI + AntDesign 前后端分离版本"; export const zhConfig: LocaleSpecificConfig<DefaultTheme.Config> = { description: META_DESCRIPTION, diff --git a/DjangoAdmin_FastAPI_AntdVue/404.md b/DjangoAdmin_FastAPI_AntdVue/404.md new file mode 100644 index 0000000..c344b20 --- /dev/null +++ b/DjangoAdmin_FastAPI_AntdVue/404.md @@ -0,0 +1,12 @@ +--- +head: + - - meta + - name: robots + content: noindex +--- + +# 页面不存在 + +抱歉，您访问的页面不存在或已被移动。 + +[返回首页](/) · [浏览文档](/zh/introduction) diff --git a/DjangoAdmin_FastAPI_AntdVue/package.json b/DjangoAdmin_FastAPI_AntdVue/package.json index 77bd941..b5517ed 100644 --- a/DjangoAdmin_FastAPI_AntdVue/package.json +++ b/DjangoAdmin_FastAPI_AntdVue/package.json @@ -5,7 +5,8 @@ "type": "module", "scripts": { "docs": "vitepress dev .", - "docs:build": "vitepress build .", + "docs:llms": "node scripts/generate-llms-txt.mjs", + "docs:build": "node scripts/generate-llms-txt.mjs && vitepress build .", "docs:preview": "vitepress preview ." }, "dependencies": { diff --git a/DjangoAdmin_FastAPI_AntdVue/public/llms.txt b/DjangoAdmin_FastAPI_AntdVue/public/llms.txt new file mode 100644 index 0000000..544fa5d --- /dev/null +++ b/DjangoAdmin_FastAPI_AntdVue/public/llms.txt @@ -0,0 +1,159 @@ +# DjangoAdmin FastAPI+AntDesign 开发文档 + +> DjangoAdmin 企业级中台解决方案 - FastAPI + AntDesign 前后端分离版本。内置 RBAC 权限体系、代码生成器等开箱即用功能，支持五种数据库一键切换。本文档共 129 篇，按章节组织。 + +## 1. 了解项目 + +- [1.1 项目介绍](http://docs.fastapi.antdvue.djangoadmin.cn/zh/introduction.html): DjangoAdmin 是企业级中台解决方案，后端基于 FastAPI + SQLAlchemy，前端基于 Vue3 + AntDesign，内置 RBAC 权限、代码生成器等开箱即用功能， +- [更新日志](http://docs.fastapi.antdvue.djangoadmin.cn/zh/changelog.html): 更新日志是项目演进的完整记录，帮助开发者和企业了解每个版本的能力变化与技术演进方向。 +- [新手入门指南](http://docs.fastapi.antdvue.djangoadmin.cn/zh/course.html): 详细的安装步骤请参考 环境准备 章节。 +- [项目目录结构](http://docs.fastapi.antdvue.djangoadmin.cn/zh/struct.html): 本页说明项目前后端目录组织与各目录职责，二次开发定位文件或了解工程结构时对照查阅。 +- [为什么选择我们？](http://docs.fastapi.antdvue.djangoadmin.cn/zh/why.html): 本框架提供开箱即用的企业级中台完整解决方案，免去从零搭建成本，助力中大型企业构建统一的数字化基座。 + +## 2. 快速入门 + +- [后端启动](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume1/backend.html): 启动后端前，请确保已完成 环境准备 章节中的所有软件安装。 +- [数据库初始化](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume1/database.html): 数据库初始化前，请确保已完成以下准备工作： 1. 目标数据库服务已启动（如 MySQL 8.0+） 2. .env 文件中的 DB_DRIVER 和数据库连接信息已正确配置 3. Python +- [Docker 一键启动](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume1/docker.html): 使用 Docker 方式启动前，请确保已安装以下软件： 1. Docker Desktop（Windows / macOS）或 Docker Engine（Linux） 2. Docker +- [环境变量速查表](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume1/env-vars.html): 1. .env.example 是环境变量模板文件，已提交到版本控制。 +- [环境准备](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume1/environment.html): 1. 部分软件安装后需要设置本地环境变量，便于在终端中使用命令。 +- [常见问题FAQ](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume1/faq.html): 遇到问题时，建议先查看终端日志输出和浏览器控制台（F12）的错误信息，通常能快速定位问题原因。 +- [第一个接口调试](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume1/first-api.html): 开始调试前，请确保已完成以下步骤： 1. 后端服务已启动（参见 后端启动） 2. 数据库已初始化（参见 数据库初始化） 3. Redis 服务已启动 +- [前端启动](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume1/frontend.html): 启动前端前，请确保已完成 环境准备 章节中的 Node.js 和 pnpm 安装，并已启动后端服务（参见 后端启动）。 + +## 3. 模块开发实战 + +- [完整代码清单](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume2/code-list.html): 本页汇总岗位管理（Position）模块涉及的全部文件代码，开发时可快速查阅与复制对照。 +- [Endpoint 层](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume2/endpoint.html): Endpoint 层是 HTTP 接口层，负责定义路由、权限装饰器与请求参数绑定，编写新接口从本页开始。 +- [常见问题与排错](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume2/faq.html): 本页汇总模块开发过程中的常见问题与排错方法，开发受阻时按症状索引即可定位。 +- [前端 API 层](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume2/fe-api.html): 前端 API 层封装后端接口的 HTTP 请求，每个业务模块对应一个 API 文件，本页讲解基于 Axios 封装的编写规范。 +- [前端路由与菜单](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume2/fe-router.html): 本页讲解前端路由与菜单机制——路由和菜单由后端动态返回，前端只需注册路由组件映射。 +- [前端页面视图](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume2/fe-view.html): 前端页面视图是用户直接交互的界面，本页讲解 Vue3 + AntDesign Vue 下一个完整 CRUD 页面的文件组成与编写方式。 +- [数据模型（Model）](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume2/model.html): 实际开发中不需要手写 DDL。 +- [概述与目标](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume2/overview.html): 其中 id、create_user、create_time、update_user、update_time、is_delete 由基类 base_model 自动提供，业务字段仅需定义 name、 +- [权限节点配置](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume2/permission.html): 实际开发中，查询类权限（page、detail、list）通常合并为一个节点 sys:position:list，减少配置工作量。 +- [Repository 层](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume2/repository.html): Repository 层是数据访问层，封装全部数据库查询操作，本页讲解基于 BaseRepository 基类的通用 CRUD 用法。 +- [路由注册](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume2/router.html): 路由注册是将模块 Endpoint 挂载到应用的过程，本页讲解在 router.py 中统一注册模块路由的方法。 +- [Pydantic Schema](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume2/schema.html): Schema 层负责请求数据校验，本页讲解基于 Pydantic v2 BaseModel 与 Field 的表单类定义规范。 +- [Service 层](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume2/service.html): Service 层是业务逻辑层，本页讲解基于 BaseService 基类声明差异点即可获得完整增删改查能力的编写方式。 + +## 4. 架构设计 + +- [核心基类体系](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume3/base-classes.html): 五大基类各司其职，覆盖从数据模型到请求校验再到业务逻辑的完整链路。 +- [缓存架构设计](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume3/cache.html): 采用两级缓存架构：第一级为进程内字典缓存（dict_util），第二级为 Redis 分布式缓存。 +- [数据库设计](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume3/database-design.html): 所有业务表继承 base_model 基类，自动获得 6 个通用字段（id / create_user / create_time / update_user / update_time / +- [目录结构设计](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume3/directory.html): 目录结构遵循「按功能分组、按职责分层」的原则。 +- [扩展性设计](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume3/extensibility.html): 遵循开闭原则（OCP）：对扩展开放，对修改关闭。 +- [分层架构设计](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume3/layer-arch.html): 采用经典的三层架构，核心原则是：依赖单向、职责单一、接口隔离。 +- [整体架构图](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume3/overview.html): 遵循以下架构设计原则，确保系统在长期演进中保持高质量和可维护性： +- [请求完整链路](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume3/request-flow.html): 一个典型的 API 请求经过以下阶段：浏览器 → Nginx → CORS → 限流 → 上传体积限制 → 请求计时 → Token 续签 → 操作日志 → DB 会话 → Redis 注入 → +- [安全架构设计](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume3/security.html): 纵深防御：认证、授权、限流、参数校验多层防护，单一防线失效时仍有其他机制兜底 最小权限：用户仅能访问已授权接口，角色权限按需分配，遵循"够用即可"原则 数据不落地：敏感信息（Token、 +- [同步/异步设计决策](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume3/sync-async.html): FastAPI 基于 ASGI 异步框架，但并非所有端点都需要 async def。 +- [技术选型说明](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume3/tech-stack.html): FastAPI 基于 ASGI 原生异步、类型提示驱动的自动文档、Pydantic v2 的高性能校验，使其在构建 RESTful API 时具有显著优势。 + +## 5. 开发指南 + +- [API 接口速查表](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/api-cheatsheet.html): API 接口速查表，按模块分组列出所有 RESTful 接口的请求方法、路径、说明和权限标识。 +- [文章管理](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/business/article.html): 文章管理模块支持富文本编辑、分类关联、封面图片上传、图集管理等功能。 +- [分类管理](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/business/category.html): 分类管理模块用于管理树形分类数据，如文章分类、产品分类等。 +- [公告与链接管理](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/business/content.html): 公告、链接、城市是三个简单 CRUD 内容模块，均继承 BaseService，提供标准的增删改查接口。 +- [部门/职级/岗位管理](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/business/dept.html): 部门、职级、岗位是组织架构管理的三个核心模块。 +- [定时任务](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/business/job.html): 定时任务模块基于 APScheduler 实现，支持 Cron 表达式调度、任务执行日志、动态启停等功能。 +- [菜单管理](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/business/menu.html): 菜单管理是 RBAC 权限系统的基础，负责管理系统的导航菜单和权限节点。 +- [参数管理](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/business/param.html): 参数管理模块用于管理动态系统参数，与系统配置模块类似但更侧重于业务参数的灵活配置。 +- [角色管理](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/business/role.html): 角色是 RBAC 权限模型的核心，连接用户和菜单（权限）。 +- [用户管理](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/business/user.html): 用户管理是系统的核心模块，属于复杂业务模块。 +- [认证流程实战](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/core/auth-flow.html): 登录 → Token 获取 → 权限校验 → Token 刷新 → 退出登录的完整认证链路实战说明。 +- [验证码机制](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/core/captcha.html): 验证码是防止自动化攻击的重要安全手段。 +- [系统配置管理](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/core/config.html): 系统配置模块用于管理动态的键值对配置项，与数据字典类似但更偏向系统级参数。 +- [跨域资源共享（CORS）](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/core/cors.html): CORS（Cross-Origin Resource Sharing）跨域资源共享是前后端分离架构必须处理的问题。 +- [演示模式](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/core/demo-mode.html): 演示模式用于在线体验环境，开启后所有写操作（新增、编辑、删除等）将被拦截，返回"演示环境，暂无操作权限"提示。 +- [数据字典使用指南](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/core/dict-guide.html): 数据字典的完整使用流程，从新增字典类型到在代码中使用字典数据的实操指南。 +- [字典模块](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/core/dict.html): 数据字典用于管理系统中的枚举值和配置项，如状态、类型、性别等。 +- [异常与响应处理](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/core/exception.html): 定义了统一的响应格式和全局异常处理机制。 +- [防重复提交](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/core/idempotent.html): 防重复提交是保障数据一致性的重要措施。 +- [用户认证（JWT）](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/core/jwt.html): JWT（JSON Web Token）是的核心认证机制。 +- [登录日志](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/core/login-log.html): 登录日志记录每次登录尝试（成功/失败），包含登录账号、IP地址、浏览器信息、登录时间等。 +- [操作日志](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/core/operation-log.html): 操作日志中间件自动拦截写请求（POST/PUT/DELETE/PATCH）并记录操作日志，无需手动埋点。 +- [请求限流](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/core/rate-limit.html): 请求限流中间件基于 Redis 实现 IP 级别的滑动窗口限流，防止恶意请求和 DoS 攻击。 +- [权限管理（RBAC）](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/core/rbac.html): 采用基于角色的访问控制（RBAC）模型，通过用户-角色-菜单三层关系实现细粒度的权限管理。 +- [参数验证（Pydantic）](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/core/validator.html): 使用 Pydantic v2 进行请求参数验证。 +- [API 层开发](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/frontend/api.html): 前端 API 层位于 src/api/ 目录，封装所有与后端的 HTTP 请求。 +- [前端构建](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/frontend/build.html): 前端使用 Vite 构建，支持开发服务器和生产构建。 +- [公共组件库](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/frontend/components.html): 项目提供丰富的公共组件，位于 ui/src/components/ 目录，基于 AntDesign Vue 二次封装，覆盖表格、表单、弹窗、上传、富文本编辑等常见场景。 +- [BasicForm 表单](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/frontend/form.html): BasicForm 位于 src/components/Form/src/BasicForm.vue，基于 AntDesign Vue 的 a-form 二次封装，通过 schemas +- [Hooks 组合式函数](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/frontend/hooks.html): 项目封装了一系列组合式函数（Hooks），位于 src/hooks/ 和 src/utils/ 目录，提供权限检查、异步 loading、防重复提交、实时时钟、项目配置等可复用逻辑。 +- [国际化](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/frontend/i18n.html): 当前项目仅支持中文界面，AntDesign Vue 使用中文语言包（zh-cn），所有界面文本直接硬编码在组件中。 +- [Modal 弹窗](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/frontend/modal.html): 项目提供 BasicModal 组件（src/components/Modal/src/BasicModal.vue）和原生 a-modal 两种弹窗用法。 +- [权限指令 v-perm](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/frontend/perm-directive.html): v-perm 和 v-perms 是项目自定义的 Vue 指令，用于按钮级别的权限控制，无权限时自动从 DOM 中移除元素。 +- [路由与菜单](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/frontend/router.html): 前端路由基于 Vue Router 4 实现动态路由生成，菜单数据从后端获取，通过 generator-routers.ts 递归生成路由表，路由守卫控制登录状态和权限。 +- [前端环境与结构](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/frontend/setup.html): 前端基于 Vue3 + AntDesign Vue 构建，使用 pnpm 作为包管理工具，Vite 作为构建工具，TypeScript 作为开发语言。 +- [Store 状态管理](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/frontend/store.html): 前端使用 Pinia 进行状态管理，核心模块包括 user（用户信息与权限）、asyncRoute（动态路由与菜单）、projectSetting（项目配置）、designSetting（主题设计）等。 +- [样式与主题](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/frontend/style.html): 前端样式方案采用 Tailwind CSS + SCSS + AntDesign Vue 主题覆盖，支持深色模式切换。 +- [BasicTable 表格](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/frontend/table.html): BasicTable 位于 src/components/Table/src/Table.vue，基于 AntDesign Vue 的 a-table 二次封装，提供列定义、数据请求、分页、操作列、 +- [工具函数](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/frontend/utils.html): 前端工具函数位于 src/utils/ 目录，提供认证管理、本地存储、日期格式化、树结构操作、文件下载等通用能力。 +- [页面视图开发](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/frontend/view.html): 页面视图位于 src/views/ 目录，每个业务模块遵循 index.vue（列表页）+ edit.vue（编辑弹窗）的标准模式，辅以 columns.ts（列定义）和 +- [接口响应规范](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/integration/api-contract.html): 后端所有接口统一返回 R.ok() / R.failed() 格式的 JSON 响应，前端通过 VAxios 的 transformRequestData 拦截器统一解包处理。 +- [字典数据联调](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/integration/dict-sync.html): 字典数据通过后端字典 API 获取，前端在下拉选择器中渲染选项。 +- [权限节点联动](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/integration/perm-sync.html): 前后端权限通过统一的权限节点字符串联动，后端 @permission_required 校验权限，前端 v-perm 指令和 TableAction 的 auth 属性控制按钮显示。 +- [代理配置](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/integration/proxy.html): 开发环境通过 Vite 代理转发 API 请求到后端，生产环境通过 Nginx 代理。 +- [文件上传联调](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/integration/upload-sync.html): 文件上传涉及前端 Upload 组件、后端上传接口和 URL 拼接三个环节，需要前后端协同配置。 +- [数据库会话](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/tools/db-session.html): 通过 contextvars + Starlette 中间件实现请求级数据库会话管理，写操作按业务成功与否自动 commit/rollback。 +- [导入导出](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/tools/excel.html): 基于 openpyxl 实现 Excel 导入导出功能，支持通过 file_template 模块管理导入模板配置。 +- [IP/UA 解析](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/tools/ip-ua.html): 提供客户端 IP 获取、IP 地理位置查询和 User-Agent 解析三大能力。 +- [日志系统](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/tools/logger.html): 通过 Python 标准库 logging 实现结构化日志，支持控制台 + 文件双输出，日志文件按大小自动轮转。 +- [密码工具](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/tools/password.html): 采用 bcrypt 双重加盐方案存储密码，源码位于 src/core/password.py。 +- [权限缓存](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/tools/perm-cache.html): 通过 Redis 实现用户权限和菜单的缓存，采用用户级缓存 + 全局版本号双层策略。 +- [请求解析工具](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/tools/request-util.html): src/utils/request.py 提供请求数据解析相关的工具函数，包括批量 ID 解析、SQL LIKE 安全处理、分页参数解析等。 +- [富文本过滤](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/tools/rich-text.html): 富文本编辑器内容存在存储型 XSS 风险，通过 bleach 库实现 HTML 白名单清洗，在落盘前统一过滤危险内容。 +- [文件上传完整流程](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/tools/upload-guide.html): 富文本编辑器（如 TinyMCE、CKEditor、WangEditor 等）的图片上传同样使用此接口。 +- [文件上传](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume4/tools/upload.html): 提供本地文件上传功能，支持图片和通用文件上传，内置扩展名白名单、大小限制、魔术字节校验和路径遍历防护。 + +## 6. 代码生成器 + +- [CLI 命令行使用](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume5/cli.html): 代码生成器 CLI 模式的使用方法，包括单表生成、批量生成、预览模式和配置导出。 +- [代码生成引擎](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume5/code-engine.html): 代码生成引擎的工作原理，包括配置解析、模板渲染、文件写入和自动注册的完整流程。 +- [配置文件详解](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume5/config.html): 代码生成器 JSON 配置文件的格式说明，包括模块名称、字段属性、字典编码等配置项的详细解释。 +- [实战案例](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume5/demo.html): 以 fastapi_example 演示表为完整案例，演示从建表到生成到使用的全流程。 +- [常见问题](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume5/faq.html): 代码生成器使用过程中常见问题的原因分析和解决方案。 +- [概述与架构](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume5/overview.html): 代码生成器的整体架构、核心模块和生成流程概述。 +- [表结构解析引擎](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume5/parser.html): 表结构解析引擎的工作原理，从数据库读取表元数据并智能推断字段用途的过程。 +- [自定义模板](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume5/templates.html): 代码生成器模板的 Jinja2 语法说明，包括模板变量、字段属性和自定义模板的开发方法。 +- [Web 管理界面](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume5/web-ui.html): 代码生成器 Web 管理界面的使用方法，通过可视化界面操作单表生成和批量生成。 + +## 7. 运维部署 + +- [备份与恢复](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume6/backup.html): - 3 份数据副本（1 份生产 + 2 份备份） - 2 种不同存储介质（如本地磁盘 + 远程存储） - 1 份异地备份（防机房级灾难） +- [数据库迁移](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume6/db-migrate.html): - 结构迁移：Alembic（自动生成 DDL 差异） - 数据迁移：scripts/migrate_db.py（跨库数据泵） - 初始化：scripts/init_db.py（全新安装一键建库） +- [部署 Checklist](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume6/deploy-checklist.html): 从服务器准备到应用上线的完整部署操作清单，适用于生产环境首次部署和后续版本更新。 +- [Docker容器化](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume6/docker.html): - 环境一致性：消除"在我机器上能跑"的问题 - 快速部署：一条命令启动完整服务 - 资源隔离：应用与宿主机环境解耦 +- [环境规划](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume6/env-plan.html): 各环境之间保持代码一致，仅通过环境变量（.env）区分配置。 +- [健康检查与监控](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume6/monitoring.html): `` 1. 应用层：健康检查端点、业务指标 2. 系统层：CPU/内存/磁盘/网络 3. 中间件：MySQL/Redis 连接状态 4. 日志：集中式日志收集与分析 `` +- [Nginx 反向代理](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume6/nginx.html): `` 客户端 → Nginx（80/443） ├─ / → 前端静态资源（dist/） ├─ /api/v1/... → FastAPI 后端（8031） └─ /api/file/ → +- [性能调优](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume6/performance.html): 1. 先测量，后优化：用数据说话，避免盲目调参 2. 瓶颈优先：找到最大瓶颈，集中优化 3. 渐进式：每次只调整一个参数，观察效果 +- [安全加固](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume6/security-hardening.html): - 最小权限：只开放必要的端口和权限 - 纵深防御：多层安全措施叠加 - 默认安全：配置默认值应为安全选项 +- [Supervisor进程管理](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume6/supervisor.html): - Linux 服务器直接部署（非 Docker） - 需要进程自动重启和日志轮转 - 管理多个相关进程 +- [故障排查手册](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume6/troubleshooting.html): 1. 查看日志：tail -f logs/supervisor.out.log 或 docker-compose logs -f 2. 检查配置：.env 文件、数据库连接、Redis 连接 3. +- [版本升级流程](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume6/upgrade.html): 1. 先备份，后升级 2. 先测试环境，后生产环境 3. 每次升级可回滚 4. 低峰期执行升级 + +## 8. 规范标准 + +- [API响应规范](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume7/api-response.html): - 所有接口必须通过 R.ok() 或 R.failed() 返回，禁止直接返回 dict - 成功响应 code=0，失败响应 code=1 - 响应体始终包含 code、data、msg、ok +- [代码审查清单](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume7/code-review.html): - 每次提交必须经过至少一人审查 - 审查关注点：正确性 > 安全性 > 可维护性 > 性能 - 审查意见应具体、可操作，避免主观评价 +- [删除规范](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume7/deletion.html): - is_delete = 0：正常记录（默认值） - is_delete = 1：已删除记录 - 所有查询方法自动过滤 is_delete = 0，业务层无需关心 +- [文档规范](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume7/doc-standard.html): - 文档与代码同步更新 - 使用中文编写（项目约定） - 示例代码可直接运行 +- [Endpoint层规范](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume7/endpoint.html): - Endpoint 只做请求分发，不含业务逻辑 - 通过装饰器控制权限和演示模式 - 委托 Service 处理业务逻辑 - 返回 R 封装的响应 +- [前端 API 规范](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume7/fe-api.html): - 每个后端模块对应一个 API 文件 - 函数命名统一使用 名词 + 动词 格式（与后端保持一致） - 请求路径使用相对路径（/position/page），不含 /api/v1 前缀（由 +- [前端页面规范](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume7/fe-component.html): - Vue3（Composition API + <script setup>） - AntDesign Vue 4.x - 自定义组件（BasicTable / BasicForm / +- [Git提交规范](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume7/git.html): `` <type>(<scope>): <subject> <body> <footer> `` +- [分页规范](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume7/pagination.html): - 前端传递 pageNo（页码，从 1 开始）和 pageSize（每页条数） - 后端返回 {records, total, size, current, pages} 结构 - 默认每页 10 +- [Pydantic Schema规范](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume7/pydantic.html): - 请求体参数必须声明为 Pydantic 模型（Form 类） - 字段约束使用 Field(...) 定义 - 自定义校验使用 @field_validator - 唯一性校验在 Schema +- [Repository层规范](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume7/repository.html): - Repository 只做数据访问原语，不处理 R 封装/序列化/业务逻辑 - 软删除由基类自动处理，子类无需关心 - 查询方法自动跳过 None 值条件 +- [Service层规范](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume7/service.html): BaseService 采用模板方法模式：基类定义流程骨架，子类通过声明差异点和覆盖钩子定制行为。 +- [测试规范](http://docs.fastapi.antdvue.djangoadmin.cn/zh/volume7/testing.html): 1. 契约测试（Contract）：验证路由、权限、表名等契约不变 2. 单元测试（Unit）：验证单个函数/方法的逻辑正确性 3. 集成测试（Integration）：验证模块间协作、真实数据库操作 + +## 附录 + +- [常见问题汇总](http://docs.fastapi.antdvue.djangoadmin.cn/zh/faq.html): 本页汇总了项目各模块的常见问题及解决方案，按场景分类索引。 +- [免责声明](http://docs.fastapi.antdvue.djangoadmin.cn/zh/other/declare.html): 使用本产品前必读的法律声明，明确产品性质、使用限制与责任划分，一旦使用本产品即视为接受本声明全部条款。 +- [广告赞助](http://docs.fastapi.antdvue.djangoadmin.cn/zh/other/sponsor.html): 1. 投放广告不得与官方全系产品存在结构性冲突和竞争 2. 广告内容需符合国家法律法规，不得包含虚假、误导性信息 3. 广告素材需经官方审核通过后方可上线，审核周期 1-3 个工作日 4. diff --git a/DjangoAdmin_FastAPI_AntdVue/public/robots.txt b/DjangoAdmin_FastAPI_AntdVue/public/robots.txt new file mode 100644 index 0000000..0c20f11 --- /dev/null +++ b/DjangoAdmin_FastAPI_AntdVue/public/robots.txt @@ -0,0 +1,33 @@ +# DjangoAdmin FastAPI+AntDesign 开发文档 +User-agent: * +Allow: / + +# 显式放行生成式引擎 / AI 爬虫（GEO） +User-agent: GPTBot +Allow: / + +User-agent: ChatGPT-User +Allow: / + +User-agent: ClaudeBot +Allow: / + +User-agent: Claude-Web +Allow: / + +User-agent: anthropic-ai +Allow: / + +User-agent: PerplexityBot +Allow: / + +User-agent: Google-Extended +Allow: / + +User-agent: Bytespider +Allow: / + +User-agent: bingbot +Allow: / + +Sitemap: http://docs.fastapi.antdvue.djangoadmin.cn/sitemap.xml diff --git a/DjangoAdmin_FastAPI_AntdVue/scripts/generate-llms-txt.mjs b/DjangoAdmin_FastAPI_AntdVue/scripts/generate-llms-txt.mjs new file mode 100644 index 0000000..170de52 --- /dev/null +++ b/DjangoAdmin_FastAPI_AntdVue/scripts/generate-llms-txt.mjs @@ -0,0 +1,122 @@ +#!/usr/bin/env node +/** + * 生成 public/llms.txt（llmstxt.org 标准）——AI 爬虫的站点摘要索引。 + * + * 数据源：zh 目录下全部 Markdown 的 H1 + :::tip 概述首句（与 meta + * description 同源，复用 .vitepress/config/extract.mjs）。按侧边栏章节分组。 + * + * 用法：node scripts/generate-llms-txt.mjs + * 已挂入 package.json 的 docs:build 前置步骤。 + */ +import fs from "node:fs"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; +import { + SITE_URL, + SITE_DESCRIPTION, + extractDescription, +} from "../.vitepress/config/extract.mjs"; + +const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."); +const ZH = path.join(ROOT, "zh"); + +/** 顶层目录 → 侧边栏章节名（与 .vitepress/config/zh.ts 保持一致） */ +const SECTIONS = [ + ["", "1. 了解项目"], + ["volume1", "2. 快速入门"], + ["volume2", "3. 模块开发实战"], + ["volume3", "4. 架构设计"], + ["volume4", "5. 开发指南"], + ["volume5", "6. 代码生成器"], + ["volume6", "7. 运维部署"], + ["volume7", "8. 规范标准"], + ["other", "附录"], +]; + +function walk(dir, out = []) { + for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { + const p = path.join(dir, entry.name); + if (entry.isDirectory()) walk(p, out); + else if (entry.name.endsWith(".md")) out.push(p); + } + return out; +} + +/** 提取首个 H1 文本 */ +function h1Of(md) { + // 围栏感知：跳过 ``` 代码块内的 # 注释，取真正的页面 H1 + let inFence = false; + for (const line of md.split("\n")) { + if (line.startsWith("```")) { inFence = !inFence; continue; } + if (!inFence && line.startsWith("# ") && !line.startsWith("## ")) { + return line.slice(2).trim(); + } + } + return ""; +} + +/** H1 编号排序键："5.10 x" → [5,10]；无编号排最后 */ +function sortKey(h1) { + const m = h1.match(/^(\d+(?:\.\d+)*)/); + if (m) return m[1].split(".").map(Number); + const letter = h1.match(/^([A-Z])\./); + if (letter) return [1000 + letter[1].charCodeAt(0)]; + return [9999]; +} + +function cmpKey(a, b) { + const len = Math.max(a.length, b.length); + for (let i = 0; i < len; i++) { + const x = a[i] ?? 0; + const y = b[i] ?? 0; + if (x !== y) return x - y; + } + return 0; +} + +const files = walk(ZH); +const groups = new Map(SECTIONS.map(([dir, label]) => [label, []])); + +for (const file of files) { + const rel = path.relative(ZH, file).replace(/\\/g, "/"); + const topDir = rel.includes("/") ? rel.split("/")[0] : ""; + const base = rel.split("/").pop(); + const label = (topDir === "" && base === "faq.md") ? "附录" + : SECTIONS.find(([dir]) => dir === topDir)?.[1] ?? "附录"; + + const md = fs.readFileSync(file, "utf8"); + const h1 = h1Of(md); + if (!h1) continue; + const desc = extractDescription(md); + const url = `${SITE_URL}/zh/${rel.replace(/\.md$/, ".html")}`; + groups.get(label).push({ h1, desc, url, key: sortKey(h1) }); +} + +const lines = [ + "# DjangoAdmin FastAPI+AntDesign 开发文档", + "", + `> ${SITE_DESCRIPTION}。内置 RBAC 权限体系、代码生成器等开箱即用功能，支持五种数据库一键切换。本文档共 ${files.length} 篇，按章节组织。`, + "", +]; + +// 按章节顺序输出，合并重复 label（appendix/other 同为「附录」，只输出一次） +const printed = new Set(); +for (const [, label] of SECTIONS) { + if (printed.has(label)) continue; + const items = groups.get(label); + if (!items?.length) continue; + printed.add(label); + + lines.push(`## ${label}`, ""); + items.sort((a, b) => cmpKey(a.key, b.key)); + for (const { h1, desc, url } of items) { + lines.push(desc ? `- [${h1}](${url}): ${desc}` : `- [${h1}](${url})`); + } + lines.push(""); +} + +const out = path.join(ROOT, "public", "llms.txt"); +fs.writeFileSync(out, lines.join("\n"), "utf8"); +console.log( + `llms.txt: ${files.length} 页 → ${path.relative(ROOT, out)} (${printed.size} 个章节)`, +); diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/course.md b/DjangoAdmin_FastAPI_AntdVue/zh/course.md index 0bbfe58..51fedf7 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/course.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/course.md @@ -1,3 +1,5 @@ +# 新手入门指南 + :::warning 特别提醒 官方精心制作本教程，目的在于方便用户快速掌握软件产品的使用和部署。通过此教程，刚入行的开发者也可以快速掌握并投入产品研发。本地部署时务必请耐心阅读文档操作。 ::: diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/introduction.md b/DjangoAdmin_FastAPI_AntdVue/zh/introduction.md index f31db1d..e7137b9 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/introduction.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/introduction.md @@ -1,3 +1,9 @@ +# 1.1 项目介绍 + +:::tip 概述 +DjangoAdmin 是企业级中台解决方案，后端基于 FastAPI + SQLAlchemy，前端基于 Vue3 + AntDesign，内置 RBAC 权限、代码生成器等开箱即用功能，支持五种数据库一键切换。 +::: + <div align="center"> <p align="center"> <img src="/logo.png" height="150" alt="logo"/> @@ -75,10 +81,10 @@ | Flask+ElementPlus前后端分离版 | 基于 Flask、SQLAlchemy、WTForms、Vue3、ElementPlus、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Flask_EleVue) | | Flask+AntDesign前后端分离版 | 基于 Flask、SQLAlchemy、WTForms、Vue3、AntDesign、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Flask_AntdVue) | | Flask+NaiveUI前后端分离版 | 基于 Flask、SQLAlchemy、WTForms、Vue3、NaiveUI、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Flask_NaiveVue) | -| FastAPI+Layui混编版 | 基于 FastAPI、Jinja2、Layui 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_Layui) | -| FastAPI+ElementPlus前后端分离版 | 基于 FastAPI、SQLAlchemy、Pydantic、Vue3、ElementPlus、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_EleVue) | -| FastAPI+AntDesign前后端分离版 | 基于 FastAPI、SQLAlchemy、Pydantic、Vue3、AntDesign、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_AntdVue) | -| FastAPI+NaiveUI前后端分离版 | 基于 FastAPI、SQLAlchemy、Pydantic、Vue3、NaiveUI、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_NaiveVue) | +| FastAPI+Layui混编版 | 基于 FastAPI、Jinja2、Layui 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_FastAPI_Layui) | +| FastAPI+ElementPlus前后端分离版 | 基于 FastAPI、SQLAlchemy、Pydantic、Vue3、ElementPlus、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_FastAPI_EleVue) | +| FastAPI+AntDesign前后端分离版 | 基于 FastAPI、SQLAlchemy、Pydantic、Vue3、AntDesign、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_FastAPI_AntdVue) | +| FastAPI+NaiveUI前后端分离版 | 基于 FastAPI、SQLAlchemy、Pydantic、Vue3、NaiveUI、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_FastAPI_NaiveVue) | | Tornado+Layui混编版 | 基于 Tornado、Jinja2、Layui 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Tornado_Layui) | | Tornado+ElementPlus前后端分离版 | 基于 Tornado、SQLAlchemy、Pydantic、Vue3、ElementPlus、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Tornado_EleVue) | | Tornado+AntDesign前后端分离版 | 基于 Tornado、SQLAlchemy、Pydantic、Vue3、AntDesign、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Tornado_AntdVue) | diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/other/declare.md b/DjangoAdmin_FastAPI_AntdVue/zh/other/declare.md index 7737479..915692a 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/other/declare.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/other/declare.md @@ -1,5 +1,9 @@ # 免责声明 +:::tip 概述 +使用本产品前必读的法律声明，明确产品性质、使用限制与责任划分，一旦使用本产品即视为接受本声明全部条款。 +::: + :::danger 重要提示 任何用户在使用本团队研发的系列软件产品（以下简称「本产品」）前，请仔细阅读并透彻理解本声明。选择不使用本产品，可随时停止使用；一旦使用本产品，即视为对本声明全部内容的认可和接受。 ::: diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/struct.md b/DjangoAdmin_FastAPI_AntdVue/zh/struct.md index ad8aca6..96d40ac 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/struct.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/struct.md @@ -1,3 +1,9 @@ +# 项目目录结构 + +:::tip 概述 +本页说明项目前后端目录组织与各目录职责，二次开发定位文件或了解工程结构时对照查阅。 +::: + ## 目录说明 在软件开发过程中，优秀的软件目录结构对于项目的组织、开发、维护和扩展至关重要，合理的目录结构能够显著提升开发效率和代码可维护性。 diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume2/code-list.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume2/code-list.md index a70f423..b5b577b 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume2/code-list.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume2/code-list.md @@ -1,5 +1,9 @@ # 完整代码清单 +:::tip 概述 +本页汇总岗位管理（Position）模块涉及的全部文件代码，开发时可快速查阅与复制对照。 +::: + 本章汇总 Position 岗位模块涉及的全部文件，便于开发时快速查阅和复制。 ## 后端文件清单 diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume2/endpoint.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume2/endpoint.md index 12d7528..c5a5aa8 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume2/endpoint.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume2/endpoint.md @@ -1,5 +1,9 @@ # Endpoint 层 +:::tip 概述 +Endpoint 层是 HTTP 接口层，负责定义路由、权限装饰器与请求参数绑定，编写新接口从本页开始。 +::: + Endpoint 层是 HTTP 接口层，负责定义路由、权限装饰器和请求参数绑定。每个业务模块对应一个 endpoint 文件，所有业务逻辑委托给 Service 层处理。 ## 文件位置 diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume2/faq.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume2/faq.md index 9e25482..5e4b074 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume2/faq.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume2/faq.md @@ -1,5 +1,9 @@ # 常见问题与排错 +:::tip 概述 +本页汇总模块开发过程中的常见问题与排错方法，开发受阻时按症状索引即可定位。 +::: + 本章汇总模块开发过程中的常见问题和解决方案。 ## 后端问题 diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume2/fe-api.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume2/fe-api.md index 797cc1c..ae9203a 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume2/fe-api.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume2/fe-api.md @@ -1,5 +1,9 @@ # 前端 API 层 +:::tip 概述 +前端 API 层封装后端接口的 HTTP 请求，每个业务模块对应一个 API 文件，本页讲解基于 Axios 封装的编写规范。 +::: + 前端 API 层负责封装后端接口的 HTTP 请求。每个业务模块对应一个 API 文件，使用项目封装的 Axios 工具发送请求。 ## 文件位置 diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume2/fe-router.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume2/fe-router.md index 0f79bbe..5c2330b 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume2/fe-router.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume2/fe-router.md @@ -1,5 +1,9 @@ # 前端路由与菜单 +:::tip 概述 +本页讲解前端路由与菜单机制——路由和菜单由后端动态返回，前端只需注册路由组件映射。 +::: + 前端路由定义页面的访问路径，菜单是路由的可视化展示。项目的路由和菜单由后端动态返回，前端只需注册路由组件映射。 ## 路由配置 diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume2/fe-view.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume2/fe-view.md index c91c239..b9b1f3d 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume2/fe-view.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume2/fe-view.md @@ -1,5 +1,9 @@ # 前端页面视图 +:::tip 概述 +前端页面视图是用户直接交互的界面，本页讲解 Vue3 + AntDesign Vue 下一个完整 CRUD 页面的文件组成与编写方式。 +::: + 前端页面视图是用户直接交互的界面。项目使用 Vue3 + AntDesign Vue + Vite 构建。一个完整的 CRUD 页面由 4 个文件组成： ``` diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume2/repository.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume2/repository.md index f268212..f530306 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume2/repository.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume2/repository.md @@ -1,5 +1,9 @@ # Repository 层 +:::tip 概述 +Repository 层是数据访问层，封装全部数据库查询操作，本页讲解基于 BaseRepository 基类的通用 CRUD 用法。 +::: + Repository 层是数据访问层，封装所有数据库查询操作。项目通过 `BaseRepository` 基类提供通用 CRUD 能力，子类通常只需声明类名，无需编写任何代码。 ## 文件位置 diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume2/router.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume2/router.md index 2fe9b5e..dfe5dd4 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume2/router.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume2/router.md @@ -1,5 +1,9 @@ # 路由注册 +:::tip 概述 +路由注册是将模块 Endpoint 挂载到应用的过程，本页讲解在 router.py 中统一注册模块路由的方法。 +::: + 路由注册是将模块的 Endpoint 挂载到应用的过程。所有模块的路由在 `src/api/v1/router.py` 中统一注册。 ## 文件位置 diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume2/schema.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume2/schema.md index 4013bcd..1ca3fcd 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume2/schema.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume2/schema.md @@ -1,5 +1,9 @@ # Pydantic Schema +:::tip 概述 +Schema 层负责请求数据校验，本页讲解基于 Pydantic v2 BaseModel 与 Field 的表单类定义规范。 +::: + Schema 层负责请求数据的校验。项目使用 Pydantic v2 的 `BaseModel` 定义表单类，通过 `Field` 约束字段格式，FastAPI 在接收请求体时自动执行校验。 ## 文件位置 diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume2/service.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume2/service.md index 84a1b32..a642ed9 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume2/service.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume2/service.md @@ -1,5 +1,9 @@ # Service 层 +:::tip 概述 +Service 层是业务逻辑层，本页讲解基于 BaseService 基类声明差异点即可获得完整增删改查能力的编写方式。 +::: + Service 层是业务逻辑层，负责实现具体的业务规则。简单 CRUD 模块继承 `BaseService` 基类，只需声明差异点即可获得完整的增删改查能力。 ## 文件位置 diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/article.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/article.md index bea27f6..08483a8 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/article.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/article.md @@ -1,3 +1,5 @@ +# 文章管理 + :::tip 文章管理 文章管理模块支持富文本编辑、分类关联、封面图片上传、图集管理等功能。适用于新闻、公告、帮助文档等内容管理场景。本模块是典型的「带文件处理」业务模块，涵盖了封面迁移、图集处理、富文本 XSS 清洗等核心机制。 ::: diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/category.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/category.md index 6914255..376495e 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/category.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/category.md @@ -1,3 +1,5 @@ +# 分类管理 + :::tip 分类管理 分类管理模块用于管理树形分类数据，如文章分类、产品分类等。通过 `parent_id` 字段实现无限级分类。 ::: diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/content.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/content.md index 8a1005a..2fb2a91 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/content.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/content.md @@ -1,3 +1,5 @@ +# 公告与链接管理 + :::tip 公告/链接/城市 公告、链接、城市是三个简单 CRUD 内容模块，均继承 BaseService，提供标准的增删改查接口。适用于系统公告、友情链接、城市数据等场景。 ::: diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/dept.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/dept.md index 374223a..e184732 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/dept.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/dept.md @@ -1,3 +1,5 @@ +# 部门/职级/岗位管理 + :::tip 部门/职级/岗位 部门、职级、岗位是组织架构管理的三个核心模块。部门采用树形结构，职级和岗位为简单 CRUD 模块，均继承 `BaseService`。用户表通过 `dept_id`、`position_id`、`level_id` 三个外键关联这三个模块。 ::: diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/job.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/job.md index 6fdf1d8..6aa953e 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/job.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/job.md @@ -1,3 +1,5 @@ +# 定时任务 + :::tip 定时任务 定时任务模块基于 APScheduler 实现，支持 Cron 表达式调度、任务执行日志、动态启停等功能。包含 job（任务定义）、job_log（执行日志）、scheduler（调度器）三个子模块。 ::: diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/menu.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/menu.md index 37776cb..9a66782 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/menu.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/menu.md @@ -1,3 +1,5 @@ +# 菜单管理 + :::tip 菜单管理 菜单管理是 RBAC 权限系统的基础，负责管理系统的导航菜单和权限节点。支持目录/菜单（type=0）和权限按钮节点（type=1）两种类型，通过树形结构组织。权限节点由系统根据前端勾选自动生成，采用 `sys:module:action` 三段式命名。 ::: diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/param.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/param.md index 0ec1e7e..6287408 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/param.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/param.md @@ -1,3 +1,5 @@ +# 参数管理 + :::tip 参数管理 参数管理模块用于管理动态系统参数，与系统配置模块类似但更侧重于业务参数的灵活配置。支持按参数键查询、修改，无需重启服务即可生效。本模块是典型的「BaseService 简单模块」，通过声明差异点即可获得完整 CRUD 能力。 ::: diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/role.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/role.md index ce9fff0..336c2dc 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/role.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/role.md @@ -1,3 +1,5 @@ +# 角色管理 + :::tip 角色管理 角色是 RBAC 权限模型的核心，连接用户和菜单（权限）。通过为角色分配菜单权限，再将角色分配给用户，实现灵活的权限管理。角色删除时需清理关联的用户角色和角色菜单数据，并即时失效受影响用户的权限缓存。 ::: diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/user.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/user.md index 7cc450c..33a074f 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/user.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/business/user.md @@ -1,3 +1,5 @@ +# 用户管理 + :::tip 用户管理 用户管理是系统的核心模块，属于复杂业务模块。包含用户 CRUD、角色关联、密码加密、行政区划、Excel 导入导出等功能。与简单 CRUD 模块不同，用户管理使用自定义 service 函数而非继承 BaseService 的类方法。 ::: diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/captcha.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/captcha.md index c8a9b51..240e6b6 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/captcha.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/captcha.md @@ -1,3 +1,5 @@ +# 验证码机制 + :::tip 验证码 验证码是防止自动化攻击的重要安全手段。使用 Pillow 生成图片验证码，存储在 Redis 中，支持防刷限流和万能验证码（演示模式）。源码位于 `src/utils/captcha.py`。 ::: diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/config.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/config.md index 3b1e478..3a01a20 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/config.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/config.md @@ -1,3 +1,5 @@ +# 系统配置管理 + :::tip 系统配置 系统配置模块用于管理动态的键值对配置项，与数据字典类似但更偏向系统级参数。支持分组管理，可通过接口动态修改，无需重启服务。模块位于 `src/modules/configuration/`，端点位于 `src/api/v1/endpoints/config.py` 和 `config_item.py`。 ::: diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/cors.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/cors.md index 58b0f89..7f4f409 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/cors.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/cors.md @@ -1,3 +1,5 @@ +# 跨域资源共享（CORS） + :::tip CORS跨域 CORS（Cross-Origin Resource Sharing）跨域资源共享是前后端分离架构必须处理的问题。通过 `CORS_ALLOWED_ORIGINS` 环境变量配置允许的跨域源。中间件位于 `src/middleware/cors.py`。 ::: diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/demo-mode.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/demo-mode.md index 3b9651c..bce77fe 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/demo-mode.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/demo-mode.md @@ -1,3 +1,5 @@ +# 演示模式 + :::tip 演示模式 演示模式用于在线体验环境，开启后所有写操作（新增、编辑、删除等）将被拦截，返回"演示环境，暂无操作权限"提示。通过 `FASTAPI_DEMO` 环境变量控制。装饰器位于 `src/core/access_decorators.py`。 ::: diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/dict.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/dict.md index bfe1854..5130234 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/dict.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/dict.md @@ -1,3 +1,5 @@ +# 字典模块 + :::tip 数据字典 数据字典用于管理系统中的枚举值和配置项，如状态、类型、性别等。通过字典编码统一管理，前端可通过 `useDictStore` 获取字典选项，避免硬编码。后端读取工具位于 `src/utils/dict_util.py`，内置进程内 TTL 缓存。 ::: diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/exception.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/exception.md index 8da880b..c9bca69 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/exception.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/exception.md @@ -1,3 +1,5 @@ +# 异常与响应处理 + :::tip 全局异常与响应 定义了统一的响应格式和全局异常处理机制。所有 API 返回 `{code, data, msg, ok}` 标准格式，异常被捕获后也转换为相同格式。响应函数位于 `src/core/response.py`，异常类型位于 `src/core/exceptions.py`。 ::: diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/idempotent.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/idempotent.md index e7d0e6a..e811f0a 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/idempotent.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/idempotent.md @@ -1,3 +1,5 @@ +# 防重复提交 + :::tip 防重复提交 防重复提交是保障数据一致性的重要措施。通过前端防抖和后端唯一性校验双重保护，防止用户重复点击导致的数据重复提交。后端唯一性校验通过 Pydantic `@field_validator` 查询数据库实现。 ::: diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/jwt.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/jwt.md index 9983fab..2e756cc 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/jwt.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/jwt.md @@ -1,3 +1,5 @@ +# 用户认证（JWT） + :::tip JWT认证 JWT（JSON Web Token）是的核心认证机制。用户登录成功后获取 Token，后续请求通过 `Authorization: Bearer <token>` 头携带 Token 进行身份验证。项目内置了 Token 生成、解析、刷新和黑名单管理功能，源码位于 `src/core/jwt.py`。 ::: diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/login-log.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/login-log.md index 3655d26..b5b5d47 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/login-log.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/login-log.md @@ -1,3 +1,5 @@ +# 登录日志 + :::tip 登录日志 登录日志记录每次登录尝试（成功/失败），包含登录账号、IP地址、浏览器信息、登录时间等。支持 IP 地理位置解析（ip2region）和 User-Agent 解析。登录逻辑位于 `src/modules/auth/service.py`，日志记录位于 `src/modules/login_log/service.py`。 ::: diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/operation-log.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/operation-log.md index 9b09821..f77ba18 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/operation-log.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/operation-log.md @@ -1,3 +1,5 @@ +# 操作日志 + :::tip 操作日志 操作日志中间件自动拦截写请求（POST/PUT/DELETE/PATCH）并记录操作日志，无需手动埋点。日志落库通过 `response.background` 异步执行，不阻塞响应。源码位于 `src/middleware/operation_log.py`。 ::: diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/rate-limit.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/rate-limit.md index d1b703a..d08213a 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/rate-limit.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/rate-limit.md @@ -1,3 +1,5 @@ +# 请求限流 + :::tip 请求限流 请求限流中间件基于 Redis 实现 IP 级别的滑动窗口限流，防止恶意请求和 DoS 攻击。默认关闭，可通过环境变量开启。源码位于 `src/middleware/rate_limit.py`，滑动窗口 Lua 脚本位于 `src/core/redis_client.py`。 ::: diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/rbac.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/rbac.md index 689045d..e03dcd5 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/rbac.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/rbac.md @@ -1,3 +1,5 @@ +# 权限管理（RBAC） + :::tip RBAC权限 采用基于角色的访问控制（RBAC）模型，通过用户-角色-菜单三层关系实现细粒度的权限管理。权限控制贯穿前后端：后端通过 `@permission_required` 装饰器校验（`src/core/access_decorators.py`），前端通过 `v-perm` 指令控制按钮显隐。 ::: diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/validator.md b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/validator.md index 44aa23e..729a411 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/validator.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/volume4/core/validator.md @@ -1,3 +1,5 @@ +# 参数验证（Pydantic） + :::tip 参数验证 使用 Pydantic v2 进行请求参数验证。所有请求体参数通过 Pydantic BaseModel 定义，FastAPI 自动解析和验证 JSON 请求体，验证失败返回标准格式错误信息。BaseForm 基类位于 `src/core/base_schemas.py`。 ::: diff --git a/DjangoAdmin_FastAPI_AntdVue/zh/why.md b/DjangoAdmin_FastAPI_AntdVue/zh/why.md index cadafb0..2e7fc4a 100644 --- a/DjangoAdmin_FastAPI_AntdVue/zh/why.md +++ b/DjangoAdmin_FastAPI_AntdVue/zh/why.md @@ -1,7 +1,7 @@ # 为什么选择我们？ :::tip 核心价值 -企业级数据中台不应从零搭建。本框架提供开箱即用的完整解决方案，为中大型企业构建统一的数字化基座。 +本框架提供开箱即用的企业级中台完整解决方案，免去从零搭建成本，助力中大型企业构建统一的数字化基座。 ::: ## 解决什么问题？ diff --git a/DjangoAdmin_FastAPI_EleVue/.vitepress/config/en.ts b/DjangoAdmin_FastAPI_EleVue/.vitepress/config/en.ts index a1a96ef..8d7fab9 100644 --- a/DjangoAdmin_FastAPI_EleVue/.vitepress/config/en.ts +++ b/DjangoAdmin_FastAPI_EleVue/.vitepress/config/en.ts @@ -29,7 +29,7 @@ // // themeConfig: { // editLink: { -// pattern: "https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_EleVue", +// pattern: "https://gitee.com/djangoadmin/DjangoAdmin_FastAPI_EleVue", // text: "Suggest changes to this page", // }, // diff --git a/DjangoAdmin_FastAPI_EleVue/.vitepress/config/extract.d.mts b/DjangoAdmin_FastAPI_EleVue/.vitepress/config/extract.d.mts new file mode 100644 index 0000000..2a46233 --- /dev/null +++ b/DjangoAdmin_FastAPI_EleVue/.vitepress/config/extract.d.mts @@ -0,0 +1,5 @@ +export declare const SITE_URL: string; +export declare const SITE_DESCRIPTION: string; +export declare function stripNumberPrefix(title: string): string; +export declare function extractDescription(md: string): string; +export declare function extractFaqs(md: string): { q: string; a: string }[]; diff --git a/DjangoAdmin_FastAPI_EleVue/.vitepress/config/extract.mjs b/DjangoAdmin_FastAPI_EleVue/.vitepress/config/extract.mjs new file mode 100644 index 0000000..3fce367 --- /dev/null +++ b/DjangoAdmin_FastAPI_EleVue/.vitepress/config/extract.mjs @@ -0,0 +1,130 @@ +/** + * SEO/GEO 共享工具（纯 ESM，零依赖）。 + * + * 同时被两类调用方 import： + * 1. VitePress 配置（.ts，esbuild 打包时内联本文件） + * 2. scripts/generate-llms-txt.mjs（Node 直接运行） + * + * 注意：SITE_URL 是全站唯一 URL 真相源。 + * docs 子域当前 TLS 证书为腾讯 CDN 默认证书（*.cdn.myqcloud.com，校验失败）， + * 故暂用 http；证书修复后只需改这里一处。 + */ + +export const SITE_URL = "http://docs.fastapi.elevue.djangoadmin.cn"; + +export const SITE_DESCRIPTION = + "DjangoAdmin 企业级中台解决方案 - FastAPI + ElementPlus 前后端分离版本"; + +/** + * 剥离 H1/标题中的章节编号前缀，用于 <title> 与 JSON-LD headline。 + * 例："5.10 字典模块" → "字典模块"；"K. 贡献指南" → "贡献指南"。 + * 页内 H1 与侧边栏编号保持不变，仅影响 SEO 输出。 + */ +export function stripNumberPrefix(title) { + return String(title) + .replace(/^(?:\d+(?:\.\d+)+|[A-Z]\.)\s+/, "") + .trim(); +} + +/** + * 从页面 Markdown 提取 meta description： + * 1. 首选 `:::tip xxx` 容器内的首句（141/143 页的标准 opener） + * 2. 回退到 H1 后的第一个普通段落 + * 输出压缩为单行、去除行内 Markdown，按中文句末标点截断（≤100 字符）。 + */ +export function extractDescription(md) { + const src = String(md); + const fm = src.match(/^---\r?\n([\s\S]*?)\r?\n---/); + const body = fm ? src.slice(fm[0].length) : src; + + let text = ""; + // frontmatter description 显式声明优先（无 H1 页面的补齐手段） + const fmDesc = fm && fm[1].match(/^description:\s*(.+)$/m); + if (fmDesc) { + text = fmDesc[1].trim().replace(/^["']|["']$/g, ""); + } + const tip = !text && body.match(/^:::\s*tip[^\n]*\n([\s\S]*?)\n:::/m); + if (tip) { + text = tip[1]; + } + if (!text) { + const afterH1 = body.match(/^# (?!#)(.+)$/m); + if (afterH1) { + const rest = body.slice((afterH1.index ?? 0) + afterH1[0].length); + const para = rest + .split(/\n{2,}/) + .find( + (p) => + p.trim() && + !/^\s*#/.test(p) && + !/^\s*:::/.test(p) && + !/^\s*```/.test(p) && + !/^\s*\|/.test(p), + ); + text = para || ""; + } + } + + text = text + .replace(/\s+/g, " ") + .replace(/`([^`]+)`/g, "$1") + .replace(/\*\*([^*]+)\*\*/g, "$1") + .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") + .trim(); + + if (!text) return ""; + + // 按中文句末标点截取首句，上限 100 字符；截断时避免切碎词 + const m = text.match(/^.{1,100}?(?:[。！？!?]|$)/); + let out = m ? m[0] : text.slice(0, 100); + if (out.length < text.length && !/[。！？!?]$/.test(out)) { + out = out.replace(/[^\s，、；：,;:]+$/, ""); + } + return out.trim() || text.slice(0, 100); +} + +function cleanText(s) { + return s + .replace(/^:::[^\n]*$/gm, "") + .replace(/^```[^\n]*$/gm, "") + .replace(/`([^`]+)`/g, "$1") + .replace(/\*\*([^*]+)\*\*/g, "$1") + .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") + .replace(/\s+/g, " ") + .trim(); +} + +/** + * 提取页面中的 Q/A 对（用于 FAQPage JSON-LD），支持两种站内格式： + * A. `### Q：问题` 标题式（如 zh/quickstart/faq.md） + * B. `**Q：问题**` 加粗式（如 zh/appendix/faq.md） + * 返回 [{ q, a }]；无匹配返回 []。 + */ +export function extractFaqs(md) { + const body = String(md).replace(/^---[\s\S]*?\n---\s*/, ""); + let faqs = []; + + // 格式 A：按 `### Q：` 切块，答案截断到下一个标题 + for (const part of body.split(/(?=^###\s*Q[：:])/m)) { + const m = part.match(/^###\s*Q[：:]\s*([^\n]+)\n+([\s\S]*)/); + if (!m) continue; + let a = m[2]; + const cut = a.search(/^#{1,4}\s/m); + if (cut >= 0) a = a.slice(0, cut); + faqs.push({ q: cleanText(m[1]), a: cleanText(a) }); + } + + // 格式 B：按 `**Q：` 切块 + if (!faqs.length) { + for (const part of body.split(/(?=^\*\*Q[：:])/m)) { + const m = part.match(/^\*\*Q[：:]\s*([^*]+)\*\*\s*\n+([\s\S]*)/); + if (!m) continue; + let a = m[2]; + const cut = a.search(/^(?:#{1,4}\s|\*\*Q)/m); + if (cut >= 0) a = a.slice(0, cut); + faqs.push({ q: cleanText(m[1]), a: cleanText(a) }); + } + } + + return faqs.filter((f) => f.q && f.a); +} diff --git a/DjangoAdmin_FastAPI_EleVue/.vitepress/config/index.ts b/DjangoAdmin_FastAPI_EleVue/.vitepress/config/index.ts index 2294856..6627a76 100644 --- a/DjangoAdmin_FastAPI_EleVue/.vitepress/config/index.ts +++ b/DjangoAdmin_FastAPI_EleVue/.vitepress/config/index.ts @@ -1,14 +1,22 @@ import { defineConfig } from "vitepress"; import { enConfig } from "./en"; +import { createSeoHooks } from "./seo"; import { sharedConfig } from "./shared"; import { zhConfig } from "./zh"; +const seo = createSeoHooks(zhConfig.themeConfig?.sidebar); + export default defineConfig({ ...sharedConfig, ignoreDeadLinks: [ (link) => link.includes('localhost'), ], + // SEO：页面级 title/description、canonical/OG/JSON-LD、sitemap+lastmod + transformPageData: seo.transformPageData, + transformHead: seo.transformHead, + sitemap: seo.sitemap, + locales: { root: { label: "简体中文", lang: "zh-CN", link: "/", ...zhConfig }, // root: { label: "English", lang: "en-US", link: "/", ...enConfig }, diff --git a/DjangoAdmin_FastAPI_EleVue/.vitepress/config/seo.ts b/DjangoAdmin_FastAPI_EleVue/.vitepress/config/seo.ts new file mode 100644 index 0000000..c7416b9 --- /dev/null +++ b/DjangoAdmin_FastAPI_EleVue/.vitepress/config/seo.ts @@ -0,0 +1,311 @@ +/** + * SEO/GEO 构建期钩子（仅 Node 构建时运行，不进客户端 bundle）： + * - transformPageData：每页独立 title（去编号前缀）与 description（取 :::tip 首句） + * - transformHead：canonical / Open Graph / twitter 卡片 / JSON-LD 结构化数据 + * - sitemap.transformItems：注入 lastmod（git 最后提交时间）并过滤 404 + * + * 由 config/index.ts 通过 createSeoHooks(zhConfig.themeConfig?.sidebar) 挂载。 + * 依赖 extract.mjs（纯 ESM，同被 scripts/generate-llms-txt.mjs 复用）。 + */ +import fs from "node:fs"; +import path from "node:path"; +import { execSync } from "node:child_process"; +import { + SITE_URL, + extractDescription, + extractFaqs, + stripNumberPrefix, +} from "./extract.mjs"; + +/** 与 vitepress HeadConfig 同构：[tag, attrs, innerHTML?] */ +type HeadTuple = [string, Record<string, any>, string?]; + +interface SideItem { + text?: string; + link?: string; + items?: SideItem[]; +} + +interface PageDataLike { + relativePath?: string; + title?: string; + description?: string; + frontmatter?: Record<string, any>; + [k: string]: any; +} + +interface TransformCtx { + pageData?: PageDataLike; + title?: string; + description?: string; + content?: string; + siteConfig?: { root?: string; srcDir?: string }; +} + +const ORG = { + "@type": "Organization", + name: "DjangoAdmin", + url: "https://www.djangoadmin.cn", + logo: `${SITE_URL}/logo.png`, + sameAs: [ + "https://gitee.com/djangoadmin/DjangoAdmin_FastAPI_EleVue", + "https://www.djangoadmin.cn", + ], +}; + +/** 相对路径 → 站内路由（cleanUrls 关闭，正文页带 .html） */ +function routeOf(relativePath: string): string { + if (relativePath === "index.md") return "/"; + if (relativePath === "404.md") return "/404.html"; + return `/${relativePath.replace(/\.md$/, ".html")}`; +} + +/** 去掉侧边栏文案前导 emoji/符号，保留 "1.1 项目介绍" 这类编号文字 */ +function cleanLabel(s?: string): string { + return (s || "").replace(/^[^\p{L}\p{N}]+/u, "").trim(); +} + +/** 从侧边栏构建 route → 面包屑文案链（含分组小节） */ +function buildCrumbMap(sidebar: unknown): Map<string, string[]> { + const map = new Map<string, string[]>(); + const groups: SideItem[] = Array.isArray(sidebar) + ? sidebar + : ((sidebar as Record<string, SideItem[]>)?.["/zh/"] ?? []); + const walk = (items: SideItem[], trail: string[]) => { + for (const item of items) { + if (item.link && item.link.startsWith("/")) { + map.set(item.link, [...trail, cleanLabel(item.text)]); + } else if (item.items?.length) { + walk(item.items, [...trail, cleanLabel(item.text)]); + } + } + }; + for (const group of groups) { + walk(group.items ?? [], [cleanLabel(group.text)].filter(Boolean)); + } + return map; +} + +/** 从渲染后的 HTML 提取 H1 纯文本（JSON-LD headline 须与页面 H1 一致） */ +function h1OfHtml(html?: string): string { + const m = (html || "").match(/<h1[^>]*>([\s\S]*?)<\/h1>/i); + if (!m) return ""; + return m[1] + .replace(/<[^>]+>/g, "") + .replace(/&/g, "&") + .replace(/</g, "<") + .replace(/>/g, ">") + .replace(/"/g, '"') + .replace(/'/g, "'") + .trim(); +} + +/** 从 Markdown 源提取 H1 纯文本（去除行内 markdown 标记） */ +function h1OfMd(md: string): string { + // 围栏感知：跳过 ``` 代码块内的 # 注释，取真正的页面 H1 + let inFence = false; + for (const line of md.split("\n")) { + if (line.startsWith("```")) { inFence = !inFence; continue; } + if (!inFence && /^# (?!#)/.test(line)) { + return line + .replace(/^# /, "") + .replace(/`([^`]+)`/g, "$1") + .replace(/\*\*([^*]+)\*\*/g, "$1") + .trim(); + } + } + return ""; +} + +export function createSeoHooks(sidebar: unknown) { + const crumbs = buildCrumbMap(sidebar); + const projectDirs: string[] = []; + let gitDates: Map<string, string> | null = null; + + const readMd = (relativePath: string, srcDir?: string): string => { + try { + return fs.readFileSync( + path.resolve(srcDir || process.cwd(), relativePath), + "utf8", + ); + } catch { + return ""; + } + }; + + /** + * 项目内每个文件最后一次 git 提交的 ISO 时间。 + * 单次 git log 调用构建全量映射（key = 相对路径，与 pageData.relativePath 一致）； + * git 不可用时静默降级（sitemap 无 lastmod、JSON-LD 无 dateModified）。 + */ + const getGitDates = (root: string): Map<string, string> => { + if (gitDates) return gitDates; + gitDates = new Map<string, string>(); + try { + const out = execSync( + "git log --format=:::%cI --name-only --relative -n 500 -- .", + { + cwd: root, + encoding: "utf8", + maxBuffer: 64 * 1024 * 1024, + stdio: ["ignore", "pipe", "ignore"], + }, + ); + let current = ""; + for (const line of out.split(/\r?\n/)) { + if (line.startsWith(":::")) { + current = line.slice(3).trim(); + continue; + } + const file = line.trim(); + if (file && current && !gitDates.has(file)) { + gitDates.set(file, current); + } + } + } catch { + // 降级：无 lastmod / dateModified + } + return gitDates; + }; + + /** 每页独立 title（去 "5.10 " 编号前缀，关键词前置）与 description（:::tip 首句） */ + function transformPageData(pageData: PageDataLike, ctx?: any): Record<string, unknown> { + const srcDir: string | undefined = ctx?.siteConfig?.srcDir; + const root: string | undefined = ctx?.siteConfig?.root; + if (root && !projectDirs.includes(root)) projectDirs.push(root); + + const out: Record<string, unknown> = {}; + const rel = pageData.relativePath; + if (rel && !pageData.frontmatter?.description) { + const desc = extractDescription(readMd(rel, srcDir)); + if (desc) out.description = desc; + } + if (pageData.title) { + out.title = stripNumberPrefix(pageData.title); + } + return out; + } + + /** 构建期注入 canonical / OG / twitter / JSON-LD */ + function transformHead(ctx: TransformCtx): HeadTuple[] { + const rel = ctx?.pageData?.relativePath || ""; + if (!rel || rel === "404.md") return []; + + const route = routeOf(rel); + const url = `${SITE_URL}${route}`; + const title = ctx.pageData?.title || ctx.title || ""; + const desc = ctx.description || ""; + const isHome = rel === "index.md"; + const image = `${SITE_URL}/logo.png`; + + const heads: HeadTuple[] = [ + ["link", { rel: "canonical", href: url }], + ["meta", { property: "og:type", content: isHome ? "website" : "article" }], + ["meta", { property: "og:site_name", content: "DjangoAdmin" }], + ["meta", { property: "og:locale", content: "zh_CN" }], + ["meta", { property: "og:title", content: title }], + ["meta", { property: "og:description", content: desc }], + ["meta", { property: "og:url", content: url }], + ["meta", { property: "og:image", content: image }], + ["meta", { property: "twitter:title", content: title }], + ["meta", { property: "twitter:description", content: desc }], + ["meta", { property: "twitter:url", content: url }], + ["meta", { property: "twitter:image", content: image }], + ]; + + // ---- JSON-LD ---- + const root = ctx.siteConfig?.root || projectDirs[0] || process.cwd(); + const srcDir = ctx.siteConfig?.srcDir || root; + const lastMod = getGitDates(root).get(rel); + const blocks: Record<string, any>[] = []; + + if (isHome) { + blocks.push({ + "@context": "https://schema.org", + "@type": "WebSite", + name: "DjangoAdmin 开发文档", + url: `${SITE_URL}/`, + inLanguage: "zh-CN", + description: desc, + }); + blocks.push({ "@context": "https://schema.org", ...ORG }); + } else { + const md = readMd(rel, srcDir); + const article: Record<string, any> = { + "@context": "https://schema.org", + "@type": "TechArticle", + headline: h1OfMd(md) || h1OfHtml(ctx.content) || title, + description: desc, + url, + inLanguage: "zh-CN", + mainEntityOfPage: { "@type": "WebPage", "@id": url }, + publisher: ORG, + }; + if (lastMod) article.dateModified = lastMod; + blocks.push(article); + + const trail = crumbs.get(route); + if (trail?.length) { + const items: Record<string, any>[] = [ + { "@type": "ListItem", position: 1, name: "首页", item: `${SITE_URL}/` }, + ]; + trail.forEach((name, i) => { + const node: Record<string, any> = { + "@type": "ListItem", + position: i + 2, + name, + }; + if (i === trail.length - 1) node.item = url; + items.push(node); + }); + blocks.push({ + "@context": "https://schema.org", + "@type": "BreadcrumbList", + itemListElement: items, + }); + } + + const faqs = extractFaqs(md); + if (faqs.length) { + blocks.push({ + "@context": "https://schema.org", + "@type": "FAQPage", + mainEntity: faqs.map((f) => ({ + "@type": "Question", + name: f.q, + acceptedAnswer: { "@type": "Answer", text: f.a }, + })), + }); + } + } + + // 转义 "<"，防止内容中出现 </script> 破坏注入 + const json = JSON.stringify(blocks).replace(/</g, "\\u003c"); + heads.push(["script", { type: "application/ld+json" }, json]); + return heads; + } + + /** sitemap.xml：过滤 404/README，注入 git lastmod */ + const sitemap = { + hostname: SITE_URL, + transformItems(items: { url: string; lastmod?: string }[]) { + const root = projectDirs[0] || process.cwd(); + const dates = getGitDates(root); + const out: { url: string; lastmod?: string }[] = []; + for (const item of items) { + // ⚠ vitepress 传入的 item.url 是相对路径（"404.html"、"zh/x.html"、""）， + // 无前导斜杠也无域名——hostname 由 SitemapStream 事后拼接。 + if (/(^|\/)404\.html$/.test(item.url)) continue; // 404 页不收录 + if (/(^|\/)README\.html$/.test(item.url)) continue; // 仓库 README 非文档页 + const p = item.url.replace(/^\//, ""); + const rel = + p === "" || p === "index.html" ? "index.md" : p.replace(/\.html$/, ".md"); + const lastmod = dates.get(rel); + out.push(lastmod ? { ...item, lastmod } : item); + } + return out; + }, + }; + + return { transformPageData, transformHead, sitemap }; +} diff --git a/DjangoAdmin_FastAPI_EleVue/.vitepress/config/shared.ts b/DjangoAdmin_FastAPI_EleVue/.vitepress/config/shared.ts index 2da878b..59d1bea 100644 --- a/DjangoAdmin_FastAPI_EleVue/.vitepress/config/shared.ts +++ b/DjangoAdmin_FastAPI_EleVue/.vitepress/config/shared.ts @@ -1,6 +1,6 @@ import { defineConfig, HeadConfig } from "vitepress"; -export const META_IMAGE = "/social.png"; +export const META_IMAGE = "/logo.png"; const rControl = /[\u0000-\u001f]/g; const rSpecial = /[\s~`!@#$%^&*()\-_+=[\]{}|\\;:"'“”‘’<>,.?/]+/g; @@ -23,6 +23,8 @@ export const slugify = (str: string): string => export const sharedConfig = defineConfig({ title: "小蚂蚁云", + // 页面 <title> 后缀：「环境准备 | DjangoAdmin 开发文档」（index.md frontmatter 可覆盖） + titleTemplate: "DjangoAdmin 开发文档", appearance: "light", markdown: { diff --git a/DjangoAdmin_FastAPI_EleVue/.vitepress/config/zh.ts b/DjangoAdmin_FastAPI_EleVue/.vitepress/config/zh.ts index fc1db2a..e7e3d1e 100644 --- a/DjangoAdmin_FastAPI_EleVue/.vitepress/config/zh.ts +++ b/DjangoAdmin_FastAPI_EleVue/.vitepress/config/zh.ts @@ -1,8 +1,9 @@ import type { DefaultTheme, LocaleSpecificConfig } from "vitepress"; -export const META_URL = "https://www.djangoadmin.cn"; -export const META_TITLE = "企业级中台解决方案"; -export const META_DESCRIPTION = "企业级中台解决方案"; +export const META_URL = "http://docs.fastapi.elevue.djangoadmin.cn"; +export const META_TITLE = "DjangoAdmin FastAPI+ElementPlus 开发文档"; +export const META_DESCRIPTION = + "DjangoAdmin 企业级中台解决方案 - FastAPI + ElementPlus 前后端分离版本"; export const zhConfig: LocaleSpecificConfig<DefaultTheme.Config> = { description: META_DESCRIPTION, @@ -29,7 +30,7 @@ export const zhConfig: LocaleSpecificConfig<DefaultTheme.Config> = { themeConfig: { editLink: { - pattern: "https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_EleVue", + pattern: "https://gitee.com/djangoadmin/DjangoAdmin_FastAPI_EleVue", text: "对本页提出修改建议", }, @@ -789,7 +790,7 @@ export const zhConfig: LocaleSpecificConfig<DefaultTheme.Config> = { { text: "9.2 免责声明", link: "/zh/other/declare.html" }, { text: "9.3 开源协议", - link: "https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_EleVue/blob/master/LICENSE", + link: "https://gitee.com/djangoadmin/DjangoAdmin_FastAPI_EleVue/blob/master/LICENSE", }, { text: "9.4 广告赞助", link: "/zh/other/sponsor.html" }, ], diff --git a/DjangoAdmin_FastAPI_EleVue/404.md b/DjangoAdmin_FastAPI_EleVue/404.md new file mode 100644 index 0000000..c344b20 --- /dev/null +++ b/DjangoAdmin_FastAPI_EleVue/404.md @@ -0,0 +1,12 @@ +--- +head: + - - meta + - name: robots + content: noindex +--- + +# 页面不存在 + +抱歉，您访问的页面不存在或已被移动。 + +[返回首页](/) · [浏览文档](/zh/introduction) diff --git a/DjangoAdmin_FastAPI_EleVue/package.json b/DjangoAdmin_FastAPI_EleVue/package.json index 77bd941..b5517ed 100644 --- a/DjangoAdmin_FastAPI_EleVue/package.json +++ b/DjangoAdmin_FastAPI_EleVue/package.json @@ -5,7 +5,8 @@ "type": "module", "scripts": { "docs": "vitepress dev .", - "docs:build": "vitepress build .", + "docs:llms": "node scripts/generate-llms-txt.mjs", + "docs:build": "node scripts/generate-llms-txt.mjs && vitepress build .", "docs:preview": "vitepress preview ." }, "dependencies": { diff --git a/DjangoAdmin_FastAPI_EleVue/public/llms.txt b/DjangoAdmin_FastAPI_EleVue/public/llms.txt new file mode 100644 index 0000000..442373e --- /dev/null +++ b/DjangoAdmin_FastAPI_EleVue/public/llms.txt @@ -0,0 +1,159 @@ +# DjangoAdmin FastAPI+ElementPlus 开发文档 + +> DjangoAdmin 企业级中台解决方案 - FastAPI + ElementPlus 前后端分离版本。内置 RBAC 权限体系、代码生成器等开箱即用功能，支持五种数据库一键切换。本文档共 129 篇，按章节组织。 + +## 1. 了解项目 + +- [1.1 项目介绍](http://docs.fastapi.elevue.djangoadmin.cn/zh/introduction.html): DjangoAdmin 是企业级中台解决方案，后端基于 FastAPI + SQLAlchemy，前端基于 Vue3 + ElementPlus，内置 RBAC 权限、代码生成器等开箱即用功能， +- [更新日志](http://docs.fastapi.elevue.djangoadmin.cn/zh/changelog.html): 更新日志是项目演进的完整记录，帮助开发者和企业了解每个版本的能力变化与技术演进方向。 +- [新手入门指南](http://docs.fastapi.elevue.djangoadmin.cn/zh/course.html): 详细的安装步骤请参考 环境准备 章节。 +- [项目目录结构](http://docs.fastapi.elevue.djangoadmin.cn/zh/struct.html): 本页说明项目前后端目录组织与各目录职责，二次开发定位文件或了解工程结构时对照查阅。 +- [为什么选择我们？](http://docs.fastapi.elevue.djangoadmin.cn/zh/why.html): 本框架提供开箱即用的企业级中台完整解决方案，免去从零搭建成本，助力中大型企业构建统一的数字化基座。 + +## 2. 快速入门 + +- [后端启动](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume1/backend.html): 启动后端前，请确保已完成 环境准备 章节中的所有软件安装。 +- [数据库初始化](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume1/database.html): 数据库初始化前，请确保已完成以下准备工作： 1. 目标数据库服务已启动（如 MySQL 8.0+） 2. .env 文件中的 DB_DRIVER 和数据库连接信息已正确配置 3. Python +- [Docker 一键启动](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume1/docker.html): 使用 Docker 方式启动前，请确保已安装以下软件： 1. Docker Desktop（Windows / macOS）或 Docker Engine（Linux） 2. Docker +- [环境变量速查表](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume1/env-vars.html): 1. .env.example 是环境变量模板文件，已提交到版本控制。 +- [环境准备](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume1/environment.html): 1. 部分软件安装后需要设置本地环境变量，便于在终端中使用命令。 +- [常见问题FAQ](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume1/faq.html): 遇到问题时，建议先查看终端日志输出和浏览器控制台（F12）的错误信息，通常能快速定位问题原因。 +- [第一个接口调试](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume1/first-api.html): 开始调试前，请确保已完成以下步骤： 1. 后端服务已启动（参见 后端启动） 2. 数据库已初始化（参见 数据库初始化） 3. Redis 服务已启动 +- [前端启动](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume1/frontend.html): 启动前端前，请确保已完成 环境准备 章节中的 Node.js 和 pnpm 安装，并已启动后端服务（参见 后端启动）。 + +## 3. 模块开发实战 + +- [完整代码清单](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume2/code-list.html): 本页汇总岗位管理（Position）模块涉及的全部文件代码，开发时可快速查阅与复制对照。 +- [Endpoint 层](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume2/endpoint.html): Endpoint 层是 HTTP 接口层，负责定义路由、权限装饰器与请求参数绑定，编写新接口从本页开始。 +- [常见问题与排错](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume2/faq.html): 本页汇总模块开发过程中的常见问题与排错方法，开发受阻时按症状索引即可定位。 +- [前端 API 层](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume2/fe-api.html): 前端 API 层封装后端接口的 HTTP 请求，每个业务模块对应一个 API 文件，本页讲解基于 Axios 封装的编写规范。 +- [前端路由与菜单](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume2/fe-router.html): 本页讲解前端路由与菜单机制——路由和菜单由后端动态返回，前端只需注册路由组件映射。 +- [前端页面视图](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume2/fe-view.html): 前端页面视图是用户直接交互的界面，本页讲解 Vue3 + ElementPlus 下一个完整 CRUD 页面的文件组成与编写方式。 +- [数据模型（Model）](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume2/model.html): 实际开发中不需要手写 DDL。 +- [概述与目标](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume2/overview.html): 本章以岗位管理（Position）模块为完整案例，手把手演示从零开发一个业务模块的全流程，学完即可掌握项目中任意模块的开发方式。 +- [权限节点配置](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume2/permission.html): 实际开发中，查询类权限（page、detail、list）通常合并为一个节点 sys:position:list，减少配置工作量。 +- [Repository 层](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume2/repository.html): Repository 层是数据访问层，封装全部数据库查询操作，本页讲解基于 BaseRepository 基类的通用 CRUD 用法。 +- [路由注册](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume2/router.html): 路由注册是将模块 Endpoint 挂载到应用的过程，本页讲解在 router.py 中统一注册模块路由的方法。 +- [Pydantic Schema](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume2/schema.html): Schema 层负责请求数据校验，本页讲解基于 Pydantic v2 BaseModel 与 Field 的表单类定义规范。 +- [Service 层](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume2/service.html): Service 层是业务逻辑层，本页讲解基于 BaseService 基类声明差异点即可获得完整增删改查能力的编写方式。 + +## 4. 架构设计 + +- [核心基类体系](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume3/base-classes.html): 五大基类各司其职，覆盖从数据模型到请求校验再到业务逻辑的完整链路。 +- [缓存架构设计](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume3/cache.html): 采用两级缓存架构：第一级为进程内字典缓存（dict_util），第二级为 Redis 分布式缓存。 +- [数据库设计](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume3/database-design.html): 所有业务表继承 base_model 基类，自动获得 6 个通用字段（id / create_user / create_time / update_user / update_time / +- [目录结构设计](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume3/directory.html): 目录结构遵循「按功能分组、按职责分层」的原则。 +- [扩展性设计](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume3/extensibility.html): 遵循开闭原则（OCP）：对扩展开放，对修改关闭。 +- [分层架构设计](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume3/layer-arch.html): 采用经典的三层架构，核心原则是：依赖单向、职责单一、接口隔离。 +- [整体架构图](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume3/overview.html): 遵循以下架构设计原则，确保系统在长期演进中保持高质量和可维护性： +- [请求完整链路](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume3/request-flow.html): 一个典型的 API 请求经过以下阶段：浏览器 → Nginx → CORS → 限流 → 上传体积限制 → 请求计时 → Token 续签 → 操作日志 → DB 会话 → Redis 注入 → +- [安全架构设计](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume3/security.html): 纵深防御：认证、授权、限流、参数校验多层防护，单一防线失效时仍有其他机制兜底 最小权限：用户仅能访问已授权接口，角色权限按需分配，遵循"够用即可"原则 数据不落地：敏感信息（Token、 +- [同步/异步设计决策](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume3/sync-async.html): FastAPI 基于 ASGI 异步框架，但并非所有端点都需要 async def。 +- [技术选型说明](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume3/tech-stack.html): FastAPI 基于 ASGI 原生异步、类型提示驱动的自动文档、Pydantic v2 的高性能校验，使其在构建 RESTful API 时具有显著优势。 + +## 5. 开发指南 + +- [API 接口速查表](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/api-cheatsheet.html): API 接口速查表，按模块分组列出所有 RESTful 接口的请求方法、路径、说明和权限标识。 +- [文章管理](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/business/article.html): 文章管理模块支持富文本编辑、分类关联、封面图片上传、图集管理等功能。 +- [分类管理](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/business/category.html): 分类管理模块用于管理树形分类数据，如文章分类、产品分类等。 +- [公告与链接管理](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/business/content.html): 公告、链接、城市是三个简单 CRUD 内容模块，均继承 BaseService，提供标准的增删改查接口。 +- [部门/职级/岗位管理](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/business/dept.html): 部门、职级、岗位是组织架构管理的三个核心模块。 +- [定时任务](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/business/job.html): 定时任务模块基于 APScheduler 实现，支持 Cron 表达式调度、任务执行日志、动态启停等功能。 +- [菜单管理](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/business/menu.html): 菜单管理是 RBAC 权限系统的基础，负责管理系统的导航菜单和权限节点。 +- [参数管理](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/business/param.html): 参数管理模块用于管理动态系统参数，与系统配置模块类似但更侧重于业务参数的灵活配置。 +- [角色管理](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/business/role.html): 角色是 RBAC 权限模型的核心，连接用户和菜单（权限）。 +- [用户管理](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/business/user.html): 用户管理是系统的核心模块，属于复杂业务模块。 +- [认证流程实战](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/core/auth-flow.html): 登录 → Token 获取 → 权限校验 → Token 刷新 → 退出登录的完整认证链路实战说明。 +- [验证码机制](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/core/captcha.html): 验证码是防止自动化攻击的重要安全手段。 +- [系统配置管理](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/core/config.html): 系统配置模块用于管理动态的键值对配置项，与数据字典类似但更偏向系统级参数。 +- [跨域资源共享（CORS）](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/core/cors.html): CORS（Cross-Origin Resource Sharing）跨域资源共享是前后端分离架构必须处理的问题。 +- [演示模式](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/core/demo-mode.html): 演示模式用于在线体验环境，开启后所有写操作（新增、编辑、删除等）将被拦截，返回"演示环境，暂无操作权限"提示。 +- [数据字典使用指南](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/core/dict-guide.html): 数据字典的完整使用流程，从新增字典类型到在代码中使用字典数据的实操指南。 +- [字典模块](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/core/dict.html): 数据字典用于管理系统中的枚举值和配置项，如状态、类型、性别等。 +- [异常与响应处理](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/core/exception.html): 定义了统一的响应格式和全局异常处理机制。 +- [防重复提交](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/core/idempotent.html): 防重复提交是保障数据一致性的重要措施。 +- [用户认证（JWT）](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/core/jwt.html): JWT（JSON Web Token）是的核心认证机制。 +- [登录日志](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/core/login-log.html): 登录日志记录每次登录尝试（成功/失败），包含登录账号、IP地址、浏览器信息、登录时间等。 +- [操作日志](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/core/operation-log.html): 操作日志中间件自动拦截写请求（POST/PUT/DELETE/PATCH）并记录操作日志，无需手动埋点。 +- [请求限流](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/core/rate-limit.html): 请求限流中间件基于 Redis 实现 IP 级别的滑动窗口限流，防止恶意请求和 DoS 攻击。 +- [权限管理（RBAC）](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/core/rbac.html): 采用基于角色的访问控制（RBAC）模型，通过用户-角色-菜单三层关系实现细粒度的权限管理。 +- [参数验证（Pydantic）](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/core/validator.html): 使用 Pydantic v2 进行请求参数验证。 +- [API 层开发](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/frontend/api.html): 前端 API 层位于 src/api/ 目录，封装所有与后端的 HTTP 请求。 +- [前端构建](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/frontend/build.html): 前端使用 Vite 构建，支持开发服务器和生产构建。 +- [公共组件库](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/frontend/components.html): 项目提供丰富的公共组件，位于 ui/src/components/ 目录，基于 ElementPlus 二次封装，覆盖表格、表单、弹窗、上传、富文本编辑等常见场景。 +- [BasicForm 表单](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/frontend/form.html): BasicForm 位于 src/components/Form/src/BasicForm.vue，基于 ElementPlus 的 el-form 二次封装，通过 schemas +- [Hooks 组合式函数](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/frontend/hooks.html): 项目封装了一系列组合式函数（Hooks），位于 src/hooks/ 和 src/utils/ 目录，提供权限检查、异步 loading、防重复提交、实时时钟、项目配置等可复用逻辑。 +- [国际化](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/frontend/i18n.html): 当前项目仅支持中文界面，ElementPlus 使用中文语言包（zh-cn），所有界面文本直接硬编码在组件中。 +- [Modal 弹窗](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/frontend/modal.html): 项目提供 BasicModal 组件（src/components/Modal/src/BasicModal.vue）和原生 el-dialog 两种弹窗用法。 +- [权限指令 v-perm](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/frontend/perm-directive.html): v-perm 和 v-perms 是项目自定义的 Vue 指令，用于按钮级别的权限控制，无权限时自动从 DOM 中移除元素。 +- [路由与菜单](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/frontend/router.html): 前端路由基于 Vue Router 4 实现动态路由生成，菜单数据从后端获取，通过 generator-routers.ts 递归生成路由表，路由守卫控制登录状态和权限。 +- [前端环境与结构](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/frontend/setup.html): 前端基于 Vue3 + ElementPlus 构建，使用 pnpm 作为包管理工具，Vite 作为构建工具，TypeScript 作为开发语言。 +- [Store 状态管理](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/frontend/store.html): 前端使用 Pinia 进行状态管理，核心模块包括 user（用户信息与权限）、asyncRoute（动态路由与菜单）、projectSetting（项目配置）、designSetting（主题设计）等。 +- [样式与主题](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/frontend/style.html): 前端样式方案采用 Tailwind CSS + SCSS + ElementPlus 主题覆盖，支持深色模式切换。 +- [BasicTable 表格](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/frontend/table.html): BasicTable 位于 src/components/Table/src/Table.vue，基于 ElementPlus 的 el-table 二次封装，提供列定义、数据请求、分页、操作列、 +- [工具函数](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/frontend/utils.html): 前端工具函数位于 src/utils/ 目录，提供认证管理、本地存储、日期格式化、树结构操作、文件下载等通用能力。 +- [页面视图开发](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/frontend/view.html): 页面视图位于 src/views/ 目录，每个业务模块遵循 index.vue（列表页）+ edit.vue（编辑弹窗）的标准模式，辅以 columns.ts（列定义）和 +- [接口响应规范](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/integration/api-contract.html): 后端所有接口统一返回 R.ok() / R.failed() 格式的 JSON 响应，前端通过 VAxios 的 transformRequestData 拦截器统一解包处理。 +- [字典数据联调](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/integration/dict-sync.html): 字典数据通过后端字典 API 获取，前端在下拉选择器中渲染选项。 +- [权限节点联动](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/integration/perm-sync.html): 前后端权限通过统一的权限节点字符串联动，后端 @permission_required 校验权限，前端 v-perm 指令和 TableAction 的 auth 属性控制按钮显示。 +- [代理配置](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/integration/proxy.html): 开发环境通过 Vite 代理转发 API 请求到后端，生产环境通过 Nginx 代理。 +- [文件上传联调](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/integration/upload-sync.html): 文件上传涉及前端 Upload 组件、后端上传接口和 URL 拼接三个环节，需要前后端协同配置。 +- [数据库会话](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/tools/db-session.html): 通过 contextvars + Starlette 中间件实现请求级数据库会话管理，写操作按业务成功与否自动 commit/rollback。 +- [导入导出](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/tools/excel.html): 基于 openpyxl 实现 Excel 导入导出功能，支持通过 file_template 模块管理导入模板配置。 +- [IP/UA 解析](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/tools/ip-ua.html): 提供客户端 IP 获取、IP 地理位置查询和 User-Agent 解析三大能力。 +- [日志系统](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/tools/logger.html): 通过 Python 标准库 logging 实现结构化日志，支持控制台 + 文件双输出，日志文件按大小自动轮转。 +- [密码工具](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/tools/password.html): 采用 bcrypt 双重加盐方案存储密码，源码位于 src/core/password.py。 +- [权限缓存](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/tools/perm-cache.html): 通过 Redis 实现用户权限和菜单的缓存，采用用户级缓存 + 全局版本号双层策略。 +- [请求解析工具](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/tools/request-util.html): src/utils/request.py 提供请求数据解析相关的工具函数，包括批量 ID 解析、SQL LIKE 安全处理、分页参数解析等。 +- [富文本过滤](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/tools/rich-text.html): 富文本编辑器内容存在存储型 XSS 风险，通过 bleach 库实现 HTML 白名单清洗，在落盘前统一过滤危险内容。 +- [文件上传完整流程](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/tools/upload-guide.html): 富文本编辑器（如 TinyMCE、CKEditor、WangEditor 等）的图片上传同样使用此接口。 +- [文件上传](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume4/tools/upload.html): 提供本地文件上传功能，支持图片和通用文件上传，内置扩展名白名单、大小限制、魔术字节校验和路径遍历防护。 + +## 6. 代码生成器 + +- [CLI 命令行使用](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume5/cli.html): 代码生成器 CLI 模式的使用方法，包括单表生成、批量生成、预览模式和配置导出。 +- [代码生成引擎](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume5/code-engine.html): 代码生成引擎的工作原理，包括配置解析、模板渲染、文件写入和自动注册的完整流程。 +- [配置文件详解](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume5/config.html): 代码生成器 JSON 配置文件的格式说明，包括模块名称、字段属性、字典编码等配置项的详细解释。 +- [实战案例](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume5/demo.html): 以 fastapi_example 演示表为完整案例，演示从建表到生成到使用的全流程。 +- [常见问题](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume5/faq.html): 代码生成器使用过程中常见问题的原因分析和解决方案。 +- [概述与架构](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume5/overview.html): 代码生成器的整体架构、核心模块和生成流程概述。 +- [表结构解析引擎](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume5/parser.html): 表结构解析引擎的工作原理，从数据库读取表元数据并智能推断字段用途的过程。 +- [自定义模板](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume5/templates.html): 代码生成器模板的 Jinja2 语法说明，包括模板变量、字段属性和自定义模板的开发方法。 +- [Web 管理界面](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume5/web-ui.html): 代码生成器 Web 管理界面的使用方法，通过可视化界面操作单表生成和批量生成。 + +## 7. 运维部署 + +- [备份与恢复](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume6/backup.html): - 3 份数据副本（1 份生产 + 2 份备份） - 2 种不同存储介质（如本地磁盘 + 远程存储） - 1 份异地备份（防机房级灾难） +- [数据库迁移](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume6/db-migrate.html): - 结构迁移：Alembic（自动生成 DDL 差异） - 数据迁移：scripts/migrate_db.py（跨库数据泵） - 初始化：scripts/init_db.py（全新安装一键建库） +- [部署 Checklist](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume6/deploy-checklist.html): 从服务器准备到应用上线的完整部署操作清单，适用于生产环境首次部署和后续版本更新。 +- [Docker容器化](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume6/docker.html): - 环境一致性：消除"在我机器上能跑"的问题 - 快速部署：一条命令启动完整服务 - 资源隔离：应用与宿主机环境解耦 +- [环境规划](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume6/env-plan.html): 各环境之间保持代码一致，仅通过环境变量（.env）区分配置。 +- [健康检查与监控](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume6/monitoring.html): `` 1. 应用层：健康检查端点、业务指标 2. 系统层：CPU/内存/磁盘/网络 3. 中间件：MySQL/Redis 连接状态 4. 日志：集中式日志收集与分析 `` +- [Nginx 反向代理](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume6/nginx.html): `` 客户端 → Nginx（80/443） ├─ / → 前端静态资源（dist/） ├─ /api/v1/... → FastAPI 后端（8031） └─ /api/file/ → +- [性能调优](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume6/performance.html): 1. 先测量，后优化：用数据说话，避免盲目调参 2. 瓶颈优先：找到最大瓶颈，集中优化 3. 渐进式：每次只调整一个参数，观察效果 +- [安全加固](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume6/security-hardening.html): - 最小权限：只开放必要的端口和权限 - 纵深防御：多层安全措施叠加 - 默认安全：配置默认值应为安全选项 +- [Supervisor进程管理](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume6/supervisor.html): - Linux 服务器直接部署（非 Docker） - 需要进程自动重启和日志轮转 - 管理多个相关进程 +- [故障排查手册](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume6/troubleshooting.html): 1. 查看日志：tail -f logs/supervisor.out.log 或 docker-compose logs -f 2. 检查配置：.env 文件、数据库连接、Redis 连接 3. +- [版本升级流程](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume6/upgrade.html): 1. 先备份，后升级 2. 先测试环境，后生产环境 3. 每次升级可回滚 4. 低峰期执行升级 + +## 8. 规范标准 + +- [API响应规范](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume7/api-response.html): - 所有接口必须通过 R.ok() 或 R.failed() 返回，禁止直接返回 dict - 成功响应 code=0，失败响应 code=1 - 响应体始终包含 code、data、msg、ok +- [代码审查清单](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume7/code-review.html): - 每次提交必须经过至少一人审查 - 审查关注点：正确性 > 安全性 > 可维护性 > 性能 - 审查意见应具体、可操作，避免主观评价 +- [删除规范](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume7/deletion.html): - is_delete = 0：正常记录（默认值） - is_delete = 1：已删除记录 - 所有查询方法自动过滤 is_delete = 0，业务层无需关心 +- [文档规范](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume7/doc-standard.html): - 文档与代码同步更新 - 使用中文编写（项目约定） - 示例代码可直接运行 +- [Endpoint层规范](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume7/endpoint.html): - Endpoint 只做请求分发，不含业务逻辑 - 通过装饰器控制权限和演示模式 - 委托 Service 处理业务逻辑 - 返回 R 封装的响应 +- [前端 API 规范](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume7/fe-api.html): - 每个后端模块对应一个 API 文件 - 函数命名统一使用 名词 + 动词 格式（与后端保持一致） - 请求路径使用相对路径（/position/page），不含 /api/v1 前缀（由 +- [前端页面规范](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume7/fe-component.html): - Vue3（Composition API + <script setup>） - ElementPlus - 自定义组件（BasicTable / BasicForm / TableAction +- [Git提交规范](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume7/git.html): `` <type>(<scope>): <subject> <body> <footer> `` +- [分页规范](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume7/pagination.html): - 前端传递 pageNo（页码，从 1 开始）和 pageSize（每页条数） - 后端返回 {records, total, size, current, pages} 结构 - 默认每页 10 +- [Pydantic Schema规范](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume7/pydantic.html): - 请求体参数必须声明为 Pydantic 模型（Form 类） - 字段约束使用 Field(...) 定义 - 自定义校验使用 @field_validator - 唯一性校验在 Schema +- [Repository层规范](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume7/repository.html): - Repository 只做数据访问原语，不处理 R 封装/序列化/业务逻辑 - 软删除由基类自动处理，子类无需关心 - 查询方法自动跳过 None 值条件 +- [Service层规范](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume7/service.html): BaseService 采用模板方法模式：基类定义流程骨架，子类通过声明差异点和覆盖钩子定制行为。 +- [测试规范](http://docs.fastapi.elevue.djangoadmin.cn/zh/volume7/testing.html): 1. 契约测试（Contract）：验证路由、权限、表名等契约不变 2. 单元测试（Unit）：验证单个函数/方法的逻辑正确性 3. 集成测试（Integration）：验证模块间协作、真实数据库操作 + +## 附录 + +- [常见问题汇总](http://docs.fastapi.elevue.djangoadmin.cn/zh/faq.html): 本页汇总了项目各模块的常见问题及解决方案，按场景分类索引。 +- [免责声明](http://docs.fastapi.elevue.djangoadmin.cn/zh/other/declare.html): 使用本产品前必读的法律声明，明确产品性质、使用限制与责任划分，一旦使用本产品即视为接受本声明全部条款。 +- [广告赞助](http://docs.fastapi.elevue.djangoadmin.cn/zh/other/sponsor.html): 1. 投放广告不得与官方全系产品存在结构性冲突和竞争 2. 广告内容需符合国家法律法规，不得包含虚假、误导性信息 3. 广告素材需经官方审核通过后方可上线，审核周期 1-3 个工作日 4. diff --git a/DjangoAdmin_FastAPI_EleVue/public/robots.txt b/DjangoAdmin_FastAPI_EleVue/public/robots.txt new file mode 100644 index 0000000..92c18ea --- /dev/null +++ b/DjangoAdmin_FastAPI_EleVue/public/robots.txt @@ -0,0 +1,33 @@ +# DjangoAdmin FastAPI+ElementPlus 开发文档 +User-agent: * +Allow: / + +# 显式放行生成式引擎 / AI 爬虫（GEO） +User-agent: GPTBot +Allow: / + +User-agent: ChatGPT-User +Allow: / + +User-agent: ClaudeBot +Allow: / + +User-agent: Claude-Web +Allow: / + +User-agent: anthropic-ai +Allow: / + +User-agent: PerplexityBot +Allow: / + +User-agent: Google-Extended +Allow: / + +User-agent: Bytespider +Allow: / + +User-agent: bingbot +Allow: / + +Sitemap: http://docs.fastapi.elevue.djangoadmin.cn/sitemap.xml diff --git a/DjangoAdmin_FastAPI_EleVue/scripts/generate-llms-txt.mjs b/DjangoAdmin_FastAPI_EleVue/scripts/generate-llms-txt.mjs new file mode 100644 index 0000000..bcb61e8 --- /dev/null +++ b/DjangoAdmin_FastAPI_EleVue/scripts/generate-llms-txt.mjs @@ -0,0 +1,122 @@ +#!/usr/bin/env node +/** + * 生成 public/llms.txt（llmstxt.org 标准）——AI 爬虫的站点摘要索引。 + * + * 数据源：zh 目录下全部 Markdown 的 H1 + :::tip 概述首句（与 meta + * description 同源，复用 .vitepress/config/extract.mjs）。按侧边栏章节分组。 + * + * 用法：node scripts/generate-llms-txt.mjs + * 已挂入 package.json 的 docs:build 前置步骤。 + */ +import fs from "node:fs"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; +import { + SITE_URL, + SITE_DESCRIPTION, + extractDescription, +} from "../.vitepress/config/extract.mjs"; + +const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."); +const ZH = path.join(ROOT, "zh"); + +/** 顶层目录 → 侧边栏章节名（与 .vitepress/config/zh.ts 保持一致） */ +const SECTIONS = [ + ["", "1. 了解项目"], + ["volume1", "2. 快速入门"], + ["volume2", "3. 模块开发实战"], + ["volume3", "4. 架构设计"], + ["volume4", "5. 开发指南"], + ["volume5", "6. 代码生成器"], + ["volume6", "7. 运维部署"], + ["volume7", "8. 规范标准"], + ["other", "附录"], +]; + +function walk(dir, out = []) { + for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { + const p = path.join(dir, entry.name); + if (entry.isDirectory()) walk(p, out); + else if (entry.name.endsWith(".md")) out.push(p); + } + return out; +} + +/** 提取首个 H1 文本 */ +function h1Of(md) { + // 围栏感知：跳过 ``` 代码块内的 # 注释，取真正的页面 H1 + let inFence = false; + for (const line of md.split("\n")) { + if (line.startsWith("```")) { inFence = !inFence; continue; } + if (!inFence && line.startsWith("# ") && !line.startsWith("## ")) { + return line.slice(2).trim(); + } + } + return ""; +} + +/** H1 编号排序键："5.10 x" → [5,10]；无编号排最后 */ +function sortKey(h1) { + const m = h1.match(/^(\d+(?:\.\d+)*)/); + if (m) return m[1].split(".").map(Number); + const letter = h1.match(/^([A-Z])\./); + if (letter) return [1000 + letter[1].charCodeAt(0)]; + return [9999]; +} + +function cmpKey(a, b) { + const len = Math.max(a.length, b.length); + for (let i = 0; i < len; i++) { + const x = a[i] ?? 0; + const y = b[i] ?? 0; + if (x !== y) return x - y; + } + return 0; +} + +const files = walk(ZH); +const groups = new Map(SECTIONS.map(([dir, label]) => [label, []])); + +for (const file of files) { + const rel = path.relative(ZH, file).replace(/\\/g, "/"); + const topDir = rel.includes("/") ? rel.split("/")[0] : ""; + const base = rel.split("/").pop(); + const label = (topDir === "" && base === "faq.md") ? "附录" + : SECTIONS.find(([dir]) => dir === topDir)?.[1] ?? "附录"; + + const md = fs.readFileSync(file, "utf8"); + const h1 = h1Of(md); + if (!h1) continue; + const desc = extractDescription(md); + const url = `${SITE_URL}/zh/${rel.replace(/\.md$/, ".html")}`; + groups.get(label).push({ h1, desc, url, key: sortKey(h1) }); +} + +const lines = [ + "# DjangoAdmin FastAPI+ElementPlus 开发文档", + "", + `> ${SITE_DESCRIPTION}。内置 RBAC 权限体系、代码生成器等开箱即用功能，支持五种数据库一键切换。本文档共 ${files.length} 篇，按章节组织。`, + "", +]; + +// 按章节顺序输出，合并重复 label（appendix/other 同为「附录」，只输出一次） +const printed = new Set(); +for (const [, label] of SECTIONS) { + if (printed.has(label)) continue; + const items = groups.get(label); + if (!items?.length) continue; + printed.add(label); + + lines.push(`## ${label}`, ""); + items.sort((a, b) => cmpKey(a.key, b.key)); + for (const { h1, desc, url } of items) { + lines.push(desc ? `- [${h1}](${url}): ${desc}` : `- [${h1}](${url})`); + } + lines.push(""); +} + +const out = path.join(ROOT, "public", "llms.txt"); +fs.writeFileSync(out, lines.join("\n"), "utf8"); +console.log( + `llms.txt: ${files.length} 页 → ${path.relative(ROOT, out)} (${printed.size} 个章节)`, +); diff --git a/DjangoAdmin_FastAPI_EleVue/zh/course.md b/DjangoAdmin_FastAPI_EleVue/zh/course.md index 669deef..c2ae62a 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/course.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/course.md @@ -1,3 +1,5 @@ +# 新手入门指南 + :::warning 特别提醒 官方精心制作本教程，目的在于方便用户快速掌握软件产品的使用和部署。通过此教程，刚入行的开发者也可以快速掌握并投入产品研发。本地部署时务必请耐心阅读文档操作。 ::: diff --git a/DjangoAdmin_FastAPI_EleVue/zh/introduction.md b/DjangoAdmin_FastAPI_EleVue/zh/introduction.md index fd3aeb1..09625aa 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/introduction.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/introduction.md @@ -1,3 +1,9 @@ +# 1.1 项目介绍 + +:::tip 概述 +DjangoAdmin 是企业级中台解决方案，后端基于 FastAPI + SQLAlchemy，前端基于 Vue3 + ElementPlus，内置 RBAC 权限、代码生成器等开箱即用功能，支持五种数据库一键切换。 +::: + <div align="center"> <p align="center"> <img src="/logo.png" height="150" alt="logo"/> @@ -75,10 +81,10 @@ | Flask+ElementPlus前后端分离版 | 基于 Flask、SQLAlchemy、WTForms、Vue3、ElementPlus、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Flask_EleVue) | | Flask+AntDesign前后端分离版 | 基于 Flask、SQLAlchemy、WTForms、Vue3、AntDesign、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Flask_AntdVue) | | Flask+NaiveUI前后端分离版 | 基于 Flask、SQLAlchemy、WTForms、Vue3、NaiveUI、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Flask_NaiveVue) | -| FastAPI+Layui混编版 | 基于 FastAPI、Jinja2、Layui 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_Layui) | -| FastAPI+ElementPlus前后端分离版 | 基于 FastAPI、SQLAlchemy、Pydantic、Vue3、ElementPlus、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_EleVue) | -| FastAPI+AntDesign前后端分离版 | 基于 FastAPI、SQLAlchemy、Pydantic、Vue3、AntDesign、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_AntdVue) | -| FastAPI+NaiveUI前后端分离版 | 基于 FastAPI、SQLAlchemy、Pydantic、Vue3、NaiveUI、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_NaiveVue) | +| FastAPI+Layui混编版 | 基于 FastAPI、Jinja2、Layui 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_FastAPI_Layui) | +| FastAPI+ElementPlus前后端分离版 | 基于 FastAPI、SQLAlchemy、Pydantic、Vue3、ElementPlus、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_FastAPI_EleVue) | +| FastAPI+AntDesign前后端分离版 | 基于 FastAPI、SQLAlchemy、Pydantic、Vue3、AntDesign、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_FastAPI_AntdVue) | +| FastAPI+NaiveUI前后端分离版 | 基于 FastAPI、SQLAlchemy、Pydantic、Vue3、NaiveUI、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_FastAPI_NaiveVue) | | Tornado+Layui混编版 | 基于 Tornado、Jinja2、Layui 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Tornado_Layui) | | Tornado+ElementPlus前后端分离版 | 基于 Tornado、SQLAlchemy、Pydantic、Vue3、ElementPlus、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Tornado_EleVue) | | Tornado+AntDesign前后端分离版 | 基于 Tornado、SQLAlchemy、Pydantic、Vue3、AntDesign、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Tornado_AntdVue) | diff --git a/DjangoAdmin_FastAPI_EleVue/zh/other/declare.md b/DjangoAdmin_FastAPI_EleVue/zh/other/declare.md index 7737479..915692a 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/other/declare.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/other/declare.md @@ -1,5 +1,9 @@ # 免责声明 +:::tip 概述 +使用本产品前必读的法律声明，明确产品性质、使用限制与责任划分，一旦使用本产品即视为接受本声明全部条款。 +::: + :::danger 重要提示 任何用户在使用本团队研发的系列软件产品（以下简称「本产品」）前，请仔细阅读并透彻理解本声明。选择不使用本产品，可随时停止使用；一旦使用本产品，即视为对本声明全部内容的认可和接受。 ::: diff --git a/DjangoAdmin_FastAPI_EleVue/zh/struct.md b/DjangoAdmin_FastAPI_EleVue/zh/struct.md index d88d168..8be8f26 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/struct.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/struct.md @@ -1,3 +1,9 @@ +# 项目目录结构 + +:::tip 概述 +本页说明项目前后端目录组织与各目录职责，二次开发定位文件或了解工程结构时对照查阅。 +::: + ## 目录说明 在软件开发过程中，优秀的软件目录结构对于项目的组织、开发、维护和扩展至关重要，合理的目录结构能够显著提升开发效率和代码可维护性。 diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume2/code-list.md b/DjangoAdmin_FastAPI_EleVue/zh/volume2/code-list.md index a70f423..b5b577b 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume2/code-list.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume2/code-list.md @@ -1,5 +1,9 @@ # 完整代码清单 +:::tip 概述 +本页汇总岗位管理（Position）模块涉及的全部文件代码，开发时可快速查阅与复制对照。 +::: + 本章汇总 Position 岗位模块涉及的全部文件，便于开发时快速查阅和复制。 ## 后端文件清单 diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume2/endpoint.md b/DjangoAdmin_FastAPI_EleVue/zh/volume2/endpoint.md index 12d7528..c5a5aa8 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume2/endpoint.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume2/endpoint.md @@ -1,5 +1,9 @@ # Endpoint 层 +:::tip 概述 +Endpoint 层是 HTTP 接口层，负责定义路由、权限装饰器与请求参数绑定，编写新接口从本页开始。 +::: + Endpoint 层是 HTTP 接口层，负责定义路由、权限装饰器和请求参数绑定。每个业务模块对应一个 endpoint 文件，所有业务逻辑委托给 Service 层处理。 ## 文件位置 diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume2/faq.md b/DjangoAdmin_FastAPI_EleVue/zh/volume2/faq.md index 9e25482..5e4b074 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume2/faq.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume2/faq.md @@ -1,5 +1,9 @@ # 常见问题与排错 +:::tip 概述 +本页汇总模块开发过程中的常见问题与排错方法，开发受阻时按症状索引即可定位。 +::: + 本章汇总模块开发过程中的常见问题和解决方案。 ## 后端问题 diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume2/fe-api.md b/DjangoAdmin_FastAPI_EleVue/zh/volume2/fe-api.md index 797cc1c..ae9203a 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume2/fe-api.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume2/fe-api.md @@ -1,5 +1,9 @@ # 前端 API 层 +:::tip 概述 +前端 API 层封装后端接口的 HTTP 请求，每个业务模块对应一个 API 文件，本页讲解基于 Axios 封装的编写规范。 +::: + 前端 API 层负责封装后端接口的 HTTP 请求。每个业务模块对应一个 API 文件，使用项目封装的 Axios 工具发送请求。 ## 文件位置 diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume2/fe-router.md b/DjangoAdmin_FastAPI_EleVue/zh/volume2/fe-router.md index 0f79bbe..5c2330b 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume2/fe-router.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume2/fe-router.md @@ -1,5 +1,9 @@ # 前端路由与菜单 +:::tip 概述 +本页讲解前端路由与菜单机制——路由和菜单由后端动态返回，前端只需注册路由组件映射。 +::: + 前端路由定义页面的访问路径，菜单是路由的可视化展示。项目的路由和菜单由后端动态返回，前端只需注册路由组件映射。 ## 路由配置 diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume2/fe-view.md b/DjangoAdmin_FastAPI_EleVue/zh/volume2/fe-view.md index 3639881..fd245a4 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume2/fe-view.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume2/fe-view.md @@ -1,5 +1,9 @@ # 前端页面视图 +:::tip 概述 +前端页面视图是用户直接交互的界面，本页讲解 Vue3 + ElementPlus 下一个完整 CRUD 页面的文件组成与编写方式。 +::: + 前端页面视图是用户直接交互的界面。项目使用 Vue3 + ElementPlus + Vite 构建。一个完整的 CRUD 页面由 4 个文件组成： ``` diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume2/overview.md b/DjangoAdmin_FastAPI_EleVue/zh/volume2/overview.md index d27c6f5..660bbe0 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume2/overview.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume2/overview.md @@ -1,5 +1,9 @@ # 概述与目标 +:::tip 概述 +本章以岗位管理（Position）模块为完整案例，手把手演示从零开发一个业务模块的全流程，学完即可掌握项目中任意模块的开发方式。 +::: + 本章以「岗位管理（Position）」模块为完整案例，手把手演示从零开发一个业务模块的全流程。学完本章后，你将掌握项目中任意模块的开发方式。 ## 你将学到什么 diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume2/repository.md b/DjangoAdmin_FastAPI_EleVue/zh/volume2/repository.md index f268212..f530306 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume2/repository.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume2/repository.md @@ -1,5 +1,9 @@ # Repository 层 +:::tip 概述 +Repository 层是数据访问层，封装全部数据库查询操作，本页讲解基于 BaseRepository 基类的通用 CRUD 用法。 +::: + Repository 层是数据访问层，封装所有数据库查询操作。项目通过 `BaseRepository` 基类提供通用 CRUD 能力，子类通常只需声明类名，无需编写任何代码。 ## 文件位置 diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume2/router.md b/DjangoAdmin_FastAPI_EleVue/zh/volume2/router.md index 2fe9b5e..dfe5dd4 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume2/router.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume2/router.md @@ -1,5 +1,9 @@ # 路由注册 +:::tip 概述 +路由注册是将模块 Endpoint 挂载到应用的过程，本页讲解在 router.py 中统一注册模块路由的方法。 +::: + 路由注册是将模块的 Endpoint 挂载到应用的过程。所有模块的路由在 `src/api/v1/router.py` 中统一注册。 ## 文件位置 diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume2/schema.md b/DjangoAdmin_FastAPI_EleVue/zh/volume2/schema.md index 4013bcd..1ca3fcd 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume2/schema.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume2/schema.md @@ -1,5 +1,9 @@ # Pydantic Schema +:::tip 概述 +Schema 层负责请求数据校验，本页讲解基于 Pydantic v2 BaseModel 与 Field 的表单类定义规范。 +::: + Schema 层负责请求数据的校验。项目使用 Pydantic v2 的 `BaseModel` 定义表单类，通过 `Field` 约束字段格式，FastAPI 在接收请求体时自动执行校验。 ## 文件位置 diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume2/service.md b/DjangoAdmin_FastAPI_EleVue/zh/volume2/service.md index 84a1b32..a642ed9 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume2/service.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume2/service.md @@ -1,5 +1,9 @@ # Service 层 +:::tip 概述 +Service 层是业务逻辑层，本页讲解基于 BaseService 基类声明差异点即可获得完整增删改查能力的编写方式。 +::: + Service 层是业务逻辑层，负责实现具体的业务规则。简单 CRUD 模块继承 `BaseService` 基类，只需声明差异点即可获得完整的增删改查能力。 ## 文件位置 diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/article.md b/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/article.md index bea27f6..08483a8 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/article.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/article.md @@ -1,3 +1,5 @@ +# 文章管理 + :::tip 文章管理 文章管理模块支持富文本编辑、分类关联、封面图片上传、图集管理等功能。适用于新闻、公告、帮助文档等内容管理场景。本模块是典型的「带文件处理」业务模块，涵盖了封面迁移、图集处理、富文本 XSS 清洗等核心机制。 ::: diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/category.md b/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/category.md index a5daffe..20ea7d1 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/category.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/category.md @@ -1,3 +1,5 @@ +# 分类管理 + :::tip 分类管理 分类管理模块用于管理树形分类数据，如文章分类、产品分类等。通过 `parent_id` 字段实现无限级分类。 ::: diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/content.md b/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/content.md index 8a1005a..2fb2a91 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/content.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/content.md @@ -1,3 +1,5 @@ +# 公告与链接管理 + :::tip 公告/链接/城市 公告、链接、城市是三个简单 CRUD 内容模块，均继承 BaseService，提供标准的增删改查接口。适用于系统公告、友情链接、城市数据等场景。 ::: diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/dept.md b/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/dept.md index 374223a..e184732 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/dept.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/dept.md @@ -1,3 +1,5 @@ +# 部门/职级/岗位管理 + :::tip 部门/职级/岗位 部门、职级、岗位是组织架构管理的三个核心模块。部门采用树形结构，职级和岗位为简单 CRUD 模块，均继承 `BaseService`。用户表通过 `dept_id`、`position_id`、`level_id` 三个外键关联这三个模块。 ::: diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/job.md b/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/job.md index 6fdf1d8..6aa953e 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/job.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/job.md @@ -1,3 +1,5 @@ +# 定时任务 + :::tip 定时任务 定时任务模块基于 APScheduler 实现，支持 Cron 表达式调度、任务执行日志、动态启停等功能。包含 job（任务定义）、job_log（执行日志）、scheduler（调度器）三个子模块。 ::: diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/menu.md b/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/menu.md index 37776cb..9a66782 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/menu.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/menu.md @@ -1,3 +1,5 @@ +# 菜单管理 + :::tip 菜单管理 菜单管理是 RBAC 权限系统的基础，负责管理系统的导航菜单和权限节点。支持目录/菜单（type=0）和权限按钮节点（type=1）两种类型，通过树形结构组织。权限节点由系统根据前端勾选自动生成，采用 `sys:module:action` 三段式命名。 ::: diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/param.md b/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/param.md index 0ec1e7e..6287408 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/param.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/param.md @@ -1,3 +1,5 @@ +# 参数管理 + :::tip 参数管理 参数管理模块用于管理动态系统参数，与系统配置模块类似但更侧重于业务参数的灵活配置。支持按参数键查询、修改，无需重启服务即可生效。本模块是典型的「BaseService 简单模块」，通过声明差异点即可获得完整 CRUD 能力。 ::: diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/role.md b/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/role.md index 802641c..7bf4b88 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/role.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/role.md @@ -1,3 +1,5 @@ +# 角色管理 + :::tip 角色管理 角色是 RBAC 权限模型的核心，连接用户和菜单（权限）。通过为角色分配菜单权限，再将角色分配给用户，实现灵活的权限管理。角色删除时需清理关联的用户角色和角色菜单数据，并即时失效受影响用户的权限缓存。 ::: diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/user.md b/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/user.md index 7cc450c..33a074f 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/user.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume4/business/user.md @@ -1,3 +1,5 @@ +# 用户管理 + :::tip 用户管理 用户管理是系统的核心模块，属于复杂业务模块。包含用户 CRUD、角色关联、密码加密、行政区划、Excel 导入导出等功能。与简单 CRUD 模块不同，用户管理使用自定义 service 函数而非继承 BaseService 的类方法。 ::: diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/captcha.md b/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/captcha.md index c8a9b51..240e6b6 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/captcha.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/captcha.md @@ -1,3 +1,5 @@ +# 验证码机制 + :::tip 验证码 验证码是防止自动化攻击的重要安全手段。使用 Pillow 生成图片验证码，存储在 Redis 中，支持防刷限流和万能验证码（演示模式）。源码位于 `src/utils/captcha.py`。 ::: diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/config.md b/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/config.md index 9a26722..3d22e08 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/config.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/config.md @@ -1,3 +1,5 @@ +# 系统配置管理 + :::tip 系统配置 系统配置模块用于管理动态的键值对配置项，与数据字典类似但更偏向系统级参数。支持分组管理，可通过接口动态修改，无需重启服务。模块位于 `src/modules/configuration/`，端点位于 `src/api/v1/endpoints/config.py` 和 `config_item.py`。 ::: diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/cors.md b/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/cors.md index 58b0f89..7f4f409 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/cors.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/cors.md @@ -1,3 +1,5 @@ +# 跨域资源共享（CORS） + :::tip CORS跨域 CORS（Cross-Origin Resource Sharing）跨域资源共享是前后端分离架构必须处理的问题。通过 `CORS_ALLOWED_ORIGINS` 环境变量配置允许的跨域源。中间件位于 `src/middleware/cors.py`。 ::: diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/demo-mode.md b/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/demo-mode.md index 3b9651c..bce77fe 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/demo-mode.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/demo-mode.md @@ -1,3 +1,5 @@ +# 演示模式 + :::tip 演示模式 演示模式用于在线体验环境，开启后所有写操作（新增、编辑、删除等）将被拦截，返回"演示环境，暂无操作权限"提示。通过 `FASTAPI_DEMO` 环境变量控制。装饰器位于 `src/core/access_decorators.py`。 ::: diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/dict.md b/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/dict.md index 21a4f1a..5239054 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/dict.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/dict.md @@ -1,3 +1,5 @@ +# 字典模块 + :::tip 数据字典 数据字典用于管理系统中的枚举值和配置项，如状态、类型、性别等。通过字典编码统一管理，前端可通过 `useDictStore` 获取字典选项，避免硬编码。后端读取工具位于 `src/utils/dict_util.py`，内置进程内 TTL 缓存。 ::: diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/exception.md b/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/exception.md index 8da880b..c9bca69 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/exception.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/exception.md @@ -1,3 +1,5 @@ +# 异常与响应处理 + :::tip 全局异常与响应 定义了统一的响应格式和全局异常处理机制。所有 API 返回 `{code, data, msg, ok}` 标准格式，异常被捕获后也转换为相同格式。响应函数位于 `src/core/response.py`，异常类型位于 `src/core/exceptions.py`。 ::: diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/idempotent.md b/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/idempotent.md index 8ec8e15..ef990e4 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/idempotent.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/idempotent.md @@ -1,3 +1,5 @@ +# 防重复提交 + :::tip 防重复提交 防重复提交是保障数据一致性的重要措施。通过前端防抖和后端唯一性校验双重保护，防止用户重复点击导致的数据重复提交。后端唯一性校验通过 Pydantic `@field_validator` 查询数据库实现。 ::: diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/jwt.md b/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/jwt.md index 9983fab..2e756cc 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/jwt.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/jwt.md @@ -1,3 +1,5 @@ +# 用户认证（JWT） + :::tip JWT认证 JWT（JSON Web Token）是的核心认证机制。用户登录成功后获取 Token，后续请求通过 `Authorization: Bearer <token>` 头携带 Token 进行身份验证。项目内置了 Token 生成、解析、刷新和黑名单管理功能，源码位于 `src/core/jwt.py`。 ::: diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/login-log.md b/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/login-log.md index 3655d26..b5b5d47 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/login-log.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/login-log.md @@ -1,3 +1,5 @@ +# 登录日志 + :::tip 登录日志 登录日志记录每次登录尝试（成功/失败），包含登录账号、IP地址、浏览器信息、登录时间等。支持 IP 地理位置解析（ip2region）和 User-Agent 解析。登录逻辑位于 `src/modules/auth/service.py`，日志记录位于 `src/modules/login_log/service.py`。 ::: diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/operation-log.md b/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/operation-log.md index 9b09821..f77ba18 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/operation-log.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/operation-log.md @@ -1,3 +1,5 @@ +# 操作日志 + :::tip 操作日志 操作日志中间件自动拦截写请求（POST/PUT/DELETE/PATCH）并记录操作日志，无需手动埋点。日志落库通过 `response.background` 异步执行，不阻塞响应。源码位于 `src/middleware/operation_log.py`。 ::: diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/rate-limit.md b/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/rate-limit.md index d1b703a..d08213a 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/rate-limit.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/rate-limit.md @@ -1,3 +1,5 @@ +# 请求限流 + :::tip 请求限流 请求限流中间件基于 Redis 实现 IP 级别的滑动窗口限流，防止恶意请求和 DoS 攻击。默认关闭，可通过环境变量开启。源码位于 `src/middleware/rate_limit.py`，滑动窗口 Lua 脚本位于 `src/core/redis_client.py`。 ::: diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/rbac.md b/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/rbac.md index c253083..c0dd3fa 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/rbac.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/rbac.md @@ -1,3 +1,5 @@ +# 权限管理（RBAC） + :::tip RBAC权限 采用基于角色的访问控制（RBAC）模型，通过用户-角色-菜单三层关系实现细粒度的权限管理。权限控制贯穿前后端：后端通过 `@permission_required` 装饰器校验（`src/core/access_decorators.py`），前端通过 `v-perm` 指令控制按钮显隐。 ::: diff --git a/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/validator.md b/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/validator.md index 4993704..dbe4097 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/validator.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/volume4/core/validator.md @@ -1,3 +1,5 @@ +# 参数验证（Pydantic） + :::tip 参数验证 使用 Pydantic v2 进行请求参数验证。所有请求体参数通过 Pydantic BaseModel 定义，FastAPI 自动解析和验证 JSON 请求体，验证失败返回标准格式错误信息。BaseForm 基类位于 `src/core/base_schemas.py`。 ::: diff --git a/DjangoAdmin_FastAPI_EleVue/zh/why.md b/DjangoAdmin_FastAPI_EleVue/zh/why.md index 2739c65..15986bc 100644 --- a/DjangoAdmin_FastAPI_EleVue/zh/why.md +++ b/DjangoAdmin_FastAPI_EleVue/zh/why.md @@ -1,7 +1,7 @@ # 为什么选择我们？ :::tip 核心价值 -企业级数据中台不应从零搭建。本框架提供开箱即用的完整解决方案，为中大型企业构建统一的数字化基座。 +本框架提供开箱即用的企业级中台完整解决方案，免去从零搭建成本，助力中大型企业构建统一的数字化基座。 ::: ## 解决什么问题？ diff --git a/DjangoAdmin_FastAPI_NaiveVue/.vitepress/config/extract.d.mts b/DjangoAdmin_FastAPI_NaiveVue/.vitepress/config/extract.d.mts new file mode 100644 index 0000000..2a46233 --- /dev/null +++ b/DjangoAdmin_FastAPI_NaiveVue/.vitepress/config/extract.d.mts @@ -0,0 +1,5 @@ +export declare const SITE_URL: string; +export declare const SITE_DESCRIPTION: string; +export declare function stripNumberPrefix(title: string): string; +export declare function extractDescription(md: string): string; +export declare function extractFaqs(md: string): { q: string; a: string }[]; diff --git a/DjangoAdmin_FastAPI_NaiveVue/.vitepress/config/extract.mjs b/DjangoAdmin_FastAPI_NaiveVue/.vitepress/config/extract.mjs new file mode 100644 index 0000000..645fa96 --- /dev/null +++ b/DjangoAdmin_FastAPI_NaiveVue/.vitepress/config/extract.mjs @@ -0,0 +1,130 @@ +/** + * SEO/GEO 共享工具（纯 ESM，零依赖）。 + * + * 同时被两类调用方 import： + * 1. VitePress 配置（.ts，esbuild 打包时内联本文件） + * 2. scripts/generate-llms-txt.mjs（Node 直接运行） + * + * 注意：SITE_URL 是全站唯一 URL 真相源。 + * docs 子域当前 TLS 证书为腾讯 CDN 默认证书（*.cdn.myqcloud.com，校验失败）， + * 故暂用 http；证书修复后只需改这里一处。 + */ + +export const SITE_URL = "http://docs.fastapi.naivevue.djangoadmin.cn"; + +export const SITE_DESCRIPTION = + "DjangoAdmin 企业级中台解决方案 - FastAPI + NaiveUI 前后端分离版本"; + +/** + * 剥离 H1/标题中的章节编号前缀，用于 <title> 与 JSON-LD headline。 + * 例："5.10 字典模块" → "字典模块"；"K. 贡献指南" → "贡献指南"。 + * 页内 H1 与侧边栏编号保持不变，仅影响 SEO 输出。 + */ +export function stripNumberPrefix(title) { + return String(title) + .replace(/^(?:\d+(?:\.\d+)+|[A-Z]\.)\s+/, "") + .trim(); +} + +/** + * 从页面 Markdown 提取 meta description： + * 1. 首选 `:::tip xxx` 容器内的首句（141/143 页的标准 opener） + * 2. 回退到 H1 后的第一个普通段落 + * 输出压缩为单行、去除行内 Markdown，按中文句末标点截断（≤100 字符）。 + */ +export function extractDescription(md) { + const src = String(md); + const fm = src.match(/^---\r?\n([\s\S]*?)\r?\n---/); + const body = fm ? src.slice(fm[0].length) : src; + + let text = ""; + // frontmatter description 显式声明优先（无 H1 页面的补齐手段） + const fmDesc = fm && fm[1].match(/^description:\s*(.+)$/m); + if (fmDesc) { + text = fmDesc[1].trim().replace(/^["']|["']$/g, ""); + } + const tip = !text && body.match(/^:::\s*tip[^\n]*\n([\s\S]*?)\n:::/m); + if (tip) { + text = tip[1]; + } + if (!text) { + const afterH1 = body.match(/^# (?!#)(.+)$/m); + if (afterH1) { + const rest = body.slice((afterH1.index ?? 0) + afterH1[0].length); + const para = rest + .split(/\n{2,}/) + .find( + (p) => + p.trim() && + !/^\s*#/.test(p) && + !/^\s*:::/.test(p) && + !/^\s*```/.test(p) && + !/^\s*\|/.test(p), + ); + text = para || ""; + } + } + + text = text + .replace(/\s+/g, " ") + .replace(/`([^`]+)`/g, "$1") + .replace(/\*\*([^*]+)\*\*/g, "$1") + .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") + .trim(); + + if (!text) return ""; + + // 按中文句末标点截取首句，上限 100 字符；截断时避免切碎词 + const m = text.match(/^.{1,100}?(?:[。！？!?]|$)/); + let out = m ? m[0] : text.slice(0, 100); + if (out.length < text.length && !/[。！？!?]$/.test(out)) { + out = out.replace(/[^\s，、；：,;:]+$/, ""); + } + return out.trim() || text.slice(0, 100); +} + +function cleanText(s) { + return s + .replace(/^:::[^\n]*$/gm, "") + .replace(/^```[^\n]*$/gm, "") + .replace(/`([^`]+)`/g, "$1") + .replace(/\*\*([^*]+)\*\*/g, "$1") + .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") + .replace(/\s+/g, " ") + .trim(); +} + +/** + * 提取页面中的 Q/A 对（用于 FAQPage JSON-LD），支持两种站内格式： + * A. `### Q：问题` 标题式（如 zh/quickstart/faq.md） + * B. `**Q：问题**` 加粗式（如 zh/appendix/faq.md） + * 返回 [{ q, a }]；无匹配返回 []。 + */ +export function extractFaqs(md) { + const body = String(md).replace(/^---[\s\S]*?\n---\s*/, ""); + let faqs = []; + + // 格式 A：按 `### Q：` 切块，答案截断到下一个标题 + for (const part of body.split(/(?=^###\s*Q[：:])/m)) { + const m = part.match(/^###\s*Q[：:]\s*([^\n]+)\n+([\s\S]*)/); + if (!m) continue; + let a = m[2]; + const cut = a.search(/^#{1,4}\s/m); + if (cut >= 0) a = a.slice(0, cut); + faqs.push({ q: cleanText(m[1]), a: cleanText(a) }); + } + + // 格式 B：按 `**Q：` 切块 + if (!faqs.length) { + for (const part of body.split(/(?=^\*\*Q[：:])/m)) { + const m = part.match(/^\*\*Q[：:]\s*([^*]+)\*\*\s*\n+([\s\S]*)/); + if (!m) continue; + let a = m[2]; + const cut = a.search(/^(?:#{1,4}\s|\*\*Q)/m); + if (cut >= 0) a = a.slice(0, cut); + faqs.push({ q: cleanText(m[1]), a: cleanText(a) }); + } + } + + return faqs.filter((f) => f.q && f.a); +} diff --git a/DjangoAdmin_FastAPI_NaiveVue/.vitepress/config/index.ts b/DjangoAdmin_FastAPI_NaiveVue/.vitepress/config/index.ts index 2294856..6627a76 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/.vitepress/config/index.ts +++ b/DjangoAdmin_FastAPI_NaiveVue/.vitepress/config/index.ts @@ -1,14 +1,22 @@ import { defineConfig } from "vitepress"; import { enConfig } from "./en"; +import { createSeoHooks } from "./seo"; import { sharedConfig } from "./shared"; import { zhConfig } from "./zh"; +const seo = createSeoHooks(zhConfig.themeConfig?.sidebar); + export default defineConfig({ ...sharedConfig, ignoreDeadLinks: [ (link) => link.includes('localhost'), ], + // SEO：页面级 title/description、canonical/OG/JSON-LD、sitemap+lastmod + transformPageData: seo.transformPageData, + transformHead: seo.transformHead, + sitemap: seo.sitemap, + locales: { root: { label: "简体中文", lang: "zh-CN", link: "/", ...zhConfig }, // root: { label: "English", lang: "en-US", link: "/", ...enConfig }, diff --git a/DjangoAdmin_FastAPI_NaiveVue/.vitepress/config/seo.ts b/DjangoAdmin_FastAPI_NaiveVue/.vitepress/config/seo.ts new file mode 100644 index 0000000..bba10ee --- /dev/null +++ b/DjangoAdmin_FastAPI_NaiveVue/.vitepress/config/seo.ts @@ -0,0 +1,311 @@ +/** + * SEO/GEO 构建期钩子（仅 Node 构建时运行，不进客户端 bundle）： + * - transformPageData：每页独立 title（去编号前缀）与 description（取 :::tip 首句） + * - transformHead：canonical / Open Graph / twitter 卡片 / JSON-LD 结构化数据 + * - sitemap.transformItems：注入 lastmod（git 最后提交时间）并过滤 404 + * + * 由 config/index.ts 通过 createSeoHooks(zhConfig.themeConfig?.sidebar) 挂载。 + * 依赖 extract.mjs（纯 ESM，同被 scripts/generate-llms-txt.mjs 复用）。 + */ +import fs from "node:fs"; +import path from "node:path"; +import { execSync } from "node:child_process"; +import { + SITE_URL, + extractDescription, + extractFaqs, + stripNumberPrefix, +} from "./extract.mjs"; + +/** 与 vitepress HeadConfig 同构：[tag, attrs, innerHTML?] */ +type HeadTuple = [string, Record<string, any>, string?]; + +interface SideItem { + text?: string; + link?: string; + items?: SideItem[]; +} + +interface PageDataLike { + relativePath?: string; + title?: string; + description?: string; + frontmatter?: Record<string, any>; + [k: string]: any; +} + +interface TransformCtx { + pageData?: PageDataLike; + title?: string; + description?: string; + content?: string; + siteConfig?: { root?: string; srcDir?: string }; +} + +const ORG = { + "@type": "Organization", + name: "DjangoAdmin", + url: "https://www.djangoadmin.cn", + logo: `${SITE_URL}/logo.png`, + sameAs: [ + "https://gitee.com/djangoadmin/DjangoAdmin_FastAPI_NaiveVue", + "https://www.djangoadmin.cn", + ], +}; + +/** 相对路径 → 站内路由（cleanUrls 关闭，正文页带 .html） */ +function routeOf(relativePath: string): string { + if (relativePath === "index.md") return "/"; + if (relativePath === "404.md") return "/404.html"; + return `/${relativePath.replace(/\.md$/, ".html")}`; +} + +/** 去掉侧边栏文案前导 emoji/符号，保留 "1.1 项目介绍" 这类编号文字 */ +function cleanLabel(s?: string): string { + return (s || "").replace(/^[^\p{L}\p{N}]+/u, "").trim(); +} + +/** 从侧边栏构建 route → 面包屑文案链（含分组小节） */ +function buildCrumbMap(sidebar: unknown): Map<string, string[]> { + const map = new Map<string, string[]>(); + const groups: SideItem[] = Array.isArray(sidebar) + ? sidebar + : ((sidebar as Record<string, SideItem[]>)?.["/zh/"] ?? []); + const walk = (items: SideItem[], trail: string[]) => { + for (const item of items) { + if (item.link && item.link.startsWith("/")) { + map.set(item.link, [...trail, cleanLabel(item.text)]); + } else if (item.items?.length) { + walk(item.items, [...trail, cleanLabel(item.text)]); + } + } + }; + for (const group of groups) { + walk(group.items ?? [], [cleanLabel(group.text)].filter(Boolean)); + } + return map; +} + +/** 从渲染后的 HTML 提取 H1 纯文本（JSON-LD headline 须与页面 H1 一致） */ +function h1OfHtml(html?: string): string { + const m = (html || "").match(/<h1[^>]*>([\s\S]*?)<\/h1>/i); + if (!m) return ""; + return m[1] + .replace(/<[^>]+>/g, "") + .replace(/&/g, "&") + .replace(/</g, "<") + .replace(/>/g, ">") + .replace(/"/g, '"') + .replace(/'/g, "'") + .trim(); +} + +/** 从 Markdown 源提取 H1 纯文本（去除行内 markdown 标记） */ +function h1OfMd(md: string): string { + // 围栏感知：跳过 ``` 代码块内的 # 注释，取真正的页面 H1 + let inFence = false; + for (const line of md.split("\n")) { + if (line.startsWith("```")) { inFence = !inFence; continue; } + if (!inFence && /^# (?!#)/.test(line)) { + return line + .replace(/^# /, "") + .replace(/`([^`]+)`/g, "$1") + .replace(/\*\*([^*]+)\*\*/g, "$1") + .trim(); + } + } + return ""; +} + +export function createSeoHooks(sidebar: unknown) { + const crumbs = buildCrumbMap(sidebar); + const projectDirs: string[] = []; + let gitDates: Map<string, string> | null = null; + + const readMd = (relativePath: string, srcDir?: string): string => { + try { + return fs.readFileSync( + path.resolve(srcDir || process.cwd(), relativePath), + "utf8", + ); + } catch { + return ""; + } + }; + + /** + * 项目内每个文件最后一次 git 提交的 ISO 时间。 + * 单次 git log 调用构建全量映射（key = 相对路径，与 pageData.relativePath 一致）； + * git 不可用时静默降级（sitemap 无 lastmod、JSON-LD 无 dateModified）。 + */ + const getGitDates = (root: string): Map<string, string> => { + if (gitDates) return gitDates; + gitDates = new Map<string, string>(); + try { + const out = execSync( + "git log --format=:::%cI --name-only --relative -n 500 -- .", + { + cwd: root, + encoding: "utf8", + maxBuffer: 64 * 1024 * 1024, + stdio: ["ignore", "pipe", "ignore"], + }, + ); + let current = ""; + for (const line of out.split(/\r?\n/)) { + if (line.startsWith(":::")) { + current = line.slice(3).trim(); + continue; + } + const file = line.trim(); + if (file && current && !gitDates.has(file)) { + gitDates.set(file, current); + } + } + } catch { + // 降级：无 lastmod / dateModified + } + return gitDates; + }; + + /** 每页独立 title（去 "5.10 " 编号前缀，关键词前置）与 description（:::tip 首句） */ + function transformPageData(pageData: PageDataLike, ctx?: any): Record<string, unknown> { + const srcDir: string | undefined = ctx?.siteConfig?.srcDir; + const root: string | undefined = ctx?.siteConfig?.root; + if (root && !projectDirs.includes(root)) projectDirs.push(root); + + const out: Record<string, unknown> = {}; + const rel = pageData.relativePath; + if (rel && !pageData.frontmatter?.description) { + const desc = extractDescription(readMd(rel, srcDir)); + if (desc) out.description = desc; + } + if (pageData.title) { + out.title = stripNumberPrefix(pageData.title); + } + return out; + } + + /** 构建期注入 canonical / OG / twitter / JSON-LD */ + function transformHead(ctx: TransformCtx): HeadTuple[] { + const rel = ctx?.pageData?.relativePath || ""; + if (!rel || rel === "404.md") return []; + + const route = routeOf(rel); + const url = `${SITE_URL}${route}`; + const title = ctx.pageData?.title || ctx.title || ""; + const desc = ctx.description || ""; + const isHome = rel === "index.md"; + const image = `${SITE_URL}/logo.png`; + + const heads: HeadTuple[] = [ + ["link", { rel: "canonical", href: url }], + ["meta", { property: "og:type", content: isHome ? "website" : "article" }], + ["meta", { property: "og:site_name", content: "DjangoAdmin" }], + ["meta", { property: "og:locale", content: "zh_CN" }], + ["meta", { property: "og:title", content: title }], + ["meta", { property: "og:description", content: desc }], + ["meta", { property: "og:url", content: url }], + ["meta", { property: "og:image", content: image }], + ["meta", { property: "twitter:title", content: title }], + ["meta", { property: "twitter:description", content: desc }], + ["meta", { property: "twitter:url", content: url }], + ["meta", { property: "twitter:image", content: image }], + ]; + + // ---- JSON-LD ---- + const root = ctx.siteConfig?.root || projectDirs[0] || process.cwd(); + const srcDir = ctx.siteConfig?.srcDir || root; + const lastMod = getGitDates(root).get(rel); + const blocks: Record<string, any>[] = []; + + if (isHome) { + blocks.push({ + "@context": "https://schema.org", + "@type": "WebSite", + name: "DjangoAdmin 开发文档", + url: `${SITE_URL}/`, + inLanguage: "zh-CN", + description: desc, + }); + blocks.push({ "@context": "https://schema.org", ...ORG }); + } else { + const md = readMd(rel, srcDir); + const article: Record<string, any> = { + "@context": "https://schema.org", + "@type": "TechArticle", + headline: h1OfMd(md) || h1OfHtml(ctx.content) || title, + description: desc, + url, + inLanguage: "zh-CN", + mainEntityOfPage: { "@type": "WebPage", "@id": url }, + publisher: ORG, + }; + if (lastMod) article.dateModified = lastMod; + blocks.push(article); + + const trail = crumbs.get(route); + if (trail?.length) { + const items: Record<string, any>[] = [ + { "@type": "ListItem", position: 1, name: "首页", item: `${SITE_URL}/` }, + ]; + trail.forEach((name, i) => { + const node: Record<string, any> = { + "@type": "ListItem", + position: i + 2, + name, + }; + if (i === trail.length - 1) node.item = url; + items.push(node); + }); + blocks.push({ + "@context": "https://schema.org", + "@type": "BreadcrumbList", + itemListElement: items, + }); + } + + const faqs = extractFaqs(md); + if (faqs.length) { + blocks.push({ + "@context": "https://schema.org", + "@type": "FAQPage", + mainEntity: faqs.map((f) => ({ + "@type": "Question", + name: f.q, + acceptedAnswer: { "@type": "Answer", text: f.a }, + })), + }); + } + } + + // 转义 "<"，防止内容中出现 </script> 破坏注入 + const json = JSON.stringify(blocks).replace(/</g, "\\u003c"); + heads.push(["script", { type: "application/ld+json" }, json]); + return heads; + } + + /** sitemap.xml：过滤 404/README，注入 git lastmod */ + const sitemap = { + hostname: SITE_URL, + transformItems(items: { url: string; lastmod?: string }[]) { + const root = projectDirs[0] || process.cwd(); + const dates = getGitDates(root); + const out: { url: string; lastmod?: string }[] = []; + for (const item of items) { + // ⚠ vitepress 传入的 item.url 是相对路径（"404.html"、"zh/x.html"、""）， + // 无前导斜杠也无域名——hostname 由 SitemapStream 事后拼接。 + if (/(^|\/)404\.html$/.test(item.url)) continue; // 404 页不收录 + if (/(^|\/)README\.html$/.test(item.url)) continue; // 仓库 README 非文档页 + const p = item.url.replace(/^\//, ""); + const rel = + p === "" || p === "index.html" ? "index.md" : p.replace(/\.html$/, ".md"); + const lastmod = dates.get(rel); + out.push(lastmod ? { ...item, lastmod } : item); + } + return out; + }, + }; + + return { transformPageData, transformHead, sitemap }; +} diff --git a/DjangoAdmin_FastAPI_NaiveVue/.vitepress/config/shared.ts b/DjangoAdmin_FastAPI_NaiveVue/.vitepress/config/shared.ts index a7a923c..209d204 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/.vitepress/config/shared.ts +++ b/DjangoAdmin_FastAPI_NaiveVue/.vitepress/config/shared.ts @@ -1,6 +1,6 @@ import { defineConfig, HeadConfig } from "vitepress"; -export const META_IMAGE = "/social.png"; +export const META_IMAGE = "/logo.png"; const rControl = /[\u0000-\u001f]/g; const rSpecial = /[\s~`!@#$%^&*()\-_+=[\]{}|\\;:"'“”‘’<>,.?/]+/g; @@ -23,6 +23,8 @@ export const slugify = (str: string): string => export const sharedConfig = defineConfig({ title: "小蚂蚁云", + // 页面 <title> 后缀：「环境准备 | DjangoAdmin 开发文档」（index.md frontmatter 可覆盖） + titleTemplate: "DjangoAdmin 开发文档", appearance: "light", markdown: { @@ -98,7 +100,7 @@ export const sharedConfig = defineConfig({ }, editLink: { - pattern: "https://gitee.com/djangoadmin/DjangoAdmin_FastAPI_EleVue", + pattern: "https://gitee.com/djangoadmin/DjangoAdmin_FastAPI_NaiveVue", text: "对本页提出修改建议", }, diff --git a/DjangoAdmin_FastAPI_NaiveVue/.vitepress/config/zh.ts b/DjangoAdmin_FastAPI_NaiveVue/.vitepress/config/zh.ts index 371150b..4bcfa0e 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/.vitepress/config/zh.ts +++ b/DjangoAdmin_FastAPI_NaiveVue/.vitepress/config/zh.ts @@ -1,8 +1,9 @@ import type { DefaultTheme, LocaleSpecificConfig } from "vitepress"; -export const META_URL = "https://www.djangoadmin.cn"; -export const META_TITLE = "企业级中台解决方案"; -export const META_DESCRIPTION = "企业级中台解决方案"; +export const META_URL = "http://docs.fastapi.naivevue.djangoadmin.cn"; +export const META_TITLE = "DjangoAdmin FastAPI+NaiveUI 开发文档"; +export const META_DESCRIPTION = + "DjangoAdmin 企业级中台解决方案 - FastAPI + NaiveUI 前后端分离版本"; export const zhConfig: LocaleSpecificConfig<DefaultTheme.Config> = { description: META_DESCRIPTION, diff --git a/DjangoAdmin_FastAPI_NaiveVue/404.md b/DjangoAdmin_FastAPI_NaiveVue/404.md new file mode 100644 index 0000000..c344b20 --- /dev/null +++ b/DjangoAdmin_FastAPI_NaiveVue/404.md @@ -0,0 +1,12 @@ +--- +head: + - - meta + - name: robots + content: noindex +--- + +# 页面不存在 + +抱歉，您访问的页面不存在或已被移动。 + +[返回首页](/) · [浏览文档](/zh/introduction) diff --git a/DjangoAdmin_FastAPI_NaiveVue/package.json b/DjangoAdmin_FastAPI_NaiveVue/package.json index 77bd941..b5517ed 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/package.json +++ b/DjangoAdmin_FastAPI_NaiveVue/package.json @@ -5,7 +5,8 @@ "type": "module", "scripts": { "docs": "vitepress dev .", - "docs:build": "vitepress build .", + "docs:llms": "node scripts/generate-llms-txt.mjs", + "docs:build": "node scripts/generate-llms-txt.mjs && vitepress build .", "docs:preview": "vitepress preview ." }, "dependencies": { diff --git a/DjangoAdmin_FastAPI_NaiveVue/public/llms.txt b/DjangoAdmin_FastAPI_NaiveVue/public/llms.txt new file mode 100644 index 0000000..90f28c5 --- /dev/null +++ b/DjangoAdmin_FastAPI_NaiveVue/public/llms.txt @@ -0,0 +1,159 @@ +# DjangoAdmin FastAPI+NaiveUI 开发文档 + +> DjangoAdmin 企业级中台解决方案 - FastAPI + NaiveUI 前后端分离版本。内置 RBAC 权限体系、代码生成器等开箱即用功能，支持五种数据库一键切换。本文档共 129 篇，按章节组织。 + +## 1. 了解项目 + +- [1.1 项目介绍](http://docs.fastapi.naivevue.djangoadmin.cn/zh/introduction.html): DjangoAdmin 是企业级中台解决方案，后端基于 FastAPI + SQLAlchemy，前端基于 Vue3 + NaiveUI，内置 RBAC 权限、代码生成器等开箱即用功能， +- [更新日志](http://docs.fastapi.naivevue.djangoadmin.cn/zh/changelog.html): 更新日志是项目演进的完整记录，帮助开发者和企业了解每个版本的能力变化与技术演进方向。 +- [新手入门指南](http://docs.fastapi.naivevue.djangoadmin.cn/zh/course.html): 详细的安装步骤请参考 环境准备 章节。 +- [项目目录结构](http://docs.fastapi.naivevue.djangoadmin.cn/zh/struct.html): 本页说明项目前后端目录组织与各目录职责，二次开发定位文件或了解工程结构时对照查阅。 +- [为什么选择我们？](http://docs.fastapi.naivevue.djangoadmin.cn/zh/why.html): 本框架提供开箱即用的企业级中台完整解决方案，免去从零搭建成本，助力中大型企业构建统一的数字化基座。 + +## 2. 快速入门 + +- [后端启动](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume1/backend.html): 启动后端前，请确保已完成 环境准备 章节中的所有软件安装。 +- [数据库初始化](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume1/database.html): 数据库初始化前，请确保已完成以下准备工作： 1. 目标数据库服务已启动（如 MySQL 8.0+） 2. .env 文件中的 DB_DRIVER 和数据库连接信息已正确配置 3. Python +- [Docker 一键启动](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume1/docker.html): 使用 Docker 方式启动前，请确保已安装以下软件： 1. Docker Desktop（Windows / macOS）或 Docker Engine（Linux） 2. Docker +- [环境变量速查表](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume1/env-vars.html): 1. .env.example 是环境变量模板文件，已提交到版本控制。 +- [环境准备](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume1/environment.html): 1. 部分软件安装后需要设置本地环境变量，便于在终端中使用命令。 +- [常见问题FAQ](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume1/faq.html): 遇到问题时，建议先查看终端日志输出和浏览器控制台（F12）的错误信息，通常能快速定位问题原因。 +- [第一个接口调试](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume1/first-api.html): 开始调试前，请确保已完成以下步骤： 1. 后端服务已启动（参见 后端启动） 2. 数据库已初始化（参见 数据库初始化） 3. Redis 服务已启动 +- [前端启动](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume1/frontend.html): 启动前端前，请确保已完成 环境准备 章节中的 Node.js 和 pnpm 安装，并已启动后端服务（参见 后端启动）。 + +## 3. 模块开发实战 + +- [完整代码清单](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume2/code-list.html): 本页汇总岗位管理（Position）模块涉及的全部文件代码，开发时可快速查阅与复制对照。 +- [Endpoint 层](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume2/endpoint.html): Endpoint 层是 HTTP 接口层，负责定义路由、权限装饰器与请求参数绑定，编写新接口从本页开始。 +- [常见问题与排错](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume2/faq.html): 本页汇总模块开发过程中的常见问题与排错方法，开发受阻时按症状索引即可定位。 +- [前端 API 层](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume2/fe-api.html): 前端 API 层封装后端接口的 HTTP 请求，每个业务模块对应一个 API 文件，本页讲解基于 Axios 封装的编写规范。 +- [前端路由与菜单](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume2/fe-router.html): 本页讲解前端路由与菜单机制——路由和菜单由后端动态返回，前端只需注册路由组件映射。 +- [前端页面视图](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume2/fe-view.html): 前端页面视图是用户直接交互的界面，本页讲解 Vue3 + NaiveUI 下一个完整 CRUD 页面的文件组成与编写方式。 +- [数据模型（Model）](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume2/model.html): 实际开发中不需要手写 DDL。 +- [概述与目标](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume2/overview.html): 其中 id、create_user、create_time、update_user、update_time、is_delete 由基类 base_model 自动提供，业务字段仅需定义 name、 +- [权限节点配置](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume2/permission.html): 实际开发中，查询类权限（page、detail、list）通常合并为一个节点 sys:position:list，减少配置工作量。 +- [Repository 层](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume2/repository.html): Repository 层是数据访问层，封装全部数据库查询操作，本页讲解基于 BaseRepository 基类的通用 CRUD 用法。 +- [路由注册](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume2/router.html): 路由注册是将模块 Endpoint 挂载到应用的过程，本页讲解在 router.py 中统一注册模块路由的方法。 +- [Pydantic Schema](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume2/schema.html): Schema 层负责请求数据校验，本页讲解基于 Pydantic v2 BaseModel 与 Field 的表单类定义规范。 +- [Service 层](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume2/service.html): Service 层是业务逻辑层，本页讲解基于 BaseService 基类声明差异点即可获得完整增删改查能力的编写方式。 + +## 4. 架构设计 + +- [核心基类体系](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume3/base-classes.html): 五大基类各司其职，覆盖从数据模型到请求校验再到业务逻辑的完整链路。 +- [缓存架构设计](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume3/cache.html): 采用两级缓存架构：第一级为进程内字典缓存（dict_util），第二级为 Redis 分布式缓存。 +- [数据库设计](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume3/database-design.html): 所有业务表继承 base_model 基类，自动获得 6 个通用字段（id / create_user / create_time / update_user / update_time / +- [目录结构设计](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume3/directory.html): 目录结构遵循「按功能分组、按职责分层」的原则。 +- [扩展性设计](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume3/extensibility.html): 遵循开闭原则（OCP）：对扩展开放，对修改关闭。 +- [分层架构设计](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume3/layer-arch.html): 采用经典的三层架构，核心原则是：依赖单向、职责单一、接口隔离。 +- [整体架构图](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume3/overview.html): 遵循以下架构设计原则，确保系统在长期演进中保持高质量和可维护性： +- [请求完整链路](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume3/request-flow.html): 一个典型的 API 请求经过以下阶段：浏览器 → Nginx → CORS → 限流 → 上传体积限制 → 请求计时 → Token 续签 → 操作日志 → DB 会话 → Redis 注入 → +- [安全架构设计](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume3/security.html): 纵深防御：认证、授权、限流、参数校验多层防护，单一防线失效时仍有其他机制兜底 最小权限：用户仅能访问已授权接口，角色权限按需分配，遵循"够用即可"原则 数据不落地：敏感信息（Token、 +- [同步/异步设计决策](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume3/sync-async.html): FastAPI 基于 ASGI 异步框架，但并非所有端点都需要 async def。 +- [技术选型说明](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume3/tech-stack.html): FastAPI 基于 ASGI 原生异步、类型提示驱动的自动文档、Pydantic v2 的高性能校验，使其在构建 RESTful API 时具有显著优势。 + +## 5. 开发指南 + +- [API 接口速查表](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/api-cheatsheet.html): API 接口速查表，按模块分组列出所有 RESTful 接口的请求方法、路径、说明和权限标识。 +- [文章管理](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/business/article.html): 文章管理模块支持富文本编辑、分类关联、封面图片上传、图集管理等功能。 +- [分类管理](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/business/category.html): 分类管理模块用于管理树形分类数据，如文章分类、产品分类等。 +- [公告与链接管理](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/business/content.html): 公告、链接、城市是三个简单 CRUD 内容模块，均继承 BaseService，提供标准的增删改查接口。 +- [部门/职级/岗位管理](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/business/dept.html): 部门、职级、岗位是组织架构管理的三个核心模块。 +- [定时任务](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/business/job.html): 定时任务模块基于 APScheduler 实现，支持 Cron 表达式调度、任务执行日志、动态启停等功能。 +- [菜单管理](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/business/menu.html): 菜单管理是 RBAC 权限系统的基础，负责管理系统的导航菜单和权限节点。 +- [参数管理](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/business/param.html): 参数管理模块用于管理动态系统参数，与系统配置模块类似但更侧重于业务参数的灵活配置。 +- [角色管理](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/business/role.html): 角色是 RBAC 权限模型的核心，连接用户和菜单（权限）。 +- [用户管理](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/business/user.html): 用户管理是系统的核心模块，属于复杂业务模块。 +- [认证流程实战](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/core/auth-flow.html): 登录 → Token 获取 → 权限校验 → Token 刷新 → 退出登录的完整认证链路实战说明。 +- [验证码机制](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/core/captcha.html): 验证码是防止自动化攻击的重要安全手段。 +- [系统配置管理](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/core/config.html): 系统配置模块用于管理动态的键值对配置项，与数据字典类似但更偏向系统级参数。 +- [跨域资源共享（CORS）](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/core/cors.html): CORS（Cross-Origin Resource Sharing）跨域资源共享是前后端分离架构必须处理的问题。 +- [演示模式](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/core/demo-mode.html): 演示模式用于在线体验环境，开启后所有写操作（新增、编辑、删除等）将被拦截，返回"演示环境，暂无操作权限"提示。 +- [数据字典使用指南](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/core/dict-guide.html): 数据字典的完整使用流程，从新增字典类型到在代码中使用字典数据的实操指南。 +- [字典模块](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/core/dict.html): 数据字典用于管理系统中的枚举值和配置项，如状态、类型、性别等。 +- [异常与响应处理](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/core/exception.html): 定义了统一的响应格式和全局异常处理机制。 +- [防重复提交](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/core/idempotent.html): 防重复提交是保障数据一致性的重要措施。 +- [用户认证（JWT）](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/core/jwt.html): JWT（JSON Web Token）是的核心认证机制。 +- [登录日志](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/core/login-log.html): 登录日志记录每次登录尝试（成功/失败），包含登录账号、IP地址、浏览器信息、登录时间等。 +- [操作日志](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/core/operation-log.html): 操作日志中间件自动拦截写请求（POST/PUT/DELETE/PATCH）并记录操作日志，无需手动埋点。 +- [请求限流](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/core/rate-limit.html): 请求限流中间件基于 Redis 实现 IP 级别的滑动窗口限流，防止恶意请求和 DoS 攻击。 +- [权限管理（RBAC）](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/core/rbac.html): 采用基于角色的访问控制（RBAC）模型，通过用户-角色-菜单三层关系实现细粒度的权限管理。 +- [参数验证（Pydantic）](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/core/validator.html): 使用 Pydantic v2 进行请求参数验证。 +- [API 层开发](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/frontend/api.html): 前端 API 层位于 src/api/ 目录，封装所有与后端的 HTTP 请求。 +- [前端构建](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/frontend/build.html): 前端使用 Vite 构建，支持开发服务器和生产构建。 +- [公共组件库](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/frontend/components.html): 项目提供丰富的公共组件，位于 ui/src/components/ 目录，基于 NaiveUI 二次封装，覆盖表格、表单、弹窗、上传、富文本编辑等常见场景。 +- [BasicForm 表单](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/frontend/form.html): BasicForm 位于 src/components/Form/src/BasicForm.vue，基于 NaiveUI 的 n-form 二次封装，通过 schemas 配置化定义表单字段， +- [Hooks 组合式函数](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/frontend/hooks.html): 项目封装了一系列组合式函数（Hooks），位于 src/hooks/ 和 src/utils/ 目录，提供权限检查、异步 loading、防重复提交、实时时钟、项目配置等可复用逻辑。 +- [国际化](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/frontend/i18n.html): 当前项目仅支持中文界面，NaiveUI 使用中文语言包（zhCN），所有界面文本直接硬编码在组件中。 +- [Modal 弹窗](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/frontend/modal.html): 项目提供 BasicModal 组件（src/components/Modal/src/BasicModal.vue）和原生 n-modal 两种弹窗用法。 +- [权限指令 v-perm](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/frontend/perm-directive.html): v-perm 和 v-perms 是项目自定义的 Vue 指令，用于按钮级别的权限控制，无权限时自动从 DOM 中移除元素。 +- [路由与菜单](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/frontend/router.html): 前端路由基于 Vue Router 4 实现动态路由生成，菜单数据从后端获取，通过 generator-routers.ts 递归生成路由表，路由守卫控制登录状态和权限。 +- [前端环境与结构](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/frontend/setup.html): 前端基于 Vue3 + NaiveUI 构建，使用 pnpm 作为包管理工具，Vite 作为构建工具，TypeScript 作为开发语言。 +- [Store 状态管理](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/frontend/store.html): 前端使用 Pinia 进行状态管理，核心模块包括 user（用户信息与权限）、asyncRoute（动态路由与菜单）、projectSetting（项目配置）、designSetting（主题设计）等。 +- [样式与主题](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/frontend/style.html): 前端样式方案采用 Tailwind CSS + Less + NaiveUI 主题覆盖，支持深色模式切换。 +- [BasicTable 表格](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/frontend/table.html): BasicTable 位于 src/components/Table/src/Table.vue，基于 NaiveUI 的 n-data-table 二次封装，提供列定义、数据请求、分页、操作列、 +- [工具函数](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/frontend/utils.html): 前端工具函数位于 src/utils/ 目录，提供认证管理、本地存储、日期格式化、树结构操作、文件下载等通用能力。 +- [页面视图开发](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/frontend/view.html): 页面视图位于 src/views/ 目录，每个业务模块遵循 index.vue（列表页）+ edit.vue（编辑弹窗）的标准模式，辅以 columns.ts（列定义）和 +- [接口响应规范](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/integration/api-contract.html): 后端所有接口统一返回 R.ok() / R.failed() 格式的 JSON 响应，前端通过 VAxios 的 transformRequestData 拦截器统一解包处理。 +- [字典数据联调](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/integration/dict-sync.html): 字典数据通过后端字典 API 获取，前端在下拉选择器中渲染选项。 +- [权限节点联动](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/integration/perm-sync.html): 前后端权限通过统一的权限节点字符串联动，后端 @permission_required 校验权限，前端 v-perm 指令和 TableAction 的 auth 属性控制按钮显示。 +- [代理配置](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/integration/proxy.html): 开发环境通过 Vite 代理转发 API 请求到后端，生产环境通过 Nginx 代理。 +- [文件上传联调](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/integration/upload-sync.html): 文件上传涉及前端 Upload 组件、后端上传接口和 URL 拼接三个环节，需要前后端协同配置。 +- [数据库会话](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/tools/db-session.html): 通过 contextvars + Starlette 中间件实现请求级数据库会话管理，写操作按业务成功与否自动 commit/rollback。 +- [导入导出](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/tools/excel.html): 基于 openpyxl 实现 Excel 导入导出功能，支持通过 file_template 模块管理导入模板配置。 +- [IP/UA 解析](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/tools/ip-ua.html): 提供客户端 IP 获取、IP 地理位置查询和 User-Agent 解析三大能力。 +- [日志系统](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/tools/logger.html): 通过 Python 标准库 logging 实现结构化日志，支持控制台 + 文件双输出，日志文件按大小自动轮转。 +- [密码工具](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/tools/password.html): 采用 bcrypt 双重加盐方案存储密码，源码位于 src/core/password.py。 +- [权限缓存](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/tools/perm-cache.html): 通过 Redis 实现用户权限和菜单的缓存，采用用户级缓存 + 全局版本号双层策略。 +- [请求解析工具](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/tools/request-util.html): src/utils/request.py 提供请求数据解析相关的工具函数，包括批量 ID 解析、SQL LIKE 安全处理、分页参数解析等。 +- [富文本过滤](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/tools/rich-text.html): 富文本编辑器内容存在存储型 XSS 风险，通过 bleach 库实现 HTML 白名单清洗，在落盘前统一过滤危险内容。 +- [文件上传完整流程](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/tools/upload-guide.html): 富文本编辑器（如 TinyMCE、CKEditor、WangEditor 等）的图片上传同样使用此接口。 +- [文件上传](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume4/tools/upload.html): 提供本地文件上传功能，支持图片和通用文件上传，内置扩展名白名单、大小限制、魔术字节校验和路径遍历防护。 + +## 6. 代码生成器 + +- [CLI 命令行使用](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume5/cli.html): 代码生成器 CLI 模式的使用方法，包括单表生成、批量生成、预览模式和配置导出。 +- [代码生成引擎](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume5/code-engine.html): 代码生成引擎的工作原理，包括配置解析、模板渲染、文件写入和自动注册的完整流程。 +- [配置文件详解](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume5/config.html): 代码生成器 JSON 配置文件的格式说明，包括模块名称、字段属性、字典编码等配置项的详细解释。 +- [实战案例](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume5/demo.html): 以 fastapi_example 演示表为完整案例，演示从建表到生成到使用的全流程。 +- [常见问题](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume5/faq.html): 代码生成器使用过程中常见问题的原因分析和解决方案。 +- [概述与架构](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume5/overview.html): 代码生成器的整体架构、核心模块和生成流程概述。 +- [表结构解析引擎](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume5/parser.html): 表结构解析引擎的工作原理，从数据库读取表元数据并智能推断字段用途的过程。 +- [自定义模板](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume5/templates.html): 代码生成器模板的 Jinja2 语法说明，包括模板变量、字段属性和自定义模板的开发方法。 +- [Web 管理界面](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume5/web-ui.html): 代码生成器 Web 管理界面的使用方法，通过可视化界面操作单表生成和批量生成。 + +## 7. 运维部署 + +- [备份与恢复](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume6/backup.html): - 3 份数据副本（1 份生产 + 2 份备份） - 2 种不同存储介质（如本地磁盘 + 远程存储） - 1 份异地备份（防机房级灾难） +- [数据库迁移](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume6/db-migrate.html): - 结构迁移：Alembic（自动生成 DDL 差异） - 数据迁移：scripts/migrate_db.py（跨库数据泵） - 初始化：scripts/init_db.py（全新安装一键建库） +- [部署 Checklist](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume6/deploy-checklist.html): 从服务器准备到应用上线的完整部署操作清单，适用于生产环境首次部署和后续版本更新。 +- [Docker容器化](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume6/docker.html): - 环境一致性：消除"在我机器上能跑"的问题 - 快速部署：一条命令启动完整服务 - 资源隔离：应用与宿主机环境解耦 +- [环境规划](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume6/env-plan.html): 各环境之间保持代码一致，仅通过环境变量（.env）区分配置。 +- [健康检查与监控](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume6/monitoring.html): `` 1. 应用层：健康检查端点、业务指标 2. 系统层：CPU/内存/磁盘/网络 3. 中间件：MySQL/Redis 连接状态 4. 日志：集中式日志收集与分析 `` +- [Nginx 反向代理](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume6/nginx.html): `` 客户端 → Nginx（80/443） ├─ / → 前端静态资源（dist/） ├─ /api/v1/... → FastAPI 后端（8031） └─ /api/file/ → +- [性能调优](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume6/performance.html): 1. 先测量，后优化：用数据说话，避免盲目调参 2. 瓶颈优先：找到最大瓶颈，集中优化 3. 渐进式：每次只调整一个参数，观察效果 +- [安全加固](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume6/security-hardening.html): - 最小权限：只开放必要的端口和权限 - 纵深防御：多层安全措施叠加 - 默认安全：配置默认值应为安全选项 +- [Supervisor进程管理](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume6/supervisor.html): - Linux 服务器直接部署（非 Docker） - 需要进程自动重启和日志轮转 - 管理多个相关进程 +- [故障排查手册](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume6/troubleshooting.html): 1. 查看日志：tail -f logs/supervisor.out.log 或 docker-compose logs -f 2. 检查配置：.env 文件、数据库连接、Redis 连接 3. +- [版本升级流程](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume6/upgrade.html): 1. 先备份，后升级 2. 先测试环境，后生产环境 3. 每次升级可回滚 4. 低峰期执行升级 + +## 8. 规范标准 + +- [API响应规范](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume7/api-response.html): - 所有接口必须通过 R.ok() 或 R.failed() 返回，禁止直接返回 dict - 成功响应 code=0，失败响应 code=1 - 响应体始终包含 code、data、msg、ok +- [代码审查清单](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume7/code-review.html): - 每次提交必须经过至少一人审查 - 审查关注点：正确性 > 安全性 > 可维护性 > 性能 - 审查意见应具体、可操作，避免主观评价 +- [删除规范](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume7/deletion.html): - is_delete = 0：正常记录（默认值） - is_delete = 1：已删除记录 - 所有查询方法自动过滤 is_delete = 0，业务层无需关心 +- [文档规范](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume7/doc-standard.html): - 文档与代码同步更新 - 使用中文编写（项目约定） - 示例代码可直接运行 +- [Endpoint层规范](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume7/endpoint.html): - Endpoint 只做请求分发，不含业务逻辑 - 通过装饰器控制权限和演示模式 - 委托 Service 处理业务逻辑 - 返回 R 封装的响应 +- [前端 API 规范](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume7/fe-api.html): - 每个后端模块对应一个 API 文件 - 函数命名统一使用 名词 + 动词 格式（与后端保持一致） - 请求路径使用相对路径（/position/page），不含 /api/v1 前缀（由 +- [前端页面规范](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume7/fe-component.html): - Vue3（Composition API + <script setup>） - NaiveUI - 自定义组件（BasicTable / BasicForm / TableAction / +- [Git提交规范](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume7/git.html): `` <type>(<scope>): <subject> <body> <footer> `` +- [分页规范](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume7/pagination.html): - 前端传递 pageNo（页码，从 1 开始）和 pageSize（每页条数） - 后端返回 {records, total, size, current, pages} 结构 - 默认每页 10 +- [Pydantic Schema规范](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume7/pydantic.html): - 请求体参数必须声明为 Pydantic 模型（Form 类） - 字段约束使用 Field(...) 定义 - 自定义校验使用 @field_validator - 唯一性校验在 Schema +- [Repository层规范](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume7/repository.html): - Repository 只做数据访问原语，不处理 R 封装/序列化/业务逻辑 - 软删除由基类自动处理，子类无需关心 - 查询方法自动跳过 None 值条件 +- [Service层规范](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume7/service.html): BaseService 采用模板方法模式：基类定义流程骨架，子类通过声明差异点和覆盖钩子定制行为。 +- [测试规范](http://docs.fastapi.naivevue.djangoadmin.cn/zh/volume7/testing.html): 1. 契约测试（Contract）：验证路由、权限、表名等契约不变 2. 单元测试（Unit）：验证单个函数/方法的逻辑正确性 3. 集成测试（Integration）：验证模块间协作、真实数据库操作 + +## 附录 + +- [常见问题汇总](http://docs.fastapi.naivevue.djangoadmin.cn/zh/faq.html): 本页汇总了项目各模块的常见问题及解决方案，按场景分类索引。 +- [免责声明](http://docs.fastapi.naivevue.djangoadmin.cn/zh/other/declare.html): 使用本产品前必读的法律声明，明确产品性质、使用限制与责任划分，一旦使用本产品即视为接受本声明全部条款。 +- [广告赞助](http://docs.fastapi.naivevue.djangoadmin.cn/zh/other/sponsor.html): 1. 投放广告不得与官方全系产品存在结构性冲突和竞争 2. 广告内容需符合国家法律法规，不得包含虚假、误导性信息 3. 广告素材需经官方审核通过后方可上线，审核周期 1-3 个工作日 4. diff --git a/DjangoAdmin_FastAPI_NaiveVue/public/robots.txt b/DjangoAdmin_FastAPI_NaiveVue/public/robots.txt new file mode 100644 index 0000000..acc9184 --- /dev/null +++ b/DjangoAdmin_FastAPI_NaiveVue/public/robots.txt @@ -0,0 +1,33 @@ +# DjangoAdmin FastAPI+NaiveUI 开发文档 +User-agent: * +Allow: / + +# 显式放行生成式引擎 / AI 爬虫（GEO） +User-agent: GPTBot +Allow: / + +User-agent: ChatGPT-User +Allow: / + +User-agent: ClaudeBot +Allow: / + +User-agent: Claude-Web +Allow: / + +User-agent: anthropic-ai +Allow: / + +User-agent: PerplexityBot +Allow: / + +User-agent: Google-Extended +Allow: / + +User-agent: Bytespider +Allow: / + +User-agent: bingbot +Allow: / + +Sitemap: http://docs.fastapi.naivevue.djangoadmin.cn/sitemap.xml diff --git a/DjangoAdmin_FastAPI_NaiveVue/scripts/generate-llms-txt.mjs b/DjangoAdmin_FastAPI_NaiveVue/scripts/generate-llms-txt.mjs new file mode 100644 index 0000000..4bf6ef8 --- /dev/null +++ b/DjangoAdmin_FastAPI_NaiveVue/scripts/generate-llms-txt.mjs @@ -0,0 +1,122 @@ +#!/usr/bin/env node +/** + * 生成 public/llms.txt（llmstxt.org 标准）——AI 爬虫的站点摘要索引。 + * + * 数据源：zh 目录下全部 Markdown 的 H1 + :::tip 概述首句（与 meta + * description 同源，复用 .vitepress/config/extract.mjs）。按侧边栏章节分组。 + * + * 用法：node scripts/generate-llms-txt.mjs + * 已挂入 package.json 的 docs:build 前置步骤。 + */ +import fs from "node:fs"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; +import { + SITE_URL, + SITE_DESCRIPTION, + extractDescription, +} from "../.vitepress/config/extract.mjs"; + +const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."); +const ZH = path.join(ROOT, "zh"); + +/** 顶层目录 → 侧边栏章节名（与 .vitepress/config/zh.ts 保持一致） */ +const SECTIONS = [ + ["", "1. 了解项目"], + ["volume1", "2. 快速入门"], + ["volume2", "3. 模块开发实战"], + ["volume3", "4. 架构设计"], + ["volume4", "5. 开发指南"], + ["volume5", "6. 代码生成器"], + ["volume6", "7. 运维部署"], + ["volume7", "8. 规范标准"], + ["other", "附录"], +]; + +function walk(dir, out = []) { + for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { + const p = path.join(dir, entry.name); + if (entry.isDirectory()) walk(p, out); + else if (entry.name.endsWith(".md")) out.push(p); + } + return out; +} + +/** 提取首个 H1 文本 */ +function h1Of(md) { + // 围栏感知：跳过 ``` 代码块内的 # 注释，取真正的页面 H1 + let inFence = false; + for (const line of md.split("\n")) { + if (line.startsWith("```")) { inFence = !inFence; continue; } + if (!inFence && line.startsWith("# ") && !line.startsWith("## ")) { + return line.slice(2).trim(); + } + } + return ""; +} + +/** H1 编号排序键："5.10 x" → [5,10]；无编号排最后 */ +function sortKey(h1) { + const m = h1.match(/^(\d+(?:\.\d+)*)/); + if (m) return m[1].split(".").map(Number); + const letter = h1.match(/^([A-Z])\./); + if (letter) return [1000 + letter[1].charCodeAt(0)]; + return [9999]; +} + +function cmpKey(a, b) { + const len = Math.max(a.length, b.length); + for (let i = 0; i < len; i++) { + const x = a[i] ?? 0; + const y = b[i] ?? 0; + if (x !== y) return x - y; + } + return 0; +} + +const files = walk(ZH); +const groups = new Map(SECTIONS.map(([dir, label]) => [label, []])); + +for (const file of files) { + const rel = path.relative(ZH, file).replace(/\\/g, "/"); + const topDir = rel.includes("/") ? rel.split("/")[0] : ""; + const base = rel.split("/").pop(); + const label = (topDir === "" && base === "faq.md") ? "附录" + : SECTIONS.find(([dir]) => dir === topDir)?.[1] ?? "附录"; + + const md = fs.readFileSync(file, "utf8"); + const h1 = h1Of(md); + if (!h1) continue; + const desc = extractDescription(md); + const url = `${SITE_URL}/zh/${rel.replace(/\.md$/, ".html")}`; + groups.get(label).push({ h1, desc, url, key: sortKey(h1) }); +} + +const lines = [ + "# DjangoAdmin FastAPI+NaiveUI 开发文档", + "", + `> ${SITE_DESCRIPTION}。内置 RBAC 权限体系、代码生成器等开箱即用功能，支持五种数据库一键切换。本文档共 ${files.length} 篇，按章节组织。`, + "", +]; + +// 按章节顺序输出，合并重复 label（appendix/other 同为「附录」，只输出一次） +const printed = new Set(); +for (const [, label] of SECTIONS) { + if (printed.has(label)) continue; + const items = groups.get(label); + if (!items?.length) continue; + printed.add(label); + + lines.push(`## ${label}`, ""); + items.sort((a, b) => cmpKey(a.key, b.key)); + for (const { h1, desc, url } of items) { + lines.push(desc ? `- [${h1}](${url}): ${desc}` : `- [${h1}](${url})`); + } + lines.push(""); +} + +const out = path.join(ROOT, "public", "llms.txt"); +fs.writeFileSync(out, lines.join("\n"), "utf8"); +console.log( + `llms.txt: ${files.length} 页 → ${path.relative(ROOT, out)} (${printed.size} 个章节)`, +); diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/course.md b/DjangoAdmin_FastAPI_NaiveVue/zh/course.md index 1d24330..9fb2b53 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/course.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/course.md @@ -1,3 +1,5 @@ +# 新手入门指南 + :::warning 特别提醒 官方精心制作本教程，目的在于方便用户快速掌握软件产品的使用和部署。通过此教程，刚入行的开发者也可以快速掌握并投入产品研发。本地部署时务必请耐心阅读文档操作。 ::: diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/introduction.md b/DjangoAdmin_FastAPI_NaiveVue/zh/introduction.md index d087665..a395bfd 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/introduction.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/introduction.md @@ -1,3 +1,9 @@ +# 1.1 项目介绍 + +:::tip 概述 +DjangoAdmin 是企业级中台解决方案，后端基于 FastAPI + SQLAlchemy，前端基于 Vue3 + NaiveUI，内置 RBAC 权限、代码生成器等开箱即用功能，支持五种数据库一键切换。 +::: + <div align="center"> <p align="center"> <img src="/logo.png" height="150" alt="logo"/> @@ -75,10 +81,10 @@ | Flask+ElementPlus前后端分离版 | 基于 Flask、SQLAlchemy、WTForms、Vue3、ElementPlus、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Flask_EleVue) | | Flask+AntDesign前后端分离版 | 基于 Flask、SQLAlchemy、WTForms、Vue3、AntDesign、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Flask_AntdVue) | | Flask+NaiveUI前后端分离版 | 基于 Flask、SQLAlchemy、WTForms、Vue3、NaiveUI、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Flask_NaiveVue) | -| FastAPI+Layui混编版 | 基于 FastAPI、Jinja2、Layui 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_Layui) | -| FastAPI+ElementPlus前后端分离版 | 基于 FastAPI、SQLAlchemy、Pydantic、Vue3、ElementPlus、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_EleVue) | -| FastAPI+AntDesign前后端分离版 | 基于 FastAPI、SQLAlchemy、Pydantic、Vue3、AntDesign、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_AntdVue) | -| FastAPI+NaiveUI前后端分离版 | 基于 FastAPI、SQLAlchemy、Pydantic、Vue3、NaiveUI、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_NaiveVue) | +| FastAPI+Layui混编版 | 基于 FastAPI、Jinja2、Layui 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_FastAPI_Layui) | +| FastAPI+ElementPlus前后端分离版 | 基于 FastAPI、SQLAlchemy、Pydantic、Vue3、ElementPlus、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_FastAPI_EleVue) | +| FastAPI+AntDesign前后端分离版 | 基于 FastAPI、SQLAlchemy、Pydantic、Vue3、AntDesign、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_FastAPI_AntdVue) | +| FastAPI+NaiveUI前后端分离版 | 基于 FastAPI、SQLAlchemy、Pydantic、Vue3、NaiveUI、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_FastAPI_NaiveVue) | | Tornado+Layui混编版 | 基于 Tornado、Jinja2、Layui 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Tornado_Layui) | | Tornado+ElementPlus前后端分离版 | 基于 Tornado、SQLAlchemy、Pydantic、Vue3、ElementPlus、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Tornado_EleVue) | | Tornado+AntDesign前后端分离版 | 基于 Tornado、SQLAlchemy、Pydantic、Vue3、AntDesign、TypeScript、Vite 等技术栈，支持 MySQL、PostgreSQL、SQLite、Oracle、SQL Server 等数据库 | [Gitee地址](https://gitee.com/djangoadmin/DjangoAdmin_Tornado_AntdVue) | diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/other/declare.md b/DjangoAdmin_FastAPI_NaiveVue/zh/other/declare.md index 7737479..915692a 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/other/declare.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/other/declare.md @@ -1,5 +1,9 @@ # 免责声明 +:::tip 概述 +使用本产品前必读的法律声明，明确产品性质、使用限制与责任划分，一旦使用本产品即视为接受本声明全部条款。 +::: + :::danger 重要提示 任何用户在使用本团队研发的系列软件产品（以下简称「本产品」）前，请仔细阅读并透彻理解本声明。选择不使用本产品，可随时停止使用；一旦使用本产品，即视为对本声明全部内容的认可和接受。 ::: diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/struct.md b/DjangoAdmin_FastAPI_NaiveVue/zh/struct.md index 9b8c006..5143ae4 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/struct.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/struct.md @@ -1,3 +1,9 @@ +# 项目目录结构 + +:::tip 概述 +本页说明项目前后端目录组织与各目录职责，二次开发定位文件或了解工程结构时对照查阅。 +::: + ## 目录说明 在软件开发过程中，优秀的软件目录结构对于项目的组织、开发、维护和扩展至关重要，合理的目录结构能够显著提升开发效率和代码可维护性。 diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/code-list.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/code-list.md index a70f423..b5b577b 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/code-list.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/code-list.md @@ -1,5 +1,9 @@ # 完整代码清单 +:::tip 概述 +本页汇总岗位管理（Position）模块涉及的全部文件代码，开发时可快速查阅与复制对照。 +::: + 本章汇总 Position 岗位模块涉及的全部文件，便于开发时快速查阅和复制。 ## 后端文件清单 diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/endpoint.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/endpoint.md index 12d7528..c5a5aa8 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/endpoint.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/endpoint.md @@ -1,5 +1,9 @@ # Endpoint 层 +:::tip 概述 +Endpoint 层是 HTTP 接口层，负责定义路由、权限装饰器与请求参数绑定，编写新接口从本页开始。 +::: + Endpoint 层是 HTTP 接口层，负责定义路由、权限装饰器和请求参数绑定。每个业务模块对应一个 endpoint 文件，所有业务逻辑委托给 Service 层处理。 ## 文件位置 diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/faq.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/faq.md index 9e25482..5e4b074 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/faq.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/faq.md @@ -1,5 +1,9 @@ # 常见问题与排错 +:::tip 概述 +本页汇总模块开发过程中的常见问题与排错方法，开发受阻时按症状索引即可定位。 +::: + 本章汇总模块开发过程中的常见问题和解决方案。 ## 后端问题 diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/fe-api.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/fe-api.md index 797cc1c..ae9203a 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/fe-api.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/fe-api.md @@ -1,5 +1,9 @@ # 前端 API 层 +:::tip 概述 +前端 API 层封装后端接口的 HTTP 请求，每个业务模块对应一个 API 文件，本页讲解基于 Axios 封装的编写规范。 +::: + 前端 API 层负责封装后端接口的 HTTP 请求。每个业务模块对应一个 API 文件，使用项目封装的 Axios 工具发送请求。 ## 文件位置 diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/fe-router.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/fe-router.md index 0f79bbe..5c2330b 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/fe-router.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/fe-router.md @@ -1,5 +1,9 @@ # 前端路由与菜单 +:::tip 概述 +本页讲解前端路由与菜单机制——路由和菜单由后端动态返回，前端只需注册路由组件映射。 +::: + 前端路由定义页面的访问路径，菜单是路由的可视化展示。项目的路由和菜单由后端动态返回，前端只需注册路由组件映射。 ## 路由配置 diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/fe-view.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/fe-view.md index c409ee9..4a8c24c 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/fe-view.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/fe-view.md @@ -1,5 +1,9 @@ # 前端页面视图 +:::tip 概述 +前端页面视图是用户直接交互的界面，本页讲解 Vue3 + NaiveUI 下一个完整 CRUD 页面的文件组成与编写方式。 +::: + 前端页面视图是用户直接交互的界面。项目使用 Vue3 + NaiveUI + Vite 构建。一个完整的 CRUD 页面由 4 个文件组成： ``` diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/repository.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/repository.md index f268212..f530306 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/repository.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/repository.md @@ -1,5 +1,9 @@ # Repository 层 +:::tip 概述 +Repository 层是数据访问层，封装全部数据库查询操作，本页讲解基于 BaseRepository 基类的通用 CRUD 用法。 +::: + Repository 层是数据访问层，封装所有数据库查询操作。项目通过 `BaseRepository` 基类提供通用 CRUD 能力，子类通常只需声明类名，无需编写任何代码。 ## 文件位置 diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/router.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/router.md index 2fe9b5e..dfe5dd4 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/router.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/router.md @@ -1,5 +1,9 @@ # 路由注册 +:::tip 概述 +路由注册是将模块 Endpoint 挂载到应用的过程，本页讲解在 router.py 中统一注册模块路由的方法。 +::: + 路由注册是将模块的 Endpoint 挂载到应用的过程。所有模块的路由在 `src/api/v1/router.py` 中统一注册。 ## 文件位置 diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/schema.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/schema.md index 4013bcd..1ca3fcd 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/schema.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/schema.md @@ -1,5 +1,9 @@ # Pydantic Schema +:::tip 概述 +Schema 层负责请求数据校验，本页讲解基于 Pydantic v2 BaseModel 与 Field 的表单类定义规范。 +::: + Schema 层负责请求数据的校验。项目使用 Pydantic v2 的 `BaseModel` 定义表单类，通过 `Field` 约束字段格式，FastAPI 在接收请求体时自动执行校验。 ## 文件位置 diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/service.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/service.md index 84a1b32..a642ed9 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/service.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume2/service.md @@ -1,5 +1,9 @@ # Service 层 +:::tip 概述 +Service 层是业务逻辑层，本页讲解基于 BaseService 基类声明差异点即可获得完整增删改查能力的编写方式。 +::: + Service 层是业务逻辑层，负责实现具体的业务规则。简单 CRUD 模块继承 `BaseService` 基类，只需声明差异点即可获得完整的增删改查能力。 ## 文件位置 diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/article.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/article.md index bea27f6..08483a8 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/article.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/article.md @@ -1,3 +1,5 @@ +# 文章管理 + :::tip 文章管理 文章管理模块支持富文本编辑、分类关联、封面图片上传、图集管理等功能。适用于新闻、公告、帮助文档等内容管理场景。本模块是典型的「带文件处理」业务模块，涵盖了封面迁移、图集处理、富文本 XSS 清洗等核心机制。 ::: diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/category.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/category.md index ac4c11b..605c03f 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/category.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/category.md @@ -1,3 +1,5 @@ +# 分类管理 + :::tip 分类管理 分类管理模块用于管理树形分类数据，如文章分类、产品分类等。通过 `parent_id` 字段实现无限级分类。 ::: diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/content.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/content.md index 8a1005a..2fb2a91 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/content.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/content.md @@ -1,3 +1,5 @@ +# 公告与链接管理 + :::tip 公告/链接/城市 公告、链接、城市是三个简单 CRUD 内容模块，均继承 BaseService，提供标准的增删改查接口。适用于系统公告、友情链接、城市数据等场景。 ::: diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/dept.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/dept.md index 374223a..e184732 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/dept.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/dept.md @@ -1,3 +1,5 @@ +# 部门/职级/岗位管理 + :::tip 部门/职级/岗位 部门、职级、岗位是组织架构管理的三个核心模块。部门采用树形结构，职级和岗位为简单 CRUD 模块，均继承 `BaseService`。用户表通过 `dept_id`、`position_id`、`level_id` 三个外键关联这三个模块。 ::: diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/job.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/job.md index 6fdf1d8..6aa953e 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/job.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/job.md @@ -1,3 +1,5 @@ +# 定时任务 + :::tip 定时任务 定时任务模块基于 APScheduler 实现，支持 Cron 表达式调度、任务执行日志、动态启停等功能。包含 job（任务定义）、job_log（执行日志）、scheduler（调度器）三个子模块。 ::: diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/menu.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/menu.md index 37776cb..9a66782 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/menu.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/menu.md @@ -1,3 +1,5 @@ +# 菜单管理 + :::tip 菜单管理 菜单管理是 RBAC 权限系统的基础，负责管理系统的导航菜单和权限节点。支持目录/菜单（type=0）和权限按钮节点（type=1）两种类型，通过树形结构组织。权限节点由系统根据前端勾选自动生成，采用 `sys:module:action` 三段式命名。 ::: diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/param.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/param.md index 0ec1e7e..6287408 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/param.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/param.md @@ -1,3 +1,5 @@ +# 参数管理 + :::tip 参数管理 参数管理模块用于管理动态系统参数，与系统配置模块类似但更侧重于业务参数的灵活配置。支持按参数键查询、修改，无需重启服务即可生效。本模块是典型的「BaseService 简单模块」，通过声明差异点即可获得完整 CRUD 能力。 ::: diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/role.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/role.md index 2b87459..a816c2c 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/role.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/role.md @@ -1,3 +1,5 @@ +# 角色管理 + :::tip 角色管理 角色是 RBAC 权限模型的核心，连接用户和菜单（权限）。通过为角色分配菜单权限，再将角色分配给用户，实现灵活的权限管理。角色删除时需清理关联的用户角色和角色菜单数据，并即时失效受影响用户的权限缓存。 ::: diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/user.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/user.md index 7cc450c..33a074f 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/user.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/business/user.md @@ -1,3 +1,5 @@ +# 用户管理 + :::tip 用户管理 用户管理是系统的核心模块，属于复杂业务模块。包含用户 CRUD、角色关联、密码加密、行政区划、Excel 导入导出等功能。与简单 CRUD 模块不同，用户管理使用自定义 service 函数而非继承 BaseService 的类方法。 ::: diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/captcha.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/captcha.md index c8a9b51..240e6b6 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/captcha.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/captcha.md @@ -1,3 +1,5 @@ +# 验证码机制 + :::tip 验证码 验证码是防止自动化攻击的重要安全手段。使用 Pillow 生成图片验证码，存储在 Redis 中，支持防刷限流和万能验证码（演示模式）。源码位于 `src/utils/captcha.py`。 ::: diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/config.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/config.md index 205a3e1..26941c0 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/config.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/config.md @@ -1,3 +1,5 @@ +# 系统配置管理 + :::tip 系统配置 系统配置模块用于管理动态的键值对配置项，与数据字典类似但更偏向系统级参数。支持分组管理，可通过接口动态修改，无需重启服务。模块位于 `src/modules/configuration/`，端点位于 `src/api/v1/endpoints/config.py` 和 `config_item.py`。 ::: diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/cors.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/cors.md index 58b0f89..7f4f409 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/cors.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/cors.md @@ -1,3 +1,5 @@ +# 跨域资源共享（CORS） + :::tip CORS跨域 CORS（Cross-Origin Resource Sharing）跨域资源共享是前后端分离架构必须处理的问题。通过 `CORS_ALLOWED_ORIGINS` 环境变量配置允许的跨域源。中间件位于 `src/middleware/cors.py`。 ::: diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/demo-mode.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/demo-mode.md index 3b9651c..bce77fe 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/demo-mode.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/demo-mode.md @@ -1,3 +1,5 @@ +# 演示模式 + :::tip 演示模式 演示模式用于在线体验环境，开启后所有写操作（新增、编辑、删除等）将被拦截，返回"演示环境，暂无操作权限"提示。通过 `FASTAPI_DEMO` 环境变量控制。装饰器位于 `src/core/access_decorators.py`。 ::: diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/dict.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/dict.md index 2fde590..ad7ec59 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/dict.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/dict.md @@ -1,3 +1,5 @@ +# 字典模块 + :::tip 数据字典 数据字典用于管理系统中的枚举值和配置项，如状态、类型、性别等。通过字典编码统一管理，前端可通过 `useDictStore` 获取字典选项，避免硬编码。后端读取工具位于 `src/utils/dict_util.py`，内置进程内 TTL 缓存。 ::: diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/exception.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/exception.md index 8da880b..c9bca69 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/exception.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/exception.md @@ -1,3 +1,5 @@ +# 异常与响应处理 + :::tip 全局异常与响应 定义了统一的响应格式和全局异常处理机制。所有 API 返回 `{code, data, msg, ok}` 标准格式，异常被捕获后也转换为相同格式。响应函数位于 `src/core/response.py`，异常类型位于 `src/core/exceptions.py`。 ::: diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/idempotent.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/idempotent.md index 60c695f..35adeaa 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/idempotent.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/idempotent.md @@ -1,3 +1,5 @@ +# 防重复提交 + :::tip 防重复提交 防重复提交是保障数据一致性的重要措施。通过前端防抖和后端唯一性校验双重保护，防止用户重复点击导致的数据重复提交。后端唯一性校验通过 Pydantic `@field_validator` 查询数据库实现。 ::: diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/jwt.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/jwt.md index 9983fab..2e756cc 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/jwt.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/jwt.md @@ -1,3 +1,5 @@ +# 用户认证（JWT） + :::tip JWT认证 JWT（JSON Web Token）是的核心认证机制。用户登录成功后获取 Token，后续请求通过 `Authorization: Bearer <token>` 头携带 Token 进行身份验证。项目内置了 Token 生成、解析、刷新和黑名单管理功能，源码位于 `src/core/jwt.py`。 ::: diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/login-log.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/login-log.md index 3655d26..b5b5d47 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/login-log.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/login-log.md @@ -1,3 +1,5 @@ +# 登录日志 + :::tip 登录日志 登录日志记录每次登录尝试（成功/失败），包含登录账号、IP地址、浏览器信息、登录时间等。支持 IP 地理位置解析（ip2region）和 User-Agent 解析。登录逻辑位于 `src/modules/auth/service.py`，日志记录位于 `src/modules/login_log/service.py`。 ::: diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/operation-log.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/operation-log.md index 9b09821..f77ba18 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/operation-log.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/operation-log.md @@ -1,3 +1,5 @@ +# 操作日志 + :::tip 操作日志 操作日志中间件自动拦截写请求（POST/PUT/DELETE/PATCH）并记录操作日志，无需手动埋点。日志落库通过 `response.background` 异步执行，不阻塞响应。源码位于 `src/middleware/operation_log.py`。 ::: diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/rate-limit.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/rate-limit.md index d1b703a..d08213a 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/rate-limit.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/rate-limit.md @@ -1,3 +1,5 @@ +# 请求限流 + :::tip 请求限流 请求限流中间件基于 Redis 实现 IP 级别的滑动窗口限流，防止恶意请求和 DoS 攻击。默认关闭，可通过环境变量开启。源码位于 `src/middleware/rate_limit.py`，滑动窗口 Lua 脚本位于 `src/core/redis_client.py`。 ::: diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/rbac.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/rbac.md index 4c2659f..e971e1d 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/rbac.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/rbac.md @@ -1,3 +1,5 @@ +# 权限管理（RBAC） + :::tip RBAC权限 采用基于角色的访问控制（RBAC）模型，通过用户-角色-菜单三层关系实现细粒度的权限管理。权限控制贯穿前后端：后端通过 `@permission_required` 装饰器校验（`src/core/access_decorators.py`），前端通过 `v-perm` 指令控制按钮显隐。 ::: diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/validator.md b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/validator.md index 6004315..e691d69 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/validator.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/volume4/core/validator.md @@ -1,3 +1,5 @@ +# 参数验证（Pydantic） + :::tip 参数验证 使用 Pydantic v2 进行请求参数验证。所有请求体参数通过 Pydantic BaseModel 定义，FastAPI 自动解析和验证 JSON 请求体，验证失败返回标准格式错误信息。BaseForm 基类位于 `src/core/base_schemas.py`。 ::: diff --git a/DjangoAdmin_FastAPI_NaiveVue/zh/why.md b/DjangoAdmin_FastAPI_NaiveVue/zh/why.md index 7ea4a64..c653241 100644 --- a/DjangoAdmin_FastAPI_NaiveVue/zh/why.md +++ b/DjangoAdmin_FastAPI_NaiveVue/zh/why.md @@ -1,7 +1,7 @@ # 为什么选择我们？ :::tip 核心价值 -企业级数据中台不应从零搭建。本框架提供开箱即用的完整解决方案，为中大型企业构建统一的数字化基座。 +本框架提供开箱即用的企业级中台完整解决方案，免去从零搭建成本，助力中大型企业构建统一的数字化基座。 ::: ## 解决什么问题？ diff --git a/DjangoAdmin_Flask_AntdVue/.vitepress/config/en.ts b/DjangoAdmin_Flask_AntdVue/.vitepress/config/en.ts index a1a96ef..b4f6f75 100644 --- a/DjangoAdmin_Flask_AntdVue/.vitepress/config/en.ts +++ b/DjangoAdmin_Flask_AntdVue/.vitepress/config/en.ts @@ -29,7 +29,7 @@ // // themeConfig: { // editLink: { -// pattern: "https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_EleVue", +// pattern: "https://gitee.com/djangoadmin/DjangoAdmin_Flask_AntdVue", // text: "Suggest changes to this page", // }, // diff --git a/DjangoAdmin_Flask_AntdVue/.vitepress/config/extract.d.mts b/DjangoAdmin_Flask_AntdVue/.vitepress/config/extract.d.mts new file mode 100644 index 0000000..2a46233 --- /dev/null +++ b/DjangoAdmin_Flask_AntdVue/.vitepress/config/extract.d.mts @@ -0,0 +1,5 @@ +export declare const SITE_URL: string; +export declare const SITE_DESCRIPTION: string; +export declare function stripNumberPrefix(title: string): string; +export declare function extractDescription(md: string): string; +export declare function extractFaqs(md: string): { q: string; a: string }[]; diff --git a/DjangoAdmin_Flask_AntdVue/.vitepress/config/extract.mjs b/DjangoAdmin_Flask_AntdVue/.vitepress/config/extract.mjs new file mode 100644 index 0000000..5a21e34 --- /dev/null +++ b/DjangoAdmin_Flask_AntdVue/.vitepress/config/extract.mjs @@ -0,0 +1,130 @@ +/** + * SEO/GEO 共享工具（纯 ESM，零依赖）。 + * + * 同时被两类调用方 import： + * 1. VitePress 配置（.ts，esbuild 打包时内联本文件） + * 2. scripts/generate-llms-txt.mjs（Node 直接运行） + * + * 注意：SITE_URL 是全站唯一 URL 真相源。 + * docs 子域当前 TLS 证书为腾讯 CDN 默认证书（*.cdn.myqcloud.com，校验失败）， + * 故暂用 http；证书修复后只需改这里一处。 + */ + +export const SITE_URL = "http://docs.flask.antdvue.djangoadmin.cn"; + +export const SITE_DESCRIPTION = + "DjangoAdmin Flask+AntDesign 企业级中台解决方案开发者文档"; + +/** + * 剥离 H1/标题中的章节编号前缀，用于 <title> 与 JSON-LD headline。 + * 例："5.10 字典模块" → "字典模块"；"K. 贡献指南" → "贡献指南"。 + * 页内 H1 与侧边栏编号保持不变，仅影响 SEO 输出。 + */ +export function stripNumberPrefix(title) { + return String(title) + .replace(/^(?:\d+(?:\.\d+)+|[A-Z]\.)\s+/, "") + .trim(); +} + +/** + * 从页面 Markdown 提取 meta description： + * 1. 首选 `:::tip xxx` 容器内的首句（141/143 页的标准 opener） + * 2. 回退到 H1 后的第一个普通段落 + * 输出压缩为单行、去除行内 Markdown，按中文句末标点截断（≤100 字符）。 + */ +export function extractDescription(md) { + const src = String(md); + const fm = src.match(/^---\r?\n([\s\S]*?)\r?\n---/); + const body = fm ? src.slice(fm[0].length) : src; + + let text = ""; + // frontmatter description 显式声明优先（无 H1 页面的补齐手段） + const fmDesc = fm && fm[1].match(/^description:\s*(.+)$/m); + if (fmDesc) { + text = fmDesc[1].trim().replace(/^["']|["']$/g, ""); + } + const tip = !text && body.match(/^:::\s*tip[^\n]*\n([\s\S]*?)\n:::/m); + if (tip) { + text = tip[1]; + } + if (!text) { + const afterH1 = body.match(/^# (?!#)(.+)$/m); + if (afterH1) { + const rest = body.slice((afterH1.index ?? 0) + afterH1[0].length); + const para = rest + .split(/\n{2,}/) + .find( + (p) => + p.trim() && + !/^\s*#/.test(p) && + !/^\s*:::/.test(p) && + !/^\s*```/.test(p) && + !/^\s*\|/.test(p), + ); + text = para || ""; + } + } + + text = text + .replace(/\s+/g, " ") + .replace(/`([^`]+)`/g, "$1") + .replace(/\*\*([^*]+)\*\*/g, "$1") + .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") + .trim(); + + if (!text) return ""; + + // 按中文句末标点截取首句，上限 100 字符；截断时避免切碎词 + const m = text.match(/^.{1,100}?(?:[。！？!?]|$)/); + let out = m ? m[0] : text.slice(0, 100); + if (out.length < text.length && !/[。！？!?]$/.test(out)) { + out = out.replace(/[^\s，、；：,;:]+$/, ""); + } + return out.trim() || text.slice(0, 100); +} + +function cleanText(s) { + return s + .replace(/^:::[^\n]*$/gm, "") + .replace(/^```[^\n]*$/gm, "") + .replace(/`([^`]+)`/g, "$1") + .replace(/\*\*([^*]+)\*\*/g, "$1") + .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") + .replace(/\s+/g, " ") + .trim(); +} + +/** + * 提取页面中的 Q/A 对（用于 FAQPage JSON-LD），支持两种站内格式： + * A. `### Q：问题` 标题式（如 zh/quickstart/faq.md） + * B. `**Q：问题**` 加粗式（如 zh/appendix/faq.md） + * 返回 [{ q, a }]；无匹配返回 []。 + */ +export function extractFaqs(md) { + const body = String(md).replace(/^---[\s\S]*?\n---\s*/, ""); + let faqs = []; + + // 格式 A：按 `### Q：` 切块，答案截断到下一个标题 + for (const part of body.split(/(?=^###\s*Q[：:])/m)) { + const m = part.match(/^###\s*Q[：:]\s*([^\n]+)\n+([\s\S]*)/); + if (!m) continue; + let a = m[2]; + const cut = a.search(/^#{1,4}\s/m); + if (cut >= 0) a = a.slice(0, cut); + faqs.push({ q: cleanText(m[1]), a: cleanText(a) }); + } + + // 格式 B：按 `**Q：` 切块 + if (!faqs.length) { + for (const part of body.split(/(?=^\*\*Q[：:])/m)) { + const m = part.match(/^\*\*Q[：:]\s*([^*]+)\*\*\s*\n+([\s\S]*)/); + if (!m) continue; + let a = m[2]; + const cut = a.search(/^(?:#{1,4}\s|\*\*Q)/m); + if (cut >= 0) a = a.slice(0, cut); + faqs.push({ q: cleanText(m[1]), a: cleanText(a) }); + } + } + + return faqs.filter((f) => f.q && f.a); +} diff --git a/DjangoAdmin_Flask_AntdVue/.vitepress/config/index.ts b/DjangoAdmin_Flask_AntdVue/.vitepress/config/index.ts index 2294856..6627a76 100644 --- a/DjangoAdmin_Flask_AntdVue/.vitepress/config/index.ts +++ b/DjangoAdmin_Flask_AntdVue/.vitepress/config/index.ts @@ -1,14 +1,22 @@ import { defineConfig } from "vitepress"; import { enConfig } from "./en"; +import { createSeoHooks } from "./seo"; import { sharedConfig } from "./shared"; import { zhConfig } from "./zh"; +const seo = createSeoHooks(zhConfig.themeConfig?.sidebar); + export default defineConfig({ ...sharedConfig, ignoreDeadLinks: [ (link) => link.includes('localhost'), ], + // SEO：页面级 title/description、canonical/OG/JSON-LD、sitemap+lastmod + transformPageData: seo.transformPageData, + transformHead: seo.transformHead, + sitemap: seo.sitemap, + locales: { root: { label: "简体中文", lang: "zh-CN", link: "/", ...zhConfig }, // root: { label: "English", lang: "en-US", link: "/", ...enConfig }, diff --git a/DjangoAdmin_Flask_AntdVue/.vitepress/config/seo.ts b/DjangoAdmin_Flask_AntdVue/.vitepress/config/seo.ts new file mode 100644 index 0000000..08c4a7b --- /dev/null +++ b/DjangoAdmin_Flask_AntdVue/.vitepress/config/seo.ts @@ -0,0 +1,311 @@ +/** + * SEO/GEO 构建期钩子（仅 Node 构建时运行，不进客户端 bundle）： + * - transformPageData：每页独立 title（去编号前缀）与 description（取 :::tip 首句） + * - transformHead：canonical / Open Graph / twitter 卡片 / JSON-LD 结构化数据 + * - sitemap.transformItems：注入 lastmod（git 最后提交时间）并过滤 404 + * + * 由 config/index.ts 通过 createSeoHooks(zhConfig.themeConfig?.sidebar) 挂载。 + * 依赖 extract.mjs（纯 ESM，同被 scripts/generate-llms-txt.mjs 复用）。 + */ +import fs from "node:fs"; +import path from "node:path"; +import { execSync } from "node:child_process"; +import { + SITE_URL, + extractDescription, + extractFaqs, + stripNumberPrefix, +} from "./extract.mjs"; + +/** 与 vitepress HeadConfig 同构：[tag, attrs, innerHTML?] */ +type HeadTuple = [string, Record<string, any>, string?]; + +interface SideItem { + text?: string; + link?: string; + items?: SideItem[]; +} + +interface PageDataLike { + relativePath?: string; + title?: string; + description?: string; + frontmatter?: Record<string, any>; + [k: string]: any; +} + +interface TransformCtx { + pageData?: PageDataLike; + title?: string; + description?: string; + content?: string; + siteConfig?: { root?: string; srcDir?: string }; +} + +const ORG = { + "@type": "Organization", + name: "DjangoAdmin", + url: "https://www.djangoadmin.cn", + logo: `${SITE_URL}/logo.png`, + sameAs: [ + "https://gitee.com/djangoadmin/DjangoAdmin_Flask_AntdVue", + "https://www.djangoadmin.cn", + ], +}; + +/** 相对路径 → 站内路由（cleanUrls 关闭，正文页带 .html） */ +function routeOf(relativePath: string): string { + if (relativePath === "index.md") return "/"; + if (relativePath === "404.md") return "/404.html"; + return `/${relativePath.replace(/\.md$/, ".html")}`; +} + +/** 去掉侧边栏文案前导 emoji/符号，保留 "1.1 项目介绍" 这类编号文字 */ +function cleanLabel(s?: string): string { + return (s || "").replace(/^[^\p{L}\p{N}]+/u, "").trim(); +} + +/** 从侧边栏构建 route → 面包屑文案链（含分组小节） */ +function buildCrumbMap(sidebar: unknown): Map<string, string[]> { + const map = new Map<string, string[]>(); + const groups: SideItem[] = Array.isArray(sidebar) + ? sidebar + : ((sidebar as Record<string, SideItem[]>)?.["/zh/"] ?? []); + const walk = (items: SideItem[], trail: string[]) => { + for (const item of items) { + if (item.link && item.link.startsWith("/")) { + map.set(item.link, [...trail, cleanLabel(item.text)]); + } else if (item.items?.length) { + walk(item.items, [...trail, cleanLabel(item.text)]); + } + } + }; + for (const group of groups) { + walk(group.items ?? [], [cleanLabel(group.text)].filter(Boolean)); + } + return map; +} + +/** 从渲染后的 HTML 提取 H1 纯文本（JSON-LD headline 须与页面 H1 一致） */ +function h1OfHtml(html?: string): string { + const m = (html || "").match(/<h1[^>]*>([\s\S]*?)<\/h1>/i); + if (!m) return ""; + return m[1] + .replace(/<[^>]+>/g, "") + .replace(/&/g, "&") + .replace(/</g, "<") + .replace(/>/g, ">") + .replace(/"/g, '"') + .replace(/'/g, "'") + .trim(); +} + +/** 从 Markdown 源提取 H1 纯文本（去除行内 markdown 标记） */ +function h1OfMd(md: string): string { + // 围栏感知：跳过 ``` 代码块内的 # 注释，取真正的页面 H1 + let inFence = false; + for (const line of md.split("\n")) { + if (line.startsWith("```")) { inFence = !inFence; continue; } + if (!inFence && /^# (?!#)/.test(line)) { + return line + .replace(/^# /, "") + .replace(/`([^`]+)`/g, "$1") + .replace(/\*\*([^*]+)\*\*/g, "$1") + .trim(); + } + } + return ""; +} + +export function createSeoHooks(sidebar: unknown) { + const crumbs = buildCrumbMap(sidebar); + const projectDirs: string[] = []; + let gitDates: Map<string, string> | null = null; + + const readMd = (relativePath: string, srcDir?: string): string => { + try { + return fs.readFileSync( + path.resolve(srcDir || process.cwd(), relativePath), + "utf8", + ); + } catch { + return ""; + } + }; + + /** + * 项目内每个文件最后一次 git 提交的 ISO 时间。 + * 单次 git log 调用构建全量映射（key = 相对路径，与 pageData.relativePath 一致）； + * git 不可用时静默降级（sitemap 无 lastmod、JSON-LD 无 dateModified）。 + */ + const getGitDates = (root: string): Map<string, string> => { + if (gitDates) return gitDates; + gitDates = new Map<string, string>(); + try { + const out = execSync( + "git log --format=:::%cI --name-only --relative -n 500 -- .", + { + cwd: root, + encoding: "utf8", + maxBuffer: 64 * 1024 * 1024, + stdio: ["ignore", "pipe", "ignore"], + }, + ); + let current = ""; + for (const line of out.split(/\r?\n/)) { + if (line.startsWith(":::")) { + current = line.slice(3).trim(); + continue; + } + const file = line.trim(); + if (file && current && !gitDates.has(file)) { + gitDates.set(file, current); + } + } + } catch { + // 降级：无 lastmod / dateModified + } + return gitDates; + }; + + /** 每页独立 title（去 "5.10 " 编号前缀，关键词前置）与 description（:::tip 首句） */ + function transformPageData(pageData: PageDataLike, ctx?: any): Record<string, unknown> { + const srcDir: string | undefined = ctx?.siteConfig?.srcDir; + const root: string | undefined = ctx?.siteConfig?.root; + if (root && !projectDirs.includes(root)) projectDirs.push(root); + + const out: Record<string, unknown> = {}; + const rel = pageData.relativePath; + if (rel && !pageData.frontmatter?.description) { + const desc = extractDescription(readMd(rel, srcDir)); + if (desc) out.description = desc; + } + if (pageData.title) { + out.title = stripNumberPrefix(pageData.title); + } + return out; + } + + /** 构建期注入 canonical / OG / twitter / JSON-LD */ + function transformHead(ctx: TransformCtx): HeadTuple[] { + const rel = ctx?.pageData?.relativePath || ""; + if (!rel || rel === "404.md") return []; + + const route = routeOf(rel); + const url = `${SITE_URL}${route}`; + const title = ctx.pageData?.title || ctx.title || ""; + const desc = ctx.description || ""; + const isHome = rel === "index.md"; + const image = `${SITE_URL}/logo.png`; + + const heads: HeadTuple[] = [ + ["link", { rel: "canonical", href: url }], + ["meta", { property: "og:type", content: isHome ? "website" : "article" }], + ["meta", { property: "og:site_name", content: "DjangoAdmin" }], + ["meta", { property: "og:locale", content: "zh_CN" }], + ["meta", { property: "og:title", content: title }], + ["meta", { property: "og:description", content: desc }], + ["meta", { property: "og:url", content: url }], + ["meta", { property: "og:image", content: image }], + ["meta", { property: "twitter:title", content: title }], + ["meta", { property: "twitter:description", content: desc }], + ["meta", { property: "twitter:url", content: url }], + ["meta", { property: "twitter:image", content: image }], + ]; + + // ---- JSON-LD ---- + const root = ctx.siteConfig?.root || projectDirs[0] || process.cwd(); + const srcDir = ctx.siteConfig?.srcDir || root; + const lastMod = getGitDates(root).get(rel); + const blocks: Record<string, any>[] = []; + + if (isHome) { + blocks.push({ + "@context": "https://schema.org", + "@type": "WebSite", + name: "DjangoAdmin 开发文档", + url: `${SITE_URL}/`, + inLanguage: "zh-CN", + description: desc, + }); + blocks.push({ "@context": "https://schema.org", ...ORG }); + } else { + const md = readMd(rel, srcDir); + const article: Record<string, any> = { + "@context": "https://schema.org", + "@type": "TechArticle", + headline: h1OfMd(md) || h1OfHtml(ctx.content) || title, + description: desc, + url, + inLanguage: "zh-CN", + mainEntityOfPage: { "@type": "WebPage", "@id": url }, + publisher: ORG, + }; + if (lastMod) article.dateModified = lastMod; + blocks.push(article); + + const trail = crumbs.get(route); + if (trail?.length) { + const items: Record<string, any>[] = [ + { "@type": "ListItem", position: 1, name: "首页", item: `${SITE_URL}/` }, + ]; + trail.forEach((name, i) => { + const node: Record<string, any> = { + "@type": "ListItem", + position: i + 2, + name, + }; + if (i === trail.length - 1) node.item = url; + items.push(node); + }); + blocks.push({ + "@context": "https://schema.org", + "@type": "BreadcrumbList", + itemListElement: items, + }); + } + + const faqs = extractFaqs(md); + if (faqs.length) { + blocks.push({ + "@context": "https://schema.org", + "@type": "FAQPage", + mainEntity: faqs.map((f) => ({ + "@type": "Question", + name: f.q, + acceptedAnswer: { "@type": "Answer", text: f.a }, + })), + }); + } + } + + // 转义 "<"，防止内容中出现 </script> 破坏注入 + const json = JSON.stringify(blocks).replace(/</g, "\\u003c"); + heads.push(["script", { type: "application/ld+json" }, json]); + return heads; + } + + /** sitemap.xml：过滤 404/README，注入 git lastmod */ + const sitemap = { + hostname: SITE_URL, + transformItems(items: { url: string; lastmod?: string }[]) { + const root = projectDirs[0] || process.cwd(); + const dates = getGitDates(root); + const out: { url: string; lastmod?: string }[] = []; + for (const item of items) { + // ⚠ vitepress 传入的 item.url 是相对路径（"404.html"、"zh/x.html"、""）， + // 无前导斜杠也无域名——hostname 由 SitemapStream 事后拼接。 + if (/(^|\/)404\.html$/.test(item.url)) continue; // 404 页不收录 + if (/(^|\/)README\.html$/.test(item.url)) continue; // 仓库 README 非文档页 + const p = item.url.replace(/^\//, ""); + const rel = + p === "" || p === "index.html" ? "index.md" : p.replace(/\.html$/, ".md"); + const lastmod = dates.get(rel); + out.push(lastmod ? { ...item, lastmod } : item); + } + return out; + }, + }; + + return { transformPageData, transformHead, sitemap }; +} diff --git a/DjangoAdmin_Flask_AntdVue/.vitepress/config/shared.ts b/DjangoAdmin_Flask_AntdVue/.vitepress/config/shared.ts index a78a71e..3fe572a 100644 --- a/DjangoAdmin_Flask_AntdVue/.vitepress/config/shared.ts +++ b/DjangoAdmin_Flask_AntdVue/.vitepress/config/shared.ts @@ -1,6 +1,6 @@ import { defineConfig, HeadConfig } from "vitepress"; -export const META_IMAGE = "/social.png"; +export const META_IMAGE = "/logo.png"; const rControl = /[\u0000-\u001f]/g; const rSpecial = /[\s~`!@#$%^&*()\-_+=[\]{}|\\;:"'“”‘’<>,.?/]+/g; @@ -23,6 +23,8 @@ export const slugify = (str: string): string => export const sharedConfig = defineConfig({ title: "小蚂蚁云", + // 页面 <title> 后缀：「环境准备 | DjangoAdmin 开发文档」（index.md frontmatter 可覆盖） + titleTemplate: "DjangoAdmin 开发文档", appearance: "light", markdown: { diff --git a/DjangoAdmin_Flask_AntdVue/.vitepress/config/zh.ts b/DjangoAdmin_Flask_AntdVue/.vitepress/config/zh.ts index d0766ea..2a5a398 100644 --- a/DjangoAdmin_Flask_AntdVue/.vitepress/config/zh.ts +++ b/DjangoAdmin_Flask_AntdVue/.vitepress/config/zh.ts @@ -1,6 +1,6 @@ import type { DefaultTheme, LocaleSpecificConfig } from "vitepress"; -export const META_URL = "https://www.djangoadmin.cn"; +export const META_URL = "http://docs.flask.antdvue.djangoadmin.cn"; export const META_TITLE = "DjangoAdmin Flask+AntDesign 开发者文档"; export const META_DESCRIPTION = "DjangoAdmin Flask+AntDesign 企业级中台解决方案开发者文档"; diff --git a/DjangoAdmin_Flask_AntdVue/404.md b/DjangoAdmin_Flask_AntdVue/404.md new file mode 100644 index 0000000..c344b20 --- /dev/null +++ b/DjangoAdmin_Flask_AntdVue/404.md @@ -0,0 +1,12 @@ +--- +head: + - - meta + - name: robots + content: noindex +--- + +# 页面不存在 + +抱歉，您访问的页面不存在或已被移动。 + +[返回首页](/) · [浏览文档](/zh/introduction) diff --git a/DjangoAdmin_Flask_AntdVue/package.json b/DjangoAdmin_Flask_AntdVue/package.json index 77bd941..b5517ed 100644 --- a/DjangoAdmin_Flask_AntdVue/package.json +++ b/DjangoAdmin_Flask_AntdVue/package.json @@ -5,7 +5,8 @@ "type": "module", "scripts": { "docs": "vitepress dev .", - "docs:build": "vitepress build .", + "docs:llms": "node scripts/generate-llms-txt.mjs", + "docs:build": "node scripts/generate-llms-txt.mjs && vitepress build .", "docs:preview": "vitepress preview ." }, "dependencies": { diff --git a/DjangoAdmin_Flask_AntdVue/public/llms.txt b/DjangoAdmin_Flask_AntdVue/public/llms.txt new file mode 100644 index 0000000..aa14eb4 --- /dev/null +++ b/DjangoAdmin_Flask_AntdVue/public/llms.txt @@ -0,0 +1,169 @@ +# DjangoAdmin Flask+AntDesign 开发文档 + +> DjangoAdmin Flask+AntDesign 企业级中台解决方案开发者文档。内置 RBAC 权限体系、代码生成器等开箱即用功能，支持五种数据库一键切换。本文档共 139 篇，按章节组织。 + +## 1. 了解项目 + +- [更新日志](http://docs.flask.antdvue.djangoadmin.cn/zh/changelog.html): 更新日志是项目演进的完整记录，帮助开发者和企业了解每个版本的能力变化与技术演进方向。 +- [新手入门指南](http://docs.flask.antdvue.djangoadmin.cn/zh/course.html): 详细的安装步骤请参考 环境准备 章节。 +- [项目介绍](http://docs.flask.antdvue.djangoadmin.cn/zh/introduction.html): DjangoAdmin 是企业级中台解决方案，后端基于 Flask + SQLAlchemy，前端基于 Vue3 + AntDesign，内置 RBAC 权限、代码生成器等开箱即用功能， +- [项目目录结构](http://docs.flask.antdvue.djangoadmin.cn/zh/struct.html): + 保持一致性：目录结构一旦确定，应保持一致性，避免随意更改。 +- [为什么选择我们？](http://docs.flask.antdvue.djangoadmin.cn/zh/why.html): 本框架提供开箱即用的企业级中台完整解决方案，免去从零搭建成本，助力中大型企业构建统一的数字化基座。 + +## 2. 快速入门 + +- [后端启动](http://docs.flask.antdvue.djangoadmin.cn/zh/volume1/backend.html): 启动后端前，请确保已完成 环境准备 章节中的所有软件安装。 +- [数据库初始化](http://docs.flask.antdvue.djangoadmin.cn/zh/volume1/database.html): 数据库初始化前，请确保已完成以下准备工作： 1. 目标数据库服务已启动（如 MySQL 8.0+） 2. .env 文件中的 DB_DRIVER 和数据库连接信息已正确配置 3. Python +- [Docker 一键启动](http://docs.flask.antdvue.djangoadmin.cn/zh/volume1/docker.html): 使用 Docker 方式启动前，请确保已安装以下软件： 1. Docker Desktop（Windows / macOS）或 Docker Engine（Linux） 2. Docker +- [环境变量速查表](http://docs.flask.antdvue.djangoadmin.cn/zh/volume1/env-vars.html): 1. .env.example 是环境变量模板文件，已提交到版本控制。 +- [环境准备](http://docs.flask.antdvue.djangoadmin.cn/zh/volume1/environment.html): 1. 部分软件安装后需要设置本地环境变量，便于在终端中使用命令。 +- [常见问题FAQ](http://docs.flask.antdvue.djangoadmin.cn/zh/volume1/faq.html): 遇到问题时，建议先查看终端日志输出和浏览器控制台（F12）的错误信息，通常能快速定位问题原因。 +- [第一个接口调试](http://docs.flask.antdvue.djangoadmin.cn/zh/volume1/first-api.html): 开始调试前，请确保已完成以下步骤： 1. 后端服务已启动（参见 后端启动） 2. 数据库已初始化（参见 数据库初始化） 3. Redis 服务已启动 +- [前端启动](http://docs.flask.antdvue.djangoadmin.cn/zh/volume1/frontend.html): 启动前端前，请确保已完成 环境准备 章节中的 Node.js 和 pnpm 安装，并已启动后端服务（参见 后端启动）。 + +## 3. 模块开发实战 + +- [路由注册（Flask Blueprint）](http://docs.flask.antdvue.djangoadmin.cn/zh/volume2/blueprint.html): 路由注册基于 Flask Blueprint 机制实现模块化挂载，本页讲解 Blueprint 的定义与在路由中心统一注册的方法。 +- [完整代码清单](http://docs.flask.antdvue.djangoadmin.cn/zh/volume2/code-list.html): 本页汇总岗位管理（Position）模块涉及的全部文件代码，开发时可快速查阅与复制对照。 +- [Router 层（Flask Blueprint）](http://docs.flask.antdvue.djangoadmin.cn/zh/volume2/endpoint.html): Router 层是 HTTP 接口层，负责定义路由、权限装饰器与请求参数解析，编写新接口从本页开始。 +- [常见问题与排错](http://docs.flask.antdvue.djangoadmin.cn/zh/volume2/faq.html): 本页汇总模块开发过程中的常见问题与排错方法，开发受阻时按症状索引即可定位。 +- [前端 API 层](http://docs.flask.antdvue.djangoadmin.cn/zh/volume2/fe-api.html): 前端 API 层封装后端接口的 HTTP 请求，每个业务模块对应一个 API 文件，本页讲解基于 Axios 封装的编写规范。 +- [前端路由与菜单](http://docs.flask.antdvue.djangoadmin.cn/zh/volume2/fe-router.html): 本页讲解前端路由与菜单机制——路由和菜单由后端动态返回，前端只需注册路由组件映射。 +- [前端页面视图](http://docs.flask.antdvue.djangoadmin.cn/zh/volume2/fe-view.html): 前端页面视图是用户直接交互的界面，本页讲解 Vue3 + AntDesign Vue 下一个完整 CRUD 页面的文件组成与编写方式。 +- [数据模型（Model）](http://docs.flask.antdvue.djangoadmin.cn/zh/volume2/model.html): 数据模型是模块开发的第一步，讲解如何用 SQLAlchemy ORM 与基类定义数据库表结构，新建模块时从本页开始。 +- [概述与目标](http://docs.flask.antdvue.djangoadmin.cn/zh/volume2/overview.html): 其中 id、create_user、create_time、update_user、update_time、is_delete 由基类 BaseModel 自动提供，业务字段仅需定义 name、 +- [权限节点配置](http://docs.flask.antdvue.djangoadmin.cn/zh/volume2/permission.html): 实际开发中，查询类权限（page、detail、list）通常合并为一个节点 sys:position:list，减少配置工作量。 +- [Repository 层](http://docs.flask.antdvue.djangoadmin.cn/zh/volume2/repository.html): Repository 层是数据访问层，封装全部数据库查询操作，本页讲解基于 BaseRepository 基类的通用 CRUD 用法。 +- [路由注册](http://docs.flask.antdvue.djangoadmin.cn/zh/volume2/router.html): 路由注册是将模块 Blueprint 挂载到应用的过程，本页讲解在路由注册中心统一挂载的方法。 +- [WTForms Schema](http://docs.flask.antdvue.djangoadmin.cn/zh/volume2/schema.html): Schema 层负责请求数据校验，本页讲解基于 WTForms 表单类与 validators 的校验规范。 +- [Service 层](http://docs.flask.antdvue.djangoadmin.cn/zh/volume2/service.html): Service 层是业务逻辑层，本页讲解基于 BaseService 基类声明差异点即可获得完整增删改查能力的编写方式。 + +## 4. 架构设计 + +- [应用工厂与扩展初始化](http://docs.flask.antdvue.djangoadmin.cn/zh/volume3/app-factory.html): Flask 应用工厂模式（create_app()）是项目的核心初始化机制。 +- [核心基类体系](http://docs.flask.antdvue.djangoadmin.cn/zh/volume3/base-classes.html): 五大基类各司其职，覆盖从数据模型到请求校验再到业务逻辑的完整链路。 +- [缓存架构设计](http://docs.flask.antdvue.djangoadmin.cn/zh/volume3/cache.html): 项目采用两级缓存架构：第一级为进程内字典缓存（dict_util），第二级为 Redis 分布式缓存。 +- [数据库设计](http://docs.flask.antdvue.djangoadmin.cn/zh/volume3/database-design.html): 所有业务表继承 BaseModel 基类，自动获得 6 个通用字段（id / create_user / create_time / update_user / update_time / +- [目录结构设计](http://docs.flask.antdvue.djangoadmin.cn/zh/volume3/directory.html): 目录结构遵循「按功能分组、按职责分层」的原则。 +- [扩展性设计](http://docs.flask.antdvue.djangoadmin.cn/zh/volume3/extensibility.html): 遵循开闭原则（OCP）：对扩展开放，对修改关闭。 +- [Flask g 对象与请求上下文](http://docs.flask.antdvue.djangoadmin.cn/zh/volume3/flask-g-object.html): Flask 的 g 对象是请求级别的全局变量容器，用于在同一请求的不同函数间共享数据。 +- [分层架构设计](http://docs.flask.antdvue.djangoadmin.cn/zh/volume3/layer-arch.html): 采用经典的三层架构，核心原则是：依赖单向、职责单一、接口隔离。 +- [整体架构图](http://docs.flask.antdvue.djangoadmin.cn/zh/volume3/overview.html): 遵循以下架构设计原则，确保系统在长期演进中保持高质量和可维护性： +- [请求完整链路](http://docs.flask.antdvue.djangoadmin.cn/zh/volume3/request-flow.html): 一个典型的 API 请求经过以下阶段：浏览器 → Nginx → CORS → Redis 注入 → DB 会话 → 操作日志 → 路由匹配 → JWT 认证 → RBAC 鉴权 → WTForms +- [安全架构设计](http://docs.flask.antdvue.djangoadmin.cn/zh/volume3/security.html): 纵深防御：认证、授权、参数校验多层防护，单一防线失效时仍有其他机制兜底 最小权限：用户仅能访问已授权接口，角色权限按需分配，遵循"够用即可"原则 数据不落地：敏感信息（Token、 +- [同步架构设计](http://docs.flask.antdvue.djangoadmin.cn/zh/volume3/sync-arch.html): 1. 成熟稳定：Flask 的同步模型经过长期验证，稳定可靠 2. 易于理解：同步编程模型更直观，易于调试和维护 3. 工具完善：Flask 生态完善，各种扩展和工具支持良好 4. 部署简单： +- [同步编程模型](http://docs.flask.antdvue.djangoadmin.cn/zh/volume3/sync-async.html): Flask 基于 WSGI 同步框架，所有视图函数和业务代码均为同步 def。 +- [技术选型说明](http://docs.flask.antdvue.djangoadmin.cn/zh/volume3/tech-stack.html): Flask 是 Python 生态中最轻量、最灵活的 Web 框架，基于 WSGI 同步模型，成熟稳定，易于调试和部署。 + +## 5. 开发指南 + +- [API 接口速查表](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/api-cheatsheet.html): API 接口速查表，按模块分组列出所有 RESTful 接口的请求方法、路径、说明和权限标识。 +- [文章管理](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/business/article.html): 文章管理模块支持富文本编辑、分类关联、封面图片上传、图集管理等功能。 +- [分类管理](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/business/category.html): 分类管理模块用于管理树形分类数据，如文章分类、产品分类等。 +- [行政区划管理](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/business/city.html): 行政区划模块管理全国省/市/区/街道四级区域数据，支持树形结构查询、级联选择器、拼音自动生成等功能。 +- [公告与链接管理](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/business/content.html): 公告、链接、城市是三个简单 CRUD 内容模块，均继承 BaseService，提供标准的增删改查接口。 +- [部门/职级/岗位管理](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/business/dept.html): 部门、职级、岗位是组织架构管理的三个核心模块。 +- [案例演示](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/business/example.html): 案例演示模块是代码生成器的参考模板，展示了标准 CRUD 模块的完整实现。 +- [文件模板管理](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/business/file-template.html): 文件模板模块用于管理系统中的文件模板，如导入导出模板、报表模板等。 +- [定时任务](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/business/job.html): 定时任务模块基于 APScheduler 实现，支持 Cron 表达式调度、任务执行日志、动态启停等功能。 +- [菜单管理](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/business/menu.html): 菜单管理是 RBAC 权限系统的基础，负责管理系统的导航菜单和权限节点。 +- [参数管理](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/business/param.html): 参数管理模块用于管理系统配置和业务配置，每个参数包含名称、编码、值、类型、排序、状态等属性。 +- [角色管理](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/business/role.html): 角色是 RBAC 权限模型的核心，连接用户和菜单（权限）。 +- [用户管理](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/business/user.html): 用户管理是系统的核心模块，属于复杂业务模块。 +- [认证流程实战](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/core/auth-flow.html): 登录 → Token 获取 → 权限校验 → Token 刷新 → 退出登录的完整认证链路实战说明。 +- [验证码机制](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/core/captcha.html): 验证码是防止自动化攻击的重要安全手段。 +- [系统配置管理](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/core/config.html): 系统配置模块用于管理动态的键值对配置项，与数据字典类似但更偏向系统级参数。 +- [跨域资源共享（CORS）](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/core/cors.html): CORS（Cross-Origin Resource Sharing）跨域资源共享是前后端分离架构必须处理的问题。 +- [演示模式](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/core/demo-mode.html): 演示模式用于在线体验环境，开启后所有写操作（新增、编辑、删除等）将被拦截，返回"演示环境，暂无操作权限"提示。 +- [数据字典使用指南](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/core/dict-guide.html): 数据字典的完整使用流程，从新增字典类型到在代码中使用字典数据的实操指南。 +- [字典模块](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/core/dict.html): 数据字典用于管理系统中的枚举值和配置项，如状态、类型、性别等。 +- [异常与响应处理](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/core/exception.html): 项目定义了统一的响应格式和全局异常处理机制。 +- [防重复提交](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/core/idempotent.html): 防重复提交是保障数据一致性的重要措施。 +- [用户认证（JWT）](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/core/jwt.html): JWT（JSON Web Token）是项目的核心认证机制。 +- [登录日志](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/core/login-log.html): 登录日志记录每次登录尝试（成功/失败），包含登录账号、IP地址、浏览器信息、登录时间等。 +- [操作日志](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/core/operation-log.html): 操作日志中间件自动拦截写请求（POST/PUT/DELETE/PATCH）并记录操作日志，无需手动埋点。 +- [权限管理（RBAC）](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/core/rbac.html): 项目采用基于角色的访问控制（RBAC）模型，通过用户-角色-菜单三层关系实现细粒度的权限管理。 +- [事务装饰器](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/core/transaction-decorator.html): 本页讲解事务装饰器的用法，适用于中间件自动事务之外的特殊场景事务控制。 +- [AOP 事务管理](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/core/transaction.html): 本页讲解 AOP 风格的事务管理机制——中间件自动管理数据库事务，业务代码无需手动 commit 或 rollback。 +- [参数验证（Schema）](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/core/validator.html): 项目使用 WTForms 进行请求参数验证。 +- [API 层开发](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/frontend/api.html): 前端 API 层位于 src/api/ 目录，封装所有与后端的 HTTP 请求。 +- [前端构建](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/frontend/build.html): 前端使用 Vite 构建，支持开发服务器和生产构建。 +- [公共组件库](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/frontend/components.html): 项目提供丰富的公共组件，位于 ui/src/components/ 目录，基于 AntDesign Vue 二次封装，覆盖表格、表单、弹窗、上传、富文本编辑等常见场景。 +- [BasicForm 表单](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/frontend/form.html): BasicForm 位于 src/components/Form/src/BasicForm.vue，基于 AntDesign Vue 的 a-form 二次封装，通过 schemas +- [Hooks 组合式函数](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/frontend/hooks.html): 项目封装了一系列组合式函数（Hooks），位于 src/hooks/ 和 src/utils/ 目录，提供权限检查、异步 loading、防重复提交、实时时钟、项目配置等可复用逻辑。 +- [国际化](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/frontend/i18n.html): 当前项目仅支持中文界面，AntDesign Vue 默认中文，所有界面文本直接硬编码在组件中。 +- [Modal 弹窗](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/frontend/modal.html): 项目提供 BasicModal 组件（src/components/Modal/src/basicModal.vue）和原生 a-modal 两种弹窗用法。 +- [权限指令 v-perm](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/frontend/perm-directive.html): v-perm 和 v-perms 是项目自定义的 Vue 指令，用于按钮级别的权限控制，无权限时自动从 DOM 中移除元素。 +- [路由与菜单](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/frontend/router.html): 前端路由基于 Vue Router 4 实现动态路由生成，菜单数据从后端获取，通过 generator-routers.ts 递归生成路由表，路由守卫控制登录状态和权限。 +- [前端环境与结构](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/frontend/setup.html): 前端基于 Vue3 + AntDesign Vue 构建，使用 pnpm 作为包管理工具，Vite 作为构建工具，TypeScript 作为开发语言。 +- [Store 状态管理](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/frontend/store.html): 前端使用 Pinia 进行状态管理，核心模块包括 user（用户信息与权限）、asyncRoute（动态路由与菜单）、projectSetting（项目配置）、designSetting（主题设计）等。 +- [样式与主题](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/frontend/style.html): 前端样式方案采用 Tailwind CSS + Less + AntDesign Vue 主题覆盖，支持深色模式切换。 +- [BasicTable 表格](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/frontend/table.html): BasicTable 位于 src/components/Table/src/Table.vue，基于 AntDesign Vue 的 a-table 二次封装，提供列定义、数据请求、分页、多选、 +- [工具函数](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/frontend/utils.html): 前端工具函数位于 src/utils/ 目录，提供认证管理、本地存储、日期格式化、树结构操作、文件下载等通用能力。 +- [页面视图开发](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/frontend/view.html): 页面视图位于 src/views/ 目录，每个业务模块遵循 index.vue（列表页）+ edit.vue（编辑弹窗）的标准模式，辅以 columns.ts（列定义）和 +- [接口响应规范](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/integration/api-contract.html): 后端所有接口统一返回 R.ok() / R.failed() 格式的 JSON 响应，前端通过 VAxios 的 transformRequestData 拦截器统一解包处理。 +- [字典数据联调](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/integration/dict-sync.html): 字典数据通过后端字典 API 获取，前端在下拉选择器中渲染选项。 +- [权限节点联动](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/integration/perm-sync.html): 前后端权限通过统一的权限节点字符串联动，后端 @check_permission 校验权限，前端 v-perm 指令和 TableAction 的 auth 属性控制按钮显示。 +- [代理配置](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/integration/proxy.html): 开发环境通过 Vite 代理转发 API 请求到后端，生产环境通过 Nginx 代理。 +- [文件上传联调](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/integration/upload-sync.html): 文件上传涉及前端 Upload 组件、后端上传接口和 URL 拼接三个环节，需要前后端协同配置。 +- [数据库会话](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/tools/db-session.html): 项目通过 Flask 的 g 对象和 before_request / after_request 钩子实现请求级数据库会话管理，写操作按业务成功与否自动 commit/rollback。 +- [导入导出](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/tools/excel.html): 项目基于 openpyxl 实现 Excel 导入导出功能，支持通过 file_template 模块管理导入模板配置。 +- [代码生成器](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/tools/generator.html): 本页讲解代码生成器的用法，可根据数据库表结构一键生成前后端 CRUD 全套代码。 +- [IP/UA 解析](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/tools/ip-ua.html): 项目提供客户端 IP 获取、IP 地理位置查询和 User-Agent 解析三大能力。 +- [密码工具](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/tools/password.html): 项目采用 bcrypt 双重加盐方案存储密码，源码位于 src/core/password.py。 +- [权限缓存](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/tools/perm-cache.html): 项目通过 Redis 实现用户权限和菜单的缓存，采用用户级缓存 + 全局版本号双层策略。 +- [请求解析工具](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/tools/request-util.html): src/common/utils/request.py 提供请求数据解析相关的工具函数，包括批量 ID 解析、SQL LIKE 安全处理、分页参数解析等。 +- [富文本过滤](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/tools/rich-text.html): 富文本编辑器内容存在存储型 XSS 风险，项目通过 bleach 库实现 HTML 白名单清洗，在落盘前统一过滤危险内容。 +- [文件上传完整流程](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/tools/upload-guide.html): 富文本编辑器（如 TinyMCE、CKEditor、WangEditor 等）的图片上传同样使用此接口。 +- [文件上传](http://docs.flask.antdvue.djangoadmin.cn/zh/volume4/tools/upload.html): 项目提供本地文件上传功能，支持图片和通用文件上传，内置扩展名白名单、大小限制、魔术字节校验和路径遍历防护。 + +## 6. 代码生成器 + +- [CLI 命令行使用](http://docs.flask.antdvue.djangoadmin.cn/zh/volume5/cli.html): 代码生成器 CLI 模式的使用方法，包括单表生成、批量生成、预览模式和配置导出。 +- [代码生成引擎](http://docs.flask.antdvue.djangoadmin.cn/zh/volume5/code-engine.html): 代码生成引擎的工作原理，包括配置解析、模板渲染、文件写入和自动注册的完整流程。 +- [配置文件详解](http://docs.flask.antdvue.djangoadmin.cn/zh/volume5/config.html): 代码生成器 JSON 配置文件的格式说明，包括模块名称、字段属性、字典编码等配置项的详细解释。 +- [实战案例](http://docs.flask.antdvue.djangoadmin.cn/zh/volume5/demo.html): 以 flask_example 演示表为完整案例，演示从建表到生成到使用的全流程。 +- [常见问题](http://docs.flask.antdvue.djangoadmin.cn/zh/volume5/faq.html): 代码生成器使用过程中常见问题的原因分析和解决方案。 +- [概述与架构](http://docs.flask.antdvue.djangoadmin.cn/zh/volume5/overview.html): 代码生成器的整体架构、核心模块和生成流程概述。 +- [表结构解析引擎](http://docs.flask.antdvue.djangoadmin.cn/zh/volume5/parser.html): 表结构解析引擎的工作原理，从数据库读取表元数据并智能推断字段用途的过程。 +- [自定义模板](http://docs.flask.antdvue.djangoadmin.cn/zh/volume5/templates.html): 代码生成器模板的 Jinja2 语法说明，包括模板变量、字段属性和自定义模板的开发方法。 +- [Web 管理界面](http://docs.flask.antdvue.djangoadmin.cn/zh/volume5/web-ui.html): 代码生成器 Web 管理界面的使用方法，通过可视化界面操作单表生成和批量生成。 + +## 7. 运维部署 + +- [备份与恢复](http://docs.flask.antdvue.djangoadmin.cn/zh/volume6/backup.html): - 3 份数据副本（1 份生产 + 2 份备份） - 2 种不同存储介质（如本地磁盘 + 远程存储） - 1 份异地备份（防机房级灾难） +- [数据库迁移](http://docs.flask.antdvue.djangoadmin.cn/zh/volume6/db-migrate.html): - 结构迁移：Flask-Migrate / Alembic（自动生成 DDL 差异） - 数据迁移：scripts/migrate_db.py（跨库数据泵） - 初始化： +- [部署 Checklist](http://docs.flask.antdvue.djangoadmin.cn/zh/volume6/deploy-checklist.html): 从服务器准备到应用上线的完整部署操作清单，适用于生产环境首次部署和后续版本更新。 +- [Docker容器化](http://docs.flask.antdvue.djangoadmin.cn/zh/volume6/docker.html): - 环境一致性：消除"在我机器上能跑"的问题 - 快速部署：一条命令启动完整服务 - 资源隔离：应用与宿主机环境解耦 +- [环境规划](http://docs.flask.antdvue.djangoadmin.cn/zh/volume6/env-plan.html): 各环境之间保持代码一致，仅通过环境变量（.env）区分配置。 +- [健康检查与监控](http://docs.flask.antdvue.djangoadmin.cn/zh/volume6/monitoring.html): `` 1. 应用层：健康检查端点、业务指标 2. 系统层：CPU/内存/磁盘/网络 3. 中间件：MySQL/Redis 连接状态 4. 日志：集中式日志收集与分析 `` +- [Nginx 反向代理](http://docs.flask.antdvue.djangoadmin.cn/zh/volume6/nginx.html): `` 客户端 → Nginx（80/443） ├─ / → 前端静态资源（dist/） ├─ /api/v1/... → Flask 后端（8021） └─ /api/file/ → 上传文件目录 +- [性能调优](http://docs.flask.antdvue.djangoadmin.cn/zh/volume6/performance.html): 1. 先测量，后优化：用数据说话，避免盲目调参 2. 瓶颈优先：找到最大瓶颈，集中优化 3. 渐进式：每次只调整一个参数，观察效果 +- [生产环境部署实战](http://docs.flask.antdvue.djangoadmin.cn/zh/volume6/production-guide.html): 生产环境部署实战指南，包含完整的部署流程、配置示例、常见问题处理和性能优化建议。 +- [安全加固](http://docs.flask.antdvue.djangoadmin.cn/zh/volume6/security-hardening.html): - 最小权限：只开放必要的端口和权限 - 纵深防御：多层安全措施叠加 - 默认安全：配置默认值应为安全选项 +- [Supervisor进程管理](http://docs.flask.antdvue.djangoadmin.cn/zh/volume6/supervisor.html): - Linux 服务器直接部署（非 Docker） - 需要进程自动重启和日志轮转 - 管理多个相关进程 +- [故障排查手册](http://docs.flask.antdvue.djangoadmin.cn/zh/volume6/troubleshooting.html): 1. 查看日志：tail -f logs/supervisor.out.log 或 docker-compose logs -f 2. 检查配置：.env 文件、数据库连接、Redis 连接 3. +- [版本升级流程](http://docs.flask.antdvue.djangoadmin.cn/zh/volume6/upgrade.html): 1. 先备份，后升级 2. 先测试环境，后生产环境 3. 每次升级可回滚 4. 低峰期执行升级 + +## 8. 规范标准 + +- [API响应规范](http://docs.flask.antdvue.djangoadmin.cn/zh/volume7/api-response.html): - 所有接口必须通过 R.ok() 或 R.failed() 返回，禁止直接返回 dict - 成功响应 code=0，失败响应 code=1 - 响应体始终包含 code、data、msg、ok +- [代码审查清单](http://docs.flask.antdvue.djangoadmin.cn/zh/volume7/code-review.html): - 每次提交必须经过至少一人审查 - 审查关注点：正确性 > 安全性 > 可维护性 > 性能 - 审查意见应具体、可操作，避免主观评价 +- [删除规范](http://docs.flask.antdvue.djangoadmin.cn/zh/volume7/deletion.html): - is_delete = 0：正常记录（默认值） - is_delete = 1：已删除记录 - 所有查询方法自动过滤 is_delete = 0，业务层无需关心 +- [文档规范](http://docs.flask.antdvue.djangoadmin.cn/zh/volume7/doc-standard.html): - 文档与代码同步更新 - 使用中文编写（项目约定） - 示例代码可直接运行 +- [Router层规范](http://docs.flask.antdvue.djangoadmin.cn/zh/volume7/endpoint.html): - Router 只做请求分发，不含业务逻辑 - 通过装饰器控制权限 - 委托 Service 处理业务逻辑 - 返回 R 封装的响应 +- [前端 API 规范](http://docs.flask.antdvue.djangoadmin.cn/zh/volume7/fe-api.html): - 每个后端模块对应一个 API 文件 - 函数命名统一使用 名词 + 动词 格式（与后端保持一致） - 请求路径使用相对路径（/position/page），不含 /api/v1 前缀（由 +- [前端页面规范](http://docs.flask.antdvue.djangoadmin.cn/zh/volume7/fe-component.html): - Vue3（Composition API + <script setup>） - AntDesign Vue 4.x - 自定义组件（BasicTable / BasicForm / +- [Git提交规范](http://docs.flask.antdvue.djangoadmin.cn/zh/volume7/git.html): `` <type>(<scope>): <subject> <body> <footer> `` +- [分页规范](http://docs.flask.antdvue.djangoadmin.cn/zh/volume7/pagination.html): - 前端传递 pageNo（页码，从 1 开始）和 pageSize（每页条数） - 后端返回分页数据字典，包含 items / total / page / pageSize / pages +- [Repository 层规范](http://docs.flask.antdvue.djangoadmin.cn/zh/volume7/repository.html): - Repository 只做数据访问原语，不处理 R 封装/序列化/业务逻辑 - 所有方法均为 @classmethod，无需创建实例 - 软删除由基类自动处理，子类无需关心 - +- [Router层规范](http://docs.flask.antdvue.djangoadmin.cn/zh/volume7/router.html): - Router 层不含业务逻辑，仅做路由定义、权限校验和参数解析 - 装饰器顺序固定为：路由 → 权限 → 演示模式 → 操作日志 - Service 模块在文件顶部统一导入（from +- [Service 层规范](http://docs.flask.antdvue.djangoadmin.cn/zh/volume7/service.html): BaseService 采用模板方法模式：基类定义流程骨架，子类通过声明差异点和覆盖钩子定制行为。 +- [测试规范](http://docs.flask.antdvue.djangoadmin.cn/zh/volume7/testing.html): 1. 契约测试（Contract）：验证路由、权限、表名等契约不变 2. 单元测试（Unit）：验证单个函数/方法的逻辑正确性 3. 集成测试（Integration）：验证模块间协作、真实数据库操作 +- [WTForms Schema 规范](http://docs.flask.antdvue.djangoadmin.cn/zh/volume7/wtforms.html): - 创建/编辑共用一个表单类，继承 BaseForm - 特殊操作单独建类（如状态更新、排序调整） - message 必填，用于返回给前端的错误信息 - 唯一性校验通过自定义 validate_ + +## 附录 + +- [常见问题汇总](http://docs.flask.antdvue.djangoadmin.cn/zh/faq.html): 本页汇总了项目各模块的常见问题及解决方案，按场景分类索引。 +- [免责声明](http://docs.flask.antdvue.djangoadmin.cn/zh/other/declare.html): 使用本产品前必读的法律声明，明确产品性质、使用限制与责任划分，一旦使用本产品即视为接受本声明全部条款。 +- [广告赞助](http://docs.flask.antdvue.djangoadmin.cn/zh/other/sponsor.html): 1. 投放广告不得与官方全系产品存在结构性冲突和竞争 2. 广告内容需符合国家法律法规，不得包含虚假、误导性信息 3. 广告素材需经官方审核通过后方可上线，审核周期 1-3 个工作日 4. diff --git a/DjangoAdmin_Flask_AntdVue/public/robots.txt b/DjangoAdmin_Flask_AntdVue/public/robots.txt new file mode 100644 index 0000000..499a330 --- /dev/null +++ b/DjangoAdmin_Flask_AntdVue/public/robots.txt @@ -0,0 +1,33 @@ +# DjangoAdmin Flask+AntDesign 开发文档 +User-agent: * +Allow: / + +# 显式放行生成式引擎 / AI 爬虫（GEO） +User-agent: GPTBot +Allow: / + +User-agent: ChatGPT-User +Allow: / + +User-agent: ClaudeBot +Allow: / + +User-agent: Claude-Web +Allow: / + +User-agent: anthropic-ai +Allow: / + +User-agent: PerplexityBot +Allow: / + +User-agent: Google-Extended +Allow: / + +User-agent: Bytespider +Allow: / + +User-agent: bingbot +Allow: / + +Sitemap: http://docs.flask.antdvue.djangoadmin.cn/sitemap.xml diff --git a/DjangoAdmin_Flask_AntdVue/scripts/generate-llms-txt.mjs b/DjangoAdmin_Flask_AntdVue/scripts/generate-llms-txt.mjs new file mode 100644 index 0000000..36c6d36 --- /dev/null +++ b/DjangoAdmin_Flask_AntdVue/scripts/generate-llms-txt.mjs @@ -0,0 +1,122 @@ +#!/usr/bin/env node +/** + * 生成 public/llms.txt（llmstxt.org 标准）——AI 爬虫的站点摘要索引。 + * + * 数据源：zh 目录下全部 Markdown 的 H1 + :::tip 概述首句（与 meta + * description 同源，复用 .vitepress/config/extract.mjs）。按侧边栏章节分组。 + * + * 用法：node scripts/generate-llms-txt.mjs + * 已挂入 package.json 的 docs:build 前置步骤。 + */ +import fs from "node:fs"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; +import { + SITE_URL, + SITE_DESCRIPTION, + extractDescription, +} from "../.vitepress/config/extract.mjs"; + +const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."); +const ZH = path.join(ROOT, "zh"); + +/** 顶层目录 → 侧边栏章节名（与 .vitepress/config/zh.ts 保持一致） */ +const SECTIONS = [ + ["", "1. 了解项目"], + ["volume1", "2. 快速入门"], + ["volume2", "3. 模块开发实战"], + ["volume3", "4. 架构设计"], + ["volume4", "5. 开发指南"], + ["volume5", "6. 代码生成器"], + ["volume6", "7. 运维部署"], + ["volume7", "8. 规范标准"], + ["other", "附录"], +]; + +function walk(dir, out = []) { + for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { + const p = path.join(dir, entry.name); + if (entry.isDirectory()) walk(p, out); + else if (entry.name.endsWith(".md")) out.push(p); + } + return out; +} + +/** 提取首个 H1 文本 */ +function h1Of(md) { + // 围栏感知：跳过 ``` 代码块内的 # 注释，取真正的页面 H1 + let inFence = false; + for (const line of md.split("\n")) { + if (line.startsWith("```")) { inFence = !inFence; continue; } + if (!inFence && line.startsWith("# ") && !line.startsWith("## ")) { + return line.slice(2).trim(); + } + } + return ""; +} + +/** H1 编号排序键："5.10 x" → [5,10]；无编号排最后 */ +function sortKey(h1) { + const m = h1.match(/^(\d+(?:\.\d+)*)/); + if (m) return m[1].split(".").map(Number); + const letter = h1.match(/^([A-Z])\./); + if (letter) return [1000 + letter[1].charCodeAt(0)]; + return [9999]; +} + +function cmpKey(a, b) { + const len = Math.max(a.length, b.length); + for (let i = 0; i < len; i++) { + const x = a[i] ?? 0; + const y = b[i] ?? 0; + if (x !== y) return x - y; + } + return 0; +} + +const files = walk(ZH); +const groups = new Map(SECTIONS.map(([dir, label]) => [label, []])); + +for (const file of files) { + const rel = path.relative(ZH, file).replace(/\\/g, "/"); + const topDir = rel.includes("/") ? rel.split("/")[0] : ""; + const base = rel.split("/").pop(); + const label = (topDir === "" && base === "faq.md") ? "附录" + : SECTIONS.find(([dir]) => dir === topDir)?.[1] ?? "附录"; + + const md = fs.readFileSync(file, "utf8"); + const h1 = h1Of(md); + if (!h1) continue; + const desc = extractDescription(md); + const url = `${SITE_URL}/zh/${rel.replace(/\.md$/, ".html")}`; + groups.get(label).push({ h1, desc, url, key: sortKey(h1) }); +} + +const lines = [ + "# DjangoAdmin Flask+AntDesign 开发文档", + "", + `> ${SITE_DESCRIPTION}。内置 RBAC 权限体系、代码生成器等开箱即用功能，支持五种数据库一键切换。本文档共 ${files.length} 篇，按章节组织。`, + "", +]; + +// 按章节顺序输出，合并重复 label（appendix/other 同为「附录」，只输出一次） +const printed = new Set(); +for (const [, label] of SECTIONS) { + if (printed.has(label)) continue; + const items = groups.get(label); + if (!items?.length) continue; + printed.add(label); + + lines.push(`## ${label}`, ""); + items.sort((a, b) => cmpKey(a.key, b.key)); + for (const { h1, desc, url } of items) { + lines.push(desc ? `- [${h1}](${url}): ${desc}` : `- [${h1}](${url})`); + } + lines.push(""); +} + +const out = path.join(ROOT, "public", "llms.txt"); +fs.writeFileSync(out, lines.join("\n"), "utf8"); +console.log( + `llms.txt: ${files.length} 页 → ${path.relative(ROOT, out)} (${printed.size} 个章节)`, +); diff --git a/DjangoAdmin_Flask_AntdVue/zh/course.md b/DjangoAdmin_Flask_AntdVue/zh/course.md index cf4e1fb..e392a3a 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/course.md +++ b/DjangoAdmin_Flask_AntdVue/zh/course.md @@ -1,3 +1,5 @@ +# 新手入门指南 + :::warning 特别提醒 官方精心制作本教程，目的在于方便用户快速掌握软件产品的使用和部署。通过此教程，刚入行的开发者也可以快速掌握并投入产品研发。本地部署时务必请耐心阅读文档操作。 ::: diff --git a/DjangoAdmin_Flask_AntdVue/zh/introduction.md b/DjangoAdmin_Flask_AntdVue/zh/introduction.md index f56800a..2568d77 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/introduction.md +++ b/DjangoAdmin_Flask_AntdVue/zh/introduction.md @@ -1,3 +1,9 @@ +# 项目介绍 + +:::tip 概述 +DjangoAdmin 是企业级中台解决方案，后端基于 Flask + SQLAlchemy，前端基于 Vue3 + AntDesign，内置 RBAC 权限、代码生成器等开箱即用功能，支持五种数据库一键切换。 +::: + <div align="center"> <p align="center"> <img src="/logo.png" height="150" alt="logo"/> diff --git a/DjangoAdmin_Flask_AntdVue/zh/other/declare.md b/DjangoAdmin_Flask_AntdVue/zh/other/declare.md index 7737479..915692a 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/other/declare.md +++ b/DjangoAdmin_Flask_AntdVue/zh/other/declare.md @@ -1,5 +1,9 @@ # 免责声明 +:::tip 概述 +使用本产品前必读的法律声明，明确产品性质、使用限制与责任划分，一旦使用本产品即视为接受本声明全部条款。 +::: + :::danger 重要提示 任何用户在使用本团队研发的系列软件产品（以下简称「本产品」）前，请仔细阅读并透彻理解本声明。选择不使用本产品，可随时停止使用；一旦使用本产品，即视为对本声明全部内容的认可和接受。 ::: diff --git a/DjangoAdmin_Flask_AntdVue/zh/struct.md b/DjangoAdmin_Flask_AntdVue/zh/struct.md index a028572..4c0d8a7 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/struct.md +++ b/DjangoAdmin_Flask_AntdVue/zh/struct.md @@ -1,3 +1,5 @@ +# 项目目录结构 + ## 目录说明 在软件开发过程中，优秀的软件目录结构对于项目的组织、开发、维护和扩展至关重要，合理的目录结构能够显著提升开发效率和代码可维护性。 diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume2/blueprint.md b/DjangoAdmin_Flask_AntdVue/zh/volume2/blueprint.md index 3db027b..6bff9d1 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume2/blueprint.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume2/blueprint.md @@ -1,5 +1,9 @@ # 路由注册（Flask Blueprint） +:::tip 概述 +路由注册基于 Flask Blueprint 机制实现模块化挂载，本页讲解 Blueprint 的定义与在路由中心统一注册的方法。 +::: + Flask 使用 `Blueprint` 机制实现模块化路由注册。每个业务模块定义自己的 Blueprint，然后在路由注册中心统一挂载到应用。 ## Blueprint 概念 diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume2/code-list.md b/DjangoAdmin_Flask_AntdVue/zh/volume2/code-list.md index be7ac1d..524c70b 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume2/code-list.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume2/code-list.md @@ -1,5 +1,9 @@ # 完整代码清单 +:::tip 概述 +本页汇总岗位管理（Position）模块涉及的全部文件代码，开发时可快速查阅与复制对照。 +::: + 本章汇总 Position 岗位模块涉及的全部文件，便于开发时快速查阅和复制。 ## 后端文件清单 diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume2/endpoint.md b/DjangoAdmin_Flask_AntdVue/zh/volume2/endpoint.md index 45b755b..03837f6 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume2/endpoint.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume2/endpoint.md @@ -1,5 +1,9 @@ # Router 层（Flask Blueprint） +:::tip 概述 +Router 层是 HTTP 接口层，负责定义路由、权限装饰器与请求参数解析，编写新接口从本页开始。 +::: + Router 层是 HTTP 接口层，负责定义路由、权限装饰器和请求参数解析。每个业务模块对应一个 router 文件，所有业务逻辑委托给 Service 层处理。 ## 文件位置 diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume2/faq.md b/DjangoAdmin_Flask_AntdVue/zh/volume2/faq.md index f43ef34..b18a4fb 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume2/faq.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume2/faq.md @@ -1,5 +1,9 @@ # 常见问题与排错 +:::tip 概述 +本页汇总模块开发过程中的常见问题与排错方法，开发受阻时按症状索引即可定位。 +::: + 本章汇总模块开发过程中的常见问题和解决方案。 ## 后端问题 diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume2/fe-api.md b/DjangoAdmin_Flask_AntdVue/zh/volume2/fe-api.md index 797cc1c..ae9203a 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume2/fe-api.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume2/fe-api.md @@ -1,5 +1,9 @@ # 前端 API 层 +:::tip 概述 +前端 API 层封装后端接口的 HTTP 请求，每个业务模块对应一个 API 文件，本页讲解基于 Axios 封装的编写规范。 +::: + 前端 API 层负责封装后端接口的 HTTP 请求。每个业务模块对应一个 API 文件，使用项目封装的 Axios 工具发送请求。 ## 文件位置 diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume2/fe-router.md b/DjangoAdmin_Flask_AntdVue/zh/volume2/fe-router.md index 0f79bbe..5c2330b 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume2/fe-router.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume2/fe-router.md @@ -1,5 +1,9 @@ # 前端路由与菜单 +:::tip 概述 +本页讲解前端路由与菜单机制——路由和菜单由后端动态返回，前端只需注册路由组件映射。 +::: + 前端路由定义页面的访问路径，菜单是路由的可视化展示。项目的路由和菜单由后端动态返回，前端只需注册路由组件映射。 ## 路由配置 diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume2/fe-view.md b/DjangoAdmin_Flask_AntdVue/zh/volume2/fe-view.md index bebc2b1..45f2f1c 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume2/fe-view.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume2/fe-view.md @@ -1,5 +1,9 @@ # 前端页面视图 +:::tip 概述 +前端页面视图是用户直接交互的界面，本页讲解 Vue3 + AntDesign Vue 下一个完整 CRUD 页面的文件组成与编写方式。 +::: + 前端页面视图是用户直接交互的界面。项目使用 Vue3 + AntDesign Vue + Vite 构建。一个完整的 CRUD 页面由 4 个文件组成： ``` diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume2/model.md b/DjangoAdmin_Flask_AntdVue/zh/volume2/model.md index 7ebcb10..229652c 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume2/model.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume2/model.md @@ -1,5 +1,9 @@ # 数据模型（Model） +:::tip 概述 +数据模型是模块开发的第一步，讲解如何用 SQLAlchemy ORM 与基类定义数据库表结构，新建模块时从本页开始。 +::: + 数据模型是模块开发的第一步，用于定义数据库表结构。项目使用 `SQLAlchemy ORM`，模型类通过继承基类自动获得通用字段和方法。 ## 文件位置 diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume2/repository.md b/DjangoAdmin_Flask_AntdVue/zh/volume2/repository.md index 17f722a..660a1cd 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume2/repository.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume2/repository.md @@ -1,5 +1,9 @@ # Repository 层 +:::tip 概述 +Repository 层是数据访问层，封装全部数据库查询操作，本页讲解基于 BaseRepository 基类的通用 CRUD 用法。 +::: + Repository 层是数据访问层，封装所有数据库查询操作。项目通过 `BaseRepository` 基类提供通用 CRUD 能力，子类只需声明 `model` 并按需实现 `page()` 和 `list_enabled()` 方法。 ## 文件位置 diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume2/router.md b/DjangoAdmin_Flask_AntdVue/zh/volume2/router.md index 7c04da7..8e52cef 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume2/router.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume2/router.md @@ -1,5 +1,9 @@ # 路由注册 +:::tip 概述 +路由注册是将模块 Blueprint 挂载到应用的过程，本页讲解在路由注册中心统一挂载的方法。 +::: + 路由注册是将模块的 Blueprint 挂载到应用的过程。所有模块的路由在 `src/routes/v1.py` 中统一注册。 ## 文件位置 diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume2/schema.md b/DjangoAdmin_Flask_AntdVue/zh/volume2/schema.md index 8f111d1..c0494dc 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume2/schema.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume2/schema.md @@ -1,5 +1,9 @@ # WTForms Schema +:::tip 概述 +Schema 层负责请求数据校验，本页讲解基于 WTForms 表单类与 validators 的校验规范。 +::: + Schema 层负责请求数据的校验。项目使用 `WTForms` 定义表单类，通过 `validators` 约束字段格式，框架在接收请求体时自动执行校验。 ## 文件位置 diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume2/service.md b/DjangoAdmin_Flask_AntdVue/zh/volume2/service.md index 84889f1..35cdece 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume2/service.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume2/service.md @@ -1,5 +1,9 @@ # Service 层 +:::tip 概述 +Service 层是业务逻辑层，本页讲解基于 BaseService 基类声明差异点即可获得完整增删改查能力的编写方式。 +::: + Service 层是业务逻辑层，负责实现具体的业务规则。简单 CRUD 模块继承 `BaseService` 基类，只需声明差异点即可获得完整的增删改查能力。 ## 文件位置 diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume4/business/article.md b/DjangoAdmin_Flask_AntdVue/zh/volume4/business/article.md index 399a9ca..7e8c3fa 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume4/business/article.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume4/business/article.md @@ -1,3 +1,5 @@ +# 文章管理 + :::tip 文章管理 文章管理模块支持富文本编辑、分类关联、封面图片上传、图集管理等功能。适用于新闻、公告、帮助文档等内容管理场景。本模块是典型的「带文件处理」业务模块，涵盖了封面迁移、图集处理、富文本 XSS 清洗等核心机制。 ::: diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume4/business/category.md b/DjangoAdmin_Flask_AntdVue/zh/volume4/business/category.md index 8794984..393f361 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume4/business/category.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume4/business/category.md @@ -1,3 +1,5 @@ +# 分类管理 + :::tip 分类管理 分类管理模块用于管理树形分类数据，如文章分类、产品分类等。通过 `parent_id` 字段实现无限级分类。 ::: diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume4/business/city.md b/DjangoAdmin_Flask_AntdVue/zh/volume4/business/city.md index 0fc2e12..3e9863a 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume4/business/city.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume4/business/city.md @@ -1,3 +1,5 @@ +# 行政区划管理 + :::tip 行政区划 行政区划模块管理全国省/市/区/街道四级区域数据，支持树形结构查询、级联选择器、拼音自动生成等功能。用户表通过 `province_code`/`city_code`/`district_code`/`street_code` 四个字段关联城市表的 `area_code`。 ::: diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume4/business/content.md b/DjangoAdmin_Flask_AntdVue/zh/volume4/business/content.md index e281099..eff119e 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume4/business/content.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume4/business/content.md @@ -1,3 +1,5 @@ +# 公告与链接管理 + :::tip 公告/链接/城市 公告、链接、城市是三个简单 CRUD 内容模块，均继承 BaseService，提供标准的增删改查接口。适用于系统公告、友情链接、城市数据等场景。 ::: diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume4/business/dept.md b/DjangoAdmin_Flask_AntdVue/zh/volume4/business/dept.md index 66d260f..2556b24 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume4/business/dept.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume4/business/dept.md @@ -1,3 +1,5 @@ +# 部门/职级/岗位管理 + :::tip 部门/职级/岗位 部门、职级、岗位是组织架构管理的三个核心模块。部门采用树形结构，职级和岗位为简单 CRUD 模块，均继承 `BaseService`。用户表通过 `dept_id`、`position_id`、`level_id` 三个外键关联这三个模块。 ::: diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume4/business/example.md b/DjangoAdmin_Flask_AntdVue/zh/volume4/business/example.md index d3110ba..fa2edd6 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume4/business/example.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume4/business/example.md @@ -1,3 +1,5 @@ +# 案例演示 + :::tip 案例演示 案例演示模块是代码生成器的参考模板，展示了标准 CRUD 模块的完整实现。包含文件字段处理、枚举字典映射、状态管理等功能，可作为新模块开发的参考范例。 ::: diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume4/business/file-template.md b/DjangoAdmin_Flask_AntdVue/zh/volume4/business/file-template.md index d7e1527..1d8ee75 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume4/business/file-template.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume4/business/file-template.md @@ -1,3 +1,5 @@ +# 文件模板管理 + :::tip 文件模板 文件模板模块用于管理系统中的文件模板，如导入导出模板、报表模板等。支持模板文件上传、按编码查询、文件 URL 自动转换等功能。 ::: diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume4/business/job.md b/DjangoAdmin_Flask_AntdVue/zh/volume4/business/job.md index 6e7c4b4..94304f9 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume4/business/job.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume4/business/job.md @@ -1,3 +1,5 @@ +# 定时任务 + :::tip 定时任务 定时任务模块基于 APScheduler 实现，支持 Cron 表达式调度、任务执行日志、动态启停等功能。包含 job（任务定义）、job_log（执行日志）、scheduler（调度器）三个子模块。 ::: diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume4/business/menu.md b/DjangoAdmin_Flask_AntdVue/zh/volume4/business/menu.md index ef9332a..b88f910 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume4/business/menu.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume4/business/menu.md @@ -1,3 +1,5 @@ +# 菜单管理 + :::tip 菜单管理 菜单管理是 RBAC 权限系统的基础，负责管理系统的导航菜单和权限节点。支持目录/菜单（type=0）和权限按钮节点（type=1）两种类型，通过树形结构组织。权限节点由系统根据前端勾选自动生成，采用 `sys:module:action` 三段式命名。 ::: diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume4/business/param.md b/DjangoAdmin_Flask_AntdVue/zh/volume4/business/param.md index 09e6a68..e107a1b 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume4/business/param.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume4/business/param.md @@ -1,3 +1,5 @@ +# 参数管理 + :::tip 参数管理 参数管理模块用于管理系统配置和业务配置，每个参数包含名称、编码、值、类型、排序、状态等属性。本模块是典型的「BaseService 简单模块」，通过声明差异点即可获得完整 CRUD 能力。 ::: diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume4/business/role.md b/DjangoAdmin_Flask_AntdVue/zh/volume4/business/role.md index aa917c7..3ddaf06 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume4/business/role.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume4/business/role.md @@ -1,3 +1,5 @@ +# 角色管理 + :::tip 角色管理 角色是 RBAC 权限模型的核心，连接用户和菜单（权限）。通过为角色分配菜单权限，再将角色分配给用户，实现灵活的权限管理。角色删除时需清理关联的用户角色和角色菜单数据，并即时失效受影响用户的权限缓存。 ::: diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume4/business/user.md b/DjangoAdmin_Flask_AntdVue/zh/volume4/business/user.md index f9891d6..7f15a85 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume4/business/user.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume4/business/user.md @@ -1,3 +1,5 @@ +# 用户管理 + :::tip 用户管理 用户管理是系统的核心模块，属于复杂业务模块。包含用户 CRUD、角色关联、密码加密、行政区划、Excel 导入导出等功能。用户管理继承 `BaseService` 获得标准 CRUD 能力，并通过覆写钩子方法实现头像保存、密码加密、角色关联等定制逻辑。 ::: diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume4/core/captcha.md b/DjangoAdmin_Flask_AntdVue/zh/volume4/core/captcha.md index d7308b3..dcec275 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume4/core/captcha.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume4/core/captcha.md @@ -1,3 +1,5 @@ +# 验证码机制 + :::tip 验证码 验证码是防止自动化攻击的重要安全手段。项目使用 Pillow 生成图片验证码，存储在 Redis 中，支持防刷限流和万能验证码（演示模式）。源码位于 `src/common/utils/captcha.py`。 ::: diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume4/core/config.md b/DjangoAdmin_Flask_AntdVue/zh/volume4/core/config.md index 82800db..031e0da 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume4/core/config.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume4/core/config.md @@ -1,3 +1,5 @@ +# 系统配置管理 + :::tip 系统配置 系统配置模块用于管理动态的键值对配置项，与数据字典类似但更偏向系统级参数。支持分组管理，可通过接口动态修改，无需重启服务。模块位于 `src/modules/configuration/`，路由位于 `src/modules/configuration/config/router.py` 和 `config_item/router.py`。 ::: diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume4/core/demo-mode.md b/DjangoAdmin_Flask_AntdVue/zh/volume4/core/demo-mode.md index 769e2ea..a94e381 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume4/core/demo-mode.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume4/core/demo-mode.md @@ -1,3 +1,5 @@ +# 演示模式 + :::tip 演示模式 演示模式用于在线体验环境，开启后所有写操作（新增、编辑、删除等）将被拦截，返回"演示环境，暂无操作权限"提示。通过 `FLASK_DEMO` 环境变量控制。装饰器位于 `src/middleware/demo.py`。 ::: diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume4/core/dict.md b/DjangoAdmin_Flask_AntdVue/zh/volume4/core/dict.md index a094aa7..fc0ee0d 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume4/core/dict.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume4/core/dict.md @@ -1,3 +1,5 @@ +# 字典模块 + :::tip 数据字典 数据字典用于管理系统中的枚举值和配置项，如状态、类型、性别等。通过字典编码统一管理，前端可通过 `useDictStore` 获取字典选项，避免硬编码。后端读取工具位于 `src/common/utils/dict_util.py`，内置进程内 TTL 缓存。 ::: diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume4/core/exception.md b/DjangoAdmin_Flask_AntdVue/zh/volume4/core/exception.md index 9d9bd15..db05970 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume4/core/exception.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume4/core/exception.md @@ -1,3 +1,5 @@ +# 异常与响应处理 + :::tip 全局异常与响应 项目定义了统一的响应格式和全局异常处理机制。所有 API 返回 `{code, data, msg, ok}` 标准格式，异常被捕获后也转换为相同格式。响应函数位于 `src/core/response.py`，异常类型位于 `src/core/exceptions.py`。 ::: diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume4/core/idempotent.md b/DjangoAdmin_Flask_AntdVue/zh/volume4/core/idempotent.md index 2849400..0d180f2 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume4/core/idempotent.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume4/core/idempotent.md @@ -1,3 +1,5 @@ +# 防重复提交 + :::tip 防重复提交 防重复提交是保障数据一致性的重要措施。通过前端防抖和后端唯一性校验双重保护，防止用户重复点击导致的数据重复提交。后端唯一性校验通过 WTForms 自定义校验器查询数据库实现。 ::: diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume4/core/jwt.md b/DjangoAdmin_Flask_AntdVue/zh/volume4/core/jwt.md index ea3a013..6492210 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume4/core/jwt.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume4/core/jwt.md @@ -1,3 +1,5 @@ +# 用户认证（JWT） + :::tip JWT认证 JWT（JSON Web Token）是项目的核心认证机制。用户登录成功后获取 Token，后续请求通过 `Authorization: Bearer <token>` 头携带 Token 进行身份验证。项目内置了 Token 生成、解析、刷新和黑名单管理功能，源码位于 `src/core/jwt.py`。 ::: diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume4/core/login-log.md b/DjangoAdmin_Flask_AntdVue/zh/volume4/core/login-log.md index f4edbfa..cb96142 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume4/core/login-log.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume4/core/login-log.md @@ -1,3 +1,5 @@ +# 登录日志 + :::tip 登录日志 登录日志记录每次登录尝试（成功/失败），包含登录账号、IP地址、浏览器信息、登录时间等。支持 IP 地理位置解析（ip2region）和 User-Agent 解析。登录逻辑位于 `src/modules/auth/service.py`，日志记录位于 `src/modules/login_log/service.py`。 ::: diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume4/core/operation-log.md b/DjangoAdmin_Flask_AntdVue/zh/volume4/core/operation-log.md index d9d212f..bc0c873 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume4/core/operation-log.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume4/core/operation-log.md @@ -1,3 +1,5 @@ +# 操作日志 + :::tip 操作日志 操作日志中间件自动拦截写请求（POST/PUT/DELETE/PATCH）并记录操作日志，无需手动埋点。日志落库通过后台线程异步执行，不阻塞响应。源码位于 `src/middleware/operation_log.py`。 ::: diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume4/core/rbac.md b/DjangoAdmin_Flask_AntdVue/zh/volume4/core/rbac.md index 137613f..5513844 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume4/core/rbac.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume4/core/rbac.md @@ -1,3 +1,5 @@ +# 权限管理（RBAC） + :::tip RBAC权限 项目采用基于角色的访问控制（RBAC）模型，通过用户-角色-菜单三层关系实现细粒度的权限管理。权限控制贯穿前后端：后端通过 `@check_permission` 装饰器校验（`src/core/permission.py`），前端通过 `v-perm` 指令控制按钮显隐。 ::: diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume4/core/transaction-decorator.md b/DjangoAdmin_Flask_AntdVue/zh/volume4/core/transaction-decorator.md index ef985d9..bce442e 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume4/core/transaction-decorator.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume4/core/transaction-decorator.md @@ -1,5 +1,9 @@ # 事务装饰器 +:::tip 概述 +本页讲解事务装饰器的用法，适用于中间件自动事务之外的特殊场景事务控制。 +::: + 除了 AOP 中间件自动管理事务外，项目还提供了事务装饰器，用于特殊场景下的事务控制。 ## @transactional 装饰器 diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume4/core/transaction.md b/DjangoAdmin_Flask_AntdVue/zh/volume4/core/transaction.md index 1706af7..a923205 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume4/core/transaction.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume4/core/transaction.md @@ -1,5 +1,9 @@ # AOP 事务管理 +:::tip 概述 +本页讲解 AOP 风格的事务管理机制——中间件自动管理数据库事务，业务代码无需手动 commit 或 rollback。 +::: + 项目采用 AOP（面向切面编程）风格的事务管理机制，通过中间件自动管理数据库事务，业务代码无需手动调用 `commit` 或 `rollback`。 ## 设计理念 diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume4/core/validator.md b/DjangoAdmin_Flask_AntdVue/zh/volume4/core/validator.md index 11e516d..6e11e47 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume4/core/validator.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume4/core/validator.md @@ -1,3 +1,5 @@ +# 参数验证（Schema） + :::tip 参数验证 项目使用 WTForms 进行请求参数验证。所有请求体参数通过 WTForms 表单类定义，框架自动解析和验证 JSON 请求体，验证失败返回标准格式错误信息。BaseForm 基类位于 `src/common/forms/base_form.py`。 ::: diff --git a/DjangoAdmin_Flask_AntdVue/zh/volume4/tools/generator.md b/DjangoAdmin_Flask_AntdVue/zh/volume4/tools/generator.md index cde5df6..60b6716 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/volume4/tools/generator.md +++ b/DjangoAdmin_Flask_AntdVue/zh/volume4/tools/generator.md @@ -1,5 +1,9 @@ # 代码生成器 +:::tip 概述 +本页讲解代码生成器的用法，可根据数据库表结构一键生成前后端 CRUD 全套代码。 +::: + 代码生成器是项目的重要工具，可以根据数据库表结构一键生成前后端 CRUD 代码，包括模型、仓库、服务、路由、表单、前端 API、前端页面等全套代码。 ## 功能概述 diff --git a/DjangoAdmin_Flask_AntdVue/zh/why.md b/DjangoAdmin_Flask_AntdVue/zh/why.md index c2ab8f4..2a2c894 100644 --- a/DjangoAdmin_Flask_AntdVue/zh/why.md +++ b/DjangoAdmin_Flask_AntdVue/zh/why.md @@ -1,7 +1,7 @@ # 为什么选择我们？ :::tip 核心价值 -企业级数据中台不应从零搭建。本框架提供开箱即用的完整解决方案，为中大型企业构建统一的数字化基座。 +本框架提供开箱即用的企业级中台完整解决方案，免去从零搭建成本，助力中大型企业构建统一的数字化基座。 ::: ## 解决什么问题？ diff --git a/DjangoAdmin_Flask_EleVue/.vitepress/config/en.ts b/DjangoAdmin_Flask_EleVue/.vitepress/config/en.ts index a1a96ef..cbbe64f 100644 --- a/DjangoAdmin_Flask_EleVue/.vitepress/config/en.ts +++ b/DjangoAdmin_Flask_EleVue/.vitepress/config/en.ts @@ -29,7 +29,7 @@ // // themeConfig: { // editLink: { -// pattern: "https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_EleVue", +// pattern: "https://gitee.com/djangoadmin/DjangoAdmin_Flask_EleVue", // text: "Suggest changes to this page", // }, // diff --git a/DjangoAdmin_Flask_EleVue/.vitepress/config/extract.d.mts b/DjangoAdmin_Flask_EleVue/.vitepress/config/extract.d.mts new file mode 100644 index 0000000..2a46233 --- /dev/null +++ b/DjangoAdmin_Flask_EleVue/.vitepress/config/extract.d.mts @@ -0,0 +1,5 @@ +export declare const SITE_URL: string; +export declare const SITE_DESCRIPTION: string; +export declare function stripNumberPrefix(title: string): string; +export declare function extractDescription(md: string): string; +export declare function extractFaqs(md: string): { q: string; a: string }[]; diff --git a/DjangoAdmin_Flask_EleVue/.vitepress/config/extract.mjs b/DjangoAdmin_Flask_EleVue/.vitepress/config/extract.mjs new file mode 100644 index 0000000..dfe00f4 --- /dev/null +++ b/DjangoAdmin_Flask_EleVue/.vitepress/config/extract.mjs @@ -0,0 +1,130 @@ +/** + * SEO/GEO 共享工具（纯 ESM，零依赖）。 + * + * 同时被两类调用方 import： + * 1. VitePress 配置（.ts，esbuild 打包时内联本文件） + * 2. scripts/generate-llms-txt.mjs（Node 直接运行） + * + * 注意：SITE_URL 是全站唯一 URL 真相源。 + * docs 子域当前 TLS 证书为腾讯 CDN 默认证书（*.cdn.myqcloud.com，校验失败）， + * 故暂用 http；证书修复后只需改这里一处。 + */ + +export const SITE_URL = "http://docs.flask.elevue.djangoadmin.cn"; + +export const SITE_DESCRIPTION = + "DjangoAdmin Flask+ElementPlus 企业级中台解决方案开发者文档"; + +/** + * 剥离 H1/标题中的章节编号前缀，用于 <title> 与 JSON-LD headline。 + * 例："5.10 字典模块" → "字典模块"；"K. 贡献指南" → "贡献指南"。 + * 页内 H1 与侧边栏编号保持不变，仅影响 SEO 输出。 + */ +export function stripNumberPrefix(title) { + return String(title) + .replace(/^(?:\d+(?:\.\d+)+|[A-Z]\.)\s+/, "") + .trim(); +} + +/** + * 从页面 Markdown 提取 meta description： + * 1. 首选 `:::tip xxx` 容器内的首句（141/143 页的标准 opener） + * 2. 回退到 H1 后的第一个普通段落 + * 输出压缩为单行、去除行内 Markdown，按中文句末标点截断（≤100 字符）。 + */ +export function extractDescription(md) { + const src = String(md); + const fm = src.match(/^---\r?\n([\s\S]*?)\r?\n---/); + const body = fm ? src.slice(fm[0].length) : src; + + let text = ""; + // frontmatter description 显式声明优先（无 H1 页面的补齐手段） + const fmDesc = fm && fm[1].match(/^description:\s*(.+)$/m); + if (fmDesc) { + text = fmDesc[1].trim().replace(/^["']|["']$/g, ""); + } + const tip = !text && body.match(/^:::\s*tip[^\n]*\n([\s\S]*?)\n:::/m); + if (tip) { + text = tip[1]; + } + if (!text) { + const afterH1 = body.match(/^# (?!#)(.+)$/m); + if (afterH1) { + const rest = body.slice((afterH1.index ?? 0) + afterH1[0].length); + const para = rest + .split(/\n{2,}/) + .find( + (p) => + p.trim() && + !/^\s*#/.test(p) && + !/^\s*:::/.test(p) && + !/^\s*```/.test(p) && + !/^\s*\|/.test(p), + ); + text = para || ""; + } + } + + text = text + .replace(/\s+/g, " ") + .replace(/`([^`]+)`/g, "$1") + .replace(/\*\*([^*]+)\*\*/g, "$1") + .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") + .trim(); + + if (!text) return ""; + + // 按中文句末标点截取首句，上限 100 字符；截断时避免切碎词 + const m = text.match(/^.{1,100}?(?:[。！？!?]|$)/); + let out = m ? m[0] : text.slice(0, 100); + if (out.length < text.length && !/[。！？!?]$/.test(out)) { + out = out.replace(/[^\s，、；：,;:]+$/, ""); + } + return out.trim() || text.slice(0, 100); +} + +function cleanText(s) { + return s + .replace(/^:::[^\n]*$/gm, "") + .replace(/^```[^\n]*$/gm, "") + .replace(/`([^`]+)`/g, "$1") + .replace(/\*\*([^*]+)\*\*/g, "$1") + .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") + .replace(/\s+/g, " ") + .trim(); +} + +/** + * 提取页面中的 Q/A 对（用于 FAQPage JSON-LD），支持两种站内格式： + * A. `### Q：问题` 标题式（如 zh/quickstart/faq.md） + * B. `**Q：问题**` 加粗式（如 zh/appendix/faq.md） + * 返回 [{ q, a }]；无匹配返回 []。 + */ +export function extractFaqs(md) { + const body = String(md).replace(/^---[\s\S]*?\n---\s*/, ""); + let faqs = []; + + // 格式 A：按 `### Q：` 切块，答案截断到下一个标题 + for (const part of body.split(/(?=^###\s*Q[：:])/m)) { + const m = part.match(/^###\s*Q[：:]\s*([^\n]+)\n+([\s\S]*)/); + if (!m) continue; + let a = m[2]; + const cut = a.search(/^#{1,4}\s/m); + if (cut >= 0) a = a.slice(0, cut); + faqs.push({ q: cleanText(m[1]), a: cleanText(a) }); + } + + // 格式 B：按 `**Q：` 切块 + if (!faqs.length) { + for (const part of body.split(/(?=^\*\*Q[：:])/m)) { + const m = part.match(/^\*\*Q[：:]\s*([^*]+)\*\*\s*\n+([\s\S]*)/); + if (!m) continue; + let a = m[2]; + const cut = a.search(/^(?:#{1,4}\s|\*\*Q)/m); + if (cut >= 0) a = a.slice(0, cut); + faqs.push({ q: cleanText(m[1]), a: cleanText(a) }); + } + } + + return faqs.filter((f) => f.q && f.a); +} diff --git a/DjangoAdmin_Flask_EleVue/.vitepress/config/index.ts b/DjangoAdmin_Flask_EleVue/.vitepress/config/index.ts index 2294856..6627a76 100644 --- a/DjangoAdmin_Flask_EleVue/.vitepress/config/index.ts +++ b/DjangoAdmin_Flask_EleVue/.vitepress/config/index.ts @@ -1,14 +1,22 @@ import { defineConfig } from "vitepress"; import { enConfig } from "./en"; +import { createSeoHooks } from "./seo"; import { sharedConfig } from "./shared"; import { zhConfig } from "./zh"; +const seo = createSeoHooks(zhConfig.themeConfig?.sidebar); + export default defineConfig({ ...sharedConfig, ignoreDeadLinks: [ (link) => link.includes('localhost'), ], + // SEO：页面级 title/description、canonical/OG/JSON-LD、sitemap+lastmod + transformPageData: seo.transformPageData, + transformHead: seo.transformHead, + sitemap: seo.sitemap, + locales: { root: { label: "简体中文", lang: "zh-CN", link: "/", ...zhConfig }, // root: { label: "English", lang: "en-US", link: "/", ...enConfig }, diff --git a/DjangoAdmin_Flask_EleVue/.vitepress/config/seo.ts b/DjangoAdmin_Flask_EleVue/.vitepress/config/seo.ts new file mode 100644 index 0000000..87c208d --- /dev/null +++ b/DjangoAdmin_Flask_EleVue/.vitepress/config/seo.ts @@ -0,0 +1,311 @@ +/** + * SEO/GEO 构建期钩子（仅 Node 构建时运行，不进客户端 bundle）： + * - transformPageData：每页独立 title（去编号前缀）与 description（取 :::tip 首句） + * - transformHead：canonical / Open Graph / twitter 卡片 / JSON-LD 结构化数据 + * - sitemap.transformItems：注入 lastmod（git 最后提交时间）并过滤 404 + * + * 由 config/index.ts 通过 createSeoHooks(zhConfig.themeConfig?.sidebar) 挂载。 + * 依赖 extract.mjs（纯 ESM，同被 scripts/generate-llms-txt.mjs 复用）。 + */ +import fs from "node:fs"; +import path from "node:path"; +import { execSync } from "node:child_process"; +import { + SITE_URL, + extractDescription, + extractFaqs, + stripNumberPrefix, +} from "./extract.mjs"; + +/** 与 vitepress HeadConfig 同构：[tag, attrs, innerHTML?] */ +type HeadTuple = [string, Record<string, any>, string?]; + +interface SideItem { + text?: string; + link?: string; + items?: SideItem[]; +} + +interface PageDataLike { + relativePath?: string; + title?: string; + description?: string; + frontmatter?: Record<string, any>; + [k: string]: any; +} + +interface TransformCtx { + pageData?: PageDataLike; + title?: string; + description?: string; + content?: string; + siteConfig?: { root?: string; srcDir?: string }; +} + +const ORG = { + "@type": "Organization", + name: "DjangoAdmin", + url: "https://www.djangoadmin.cn", + logo: `${SITE_URL}/logo.png`, + sameAs: [ + "https://gitee.com/djangoadmin/DjangoAdmin_Flask_EleVue", + "https://www.djangoadmin.cn", + ], +}; + +/** 相对路径 → 站内路由（cleanUrls 关闭，正文页带 .html） */ +function routeOf(relativePath: string): string { + if (relativePath === "index.md") return "/"; + if (relativePath === "404.md") return "/404.html"; + return `/${relativePath.replace(/\.md$/, ".html")}`; +} + +/** 去掉侧边栏文案前导 emoji/符号，保留 "1.1 项目介绍" 这类编号文字 */ +function cleanLabel(s?: string): string { + return (s || "").replace(/^[^\p{L}\p{N}]+/u, "").trim(); +} + +/** 从侧边栏构建 route → 面包屑文案链（含分组小节） */ +function buildCrumbMap(sidebar: unknown): Map<string, string[]> { + const map = new Map<string, string[]>(); + const groups: SideItem[] = Array.isArray(sidebar) + ? sidebar + : ((sidebar as Record<string, SideItem[]>)?.["/zh/"] ?? []); + const walk = (items: SideItem[], trail: string[]) => { + for (const item of items) { + if (item.link && item.link.startsWith("/")) { + map.set(item.link, [...trail, cleanLabel(item.text)]); + } else if (item.items?.length) { + walk(item.items, [...trail, cleanLabel(item.text)]); + } + } + }; + for (const group of groups) { + walk(group.items ?? [], [cleanLabel(group.text)].filter(Boolean)); + } + return map; +} + +/** 从渲染后的 HTML 提取 H1 纯文本（JSON-LD headline 须与页面 H1 一致） */ +function h1OfHtml(html?: string): string { + const m = (html || "").match(/<h1[^>]*>([\s\S]*?)<\/h1>/i); + if (!m) return ""; + return m[1] + .replace(/<[^>]+>/g, "") + .replace(/&/g, "&") + .replace(/</g, "<") + .replace(/>/g, ">") + .replace(/"/g, '"') + .replace(/'/g, "'") + .trim(); +} + +/** 从 Markdown 源提取 H1 纯文本（去除行内 markdown 标记） */ +function h1OfMd(md: string): string { + // 围栏感知：跳过 ``` 代码块内的 # 注释，取真正的页面 H1 + let inFence = false; + for (const line of md.split("\n")) { + if (line.startsWith("```")) { inFence = !inFence; continue; } + if (!inFence && /^# (?!#)/.test(line)) { + return line + .replace(/^# /, "") + .replace(/`([^`]+)`/g, "$1") + .replace(/\*\*([^*]+)\*\*/g, "$1") + .trim(); + } + } + return ""; +} + +export function createSeoHooks(sidebar: unknown) { + const crumbs = buildCrumbMap(sidebar); + const projectDirs: string[] = []; + let gitDates: Map<string, string> | null = null; + + const readMd = (relativePath: string, srcDir?: string): string => { + try { + return fs.readFileSync( + path.resolve(srcDir || process.cwd(), relativePath), + "utf8", + ); + } catch { + return ""; + } + }; + + /** + * 项目内每个文件最后一次 git 提交的 ISO 时间。 + * 单次 git log 调用构建全量映射（key = 相对路径，与 pageData.relativePath 一致）； + * git 不可用时静默降级（sitemap 无 lastmod、JSON-LD 无 dateModified）。 + */ + const getGitDates = (root: string): Map<string, string> => { + if (gitDates) return gitDates; + gitDates = new Map<string, string>(); + try { + const out = execSync( + "git log --format=:::%cI --name-only --relative -n 500 -- .", + { + cwd: root, + encoding: "utf8", + maxBuffer: 64 * 1024 * 1024, + stdio: ["ignore", "pipe", "ignore"], + }, + ); + let current = ""; + for (const line of out.split(/\r?\n/)) { + if (line.startsWith(":::")) { + current = line.slice(3).trim(); + continue; + } + const file = line.trim(); + if (file && current && !gitDates.has(file)) { + gitDates.set(file, current); + } + } + } catch { + // 降级：无 lastmod / dateModified + } + return gitDates; + }; + + /** 每页独立 title（去 "5.10 " 编号前缀，关键词前置）与 description（:::tip 首句） */ + function transformPageData(pageData: PageDataLike, ctx?: any): Record<string, unknown> { + const srcDir: string | undefined = ctx?.siteConfig?.srcDir; + const root: string | undefined = ctx?.siteConfig?.root; + if (root && !projectDirs.includes(root)) projectDirs.push(root); + + const out: Record<string, unknown> = {}; + const rel = pageData.relativePath; + if (rel && !pageData.frontmatter?.description) { + const desc = extractDescription(readMd(rel, srcDir)); + if (desc) out.description = desc; + } + if (pageData.title) { + out.title = stripNumberPrefix(pageData.title); + } + return out; + } + + /** 构建期注入 canonical / OG / twitter / JSON-LD */ + function transformHead(ctx: TransformCtx): HeadTuple[] { + const rel = ctx?.pageData?.relativePath || ""; + if (!rel || rel === "404.md") return []; + + const route = routeOf(rel); + const url = `${SITE_URL}${route}`; + const title = ctx.pageData?.title || ctx.title || ""; + const desc = ctx.description || ""; + const isHome = rel === "index.md"; + const image = `${SITE_URL}/logo.png`; + + const heads: HeadTuple[] = [ + ["link", { rel: "canonical", href: url }], + ["meta", { property: "og:type", content: isHome ? "website" : "article" }], + ["meta", { property: "og:site_name", content: "DjangoAdmin" }], + ["meta", { property: "og:locale", content: "zh_CN" }], + ["meta", { property: "og:title", content: title }], + ["meta", { property: "og:description", content: desc }], + ["meta", { property: "og:url", content: url }], + ["meta", { property: "og:image", content: image }], + ["meta", { property: "twitter:title", content: title }], + ["meta", { property: "twitter:description", content: desc }], + ["meta", { property: "twitter:url", content: url }], + ["meta", { property: "twitter:image", content: image }], + ]; + + // ---- JSON-LD ---- + const root = ctx.siteConfig?.root || projectDirs[0] || process.cwd(); + const srcDir = ctx.siteConfig?.srcDir || root; + const lastMod = getGitDates(root).get(rel); + const blocks: Record<string, any>[] = []; + + if (isHome) { + blocks.push({ + "@context": "https://schema.org", + "@type": "WebSite", + name: "DjangoAdmin 开发文档", + url: `${SITE_URL}/`, + inLanguage: "zh-CN", + description: desc, + }); + blocks.push({ "@context": "https://schema.org", ...ORG }); + } else { + const md = readMd(rel, srcDir); + const article: Record<string, any> = { + "@context": "https://schema.org", + "@type": "TechArticle", + headline: h1OfMd(md) || h1OfHtml(ctx.content) || title, + description: desc, + url, + inLanguage: "zh-CN", + mainEntityOfPage: { "@type": "WebPage", "@id": url }, + publisher: ORG, + }; + if (lastMod) article.dateModified = lastMod; + blocks.push(article); + + const trail = crumbs.get(route); + if (trail?.length) { + const items: Record<string, any>[] = [ + { "@type": "ListItem", position: 1, name: "首页", item: `${SITE_URL}/` }, + ]; + trail.forEach((name, i) => { + const node: Record<string, any> = { + "@type": "ListItem", + position: i + 2, + name, + }; + if (i === trail.length - 1) node.item = url; + items.push(node); + }); + blocks.push({ + "@context": "https://schema.org", + "@type": "BreadcrumbList", + itemListElement: items, + }); + } + + const faqs = extractFaqs(md); + if (faqs.length) { + blocks.push({ + "@context": "https://schema.org", + "@type": "FAQPage", + mainEntity: faqs.map((f) => ({ + "@type": "Question", + name: f.q, + acceptedAnswer: { "@type": "Answer", text: f.a }, + })), + }); + } + } + + // 转义 "<"，防止内容中出现 </script> 破坏注入 + const json = JSON.stringify(blocks).replace(/</g, "\\u003c"); + heads.push(["script", { type: "application/ld+json" }, json]); + return heads; + } + + /** sitemap.xml：过滤 404/README，注入 git lastmod */ + const sitemap = { + hostname: SITE_URL, + transformItems(items: { url: string; lastmod?: string }[]) { + const root = projectDirs[0] || process.cwd(); + const dates = getGitDates(root); + const out: { url: string; lastmod?: string }[] = []; + for (const item of items) { + // ⚠ vitepress 传入的 item.url 是相对路径（"404.html"、"zh/x.html"、""）， + // 无前导斜杠也无域名——hostname 由 SitemapStream 事后拼接。 + if (/(^|\/)404\.html$/.test(item.url)) continue; // 404 页不收录 + if (/(^|\/)README\.html$/.test(item.url)) continue; // 仓库 README 非文档页 + const p = item.url.replace(/^\//, ""); + const rel = + p === "" || p === "index.html" ? "index.md" : p.replace(/\.html$/, ".md"); + const lastmod = dates.get(rel); + out.push(lastmod ? { ...item, lastmod } : item); + } + return out; + }, + }; + + return { transformPageData, transformHead, sitemap }; +} diff --git a/DjangoAdmin_Flask_EleVue/.vitepress/config/shared.ts b/DjangoAdmin_Flask_EleVue/.vitepress/config/shared.ts index b34a5fc..304740c 100644 --- a/DjangoAdmin_Flask_EleVue/.vitepress/config/shared.ts +++ b/DjangoAdmin_Flask_EleVue/.vitepress/config/shared.ts @@ -1,6 +1,6 @@ import { defineConfig, HeadConfig } from "vitepress"; -export const META_IMAGE = "/social.png"; +export const META_IMAGE = "/logo.png"; const rControl = /[\u0000-\u001f]/g; const rSpecial = /[\s~`!@#$%^&*()\-_+=[\]{}|\\;:"'“”‘’<>,.?/]+/g; @@ -23,6 +23,8 @@ export const slugify = (str: string): string => export const sharedConfig = defineConfig({ title: "小蚂蚁云", + // 页面 <title> 后缀：「环境准备 | DjangoAdmin 开发文档」（index.md frontmatter 可覆盖） + titleTemplate: "DjangoAdmin 开发文档", appearance: "light", markdown: { diff --git a/DjangoAdmin_Flask_EleVue/.vitepress/config/zh.ts b/DjangoAdmin_Flask_EleVue/.vitepress/config/zh.ts index d268821..7f36871 100644 --- a/DjangoAdmin_Flask_EleVue/.vitepress/config/zh.ts +++ b/DjangoAdmin_Flask_EleVue/.vitepress/config/zh.ts @@ -1,6 +1,6 @@ import type { DefaultTheme, LocaleSpecificConfig } from "vitepress"; -export const META_URL = "https://www.djangoadmin.cn"; +export const META_URL = "http://docs.flask.elevue.djangoadmin.cn"; export const META_TITLE = "DjangoAdmin Flask+ElementPlus 开发者文档"; export const META_DESCRIPTION = "DjangoAdmin Flask+ElementPlus 企业级中台解决方案开发者文档"; diff --git a/DjangoAdmin_Flask_EleVue/404.md b/DjangoAdmin_Flask_EleVue/404.md new file mode 100644 index 0000000..c344b20 --- /dev/null +++ b/DjangoAdmin_Flask_EleVue/404.md @@ -0,0 +1,12 @@ +--- +head: + - - meta + - name: robots + content: noindex +--- + +# 页面不存在 + +抱歉，您访问的页面不存在或已被移动。 + +[返回首页](/) · [浏览文档](/zh/introduction) diff --git a/DjangoAdmin_Flask_EleVue/package.json b/DjangoAdmin_Flask_EleVue/package.json index 77bd941..b5517ed 100644 --- a/DjangoAdmin_Flask_EleVue/package.json +++ b/DjangoAdmin_Flask_EleVue/package.json @@ -5,7 +5,8 @@ "type": "module", "scripts": { "docs": "vitepress dev .", - "docs:build": "vitepress build .", + "docs:llms": "node scripts/generate-llms-txt.mjs", + "docs:build": "node scripts/generate-llms-txt.mjs && vitepress build .", "docs:preview": "vitepress preview ." }, "dependencies": { diff --git a/DjangoAdmin_Flask_EleVue/public/llms.txt b/DjangoAdmin_Flask_EleVue/public/llms.txt new file mode 100644 index 0000000..2435b77 --- /dev/null +++ b/DjangoAdmin_Flask_EleVue/public/llms.txt @@ -0,0 +1,169 @@ +# DjangoAdmin Flask+ElementPlus 开发文档 + +> DjangoAdmin Flask+ElementPlus 企业级中台解决方案开发者文档。内置 RBAC 权限体系、代码生成器等开箱即用功能，支持五种数据库一键切换。本文档共 139 篇，按章节组织。 + +## 1. 了解项目 + +- [更新日志](http://docs.flask.elevue.djangoadmin.cn/zh/changelog.html): 更新日志是项目演进的完整记录，帮助开发者和企业了解每个版本的能力变化与技术演进方向。 +- [新手入门指南](http://docs.flask.elevue.djangoadmin.cn/zh/course.html): 详细的安装步骤请参考 环境准备 章节。 +- [项目介绍](http://docs.flask.elevue.djangoadmin.cn/zh/introduction.html): DjangoAdmin 是企业级中台解决方案，后端基于 Flask + SQLAlchemy，前端基于 Vue3 + ElementPlus，内置 RBAC 权限、代码生成器等开箱即用功能， +- [项目目录结构](http://docs.flask.elevue.djangoadmin.cn/zh/struct.html): + 保持一致性：目录结构一旦确定，应保持一致性，避免随意更改。 +- [为什么选择我们？](http://docs.flask.elevue.djangoadmin.cn/zh/why.html): 本框架提供开箱即用的企业级中台完整解决方案，免去从零搭建成本，助力中大型企业构建统一的数字化基座。 + +## 2. 快速入门 + +- [后端启动](http://docs.flask.elevue.djangoadmin.cn/zh/volume1/backend.html): 启动后端前，请确保已完成 环境准备 章节中的所有软件安装。 +- [数据库初始化](http://docs.flask.elevue.djangoadmin.cn/zh/volume1/database.html): 数据库初始化前，请确保已完成以下准备工作： 1. 目标数据库服务已启动（如 MySQL 8.0+） 2. .env 文件中的 DB_DRIVER 和数据库连接信息已正确配置 3. Python +- [Docker 一键启动](http://docs.flask.elevue.djangoadmin.cn/zh/volume1/docker.html): 使用 Docker 方式启动前，请确保已安装以下软件： 1. Docker Desktop（Windows / macOS）或 Docker Engine（Linux） 2. Docker +- [环境变量速查表](http://docs.flask.elevue.djangoadmin.cn/zh/volume1/env-vars.html): 1. .env.example 是环境变量模板文件，已提交到版本控制。 +- [环境准备](http://docs.flask.elevue.djangoadmin.cn/zh/volume1/environment.html): 1. 部分软件安装后需要设置本地环境变量，便于在终端中使用命令。 +- [常见问题FAQ](http://docs.flask.elevue.djangoadmin.cn/zh/volume1/faq.html): 遇到问题时，建议先查看终端日志输出和浏览器控制台（F12）的错误信息，通常能快速定位问题原因。 +- [第一个接口调试](http://docs.flask.elevue.djangoadmin.cn/zh/volume1/first-api.html): 开始调试前，请确保已完成以下步骤： 1. 后端服务已启动（参见 后端启动） 2. 数据库已初始化（参见 数据库初始化） 3. Redis 服务已启动 +- [前端启动](http://docs.flask.elevue.djangoadmin.cn/zh/volume1/frontend.html): 启动前端前，请确保已完成 环境准备 章节中的 Node.js 和 pnpm 安装，并已启动后端服务（参见 后端启动）。 + +## 3. 模块开发实战 + +- [路由注册（Flask Blueprint）](http://docs.flask.elevue.djangoadmin.cn/zh/volume2/blueprint.html): 路由注册基于 Flask Blueprint 机制实现模块化挂载，本页讲解 Blueprint 的定义与在路由中心统一注册的方法。 +- [完整代码清单](http://docs.flask.elevue.djangoadmin.cn/zh/volume2/code-list.html): 本页汇总岗位管理（Position）模块涉及的全部文件代码，开发时可快速查阅与复制对照。 +- [Router 层（Flask Blueprint）](http://docs.flask.elevue.djangoadmin.cn/zh/volume2/endpoint.html): Router 层是 HTTP 接口层，负责定义路由、权限装饰器与请求参数解析，编写新接口从本页开始。 +- [常见问题与排错](http://docs.flask.elevue.djangoadmin.cn/zh/volume2/faq.html): 本页汇总模块开发过程中的常见问题与排错方法，开发受阻时按症状索引即可定位。 +- [前端 API 层](http://docs.flask.elevue.djangoadmin.cn/zh/volume2/fe-api.html): 前端 API 层封装后端接口的 HTTP 请求，每个业务模块对应一个 API 文件，本页讲解基于 Axios 封装的编写规范。 +- [前端路由与菜单](http://docs.flask.elevue.djangoadmin.cn/zh/volume2/fe-router.html): 本页讲解前端路由与菜单机制——路由和菜单由后端动态返回，前端只需注册路由组件映射。 +- [前端页面视图](http://docs.flask.elevue.djangoadmin.cn/zh/volume2/fe-view.html): 前端页面视图是用户直接交互的界面，本页讲解 Vue3 + ElementPlus 下一个完整 CRUD 页面的文件组成与编写方式。 +- [数据模型（Model）](http://docs.flask.elevue.djangoadmin.cn/zh/volume2/model.html): 数据模型是模块开发的第一步，讲解如何用 SQLAlchemy ORM 与基类定义数据库表结构，新建模块时从本页开始。 +- [概述与目标](http://docs.flask.elevue.djangoadmin.cn/zh/volume2/overview.html): 其中 id、create_user、create_time、update_user、update_time、is_delete 由基类 BaseModel 自动提供，业务字段仅需定义 name、 +- [权限节点配置](http://docs.flask.elevue.djangoadmin.cn/zh/volume2/permission.html): 实际开发中，查询类权限（page、detail、list）通常合并为一个节点 sys:position:list，减少配置工作量。 +- [Repository 层](http://docs.flask.elevue.djangoadmin.cn/zh/volume2/repository.html): Repository 层是数据访问层，封装全部数据库查询操作，本页讲解基于 BaseRepository 基类的通用 CRUD 用法。 +- [路由注册](http://docs.flask.elevue.djangoadmin.cn/zh/volume2/router.html): 路由注册是将模块 Blueprint 挂载到应用的过程，本页讲解在路由注册中心统一挂载的方法。 +- [WTForms Schema](http://docs.flask.elevue.djangoadmin.cn/zh/volume2/schema.html): Schema 层负责请求数据校验，本页讲解基于 WTForms 表单类与 validators 的校验规范。 +- [Service 层](http://docs.flask.elevue.djangoadmin.cn/zh/volume2/service.html): Service 层是业务逻辑层，本页讲解基于 BaseService 基类声明差异点即可获得完整增删改查能力的编写方式。 + +## 4. 架构设计 + +- [应用工厂与扩展初始化](http://docs.flask.elevue.djangoadmin.cn/zh/volume3/app-factory.html): Flask 应用工厂模式（create_app()）是项目的核心初始化机制。 +- [核心基类体系](http://docs.flask.elevue.djangoadmin.cn/zh/volume3/base-classes.html): 五大基类各司其职，覆盖从数据模型到请求校验再到业务逻辑的完整链路。 +- [缓存架构设计](http://docs.flask.elevue.djangoadmin.cn/zh/volume3/cache.html): 项目采用两级缓存架构：第一级为进程内字典缓存（dict_util），第二级为 Redis 分布式缓存。 +- [数据库设计](http://docs.flask.elevue.djangoadmin.cn/zh/volume3/database-design.html): 所有业务表继承 BaseModel 基类，自动获得 6 个通用字段（id / create_user / create_time / update_user / update_time / +- [目录结构设计](http://docs.flask.elevue.djangoadmin.cn/zh/volume3/directory.html): 目录结构遵循「按功能分组、按职责分层」的原则。 +- [扩展性设计](http://docs.flask.elevue.djangoadmin.cn/zh/volume3/extensibility.html): 遵循开闭原则（OCP）：对扩展开放，对修改关闭。 +- [Flask g 对象与请求上下文](http://docs.flask.elevue.djangoadmin.cn/zh/volume3/flask-g-object.html): Flask 的 g 对象是请求级别的全局变量容器，用于在同一请求的不同函数间共享数据。 +- [分层架构设计](http://docs.flask.elevue.djangoadmin.cn/zh/volume3/layer-arch.html): 采用经典的三层架构，核心原则是：依赖单向、职责单一、接口隔离。 +- [整体架构图](http://docs.flask.elevue.djangoadmin.cn/zh/volume3/overview.html): 遵循以下架构设计原则，确保系统在长期演进中保持高质量和可维护性： +- [请求完整链路](http://docs.flask.elevue.djangoadmin.cn/zh/volume3/request-flow.html): 一个典型的 API 请求经过以下阶段：浏览器 → Nginx → CORS → Redis 注入 → DB 会话 → 操作日志 → 路由匹配 → JWT 认证 → RBAC 鉴权 → WTForms +- [安全架构设计](http://docs.flask.elevue.djangoadmin.cn/zh/volume3/security.html): 纵深防御：认证、授权、参数校验多层防护，单一防线失效时仍有其他机制兜底 最小权限：用户仅能访问已授权接口，角色权限按需分配，遵循"够用即可"原则 数据不落地：敏感信息（Token、 +- [同步架构设计](http://docs.flask.elevue.djangoadmin.cn/zh/volume3/sync-arch.html): 1. 成熟稳定：Flask 的同步模型经过长期验证，稳定可靠 2. 易于理解：同步编程模型更直观，易于调试和维护 3. 工具完善：Flask 生态完善，各种扩展和工具支持良好 4. 部署简单： +- [同步编程模型](http://docs.flask.elevue.djangoadmin.cn/zh/volume3/sync-async.html): Flask 基于 WSGI 同步框架，所有视图函数和业务代码均为同步 def。 +- [技术选型说明](http://docs.flask.elevue.djangoadmin.cn/zh/volume3/tech-stack.html): Flask 是 Python 生态中最轻量、最灵活的 Web 框架，基于 WSGI 同步模型，成熟稳定，易于调试和部署。 + +## 5. 开发指南 + +- [API 接口速查表](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/api-cheatsheet.html): API 接口速查表，按模块分组列出所有 RESTful 接口的请求方法、路径、说明和权限标识。 +- [文章管理](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/business/article.html): 文章管理模块支持富文本编辑、分类关联、封面图片上传、图集管理等功能。 +- [分类管理](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/business/category.html): 分类管理模块用于管理树形分类数据，如文章分类、产品分类等。 +- [行政区划管理](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/business/city.html): 行政区划模块管理全国省/市/区/街道四级区域数据，支持树形结构查询、级联选择器、拼音自动生成等功能。 +- [公告与链接管理](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/business/content.html): 公告、链接、城市是三个简单 CRUD 内容模块，均继承 BaseService，提供标准的增删改查接口。 +- [部门/职级/岗位管理](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/business/dept.html): 部门、职级、岗位是组织架构管理的三个核心模块。 +- [案例演示](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/business/example.html): 案例演示模块是代码生成器的参考模板，展示了标准 CRUD 模块的完整实现。 +- [文件模板管理](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/business/file-template.html): 文件模板模块用于管理系统中的文件模板，如导入导出模板、报表模板等。 +- [定时任务](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/business/job.html): 定时任务模块基于 APScheduler 实现，支持 Cron 表达式调度、任务执行日志、动态启停等功能。 +- [菜单管理](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/business/menu.html): 菜单管理是 RBAC 权限系统的基础，负责管理系统的导航菜单和权限节点。 +- [参数管理](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/business/param.html): 参数管理模块用于管理系统配置和业务配置，每个参数包含名称、编码、值、类型、排序、状态等属性。 +- [角色管理](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/business/role.html): 角色是 RBAC 权限模型的核心，连接用户和菜单（权限）。 +- [用户管理](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/business/user.html): 用户管理是系统的核心模块，属于复杂业务模块。 +- [认证流程实战](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/core/auth-flow.html): 登录 → Token 获取 → 权限校验 → Token 刷新 → 退出登录的完整认证链路实战说明。 +- [验证码机制](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/core/captcha.html): 验证码是防止自动化攻击的重要安全手段。 +- [系统配置管理](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/core/config.html): 系统配置模块用于管理动态的键值对配置项，与数据字典类似但更偏向系统级参数。 +- [跨域资源共享（CORS）](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/core/cors.html): CORS（Cross-Origin Resource Sharing）跨域资源共享是前后端分离架构必须处理的问题。 +- [演示模式](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/core/demo-mode.html): 演示模式用于在线体验环境，开启后所有写操作（新增、编辑、删除等）将被拦截，返回"演示环境，暂无操作权限"提示。 +- [数据字典使用指南](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/core/dict-guide.html): 数据字典的完整使用流程，从新增字典类型到在代码中使用字典数据的实操指南。 +- [字典模块](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/core/dict.html): 数据字典用于管理系统中的枚举值和配置项，如状态、类型、性别等。 +- [异常与响应处理](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/core/exception.html): 项目定义了统一的响应格式和全局异常处理机制。 +- [防重复提交](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/core/idempotent.html): 防重复提交是保障数据一致性的重要措施。 +- [用户认证（JWT）](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/core/jwt.html): JWT（JSON Web Token）是项目的核心认证机制。 +- [登录日志](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/core/login-log.html): 登录日志记录每次登录尝试（成功/失败），包含登录账号、IP地址、浏览器信息、登录时间等。 +- [操作日志](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/core/operation-log.html): 操作日志中间件自动拦截写请求（POST/PUT/DELETE/PATCH）并记录操作日志，无需手动埋点。 +- [权限管理（RBAC）](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/core/rbac.html): 项目采用基于角色的访问控制（RBAC）模型，通过用户-角色-菜单三层关系实现细粒度的权限管理。 +- [事务装饰器](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/core/transaction-decorator.html): 本页讲解事务装饰器的用法，适用于中间件自动事务之外的特殊场景事务控制。 +- [AOP 事务管理](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/core/transaction.html): 本页讲解 AOP 风格的事务管理机制——中间件自动管理数据库事务，业务代码无需手动 commit 或 rollback。 +- [参数验证（Schema）](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/core/validator.html): 项目使用 WTForms 进行请求参数验证。 +- [API 层开发](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/frontend/api.html): 前端 API 层位于 src/api/ 目录，封装所有与后端的 HTTP 请求。 +- [前端构建](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/frontend/build.html): 前端使用 Vite 构建，支持开发服务器和生产构建。 +- [公共组件库](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/frontend/components.html): 项目提供丰富的公共组件，位于 ui/src/components/ 目录，基于 ElementPlus 二次封装，覆盖表格、表单、弹窗、上传、富文本编辑等常见场景。 +- [BasicForm 表单](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/frontend/form.html): BasicForm 位于 src/components/Form/src/BasicForm.vue，基于 ElementPlus 的 el-form 二次封装，通过 schemas +- [Hooks 组合式函数](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/frontend/hooks.html): 项目封装了一系列组合式函数（Hooks），位于 src/hooks/ 和 src/utils/ 目录，提供权限检查、异步 loading、防重复提交、实时时钟、项目配置等可复用逻辑。 +- [国际化](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/frontend/i18n.html): 当前项目仅支持中文界面，ElementPlus 使用中文语言包（zh-cn），所有界面文本直接硬编码在组件中。 +- [Modal 弹窗](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/frontend/modal.html): 项目提供 BasicModal 组件（src/components/Modal/src/BasicModal.vue）和原生 el-dialog 两种弹窗用法。 +- [权限指令 v-perm](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/frontend/perm-directive.html): v-perm 和 v-perms 是项目自定义的 Vue 指令，用于按钮级别的权限控制，无权限时自动从 DOM 中移除元素。 +- [路由与菜单](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/frontend/router.html): 前端路由基于 Vue Router 4 实现动态路由生成，菜单数据从后端获取，通过 generator-routers.ts 递归生成路由表，路由守卫控制登录状态和权限。 +- [前端环境与结构](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/frontend/setup.html): 前端基于 Vue3 + ElementPlus 构建，使用 pnpm 作为包管理工具，Vite 作为构建工具，TypeScript 作为开发语言。 +- [Store 状态管理](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/frontend/store.html): 前端使用 Pinia 进行状态管理，核心模块包括 user（用户信息与权限）、asyncRoute（动态路由与菜单）、projectSetting（项目配置）、designSetting（主题设计）等。 +- [样式与主题](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/frontend/style.html): 前端样式方案采用 Tailwind CSS + SCSS + ElementPlus 主题覆盖，支持深色模式切换。 +- [BasicTable 表格](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/frontend/table.html): BasicTable 位于 src/components/Table/src/Table.vue，基于 ElementPlus 的 el-table 二次封装，提供列定义、数据请求、分页、操作列、 +- [工具函数](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/frontend/utils.html): 前端工具函数位于 src/utils/ 目录，提供认证管理、本地存储、日期格式化、树结构操作、文件下载等通用能力。 +- [页面视图开发](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/frontend/view.html): 页面视图位于 src/views/ 目录，每个业务模块遵循 index.vue（列表页）+ edit.vue（编辑弹窗）的标准模式，辅以 columns.ts（列定义）和 +- [接口响应规范](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/integration/api-contract.html): 后端所有接口统一返回 R.ok() / R.failed() 格式的 JSON 响应，前端通过 VAxios 的 transformRequestData 拦截器统一解包处理。 +- [字典数据联调](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/integration/dict-sync.html): 字典数据通过后端字典 API 获取，前端在下拉选择器中渲染选项。 +- [权限节点联动](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/integration/perm-sync.html): 前后端权限通过统一的权限节点字符串联动，后端 @check_permission 校验权限，前端 v-perm 指令和 TableAction 的 auth 属性控制按钮显示。 +- [代理配置](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/integration/proxy.html): 开发环境通过 Vite 代理转发 API 请求到后端，生产环境通过 Nginx 代理。 +- [文件上传联调](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/integration/upload-sync.html): 文件上传涉及前端 Upload 组件、后端上传接口和 URL 拼接三个环节，需要前后端协同配置。 +- [数据库会话](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/tools/db-session.html): 项目通过 Flask 的 g 对象和 before_request / after_request 钩子实现请求级数据库会话管理，写操作按业务成功与否自动 commit/rollback。 +- [导入导出](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/tools/excel.html): 项目基于 openpyxl 实现 Excel 导入导出功能，支持通过 file_template 模块管理导入模板配置。 +- [代码生成器](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/tools/generator.html): 本页讲解代码生成器的用法，可根据数据库表结构一键生成前后端 CRUD 全套代码。 +- [IP/UA 解析](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/tools/ip-ua.html): 项目提供客户端 IP 获取、IP 地理位置查询和 User-Agent 解析三大能力。 +- [密码工具](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/tools/password.html): 项目采用 bcrypt 双重加盐方案存储密码，源码位于 src/core/password.py。 +- [权限缓存](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/tools/perm-cache.html): 项目通过 Redis 实现用户权限和菜单的缓存，采用用户级缓存 + 全局版本号双层策略。 +- [请求解析工具](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/tools/request-util.html): src/common/utils/request.py 提供请求数据解析相关的工具函数，包括批量 ID 解析、SQL LIKE 安全处理、分页参数解析等。 +- [富文本过滤](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/tools/rich-text.html): 富文本编辑器内容存在存储型 XSS 风险，项目通过 bleach 库实现 HTML 白名单清洗，在落盘前统一过滤危险内容。 +- [文件上传完整流程](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/tools/upload-guide.html): 富文本编辑器（如 TinyMCE、CKEditor、WangEditor 等）的图片上传同样使用此接口。 +- [文件上传](http://docs.flask.elevue.djangoadmin.cn/zh/volume4/tools/upload.html): 项目提供本地文件上传功能，支持图片和通用文件上传，内置扩展名白名单、大小限制、魔术字节校验和路径遍历防护。 + +## 6. 代码生成器 + +- [CLI 命令行使用](http://docs.flask.elevue.djangoadmin.cn/zh/volume5/cli.html): 代码生成器 CLI 模式的使用方法，包括单表生成、批量生成、预览模式和配置导出。 +- [代码生成引擎](http://docs.flask.elevue.djangoadmin.cn/zh/volume5/code-engine.html): 代码生成引擎的工作原理，包括配置解析、模板渲染、文件写入和自动注册的完整流程。 +- [配置文件详解](http://docs.flask.elevue.djangoadmin.cn/zh/volume5/config.html): 代码生成器 JSON 配置文件的格式说明，包括模块名称、字段属性、字典编码等配置项的详细解释。 +- [实战案例](http://docs.flask.elevue.djangoadmin.cn/zh/volume5/demo.html): 以 flask_example 演示表为完整案例，演示从建表到生成到使用的全流程。 +- [常见问题](http://docs.flask.elevue.djangoadmin.cn/zh/volume5/faq.html): 代码生成器使用过程中常见问题的原因分析和解决方案。 +- [概述与架构](http://docs.flask.elevue.djangoadmin.cn/zh/volume5/overview.html): 代码生成器的整体架构、核心模块和生成流程概述。 +- [表结构解析引擎](http://docs.flask.elevue.djangoadmin.cn/zh/volume5/parser.html): 表结构解析引擎的工作原理，从数据库读取表元数据并智能推断字段用途的过程。 +- [自定义模板](http://docs.flask.elevue.djangoadmin.cn/zh/volume5/templates.html): 代码生成器模板的 Jinja2 语法说明，包括模板变量、字段属性和自定义模板的开发方法。 +- [Web 管理界面](http://docs.flask.elevue.djangoadmin.cn/zh/volume5/web-ui.html): 代码生成器 Web 管理界面的使用方法，通过可视化界面操作单表生成和批量生成。 + +## 7. 运维部署 + +- [备份与恢复](http://docs.flask.elevue.djangoadmin.cn/zh/volume6/backup.html): - 3 份数据副本（1 份生产 + 2 份备份） - 2 种不同存储介质（如本地磁盘 + 远程存储） - 1 份异地备份（防机房级灾难） +- [数据库迁移](http://docs.flask.elevue.djangoadmin.cn/zh/volume6/db-migrate.html): - 结构迁移：Flask-Migrate / Alembic（自动生成 DDL 差异） - 数据迁移：scripts/migrate_db.py（跨库数据泵） - 初始化： +- [部署 Checklist](http://docs.flask.elevue.djangoadmin.cn/zh/volume6/deploy-checklist.html): 从服务器准备到应用上线的完整部署操作清单，适用于生产环境首次部署和后续版本更新。 +- [Docker容器化](http://docs.flask.elevue.djangoadmin.cn/zh/volume6/docker.html): - 环境一致性：消除"在我机器上能跑"的问题 - 快速部署：一条命令启动完整服务 - 资源隔离：应用与宿主机环境解耦 +- [环境规划](http://docs.flask.elevue.djangoadmin.cn/zh/volume6/env-plan.html): 各环境之间保持代码一致，仅通过环境变量（.env）区分配置。 +- [健康检查与监控](http://docs.flask.elevue.djangoadmin.cn/zh/volume6/monitoring.html): `` 1. 应用层：健康检查端点、业务指标 2. 系统层：CPU/内存/磁盘/网络 3. 中间件：MySQL/Redis 连接状态 4. 日志：集中式日志收集与分析 `` +- [Nginx 反向代理](http://docs.flask.elevue.djangoadmin.cn/zh/volume6/nginx.html): `` 客户端 → Nginx（80/443） ├─ / → 前端静态资源（dist/） ├─ /api/v1/... → Flask 后端（8021） └─ /api/file/ → 上传文件目录 +- [性能调优](http://docs.flask.elevue.djangoadmin.cn/zh/volume6/performance.html): 1. 先测量，后优化：用数据说话，避免盲目调参 2. 瓶颈优先：找到最大瓶颈，集中优化 3. 渐进式：每次只调整一个参数，观察效果 +- [生产环境部署实战](http://docs.flask.elevue.djangoadmin.cn/zh/volume6/production-guide.html): 生产环境部署实战指南，包含完整的部署流程、配置示例、常见问题处理和性能优化建议。 +- [安全加固](http://docs.flask.elevue.djangoadmin.cn/zh/volume6/security-hardening.html): - 最小权限：只开放必要的端口和权限 - 纵深防御：多层安全措施叠加 - 默认安全：配置默认值应为安全选项 +- [Supervisor进程管理](http://docs.flask.elevue.djangoadmin.cn/zh/volume6/supervisor.html): - Linux 服务器直接部署（非 Docker） - 需要进程自动重启和日志轮转 - 管理多个相关进程 +- [故障排查手册](http://docs.flask.elevue.djangoadmin.cn/zh/volume6/troubleshooting.html): 1. 查看日志：tail -f logs/supervisor.out.log 或 docker-compose logs -f 2. 检查配置：.env 文件、数据库连接、Redis 连接 3. +- [版本升级流程](http://docs.flask.elevue.djangoadmin.cn/zh/volume6/upgrade.html): 1. 先备份，后升级 2. 先测试环境，后生产环境 3. 每次升级可回滚 4. 低峰期执行升级 + +## 8. 规范标准 + +- [API响应规范](http://docs.flask.elevue.djangoadmin.cn/zh/volume7/api-response.html): - 所有接口必须通过 R.ok() 或 R.failed() 返回，禁止直接返回 dict - 成功响应 code=0，失败响应 code=1 - 响应体始终包含 code、data、msg、ok +- [代码审查清单](http://docs.flask.elevue.djangoadmin.cn/zh/volume7/code-review.html): - 每次提交必须经过至少一人审查 - 审查关注点：正确性 > 安全性 > 可维护性 > 性能 - 审查意见应具体、可操作，避免主观评价 +- [删除规范](http://docs.flask.elevue.djangoadmin.cn/zh/volume7/deletion.html): - is_delete = 0：正常记录（默认值） - is_delete = 1：已删除记录 - 所有查询方法自动过滤 is_delete = 0，业务层无需关心 +- [文档规范](http://docs.flask.elevue.djangoadmin.cn/zh/volume7/doc-standard.html): - 文档与代码同步更新 - 使用中文编写（项目约定） - 示例代码可直接运行 +- [Router层规范](http://docs.flask.elevue.djangoadmin.cn/zh/volume7/endpoint.html): - Router 只做请求分发，不含业务逻辑 - 通过装饰器控制权限 - 委托 Service 处理业务逻辑 - 返回 R 封装的响应 +- [前端 API 规范](http://docs.flask.elevue.djangoadmin.cn/zh/volume7/fe-api.html): - 每个后端模块对应一个 API 文件 - 函数命名统一使用 名词 + 动词 格式（与后端保持一致） - 请求路径使用相对路径（/position/page），不含 /api/v1 前缀（由 +- [前端页面规范](http://docs.flask.elevue.djangoadmin.cn/zh/volume7/fe-component.html): - Vue3（Composition API + <script setup>） - ElementPlus - 自定义组件（BasicTable / BasicForm / TableAction +- [Git提交规范](http://docs.flask.elevue.djangoadmin.cn/zh/volume7/git.html): `` <type>(<scope>): <subject> <body> <footer> `` +- [分页规范](http://docs.flask.elevue.djangoadmin.cn/zh/volume7/pagination.html): - 前端传递 pageNo（页码，从 1 开始）和 pageSize（每页条数） - 后端返回分页数据字典，包含 items / total / page / pageSize / pages +- [Repository 层规范](http://docs.flask.elevue.djangoadmin.cn/zh/volume7/repository.html): - Repository 只做数据访问原语，不处理 R 封装/序列化/业务逻辑 - 所有方法均为 @classmethod，无需创建实例 - 软删除由基类自动处理，子类无需关心 - +- [Router层规范](http://docs.flask.elevue.djangoadmin.cn/zh/volume7/router.html): - Router 层不含业务逻辑，仅做路由定义、权限校验和参数解析 - 装饰器顺序固定为：路由 → 权限 → 演示模式 → 操作日志 - Service 模块在文件顶部统一导入（from +- [Service 层规范](http://docs.flask.elevue.djangoadmin.cn/zh/volume7/service.html): BaseService 采用模板方法模式：基类定义流程骨架，子类通过声明差异点和覆盖钩子定制行为。 +- [测试规范](http://docs.flask.elevue.djangoadmin.cn/zh/volume7/testing.html): 1. 契约测试（Contract）：验证路由、权限、表名等契约不变 2. 单元测试（Unit）：验证单个函数/方法的逻辑正确性 3. 集成测试（Integration）：验证模块间协作、真实数据库操作 +- [WTForms Schema 规范](http://docs.flask.elevue.djangoadmin.cn/zh/volume7/wtforms.html): - 创建/编辑共用一个表单类，继承 BaseForm - 特殊操作单独建类（如状态更新、排序调整） - message 必填，用于返回给前端的错误信息 - 唯一性校验通过自定义 validate_ + +## 附录 + +- [常见问题汇总](http://docs.flask.elevue.djangoadmin.cn/zh/faq.html): 本页汇总了项目各模块的常见问题及解决方案，按场景分类索引。 +- [免责声明](http://docs.flask.elevue.djangoadmin.cn/zh/other/declare.html): 使用本产品前必读的法律声明，明确产品性质、使用限制与责任划分，一旦使用本产品即视为接受本声明全部条款。 +- [广告赞助](http://docs.flask.elevue.djangoadmin.cn/zh/other/sponsor.html): 1. 投放广告不得与官方全系产品存在结构性冲突和竞争 2. 广告内容需符合国家法律法规，不得包含虚假、误导性信息 3. 广告素材需经官方审核通过后方可上线，审核周期 1-3 个工作日 4. diff --git a/DjangoAdmin_Flask_EleVue/public/robots.txt b/DjangoAdmin_Flask_EleVue/public/robots.txt new file mode 100644 index 0000000..67e73b1 --- /dev/null +++ b/DjangoAdmin_Flask_EleVue/public/robots.txt @@ -0,0 +1,33 @@ +# DjangoAdmin Flask+ElementPlus 开发文档 +User-agent: * +Allow: / + +# 显式放行生成式引擎 / AI 爬虫（GEO） +User-agent: GPTBot +Allow: / + +User-agent: ChatGPT-User +Allow: / + +User-agent: ClaudeBot +Allow: / + +User-agent: Claude-Web +Allow: / + +User-agent: anthropic-ai +Allow: / + +User-agent: PerplexityBot +Allow: / + +User-agent: Google-Extended +Allow: / + +User-agent: Bytespider +Allow: / + +User-agent: bingbot +Allow: / + +Sitemap: http://docs.flask.elevue.djangoadmin.cn/sitemap.xml diff --git a/DjangoAdmin_Flask_EleVue/scripts/generate-llms-txt.mjs b/DjangoAdmin_Flask_EleVue/scripts/generate-llms-txt.mjs new file mode 100644 index 0000000..6c3e175 --- /dev/null +++ b/DjangoAdmin_Flask_EleVue/scripts/generate-llms-txt.mjs @@ -0,0 +1,122 @@ +#!/usr/bin/env node +/** + * 生成 public/llms.txt（llmstxt.org 标准）——AI 爬虫的站点摘要索引。 + * + * 数据源：zh 目录下全部 Markdown 的 H1 + :::tip 概述首句（与 meta + * description 同源，复用 .vitepress/config/extract.mjs）。按侧边栏章节分组。 + * + * 用法：node scripts/generate-llms-txt.mjs + * 已挂入 package.json 的 docs:build 前置步骤。 + */ +import fs from "node:fs"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; +import { + SITE_URL, + SITE_DESCRIPTION, + extractDescription, +} from "../.vitepress/config/extract.mjs"; + +const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."); +const ZH = path.join(ROOT, "zh"); + +/** 顶层目录 → 侧边栏章节名（与 .vitepress/config/zh.ts 保持一致） */ +const SECTIONS = [ + ["", "1. 了解项目"], + ["volume1", "2. 快速入门"], + ["volume2", "3. 模块开发实战"], + ["volume3", "4. 架构设计"], + ["volume4", "5. 开发指南"], + ["volume5", "6. 代码生成器"], + ["volume6", "7. 运维部署"], + ["volume7", "8. 规范标准"], + ["other", "附录"], +]; + +function walk(dir, out = []) { + for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { + const p = path.join(dir, entry.name); + if (entry.isDirectory()) walk(p, out); + else if (entry.name.endsWith(".md")) out.push(p); + } + return out; +} + +/** 提取首个 H1 文本 */ +function h1Of(md) { + // 围栏感知：跳过 ``` 代码块内的 # 注释，取真正的页面 H1 + let inFence = false; + for (const line of md.split("\n")) { + if (line.startsWith("```")) { inFence = !inFence; continue; } + if (!inFence && line.startsWith("# ") && !line.startsWith("## ")) { + return line.slice(2).trim(); + } + } + return ""; +} + +/** H1 编号排序键："5.10 x" → [5,10]；无编号排最后 */ +function sortKey(h1) { + const m = h1.match(/^(\d+(?:\.\d+)*)/); + if (m) return m[1].split(".").map(Number); + const letter = h1.match(/^([A-Z])\./); + if (letter) return [1000 + letter[1].charCodeAt(0)]; + return [9999]; +} + +function cmpKey(a, b) { + const len = Math.max(a.length, b.length); + for (let i = 0; i < len; i++) { + const x = a[i] ?? 0; + const y = b[i] ?? 0; + if (x !== y) return x - y; + } + return 0; +} + +const files = walk(ZH); +const groups = new Map(SECTIONS.map(([dir, label]) => [label, []])); + +for (const file of files) { + const rel = path.relative(ZH, file).replace(/\\/g, "/"); + const topDir = rel.includes("/") ? rel.split("/")[0] : ""; + const base = rel.split("/").pop(); + const label = (topDir === "" && base === "faq.md") ? "附录" + : SECTIONS.find(([dir]) => dir === topDir)?.[1] ?? "附录"; + + const md = fs.readFileSync(file, "utf8"); + const h1 = h1Of(md); + if (!h1) continue; + const desc = extractDescription(md); + const url = `${SITE_URL}/zh/${rel.replace(/\.md$/, ".html")}`; + groups.get(label).push({ h1, desc, url, key: sortKey(h1) }); +} + +const lines = [ + "# DjangoAdmin Flask+ElementPlus 开发文档", + "", + `> ${SITE_DESCRIPTION}。内置 RBAC 权限体系、代码生成器等开箱即用功能，支持五种数据库一键切换。本文档共 ${files.length} 篇，按章节组织。`, + "", +]; + +// 按章节顺序输出，合并重复 label（appendix/other 同为「附录」，只输出一次） +const printed = new Set(); +for (const [, label] of SECTIONS) { + if (printed.has(label)) continue; + const items = groups.get(label); + if (!items?.length) continue; + printed.add(label); + + lines.push(`## ${label}`, ""); + items.sort((a, b) => cmpKey(a.key, b.key)); + for (const { h1, desc, url } of items) { + lines.push(desc ? `- [${h1}](${url}): ${desc}` : `- [${h1}](${url})`); + } + lines.push(""); +} + +const out = path.join(ROOT, "public", "llms.txt"); +fs.writeFileSync(out, lines.join("\n"), "utf8"); +console.log( + `llms.txt: ${files.length} 页 → ${path.relative(ROOT, out)} (${printed.size} 个章节)`, +); diff --git a/DjangoAdmin_Flask_EleVue/zh/course.md b/DjangoAdmin_Flask_EleVue/zh/course.md index 4238824..c959698 100644 --- a/DjangoAdmin_Flask_EleVue/zh/course.md +++ b/DjangoAdmin_Flask_EleVue/zh/course.md @@ -1,3 +1,5 @@ +# 新手入门指南 + :::warning 特别提醒 官方精心制作本教程，目的在于方便用户快速掌握软件产品的使用和部署。通过此教程，刚入行的开发者也可以快速掌握并投入产品研发。本地部署时务必请耐心阅读文档操作。 ::: diff --git a/DjangoAdmin_Flask_EleVue/zh/introduction.md b/DjangoAdmin_Flask_EleVue/zh/introduction.md index 7d241ce..3027a7c 100644 --- a/DjangoAdmin_Flask_EleVue/zh/introduction.md +++ b/DjangoAdmin_Flask_EleVue/zh/introduction.md @@ -1,3 +1,9 @@ +# 项目介绍 + +:::tip 概述 +DjangoAdmin 是企业级中台解决方案，后端基于 Flask + SQLAlchemy，前端基于 Vue3 + ElementPlus，内置 RBAC 权限、代码生成器等开箱即用功能，支持五种数据库一键切换。 +::: + <div align="center"> <p align="center"> <img src="/logo.png" height="150" alt="logo"/> diff --git a/DjangoAdmin_Flask_EleVue/zh/other/declare.md b/DjangoAdmin_Flask_EleVue/zh/other/declare.md index 7737479..915692a 100644 --- a/DjangoAdmin_Flask_EleVue/zh/other/declare.md +++ b/DjangoAdmin_Flask_EleVue/zh/other/declare.md @@ -1,5 +1,9 @@ # 免责声明 +:::tip 概述 +使用本产品前必读的法律声明，明确产品性质、使用限制与责任划分，一旦使用本产品即视为接受本声明全部条款。 +::: + :::danger 重要提示 任何用户在使用本团队研发的系列软件产品（以下简称「本产品」）前，请仔细阅读并透彻理解本声明。选择不使用本产品，可随时停止使用；一旦使用本产品，即视为对本声明全部内容的认可和接受。 ::: diff --git a/DjangoAdmin_Flask_EleVue/zh/struct.md b/DjangoAdmin_Flask_EleVue/zh/struct.md index 6f286fd..2575ce9 100644 --- a/DjangoAdmin_Flask_EleVue/zh/struct.md +++ b/DjangoAdmin_Flask_EleVue/zh/struct.md @@ -1,3 +1,5 @@ +# 项目目录结构 + ## 目录说明 在软件开发过程中，优秀的软件目录结构对于项目的组织、开发、维护和扩展至关重要，合理的目录结构能够显著提升开发效率和代码可维护性。 diff --git a/DjangoAdmin_Flask_EleVue/zh/volume2/blueprint.md b/DjangoAdmin_Flask_EleVue/zh/volume2/blueprint.md index 3db027b..6bff9d1 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume2/blueprint.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume2/blueprint.md @@ -1,5 +1,9 @@ # 路由注册（Flask Blueprint） +:::tip 概述 +路由注册基于 Flask Blueprint 机制实现模块化挂载，本页讲解 Blueprint 的定义与在路由中心统一注册的方法。 +::: + Flask 使用 `Blueprint` 机制实现模块化路由注册。每个业务模块定义自己的 Blueprint，然后在路由注册中心统一挂载到应用。 ## Blueprint 概念 diff --git a/DjangoAdmin_Flask_EleVue/zh/volume2/code-list.md b/DjangoAdmin_Flask_EleVue/zh/volume2/code-list.md index be7ac1d..524c70b 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume2/code-list.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume2/code-list.md @@ -1,5 +1,9 @@ # 完整代码清单 +:::tip 概述 +本页汇总岗位管理（Position）模块涉及的全部文件代码，开发时可快速查阅与复制对照。 +::: + 本章汇总 Position 岗位模块涉及的全部文件，便于开发时快速查阅和复制。 ## 后端文件清单 diff --git a/DjangoAdmin_Flask_EleVue/zh/volume2/endpoint.md b/DjangoAdmin_Flask_EleVue/zh/volume2/endpoint.md index 45b755b..03837f6 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume2/endpoint.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume2/endpoint.md @@ -1,5 +1,9 @@ # Router 层（Flask Blueprint） +:::tip 概述 +Router 层是 HTTP 接口层，负责定义路由、权限装饰器与请求参数解析，编写新接口从本页开始。 +::: + Router 层是 HTTP 接口层，负责定义路由、权限装饰器和请求参数解析。每个业务模块对应一个 router 文件，所有业务逻辑委托给 Service 层处理。 ## 文件位置 diff --git a/DjangoAdmin_Flask_EleVue/zh/volume2/faq.md b/DjangoAdmin_Flask_EleVue/zh/volume2/faq.md index f43ef34..b18a4fb 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume2/faq.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume2/faq.md @@ -1,5 +1,9 @@ # 常见问题与排错 +:::tip 概述 +本页汇总模块开发过程中的常见问题与排错方法，开发受阻时按症状索引即可定位。 +::: + 本章汇总模块开发过程中的常见问题和解决方案。 ## 后端问题 diff --git a/DjangoAdmin_Flask_EleVue/zh/volume2/fe-api.md b/DjangoAdmin_Flask_EleVue/zh/volume2/fe-api.md index 797cc1c..ae9203a 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume2/fe-api.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume2/fe-api.md @@ -1,5 +1,9 @@ # 前端 API 层 +:::tip 概述 +前端 API 层封装后端接口的 HTTP 请求，每个业务模块对应一个 API 文件，本页讲解基于 Axios 封装的编写规范。 +::: + 前端 API 层负责封装后端接口的 HTTP 请求。每个业务模块对应一个 API 文件，使用项目封装的 Axios 工具发送请求。 ## 文件位置 diff --git a/DjangoAdmin_Flask_EleVue/zh/volume2/fe-router.md b/DjangoAdmin_Flask_EleVue/zh/volume2/fe-router.md index 0f79bbe..5c2330b 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume2/fe-router.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume2/fe-router.md @@ -1,5 +1,9 @@ # 前端路由与菜单 +:::tip 概述 +本页讲解前端路由与菜单机制——路由和菜单由后端动态返回，前端只需注册路由组件映射。 +::: + 前端路由定义页面的访问路径，菜单是路由的可视化展示。项目的路由和菜单由后端动态返回，前端只需注册路由组件映射。 ## 路由配置 diff --git a/DjangoAdmin_Flask_EleVue/zh/volume2/fe-view.md b/DjangoAdmin_Flask_EleVue/zh/volume2/fe-view.md index 3639881..fd245a4 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume2/fe-view.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume2/fe-view.md @@ -1,5 +1,9 @@ # 前端页面视图 +:::tip 概述 +前端页面视图是用户直接交互的界面，本页讲解 Vue3 + ElementPlus 下一个完整 CRUD 页面的文件组成与编写方式。 +::: + 前端页面视图是用户直接交互的界面。项目使用 Vue3 + ElementPlus + Vite 构建。一个完整的 CRUD 页面由 4 个文件组成： ``` diff --git a/DjangoAdmin_Flask_EleVue/zh/volume2/model.md b/DjangoAdmin_Flask_EleVue/zh/volume2/model.md index 7ebcb10..229652c 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume2/model.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume2/model.md @@ -1,5 +1,9 @@ # 数据模型（Model） +:::tip 概述 +数据模型是模块开发的第一步，讲解如何用 SQLAlchemy ORM 与基类定义数据库表结构，新建模块时从本页开始。 +::: + 数据模型是模块开发的第一步，用于定义数据库表结构。项目使用 `SQLAlchemy ORM`，模型类通过继承基类自动获得通用字段和方法。 ## 文件位置 diff --git a/DjangoAdmin_Flask_EleVue/zh/volume2/repository.md b/DjangoAdmin_Flask_EleVue/zh/volume2/repository.md index 17f722a..660a1cd 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume2/repository.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume2/repository.md @@ -1,5 +1,9 @@ # Repository 层 +:::tip 概述 +Repository 层是数据访问层，封装全部数据库查询操作，本页讲解基于 BaseRepository 基类的通用 CRUD 用法。 +::: + Repository 层是数据访问层，封装所有数据库查询操作。项目通过 `BaseRepository` 基类提供通用 CRUD 能力，子类只需声明 `model` 并按需实现 `page()` 和 `list_enabled()` 方法。 ## 文件位置 diff --git a/DjangoAdmin_Flask_EleVue/zh/volume2/router.md b/DjangoAdmin_Flask_EleVue/zh/volume2/router.md index 7c04da7..8e52cef 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume2/router.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume2/router.md @@ -1,5 +1,9 @@ # 路由注册 +:::tip 概述 +路由注册是将模块 Blueprint 挂载到应用的过程，本页讲解在路由注册中心统一挂载的方法。 +::: + 路由注册是将模块的 Blueprint 挂载到应用的过程。所有模块的路由在 `src/routes/v1.py` 中统一注册。 ## 文件位置 diff --git a/DjangoAdmin_Flask_EleVue/zh/volume2/schema.md b/DjangoAdmin_Flask_EleVue/zh/volume2/schema.md index 8f111d1..c0494dc 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume2/schema.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume2/schema.md @@ -1,5 +1,9 @@ # WTForms Schema +:::tip 概述 +Schema 层负责请求数据校验，本页讲解基于 WTForms 表单类与 validators 的校验规范。 +::: + Schema 层负责请求数据的校验。项目使用 `WTForms` 定义表单类，通过 `validators` 约束字段格式，框架在接收请求体时自动执行校验。 ## 文件位置 diff --git a/DjangoAdmin_Flask_EleVue/zh/volume2/service.md b/DjangoAdmin_Flask_EleVue/zh/volume2/service.md index 84889f1..35cdece 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume2/service.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume2/service.md @@ -1,5 +1,9 @@ # Service 层 +:::tip 概述 +Service 层是业务逻辑层，本页讲解基于 BaseService 基类声明差异点即可获得完整增删改查能力的编写方式。 +::: + Service 层是业务逻辑层，负责实现具体的业务规则。简单 CRUD 模块继承 `BaseService` 基类，只需声明差异点即可获得完整的增删改查能力。 ## 文件位置 diff --git a/DjangoAdmin_Flask_EleVue/zh/volume4/business/article.md b/DjangoAdmin_Flask_EleVue/zh/volume4/business/article.md index 399a9ca..7e8c3fa 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume4/business/article.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume4/business/article.md @@ -1,3 +1,5 @@ +# 文章管理 + :::tip 文章管理 文章管理模块支持富文本编辑、分类关联、封面图片上传、图集管理等功能。适用于新闻、公告、帮助文档等内容管理场景。本模块是典型的「带文件处理」业务模块，涵盖了封面迁移、图集处理、富文本 XSS 清洗等核心机制。 ::: diff --git a/DjangoAdmin_Flask_EleVue/zh/volume4/business/category.md b/DjangoAdmin_Flask_EleVue/zh/volume4/business/category.md index 14347de..9b7e8b5 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume4/business/category.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume4/business/category.md @@ -1,3 +1,5 @@ +# 分类管理 + :::tip 分类管理 分类管理模块用于管理树形分类数据，如文章分类、产品分类等。通过 `parent_id` 字段实现无限级分类。 ::: diff --git a/DjangoAdmin_Flask_EleVue/zh/volume4/business/city.md b/DjangoAdmin_Flask_EleVue/zh/volume4/business/city.md index 0fc2e12..3e9863a 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume4/business/city.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume4/business/city.md @@ -1,3 +1,5 @@ +# 行政区划管理 + :::tip 行政区划 行政区划模块管理全国省/市/区/街道四级区域数据，支持树形结构查询、级联选择器、拼音自动生成等功能。用户表通过 `province_code`/`city_code`/`district_code`/`street_code` 四个字段关联城市表的 `area_code`。 ::: diff --git a/DjangoAdmin_Flask_EleVue/zh/volume4/business/content.md b/DjangoAdmin_Flask_EleVue/zh/volume4/business/content.md index e281099..eff119e 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume4/business/content.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume4/business/content.md @@ -1,3 +1,5 @@ +# 公告与链接管理 + :::tip 公告/链接/城市 公告、链接、城市是三个简单 CRUD 内容模块，均继承 BaseService，提供标准的增删改查接口。适用于系统公告、友情链接、城市数据等场景。 ::: diff --git a/DjangoAdmin_Flask_EleVue/zh/volume4/business/dept.md b/DjangoAdmin_Flask_EleVue/zh/volume4/business/dept.md index 66d260f..2556b24 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume4/business/dept.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume4/business/dept.md @@ -1,3 +1,5 @@ +# 部门/职级/岗位管理 + :::tip 部门/职级/岗位 部门、职级、岗位是组织架构管理的三个核心模块。部门采用树形结构，职级和岗位为简单 CRUD 模块，均继承 `BaseService`。用户表通过 `dept_id`、`position_id`、`level_id` 三个外键关联这三个模块。 ::: diff --git a/DjangoAdmin_Flask_EleVue/zh/volume4/business/example.md b/DjangoAdmin_Flask_EleVue/zh/volume4/business/example.md index d3110ba..fa2edd6 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume4/business/example.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume4/business/example.md @@ -1,3 +1,5 @@ +# 案例演示 + :::tip 案例演示 案例演示模块是代码生成器的参考模板，展示了标准 CRUD 模块的完整实现。包含文件字段处理、枚举字典映射、状态管理等功能，可作为新模块开发的参考范例。 ::: diff --git a/DjangoAdmin_Flask_EleVue/zh/volume4/business/file-template.md b/DjangoAdmin_Flask_EleVue/zh/volume4/business/file-template.md index d7e1527..1d8ee75 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume4/business/file-template.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume4/business/file-template.md @@ -1,3 +1,5 @@ +# 文件模板管理 + :::tip 文件模板 文件模板模块用于管理系统中的文件模板，如导入导出模板、报表模板等。支持模板文件上传、按编码查询、文件 URL 自动转换等功能。 ::: diff --git a/DjangoAdmin_Flask_EleVue/zh/volume4/business/job.md b/DjangoAdmin_Flask_EleVue/zh/volume4/business/job.md index 6e7c4b4..94304f9 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume4/business/job.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume4/business/job.md @@ -1,3 +1,5 @@ +# 定时任务 + :::tip 定时任务 定时任务模块基于 APScheduler 实现，支持 Cron 表达式调度、任务执行日志、动态启停等功能。包含 job（任务定义）、job_log（执行日志）、scheduler（调度器）三个子模块。 ::: diff --git a/DjangoAdmin_Flask_EleVue/zh/volume4/business/menu.md b/DjangoAdmin_Flask_EleVue/zh/volume4/business/menu.md index ef9332a..b88f910 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume4/business/menu.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume4/business/menu.md @@ -1,3 +1,5 @@ +# 菜单管理 + :::tip 菜单管理 菜单管理是 RBAC 权限系统的基础，负责管理系统的导航菜单和权限节点。支持目录/菜单（type=0）和权限按钮节点（type=1）两种类型，通过树形结构组织。权限节点由系统根据前端勾选自动生成，采用 `sys:module:action` 三段式命名。 ::: diff --git a/DjangoAdmin_Flask_EleVue/zh/volume4/business/param.md b/DjangoAdmin_Flask_EleVue/zh/volume4/business/param.md index 09e6a68..e107a1b 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume4/business/param.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume4/business/param.md @@ -1,3 +1,5 @@ +# 参数管理 + :::tip 参数管理 参数管理模块用于管理系统配置和业务配置，每个参数包含名称、编码、值、类型、排序、状态等属性。本模块是典型的「BaseService 简单模块」，通过声明差异点即可获得完整 CRUD 能力。 ::: diff --git a/DjangoAdmin_Flask_EleVue/zh/volume4/business/role.md b/DjangoAdmin_Flask_EleVue/zh/volume4/business/role.md index 77ac59e..a39a74d 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume4/business/role.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume4/business/role.md @@ -1,3 +1,5 @@ +# 角色管理 + :::tip 角色管理 角色是 RBAC 权限模型的核心，连接用户和菜单（权限）。通过为角色分配菜单权限，再将角色分配给用户，实现灵活的权限管理。角色删除时需清理关联的用户角色和角色菜单数据，并即时失效受影响用户的权限缓存。 ::: diff --git a/DjangoAdmin_Flask_EleVue/zh/volume4/business/user.md b/DjangoAdmin_Flask_EleVue/zh/volume4/business/user.md index f9891d6..7f15a85 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume4/business/user.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume4/business/user.md @@ -1,3 +1,5 @@ +# 用户管理 + :::tip 用户管理 用户管理是系统的核心模块，属于复杂业务模块。包含用户 CRUD、角色关联、密码加密、行政区划、Excel 导入导出等功能。用户管理继承 `BaseService` 获得标准 CRUD 能力，并通过覆写钩子方法实现头像保存、密码加密、角色关联等定制逻辑。 ::: diff --git a/DjangoAdmin_Flask_EleVue/zh/volume4/core/captcha.md b/DjangoAdmin_Flask_EleVue/zh/volume4/core/captcha.md index d7308b3..dcec275 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume4/core/captcha.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume4/core/captcha.md @@ -1,3 +1,5 @@ +# 验证码机制 + :::tip 验证码 验证码是防止自动化攻击的重要安全手段。项目使用 Pillow 生成图片验证码，存储在 Redis 中，支持防刷限流和万能验证码（演示模式）。源码位于 `src/common/utils/captcha.py`。 ::: diff --git a/DjangoAdmin_Flask_EleVue/zh/volume4/core/config.md b/DjangoAdmin_Flask_EleVue/zh/volume4/core/config.md index efe17b9..ae4dfc9 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume4/core/config.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume4/core/config.md @@ -1,3 +1,5 @@ +# 系统配置管理 + :::tip 系统配置 系统配置模块用于管理动态的键值对配置项，与数据字典类似但更偏向系统级参数。支持分组管理，可通过接口动态修改，无需重启服务。模块位于 `src/modules/configuration/`，路由位于 `src/modules/configuration/config/router.py` 和 `config_item/router.py`。 ::: diff --git a/DjangoAdmin_Flask_EleVue/zh/volume4/core/demo-mode.md b/DjangoAdmin_Flask_EleVue/zh/volume4/core/demo-mode.md index 769e2ea..a94e381 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume4/core/demo-mode.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume4/core/demo-mode.md @@ -1,3 +1,5 @@ +# 演示模式 + :::tip 演示模式 演示模式用于在线体验环境，开启后所有写操作（新增、编辑、删除等）将被拦截，返回"演示环境，暂无操作权限"提示。通过 `FLASK_DEMO` 环境变量控制。装饰器位于 `src/middleware/demo.py`。 ::: diff --git a/DjangoAdmin_Flask_EleVue/zh/volume4/core/dict.md b/DjangoAdmin_Flask_EleVue/zh/volume4/core/dict.md index 2a28f79..409b623 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume4/core/dict.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume4/core/dict.md @@ -1,3 +1,5 @@ +# 字典模块 + :::tip 数据字典 数据字典用于管理系统中的枚举值和配置项，如状态、类型、性别等。通过字典编码统一管理，前端可通过 `useDictStore` 获取字典选项，避免硬编码。后端读取工具位于 `src/common/utils/dict_util.py`，内置进程内 TTL 缓存。 ::: diff --git a/DjangoAdmin_Flask_EleVue/zh/volume4/core/exception.md b/DjangoAdmin_Flask_EleVue/zh/volume4/core/exception.md index 9d9bd15..db05970 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume4/core/exception.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume4/core/exception.md @@ -1,3 +1,5 @@ +# 异常与响应处理 + :::tip 全局异常与响应 项目定义了统一的响应格式和全局异常处理机制。所有 API 返回 `{code, data, msg, ok}` 标准格式，异常被捕获后也转换为相同格式。响应函数位于 `src/core/response.py`，异常类型位于 `src/core/exceptions.py`。 ::: diff --git a/DjangoAdmin_Flask_EleVue/zh/volume4/core/idempotent.md b/DjangoAdmin_Flask_EleVue/zh/volume4/core/idempotent.md index 23c2af4..1c6ed8c 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume4/core/idempotent.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume4/core/idempotent.md @@ -1,3 +1,5 @@ +# 防重复提交 + :::tip 防重复提交 防重复提交是保障数据一致性的重要措施。通过前端防抖和后端唯一性校验双重保护，防止用户重复点击导致的数据重复提交。后端唯一性校验通过 WTForms 自定义校验器查询数据库实现。 ::: diff --git a/DjangoAdmin_Flask_EleVue/zh/volume4/core/jwt.md b/DjangoAdmin_Flask_EleVue/zh/volume4/core/jwt.md index ea3a013..6492210 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume4/core/jwt.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume4/core/jwt.md @@ -1,3 +1,5 @@ +# 用户认证（JWT） + :::tip JWT认证 JWT（JSON Web Token）是项目的核心认证机制。用户登录成功后获取 Token，后续请求通过 `Authorization: Bearer <token>` 头携带 Token 进行身份验证。项目内置了 Token 生成、解析、刷新和黑名单管理功能，源码位于 `src/core/jwt.py`。 ::: diff --git a/DjangoAdmin_Flask_EleVue/zh/volume4/core/login-log.md b/DjangoAdmin_Flask_EleVue/zh/volume4/core/login-log.md index f4edbfa..cb96142 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume4/core/login-log.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume4/core/login-log.md @@ -1,3 +1,5 @@ +# 登录日志 + :::tip 登录日志 登录日志记录每次登录尝试（成功/失败），包含登录账号、IP地址、浏览器信息、登录时间等。支持 IP 地理位置解析（ip2region）和 User-Agent 解析。登录逻辑位于 `src/modules/auth/service.py`，日志记录位于 `src/modules/login_log/service.py`。 ::: diff --git a/DjangoAdmin_Flask_EleVue/zh/volume4/core/operation-log.md b/DjangoAdmin_Flask_EleVue/zh/volume4/core/operation-log.md index d9d212f..bc0c873 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume4/core/operation-log.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume4/core/operation-log.md @@ -1,3 +1,5 @@ +# 操作日志 + :::tip 操作日志 操作日志中间件自动拦截写请求（POST/PUT/DELETE/PATCH）并记录操作日志，无需手动埋点。日志落库通过后台线程异步执行，不阻塞响应。源码位于 `src/middleware/operation_log.py`。 ::: diff --git a/DjangoAdmin_Flask_EleVue/zh/volume4/core/rbac.md b/DjangoAdmin_Flask_EleVue/zh/volume4/core/rbac.md index a65f751..6d0f797 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume4/core/rbac.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume4/core/rbac.md @@ -1,3 +1,5 @@ +# 权限管理（RBAC） + :::tip RBAC权限 项目采用基于角色的访问控制（RBAC）模型，通过用户-角色-菜单三层关系实现细粒度的权限管理。权限控制贯穿前后端：后端通过 `@check_permission` 装饰器校验（`src/core/permission.py`），前端通过 `v-perm` 指令控制按钮显隐。 ::: diff --git a/DjangoAdmin_Flask_EleVue/zh/volume4/core/transaction-decorator.md b/DjangoAdmin_Flask_EleVue/zh/volume4/core/transaction-decorator.md index ef985d9..bce442e 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume4/core/transaction-decorator.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume4/core/transaction-decorator.md @@ -1,5 +1,9 @@ # 事务装饰器 +:::tip 概述 +本页讲解事务装饰器的用法，适用于中间件自动事务之外的特殊场景事务控制。 +::: + 除了 AOP 中间件自动管理事务外，项目还提供了事务装饰器，用于特殊场景下的事务控制。 ## @transactional 装饰器 diff --git a/DjangoAdmin_Flask_EleVue/zh/volume4/core/transaction.md b/DjangoAdmin_Flask_EleVue/zh/volume4/core/transaction.md index 1706af7..a923205 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume4/core/transaction.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume4/core/transaction.md @@ -1,5 +1,9 @@ # AOP 事务管理 +:::tip 概述 +本页讲解 AOP 风格的事务管理机制——中间件自动管理数据库事务，业务代码无需手动 commit 或 rollback。 +::: + 项目采用 AOP（面向切面编程）风格的事务管理机制，通过中间件自动管理数据库事务，业务代码无需手动调用 `commit` 或 `rollback`。 ## 设计理念 diff --git a/DjangoAdmin_Flask_EleVue/zh/volume4/core/validator.md b/DjangoAdmin_Flask_EleVue/zh/volume4/core/validator.md index f647de6..66f0d8f 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume4/core/validator.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume4/core/validator.md @@ -1,3 +1,5 @@ +# 参数验证（Schema） + :::tip 参数验证 项目使用 WTForms 进行请求参数验证。所有请求体参数通过 WTForms 表单类定义，框架自动解析和验证 JSON 请求体，验证失败返回标准格式错误信息。BaseForm 基类位于 `src/common/forms/base_form.py`。 ::: diff --git a/DjangoAdmin_Flask_EleVue/zh/volume4/tools/generator.md b/DjangoAdmin_Flask_EleVue/zh/volume4/tools/generator.md index cde5df6..60b6716 100644 --- a/DjangoAdmin_Flask_EleVue/zh/volume4/tools/generator.md +++ b/DjangoAdmin_Flask_EleVue/zh/volume4/tools/generator.md @@ -1,5 +1,9 @@ # 代码生成器 +:::tip 概述 +本页讲解代码生成器的用法，可根据数据库表结构一键生成前后端 CRUD 全套代码。 +::: + 代码生成器是项目的重要工具，可以根据数据库表结构一键生成前后端 CRUD 代码，包括模型、仓库、服务、路由、表单、前端 API、前端页面等全套代码。 ## 功能概述 diff --git a/DjangoAdmin_Flask_EleVue/zh/why.md b/DjangoAdmin_Flask_EleVue/zh/why.md index 90c0234..add34dc 100644 --- a/DjangoAdmin_Flask_EleVue/zh/why.md +++ b/DjangoAdmin_Flask_EleVue/zh/why.md @@ -1,7 +1,7 @@ # 为什么选择我们？ :::tip 核心价值 -企业级数据中台不应从零搭建。本框架提供开箱即用的完整解决方案，为中大型企业构建统一的数字化基座。 +本框架提供开箱即用的企业级中台完整解决方案，免去从零搭建成本，助力中大型企业构建统一的数字化基座。 ::: ## 解决什么问题？ diff --git a/DjangoAdmin_Flask_NaiveVue/.vitepress/config/en.ts b/DjangoAdmin_Flask_NaiveVue/.vitepress/config/en.ts index a1a96ef..a4aee7d 100644 --- a/DjangoAdmin_Flask_NaiveVue/.vitepress/config/en.ts +++ b/DjangoAdmin_Flask_NaiveVue/.vitepress/config/en.ts @@ -29,7 +29,7 @@ // // themeConfig: { // editLink: { -// pattern: "https://gitee.com/djangoadmin/DjangoAdmin_Fastapi_EleVue", +// pattern: "https://gitee.com/djangoadmin/DjangoAdmin_Flask_NaiveVue", // text: "Suggest changes to this page", // }, // diff --git a/DjangoAdmin_Flask_NaiveVue/.vitepress/config/extract.d.mts b/DjangoAdmin_Flask_NaiveVue/.vitepress/config/extract.d.mts new file mode 100644 index 0000000..2a46233 --- /dev/null +++ b/DjangoAdmin_Flask_NaiveVue/.vitepress/config/extract.d.mts @@ -0,0 +1,5 @@ +export declare const SITE_URL: string; +export declare const SITE_DESCRIPTION: string; +export declare function stripNumberPrefix(title: string): string; +export declare function extractDescription(md: string): string; +export declare function extractFaqs(md: string): { q: string; a: string }[]; diff --git a/DjangoAdmin_Flask_NaiveVue/.vitepress/config/extract.mjs b/DjangoAdmin_Flask_NaiveVue/.vitepress/config/extract.mjs new file mode 100644 index 0000000..f7c8292 --- /dev/null +++ b/DjangoAdmin_Flask_NaiveVue/.vitepress/config/extract.mjs @@ -0,0 +1,130 @@ +/** + * SEO/GEO 共享工具（纯 ESM，零依赖）。 + * + * 同时被两类调用方 import： + * 1. VitePress 配置（.ts，esbuild 打包时内联本文件） + * 2. scripts/generate-llms-txt.mjs（Node 直接运行） + * + * 注意：SITE_URL 是全站唯一 URL 真相源。 + * docs 子域当前 TLS 证书为腾讯 CDN 默认证书（*.cdn.myqcloud.com，校验失败）， + * 故暂用 http；证书修复后只需改这里一处。 + */ + +export const SITE_URL = "http://docs.flask.naivevue.djangoadmin.cn"; + +export const SITE_DESCRIPTION = + "DjangoAdmin Flask+NaiveUI 企业级中台解决方案开发者文档"; + +/** + * 剥离 H1/标题中的章节编号前缀，用于 <title> 与 JSON-LD headline。 + * 例："5.10 字典模块" → "字典模块"；"K. 贡献指南" → "贡献指南"。 + * 页内 H1 与侧边栏编号保持不变，仅影响 SEO 输出。 + */ +export function stripNumberPrefix(title) { + return String(title) + .replace(/^(?:\d+(?:\.\d+)+|[A-Z]\.)\s+/, "") + .trim(); +} + +/** + * 从页面 Markdown 提取 meta description： + * 1. 首选 `:::tip xxx` 容器内的首句（141/143 页的标准 opener） + * 2. 回退到 H1 后的第一个普通段落 + * 输出压缩为单行、去除行内 Markdown，按中文句末标点截断（≤100 字符）。 + */ +export function extractDescription(md) { + const src = String(md); + const fm = src.match(/^---\r?\n([\s\S]*?)\r?\n---/); + const body = fm ? src.slice(fm[0].length) : src; + + let text = ""; + // frontmatter description 显式声明优先（无 H1 页面的补齐手段） + const fmDesc = fm && fm[1].match(/^description:\s*(.+)$/m); + if (fmDesc) { + text = fmDesc[1].trim().replace(/^["']|["']$/g, ""); + } + const tip = !text && body.match(/^:::\s*tip[^\n]*\n([\s\S]*?)\n:::/m); + if (tip) { + text = tip[1]; + } + if (!text) { + const afterH1 = body.match(/^# (?!#)(.+)$/m); + if (afterH1) { + const rest = body.slice((afterH1.index ?? 0) + afterH1[0].length); + const para = rest + .split(/\n{2,}/) + .find( + (p) => + p.trim() && + !/^\s*#/.test(p) && + !/^\s*:::/.test(p) && + !/^\s*```/.test(p) && + !/^\s*\|/.test(p), + ); + text = para || ""; + } + } + + text = text + .replace(/\s+/g, " ") + .replace(/`([^`]+)`/g, "$1") + .replace(/\*\*([^*]+)\*\*/g, "$1") + .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") + .trim(); + + if (!text) return ""; + + // 按中文句末标点截取首句，上限 100 字符；截断时避免切碎词 + const m = text.match(/^.{1,100}?(?:[。！？!?]|$)/); + let out = m ? m[0] : text.slice(0, 100); + if (out.length < text.length && !/[。！？!?]$/.test(out)) { + out = out.replace(/[^\s，、；：,;:]+$/, ""); + } + return out.trim() || text.slice(0, 100); +} + +function cleanText(s) { + return s + .replace(/^:::[^\n]*$/gm, "") + .replace(/^```[^\n]*$/gm, "") + .replace(/`([^`]+)`/g, "$1") + .replace(/\*\*([^*]+)\*\*/g, "$1") + .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") + .replace(/\s+/g, " ") + .trim(); +} + +/** + * 提取页面中的 Q/A 对（用于 FAQPage JSON-LD），支持两种站内格式： + * A. `### Q：问题` 标题式（如 zh/quickstart/faq.md） + * B. `**Q：问题**` 加粗式（如 zh/appendix/faq.md） + * 返回 [{ q, a }]；无匹配返回 []。 + */ +export function extractFaqs(md) { + const body = String(md).replace(/^---[\s\S]*?\n---\s*/, ""); + let faqs = []; + + // 格式 A：按 `### Q：` 切块，答案截断到下一个标题 + for (const part of body.split(/(?=^###\s*Q[：:])/m)) { + const m = part.match(/^###\s*Q[：:]\s*([^\n]+)\n+([\s\S]*)/); + if (!m) continue; + let a = m[2]; + const cut = a.search(/^#{1,4}\s/m); + if (cut >= 0) a = a.slice(0, cut); + faqs.push({ q: cleanText(m[1]), a: cleanText(a) }); + } + + // 格式 B：按 `**Q：` 切块 + if (!faqs.length) { + for (const part of body.split(/(?=^\*\*Q[：:])/m)) { + const m = part.match(/^\*\*Q[：:]\s*([^*]+)\*\*\s*\n+([\s\S]*)/); + if (!m) continue; + let a = m[2]; + const cut = a.search(/^(?:#{1,4}\s|\*\*Q)/m); + if (cut >= 0) a = a.slice(0, cut); + faqs.push({ q: cleanText(m[1]), a: cleanText(a) }); + } + } + + return faqs.filter((f) => f.q && f.a); +} diff --git a/DjangoAdmin_Flask_NaiveVue/.vitepress/config/index.ts b/DjangoAdmin_Flask_NaiveVue/.vitepress/config/index.ts index 2294856..6627a76 100644 --- a/DjangoAdmin_Flask_NaiveVue/.vitepress/config/index.ts +++ b/DjangoAdmin_Flask_NaiveVue/.vitepress/config/index.ts @@ -1,14 +1,22 @@ import { defineConfig } from "vitepress"; import { enConfig } from "./en"; +import { createSeoHooks } from "./seo"; import { sharedConfig } from "./shared"; import { zhConfig } from "./zh"; +const seo = createSeoHooks(zhConfig.themeConfig?.sidebar); + export default defineConfig({ ...sharedConfig, ignoreDeadLinks: [ (link) => link.includes('localhost'), ], + // SEO：页面级 title/description、canonical/OG/JSON-LD、sitemap+lastmod + transformPageData: seo.transformPageData, + transformHead: seo.transformHead, + sitemap: seo.sitemap, + locales: { root: { label: "简体中文", lang: "zh-CN", link: "/", ...zhConfig }, // root: { label: "English", lang: "en-US", link: "/", ...enConfig }, diff --git a/DjangoAdmin_Flask_NaiveVue/.vitepress/config/seo.ts b/DjangoAdmin_Flask_NaiveVue/.vitepress/config/seo.ts new file mode 100644 index 0000000..4224078 --- /dev/null +++ b/DjangoAdmin_Flask_NaiveVue/.vitepress/config/seo.ts @@ -0,0 +1,311 @@ +/** + * SEO/GEO 构建期钩子（仅 Node 构建时运行，不进客户端 bundle）： + * - transformPageData：每页独立 title（去编号前缀）与 description（取 :::tip 首句） + * - transformHead：canonical / Open Graph / twitter 卡片 / JSON-LD 结构化数据 + * - sitemap.transformItems：注入 lastmod（git 最后提交时间）并过滤 404 + * + * 由 config/index.ts 通过 createSeoHooks(zhConfig.themeConfig?.sidebar) 挂载。 + * 依赖 extract.mjs（纯 ESM，同被 scripts/generate-llms-txt.mjs 复用）。 + */ +import fs from "node:fs"; +import path from "node:path"; +import { execSync } from "node:child_process"; +import { + SITE_URL, + extractDescription, + extractFaqs, + stripNumberPrefix, +} from "./extract.mjs"; + +/** 与 vitepress HeadConfig 同构：[tag, attrs, innerHTML?] */ +type HeadTuple = [string, Record<string, any>, string?]; + +interface SideItem { + text?: string; + link?: string; + items?: SideItem[]; +} + +interface PageDataLike { + relativePath?: string; + title?: string; + description?: string; + frontmatter?: Record<string, any>; + [k: string]: any; +} + +interface TransformCtx { + pageData?: PageDataLike; + title?: string; + description?: string; + content?: string; + siteConfig?: { root?: string; srcDir?: string }; +} + +const ORG = { + "@type": "Organization", + name: "DjangoAdmin", + url: "https://www.djangoadmin.cn", + logo: `${SITE_URL}/logo.png`, + sameAs: [ + "https://gitee.com/djangoadmin/DjangoAdmin_Flask_NaiveVue", + "https://www.djangoadmin.cn", + ], +}; + +/** 相对路径 → 站内路由（cleanUrls 关闭，正文页带 .html） */ +function routeOf(relativePath: string): string { + if (relativePath === "index.md") return "/"; + if (relativePath === "404.md") return "/404.html"; + return `/${relativePath.replace(/\.md$/, ".html")}`; +} + +/** 去掉侧边栏文案前导 emoji/符号，保留 "1.1 项目介绍" 这类编号文字 */ +function cleanLabel(s?: string): string { + return (s || "").replace(/^[^\p{L}\p{N}]+/u, "").trim(); +} + +/** 从侧边栏构建 route → 面包屑文案链（含分组小节） */ +function buildCrumbMap(sidebar: unknown): Map<string, string[]> { + const map = new Map<string, string[]>(); + const groups: SideItem[] = Array.isArray(sidebar) + ? sidebar + : ((sidebar as Record<string, SideItem[]>)?.["/zh/"] ?? []); + const walk = (items: SideItem[], trail: string[]) => { + for (const item of items) { + if (item.link && item.link.startsWith("/")) { + map.set(item.link, [...trail, cleanLabel(item.text)]); + } else if (item.items?.length) { + walk(item.items, [...trail, cleanLabel(item.text)]); + } + } + }; + for (const group of groups) { + walk(group.items ?? [], [cleanLabel(group.text)].filter(Boolean)); + } + return map; +} + +/** 从渲染后的 HTML 提取 H1 纯文本（JSON-LD headline 须与页面 H1 一致） */ +function h1OfHtml(html?: string): string { + const m = (html || "").match(/<h1[^>]*>([\s\S]*?)<\/h1>/i); + if (!m) return ""; + return m[1] + .replace(/<[^>]+>/g, "") + .replace(/&/g, "&") + .replace(/</g, "<") + .replace(/>/g, ">") + .replace(/"/g, '"') + .replace(/'/g, "'") + .trim(); +} + +/** 从 Markdown 源提取 H1 纯文本（去除行内 markdown 标记） */ +function h1OfMd(md: string): string { + // 围栏感知：跳过 ``` 代码块内的 # 注释，取真正的页面 H1 + let inFence = false; + for (const line of md.split("\n")) { + if (line.startsWith("```")) { inFence = !inFence; continue; } + if (!inFence && /^# (?!#)/.test(line)) { + return line + .replace(/^# /, "") + .replace(/`([^`]+)`/g, "$1") + .replace(/\*\*([^*]+)\*\*/g, "$1") + .trim(); + } + } + return ""; +} + +export function createSeoHooks(sidebar: unknown) { + const crumbs = buildCrumbMap(sidebar); + const projectDirs: string[] = []; + let gitDates: Map<string, string> | null = null; + + const readMd = (relativePath: string, srcDir?: string): string => { + try { + return fs.readFileSync( + path.resolve(srcDir || process.cwd(), relativePath), + "utf8", + ); + } catch { + return ""; + } + }; + + /** + * 项目内每个文件最后一次 git 提交的 ISO 时间。 + * 单次 git log 调用构建全量映射（key = 相对路径，与 pageData.relativePath 一致）； + * git 不可用时静默降级（sitemap 无 lastmod、JSON-LD 无 dateModified）。 + */ + const getGitDates = (root: string): Map<string, string> => { + if (gitDates) return gitDates; + gitDates = new Map<string, string>(); + try { + const out = execSync( + "git log --format=:::%cI --name-only --relative -n 500 -- .", + { + cwd: root, + encoding: "utf8", + maxBuffer: 64 * 1024 * 1024, + stdio: ["ignore", "pipe", "ignore"], + }, + ); + let current = ""; + for (const line of out.split(/\r?\n/)) { + if (line.startsWith(":::")) { + current = line.slice(3).trim(); + continue; + } + const file = line.trim(); + if (file && current && !gitDates.has(file)) { + gitDates.set(file, current); + } + } + } catch { + // 降级：无 lastmod / dateModified + } + return gitDates; + }; + + /** 每页独立 title（去 "5.10 " 编号前缀，关键词前置）与 description（:::tip 首句） */ + function transformPageData(pageData: PageDataLike, ctx?: any): Record<string, unknown> { + const srcDir: string | undefined = ctx?.siteConfig?.srcDir; + const root: string | undefined = ctx?.siteConfig?.root; + if (root && !projectDirs.includes(root)) projectDirs.push(root); + + const out: Record<string, unknown> = {}; + const rel = pageData.relativePath; + if (rel && !pageData.frontmatter?.description) { + const desc = extractDescription(readMd(rel, srcDir)); + if (desc) out.description = desc; + } + if (pageData.title) { + out.title = stripNumberPrefix(pageData.title); + } + return out; + } + + /** 构建期注入 canonical / OG / twitter / JSON-LD */ + function transformHead(ctx: TransformCtx): HeadTuple[] { + const rel = ctx?.pageData?.relativePath || ""; + if (!rel || rel === "404.md") return []; + + const route = routeOf(rel); + const url = `${SITE_URL}${route}`; + const title = ctx.pageData?.title || ctx.title || ""; + const desc = ctx.description || ""; + const isHome = rel === "index.md"; + const image = `${SITE_URL}/logo.png`; + + const heads: HeadTuple[] = [ + ["link", { rel: "canonical", href: url }], + ["meta", { property: "og:type", content: isHome ? "website" : "article" }], + ["meta", { property: "og:site_name", content: "DjangoAdmin" }], + ["meta", { property: "og:locale", content: "zh_CN" }], + ["meta", { property: "og:title", content: title }], + ["meta", { property: "og:description", content: desc }], + ["meta", { property: "og:url", content: url }], + ["meta", { property: "og:image", content: image }], + ["meta", { property: "twitter:title", content: title }], + ["meta", { property: "twitter:description", content: desc }], + ["meta", { property: "twitter:url", content: url }], + ["meta", { property: "twitter:image", content: image }], + ]; + + // ---- JSON-LD ---- + const root = ctx.siteConfig?.root || projectDirs[0] || process.cwd(); + const srcDir = ctx.siteConfig?.srcDir || root; + const lastMod = getGitDates(root).get(rel); + const blocks: Record<string, any>[] = []; + + if (isHome) { + blocks.push({ + "@context": "https://schema.org", + "@type": "WebSite", + name: "DjangoAdmin 开发文档", + url: `${SITE_URL}/`, + inLanguage: "zh-CN", + description: desc, + }); + blocks.push({ "@context": "https://schema.org", ...ORG }); + } else { + const md = readMd(rel, srcDir); + const article: Record<string, any> = { + "@context": "https://schema.org", + "@type": "TechArticle", + headline: h1OfMd(md) || h1OfHtml(ctx.content) || title, + description: desc, + url, + inLanguage: "zh-CN", + mainEntityOfPage: { "@type": "WebPage", "@id": url }, + publisher: ORG, + }; + if (lastMod) article.dateModified = lastMod; + blocks.push(article); + + const trail = crumbs.get(route); + if (trail?.length) { + const items: Record<string, any>[] = [ + { "@type": "ListItem", position: 1, name: "首页", item: `${SITE_URL}/` }, + ]; + trail.forEach((name, i) => { + const node: Record<string, any> = { + "@type": "ListItem", + position: i + 2, + name, + }; + if (i === trail.length - 1) node.item = url; + items.push(node); + }); + blocks.push({ + "@context": "https://schema.org", + "@type": "BreadcrumbList", + itemListElement: items, + }); + } + + const faqs = extractFaqs(md); + if (faqs.length) { + blocks.push({ + "@context": "https://schema.org", + "@type": "FAQPage", + mainEntity: faqs.map((f) => ({ + "@type": "Question", + name: f.q, + acceptedAnswer: { "@type": "Answer", text: f.a }, + })), + }); + } + } + + // 转义 "<"，防止内容中出现 </script> 破坏注入 + const json = JSON.stringify(blocks).replace(/</g, "\\u003c"); + heads.push(["script", { type: "application/ld+json" }, json]); + return heads; + } + + /** sitemap.xml：过滤 404/README，注入 git lastmod */ + const sitemap = { + hostname: SITE_URL, + transformItems(items: { url: string; lastmod?: string }[]) { + const root = projectDirs[0] || process.cwd(); + const dates = getGitDates(root); + const out: { url: string; lastmod?: string }[] = []; + for (const item of items) { + // ⚠ vitepress 传入的 item.url 是相对路径（"404.html"、"zh/x.html"、""）， + // 无前导斜杠也无域名——hostname 由 SitemapStream 事后拼接。 + if (/(^|\/)404\.html$/.test(item.url)) continue; // 404 页不收录 + if (/(^|\/)README\.html$/.test(item.url)) continue; // 仓库 README 非文档页 + const p = item.url.replace(/^\//, ""); + const rel = + p === "" || p === "index.html" ? "index.md" : p.replace(/\.html$/, ".md"); + const lastmod = dates.get(rel); + out.push(lastmod ? { ...item, lastmod } : item); + } + return out; + }, + }; + + return { transformPageData, transformHead, sitemap }; +} diff --git a/DjangoAdmin_Flask_NaiveVue/.vitepress/config/shared.ts b/DjangoAdmin_Flask_NaiveVue/.vitepress/config/shared.ts index 58d14fb..6b8c425 100644 --- a/DjangoAdmin_Flask_NaiveVue/.vitepress/config/shared.ts +++ b/DjangoAdmin_Flask_NaiveVue/.vitepress/config/shared.ts @@ -1,6 +1,6 @@ import { defineConfig, HeadConfig } from "vitepress"; -export const META_IMAGE = "/social.png"; +export const META_IMAGE = "/logo.png"; const rControl = /[\u0000-\u001f]/g; const rSpecial = /[\s~`!@#$%^&*()\-_+=[\]{}|\\;:"'“”‘’<>,.?/]+/g; @@ -23,6 +23,8 @@ export const slugify = (str: string): string => export const sharedConfig = defineConfig({ title: "小蚂蚁云", + // 页面 <title> 后缀：「环境准备 | DjangoAdmin 开发文档」（index.md frontmatter 可覆盖） + titleTemplate: "DjangoAdmin 开发文档", appearance: "light", markdown: { diff --git a/DjangoAdmin_Flask_NaiveVue/.vitepress/config/zh.ts b/DjangoAdmin_Flask_NaiveVue/.vitepress/config/zh.ts index 231a658..796d6c9 100644 --- a/DjangoAdmin_Flask_NaiveVue/.vitepress/config/zh.ts +++ b/DjangoAdmin_Flask_NaiveVue/.vitepress/config/zh.ts @@ -1,6 +1,6 @@ import type { DefaultTheme, LocaleSpecificConfig } from "vitepress"; -export const META_URL = "https://www.djangoadmin.cn"; +export const META_URL = "http://docs.flask.naivevue.djangoadmin.cn"; export const META_TITLE = "DjangoAdmin Flask+NaiveUI 开发者文档"; export const META_DESCRIPTION = "DjangoAdmin Flask+NaiveUI 企业级中台解决方案开发者文档"; diff --git a/DjangoAdmin_Flask_NaiveVue/404.md b/DjangoAdmin_Flask_NaiveVue/404.md new file mode 100644 index 0000000..c344b20 --- /dev/null +++ b/DjangoAdmin_Flask_NaiveVue/404.md @@ -0,0 +1,12 @@ +--- +head: + - - meta + - name: robots + content: noindex +--- + +# 页面不存在 + +抱歉，您访问的页面不存在或已被移动。 + +[返回首页](/) · [浏览文档](/zh/introduction) diff --git a/DjangoAdmin_Flask_NaiveVue/package.json b/DjangoAdmin_Flask_NaiveVue/package.json index 77bd941..b5517ed 100644 --- a/DjangoAdmin_Flask_NaiveVue/package.json +++ b/DjangoAdmin_Flask_NaiveVue/package.json @@ -5,7 +5,8 @@ "type": "module", "scripts": { "docs": "vitepress dev .", - "docs:build": "vitepress build .", + "docs:llms": "node scripts/generate-llms-txt.mjs", + "docs:build": "node scripts/generate-llms-txt.mjs && vitepress build .", "docs:preview": "vitepress preview ." }, "dependencies": { diff --git a/DjangoAdmin_Flask_NaiveVue/public/llms.txt b/DjangoAdmin_Flask_NaiveVue/public/llms.txt new file mode 100644 index 0000000..0b885b1 --- /dev/null +++ b/DjangoAdmin_Flask_NaiveVue/public/llms.txt @@ -0,0 +1,169 @@ +# DjangoAdmin Flask+NaiveUI 开发文档 + +> DjangoAdmin Flask+NaiveUI 企业级中台解决方案开发者文档。内置 RBAC 权限体系、代码生成器等开箱即用功能，支持五种数据库一键切换。本文档共 139 篇，按章节组织。 + +## 1. 了解项目 + +- [更新日志](http://docs.flask.naivevue.djangoadmin.cn/zh/changelog.html): 更新日志是项目演进的完整记录，帮助开发者和企业了解每个版本的能力变化与技术演进方向。 +- [新手入门指南](http://docs.flask.naivevue.djangoadmin.cn/zh/course.html): 详细的安装步骤请参考 环境准备 章节。 +- [项目介绍](http://docs.flask.naivevue.djangoadmin.cn/zh/introduction.html): DjangoAdmin 是企业级中台解决方案，后端基于 Flask + SQLAlchemy，前端基于 Vue3 + NaiveUI，内置 RBAC 权限、代码生成器等开箱即用功能， +- [项目目录结构](http://docs.flask.naivevue.djangoadmin.cn/zh/struct.html): + 保持一致性：目录结构一旦确定，应保持一致性，避免随意更改。 +- [为什么选择我们？](http://docs.flask.naivevue.djangoadmin.cn/zh/why.html): 本框架提供开箱即用的企业级中台完整解决方案，免去从零搭建成本，助力中大型企业构建统一的数字化基座。 + +## 2. 快速入门 + +- [后端启动](http://docs.flask.naivevue.djangoadmin.cn/zh/volume1/backend.html): 启动后端前，请确保已完成 环境准备 章节中的所有软件安装。 +- [数据库初始化](http://docs.flask.naivevue.djangoadmin.cn/zh/volume1/database.html): 数据库初始化前，请确保已完成以下准备工作： 1. 目标数据库服务已启动（如 MySQL 8.0+） 2. .env 文件中的 DB_DRIVER 和数据库连接信息已正确配置 3. Python +- [Docker 一键启动](http://docs.flask.naivevue.djangoadmin.cn/zh/volume1/docker.html): 使用 Docker 方式启动前，请确保已安装以下软件： 1. Docker Desktop（Windows / macOS）或 Docker Engine（Linux） 2. Docker +- [环境变量速查表](http://docs.flask.naivevue.djangoadmin.cn/zh/volume1/env-vars.html): 1. .env.example 是环境变量模板文件，已提交到版本控制。 +- [环境准备](http://docs.flask.naivevue.djangoadmin.cn/zh/volume1/environment.html): 1. 部分软件安装后需要设置本地环境变量，便于在终端中使用命令。 +- [常见问题FAQ](http://docs.flask.naivevue.djangoadmin.cn/zh/volume1/faq.html): 遇到问题时，建议先查看终端日志输出和浏览器控制台（F12）的错误信息，通常能快速定位问题原因。 +- [第一个接口调试](http://docs.flask.naivevue.djangoadmin.cn/zh/volume1/first-api.html): 开始调试前，请确保已完成以下步骤： 1. 后端服务已启动（参见 后端启动） 2. 数据库已初始化（参见 数据库初始化） 3. Redis 服务已启动 +- [前端启动](http://docs.flask.naivevue.djangoadmin.cn/zh/volume1/frontend.html): 启动前端前，请确保已完成 环境准备 章节中的 Node.js 和 pnpm 安装，并已启动后端服务（参见 后端启动）。 + +## 3. 模块开发实战 + +- [路由注册（Flask Blueprint）](http://docs.flask.naivevue.djangoadmin.cn/zh/volume2/blueprint.html): 路由注册基于 Flask Blueprint 机制实现模块化挂载，本页讲解 Blueprint 的定义与在路由中心统一注册的方法。 +- [完整代码清单](http://docs.flask.naivevue.djangoadmin.cn/zh/volume2/code-list.html): 本页汇总岗位管理（Position）模块涉及的全部文件代码，开发时可快速查阅与复制对照。 +- [Router 层（Flask Blueprint）](http://docs.flask.naivevue.djangoadmin.cn/zh/volume2/endpoint.html): Router 层是 HTTP 接口层，负责定义路由、权限装饰器与请求参数解析，编写新接口从本页开始。 +- [常见问题与排错](http://docs.flask.naivevue.djangoadmin.cn/zh/volume2/faq.html): 本页汇总模块开发过程中的常见问题与排错方法，开发受阻时按症状索引即可定位。 +- [前端 API 层](http://docs.flask.naivevue.djangoadmin.cn/zh/volume2/fe-api.html): 前端 API 层封装后端接口的 HTTP 请求，每个业务模块对应一个 API 文件，本页讲解基于 Axios 封装的编写规范。 +- [前端路由与菜单](http://docs.flask.naivevue.djangoadmin.cn/zh/volume2/fe-router.html): 本页讲解前端路由与菜单机制——路由和菜单由后端动态返回，前端只需注册路由组件映射。 +- [前端页面视图](http://docs.flask.naivevue.djangoadmin.cn/zh/volume2/fe-view.html): 前端页面视图是用户直接交互的界面，本页讲解 Vue3 + NaiveUI 下一个完整 CRUD 页面的文件组成与编写方式。 +- [数据模型（Model）](http://docs.flask.naivevue.djangoadmin.cn/zh/volume2/model.html): 数据模型是模块开发的第一步，讲解如何用 SQLAlchemy ORM 与基类定义数据库表结构，新建模块时从本页开始。 +- [概述与目标](http://docs.flask.naivevue.djangoadmin.cn/zh/volume2/overview.html): 其中 id、create_user、create_time、update_user、update_time、is_delete 由基类 BaseModel 自动提供，业务字段仅需定义 name、 +- [权限节点配置](http://docs.flask.naivevue.djangoadmin.cn/zh/volume2/permission.html): 实际开发中，查询类权限（page、detail、list）通常合并为一个节点 sys:position:list，减少配置工作量。 +- [Repository 层](http://docs.flask.naivevue.djangoadmin.cn/zh/volume2/repository.html): Repository 层是数据访问层，封装全部数据库查询操作，本页讲解基于 BaseRepository 基类的通用 CRUD 用法。 +- [路由注册](http://docs.flask.naivevue.djangoadmin.cn/zh/volume2/router.html): 路由注册是将模块 Blueprint 挂载到应用的过程，本页讲解在路由注册中心统一挂载的方法。 +- [WTForms Schema](http://docs.flask.naivevue.djangoadmin.cn/zh/volume2/schema.html): Schema 层负责请求数据校验，本页讲解基于 WTForms 表单类与 validators 的校验规范。 +- [Service 层](http://docs.flask.naivevue.djangoadmin.cn/zh/volume2/service.html): Service 层是业务逻辑层，本页讲解基于 BaseService 基类声明差异点即可获得完整增删改查能力的编写方式。 + +## 4. 架构设计 + +- [应用工厂与扩展初始化](http://docs.flask.naivevue.djangoadmin.cn/zh/volume3/app-factory.html): Flask 应用工厂模式（create_app()）是项目的核心初始化机制。 +- [核心基类体系](http://docs.flask.naivevue.djangoadmin.cn/zh/volume3/base-classes.html): 五大基类各司其职，覆盖从数据模型到请求校验再到业务逻辑的完整链路。 +- [缓存架构设计](http://docs.flask.naivevue.djangoadmin.cn/zh/volume3/cache.html): 项目采用两级缓存架构：第一级为进程内字典缓存（dict_util），第二级为 Redis 分布式缓存。 +- [数据库设计](http://docs.flask.naivevue.djangoadmin.cn/zh/volume3/database-design.html): 所有业务表继承 BaseModel 基类，自动获得 6 个通用字段（id / create_user / create_time / update_user / update_time / +- [目录结构设计](http://docs.flask.naivevue.djangoadmin.cn/zh/volume3/directory.html): 目录结构遵循「按功能分组、按职责分层」的原则。 +- [扩展性设计](http://docs.flask.naivevue.djangoadmin.cn/zh/volume3/extensibility.html): 遵循开闭原则（OCP）：对扩展开放，对修改关闭。 +- [Flask g 对象与请求上下文](http://docs.flask.naivevue.djangoadmin.cn/zh/volume3/flask-g-object.html): Flask 的 g 对象是请求级别的全局变量容器，用于在同一请求的不同函数间共享数据。 +- [分层架构设计](http://docs.flask.naivevue.djangoadmin.cn/zh/volume3/layer-arch.html): 采用经典的三层架构，核心原则是：依赖单向、职责单一、接口隔离。 +- [整体架构图](http://docs.flask.naivevue.djangoadmin.cn/zh/volume3/overview.html): 遵循以下架构设计原则，确保系统在长期演进中保持高质量和可维护性： +- [请求完整链路](http://docs.flask.naivevue.djangoadmin.cn/zh/volume3/request-flow.html): 一个典型的 API 请求经过以下阶段：浏览器 → Nginx → CORS → Redis 注入 → DB 会话 → 操作日志 → 路由匹配 → JWT 认证 → RBAC 鉴权 → WTForms +- [安全架构设计](http://docs.flask.naivevue.djangoadmin.cn/zh/volume3/security.html): 纵深防御：认证、授权、参数校验多层防护，单一防线失效时仍有其他机制兜底 最小权限：用户仅能访问已授权接口，角色权限按需分配，遵循"够用即可"原则 数据不落地：敏感信息（Token、 +- [同步架构设计](http://docs.flask.naivevue.djangoadmin.cn/zh/volume3/sync-arch.html): 1. 成熟稳定：Flask 的同步模型经过长期验证，稳定可靠 2. 易于理解：同步编程模型更直观，易于调试和维护 3. 工具完善：Flask 生态完善，各种扩展和工具支持良好 4. 部署简单： +- [同步编程模型](http://docs.flask.naivevue.djangoadmin.cn/zh/volume3/sync-async.html): Flask 基于 WSGI 同步框架，所有视图函数和业务代码均为同步 def。 +- [技术选型说明](http://docs.flask.naivevue.djangoadmin.cn/zh/volume3/tech-stack.html): Flask 是 Python 生态中最轻量、最灵活的 Web 框架，基于 WSGI 同步模型，成熟稳定，易于调试和部署。 + +## 5. 开发指南 + +- [API 接口速查表](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/api-cheatsheet.html): API 接口速查表，按模块分组列出所有 RESTful 接口的请求方法、路径、说明和权限标识。 +- [文章管理](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/business/article.html): 文章管理模块支持富文本编辑、分类关联、封面图片上传、图集管理等功能。 +- [分类管理](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/business/category.html): 分类管理模块用于管理树形分类数据，如文章分类、产品分类等。 +- [行政区划管理](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/business/city.html): 行政区划模块管理全国省/市/区/街道四级区域数据，支持树形结构查询、级联选择器、拼音自动生成等功能。 +- [公告与链接管理](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/business/content.html): 公告、链接、城市是三个简单 CRUD 内容模块，均继承 BaseService，提供标准的增删改查接口。 +- [部门/职级/岗位管理](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/business/dept.html): 部门、职级、岗位是组织架构管理的三个核心模块。 +- [案例演示](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/business/example.html): 案例演示模块是代码生成器的参考模板，展示了标准 CRUD 模块的完整实现。 +- [文件模板管理](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/business/file-template.html): 文件模板模块用于管理系统中的文件模板，如导入导出模板、报表模板等。 +- [定时任务](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/business/job.html): 定时任务模块基于 APScheduler 实现，支持 Cron 表达式调度、任务执行日志、动态启停等功能。 +- [菜单管理](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/business/menu.html): 菜单管理是 RBAC 权限系统的基础，负责管理系统的导航菜单和权限节点。 +- [参数管理](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/business/param.html): 参数管理模块用于管理系统配置和业务配置，每个参数包含名称、编码、值、类型、排序、状态等属性。 +- [角色管理](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/business/role.html): 角色是 RBAC 权限模型的核心，连接用户和菜单（权限）。 +- [用户管理](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/business/user.html): 用户管理是系统的核心模块，属于复杂业务模块。 +- [认证流程实战](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/core/auth-flow.html): 登录 → Token 获取 → 权限校验 → Token 刷新 → 退出登录的完整认证链路实战说明。 +- [验证码机制](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/core/captcha.html): 验证码是防止自动化攻击的重要安全手段。 +- [系统配置管理](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/core/config.html): 系统配置模块用于管理动态的键值对配置项，与数据字典类似但更偏向系统级参数。 +- [跨域资源共享（CORS）](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/core/cors.html): CORS（Cross-Origin Resource Sharing）跨域资源共享是前后端分离架构必须处理的问题。 +- [演示模式](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/core/demo-mode.html): 演示模式用于在线体验环境，开启后所有写操作（新增、编辑、删除等）将被拦截，返回"演示环境，暂无操作权限"提示。 +- [数据字典使用指南](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/core/dict-guide.html): 数据字典的完整使用流程，从新增字典类型到在代码中使用字典数据的实操指南。 +- [字典模块](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/core/dict.html): 数据字典用于管理系统中的枚举值和配置项，如状态、类型、性别等。 +- [异常与响应处理](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/core/exception.html): 项目定义了统一的响应格式和全局异常处理机制。 +- [防重复提交](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/core/idempotent.html): 防重复提交是保障数据一致性的重要措施。 +- [用户认证（JWT）](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/core/jwt.html): JWT（JSON Web Token）是项目的核心认证机制。 +- [登录日志](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/core/login-log.html): 登录日志记录每次登录尝试（成功/失败），包含登录账号、IP地址、浏览器信息、登录时间等。 +- [操作日志](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/core/operation-log.html): 操作日志中间件自动拦截写请求（POST/PUT/DELETE/PATCH）并记录操作日志，无需手动埋点。 +- [权限管理（RBAC）](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/core/rbac.html): 项目采用基于角色的访问控制（RBAC）模型，通过用户-角色-菜单三层关系实现细粒度的权限管理。 +- [事务装饰器](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/core/transaction-decorator.html): 本页讲解事务装饰器的用法，适用于中间件自动事务之外的特殊场景事务控制。 +- [AOP 事务管理](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/core/transaction.html): 本页讲解 AOP 风格的事务管理机制——中间件自动管理数据库事务，业务代码无需手动 commit 或 rollback。 +- [参数验证（Schema）](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/core/validator.html): 项目使用 WTForms 进行请求参数验证。 +- [API 层开发](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/frontend/api.html): 前端 API 层位于 src/api/ 目录，封装所有与后端的 HTTP 请求。 +- [前端构建](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/frontend/build.html): 前端使用 Vite 构建，支持开发服务器和生产构建。 +- [公共组件库](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/frontend/components.html): 项目提供丰富的公共组件，位于 ui/src/components/ 目录，基于 NaiveUI 二次封装，覆盖表格、表单、弹窗、上传、富文本编辑等常见场景。 +- [BasicForm 表单](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/frontend/form.html): BasicForm 位于 src/components/Form/src/BasicForm.vue，基于 NaiveUI 的 n-form 二次封装，通过 schemas 配置化定义表单字段， +- [Hooks 组合式函数](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/frontend/hooks.html): 项目封装了一系列组合式函数（Hooks），位于 src/hooks/ 和 src/utils/ 目录，提供权限检查、异步 loading、防重复提交、实时时钟、项目配置等可复用逻辑。 +- [国际化](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/frontend/i18n.html): 当前项目仅支持中文界面，NaiveUI 通过 n-config-provider 的 locale 属性配置中文语言包，所有界面文本直接硬编码在组件中。 +- [Modal 弹窗](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/frontend/modal.html): 项目提供 BasicModal 组件（src/components/Modal/src/BasicModal.vue）和原生 basicModal 两种弹窗用法。 +- [权限指令 v-perm](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/frontend/perm-directive.html): v-perm 和 v-perms 是项目自定义的 Vue 指令，用于按钮级别的权限控制，无权限时自动从 DOM 中移除元素。 +- [路由与菜单](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/frontend/router.html): 前端路由基于 Vue Router 4 实现动态路由生成，菜单数据从后端获取，通过 generator-routers.ts 递归生成路由表，路由守卫控制登录状态和权限。 +- [前端环境与结构](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/frontend/setup.html): 前端基于 Vue3 + NaiveUI 构建，使用 pnpm 作为包管理工具，Vite 作为构建工具，TypeScript 作为开发语言。 +- [Store 状态管理](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/frontend/store.html): 前端使用 Pinia 进行状态管理，核心模块包括 user（用户信息与权限）、asyncRoute（动态路由与菜单）、projectSetting（项目配置）、designSetting（主题设计）等。 +- [样式与主题](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/frontend/style.html): 前端样式方案采用 Tailwind CSS + SCSS + NaiveUI 主题系统，支持深色模式切换。 +- [BasicTable 表格](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/frontend/table.html): BasicTable 位于 src/components/Table/src/Table.vue，基于 NaiveUI 的 n-data-table 二次封装，提供列定义、数据请求、分页、操作列、 +- [工具函数](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/frontend/utils.html): 前端工具函数位于 src/utils/ 目录，提供认证管理、本地存储、日期格式化、树结构操作、文件下载等通用能力。 +- [页面视图开发](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/frontend/view.html): 页面视图位于 src/views/ 目录，每个业务模块遵循 index.vue（列表页）+ edit.vue（编辑弹窗）的标准模式，辅以 columns.ts（列定义）和 +- [接口响应规范](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/integration/api-contract.html): 后端所有接口统一返回 R.ok() / R.failed() 格式的 JSON 响应，前端通过 VAxios 的 transformRequestData 拦截器统一解包处理。 +- [字典数据联调](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/integration/dict-sync.html): 字典数据通过后端字典 API 获取，前端在下拉选择器中渲染选项。 +- [权限节点联动](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/integration/perm-sync.html): 前后端权限通过统一的权限节点字符串联动，后端 @check_permission 校验权限，前端 v-perm 指令和 TableAction 的 auth 属性控制按钮显示。 +- [代理配置](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/integration/proxy.html): 开发环境通过 Vite 代理转发 API 请求到后端，生产环境通过 Nginx 代理。 +- [文件上传联调](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/integration/upload-sync.html): 文件上传涉及前端 Upload 组件、后端上传接口和 URL 拼接三个环节，需要前后端协同配置。 +- [数据库会话](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/tools/db-session.html): 项目通过 Flask 的 g 对象和 before_request / after_request 钩子实现请求级数据库会话管理，写操作按业务成功与否自动 commit/rollback。 +- [导入导出](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/tools/excel.html): 项目基于 openpyxl 实现 Excel 导入导出功能，支持通过 file_template 模块管理导入模板配置。 +- [代码生成器](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/tools/generator.html): 本页讲解代码生成器的用法，可根据数据库表结构一键生成前后端 CRUD 全套代码。 +- [IP/UA 解析](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/tools/ip-ua.html): 项目提供客户端 IP 获取、IP 地理位置查询和 User-Agent 解析三大能力。 +- [密码工具](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/tools/password.html): 项目采用 bcrypt 双重加盐方案存储密码，源码位于 src/core/password.py。 +- [权限缓存](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/tools/perm-cache.html): 项目通过 Redis 实现用户权限和菜单的缓存，采用用户级缓存 + 全局版本号双层策略。 +- [请求解析工具](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/tools/request-util.html): src/common/utils/request.py 提供请求数据解析相关的工具函数，包括批量 ID 解析、SQL LIKE 安全处理、分页参数解析等。 +- [富文本过滤](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/tools/rich-text.html): 富文本编辑器内容存在存储型 XSS 风险，项目通过 bleach 库实现 HTML 白名单清洗，在落盘前统一过滤危险内容。 +- [文件上传完整流程](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/tools/upload-guide.html): 富文本编辑器（如 TinyMCE、CKEditor、WangEditor 等）的图片上传同样使用此接口。 +- [文件上传](http://docs.flask.naivevue.djangoadmin.cn/zh/volume4/tools/upload.html): 项目提供本地文件上传功能，支持图片和通用文件上传，内置扩展名白名单、大小限制、魔术字节校验和路径遍历防护。 + +## 6. 代码生成器 + +- [CLI 命令行使用](http://docs.flask.naivevue.djangoadmin.cn/zh/volume5/cli.html): 代码生成器 CLI 模式的使用方法，包括单表生成、批量生成、预览模式和配置导出。 +- [代码生成引擎](http://docs.flask.naivevue.djangoadmin.cn/zh/volume5/code-engine.html): 代码生成引擎的工作原理，包括配置解析、模板渲染、文件写入和自动注册的完整流程。 +- [配置文件详解](http://docs.flask.naivevue.djangoadmin.cn/zh/volume5/config.html): 代码生成器 JSON 配置文件的格式说明，包括模块名称、字段属性、字典编码等配置项的详细解释。 +- [实战案例](http://docs.flask.naivevue.djangoadmin.cn/zh/volume5/demo.html): 以 flask_example 演示表为完整案例，演示从建表到生成到使用的全流程。 +- [常见问题](http://docs.flask.naivevue.djangoadmin.cn/zh/volume5/faq.html): 代码生成器使用过程中常见问题的原因分析和解决方案。 +- [概述与架构](http://docs.flask.naivevue.djangoadmin.cn/zh/volume5/overview.html): 代码生成器的整体架构、核心模块和生成流程概述。 +- [表结构解析引擎](http://docs.flask.naivevue.djangoadmin.cn/zh/volume5/parser.html): 表结构解析引擎的工作原理，从数据库读取表元数据并智能推断字段用途的过程。 +- [自定义模板](http://docs.flask.naivevue.djangoadmin.cn/zh/volume5/templates.html): 代码生成器模板的 Jinja2 语法说明，包括模板变量、字段属性和自定义模板的开发方法。 +- [Web 管理界面](http://docs.flask.naivevue.djangoadmin.cn/zh/volume5/web-ui.html): 代码生成器 Web 管理界面的使用方法，通过可视化界面操作单表生成和批量生成。 + +## 7. 运维部署 + +- [备份与恢复](http://docs.flask.naivevue.djangoadmin.cn/zh/volume6/backup.html): - 3 份数据副本（1 份生产 + 2 份备份） - 2 种不同存储介质（如本地磁盘 + 远程存储） - 1 份异地备份（防机房级灾难） +- [数据库迁移](http://docs.flask.naivevue.djangoadmin.cn/zh/volume6/db-migrate.html): - 结构迁移：Flask-Migrate / Alembic（自动生成 DDL 差异） - 数据迁移：scripts/migrate_db.py（跨库数据泵） - 初始化： +- [部署 Checklist](http://docs.flask.naivevue.djangoadmin.cn/zh/volume6/deploy-checklist.html): 从服务器准备到应用上线的完整部署操作清单，适用于生产环境首次部署和后续版本更新。 +- [Docker容器化](http://docs.flask.naivevue.djangoadmin.cn/zh/volume6/docker.html): - 环境一致性：消除"在我机器上能跑"的问题 - 快速部署：一条命令启动完整服务 - 资源隔离：应用与宿主机环境解耦 +- [环境规划](http://docs.flask.naivevue.djangoadmin.cn/zh/volume6/env-plan.html): 各环境之间保持代码一致，仅通过环境变量（.env）区分配置。 +- [健康检查与监控](http://docs.flask.naivevue.djangoadmin.cn/zh/volume6/monitoring.html): `` 1. 应用层：健康检查端点、业务指标 2. 系统层：CPU/内存/磁盘/网络 3. 中间件：MySQL/Redis 连接状态 4. 日志：集中式日志收集与分析 `` +- [Nginx 反向代理](http://docs.flask.naivevue.djangoadmin.cn/zh/volume6/nginx.html): `` 客户端 → Nginx（80/443） ├─ / → 前端静态资源（dist/） ├─ /api/v1/... → Flask 后端（8021） └─ /api/file/ → 上传文件目录 +- [性能调优](http://docs.flask.naivevue.djangoadmin.cn/zh/volume6/performance.html): 1. 先测量，后优化：用数据说话，避免盲目调参 2. 瓶颈优先：找到最大瓶颈，集中优化 3. 渐进式：每次只调整一个参数，观察效果 +- [生产环境部署实战](http://docs.flask.naivevue.djangoadmin.cn/zh/volume6/production-guide.html): 生产环境部署实战指南，包含完整的部署流程、配置示例、常见问题处理和性能优化建议。 +- [安全加固](http://docs.flask.naivevue.djangoadmin.cn/zh/volume6/security-hardening.html): - 最小权限：只开放必要的端口和权限 - 纵深防御：多层安全措施叠加 - 默认安全：配置默认值应为安全选项 +- [Supervisor进程管理](http://docs.flask.naivevue.djangoadmin.cn/zh/volume6/supervisor.html): - Linux 服务器直接部署（非 Docker） - 需要进程自动重启和日志轮转 - 管理多个相关进程 +- [故障排查手册](http://docs.flask.naivevue.djangoadmin.cn/zh/volume6/troubleshooting.html): 1. 查看日志：tail -f logs/supervisor.out.log 或 docker-compose logs -f 2. 检查配置：.env 文件、数据库连接、Redis 连接 3. +- [版本升级流程](http://docs.flask.naivevue.djangoadmin.cn/zh/volume6/upgrade.html): 1. 先备份，后升级 2. 先测试环境，后生产环境 3. 每次升级可回滚 4. 低峰期执行升级 + +## 8. 规范标准 + +- [API响应规范](http://docs.flask.naivevue.djangoadmin.cn/zh/volume7/api-response.html): - 所有接口必须通过 R.ok() 或 R.failed() 返回，禁止直接返回 dict - 成功响应 code=0，失败响应 code=1 - 响应体始终包含 code、data、msg、ok +- [代码审查清单](http://docs.flask.naivevue.djangoadmin.cn/zh/volume7/code-review.html): - 每次提交必须经过至少一人审查 - 审查关注点：正确性 > 安全性 > 可维护性 > 性能 - 审查意见应具体、可操作，避免主观评价 +- [删除规范](http://docs.flask.naivevue.djangoadmin.cn/zh/volume7/deletion.html): - is_delete = 0：正常记录（默认值） - is_delete = 1：已删除记录 - 所有查询方法自动过滤 is_delete = 0，业务层无需关心 +- [文档规范](http://docs.flask.naivevue.djangoadmin.cn/zh/volume7/doc-standard.html): - 文档与代码同步更新 - 使用中文编写（项目约定） - 示例代码可直接运行 +- [Router层规范](http://docs.flask.naivevue.djangoadmin.cn/zh/volume7/endpoint.html): - Router 只做请求分发，不含业务逻辑 - 通过装饰器控制权限 - 委托 Service 处理业务逻辑 - 返回 R 封装的响应 +- [前端 API 规范](http://docs.flask.naivevue.djangoadmin.cn/zh/volume7/fe-api.html): - 每个后端模块对应一个 API 文件 - 函数命名统一使用 名词 + 动词 格式（与后端保持一致） - 请求路径使用相对路径（/position/page），不含 /api/v1 前缀（由 +- [前端页面规范](http://docs.flask.naivevue.djangoadmin.cn/zh/volume7/fe-component.html): - Vue3（Composition API + <script setup>） - NaiveUI - 自定义组件（BasicTable / BasicForm / TableAction / +- [Git提交规范](http://docs.flask.naivevue.djangoadmin.cn/zh/volume7/git.html): `` <type>(<scope>): <subject> <body> <footer> `` +- [分页规范](http://docs.flask.naivevue.djangoadmin.cn/zh/volume7/pagination.html): - 前端传递 pageNo（页码，从 1 开始）和 pageSize（每页条数） - 后端返回分页数据字典，包含 items / total / page / pageSize / pages +- [Repository 层规范](http://docs.flask.naivevue.djangoadmin.cn/zh/volume7/repository.html): - Repository 只做数据访问原语，不处理 R 封装/序列化/业务逻辑 - 所有方法均为 @classmethod，无需创建实例 - 软删除由基类自动处理，子类无需关心 - +- [Router层规范](http://docs.flask.naivevue.djangoadmin.cn/zh/volume7/router.html): - Router 层不含业务逻辑，仅做路由定义、权限校验和参数解析 - 装饰器顺序固定为：路由 → 权限 → 演示模式 → 操作日志 - Service 模块在文件顶部统一导入（from +- [Service 层规范](http://docs.flask.naivevue.djangoadmin.cn/zh/volume7/service.html): BaseService 采用模板方法模式：基类定义流程骨架，子类通过声明差异点和覆盖钩子定制行为。 +- [测试规范](http://docs.flask.naivevue.djangoadmin.cn/zh/volume7/testing.html): 1. 契约测试（Contract）：验证路由、权限、表名等契约不变 2. 单元测试（Unit）：验证单个函数/方法的逻辑正确性 3. 集成测试（Integration）：验证模块间协作、真实数据库操作 +- [WTForms Schema 规范](http://docs.flask.naivevue.djangoadmin.cn/zh/volume7/wtforms.html): - 创建/编辑共用一个表单类，继承 BaseForm - 特殊操作单独建类（如状态更新、排序调整） - message 必填，用于返回给前端的错误信息 - 唯一性校验通过自定义 validate_ + +## 附录 + +- [常见问题汇总](http://docs.flask.naivevue.djangoadmin.cn/zh/faq.html): 本页汇总了项目各模块的常见问题及解决方案，按场景分类索引。 +- [免责声明](http://docs.flask.naivevue.djangoadmin.cn/zh/other/declare.html): 使用本产品前必读的法律声明，明确产品性质、使用限制与责任划分，一旦使用本产品即视为接受本声明全部条款。 +- [广告赞助](http://docs.flask.naivevue.djangoadmin.cn/zh/other/sponsor.html): 1. 投放广告不得与官方全系产品存在结构性冲突和竞争 2. 广告内容需符合国家法律法规，不得包含虚假、误导性信息 3. 广告素材需经官方审核通过后方可上线，审核周期 1-3 个工作日 4. diff --git a/DjangoAdmin_Flask_NaiveVue/public/robots.txt b/DjangoAdmin_Flask_NaiveVue/public/robots.txt new file mode 100644 index 0000000..7069fa7 --- /dev/null +++ b/DjangoAdmin_Flask_NaiveVue/public/robots.txt @@ -0,0 +1,33 @@ +# DjangoAdmin Flask+NaiveUI 开发文档 +User-agent: * +Allow: / + +# 显式放行生成式引擎 / AI 爬虫（GEO） +User-agent: GPTBot +Allow: / + +User-agent: ChatGPT-User +Allow: / + +User-agent: ClaudeBot +Allow: / + +User-agent: Claude-Web +Allow: / + +User-agent: anthropic-ai +Allow: / + +User-agent: PerplexityBot +Allow: / + +User-agent: Google-Extended +Allow: / + +User-agent: Bytespider +Allow: / + +User-agent: bingbot +Allow: / + +Sitemap: http://docs.flask.naivevue.djangoadmin.cn/sitemap.xml diff --git a/DjangoAdmin_Flask_NaiveVue/scripts/generate-llms-txt.mjs b/DjangoAdmin_Flask_NaiveVue/scripts/generate-llms-txt.mjs new file mode 100644 index 0000000..31a5cf0 --- /dev/null +++ b/DjangoAdmin_Flask_NaiveVue/scripts/generate-llms-txt.mjs @@ -0,0 +1,122 @@ +#!/usr/bin/env node +/** + * 生成 public/llms.txt（llmstxt.org 标准）——AI 爬虫的站点摘要索引。 + * + * 数据源：zh 目录下全部 Markdown 的 H1 + :::tip 概述首句（与 meta + * description 同源，复用 .vitepress/config/extract.mjs）。按侧边栏章节分组。 + * + * 用法：node scripts/generate-llms-txt.mjs + * 已挂入 package.json 的 docs:build 前置步骤。 + */ +import fs from "node:fs"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; +import { + SITE_URL, + SITE_DESCRIPTION, + extractDescription, +} from "../.vitepress/config/extract.mjs"; + +const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."); +const ZH = path.join(ROOT, "zh"); + +/** 顶层目录 → 侧边栏章节名（与 .vitepress/config/zh.ts 保持一致） */ +const SECTIONS = [ + ["", "1. 了解项目"], + ["volume1", "2. 快速入门"], + ["volume2", "3. 模块开发实战"], + ["volume3", "4. 架构设计"], + ["volume4", "5. 开发指南"], + ["volume5", "6. 代码生成器"], + ["volume6", "7. 运维部署"], + ["volume7", "8. 规范标准"], + ["other", "附录"], +]; + +function walk(dir, out = []) { + for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { + const p = path.join(dir, entry.name); + if (entry.isDirectory()) walk(p, out); + else if (entry.name.endsWith(".md")) out.push(p); + } + return out; +} + +/** 提取首个 H1 文本 */ +function h1Of(md) { + // 围栏感知：跳过 ``` 代码块内的 # 注释，取真正的页面 H1 + let inFence = false; + for (const line of md.split("\n")) { + if (line.startsWith("```")) { inFence = !inFence; continue; } + if (!inFence && line.startsWith("# ") && !line.startsWith("## ")) { + return line.slice(2).trim(); + } + } + return ""; +} + +/** H1 编号排序键："5.10 x" → [5,10]；无编号排最后 */ +function sortKey(h1) { + const m = h1.match(/^(\d+(?:\.\d+)*)/); + if (m) return m[1].split(".").map(Number); + const letter = h1.match(/^([A-Z])\./); + if (letter) return [1000 + letter[1].charCodeAt(0)]; + return [9999]; +} + +function cmpKey(a, b) { + const len = Math.max(a.length, b.length); + for (let i = 0; i < len; i++) { + const x = a[i] ?? 0; + const y = b[i] ?? 0; + if (x !== y) return x - y; + } + return 0; +} + +const files = walk(ZH); +const groups = new Map(SECTIONS.map(([dir, label]) => [label, []])); + +for (const file of files) { + const rel = path.relative(ZH, file).replace(/\\/g, "/"); + const topDir = rel.includes("/") ? rel.split("/")[0] : ""; + const base = rel.split("/").pop(); + const label = (topDir === "" && base === "faq.md") ? "附录" + : SECTIONS.find(([dir]) => dir === topDir)?.[1] ?? "附录"; + + const md = fs.readFileSync(file, "utf8"); + const h1 = h1Of(md); + if (!h1) continue; + const desc = extractDescription(md); + const url = `${SITE_URL}/zh/${rel.replace(/\.md$/, ".html")}`; + groups.get(label).push({ h1, desc, url, key: sortKey(h1) }); +} + +const lines = [ + "# DjangoAdmin Flask+NaiveUI 开发文档", + "", + `> ${SITE_DESCRIPTION}。内置 RBAC 权限体系、代码生成器等开箱即用功能，支持五种数据库一键切换。本文档共 ${files.length} 篇，按章节组织。`, + "", +]; + +// 按章节顺序输出，合并重复 label（appendix/other 同为「附录」，只输出一次） +const printed = new Set(); +for (const [, label] of SECTIONS) { + if (printed.has(label)) continue; + const items = groups.get(label); + if (!items?.length) continue; + printed.add(label); + + lines.push(`## ${label}`, ""); + items.sort((a, b) => cmpKey(a.key, b.key)); + for (const { h1, desc, url } of items) { + lines.push(desc ? `- [${h1}](${url}): ${desc}` : `- [${h1}](${url})`); + } + lines.push(""); +} + +const out = path.join(ROOT, "public", "llms.txt"); +fs.writeFileSync(out, lines.join("\n"), "utf8"); +console.log( + `llms.txt: ${files.length} 页 → ${path.relative(ROOT, out)} (${printed.size} 个章节)`, +); diff --git a/DjangoAdmin_Flask_NaiveVue/zh/course.md b/DjangoAdmin_Flask_NaiveVue/zh/course.md index b3df6fb..f208ed3 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/course.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/course.md @@ -1,3 +1,5 @@ +# 新手入门指南 + :::warning 特别提醒 官方精心制作本教程，目的在于方便用户快速掌握软件产品的使用和部署。通过此教程，刚入行的开发者也可以快速掌握并投入产品研发。本地部署时务必请耐心阅读文档操作。 ::: diff --git a/DjangoAdmin_Flask_NaiveVue/zh/introduction.md b/DjangoAdmin_Flask_NaiveVue/zh/introduction.md index a54ca54..8aa9e7d 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/introduction.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/introduction.md @@ -1,3 +1,9 @@ +# 项目介绍 + +:::tip 概述 +DjangoAdmin 是企业级中台解决方案，后端基于 Flask + SQLAlchemy，前端基于 Vue3 + NaiveUI，内置 RBAC 权限、代码生成器等开箱即用功能，支持五种数据库一键切换。 +::: + <div align="center"> <p align="center"> <img src="/logo.png" height="150" alt="logo"/> diff --git a/DjangoAdmin_Flask_NaiveVue/zh/other/declare.md b/DjangoAdmin_Flask_NaiveVue/zh/other/declare.md index 7737479..915692a 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/other/declare.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/other/declare.md @@ -1,5 +1,9 @@ # 免责声明 +:::tip 概述 +使用本产品前必读的法律声明，明确产品性质、使用限制与责任划分，一旦使用本产品即视为接受本声明全部条款。 +::: + :::danger 重要提示 任何用户在使用本团队研发的系列软件产品（以下简称「本产品」）前，请仔细阅读并透彻理解本声明。选择不使用本产品，可随时停止使用；一旦使用本产品，即视为对本声明全部内容的认可和接受。 ::: diff --git a/DjangoAdmin_Flask_NaiveVue/zh/struct.md b/DjangoAdmin_Flask_NaiveVue/zh/struct.md index 164bfbd..ead39fc 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/struct.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/struct.md @@ -1,3 +1,5 @@ +# 项目目录结构 + ## 目录说明 在软件开发过程中，优秀的软件目录结构对于项目的组织、开发、维护和扩展至关重要，合理的目录结构能够显著提升开发效率和代码可维护性。 diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume2/blueprint.md b/DjangoAdmin_Flask_NaiveVue/zh/volume2/blueprint.md index 3db027b..6bff9d1 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume2/blueprint.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume2/blueprint.md @@ -1,5 +1,9 @@ # 路由注册（Flask Blueprint） +:::tip 概述 +路由注册基于 Flask Blueprint 机制实现模块化挂载，本页讲解 Blueprint 的定义与在路由中心统一注册的方法。 +::: + Flask 使用 `Blueprint` 机制实现模块化路由注册。每个业务模块定义自己的 Blueprint，然后在路由注册中心统一挂载到应用。 ## Blueprint 概念 diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume2/code-list.md b/DjangoAdmin_Flask_NaiveVue/zh/volume2/code-list.md index be7ac1d..524c70b 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume2/code-list.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume2/code-list.md @@ -1,5 +1,9 @@ # 完整代码清单 +:::tip 概述 +本页汇总岗位管理（Position）模块涉及的全部文件代码，开发时可快速查阅与复制对照。 +::: + 本章汇总 Position 岗位模块涉及的全部文件，便于开发时快速查阅和复制。 ## 后端文件清单 diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume2/endpoint.md b/DjangoAdmin_Flask_NaiveVue/zh/volume2/endpoint.md index 45b755b..03837f6 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume2/endpoint.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume2/endpoint.md @@ -1,5 +1,9 @@ # Router 层（Flask Blueprint） +:::tip 概述 +Router 层是 HTTP 接口层，负责定义路由、权限装饰器与请求参数解析，编写新接口从本页开始。 +::: + Router 层是 HTTP 接口层，负责定义路由、权限装饰器和请求参数解析。每个业务模块对应一个 router 文件，所有业务逻辑委托给 Service 层处理。 ## 文件位置 diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume2/faq.md b/DjangoAdmin_Flask_NaiveVue/zh/volume2/faq.md index f43ef34..b18a4fb 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume2/faq.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume2/faq.md @@ -1,5 +1,9 @@ # 常见问题与排错 +:::tip 概述 +本页汇总模块开发过程中的常见问题与排错方法，开发受阻时按症状索引即可定位。 +::: + 本章汇总模块开发过程中的常见问题和解决方案。 ## 后端问题 diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume2/fe-api.md b/DjangoAdmin_Flask_NaiveVue/zh/volume2/fe-api.md index 797cc1c..ae9203a 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume2/fe-api.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume2/fe-api.md @@ -1,5 +1,9 @@ # 前端 API 层 +:::tip 概述 +前端 API 层封装后端接口的 HTTP 请求，每个业务模块对应一个 API 文件，本页讲解基于 Axios 封装的编写规范。 +::: + 前端 API 层负责封装后端接口的 HTTP 请求。每个业务模块对应一个 API 文件，使用项目封装的 Axios 工具发送请求。 ## 文件位置 diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume2/fe-router.md b/DjangoAdmin_Flask_NaiveVue/zh/volume2/fe-router.md index 0f79bbe..5c2330b 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume2/fe-router.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume2/fe-router.md @@ -1,5 +1,9 @@ # 前端路由与菜单 +:::tip 概述 +本页讲解前端路由与菜单机制——路由和菜单由后端动态返回，前端只需注册路由组件映射。 +::: + 前端路由定义页面的访问路径，菜单是路由的可视化展示。项目的路由和菜单由后端动态返回，前端只需注册路由组件映射。 ## 路由配置 diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume2/fe-view.md b/DjangoAdmin_Flask_NaiveVue/zh/volume2/fe-view.md index de87811..bc4e267 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume2/fe-view.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume2/fe-view.md @@ -1,5 +1,9 @@ # 前端页面视图 +:::tip 概述 +前端页面视图是用户直接交互的界面，本页讲解 Vue3 + NaiveUI 下一个完整 CRUD 页面的文件组成与编写方式。 +::: + 前端页面视图是用户直接交互的界面。项目使用 Vue3 + NaiveUI + Vite 构建。一个完整的 CRUD 页面由 4 个文件组成： ``` diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume2/model.md b/DjangoAdmin_Flask_NaiveVue/zh/volume2/model.md index 7ebcb10..229652c 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume2/model.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume2/model.md @@ -1,5 +1,9 @@ # 数据模型（Model） +:::tip 概述 +数据模型是模块开发的第一步，讲解如何用 SQLAlchemy ORM 与基类定义数据库表结构，新建模块时从本页开始。 +::: + 数据模型是模块开发的第一步，用于定义数据库表结构。项目使用 `SQLAlchemy ORM`，模型类通过继承基类自动获得通用字段和方法。 ## 文件位置 diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume2/repository.md b/DjangoAdmin_Flask_NaiveVue/zh/volume2/repository.md index 17f722a..660a1cd 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume2/repository.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume2/repository.md @@ -1,5 +1,9 @@ # Repository 层 +:::tip 概述 +Repository 层是数据访问层，封装全部数据库查询操作，本页讲解基于 BaseRepository 基类的通用 CRUD 用法。 +::: + Repository 层是数据访问层，封装所有数据库查询操作。项目通过 `BaseRepository` 基类提供通用 CRUD 能力，子类只需声明 `model` 并按需实现 `page()` 和 `list_enabled()` 方法。 ## 文件位置 diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume2/router.md b/DjangoAdmin_Flask_NaiveVue/zh/volume2/router.md index 7c04da7..8e52cef 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume2/router.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume2/router.md @@ -1,5 +1,9 @@ # 路由注册 +:::tip 概述 +路由注册是将模块 Blueprint 挂载到应用的过程，本页讲解在路由注册中心统一挂载的方法。 +::: + 路由注册是将模块的 Blueprint 挂载到应用的过程。所有模块的路由在 `src/routes/v1.py` 中统一注册。 ## 文件位置 diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume2/schema.md b/DjangoAdmin_Flask_NaiveVue/zh/volume2/schema.md index 8f111d1..c0494dc 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume2/schema.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume2/schema.md @@ -1,5 +1,9 @@ # WTForms Schema +:::tip 概述 +Schema 层负责请求数据校验，本页讲解基于 WTForms 表单类与 validators 的校验规范。 +::: + Schema 层负责请求数据的校验。项目使用 `WTForms` 定义表单类，通过 `validators` 约束字段格式，框架在接收请求体时自动执行校验。 ## 文件位置 diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume2/service.md b/DjangoAdmin_Flask_NaiveVue/zh/volume2/service.md index 84889f1..35cdece 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume2/service.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume2/service.md @@ -1,5 +1,9 @@ # Service 层 +:::tip 概述 +Service 层是业务逻辑层，本页讲解基于 BaseService 基类声明差异点即可获得完整增删改查能力的编写方式。 +::: + Service 层是业务逻辑层，负责实现具体的业务规则。简单 CRUD 模块继承 `BaseService` 基类，只需声明差异点即可获得完整的增删改查能力。 ## 文件位置 diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/article.md b/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/article.md index 399a9ca..7e8c3fa 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/article.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/article.md @@ -1,3 +1,5 @@ +# 文章管理 + :::tip 文章管理 文章管理模块支持富文本编辑、分类关联、封面图片上传、图集管理等功能。适用于新闻、公告、帮助文档等内容管理场景。本模块是典型的「带文件处理」业务模块，涵盖了封面迁移、图集处理、富文本 XSS 清洗等核心机制。 ::: diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/category.md b/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/category.md index ae44e52..1c49d5e 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/category.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/category.md @@ -1,3 +1,5 @@ +# 分类管理 + :::tip 分类管理 分类管理模块用于管理树形分类数据，如文章分类、产品分类等。通过 `parent_id` 字段实现无限级分类。 ::: diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/city.md b/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/city.md index 0fc2e12..3e9863a 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/city.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/city.md @@ -1,3 +1,5 @@ +# 行政区划管理 + :::tip 行政区划 行政区划模块管理全国省/市/区/街道四级区域数据，支持树形结构查询、级联选择器、拼音自动生成等功能。用户表通过 `province_code`/`city_code`/`district_code`/`street_code` 四个字段关联城市表的 `area_code`。 ::: diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/content.md b/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/content.md index e281099..eff119e 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/content.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/content.md @@ -1,3 +1,5 @@ +# 公告与链接管理 + :::tip 公告/链接/城市 公告、链接、城市是三个简单 CRUD 内容模块，均继承 BaseService，提供标准的增删改查接口。适用于系统公告、友情链接、城市数据等场景。 ::: diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/dept.md b/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/dept.md index 66d260f..2556b24 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/dept.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/dept.md @@ -1,3 +1,5 @@ +# 部门/职级/岗位管理 + :::tip 部门/职级/岗位 部门、职级、岗位是组织架构管理的三个核心模块。部门采用树形结构，职级和岗位为简单 CRUD 模块，均继承 `BaseService`。用户表通过 `dept_id`、`position_id`、`level_id` 三个外键关联这三个模块。 ::: diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/example.md b/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/example.md index d3110ba..fa2edd6 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/example.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/example.md @@ -1,3 +1,5 @@ +# 案例演示 + :::tip 案例演示 案例演示模块是代码生成器的参考模板，展示了标准 CRUD 模块的完整实现。包含文件字段处理、枚举字典映射、状态管理等功能，可作为新模块开发的参考范例。 ::: diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/file-template.md b/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/file-template.md index d7e1527..1d8ee75 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/file-template.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/file-template.md @@ -1,3 +1,5 @@ +# 文件模板管理 + :::tip 文件模板 文件模板模块用于管理系统中的文件模板，如导入导出模板、报表模板等。支持模板文件上传、按编码查询、文件 URL 自动转换等功能。 ::: diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/job.md b/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/job.md index 6e7c4b4..94304f9 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/job.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/job.md @@ -1,3 +1,5 @@ +# 定时任务 + :::tip 定时任务 定时任务模块基于 APScheduler 实现，支持 Cron 表达式调度、任务执行日志、动态启停等功能。包含 job（任务定义）、job_log（执行日志）、scheduler（调度器）三个子模块。 ::: diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/menu.md b/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/menu.md index ef9332a..b88f910 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/menu.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/menu.md @@ -1,3 +1,5 @@ +# 菜单管理 + :::tip 菜单管理 菜单管理是 RBAC 权限系统的基础，负责管理系统的导航菜单和权限节点。支持目录/菜单（type=0）和权限按钮节点（type=1）两种类型，通过树形结构组织。权限节点由系统根据前端勾选自动生成，采用 `sys:module:action` 三段式命名。 ::: diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/param.md b/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/param.md index 09e6a68..e107a1b 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/param.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/param.md @@ -1,3 +1,5 @@ +# 参数管理 + :::tip 参数管理 参数管理模块用于管理系统配置和业务配置，每个参数包含名称、编码、值、类型、排序、状态等属性。本模块是典型的「BaseService 简单模块」，通过声明差异点即可获得完整 CRUD 能力。 ::: diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/role.md b/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/role.md index 24a0811..696bcce 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/role.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/role.md @@ -1,3 +1,5 @@ +# 角色管理 + :::tip 角色管理 角色是 RBAC 权限模型的核心，连接用户和菜单（权限）。通过为角色分配菜单权限，再将角色分配给用户，实现灵活的权限管理。角色删除时需清理关联的用户角色和角色菜单数据，并即时失效受影响用户的权限缓存。 ::: diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/user.md b/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/user.md index f9891d6..7f15a85 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/user.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume4/business/user.md @@ -1,3 +1,5 @@ +# 用户管理 + :::tip 用户管理 用户管理是系统的核心模块，属于复杂业务模块。包含用户 CRUD、角色关联、密码加密、行政区划、Excel 导入导出等功能。用户管理继承 `BaseService` 获得标准 CRUD 能力，并通过覆写钩子方法实现头像保存、密码加密、角色关联等定制逻辑。 ::: diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/captcha.md b/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/captcha.md index d7308b3..dcec275 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/captcha.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/captcha.md @@ -1,3 +1,5 @@ +# 验证码机制 + :::tip 验证码 验证码是防止自动化攻击的重要安全手段。项目使用 Pillow 生成图片验证码，存储在 Redis 中，支持防刷限流和万能验证码（演示模式）。源码位于 `src/common/utils/captcha.py`。 ::: diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/config.md b/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/config.md index 0ab6cea..7f23f02 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/config.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/config.md @@ -1,3 +1,5 @@ +# 系统配置管理 + :::tip 系统配置 系统配置模块用于管理动态的键值对配置项，与数据字典类似但更偏向系统级参数。支持分组管理，可通过接口动态修改，无需重启服务。模块位于 `src/modules/configuration/`，路由位于 `src/modules/configuration/config/router.py` 和 `config_item/router.py`。 ::: diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/demo-mode.md b/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/demo-mode.md index 769e2ea..a94e381 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/demo-mode.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/demo-mode.md @@ -1,3 +1,5 @@ +# 演示模式 + :::tip 演示模式 演示模式用于在线体验环境，开启后所有写操作（新增、编辑、删除等）将被拦截，返回"演示环境，暂无操作权限"提示。通过 `FLASK_DEMO` 环境变量控制。装饰器位于 `src/middleware/demo.py`。 ::: diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/dict.md b/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/dict.md index 509f168..39dfd45 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/dict.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/dict.md @@ -1,3 +1,5 @@ +# 字典模块 + :::tip 数据字典 数据字典用于管理系统中的枚举值和配置项，如状态、类型、性别等。通过字典编码统一管理，前端可通过 `useDictStore` 获取字典选项，避免硬编码。后端读取工具位于 `src/common/utils/dict_util.py`，内置进程内 TTL 缓存。 ::: diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/exception.md b/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/exception.md index 9d9bd15..db05970 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/exception.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/exception.md @@ -1,3 +1,5 @@ +# 异常与响应处理 + :::tip 全局异常与响应 项目定义了统一的响应格式和全局异常处理机制。所有 API 返回 `{code, data, msg, ok}` 标准格式，异常被捕获后也转换为相同格式。响应函数位于 `src/core/response.py`，异常类型位于 `src/core/exceptions.py`。 ::: diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/idempotent.md b/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/idempotent.md index da22070..5033a02 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/idempotent.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/idempotent.md @@ -1,3 +1,5 @@ +# 防重复提交 + :::tip 防重复提交 防重复提交是保障数据一致性的重要措施。通过前端防抖和后端唯一性校验双重保护，防止用户重复点击导致的数据重复提交。后端唯一性校验通过 WTForms 自定义校验器查询数据库实现。 ::: diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/jwt.md b/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/jwt.md index ea3a013..6492210 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/jwt.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/jwt.md @@ -1,3 +1,5 @@ +# 用户认证（JWT） + :::tip JWT认证 JWT（JSON Web Token）是项目的核心认证机制。用户登录成功后获取 Token，后续请求通过 `Authorization: Bearer <token>` 头携带 Token 进行身份验证。项目内置了 Token 生成、解析、刷新和黑名单管理功能，源码位于 `src/core/jwt.py`。 ::: diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/login-log.md b/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/login-log.md index f4edbfa..cb96142 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/login-log.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/login-log.md @@ -1,3 +1,5 @@ +# 登录日志 + :::tip 登录日志 登录日志记录每次登录尝试（成功/失败），包含登录账号、IP地址、浏览器信息、登录时间等。支持 IP 地理位置解析（ip2region）和 User-Agent 解析。登录逻辑位于 `src/modules/auth/service.py`，日志记录位于 `src/modules/login_log/service.py`。 ::: diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/operation-log.md b/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/operation-log.md index d9d212f..bc0c873 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/operation-log.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/operation-log.md @@ -1,3 +1,5 @@ +# 操作日志 + :::tip 操作日志 操作日志中间件自动拦截写请求（POST/PUT/DELETE/PATCH）并记录操作日志，无需手动埋点。日志落库通过后台线程异步执行，不阻塞响应。源码位于 `src/middleware/operation_log.py`。 ::: diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/rbac.md b/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/rbac.md index e805567..8bc9b47 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/rbac.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/rbac.md @@ -1,3 +1,5 @@ +# 权限管理（RBAC） + :::tip RBAC权限 项目采用基于角色的访问控制（RBAC）模型，通过用户-角色-菜单三层关系实现细粒度的权限管理。权限控制贯穿前后端：后端通过 `@check_permission` 装饰器校验（`src/core/permission.py`），前端通过 `v-perm` 指令控制按钮显隐。 ::: diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/transaction-decorator.md b/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/transaction-decorator.md index ef985d9..bce442e 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/transaction-decorator.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/transaction-decorator.md @@ -1,5 +1,9 @@ # 事务装饰器 +:::tip 概述 +本页讲解事务装饰器的用法，适用于中间件自动事务之外的特殊场景事务控制。 +::: + 除了 AOP 中间件自动管理事务外，项目还提供了事务装饰器，用于特殊场景下的事务控制。 ## @transactional 装饰器 diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/transaction.md b/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/transaction.md index 1706af7..a923205 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/transaction.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/transaction.md @@ -1,5 +1,9 @@ # AOP 事务管理 +:::tip 概述 +本页讲解 AOP 风格的事务管理机制——中间件自动管理数据库事务，业务代码无需手动 commit 或 rollback。 +::: + 项目采用 AOP（面向切面编程）风格的事务管理机制，通过中间件自动管理数据库事务，业务代码无需手动调用 `commit` 或 `rollback`。 ## 设计理念 diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/validator.md b/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/validator.md index 39b0c99..89ecd46 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/validator.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume4/core/validator.md @@ -1,3 +1,5 @@ +# 参数验证（Schema） + :::tip 参数验证 项目使用 WTForms 进行请求参数验证。所有请求体参数通过 WTForms 表单类定义，框架自动解析和验证 JSON 请求体，验证失败返回标准格式错误信息。BaseForm 基类位于 `src/common/forms/base_form.py`。 ::: diff --git a/DjangoAdmin_Flask_NaiveVue/zh/volume4/tools/generator.md b/DjangoAdmin_Flask_NaiveVue/zh/volume4/tools/generator.md index cde5df6..60b6716 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/volume4/tools/generator.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/volume4/tools/generator.md @@ -1,5 +1,9 @@ # 代码生成器 +:::tip 概述 +本页讲解代码生成器的用法，可根据数据库表结构一键生成前后端 CRUD 全套代码。 +::: + 代码生成器是项目的重要工具，可以根据数据库表结构一键生成前后端 CRUD 代码，包括模型、仓库、服务、路由、表单、前端 API、前端页面等全套代码。 ## 功能概述 diff --git a/DjangoAdmin_Flask_NaiveVue/zh/why.md b/DjangoAdmin_Flask_NaiveVue/zh/why.md index 8fa7c91..7fc6fd9 100644 --- a/DjangoAdmin_Flask_NaiveVue/zh/why.md +++ b/DjangoAdmin_Flask_NaiveVue/zh/why.md @@ -1,7 +1,7 @@ # 为什么选择我们？ :::tip 核心价值 -企业级数据中台不应从零搭建。本框架提供开箱即用的完整解决方案，为中大型企业构建统一的数字化基座。 +本框架提供开箱即用的企业级中台完整解决方案，免去从零搭建成本，助力中大型企业构建统一的数字化基座。 ::: ## 解决什么问题？