First Commit

2026-03-25 14:15:04 +08:00
commit 134d84d933
84 changed files with 25878 additions and 0 deletions
--- a/有维项目/.qoder/repowiki/zh/content/扩展与集成/数据持久化策略.md
+++ b/有维项目/.qoder/repowiki/zh/content/扩展与集成/数据持久化策略.md
@@ -0,0 +1,366 @@
+# 数据持久化策略
+
+<cite>
+**本文档引用的文件**
+- [index.html](file://index.html)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考量](#性能考量)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本项目为“有维商学”前端单页应用，当前未实现任何客户端数据持久化（如 localStorage/sessionStorage、IndexedDB、Web SQL 等），所有用户状态与界面交互均为内存态，刷新即丢失。本文档围绕现有代码现状，提出数据持久化策略与扩展方案，涵盖数据模型设计、同步机制、备份恢复、清理规则、隐私保护、迁移升级、性能优化与安全考虑，并提供可视化图示辅助理解。
+
+## 项目结构
+- 单文件 HTML 应用，包含完整的页面结构、样式与内联 JavaScript。
+- 页面包含登录页、仪表盘、AI智能体页等，通过内联脚本实现页面切换与交互。
+- 无外部依赖，所有逻辑集中在 index.html 中。
+
+```mermaid
+graph TB
+A["index.html<br/>主页面与内联脚本"] --> B["登录页<br/>表单与提交逻辑"]
+A --> C["仪表盘页<br/>导航与Tab切换"]
+A --> D["AI智能体页<br/>卡片与筛选"]
+A --> E["聊天弹窗<br/>消息发送与显示"]
+```
+
+图表来源
+- [index.html](file://index.html)
+
+章节来源
+- [index.html](file://index.html)
+
+## 核心组件
+- 用户状态管理：当前登录用户名在内存中维护，页面切换与用户头像显示依赖该变量。
+- 页面路由：通过内联函数切换页面与 Tab，无历史记录持久化。
+- 交互组件：用户菜单、行业筛选、聊天对话等均为内存态，未与持久化绑定。
+
+章节来源
+- [index.html](file://index.html)
+
+## 架构总览
+当前架构为纯前端单页应用，无后端接口调用与数据持久化层。若要引入数据持久化，建议采用如下分层：
+- 表现层：index.html 的页面与交互逻辑
+- 业务层：用户、课程、AI对话、会员状态等数据模型与业务规则
+- 持久化层：localStorage/sessionStorage（短期）、IndexedDB（长期）、Web SQL（兼容）
+- 同步层：与后端 API 的数据同步与一致性保障
+- 安全层：加密、访问控制、审计日志
+
+```mermaid
+graph TB
+subgraph "表现层"
+UI["index.html<br/>页面与交互"]
+end
+subgraph "业务层"
+UM["用户模型"]
+CM["课程模型"]
+AIM["AI对话模型"]
+MEM["会员状态模型"]
+end
+subgraph "持久化层"
+LS["localStorage"]
+SS["sessionStorage"]
+IDB["IndexedDB"]
+WSQL["Web SQL"]
+end
+subgraph "同步层"
+API["后端API"]
+end
+subgraph "安全层"
+ENC["加密"]
+ACL["访问控制"]
+AUDIT["审计日志"]
+end
+UI --> UM
+UI --> CM
+UI --> AIM
+UI --> MEM
+UM --> LS
+CM --> LS
+AIM --> LS
+MEM --> LS
+LS --> IDB
+SS --> IDB
+IDB --> API
+WSQL --> API
+API --> ENC
+API --> ACL
+API --> AUDIT
+```
+
+图表来源
+- [index.html](file://index.html)
+
+## 详细组件分析
+
+### 用户数据模型与持久化
+- 当前实现：登录用户名保存在内存变量中，刷新即丢失；用户头像与显示名称通过更新 DOM 实现。
+- 建议模型字段（示例）：
+  - 用户标识、昵称、头像、登录时间、最近活跃时间、设备指纹、会员等级、权限集合
+- 持久化策略：
+  - 短期：sessionStorage（会话级，浏览器关闭即清空）
+  - 长期：localStorage（跨会话保留，需注意隐私与容量）
+  - 安全：对敏感字段进行加密存储，定期轮换密钥
+
+```mermaid
+classDiagram
+class UserModel {
+string userId
+string displayName
+string avatar
+datetime lastLogin
+datetime lastActive
+string deviceFingerprint
+string membershipLevel
+array permissions
+saveToStorage()
+loadFromStorage()
+clearStorage()
+}
+```
+
+图表来源
+- [index.html](file://index.html)
+
+章节来源
+- [index.html](file://index.html)
+
+### 课程数据模型与持久化
+- 当前实现：课程列表为静态展示，无用户学习进度与收藏状态。
+- 建议模型字段（示例）：
+  - 课程ID、标题、描述、时长、学习状态、完成时间、评分、笔记
+- 持久化策略：
+  - 使用 IndexedDB 存储结构化课程数据，支持复杂查询与索引
+  - localStorage 仅用于轻量元数据（如最近浏览）
+
+```mermaid
+classDiagram
+class CourseModel {
+string courseId
+string title
+string description
+number duration
+string status
+datetime completedAt
+number rating
+string notes
+saveToDB()
+loadFromDB()
+syncWithServer()
+}
+```
+
+图表来源
+- [index.html](file://index.html)
+
+章节来源
+- [index.html](file://index.html)
+
+### AI对话记录模型与持久化
+- 当前实现：聊天弹窗为内存态，消息在页面内渲染，无持久化。
+- 建议模型字段（示例）：
+  - 对话ID、AI角色、消息数组（含时间戳、类型、内容）、会话标签、创建/更新时间
+- 持久化策略：
+  - IndexedDB 分区存储（按角色/日期），支持批量写入与增量同步
+  - sessionStorage 用于临时草稿
+
+```mermaid
+classDiagram
+class ChatRecordModel {
+string chatId
+string aiRole
+array messages
+string tag
+datetime createdAt
+datetime updatedAt
+saveToDB()
+loadFromDB()
+exportHistory()
+}
+```
+
+图表来源
+- [index.html](file://index.html)
+
+章节来源
+- [index.html](file://index.html)
+
+### 会员状态模型与持久化
+- 当前实现：会员体系为静态展示，无用户会员状态与有效期持久化。
+- 建议模型字段（示例）：
+  - 会员ID、类型、到期时间、续费记录、权益清单、订阅状态
+- 持久化策略：
+  - localStorage/sessionStorage 保存当前会话状态
+  - IndexedDB 存储历史订阅与权益变更
+
+```mermaid
+classDiagram
+class MembershipModel {
+string membershipId
+string level
+datetime expireAt
+array renewalRecords
+array privileges
+string subscriptionStatus
+saveToStorage()
+loadFromStorage()
+checkRenewalDue()
+}
+```
+
+图表来源
+- [index.html](file://index.html)
+
+章节来源
+- [index.html](file://index.html)
+
+### 数据同步机制与一致性
+- 离线优先：本地 IndexedDB 作为主存储，sessionStorage 作为缓存层
+- 在线同步：通过后端 API 接口进行双向同步，冲突解决采用时间戳与版本号
+- 一致性策略：
+  - 写入本地后立即标记为“待同步”
+  - 后台任务周期性上传，失败重试指数退避
+  - 下发变更时进行本地合并与冲突消解
+
+```mermaid
+sequenceDiagram
+participant UI as "界面"
+participant Local as "本地存储(IndexedDB)"
+participant Sync as "同步队列"
+participant API as "后端API"
+UI->>Local : 写入数据(标记待同步)
+Local-->>Sync : 入队
+Sync->>API : 上传变更
+API-->>Sync : 返回结果
+Sync->>Local : 标记已同步/更新状态
+API-->>UI : 下发最新数据(推送/拉取)
+```
+
+图表来源
+- [index.html](file://index.html)
+
+章节来源
+- [index.html](file://index.html)
+
+### 数据备份与恢复策略
+- 备份：定期导出用户数据（JSON/CSV），支持选择性导出（用户、课程、对话、会员）
+- 恢复：导入时进行格式校验与冲突检测，支持增量恢复
+- 清理：过期数据（如历史对话、过期会员）自动归档或删除
+
+```mermaid
+flowchart TD
+Start(["开始"]) --> Export["导出数据"]
+Export --> Validate{"校验格式"}
+Validate --> |通过| Save["保存到本地/云端"]
+Validate --> |失败| Fix["修复格式错误"]
+Fix --> Export
+Save --> Restore["导入数据"]
+Restore --> Merge["合并/冲突检测"]
+Merge --> Apply["应用到本地存储"]
+Apply --> End(["结束"])
+```
+
+图表来源
+- [index.html](file://index.html)
+
+章节来源
+- [index.html](file://index.html)
+
+### 数据清理规则与隐私保护
+- 清理规则：
+  - 会话结束后清理 sessionStorage
+  - 30天未登录的用户数据进行匿名化处理
+  - 过期会员数据定期归档
+- 隐私保护：
+  - 敏感字段（如手机号、支付信息）加密存储
+  - 本地不保留明文敏感数据
+  - 提供数据删除与匿名化选项
+
+章节来源
+- [index.html](file://index.html)
+
+### 数据迁移与版本升级
+- 版本管理：在本地存储中记录 schema 版本号
+- 迁移流程：
+  - 启动时检查版本，执行迁移脚本
+  - 支持回滚与增量迁移
+  - 迁移完成后更新版本号
+
+章节来源
+- [index.html](file://index.html)
+
+### 性能优化建议
+- 批量操作：将多次小写入合并为批量写入，减少索引重建
+- 索引优化：为常用查询字段建立复合索引（如用户ID+时间）
+- 内存管理：及时释放大对象引用，避免内存泄漏
+- 缓存策略：合理使用 sessionStorage 与 localStorage，避免超限
+
+章节来源
+- [index.html](file://index.html)
+
+### 数据安全考虑
+- 加密：对敏感字段进行对称加密，密钥与数据分离存储
+- 访问控制：基于用户权限与角色的最小授权原则
+- 审计日志：记录关键数据变更与访问行为，便于追踪
+
+章节来源
+- [index.html](file://index.html)
+
+## 依赖关系分析
+- 当前依赖：无外部依赖，所有逻辑内联于 index.html
+- 扩展依赖：引入 IndexedDB/Web SQL 后，需考虑浏览器兼容性与降级策略
+
+```mermaid
+graph LR
+IDX["IndexedDB API"] --> PERSIST["持久化层"]
+Sess["sessionStorage API"] --> PERSIST
+Local["localStorage API"] --> PERSIST
+PERSIST --> SYNC["同步层"]
+SYNC --> API["后端API"]
+```
+
+图表来源
+- [index.html](file://index.html)
+
+章节来源
+- [index.html](file://index.html)
+
+## 性能考量
+- 读写性能：优先使用 IndexedDB，localStorage 仅用于轻量数据
+- 网络性能：离线优先，后台异步同步，避免阻塞主线程
+- 内存占用：控制单次加载数据量，使用分页与懒加载
+
+[本节为通用指导，无需特定文件来源]
+
+## 故障排查指南
+- 常见问题：
+  - 浏览器禁用 localStorage/sessionStorage 导致状态丢失
+  - IndexedDB 不可用或存储空间不足
+  - 同步失败导致数据不一致
+- 排查步骤：
+  - 检查浏览器开发者工具的 Application/Storage 面板
+  - 查看同步队列与错误日志
+  - 验证后端 API 响应与鉴权状态
+
+章节来源
+- [index.html](file://index.html)
+
+## 结论
+当前项目为纯前端单页应用，尚未实现数据持久化。建议尽快引入 IndexedDB 作为主要存储，结合 localStorage/sessionStorage 与后端 API，构建完整的数据持久化与同步体系。同时完善备份恢复、清理规则、隐私保护与安全策略，确保用户体验与数据安全。
+
+[本节为总结，无需特定文件来源]
+
+## 附录
+- 参考实现位置：
+  - 用户状态与页面切换：[index.html](file://index.html)
+  - 聊天对话与消息渲染：[index.html](file://index.html)
+  - 行业筛选与卡片展示：[index.html](file://index.html)