更新开发文档

README.md

@@ -1,34 +1,65 @@
-This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app).
+# Work Admin 商城后台项目说明
 
-## Getting Started
+建设一个商城系统订单与工单管理后台。系统既要兼容第三方课程/商品接口，也要支持平台自营分类和自营商品的售卖流程，并为后续支付能力预留完整订单与支付状态。
 
-First, run the development server:
+## 本地默认登录
 
-```bash
-npm run dev
-# or
-yarn dev
-```
+- 管理员账号：`root`
+- 管理员密码：`123456`
+- 该账号仅用于本地开发。生产环境上线前必须修改密码，并禁止在文档或日志中暴露真实密码。
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+## 技术栈
 
-You can start editing the page by modifying `pages/index.tsx`. The page auto-updates as you edit the file.
+- 包管理器：`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，可用于订单同步、支付补偿、日志拉取等
 
-[API routes](https://nextjs.org/docs/api-routes/introduction) can be accessed on [http://localhost:3000/api/hello](http://localhost:3000/api/hello). This endpoint can be edited in `pages/api/hello.ts`.
+## 常用命令
 
-The `pages/api` directory is mapped to `/api/*`. Files in this directory are treated as [API routes](https://nextjs.org/docs/api-routes/introduction) instead of React pages.
+- `pnpm dev`：同时启动前端和后端开发服务。
+- `pnpm dev:frontend`：只启动前端，默认 `http://localhost:3000`。
+- `pnpm dev:backend`：只启动后端，默认 `http://localhost:3001`。
+- `pnpm lint`：运行前端、后端、共享模块的 ESLint 和 Stylelint。
+- `pnpm test`：运行 workspace 测试。
+- `pnpm build`：构建前端、后端和共享模块。
 
-## Learn More
+## 核心业务原则
 
-To learn more about Next.js, take a look at the following resources:
+### 统一商城模型
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+本项目不是单纯的第三方课程管理后台，而是商城后台。商品来源需要统一建模：
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome!
+- `third_party`：第三方接口同步来的分类和商品。下单后需要由服务端调用第三方接口提交信息。
+- `self_owned`：平台自己新建的分类和商品。下单后只需要写入本地数据库，不调用第三方下单接口。
 
-## Deploy on Vercel
+建议分类、商品、订单都保留来源字段，例如：
 
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+- `source_type`: `third_party` 或 `self_owned`
+- `external_id`: 第三方分类/商品/订单 ID，自营数据为空
+- `provider`: 第三方供应商标识，当前默认可用 `biedawo`
+- `fulfillment_type`: `third_party_api`、`local_only`、`manual`
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.
+### 商品售卖流程
+
+第三方商品：
+
+1. 后台同步第三方分类：`act=getcate`。
+2. 后台同步第三方课程/商品：`act=getclass`。
+3. 用户/管理员输入学校、账号、密码、项目 ID 查课：`act=get`。
+4. 选择课程并创建订单。
+5. 如果订单已支付或后台允许先提交，则服务端调用第三方下单：`act=add`。
+6. 保存第三方请求、脱敏后的响应、第三方订单号和本地订单状态。
+
+自营商品：
+
+1. 后台手动创建分类和商品。
+2. 商品可配置价格、上下架状态、库存/限购、交付类型、售后规则等。
+3. 用户/管理员创建订单时只写入本地订单、订单明细和交付记录。
+4. 不调用第三方 `get`、`add`、`orders` 等接口。
+5. 后续可由后台人工处理、自动发货或扩展为其他自营交付流程。