← 返回首页
仓库目录与根入口说明
# 仓库目录与根入口说明
本文是 anenreo 仓库结构的权威说明。目录收敛只解决可维护性，不代表 192 项领域功能已经完成。
## 根目录保留规则
受版本控制的根文件固定为 17 个，分为四类：
| 类别 | 文件 | 保留理由 |
|---|---|---|
| 工作区契约 | `.editorconfig`、`.gitignore`、`.npmrc`、`package.json`、`pnpm-lock.yaml`、`pnpm-workspace.yaml`、`tsconfig.base.json` | 编辑器、Git、包管理和 TypeScript 从根目录发现这些配置。 |
| 项目契约 | `AGENTS.md`、`README.md`、`docker-compose.yml` | Agent 规则、项目说明和基础设施编排的统一入口。 |
| 环境模板 | `.env.example`、`.env.production.example` | 只提供非秘密键名和部署模板；真实值不得提交。 |
| 人类入口 | `START-HERE.html`、`start-local.cmd`、`check-local.cmd`、`check-runtime.cmd`、`stop-local.cmd` | 一个导航页和四个 Windows 双击入口；实现统一放在 `scripts/`。 |
本机可额外存在 Git 忽略的 `.env.development` 与 `.env.test`。它们属于用户运行配置，不计入源码根文件，也不得进入候选包。
根目录禁止重新出现 PowerShell/Shell 实现、项目状态副本、升级 HTML、交接文档、Manifest、日志、截图、测试输出或打包产物。`tests/architecture/root-entry-surface.test.mjs` 对这条规则执行自动门禁。
## 一级目录职责
| 目录 | 单一职责 | 不应放入 |
|---|---|---|
| `apps/api/` | NestJS API、领域用例、Record Kernel、持久化、迁移和 API 测试 | PC/Mobile 页面、仓库级生成物 |
| `apps/web/` | Nuxt PC Web 页面、组件和浏览器端适配 | 服务端秘密、移动端专用代码 |
| `apps/mobile/` | uni-app Mobile/H5 页面、移动端网络与离线适配 | Provider 密钥管理、后端持久化 |
| `packages/contracts/` | 三端共享且可序列化的 DTO、枚举和协议 | 数据库行、框架对象、运行状态 |
| `packages/module-catalog/` | 24 模块、192 功能和展示元数据的权威目录 | 领域完成度的推断逻辑 |
| `docs/` | 设计、计划、标准、报告源和交接说明 | 可再生成 HTML、运行日志 |
| `docs-site/` | 由 `scripts/generate-docs.mjs` 生成并交付的静态 HTML 文档 | 人工维护的独立事实源 |
| `scripts/runtime/` | 本地安全启动、只读检查、范围化停止实现 | 根目录包装器、业务规则 |
| `scripts/quality/` | 本地质量门禁实现 | 业务运行时逻辑 |
| `scripts/lib/` | 仓库脚本共享的安全与生成基础设施 | 应用业务用例 |
| `tests/` | 仓库级架构、运行、修复、安全和跨端合同测试 | 应用生产代码 |
| `skills/` | 项目实现真实性规则及其检查器 | 通用业务实现 |
| `tools/` | 一次性维护、代码生成和批处理工具 | 日常运行入口 |
| `patches/` | pnpm 依赖补丁 | 项目源码副本 |
| `preview/` | 受版本控制的零安装静态产品预览 | 真实数据库、Provider 或用户秘密 |
| `reports/` | 候选包明确允许的少量脱敏、稳定证据 | 可再生成机器报告和本机日志 |
| `_work/` | Git 忽略的运行、构建、截图、报告、临时目录和发布输出 | 需要审查和长期维护的源码 |
## 代码依赖方向
```text
apps/web ─┐
apps/mobile ──> packages/contracts <── apps/api
└──> packages/module-catalog <── apps/api
apps/* ──> 各应用内部的 presentation/application/domain/infrastructure
scripts/* ──> 仓库治理与交付，不被 apps/* 作为业务运行时依赖
docs-site/* <── scripts/generate-docs.mjs <── docs/*
_work/* <── 所有可再生成输出
```
共享包只承载跨端合同和权威目录。领域规则、事务和持久化留在 API；PC 与 Mobile 只通过合同调用 API，不复制后端领域实现。仓库脚本不进入应用依赖图。
## 新文件放置判断
1. 是用户业务规则或持久化：放到 `apps/api` 对应领域切片。
2. 是 PC/Mobile 交互：放到对应应用，并复用 `packages/contracts`。
3. 是跨端可序列化协议：放到 `packages/contracts`。
4. 是模块或功能权威元数据：放到 `packages/module-catalog`。
5. 是设计、计划或报告源：放到 `docs` 的对应分类。
6. 是仓库自动化实现：放到 `scripts/runtime`、`scripts/quality` 或 `scripts/lib`。
7. 是可再生成结果：只写入项目直属 `_work`；需要交付的 HTML 由生成器写入 `docs-site` 或 `preview`。
如果新文件无法归入上述职责，应先解释新的稳定边界，不能直接堆到根目录。