Skip to content

Latest commit

 

History

History
53 lines (38 loc) · 5.72 KB

README.md

File metadata and controls

53 lines (38 loc) · 5.72 KB

开发与可维护性规范

代码应让接手的人能从用户动作找到入口、理解状态和数据流,并在合理范围内修改及验证。目录多、抽象多、测试数量多本身不证明可维护。本文是后续 DeepSeek 实施的约束,根 AGENTS.md 只保留执行入口。

代码结构

  • 沿用当前明确的业务边界,小步整理;先移除重复逻辑和混合职责,再决定是否移动目录。不要按新框架模板覆盖项目。
  • 页面组件负责组装和呈现;认证状态、在线学习流程、伙伴偏好与键盘上下文按职责抽成可独立测试的 composable/应用服务。不要把整个页面原样搬进一个 useEverything 文件。
  • 状态机/领域规则用明确输入输出的纯逻辑;网络、存储、随机源、时钟和渲染通过边界调用。领域逻辑不反向依赖 Vue、Phaser 或 DOM。
  • 服务端继续按业务分包。Controller 做输入/认证边界,应用服务编排业务和事务,Mapper 做受约束持久化;不为每个简单方法强加接口/Impl/BaseService。
  • 同类公开能力有一个权威入口;不要新增 utils/common/helpers 大杂烩来藏原来的大文件。
  • 命名使用词库、学习目标、复习、牌组、遭遇等领域词;不在运行类名、注释和资源路径里堆积 P2/G1/H3 等开发阶段代号。
  • 有明确区别时才做统一抽象:本地和在线存储、角色表情和关系值、战术牌和学习卡片不能因名字相近混成一个对象。

当前优先整理入口

以下是源代码抽查后识别的职责问题,实施前需重新核对调用方。文件行数只是定位信号,不设机械上限。

入口 已观察到的职责混合 整理方向与不可破坏点
localRepository.ts 词库 CRUD、导入、偏好、队列、会话、正式评分、诊断、备份集中 按词库/会话/复习/备份分离实现,保留小型兼容 facade;跨表事务仍有单一所有者,不能拆成多个失去原子性的写入
GameWorkspace.vue 登录注册、大厅查询、会话恢复、提交评分、伙伴偏好、键盘与结果统计 拆认证入口、学习会话应用逻辑、伙伴偏好与展示组件;统一取消/账号代际保护,避免晚到响应串号
client.ts 所有 API DTO、接口、CSRF/错误处理和业务端点聚集 分清传输层、业务客户端和契约类型;保留一个 CSRF/错误边界,不在每个模块重复请求包装
ReviewService.java 门禁、快照映射、回执、worker 预览与事务推进 保留清晰的应用编排,按实际共性抽策略/映射;worker 在事务外计算、事务内 CAS/幂等顺序不得变

H0-03 可以拆成多个独立提交,优先整理即将扩展的入口;不要在一次提交同时改目录、命名、算法、API 与产品行为。未涉及的正常模块无需为对称性而重写。

可读代码

  • TypeScript 使用严格类型,边界数据先验证后使用;不要靠 as unknown as、any、忽略错误或关闭 lint 掩盖问题。
  • 使用清晰控制流,条件、循环有花括号;避免深层嵌套、长三元表达式和一行多个语句。
  • 注释解释业务不变量、边界和取舍。提交幂等、评分策略、数据迁移、资源生命周期等需要解释“为什么”;不逐行翻译语法。
  • 错误区分用户可修复问题、网络失败、权限和状态冲突;不能 catch 后返回空数组假装没有数据。
  • Vue 受控 props/事件保持单向,API/存储不要从任意子组件发起。样式遵守现有 token 和组件作用域,不把所有新界面继续堆进 main.css。
  • Java 服务和 DTO 用有意义的类型表达契约。现有 JSON 快照存储是架构决定;可以收拢类型化访问/校验,但不能借整理无声更换数据格式或事务。
  • API、迁移、文档与消费者在同一行为切片中更新;已运行 Flyway 和旧日志不可改写。

验证与提交

  1. 读取 AGENTS、文档导航、当前 Git 和本地交接,确认要改的能力与已有改动。
  2. 保持原行为的结构整理先用已有测试保护;涉及事务、幂等、并发、跨端或策略变更补有意义的反例。
  3. Web 使用现有 type-check/lint/test/build;服务端按影响运行单元或真实 MySQL 集成。文档调整检查链接、路径、契约一致性即可。
  4. 完成后人工阅读实际 diff,检查命名、职责、无关改动和缺失消费者,不能只看命令退出码。
  5. 只暂存当前切片及依赖;部分暂存需要验证候选快照,不能把工作区测试结果当作暂存快照的证明。
  6. 每个可验证切片创建本地 commit 并在交付中报告 SHA;未经指令不推送、发布或改写历史。不要为了凑切片创建不可构建的提交。

截图、录屏、trace、命令原始输出、机器端口与聊天交接只放忽略的 .local/。实际 UI/声音验收仍需执行;不把过程产物提交,并不意味着可以不验证。测试源码、固定 fixture 和确定性测试数据继续提交。

文档与资源

新文档先选择 导航 中的主题,优先更新已有文件;运行规则写产品,实现取舍写架构,协议字段写 OpenAPI,不复制三份长期事实。根 README 面向使用者,AGENTS 面向执行者,本地交接用于恢复现场。

二进制素材按 资源管理 使用 LFS。清理过程文件不删除成品资源,重命名/迁移时同步消费者和来源清单。未经明确授权不重写 Git 历史或清理共享数据库/容器。