feat(docs): update database migration guide with detailed steps and prerequisites

AML_Backend

@@ -0,0 +1 @@
+Subproject commit cd254759bddd1cb149071cda281f8701277865fd

AML_Frontend

@@ -0,0 +1 @@
+Subproject commit 649a90af3b6600fe82834bb4d3530855abbd02fe

docs/AML_Backend/数据库迁移指南/readme.md

@@ -1,21 +1,167 @@
 # 数据库迁移指南
 
-## 前置条件
-- vs开发环境
-- 确保项目已经成功构建
-- 确保已安装Entity Framework Core工具
+本项目使用 Entity Framework Core 迁移。迁移文件生成在：
+`AML_Backend/src/iCON.Abp.FX.EntityFrameworkCore.DbMigrations/Migrations/`
+对应的 DbContext 为 `FXMigrationsDbContext`，设计时工厂为
+`EntityFrameworkCore/FXMigrationsDbContextFactory.cs`。
 
-## 迁移步骤
-1. 在Visual Studio中将`EntityFrameworkCore.DbMigrations`设置为启动项目
-2. 打开包管理器控制台(Package Manager Console)
-3. 将默认项目设置为：`src\EntityFrameworkCore.DbMigrations`
-4. 执行迁移命令：
-   ```
-   Add-Migration <MigrationName>
-   ```
-5. 迁移将自动应用到数据库
+生成迁移有两条等价路径：**A. Visual Studio 包管理器控制台（Windows）** 与
+**B. `dotnet ef` 命令行（macOS / Linux / 无 VS 的开发环境）**。二者产物完全一致，
+按你的操作系统任选其一即可。
+
+> 说明：迁移**只在开发/构建环境生成**（生成 `*.cs` + 更新 `ModelSnapshot`）；
+> 运行时由 `Database.Migrate()` 自动应用到数据库。**不要**用手写 `ALTER TABLE`
+> 代替生成迁移——运行时会读取迁移里的 `TargetModel`（完整模型快照）做比对，
+> 缺少对应迁移会导致模型不一致。手动改库仅可作为本地临时应急。
+
+---
+
+## 路径 A · Visual Studio 包管理器控制台（Windows）
+
+### 前置条件
+- Visual Studio 开发环境
+- 确保解决方案已成功构建
+- 已安装 EF Core 工具
+
+### 步骤
+1. 将 `EntityFrameworkCore.DbMigrations` 设为启动项目
+2. 打开包管理器控制台（Package Manager Console）
+3. 默认项目选择：`src\iCON.Abp.FX.EntityFrameworkCore.DbMigrations`
+4. 执行：`Add-Migration <MigrationName>`
+5. 迁移会在下次运行时自动应用
+
+- 撤销上一个（尚未应用的）迁移：`Remove-Migration`
+
+---
+
+## 路径 B · `dotnet ef` 命令行（macOS / Linux / 无 VS）
+
+`Add-Migration`（PMC）与 `dotnet ef migrations add`（CLI）是同一功能的两种入口。
+在没有 Visual Studio 的开发机（如本机 macOS）上，**完全可以就地生成迁移**，用 CLI 即可。
+
+> 本机已按此流程实测生成过 `AddAssignedAgentUserIdToFeedback`（`Feedback` 表新增
+> 可空列 `AssignedAgentUserId`），产物与既有 EF Core 5.0.17 迁移格式一致。
+
+### B.0 前置条件（本机现状与坑）
+
+| 前置项 | 现状 / 处理 |
+|--------|-------------|
+| **dotnet-ef 工具** | 项目未自带。用本地工具清单安装（见 B.1）。 |
+| **.NET 运行时** | 项目 target `net6.0`；本机可能只装了更高版本（如 .NET 10）。构建不受影响，但运行设计时宿主需 **roll-forward**（见 B.2）。 |
+| **设计时配置来源** | `FXMigrationsDbContextFactory` 从 `src/iCON.Abp.FX.DbMigrator/appsettings.json` + **Nacos** 读取 `DBConfig` / `ConnectionStrings`。开发机若连不上 Nacos（默认 `192.168.1.120:8848`），需改用**本地优先配置**离线生成（见 B.3）。 |
+
+### B.1 安装 dotnet-ef（本地工具清单，一次性）
+
+在 `AML_Backend/` 目录下：
+
+```bash
+cd AML_Backend
+dotnet new tool-manifest          # 若已有 .config/dotnet-tools.json 或 dotnet-tools.json 可跳过
+dotnet tool install dotnet-ef     # 或指定版本：--version "10.*"
+dotnet ef --version               # 验证
+```
+
+> `dotnet-ef` 工具版本可高于项目的 EF Core 版本（本机用 10.0.9 生成 EF Core 5 的迁移没问题）——
+> 代码生成用的是**项目引用的 EF Core Design（5.0.\*）**，所以产物仍是 5.0.17 格式，与既有迁移一致。
+
+### B.2 运行时 roll-forward（仅当本机缺少 net6.0 运行时）
+
+`dotnet ef` 会构建启动项目（`net6.0`）并在该运行时里启动设计时宿主。本机若只有 .NET 10，
+需允许从 net6 向上滚动到已装的运行时，给命令加环境变量：
+
+```bash
+DOTNET_ROLL_FORWARD=LatestMajor dotnet ef migrations add ...
+```
+
+（若本机已装 .NET 6 运行时，则不需要这个变量。）
+
+### B.3 离线配置：绕开不可达的 Nacos（仅当连不上 Nacos）
+
+`FXMigrationsDbContextFactory` 通过 `AddNacosV2ConfigurationLocalFirst()` 读取配置：
+**本地 `appsettings.json` 里若没有 `NacosConfig` 节点，就完全不连 Nacos、只用本地配置**。
+利用这一点，把 `src/iCON.Abp.FX.DbMigrator/appsettings.json` 临时替换为本地优先版本
+（去掉 `NacosConfig`，补上 `DBConfig` 与连接串）。
+
+> 生成迁移（`migrations add`）**不会真的连库**，只需连接串可解析（非空）即可；
+> 指向本机 docker 的 SQL Server 最稳妥。
+
+```bash
+cd AML_Backend/src/iCON.Abp.FX.DbMigrator
+cp appsettings.json appsettings.json.nacos-bak      # 备份
+cat > appsettings.json <<'JSON'
+{
+  "DBConfig": { "DBType": "mssql", "ConnectionStringName": "Default" },
+  "ConnectionStrings": {
+    "Default": "Server=localhost,11433;Database=AbpAML;User Id=sa;Password=Aml@Local2026;TrustServerCertificate=True"
+  }
+}
+JSON
+```
+
+（`localhost,11433` / `sa` / `Aml@Local2026` 为 `docs/AML_Backend/docker-compose-local-dev` 本地栈的库；
+按你的本地环境替换。）
+
+**生成完成后务必还原**，避免把本地连接串提交进仓库：
+
+```bash
+mv -f appsettings.json.nacos-bak appsettings.json
+```
+
+### B.4 生成迁移
+
+在 `AML_Backend/` 目录下执行（项目与启动项目都指向 DbMigrations，
+设计时工厂就在其中，`../iCON.Abp.FX.DbMigrator/appsettings.json` 会被正确解析到）：
+
+```bash
+cd AML_Backend
+DOTNET_ROLL_FORWARD=LatestMajor dotnet ef migrations add <MigrationName> \
+  --project src/iCON.Abp.FX.EntityFrameworkCore.DbMigrations \
+  --startup-project src/iCON.Abp.FX.EntityFrameworkCore.DbMigrations \
+  --context FXMigrationsDbContext
+```
+
+看到 `Build succeeded.` + `Done.` 即成功。会生成两文件并更新快照：
+- `Migrations/<时间戳>_<MigrationName>.cs`（`Up`/`Down`）
+- `Migrations/<时间戳>_<MigrationName>.Designer.cs`
+- `Migrations/FXMigrationsDbContextModelSnapshot.cs`（追加本次模型变更）
+
+**核对**：`git diff --stat` 看快照，确认只包含你本次改的实体属性（若夹带了别的变更，
+说明工作树里还有未生成迁移的模型改动，需甄别）。
+
+撤销刚生成、尚未应用的迁移：
+
+```bash
+DOTNET_ROLL_FORWARD=LatestMajor dotnet ef migrations remove \
+  --project src/iCON.Abp.FX.EntityFrameworkCore.DbMigrations \
+  --startup-project src/iCON.Abp.FX.EntityFrameworkCore.DbMigrations \
+  --context FXMigrationsDbContext
+```
+
+### 已生成示例（AssignedAgentUserId）
+
+`20260706234441_AddAssignedAgentUserIdToFeedback.cs`：
+
+```csharp
+protected override void Up(MigrationBuilder migrationBuilder)
+{
+    migrationBuilder.AddColumn<Guid>(
+        name: "AssignedAgentUserId",
+        table: "AMLPortal_Feedbacks",
+        type: "uniqueidentifier",
+        nullable: true);
+}
+protected override void Down(MigrationBuilder migrationBuilder)
+{
+    migrationBuilder.DropColumn(
+        name: "AssignedAgentUserId",
+        table: "AMLPortal_Feedbacks");
+}
+```
+
+---
 
 ## 注意事项
-- 每次修改实体模型后都需要创建新的迁移
-- 可以使用`Remove-Migration`命令撤销上一次迁移
-- 确保数据库连接字符串配置正确
+- 每次修改实体模型后都要生成一个新迁移，并**连同更新后的 `ModelSnapshot` 一起提交**。
+- 迁移在下次运行 `DbMigrator` / Host（`Database.Migrate()`）时自动应用到数据库。
+- 生成迁移不需要真连库；**应用**迁移才需要连接串正确、且账号有 DDL 权限。
+- 别把 B.3 里临时的本地连接串（`appsettings.json`）提交进仓库。

justsolutionsWeb

@@ -0,0 +1 @@
+Subproject commit 148e9f9292166c512282d57306944a6c1216860b

justsolutionsWebV2

@@ -0,0 +1 @@
+Subproject commit f2f01bb4b62758b5ad901505c7a0e3540d93c956