feat(task): M1 任务域后端与 Web 列表（状态机/乐观锁/视图/搜索）

- item/tag/item_tag/comment/activity 五表迁移，RLS 全覆盖，pg_trgm 子串索引
- 状态机 domain/task.py：非法流转回 5002 并给 allowed，done 写 completed_at
- /workspaces/{ws}/items 列表/详情/新建/改/状态/软删/评论/标签
- 乐观锁 UPDATE...WHERE version，冲突 4009 + current_version
- Web 任务页：视图 tab、快速新建、勾选完成、开工/阻塞、详情事件流、游标分页
- 测试 43 全绿，ruff 干净，Web 构建通过
- 文档：2.Design/API.md 新增，ROADMAP 按已验证口径重写

2.Design/API.md

@@ -0,0 +1,206 @@
+# 接口约定（M0–M1 已实现）
+
+> 只写**已经在跑**的接口。写完没验证的东西不进这份文档。
+> 前缀 `/api/v1`。所有响应都是同一个信封，**HTTP 200 不代表业务成功**。
+
+## 0. 通用
+
+### 0.1 信封
+
+```json
+{ "code": 0, "message": "ok", "data": { }, "request_id": "c4a8…" }
+```
+
+- `code == 0` 才是成功；非 0 时 `data` 里放结构化细节（例如冲突时的 `current_version`）。
+- `request_id` 出现在响应头 `X-Request-Id` 与日志里，报障时带上它。
+- 分页统一 `{items, next_cursor, has_more}`；`next_cursor` 为空即到底。
+
+### 0.2 错误码
+
+| 码 | HTTP | 含义 | 客户端该怎么处理 |
+|---|---|---|---|
+| 1001 | 400 | 参数不合法 | 提示并标红字段 |
+| 1002 | 401 | 未认证 | 清 token → 登录页 |
+| 1004 | 404 | 资源不存在 | — |
+| 1009 | 409 | 唯一冲突（如 slug 已存在） | 换个名字 |
+| 2001 | 401 | 缺少访问令牌 | 登录页 |
+| 2002 | 401 | 令牌无效/过期 | 先试 refresh，失败再登录 |
+| 2003 | 403 | 令牌类型不符（refresh 当 access 用） | 程序 bug |
+| 2010 | 429 | 验证码请求太频繁 | 倒计时 60 秒 |
+| 2011 | 400 | 验证码错误/已过期 | 重发 |
+| 2012 | 403 | 账号被禁用 | 联系管理员 |
+| 3001 | 404 | 工作区不存在 | — |
+| 3003 | 403 | 不是该工作区成员 | **不要**提示"工作区不存在" |
+| 3004 | 403 | 角色权限不足 | 隐藏对应按钮 |
+| 3005 | 409 | 已经是成员 | 直接进工作区 |
+| 3010 | 400 | 邀请码无效/过期 | 提示重新索取 |
+| 4009 | 409 | 版本冲突（乐观锁） | 用 `data.current_version` 重试或刷新 |
+| 5001 | 404 | 任务不存在 | 刷新列表 |
+| 5002 | 409 | 非法状态流转 | 用 `data.allowed` 决定下一步给什么按钮 |
+| 5003 | 404 | 标签不存在 | — |
+
+> 错误码发布后**不许改号**，客户端靠它做分支。
+
+### 0.3 认证
+
+`Authorization: Bearer <access_token>`。`access` 30 分钟，`refresh` 14 天。
+`refresh_token` 只能用于 `/auth/refresh`（服务端校验 `typ`）。
+
+### 0.4 幂等
+
+所有 `POST/PATCH/DELETE` 都可带 `Idempotency-Key: <uuid>`。
+24 小时内同用户 + 同 key 返回首次结果，并带响应头 `X-Idempotent-Replay: 1`。
+**只缓存 2xx/3xx**，失败不缓存，所以重试是安全的。
+
+### 0.5 并发
+
+改动类接口（`PATCH /items/{id}`、`POST /items/{id}/status`、`DELETE`）必须带 `version`。
+拿不到 `version` 就别改——先 `GET` 一次。
+
+---
+
+## 1. 认证 `/auth`
+
+### `POST /auth/sms/send`
+
+```json
+{ "phone": "13800000000" }
+```
+
+响应 `data: { dev_code?: "123456" }`。`ENV=dev` 时才回显验证码，生产没有这个字段。
+60 秒内重复请求 → `2010`。
+
+### `POST /auth/login`
+
+```json
+{ "phone": "13800000000", "code": "123456" }
+```
+
+```json
+{ "user": { "id": "…", "phone": "138****0000", "nickname": "用户0000" },
+  "tokens": { "access_token": "…", "refresh_token": "…", "token_type": "bearer", "expires_in": 1800 } }
+```
+
+手机号**首次登录即注册**（昵称取"用户" + 后四位）。手机号回显永远是打码的。
+
+### `POST /auth/refresh`
+
+```json
+{ "refresh_token": "…" }
+```
+
+返回同形状的 `tokens`。无状态 JWT，**服务端不维护黑名单**——token 泄露只能等过期，这是 M0 已知取舍。
+
+### `GET /auth/me`
+
+返回 `{ user, workspaces[] }`，`workspaces[].role` 是当前用户在该工作区的角色。
+
+---
+
+## 2. 工作区 `/workspaces`
+
+| 方法 | 路径 | 权限 | 说明 |
+|---|---|---|---|
+| POST | `/workspaces` | 登录 | 建工作区，创建者自动成为 `owner` |
+| GET | `/workspaces` | 登录 | 我加入的工作区 |
+| GET | `/workspaces/{ws_id}` | 成员 | 详情 |
+| GET | `/workspaces/{ws_id}/members` | 成员 | 游标分页 |
+| POST | `/workspaces/{ws_id}/invitations` | admin+ | 生成邀请码，`{role}`；**只有 owner 能邀请 admin** |
+| POST | `/workspaces/{ws_id}/join` | 登录 | `{code}` 凭码加入，邀请码一次性 |
+
+角色等级：`owner(4) > admin(3) > member(2) > guest(1)`。
+
+---
+
+## 3. 任务 `/workspaces/{ws_id}/items`
+
+所有接口都要求**是该工作区成员**；跨租户一律 `3003`，任务不存在一律 `5001`（不区分"没有"和"不是你的"）。
+
+### 3.1 `GET /items`
+
+| 参数 | 取值 | 说明 |
+|---|---|---|
+| `view` | `inbox` `active` `today` `week` `done` `canceled` `all` `deleted` | 默认 `active`（todo+doing+blocked） |
+| `status` | 可重复 | 与 `view` 叠加时取更严的 |
+| `assignee` | `me` 或 uuid | |
+| `tag` | 标签名 | |
+| `q` | 关键词 | 标题 + 正文，`ILIKE %q%` |
+| `sort` | `updated`(默认) `due` `created` | `due` 不分页 |
+| `include_deleted` | 布尔 | 与 `view=all` 一起用 |
+| `limit` | 1–100，默认 20 | |
+| `cursor` | 上一页的 `next_cursor` | |
+
+`today` / `week` 的边界按 `settings.default_timezone`（默认 `Asia/Shanghai`）算，
+用**半开区间** `[今天 00:00, 明天 00:00)`，不用 UTC 切日。
+
+### 3.2 `POST /items`
+
+```json
+{ "title": "今天要交的周报", "body_md": "", "due_at": "2026-10-28T18:00:00+08:00",
+  "priority": 1, "assignee_id": null, "status": "inbox", "tag_names": ["周报"] }
+```
+
+`status` 默认 `inbox`（进收件箱，先归类再排期）。返回完整 `item`（含 `tags[]`、`version`）。
+
+### 3.3 `PATCH /items/{item_id}`
+
+**必须带 `version`**。`null` 与"没传"含义不同：
+
+- 传 `due_at: null` → 表示"清空"要用 `"clear_due_at": true`
+- 同理 `clear_assignee`、`clear_tags`
+- `tag_names` 一旦传就是**整体替换**
+
+冲突回 `4009` 且 `data.current_version` 给最新版本号。
+
+### 3.4 `POST /items/{item_id}/status`
+
+```json
+{ "status": "doing", "version": 3 }
+```
+
+状态机（`backend/app/domain/task.py`）：
+
+```
+inbox   → todo, canceled
+todo    → inbox, doing, done, canceled
+doing   → todo, done, blocked, canceled
+blocked → doing, canceled
+done    → todo            (重开)
+canceled→ todo            (恢复)
+```
+
+非法流转回 `5002`，`data = { from, to, allowed }`。
+**前端可以据此直接渲染"下一步能点什么"，不用自己维护一份规则。**
+目标状态与当前相同：直接返回，版本号不变。
+
+### 3.5 `DELETE /items/{item_id}?version=3`
+
+软删（写 `deleted_at`），只在 `view=deleted` / `include_deleted=true` 时可见。
+
+### 3.6 评论
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/items/{item_id}/comments` | 时间正序，游标分页 |
+| POST | `/items/{item_id}/comments` | `{body_md}` |
+
+### 3.7 标签 `/workspaces/{ws_id}/tags`
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/tags` | 工作区内标签，`{id,name,color}` |
+| POST | `/tags` | `{name, color?}`；同名直接返回已有的（幂等，不报错） |
+
+---
+
+## 4. 健康与版本
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/health` | `{status, db}`，DB 探活用 `SELECT 1` |
+| GET | `/version` | `{commit, build_time, db_role}` |
+
+`db_role` 里的 `is_super / bypass_rls / read_all` 全为 `false` 才说明 RLS 真的生效——
+这是部署后的第一道检查，比"能登录"重要得多。
+
+部署校验：`curl /version` 的 `commit` 必须等于 `git rev-parse --short HEAD`。

2.Design/ROADMAP-M0-M1.md

@@ -145,44 +145,58 @@
 
 **里程碑目标**：自己开始每天用它记待办，连续 3 天不别扭。
 
+> 进度口径：`[x]` = 已实现**且验证过**（测试/构建/冒烟），`[ ]` = 未做。每项后面写证据或偏差原因。
+
 ### 1.1 数据（1d）
-- [ ] `item` `item_assignee` `tag` `item_tag` `comment` `activity` 迁移
-- [ ] 索引：`(ws_id, status, due_at)`、`(ws_id, owner_id, status)`、`deleted_at` 部分索引
-- [ ] 全文索引：`zhparser` 或 `pg_bigm` 建在 `title + body_md`
+- [x] `item` `tag` `item_tag` `comment` `activity` 迁移（`backend/alembic/versions/0002_tasks.py`，revision 0002 ← 0001）
+- [x] 索引：`ix_item_ws_status_due (ws,status,due_at)`、`ix_item_ws_assignee`、`ix_item_ws_updated`、`ix_item_ws_sort`
+- [~] 中文全文：**没用 zhparser/pg_bigm，改用 `pg_trgm` + `ILIKE`**。理由：服务器是 Alpine 上的 PG 17，`pg_available_extensions` 只有 `pg_trgm`/`pgcrypto`，装 zhparser 要编译 + 改镜像；trigram 对中文按 3 字符切，子串匹配够用，且 `gin_trgm_ops` 索引能救性能。真正需要"相关度排序"时再上 zhparser（M3 知识库阶段重评）。
+- [x] 偏差：**没有 `item_assignee` 关联表**，`item.assignee_id` 单列。理由：M1 只有"一个任务一个负责人"，多人协作由工单阶段（M2）的 `item_link` 承担；提前上关联表会让每条查询都多一次 join。
+- [x] RLS：五张新表全部 `ENABLE ROW LEVEL SECURITY` + `workspace_id = app_ws_id()`，并 GRANT 给 `dadao_app`
 
 ### 1.2 领域（1.5d）
-- [ ] 状态机 `inbox→todo→doing→done`（+ blocked/canceled），非法流转拒绝并给提示
-- [ ] 所有变更写 `activity`（含 `changed_fields` 增量）
-- [ ] `version` 乐观锁，冲突返回 409 带当前版本
+- [x] 状态机 `backend/app/domain/task.py`：`inbox→todo→doing→done`（+ blocked/canceled，`done→todo` 可重开）；非法流转抛 `5002` 并回 `allowed`（"你可以去 canceled/todo"），不用前端猜
+- [x] 所有变更写 `activity`（`created` / `updated` / `status_changed{from,to}` / `commented`，payload 是 JSONB）
+- [x] `version` 乐观锁：`UPDATE ... WHERE version = ?` 看 `rowcount`，冲突回 `4009` + `current_version`（实测 stale 请求拿到 `current=4`）
+- [x] `done` 写 `completed_at`，重开清空；`deleted_at` 软删，`view=deleted` 才看得到
 
 ### 1.3 API（1.5d）
-- [ ] 增删改查、批量状态变更、排序（手动 sort_order）
-- [ ] 视图查询：inbox / today / week / all，支持标签与关键词过滤
-- [ ] 搜索接口（标题 + 正文，返回高亮片段）
+- [x] 增删改查（`backend/app/api/items.py`）、`POST /{id}/status`、软删（带 version）
+- [x] 视图：`inbox|active|today|week|done|canceled|all|deleted`；`today/week` 按 `Asia/Shanghai` 切日界（`settings.default_timezone`），不按 UTC
+- [x] 过滤：`status`（可重复）、`assignee=me|<uuid>`、`tag`、`q`（标题+正文 ILIKE，实测中文 `周报` 命中）
+- [ ] **批量状态变更**未做（M1 先做单条，批量等看板拖拽一起上）
+- [~] 搜索返回高亮片段：未做，只返回命中行。理由：高亮要在客户端按 query 二次切词，纯展示逻辑，等 Web 有真实使用反馈再补
+- [x] 分页：`(sort_key DESC, id DESC)` keyset 游标；`sort=due` 不分页（NULLS LAST 会把 NULL 行切碎，只有今日/逾期短列表用）
 
 ### 1.4 Web（3d）
-- [ ] 四视图 + 看板拖拽（列 = 状态）
-- [ ] 详情侧栏：优先级/截止/标签/备注/子任务（一层）/评论
-- [ ] 全局快速录入（`Ctrl+K` 或顶部输入框，支持 `#标签` `!优先级` `@人` 语法）
-- [ ] 键盘流：`j/k` 上下、`Enter` 完成、`e` 编辑
+- [x] 视图 tab（今天/进行中/收件箱/已完成/全部）+ 搜索框 + 回车快速新建（`web/src/pages/Tasks.tsx`）
+- [x] 勾选完成/重开、`收下`（inbox→todo）、`开工`（todo→doing）、`阻塞`
+- [x] 点标题展开：正文、标签、最近 8 条事件流；`409` 时提示"刚被别人改过"并重载
+- [x] 加载更多（游标），空态文案（"今天没有到期的事，挺好。"）
+- [x] `npm run build` 通过：38 modules，`183.26 kB │ gzip 60.08 kB`
+- [ ] 看板拖拽（列 = 状态）未做
+- [ ] 详情侧栏（优先级/截止日期选择器/评论输入/子任务）未做——当前详情只读
+- [ ] 全局快速录入 `#标签 !优先级 @人` 语法未做
+- [ ] 键盘流 `j/k`、`Enter`、`e` 未做
 
 ### 1.5 安卓（1.5d）
