MindGuard 项目开发者交接文档

字数

8059 字

阅读时间

36 分钟

文档版本: v1.0 | 创建日期: 2025-10-18 | 架构师: Winston
目标读者: 开发团队成员 | 项目状态: 从半成品到完整产品的关键增强阶段

📋 执行摘要

项目背景与目标

MindGuard 是一个面向高校场景的心理健康支持微信小程序，目前已完成基础架构搭建，处于半成品完善增强阶段。本次开发的核心目标是完成"情绪打卡 → AI建议 → 任务执行 → 社区守护"的价值闭环，将项目从半成品状态提升为生产就绪的完整产品。

已创建用户故事概览

作为架构师，我已经完成了4个关键用户故事的创建和详细规划：

Story 1.1: 完善情绪打卡系统 (3点 - 简单)
- 多情绪类型选择、强度调节、心情轮统计
- 离线缓存和数据同步机制
Story 1.2: 实现AI微建议生成工作流 (8点 - 复杂)
- Dify工作流集成、个性化建议生成、反馈闭环
- 服务降级和缓存机制
Story 1.3: 完善社区树洞核心功能 (5点 - 中等)
- 匿名发帖、风险识别、内容审核、互动功能
- 个性化推荐和关注系统
Story 1.4: 建立任务管理和执行闭环 (4点 - 中等)
- 任务创建、执行跟踪、复盘反馈、数据可视化
- 多来源任务整合

关键技术决策

架构保持: 基于现有微信小程序 + CloudBase + Dify技术栈，避免破坏性变更
数据驱动: 所有新功能都基于现有数据模型扩展，确保向后兼容
渐进增强: 采用灰度发布策略，确保现有用户体验不受影响
AI优先: 重点优化Dify工作流集成，建立完整的AI服务降级机制

🏗️ 技术架构总览

现有技术栈

