公考大师AI - 完整项目文档与文件说明

本文档详细记录了“公考大师AI”项目从一个基础工具演进至一个功能完善、注重隐私、具备商业运营潜力的多用户平台的最终架构。以下是每一个文件在最终系统中的详细职责与核心逻辑说明。

核心架构原则

混合存储模型：服务器不存储任何聊天内容，仅负责用户账户和对话“书签”（元数据）的管理；所有具体聊天记录通过IndexedDB安全地存储在用户本地浏览器，以最大化保护用户隐私并提升性能。
多用户账户体系：支持独立用户通过邮箱密码注册，并由管理员进行后台审核激活，为付费运营打下基础。
并发会话限制：通过服务器实时追踪，限制同一账户最多在2台设备上同时进行对话，防止账户滥用。
分层菜单交互：采用“左侧主菜单 + 底部设置菜单”的现代UI交互模式，提升用户体验。

文件结构与详细说明

根目录 (/)

文件名	类型	核心职责与逻辑说明
`index.php`	已修改	应用主入口：作为用户登录后看到的第一个页面，是整个单页应用（SPA）的HTML“外壳”。身份验证：在文件最顶部通过 `require_once` 引入 `auth_check.php`，确保只有合法用户才能访问。 UI骨架：定义了页面的三大块布局：顶部的`<header>`，中间的`<main>`内容区，和底部的`<footer>`输入区。菜单结构：包含了左侧滑出主菜单 (`#sidebar-menu`) 和底部弹出设置菜单 (`#settings-sheet`) 的完整HTML结构。动态数据显示：使用PHP从`$_SESSION`中读取并安全地显示经过特殊格式化的用户邮箱。
`login.php`	已修改	多用户登录页：提供“邮箱”和“密码”输入框，取代了旧的单一密码模式。用户引导：提供了指向注册页面 (`register.php`) 和未来“忘记密码”功能的链接。 “记住我”功能：包含一个复选框，允许用户选择是否启用长期登录。
`register.php`	新文件	新用户注册页：提供“邮箱”、“密码”和“确认密码”的表单，是用户加入系统的唯一入口。用户反馈：能够接收并显示来自后端处理脚本的成功或错误消息（例如“注册成功，等待审核”或“邮箱已被注册”）。
`handle_register.php`	新文件	注册逻辑处理器：负责处理来自`register.php`的POST请求。输入验证：检查邮箱格式、密码长度、两次密码是否一致。数据安全：使用`password_hash()`将用户密码加密为安全的哈希值。数据库操作：连接数据库，检查邮箱是否已存在，然后将新用户信息`INSERT`到`users`表，并将初始状态`status`设置为`'pending_review'`。
`check_login.php`	已修改	多用户登录验证器：处理来自`login.php`的登录请求。数据库查询：根据提交的邮箱查询`users`表，获取用户信息。密码比对：使用`password_verify()`安全地比对用户输入的密码和数据库中存储的哈希值。状态检查：在密码正确后，必须检查用户的`status`是否为`'active'`，否则将拒绝登录并给出相应提示。会话创建：验证成功后，创建用户会话(`$_SESSION`)，并存入`user_id`和`user_email`。 “记住我”处理：如果用户勾选了“记住我”，则生成并存储长期有效的认证令牌到`auth_tokens`表和浏览器Cookie中。
`logout.php`	已修改	统一登出脚本：负责处理用户的退出登录请求。会话清理：调用`auth_check.php`中的`logoutAndRedirect()`函数，该函数会销毁PHP会话、删除“记住我”的Cookie和数据库令牌。并发会话清理：在登出前，会清空`users`表中该用户的`active_sessions`字段，确保该用户在所有设备上都完全下线。
`auth_check.php`	新文件	统一身份验证中心：所有需要登录才能访问的页面的“守门员”，在文件开头被引入。多层验证逻辑：首先检查是否存在有效的PHP会话。如果会话存在，则进一步检查版本号，实现后台更新后强制全体用户下线。如果会话不存在，则检查是否存在“记住我”的Cookie。如果Cookie存在，则验证其令牌的有效性、时效性，并检查对应用户的状态是否为`'active'`。验证通过后，为用户重新创建会话。如果所有验证都失败，则强制跳转到登录页。
`db.php`	已修改	数据库定义与连接器：定义了整个应用最终的SQLite数据库结构。自动化建表：当数据库文件`auth.sqlite`不存在时，会自动创建它，并执行`CREATE TABLE IF NOT EXISTS`命令来建立`users`, `auth_tokens`, 和 `conversations`三张表。隐私保证：明确包含`DROP TABLE IF EXISTS messages;`语句，以确保服务器上绝不保留任何旧的、包含聊天内容的表。
`service-worker.js`	已修改	PWA核心：让应用具备渐进式网页应用的特性（如离线访问、快速加载）。缓存策略：采用“Stale-While-Revalidate”（后台更新同步）策略，兼顾了秒开速度和内容的自动更新。资源清单：包含了所有核心页面和资源（CSS, JS, 图片等）的缓存列表。
`generate_hash.php`	新文件	安全工具：一个独立的辅助脚本，用于将明文密码转换为安全的哈希值，供您在配置文件或数据库后台中使用。
`version.txt`	新文件	版本控制器：一个简单的文本文件，只包含版本号（如`1.0.0`）。当您想在更新网站后强制所有用户重新登录时，只需修改这个文件的内容即可。

