Skip to content

Commit 3118f9e

Browse files
AGIBuildAGIBuild
committed
proposal: add-home-module - orbital control center style home page
- Add Home bundled module with Core/Avalonia/Blazor projects - Orbital control center visual design with starfield background - Module cards with running status indicators (green/gray) - Quick create module button in CLI section - Default navigation to Home on app startup (breaking change) - 23 implementation tasks, 4 requirements with 14 scenarios
1 parent 0413780 commit 3118f9e

File tree

4 files changed

+313
-0
lines changed

4 files changed

+313
-0
lines changed

‎openspec/changes/add-home-module/design.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
## Context
2+
3+
Modulus 是一个插件式应用框架，当前缺少一个能展示框架价值的"门面"页面。用户第一次打开应用时看到的是模块管理列表，无法快速理解框架的核心卖点。
4+
5+
需要一个视觉上有吸引力、信息展示清晰的主页模块，作为应用的"第一印象"。
6+
7+
## Goals / Non-Goals
8+
9+
**Goals:**
10+
- 创建视觉新颖的主页，展示 Modulus 框架的核心价值
11+
- 应用启动后默认显示主页
12+
- 展示已安装模块状态、框架特性、快速入门命令
13+
- 支持 Avalonia 和 Blazor 双平台
14+
15+
**Non-Goals:**
16+
- 不需要复杂的交互逻辑（主页主要是展示性质）
17+
- 不需要实时数据刷新（模块状态在打开时获取即可）
18+
- 不需要支持用户自定义布局
19+
20+
## Decisions
21+
22+
### 1. 设计风格：轨道控制中心
23+
24+
**选择**: 采用"太空/轨道"隐喻的设计语言
25+
26+
**原因**:
27+
- "模块围绕核心运行"与"插件式框架"概念完美契合
28+
- 深色科技感与现有主题风格一致
29+
- 动态效果（漂浮、脉冲）增加视觉吸引力
30+
- 区别于传统管理后台的"AI slop"风格
31+
32+
**视觉元素**:
33+
```
34+
┌─────────────────────────────────────────────────────────────┐
35+
│ 🌟 星空粒子背景 (CSS/Canvas 实现) │
36+
│ │
37+
│ ╭──────╮ ╭──────╮ ╭──────╮ │
38+
│ │Module│ │Module│ │Module│ ← 漂浮的模块卡片 │
39+
│ ╰──────╯ ╰──────╯ ╰──────╯ │
40+
│ ╭─────────────╮ │
41+
│ │ MODULUS │ ← 中央发光 Logo + 脉冲动画 │
42+
│ │ ◉ ✨ │ │
43+
│ ╰─────────────╯ │
44+
│ │
45+
│ ┌─ 特性卡片 ──────────────────────────────────────────┐ │
46+
│ │ 多宿主 │ 热重载 │ VS兼容 │ AI就绪 │ │ │
47+
│ └────────────────────────────────────────────────────┘ │
48+
│ │
49+
│ ┌─ 快速开始 ─────────────────────────────────────────┐ │
50+
│ │ $ modulus new MyModule -t avalonia │ │
51+
│ └────────────────────────────────────────────────────┘ │
52+
└─────────────────────────────────────────────────────────────┘
53+
```
54+
55+
### 2. 模块结构
56+
57+
```
58+
src/Modules/Home/
59+
├── extension.vsixmanifest # 模块清单
60+
├── Home.Core/
61+
│ ├── Home.Core.csproj
62+
│ ├── HomeModule.cs # ModulusPackage 入口
63+
│ ├── ViewModels/
64+
│ │ └── HomeViewModel.cs # 主页 ViewModel
65+
│ └── Services/
66+
│ ├── IHomeStatisticsService.cs
67+
│ └── HomeStatisticsService.cs
68+
├── Home.UI.Avalonia/
69+
│ ├── Home.UI.Avalonia.csproj
70+
│ ├── HomeAvaloniaModule.cs # UI 入口
71+
│ ├── HomeView.axaml # 主视图
72+
│ ├── HomeView.axaml.cs
73+
│ └── Controls/ # 自定义控件
74+
│ ├── StarfieldPanel.cs # 星空背景
75+
│ └── OrbitPanel.cs # 轨道布局
76+
└── Home.UI.Blazor/
77+
├── Home.UI.Blazor.csproj
78+
├── HomeBlazorModule.cs # UI 入口
79+
└── HomePage.razor # 主页面
80+
```
81+
82+
### 3. 统计数据来源
83+
84+
**HomeStatisticsService** 通过注入获取数据：
85+
- 已安装模块数：`IModuleRepository.GetAllAsync().Count`
86+
- 运行中模块数：`IModuleManager.LoadedModules.Count`
87+
- 框架版本：Assembly metadata
88+
89+
### 4. 默认导航实现
90+
91+
**Avalonia Host** (`App.axaml.cs`):
92+
```csharp
93+
// 原: shellVm.NavigateTo<ModuleListViewModel>();
94+
// 改: shellVm.NavigateTo<HomeViewModel>();
95+
```
96+
97+
**Blazor Host** (`Routes.razor`):
98+
- 默认路由从 `/modules` 改为 `/home`
99+
100+
### 5. 菜单注册
101+
102+
`extension.vsixmanifest` 中注册 Home 菜单项：
103+
```xml
104+
<Asset Type="Modulus.Menu"
105+
Id="home"
106+
DisplayName="Home"
107+
Icon="Home"
108+
Route="Home.Core.ViewModels.HomeViewModel"
109+
TargetHost="Modulus.Host.Avalonia"
110+
Order="1" /> <!-- Order=1 确保在菜单最上方 -->
111+
```
112+
113+
## Risks / Trade-offs
114+
115+
| 风险 | 缓解措施 |
116+
|------|----------|
117+
| 星空动画可能影响低端设备性能 | 提供动画开关或根据设备性能自动降级 |
118+
| 设计风格可能与用户期望不符 | 保持布局可扩展，便于后续调整 |
119+
| 默认导航变更可能影响现有用户习惯 | ModuleList 仍然可以通过菜单访问 |
120+
121+
## Migration Plan
122+
123+
1. 创建 Home 模块，先不修改默认导航
124+
2. 测试 Home 模块独立运行
125+
3. 修改默认导航，全面测试
126+
4. 合并代码
127+
128+
## Resolved Questions
129+
130+
- [x] 是否需要在 Home 页面添加"快速创建模块"的交互入口？**是** - 在 CLI 命令区域添加"创建模块"按钮，点击后打开模块创建向导或跳转到文档
131+
- [x] 模块卡片是否需要显示运行状态（运行中/已停止）？**是** - 模块卡片右上角显示状态指示灯（绿色=运行中，灰色=已停止）
132+

