# 项目进度追踪

## 当前阶段：P8 — 平台轻量化改造

### P6 — 技能广场 & 付费技能（2026-06-14）✅

| 子项 | 说明 | 状态 |
|------|------|------|
| **市场调研** | 选定方向：付费 AI Skill（每个 Skill 解决一个垂直痛点） | ✅ |
| **Prisma Schema** | Skill 模型加 `price` 字段；新增 `UserSkill` 关联表；Order 加 `metadata` | ✅ |
| **后端** | Orders 支持 `planType: 'SKILL'`；Skills 端增加 access control + marketplace API | ✅ |
| **第一个 Skill** | 标题大师 (TitleCraft) — AI 爆款标题生成器，¥9.9 | ✅ |
| **第二批 5 个 Skill** | 回款助手(¥19.9)、提案智造(¥19.9)、差评分析师(¥19.9)、商品文案大师(¥29.9)、合同审查助手(¥29.9) | ✅ |
| **前端** | `/marketplace` 技能广场页：过滤（全部/免费/付费/已拥有）、购买按钮、支付弹窗 | ✅ |
| **导航** | Header 新增「技能广场」入口 | ✅ |
| **i18n** | 中英文 marketplace.* 完整翻译 key + business 分类 | ✅ |

### P7 — 管理后台 CRUD + 平台审计（2026-06-17）

| 子项 | 说明 | 状态 |
|------|------|------|
| **Admin CRUD - Practices** | 后端完整 CRUD 端点 + 前端 list/new/edit 页面 | ✅ |
| **Admin CRUD - Posts** | 后端 list/detail/status/delete + 前端 list/detail 页面 | ✅ |
| **Admin CRUD - Models** | 后端完整 CRUD + 前端 list/new/edit 页面 | ✅ |
| **Admin CRUD - Skills** | 后端 list/detail/edit 端点 | ✅ |
| **Admin CRUD - Circles** | 后端 list/delete 端点 | ✅ |
| **Admin 首页** | 新增 practices、posts、models 管理入口 | ✅ |
| **前端数据完整性审计** | 确认所有展示页面均从 API 获取数据，无 mock/静态数据残留 | ✅ |
| **¥{price} 变量修复** | marketplace 页 ¥{price} 缺少 .replace() 问题修复 | ✅ |
| **i18n 模板变量审计** | 审计 19 个模板变量，确认无其它遗漏 | ✅ |
| **Circles JSX 语法修复** | 缺失 `</div>` 导致的编译错误 | ✅ |
| **构建部署** | 108/108 页面，主站 + 镜像站已更新，Nginx reload | ✅ |
| **战略分析** | 平台瘦身可能性 + 广告/返佣模式调研（详见分析报告） | ✅ |

### 已做关键决策
- Skill = 最小可交付产品单元。不是"又一个 AI 平台"，而是**每做一个 Skill 就单独卖**
- 第一个 Skill 选"标题大师"——最窄、最痛、最快见效，不依赖人脉
- 定价 ¥9.9（低门槛试探市场），后续 Skill 可根据价值定价 ¥19.9-¥49
- 购买后永久拥有，不走订阅制（降低决策门槛）
- **（P7）** 战略方向思考：是否从"重平台"转向"轻量级信息展示 +练习 +联盟返佣"

### 部署备忘
```bash
# 前端部署后需要：
cd backend && node prisma/update-skill.cjs  # 如果 system prompt 需要更新
```

### P8 — 平台轻量化改造（2026-06-17）

| 子项 | 说明 | 状态 |
|------|------|------|
| **Prisma Schema** | Tool 模型加 `affiliateLink` 字段 | ✅ |
| **免费用户配额** | 沙盒配额 10→5 次/日 | ✅ |
| **后端 API** | Tools 返回 affiliateLink；新增 `/admin/tools` CRUD 5 端点 | ✅ |
| **导航调整** | 主菜单隐藏企业版、社区（页面保留 URL 访问） | ✅ |
| **首页重定位** | Hero 文案改为"AI 工具指南 · 实战练习"；Feature 卡片重写 | ✅ |
| **精选工具区块** | 首页新增"精选 AI 工具"展示区（Stats 与 Features 之间） | ✅ |
| **工具页返佣 Badge** | 有 affiliateLink 的工具显示绿色"推荐"标记 | ✅ |
| **AGENTS.md 更新** | 定位改为"AI 工具指南与技能练习平台"；路线图重排序 | ✅ |
| **构建部署** | 前端 108/108 页面 + 后端 build + PM2 restart + Nginx reload | ✅ |

