InterfaceLog Module Reference

接口输入/输出日志模块（STATIC 模块库）。 More...

Classes
struct	interface_log::ApiName
	接口名强类型。 语义：调用方必须显式构造 ApiName，避免把任意字符串误当接口名。 More...
struct	interface_log::LogText
	接口输入/输出文本强类型。 语义：与 ApiName 一样显式构造，参数顺序在编译期被类型约束。 More...

Enumerations
enum class	interface_log::ApiStatus { interface_log::ok , interface_log::failed }
	接口调用结果状态。 More...
enum class	interface_log::LogError { interface_log::invalid_path , interface_log::backend_unavailable }
	可恢复的日志初始化错误。 More...

Functions
std::expected< std::monostate, LogError >	interface_log::init (const std::filesystem::path &log_path="log/interface.log")
	初始化 bqlog TextFileAppender（可重复调用；路径变化会重建后端）。
std::size_t	interface_log::cleanup_old_logs (const std::filesystem::path &log_path, int months_back=3)
	删除超过保留期的接口日志与每日 trace 日志。
void	interface_log::set_enabled (bool enabled)
	启用/禁用接口记录（内存与文件同时生效）。
bool	interface_log::enabled ()
	当前是否启用接口记录。
void	interface_log::record (ApiName api, LogText input, LogText output, ApiStatus status)
	记录一次接口调用。
std::vector< std::string >	interface_log::recent ()
	取出最近 <= kMaxLines 条记录（最旧在前）。
std::size_t	interface_log::count ()
	当前环形缓冲条数（<= kMaxLines）。
void	interface_log::clear ()
	清空内存环形缓冲（不动 bqlog 文件）。
std::filesystem::path	interface_log::log_path ()
	当前配置的日志路径。
template<std::invocable< std::string_view > Visitor>
void	interface_log::for_each_recent (Visitor &&visitor)
	在锁内逐条访问环形缓冲（函数对象设计）。
std::string_view	interface_log::status_name (ApiStatus status) noexcept
	状态枚举到可读名称（供日志/测试使用）。
std::string_view	interface_log::log_error_message (LogError error) noexcept
	LogError 到可读消息（供 CLI / 测试使用）。

Variables
constexpr std::size_t	interface_log::kMaxLines = 1000
	环形缓冲最大记录条数（= 1000）。
constexpr std::string_view	interface_log::kDeveloperWebsite = "https://suchaharcan.github.io/"
	开发者网站水印；每次初始化 bqlog 与 CLI 调用日志都会写出。

Detailed Description

接口输入/输出日志模块（STATIC 模块库）。

设计依据（详见模板 README 的参考资料）：

• 类型即注释：接口名、输入/输出文本都使用强类型（ApiName / LogText）， 避免把多个 std::string 混在一张参数表里传错顺序。
• 错误分类：可恢复错误（后端不可用、路径非法）用 std::expected 返回， 不抛异常；内存环形记录始终可用，作为 bqlog 后端的降级缓冲。
• 函数对象设计：for_each_recent 接受任意可调用对象（模板参数）， 不引入 std::function 的类型擦除开销。
• 无 UB：所有共享状态由 std::mutex 保护；环形队列只在锁内访问。

日志分工：

• bqlog（C++ 模块 import bq.log）：TextFileAppender 落盘，max_file_size 限制文件大小；
• 内存环形缓冲：最多保留 kMaxLines = 1000 条，超出淘汰最旧记录。

Files
file	/Users/runner/work/CXX-CMake-template/CXX-CMake-template/single-exe-static-modules/modules/interface_log/include/InterfaceLog.cppm