‎openspec/changes/add-home-module/proposal.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Change: 添加 Home 主页模块
2+
3+
## Why
4+
5+
当前应用启动后默认显示的是 Module List（模块管理）页面，无法让用户第一时间理解 Modulus 框架的核心价值和特色。需要一个风格新颖、视觉吸引力强的主页模块，作为用户的"第一印象"页面。
6+
7+
## What Changes
8+
9+
- 新增 `Home` bundled 模块，包含：
10+
- `Home.Core` - 核心逻辑（ViewModel、统计服务）
11+
- `Home.UI.Avalonia` - Avalonia 桌面端视图
12+
- `Home.UI.Blazor` - Blazor 移动端视图
13+
- 采用"轨道控制中心"设计风格：
14+
- 深空渐变背景 + 星点粒子效果
15+
- 中央发光 Logo + 脉冲动画
16+
- 模块卡片围绕核心"漂浮"展示
17+
- 底部 CLI 快速入门命令展示
18+
- **BREAKING**: 应用启动后默认导航到 Home 模块（而非 ModuleListViewModel）
19+
- 更新 `bundled-modules.json` 包含 Home 模块配置
20+
21+
## Impact
22+
23+
- Affected specs: `navigation`（添加默认导航配置）
24+
- Affected code:
25+
- `src/Modules/Home/` - 新增模块
26+
- `src/Hosts/Modulus.Host.Avalonia/App.axaml.cs` - 修改默认导航
27+
- `src/Hosts/Modulus.Host.Blazor/` - 修改默认路由
28+
- `src/Hosts/*/Resources/bundled-modules.json` - 添加 Home 模块注册
29+