-- [ ] 列表 + 详情 + 勾选完成
-- [ ] 下拉刷新、只读缓存（Room，仅离线展示，改动必须联网）
+- [ ] 任务列表 + 详情 + 勾选完成（`android/` 目前只有 M0 的登录/工作区壳）
 
 ### 1.6 通知与提醒（0.8d）
-- [ ] 站内通知表与未读角标
-- [ ] 每日摘要邮件（可关）
+- [ ] 站内通知表与未读角标（表在 M2 随工单一起建）
+- [ ] 每日摘要邮件
 
 ### 1.7 测试与验收（0.7d）
-- [ ] 每个接口一条 happy path + 一条越权用例
-- [ ] 前端关键交互 e2e（Playwright 起 3 条：登录、建任务、拖动状态）
+- [x] `backend/tests/test_items.py` 10 个用例：默认收件箱、状态机 happy path 与非法流转、版本冲突、跨租户 3003 且他人列表为空、搜索+标签、`today` 时区边界、软删、评论与事件流、游标翻页不重复
+- [x] 全量 `pytest -q` → **43 passed**；`ruff check` + `ruff format --check` 全 0
+- [ ] Playwright e2e 未做
+- [ ] 性能口径（1000 条下首屏 < 300ms）未实测
 
 ### M1 完成定义（DOD）
-- [ ] 连续 3 天所有待办都记在里面，没有回到微信/备忘录
+- [ ] 连续 3 天所有待办都记在里面，没有回到微信/备忘录 —— 只有真实使用能证伪，代码侧无法替代
 - [ ] 冷启动到"建完第一个任务"< 90 秒（新账号实测）
 - [ ] 1000 条任务下四视图首屏 < 300ms
-- [ ] 跨租户测试、越权测试全绿
+- [x] 跨租户测试、越权测试全绿（`test_tenant_isolation.py` + `test_items.py::test_cross_tenant_access_denied`）
 
 ---