44 lines
3.9 KiB
Go
44 lines
3.9 KiB
Go
# 项目协作规则
|
||
|
||
## 全局规则
|
||
|
||
- 代码、包、方法、结构体、接口、关键业务分支、复杂判断和关键配置都需要编写清晰的中文注释。
|
||
- 注释要说明业务意图、输入输出、边界条件和注意事项，避免只重复代码字面含义。
|
||
- 模块职责要清晰，避免跨层调用、重复实现和无关逻辑混入。
|
||
- 新增或修改功能时，优先遵循项目已有目录结构、命名方式、封装习惯和错误处理方式。
|
||
- 公共能力应沉淀为可复用模块或组件，避免在多个页面、控制器或服务中复制粘贴。
|
||
|
||
## 前端规则
|
||
|
||
- 项目名称为“萧康云医官网”，定位为面向诊所赋能业务的 SaaS 平台。
|
||
- 产品端形态包含小程序患者端、医生端、门店老板端、推广员端，以及 PC 管理后台和官网相关页面。
|
||
- 页面设计要体现 SaaS 平台的专业、清晰、高效，优先服务信息扫描、业务转化和多角色理解。
|
||
- 必须注意多端适配，兼容移动端、平板端和桌面端，不允许出现文字溢出、布局重叠、关键按钮不可触达等问题。
|
||
- 必须提供暗色模式适配；暗色模式以灰黑体系为主，文字、按钮、卡片、图表和状态提示都要保持可读。
|
||
- 采用模块化、组件化设计，页面由清晰的业务模块和可复用 UI 组件组成。
|
||
- 组件职责保持单一，状态、事件、属性和插槽设计清楚，避免单个组件承担过多页面逻辑。
|
||
- 表单、列表、筛选、弹窗、空状态、加载状态、错误状态、成功状态等常见状态要完整设计。
|
||
- 视觉风格要克制、现代、可信，适合医疗和诊所经营场景；避免过度营销化、装饰化或单一色系堆叠。
|
||
|
||
## 后端规则
|
||
|
||
- 后端使用 GoFrame GF 框架，必须遵循 GF 的项目结构、路由注册、控制器、服务、模型、配置和错误处理规范。
|
||
- 分层链路固定为：路由 -> 控制器 -> service 服务层 -> 模型层。
|
||
- 路由层只负责请求路径、HTTP 方法、中间件和控制器绑定，不编写业务逻辑。
|
||
- 控制器层负责获取请求信息、参数验证、用户信息解析、调用 service，并返回统一响应。
|
||
- 控制器层不编写核心业务逻辑，不直接操作数据库，不绕过 service 调用模型。
|
||
- service 层是业务逻辑层，负责业务流程编排、权限判断、事务控制、数据处理和外部服务调用。
|
||
- 模型层只用于定义表结构、表关系、字段映射和数据承载，不编写业务逻辑。
|
||
- 数据库访问、事务、缓存、队列、第三方接口等能力应按 GF 推荐方式封装，并放在合适的服务或基础设施模块中。
|
||
- 参数校验、错误码、日志、上下文传递和用户身份解析要保持统一规范。
|
||
- 不准使用数据库迁移自动删除或破坏已有数据，结构调整必须提供可审查的 SQL。
|
||
|
||
## API 响应与字段命名规则
|
||
|
||
- 所有 HTTP API 的 HTTP 状态码统一返回 200，不用 4xx/5xx 直接表达业务失败；前端必须通过响应体 `code` 判断成功或失败。
|
||
- 统一响应结构固定为 `{ "code": 0, "message": "ok", "result": ... }`。
|
||
- 业务错误返回 `code != 0`，`message` 必须给出清晰中文错误信息，`result` 默认返回 `null`。
|
||
- 控制器返回错误时必须调用统一响应封装，禁止出现无错误信息的 500、空响应或框架默认错误页。
|
||
- JSON 请求字段和响应字段统一使用下划线命名 `snake_case`，例如 `order_no`、`tenant_name`、`contact_name`、`plan_code`、`billing_cycle`、`menu_layout`、`global_layout`、`final_layout`。
|
||
- Go 结构体字段可以保持 Go 命名规范，但 `json` tag 必须写成 `snake_case`；map 返回值的 key 也必须使用 `snake_case`。
|
||
- 使用 GF 时避免统一响应被二次包装；如果控制器已经写出 `{ code, message, result }`，不要再叠加响应中间件造成 500 或嵌套响应。 |