企业官网建设流程全解析

• 后端
• 前端
• CMS

TaleBook 是一个前后端分离的个人书库项目：前端位于app/（Nuxt 3 + Vue 3 Composition API），后端位于webserver/（Tornado + SQLAlchemy）。本文基于项目内的开发规范文档 code_rules.md，系统梳理其"小步修改、逐步验证"的协作节奏、i18n / Python / Vue 三类文件的修改细则，并结合仓库源码与配套脚本，给出可落地、可校验的开发流程。读完本文，你将掌握 TaleBook 代码提交前必须遵守的修改粒度、验证命令与工程约定，并理解每条规范背后的源码依据。

一、核心原则：小步修改（必须遵守）

TaleBook 的开发规范把"小步修改"列为必须遵守的硬性要求，而非建议。其四条基本约束是：

1. 每次只修改一小部分（每个文件 ≤ 3 个修改点）；
2. 大任务必须拆分成多个小步骤；
3. 保持原有结构和格式；
4. 每步完成后必须验证。

这一原则在仓库的实际工程结构中有明显呼应：项目规模庞大（前端组件、后端服务、插件系统、i18n 语言包并存），任何一次跨文件、跨模块的大改都可能引入难以定位的回归。规范通过强制"小步快跑"，把每一次变更的排查范围压缩到最小。

对应的禁止行为同样严格：

• 禁止一次性大规模修改；
• 禁止不验证就继续下一步；
• 禁止破坏原有文件结构；
• 禁止不读取文件就直接修改。

后两点尤其值得注意："不读取文件就直接修改"被明确列为违规，意味着任何改动前必须先通读目标文件的上下文，这与"保持原有结构和格式"相互支撑——只有理解了原有结构，才能保证改动不破坏既有约定。

二、按文件类型拆分修改规范

规范将日常改动按文件类型分别约定修改粒度，避免在单次操作中混入过多无关内容。

1. i18n 翻译文件：一次只添加一个分类

• ✅ 每次只添加一个分类（如先title，再button）；
• ❌ 禁止一次性修改所有内容；
• 每步验证 JSON 格式。

这一条对应的是 TaleBook 的嵌套翻译键结构。以中文语言包 app/i18n/locales/zh-CN.json 为例，imports分类下就同时存在title、titles、button三个子命名空间：

"imports": { "title": "导入图书", "titles": { "addOpdsSource": "添加 OPDS 源", "editOpdsSource": "编辑 OPDS 源" }, "button": { "refresh": "刷新", "scanBooks": "扫描书籍" } }

英文语言包 app/i18n/locales/en-US.json 中对应位置是"addOpdsSource": "Add OPDS Source"。由于翻译键采用嵌套结构（如规范中举例的titles.addOpdsSource），一次只添加一个分类可以有效避免：键路径写错、层级错位、中英文语言包不同步等问题。前端的 i18n 初始化配置位于 app/i18n.config.ts，默认语言为zh-CN，通过legacy: false启用 Vue I18n 的 Composition 模式，语言包以messages注入。

仓库还提供了两个配套的静态检查脚本，用于在人工"每步验证"之外做自动化兜底：

• scripts/check_i18n_translation_missing.py：用正则(?:[^a-zA-Z0-9_]t|\$t)\('([a-zA-Z0-9_.]+)'\)扫描app/下所有.vue/.js/.ts文件里用到的翻译键，再与每个语言包扁平化后的键集合比对，输出"代码中用到了但语言包缺失"的键，实现missing keys检测；
• scripts/check_i18n_translation_useless.py：反向检查语言包中存在但代码中已无人引用的"无用翻译键"，防止语言包膨胀。

这两个脚本与规范"每步验证 JSON 格式"的要求互为补充：前者保证新增键被正确覆盖，后者保证删除键不会遗留死数据。

2. 代码文件（Python）：一次只改一个函数/类

• ✅ 每次只修改一个函数/类；
• ❌ 禁止同时修改多个不相关部分；
• Python 文件需验证语法。

后端webserver/是基于 Tornado + SQLAlchemy 的 Python 工程，函数与类之间的调用链较长（如handlers/→services/→models.py）。同时修改多个不相关部分，会让一次验证无法定位是哪个改动引入了错误。因此规范要求改动聚焦到单个函数/类，并通过语法验证把低级错误挡在门外。

3. Vue 文件：先 template，再 script，分步验证

• ✅ 先template，再script，分步验证；
• ❌ 禁止同时修改多个部分。

