# 源码基线与发布约定

## 本次生产源码归档

2026 年 10 月 30 日完成只读核对：

- 归档前的 `main`：`e2a8f2dda3f190f78529b4419f295a356476c74b`。
- 原主线回退标签：`main-before-production-sync-20261030`。
- 生产源码分支：`codex/canvas-image-429-deploy-1001`。
- 生产源码提交：`439fd56fe120fdb9f855b50fa4df9ce2e71bb72a`。
- 实际运行构建 ID：`QhoygcZ4-x42PwCgCEj1d`。
- 生产目录另有 19 个已跟踪文件的修改和 6 个新增源码文件。

这些源码改动按原始内容归档在标签 `production-snapshot-48-20261030`，
25 个文件均经过 SHA256 校验。原始补丁和文件副本还保存在独立的本地备份中。
环境文件、模型配置备份和历史构建目录未加入源码归档。

源码归档标签表示核对时的服务器源码状态。实际运行的构建单独用构建 ID 标识，
不能仅凭服务器分支名或提交号认定某份构建已经部署。

接手分支 `codex/production-48-20261030` 在归档后只清理构建目录引用和仓库检查兼容性，
通过 PR 将已审查的生产源码同步回 `main`。本次源码同步不包含服务器部署或重启。

## 后续开发与合并

1. 从最新 `main` 创建任务分支，使用 `codex/<任务>` 命名。
2. 每次提交只暂存本次任务明确涉及的文件，检查暂存区差异和凭据。
3. 通过 PR 合入 `main`，记录验证结果；未通过或未执行的检查须写明原因。
4. 历史生产、试验和备份分支先保留。确认改动是否已收录后，再单独评审归档。
5. 服务器上的临时修复应及时取回源码、审查、提交并合入主线，避免再次形成服务器独有状态。

源码换行由 `.gitattributes` 固定为 LF，Windows 批处理文件保留 CRLF。
这样源码断言和检查在 Windows、Linux 上读取到相同内容，避免仅因换行差异误报。

## 构建与发布

- 从 `main` 的确定提交或对应发布标签构建，保留提交号与构建 ID 的对应关系。
- 默认构建目录为 `.next`；独立发布可设置 `NEXT_DIST_DIR`。
- `next-env.d.ts` 和 `tsconfig.json` 中不要提交某台服务器历史构建目录的引用。
- `.next-*`、模型配置备份、临时目录和备份文件留在运行环境，不纳入版本控制。
- 发布前保存可回滚版本，发布后核对实际运行构建、页面和必要业务流程。
- 合并源码与部署是两个操作；部署需要单独明确目标和发布范围。

`scripts/storage/` 下的迁移、审计脚本作为维护源码保存。
执行前须检查参数、目标存储和数据库配置；本次归档没有执行任何数据迁移。

## 验证入口

项目固定使用 pnpm 9.12.3，依赖按锁文件安装。
常规检查入口为 `pnpm check:branch`、`pnpm check:quality` 和 `pnpm build`，
运行环境与路由验收按 PR 模板记录。
`pnpm lint` 直接使用锁文件中的 Biome 版本执行现有检查，避免包装命令再次调用 `npx`。
历史 lint 或格式诊断应在 PR 中如实记录，不通过放宽规则或跳过检查掩盖。
Playwright 入口通过 Node 设置测试环境变量，辅助测试额外启用 `react-server` 模块条件，
可在 Windows 和 Linux 上使用同一条命令。
构建后的公共 source map 清理由 Node 完成，只处理工作区内当前构建目录的 `static` 文件。
原生 Agent 沙箱测试另外需要对应的运行时和隔离环境，应单独记录是否具备这些条件。

仓库工作流目前均为手动触发。若以后增加自动发布，须明确发布分支、目标环境、
审批和回滚方式，避免普通推送意外触发生产变更。

本次归档保留现有生产行为，历史质量问题和未执行的验收项目在合并 PR 中单独列明。