目录结构

Nexus 采用标准的 Nuxt 4 单体仓库布局，并通过 modules/ 实现业务模块化。目录设计的核心目标是：让 Coding Agent 以更低成本理解项目（即 SPEC 中定义的「Agent Context 协议」）。

kesanai-nexus/
├── app/                  # Nuxt 应用层（页面 / 布局 / 组件 / composables / 多语言）
│   ├── pages/            # 路由页面，按 public / user / admin / modules 三层分离
│   ├── layouts/          # admin.vue / user.vue / module.vue 三种布局
│   ├── components/       # 业务组件 + ui/（shadcn-vue 组件库）
│   ├── composables/      # useAuth / useTheme / useI18n / useNexusAuth / useLocale ...
│   ├── locales/          # zh.ts / en.ts / index.ts（多语言包）
│   ├── middleware/       # locale.global / auth / admin 路由中间件
│   ├── assets/css/       # main.css + themes/（主题预设：默认 / 暖橙 / 黑金）
│   └── app.vue / app.config.ts / router.options.ts
├── modules/              # 可插拔业务模块（每个目录是一个独立模块）
│   ├── example/          # 最小可运行示例（pages / api / migrations / menu.json + nexus-module.json）
│   └── wechat-creator/   # 微信创作者模块（完整业务示例）
├── server/               # 服务端（Nuxt 服务器路由 / 工具函数 / 插件）
│   ├── api/              # 业务 API 路由（auth / ai / pay / admin / user / oauth / licenses ...）
│   ├── routes/           # 服务端路由（uploads / sitemap.xml / .well-known）
│   ├── utils/            # ai/（Provider 抽象）/ auth / credits / payments / modules / oauth ...
│   ├── database/         # schema.ts + migrations/（Drizzle 迁移）
│   ├── plugins/          # db-migrate / seed-admin / module-migrations / ai-task-poller
│   └── middleware/       # maintenance.ts
├── config/               # 配置化扩展入口
│   └── modules.ts        # 声明启用哪些模块（对应 modules/<name>/nexus-module.json）
├── shared/               # 前后端共享代码（如 theme.ts 设计 Token）
├── lib/                  # 根级工具（lib/utils.ts）
├── components/           # 根级共享 UI（components/ui）
├── composables/          # 根级共享 composables
├── public/               # 静态资源（logo / favicon / providers / uploads）
├── scripts/              # build-image.sh / start.sh / generate-init-sql.mjs
├── tests/                # structure / unit / e2e 测试
├── .oms/                 # 规格驱动开发体系（SPEC / CONTEXT / sprints / plans / feats ...）
├── .claude/              # Agent 规则与 Skill（rules / skills / settings.json）
├── docs/                 # 数据库 Schema 等说明
├── docker-compose.yml / docker-compose-full.yml / Dockerfile
├── nuxt.config.ts / drizzle.config.ts / package.json
└── .env / .env.example

关键目录说明

app/ —— 应用层

Nuxt 约定式路由与组件所在。页面按访问层级分目录：

• pages/admin/*：Admin 运营后台页面（用户、订单、积分、AI 模型、授权、工单等）。
• pages/user/*：登录后用户区页面。
• pages/modules/*：各业务模块注册的页面（由模块机制自动挂载）。
• layouts/：admin（后台布局）、user（用户区布局）、module（模块页布局）。
• composables/：以 use 开头的组合式函数，例如 useAuth（鉴权状态）、useTheme（主题切换）、useI18n（多语言）。
• locales/：多语言包（zh.ts / en.ts），运行期由系统配置页「语言」Tab 管理。

modules/ —— 业务模块

每个子目录是一个可插拔模块，自带 nexus-module.json（模块元信息）、pages/（页面）、api/（服务端路由）、migrations/（Drizzle 迁移）、menu.json（后台菜单）。模块在 config/modules.ts 中启用后，其页面、API、迁移、菜单会被构建期聚合、运行期加载。详见 模块机制。

server/ —— 服务端

Nuxt 的服务器引擎层（Nitro）：

• api/：按业务域组织的 API 路由，文件名即路由（users.get.ts → GET /api/users）。
• utils/ai/：AI Provider 适配器抽象（工厂 + OpenAI/Anthropic 适配器 + 模型解析 + 任务轮询），见 AI 基础设施。
• utils/payments/：微信 / 支付宝 / Mock 支付实现。
• database/：schema.ts（Drizzle 表定义）+ migrations/（迁移历史）。
• plugins/：启动期插件——db-migrate（自动迁移）、seed-admin（创建默认管理员）、module-migrations（执行模块迁移）、ai-task-poller（AI 异步任务轮询）。

config/ —— 配置化扩展

config/modules.ts 是唯一需要手动维护的「启用清单」，声明当前加载哪些模块。其余扩展（新页面、新 API、新迁移）都跟随模块目录自动生效。

.oms/ 与 .claude/ —— Agent 协作体系

• .oms/：规格驱动开发（SDD）的文档体系，包含项目顶层规格 SPEC.md、状态中转 CONTEXT.md、Sprint/Plan/Feat 归档等。
• .claude/：Coding Agent 的规则（rules/）与技能（skills/），让 Agent 以标准化方式理解并扩展项目。

详见 AI 驱动开发。

约定速查

类型	约定
页面	小写或 kebab-case（login.vue、user-profile.vue），默认页 index.vue
业务组件	FeatureName.vue；基础 UI 组件 UiButton.vue
API 路由	<resource>.<method>.ts（users.get.ts、users.post.ts）
Composables	camelCase，以 use 开头（useAuth.ts）
函数	动词 + 名词（getUserById、createUser）；布尔量 isValid / canEdit

更完整的代码风格见 项目规则体系。