@colin4k1024/tsp 2.4.0

package/skills/goframe-v2/references//346/240/270/345/277/203/347/273/204/344/273/266//346/225/260/346/215/256/345/272/223ORM/ORM/351/223/276/345/274/217/346/223/215/344/275/234/ORM/351/223/276/345/274/217/346/223/215/344/275/234-/346/225/260/346/215/256/346/237/245/350/257/242/ORM/346/237/245/350/257/242-/345/270/270/347/224/250/346/223/215/344/275/234/347/244/272/344/276/213.md

@@ -0,0 +1,271 @@
+## `in` 查询
+
+使用字符串、 `slice` 参数类型。当使用 `slice` 参数类型时，预处理占位符只需要一个 `?` 即可。
+
+```go
+// SELECT * FROM user WHERE uid IN(100,10000,90000)
+g.Model("user").Where("uid IN(?,?,?)", 100, 10000, 90000).All()
+g.Model("user").Where("uid", g.Slice{100, 10000, 90000}).All()
+
+// SELECT * FROM user WHERE gender=1 AND uid IN(100,10000,90000)
+g.Model("user").Where("gender=? AND uid IN(?)", 1, g.Slice{100, 10000, 90000}).All()
+
+// SELECT COUNT(*) FROM user WHERE age in(18,50)
+g.Model("user").Where("age IN(?,?)", 18, 50).Count()
+g.Model("user").Where("age", g.Slice{18, 50}).Count()
+```
+
+使用任意 `map` 参数类型。
+
+```go
+// SELECT * FROM user WHERE gender=1 AND uid IN(100,10000,90000)
+g.Model("user").Where(g.Map{
+    "gender" : 1,
+    "uid"    : g.Slice{100,10000,90000},
+}).All()
+```
+
+使用 `struct` 参数类型，注意查询条件的顺序和 `struct` 的属性定义顺序有关。
+
+```go
+type User struct {
+    Id     []int  `orm:"uid"`
+    Gender int    `orm:"gender"`
+}
+// SELECT * FROM `user` WHERE uid IN(100,10000,90000) AND gender=1
+g.Model("user").Where(User{
+    Gender: 1,
+    Id:     []int{100, 10000, 90000},
+}).All()
+
+```
+
+为提高易用性，当传递的 `slice` 参数为空或 `nil` 时，查询并不会报错，而是转换为一个 `false` 条件语句。
+
+```go
+// SELECT * FROM `user` WHERE 0=1
+g.Model("user").Where("uid", g.Slice{}).All()
+// SELECT * FROM `user` WHERE `uid` IS NULL
+g.Model("user").Where("uid", nil).All()
+```
+
+`ORM` 同时也提供了常用条件方法 `WhereIn/WhereNotIn/WhereOrIn/WhereOrNotIn` 方法，用于常用的 `In` 查询条件过滤。方法定义如下：
+
+```go
+func (m *Model) WhereIn(column string, in interface{}) *Model
+func (m *Model) WhereNotIn(column string, in interface{}) *Model
+func (m *Model) WhereOrIn(column string, in interface{}) *Model
+func (m *Model) WhereOrNotIn(column string, in interface{}) *Model
+```
+
+使用示例：
+
+```go
+// SELECT * FROM `user` WHERE (`gender`=1) AND (`type` IN(1,2,3))
+g.Model("user").Where("gender", 1).WhereIn("type", g.Slice{1,2,3}).All()
+
+// SELECT * FROM `user` WHERE (`gender`=1) AND (`type` NOT IN(1,2,3))
+g.Model("user").Where("gender", 1).WhereNotIn("type", g.Slice{1,2,3}).All()
+
+// SELECT * FROM `user` WHERE (`gender`=1) OR (`type` IN(1,2,3))
+g.Model("user").Where("gender", 1).WhereOrIn("type", g.Slice{1,2,3}).All()
+
+// SELECT * FROM `user` WHERE (`gender`=1) OR (`type` NOT IN(1,2,3))
+g.Model("user").Where("gender", 1).WhereOrNotIn("type", g.Slice{1,2,3}).All()
+```
+
+## `like         ` 查询
+
+```go
+// SELECT * FROM `user` WHERE name like '%john%'
+g.Model("user").Where("name like ?", "%john%").All()
+// SELECT * FROM `user` WHERE birthday like '1990-%'
+g.Model("user").Where("birthday like ?", "1990-%").All()
+
+```
+
+从 `goframe v1.16` 版本开始， `goframe` 的 `ORM` 同时也提供了常用条件方法 `WhereLike/WhereNotLike/WhereOrLike/WhereOrNotLike` 方法，用于常用的 `Like` 查询条件过滤。方法定义如下：
+
+```go
+func (m *Model) WhereLike(column string, like interface{}) *Model
+func (m *Model) WhereNotLike(column string, like interface{}) *Model
+func (m *Model) WhereOrLike(column string, like interface{}) *Model
+func (m *Model) WhereOrNotLike(column string, like interface{}) *Model
+```
+
+使用示例：
+
+```go
+// SELECT * FROM `user` WHERE (`gender`=1) AND (`name` LIKE 'john%')
+g.Model("user").Where("gender", 1).WhereLike("name", "john%").All()
+
+// SELECT * FROM `user` WHERE (`gender`=1) AND (`name` NOT LIKE 'john%')
+g.Model("user").Where("gender", 1).WhereNotLike("name", "john%").All()
+
+// SELECT * FROM `user` WHERE (`gender`=1) OR (`name` LIKE 'john%')
+g.Model("user").Where("gender", 1).WhereOrLike("name", "john%").All()
+
+// SELECT * FROM `user` WHERE (`gender`=1) OR (`name` NOT LIKE 'john%')
+g.Model("user").Where("gender", 1).WhereOrNotLike("name", "john%").All()
+```
+
+## `min/max/avg/sum`
+
+我们直接将统计方法使用在 `Fields` 方法上，例如：
+
+```go
+// SELECT MIN(score) FROM `user` WHERE `uid`=1 LIMIT 1
+g.Model("user").Fields("MIN(score)").Where("uid", 1).Value()
+
+// SELECT MAX(score) FROM `user` WHERE `uid`=1 LIMIT 1
+g.Model("user").Fields("MAX(score)").Where("uid", 1).Value()
+
+// SELECT AVG(score) FROM `user` WHERE `uid`=1 LIMIT 1
+g.Model("user").Fields("AVG(score)").Where("uid", 1).Value()
+
+// SELECT SUM(score) FROM `user` WHERE `uid`=1  LIMIT 1
+g.Model("user").Fields("SUM(score)").Where("uid", 1).Value()
+```
+
+从 `goframe v1.16` 版本开始， `goframe` 的 `ORM` 同时也提供了常用统计方法 `Min/Max/Avg/Sum` 方法，用于常用的字段统计查询。方法定义如下：
+
+```go
+func (m *Model) Min(column string) (float64, error)
+func (m *Model) Max(column string) (float64, error)
+func (m *Model) Avg(column string) (float64, error)
+func (m *Model) Sum(column string) (float64, error)
+```
+
+上面的示例使用快捷统计方法改造后：
+
+```go
+// SELECT MIN(`score`) FROM `user` WHERE `uid`=1 LIMIT 1
+g.Model("user").Where("uid", 1).Min("score")
+
+// SELECT MAX(`score`) FROM `user` WHERE `uid`=1 LIMIT 1
+g.Model("user").Where("uid", 1).Max("score")
+
+// SELECT AVG(`score`) FROM `user` WHERE `uid`=1 LIMIT 1
+g.Model("user").Where("uid", 1).Avg("score")
+
+// SELECT SUM(`score`) FROM `user` WHERE `uid`=1 LIMIT 1
+g.Model("user").Where("uid", 1).Sum("score")
+```
+
+## `count` 查询
+
+```go
+// SELECT COUNT(1) FROM `user` WHERE `birthday`='1990-10-01'
+g.Model("user").Where("birthday", "1990-10-01").Count()
+// SELECT COUNT(uid) FROM `user` WHERE `birthday`='1990-10-01'
+g.Model("user").Fields("uid").Where("birthday", "1990-10-01").Count()
+
+```
+
+从 `goframe v1.16` 版本开始， `goframe` 的 `ORM` 同时也提供了一个按照字段进行 `Count` 的常用方法 `CountColumn`。方法定义如下：
+
+```go
+func (m *Model) CountColumn(column string) (int, error)
+```
+
+使用示例：
+
+```go
+g.Model("user").Where("birthday", "1990-10-01").CountColumn("uid")
+```
+
+## `distinct` 查询
+
+```go
+// SELECT DISTINCT uid,name FROM `user`
+g.Model("user").Fields("DISTINCT uid,name").All()
+// SELECT COUNT(DISTINCT uid,name) FROM `user`
+g.Model("user").Fields("DISTINCT uid,name").Count()
+
+```
+
+从 `goframe v1.16` 版本开始， `goframe` 的 `ORM` 同时也提供了一个字段唯一性过滤标记方法 `Distinct`。方法定义如下：
+
+```go
+func (m *Model) Distinct() *Model
+```
+
+使用示例：
+
+```go
+// SELECT COUNT(DISTINCT `name`) FROM `user`
+g.Model("user").Distinct().CountColumn("name")
+
+// SELECT COUNT(DISTINCT uid,name) FROM `user`
+g.Model("user").Distinct().CountColumn("uid,name")
+
+// SELECT DISTINCT group,age FROM `user`
+g.Model("user").Fields("group, age").Distinct().All()
+```
+
+## `between` 查询
+
+```go
+// SELECT * FROM `user` WHERE age between 18 and 20
+g.Model("user").Where("age between ? and ?", 18, 20).All()
+
+```
+
+从 `goframe v1.16` 版本开始， `goframe` 的 `ORM` 同时也提供了常用条件方法 `WhereBetween/WhereNotBetween/WhereOrBetween/WhereOrNotBetween` 方法，用于常用的 `Between` 查询条件过滤。方法定义如下：
+
+```go
+func (m *Model) WhereBetween(column string, min, max interface{}) *Model
+func (m *Model) WhereNotBetween(column string, min, max interface{}) *Model
+func (m *Model) WhereOrBetween(column string, min, max interface{}) *Model
+func (m *Model) WhereOrNotBetween(column string, min, max interface{}) *Model
+```
+
+使用示例：
+
+```go
+// SELECT * FROM `user` WHERE (`gender`=0) AND (`age` BETWEEN 16 AND 20)
+g.Model("user").Where("gender", 0).WhereBetween("age", 16, 20).All()
+
+// SELECT * FROM `user` WHERE (`gender`=0) AND (`age` NOT BETWEEN 16 AND 20)
+g.Model("user").Where("gender", 0).WhereNotBetween("age", 16, 20).All()
+
+// SELECT * FROM `user` WHERE (`gender`=0) OR (`age` BETWEEN 16 AND 20)
+g.Model("user").Where("gender", 0).WhereOrBetween("age", 16, 20).All()
+
+// SELECT * FROM `user` WHERE (`gender`=0) OR (`age` NOT BETWEEN 16 AND 20)
+g.Model("user").Where("gender", 0).WhereOrNotBetween("age", 16, 20).All()
+```
+
+## `null` 查询
+
+`ORM` 提供了常用条件方法 `WhereNull/WhereNotNull/WhereOrNull/WhereOrNotNull` 方法，用于常用的 `Null` 查询条件过滤。方法定义如下：
+
+```go
+func (m *Model) WhereNull(columns ...string) *Model
+func (m *Model) WhereNotNull(columns ...string) *Model
+func (m *Model) WhereOrNull(columns ...string) *Model
+func (m *Model) WhereOrNotNull(columns ...string) *Model
+```
+
+使用示例：
+
+```go
+// SELECT * FROM `user` WHERE (`created_at`>'2021-05-01 00:00:00') AND (`inviter` IS NULL)
+g.Model("user").Where("created_at>?", gtime.New("2021-05-01")).WhereNull("inviter").All()
+
+// SELECT * FROM `user` WHERE (`created_at`>'2021-05-01 00:00:00') AND (`inviter` IS NOT NULL)
+g.Model("user").Where("created_at>?", gtime.New("2021-05-01")).WhereNotNull("inviter").All()
+
+// SELECT * FROM `user` WHERE (`created_at`>'2021-05-01 00:00:00') OR (`inviter` IS NULL)
+g.Model("user").Where("created_at>?", gtime.New("2021-05-01")).WhereOrNull("inviter").All()
+
+// SELECT * FROM `user` WHERE (`created_at`>'2021-05-01 00:00:00') OR (`inviter` IS NOT NULL)
+g.Model("user").Where("created_at>?", gtime.New("2021-05-01")).WhereOrNotNull("inviter").All()
+```
+
+同时，这几个方法的参数支持多个字段输入，例如：
+
+```go
+// SELECT * FROM `user` WHERE (`created_at`>'2021-05-01 00:00:00') AND (`inviter` IS NULL) AND (`creator` IS NULL)
+g.Model("user").Where("created_at>?", gtime.New("2021-05-01")).WhereNull("inviter", "creator").All()
+```