### P8.1 — SSG 动态路由修复 + 编程导师场景（2026-06-18）

| 子项 | 说明 | 状态 |
|------|------|------|
| **SSG 404 根因诊断** | `NEXT_PUBLIC_API_URL=/api/v1` 在 Node.js 构建时不解析，所有动态路由只生成了 fallback ID `1` | ✅ |
| **config.ts 修复** | SSG 构建时自动使用 `http://localhost:4000/api/v1` 直连后端 | ✅ |
| **页面数验证** | 108→127 页面，courses/[id] 正确生成 ID 17/18/19，skills/[id] 正确生成 general-chat/coding/writing | ✅ |
| **编程导师场景** | 沙盒新增 `sceneId=tutor`，苏格拉底式教学法 prompt，4 个 starter 问题 | ✅ |
| **i18n 同步** | 中英文新增 `sceneTutor: '编程导师'/'Programming Tutor'` | ✅ |
| **项目文档更新** | README.md 全面重写（技术栈、产品定位、功能表）；AGENTS.md 定位同步 | ✅ |
| **生产部署** | 127 页面全部部署并验证 courses 详情页 200 OK | ✅ |

### P8.2 — 返佣工具库扩充 + 管理后台完善（2026-06-23）

| 子项 | 说明 | 状态 |
|------|------|------|
| **Admin 新建工具页** | 添加 `affiliateLink`（返佣链接）输入字段 + 提示文案 | ✅ |
| **Admin 编辑工具页** | 重写为可编辑表单（原为只读展示且不保存）；添加 affiliateLink + PUT 保存 | ✅ |
| **seed-enrich 破坏性修复** | `deleteMany()` → `upsert` by name，避免重新运行 seed-enrich 时清除国内工具 | ✅ |
| **新增国内 AI 工具** | 豆包、通义千问、文心一言、WPS AI、Canva、腾讯元宝、讯飞星火、剪映专业版（8个） | ✅ |
| **返佣链接配置** | 通义千问(阿里云云大使)、文心一言(百度智能云)、Canva(Canvassador)、腾讯元宝(腾讯云)、讯飞星火 共 5 个工具配置真实风格推广链接 | ✅ |
| **工具总数** | 原有 6 个 + 新增 8 个 = **14 个工具**，其中 8 个有返佣链接 | ✅ |

### P8.3 — 沙盒模型合规优化 + 返佣注册文档（2026-06-23）

| 子项 | 说明 | 状态 |
|------|------|------|
| **AI Gateway 清理** | 移除 GPT-3.5/GPT-4/Claude/Llama 等境外模型引用，MODEL_CATALOG 仅保留国内已备案模型 | ✅ |
| **modelMap 净化** | chat() 和 chatStream() 中的 modelMap 仅路由到国内 provider（移除 general/openai/gpt/longcat） | ✅ |
| **provider 命名清晰化** | "OpenAI 兼容接口" → "硅基流动 / DeepSeek"，明确标注实际调用的国内服务商 | ✅ |
| **沙盒可用模型 API** | 新增 `GET /sandbox/models` 端点，返回实际可用的模型列表（按 provider 注册状态动态过滤） | ✅ |
| **前端模型列表** | ModelSelector 改为从 `/sandbox/models` 获取，不再从 `/public/models`（百科模型列表）获取 | ✅ |
| **models.ts 清理** | 移除 foreign 模型，仅保留 deepseek-v4-flash 和 sensenova-6.7-flash-lite，DEFAULT_MODEL 改为 domestic | ✅ |
| **返佣注册指南** | 新建 `docs/affiliate-registration.md`，收录 7 个平台的注册入口、佣金比例、申请流程 | ✅ |

### P8.4 — @Res() 非流式响应 Bug 修复 + 双模型验证 + 生产部署（2026-06-24）

