1

T-229

ila edited this page 2026-08-07 16:36:43 +08:00

Table of Contents

• 问题 / 背景
• 关联需求与交互
• 方案
• 验收要点
• 边界
• 执行记录

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

同步来源：docs/tasks/T-229.md · commit afc651f75a3a

---

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，文档明确文件权限、启动位置和环境覆盖顺序。

验收要点

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