@leiax00/yushe-agent-kit 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. package/.agents/dsh/plugins/yushe-user-rules/README.md +66 -0
  2. package/.agents/dsh/plugins/yushe-user-rules/cordis.patch.yml +5 -0
  3. package/.agents/dsh/plugins/yushe-user-rules/index.js +561 -0
  4. package/.agents/dsh/plugins/yushe-user-rules/package.json +9 -0
  5. package/.agents/rules/docs-management.md +16 -0
  6. package/.agents/rules/git-workflow.md +74 -0
  7. package/.agents/rules/interaction.md +35 -0
  8. package/.agents/skills/yx-api-design/SKILL.md +15 -0
  9. package/.agents/skills/yx-api-design/references/evolution.md +11 -0
  10. package/.agents/skills/yx-api-design/references/http-contract.md +33 -0
  11. package/.agents/skills/yx-api-design/references/idempotency.md +13 -0
  12. package/.agents/skills/yx-backend-architecture/SKILL.md +77 -0
  13. package/.agents/skills/yx-backend-architecture/references/common/clean-design.md +51 -0
  14. package/.agents/skills/yx-backend-architecture/references/common/common.md +31 -0
  15. package/.agents/skills/yx-backend-architecture/references/go/guide.md +9 -0
  16. package/.agents/skills/yx-backend-architecture/references/java/api-layout.md +103 -0
  17. package/.agents/skills/yx-backend-architecture/references/java/coding-style.md +36 -0
  18. package/.agents/skills/yx-backend-architecture/references/java/data-objects.md +68 -0
  19. package/.agents/skills/yx-backend-architecture/references/java/enums-and-constants.md +42 -0
  20. package/.agents/skills/yx-backend-architecture/references/java/framework-boundaries.md +25 -0
  21. package/.agents/skills/yx-backend-architecture/references/java/input-contracts.md +39 -0
  22. package/.agents/skills/yx-backend-architecture/references/java/integrations.md +54 -0
  23. package/.agents/skills/yx-backend-architecture/references/java/logging-and-audit.md +29 -0
  24. package/.agents/skills/yx-backend-architecture/references/java/mybatis-plus.md +65 -0
  25. package/.agents/skills/yx-backend-architecture/references/java/record-vs-class.md +74 -0
  26. package/.agents/skills/yx-backend-architecture/references/java/repositories-and-modules.md +95 -0
  27. package/.agents/skills/yx-backend-architecture/references/java/spring-boot.md +35 -0
  28. package/.agents/skills/yx-backend-architecture/references/java/structure.md +69 -0
  29. package/.agents/skills/yx-backend-architecture/references/java/verification.md +36 -0
  30. package/.agents/skills/yx-backend-architecture/references/python/guide.md +9 -0
  31. package/.agents/skills/yx-backend-architecture/references/typescript/guide.md +9 -0
  32. package/.agents/skills/yx-database-design/SKILL.md +16 -0
  33. package/.agents/skills/yx-database-design/references/engines.md +17 -0
  34. package/.agents/skills/yx-database-design/references/index-and-transactions.md +11 -0
  35. package/.agents/skills/yx-database-design/references/migrations.md +13 -0
  36. package/.agents/skills/yx-database-design/references/modeling.md +13 -0
  37. package/.agents/skills/yx-docs/SKILL.md +32 -0
  38. package/.agents/skills/yx-docs/references/layout.md +102 -0
  39. package/.agents/skills/yx-docs/references/module-docs.md +60 -0
  40. package/.agents/skills/yx-docs/references/notes.md +39 -0
  41. package/.agents/skills/yx-docs/references/reading-protocol.md +25 -0
  42. package/.agents/skills/yx-docs/references/releases.md +63 -0
  43. package/.agents/skills/yx-docs/references/when-to-write.md +33 -0
  44. package/.agents/skills/yx-docs/references/writing-guide.md +80 -0
  45. package/.agents/skills/yx-frontend-architecture/SKILL.md +16 -0
  46. package/.agents/skills/yx-frontend-architecture/references/frameworks.md +15 -0
  47. package/.agents/skills/yx-frontend-architecture/references/state-and-interaction.md +11 -0
  48. package/.agents/skills/yx-frontend-architecture/references/structure.md +11 -0
  49. package/LICENSE +21 -0
  50. package/README.md +76 -2
  51. package/dist/bin/yak.js +11 -0
  52. package/dist/cli/fsx.js +72 -0
  53. package/dist/cli/kit.js +47 -0
  54. package/dist/cli/main.js +132 -0
  55. package/dist/cli/targets/claude.js +47 -0
  56. package/dist/cli/targets/dsh.js +61 -0
  57. package/dist/cli/targets/registry.js +33 -0
  58. package/dist/cli/targets/types.js +1 -0
  59. package/package.json +40 -4
