| name | feature-architecture-planning |
| description | Comprehensive architecture planning for new features. Includes architecture design, tech stack selection, file structure planning, implementation roadmap, and risk assessment. Invoke when adding new features, modules, or when user asks for architecture planning. |
功能架构规划
概述
这是一个完整的功能架构规划流程，用于在开发新功能前进行系统性的设计和规划。确保功能开发有清晰的架构、合理的技术选型、明确的实施计划和可控的风险。
触发条件
当出现以下情况时调用此 Skill：
- 用户要求添加新功能
- 用户要求开发新模块
- 用户询问"如何实现某功能"
- 用户要求"规划一下架构"
- 用户要求"设计一下方案"
- 用户要求"评估一下技术方案"
规划流程
第一步：需求分析与现状调研
1.1 理解需求
- 明确功能目标和核心需求
- 识别功能边界和约束条件
- 确定优先级和里程碑
1.2 调研现状
- 搜索项目中相关的现有代码
- 了解项目的技术栈和架构模式
- 分析类似功能的实现方式
- 识别可复用的组件和模块
工具使用：
SearchCodebase("关键词")
Grep("pattern")
Glob("pattern")
Read("关键文件路径")
LS("目录路径")
第二步：架构设计
2.1 整体架构图
绘制清晰的分层架构图，包含：
┌─────────────────────────────────────────────────────────────┐
│ 表现层 │
├─────────────────────────────────────────────────────────────┤
│ Activity/Fragment/Screen │
│ └── UI组件 │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 业务层 │
├─────────────────────────────────────────────────────────────┤
│ ViewModel │
│ ├── 状态管理 │
│ └── 业务逻辑 │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 数据层 │
├─────────────────────────────────────────────────────────────┤
│ Repository │
│ ├── Dao (数据访问对象) │
│ └── DataSource (数据源) │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 数据存储 │
├─────────────────────────────────────────────────────────────┤
│ Room Database / SharedPreferences / File / Network │
└─────────────────────────────────────────────────────────────┘
2.2 模块划分
- 表现层：UI展示、用户交互
- 业务层：业务逻辑、状态管理
- 数据层：数据访问、缓存策略
- 基础设施层：工具类、扩展函数
2.3 依赖关系
明确各层之间的依赖方向（单向依赖，避免循环依赖）
第三步：技术栈选择
3.1 核心技术评估
| 技术 | 用途 | 选择理由 | 是否已有 |
|---|
| 技术A | 用途A | 理由A | ✅/❌ |
| 技术B | 用途B | 理由B | ✅/❌ |
3.2 新增依赖
// 需要添加的依赖
implementation 'xxx:xxx:version'
3.3 技术选型原则
- 优先使用项目已有技术：降低学习成本，保持一致性
- 选择成熟稳定的技术：避免踩坑，降低风险
- 考虑团队技术栈：便于维护和协作
- 评估性能影响：避免引入性能瓶颈
第四步：数据模型设计
4.1 实体类设计
@Entity(tableName = "table_name")
data class EntityName(
@PrimaryKey(autoGenerate = true)
val id: Long = 0,
val field1: String,
val field2: Int,
val createTime: Long = System.currentTimeMillis(),
val updateTime: Long = System.currentTimeMillis()
)
4.2 数据访问对象（Dao）
@Dao
interface EntityDao {
@Query("SELECT * FROM table_name")
fun flowAll(): Flow<List<EntityName>>
@Insert(onConflict = OnConflictStrategy.REPLACE)
suspend fun insert(entity: EntityName)
@Delete
suspend fun delete(entity: EntityName)
}
4.3 数据库迁移
val MIGRATION_X_Y = object : Migration(X, Y) {
override fun migrate(database: SupportSQLiteDatabase) {
database.execSQL("""
CREATE TABLE IF NOT EXISTS table_name (...)
""")
database.execSQL("CREATE INDEX IF NOT EXISTS ...")
}
}
第五步：文件结构规划
5.1 需要新增的文件
项目根目录/
├── 数据层/
│ ├── entities/
│ │ └── NewEntity.kt ✨ 新增
│ └── dao/
│ └── NewDao.kt ✨ 新增
│
├── 业务层/
│ └── NewViewModel.kt ✨ 新增
│
└── 表现层/
├── NewActivity.kt ✨ 新增
├── NewScreen.kt ✨ 新增
└── components/
└── NewComponent.kt ✨ 新增
5.2 需要修改的文件
项目根目录/
├── 配置文件/
│ └── AppDatabase.kt 📝 修改
│
└── 入口文件/
└── MainActivity.kt 📝 修改
5.3 需要删除的文件
项目根目录/
└── 旧文件/
└── OldFile.kt ❌ 删除
第六步：核心代码实现要点
6.1 ViewModel 设计
class FeatureViewModel(
application: Application
) : BaseViewModel(application) {
private val _uiState = MutableStateFlow<UiState>(UiState.Idle)
val uiState: StateFlow<UiState> = _uiState.asStateFlow()
val data: Flow<List<Entity>> = repository.getData()
fun doSomething() {
execute {
}.onSuccess {
}.onError {
}
}
sealed class UiState {
object Idle : UiState()
object Loading : UiState()
data class Error(val message: String) : UiState()
}
}
6.2 Screen/Fragment 设计
@Composable
fun FeatureScreen(
viewModel: FeatureViewModel = viewModel(),
onBackClick: () -> Unit
) {
val uiState by viewModel.uiState.collectAsState()
val data by viewModel.data.collectAsState(initial = emptyList())
Scaffold(
topBar = {
TopAppBar(
title = { Text("功能标题") },
navigationIcon = {
IconButton(onClick = onBackClick) {
Icon(Icons.Default.ArrowBack, "返回")
}
}
)
}
) { paddingValues ->
when (uiState) {
is UiState.Loading -> LoadingComponent()
is UiState.Error -> ErrorComponent((uiState as UiState.Error).message)
else -> ContentComponent(data)
}
}
}
6.3 Repository 设计
class FeatureRepository {
private val dao = appDb.entityDao()
fun getData(): Flow<List<Entity>> = dao.flowAll()
suspend fun saveData(entity: Entity) {
dao.insert(entity)
}
suspend fun deleteData(entity: Entity) {
dao.delete(entity)
}
}
第七步：实施计划
阶段一：数据层搭建（X天）
任务清单：
关键文件：
- Entity.kt
- Dao.kt
- Repository.kt
验收标准：
阶段二：业务层实现（X天）
任务清单：
关键文件：
验收标准：
阶段三：UI层开发（X天）
任务清单：
关键文件：
- Activity.kt
- Screen.kt
- Component.kt
验收标准：
阶段四：集成与测试（X天）
任务清单：
关键文件：
验收标准：
第八步：数据迁移策略
8.1 旧数据迁移
object DataMigration {
fun migrateOldData() {
val oldData = getOldData()
val newData = oldData.map {
NewEntity(
field1 = it.oldField1,
field2 = it.oldField2
)
}
appDb.entityDao().insert(*newData.toTypedArray())
clearOldData()
}
}
8.2 默认数据导入
fun importDefaultData() {
val defaultData = loadDefaultData()
appDb.entityDao().insert(*defaultData.toTypedArray())
}
第九步：风险与应对
| 风险 | 影响程度 | 发生概率 | 应对措施 |
|---|
| 风险1 | 高/中/低 | 高/中/低 | 具体措施 |
| 风险2 | 高/中/低 | 高/中/低 | 具体措施 |
常见风险：
-
数据库版本冲突
- 影响：高
- 应对：使用fallbackToDestructiveMigrationFrom，提供完整迁移脚本
-
数据丢失
- 影响：高
- 应对：实现数据迁移工具，首次启动时自动迁移
-
性能问题
- 影响：中
- 应对：使用Flow响应式更新，避免频繁查询
-
兼容性问题
第十步：预期成果
10.1 功能成果
✅ 核心功能
✅ 性能指标
- 启动时间 < X秒
- 内存占用 < XMB
- 响应时间 < X毫秒
10.2 代码成果
- 📁 新增文件：X个
- 📝 修改文件：X个
- ❌ 删除文件：X个
- 📊 代码行数预估：约X行
10.3 文档成果
第十一步：后续扩展方向
11.1 短期扩展（1-2周）
11.2 中期扩展（1-2月）
11.3 长期扩展（3-6月）
验证清单
架构验证
技术验证
实现验证
测试验证
文档验证
输出模板
## 📐 [功能名称] 架构规划
### 一、架构设计
#### 1.1 整体架构图
[架构图]
#### 1.2 模块划分
[模块说明]
---
### 二、技术栈选择
#### 2.1 核心技术
[技术表格]
#### 2.2 新增依赖
[依赖列表]
---
### 三、数据模型设计
#### 3.1 实体类
[实体类定义]
#### 3.2 数据访问对象
[Dao定义]
---
### 四、文件结构规划
#### 4.1 新增文件
[文件树]
#### 4.2 修改文件
[文件列表]
#### 4.3 删除文件
[文件列表]
---
### 五、核心代码实现要点
#### 5.1 ViewModel设计
[代码示例]
#### 5.2 Screen设计
[代码示例]
---
### 六、实施计划
#### 阶段一：数据层搭建（X天）
[任务清单]
#### 阶段二：业务层实现（X天）
[任务清单]
#### 阶段三：UI层开发（X天）
[任务清单]
#### 阶段四：集成与测试（X天）
[任务清单]
---
### 七、数据迁移策略
#### 7.1 旧数据迁移
[迁移代码]
#### 7.2 默认数据导入
[导入代码]
---
### 八、风险与应对
| 风险 | 影响 | 应对措施 |
|------|------|----------|
| ... | ... | ... |
---
### 九、预期成果
#### 9.1 功能成果
[功能列表]
#### 9.2 代码成果
[统计数据]
---
### 十、后续扩展方向
#### 10.1 短期扩展
[扩展计划]
#### 10.2 中期扩展
[扩展计划]
#### 10.3 长期扩展
[扩展计划]
---
## 📋 总结
[总结说明]
**预计总开发时间：X-Y天**
注意事项
- 充分调研：在规划前必须充分调研现有代码，避免重复造轮子
- 遵循规范：遵循项目现有的架构规范和编码风格
- 渐进式开发：分阶段实施，每个阶段都要有可验证的成果
- 风险意识：提前识别风险，准备好应对措施
- 文档先行：先设计后编码，文档和代码同步更新
- 可测试性：设计时考虑测试，确保代码可测试
- 性能优先：关注性能指标，避免性能瓶颈
- 用户体验：从用户角度思考，提供良好的用户体验
示例参考
参考实际案例：直链上传配置功能架构规划
该案例完整展示了：
- 从需求分析到架构设计的完整流程
- 数据层、业务层、UI层的详细规划
- 技术选型和风险评估
- 分阶段实施计划
- 数据迁移策略
- 预期成果和后续扩展
快速使用
当用户要求规划新功能时，按照以下步骤快速输出：
- 第一步：调研现状（使用搜索工具）
- 第二步：设计架构（绘制架构图）
- 第三步：选择技术（评估技术栈）
- 第四步：设计数据模型（定义实体和Dao）
- 第五步：规划文件结构（列出新增/修改/删除文件）
- 第六步：编写核心代码要点（ViewModel、Screen等）
- 第七步：制定实施计划（分阶段任务）
- 第八步：设计迁移策略（数据迁移方案）
- 第九步：评估风险（风险列表和应对）
- 第十步：定义预期成果（功能和代码成果）
- 第十一步：规划扩展方向（短中长期）
输出完整的架构规划文档，供用户确认后开始实施。
