Yuan-ICP 项目文档

Appearance

项目结构 ​

本文档详细介绍 Yuan-ICP 项目的目录结构和核心文件，帮助开发者快速了解项目组织方式。

📁 总体目录结构 ​

Yuan-ICP/
├── admin/                  # 后台管理模块
├── api/                    # API接口模块
├── config/                 # 配置文件目录
├── data/                   # 数据存储目录
├── includes/               # 核心功能库
├── install/                # 安装程序
├── plugins/                # 插件目录
├── scripts/                # 前端脚本
├── themes/                 # 主题目录
├── uploads/                # 上传文件目录
├── vendor/                 # Composer依赖
├── index.php               # 前台入口文件
├── apply.php               # 备案申请页面
├── query.php               # 备案查询页面
├── result.php              # 申请结果页面
├── select_number.php       # 号码选择页面
├── announcements.php       # 公告列表页面
├── announcement.php        # 公告详情页面
├── leap.php                # 闰年相关功能
├── composer.json           # Composer配置
└── LICENSE                 # 开源协议

🏠 前台核心文件 ​

index.php ​

系统首页入口

  • 检查系统安装状态
  • 加载系统配置和公告信息
  • 显示统计数据（总申请数、已通过数等）
  • 使用主题系统渲染页面
php
// 关键功能
- 安装检查：未安装时自动跳转到安装向导
- 配置加载：从数据库加载系统配置
- 数据统计：查询备案申请统计信息
- 主题渲染：使用ThemeManager渲染页面

apply.php ​

备案申请页面

  • 处理用户备案申请表单
  • 验证用户输入数据
  • CSRF防护机制
  • 将申请数据存储到Session中
php
// 主要功能
- 表单验证：网站名称、域名、邮箱格式验证
- CSRF保护：防止跨站请求伪造
- 数据暂存：将申请信息存储到Session
- 流程跳转：验证通过后跳转到号码选择页面

select_number.php ​

号码选择页面

  • 支持两种号码获取模式
  • 号码池选择或自动生成
  • 靓号识别和标识
  • 完成备案申请提交

query.php ​

备案查询功能

  • 支持按备案号或域名查询
  • 仅显示已审核通过的备案
  • 查询结果详细展示
  • 防止未授权访问
php
// 查询特性
- 多条件查询：支持备案号和域名查询
- 状态过滤：只显示approved状态的备案
- 安全控制：防止查询敏感信息
- 结果展示：完整的备案信息显示

🛠️ 后台管理模块 (admin/) ​

dashboard.php ​

管理仪表盘

  • 系统统计数据展示
  • 最近备案申请列表
  • 数据缓存机制
  • 响应式管理界面
php
// 核心功能
- 统计缓存：5分钟缓存机制提高性能
- 数据概览：总数、待审核、已通过、已驳回统计
- 最近活动：显示最新5条备案申请
- 快速操作：提供常用功能快速访问

applications.php ​

备案申请管理

  • 申请列表展示和筛选
  • 审核操作（通过/驳回）
  • 分页功能支持
  • 邮件通知发送
php
// 主要特性
- 高级筛选：按状态、关键词筛选
- 批量操作：支持批量审核操作
- 邮件通知：审核结果自动邮件通知
- 靓号标识：自动识别并标识靓号
- 分页展示：支持大量数据分页显示

其他后台文件 ​

  • announcements.php - 公告管理
  • settings.php - 系统设置
  • numbers.php - 号码池管理
  • themes.php - 主题管理
  • plugins.php - 插件管理
  • logs.php - 操作日志
  • backup.php - 数据备份

🔌 API接口模块 (api/) ​

get_numbers.php ​

号码获取API

  • RESTful API设计
  • 支持双模式号码获取
  • JSON格式数据返回
  • 防重复号码机制
php
// API特性
- 双模式支持：自动生成模式和号码池模式
- 数据格式：标准JSON格式返回
- 防重复：确保返回的号码唯一性
- 靓号标识：自动标识靓号属性

📚 核心功能库 (includes/) ​

functions.php ​

核心函数库 包含系统所有核心功能函数：

数据库相关 ​

php
db()                    # 获取数据库连接
config()               # 加载配置文件
is_installed()         # 检查系统安装状态
db_now()              # 获取数据库时间戳

安全功能 ​

php
hash_password()        # 密码哈希
verify_password()      # 密码验证
generate_csrf_token()  # 生成CSRF令牌
validate_csrf_token()  # 验证CSRF令牌
sanitizeInput()        # 输入数据清理

业务逻辑 ​

php
generate_unique_icp_number()      # 生成唯一备案号
is_premium_number()              # 判断是否为靓号
check_if_number_is_premium()     # 检查号码靓号状态
send_email()                     # 发送邮件通知

