init gobatch doc

Author: chararch

.github/workflows/docs.yml

@@ -0,0 +1,35 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - '**'  # 监控所有文件变化
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '16'
+
+      - name: Install dependencies
+        run: |
+          npm install -g gitbook-cli
+          gitbook install
+
+      - name: Build documentation
+        run: |
+          gitbook build
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./_book
+          force_orphan: true

SUMMARY.md

@@ -0,0 +1,28 @@
+# Summary
+
+* 中文文档
+    * [简介](zh/introduction.md)
+    * [快速开始](zh/quickstart.md)
+    * [基础知识](zh/basics.md)
+    * [架构设计](zh/architecture.md)
+    * [任务介绍](zh/job.md)
+    * [Step介绍](zh/step.md)
+    * [依赖](zh/dependencies.md)
+    * [配置](zh/configuration.md)
+    * [一个简单示例](zh/usage_examples.md)
+    * [文件处理示例](zh/file_examples.md)
+    * [贡献指南](zh/contribution_guide.md)
+    * [问题反馈](zh/feedback.md)
+* English Documentation
+    * [Introduction](en/introduction.md)
+    * [Quick Start](en/quickstart.md)
+    * [Basics](en/basics.md)
+    * [Architecture](en/architecture.md)
+    * [Job](en/job.md)
+    * [Step](en/step.md)
+    * [Dependencies](en/dependencies.md)
+    * [Configuration](en/configuration.md)
+    * [A Simple Example](en/usage_examples.md)
+    * [File Example](en/file_examples.md)
+    * [Contribution Guide](en/contribution_guide.md)
+    * [Feedback](en/feedback.md)

book.json

@@ -0,0 +1,28 @@
+{
+    "title": "GoBatch Documentation",
+    "description": "GoBatch batch processing framework documentation",
+    "language": "zh-hans",
+    "plugins": [
+        "-sharing",
+        "expandable-chapters",
+        "copy-code-button",
+        "language-picker"
+    ],
+    "pluginsConfig": {
+        "language-picker": {
+            "grid-columns": 2,
+            "languages": [
+                {
+                    "lang": "zh-hans",
+                    "name": "简体中文",
+                    "link": "zh"
+                },
+                {
+                    "lang": "en",
+                    "name": "English",
+                    "link": "en"
+                }
+            ]
+        }
+    }
+}

en/api_reference.md

