@lark-apaas/coding-steering 0.1.44-alpha.20260902103329 → 0.1.44

package/package.json

@@ -1,14 +1,11 @@
 {
   "name": "@lark-apaas/coding-steering",
-  "version": "0.1.44-alpha.20260902103329",
+  "version": "0.1.44",
   "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"
   },
@@ -20,5 +17,8 @@
     "miaoda",
     "coding-steering"
   ],
-  "license": "MIT"
-}
+  "license": "MIT",
+  "scripts": {
+    "lint:md": "markdownlint 'steering/**/*.md' --ignore 'steering/**/skills/**' --ignore 'steering/**/skills_common/**' --ignore 'steering/**/skills_local/**'"
+  }
+}

package/steering/nestjs-react-fullstack/skills/client-builtins-file-storage-service/SKILL.md

@@ -19,7 +19,7 @@ match-template-name: nestjs-react-fullstack
 项目提供了dataloom SDK的文件服务，用于文件的上传，下载，删除，列出bucket中文件，创建临时签名url等能力。
 
 ## 使用注意
-- **入口边界**：本 SDK 是**应用前端代码**读写应用存储的唯一入口。Agent 自己在对话 / 开发中上传、灌数据或调试文件请用 `miaoda file` CLI（见 `miaoda-file` skill）——二者操作同一个应用存储桶，但 **`miaoda file` CLI 禁止写进页面代码**，页面里一律用本 SDK。
+- **入口边界**：本 SDK 是**应用前端代码**读写应用存储的唯一入口。Agent 自己在对话 / 开发中上传、灌数据或调试文件，先加载应用文件存储操作 skill（按「应用文件存储 / 文件上传 / 文件下载」召回），用其 CLI 命令操作，具体命令一律以该 skill 为准——二者操作同一个应用存储桶，但**该 CLI 命令只供 Agent 在沙箱终端使用，禁止写进页面代码**，页面里一律用本 SDK。
 - @lark-apaas/client-toolkit/dataloom 这个SDK只适用于前端调用，禁止在服务端调用
 - 上传成功后，最重要的返回值是 `data.download_url`。需要将此URL保存到你的业务数据库中
 - **⚠️ 场景区分（重要）**：`dataloom.storage` 仅适用于需要持久化存储文件或获取 `download_url` 保存到数据库的场景。如果文件仅作为插件输入（传给 `capabilityClient`），**必须直接传 File/Blob 对象，禁止先走 dataloom 上传再传 URL**；插件调用（capability）不属于 dataloom，详见 plugin-guide

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

@@ -111,6 +111,12 @@ Module '"@client/src/api/gen"' has no exported member named 'DiscrepancyResponse
 - [ ] 已根据实际定义修正代码
 - [ ] 已验证修改后类型使用正确
 
+## 业务日期错位
+
+**问题描述**：本地凌晨、周一或月初附近，日期落到前一天、上周或上月。
+
+**解决步骤**：按 `coding-guide` 的「业务日期」一节改——自然日统一走业务时区 helper；精确时刻不动。
+
 ## JSX 和语法错误
 
 ### 特殊字符转义处理

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

@@ -340,6 +340,12 @@ await db.select().from(users).where(eq(users.adminUser, userId));
 
 - **禁止删类型注解消除报错**（`as unknown as T` 同禁）：典型症状是「改完 service，错误跑到 controller 了」——错误没有转移，是校验点被往外推了一层；推到最外层删完，报错归零而契约失守。
 
+### 业务日期
+
+需求里的日期是**自然日**（哪一天 / 哪一周 / 哪一月）而不是精确时刻时，按业务时区计算，未指定时默认 `Asia/Shanghai`。
+
+项目里放一个 helper 统一产出 `day` / `month` / `weekStart` / `shiftDay`；服务端写入、统计聚合、前端展示都比较它的返回值。
+
 ### PostgreSQL SQLSTATE / Drizzle 异常处理（CRITICAL）
 
 - 可预期幂等 / 冲突优先用数据库原子语义（`ON CONFLICT`、`UPDATE ... WHERE ... RETURNING`），不要靠异常流兜底。

package/steering/nestjs-react-fullstack/skills/server-builtins-file-storage-service/SKILL.md

@@ -11,7 +11,7 @@ match-template-name: nestjs-react-fullstack
 在 NestJS 服务端代码中使用 `FileService` 进行文件上传、下载、删除和管理。
 
 > **使用注意**: 仅用于服务端文件处理场景，非必要文件上传下载场景请使用前端 `client-builtins-file-storage-service` skill。
-> **入口边界**：本 SDK 是**服务端代码**读写应用存储的入口；Agent 在对话 / 开发中自己上传或调试文件用 `miaoda file` CLI（见 `miaoda-file` skill）。二者与本 SDK 操作同一个应用存储桶，但 **`miaoda file` CLI 禁止写进服务端代码**。
+> **入口边界**：本 SDK 是**服务端代码**读写应用存储的入口；Agent 在对话 / 开发中自己上传或调试文件，先加载应用文件存储操作 skill（按「应用文件存储 / 文件上传 / 文件下载」召回），用其 CLI 命令操作，具体命令一律以该 skill 为准。二者与本 SDK 操作同一个应用存储桶，但**该 CLI 命令只供 Agent 在沙箱终端使用，禁止写进服务端代码**。
 
 ## 使用场景
 

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

