chore: initialize clean metapi repository

docs/project-structure.md

@@ -0,0 +1,148 @@
+# Metapi 项目目录规范
+
+本文档说明 Metapi 的目录组织方式，目标是让新功能落位更稳定、查找更直接、临时文件不污染根目录。
+
+## 顶层目录
+
+```text
+metapi/
+├── data/                  # 运行时数据（SQLite 数据库）
+├── dist/                  # 构建产物（前后端）
+├── docker/                # 容器相关文件
+│   ├── Dockerfile         # 多阶段构建（Alpine）
+│   └── docker-compose.yml # Docker Compose 编排
+├── docs/                  # 文档与资源
+│   ├── logos/             # Logo 素材
+│   │   └── drafts/        # Logo 草稿
+│   └── project-structure.md
+├── drizzle/               # Drizzle ORM 迁移 SQL 与元数据
+├── scripts/               # 项目脚本（按场景分组）
+│   └── dev/
+│       └── restart.bat    # Windows 开发环境快捷重启
+├── src/
+│   ├── server/            # Fastify 后端服务
+│   └── web/               # React 前端应用
+├── tmp/                   # 临时调试文件（已 gitignore）
+├── package.json
+├── tsconfig.json
+├── tsconfig.server.json
+├── vite.config.ts
+└── README.md
+```
+
+## 后端目录约定（`src/server`）
+
+```text
+src/server/
+├── index.ts               # 服务启动入口
+├── config.ts              # 环境变量与配置加载
+├── middleware/
+│   └── auth.ts            # 认证中间件
+├── db/
+│   ├── index.ts           # 数据库连接
+│   ├── schema.ts          # Drizzle 表定义（全部 Schema）
+│   └── migrate.ts         # 迁移执行器
+├── routes/
+│   ├── api/               # 管理 API 路由
+│   │   ├── auth.ts        # 登录 / 登出
+│   │   ├── sites.ts       # 站点 CRUD
+│   │   ├── accounts.ts    # 账号管理
+│   │   ├── accountTokens.ts # Token 同步与管理
+│   │   ├── tokens.ts      # Token 批量操作
+│   │   ├── tokenRoutes.ts # 路由规则管理
+│   │   ├── checkin.ts     # 签到触发与日志
+│   │   ├── stats.ts       # 仪表盘统计
+│   │   ├── search.ts      # 全局搜索
+│   │   ├── events.ts      # 事件日志
+│   │   ├── tasks.ts       # 后台任务状态
+│   │   ├── settings.ts    # 运行时配置
+│   │   ├── monitor.ts     # 外部监控集成
+│   │   └── test.ts        # 测试 / 验证端点
+│   └── proxy/             # 代理路由
+│       ├── router.ts      # 代理路由注册
+│       ├── chat.ts        # Chat Completions & Claude Messages
+│       ├── completions.ts # Legacy Completions
+│       ├── embeddings.ts  # 向量嵌入
+│       ├── images.ts      # 图像生成
+│       ├── models.ts      # 模型列表
+│       └── chatFormats.ts # OpenAI <-> Claude 格式转换
+└── services/
+    ├── platforms/          # 平台适配器
+    │   ├── base.ts         # 适配器接口定义
+    │   ├── index.ts        # 适配器注册表
+    │   ├── newApi.ts       # New API 适配器
+    │   ├── oneApi.ts       # One API 适配器
+    │   ├── oneHub.ts       # OneHub 适配器
+    │   ├── doneHub.ts      # DoneHub 适配器
+    │   ├── veloera.ts      # Veloera 适配器
+    │   ├── anyrouter.ts    # AnyRouter 适配器
+    │   └── sub2api.ts      # Sub2API 适配器
+    ├── tokenRouter.ts              # 智能路由引擎
+    ├── checkinService.ts           # 签到执行
+    ├── checkinScheduler.ts         # 签到调度
+    ├── checkinRewardParser.ts      # 奖励金额解析
+    ├── balanceService.ts           # 余额刷新
+    ├── modelService.ts             # 模型发现与管理
+    ├── modelPricingService.ts      # 模型定价
+    ├── modelAnalysisService.ts     # 使用分析
+    ├── notifyService.ts            # 多渠道通知
+    ├── notificationThrottle.ts     # 通知节流
+    ├── alertService.ts             # 告警事件
+    ├── alertRules.ts               # 告警规则
+    ├── backupService.ts            # 数据导入导出
+    ├── backgroundTaskService.ts    # 后台任务管理
+    ├── accountCredentialService.ts # 凭证加密
+    ├── accountHealthService.ts     # 健康状态管理
+    ├── accountExtraConfig.ts       # 平台专属配置
+    ├── proxyRetryPolicy.ts         # 重试策略
+    ├── proxyUsageParser.ts         # Token 用量解析
+    ├── proxyUsageFallbackService.ts # 余额兜底估算
+    ├── failureReasonService.ts     # 错误分类
+    ├── siteDetector.ts             # 平台自动检测
+    ├── dailySummaryService.ts      # 每日摘要
+    ├── todayIncomeRewardService.ts # 今日收入快照
+    ├── localTimeService.ts         # 时区处理
+    ├── upstreamModelDescriptionService.ts # 上游模型描述缓存
+    ├── startupInfo.ts              # 启动信息
+    └── settings.ts                 # 运行时配置管理
+```
+
+## 前端目录约定（`src/web`）
+
+```text
+src/web/
+├── App.tsx                # 应用入口与路由配置
+├── main.tsx               # Vite 入口
+├── api.ts                 # 统一 API 请求客户端
+├── authSession.ts         # 认证会话管理
+├── i18n.tsx               # 国际化
+├── components/            # 通用 UI 组件
+│   ├── BrandIcon.tsx      # 模型品牌图标
+│   ├── ModelAnalysisPanel.tsx # 消费分析图表
+│   ├── SearchModal.tsx    # 全局搜索弹窗
+│   ├── NotificationPanel.tsx # 实时事件面板
+│   ├── Toast.tsx          # 通知提示
+│   ├── SiteDistributionChart.tsx # 余额分布饼图
+│   └── SiteTrendChart.tsx # 消费趋势图
+├── pages/                 # 页面组件（路由页）
+│   ├── Dashboard.tsx      # 仪表盘
+│   ├── Sites.tsx          # 站点管理
+│   ├── Accounts.tsx       # 账号管理
+│   ├── Tokens.tsx         # Token 管理
+│   ├── TokenRoutes.tsx    # 路由规则
+│   ├── Models.tsx         # 模型广场
+│   ├── CheckinLog.tsx     # 签到日志
+│   ├── ProxyLogs.tsx      # 代理日志
+│   ├── Settings.tsx       # 系统设置
+│   ├── About.tsx          # 关于页面
+│   └── helpers/           # 页面级纯逻辑 / 工具函数（含测试）
+└── public/                # 静态资源
+```
+
+## 目录卫生规则
+
+- 所有调试临时文件放入 `tmp/`，不要散落在项目根目录。
+- 开发脚本统一放入 `scripts/<scene>/`，根目录仅保留必要入口文件。
+- 素材草稿统一归档到 `docs/logos/drafts/`，避免根目录堆积二进制文件。
+- 测试文件与被测文件同目录（`*.test.ts`），方便就近维护。
+- 平台适配器新增时，在 `services/platforms/` 中创建独立文件并注册到 `index.ts`。