# REQUIREMENTS

## 0. 技能标识

- 拟定 slug（英文，符合 `development/NAMING.md`）：add-todo-all
- 中文 name：待办事项
- 中文 description（一句话）：提供待办事项的创建、查看、标记完成、删除、批量操作能力；支持设置截止时间与优先级；数据持久化在本地 SQLite。
- account-manager platform_key（如有）：无（纯本地数据技能，不涉及外部账号登录）
- 命名形态：标准型
- **网页 RPA（如有）— 登录策略：** `not_needed`
  - 本技能不涉及任何网页自动化、浏览器操作或外部系统登录，所有数据存储与操作均在本地 SQLite 中完成。
  - 不调用 account-manager，不使用 profile_dir。

## 0.1 宿主入口定位

| 主能力（Action id / CLI） | 对话 | 数据管理 | 定时 | 不挂理由（若不挂） |
|---------------------------|------|----------|------|--------------------|
| `todo add` | 挂 | toolbar（新增按钮） | 不挂 | 定时无意义 |
| `todo list` | 挂 | row | 不挂 | 定时无意义 |
| `todo done`（Action `todo-done-row`） | 挂（短 CLI 直调） | row（「完成本行」按钮） | 不挂 | 定时无意义；batch 批量完成暂未声明 |
| `todo delete` | 挂 | row + batch（删除） | 不挂 | 定时无意义 |
| `todo stats` | 挂 | toolbar（统计） | 不挂 | 定时无意义 |
| `remind` | 挂 | toolbar | 挂 | 定时扫描到期/待办项并提醒 |
| `init-db` | 不挂 | 不挂 | 不挂 | 宿主安装/更新时静默调用，不对用户暴露 |
| `health` | 不挂 | 不挂 | 不挂 | 内部诊断命令 |
| `version` | 不挂 | 不挂 | 不挂 | 内部诊断命令 |
| `config-path` | 不挂 | 不挂 | 不挂 | 内部诊断命令 |

说明：

- 数据管理页面默认展示列：`title`、`status`、`priority`、`due_at`、`created_at`；默认按 `created_at` 倒序。
- `status` 与 `priority` 字段在数据管理中以下拉枚举展示（pending=待办/done=完成；high=高/normal=中/low=低）。

## 0.2 AI + RPA 协作与授权边界

### Agent 设计

- 用户会怎样描述本任务：
  - “帮我加一条待办：周五前提交周报，优先级高。”
  - “帮我看看有哪些待办。”
  - “把第 1、3 条标记为完成。”
  - “把第 2 条删掉。”
  - “统计一下待办情况。”
- 支持哪些用户意图；分别映射到哪个 Action：
  - 新增待办 → `todo add`
  - 查看列表 → `todo list`
  - 标记完成 → `todo done`
  - 删除待办 → `todo delete`
  - 统计概览 → `todo stats`
  - 到期提醒 → `remind`（async）
- 每种意图必须提取哪些参数：
  - 新增：`title`（必填）、`priority`（可选，默认 normal）、`due_at`（可选，Unix 秒）
  - 查看列表：`status`（可选，pending/done）、`limit`（可选，默认 100）
  - 标记完成：`ids`（必填，单个或逗号分隔多个）
  - 删除：`ids`（必填，单个或逗号分隔多个）
  - 提醒：`seconds`（可选，模拟运行秒数，默认 3）
- 缺少哪些参数时必须追问：
  - 新增时缺少 `title` 必须追问
  - 标记完成/删除时缺少 `ids` 必须追问
- 哪些动作必须先展示对象、数量和影响，再取得明确确认：
  - 批量删除（影响多条数据，删除不可恢复）
  - 批量标记完成（可提示将标记的数量）
- Agent 最终如何解释成功、部分成功、失败、等待人工和停止：
  - 成功：返回操作后的待办数据或统计结果
  - 部分成功：批量操作中逐条返回 `ok/id/error`，告知哪些成功哪些失败及原因
  - 失败：返回 `ERROR:` 前缀 + 中文原因（如标题为空、编号不存在、已完成不可重复标记）
  - 等待人工：本技能无外部依赖，无需人工介入
  - 停止：async 任务支持 `JobStopped` 取消

### 授权与平台边界

