SaaS2/docs/快速入门指南.md

待办事项管理系统 - 快速入门指南

🚀 快速开始

1. 环境准备

# 安装依赖
pnpm install

# 启动数据库 (MongoDB)
mongod

# 启动开发服务器
pnpm run dev

2. 核心文件结构

src/
├── components/TodoManager/     # 🎯 主要组件
├── hooks/useSocket.ts         # 🔗 实时通信
├── pages/api/todos/[id].ts    # 📡 核心API
└── types/socket.ts            # 📝 类型定义

⚡ 5分钟实现待办事项

步骤1: 创建数据模型

// models/Todo.ts
const TodoSchema = new Schema({
  标题: { type: String, required: true },
  状态: { type: String, enum: ['待处理', '进行中', '已完成', '已取消'] },
  优先级: { type: String, enum: ['低', '中', '高', '紧急'] },
  办理人员: [{ type: Schema.Types.ObjectId, ref: 'User' }],
  // ... 其他字段
});

步骤2: 创建API接口

// pages/api/todos/[id].ts
export default async function handler(req, res) {
  switch (req.method) {
    case 'PATCH':
      // 更新状态
      const updatedTodo = await Todo.findByIdAndUpdate(id, data);
      
      // 发送实时通知
      res.socket.server.io.emit('todo-status-changed', {
        data: updatedTodo,
        message: '状态已更新'
      });
      break;
  }
}

步骤3: 添加实时通信

// hooks/useSocket.ts
socket.on('todo-status-changed', (data) => {
  // 刷新数据
  window.dispatchEvent(new CustomEvent('todo-data-updated'));
});

步骤4: 创建UI组件

// components/TodoManager/index.tsx
const TodoManager = () => {
  const [todos, setTodos] = useState([]);
  
  // 监听实时更新
  useEffect(() => {
    const handleUpdate = () => fetchTodos();
    window.addEventListener('todo-data-updated', handleUpdate);
    return () => window.removeEventListener('todo-data-updated', handleUpdate);
  }, []);
  
  return (
    <List
      dataSource={todos}
      renderItem={todo => <TodoItem todo={todo} />}
    />
  );
};

🔧 关键配置

Socket.IO 服务器

// pages/api/socket.ts
const io = new ServerIO(httpServer, {
  path: '/api/socket',
  cors: { origin: 'http://localhost:3000' }
});

客户端连接

const socket = io({ path: '/api/socket' });

🎯 核心功能实现

1. 状态更新 + 实时同步

const updateStatus = async (todoId, newStatus) => {
  await fetch(`/api/todos/${todoId}`, {
    method: 'PATCH',
    body: JSON.stringify({ action: 'update-status', 状态: newStatus })
  });
  // 实时通知会自动触发界面更新
};

2. 通知机制

// 只给相关用户显示通知，但所有人都更新数据
if (isTargetUser && !isCreator) {
  notification.open({ message: '有新更新' });
}
if (isTargetUser) {
  // 触发数据更新
  window.dispatchEvent(new CustomEvent('todo-data-updated'));
}

3. 分组显示

const groupedTodos = useMemo(() => ({
  active: todos.filter(t => ['待处理', '进行中'].includes(t.状态)),
  completed: todos.filter(t => t.状态 === '已完成'),
  cancelled: todos.filter(t => t.状态 === '已取消')
}), [todos]);

🐛 常见问题

Q: 操作者看不到自己的更新？

A: 检查通知逻辑，确保数据更新事件在 isTargetUser 条件内触发

Q: Socket连接失败？

A: 确认Socket.IO服务器正确初始化，检查CORS配置

Q: 统计数据为0？

A: 实现双重统计策略：API统计 + 本地计算备用

📚 扩展阅读

• 完整开发指南
• API文档
• Socket.IO官方文档

---

⚡ 5分钟就能上手，30分钟完成核心功能！