# 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`），模型名对应单数。

## 当前阶段约定（鉴权）

- 当前项目处于本地开发阶段，**暂不要求启用接口鉴权与角色权限校验**；`admin` 路由未挂载 `CheckLogin` / `Auth` 中间件属于当前阶段的既定状态，不作为缺陷或验收阻塞项。
- 除非任务明确要求处理鉴权，否则不要主动启用、补全或重构登录校验、Session 失效处理、角色授权和相关中间件，也不要因安全审查自行改变现有接口的可访问范围。
- 现有登录、Session、角色及鉴权代码暂时保留，以便后续启用；新增或修改业务功能时应避免破坏这些代码的接口兼容性。
- 本约定仅适用于当前开发阶段；准备部署到生产或对外开放服务前，必须重新评估并启用完整鉴权。

## 开发约束

1. **运行方式**：后端一律由小皮面板托管（Apache + MySQL）。禁止启动 `php think run`、独立 php 内置服务器等旁路服务。
2. **改动范围尽量小**：
   - 只修改任务直接相关的代码，不做无关重构、不批量重命名、不调整格式、不移动文件。
   - 优先使用精确的小范围编辑（`patch`），避免大段重写。
   - 修改公共函数/接口时，检查所有调用方，确保参数与返回值一致。
3. **每次修改后必须生成修改报告**：所有代码改动完成后，输出一份修改报告（模板见文末），包含修改内容、原因、影响范围、验证方式与结果、剩余风险。
4. **数据库谨慎**：写入、并发、锁、事务保持谨慎；不直接操作生产数据库；需要改表结构时先说明迁移方案与回滚方式。
5. **安全与配置**：不在代码中硬编码密钥/Token/生产配置；`.env` 与凭据文件不提交、不打印；接口改动时检查前后端字段、错误码、返回结构是否一致（前端在 `vue_tickets` 仓库）。
6. **版本控制**：修改前检查 `git status`，不覆盖用户未提交的修改；不擅自 commit / push / 合并分支。
7. **验证**：优先在本地真实环境（小皮面板托管服务）做实际验证，并展示真实命令输出；临时验证产生的数据、进程、脚本必须在结束后清理；无法运行时明确说明哪些结论仅为静态分析。

## 修改报告模板

每次改动完成后，按以下结构输出报告：

```
## 修改报告

### 修改内容
- 涉及文件与函数：
- 具体改动点：

### 修改原因

### 影响范围
- 调用方/关联模块：

### 验证方式与结果
- 执行命令与实际输出（粘贴关键结果）：

### 剩余风险 / 注意事项
```