@llryiop/avatar-boot-cli 1.0.1 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (66) hide show
  1. package/docs/exam-question-generate-api.md +163 -0
  2. package/package.json +1 -1
  3. package/src/prompts.js +3 -3
  4. package/src/transform.js +1 -1
  5. package/templates/.claude/skills/avatar-boot-starter-feign/README.md +243 -0
  6. package/templates/.claude/skills/avatar-boot-starter-feign/SKILL.md +47 -219
  7. package/templates/.claude/skills/avatar-boot-starter-feign/references//345/212/237/350/203/275/350/257/246/350/247/243.md +65 -0
  8. package/templates/.claude/skills/avatar-boot-starter-feign/references//345/277/253/351/200/237/346/216/245/345/205/245/346/214/207/345/215/227.md +75 -0
  9. package/templates/.claude/skills/avatar-boot-starter-feign/references//351/205/215/347/275/256/345/217/202/350/200/203.md +70 -0
  10. package/templates/.claude/skills/avatar-boot-starter-job/README.md +437 -0
  11. package/templates/.claude/skills/avatar-boot-starter-job/SKILL.md +35 -414
  12. package/templates/.claude/skills/avatar-boot-starter-job/references//345/270/270/350/247/201/351/227/256/351/242/230.md +55 -0
  13. package/templates/.claude/skills/avatar-boot-starter-job/references//345/277/253/351/200/237/346/216/245/345/205/245/344/270/216/351/205/215/347/275/256.md +124 -0
  14. package/templates/.claude/skills/avatar-boot-starter-job/references//347/233/221/346/216/247/346/214/207/346/240/207.md +72 -0
  15. package/templates/.claude/skills/avatar-boot-starter-kafka/README.md +580 -0
  16. package/templates/.claude/skills/avatar-boot-starter-kafka/SKILL.md +36 -560
  17. package/templates/.claude/skills/avatar-boot-starter-kafka/references//346/234/200/344/275/263/345/256/236/350/267/265.md +43 -0
  18. package/templates/.claude/skills/avatar-boot-starter-kafka/references//346/240/270/345/277/203/345/212/237/350/203/275.md +117 -0
  19. package/templates/.claude/skills/avatar-boot-starter-kafka/references//351/205/215/347/275/256/345/217/202/350/200/203.md +54 -0
  20. package/templates/.claude/skills/avatar-boot-starter-mysql/README.md +572 -0
  21. package/templates/.claude/skills/avatar-boot-starter-mysql/SKILL.md +40 -550
  22. package/templates/.claude/skills/avatar-boot-starter-mysql/references//345/256/236/344/275/223/344/270/216/345/212/237/350/203/275.md +96 -0
  23. package/templates/.claude/skills/avatar-boot-starter-mysql/references//345/277/253/351/200/237/346/216/245/345/205/245/344/270/216/346/225/260/346/215/256/346/272/220.md +91 -0
  24. package/templates/.claude/skills/avatar-boot-starter-mysql/references//351/253/230/347/272/247/347/211/271/346/200/247/344/270/216/351/205/215/347/275/256.md +59 -0
  25. package/templates/.claude/skills/avatar-boot-starter-nacos/README.md +901 -0
  26. package/templates/.claude/skills/avatar-boot-starter-nacos/SKILL.md +40 -879
  27. package/templates/.claude/skills/avatar-boot-starter-nacos/references//345/212/237/350/203/275/344/275/277/347/224/250.md +134 -0
  28. package/templates/.claude/skills/avatar-boot-starter-nacos/references//345/277/253/351/200/237/346/216/245/345/205/245/344/270/216/351/205/215/347/275/256.md +96 -0
  29. package/templates/.claude/skills/avatar-boot-starter-nacos/references//346/225/205/351/232/234/346/216/222/346/237/245.md +64 -0
  30. package/templates/.claude/skills/avatar-boot-starter-oss/README.md +594 -0
  31. package/templates/.claude/skills/avatar-boot-starter-oss/SKILL.md +52 -570
  32. package/templates/.claude/skills/avatar-boot-starter-oss/references//345/277/253/351/200/237/346/216/245/345/205/245/344/270/216/351/205/215/347/275/256.md +77 -0
  33. package/templates/.claude/skills/avatar-boot-starter-oss/references//346/240/270/345/277/203/345/212/237/350/203/275.md +94 -0
  34. package/templates/.claude/skills/avatar-boot-starter-oss/references//350/247/204/350/214/203/344/270/216/346/263/250/346/204/217/344/272/213/351/241/271.md +61 -0
  35. package/templates/.claude/skills/avatar-boot-starter-redis/README.md +586 -0
  36. package/templates/.claude/skills/avatar-boot-starter-redis/SKILL.md +42 -566
  37. package/templates/.claude/skills/avatar-boot-starter-redis/references//345/277/253/351/200/237/346/216/245/345/205/245/344/270/216/351/205/215/347/275/256.md +78 -0
  38. package/templates/.claude/skills/avatar-boot-starter-redis/references//346/225/260/346/215/256/346/223/215/344/275/234.md +111 -0
  39. package/templates/.claude/skills/avatar-boot-starter-redis/references//351/253/230/347/272/247/345/212/237/350/203/275.md +90 -0
  40. package/templates/.claude/skills/avatar-boot-starter-rocketmq/README.md +662 -0
  41. package/templates/.claude/skills/avatar-boot-starter-rocketmq/SKILL.md +48 -640
  42. package/templates/.claude/skills/avatar-boot-starter-rocketmq/references//346/240/270/345/277/203/345/212/237/350/203/275.md +101 -0
  43. package/templates/.claude/skills/avatar-boot-starter-rocketmq/references//351/205/215/347/275/256/344/270/216/346/263/250/346/204/217/344/272/213/351/241/271.md +44 -0
  44. package/templates/.claude/skills/avatar-boot-starter-rocketmq/references//351/253/230/347/272/247/347/211/271/346/200/247.md +71 -0
  45. package/templates/.claude/skills/avatar-boot-starter-web/README.md +1007 -0
  46. package/templates/.claude/skills/avatar-boot-starter-web/SKILL.md +150 -1003
  47. package/templates/.claude/skills/avatar-boot-starter-web/references//345/212/237/350/203/275-LogInfo/346/263/250/350/247/243.md +75 -0
  48. package/templates/.claude/skills/avatar-boot-starter-web/references//345/212/237/350/203/275-/345/205/250/345/261/200/345/274/202/345/270/270/345/244/204/347/220/206.md +90 -0
  49. package/templates/.claude/skills/avatar-boot-starter-web/references//345/212/237/350/203/275-/346/214/207/346/240/207/347/233/221/346/216/247.md +74 -0
  50. package/templates/.claude/skills/avatar-boot-starter-web/references//345/212/237/350/203/275-/346/227/245/345/277/227/344/275/223/347/263/273.md +73 -0
  51. package/templates/.claude/skills/avatar-boot-starter-web/references//345/212/237/350/203/275-/350/257/267/346/261/202/344/270/212/344/270/213/346/226/207.md +77 -0
  52. package/templates/.claude/skills/avatar-boot-starter-web/references//345/277/253/351/200/237/346/216/245/345/205/245/346/214/207/345/215/227.md +52 -0
  53. package/templates/.claude/skills/avatar-boot-starter-web/references//346/263/250/346/204/217/344/272/213/351/241/271.md +68 -0
  54. package/templates/.claude/skills/avatar-boot-starter-web/references//350/207/252/345/256/232/344/271/211/346/211/251/345/261/225/346/214/207/345/215/227.md +107 -0
  55. package/templates/.claude/skills/avatar-boot-starter-web/references//351/205/215/347/275/256/345/217/202/350/200/203.md +107 -0
  56. package/templates/.claude/skills/crud-generator/SKILL.md +133 -64
  57. package/templates/.claude/skills/database-design/README.md +207 -0
  58. package/templates/.claude/skills/database-design/SKILL.md +469 -82
  59. package/templates/.claude/skills/database-design/references//345/221/275/345/220/215/350/247/204/350/214/203.md +232 -0
  60. package/templates/.claude/skills/database-design/references//345/255/227/346/256/265/347/261/273/345/236/213/350/247/204/350/214/203.md +400 -0
  61. package/templates/.claude/skills/database-design/references//347/264/242/345/274/225/350/247/204/350/214/203.md +506 -0
  62. package/templates/avatar-scaffold-api/pom.xml +0 -5
  63. package/templates/avatar-scaffold-service/pom.xml +25 -87
  64. package/templates/avatar-scaffold-service/src/main/resources/application-dev.yaml +3 -5
  65. package/templates/avatar-scaffold-service/src/main/resources/application-local.yaml +2 -2
  66. package/templates/pom.xml +9 -18
