docs: import wiki at afc651f75a3a

T-229.-.md

@@ -0,0 +1,67 @@
+<!-- docs-wiki-sync:docs/tasks/T-229.md@afc651f75a3abc2676bb13aa8a80f6aa6a25a72e -->
+> 同步来源：[`docs/tasks/T-229.md`](/chengma/mroubao/src/commit/afc651f75a3abc2676bb13aa8a80f6aa6a25a72e/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`，文档明确文件权限、启动位置和环境覆盖顺序。
+
+## 验收要点
+
+- [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。