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