# ECommerceDataSystem **Repository Path**: LiuGuiLin_Admin/ecommerce-data-system ## Basic Information - **Project Name**: ECommerceDataSystem - **Description**: 电商数据中台 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-08 - **Last Updated**: 2026-11-12 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 电商全链路数据管理系统 多平台(抖店 / 淘宝 / 拼多多 / 线下)订单、流量、投流数据的统一导入、对账与真实利润核算后台。 - 后端:Java 17 · Spring Boot 3.2 · Spring Security + JWT · MyBatis-Plus · MySQL 8 · Redis · EasyExcel - 前端:Vue 3 · TypeScript · Vite 5 · Arco Design Vue · ECharts - 部署:Docker Compose(MySQL + Redis + 后端 + Nginx) --- ## 1. 快速启动 ### Windows 一键启动 双击 `run.bat`,或在命令行执行: | 命令 | 行为 | |---|---| | `run.bat` | 自动选择:检测到 Docker 用容器启动,否则用本地开发模式 | | `run.bat docker` | 强制 Docker Compose 启动,访问 http://localhost:8088 | | `run.bat local` | 本地开发启动(MySQL 可用时连 MySQL,否则自动切 H2),访问 http://localhost:5173 | | `run.bat demo` | 强制内嵌 H2 演示模式,零依赖,访问 http://localhost:5173 | | `run.bat stop` | 停止容器(数据卷保留) | | `run.bat check` | 只检查环境、端口占用与构建产物,不启动 | 脚本会自动:检测 Java/Node/Docker → 校验 3306/6379 端口 → 缺失 jar 时用 Maven 打包 → 分别在独立窗口启动后端与前端 → 等待端口就绪后打开浏览器。运行日志保留在“电商后端”“电商前端”两个窗口。 > `run.bat` 以 GBK(ANSI) 编码保存,确保 cmd 中文正常显示;请勿另存为 UTF-8。 ### 零依赖演示模式(无 MySQL / 无 Docker) 内嵌 H2(MySQL 兼容模式)作为数据库,适合本机快速体验: ```bash cd backend java -jar target/ecom-data-backend.jar --spring.profiles.active=demo # 或:run.bat demo ``` - 数据保存在 `backend/data/ecom.mv.db`,删除该文件即重置;上传文件在 `backend/uploads`。 - Redis 缺失时自动降级:JWT 校验仍生效,仅「登出踢出黑名单」失效(重启后旧 token 仍可用)。 - 执行 `run.bat` / `run.bat local` 时若检测到 3306 未监听,也会自动切到该模式。 - 演示模式仅用于体验与联调,生产请使用 MySQL 8 + Redis。 ### Docker Compose 手动启动 ```bash # 在项目根目录 docker compose up -d --build ``` | 服务 | 地址 | |---|---| | 前端 | http://localhost:8088 | | 后端 API | http://localhost:8088/api(经 Nginx 代理) | | MySQL | localhost:3306(库 `ecom_data`,root/root123456,可用环境变量覆盖) | | Redis | localhost:6379 | 首次启动自动建表并初始化数据(`DataInitializer`):权限、3 个角色、3 个账号、4 个店铺、7 个调整类目、4 平台 × 5 类数据的字段映射模板。 | 账号 | 密码 | 角色 | 能力 | |---|---|---|---| | `admin` | `123456` | SUPER_ADMIN | 全部权限(含系统设置、审计日志) | | `manager` | `123456` | ADMIN | 除系统设置、审计日志外的全部权限 | | `operator` | `123456` | OPERATOR | 仅导入 + 查看,任何写接口返回 403 | > 修改端口:`WEB_PORT=9090 docker compose up -d`。生产环境请修改 `MYSQL_ROOT_PASSWORD` 与 `JWT_SECRET`。 ### 本地开发 ```bash # 依赖:JDK 17+、Maven 3.9+、Node 18+、MySQL 8、Redis cd backend && mvn spring-boot:run # 默认 localhost:3306/ecom_data, root/root cd frontend && npm install && npm run dev # http://localhost:5173,/api 代理到 8080 ``` 配置项均可用环境变量覆盖:`MYSQL_HOST/MYSQL_PORT/MYSQL_DB/MYSQL_USER/MYSQL_PASSWORD`、`REDIS_HOST/REDIS_PORT`、`JWT_SECRET`、`UPLOAD_DIR`。 --- ## 2. 目录结构 ``` ECommerceDataSystem/ ├── backend/ Spring Boot 后端 │ ├── src/main/java/com/ecom/data/ │ │ ├── common/ 统一响应 Result、分页、异常、JSON diff │ │ ├── security/ JWT、@RequirePerm 接口鉴权、登录用户 │ │ ├── aspect/ @AuditLog 审计切面(before/after + diff) │ │ ├── domain/entity/ 27 张表的实体 │ │ ├── mapper/ MyBatis-Plus Mapper │ │ ├── importer/ 导入器:抽象基类 + 各平台/各数据类型实现 │ │ ├── service/impl/ upsert、diff、利润计算、异步导入执行 │ │ └── controller/ 18 个 REST 控制器 │ └── src/main/resources/db/schema.sql ├── frontend/ Vue3 前端(Arco Pro 风格布局) ├── samples/ 验收测试用 Excel 样例 ├── scripts/acceptance_test.py 自动化验收脚本 └── docker-compose.yml ``` --- ## 3. 权限模型(RBAC) - 接口级:`@RequirePerm("order:edit")` + 切面校验,无权限直接 403 JSON,运营角色对所有编辑接口一律 403。 - 按钮级:前端 `v-permission="'order:edit'"` 指令删除无权限节点,路由守卫按 `perms` 拦截页面。 - 审计:所有写操作经 `@AuditLog` 记录 `sys_audit_log`(操作人、IP、类型、目标表/ID、before/after JSON、字段级 diff),仅 SUPER_ADMIN 可查。 --- ## 4. 导入与对账 ### 4.1 三种导入模式 | 模式 | 用途 | |---|---| | `FULL` 全量 | 首次接入,导入历史全部订单 | | `DAILY` 每日增量 | 每日导入前一日数据 | | `MONTHLY_BACKFILL` 月度回补 | 每月重新导入上一自然月,捕捉退款/状态变更 | 流程:上传 → `sys_import_task`(PENDING)→ `@Async` 解析(进度写库,页面轮询可查)→ 逐行校验 → upsert → diff 对账。 ### 4.2 幂等与去重 | 数据 | 业务唯一键 | |---|---| | 订单 | `platform + shop_id + order_no + sub_order_no`(库表唯一索引) | | 流量日报 | `platform + shop_id + stat_date` | | 投流消耗 | `platform + shop_id + stat_date + plan_id` | 已存在则更新(先写 `biz_order_snapshot` 旧值快照 + `biz_order_change_log` 明细),不存在则插入。同一文件重复导入订单数不变。 ### 4.3 变更比对 变更类型:`STATUS` 状态变更、`AMOUNT` 金额变更、`NEW_REFUND` 新出现退款。对账中心可按平台/店铺/日期/类型筛选、导出 Excel;确认归档后该期间订单 `locked=1`,再次导入会被拒绝,仅 SUPER_ADMIN 可解锁。 ### 4.4 字段映射模板 每个平台 × 数据类型维护 `列名 → 标准字段` 映射(版本化,`sys_field_mapping`)。上传时按平台+类型取最新启用版本;匹配不上的列名记入任务的 `unmatched_columns`,不静默丢字段。 ### 4.5 异常处理 逐行校验金额/日期/必填/订单号;失败行写 `sys_import_error`(行号、原因、原始数据),不阻断整体导入,可下载错误文件修正后重传。 --- ## 5. 利润核算 ``` 利润 = 真实销售额(排除刷单) − 退款金额 − 货品成本(SKU 成本价 × 销量,按支付时间取生效期价格) − 平台扣点 − 物流成本(按店铺+日期区间取单均运费 × 单量) − 投流花费(消耗日报汇总) − 代理返佣 − 达人抽佣 − 自定义调整项(扣减类目加支出,增加类目冲回) − 刷单成本(刷单订单运费 + 关联刷单佣金,单列展示) − 固定成本分摊(按销售额占比 / 平均 / 手动指定店铺) ``` 口径约束: 1. 销售口径统一「支付时间 + 实付金额」; 2. 广告归因 GMV 仅用于 ROI,不计入销售额; 3. `ROI = 广告归因 GMV ÷ 投流花费`,整体与单计划分别展示; 4. `转化率 = 支付买家数 ÷ 访客数`,按平台分别计算,不做跨平台混合。 下钻维度:平台 / 店铺 / 商品 / SKU / 代理 / 达人 × 日 / 周 / 月。商品、SKU、代理、达人维度只归集可直接归属到订单的成本(销售额、退款、货品成本、扣点、物流、刷单成本、关联调整项、佣金);投流与固定成本属店铺级费用,不在此维度分摊。 --- ## 6. 验收 启动系统后执行: ```bash python scripts/acceptance_test.py --host http://localhost:8088 ``` 脚本按 PRD 验收标准逐条断言: 1. 运营账号可上传/查看,但调用编辑接口返回 403,页面无编辑入口; 2. 同一订单文件连续导入 3 次,订单总数不变; 3. 先导入 `samples/抖店订单_2026-10_全量.xlsx`,再导入 `抖店订单_2026-10_月度回补.xlsx`,对账中心恰好列出 5 条变更(3 条新增退款 + 2 条状态变更); 4. 利润报表成本拆分与手工计算一致(可用 `samples` 数据核对); 5. 审计日志可查到每次导入/修改的操作人与前后值。 样例文件(列名与内置「抖店」映射模板一致): - `samples/抖店订单_2026-10_全量.xlsx`:12 笔订单,其中 2 笔备注含「刷单」 - `samples/抖店订单_2026-10_月度回补.xlsx`:3 笔新增退款 + 2 笔状态变更 - `samples/抖店流量日报_2026-10.xlsx`、`抖店投流消耗日报_2026-10.xlsx`、`抖店投流充值_2026-10.xlsx` --- ## 7. 自动化测试 ```bash cd backend && mvn test ``` 共 13 个测试,全部通过: | 测试 | 覆盖内容 | |---|---| | `OrderUpsertServiceTest` | 订单唯一键 upsert、旧值快照与变更日志 | | `ReconDiffServiceTest` | 月度回补 diff:状态变更 / 金额变更 / 新增退款分类 | | `ProfitCalculatorTest` | 利润公式(含刷单剔除、SKU 生效期取价) | | `ApiSmokeTest` | H2 + Mock Redis 端到端:登录、导入 3 次幂等、回补 5 条变更、运营 403、利润拆分自洽、审计日志、按平台转化率 | `ApiSmokeTest` 使用 H2(MySQL 兼容模式)与 Mock Redis,不需要本机安装 MySQL/Redis;生产运行仍使用 MySQL 8 + Redis。 --- ## 8. 已知边界 - 导入文件格式为 `.xlsx`(EasyExcel);CSV 需另存为 xlsx。 - 平台数据通过导出文件接入,未对接各平台 OpenAPI;新增平台只需实现一个 `AbstractOrderImporter` 子类并配置映射模板。 - 商品/SKU/代理/达人维度不摊分投流与固定成本(店铺级费用),按店铺维度查看完整利润。 - 附件默认存本地 `UPLOAD_DIR`(Compose 挂载为数据卷),生产可替换为对象存储。 - `demo` 模式使用 H2 文件库(`backend/data/ecom.mv.db`),并发与数据量与 MySQL 有差异,勿用于生产。