技术架构文档 · 横影·映航

1总体架构

系统采用前后端分离的单体应用架构：Vue 3 前端（Vite 构建）通过 Nginx 反代访问 Spring Boot 3 单体后端，后端按业务域分包（module），经 MyBatis-Plus 访问 MySQL，Redis 承担缓存与配额计数；AI 能力以「规则引擎 + 统计模型」为 MVP 骨架，统一接入 DeepSeek V4 Flash 大模型基座（OpenAI 兼容协议）。

接入层 Vue3 + Element Plus 前端Nginx 反代 / 静态托管浏览器 / 经营大屏

▼ JWT（Authorization: Bearer）

网关/鉴权 Spring Security + JwtAuthenticationFilterOpenAPI 数据网关 /api/open/v1（AK/SK）

▼ 业务域分包（com.hy.cinepilot.module.*）

业务模块 systemboxofficeschedulingcdppricingwarning aimarketingopenapitenanthome

▼ MyBatis-Plus（多租户拦截 + 逻辑删除 + 分页）

数据层 MySQL 8（Flyway V1-V9，71 张表）Redis 7（缓存/配额计数）DemoDataGen 确定性演示数据

▲ LlmClient（OpenAI 兼容 /chat/completions）

AI 底座 DeepSeek V4 Flash（唯一基座）规则引擎 + 统计模型（降级）llm_call_log 调用留痕

2技术栈明细

层	技术选型	版本	用途
运行时	Java（Temurin JDK）	21	后端运行环境
框架	Spring Boot	3.2.5	Web / 依赖注入 / 定时任务
持久化	MyBatis-Plus	3.5.5	ORM、多租户拦截、逻辑删除、分页
数据库	MySQL	8.0	业务数据（Flyway V1-V9 迁移）
缓存	Redis	7	缓存、配额计数（dev 模式可关闭）
安全	Spring Security + JWT（jjwt）	6.2.4 / 0.12.5	登录鉴权、RBAC 数据范围
API 文档	SpringDoc OpenAPI	2.5.0	Swagger UI / v3/api-docs
前端	Vue 3 + TypeScript + Vite	3.4 / 5.4 / 5.2	SPA 界面
UI 组件	Element Plus / Pinia / ECharts	2.7 / 2.1 / 5.5	组件库 / 状态 / 图表
构建部署	Maven / npm / Docker Compose	3.9 / 20 / —	后端打包 / 前端构建 / 容器化（Podman 兼容）
AI 基座	DeepSeek V4 Flash（OpenAI 兼容）	—	RAG / NL 生成 / 营销 Agent 文案

3后端工程结构

com.hy.cinepilot
├── CinePilotApplication.java
├── common/          Result / BizException / DemoDataGen（确定性演示数据）
├── config/          SecurityConfig / MybatisPlusConfig / JwtUtil / DataInitializer
├── security/        JwtAuthenticationFilter / UserContext（线程级租户上下文）
└── module/
    ├── auth/        POST /api/auth/login·logout·me
    ├── home/        GET /api/home/kpis·box-trend·warnings·system-status
    ├── system/      区域/门店/门店树
    ├── boxoffice/   三级大盘/榜单/竞对/日报/归因/大屏
    ├── scheduling/  排片计划/预测回测/调排建议/偏好模型/效率
    ├── cdp/         OneID/RFM/活动/券/触达/唤醒
    ├── pricing/     四维定价/渠道/合规/审计/归因/票源约束
    ├── warning/     规则/目标占比/收件箱/扫描
    ├── ai/          模型/通道/监控/问答/知识库/应用工坊 + llm/LlmClient
    ├── marketing/   营销 Agent（策略/内容/下发/效果/效果库）
    ├── openapi/     开放平台管理 + 数据网关
    └── tenant/      租户/套餐/配额/账单

4数据字典（Flyway V1-V9，71 张表）

