ShaoHua
65cee20006
- 新增 00-目录与导读.md 双入口导航 - 用户面(01-04)：项目介绍、安装指南、版本记录、其他信息 - 开发者面(05-10)：技术栈、构建、架构、云同步、代码规范、MCP - 拆分旧01为 01(用户)+05(开发者)；旧02为 02(用户)+06(开发者) - 合并旧08+09 MCP文档为 10-MCP服务集成 - 同步更新 README.md 与 .trae/rules/项目/ 交叉引用
5.3 KiB
5.3 KiB
数据模型与迁移约束（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 必须遵守的纪律
- 禁止手改
*ModelSnapshot.cs：使用dotnet ef migrations add命令生成 - 迁移命名以动词开头：
AddXxx/UpdateXxx/RemoveXxx/RenameXxx - 避免破坏性迁移：删除字段前先确认数据已被业务层迁移；优先采用"双写/兼容期"
- 嵌入式宿主启动时自动 Migrate：见
EmbeddedWebServerService.cs中的db.Database.Migrate()调用；任何破坏迁移幂等性的改动都会让客户端启动失败 - 业务字段命名沿用
Task*词根（即业务实体），编码工作侧不要在实体上用Task词根之外的同义词 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 变更）
- 是否新增了 EF Core 迁移（而非手改快照）？
- 迁移名称是否以
AddXxx/UpdateXxx/RemoveXxx开头？ - 是否在 docs/manual/07-技术架构设计.md 中同步更新数据模型描述？
- 是否在 docs/manual/03-版本记录.md 中追加非琐碎变更条目？
- 是否在嵌入式宿主上验证了启动时 Migrate 不报错？