docs: reorganize docs — archive outdated, create brainstorming folder

- Create docs/brainstorming/ with 5 discussion records (Mar 16 - Apr 7) - Archive ~30 outdated audit reports (V5-V11) to docs/archive/old-audits/ - Archive superseded analysis docs to docs/archive/old-analysis/ - Archive completed session plans to docs/archive/old-plans/ - Archive old test reports/validations to respective archive folders - Remove empty directories left after moves - Keep current docs: TRUTH.md, feature docs, deployment, knowledge-base, superpowers
2026-04-07 09:54:30 +08:00
parent 8e9fc54d92
commit 2e5f63be32
101 changed files with 1829 additions and 17 deletions
--- a/docs/archive/old-analysis/OPTIMIZATION-ROADMAP.md
+++ b/docs/archive/old-analysis/OPTIMIZATION-ROADMAP.md
@@ -0,0 +1,331 @@
+# ZCLAW 项目优化路线图
+
+> **制定日期：** 2026-03-21
+> **基于：** 深度分析报告 + 头脑风暴会议
+
+---
+
+## 一、优化优先级矩阵
+
+### 1.1 优先级定义
+
+| 优先级 | 定义 | 时间要求 |
+|--------|------|----------|
+| P0 | 紧急影响使用 | 1 周内 |
+| P1 | 重要影响体验 | 2-4 周 |
+| P2 | 中期提升 | 1-2 月 |
+| P3 | 长期愿景 | 6 月+ |
+
+### 1.2 问题-方案-工作量矩阵
+
+| ID | 问题 | 方案 | 优先级 | 工作量 | 责任人 |
+|----|------|------|--------|--------|--------|
+| Q1 | gateway-client.ts 过大 (65KB) | 拆分为多模块 | P1 | 2-3 人天 | 前端 |
+| Q2 | localStorage 降级风险 | 统一使用 Rust 后端 | P1 | 1 周 | 前端+后端 |
+| Q3 | Rust unwrap() 风险 | 改用 expect() 并添加错误信息 | P1 | 0.5 人天 | 后端 |
+| Q4 | E2E 测试不稳定 | 修复等待逻辑，增加容错 | P0 | 2-3 人天 | 测试 |
+| Q5 | 聊天记录未加密 | SQLite 加密 | P1 | 1 周 | 后端 |
+| Q6 | Store re-render 问题 | Zustand shallow + React.memo | P2 | 2-3 人天 | 前端 |
+| Q7 | 缺少兼容性测试 | 建立自动化测试套件 | P1 | 1 周 | 测试 |
+| Q8 | 飞书集成不完整 | 完善 OAuth + 消息收发 | P2 | 1 周 | 前端+后端 |
+| Q9 | 插件市场不完善 | 插件市场 MVP | P2 | 1 周 | 前端 |
+| Q10 | 缺少 i18n | 引入 react-i18next | P2 | 1-2 周 | 前端 |
+
+---
+
+## 二、分阶段实施计划
+
+### Phase 0: 稳定化 (1-2 周)
+
+**目标：** 解决影响正常使用的 P0 问题
+
+#### Sprint 1: E2E 测试修复
+
+| 任务 | 描述 | 验收标准 |
+|------|------|----------|
+| T1.1 | 分析失败测试原因 | 列出所有不稳定测试 |
+| T1.2 | 修复等待逻辑 | 使用 `waitForFunction` 替代固定等待 |
+| T1.3 | 增加断言容错 | 处理网络延迟等边界情况 |
+| T1.4 | 验证修复 | 所有 E2E 测试通过率 > 95% |
+
+#### Sprint 2: 紧急 Bug 修复
+
+| 任务 | 描述 | 验收标准 |
+|------|------|----------|
+| T2.1 | 收集线上问题 | 基于用户反馈和监控 |
+| T2.2 | 修复 Top 5 Bug | 每个 Bug 有回归测试 |
+| T2.3 | 发布补丁版本 | v0.x.1 |
+
+**交付物：** 稳定的测试套件，补丁版本
+
+---
+
+### Phase 1: 架构优化 (2-4 周)
+
+**目标：** 提升代码质量和可维护性
+
+#### Sprint 3: gateway-client 拆分
+
+| 任务 | 描述 | 验收标准 |
+|------|------|----------|
+| T3.1 | 设计模块边界 | 输出模块划分文档 |
+| T3.2 | 拆分 websocket 模块 | 提取 WebSocket 管理逻辑 |
+| T3.3 | 拆分 rest 模块 | 提取 REST API 逻辑 |
+| T3.4 | 拆分 stream 模块 | 提取流式处理逻辑 |
+| T3.5 | 更新导入路径 | 全量回归测试 |
+| T3.6 | 编写模块文档 | 每个模块有 JSDoc |
+
+#### Sprint 4: Rust 后端加固
+
+| 任务 | 描述 | 验收标准 |
+|------|------|----------|
+| T4.1 | 替换 unwrap() | 使用 expect() 并添加上下文 |
+| T4.2 | 错误处理统一 | 所有命令返回 Result<T, String> |
+| T4.3 | 添加日志 | 关键路径有 tracing 日志 |
+| T4.4 | 安全审计 | 确认无敏感信息泄露 |
+
+#### Sprint 5: 持久化安全加固
+
+| 任务 | 描述 | 验收标准 |
+|------|------|----------|
+| T5.1 | 评估加密方案 | 选择 AES-256 或类似 |
+| T5.2 | 实现 SQLite 加密 | 聊天记录加密存储 |
+| T5.3 | 密钥管理 | 密钥存储在 OS Keyring |
+| T5.4 | 兼容性测试 | 旧数据迁移平滑 |
+
+**交付物：** 重构后的代码、安全加固、测试报告
+
+---
+
+### Phase 2: 体验优化 (1-2 月)
+
+**目标：** 提升用户使用体验
+
+#### Sprint 6: 性能优化
+
+| 任务 | 描述 | 验收标准 |
+|------|------|----------|
+| T6.1 | 分析 re-render 瓶颈 | 输出性能分析报告 |
+| T6.2 | Zustand shallow 优化 | 减少不必要的 re-render |
+| T6.3 | React.memo 优化 | 重点组件优化 |
+| T6.4 | 性能测试 | 1000+ 消息场景流畅 |
+
+#### Sprint 7: 飞书集成完善
+
+| 任务 | 描述 | 验收标准 |
+|------|------|----------|
+| T7.1 | OAuth 流程修复 | 完整的认证流程 |
+| T7.2 | 消息接收 | 支持接收飞书消息 |
+| T7.3 | 消息发送 | 支持回复飞书消息 |
+| T7.4 | 消息格式适配 | 支持富文本、图片等 |
+
+#### Sprint 8: 插件市场 MVP
+
+| 任务 | 描述 | 验收标准 |
+|------|------|----------|
+| T8.1 | 插件市场 UI | 列表、详情、安装界面 |
+| T8.2 | 插件 API 定义 | 标准化插件接口 |
+| T8.3 | 插件审核机制 | 基础的内容审核 |
+| T8.4 | 已有插件迁移 | 3 个插件正常安装 |
+
+#### Sprint 9: 国际化支持
+
+| 任务 | 描述 | 验收标准 |
+|------|------|----------|
+| T9.1 | i18n 框架集成 | react-i18next 配置 |
+| T9.2 | 字符串提取 | 提取所有硬编码字符串 |
+| T9.3 | 中文翻译完善 | 确保中文显示正确 |
+| T9.4 | 英文翻译 | 基础英文翻译 |
+| T9.5 | 语言切换 | 支持中英文切换 |
+
+**交付物：** 性能优化报告、飞书集成文档、插件市场 MVP、i18n 支持
+
+---
+
+### Phase 3: 差异化功能 (3-6 月)
+
+**目标：** 构建竞争壁垒
+
+#### Sprint 10: 知识图谱基础
+
+| 任务 | 描述 | 验收标准 |
+|------|------|----------|
+| T10.1 | 实体提取 | 从对话中提取实体 |
+| T10.2 | 关系挖掘 | 实体间关系识别 |
+| T10.3 | 图谱存储 | 图数据库或关系模拟 |
+| T10.4 | 查询接口 | 基础的知识图谱查询 |
+
+#### Sprint 11: 主动建议能力
+
+| 任务 | 描述 | 验收标准 |
+|------|------|----------|
+| T11.1 | 上下文分析 | 分析用户当前任务 |
+| T11.2 | 建议生成 | 基于上下文生成建议 |
+| T11.3 | UI 集成 | 在 ChatArea 中展示建议 |
+| T11.4 | 用户反馈 | 用户可采纳或忽略建议 |
+
+#### Sprint 12: 跨设备同步 (Pro)
+
+| 任务 | 描述 | 验收标准 |
+|------|------|----------|
+| T12.1 | 端到端加密 | 消息加密传输和存储 |
+| T12.2 | 设备配对 | 安全的设备注册流程 |
+| T12.3 | 数据同步 | 消息和记忆同步 |
+| T12.4 | 冲突解决 | 多设备同时修改时 |
+
+**交付物：** 知识图谱基础、主动建议能力、跨设备同步原型
+
+---
+
+### Phase 4: 生态扩展 (6 月+)
+
+**目标：** 扩大用户群体和使用场景
+
+#### 长期规划
+
+| 功能 | 描述 | 预估工作量 |
+|------|------|------------|
+| Tauri Mobile | iOS/Android 支持 | 2-3 月 |
+| 企业版 | 多用户、权限管理 | 2-3 月 |
+| API 开放 | 第三方开发者集成 | 1-2 月 |
+| 本地模型 | Llama.cpp 集成 | 2-3 月 |
+
+---
+
+## 三、技术债务清理
+
+### 3.1 技术债务清单
+
+| ID | 债务 | 影响 | 清理方式 | 优先级 |
+|----|------|------|----------|--------|
+| D1 | gatewayStore.ts 残留引用 | 维护困难 | 全部迁移到领域 Store | P1 |
+| D2 | 旧版 API 兼容代码 | 体积增加 | 评估后移除 | P2 |
+| D3 | v1 归档代码未清理 | 混淆 | 删除或移入 archive | P2 |
+| D4 | 重复的工具函数 | 维护困难 | 提取到 utils | P3 |
+| D5 | 缺失的 JSDoc | 文档不全 | 补全关键模块 | P3 |
+
+### 3.2 清理计划
+
+```
+Q2: D1, D2
+Q3: D3
+Q4: D4, D5
+```
+
+---
+
+## 四、监控指标
+
+### 4.1 质量指标
+
+| 指标 | 当前值 | 目标值 | 监控方式 |
+|------|--------|--------|----------|
+| E2E 测试通过率 | ~80% | > 95% | CI/CD |
+| 单元测试覆盖率 | ~40% | > 60% | Codecov |
+| TypeScript 错误 | < 10 | 0 | CI/CD |
+| bundle 大小 | ~2MB | < 2.5MB | 打包监控 |
+
+### 4.2 性能指标
+
+| 指标 | 当前值 | 目标值 | 监控方式 |
+|------|--------|--------|----------|
+| 首屏加载 | ~2s | < 1.5s | Lighthouse |
+| 消息响应延迟 | ~200ms | < 100ms | APM |
+| 内存占用 (idle) | ~150MB | < 200MB | 性能监控 |
+| WebSocket 重连 | < 3 次 | < 1 次 | 日志分析 |
+
+### 4.3 业务指标
+
+| 指标 | 当前值 | 目标值 |
+|------|--------|--------|
+| 日活跃用户 | - | 需建立埋点 |
+| 功能使用率 | - | 需建立埋点 |
+| 反馈评分 | - | 需收集 |
+| 崩溃率 | - | < 0.1% |
+
+---
+
+## 五、资源需求
+
+### 5.1 人力需求
+
+| 角色 | Phase 0-1 | Phase 2 | Phase 3-4 |
+|------|-----------|---------|-----------|
+| 前端开发 | 1 | 2 | 2 |
+| 后端开发 | 1 | 1 | 1 |
+| 测试开发 | 1 | 1 | 1 |
+| 产品经理 | 0.5 | 0.5 | 1 |
+
+### 5.2 技术债务融资
+
+| 来源 | 可能性 | 备注 |
+|------|--------|------|
+| 政府补贴 | 中 | 科技型中小企业 |
+| 开源捐赠 | 低 | 需要社区基础 |
+| 企业版收入 | 高 | 长期可持续 |
+
+---
+
+## 六、风险与应对
+
+### 6.1 项目风险
+
+| 风险 | 概率 | 影响 | 应对措施 |
+|------|------|------|----------|
+| ZCLAW 版本不兼容 | 中 | 高 | 建立兼容性测试套件 |
+| 关键人员离职 | 低 | 高 | 文档和知识共享 |
+| 竞品快速迭代 | 高 | 中 | 聚焦差异化功能 |
+| 技术方案不可行 | 低 | 中 | 技术验证先行 |
+
+### 6.2 应对策略
+
+1. **版本兼容性**
+   - 方案：建立自动化测试套件
+   - 负责人：测试团队
+   - 开始时间：Phase 1
+
+2. **竞品压力**
+   - 方案：聚焦差异化（知识图谱、主动建议）
+   - 负责人：产品团队
+   - 开始时间：Phase 3
+
+---
+
+## 七、总结
+
+本优化路线图分为 4 个阶段：
+
+| 阶段 | 时间 | 目标 |
+|------|------|------|
+| Phase 0 | 1-2 周 | 稳定化 - 解决 P0 问题 |
+| Phase 1 | 2-4 周 | 架构优化 - 提升代码质量 |
+| Phase 2 | 1-2 月 | 体验优化 - 提升用户满意度 |
+| Phase 3 | 3-6 月 | 差异化功能 - 构建竞争壁垒 |
+| Phase 4 | 6 月+ | 生态扩展 - 扩大用户群体 |
+
+**核心理念：**
+- 稳定性优先于新功能
+- 渐进式改进，避免大规模重构
+- 聚焦差异化，建立竞争壁垒
+- 保持本地优先，保护用户隐私
+
+---
+
+## 八、附录
+
+### A. 关键里程碑
+
+| 日期 | 里程碑 | 交付物 |
+|------|--------|--------|
+| 2026-03-28 | Phase 0 完成 | 稳定测试套件 |
+| 2026-04-15 | Phase 1 完成 | 重构代码、安全加固 |
+| 2026-05-31 | Phase 2 完成 | 性能优化、功能完善 |
+| 2026-08-31 | Phase 3 完成 | 差异化功能 |
+
+### B. 审批记录
+
+| 角色 | 日期 | 签字 |
+|------|------|------|
+| 技术负责人 | 2026-03-21 | |
+| 产品负责人 | 2026-03-21 | |
+| 项目经理 | 2026-03-21 | |