一、安装与数据库运维
1.1 首次安装机制：首次部署访问 install.php：
-检测 config.php 文件是否存在，若不存在，展示一次性安装表单，让用户同时填写部署级配置与首个超级管理员账号：
■ 数据库路径：程序自动随机生成文件名（如 data/sys_<随机串>.db，避免多系统共用目录时冲突），可改；
■ 文件上传路径：默认 /uploads，可改；
■ 日志存储路径：默认 /logs，可改；
■ 数据库备份保留天数：默认 3 天，可改；
■ 首个超级管理员账号：用户名 + 密码；
- 提交后按顺序执行：
⑴. 检测各个路径是否可写，不满足则直接中止并明确提示缺失项；
⑵. 检测通过后，把上述部署级配置值替换 config.template.php 中对应占位符，生成 config.php（占位符清单见 7.1）；
⑶. 自动调用 updatedb.php 初始化数据库（建表、建索引）；
⑷. 创建首个超级管理员账号；
⑸. 在 data/ 目录生成 install.lock 标记文件。
已存在 install.lock 时，install.php 自动跳转登录页，禁止重复初始化。
1.2 数据库结构升级：所有数据库结构变更统一由 updatedb.php 维护，业务代码中不做任何隐式结构变更。
- updatedb.php 自身幂等：每次访问都按自有逻辑执行全部升级步骤，已存在的表、字段、索引自动跳过，完整保留原有业务数据；
- 所有建表、加字段、建索引、改字段类型等结构变更，必须以增量步骤写入 updatedb.php；业务代码（model / controller / view）中严禁出现 CREATE TABLE / ALTER TABLE / CREATE INDEX 等 DDL 语句；
- 所有结构变更事务化执行，失败自动回滚；
- 执行升级前自动通过 VACUUM INTO 做一次一致性备份（复用 1.6 备份机制），升级失败可回滚到备份；
- 升级完成后自动清理临时缓存（如有）。
1.3 时区统一约定：所有时间存储、展示、日志均统一使用北京时间（Asia/Shanghai）。
1.4 索引优化约定：高频查询字段、外键关联字段统一建立索引，随升级脚本同步维护。
1.5 外键约束校验（数据库级外键）：启用数据库级外键约束——数据库连接统一执行 PRAGMA foreign_keys = ON；业务表之间以 FOREIGN KEY 子句声明外键关系（默认 ON DELETE RESTRICT，禁止级联删除被引用记录）；删除数据统一先弹模态确认，删除前自动校验引用关系，存在被引用记录时禁止删除并提示引用来源（如「该分类下存在 3 篇文章，无法删除」）；仅当无引用记录时才允许确认后删除，删除成功写入审计日志；被引用拦截的删除不执行、不写审计日志。
1.6 数据库自动备份：每日首次访问自动备份，采用 VACUUM INTO 命令生成一致性备份，加文件锁防并发损坏；备份文件与数据库同目录；默认保留最近 3 天并自动清理超期备份，保留天数可配置。
1.7 SQLite WAL 模式：数据库连接统一开启 PRAGMA journal_mode = WAL，降低多请求并发读写时的锁冲突与"database is locked"报错概率。
二、账号与权限安全
2.1 密码强度规则：大小写字母、数字、特殊字符至少包含 3 种，长度 ≥ 8 位。
2.2 密码加密存储：统一使用 password_hash 进行单向加密存储。
2.3 登录失败提示：统一返回「账号或密码错误」模糊提示，防止账号枚举。
2.4 登录错误锁定：连续密码错误达到阈值自动锁定账号，锁定时长可配置（默认阈值 3 次、时长 24 小时）；
2.5 单设备登录限制：同一账号仅允许单设备同时登录，新设备登录后其他设备自动退出；被挤下线的设备在登录页显示提示「该账号已在其他设备登录，当前设备已被退出登录」（普通会话超时不显示该提示）。
2.6 密码修改校验：分两种场景——本人修改密码需验证旧密码并两次输入确认；管理员在编辑弹窗中替他人修改密码时免验旧密码，两次输入一致即可，密码字段不回显，留空表示不修改。
2.7 用户名只读限制：用户名创建后不可修改，编辑页置灰显示。
2.8 管理员自保限制：超级管理员不能删除自身；不能删除或降级最后一个超级管理员（防锁死）；不能锁定自身；不能锁定最后一个可用的超级管理员。
2.9 会话超时机制：登录会话闲置超时后自动销毁并跳转至登录页，超时时长可配置（默认 30 分钟）。
2.10 接口权限校验：所有后端接口服务端统一做权限校验，防止越权访问。
2.11 CSRF 防护：表单提交与关键操作加入 CSRF 令牌校验，防范跨站请求伪造攻击。
2.12 注入与 XSS 防护：全局输入过滤输出转义，数据库使用预处理语句。
2.13 响应头安全加固：统一设置安全响应头（X-Content-Type-Options、X-Frame-Options、Referrer-Policy、Content-Security-Policy、X-XSS-Protection），作为 Web 服务器配置的替代或补充；CSP 中 img-src 需包含 data: 与 blob:，保证图片上传预览等前端功能不被拦截。
2.14 Session Cookie 安全配置：启用 HttpOnly、Secure、SameSite=Strict 属性（HTTP 协议下 Secure 自动降级，保证本地 http 调试可用）。
2.15 RBAC 权限控制（可选启用，启用后为必选要求）：基于角色权限模型，支持角色创建、菜单与操作权限分配，动态渲染菜单与控制操作权限。
三、全局前端布局规范
3.1 响应式适配：所有页面完整适配 PC 端与移动端显示。
3.2 后台主框架：左右分栏布局。
- 左侧导航：可折叠；PC 端默认显示、折叠状态跨页记忆；移动端默认收起，点击菜单展开，点击非菜单区域自动收起。
- 左上角：系统名称 + 版本号显示在同一行（版本号紧随系统名称之后），版本信息统一读取 constants.php（APP_VERSION）；名称下方小字号展示品牌标语（slogan，允许为空）。
- 左下角：展示「当前账户：用户名」「角色：角色名」，并提供带图标的「修改密码」「退出登录」入口。
- 右上角：展示当前登录用户名，下拉菜单提供不同主题风格切换，选择保存于本地浏览器。
四、登录页专项规范
4.1 验证码要求（中文算术题）：登录验证码为中文算术题，算式以中文符号呈现（如 2乘3=？），提高机器破解难度：
- 加法/减法：两个数均为 1-30，减法结果不为负数；
- 乘法/除法：两个数均为个位数（1-9），除法结果必须整除、无小数；
- 文字：数字与中文运算符统一从 8 色柔和色池随机取色（暖白/天蓝/薄荷绿/柔黄/蜜橙/淡紫/青蓝/藕粉），相邻字符避免同色（最多重取 3 次），防止机器通过颜色找规律；
- 字号大小错落（数字 17-20px、中文运算符 15-17px），轻微旋转（±12°），配 2 条暗部斜线 + 稀疏噪点干扰，不影响阅读；
4.2 验证码失效机制：支持点击刷新，验证后立即失效。
4.3 记住登录状态：采用 selector/validator 令牌机制实现长效登录，本地不存储密码。
4.4 版权标识：底部居中显示 ©年份 系统名称 备案号，备案号可在系统配置表中配置。
4.5 被踢提示：同一账号在其他设备登录导致当前设备被退出时，登录页顶部显示黄色提示「该账号已在其他设备登录，当前设备已被退出登录」（见 2.5）。
五、列表与分页规范
5.1 单页 CRUD 操作：同业务增删改查在同一页面完成，全程无刷新。
5.2 列自定义配置：各业务列表的列支持列显隐控制，配置保存在本地浏览器，支持一键重置；PC 端与移动端默认显示列不同（移动端默认仅显示精简列，用户可通过列设置手动展开更多列）。
5.3 操作列适配：PC 端默认显示操作列，移动端默认隐藏（移动端可通过列设置展开）；操作按钮文字前统一加内联 SVG 图标（不依赖外部 CDN）。
5.4 行详情交互：点击列表行查看详情，有权限可直接跳转编辑；从详情弹窗切换到编辑时，详情弹窗自动关闭，无需手动多关一次。
5.5 分页样式规范：
- PC 端：左侧显示「第 A/B 页（共 C 条）」+ 每页条数下拉（选择后保存在本机浏览器，下次按保存值显示）；右侧提供首页、上一页、下一页、末页按钮，以及跳页下拉（文案为「跳转到」+ 下拉列表「第1页、第2页…」）；
- 移动端：左侧显示「第 A/B 页（共 C 条）」，右侧仅保留上一页、下一页按钮。
5.6 默认排序：所有列表统一按主键 ID 倒序排列。
5.7 搜索区布局：搜索输入框设置 enterkeyhint="search"。
六、表单与交互体验
6.1 输入框增强：所有输入框支持双击清空内容；所有搜索输入框支持回车触发搜索；移动端搜索输入框键盘显示「搜索」按钮（enterkeyhint="search"），不显示「下一步」按钮。
6.2 表单双重校验：前端实时校验 + 后端二次合法性校验。
6.3 加载与防重复提交：异步操作显示加载状态，禁用按钮防重复提交。
6.4 全局消息提示：无需用户确认的提示（成功、失败、状态反馈）用页面中央的 Toast，几秒后自动消失；需要用户确认的破坏性操作（删除、重置等）用页面中央的模态确认窗口；需要输入内容用模态输入窗口。全项目禁用原生 alert/confirm/prompt，所有提示居中显示。
6.5 密码字段回显约定：编辑弹窗中的密码字段一律不回显；留空表示不修改密码，填写才修改（免验旧密码，见 2.6）。
七、系统配置与日志
7.1 配置文件分层：系统配置分三层，各司其职，覆盖更新代码时互不影响；新增配置项必须先判断归属，不得随意塞入 config.php：
- constants.php（随代码分发，部署时用户无需修改，随版本覆盖）：存放所有默认的、不需用户手工修改的系统配置，包括 APP_VERSION（系统版本号）、RELEASE_DATE（发布日期）及其他系统内置默认参数。
- config.template.php（随代码分发，部署级默认模板）：内含占位符，由 install.php 安装时替换为用户填写值（安装流程见 1.1），包括 __DB_PATH__（数据库文件路径，安装时随机生成）、__UPLOAD_DIR__（文件上传路径，默认 /uploads）、__LOG_DIR__（日志存储路径，默认 /logs）、__BACKUP_KEEP_DAYS__（数据库备份保留天数，默认 3 天）。
- config.php（install.php 替换模板占位符生成）：用户实际部署配置；覆盖更新代码时此文件保留、不被覆盖。
部署级路径类配置（DB_PATH、UPLOAD_DIR、LOG_DIR、BACKUP_KEEP_DAYS）均在 config.php 中，不存放到系统配置表；业务运行参数（系统名称、备案号、安全阈值等）存于数据库系统配置表（见 7.2）。
7.2 系统配置表：核心运行参数统一管理（部署级路径类配置除外），提供单一编辑页面，无需新增删除功能：
- 系统名称：默认为空
- 品牌标语（slogan）：默认为空
- 网站备案号：默认为空
- 密码错误次数阈值：默认 3 次
- 账号锁定时长：默认 24 小时
- 会话超时时长：默认 30 分钟
其中文件上传路径、日志存储路径、备份文件保留天数（见 7.1）位于 config.php、不在系统配置表中，但系统配置页面以只读方式展示其当前值，便于运维确认；如需修改须直接编辑 config.php，页面上不可改。
7.3 异常处理与日志（可选启用，启用后为必选要求）：全局异常捕获机制，异常日志按天生成文件存储（error_YYYY-MM-DD.log，不入库）；日志路径在 config.php 中配置（见 7.1）。
7.4 操作审计日志（可选启用，启用后为必选要求）：记录账号登录、数据增删改、权限变更等关键操作，包含操作人、操作时间、操作内容、客户端IP信息，支持操作追溯与安全审计；审计日志仅提供列表查看与搜索功能，无需新增、删除功能。
八、架构与发布规范
8.1 MVC 架构：采用手写 MVC 架构（零第三方依赖），统一入口 index.php?r=xxx；页面路由与 API 路由统一在 config/routes.php 登记（API 一并并入路由，形如 index.php?r=api/模块/动作）；新增业务模块时在路由表登记页面与 API 路由，并在 app/controllers、app/models、app/views 增加对应文件即可，不影响既有模块。
8.2 部署环境：Web 服务器为 IIS（PHP FastCGI，零伪静态配置）或任何支持 PHP 的服务器（Apache / Nginx / php -S）；支持部署在网站根目录或任意子目录（如 /admin），BASE_URL 自动检测；反向代理等特殊场景可用 config.php 中 BASE_URL_OVERRIDE 手动覆盖（见 7.1，覆盖更新时保留）。
8.3 运行时目录保护：data（数据库与备份文件）、logs、uploads 目录内均放置 web.config（IIS）禁止 Web 直接访问，数据库、备份、日志文件不可被下载；部署到非 IIS 服务器时需在服务器层配置等价拒绝规则。
8.4 版本号约定：采用两位版本号（如 v1.0、v2.5）——重大更新改前面版本号，小更新改后面版本号，同一天所有更新共用一个版本；版本号定义于 constants.php 的 APP_VERSION（见 7.1）；页面版本显示、打包文件名、文档文件名必须与 APP_VERSION 一致（同步更新，不得遗漏）。updatedb.php 自身幂等（见 1.2），不依赖版本号判断是否需要升级。
8.5 打包发布与更新流程：
- 发布包为 zip 压缩包，文件名带版本号（如 admin_system_php81_sqlite_v2.5.zip）；
- 打包时必须排除：data/ 目录（数据库与备份文件；仅保留其中的 web.config 防 Web 直接访问）、logs/、uploads/ 等运行时目录、config.php（用户实际配置）、所有 *.db / *.db-wal / *.db-shm 数据库文件；
- 发布包中必须包含：config.template.php、constants.php、install.php、updatedb.php、全部业务代码；
- 首次部署：上传代码后运行 install.php（内部自动调用 updatedb.php 完成数据库初始化），按引导完成环境检测、配置生成与超管创建；
- 日常更新：直接上传代码覆盖即可——config.php、数据库文件、上传文件、日志均保留不受影响；若本次发布包含数据库结构变更，需手工单独运行一次 updatedb.php（幂等，无变更时访问也无副作用）；无结构变更则无需运行；
- 历史发布包保留，不覆盖旧文件。
8.6 测试环境隔离：项目源码目录始终保持干净，只存放代码与源文件。本地测试时，先把项目代码完整复制到一个临时目录，在临时目录中做测试。
评论（0）
暂无评论。