域	表
平台/SaaS	`sys_tenant` `sys_tenant_package` `sys_tenant_quota` `sys_tenant_bill` `sys_user` `sys_role` `sys_permission` `sys_user_role` `sys_role_permission` `sys_operation_log` `sys_data_source`
主数据	`cinema_region` `cinema_store` `cinema_hall` `cinema_seat_zone` `film` `competitor_store`
票房	`box_office_daily` `box_office_hourly` `box_office_film` `ticket_sale_detail` `ai_attribution` `daily_report` `daily_report_subscribe`
排片	`schedule_plan` `schedule_session` `schedule_suggestion` `schedule_consistency_check` `schedule_target_ratio` `predict_result` `predict_backtest` `local_preference_model` `session_efficiency`
CDP/营销	`member_profile` `member_identity` `member_merge_log` `member_rfm` `member_tag` `member_tag_relation` `campaign` `coupon_template` `coupon_instance` `campaign_touch_log` `wake_up_task`
定价	`price_zone_rule` `price_session_rule` `price_user_rule` `price_adjust_log` `price_clearance_log` `price_compliance_check` `channel_setting` `price_attribution` `ticket_source_constraint`
预警	`warning_rule` `warning_event` `notify_record` `notify_template`
AI 中台	`ai_model` `llm_channel` `llm_call_log` `kb_document` `qa_record` `ai_app`
营销 Agent	`mk_campaign` `mk_content` `mk_delivery` `mk_effect` `strategy_effect_lib`
开放平台	`open_app` `open_api_catalog` `open_api_log`

多租户约定：业务表均含 tenant_id，由 TenantLineInnerInterceptor 自动注入；豁免表：平台基础表（sys_tenant 等）、cinema_region、film、sys_user、open_api_catalog、open_app、open_api_log。逻辑删除统一 deleted 字段。

5关键机制

认证与授权

登录签发 JWT（HS384），请求经 JwtAuthenticationFilter 解析并写入 UserContext（线程级 ThreadLocal：userId/tenantId/dataScope/scopeIds）；数据范围 ALL/REGION/STORE 控制门店级可见性；开放平台数据网关独立走 AK/SK 鉴权（permitAll 后自行校验）。

AI 调用与降级

LlmClient 以 Java HttpClient 调用 {base-url}/chat/completions，携带 thinking:{type:disabled} 关闭推理（避免 token 被思考耗尽）；请求成功写入 llm_call_log（场景/Token/成本/延迟/状态）；所有业务调用方对异常统一降级到规则链/模板，保证演示可用性。

演示数据

DemoDataGen 以「门店名+ID+日期」哈希为种子生成稳定伪随机数据（票房/人次/上座率/均价/影片明细/榜单/归因），保证任意门店、任意日期的演示可复现。

6部署与运维

本机开发（推荐）

# 1. 容器（Podman，国内镜像源）
podman run -d --name cinepilot-mysql -e MYSQL_ROOT_PASSWORD=root123 -e MYSQL_DATABASE=cinema_cockpit -e MYSQL_USER=cinepilot -e MYSQL_PASSWORD=cinepilot123 -p 3306:3306 docker.m.daocloud.io/library/mysql:8.0
podman run -d --name cinepilot-redis -p 6379:6379 docker.m.daocloud.io/library/redis:7-alpine

# 2. 后端（prod，Flyway 自动建表灌数据）
cd backend
$env:SPRING_PROFILES_ACTIVE="prod"; $env:MYSQL_HOST="localhost"; $env:REDIS_HOST="localhost"
mvn spring-boot:run            # 或 java -jar target/cinepilot-1.0.0.jar

# 3. 前端
cd frontend && npm install && npm run dev   # http://localhost:5173

容器化一键部署

cd deploy
podman compose up -d --build     # 或 docker compose up -d --build；访问 http://localhost:8088

环境变量

变量	默认	说明
SPRING_PROFILES_ACTIVE	dev	prod 连接 MySQL/Redis
MYSQL_HOST / MYSQL_PORT / MYSQL_DB / MYSQL_USER / MYSQL_PASSWORD	localhost:3306 / cinema_cockpit / cinepilot / cinepilot123	数据库连接
REDIS_HOST / REDIS_PORT	localhost:6379	Redis 连接
LLM_BASE_URL / LLM_API_KEY / LLM_MODEL	http://192.168.20.132:3333/v1 / sk-… / deepseek-v4-flash	大模型基座（唯一）