From d75a7d8dc0efef5413af6b75aea8a40492a72aa5 Mon Sep 17 00:00:00 2001
From: QiuSW <105186638@qq.com>
Date: Wed, 29 Jul 2026 10:18:25 +0800
Subject: [PATCH] docs(t229): plan ERP dotenv configuration

---
 docs/current-state.md |  7 ++---
 docs/tasks/T-229.md   | 60 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 64 insertions(+), 3 deletions(-)
 create mode 100644 docs/tasks/T-229.md

diff --git a/docs/current-state.md b/docs/current-state.md
index 5254e6d..06cb4f7 100644
--- a/docs/current-state.md
+++ b/docs/current-state.md
@@ -5,7 +5,7 @@
 ## 当前快照
 
 - 日期：2026-07-29
-- 阶段：T-228 已完成单 Go 后端 ERP 切换；等待真实凭证下的人工验证码登录 smoke
+- 阶段：T-229 待增加受控 `backend-api/.env` ERP 凭证加载；随后进行人工验证码登录 smoke
 - Git：当前分支为 `main`；T-001 至 T-004、T-101 至 T-104、T-201 至 T-219
   均按文档提交、实现提交的顺序纳入历史
 - 生产代码：`android-buyer/` 已接入 Roubao Android 源码
@@ -197,8 +197,9 @@
 - 已完成：另含 T-220 至 T-228 ERP 契约、货运存储、采购需求生成、日期增量同步、Go
   直连协议、人工验证码会话、直连 `FreightSource` 和旧 Connector 清理。
 - 进行中：无。
-- 下一步：真实 ERP 上线前确认开放 API、数据使用权限，并由人员在 `/erp` 完成验证码
-  登录后以受控单号执行一次不记录订单内容的 smoke。
+- 下一步：T-229 让本地单机从受控 `backend-api/.env` 读取 ERP 凭证；随后确认开放 API、
+  数据使用权限，并由人员在 `/erp` 完成验证码登录后以受控单号执行一次不记录订单内容的
+  smoke。
 
 ## 当前可运行内容
 
diff --git a/docs/tasks/T-229.md b/docs/tasks/T-229.md
new file mode 100644
index 0000000..086a8db
--- /dev/null
+++ b/docs/tasks/T-229.md
@@ -0,0 +1,60 @@
+---
+id: T-229
+title: 从受控 .env 加载 ERP 凭证
+phase: 2
+deps:
+  - T-228
+status: TODO
+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/.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：创建任务，等待文档提交后实现。