‎openspec/changes/add-home-module/specs/navigation/spec.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
## ADDED Requirements
2+
3+
### Requirement: Default Home Navigation
4+
5+
应用启动后，导航服务 SHALL 自动导航到 Home 主页模块，作为用户看到的第一个视图。
6+
7+
#### Scenario: Avalonia host navigates to Home on startup
8+
9+
- **WHEN** Avalonia Host 应用启动完成
10+
- **AND** 所有模块初始化完毕
11+
- **THEN** 自动导航到 `HomeViewModel`
12+
- **AND** Home 主页视图显示在内容区域
13+
14+
#### Scenario: Blazor host routes to Home on startup
15+
16+
- **WHEN** Blazor Host 应用启动
17+
- **AND** 用户访问根路径 `/`
18+
- **THEN** 路由重定向到 `/home`
19+
- **AND** Home 主页组件渲染
20+
21+
#### Scenario: Home menu item appears first in navigation
22+
23+
- **GIVEN** Home 模块已安装并注册
24+
- **WHEN** 导航菜单渲染
25+
- **THEN** Home 菜单项显示在主菜单列表的第一位（Order=1）
26+
- **AND** 显示 Home 图标和 "Home" 或 "主页" 文字
27+
28+
### Requirement: Home Module Statistics Display
29+
30+
Home 主页 SHALL 展示框架和模块的统计信息，帮助用户了解当前系统状态。
31+
32+
#### Scenario: Display installed modules count
33+
34+
- **WHEN** Home 主页加载
35+
- **THEN** 显示已安装模块的总数
36+
- **AND** 统计数据从 `IModuleRepository` 获取
37+
38+
#### Scenario: Display running modules count
39+
40+
- **WHEN** Home 主页加载
41+
- **THEN** 显示当前运行中模块的数量
42+
- **AND** 运行中模块以视觉高亮方式在轨道区域展示
43+
44+
#### Scenario: Module card shows running status indicator
45+
46+
- **WHEN** Home 主页显示模块卡片
47+
- **AND** 模块处于运行中状态
48+
- **THEN** 卡片右上角显示绿色状态指示灯
49+
- **AND** 指示灯有轻微闪烁动画
50+
51+
#### Scenario: Module card shows stopped status indicator
52+
53+
- **WHEN** Home 主页显示模块卡片
54+
- **AND** 模块处于已停止状态
55+
- **THEN** 卡片右上角显示灰色状态指示灯
56+
57+
#### Scenario: Display framework version
58+
59+
- **WHEN** Home 主页加载
60+
- **THEN** 显示当前 Modulus 框架版本号
61+
62+
### Requirement: Home Module Visual Style
63+
64+
Home 主页 SHALL 采用"轨道控制中心"视觉风格，体现模块化框架的核心概念。
65+
66+
#### Scenario: Starfield background renders
67+
68+
- **WHEN** Home 主页显示
69+
- **THEN** 背景显示深空渐变色
70+
- **AND** 有细腻的星点粒子效果（可通过动画实现）
71+
72+
#### Scenario: Central logo with pulse animation
73+
74+
- **WHEN** Home 主页显示
75+
- **THEN** 中央显示 Modulus Logo
76+
- **AND** Logo 有发光脉冲动画效果
77+
78+
#### Scenario: Module cards float around core
79+
80+
- **WHEN** Home 主页显示
81+
- **AND** 有已安装的模块
82+
- **THEN** 模块以卡片形式围绕中央 Logo 展示
83+
- **AND** 卡片有轻微的漂浮动画效果
84+
85+
#### Scenario: Feature cards grid
86+
87+
- **WHEN** Home 主页显示
88+
- **THEN** 下方显示框架核心特性的卡片网格
89+
- **AND** 包含多宿主架构、热重载、VS兼容、AI就绪等特性
90+
91+
#### Scenario: CLI quick start section
92+
93+
- **WHEN** Home 主页显示
94+
- **THEN** 底部显示终端风格的 CLI 快速入门命令
95+
- **AND** 展示 `modulus new`, `modulus build`, `modulus install` 等命令示例
96+
97+
### Requirement: Quick Create Module Action
98+
99+
Home 主页 SHALL 提供"快速创建模块"入口，方便用户快速开始开发新模块。
100+
101+
#### Scenario: Quick create button displayed
102+
103+
- **WHEN** Home 主页显示
104+
- **THEN** CLI 命令区域旁显示"创建模块"按钮
105+
- **AND** 按钮样式与整体视觉风格一致
106+
107+
#### Scenario: Quick create action triggered
108+
109+
- **WHEN** 用户点击"创建模块"按钮
110+
- **THEN** 打开模块创建向导对话框
111+
- **OR** 跳转到模块开发文档页面（如果向导未实现）
112+

