# 项目通用开发规则

- 2026-10-13最新授权（P98）：P97登录链整理完成后，允许按完整评审进行KV专属namespace、类/文件名及KV引入警告的整理，取代此前命名后置优先级；只做等价名称/引用变化及已核无副作用的警告处理。保留Dev独立入口、公共PF/KV存档合同及原业务/异常语义，不为清零警告去掉async或新增伪await，不扩改无关代码。

- 2026-10-13后续优先级：先核迁移新增文件和类的实际必要性，确认无消费者则删除；职责可由现有实现等价承接时，先完整评审再合并，减少冗余文件和层次。不能只用排版整理代替结构核销，也不能把减少文件数冒称减少类。保留原业务、资源生命周期和用户明确要求的服务入口；namespace与命名统一仍后置。

- 2026-10-13当前优先级：先整理本次迁移代码，使实现简洁、准确、易读；`Core/KV` 移位后的 namespace 与类/文件命名统一列为后置事项，当前不穿插改名。先处理重复闲置实现和难读的紧凑写法，保持原业务、数据、同步/异步、异常和调用顺序；不以可读性为由增加层次或重设流程。修改前完整评审，保留用户编辑。

- `CodexOutput/` 仅用于本地开发文档、评审及验证产物，不得纳入 Git 提交/推送、服务器上传、部署或发布包；不得使用 `git add -f` 强制加入。已被 Git 跟踪的内容仅取消跟踪，保留本地文件及现有修改。

- 2026-10-10用户要求开发后读取并执行：[PlayFab到KV-存量核查纠偏与开发后检查执行要求](CodexOutput/PlayFab到KV-存量核查纠偏与开发后检查执行要求-2026-10-10.md)。开发会话完成当前批次后必须读取本文，将存量核查纳入已有唯一TODO；后续每批开发及独立AI复核完成后执行其中第六部分的受影响范围自检，本轮核查纠偏完成后再做最终汇总检查，并在既有实施日志记录范围、证据和未闭合项。不能仅记录“已读”或用AI报告代替开发端检查；已有匹配hash的评审复用，不每批重复全工程扫描。发现超出已审边界的问题先补完整方案评审，不扩大业务重构或删除许可。检查通过且仍有已授权工作时继续，不停等用户催促。

- 2026-10-10用户明确要求持续执行：阻塞解除后，只要下一步工作仍在当前客户端侧且已有授权，就立即继续，不能因阶段汇报、更新文档、完成一个检查点/模块或本批审核通过而结束执行、等待用户再说“继续”。按唯一TODO串行推进；必要方案评审和独立AI代码复核由当前侧主动完成，复核通过后继续下一项，已有匹配hash的报告复用。遇到局部阻塞先保留证据并继续不依赖它的已授权工作；只有确实需要用户裁决/外部交付且无其他可推进项、用户明确暂停，或授权范围内工作全部完成时才停止，并说明具体原因。此规则覆盖旧的逐模块停下等人工review节奏，不免除编码前完整方案评审，不扩大1:1迁移、服务器只读、保留工作树及暂不打包边界。

- 2026-10-09最新用户授权：因人工难以阅读整批差异，使用独立AI代码review承接本次模块review，参考裁决后继续后续。模块仍串行，编码前完整方案评审不省略；每模块代码与必要验证完成后由AI复核，发现问题先修本模块，通过后继续。已有匹配当前hash的独立AI报告优先复用，不重复送审；未定业务合同、行为差异或必须由用户裁决的问题仍集中说明。本授权不构成服务器修改、业务优化、整文件回滚或打包许可，也不冒充正式全链验收。

- 2026-10-09用户再次确认：PlayerKV精简仍受全流程1:1平移规则约束，不是架构升级或业务重构授权。只核减本次迁移新增且已被等价替换的重复实现；先列原版→当前→目标的方法、数据及顺序对照，再评审实施。已知行为偏差必须列入唯一模块TODO，未验证不得宣称无漂移；不因服务器暂未交付擅自改变业务、永久冻结功能或扩大改造范围。

- 当前执行边界（2026-10-08本轮用户指令）：保留旧 PlayFabUserService、AggUserService 原实现，新增 KV 服务承接迁移功能；保留现有改动，不整文件回滚。下条此前记录的“最终删除旧类”不构成本轮删除许可，也不作为当前方案前提。先区分既有共用接口、原类行为差异和KV专用实现；冲突范围完成具体方案评审后再改，不继续向旧PF添加KV职责。核对记录见 CodexOutput/upserver/B3BatchMigration/M2/M2-保留旧PF决议与当前评审工作树核对-2026-10-08.md。

- PlayFabUserService 是迁移完成后要移除的旧实现，不是 KV 的宿主或最终双后端架构。迁移期间保留旧类仅用于原行为对照及尚未迁出的有效消费者；不得再为 KV 加接口、partial、验证构造器或加载分支。KVUserService / AggKVUserService / DevKVUserService 独立承接原能力，相关消费者与有效验证迁完后删除旧 PF 实现及其迁移残留。保持原业务行为不等于永久保留旧类；不整文件回滚，不覆盖用户编辑，不提前删除仍在使用的功能。

