Classes
struct	ProjectNode
	Project.json 节点的内部视图，不进入公开 API。 More...
struct	TaskLocation
	任务在项目/清单层级中的成员关系缓存。 More...
struct	LoadedTask
	原始 JSON 与展示快照一起返回，编辑时可保留未知 Stacks 字段。 More...
class	ScopedFileLock
	进程内排他写锁；析构时自动 flock unlock + close。 More...

Typedefs
using	json = nlohmann::json

Functions
std::string	trim (std::string value)
	去除首尾 ASCII 空白，保留标题/描述内部内容。
std::string	lower_ascii (std::string value)
	仅做 ASCII 小写化，足够处理命令别名、优先级和任务搜索。
bool	valid_identifier (std::string_view value)
	校验 Stacks ID 的跨 Alfred token 安全字符集。
std::string	local_timestamp ()
	本地秒级时间，用于 Stacks UI 可读的 updated/completed/archived 字段。
std::string	utc_timestamp ()
	UTC 微秒时间，用于 task.created/updated 的 ISO 兼容格式。
std::string	local_date ()
	从本地时间戳提取 YYYY-MM-DD；转换失败时返回空串。
fs::path	normalized_path (const fs::path &value)
	规范化绝对路径；不要求目标路径已存在，适配首次创建工作区目录。
std::expected< json, TaskError >	load_json (const fs::path &file, TaskManager::TaskError parse_error)
	防御性读取 JSON 文件。
bool	atomic_write_json (const fs::path &target, const json &value)
	以同目录临时文件 + rename 原子替换 JSON。
std::string	string_value (const json &object, std::string_view key, std::string fallback={})
	只在目标字段为字符串时返回值，避免 nlohmann 类型异常穿透 API。
int	int_value (const json &object, std::string_view key, int fallback=0)
	只在目标字段为整数时返回值；浮点和字符串一律回退。
bool	bool_value (const json &object, std::string_view key, bool fallback=false)
	只在目标字段为布尔值时返回值。
void	erase_json_id (json &array, std::string_view task_id)
	从 JSON 字符串数组中移除指定任务 ID，保留其他元素顺序。
std::optional< std::chrono::year_month_day >	parse_iso_date (std::string_view value)
	严格解析 YYYY-MM-DD，并借助 year_month_day::ok 拒绝 2 月 30 日等非法日期。
std::string	format_date (std::chrono::year_month_day date)
	将日历日期格式化为 Alfred/Stacks 共用的 ISO 文本。
std::string	effective_anchor (const std::optional< std::string > &anchor)
	优先使用显式锚点；锚点非法或缺失时回退到当前本地日期。
std::optional< std::string >	normalize_priority_value (std::string_view value)
	将用户优先级表达式归一化为 Stacks 值。
std::expected< std::vector< ProjectNode >, TaskError >	load_projects (const DatabasePaths &paths)
	读取 Project.json，过滤无效/重复节点并恢复项目到工作区的归属。
std::expected< std::set< fs::path >, TaskError >	load_libraries (const DatabasePaths &paths)
	合并 library_paths 与项目节点推导出的工作区，确保旧索引也能扫描任务。
std::expected< std::vector< BoardTarget >, TaskError >	load_boards_impl (const DatabasePaths &paths)
	从项目文件恢复项目和清单的扁平看板列表。
std::expected< BoardTarget, TaskError >	resolve_board (std::string_view id, const DatabasePaths &paths)
	在扁平看板列表中解析项目/清单目标，供创建任务定位 .project 文件。
std::expected< std::unordered_map< std::string, TaskLocation >, TaskError >	load_memberships (const DatabasePaths &paths)
	建立“任务 ID → 项目/清单位置”缓存。
std::expected< LoadedTask, TaskError >	load_task_from_file (const fs::path &file, const std::filesystem::path &library_path, const std::unordered_map< std::string, TaskLocation > &memberships)
	读取单个 .task：保留未知字段，并把 Stacks 原生字段映射为 TaskRecord。
std::expected< std::vector< TaskRecord >, TaskError >	scan_tasks (const DatabasePaths &paths)
	扫描所有已保存工作区的 tasks 目录，跳过重复文件与损坏任务。
std::expected< LoadedTask, TaskError >	find_task_raw (TaskId task_id, const DatabasePaths &paths)
	通过任务 ID 在所有工作区中查找原始 JSON，避免依赖全局唯一路径索引。
std::expected< TaskRecord, TaskError >	save_task (TaskId task_id, json &raw, const DatabasePaths &paths)
	原子写回编辑后的任务，并重新读取规范化快照。
bool	task_matches_query (const TaskRecord &task, std::string_view query)
	对标题、描述、ID、项目名和清单名执行不区分大小写的子串匹配。