层级	技术选型	关键配置	集成要求
前端	微信小程序原生 + TDesign Miniprogram	主包<2MB, 分包<1MB	保持设计语言一致性
服务层	miniprogram/services/*.js	统一{ok,data,error}格式	扩展现有服务模块
云函数	微信云开发 CloudBase	环境: cloud1-9gpfk3ie94d8630a	复用现有7个云函数
数据库	微信云数据库 NoSQL	现有16个核心集合	新增字段向后兼容
AI服务	Dify工作流平台	需要降级和缓存机制	确保响应时间<5秒

核心架构约束

性能要求:
- 基础操作响应时间 < 2秒
- AI生成内容响应时间 < 5秒
- 支持至少1000并发用户
安全合规:
- 遵循P0-P3隐私分级制度
- 所有敏感数据必须加密存储
- SOS功能必须保证100%可用性
兼容性要求:
- 保持现有API接口向后兼容
- 数据库模式变更支持平滑迁移
- TDesign设计语言一致性

分包规划策略

主包 (pages/) - <2MB
├── today/ - 情绪打卡和微建议 (需扩展)
├── tasks/ - 任务管理 (需扩展)
├── treehole/ - 社区入口 (需扩展)
├── journal/ - 日记功能 (需扩展)
└── mine/ - 个人中心 (需扩展)

普通分包 (packages/) - <1MB each
├── community/ - 社区详情 (重点扩展)
├── journal/ - 日记详情 (扩展)
├── profile/ - 个人资料 (扩展)
└── tasks/ - 任务详情 (新增)

独立分包 (independent/) - 独立加载
├── sos/ - 紧急求助 (保持现有)
└── heartchat/ - AI对话 (保持现有)

📊 数据模型集成指导

现有数据库集合概览

集合名	主要用途	本次变更	兼容性要求
`users`	用户基础资料	扩展统计字段	✅ 完全兼容
`checkins`	情绪打卡	新增字段: mood_intensity, energy_level	✅ 向后兼容
`suggestions`	微建议系统	新增集合	✅ 无影响
`tasks`	任务管理	新增集合	✅ 无影响
`posts`	树洞帖子	新增集合	✅ 无影响
`comments`	社区互动	新增集合	✅ 无影响
`badges`	徽章成就	扩展进度字段	✅ 完全兼容

新增数据模型详细设计

1. CHECKINS集合扩展

新增字段:

javascript

{
  // 现有字段保持不变...
  "mood_intensity": Number,     // 1-5级情绪强度 (新增)
  "energy_level": Number,       // 0-5级能量指数 (新增)
  "primary_emotion": String,    // 主情绪类别枚举 (新增)
  "suggestion_ids": Array,      // 关联建议ID列表 (新增)
  "checkin_count": Number       // 当日打卡次数 (新增)
}

数据迁移策略:

为现有记录设置默认值: mood_intensity=3, energy_level=3
使用云函数批量更新现有数据
添加复合索引: user_id_1_checkin_date_-1

2. SUGGESTIONS集合 (新增)

javascript

{
  "_id": String,                // 建议唯一ID
  "user_id": String,            // 用户ID
  "session_id": String,         // 推荐会话ID
  "title": String,              // 建议标题
  "description": String,        // 建议描述
  "category": String,           // 建议分类
  "priority_rank": Number,      // 当前排序
  "source": String,             // 来源 (model/curated/manual)
  "status": String,             // 状态 (active/accepted/skipped/expired)
  "accepted_task_id": String,   // 接受后生成的任务ID
  "expired_at": Date,           // 失效时间
  "createdAt": Date,
  "updatedAt": Date
}

3. TASKS集合 (新增)

javascript

{
  "_id": String,                     // 任务唯一ID
  "user_id": String,                 // 用户ID
  "title": String,                   // 任务标题
  "description": String,             // 任务描述
  "source": String,                  // 来源分类
  "origin_reference_type": String,   // 来源实体类型
  "origin_reference_id": String,     // 来源实体ID
  "category": String,                // 任务分类
  "status": String,                  // 任务状态
  "due_at": Date,                    // 截止时间
  "priority": String,                // 优先级
  "linked_checkin_id": String,       // 完成回执关联
  "review_data": Object,             // 复盘数据
  "pomodoro_sessions": Array,        // 番茄计时记录
  "createdAt": Date,
  "updatedAt": Date
}

4. POSTS集合 (新增)

javascript

{
  "_id": String,                 // 帖子唯一ID
  "user_id": String,             // 用户ID
  "alias_name": String,          // 匿名展示名
  "anonymity_mode": String,      // 匿名模式
  "content": String,             // 帖子内容
  "tags": Array,                 // 主题标签
  "topic": String,               // 话题分类
  "mood_thermometer": Number,    // 情绪温度
  "risk_score": Number,          // 风险模型分值
  "risk_level": String,          // 风险等级
  "status": String,              // 发布状态
  "action_card_id": String,      // 行动卡引用
  "hug_count": Number,           // 抱抱数
  "comment_count": Number,       // 评论数
  "content_hash": String,        // 内容哈希
  "publishedAt": Date,
  "createdAt": Date,
  "updatedAt": Date
}

数据库索引优化策略

新增复合索引:

javascript

// checkins集合
{ "user_id": 1, "checkin_date": -1 }           // 用户情绪历史
{ "risk_level": 1, "user_id": 1 }               // 风险用户识别
{ "primary_emotion": 1, "created_at": -1 }      // 情绪分析

// suggestions集合
{ "user_id": 1, "session_id": 1, "priority_rank": 1 }  // 会话内查询
{ "status": 1, "user_id": 1, "created_at": -1 }         // 状态追踪

// tasks集合
{ "user_id": 1, "status": 1, "due_at": 1 }              // 任务看板
{ "origin_reference_type": 1, "origin_reference_id": 1 } // 来源追踪

// posts集合
{ "topic": 1, "status": 1, "publishedAt": -1 }          // 话题筛选
{ "risk_level": 1, "status": 1 }                        // 风险内容识别

🔧 API集成与服务扩展

服务层扩展指导原则

保持现有格式: 所有API返回必须维持 { ok, data, error } 格式
Mock数据对齐: 新增Mock数据必须与真实API格式完全一致
错误处理统一: 遵循现有错误处理和日志记录规范
向后兼容: 新增参数必须有默认值，避免破坏现有调用

核心服务层扩展

1. checkins.js 服务扩展

新增方法:

javascript

// 扩展现有createCheckin方法
async function createCheckin(payload) {
  // 支持新增字段: mood_intensity, energy_level, primary_emotion
  // 保持向后兼容，为新字段设置默认值
}

// 新增方法
async function getMoodWheelData(userId, timeRange) {
  // 获取心情轮统计数据
}

async function getTodayCheckinSummary(userId) {
  // 获取今日打卡汇总，包含建议关联
}

Mock数据更新:

javascript

const MOCK_CHECKIN_DATA = {
  // 现有字段保持不变
  mood_intensity: 4,
  energy_level: 3,
  primary_emotion: 'calm',
  suggestion_ids: ['sg_001', 'sg_002']
};

2. suggestions.js 服务扩展

完整实现 (从基础服务扩展为完整功能):

javascript

async function getTodaySuggestions(userId) {
  // 集成Dify API调用
  // 实现缓存机制
  // 支持降级处理
}

async function acceptSuggestion(suggestionId, userId) {
  // 接受建议并创建关联任务
  // 更新建议状态
}

async function submitFeedback(suggestionId, feedback) {
  // 提交建议质量反馈
  // 更新模型优化数据
}

async function refreshSuggestions(userId) {
  // 刷新建议列表
  // 控制刷新频率
}

3. tasks.js 服务扩展

完整实现 (从基础服务扩展为完整功能):

javascript

async function createTaskFromSuggestion(suggestionId, userId) {
  // 从建议创建任务
  // 设置任务来源和关联
}

async function updateTaskStatus(taskId, status, userId) {
  // 更新任务状态
  // 触发相关通知
}

async function startTaskTimer(taskId, userId) {
  // 开始番茄计时
  // 记录计时会话
}

async function completeTask(taskId, reviewData, userId) {
  // 完成任务并提交复盘
  // 更新成就和徽章
}

async function getTaskSummary(userId, timeRange) {
  // 获取任务统计和洞察
}

4. forum.js 服务扩展

完整实现 (从基础服务扩展为完整功能):

javascript

async function publishPost(postData, userId) {
  // 发布帖子，包含风险自检
  // 触发审核流程
}

async function assessContentRisk(content) {
  // 内容风险评估
  // 集成AI风险识别
}

async function submitComment(commentData, userId) {
  // 提交评论
  // 更新帖子互动统计
}

async function toggleInteraction(postId, interactionType, userId) {
  // 互动操作 (抱抱、收藏等)
}

云函数集成规范

1. suggestionOrchestrator 云函数扩展

主要action扩展:

javascript

exports.main = async (event, context) => {
  const { action, payload } = event;

  switch (action) {
    case 'generate':
      return await generateSuggestions(payload);
    case 'updateFeedback':
      return await updateSuggestionFeedback(payload);
    case 'refresh':
      return await refreshSuggestions(payload);
    case 'analyzePerformance':
      return await analyzeSuggestionPerformance(payload);
    default:
      return { ok: false, error: 'Unknown action' };
  }
};

Dify集成要求:

实现API调用超时控制 (5秒)
添加重试机制和降级策略
缓存常见情绪组合的建议结果

2. taskWorkflow 云函数实现

核心功能:

javascript

// 任务CRUD操作
async function createTask(taskData) { /* ... */ }
async function updateTask(taskId, updateData) { /* ... */ }
async function deleteTask(taskId) { /* ... */ }

