Namespaces
namespace	anonymous_namespace{TaskManager.cppm}

Classes
struct	TargetId
	可创建任务的看板目标 ID。 More...
struct	TaskId
	已校验任务 ID；作为所有任务读写接口的稳定主键。 More...
struct	TaskTitle
	任务标题；create/update 时仍会执行 trim 与空值校验。 More...
struct	TaskDescription
	任务描述；允许空字符串，不改写 Markdown/HTML 内容。 More...
struct	DatabasePaths
	三个运行数据库路径；一次传参避免同类 path 参数顺序错误。 More...
struct	CreateTaskOptions
	创建任务所需的数据库与 Inbox 默认工作区。 More...
struct	TaskInput
	创建任务输入；日期保留用户文本，由 normalize_date 在业务层校验。 More...
struct	TaskPatch
	部分更新任务；optional 表示“未提供”，clear_* 表示“显式清空”。 More...
struct	TaskListOptions
	任务列表的过滤条件；默认保留已完成任务、排除已归档任务。 More...
struct	BoardTarget
	项目或清单的统一展示目标；WorkflowUI 用它构造 Alfred 条目。 More...
struct	TaskRecord
	跨模块使用的任务只读快照；字段名对应 Stacks 文件与 UI 展示语义。 More...
struct	TaskResult
	创建任务的稳定结果，不返回可被后续修改的内部 JSON。 More...
struct	TimerRecord
	Timers.json 中的运行中计时快照。 More...
struct	StopTimerResult
	停止计时结果；timelog_id 可在任务文件中定位新记录。 More...
struct	DeleteResult
	可恢复删除结果；trash_file 指向 tasks/.trash 中的副本。 More...
struct	WeekBounds
	周一至周日的 ISO 日期区间。 More...

Enumerations
enum class	TaskError { invalid_target_id , invalid_task_id , empty_title , invalid_date , invalid_date_range , invalid_priority , project_db_unreadable , stack_db_unreadable , target_not_found , target_kind_unknown , project_file_not_found , project_file_unreadable , task_not_found , task_file_unreadable , timer_not_running , timer_already_running , timer_db_unreadable , no_inbox_library , invalid_library_path , lock_failure , write_failure , delete_failure }
	任务业务的可恢复错误分类；UI 只消费 task_error_message。 More...

Functions
TaskId	generate_id ()
	生成线程安全的 20 字符任务 ID。
std::expected< TaskResult, TaskError >	create_task (TargetId target_id, TaskInput input, const CreateTaskOptions &options)
	在项目或清单下创建任务，并回滚“任务已写、项目未写”的半成功状态。
std::expected< TaskResult, TaskError >	create_inbox_task (TaskInput input, const CreateTaskOptions &options)
	在指定/默认工作区创建 Stacks project=inbox 任务。
std::expected< std::vector< BoardTarget >, TaskError >	list_boards (const DatabasePaths &paths)
	按项目名排序加载项目与清单的扁平列表。
std::expected< std::vector< TaskRecord >, TaskError >	list_tasks (const DatabasePaths &paths, const TaskListOptions &options={})
	扫描所有工作区任务并按目标、完成状态、归档状态和关键词过滤。
std::expected< std::vector< TaskRecord >, TaskError >	list_week_due (const DatabasePaths &paths, std::optional< std::string > anchor_date=std::nullopt)
	返回指定自然周内未完成、未归档且有截止日期的任务。
std::expected< TaskRecord, TaskError >	get_task (TaskId task_id, const DatabasePaths &paths)
	以任务 ID 在工作区索引中定位并读取任务快照。
std::expected< TaskRecord, TaskError >	update_task (TaskId task_id, const TaskPatch &patch, const DatabasePaths &paths)
	应用部分更新；修改前后都会验证日期区间与优先级。
std::expected< TaskRecord, TaskError >	set_due_date (TaskId task_id, std::string due_date, const DatabasePaths &paths)
	仅更新截止日期；内部复用 update_task。
std::expected< TaskRecord, TaskError >	set_start_date (TaskId task_id, std::string start_date, const DatabasePaths &paths)
	仅更新开始日期；内部复用 update_task。
std::expected< TaskRecord, TaskError >	set_schedule (TaskId task_id, std::string start_date, std::string due_date, const DatabasePaths &paths)
	同时更新开始与截止日期，并校验区间顺序。
std::expected< TaskRecord, TaskError >	set_task_done (TaskId task_id, bool done, const DatabasePaths &paths)
	写入 Stacks 完成字段或清空完成状态。
std::expected< TaskRecord, TaskError >	archive_task (TaskId task_id, const DatabasePaths &paths)
	写入 archived 时间，保留任务文件供后续恢复。
