flycms-dev

# FlyCms 开发总纲 目标是让每次改动都长得像这个项目已有的代码，而不是像通用教程。细节 SOP 和决策记录在 references/ 里，先按需读： - 新增后端模块/接口/管理页面 → 读 `references/backend-conventions.md`（含可直接套用的代码模板） - 想引入新框架、改架构、或发现代码"不顺眼"想顺手重构 → 先读 `references/tech-debt.md`（技术债台账 + 已定的架构决策，多数"顺手改进"已被明确否决过） - 前端登录/菜单/权限/按钮控制 → 触发 `flycms-frontend-access` skill，完整手册在 `docs/frontend-access-guide.md` ## 项目一张图 ``` FlyCms/ ├── backend/ Spring Boot 4.1.1 / JDK 25 / MyBatis(XML) / Freemarker / Ehcache / MySQL，端口 80 │ └── src/main/java/com/flycms/ │ ├── module/<域>/{dao,model,service}/ # 业务三层，DAO 接口与 XML 同目录 │ ├── web/front|system/ # 前台页面 / 管理后台（Freemarker 渲染） │ ├── web/api/ # 给 vben 前端的 REST（/api/**，DataVo） │ ├── interceptor/ # AdminInterceptor（/system/** URL 权限）、UserInterceptor │ ├── core/{base,controller,entity,utils}/ │ └── config/ # WebMvcConfig(拦截器注册)、CorsConfig、Druid… ├── frontend/ vue-vben-admin v5 pnpm monorepo；主力应用 apps/web-antd，dev 端口 5666 └── docs/frontend-access-guide.md # 前后端权限对接手册（唯一信息源） ``` ## 铁律（每条都有原因，违反即返工） 1. **DAO XML 统一放 `src/main/resources/mapper/`**（2026-09-29 G26 归位后的现行约定；文件名用 `模块__XxxDao.xml` 平铺）。`application.yml` 的 `mapper-locations` 扫 `classpath:mapper/**/*.xml`；`pom.xml` 已不再把 `src/main/java` 当资源目录——新 Mapper XML 放回 java 目录会静默不打包，启动报绑定失败。 2. **Controller 归位**：前台页面 → `web/front`；管理后台页面（含 Freemarker 渲染 + 局部 @ResponseBody）→ `web/system`，视图一律 `theme.getAdminTemplate("admin/xxx")` 返回；给 vben 前端的新 REST → `web/api`，路径 `/api/**`，返回 `DataVo`。不要在老 controller 里继续堆纯 JSON 端点。 3. **响应与分页**：JSON 一律 `DataVo`（成功 `DataVo.success(message, data)` 两参重载——单参重载有 message/data 分派陷阱）；分页一律 `PageVo<T>`（service 里 `new PageVo<>(pageNum)`、`setRows`、`setList(dao.getXxx(pageVo.getOffset(), pageVo.getRows()))`、`setCount(dao.countXxx())`，XML 里手写 `limit #{offset}, #{rows}`）。 4. **ID 与表**：主键 `SnowFlake.nextId()`（`core/utils/SnowFlake.java`），表名 `fly_` 前缀、bigint 主键。SQL 全部走 DAO XML 的 `#{}` 预编译，禁止字符串拼接。 5. **校验与密码**：入参用 jakarta validation 注解 + `@Valid ... BindingResult` 逐条 `DataVo.failure(error.getDefaultMessage())`；密码存取只经 `BCryptUtils`；登录失败锁定逻辑（attempts）沿用 AdminService 现状，不要另造。 6. **权限闭环**：`/system/**` 下的新端点自动被 AdminInterceptor 按 URL 权限拦截——**上线前必须** `GET /system/admin/permission_sync` 注册 action_key 并在角色组勾选，否则所有人 403；`/api/**` 不在拦截范围，端点内必须自查 session 并对未登录抛 HTTP 401（vben 只认 401）。 7. **依赖卫生**：新代码用 commons-lang3 / commons-io 等现代坐标；`org.apache.commons.lang`（2.x）只出现在遗留代码里，不要模仿。 ## 改完怎么验证（本项目无自动化测试，验证 = 编译 + 冒烟） 1. 后端：`cd backend && mvn -q compile` 过了再谈下一步；涉及启动行为的，`mvn spring-boot:run` 起服务后按"登录 → 菜单 → 目标页面/接口"冒烟。 2. 前端：`cd frontend && pnpm dev:antd` 起开发服（5666），改动涉及类型的跑 `pnpm check:type`；涉及登录/权限的按手册 §3 验收。 3. 数据库变更：在 `doc/` 下同步维护 SQL 变更说明，保持 `doc/flycms_date.sql` 是可建库的完整基线。 ## 禁止事项（防腐化边界） - 不引入新框架/新 ORM/新安全框架（Shiro、Spring Security、MyBatis-Plus、JWT…）。现行选型及理由见 `references/tech-debt.md` 的决策记录；确有必要，先在对话中提出权衡再动。 - 不改 `DataVo` 字段语义、拦截器路径规则、`/api` 代理契约——前端手册与 skill 都建立在这些契约上。 - 不做"顺手大重构"。发现坏味道记入 tech-debt 台账，单独立任务处理。 - 提交信息沿用仓库惯例：中文一行式动词开头（如"修复表名BUG"）。