@@ -0,0 +1,3 @@
+# API Reference
+
+The complete API documentation is available at [GoDoc](http://godoc.org/github.com/chararch/gobatch).

en/architecture.md

@@ -0,0 +1,192 @@
+# Architecture Design
+
+## Overall Architecture
+
+GoBatch consists of three layers:
+
+1. **Interface Layer**
+   - Provides APIs for upper-level applications
+   - Includes job orchestration, management, start and pause operations
+
+2. **Core Layer**
+   - Provides job execution engine
+   - Includes common components for data processing, file I/O, parallel processing, and error handling
+
+3. **Foundation Layer**
+   - Goroutine pool management
+   - Transaction management
+   - Job execution state recording
+   - Logging
+
+[](../images/layer.png)
+
+As a batch processing framework, GoBatch's core capabilities are job orchestration and execution. Applications must first complete job orchestration through GoBatch interfaces before executing tasks.
+
+In terms of job structure, a Job consists of multiple Steps, each containing business logic, executed in sequence. Job orchestration involves constructing different business logic into multiple Steps and assembling them into a Job in a specific order, managed by the GoBatch runtime. As a batch processing framework, GoBatch can manage multiple jobs.
+
+During job execution, applications can pass parameters to specified jobs. GoBatch generates a JobInstance based on the input parameters. A JobInstance may be executed multiple times, and for each execution, GoBatch creates a JobExecution record to track the execution state. Similarly, each Step execution generates a StepExecution record. GoBatch stores JobInstance, JobExecution, and StepExecution through Repository in the database.
+
+GoBatch supports multiple ways to trigger job execution. Applications can trigger jobs through scheduled tasks, real-time events, or command-line interfaces.
+
+The execution flow of GoBatch batch processing applications is as follows:
+
+[](../images/arch.png)
+
+## Core Components
+
+### Job
+Job is the highest-level concept in batch processing, representing a complete batch task. Each Job contains one or more Steps executed in a specific order. The main responsibility of a Job is to coordinate the execution of Steps. For detailed information about Jobs, see [Job](job.md).
+
+### Step
+Step is an independent processing unit within a Job. GoBatch supports three types of steps:
+
+1. **SimpleStep**
+   - Executes a task in a single thread
+   - Suitable for simple processing logic
+   - Implements business logic through Handler or Task interface
+
+2. **ChunkStep**
+   - Processes data in chunks
+   - Implements "read-process-write" pattern
+   - Supports transaction management
+   - Main components:
+     - ItemReader: Data reading
+     - ItemProcessor: Data processing
+     - ItemWriter: Data writing
+
+3. **PartitionStep**
+   - Supports parallel processing
+   - Splits large tasks into subtasks
+   - Can aggregate subtask results
+   - Main components:
+     - Partitioner: Task partitioning
+     - Aggregator: Result aggregation
+
+For detailed information about Steps, see [Step](step.md).
+
+### Builders
+
+1. **JobBuilder**
+   - Used to build Job instances
+   - Supports Steps and Listeners configuration
+   - Provides fluent API
+
+2. **StepBuilder**
+   - Used to build Step instances
+   - Supports Reader, Processor, Writer configuration
+   - Supports partition and listener configuration
+   - Provides fluent API
+
+[](../images/builder.png)
+
+## Execution Mechanism
+
+### Job Orchestration
+1. **Step Building**
+   - Create Step instances using StepBuilder
+   - Configure Step processing logic and behavior
+   - Set listeners and other parameters
+
+[](../images/step_builder.png)
+
+2. **Job Building**
+   - Create Job instances using JobBuilder
+   - Add Steps and configure execution order
+   - Set Job-level listeners
+
+[](../images/job_reassemble.png)
+
+3. **Registration**
+   - Register Job to JobRegistry
+   - Support runtime Job lookup and management
+
+### Job Execution
+
+1. **Job Execution Flow**
+   - Parameter validation
+   - Create JobInstance and JobExecution
+   - Execute Steps in sequence
+   - State management and context maintenance
+   - Process execution results
+
+2. **Step Execution Flow**
+   - Step initialization
+   - Resource allocation
+   - Execute business logic
+     - SimpleStep: Direct Handler execution
+     - ChunkStep: Iterative read-process-write
+     - PartitionStep: Parallel subtask execution
+   - Resource cleanup
+   - State update
+
+[](../images/start_job.png)
+
+### Transaction Management
+
+1. **TransactionManager**
+   - Manage database transactions
+   - Provide transaction begin, commit, and rollback operations
+   - Support custom transaction managers
+
+2. **Chunk Processing**
+   - Each Chunk as a transaction unit
+   - Support failure rollback
+   - Provide retry mechanism
+
+## Extension Mechanism
+
+### Listener Interfaces
+
+1. **JobListener**
+   - BeforeJob: Callback before job execution
+   - AfterJob: Callback after job execution
+
+2. **StepListener**
+   - BeforeStep: Callback before step execution
+   - AfterStep: Callback after step execution
+
+3. **ChunkListener**
+   - BeforeChunk: Callback before chunk processing
+   - AfterChunk: Callback after chunk processing
+   - OnError: Error handling callback
+
+4. **PartitionListener**
+   - BeforePartition: Callback before partitioning
+   - AfterPartition: Callback after partitioning
+   - OnError: Error handling callback
+
+## State Management
+
+### Execution State Recording
+GoBatch records runtime states through the following objects:
+
+1. **JobInstance**
+   - Corresponds to a set of parameters for a Job
+   - Same parameters map to the same JobInstance
+
+2. **JobExecution**
+   - Corresponds to one execution of a JobInstance
+   - Restart generates new JobExecution
+
+3. **StepContext**
+   - Corresponds to Step context under a JobInstance
+   - Independent of execution count
+
+4. **StepExecution**
+   - Corresponds to Step execution under a JobExecution
+   - Restart generates new StepExecution
+
+The database table relationships of these 4 objects are as follows:
+[](../images/status_record.png)
+
+### State Transitions
+Job and Step execution states:
+- STARTING: Waiting for execution
+- STARTED: Currently executing
+- STOPPING: Stopping in progress
+- STOPPED: Stopped
+- COMPLETED: Successfully completed
+- FAILED: Execution failed
+- UNKNOWN: Unknown state
+
+[](../images/status_trans.png)

en/basics.md

@@ -0,0 +1,23 @@
+# Basics
+
+## Core Concepts
+
+### Job
+A Job represents a complete batch processing task. It consists of one or more Steps that are executed in a specific sequence. Each Job has a unique name and can be configured with various parameters and listeners. For detailed information about Jobs, see [Job](job.md).
+
+### Step
+A Step is a single phase in a Job that encapsulates an independent unit of processing. GoBatch supports three types of steps:
+- **Simple Step**: Executes a single task in one thread
+- **Chunk Step**: Processes data in chunks (read-process-write pattern)
+- **Partition Step**: Splits a large task into multiple sub-tasks for parallel processing
+
+For detailed information about Steps, see [Step](step.md).
+
+### JobInstance
+A JobInstance represents a logical run of a Job, uniquely identified by the Job name and job parameters. Multiple JobExecutions may be created for a single JobInstance in case of failures.
+
+### JobExecution
+A JobExecution represents a single attempt to execute a JobInstance. Each execution tracks its status, start time, end time, and execution results.
+
+### StepExecution
+A StepExecution represents a single attempt to execute a Step within a JobExecution. It contains information about the step's execution status and results.

en/configuration.md

@@ -0,0 +1,37 @@
+# Configuration Guide
+
+## Global Settings
+
+### Database Configuration
+
+GoBatch needs a database to store job and step execution contexts, so you must set up the database connection before running any job.
+
+```go
+gobatch.SetDB(sqlDb)
+```
+
+### Transaction Manager
+
+For chunk steps, you must register a TransactionManager instance with GoBatch. The transaction manager interface is defined as:
+
+```go
+type TransactionManager interface {
+    BeginTx() (tx interface{}, err BatchError)
+    Commit(tx interface{}) BatchError
+    Rollback(tx interface{}) BatchError
+}
+```
+
+If you have set up the database but haven't set a transaction manager, GoBatch will create a default transaction manager instance for you.
+
+### Concurrency Control
+
+GoBatch uses internal task pools to run jobs and steps. You can set the maximum concurrency using:
+
+```go
+// Set maximum running jobs (default: 10)
+gobatch.SetMaxRunningJobs(100)
+
+// Set maximum running steps (default: 1000)
+gobatch.SetMaxRunningSteps(5000)
+```

en/contribution_guide.md

@@ -0,0 +1,31 @@
+# Contribution Guide
+
+## Development Setup
+
+1. **Fork Repository**
+   - Fork [GoBatch repository](https://github.com/chararch/gobatch)
+   - Clone locally
+
+## Code Standards
+
+- Use `gofmt` to format code
+- Add comments for exported items
+- Write unit tests
+
+## Submission Process
+
+1. **Create Branch**
+   - Use meaningful branch names (e.g., `feature/new-reader`)
+   - One task per branch
+
+2. **Commit Code**
+   - Clear commit messages
+   - Reference related issues
+
+3. **Update Documentation**
+   - Update relevant docs
+   - Ensure examples work
+
+4. **Submit PR**
+   - Describe changes
+   - Ensure tests pass