@mathcrowd/mmarked 2.0.2 → 3.0.0

package/CHANGELOG.md

@@ -1,3 +1,28 @@
+# [3.0.0](https://cloud.mathcrowd.cn:2444/agile/frontend/mathcrowd-marked-lib/compare/v2.0.3...v3.0.0) (2025-12-25)
+
+
+### Bug Fixes
+
+* **ci:** add contents write permission to release workflow ([9f4d3cc](https://cloud.mathcrowd.cn:2444/agile/frontend/mathcrowd-marked-lib/commits/9f4d3cc60d410a93f015796f3e6023f7098b982f))
+* **ci:** remove tags-only restriction from github sync job ([5e54dd2](https://cloud.mathcrowd.cn:2444/agile/frontend/mathcrowd-marked-lib/commits/5e54dd2114cc67eab5d6bc019ad161052dbc1484))
+
+
+### Features
+
+* add Node.js-only license validation with browser exemption ([acb4f1a](https://cloud.mathcrowd.cn:2444/agile/frontend/mathcrowd-marked-lib/commits/acb4f1a5c75f4fe5ebb4434dbbdc970664a2f048))
+
+
+
+## [2.0.3](https://cloud.mathcrowd.cn:2444/agile/frontend/mathcrowd-marked-lib/compare/v2.0.2...v2.0.3) (2025-10-12)
+
+
+### Bug Fixes
+
+* **build:** preserve .gitignore in docs directory ([f9c1e79](https://cloud.mathcrowd.cn:2444/agile/frontend/mathcrowd-marked-lib/commits/f9c1e792c8d79311fa98c30eb6cb794cfaa870c6))
+* **ci:** remove build steps from GitHub release workflow ([d3d74c6](https://cloud.mathcrowd.cn:2444/agile/frontend/mathcrowd-marked-lib/commits/d3d74c63706546c848d6a64f71dc4281cec76414))
+
+
+
 ## [2.0.2](https://cloud.mathcrowd.cn:2444/agile/frontend/mathcrowd-marked-lib/compare/v2.0.1...v2.0.2) (2025-10-12)
 
 

package/LICENSE_SYSTEM_DOCS.md

@@ -0,0 +1,341 @@
+# MMarked 许可证系统状态文档
+
+## 📋 系统概述
+
+MMarked 是一个用于教育和数学内容的 Markdown 渲染库，支持 LaTeX 公式、定理块等高级功能。本文档描述了其许可证管理系统的工作原理和后端接口规范。
+
+## 🎯 许可证系统设计目标
+
+- ✅ **服务端商业使用收费**：Node.js 环境下的商业使用需要许可证
+- ✅ **客户端免费使用**：浏览器环境完全免费，无任何限制
+- ✅ **非侵入式警告**：未授权使用时显示友好的警告信息
+- ✅ **使用情况统计**：自动收集和报告使用统计数据
+- ✅ **安全性优先**：端点地址硬编码，防止恶意修改
+
+## 🔧 系统架构
+
+### 前端/客户端功能
+
+#### 许可证验证逻辑
+- **环境检测**：通过 `process` 对象检测是否在 Node.js 环境中
+- **浏览器豁免**：浏览器环境 (`typeof process === 'undefined'`) 完全跳过验证
+- **同步检查**：`isLicensed()` 函数在浏览器中总是返回 `false`
+- **警告注入**：只在 Node.js 环境中检查，未授权时每 1000 次调用注入 SVG 警告
+
+#### 统计数据收集
+- **调用跟踪**：每次调用 `renderMarkdown()` 或 `renderMarkdownCompact()` 时记录
+- **内存存储**：统计数据存储在内存中，随应用重启清零
+- **Session ID机制**：每个应用实例生成唯一session_id，后端按IP或api-key汇总跨部署数据
+- **数据字段**：
+  ```typescript
+  interface UsageStats {
+    totalCalls: number                    // 总调用次数
+    renderMarkdownCalls: number          // renderMarkdown 调用次数
+    renderMarkdownCompactCalls: number   // renderMarkdownCompact 调用次数
+    firstUsedAt: number                  // 首次使用时间戳
+    lastUsedAt: number                  // 最后使用时间戳
+    apiKey?: string                     // API 密钥
+    nodeVersion?: string                // Node.js 版本
+    sessionId?: string                  // 会话ID（跨部署汇总用）
+  }
+  ```
+
+### 服务端功能
+
+#### 许可证配置
+```typescript
+configureLicense({
+  apiKey: 'MMARKED-XXXX-XXXX-XXXX-XXXX'  // 许可证密钥
+})
+```
+
+#### 自动报告机制
+- **报告频率**：每小时一次 (60 * 60 * 1000 毫秒)
+- **触发时机**：许可证配置后自动启动定时器
+- **报告内容**：累积统计数据（从应用启动开始的所有调用）
+- **重复报告防护**：记录最后报告时间，避免重启后重复发送相同数据
+- **失败处理**：静默失败，不影响用户正常使用
+
+#### 警告系统
+- **警告频率**：每 1000 次未授权调用注入一次警告
+- **警告格式**：伪装成 SVG 数学公式的 HTML 片段
+- **警告内容**：
+  - 非商业使用警告
+  - 联系方式 (charles@mathcrowd.cn)
+  - 许可证配置指引
+
+## 📊 数据流图
+
+```
+┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
+│   客户端调用    │───▶│  统计数据收集    │───▶│   定时报告发送   │
+│                 │    │                  │    │                 │
+│ • renderMarkdown│    │ • totalCalls++   │    │ • 每小时一次    │
+│ • renderCompact │    │ • 生成sessionId  │    │ • POST /report-usage │
+└─────────────────┘    └──────────────────┘    └─────────────────┘
+                                │
+                                ▼
+                       ┌──────────────────┐    ┌──────────────────┐
+                       │   后端数据汇总    │───▶│   跨部署统计     │
+                       │                  │    │                  │
+                       │ • 按IP汇总       │    │ • 按api-key汇总  │
+                       │ • 按sessionId分组│    │ • 累计使用量     │
+                       └──────────────────┘    └──────────────────┘
+```
+
+## ⚠️ 警告注入机制
+
+### 触发条件
+- 运行在 Node.js 环境
+- 未配置有效许可证
+- 总调用次数达到 1000 的倍数
+
+### 警告外观
+```html
+<svg xmlns="http://www.w3.org/2000/svg" class="MJX-svg-equation" role="img" focusable="false"
+     viewBox="0 0 800 80" style="vertical-align: -0.5ex; margin: 1em 0; max-width: 100%; display: block;"
+     aria-label="Non-commercial use warning" data-formula-id="随机ID" data-timestamp="时间戳">
+  <defs>
+    <style type="text/css">
+      .mjx-warning-text { font-family: Arial, sans-serif; font-size: 14px; fill: #856404; }
+      .mjx-warning-link { font-family: Arial, sans-serif; font-size: 14px; fill: #0066cc; text-decoration: underline; cursor: pointer; }
+    </style>
+  </defs>
+  <rect width="800" height="80" fill="#fff3cd" stroke="#ffc107" stroke-width="1" rx="4"/>
+  <text x="20" y="25" class="mjx-warning-text" font-weight="bold">⚠️ Non-Commercial Use Only</text>
+  <text x="20" y="45" class="mjx-warning-text">This content uses @mathcrowd/mmarked without valid commercial license.</text>
+  <text x="20" y="65" class="mjx-warning-text">For commercial use, contact: </text>
+  <a href="mailto:charles@mathcrowd.cn">
+    <text x="220" y="65" class="mjx-warning-link">charles@mathcrowd.cn</text>
+  </a>
+</svg>
+```
+
+---
+
+# 🔗 后端接口规范
+
+## 1. 许可证验证接口
+
+### 接口信息
+- **URL**: `https://api.mathcrowd.cn/validate-license`
+- **方法**: `POST`
+- **内容类型**: `application/json`
+
+### 请求体
+```json
+{
+  "apiKey": "MMARKED-XXXX-XXXX-XXXX-XXXX"
+}
+```
+
+### 响应格式
+```json
+{
+  "valid": true|false,
+  "message": "验证结果描述（可选）",
+  "expiresAt": "2024-12-31T23:59:59Z（可选）",
+  "tier": "free|basic|pro|enterprise（可选）"
+}
+```
+
+### 错误处理
+- **网络错误**: 客户端静默失败，继续使用（假设有效）
+- **无效许可证**: 返回 `{"valid": false, "message": "License key is invalid"}`
+- **服务器错误**: 返回 `{"valid": false, "message": "Server error"}`
+
+## 2. 使用统计报告接口
+
+### 接口信息
+- **URL**: `https://api.mathcrowd.cn/report-usage`
+- **方法**: `POST`
+- **内容类型**: `application/json`
+- **频率**: 每小时一次（客户端定时发送）
+
+### 请求体
+```json
+{
+  "totalCalls": 1500,
+  "renderMarkdownCalls": 1200,
+  "renderMarkdownCompactCalls": 300,
+  "firstUsedAt": 1703452800000,
+  "lastUsedAt": 1703456400000,
+  "apiKey": "MMARKED-XXXX-XXXX-XXXX-XXXX",
+  "timestamp": 1703456400000,
+  "nodeVersion": "18.17.0",
+  "sessionId": "550e8400-e29b-41d4-a716-446655440000"
+}
+```
+
+### 字段说明
+- **totalCalls**: 从应用启动开始的总调用次数
+- **renderMarkdownCalls**: `renderMarkdown()` 函数调用次数
+- **renderMarkdownCompactCalls**: `renderMarkdownCompact()` 函数调用次数
+- **firstUsedAt**: 首次使用时间戳（毫秒）
+- **lastUsedAt**: 最后使用时间戳（毫秒）
+- **apiKey**: 许可证密钥
+- **timestamp**: 报告发送时间戳（毫秒）
+- **nodeVersion**: Node.js 版本字符串
+- **sessionId**: 唯一会话标识符，用于跨部署数据汇总
+
+### 响应要求
+- **成功响应**: HTTP 200-299 状态码
+- **失败处理**: 客户端对任何非 2xx 响应都静默忽略
+- **超时**: 客户端设置合理的超时时间（建议 30 秒）
+
+### 安全考虑
+- **IP 提取**: 从 HTTP 请求头中提取客户端 IP 地址
+- **数据验证**: 验证 apiKey 格式和必需字段
+- **速率限制**: 防止恶意高频报告
+- **数据存储**: 安全存储统计数据，用于分析和计费
+
+## 3. 实现建议
+
+### 后端数据存储
+```sql
+-- 使用统计表（按session存储原始数据）
+CREATE TABLE usage_reports (
+  id SERIAL PRIMARY KEY,
+  api_key VARCHAR(255) NOT NULL,
+  client_ip INET,
+  session_id VARCHAR(255) NOT NULL,        -- 新增：会话ID
+  total_calls INTEGER NOT NULL,
+  render_markdown_calls INTEGER NOT NULL,
+  render_compact_calls INTEGER NOT NULL,
+  first_used_at TIMESTAMP NOT NULL,
+  last_used_at TIMESTAMP NOT NULL,
+  report_timestamp TIMESTAMP NOT NULL,
+  node_version VARCHAR(50),
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- 汇总统计表（按IP和API密钥汇总）
+CREATE TABLE usage_aggregates (
+  id SERIAL PRIMARY KEY,
+  api_key VARCHAR(255) NOT NULL,
+  client_ip INET,
+  total_sessions INTEGER DEFAULT 0,        -- 会话总数
+  total_calls BIGINT DEFAULT 0,            -- 累计调用次数
+  render_markdown_calls BIGINT DEFAULT 0,  -- 累计renderMarkdown调用
+  render_compact_calls BIGINT DEFAULT 0,   -- 累计renderCompact调用
+  first_used_at TIMESTAMP,                 -- 首次使用时间
+  last_used_at TIMESTAMP,                  -- 最后使用时间
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE(api_key, client_ip)               -- 每个IP+API密钥的唯一记录
+);
+
+-- 许可证表
+CREATE TABLE licenses (
+  id SERIAL PRIMARY KEY,
+  api_key VARCHAR(255) UNIQUE NOT NULL,
+  valid BOOLEAN DEFAULT true,
+  expires_at TIMESTAMP,
+  tier VARCHAR(20) DEFAULT 'basic',
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+### API 端点实现示例（Node.js/Express）
+```javascript
+// 许可证验证
+app.post('/validate-license', async (req, res) => {
+  const { apiKey } = req.body;
+
+  try {
+    const license = await db.query('SELECT * FROM licenses WHERE api_key = $1', [apiKey]);
+
+    if (license.rows.length === 0) {
+      return res.json({ valid: false, message: 'License key not found' });
+    }
+
+    const lic = license.rows[0];
+    const isValid = lic.valid && (!lic.expires_at || new Date() < lic.expires_at);
+
+    res.json({
+      valid: isValid,
+      message: isValid ? 'License is valid' : 'License expired or invalid',
+      expiresAt: lic.expires_at,
+      tier: lic.tier
+    });
+  } catch (error) {
+    console.error('License validation error:', error);
+    res.status(500).json({ valid: false, message: 'Server error' });
+  }
+});
+
+// 使用统计报告
+app.post('/report-usage', async (req, res) => {
+  const clientIp = req.ip || req.connection.remoteAddress;
+  const reportData = req.body;
+
+  try {
+    // 1. 存储原始会话数据
+    await db.query(`
+      INSERT INTO usage_reports
+      (api_key, client_ip, session_id, total_calls, render_markdown_calls, render_compact_calls,
+       first_used_at, last_used_at, report_timestamp, node_version)
+      VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
+    `, [
+      reportData.apiKey,
+      clientIp,
+      reportData.sessionId,  // 新增sessionId
+      reportData.totalCalls,
+      reportData.renderMarkdownCalls,
+      reportData.renderMarkdownCompactCalls,
+      new Date(reportData.firstUsedAt),
+      new Date(reportData.lastUsedAt),
+      new Date(reportData.timestamp),
+      reportData.nodeVersion
+    ]);
+
+    // 2. 更新汇总统计（按IP+API密钥）
+    await db.query(`
+      INSERT INTO usage_aggregates
+      (api_key, client_ip, total_sessions, total_calls, render_markdown_calls, render_compact_calls,
+       first_used_at, last_used_at, updated_at)
+      VALUES ($1, $2, 1, $3, $4, $5, $6, $7, CURRENT_TIMESTAMP)
+      ON CONFLICT (api_key, client_ip) DO UPDATE SET
+        total_sessions = usage_aggregates.total_sessions + 1,
+        total_calls = usage_aggregates.total_calls + EXCLUDED.total_calls,
+        render_markdown_calls = usage_aggregates.render_markdown_calls + EXCLUDED.render_markdown_calls,
+        render_compact_calls = usage_aggregates.render_compact_calls + EXCLUDED.render_compact_calls,
+        first_used_at = LEAST(usage_aggregates.first_used_at, EXCLUDED.first_used_at),
+        last_used_at = GREATEST(usage_aggregates.last_used_at, EXCLUDED.last_used_at),
+        updated_at = CURRENT_TIMESTAMP
+    `, [
+      reportData.apiKey,
+      clientIp,
+      reportData.totalCalls,
+      reportData.renderMarkdownCalls,
+      reportData.renderMarkdownCompactCalls,
+      new Date(reportData.firstUsedAt),
+      new Date(reportData.lastUsedAt)
+    ]);
+
+    res.json({ success: true });
+  } catch (error) {
+    console.error('Usage report error:', error);
+    res.status(500).json({ error: 'Failed to save usage report' });
+  }
+});
+```
+
+## 📈 监控和分析
+
+### 关键指标
+- **每日活跃用户**: 基于唯一 IP 地址统计
+- **使用频率**: 平均每小时调用次数
+- **许可证采用率**: 配置许可证的用户比例
+- **功能使用分布**: renderMarkdown vs renderMarkdownCompact 调用比例
+- **会话统计**: 每个IP的平均会话数和总会话数
+- **跨部署使用量**: 按IP和API密钥汇总的累计使用量
+
+### 告警规则
+- 异常高频报告（可能表示滥用）
+- 许可证过期提醒
+- 服务器错误率监控
+
+---
+
+*最后更新: 2024年12月25日*