docs: brainstorm,brief and prd

docs/prd/technical-assumptions.md

@@ -0,0 +1,118 @@
+# 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 只定义目标字体族
+
+---
+