@@ -116,6 +116,12 @@ Module '"@client/src/api/gen"' has no exported member named 'DiscrepancyResponse
 - [ ] 已根据实际定义修正代码
 - [ ] 已验证修改后类型使用正确
 
+## 业务日期错位
+
+**问题描述**：本地凌晨、周一或月初附近，日期落到前一天、上周或上月。
+
+**解决步骤**：按 `coding-guide` 的「业务日期」一节改——自然日统一走业务时区 helper；精确时刻不动。
+
 ## JSX 和语法错误
 
 ### 特殊字符转义处理

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

@@ -286,6 +286,12 @@ await db.select().from(users).where(eq(users.adminUser, userId));
 
 - **`customTimestamptz` 跨网络后是 string**：service 内查询返回 `Date`，但 API 响应经 JSON 序列化后前端拿到 ISO string。`shared/api.interface.ts` 中 timestamptz 字段声明为 `string`，前端需要 Date 时手动 `new Date(value)`。
 
+### 业务日期
+
+需求里的日期是**自然日**（哪一天 / 哪一周 / 哪一月）而不是精确时刻时，按业务时区计算，未指定时默认 `Asia/Shanghai`。
+
+项目里放一个 helper 统一产出 `day` / `month` / `weekStart` / `shiftDay`；服务端写入、统计聚合、前端展示都比较它的返回值。
+
 ### 数据库使用强约束
 
 - 仅通过 schema.ts 暴露的客户端和类型读写，禁止手写 SQL/临时类型
@@ -443,7 +449,7 @@ NestJS 自己不读 env。直连 NestJS 端口 → header 缺失 → `req.userCo
 
 - **框架**: React 19 + TypeScript
 - **路由**: React Router DOM v6
-- **样式**: tailwindcss（语义化 token）为主，复杂 CSS 用 CSS Modules（`*.module.css`），动态计算值用行内 `style`
+- **样式**: styled-jsx + tailwindcss（语义化 token）。styled-jsx 使用前提见下方"样式开发"
 - **UI 组件库**: shadcn/ui — Use components for functionality, heavily style them
 - **图表**: ReactECharts，**开发前必须调用 `/charts-skill`**
 - **图标**: Lucide React（唯一图标库，禁止 Emoji 和其他图标库）
@@ -535,7 +541,7 @@ import { axiosForBackend } from '@lark-apaas/client-toolkit/utils/getAxiosForBac
 ```
 需要写样式？
 ├─ 基础布局/间距/颜色 → Tailwind ✅
-├─ 复杂动画/伪元素/高级CSS → CSS Modules（`*.module.css`）✅
+├─ 复杂动画/伪元素/高级CSS → styled-jsx ✅
 └─ JS动态计算值 → 行内 style ✅
 ```
 
@@ -548,12 +554,10 @@ import { axiosForBackend } from '@lark-apaas/client-toolkit/utils/getAxiosForBac
 - **arbitrary values 中空格用下划线**：`from-[hsl(215_60%_18%)]` 非 `from-[hsl(215 60% 18%)]`
 - `tailwind-theme.css` 自定义属性用 `hsl(H, S%, L%)` 格式（非 `23 10% 23%`）
 
-### CSS Modules 规范
+### styled-jsx 规范
 
-- 文件名：`ComponentName.module.css`，与组件同目录
-- 导入用 `import styles from './ComponentName.module.css'`，通过 `className={styles.foo}` 引用
-- 类名用 camelCase，避免使用连字符（`styles.myClass` 而非 `styles['my-class']`）
-- 全局样式（如动画 keyframes、CSS 变量）放在 `client/src/index.css` 或 `tailwind-theme.css`
+- **技术栈一致性**：仅在已配置 styled-jsx 插件的项目中使用。`package.json` 无 `styled-jsx` 依赖则**禁用**，否则运行时 SyntaxError
+- **禁止动态插值**：`<style jsx>` 内禁止 `${...}` 等表达式（会卡死）。动态值放 CSS 变量，用 `var(--xxx)` 引用
 
 ### 布局/排版
 

package/steering/vite-react/tech.md

@@ -73,4 +73,7 @@ const url = flags[`/src/assets/flags/${code}.svg`]
 1. **shadcn-ui 组件不直接改源码**——需要变化时通过 `className` / `variant` props 控制。
 2. **样式优先用 Tailwind utility**，避免写 CSS module。
 3. **表单始终用 react-hook-form + zod**——不要直接操作 input value。
+   字段类型由 zod schema 推导、`defaultValues` 覆盖全字段、运行时校验用 `zodResolver`；
+   提交到必填 API/service Request 时，submit 的类型边界用业务 Request 而不是
+   `z.infer`（做法见 `forms-skill`）。
 4. **图表 ECharts 优先 echarts-for-react**——React 19 严格模式下注意 echarts instance 的初始化时机。