//! 运行各模块的小演示。真正的实现都在库 crate(见 `src/lib.rs` 及其模块)。

use rt_43_class_like::{Account, BankAccount, SavingsAccount, print_static, total_balance};

fn main() {
    println!("== 1. 封装:构造器 + 方法维护不变量 ==");
    let mut acc = BankAccount::new("阿俊", 10_000).expect("开户成功");
    acc.deposit(5_000);
    match acc.withdraw(3_000) {
        Ok(()) => println!("  取款成功,余额 {}", acc.balance()),
        Err(e) => println!("  取款失败:{e}"),
    }
    if let Err(e) = acc.withdraw(999_999) {
        println!("  非法取款被拦截:{e}");
    }
    // Display:直接用 {} 打印,等价于其它语言的 toString。
    println!("  Display -> {acc}");

    println!("== 2. 关联常量当作静态常量使用 ==");
    println!("  最低开户金额 = {} 分", BankAccount::MIN_OPENING);

    println!("== 3. 组合代替继承:储蓄账户计息 ==");
    let mut savings = SavingsAccount::new("小美", 100_000, 250).expect("开户成功");
    savings.accrue_interest();
    println!("  计息后:{}", savings.summary());

    println!("== 4. 多态:静态分发 vs 动态分发 ==");
    print_static(&acc);
    print_static(&savings);
    let accounts: Vec<Box<dyn Account>> = vec![Box::new(acc), Box::new(savings)];
    for a in &accounts {
        println!("  dynamic -> {}", a.summary());
    }
    println!("  全部账户余额合计 = {} 分", total_balance(&accounts));
}

//! Rust 里没有 `class` 关键字,但「类」的能力都能用 struct + impl + trait 表达。
//!
//! 本 crate 按其它语言里熟悉的面向对象概念,把代码拆成几个模块逐一对照:
//! - `account`:封装 + 构造器 + 关联常量 + Display(等价 toString)。
//! - `account_trait`:接口 / 抽象基类(trait + 默认方法)。
//! - `savings`:用「组合 + 委托」代替继承。
//! - `polymorphism`:静态分发(泛型)与动态分发(`dyn`)。

pub mod account;
pub mod account_trait;
pub mod polymorphism;
pub mod savings;

// 重新导出常用类型,调用方可以直接 `use rt_43_class_like::BankAccount`。
pub use account::BankAccount;
pub use account_trait::Account;
pub use polymorphism::{print_static, total_balance};
pub use savings::SavingsAccount;

//! 接口 / 抽象基类:trait。
//!
//! trait 既能像 interface 规定「必须实现的方法」,
//! 也能像抽象基类提供「默认实现」。

/// 「账户」契约。任何想被当作账户对待的类型都要实现它。
pub trait Account {
    /// 抽象方法:必须实现。
    fn balance(&self) -> i64;
    /// 抽象方法:必须实现。
    fn kind(&self) -> &str;

    /// 默认方法:不重写就用这份实现(类似抽象基类里的具体方法)。
    fn summary(&self) -> String {
        format!("[{}] 余额 {} 分", self.kind(), self.balance())
    }
}

//! 封装:struct 存字段(默认私有)+ impl 提供方法。
//!
//! 字段不加 `pub` 默认私有,模块外只能通过方法访问,
//! 等价于其它语言把字段设为 private、再提供 getter / setter。

use std::fmt;

use crate::account_trait::Account;

/// 一个银行账户。余额以「分」为单位存储,且保证永不为负 —— 这条不变量
/// 由方法来维护,外部拿不到可变字段,自然无法破坏它。
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BankAccount {
    owner: String,
    balance: i64,
}

impl BankAccount {
    /// 关联常量:类似「类的静态常量」。用 `BankAccount::MIN_OPENING` 访问。
    pub const MIN_OPENING: i64 = 100;

    /// 关联函数(无 `self`)= 构造器 / 静态工厂方法。
    /// 返回 `Result`,把「开户金额不足」这种非法状态挡在对象诞生之前。
    pub fn new(owner: &str, opening: i64) -> Result<Self, String> {
        if opening < Self::MIN_OPENING {
            return Err(format!("开户金额至少 {} 分", Self::MIN_OPENING));
        }
        Ok(Self {
            owner: owner.to_string(),
            balance: opening,
        })
    }

    /// `&self`:只读 getter。返回借用,避免不必要的克隆。
    pub fn owner(&self) -> &str {
        &self.owner
    }

    /// `&mut self`:会修改自身的实例方法。
    pub fn deposit(&mut self, amount: i64) {
        self.balance += amount;
    }

    /// `&mut self`:取款时维护「余额不为负」的不变量,违反就返回错误。
    pub fn withdraw(&mut self, amount: i64) -> Result<(), String> {
        if amount > self.balance {
            return Err(format!("余额不足:想取 {amount},仅有 {}", self.balance));
        }
        self.balance -= amount;
        Ok(())
    }
}

