---
title: 关键技术决策记录
type: curated
permalink: main/projects/d44c219a-0b31-4de1-b160-323eb34a4c6a/curated/关键技术决策记录
stable_id: dc8f8ea1-5790-4480-a7dc-490e45bc506f
scope: project
project_id: d44c219a-0b31-4de1-b160-323eb34a4c6a
workspace_type: development
usage_profile_id: null
preference_context: development
document_type: decisions
revision: 1
source_memory_ids:
- 2939ce96-a6f6-418a-9a70-568980dbdc2a
- 2fafa191-d208-41e4-9f7b-ce5a633c886b
- 3efd0adf-f91b-4d78-b163-5365c257d6d4
- 46eb1720-910a-4e4e-b56b-b6ac43b0cec1
- 67a86e88-a750-4cd8-9650-c1b7cfbf22b9
- 6b129c78-a412-41e9-af9f-63ab071e03d9
- 76e12a12-446a-4d96-bb49-2534930a5d56
- 7737eaaf-441e-476e-aea0-42a4d13ae245
- 7e83a02d-9eb6-4e97-9f23-102f34ae8b1e
- 92e5c8d9-c4ef-4ab7-99ac-1b81f3228b59
- a9739d28-4318-492e-bad3-53e9ea2769a8
- ada12b65-afa2-415e-98b3-2a24ff57feb9
- ae318134-8651-4563-bc22-491c51f87af4
- b7e0eb44-e38f-40a3-8736-3a7a9de84818
- beb81aaa-8e86-4af7-a6c8-d35f7682d330
- d5bb7f58-99bb-4381-ac98-300cceb128fe
- dc70f54c-8e29-4834-a5c1-a63bc9ac9e68
- dcdbeb7d-dd75-4294-8853-872491043db1
- dd093dd7-71be-46a2-bcb1-4a87c3d4b9ab
- dd22c710-2822-4515-a28c-ead99162caac
- e1b8d25d-f638-4fbe-8a8d-0eda8f2d7d46
source_checkpoint_ids:
- 4f5c2b7f-d115-46c2-87be-80c8605ccbdb
- d45ff9ab-e2f4-4de8-8ccb-389754c1e3a4
source_file_ids:
- 07583531-4b5a-4826-ad88-be4c3f16ba9d
- 2749e8f9-a45f-43b0-a818-143ae532db24
- 2977cf7c-7494-4b28-a8c6-2fbc6261c810
- 4e728912-7bd0-455c-ac3a-e35189c26e37
- 8f5b3f27-3ed1-4bf1-97ef-cb130f238161
source_git_commit: d7c6368
source_git_commits:
- d7c6368
source_agent_sync_ids:
- artveris-curation-2026-09-03-migration
model_connection: Sub2API
model_name: git-restore
source_count: 42
source_revisions:
  memory:ae318134-8651-4563-bc22-491c51f87af4: '1'
  memory:dd22c710-2822-4515-a28c-ead99162caac: '1'
  memory:a9739d28-4318-492e-bad3-53e9ea2769a8: '1'
  memory:dc70f54c-8e29-4834-a5c1-a63bc9ac9e68: '1'
  memory:e1b8d25d-f638-4fbe-8a8d-0eda8f2d7d46: '1'
  memory:6b129c78-a412-41e9-af9f-63ab071e03d9: '1'
source_dispositions:
  processed: 42
  unchanged: 0
  unsupported: 0
  skipped: 0
cited_source_ids:
- memory:ae318134-8651-4563-bc22-491c51f87af4
- memory:dd22c710-2822-4515-a28c-ead99162caac
- memory:a9739d28-4318-492e-bad3-53e9ea2769a8
- memory:dc70f54c-8e29-4834-a5c1-a63bc9ac9e68
- memory:e1b8d25d-f638-4fbe-8a8d-0eda8f2d7d46
- memory:6b129c78-a412-41e9-af9f-63ab071e03d9
job_cited_source_ids:
- memory:ae318134-8651-4563-bc22-491c51f87af4
- memory:dd22c710-2822-4515-a28c-ead99162caac
- memory:a9739d28-4318-492e-bad3-53e9ea2769a8
- memory:dc70f54c-8e29-4834-a5c1-a63bc9ac9e68
- memory:e1b8d25d-f638-4fbe-8a8d-0eda8f2d7d46
- memory:6b129c78-a412-41e9-af9f-63ab071e03d9
conflicts: []
supersedes: []
preferences: []
source_cursor: 359
source_hash: 06340ad0d2d916308bcf502ff22c22461eeb2afaaeea56df8687dae4fdb0f11d
prompt_version: 2026-08-12.3
schema_version: '3'
curation_job_id: null
created_at: '2026-09-03T04:21:16.235463+00:00'
updated_at: '2026-09-23T15:07:04.465178+00:00'
tags:
- 决策
- 技术选型
- 链上范围
- 规范
restored_from_commit: 6a6a895eafcca6052e81a14fca103a42635dd1c2
---