管理后台目录 (`/admin/`)

文件名	类型	核心职责与逻辑说明
`index.php`	新文件	后台主页：以表格形式列出所有在`users`表中注册的用户及其状态。审核功能入口：为状态是`'pending_review'`的用户提供一个“审核通过”按钮。后台权限保护：在文件顶部检查管理员登录会话，防止未授权访问。
`login.php`	新文件	后台独立登录页：提供一个与前台完全隔离的、仅有密码输入的登录界面。
`check_login.php`	新文件	后台登录验证器：使用一个独立的、硬编码在文件中的管理员密码哈希来验证登录。
`approve_user.php`	新文件	审核操作处理器：接收来自主页“审核通过”按钮的请求，将数据库中对应用户的`status`字段更新为`'active'`，并为其设置一个默认的套餐到期日。
`logout.php`	新文件	后台安全退出：只销毁管理员的登录会话，不影响任何前台用户的状态。

API目录 (`/api/`)

文件名	类型	核心职责与逻辑说明
`analyze.php`	已修改	AI交互核心：与Gemini AI进行通信。元数据创建：如果是新对话，则在`conversations`表中创建一条“书签”记录，并返回其ID。隐私保护：严格遵守混合存储模型，绝不将聊天内容写入服务器数据库。
`get_history.php`	新文件	历史列表服务：从服务器数据库查询并返回当前用户所有对话的“书签”列表（仅含ID和标题），用于填充侧边栏。
`delete_history.php`	新文件	历史删除服务：处理删除单条或全部历史“书签”的请求。
`close_conversation.php`	新文件	对话归档服务：当用户点击“新对话”时，前端会调用此接口，将当前对话标记为“已结束”，使其正式成为历史记录。
`session_manager.php`	新文件	并发会话管理器：处理前端的“签到/签出”请求，通过读写`users`表的`active_sessions`字段，来实时控制同一账户的活跃设备数量，实现最多2台设备同时对话的限制。

资源目录 (`/assets/`)

文件名	类型	核心职责与逻辑说明
`css/style.css`	已修改	主应用样式：包含主界面、聊天气泡、顶部导航栏、左侧滑出主菜单、底部弹出设置菜单等所有UI元素的最终样式和动画。
`css/login.css`	新文件	登录/注册页样式：包含“荣光之路”主题的所有样式，与主应用样式完全分离。
`js/main.js`	已修改	前端总指挥：作为JS模块的入口，负责初始化本地数据库(`localDB.js`)、进行会话签到(调用`session_manager.php`)、加载历史列表、并协调其他所有模块开始工作。
`js/ui.js`	已修改	UI交互大脑：封装了所有与DOM相关的复杂交互逻辑，如主菜单和设置菜单的打开/关闭动画、根据数据动态渲染历史对话列表等。
`js/history.js`	已修改	历史记录协调者：负责处理与历史记录相关的所有前端逻辑，如调用API获取列表、发起删除请求，并联动`localDB.js`删除本地数据。
`js/api.js`	已修改	核心业务逻辑：负责处理发送问题给AI的`triggerAnalysis`函数。在获取到AI回复后，它会调用`localDB.js`将用户的提问和AI的回答都存入本地数据库。
`js/localDB.js`	新文件	前端本地数据库：封装了所有与IndexedDB的交互。是“混合存储模型”在前端的基石，负责所有聊天内容的本地增、删、改、查。