# DoTouch.AI — 项目全景梳理

> 版本：v1.5.0（含稳定汇率策略） ｜ 整理日期：2026-08-09 ｜ 用途：团队伙伴快速了解项目全貌

---

## 一、项目定位

**一句话**：面向越南及海外市场的国产大模型 API 中转站——以 OpenAI 兼容格式转售阿里云百炼上的国产模型能力（DeepSeek V4、GLM 5.2、Qwen 等 236 款），主打"国内算力价格优势 → 海外平价服务"，本地化语言 + 本币支付（MoMo/ZaloPay）。

**商业模式**：上游（阿里云百炼）按人民币结算 → 平台以 USD 为定价基准、**本币收款（稳定汇率）** → 向越南/海外开发者出售 API 调用。

**关键决策记录**：
- 部署区域：香港节点
- 计费模式：仅预充值（钱包），无后付费
- 客服：Chatwoot 自托管
- 定价策略：**稳定汇率**（本币收款 → 汇率低频人工维护，不接实时 API，避免定价波动）

---

## 二、技术架构

```
dotouch-ai/  (pnpm monorepo)
├── apps/
│   ├── web/    Next.js 14 (App Router) + TypeScript + Tailwind + next-intl
│   │           ├── 官网落地页（8 路由，SSG 静态化，TTFB ~13ms）
│   │           ├── 用户控制台（真实会话：总览/API Keys/用量/钱包/邀请奖励）
│   │           └── 管理后台（运营/用户/模型/限额/邀请策略/系统设置）
│   └── api/    NestJS v11 + Prisma + ioredis
│               └── OpenAI 兼容网关（SSE 流式 / 非流式）+ 13 个业务模块
├── packages/
│   └── shared/ 共享类型与常量（4 语言、模型目录等）
└── docker-compose.yml / docker-compose.demo.yml
    PostgreSQL 16 + Redis 7 + API/Web 双镜像（standalone）
```

**代码规模**：API ~4.8k 行 TS ｜ Web ~6.2k 行 TS/TSX ｜ 数据库 12 张表

**质量基线**：typecheck 0 错误、生产构建通过、SSG 47 静态页、演示环境可完整走通全流程。

---

## 三、后端模块（apps/api/src）

| 模块 | 职责 |
|---|---|
| `auth` | 注册/登录/密码重置（邮箱验证码 8 位/15 分钟）、JWT、**Google/Facebook OAuth 社交登录**（v1.4.0）、登录限流（5 次/15 分钟） |
| `keys` | API Key 全生命周期：创建（`dt_` 前缀仅返回一次）/轮换/撤销/过期/Key 级限额配置，事件审计 |
| `gateway` | **OpenAI 兼容网关**：`POST /v1/chat/completions`，SSE 流式 + 非流式，错误体 OpenAI 规范，Redis 限流 |
| `models` | 模型目录（236 全量真实扫描）+ 定价元数据（OpenAI 格式） |
| `wallet` | 钱包余额/流水/充值（预充值模式）、精确扣减与流式预扣-结算-退款 |
| `payments` | 支付渠道抽象（provider 接口）+ webhook 回调，渠道接入中 |
| `usage` | 用量明细/日聚合（统计成本与请求数） |
| `quota` | **用量限额**：三维度（tokens/请求/成本）× 每日/总量，账号级+Key 级双重校验，429 quota_exceeded，站内+邮件预警 |
| `referral` | **邀请奖励**（v1.5.0）：邀请码/绑定/记录/奖励发放/策略配置（SystemConfig 可配），首充挂接 |
| `config` | **系统配置**：`GET /v1/config/fx` 稳定汇率（VND 25,400 / CNY 7.2，SystemConfig 驱动） |
| `email` | 邮件服务（验证码/预警），演示环境日志直出 |
| `admin` | 管理后台 API：统计/用户/模型/限额/推荐策略，role=admin 守卫 |
| `health` | 健康检查（含版本号） |

## 四、数据库（Prisma，12 表）

```
User ──┬── ApiKey ──┬── ApiKeyEvent（Key 操作审计）
       │            └── QuotaEvent（限额预警/封禁事件）
       ├── ModelCatalog（236 模型目录）
       ├── BalanceTransaction（余额流水）
       ├── UsageRecord（用量明细）
       ├── Order（充值订单）→ 支付渠道
       ├── ReferralRecord（邀请关系）→ ReferralReward（奖励发放）
       └── SystemConfig（策略 KV：推荐奖励/汇率等）
```

## 五、前端（apps/web，8 路由 × 4 语言）

| 路由 | 内容 |
|---|---|
| `/` 首页 | Hero/特性/模型卡（**本币价格 FxPrice** 7 币种）/定价预览/邀请奖励区块/FAQ/CTA |
| `/models` 模型列表 | 4 主推模型表格，下钻详情 |
| `/models/[id]` 模型详情 | 规格表 + 真实定价 + 代码示例 + 相关模型（JSON-LD Product） |
| `/pricing` 定价页 | 价格表 + 计费规则/政策/FAQ + 汇率提示条 |
| `/pricing/catalog` 模型大全 | 236 模型分类 tabs 全量定价 |
| `/docs` 操作文档 | 快速开始/API 参考/错误码/计费 |
| `/console` 用户控制台 | 总览/API Keys/用量(限额进度条)/钱包/邀请奖励（自包含布局） |
| `/admin` 管理后台 | 登录门(role=admin) + 数据看板/用户/模型/限额/邀请策略/系统设置 |

