XuqmGroup-Symbolicator/docs/IMPLEMENTATION_HANDOFF.md

Symbolicator 实施交接

当前架构

• src/index.ts：Express 应用工厂、公共中间件、健康检查和统一错误边界。
• src/routes/symbolicate.ts：认证和 /api/symbolicate 路由编排。
• src/parsers/：各平台解析器；路由层不复制解析规则。
• test/：使用 Node 内置测试运行器验证 HTTP 契约和关键解析器。
• Dockerfile：Node 24 LTS 多阶段、锁文件安装、非 root 运行和容器健康检查。

本次现代化决策

1. Express 5、source-map 0.8 和 TypeScript 7 已通过当前源码构建与契约测试，不保留旧版 并行实现。
2. multer 升级到 2.2.0，消除旧依赖链安全问题；当前没有 multipart HTTP 契约，因此不注册 上传中间件。
3. 全局请求体上限由 200 MiB 收敛为 105 MiB，覆盖现有 100 MB mapping 业务上限且避免 无边界内存占用。
4. 应用工厂使测试无需修改全局环境变量或占用固定端口；生产入口仍是 node dist/index.js。
5. 错误日志只记录错误类型，不记录请求体、凭据、符号文件和用户提供的路径。

接手验证

npm ci
npm run check
npm audit --audit-level=low
docker build -t xuqm-symbolicator:local .

最后一项仅在 Docker daemon 可用时执行。iOS atos 和 Flutter SDK 不属于该 Linux 镜像，相关平台仍需在具有对应工具链的实际运行环境单独验证。

2026-07-27 验证记录

• npm ci：通过，安装过程的依赖安全审计为 0 个漏洞。
• npm run check：通过，共 8 项构建、HTTP 契约、解析器、安全和 Dockerfile 静态测试。
• npm start + GET /health：构建产物启动成功并返回既有健康响应。
• node:24.18.0-alpine：官方镜像清单包含 amd64、arm64 和 s390x。
• docker build：未执行；本机安装了 Docker CLI，但 Docker daemon 未运行。
• iOS/Flutter 外部工具链：未验证；当前 Linux 容器不提供 atos 和 Flutter SDK。
• Jenkins xuqmgroup-symbolicator #9：通过。Windows 节点完成容器构建、生产部署、 版本 1.0.5 提交和 SSH 推送；一次性 git-ssh.cmd 已在凭据作用域结束时删除。

禁止事项

• 不得恢复 npm install 容器构建或忽略锁文件。
• 不得把 Jenkins 仓库地址改回包含 Token 的 URL；现有 SSH credentials 方案是基线。
• Windows Jenkins 的 OpenSSH Agent 以系统服务运行，ssh-agent Pipeline 插件无法解析 其空输出；Git 推送必须通过 sshUserPrivateKey 临时文件和当前进程 GIT_SSH_COMMAND 使用密钥，禁止退回凭据化 URL。
• 不得在日志中输出认证信息或完整异常输入。
• 不得在没有显式限额与清理策略时启用 multipart 上传。