Files

T

yuzhiran-dev fb8152401b 支付功能对齐网关文档 + 完善管理操作

- GatewayPayService: 新增 remark 字段(传uid/oid), 移除废弃 return_url, 新增 closeOrder/syncOrderStatus
- PaymentController: 新增 POST /payment/gateway/sync/:orderNo 和 /close/:id 端点
- Admin 订单页: 待支付订单增加「同步状态」按钮
- OrdersService: 下单时传入 remark 使 webhook 可匹配
- 清理 PaymentService 未使用依赖
- docs/progress.md 更新支付架构

2026-06-05 13:19:44 +08:00

13 KiB

Executable File

Raw Blame History

项目进度追踪

当前阶段：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 小时

部署流程:

# 前端
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 编译无错误
✅ 前端 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()

Gaps Identified (远期)

payment.service.ts (微信直连) 和 alipay.service.ts (支付宝直连) 为遗留代码，已被 GatewayPayService 全面替代，待确认无人依赖后可移除
课程购买页 (courses/[id]/client.tsx) 仍直接调用 wxpay/unified-order 绕过 OrdersService，未传入 remark

Verification

✅ 后端 92 项测试全部通过
✅ 后端 TypeScript 编译无错误
✅ 前端 75 静态页面全部生成成功

13 KiB Executable File Raw Blame History Unescape Escape

项目进度追踪

当前阶段：P4 — 支付闭环 + 部署

Phase 1-4 — 全部完成 ✅

P0 — 全局优化（全部完成 ✅）

P1 — 学习技能包（全部完成 ✅）

P2 — CSS 统一（全部完成 ✅）

P3 — 体验增强（全部完成 ✅）

P4 — 支付闭环 + 统一网关（已完成 ✅）

P5 — 运营助手（已完成 ✅）

部署架构

域名概况

www.yuzhiran.com 部署详情

trade.yuzhiran.com（独立项目）

支付对接

架构总览

统一支付网关对接参数

后端对接文件

API 端点一览

商户密钥文件

2026-05-31 Session (下午)

Changes Made

用户端 AI 助手可用操作

管理后台新增工具

Verification

2026-06-01 Session — 注册优化 + 镜像站部署

Changes Made

Verification

2026-06-01 Session — 支付功能对齐网关文档 + 完善管理操作

Changes Made

Payment 架构现状

Gaps Identified (远期)

Verification

13 KiB

Executable File

Raw Blame History