From 430ddbe9b62cfb8588b23fbd5df83ff1a5153007 Mon Sep 17 00:00:00 2001 From: hellcat Date: Sun, 11 Oct 2026 10:26:58 +0800 Subject: [PATCH] docs: establish AI maintenance guide and operational handoff --- .gitignore | 9 ++++- codex/output/maintenance/ARCHITECTURE.md | 47 ++++++++++++++++++++++ codex/output/maintenance/BUSINESS_RULES.md | 33 +++++++++++++++ codex/output/maintenance/DEPLOYMENT.md | 37 +++++++++++++++++ codex/output/maintenance/README.md | 25 ++++++++++++ codex/output/maintenance/STATUS.md | 29 +++++++++++++ 6 files changed, 179 insertions(+), 1 deletion(-) create mode 100644 codex/output/maintenance/ARCHITECTURE.md create mode 100644 codex/output/maintenance/BUSINESS_RULES.md create mode 100644 codex/output/maintenance/DEPLOYMENT.md create mode 100644 codex/output/maintenance/README.md create mode 100644 codex/output/maintenance/STATUS.md diff --git a/.gitignore b/.gitignore index 2a3e47c..dfb231b 100755 --- a/.gitignore +++ b/.gitignore @@ -40,7 +40,14 @@ compose.split.yaml # Separate frontend repository (commit it independently) /stellar/ # Local reports, backups, screenshots and private operational records -/codex/output/ +/codex/output/* +!/codex/output/maintenance/ +/codex/output/maintenance/* +!/codex/output/maintenance/README.md +!/codex/output/maintenance/ARCHITECTURE.md +!/codex/output/maintenance/BUSINESS_RULES.md +!/codex/output/maintenance/DEPLOYMENT.md +!/codex/output/maintenance/STATUS.md /deliverables/ # Local native-client build products /macos-client/build/ diff --git a/codex/output/maintenance/ARCHITECTURE.md b/codex/output/maintenance/ARCHITECTURE.md new file mode 100644 index 0000000..27ca6fd --- /dev/null +++ b/codex/output/maintenance/ARCHITECTURE.md @@ -0,0 +1,47 @@ +# 架构与配置 + +## 仓库与入口 + +- 当前 Laravel 后端：本地 /private/var/www/wwwroot/dpl。composer.json 要求 PHP ^8.2、Laravel ^12；仍使用 App\Http\Kernel、App\Console\Kernel 绑定方式，不能直接套用新项目默认结构。 +- Gitea 后端 origin：tom/dpl，远端 main；当前本地 master 跟踪 origin/main，变更分支默认用 codex/ 前缀。以 git branch -vv 为准。 +- stellar/ 是独立 Vue/Vite 前台仓库，不属于后端提交；修改前分别核对其远端与差异。 +- public/assets/admin 是 Git 子模块，仓库指定已构建后台资源版本；.gitmodules 指向 xboard-admin-dist。不要直接改压缩产物或擅自推送第三方仓库。 +- HTTP 入口 public/index.php → bootstrap/app.php → App\Http\Kernel。API 由 App\Providers\RouteServiceProvider 加载 app/Http/Routes/V1、V2 中的映射；不是只看 routes/web.php。 +- 后台 Blade：resources/views/admin.blade.php；自定义后台扩展的源文件 resources/js/admin/ 与运行副本 public/admin-custom/ 必须一致。 +- 当前后台入口配置 secure_path=dove，通过 routes/web.php 使用，不是硬编码固定路由。后台 API 也使用这个配置。后台路径不是身份认证的替代。 + +## 主要业务入口 + +| 范围 | 入口 | +| --- | --- | +| 登录与注册 | app/Services/Auth/、AuthService.php、对应 Passport 控制器 | +| 套餐、订单、支付 | PlanService.php、OrderService.php、PaymentService.php、对应控制器与模型 | +| 用户、节点、流量 | UserService.php、ServerService.php、NodeRegistry.php、TrafficResetService.php | +| 工单 | TicketService.php、工单控制器 | +| 邮件 | MailService.php → SendEmailJob → MailFlow/Dispatcher；渠道、额度、状态、来信、回复、日报均在 MailFlow/ | +| 定时运行 | app/Console/Kernel.php，命令实现 app/Console/Commands/ | +| 教程 | resources/tutorials/、resources/views/tutorials/、scripts/tutorials/ | + +## 配置来源 + +- .env 与 config/*.php 提供启动配置；config:cache 后修改 .env 需要重建缓存。不得打印整个配置或复制环境密钥进 Git。 +- admin_setting() 通过 App\Support\Setting 读取 v2_settings，并在 Redis 缓存 admin_settings。设置用原设置服务保存，避免直接改表后忘记缓存失效。 +- app_url、force_https 由 ApplyRuntimeSettings 在请求中应用；网站名称、主页与邮箱发信域名是不同用途的配置。 +- MailFlow\Settings 合并 config/mailflow.php 与后台 mail_flow，解密三个敏感字段；publicSettings 只返回“是否已配置”，不能要求 API 回传明文密钥。 +- mail_flow 中密钥采用 encrypted: 前缀，依赖当前环境 APP_KEY；不同环境不可直接复制密文当作可用凭据。已有用户密码是哈希，不能还原或写入文档。 +- 自动邮件档位是 v2_settings 中独立 automatic_mail_policy 记录。直接核验当前状态；代码无记录时兼容回退到一档，不能把当前三档配置误称为全新安装默认值。 +- MailTemplate 数据库自定义模板优先于文件模板。改文件后检查是否被同名数据库模板覆盖。 + +## 开发与验证 + +前台日常开发在 stellar/ 使用 npm run dev；根 package.json 没有 dev 命令。教程热更新可在 stellar/ 使用 npm run tutorials:watch。build 仅用于发布或明确构建验证。 + +邮件隔离回归（SQLite 内存库，测试阻止未模拟 HTTP）： + +```bash +vendor/bin/phpunit --bootstrap vendor/autoload.php tests/Feature/MailFlow +``` + +实际 JS 文件可用 node --check 验证语法，PHP 用 php -l。业务变更选择相关测试，不盲目运行会触及真实数据库或外部服务的命令。真实发信、支付、收件轮询及日报命令可能产生副作用，先确认本次授权和去重记录。 + +后台邮件页面为“系统配置 → 邮件设置”，包含基本设置、模板管理、Resend 与档位、收件与自动回复、用量汇报。扩展页签复用已有样式，不使用悬浮按钮或弹窗；修改后验证原生页签、键盘切换、异步加载、保存范围和密钥留空行为。 diff --git a/codex/output/maintenance/BUSINESS_RULES.md b/codex/output/maintenance/BUSINESS_RULES.md new file mode 100644 index 0000000..a89ee0a --- /dev/null +++ b/codex/output/maintenance/BUSINESS_RULES.md @@ -0,0 +1,33 @@ +# 业务约束 + +## 邮件渠道 + +- 验证码、登录链接、工单回应邮件通知优先 Resend；工单通知须有有效用户邮箱。额度耗尽或明确无法使用时走常规邮箱。 +- 其他通知、人工群发与来信自动回复使用常规邮箱；收件通过该邮箱 IMAP。不能把“Resend 支持收件 API”理解成已有 IMAP 邮箱。 +- 额度采用官方用量查询与本地预占；当前查询缓存 15 秒，并非每封都查。日/月限制有免费档保护，默认 100/3000，以实际配置及官方结果为准。 +- 发送超时属于结果未知，不直接跨渠道重复发。已提交是接口/SMTP 接受；Resend 已投递需投递事件或状态核对，不等于已读。普通 SMTP 不能假装具有投递回执。 +- 回调必须通过签名和事件去重。回调密钥可选是允许仅用状态核对，并非允许无签名回调。 +- 来信加密保存；普通来信不要求网站绑定邮箱。按发件地址北京时间每自然日只自动回复一次。同一来信不再次回复。过滤退信、自身、自动与列表邮件，防止循环；限制不能阻止攻击者换邮箱。 +- 日报北京时间每天 08:00，通过 master 当前默认会话；默认目的地及发送授权已经由用户确认，但任何后续目的地/授权变化仍需核对。真实发送和定时调度分别验收。 + +## 自动邮件三档 + +| 档位 | 提醒类自动邮件 | 实际套餐到期通知 | +| --- | --- | --- | +| 一档 | 原有逻辑 | 按现有用途与用户设置判断，不扩大旧行为 | +| 二档 | 关闭流量及到期前提醒等 | 仅允许启用二档之后新到期的用户，不补历史到期 | +| 三档 | 关闭 | 关闭 | + +管理员人工群发、验证与登录邮件、工单回应通知、来信自动回复始终不受档位影响。到期通知只有后台允许且用户未关闭提醒才发；任一方关闭均不发。改档要核对排队任务发送时的再次判断，恢复档位不补发已取消任务。 + +## 品牌与后台 + +邮件发件名称使用 app_name，正文 Logo 与名称并排、保持协调的小间距；页脚链接是网站正式主页，不能使用 deeplink-system.com 发信服务域名代替主页。收件箱头像由邮箱客户端决定，正文 Logo 不能强制控制它。 + +后台管理员权限必须在账号数据与实际登录中验证。路径变更需同时验证 HTML、资源加载和登录仪表盘；不能仅依靠 200 响应。密码、SMTP/IMAP/API 凭据不得写进维护指南、Git 提交或截图。 + +## 支付与授权边界 + +支付优先复用已有配置；涉及支付代码修改需按此前用户边界先确认具体改动。不得把邮件发布顺便混入支付变更，也不得未经授权执行真实付款。 + +常规已授权的修复、验证、文档与 Git 发布继续推进；涉及删除不可恢复数据、变更账号权限范围、新的外部数据传输目的地等敏感边界需要明确授权。已有授权不用重复询问。备份、脱敏与隔离数据不自动等于完成真实业务验收。 diff --git a/codex/output/maintenance/DEPLOYMENT.md b/codex/output/maintenance/DEPLOYMENT.md new file mode 100644 index 0000000..c5354b4 --- /dev/null +++ b/codex/output/maintenance/DEPLOYMENT.md @@ -0,0 +1,37 @@ +# 发布与恢复 + +## 目标与连接 + +本项目生产站点为 https://dp-link.net，后台 /dove；后端目录 /www/wwwroot/dp-link.net，服务器逻辑名 site-jp02。通过既定白色跳板连接；具体连接资料参见本机 /Users/hellcat/Documents/CoDocs/项目关系.md 与 vps连接资料.md，不把它们的内容提交到公开仓库。 + +本地 http://dpl.loc/dove 已配置到当前 Laravel public/。本机 Nginx 配置 /usr/local/etc/nginx/servers/dpl.loc.conf，PHP-FPM 使用现有 9000 端口。系统级服务重载可能需要 Mac 管理员授权；不持久保存系统密码。 + +## Git 发布顺序 + +1. 复核最新用户要求、目标服务器、仓库和改动范围；读取本地与线上 git status、当前 HEAD、远端。线上既有无关修改必须保留，不能直接 reset --hard、clean 或无范围 stash。 +2. 做相关测试和 diff 审查。高影响变更应接受独立审查；不要把未执行的审查记成已通过。确认无凭据、备份、私密配置和其他任务内容混入。 +3. 提交所需代码并推送项目 origin；记录明确提交版本。单独前台仓库或其他项目独立处理。 +4. 生产先记录当前提交，备份受影响文件/配置；数据库迁移前备份数据库并设计数据恢复方案。验证备份存在与权限，不能只写“有备份”。 +5. 按现场状态暂停必要任务，避免本地/线上重复处理同一个邮箱。服务器 git fetch 后更新到明确目标提交，优先 fast-forward，保留无关修改。 +6. 如涉及后台资源，初始化仓库指定子模块：git submodule update --init --checkout public/assets/admin。不要擅自升级至上游最新版本。此前缺失子模块曾造成后台 HTML 200 但脚本 404、整页空白。 +7. 依赖或数据库变化才执行对应 composer/迁移步骤；不得顺带升级 PHP 或全部系统包。处理 Laravel 配置/视图缓存，重载受影响常驻进程，恢复原调度。 +8. 核对线上 HEAD、相关文件、资源 HTTP 状态、页面显示、实际登录/保存、队列及必要的业务闭环。明确尚未到时或未验证的定时任务。 + +默认发布禁止打包覆盖，除非用户明确指定。服务器直接读取已有仓库优先；不能为了拉取 Git 自动复制本机用户名密码到服务器。凭据传输若被审批拒绝，报告真实原因，使用不涉及该凭据的既有合法读取方式。 + +## 当前运行依赖 + +生产使用 php8.4-fpm.service、dpl-horizon.service、Redis 与既有 /etc/cron.d/dpl-scheduler。Horizon 处理 send_email 队列；cron 执行 Laravel schedule:run。mail:poll-inbox 每分钟，mail:reconcile 每五分钟，邮件日报 08:00 加五分钟补偿扫描。时间和锁的实际实现以 Console\Kernel 和服务代码为准。 + +IMAP 扩展需同时在 CLI 与处理后台请求的 FPM 中可用；安装后不能只验证 CLI，常驻进程可能仍加载旧环境。 + +## 恢复与排错 + +- 代码：核对受影响范围和线上未提交修改，再更新到记录的旧提交并恢复缓存/进程。不要为了回滚本任务破坏其他修改。 +- 数据：代码回滚不等于数据库回滚。新增业务表与已发送记录通常应保留；删表或恢复整库会损失上线后的数据，需单独决策。 +- 账号与配置：使用受保护备份恢复指定字段，保持 APP_KEY。不得跨环境盲目复制加密密钥。 +- 后台空白：先查引用的 JS/CSS 和 manifest/子模块，再查浏览器报错；必须实际渲染和登录验收。 +- 配置保存失败：检查请求校验、旧配置合并、密钥留空保留、FPM 扩展加载与 Redis 缓存。 +- 邮件异常：先查看记录状态、幂等键、配额、收件游标和队列；不能通过重复发真实邮件来试错。 + +最近备份目录记录为 /root/codex-backups/dpl/，具体任务子目录与版本文件需现场核验；生产受保护备份不纳入 Git。历史 codex/output 中脚本仅作审计，不能不检查幂等和适用版本就重跑。 diff --git a/codex/output/maintenance/README.md b/codex/output/maintenance/README.md new file mode 100644 index 0000000..dff9054 --- /dev/null +++ b/codex/output/maintenance/README.md @@ -0,0 +1,25 @@ +# dpl：AI 维护入口 + +核对日期：2026-10-11。文档随代码版本维护；运行状态必须现场复核，不能把历史验收当成当前状态。 + +## 接手顺序 + +1. 阅读全局 AGENTS.md、当前用户要求和本目录说明。用户最新明确边界优先，不扩大本次授权。 +2. 确认所在仓库、分支、工作区差异与远端；分别识别用户既有修改、本次任务与其他聊天修改。不要覆盖、清理或混入其他任务。 +3. 按 [架构与配置](ARCHITECTURE.md) 沿实际调用链检查问题；按 [业务约束](BUSINESS_RULES.md) 判断影响。 +4. 修改后运行与影响范围相关的检查；后台界面必须浏览器验收，包括页面显示、保存、切换、权限。HTTP 200 不代表前端可用。 +5. 本地实现、提交、推送、部署、真实联调分别报告。发布按 [发布与恢复](DEPLOYMENT.md) 执行。 +6. 完成后同步本目录说明与 [验收状态](STATUS.md)。记录事实、证据、限制与下一步，不存密钥或用户原始邮件。 + +## 文档导航 + +| 文件 | 用途 | +| --- | --- | +| ARCHITECTURE.md | 服务入口、前后端边界、配置来源、开发与检查 | +| BUSINESS_RULES.md | 邮件、提醒、账号与支付等不可随意改变的约束 | +| DEPLOYMENT.md | Git 发布、备份、运行依赖、恢复及故障排查 | +| STATUS.md | 最近验证基线、已知限制与待验收项目 | + +这些说明用于辅助 AI 接手，不代表 AI 会在聊天结束后自动持续运行。应用定时任务在服务器执行，AI 维护任务需要会话或明确配置的自动化来启动。 + +所有维护输出放在项目 codex/output/。本目录五份维护文档允许纳入 Git；其他运行日志、截图、备份、临时脚本仍默认忽略。凭据与私密配置始终不提交。 diff --git a/codex/output/maintenance/STATUS.md b/codex/output/maintenance/STATUS.md new file mode 100644 index 0000000..121f116 --- /dev/null +++ b/codex/output/maintenance/STATUS.md @@ -0,0 +1,29 @@ +# 接手验收状态 + +文档核对日期：2026-10-11。以下为当前会话已验证的事实，不承诺服务器一直保持此状态。 + +## 最新代码基线 + +- 邮件页签实现版本 13117587c86aa49dafad3467b04d90469f4de2ab；本地提交推送、生产 Git fast-forward 完成。 +- 本地和线上后台实际登录成功；/dove 已验证渲染后台仪表盘。 +- 邮件设置已拆为五页签；无旧悬浮按钮与弹窗。基本设置保留 SMTP，新增 Resend 与档位、收件与自动回复、用量汇报。当前档位三档。 +- 两环境新增页签显示和切换已验收；Resend 页签保存原配置成功。每个扩展页签仅提交本页字段，密钥留空保留。 +- 最新邮件隔离回归：57 测试、333 断言通过。 + +## 已有真实联调与限制 + +Resend 发信、常规 SMTP、配额回退、投递事件回调、master 一次性汇报都曾实测。来信保存、每日一次自动回复曾在本地实测并收到回复。生产 IMAP 连接与增量检查已验证。 + +尚未在本轮复核的项目：生产新来信触发的完整自动回复链、首次/最新 08:00 定时汇报是否实际送达。这不是实现缺失，但不能按既有单次发送测试宣称定时运行已验收。若后续任务要求继续验收，先检查已处理记录避免重复回复/汇报。 + +## 接手注意 + +- 生产曾有与邮件无关的教程和文件模式修改，发布时保留了它们。下次仍必须重新核对，不能假定生产工作区干净。 +- 后台资源子模块版本目前锁定 ef5f43da335092cbff8fdf0ad7ff9b4d92d7d0d7；已修复生产未初始化导致的空白问题。 +- 后台邮件 UI 目前由扩展脚本接入已构建的第三方管理界面。升级后台子模块需回归挂载、页签、样式、保存、异步切换和原功能，不能认为 DOM 结构永久稳定。 +- 本地 PHP-FPM 已重载以加载已安装 IMAP；其他环境需独立确认。 +- 独立项目、支付等未列入本轮实现；不能把本轮完成扩展为其他聊天任务也完成。 + +## 每次维护更新本文件 + +记录任务、修改文件、测试、提交、是否推送/部署、真实验收结果、尚未完成项与敏感边界。禁止写密码、令牌、原始用户邮件或未经核实的完成结论。