Imported from jiumao2/PKUBA_Miniprogram (
AGENTS.md). Install upstream withnpx skills add jiumao2/PKUBA_Miniprogram. Copyright stays with the author.
PKUBA 项目宪法
生产级默认
main是生产发布来源；代码、配置、迁移、文档、测试和 Git 操作一律按可发布、可审计、可回滚标准执行，不接受“仅测试可用”的产品实现。- 发布级标准不等于生产操作授权。连接生产、修改仓库门禁、创建或删除标签、发布镜像、切换域名、迁移或恢复生产数据，仍须取得当前任务对精确目标和动作的明确授权。
README.md是公开项目首页，只写稳定的产品定位、能力、架构、入口和许可证；日期化进度、QA 数据、私有路径、账号、阻断状态和临时操作不得进入 README。- 本地演示、故障注入和合成数据必须与生产配置、数据库、媒体和凭据隔离，并在代码和文档中明确标注仅限本地。
权威与规则
- 本仓库是新版系统唯一实现；旧小程序与
ScoresheetReader只读。 - Django/PostgreSQL 是业务权威；客户端只呈现状态并提交意图。
- 规则优先级：最新用户决定 >
docs/SYSTEM_SPEC.md> 专题规范与docs/USER_GUIDE.md>Plan.md> 当前代码和动态测试证据 > 旧项目 / 《参赛手册》。 - 旧资料只用于理解历史；与新版决定冲突时不得覆盖新版规则。
- 安全清理、依赖升级、扫描告警处置和行为“改进”前必须先核对
docs/FINDING_DISPOSITIONS.md。命中有效的KEEP_AS_DESIGNED、FALSE_POSITIVE、ACCEPTED_RISK或DEFERRED时，未经用户重新确认不得修改、关闭、驳回、升级绕过或声称已修复。 - 未命中登记的新告警或新问题默认是
REVIEW_REQUIRED；发现只授权诊断和报告，不授权修改代码、配置、依赖、数据或外部告警状态，必须先向用户报告证据和修复选项并取得明确决定。 - 只有登记的重新打开条件被真实证据触发时，才先报告证据并请求用户决定；无法访问登记引用的私密详情时不得猜测或通过公开文件补写敏感内容。
业务不变量
- 权限、状态迁移、版本检查、容量、比分、排名和派生数据均由服务端重算。
- 写操作使用稳定 ID；关键命令必须事务化、可重试、可审计，并按需要支持幂等。
- 所有赛季专属记录必须在数据库层隔离，不得跨赛季共用球队、组别、赛程或统计。
- 归档赛季默认整体只读；任何获准纠错必须走专用服务、明确确认并保留审计。
- publication、revision、审计和来源证据不可原地改写或物理删除。
- 永久政策、活动锁、资源预留和运行状态必须分别存储。
- 调赛的日期关系、处理通道和管理员审核认定是不同语义，不得复用同一枚举。
- 未发布的调赛目标场地只供服务端预留与冲突检查，不得向申请参与者或管理员泄露。
- 私密身份、令牌、名单、记录表和媒体不得进入日志、公开接口或 Git。
- 数据恢复必须保持数据库、媒体与归档清单属于同一一致恢复点。
接口与兼容
- API 永远重新读取当前权限、状态和版本，不信任客户端上传的完整对象。
- 枚举值一经持久化不得更换含义；历史记录必须持续可读、可解释。
- 数据库与协议变更遵循 expand / contract；schema 兼容不等于语义兼容，旧版本只有通过 capability 与动态证据后才能共存或回切，再单独收紧。
- 明确废止旧协议时，应在一次受控清理中删除入口、实现、夹具、测试和说明。
- 模型、迁移、OpenAPI、生成客户端、页面、文档和测试必须同步更新。
- 可预期的校验、权限、状态与并发冲突应稳定返回可识别的 4xx / 409；不可预期故障保持 5xx、可观测且不得泄密。失败事务不得留下部分写入。
协作与验证
- 共享工作区禁止 reset、clean、覆盖式恢复或清理他人正在修改的文件。
- 保留无关改动；
docs/INDEPENDENT_TEST_PLAN_AND_RESULTS.md由独立测试任务维护。 - 先做调用链审计和聚焦测试，再运行 PostgreSQL、类型、单测和生产构建全门槛。
- 构建成功不能替代数据库约束、真实 API、浏览器或微信开发者工具验收。
- 测试数据、生产系统、付费服务、发布标签和域名切换必须遵守当前任务授权边界。
- 提交前检查敏感内容、迁移状态、生成文件、文档和未跟踪文件范围。
Agent 接手与交付
- 接手任务先完整阅读本文件、
docs/MAINTAINER_GUIDE.md、WORKFLOW.md及受影响领域的权威文档；涉及安全清理、依赖升级、扫描告警或行为“改进”时还必须阅读docs/FINDING_DISPOSITIONS.md。随后再检查分支、HEAD、origin/main、工作区和运行制品；不得从任务标题或旧对话摘要猜测当前状态。 - 开始修改前记录基线 SHA、任务范围和明确不做事项。文件范围以候选分支相对基线的 Git diff 为准；若基线或共享工作区出现他人产品改动，停止写入并重新核对，不得 reset、clean 或覆盖。
- 实现者只修改批准范围并提供聚焦测试、相邻流程、完整门槛、已知边界和未验证事项。涉及 UI 必须使用真实浏览器或微信开发者工具；涉及数据库、并发、迁移和恢复必须使用隔离 PostgreSQL 或成套恢复副本。
- 实现者可以在功能分支正常提交候选。候选交接必须包含 base、PR head commit/tree、Git diff 路径、实际测试输出、运行制品身份和剩余边界；Git commit/tree 是候选的内容身份，不再手工维护逐文件哈希清单。任何新提交都会使旧验收失效，并按影响范围重新测试。
- 独立测试任务拥有并维护
docs/INDEPENDENT_TEST_PLAN_AND_RESULTS.md；实现和提交任务不得读取后顺手改写、暂存或提交该报告，也不得用自己的测试替代独立结论。 - 独立测试绑定 PR head SHA，在 required CI 成功并完成差异审查、聚焦及必要动态验收后发送
ACCEPTED_FOR_MERGE <SHA>。squash merge 后若maintree 与已验收 PR tree 相同，只需确认身份和mainCI，不机械重跑完整测试；tree 不同则重新验收。提交前仍须检查 staged diff、空白错误、敏感内容和未跟踪文件，合并后核对本地、远端、GitHubmain、最终 tree 及 required CI。 - 详细接手、验证、交接和提交命令以
docs/MAINTAINER_GUIDE.md与WORKFLOW.md为准；本文件只保留不可违反的仓库级约束。
权威文档索引
- 维护者与 Agent 接手、验证和交接：
docs/MAINTAINER_GUIDE.md - 本地环境、微信开发者工具与检查命令：
docs/DEVELOPMENT.md - 团队协作、评审与发布流程：
WORKFLOW.md - 总体计划与里程碑：
Plan.md - 稳定系统规范：
docs/SYSTEM_SPEC.md - 用户可见与隐式规则：
docs/USER_GUIDE.md - 调赛状态机与兼容：
docs/RESCHEDULING.md - 赛程导入：
docs/SCHEDULE_IMPORT_V3.md - 记录表：
docs/SCORESHEETS.md - API 幂等、分页、超时与错误：
docs/API_RELIABILITY.md - 已知问题、误报、按设计保留、接受风险与延期处置：
docs/FINDING_DISPOSITIONS.md - 备份归档与恢复：
docs/BACKUP_AND_ARCHIVE.md、docs/DEPLOYMENT.md