Expand story tutorials with inline language-feature notes

story/begin-v3/01_system_boot.md

@@ -33,6 +33,14 @@ cjc smart_home_boot.cj -o boot_loader
 
 当终端打印出启动信息时，意味着你的代码已经成功接管了硬件的控制权。
 
+代码要点：
+
+*   `main()` 是顶层函数入口，默认返回 `Unit`，无需额外声明返回类型。
+*   `println` 来自标准库，适合在启动阶段输出关键事件与阶段标记。
+*   字符串模板 `${}` 可以嵌入表达式，让启动日志保持清晰可读。
+
+在真实系统中，入口函数只负责编排步骤，具体的自检、配置加载建议拆分成独立函数，便于测试与复用。
+
 ## 工程化提示
 
 *   启动日志建议包含模块名与版本号，便于部署排查。

story/begin-v3/02_sensor_data.md

@@ -44,6 +44,12 @@ main() {
 // currentTemp = "Error" // ❌ 编译器拦截：防止脏数据污染系统
 ```
 
+代码要点：
+
+`let` 声明不可变数据，适合设备编号、位置等长期不变的信息；`var` 用于实时温湿度等可变状态，避免误把动态值写进常量。
+类型推断让代码更简洁，但对关键业务指标仍建议显式标注类型，减少单位或精度混用的风险。
+日志中的字符串模板 `${}` 支持直接嵌入表达式，能把状态快照一次性输出为清晰的运行记录。
+
 ## 工程化提示
 
 *   传感器数据建议统一单位与采样周期，避免误读。

story/begin-v3/03_automation_logic.md

@@ -73,6 +73,12 @@ main() {
 ```
 通过这些逻辑，原本冰冷的硬件开始表现出“智能”。
 
+代码要点：
+
+`if` 在仓颉中是表达式，可以直接用于返回值或组合日志，减少冗余的临时变量。
+`while` 适合持续监控任务，`for (portId in 1..=4)` 使用闭区间范围语法，明确扫描范围包含起止端口。
+`break` 与 `continue` 让循环具备“可控退出”和“跳过分支”的语义，是实现安全策略与故障跳过的关键手段。
+
 ## 工程化提示
 
 *   阈值判断要考虑“抖动区间”，避免频繁开关设备。

story/begin-v3/04_device_control.md

@@ -52,6 +52,12 @@ main() {
 
 通过函数，我们将“做什么”（业务）和“怎么做”（实现）分离开来，这是现代软件工程的基石。
 
+代码要点：
+
+`func` 默认返回 `Unit`，适合封装设备指令等“只产生副作用”的动作；参数类型明确后，调用端的意图也更清晰。
+高阶函数 `executeScene` 接收 `() -> Unit` 的函数参数，场景逻辑可以像数据一样传递，形成可插拔的流程编排。
+Lambda `{ => ... }` 会捕获外部变量（如场景配置），因此能够在不改动执行器的情况下组合新场景。
+
 ## 工程化提示
 
 *   设备驱动函数应保持幂等性，避免重复指令造成异常。

story/begin-v3/05_device_models.md

@@ -72,6 +72,12 @@ main() {
 }
 ```
 
+代码要点：
+
+`struct` 是值类型，适合表示“不可变的事件快照”，复制时会得到独立副本，避免外部随意修改历史记录。
+`class` 是引用类型，强调对象身份与生命周期，方法内直接修改状态会反映到所有持有引用的地方。
+初始化函数使用 `this` 绑定字段，让模型从构造开始就保持一致性与可读性。
+
 ## 工程化提示
 
 *   传感器数据应带上时间戳与来源，便于回溯。

story/begin-v3/06_unified_protocol.md

@@ -74,6 +74,12 @@ main() {
 }
 ```
 
+代码要点：
+
+接口 `Switchable` 定义了稳定的能力契约，实现类通过 `<:` 声明遵循协议，调用端只依赖接口即可获得多态行为。
+`masterSwitch` 的参数是接口类型，编译器会在运行时分派到具体实现，实现“品牌无关”的控制。
+`extend` 为现有类型添加方法，`this` 代表被扩展的实例，它不会破坏原有类型，适合作为工具增强层。
+
 ## 工程化提示
 
 *   协议定义要稳定清晰，避免频繁变更影响所有设备实现。

story/begin-v3/07_data_center.md

@@ -89,6 +89,12 @@ main() {
 }
 ```
 
+代码要点：
+
+`HashMap<String, ArrayList<String>>` 展示了嵌套泛型的表达能力，能精准描述“房间 -> 设备列表”的映射关系。
+`for (dev in roomDevices["Living Room"])` 依赖集合的迭代协议，让遍历逻辑保持简洁一致。
+`ConfigItem<T>` 将类型参数写进结构体，既能复用代码，又能让配置值在编译期保持类型安全。
+
 ## 工程化提示
 
 *   房间设备映射应考虑同步更新机制，避免配置漂移。

story/begin-v3/08_system_stability.md

@@ -83,6 +83,12 @@ main() {
 }
 ```
 
+代码要点：
+
+`Option` 的 `Some/None` 明确区分“可预期为空”的场景，配合 `match` 实现穷尽式处理，减少遗漏分支。
+`try-catch-finally` 让不可恢复的错误在关键路径被捕获并记录，同时通过 `finally` 保证收尾逻辑必然执行。
+带参数的枚举分支让指令携带上下文数据，比起多字段结构体更贴近业务语义。
+
 ## 工程化提示
 
 *   设备离线属于可预期错误，优先使用返回值而非抛异常。

story/begin-v3/09_parallel_processing.md

@@ -76,6 +76,12 @@ main() {
 }
 ```
 
+代码要点：
+
+`spawn` 会返回 `Future<Unit>`，`get()` 用于等待任务完成，构成最基础的并发同步模型。
+并发块内的闭包可以捕获外部变量（如 `totalPowerUsage`），使任务之间共享状态成为可能，但也因此需要原子或锁保护。
+`AtomicInt64.fetchAdd` 提供无锁的原子更新，适合高频计数场景。
+
 ## 工程化提示
 
 *   并发任务应设置超时与失败回调，避免阻塞主流程。

story/begin-v3/10_smart_hub.md

@@ -135,6 +135,12 @@ main() {
 
 智能家居只是物联网（IoT）的一个缩影。同样的逻辑可以应用在工业自动化、智慧城市等更广阔的领域。仓颉语言的高效与安全，将是你构建万物互联世界的坚实基石。
 
+代码要点：
+
+接口 `SmartDevice` 让控制中枢只依赖抽象能力，`public func getName() = name` 体现了表达式函数的简洁写法。
+`if (isOn) "ON" else "OFF"` 也是表达式，适合用于状态映射，减少冗余分支。
+`DateTime.now()` 与时间差计算展示了标准库时间 API，配合并发 `spawn` 与 `Future` 构成批量控制与耗时统计的完整链路。
+
 ## 工程化提示
 
 *   批量控制设备时建议设置超时与失败重试机制。

story/begin-v4/01_server_core.md

@@ -43,6 +43,12 @@ cjc web_core.cj -o server
 
 虽然它现在还不能处理真正的 HTTP 请求，但它已经具备了作为一个守护进程（Daemon）的基本形态。这是所有高性能服务器的起点。
 
+代码要点：
+
+`import std.time.*` 展示了模块导入语法，常用的时间工具会在启动阶段参与心跳与监控。
+`while (true)` 明确表达“持续运行”的服务生命周期，结合 `sleep(Duration.second * 5)` 可以避免空转占满 CPU。
+使用 `let` 声明端口与版本等常量，让配置意图一目了然，防止误写。
+
 ## 工程化提示
 
 *   真实服务需依赖标准网络库或框架，示例仅演示启动结构。

story/begin-v4/02_http_protocol.md

@@ -73,6 +73,12 @@ main() {
 }
 ```
 
+代码要点：
+
+枚举 `HttpMethod` 用 `extend` 增加方法，体现“数据 + 行为”的组合式设计，避免在外部写大量 `match`。
+`class Context` 作为引用类型，方便在中间件链中被多次修改；默认字段值让对象创建更轻量。
+初始化函数中使用 `this` 绑定成员，体现了仓颉面向对象的清晰语义。
+
 ## 工程化提示
 
 *   协议字段的命名要与标准一致，避免歧义。

story/begin-v4/03_router_logic.md

@@ -62,6 +62,12 @@ main() {
 }
 ```
 
+代码要点：
+
+`type Handler = (Context) -> Unit` 是函数类型别名，简化了路由表的类型声明。
+`HashMap<String, Handler>` 让处理函数像数据一样存储与检索，符合“路径 -> 行为”的模型。
+`router.add("/index") { ctx => ... }` 体现了 lambda 的简洁写法，使路由声明更接近 DSL 风格。
+
 ## 工程化提示
 
 *   路由匹配建议支持动态参数与方法过滤，本例只演示核心思路。

story/begin-v4/04_middleware_chain.md

@@ -90,6 +90,12 @@ main() {
 }
 ```
 
+代码要点：
+
+内部函数 `dispatch` 展示了函数嵌套与递归调用的能力，让中间件链构建保持私有封装。
+`let next = { => dispatch(index + 1) }` 创建闭包并捕获 `index`，体现洋葱模型的“前后包裹”语义。
+函数类型别名 `Middleware` 与 `Next` 让复杂签名变得可读，是构建框架 API 的常见方式。
+
 ## 工程化提示
 
 *   中间件顺序要固定并可配置，避免逻辑混乱。

story/begin-v4/05_ioc_container.md

@@ -89,6 +89,12 @@ main() {
 }
 ```
 
+代码要点：
+
+接口 `Service` 提供统一能力约束，容器可以只暴露接口类型，降低模块之间的耦合。
+`Option` 配合 `if (let Some(svc) <- ...)` 展示了模式匹配式的解包语法，避免空指针风险。
+`is`/`as` 体现了类型检查与显式转换，提示我们在强类型体系下要谨慎对待类型边界。
+
 ## 工程化提示
 
 *   真实 IoC 容器需要生命周期管理与依赖图校验，本例仅演示核心流程。

story/begin-v4/06_state_management.md

@@ -77,6 +77,12 @@ main() {
 }
 ```
 
+代码要点：
+
+带参数的枚举分支（如 `Paid(Float64)`）让状态天然携带业务上下文，减少额外字段。
+`match ((current, action))` 展示了元组模式匹配的写法，可把多个条件合并为清晰规则表。
+`case _` 为兜底分支，确保状态机在未知输入下仍保持稳定输出。
+
 ## 工程化提示
 
 *   状态机应集中管理流转规则，避免散落在多处业务逻辑。

story/begin-v4/07_async_worker.md

@@ -70,6 +70,12 @@ main() {
 }
 ```
 
+代码要点：
+
+`spawn` 启动轻量线程并返回 `Future<Unit>`，结合 `for (f in futures) { f.get() }` 实现最基础的同步等待。
+`Duration.millisecond * (id * 100)` 展示了时间单位的可读表达方式，便于描述 SLA 与性能测试。
+`AtomicInt64.fetchAdd` 适合高并发下的计数统计，不需要额外锁即可保证一致性。
+
 ## 工程化提示
 
 *   真实服务会使用线程池或协程框架，本例仅演示核心概念。

story/begin-v4/08_config_loader.md

@@ -68,6 +68,12 @@ main() {
 }
 ```
 
+代码要点：
+
+结构体 `AppConfig` 通过默认值表达“安全基线”，即便配置读取失败也能保证系统可启动。
+`throw Exception(...)` 与 `try/catch` 构成明确的异常路径，让错误处理与正常逻辑分离。
+在 `catch` 分支返回新的 `AppConfig()`，体现“值类型拷贝”的简单与安全。
+
 ## 工程化提示
 
 *   配置读取应区分“缺失”与“格式错误”，并提供清晰提示。

story/begin-v4/09_routing_dsl.md

@@ -88,6 +88,12 @@ main() {
 }
 ```
 
+代码要点：
+
+宏属于编译期能力，能在生成代码前读取结构并输出“路由注册”模板，减少重复样板。
+`public static func` 体现了静态方法的使用场景，适合承载编译期生成的集中注册逻辑。
+注解式 DSL 强调声明性，让业务代码更像“配置”，而具体实现仍由编译器生成可执行代码。
+
 ## 工程化提示
 
 *   DSL 设计要保持一致性，避免引入歧义。

story/begin-v4/10_full_stack_demo.md

@@ -131,6 +131,12 @@ main() {
 
 这正是从“码农”进阶为“架构师”的必经之路。继续探索吧，用仓颉构建更宏大的数字大厦！
 
+代码要点：
+
+`struct Post` 用值类型承载只读数据，而 `class BlogController` 管理依赖与行为，体现“数据/行为分离”的建模习惯。
+接口 `BlogService` 让控制器只依赖抽象能力，便于替换实现并进行测试。
+列表字面量 `[]` 与 `for (req in requests)` 展示了集合初始化与迭代语法，适合模拟请求流转。
+
 ## 工程化提示
 
 *   JSON 序列化应使用可靠库，避免手工拼接引入格式问题。

story/begin-v5/01_mission_briefing.md

@@ -30,6 +30,12 @@ main() {
 *   `main()` 是系统唯一入口，保持它“可读、简洁、稳定”。
 *   启动日志要包含服务名、版本、环境等关键信息。
 
+代码要点：
+
+`DateTime.now()` 提供高精度时间戳，适合写入启动日志并作为后续耗时统计的基准点。
+字符串模板 `${}` 可以直接拼接多字段信息，让启动输出保持一致格式。
+将 banner 输出提取成函数，可以让入口只负责流程编排，便于测试与复用。
+
 ## 工程化提示
 
 *   启动日志建议统一格式，以便后续接入日志平台。

story/begin-v5/02_domain_modeling.md

@@ -50,6 +50,12 @@ struct Warehouse {
 }
 ```
 
+代码要点：
+
+`struct` 适合描述“不可变快照”，复制后不会共享状态，避免订单数据被意外篡改。
+`class Vehicle` 作为引用类型，可以在多个模块中共享同一辆车的状态，`var load` 体现了可变业务属性。
+`public init` 与 `this` 的组合，让构造流程清晰、可读，便于统一校验逻辑。
+
 ## 工程化提示
 
 *   订单属于“数据快照”，适合用 `struct` 保持不可变。

story/begin-v5/03_dispatch_rules.md

@@ -45,6 +45,12 @@ main() {
 }
 ```
 
+代码要点：
+
+`if/else` 在仓颉中可直接返回字符串，让规则函数保持“输入 -> 输出”的清晰映射。
+数组字面量 `[]` 让样例数据创建更紧凑，配合类型推断简化测试用例。
+`for (order in orders)` 基于可迭代协议遍历集合，使批量调度逻辑更易读。
+
 ## 工程化提示
 
 *   条件判断应先处理异常或关键路径，减少分支嵌套。

story/begin-v5/04_strategy_functions.md

@@ -45,6 +45,12 @@ main() {
 }
 ```
 
+代码要点：
+
+`type ScoreFn = (Route) -> Float64` 把函数签名抽象成类型，使策略接口更稳定、更易复用。
+传入的闭包 `{ r => ... }` 会捕获外部上下文，让评分逻辑可以在不改动核心函数的情况下灵活替换。
+`Float64(r.congestion)` 展示了显式类型转换，确保算术计算的精度一致。
+
 ## 工程化提示
 
 *   策略函数命名要表达业务意图，如 `scoreByFast`。

story/begin-v5/05_route_collections.md

@@ -58,6 +58,12 @@ main() {
 }
 ```
 
+代码要点：
+
+`Cache<T>` 展示了泛型类的可复用能力，不同类型的缓存可共享同一套逻辑。
+`Mutex` 与 `synchronized(lock)` 提供最基础的临界区保护，避免并发写入导致缓存失真。
+`Option` 返回值让调用端明确区分“命中”与“未命中”，避免使用空值判断。
+
 ## 工程化提示
 
 *   缓存要设置过期策略，避免过时数据影响调度。

story/begin-v5/06_device_protocols.md

@@ -43,6 +43,12 @@ main() {
 }
 ```
 
+代码要点：
+
+接口 `Telemetry` 定义读取能力，设备类只需实现 `read()`，调度层即可通过多态屏蔽厂商差异。
+`struct SensorPacket` 适合承载采集快照，字段保持不可变有利于审计与追踪。
+`extend Float64` 让数值具备语义化展示方法，`this` 指向被扩展的实例，避免在业务层重复格式化。
+
 ## 工程化提示
 
 *   接口定义要稳定，避免频繁改动影响所有设备。

story/begin-v5/07_resilience_handling.md

@@ -48,6 +48,12 @@ main() {
 }
 ```
 
+代码要点：
+
+`Option` 的 `Some/None` 明确区分“数据不存在”与“系统失败”，让可预期错误走轻量路径。
+`match` 结构保证每个分支都被处理，逻辑更适合做审计与可追踪输出。
+`try-catch` 处理不可恢复异常时应尽量把错误上下文写入日志，便于后续问题复盘。
+
 ## 工程化提示
 
 *   能用返回值表达的错误不要抛异常，提升可控性。

story/begin-v5/08_concurrent_events.md

@@ -48,6 +48,12 @@ main() {
 }
 ```
 
+代码要点：
+
+`spawn { handleDockEvent("Dock-A") }` 返回 `Future<Int64>`，表明并发任务也可以带返回值。
+通过遍历 `futures` 并调用 `get()` 汇总结果，体现“并发执行 + 同步汇总”的常用模式。
+`AtomicInt64.fetchAdd` 让共享指标在并发场景中保持准确，避免手动加锁的开销。
+
 ## 工程化提示
 
 *   并发任务应设置超时和失败回调，避免任务悬挂。

story/begin-v5/09_state_machine.md

@@ -44,6 +44,12 @@ main() {
 }
 ```
 
+代码要点：
+
+带参数的枚举分支（如 `Assigned(String)`）让状态天然携带业务数据，避免额外的字段管理。
+`match ((state, action))` 通过元组匹配把规则集中表达，使状态机更像一张规则表。
+`case _ => state` 为兜底策略，保证未知动作不会破坏状态一致性。
+
 ## 工程化提示
 
 *   状态流转建议集中管理，避免散落在各模块。

story/begin-v5/10_config_and_io.md

@@ -64,6 +64,12 @@ main() {
 }
 ```
 
+代码要点：
+
+结构体默认值让配置具备“合理兜底”，即便读取失败也能维持基础运行。
+`throw` 与 `try/catch` 将异常路径显式化，避免隐藏的失败导致启动流程不透明。
+`orderToJson` 利用字符串模板输出序列化结果，便于快速验证字段是否齐全。
+
 ## 工程化提示
 
 *   配置分层加载（默认/文件/环境变量）更稳健。