infometa Full-Stack Development Practices
MANDATORY WORKFLOW
触发此 skill 后，必须按以下步骤执行：
Step 0: Gather Requirements
确认以下信息（如用户已指定则跳过）：
- Stack: 后端+前端语言/框架
- Service type: API-only / 全栈单体 / 微服务
- Database: SQL / NoSQL
- Integration: REST / GraphQL / tRPC / gRPC
- Real-time: SSE / WebSocket / Polling /不需要
- Auth: JWT / Session / OAuth / 不需要
Step 1: Architectural Decisions
基于需求做出并声明决策（每个决策一句话）：
| 决策项 | 参考 |
|---|---|
| 项目结构 | Feature-first（推荐）vs Layer-first |
| API 客户端 | Typed fetch / React Query / tRPC / OpenAPI |
| 认证策略 | JWT + refresh / session / 第三方 |
| 实时方案 | Polling / SSE / WebSocket |
| 错误处理 | Typed error hierarchy + global handler |
Step 2: Scaffold with Checklist
后端服务 Checklist：
- Feature-first 项目结构
- 配置集中管理，环境变量启动时验证（fail fast）
- 类型化错误层级（非通用 Error）
- 全局错误处理中间件
- 结构化 JSON 日志 + request ID
- 数据库 Migration +连接池
- 输入验证（Zod / Pydantic / Go validator）
- 认证中间件
- 健康检查端点（
/health,/ready） - 优雅关闭（SIGTERM）
- CORS 配置（显式 origin）
- 安全头（helmet等）
-
.env.example（不含真实密钥）
前后端集成 Checklist：
- 类型化 API Client
- Base URL 从环境变量读取
- Auth token 自动附加
- API 错误映射为用户友好消息
- Loading 状态处理
- 跨边界类型安全
- CORS 显式配置
- Refresh token 流程
Step 3: Implement
按照 references 中的模式编写代码。每完成一个模块立即验证。
Step 4: Verify
# 构建检查
cd server && npm run build
cd client && npm run build
# 冒烟测试
curl http://localhost:3000/health
# 集成检查：前端能连通后端
Step 5: Handoff
📦 交付：
- 实现的功能和端点列表
- 启动命令
- 已知限制 / 下一步建议
- 关键文件列表
7条铁律
- 按Feature 组织代码，不按技术层
- Controller 不含业务逻辑
- Service 不导入 HTTP 请求/响应类型
- 所有配置来自环境变量，启动时验证
- 所有错误类型化、结构化返回
- 所有输入在边界处验证
- 结构化 JSON 日志 + request ID
详细参考文档（按需查阅）
需要具体代码模式和深入指导时，查阅以下参考文档：
| 主题 | 参考文件 |
|---|---|
| 项目结构、三层架构、DI 模式 | references/architecture-patterns.md |
| API 设计（URL、状态码、分页） | references/api-design.md |
| 认证流程（JWT、刷新、RBAC） | references/auth-flow.md |
| 数据库 Schema、索引、迁移 | references/db-schema.md |
| Django 最佳实践 | references/django-best-practices.md |
| 环境管理与CORS | references/environment-management.md |
| 发布检查清单 | references/release-checklist.md |
| 技术选型决策 | references/technology-selection.md |
| 测试策略 | references/testing-strategy.md |
反模式速查
| ❌ 不要 | ✅ 应该 |
|---|---|
| 业务逻辑写在路由/Controller | 移到 Service 层 |
process.env 散落各处 |
集中配置模块 |
console.log |
结构化 JSON Logger |
通用 Error('oops') |
类型化错误类 |
| Controller 直接查DB | Repository 模式 |
| 无输入验证 | 边界验证（Zod/Pydantic） |
| 静默吞错 | 日志 + 重抛或返回错误 |
| 无健康检查 | /health + /ready |
| 硬编码配置密钥 | 环境变量 |
| 无优雅关闭 | 处理 SIGTERM |
| 前端硬编码 API URL | 环境变量 |
| JWT 存localStorage | Memory + httpOnly cookie |
| 展示原始 API错误 | 映射为用户友好消息 |
| 大文件走 API Server | Presigned URL 直传 |