CaiWuXiTong/AGENTS.md

CaiWuXiTong 团队规则

本文件只保留团队协作和高风险操作的必要边界。普通功能开发应顺畅推进，不因生产级要求反复停下确认。详细步骤按任务需要读取对应 SOP，不在这里重复。

1. 工作原则与授权边界

• 默认使用中文，先给结论；以当前代码、配置、数据和日志为准，旧文档和历史结论仅作参考。
• 用户说“先看、排查、审计”时先只读说明事实和影响；用户说“修改、修复、实现”时，Codex 可直接完成范围内的本地改动、测试、提交和 PR，不必为正常开发步骤逐项请示。
• 围绕用户当前目标持续完成实现和必要验证，常规实现细节自主决定；优先复用现有模式，不顺手重构、升级依赖或修改无关模块。
• 仅在缺失信息会实质改变业务目标、实际写入冲突无法自行安全解决、缺少必需权限，或高风险操作尚未获授权时暂停依赖该条件的步骤；其余工作继续。
• 明确授权在同一任务、目标和影响范围内持续有效，不重复确认；范围、风险或费用实质变化时再确认。不得把 Skill 流程建议当成额外审批要求，也不自行增加团队契约、负责人审批或强制流程。
• 不为理论上可能、但正常使用无法触发的问题增加复杂框架、兜底层或重复检查。

2. 开工与多人协作

• 开工先核对项目目录、git status --short --branch、origin、Git 身份和最新 main；保护现有未提交内容，不覆盖、不顺带提交。
• 开发从最新 main 建立独立任务分支：功能用 feature/用户名-任务名，修复用 fix/用户名-问题名，紧急修复用 hotfix/用户名-问题名。
• 只改独立页面、独立测试或文档时，不强制运行重型预检或提前建立 WIP PR；确认没有明显同名任务后即可开发。
• 涉及多人正在修改的共享文件时，可用 scripts/codex-task-preflight.ps1 辅助检查；不把预检或提前创建 WIP PR 设为普通开发的必经步骤。
• 冲突以当前实际改动为准。结合 PR 合并状态和文件差异排除旧分支、squash 合并造成的误报；仅复用组件或读取同一数据源不阻塞开发。
• 多代理只用于边界清楚且不修改同一批文件的独立工作；主 Codex 负责最终复核。

3. Git、PR 与合并

• main 是稳定主线，不直接在其上开发，不强推。一个分支只完成一个任务。
• 禁止使用 git push --force、git reset --hard、git clean -fd，除非负责人明确指定目标和操作。
• 提交前检查 git status、实际 diff 和暂存区，只提交当前任务文件；不得带入 .env、凭据、日志、构建产物或他人的改动。
• PR 说明做了什么、修改文件、验证结果，以及是否涉及金额、权限、数据库或配置。小型低风险任务不要求冗长模板说明。
• 任务 Codex 在需求满足、相关测试通过且完整 diff 自审无误后，可直接执行 Squash merge、验证远程 main 并清理已合并分支，不需要另一位开发者或负责人再次操作。
• 普通代码发布在相关验证通过、完整 diff 自审并合并到最新 main 后，由任务 Codex 直接部署和验收，无需另行取得部署授权。上游接入和共享镜像同步按第 6 节自主完成；除此之外的生产迁移、数据修复、删除或覆盖配置仍需单独明确授权。

4. 验证要求

• 验证只覆盖本次改动最可能影响的真实路径，优先运行直接测试或实际页面；不因普通页面改动自动升级为全仓库、全服务审计。
• 前端改动至少检查目标页面、关键交互和错误状态；后端改动至少运行相关测试或走一次目标接口；纯文档改动检查内容、链接和 diff 即可。
• 涉及金额、权限、导入、审批或数据库结构时，增加对应边界和回归验证。
• 已确认且状态未变化的内容不重复检查。未验证或验证失败时如实说明，不能写“应该没问题”。
• 数据页面按本次影响验证代表性数据量下的首页、翻页和筛选耗时；明显长时间等待不能以“返回正确”判定通过。低风险改动不增加重复或仅复述实现的测试。
• 明确区分：本地已验证、已提交/推送、已合并、已上线和仍需生产验收。

5. 前端与视觉

• 只有前端任务需要先阅读根目录 DESIGN.md；.impeccable/design.json 是同源机器规范。
• 正式主题为 VIP 黑金。新增或修改页面复用已有设计令牌和共享组件，不扩散旧紫色、亮蓝色或另一套黑金样式。
• 标签页和局部导航使用局部切换，不用整页刷新代替；不叠加重复选中标识。
• 截图和 design-qa.md 是验收证据，不覆盖 DESIGN.md。改变整体视觉方向需要负责人确认。
• 前端验收以实际页面为准，不以代码截图或“已经构建”代替。

6. 数据、上游与敏感信息

