# AGENTS.md

## 项目概览
`xiaohh-generator` 是基于 Spring Boot 4.0.8 + Java 21 的**数据库表代码生成器**：从 MySQL `information_schema` 导入表结构，用 FreeMarker 模板生成 Controller/Entity/Service/ServiceImpl/Mapper/Mapper.xml，前端为 Thymeleaf（端口 8888）。

## 构建与运行
- 项目要求 Java 21、Maven（无 Maven Wrapper，使用本机 `mvn`）。
- 命令：启动 `mvn spring-boot:run`（默认 `dev` profile，端口 8888）；打包 `mvn clean package` → `target/xiaohh-generator.jar`；测试 `mvn test`；单测 `mvn -Dtest=ClassName#method test`。
- 运行前需本地 MySQL（`application-dev.yaml` 硬编码 `127.0.0.1:3306`、`root/xiaohh1234`），并先执行 `sql/xiaohh_generator.sql` 建库建表。

## 代码生成流水线（最不直观）
1. 导入表：`GenTableController#importTable` → `GenTableServiceImpl#importGenTable`，从 `information_schema` 读表/列写 `gen_table`、`gen_column`。
2. 生成：`generateCodeList(tableId)` 遍历 `classpath:config/generator-file.json` 清单，用 `code-template/*.ftl` 渲染 `GenTable`。
3. **两种占位符别混淆**：
   - FreeMarker 用 `${...}`，只渲染模板内容。
   - 文件名/路径中的 `{{packageName}}`、`{{moduleName}}`、`{{className}}`、`{{businessName}}`、`{{businessName?kebabCase}}` 由 Spring 事件监听器 `GenCodeFileEventListener` 回调替换，**不经过 FreeMarker**。新增占位符要同时改 `generator-file.json` 和该监听器。
4. 下载 `/gen/table/{downloadType}/{tableIds}`（1=tar.gz，2=zip）；预览 `/gen/table/preview/{tableId}`。

## 配置（`src/main/resources/config/`）
- `generator-file.json`：生成文件清单（文件名/路径/模板），新增生成类型改这里。
- `database-type-mapping.json`：MySQL 类型 → Java 类型（默认项 `default:true`）+ 表单控件类型。
- `table-prefix-to-module.json`：表前缀 → 模块名（如 `sys` → `system`）；表名不匹配 `^[a-z]+(_[a-z]+)+$` 且无映射时模块名/业务名为 `unknown`。
- 三个 JSON 每次调用从 classpath 重读，无缓存。

## 模板与生成代码约束
- `code-template/*.ftl` 生成的是**下游 xiaohh 框架**代码，引用本仓库不存在的包（`work.xiaohh.common.core`、`work.xiaohh.common.excel` 等）；`controller.ftl` 用的 `conditionEffectRows` 在本仓库 `BaseController` 里叫 `condition`。改模板时不要假设生成结果能在本仓库编译。
- 模板可用计算属性来自实体 getter（`GenColumn.operationType` 位掩码：增=8、删=4、查=2、改=1）：`insertableColumns`/`deletableColumns`/`selectableColumns`/`updatableColumns`/`visibleColumns`、`kebabCaseBusinessName`。改模板字段前先看 `GenTable`/`GenColumn`。

## 代码约定
- Java 21，大量 `var`；构造器注入，`final` 字段且字段声明在构造器**之后**。
- 每个类/方法/字段写中文 Javadoc（含 `@author XiaoHH`、`@version 1.0.0`）。
- 无 lint/format/checkstyle 配置，勿引入新工具链。
- Mapper 接口标 `@Mapper`，XML 位于 `resources/mapper/generator/`。

## Docker
`docker/Dockerfile` 从构建上下文 `docker/` 复制 `java/xiaohh-generator.jar`；发布前把 `target/xiaohh-generator.jar` 放到 `docker/java/`（`finalName=xiaohh-generator`）。