项目架构总览

受众：开发者摘要：项目架构方向、模块结构、设计抽象、组件选型。细节规范见 conventions.md；各 starter 详细状态见对应文档。

项目定位

详见 .ai/decisions/adr-001-project-positioning.md。

在 Spring Boot 标准体系之上提供接近 Laravel 的开发体验：

底层遵循 Spring Boot 标准扩展方式：starter / auto-configuration / properties / condition / actuator
上层吸收 Laravel 优点：约定优先 / 短名 Facade / Provider 化扩展 / 配置简洁 / 模块开箱即用
默认运行依赖保持简单：应用 + Redis + MySQL/PostgreSQL；lite profile 仅作为历史兼容和隔离诊断的单进程模式，不作为普通开发推荐路径
框架名用于 Maven 坐标、包名、配置前缀和文档；业务代码 API 避免强项目命名

模块结构

详见 .ai/decisions/adr-002-module-boundaries.md；快速决策"新代码放哪儿"与四层 / 引擎↔控制台配对看模块地图，命名 / 分族 / system 拆解的 v2 治理见 .ai/decisions/adr-045-module-governance-taxonomy.md（目标命名分档落地中，下方仍为当前形态）。

text

spring-open
├── spring-open-dependencies          # 依赖版本管理
├── spring-open-parent                # 构建父模块
├── spring-open-starters
│   ├── spring-open-starter-toolkit
│   ├── spring-open-starter-common        # 纯 Java 基石：Result / 异常 / 分页 / TraceId / Money 值对象 / 常量（包 com.springopen.starter.common.*，非自动装配 starter）
│   └── spring-open-starter-*             # 技术能力 starter
├── spring-open-core                  # 框架核心运行时能力聚合（非纯 Java 层）
│   ├── spring-open-core-iam          # 统一身份底座：IAM / 用户 / RBAC
│   ├── spring-open-core-config       # 配置中心底座
│   ├── spring-open-core-knowledge    # Knowledge 后台管理面
│   ├── spring-open-core-plugin       # Plugin 后台治理面：状态 / 生命周期 / 执行审计
│   ├── spring-open-core-organization          # 组织岗位底座
│   ├── spring-open-core-money        # 资金钱包底座：余额资金
│   ├── spring-open-core-web3         # 链上能力底座
│   ├── spring-open-core-cashier      # 支付收银台底座
│   ├── spring-open-core-entitlement  # 权益底座
│   ├── spring-open-core-voucher      # 通用卡券底座
│   ├── spring-open-core-conversation # 通信底座：IM 会话
│   ├── spring-open-core-notification # 通知底座：站内信 / 通知规则 / 发送日志
│   ├── spring-open-core-async-task   # 异步任务底座：任务生命周期 / CSV 导出
│   ├── spring-open-core-content-safety # 内容安全底座：词库 / 检测日志 / 复核任务
│   ├── spring-open-core-reporting    # 报表底座：定义 / 快照 / 异步导出聚合
│   ├── spring-open-core-risk         # 风控底座：规则 / 限额 / 冻结 / 人工复核
│   ├── spring-open-core-runtime      # 通用运行时底座：开放 API / 演示数据清理 contract
│   ├── spring-open-core-approval-workflow # Approval Workflow 运维底座：只读后台流程目录与待办摘要
│   ├── spring-open-core-observability # Observability 运维底座：只读后台观测目录
│   ├── spring-open-core-document     # Document 运维底座：只读后台 Provider 目录
│   ├── spring-open-core-rate-limit   # Rate Limit 运维底座：只读后台 store / 响应头 / runbook 快照
│   ├── spring-open-core-queue        # Queue 运维底座：指标 / 失败任务重试
│   ├── spring-open-core-scheduler    # Scheduler 运维底座：任务状态 / 执行日志 / 失败告警
│   ├── spring-open-core-database-backup # 数据库备份运维底座：手动 / 定时备份、校验、加密、副本、下载和保留策略
│   ├── spring-open-core-websocket    # WebSocket 运维底座
│   ├── spring-open-core-audit        # 操作审计日志底座
│   ├── spring-open-core-sqlconsole   # 应急 SQL 控制台底座
│   ├── spring-open-core-secret       # 通用 Secret / BYOK / 轮换 / 掩码底座
│   ├── spring-open-core-site         # 站点公开信息底座
│   ├── spring-open-core-dict         # 字典底座
│   ├── spring-open-core-i18n         # 多语言文案底座
│   └── spring-open-core-template     # 文本模板底座
├── spring-open-modules               # 纯业务叶子模块（互不依赖）
│   ├── spring-open-module-cms        # 内容管理
│   ├── spring-open-module-blog       # 博客
│   ├── spring-open-module-forum      # 论坛
│   ├── spring-open-module-mall       # 商城
│   ├── spring-open-module-short-link # 短链接
│   ├── spring-open-module-live-code  # 活码
│   ├── spring-open-module-live       # 直播
│   ├── spring-open-module-search     # 统一搜索
│   ├── spring-open-module-ai         # AI 模型平台 / 网关
│   ├── spring-open-module-open-platform  # 开放平台
│   └── spring-open-module-install    # 企业安装向导
├── spring-open-views                 # 前端构建模块聚合
│   ├── spring-open-view-docs         # VitePress 文档站
│   ├── spring-open-view-install      # 安装向导
│   ├── spring-open-view-admin        # 后台管理
│   ├── spring-open-view-app          # uni-app 移动端
│   └── spring-open-view-pc           # Nuxt 4 PC 端
├── spring-open-application           # 应用装配入口
└── views/                            # 前端源码（docs / install / app / admin / pc）

