# YPB2C AI 编程规则 本文件是仓库唯一的项目强制规则源；本文明确引用的专项规则文档视为本文件组成部分。 ## 规则文档索引与优先级 | 文档 | 定位 | 读取时机 | |---|---|---| | `AGENTS.md` | 项目强制规则与项目级覆盖 | 每次任务 | | `docs/PHP_RULES.md` | 通用 PHP 编码、PHPDoc、安全、依赖和验证规则 | 修改 PHP 时 | | `docs/DB.md` | 数据库设计、命名、索引、Comment 和 DDL 规则 | 涉及数据库结构或数据修复时 | | `docs/PROJECT_ARCHITECTURE.md` | 项目架构事实，不定义规则 | 定位入口、模块、租户和调用链时 | - 规则冲突优先级：用户最新明确要求 > `AGENTS.md` 项目规则 > 当前任务适用的专项规则。 - 项目事实以当前工作区代码为准；代码与 `docs/PROJECT_ARCHITECTURE.md` 不一致时，按已确认的代码事实更新架构文档。 ## 1. 强制基线与配置保密 - PHP 最低兼容版本为 PHP 7.3；详细编码边界见第 5 节。 - 项目是无命名空间的自研 PHP MVC，不引入 Laravel、ThinkPHP、Symfony 等应用框架。 - 优先稳定、最小修改和历史接口兼容，不顺手重构无关代码，不全仓统一旧代码风格。 - 新增或修改的文本文件必须使用 UTF-8 无 BOM 编码，换行统一为 CRLF；不为统一格式批量改写无关文件。 - 当前目录是 SVN 工作副本，不使用 Git 命令，不修改 `.svn/`。可用时使用只读 SVN 状态和差异命令。 - 禁止把数据库口令、Token、密钥、Cookie、完整请求数据、个人信息或生产日志写入文档、回复、测试数据和新代码。 ### 配置文件强制保密边界 - 禁止打开、读取、搜索、解析、执行、打印或通过工具结果暴露任何配置文件。受保护范围包括 `mvc/common.config.php`、`mvc/dwz.config.php`、各应用配置文件，以及其他运行、部署、依赖或环境配置文件。 - 禁止披露配置的键名、值、层级、结构、映射、连接别名、路由或自动加载规则、地址、路径、开关及其推断结论。 - 配置信息不得进入文档、回复、注释、测试数据、日志、截图、补丁说明或新代码；脱敏后也不得复述结构或映射。 - 不得通过 `include`、`require`、PHP 执行、语法检查、依赖管理命令或其他间接方式读取配置；验证命令必须排除配置文件。 - 任务依赖配置知识时，停止该部分工作，请用户提供不含配置内容的业务结论或明确操作指令。 以上保密边界适用于后续全部章节，不再重复展开。 ## 2. 每次任务的工作流 先按“规则文档索引与优先级”读取当前任务适用的文档。需要历史背景时，检索 `docs/需求变更历史.md` 中与目标模块相关的最近记录；随后定位目标入口、CLI/任务脚本或实际调用方及其直接调用链。纯文档任务跳过代码调用链。 修改前确认： - 请求从哪个入口、CLI/任务脚本或调用方进入，对应哪个 Action、方法、模板或接口返回格式。 - 数据来自哪个业务方法和 Base 调用链，是否已有公共能力可以复用。 - 改动属于共享系统还是租户覆盖，是否影响权限、订单、支付、退款、上传、外部接口、定时任务或批量数据。 - 新增或实质重写 PHP 方法且操作人未知时，编辑前在当前会话确认作者。 无法安全确认且不同答案会造成高风险差异时，再向用户提问。修改时只触及完成需求必需的文件；修改后检查调用链、影响范围、PHP 7.3 语法和文档记录。 ## 3. 项目架构与范围 - 核心组件、活动入口、请求链、租户结构、数据调用方向和前端形态统一见 `docs/PROJECT_ARCHITECTURE.md`。 - 架构文档标记的停止使用目录不属于常规需求范围；除非用户明确提出重新启用或专项处置，不分析、不扩展、不升级。 ## 4. 路由与权限边界 - `mvc::$URL_PARAMS` 可能同时包含位置参数和命名参数；使用前检查存在性、类型和值域。 - `baseAction` 并非所有 Action 都继承；权限必须沿实际继承和调用链确认。 - 登录跳转、白名单、公开接口和外部回调是安全边界，未经确认不得扩大。 ## 5. PHP 编程规则 - PHP 编码、PHPDoc、安全、依赖和验证统一遵循 `docs/PHP_RULES.md`。 - 本项目最低兼容 PHP 7.3，并沿用无命名空间的传统类加载方式。 ## 6. 共享系统与租户覆盖 - 共享和实例目录结构见 `docs/PROJECT_ARCHITECTURE.md`，覆盖关系依据实际代码引用和用户明确范围判断。 - 修改共享文件前，扫描数字实例是否对目标路由、模板或静态文件存在私有覆盖。 - 未经用户确认，不批量修改、复制或格式化所有数字实例。 - 不直接修改明显生成物代替源文件；先确认非配置代码中的生成来源。 - 租户专项需求优先沿用现有实例覆盖；全租户需求修改共享系统，并静态核对纯共享实例和有覆盖实例的调用链。 ## 7. 数据访问 - 数据调用方向见 `docs/PROJECT_ARCHITECTURE.md`。 - `mvc/lib/LibDb.php` 是底层实现，只供数据访问层内部封装使用。 - Action 和业务代码不得直接实例化、调用或新增对 `LibDb` 的依赖。 - 优先复用对应业务模块现有方法和 `XXXBase.class.php`；需要新增数据能力时，在对应 Base 中增加职责清晰的方法。 - 没有合适业务 Base 时，使用 `mod_base/BaseDb.class.php` 的封装方法。 - 仅当用户未来明确要求时，才可结合目标模块新增 `XXXBaseDb.class.php`；不得自行增加这一层。 - 历史直接调用 `LibDb` 只作为遗留事实和风险，不是新代码范式；仅在需求范围内逐步收口，不全仓替换。 - 底层事务是遗留实现，不提供跨连接原子性保证；订单、支付、退款、提现、库存或跨数据源写入必须设计失败路径和补偿方案。 - 未经用户确认不执行 DDL、批量更新或物理删除；变更流程遵循 `docs/DB.md`。 ## 8. 接口与返回特例 - `LibFc::ReturnData(true, ...)` 返回成功数组；失败分支可能输出并终止，调用方不得假定失败后仍继续执行。 - 不擅自改变既有接口字段、Content-Type、状态码、登录失效码或 JSON/JSONP 行为。 ## 9. 前端、依赖与生成物 - 前端技术形态见 `docs/PROJECT_ARCHITECTURE.md`。修改前查看目标模板实际加载的头文件和组件，复用当前页面模式，不全局升级前端库或引入新的 SPA/组件框架。 - 开发或修改 `admin` 列表时，数据表格必须接入现有 `YpTable` 的列过滤与排序：表格使用 `YpTable`，表头启用 `Filter Sortable`，可排序列使用 `Sort`，数字列沿用 `sort="float"`，过滤输入使用 `FilterTxt`。 - `admin` 列表的搜索区、条件回显和表格展示优先参考路由 `ypcCar/standModelAny` 的 Action 与同名模板，按目标业务精简字段，不复制业务专属逻辑。 - 不修改 `mvc/vendor/`、各应用 `vendor/`、`node_modules/` 或第三方静态源码实现业务需求。 - 依赖变更必须由用户单独授权，并保持 PHP 7.3 兼容。 ## 10. 修改后验证 1. 对每个修改过的非配置 PHP 文件使用 PHP 7.3 执行 `-n -l`；项目配置文件不得参与检查。 2. 静态检查调用方、模板、类名、实际代码引用、返回字段和租户影响面。 3. AI 禁止执行 CLI 或 Web 应用入口，只能进行不读取配置的静态检查或隔离逻辑验证；`docs/PHP_RULES.md` 中允许项目授权执行入口的通用例外不适用于本项目。 4. 涉及接口、数据库、浏览器、租户或外部服务时，最终回复明确标记未执行的入口级或集成验证。 PHP 7.3 可执行文件无法确认时，在当前会话询问；仍无法取得时标记语法检查未执行及原因，不得声称验证完成。真实工具路径、测试 URL 和个人服务信息不得写入共享文档。 ## 11. 文档、变更历史与完成回复 - 架构或项目事实变化时更新 `docs/PROJECT_ARCHITECTURE.md`。 - 功能、接口、数据库、权限、页面交互、共享租户行为或项目规则变化时更新 `docs/需求变更历史.md`。 - 新记录放在表格顶部，日期使用 `YYYY-MM-DD`，写明业务含义、影响范围、处理结论和验证状态。 - 仅修正错别字、纯格式或只补内部注释且不改变行为时，可以不记录。 - `docs/README.md` 是文档索引；新增文档时登记用途，避免多处重复维护同一事实。 - 文档只写已验证事实；推断标记“待确认”。 最终回复说明修改文件、核心改动、影响范围、共享租户/接口/数据库影响、已执行验证、未验证原因和仍需用户确认的高风险问题。