docs: README补附件全链路章节(上传/规整/展示/打开下载/错误码/charset乱码修复)

README.md

@@ -26,10 +26,26 @@
 
 | 表 | 说明 |
 |---|------|
-| tk_tickets | 工单主表（状态机+当前受理角色/人+agent处理锁） |
-| tk_messages | 往来消息（visibility: customer客户可见/internal内部备注） |
+| tk_tickets | 工单主表（状态机+当前受理角色/人+agent处理锁；customer_user_id 必填=提单人，待办精确到人） |
+| tk_messages | 往来消息（visibility: customer客户可见/internal内部备注；attachments JSON 列存附件清单） |
 | tk_transfers | 转派流水（append-only，每次受理方变更必留痕） |
 
+## 附件（2026-09-11 上线，全链路）
+
+- **上传**：客户建单表单（Form uitype=file multiple）、追问/回复弹窗（UiFile multiple）→
+  FormData multipart → ahserver getPostData 自动落 FileStorage（filesroot，按用户目录分片），
+  params_kw['attachments'] 得 webpath（单 str / 多 list）。前端拦截：单条 ≤9 个、总量 ≤9.5MB。
+- **服务端规整**：core.normalize_attachments 生成 [{id,name,webpath,size}]（不信任客户端）：
+  路径必须 '/' 开头无 '..'、realpath 不越出 filesroot、真实存在；并调 tfr.file_useful 把文件
+  从临时清理队列摘除（否则 multipart 上传 1 小时后被当临时文件删）。错误码 TK_E014。
+- **展示**：ticket_detail_popup.dspy（页面详情与平台待办共用）消息流内联附件行 +
+  末尾「全部附件」汇总区；上传方彩色徽标区分（客户蓝/智能助手紫/人工客服橙）+昵称。
+  附件不做 markdown 链接——MdWidget 会劫持同源 <a> 为加载 markdown，用独立按钮行。
+- **打开/下载**：ticket_attachment.dspy（msg_id+att_id 反查，I5 服务端校验：客户只能取
+  visibility=customer 消息附件；staff/admin 全量）→ FileResponse；?download=1 加 attachment 头。
+  文本类显式 Content-Type charset=utf-8（aiohttp FileResponse 猜类型不附 charset → 中文乱码）。
+  错误码 TK_E015（附件不存在/丢失）。load_path 已注册 logined。
+
 ## 参数（params 表，运行时可改）
 
 | 参数 | 默认 | 说明 |