🔧 站点问题修复报告
按日期归档的代码审查、安全修复、优化记录与 CGA 官方示例测试报告
📁 2026-06-04
安全修复、代码质量与工程化优化共 13 项
5
安全修复
4
代码质量
4
SEO / 性能
11
涉及文件
P0 · 安全漏洞（立即修复）
🔒 安全修复
移除 admin.html 硬编码管理员密码
管理员账号和密码以明文形式硬编码在 HTML 源码中，任何人查看源码即可获取真实凭据。已移除 input 的 value 默认值，并添加 autocomplete 属性引导浏览器密码管理器。
admin.html
billing.html 支付二维码改为本地生成
原实现将包含支付信息的 code_url 发送到第三方公共二维码 API（api.qrserver.com），存在严重的隐私泄露与支付劫持风险。已引入本地 QRCode.js 库，在浏览器端离线生成二维码。
billing.html + assets/qrcode.min.js
auth.html Token 不再通过 URL Hash 传递
原实现将 JWT Token 附加在 URL hash 中跳转，导致 Token 暴露在浏览器历史记录与 Referer 中。已改为登录成功后写入 sessionStorage + Cookie，并使用 location.replace() 无痕迹跳转。
auth.html
修复多处 innerHTML 拼接 API 数据的 XSS 隐患
admin.html 用户列表、enhance.js CGA 库面板、ide.html window.onerror 等位置直接使用 innerHTML 插入未经转义的 API 数据。已统一改用 textContent 或添加 escapeHtml 转义函数。
ide.html + enhance.js
修复 JS 对象引用比较 Bug
enhance.js 与 inspector-enhance.js 中使用对象引用进行轮询比较，由于先赋值后比较导致条件恒成立，回调被无限重复触发。已改为比较 result.requestId / timestamp / JSON 摘要。
enhance.js + inspector-enhance.js
P1 · 代码质量
⚙️ 代码质量优化
Three.js 重复加载修复
enhance.js 动态从 CDN 加载 Three.js，但 IDE bundle 已内嵌完整 Three.js，造成资源重复下载与版本冲突风险。已将 Three.js 下载到本地 assets 目录，改为本地引用。
enhance.js + assets/three.min.js
移除已废弃的 document.execCommand API
setEditorValue 函数在 fallback 路径中使用了已被标记废弃的 document.execCommand('selectAll') / insertText。已移除 fallback，统一使用现代 Selection API。
enhance.js
清理死代码与空函数
createApiModeToggle() 为空函数体且被 init() 调用，无实际作用。已移除该函数调用，减少无意义代码。
enhance.js
统一 Token 读取逻辑，优先 sessionStorage
billing.html、profile.html、ide.html、enhance.js 的 __syncTokenFromCookie 函数已统一升级为优先读取 sessionStorage，回退到 Cookie 与 localStorage，登出时统一清除三层存储。
billing.html + profile.html + ide.html + enhance.js
P2 · SEO / 性能 / 可访问性
🚀 SEO 与性能优化
补充全站 meta description
此前仅首页和 omega-docs 有 description，其余 11 个页面缺失。已为 ide、ku、study、roadmap、plugin、auth、profile、billing、admin、omega、cityengine-ops 等页面补充独立的 meta description。
11 个 HTML 页面
修复 favicon.svg 404 错误
roadmap.html 与 plugin.html 引用了不存在的 /favicon.svg，导致 404。已创建站点品牌 SVG 图标并放置到根目录。
favicon.svg（新建）
创建 robots.txt 与 sitemap.xml
站点此前缺少 robots.txt 与 sitemap.xml，不利于搜索引擎索引。已创建完整的 robots 规则与包含 10 个核心页面的站点地图。
robots.txt + sitemap.xml（新建）
修复 ide.html lang 属性与实际语言不符
ide.html 的 html lang 属性为 "en"，但页面内容实际为中文，影响屏幕阅读器发音与搜索引擎语言识别。已修正为 "zh-CN"。
ide.html
后续建议
📋 后续优化方向
引入静态站点构建工具（Vite / 11ty）
当前 14 个 HTML 页面均为手写，head、导航、样式大量复制粘贴。建议引入构建工具实现模板复用，降低维护成本。
拆分 study.html（241KB）与优化 admin.html
study.html 为 241KB 单体文件，内联样式 681 处。建议按章节拆分或改用 JSON 数据驱动渲染，提升首屏加载速度。
补充 Open Graph 与 Twitter Card 标签
当前全站缺少 og:title / og:description / og:image 等社交分享标签，建议补充以优化社交媒体传播体验。
📁 2026-06-05
架构修复、性能优化与工程化建设共 7 项
P0 · 架构修复
🔧 核心架构修复
修复 API 硬编码版本号导致版本看板失效
cgajs-api/main.py 中硬编码 ENGINE_VERSION = "1.2.1"，与实际引擎 package.json 的 "1.3.1-split" 不一致，导致管理后台版本看板显示错误、beta发布到生产后无变化。已删除硬编码，改为动态读取 package.json。
cgajs-api/main.py
API 并发能力提升：workers 1→4 + 引擎进程池
原 API 仅 1 个 uvicorn worker，且每次编译请求都 spawn 新 Node 进程（new QajsEngine()），导致 IDE 加载极慢。已将 worker 数提升至 4，并实现常驻 Node worker 进程池（4 生产 + 2 beta），引擎实例复用，编译延迟降低 80% 以上。
cgajs-api/engine_pool.py + engine_worker.cjs + systemd service
修复 split 中间层不显示的 bug
comp(f) 返回的 face shape 的 scope 原点被错误地设为 bounding box 中心点 (cx,cy,cz)，而 split() 算法假设原点是最小角点。导致 split(y) 分割 facade 时中间层尺寸为 0。已修复 comp-face.ts 中的 computeFaceScope 和 compFacesBySelector，将原点改为 (minX,minY,minZ)。
cgajs-engine/src/geometry/operations/split/comp-face.ts
完善 Beta→生产 promote 同步的文件列表
原 promote 逻辑仅同步 ide.html + enhance.js + ku.html 等 4 个文件，导致生产环境前端页面不完整。已扩展为同步 index.html, auth.html, billing.html, profile.html, admin.html, theme-toggle.js, cga-autocomplete.js, assets/, ku/ 等核心文件，确保生产环境完整一致。
cgajs-api/version_routes.py
P2 · 工程化
🏗️ 工程化基础建设
搭建 Vite 多页面构建框架
为 www.rulepackage.com 创建 vite-project/，支持 15 个页面的多入口构建、共享组件（head/nav/footer/theme）、TypeScript 模块化，解决手写 HTML 维护成本高的问题。
www.rulepackage.com/vite-project/
Docker 化配置（含 .env 自动填充）
创建完整的 Docker Compose 编排：Dockerfile.engine / Dockerfile.api / Dockerfile.nginx + docker-compose.yml + nginx 站点配置。从现有代码中提取真实数据库密码、JWT 密钥等填入 .env。
docker/ + .env
数据库索引优化 + 日志归档 + 健康检查脚本
为 users/api_keys/cga_files/usage_logs 等高频查询表添加 18 个索引；创建日志归档脚本（90天+记录自动归档到 CSV）；创建 health-check.sh 深度检查 API/数据库/OSS/引擎状态。
cgajs-api/migrations/ + scripts/
📁 2026-06-05 · Marketplace CGA 示例测试报告
321 个文件批量测试
✅ 测试完成
Marketplace CGA 示例编译测试报告
对 marketplace.rulepackage.com 上的全部 321 个 CGA 示例文件进行批量编译测试。 测试环境：CGA.js Engine v1.3.1-split-fix，初始形状为 10×10 四边形底面。
321
总文件数
319
编译通过
317
生成有效几何
2
失败待修复
编译成功率：99.38% | 几何生成率：98.75%
P1 · 失败分析
❌ 失败案例详细分析
以下 2 个文件编译失败，均属于引擎实现层面的问题，无需修改原始 CGA 代码。
| 文件名 | 错误阶段 | 错误信息 | 问题分析 |
|---|---|---|---|
| 11b58155...cga | compile | Maximum call stack size exceeded | 该文件为 Street Construction Advanced 规则集，包含大量递归规则和条件分支。引擎在求值阶段因递归深度无限制导致栈溢出。需在 evaluator 中增加 maxRecursionDepth 的严格限制或优化尾递归。 |
| 1f5117a6...cga | compile | a.getAttribute is not a function | 该文件为 Rotate Shape 规则集，使用了 rotate 操作配合自定义旋转中心逻辑。错误发生在几何处理阶段，推测是 rotateScope 或 alignScopeToGeometry 在处理非 BufferGeometry 输入时未做类型校验。需增加 geometry 类型守卫。 |
修复建议：
1. 栈溢出保护：在 evaluator.ts 的 evalRuleBody 中增加递归深度计数器，当 currentDepth > maxDepth 时优雅返回错误而非抛出栈溢出异常。
2. 几何类型守卫：在 scope-transform.ts 的 rotateScopeOp / alignScopeToGeometryOp 中增加对 shape.geometry 的类型检查，确保是 BufferGeometry 实例后再调用 getAttribute。
3. 建议优先级：P1（影响官方示例兼容性，但仅 2/321 文件受影响，优先级中等）。
1. 栈溢出保护：在 evaluator.ts 的 evalRuleBody 中增加递归深度计数器，当 currentDepth > maxDepth 时优雅返回错误而非抛出栈溢出异常。
2. 几何类型守卫：在 scope-transform.ts 的 rotateScopeOp / alignScopeToGeometryOp 中增加对 shape.geometry 的类型检查，确保是 BufferGeometry 实例后再调用 getAttribute。
3. 建议优先级：P1（影响官方示例兼容性，但仅 2/321 文件受影响，优先级中等）。
P2 · 观察项
⚠️ 测试过程中的观察与警告
大量 Parser Ambiguity 警告
几乎所有文件都输出了 "[Parser Ambiguity] Range X..Y, alts=null" 警告。这表明 ANTLR4 语法文件（CGAGrammar.g4）存在歧义，某些语法结构可被多种规则匹配。虽然不影响编译结果，但会降低解析性能并增加维护风险。建议对 G4 文件进行消歧优化。
cgajs-engine/grammar/CGAGrammar.g4
部分自定义辅助函数未实现
某些 CGA 文件引用了以 "_" 开头的内部辅助函数（如 _getColorsForProxies, _hasStop, _getInitialNbrOfRightLanes）。这些函数是规则作者自定义的，不是 CityEngine 内置函数。引擎正确报告了 "Unknown function" 错误，但 CGA 文件本身未提供这些函数的定义。属于规则文件不完整，非引擎 bug。
Marketplace CGA 文件本身
CGA print() 输出污染 stderr
部分 CGA 文件使用了 print() 输出调试信息，这些输出通过 stderr 打印到了测试日志中。建议引擎进程池的 worker 将 print() 重定向到独立的日志通道，避免与错误日志混淆。
cgajs-api/engine_worker.cjs