Legacy Rapid Expansion (旧项目快速扩充)

Instructions

仅在旧项目加入新功能时使用
先填写 Required Inputs（隔离边界、桥接契约、回退方案）
依照下方章节顺序套用
一次只创建一个隔离区与桥接点
完成后对照 Quick Checklist

When to Use

Scenario B：旧项目加新功能

Example Prompts

"请依照 Islanding Architecture 创建 modern/ 与 bridge/"
"用 Hybrid Theming 章节让新 Compose UI 沿用旧 Theme"
"请用 Feature Toggle 章节设计新功能开关"

Workflow

先确认 Required Inputs（隔离范围、bridge API、toggle 策略）
创建 Islanding Architecture 与 Bridge Pattern
处理 Hybrid Theming 与 Wrapper Activities
配置 Feature Toggle 与回滚流程
执行 Legacy Gate 并用 Quick Checklist 验收

Practical Notes (2026)

新功能必须独立于 legacy 内部实作
Bridge API 需稳定，避免频繁变更造成扩散
Feature Toggle 作为上线与回退的唯一入口
新旧系统边界必须有 owner，避免“共享无人区”
迁移期间每个 bridge 调用都应有埋点便于回滚判断

Minimal Template

目标: 
隔离范围: 
旧系统依赖:
回滚触发条件:
Bridge 契约: 
Toggle 策略: 
验收: Quick Checklist

Required Inputs (执行前输入)

隔离范围（新功能边界与 legacy 触点）
Bridge 契约（输入/输出/错误码）
Feature Toggle 策略（开关位置、默认值、回滚）
回滚触发条件（指标阈值与负责人）
埋点字段（新旧路径识别）

Deliverables (完成后交付物)

modern/ 与 bridge/ 目录落地
Bridge API 文档与使用样例
Hybrid theme 兼容策略
Toggle 配置与灰度/回滚脚本
Legacy Gate 验收记录

Legacy Gate (验收门槛)

./gradlew test
./gradlew connectedDebugAndroidTest

需要在 PR 说明中附新旧路径对照与回滚步骤。

Islanding Architecture (孤岛策略)

在旧架构中切出一块「净土」，新功能完全使用现代架构开发。

目录结构

app/
├── legacy/                # 旧代码 (不动)
│   ├── activities/
│   └── fragments/
├── modern/                # 新代码 (净土)
│   ├── core/
│   │   ├── data/
│   │   ├── domain/
│   │   └── ui/
│   └── feature/
│       └── newfeature/
└── bridge/                # 桥接层
    ├── LegacyNavigator.kt
    └── ModernEntryPoint.kt

Bridge Pattern

// bridge/ModernEntryPoint.kt
object ModernEntryPoint {
    
    fun startNewFeatureActivity(context: Context, params: Bundle) {
        val intent = Intent(context, NewFeatureActivity::class.java).apply {
            putExtras(params)
        }
        context.startActivity(intent)
    }

    fun startCheckoutCompose(context: Context, orderId: String) {
        startNewFeatureActivity(
            context = context,
            params = bundleOf("order_id" to orderId, "entry" to "checkout")
        )
    }
    
    @Composable
    fun NewFeatureScreen(params: Map<String, Any>) {
        // 现代 Compose UI
    }
}

// 旧代码调用
class LegacyActivity : AppCompatActivity() {
    fun onButtonClick() {
        ModernEntryPoint.startNewFeatureActivity(this, bundleOf("id" to productId))
    }
}

Hybrid Theming

让 Compose UI 沿用旧有的 XML Theme。

MDC-Android Compose Theme Adapter

// build.gradle.kts
dependencies {
    implementation("com.google.android.material:compose-theme-adapter:<project-verified-version>")
}

// 使用
@Composable
fun NewFeatureScreen() {
    MdcTheme {  // 自动桥接 XML Theme
        Surface {
            // Compose UI 会使用 XML 定义的 colors/typography
        }
    }
}

渐进式迁移

// 1. 初期：完全沿用 XML Theme
MdcTheme { content() }

// 2. 中期：覆写部分 Token
MdcTheme(
    setTextColors = true,
    setDefaultFontFamily = true
) { content() }

// 3. 后期：完全使用 Compose Theme
AppTheme { content() }

Wrapper Activities

快速将 Compose Screen 包装供旧有 startActivity 调用。

通用 Wrapper

@AndroidEntryPoint
class ComposeWrapperActivity : ComponentActivity() {
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        val screenType = intent.getStringExtra(EXTRA_SCREEN_TYPE)
        val params = intent.extras ?: Bundle.EMPTY
        
        setContent {
            AppTheme {
                when (screenType) {
                    "new_feature" -> NewFeatureScreen(params.toMap())
                    "settings" -> SettingsScreen()
                    else -> ErrorScreen()
                }
            }
        }
    }
    
    companion object {
        private const val EXTRA_SCREEN_TYPE = "screen_type"
        
        fun newIntent(context: Context, screenType: String, params: Bundle = Bundle.EMPTY): Intent {
            return Intent(context, ComposeWrapperActivity::class.java).apply {
                putExtra(EXTRA_SCREEN_TYPE, screenType)
                putExtras(params)
            }
        }
    }
}

Feature Toggle

安全地在 Production 环境开关新功能。

interface FeatureFlags {
    val useNewCheckout: Boolean
    val enableComposeProfile: Boolean
}

class RemoteFeatureFlags @Inject constructor(
    private val remoteConfig: FirebaseRemoteConfig
) : FeatureFlags {
    override val useNewCheckout: Boolean
        get() = remoteConfig.getBoolean("use_new_checkout")
}

// 使用
class CheckoutNavigator @Inject constructor(
    private val context: Context,
    private val featureFlags: FeatureFlags
) {
    fun navigateToCheckout(orderId: String) {
        if (featureFlags.useNewCheckout) {
            ModernEntryPoint.startCheckoutCompose(context, orderId)
        } else {
            context.startActivity(Intent(context, LegacyCheckoutActivity::class.java))
        }
    }
}

Quick Checklist

Required Inputs 已填写并冻结（边界/契约/回滚）
新功能放在 modern/ 目录
桥接层清晰定义 (bridge/)
Hybrid Theming 确保视觉一致
Feature Toggle 控制上线
避免新代码依赖旧代码的内部实作
Legacy Gate 已执行并记录结果