commit f31340ab93d46ca6a10f2a91aff5ae457bfc4887
Author: wolves <yangwolves@foxmail.com>
Date:   Thu Jan 22 22:42:07 2026 +0800

    init

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..b0d6d66
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,5 @@
+.vscode
+
+.idea
+
+.DS_Store
\ No newline at end of file
diff --git a/docs/issues.md b/docs/issues.md
new file mode 100644
index 0000000..f9d676e
--- /dev/null
+++ b/docs/issues.md
@@ -0,0 +1,176 @@
+## 你目前设计里最容易被忽略的点（高优先级）
+
+### 1) 微服务拆分的时序与边界
+
+* 你写了“微服务 + K8s”，但阶段 1 又是 MVP。需要你明确：**MVP 阶段是否仍按单体/模块化实现**，还是从一开始就拆服务？否则会出现“为了拆而拆”导致交付极慢。
+* “个人任务服务”和“团队任务服务”边界：**同一份任务模型是否复用？**（字段/状态/权限/共享逻辑是否一致）如果不清晰，后期会出现大量重复代码与不一致行为。
+
+### 2) 权限模型过于粗
+
+* 你只写了“普通用户/管理员”。但你又支持团队/组织、多租户、协作编辑：这里通常需要更细的授权维度（例如：团队角色 vs 资源级权限）。
+* 需要你明确：**权限是 RBAC 还是 ABAC？**以及“任务”这一资源的授权粒度：按列表/项目/任务？是否支持只读、可评论、可编辑、可管理？
+
+### 3) JWT + Refresh Token 的安全细节没落地
+
+你写了机制，但没写关键决策点：
+
+* Refresh Token 存哪（httpOnly cookie / localStorage / DB）？**多端登录**如何管理（每设备一份还是共享一份）？
+* Token 轮换/吊销：**如何“立即登出”**、如何处理泄露、是否做 refresh token rotation + reuse detection？
+* CSRF/CORS 策略：如果用 cookie，需要明确 CSRF 方案；如果用 header token，需要明确 XSS 风险与防护。
+
+### 4) “实时同步 + 离线 + 冲突处理”缺少一致性边界
+
+你提到版本号控制，但缺少决策点：
+
+* 冲突的“真相源”是谁：服务端强一致、还是客户端合并、还是最后写入 wins？
+* 版本号是**行级/任务级/字段级**？拖拽排序会带来大量并发写，冲突策略要提前定。
+* 离线恢复：需要明确**操作日志（oplog）**还是全量覆盖？恢复时如何幂等？如何处理重放导致的重复创建/重复通知？
+
+### 5) “排序/拖拽”在 DB 层的表示
+
+* 任务排序字段用什么策略（浮点/稠密 rank/链表/分段），批量移动时复杂度如何控制。
+* 团队协作下两个人同时拖拽同一列表，冲突规则是什么。
+
+---
+
+## 架构与工程层面的漏项（中高优先级）
+
+### 6) 数据域与事件流缺口
+
+你有 Kafka，但没有写：
+
+* 哪些场景发事件（任务创建/状态变化/到期/成员变更），哪些服务订阅（通知/搜索索引/统计）。
+* 事件的**幂等键、重试、死信队列**、顺序性要求（同一任务的事件是否要求有序）。
+
+### 7) 数据库与多租户隔离策略没定
+
+你写“多租户可选”，但需要明确：
+
+* 隔离方式：同库同表加 tenant_id / schema-per-tenant / db-per-tenant。
+* 索引策略：tenant_id + 常用过滤字段的联合索引，否则一上量就慢。
+* 数据导出/删除（GDPR 类需求）：租户级删除如何落地。
+
+### 8) 搜索（Elastic）与一致性/权限过滤
+
+* 索引更新是同步还是异步？异步就会有“刚改完搜不到/刚删还搜得到”的窗口，你要接受还是要补偿。
+* 更关键：**搜索结果如何做权限过滤**（尤其团队任务）——是索引里预计算 ACL，还是查询后回源 DB 过滤？两种成本差异很大。
+
+### 9) 统计分析服务的数据来源
+
+* 统计是直接扫业务库、还是走事件/数仓（OLAP）？如果直接扫 PostgreSQL，后期会影响主库。
+* 指标口径要提前定：完成度如何算？归档算不算？重复任务怎么算？
+
+### 10) 附件功能缺少存储与安全链路
+
+你写“附件”，但没写：
+
+* 对象存储（S3/MinIO/OSS）与上传方式（直传/中转）、预签名 URL。
+* 权限校验：下载链接如何防泄露；是否要病毒扫描/类型限制/大小限制。
+
+---
+
+## API 与可观测性漏项（中优先级）
+
+### 11) REST 统一，但跨服务调用与版本管理没写
+
+* 内部服务间也用 REST：需要明确超时、重试、熔断、限流、降级策略（否则生产级链路会很脆）。
+* API 版本策略：/v1、header 版本、还是字段向后兼容？OpenAPI 如何跟版本绑定？
+
+### 12) 幂等性与一致性保障
+
+* 任务创建/批量操作/通知触发都需要幂等策略：请求重试、网络抖动会重复写。
+* 事务边界：跨服务操作（例如创建任务后发通知 + 建索引）如何保证“至少一次/恰好一次”的效果？你目前没定义接受的语义。
+
+### 13) 观测只列了工具，缺少“约定”
+
+* traceId 如何贯穿网关→各服务→Kafka？
+* 日志规范：结构化字段、用户标识脱敏、错误分级。
+* SLO/报警：你要监控哪些关键指标（登录失败率、任务写入错误率、WebSocket 连接数、消费堆积等）。
+
+---
+
+## 测试与交付漏项（中优先级）
+
+### 14) 测试分层覆盖点没写
+
+* 微服务下建议考虑**契约测试**（consumer-driven contract），否则服务改动容易把别的服务打崩。
+* 离线/冲突/实时同步属于“最难测”的部分：需要明确用什么方式做端到端场景测试与回归数据集。
+
+### 15) 数据迁移与灰度发布
+
+* PostgreSQL schema 迁移工具与流程（向前兼容/回滚策略）。
+* 灰度发布时旧客户端/新服务并存的兼容策略（尤其 Token、WebSocket 协议、排序字段变更）。
+
+---
+
+## 小但容易踩坑的细节（低到中优先级）
+
+* 时区：截止时间、提醒、统计按用户时区还是租户时区？
+* 删除语义：软删/硬删/归档的区别；是否支持恢复；审计日志保留多久。
+* 限流与防刷：登录、搜索、Webhook 回调都需要限流与签名验证。
+* Webhook：重试、签名、回调失败处理、事件订阅管理页面。
+
+---
+
+# 补全要点（建议方案）
+
+## 1) 微服务拆分的时序与边界
+- MVP 采用“模块化单体”，对外保持 REST 接口一致；阶段 4 再按服务拆分，避免过早复杂化。
+- 个人任务与团队任务复用统一任务模型，权限/可见性通过资源归属（owner_id/team_id）区分。
+
+## 2) 权限模型
+- 采用 RBAC + 资源级权限控制。
+- 团队角色：Owner/Admin/Member/Viewer；资源级权限：read/write/manage/comment。
+
+## 3) JWT + Refresh Token 细节
+- Access Token 放 Header，Refresh Token 放 httpOnly Cookie。
+- 每设备一份 Refresh Token，开启 rotation + reuse detection；支持即时注销（服务端黑名单/版本号）。
+- Cookie 场景启用 CSRF Token；Header 场景启用 CSP/XSS 防护策略。
+
+## 4) 实时同步与离线
+- 服务端为真相源；乐观并发控制（version 字段），冲突默认 last-write-wins，可选手动合并。
+- 离线采用 oplog（操作日志）重放，使用幂等键避免重复创建/通知。
+
+## 5) 排序/拖拽
+- 采用稠密 rank（如 1.0、1.5、2.0）策略；必要时批量重排。
+- 并发拖拽冲突：按 version + rank 重新计算并回传最新排序。
+
+## 6) 事件流（Kafka）
+- 事件：task.created/updated/completed/deleted, reminder.due, team.member.changed。
+- 订阅：通知服务、搜索服务、统计服务；统一幂等键 + 重试 + 死信队列。
+
+## 7) 多租户隔离
+- 同库同表 + tenant_id，联合索引（tenant_id, user_id, status, due_at）。
+- 支持租户级数据导出与清理（软删 + 异步物理清理）。
+
+## 8) 搜索一致性与权限
+- 索引异步更新，允许短暂不一致；删除走补偿任务。
+- 搜索权限：索引内嵌 ACL 字段（team_id、member_ids、visibility），查询时过滤。
+
+## 9) 统计分析数据源
+- 统计基于事件流汇总，落地到统计表或 OLAP。
+- 指标口径：归档不计入活跃任务，重复任务按实例统计。
+
+## 10) 附件链路
+- 对象存储：S3/MinIO；上传采用预签名直传。
+- 下载走鉴权签名 URL，限制类型/大小，可选病毒扫描。
+
+## 11) REST 内部调用与版本
+- 服务调用设置超时、重试、熔断、限流；使用统一 client 中间件。
+- API 版本：/v1；OpenAPI 与版本绑定。
+
+## 12) 幂等性与一致性
+- 写请求支持 Idempotency-Key。
+- 跨服务操作采用“至少一次”语义，消费端保证幂等。
+
+## 13) 可观测性约定
+- traceId 贯穿网关→服务→Kafka；统一结构化日志字段与脱敏策略。
+- 关键指标：登录失败率、任务写入错误率、事件积压、搜索延迟。
+
+## 14) 测试分层
+- 单元 + 集成 + 端到端 + 契约测试（服务间）。
+- 离线/冲突/实时同步采用固定场景回归集。
+
+## 15) 数据迁移与灰度
+- 迁移工具：goose 或 atlas，遵循向前兼容。
+- 灰度发布支持旧客户端兼容（Token、字段、排序策略）。
diff --git a/docs/overview.md b/docs/overview.md
new file mode 100644
index 0000000..27d3b28
--- /dev/null
+++ b/docs/overview.md
@@ -0,0 +1,107 @@
+# Todolist 全功能应用计划
+
+## 目标与范围
+构建一个“复杂但可靠”的 Todo 应用，覆盖前后端、鉴权、权限、数据一致性、性能与观测等完整链路，满足生产级实践。
+
+- 支持个人/团队任务管理
+- 分布式微服务架构，Kubernetes 部署
+- 网页/小程序/移动端 多端适配
+
+## 功能规划
+### 1. 用户与权限
+- 用户注册/登录/退出
+- JWT + Refresh Token 机制
+- 角色权限（普通用户/管理员）
+- 多租户可选（组织/团队）
+
+### 2. 任务管理（核心）
+- 任务 CRUD（标题/描述/截止时间/优先级/标签/附件）
+- 任务状态流转（待办/进行中/完成/归档）
+- 子任务、多级任务
+- 任务排序、拖拽
+- 批量操作
+
+### 3. 数据同步与协作
+- 实时同步（WebSocket/Server-Sent Events）
+- 冲突处理与版本号控制
+- 离线缓存与恢复
+
+### 4. 通知与提醒
+- 站内通知、邮件通知、Webhook
+- 定时提醒（cron/队列驱动）
+
+### 5. 搜索与分析
+- 全文检索
+- 任务完成度、统计报表
+- 活跃度/时间分布
+
+---
+
+## 技术架构
+### 服务划分（微服务）
+- 网关/API Gateway（统一入口、路由、鉴权前置、限流）
+- 认证服务（登录、注册、令牌、会话）
+- 用户服务（用户资料、偏好）
+- 个人任务服务（个人任务、标签、提醒）
+- 团队服务（团队/组织、成员、角色）
+- 团队任务服务（团队任务、协作、权限）
+- 通知服务（站内/邮件/Webhook）
+- 搜索服务（索引与查询）
+- 统计分析服务（报表、指标）
+- 通信协议：统一使用 HTTP RESTful
+
+### 前端
+- 框架：Vue 3 + Vite + TypeScript
+- 状态管理：Pinia
+- UI：自定义设计系统 + Tailwind / Radix
+- 路由：Vue Router
+- 数据请求：TanStack Query（Vue）
+
+### 后端
+- 语言：Go
+- Web 框架：Gin
+- DB：PostgreSQL
+- ORM/数据访问：GORM + sqlc（学习对比，混合使用）
+- 缓存：Redis
+- 搜索：Elastic
+- 消息队列：Kafka
+
+### 中间件/基础设施
+- 鉴权中间件（JWT/Session）
+- 日志与监控（Zap + Prometheus + Grafana）
+- 链路追踪（OpenTelemetry）
+- 配置管理（Viper）
+- 容器化与编排（Docker + Kubernetes）
+- 服务发现与配置（K8s Service/ConfigMap/Secret）
+
+---
+
+## 分阶段实施计划
+### 阶段 1：核心 MVP
+- 用户注册/登录
+- 任务 CRUD
+- 基础列表/详情页面
+- 基础权限控制
+
+### 阶段 2：增强功能
+- 子任务、多标签
+- 搜索功能
+- 任务统计报表
+
+### 阶段 3：协作与实时
+- WebSocket 实时同步
+- 冲突处理机制
+- 离线缓存支持
+
+### 阶段 4：运维与优化
+- 监控报警
+- CI/CD 自动化
+- 性能优化与安全审计
+- 微服务拆分与 K8s 部署（服务编排、网关、灰度发布）
+
+---
+
+## 测试与交付
+- 单元测试、集成测试
+- API 文档（OpenAPI）
+- 端到端测试（Cypress/Playwright）