// 任务状态流转
async function startTask(taskId) { /* ... */ }
async function completeTask(taskId, reviewData) { /* ... */ }
async function pauseTask(taskId) { /* ... */ }

// 任务统计和分析
async function getTaskStats(userId, timeRange) { /* ... */ }
async function generateTaskReport(userId) { /* ... */ }

3. treeholeModeration 云函数实现

核心功能:

javascript

// 风险识别和评估
async function assessContentRisk(content) { /* ... */ }
async function calculateRiskScore(content, metadata) { /* ... */ }

// 内容审核
async function moderateContent(postId, decision) { /* ... */ }
async function processReport(reportData) { /* ... */ }

// 推荐算法
async function getRecommendedPosts(userId, filters) { /* ... */ }
async function updatePostRecommendations(postId) { /* ... */ }

🎨 前端组件开发指导

TDesign组件使用规范

设计系统一致性: 严格遵循TDesign Miniprogram设计规范
主题定制: 使用项目统一主题配置，避免自定义样式
组件封装: 复杂UI应封装为自定义组件，保持页面简洁
响应式设计: 确保在不同屏幕尺寸下的适配

核心组件开发指导

1. 情绪打卡组件 (emotion-picker)

文件位置: miniprogram/components/emotion-picker/

核心功能:

javascript

// emotion-picker/index.js
Component({
  properties: {
    visible: Boolean,
    defaultMood: Number,
    defaultIntensity: Number
  },

  methods: {
    onEmotionSelect(e) {
      // 情绪选择处理
    },

    onIntensityChange(e) {
      // 强度调节处理
    },

    onTagSelect(e) {
      // 标签选择处理
    },

    onSubmit() {
      // 提交打卡数据
      this.triggerEvent('submit', {
        mood_score: this.data.mood_score,
        mood_intensity: this.data.intensity,
        primary_emotion: this.data.emotion,
        tags: this.data.selectedTags
      });
    }
  }
});

TDesign组件使用:

xml

<!-- emotion-picker/index.wxml -->
<t-popup visible="{{visible}}" placement="bottom" bind:visible-change="onVisibleChange">
  <view class="emotion-picker">
    <t-slider value="{{intensity}}" min="1" max="5" step="1" bind:change="onIntensityChange" />
    <t-tag-group>
      <t-tag v-for="tag in tags" :key="tag" theme="primary" @click="onTagSelect">{{tag}}</t-tag>
    </t-tag-group>
    <t-button theme="primary" bind:click="onSubmit">提交打卡</t-button>
  </view>
</t-popup>

2. 建议卡片组件 (suggestion-card)

文件位置: miniprogram/components/suggestion-card/

核心功能:

javascript

// suggestion-card/index.js
Component({
  properties: {
    suggestion: Object,
    showActions: Boolean
  },

  methods: {
    onAccept() {
      // 接受建议，创建任务
      this.triggerEvent('accept', { suggestionId: this.data.suggestion._id });
    },

    onSkip() {
      // 跳过建议
      this.triggerEvent('skip', { suggestionId: this.data.suggestion._id });
    },

    onFavorite() {
      // 收藏建议
      this.triggerEvent('favorite', { suggestionId: this.data.suggestion._id });
    },

    onFeedback() {
      // 提交反馈
      this.triggerEvent('feedback', { suggestionId: this.data.suggestion._id });
    }
  }
});

3. 任务卡片组件 (task-card)

文件位置: miniprogram/components/task-card/

核心功能:

javascript

// task-card/index.js
Component({
  properties: {
    task: Object,
    showTimer: Boolean
  },

  methods: {
    onStartTask() {
      // 开始任务
      this.triggerEvent('start', { taskId: this.data.task._id });
    },

    onPauseTask() {
      // 暂停任务
      this.triggerEvent('pause', { taskId: this.data.task._id });
    },

    onCompleteTask() {
      // 完成任务
      this.triggerEvent('complete', { taskId: this.data.task._id });
    },

    onShowDetail() {
      // 显示任务详情
      this.triggerEvent('detail', { taskId: this.data.task._id });
    }
  }
});

4. 番茄计时器组件 (tomato-timer)

文件位置: miniprogram/components/tomato-timer/

核心功能:

javascript

// tomato-timer/index.js
Component({
  properties: {
    taskId: String,
    duration: Number,
    isRunning: Boolean
  },

  data: {
    remainingTime: 0,
    isPaused: false
  },

  methods: {
    startTimer() {
      // 开始计时
      this.setData({ isRunning: true, isPaused: false });
      this.timer = setInterval(() => {
        if (this.data.remainingTime > 0) {
          this.setData({ remainingTime: this.data.remainingTime - 1 });
        } else {
          this.completeTimer();
        }
      }, 1000);
    },

    pauseTimer() {
      // 暂停计时
      this.setData({ isPaused: true });
      clearInterval(this.timer);
    },

    completeTimer() {
      // 完成计时
      clearInterval(this.timer);
      this.setData({ isRunning: false });
      this.triggerEvent('complete', { taskId: this.data.taskId });
    }
  }
});

