# takewy

**Repository Path**: osheyx/takewy

## Basic Information

- **Project Name**: takewy
- **Description**: 学一手 Takewy —— AI + 用户共创的速成教程知识库 H5（Vue3 + Vite + Vant4 / NestJS + Prisma + PostgreSQL）。每天学一手，碎片时间长本事。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-30
- **Last Updated**: 2026-10-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 学一手 Takewy

> 每天学一手，碎片时间长本事。
> 一个由 **AI + 用户共创**持续打磨的速成教程知识库 H5：人人是学生也是老师，甩个链接 AI 补成标准教程，学完打卡赚积分，数据驱动每篇教程越变越好。

## 这是什么

- **产品形态**：移动 H5 起步（免安装、链接直达；微信小程序/App 是主体资质到位后的事，见调研文档）
- **MVP 边界**：不做变现，只验证「教程完读率 × 素材供给转化 × AI 内容质量」三个飞轮
- **核心机制**：七段式标准化教程、经典/时效版本链可追溯、分步图文 + 速查卡双形态、积分成长体系、教程健康分驱动 AI 迭代

## 可运行原型系统（零基础设施）

一套真实的前后端全栈系统，**本机跑起来不需要数据库、Docker、消息队列或任何 AI 密钥**：

| 层 | 技术 | 零基建替换 |
|---|---|---|
| H5 | Vue 3.5 + Vite 6 + Vant 4.9 + Pinia | 静态构建，直接上 CDN |
| API | NestJS 11 + Prisma 6 | 无状态可水平扩展 |
| 数据库 | SQLite（JSON 存 TEXT） | 改 `DATABASE_URL` 换 PostgreSQL（JSONB） |
| AI | `MockAiProvider` 确定性七段式生成 | `AI_PROVIDER=openai_compatible` 接 DeepSeek/豆包/Qwen/GLM |
| 队列 | 进程内异步（setImmediate 接缝） | 换 BullMQ + Redis |
| 短信 | `DEV_SMS_CODE=123456` 固定验证码 | 阿里云短信认证 API |

### 环境要求

Node ≥ 20、pnpm 10（`npm i -g pnpm`）。

### 启动（三条命令）

```bash
pnpm install                      # 1. 安装（postinstall 自动 prisma generate）
pnpm db:push && pnpm seed         # 2. 建库 + 灌入 104 篇种子教程（40 用户 / 约 2.6w 事件 / 917 复现）
pnpm dev                          # 3. 同时起 API(:3000) 与 H5(:5173)
```

浏览器打开 **http://127.0.0.1:5173/**（手机视图 390×844 最佳）。
H5 通过 Vite 代理访问 API，无需关心跨域。API 地址：http://127.0.0.1:3000/api/v1。

> 沙箱终端里 `localhost` 可能被 VPN/DNS 劫持，用 `127.0.0.1`；本机浏览器不受影响。

### 一键端到端冒烟

API 运行中，另开终端：

```bash
pnpm gate                         # 聚合门禁：全量 build + 依赖边界 + 纯包/api 单测 + h5 lint/type-check/unit
pnpm smoke                        # 24 节 217 项端到端：feed/搜索/七段式/版本链快照/
                                  # 投稿→AI→去重→质检→发布/学完积分/打卡/反馈/收藏/
                                  # 环境画像/小测/复现率/变体/闪卡/行动卡/校对投票/AI 补空词/
                                  # 段落追问/正误对比/音频/海报/学习地图/创作者主页/zod 负例/幂等
```

### 你可以在原型里点到什么

V1.0 全链路 + V1.1/V1.2 能力（规格见 [docs/PRODUCT-V1.1.md](docs/PRODUCT-V1.1.md)）：

- **首页**：领域筛选、经典/时效筛选、下拉刷新、今日速成
- **详情**：七段式（简介/准备/步骤勾选含预期结果/坑点/案例/总结/速查卡）、分步/速查双形态、
  版本链时间线（旧版只读快照）、报错与经验（踩坑/纠正/案例/技巧）、点赞、收藏、分享、
  跟做进度实时同步
