开发说明 · Development

代码结构 · Repository layout

路径 Path	内容 Contents
R/	函数代码；帮助页面用roxygen2注释（Markdown模式）编写
man/	由roxygen2生成的帮助页面，不要手工修改
inst/extdata/	包内自带数据：FAO数据、渔区边界、FishBase特征表、海表温度、图表标签（chart_labels.csv）、报告模板（report_text.csv、report_references.csv）
inst/cmsy/	官方CMSY++代码、神经网络和用户手册
vignettes/articles/	网站英文文章；zh/为中文版；zh/reference/为中文函数参考（自动生成）
pkgdown/	网站样式与脚本（extra.css、extra.js：中英文切换、函数参考前后页）、图标、中文函数说明的翻译（zh-reference/*.json）
data-raw/	生成包内数据、README图片和中文函数参考的脚本
tests/testthat/	测试

修改函数后 · After changing a function

1. 修改R/中的代码和roxygen注释，然后生成帮助页面：

   roxygen2::roxygenise()
   

2. 更新中文函数参考（需在UTF-8环境中运行）：

   LC_ALL=en_US.UTF-8 Rscript data-raw/make_zh_reference.R extract
   

   帮助页面有变化的函数，其pkgdown/zh-reference/<函数>.json会标记"stale": true；对照en中的英文更新zh中的翻译，再把stale改为false。新函数会得到一个空白的翻译文件。

   LC_ALL=en_US.UTF-8 Rscript data-raw/make_zh_reference.R build
   

   生成vignettes/articles/zh/reference/中的页面。测试test-zh-reference.R会检查每个函数都有完整、最新的中文说明。

3. 新函数要加入_pkgdown.yml的reference分组；extra.js中的GROUPS_ZH给出分组的中文名。

4. 运行测试和检查：

   testthat::test_local()
   

   R CMD build . && R CMD check --no-manual faofishingreport_*.tar.gz
   

网站 · Website

• 本地构建：pkgdown::build_site()（需要pandoc，例如RStudio自带的）。
• 推送到main后，GitHub Actions（.github/workflows/pkgdown.yaml）自动构建网站并发布到gh-pages分支。
• 文章开头的source("../_setup.R")加载本包、设置图表并显示所用的FAO版本；中文文章额外运行fao_settings(lang = "zh")。
• README图片由data-raw/make_readme_figures.R生成，保存在man/figures/。

分支与发布 · Branches and releases

• main：发布版本，网站由此构建。
• dev：开发分支，较大的新功能先在这里完成和测试（例如CMSY++的三系统检验），再合并到main。
• 其他分支为单独的测试任务。
• 发布新版本：更新DESCRIPTION的Version、inst/CITATION和NEWS.md，运行检查后推送main。
• 提交信息用中文描述改动内容。

持续集成 · Continuous integration

工作流 Workflow	作用
R-CMD-check.yaml	在Windows、macOS和Linux上运行R CMD check
test-coverage.yaml	测试覆盖率（Codecov）
pkgdown.yaml	构建并发布网站
cmsy-cross-platform.yaml	在三个系统上实际运行CMSY++