页面集成示例

今天页面 (pages/today/index.js) 集成

javascript

// pages/today/index.js
const checkinsService = require('../../services/checkins.js');
const suggestionsService = require('../../services/suggestions.js');

Page({
  data: {
    todayCheckin: null,
    suggestions: [],
    moodWheelData: []
  },

  async onLoad() {
    await this.loadTodayData();
  },

  async loadTodayData() {
    try {
      // 加载今日打卡
      const todayCheckin = await checkinsService.getTodayCheckin();

      // 加载今日建议
      const suggestions = await suggestionsService.getTodaySuggestions();

      // 加载心情轮数据
      const moodWheelData = await checkinsService.getMoodWheelData('week');

      this.setData({
        todayCheckin,
        suggestions,
        moodWheelData
      });
    } catch (error) {
      console.error('加载今日数据失败:', error);
    }
  },

  onEmotionCheckinSubmit(e) {
    const checkinData = e.detail;
    this.submitCheckin(checkinData);
  },

  async submitCheckin(checkinData) {
    try {
      const result = await checkinsService.createCheckin(checkinData);
      if (result.ok) {
        // 重新加载建议
        await this.loadTodayData();
        wx.showToast({ title: '打卡成功', icon: 'success' });
      }
    } catch (error) {
      wx.showToast({ title: '打卡失败', icon: 'error' });
    }
  },

  onSuggestionAccept(e) {
    const { suggestionId } = e.detail;
    this.acceptSuggestion(suggestionId);
  },

  async acceptSuggestion(suggestionId) {
    try {
      const result = await suggestionsService.acceptSuggestion(suggestionId);
      if (result.ok) {
        await this.loadTodayData();
        wx.showToast({ title: '已创建任务', icon: 'success' });
      }
    } catch (error) {
      wx.showToast({ title: '创建任务失败', icon: 'error' });
    }
  }
});

🧪 测试策略与质量保证

测试架构设计

1. 单元测试

测试框架: Jest 文件位置: miniprogram/services/__tests__/

测试覆盖要求:

服务层函数覆盖率 ≥ 80%
云函数核心逻辑覆盖率 ≥ 80%
工具函数覆盖率 ≥ 90%

示例测试文件:

javascript

// miniprogram/services/__tests__/checkins.test.js
const checkinsService = require('../checkins.js');

describe('checkinsService', () => {
  describe('createCheckin', () => {
    it('should create checkin with new fields', async () => {
      const mockData = {
        mood_score: 75,
        mood_intensity: 4,
        energy_level: 3,
        primary_emotion: 'calm'
      };

      const result = await checkinsService.createCheckin(mockData);

      expect(result.ok).toBe(true);
      expect(result.data.mood_intensity).toBe(4);
      expect(result.data.energy_level).toBe(3);
    });

    it('should handle missing new fields with defaults', async () => {
      const mockData = {
        mood_score: 75
        // 缺少新增字段
      };

      const result = await checkinsService.createCheckin(mockData);

      expect(result.ok).toBe(true);
      expect(result.data.mood_intensity).toBe(3); // 默认值
      expect(result.data.energy_level).toBe(3);  // 默认值
    });
  });
});

2. 集成测试

测试范围:

情绪打卡 → 建议生成 → 任务创建完整流程
社区发帖 → 风险识别 → 审核处理流程
数据库事务一致性测试

示例集成测试:

javascript

// __tests__/integration/emotion-suggestion-task.test.js
describe('Emotion to Task Flow', () => {
  it('should complete emotion-checkin to task-creation flow', async () => {
    // 1. 创建情绪打卡
    const checkinData = {
      mood_score: 65,
      primary_emotion: 'anxious'
    };
    const checkinResult = await checkinsService.createCheckin(checkinData);
    expect(checkinResult.ok).toBe(true);

    // 2. 获取生成的建议
    const suggestions = await suggestionsService.getTodaySuggestions();
    expect(suggestions.length).toBeGreaterThan(0);

    // 3. 接受建议创建任务
    const taskResult = await suggestionsService.acceptSuggestion(suggestions[0]._id);
    expect(taskResult.ok).toBe(true);
    expect(taskResult.data.source).toBe('suggestion');

    // 4. 验证任务与打卡的关联
    const task = await tasksService.getTaskDetail(taskResult.data._id);
    expect(task.data.linked_checkin_id).toBe(checkinResult.data._id);
  });
});

3. 端到端测试

测试工具: 微信开发者工具自动化测试 测试场景:

完整用户旅程测试
性能基准测试
兼容性测试

4. AI服务测试

Dify集成测试:

javascript

// __tests__/integration/dify-api.test.js
describe('Dify API Integration', () => {
  it('should generate suggestions within timeout', async () => {
    const startTime = Date.now();

    const result = await suggestionOrchestrator.generateSuggestions({
      user_id: 'test_user',
      mood_data: { score: 60, emotion: 'anxious' }
    });

    const duration = Date.now() - startTime;
    expect(duration).toBeLessThan(5000); // 5秒超时
    expect(result.ok).toBe(true);
    expect(result.data.suggestions).toBeDefined();
  });

  it('should handle Dify API failure gracefully', async () => {
    // 模拟API失败
    const result = await suggestionOrchestrator.generateSuggestions({
      user_id: 'test_user',
      mood_data: { score: 60, emotion: 'anxious' },
      useMock: true // 强制使用Mock数据
    });

    expect(result.ok).toBe(true);
    expect(result.data.source).toBe('mock');
  });
});

