140 lines
6.1 KiB
Markdown
140 lines
6.1 KiB
Markdown
---
|
||
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。 |