create-dwy 0.5.0 → 0.6.0

package/templates/claude-global/rules/dwy-tech-stack.md

@@ -0,0 +1,60 @@
+---
+description: 跨栈技术选型强制约束(FastAPI/Vue3/Flutter/UV/pnpm/Docker/S3 等,全局加载)
+---
+
+# 跨栈技术选型强制约束
+
+每个领域只有一个方案,AI 不得选替代,不得"建议改用 XX"。
+
+## 后端
+
+| 领域 | 唯一方案 | 禁止替代 |
+|------|---------|---------|
+| Web 框架 | FastAPI | Django, Flask, Tornado, Sanic |
+| ORM | SQLAlchemy 2.0 (异步) | Tortoise ORM, Peewee, Django ORM |
+| 关系数据库 | PostgreSQL | MySQL, MariaDB, SQLite(生产) |
+| 缓存 / 消息队列 | Redis | Memcached, RabbitMQ, Kafka |
+| 异步任务 | ARQ (eapi[tasks]) | Celery, Dramatiq, Huey |
+| 数据库迁移 | Alembic | 手动 DDL, Django migrations |
+| 包管理 | UV | pip, Poetry, Pipenv |
+| 密码哈希 | bcrypt (eapi security) | argon2, scrypt, 自实现 |
+| JWT | python-jose (eapi security) | PyJWT, 自实现 |
+| 数据校验 | Pydantic v2 | marshmallow, attrs, 手动校验 |
+| 基础设施层 | dwyeapi | 自造框架、手写基础设施 |
+| Linter/Formatter | Ruff | Black, isort, flake8, pylint |
+
+## 前端(Web)
+
+| 领域 | 唯一方案 | 禁止替代 |
+|------|---------|---------|
+| 框架 | Vue 3 (Composition API) | React, Svelte, Angular, Vue 2 |
+| 构建工具 | Vite | Webpack, Rollup, esbuild 直接用 |
+| 组件库 | @dwydev/eui | Element Plus, Ant Design Vue, Naive UI |
+| 工具库 | @dwydev/ekit | 手写 request/storage/validators |
+| 状态管理 | Pinia (Setup Store) | Vuex, 手动 reactive/provide |
+| 样式 | Tailwind CSS 4 | Sass/Less 手写、CSS Modules、UnoCSS |
+| 包管理 | pnpm | npm, yarn |
+| 项目结构 | pnpm monorepo (workspace) | Lerna, Nx, Turborepo |
+| 表单校验 | vee-validate + zod | 手动 v-model 校验 |
+| 路由 | Vue Router 4 | — |
+| 测试 | Vitest | Jest |
+
+## 移动端 / 桌面端
+
+| 领域 | 唯一方案 | 禁止替代 |
+|------|---------|---------|
+| 框架 | Flutter | React Native, Kotlin Multiplatform, MAUI |
+| 状态管理 | Riverpod | GetX, Bloc, Provider, MobX |
+| HTTP 客户端 | Dio | http, Chopper, Retrofit |
+| 路由 | GoRouter | auto_route, Routemaster |
+| 本地存储 | shared_preferences + flutter_secure_storage | Hive, Isar, sqflite(非必要时) |
+| 代码生成 | riverpod_generator + freezed + json_serializable | 手写 fromJson/toJson |
+
+## 基础设施
+
+| 领域 | 唯一方案 |
+|------|---------|
+| 容器化 | Docker + Docker Compose |
+| 对象存储(开发) | MinIO (S3 协议) |
+| 对象存储(生产) | 任何 S3 兼容云服务 |
+| 时序数据库(量化金融) | DolphinDB |

package/templates/claude-global/rules/dwy-vue-api.md

