chore: merge dev into main

[Illustar0]

Summary by CodeRabbit

发布说明

• API 变更

  • OnlineDevice 字段命名规范更新，从驼峰式改为蛇形式（如 login_time、session_id）；旧属性名仍可访问但会触发弃用警告。

• Bug 修复

  • 加强了 JWT 令牌过期字段的验证严格度。
  • 增强了门户网址解析的有效性校验。

• 文档

  • 更新了在线设备字段命名文档，说明新旧字段名称的对应关系。

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

本PR对ZZU.Py的类型安全性和数据规范化进行了全面升级。主要包括：网络模型从驼峰命名改为snake_case并配置Pydantic别名、认证流程的JWT和公钥验证更新、Portal发现URL校验增强、whenever库日期时间处理改进，以及工具函数的优化。

Changes

类型安全与规范化

Layer / File(s)	Summary
网络模型字段规范化与别名兼容 zzupy/model/network.py, docs/usage/web/network.md	OnlineDevice、AuthResult、PortalInfo 的字段从驼峰改为snake_case（如 loginTime → login_time），通过 alias_generator=to_camel 自动支持驼峰别名的序列化/反序列化；旧属性访问器保留兼容性但触发 DeprecationWarning。
认证流程必要字段验证 zzupy/aio/app/auth.py, zzupy/app/auth.py	JWT 的 exp 字段解析从容错式 get("exp") 改为直接读取 ["exp"] 并显式转换为 float；登录流程在获取RSA公钥后和MFAClient中添加断言确保公钥非空。
Portal发现URL解析与异常精准捕获 zzupy/aio/web/network.py, zzupy/web/network.py	认证URL解析时校验 scheme 和 netloc 完整性，缺失则抛出 ParsingError；异常捕获范围从宽泛 Exception 收窄为 httpx2.RequestError 和 ValueError，并添加 logger.debug 记录失败原因。
whenever 日期时间类型升级与RFC 5545导出 zzupy/model/eas.py	日期解析失败改为显式抛出 ValueError；时间字段若非 ZonedDateTime 则按 hhmm 格式用 Time.parse 生成带 Asia/Shanghai 时区的时间；日历导出 dtstart/dtend/dtstamp 由 py_datetime() 切换为 to_stdlib() 以符合RFC 5545；PeriodInfo.practice_unit 改为 `str
工具函数与文档更新 zzupy/utils.py, docs/note.md	require_auth 装饰器从 asyncio.iscoroutinefunction 改为 inspect.iscoroutinefunction；文档更新标题样式和字段命名说明。

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• Illustar0/ZZU.Py#33：Portal发现流程中的URL解析验证和 ParsingError 异常处理逻辑在两个PR中修改相同的代码路径（discover_portal_info）。

Poem

🐰 从驼峰到下划线，命名更齐整；
公钥必须验，安全上一阶；
URL需校验，错误捕得准；
whenever换算法，时区问题清；
工具换模块，类型更安全。✨

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 60.61% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Title check	❓ Inconclusive	标题'chore: merge dev into main'是一个通用的分支合并操作描述，没有反映出此次PR中多个重要的功能改进和API变更（如OnlineDevice字段命名标准化、JWT解析改进、网络发现日志增强等）。	建议更新标题以反映本次PR的主要变更内容，例如'chore: standardize field naming and improve validation'或类似表述，以便更清楚地传达此次合并的核心改进。

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch dev

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}