study_work/AGENTS.md

Work Admin 商城后台项目说明

本文是给后续开发者和大模型快速接手项目用的总览文档。进入仓库后应先读本文，再按需查看 docs/README.md 的第三方接口文档、docs/database.md 的数据库草案和 docs/payment-integration.md 的支付接入说明。

开发规范

• 进行最小颗粒的开发，每一个步骤开发完成请给我反馈。
• 当前项目是中文项目，请尽量在前端项目中使用中文。
• 所有的需要表格和查询的页面请参考/list/search-table的样式实现

一句话目标

建设一个商城系统订单与工单管理后台。系统既要兼容第三方课程/商品接口，也要支持平台自营分类和自营商品的售卖流程，并为后续支付能力预留完整订单与支付状态。

当前进度

已完成：

• 工程初始化已完成，当前是 pnpm monorepo。
• 前端位于 packages/frontend，基于 Next.js 16、React 18、Shadcn Admin 模板。
• 后端位于 packages/backend，基于 NestJS 11，默认开发端口 3001。
• 共享包位于 packages/share，用于沉淀前后端共用类型、常量和工具函数。
• docs/README.md 已整理第三方接口文档。
• docs/database.md 已记录数据库基础方向。
• docs/migrations 中已有分类、课程、接口日志索引、课程价格和内容字段相关 SQL 草案。

尚未完成：

• 后端业务模块、TypeORM 实体、数据库连接、鉴权、第三方调用封装仍需实现。
• 前端仍主要是 Shadcn 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. 后续可由后台人工处理、自动发货或扩展为其他自营交付流程。

支付预留

订单创建后应进入 pending_payment，支付成功后再进入后续履约流程：

• 第三方商品：支付成功后调用第三方下单接口，成功后进入 submitted 或 processing。
• 自营商品：支付成功后生成本地交付记录，进入 paid、processing 或 completed，具体取决于交付类型。

支付接入详情见 docs/payment-integration.md。

核心业务模块

1. 用户与权限

• 管理员登录。
• 用户管理、用户注册。
• 角色权限：超级管理员、普通用户。
• 操作审计日志。
• 登录日志。

2. 商品分类与商品管理

第三方分类和商品：

• 同步第三方分类：act=getcate。
• 同步第三方课程/商品：act=getclass。
• 本地缓存第三方分类和商品。
• 支持手动同步和刷新。
• 第三方商品必须标记 source_type=third_party，并保存第三方项目 ID、课程 ID、原始关键信息或结构化字段。

自营分类和商品：

• 后台新建、编辑、删除/停用自营分类。
• 后台新建、编辑、上下架自营商品。
• 支持价格、商品描述、库存、排序、封面、售后说明、交付类型等字段。
• 自营商品必须标记 source_type=self_owned。

3. 第三方 API 账号与调用日志

• 基础地址默认 https://biedawo.org/api.php。
• 当前推荐通过 .env 配置 WK_BASE_URL、WK_APP_UID、WK_APP_KEY。
• WK_APP_KEY 原样作为第三方 key 使用，前端和日志展示时必须脱敏。
• 排查第三方请求参数时，可临时设置 WK_DEBUG_LOG=true，后端控制台会输出脱敏后的请求 URL、form body、响应状态和响应内容。
• 支持接口连接测试。
• 所有第三方调用都必须写入接口调用日志，包括 act、耗时、状态、失败原因、脱敏请求、脱敏响应。
• 前端不得直接请求第三方 API。

4. 查课与下单

第三方商品查课：

• 查课接口：act=get。
• 输入学校、账号、密码、项目 ID。
• 展示可下单课程。
• 支持通用 expand 参数。
• 支持恐龙项目 expand.konglong 参数。

统一下单：

• 创建本地订单时先识别商品来源。
• 第三方商品按第三方流程提交。
• 自营商品只写入本地数据库。
• 下单请求与响应必须落库，敏感字段必须脱敏展示。
• 下单失败时展示第三方返回信息或本地错误信息。

