Merge branch 'master' into codex/shiyan

# Conflicts:
#	web/package-lock.json

.env.example

@@ -17,6 +17,7 @@ BackgroundJobs__Transport=InMemory
 BackgroundJobs__AutomaticScheduleConcurrency=1
 BackgroundJobs__SchedulePublishConcurrency=1
 BackgroundJobs__MakeupExamAutoConcurrency=1
+BackgroundJobs__ExamArrangementConcurrency=1
 # RabbitMq__HostName=rabbitmq.example.edu.cn
 # RabbitMq__Port=5671
 # RabbitMq__UserName=jiaowu
@@ -35,6 +36,24 @@ Cache__AnalyticsExpirationMinutes=3
 Cache__AnalyticsLocalExpirationSeconds=30
 Cache__MaximumPayloadKilobytes=2048
 
+# OpenTelemetry 默认收集 HTTP、运行时和数据库指标；配置 OTLP 地址后才会外发。
+Observability__Enabled=true
+Observability__ServiceName=jiaowu-api
+Observability__SlowQueryThresholdMilliseconds=500
+# 默认不记录完整 SQL，避免日志或追踪系统接触业务数据。
+Observability__IncludeSqlText=false
+Observability__MaximumSqlTextLength=2000
+# OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.edu.cn:4317
+# OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20REPLACE_WITH_TOKEN
+
+# 系统内“运维与审计 → 系统性能”从 Prometheus 只读查询汇总指标。
+PerformanceReporting__Enabled=false
+# PerformanceReporting__PrometheusBaseUrl=https://prometheus.example.edu.cn/
+# PerformanceReporting__BearerToken=REPLACE_WITH_READ_ONLY_TOKEN
+# PerformanceReporting__GrafanaBaseUrl=https://grafana.example.edu.cn/
+PerformanceReporting__CacheSeconds=30
+PerformanceReporting__TimeoutSeconds=10
+
 # 运维控制台备份目录必须位于持久化、仅服务账号可写的位置。
 Operations__BackupDirectory=/var/lib/jiaowu/backups
 Operations__BackupWarningHours=24
@@ -48,10 +67,32 @@ Operations__MySqlClientPath=mysql
 Jwt__Issuer=Jiaowu.Api
 Jwt__Audience=Jiaowu.Web
 Jwt__Key=REPLACE_WITH_AT_LEAST_32_RANDOM_BYTES
-Jwt__ExpireMinutes=60
+Jwt__AccessTokenMinutes=10
+Jwt__WebIdleMinutes=30
+Jwt__AppIdleMinutes=4320
+
+# Keycloak SSO（可选）。Authority 必须指向 realm，例如：
+# https://sso.example.edu.cn/realms/mingxu
+Sso__Enabled=false
+# Sso__DisplayName=学校统一身份认证
+# Sso__Authority=https://sso.example.edu.cn/realms/mingxu
+# Sso__ClientId=jiaowu-web
+# Sso__ClientSecret=REPLACE_WITH_KEYCLOAK_CLIENT_SECRET
+# Sso__UserNameClaim=preferred_username
+# Sso__RequireHttpsMetadata=true
+# 首次 SSO 登录优先绑定同名本地账号；用户名不同时由用户输入现有账号密码完成绑定。
+# 不会自动创建账号或授予角色。
+# Sso__LinkExistingUsersByUserName=true
+# 前后端同域部署时留空；开发或分离部署时填写前端公开根地址。
+# Sso__FrontendBaseUrl=https://jiaowu.example.edu.cn
+# 必须与 Keycloak 客户端的 Valid redirect URI 完全一致。
+# Sso__CallbackUrl=https://jiaowu.example.edu.cn/signin-keycloak
 
 AllowedHosts=jiaowu.example.edu.cn
 Cors__Origins__0=https://jiaowu.example.edu.cn
+Cors__Origins__1=capacitor://localhost
+Cors__Origins__2=https://localhost
+Cors__Origins__3=http://localhost
 
 # 二维码使用的公网根地址；反向代理部署时必须填写最终 HTTPS 地址。
 OfficialDocuments__InstitutionName=明序大学

README.md

@@ -47,6 +47,68 @@ dotnet run --project src/Jiaowu.Api
 
 访问 `http://localhost:5255`。`/api` 和静态页面由同一个 ASP.NET Core 服务提供，`/base-data` 等前端路由刷新时也会回退到 `index.html`。
 
