alien_py_cloud/alien_3rd_esign

Alien 3rd Esign 模块开发文档

概览

基于 FastAPI 的电子签约子模块，负责店铺合同签约相关的接口、服务与数据访问。当前实现为骨架，需在此基础上补充业务逻辑。

目录结构

alien_3rd_esign/
├── main.py                    # 应用入口，挂载路由与健康检查
├── api/
│   ├── router.py              # 路由分组，当前仅根路径
│   └── deps.py                # 依赖注入，提供 ContractServer
├── db/
│   └── models/
│       └── contract_store.py  # 店铺合同表模型
├── repositories/
│   └── contract_repo.py       # 合同仓储（待实现）
├── services/
│   └── contract_server.py     # 合同服务层（待实现）
├── schemas/
│   ├── request/               # 请求 Pydantic 模型（待补充）
│   └── response/              # 响应 Pydantic 模型（待补充）
└── __init__.py

运行与环境

• 依赖外部配置 alien_gateway.config.settings，至少包含 PROJECT_NAME，以及数据库配置（见上游网关项目）。
• 数据库会话来自 alien_database.session.get_db，确保上游已配置 SQLAlchemy Engine/Session。

• 安装依赖后本地运行示例：

  uvicorn alien_3rd_esign.main:app --host 0.0.0.0 --port 8006 --reload
  

现有 API

• GET /api/esign/：模块存活确认，返回 {"module": "Contract", "status": "Ok"}。
• GET /health：健康检查，返回 {"service": "sign", "status": "ok"}。

数据模型

• ContractStore（表名 contract_store）
  • store_id (BigInteger, PK) 店铺 ID
  • business_segment (String) 经营板块
  • merchant_name (String) 商家姓名
  • contact_phone (String) 联系电话
  • signing_status (String, 默认“未签署”) 状态：已签署/未签署/已到期
  • signing_time (DateTime, 可空) 签署时间
  • effective_time (DateTime, 可空) 生效时间
  • expiry_time (DateTime, 可空) 到期时间
  • 继承 AuditMixin，包含审计字段（创建/更新人、时间等，具体见 alien_database.base）。

开发指引

• 路由层：在 api/router.py 按资源划分路由，通过 Depends(get_contract_service) 注入服务。
• 服务层：在 services/contract_server.py 编写业务逻辑（状态流转、有效期计算、外部电子签平台集成、权限校验）。
• 仓储层：在 repositories/contract_repo.py 实现对 ContractStore 的 CRUD、列表分页、状态更新等。
• Schema：在 schemas/request/ 与 schemas/response/ 定义 Pydantic 模型，约束字段、枚举和值域。
• 异常与校验：使用 FastAPI/HTTPException 统一错误响应；对输入做类型与业务校验。
• 测试：为服务和仓储编写单元/集成测试，可使用 SQLite 内存库或测试数据库。

后续待办（建议）

• 补充合同创建、查询、签署、续签、到期提醒等接口。
• 定义请求/响应 schema 与枚举，完善文档化（可结合 FastAPI OpenAPI/Swagger）。
• 增加仓储实现与事务管理，补齐状态机校验。
• 编写自动化测试与示例请求（如 HTTPie/Thunder Client 集合）。