性能测试要求

1. 响应时间基准

操作类型	目标时间	测试方法
情绪打卡提交	< 2秒	自动化测试
建议生成	< 5秒	API测试
任务状态更新	< 1秒	单元测试
页面加载	< 2秒	性能监控

2. 并发测试

测试场景:

1000并发用户情绪打卡
500并发用户社区发帖
200并发用户任务操作

测试工具: Artillery + 自定义脚本

质量门禁标准

代码质量:
- ESLint检查通过率 100%
- 代码覆盖率 ≥ 80%
- 所有PR必须通过Code Review
性能标准:
- 页面加载时间 < 2秒
- API响应时间符合基准要求
- 内存使用量增长 < 10%
安全标准:
- 所有用户输入验证
- 敏感数据加密存储
- 权限控制测试通过

🚀 部署与运维指导

部署策略

1. 渐进式发布

阶段1: 内部测试 (Day 1-2)

开发团队内部测试
核心功能验证
性能基准测试

阶段2: 灰度发布 (Day 3-4)

10%用户流量
监控关键指标
收集用户反馈

阶段3: 全量发布 (Day 5+)

100%用户流量
持续监控
快速响应机制

2. 数据库迁移

迁移脚本示例:

javascript

// cloudfunctions/database-migration/index.js
exports.main = async (event, context) => {
  const db = cloud.database();

  // 为checkins集合添加新字段
  try {
    // 获取所有需要更新的记录
    const checkins = await db.collection('checkins').get();

    // 批量更新
    const batch = db.startBatch();
    checkins.data.forEach(checkin => {
      batch.doc(checkin._id).update({
        mood_intensity: checkin.mood_intensity || 3,
        energy_level: checkin.energy_level || 3,
        primary_emotion: checkin.primary_emotion || 'calm'
      });
    });

    await batch.commit();

    // 创建索引
    await db.collection('checkins').createIndex({
      user_id: 1,
      checkin_date: -1
    });

    return { ok: true, message: 'Migration completed successfully' };
  } catch (error) {
    return { ok: false, error: error.message };
  }
};

3. 云函数部署

部署顺序:

数据库迁移脚本
核心云函数 (suggestionOrchestrator, taskWorkflow, treeholeModeration)
前端代码更新
配置更新和监控设置

监控与告警

1. 关键指标监控

业务指标:

情绪打卡完成率
建议接受率
任务完成率
社区互动频率

技术指标:

API响应时间
错误率
数据库查询性能
内存使用情况

2. 告警配置

告警规则:

javascript

// 示例告警配置
const alertRules = {
  'api_response_time': {
    threshold: 5000, // 5秒
    window: '5m',
    action: 'notify_team'
  },
  'error_rate': {
    threshold: 0.05, // 5%
    window: '10m',
    action: 'rollback_deployment'
  },
  'suggestion_generation_failure': {
    threshold: 0.1, // 10%
    window: '5m',
    action: 'switch_to_mock'
  }
};

3. 日志管理

日志格式:

javascript

// 统一日志格式
const logger = {
  info: (message, context = {}) => {
    console.log(JSON.stringify({
      level: 'INFO',
      timestamp: new Date().toISOString(),
      message,
      context,
      trace_id: generateTraceId()
    }));
  },

  error: (message, error, context = {}) => {
    console.error(JSON.stringify({
      level: 'ERROR',
      timestamp: new Date().toISOString(),
      message,
      error: error.message,
      stack: error.stack,
      context,
      trace_id: generateTraceId()
    }));
  }
};

回滚策略

1. 快速回滚机制

前端回滚:

微信小程序版本回退
分包配置回退
静态资源回退

后端回滚:

云函数版本回退
数据库配置回退
环境变量回退

2. 数据恢复

备份策略:

数据库每日自动备份
关键操作前手动备份
备份验证机制

恢复流程:

javascript

// 数据恢复脚本示例
async function restoreDatabase(backupId) {
  try {
    // 1. 停止写入操作
    await setMaintenanceMode(true);

    // 2. 恢复数据库
    const restoreResult = await restoreFromBackup(backupId);

    // 3. 验证数据完整性
    const integrityCheck = await verifyDataIntegrity();

    if (integrityCheck.passed) {
      // 4. 恢复服务
      await setMaintenanceMode(false);
      return { ok: true, message: 'Database restored successfully' };
    } else {
      throw new Error('Data integrity check failed');
    }
  } catch (error) {
    await setMaintenanceMode(false);
    return { ok: false, error: error.message };
  }
}

🔒 安全与合规指导

数据安全要求

1. 隐私分级实施

P0级 (公开):

基础配置信息
应用版本信息

P1级 (基础):

用户昵称、头像
非敏感统计数据

P2级 (敏感):

用户行为数据
任务状态信息
社区互动记录

P3级 (高敏):

情绪打卡数据
心情随笔内容
SOS求助信息

2. 数据加密策略

字段级加密:

javascript

// 敏感字段加密示例
const crypto = require('crypto');

