---
id: T-229
title: 从受控 .env 加载 ERP 凭证
phase: 2
deps:
  - T-228
status: DONE
created: 2026-07-29
context_ref: 13a1355
work_branch: null
write_paths:
  - docs/tasks/T-229.md
  - docs/api.md
  - docs/current-state.md
  - docs/05-coding-rules.md
  - backend-api/.gitignore
  - backend-api/.env.example
  - backend-api/README.md
  - backend-api/SCAFFOLD.md
  - backend-api/cmd/api/**
  - backend-api/internal/config/**
---

## 问题 / 背景

T-226 至 T-228 要求 ERP 账号和密码只在后端进程内使用，但当前只能通过启动父进程环境
注入，Windows 本地启动不便。需要为单机验证增加受控的 `backend-api/.env` 读取，同时
不能退回到把凭证写入批处理、SQLite、浏览器、日志或 Git 的做法。

## 关联需求与交互

- 功能：F-011、F-012。
- 用户故事：US-011、US-012。
- 交互：IX-012；ADMIN 仍只在 `/erp` 输入人工验证码，不输入 ERP 账号或密码。
- 架构：API 进程在读取配置前解析本地 `.env`，只作为进程环境变量的回退来源。

## 方案

1. 默认只读取 API 当前工作目录中的 `.env`，即标准启动路径的 `backend-api/.env`；文件
   缺失时保持未配置状态，不阻断其他后端功能。
2. 只允许 `.env` 为顺运宝 URL、用户名和密码提供值；进程环境变量优先，`.env` 不修改
   全局进程环境，不支持变量展开、命令替换或 shell 执行。
3. 限制文件/行大小、拒绝重复键、非法键、NUL 和无效引号；错误不回显值或文件内容。
4. 提供被忽略的 `.env` 对应的 `.env.example`，文档明确文件权限、启动位置和环境覆盖顺序。

## 验收要点

- [x] API 从 `backend-api/.env` 读取完整 ERP 凭证；系统环境变量覆盖同名 `.env` 值。
- [x] 文件缺失、格式错误、重复键、未知受控键和敏感值均有测试；错误和日志不泄露密码。
- [x] `.env` 始终被 Git 忽略，`.env.example` 不含真实凭证；Admin 页面仍没有账号/密码字段。
- [x] `go test ./...`、`go test -race ./...`、`go vet ./...` 和 API 构建通过。

## 边界

- 不让 `authctl` 密码、数据库路径、HTTP 监听或 TLS 私钥通过此 ERP `.env` 机制加载。
- 不实现 Web 编辑、自动登录、OCR、加密持久化 ERP 会话或多账号。
- 不读取工作区根目录、用户目录或任意指定路径的 `.env`。

## 执行记录

- 2026-07-29：创建任务并以提交 `d75a7d8` 固定范围。
- 2026-07-29：实现仅限 `cmd/api` 的受控 `.env` 回退；新增 parser/优先级/敏感错误和 API
  入口测试。验证：`GOTOOLCHAIN=local go test ./...`、`go test -race ./...`、`go vet ./...`
  及三个 Go 入口构建通过；未访问真实 ERP。