@lark-apaas/coding-steering 0.1.60 → 0.1.61-alpha.20260930060131

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@lark-apaas/coding-steering",
-  "version": "0.1.60",
+  "version": "0.1.61-alpha.20260930060131",
   "description": "Stack-specific steering content for miaoda-coding templates",
   "type": "module",
   "files": [
     "steering"
   ],
+  "scripts": {
+    "lint:md": "markdownlint 'steering/**/*.md' --ignore 'steering/**/skills/**' --ignore 'steering/**/skills_common/**' --ignore 'steering/**/skills_local/**'"
+  },
   "devDependencies": {
     "markdownlint-cli": "^0.47.0"
   },
@@ -17,8 +20,5 @@
     "miaoda",
     "coding-steering"
   ],
-  "license": "MIT",
-  "scripts": {
-    "lint:md": "markdownlint 'steering/**/*.md' --ignore 'steering/**/skills/**' --ignore 'steering/**/skills_common/**' --ignore 'steering/**/skills_local/**'"
-  }
-}
+  "license": "MIT"
+}

package/steering/nestjs-react-fullstack/skills/code-fix/SKILL.md

@@ -81,35 +81,15 @@ import { ListPlus, Cake, Home, Building, Twitter } from "lucide-react";
 1. 整个项目 `grep "export.*\bX\b"` 找所有同名 export 一并处理，**不能只改单点**——首次出 bug 时同类常已在多处复制粘贴
 2. 预防规则（跨子组件常量前缀化、行内/桶导出二选一）见 `coding-guide` 的「TypeScript 规范 · 命名约定」与「文件命名约定 · 导入导出」
 
-### 前端 Dto 类型使用错误
-**问题描述**：代码中使用的 Dto 类型属性与实际定义不一致，导致 TypeScript 类型检查报错
+### 类型错误按实际来源分流
 
-**核心原则**：遇到类型错误，先查 `@client/src/api/gen/types.gen.ts` 确认定义，再修改代码
+遇到类型不匹配、缺属性或导入失败，先从报错使用点检查实际 import 与返回签名，不能因名称含 Dto 就默认查生成类型：
 
-**错误示例**：
-- 示例1： 赋值时缺失必需属性
-```
-Property 'dueDate' is missing in type {...} but required in type 'CreateBorrowRecordDto'
-```
-
-- 示例2：访问不存在的属性
-```
-Property 'avatar' does not exist on type 'LotteryParticipantResponseDto'
-```
+1. **生成 OpenAPI 类型**：实际 import 溯源到 `@client/src/api/gen` 时，读取 `@client/src/api/gen/types.gen.ts` 的真实导出及字段，修调用代码；不要手改生成文件。
+2. **业务 `/api` 或 shared 类型**：按 `coding-guide` 的「shared/api.interface.ts 规范」读共享声明、server controller/service 返回、client API helper、hook 签名和调用/状态消费者。合同发生变化时搜全部引用，一次迁移生产者和消费者；不要把业务类型误当生成 DTO。
+3. **数据库字段**：读当前 `server/database/schema.ts` 的生成类型；涉及 DDL 按数据库操作 skill 更新并重新生成后再读，不靠手写或修改生成 schema 消错。
 
-- 示例3：导入不存在的类型
-```
-Module '"@client/src/api/gen"' has no exported member named 'DiscrepancyResponseDto'
-```
-**解决步骤**：
-1. 在 `@client/src/api/gen/types.gen.ts` 中搜索目标Dto实际定义
-2. 确认类型名称是否正确，明确完整定义
-
-**检查清单**：
-- [ ] 已查看 `@client/src/api/gen/types.gen.ts` 中的类型定义
-- [ ] 已对比代码使用与实际定义的差异
-- [ ] 已根据实际定义修正代码
-- [ ] 已验证修改后类型使用正确
+TS2345/2339/2353/2322/2741 均先查报错表达式与真实声明：缺必需键要补齐，额外键或不存在的属性要按真实合同纠正。修完按 `coding-guide`「质量保障流程」重跑相关前后端 typecheck 和原项目 lint，禁止靠类型断言或跳过检查掩盖不一致。
 
 ## 业务日期错位
 

package/steering/nestjs-react-fullstack/skills/coding-guide/SKILL.md