‎openspec/changes/add-home-module/tasks.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
## 1. 创建 Home 模块项目结构
2+
3+
- [ ] 1.1 创建 `src/Modules/Home/Home.Core/` 项目
4+
- [ ] 1.2 创建 `src/Modules/Home/Home.UI.Avalonia/` 项目
5+
- [ ] 1.3 创建 `src/Modules/Home/Home.UI.Blazor/` 项目
6+
- [ ] 1.4 创建 `src/Modules/Home/extension.vsixmanifest` 清单文件
7+
- [ ] 1.5 将项目添加到 `Modulus.sln`
8+
9+
## 2. 实现 Home.Core
10+
11+
- [ ] 2.1 创建 `HomeModule.cs` (ModulusPackage 入口)
12+
- [ ] 2.2 创建 `HomeViewModel.cs` - 主页 ViewModel
13+
- [ ] 2.3 创建 `IHomeStatisticsService.cs` - 统计服务接口
14+
- [ ] 2.4 实现 `HomeStatisticsService.cs` - 获取已安装模块数、运行状态等
15+
16+
## 3. 实现 Home.UI.Avalonia（轨道控制中心风格）
17+
18+
- [ ] 3.1 创建 `HomeAvaloniaModule.cs` (UI 入口)
19+
- [ ] 3.2 创建 `HomeView.axaml` 主视图
20+
- [ ] 3.3 实现星空粒子背景 (`StarfieldPanel` 自定义控件或 Canvas)
21+
- [ ] 3.4 实现中央 Logo 脉冲动画
22+
- [ ] 3.5 实现模块卡片轨道布局组件（含运行状态指示灯）
23+
- [ ] 3.6 实现特性卡片网格
24+
- [ ] 3.7 实现 CLI 命令展示区域
25+
- [ ] 3.8 实现"快速创建模块"按钮及交互
26+
27+
## 4. 实现 Home.UI.Blazor
28+
29+
- [ ] 4.1 创建 `HomeBlazorModule.cs` (UI 入口)
30+
- [ ] 4.2 创建 `HomePage.razor` 主页面
31+
- [ ] 4.3 实现响应式布局（复用轨道控制中心设计）
32+
- [ ] 4.4 实现模块状态指示和"快速创建"按钮
33+
34+
## 5. 集成与配置
35+
36+
- [ ] 5.1 更新 `bundled-modules.json` 添加 Home 模块（Order=1，置顶）
37+
- [ ] 5.2 修改 Avalonia Host 默认导航到 `HomeViewModel`
38+
- [ ] 5.3 修改 Blazor Host 默认路由到 `/home`
39+
- [ ] 5.4 构建并测试模块加载
40+

0 commit comments

Comments
 (0)