- KV模式的迁移目标是由KV管理器及其接线承接原PlayFab相关能力，不只迁个人存档；等级榜、公开资料、好友和匹配是原PlayFab调用的既有功能，不得当作新增产品需求、默认延期或直接转交服务端。先核客户端已有KV能力及等价调用映射；只有明确证实缺少必要能力时，才把具体接口证据集中写入沟通文档。不得反复要求用户确认“是否存KV”、新ID或原邮件流程。已审同合同替换连续实施，确有新合同或架构差异时一次合并评审，避免逐功能送审。
- 整个迁移流程、所有阶段与批次均只做平移，不限于 M2。全部迁移完成前，仅修改完成迁移所必需的存储、身份和接口接线，保留原业务规则、调用顺序、同步/异步方式、返回值、异常处理和界面流程。不得夹带额外业务修正、优化或代码重构；不得以“更安全”“更合理”或“顺手修复”为由改变原逻辑。
- 发现原有业务缺陷、代码结构问题或可优化点，统一记录到迁移完成后的待办，不在任何迁移阶段穿插处理。必须等整个迁移流程全部完成后，再由用户另行授权修正；单个阶段完成不构成提前修正的许可。此前方案或评审包含此类扩展时，以此规则及用户最新要求为准。
- 最终闲置实现清理仅限本次迁移造成且经核实已无消费者的实现，不得借清理重构代码或删除原有有效功能。确有无法保持原流程的迁移障碍，先说明具体差异，不自行改写业务规则或冻结功能。
- 在满足已确认的功能、正确性和必要安全边界的前提下，优先选择最简单、最直观、最容易维护的实现。抽象应服务于实际调用者；不要为假设中的扩展增加接口、适配器、管理器、状态机或重复保护层。
- 修改代码前完成相关方案的完整评审，记录裁决和开发边界。评审新增抽象时，说明它解决的具体问题、实际调用点，以及为何复用或小幅修改现有实现不足；无法说明必要性的层次不要引入。
- 同一事实保持单一来源，同一业务流程避免多重开关和重复状态。迁移中的临时路径须登记，最终通关前恢复或清理；最终代码删除闲置实现，但保留仍在使用的原有功能。
- 原设计是迁移基准，尽量做到 1:1 平移：优先复用原方法、业务调用链和初始化入口，仅替换必要的数据来源、身份值和存储接口。不得以迁移为由过度设计、升级架构，或另建与原流程并行的解码、模块装配、初始化和状态管理体系。只有经源码证实无法复用的具体差异才进入集中评审，说明最小改动及行为影响；不得先增加层次再要求原业务适配。已经引入的重复实现须列入方案修订，完整评审并验证等价后再替换和清理，不能直接删除仍在使用的代码。
- 2026-10-08历史节奏（已由2026-10-09独立AI模块review授权、2026-10-10持续执行规则替代）：原要求每模块完成后停下等人工review。当前仍按模块串行、先完整评审再编码，提供原版对照/代码入口/差异/验证，模块问题先修本模块；独立AI复核通过后继续，不再机械等待人工回复。

## C# 代码格式

- 2026-10-13范围约束：显式访问限定符和代码格式规则只落实到本次KV迁移新增的代码及迁移确需修改的具体成员。与KV引入无关的原有类、字段、方法不因缺少private/public/internal/protected而修改；同一文件含KV接线也不构成整文件补齐或重排许可。已有合法且有效的访问范围保持，不为统一风格扩大差异。

- `[Inject]` 必须单独占一行，被标注的字段、属性或方法声明从下一行开始；不得写成 `[Inject] public ...`。新增或修改注入声明时遵守此规则，保留已有的换行格式；不因此批量重排无关代码。
- 字段必须显式声明访问修饰符，类内部使用的字段优先写 `private`，不要依赖省略修饰符时的默认可见性。例如写 `private readonly ...`、`private static ...`、`private ...`。此规则指访问级别，不要求给变量名增加前缀或改名。
- 2026-10-13补充：类实现中的方法、构造器及嵌套类型也必须显式声明访问修饰符，和字段一样按实际调用者选择 `private`、`internal`、`protected` 或 `public`；省略修饰符的既有私有成员补 `private` 时保持原访问范围。局部变量、参数、局部函数、静态构造器、析构器及语言不允许访问修饰符的显式接口实现不套用；不因此扩大无关代码重排。
- 按实际消费者选择最小必要访问级别：跨类调用、依赖注入、接口或继承确需 `internal`、`protected`、`public` 时保留对应权限，不得为了统一为 `private` 而破坏现有调用。构造器也须核对创建位置；局部变量、参数及不允许访问修饰符的显式接口实现不套用字段规则。不批量调整无关代码。
- `if`、`else if`、`else` 分支必须使用大括号，即使只有一条语句也不省略；条件、分支语句不能挤在同一行，不写 `if (...) return ...;` 或 `{ statement; }`。
- 使用大括号的代码块采用换行格式：左、右大括号各自独立成行，块内语句逐行书写并缩进。方法、构造器、属性访问器及控制流块均保持清晰展开，不用一行多个语句压缩代码；不改变条件、执行顺序或原业务行为。

```csharp
[Inject]
public ICustomServerMgr customServerMgr
{
    get;
    set;
}

[Inject]
public IPlayerSaveStore SaveStore
{
    get;
    set;
}

private readonly PlayerKVRuntimeSelection selection;
private PlayerKVGameSessionHandle handle;
```

条件分支示例：

```csharp
if (!IsAuthorized)
{
    return ELoginStep.Api;
}
```