# 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. 订单列表与订单详情。