FullAccess——Myriad Beta 代码规范

Myriad 由 React 管理端、React Native / Expo 移动端、FastAPI 服务和 PostgreSQL/PostGIS 数据库组成。本篇整理 Beta 开发沿用的工程规则，并把 Alpha 遇到的跨端问题写成可复验的场景。配置和执行命令以 Myriad CodeArts 仓库 中的实际文件为准。

目录

一、从 Alpha 复盘到 Beta 检查

二、目录、命名与工具

• 文本使用 UTF-8、LF，保留文件末尾换行。Python 缩进 4 个空格，其他文件默认 2 个空格，具体配置见 .editorconfig。Python 使用 Ruff 和 basedpyright，TypeScript 使用仓库的 strict 配置。
• Python 函数、变量及数据库字段使用 snake_case。TypeScript 函数和局部变量使用 camelCase，组件和类型使用 PascalCase，自定义 Hook 使用 use 前缀。HTTP 字段遵循生成契约，例如 expected_event_version。
• 环境使用仓库指定的 Node 24、pnpm 11.18.0、Python 3.13 和 uv。依赖变更同步更新对应锁文件。新增代码沿用所在模块的目录和格式，注释优先说明权限、状态变化或加锁原因。

三、接口、状态与前端写入

1. 从同一份契约生成客户端。 修改请求或响应时，先更新 FastAPI 路由和 Pydantic DTO，再生成 OpenAPI 与 TypeScript 客户端。管理端和移动端通过 @myriad/api-client 调用接口，按服务端返回的 allowed_actions、版本与回执状态展示操作。
2. 保留三类记录的含义。 report 保存上报人的原始描述和附件，event 保存管理员组织处理的事件，work_order 保存工作者的任务。重复上报可归入同一事件。一起派工可以创建多张独立工单。历史关联只提供查阅入口，当前事件继续按自己的状态流转。
3. 写入成功以服务端响应或回查为准。 请求等待期间展示处理中。响应丢失时保留该账号的草稿、原请求内容、版本和幂等键，再用原键确认。收到明确的版本冲突后刷新数据，由用户根据最新状态重新提交。退出或切换账号时清理上一账号的私有草稿和缓存。
4. 按错误码处理。 后端统一返回 code、message、details。会话失效引导重新认证，版本冲突引导刷新，参数不合法时保留可修改的输入。访问未授权对象时按接口约定返回 404。

以工单完工为例，客户端按契约传入事件版本、工单版本、附件 ID 和 Idempotency-Key。服务端确认成功后，再更新工作者界面并刷新上报者回执。回归时核对工单、照片权限和上报者看到的结果。

四、事务、数据库与附件

• 写操作由调用方管理事务。 内部服务共用同一事务。状态、证据、修订记录、outbox 和幂等成功记录一起提交。派工确认分类和创建工单也按同一事务处理。批量派工按逐项事务返回每项结果。
• 统一加锁与版本检查。 按区域、按 ID 排序的事件、工单、人员及上报、请求或附件的顺序加锁。关系、合并和人员配置写入使用区域排他锁，普通业务使用区域共享锁。持锁后重新核对版本、当前工单和人员资格。一个事件最多保留一张有效工单。
• 幂等覆盖实际操作对象。 幂等范围包含操作者、操作名和键，请求指纹包含路径资源 ID 和请求内容。同键同内容返回已保存结果，同键异内容返回冲突。
• 结构变更用新迁移。 保留已采用的 0001_foundation.sql，新增迁移描述结构变化。数据库回归使用独立的 _test 库，清理和恢复演练也在独立环境执行。
• 图片通过受控接口读写。 服务端解码、校验大小与格式、重新编码，再写入私有磁盘，写入完成后标记为 ready。绑定随业务事务提交。每次读取按账号、区域和记录归属检查权限，历史完工凭证保留原来的证据。清理候选先排除业务和历史引用，事务提交后再删除文件。

五、AI 建议与配置

模型提供候选、证据和分类草案。服务端校验结构、候选、事件版本和配置，管理员确认后才执行合并、派工或分类变更。人工分类优先。建议过期、模型失败或额度耗尽时保留人工流程。关闭模型后，含图上报、人工派工、完工和回执仍应通过回归。

管理端使用 HttpOnly Cookie，移动端通过共用客户端携带会话令牌。模型密钥留在后端环境。提交、日志、测试截图和课程博客使用合成数据或脱敏材料。AI 辅助生成的代码与测试由提交者核对，交付记录以实际执行结果为准。

六、按改动范围做验证

下表的命令从仓库根目录执行。先检查改动及直接使用该能力的页面，再按影响扩大回归。

测试记录分别写明 HTTP 与数据库、浏览器、原生构建、模拟器和真机的结果。页面截图等服务端状态更新后再取证。候选版本发布或答辩演示时，代码版本、运行材料和测试证据相互对应。

七、提交与集成

提交按可独立说明的改动拆分，标题沿用仓库的 类型(模块): 说明 格式，关联实际 Issue 或任务编号。例如 fix(reporting): 恢复上报响应丢失后的原键确认。成员自行完成实现与自测，集成负责人统一审核公共契约、数据库迁移和跨端影响，再按团队流程合入。

交付时写清楚改了什么、影响哪些角色、执行了哪些命令、结果如何、还有哪些环境待验。启动步骤、配置或接口行为发生变化时，同步更新对应手册。跨端问题以报修最后一步为准，例如完工后上报者能打开自己的回执和完工照片。