上图是当前主线形态。所有 spring-open-core-* 底座能力模块都直接挂在 spring-open-core/ 下；平台域与运行时服务 / 控制台域只作为职责分类，不再新增 Maven 分组聚合层。conversation / notification / async-task / content-safety / reporting / risk / entitlement / voucher / cashier / runtime / secret / money 已归位 spring-open-core-*；web3 / websocket / scheduler / queue / database-backup / sqlconsole / site / dict / i18n / template / audit / organization / iam / config / knowledge / plugin 已从大模块剥离到 spring-open-core-*；历史 spring-open-core-system 和过渡 spring-open-core-resources 当前不存在，模块边界由真实 owning module、依赖方向和迁移归属维护，不按 system 字面量设禁区；演示数据清理入口已归入 install，贡献 contract 留 core-runtime。

模块职责：

区域	职责
`spring-open-dependencies`	依赖版本管理，继承 Spring Boot parent
`spring-open-parent`	构建父模块，管理 Maven 插件和 profile
`spring-open-starter-toolkit`	纯 Java 工具，不依赖 Spring
`spring-open-core`	框架核心运行时能力聚合层，不等同于纯 Java 层（只含 `core-*` 运行时底座）
`spring-open-starter-common`	纯 Java 原语和值对象层：Result、异常、分页、TraceId、Money 值对象、常量、通用契约；只向下依赖 `spring-open-starter-toolkit`，不依赖 Spring / DB / Controller / `core-*` 运行时
`spring-open-core-*`（运行时底座）	带 Spring/DB/API 的中性底座（ADR-044 / ADR-045）：`core-iam` / `core-config` / `core-knowledge` / `core-plugin` / `core-conversation` / `core-notification` / `core-async-task` / `core-content-safety` / `core-reporting` / `core-risk` / `core-entitlement` / `core-voucher` / `core-cashier` / `core-runtime` / `core-secret` / `core-money` / `core-web3` / `core-websocket` / `core-scheduler` / `core-queue` / `core-database-backup` / `core-rate-limit` / `core-approval-workflow` / `core-observability` / `core-document` / `core-sqlconsole` / `core-site` / `core-dict` / `core-i18n` / `core-template` / `core-audit` / `core-organization` 已归位或剥离；历史 `core-system` 和过渡 `core-resources` 已删除；物理位于 `spring-open-core/spring-open-core-*`
`spring-open-starter-execution`	钩子 / 管道 / 责任链共享执行上下文、类型安全 key 和中止状态
`spring-open-starter-chain`	条件决策责任链，Handler 显式 `proceed` 才继续传递
`spring-open-starters`	框架 starter 聚合
`spring-open-modules`	纯业务叶子模块（互不依赖；跨模块走事件 / SPI / Provider / 标量 ID）
`spring-open-views`	前端构建模块聚合，不放业务代码
`spring-open-application`	应用启动与装配，不写业务逻辑

模块边界规则：

