init
This commit is contained in:
176
docs/issues.md
Normal file
176
docs/issues.md
Normal file
@@ -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、字段、排序策略）。
|
||||
107
docs/overview.md
Normal file
107
docs/overview.md
Normal file
@@ -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）
|
||||
Reference in New Issue
Block a user