- 目标浏览器 / 桌面软件 / 手机 App：无
- 账号、设备、数据和业务权限由谁授权：无需外部授权，数据存于本地 SQLite
- 是否有获得授权的官方 API；若不用，原因是什么：不涉及外部系统
- 目标平台规则、合同或客户约定中的自动化边界：不适用
- 明确禁止的实现路线：不适用（无外部交互）
- 正常界面无法闭环时的上报与停止条件：不适用

### RPA 风控设计

不适用。本技能为纯本地数据操作，不涉及任何 RPA、浏览器、桌面或移动端自动化。

## 0.3 业务行生命周期

不适用。

本技能的 `todos` 表为用户直接管理的 CRUD 数据，不存在自动处理队列：
- `pending` → `done` 的状态变更由用户主动触发（`todo done`），非技能自动捞起处理。
- 无「进行中」抢占、无失败重试、无跳过逻辑。
- 因此不适用 `WORK_ITEM_STATUS.md` 的处理队列生命周期。

## 1. 文档目标

- 本文档用于明确 `add-todo-all` 的研发范围、交付标准、依赖关系和验收要求。
- 技术人员应以本文件作为开发范围依据，以避免实现偏差、范围蔓延或理解不一致。

## 2. 业务背景

- 当前用户在日常工作中需要管理个人或团队的待办事项，人工记录容易遗漏且难以批量管理。
- 现有流程主要依赖手动记录，存在「不易追踪进度、无法批量操作、缺少到期提醒」等问题。
- 因此需要开发 `add-todo-all`，用于在本地自动完成待办的创建、查询、状态变更、批量删除与到期提醒，输出结构化 JSON 结果并持久化到本地 SQLite。

## 3. 开发目标

- 解析并校验待办输入的关键字段（标题非空、优先级合法、状态合法）
- 通过本地 SQLite 完成待办的增删改查
- 输出结构化结果（stdout JSON）
- 写入业务表 `todos`（含 `created_at` / `updated_at` Unix 秒级时间戳）
- 支持失败可诊断（稳定错误信息、`ERROR:` 前缀）
- 完成 CLI 入口与 `health` / `version` / `init-db` 最小可运行验证
- 实现 async 提醒任务范式（`job_context` + `emit` + `finish`）

## 4. 功能范围

### 必须实现

- 支持 `python scripts/main.py health`（运行时健康检查）
- 支持 `python scripts/main.py version`（版本信息 JSON）
- 支持 `python scripts/main.py init-db`（幂等建库与数据管理元数据）
- 支持 `python scripts/main.py todo add <title> [-p high|normal|low] [-d <unix秒>]`（新增待办）
- 支持 `python scripts/main.py todo list [-s pending|done] [-n <limit>]`（列出待办，默认 100 条，按创建时间倒序）
- 支持 `python scripts/main.py todo done <id>`（标记完成，支持逗号分隔批量）
- 支持 `python scripts/main.py todo delete <id>`（删除，支持逗号分隔批量）
- 支持 `python scripts/main.py todo stats`（统计总数/待办数/完成数）
- 支持 `python scripts/main.py remind [-s <秒>]`（async 提醒任务，演示进度推送与终态上报）
- 支持 `python scripts/main.py config-path`（输出 .env 与模板路径）
- 业务内核统一在 `service/todo_service.py`，CLI / Action / 数据管理按钮共用同一内核
- 数据管理元数据：`todos` 表及字段具备中文 `display_name`，状态/优先级为枚举下拉，整表只读

### 可后续扩展

- 支持失败自动重试
- 支持多用户/多工作空间隔离
- 支持分类标签
- 支持截止时间到期的真实推送通知（当前 demo 仅统计，不做真实推送）

## 5. 非功能要求

- 目录结构必须符合当前 `skill-template` 规范
- 入口必须统一为 `scripts/main.py`
- 用户市场四 Tab 写在根 `README.md` / `TUTORIAL.md` / `DEMO.md` / `CHANGELOG.md`；LLM/运行契约写在 `SKILL.md`；开发规范在 `development/`
- 输出格式应尽量机读友好；错误前缀统一为 `ERROR:`
- Windows 环境下需保证 UTF-8 输出兼容
- 必须具备基本日志能力；敏感字段脱敏
- 业务表时间字段统一使用 Unix 秒级整数（`created_at` / `updated_at`）
- 数据管理展示顺序由 `PRAGMA table_info` 的 cid 决定，不依赖 `display_order`

## 6. 输入输出要求

### 输入

