Hua.Todo/.trae/rules/项目/03-数据模型与迁移约束.md

数据模型与迁移约束（Hua.Todo 专属）

适用范围：本规则属于 项目规则（仅 Hua.Todo 项目生效）。

描述当前数据库实体、字段约束、EF Core 迁移历史，约束智能体在改 schema 时遵循的纪律。

一、技术栈

• ORM：EF Core
• 数据库：SQLite（嵌入式与 Host 开发都走 SQLite；生产 Host 可切其他后端）
• DbContext：TodoDbContext
• 迁移目录：Hua.Todo.Application/Migrations/
• 表名规范：遵循 ABP 模板规范，格式为 T_{实体名}s，如 T_Tasks、T_Users

二、当前实体清单（src/Hua.Todo.Core/Entities/）

2.1 TaskEntity（待重构为 ABP 基类）

⚠️ 重大变更预警：TaskEntity 计划继承 FullAuditedEntityWithUser<Guid, IdentityUser>，重构后将包含 ABP 全部审计字段。此改为破坏性变更，详见 09-CloudSync-同步策略改进方案.md。

重构前（当前）：

字段	类型	说明
Id	int	主键（待改为 Guid）
UserId	Guid	任务所属用户
Title	string	标题
Priority	TaskPriority	优先级枚举
IsCompleted	bool	是否完成
CreatedAt	DateTime	创建时间
UpdatedAt	DateTime	更新时间
ParentTaskId	int?	父任务ID（待改为 Guid?）

重构后（ABP 标准）：

继承 FullAuditedEntityWithUser<Guid, IdentityUser> 后自动获得：

ABP 审计字段	类型	说明
Id	Guid	主键（强制 Guid）
ExtraProperties	ExtraPropertyDictionary	扩展属性（基类提供）
ConcurrencyStamp	string?	并发戳
CreationTime	DateTime	创建时间
CreatorId	Guid?	创建人
LastModificationTime	DateTime?	最后修改时间
LastModifierId	Guid?	最后修改人
IsDeleted	bool	软删除标记
DeletionTime	DateTime?	删除时间
DeleterId	Guid?	删除人

业务字段保留：UserId、Title、Priority、IsCompleted、ParentTaskId

2.2 其他实体

实体	关键字段	约束
TaskPriority	枚举	Priority 字段对应类型
UserEntity	Id、UserName、PasswordHash、PasswordSalt、Role、MustChangePassword	唯一索引：UserName
UserSessionEntity	SessionId、UserId、ExpiresAtUtc、IsStepUp、StepUpExpiresAtUtc	session token 由 DB 管理（非纯 JWT）
SecurityPolicyEntity	UserId、AllowPersist、AllowSync、SecondFactorExpiryMinutes、IsTrustedDeviceOnly	与 User 一对一
AuditLogEntity	Id、UserId、Action、OccurredAtUtc、Details	关键安全事件
TodoUserIds	LocalUserId = "local"	静态常量类，非实体

三、迁移历史（按时间）

迁移	含义
20260313044926_InitialCreate	初始 Tasks 表
20260313092658_AddParentTaskId	父子任务字段
20260406172936_AddCloudSyncCoreEntities	Users / UserSessions / SecurityPolicies
20260406173734_AddAllowSyncToSecurityPolicy	AllowSync 字段
20260413140347_UpdateSecurityEntities	安全实体调整
20260413140753_AddAuditLogs	AuditLogs 表
20260424164713_AddPasswordSaltToUsers	密码加盐
20260510171230_AddMustChangePasswordToUsers	强制改密标志
MakeTaskEntityAbpCompatible（待创建）	重构为继承 ABP 基类，新增审计字段，主键从 int 改为 Guid

四、改 schema 必须遵守的纪律

1. 禁止手改 *ModelSnapshot.cs：使用 dotnet ef migrations add 命令生成
2. 迁移命名以动词开头：AddXxx / UpdateXxx / RemoveXxx / RenameXxx
3. 避免破坏性迁移：删除字段前先确认数据已被业务层迁移；优先采用"双写/兼容期"
4. 嵌入式宿主启动时自动 Migrate：见 EmbeddedWebServerService.cs 中的 db.Database.Migrate() 调用；任何破坏迁移幂等性的改动都会让客户端启动失败
5. 业务字段命名沿用 Task* 词根（即业务实体），编码工作侧不要在实体上用 Task 词根之外的同义词
6. UserId 字段不可为空：本地模式使用 TodoUserIds.LocalUserId = "local"，云端模式使用真实用户 GUID 字符串

五、DTO 与实体的映射边界

• 实体（Entity）：仅在 Hua.Todo.Core / Hua.Todo.Application/Data 内部使用
• DTO（Models）：跨进程边界（HTTP API、WebView 注入）使用，位于 Hua.Todo.Application/CloudSync/Models/ 与 Hua.Todo.Application/Models/
• 不要把实体直接序列化为 API 响应：避免暴露内部字段、避免循环引用

六、检查清单（schema 变更）

1. 是否新增了 EF Core 迁移（而非手改快照）？
2. 迁移名称是否以 AddXxx/UpdateXxx/RemoveXxx 开头？
3. 是否在 docs/manual/01-技术设计文档.md 中同步更新数据模型描述？
4. 是否在 docs/manual/06-版本记录.md 中追加非琐碎变更条目？
5. 是否在嵌入式宿主上验证了启动时 Migrate 不报错？