4.1 KiB
贵金属克数与数据库注释更新
历史验收记录：2026-10-04 起所有旧备份兼容与单文件 JSON 支持已删除，当前仅接受 ZIP v9；本文旧版本测试记录不代表现行功能。现行 MCP 权限与工具范围见 本次更新。
独立资产新增弹窗选择「贵金属」后，填写黄金/白银、克数、纯度、原币和业务时间，无需填写金额或市场单价。默认随参考价自动估值；没有有效报价时为「待估值」，总览提示不完整，不把未知价值作为已知零值。后续自动/手动报价继续沿用现有 MetalsService 和历史逻辑。
买入价为可选的每克实物成本（原币）。成本 = 总克数 × 买入价；估值 = 总克数 × 纯度 × 对应币种纯金属每克报价；盈亏 = 当前估值 − 成本。全程 Decimal，金额 8 位小数四舍五入；每克成本最多 12 位整数、12 位小数且必须大于零。它是估值盈亏，不包含未记录的税费/已实现卖出收益。省略或清空价格不显示盈亏，缺少估值时盈亏待定。旧贵金属资产可在详情补充成本。
服务、备份和 MCP
REST POST /api/metals/holdings 与 MCP metal_holding_create 共用 MetalsBusinessService.create；无需 amount。现有 PUT /api/metals/:id 与 metal_configure 接受可选 metalCostPerGram，省略保留、null 清除。position 查询返回 valuationAvailable、metalCost、metalProfit。前端只展示服务端结果，不以 Number 计算盈亏。
ZIP v8 增加可选成本字段，既有备份缺少字段仍可验证恢复；配置、成本和估值历史保持用户隔离。新 MCP 工具遵循服务端草稿、确认、幂等与并发规则，工具总数为 49。
迁移和启动
- 20261003120000_metal_cost：Position 增加可空 DECIMAL(24,12) metalCostPerGram，附中文字段注释，不回填未知成本。
- 20261003130000_migration_comments：为 Prisma 自己的迁移表和 8 个字段补齐注释，保持实际类型、可空性和默认值。
- 前一 MCP 提交已新增 20261003090000_agent_access、20261003100000_agent_audit、20261003110000_agent_comments。
全部 migration deploy 已在当前 MySQL 实际执行，累计 22 个迁移。scripts/check-comments.cjs 验证所有 17 张表、159 个字段均有注释，清单见 database-comments.json。无新增环境变量；启动命令见 MCP 文档。先暂停 API，再 db:generate、db:migrate，然后 dev；不使用 reset。
实际验证
- 前后端 typecheck/build 通过。
- 36 项单元测试通过：待估值完整性、精确克数成本、行情/失败回退、原计算和 ZIP 等。
- 18 组真实 REST/MySQL 测试通过：无价格克数创建、拥有报价创建、精确盈亏、成本保留/清除、外用户拒绝、无效克数拒绝、新备份恢复和旧备份兼容，以及原业务回归。
- 3 组官方 SDK/MySQL MCP 测试通过：包含新增克数工具真实写入和查询；原 OAuth、确认、幂等、并发与失败回滚继续通过。
- 2026-10-03 22:55（UTC+8）用户授权后，使用临时本地账号完成真实浏览器验证：黄金/白银按克数创建；不填市场价格或买入价也能保存；初始待估值；保存/清空买入成本；现有估值历史显示；报价自动更新后的详情同步。2.5 克 × 纯度 0.8 × 测试报价 20 = 40 CNY；每克买入价 12.8 得成本 32 CNY、盈亏 8 CNY。
- 浏览器发现并修复报价已完成但父页面金额仍待估值的问题：MetalPanel 轮询离开 updating 状态时刷新持仓和历史，回调使用 ref 保持当前引用。真实白银报价完成后，无需点击刷新即可显示估值、成本、盈亏与历史。
- 修复后前端 typecheck 和生产 build 再次通过。另通过 Prisma 检查浏览器写入持久化结果，并清理临时用户、两个测试持仓、报价和登录会话。截图保存在独立验证目录，没有写入 docs。
- 已有 MCP 管理页在前一阶段已浏览器验证。其他商业 Agent 客户端和生产代理部署仍未验证。
本次不部署、不推送、不改本地 .env，也不把图片保存进 docs。