Variables
std::atomic< std::uint64_t >	g_sequence {0}
	进程内原子序号，与时间/随机设备一起构成 ID 种子的去重分量。

Typedef Documentation

◆ json

using TaskManager::anonymous_namespace{TaskManager.cppm}::json = nlohmann::json

Definition at line 344 of file TaskManager.cppm.

Function Documentation

◆ atomic_write_json()

bool TaskManager::anonymous_namespace{TaskManager.cppm}::atomic_write_json	(	const fs::path &	target,
		const json &	value )

以同目录临时文件 + rename 原子替换 JSON。

Returns: 创建目录、写入、flush 或 rename 任一步失败均返回 false。

Definition at line 503 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ bool_value()

bool TaskManager::anonymous_namespace{TaskManager.cppm}::bool_value	(	const json &	object,
		std::string_view	key,
		bool	fallback = false )

只在目标字段为布尔值时返回值。

Definition at line 550 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ effective_anchor()

std::string TaskManager::anonymous_namespace{TaskManager.cppm}::effective_anchor ( const std::optional< std::string > & anchor )

优先使用显式锚点；锚点非法或缺失时回退到当前本地日期。

Definition at line 616 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ erase_json_id()

void TaskManager::anonymous_namespace{TaskManager.cppm}::erase_json_id	(	json &	array,
		std::string_view	task_id )

从 JSON 字符串数组中移除指定任务 ID，保留其他元素顺序。

Definition at line 558 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ find_task_raw()

std::expected< LoadedTask, TaskError > TaskManager::anonymous_namespace{TaskManager.cppm}::find_task_raw	(	TaskId	task_id,
		const DatabasePaths &	paths )

通过任务 ID 在所有工作区中查找原始 JSON，避免依赖全局唯一路径索引。

Definition at line 931 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ format_date()

std::string TaskManager::anonymous_namespace{TaskManager.cppm}::format_date ( std::chrono::year_month_day date )

将日历日期格式化为 Alfred/Stacks 共用的 ISO 文本。

Definition at line 610 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ int_value()

int TaskManager::anonymous_namespace{TaskManager.cppm}::int_value	(	const json &	object,
		std::string_view	key,
		int	fallback = 0 )

只在目标字段为整数时返回值；浮点和字符串一律回退。

Definition at line 542 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ load_boards_impl()

std::expected< std::vector< BoardTarget >, TaskError > TaskManager::anonymous_namespace{TaskManager.cppm}::load_boards_impl ( const DatabasePaths & paths )

从项目文件恢复项目和清单的扁平看板列表。

Note: 排序键为项目标题 → 项目节点优先 → 清单标题，保证 Alfred 顺序稳定。

Definition at line 722 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ load_json()

std::expected< json, TaskError > TaskManager::anonymous_namespace{TaskManager.cppm}::load_json	(	const fs::path &	file,
		TaskManager::TaskError	parse_error )

防御性读取 JSON 文件。

Parameters

file	源文件。
parse_error	打开、读取或解析失败时返回的业务错误。

Definition at line 486 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ load_libraries()

std::expected< std::set< fs::path >, TaskError > TaskManager::anonymous_namespace{TaskManager.cppm}::load_libraries ( const DatabasePaths & paths )

合并 library_paths 与项目节点推导出的工作区，确保旧索引也能扫描任务。

Definition at line 693 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ load_memberships()

std::expected< std::unordered_map< std::string, TaskLocation >, TaskError > TaskManager::anonymous_namespace{TaskManager.cppm}::load_memberships ( const DatabasePaths & paths )

建立“任务 ID → 项目/清单位置”缓存。

Note: backlog 任务与 Stack 任务都进入同一映射；重复 ID 保留首次位置。

Definition at line 800 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ load_projects()

std::expected< std::vector< ProjectNode >, TaskError > TaskManager::anonymous_namespace{TaskManager.cppm}::load_projects ( const DatabasePaths & paths )

读取 Project.json，过滤无效/重复节点并恢复项目到工作区的归属。

Definition at line 654 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ load_task_from_file()

std::expected< LoadedTask, TaskError > TaskManager::anonymous_namespace{TaskManager.cppm}::load_task_from_file	(	const fs::path &	file,
		const std::filesystem::path &	library_path,
		const std::unordered_map< std::string, TaskLocation > &	memberships )

读取单个 .task：保留未知字段，并把 Stacks 原生字段映射为 TaskRecord。

Definition at line 845 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ local_date()

std::string TaskManager::anonymous_namespace{TaskManager.cppm}::local_date ( )

从本地时间戳提取 YYYY-MM-DD；转换失败时返回空串。

