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