- **学得动（V1.1）**：按读者设备画像渲染**环境变体写法**、学后小测、按环境切片的**复现率**展示、
  坑点**正误对比卡**、浏览器本地 Web Speech **通勤听音频**
- **不卡壳（V1.2）**：每个步骤可**段落级 AI 追问**（只依据该步上下文，10 次/分限流，
  应答一律标注「AI 生成，未经验证」；真实模型失败自动回落 mock 并标记 fallback）、
  **闪卡**间隔复习（简化 SM，学完自动制卡）、**行动卡**执行意图与到期清单、**学习地图**
- **共创**：投稿文本/链接 → AI 异步七段式草稿 + 质检 + 去重提示 → 编辑发布 → 立刻可搜
  （重复投稿命中去重，引导补经验而非重复发文）；人工 fork 草稿进**校对投票队列**（一人一票）；
  **分享海报**（本地生成二维码，同次查看复用短链不刷分享计数）；**创作者主页**（采纳经验/徽章/bio，
  零贡献用户隐私门槛 404）
- **我的**：匿名可直接用；短信验证码登录（开发环境固定 123456）、成长等级/徽章/积分流水、
  连续打卡、在学/已学/收藏
- **埋点**：32 个契约事件，前端批量（10 条/5 秒）上报，pagehide 用 sendBeacon 兜底；
  教程事件强制带 tutorialId+versionId

### 接真实大模型

```bash
# apps/api/.env
AI_PROVIDER=openai_compatible
AI_BASE_URL=https://api.deepseek.com   # 或豆包/Qwen/GLM 的 OpenAI 兼容端点
AI_API_KEY=sk-xxx
AI_MODEL=deepseek-chat
```

Provider 契约在 `apps/api/src/modules/ai/ai.types.ts`（七段式草稿输出必须符合 `AiDraftDTO`，
另有段落追问 `ask()`：只依据单步上下文应答）；真实模型不可用时自动回落确定性 mock，
追问响应会标记 `fallback:true` 并在 H5 显示「基础模型应答」提示。
选型、四级去重、成本测算见 [docs/RESEARCH-AI.md](docs/RESEARCH-AI.md)。

### 常用脚本

| 命令 | 作用 |
|---|---|
| `pnpm dev` / `pnpm dev:api` / `pnpm dev:h5` | 全栈 / 仅 API / 仅 H5（watch） |
| `pnpm build` | contracts 双格式构建 → API/H5 生产构建（H5 含 vue-tsc 类型门） |
| `pnpm gate` | 聚合门禁：build + 依赖边界（dependency-cruiser）+ 全部单测 + h5 lint/类型/单测 |
| `pnpm db:push` / `pnpm seed` / `pnpm smoke` | 建表 / 灌 104 篇种子 / 24 节 217 项端到端冒烟 |

### 生产部署（Docker Compose 单机）

镜像与编排已就绪，**拿到机器后无需改代码**：

```bash
cd infra
cp .env.example .env             # 强 DB 密码 + 32+ 位 INTERNAL_KEY；DEV_SMS_CODE 留空
RUN_SEED=true docker compose -f docker-compose.prod.yml up -d --build   # 首启：PG 建表 + 灌种
# api 健康后把 RUN_SEED 置回 false 再正常重启；H5 在 :8080，前置网关终止 HTTPS
```

api 镜像 entrypoint 会自动把 Prisma 切到 PostgreSQL provider 并 `db push`；
H5/admin 为 nginx 静态镜像，`/api` 同源反代。CI 每次推送构建三个镜像防 Dockerfile 腐烂。
上线放行（域名/ICP 备案/HTTPS/短信/OSS/软著）见 [`docs/LAUNCH-CHECKLIST.md`](docs/LAUNCH-CHECKLIST.md)。

