ui/docs/prd/technical-assumptions.md

Technical Assumptions

Repository Structure: Monorepo

决策： 采用 Monorepo 结构，所有代码在单一 Git 仓库中管理

目录结构：

D:\32_avalonia.ui/
├── src/
│   ├── Penguin.AvaloniaUI/              # 核心控件库项目
│   ├── Penguin.AvaloniaUI.SourceGenerators/  # Source Generator（可选，Post-MVP）
│   ├── Example/                         # 示例应用项目
│   └── Penguin.AvaloniaUI.Tests/        # 单元测试项目
├── docs/                                # 文档
└── .bmad-core/                          # BMAD 框架配置

Rationale:

• Monorepo 简化了控件库和示例应用的协同开发，便于快速迭代和测试
• 依赖管理更简单，所有项目共享同一个 NuGet 依赖版本
• MVP 阶段项目数量少（3-4 个），Monorepo 不会带来复杂度负担
• 未来如果需要拆分（如 Source Generator 独立发布），迁移成本也可控

Service Architecture

架构类型： 单体库（Monolithic Library）

说明：

• Penguin.AvaloniaUI 是一个单一的 .NET 类库项目，所有控件作为命名空间组织在同一个程序集中
• 不采用微服务或独立的控件包（如每个控件一个 NuGet 包），避免过度设计和版本管理复杂度
• 控件之间可以有依赖关系（如 UserGuide 依赖 Overlay），但应尽量保持松耦合
• 使用命名空间隔离不同功能模块：
  • Penguin.AvaloniaUI.Controls - 业务场景控件
  • Penguin.AvaloniaUI.Layouts - 布局控件
  • Penguin.AvaloniaUI.Themes - 主题和样式
  • Penguin.AvaloniaUI.Utils - 工具类

架构约束：

• 所有控件必须继承自 Avalonia 的标准控件基类（TemplatedControl、UserControl 等）
• 样式和模板通过 Avalonia 的资源字典（ResourceDictionary）组织
• 主题切换通过 Application.Current.Resources 动态加载不同的资源字典实现

Testing Requirements

测试策略： 单元测试 + 手动集成测试

单元测试范围：

• 核心业务逻辑：PropertyGrid 的属性解析、UserGuide 的步骤流转逻辑
• 工具类：ThemeManager、LocalizationManager（如果实现）等
• 数据绑定和验证：PropertyGrid 的数据模型和 ReactiveUI 集成

不包括的测试：

• UI 渲染测试（Avalonia 的渲染层不易测试，依赖手动验证）
• 跨平台兼容性测试（MVP 阶段只在 Windows 上测试）
• 性能基准测试（除非发现明显的性能问题）

手动测试：

• 使用 Example 项目作为主要测试载体
• 每个控件应在 Example 中有独立的演示页面
• 测试场景包括：主题切换、属性编辑、引导流程、异常处理

测试框架：

• xUnit 作为单元测试框架
• FluentAssertions 用于断言（可选）
• 不引入 UI 自动化测试框架（如 Appium）

Rationale:

• MVP 阶段时间紧张，优先保证核心逻辑的正确性，UI 渲染依赖手动测试
• 上位机和 AI 桌面应用通常不需要极高的测试覆盖率（不像 Web 应用需要应对大规模用户）
• Example 项目本身就是"活文档"，可以作为回归测试的基准

Additional Technical Assumptions and Requests

1. 核心技术栈：

• .NET 版本： .NET 8.0 或更高（LTS 版本）
• Avalonia 版本： 11.x（最新稳定版），锁定到次要版本（如 11.0.x）
• ReactiveUI 版本： 最新稳定版（19.x 或更高）
• Semi.Avalonia 版本： 最新稳定版（需要在项目初期快速评估其可用性）

2. AOT 支持策略（软约束）：

• 架构设计应考虑未来 AOT 支持，但 MVP 阶段允许使用反射
• PropertyGrid 如果使用反射实现，应设计清晰的抽象层，便于后续迁移到 Source Generator
• 避免使用 Reflection.Emit 和动态类型（dynamic）
• 尽量使用编译时类型安全的 API

3. 国际化架构预留：

• 控件内置文本（如 PropertyGrid 的"名称"、"值"列头，UserGuide 的"下一步"按钮）应通过资源系统管理，而非硬编码
• MVP 阶段可以使用单一语言（中文或英文），但代码结构应支持后续扩展为多语言
• 推荐方案：使用 Avalonia 的本地化机制（IResourceProvider）或自定义 LocalizationManager

4. 依赖管理原则：

• 最小化第三方依赖：除了 Avalonia、ReactiveUI、Semi.Avalonia 外，尽量不引入其他 NuGet 包
• 锁定主要依赖版本：Avalonia 和 ReactiveUI 的主版本号应固定，避免自动升级导致 Breaking Changes
• Semi.Avalonia 的可选性：如果评估后发现 Semi.Avalonia 不可用或过于复杂，允许放弃使用，改为自定义样式系统（风险缓解措施）

5. 开发工具和环境：

• IDE： Visual Studio 2022 或 Rider
• 版本控制： Git，托管在本地或私有仓库
• 持续集成（可选）： MVP 阶段不强制要求 CI/CD，手动构建和测试即可
• 代码格式化： 使用 .editorconfig 统一代码风格

6. 性能优化原则：

• 过早优化是万恶之源：MVP 阶段优先功能完整性，性能问题在出现时再优化
• 已知的性能需求：PropertyGrid 对 50 个属性的生成时间 < 200ms，主题切换 < 100ms（见 NFR）
• 虚拟化和懒加载：如果 PropertyGrid 需要支持数百个属性，考虑使用 VirtualizingStackPanel（Post-MVP）

7. 文档和注释规范：

• 所有公开 API（public class、public method）必须有 XML 文档注释
• 复杂的业务逻辑应有内联注释解释设计意图
• README 应包括：快速开始、控件列表、使用示例、常见问题

8. 颜色系统和字体配置：

• 苹果颜色系统的具体实现细节（颜色值、命名规范）将在架构和开发阶段由 UX Expert 确定，PRD 只明确方向
• 字体配置的具体 fallback 策略将在实现时补充，PRD 只定义目标字体族

---