package/skills/goframe-v2/references//346/240/270/345/277/203/347/273/204/344/273/266//346/225/260/346/215/256/345/272/223ORM/ORM/351/223/276/345/274/217/346/223/215/344/275/234/ORM/351/223/276/345/274/217/346/223/215/344/275/234-/346/225/260/346/215/256/346/237/245/350/257/242/ORM/346/237/245/350/257/242-/345/270/270/347/224/250/346/237/245/350/257/242/346/226/271/346/263/225.md

@@ -0,0 +1,40 @@
+## 基本介绍
+数据查询比较常用的几个方法：
+
+```go
+func (m *Model) All(where ...interface{} (Result, error)
+func (m *Model) One(where ...interface{}) (Record, error)
+func (m *Model) Array(fieldsAndWhere ...interface{}) ([]Value, error)
+func (m *Model) Value(fieldsAndWhere ...interface{}) (Value, error)
+func (m *Model) Count(where ...interface{}) (int, error)
+func (m *Model) CountColumn(column string) (int, error)
+```
+
+简要说明：
+
+1. `All` 用于查询并返回多条记录的列表/数组。
+2. `One` 用于查询并返回单条记录。
+3. `Array` 用于查询指定字段列的数据，返回数组。
+4. `Value` 用于查询并返回一个字段值，往往需要结合 `Fields` 方法使用。
+5. `Count` 用于查询并返回记录数。
+
+此外，也可以看得到这五个方法定义中也支持条件参数的直接输入，参数类型与 `Where` 方法一致。但需要注意，其中 `Array` 和 `Value` 方法的参数中至少应该输入字段参数。
+
+## 使用示例
+
+```go
+// SELECT * FROM `user` WHERE `score`>60
+Model("user").Where("score>?", 60).All()
+
+// SELECT * FROM `user` WHERE `score`>60 LIMIT 1
+Model("user").Where("score>?", 60).One()
+
+// SELECT `name` FROM `user` WHERE `score`>60
+Model("user").Fields("name").Where("score>?", 60).Array()
+
+// SELECT `name` FROM `user` WHERE `uid`=1 LIMIT 1
+Model("user").Fields("name").Where("uid", 1).Value()
+
+// SELECT COUNT(1) FROM `user` WHERE `status` IN(1,2,3)
+Model("user").Where("status", g.Slice{1,2,3}).Count()
+```