@@ -0,0 +1,25 @@
1
+ # 公共框架与业务模块的边界
2
+
3
+ 只有存在实际复用需求时才提炼 framework 模块或 starter;先检查已有能力。不要因为要写第二个 Mapper 就创建框架,也不要复制完整脚手架和历史依赖。
4
+
5
+ ## 可以提炼
6
+
7
+ 一致的数据库/MyBatis 技术依赖组合、分页装配、必要技术扩展,以及业务无关的分页/错误等基础契约。按技术职责保持内聚,避免 db、MyBatis、MyBatis-Plus 多个仅转发依赖的薄壳。
8
+
9
+ 具体 Spring Boot 自动配置注册方式按项目版本核实。装配应支持合理默认、应用覆盖及必要条件;不能写死业务包,也不为探测配置主动建立数据库连接。应用决定业务扫描范围与环境配置。不要提供静默降级为无事务的生产路径。
10
+
11
+ 依赖版本沿用 BOM/父工程集中管理;服务不重复复制框架已经提供的依赖组合。框架不默认加入多数据源、读写分离、额外驱动、租户插件或通用业务基类。
12
+
13
+ ## 必须留在业务或应用侧
14
+
15
+ 业务 DO、Mapper、聚合仓储实现、SQL、迁移、数据范围政策和业务校验属于业务。数据库地址、凭据、环境连接池配置由应用环境管理,不能硬编码进框架。可信操作者可通过技术接口提供,框架不能反向依赖 identity 等业务实现。
16
+
17
+ 共享分页契约不携带 IPage/Servlet,ORM 转换由具体适配器承担。业务常量和 DTO 不因多处使用自动上移 framework-common;仍由实际业务所有者公开稳定契约。
18
+
19
+ ## 防止重复层次
20
+
21
+ 沿用当前 [Repository 统一形态](repositories-and-modules.md):简单和复杂用例均通过 Repository 接口访问持久化,RepositoryImpl 按需使用 ServiceImpl 或 Mapper,统一范围条件和重复持久化规则。应用层不得直接使用 Mapper/ServiceImpl,也不新增并行 DataService 门面。
22
+
23
+ 复杂领域以聚合 Repository 隔离持久化,不额外叠加数据 Service→Repository→Adapter 多层 CRUD 转发。一个 Repository 可以组合多个 Mapper,一个模块也可以有多个 Repository;仅在职责分化后按能力聚合。
24
+
25
+ 查询投影允许由 application 定义查询模型/端口,并由 infrastructure 实现;这是约定的依赖倒置,不因旧规范要求全放 model 而搬迁。不要让 Mapper 签名引用 Controller/Handler/Service 的私有嵌套实现类型,必要的跨边界模型应有独立、清晰的契约归属。
@@ -0,0 +1,39 @@
1
+ # 输入契约、可信范围与模型绑定
2
+
3
+ ## 请求意图与可信上下文
4
+
5
+ 客户端 DTO 仅表示请求意图。认证主体、有效租户、权限与数据范围由服务端可信来源构造,不能作为客户端可绑定字段混入同一个 Query/Command。用例可把已验证的请求意图与可信范围组合成内部查询条件,条件类型不接受 HTTP 自动绑定。
6
+
7
+ 如果授权规则把“操作”与“资源范围”配对,必须保持配对关系;不能把多条授权中的操作与范围分别求并集后任意组合。无真实身份接入时不为跑通流程新增匿名白名单或自报特权头;测试替身只用于明确的测试环境。
8
+
9
+ MUST 在资源查询、修改、批量操作和自定义 SQL 中保持有效范围;只按 ID 查到对象不等于获得访问权限。身份校验、资源授权和数据过滤各自承担职责,不用其中一个替代全部。
10
+
11
+ ## 缺失、显式 null 与默认值
12
+
13
+ 每个输入契约明确区分:字段未提供、显式 null、空字符串、空集合和合法值。Create、全量替换、PATCH 的含义不同,不能共用一个万能 save DTO 掩盖差异。
14
+
15
+ PATCH 常见语义是“未提供不修改、null 清空或拒绝、值为替换”;只有当前契约确实采用时执行,不擅自套用。需要区分未传时,primitive 的 0/false 往往不足;包装类型可区分 null 与数值,但本身不能区分 JSON 字段缺失与显式 null,必须有实际支持的存在性表示或绑定策略。
16
+
17
+ 默认值不能在绑定/构造阶段提前抹掉业务需要区分的状态。先确定请求契约,再决定规范化和校验顺序;长度、空白、重复项和集合 null 元素都需定义。禁止把显式非法值“修正”为默认成功值。
18
+
19
+ ## 绑定路径与存在性
20
+
21
+ 如果项目依赖无参构造 + setter 绑定表达“缺省保留默认、显式 null 拒绝”,优先保留验证过的 class 方案,不能无测试替换为 record。
22
+
23
+ 不能普遍声称 record 永远无法表达字段存在性,也不能声称 class 自动解决 null 契约。creator/setter、注解、Jackson 模块及版本可能影响行为,必须用实际绑定链路验证“缺失/null/有效值/非法值”四类输入。真实问题需要存在性模型时使用受支持的类型或绑定方案;不要为规避绑定随意引入通用 JSON 解析框架。
24
+
25
+ 固定结构请求使用类型化 DTO 和项目支持的 Bean Validation,不默认改用 Map/JsonNode 手写逐字段解析。只有真实动态结构或现有协议需要时采用树模型,并仍验证约束。
26
+
27
+ ## GET、分页与返回契约
28
+
29
+ GET 筛选可用受支持的请求对象绑定,保持现有 URL 参数名、日期格式、多值语义和分页约定,不为减少 Controller 参数改成 GET JSON body。不能把服务端租户/授权范围混入请求绑定对象。
30
+
31
+ 复用已有公共分页输入/结果,业务条目仍使用自己的模型;公共模型不依赖 ORM/Servlet,框架 Page/IPage 转换留在适配边界。不因引入框架改变外部页码起点、大小限制和排序。
32
+
33
+ 已有统一响应时由 Web 层负责协议包装,应用层返回业务结果。验证正常响应、字段错误、异常处理、认证/授权拒绝和默认错误入口的实际形状;204、文件与流不强行包装 JSON。新增响应外壳属于契约变更,需要同步文档和消费者,不能作为随手“统一风格”的修改。
34
+
35
+ ## 验证
36
+
37
+ 覆盖缺失/null/空值、未知字段策略、类型错误、整数边界、布尔属性命名、集合重复项、规范化前后长度和实际 JSON 字段。未知字段是否拒绝沿用明确契约,不因复用旧项目规范突然收紧已有 API。
38
+
39
+ 请求模型变更除编译外还应验证实际序列化/反序列化。Mock 或对象手工构造不能证明 HTTP 绑定行为。
@@ -0,0 +1,54 @@
1
+ # 模块 API、跨服务调用与事件
2
+
3
+ ## 入站、编排与出站
4
+
5
+ 始终以当前模块为参照,方向不由读/写决定:别人查询本模块也是入站。
6
+
7
+ | 角色 | 所属位置 | 方向 |
8
+ |---|---|---|
9
+ | 提供给同 JVM 其他模块的接口 | api | 入站契约 |
10
+ | 接收 HTTP 请求 | internal/web | 入站协议适配 |
11
+ | 执行用例、组织协作 | application | 内部编排 |
12
+ | 本模块定义所需外部能力 | application/port | 出站契约,按需建立 |
13
+ | 调用外部 HTTP/RPC | infrastructure/integration | 出站适配 |
14
+
15
+ 同 JVM 默认由 XxxAppService 直接实现公开 API 接口。调用方注入接口,运行时由其实现执行;只公开必要方法,无需为一次转发再建 Facade。公开契约需要组合/转换多个用例时才增加独立 API 实现类。
16
+
17
+ OTA → DeviceQueryApi → DeviceAppService:对 OTA 是出站,对 Device 是入站。简单同 JVM 调用不强制再包 Port/Adapter;独立部署通信按出站端口隔离。外部 HTTP 请求仍由 web 接收,不进 integration。
18
+
19
+ ## 三类边界
20
+
21
+ 1. 同 JVM:OTA 用例 → device/api/DeviceQueryApi → device/internal/application 的实现。只返回 DeviceSnapshot 等公开契约,不返回 DO/Mapper/内部领域对象。
22
+ 2. 独立部署服务:OTA application 定义 DeviceInfoPort 和本地 DeviceInfo;infrastructure/integration 的 DeviceHttpAdapter 实现端口、调用 HTTP/RPC Client,并将 RemoteDeviceResp 转成 DeviceInfo。用例不知道 Feign/RestClient/WebClient/gRPC 的实现类型。
23
+ 3. 异步事件:领域事件表达内部事实;模块公开事件放所有者 api/event;跨服务消息使用明确版本化的 schema,在 messaging 适配层转换,不直接序列化内部领域对象。
24
+
25
+ ## 远程调用布局
26
+
27
+ ```text
28
+ ota/internal/
29
+ ├── application/
30
+ │ ├── check/CheckUpgradeHandler.java
31
+ │ └── port/
32
+ │ ├── DeviceInfoPort.java
33
+ │ └── DeviceInfo.java
34
+ └── infrastructure/integration/device/
35
+ ├── DeviceHttpAdapter.java
36
+ ├── DeviceHttpClient.java
37
+ └── RemoteDeviceResp.java
38
+ ```
39
+
40
+ Port 的抽象由消费方定义,字段只包含用例所需信息;远程传输 DTO 留在适配器。提供方 HTTP 入口位于其 internal/web/internal 或已有对应入口。
41
+
42
+ 使用项目已有 HTTP/RPC 栈;接口声明并不自动产生可用 Bean,需按所用版本完成代理/客户端装配。明确认证、超时、资源限制、追踪、错误映射以及可安全重试的操作。不可默认内部网络可信,也不能把远程成功副作用当作本地事务可回滚的一部分。
43
+
44
+ ## 共享与独立发布
45
+
46
+ Java 服务确有共享需求时可拆 device-api 契约 Jar 和可选 device-client SDK;消费者不依赖 device-service 实现 Jar。api Jar 不携带 ORM 实体或内部业务实现,client SDK 也不能反向决定应用端口设计。
47
+
48
+ 多语言或独立协议演进优先评估 OpenAPI/Protobuf 等契约;消费方处理未知字符串业务码,避免直接共享内部 Java Enum 导致同步发布。共享契约类型与共享内部实现不是一回事。
49
+
50
+ ## 事件与查询
51
+
52
+ 需要即时结果的查询优先同步模块 API/远程查询,不为降低表面耦合全部改成事件。通知、审计等已发生事实可事件化;可靠跨进程交付需考虑 outbox、幂等、重试和恢复。若双向公开契约产生模块循环,重新划分概念所有权、提炼必要稳定契约或改用事件,不把所有业务类型搬入 shared 来隐藏循环。
53
+
54
+ 跨模块可访问的类型及只读例外统一见 [公开访问边界](api-layout.md);模块内部多仓储的组织按主入口加载 Repository 文档。
@@ -0,0 +1,29 @@
1
+ # 业务日志与审计
2
+
3
+ ## 日志服务于排查
4
+
5
+ 在关键变更、外部调用、批处理和有诊断价值的拒绝点记录有界信息,不给每个方法机械增加进入/退出日志,也不以万能切面替代业务语义。
6
+
7
+ 优先使用现有 SLF4J 占位符和日志设施,记录操作、资源标识、数量、修改字段标志以及可信身份范围。复用 requestId/traceId;需核实实际日志配置输出关联标识,异步任务的上下文传递与清理不能假定自动生效。
8
+
9
+ 成功写入阶段信息通常 INFO,普通查询摘要通常 DEBUG,预期拒绝按排查价值选择 DEBUG/WARN,未知故障在统一异常边界 ERROR 并保留堆栈。等级按项目运营约定调整;避免逐层 catch-log-rethrow 重复打印。
10
+
11
+ 禁止无差别打印 DTO、响应、完整集合、SQL 参数、自由文本、凭据或令牌。对外部可控日志内容限制长度并处理换行等日志注入风险;标识也按实际敏感等级脱敏,不把“数字 ID”视作天然公开。
12
+
13
+ ## 事务结果不能提前宣布
14
+
15
+ @Transactional 方法体结束并不代表事务一定提交;可能仍处于代理提交阶段或外层事务中。提交前日志只能描述处理阶段,不写确定的“提交成功”。确需记录提交结果时使用项目已有事务完成机制,并验证失败/回滚;不为增加一条日志引入通用事务包装层。
16
+
17
+ 异常路径保留真实失败,不能为日志改变返回值、异常类型、权限或回滚行为。事务完成后发布一次事件也不自动成为可靠审计交付。
18
+
19
+ ## 诊断日志与操作审计不同
20
+
21
+ 诊断日志不能替代需要可靠保存的操作审计。已有统一审计能力优先复用,不为每个模块重复建立同构操作日志表;确有独立业务语义的状态历史、版本记录仍由所属业务维护。
22
+
23
+ 通用记录契约、脱敏与基础设施可复用;存储适配、业务详情和保留要求按实际需求决定。不将统一审计解读为必须一张全局表或必须新增独立服务。
24
+
25
+ 明确成功/失败审计与业务事务的关系、故障影响、幂等及可靠交付要求。不能把异步告警当可靠留痕,也不能为保留失败审计随意用 REQUIRES_NEW 拆断业务一致性。
26
+
27
+ ## 按风险验证
28
+
29
+ 修改日志/审计时验证关键节点覆盖、敏感字段排除、级别、关联标识及回滚不误报;需可靠审计时再验证存储/投递失败路径。纯格式修改不强制增加全套日志测试。
@@ -0,0 +1,65 @@
1
+ # MyBatis-Plus 持久化规范
2
+
3
+ ## 版本与边界
4
+
5
+ 先确认 MyBatis-Plus、MyBatis、Spring Boot 和数据库版本及已有插件链。依赖拆分、分页解析器和插件行为随版本变化,应核对所用版本文档;不要为了套用示例自动添加最新版依赖。
6
+
7
+ DO、Mapper 和 RepositoryImpl 位于 persistence。简单和复杂模块均采用 AppService → Repository 接口 → RepositoryImpl → Mapper;AppService 不访问 Mapper/Wrapper 或继承的 CRUD 旁路。Repository 接口不继承 IService/BaseMapper,不暴露数据访问技术类型,参见 [统一 Repository 形态](repositories-and-modules.md)。
8
+
9
+ RepositoryImpl MAY 继承 ServiceImpl 复用能力,也 MAY 直接组合 Mapper;不强制继承。多表聚合可使用多个 Mapper,ServiceImpl 不能替代领域契约。只暴露实际所需 Repository 方法,明确 insert/update、聚合保存和冲突语义,不叠加纯转发 DataService。
10
+
11
+ 对象分类与 TypeHandler 读取 [数据对象](data-objects.md),枚举映射读取 [枚举规范](enums-and-constants.md)。
12
+
13
+ ## 映射与输入
14
+
15
+ 主键策略应与数据库、分布式生成方式及外部契约一致;大整数跨 JavaScript 边界时需保证精度。明确表列、枚举业务值、时间和 JSON 类型映射。自动填充审计字段前确认实际插入/更新路径支持填充,不把 fill 当作权限校验。
16
+
17
+ 更新只映射允许修改的字段。区分“未传”“显式置空”“保持原值”,结合字段更新策略验证 SQL;不要靠全量 DTO 拷贝或全局允许 null 更新实现 PATCH。
18
+
19
+ ## 查询与 SQL
20
+
21
+ - 值使用参数绑定;动态列名、排序字段从服务端白名单映射,不能直接拼入用户字符串。
22
+ - Lambda Wrapper 适合普通单表查询;复杂连接、统计和批量处理用可审查的 XML/SQL,并保留参数绑定。
23
+ - 谨慎使用 `${}`、last、apply 等原始 SQL 能力,不能让不可信输入进入结构片段。
24
+ - 列表必须分页或使用受限批次,设置页大小上限及稳定排序;大偏移按需求改为游标分页。
25
+ - 显式选择所需字段,避免循环中逐条查询的 N+1;批量 IN 要考虑数据库参数限制与结果排序。
26
+ - 更新和删除检查条件及影响行数。即使启用防全表更新插件,也要验证业务条件完整。
27
+
28
+ ## 并发与租户
29
+
30
+ 例如库存扣减的 SQL 意图为:
31
+
32
+ ```sql
33
+ UPDATE inventory
34
+ SET available = available - :quantity, version = version + 1
35
+ WHERE id = :id AND tenant_id = :tenant_id
36
+ AND available >= :quantity AND version = :expected_version;
37
+ ```
38
+
39
+ 此处冒号参数仅表达绑定意图,落地为 Mapper 时按实际 MyBatis 语法绑定。先验证 quantity > 0;影响行数为 0 是并发冲突、库存不足或对象不可见,需按业务语义处理,不能继续返回成功。
40
+
41
+ 乐观锁插件的生效取决于实体版本字段、调用方式和插件配置;自定义 SQL 不能默认被自动保护。重试必须重读状态并重新判定业务规则,不能盲目重放支付等外部副作用。
42
+
43
+ 租户拦截器是纵深防御,不替代认证和资源授权。测试自定义 SQL、连接查询、异步任务和显式忽略拦截器的路径。客户端传来的 tenantId 不能直接成为可信隔离条件。
44
+
45
+ ## 逻辑删除、唯一性与性能
46
+
47
+ 逻辑删除改变查询与唯一性语义:数据库唯一约束仍作用于已删除记录,需按数据库能力设计“仅活跃记录唯一”或允许复用的键。不要机械使用 unique(业务键, deleted) 并声称支持反复删除和重建。
48
+
49
+ 确认自定义 SQL、统计、关联和管理员查询的删除过滤。逻辑删除不等于隐私数据清除。
50
+
51
+ 分页插件位置、数据库方言及多插件组合按实际版本确认;复杂连接的 count 与结果行数可能不一致,应验证计数 SQL。用真实数据分布检查执行计划,区分数据库批量语句、批处理执行和事务边界;禁止无界大事务。
52
+
53
+ ## 最低验证集合
54
+
55
+ 包含分页边界、null 更新、唯一冲突、乐观锁冲突、租户隔离、逻辑删除过滤和受影响行数。对本次没有涉及的插件不强行启用或追加测试。
56
+
57
+ ## ORM 使用与元数据补充
58
+
59
+ 常规 CRUD 优先复用现有 BaseMapper/Wrapper,不重复手写相同 SQL。新写复杂关联、聚合或特殊批量 SQL 默认放 Mapper XML,Java Mapper 保持方法签名与参数绑定,避免把大段 SQL 写进注解;已有合理实现不因本次规范更新强制迁移。
60
+
61
+ 复合键按实际键结构定位和更新,不为迎合框架伪造单主键,也不调用并不适用的 ById 方法。范围条件必须覆盖普通 CRUD、自定义 SQL、批量和锁定查询,不允许按 ID 更新时漏掉租户或业务可见范围。
62
+
63
+ 创建时间与创建者不能被更新覆盖;更新者来自可信服务端提供者,无登录用户的任务采用明确系统主体或约定空值,不伪造用户。更新者为空时明确定义是否清空,避免保留上次操作者造成错误归因。备注等业务可编辑字段不能自动当作审计元数据填充。
64
+
65
+ 自动填充必须验证实际调用形态,特别是仅 Wrapper、空实体、批量、自定义 SQL 的路径不能假定与标准实体更新等价。生成 SQL/Wrapper 的离线测试只能证明构建意图,不能证明数据库执行、锁、约束和回滚。
@@ -0,0 +1,74 @@
1
+ # record 与 class 的选择规范
2
+
3
+ ## 先判断语义,再选语法
4
+
5
+ 本项目的默认判断:对象表示“创建后保持稳定的一份值/数据”,且按全部组成值判断相等符合业务含义时,优先 record;对象表示“有身份和生命周期的事物”、需要受控状态变化或提供服务能力时,使用普通 class。record 本身也是一种 class,这里 class 指普通类。
6
+
7
+ 这不是“DTO 一律 record、带方法一律 class”。record 可以有校验、计算和返回新值的业务方法;普通 class 也可以不可变。字段多少、是否使用 Lombok/Builder 都不是第一判断依据。
8
+
9
+ ## 本项目默认选择表
10
+
11
+ | 场景 | 默认选择 | 选择条件/例外 |
12
+ |---|---|---|
13
+ | Command、Query、Result、列表投影 | record | 一次构建后作为稳定输入/结果传递;绑定或映射不支持时用 class |
14
+ | HTTP JSON Req/Resp | record | 实际序列化、反序列化和校验链路支持;表单/multipart/旧 Bean 绑定按实际能力选择 class |
15
+ | 模块 API DTO、远程 DTO、事件快照 | record | 适合稳定数据快照;发布契约变更需单独评估兼容性 |
16
+ | 领域值对象,如 Imei、VersionNumber、DateRange | record | 组成值定义业务含义,构造时校验;需隐藏表示或定制相等语义时评估不可变 class |
17
+ | 领域实体/聚合,如 Device、UpgradeRule | class | 有业务身份、生命周期和受控状态转换;不能默认按所有字段生成 equals/hashCode |
18
+ | MyBatis/MyBatis-Plus 表映射 DO | class | 本项目默认支持常见字段映射、ID 回填、审计填充及更新流程;不宣称 MyBatis 无法使用 record |
19
+ | 只读 SQL 查询投影 | record | 实际构造器映射及空值/类型转换已验证;它是查询结果,不承担可变 DO 的职责 |
20
+ | Controller、Handler、Service、Repository 实现、Adapter、配置装配 | class | 表达依赖与执行职责,不是透明值载体 |
21
+ | 配置属性对象 | 按绑定方式决定 | 构造器绑定并固定配置可用 record;需要 JavaBean 绑定/受支持的可变机制时用 class |
22
+
23
+ ## 必须选择/保留 class 的信号
24
+
25
+ 对象需要创建后改变实例状态、依赖类继承/子类代理、保留组件列表以外的实例状态,或不应公开完整表示时,采用 class。不要为适配 record 暴露不该公开的字段或重建复杂状态管理。
26
+
27
+ 实体的身份与状态分开处理;同一个设备改变固件版本后仍是同一业务实体。不要为了省代码让 record 的默认全组件相等语义替代身份设计。也不要对实体直接使用 Lombok @Data/@Value 的生成相等逻辑而不审查。
28
+
29
+ class 不等于公开 setter:聚合通过 activate、changeChannel 等业务方法变化;禁止任意 setter 绕过规则。只读 class 同样可以用 final 字段与构建边界保持不可变。
30
+
31
+ ## record 使用约束
32
+
33
+ 排版遵循 [编码基线](coding-style.md)。构造时保护值对象不变量;DTO 格式校验与领域规则分开,不把网络/数据库调用塞进构造器。
34
+
35
+ ```java
36
+ public record DateRange(
37
+ LocalDate start,
38
+ LocalDate end
39
+ ) {
40
+ public DateRange {
41
+ Objects.requireNonNull(start, "start");
42
+ Objects.requireNonNull(end, "end");
43
+ if (start.isAfter(end)) {
44
+ throw new IllegalArgumentException("开始日期不能晚于结束日期");
45
+ }
46
+ }
47
+
48
+ public boolean contains(LocalDate date) {
49
+ Objects.requireNonNull(date, "date");
50
+ return !date.isBefore(start) && !date.isAfter(end);
51
+ }
52
+ }
53
+ ```
54
+
55
+ 示例需导入 java.time.LocalDate、java.util.Objects;表示日期区间且包含两端。它有业务行为,但仍适合 record,因为不改变自身状态。
56
+
57
+ record 只保证组件引用不可重新赋值,不保证引用对象深度不可变。集合/数组/可变日期需要合适的防御性复制;若使用 List.copyOf,必须接受并说明其拒绝 null 元素的语义。集合中元素若仍可变,仅复制集合不足以构成不可变快照;数组输入复制后还要考虑访问器泄露。
58
+
59
+ 默认 equals/hashCode 基于组件;数组组件不会自动得到按内容比较的值语义,金额的小数精度等也可能影响业务相等。优先选择符合语义的不可变组件和规范化方式;不要为迁就 record 编写一整套难懂的相等性补丁。
60
+
61
+ 自动 toString 可能包含敏感组件,不能把口令/令牌 DTO 直接写日志。是否使用 record/class 都不能替代日志脱敏和访问控制。
62
+
63
+ ## 框架兼容与演进检查
64
+
65
+ 选择类型前看项目 JDK、JSON/Bean Validation、ORM 映射和注解处理版本,并通过实际调用路径验证;语言支持不等于框架的所有绑定模式都支持。不要未经验证就把现有 DO、表单模型或代理对象批量替换成 record。
66
+
67
+ 改 class 为 record 会改变构造方式、访问器命名、相等性和默认字符串表示,可能破坏反射/Java 调用方。record 新增组件也会改变构造器;JSON 消费方兼容与 Java 二进制兼容要分别判断。按现有契约演进规则处理,不将这种改动视为纯格式化。
68
+
69
+ 类型变更重点检查构造/访问兼容、集合复制、值相等、敏感日志和实际框架能力。若同时改变输入契约,按主入口另选对应文档;只改规范时不宣称已验证业务框架。
70
+
71
+ ## 依据
72
+
73
+ [Oracle Java 21 Record Classes](https://docs.oracle.com/en/java/javase/21/language/records.html) 用于核对语言特性。上面的角色选择表是本项目的设计约定,不是 Java 语言对 DTO、领域实体或 ORM 的强制分类。
74
+
@@ -0,0 +1,95 @@
1
+ # Repository 统一形态与模块拆分
2
+
3
+ ## 统一调用路径
4
+
5
+ 新写或本次明确重构的 Java 模块,MUST 使用:
6
+
7
+ ```text
8
+ Controller → XxxAppService → XxxRepository 接口 → XxxRepositoryImpl → Mapper
9
+ ```
10
+
11
+ 这是当前明确选定的团队边界:用少量仓储接口样板换取持久化隔离,不是要求所有对象都有接口,也不意味着类数量最少。既有模块按任务范围渐进调整,不借更新规范无范围重写存量业务。
12
+
13
+ - AppService 编排用例、业务资格与事务;访问持久化时只依赖 Repository 接口,不注入 RepositoryImpl、Mapper、IService 或 ServiceImpl。它仍可依赖其他模块公开 API、外部能力 Port 及必要领域协作对象。
14
+ - Repository 定义本模块需要的持久化能力,不能继承 IService/BaseMapper,也不复制完整通用 CRUD API。
15
+ - RepositoryImpl 位于 persistence,MAY 继承 MyBatis-Plus ServiceImpl,也 MAY 直接组合 Mapper;ServiceImpl 是实现复用工具,不等同领域 Repository。
16
+ - Mapper、Wrapper、BaseMapper、IService、ServiceImpl 等数据访问技术类型限制在 persistence 实现边界(集中技术配置除外),不出现在用例和 Repository 契约中。禁止 getBaseMapper 等旁路。IPage/Page 在持久化边界转换为独立分页模型。
17
+ - 不再增加一套仅转发 CRUD 的 DataService;真正需要内部协作时可局部拆实现,但不能重复堆叠 DataService/Repository/Adapter。
18
+
19
+ ServiceImpl 继承的公开方法并不会因为实现了 Repository 接口而消失;通过接口注入并检查依赖来限制访问,不宣称 Java 自动隐藏这些方法。架构检查应拒绝应用层引用持久化实现和框架数据访问类型。
20
+
21
+ Repository 方法表达实际查询、插入、更新、加锁或聚合保存语义。不要默认把底层布尔返回值等同于整个用例成功;检查影响行数、冲突与失败语义,保留数据库异常原因。
22
+
23
+ ## 接口、模型和实现的位置
24
+
25
+ 默认统一把内部 Repository 接口放 `internal/repository`;实现、Mapper、DO 放 `internal/infrastructure/persistence`。复杂模块也可沿用已确定的 `domain/repository`,但同一职责只保留一处接口,不在两处创建重复门面。repository 包是内部契约,不是跨模块公开 api。
26
+
27
+ ```text
28
+ device/internal/
29
+ ├── web/
30
+ │ ├── DeviceController.java
31
+ │ ├── CreateDeviceReq.java
32
+ │ └── DeviceResp.java
33
+ ├── application/
34
+ │ └── DeviceAppService.java
35
+ ├── repository/
36
+ │ └── DeviceRepository.java
37
+ ├── domain/ # 只有真实领域规则时建立
38
+ └── infrastructure/persistence/
39
+ ├── DeviceRepositoryImpl.java
40
+ ├── DeviceMapper.java
41
+ └── DeviceDO.java
42
+ ```
43
+
44
+ 简单 CRUD MAY 在 AppService 与 Repository 间复用本模块 DO,避免复制没有独立语义的对象。这是对“纯粹隔离持久化模型”的明确简化:应用层可能引用 DO,但仍不得直接操作 Mapper/Wrapper,也不得用 DO 自动绑定外部输入。若需要完全隔离持久化注解/模型,再使用应用数据模型,不为了统一形式强制复制。
45
+
46
+ 复杂业务 Repository 使用领域对象和业务值类型,实现负责 DO 转换。domain 不依赖 persistence DO 或 MyBatis;domain 的逻辑接口即使位于内部 repository 包,依赖仍向业务模型,不反向指向技术实现。
47
+
48
+ 普通查询可用独立查询投影,不强制重建聚合。查询端口与 Repository 若表达同一能力只保留一个;不为了命名统一复制 ReadRepository/QueryPort 两套接口。
49
+
50
+ ## 一个业务模块允许多个 Repository
51
+
52
+ Repository 围绕业务对象、聚合及一致性边界设计,不按表一一对应。例如 OTA 可以包含 FirmwareRepository、UpgradeRuleRepository、UpgradeTaskRepository。
53
+
54
+ 一个 UpgradeRuleRepository 实现可以协调规则表、条件表、路径约束等多个 Mapper,保存完整聚合。多表聚合不适合单表 ServiceImpl 时直接组合 Mapper,不强制继承。
55
+
56
+ 一个 AppService MAY 协调多个本模块 Repository,事务边界仍由业务用例决定。同一事务资源与事务管理器下的操作按实际配置参与事务;不要因每个 Repository 有多个写入就各自 REQUIRES_NEW,也不把跨服务写入宣称为本地原子提交。
57
+
58
+ 注入多个 Repository 时按 [编码基线](coding-style.md) 检查依赖与构造参数;需要报告取舍时给出实际用例,不通过万能上下文隐藏依赖。
59
+
60
+ ## 何时按能力继续分包
61
+
62
+ 多个 Repository 本身不触发拆包。先保持按职责的平铺;当一个能力的修改经常穿过大量无关文件、规则/消费者/变化原因相互独立,或需要明确内部访问边界时,再按能力聚合。
63
+
64
+ ```text
65
+ ota/
66
+ ├── api/
67
+ └── internal/
68
+ ├── firmware/
69
+ │ ├── application/
70
+ │ ├── domain/
71
+ │ ├── repository/
72
+ │ └── persistence/
73
+ ├── rule/
74
+ │ ├── application/
75
+ │ ├── domain/
76
+ │ ├── repository/
77
+ │ └── persistence/
78
+ ├── task/
79
+ │ ├── application/
80
+ │ ├── domain/
81
+ │ ├── repository/
82
+ │ └── persistence/
83
+ ├── web/
84
+ └── integration/
85
+ ```
86
+
87
+ 这里能力内的 persistence 仍是基础设施边界,省掉额外 infrastructure 层级是目录简化,不改变依赖规则。每个能力只创建实际需要的子包;DO/Mapper 数量增加时可在 persistence 内分 model/mapper,不预建空目录。
88
+
89
+ 不要同时存在职责不清的根 repository 与能力 repository 两套位置。跨能力的数据归属仍唯一:用例通过所属 Repository/能力接口协调,不直接写另一能力的数据表。若能力确实有独立业务语言、所有权和演进边界,应评估提升为并列业务模块,而不是无限嵌套子包。
90
+
91
+ 同一模块能力划分不自动产生独立部署、分库或子模块 api;只为实际稳定消费者设计必要接口。
92
+
93
+ ## 涉及跨模块时
94
+
95
+ 同模块多 Repository 与跨领域调用是不同边界,不能以“统一 Repository”把远程服务伪装成可一起提交的本地仓储。出现跨模块消费者时读取 [公开访问边界](api-layout.md);实现调用链时读取 [集成边界](integrations.md)。
@@ -0,0 +1,35 @@
1
+ # Spring Boot 服务边界
2
+
3
+ ## Web 与服务
4
+
5
+ Controller 负责绑定、格式校验、调用用例及 HTTP 映射,不编排数据库事务。Bean Validation 处理格式/长度/范围;跨对象业务不变量放在用例或领域层。认证身份和租户来自可信上下文,资源级授权必须在服务端检查。
6
+
7
+ 使用项目已有的统一异常处理,区分参数错误、未认证、无权限、不存在、并发冲突和系统故障。对外错误不暴露堆栈、SQL 或内部路径。日志应保留原因与关联标识,避免多层重复记录同一异常。
8
+
9
+ ## 事务
10
+
11
+ 以一个需要原子性的业务用例为事务边界,确认事务管理器、数据源和调用是否经过 Spring 代理。默认代理模式下同类自调用不能触发目标方法的事务拦截;不要以 private 方法注解或新建对象调用作为事务保证。
12
+
13
+ 默认回滚规则通常覆盖 RuntimeException/Error,不应假定 checked exception 自动回滚;结合项目配置明确 rollbackFor 或统一异常语义。捕获异常后正常返回可能导致提交,必须明确是否重新抛出或标记回滚。
14
+
15
+ `readOnly` 是事务/驱动优化提示,不是禁止写入的安全边界。`REQUIRES_NEW` 会独立提交且额外占用连接,仅在有意需要独立事务时使用。异步线程不能自动继承调用线程事务;异步任务需明确自己的事务边界和失败补偿。
16
+
17
+ 事务内避免长时间远程调用和文件处理。读后写的库存扣减需条件更新/锁/版本控制,不靠 @Transactional 单独解决。多数据源和跨服务一致性不能直接宣称由一个注解保证。
18
+
19
+ ## 配置和集成
20
+
21
+ 配置按职责归组并校验必填项。环境差异通过外部配置提供,凭据不入源码。HTTP 客户端、连接池和消息消费者使用有限超时、并发和重试预算。远程 SDK 返回类型在适配器内转换,不穿透到领域。
22
+
23
+ 缓存更新考虑事务提交时机和失败补偿;事务提交前删除缓存可能被旧读回填。需要可靠异步交付时采用持久化消息方案,不能仅依赖内存事件或 afterCommit 回调。
24
+
25
+ ## 验证
26
+
27
+ 业务规则可用纯单元测试;Web 层检查绑定、状态码和授权;事务/SQL 用真实兼容数据库做集成测试。测试中通过 Spring 代理调用服务,并在事务外验证提交/回滚结果,避免测试自身的回滚掩盖问题。
28
+
29
+ ## 输入、事务时序与日志补充
30
+
31
+ 绑定/显式 null/可信范围细则见 [输入契约](input-contracts.md);业务日志与持久化审计见 [日志与审计](logging-and-audit.md);提炼 starter 或公共技术模块时读取 [框架边界](framework-boundaries.md)。
32
+
33
+ 默认以现有声明式事务覆盖用例;明确需要分段事务或动态边界时再评估程序式事务,不为轻量 DDD 统一包装事务端口/回调。入口身份校验与事务内业务资格检查各有职责,依赖当前状态的检查应位于适当事务/锁保护内。
34
+
35
+ 事务拦截可能在方法体业务校验前开始资源处理,不能保证“校验失败前绝不建连”。只有需求确实约束该时序时才局部拆分,不为断言某个调用顺序新增通用框架。
@@ -0,0 +1,69 @@
1
+ # Java 项目架构与目录组织
2
+
3
+ ## 架构基线
4
+
5
+ SHOULD 采用 Spring Boot 模块化单体、业务 Package 优先、复杂业务轻量 DDD、查询侧适度简化。先逻辑模块化,按团队/构建/发布需求再物理拆分,不为每层创建 Maven Module。
6
+
7
+ 先核对 pom.xml/Gradle、toolchain、BOM 和现有结构。原讨论的 Java 21/25 LTS 选型不是强制升级指令。新增模块采用当前约定;既有模块局部修改保持兼容,必要偏离明确说明,不扩大重构范围。
8
+
9
+ ## 默认项目结构
10
+
11
+ ```text
12
+ iot-platform/
13
+ ├── pom.xml
14
+ └── src/
15
+ ├── main/
16
+ │ ├── java/com/example/iot/
17
+ │ │ ├── IotApplication.java
18
+ │ │ ├── identity/
19
+ │ │ ├── product/
20
+ │ │ ├── device/
21
+ │ │ │ ├── api/ # 公开契约,有消费者才建立
22
+ │ │ │ └── internal/
23
+ │ │ │ ├── web/ # Controller、Req、Resp
24
+ │ │ │ ├── application/
25
+ │ │ │ │ └── DeviceAppService.java
26
+ │ │ │ ├── repository/
27
+ │ │ │ │ └── DeviceRepository.java
28
+ │ │ │ ├── domain/ # 按真实复杂度建立
29
+ │ │ │ ├── infrastructure/
30
+ │ │ │ │ ├── persistence/ # RepositoryImpl、Mapper、DO、Converter
31
+ │ │ │ │ ├── integration/ # 外部调用适配
32
+ │ │ │ │ └── messaging/ # MQ 适配
33
+ │ │ │ └── config/ # 必要配置和装配
34
+ │ │ ├── ota/
35
+ │ │ ├── system/
36
+ │ │ └── shared/ # 稳定、无业务归属技术能力
37
+ │ └── resources/
38
+ │ ├── mapper/ # 按模块组织 XML,沿用扫描配置
39
+ │ └── db/migration/ # 沿用实际迁移工具
40
+ └── test/java/com/example/iot/
41
+ ```
42
+
43
+ 示例表示职责位置,不要求创建所有目录。默认 internal/web,不使用 interfaces/rest。完整 Repository 形态、多仓储和能力分包规则必须读取 [Repository 与模块](repositories-and-modules.md)。
44
+
45
+ ## 应用层从简单开始
46
+
47
+ 简单业务使用 XxxAppService,不使用冗长 XxxApplicationService;一个内聚能力的读写用例可共处,不预先拆 Command/Query/Handler。只定义实际需要的 Req/Resp、输入和结果对象,不为每层复制同构 DTO。
48
+
49
+ 规则、用例和变化原因增多时再按 create/check/publish 等用例拆 Handler/Command/Query,或按 firmware/rule/task 能力聚合。AppService 不能成为万能巨型服务;也不能仅因为有读写两种方法就引入完整 CQRS、双库或事件溯源。
50
+
51
+ 新 HTTP 类型默认 XxxReq/XxxResp;查询结果和快照仍可用 DeviceDetail/DeviceSnapshot 等业务名。存量公共名称按兼容需求处理,不批量强改。
52
+
53
+ ## api/internal 和依赖方向
54
+
55
+ - api 仅公开接口、DTO、必要枚举/错误契约/事件,不能引用 internal。细分遵循 [api 包组织](api-layout.md)。HTTP Controller 仍在 internal/web。
56
+ - web 调用 application,application 不依赖 web;数据访问统一依赖 Repository 接口,不依赖 Mapper 或持久化实现。
57
+ - Repository 接口默认 internal/repository;复杂模块沿用 domain/repository 也可,但不重复定义。业务语义与依赖方向优先于物理目录。
58
+ - RepositoryImpl/Mapper/Wrapper/ServiceImpl 在 persistence;实现按需继承 ServiceImpl 或组合 Mapper。简单 CRUD 允许模块内部复用 DO 是明确的模型隔离简化,见专项规范。
59
+ - domain 不依赖 MVC、MyBatis、HTTP Client 或 DO;复杂聚合通过业务行为保护不变量,持久化转换由实现负责。
60
+ - application 所需外部 Port 由消费方定义,integration 实现;配置/启动装配具体实现。
61
+ - 出现跨模块消费者时读取 [公开访问边界](api-layout.md),本文件不另定义跨模块规则。
62
+
63
+ web 按实际受众可分 admin/device/internal,命名不是安全隔离;所有入口仍需适用认证授权。
64
+
65
+ ## 拆分构建或部署
66
+
67
+ 先一个应用按业务包组织。必要时拆 platform-boot 组合根、platform-shared、module-device/module-ota 等,不按全局 web/application/domain 技术层横切。
68
+
69
+ 独立服务内部仍可模块化;完全没有同 JVM 消费者的服务可省略无用途 api 门面,以 HTTP/RPC/消息契约交互。包增长先判断业务能力与所有权,不按 Repository 数量或类数机械拆模块。
@@ -0,0 +1,36 @@
1
+ # Java 验证指南
2
+
3
+ 本文件只选择证据,不重新定义架构、格式或对象规则。小改动只检查相关行为;风险增大时按下表组合,未执行项明确说明。
4
+
5
+ ## 规则位置与对应证据
6
+
7
+ | 变化 | 权威规范 | 应观察的结果 |
8
+ |---|---|---|
9
+ | 排版、参数、局部逻辑 | [编码基线](coding-style.md) | 现有格式检查及相关行为通过,没有因凑参数产生转发层 |
10
+ | 模块/目录/仓储边界 | [结构](structure.md)、[Repository](repositories-and-modules.md) | 依赖不越界;简单模块保持 AppService,复杂度需要时再按用例/能力拆分 |
11
+ | 公开 api | [api 组织](api-layout.md) | 公开类型不递归泄露 internal,消费者兼容 |
12
+ | 跨模块/服务 | [集成](integrations.md) | 入站/出站清楚;调用方仅依赖契约,远程失败按协议处理 |
13
+ | 新对象或构建变化 | [数据对象](data-objects.md)、[类型选择](record-vs-class.md) | 构造不变量、相等性、默认值、复制与消费者保持预期 |
14
+ | PATCH/绑定/权限范围 | [输入契约](input-contracts.md) | 真实绑定覆盖缺失/null/非法值,可信条件不可被客户端覆盖 |
15
+ | 事务/SQL | [Spring](spring-boot.md)、[MyBatis-Plus](mybatis-plus.md) | 事务外重读、并发约束、真实更新路径符合预期 |
16
+ | 日志/审计 | [日志与审计](logging-and-audit.md) | 无敏感信息、无提前成功,可靠审计符合需求 |
17
+ | 提炼框架 | [框架边界](framework-boundaries.md) | 不依赖业务包/环境秘密,不静默降级事务 |
18
+ | 结构简化/模式选择 | [简洁设计](../common/clean-design.md) | 行为不退化,抽象解决现有问题,没有猜测性扩展 |
19
+
20
+ 链接按当前变化选择,不递归读取整个表。已有架构测试优先复用;未配置自动检查时报告手工依赖审查范围,不声称包名本身强制隔离。
21
+
22
+ ## 按风险挑选行为案例
23
+
24
+ - 两步写入中第二步失败:事务外查询确认没有部分提交。
25
+ - 并发扣最后一份库存:最多一次成功,库存不负。
26
+ - 同幂等键并发写入:符合契约,不重复产生业务记录。
27
+ - PATCH 未传与显式 null:分别保持原值或按契约清空/拒绝。
28
+ - 跨租户/越权输入:资源不可见或拒绝,可信范围未被覆盖。
29
+ - 软删除后重建:唯一性符合实际生命周期要求。
30
+ - 远程通知失败:本地状态与重试消息可追踪,不误称全链路回滚。
31
+
32
+ 纯领域行为用单元测试;绑定用实际框架链路;SQL/锁/方言需兼容数据库。Mock、编译、生成 SQL 和静态检查分别说明能证明什么,不能替代真实数据库执行。纯排版不新增镜像测试。
33
+
34
+ ## 收尾
35
+
36
+ 检查未提交变更与调用方,必要时干净构建,保护用户并行改动。说明实际测试、重要兼容影响与缺口;评审附位置、触发条件和影响,不为每次开发写长检查报告。
@@ -0,0 +1,9 @@
1
+ # Python 后端扩展入口
2
+
3
+ 检查 pyproject.toml、锁文件、Python 版本和同步/异步栈。按业务模块组织 API、用例、领域和持久化;不强制每层抽象基类。
4
+
5
+ 输入模型与 ORM 模型分开,区分可空和可缺省。类型注解不替代外部输入校验。数据库 Session/事务生命周期绑定用例或请求,不使用全局共享 Session;发生异常后明确回滚与释放。
6
+
7
+ 异步端点避免直接运行阻塞数据库/网络操作;同步与异步驱动选择遵循项目实际栈。金额使用 Decimal 并定义序列化;异常在 API 边界映射,不能吞掉失败。验证资源关闭、事务回滚和授权。
8
+
9
+ 实际使用 FastAPI、Django 或 SQLAlchemy 时在本目录新增对应指南,注明项目版本,并从 SKILL.md 按条件链接;不要同时加载所有框架。
@@ -0,0 +1,9 @@
1
+ # TypeScript 后端扩展入口
2
+
3
+ 保留已有框架和构建方式,检查 tsconfig、包版本和运行时。按业务模块组织 route/controller、use-case、model、adapter;不强制使用 NestJS 或装饰器。
4
+
5
+ 外部 JSON 需要运行时校验,TypeScript 类型断言不能提供校验。避免 any 穿透边界;明确 undefined、null 和未传字段。用 Promise 链路传播异常,独立任务应有失败处理。事务对象限于用例边界,不能默认异步上下文自动传递事务。
6
+
7
+ 数据库访问通过项目已有 Prisma、Drizzle 或其他适配器;不要为统一风格更换 ORM。金额、大整数和日期在 JSON 边界明确表示方式。验证事务失败、并发请求和资源授权。
8
+
9
+ 扩展时在本目录新增 nestjs.md、fastify.md 或持久化适配指南,并在 SKILL.md 添加带触发条件的链接;仅为实际选用的框架创建内容。
@@ -0,0 +1,16 @@
1
+ ---
2
+ name: yx-database-design
3
+ description: 设计或评审关系型数据库表、约束、索引、事务策略及可演进迁移;覆盖 MySQL/PostgreSQL 差异,ORM 封装交由后端架构 Skill。
4
+ ---
5
+
6
+ # 数据库设计
7
+
8
+ 先确认数据库产品/版本、现有 schema、迁移工具、数据规模、主要查询、读写并发和可用停机窗口。信息不足时给出明确假设,不默认具备在线 DDL 或零停机能力。
9
+
10
+ 1. 表结构、字段、唯一性和隔离需求读取 [模型与约束](references/modeling.md)。
11
+ 2. 索引、慢查询、锁和并发读取 [索引与事务](references/index-and-transactions.md)。
12
+ 3. 任何结构或数据演进读取 [迁移与兼容](references/migrations.md)。
13
+ 4. 按实际产品读取 [MySQL/PostgreSQL 差异](references/engines.md) 的相关部分。
14
+ 5. 如果变化影响外部字段或查询语义,显式加载 `yx-api-design`;ORM 映射/调用实现属于 `yx-backend-architecture`,不得假定另一个 Skill 自动继承。
15
+
16
+ 交付 DDL/迁移建议、关键查询与索引对应关系、兼容顺序、风险及验证结果。生成迁移文件不等于执行迁移;是否执行按用户授权和目标环境判断,不能因加载本 Skill 自动操作生产库。
@@ -0,0 +1,17 @@
1
+ # 数据库产品差异
2
+
3
+ 以下是设计检查点,不是跨版本 SQL 保证。编写 DDL 前以实际产品、版本和配置核实。
4
+
5
+ ## MySQL
6
+
7
+ 确认存储引擎、字符集、排序规则、时区及 SQL mode。自增、生成列、JSON 索引和 CHECK 的支持随版本变化。唯一索引中 NULL 的行为会影响软删除活跃键方案;若用生成列表达活跃键,验证多次删除重建与组合键场景。
8
+
9
+ InnoDB 隔离与锁行为受隔离级别、索引访问路径和查询形式影响。DDL 可能隐式提交;不能假定迁移工具外层事务会回滚所有 DDL。在线 DDL 仍可能等待元数据锁,应在代表性环境测试。
10
+
11
+ ## PostgreSQL
12
+
13
+ 可以评估部分唯一索引表达仅活跃记录唯一,但需核对查询谓词与工具支持。唯一约束的 NULL 处理有版本与配置差异。timestamp with time zone 表达时间点,不保存原始地区时区名;业务需要原始时区时单独记录。
14
+
15
+ 多数 DDL 可事务化,但并非所有操作都允许在事务块中执行;例如并发建索引需按迁移工具配置处理,失败后检查残留无效索引。大表变更、锁超时和 vacuum 影响需要独立评估。
16
+
17
+ 不要把 MySQL 的自增、反引号、JSON 运算或分页语法直接复制到 PostgreSQL,反之亦然。数据库方言差异应在集成测试中验证。
@@ -0,0 +1,11 @@
1
+ # 索引、事务与并发
2
+
3
+ 每个索引对应具体查询的过滤、连接或排序需求,记录读收益与写入/空间成本。复合索引顺序依据实际访问模式、等值/范围条件及排序决定,不能机械套用“选择性最高永远在前”。检查已有索引和冗余覆盖。
4
+
5
+ 使用代表性数据和参数检查执行计划、扫描行数、回表与排序;EXPLAIN ANALYZE 可能真正执行语句,修改语句只在安全测试环境评估。空表计划不能代表生产表现。函数、隐式类型转换和排序规则可能影响索引使用。
6
+
7
+ 大列表采用稳定排序并加入唯一键消除并列;深分页评估 keyset 游标及一致性需求。查询上限、批次大小和超时需明确。
8
+
9
+ 选择隔离级别前描述需要防止的异常。事务不能自动消除丢失更新、超卖或所有幻读。条件更新检查影响行数;悲观锁保持一致加锁顺序并限制持锁时间;乐观锁冲突需要业务处理。
10
+
11
+ 死锁和序列化失败可以在有限预算内重试整个可重试事务,外部副作用须去重或推迟。不要仅重试最后一条 SQL。集成验证包括并发唯一冲突、边界库存和事务回滚。