3.0 KiB
3.0 KiB
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_ownedexternal_id: 第三方分类/商品/订单 ID，自营数据为空provider: 第三方供应商标识，当前默认可用biedawofulfillment_type:third_party_api、local_only、manual
商品售卖流程
第三方商品：
- 后台同步第三方分类：
act=getcate。 - 后台同步第三方课程/商品：
act=getclass。 - 用户/管理员输入学校、账号、密码、项目 ID 查课：
act=get。 - 选择课程并创建订单。
- 如果订单已支付或后台允许先提交，则服务端调用第三方下单：
act=add。 - 保存第三方请求、脱敏后的响应、第三方订单号和本地订单状态。
自营商品：
- 后台手动创建分类和商品。
- 商品可配置价格、上下架状态、库存/限购、交付类型、售后规则等。
- 用户/管理员创建订单时只写入本地订单、订单明细和交付记录。
- 不调用第三方
get、add、orders等接口。 - 后续可由后台人工处理、自动发货或扩展为其他自营交付流程。