std::expected< DeleteResult, TaskError >	delete_task (TaskId task_id, const DatabasePaths &paths)
	从所有项目引用移除任务，并把 .task 移入可恢复 .trash。
std::expected< TimerRecord, TaskError >	start_timer (TaskId task_id, const DatabasePaths &paths)
	在 Timers.json 中登记运行中计时；重复启动返回分类错误。
std::expected< StopTimerResult, TaskError >	stop_timer (TaskId task_id, const DatabasePaths &paths)
	停止计时、写 Stacks timelog，并在第二步失败时回滚任务文件。
std::expected< std::vector< TimerRecord >, TaskError >	list_timers (const DatabasePaths &paths)
	列出 Timers.json 中的运行中计时快照。
std::expected< std::string, TaskError >	normalize_date (std::string_view value, std::optional< std::string > anchor_date=std::nullopt)
	将 YYYY-MM-DD、today、tomorrow、+Nd 或英文星期解析为 ISO 日期。
WeekBounds	week_bounds (std::optional< std::string > anchor_date=std::nullopt)
	计算锚点日期所在周的周一/周日边界。
std::string_view	task_error_message (TaskError error) noexcept
	将 TaskError 映射为稳定的 CLI/Alfred 文本。
template<std::invocable< std::string_view > Visitor>
std::expected< std::size_t, TaskError >	for_each_backlog_id (const std::filesystem::path &project_file, Visitor &&visitor)
	以函数对象遍历项目 backlog ID。

Variables
constexpr std::size_t	kTaskIdLength = 20
	任务 ID 固定为 20 字符，变异测试会硬编码检查此协议。

Enumeration Type Documentation

◆ TaskError

enum class TaskManager::TaskError

exportstrong

任务业务的可恢复错误分类；UI 只消费 task_error_message。

Enumerator
invalid_target_id	项目/清单 ID 含非法字符或为空。
invalid_task_id	任务 ID 格式非法。
empty_title	trim 后标题为空。
invalid_date	日期表达式或日历日期非法。
invalid_date_range	开始日期晚于截止日期。
invalid_priority	未识别优先级文本。
project_db_unreadable	Project.json 无法解析。
stack_db_unreadable	Stack.json 无法解析。
target_not_found	索引中无目标看板。
target_kind_unknown	目标类型不是 project/stack。
project_file_not_found	.project 路径不存在。
project_file_unreadable	.project 无法解析。
task_not_found	全部工作区中无此任务。
task_file_unreadable	.task 无法解析。
timer_not_running	目标任务未在计时。
timer_already_running	目标任务已有计时。
timer_db_unreadable	Timers.json 无法解析。
no_inbox_library	没有可用于 Inbox 的工作区。
invalid_library_path	指定工作区不存在或不是目录。
lock_failure	另一个进程持写锁。
write_failure	写任务/索引文件失败。
delete_failure	项目引用回滚或移入垃圾箱失败。

Definition at line 204 of file TaskManager.cppm.

Function Documentation

◆ archive_task()

std::expected< TaskRecord, TaskError > TaskManager::archive_task	(	TaskId	task_id,
		const DatabasePaths &	paths )

export

写入 archived 时间，保留任务文件供后续恢复。

Definition at line 1547 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ create_inbox_task()

std::expected< TaskResult, TaskError > TaskManager::create_inbox_task	(	TaskInput	input,
		const CreateTaskOptions &	options )

export

在指定/默认工作区创建 Stacks project=inbox 任务。

Definition at line 1172 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ create_task()

std::expected< TaskResult, TaskError > TaskManager::create_task	(	TargetId	target_id,
		TaskInput	input,
		const CreateTaskOptions &	options )

export

在项目或清单下创建任务，并回滚“任务已写、项目未写”的半成功状态。

Definition at line 1027 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ delete_task()

std::expected< DeleteResult, TaskError > TaskManager::delete_task	(	TaskId	task_id,
		const DatabasePaths &	paths )

export

从所有项目引用移除任务，并把 .task 移入可恢复 .trash。

Definition at line 1570 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ for_each_backlog_id()

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

std::expected< std::size_t, TaskError > TaskManager::for_each_backlog_id	(	const std::filesystem::path &	project_file,
		Visitor &&	visitor )

export

以函数对象遍历项目 backlog ID。

Returns: 成功返回字符串 ID 数量；文件损坏返回分类错误。

Note: backlog 缺失/非数组视为空列表，不隐式修改源文件。

Definition at line 313 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ generate_id()

TaskId TaskManager::generate_id ( )

export

生成线程安全的 20 字符任务 ID。

Definition at line 994 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_task()

std::expected< TaskRecord, TaskError > TaskManager::get_task	(	TaskId	task_id,
		const DatabasePaths &	paths )

export

