EIS-dotnet/MIGRATION.md

ASP.NET Core 10 迁移

迁移采用兼容优先的渐进式方案：ASP.NET Core 作为统一入口，尚未迁移的 /api/* 请求暂时转发给运行在 4174 端口的 Node.js 服务。每完成一个功能域，就在 ASP.NET Core 中注册对应原生端点并停止转发该路径。

当前阶段

• ASP.NET Core 10 解决方案与分层项目
• 原前端静态资源无修改托管
• 旧 API 兼容转发，包含 Cookie、请求体、文件下载和状态码
• 存活与迁移就绪检查
• 公开首页与已发布通知（原生 SQLite / MySQL 读取）
• 招生公示与 HMAC 文书验真公开接口
• 登录、自主注册、Session 与 TOTP（兼容开关默认关闭）
• 考生业务
• 管理后台、审批流和考务编排（管理端读取、组织维护、批量报名号审批、流程配置及通知公告管理已原生化）
• 考生志愿填报与招生录取查询
• Excel、文书和缓存
• 容器入口切换及 Node.js 后端移除

本地运行

先在一个终端运行旧 API：

$env:PORT = '4174'
npm start

再在另一个终端运行 ASP.NET Core 入口：

dotnet run --project .\src\Eis.Web\Eis.Web.csproj

浏览器仍访问 http://127.0.0.1:4173。

• GET /health/live：只检查 ASP.NET Core 宿主。
• GET /health/migration：检查迁移宿主和旧 API 转发链路。

可通过配置 LegacyNode:Enabled=false 禁用兼容转发；此时尚未迁移的 API 会返回 501。

认证域的 ASP.NET Core 原生实现已经覆盖 /api/auth/*，包括现有 PBKDF2 密码、hz_session Cookie、登录挑战、TOTP、防重放、恢复码和自主注册。迁移期间默认仍由 Node 处理认证；显式设置以下变量后切换到原生实现：

$env:AUTH_NATIVE_ENABLED = 'true'

开发环境未配置 Redis 时可以使用进程内状态独立验证原生认证。生产环境以及仍需访问 Node 受保护接口的联调环境必须配置 REDIS_URL 或 REDIS_SESSION_URL；两个运行时会复用相同逻辑库和 exam-information:auth 键前缀，从而共享登录会话。GET /health/migration 会报告 authentication.nativeEnabled、状态后端和跨运行时会话共享能力。

考生域全部端点（首页、通知、个人资料读取与提交、可报名考试、我的报名读取与提交、成绩与总分排名、成绩单防伪码、成绩复议、准考证下载、志愿填报与录取查询）可通过以下开关原生运行；该开关必须与原生认证及共享 Redis 同时启用：

$env:AUTH_NATIVE_ENABLED = 'true'
$env:CANDIDATE_NATIVE_ENABLED = 'true'

管理后台第一批只读接口（管理上下文、仪表盘、学校、学校组织、管理员和考试列表）已经原生化，并保留超级、校级、班级管理员的权限与数据作用域。第二批覆盖学校、班级和管理员的创建与维护、管理员密码重置及自主注册开关；更新操作与审计日志在同一事务中提交，停用或重置管理员会同步失效其会话。第三批覆盖批量报名号申领的读取、提交和审批，终审会按照当前号码规则原子生成考生账号、初始密码和待补录资料。第四批覆盖报名号规则及审批流程定义的读取与维护，并保留流程层级和批量申领终审约束。第五批覆盖完整通知公告管理：超级管理员可读取手工公告与五类系统公示、创建和编辑手工公告，并控制系统公示是否公开显示；HTML 净化、显隐更新和审计日志均由 ASP.NET Core 原生处理。

其余审批流和考务编排接口仍转发给 Node，因此管理端开关都要求原生认证和共享 Redis；各写入子功能还必须与只读开关一起启用：

$env:AUTH_NATIVE_ENABLED = 'true'
$env:ADMIN_NATIVE_READS_ENABLED = 'true'
$env:ADMIN_NATIVE_ORGANIZATION_WRITES_ENABLED = 'true'
$env:ADMIN_NATIVE_ACCOUNT_BATCHES_ENABLED = 'true'
$env:ADMIN_NATIVE_CONFIGURATION_ENABLED = 'true'
$env:ADMIN_NATIVE_NOTICE_MANAGEMENT_ENABLED = 'true'

旧版 ADMIN_NATIVE_NOTICE_WRITES_ENABLED 仍可作为兼容别名使用。GET /health/migration 的 administration.nativeReadsEnabled、administration.nativeOrganizationWritesEnabled、administration.nativeAccountBatchesEnabled、administration.nativeConfigurationEnabled、administration.nativeNoticeManagementEnabled 和 administration.nativeRoutes 会报告这些端点是否已切换。

完整的宿主、静态资源、JSON 转发和 Session Cookie 冒烟测试：

pwsh.exe -NoLogo -NoProfile -NonInteractive -File .\scripts\smoke-dotnet-migration.ps1