@@ -0,0 +1,146 @@
+---
+description: Vue 前端网络层(ekit createRequest + 拦截器插件)
+paths:
+  - "**/api/**/*.ts"
+  - "**/api/**/*.vue"
+  - "**/api/client.ts"
+---
+
+# Vue 前端网络层规范
+
+## 六、API 请求规范
+
+### 强制规则
+
+- API 文件按**业务域拆分**（`api/user.ts`、`api/exam.ts`）
+- 每个 API 函数**独立导出**，不使用 default export
+- 请求参数和响应使用**类型标注**
+- **禁止**在组件中直接创建 axios 实例或调用 `fetch`
+
+### API 文件结构
+
+```typescript
+// api/user.ts
+import request from '@/utils/request'
+import type { UserInfo, UserCreate, UserUpdate } from '@/types/user'
+
+export function getUsers(params?: { page?: number; page_size?: number }) {
+  return request.get<{ items: UserInfo[]; total: number }>('/users', { params })
+}
+
+export function getUser(id: number) {
+  return request.get<UserInfo>(`/users/${id}`)
+}
+
+export function createUser(data: UserCreate) {
+  return request.post<UserInfo>('/users', data)
+}
+
+export function updateUser(id: number, data: UserUpdate) {
+  return request.put<UserInfo>(`/users/${id}`, data)
+}
+
+export function deleteUser(id: number) {
+  return request.delete(`/users/${id}`)
+}
+```
+
+### 请求实例配置
+
+```typescript
+// utils/request.ts
+import axios from 'axios'
+
+const request = axios.create({
+  baseURL: '/api',
+  timeout: 30000,
+})
+
+// Token 注入
+request.interceptors.request.use((config) => {
+  const token = localStorage.getItem('token')
+  if (token) {
+    config.headers.Authorization = `Bearer ${token}`
+  }
+  return config
+})
+
+// 401 处理
+request.interceptors.response.use(
+  (response) => response,
+  (error) => {
+    if (error.response?.status === 401) {
+      localStorage.removeItem('token')
+      window.location.href = '/login'
+    }
+    return Promise.reject(error)
+  },
+)
+
+export default request
+```
+
+### 禁止的写法
+
+```typescript
+// ❌ 在组件中直接调用
+const res = await axios.get('/api/users')
+
+// ✅ 通过 API 模块调用
+import { getUsers } from '@/api/user'
+const res = await getUsers()
+
+// ❌ API 函数使用 default export
+export default { getUsers, createUser }
+
+// ✅ 每个函数独立导出
+export function getUsers() { ... }
+export function createUser() { ... }
+```
+
+---
+
+## 网络层规范（ekit 统一方案）
+
+### Vue 前端
+
+**唯一方式：** ekit `createRequest()` + 插件。
+
+```typescript
+// api/client.ts
+import { createRequest } from '@dwydev/ekit'
+
+export const request = createRequest({
+  baseURL: import.meta.env.VITE_API_BASE_URL,
+  plugins: [
+    tokenPlugin(),         // 注入 Authorization header
+    refreshTokenPlugin(),  // 401 自动刷新
+    unwrapPlugin(),        // 解包响应 → data
+  ],
+})
+
+// api/user.ts — 按业务域拆分
+export function getUsers(params: { page: number; page_size: number }) {
+  return request.get('/users', { params })
+}
+
+export function createUser(data: UserCreate) {
+  return request.post('/users', data)
+}
+```
+
+**禁止：** `axios.create()`、`fetch()`、`new XMLHttpRequest()`
+
+### 响应解包
+
+前端的解包逻辑必须与后端 eapi response 格式对齐：
+
+```
+后端返回: { code: "SUCCESS", message: "success", data: {...}, timestamp: ... }
+                                                      ↓ unwrap
+前端拿到: {...}  (直接是 data 的内容)
+```
+
+分页响应解包后拿到 `{ items, total, page, page_size }`（保持 snake_case 对齐后端 JSON）。
+
+业务失败时（`code !== "SUCCESS"`），unwrapPlugin 抛出的 HttpError 携带 `businessCode` 和 `apiResponse`。业务 catch 中用 `isApiBusinessError(err)` 做类型守卫后按 `err.businessCode` 分支（如 `NOT_FOUND` / `VALIDATION_ERROR` / `PERMISSION_DENIED`）；`VALIDATION_ERROR` 场景可用 `extractValidationErrors(err)` 直接给 vee-validate 的 `setErrors` 回填。