## 静态高保真原型

[`prototype/index.html`](prototype/index.html) 是**单文件静态设计稿**（无后端，沟通用），
保留作视觉/交互参照；真实系统以上面的 monorepo 为准。

## 文档索引

| 文档 | 内容 |
|---|---|
| [`docs/MVP-PRD.md`](docs/MVP-PRD.md) | MVP 产品需求文档：定位、内容模型、页面、流程、积分、AI 流水线、埋点、指标 |
| [`docs/PRODUCT-V1.1.md`](docs/PRODUCT-V1.1.md) | V1.1/V1.2 迭代规格（环境变体/闪卡/行动卡/校对投票/正误对比/音频/海报/地图/创作者/段落追问） |
| [`docs/LEARNING-DESIGN.md`](docs/LEARNING-DESIGN.md) | 学习设计三原则与「可重复性契约」八字段（内容第一法律） |
| [`docs/NAMING.md`](docs/NAMING.md) | 全工程命名规范（DTO/DB/埋点/API 的唯一事实源） |
| [`docs/LAUNCH-CHECKLIST.md`](docs/LAUNCH-CHECKLIST.md) | 上线放行清单（域名/ICP/HTTPS/短信/OSS/软著等外部前置） |
| [`docs/RESEARCH-AI.md`](docs/RESEARCH-AI.md) | **AI 选型调研**：模型分层、2026 价格、单篇成本、四级去重、链接解析、OCR、AIGC 合规 |
| [`docs/RESEARCH-H5-GROWTH.md`](docs/RESEARCH-H5-GROWTH.md) | **H5 与增长调研**：形态决策、微信红线、短信登录成本、SEO/Nuxt 迁移、三阶段路线图 |
| [`docs/ARCHITECTURE-30W.md`](docs/ARCHITECTURE-30W.md) | **30 万 DAU 架构方案**：容量测算、三阶段拓扑与账单（0 → 3 千 → 2.5 万元/月）、合规倒排、接缝替换清单 |
| [`docs/ARCHITECTURE-MODULES.md`](docs/ARCHITECTURE-MODULES.md) | 现网模块划分与依赖边界（纯包四引擎、barrel 跨模块、depcruise 门禁） |
| [`docs/TASKS.md`](docs/TASKS.md) | 任务看板 |
| [`docs/progress/`](docs/progress/) | 每日推进日志 |
| [`plan.txt`](plan.txt) | 早期商业规划（后置变现，MVP 不实施） |

## 工程结构

```
apps/h5             Vue3 + Vite + Vant 4（C 端 H5，features/ 按域拆分）
apps/api            NestJS + Prisma（SQLite 原型 / PostgreSQL 生产）
  src/platform      config / logger / http 信封 / database / jobs 接缝 / 调度
  src/pipeline      素材→AI 七段式→质量门→发布编排
  src/modules       tutorial / search / share / material / point / me / event / admin …
apps/admin          零依赖 Vite 内部运营后台（健康分/校对/时效复检/空词榜）
packages/contracts  前后端共享 DTO / 枚举 / 积分等级 / 埋点事件（CJS+ESM 双产物）
packages/content    纯引擎：block 校验 / 机审 5 门 / 小测出题判分 / 变体匹配（零 IO）
packages/points     纯引擎：积分裁决 / 防刷幂等 / 徽章
packages/health     纯引擎：健康分 v2（复现率 30 权重 / 环境切片 / nextAction）
prototype           单文件 HTML 高保真原型（设计参照，非生产代码）
infra               compose / .env 模板 / 生产单机编排
.github/workflows   CI：门禁+单测+E2E smoke+三个生产镜像构建
docs                产品、调研与架构文档
```

技术栈与工程规则见 [`CLAUDE.md`](CLAUDE.md)。包管理：pnpm workspace + Node ≥20；
共享契约是全工程唯一事实源，前后端都从 `@takewy/contracts` 引，禁止两边各定义一份。