yuzhiran-dev
0f215d2aad
- 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
233 lines
11 KiB
Markdown
Executable File
233 lines
11 KiB
Markdown
Executable File
# 项目进度追踪
|
||
|
||
## 当前阶段：P4 — 支付闭环 + 部署
|
||
|
||
### Phase 1-4 — 全部完成 ✅
|
||
|
||
### P0 — 全局优化（全部完成 ✅）
|
||
| 子项 | 说明 | 状态 |
|
||
|------|------|------|
|
||
| **P0a** | i18n 基础设施 + 翻译文件 + LanguageProvider + useT hook | ✅ |
|
||
| **P0b** | UI 统一 — Design Token + 共享组件库 | ✅ |
|
||
| **P0c** | 逐页翻译 + 语言切换 — 沙盒页面 useT 化 | ✅ |
|
||
| **P0d** | 会员定价页重构（用量可视化） | ✅ |
|
||
| **P0e** | 模型选择器升级（卡片式 + 能力标签） | ✅ |
|
||
| **P0f** | 会话分享链接 — HMAC 签名 + 分享查看页 | ✅ |
|
||
|
||
### P1 — 学习技能包（全部完成 ✅）
|
||
| 子项 | 说明 | 状态 |
|
||
|------|------|------|
|
||
| **后端** | SkillsModule + 8 技能定义 + 过滤/详情 API | ✅ |
|
||
| **前端** | /skills 市场 + /skills/[id] 详情 + header 入口 | ✅ |
|
||
| **沙盒集成** | 替代硬编码 SCENES，从 API 动态加载，?skill=xxx 支持 | ✅ |
|
||
|
||
### P2 — CSS 统一（全部完成 ✅）
|
||
| 子项 | 说明 | 状态 |
|
||
|------|------|------|
|
||
| **Mobile variables.css** | Design Token 变量定义（Web/Mobile 统一） | ✅ |
|
||
| **Mobile 全站 18 页** | 批量替换 hardcoded color → CSS vars | ✅ |
|
||
| **PC 响应式** | header/compare/sandbox/member/workshop 移动端修复 | ✅ |
|
||
|
||
### P3 — 体验增强（全部完成 ✅）
|
||
| 优先级 | 项目 | 说明 | 状态 |
|
||
|--------|------|------|------|
|
||
| **P4a** | 多模态 — 图片上传 + 沙盒 Vision | ✅ 完成 |
|
||
| **P4b** | 代码语法高亮 | highlight.js + CodeBlock 组件 | ✅ |
|
||
| **P3c** | 会话重命名 | PATCH endpoint + 双击编辑 | ✅ |
|
||
| — | SDK / 共享 UI 包 | 远期规划 | 📋 |
|
||
|
||
### P4 — 支付闭环 + 统一网关（已完成 ✅）
|
||
| 子项 | 说明 | 状态 |
|
||
|------|------|------|
|
||
| **P4a** | 统一支付网关集成 — `GatewayPayService` HMAC-SHA256 对接 yzrcloud.cn 网关，支持支付宝/微信 | ✅ |
|
||
| **P4b** | 会员页双支付按钮 — 支付宝/微信可选，统一走网关 | ✅ |
|
||
| **P4c** | 网关 Webhook 接收 — `POST /api/v1/payment/gateway/webhook`，处理 `recharge.completed` / `order.refunded` | ✅ |
|
||
| **P4d** | 管理后台订单增强 — 搜索/分页/渠道筛选/退款弹窗/标记已付 | ✅ |
|
||
| **P4e** | Mock 降级 — 网关不可达时自动 mock 完成支付，不影响开发 | ✅ |
|
||
| — | 订阅到期提醒 / 自动续费 | 📋 远期 |
|
||
|
||
### 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 动态注入工具列表 | ✅ |
|
||
|
||
---
|
||
|
||
## 部署架构
|
||
|
||
### 域名概况
|
||
|
||
| 域名 | 类型 | 说明 | 状态 |
|
||
|------|------|------|------|
|
||
| **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 (`yuzhiran-api`) | 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 yuzhiran-api
|
||
```
|
||
|
||
### 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
|
||
|
||
---
|
||
|
||
## 支付对接
|
||
|
||
### 架构总览
|
||
|
||
```
|
||
前端 (会员页) → POST /orders/create → GatewayPayService → HMAC-SHA256 → yzrcloud.cn 网关
|
||
├── 支付宝 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 编译无错误
|
||
- ✅ 前端 83 静态页面全部生成成功（含 8 个 /practices/[id] 页面）
|
||
|
||
---
|
||
|
||
## 2026-06-10 Session (续) — ¥9.9 用量包 + 企业版 MVP
|
||
|
||
### ¥9.9 用量包系统
|
||
- **User 模型**: 新增 `sandboxExtra Int @default(0)` 字段（购买的额外配额）
|
||
- **配额逻辑改造** (`SandboxService`): 优先消耗每日免费 → 不足时扣除 `sandboxExtra`；`getQuota()` 返回 `dailyRemaining` + `extra` + `totalRemaining`
|
||
- **Orders 支持 `PACKAGE`**: `completeMockPayment()` 检测 `PACKAGE` 时按金额增加 extra 配额（¥9.9→50次, ¥49→300次）
|
||
- **前端沙盒**: 配额显示双层（今日已用 + 剩余额外），超限跳转购买页
|
||
- **新增 `/practices/packages`**: 三档用量包购买页（¥4.9/10次, ¥9.9/50次, ¥49/300次），复用现有支付流程
|
||
|
||
### 企业版 MVP
|
||
- **后端**: 11 enterprise API 端点 + Organization/OrganizationMember 模型 + 完整 CRUD（已有）
|
||
- **新增 `/enterprise`**: 营销着陆页 — Shadow AI 数据隔离故事、六大功能、定价、FAQ
|
||
- **新增 `/enterprise/dashboard`**: 团队管理后台 — 创建组织/邀请成员/使用报告
|
||
- **Header 导航**: 新增「企业版」入口
|
||
- **i18n**: 完整 `enterprise.*` 翻译 keys
|
||
|
||
### Files Created
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `frontend/src/app/practices/packages/page.tsx` | 用量包购买页 |
|
||
| `frontend/src/app/enterprise/page.tsx` | 企业版营销着陆页 |
|
||
| `frontend/src/app/enterprise/dashboard/page.tsx` | 团队管理后台 |
|
||
|
||
### Verification
|
||
- ✅ 后端 92 项测试全部通过
|
||
- ✅ Prisma migrate 成功
|
||
- ✅ 前端 86 个静态页面全部生成成功
|
||
- ✅ Header 导航已更新（练习 + 企业版）
|
||
- ✅ i18n 中英文完整翻译
|
||
|
||
### Verification
|
||
- ✅ 后端 92 项测试全部通过
|
||
- ✅ 后端 TypeScript 编译无错误
|
||
- ✅ 前端 75 静态页面全部生成成功
|