+## Capacitor Android App
+
+`web/.env.capacitor` 配置 App 使用的 HTTPS API 与公开站点地址。生成或更新
+Android 工程前先构建并同步原生插件：
+
+```powershell
+Set-Location web
+npm ci
+npm run build:capacitor
+npm run cap:sync
+npm run cap:open:android
+```
+
+学生在 App 的“我的考勤”中可调用原生相机扫描教师展示的签到二维码；二维码由服务端
+签名、每 10 秒刷新并在 20 秒后失效，扫码后先显示课程和签到时限，仍需学生确认才
+提交。教师可直接在手机 App 发起定位签到，以教师手机的原生精确位置作为签到点；
+教室电脑没有定位模块时不影响该流程。服务端校验课程名单、签到时间、距离和定位精度，
+并记录签到设备摘要、IP、失败次数和异常频率，供任课教师在考勤明细中复核。Android
+最低版本为 API 26；相机和精确位置权限均按需申请。
+
+### App 前端热更新
+
+App 内置自建 OTA 更新器。它只更新 `dist` 中的 HTML、JavaScript、CSS 和静态资源；
+新增或升级 Capacitor 插件、修改原生权限、Android/iOS 工程或原生版本号时，仍必须
+重新构建并安装 App。首次启用更新器也需要发布一次包含更新插件的新 App，之后普通
+前端修复不再需要重新打包。
+
+生成更新 ZIP：
+
+```powershell
+Set-Location web
+npm ci
+npm run ota:package -- --version 1.0.1
+```
+
+ZIP 会生成到 `.artifacts/app-updates`，根目录直接包含 `index.html`。使用
+SuperAdmin 进入“运维与审计 → App 前端热更新”，上传 ZIP，填写目标平台、通道和
+兼容的原生版本后先保存为草稿，再执行发布。当前 Android 工程的 `versionName` 为
+`1.0`，因此对应更新包的“兼容原生版本”应填写 `1.0`。
+
+App 启动后向 `/api/app-updates/latest` 检查版本，在后台下载并校验服务端提供的
+SHA-256，下次启动时切换。新资源若未能成功启动，原生更新器会自动回滚。再次发布
+已归档版本即可回滚正式通道；不同原生版本、Android/iOS、测试/正式通道彼此隔离。
+更新版本元数据和 ZIP 保存在数据库中，部署新服务端版本前必须先执行
+`--migrate-only`。
+
+### Android 开屏、快捷入口与桌面组件
+
+Android App 在系统静态启动页之后显示智能问候：优先使用当前登录姓名和春节、端午、
+中秋、国庆等节日文案，其次按早上、中午、下午和晚上展示问候；轻触可立即跳过，并
+遵守系统“减少动画”设置。
+
+长按 App 图标提供“我的课表、考试安排、课堂签到、消息中心”四个快捷入口。“课堂
+签到”会按当前角色将学生带到扫码/定位签到，将教师带到发起签到。桌面组件提供“今日
+课表”和“近期考试”，展示 App 最近一次成功加载并安全写入 Android 本地缓存的数据；
+退出账号时会清空组件，跨日且尚未打开 App 刷新时不会继续展示过期的今日课表。
+
+原生 Java、清单和组件资源模板保存在 `web/native/android`。每次运行
+`npm run cap:sync` 后，`configure-capacitor.mjs` 会把模板同步到被 Git 忽略的
+`web/android` 生成目录。上述能力涉及 Android 原生代码，首次加入或以后修改时必须
+重新构建 App，不能通过前端 OTA 单独下发。
+
 ## MySQL 8.4 生产部署
 
 非 Development 环境只允许使用 MySQL。构建发布包与数据库配置相互独立：
@@ -82,6 +144,50 @@ Kubernetes 或密钥管理系统仍可覆盖文件中的值。
 `chmod 600 .env`，Windows 应通过 ACL 只允许服务账号和管理员读取。连接串中的证书
 路径必须是运行服务器上的实际路径。
 
