# 项目协作规则

## 全局规则

- 代码、包、方法、结构体、接口、关键业务分支、复杂判断、关键配置均需要编写清晰的中文注释。
- 注释要说明业务意图、输入输出、边界条件和注意事项，避免只重复代码字面含义。
- 模块职责要清晰，避免跨层调用、重复实现和无关逻辑混入。
- 新增或修改功能时，优先遵循项目已有目录结构、命名方式、封装习惯和错误处理方式。
- 公共能力应沉淀为可复用模块或组件，避免在多个页面、控制器或服务中复制粘贴。

## 前端规则

- 项目名称为“萧康云医官网”，定位为面向诊所赋能业务的 SaaS 平台。
- 产品端形态包含小程序患者端、医生端、门店老板端、推广员端，以及 PC 端管理或官网相关页面。
- 页面设计要体现 SaaS 平台的专业、清晰、高效，优先服务信息扫描、业务转化和多角色理解。
- 必须注意多端适配，兼容移动端、平板端和桌面端，不允许出现文字溢出、布局重叠、关键按钮不可触达等问题。
- 必须提供暗色模式适配，颜色、阴影、边框、图标、图表和状态提示都要在明暗主题下保持可读。
- 采用模块化、组件化设计，页面由清晰的业务模块和可复用 UI 组件组成。
- 组件应保持职责单一，状态、事件、属性和插槽设计清楚，避免单个组件承担过多页面逻辑。
- 表单、列表、筛选、弹窗、空状态、加载态、错误态、成功态等常见状态要完整设计。
- 视觉风格要克制、现代、可信，适合医疗和诊所经营场景；避免过度营销化、装饰化或单一色系堆叠。

## 后端规则

- 后端使用 GoFrame GF 框架，必须遵循 GF 的项目结构、路由注册、控制器、服务、模型、配置和错误处理规范。
- 分层链路为：路由 -> 控制器 -> service 服务层 -> 模型层。
- 路由层只负责请求路径、HTTP 方法、中间件和控制器绑定，不编写业务逻辑。
- 控制器层负责获取请求信息、参数验证、用户信息解析、调用 service，并返回统一响应。
- 控制器层不编写核心业务逻辑，不直接操作数据库，不绕过 service 调用模型。
- service 层是业务逻辑层，负责业务流程编排、权限判断、事务控制、数据处理和外部服务调用。
- 模型层只用于定义表结构、表关系、字段映射和数据承载，不编写业务逻辑。
- 数据库访问、事务、缓存、队列、第三方接口等能力应按 GF 推荐方式封装，并放在合适的服务或基础设施模块中。
- 参数校验、错误码、日志、上下文传递和用户身份解析要保持统一规范。