package/skills/goframe-v2/references//346/240/270/345/277/203/347/273/204/344/273/266//346/225/260/346/215/256/345/272/223ORM/ORM/351/223/276/345/274/217/346/223/215/344/275/234/ORM/351/223/276/345/274/217/346/223/215/344/275/234-/346/227/266/351/227/264/347/273/264/346/212/244/ORM/351/223/276/345/274/217/346/223/215/344/275/234-/346/227/266/351/227/264/347/273/264/346/212/244.md

@@ -0,0 +1,39 @@
+## 基本介绍
+:::warning
+需要注意，该特性仅对链式操作有效。
+:::
+`gdb` 模块支持对数据记录的写入、更新、删除时间自动填充，提高开发维护效率。为了便于时间字段名称、类型的统一维护，如果使用该特性，我们约定：
+
+- 字段的类型可以为时间类型、数字整型或者布尔型，如: `date`, `datetime`, `timestamp`, `int`, `uint`, `big int`, `bool`等。
+- 字段的名称支持自定义设置，默认名称约定为：
+  - `created_at` 用于记录创建时更新，仅会写入一次。
+  - `updated_at` 用于记录修改时更新，每次记录变更时更新。
+  - `deleted_at` 用于记录的软删除特性，只有当记录删除时会写入一次。
+字段名称不区分大小写，也会忽略特殊字符，例如 `CreatedAt`, `UpdatedAt`, `DeletedAt` 也是支持的。
+
+## 特性配置
+
+时间字段名称可以通过配置文件进行自定义修改，并可使用 `timeMaintainDisabled` 配置在数据库实例上完整关闭该特性。
+
+在配置文件中对应配置项：
+
+```yaml
+database:
+  default:                      # 分组名称，可自定义，默认为default
+    createdAt: "created_at"     # (可选)自动创建时间字段名称
+    updatedAt: "updated_time"   # (可选)自动更新时间字段名称
+    deletedAt: "is_deleted"     # (可选)软删除时间字段名称
+    timeMaintainDisabled: false # (可选)是否完全关闭时间更新特性，为true时CreatedAt/UpdatedAt/DeletedAt都将失效
+```
+
+:::tip
+特别是针对历史项目，本身已经存在不一样的时间字段名称时，可以通过配置项灵活配置时间字段名称。
+:::
+
+完整的数据库配置请参考 [ORM使用配置](../../ORM使用配置/ORM使用配置.md) 章节。
+
+## 特性启用
+
+当数据表包含 `created_at`、 `updated_at`、 `deleted_at` 任意一个或多个字段时，或者包含配置文件中对应的配置字段时，该特性自动启用。
+
+## 相关文档

