文件清单与说明

📂 根目录文件

配置文件

源代码

后端示例

📁 src/ 目录详解

src/main.js

• 用途: Vite 应用入口点
• 功能: 导入应用主逻辑和样式，初始化应用
• 关键:
• 导入 initApp 从 ./js/app.js
• 导入全局样式
• 监听 DOMContentLoaded 事件

import { initApp } from './js/app.js';
import './styles/main.css';

document.addEventListener('DOMContentLoaded', initApp);

src/js/app.js ⭐

• 用途: 应用主逻辑和核心业务
• 关键函数:
• initApp() - 应用初始化入口
• handleAuthCallback() - 处理 OAuth 回调
• handleUnauthorized() - 处理未授权状态
• displayUserInfo() - 显示用户信息
• handleGetCode() - 处理获取密码
• 关键变量:
• oauth - OAuth 客户端实例
• apiClient - HTTP 客户端实例
• 核心流程:

1. 初始化 OAuth 客户端
2. 检查是否有授权码
3. 根据认证状态显示相应 UI

src/js/wechat-oauth.js 🔐

• 用途: 企业微信 OAuth 2.0 客户端
• 主要类: WeChatOAuth
• 关键方法:
• getAuthUrl() - 获取授权链接
• getAuthCode() - 从 URL 获取授权码
• exchangeCodeForUserInfo(code) - 交换用户信息
• getUserInfo() - 获取缓存的用户信息
• isAuthorized() - 检查是否已授权
• clearUserInfo() - 清除用户信息
• 状态管理: sessionStorage

src/js/wecom-config.js ⚙️

• 用途: 企业微信应用配置
• 导出: WECOM_CONFIG 对象
• 必需字段:
• corpId - 企业 ID
• agentId - 应用 ID
• redirectUri - OAuth 回调地址
• apiBaseUrl - API 基础路径
• 修改: 根据实际应用填入

src/js/api-client.js 🌐

• 用途: HTTP 客户端和 API 通信
• 主要类: ApiClient
• 关键方法:
• get(endpoint) - GET 请求
• post(endpoint, data) - POST 请求
• getUserInfoByCode(code) - 获取用户信息
• getWeChatUserDetail(userId) - 获取用户详情
• verifyUserPermission(userId) - 验证权限
• 特性: 自动错误处理和响应解析

src/js/utils.js 🛠️

• 用途: 通用工具函数库
• 导出函数:
• getHistoryFromStorage() - 获取历史记录
• saveHistoryToStorage(history) - 保存历史记录
• formatDateTime(date) - 日期格式化
• isValid(expiryTime) - 检查是否有效
• getRemainingTime(expiryTime) - 获取剩余时间
• generateCode() - 生成验证码
• generatePassword() - 生成密码
• showMessage(message, type) - 显示提示消息
• copyToClipboard(text) - 复制到剪贴板
• 用途: 复用最频繁的业务逻辑

src/styles/main.css 🎨

• 用途: 全局样式和响应式设计
• 主要样式类:
• .container - 容器
• .header-card - 头部卡片
• .form-input - 输入框
• .btn-primary - 主按钮
• .history-table - 历史表格
• .auth-prompt - 授权提示
• 响应式断点:
• 768px - 平板
• 480px - 手机
• 360px - 小屏手机

📄 根目录文档文件

🔄 数据流向

用户输入 (input)
    ↓
验证 (validate)
    ↓
业务逻辑 (app.js)
    ↓
API 调用 (api-client.js)
    ↓
后端处理 (server-example.js)
    ↓
数据返回 (response)
    ↓
存储 (localStorage/sessionStorage)
    ↓
显示 (UI update)

🔐 认证流程详解

client/index.html
    ↓
wechat-oauth.js (getAuthCode)
    ↓
[检查 URL 中的 code 参数]
    ├─ 如果有 code → exchangeCodeForUserInfo
    ├─ 如果无 code → getAuthUrl (重定向)
    └─ 如果已授权 → getUserInfo (sessionStorage)
    ↓
app.js (displayUserInfo)
    ↓
UI 显示用户信息

📊 模块依赖关系

main.js
  ├── app.js
  │   ├── wechat-oauth.js
  │   ├── api-client.js
  │   ├── wecom-config.js
  │   └── utils.js
  └── styles/main.css

server-example.js
  ├── axios (HTTP)
  ├── dotenv (配置)
  └── express (框架)

🚀 构建输出

执行 npm run build 后生成 dist/ 目录：

dist/
├── index.html          # 优化后的 HTML
├── assets/
│   ├── index-xxx.js    # 打包后的 JavaScript
│   └── index-xxx.css   # 打包后的 CSS
└── (其他资源)

✅ 完整性检查表

使用此清单确保所有文件都已配置：

• [ ] src/js/wecom-config.js - 已填入企业 ID 和 AgentID
• [ ] .env - 已创建和配置
• [ ] WECOM_CORP_ID - 已设置
• [ ] WECOM_APP_SECRET - 已设置
• [ ] 企业微信后台 - 已配置回调地址
• [ ] 企业微信后台 - 已添加可信域名
• [ ] server-example.js - 已根据需要自定义
• [ ] HTTPS - 已配置
• [ ] 防火墙 - 已允许必要的端口

🔍 常见文件修改

添加新的 API 端点

1. 在 server-example.js 中添加路由
2. 在 src/js/api-client.js 中添加对应方法
3. 在 src/js/app.js 中调用方法

修改样式

1. 编辑 src/styles/main.css
2. Vite 会自动热更新

添加新功能

1. 创建新的 .js 文件在 src/js/
2. 在 src/js/app.js 中导入
3. 调用相应函数

自定义用户信息显示

编辑 src/js/app.js 中的 displayUserInfo() 函数

📦 依赖说明

前端依赖

仅有 Vite (开发依赖)：
json { "devDependencies": { "vite": "^5.0.0" } }

特点: 零运行时依赖，轻量级应用

后端依赖 (可选)

如使用 server-example.js:
bash npm install express axios cors dotenv morgan

🎯 文件使用场景

此清单定期更新以保持准确性

最后更新: 2025年12月9日