# moras-A2A · 已落地能力 + 当前路线图

> 本文件原为 4 个 Phase 的开发设想；Phase 1-4 已经全部上线，此处改写为
> **已交付清单 + 当前路线图**，避免与代码事实漂移。
> 历史完整设想见 git history `git log -- docs/PLAN.md`。

---

## 一、定位（一句话）

把 Moras 体系内已生产的爆款 KOC 视频，通过 4 种适配方式（Skills /
A2A JSON-RPC / OpenAPI / 薄 MCP）塞进 7 个外部 Agent 平台。
**REST API 是唯一事实源**，每笔成交通过短链 `selltoai.ai/r/:recId` 回写归因。
moras-api 完全不动；moras-bi 通过 ETL JOIN `attribution_*` 表拿渠道维度 GMV。

完整业务拓扑、数据库表、归因流程图见仓库根 [README.md](../README.md)
与 [docs/AGENT_WORKFLOW_HANDBOOK.md](AGENT_WORKFLOW_HANDBOOK.md)。

---

## 二、已落地能力清单（核对源码）

### 2.1 Phase 1 · REST 事实源 + 短链 ✅

- 仓库骨架、Express 入口、PM2 ecosystem
- 数据库：`pcd_cards` / `attribution_clicks` / `attribution_orders` /
  `intent_requests` / `intent_proposals` / `match_sessions` / `match_tokens` /
  `merchant_*` / `developer_api_keys` / `commerce_agents` 等
  （详见 [src/db/schema.sql](../src/db/schema.sql)）
- PCD schema + Builder：[src/pcd/schema.js](../src/pcd/schema.js)、
  [src/pcd/builder.js](../src/pcd/builder.js)
- 直读 ai_autocut + ai_tkshops + moras_bi（沿用 harness.js 模式）
- REST API + OpenAPI 3.0 规范：[src/rest/](../src/rest/) 与
  [public/openapi.json](../public/openapi.json)
- 短链与落地页：[src/redirect/server.js](../src/redirect/server.js)
  （`/r/:recId` 写点击 → 302 联盟 URL；`/v/:recId` SSR 多视频聚合页）

### 2.2 Phase 2 · Skills + A2A + Gemini ✅

- `moras-shop` Skill 包：[skills/moras-shop/SKILL.md](../skills/moras-shop/SKILL.md)
  + 多份 `examples/`，覆盖 OpenClaw / Claude Code / Cursor / Codex
- A2A JSON-RPC 2.0：[src/a2a/](../src/a2a/) `POST /a2a` + Agent Card
- Agent Card 暴露 **14 个 skill**（见 [src/a2a/agentCard.js](../src/a2a/agentCard.js)）：
  1. `recommend_products`
  2. `submit_intent`
  3. `submit_proposal`
  4. `get_match_result`
  5. `accept_match`
  6. `list_commerce_agents`
  7. `get_commerce_agent`
  8. `record_decision_event`
  9. `prepare_experience_feed`
  10. `run_commerce_runtime`
  11. `run_agentic_checkout`
  12. `get_product_card`
  13. `get_creator_showcase`
  14. `lookup_card`
- 渲染层：[src/render/](../src/render/) markdown / chatgpt-apps / a2a artifact
- Gemini Extension manifest 直指 `public/openapi.json`，Gemini 自动渲染富响应

### 2.3 Phase 3 · 归因 + 报表 + MCP ✅

- TikTok Shop 联盟 webhook ingest：[src/attribution/webhookIngest.js](../src/attribution/webhookIngest.js)
- Daily fuzzy-match 兜底对账：`npm run cron:reconcile`
  （[src/attribution/dailyReconcile.js](../src/attribution/dailyReconcile.js)）
- ROI / 渠道 / 归因报表（Supply Key 鉴权）：
  [src/attribution/reportApi.js](../src/attribution/reportApi.js)
- 薄 MCP 包装：[bin/mcp.js](../bin/mcp.js)（包名 `moras-a2a-mcp`，
  全部 tool 转调 REST，不持有业务逻辑）

### 2.4 Phase 4 · 生产化 ✅

- 限频 token bucket（per-channel + per-IP）：[src/auth/rateLimit.js](../src/auth/rateLimit.js)
- 反作弊：24h 同 `ip_hash + UA + rec_id` 去重 + CTR 异常自动降权
  （[src/redirect/antiAbuse.js](../src/redirect/antiAbuse.js)）
- Region 隔离：CF-IPCountry / X-Country header
  （[src/auth/regionGate.js](../src/auth/regionGate.js)，配 `REGION_BLOCKLIST`）