function encryptSensitiveData(data, key) {
  const algorithm = 'aes-256-gcm';
  const iv = crypto.randomBytes(16);
  const cipher = crypto.createCipher(algorithm, key);

  let encrypted = cipher.update(JSON.stringify(data), 'utf8', 'hex');
  encrypted += cipher.final('hex');

  const authTag = cipher.getAuthTag();

  return {
    encrypted,
    iv: iv.toString('hex'),
    authTag: authTag.toString('hex')
  };
}

传输加密:

所有API调用使用HTTPS
微信小程序内置安全传输
敏感数据额外加密

3. 访问控制

权限验证:

javascript

// 云函数权限验证示例
exports.main = async (event, context) => {
  const { OPENID } = cloud.getWXContext();

  // 验证用户身份
  const user = await db.collection('users').where({
    _openid: OPENID
  }).get();

  if (!user.data.length) {
    return { ok: false, error: 'User not found' };
  }

  // 验证数据访问权限
  if (event.user_id && event.user_id !== user.data[0]._id) {
    return { ok: false, error: 'Access denied' };
  }

  // 继续处理请求...
};

内容安全

1. 内容审核

自动审核:

微信内容安全API
敏感词过滤
AI风险评估

人工审核:

高风险内容标记
审核工作台
处理流程追踪

2. 风险识别

风险等级定义:

javascript

const RISK_LEVELS = {
  L1: { // 一般风险
    score: 0.0 - 0.3,
    action: 'auto_approve',
    description: '正常内容'
  },
  L2: { // 需要关注
    score: 0.3 - 0.6,
    action: 'review_required',
    description: '需要人工审核'
  },
  L3: { // 需要干预
    score: 0.6 - 0.8,
    action: 'immediate_review',
    description: '高风险内容，需要立即处理'
  },
  L4: { // 紧急危机
    score: 0.8 - 1.0,
    action: 'sos_trigger',
    description: '危机情况，触发SOS流程'
  }
};

合规要求

1. 数据保护合规

用户授权:

javascript

// 隐私授权管理
const privacyManager = {
  checkConsent: async (userId, dataType) => {
    const user = await db.collection('users').doc(userId).get();
    const consent = user.data.consent_version;

    // 检查用户是否同意特定数据处理
    const consentConfig = await getConsentConfig(consent);
    return consentConfig[dataType] || false;
  },

  updateConsent: async (userId, consentData) => {
    return await db.collection('users').doc(userId).update({
      consent_version: consentData.version,
      consent_data: consentData,
      updated_at: new Date()
    });
  }
};

数据导出与删除:

javascript

// GDPR合规接口
exports.main = async (event, context) => {
  const { action, user_id } = event;

  switch (action) {
    case 'export':
      return await exportUserData(user_id);
    case 'delete':
      return await deleteUserData(user_id);
    default:
      return { ok: false, error: 'Invalid action' };
  }
};

2. 未成年人保护

特殊保护措施:

年龄验证机制
家长监护功能
内容过滤强化
使用时间限制

📈 下一步开发工作流

开发优先级与时间线

第1周: 基础功能完善

重点: Story 1.1 (情绪打卡系统)

扩展情绪打卡UI组件
实现数据模型扩展
完成心情轮统计功能
基础测试覆盖

第2周: AI核心功能

重点: Story 1.2 (AI微建议生成)

Dify工作流集成
建议生成算法优化
服务降级机制实现
性能测试与优化

第3周: 社区功能

重点: Story 1.3 (社区树洞功能)

发帖功能实现
风险识别算法
内容审核机制
互动功能开发

第4周: 任务闭环

重点: Story 1.4 (任务管理闭环)

任务创建与管理
执行跟踪功能
复盘反馈系统
数据可视化

第5周: 测试与发布

重点: 端到端测试与发布准备

完整功能测试
性能优化
安全审查
发布准备

团队协作规范

1. 代码管理

分支策略:

bash

# 主分支
main - 生产环境代码
develop - 开发环境代码

# 功能分支
feature/emotion-checkin - 情绪打卡功能
feature/ai-suggestions - AI建议功能
feature/community - 社区功能
feature/tasks - 任务管理功能

# 发布分支
release/v1.0 - 版本发布分支
hotfix/critical-bug - 紧急修复分支

提交规范:

bash

# 提交格式
<type>(<scope>): <subject>

# 示例
feat(emotion): 添加情绪强度滑块功能
fix(suggestion): 修复建议生成超时问题
docs(api): 更新API文档
test(tasks): 添加任务管理单元测试

2. 代码审查

审查清单:

[ ] 代码符合项目规范
[ ] 测试覆盖率达标
[ ] 性能影响评估
[ ] 安全性检查
[ ] 向后兼容性验证
[ ] 文档更新完整

3. 沟通机制

每日站会:

功能开发进度
遇到的阻碍
今日工作计划
需要协助的问题

周度回顾:

完成功能总结
质量指标回顾
下周计划调整
风险评估更新

质量保证流程

1. 开发阶段

编码规范:

ESLint配置强制执行
代码格式化统一
注释规范完整
错误处理完善

单元测试:

TDD开发模式
测试驱动开发
覆盖率监控
持续集成

2. 测试阶段

功能测试:

用户故事验收
边界条件测试
异常情况处理
用户体验验证

集成测试:

模块间接口测试
数据一致性验证
性能基准测试
安全性测试

3. 发布阶段

预发布验证:

完整功能测试
数据迁移验证
性能压力测试
用户验收测试

发布监控:

实时性能监控
错误日志追踪
用户反馈收集
快速响应机制

🎯 成功标准与验收条件

功能验收标准

Story 1.1: 情绪打卡系统

