You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
virt/docs/USER_COPY_CATALOG.md

103 lines
8.4 KiB
Markdown

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# 用户界面文案目录
Virt Cloud 的用户界面文案使用“源码中文合同 + 管理员目标语言译文”模型。源码只保存简体中文安全基线、稳定语义键和渲染元数据;英文及其他目标语言译文不得进入仓库,必须由管理员在后台录入、发布和回滚。
## 双平面架构
系统把编辑与用户请求严格分开:
1. **管理平面**使用数据库表 `ui_copy_locales`、`ui_copy_entries`、`ui_copy_drafts`、`ui_copy_publications` 和 `ui_copy_revision_items`。它负责同步源码合同、保存管理员草稿、校验参数、记录不可变发布历史和执行回滚。
2. **运行平面**只读取 `web/storage/framework/user-copy/current.json` 及其指向的 `generations/<generation>/` 不可变 PHP/JSON 文件。普通用户请求不会查询上述五张翻译表,也不会在文件缺失或损坏时临时回查数据库。
发布器先完整写入并校验一个不可变 generation,再原子切换 `current.json`。写入或校验失败时旧指针继续生效;回滚只把对应语言的指针切回已验证的历史 generation。PHP 模板和浏览器运行时从同一份 generation 读取,因此不存在服务器端和浏览器端各自维护一套译文的问题。
目标语言中缺少、过期或与当前源码/参数合同不兼容的词条,会逐词回退到当前中文源码基线。回退不读取数据库。已发布译文只有在 `source_hash` 与 `placeholder_hash` 仍兼容时才会继续使用。
## 源码合同
入口为 `web/resources/user-copy/manifest.php`,页面词条按功能拆分在 `web/resources/user-copy/entries/*.entries.php`。每条词条必须声明:
- 静态小写语义键,例如 `instance.settings.hostname.help`;禁止运行时拼接键,也禁止 `.dynamic.h<hash>` 形式的临时哈希键。
- `scope`、`page`、文案种类、中文基线、格式、参数合同、风险级别和是否允许隐藏。
- 需要插值时使用 ICU 格式并完整声明参数;译文必须保持参数合同。
- 支付、删除、重装、数据丢失、效果未知等关键文案必须可见,不能被目标语言草稿隐藏。
- Toast 的语义级别由源码合同决定。译文管理员只能修改内容,不能把错误或警告改成成功提示。
条目文件返回带 `key` 字段的列表,而不是以 key 作为 PHP 数组下标。这样加载合同可以发现重复键,避免 PHP 在解析关联数组时静默覆盖。校验后目录按键排序,源码排列顺序不会改变摘要。
## 页面范围
当前 Manifest 明确登记以下用户页面及公共界面:
| 分组 | 页面键 |
| --- | --- |
| 公共与认证 | `public.home`、`public.error`、`auth.login`、`auth.register`、`auth.password` |
| 法律页面 | `legal.terms`、`legal.privacy` |
| 云资源 | `cloud.instances`、`cloud.deploy`、`cloud.detail`、`cloud.reinstall`、`cloud.backups`、`cloud.snapshots`、`cloud.traffic`、`cloud.vpcs`、`cloud.isos`、`cloud.keys` |
| 账单 | `cloud.invoices`、`cloud.invoice_detail`、`user.recharge` |
| 账户与支持 | `user.account`、`user.invite`、`user.tickets`、`user.tasks`、`user.announcements` |
`common` scope 提供导航、通用对话框、通用请求错误、Toast 标题等跨页内容;页面只能加载 Manifest 为该页面登记的 scope。`UserCopyPageResolver` 负责非 Cloud 用户路由的页面映射,Cloud 页面在控制器绑定时显式指定页面键。
当前公共语言选择支持 `zh-CN` 与 `en`:优先使用 `?lang=`,其次使用持久 Cookie,最后解析浏览器 `Accept-Language`。源码没有英文兜底;尚未发布英文译文的条目按上述规则显示中文基线。
## 管理员工作流
超级管理员通过“管理员后台 → 用户界面译文”完成以下操作:
1. **同步源码词条**:把当前 Manifest 投影到管理账本;源码删除的条目标记为孤立,中文基线或参数合同变化会使不兼容草稿变为 stale。
2. **编辑草稿**:按页面和目标语言筛选词条,保存时校验 UTF-8、长度、ICU 参数、可见性和乐观版本。
3. **安全预览**:预览使用受限 iframe,不执行目标译文中的脚本。
4. **发布目标语言**:把有效草稿和兼容的历史译文编译为新的不可变目录,并原子激活。
5. **发布历史与回滚**:历史发布保留完整词条快照;回滚只允许切换到已经通过完整性校验且属于同一语言的 generation。
数据库是编辑和审计账本,不是用户请求的运行时依赖。管理员页面或数据库临时不可用不会影响已经发布的用户界面目录。
## 模板与浏览器运行时
Smarty 模板使用 `{user_copy key='...'}`;浏览器代码使用 `VenixUserCopy.text(key, parameters)`,并通过同一运行时提供的 `number`、`currency`、`date` 和 `bytes` 格式化数值。页面 Bootstrap 只包含当前页面 scope 所需的消息和元数据。
`web/tests/UserCopyCompleteCoverageTest.php` 是用户前端文件所有权清单和最终覆盖门禁:
- 显式列出所有非管理员 Venix 模板,包括根级落地页、错误页、认证、Cloud、账户、法律页和共享组件;新增或删除模板必须同时更新清单。
- 显式列出所有用户专属浏览器 JS;`web/public/cloud/` 和 `web/public/theme/venix/js/` 中每个 JS 都必须被分类为用户、管理员、基础设施、vendor 或明确未使用。
- 管理员 JS/CSS、vendor 文件、上传哈希 Worker 和未被用户模板加载的遗留探测脚本不参与用户文案扫描,避免把管理后台文案和协议常量误判为用户译文缺口。
门禁拒绝:
- 未登记的可见中文,以及模板中未登记的可见英文文本或可见英文属性;
- 直接写入字面量的 Toast/Confirm 文案;
- 固定 `zh-CN` 的浏览器日期或数字格式;
- 直接读取或展示后端 `message`、`detail`、`msg`、`errmsg`、`error`;
- `.dynamic.h<hash>` 临时哈希键和旧 `$language == 'true'` 分支;
- 未分类的新模板、新 Cloud JS 或新 Venix JS。
允许排除的内容只有四类,而且标记必须与代码同一行并附带非空原因:
```text
// user-copy: allow technical-constant non-rendered protocol token
// user-copy: allow technical-regex backend classifier never rendered
// user-copy: allow test-fixture scanner rejection sample
// user-copy: allow admin-compatibility shared admin fallback
```
`technical-constant` 只用于不渲染的协议、单位或机器标识;`technical-regex` 只用于对后端技术错误进行分类且匹配内容绝不直接显示;`test-fixture` 只允许出现在测试样本;`admin-compatibility` 只允许用于同一资产同时被管理员页面加载、管理员尚无用户目录 Bootstrap 的兼容 fallback,而且用户路径仍必须优先从目录读取。普通用户专属资产不能使用 `admin-compatibility`。实际用户文案、后端错误原文和其他临时 fallback 都不能借标记绕过目录。任意其他类别、缺少原因或单独一行的标记都会被门禁拒绝。
## 部署与发布
1. 同时发布 PHP、模板、浏览器资产和 Manifest;不得只发布其中一部分。
2. 全新环境从当前 `web/sql/ss.sql` 创建数据库。既有环境必须先备份,再用经审核的一次性增量迁移创建上述五张 `ui_copy_*` 表和约束;不得在非空数据库运行 `php xcat cloudInit` 冒充升级。
3. 确认 PHP 运行用户可以创建并原子重命名 `web/storage/framework/user-copy/` 下的文件和目录;不要预先手工编写 `current.json`。
4. 重启/重载承载 PHP 的长期进程,使其加载同一版本代码;按项目共享资源版本发布静态文件。
5. 以超级管理员进入“用户界面译文”,先执行“同步源码词条”,确认投影完整后录入英文草稿。
6. 发布目标语言,确认 `current.json` 已指向新 generation,并分别验收 Smarty 页面、浏览器动态提示、语言切换和中文缺词回退。
7. 发布后运行下列合同测试;覆盖门禁必须为零违规才能视为迁移完成:
```bash
php web/tests/UserCopyManifestContractTest.php
php web/tests/UserCopyCoverageScannerTest.php
php web/tests/UserCopyCompleteCoverageTest.php
```
用户请求只依赖源码中文基线和已发布文件,因此翻译数据库停机验收应保持页面可读;删除或篡改当前 generation 的测试只能在隔离环境执行,并应验证安全回退而不是数据库回查。