贡献指南

​

快速开始

1. 在 GitHub 上 Fork 仓库
2. 克隆你的 fork 到本地：
   git clone https://github.com/YOUR_USERNAME/worldmonitor.git
   cd worldmonitor
   
3. 安装依赖：
   npm install
   
4. 创建功能分支：
   git checkout -b feature/your-feature-name
   
5. 启动开发服务器：
   npm run dev
   

​

代码风格与规范

• 启用严格类型检查，尽量避免使用 any
• 数据结构使用 interface，联合类型使用 type
• 优先使用 const 而非 let，绝不使用 var

• Services（src/services/）处理数据获取与业务逻辑
• Components（src/components/）处理 UI 渲染
• Config（src/config/）包含静态数据与常量
• Utils（src/utils/）包含共享的辅助函数

• 耗时计算应放在 Web Worker 中运行
• 列表项超过 50 条时使用虚拟滚动
• 对外部 API 调用实现熔断器

• 代码应通过清晰的命名实现自文档化
• 仅在算法或变通方案不明显时才添加注释
• 永远不要提交被注释掉的代码

​

安全与输入校验

​

XSS 防护

escapeHtml(str)  // 将 & < > " ' 编码为 HTML 实体
sanitizeUrl(url) // 仅允许 http/https 协议

• 新闻标题与来源（RSS feeds）
• 搜索结果与高亮
• 监控关键词（用户输入）
• 地图弹窗内容
• 紧张关系配对标签

​

代理端点校验

​

内容安全

• URL 通过 URL() 构造函数校验，仅允许 http: 与 https: 协议
• 外部链接使用 rel="noopener" 以防止反向标签劫持
• 没有内联脚本或 eval()，所有代码在构建时打包

​

安全相关贡献

• 渲染用户可控或外部数据时始终使用 escapeHtml()
• 对来自外部来源的 URL 使用 sanitizeUrl()
• 在 API 代理端点中校验并限幅参数

​

提交 Pull Request

1. 确保代码可构建：
   npm run build
   
2. 在浏览器中手动测试你的改动
3. 编写清晰的提交信息：
   Add earthquake magnitude filtering to map layer
   
   - Adds slider control to filter by minimum magnitude
   - Persists preference to localStorage
   - Updates URL state for shareable links
   
4. 推送到你的 fork：
   git push origin feature/your-feature-name
   
5. 提交 Pull Request，需包含：
   • 清晰描述改动的标题
   • PR 做了什么以及为什么的说明
   • UI 改动的截图
   • 任何破坏性变更或迁移说明

​

优秀的 PR 应具备什么

​

贡献类型

• 发现问题？修复它并提交 PR
• 在 PR 描述中提供复现步骤

• 新的数据图层（需有公开 API 来源）
• UI/UX 改进
• 性能优化
• 新的信号检测算法

• 用于新闻聚合的额外 RSS feeds
• 新的地理空间数据集（基地、基础设施等）
• 现有数据的替代 API

• 澄清现有文档
• 添加示例与用例
• 修复错别字并提升可读性

• 通过 GitHub Issues（非关键）或邮件（关键）报告漏洞
• XSS 防护改进
• 输入校验增强

​

评审流程

1. 提交 PR 时运行自动化检查
2. 数日内进行维护者评审
3. 通过向同一分支提交 commit 来处理反馈
4. 批准后合并

​

许可证