开发指南与架构

技术栈与目录

目录/文件	说明
`src/Jiaowu.Api`	ASP.NET Core API、EF Core 实体、业务服务、迁移、鉴权和后台任务。
`web`	Vue 3、TypeScript、Vite、Element Plus 前端及 Capacitor 工程/脚本。
`web-react`	React、TypeScript、Vite、React Router、Ant Design 并行迁移工程；当前仅用于联调验收。
`src/Jiaowu.Plugin.Abstractions`	插件 SDK 合同、清单和宿主扩展接口。
`samples/Jiaowu.SamplePlugin`	可构建、打包和签名的示例插件。
`tests`	单元与集成测试。
`deploy`	systemd、部署等运行环境资源。
`scripts`	开发、发布和辅助脚本。
`versions.props`	后端、前端和 Swagger 产品版本的集中来源。

后端使用 ASP.NET Core 10、EF Core 10；正式前端使用 Vue 3、TypeScript、Vite 与 Element Plus。web 的构建产物进入 API 的静态资源目录，单服务模式由 API 同时提供 /api 和前端路由回退。

web-react 是并行迁移工程，可通过 http://127.0.0.1:5174/next/ 联调，并复用现有 API 合同和会话兼容约定。迁移矩阵中处于 verification 的页面表示已实现、仍需正常/空数据/异常/无权限/移动端联调，不等于已成为生产默认前端；当前生产构建和 Capacitor 仍以 web 为准。

启动与验证

前端命令必须在 web 目录运行：

Set-Location web
npm install
npm run build

需要验证 React 迁移工程时，在 web-react 目录独立执行：

Set-Location web-react
npm install
npm run build

后端可使用 dotnet build Jiaowu.slnx、dotnet test Jiaowu.slnx 或针对具体项目的命令。修改包含 API、数据库或页面的完整功能时，至少验证编译、相关测试和实际 UI/API 链路；不要把“构建成功”误认为业务已验收。

接口与鉴权约定

控制器使用 [Authorize] 与角色限制，并在业务查询和写入中落实数据范围。
登录页通过匿名 POST /api/auth/login/captcha 获取验证码图片和 captchaId；登录请求提交 captchaId 与 captchaCode，服务端校验后再执行密码认证。验证码约两分钟过期且一次性消费，普通登录和 Keycloak SSO 登录都必须完成该校验。
CurrentUserDataScope 等服务负责当前用户的学院、行政班、本人等范围；新增接口不得只在前端限制数据。
教师与教学任务关系、学生与档案关系必须从数据库按当前用户验证。对依赖导航属性的授权判断，显式加载需要的关系或改用数据库查询，避免跟踪上下文偶然掩盖授权缺陷。
列表接口优先提供服务端筛选、Count / Skip / Take 分页；不要先加载所有数据再在浏览器分页。
面向选择框的选项接口必须返回完整、已授权的范围，不能复用分页列表造成选项截断。

数据与计算原则

服务端是成绩总评、绩点、实验课程聚合、毕业/学位结论等派生数据的唯一权威来源；不信任浏览器或 Excel 的公式结果。
重要聚合应有单一持久化来源，并由写入事件或后台任务刷新缓存、统计和下游读取。
MySQL 写入涉及可重试事务时，使用项目提供的可重试执行策略/帮助方法；不要在普通事务中直接重试导致 EF Core 执行策略异常。
引入状态机时定义清楚草稿、提交、审核、发布、锁定等转换，并确保正常/异常路径具有同等授权校验。

前端约定

路由定义在 web/src/router，布局和菜单在 web/src/layouts，页面在 web/src/views，接口封装在 web/src/api。菜单可依据角色隐藏不相关模块，但每个 API 都必须自行授权。扩展页面时同时处理加载、空态、失败提示、筛选分页、权限不足和移动端布局。

Android 原生模板位于 web/native/android；运行 npm run cap:sync 后同步至被 Git 忽略的 web/android。仅修改前端资源时可按 OTA 流程发布；修改原生模板、插件、权限或版本时需要重新构建原生 App。

插件开发与装载边界

插件项目面向 net10.0，引用 src/Jiaowu.Plugin.Abstractions，入口实现 IJiaowuPluginModule。插件控制器统一使用 /api/plugin-extensions/{pluginId} 前缀，并自行声明 [Authorize]、角色和数据范围校验；插件启用状态只控制可用性，不能充当授权。

插件包根目录包含 plugin.json，后端程序集放在 backend/。宿主支持插件服务、控制器、幂等数据库迁移、后台任务和事件处理器；迁移只能操作插件自有表，不能修改或删除 Identity、成绩、学籍等核心业务数据。上传的 ZIP 和 SIG 经签名、路径、大小、清单及 Host API 校验后先进入暂存区，激活或回滚请求在下次重启时生效。

完整合同、发布者密钥配置和打包命令以 docs/plugin-sdk.md 为准。调试插件时应同时验证插件禁用、无权限、迁移失败、任务异常和版本回滚路径，不能只验证菜单出现。

配置、可观测性与版本

不得把数据库密码、JWT、SSO 客户端密钥写入 appsettings、前端代码、测试快照或 Wiki 示例。使用 .env.example 作为公开配置模板。

版本仅在根目录 versions.props 中维护前端、后端和 Swagger 三类产品版本。后端从该文件导入并公开 Swagger 文档版本，Vite 从同一文件注入前端版本；不要再建立重复版本来源。

变更检查清单

明确角色、数据范围、状态变化与错误处理。
若含数据库模型变化，新增/更新迁移并考虑 SQLite 开发与 MySQL 生产兼容性。
若含列表或选择器，验证分页、筛选和完整受限选项。
若含成绩/统计，验证服务端重新计算、聚合刷新和导入异常回滚。
若含 UI，运行 npm run build 并在实际浏览器检查关键交互。
若含后台任务或缓存，验证任务触发、失败处理与缓存失效。
保持最小聚焦改动，避免覆盖工作区中与本任务无关的改动。