### 1. 技术选型决策 (memory:ae318134-8651-4563-bc22-491c51f87af4)
- **UserKey** 明文保存，便于系统迁移后恢复；**AppKey** 加密存储。
- 全局唯一 `.env` 配置文件，取代旧 `config/` JSON。
- 安装向导合并至 admin 模块，取消独立 `apps/install`。
- 核心部署采用单节点 Node 服务 + 可选 Docker/SSH，避免多容器复杂性。
- 采用动态追踪代码链接、无状态 TOTP 预览令牌、防篡改模块布局、Photo‑Swipe v5 UI。
- 明确 **不构建** NFC、多组织隔离、主动告警、C‑端 skeleton screens、IP/UA 区域解析等功能。

### 2. 天河链接入范围决策 (memory:dd22c710-2822-4515-a28c-ead99162caac)
- **仅上传 + 发布** 链上流程（无二次转移、烧毁）。
- 链上不存放媒体或摘要，所有媒体均离线存储。
- 统一使用单一平台钱包 `artveris-platform`。
- 计费方式基于 API 调用次数，删除功能不支持。
- C 端展示仅提供区块浏览器交易详情链接，无 on‑chain 销售状态标记。

### 3. 出库/上链不变量与审计约束 (memory:a9739d28-4318-492e-bad3-53e9ea2769a8)
1. 链上记录与出库记录 **解耦**。
2. 每个追溯码最多拥有一条 `OutboundRecord`（时间必填，可修改）。
3. 单次批量发布最多 **5 000** `productId`，按艺术品分组。
4. 已存在的码若状态为 `FAILED` 方可重复 mint。
5. `UNKNOWN` 状态必须保留原始参数，仅管理员可强制重试。
6. 审计流：修订创建快照，只有批准的修订才替换线上数据；超级管理员操作自动批准。

### 4. 数据持久化红线 (memory:dc70f54c-8e29-4834-a5c1-a63bc9ac9e68)
- 升级过程 **禁止** 覆盖 `.env`、`storage/`、`backups/`、数据库。
- Prisma 基线迁移 `20260715000000_init`，全局 `trace_code_sequence.next_seq` 不可回滚，最高 999 999。
- 禁止删除存活的 trace code、ONCHAIN/UNKNOWN 状态码。
- 媒体仅通过键存储，不允许 SVG。
- 短码 URL 动态生成 `{{clientBaseUrl}}/#/trace/{{shortCode}}`。

### 5. 构建与本地开发硬约束 (memory:e1b8d25d-f638-4fbe-8a8d-0eda8f2d7d46)
- PNPM 10.28.0、Node ≥20.11.1（推荐 24 LTS）。
- 使用 `scripts/dev.py` 进行本地环境搭建，若缺少 `.env` 自动进入安装向导。
- 在运行 `nest build` 或升级脚本前必须 **停止** 开发 API。
- Windows PowerShell 中 `&&` 不被支持，需要分行或使用 `;`。
- 严禁提交 Secrets，`.env`、`docs/系统测试信息.md`、`.deploy/` 必须在 `.gitignore` 中。

### 6. 开发与提交规范 (memory:6b129c78-a412-41e9-af9f-63ab071e03d9)
- 使用中文进行所有交流和提交信息。
- 开发环境统一为 Windows + PowerShell + WSL2。
- 采用 YAGNI/KISS 原则，复用已有框架。
- 提交顺序：**清理 → 记忆更新 → 文档 → .gitignore → commit**。
- Commit message 格式 `type: 中文描述`（type 如 feat、fix、refactor 等）。
- 分支策略：`main`（生产） 与 `dev`（长期开发），两者均同步至 Gitea 与 GitHub。
- 许可证采用 PolyForm Strict 1.0.0。