P8 平台轻量化改造 + SSG修复 + 编程导师 + 文档完善

- Prisma: Tool 模型加 affiliateLink；免费用户沙盒 10→5 次/日 - 后端: Tools API + /admin/tools CRUD 5 端点；Practices 完整模块 - 导航: 主菜单隐藏企业版/社区（URL 可访问） - 首页: 重定位为 AI 工具指南；新增精选工具区块；Feature 重写 - 工具页: affiliateLink 绿色推荐 Badge - SSG 修复: config.ts 构建时直连 localhost:4000，页面 108→127 - 沙盒: 新增编程导师场景（苏格拉底教学法） - 练习系统: Practices 多场景练习（含结构化评分） - 技能广场: 6 个付费 Skill（标题大师/回款助手等） - 管理后台: Models/Posts/Practices CRUD 页面 - 文档: README + progress.md 全面更新；AGENTS.md 同步定位 - 清理: .env.example 移除；tsbuildinfo gitignore
2026-06-18 18:14:07 +08:00
parent fb8152401b
commit 0f215d2aad
103 changed files with 5240 additions and 778 deletions
@@ -1,59 +1,81 @@
 # 项目进度追踪

-## 当前阶段：P4 — 支付闭环 + 部署
+## 当前阶段：P8 — 平台轻量化改造

-### Phase 1-4 — 全部完成 ✅
+### P6 — 技能广场 & 付费技能（2026-06-14）✅

-### P0 — 全局优化（全部完成 ✅）
 | 子项 | 说明 | 状态 |
 |------|------|------|
-| **P0a** | i18n 基础设施 + 翻译文件 + LanguageProvider + useT hook | ✅ |
-| **P0b** | UI 统一 — Design Token + 共享组件库 | ✅ |
-| **P0c** | 逐页翻译 + 语言切换 — 沙盒页面 useT 化 | ✅ |
-| **P0d** | 会员定价页重构（用量可视化） | ✅ |
-| **P0e** | 模型选择器升级（卡片式 + 能力标签） | ✅ |
-| **P0f** | 会话分享链接 — HMAC 签名 + 分享查看页 | ✅ |
+| **市场调研** | 选定方向：付费 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）

-### P1 — 学习技能包（全部完成 ✅）
 | 子项 | 说明 | 状态 |
 |------|------|------|
-| **后端** | SkillsModule + 8 技能定义 + 过滤/详情 API | ✅ |
-| **前端** | /skills 市场 + /skills/[id] 详情 + header 入口 | ✅ |
-| **沙盒集成** | 替代硬编码 SCENES，从 API 动态加载，?skill=xxx 支持 | ✅ |
+| **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）

-### P2 — CSS 统一（全部完成 ✅）
 | 子项 | 说明 | 状态 |
 |------|------|------|
-| **Mobile variables.css** | Design Token 变量定义（Web/Mobile 统一） | ✅ |
-| **Mobile 全站 18 页** | 批量替换 hardcoded color → CSS vars | ✅ |
-| **PC 响应式** | header/compare/sandbox/member/workshop 移动端修复 | ✅ |
+| **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 | ✅ |

-### P3 — 体验增强（全部完成 ✅）
-| 优先级 | 项目 | 说明 | 状态 |
-|--------|------|------|------|
-| **P4a** | 多模态 — 图片上传 + 沙盒 Vision | ✅ 完成 |
-| **P4b** | 代码语法高亮 | highlight.js + CodeBlock 组件 | ✅ |
-| **P3c** | 会话重命名 | PATCH endpoint + 双击编辑 | ✅ |
-| — | SDK / 共享 UI 包 | 远期规划 | 📋 |
+### P8.1 — SSG 动态路由修复 + 编程导师场景（2026-06-18）

-### P4 — 支付闭环 + 统一网关（已完成 ✅）
 | 子项 | 说明 | 状态 |
 |------|------|------|