- `title`：待办标题，必填，非空字符串
- `priority`：优先级，可选，枚举 `high` / `normal` / `low`，默认 `normal`
- `due_at`：截止时间，可选，Unix 秒整数，默认 null
- `status`：列表过滤状态，可选，枚举 `pending` / `done`
- `limit`：列表返回上限，可选，整数，默认 100
- `ids`：标记完成/删除的待办编号，必填，单个数字或逗号分隔的数字列表
- `seconds`：提醒任务模拟运行秒数，可选，整数，默认 3
- 环境变量 / `.env`：本技能无强制环境变量依赖（`.env.example` 为模板通用项，本技能不使用 RPA 相关配置）

### 输出

- 成功结果（stdout JSON）：
  - 新增：单条待办对象 `{id, title, status, priority, due_at, created_at, updated_at}`
  - 列表：`{count, items: [Todo...]}`
  - 标记完成/删除：`{count, items: [{ok, id, ...}]}`
  - 统计：`{total, pending, done}`
- 错误输出：
  - `ERROR:TODO_INVALID: <原因>`（标题为空、优先级非法等）
  - 批量操作中失败项返回 `{ok: false, id, error}`
- 数据库记录：表 `todos`，字段 `id, title, status, priority, due_at, created_at, updated_at`
- async 提醒任务：通过 `emit` 推送进度，通过 `finish` 上报终态

## 7. 依赖的兄弟技能或外部系统

### 兄弟技能依赖

- 无（不依赖 account-manager 或其他兄弟技能）

### 外部系统依赖

- 无（纯本地 SQLite 存储，不访问任何外部 API 或网页）
- Gitea / 匠厂客户端：发布与正式环境验证

### Python 包依赖（requirements.txt）

- 本技能无特有 Python 三方包依赖（仅使用 Python 标准库 `sqlite3`、`argparse`、`asyncio`、`json` 等）
- `jiangchang-platform-kit` 由宿主共享 runtime 提供，不写入 requirements

## 8. 不在本次范围内的内容

- 本次不实现分类标签功能
- 本次不实现多用户/多工作空间隔离
- 本次不实现截止时间到期的真实推送通知（remind 仅为 async 范式演示，统计后不做真实推送）
- 本次不实现失败自动重试
- 本次不兼容旧模板历史结构（`docs/`、`optional/`、`skill_main.py` 等）

## 9. 验收标准

- 代码结构符合模板规范；`SKILL.md` slug 与 `constants.SKILL_SLUG` 一致
- `health`、`version`、`init-db` 命令执行正常
- `python tests/run_tests.py -v` 必跑测试全部通过
- `todo add` / `todo list` / `todo done` / `todo delete` / `todo stats` 命令在本地真实跑通
- 业务表 `todos` 写入和查询符合 `references/SCHEMA.md`（含 `created_at` / `updated_at` Unix 秒级规范）
- `init_db()` 已写入 `_jiangchang_tables` / `_jiangchang_columns`；`todos` 表及字段具备中文 `display_name`
- `todos` 表 `readonly=1`，字段 `editable=0`，宿主不直写业务表
- `status` / `priority` 字段具备 `options_json` 枚举下拉
- 字段展示顺序与 `PRAGMA table_info(todos)` 的 cid 一致；不依赖 `display_order`
- `tests/test_display_metadata.py` 通过
- `SKILL.md` 的 `developer_ids` 已配置为开发者本人匠厂用户 ID
- 发布后 Gitea 工作流成功；匠厂技能市场对开发者账号可见最新版本并可安装
- 安装后按本技能入口定位表与 `actions.json` 声明完成宿主多入口验收

## 10. 开发注意事项

- 只修改当前 skill 仓库，不要改动无关兄弟项目
- `cli` 只做参数解析；核心业务逻辑在 `service/todo_service.py`
- 单业务内核、多入口：CLI / Action / 数据管理按钮都调用 `todo_service` 的同一函数，禁止按入口分叉业务行为
- 数据表为只读，所有增删改通过技能 Action 走，宿主不直写
- 发布前完成本地验证、工作流验证和正式环境安装验证（含 `developer_ids` 与宿主多入口）

## 11. 变更记录

| 日期 | 版本 | 变更人 | 变更内容 |
|------|------|--------|----------|
| 2026-09-07 | v0.1.0 | - | 初版需求文档 |
| 2026-09-11 | v0.1.1 | - | 入口定位表登记行级 Action `todo-done-row`（todos 表操作列「完成本行」，sync/direct，`$row.$pk` 预填） |