[ ] 支持多种情绪类型选择 (至少6种基础情绪)
[ ] 情绪强度调节功能正常 (1-5级)
[ ] 心情轮统计准确展示 (周/月视图)
[ ] 离线缓存机制正常工作
[ ] 数据同步机制稳定可靠

Story 1.2: AI微建议生成

[ ] Dify工作流集成成功
[ ] 建议生成时间 < 5秒
[ ] 建议内容质量评分 > 3.5/5
[ ] 反馈机制完整可用
[ ] 服务降级机制有效

Story 1.3: 社区树洞功能

[ ] 匿名发帖功能正常
[ ] 风险识别准确率 > 85%
[ ] 内容审核流程完整
[ ] 互动功能响应及时
[ ] 个性化推荐有效

Story 1.4: 任务管理闭环

[ ] 任务创建流程顺畅
[ ] 执行跟踪准确完整
[ ] 复盘反馈机制有效
[ ] 数据统计准确
[ ] 与其他模块集成良好

技术验收标准

性能指标

[ ] 页面加载时间 < 2秒
[ ] API响应时间符合基准
[ ] 并发支持 ≥ 1000用户
[ ] 内存使用稳定
[ ] 数据库查询优化

质量指标

[ ] 代码覆盖率 ≥ 80%
[ ] 错误率 < 0.1%
[ ] 安全扫描通过
[ ] 用户满意度 > 4.0/5.0
[ ] 崩溃率 < 0.01%

安全指标

[ ] 数据加密率 100%
[ ] 权限控制严格
[ ] 内容安全审核通过
[ ] 隐私合规达标
[ ] SOS功能100%可用

业务验收标准

用户体验

[ ] 功能完整性验证
[ ] 界面交互流畅
[ ] 错误提示友好
[ ] 引导说明清晰
[ ] 响应式设计适配

数据完整性

[ ] 数据流转正确
[ ] 关联关系准确
[ ] 统计数据一致
[ ] 备份恢复有效
[ ] 迁移过程平滑

📞 支持与联系

技术支持资源

文档资源

项目架构文档: CLAUDE.md
数据库设计: docs/数据库设计.md
API接口文档: docs/接口占位文档.md
用户故事详情: docs/stories/ 目录

工具与资源

微信开发者工具: 最新版本
CloudBase控制台: 环境管理
Dify工作流平台: AI服务配置
代码仓库: Git版本控制

问题反馈渠道

技术问题

优先级P0: 立即联系架构师
优先级P1: 项目群内讨论
优先级P2: GitHub Issues
优先级P3: 定期回顾讨论

业务问题

需求变更: 产品经理确认
用户反馈: 收集并分析
性能问题: 技术团队处理
安全问题: 立即响应

持续改进机制

定期回顾

周度技术回顾: 每周五下午
双周产品回顾: 每两周一次
月度战略回顾: 每月一次
季度业务回顾: 每季度一次

反馈收集

用户体验反馈: 应用内收集
开发团队反馈: 内部讨论
运维监控反馈: 自动化监控
业务数据反馈: 数据分析

📚 附录

关键术语表

术语	定义	英文
情绪打卡	用户记录当前情绪状态的功能	Mood Check-in
微建议	基于情绪状态生成的个性化建议	Micro-suggestions
心情轮	情绪状态的可视化图表	Mood Wheel
树洞社区	匿名心理支持社区	Treehole Community
任务闭环	从建议到执行到反馈的完整流程	Task Loop
REBT疗法	理性情绪行为疗法	REBT Therapy
SOS求助	紧急心理危机干预	SOS Emergency
心语精灵	AI对话助手系统	HeartChat AI
抱抱功能	社区支持互动功能	Hug Feature
行动卡	从社区内容生成的行动建议	Action Card

技术栈详细说明

前端技术栈

微信小程序 (基础库 2.32+)
├── TDesign Miniprogram v1.0+
├── JavaScript ES6+
├── WXML/WXSS
└── 组件化开发

后端技术栈

微信云开发 CloudBase
├── 云函数 (Node.js 16.x)
├── 云数据库 (NoSQL)
├── 云存储
└── 云调用

AI服务集成

Dify 工作流平台
├── 情绪分析工作流
├── 建议生成工作流
├── 风险评估工作流
└── 对话管理工作流

常用命令速查

开发环境启动

bash

# 启动微信开发者工具
# 项目路径: D:\Code\MindGuard

# 安装依赖
cd miniprogram && npm install

# 云函数本地调试
# 在微信开发者工具中开启云开发本地调试

数据库管理

javascript

// 查询数据
db.collection('collection_name').where({}).get()

// 插入数据
db.collection('collection_name').add({ data: {} })

// 更新数据
db.collection('collection_name').doc('id').update({ data: {} })

// 删除数据
db.collection('collection_name').doc('id').remove()

云函数调试

javascript

// 云函数本地调试
// 在微信开发者工具中右键云函数 -> 本地调试

// 云函数上传部署
// 右键云函数 -> 上传并部署：云端安装依赖

版本发布流程

发布前检查清单

[ ] 所有测试通过
[ ] 代码审查完成
[ ] 文档更新完整
[ ] 数据库迁移脚本准备
[ ] 监控配置就绪
[ ] 回滚方案准备
[ ] 团队沟通完成

发布步骤

代码合并: 合并到release分支
数据库迁移: 执行迁移脚本
云函数部署: 更新所有云函数
前端构建: 构建小程序代码
灰度发布: 10%用户流量测试
全量发布: 100%用户流量
监控验证: 确认所有指标正常

