# begin_marketing

**Repository Path**: yangsj/begin_marketing

## Basic Information

- **Project Name**: begin_marketing
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-29
- **Last Updated**: 2026-08-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Begin Marketing

面向线下零售、餐饮等行业的营销工具平台。平台提供抽奖助手等工具，注册用户基于工具创建自己的营销产品，并围绕产品沉淀参与、转化和奖励数据。

## 当前底座

- JDK 21、Spring Boot 3.5、Maven 多模块。
- Druid + MySQL 8 + 原生 MyBatis XML。
- 统一响应、分页、错误码、请求上下文和常用工具。
- 缓存、计数、锁和领域事件端口；V1 使用 MySQL 本地适配，后续可替换 Redis/MQ。
- 普通用户统一使用 `user_account + user_login_identity`；登录身份只负责认证，业务关系统一关联不可变 `user_code`，禁止使用自增 `id`。
- 所有 `*_status` 数据库字段统一使用 `VARCHAR(32)` 和可读枚举值；`delete_status` 使用 `NOT_DELETED/DELETED`。
- 所有数据库时间字段统一使用 `*_time`，Java 属性使用 `*Time`，不使用 `*_at/*At`。
- 已提供 `@RequireUserLevel(n)` 最低用户等级拦截；当前等级大于或等于要求等级即可访问，无注解时不做等级限制。
- Shiro 2.2 无状态 JWT 认证、数据库会话撤销、登录审计、刷新令牌轮换和平台/用户接口隔离。

## 模块

```text
marketing-common          公共模型、上下文、错误和基础端口
marketing-infrastructure  MyBatis XML 与 MySQL 本地适配器
marketing-user            平台账号、用户主账户、登录身份、等级与账号变更审计
marketing-security-shiro  Shiro Realm、JWT、密码/手机号认证和会话管理
marketing-system          平台系统设置、公开活动站点配置
marketing-product         用户营销产品与展示配置
marketing-channel         活动渠道、访问归因与渠道漏斗
marketing-reward          奖品、库存、发奖与核销
marketing-tool-lottery    抽奖助手配置、开奖与抽奖记录
marketing-boot            Spring Boot 启动、Druid、Web 和健康检查
marketing-web             Vue 3 管理后台与消费者 H5
```

业务模块按实际开发阶段增加，不预建空模块。

## 初始化数据库

```bash
mysql -u root -p < database/begin_marketing_mysql8.sql
```

默认数据库为 `begin_marketing`，字符集为 `utf8mb4`，排序规则为 `utf8mb4_0900_ai_ci`。数据库脚本会创建库和表，但不会删除已有库。
已有 P0 数据库升级到渠道漏斗版本时，执行一次
`database/migrations/V20260812_1__add_marketing_channel_funnel.sql`；脚本会补充渠道、访问和行为表，扩展参与归因字段，并为历史活动幂等补齐四个默认渠道。

## 本地配置

复制 `.env.example` 的变量到本机运行环境，并填写数据库密码。仓库配置文件不保存真实密码。

```bash
export BEGIN_DB=root
export BEGIN_DB_PWD='your-local-password'
export BEGIN_MARKETING_VISITOR_HASH_PEPPER='your-independent-random-secret'
```

## 构建与启动

```bash
mvn test
mvn package
java -jar marketing-boot/target/marketing-boot-1.0.0-SNAPSHOT.jar
```

启动前端开发服务器：

```bash
cd marketing-web
npm install
npm run dev
```

需要编译后只启动 Spring Boot 时：

```bash
cd marketing-web
npm run build:backend
```

再启动 `marketing-boot`，页面和 API 都由 `http://127.0.0.1:8080` 提供，无需保留 Vite 进程。

本地验证入口：

- `GET /actuator/health`
- `GET /api/public/framework/info`

账号接口见 `docs/specs/feature-account-system.md`。首次启动可通过
`BEGIN_MARKETING_PLATFORM_BOOTSTRAP_*` 环境变量引导创建唯一超级管理员；生产环境创建成功后应关闭引导开关。

平台超级管理员可在 `/platform/settings` 维护“公开活动站点地址”。该地址保存在
`system_config` 表中，用于活动入口、复制链接和二维码；配置为空时回退到打开活动工作台的浏览器站点。
数据库密码、JWT 密钥和身份加密密钥等敏感配置仍只允许通过部署环境变量注入。

普通 `mvn test` 运行快速单元测试；真实 MySQL 集成测试必须显式执行，避免因为缺少数据库配置而被误认为已经验证：

```bash
mvn -Pmysql-integration test
```

执行前必须提供 `BEGIN_MARKETING_DB_URL`、`BEGIN_DB` 和 `BEGIN_DB_PWD`。集成测试直接验证 MyBatis XML、事务、渠道归因与漏斗、库存并发、账号关联和平台用户分页，并清理或回滚测试数据；缺少或错误的数据库配置会让命令失败，不会静默跳过。

Flyway 依赖和基线配置已经预留，但在初始化脚本拆分成正式版本化迁移前默认关闭，避免无迁移文件时向数据库增加误导性的元数据；后续通过 `BEGIN_MARKETING_FLYWAY_ENABLED=true` 启用。

## 设计与规范

- `docs/system-architecture-design.md`
- `docs/begin-marketing-development-guidelines.md`
- `docs/modules/marketing-user-architecture-design.md`
- `docs/modules/marketing-lottery-architecture-design.md`
- `docs/specs/feature-marketing-channel-funnel.md`
- `docs/diagrams/marketing-lottery-er-diagram.html`
- `docs/specs/feature-system-framework.md`