- Prometheus metrics：[src/utils/metrics.js](../src/utils/metrics.js) `/metrics`
  暴露 `http_*`、`pcd_build_total`、`redirect_clicks_total`、`cache_hit_total`、
  `attribution_orders_total`、`api_auth_fail_total`、`api_key_request_total`、
  `commerce_events_total`、`merchant_delivery_total`
- PM2 上线：[ecosystem.config.js](../ecosystem.config.js) + `deploy.sh`

### 2.5 Phase 5+ · Commerce Loop（已上线，不在原 4 Phase 内）✅

- Intent → Proposal → MatchSession → MatchToken → Attribution Outcome
  五段链路：[src/exchange/service.js](../src/exchange/service.js)
- MatchToken HMAC-SHA256 签名 + 短链注入 `?mt=`
- Merchant Agent Registry + Webhook delivery：[src/merchant/](../src/merchant/) +
  [src/agents/](../src/agents/)
- Commerce Proof Feed `/v1/proof-feed`：从 `moras_bi.dwd_video_pipeline`
  归一化为 `moras://commerce-proof/{asset_id}`
- Community proof 通道（Reddit / 论坛证据）：[src/communityProof/](../src/communityProof/)
- Developer Console + Bearer API key + Invite Code 生命周期：
  [src/developers/](../src/developers/) + [src/auth/apiKey.js](../src/auth/apiKey.js)
- Portal v4：home / try / proof / connect / merchants / developers / reference /
  status / ops 共 9 页（见 [src/portal/pages/](../src/portal/pages/)）
- Pino 结构化日志统一：[src/utils/logger.js](../src/utils/logger.js)

---

## 三、当前路线图（Roadmap）

按"用户感知度 × 风险度"排，每一项独立可立项。

### 3.1 Portal 全站对齐 ✅（本轮 Wave 1 已完成）

- 抽 `lp-page-hero` / `lp-platforms-strip` / `lp-chain-steps` /
  `lp-next-steps` 共享组件到 `public/portal/portal.css`
- try / proof / connect / merchants / developers / reference / status / ops
  hero 全部统一到 lp-* 设计语言
- 五段链路叙事在 try / proof / merchants 完整呈现
- ops.js / status.js / merchants.js 内联中英对照搬入 i18n.js
- connect / developers / merchants 各加"清晰下一步"CTA row

### 3.2 P0 工程债 ✅（本轮 Wave 2 已完成）

- `.env.sample` 补 `MATCH_TOKEN_SIGNING_SECRET` /
  `MERCHANT_WEBHOOK_SIGNING_SECRET`，`signingSecret()` 报错指引到 .env.sample
- `db/pool.js` `morasQuery` 解耦：只看 moras 池自身 stub，加 3 条单测
- `pcd_build_total` / `redirect_clicks_total` / `cache_hit_total` 三个
  Prometheus 指标接 `inc()` 调用
- `events/broker.js` 切 pino + 结构化字段（topic / subscriberId / lag）

### 3.3 文档收敛 ✅（本轮 Wave 3 已完成）

- 重写本文件
- `PLATFORM_INTEGRATION.md` MCP 包名校正、ChatGPT Phase 3 叙述清理
- 测试矩阵数字以 README 为单一事实源
- 新建 [docs/RUNBOOK.md](RUNBOOK.md) 与 [docs/SECURITY_MODEL.md](SECURITY_MODEL.md)，
  `coding-tasks/TEST-REPORT.md` 加历史快照声明

### 3.4 工程结构演进（本轮 Wave 4 增量进行中）

- ✅ **Wave 4.1 (exchange god-module 拆分完成)**：原 2391 行
  [src/exchange/service.js](../src/exchange/service.js) 拆为 7 个聚焦子模块 +
  facade re-export，零行为变更：
  - [matchToken.js](../src/exchange/matchToken.js) · 签名 / 校验（+ 12 单测）
  - [_shared.js](../src/exchange/_shared.js) · state + helpers + normalizers + CRUD
  - [intent.js](../src/exchange/intent.js) · createIntent + dispatch 调度
  - [proposal.js](../src/exchange/proposal.js) · proposal CRUD + 评分 + Moras 自营合成
  - [matchSession.js](../src/exchange/matchSession.js) · session/token 颁发 + PCD 渲染
  - [feedback.js](../src/exchange/feedback.js) · feedback / reputation / decision events
  - [merchantDelivery.js](../src/exchange/merchantDelivery.js) · Intent.Surge 商家分发 + DLQ
  - [settlement.js](../src/exchange/settlement.js) · commerce runtime + agentic checkout
  - service.js 收敛为 facade（仅保留 `recommendFromRawIntent` 协调器）
  - 测试矩阵全绿：264/264（102 unit + 160 integration + 2 e2e）
