# 🎯 5分钟快速导航 > **你在这里**: 项目已完成，准备开始使用 | **下一步**: 选择你的路径 --- ## 🚀 3 种开始方式 ### 🟢 方式 1: 我只想快速体验（5分钟） ```bash # 1️⃣ 进入项目目录 cd d:\gitData\qiyeWeComApp # 2️⃣ 安装依赖 npm install # 3️⃣ 启动开发服务器 npm run dev # 4️⃣ 打开浏览器 # http://localhost:5173 ``` **完成！** ✅ 你现在看到了应用界面 👉 **下一步**: 修改 `src/js/wecom-config.js` 添加企业微信配置 --- ### 🟡 方式 2: 我想理解整个项目（30分钟） ```bash # 1️⃣ 快速浏览项目结构 ls -la src/ ls -la docs/ # 2️⃣ 阅读这些文件（按顺序） - QUICK_START.md (5分钟) ← 开始这里 - README_VITE.md (10分钟) - WECOM_INTEGRATION_GUIDE.md (15分钟) # 3️⃣ 尝试运行应用 npm run dev # 4️⃣ 打开浏览器开发者工具 (F12) # 查看 Console 和 Network 标签 ``` **完成！** ✅ 你现在理解了项目架构 👉 **下一步**: 按照 [DELIVERY.md](./DELIVERY.md) 进行配置 --- ### 🔴 方式 3: 我想深入学习（2小时） ```bash # 1️⃣ 完整学习路径 1. DELIVERY.md (10分钟) 2. README_VITE.md (15分钟) 3. PROJECT_SUMMARY.md (30分钟) 4. FILE_INVENTORY.md (20分钟) 5. 源代码阅读 (30分钟) 6. WECOM_OAUTH_GUIDE.md (20分钟) 7. 实践修改代码 (15分钟) # 2️⃣ 运行和调试 npm run dev # 启动开发服务器 F12 # 打开开发者工具 编辑代码 # 实时看到效果 # 3️⃣ 深入学习 阅读 PROJECT_SUMMARY.md 了解架构和扩展 ``` **完成！** ✅ 你现在是项目专家 👉 **下一步**: 根据需要扩展功能 --- ## 📚 文档快速导航 | 用途 | 文档 | 时间 | 链接 | |------|------|------|------| | **我很急** | QUICK_START.md | 5分钟 | 👉 [打开](./QUICK_START.md) | | **我想开始** | DELIVERY.md | 10分钟 | 👉 [打开](./DELIVERY.md) | | **我想了解** | README_VITE.md | 15分钟 | 👉 [打开](./README_VITE.md) | | **我想学习** | WECOM_INTEGRATION_GUIDE.md | 30分钟 | 👉 [打开](./WECOM_INTEGRATION_GUIDE.md) | | **我想精通** | PROJECT_SUMMARY.md | 40分钟 | 👉 [打开](./PROJECT_SUMMARY.md) | | **我要代码** | FILE_INVENTORY.md | 30分钟 | 👉 [打开](./FILE_INVENTORY.md) | | **我要索引** | INDEX.md | - | 👉 [打开](./INDEX.md) | --- ## ⚡ 常用命令 ```bash # 开发相关 npm run dev # 启动开发服务器 (http://localhost:5173) npm run build # 构建生产版本 (生成 dist/ 文件夹) npm run preview # 预览生产版本 # 文件查看 cat package.json # 查看项目配置 cat src/js/app.js # 查看核心逻辑 cat vite.config.js # 查看 Vite 配置 ``` --- ## 🐛 常见错误快速修复 ### ❌ `npm: 命令未找到` ```bash # 安装 Node.js # 下载: https://nodejs.org # 或使用 PowerShell 安装 choco install nodejs ``` ### ❌ `Port 5173 already in use` ```bash # 方法 1: 使用其他端口 npm run dev -- --port 5174 # 方法 2: 关闭占用端口的程序 Get-Process | Where-Object {$_.ProcessName -like "*node*"} | Stop-Process ``` ### ❌ `Cannot find module` ```bash # 重新安装依赖 rm -r node_modules package-lock.json npm install ``` ### ❌ `OAuth 跳转失败` ```bash # 检查配置 cat src/js/wecom-config.js # 确保这些值已填写: - corpId (企业ID) - agentId (应用ID) - redirectUri (回调地址) - apiBaseUrl (后端地址) ``` ### ❌ `样式不显示` ```bash # 清理缓存 rm -r .vite npm run dev # 或者按 Ctrl+F5 硬刷新浏览器 ``` --- ## 💡 三个必知概念 ### 1️⃣ OAuth 2.0 认证流 ``` 用户 → 企业微信 → 应用 → 后端 → 用户信息 → 页面显示 ``` **关键点**: - 用户在企业微信中授权一次 - 应用自动获取用户信息 - 无需手动登录 ### 2️⃣ 前后端分离 ``` 前端 (这个项目) → HTTP API → 后端服务 ↓ ↓ 处理 UI 处理业务逻辑 管理状态 访问数据库 验证输入 调用企业微信 ``` **你需要做**: 实现后端服务 (参考 [server-example.js](./server-example.js)) ### 3️⃣ Vite 热更新 ``` 编辑代码 → Vite 检测 → 自动编译 → 刷新浏览器 (1s) (0.2s) (0.1s) ``` **你会看到**: 保存代码后立即看到效果，无需手动刷新 --- ## 🎯 接下来的 3 步 ### ✅ 第 1 步: 本地开发 (现在) ```bash npm install npm run dev # 浏览器打开 http://localhost:5173 ``` **预期结果**: 看到登录页面 **参考**: [DELIVERY.md - 第一步](./DELIVERY.md#✅-第一步本地开发) --- ### ✅ 第 2 步: 配置企业微信 ```bash # 1️⃣ 编辑配置文件 编辑 src/js/wecom-config.js # 2️⃣ 填写以下信息: - WECOM_CORP_ID (在企业微信后台获取) - WECOM_AGENT_ID (在企业微信后台获取) - WECOM_REDIRECT_URI (你的应用 URL) - WECOM_API_BASE (你的后端地址) # 3️⃣ 在企业微信后台配置: - 添加可信域名 - 配置 OAuth 回调地址 - 设置应用权限 ``` **预期结果**: 在企业微信中可以授权登录 **参考**: [WECOM_INTEGRATION_GUIDE.md](./WECOM_INTEGRATION_GUIDE.md#配置步骤) --- ### ✅ 第 3 步: 实现后端 ```bash # 参考 server-example.js 实现以下接口: POST /api/wecom/getUserInfo # 交换 OAuth code 获取用户信息 GET /api/wecom/userDetail/:userId # 获取用户详情 GET /api/wecom/verify/:userId # 验证用户权限 # 环境变量配置 (.env 文件) WECOM_CORP_ID=xxx WECOM_APP_SECRET=xxx WECOM_AGENT_ID=xxx ``` **预期结果**: 后端能处理 OAuth 认证 **参考**: [server-example.js](./server-example.js) --- ## 📞 快速问题解答 ### Q: 我应该从哪个文件开始修改？ **A**: 按优先级： 1. 先改 `src/js/wecom-config.js` (配置企业微信) 2. 再改 `src/js/app.js` (业务逻辑) 3. 最后改 `src/styles/main.css` (样式) ### Q: 我如何添加新功能？ **A**: 步骤： 1. 在 `src/js/app.js` 中添加函数 2. 在 `index.html` 中添加 HTML 3. 在 `src/styles/main.css` 中添加样式 4. 保存文件自动刷新浏览器 ### Q: 如何调试代码？ **A**: 1. 打开浏览器 F12 2. 查看 Console 标签看输出 3. 查看 Network 标签看网络请求 4. 在代码中添加 `console.log()` 打印调试信息 ### Q: 如何部署到生产？ **A**: ```bash npm run build # 生成 dist/ 文件夹 # 将 dist/ 文件夹上传到服务器 # 配置 Web 服务器 (Nginx/Apache) ``` 详见 [DELIVERY.md](./DELIVERY.md#✅-第五步生产部署) ### Q: 我遇到了奇怪的错误怎么办？ **A**: 1. 查看 [QUICK_START.md - 常见错误](./QUICK_START.md#🐛-常见错误) 2. 查看 [WECOM_INTEGRATION_GUIDE.md - 故障排查](./WECOM_INTEGRATION_GUIDE.md#故障排查) 3. 按 Ctrl+Shift+Delete 清理浏览器缓存 4. 重新运行 `npm run dev` --- ## 📊 项目检查清单 开始前，确保你有： - ✅ Node.js 14+ (运行 `node --version` 检查) - ✅ npm (运行 `npm --version` 检查) - ✅ 文本编辑器 (VS Code 推荐) - ✅ 浏览器 (Chrome/Firefox/Edge) - ✅ 企业微信账号 (可选，后续需要) - ✅ 这个项目代码 ✅ --- ## 🎁 你现在拥有 ``` ✅ 完整的前端应用 ✅ 企业微信 OAuth 2.0 集成 ✅ 响应式移动设计 ✅ 后端参考实现 ✅ 11 个详尽文档 ✅ 100+ 个代码示例 ✅ 30+ 个常见问题解答 ✅ 企业级代码质量 ✅ 生产就绪状态 ``` --- ## 🚀 现在就开始 ### 选择你的路径： **👶 我是新手** ``` → 打开 QUICK_START.md → 按照步骤操作 → 不会的查看文档 ``` **👨‍💻 我是开发者** ``` → 打开 README_VITE.md → 运行 npm install && npm run dev → 开始编码 ``` **🏆 我是架构师** ``` → 打开 PROJECT_SUMMARY.md → 审查代码架构 → 提出优化建议 ``` --- ## 💬 常用快捷键 ``` F12 打开浏览器开发者工具 Ctrl+S 保存文件 (自动刷新) Ctrl+F 在文件中搜索 Ctrl+/ 注释/取消注释代码 Ctrl+D 选择相同单词 Ctrl+Shift+P 打开 VS Code 命令面板 ``` --- ## 📌 重要文件位置 ``` 项目根目录 ├── src/ │ ├── js/ │ │ ├── app.js ← 核心逻辑 │ │ ├── wechat-oauth.js ← OAuth 客户端 │ │ ├── api-client.js ← API 请求 │ │ ├── wecom-config.js ← 配置 (需要修改) │ │ └── utils.js ← 工具函数 │ ├── styles/ │ │ └── main.css ← 样式 │ └── main.js ← 入口点 ├── index.html ← HTML 页面 ├── server-example.js ← 后端参考 ├── vite.config.js ← Vite 配置 ├── package.json ← 项目配置 └── 文档 (*.md 文件) ``` --- ## ⏱️ 时间规划 ``` 现在 - 5分钟 : 快速体验应用 +15分钟 : 阅读项目说明 +30分钟 : 理解代码架构 +1小时 : 配置企业微信 +2小时 : 实现后端服务 +1小时 : 测试全流程 +1小时 : 部署到生产 ───────────────── 总计: 约 6小时 ``` --- ## 🎯 现在就做这个 ```bash # 在 PowerShell 中运行: cd d:\gitData\qiyeWeComApp npm install npm run dev # 然后打开浏览器: # http://localhost:5173 ``` **就这样！** ✅ --- ## 🆘 需要帮助？ | 情况 | 查看这里 | |------|---------| | 我不知道怎么开始 | [QUICK_START.md](./QUICK_START.md) | | 我要配置企业微信 | [WECOM_INTEGRATION_GUIDE.md](./WECOM_INTEGRATION_GUIDE.md) | | 我遇到了错误 | [QUICK_START.md#🐛-常见错误](./QUICK_START.md#🐛-常见错误) | | 我要理解代码 | [FILE_INVENTORY.md](./FILE_INVENTORY.md) | | 我要学习架构 | [PROJECT_SUMMARY.md](./PROJECT_SUMMARY.md) | | 我要找具体文件 | [INDEX.md](./INDEX.md) | --- **准备好了吗？** 让我们开始吧！ 🚀 `npm run dev` → 打开浏览器 → 开始开发！ --- _更新于: 2025-12-09_ _祝你编码愉快！_ 💻✨