# digital-me-backend — Claude Instructions

## Service
数字我 / Digital Me — 主场是 **大师数字传承馆 + 线上版权变现**：平台签约各领域名家(大师)，
免费为其建【知识库】与【作品墙】，并享有其线上数字化变现版权 —— 知识付费问答、作品周边
(手办/签名作品克隆版)、作品库授权给机构、数字人带货、付费咨询/会员。**知识最重要**；形象/
声音次要(照片+预置音即可，无需视频)。个人分身是次级工具(个人在「我的分身」自建，可定向分享)，
不再是平台主打的社交产品。

分身已具备「帮你办事」能力(联网查、记事、待办提醒、工作流定时跑，见 capabilities.js 的
assist 分类) —— 早期文档"NOT 帮你做事的隐形助理""NOT knowledge-work tool"的表述已作废。

国内版**数据不出域**是红线：LLM 用 DashScope/Qwen；Claude/HeyGen/Resend/Stripe/Azure 等
海外出站由 config 开关门控(overseasFallback / overseasEgress)，默认建站期临时开、进生产前关。

## Lineage
The multimodal pipeline is lifted from the proven `super-individual-app`
platform (whose artist vertical is "The Digital Atelier"). Digital Me 现在就是围绕
大师传承馆(master gallery)+ 作品/授权变现构建 —— 早期"no master-gallery/license code"
的说明已不适用(masters/works/agreements/tours 等业务域均已落地)。

## Stack
- Node 20 + Express (ES modules — `"type": "module"`)
- MongoDB (own DB `digital_me` — never share another product's DB)
- LLM: Qwen via DashScope (OpenAI-compatible) primary; Claude Haiku fallback
- Embeddings: DashScope `text-embedding-v3` for knowledge RAG
- Avatar 捏脸: 通义万相 wanx-style-repaint (`services/media.js`)
- Voice clone + TTS: DashScope CosyVoice v2 (`services/media.js` + `ttsWs.js`)
- 口播视频: 通义 EMO audio-driven talking head (`services/talkingVideo.js`)

## Conventions
- Routes thin; logic in `services/`.
- All secrets via `.env` (see `.env.example`); never hardcode.
- Per-owner isolation: every `/api/twins/:id` route ownership-checks via
  `loadTwin` (ownerId match). The public `/api/embed/:slug` router is the
  ONLY no-auth surface — it reads published twins only and never persists.
- Everything degrades gracefully without AI keys (chat → 502 only if no LLM
  at all; avatar → flat photo; voice → `voice-not-cloned`). Keep it usable.
- Rate limit: 120 req/min global.

## Two runtime constraints
1. AI features need `DASHSCOPE_API_KEY` (`.env`).
2. 捏脸 / 口播视频 need `PUBLIC_URL` to be **publicly reachable** — DashScope
   pulls the photo/audio by URL, so a `localhost` PUBLIC_URL makes those two
   features fail (chat + voice still work). Use a tunnel in dev.