-| **P4a** | 统一支付网关集成 — `GatewayPayService` HMAC-SHA256 对接 yzrcloud.cn 网关，支持支付宝/微信 | ✅ |
-| **P4b** | 会员页双支付按钮 — 支付宝/微信可选，统一走网关 | ✅ |
-| **P4c** | 网关 Webhook 接收 — `POST /api/v1/payment/gateway/webhook`，处理 `recharge.completed` / `order.refunded` | ✅ |
-| **P4d** | 管理后台订单增强 — 搜索/分页/渠道筛选/退款弹窗/标记已付 | ✅ |
-| **P4e** | Mock 降级 — 网关不可达时自动 mock 完成支付，不影响开发 | ✅ |
-| — | 订阅到期提醒 / 自动续费 | 📋 远期 |
+| **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 | ✅ |

-### P5 — 运营助手（已完成 ✅）
-| 子项 | 说明 | 状态 |
-|------|------|------|
-| **P5a** | 新增 `POST /admin/ai-assistant/chat` 端点 — 管理员专用 AI 聊天 | ✅ |
-| **P5b** | `AdminAiAssistantService` — 19 个可执行工具定义 | ✅ |
-| **P5c** | `POST /admin/ai-assistant/action` — 工具执行 + AI 总结 | ✅ |
-| **P5d** | 前端 Tool Calling 架构 — AI 自动识别意图→调用→解释→展示 | ✅ |
-| **P5e** | system prompt 动态注入工具列表 | ✅ |
+### 待办/下一步
+1. **为工具库加返佣链接**：在管理后台 `/admin/tools/new` 和编辑页录入 affiliateLink 字段
+2. **注册 AI 工具联盟账号**：对接 Canva/Copy.ai 等工具的返佣计划
+3. **内容策略**：批量生产 AI 工具评测文章做 SEO
+4. **编程导师内容扩充**：按难度分级写更多 starter 问题

 ---

