super-bill-software

super-bill Software

1. 调用边界

• 本 Skill 只负责软件领域分析和实现规则，不能绕过主 super-bill。
• 正式需求先用 superpowers；架构与版本选型先用 Context7；涉及 UI 必须用 ui-ux-pro-max-skill。
• 没有小白可读的需求/架构文档和用户批准，禁止写生产代码。
• 开发必须在非 main 分支；开发完成后交给独立测试 Agent。
• 满足主 Skill「小改动快速通道」条件时，可在当前会话直接实现并自检，不派 subagent；本 Skill 第 4 节数据库强制规则、时区语义和配置外置要求不豁免。改动涉及 schema、迁移、聚合语义或 API 破坏性变更时必须退回完整流程。

2. 能力范围

• 产品需求、业务流程、后台、管理端、数据大屏和报表。
• Python 异步服务、FastAPI、API 契约、任务调度、消息处理。
• MySQL/PostgreSQL、SQLAlchemy ORM、Redis、数据建模与迁移。
• React 19 + TypeScript、Vite/Next.js、Tailwind CSS、ECharts、bun 项目管理和前后端联调。
• FastMCP streamable-http 服务、IoT 桥梁服务和 AI 应用后端。
• 高并发、高可用、链路追踪、日志、指标、告警和工程规范。

3. 技术选择原则

优先级：

用户明确要求
> 现有项目约束
> 当前官方兼容性和安全要求
> super-bill 默认偏好

默认偏好，新项目和项目改造必须遵守：

• Web/API：FastAPI + asyncio + lifespan，并使用 Pydantic v2 做输入输出校验。
• Python：uv安装,3.11+，适用时使用 asyncio.TaskGroup 和结构化并发。
• 对外 HTTP：aiohttp；现有项目已统一使用 httpx 等方案时遵循现有架构。
• 定时任务：异步 APScheduler；分布式或高可靠任务按需求评估 Taskiq/Celery/队列方案。
• Redis：redis-py 异步客户端。
• MQTT：优先 aiomqtt。
• PostgreSQL 驱动：psycopg 3 异步能力。
• MySQL 驱动：现有项目兼容时优先 asyncmy；engine、连接池和 session factory 由 lifespan 管理。
• 前端：React 19 + TypeScript strict + Vite 7 SPA；需要 RSC/SEO 时用 Next.js 16 App Router。现有非 React 项目遵循原架构，不强行重写。完整技术栈和代码模板见 assets/react-frontend.md。
• 前端包管理与脚本：bun（bun create vite、bun add、bun test）；Monorepo 用 Turborepo + bun workspace。
• 样式与组件：Tailwind CSS v4 + shadcn/ui（Base UI/Radix）；中后台高密度 Table/Form/DatePicker 用 Semi Design；禁止两套主按钮体系并存。
• 前端数据与状态：TanStack Query（服务端状态）+ Zustand v5（仅 UI 状态）+ React Hook Form + Zod；请求统一走 ky 封装，禁用裸 fetch/axios。
• 路由与图标：TanStack Router（Vite）/ App Router（Next.js）；lucide-react 为唯一图标源。
• AI 流式 Markdown：只用 Vercel Streamdown，传输用原生 fetch + ReadableStream，禁止 EventSource，SSE 不放进 queryFn；必须配 Tailwind @source 扫描 streamdown 发行文件。
• 前端测试：Vitest + Testing Library + Playwright + axe 进 CI；Storybook 8 做组件文档。
• 图表：ECharts。

选择前必须用 Context7 核对当前版本 API、生命周期、弃用项和兼容性。

4. 数据库强制规则

除非用户明确指定其他方案架构，业务数据库必须遵守：

1. 使用 SQLAlchemy 2.x ORM，不能默认用裸 SQL、同步 ORM 或另一套 ORM 替代。
2. 使用 async engine、async_sessionmaker 和 AsyncSession。
3. engine 与 session factory 必须在应用 lifespan 中创建和释放。
4. Redis、aiohttp ClientSession、scheduler、MQTT client 等共享资源也应由 lifespan 统一管理。
5. 具体 AsyncSession 必须请求级或任务级隔离，禁止全局共享同一个 session。
6. 使用异步依赖或异步上下文管理器获取 session。
7. 事务必须有明确 commit/rollback 边界；异常时回滚并保留可追踪日志。
8. 不把 session、连接或事务跨并发任务共享。
9. 服务器现有 MySQL 且满足需求时优先复用，不擅自新建另一套数据库服务。
10. 开发数据库与测试数据库必须物理或逻辑隔离，禁止自动化测试写入开发库、生产库。