82 lines
8.4 KiB
Markdown
82 lines
8.4 KiB
Markdown
# CaiWuXiTong 团队规则
|
||
|
||
本文件只保留团队协作和高风险操作的必要边界。普通功能开发应顺畅推进，不因生产级要求反复停下确认。详细步骤按任务需要读取对应 SOP，不在这里重复。
|
||
|
||
## 1. 工作原则与授权边界
|
||
|
||
- 默认使用中文，先给结论；以当前代码、配置、数据和日志为准，旧文档和历史结论仅作参考。
|
||
- 用户说“先看、排查、审计”时先只读说明事实和影响；用户说“修改、修复、实现”时，Codex 可直接完成范围内的本地改动、测试、提交和 PR，不必为正常开发步骤逐项请示。
|
||
- 一次只处理一个明确任务，优先复用现有模式和解决根因；不顺手重构、升级依赖或修改无关模块。
|
||
- 只有以下情况需要停止并说明：产品方向存在会改变结果的歧义；与其他任务发生实际写入冲突；需要生产发布、生产数据写入、迁移、删除或其他不可逆操作；缺少完成任务必需的外部权限。
|
||
- 不为理论上可能、但正常使用无法触发的问题增加复杂框架、兜底层或重复检查。
|
||
|
||
## 2. 开工与多人协作
|
||
|
||
- 开工先核对项目目录、`git status --short --branch`、`origin`、Git 身份和最新 `main`；保护现有未提交内容，不覆盖、不顺带提交。
|
||
- 开发从最新 `main` 建立独立任务分支：功能用 `feature/用户名-任务名`，修复用 `fix/用户名-问题名`，紧急修复用 `hotfix/用户名-问题名`。
|
||
- 只改独立页面、独立测试或文档时，不强制运行重型预检或提前建立 WIP PR；确认没有明显同名任务后即可开发。
|
||
- 当任务会修改共享路由、Controller、Repository、数据表/视图、`source_key`、`scope`、权限名、菜单键或公共组件，或远程已有相同区域任务时，才运行 `scripts/codex-task-preflight.ps1`，列明“将修改”和“仅复用”内容，并尽早推送 WIP PR。
|
||
- 只有双方会写同一契约或同一文件时才算冲突。仅调用现有路由、组件、Repository 或读取同一数据源不构成阻塞。
|
||
- 多代理只用于边界清楚且不修改同一批文件的独立工作；主 Codex 负责最终复核。
|
||
|
||
## 3. Git、PR 与合并
|
||
|
||
- `main` 是稳定主线，不直接在其上开发，不强推。一个分支只完成一个任务。
|
||
- 禁止使用 `git push --force`、`git reset --hard`、`git clean -fd`，除非负责人明确指定目标和操作。
|
||
- 提交前检查 `git status`、实际 diff 和暂存区，只提交当前任务文件；不得带入 `.env`、凭据、日志、构建产物或他人的改动。
|
||
- PR 说明做了什么、修改文件、验证结果，以及是否涉及金额、权限、数据库或配置。小型低风险任务不要求冗长模板说明。
|
||
- 任务 Codex 在需求满足、相关测试通过且完整 diff 自审无误后，可直接执行 Squash merge、验证远程 `main` 并清理已合并分支，不需要另一位开发者或负责人再次操作。
|
||
- 生产部署、生产迁移、数据修复、删除或覆盖配置仍需单独明确授权，不能因为代码已合并而自动执行。
|
||
|
||
## 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` 确认。负责人明确要求时，可在当前一对一对话提供指定范围的敏感信息，但不得扩大传播。
|
||
- 生产数据库写入、迁移、删除、批量导入和凭据轮换必须先说明影响，准备备份或回滚，并取得明确授权。普通本地只读排查和有限业务查询不需要额外审批。
|
||
- `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 完成。
|
||
- 标准初始化由 Codex 在最新 `main` 上运行不带参数的 `deploy/local-init.sh`。不要让新人判断 `--build`、手工迁移共享数据库、复制他人 `.env` 或配置上游连接。
|
||
- 本地连接系统数据库后，用户、菜单、设置和上游登记继续使用团队系统数据库，不把主连接切回本机临时 MySQL。
|
||
- 与数据库无关的普通页面或业务功能可以直接开发，不要求开发者先理解或验证全部上游、镜像和生产部署链路。
|
||
- 只有接入新上游数据时，才需要验证对应来源的只读查询、镜像同步状态、总数及代表性分页/筛选；无需每个普通任务重复验证两套数据库。
|
||
|
||
## 8. 构建与生产部署
|
||
|
||
- 只有用户明确要求“部署、上线”时才执行生产发布；正式发布只使用已合并的最新 `main`。
|
||
- Windows 开发机统一使用 `scripts/deploy-from-workstation.ps1`。服务器只运行开发机已构建的 `caiwu_akaunting:<commit>` 镜像，禁止在服务器执行 Composer、npm 或 Docker 构建。
|
||
- 当前生产入口为 `https://caiwu.jiansuntuzhi.cn:8442`；公网仍只使用 `8442`，日常发布不得改成无端口地址。
|
||
- 发布脚本检测到新增数据库迁移时必须停止，取得负责人明确授权并完成备份后才能使用迁移开关。
|
||
- 容器内 Laravel 命令使用 `www-data`。发布后只需确认部署 SHA、应用容器健康、受影响的真实页面/接口、迁移是否执行，以及当前和上一版镜像可回滚。
|
||
- 程序静态资源随应用镜像同源发布；七牛只存用户上传的业务图片、票据和附件。
|
||
- 只有本地初始化、服务器维护、生产发布或数据库迁移任务需要读取 `docs/开发与部署SOP.md` 的对应章节；普通功能开发无需加载整份 SOP。
|
||
|
||
## 9. 规则优先级
|
||
|
||
- 本文件是团队当前有效的简明规则。`DESIGN.md` 和 `docs/开发与部署SOP.md` 只在对应任务中按需读取。
|
||
- 详细文档与本文件冲突时，以本文件和负责人最新明确要求为准；历史截图、旧聊天记录和临时排错方案不能覆盖当前规则。
|
||
- 可说明的工作提交后运行增量的项目推进同步。
|
||
- 仅同步 Git 元数据；匹配不清或同步失败时停止同步，不影响提交、推送或发布。
|