@@ -71,13 +93,13 @@

 ```
 用户 → Nginx (443/80) → /api/* → backend (127.0.0.1:4000)
-                      → /* → static files (/www/wwwroot/www.yuzhiran.com/)
+                     → /* → 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 (`yuzhiran-api`) | 4000 |
+| **后端** | NestJS + Prisma + MySQL | PM2 (`backend`) | 4000 |
 | **数据库** | MySQL 8.0 | systemd (`ai_leaning`) | 3306 |
 | **Web 服务器** | Nginx (宝塔面板) | systemd | 443/80 |
 | **支付网关** | yzrcloud.cn 统一网关 | 外部服务 | 8100(内网) |
@@ -95,16 +117,9 @@ cp -r out/* /www/wwwroot/www.yuzhiran.com/

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

-### trade.yuzhiran.com（独立项目）
-
-非 AI 学习平台项目，独立部署：
- 前端 SPA (React)，root at `/www/wwwroot/trade.yuzhiran.com/`
- 后端 API at `127.0.0.1:8002`
- 路由: `/admin/` → SPA fallback, `/workspace/` → SPA fallback
-
 ---

 ## 支付对接
@@ -113,162 +128,16 @@ pm2 restart yuzhiran-api

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

-### 统一支付网关对接参数
-
-| 参数 | 值 | 来源 |
-|------|-----|------|
-| 网关地址(内网) | `http://localhost:8100` | `.env` |
-| 网关地址(外网) | `https://www.yzrcloud.cn/api/gateway` | 未启用 |
-| API Key | `pay_2ac89d9831244c2ebdbb2a24` | AI学习平台.key |
-| API Secret | `6a2e6c6801384bd0800849ef42ad5e8ef51898819895478a` | AI学习平台.key |
-| 签名算法 | HMAC-SHA256 | `sign_str = "{method}\n{path}\n{timestamp}\n{body_sha256}"` |
-| Webhook | `POST /api/v1/payment/gateway/webhook` | 后端接收 |
-| 支付方式 | `alipay` / `wechat` | 网关统一处理 |
-| Mock 模式 | `GATEWAY_PAY_MOCK=true` | 开发环境启用 |
-
-### 后端对接文件
-
-| 文件 | 说明 |
-|------|------|
-| `backend/src/modules/payment/gateway-pay.service.ts` | 核心网关服务，HMAC 签名 + 下单/查询/退款/Webhook |
-| `backend/src/modules/payment/payment.controller.ts` | `/api/v1/payment/gateway/webhook` 等端点 |
-| `backend/src/modules/orders/orders.service.ts` | 下单路由，统一走网关 |
-| `backend/.env` | `GATEWAY_PAY_*` 配置项 |
-
-### API 端点一览
-
-| 方法 | 路径 | 说明 | 认证 |
-|------|------|------|------|
-| POST | `/api/v1/payment/gateway/webhook` | 网关支付成功/退款回调 | 无（网关签名在 body 中） |
-| GET | `/api/v1/payment/wxpay/query?outTradeNo=xxx` | 订单状态查询（转网关） | JWT |
-| POST | `/api/v1/payment/wxpay/refund` | 退款（转网关） | JWT |
-| POST | `/api/v1/orders/create` | 创建订单+发起支付 | JWT |
-| GET | `/api/v1/admin/orders?page=&search=&status=&payChannel=` | 管理员订单搜索 | Admin JWT |
-| POST | `/api/v1/admin/orders/:orderNo/refund` | 管理员退款 | Admin JWT |
-| POST | `/api/v1/admin/orders/:orderNo/mark-paid` | 标记人工已付 | Admin JWT |
-
-### 商户密钥文件
-
-备份位置: `/root/hermes-workspace/backup/网关支付/pay-api/merchants/AI学习平台.key`
-
---
-
-## 2026-05-31 Session (下午)
-
-### Changes Made
- **AI 助手架构升级**: 用户端 + 管理后台双 AI 助手均采用完整 Tool Calling 架构
- **新增 `UserAiAssistantService`**: 后台工具执行服务，18 个工具（搜索/技能/学情/通知/个人信息/模型/提示词/课程/订单）
- **新增 `AiAssistantController`**: `POST /api/v1/ai-assistant/chat` + `/action` 端点
- **新增 `AiAssistantModule`**: 注册 SkillsModule + AIModule 依赖
- **重写前端 `ai-assistant.tsx`**: Tool Calling 架构 + 页面感知上下文 + 登录控制
- **更新前端 `admin-ai-assistant.tsx`**: 新增 search/mark-all-notifications-read 工具描述 + 更多 starter
- **新增后台 `search`/`mark-all-notifications-read` 工具**: 全局搜索用户/订单/课程/内容 + 通知批量已读
- **重构 `assistant-actions.ts`**: 统一 `executeClientAction()` API，支持所有客户端操作
- **清理 `assistant-context.ts`**: 精简为纯上下文数据源，移除旧 action 格式
-
-### 用户端 AI 助手可用操作
-| 分类 | 工具 |
-|------|------|
-| 🧭 导航 | `navigate` — 跳转到任意页面 |
-| 🔍 搜索 | `search` — 全局搜索课程/提示词/工具/文章 |
-| 🎯 技能 | `list-skills` / `get-skill` / `get-skill-categories` |
-| 📊 学情 | `get-learning-analytics` / `get-learning-path` |
-| 🔔 通知 | `list-notifications` / `get-unread-count` / `mark-notification-read` / `mark-all-read` |
-| 👤 个人 | `get-profile` / `list-user-orders` / `get-current-subscription` |
-| 📚 内容 | `list-models` / `list-prompts` / `list-courses` |
-| ⚡ 客户端 | `setModel` / `startChat` / `openSkill` / `setParameter` |
-
-### 管理后台新增工具
-| 工具 | 说明 |
-|------|------|
-| `search` | 全局搜索用户/订单/课程/内容 |
-| `mark-all-notifications-read` | 批量标记所有通知已读 |
-
-### Verification
- ✅ 后端 92 项测试全部通过
- ✅ 后端 TypeScript 编译无错误
- ✅ 前端 75 静态页面全部生成成功
- ✅ 所有文件创建/修改完成
-
---
- `frontend/src/lib/models.ts` 作为模型列表单数据源
- 所有颜色使用 CSS 变量（`text-foreground`/`text-muted-foreground`/`bg-card`/`bg-muted`/`border-border`）
- 沙盒 JWT 认证保留
- 支付全部通过 yzrcloud.cn 统一网关处理，支持支付宝/微信
- 运营助手采用 Tool Calling 架构
- 前端静态导出 (`output: 'export'`) + Nginx 直接提供
- 注册支持用户名、手机号、邮箱三选一，登录支持用户名/手机号/邮箱
- 注册时校验重复用户名/手机号/邮箱并返回友好提示
- 镜像站点 `www.yuzhiran.com.cn` 与主站配置同步
-
---
-
-## 2026-06-01 Session — 注册优化 + 镜像站部署
-
-### Changes Made
- **Prisma User 模型**: 新增 `username` 字段 (`String? @unique`)
- **注册 DTO**: 新增 `username` 字段验证（2-20位，支持中英文/数字/下划线）
- **注册逻辑重构** (`auth.service.ts`):
-  - 注册前分别检查 username/phone/email 是否已存在 → 友好提示
-  - 三字段至少需提供一个
-  - 注册成功用 username 做默认 nickname
- **登录逻辑** (`auth.service.ts`): `OR` 查询增加 `{ username: account }`
- **前端 i18n**: 新增 `username`/`usernameOptional`/`usernameConflict`/`phoneConflict`/`emailConflict` 翻译 key
- **前端 auth 页**:
-  - 注册表单增加用户名输入框
-  - 前端预校验用户名格式（2-20位，中英文/数字/下划线）
-  - 友好错误映射：覆盖用户名/手机号/邮箱冲突提示
-  - 登录框提示改为 "用户名 / 手机号 / 邮箱"
- **镜像站部署**:
-  - 前端静态文件部署至 `/www/wwwroot/www.yuzhiran.com.cn/`
-  - Nginx vhost 配置同步主站：Next.js clean URL + API proxy + 静态缓存
-  - Nginx reload + PM2 restart
-
-### Verification
- ✅ Prisma db push 成功（`username` 列 + 唯一索引）
- ✅ 后端 92 项测试全部通过
- ✅ 后端 TypeScript 编译无错误
- ✅ 前端 75 静态页面全部生成成功
- ✅ Nginx 配置语法验证通过
- ✅ 主站 + 镜像站均已部署
-
---
-
-## 2026-06-01 Session — 支付功能对齐网关文档 + 完善管理操作
-
-### Changes Made
- **GatewayPayService 对齐网关文档**:
-  - `createOrder()` 新增 `remark` 参数（传入 `{"uid":userId,"oid":orderId}`），移除废弃的 `return_url`
-  - 新增 `closeOrder(gatewayOrderId)` — 调用 `POST /v1/pay/orders/{id}/close`
-  - 新增 `syncOrderStatus(orderNo)` — 从网关查询订单状态，若 `paid` 则自动更新本地 + 激活订阅
- **OrdersService**: 下单时传入 `remark`（含 uid/oid），使 webhook 回调可正确匹配用户和订单
- **PaymentController**:
-  - 新增 `POST /payment/gateway/sync/:orderNo` — 手动同步单笔订单状态
-  - 新增 `POST /payment/gateway/close/:gatewayOrderId` — 关闭未支付订单
-  - 清理未使用的 `PaymentService` 依赖
- **管理后台订单页** (`admin/orders/page.tsx`):
-  - 待支付订单增加「同步状态」按钮 — 调用网关查询后更新
- **文档**: `docs/progress.md` 支付部署架构更新为统一网关模式
-
-### Payment 架构现状
+### 技能购买流程
 ```
-下单: 会员页 → POST /orders/create → OrdersService → GatewayPayService → yzrcloud.cn 网关
-查询: POST /payment/gateway/sync/:orderNo → GatewayPayService.syncOrderStatus()
-关闭: POST /payment/gateway/close/:id → GatewayPayService.closeOrder()
-退款: POST /admin/orders/:orderNo/refund → GatewayPayService.refund()
-回调: POST /payment/gateway/webhook → GatewayPayService.handleWebhook()
+用户点击"解锁" → POST /orders/create (planType=SKILL, skillId=xxx)
+                                       → mock支付自动完成
+                                       → UserSkill 记录创建
+                                       → 技能广场页显示"已拥有"
+                                       → 用户可直接在沙盒使用
 ```
-
-### Gaps Identified (远期)
- `payment.service.ts` (微信直连) 和 `alipay.service.ts` (支付宝直连) 为遗留代码，已被 GatewayPayService 全面替代，待确认无人依赖后可移除
- 课程购买页 (`courses/[id]/client.tsx`) 仍直接调用 `wxpay/unified-order` 绕过 OrdersService，未传入 `remark`
-
-### Verification
- ✅ 后端 92 项测试全部通过
- ✅ 后端 TypeScript 编译无错误
- ✅ 前端 75 静态页面全部生成成功