发布后验证

[ ] 核心功能正常
[ ] 性能指标达标
[ ] 错误率正常
[ ] 用户反馈良好
[ ] 监控告警正常

文档维护: 本文档随项目进展持续更新，如有疑问或建议，请联系架构师团队。

最后更新: 2025-10-18 文档版本: v1.0 下次更新: 根据开发进展和反馈持续更新

贡献者

Cai Hongyu

文件历史

最后编辑于 4 个月前查看完整历史

MindGuard 项目开发者交接文档 ​

📋 执行摘要 ​

项目背景与目标 ​

已创建用户故事概览 ​

关键技术决策 ​

🏗️ 技术架构总览 ​

现有技术栈 ​

核心架构约束 ​

分包规划策略 ​

📊 数据模型集成指导 ​

现有数据库集合概览 ​

新增数据模型详细设计 ​

1. CHECKINS集合扩展 ​

2. SUGGESTIONS集合 (新增) ​

3. TASKS集合 (新增) ​

4. POSTS集合 (新增) ​

数据库索引优化策略 ​

🔧 API集成与服务扩展 ​

服务层扩展指导原则 ​

核心服务层扩展 ​

1. checkins.js 服务扩展 ​

2. suggestions.js 服务扩展 ​

3. tasks.js 服务扩展 ​

4. forum.js 服务扩展 ​

云函数集成规范 ​

1. suggestionOrchestrator 云函数扩展 ​

2. taskWorkflow 云函数实现 ​

3. treeholeModeration 云函数实现 ​

🎨 前端组件开发指导 ​

TDesign组件使用规范 ​

核心组件开发指导 ​

1. 情绪打卡组件 (emotion-picker) ​

2. 建议卡片组件 (suggestion-card) ​

3. 任务卡片组件 (task-card) ​

4. 番茄计时器组件 (tomato-timer) ​

页面集成示例 ​

今天页面 (pages/today/index.js) 集成 ​

🧪 测试策略与质量保证 ​

测试架构设计 ​

1. 单元测试 ​

2. 集成测试 ​

3. 端到端测试 ​

4. AI服务测试 ​

性能测试要求 ​

1. 响应时间基准 ​

2. 并发测试 ​

质量门禁标准 ​

🚀 部署与运维指导 ​

部署策略 ​

1. 渐进式发布 ​

2. 数据库迁移 ​

3. 云函数部署 ​

监控与告警 ​

1. 关键指标监控 ​

2. 告警配置 ​

3. 日志管理 ​

回滚策略 ​

1. 快速回滚机制 ​

2. 数据恢复 ​

🔒 安全与合规指导 ​

数据安全要求 ​

1. 隐私分级实施 ​

2. 数据加密策略 ​

3. 访问控制 ​

内容安全 ​

1. 内容审核 ​

2. 风险识别 ​

合规要求 ​

1. 数据保护合规 ​

2. 未成年人保护 ​

📈 下一步开发工作流 ​

开发优先级与时间线 ​

第1周: 基础功能完善 ​

第2周: AI核心功能 ​

第3周: 社区功能 ​

第4周: 任务闭环 ​

第5周: 测试与发布 ​

团队协作规范 ​

1. 代码管理 ​

2. 代码审查 ​

MindGuard 项目开发者交接文档

📋 执行摘要

项目背景与目标

已创建用户故事概览

关键技术决策

🏗️ 技术架构总览

现有技术栈

核心架构约束

分包规划策略

📊 数据模型集成指导

现有数据库集合概览

新增数据模型详细设计

1. CHECKINS集合扩展

2. SUGGESTIONS集合 (新增)

3. TASKS集合 (新增)

4. POSTS集合 (新增)

数据库索引优化策略

🔧 API集成与服务扩展

服务层扩展指导原则

核心服务层扩展

1. checkins.js 服务扩展

2. suggestions.js 服务扩展

3. tasks.js 服务扩展

4. forum.js 服务扩展

云函数集成规范

1. suggestionOrchestrator 云函数扩展

2. taskWorkflow 云函数实现

3. treeholeModeration 云函数实现

🎨 前端组件开发指导

TDesign组件使用规范

核心组件开发指导

1. 情绪打卡组件 (emotion-picker)

2. 建议卡片组件 (suggestion-card)

3. 任务卡片组件 (task-card)

4. 番茄计时器组件 (tomato-timer)

页面集成示例

今天页面 (pages/today/index.js) 集成

🧪 测试策略与质量保证

测试架构设计

1. 单元测试

2. 集成测试

3. 端到端测试

4. AI服务测试

性能测试要求

1. 响应时间基准

2. 并发测试

质量门禁标准

🚀 部署与运维指导

部署策略

1. 渐进式发布

2. 数据库迁移

3. 云函数部署

监控与告警

1. 关键指标监控

2. 告警配置

3. 日志管理

回滚策略

1. 快速回滚机制

2. 数据恢复

🔒 安全与合规指导

数据安全要求

1. 隐私分级实施

2. 数据加密策略

3. 访问控制

内容安全

1. 内容审核

2. 风险识别

合规要求

1. 数据保护合规

2. 未成年人保护

📈 下一步开发工作流

开发优先级与时间线

第1周: 基础功能完善

第2周: AI核心功能

第3周: 社区功能

第4周: 任务闭环

第5周: 测试与发布

团队协作规范

1. 代码管理

2. 代码审查