19 KiB
19 KiB
现有功能 → MCP 覆盖与验证矩阵
盘点来源：App.tsx、Calendar、SchedulePanel、MetalPanel、IconLibrary、TransferForm、DebtPaymentForm、GroupOrderList 及所有 API Controller 路由。架构沿用 NestJS/Express/Prisma/MySQL/Zod，不新增消费账本或 AI 框架。
验证记号：M test/mcp.test.ts 第一组真实官方 SDK/MySQL；C 第二组并发/图标/密码修改；O 第三组 OAuth；R 原 17 组真实 REST/MySQL 回归；U 原单元计算/行情/ZIP 测试。均有实际业务断言。M 中公共刷新验证无需要更新资产时的真实调用；外部行情响应和失败回退由 U 验证，未声称行情供应商稳定可用。
普通写入需要 draft 或 write，且受用户 readonly/draft/direct 策略约束；敏感操作额外要求 sensitive 并强制网页确认。所有写入工具要求幂等键和 expectedState。每项都先检查可信用户归属；annotations 不替代权限。
| 现有页面/API 与功能 | MCP 操作路径 | 权限 | 确认方式 | 验证 |
|---|---|---|---|---|
| 账户/独立资产/债务列表 GET positions | positions_list：kind、名称、归档、方向、币种、分组、排序、offset/limit | read | 无 | M：查询、重名、分页和外用户隔离 |
| 项目详情 GET positions/:id | position_get | read | 隐藏项目须连接独立网页解锁 | M：当前余额、隐藏/外用户拒绝 |
| 创建项目 POST positions | position_create，保留账户/资产/债务初始绝对余额语义 | draft/write | 策略决定草稿或直接 | M/C：3 类对象、重复调用、无效金额、并发 |
| 元数据、分类、分组、图标、归档/恢复、隐藏、计入开关 PATCH positions/:id | position_update，完整 metadata；币种与方向固定 | draft/write | 策略 | M：分组、归档禁止金额更新与恢复；R：隐藏和开关 |
| 分组拖拽排序 PATCH settings | settings_update.accountGroupOrder | draft/write | 策略 | M/R：持久化、排序、备份 |
| 类别选项、名称与分组配置 | position_create/update；positions_list 读取现有值，Schema/描述提供规则 | read + draft/write | 策略 | M/R；当前没有独立分类/分组实体 CRUD |
| 新增余额、资产估值、负债余额及单边还款 POST revisions | balance_record，reason 区分；amount 为变更后余额 | draft/write | 策略 | M：精确余额；R/U：负债、估值、业务时间 |
| 历史全局/单项目 GET history、positions/:id/history | history_list.positionId、cursor、from/to | read | 无 | M/R：页大小、游标、前序余额、日期范围 |
| 更正普通历史 PUT revisions | history_update | draft/write | 策略 | M/R：重放、精度、日历联动 |
| 删除/撤销历史 DELETE revisions | history_delete；配对记录删除完整双边 | draft/write | 策略，destructive annotation | M/R：余额重算及双边撤销 |
| 债务关联账户/资产 PUT links | debt_links_set.targetIds | draft/write | 策略 | M：合法关联、隐藏目标拒绝；R：外用户拒绝 |
| 资金往来列表 GET transfers | movements_list：cursor、日期过滤 | read | 无 | M/R |
| 按历史找双边记录 GET transfers/revision/:revisionId | movement_by_revision | read | 无 | M/R |
| 转账、借入、借出、收款、还款 POST transfers | movement_create.operation：transfer/borrow/lend/collect/repay | draft/write | 策略，双边事务 | M：转账、repay、信用卡溢缴；R：全部 5 种语义；C：错误回滚 |
| 修改配对记录 PUT transfers/:id | movement_update | draft/write | 策略，后续历史重放 | M/R |
| 删除/撤销配对记录 DELETE transfers/:id | movement_delete | draft/write | 策略，双边撤销 | M/R |
| 净资产、总额、结构、变化归因 GET overview | overview_get，明细分页、保留全局总额 | read | 隐藏项目按本连接可见范围 | M/R/U：总额、开关、外币缺失 |
| 轨迹、日期与统计粒度 GET trend | trend_get：day/week/month 及 from/to | read | 无 | M/R/U：范围、首日、期末、归因 |
| 本位币、币种、实际汇率与更新状态 GET settings | settings_get，固定币种枚举且金额无浮点计算 | read | 无 | M/R/U |
| 本位币切换、显示菜单、备注、闲置退出、登录时长、总览卡片、独立资产计入 PATCH settings | settings_update | draft/write | 策略 | M/R |
| 是否查看隐藏资产需密码 PATCH settings | settings_update.requireHiddenPassword | sensitive | 强制网页密码确认 | M：draft 权限无法改变；R：会话锁定规则 |
| 自动/重试日汇率 POST rates/refresh | rates_refresh；已有后台定时更新保留 | draft/write | 策略 | M：真实工具调用；U：成功解析、手工优先、失败保留 |
| 金银报价与状态 GET metals | metals_prices，最近 100 条 | read | 无；查询 MCP 不触发隐式自动更新 | M/U/R |
| 金银报价刷新 POST metals/refresh | metals_refresh | draft/write | 策略，沿用自动估值 | M：无配置资产调用；U：外部响应和失败回退 |
| 每克报价手动回退 POST metals/prices | metal_price_set，Decimal 价格 | draft/write | 策略 | M/R/U：手动优先、精确估值 |
| 克数、品种、纯度、自动估价 PUT metals/:id | metal_configure | draft/write | 策略 | M/R/U：估值历史和去重 |
| 应用估价 POST metals/:id/value | metal_value | draft/write | 策略 | M/R/U |
| 收支月日历 GET calendar | calendar_month，YYYY-MM | read | 无 | M/R/U |
| 单日日历明细 GET calendar/day | calendar_day，业务日和分页 | read | 无 | M/R/U：历史修改、转账排除、Decimal |
| 计划列表/状态 GET schedules | schedules_list，按到期排序分页；history_list 查看执行历史 | read | 无 | M/R |
| 新建/修改支出或转账计划 POST/PUT schedules | schedule_create/update | draft/write | 策略 | M/R：真实执行及编辑限制 |
| 启用/停用 PATCH schedules/:id | schedule_toggle | draft/write | 策略 | M/R |
| 删除计划 DELETE schedules/:id | schedule_delete，保留执行历史 | draft/write | 策略 | M/R |
| 按需运行到期计划 POST schedules/run | schedules_run，最多 20 项、hasMore；MCP 失败整批回滚 | draft/write | 策略，幂等事务 | M/C/R/U |
| 登录个人资料 GET auth/me | settings_get；connection_info 提供 Agent 授权资料 | read | 无 | M/C |
| 修改用户名和密码 PATCH auth/credentials | credentials_change_request → 网页 → operation_get | sensitive | 网站验证当前密码、输入新值，Agent 不收到密码 | C/R：真实密码登录、原会话轮换、Agent 降权结果查询 |
| 隐藏资产密码核验 POST auth/reveal | hidden_unlock_request → 网页 → operation_get | sensitive | 网页当前密码，当前连接 5 分钟 | M/R：锁定、隔离、失效规则 |
| 锁定隐藏资产 POST auth/lock | hidden_lock | draft/write | 策略；也可网页锁定 | M/R |
| 退出登录 POST auth/logout | connection_revoke 退出当前 MCP 连接；网页退出仍在原页面 | 当前连接认证 | 撤销是即时缩小授权，不受写入策略阻碍 | M/O/R：后续 401 |
| 注册/登录、网页 activity | OAuth 网页入口复用原注册/登录，Agent 令牌不依赖网页 Cookie；activity 为网页会话维护 | 网页认证/OAuth | 用户登录或注册及授权 | O/R、浏览器验证管理入口 |
| 图标搜索 GET icons | icons_list，60/页、q | read | 无 | M/C/R |
| 图标图片 GET icons/:id/image | icon_image → 同连接 Bearer GET | read | 无 | C/R：PNG 和归属 |
| 上传图标 POST icons/upload | file_upload_request(kind=icon) → POST file → icon_publish | draft/write；共享须 sensitive | 私有按策略；共享网页确认及中文名 | C/R：私有和共享实际保存 |
| 导出备份 GET backup | backup_export → 网页 → operation_get → Bearer 下载 | sensitive | 网页密码，短期授权入口 | M/R：完整 ZIP、隐藏数据、令牌排除、跨用户及未登录拒绝 |
| 上传备份 POST backup/upload | file_upload_request(kind=backup) → Bearer multipart → file_status | draft/write | 用户控制上传；不提交账目 | M/R：真实 ZIP 传输 |
| 预检 POST backup/preview | import_preview(token)，上传同时预检 | read（上传需要 draft/write） | 不修改账目 | M/R/U：结构/校验/重复/冲突 |
| 追加恢复 POST backup/import、import-file | backup_import(token) → 网页 → operation_get | sensitive | 强制网页密码及数量/冲突预览 | M/R：真实恢复、重复冲突不改变数据 |
| 清空资格 GET backup/clear-status | data_clear_request 网页确认时复用现有备份资格及指纹 | sensitive | 网站先下载最新备份 | M/R |
| 清空财务数据 POST backup/clear | data_clear_request → 网页 → operation_get | sensitive | 密码、备份指纹及“确定清空” | M/R：未下载拒绝、真实清空、保留账号 |
| 新增接入管理、权限、PAT、撤销、调用日志和待确认页 | /api/agent 管理；connection_info、operation_get、state_get；OAuth 标准路径 | 网站身份/本连接 Bearer | PAT/策略验证密码；操作归属校验 | M/C/O、真实浏览器管理页 |
不存在的业务不列作“已实现”：单个持仓永久删除、账户注销、覆盖导入、批量删除、独立分类/分组对象 CRUD 均不在当前页面/API 中。历史删除、资金往来撤销、计划删除、归档及备份保护清空全部已有路径均已覆盖。
共享服务：PortfolioBusinessService、TransfersBusinessService、SchedulesBusinessService、CalendarBusinessService、SettingsBusinessService、MetalsBusinessService、IconsBusinessService、BackupBusinessService、AuthBusinessService。REST Controller 仅转发并保留原参数、文件拦截器、认证和路由；SDK Catalogue 调用同一服务，不复制金额或重放。
金额状态、OAuth、scope、Origin/Host、文件生命周期和客户端限制见 接入文档。当前官方客户端验证通过；未验证其他产品配置和生产 HTTPS 反向代理。