@@ -0,0 +1,232 @@
1
+ # MySQL 命名规范
2
+
3
+ ## 一、核心原则
4
+
5
+ **命名格式**:`{部门缩写}_{业务域}_{实体名}`
6
+
7
+ 通过名称可立即识别:**哪个部门** → **哪个业务** → **什么实体**
8
+
9
+ ---
10
+
11
+ ## 二、部门缩写对照表
12
+
13
+ | 团队 | 缩写 | 示例数据库/表前缀 |
14
+ |------|------|-----------------|
15
+ | 讯飞智作 | `zz` | `zz_` |
16
+ | 交互平台 | `jh` | `jh_` |
17
+ | 资产平台 | `zc` | `zc_` |
18
+ | 大模型 | `dm` | `dm_` |
19
+
20
+ > 新增部门需在此表登记缩写,避免冲突。
21
+
22
+ | 团队 | 业务 | 缩写 | 示例数据库/表前缀 |
23
+ |------|------|------|-----------------|
24
+ | 讯飞智作 | 智作平台 | `plt` | `zz_plt_` |
25
+
26
+ ---
27
+
28
+ ## 三、表命名规范
29
+
30
+ ### 格式
31
+
32
+ `{部门缩写}_{业务域}_{实体名}`
33
+
34
+ ### 示例
35
+
36
+ ```
37
+ zz_plt_role -- 智作平台-角色表
38
+ zz_plt_user -- 智作平台-用户表
39
+ zz_plt_media_platform -- 智作平台-媒体信息平台
40
+ jh_usr_account -- 交互平台-用户账号
41
+ ```
42
+
43
+ ### 规则
44
+
45
+ - 全小写,单词间用下划线 `_` 分隔
46
+ - 长度不超过 32 个字符
47
+ - 禁止使用 MySQL 保留字
48
+ - 表名能清晰表达实体含义,使用名词
49
+ - 关联表/中间表:`{表A}_{表B}_rel` 或 `{表A}_{表B}_map`
50
+ - 历史归档表:`{原表名}_history` 或 `{原表名}_archive`
51
+ - 临时表:`{原表名}_tmp`(用完即删)
52
+ - 长度不超过 64 个字符
53
+ - **Spring 实体类不需要前缀**,直接使用后面的表名作为实体类即可
54
+
55
+ ### Spring 实体类映射
56
+
57
+ | 表名 | 实体类名 |
58
+ |------|---------|
59
+ | `zz_plt_role` | `Role` |
60
+ | `zz_plt_user` | `User` |
61
+ | `zz_plt_media_platform` | `MediaPlatform` |
62
+
63
+ ---
64
+
65
+ ## 四、字段命名规范
66
+
67
+ ### 规则
68
+
69
+ - 全小写,单词间用下划线 `_` 分隔
70
+ - 布尔类型字段以 `is_` 开头,如 `is_deleted`、`is_enabled`
71
+ - 时间字段以 `_at` 或 `_time` 结尾,如 `created_at`、`expire_time`
72
+ - 外键字段以 `_id` 结尾,如 `user_id`、`role_id`
73
+ - 禁止使用 MySQL 保留字作为字段名(如 `order`、`status` 需加前缀)
74
+
75
+ ### 常用字段命名
76
+
77
+ | 字段类型 | 命名格式 | 示例 |
78
+ |---------|--------------------------|------|
79
+ | 主键 | `id` | `id` |
80
+ | 编码 | `{entity}_code` | `role_code`, `user_code` |
81
+ | 名称 | `{entity}_name` | `role_name`, `user_name` |
82
+ | 描述 | `description` | `description` |
83
+ | 备注 | `remark` | `remark` |
84
+ | 状态 | `status` | `status` |
85
+ | 类型 | `type` 或 `{entity}_type` | `type`, `avatar_type` |
86
+ | 排序 | `sort_order` | `sort_order` |
87
+ | 启用标记 | `is_enabled` | `is_enabled` |
88
+ | 删除标记 | `is_deleted` | `is_deleted` |
89
+ | 创建时间 | `create_time` | `create_time` |
90
+ | 更新时间 | `update_time` | `update_time` |
91
+ | 创建人 | `created_by` | `created_by` |
92
+ | 更新人 | `updated_by` | `updated_by` |
93
+ | 外键 | `{entity}_id` | `user_id`, `role_id` |
94
+ | 租户ID | `tenant_id` | `tenant_id` |
95
+
96
+ ---
97
+
98
+ ## 五、索引命名规范
99
+
100
+ | 类型 | 格式 | 示例 |
101
+ |------|------|------|
102
+ | 主键 | `pk_{表名}` | `pk_zz_plt_role` |
103
+ | 唯一索引 | `uk_{表名}_{字段}` | `uk_zz_plt_role_code` |
104
+ | 普通索引 | `idx_{表名}_{字段}` | `idx_zz_plt_role_name` |
105
+ | 联合索引 | `idx_{表名}_{字段1}_{字段2}` | `idx_zz_plt_role_status_enabled` |
106
+ | 全文索引 | `ft_{表名}_{字段}` | `ft_zz_plt_article_title` |
107
+
108
+ ### 注意事项
109
+
110
+ - 主键索引由 MySQL 自动创建,无需在 CREATE TABLE 中显式声明 `pk_{表名}`
111
+ - 索引名称要能清晰表达索引的用途
112
+ - 联合索引按照最左前缀原则排列字段顺序
113
+
114
+ ---
115
+
116
+ ## 六、关联表命名规范
117
+
118
+ ### 格式
119
+
120
+ `{表A}_{表B}_rel` 或 `{表A}_{表B}_map`
121
+
122
+ ### 示例
123
+
124
+ ```sql
125
+ -- 虚拟人与角色关联表
126
+ zz_plt_avatar_role_rel
127
+
128
+ -- 用户与权限映射表
129
+ zz_plt_user_permission_map
130
+ ```
131
+
132
+ ### 规则
133
+
134
+ - 使用 `_rel` 后缀表示关联关系
135
+ - 使用 `_map` 后缀表示映射关系
136
+ - 表名中的两个实体按字母顺序排列(可选,但建议保持一致)
137
+
138
+ ---
139
+
140
+ ## 七、特殊表命名
141
+
142
+ ### 历史归档表
143
+
144
+ ```
145
+ zz_plt_role_history -- 角色历史表
146
+ zz_plt_user_archive -- 用户归档表
147
+ ```
148
+
149
+ ### 临时表
150
+
151
+ ```
152
+ zz_plt_role_tmp -- 角色临时表(用完即删)
153
+ ```
154
+
155
+ ### 分表
156
+
157
+ ```
158
+ zz_plt_order_0000
159
+ zz_plt_order_0001
160
+ ...
161
+ zz_plt_order_0063 -- 64 张分表
162
+ ```
163
+
164
+ ---
165
+
166
+ ## 八、命名禁忌
167
+
168
+ ### 禁止使用的命名
169
+
170
+ - ❌ 使用 MySQL 保留字(如 `order`、`group`、`select`)
171
+ - ❌ 使用中文拼音(如 `yonghu`、`jiaose`)
172
+ - ❌ 使用缩写不明确的名称(如 `usr_acc_info`)
173
+ - ❌ 使用驼峰命名(如 `userName`、`roleCode`)
174
+ - ❌ 使用大写字母(如 `USER_NAME`、`ROLE_CODE`)
175
+
176
+ ### 正确的命名
177
+
178
+ - ✅ 使用英文单词(如 `user`、`role`)
179
+ - ✅ 使用下划线分隔(如 `user_name`、`role_code`)
180
+ - ✅ 使用全小写(如 `created_at`、`is_deleted`)
181
+ - ✅ 使用清晰的缩写(如 `desc` → `description`)
182
+
183
+ ---
184
+
185
+ ## 九、命名一致性
186
+
187
+ ### 同一概念使用相同命名
188
+
189
+ | 概念 | 统一命名 | 禁止使用 |
190
+ |------|---------|------------------------------|
191
+ | 创建时间 | `create_time` | `created_at`, `gmt_create` |
192
+ | 更新时间 | `update_time` | `updated_at`, `gmt_modified` |
193
+ | 删除标记 | `is_deleted` | `deleted`, `del_flag` |
194
+ | 启用标记 | `is_enabled` | `enabled`, `status` |
195
+ | 排序权重 | `sort_order` | `sort`, `order_num` |
196
+
197
+ ### 外键命名一致性
198
+
199
+ ```sql
200
+ -- 用户表
201
+ CREATE TABLE `zz_plt_user` (
202
+ `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
203
+ ...
204
+ );
205
+
206
+ -- 订单表(引用用户)
207
+ CREATE TABLE `zz_plt_order` (
208
+ `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
209
+ `user_id` BIGINT UNSIGNED NOT NULL COMMENT '用户ID', -- 外键字段名与主表主键对应
210
+ ...
211
+ );
212
+ ```
213
+
214
+ ---
215
+
216
+ ## 十、命名检查清单
217
+
218
+ 创建表前,请检查以下项目:
219
+
220
+ - [ ] 表名是否符合 `{部门}_{业务域}_{实体}` 格式
221
+ - [ ] 表名是否全小写,使用下划线分隔
222
+ - [ ] 字段名是否全小写,使用下划线分隔
223
+ - [ ] 布尔字段是否以 `is_` 开头
224
+ - [ ] 时间字段是否以 `_time` 结尾
225
+ - [ ] 外键字段是否以 `_id` 结尾
226
+ - [ ] 索引名称是否符合规范
227
+ - [ ] 是否避免使用 MySQL 保留字
228
+ - [ ] 命名是否清晰、一致、易理解
229
+
230
+ ---
231
+
232
+ **参考文档**:[MySQL 数据库规范](../../../database/mysql-specification.md)
@@ -0,0 +1,400 @@
1
+ # MySQL 字段类型规范
2
+
3
+ ## 一、数据类型选择指南
4
+
5
+ | 场景 | 推荐类型 | 禁止类型 | 说明 |
6
+ |------|---------|---------|------|
7
+ | 主键 | `BIGINT UNSIGNED AUTO_INCREMENT` | `INT`、`UUID` | 避免溢出,UUID 影响写性能 |
8
+ | 外键 | `BIGINT UNSIGNED` | `INT` | 与主键类型保持一致 |
9
+ | 字符串(短) | `VARCHAR(n)` | `CHAR`(变长场景) | 按实际最大长度设置 |
10
+ | 字符串(长文本) | `TEXT` / `MEDIUMTEXT` | `LONGTEXT`(非必要) | 超过 1000 字符用 TEXT |
11
+ | 时间 | `DATETIME` | `TIMESTAMP` | TIMESTAMP 有 2038 年问题 |
12
+ | 布尔 | `TINYINT(1)` | `BOOLEAN`、`BIT` | 0/1 语义清晰 |
13
+ | 金额 | `DECIMAL(18,4)` | `FLOAT`、`DOUBLE` | 浮点数有精度丢失 |
14
+ | 枚举 | `TINYINT` + 注释说明 | `ENUM` | ENUM 修改成本高 |
15
+ | JSON | `JSON` | `TEXT` 存 JSON | MySQL 8.0 原生 JSON 类型 |
16
+ | IP 地址 | `VARCHAR(45)` | `INT` | 兼容 IPv6 |
17
+
18
+ ---
19
+
20
+ ## 二、VARCHAR 长度参考
21
+
22
+ | 字段类型 | 建议长度 | 说明 |
23
+ |---------|---------|------|
24
+ | 用户名 | `VARCHAR(64)` | 一般用户名不超过 32 个字符 |
25
+ | 邮箱 | `VARCHAR(128)` | 标准邮箱格式 |
26
+ | 手机号 | `VARCHAR(20)` | 支持国际号码格式 |
27
+ | URL | `VARCHAR(512)` | 一般 URL 长度 |
28
+ | 编码/Code | `VARCHAR(64)` | 业务编码字段 |
29
+ | 名称/Name | `VARCHAR(128)` | 一般名称字段 |
30
+ | 描述/Description | `VARCHAR(512)` | 简短描述 |
31
+ | 备注/Remark | `VARCHAR(1024)` | 较长备注信息 |
32
+ | 标题/Title | `VARCHAR(256)` | 文章标题等 |
33
+ | 地址/Address | `VARCHAR(256)` | 详细地址 |
34
+
35
+ ---
36
+
37
+ ## 三、常用字段类型模板
38
+
39
+ ### 基础字段
40
+
41
+ ```sql
42
+ -- 主键(必须)
43
+ `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '主键ID',
44
+
45
+ -- 创建时间(必须)
46
+ `create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
47
+
48
+ -- 更新时间(必须)
49
+ `update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
50
+
51
+ -- 逻辑删除(必须)
52
+ `is_deleted` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '逻辑删除:0-未删除,1-已删除',
53
+ ```
54
+
55
+ ### 审计字段(可选)
56
+
57
+ ```sql
58
+ -- 创建人
59
+ `created_by` BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT '创建人ID',
60
+
61
+ -- 更新人
62
+ `updated_by` BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT '更新人ID',
63
+ ```
64
+
65
+ ### 业务字段
66
+
67
+ ```sql
68
+ -- 编码字段
69
+ `{entity}_code` VARCHAR(64) NOT NULL COMMENT '{实体}编码',
70
+
71
+ -- 名称字段
72
+ `{entity}_name` VARCHAR(128) NOT NULL COMMENT '{实体}名称',
73
+
74
+ -- 描述字段
75
+ `description` VARCHAR(512) DEFAULT NULL COMMENT '描述',
76
+
77
+ -- 备注字段
78
+ `remark` VARCHAR(1024) DEFAULT NULL COMMENT '备注',
79
+
80
+ -- 启用状态
81
+ `is_enabled` TINYINT(1) NOT NULL DEFAULT 1 COMMENT '是否启用:0-禁用,1-启用',
82
+
83
+ -- 排序权重
84
+ `sort_order` INT NOT NULL DEFAULT 0 COMMENT '排序权重',
85
+
86
+ -- 状态字段
87
+ `status` TINYINT NOT NULL DEFAULT 0 COMMENT '状态:0-待审核,1-已通过,2-已拒绝',
88
+
89
+ -- 类型字段
90
+ `type` TINYINT NOT NULL DEFAULT 1 COMMENT '类型:1-类型A,2-类型B',
91
+
92
+ -- 租户ID(多租户场景)
93
+ `tenant_id` BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT '租户ID',
94
+
95
+ -- 外键字段
96
+ `user_id` BIGINT UNSIGNED NOT NULL COMMENT '用户ID',
97
+ `role_id` BIGINT UNSIGNED NOT NULL COMMENT '角色ID',
98
+
99
+ -- URL字段
100
+ `url` VARCHAR(512) DEFAULT NULL COMMENT 'URL地址',
101
+ `image_url` VARCHAR(512) DEFAULT NULL COMMENT '图片URL',
102
+ `video_url` VARCHAR(512) DEFAULT NULL COMMENT '视频URL',
103
+
104
+ -- JSON配置
105
+ `config_json` JSON DEFAULT NULL COMMENT '扩展配置(JSON格式)',
106
+ `extra_json` JSON DEFAULT NULL COMMENT '额外信息(JSON格式)',
107
+
108
+ -- 金额字段
109
+ `amount` DECIMAL(18,4) NOT NULL DEFAULT 0.0000 COMMENT '金额',
110
+ `price` DECIMAL(18,4) NOT NULL DEFAULT 0.0000 COMMENT '价格',
111
+
112
+ -- 数量字段
113
+ `quantity` INT NOT NULL DEFAULT 0 COMMENT '数量',
114
+ `stock` INT NOT NULL DEFAULT 0 COMMENT '库存',
115
+
116
+ -- 时间字段
117
+ `start_time` DATETIME DEFAULT NULL COMMENT '开始时间',
118
+ `end_time` DATETIME DEFAULT NULL COMMENT '结束时间',
119
+ `expire_time` DATETIME DEFAULT NULL COMMENT '过期时间',
120
+ `publish_time` DATETIME DEFAULT NULL COMMENT '发布时间',
121
+ ```
122
+
123
+ ---
124
+
125
+ ## 四、特殊场景字段
126
+
127
+ ### 树形结构
128
+
129
+ ```sql
130
+ -- 父节点ID
131
+ `parent_id` BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT '父节点ID',
132
+
133
+ -- 层级
134
+ `level` INT NOT NULL DEFAULT 0 COMMENT '层级',
135
+
136
+ -- 路径
137
+ `path` VARCHAR(512) DEFAULT NULL COMMENT '路径(如:/1/2/3/)',
138
+
139
+ -- 是否叶子节点
140
+ `is_leaf` TINYINT(1) NOT NULL DEFAULT 1 COMMENT '是否叶子节点:0-否,1-是',
141
+ ```
142
+
143
+ ### 版本控制
144
+
145
+ ```sql
146
+ -- 版本号
147
+ `version` INT NOT NULL DEFAULT 0 COMMENT '版本号(乐观锁)',
148
+
149
+ -- 版本标识
150
+ `version_tag` VARCHAR(64) DEFAULT NULL COMMENT '版本标识(如:v1.0.0)',
151
+ ```
152
+
153
+ ### 软删除增强
154
+
155
+ ```sql
156
+ -- 删除时间
157
+ `deleted_at` DATETIME DEFAULT NULL COMMENT '删除时间',
158
+
159
+ -- 删除人
160
+ `deleted_by` BIGINT UNSIGNED DEFAULT NULL COMMENT '删除人ID',
161
+ ```
162
+
163
+ ### 审批流程
164
+
165
+ ```sql
166
+ -- 审批状态
167
+ `approval_status` TINYINT NOT NULL DEFAULT 0 COMMENT '审批状态:0-待审批,1-已通过,2-已拒绝',
168
+
169
+ -- 审批人
170
+ `approver_id` BIGINT UNSIGNED DEFAULT NULL COMMENT '审批人ID',
171
+
172
+ -- 审批时间
173
+ `approval_time` DATETIME DEFAULT NULL COMMENT '审批时间',
174
+
175
+ -- 审批意见
176
+ `approval_remark` VARCHAR(512) DEFAULT NULL COMMENT '审批意见',
177
+ ```
178
+
179
+ ### 地理位置
180
+
181
+ ```sql
182
+ -- 经度
183
+ `longitude` DECIMAL(10,6) DEFAULT NULL COMMENT '经度',
184
+
185
+ -- 纬度
186
+ `latitude` DECIMAL(10,6) DEFAULT NULL COMMENT '纬度',
187
+
188
+ -- 地址
189
+ `address` VARCHAR(256) DEFAULT NULL COMMENT '详细地址',
190
+
191
+ -- 省份
192
+ `province` VARCHAR(64) DEFAULT NULL COMMENT '省份',
193
+
194
+ -- 城市
195
+ `city` VARCHAR(64) DEFAULT NULL COMMENT '城市',
196
+
197
+ -- 区县
198
+ `district` VARCHAR(64) DEFAULT NULL COMMENT '区县',
199
+ ```
200
+
201
+ ---
202
+
203
+ ## 五、禁止使用的类型
204
+
205
+ ### 严格禁止
206
+
207
+ ```sql
208
+ -- ❌ FLOAT/DOUBLE(精度问题)
209
+ `price` FLOAT -- 错误!金额必须用 DECIMAL
210
+
211
+ -- ❌ ENUM(修改困难)
212
+ `status` ENUM('pending', 'approved', 'rejected') -- 错误!使用 TINYINT + 注释
213
+
214
+ -- ❌ SET(语义不清)
215
+ `permissions` SET('read', 'write', 'delete') -- 错误!使用关联表
216
+
217
+ -- ❌ TIMESTAMP(2038年问题)
218
+ `created_at` TIMESTAMP -- 错误!使用 DATETIME
219
+
220
+ -- ❌ INT 作为主键(容易溢出)
221
+ `id` INT AUTO_INCREMENT -- 错误!使用 BIGINT UNSIGNED
222
+ ```
223
+
224
+ ### 不推荐使用
225
+
226
+ ```sql
227
+ -- 不推荐:TINYTEXT、MEDIUMBLOB、LONGBLOB(非必要场景)
228
+ `content` TINYTEXT -- 使用 VARCHAR 或 TEXT
229
+
230
+ -- 不推荐:CHAR(变长场景)
231
+ `name` CHAR(100) -- 使用 VARCHAR(100)
232
+
233
+ -- 不推荐:BIT(语义不清)
234
+ `is_enabled` BIT(1) -- 使用 TINYINT(1)
235
+ ```
236
+
237
+ ---
238
+
239
+ ## 六、数据类型选择决策树
240
+
241
+ ### 存储数字
242
+
243
+ ```
244
+ 是否是主键?
245
+ ├─ 是 → BIGINT UNSIGNED AUTO_INCREMENT
246
+ └─ 否
247
+ ├─ 是否是外键?
248
+ │ └─ 是 → BIGINT UNSIGNED
249
+ └─ 否
250
+ ├─ 是否是金额?
251
+ │ └─ 是 → DECIMAL(18,4)
252
+ └─ 否
253
+ ├─ 是否是布尔值?
254
+ │ └─ 是 → TINYINT(1)
255
+ └─ 否
256
+ ├─ 是否是枚举/状态?
257
+ │ └─ 是 → TINYINT(配合注释)
258
+ └─ 否 → INT(一般整数)
259
+ ```
260
+
261
+ ### 存储文本
262
+
263
+ ```
264
+ 文本长度?
265
+ ├─ < 64 字符 → VARCHAR(64)
266
+ ├─ < 128 字符 → VARCHAR(128)
267
+ ├─ < 512 字符 → VARCHAR(512)
268
+ ├─ < 1000 字符 → VARCHAR(1024)
269
+ └─ > 1000 字符 → TEXT / MEDIUMTEXT
270
+ ```
271
+
272
+ ### 存储时间
273
+
274
+ ```
275
+ 是否需要自动更新?
276
+ ├─ 创建时间 → DATETIME DEFAULT CURRENT_TIMESTAMP
277
+ ├─ 更新时间 → DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
278
+ └─ 业务时间 → DATETIME DEFAULT NULL
279
+ ```
280
+
281
+ ---
282
+
283
+ ## 七、字段定义最佳实践
284
+
285
+ ### 1. 明确 NOT NULL 还是 NULL
286
+
287
+ ```sql
288
+ -- ✅ 推荐:必填字段使用 NOT NULL + DEFAULT
289
+ `role_name` VARCHAR(128) NOT NULL COMMENT '角色名称',
290
+ `is_enabled` TINYINT(1) NOT NULL DEFAULT 1 COMMENT '是否启用',
291
+
292
+ -- ✅ 推荐:可选字段使用 DEFAULT NULL
293
+ `description` VARCHAR(512) DEFAULT NULL COMMENT '描述',
294
+ `remark` VARCHAR(1024) DEFAULT NULL COMMENT '备注',
295
+
296
+ -- ❌ 错误:必填字段没有 NOT NULL
297
+ `role_name` VARCHAR(128) COMMENT '角色名称', -- 可能插入 NULL
298
+
299
+ -- ❌ 错误:可选字段使用 NOT NULL 但没有 DEFAULT
300
+ `description` VARCHAR(512) NOT NULL COMMENT '描述', -- 必须传值
301
+ ```
302
+
303
+ ### 2. 合理设置 DEFAULT 值
304
+
305
+ ```sql
306
+ -- ✅ 数字类型的默认值
307
+ `sort_order` INT NOT NULL DEFAULT 0 COMMENT '排序权重',
308
+ `quantity` INT NOT NULL DEFAULT 0 COMMENT '数量',
309
+ `amount` DECIMAL(18,4) NOT NULL DEFAULT 0.0000 COMMENT '金额',
310
+
311
+ -- ✅ 布尔类型的默认值
312
+ `is_enabled` TINYINT(1) NOT NULL DEFAULT 1 COMMENT '是否启用',
313
+ `is_deleted` TINYINT(1) NOT NULL DEFAULT 0 COMMENT '逻辑删除',
314
+
315
+ -- ✅ 时间类型的默认值
316
+ `create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
317
+ `update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
318
+
319
+ -- ✅ 字符串类型的默认值(可选)
320
+ `status` VARCHAR(32) NOT NULL DEFAULT 'pending' COMMENT '状态',
321
+ ```
322
+
323
+ ### 3. 字段注释规范
324
+
325
+ ```sql
326
+ -- ✅ 清晰的注释
327
+ `status` TINYINT NOT NULL DEFAULT 0 COMMENT '状态:0-待审核,1-已通过,2-已拒绝',
328
+ `type` TINYINT NOT NULL DEFAULT 1 COMMENT '类型:1-2D,2-3D,3-全息',
329
+ `is_enabled` TINYINT(1) NOT NULL DEFAULT 1 COMMENT '是否启用:0-禁用,1-启用',
330
+
331
+ -- ❌ 模糊的注释
332
+ `status` TINYINT NOT NULL DEFAULT 0 COMMENT '状态', -- 没说明具体含义
333
+ `type` TINYINT NOT NULL DEFAULT 1 COMMENT '类型', -- 没说明有哪些类型
334
+ ```
335
+
336
+ ---
337
+
338
+ ## 八、常见错误示例
339
+
340
+ ### 错误 1:使用 INT 作为主键
341
+
342
+ ```sql
343
+ -- ❌ 错误
344
+ CREATE TABLE `zz_plt_user` (
345
+ `id` INT AUTO_INCREMENT, -- INT 最大 21 亿,容易溢出
346
+ ...
347
+ );
348
+
349
+ -- ✅ 正确
350
+ CREATE TABLE `zz_plt_user` (
351
+ `id` BIGINT UNSIGNED AUTO_INCREMENT, -- 支持更大数据量
352
+ ...
353
+ );
354
+ ```
355
+
356
+ ### 错误 2:使用 FLOAT/DOUBLE 存储金额
357
+
358
+ ```sql
359
+ -- ❌ 错误
360
+ `price` FLOAT COMMENT '价格', -- 精度丢失
361
+
362
+ -- ✅ 正确
363
+ `price` DECIMAL(18,4) NOT NULL DEFAULT 0.0000 COMMENT '价格',
364
+ ```
365
+
366
+ ### 错误 3:使用 ENUM 类型
367
+
368
+ ```sql
369
+ -- ❌ 错误
370
+ `status` ENUM('pending', 'approved', 'rejected') COMMENT '状态', -- 修改需要 DDL
371
+
372
+ -- ✅ 正确
373
+ `status` TINYINT NOT NULL DEFAULT 0 COMMENT '状态:0-待审核,1-已通过,2-已拒绝',
374
+ ```
375
+
376
+ ### 错误 4:使用 TIMESTAMP
377
+
378
+ ```sql
379
+ -- ❌ 错误
380
+ `create_time` TIMESTAMP DEFAULT CURRENT_TIMESTAMP, -- 2038 年问题
381
+
382
+ -- ✅ 正确
383
+ `create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
384
+ ```
385
+
386
+ ### 错误 5:VARCHAR 长度不合理
387
+
388
+ ```sql
389
+ -- ❌ 错误
390
+ `name` VARCHAR(10), -- 太短,可能截断
391
+ `url` VARCHAR(10000), -- 太长,浪费空间
392
+
393
+ -- ✅ 正确
394
+ `name` VARCHAR(128), -- 合理长度
395
+ `url` VARCHAR(512), -- 一般 URL 长度
396
+ ```
397
+
398
+ ---
399
+
400
+ **参考文档**:[MySQL 数据库规范](../../../database/mysql-specification.md)