DoTouch.AI — 项目全景梳理

版本：v1.6.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/ 共享类型与常量（9 语言、模型目录等）
└── 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 路由 × 9 语言）

路由	内容
`/` 首页	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（81 条）+ robots.txt + IndexNow 推送
JSON-LD：Organization / WebSite / Product / BreadcrumbList
全站 SSG：9 语言全量静态化，sitemap 81 条 URL，TTFB 中位 14–18ms（基线：docs/seo/performance-baseline-v1.6.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"表述（改用"低价/性价比"），降低价格锚定风险

九、演示环境与账号

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 文案（9 语言同步）
文档 → 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。

PROJECT-OVERVIEW.md 8.5 KB Historie Surový