• 密码、Token、SSH 私钥、数据库连接串、真实财务数据和生产日志不得进入 Git、PR 或公开文档。
• 需要长期保存的敏感信息写入被 Git 忽略的 runtime/private/敏感信息.md；写入前用 git check-ignore 确认。负责人明确要求时，可在当前一对一对话提供指定范围的敏感信息，但不得扩大传播。
• 本任务所需的上游只读排查、数据字典刷新、数据集登记和启用、共享镜像建表及索引迁移、首次全量、增量、历史回补和镜像校准，由开发者的 Codex 自主完成，无需负责人逐次授权或代执行。Codex 自行核对来源与范围、备份受影响的配置/镜像及同步状态，使用生产同步节点和现有互斥锁分批执行，并核对源数据、完成状态与真实页面；不把这些工作转交给新人。可从上游重建的镜像修复属于此范围；上游写入、原始业务/财务数据修改、无关数据删除、凭据轮换和覆盖生产连接配置仍需单独授权。
• caiwu_system_config 保存用户、权限、设置、连接资料、数据字典和同步状态；caiwu_business_mirror 保存项目已正式接入的上游业务数据。二者不是 SQL Server 网络代理。
• 上游数据库统一按只读黑盒处理。业务查询使用固定、参数化的 Repository/查询执行器，禁止把用户输入拼成 SQL 或执行写操作。
• 正式页面优先读取共享业务镜像；尚未迁移的旧页面可继续使用现有快照兼容层。接入新数据时沿用现有镜像数据集、稳定游标、断点同步和同步状态模式，不另造一套链路。
• 两个现有来源固定为：jiansun 对应 JianSun 旧业务库；operations_replica 对应 JSReportReplica 的 rpt 只读视图。不得交换来源或写回历史临时库名。
• 只有涉及上游接入、镜像同步、数据字典或生产刷新时，才读取 docs/开发与部署SOP.md 第 8 节及 docs/上游业务镜像清单.md。

7. 新人本地开发

• 新人只需启动 Docker Desktop、网页登录并输入负责人提供的系统数据库密码；Codex 按 SOP 运行不带参数的 deploy/local-init.sh，完成初始化和排错，不让新人选择构建或迁移参数。
• 连接团队系统数据库后保留该连接，不切回临时库、不复制他人 .env；普通功能开发无需检查全部上游链路，仅接入新数据时验证对应来源。

8. 构建与生产部署

• 普通代码发布由任务 Codex 在完成验证与合并后直接执行，不要求用户再次说“部署、上线”；用户明确要求仅本地开发、仅审查或暂不上线时遵循其范围。正式发布只使用已合并的最新 main。
• Windows 开发机统一使用 scripts/deploy-from-workstation.ps1，macOS 开发机使用 bash scripts/deploy-from-mac.sh；两者流程一致（本机构建前端与镜像、迁移拦截、增量推送服务器本机 Registry、激活与健康检查、双版本保留）。服务器只运行开发机已构建的 caiwu_akaunting:<commit> 镜像，禁止在服务器执行 Composer、npm 或 Docker 构建。
• 新人只需表达部署需求；Codex 使用默认生产入口运行脚本。首次通过本机窗口提供一次服务器密码后，加密保存在本人电脑供后续自动使用，不要求新人准备私钥、执行命令或每次重输密码。已有私钥认证仍兼容。
• 当前生产入口为 https://caiwu.jiansuntuzhi.cn:8442；公网仍只使用 8442，日常发布不得改成无端口地址。
• 发布脚本检测到新增数据库迁移时，由 Codex 核对全部待执行迁移。仅涉及本任务共享镜像建表、字段、索引和同步登记的迁移，完成备份后自主使用 -AllowMigrations（macOS 为 --allow-migrations）；其他迁移仍按第 6 节确认授权。不能因需要迁移开关就把镜像接入停给负责人。
• 容器内 Laravel 命令使用 www-data。发布后只需确认部署 SHA、应用容器健康、受影响的真实页面/接口、迁移是否执行，以及当前和上一版镜像可回滚。
• 程序静态资源随应用镜像同源发布；七牛只存用户上传的业务图片、票据和附件。
• 只有本地初始化、服务器维护、生产发布或数据库迁移任务需要读取 docs/开发与部署SOP.md 的对应章节；普通功能开发无需加载整份 SOP。

9. 规则优先级

• 本文件是团队当前有效的简明规则。DESIGN.md 和 docs/开发与部署SOP.md 只在对应任务中按需读取。
• 详细文档与本文件冲突时，以本文件和负责人最新明确要求为准；历史截图、旧聊天记录和临时排错方案不能覆盖当前规则。
• 可说明的工作提交后运行增量的项目推进同步。
• 仅同步 Git 元数据；匹配不清或同步失败时停止同步，不影响提交、推送或发布。