chisup/docs/03-tech-stack.md

技术栈（Tech Stack）

“用什么”的统一速查表。未定项必须标为待定，不让 agent 在代码里自行决定。

一、技术栈一览

维度	选型	状态	理由 / 说明
运行时	当前系统 Python 3.8	已定	用户指定，不创建虚拟环境
Web 框架	Flask 3.0.3 + application factory	已定	用户指定 Flask 版本；factory 模式便于配置注入和测试
数据校验	待定，建议 Pydantic v1 或 Marshmallow	待定	Python 3.8 下需注意版本兼容
HTTP 客户端	requests[socks] 2.32.4	已定	CHIS 会话 cookie 管理简单稳定；CHIS_PROXY 有值时走 SOCKS5 代理
Redis 客户端	待定，建议 redis-py	待定	保存 CHIS 会话、幂等和短期状态
SM2 加密	gmssl 3.2.2	已定	兼容 hans_chis.sm2.sm2_encrypt 的 CryptSM2(mode=0) 行为
日志	Python logging + TimedRotatingFileHandler	已定	logs/ 每天一个综合日志文件，保留 1 年
请求归档	本地 JSON 文件	已定	archives/ 每个接口请求一个完整归档文件，部署在内网前置机，不脱敏
数据库	待定	待定	MVP 可先只用 Redis；上报流水可能需要 MySQL / SQLite / PostgreSQL
第三方鉴权	待定，建议 app_key + HMAC 或 Bearer Token	待定	不建议第三方直接裸传 CHIS 账号密码
测试	pytest 8.3.5	已定	兼容当前系统 Python 3.8；适合 mapper、client、service 单元测试
部署	待定，建议 gunicorn / waitress + systemd / Windows 服务	待定	取决于部署环境

二、决策记录与演进

• Flask 3.0.3 + Python 3.8 已定，但 Python 3.8 生命周期已结束；如果部署环境允许，未来建议评估 Python 3.10+。
• 本项目使用当前系统 Python 3.8 环境，不创建虚拟环境；依赖仍必须写入 requirements.txt 并固定关键版本。
• Flask 应用必须使用 application factory 模式，即 app/__init__.py 暴露 create_app(config_object=None)；不要在模块导入时创建并配置全局业务 app。
• Redis 是会话缓存核心，不建议把 CHIS 会话保存在进程内存。
• 运行日志保存到 logs/，每天一个综合日志文件，包含 INFO/WARNING/ERROR/EXCEPTION 等级摘要，保留 1 年。
• 接口请求归档保存到 archives/，一个 API 请求一个 JSON archive 文件，文件内容保存完整 API 与 CHIS 请求 / 响应，不脱敏；该目录仅用于内网前置机本地审计排查，不提交 git。
• CHIS public key 从配置文件或环境变量读取；当前不依赖 /chis/logon/publicKey 动态获取。
• CHIS_BASE_URL 支持完整地址如 http://host:port/chis，也兼容旧项目的 host 写法如 host:port，代码会补齐为 http://host:port/chis。
• CHIS 外呼请求支持可选代理：CHIS_PROXY 为空时直连；有值时只作用于访问 CHIS 的 HTTP client，不影响第三方调用 chisup 的入站请求。
• CHIS_PROXY 推荐格式为 socks5h://127.0.0.1:1080；requests[socks]==2.32.4 已固定到依赖，保证 SOCKS5 可用。
• CHIS 登录代码来自 Django 项目参考实现，迁移到 Flask 时只复用登录链路、SM2 算法和请求形状，不复用 Django model/cache；当前登录实现位于 app/chis/auth.py，SM2 实现位于 app/chis/crypto.py。
• 当前不引入异步队列，先跑通同步单条上报闭环；批量和重试队列放到 V2。
• 当前不引入管理后台，先保证 API、会话和转换稳定。

三、构建与运行命令

当前可用命令：

用途	命令
安装依赖	python -m pip install -r requirements.txt
本地开发	python run.py
测试	python -m pytest
格式化 / 静态检查	待定

可选文档检查：

Get-ChildItem -Recurse -File          # PowerShell
# bash 等价: find . -type f -not -path './.git/*'

四、依赖纪律

• 新增依赖前先说明用途、替代方案和 Python 3.8 兼容性。
• 不创建 .venv、venv 或其他项目虚拟环境目录；如需隔离，必须先更新本文并取得确认。
• 和 CHIS 登录、SM2/RSA/AES 加密相关的依赖必须由真实登录代码驱动，不要凭 HAR 猜；当前 SM2 参考 hans_chis.sm2.sm2_encrypt。
• CHIS HTTP 代理只从 CHIS_PROXY 读取；测试和文档示例不得写真实代理地址、账号或密码。
• 不允许在代码或 .env.example 中写真实 CHIS 地址、账号、密码、Cookie。
• logs/ 和 archives/ 必须加入 .gitignore；archive 文件包含敏感原始数据，不得进入代码仓库或测试快照。