DOO 项目开发文档与系统架构

DOO（Simple Server）是一个轻量级 PHP RESTful API 服务框架 + uni-app (Vue 3) 跨端内容社交应用。本文为项目开发文档与系统架构说明。  ## 一、项目概述 DOO 采用**中间件链 + 服务-仓库分层架构**，内置 80+ API、频率限制、RBAC 权限管理、考勤/加班/薪资计算、公告与文章系统及自动化爬虫等完整功能模块。配套 uni-app（Vue 3）跨端 App 和原生双版本管理后台。 - 后端：PHP 7.2+ / MySQL 5.7+ / PDO 全量预处理 - 前端：uni-app (Vue 3) + Vite + Vuex，Capacitor 6 原生封装 - 管理后台：admin-vue（Vue 3 SPA，主力版）+ admin-web（原生 HTML/JS/CSS） - 线上部署：Ubuntu 22.04 + Nginx + PHP-FPM，App 全量包发布 ## 二、系统架构  ``` 请求（HTTP Request） │ ▼ ┌──────────────────┐ │ CORS 中间件 │ 跨域白名单 + OPTIONS 预检 └────────┬─────────┘ ▼ ┌──────────────────┐ │ 日志中间件 │ 请求/响应 JSON 日志 + 毫秒计时 └────────┬─────────┘ ▼ ┌──────────────────┐ │ 错误中间件 │ try/catch 全局异常捕获 └────────┬─────────┘ ▼ ┌──────────────────┐ │ 路由层 │ URI 解析 → 分发到处理器 └────────┬─────────┘ ▼ ┌──────────────────┐ │ 服务层 │ 业务逻辑、权限验证、流程编排 └────────┬─────────┘ ▼ ┌──────────────────┐ │ 仓库层 │ SQL 构建、PDO 执行 └────────┬─────────┘ ▼ MySQL 数据库 ``` ### 统一路由入口（v2.2.0） 所有 `/api/*` 请求通过 `.htaccess` rewrite 进入 `index.php`（86+ 路由）： ``` /api/login.php ──→ index.php?__route=login.php /api/auth/login ──→ index.php?__route=auth/login /api/content.php?id=1 ──→ index.php?__route=content.php&id=1 ``` 路由分发策略： | 路由类型 | 示例 | 处理方式 | |----------|------|----------| | RESTful 核心路由 | auth/login, users/1, content | 直接调用 Service 层（无重复 DB 连接） | | 传统文件路由 | login.php, feedback.php 等 | require 原文件（中间件已就绪） | | RESTful + query fallback | /users.php?id=1 | $_GET['id'] 自动兼容 | ## 三、后端目录结构 ``` server/ ├── api/ # API 端点（90+ 接口文件） │ ├── index.php # 集中式路由入口 │ ├── login.php # 用户登录（含频率限制） │ ├── register.php # 用户注册（邮箱验证 + 频率限制） │ ├── content.php # 内容 CRUD │ ├── announcements.php # 公告列表 │ ├── get_articles.php # 文章列表（支持分类筛选） │ ├── upload_article.php # 发布文章 │ ├── overtime.php # 加班记录 + 薪资计算（五险一金 + 个税） │ ├── admin_*.php # 管理后台模块（用户/内容/轮播/统计/日志/文章/反馈/加班/RBAC） │ ├── crawl_hotsearch.php # 通用热榜抓取 → 自动发布 │ ├── crawl_images.php # 自动抓图 → 发布 │ ├── ai_proxy.php # AI 代理转发 │ ├── system_monitor.php # 系统监控（需管理员） │ └── ... ├── config/ # Config.php（.env）+ Database.php（PDO）+ RateLimiter.php ├── middleware/ # CORS / 日志 / 错误 / 认证 — 链式中间件 ├── services/ # UserService / ContentService — 业务逻辑 ├── repositories/ # UserRepository / ContentRepository — 数据访问 ├── sql/ # 数据库结构脚本 ├── uploads/ # 上传文件目录 ├── downloads/ # APK 下载目录 └── mail.php # 邮件发送（PHPMailer） ``` ## 四、前端（uni-app）  - **页面**：21 个页面，4 个 Tab（首页/工时/消息/我），覆盖启动、认证、内容、公告、文章、个人中心、管理后台 - **目录**：pages/（splash/auth/tabbar/content/info/user/article/admin 等）、components/、store/（Vuex）、utils/ - **跨平台**：iOS / Android 原生 App、H5 网页版、微信小程序，一套代码四端编译 - **管理后台入口**：APP 内 system-settings → goAdmin 进入原生后台（pages/admin/，13 页），无需 webview ## 五、数据库设计（27 张表）  ### 核心业务表 **users — 用户**：id PK、username UNIQUE、password（bcrypt 哈希）、nickname、email、avatar、role（user/admin）、level/experience/points（等级积分）、followers、following、likes、时间戳 **content — 内容**：id PK、user_id FK、title、content、image_url/video_url、tags、category、type、status（draft/published/deleted）、likes/comments、recommended **articles — 文章**：id PK、title、content、excerpt、author、tags、category、status、cover、top、user_id、created_at ### 社交与内容辅助表 | 表名 | 说明 | 关键字段 | |------|------|----------| | follows | 关注关系 | follower_id → following_id (UNIQUE) | | collections | 收藏 | user_id + content_id (UNIQUE) | | carousels | 轮播图 | title, image_url, sort_order, is_active | | announcements | 公告 | title, content, is_active | | feedback / feedback_replies | 用户反馈 + 回复 | user_id, type, content, status(0未读/1已读/2已处理) | | images / files | 图片与文件管理 | 上传路径、类型、大小 | ### 考勤/薪资表 | 表名 | 说明 | |------|------| | attendance | 考勤打卡 (user_id, date, check_in, check_out, duration) | | overtime | 加班记录 (user_id, date, hours, rate, multiplier, salary, type: overtime/comp) | | overtime_config | 加班费率 (normal_rate, weekend_rate, holiday_rate) | | salary_config | 薪资配置 (底薪/奖金/绩效/五险一金费率/加班时薪，按月) | ### RBAC 权限表（admin_permissions.php 自动创建） roles（super_admin/admin/editor/user）、permissions（12 项）、role_permissions、user_roles ### 系统与辅助表 logs（操作日志）、rate_limits（频率限制）、user_behaviors（行为记录）、email_verifications（邮箱验证）、password_resets（密码重置）、splash_config（开屏页）、app_versions（版本管理）、env_monitor（环境监控） ## 六、核心 API 模块 | 模块 | 端点示例 | 说明 | |------|---------|------| | 认证 | login / register / forgot_password / change_password / delete_account | 频率限制 + Session/Token 双机制 | | 用户 | get_users / update_user / user_level | 用户信息与等级积分 | | 内容 | content.php (CRUD) / feed.php / get_carousels.php | 内容 + 视频流 + 轮播 | | 收藏 | add_collection / get_collections | 收藏管理 | | 文章 | get_articles / upload_article / delete_article / simple_articles | 文章系统 | | 公告 | announcements / get_announcement_detail | 公告列表与详情 | | 考勤薪资 | overtime.php（加班/调休 + 薪资总览） | 五险一金个税计算 | | 反馈 | feedback / feedback_answer / get_my_feedback | 反馈闭环 | | 文件 | upload / upload_image / files / files_preview / files_upload / download_proxy | 上传/预览/APK 代理 | | 管理 | admin_users / admin_content / admin_articles / admin_feedback / admin_overtime / admin_permissions 等 15 个 | 均需管理员 Session/Token | | 爬虫 | crawl_hotsearch / crawl_images / crawl_douyin_hotsearch / crawl_toutiao_hotsearch | 自动抓取发布 | | 系统 | system_monitor / deploy / check_update / get_versions / upload_version / wgt_manager | 监控 + 版本管理 | | AI | ai_proxy | 转发到本地 LLM 服务 | 所有接口统一响应格式： ```json { "code": 200, "message": "操作成功", "data": { ... } } ``` ## 七、安全机制 | 措施 | 实现位置 | |------|----------| | bcrypt 密码加密 | login.php, register.php, UserService | | 全量 PDO 预处理 | 所有 SQL 查询均使用 prepare + bind | | 频率限制 | RateLimiter — login(5/5min), register(3/10min) | | 管理员 Session 验证 | 所有 admin_*.php 统一检查会话/Token | | 文件上传白名单 | 类型 + 大小限制 | | 路径穿越防护 | basename() 防护 (download_proxy.php) | | CORS 白名单 | cors_headers.php + Config.php .env 配置 | | Token 认证 | 登录成功返回随机 hex token | | 错误信息脱敏 | ErrorMiddleware 仅 api.debug=true 时暴露堆栈 | ## 八、部署指南  ### 环境要求 - PHP 7.2+ / MySQL 5.7+ / MariaDB 10.2+ - Apache 2.4+ (mod_rewrite) 或 Nginx 1.16+ - PHP 扩展：PDO_MySQL, fileinfo, gd, curl, openssl ### 安装步骤 ```bash # 1. 克隆 git clone git@github.com:jackchenjiufu/Simple.git cd Simple # 2. 安装依赖 composer install # 3. 配置 .env（数据库信息） cp server/config/.env.example server/config/.env # 4. 导入数据库 mysql -u root -p < server/sql/doo-app.sql # 5. 目录权限 chmod 755 server/uploads/ server/downloads/ server/logs/ chmod 600 server/config/.env # 6. 初始化 curl http://localhost/server/api/init_database.php curl http://localhost/server/api/reset_admin.php # 管理员密码 → admin123 ``` ### 访问地址 - 用户端：http://your-domain.com/ - 管理后台（Vue 3 SPA）：http://your-domain.com/admin-vue-dist/ - 管理后台（原生版）：http://your-domain.com/admin-web/ - 管理入口（线上）：http://139.196.185.197:7070/admin - API 接口：http://your-domain.com/server/api/ ## 九、版本历程 | 版本 | 日期 | 关键内容 | |------|------|----------| | v2.4.0 | 2026-07-18 | 反馈系统闭环、轮播上传、admin-vue 重构（Vue 3 SPA）、Token 鉴权 | | v2.3.0 | 2026-06-21 | api-bridge.php 修复 401、反馈管理完整可用 | | v2.2.0 | 2026-06-20 | 统一路由系统（.htaccess → index.php，86+ 路由） | | v2.1.0 | 2026-06-20 | 分页总数修复、错误脱敏、CORS 全覆盖 | | v2.0.0 | 2026-06-20 | 更名 Simple Server，考勤薪资/RBAC/爬虫 | ## 十、已废弃功能说明 以下功能曾在上线早期版本中存在，当前版本已移除或不再维护： | 功能 | 现状 | |------|------| | 私信/聊天（messages 表 + send_message/get_chat_history API） | 已废弃，API 与数据表均已移除；「消息」Tab 现展示公告 | | 关注 API（follow/check_follow.php） | 已废弃，API 文件移除；follows 表保留 | | 推荐引擎（recommend.php + 推荐/A-B 测试 7 张表） | 已废弃，API 与表均已移除；首页降级为文章/内容列表 | | 用户画像/行为推荐（user_profile.php 推荐接口） | 已废弃，前端有默认列表回退 | | 行为上报（user_behavior.php） | 已废弃 | | WebSocket 实时推送（Node.js 1884/1885） | 已废弃，服务未部署 | | 在线人数统计（online_count.php） | 已废弃 | --- **项目地址**: https://github.com/jackchenjiufu/Simple