446 lines
15 KiB
Markdown
446 lines
15 KiB
Markdown
# Work Admin 商城后台项目说明
|
||
|
||
本文是给后续开发者和大模型快速接手项目用的总览文档。进入仓库后应先读本文，再按需查看 `docs/README.md` 的第三方接口文档、`docs/database.md` 的数据库草案和 `docs/payment-integration.md` 的支付接入说明。
|
||
|
||
# 开发规范
|
||
|
||
- 进行最小颗粒的开发，每一个步骤开发完成请给我反馈。
|
||
- 当前项目是中文项目，请尽量在前端项目中使用中文。
|
||
- 所有的需要表格和查询的页面请参考`/list/search-table`的样式实现
|
||
|
||
## 一句话目标
|
||
|
||
建设一个商城系统订单与工单管理后台。系统既要兼容第三方课程/商品接口，也要支持平台自营分类和自营商品的售卖流程，并为后续支付能力预留完整订单与支付状态。
|
||
|
||
## 当前进度
|
||
|
||
已完成：
|
||
|
||
- 工程初始化已完成，当前是 pnpm monorepo。
|
||
- 前端位于 `packages/frontend`，基于 Next.js 16、React 18、Shadcn Admin 模板。
|
||
- 后端位于 `packages/backend`，基于 NestJS 11，默认开发端口 `3001`。
|
||
- 共享包位于 `packages/share`，用于沉淀前后端共用类型、常量和工具函数。
|
||
- `docs/README.md` 已整理第三方接口文档。
|
||
- `docs/database.md` 已记录数据库基础方向。
|
||
- `docs/migrations` 中已有分类、课程、接口日志索引、课程价格和内容字段相关 SQL 草案。
|
||
|
||
尚未完成：
|
||
|
||
- 后端业务模块、TypeORM 实体、数据库连接、鉴权、第三方调用封装仍需实现。
|
||
- 前端仍主要是 Shadcn Admin 模板页面，业务菜单和业务页面仍需替换/新增。
|
||
- 登录、权限、商品管理、下单、订单管理、工单、日志、支付均未形成完整业务闭环。
|
||
- 当前迁移草案更偏第三方课程缓存，后续需要扩展为同时支持第三方商品和自营商品的统一商城模型。
|
||
|
||
## 本地默认登录
|
||
|
||
- 管理员账号：`root`
|
||
- 管理员密码：`123456`
|
||
- 该账号仅用于本地开发。生产环境上线前必须修改密码，并禁止在文档或日志中暴露真实密码。
|
||
|
||
## 技术栈
|
||
|
||
- 包管理器：`pnpm@10.33.0`
|
||
- Monorepo：`pnpm-workspace.yaml`，workspace 范围为 `packages/*`
|
||
- 前端：React、TypeScript、Shadcn Admin 、Tailwind CSS 可按实际使用保留
|
||
- 后端：NestJS 11、TypeScript、MySQL、TypeORM
|
||
- 参数校验：Zod 或 NestJS DTO 校验管道
|
||
- 鉴权：NextAuth.js 或后端自建 Session/JWT，优先选择与 NestJS 后端一致的方案
|
||
- 密码哈希：bcrypt 或 argon2
|
||
- 密钥加密：Node crypto，用于第三方 `key` 等敏感信息
|
||
- 后续异步任务：Redis + BullMQ，可用于订单同步、支付补偿、日志拉取等
|
||
|
||
## 常用命令
|
||
|
||
- `pnpm dev`：同时启动前端和后端开发服务。
|
||
- `pnpm dev:frontend`：只启动前端，默认 `http://localhost:3000`。
|
||
- `pnpm dev:backend`：只启动后端，默认 `http://localhost:3001`。
|
||
- `pnpm lint`：运行前端、后端、共享模块的 ESLint 和 Stylelint。
|
||
- `pnpm test`：运行 workspace 测试。
|
||
- `pnpm build`：构建前端、后端和共享模块。
|
||
|
||
## 核心业务原则
|
||
|
||
### 统一商城模型
|
||
|
||
本项目不是单纯的第三方课程管理后台，而是商城后台。商品来源需要统一建模：
|
||
|
||
- `third_party`：第三方接口同步来的分类和商品。下单后需要由服务端调用第三方接口提交信息。
|
||
- `self_owned`：平台自己新建的分类和商品。下单后只需要写入本地数据库，不调用第三方下单接口。
|
||
|
||
建议分类、商品、订单都保留来源字段，例如：
|
||
|
||
- `source_type`: `third_party` 或 `self_owned`
|
||
- `external_id`: 第三方分类/商品/订单 ID，自营数据为空
|
||
- `provider`: 第三方供应商标识，当前默认可用 `biedawo`
|
||
- `fulfillment_type`: `third_party_api`、`local_only`、`manual`
|
||
|
||
### 商品售卖流程
|
||
|
||
第三方商品：
|
||
|
||
1. 后台同步第三方分类：`act=getcate`。
|
||
2. 后台同步第三方课程/商品：`act=getclass`。
|
||
3. 用户/管理员输入学校、账号、密码、项目 ID 查课：`act=get`。
|
||
4. 选择课程并创建订单。
|
||
5. 如果订单已支付或后台允许先提交，则服务端调用第三方下单：`act=add`。
|
||
6. 保存第三方请求、脱敏后的响应、第三方订单号和本地订单状态。
|
||
|
||
自营商品：
|
||
|
||
1. 后台手动创建分类和商品。
|
||
2. 商品可配置价格、上下架状态、库存/限购、交付类型、售后规则等。
|
||
3. 用户/管理员创建订单时只写入本地订单、订单明细和交付记录。
|
||
4. 不调用第三方 `get`、`add`、`orders` 等接口。
|
||
5. 后续可由后台人工处理、自动发货或扩展为其他自营交付流程。
|
||
|
||
### 支付预留
|
||
|
||
订单创建后应进入 `pending_payment`，支付成功后再进入后续履约流程：
|
||
|
||
- 第三方商品：支付成功后调用第三方下单接口，成功后进入 `submitted` 或 `processing`。
|
||
- 自营商品：支付成功后生成本地交付记录，进入 `paid`、`processing` 或 `completed`，具体取决于交付类型。
|
||
|
||
支付接入详情见 `docs/payment-integration.md`。
|
||
|
||
## 核心业务模块
|
||
|
||
### 1. 用户与权限
|
||
|
||
- 管理员登录。
|
||
- 用户管理、用户注册。
|
||
- 角色权限：超级管理员、普通用户。
|
||
- 操作审计日志。
|
||
- 登录日志。
|
||
|
||
### 2. 商品分类与商品管理
|
||
|
||
第三方分类和商品：
|
||
|
||
- 同步第三方分类：`act=getcate`。
|
||
- 同步第三方课程/商品：`act=getclass`。
|
||
- 本地缓存第三方分类和商品。
|
||
- 支持手动同步和刷新。
|
||
- 第三方商品必须标记 `source_type=third_party`，并保存第三方项目 ID、课程 ID、原始关键信息或结构化字段。
|
||
|
||
自营分类和商品：
|
||
|
||
- 后台新建、编辑、删除/停用自营分类。
|
||
- 后台新建、编辑、上下架自营商品。
|
||
- 支持价格、商品描述、库存、排序、封面、售后说明、交付类型等字段。
|
||
- 自营商品必须标记 `source_type=self_owned`。
|
||
|
||
### 3. 第三方 API 账号与调用日志
|
||
|
||
- 基础地址默认 `https://biedawo.org/api.php`。
|
||
- 当前推荐通过 `.env` 配置 `WK_BASE_URL`、`WK_APP_UID`、`WK_APP_KEY`。
|
||
- `WK_APP_KEY` 原样作为第三方 `key` 使用，前端和日志展示时必须脱敏。
|
||
- 排查第三方请求参数时，可临时设置 `WK_DEBUG_LOG=true`，后端控制台会输出脱敏后的请求 URL、form body、响应状态和响应内容。
|
||
- 支持接口连接测试。
|
||
- 所有第三方调用都必须写入接口调用日志，包括 act、耗时、状态、失败原因、脱敏请求、脱敏响应。
|
||
- 前端不得直接请求第三方 API。
|
||
|
||
### 4. 查课与下单
|
||
|
||
第三方商品查课：
|
||
|
||
- 查课接口：`act=get`。
|
||
- 输入学校、账号、密码、项目 ID。
|
||
- 展示可下单课程。
|
||
- 支持通用 `expand` 参数。
|
||
- 支持恐龙项目 `expand.konglong` 参数。
|
||
|
||
统一下单：
|
||
|
||
- 创建本地订单时先识别商品来源。
|
||
- 第三方商品按第三方流程提交。
|
||
- 自营商品只写入本地数据库。
|
||
- 下单请求与响应必须落库，敏感字段必须脱敏展示。
|
||
- 下单失败时展示第三方返回信息或本地错误信息。
|
||
|
||
### 5. 订单管理
|
||
|
||
第三方订单相关接口：
|
||
|
||
- 获取订单：`act=orders`
|
||
- 查单：`act=chadan`
|
||
- 补单：`act=budan`
|
||
- 改密：`act=gaimi`
|
||
- 暂停：`act=stop`
|
||
- 优先学习：`act=priority`
|
||
- 课程转换：`act=convert`
|
||
- 修改时长：`act=update_time`
|
||
- 修改周期：`act=update_cycle`
|
||
|
||
功能：
|
||
|
||
- 订单列表。
|
||
- 订单详情。
|
||
- 按订单 ID、账号、学校、课程、状态、来源、项目筛选。
|
||
- 第三方订单支持查单刷新、补单、改密、暂停、优先学习、课程转换、修改时长、修改周期。
|
||
- 自营订单支持本地发货、备注、关闭、退款标记、售后处理等本地操作。
|
||
- 所有操作写入 `order_actions` 或统一审计日志。
|
||
|
||
### 6. 日志管理
|
||
|
||
第三方日志接口：
|
||
|
||
- 恐龙 Stream 日志：`/api/streamLogs`
|
||
- 普通日志：`act=cha_logwk`
|
||
- zhs 明细：`act=cha_log`
|
||
- 易教育学习记录：`act=get_yjy_study_log`
|
||
|
||
功能：
|
||
|
||
- 订单日志查询。
|
||
- Stream 日志实时展示。
|
||
- 日志内容格式化展示。
|
||
- 日志查询历史记录。
|
||
- 异常日志标记。
|
||
|
||
### 7. 工单管理
|
||
|
||
第三方工单接口：
|
||
|
||
- 上传工单图片：`act=uploadTicketImage`
|
||
- 提交工单：`act=submitWorkOrder`
|
||
- 查询工单：`act=queryWorkOrder`
|
||
|
||
功能：
|
||
|
||
- 工单图片上传。
|
||
- 附件预览。
|
||
- 提交工单。
|
||
- 查询工单状态。
|
||
- 本地保存工单记录。
|
||
- 工单状态映射展示。
|
||
- 限制同一订单重复创建工单。
|
||
- 自营订单也应支持本地工单，必要时不调用第三方工单接口。
|
||
|
||
工单状态映射：
|
||
|
||
| 状态值 | 状态文本 | 说明 |
|
||
| --- | --- | --- |
|
||
| 1 | 待处理 | 已创建，等待处理 |
|
||
| 2 | 处理中 | 管理员处理中 |
|
||
| 3 | 已回复 | 等待用户确认 |
|
||
| 4 | 已解决 | 工单已解决 |
|
||
| 5 | 已关闭 | 工单关闭 |
|
||
| 6 | 已取消 | 工单取消 |
|
||
|
||
### 8. 支付管理
|
||
|
||
支付模块需要预留并逐步实现：
|
||
|
||
- 支付渠道配置。
|
||
- 创建支付单。
|
||
- 支付回调验签。
|
||
- 支付状态同步。
|
||
- 退款申请和退款回调。
|
||
- 支付日志和回调日志。
|
||
- 支付成功后触发对应订单履约。
|
||
|
||
详细接入文档见 `docs/payment-integration.md`。
|
||
|
||
## 第三方接口摘要
|
||
|
||
通用规则：
|
||
|
||
- 除 `/api/streamLogs` 外，所有接口使用 `POST`。
|
||
- 请求头使用 `Content-Type: application/x-www-form-urlencoded`。
|
||
- 基础 URL 为 `https://biedawo.org/api.php`。
|
||
- 常规响应格式为 JSON。
|
||
- `/api/streamLogs` 为 GET 请求，响应为 Stream 格式。
|
||
|
||
接口清单详见 `docs/README.md`。实现时不要把 `uid`、`key`、学生账号、学生密码暴露给前端。
|
||
|
||
## 下单 expand 参数
|
||
|
||
通用字段：
|
||
|
||
```json
|
||
{
|
||
"score": 95,
|
||
"duration": 35,
|
||
"period": 7,
|
||
"staticIds": [1, 2]
|
||
}
|
||
```
|
||
|
||
恐龙项目字段：
|
||
|
||
```json
|
||
{
|
||
"konglong": {
|
||
"remark": ["urgent", "code_ready"],
|
||
"city": "beijing",
|
||
"tag": "vip",
|
||
"config": {
|
||
"useTime": 60,
|
||
"code": "888888"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 建议数据模型方向
|
||
|
||
后续不要把第三方课程和自营商品拆成两套完全独立的业务主干。建议使用统一主表并通过来源字段分流：
|
||
|
||
- `categories`：分类表，支持 `source_type`、`provider`、`external_id`。
|
||
- `products` ：商品表，支持第三方课程和自营商品。
|
||
- `product_skus`：如后续商品存在规格、套餐、周期，可新增 SKU。
|
||
- `orders`：订单主表，记录用户、金额、支付状态、履约状态、来源摘要。
|
||
- `order_items`：订单明细，记录商品快照。
|
||
- `order_fulfillments`：履约记录，区分第三方 API 提交和本地交付。
|
||
- `payments`：支付单，记录支付渠道、支付金额、支付状态、渠道流水号。
|
||
- `payment_events`：支付回调和主动查询日志。
|
||
- `refunds`：退款单。
|
||
- `api_call_logs`：第三方接口调用日志。
|
||
- `audit_logs`：后台操作审计日志。
|
||
|
||
## 开发阶段计划
|
||
|
||
### 阶段 1：项目初始化
|
||
|
||
状态：基本完成。
|
||
|
||
- 建立 monorepo。
|
||
- 建立前端、后端、共享包。
|
||
- 保留 Shadcn Admin 后台模板。
|
||
- 准备基础 lint、test、build 命令。
|
||
|
||
验收标准：
|
||
|
||
- 可以启动本地开发服务。
|
||
- 可以访问登录页和后台首页。
|
||
- 后端服务可以启动。
|
||
|
||
### 阶段 2：数据库、鉴权与基础后台
|
||
|
||
状态：待开发。
|
||
|
||
- 接入 MySQL 和 TypeORM。
|
||
- 建立用户、角色、登录日志、审计日志基础表。
|
||
- 实现管理员登录。
|
||
- 实现 Session/JWT 鉴权。
|
||
- 未登录不能访问后台页面。
|
||
|
||
建议：
|
||
- 强制改密时自动跳转账号安全页
|
||
- 权限配置更细的资源枚举
|
||
- 日志导出
|
||
|
||
### 阶段 3：第三方 API 封装与接口日志
|
||
|
||
状态：待开发。
|
||
|
||
- 封装第三方通用调用客户端。
|
||
- 从环境变量读取 `WK_BASE_URL`、`WK_APP_UID`、`WK_APP_KEY`。
|
||
- 实现连接测试。
|
||
|
||
### 阶段 4：分类与商品
|
||
|
||
- 同步第三方分类和商品。
|
||
- 新建自营分类和商品。
|
||
- 商品列表同时展示第三方商品和自营商品。
|
||
- 商品来源、状态、价格、描述、排序可管理。
|
||
|
||
验收标准：
|
||
|
||
- 可以同步第三方分类数据。
|
||
- 可以同步第三方商品数据。
|
||
- 可以创建自营分类。
|
||
- 可以创建自营商品。
|
||
|
||
### 阶段 5：查课、购物车/下单与支付预留
|
||
|
||
状态：待开发。
|
||
|
||
- 第三方商品支持查课。
|
||
- 统一创建本地订单。
|
||
- 订单创建后默认待支付。
|
||
- 支付能力先预留表结构、状态和接口边界。
|
||
- 支付成功后按商品来源触发履约。
|
||
|
||
验收标准：
|
||
|
||
- 第三方商品可以查课后创建订单。
|
||
- 自营商品可以直接创建本地订单。
|
||
- 订单能区分 `pending_payment`、`paid`、`submitted` 等状态。
|
||
|
||
### 阶段 6：订单管理与第三方订单操作
|
||
|
||
状态：待开发。
|
||
|
||
- 订单列表和详情页。
|
||
- 第三方订单同步和查单刷新。
|
||
- 第三方订单补单、改密、暂停、优先学习、课程转换、修改时长、修改周期。
|
||
- 自营订单本地发货、关闭、备注、售后处理。
|
||
- 所有操作写入操作记录。
|
||
|
||
### 阶段 7：日志管理
|
||
|
||
状态：待开发。
|
||
|
||
- 普通日志查询。
|
||
- zhs 明细查询。
|
||
- 易教育学习记录查询。
|
||
- `/api/streamLogs` 服务端代理。
|
||
- 日志查看页面。
|
||
|
||
### 阶段 8：工单管理
|
||
|
||
状态：待开发。
|
||
|
||
- 第三方工单图片上传。
|
||
- 第三方工单提交和查询。
|
||
- 自营本地工单。
|
||
- 附件上传与预览。
|
||
- 工单与本地订单关联。
|
||
|
||
### 阶段 9：支付接入
|
||
|
||
状态：预留，待开发。
|
||
|
||
- 按 `docs/payment-integration.md` 实现支付渠道、支付单、回调、退款和补偿。
|
||
- 支付成功后触发第三方下单或自营履约。
|
||
- 支付失败、超时、重复回调、金额不一致都要有明确处理。
|
||
|
||
### 阶段 10：安全、审计与体验优化
|
||
|
||
状态：待开发。
|
||
|
||
- 敏感字段脱敏显示。
|
||
- 操作审计。
|
||
- 接口错误统一处理。
|
||
- 请求超时与重试策略。
|
||
- 表格筛选、分页、批量操作。
|
||
- 数据备份说明。
|
||
- 生产部署说明。
|
||
|
||
## 安全要求
|
||
|
||
- 第三方 `key` 必须加密保存或只通过安全环境变量读取。
|
||
- 学生密码、第三方密钥、支付密钥、请求原文中的敏感字段展示时必须脱敏。
|
||
- 前端不得直接请求第三方 API。
|
||
- 前端不得直接处理支付渠道私钥、商户密钥、第三方 API key。
|
||
- 第三方 API 调用必须经过服务端封装。
|
||
- 支付回调必须验签，并校验金额、订单号、支付状态。
|
||
- 所有订单操作、工单操作、配置修改、支付状态变更必须写入审计或事件日志。
|
||
- 上传文件需要限制类型和大小。
|
||
|
||
## 当前最高优先级
|
||
|
||
最小可行版本优先完成：
|
||
|
||
1. 数据库连接、TypeORM 基础实体和迁移机制。
|
||
2. 登录与权限。
|
||
3. 第三方 API 封装与调用日志。
|
||
4. 统一分类和商品模型，兼容第三方与自营。
|
||
5. 第三方分类/商品同步。
|
||
6. 自营分类/商品管理。
|
||
7. 查课。
|
||
8. 统一创建订单，并预留支付状态。
|
||
9. 第三方商品支付后提交第三方订单，自营商品支付后写入本地履约。
|
||
10. 订单列表与订单详情。
|