| 子项 | 说明 | 状态 |
|------|------|------|
| **Bug 诊断** | `sandbox.controller.ts` 注入 `@Res() res: Response` 后 NestJS 进入 Express native 模式，非流式 `return` 值被静默丢弃，curl 收到 0 bytes | ✅ |
| **Bug 修复** | 非流式分支改为 `const result = await ...; res.json(result)`，流式分支不变 | ✅ |
| **provider 覆盖修复** | 商汤科技此前同时注册 `deepseek-v4-flash` + `sensenova`，覆盖了硅基流动的 deepseek 注册。修复后商汤仅注册 `sensenova-6.7-flash-lite` | ✅ |
| **双模型功能验证** | `deepseek-v4-flash`(硅基流动) HTTP 201 ~3-18s 正常回复；`sensenova-6.7-flash-lite`(商汤科技) HTTP 201 ~2s 正常回复 | ✅ |
| **生产部署** | 前端 108 页面构建推送主站+镜像站，后端 build + PM2 restart，Nginx reload | ✅ |
| **线上验证** | 编译产物仅含 `deepseek-v4-flash` 和 `sensenova-6.7-flash-lite`，无任何国外模型引用 | ✅ |

### 待办/下一步
1. **注册联盟账号**：按 affiliate-registration.md 优先级注册阿里云云大使、百度智能云推广大使、Canvassador、腾讯云推广大使
2. **替换占位链接**：拿到真实联盟 ID 后替换 seed-tools-affiliate.ts 中的 `yuzhiran` 占位
3. **内容策略**：批量生产 AI 工具评测文章做 SEO
4. **编程导师内容扩充**：按难度分级写更多 starter 问题

---

## 部署架构

### 域名概况

| 域名 | 类型 | 说明 | 状态 |
|------|------|------|------|
| **www.yuzhiran.com** | AI 学习平台 | 前端静态导出 + NestJS 后端 | 🟢 线上 |
| **trade.yuzhiran.com** | 另一项目（非 AI 平台） | SPA 应用，独立后端 8002 端口 | 🟢 线上 |
| **alvnc.yuzhiran.com** | 其他服务 | — | 🟢 线上 |

### www.yuzhiran.com 部署详情

```
用户 → Nginx (443/80) → /api/* → backend (127.0.0.1:4000)
                     → /* → static files (/www/wwwroot/www.yuzhiran.com/)
```

| 组件 | 技术栈 | 运行方式 | 端口 |
|------|--------|---------|------|
| **前端** | Next.js 14 App Router → `output: 'export'` 静态 HTML | Nginx 直接提供 `/www/wwwroot/www.yuzhiran.com/` | 443/80 |
| **后端** | NestJS + Prisma + MySQL | PM2 (`backend`) | 4000 |
| **数据库** | MySQL 8.0 | systemd (`ai_leaning`) | 3306 |
| **Web 服务器** | Nginx (宝塔面板) | systemd | 443/80 |
| **支付网关** | yzrcloud.cn 统一网关 | 外部服务 | 8100(内网) |

**Nginx 配置** (`/www/server/panel/vhost/nginx/www.yuzhiran.com.conf`):
- 静态资源 `/` → `try_files $uri $uri.html $uri/index.html =404`
- API 代理 `/api/` → `proxy_pass http://127.0.0.1:4000`
- 静态资源缓存: `_next/static/` 365 天, 图片 30 天, JS/CSS 12 小时

**部署流程**:
```bash
# 前端
cd frontend && npm run build     # 生成 out/
cp -r out/* /www/wwwroot/www.yuzhiran.com/

# 后端
cd backend && npm run build       # 生成 dist/
pm2 restart backend
```

---

## 支付对接

### 架构总览

```
前端 (会员页) → POST /orders/create → GatewayPayService → HMAC-SHA256 → yzrcloud.cn 网关
                                                                      ├── 支付宝 PC 网站
                                                                      └── 微信 Native 扫码
网关回调 → POST /api/v1/payment/gateway/webhook → 更新订单 + 激活订阅/关联技能
```

### 技能购买流程
```
用户点击"解锁" → POST /orders/create (planType=SKILL, skillId=xxx)
                                       → mock支付自动完成
                                       → UserSkill 记录创建
                                       → 技能广场页显示"已拥有"
                                       → 用户可直接在沙盒使用
```
