refactor(layout): unify public headers and source directories

.clang-format-ignore

@@ -3,7 +3,7 @@ src/proto/cpp/
 include/ark/meta_define.hpp
 tests/catch.hpp
 tests/network/doctest.h
-plugins/utility/include/ark/utility/ctpl.h
-plugins/utility/include/ark/utility/ctpl_stl.h
-plugins/physic/include/ark/physic/wave_front.cpp
-plugins/physic/include/ark/physic/wave_front.hpp
+include/ark/utility/ctpl.h
+include/ark/utility/ctpl_stl.h
+src/plugins/physic/wave_front.cpp
+include/ark/physic/wave_front.hpp

.clang-tidy

@@ -1,8 +1,8 @@
 ---
 Checks: '-*,readability-identifier-naming,modernize-use-nullptr,modernize-use-override'
 WarningsAsErrors: ''
-HeaderFilterRegex: '(^|/)(include/ark/|plugins/[^/]+/(include/ark/|src/)|src/|examples/|tests/)'
-ExcludeHeaderFilterRegex: '(\.pb\.(h|cc)$|(^|/)(catch\.hpp|doctest\.h)$|(^|/)(plugins/utility/include/ark/utility/ctpl(_stl)?\.h|plugins/physic/include/ark/physic/wave_front\.(hpp|cpp))$)'
+HeaderFilterRegex: '(^|/)(include/ark/|src/|examples/|tests/|benchmarks/)'
+ExcludeHeaderFilterRegex: '(\.pb\.(h|cc)$|(^|/)(catch\.hpp|doctest\.h)$|(^|/)(include/ark/utility/ctpl(_stl)?\.h|include/ark/physic/wave_front\.hpp|src/plugins/physic/wave_front\.cpp)$)'
 FormatStyle: file
 CheckOptions:
   readability-identifier-naming.CheckAnonFieldInParent: true

CMakeLists.txt

@@ -213,24 +213,7 @@ if(ARK_BUILD_CONFIG)
     add_subdirectory(src/config)
 endif()
 
-add_library(ark_core INTERFACE)
-add_library(ark::core ALIAS ark_core)
-target_compile_features(ark_core INTERFACE cxx_std_20)
-target_include_directories(ark_core INTERFACE
-    "$<BUILD_INTERFACE:${ROOT_DIR}/include>"
-    "$<BUILD_INTERFACE:${3RD_PARTY_DIR}>"
-    "$<BUILD_INTERFACE:${3RD_PARTY_DIR}/spdlog/include>"
-    "${RAPIDXML_INCLUDE_DIR}")
-target_link_libraries(ark_core INTERFACE arknet::arknet ${CMAKE_DL_LIBS})
-target_compile_definitions(ark_core INTERFACE
-    $<$<BOOL:${ARK_USE_GUID_32}>:ARK_USE_GUID_32>
-    $<$<BOOL:${ARK_DOCKER_ALPINE}>:ARK_DOCKER_ALPINE>
-    $<$<BOOL:${ARK_OPEN_FILE_LOG}>:OPEN_FILE_LOG>
-    $<$<CONFIG:Debug>:_DEBUG>)
-if(MSVC)
-    target_compile_options(ark_core INTERFACE /bigobj /utf-8 /Zc:__cplusplus)
-    target_compile_definitions(ark_core INTERFACE WIN32_LEAN_AND_MEAN _WIN32_WINNT=0x0601)
-endif()
+add_subdirectory(src/core)
 
 add_library(ark_sdk INTERFACE)
 add_library(ark::ark ALIAS ark_sdk)
@@ -280,7 +263,7 @@ if(ARK_BUILD_PROTO)
     add_subdirectory(src/proto)
     target_link_libraries(ark_sdk INTERFACE ark::proto)
 endif()
-add_subdirectory(plugins)
+add_subdirectory(src/plugins)
 link_libraries(ark::ark)
 if(ARK_BUILD_APPLICATIONS)
     add_subdirectory(src/app)

benchmarks/CMakeLists.txt

@@ -14,7 +14,7 @@ if(ARK_BUILD_DATABASE_BENCHMARKS)
     endif()
     find_package(Threads REQUIRED)
     add_executable(ark_database_benchmark database.cpp)
-    target_include_directories(ark_database_benchmark PRIVATE "${ROOT_DIR}/plugins")
+    target_include_directories(ark_database_benchmark PRIVATE "${ROOT_DIR}/src/plugins")
     target_link_libraries(ark_database_benchmark PRIVATE arknet::arknet Threads::Threads)
     if(WIN32)
         target_link_libraries(ark_database_benchmark PRIVATE psapi)

