开发说明

开发说明（Development Notes）

目录

• 编码规范
  • 通用编码实践
  • Javascript
  • SQL
  • 全局选项
  • i18n
  • 安全准则
  • 版本信息对话框
• 前端
  • 页面设计
  • 按钮颜色
• 贡献

编码规范

正在制定编码规范与规则，让协作更轻松。

通用编码实践

• 所有代码都必须有注释——缺少代码注释的 PR 在补上之前不会被合并
• 代码须按 4 个制表位缩进
• 新建的控制器必须有对应的配套方法，该方法必须包含此项的所有功能，不要把条目加到其他模型里
• PR 必须经过测试，未测试的会被拒绝；合并不设时间表，只能尽力而为
• 应使用 curl，而不是已弃用的 file_get_contents
• 静态资源必须存放在本地而不是 CDN，并正确放在 /assets 文件夹中

Javascript

• 尽可能把 Javascript 放在 assets/js/sections 下的独立文件中，除非确实不适合；优先使用 jQuery

SQL

• SQL 查询必须有节制，并设计得尽可能快；这能让 Wavelog 尽可能快
• SQL 查询应尽可能使用绑定变量
• 优先使用原生 SQL 语法，而不是 CodeIgniter 查询构造器

全局选项

如果你的功能需要一个全局配置选项——即登录或未登录状态下都需要的设置，而不是仅供单个用户使用——那么它应该放在全局的 'options' 表中

该表包含以下字段

• option_name - 选项名称
• option_value - 选项的值
• autoload - 取值为 yes 或 no，表示该选项是否为所有人加载；用户名和密码之类的内容不应自动加载

i18n

• 尽可能使用 gettext
• 使用 echo __("This is a string"); 而不是 echo "This is a string";
• 如果字符串中有可变部分，请这样写：echo sprintf(__("This is a %s text. It it's simple %s."), $variable, "<br/>");
• __([String]) 方法不能用于变量
• 翻译应使用双引号 echo __("This is a string");
• Javascript 翻译可以通过在 wavelog/application/views/interface_assets/footer.php 中设置所需的 i18n 字符串来实现

更多信息见翻译

安全准则

• 永远不要信任用户输入，意思是：要反复检查提交的变量是否在权限范围内。例如：日志编辑页面只显示已登录用户的日志。若要编辑该日志，你要把日志的 id 传给控制器内的某个函数。在处理之前必须检查传入的 ID 是否属于该用户
• 所有修改数据、且仅由用户/管理员调用的控制器，必须检查该用户是否有权调用这些函数。最好在构造函数中完成
• 所有面向访客的其他控制器必须检查不得泄露（受保护的）数据
• 所有由计划任务调用的其他控制器，不得向调用该脚本的用户/计划任务披露任何数据。例如：由计划任务调用的 LoTW 上传不得显示上传了哪些 QSO
• 永远不要为关键函数假定默认值
• 用户输入可以通过安全模块的 xss_clean([user input]) 函数清理，或通过 input->get([user input], "TRUE") 清理

版本信息对话框

版本信息对话框仅由数据库触发，数据存放在两张数据表中：

• 数据表 options - 包含版本对话框的基本配置

• 数据表 user_options - 包含触发器，若为 false 则会向用户显示该对话框。如果用户点击「不再显示」，option_value 会被覆盖为 true

要为所有用户远程触发/覆盖数据库（用于更新），只需在迁移脚本的 functiopn up() 中使用以下三行。

// Trigger Version Info Dialog
$this->db->where('option_type', 'version_dialog');
$this->db->where('option_name', 'confirmed');
$this->db->update('user_options', array('option_value' => 'false'));

前端

页面设计

• 页面的功能性标题使用 H2

按钮颜色

• 蓝色 = 实心 = 添加内容、启用内容，或执行其他任何主要操作。
• 蓝色 = 描边 = 编辑、更改或更新内容。
• 红色 = 删除内容，或做出不可逆的更改。
• 灰色 = 停用内容。
• 黄色 = 重置内容或清空字段（不是永久删除）。
• 绿色 = 搜索。

贡献

• 永远欢迎 😉
• 必须_基于_最新的 dev（例如 git clone [your fork]、git checkout dev、git pull、git checkout -b my_contribution）
• PR 必须_针对_ dev 创建（例如 git request-pull my_contribution https://github.com/wavelog/wavelog.git dev - 或通过 GitHub 图形界面（推荐））