项目架构

工作区分工

包	技术	职责
@alang/site	Vue 3、Vite、Vant、Element Plus	Vue 前台
@alang/manage	React、TypeScript、Vite、Semi UI	管理后台与前端测试
@alang/service	JDK 21、Spring Boot 3.5、Gradle、wuli3	HTTP API、业务与数据访问
@alang/docs	VitePress	开发者文档

Turbo 调度包内 scripts；pnpm 管理 JavaScript 依赖；后端使用原有 Gradle Wrapper。 原始项目按源文件复制导入，三个相邻目录保留，不作为运行时依赖。

后端模块

alang-bootstrap 是唯一可执行模块，alang-common 提供共享能力。 用户、商品、资金、交易、合同、IM 与能力支持模块各拆为 -api 与 -service。 跨模块消费方只依赖 -api；bootstrap 组装 -service。

调用方向为 controller → service → repository → model，事务边界位于 service。 数据由归属模块写入，禁止直接操作其他模块的表或依赖其他模块的 -service。 SQL 使用 MyBatis XML，遵循后端 AGENTS.md 的仓储与 Mapper 约定。

前后端联调

浏览器访问后台 Vite 5602，业务 API 通过 /admin-api 代理至后端 5600。 请求携带 Authorization: Bearer <accessToken> 和 X-Wuli3-Principal-Permission-Token。 API 地址只使用路径前缀，生产通过 Nginx 代理维持同源。

演示页面的图片上传先调用 /admin-api/sts/credential 获取临时凭证和上传目标，再由浏览器直传 OSS。 对象路径使用返回的 directory，图片访问地址由 prefixUrl 与对象 key 拼接；OSS 上传不经过后端文件代理。 临时目录及过期清理约定见 部署指南。

文档与规格

docs/ 面向使用者，说明现状和操作步骤。openspec/specs/ 描述长期能力； openspec/changes/ 记录本次变更；openspec/rules/ 保存项目约束； openspec/state/ 记录已验证状态，openspec/design/ 记录设计原因。

Vue 前台在 5604 启动，保留上游脚本，由 Turbo @alang/site#dev 调用包级转发脚本，5604 端口仍在根 web:dev 维护；其 API 配置仍来自上游环境。