5. 订单管理

第三方订单相关接口：

• 获取订单：act=orders
• 查单：act=chadan
• 补单：act=budan
• 改密：act=gaimi
• 暂停：act=stop
• 优先学习：act=priority
• 课程转换：act=convert
• 修改时长：act=update_time
• 修改周期：act=update_cycle

功能：

• 订单列表。
• 订单详情。
• 按订单 ID、账号、学校、课程、状态、来源、项目筛选。
• 第三方订单支持查单刷新、补单、改密、暂停、优先学习、课程转换、修改时长、修改周期。
• 自营订单支持本地发货、备注、关闭、退款标记、售后处理等本地操作。
• 所有操作写入 order_actions 或统一审计日志。

6. 日志管理

第三方日志接口：

• 恐龙 Stream 日志：/api/streamLogs
• 普通日志：act=cha_logwk
• zhs 明细：act=cha_log
• 易教育学习记录：act=get_yjy_study_log

功能：

• 订单日志查询。
• Stream 日志实时展示。
• 日志内容格式化展示。
• 日志查询历史记录。
• 异常日志标记。

7. 工单管理

第三方工单接口：

• 上传工单图片：act=uploadTicketImage
• 提交工单：act=submitWorkOrder
• 查询工单：act=queryWorkOrder

功能：

• 工单图片上传。
• 附件预览。
• 提交工单。
• 查询工单状态。
• 本地保存工单记录。
• 工单状态映射展示。
• 限制同一订单重复创建工单。
• 自营订单也应支持本地工单，必要时不调用第三方工单接口。

工单状态映射：

状态值	状态文本	说明
1	待处理	已创建，等待处理
2	处理中	管理员处理中
3	已回复	等待用户确认
4	已解决	工单已解决
5	已关闭	工单关闭
6	已取消	工单取消

8. 支付管理

支付模块需要预留并逐步实现：

• 支付渠道配置。
• 创建支付单。
• 支付回调验签。
• 支付状态同步。
• 退款申请和退款回调。
• 支付日志和回调日志。
• 支付成功后触发对应订单履约。

详细接入文档见 docs/payment-integration.md。

第三方接口摘要

通用规则：

• 除 /api/streamLogs 外，所有接口使用 POST。
• 请求头使用 Content-Type: application/x-www-form-urlencoded。
• 基础 URL 为 https://biedawo.org/api.php。
• 常规响应格式为 JSON。
• /api/streamLogs 为 GET 请求，响应为 Stream 格式。

接口清单详见 docs/README.md。实现时不要把 uid、key、学生账号、学生密码暴露给前端。

下单 expand 参数

通用字段：

{
  "score": 95,
  "duration": 35,
  "period": 7,
  "staticIds": [1, 2]
}

恐龙项目字段：

{
  "konglong": {
    "remark": ["urgent", "code_ready"],
    "city": "beijing",
    "tag": "vip",
    "config": {
      "useTime": 60,
      "code": "888888"
    }
  }
}

建议数据模型方向

后续不要把第三方课程和自营商品拆成两套完全独立的业务主干。建议使用统一主表并通过来源字段分流：

• categories：分类表，支持 source_type、provider、external_id。
• products ：商品表，支持第三方课程和自营商品。
• product_skus：如后续商品存在规格、套餐、周期，可新增 SKU。
• orders：订单主表，记录用户、金额、支付状态、履约状态、来源摘要。
• order_items：订单明细，记录商品快照。
• order_fulfillments：履约记录，区分第三方 API 提交和本地交付。
• payments：支付单，记录支付渠道、支付金额、支付状态、渠道流水号。
• payment_events：支付回调和主动查询日志。
• refunds：退款单。
• api_call_logs：第三方接口调用日志。
• audit_logs：后台操作审计日志。

开发阶段计划

阶段 1：项目初始化

状态：基本完成。

• 建立 monorepo。
• 建立前端、后端、共享包。
• 保留 Shadcn Admin 后台模板。
• 准备基础 lint、test、build 命令。

