架构说明

总览

项目由 React 后台、React 前台、Spring Boot 服务和 MySQL 组成。开发时 Vite 分别代理 /api-backend 与 /api-web 请求；部署时两个 Nginx 站点分别提供静态页面，并将各自的接口同源转发给后端。

Turbo 管理前台、后台、后端和 VitePress 文档构建。pnpm dev 会并行启动四项开发服务。

仓库目录

路径	职责
packages/manage/	React 19、TypeScript、Semi UI 后台；动态菜单路由与权限按钮
packages/web/	React 前台站点；公开查询与参赛者工作台
packages/server/weiran-cqt/	常青藤赛事业务的五层源码
上游 weiran-framework 组件包	统一响应、异常、认证拦截、权限注解和基础契约
上游 weiran-system 组件包	登录、用户、角色、菜单、字典、系统配置和日志等通用能力
上游 weiran-region 组件包	行政区划管理与查询
packages/server/weiran-app/	可执行 Spring Boot 应用、配置和集成测试
packages/server/weiran-dependencies/	Gradle 依赖版本平台
docs/	VitePress 文档站，纳入 pnpm workspace 与 Turbo
openspec/	需求、规格、工程规则和变更记录

后端模块分层

本仓仅编译 weiran-cqt 五层，Gradle 项目名保持扁平，例如 :weiran-cqt-api，目录按模块嵌套；framework、system 和 region 的实现从上游 0.2.2 组件包引入：

packages/server/weiran-cqt/
├── weiran-cqt-api/
├── weiran-cqt-domain/
├── weiran-cqt-application/
├── weiran-cqt-infrastructure/
└── weiran-cqt-adapter/

层	主要职责
api	模块对外服务接口、命令和数据类型
domain	领域规则、实体和值对象、端口
application	编排用例，实现 API 服务
infrastructure	数据库访问、外部 SDK、配置和端口实现
adapter	HTTP Controller、请求校验和权限声明

依赖由外向内：adapter → application → domain，infrastructure → domain。领域层不依赖 Spring、数据库或供应商 SDK。新业务模块应先登记模块和资源号段，再按五层创建目录；构建会自动发现完整模块。

请求与权限

1. 登录后端返回的菜单驱动前端路由和导航。
2. 浏览器使用 HttpOnly Cookie 携带令牌；写请求附带 CSRF Token。
3. 框架认证拦截器校验身份，@RequiresPermission 检查按钮权限。
4. Controller 调用 application 服务，服务通过 domain 端口访问基础设施。
5. 后端统一返回 {code, message, data}；成功 code 为数字 0。

数据库表由各模块的 Flyway 脚本创建。已经合入的迁移脚本不修改，只追加新脚本。

配置和权威文档

• 系统配置页面由分组和表单元数据驱动，具体用法见系统配置说明。
• 本地配置放在 packages/server/config/application-local.yml，不提交到版本库。
• 部署密钥通过环境变量注入，不写入源码或日志。
• 数据库、错误码与跨接口业务约束见 packages/server/docs/01-架构与接口契约.md；HTTP 接口定义由 Springdoc 动态生成，本地 Swagger UI 地址为 /swagger-ui.html，JSON 定义地址为 /v3/api-docs（仅 local profile 开启）；部署操作见 packages/server/docs/02-部署.md；工程约束见根目录 AGENTS.md。