- ✅ **Wave 4.2 (db migrations 框架)**：新建 [src/db/migrations/](../src/db/migrations/)
  目录、[src/db/migrationRunner.js](../src/db/migrationRunner.js) 与 8 个新单测；
  `npm run db:init` 末尾顺带跑 `runMigrations`，记录到
  `db_migrations(version, name, checksum, applied_at)`
- ✅ **Wave 4.3 (merchant registry 标记 deprecated alias)**：
  `/v1/merchant/*` 路由响应一律带 `Deprecation: true` 与
  `Link: </v1/agents/...>; rel="successor-version"`，进程内首次命中打 warn 日志；
  registry 模块头部注释指向 [src/agents/registry.js](../src/agents/registry.js)；
  实际 schema 合并留独立 PR
- ✅ **Wave 4.4 (a2a/runtime.js persistTask 错误处理对齐)**：DB error 改为
  `log.warn + metric.inc('a2a_persist_fail')`，与其它 DB 封装风格一致
- ✅ **Wave 4.5 (历史路线图盘点 + 缺口收口)**：
  - **recommend 降级 demo**：REST `/v1/recommend` 走 `recommendPool.demoFallbackRows`
    已在历史 PR 落地；本轮把 [src/a2a/messageSend.js](../src/a2a/messageSend.js)
    `recommend_products` skill 的早退 `intent_engine_unavailable` 移除，A2A 调用
    与 REST 行为一致，Gemini 不可用时 metadata 携带 `intent_source: demo_fallback`
    + `degraded: true`。新增 [tests/unit/messageSend.test.js](../tests/unit/messageSend.test.js)
    断言覆盖
  - **MatchToken `/verify` 端点**：[src/rest/matchTokens.js](../src/rest/matchTokens.js)
    已实现 `GET /v1/match-tokens/:id/verify` + `POST /:id/payment-authorization`，
    与 [src/exchange/matchToken.js](../src/exchange/matchToken.js) HMAC 配套
  - **MCP 按需加载**：[src/mcp/server.js](../src/mcp/server.js) `discover_tools`
    bootstrap 模式已上线，工具按需 `registerTool`
  - **EventBroker 推送**：`POST /events/subscribe`（X-Supply-Key 鉴权）+
    `broker.publish` HTTP fanout 已可用，pino 结构化日志覆盖订阅 / 投递路径

---

## 四、不会动的边界

- `cta.primary.url` 透传（带 `recId` + 可选 `?mt=matchTokenId`）
- 归因主键 `recId` 路径
- [src/pcd/schema.js](../src/pcd/schema.js) 的字段
- 不调用 moras-api，所有数据从 ai_autocut / ai_tkshops / moras_bi 直读
- 生产 PM2 配置 / 真实 `.env` / `X-Supply-Key`

---

## 五、相关文档索引

- [README.md](../README.md) — 仓库总入口与测试矩阵单一事实源
- [docs/AGENT_WORKFLOW_HANDBOOK.md](AGENT_WORKFLOW_HANDBOOK.md) — 角色与流程手册
- [docs/INTENT_MATCHING_PROTOCOL.md](INTENT_MATCHING_PROTOCOL.md) — 意图与撮合协议
- [docs/AGENTIC_CHECKOUT_PROTOCOL.md](AGENTIC_CHECKOUT_PROTOCOL.md) — Agentic checkout
- [docs/EXPERIENCE_COMMERCE_PROTOCOL.md](EXPERIENCE_COMMERCE_PROTOCOL.md) — 体验式交易
- [docs/COMMERCE_RUNTIME_LAYER.md](COMMERCE_RUNTIME_LAYER.md) — Commerce Runtime
- [docs/PCD_SPEC.md](PCD_SPEC.md) — PCD 字段规范
- [docs/ATTRIBUTION.md](ATTRIBUTION.md) — 给 moras-bi ETL 的字段映射
- [docs/PLATFORM_INTEGRATION.md](PLATFORM_INTEGRATION.md) — 各平台接入手册
- [docs/INTENT_MANDATE.md](INTENT_MANDATE.md) — 意图凭证签发
- [docs/A2A_REQUIREMENTS.md](A2A_REQUIREMENTS.md) — A2A 协议要求
- [docs/A2A_UPGRADE_PLAN.md](A2A_UPGRADE_PLAN.md) — A2A 升级路径
- [docs/PRODUCTION_CLOSED_LOOP_UPGRADE.md](PRODUCTION_CLOSED_LOOP_UPGRADE.md) — 闭环路线图
- [docs/RUNBOOK.md](RUNBOOK.md) — 运维 SOP & 故障排查
- [docs/SECURITY_MODEL.md](SECURITY_MODEL.md) — 安全模型 & 密钥层级
- [coding-tasks/INDEX.md](../coding-tasks/INDEX.md) — 任务索引
- [coding-tasks/TEST-REPORT.md](../coding-tasks/TEST-REPORT.md) — 历史测试快照