From 26d1d391b75c63607acb624c698eecb068005e69 Mon Sep 17 00:00:00 2001 From: cloud370 Date: Tue, 23 Sep 2025 03:37:17 +0800 Subject: [PATCH] docs: enhance README with comprehensive project overview MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add detailed project description and core features - Update quick start guide with db:setup command - Enhance project structure documentation - Add core functionality sections - Link to comprehensive API and design docs - Improve formatting and organization 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- README.md | 88 +++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 69 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 204397f..e2fa908 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,20 @@ # Accounts Manager -轻量化账号管理平台 +轻量化账号管理平台 - 专为自动化脚本和Web管理设计的高性能账号管理系统 + +## 概述 + +Accounts Manager 是一个基于 TypeScript 和 Fastify 构建的轻量级账号管理平台，采用单表设计理念，为自动化脚本和管理后台提供独立优化的 API 接口。系统支持账号的获取、锁定、状态更新、批量管理等功能，并提供完善的统计分析能力。 + +## 核心特性 + +- 🚀 **高性能**: 基于 Fastify 框架，提供极快的 API 响应速度 +- 🔒 **并发安全**: 支持账号锁定机制，防止并发获取同一账号 +- 📊 **统计分析**: 提供详细的账号使用统计和概览数据 +- 🔄 **自动化**: 支持后台任务自动清理超时锁定 +- 🎯 **双API设计**: 为脚本和Web端提供专门优化的API接口 +- 💾 **简化设计**: 单表架构，降低系统复杂性 +- 🛡️ **类型安全**: 完整的 TypeScript 支持和 Zod 数据校验 ## 技术栈 @@ -38,11 +52,20 @@ LOCK_TIMEOUT_MINUTES=5 ### 3. 数据库设置 -运行数据库迁移： +初始化数据库： ```bash +# 创建数据库（如果不存在） +npm run db:create + +# 生成迁移文件 npm run db:generate + +# 运行迁移 npm run db:migrate + +# 或者一键设置（创建+迁移） +npm run db:setup ``` ### 4. 启动服务 @@ -113,23 +136,50 @@ npm run db:studio ``` src/ -├── api/v1/ -│ ├── script/ # 脚本API -│ └── web/ # 前端API -├── core/ # 业务逻辑 -├── db/ # 数据库配置 -├── jobs/ # 后台任务 -├── lib/ # 工具函数 -├── types/ # 类型定义 -├── config.ts # 配置 -└── index.ts # 入口文件 +├── api/v1/ # API 路由 +│ ├── script/ # 脚本专用API +│ │ └── actions.ts # 获取、更新、上传账号 +│ └── web/ # Web管理API +│ ├── accounts.ts # 账号CRUD操作 +│ └── stats.ts # 统计数据 +├── core/ # 核心业务逻辑 +│ └── AccountService.ts # 账号服务 +├── db/ # 数据库相关 +│ ├── index.ts # 数据库连接 +│ └── schema.ts # 表结构定义 +├── jobs/ # 后台任务 +│ └── staleLockCleanup.ts # 锁定清理任务 +├── lib/ # 工具库 +│ └── apiResponse.ts # 统一响应格式 +├── types/ # 类型定义 +│ ├── api.ts # API类型 +│ └── index.ts # 核心类型 +├── scripts/ # 脚本工具 +│ └── createDatabase.ts # 数据库创建 +├── config.ts # 应用配置 +└── index.ts # 应用入口 ``` -## 特性 +## 核心功能 -- **单表设计**: 简化数据模型 -- **OwnerID认证**: 基于URL的身份验证 -- **自动锁定管理**: 防止并发冲突 -- **后台清理任务**: 自动释放超时锁定 -- **统一响应格式**: 标准化API响应 -- **类型安全**: 完整的TypeScript支持 \ No newline at end of file +### 账号管理 +- **自动锁定**: 防止并发访问同一账号 +- **状态追踪**: 支持自定义账号状态管理 +- **批量操作**: 支持批量创建、更新、删除账号 +- **智能清理**: 自动释放超时锁定的账号 + +### API 接口 +- **脚本API**: 专为自动化脚本优化的轻量级接口 +- **管理API**: 功能完整的Web管理界面API +- **统一响应**: 标准化的API响应格式 +- **类型安全**: 完整的TypeScript类型定义 + +### 数据统计 +- **实时概览**: 账号总数、平台分布、状态统计 +- **详细分析**: 多维度数据统计和分析 +- **可视化友好**: 支持前端图表展示 + +## 详细文档 + +- [API文档](./docs/API文档.md) - 完整的API接口说明 +- [设计文档](./docs/设计.md) - 系统架构和设计理念 \ No newline at end of file