wip

AGENTS.md

@@ -0,0 +1,54 @@
+# AGENTS.md — NewTicket 项目约束
+
+## 技术栈（后端）
+
+- **语言/运行时**：PHP 8.0.2 NTS（phpStudy 自带，位于 `D:\phpstudy_pro\Extensions\php\php8.0.2nts`，已加入 PATH）
+- **框架**：ThinkPHP 8（`topthink/framework ^8.0`），多应用模式（`auto_multi_app`），ORM 为 `topthink/think-orm ^3.0|^4.0`
+- **Web 服务器**：小皮面板（phpStudy）Apache 2.4.39，托管 `localhost:80`
+- **数据库**：小皮面板 MySQL 5.7.26（`127.0.0.1:3306`），库名 `tickets`，账号 `gds_tickets` / `gds_tickets`（见 `.env`）
+- **实时推送**：Workerman v4.2.1（`workerman/workerman ^4.2`；v5 需 PHP 8.1，当前环境装不了），独立进程 `worker/websocket.php`
+- **包管理**：Composer 2.5.8
+- **代码结构**：`app/`（PSR-4 自动加载）、`config/`、`route/`、`worker/`；前端为独立仓库 `vue_tickets`（Vue 3 + Vite，非本仓库）
+
+## 运行方式（重要）
+
+- **后端由小皮面板接管**：Apache 跑 80 端口、MySQL 跑 3306 端口。**不要启动 `php think run` 之类的旁路开发服务器**——端口、Session、环境不一致会掩盖问题，也会与面板托管的服务冲突。
+- 本地验证接口直接请求 `http://localhost/admin/<route>`（如 `http://localhost/admin/ticketsfind`）。
+- admin 应用路由前缀为 `/admin`，路由定义在 `app/admin/route/app.php`。
+- WebSocket 推送是独立进程，需单独启动：`php worker/websocket.php start`；`TicketNotifier::notify` 设计为静默失败，广播服务不可用不影响主流程。
+- 数据库表名为复数（`users`、`companys`、`company_operators`、`tickets`），模型名对应单数。
+
+## 开发约束
+
+1. **运行方式**：后端一律由小皮面板托管（Apache + MySQL）。禁止启动 `php think run`、独立 php 内置服务器等旁路服务。
+2. **改动范围尽量小**：
+   - 只修改任务直接相关的代码，不做无关重构、不批量重命名、不调整格式、不移动文件。
+   - 优先使用精确的小范围编辑（`patch`），避免大段重写。
+   - 修改公共函数/接口时，检查所有调用方，确保参数与返回值一致。
+3. **每次修改后必须生成修改报告**：所有代码改动完成后，输出一份修改报告（模板见文末），包含修改内容、原因、影响范围、验证方式与结果、剩余风险。
+4. **数据库谨慎**：写入、并发、锁、事务保持谨慎；不直接操作生产数据库；需要改表结构时先说明迁移方案与回滚方式。
+5. **安全与配置**：不在代码中硬编码密钥/Token/生产配置；`.env` 与凭据文件不提交、不打印；接口改动时检查前后端字段、错误码、返回结构是否一致（前端在 `vue_tickets` 仓库）。
+6. **版本控制**：修改前检查 `git status`，不覆盖用户未提交的修改；不擅自 commit / push / 合并分支。
+7. **验证**：优先在本地真实环境（小皮面板托管服务）做实际验证，并展示真实命令输出；临时验证产生的数据、进程、脚本必须在结束后清理；无法运行时明确说明哪些结论仅为静态分析。
+
+## 修改报告模板
+
+每次改动完成后，按以下结构输出报告：
+
+```
+## 修改报告
+
+### 修改内容
+- 涉及文件与函数：
+- 具体改动点：
+
+### 修改原因
+
+### 影响范围
+- 调用方/关联模块：
+
+### 验证方式与结果
+- 执行命令与实际输出（粘贴关键结果）：
+
+### 剩余风险 / 注意事项
+```