以任务 ID 在工作区索引中定位并读取任务快照。

Definition at line 1388 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ list_boards()

std::expected< std::vector< BoardTarget >, TaskError > TaskManager::list_boards ( const DatabasePaths & paths )

export

按项目名排序加载项目与清单的扁平列表。

Definition at line 1279 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ list_tasks()

std::expected< std::vector< TaskRecord >, TaskError > TaskManager::list_tasks	(	const DatabasePaths &	paths,
		const TaskListOptions &	options = {} )

export

扫描所有工作区任务并按目标、完成状态、归档状态和关键词过滤。

Definition at line 1291 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ list_timers()

std::expected< std::vector< TimerRecord >, TaskError > TaskManager::list_timers ( const DatabasePaths & paths )

export

列出 Timers.json 中的运行中计时快照。

Definition at line 1816 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ list_week_due()

std::expected< std::vector< TaskRecord >, TaskError > TaskManager::list_week_due	(	const DatabasePaths &	paths,
		std::optional< std::string >	anchor_date = std::nullopt )

export

返回指定自然周内未完成、未归档且有截止日期的任务。

Definition at line 1364 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ normalize_date()

std::expected< std::string, TaskError > TaskManager::normalize_date	(	std::string_view	value,
		std::optional< std::string >	anchor_date = std::nullopt )

export

将 YYYY-MM-DD、today、tomorrow、+Nd 或英文星期解析为 ISO 日期。

Definition at line 1850 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ set_due_date()

std::expected< TaskRecord, TaskError > TaskManager::set_due_date	(	TaskId	task_id,
		std::string	due_date,
		const DatabasePaths &	paths )

export

仅更新截止日期；内部复用 update_task。

Definition at line 1484 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ set_schedule()

std::expected< TaskRecord, TaskError > TaskManager::set_schedule	(	TaskId	task_id,
		std::string	start_date,
		std::string	due_date,
		const DatabasePaths &	paths )

export

同时更新开始与截止日期，并校验区间顺序。

Definition at line 1500 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ set_start_date()

std::expected< TaskRecord, TaskError > TaskManager::set_start_date	(	TaskId	task_id,
		std::string	start_date,
		const DatabasePaths &	paths )

export

仅更新开始日期；内部复用 update_task。

Definition at line 1492 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ set_task_done()

std::expected< TaskRecord, TaskError > TaskManager::set_task_done	(	TaskId	task_id,
		bool	done,
		const DatabasePaths &	paths )

export

写入 Stacks 完成字段或清空完成状态。

Definition at line 1510 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ start_timer()

std::expected< TimerRecord, TaskError > TaskManager::start_timer	(	TaskId	task_id,
		const DatabasePaths &	paths )

export

在 Timers.json 中登记运行中计时；重复启动返回分类错误。

Definition at line 1671 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ stop_timer()

std::expected< StopTimerResult, TaskError > TaskManager::stop_timer	(	TaskId	task_id,
		const DatabasePaths &	paths )

export

停止计时、写 Stacks timelog，并在第二步失败时回滚任务文件。

Definition at line 1730 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ task_error_message()

std::string_view TaskManager::task_error_message ( TaskError error )

exportnoexcept

将 TaskError 映射为稳定的 CLI/Alfred 文本。

Definition at line 1925 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ update_task()

std::expected< TaskRecord, TaskError > TaskManager::update_task	(	TaskId	task_id,
		const TaskPatch &	patch,
		const DatabasePaths &	paths )

export

应用部分更新；修改前后都会验证日期区间与优先级。

Definition at line 1403 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ week_bounds()

WeekBounds TaskManager::week_bounds ( std::optional< std::string > anchor_date = std::nullopt )

export

计算锚点日期所在周的周一/周日边界。

Definition at line 1908 of file TaskManager.cppm.

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

◆ kTaskIdLength

std::size_t TaskManager::kTaskIdLength = 20

inlineconstexprexport

任务 ID 固定为 20 字符，变异测试会硬编码检查此协议。

Definition at line 60 of file TaskManager.cppm.

Namespaces

Classes

Enumerations

Functions

Variables

Enumeration Type Documentation

◆ TaskError

Function Documentation

◆ archive_task()

◆ create_inbox_task()

◆ create_task()

◆ delete_task()

◆ for_each_backlog_id()

◆ generate_id()

◆ get_task()

◆ list_boards()

◆ list_tasks()

◆ list_timers()

◆ list_week_due()

◆ normalize_date()

◆ set_due_date()

◆ set_schedule()

◆ set_start_date()

◆ set_task_done()

◆ start_timer()

◆ stop_timer()

◆ task_error_message()

◆ update_task()

◆ week_bounds()

Variable Documentation

◆ kTaskIdLength