lowriskquotes-montecarlo

EstiMate

一款移动端优先的承包商成本估算应用，使用 Monte Carlo 模拟为工作报价提供概率风险分析。原生为 iOS（SwiftUI）和 Android（Jetpack Compose）构建。

概览

EstiMate 帮助技术工人和承包商摆脱单点估算，了解可能的成本和风险范围。你无需猜测一个数字，而是输入带有不确定性等级的估算，应用会运行数千次模拟，为你展示总成本的概率分布。

核心价值主张：

• 离线优先，无需登录
• 在移动设备上进行复杂的风险分析（这类功能通常只出现在企业级桌面软件中）
• 通过提供统计上稳妥的报价建议，帮助承包商避免报价过低
• 为客户生成专业的 PDF 报价单

功能

核心估算

• 项目管理 - 创建、保存和管理多个项目估算
• 明细项 - 添加材料、人工、分包商和其他成本
• 风险等级 - 5 级不确定性系统：
  • 确定（±2%）- 固定价格或合同价格
  • 低（±8%）- 价格稳定的已知供应商
  • 中（±15%）- 标准市场波动
  • 高（±25%）- 波动较大或不确定的成本
  • 大致估算（±40%）- 范围未知的项目

工期与差旅估算

• 工作时长 - 按复杂度等级估算天数（从常规 ±10% 到范围未知 ±60%）
• 人工配置 - 时薪、每日工时、额外工人
• 差旅成本 - 单程行程时间、交通波动、现场访问、里程跟踪
• 相关性建模 - 工期的不确定性会自动影响差旅成本

Monte Carlo 模拟

• 进行 1,000 次以上迭代，并检测收敛情况
• 分布偏向超支（更符合施工项目的实际情况）
• 百分位数结果：P10、P50、P80、P90、P95
• 按类别细分成本（材料、工期、差旅）
• 计算标准差和置信度

结果与导出

• 钟形曲线可视化 - 以颜色区分成本分布直方图
• 报价建议 - 保守（P50）、推荐（P80）、稳妥（P90）
• PDF 导出 - 面向客户的专业报价单，附带成本明细
• 分享 - 通过平台分享面板导出

国际化

地区	货币	距离	术语
US	USD ($)	英里	承包商、人工
UK	GBP (£)	英里	技术工人、人工
Canada	CAD ($)	千米	承包商、人工
Australia	AUD ($)	千米	技术工人、人工
New Zealand	NZD ($)	千米	技术工人、人工

技术栈

iOS

• 语言： Swift
• UI 框架： SwiftUI
• 架构： MVVM
• 最低 iOS 版本： 14.0+
• 存储： UserDefaults（仅本地存储）
• PDF： PDFKit/UIGraphicsPDFRenderer
• 图表： Apple Charts 框架（iOS 16.4+）

Android

• 语言： Kotlin
• UI 框架： Jetpack Compose
• 架构： MVVM，使用 ViewModel + StateFlow
• 最低 SDK： 26（Android 8.0）
• 目标 SDK： 34（Android 14）
• 存储： SharedPreferences + GSON
• PDF： iText 7
• 导航： Jetpack Navigation Compose

项目结构

contractors_app/
├── ios/RiskEstimator/           # iOS application
│   └── RiskEstimator/
│       ├── RiskEstimatorApp.swift      # App entry point
│       ├── ContentView.swift           # Root navigation
│       ├── ViewModels/
│       │   └── EstimatorViewModel.swift
│       ├── Models/
│       │   ├── Project.swift
│       │   ├── LineItem.swift
│       │   ├── Worker.swift
│       │   └── SimulationResult.swift
│       ├── Services/
│       │   ├── MonteCarloEngine.swift
│       │   ├── StorageService.swift
│       │   └── PDFService.swift
│       ├── Views/
│       │   ├── Screens/
│       │   │   ├── HomeScreen.swift
│       │   │   ├── EstimatorScreen.swift
│       │   │   └── ResultsScreen.swift
│       │   └── Components/
│       │       ├── RiskSlider.swift
│       │       ├── ComplexitySlider.swift
│       │       ├── TrafficSlider.swift
│       │       ├── BellCurveChart.swift
│       │       └── ...
│       └── Utils/
│           ├── Localization.swift
│           └── CurrencyFormatter.swift
│
├── android/RiskEstimator/       # Android application
│   └── app/src/main/java/com/riskestimator/app/
│       ├── MainActivity.kt
│       ├── ui/
│       │   ├── RiskEstimatorApp.kt
│       │   ├── EstimatorViewModel.kt
│       │   ├── screens/
│       │   │   ├── HomeScreen.kt
│       │   │   ├── EstimatorScreen.kt
│       │   │   └── ResultsScreen.kt
│       │   ├── components/
│       │   │   ├── RiskSlider.kt
│       │   │   ├── BellCurveChart.kt
│       │   │   └── ...
│       │   └── theme/
│       ├── data/
│       │   ├── model/
│       │   └── repository/
│       └── domain/
│           ├── MonteCarloEngine.kt
│           └── PDFService.kt
│
├── icons/                       # App icon assets
├── PROGRESS.md                  # Project roadmap & status
└── contractor_app_market_research.md

架构

两个平台均采用 MVVM（Model-View-ViewModel） 模式：

