# Work 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. 后续可由后台人工处理、自动发货或扩展为其他自营交付流程。