cmroubao/docs/tasks/T-229.md

id, title, phase, deps, status, created, context_ref, work_branch, write_paths

id	title	phase	deps	status	created	context_ref	work_branch	write_paths
T-229	从受控 .env 加载 ERP 凭证	2	T-228	TODO	2026-07-29	13a1355	null	docs/tasks/T-229.md docs/api.md docs/current-state.md docs/05-coding-rules.md 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，文档明确文件权限、启动位置和环境覆盖顺序。

验收要点

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

边界

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

执行记录

• 2026-07-29：创建任务，等待文档提交后实现。