验收标准：

• 可以启动本地开发服务。
• 可以访问登录页和后台首页。
• 后端服务可以启动。

阶段 2：数据库、鉴权与基础后台

状态：待开发。

• 接入 MySQL 和 TypeORM。
• 建立用户、角色、登录日志、审计日志基础表。
• 实现管理员登录。
• 实现 Session/JWT 鉴权。
• 未登录不能访问后台页面。

建议：

• 强制改密时自动跳转账号安全页
• 权限配置更细的资源枚举
• 日志导出

阶段 3：第三方 API 封装与接口日志

状态：待开发。

• 封装第三方通用调用客户端。
• 从环境变量读取 WK_BASE_URL、WK_APP_UID、WK_APP_KEY。
• 实现连接测试。

阶段 4：分类与商品

• 同步第三方分类和商品。
• 新建自营分类和商品。
• 商品列表同时展示第三方商品和自营商品。
• 商品来源、状态、价格、描述、排序可管理。

验收标准：

• 可以同步第三方分类数据。
• 可以同步第三方商品数据。
• 可以创建自营分类。
• 可以创建自营商品。

阶段 5：查课、购物车/下单与支付预留

状态：待开发。

• 第三方商品支持查课。
• 统一创建本地订单。
• 订单创建后默认待支付。
• 支付能力先预留表结构、状态和接口边界。
• 支付成功后按商品来源触发履约。

验收标准：

• 第三方商品可以查课后创建订单。
• 自营商品可以直接创建本地订单。
• 订单能区分 pending_payment、paid、submitted 等状态。

阶段 6：订单管理与第三方订单操作

状态：待开发。

• 订单列表和详情页。
• 第三方订单同步和查单刷新。
• 第三方订单补单、改密、暂停、优先学习、课程转换、修改时长、修改周期。
• 自营订单本地发货、关闭、备注、售后处理。
• 所有操作写入操作记录。

阶段 7：日志管理

状态：待开发。

• 普通日志查询。
• zhs 明细查询。
• 易教育学习记录查询。
• /api/streamLogs 服务端代理。
• 日志查看页面。

阶段 8：工单管理

状态：待开发。

• 第三方工单图片上传。
• 第三方工单提交和查询。
• 自营本地工单。
• 附件上传与预览。
• 工单与本地订单关联。

阶段 9：支付接入

状态：预留，待开发。

• 按 docs/payment-integration.md 实现支付渠道、支付单、回调、退款和补偿。
• 支付成功后触发第三方下单或自营履约。
• 支付失败、超时、重复回调、金额不一致都要有明确处理。

阶段 10：安全、审计与体验优化

状态：待开发。

• 敏感字段脱敏显示。
• 操作审计。
• 接口错误统一处理。
• 请求超时与重试策略。
• 表格筛选、分页、批量操作。
• 数据备份说明。
• 生产部署说明。

安全要求

• 第三方 key 必须加密保存或只通过安全环境变量读取。
• 学生密码、第三方密钥、支付密钥、请求原文中的敏感字段展示时必须脱敏。
• 前端不得直接请求第三方 API。
• 前端不得直接处理支付渠道私钥、商户密钥、第三方 API key。
• 第三方 API 调用必须经过服务端封装。
• 支付回调必须验签，并校验金额、订单号、支付状态。
• 所有订单操作、工单操作、配置修改、支付状态变更必须写入审计或事件日志。
• 上传文件需要限制类型和大小。

当前最高优先级

最小可行版本优先完成：

1. 数据库连接、TypeORM 基础实体和迁移机制。
2. 登录与权限。
3. 第三方 API 封装与调用日志。
4. 统一分类和商品模型，兼容第三方与自营。
5. 第三方分类/商品同步。
6. 自营分类/商品管理。
7. 查课。
8. 统一创建订单，并预留支付状态。
9. 第三方商品支付后提交第三方订单，自营商品支付后写入本地履约。
10. 订单列表与订单详情。