/// toString:实现 `Display`,而不是写一个 `to_string` 方法。
/// 实现了 Display 就自动获得 `.to_string()` 和 `{}` 格式化能力。
impl fmt::Display for BankAccount {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "{} 的账户:{:.2} 元",
            self.owner,
            self.balance as f64 / 100.0
        )
    }
}

impl Account for BankAccount {
    fn balance(&self) -> i64 {
        self.balance
    }

    fn kind(&self) -> &str {
        "普通账户"
    }
    // 不重写 summary,直接用 trait 的默认实现。
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn rejects_low_opening() {
        assert!(BankAccount::new("阿俊", 50).is_err());
    }

    #[test]
    fn deposit_and_withdraw_keep_invariant() {
        let mut acc = BankAccount::new("阿俊", 1_000).unwrap();
        acc.deposit(500);
        assert_eq!(acc.balance(), 1_500);
        assert!(acc.withdraw(2_000).is_err()); // 不变量:不能透支
        assert!(acc.withdraw(1_000).is_ok());
        assert_eq!(acc.balance(), 500);
    }

    #[test]
    fn display_formats_yuan() {
        let acc = BankAccount::new("阿俊", 12_345).unwrap();
        assert_eq!(acc.to_string(), "阿俊 的账户:123.45 元");
    }

    #[test]
    fn default_trait_method_used_by_bank_account() {
        let acc = BankAccount::new("阿俊", 1_000).unwrap();
        assert_eq!(acc.summary(), "[普通账户] 余额 1000 分");
    }
}

//! 多态:同一段逻辑作用于不同类型。

use crate::account_trait::Account;

/// 静态分发(泛型):编译期为每个具体类型生成专门代码,零运行时开销。
pub fn print_static(acc: &impl Account) {
    println!("  static  -> {}", acc.summary());
}

/// 动态分发(trait 对象):运行期通过虚表调用,代价是一次间接跳转,
/// 好处是能把「不同的具体类型」装进同一个集合里。
pub fn total_balance(accounts: &[Box<dyn Account>]) -> i64 {
    accounts.iter().map(|a| a.balance()).sum()
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::account::BankAccount;
    use crate::savings::SavingsAccount;

    #[test]
    fn polymorphism_over_trait_objects() {
        let accounts: Vec<Box<dyn Account>> = vec![
            Box::new(BankAccount::new("阿俊", 1_000).unwrap()),
            Box::new(SavingsAccount::new("小美", 2_000, 100).unwrap()),
        ];
        assert_eq!(total_balance(&accounts), 3_000);
    }
}

//! 「继承」用组合代替:composition over inheritance。
//!
//! Rust 不能继承 struct。要复用 BankAccount 的能力,就把它作为字段
//! 「包」进来,新增自己的字段/方法,并把需要的调用「委托」过去。

use crate::account::BankAccount;
use crate::account_trait::Account;

/// 储蓄账户:在普通账户之上增加「计息」能力。
pub struct SavingsAccount {
    base: BankAccount, // 组合:拥有一个 BankAccount,而非继承它
    rate_bps: i64,     // 年利率,单位:基点(1% = 100bps)
}

impl SavingsAccount {
    pub fn new(owner: &str, opening: i64, rate_bps: i64) -> Result<Self, String> {
        Ok(Self {
            base: BankAccount::new(owner, opening)?, // 复用父类型的构造器
            rate_bps,
        })
    }

    /// 新增能力:按利率结算一次利息。
    pub fn accrue_interest(&mut self) {
        let interest = self.base.balance() * self.rate_bps / 10_000;
        self.base.deposit(interest);
    }

    /// 委托:把基础能力转发给内部的 BankAccount(等价于调用「父类方法」)。
    pub fn deposit(&mut self, amount: i64) {
        self.base.deposit(amount);
    }
}

// 让「子类型」也满足同一个接口 —— 通过委托实现 trait,
// 于是 SavingsAccount 能和 BankAccount 一起被多态地使用。
impl Account for SavingsAccount {
    fn balance(&self) -> i64 {
        self.base.balance()
    }

    fn kind(&self) -> &str {
        "储蓄账户"
    }

    /// 重写(覆盖)默认方法 —— 类似子类 override 基类方法。
    fn summary(&self) -> String {
        format!(
            "[{}] 余额 {} 分,年化 {}bps",
            self.kind(),
            self.balance(),
            self.rate_bps
        )
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn savings_overrides_summary_and_accrues() {
        let mut savings = SavingsAccount::new("小美", 100_000, 250).unwrap();
        savings.accrue_interest(); // 100000 * 250 / 10000 = 2500
        assert_eq!(savings.balance(), 102_500);
        assert!(savings.summary().contains("储蓄账户"));
        assert!(savings.summary().contains("250bps"));
    }
}

[package]
name = "rt_43_class_like"
version.workspace = true
edition.workspace = true
publish.workspace = true