@@ -117,6 +117,7 @@ shared/
 - 编写前后端代码前，**必须先读取该文件**，严格按照定义实现。禁止凭记忆编写
 - **严格使用已定义的属性名和类型**，禁止使用不存在的属性名。需要新增字段必须先在此文件添加
 - **import 类型前必须确认实际导出**：先读取文件确认类型名称存在且拼写一致，禁止臆造类型名
+- **合同变更先读后改**：本轮改变 API 响应、hook 参数或对象字面量的结构时，首次 Edit 前沿实际 import 和签名读 `shared/api.interface.ts`、server controller/service 返回、client API helper 返回类型、hook 签名及调用/状态消费者；搜索所有引用。一次迁移要同时更新源合同、实现、helper、hook 和所有受影响消费者；属性拼写、多余键或缺失必需键均以真实声明为准，不凭记忆造字段。未改变合同的日常修改无需全链迁移。
 - 属性统一 camelCase（禁止 snake_case），server 端 schema 的 snake_case 不应泄漏到接口类型
 - shared 目录是前后端共享文件，**禁止反向引用** `@server/*`、`@client/*` 等路径别名
 - **请求 DTO 中的 shared 字符串联合别名**：`shared/api.interface.ts` 是前后端契约权威。带 `class-validator` 的 NestJS 请求 DTO 字段若对应 shared 字符串字面量联合 `type` alias，不把 imported alias 直接写在 DTO 属性上；改用等价 inline literal union + `@IsString()` + `@IsIn([...])`，DTO class 仍 `implements` shared 请求接口。
@@ -233,6 +234,7 @@ shared/
 
 - **日志源**：服务端读 `server-devserver` / `server` 日志，客户端读 `client-devserver` 日志
 - **dev 服务无响应**：`pkill -f "npm run dev"` 触发重启
+- **类型错误与复查**：TS2345/2339/2353/2322/2741 从报错行追到生产者及类型声明，再修受影响消费者；不能以 `as any`、假字段或跳过检查消错。修复后重跑项目的 `npm run type:check:client`、涉及服务端时的 `npm run type:check:server` 和原有 `npm run lint`；若 lint 命中无权修改的平台受保护路径，保留原错并移交平台维护者，不宣称通过。
 
 ---
 
@@ -516,6 +518,7 @@ await db.select().from(users).where(eq(users.adminUser, userId));
 4. **前后端一致性**（CRITICAL）：
    - 前端 API 调用的 HTTP method 和 path **必须**与后端 Controller 装饰器完全匹配（`GET≠POST` → 405）
    - 后端 Service 返回值结构**必须**与 `shared/api.interface.ts` 中定义的响应类型完全匹配（禁止后端直接返回数组而 shared 定义为 `{items: T[]}`）
+   - **迁移示例（业务自有类型，以实际声明为准）**：若 helper 签名从 `fetchSales(): Promise<Sale[]>` 变为 `fetchSales(): Promise<{ sales: Sale[]; pendingSessions: Session[] }>`，hook 应取 `const result = await fetchSales(); setSales(result.sales)`，不能继续 `setSales(result)`；需要会话数据的状态/调用方也按新字段迁移。
 5. **路由注册验证**：创建新 Controller 后必须用接口测试工具验证路由是否生效。**遇到 404 排查路径**：① 检查 `@Controller(...)` 是否以 `api/` 或 `openapi/` 开头 ② 检查 Module 是否在 `app.module.ts` 注册 ③ 检查静态路由是否在动态路由 `/:id` 之前
 6. **@Query/@Param 类型转换**：默认 string，必须在 controller 层手动转换（如 `parseInt(limit, 10)`）
 7. **写接口鉴权**：POST/PUT/PATCH/DELETE 不一刀切。个人/后台/依赖当前用户的写入加 `@NeedLogin()`；未登录访客表单/报名/反馈可公开，但每张被写入的 RLS 表都要有 `FOR INSERT TO anon WITH CHECK (true)` 或等价 Drizzle `withCheck`，并用未登录 HTTP POST 验证。`FOR SELECT TO anon` 只读、`FOR INSERT TO authenticated` 只登录态；公开只读页的增删改仍按登录态处理。