package/skills/goframe-v2/references//346/240/270/345/277/203/347/273/204/344/273/266//346/225/260/346/215/256/345/272/223ORM/ORM/351/223/276/345/274/217/346/223/215/344/275/234/ORM/351/223/276/345/274/217/346/223/215/344/275/234-/346/227/266/351/227/264/347/273/264/346/212/244//346/227/266/351/227/264/347/273/264/346/212/244-SoftTimeOption.md

@@ -0,0 +1,42 @@
+在前面的[整型字段](./时间维护-整型字段.md)的示例中，时间字段写入的都是秒级时间戳，但如果我们想要控制时间写入的粒度，写入毫秒级时间戳怎么做呢？
+我们可以使用`SoftTimeOption`来控制写入的时间数值粒度。
+
+## 示例SQL
+这是后续示例代码中用到的`MySQL`表结构。由于需要写入比秒级更细粒度的数值，因此字段类型使用`big int`来存储。
+
+```sql
+CREATE TABLE `user` (
+  `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
+  `name` varchar(45) NOT NULL,
+  `status` tinyint DEFAULT 0,
+  `created_at` bigint unsigned DEFAULT NULL,
+  `updated_at` bigint unsigned DEFAULT NULL,
+  `deleted_at` bigint unsigned DEFAULT NULL,
+  PRIMARY KEY (`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8;
+```
+
+:::tip
+如果您尝试测试查看`ORM`操作执行的`SQL`语句，建议您打开`debug`模式（相关文档：[调试模式](../../ORM高级特性/ORM高级特性-调试模式.md)），`SQL`语句将会自动打印到日志输出。
+:::
+
+## `created_at` 写入时间
+
+```go
+// INSERT INTO `user`(`name`,`created_at`,`updated_at`,`deleted_at`) VALUES('john',1731484186556,1731484186556,0)
+g.Model("user").SoftTime(gdb.SoftTimeOption{
+  SoftTimeType: gdb.SoftTimeTypeTimestampMilli,
+}).Data(g.Map{"name": "john"}).Insert()
+```
+
+其中`SoftTimeType`控制时间粒度，粒度选项如下：
+```go
+const (
+    SoftTimeTypeAuto           SoftTimeType = 0 // (Default)Auto detect the field type by table field type.
+    SoftTimeTypeTime           SoftTimeType = 1 // Using datetime as the field value.
+    SoftTimeTypeTimestamp      SoftTimeType = 2 // In unix seconds.
+    SoftTimeTypeTimestampMilli SoftTimeType = 3 // In unix milliseconds.
+    SoftTimeTypeTimestampMicro SoftTimeType = 4 // In unix microseconds.
+    SoftTimeTypeTimestampNano  SoftTimeType = 5 // In unix nanoseconds.
+)
+```

package/skills/goframe-v2/references//346/240/270/345/277/203/347/273/204/344/273/266//346/225/260/346/215/256/345/272/223ORM/ORM/351/223/276/345/274/217/346/223/215/344/275/234/ORM/351/223/276/345/274/217/346/223/215/344/275/234-/346/227/266/351/227/264/347/273/264/346/212/244//346/227/266/351/227/264/347/273/264/346/212/244-/345/237/272/346/234/254/344/275/277/347/224/250.md

@@ -0,0 +1,102 @@
+以下的示例中，我们默认示例中的数据表均包含了`created_at`、 `updated_at`、 `deleted_at`这3个字段，并且字段类型为`datetime`。
+
+## 示例SQL
+这是后续示例代码中用到的`MySQL`表结构。
+```sql
+CREATE TABLE `user` (
+  `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
+  `name` varchar(45) NOT NULL,
+  `status` tinyint DEFAULT 0,
+  `created_at` datetime DEFAULT NULL,
+  `updated_at` datetime DEFAULT NULL,
+  `deleted_at` datetime DEFAULT NULL,
+  PRIMARY KEY (`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8;
+
+CREATE TABLE IF NOT EXISTS `user_detail` (
+    `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
+    `address` varchar(45) NOT NULL,
+    PRIMARY KEY (`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8;
+```
+
+:::tip
+- 如果您选择使用时间字段类型，那么您需要将该字段设置为允许为`NULL`，这样软删除才能起作用。
+- 如果您尝试测试查看`ORM`操作执行的`SQL`语句，建议您打开`debug`模式（相关文档：[调试模式](../../ORM高级特性/ORM高级特性-调试模式.md)），`SQL`语句将会自动打印到日志输出。
+:::
+
+## `created_at` 写入时间
+
+在执行 `Insert/InsertIgnore/BatchInsert/BatchInsertIgnore` 方法时自动写入该时间，随后的更新/删除操作不会引起`created_at`字段内容的改变。
+:::warning
+需要注意的是 `Replace` 方法也会更新该字段，因为该操作相当于删除已存在的旧数据并重新写一条数据。
+:::
+```go
+// INSERT INTO `user`(`name`,`created_at`,`updated_at`) VALUES('john', `2020-06-06 21:00:00`, `2020-06-06 21:00:00`)
+g.Model("user").Data(g.Map{"name": "john"}).Insert()
+
+// INSERT IGNORE INTO `user`(`id`,`name`,`created_at`,`updated_at`) VALUES(10000,'john', `2020-06-06 21:00:00`, `2020-06-06 21:00:00`)
+g.Model("user").Data(g.Map{"id": 10000, "name": "john"}).InsertIgnore()
+
+// REPLACE INTO `user`(`id`,`name`,`created_at`,`updated_at`) VALUES(10000,'john', `2020-06-06 21:00:00`, `2020-06-06 21:00:00`)
+g.Model("user").Data(g.Map{"id": 10000, "name": "john"}).Replace()
+
+// INSERT INTO `user`(`id`,`name`,`created_at`,`updated_at`) VALUES(10001,'john', `2020-06-06 21:00:00`, `2020-06-06 21:00:00`) ON DUPLICATE KEY UPDATE `id`=VALUES(`id`),`name`=VALUES(`name`),`updated_at`=VALUES(`updated_at`)
+g.Model("user").Data(g.Map{"id": 10001, "name": "john"}).Save()
+```
+
+## `deleted_at` 数据软删除
+
+当软删除存在时(即`deleted_at`字段存在时），所有的查询语句都将会自动加上 `deleted_at` 的条件。
+
+```go
+// UPDATE `user` SET `deleted_at`='2020-06-06 21:00:00' WHERE id=10 AND `deleted_at` IS NULL
+g.Model("user").Where("id", 10).Delete()
+```
+
+查询的时候会发生一些变化，例如：
+
+```go
+// SELECT * FROM `user` WHERE id>1 AND `deleted_at` IS NULL
+g.Model("user").Where("id>?", 1).All()
+```
+
+可以看到当数据表中存在 `deleted_at` 字段时，所有涉及到该表的查询操作都将自动加上 `deleted_at IS NULL` 的条件。
+
+## `updated_at` 更新时间
+
+在执行 `Save/Update` 方法时自动写入该时间。
+:::warning
+需要注意的是 `Replace` 方法也会更新该字段，因为该操作相当于删除已存在的旧数据并重新写一条数据。
+:::
+```go
+// UPDATE `user` SET `name`='john guo',`updated_at`='2020-06-06 21:00:00' WHERE name='john' AND `deleted_at` IS NULL
+g.Model("user").Data(g.Map{"name" : "john guo"}).Where("name", "john").Update()
+
+// UPDATE `user` SET `status`=1,`updated_at`='2020-06-06 21:00:00' WHERE `deleted_at` IS NULL ORDER BY `id` ASC LIMIT 10
+g.Model("user").Data("status", 1).OrderAsc("id").Limit(10).Update()
+
+// INSERT INTO `user`(`id`,`name`,`update_at`) VALUES(1,'john guo','2020-12-29 20:16:14') ON DUPLICATE KEY UPDATE `id`=VALUES(`id`),`name`=VALUES(`name`),`update_at`=VALUES(`update_at`)
+g.Model("user").Data(g.Map{"id": 1, "name": "john guo"}).Save()
+```
+
+## 联表查询的场景
+
+如果关联查询的几个表都启用了软删除特性时，会发生以下这种情况，即条件语句中会增加所有相关表的软删除时间判断。
+
+```go
+// SELECT * FROM `user` AS `u` LEFT JOIN `user_detail` AS `ud` ON (ud.id=u.id) WHERE (`u`.`id`=10) AND `u`.`deleted_at` IS NULL LIMIT 1
+g.Model("user", "u").LeftJoin("user_detail", "ud", "ud.id=u.id").Where("u.id", 10).One()
+```
+
+## `Unscoped` 忽略时间特性
+
+`Unscoped` 用于在链式操作中忽略自动时间更新特性，例如上面的示例，加上 `Unscoped` 方法后：
+
+```go
+// SELECT * FROM `user` WHERE id>1
+g.Model("user").Unscoped().Where("id>?", 1).All()
+
+// SELECT * FROM `user` AS `u` LEFT JOIN `user_detail` AS `ud` ON (ud.id=u.id) WHERE u.id=10 LIMIT 1
+g.Model("user", "u").LeftJoin("user_detail", "ud", "ud.id=u.id").Where("u.id", 10).Unscoped().One()
+```

package/skills/goframe-v2/references//346/240/270/345/277/203/347/273/204/344/273/266//346/225/260/346/215/256/345/272/223ORM/ORM/351/223/276/345/274/217/346/223/215/344/275/234/ORM/351/223/276/345/274/217/346/223/215/344/275/234-/346/227/266/351/227/264/347/273/264/346/212/244//346/227/266/351/227/264/347/273/264/346/212/244-/345/270/203/345/260/224/345/255/227/346/256/265.md

@@ -0,0 +1,45 @@
+从`v2.8`版本开始，
+如果时间字段`created_at`、 `updated_at`、 `deleted_at`为布尔字段，ORM组件会自动识别支持，并写入布尔类型数值（写入数值通过`0`和`1`表示）。
+通常布尔字段为`deleted_at`字段，我们这里只演示`deleted_at`字段类型为`bool`的情况。
+
+## 示例SQL
+这是后续示例代码中用到的`MySQL`表结构。
+
+```sql
+CREATE TABLE `user` (
+  `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
+  `name` varchar(45) NOT NULL,
+  `status` tinyint DEFAULT 0,
+  `created_at` int(10) unsigned DEFAULT NULL,
+  `updated_at` int(10) unsigned DEFAULT NULL,
+  `deleted_at` bit(1) DEFAULT NULL,
+  PRIMARY KEY (`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8;
+```
+
+我们建议使用`bit(1)`来表示字段的`bool`类型，而非`tinyint(1)`或者`int(1)`。因为`tinyint(1)/int(1)`字段类型表示的范围是`-127~127`，通常可能会被用作状态字段类型。而`bit(1)`的类型范围为`0/1`，可以很好的表示`bool`类型的两个值`false/true`。
+
+:::tip
+如果您尝试测试查看`ORM`操作执行的`SQL`语句，建议您打开`debug`模式（相关文档：[调试模式](../../ORM高级特性/ORM高级特性-调试模式.md)），`SQL`语句将会自动打印到日志输出。
+:::
+
+## `created_at` 写入时间
+
+```go
+// INSERT INTO `user`(`name`,`created_at`,`updated_at`,`deleted_at`) VALUES('john',1731481488,1731481488,0)
+g.Model("user").Data(g.Map{"name": "john"}).Insert()
+```
+
+## `deleted_at` 数据软删除
+
+```go
+// UPDATE `user` SET `deleted_at`=1 WHERE (`id`=10) AND `deleted_at`=0
+g.Model("user").Where("id", 10).Delete()
+```
+
+查询的时候会发生一些变化，例如：
+
+```go
+// SELECT * FROM `user` WHERE (id>1) AND `deleted_at`=0
+g.Model("user").Where("id>?", 1).All()
+```

package/skills/goframe-v2/references//346/240/270/345/277/203/347/273/204/344/273/266//346/225/260/346/215/256/345/272/223ORM/ORM/351/223/276/345/274/217/346/223/215/344/275/234/ORM/351/223/276/345/274/217/346/223/215/344/275/234-/346/227/266/351/227/264/347/273/264/346/212/244//346/227/266/351/227/264/347/273/264/346/212/244-/346/225/264/345/236/213/345/255/227/346/256/265.md

@@ -0,0 +1,94 @@
+从`v2.8`版本开始，如果时间字段`created_at`、 `updated_at`、 `deleted_at`为整型字段，ORM组件会自动识别支持，并写入**秒级的时间戳**数值。
+
+## 示例SQL
+这是后续示例代码中用到的`MySQL`表结构。
+
+```sql
+CREATE TABLE `user` (
+  `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
+  `name` varchar(45) NOT NULL,
+  `status` tinyint DEFAULT 0,
+  `created_at` int(10) unsigned DEFAULT NULL,
+  `updated_at` int(10) unsigned DEFAULT NULL,
+  `deleted_at` int(10) unsigned DEFAULT NULL,
+  PRIMARY KEY (`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8;
+
+CREATE TABLE IF NOT EXISTS `user_detail` (
+    `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
+    `address` varchar(45) NOT NULL,
+    PRIMARY KEY (`id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8;
+```
+
+:::tip
+如果您尝试测试查看`ORM`操作执行的`SQL`语句，建议您打开`debug`模式（相关文档：[调试模式](../../ORM高级特性/ORM高级特性-调试模式.md)），`SQL`语句将会自动打印到日志输出。
+:::
+
+## `created_at` 写入时间
+
+在执行 `Insert/InsertIgnore/BatchInsert/BatchInsertIgnore` 方法时自动写入该时间，随后的更新/删除操作不会引起`created_at`字段内容的改变。
+:::warning
+需要注意的是 `Replace` 方法也会更新该字段，因为该操作相当于删除已存在的旧数据并重新写一条数据。
+:::
+```go
+// INSERT INTO `user`(`name`,`created_at`,`updated_at`,`deleted_at`) VALUES('john',1731481488,1731481488,0)
+g.Model("user").Data(g.Map{"name": "john"}).Insert()
+
+// INSERT IGNORE INTO `user`(`id`,`name`,`created_at`,`updated_at`,`deleted_at`) VALUES(10000,'john',1731481518,1731481518,0) 
+g.Model("user").Data(g.Map{"id": 10000, "name": "john"}).InsertIgnore()
+
+// REPLACE INTO `user`(`id`,`name`,`created_at`,`updated_at`,`deleted_at`) VALUES(10000,'john',1731481747,1731481747,0)
+g.Model("user").Data(g.Map{"id": 10000, "name": "john"}).Replace()
+
+// INSERT INTO `user`(`id`,`name`,`created_at`,`updated_at`,`deleted_at`) VALUES(10001,'john',1731481766,1731481766,0) ON DUPLICATE KEY UPDATE `id`=VALUES(`id`),`name`=VALUES(`name`),`updated_at`=VALUES(`updated_at`),`deleted_at`=VALUES(`deleted_at`)
+g.Model("user").Data(g.Map{"id": 10001, "name": "john"}).Save()
+```
+
+## `deleted_at` 数据软删除
+
+当软删除存在时(即`deleted_at`字段存在时），所有的查询语句都将会自动加上 `deleted_at` 的条件。
+
+```go
+// UPDATE `user` SET `deleted_at`=1731481948 WHERE (`id`=10) AND `deleted_at`=0
+g.Model("user").Where("id", 10).Delete()
+```
+
+查询的时候会发生一些变化，例如：
+
+```go
+// SELECT * FROM `user` WHERE (id>1) AND `deleted_at`=0
+g.Model("user").Where("id>?", 1).All()
+```
+
+可以看到当数据表中存在 `deleted_at` 字段时，所有涉及到该表的查询操作都将自动加上 `deleted_at=0` 的条件。
+
+## `updated_at` 更新时间
+
+在执行 `Save/Update` 方法时自动写入该时间。需要注意的是 `Replace` 方法也会更新该字段，因为该操作相当于删除已存在的旧数据并重新写一条数据。
+:::info
+如果同时存在`deleted_at`软删除字段，那么更新操作语句中同样会出现`deleted_at` 的条件。
+:::
+```go
+// UPDATE `user` SET `name`='john guo',`updated_at`=1731481821 WHERE (`name`='john') AND `deleted_at`=0
+g.Model("user").Data(g.Map{"name" : "john guo"}).Where("name", "john").Update()
+
+// UPDATE `user` SET `status`=1,`updated_at`=1731481895 WHERE `deleted_at`=0 ORDER BY `id` ASC LIMIT 10
+g.Model("user").Data("status", 1).OrderAsc("id").Limit(10).Update()
+
+// INSERT INTO `user`(`id`,`name`,`created_at`,`updated_at`,`deleted_at`) VALUES(1,'john guo',1731481915,1731481915,0) ON DUPLICATE KEY UPDATE `id`=VALUES(`id`),`name`=VALUES(`name`),`updated_at`=VALUES(`updated_at`),`deleted_at`=VALUES(`deleted_at`)
+g.Model("user").Data(g.Map{"id": 1, "name": "john guo"}).Save()
+```
+
+## 联表查询的场景
+
+如果关联查询的几个表都启用了软删除特性时，会发生以下这种情况，即条件语句中会增加所有相关表的软删除时间判断。
+
+```go
+// SELECT * FROM `user` AS `u` LEFT JOIN `user_detail` AS `ud` ON (ud.id=u.id) WHERE (`u`.`id`=10) AND `u`.`deleted_at`=0 LIMIT 1
+g.Model("user", "u").LeftJoin("user_detail", "ud", "ud.id=u.id").Where("u.id", 10).One()
+```
+
+## 控制写入时间粒度
+
+本章节的时间字段数值写入默认是秒级时间戳，但如果我们想要控制时间写入的粒度，写入毫秒级时间戳怎么做呢？我们可以使用[SoftTimeOption](./时间维护-SoftTimeOption.md)。