spring-open-application 只负责装配和配置，不承载业务
spring-open-application 作为组合根显式声明所装配的核心运行时模块与业务模块 Maven 依赖；连接两个 core 的跨核桥接归各自 owning core 模块，不再设独立桥接仓（ADR-045 B1 已拆除 spring-open-core-integrations）
starter 和业务模块不反向依赖 application
spring-open-starter-common 保持纯 Java 边界；spring-open-core 是核心聚合名，不把整个 core 误写成纯 Java 层
业务模块之间不互相建立 Maven 依赖；跨模块能力优先通过事件、Facade、Provider 或 starter 抽象连接
需要跨两个业务模块的场景，先抽象为顶层稳定接口，再由具体模块提供实现；例如 Mall 余额支付只调用 Payment provider，Money 余额模块提供 balance provider
spring-open-starter-toolkit 不依赖 Spring Boot / Spring Framework / 数据库 / Web / i18n
第三方 SDK 隐藏在 starter 抽象之后，不暴露为业务可见 provider 名

业务模块后期剥离

详见 modules.md 业务模块剥离规划。

cms / blog / forum / mall / marketing / marketplace / live / video / reading 当前在主仓库孵化，后期都要能剥离为基于本框架的独立二次开发项目。

定位：「基于框架的产品能力」，不是框架核心。开发时必须保持：

独立 Maven 模块、独立配置前缀、独立 API 前缀、独立表前缀、独立权限前缀
可从应用装配注释或移除，不影响核心模块 / 其他业务模块 / starter / 视图构建
只依赖框架对外稳定能力（IAM / Storage / Search / Notification / Payment / Queue / Scheduler / WebSocket）
不把模块专属常量、业务枚举、菜单、权限、配置、表结构或路由写入 spring-open-core / 通用 starter / 其他业务模块
需要框架增强时先抽象通用扩展点；只有通用能力进入 core / starter，产品专属逻辑留在模块内

剥离后的理想形态：独立项目拥有自己的应用装配、前端视图、部署文档和发布节奏，同时继续以本框架作为基础框架。

业务模块反哺底座

业务模块也是框架底座的孵化来源。Blog / Forum / Mall / Distribution / App / PC / XBox 等真实产品线先解决具体业务问题；同一能力出现两个以上明确消费方时再抽象为底座。

抽象流程：

先在真实模块内孵化能力
出现第二个消费方后评估抽象为底座
抽出通用 API / Facade / Provider / 事件 / 权限 / 配置 / 文档
原模块回退为底座消费者，不继续维护重复私有实现
补充「孵化模块移除后仍可用」和「至少两个模块接入」的验证或说明

底座优先级：通信底座 → 用户与附件底座 → 内容社区底座 → 交易履约底座 → 权益与 Web3 底座 → 增长与 AI 底座 → 产品模块闭环。如果某个底座阻塞多个模块，优先级高于普通业务页面；只有单个模块使用的能力先留模块内孵化。

适合反哺的能力：用户公开资料、关注关系、互动审核、发布状态、分类标签、Feed、会话通知、交易履约事件、钱包身份、Gate / Entitlement、邀请分享、用户偏好、业务附件、AI Bot 会话桥接。

模块专属实体留在模块内：Blog 文章 / Forum 主题、回帖 / Mall 订单 / Distribution 佣金 / XBox 社区玩法等。

模块分层与膨胀治理

模块按四层单向依赖组织（详见 .ai/decisions/adr-044-module-layering.md）：

text

spring-open-starter-toolkit  ←  spring-open-starter-common  ←  spring-open-starters  ←  spring-open-core-*（运行时底座）  ←  spring-open-modules

starter-toolkit / common / starters：纯技术原语与基石与技术 starter；spring-open-starter-common 位于 spring-open-starters/spring-open-starter-common，保持纯 Java、无 AutoConfiguration，只向下依赖 starter-toolkit，通用 starter 只依赖 spring-open-starter-common。
核心运行时 / 底座能力模块：中性、可被任意业务模块依赖、只向下依赖、绝不依赖业务模块、不成环。iam（IAM / 账号 / RBAC / 租户 / 数据范围 / 工作空间）、config（配置 / 分类 / 变更日志）、knowledge（Knowledge 后台管理面）、plugin（Plugin 后台治理面）、notification（站内信 / 通知规则 / 发送日志）、async-task（异步任务 / CSV 导出）、content-safety（内容安全词库 / 检测日志 / 复核任务 / 批量扫描）、reporting（报表定义 / 即时快照 / 异步导出聚合）、risk（风控规则 / 限额 / 冻结 / 人工复核）、dict（字典）、i18n（多语言文案）、template（文本模板后台 / 仓储）、file（文件元数据 / 当前用户文件 / 媒体资产绑定）、runtime（开放 API contract / 演示数据清理贡献 contract）、secret（通用可逆 Secret 加密 / 解密 / 掩码）、websocket（在线会话运维 / 用户解析）、scheduler（调度任务运维 / 执行日志）、queue（队列运维 / 失败任务重试）、database-backup（数据库备份运维）、rate-limit（限流运维 / store 快照）、money（余额）、web3（链上能力）、audit（操作审计日志）、organization（岗位 / 用户岗位关系）、conversation（IM 通信）、cashier（支付收银台）、entitlement（权益）、voucher（通用卡券）。核心运行时底座位于 spring-open-core/spring-open-core-* 直接子模块，不进 spring-open-starter-common；system 是正常业务语义，是否作为模块名或路由名使用只按职责评估。
业务模块（叶子）：blog / forum / cms / chat / mall / short-link / live-code / live / search / ai / open-platform / advertising / payment-platform / distribution / marketplace / marketing / form / meeting / reading / video / install。互不建立 Maven 依赖，跨模块只保存标量 ID，联动走事件 / SPI / Provider。

