onenav/AGENTS.md

AGENTS

• 全程使用中文输出，包括分析、进度说明、变更说明、提交信息建议；不要默认切回英文。

入口与分发

• 真实入口是根目录 index.php，不要从 README 猜流程。
• index.php 启动顺序固定：先检查 data/config.php，不存在就进入 controller/init.php；再检查 data/onenav.db3，不存在时从 db/onenav.simple.db3 复制；然后 require ./data/config.php；最后按 ?c= 分发到 controller/*.php。
• 未传 c 时进入 controller/index.php；?c=api、?c=admin、?c=login、?c=mobile 等都直接映射到 controller/<name>.php。
• index.php 会拒绝包含 ./ 的控制器参数；改路由时不要破坏这层基于文件名的动态分发。
• .htaccess 只做两条重要伪静态：/click/<id> -> index.php?c=click&id=<id>，/api/<method> -> index.php?c=api&method=<method>。

关键目录

• controller/ 放页面/入口控制器，真正的 API 业务主要在 class/Api.php，不要只改 controller/api.php 的参数转发层。
• functions/helper.php 放登录态、主题枚举、移动端跳转等共享函数；前台首页和后台都依赖它。
• 后台管理的大部分前端交互、表格渲染和 API 调用集中在 templates/admin/static/embed.js；改后台管理行为时要同时检查这个文件。
• 内置主题在 templates/，用户自定义主题走 data/templates/；代码里默认先找内置目录，再回退到 data/templates/。
• db/onenav.simple.db3 是初始化种子库，data/onenav.db3 是运行中的真实数据。

运行与状态文件

• data/config.php 和 data/onenav.db3 是本地实例状态文件，且被 .gitignore 忽略；除非用户明确要求，不要覆盖、删除、重建这两个文件。
• 安装流程依赖 config.simple.php 模板生成 data/config.php；涉及初始化逻辑时，同时检查 controller/init.php 和 config.simple.php。
• controller/init.php 的可执行约束比 README 更可信：初始化会检查 pdo_sqlite、openssl、zlib、curl，并拒绝二级目录安装。

前台与主题流程

• controller/index.php 会先查 on_options.s_site 和分类/链接，再决定主题；不要只看模板目录名判断首页行为。
• 未配置主题时默认 default2；已配置时按 UA 在 s_themes 中区分 pc_theme 和 mobile_theme。
• ?theme= 只允许切到 get_all_themes() 返回的主题；这个函数会排除 admin、mobile、universal。
• 主题配置文件兼容两套命名：优先 config.json，其次 info.json；内置主题和 data/templates/ 都要一起兼容。

认证与 API 约束

• 登录态不是 PHP session，而是 key cookie；functions/helper.php::is_login() 会把它和 USER + ENCRYPTED_PASSWORD + onenav + User-Agent 的 MD5 比较。
• class/Api.php::auth() 允许两种 API 鉴权：token=md5(USER + SecretKey) 或请求头 X-Token；没传 token 时会退回 cookie 登录态。
• 后台和移动后台都依赖同一套 cookie 登录判断；改鉴权时要一起看 controller/admin.php、controller/mobile.php、controller/login.php。

验证方式

• 仓库里没有可验证的 composer.json、package.json、CI workflow、lint/test 配置；不要臆造 composer test、npm run build 之类命令。
• 对 PHP 改动，最小可执行验证是对改过的文件运行 php -l <file>。
• 对路由或接口改动，优先按真实入口验证：/index.php?c=... 或重写后的 /api/...、/click/...。