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

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

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

Variables
constexpr std::size_t	kMaxLines = 1000
	环形缓冲最大记录条数（= 1000）。
constexpr std::string_view	kDeveloperWebsite = "https://suchaharcan.github.io/"
	开发者网站水印；每次初始化 bqlog 与 CLI 调用日志都会写出。
std::mutex	g_mutex
	保护下列全部可变状态。
std::deque< std::string >	g_lines
	最近调用记录；队首最旧。
std::optional< bq::log >	g_logger
	可选 bqlog 文件后端。
std::filesystem::path	g_log_path
	当前后端日志基准路径。
bool	g_initialized = false
	bqlog 是否已成功初始化。
bool	g_recording_enabled = true
	Alfred 配置控制的全局日志开关。

Enumeration Type Documentation

◆ ApiStatus

enum class interface_log::ApiStatus

exportstrong

接口调用结果状态。

Enumerator
ok	调用成功
failed	调用失败（错误已记录在 output 文本中）

Definition at line 35 of file InterfaceLog.cppm.

◆ LogError

enum class interface_log::LogError

exportstrong

可恢复的日志初始化错误。

Enumerator
invalid_path	日志路径为空
backend_unavailable	bqlog 后端初始化失败（环形缓冲仍可用）

Definition at line 41 of file InterfaceLog.cppm.

Function Documentation

◆ cleanup_old_logs()

std::size_t interface_log::cleanup_old_logs	(	const std::filesystem::path &	log_path,
		int	months_back = 3 )

export

删除超过保留期的接口日志与每日 trace 日志。

Parameters

log_path	当前接口日志基准路径（通常为 log/interface.log）
months_back	保留月数，默认 3

Returns: 被删除的文件数量

Definition at line 202 of file InterfaceLog.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ clear()

void interface_log::clear ( )

export

清空内存环形缓冲（不动 bqlog 文件）。

Definition at line 303 of file InterfaceLog.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ count()

std::size_t interface_log::count ( )

export

当前环形缓冲条数（<= kMaxLines）。

Definition at line 298 of file InterfaceLog.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ enabled()

bool interface_log::enabled ( )

export

当前是否启用接口记录。

Definition at line 288 of file InterfaceLog.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ for_each_recent()

template<std::invocable< std::string_view > Visitor>

void interface_log::for_each_recent ( Visitor && visitor )

export

在锁内逐条访问环形缓冲（函数对象设计）。

Parameters

visitor 满足 std::invocable<std::string_view> 的可调用对象

Note: 模板参数避免 std::function 的类型擦除开销；visitor 抛出异常会向上传播。

Definition at line 314 of file InterfaceLog.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ init()

std::expected< std::monostate, LogError > interface_log::init ( const std::filesystem::path & log_path = "log/interface.log" )

export

初始化 bqlog TextFileAppender（可重复调用；路径变化会重建后端）。

Parameters

log_path 文本日志路径，默认 log/interface.log

Returns: 成功为 std::monostate；失败返回 LogError（环形缓冲不受影响）

Note: 调用 create_log 前会先创建父目录；日志文件由 BqLog 附加日期序号。

Definition at line 155 of file InterfaceLog.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ log_error_message()

std::string_view interface_log::log_error_message ( LogError error )

exportnoexcept

LogError 到可读消息（供 CLI / 测试使用）。

Definition at line 332 of file InterfaceLog.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ log_path()

std::filesystem::path interface_log::log_path ( )

export

当前配置的日志路径。

Definition at line 308 of file InterfaceLog.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ now_string()

std::string interface_log::now_string ( )

当前时间字符串（本地时间，秒级精度）。

Note: 使用 C++20 chrono + format，避免依赖平台 localtime。

Definition at line 147 of file InterfaceLog.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ recent()

std::vector< std::string > interface_log::recent ( )

export

取出最近 <= kMaxLines 条记录（最旧在前）。

Returns: 快照副本，调用方无需持锁

Definition at line 293 of file InterfaceLog.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ record()

void interface_log::record	(	ApiName	api,
		LogText	input,
		LogText	output,
		ApiStatus	status )

export

记录一次接口调用。

Parameters

api	接口名（强类型）
input	输入摘要
output	输出摘要（失败时为错误信息）
status	调用状态

Postcondition: 环形缓冲 <= kMaxLines；bqlog 文件追加一行（后端可用时）

Note: 线程安全；耗时操作（force_flush）在锁内执行，调用方勿在高频路径使用。

Definition at line 257 of file InterfaceLog.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ set_enabled()

void interface_log::set_enabled ( bool enabled )

export

启用/禁用接口记录（内存与文件同时生效）。

Definition at line 282 of file InterfaceLog.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ status_name()

std::string_view interface_log::status_name ( ApiStatus status )

exportnoexcept

状态枚举到可读名称（供日志/测试使用）。

Definition at line 321 of file InterfaceLog.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

◆ g_initialized

bool interface_log::g_initialized = false

bqlog 是否已成功初始化。

Definition at line 140 of file InterfaceLog.cppm.

◆ g_lines

std::deque<std::string> interface_log::g_lines

最近调用记录；队首最旧。

Definition at line 137 of file InterfaceLog.cppm.

◆ g_log_path

std::filesystem::path interface_log::g_log_path

当前后端日志基准路径。

Definition at line 139 of file InterfaceLog.cppm.

◆ g_logger

std::optional<bq::log> interface_log::g_logger

可选 bqlog 文件后端。

Definition at line 138 of file InterfaceLog.cppm.

◆ g_mutex

std::mutex interface_log::g_mutex

保护下列全部可变状态。

Definition at line 136 of file InterfaceLog.cppm.

◆ g_recording_enabled

bool interface_log::g_recording_enabled = true

Alfred 配置控制的全局日志开关。

Definition at line 141 of file InterfaceLog.cppm.

◆ kDeveloperWebsite

std::string_view interface_log::kDeveloperWebsite = "https://suchaharcan.github.io/"

inlineconstexprexport

开发者网站水印；每次初始化 bqlog 与 CLI 调用日志都会写出。

Definition at line 32 of file InterfaceLog.cppm.

◆ kMaxLines

std::size_t interface_log::kMaxLines = 1000

inlineconstexprexport

环形缓冲最大记录条数（= 1000）。

Definition at line 29 of file InterfaceLog.cppm.

Classes

Enumerations

Functions

Variables

Enumeration Type Documentation

◆ ApiStatus

◆ LogError

Function Documentation

◆ cleanup_old_logs()

◆ clear()

◆ count()

◆ enabled()

◆ for_each_recent()

◆ init()

◆ log_error_message()

◆ log_path()

◆ now_string()

◆ recent()

◆ record()

◆ set_enabled()

◆ status_name()

Variable Documentation

◆ g_initialized

◆ g_lines

◆ g_log_path

◆ g_logger

◆ g_mutex

◆ g_recording_enabled

◆ kDeveloperWebsite

◆ kMaxLines