docs(api): 补附件契约、Markdown 存储理由与富文本路由

2.Design/ROADMAP-M0-M1.md

@@ -349,3 +349,34 @@
 - [x] 模拟器（API 35）实跑：登录 → 工作区 → 任务勾选 → 工单 → 知识 → 成员，截图存 `2.Design/screens/android-*.png`
 - [~] 看板不做拖拽：手机屏幕上一列已占 76% 宽，拖拽命中率太差；改为点卡片选目标列，功能等价
 - [ ] 离线缓存（Room）、图片附件、消息推送：均未做，M5 再议
+
+---
+
+## 5. 富文本与附件（M2.5）
+
+### 5.1 决策：正文存 Markdown，不存 HTML
+- [x] 任务备注、工单说明与验收结论、知识正文、评论，统一 `*_md` 字段存 Markdown
+- [x] 渲染器自研零依赖（`web/src/lib/markdown.ts`），**先转义再上标签**，链接协议白名单 `http(s)/mailto//`
+- [x] 不做 contenteditable 富文本：它产出 HTML，导出/检索/喂 LLM 都要再清洗，且 `dangerouslySetInnerHTML` 面积更大
+- [ ] 表格与 HTML 片段：暂不支持，按原样当文本（等真有需求再加）
+
+### 5.2 附件
+- [x] 后端：`attachment` 表 + RLS + 迁移 0005；`POST/GET/DELETE` 与 `download`/`raw` 两个读取口
+- [x] 本地磁盘存储（`backend/app/services/storage.py`），key 由内容 sha256 决定；换对象存储只改这一个文件
+- [x] 上限 `MAX_UPLOAD_MB=20`，声明大小与流式读取双重拦截，超限 `8002`
+- [x] 列表带 `attachment_count`，详情带 `attachments`，避免一屏 N 次请求
+- [x] 下载走带 `Authorization` 的 fetch 转 blob；`<img>` 直链走 `raw?token=`，只允许本工作区成员
+- [ ] 图片直链改一次性签名 URL（当前 token 放 query，上生产前必须换）
+- [ ] 缩略图、图片压缩、病毒扫描：未做
+
+### 5.3 编辑器
+- [x] `RichTextEditor`：工具栏（粗体/斜体/标题/列表/引用/代码/链接/图片）+ `Ctrl+B`/`Ctrl+I` + 预览切换
+- [x] 粘贴与拖拽上传图片，自动在光标处插入 `![文件名](attachmentUrl(...))`
+- [x] `AttachmentPanel`：上传/下载/删除（删除二次确认，对应后端 `?confirm=true`）
+- [x] 安卓：本轮未做富文本编辑，只做只读渲染 + 附件下载（M5 再议）
+
+### 5.4 验证
+- [x] 后端 `pytest` → **70 passed**（新增附件 5 个用例：上传下载、超限、跨租户、删除确认与权限、raw 直链鉴权）
+- [x] `web/e2e/richtext.mjs` → 9 项全绿（渲染、贴图上传后 `/raw` 返回 200、附件落库后重开仍在、控制台无报错）
+- [x] 既有三套 e2e 回归通过（smoke 7 / tickets 8 / knowledge 7）
+- [x] `tsc -b` 0 错；`vite build` 255.07 kB │ gzip 80.85 kB