+### Keycloak 单点登录（可选）
+
+系统支持 Keycloak 的 OpenID Connect 授权码流程。Keycloak 只负责验证身份；账号是否
+启用、角色和学院数据范围仍以本系统 Identity 数据为准。首次 SSO 登录会用
+`preferred_username`（可通过 `Sso__UserNameClaim` 修改）优先匹配已有登录账号并记录
+外部账号绑定。如果 Keycloak 用户名与教务系统账号不同，认证后会进入账户绑定页，用户
+需要再输入一次现有教务系统账号和密码；验证成功后建立永久绑定并直接登录。绑定不会
+自动创建本地账号、修改人员档案或从 Keycloak 导入高权限角色。同一 Keycloak 身份不能
+绑定多个本地账号，同一本地账号也不能绑定多个 Keycloak 身份。原账号密码登录和学生
+自助激活入口不受影响。
+
+在 Keycloak 中创建 OpenID Connect 客户端，并至少配置：
+
+- Valid redirect URI：`https://jiaowu.example.edu.cn/signin-keycloak`
+- Valid post logout redirect URI：`https://jiaowu.example.edu.cn/*`（若后续启用 Keycloak 全局退出）
+- Standard flow：开启；Implicit flow：关闭；PKCE：`S256`
+
+然后在 `.env` 中配置：
+
+```dotenv
+Sso__Enabled=true
+Sso__DisplayName=学校统一身份认证
+Sso__Authority=https://sso.example.edu.cn/realms/mingxu
+Sso__ClientId=jiaowu-web
+Sso__ClientSecret=REPLACE_WITH_KEYCLOAK_CLIENT_SECRET
+Sso__UserNameClaim=preferred_username
+Sso__RequireHttpsMetadata=true
+Sso__LinkExistingUsersByUserName=true
+Sso__FrontendBaseUrl=https://jiaowu.example.edu.cn
+Sso__CallbackUrl=https://jiaowu.example.edu.cn/signin-keycloak
+```
+
+前后端同域时 `Sso__FrontendBaseUrl` 可以留空。本地 Vite 开发默认回到
+`http://localhost:5173`，Keycloak 测试客户端需同时允许
+`http://localhost:5255/signin-keycloak`。`Sso__CallbackUrl` 是应用实际发送给 Keycloak
+的 `redirect_uri`，必须与客户端的 Valid redirect URI 完全一致；建议生产环境始终显式
+配置它，避免反向代理导致 scheme 或 host 推导错误。个人账户页的“管理员配置参考”也会
+显示当前生效的完整回调地址。多实例部署应配置 Redis，以便任意实例都能兑换两分钟内
+有效、使用后即删除的 SSO 登录码及五分钟内有效的绑定意图。
+
+用户登录后可从页面右上角进入“个人账户”，主动绑定或解除 Keycloak 账号。主动绑定先
+使用当前 JWT 创建五分钟有效的一次性绑定意图，再跳转 Keycloak；回调只能绑定到发起该
+意图的本地账号。解绑需要再次验证本地密码，避免仅凭未锁屏的登录会话解除身份关联。
+
 ### Linux systemd 服务
 
 仓库提供 [`deploy/systemd/jiaowu.service`](deploy/systemd/jiaowu.service)，适用于
@@ -260,6 +366,55 @@ Redis 只作为可丢弃的查询缓存。连接失败时应用回源数据库
 `allkeys-lfu` 淘汰策略，不启用持久化。`compose.app.example.yml` 不创建 Redis；
 如需连接外部 Redis，在 `.env` 中配置上述连接串即可。
 
