目录结构

仓库根

图 1 · 仓库目录分层

asone/
├── asone-server/                    # 后端 Maven 多模块工程
│   ├── asone-server-system/         # 共享内核 + 系统管理域
│   ├── asone-module-advertisement/  # 广告投放分析域
│   ├── asone-module-channel-report/ # 渠道报表同步域
│   ├── asone-module-iaa/            # IAA 变现分析域
│   ├── asone-server-boot/           # 唯一启动模块（聚合全部业务模块）
│   ├── Dockerfile / build.sh        # 后端镜像与本地构建入口
│   └── pom.xml                      # 父 POM：版本与依赖统一管理
├── asone-front/                     # 前端工程（UmiJS Max）
│   ├── config/                      # 构建配置、按业务域拆分的路由、代理
│   ├── src/                         # 页面、接口层、组件、Hook、文案
│   ├── Dockerfile / nginx.conf      # 前端镜像（nginx:alpine）与站点配置
│   └── build.sh
├── docs/                            # 文档工程
│   ├── api/                         # 接口文档工程（Vite + Scalar）
│   ├── docs/                        # 平台文档站（VuePress，内容在 docs/docs/docs）
│   └── developer-docs/              # 开发者文档站（VuePress，本站）
├── xxl-job/
│   ├── deploy/                      # 调度中心部署物料：Dockerfile、application.properties
│   └── xxl-job/                     # 上游官方源码（git submodule），不在开发范围
├── flow.yaml                        # 云效 Flow CI/CD 流水线
└── README.md

xxl-job/xxl-job/ 不在工作范围

xxl-job/xxl-job/ 是第三方 vendored 源码，父仓库只记录 commit 指针，改动既不会进入 diff，也会在 git submodule update 时丢失。所有编码、检索、审查、规范自查一律忽略它；需要调整行为时改 xxl-job/deploy/ 配置、调度中心任务参数或我们的执行器 task 代码。

后端单个业务模块

asone-module-xxx/src/main/java/com/qianxunclub/asone/xxx/
├── constants/        # 枚举、权限点、业务常量
├── controller/       # REST 入口，统一 /api 前缀
├── service/          # 业务编排、事务边界
├── mapper/           # MyBatis-Plus Mapper 接口
├── model/
│   ├── entity/       # 数据库实体
│   ├── request/      # 入参对象
│   └── response/     # 出参对象
├── dto/              # 内部传输对象（按域需要）
├── export/           # 导出任务处理器
├── task/             # @XxlJob 定时任务
└── config/           # 外部服务与渠道配置（按域需要）

asone-module-xxx/src/main/resources/
├── application-xxx.yml   # 模块级配置，需加入 boot 的 spring.profiles.include
├── mapper/*.xml          # MyBatis XML
└── i18n/messages-xxx*.properties  # 模块文案（默认中文，_en_US 英文）

asone-server-system 结构相同，额外承担全局能力：

包	内容
`annotation` / `aspect`	`@OperationLog`、`@ApiKeyAllowed` 及其切面
`configuration`	`SecurityConfiguration`、`MybatisPlusConfiguration`、`WebMvcConfiguration`、`GlobalResponseBodyAdvice`、`GlobalExceptionHandler`、`BizException`、`XxlJobExecutorConfiguration`
`security` / `filter` / `interceptor`	API Key 认证过滤器、CSRF Cookie 过滤器、用户活动过滤器、限流拦截器
`identity` / `notify` / `tenant` / `i18n` / `utils`	第三方身份登录、通知、租户、国际化、通用工具
`model/{dto,entity,request,response}`	全局返回体 `Result<T>` 位于 `model/dto`
`task`	`ExportTaskScheduler`、`ApprovalRetentionScheduler`、`IpLocationSyncTask`

启动模块

asone-server-boot/src/main/
├── java/com/qianxunclub/asone/AsoneServerApplication.java   # 唯一的 @SpringBootApplication
└── resources/
    ├── application.yml            # 端口、profiles.include、虚拟线程、数据源、xxl.job.*、actuator
    ├── application-local.yml      # 本地覆盖
    └── logback.xml

前端目录

asone-front/
├── config/
│   ├── config.ts               # UmiJS Max 主配置（非 .umirc.ts）
│   ├── proxy.ts                # 按 UMI_ENV 选择的后端代理
│   ├── routes.ts               # 汇总展开各业务域路由
│   └── routes/                 # advRoutes / iaaRoutes / systemRoutes / channelReportRoutes / approvalRoutes
├── src/
│   ├── pages/                  # Account / Advertisement / ChannelReport / Iaa / System / Login / Workplace + 403 / 404 / 500
│   ├── services/asone-server/  # 后端接口封装，按域 + controller 文件组织
│   ├── components/             # 跨页面复用组件
│   ├── hooks/                  # 自定义 Hook
│   ├── models/                 # 全局 Model：approvalTodo / exportTask / menuFavorite / menuRecent
│   ├── locales/{zh-CN,en-US}   # 中英文文案 + runtime.ts
│   ├── constants/              # 权限码、表头搜索等常量
│   ├── theme/                  # 主题与设计变量
│   ├── utils/                  # 工具函数
│   ├── types/                  # 类型定义
│   ├── access.ts               # 权限判定：normalRouteFilter / hasPermission / isSystemAdmin
│   ├── app.tsx                 # getInitialState
│   └── globalRequestConfig.ts  # 统一响应结构与请求拦截
└── scripts/                    # i18n-check 等工程脚本与其 node --test 用例

业务域对应关系：

图 2 · 一个业务域贯穿的六层落位

业务域	页面目录	接口目录	路由文件	后端模块
系统管理	`src/pages/System`、`src/pages/Account`	`src/services/asone-server/system`	`config/routes/systemRoutes.ts`	`asone-server-system`
广告投放	`src/pages/Advertisement`	`src/services/asone-server/advertisement`	`config/routes/advRoutes.ts`	`asone-module-advertisement`
渠道报表	`src/pages/ChannelReport`	`src/services/asone-server/channel-report`	`config/routes/channelReportRoutes.ts`	`asone-module-channel-report`
IAA 变现	`src/pages/Iaa`	`src/services/asone-server/iaa`	`config/routes/iaaRoutes.ts`	`asone-module-iaa`
审批	`src/pages/System/Approval`	`src/services/asone-server/system`	`config/routes/approvalRoutes.ts`	`asone-server-system`
工作台 / 登录	`src/pages/Workplace`、`src/pages/Login`	—	`config/routes.ts`	`asone-server-system`

文档与部署物料

内容	位置
仓库总览与速查	`README.md`
开发者文档站（本站源码）	`docs/developer-docs/docs/`
全量数据库 DDL	`docs/developer-docs/docs/public/1-ddl.sql`（站内下载链接 `/1-ddl.sql`）
平台文档站（使用者视角）	`docs/docs/docs/`
接口文档工程	`docs/api/`
渠道接口对接文档	`asone-server/asone-module-channel-report/docs/`
编码与流程规则	`.trae/rules/`
流水线定义	`flow.yaml`
调度中心部署配置	`xxl-job/deploy/Dockerfile`、`xxl-job/deploy/application.properties`

文档即代码的一部分

新增技术栈、新增模块 / 目录、调整架构或部署方式时，必须同步更新本站对应页面，规则见文档同步规则。