工具函数 ​

php
redirect()            # 页面重定向
current_url()         # 获取当前URL
isValidDomain()       # 域名格式验证
log_memory_usage()    # 内存使用记录

theme_manager.php ​

主题管理器

  • 主题加载和切换
  • 模板渲染引擎
  • 主题配置管理
  • 样式和脚本加载

auth.php ​

认证授权系统

  • 用户登录验证
  • 会话管理
  • 权限检查
  • 登录状态维护

hooks.php ​

钩子系统

  • 插件钩子机制
  • 事件触发器
  • 扩展点定义
  • 回调函数管理

🎨 主题系统 (themes/) ​

默认主题结构 ​

themes/default/
├── theme.json          # 主题配置文件
├── css/               # 样式文件目录
├── js/                # JavaScript文件
└── templates/         # 模板文件目录
    ├── header.php     # 页面头部模板
    ├── footer.php     # 页面底部模板
    ├── home.php       # 首页模板
    ├── apply.php      # 申请页面模板
    ├── query.php      # 查询页面模板
    └── result.php     # 结果页面模板

主题开发规范 ​

  • theme.json - 主题元信息配置
  • templates/ - 页面模板文件
  • css/ - 样式文件
  • js/ - JavaScript脚本

🔧 安装程序 (install/) ​

database.sql ​

数据库初始化脚本

  • 创建所有数据表
  • 插入初始配置数据
  • 支持多数据库类型
  • 包含索引优化
sql
-- 主要数据表
admin_users          # 管理员用户表
system_config        # 系统配置表
announcements        # 公告信息表
selectable_numbers   # 号码池表
icp_applications     # 备案申请表
plugins             # 插件信息表
operation_logs      # 操作日志表

安装向导文件 ​

  • step1.php - 环境检查
  • step2.php - 配置设置
  • step3.php - 完成安装
  • optimize.sql - 性能优化脚本

📦 插件系统 (plugins/) ​

插件结构 ​

plugins/example-plugin/
├── plugin.json        # 插件配置文件
├── main.php          # 插件主文件
├── install.php       # 安装脚本
├── uninstall.php     # 卸载脚本
└── assets/           # 插件资源文件

插件开发接口 ​

  • 钩子系统 - 在特定位置执行插件代码
  • 配置管理 - 插件配置存储和读取
  • 数据库操作 - 插件专用数据表管理
  • 资源加载 - 插件CSS/JS资源加载

📝 配置系统 (config/) ​

配置文件类型 ​

  • database.php - 数据库连接配置
  • app.php - 应用程序配置
  • mail.php - 邮件系统配置
  • cache.php - 缓存配置

配置加载机制 ​

  • 支持环境变量覆盖
  • 配置缓存机制
  • 类型安全检查
  • 默认值支持

🗄️ 数据存储 (data/) ​

存储内容 ​

  • sqlite.db - SQLite数据库文件
  • cache/ - 系统缓存文件
  • logs/ - 系统日志文件
  • backups/ - 数据备份文件

📈 性能优化 ​

缓存机制 ​

  • 配置缓存 - 系统配置信息缓存
  • 数据缓存 - 仪表盘统计数据缓存
  • 模板缓存 - 主题模板编译缓存

数据库优化 ​

  • 索引设计 - 合理的数据库索引
  • 查询优化 - 高效的SQL查询
  • 连接池 - 数据库连接复用

内存管理 ​

  • 垃圾回收 - 及时释放内存
  • 内存限制 - 合理的内存使用限制
  • 内存监控 - 内存使用情况记录

🔐 安全机制 ​

输入验证 ​

  • 数据过滤 - 用户输入数据清理
  • 格式验证 - 邮箱、域名格式验证
  • 长度限制 - 输入数据长度控制

访问控制 ​

  • 身份验证 - 管理员登录验证
  • 权限检查 - 操作权限验证
  • 会话安全 - 安全的会话管理

攻击防护 ​

  • CSRF防护 - 跨站请求伪造防护
  • XSS防护 - 跨站脚本攻击防护
  • SQL注入防护 - 使用预处理语句

🚀 扩展开发 ​

主题开发 ​

  1. 创建主题目录
  2. 编写theme.json配置
  3. 开发模板文件
  4. 添加样式和脚本

插件开发 ​

  1. 创建插件目录
  2. 编写plugin.json配置
  3. 实现插件功能
  4. 注册钩子函数

API扩展 ​

  1. 创建API文件
  2. 实现业务逻辑
  3. 返回JSON数据
  4. 添加认证机制

📚 相关文档 ​

基于 MIT 协议发布

版权所有 © 2025-2025 Yuan-ICP