┌─────────────────────────────────────────────────────────┐
│                         Views                            │
│  (SwiftUI Views / Jetpack Compose Screens)              │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│                     ViewModel                            │
│  - Manages UI state                                      │
│  - Coordinates between Views and Services               │
│  - Triggers simulations                                  │
└─────────────────────────────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
┌─────────────────┐ ┌───────────┐ ┌─────────────────┐
│ MonteCarloEngine│ │StorageRepo│ │   PDFService    │
│                 │ │           │ │                 │
│ - Simulation    │ │ - CRUD    │ │ - Generate PDF  │
│ - Statistics    │ │ - Persist │ │ - Export        │
└─────────────────┘ └───────────┘ └─────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│                        Models                            │
│  Project, LineItem, Worker, SimulationResult            │
└─────────────────────────────────────────────────────────┘

数据模型

项目

struct Project {
    id: UUID
    name: String
    clientName: String
    createdAt: Date
    profitMargin: Double        // Default 15%
    lineItems: [LineItem]
    workers: [Worker]           // iOS only
    estimatedDays: Double
    complexityLevel: ComplexityLevel
    hourlyLaborRate: Double
    hoursPerDay: Double
    travelTimeMinutes: Double
    trafficVariability: TrafficVariability
    numberOfSiteVisits: Int     // 0 = auto-calculate
    includeReturnTrip: Bool
    mileageRate: Double
    distance: Double
}

明细项

struct LineItem {
    id: UUID
    name: String
    estimatedCost: Double
    category: ItemCategory      // Material, Labor, Subcontractor, Other
    riskLevel: RiskLevel        // Certain, Low, Medium, High, WildGuess
}

模拟结果

struct SimulationResult {
    simulations: [Double]       // All iteration results
    percentile10/50/80/90/95: Double
    mean: Double
    standardDeviation: Double
    min, max: Double
    // Category breakdowns
    materialCostP50/P80: Double
    durationCostP50/P80: Double
    travelCostP50/P80: Double
    iterationsRun: Int
    isConverged: Bool
}

风险／方差乘数

等级	方差	使用场景
确定	±2%	固定合同、锁定价格
低	±8%	可靠的供应商、稳定的成本
中	±15%	常规市场波动
高	±25%	价格波动大的材料、不确定的人工成本
大胆猜测	±40%	范围未知、新供应商

复杂度	方差	使用场景
常规	±10%	重复作业、熟悉的工作范围
中等	±25%	标准项目
复杂	±40%	多工种、定制工作
范围未知	±60%	需要勘察、存在未知因素

交通状况	方差	使用场景
可预测	±10%	农村地区、固定日程
多变	±25%	郊区、正常交通
波动较大	±50%	城市、交通高峰时段

入门指南

iOS

1. 在 Xcode 中打开 ios/RiskEstimator/RiskEstimator.xcodeproj
2. 选择目标设备或模拟器
3. 构建并运行（⌘R）

要求：

• Xcode 14.0+
• iOS 14.0+ 部署目标
• Swift 5.0+

Android

1. 在 Android Studio 中打开 android/RiskEstimator
2. 同步 Gradle 文件
3. 选择目标设备或模拟器
4. 构建并运行

要求：

• Android Studio Hedgehog 或更高版本
• JDK 17
• Android SDK 26+（最低）／34（目标）

Monte Carlo 模拟

模拟引擎使用 Box-Muller 变换生成正态分布的随机值，并可选择向超支方向倾斜（反映现实项目的实际情况）。

算法

For each iteration (1,000 - 10,000):
    1. For each line item:
       - Generate random variance based on risk level
       - Apply skewed normal distribution (bias toward overages)
       - Calculate simulated cost

    2. For duration:
       - Generate random variance based on complexity
       - Calculate labor cost = days × hours × rate

    3. For travel:
       - Correlate visits with duration uncertainty
       - Generate traffic variance
       - Calculate travel time + mileage costs

    4. Sum all costs + profit margin

Calculate statistics from all iterations
Check for convergence (P80 standard error < 0.5%)

收敛检测

引擎会自适应运行：

• 最少：1,000 次迭代
• 最多：10,000 次迭代
• 如果 P80 估算值趋于稳定（标准误差 < 0.5%），则提前停止

PDF 生成

生成报价单以供客户查看：

• 专业排版，包含项目详情
• 按类别拆分成本
• 利润率计入各类别成本（对客户隐藏）
• 不包含 Monte Carlo 术语，只提供清晰的价格
• 可通过平台分享面板导出

存储

两个平台都仅使用本地存储：

• **iOS：**使用 Codable 序列化的 UserDefaults
• **Android：**使用 GSON 的 SharedPreferences

无需云同步或服务器，可在现场完全离线使用。

当前状态

**版本：**1.1（MVP 功能已完备）

已完成

• 项目的完整 CRUD 操作
• 带收敛检测的 Monte Carlo 引擎
• 五级风险系统
• 工期和出行不确定性
• 按类别拆分成本
• PDF 导出
• 多地区／多币种支持

路线图（第 3 阶段）

• 模拟引擎的单元测试
• 全面的错误处理
• 输入验证
• 集成崩溃报告
• Android 发布版缩减体积

详细路线图请参阅 PROGRESS.md。

许可证

专有软件，保留所有权利。

已验证的更改

Web 应用会发布 /.well-known/changes.json 和 /changes.json（verified-changes/0.1）。请参阅 web/README.md。