**国际化**：9 语言（vi 默认 / en / zh-CN / zh-TW / id-ID 印尼 / ms-MY 马来 / th-TH 泰 / zh-HK 香港 / ar-SA 沙特·RTL），全站 398 条文案翻译 + hreflang + 多语言 SEO。
**本币定价**：USD 基准 + 稳定汇率换算 7 币种（₫ / ¥ / Rp / RM / ฿ / HK$ / SAR），`FxPrice` 组件统一渲染。

## 六、SEO 与性能（v1.3.0，P1 已完成）

- 全页多语言 metadata（title/description/canonical/OG/Twitter）
- sitemap.xml（36 条）+ robots.txt + IndexNow 推送
- JSON-LD：Organization / WebSite / Product / BreadcrumbList
- 全站 SSG：47/47 静态页，TTFB ~13ms（基线：docs/seo/performance-baseline-v1.3.0.md）
- 待办：P2 内容 SEO（博客）、P3 站内搜索/GA4（数据出境合规评估中）

## 七、迭代历史（核心节奏）

| 版本 | 里程碑 |
|---|---|
| v1.0.0 | 项目启动：香港部署/预充值/Logo 定稿（B1 网络枢纽） |
| v1.1.x | 官网静态审阅稿 → 多页面站 + 多语言 + 认证弹窗体系 |
| v1.2.0 | **全功能本地演示版**：官网 8 路由 + 真实认证闭环 + 控制台/管理后台 + Docker 演示环境 |
| v1.3.0 | P1 技术 SEO + SSG 性能优化 |
| v1.4.0 | Google/Facebook 社交登录（OAuth + mock 演示） |
| v1.5.0 | 邀请奖励系统（转介绍双方 10% + 注册奖励 + 首充奖励，SystemConfig 可配） |
| v1.6.0 | **国际化扩展**：5 新语言（印尼/马来/泰/香港/沙特 RTL）+ 7 币种稳定汇率 + 管理后台汇率卡扩展 |
| 待定版 | 稳定汇率策略：本币定价 + `/v1/config/fx` + 全站"低价"表述（移除 7 折对外宣传） |

## 八、合规与风险（重点 ⚠️）

- **最高优先级**：美系平台（OpenRouter §7.4 / Together §4.3d）均明令禁止 API 转售——DoTouch 属转售模式，**需向阿里云百炼确认分销授权**（书面许可），见 `docs/compliance/alibaba-bailian-terms-20260808.md`
- 数据分析工具选型需评估数据出境合规（GA4 vs PDPD），P3 决策
- 对外宣传已去除"7 折/70% of China Price"表述（改用"低价/性价比"），降低价格锚定风险

## 九、演示环境与账号

```bash
docker compose -f docker-compose.demo.yml up -d   # 独立隔离环境
# 演示站：http://localhost:3000  ｜  API：http://localhost:8081/v1
```

| 账号 | 用途 | 密码 |
|---|---|---|
| `demo.user@dotouch.ai` | 官网/用户控制台 | `User2026!` |
| `admin@dotouch.ai` | 管理后台 | `Admin2026!` |
| `test-e2e@dotouch.ai` | 接口联调（admin） | `Test1234` |
| `social.demo@dotouch.ai` | 社交登录演示（mock） | — |

## 十、团队协作指南

**环境准备**：`pnpm install` → `docker compose up -d`（本地 PG/Redis）→ `pnpm db:generate` → `pnpm dev`

**目录约定**：
- 新功能 → `apps/api/src/<module>/`（controller/service/module + dto/）+ Prisma schema + seed
- 新页面 → `apps/web/src/app/[locale]/<route>/` + `components/` 组件 + `messages/<lang>.json` 文案（4 语言同步）
- 文档 → `docs/`（requirements/设计/测试/合规/SEO 分类归档）

**规范**：
- 版本：`docs/VERSIONING.md`（时间戳 + 递增版本号），变更写 `docs/CHANGELOG.md`
- 测试：手工验收体系——`docs/testing/feature-acceptance-matrix.md`（F-01~F-14，90+ 用例）逐项验收，结果记录 `test-run-log.md`（当前无自动化 spec，验收靠独立测试 Agent 执行）
- 定价文案：不得出现"7 折/70% of China"类表述；价格统一走 `FxPrice`（稳定汇率）
- 提交：feat/fix/docs 前缀 + 变更要点 + 版本标注

**已知待办**：① pricing/catalog/模型详情页接入 FxPrice 本币主价（首页已完成）；② 管理后台汇率输入持久化到 SystemConfig；③ 支付渠道正式接入（MoMo/ZaloPay 真实沙箱）；④ 自动化测试补强；⑤ 阿里云百炼分销授权确认；⑥ SEO P2/P3。