118 lines
6.0 KiB
Markdown
118 lines
6.0 KiB
Markdown
# 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 只定义目标字体族
|
||
|
||
---
|
||
|