签入版本

EasyGoAdmin_Gin_EleVue/zh/generator/faq.md

@@ -1,67 +1,62 @@
-# 10.9 常见问题
+# 10.8 常见问题
 
-### Q: 生成的文件在哪里？
+:::tip 概述
+生成器问题多集中在"推断不符预期"与"覆盖策略"两类。核心原则：**表注释是推断的输入质量，overwrite 是手写内容的安全阀**。
+:::
 
-A: 后端文件生成到 `app/` 目录，前端文件生成到 `ui/src/` 目录。具体路径：
+## 生成内容类
 
-```text
-app/controller/{Name}Controller.php       # 控制器
-app/logic/{Name}Logic.php                 # 业务逻辑
-app/model/{Name}.php                      # 数据模型
-app/validate/{Name}Validate.php           # 验证器
-ui/src/api/{app}/{name}.ts                # API 接口
-ui/src/views/{app}/{name}/index.vue       # 列表页
-ui/src/views/{app}/{name}/edit.vue        # 编辑弹窗
-ui/src/views/{app}/{name}/detail.vue      # 详情弹窗
-ui/src/views/{app}/{name}/columns.ts      # 表格列配置（仅 ui/ 模板）
-ui/src/views/{app}/{name}/querySchemas.ts # 查询表单配置（仅 ui/ 模板）
-```
+**Q：枚举列没有生成字典和 SerializeMaps？**
 
-树形结构模块（含 `parent_id` 字段）使用 `ui2/` 模板，不生成 `columns.ts` 和 `querySchemas.ts`。
+列注释须含标准枚举形态：`1-在用 2-停用`（取值-含义，空格分隔）。改 COMMENT 后重新生成。
 
-### Q: 生成后需要手动修改吗？
+**Q：树形表生成了普通页面？**
 
-A: 通常需要。生成的是基础 CRUD 代码，复杂业务逻辑（如关联查询、钩子处理、导入导出）需要手动补充。
+确认 parent_id 列存在且注释正常（父级ID）。树形识别依赖 parent_id 列。
 
-### Q: 可以重新生成吗？
+**Q：唯一性校验没生成？**
 
-A: 可以，但会覆盖已有文件。建议先备份自定义修改。预览接口（preview）不会写入文件，可安全查看。
+UniqueFields 推断自 `uk_` 前缀唯一索引——检查表上是否建了 uk_ 索引。
 
-### Q: 树形结构表怎么生成？
+**Q：文件字段没有转正声明？**
 
-A: 表中包含 `parent_id` 字段时，生成器会自动使用 `ui2/` 树形模板。
+文件列的识别依赖列语义（列名/注释）。必要时生成后手工在 FileFields 声明中补上。
 
-### Q: 生成的权限码格式是什么？
+## 落盘与覆盖类
 
-A: 格式为 `sys:{模块名}:{操作}`，如 `sys:example:add`。
+**Q：生成后手写内容丢了？**
 
-### Q: 支持哪些数据库？
+overwrite=true 会覆盖全部产物。有手写内容的模块必须 overwrite=false（或生成前提交 git 便于回滚）。
 
-A: 支持 MySQL、PostgreSQL、SQL Server、Oracle、SQLite 五种数据库。生成器会自动检测当前配置的数据库类型。
+**Q：router.go 生成了重复声明？**
 
-### Q: 生成时报错"表名格式不合法"
+不会——声明块按模块标记幂等追加。若手工在块内加了方法，重新生成时非标准手工方法仍保留（声明块外的手写 handler 方法不受影响）。
 
-A: 表名只允许字母、数字、下划线，且不能以数字开头。检查表名是否包含特殊字符。
+**Q：菜单重复创建？**
 
-### Q: 演示环境下能用吗？
+菜单创建幂等（按名称/路径判定）。看到重复菜单时检查是否手工建过同名不同路径的菜单。
 
-A: 预览功能（preview）在演示环境下可用，实际生成（generate）会被拦截。
+## 运行类
 
-### Q: 可以用命令行生成吗？
+**Q：Web 界面 404？**
 
-A: 可以。使用 `php think generate:code <表名>` 命令行生成。CLI 不受演示环境限制，也不需要权限配置。详见 [10.2 CLI 命令行使用](/zh/generator/cli.html)。
+`generator.enable=false` 时生成器路由整体不注册。确认配置后重启。
 
-### Q: CLI 命令和 Web 端有什么区别？
+**Q：生产环境能打开生成器？**
 
-A: 底层引擎完全相同，区别在于操作方式：
-- CLI 适合开发环境、批量操作、CI/CD 集成
-- Web 端适合日常开发、可视化配置
-- CLI 不受权限和演示模式限制
-- CLI 支持 `--output` 导出配置、`--config` 从配置生成
+不正常。生产必须 enable=false；app.prod=true 时启动校验会直接拒绝这种组合。
 
-### Q: 如何批量生成多张表？
+**Q：CLI 报数据库连接失败？**
 
-A: Web 端可多选表后点击批量生成。CLI 使用 `--batch` 选项：
-```bash
-php think generate:code table1,table2,table3 --batch
-```
+生成器需要连库内省。检查 database 配置；它不依赖 Redis（仅内省）。
+
+## 效率建议
+
+- 建表评审时就按生成器的推断输入（注释/索引/列名）把关——源头质量决定产物质量
+- 团队统一 overwrite 策略，避免"我这边覆盖了你那边跳过"的协作事故
+- 模板定制走 preview 快速迭代，确认后再落盘
+
+## 相关
+
+- [10.4 表结构解析与渲染引擎](/zh/generator/code-engine.html)
+- [10.6 配置与覆盖策略](/zh/generator/config.html)