doctor-bill-software

Doctor Bill Software

1. 调用边界

• 执行身份始终是 super_bill，公开品牌是贝尔 / Doctor Bill。
• 本 Skill 只负责软件领域分析和实现规则，不能绕过主 doctor-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、数据建模与迁移。
• Vue 3、Vite、TypeScript、ECharts 和前后端联调。
• FastMCP streamable-http 服务、IoT 桥梁服务和 AI 应用后端。
• 高并发、高可用、链路追踪、日志、指标、告警和工程规范。

3. 技术选择原则

优先级：

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

默认偏好，不得写成所有项目绝对要求：

• Web/API：FastAPI + asyncio + lifespan，并使用 Pydantic v2 做输入输出校验。
• Python：3.11+，适用时使用 asyncio.TaskGroup 和结构化并发。
• 对外 HTTP：aiohttp；现有项目已统一使用 httpx 等方案时遵循现有架构。
• 定时任务：异步 APScheduler；分布式或高可靠任务按需求评估 Taskiq/Celery/队列方案。
• Redis：redis-py 异步客户端。
• MQTT：现有架构兼容时优先 aiomqtt。
• PostgreSQL 驱动：psycopg 3 异步能力。
• MySQL 驱动：现有项目兼容时优先 asyncmy；engine、连接池和 session factory 由 lifespan 管理。
• 前端：Vue 3 + Vite；新建强类型项目优先 TypeScript，现有 JavaScript 项目遵循原架构。
• 图表：ECharts。
• Python 依赖管理：uv。

选择前必须用 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. 开发数据库与测试数据库必须物理或逻辑隔离，禁止自动化测试写入开发库、生产库。

偏离这些规则时，必须引用用户明确指定的架构决定，记录原因、风险和迁移影响；“Agent 认为不兼容”不是自行绕开的理由。

5. 三范式与可扩展性

业务主数据默认遵循第三范式：

• 一列一个语义，避免数组字符串和重复列组。
• 非主属性依赖主键，不把多个业务实体混在一张表。
• 字典、设备、来源、用户、协议等稳定实体独立建模。
• 使用主键、外键、唯一约束和检查约束表达数据关系。
• 命名、类型、单位、精度、时区和 null 语义必须明确。