diff --git a/README.md b/README.md index 04c2a65..15890cf 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # TIKU Backend -题库 SaaS 新后端。目标是从旧 PocketBase / Supabase / Nest 方案迁到更可控的 ASP.NET Core + PostgreSQL 架构。 +题库 SaaS 正式后端。项目正在从旧 PocketBase / Supabase / Nest 方案迁到更可控的 ASP.NET Core + PostgreSQL 架构。本仓库是后续开发的唯一目标后端，架构决策见 [`docs/adr/0001-authoritative-dotnet-backend.md`](docs/adr/0001-authoritative-dotnet-backend.md)。 当前判断很明确：现在团队已经有后端开发，继续把核心认证、权限、多租户隔离、业务一致性交给 BaaS 规则，会让复杂度藏在平台、SQL policy 和前端约定之间。新后端把这些东西收回应用层和数据库约束里，开发、排查、审计都会更直接。 @@ -92,7 +92,7 @@ Tiku.IntegrationTests # API / EF 模型集成测试 Tiku.Infrastructure/Persistence/Migrations/20260725220742_InitialSchema.cs ``` -当前 EF 模型包含 124 个 DbSet，覆盖： +当前 EF 模型覆盖： - 租户、用户、成员、认证、Session、短信验证码 - 地区、模块、院校、专业、科目、分类 @@ -124,7 +124,7 @@ Tiku.Infrastructure/Persistence/Migrations/20260725220742_InitialSchema.cs ### 已迁移 API -当前新后端有 43 个 endpoint，其中 3 个是安全诊断接口。已完成的业务/API 闭环： +2026-07-27 运行时 OpenAPI 基线包含 192 个路径、237 个操作。已完成的业务/API 闭环包括： - health - tenant resolve / current public @@ -139,17 +139,14 @@ Tiku.Infrastructure/Persistence/Migrations/20260725220742_InitialSchema.cs ## 还剩多少待迁移 -按旧 Nest API 粗略统计，旧版约 342 个 HTTP endpoint；新后端目前 43 个，其中安全诊断 3 个不算旧业务迁移。按 endpoint 数量估算： +运行时契约基线显示，旧 NestJS 有 342 个操作，当前 .NET 有 237 个操作： ```text 旧版 endpoint 总量：约 342 -新后端已实现：43 -其中诊断接口：3 -已覆盖旧业务接口：约 40 -待迁移旧业务接口：约 302 +当前 .NET 操作：237 ``` -这个数字只是迁移工作量参考，不代表 302 个都应该原样照搬。旧版里有不少平台运营、商业化自动化、审计告警、积分、督导、对账等后段能力，应该按新架构重新筛选。 +两边路径设计并非逐字兼容，不能用 `342 - 237` 推算剩余工作量。详细机械比较和后续取舍入口见 [`docs/migration/contracts/operation-inventory.csv`](docs/migration/contracts/operation-inventory.csv)。旧版里有不少平台运营、商业化自动化、审计告警、积分、督导、对账等后段能力，应按新架构重新筛选。 优先级建议： @@ -166,10 +163,11 @@ Tiku.Infrastructure/Persistence/Migrations/20260725220742_InitialSchema.cs ## 常用命令 ```bash -dotnet build /home/xiong/Games/Anii/TIKU-BACKEND/TIKU-BACKEND.slnx -dotnet test /home/xiong/Games/Anii/TIKU-BACKEND/TIKU-BACKEND.slnx -dotnet format /home/xiong/Games/Anii/TIKU-BACKEND/TIKU-BACKEND.slnx --verify-no-changes -git -C /home/xiong/Games/Anii/TIKU-BACKEND diff --check +dotnet restore TIKU-BACKEND.slnx +dotnet build TIKU-BACKEND.slnx --no-restore +dotnet test TIKU-BACKEND.slnx --no-build +dotnet format TIKU-BACKEND.slnx --verify-no-changes --no-restore +git diff --check ``` 生成数据库 SQL： diff --git a/docs/adr/0001-authoritative-dotnet-backend.md b/docs/adr/0001-authoritative-dotnet-backend.md new file mode 100644 index 0000000..2c5dac6 --- /dev/null +++ b/docs/adr/0001-authoritative-dotnet-backend.md @@ -0,0 +1,31 @@ +# ADR 0001：以 .NET + PostgreSQL 作为唯一目标后端 + +- 状态：已接受 +- 日期：2026-07-27 + +## 背景 + +项目已有一套 NestJS 后端，数据库、认证和存储与 Supabase 的部署及规则耦合较深。新的 ASP.NET Core 后端已经形成完整解决方案、EF Core 模型、迁移链和大量业务 API。前后端尚未进入正式开发，当前仍处于可以直接收敛技术路线的窗口。 + +## 决策 + +1. 本仓库是题库 SaaS 唯一继续演进的后端。 +2. 旧 NestJS 仓库冻结为业务行为、接口契约和数据迁移参考；除迁移阻断问题外，不再承接新功能。 +3. EF Core Migration 是普通数据库结构变更的唯一权威历史。生产环境通过 `Tiku.DbMigrator` 显式执行经审查的迁移，API 不在启动时自动同步结构。 +4. 应用只依赖标准 PostgreSQL 能力和 Npgsql。Supabase 可以临时作为 PostgreSQL 托管商，但不是应用层依赖。 +5. 身份、对象存储、短信、支付和通知通过 Application 层接口隔离供应商。前端不直连 Supabase 业务表。 +6. Yudao 不作为运行时依赖，只参考其 RBAC、租户套餐、审计和后台产品设计。 +7. 新功能按完整领域闭环迁移和验收，不以 Controller 或 endpoint 数量作为完成标准。 + +## 迁移边界 + +- 认证和授权由 ASP.NET Core、JWT、数据库 Session 和应用权限策略负责。 +- 多租户隔离由请求租户上下文、EF 查询/写入防护、数据库约束和真实 PostgreSQL 测试共同负责。 +- 普通表、列、索引、约束由 EF Core Migration 管理；确有必要的 PostgreSQL 专用 SQL 可以包含在 Migration 中并接受审查。 +- 旧 OpenAPI 用于发现能力缺口，不要求新接口逐字兼容。任何主动不兼容都必须在迁移清单中记录决定和替代接口。 + +## 结果 + +- 不再建设长期双后端或双写链路。 +- 更换 PostgreSQL 托管商不要求重写业务代码。 +- 后续开发先补真实 PostgreSQL 测试、强制租户边界、生产配置 fail-fast 和敏感配置加密，再扩展业务模块。 diff --git a/docs/migration-roadmap.md b/docs/migration-roadmap.md index b983d4c..1bed493 100644 --- a/docs/migration-roadmap.md +++ b/docs/migration-roadmap.md @@ -2,6 +2,11 @@ 本文档用于记录从旧 PocketBase / Supabase / NestJS 后端迁移到新 ASP.NET Core + PostgreSQL 后端的阶段性状态和后续优先级。 +仓库转正决策和第一阶段基线分别见： + +- [`docs/adr/0001-authoritative-dotnet-backend.md`](adr/0001-authoritative-dotnet-backend.md) +- [`docs/migration/phase-1-repository-baseline.md`](migration/phase-1-repository-baseline.md) + 迁移原则： - 不追求旧接口逐字兼容，新前端按新 REST API 对接。 @@ -205,13 +210,14 @@ 每批迁移完成后都必须： ```bash -dotnet build /home/xiong/Games/Anii/TIKU-BACKEND/TIKU-BACKEND.slnx -dotnet test /home/xiong/Games/Anii/TIKU-BACKEND/TIKU-BACKEND.slnx -dotnet format /home/xiong/Games/Anii/TIKU-BACKEND/TIKU-BACKEND.slnx --verify-no-changes -git -C /home/xiong/Games/Anii/TIKU-BACKEND diff --check +dotnet restore TIKU-BACKEND.slnx +dotnet build TIKU-BACKEND.slnx --no-restore +dotnet test TIKU-BACKEND.slnx --no-build +dotnet format TIKU-BACKEND.slnx --verify-no-changes --no-restore +git diff --check dotnet ef migrations script \ - --project /home/xiong/Games/Anii/TIKU-BACKEND/Tiku.Infrastructure \ - --startup-project /home/xiong/Games/Anii/TIKU-BACKEND/Tiku.DbMigrator + --project Tiku.Infrastructure \ + --startup-project Tiku.DbMigrator ``` 如果某批不涉及数据库 migration，也仍然运行 migration script，确认当前模型快照和迁移链没有损坏。 diff --git a/docs/migration/contracts/README.md b/docs/migration/contracts/README.md new file mode 100644 index 0000000..84334a4 --- /dev/null +++ b/docs/migration/contracts/README.md @@ -0,0 +1,20 @@ +# API 契约基线 + +`operation-inventory.csv` 是旧 NestJS 与当前 .NET 运行时 OpenAPI 的机械比较结果。 + +状态说明： + +- `exact_match`：HTTP 方法和路径完全一致。仍需核对 DTO、响应、权限和业务错误。 +- `legacy_only`：只存在于旧 NestJS；后续决定迁移、替代或删除。 +- `target_only`：只存在于 .NET；通常是新 REST 设计、诊断接口或路径调整。 + +重新生成： + +```bash +python3 scripts/compare_openapi.py \ + --legacy /path/to/nest-openapi.json \ + --target /path/to/dotnet-openapi.json \ + --output docs/migration/contracts/operation-inventory.csv +``` + +旧 NestJS 开发环境文档默认是 `/openapi.json`，当前 .NET 开发环境文档是 `/openapi/v1.json`。原始 OpenAPI 文件可能较大且会频繁变化，不提交仓库；提交归一化后的 CSV 基线。 diff --git a/docs/migration/contracts/operation-inventory.csv b/docs/migration/contracts/operation-inventory.csv new file mode 100644 index 0000000..f19e270 --- /dev/null +++ b/docs/migration/contracts/operation-inventory.csv @@ -0,0 +1,415 @@ +method,path,status,legacy_operation_id,legacy_summary,target_operation_id,target_summary +GET,/api/ai/school-recommendations,legacy_only,AiController_list,查询院校推荐报告,, +GET,/api/ai/school-recommendations/detail,legacy_only,AiController_detail,获取院校推荐报告详情,, +GET,/api/ai/school-recommendations/export,legacy_only,AiController_exportReport,导出院校推荐报告,, +POST,/api/ai/school-recommendations/generate,legacy_only,AiController_generate,生成院校推荐报告,, +GET,/api/assets/{assetId}/download,target_only,,,,获取资源下载地址 +GET,/api/assets/{assetId}/preview,target_only,,,,获取资源预览地址 +POST,/api/auth/login/password,target_only,,,,手机号密码登录 +POST,/api/auth/login/sms,target_only,,,,短信验证码登录 +POST,/api/auth/logout,exact_match,AuthController_logout,退出登录,,退出登录 +GET,/api/auth/me,legacy_only,AuthController_me,获取当前登录用户,, +POST,/api/auth/oauth/qq,legacy_only,AuthController_qq,QQ OAuth 登录,, +POST,/api/auth/oauth/wechat,exact_match,AuthController_wechat,微信网页 OAuth 登录,,微信网页 OAuth 登录 +POST,/api/auth/oauth/wechat-miniapp,exact_match,AuthController_miniapp,微信小程序登录,,微信小程序登录 +POST,/api/auth/phone/bind,legacy_only,AuthController_bindPhone,绑定手机号,, +POST,/api/auth/refresh,target_only,,,,刷新登录会话 +POST,/api/auth/sms/send,legacy_only,AuthController_sendSms,发送短信验证码,, +POST,/api/auth/sms/verify,legacy_only,AuthController_verifySms,校验短信验证码并登录,, +GET,/api/catalog/announcements,exact_match,CatalogController_announcements,查询公告,,查询公告 +GET,/api/catalog/app-assets,target_only,,,,查询应用资源 +GET,/api/catalog/assets,legacy_only,CatalogController_assets,查询内容资源,, +GET,/api/catalog/assets/download,legacy_only,CatalogController_download,获取资源下载地址,, +GET,/api/catalog/assets/preview,legacy_only,CatalogController_preview,获取资源预览地址,, +GET,/api/catalog/banners,exact_match,CatalogController_banners,查询首页横幅,,查询首页横幅 +GET,/api/catalog/categories,exact_match,CatalogController_categories,查询题目分类,,查询题目分类 +GET,/api/catalog/content-assets,target_only,,,,查询内容资源 +GET,/api/catalog/content-entries,exact_match,CatalogController_contentEntries,查询内容入口,,查询内容入口 +GET,/api/catalog/content-nodes,exact_match,CatalogController_contentNodes,查询内容导航节点,,查询内容导航节点 +GET,/api/catalog/exam-dates,exact_match,CatalogController_examDates,查询考试日期,,查询考试日期 +GET,/api/catalog/faqs,exact_match,CatalogController_faqs,查询常见问题,,查询常见问题 +GET,/api/catalog/handbook-chapters,exact_match,CatalogController_handbookChapters,查询知识手册章节,,查询知识手册章节 +GET,/api/catalog/handbook-entries,exact_match,CatalogController_handbookEntries,查询知识手册条目,,查询知识手册条目 +GET,/api/catalog/handbook-subjects,exact_match,CatalogController_handbookSubjects,查询知识手册科目,,查询知识手册科目 +GET,/api/catalog/images,target_only,,,,查询图片资源 +GET,/api/catalog/majors,exact_match,CatalogController_majors,查询专业目录,,查询专业目录 +GET,/api/catalog/module-nodes,exact_match,CatalogController_moduleNodes,查询模块导航节点,,查询模块导航节点 +GET,/api/catalog/practice-blueprints,exact_match,CatalogController_blueprints,查询练习蓝图,,查询练习蓝图 +GET,/api/catalog/products,exact_match,CatalogController_products,查询可购买产品,,查询可购买产品 +GET,/api/catalog/question-banks,target_only,,,,查询题库列表 +GET,/api/catalog/question-categories,target_only,,,,查询题目分类 +GET,/api/catalog/question-collections,exact_match,CatalogController_collections,查询可用题集,,查询可用题集 +GET,/api/catalog/question-collections/questions,exact_match,CatalogController_collectionQuestions,查询题集内题目,,查询题集内题目 +GET,/api/catalog/question-videos,target_only,,,,查询题目关联视频 +GET,/api/catalog/questions,exact_match,CatalogController_questions,查询已发布题目,,查询已发布题目 +GET,/api/catalog/questions/{questionId},target_only,,,,查询题目详情 +GET,/api/catalog/questions/{questionId}/versions,target_only,,,,查询题目版本 +GET,/api/catalog/region-modules,exact_match,CatalogController_regionModules,查询地区功能模块,,查询地区功能模块 +GET,/api/catalog/regions,exact_match,CatalogController_regions,查询可用地区,,查询可用地区 +GET,/api/catalog/schools,exact_match,CatalogController_schools,查询院校目录,,查询院校目录 +GET,/api/catalog/subjects,exact_match,CatalogController_subjects,查询科目目录,,查询科目目录 +GET,/api/catalog/svip-plans,exact_match,CatalogController_svipPlans,查询 SVIP 套餐,,查询 SVIP 套餐 +GET,/api/catalog/timelines,legacy_only,CatalogController_timelines,查询考试时间线,, +GET,/api/catalog/video-explanations,target_only,,,,查询视频讲解 +GET,/api/catalog/vocabulary-units,exact_match,CatalogController_vocabularyUnits,查询词汇单元,,查询词汇单元 +GET,/api/catalog/vocabulary-words,exact_match,CatalogController_vocabularyWords,查询词汇单词,,查询词汇单词 +POST,/api/commerce/activation-codes/check,legacy_only,CommerceOrdersController_checkCode,检查激活码是否可兑换,, +POST,/api/commerce/activation-codes/redeem,legacy_only,CommerceOrdersController_redeemCode,兑换激活码并发放权益,, +GET,/api/commerce/adjustment-vouchers,legacy_only,CommerceAdjustmentsController_list,查询调账凭证,, +POST,/api/commerce/adjustment-vouchers,legacy_only,CommerceAdjustmentsController_create,创建调账凭证,, +GET,/api/commerce/adjustment-vouchers/events,legacy_only,CommerceAdjustmentsController_events,查询调账凭证事件,, +GET,/api/commerce/adjustment-vouchers/report,legacy_only,CommerceAdjustmentsController_report,查询调账统计报告,, +POST,/api/commerce/adjustment-vouchers/status,legacy_only,CommerceAdjustmentsController_status,审核或关闭调账凭证,, +GET,/api/commerce/coupons,target_only,,,,查询当前用户优惠券 +POST,/api/commerce/coupons/check,target_only,,,,校验优惠券并预览订单金额 +POST,/api/commerce/coupons/claim,exact_match,CommerceOrdersController_claimCoupon,领取优惠券,,领取优惠券 +GET,/api/commerce/entitlements,legacy_only,CommerceOrdersController_entitlements,查询当前用户有效权益,, +GET,/api/commerce/entitlements/check,legacy_only,CommerceOrdersController_entitlementCheck,检查当前用户是否拥有指定权益,, +GET,/api/commerce/entitlements/current,target_only,,,,查询当前用户权益 +GET,/api/commerce/operations/anomalies,legacy_only,CommerceAdjustmentsController_operations,查询支付运营异常总览,, +GET,/api/commerce/orders,exact_match,CommerceOrdersController_list,查询当前用户订单,,查询当前用户订单 +POST,/api/commerce/orders,exact_match,CommerceOrdersController_create,创建商城订单,,创建学生端订单 +GET,/api/commerce/orders/detail,legacy_only,CommerceOrdersController_detail,查询订单详情,, +GET,/api/commerce/orders/status,legacy_only,CommerceOrdersController_status,查询订单及最新支付状态,, +GET,/api/commerce/orders/{orderNo},target_only,,,,查询当前用户订单详情 +POST,/api/commerce/payments,target_only,,,,创建订单支付 +POST,/api/commerce/payments/create,legacy_only,CommercePaymentsController_createPayment,创建第三方支付参数,, +POST,/api/commerce/payments/manual-confirm,legacy_only,CommercePaymentsController_manualConfirm,人工确认线下支付,, +POST,/api/commerce/payments/notify/alipay,exact_match,CommercePaymentsController_alipayPayment,接收支付宝支付结果通知,,支付宝支付回调 +POST,/api/commerce/payments/notify/wechat-pay,target_only,,,,微信支付回调 +POST,/api/commerce/payments/notify/wechat_pay,legacy_only,CommercePaymentsController_wechatPayment,接收微信支付成功通知,, +GET,/api/commerce/reconciliation/anomalies,legacy_only,CommerceReconciliationController_anomalies,查询对账异常汇总,, +GET,/api/commerce/reconciliation/batches,legacy_only,CommerceReconciliationController_batches,查询对账批次,, +POST,/api/commerce/reconciliation/import,legacy_only,CommerceReconciliationController_import,导入支付渠道账单并创建对账批次,, +GET,/api/commerce/reconciliation/issues,legacy_only,CommerceReconciliationController_issues,查询对账处理工单,, +POST,/api/commerce/reconciliation/issues/create,legacy_only,CommerceReconciliationController_createIssue,从对账异常创建处理工单,, +GET,/api/commerce/reconciliation/issues/events,legacy_only,CommerceReconciliationController_issueEvents,查询对账工单事件,, +POST,/api/commerce/reconciliation/issues/status,legacy_only,CommerceReconciliationController_updateIssue,更新对账工单状态,, +GET,/api/commerce/reconciliation/items,legacy_only,CommerceReconciliationController_items,查询对账明细,, +POST,/api/commerce/reconciliation/preview,legacy_only,CommerceReconciliationController_preview,预览支付渠道账单对账,, +GET,/api/commerce/reconciliation/provider-bills/jobs,legacy_only,CommerceReconciliationController_billJobs,查询渠道账单下载任务,, +POST,/api/commerce/reconciliation/provider-bills/request,legacy_only,CommerceReconciliationController_requestBill,创建渠道官方账单下载任务,, +GET,/api/commerce/refunds,legacy_only,CommercePaymentsController_refunds,查询租户退款申请,, +POST,/api/commerce/refunds,legacy_only,CommercePaymentsController_createRefund,创建退款申请,, +POST,/api/commerce/refunds/notify/alipay,legacy_only,CommercePaymentsController_alipayRefund,接收支付宝退款结果通知,, +POST,/api/commerce/refunds/notify/wechat_pay,legacy_only,CommercePaymentsController_wechatRefund,接收微信退款结果通知,, +POST,/api/commerce/refunds/status,legacy_only,CommercePaymentsController_updateRefund,审核或处理退款,, +PUT,/api/commission/member-rate,exact_match,ReferralCommissionController_memberRate,设置成员专属佣金率,, +GET,/api/commission/orders,exact_match,ReferralCommissionController_orders,查询佣金来源明细,, +GET,/api/commission/settings,exact_match,ReferralCommissionController_settings,查询租户佣金配置,, +PUT,/api/commission/settings,exact_match,ReferralCommissionController_updateSettings,保存租户佣金配置,, +GET,/api/commission/settlements,exact_match,ReferralCommissionController_settlements,查询佣金结算单,, +GET,/api/commission/settlements/export,exact_match,ReferralCommissionController_export,导出佣金结算明细,, +POST,/api/commission/settlements/generate,exact_match,ReferralCommissionController_generate,生成佣金结算单,, +GET,/api/commission/settlements/proofs,exact_match,ReferralCommissionController_proofs,查询佣金结算凭证,, +POST,/api/commission/settlements/proofs,exact_match,ReferralCommissionController_createProof,提交佣金打款或票据凭证,, +POST,/api/commission/settlements/proofs/status,exact_match,ReferralCommissionController_updateProof,审核佣金结算凭证,, +POST,/api/commission/settlements/status,exact_match,ReferralCommissionController_updateStatus,更新佣金结算状态,, +GET,/api/commission/summary,exact_match,ReferralCommissionController_summary,查询佣金汇总,, +GET,/api/crm/config,exact_match,ReferralCrmController_config,查询 CRM 推送配置,,查询 CRM 推送配置 +PUT,/api/crm/config,exact_match,ReferralCrmController_upsertConfig,保存 CRM 推送与线索分配配置,,保存 CRM 推送配置 +GET,/api/crm/dead-letters,exact_match,ReferralCrmController_deadLetters,查询 CRM 死信任务与汇总,,查询 CRM 死信任务与汇总 +GET,/api/crm/queue,exact_match,ReferralCrmController_queue,查询 CRM webhook 队列,,查询 CRM webhook 队列 +POST,/api/crm/queue/action,exact_match,ReferralCrmController_action,重试或忽略 CRM 死信任务,,重试或忽略 CRM 死信任务 +GET,/api/crm/queue/logs,exact_match,ReferralCrmController_logs,查询 CRM 队列执行日志,,查询 CRM 队列执行日志 +GET,/api/health,target_only,,,,健康检查 +POST,/api/learning/answers,exact_match,LearningController_answer,提交题目答案,,提交题目答案 +GET,/api/learning/favorites/questions,exact_match,LearningController_favoriteQuestions,查询收藏题目,,查询收藏题目 +POST,/api/learning/favorites/questions,exact_match,LearningController_toggleFavoriteQuestion,收藏或取消收藏题目,,收藏或取消收藏题目 +GET,/api/learning/leaderboard,exact_match,LearningController_leaderboard,查询学习排行榜,,查询学习排行榜 +GET,/api/learning/practice-reports,exact_match,LearningController_reports,查询练习报告列表,,查询练习报告列表 +POST,/api/learning/practice-sessions,exact_match,LearningController_createSession,创建练习会话,,创建练习会话 +GET,/api/learning/practice-sessions/detail,exact_match,LearningController_sessionDetail,获取练习会话详情,,获取练习会话详情 +GET,/api/learning/practice-sessions/history,exact_match,LearningController_history,查询练习历史,,查询练习历史 +GET,/api/learning/practice-sessions/report,exact_match,LearningController_sessionReport,获取练习会话报告,,获取练习会话报告 +POST,/api/learning/practice-sessions/submit,exact_match,LearningController_submitSession,提交练习会话,,提交练习会话并生成报告 +GET,/api/learning/stats,exact_match,LearningController_stats,查询学习统计,,查询学习统计 +GET,/api/learning/trend,exact_match,LearningController_trend,查询学习趋势,,查询学习趋势 +GET,/api/learning/vocabulary/favorites,exact_match,LearningController_favoriteWords,查询收藏单词,,查询收藏单词 +POST,/api/learning/vocabulary/favorites,exact_match,LearningController_toggleFavoriteWord,收藏或取消收藏单词,,收藏或取消收藏单词 +GET,/api/learning/vocabulary/progress,exact_match,LearningController_wordProgress,查询单词学习进度,,查询单词学习进度 +POST,/api/learning/vocabulary/progress,exact_match,LearningController_updateWordProgress,更新单词学习进度,,更新单词学习进度 +POST,/api/learning/vocabulary/review,exact_match,LearningController_reviewWord,提交单词复习结果,,提交单词复习结果 +GET,/api/learning/vocabulary/review-plan,exact_match,LearningController_wordPlan,生成单词复习计划,,生成单词复习计划 +GET,/api/learning/vocabulary/stats,exact_match,LearningController_wordStats,查询单词学习统计,,查询单词学习统计 +GET,/api/learning/wrong-questions,exact_match,LearningController_wrongQuestions,查询错题列表,,查询错题列表 +POST,/api/learning/wrong-questions/resolve,exact_match,LearningController_resolveWrong,将错题标记为已解决,,将错题标记为已解决 +GET,/api/learning/wrong-questions/review-plan,exact_match,LearningController_wrongPlan,生成错题复习计划,,生成错题复习计划 +GET,/api/me,target_only,,,, +GET,/api/platform-admin/audit-alert-rules,legacy_only,PlatformAdminAuditController_rules,查询平台审计告警规则,, +GET,/api/platform-admin/audit-alerts,legacy_only,PlatformAdminAuditController_alerts,查询平台审计告警,, +POST,/api/platform-admin/audit-alerts/status,legacy_only,PlatformAdminAuditController_updateAlert,更新平台审计告警状态,, +GET,/api/platform-admin/audit-logs,legacy_only,PlatformAdminAuditController_logs,查询平台审计日志,, +GET,/api/platform-admin/audit-logs/export,legacy_only,PlatformAdminAuditController_exportLogs,导出平台审计日志,, +GET,/api/platform-admin/audit-notification-channels,legacy_only,PlatformAdminAuditController_channels,查询审计告警通知渠道,, +PUT,/api/platform-admin/audit-notification-channels,legacy_only,PlatformAdminAuditController_upsertChannel,创建或更新审计告警通知渠道,, +GET,/api/platform-admin/audit-notification-events,legacy_only,PlatformAdminAuditController_events,查询审计告警通知事件,, +GET,/api/platform-admin/dunning-notification-channels,legacy_only,PlatformAdminDunningChannelsController_channels,查询平台催缴通知渠道,, +PUT,/api/platform-admin/dunning-notification-channels,legacy_only,PlatformAdminDunningChannelsController_upsertChannel,创建或更新平台催缴通知渠道,, +GET,/api/platform-admin/dunning-notification-events,legacy_only,PlatformAdminDunningEventsController_events,查询平台催缴通知事件,, +GET,/api/platform-admin/invoices,legacy_only,PlatformAdminBillingController_invoices,查询平台租户账单,, +POST,/api/platform-admin/invoices,legacy_only,PlatformAdminBillingController_createInvoice,手工创建租户账单,, +POST,/api/platform-admin/invoices/from-subscription,legacy_only,PlatformAdminBillingController_fromSubscription,为单个订阅生成账单,, +POST,/api/platform-admin/invoices/from-subscriptions-batch,legacy_only,PlatformAdminBillingController_fromSubscriptionsBatch,批量生成订阅账单,, +POST,/api/platform-admin/invoices/from-usage-overage,legacy_only,PlatformAdminBillingController_fromUsage,批量生成用量超额账单,, +POST,/api/platform-admin/invoices/payments/manual-confirm,legacy_only,PlatformAdminBillingController_confirmPayment,人工确认平台服务费收款,, +POST,/api/platform-admin/invoices/process-overdue,legacy_only,PlatformAdminBillingController_processOverdue,处理逾期账单并创建催缴记录,, +GET,/api/platform-admin/invoices/reminders,legacy_only,PlatformAdminBillingController_reminders,查询账单催缴记录,, +GET,/api/platform-admin/invoices/subscription-candidates,legacy_only,PlatformAdminBillingController_subscriptionCandidates,预览订阅账单候选,, +GET,/api/platform-admin/invoices/usage-overage-candidates,legacy_only,PlatformAdminBillingController_usageCandidates,预览用量超额账单候选,, +GET,/api/platform-admin/overview,legacy_only,PlatformAdminOverviewController_overview,查询平台经营概览,, +GET,/api/platform-admin/permissions,legacy_only,PlatformAdminOverviewController_permissions,查询当前平台管理员权限,, +GET,/api/platform-admin/plans,legacy_only,PlatformAdminOverviewController_plans,查询平台 SaaS 套餐,, +GET,/api/platform-admin/question-bank-grants,legacy_only,PlatformAdminQuestionBanksController_grants,查询公共题库授权规则,, +PUT,/api/platform-admin/question-bank-grants,legacy_only,PlatformAdminQuestionBanksController_upsertGrant,创建或更新公共题库授权,, +GET,/api/platform-admin/question-bank-sync-status,legacy_only,PlatformAdminQuestionBanksController_syncStatus,查询公共题库采用与同步状态,, +GET,/api/platform-admin/question-banks,legacy_only,PlatformAdminQuestionBanksController_banks,查询平台公共题库,, +GET,/api/platform-admin/staff,legacy_only,PlatformAdminOverviewController_staff,查询平台员工列表,, +PUT,/api/platform-admin/staff,legacy_only,PlatformAdminOverviewController_upsertStaff,创建或更新平台员工,, +PATCH,/api/platform-admin/staff/status,legacy_only,PlatformAdminOverviewController_updateStaffStatus,启用或禁用平台员工,, +POST,/api/platform-admin/subscriptions,legacy_only,PlatformAdminBillingController_createSubscription,创建租户订阅,, +GET,/api/platform-admin/tenants,legacy_only,PlatformAdminTenantsController_list,查询平台租户列表,, +POST,/api/platform-admin/tenants,legacy_only,PlatformAdminTenantsController_create,创建平台租户,, +PUT,/api/platform-admin/tenants/billing-profile,legacy_only,PlatformAdminTenantsController_billingProfile,保存租户账务与开票资料,, +GET,/api/platform-admin/tenants/detail,legacy_only,PlatformAdminTenantsController_detail,查询平台租户详情,, +PATCH,/api/platform-admin/tenants/status,legacy_only,PlatformAdminTenantsController_status,更新租户业务与账务状态,, +GET,/api/platform-admin/usage,legacy_only,PlatformAdminBillingController_usage,查询租户平台用量记录,, +POST,/api/platform-admin/usage,legacy_only,PlatformAdminBillingController_recordUsage,记录租户平台用量,, +GET,/api/points/exchange-items,target_only,,,,查询积分兑换项 +GET,/api/points/exchange-orders,target_only,,,,查询当前用户积分兑换订单 +POST,/api/points/exchange-orders,target_only,,,,创建积分兑换订单 +GET,/api/points/summary,target_only,,,,查询当前用户积分摘要 +GET,/api/points/tasks,target_only,,,,查询当前可领取积分任务 +POST,/api/points/tasks/claim,target_only,,,,领取积分任务奖励 +GET,/api/profile/activity-tasks,legacy_only,ProfileController_tasks,查询积分活动任务,, +POST,/api/profile/activity-tasks/claim,legacy_only,ProfileController_claimTask,领取活动任务奖励,, +GET,/api/profile/badges,exact_match,ProfileController_badges,查询徽章列表,,查询徽章列表 +POST,/api/profile/check-in,legacy_only,ProfileController_checkIn,每日签到,, +GET,/api/profile/exam-countdowns,exact_match,ProfileController_countdowns,查询考试倒计时,,查询考试倒计时 +GET,/api/profile/exchange-items,legacy_only,ProfileController_exchangeItems,查询积分兑换商品,, +POST,/api/profile/exchange-items/redeem,legacy_only,ProfileController_redeem,兑换积分商品,, +GET,/api/profile/feedbacks,exact_match,ProfileController_feedbacks,查询反馈记录,,查询反馈记录 +POST,/api/profile/feedbacks,exact_match,ProfileController_submitFeedback,提交意见反馈,,提交意见反馈 +GET,/api/profile/me,exact_match,ProfileController_me,获取当前学生资料,,获取当前学生资料 +PATCH,/api/profile/me,exact_match,ProfileController_updateMe,更新当前学生资料,,更新当前学生资料 +GET,/api/profile/notifications,exact_match,ProfileController_notificationList,查询用户通知,,查询用户通知 +POST,/api/profile/notifications/status,exact_match,ProfileController_notificationStatus,更新通知状态,,更新通知状态 +GET,/api/profile/score-events,legacy_only,ProfileController_scoreEvents,查询积分流水,, +GET,/api/questions/videos,legacy_only,QuestionVideoController_list,查询单道题目的解析视频,, +POST,/api/questions/videos/batch,legacy_only,QuestionVideoController_batch,批量查询题目解析视频,, +POST,/api/referral/bind,exact_match,ReferralPublicController_bind,绑定当前用户的推荐归属,,绑定当前用户推荐归属 +GET,/api/referral/conversion-report,exact_match,ReferralManagementController_conversion,查询推荐转化与佣金报告,,查询推荐转化报告 +POST,/api/referral/invite-code,exact_match,ReferralPublicController_invite,生成或查询当前成员邀请码,,生成或查询当前成员邀请码 +POST,/api/referral/manual-bind,exact_match,ReferralManagementController_manualBind,人工调整学生推荐归属,,人工调整学生推荐归属 +POST,/api/referral/qrcode,exact_match,ReferralPublicController_qrcode,生成或查询推广二维码,,生成或查询推广二维码 +POST,/api/referral/resolve,exact_match,ReferralPublicController_resolve,解析推荐邀请码,,解析推荐邀请码 +GET,/api/referral/sales-clients,exact_match,ReferralManagementController_clients,查询推荐人名下客户,,查询推荐人名下客户 +GET,/api/referral/sales-stats,exact_match,ReferralManagementController_salesStats,查询销售推荐统计排行,,查询销售推荐统计排行 +GET,/api/referral/stats,exact_match,ReferralManagementController_stats,查询推荐人个人统计,,查询推荐人个人统计 +GET,/api/referral/team,exact_match,ReferralManagementController_team,查询推荐团队成员,,查询推荐团队成员 +PUT,/api/referral/team,exact_match,ReferralManagementController_upsertTeam,新增或更新推荐团队关系,,新增或更新推荐团队关系 +POST,/api/referral/track-event,exact_match,ReferralPublicController_track,记录推荐行为并按规则创建线索,,记录推荐行为 +GET,/api/scoreline/fields,exact_match,ScorelineController_fields,查询分数线字段配置,,查询分数线字段配置 +GET,/api/scoreline/majors,legacy_only,ScorelineController_majors,查询分数线专业,, +GET,/api/scoreline/records,exact_match,ScorelineController_records,分页查询分数线记录,,分页查询分数线记录 +GET,/api/scoreline/schools,legacy_only,ScorelineController_schools,查询分数线院校,, +GET,/api/scoreline/trend,exact_match,ScorelineController_trend,查询历年分数线趋势,,查询历年分数线趋势 +GET,/api/scoreline/years,exact_match,ScorelineController_years,查询分数线可用年份,,查询分数线可用年份 +GET,/api/tenant-admin/activation-codes,legacy_only,TenantCodesController_codes,查询激活码,, +PUT,/api/tenant-admin/activation-codes,legacy_only,TenantCodesController_upsertCode,新增或更新激活码,, +POST,/api/tenant-admin/activation-codes/generate,legacy_only,TenantCodesController_generate,批量生成激活码,, +GET,/api/tenant-admin/announcements,legacy_only,TenantMarketingOperationsController_announcements,查询租户公告,, +PUT,/api/tenant-admin/announcements,legacy_only,TenantMarketingOperationsController_upsertAnnouncement,新增或更新租户公告,, +GET,/api/tenant-admin/audit-logs,exact_match,TenantGovernanceController_audit,查询租户审计日志,,查询租户审计日志 +GET,/api/tenant-admin/auth-providers,exact_match,TenantIntegrationConfigController_authProviders,查询租户登录 Provider 公开配置,,查询租户登录 Provider 公开配置 +PUT,/api/tenant-admin/auth-providers,exact_match,TenantIntegrationConfigController_upsertAuthProvider,新增或更新租户登录 Provider,,新增或更新租户登录 Provider +GET,/api/tenant-admin/badge-grants,exact_match,TenantBadgeManagementController_grants,查询勋章发放记录,,查询勋章发放记录 +POST,/api/tenant-admin/badge-grants,exact_match,TenantBadgeManagementController_grant,向租户成员发放勋章,,向租户成员发放勋章 +GET,/api/tenant-admin/badges,exact_match,TenantBadgeManagementController_badges,查询租户勋章,,查询租户勋章 +PUT,/api/tenant-admin/badges,exact_match,TenantBadgeManagementController_upsertBadge,新增或更新租户勋章,,新增或更新租户勋章 +GET,/api/tenant-admin/banners,legacy_only,TenantMarketingOperationsController_banners,查询租户 Banner,, +PUT,/api/tenant-admin/banners,legacy_only,TenantMarketingOperationsController_upsertBanner,新增或更新租户 Banner,, +PUT,/api/tenant-admin/branding,exact_match,TenantAppearanceController_branding,更新租户品牌信息,,更新租户品牌信息 +GET,/api/tenant-admin/classes,exact_match,TenantAdminClassesController_list,查询可管理的班级,,查询租户班级 +PUT,/api/tenant-admin/classes,exact_match,TenantAdminClassesController_upsert,新增或更新班级,,新增或更新租户班级 +POST,/api/tenant-admin/classes/disable,exact_match,TenantAdminClassesController_disable,停用班级,,停用租户班级 +GET,/api/tenant-admin/classes/members,exact_match,TenantAdminClassesController_members,查询班级成员,,查询班级成员 +PUT,/api/tenant-admin/classes/members,exact_match,TenantAdminClassesController_upsertMember,新增或更新班级成员,,新增或更新班级成员 +POST,/api/tenant-admin/classes/members/bulk-assign,legacy_only,TenantAdminClassesController_bulkAssign,批量分配班级成员,, +POST,/api/tenant-admin/classes/members/remove,exact_match,TenantAdminClassesController_removeMember,移除班级成员,,移除班级成员 +GET,/api/tenant-admin/code-batches,legacy_only,TenantCodesController_batches,查询兑换码批次,, +PUT,/api/tenant-admin/code-batches,legacy_only,TenantCodesController_upsertBatch,新增或更新兑换码批次,, +GET,/api/tenant-admin/coupons,legacy_only,TenantCodesController_coupons,查询优惠券,, +PUT,/api/tenant-admin/coupons,legacy_only,TenantCodesController_upsertCoupon,新增或更新优惠券,, +GET,/api/tenant-admin/coupons/redemptions,legacy_only,TenantCodesController_redemptions,查询优惠券核销明细,, +GET,/api/tenant-admin/coupons/report,legacy_only,TenantCodesController_report,查询优惠券核销报表,, +GET,/api/tenant-admin/dashboard,legacy_only,TenantAdminInsightsController_dashboard,查询租户运营管理看板,, +GET,/api/tenant-admin/domains,exact_match,TenantIntegrationConfigController_domains,查询租户域名,,查询租户域名 +POST,/api/tenant-admin/domains,exact_match,TenantIntegrationConfigController_createDomain,添加租户域名,,添加租户域名 +GET,/api/tenant-admin/exam-dates,legacy_only,TenantMarketingOperationsController_examDates,查询租户考试日期,, +PUT,/api/tenant-admin/exam-dates,legacy_only,TenantMarketingOperationsController_upsertExamDate,新增或更新考试日期,, +GET,/api/tenant-admin/faqs,legacy_only,TenantMarketingOperationsController_faqs,查询租户常见问题,, +PUT,/api/tenant-admin/faqs,legacy_only,TenantMarketingOperationsController_upsertFaq,新增或更新租户常见问题,, +GET,/api/tenant-admin/feedbacks,exact_match,TenantMarketingOperationsController_feedbacks,查询用户反馈,,查询用户反馈 +GET,/api/tenant-admin/feedbacks/events,legacy_only,TenantMarketingOperationsController_feedbackEvents,查询单条反馈处理事件,, +GET,/api/tenant-admin/feedbacks/report,legacy_only,TenantMarketingOperationsController_feedbackReport,查询反馈处理统计报表,, +POST,/api/tenant-admin/feedbacks/status,exact_match,TenantMarketingOperationsController_updateFeedback,更新反馈处理状态并可发放奖励,,处理用户反馈 +GET,/api/tenant-admin/members,exact_match,TenantGovernanceController_members,查询租户成员,,查询租户成员 +PUT,/api/tenant-admin/members,exact_match,TenantGovernanceController_upsert,新增或更新租户成员,,新增或更新租户成员 +POST,/api/tenant-admin/members/disable,exact_match,TenantGovernanceController_disable,停用租户成员并撤销会话,,停用租户成员并撤销会话 +GET,/api/tenant-admin/notifications,target_only,,,,查询用户站内通知 +PUT,/api/tenant-admin/notifications,target_only,,,,新增或更新用户站内通知 +GET,/api/tenant-admin/overview,legacy_only,TenantAdminInsightsController_overview,查询租户基础信息与公开配置,, +GET,/api/tenant-admin/payment-accounts,legacy_only,TenantIntegrationConfigController_payments,查询租户支付账号公开配置,, +PUT,/api/tenant-admin/payment-accounts,legacy_only,TenantIntegrationConfigController_upsertPayment,新增或更新租户支付账号,, +GET,/api/tenant-admin/permissions,exact_match,TenantAdminRolesController_permissions,查询当前管理员权限矩阵,,查询租户后台权限矩阵 +GET,/api/tenant-admin/point-activity-claims,legacy_only,TenantPointsController_claims,查询积分任务领取记录,, +GET,/api/tenant-admin/point-activity-tasks,legacy_only,TenantPointsController_tasks,查询积分活动任务,, +PUT,/api/tenant-admin/point-activity-tasks,legacy_only,TenantPointsController_upsertTask,新增或更新积分活动任务,, +GET,/api/tenant-admin/point-exchange-items,legacy_only,TenantPointsController_items,查询积分兑换项,, +PUT,/api/tenant-admin/point-exchange-items,legacy_only,TenantPointsController_upsertItem,新增或更新积分兑换项,, +GET,/api/tenant-admin/point-exchange-orders,legacy_only,TenantPointsController_orders,查询积分兑换订单,, +GET,/api/tenant-admin/points-risk-report,legacy_only,TenantPointsController_risk,查询积分风险报表,, +GET,/api/tenant-admin/role-templates,exact_match,TenantAdminRolesController_templates,查询租户角色模板,,查询租户角色模板 +PUT,/api/tenant-admin/role-templates,exact_match,TenantAdminRolesController_upsert,新增或更新租户角色模板,,新增或更新租户角色模板 +POST,/api/tenant-admin/role-templates/disable,exact_match,TenantAdminRolesController_disable,停用租户角色模板,,停用租户角色模板 +GET,/api/tenant-admin/secrets,legacy_only,TenantSecretVaultController_list,查询租户密钥掩码状态,, +PUT,/api/tenant-admin/secrets,legacy_only,TenantSecretVaultController_upsert,写入或轮换租户密钥,, +PUT,/api/tenant-admin/settings,exact_match,TenantAppearanceController_settings,更新租户公开设置与功能开关,,更新租户公开设置与功能开关 +GET,/api/tenant-admin/student-followups,target_only,,,,查询学生跟进 +PUT,/api/tenant-admin/student-followups,target_only,,,,新增或更新学生跟进 +GET,/api/tenant-admin/student-notes,target_only,,,,查询学生备注 +PUT,/api/tenant-admin/student-notes,target_only,,,,新增或更新学生备注 +GET,/api/tenant-admin/students,exact_match,TenantAdminStudentsController_list,游标分页查询租户学生,,查询租户学生 +PUT,/api/tenant-admin/students,exact_match,TenantAdminStudentsController_upsert,新增或更新租户学生档案,,新增或更新租户学生档案 +POST,/api/tenant-admin/students/bulk-upsert,legacy_only,TenantAdminStudentsController_bulkUpsert,批量新增或更新租户学生,, +POST,/api/tenant-admin/students/crm-push,legacy_only,TenantAdminStudentsController_crmPush,批量创建学生跟进并推送 CRM,, +GET,/api/tenant-admin/students/followups,legacy_only,TenantAdminEngagementController_followups,查询学生跟进任务,, +PUT,/api/tenant-admin/students/followups,legacy_only,TenantAdminEngagementController_upsertFollowup,新增或更新学生跟进任务,, +GET,/api/tenant-admin/students/followups/report,legacy_only,TenantAdminEngagementController_report,查询学生跟进统计报表,, +GET,/api/tenant-admin/students/notes,legacy_only,TenantAdminEngagementController_notes,查询学生备注,, +PUT,/api/tenant-admin/students/notes,legacy_only,TenantAdminEngagementController_upsertNote,新增或更新学生备注,, +POST,/api/tenant-admin/students/status,exact_match,TenantAdminStudentsController_status,禁用、邀请或恢复租户学生,,更新租户学生状态 +POST,/api/tenant-admin/students/supervision/generate,legacy_only,TenantAdminSupervisionController_generate,批量生成学习督导跟进任务,, +GET,/api/tenant-admin/students/supervision/preview,legacy_only,TenantAdminSupervisionController_preview,预览学习风险学生与督导原因,, +GET,/api/tenant-admin/students/supervision/rules,legacy_only,TenantAdminSupervisionController_rules,查询学习督导规则,, +PUT,/api/tenant-admin/students/supervision/rules,legacy_only,TenantAdminSupervisionController_upsertRule,新增或更新学习督导规则,, +GET,/api/tenant-admin/teachers,legacy_only,TenantAdminInsightsController_teachers,查询租户教师,, +GET,/api/tenant-admin/theme,exact_match,TenantAppearanceController_theme,查询租户当前主题与草稿,,查询租户当前主题与草稿 +GET,/api/tenant-admin/theme-templates,exact_match,TenantAppearanceController_templates,查询可用的租户主题模板,,查询可用租户主题模板 +POST,/api/tenant-admin/theme/preview,exact_match,TenantAppearanceController_preview,生成并保存租户主题草稿,,生成租户主题草稿 +POST,/api/tenant-admin/theme/publish,exact_match,TenantAppearanceController_publish,发布租户主题,,发布租户主题 +GET,/api/tenant-admin/user-notifications,legacy_only,TenantAdminInsightsController_notifications,查询租户用户通知,, +GET,/api/tenant-commerce/activation-codes,target_only,,,,查询兑换码 +POST,/api/tenant-commerce/activation-codes/redeem,target_only,,,,后台核销兑换码 +POST,/api/tenant-commerce/code-batches,target_only,,,,创建兑换码批次 +GET,/api/tenant-commerce/coupons,target_only,,,,查询租户优惠券 +PUT,/api/tenant-commerce/coupons,target_only,,,,新增或更新租户优惠券 +GET,/api/tenant-commerce/coupons/redemptions,target_only,,,,查询优惠券领取和核销记录 +GET,/api/tenant-commerce/coupons/report,target_only,,,,查询优惠券基础报表 +GET,/api/tenant-commerce/orders,target_only,,,,查询租户订单 +GET,/api/tenant-commerce/payment-accounts,target_only,,,,查询租户支付账号 +PUT,/api/tenant-commerce/payment-accounts,target_only,,,,新增或更新租户支付账号 +GET,/api/tenant-commerce/payments,target_only,,,,查询租户支付记录 +GET,/api/tenant-commerce/point-activity-claims,target_only,,,,查询积分任务领取记录 +GET,/api/tenant-commerce/point-activity-tasks,target_only,,,,查询积分活动任务 +PUT,/api/tenant-commerce/point-activity-tasks,target_only,,,,新增或更新积分活动任务 +GET,/api/tenant-commerce/point-exchange-items,target_only,,,,查询积分兑换项 +PUT,/api/tenant-commerce/point-exchange-items,target_only,,,,新增或更新积分兑换项 +GET,/api/tenant-commerce/point-exchange-orders,target_only,,,,查询积分兑换订单 +POST,/api/tenant-commerce/point-exchange-orders/status,target_only,,,,更新积分兑换订单状态 +PUT,/api/tenant-commerce/secrets,target_only,,,,写入或轮换租户密钥 +GET,/api/tenant-content/assets,exact_match,TenantContentAssetsController_list,查询租户内容资产,,查询租户内容资产 +PUT,/api/tenant-content/assets,exact_match,TenantContentAssetsController_upsert,新增或更新内容资产,,新增或更新内容资产 +GET,/api/tenant-content/assets/access-events,exact_match,TenantContentAssetsController_accessEvents,查询资产访问审计事件,,查询资产访问审计事件 +POST,/api/tenant-content/assets/confirm-upload,legacy_only,TenantContentAssetsController_confirmUpload,确认并验证内容资产上传,, +GET,/api/tenant-content/assets/security-scan-events,exact_match,TenantContentAssetsController_scanEvents,查询资产安全扫描事件,,查询资产安全扫描事件 +POST,/api/tenant-content/assets/sign-download,exact_match,TenantContentAssetsController_signDownload,签发管理侧资产下载地址,,签发管理侧资产下载地址 +POST,/api/tenant-content/assets/sign-preview,exact_match,TenantContentAssetsController_signPreview,签发管理侧资产预览地址,,签发管理侧资产预览地址 +POST,/api/tenant-content/assets/sign-upload,legacy_only,TenantContentAssetsController_signUpload,签发内容资产上传凭证,, +POST,/api/tenant-content/assets/uploads/confirm,target_only,,,,确认资产上传完成 +POST,/api/tenant-content/assets/uploads/sign,target_only,,,,创建资产上传签名 +GET,/api/tenant-content/content-entries,legacy_only,ContentNavigationController_entries,查询租户内容入口,, +PUT,/api/tenant-content/content-entries,legacy_only,ContentNavigationController_upsertEntry,新增或更新内容入口,, +GET,/api/tenant-content/content-nodes,legacy_only,ContentNavigationController_nodes,查询内容导航节点,, +PUT,/api/tenant-content/content-nodes,legacy_only,ContentNavigationController_upsertNode,新增或更新内容导航节点,, +GET,/api/tenant-content/entries,target_only,,,,查询租户内容入口 +POST,/api/tenant-content/entries,target_only,,,,创建或更新内容入口 +GET,/api/tenant-content/exports/jobs,legacy_only,TenantContentExportsController_jobs,查询题库导出任务,, +POST,/api/tenant-content/exports/questions,legacy_only,TenantContentExportsController_create,创建题库导出或立即生成 JSON,, +GET,/api/tenant-content/handbook-chapters,exact_match,HandbookManagementController_chapters,查询管理侧知识手册章节,,查询管理侧知识手册章节 +PUT,/api/tenant-content/handbook-chapters,exact_match,HandbookManagementController_upsertChapter,新增或更新知识手册章节,,新增或更新知识手册章节 +GET,/api/tenant-content/handbook-entries,exact_match,HandbookManagementController_entries,查询管理侧知识手册条目,,查询管理侧知识手册条目 +PUT,/api/tenant-content/handbook-entries,exact_match,HandbookManagementController_upsertEntry,新增或更新知识手册条目,,新增或更新知识手册条目 +GET,/api/tenant-content/handbook-subjects,exact_match,HandbookManagementController_subjects,查询管理侧知识手册科目,,查询管理侧知识手册科目 +PUT,/api/tenant-content/handbook-subjects,exact_match,HandbookManagementController_upsertSubject,新增或更新知识手册科目,,新增或更新知识手册科目 +GET,/api/tenant-content/import-jobs,target_only,,,,查询内容导入任务 +GET,/api/tenant-content/import-jobs/{jobId},target_only,,,,查询内容导入任务详情 +GET,/api/tenant-content/imports,legacy_only,TenantContentImportsController_jobs,查询内容导入任务,, +GET,/api/tenant-content/imports/detail,legacy_only,TenantContentImportsController_detail,查询内容导入任务详情,, +GET,/api/tenant-content/imports/field-mapping,exact_match,TenantContentImportsController_fieldMapping,查询导入字段映射说明,,查询导入字段映射 +POST,/api/tenant-content/imports/handbook,legacy_only,TenantContentImportsController_importHandbook,执行或排队知识手册导入,, +GET,/api/tenant-content/imports/issues,exact_match,TenantContentImportsController_issues,查询内容导入问题明细,,查询内容导入问题明细 +GET,/api/tenant-content/imports/post-check,exact_match,TenantContentImportsController_postCheckStatus,查询内容导入后检查状态,,查询内容导入后检查状态 +POST,/api/tenant-content/imports/post-check,exact_match,TenantContentImportsController_runPostCheck,执行内容导入后完整性检查,,执行内容导入后完整性检查 +POST,/api/tenant-content/imports/preview/handbook,legacy_only,TenantContentImportsController_previewHandbook,预览知识手册导入数据,, +POST,/api/tenant-content/imports/preview/questions,legacy_only,TenantContentImportsController_previewQuestions,预览题目导入数据,, +POST,/api/tenant-content/imports/preview/scoreline,legacy_only,TenantContentImportsController_previewScoreline,预览分数线导入数据,, +POST,/api/tenant-content/imports/preview/videos,legacy_only,TenantContentImportsController_previewVideos,预览视频解析导入数据,, +POST,/api/tenant-content/imports/preview/vocabulary,legacy_only,TenantContentImportsController_previewVocabulary,预览词汇导入数据,, +POST,/api/tenant-content/imports/preview/{importType},target_only,,,,预览内容导入数据 +POST,/api/tenant-content/imports/questions,legacy_only,TenantContentImportsController_importQuestions,执行或排队题目导入,, +POST,/api/tenant-content/imports/scoreline,legacy_only,TenantContentImportsController_importScoreline,执行或排队分数线导入,, +GET,/api/tenant-content/imports/templates,exact_match,TenantContentImportsController_template,获取内容导入模板,,获取内容导入模板 +POST,/api/tenant-content/imports/videos,legacy_only,TenantContentImportsController_importVideos,执行或排队视频解析导入,, +POST,/api/tenant-content/imports/vocabulary,legacy_only,TenantContentImportsController_importVocabulary,执行或排队词汇导入,, +POST,/api/tenant-content/imports/{importType},target_only,,,,执行同步内容导入 +GET,/api/tenant-content/media-analytics/asset-events,legacy_only,TenantContentAssetsController_assetAnalytics,查询媒体资产访问明细,, +GET,/api/tenant-content/media-analytics/summary,legacy_only,TenantContentAssetsController_summary,查询媒体访问分析汇总,, +GET,/api/tenant-content/media-analytics/video-events,legacy_only,TenantContentAssetsController_videoAnalytics,查询媒体视频播放明细,, +GET,/api/tenant-content/nodes,target_only,,,,查询租户内容节点 +POST,/api/tenant-content/nodes,target_only,,,,创建或更新内容节点 +GET,/api/tenant-content/notifications,legacy_only,TenantContentPublicBanksController_notifications,查询租户内容通知,, +POST,/api/tenant-content/notifications/status,legacy_only,TenantContentPublicBanksController_updateNotifications,批量更新租户内容通知状态,, +GET,/api/tenant-content/operations/{kind},target_only,,,,查询运营内容 +PUT,/api/tenant-content/operations/{kind},target_only,,,,新增或更新运营内容 +GET,/api/tenant-content/practice-blueprints,exact_match,ContentNavigationController_blueprints,查询练习蓝图,,查询练习蓝图 +POST,/api/tenant-content/practice-blueprints,target_only,,,,创建或更新练习蓝图 +PUT,/api/tenant-content/practice-blueprints,legacy_only,ContentNavigationController_upsertBlueprint,新增或更新练习蓝图,, +GET,/api/tenant-content/public-question-banks,legacy_only,TenantContentPublicBanksController_list,查询可采用的公共题库,, +POST,/api/tenant-content/public-question-banks/adopt,legacy_only,TenantContentPublicBanksController_adopt,采用公共题库并复制内容,, +GET,/api/tenant-content/public-question-banks/conflicts,legacy_only,TenantContentPublicBanksController_conflicts,查询公共题库同步冲突,, +POST,/api/tenant-content/public-question-banks/conflicts/resolve,legacy_only,TenantContentPublicBanksController_resolve,解决单条公共题库同步冲突,, +POST,/api/tenant-content/public-question-banks/conflicts/resolve-batch,legacy_only,TenantContentPublicBanksController_resolveBatch,批量解决公共题库同步冲突,, +POST,/api/tenant-content/public-question-banks/sync,legacy_only,TenantContentPublicBanksController_sync,同步已采用的公共题库,, +GET,/api/tenant-content/question-collections,exact_match,ContentNavigationController_collections,查询题目集合,,查询租户题集 +POST,/api/tenant-content/question-collections,target_only,,,,创建或更新题集 +PUT,/api/tenant-content/question-collections,legacy_only,ContentNavigationController_upsertCollection,新增或更新题目集合,, +PUT,/api/tenant-content/question-collections/items,legacy_only,ContentNavigationController_replaceItems,整体替换题集中的题目,, +POST,/api/tenant-content/question-collections/items/replace,target_only,,,,替换题集题目 +POST,/api/tenant-content/question-videos,exact_match,VideoManagementController_bind,绑定题目与解析视频,,绑定题目与解析视频 +PATCH,/api/tenant-content/questions,exact_match,QuestionManagementController_update,更新题目并可选择创建新版本,,更新题目并可选择创建新版本 +POST,/api/tenant-content/questions,exact_match,QuestionManagementController_create,创建题目及首个版本,,创建题目及首个版本 +GET,/api/tenant-content/scoreline/fields,exact_match,ScorelineManagementController_fields,查询管理侧分数线字段,,查询管理侧分数线字段 +PUT,/api/tenant-content/scoreline/fields,exact_match,ScorelineManagementController_upsertField,新增或更新动态分数线字段,,新增或更新动态分数线字段 +GET,/api/tenant-content/scoreline/majors,exact_match,ScorelineManagementController_majors,查询管理侧分数线专业,,查询管理侧分数线专业 +PUT,/api/tenant-content/scoreline/majors,exact_match,ScorelineManagementController_upsertMajor,新增或更新分数线专业,,新增或更新分数线专业 +GET,/api/tenant-content/scoreline/records,exact_match,ScorelineManagementController_records,查询管理侧分数线记录,,查询管理侧分数线记录 +PUT,/api/tenant-content/scoreline/records,exact_match,ScorelineManagementController_upsertRecord,新增或更新分数线记录,,新增或更新分数线记录 +GET,/api/tenant-content/scoreline/schools,exact_match,ScorelineManagementController_schools,查询管理侧分数线院校,,查询管理侧分数线院校 +PUT,/api/tenant-content/scoreline/schools,exact_match,ScorelineManagementController_upsertSchool,新增或更新分数线院校,,新增或更新分数线院校 +GET,/api/tenant-content/scoreline/trend,target_only,,,,查询分数线趋势摘要 +GET,/api/tenant-content/scoreline/years,target_only,,,,查询分数线年份 +GET,/api/tenant-content/videos,exact_match,VideoManagementController_list,查询租户视频解析,,查询租户视频解析 +PUT,/api/tenant-content/videos,exact_match,VideoManagementController_upsert,新增或更新视频解析,,新增或更新视频解析 +GET,/api/tenant-content/vocabulary-units,exact_match,VocabularyManagementController_units,查询管理侧词汇单元,,查询管理侧词汇单元 +PUT,/api/tenant-content/vocabulary-units,exact_match,VocabularyManagementController_upsertUnit,新增或更新词汇单元,,新增或更新词汇单元 +GET,/api/tenant-content/vocabulary-words,exact_match,VocabularyManagementController_words,查询管理侧词汇,,查询管理侧词汇 +PUT,/api/tenant-content/vocabulary-words,exact_match,VocabularyManagementController_upsertWord,新增或更新词汇,,新增或更新词汇 +GET,/api/tenant/current-public,target_only,,,,获取公开租户配置 +GET,/api/tenant/resolve,exact_match,TenantController_resolve,解析当前租户,,解析当前租户 +GET,/api/tenants/current,target_only,,,, +POST,/api/videos/play,legacy_only,VideoController_play,申请视频播放地址,, +POST,/api/videos/progress,legacy_only,VideoController_progress,上报视频播放进度,, +GET,/api/videos/search,legacy_only,VideoController_search,搜索通用解析视频,, +GET,/health,legacy_only,HealthController_check,检查 API 与数据库健康状态,, diff --git a/docs/migration/phase-1-repository-baseline.md b/docs/migration/phase-1-repository-baseline.md new file mode 100644 index 0000000..2e9cc6c --- /dev/null +++ b/docs/migration/phase-1-repository-baseline.md @@ -0,0 +1,75 @@ +# 第一阶段：仓库转正基线 + +基线日期：2026-07-27。 + +## 仓库身份 + +- 本仓库是 ASP.NET Core 目标后端，后续新功能只在这里开发。 +- 旧 NestJS 后端只用于核对业务行为、接口契约和数据迁移。 +- 保留现有 Git 历史，不重新初始化仓库。 +- 正式远程使用 `https://git.gongxue100.com/xiongyuxing/tiku-backend.net.git`。 +- 默认分支统一为 `main`，远程创建后再设置保护规则。 + +## 当前可验证基线 + +| 项目 | 结果 | +| --- | ---: | +| 旧 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 +``` + +如果服务端已经自动创建了 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。 +- [ ] 首次推送 `main`。 +- [ ] 在自建 Git 上启用 `main` 分支保护和 CI（等待远程仓库）。 diff --git a/scripts/compare_openapi.py b/scripts/compare_openapi.py new file mode 100755 index 0000000..ab3b49c --- /dev/null +++ b/scripts/compare_openapi.py @@ -0,0 +1,95 @@ +#!/usr/bin/env python3 +"""Compare two OpenAPI documents by normalized HTTP method and path.""" + +from __future__ import annotations + +import argparse +import csv +import json +from pathlib import Path +from typing import Any + + +HTTP_METHODS = {"delete", "get", "head", "options", "patch", "post", "put", "trace"} + + +def parse_args() -> argparse.Namespace: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--legacy", required=True, type=Path, help="Legacy OpenAPI JSON") + parser.add_argument("--target", required=True, type=Path, help="Target OpenAPI JSON") + parser.add_argument("--output", required=True, type=Path, help="Output CSV") + return parser.parse_args() + + +def load_operations(path: Path) -> dict[tuple[str, str], dict[str, str]]: + with path.open(encoding="utf-8") as source: + document: dict[str, Any] = json.load(source) + + operations: dict[tuple[str, str], dict[str, str]] = {} + for route, path_item in document.get("paths", {}).items(): + if not isinstance(path_item, dict): + continue + for method, operation in path_item.items(): + normalized_method = method.lower() + if normalized_method not in HTTP_METHODS or not isinstance(operation, dict): + continue + operations[(normalized_method.upper(), route)] = { + "operation_id": str(operation.get("operationId", "")), + "summary": str(operation.get("summary", "")), + } + return operations + + +def main() -> None: + args = parse_args() + legacy = load_operations(args.legacy) + target = load_operations(args.target) + keys = sorted(legacy.keys() | target.keys(), key=lambda key: (key[1], key[0])) + + args.output.parent.mkdir(parents=True, exist_ok=True) + with args.output.open("w", encoding="utf-8", newline="") as destination: + writer = csv.DictWriter( + destination, + fieldnames=( + "method", + "path", + "status", + "legacy_operation_id", + "legacy_summary", + "target_operation_id", + "target_summary", + ), + lineterminator="\n", + ) + writer.writeheader() + for method, route in keys: + legacy_operation = legacy.get((method, route), {}) + target_operation = target.get((method, route), {}) + status = ( + "exact_match" + if legacy_operation and target_operation + else "legacy_only" + if legacy_operation + else "target_only" + ) + writer.writerow( + { + "method": method, + "path": route, + "status": status, + "legacy_operation_id": legacy_operation.get("operation_id", ""), + "legacy_summary": legacy_operation.get("summary", ""), + "target_operation_id": target_operation.get("operation_id", ""), + "target_summary": target_operation.get("summary", ""), + } + ) + + exact_matches = len(legacy.keys() & target.keys()) + print( + f"legacy={len(legacy)} target={len(target)} exact={exact_matches} " + f"legacy_only={len(legacy) - exact_matches} target_only={len(target) - exact_matches}" + ) + + +if __name__ == "__main__": + main()