Definition at line 466 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ local_timestamp()

std::string TaskManager::anonymous_namespace{TaskManager.cppm}::local_timestamp ( )

本地秒级时间，用于 Stacks UI 可读的 updated/completed/archived 字段。

Definition at line 434 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ lower_ascii()

std::string TaskManager::anonymous_namespace{TaskManager.cppm}::lower_ascii ( std::string value )

仅做 ASCII 小写化，足够处理命令别名、优先级和任务搜索。

Definition at line 418 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ normalize_priority_value()

std::optional< std::string > TaskManager::anonymous_namespace{TaskManager.cppm}::normalize_priority_value ( std::string_view value )

将用户优先级表达式归一化为 Stacks 值。

Returns: 空字符串表示清除；nullopt 表示未知输入。

Definition at line 630 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ normalized_path()

fs::path TaskManager::anonymous_namespace{TaskManager.cppm}::normalized_path ( const fs::path & value )

规范化绝对路径；不要求目标路径已存在，适配首次创建工作区目录。

Definition at line 472 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ parse_iso_date()

std::optional< std::chrono::year_month_day > TaskManager::anonymous_namespace{TaskManager.cppm}::parse_iso_date ( std::string_view value )

严格解析 YYYY-MM-DD，并借助 year_month_day::ok 拒绝 2 月 30 日等非法日期。

Definition at line 571 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ resolve_board()

std::expected< BoardTarget, TaskError > TaskManager::anonymous_namespace{TaskManager.cppm}::resolve_board	(	std::string_view	id,
		const DatabasePaths &	paths )

在扁平看板列表中解析项目/清单目标，供创建任务定位 .project 文件。

Definition at line 781 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ save_task()

std::expected< TaskRecord, TaskError > TaskManager::anonymous_namespace{TaskManager.cppm}::save_task	(	TaskId	task_id,
		json &	raw,
		const DatabasePaths &	paths )

原子写回编辑后的任务，并重新读取规范化快照。

Note: 时间戳在写前统一刷新；失败不会返回半更新的 TaskRecord。

Definition at line 958 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ scan_tasks()

std::expected< std::vector< TaskRecord >, TaskError > TaskManager::anonymous_namespace{TaskManager.cppm}::scan_tasks ( const DatabasePaths & paths )

扫描所有已保存工作区的 tasks 目录，跳过重复文件与损坏任务。

Definition at line 892 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ string_value()

std::string TaskManager::anonymous_namespace{TaskManager.cppm}::string_value	(	const json &	object,
		std::string_view	key,
		std::string	fallback = {} )

只在目标字段为字符串时返回值，避免 nlohmann 类型异常穿透 API。

Definition at line 534 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ task_matches_query()

bool TaskManager::anonymous_namespace{TaskManager.cppm}::task_matches_query	(	const TaskRecord &	task,
		std::string_view	query )

对标题、描述、ID、项目名和清单名执行不区分大小写的子串匹配。

Definition at line 980 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ trim()

std::string TaskManager::anonymous_namespace{TaskManager.cppm}::trim ( std::string value )

去除首尾 ASCII 空白，保留标题/描述内部内容。

Definition at line 410 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ utc_timestamp()

std::string TaskManager::anonymous_namespace{TaskManager.cppm}::utc_timestamp ( )

UTC 微秒时间，用于 task.created/updated 的 ISO 兼容格式。

Definition at line 448 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ valid_identifier()

bool TaskManager::anonymous_namespace{TaskManager.cppm}::valid_identifier ( std::string_view value )

校验 Stacks ID 的跨 Alfred token 安全字符集。

Definition at line 426 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

◆ g_sequence

std::atomic<std::uint64_t> TaskManager::anonymous_namespace{TaskManager.cppm}::g_sequence {0}

进程内原子序号，与时间/随机设备一起构成 ID 种子的去重分量。

Definition at line 407 of file TaskManager.cppm.

Classes

Typedefs

Functions

Variables

Typedef Documentation

◆ json

Function Documentation

◆ atomic_write_json()

◆ bool_value()

◆ effective_anchor()

◆ erase_json_id()

◆ find_task_raw()

◆ format_date()

◆ int_value()

◆ load_boards_impl()

◆ load_json()

◆ load_libraries()

◆ load_memberships()

◆ load_projects()

◆ load_task_from_file()

◆ local_date()

◆ local_timestamp()

◆ lower_ascii()

◆ normalize_priority_value()

◆ normalized_path()

◆ parse_iso_date()

◆ resolve_board()

◆ save_task()

◆ scan_tasks()

◆ string_value()

◆ task_matches_query()

◆ trim()

◆ utc_timestamp()

◆ valid_identifier()

Variable Documentation

◆ g_sequence