跳转到主要内容
欢迎贡献代码！无论是修复 bug、添加功能、改进文档，还是提出建议，你的帮助都能让这个项目变得更好。本指南涵盖了贡献工作流程、代码规范以及安全要求。

​
快速开始

  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

​
代码风格与规范

本项目遵循特定的模式以保持一致性： TypeScript
  • 启用严格类型检查，尽量避免使用 any
  • 数据结构使用 interface，联合类型使用 type
  • 优先使用 const 而非 let，绝不使用 var
架构
  • Services（src/services/）处理数据获取与业务逻辑
  • Components（src/components/）处理 UI 渲染
  • Config（src/config/）包含静态数据与常量
  • Utils（src/utils/）包含共享的辅助函数
性能
  • 耗时计算应放在 Web Worker 中运行
  • 列表项超过 50 条时使用虚拟滚动
  • 对外部 API 调用实现熔断器
注释政策
  • 代码应通过清晰的命名实现自文档化
  • 仅在算法或变通方案不明显时才添加注释
  • 永远不要提交被注释掉的代码

​
安全与输入校验

仪表盘处理来自数十个外部来源的不可信数据。纵深防御措施可防止注入攻击与 API 滥用。

​
XSS 防护

所有对用户可见的内容在插入 DOM 之前都会被净化： 
escapeHtml(str)  // 将 & < > " ' 编码为 HTML 实体
sanitizeUrl(url) // 仅允许 http/https 协议
这适用于：
  • 新闻标题与来源（RSS feeds）
  • 搜索结果与高亮
  • 监控关键词（用户输入）
  • 地图弹窗内容
  • 紧张关系配对标签
搜索中的 mark 元素高亮在包裹匹配项之前先对文本进行转义，防止通过构造恶意搜索查询进行注入。

​
代理端点校验

公开 API 入口对所有参数进行校验与限幅：
端点校验规则
GET /api/market/v1/list-market-quotes股票/指数 symbols 列表；为空则返回默认值
GET /api/market/v1/list-crypto-quotesCoinGecko ids 列表；为空则返回默认值
GET /api/polymarket遗留 Polymarket 代理：排序字段白名单，limit 限制在 1-100
这可防止上游 API 滥用以及因格式错误请求导致的速率限制耗尽。

​
内容安全

  • 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 应具备什么

应该做不应该做
聚焦于单一功能或修复把不相关的改动捆绑在一起
遵循现有代码模式未经讨论就引入新框架
保持改动最小且聚焦不必要地重构周边代码
添加功能时更新 README添加功能却不写文档
测试边界情况只考虑正常流程

​
贡献类型

Bug 修复
  • 发现问题？修复它并提交 PR
  • 在 PR 描述中提供复现步骤
新功能
  • 新的数据图层（需有公开 API 来源）
  • UI/UX 改进
  • 性能优化
  • 新的信号检测算法
数据源
  • 用于新闻聚合的额外 RSS feeds
  • 新的地理空间数据集（基地、基础设施等）
  • 现有数据的替代 API
文档
  • 澄清现有文档
  • 添加示例与用例
  • 修复错别字并提升可读性
安全
  • 通过 GitHub Issues（非关键）或邮件（关键）报告漏洞
  • XSS 防护改进
  • 输入校验增强

​
评审流程

  1. 提交 PR 时运行自动化检查
  2. 数日内进行维护者评审
  3. 通过向同一分支提交 commit 来处理反馈
  4. 批准后合并
未遵循代码风格或引入安全问题的 PR 将被要求修改。

​
许可证

向 World Monitor 贡献代码即表示你同意你的贡献以 AGPL-3.0 许可。完整条款、商业许可及常见场景请参见许可证页面。