治理目标：历史巨石模块曾同时承载平台基础、运行时基建和 web3 / balance / conversation 业务域，体量过大、被全员依赖。当前已剥离 Conversation、Notification、Money、Web3、WebSocket、Scheduler、Queue、Support、SQL 控制台、平台元数据、操作审计、岗位域、IAM、Config、Knowledge、Plugin 和演示数据清理等能力；是否使用 system 命名不再按历史债一刀切限制，而是按真实 owning module、依赖方向和迁移归属判断。

Starter 架构

详见 .ai/decisions/adr-003-one-capability-one-starter.md 和 starters.md。

前期坚持：

一个功能，一个 starter；一个 starter，一个完整体验。

例：多语言和翻译分别直接做 spring-open-starter-i18n + spring-open-starter-translate，暂不拆 core / autoconfigure / starter 三层。

后续拆分条件：

provider 引入很重的第三方依赖
用户明显需要按需引入
多个 starter 复用同一套核心契约
模块代码规模变大、维护成本上升
需要单独发布某个 provider

Provider 扩展模型

可替换能力统一采用 Facade -> Manager -> Resolver -> Provider SPI。职责、标准文件结构、配置约定和迁移规则见 Provider 扩展模型。

配置模型

详见 configuration.md 和 config.md。

统一配置前缀：

yaml

spring:
  open:
    config:
      enabled: true
    auth:
      persistence:
        store: redis
    cache:
      default-provider: redis
      providers:
        redis:
          provider: redis

规则：

配置 key 使用 kebab-case
Java properties 字段使用 camelCase
每个 starter 必须提供 @ConfigurationProperties
每个 starter 必须使用 Spring Boot 标准自动配置方式

读取优先级：

后台数据库配置（config_entry）
本地 application.yml / application-*.yml
环境变量 / .env
默认值

数据库配置覆盖能力适用于 Mail / SMS / Storage / Payment / Translate / Notification / Web3 等需要运行时切换的能力。

详细 RuntimeConfigSource 机制（数据库 provider 接入 / 缓存链路 / 多实例广播 / 配置变更日志）见 config.md。

Web 与 API

详见 .ai/decisions/adr-007-web-api-spec.md 和 web.md。

