Stacks 2 任务业务模块。 More...

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

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

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

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

Detailed Description

Stacks 2 任务业务模块。

职责边界：

创建看板任务与全局收件箱任务；
查询项目、Stack 和任务；
修改标题/描述、开始日期、截止日期；
完成/重新打开、归档、可恢复删除；
在本周截止范围内聚合所有已保存工作区；
启动/停止计时并写入 Stacks 2 兼容的 timelogs。

所有写操作都通过同目录临时文件 + rename(2) 原子替换。需要同时更新 .task 和 .project 的创建操作带失败回滚；删除操作移动到 tasks/.trash。

实现边界：

所有公开 API 接收强类型 ID、标题和描述，错误通过 std::expected 返回；
写入前统一取得 .stacks-tools.lock，避免 Alfred 与 CLI 并发破坏 JSON；
任务文件中 Stacks 原生字段保持原名（startdate/duedate/completed/timelogs）；
插件私有运行状态只写入 Timers.json，不污染 Stacks 工作区；
读取路径尽量容错，写入路径失败时明确返回 TaskError，不静默吞掉业务错误。

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

Classes

Enumerations

Functions

Variables

Detailed Description

Files