app/components/下的 Vue 单文件组件（如 OpdsImportDialog.vue）同一文件里混合了模板、脚本与样式。规范要求把 template 与 script 视为两个独立步骤分别修改、分别验证，避免模板与脚本的改动相互干扰、一次报错难以归因。

三、验证要求：每步修改后必须执行的检查

规范给出了两类文件的命令行验证方式，这是"每步完成后必须验证"的具体落地工具。

JSON 文件验证（适用于 i18n 语言包等）：

python -c "import json; json.load(open('文件路径', encoding='utf-8'))"

该命令会把 JSON 文件完整解析一遍，任何尾逗号、未闭合括号、非法转义都会立即报错。对于像 app/i18n/locales/zh-CN.json（约 2200 行）这样的大型语言包，这一句验证是修改后最廉价、最有效的自检手段。

Python 文件验证：

python -m py_compile 文件路径

py_compile只做语法编译检查，不执行代码，速度快、无副作用，适合在每次修改单个函数/类后立即执行。

这两条验证命令与仓库测试体系（tests/下的test_main.py、test_models.py等）分工明确：编译/解析验证负责"语法正确"，测试用例负责"逻辑正确"，两者都遵循"小步验证"的节奏。

四、推荐做法与工程红线

规范在"禁止行为"之外，还归纳了四条推荐做法：

1. 小步快跑，及时验证；
2. 保持向后兼容；
3. 遵循项目已有规范；
4. 遇到问题及时沟通。

其中"保持向后兼容"在数据库演进上体现得最典型。规范在项目规范一节明确写道：数据库新增表需--syncdb。这句话对应的是一条真实存在的命令行入口：

python server.py --syncdb

从源码看，该入口定义于 webserver/main.py：

define("syncdb", default=False, type=bool, help=_("Create all tables"))

并在启动流程中触发建表逻辑（webserver/main.py）：

if options.syncdb: models.user_syncdb(engine)

真正的建表实现位于 webserver/models.py：

def user_syncdb(engine): Base.metadata.create_all(engine)

Base.metadata.create_all只会创建尚不存在的表，对已有表不做破坏性变更，这正是"保持向后兼容"的底层保证。项目还提供更精细的增量迁移工具 webserver/migrate_db.py，通过compare_and_migrate对比模型列与数据库实际列，按add_column等动作逐个补齐，而非重建整库。

--syncdb在真实部署链路中同样可见：

• Dockerfile 在镜像构建阶段执行python3 server.py --syncdb预建数据表；
• 开发脚本 docker/start-dev.sh 以gosu talebook:talebook身份运行server.py --syncdb；
• 服务自检模块 webserver/self_check.py 把syncdb作为启动自检项之一，失败时返回syncdb_failed状态，并在 docker/status_page.html 中提示"数据库初始化失败，请检查 /data/books 目录是否可写、磁盘空间是否充足"。

因此，TaleBook 的数据库变更规范可以概括为：新增表 →python server.py --syncdb；表结构小改动 → 依赖migrate_db.py的增量迁移；任何情况下不做重建式破坏性变更。

五、项目工程规范一览

规范最后给出了 TaleBook 的技术栈与命名约定，这些约定与仓库目录结构一一对应，是后续所有"遵循项目已有规范"的落点：

六、规范的日常落地流程

将上述规范串成一次典型修改的完整流程，可以归纳为五步：

1. 读取：先通读目标文件，理解原有结构与格式（对应"禁止不读取文件就直接修改"）；
2. 切分：把大任务拆成小步骤，每次改动限定在一个文件、一个分类或一个函数/类内（对应"每个文件 ≤ 3 个修改点"）；
3. 修改：按文件类型套用细则——i18n 一次只加一个分类、Python 一次只改一个函数/类、Vue 先 template 后 script；
4. 验证：JSON 用python -c "import json; json.load(...)"，Python 用python -m py_compile，必要时再跑 scripts/check_i18n_translation_missing.py 与 scripts/check_i18n_translation_useless.py 做语言包一致性检查；
5. 推进：验证通过后再进入下一步，全程保持向后兼容，遇到歧义及时沟通。

这套"小步修改 → 分级验证 → 向后兼容"的规范，配合仓库中的自检脚本、--syncdb建表入口与增量迁移工具，构成了 TaleBook 开发流程中可执行、可审计的工程约束。无论是新增一个 i18n 翻译分类、重构一个 Python 服务函数，还是给数据库增加一张新表，都可以在这一框架内以最小的风险完成。

• 后端
• 前端
• CMS