Controller 统一返回 ResponseEntity<?>
普通 JSON 的响应体使用 Result<T>
HTTP status 只表传输层结果，业务状态由 Result.code 表达
Controller 不写业务逻辑；入参 DTO + Validation，出参 VO
REST API 必须带版本：/api/v1/{domain}/**；后台管理 API 对外统一使用 /api/v1/admin/{domain}/**
根路由 / 由 View Starter 提供低优先级智能兜底（见 .ai/decisions/adr-026-view-root-route.md）

IAM 主线

详见 .ai/decisions/adr-008-unified-iam.md 和 iam.md。

统一账号体系：

iam_user 是唯一账号主体
管理员、普通用户、商户、开发者通过角色、权限、身份绑定和 profile 扩展
当前阶段不拆 admin_user / user
当前阶段统一使用 Sa-Token StpUtil
多租户、多组织、多部门、数据权限在统一账号体系上扩展

数据权限走显式接入（见 .ai/decisions/adr-009-explicit-data-scope.md），不启用全局 SQL 拦截器。

业务模块清单

详见 modules.md。

模块	API 前缀	文档	阶段
`spring-open-core-iam`	`/api/v1/auth/` `/api/v1/iam/` `/api/v1/admin/iam/**`	iam.md	已建立
`spring-open-core-knowledge`	`/api/v1/knowledge/` `/api/v1/admin/knowledge/`	knowledge.md	已建立
`spring-open-core-plugin`	`/api/v1/admin/plugins/**`	plugin.md	已建立
`spring-open-module-cms`	`/api/v1/cms/**`	cms.md	已建立
`spring-open-module-blog`	`/api/v1/blog/**`	blog.md	已建立
`spring-open-module-forum`	`/api/v1/forum/**`	forum.md	已建立
`spring-open-module-mall`	`/api/v1/mall/**`	mall.md	已建立
`spring-open-module-search`	`/api/v1/search/**`	search.md	已建立
`spring-open-module-ai`	`/api/v1/admin/ai/platform/`、`/api/v1/ai/platform/`、`/api/v1/ai/console/`、`/api/v1/ai/gateway/`	ai.md、ai-platform.md、ai-gateway.md	已建立独立 AI 模块和用户侧 AI Console
`spring-open-module-open-platform`	`/api/v1/open/**`	open-platform.md	可选；开放 API 底座已建立
`spring-open-module-install`	`/api/v1/install/**`	install.md	第一阶段

V1.0 之后规划：distribution / marketing / marketplace / live / video / reading / xbox（详见对应 ADR 和 .ai/modules/）。

运行目录语义

目录	语义
`public/`	公开静态资源，挂载到根路由（例 `public/test.txt` → `http://localhost:8000/test.txt`）
`storage/`	本地存储根目录
`storage/runtime/`	临时运行文件，可删除
`storage/runtime/cache/`	文件缓存目录（不进 Git）
`storage/runtime/logs/`	Spring Boot 日志目录（不进 Git）
`public/docs/`	VitePress 构建产物（不进 Git）

前端构建

详见 .ai/decisions/adr-014-frontend-source-build.md 和 frontend.md。

源码统一 views/<name> + Maven spring-open-views/spring-open-view-<name> + 产物 public/<name>
当前覆盖 docs / install / admin / app / pc
视图聚合命令：./mvnw -f spring-open-views/pom.xml package -DskipTests
视图构建总开关：-Dbuild.skip.views=true 跳过
spring-open-application 不依赖 view 模块，不被前端构建污染
Node / pnpm 工具链版本统一固定，见 .ai/stack.md

组件选型

详见 .ai/stack.md 和 .ai/decisions/adr-005-ecosystem-first.md。

能力	当前优先生态
Auth	Sa-Token
Data	MyBatis-Plus
Redis	Redisson
Scheduler	db-scheduler
SMS	sms4j
Storage	x-file-storage
OAuth / 社交登录	JustAuth
Payment	IJPay 或服务商官方 SDK
文档站	VitePress
后台模板	vue-pure-admin（仅 `views/admin`）
App 移动端	uni-app
PC 端	Nuxt 4 + Vue 3 + TypeScript

生态库只隐藏在项目抽象边界内，不作为业务可见 provider 名。

本地运行

详见 getting-started.md。

bash

# 启动基础环境（MySQL + Redis）
docker compose -f docker/docker-compose.yml up -d

# 启动应用
./mvnw -pl spring-open-application spring-boot:run

# 如需隔离诊断可显式使用 lite；普通开发不推荐使用
./mvnw -Plite -pl spring-open-application spring-boot:run

全新 checkout 或执行过 mvn clean 后，先运行 ./mvnw -pl spring-open-application -am install -DskipTests -DskipITs -DskipFrontend 安装应用依赖，再运行应用模块；不要把 -am 和 spring-boot:run 组合使用。

完整 Docker 部署（含 Nginx）参见 docker.md 和 deployment.md。

应用骨架

详见 getting-started.md。

主应用：spring-open-application，直接装配业务模块、应用级运行时依赖和测试依赖；业务模块显式声明自己需要的具体 spring-open-starter-*，不再依赖 all-in-one starter 兜底

参考

各 ADR 决策详细：.ai/decisions/
AI Agent 操作契约：AGENTS.md
文档写作规范：.ai/STYLE.md
当前进度：.ai/progress.md
当前路线图：.ai/roadmap.md

项目架构总览 ​

项目定位 ​

模块结构 ​

业务模块后期剥离 ​

业务模块反哺底座 ​

模块分层与膨胀治理 ​

Starter 架构 ​

Provider 扩展模型 ​

配置模型 ​

Web 与 API ​

IAM 主线 ​

业务模块清单 ​

运行目录语义 ​

前端构建 ​

组件选型 ​

本地运行 ​

应用骨架 ​

参考 ​