benchmarks/database.cpp

@@ -29,9 +29,9 @@
 #endif
 
 #include "detail/database_awaitable.hpp"
-#include "redis/src/detail/redis_service.hpp"
+#include "redis/detail/redis_service.hpp"
 #if defined(ARKNET_ENABLE_SSL)
-#include "mysql/src/detail/mysql_service.hpp"
+#include "mysql/detail/mysql_service.hpp"
 #endif
 
 namespace {

docs/concepts/architecture.md

@@ -5,7 +5,7 @@
 | Application | Select plugins and process configuration | [Application sources](https://github.com/OpenArkStudio/ark/tree/main/src/app) |
 | Plugin | Install and uninstall a group of modules | [ark::sample1_plugin](https://github.com/OpenArkStudio/ark/blob/main/examples/sample1/sample1_plugin.cpp) |
 | Module | Provide an interface and participate in the application lifecycle | [ark::module](https://github.com/OpenArkStudio/ark/blob/main/include/ark/module.hpp) |
-| Networking | Integrate arknet endpoints and queue application messages/events | [Network plugin](https://github.com/OpenArkStudio/ark/tree/main/plugins/net) |
+| Networking | Integrate arknet endpoints and queue application messages/events | [Network plugin](https://github.com/OpenArkStudio/ark/tree/main/src/plugins/net) |
 
 The module interface offers `init`, `post_init`, `check_config`, `pre_update`, `update`, `pre_shut` and `shut`. Keep initialization and shutdown responsibilities paired. Stop callback sources before releasing modules they reference.
 

docs/concepts/architecture_CN.md

@@ -5,7 +5,7 @@
 | 应用 | 选择插件与进程配置 | [应用源码](https://github.com/OpenArkStudio/ark/tree/main/src/app) |
 | 插件 | 安装与卸载一组模块 | [ark::sample1_plugin](https://github.com/OpenArkStudio/ark/blob/main/examples/sample1/sample1_plugin.cpp) |
 | 模块 | 提供接口，参与应用生命周期 | [ark::module](https://github.com/OpenArkStudio/ark/blob/main/include/ark/module.hpp) |
-| 网络 | 使用 arknet 端点，排队分发业务消息与事件 | [网络插件](https://github.com/OpenArkStudio/ark/tree/main/plugins/net) |
+| 网络 | 使用 arknet 端点，排队分发业务消息与事件 | [网络插件](https://github.com/OpenArkStudio/ark/tree/main/src/plugins/net) |
 
 模块接口提供 `init`、`post_init`、`check_config`、`pre_update`、`update`、`pre_shut` 和 `shut`。初始化与关闭职责应成对处理；释放模块前，先停止引用它的回调来源。
 

docs/guides/data-structures.md

@@ -1,6 +1,6 @@
 # Data structures and metadata
 
-The separation of definitions and values remains: metadata describes field names, indices, types and flags; entities retain definitions and values. Public types now live in `plugins/kernel/include/ark/kernel/` with the snake_case names below. See [configuration tools](tools.md) for generated C++ and [Protobuf](../reference/protobuf.md) for protocol messages.
+The separation of definitions and values remains: metadata describes field names, indices, types and flags; entities retain definitions and values. Public types now live in `include/ark/kernel/` with the snake_case names below. See [configuration tools](tools.md) for generated C++ and [Protobuf](../reference/protobuf.md) for protocol messages.
 
 | Historical name | Current name |
 | --- | --- |

docs/guides/data-structures_CN.md

@@ -1,6 +1,6 @@
 # 数据结构与元数据
 
-数据与定义分离的设计仍保留：元数据描述字段名、下标、类型和标志，实体保存引用及其值。当前公开类型位于 `plugins/kernel/include/ark/kernel/`，使用以下 snake_case 名称。配置工具生成 C++ 的流程见[配置工具](tools_CN.md)，协议消息见 [Protobuf](../reference/protobuf_CN.md)。
+数据与定义分离的设计仍保留：元数据描述字段名、下标、类型和标志，实体保存引用及其值。当前公开类型位于 `include/ark/kernel/`，使用以下 snake_case 名称。配置工具生成 C++ 的流程见[配置工具](tools_CN.md)，协议消息见 [Protobuf](../reference/protobuf_CN.md)。
 
 | 旧名称 | 当前名称 |
 | --- | --- |

docs/project-layout.md

@@ -16,13 +16,14 @@ build's artifacts into the runtime's `bin/` directory.
 
 | Path | Contents |
 | --- | --- |
-| `include/ark/` | Public core headers |
+| `include/ark/` | Public core and plugin headers |
+| `src/core/` | Core CMake target and header-only usage requirements |
 | `src/app/` | Application entry point |
 | `src/proto/` | Protocol schemas and codec implementation |
 | `src/server/` | Built-in server applications |
-| `plugins/<name>/include/ark/<name>/` | Public headers for an official plugin |
-| `plugins/<name>/src/` | Plugin implementation |
-| `plugins/<name>/tests/` | Tests specific to that plugin, when provided |
+| `include/ark/<name>/` | Public headers for an official plugin |
+| `src/plugins/<name>/` | Plugin implementation |
+| `tests/` | Core, network and private database regressions |
 | `tests/network/` | Network and logging regressions |
 | `tests/consumer/` | An independent project consuming the public SDK |
 | `examples/` | Application examples |

docs/project-layout_CN.md

@@ -14,13 +14,14 @@ ark 使用 C++20。核心与官方插件放在本仓库，业务插件放在应
 
 | 路径 | 内容 |
 | --- | --- |
-| `include/ark/` | 核心公开头文件 |
+| `include/ark/` | 核心与插件公开头文件 |
+| `src/core/` | 核心 CMake target 与 header-only 使用要求 |
 | `src/app/` | 应用入口 |
 | `src/proto/` | 协议定义与编解码实现 |
 | `src/server/` | 内置服务端应用 |
-| `plugins/<name>/include/ark/<name>/` | 官方插件公开头文件 |
-| `plugins/<name>/src/` | 插件实现 |
-| `plugins/<name>/tests/` | 插件专属测试，按需提供 |
+| `include/ark/<name>/` | 官方插件公开头文件 |
+| `src/plugins/<name>/` | 插件实现 |
+| `tests/` | 核心、网络与私有数据库回归测试 |
 | `tests/network/` | 网络与日志回归测试 |
 | `tests/consumer/` | 独立使用公开 SDK 的示例项目 |
 | `examples/` | 应用示例 |

docs/project/plugin-organization.md

@@ -1,34 +1,36 @@
 # Official plugins and repository organization
 
-The project now uses top-level `plugins/<name>/`, public core headers in `include/ark/` and implementations in `src/`. Core and official plugins belong in `ark`; business plugins belong in application repositories; `arknet` remains independent. Hot-update design and implementation are deferred while individual plugin integrations receive their own functional acceptance. The directory and snake_case migration is complete.
+Public core and plugin headers live in `include/ark/`; core build definitions live in `src/core/` and official plugin implementations in `src/plugins/<name>/`. Core and official plugins belong in `ark`; business plugins belong in application repositories; `arknet` remains independent. Hot-update design and implementation are deferred while individual plugin integrations receive their own functional acceptance. The directory and snake_case migration is complete.
 
 ## Existing implementations
 
 | Repository | Related code in ark | Proposed destination | Integration work |
 | --- | --- | --- | --- |
-| [MySQLPlugin](https://github.com/OpenArkStudio/MySQLPlugin) | `plugins/mysql` | `plugins/mysql` | Implement the MySQL client in arknet; integrate configuration, connection services and business callbacks in the plugin |
-| [RedisPlugin](https://github.com/OpenArkStudio/RedisPlugin) | `plugins/redis` | `plugins/redis` | Implement the Redis client in arknet, then replace aredis and bredis calls |
-| [URLPlugin](https://github.com/OpenArkStudio/URLPlugin) | Net HTTP client and HTTP server plugin | `plugins/http` | Compare libcurl requests, encoding and actor integration; unify the HTTP service interface |
-| [LuaScriptPlugin](https://github.com/OpenArkStudio/LuaScriptPlugin) | Integration with the new plugin interface required | `plugins/lua` | Define bindings and script lifecycle; replace old NFComm interface dependencies |
-| [ActorPlugin](https://github.com/OpenArkStudio/ActorPlugin) | Integration with the new plugin interface required | `plugins/actor` | Define task scheduling, message delivery and business-thread responsibilities |
+| [MySQLPlugin](https://github.com/OpenArkStudio/MySQLPlugin) | `src/plugins/mysql` | `src/plugins/mysql` | Implement the MySQL client in arknet; integrate configuration, connection services and business callbacks in the plugin |
+| [RedisPlugin](https://github.com/OpenArkStudio/RedisPlugin) | `src/plugins/redis` | `src/plugins/redis` | Implement the Redis client in arknet, then replace aredis and bredis calls |
+| [URLPlugin](https://github.com/OpenArkStudio/URLPlugin) | Net HTTP client and HTTP server plugin | `src/plugins/http` | Compare libcurl requests, encoding and actor integration; unify the HTTP service interface |
+| [LuaScriptPlugin](https://github.com/OpenArkStudio/LuaScriptPlugin) | Integration with the new plugin interface required | `src/plugins/lua` | Define bindings and script lifecycle; replace old NFComm interface dependencies |
+| [ActorPlugin](https://github.com/OpenArkStudio/ActorPlugin) | Integration with the new plugin interface required | `src/plugins/actor` | Define task scheduling, message delivery and business-thread responsibilities |
 
 These repositories use different generations of interfaces and build systems. Compare features, overlapping implementations and dependencies during integration. MySQL and Redis clients belong in arknet; discuss other plugin dependencies separately.
 
-## Proposed layout
+## Directory layout
 
 ```text
 ark/
-├── include/ark/         # Public core interfaces
-├── src/                 # Core runtime implementation
-├── plugins/             # Official plugins, one directory per plugin
-│   ├── kernel/
-│   ├── net/
-│   ├── bus/
-│   ├── http/
-│   ├── mysql/
-│   ├── redis/
-│   ├── lua/
-│   └── actor/
+├── include/ark/         # Public core and plugin interfaces
+├── src/
+│   ├── core/            # Header-only core target definitions
+│   ├── plugins/         # Official plugin implementations and CMake files
+│   │   ├── kernel/
+│   │   ├── net/
+│   │   ├── bus/
+│   │   ├── http/
+│   │   ├── mysql/
+│   │   └── redis/
+│   ├── app/
+│   ├── proto/
+│   └── server/
 ├── examples/            # Example applications and business plugins
 ├── tests/               # Core and cross-plugin integration tests
 ├── benchmarks/          # Standalone C++ benchmark programs
@@ -37,16 +39,17 @@ ark/
 └── docs/                # English/Chinese documentation and Nimbus site
 ```
 
-This shows the main directories. Existing Consul, etcd, Kafka and other official plugins follow the same convention.
+This shows the main directories. Existing Consul, etcd, Kafka and other official plugins follow the same convention. Lua and Actor integration remains planned; the table above identifies their proposed implementation directories.
 
 Each plugin follows the same package layout, for example:
 
 ```text
-plugins/mysql/
+include/ark/mysql/      # Public interfaces for plugin consumers
+src/plugins/mysql/
 ├── CMakeLists.txt
-├── include/ark/mysql/   # Public interfaces for plugin consumers
-├── src/                 # Plugin entry point, framework integration and private code
-└── tests/               # Plugin-specific tests
+├── detail/             # Private native database bridge
+└── *.cpp               # Plugin entry point and framework integration
+tests/database/         # Database integration and coroutine tests
 ```
 
 Usage documentation belongs in `docs/`, and example applications in `examples/`. Define public interfaces around capabilities; keep database client types within implementation code where possible.

docs/project/plugin-organization_CN.md

@@ -1,34 +1,36 @@
 # 官方插件与仓库组织
 
-工程目录已采用顶层平铺的 `plugins/<名称>/`，核心公开接口放在 `include/ark/`，实现放在 `src/`。核心与官方插件纳入 `ark`，业务插件放在应用仓库，`arknet` 保持独立。业务热更新的设计与实现暂缓，目录与 snake_case 整理已经落地，独立插件的功能整合仍按插件分别验收。
+核心与插件的公开接口统一放在 `include/ark/`，核心构建定义放在 `src/core/`，官方插件实现放在 `src/plugins/<名称>/`。核心与官方插件纳入 `ark`，业务插件放在应用仓库，`arknet` 保持独立。业务热更新的设计与实现暂缓，目录与 snake_case 整理已经落地，独立插件的功能整合仍按插件分别验收。
 
 ## 现有实现
 
 | 独立仓库 | ark 内的相关实现 | 建议合入位置 | 需要整理的内容 |
 | --- | --- | --- | --- |
-| [MySQLPlugin](https://github.com/OpenArkStudio/MySQLPlugin) | `plugins/mysql` | `plugins/mysql` | 由 arknet 自主实现 MySQL 客户端；插件整合配置、连接服务和业务回调 |
-| [RedisPlugin](https://github.com/OpenArkStudio/RedisPlugin) | `plugins/redis` | `plugins/redis` | 由 arknet 自主实现 Redis 客户端，再替换 aredis、bredis 的调用 |
-| [URLPlugin](https://github.com/OpenArkStudio/URLPlugin) | Net HTTP client 与 HTTP server 插件 | `plugins/http` | 对照 libcurl 版本的请求、编码与 actor 调用能力，统一 HTTP 服务接口 |
-| [LuaScriptPlugin](https://github.com/OpenArkStudio/LuaScriptPlugin) | 需要按新插件接口接入 | `plugins/lua` | 整理 Lua 绑定与脚本生命周期，移除对旧 NFComm 接口的依赖 |
-| [ActorPlugin](https://github.com/OpenArkStudio/ActorPlugin) | 需要按新插件接口接入 | `plugins/actor` | 明确任务调度、消息投递和业务线程的关系 |
+| [MySQLPlugin](https://github.com/OpenArkStudio/MySQLPlugin) | `src/plugins/mysql` | `src/plugins/mysql` | 由 arknet 自主实现 MySQL 客户端；插件整合配置、连接服务和业务回调 |
+| [RedisPlugin](https://github.com/OpenArkStudio/RedisPlugin) | `src/plugins/redis` | `src/plugins/redis` | 由 arknet 自主实现 Redis 客户端，再替换 aredis、bredis 的调用 |
+| [URLPlugin](https://github.com/OpenArkStudio/URLPlugin) | Net HTTP client 与 HTTP server 插件 | `src/plugins/http` | 对照 libcurl 版本的请求、编码与 actor 调用能力，统一 HTTP 服务接口 |
+| [LuaScriptPlugin](https://github.com/OpenArkStudio/LuaScriptPlugin) | 需要按新插件接口接入 | `src/plugins/lua` | 整理 Lua 绑定与脚本生命周期，移除对旧 NFComm 接口的依赖 |
+| [ActorPlugin](https://github.com/OpenArkStudio/ActorPlugin) | 需要按新插件接口接入 | `src/plugins/actor` | 明确任务调度、消息投递和业务线程的关系 |
 
 这些仓库仍保留不同代际的接口和构建方式。合入时逐项对照功能、重叠实现与依赖。MySQL、Redis 客户端归入 arknet，其他插件的依赖按各自需求讨论。
 
-## 目录建议
+## 目录布局
 
 ```text
 ark/
-├── include/ark/         # 核心公开接口
-├── src/                 # 核心运行时实现
-├── plugins/             # 官方插件，按名称平铺
-│   ├── kernel/
-│   ├── net/
-│   ├── bus/
-│   ├── http/
-│   ├── mysql/
-│   ├── redis/
-│   ├── lua/
-│   └── actor/
+├── include/ark/         # 核心与插件公开接口
+├── src/
+│   ├── core/            # header-only 核心 target 定义
+│   ├── plugins/         # 官方插件实现与 CMake 文件
+│   │   ├── kernel/
+│   │   ├── net/
+│   │   ├── bus/
+│   │   ├── http/
+│   │   ├── mysql/
+│   │   └── redis/
+│   ├── app/
+│   ├── proto/
+│   └── server/
 ├── examples/            # 示例应用与业务插件
 ├── tests/               # 核心与跨插件集成测试
 ├── benchmarks/          # 可独立编译运行的基准程序
@@ -37,16 +39,17 @@ ark/
 └── docs/                # 中英文文档与 Nimbus 站点
 ```
 
-上图列出主要目录。Consul、etcd、Kafka 等现有官方插件也按同一规则组织。
+上图列出主要目录。Consul、etcd、Kafka 等现有官方插件也按同一规则组织。Lua、Actor 的接入仍在规划中，上表列出的是它们的建议实现位置。
 
 每个插件采用相同的目录布局，以 MySQL 为例：
 
 ```text
-plugins/mysql/
+include/ark/mysql/      # 使用该插件时需要的公开接口
+src/plugins/mysql/
 ├── CMakeLists.txt
-├── include/ark/mysql/   # 使用该插件时需要的公开接口
-├── src/                 # 插件入口、框架接入与私有实现
-└── tests/               # 该插件的独立测试
+├── detail/             # 私有原生数据库桥接
+└── *.cpp               # 插件入口与框架接入
+tests/database/         # 数据库集成与协程测试
 ```
 
 插件使用说明放在 `docs/`，示例应用放在 `examples/`。公共接口按能力定义，数据库客户端类型尽量保留在实现内。