Update child spec builder implementation and docs

- Improve child spec builder implementation and test coverage

- Align example child spec builder usage with implementation

- Update English and Chinese child spec builder documentation

Author: developerworks

examples/child_spec_builder.rs

@@ -21,11 +21,15 @@ fn main() -> Result<(), SupervisorError> {
 
     // Build and print a worker child with fluent setters.
     demo_worker_builder()?;
-    // Build and print a one-shot job override on a worker base.
+    // Build and print a service child with service role defaults.
+    demo_service_builder()?;
+    // Build and print a job child with job role defaults.
     demo_job_builder()?;
     // Build and print a nested supervisor child.
     demo_supervisor_builder()?;
-    // Build and print a sidecar from the minimal `new` entry point.
+    // Build and print a sidecar child with sidecar role defaults.
+    demo_sidecar_builder()?;
+    // Build and print a worker from the minimal `new` entry point.
     demo_minimal_new_builder()?;
     // Show that `build` rejects invalid sidecar combinations.
     demo_build_failure()?;
@@ -61,25 +65,47 @@ fn demo_worker_builder() -> Result<(), SupervisorError> {
     Ok(())
 }
 
-/// Builds a one-shot job child by overriding role and restart policy on a worker base.
+/// Builds a service child with the `service` entry point.
+fn demo_service_builder() -> Result<(), SupervisorError> {
+    // Create a no-op async worker factory.
+    let factory = Arc::new(service_fn(|_ctx| async { TaskResult::Succeeded }));
+
+    // Build a service child with service role defaults.
+    let spec = ChildSpecBuilder::service(
+        ChildId::new("api-service"),
+        "API Service",
+        TaskKind::AsyncWorker,
+        factory,
+    )
+    .tag("service")
+    .group("api")
+    .build()?;
+
+    // Print the service summary.
+    println!("--- service entry ---");
+    print_spec_summary(&spec);
+    println!();
+    Ok(())
+}
+
+/// Builds a one-shot job child with the `job` entry point.
 fn demo_job_builder() -> Result<(), SupervisorError> {
     // Create a no-op async worker factory.
     let factory = Arc::new(service_fn(|_ctx| async { TaskResult::Succeeded }));
 
-    // Build a job child by overriding role and restart policy on a worker base.
-    let spec = ChildSpecBuilder::worker(
+    // Build a job child with job role defaults and a temporary restart policy.
+    let spec = ChildSpecBuilder::job(
         ChildId::new("nightly-export"),
         "Nightly Export",
         TaskKind::AsyncWorker,
         factory,
     )
-    .task_role(TaskRole::Job)
     .restart_policy(RestartPolicy::Temporary)
     .tag("job")
     .build()?;
 
     // Print the job summary.
-    println!("--- job override on worker base ---");
+    println!("--- job entry ---");
     print_spec_summary(&spec);
     println!();
     Ok(())
@@ -99,27 +125,47 @@ fn demo_supervisor_builder() -> Result<(), SupervisorError> {
     Ok(())
 }
 
-/// Builds a sidecar from the minimal `new` entry point plus required fields.
-fn demo_minimal_new_builder() -> Result<(), SupervisorError> {
+/// Builds a sidecar child with the `sidecar` entry point.
+fn demo_sidecar_builder() -> Result<(), SupervisorError> {
     // Identify the primary child that the sidecar follows.
     let primary_id = ChildId::new("api");
     // Create a no-op async worker factory.
     let factory = Arc::new(service_fn(|_ctx| async { TaskResult::Succeeded }));
 
-    // Build a sidecar from the minimal `new` entry point plus required fields.
-    let spec = ChildSpecBuilder::new(ChildId::new("metrics-sidecar"), "Metrics Sidecar")
+    // Build a sidecar whose primary child is also added as a dependency.
+    let spec = ChildSpecBuilder::sidecar(
+        ChildId::new("metrics-sidecar"),
+        "Metrics Sidecar",
+        TaskKind::AsyncWorker,
+        factory,
+        SidecarConfig::new(primary_id, false),
+    )
+    .tag("sidecar")
+    .build()?;
+
+    // Print the sidecar summary including dependency ids.
+    println!("--- sidecar entry ---");
+    print_spec_summary(&spec);
+    println!("  dependencies      = {:?}", spec.dependencies);
+    println!();
+    Ok(())
+}
+
+/// Builds a worker from the minimal `new` entry point plus required fields.
+fn demo_minimal_new_builder() -> Result<(), SupervisorError> {
+    // Create a no-op async worker factory.
+    let factory = Arc::new(service_fn(|_ctx| async { TaskResult::Succeeded }));
+
+    // Build a worker from the minimal `new` entry point plus required fields.
+    let spec = ChildSpecBuilder::new(ChildId::new("custom-worker"), "Custom Worker")
         .kind(TaskKind::AsyncWorker)
         .factory(factory)
-        .task_role(TaskRole::Sidecar)
-        .sidecar_config(SidecarConfig::new(primary_id.clone(), false))
-        .dependency(primary_id)
-        .tag("sidecar")
+        .tag("custom")
         .build()?;
 
-    // Print the sidecar summary including dependency ids.
+    // Print the custom worker summary.
     println!("--- new entry + setters ---");
     print_spec_summary(&spec);
-    println!("  dependencies      = {:?}", spec.dependencies);
     println!();
     Ok(())
 }

manual/en/child-spec-builder.md

@@ -31,6 +31,9 @@ Legacy code may still mutate fields after construction. New code should prefer t
 | Method | Purpose | Default highlights |
 | --- | --- | --- |
 | `worker(id, name, kind, factory)` | Async or blocking worker | Matches `ChildSpec::worker`: `Transient` restart, `Critical` criticality, `TaskRole::Worker`, and so on |
+| `service(id, name, kind, factory)` | Long-running service | Based on worker defaults: `TaskRole::Service`, `Critical` criticality |
+| `job(id, name, kind, factory)` | Finite job | Based on worker defaults: `TaskRole::Job`, `Optional` criticality |
+| `sidecar(id, name, kind, factory, sidecar_config)` | Sidecar attached to a primary child | Based on worker defaults: `TaskRole::Sidecar`, writes `sidecar_config`, and automatically adds the primary child dependency |
 | `supervisor(id, name)` | Nested supervisor | `kind = Supervisor`, `factory = None`, `task_role = Supervisor`, `criticality = Critical` |
 | `new(id, name)` | Minimal skeleton | Sets only `id` / `name` plus baseline policies; caller must add `kind` and, for workers, `factory` |
 
@@ -40,6 +43,8 @@ Legacy code may still mutate fields after construction. New code should prefer t
 | --- | --- |
 | `build()` | Takes the inner `ChildSpec`, calls `validate()`, returns `Ok(spec)` or `SupervisorError` |
 
+All entry methods and setters return `ChildSpecBuilder`, which means construction is still in progress. Only `build()` consumes the builder and returns the final `ChildSpec`.
+
 There is **no** `build_validated()`. Validation is always performed inside `build()`.
 
 `ChildSpec::worker(...)` also returns `Result<ChildSpec, SupervisorError>` via `ChildSpecBuilder::worker(...).build()`.
@@ -87,31 +92,45 @@ Naming convention: plural fields use `dependencies(...)`, `tags(...)`; singular
 
 ## Common combinations
 
-### Job override
+### Service
+
+Long-running services should prefer `service(...)`; callers do not need to set `TaskRole::Service` by hand:
+
+```rust
+ChildSpecBuilder::service(id, "API Service", TaskKind::AsyncWorker, factory)
+    .tag("service")
+    .build()?;
+```
+
+### Job
 
-Override `task_role` and `restart_policy` on a worker base:
+Finite work should prefer `job(...)`. You can still override `restart_policy` for one-shot behavior:
 
 ```rust
-ChildSpecBuilder::worker(id, "Nightly Export", TaskKind::AsyncWorker, factory)
-    .task_role(TaskRole::Job)
+ChildSpecBuilder::job(id, "Nightly Export", TaskKind::AsyncWorker, factory)
     .restart_policy(RestartPolicy::Temporary)
     .build()?;
 ```
 
 ### Sidecar
 
-When `task_role = Sidecar`, you must also set `sidecar_config`, or `build()` validation fails:
+Sidecars attached to a primary child should prefer `sidecar(...)`. This entry writes `sidecar_config` and automatically adds the primary child dependency:
 
 ```rust
-use rust_supervisor::policy::task_role_defaults::{SidecarConfig, TaskRole};
-
-ChildSpecBuilder::worker(id, "Metrics Sidecar", TaskKind::AsyncWorker, factory)
-    .task_role(TaskRole::Sidecar)
-    .sidecar_config(SidecarConfig::new(primary_id.clone(), false))
-    .dependency(primary_id)
-    .build()?;
+use rust_supervisor::policy::task_role_defaults::SidecarConfig;
+
+ChildSpecBuilder::sidecar(
+    id,
+    "Metrics Sidecar",
+    TaskKind::AsyncWorker,
+    factory,
+    SidecarConfig::new(primary_id.clone(), false),
+)
+.build()?;
 ```
 
+If you still configure `task_role = Sidecar` manually with setters, you must also set `sidecar_config`, or `build()` validation fails.
+
 ### Worker from `new()`
 
 ```rust
@@ -124,7 +143,7 @@ ChildSpecBuilder::new(ChildId::new("custom"), "custom")
 ## Data flow (short)
 
 ```text
-ChildSpecBuilder::worker / supervisor / new
+ChildSpecBuilder::worker / service / job / sidecar / supervisor / new
         |
         v
    fluent setters (policy, role, deps, env, ...)
@@ -144,7 +163,7 @@ Runnable demo:
 cargo run --example child_spec_builder
 ```
 
-Source: [`examples/child_spec_builder.rs`](../../examples/child_spec_builder.rs). Covers worker, job override, supervisor, `new()` + sidecar, and an intentionally invalid sidecar combination.
+Source: [`examples/child_spec_builder.rs`](../../examples/child_spec_builder.rs). Covers worker, service, job, sidecar, supervisor, the `new()` path, and an intentionally invalid sidecar combination.
 
 ## Tests and regression
 
@@ -154,6 +173,9 @@ External tests: [`src/spec/tests/child_builder_test.rs`](../../src/spec/tests/ch
 | --- | --- |
 | `worker_builder_matches_child_spec_worker_defaults` | Builder output matches `ChildSpec::worker` field-for-field |
 | `supervisor_builder_produces_valid_supervisor_child` | Supervisor entry has no factory and validates |
+| `service_builder_sets_service_role` | Service entry sets `TaskRole::Service` and `Critical` criticality |
+| `job_builder_sets_job_role_and_optional_criticality` | Job entry sets `TaskRole::Job` and `Optional` criticality |
+| `sidecar_builder_sets_sidecar_role_binding_and_dependency` | Sidecar entry sets the binding and automatically adds the primary child dependency |
 | `builder_setters_apply_expected_fields` | Sidecar, dependency, tag, and related setters |
 | `build_rejects_invalid_sidecar_combination` | Missing `sidecar_config` makes `build()` fail |
 | `new_builder_can_build_valid_worker_with_factory` | `new()` path works after required fields are set |

manual/en/child-spec.md

@@ -91,6 +91,9 @@ Entry methods:
 | Method                              | Purpose                                                                 |
 | ----------------------------------- | ----------------------------------------------------------------------- |
 | `ChildSpecBuilder::worker(...)`     | Async or blocking worker; defaults match `ChildSpec::worker`            |
+| `ChildSpecBuilder::service(...)`    | Long-running service; sets `TaskRole::Service`                          |
+| `ChildSpecBuilder::job(...)`        | Finite job; sets `TaskRole::Job`                                         |
+| `ChildSpecBuilder::sidecar(...)`    | Sidecar; sets sidecar binding and the primary child dependency           |
 | `ChildSpecBuilder::supervisor(...)` | Nested supervisor; no factory                                           |
 | `ChildSpecBuilder::new(...)`        | Minimal skeleton; caller must set `kind` and, for workers, `factory`    |
 

manual/zh/child-spec-builder.md

@@ -31,6 +31,9 @@ use rust_supervisor::spec::child_builder::ChildSpecBuilder;
 | 方法 | 用途 | 默认值要点 |
 |---|---|---|
 | `worker(id, name, kind, factory)` | 异步或阻塞 worker | 与 `ChildSpec::worker` 一致: `Transient` 重启, `Critical` 关键性, `TaskRole::Worker` 等 |
+| `service(id, name, kind, factory)` | 常驻 service(服务) | 基于 worker 默认值: `TaskRole::Service`, `Critical` 关键性 |
+| `job(id, name, kind, factory)` | 有限生命周期 job(一次性任务) | 基于 worker 默认值: `TaskRole::Job`, `Optional` 关键性 |
+| `sidecar(id, name, kind, factory, sidecar_config)` | 跟随 primary child(主子任务) 的 sidecar(边车) | 基于 worker 默认值: `TaskRole::Sidecar`, 写入 `sidecar_config`, 并自动加入 primary child 依赖 |
 | `supervisor(id, name)` | 嵌套 supervisor(监督器) | `kind = Supervisor`, `factory = None`, `task_role = Supervisor`, `criticality = Critical` |
 | `new(id, name)` | 最小骨架 | 仅填 `id` / `name` 与 baseline(基线) 策略; 调用方需自行补 `kind`, 以及 worker 所需的 `factory` |
 
@@ -40,6 +43,8 @@ use rust_supervisor::spec::child_builder::ChildSpecBuilder;
 |---|---|
 | `build()` | 取出内部 `ChildSpec`, 调用 `validate()`, 成功返回 `Ok(spec)`, 失败返回 `SupervisorError` |
 
+所有入口方法和 setter(设置器) 都返回 `ChildSpecBuilder`, 只表示"还在构造中". 只有 `build()` 会消费 builder(构建器), 并返回最终 `ChildSpec`.
+
 **没有** `build_validated()`. 校验统一在 `build()` 内完成.
 
 `ChildSpec::worker(...)` 同样返回 `Result<ChildSpec, SupervisorError>`, 实现为 `ChildSpecBuilder::worker(...).build()`.
@@ -87,31 +92,45 @@ fn build_worker() -> Result<ChildSpec, SupervisorError> {
 
 ## 常见组合示例
 
-### Job (一次性任务) 覆盖
+### Service (服务)
+
+常驻服务优先使用 `service(...)`, 不需要手动设置 `TaskRole::Service`:
+
+```rust
+ChildSpecBuilder::service(id, "API Service", TaskKind::AsyncWorker, factory)
+    .tag("service")
+    .build()?;
+```
+
+### Job (一次性任务)
 
-在 worker 基座上改 `task_role` 与 `restart_policy`:
+有限生命周期任务优先使用 `job(...)`. 如果需要一次运行后停止, 可以继续覆盖 `restart_policy`:
 
 ```rust
-ChildSpecBuilder::worker(id, "Nightly Export", TaskKind::AsyncWorker, factory)
-    .task_role(TaskRole::Job)
+ChildSpecBuilder::job(id, "Nightly Export", TaskKind::AsyncWorker, factory)
     .restart_policy(RestartPolicy::Temporary)
     .build()?;
 ```
 
 ### Sidecar (边车)
 
-`task_role = Sidecar` 时必须同时设置 `sidecar_config`, 否则 `build()` 校验失败:
+跟随主任务的边车优先使用 `sidecar(...)`. 这个入口会写入 `sidecar_config`, 并把 primary child 自动加入依赖:
 
 ```rust
-use rust_supervisor::policy::task_role_defaults::{SidecarConfig, TaskRole};
-
-ChildSpecBuilder::worker(id, "Metrics Sidecar", TaskKind::AsyncWorker, factory)
-    .task_role(TaskRole::Sidecar)
-    .sidecar_config(SidecarConfig::new(primary_id.clone(), false))
-    .dependency(primary_id)
-    .build()?;
+use rust_supervisor::policy::task_role_defaults::SidecarConfig;
+
+ChildSpecBuilder::sidecar(
+    id,
+    "Metrics Sidecar",
+    TaskKind::AsyncWorker,
+    factory,
+    SidecarConfig::new(primary_id.clone(), false),
+)
+.build()?;
 ```
 
+如果仍然用 setter(设置器) 手动设置 `task_role = Sidecar`, 就必须同时设置 `sidecar_config`, 否则 `build()` 校验失败.
+
 ### 从 `new()` 拼出 worker
 
 ```rust
@@ -124,7 +143,7 @@ ChildSpecBuilder::new(ChildId::new("custom"), "custom")
 ## 数据流 (简图)
 
 ```text
-ChildSpecBuilder::worker / supervisor / new
+ChildSpecBuilder::worker / service / job / sidecar / supervisor / new
         |
         v
    链式 setter (policy, role, deps, env, ...)
@@ -144,7 +163,7 @@ ChildSpecBuilder::worker / supervisor / new
 cargo run --example child_spec_builder
 ```
 
-源码: [`examples/child_spec_builder.rs`](../../examples/child_spec_builder.rs). 覆盖 worker, job 覆盖, supervisor, `new()` + sidecar, 以及故意失败的 sidecar 组合.
+源码: [`examples/child_spec_builder.rs`](../../examples/child_spec_builder.rs). 覆盖 worker, service, job, sidecar, supervisor, `new()` 路径, 以及故意失败的 sidecar 组合.
 
 ## 测试与回归
 
@@ -154,6 +173,9 @@ cargo run --example child_spec_builder
 |---|---|
 | `worker_builder_matches_child_spec_worker_defaults` | Builder 与 `ChildSpec::worker` 字段一致 |
 | `supervisor_builder_produces_valid_supervisor_child` | supervisor 入口无 factory 且可校验 |
+| `service_builder_sets_service_role` | service 入口设置 `TaskRole::Service` 与 `Critical` 关键性 |
+| `job_builder_sets_job_role_and_optional_criticality` | job 入口设置 `TaskRole::Job` 与 `Optional` 关键性 |
+| `sidecar_builder_sets_sidecar_role_binding_and_dependency` | sidecar 入口设置绑定并自动加入 primary child 依赖 |
 | `builder_setters_apply_expected_fields` | sidecar, dependency, tag 等 setter |
 | `build_rejects_invalid_sidecar_combination` | 缺 `sidecar_config` 时 `build()` 失败 |
 | `new_builder_can_build_valid_worker_with_factory` | `new()` 路径补全后可构建 |

manual/zh/child-spec.md

@@ -89,6 +89,9 @@ let spec = ChildSpecBuilder::worker(
 | 方法                                | 用途                                                 |
 | ----------------------------------- | ---------------------------------------------------- |
 | `ChildSpecBuilder::worker(...)`     | 异步或阻塞 worker, 默认值与 `ChildSpec::worker` 一致 |
+| `ChildSpecBuilder::service(...)`    | 常驻 service(服务), 自动设置 `TaskRole::Service`     |
+| `ChildSpecBuilder::job(...)`        | 有限生命周期 job(一次性任务), 自动设置 `TaskRole::Job` |
+| `ChildSpecBuilder::sidecar(...)`    | sidecar(边车), 自动设置绑定和主子任务依赖            |
 | `ChildSpecBuilder::supervisor(...)` | 嵌套 supervisor, 无 factory                          |
 | `ChildSpecBuilder::new(...)`        | 最小骨架, 需自行补 `kind` 和 `factory`               |