docs: simplify migration documentation

This commit is contained in:
2026-07-28 16:22:50 +08:00
parent b8d14e8a7e
commit 5732df8886
13 changed files with 484 additions and 2016 deletions

View File

@@ -1,75 +1,35 @@
# 第一阶段:仓库转正基线
基线日期2026-07-27
状态:已完成
## 仓库身份
## 目标
- 本仓库是 ASP.NET Core 目标后端,后续新功能只在这里开发
- 旧 NestJS 后端只用于核对业务行为、接口契约和数据迁移
- 保留现有 Git 历史,不重新初始化仓库
- 正式远程使用 `https://git.gongxue100.com/xiongyuxing/tiku-backend.net.git`
- 默认分支统一为 `main`,远程创建后再设置保护规则。
- 确认 ASP.NET Core + EF Core + PostgreSQL 仓库为唯一目标后端。
- 建立旧 NestJS OpenAPI 与当前 .NET OpenAPI 的机械比较基线
- 接入自建 Git 上游
## 当前可验证基线
## 结果
| 项目 | 结果 |
- 旧 NestJS 仅作为行为、接口和迁移参考。
- 新功能在 .NET 仓库开发。
- 旧 URL 不要求逐字兼容。
- API 差距记录在 `docs/migration/contracts/operation-inventory.csv`
基线快照:
| 项 | 数量 |
| --- | ---: |
| 旧 NestJS OpenAPI 路径 | 283 |
| 旧 NestJS OpenAPI 操作 | 342 |
| 当前 .NET OpenAPI 路径 | 192 |
| 当前 .NET OpenAPI 操作 | 237 |
| 方法和路径完全一致 | 165 |
| 仅旧 NestJS 存在 | 177 |
| 仅当前 .NET 存在 | 72 |
| 当前 .NET Controller 文件 | 20 |
| 当前 EF Core Migration | 7 |
OpenAPI 数字来自开发环境运行时文档,不以 Controller 特性数量或 README 手工统计为准。详细清单见 [operation-inventory.csv](contracts/operation-inventory.csv)。
## 权威来源
| 内容 | 权威来源 |
| --- | --- |
| 目标架构 | `docs/adr/0001-authoritative-dotnet-backend.md` |
| API 契约 | 运行时 `/openapi/v1.json` |
| 数据库模型 | EF Core 实体和 Fluent Configuration |
| 数据库结构历史 | `Tiku.Infrastructure/Persistence/Migrations/` |
| 生产迁移入口 | `Tiku.DbMigrator` |
| 迁移范围与取舍 | `docs/migration/contracts/operation-inventory.csv` 及后续决策记录 |
## 自建 Git 接入
远程仓库创建完成后,在仓库根目录执行:
## 验收
```bash
git remote add origin https://git.gongxue100.com/xiongyuxing/tiku-backend.net.git
git push -u origin main
dotnet build TIKU-BACKEND.slnx --no-restore
dotnet test Tiku.UnitTests/Tiku.UnitTests.csproj --no-restore
dotnet test Tiku.IntegrationTests/Tiku.IntegrationTests.csproj --no-restore
dotnet ef migrations script --project Tiku.Infrastructure --startup-project Tiku.DbMigrator
git diff --check
```
如果服务端已经自动创建了 README 或初始提交,不要强制推送;先拉取并确认如何合并历史。
## 基线验证
2026-07-27 在 macOS、.NET SDK 10.0.301 上完成:
```text
dotnet restore通过
dotnet build通过0 warning / 0 error
dotnet test通过261/261
dotnet format --verify-no-changes通过
EF Core migration script通过生成 4166 行 SQL
API 契约清单校验通过414 个唯一操作
```
首次 restore 曾因 `api.nuget.org` TLS EOF 和下载超时失败;串行重试成功。这是依赖源网络故障,不是源码或项目路径问题。
## 第一阶段退出条件
- [x] 明确 .NET 是唯一目标后端。
- [x] 保留并接续现有 Git 历史。
- [x] 仓库命令不依赖开发者机器的绝对路径。
- [x] 建立旧 NestJS 与当前 .NET 的 OpenAPI 操作基线。
- [x] 固定 EF Core Migration 的权威地位。
- [x] 配置自建 Git remote。
- [x] 首次推送 `main`
- [ ] 在自建 Git 上启用 `main` 分支保护和 CI等待远程仓库