# 项目工作规则

以下规则适用于本项目的所有开发与修改。

## SQL 文件命名

- 生成或更新 SQL 脚本时，必须统一写入 `update.sql`。
- 不得创建带日期后缀或日期标记的替代文件，例如 `updateYYYYMMDD.sql`、`update-YYYY-MM-DD.sql`，或任何以年、月、日或日期作为 `XXX` 的 `updateXXX.sql` 文件。
- 如果 `update.sql` 已存在，直接更新该文件并保留无关的原有内容，不得另行创建其他 SQL 更新文件。

## 方法位置

- 新增方法必须写在目标文件的最下方；类或对象中的方法应追加在其最后一个已有方法之后、闭合括号之前。
- 不得将新增方法插入文件顶部，也不得放在已有方法之前。
- 修改已有方法时，保留其原有位置。

## Controller 代码风格

- Controller 写法参考项目现有实现（如 `app/controller/tender_controller.js`），保持项目代码风格一致。
- 页面渲染使用 `const renderData` 组织数据，再传给 `this.layout(...)`。常规数据可以直接在 `renderData` 对象初始化时集中设置；后续补充的数据，或 `if` 等条件分支中仅对部分用户可见的数据，再通过 `renderData.xxx` 赋值。不要求所有字段都逐项赋值。

## Service 与查询代码风格

- Controller 负责请求处理与响应；较复杂的字段配置、权限判断、业务校验和流程编排抽取到 lib。Service 层只负责数据库查询、写入及相关事务操作，供 Controller 或 lib 调用，不得混入上述业务逻辑。
- Service 写法必须参考系统现有实现，优先复用已有方法，保持项目代码风格一致。
- 普通数据库操作优先使用系统已有的 Service、基类方法或数据库封装；只有遇到复杂 SQL 查询时才使用手写 SQL。
- 手写 SQL 时，使用 `const sql` 和 `const sqlParam` 分别声明 SQL 语句与参数。
- 参数必须通过占位符传递，不得直接拼接参数到 SQL 语句中。
- 所有权限查询均不使用 `SqlBuilder`。

## 弹窗组织

- 弹窗模板独立放置，不得直接混写在主页面模板中。
- 首页或列表页的弹窗可以使用对应模块下的 `modal.ejs`。
- 其他页面的弹窗使用 `<页面名>_modal.ejs`，例如广元大屏使用 `guangyuan_modal.ejs`，避免不同页面统一使用 `modal.ejs` 而混淆归属。
- 如果需要独立的弹窗 JavaScript 文件，同样按页面命名为 `<页面名>_modal.js`；首页或列表页可以使用 `modal.js`。不必仅为命名而新建独立脚本。

## 测试文件

- 不新增测试文件。

## 页面样式组织

- 页面自定义 CSS 统一写入 `app/public/css/main.css`，不另建页面专用 CSS 文件。
- 使用页面专属类名限定样式作用范围，避免影响其他页面。

## 前端 JavaScript 代码风格

- 前端 JavaScript 的业务接口请求优先使用系统封装的 `postData`，不另行使用 `fetch` 或重复封装底层 Ajax；页面导航和静态资源加载不在此限制内。
- `postData` 的成功回调接收的是解包后的 `data`，不要再次按完整响应对象读取；异步包装时必须保留失败回调，使加载失败和重试流程正常工作。