From b651b6af667f840e2133bd4b9f30319d78ec0ea5 Mon Sep 17 00:00:00 2001
From: caoqianming <caoqianming@foxmail.com>
Date: Mon, 20 Apr 2026 08:18:51 +0800
Subject: [PATCH] refactor(core): move doc handler to core and split API.md per
 app

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../app_feeder_distributor/src/handler/doc.rs | 36 ++-----------------
 crates/app_operation_system/src/handler.rs    |  1 +
 .../app_operation_system/src/handler/doc.rs   | 10 ++++++
 crates/app_operation_system/src/lib.rs        |  1 +
 crates/plc_platform_core/src/handler.rs       |  1 +
 crates/plc_platform_core/src/handler/doc.rs   | 23 ++++++++++++
 API.md => docs/api-feeder.md                  |  0
 docs/api-ops.md                               | 15 ++++++++
 8 files changed, 54 insertions(+), 33 deletions(-)
 create mode 100644 crates/app_operation_system/src/handler.rs
 create mode 100644 crates/app_operation_system/src/handler/doc.rs
 create mode 100644 crates/plc_platform_core/src/handler/doc.rs
 rename API.md => docs/api-feeder.md (100%)
 create mode 100644 docs/api-ops.md

diff --git a/crates/app_feeder_distributor/src/handler/doc.rs b/crates/app_feeder_distributor/src/handler/doc.rs
index cc30736..f9df9b9 100644
--- a/crates/app_feeder_distributor/src/handler/doc.rs
+++ b/crates/app_feeder_distributor/src/handler/doc.rs
@@ -1,40 +1,10 @@
-use axum::{
-    http::{header, HeaderMap, HeaderValue, StatusCode},
-    response::IntoResponse,
-};
-
+use axum::response::IntoResponse;
 use plc_platform_core::util::response::ApiErr;
 
 pub async fn get_api_md() -> Result<impl IntoResponse, ApiErr> {
-    let content = tokio::fs::read_to_string("API.md")
-        .await
-        .map_err(|err| {
-            tracing::error!("Failed to read API.md: {}", err);
-            ApiErr::NotFound("API.md not found".to_string(), None)
-        })?;
-
-    let mut headers = HeaderMap::new();
-    headers.insert(
-        header::CONTENT_TYPE,
-        HeaderValue::from_static("text/markdown; charset=utf-8"),
-    );
-
-    Ok((StatusCode::OK, headers, content))
+    plc_platform_core::handler::doc::serve_markdown("docs/api-feeder.md").await
 }
 
 pub async fn get_readme_md() -> Result<impl IntoResponse, ApiErr> {
-    let content = tokio::fs::read_to_string("README.md")
-        .await
-        .map_err(|err| {
-            tracing::error!("Failed to read README.md: {}", err);
-            ApiErr::NotFound("README.md not found".to_string(), None)
-        })?;
-
-    let mut headers = HeaderMap::new();
-    headers.insert(
-        header::CONTENT_TYPE,
-        HeaderValue::from_static("text/markdown; charset=utf-8"),
-    );
-
-    Ok((StatusCode::OK, headers, content))
+    plc_platform_core::handler::doc::serve_markdown("README.md").await
 }
diff --git a/crates/app_operation_system/src/handler.rs b/crates/app_operation_system/src/handler.rs
new file mode 100644
index 0000000..dc16bd5
--- /dev/null
+++ b/crates/app_operation_system/src/handler.rs
@@ -0,0 +1 @@
+pub mod doc;
diff --git a/crates/app_operation_system/src/handler/doc.rs b/crates/app_operation_system/src/handler/doc.rs
new file mode 100644
index 0000000..153d2ea
--- /dev/null
+++ b/crates/app_operation_system/src/handler/doc.rs
@@ -0,0 +1,10 @@
+use axum::response::IntoResponse;
+use plc_platform_core::util::response::ApiErr;
+
+pub async fn get_api_md() -> Result<impl IntoResponse, ApiErr> {
+    plc_platform_core::handler::doc::serve_markdown("docs/api-ops.md").await
+}
+
+pub async fn get_readme_md() -> Result<impl IntoResponse, ApiErr> {
+    plc_platform_core::handler::doc::serve_markdown("README.md").await
+}
diff --git a/crates/app_operation_system/src/lib.rs b/crates/app_operation_system/src/lib.rs
index de705cd..fc8028d 100644
--- a/crates/app_operation_system/src/lib.rs
+++ b/crates/app_operation_system/src/lib.rs
@@ -1,4 +1,5 @@
 pub mod app;
+pub mod handler;
 pub mod router;
 
 pub use app::{run, test_state, AppState};
diff --git a/crates/plc_platform_core/src/handler.rs b/crates/plc_platform_core/src/handler.rs
index f4ee9bc..7031130 100644
--- a/crates/plc_platform_core/src/handler.rs
+++ b/crates/plc_platform_core/src/handler.rs
@@ -1 +1,2 @@
+pub mod doc;
 pub mod log;
diff --git a/crates/plc_platform_core/src/handler/doc.rs b/crates/plc_platform_core/src/handler/doc.rs
new file mode 100644
index 0000000..de0fa9c
--- /dev/null
+++ b/crates/plc_platform_core/src/handler/doc.rs
@@ -0,0 +1,23 @@
+use axum::{
+    http::{header, HeaderMap, HeaderValue, StatusCode},
+    response::IntoResponse,
+};
+
+use crate::util::response::ApiErr;
+
+pub async fn serve_markdown(path: &str) -> Result<impl IntoResponse, ApiErr> {
+    let content = tokio::fs::read_to_string(path)
+        .await
+        .map_err(|err| {
+            tracing::error!("Failed to read {}: {}", path, err);
+            ApiErr::NotFound(format!("{} not found", path), None)
+        })?;
+
+    let mut headers = HeaderMap::new();
+    headers.insert(
+        header::CONTENT_TYPE,
+        HeaderValue::from_static("text/markdown; charset=utf-8"),
+    );
+
+    Ok((StatusCode::OK, headers, content))
+}
diff --git a/API.md b/docs/api-feeder.md
similarity index 100%
rename from API.md
rename to docs/api-feeder.md
diff --git a/docs/api-ops.md b/docs/api-ops.md
new file mode 100644
index 0000000..0f139c1
--- /dev/null
+++ b/docs/api-ops.md
@@ -0,0 +1,15 @@
+# 运转系统 API
+
+## 健康检查
+
+- `GET /api/health` — 返回应用名称和状态
+
+## 日志
+
+- `GET /api/logs` — 拉取日志内容
+- `GET /api/logs/stream` — SSE 增量推送
+
+## 文档
+
+- `GET /api/docs/api-md` — 获取 API 文档
+- `GET /api/docs/readme-md` — 获取 README