simcompanies-maintenance

name	simcompanies-maintenance
description	Maintain the Auto Max PPHPL SimCompanies Tampermonkey userscript through a consistent analysis, change, validation, and release workflow. Use for every bug report, feature change, new feature, regression investigation, or release affecting this repository.

SimCompanies 维护流程

在此仓库执行任何工作都必须遵循本流程。执行前阅读 AGENTS.md、AGENTS.local.md（如存在）、references/project-map.md 和 docs/daily-workflow.md。

工作流程

1. 分类

• 解释、审计或诊断：只检查并报告证据，不修改文件。
• 修复 Bug：追踪调用链、确认根因、提出最小修复，并在修改前等待确认。
• 功能修改或新增功能：明确页面、模块归属、路由/初始化路径、状态或存储需求、DOM 生命周期和验收标准；先提出方案再等待确认。
• 发布：确认产物来自当前源码，且 Userscript 元数据和版本正确。

2. 绘制调用链

追踪 URL/启动触发点、pageObserver 和开关状态、模块注册或启动路径、DOM/React 生命周期、网络、缓存、存储、Worker、计时器与 Observer 行为，以及 SPA 离开或重复初始化时的清理。

报告证据、受影响文件、根因、最小修改方案、修改后的预期行为和剩余风险。

3. 保持边界

• 保留 ES Modules、功能归属、window.SC_Modules 和 pageObserver。
• 除非明确批准迁移，否则保持存储键和数据格式不变。
• 在适用处使用既有通信方式和共享工具。
• 没有既有约定时，新的 DOM ID/class/data 属性和持久化键使用 sc- 前缀。
• 每个 Observer、计时器、Worker 请求和事件监听都必须有明确所有者与清理/重新初始化路径。
• 新增功能若引入 localStorage/sessionStorage 持久化键或需要排错的持久化状态，必须通过 src/core/exportInfo.js 的 registerExportInfo 注册导出信息；导出中心本身不维护固定键清单。
• 注册时必须标注 scope（realm/global）并只登记插件自身写入的键；删除或改名存储键时同步更新注册。

修复 Bug 或修改功能时，不得进行架构迁移、大范围清理、命名变更或无关格式化。

4. 实现与验证

确认后只修改约定文件，并保持范围外行为不变。修改源码后必须运行 npm run build。

涉及 UI/SPA 时，检查首次进入、离开再返回、React 替换、重复初始化、桌面和手机布局、深色和浅色主题、功能开关、加载/空数据/网络/缓存路径，以及重复 UI、监听、Observer 或计时器。未实际操作浏览器时，不得声称已完成浏览器验证。

面板显隐：显示/隐藏一律用 CSS 类切换（如 show-settings/show-backup），不要给元素设置内联 display——内联样式优先级高于样式表，会覆盖 CSS 里的默认隐藏，导致面板内容直接可见。

4.1 代码约定（踩坑沉淀）

• 先查既有实现：新功能/新调用先 grep 现有模块的同类做法（网络请求用 window.__SC_Network、公司页跳转用 getCompanyLink 同款 URL（/company/<realm>/<名称>/）、领域键用 getScopedKey、面板按钮沿用 createActionButton 模式），不要另起炉灶。
• 内嵌第三方代码：保留原始版权与许可头（如 src/utils/lzstring.js 的 WTFPL 声明），并记入模块地图。
• 领域作用域键：一律经 core/storage.js 的 getScopedKey 生成（R<realmId>-<名称>，如 R0-SC-Saved-Bonuses、R0-SC-AGENCY_FOUND_EXECUTIVE），不要用 SC_<名称>_<realmId> 后缀；新增领域键前先 grep 现有模式确认。
• 领域隔离：涉及领域/公司实体的用户配置（品质范围、备注、预设等）必须按领域分开存储，避免跨领域串扰（建筑 id 跨领域可能重复）。
• 范围类输入约束：任何"从~到"范围输入必须保证前后关系（如品质从 ≤ 到）：修改时钳制，读取时归一（脏数据自动交换）。

5. 正式发布

将 src/ 视为唯一源码，将 .user.js 视为生成产物。正式构建必须要求用户提供一行更新说明；除非用户明确指定其他版本，否则执行：

npm run release -- "<changelog>"

该命令只递增补丁版本（1.x.y 到 1.x.(y+1)），同步受追踪的版本值和 CHANGELOG.md，生成根目录 autoMaxPPHPL.user.js，移除名称中的 (DEV)，并向最终产物追加 // @changelog <更新说明>。不要将更新说明写入业务代码或 Userscript 头部；运行时更新器读取产物尾注。

使用 npm run release -- --dry-run "<更新说明>" 验证发布输入而不写入文件。只有用户明确要求例外时才使用 --version 1.x.y。未被单独要求时，不得提交或推送。

确认正式产物包含预期改动、匹配的版本、没有 (DEV) 标记、正确的更新/下载地址和提供的更新说明。报告修改文件、构建结果、已执行检查和剩余风险。

5.1 发布与合并实操要点（踩坑沉淀，只记会再遇到的）

• 发布前核对 CHANGELOG：将工作区改动逐项与 CHANGELOG.md 未发布区条目一一对应，防止功能改动漏记。
• 提交前确认分支：不要直接提交 main；功能走 feat/、发布走 release/ 分支 + PR。收到"提交当前分支"类指示时若正处于 main，先确认是否应新建分支。
• 未发布区混用：多个 WIP 功能共用未发布区时，提交/发布前确认本次发布范围，避免条目与代码归属错位。
• 分支保护：main 有必需状态检查时，CI 未绿会拒绝合并；本仓库未启用 auto-merge（gh pr merge --auto 会报 enablePullRequestAutoMerge 错误），正确做法是等 CI 变绿（轮询 gh pr checks）后再执行 gh pr merge。
• release 后检查 CHANGELOG 格式：新版本条目与下一节之间应保留空行（条目通常为"更新说明 + 原未发布明细"）。
• 中文 PR 载荷：gh pr create 没有 --title-file（只有 --body-file）；标题与正文统一用 UTF-8 JSON 文件 + gh api ... --input 提交，创建后到 GitHub 核对中文（配合第 6 节编码规则）。

6. 公开协作质量

• 面向维护者和贡献者的仓库文档使用中文；代码标识、命令、URL 和第三方名称保持原样。
• 面向用户的文案（面板说明、更新说明/CHANGELOG）简短直白、只讲功能、不讲实现原理；实现细节（两领域/缓存/压缩/标记/跳转机制等）放维护文档（模块地图、SKILL）。
• 每次源码改动都运行 npm run check；准备合并时确认 GitHub Actions 的 CI 已通过。
• 用户可见行为发生变化时，同步更新 CHANGELOG.md 的 未发布 区域；正式构建会自动写入版本记录。
• 提交 Bug 或功能建议时使用 .github/ISSUE_TEMPLATE/ 模板；Pull Request 必须写明调用链、影响范围、验证结果和剩余风险。
• 通过 GitHub API/CLI 自动创建或更新 PR 时，标题和正文中的中文不要依赖命令行本地编码直接传参；推荐在 JSON 中使用 \uXXXX 转义或确保 UTF-8，创建后到 GitHub 页面核对中文显示。
• 不提交 dist/、依赖目录、环境变量、日志、Cookie、令牌或其他敏感信息。