+### OpenTelemetry 与慢查询定位
+
+应用已接入 OpenTelemetry 的 ASP.NET Core、HttpClient、.NET Runtime 指标，并通过
+`Jiaowu.Api.Database` ActivitySource 和 Meter 记录 EF Core 数据库命令。配置
+`OTEL_EXPORTER_OTLP_ENDPOINT` 后才启动 OpenTelemetry SDK 并向 OTLP Collector 外发；
+未配置时不会创建无处消费的请求 Span，也不会尝试连接本地 Collector，结构化慢查询日志
+仍然有效。
+
+```text
+Observability__Enabled=true
+Observability__ServiceName=jiaowu-api
+Observability__SlowQueryThresholdMilliseconds=500
+OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.edu.cn:4317
+```
+
+数据库指标包括 `jiaowu.db.command.duration`、`jiaowu.db.command.slow` 和
+`jiaowu.db.command.failed`。为关键 EF 查询添加 `TagWith("模块.查询名")` 后，日志和
+追踪会直接显示该稳定名称；无标签查询只显示操作类型和 SQL 模板哈希。默认
+`Observability__IncludeSqlText=false`，不会把 SQL、参数值或连接串发送到日志和追踪
+系统。仅在受控诊断窗口内临时启用完整 SQL 模板，并限制 Collector 权限与保留时间。
+
+应用侧阈值用于关联接口、TraceId 和查询名称；生产 MySQL 还应由数据库管理员启用慢查询
+日志，并将 `long_query_time` 设为与应用阈值一致。先按查询哈希/标签汇总高频慢查询，再
+对脱敏后的 `SELECT` 在测试库或只读副本执行 `EXPLAIN ANALYZE`，根据实际扫描行数和循环
+次数决定是否补组合索引或改写投影。`EXPLAIN ANALYZE` 会真实执行语句，不能直接用于生产
+写操作。参考 [MySQL 慢查询日志](https://dev.mysql.com/doc/refman/8.0/en/slow-query-log.html)
+和 [MySQL 8.4 EXPLAIN](https://dev.mysql.com/doc/refman/8.4/en/explain.html)。
+
+OpenTelemetry Collector 将指标写入 Prometheus 后，超级管理员可直接在“组织与权限 →
+运维与审计 → 系统性能”查看请求量、5xx 比例、HTTP/数据库 P95、慢查询趋势，以及最慢
+接口和数据库查询排行。报表由 API 使用固定 PromQL 只读查询 Prometheus，浏览器不会
+接触 Prometheus 地址或令牌；结果默认缓存 30 秒。原始 Trace 和更长时间范围仍建议在
+Grafana 中下钻，配置其地址后页面会显示跳转入口。
+
+```text
+PerformanceReporting__Enabled=true
+PerformanceReporting__PrometheusBaseUrl=https://prometheus.example.edu.cn/
+PerformanceReporting__BearerToken=REPLACE_WITH_READ_ONLY_TOKEN
+PerformanceReporting__GrafanaBaseUrl=https://grafana.example.edu.cn/
+PerformanceReporting__CacheSeconds=30
+PerformanceReporting__TimeoutSeconds=10
+```
+
+`PrometheusBaseUrl` 必须指向可访问 `/api/v1/query` 和 `/api/v1/query_range` 的
+Prometheus 兼容接口，令牌应仅具有查询权限。未启用、未配置或指标源暂时不可用时，页面
+会显示明确的空状态，不会改查业务数据库或拖慢正常请求。若 Collector/Prometheus 对
+指标名或 `service_name` 标签做了转换，可通过 `PerformanceReporting` 下对应的
+`*MetricName` 和 `ServiceNameLabel` 配置项适配，无需改前端。
+
 ### 后台任务与 RabbitMQ
 
 自动排课、课表发布和补考自动生成使用数据库 Outbox 保存任务消息。创建业务任务与
@@ -280,6 +435,7 @@ BackgroundJobs__Transport=RabbitMq
 BackgroundJobs__AutomaticScheduleConcurrency=1
 BackgroundJobs__SchedulePublishConcurrency=1
 BackgroundJobs__MakeupExamAutoConcurrency=1
+BackgroundJobs__ExamArrangementConcurrency=1
 RabbitMq__HostName=rabbitmq.example.edu.cn
 RabbitMq__Port=5671
 RabbitMq__UserName=jiaowu
@@ -305,9 +461,10 @@ Outbox 租约恢复改为按维护周期执行，避免积压发布时每条消
 
 ### 运维与审计控制台
 
-超级管理员可从“组织与权限 → 运维与审计”查询写操作日志、三类失败后台任务、数据库、
+超级管理员可从“组织与权限 → 运维与审计”查看系统性能，查询写操作日志、三类失败后台
-缓存与任务通道健康状态，并查看由 5xx、失败/重试任务、健康探针和备份时效汇总出的异常
+任务、数据库、缓存与任务通道健康状态，并查看由 5xx、失败/重试任务、健康探针和备份
-告警。查询接口和备份操作均在后端强制要求 `SuperAdmin`，不能只依赖前端菜单隐藏。
+时效汇总出的异常告警。查询接口和备份操作均在后端强制要求 `SuperAdmin`，不能只依赖
+前端菜单隐藏。
 
 SQLite 开发环境直接使用在线备份 API。MySQL 环境需要在服务器安装 `mysqldump` 与
 `mysql`（容器镜像已包含对应的 `mariadb-dump` 与 `mariadb` 客户端），并配置独立的

compose.example.yml

@@ -20,6 +20,7 @@ x-jiaowu-environment: &jiaowu-environment
   BackgroundJobs__AutomaticScheduleConcurrency: "${BACKGROUND_JOB_AUTOMATIC_SCHEDULE_CONCURRENCY:-1}"
   BackgroundJobs__SchedulePublishConcurrency: "${BACKGROUND_JOB_SCHEDULE_PUBLISH_CONCURRENCY:-1}"
   BackgroundJobs__MakeupExamAutoConcurrency: "${BACKGROUND_JOB_MAKEUP_EXAM_AUTO_CONCURRENCY:-1}"
+  BackgroundJobs__ExamArrangementConcurrency: "${BACKGROUND_JOB_EXAM_ARRANGEMENT_CONCURRENCY:-1}"
   RabbitMq__HostName: rabbitmq
   RabbitMq__Port: "5672"
   RabbitMq__UserName: "${RABBITMQ_USER:-jiaowu}"
@@ -29,7 +30,9 @@ x-jiaowu-environment: &jiaowu-environment
   Jwt__Issuer: Jiaowu.Api
   Jwt__Audience: Jiaowu.Web
   Jwt__Key: "${JWT_KEY:?请在 .env.docker 中设置 JWT_KEY}"
-  Jwt__ExpireMinutes: "60"
+  Jwt__AccessTokenMinutes: "10"
+  Jwt__WebIdleMinutes: "30"
+  Jwt__AppIdleMinutes: "4320"
   AllowedHosts: "${ALLOWED_HOSTS:-localhost}"
   Cors__Origins__0: "${CORS_ORIGIN:-http://localhost:8080}"
   OfficialDocuments__PublicBaseUrl: "${OFFICIAL_DOCUMENTS_PUBLIC_BASE_URL:-http://localhost:8080}"